[Diffusion] Simplify DLO host plan setup

Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>
[Diffusion] Prefer host-cache registration when pinned
2026-08-19 23:00:31 +08:00 · 2026-08-19 18:13:44 +08:00 · 2026-08-19 11:23:36 +08:00 · 2026-08-19 11:23:36 +08:00 · 2026-08-19 11:23:36 +08:00 · 2026-08-19 11:23:36 +08:00
631 changed files with 26060 additions and 41612 deletions
@@ -17,7 +17,7 @@ steps:
        - export VLLM_ROCM_USE_AITER=0
        # ignore test_teacache_extractors.py because it use rocm gemm kernel from vLLM
        # that is not supported on CPU
-        - "pytest -sv tests/model_executor -m 'core_model and cpu' --num-shards=$$BUILDKITE_PARALLEL_JOB_COUNT --shard-id=$$BUILDKITE_PARALLEL_JOB"
+        - "pytest -sv tests/model_executor -m 'core_model and cpu' --num-shards=$$BUILDKITE_PARALLEL_JOB_COUNT --shard-id=$$BUILDKITE_PARALLEL_JOB --cov=vllm_omni --cov-report=term-missing:skip-covered --cov-report=xml:coverage-model-executor-$$BUILDKITE_PARALLEL_JOB.xml"

    - label: "Simple · Diffusion Test · Shard %N/%t"
      agent_pool: mi300_1
@@ -29,7 +29,7 @@ steps:
        - export VLLM_ROCM_USE_AITER=0
        # ignore test_teacache_extractors.py because it use rocm gemm kernel from vLLM
        # that is not supported on CPU
-        - "pytest -sv tests/diffusion -m 'core_model and cpu' --ignore=tests/diffusion/cache/test_teacache_extractors.py --num-shards=$$BUILDKITE_PARALLEL_JOB_COUNT --shard-id=$$BUILDKITE_PARALLEL_JOB"
+        - "pytest -sv tests/diffusion -m 'core_model and cpu' --ignore=tests/diffusion/cache/test_teacache_extractors.py --num-shards=$$BUILDKITE_PARALLEL_JOB_COUNT --shard-id=$$BUILDKITE_PARALLEL_JOB --cov=vllm_omni --cov-report=term-missing:skip-covered --cov-report=xml:coverage-diffusion-$$BUILDKITE_PARALLEL_JOB.xml"

    - label: "Simple · Engine&Entrypoints Test"
      agent_pool: mi300_1
@@ -38,7 +38,7 @@ steps:
      grade: Blocking
      commands:
        - export VLLM_ROCM_USE_AITER=0
-        - "pytest -sv tests/entrypoints tests/engine -m 'core_model and cpu'"
+        - "pytest -sv tests/entrypoints tests/engine -m 'core_model and cpu' --cov=vllm_omni --cov-report=term-missing:skip-covered --cov-report=xml"

    - label: "Simple · Other Test"
      agent_pool: mi300_1
@@ -49,7 +49,7 @@ steps:
        - export VLLM_ROCM_USE_AITER=0
        # ignore test_teacache_extractors.py because it use rocm gemm kernel from vLLM
        # that is not supported on CPU
-        - "pytest -sv tests/ -m 'core_model and cpu' --ignore=tests/diffusion --ignore=tests/model_executor --ignore=tests/entrypoints --ignore=tests/engine  --ignore=tests/diffusion/cache/test_teacache_extractors.py"
+        - "pytest -sv tests/ -m 'core_model and cpu' --ignore=tests/diffusion --ignore=tests/model_executor --ignore=tests/entrypoints --ignore=tests/engine  --ignore=tests/diffusion/cache/test_teacache_extractors.py --cov=vllm_omni --cov-report=term-missing:skip-covered --cov-report=xml"

 - group: ":card_index_dividers: Diffusion Test"
  steps:
@@ -17,7 +17,7 @@ steps:
        - export VLLM_ROCM_USE_AITER=0
        # ignore test_teacache_extractors.py because it use rocm gemm kernel from vLLM
        # that is not supported on CPU
-        - "pytest -sv tests/model_executor -m 'core_model and cpu' --num-shards=$$BUILDKITE_PARALLEL_JOB_COUNT --shard-id=$$BUILDKITE_PARALLEL_JOB"
+        - "pytest -sv tests/model_executor -m 'core_model and cpu' --num-shards=$$BUILDKITE_PARALLEL_JOB_COUNT --shard-id=$$BUILDKITE_PARALLEL_JOB --cov=vllm_omni --cov-report=term-missing:skip-covered --cov-report=xml:coverage-model-executor-$$BUILDKITE_PARALLEL_JOB.xml"

    - label: "Simple · Diffusion Test"
      agent_pool: mi300_1
@@ -28,7 +28,7 @@ steps:
        - export VLLM_ROCM_USE_AITER=0
        # ignore test_teacache_extractors.py because it use rocm gemm kernel from vLLM
        # that is not supported on CPU
-        - "pytest -sv tests/diffusion -m 'core_model and cpu'  --ignore=tests/diffusion/cache/test_teacache_extractors.py"
+        - "pytest -sv tests/diffusion -m 'core_model and cpu'  --ignore=tests/diffusion/cache/test_teacache_extractors.py --cov=vllm_omni --cov-report=term-missing:skip-covered --cov-report=xml"

    - label: "Simple · Engine&Entrypoints Test"
      agent_pool: mi300_1
@@ -37,7 +37,7 @@ steps:
      grade: Blocking
      commands:
        - export VLLM_ROCM_USE_AITER=0
-        - "pytest -sv tests/entrypoints tests/engine -m 'core_model and cpu'"
+        - "pytest -sv tests/entrypoints tests/engine -m 'core_model and cpu' --cov=vllm_omni --cov-report=term-missing:skip-covered --cov-report=xml"

    - label: "Simple · Other Test"
      agent_pool: mi300_1
@@ -48,7 +48,7 @@ steps:
        - export VLLM_ROCM_USE_AITER=0
        # ignore test_teacache_extractors.py because it use rocm gemm kernel from vLLM
        # that is not supported on CPU
-        - "pytest -sv tests/ -m 'core_model and cpu' --ignore=tests/diffusion --ignore=tests/model_executor --ignore=tests/entrypoints --ignore=tests/engine  --ignore=tests/diffusion/cache/test_teacache_extractors.py"
+        - "pytest -sv tests/ -m 'core_model and cpu' --ignore=tests/diffusion --ignore=tests/model_executor --ignore=tests/entrypoints --ignore=tests/engine  --ignore=tests/diffusion/cache/test_teacache_extractors.py --cov=vllm_omni --cov-report=term-missing:skip-covered --cov-report=xml"

 - label: "Custom Pipeline Test"
  agent_pool: mi300_1
@@ -16,11 +16,6 @@
 # At least one of --offline/--online is required, so a job with only one mode runs
 # just that half. Total runtime is bounded by the step's timeout_in_minutes.
 #
-# Coverage + artifact upload run only on scheduled weekly E2E sweeps
-# (WEEKLY=1 and BUILDKITE_BRANCH=main — same gate as bootstrap --e2e).
-# All other invocations (PR merge-test, regular main merge, local) run the
-# same combined pytest as the job used before coverage was added.
-#
 # Exits non-zero if any half or the upload failed.
 set -uo pipefail

@@ -49,17 +44,6 @@ if ((${#OFFLINE[@]} == 0 && ${#ONLINE[@]} == 0)); then
    exit 2
 fi

-_should_run_coverage() {
-    [[ "${WEEKLY:-}" == "1" && "${BUILDKITE_BRANCH:-}" == "main" ]]
-}
-
-if ! _should_run_coverage; then
-    PATHS=("${OFFLINE[@]}" "${ONLINE[@]}")
-    echo "--- pytest (no coverage): ${MODEL_ID}"
-    pytest -s -v "${PATHS[@]}" "${PYTEST_ARGS[@]}"
-    exit $?
-fi
-
 # Two steps can test the same model, and artifacts are scoped to the build (a
 # nightly one carries the ready, merge and nightly tiers at once), so unsuffixed
 # reports would share a path -- a glob download then races to rename onto one file.
@@ -1,6 +1,5 @@
 #!/usr/bin/env python3
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Render and optionally upload Buildkite pipeline YAML with diff-aware logic.

 Bootstrap mode (``bootstrap-upload-steps.yml``):
@@ -59,12 +58,11 @@ BOOTSTRAP_UPLOAD_IF_KEYS = {
 E2E_GROUP_MARKER = "E2E Test"
 CI_MIRROR_HARDWARES_PATH = ROOT / ".buildkite/common/ci_mirror_hardwares.yml"

-# Bootstrap Buildkite ``if`` expressions.
-# ``*_MAIN_IF``: main + env schedule. ``*_LABEL_IF``: PR label (and/or composed with MAIN).
-# ``*_UPLOAD_IF``: full gate for uploading that child pipeline.
-NIGHTLY_MAIN_IF = 'build.branch == "main" && build.env("NIGHTLY") == "1"'
-NIGHTLY_LABEL_IF = (
-    f"({NIGHTLY_MAIN_IF}) || "
+CUDA_NIGHTLY_ONLY = (
+    '(build.pull_request.labels includes "nightly-test") || (build.branch == "main" && build.env("NIGHTLY") == "1")'
+)
+NPU_NIGHTLY_ONLY = (
+    '(build.branch == "main" && build.env("NIGHTLY") == "1") || '
    '(build.branch != "main" && ('
    'build.pull_request.labels includes "nightly-test" || '
    'build.pull_request.labels includes "omni-test" || '
@@ -73,19 +71,6 @@ NIGHTLY_LABEL_IF = (
    'build.pull_request.labels includes "diffusion-x2v-test"'
    "))"
 )
-WEEKLY_E2E_IF = 'build.branch == "main" && build.env("WEEKLY") == "1"'
-WEEKLY_MAIN_IF = 'build.branch == "main" && (build.env("WEEKLY") == "1" || build.env("NON_CRITICAL") == "1")'
-WEEKLY_LABEL_IF = f'({WEEKLY_MAIN_IF}) || (build.branch != "main" && build.pull_request.labels includes "weekly-test")'
-READY_LABEL_IF = 'build.branch != "main" && build.pull_request.labels includes "ready"'
-MERGE_LABEL_IF = 'build.branch != "main" && build.pull_request.labels includes "merge-test"'
-MERGE_MAIN_IF = (
-    'build.branch == "main" && build.env("NIGHTLY") != "1" && '
-    'build.env("WEEKLY") != "1" && build.env("NON_CRITICAL") != "1"'
-)
-READY_UPLOAD_IF = f"({WEEKLY_E2E_IF}) || ({READY_LABEL_IF})"
-MERGE_UPLOAD_IF = f"({WEEKLY_E2E_IF}) || (({MERGE_MAIN_IF}) || ({MERGE_LABEL_IF}))"
-BOOTSTRAP_DISABLED_IF = "false"
-BOOTSTRAP_ENABLED_IF = "true"


 # --- Logging ---
@@ -117,47 +102,74 @@ def _format_bootstrap_if(expr: str) -> str:


 def _compute_bootstrap_if_exprs(*, decision, platform: str) -> dict[str, str]:
+    disabled = "false"
+    nightly_main = 'build.branch == "main" && build.env("NIGHTLY") == "1"'
+    nightly_only = NPU_NIGHTLY_ONLY if platform == "npu" else CUDA_NIGHTLY_ONLY
+
    if platform == "npu":
-        ready_upload = READY_LABEL_IF
-        merge_upload = BOOTSTRAP_DISABLED_IF
-        weekly_label_if = BOOTSTRAP_DISABLED_IF
+        ready_pr = (
+            'build.branch != "main" && ('
+            'build.pull_request.labels includes "npu-test" || '
+            'build.pull_request.labels includes "ready"'
+            ")"
+        )
+        nightly_label_if = nightly_only
+        weekly_label_if = disabled
+        merge_base = disabled
    else:
-        ready_upload = READY_UPLOAD_IF
-        merge_upload = MERGE_UPLOAD_IF
-        weekly_label_if = WEEKLY_LABEL_IF
+        ready_pr = 'build.branch != "main" && build.pull_request.labels includes "ready"'
+        merge_main = 'build.branch == "main" && build.env("NIGHTLY") != "1" && build.env("WEEKLY") != "1"'
+        merge_pr = 'build.branch != "main" && build.pull_request.labels includes "merge-test"'
+        nightly_label_if = (
+            '(build.branch == "main" && build.env("NIGHTLY") == "1") || '
+            '(build.branch != "main" && ('
+            'build.pull_request.labels includes "nightly-test" || '
+            'build.pull_request.labels includes "omni-test" || '
+            'build.pull_request.labels includes "tts-test" || '
+            'build.pull_request.labels includes "diffusion-x2iat-test" || '
+            'build.pull_request.labels includes "diffusion-x2v-test"'
+            "))"
+        )
+        weekly_label_if = (
+            '(build.branch == "main" && build.env("WEEKLY") == "1") || '
+            '(build.branch != "main" && build.pull_request.labels includes "weekly-test")'
+        )
+        merge_base = f"({nightly_main}) || (({merge_main}) || ({merge_pr}))"
+
+    ready_base = f"({nightly_main}) || ({ready_pr})"
+    weekly_main = 'build.branch == "main" && build.env("WEEKLY") == "1"'

    if decision.skip_all:
        # Docs / skip-mark only: no PR-label escape hatch. Main scheduled
-        # NIGHTLY=1 still runs L4; WEEKLY=1 / NON_CRITICAL=1 still run L5.
-        # main+WEEKLY=1 also uploads L2/L3 (those steps then pass --e2e).
-        image_expr = f"({NIGHTLY_MAIN_IF}) || ({WEEKLY_MAIN_IF})" if platform == "cuda" else NIGHTLY_MAIN_IF
-        ready_expr = WEEKLY_E2E_IF if platform == "cuda" else BOOTSTRAP_DISABLED_IF
-        merge_expr = WEEKLY_E2E_IF if platform == "cuda" else BOOTSTRAP_DISABLED_IF
-        nightly_expr = NIGHTLY_MAIN_IF
-        weekly_expr = WEEKLY_MAIN_IF if platform == "cuda" else BOOTSTRAP_DISABLED_IF
+        # NIGHTLY=1 still runs L4 + L2/L3 (--e2e); WEEKLY=1 still runs L5.
+        image_expr = f"({nightly_main}) || ({weekly_main})" if platform == "cuda" else nightly_main
+        ready_expr = nightly_main
+        merge_expr = nightly_main if platform == "cuda" else disabled
+        nightly_expr = nightly_main
+        weekly_expr = weekly_main if platform == "cuda" else disabled
    elif decision.skip_l2_l3:
        l2_enabled = decision.is_run("npu", "l2") if platform == "npu" else decision.is_run("cuda", "l2")
        l3_enabled = platform == "cuda" and decision.is_run("cuda", "l3")

-        ready_expr = ready_upload if l2_enabled else BOOTSTRAP_DISABLED_IF
-        merge_expr = merge_upload if l3_enabled else BOOTSTRAP_DISABLED_IF
-        nightly_expr = NIGHTLY_LABEL_IF
-        weekly_expr = weekly_label_if if platform == "cuda" else BOOTSTRAP_DISABLED_IF
+        ready_expr = ready_base if l2_enabled else disabled
+        merge_expr = merge_base if l3_enabled else disabled
+        nightly_expr = nightly_label_if
+        weekly_expr = weekly_label_if if platform == "cuda" else disabled

-        image_parts = [f"({NIGHTLY_LABEL_IF})"]
+        image_parts = [f"({nightly_label_if})"]
        if platform == "cuda":
            image_parts.append(f"({weekly_label_if})")
        if l2_enabled:
-            image_parts.insert(0, f"({ready_upload})")
+            image_parts.insert(0, f"({ready_base})")
        if l3_enabled:
-            image_parts.insert(1 if l2_enabled else 0, f"({merge_upload})")
+            image_parts.insert(1 if l2_enabled else 0, f"({merge_base})")
        image_expr = " || ".join(image_parts)
    else:
-        image_expr = BOOTSTRAP_ENABLED_IF
-        ready_expr = ready_upload
-        merge_expr = merge_upload if platform == "cuda" else BOOTSTRAP_DISABLED_IF
-        nightly_expr = NIGHTLY_LABEL_IF
-        weekly_expr = weekly_label_if if platform == "cuda" else BOOTSTRAP_DISABLED_IF
+        image_expr = "true"
+        ready_expr = ready_base
+        merge_expr = merge_base if platform == "cuda" else disabled
+        nightly_expr = nightly_label_if
+        weekly_expr = weekly_label_if if platform == "cuda" else disabled

    return {
        "image": _format_bootstrap_if(image_expr),
@@ -8,28 +8,28 @@ steps:
    agents:
      queue: "cpu_queue_premerge"

-  # L2 Test — PR ready label (diff-aware) or main+WEEKLY=1 (--e2e, full E2E group)
+  # L2 Test — PR ready label (diff-aware) or main+NIGHTLY=1 (--e2e, full E2E group)
  - label: "Upload Ready Pipeline"
    depends_on: image-build
    key: upload-ready-pipeline
    commands:
      - |
        EXTRA=""
-        if [ "${WEEKLY:-}" = "1" ] && [ "${BUILDKITE_BRANCH}" = "main" ]; then
+        if [ "${NIGHTLY:-}" = "1" ] && [ "${BUILDKITE_BRANCH}" = "main" ]; then
          EXTRA="--e2e"
        fi
        python3 .buildkite/common/scripts/upload_pipeline.py --upload $$EXTRA .buildkite/cuda/test-ready.yml
    agents:
      queue: "cpu_queue_premerge"

-  # L3 Test — PR merge-test label (diff-aware) or main+WEEKLY=1 (--e2e, full E2E group)
+  # L3 Test — PR merge-test label (diff-aware) or main+NIGHTLY=1 (--e2e, full E2E group)
  - label: "Upload Merge Pipeline"
    depends_on: image-build
    key: upload-merge-pipeline
    commands:
      - |
        EXTRA=""
-        if [ "${WEEKLY:-}" = "1" ] && [ "${BUILDKITE_BRANCH}" = "main" ]; then
+        if [ "${NIGHTLY:-}" = "1" ] && [ "${BUILDKITE_BRANCH}" = "main" ]; then
          EXTRA="--e2e"
        fi
        python3 .buildkite/common/scripts/upload_pipeline.py --upload $$EXTRA .buildkite/cuda/test-merge.yml
@@ -45,7 +45,7 @@ steps:
    agents:
      queue: "cpu_queue_premerge"

-  # L5 Test — main+WEEKLY=1 / NON_CRITICAL=1 (scheduled), or PR with weekly-test label
+  # L5 Test — main+WEEKLY=1 (scheduled), or PR with weekly-test label
  - label: "Upload Weekly Pipeline"
    depends_on: image-build
    key: upload-weekly-pipeline
@@ -9,27 +9,23 @@ steps:
    depends_on: upload-merge-pipeline
    steps:
      - label: "Simple · Model Executor Test"
-        timeout_in_minutes: 20
        commands:
-          - "pytest -sv tests/model_executor -m 'core_model and cpu'"
+          - "timeout 20m pytest -sv tests/model_executor -m 'core_model and cpu' --cov=vllm_omni --cov-report=term-missing:skip-covered --cov-report=xml"
        mirror_hardwares: l4_1

      - label: "Simple · Diffusion Test"
-        timeout_in_minutes: 20
        commands:
-          - "pytest -sv tests/diffusion -m 'core_model and cpu'"
+          - "timeout 20m pytest -sv tests/diffusion -m 'core_model and cpu' --cov=vllm_omni --cov-report=term-missing:skip-covered --cov-report=xml"
        mirror_hardwares: l4_1

      - label: "Simple · Engine&Entrypoints Test"
-        timeout_in_minutes: 20
        commands:
-          - "pytest -sv tests/entrypoints tests/engine -m 'core_model and cpu'"
+          - "timeout 20m pytest -sv tests/entrypoints tests/engine -m 'core_model and cpu' --cov=vllm_omni --cov-report=term-missing:skip-covered --cov-report=xml"
        mirror_hardwares: l4_1

      - label: "Simple · Other Test"
-        timeout_in_minutes: 20
        commands:
-          - "pytest -sv tests/ -m 'core_model and cpu' --ignore=tests/diffusion --ignore=tests/model_executor --ignore=tests/entrypoints --ignore=tests/engine"
+          - "timeout 20m pytest -sv tests/ -m 'core_model and cpu' --ignore=tests/diffusion --ignore=tests/model_executor --ignore=tests/entrypoints --ignore=tests/engine --cov=vllm_omni --cov-report=term-missing:skip-covered --cov-report=xml"
        mirror_hardwares: l4_1

  - group: ":card_index_dividers: Diffusion Test"
@@ -123,8 +119,6 @@ steps:
        source_file_dependencies:
          - tests/e2e/offline_inference/test_qwen3_omni.py
          - tests/e2e/online_serving/test_qwen3_omni.py
-          - tests/helpers/runtime.py
-          - vllm_omni/entrypoints/openai/serving_chat.py
          - vllm_omni/model_executor/models/qwen3_omni/
          - vllm_omni/model_executor/models/common/qwen3_code_predictor.py
          - vllm_omni/model_executor/models/common/snake_activation.py
@@ -89,6 +89,32 @@ steps:
            exit $$EXIT
        mirror_hardwares: h100_2

+      - label: ":full_moon: Omni · Perf Test · vLLM Text"
+        key: nightly-omni-performance-vllm-text
+        timeout_in_minutes: 180
+        commands:
+          - export BENCHMARK_DIR=tests/dfx/perf/results
+          - |
+            set +e
+            pytest -s -v tests/dfx/perf/scripts/run_benchmark.py --test-config-file tests/dfx/perf/tests/test_qwen3_omni_vllm_text.json
+            EXIT=$$?
+            buildkite-agent artifact upload "tests/dfx/perf/results/*.json"
+            exit $$EXIT
+        mirror_hardwares: h100_2
+
+      - label: ":full_moon: Omni · Perf Test · Multi-Replica"
+        key: nightly-omni-performance-multi-replicas
+        timeout_in_minutes: 180
+        commands:
+          - export BENCHMARK_DIR=tests/dfx/perf/results
+          - |
+            set +e
+            pytest -s -v tests/dfx/perf/scripts/run_benchmark.py --test-config-file tests/dfx/perf/tests/test_qwen3_omni_multi_replicas.json
+            EXIT=$$?
+            buildkite-agent artifact upload "tests/dfx/perf/results/*.json"
+            exit $$EXIT
+        mirror_hardwares: h100_3
+
      - label: ":full_moon: Omni · MiniCPM-o 4.5 · Perf Test"
        key: nightly-omni-performance-minicpmo-4-5
        timeout_in_minutes: 180
@@ -229,12 +255,6 @@ steps:
          - pytest -s -v tests/e2e/accuracy/test_hunyuan_image3_pixel_accuracy.py -m full_model --run-level full_model
        mirror_hardwares: h100_4

-      - label: ":full_moon: HiDream-O1-Image · Accuracy Test"
-        timeout_in_minutes: 180
-        commands:
-          - pytest -s -v tests/e2e/accuracy/test_hidream_o1_image.py -m full_model --run-level full_model
-        mirror_hardwares: h100_2
-
      - label: ":full_moon: Diffusion X2I(&A&T) · Perf Test · Qwen-Image"
        key: nightly-diffusion-x2iat-performance-qwen-image
        timeout_in_minutes: 180
@@ -386,6 +406,8 @@ steps:
    depends_on:
      - nightly-omni-performance-no-async-chunk
      - nightly-omni-performance-async-chunk
+      - nightly-omni-performance-vllm-text
+      - nightly-omni-performance-multi-replicas
      - nightly-tts-performance
      - nightly-diffusion-x2iat-performance-qwen-image
      - nightly-diffusion-x2v-performance
@@ -397,6 +419,8 @@ steps:
      - buildkite-agent artifact download "tests/dfx/perf/results/*.json" . --step nightly-tts-performance
      - buildkite-agent artifact download "tests/dfx/perf/results/*.json" . --step nightly-omni-performance-no-async-chunk
      - buildkite-agent artifact download "tests/dfx/perf/results/*.json" . --step nightly-omni-performance-async-chunk
+      - buildkite-agent artifact download "tests/dfx/perf/results/*.json" . --step nightly-omni-performance-vllm-text
+      - buildkite-agent artifact download "tests/dfx/perf/results/*.json" . --step nightly-omni-performance-multi-replicas
      - buildkite-agent artifact download "tests/dfx/perf/results/*.json" . --step nightly-diffusion-x2iat-performance-qwen-image
      - buildkite-agent artifact download "tests/dfx/perf/results/*.json" . --step nightly-diffusion-x2v-performance
      - python tools/nightly/generate_nightly_perf_excel.py
@@ -9,27 +9,23 @@ steps:
    depends_on: upload-ready-pipeline
    steps:
      - label: "Simple · Model Executor Test"
-        timeout_in_minutes: 20
        commands:
-          - "pytest -sv tests/model_executor -m 'core_model and cpu'"
+          - "timeout 20m pytest -sv tests/model_executor -m 'core_model and cpu' --cov=vllm_omni --cov-report=term-missing:skip-covered --cov-report=xml"
        mirror_hardwares: l4_1

      - label: "Simple · Diffusion Test"
-        timeout_in_minutes: 20
        commands:
-          - "pytest -sv tests/diffusion -m 'core_model and cpu'"
+          - "timeout 20m pytest -sv tests/diffusion -m 'core_model and cpu' --cov=vllm_omni --cov-report=term-missing:skip-covered --cov-report=xml"
        mirror_hardwares: l4_1

      - label: "Simple · Engine&Entrypoints Test"
-        timeout_in_minutes: 20
        commands:
-          - "pytest -sv tests/entrypoints tests/engine -m 'core_model and cpu'"
+          - "timeout 20m pytest -sv tests/entrypoints tests/engine -m 'core_model and cpu' --cov=vllm_omni --cov-report=term-missing:skip-covered --cov-report=xml"
        mirror_hardwares: l4_1

      - label: "Simple · Other Test"
-        timeout_in_minutes: 20
        commands:
-          - "pytest -sv tests/ -m 'core_model and cpu' --ignore=tests/diffusion --ignore=tests/model_executor --ignore=tests/entrypoints --ignore=tests/engine"
+          - "timeout 20m pytest -sv tests/ -m 'core_model and cpu' --ignore=tests/diffusion --ignore=tests/model_executor --ignore=tests/entrypoints --ignore=tests/engine --cov=vllm_omni --cov-report=term-missing:skip-covered --cov-report=xml"
        mirror_hardwares: l4_1

  - group: ":card_index_dividers: Diffusion Test"
@@ -80,7 +76,7 @@ steps:

      - label: "Tiny Model Tests · Diffusion (base)"
        commands:
-          - timeout 15m pytest -sv -n 4 tests/model_tests/diffusion -m 'core_model and cuda' --run-level "core_model"
+          - timeout 15m pytest -sv tests/model_tests/diffusion -m 'core_model and cuda' --run-level "core_model"
        mirror_hardwares: l4_1

  - label: "Engine&Model Executor Test"
@@ -172,8 +168,6 @@ steps:
      - label: "Omni · Qwen3-Omni Test"
        source_file_dependencies:
          - tests/e2e/online_serving/test_qwen3_omni.py
-          - tests/helpers/runtime.py
-          - vllm_omni/entrypoints/openai/serving_chat.py
          - vllm_omni/model_executor/models/qwen3_omni/
          - vllm_omni/model_executor/models/common/qwen3_code_predictor.py
          - vllm_omni/model_executor/models/common/snake_activation.py
@@ -5,91 +5,51 @@ env:
  HF_HUB_ETAG_TIMEOUT: 60

 steps:
-  - label: "Simple · CPU Coverage Test"
-    key: weekly-simple-cpu-coverage
-    depends_on: upload-weekly-pipeline
-    if: build.env("WEEKLY") == "1"
-    timeout_in_minutes: 60
-    commands:
-      - |
-        set +e
-        REPORT="coverage-core-model-cpu-$${BUILDKITE_STEP_ID:-local}.xml"
-        pytest -sv tests/ -m 'core_model and cpu' --cov=vllm_omni --cov-report=term-missing:skip-covered --cov-report=xml:$${REPORT}
-        EXIT=$$?
-        gzip -9 -f "$${REPORT}"
-        buildkite-agent artifact upload "$${REPORT}.gz"
-        exit $$EXIT
-    mirror_hardwares: l4_1

-  - group: "Reliability Test"
+  - label: "Reliability Test - qwen3-omni"
+    timeout_in_minutes: 180
+    depends_on: upload-weekly-pipeline
+    if: build.env("WEEKLY") == "1" || build.pull_request.labels includes "weekly-test"
+    commands:
+      - pytest -s -v tests/dfx/reliability/test_reliability_qwen3_omni.py -m "slow"
+    mirror_hardwares: h100_2
+
+  - label: "Reliability Test - wan22"
+    timeout_in_minutes: 180
+    depends_on: upload-weekly-pipeline
+    if: build.env("WEEKLY") == "1" || build.pull_request.labels includes "weekly-test"
+    commands:
+      - pytest -s -v tests/dfx/reliability/test_reliability_wan22.py -m "slow"
+    mirror_hardwares: h100_2
+
+  - label: "Reliability Test - hunyuan-image"
+    timeout_in_minutes: 180
+    depends_on: upload-weekly-pipeline
+    if: build.env("WEEKLY") == "1" || build.pull_request.labels includes "weekly-test"
+    commands:
+      - pytest -s -v tests/dfx/reliability/test_reliability_hunyuan_image.py -m "slow"
+    mirror_hardwares: h100_4
+
+  - group: "Reliability Test - Invalid parameters Test"
    depends_on: upload-weekly-pipeline
    if: build.env("WEEKLY") == "1" || build.pull_request.labels includes "weekly-test"
    steps:

-      - label: "Reliability Test · qwen3-omni"
-        timeout_in_minutes: 180
-        commands:
-          - pytest -s -v tests/dfx/reliability/test_reliability_qwen3_omni.py -m "slow"
-        mirror_hardwares: h100_2
-
-      - label: "Reliability Test · wan22"
-        timeout_in_minutes: 180
-        commands:
-          - pytest -s -v tests/dfx/reliability/test_reliability_wan22.py -m "slow"
-        mirror_hardwares: h100_2
-
-      - label: "Reliability Test · hunyuan-image"
-        timeout_in_minutes: 180
-        commands:
-          - pytest -s -v tests/dfx/reliability/test_reliability_hunyuan_image.py -m "slow"
-        mirror_hardwares: h100_4
-
-      - label: "Reliability Test · Invalid parameters · H100"
+      - label: "Invalid parameters Test · H100"
        timeout_in_minutes: 120
        commands:
          - pytest -s -v tests/dfx/reliability/invalid_param_test/ -m "slow and H100"
        mirror_hardwares: h100_2

-      - label: "Reliability Test · Invalid parameters · L4"
+      - label: "Invalid parameters Test · L4"
        timeout_in_minutes: 120
        commands:
          - pytest -s -v tests/dfx/reliability/invalid_param_test/ -m "slow and L4"
        mirror_hardwares: l4_1

-  - group: "Perf Test"
-    depends_on: upload-weekly-pipeline
-    if: build.env("WEEKLY") == "1" || build.pull_request.labels includes "weekly-test"
-    steps:
-
-      - label: ":full_moon: Omni · Perf Test · vLLM Text"
-        key: weekly-omni-performance-vllm-text
-        timeout_in_minutes: 180
-        commands:
-          - export BENCHMARK_DIR=tests/dfx/perf/results
-          - |
-            set +e
-            pytest -s -v tests/dfx/perf/scripts/run_benchmark.py --test-config-file tests/dfx/perf/tests/test_qwen3_omni_vllm_text.json
-            EXIT=$$?
-            buildkite-agent artifact upload "tests/dfx/perf/results/*.json"
-            exit $$EXIT
-        mirror_hardwares: h100_2
-
-      - label: ":full_moon: Omni · Perf Test · Multi-Replica"
-        key: weekly-omni-performance-multi-replicas
-        timeout_in_minutes: 180
-        commands:
-          - export BENCHMARK_DIR=tests/dfx/perf/results
-          - |
-            set +e
-            pytest -s -v tests/dfx/perf/scripts/run_benchmark.py --test-config-file tests/dfx/perf/tests/test_qwen3_omni_multi_replicas.json
-            EXIT=$$?
-            buildkite-agent artifact upload "tests/dfx/perf/results/*.json"
-            exit $$EXIT
-        mirror_hardwares: h100_3
-
  - group: ":card_index_dividers: E2E Tests"
    depends_on: upload-weekly-pipeline
-    if: build.env("NON_CRITICAL") == "1"
+    if: build.env("WEEKLY") == "1" || build.pull_request.labels includes "weekly-test"
    steps:

      - label: "Omni · L4"
@@ -115,7 +75,7 @@ steps:
        mirror_hardwares: h100_2

      - label: "TTS · L4"
-        timeout_in_minutes: 120
+        timeout_in_minutes: 90
        commands:
          - export VLLM_ALLOW_LONG_MAX_MODEL_LEN="1"
          - export VLLM_USE_DEEP_GEMM="0"
@@ -166,7 +126,7 @@ steps:
        mirror_hardwares: l4_4

      - label: "Diffusion · H100 · Single-GPU"
-        timeout_in_minutes: 150
+        timeout_in_minutes: 120
        commands:
          - >-
            pytest -sv
@@ -81,55 +81,6 @@ steps:
            EXIT=$$?
            buildkite-agent artifact upload "tests/e2e/accuracy/minicpmo_4_5/results/*.json"
            exit $$EXIT
-      - label: ":full_moon: Omni · MiniCPM-o 4.5 · Perf Test"
-        key: nightly-omni-performance-minicpmo-4-5-npu
-        timeout_in_minutes: 180
-        mirror_hardwares: a3_npu_2
-        env:
-          VLLM_WORKER_MULTIPROC_METHOD: spawn
-          VLLM_ALLOW_LONG_MAX_MODEL_LEN: "1"
-          HF_TOKEN: "${HF_TOKEN}"
-        commands:
-          - export BENCHMARK_DIR=tests/dfx/perf/results
-          - |
-            set +e
-            pytest -s -v tests/dfx/perf/scripts/run_benchmark.py -m "npu and A3" --test-config-file tests/dfx/perf/tests/test_minicpmo_4_5.json
-            EXIT=$$?
-            buildkite-agent artifact upload "tests/dfx/perf/results/*.json"
-            exit $$EXIT
-      - label: ":full_moon: Omni · MiniCPM-o 4.5 · Perf Test (A2)"
-        key: nightly-omni-performance-minicpmo-4-5-npu-a2
-        timeout_in_minutes: 180
-        mirror_hardwares: a2b3_npu_1
-        env:
-          VLLM_WORKER_MULTIPROC_METHOD: spawn
-          VLLM_ALLOW_LONG_MAX_MODEL_LEN: "1"
-          HF_TOKEN: "${HF_TOKEN}"
-          HF_HUB_OFFLINE: "1"
-        commands:
-          - export BENCHMARK_DIR=tests/dfx/perf/results
-          - |
-            set +e
-            pytest -s -v tests/dfx/perf/scripts/run_benchmark.py -m "npu and A2" --test-config-file tests/dfx/perf/tests/test_minicpmo_4_5.json
-            EXIT=$$?
-            buildkite-agent artifact upload "tests/dfx/perf/results/*.json"
-            exit $$EXIT
-      - label: ":full_moon: Omni · MiniCPM-o 4.5 · Duplex Seed-TTS Perf Test"
-        key: nightly-omni-performance-minicpmo-4-5-duplex-seed-tts-npu
-        timeout_in_minutes: 180
-        mirror_hardwares: a3_npu_2
-        env:
-          VLLM_WORKER_MULTIPROC_METHOD: spawn
-          VLLM_ALLOW_LONG_MAX_MODEL_LEN: "1"
-          HF_TOKEN: "${HF_TOKEN}"
-        commands:
-          - export BENCHMARK_DIR=tests/dfx/perf/results
-          - |
-            set +e
-            pytest -s -v tests/dfx/perf/scripts/run_benchmark.py -m "npu and A3" --test-config-file tests/dfx/perf/tests/test_minicpmo_4_5_duplex_seed_tts.json
-            EXIT=$$?
-            buildkite-agent artifact upload "tests/dfx/perf/results/*.json"
-            exit $$EXIT
  - group: ":card_index_dividers: TTS Model Test"
    key: nightly-tts-test-group
    depends_on: upload-nightly-pipeline
@@ -43,7 +43,7 @@ steps:
    depends_on: upload-ready-pipeline
    steps:
      - label: ":sound: TTS · Qwen3-TTS CustomVoice Test"
-        mirror_hardwares: a3_npu_2
+        mirror_hardwares: a2b3_npu_1
        env:
          VLLM_WORKER_MULTIPROC_METHOD: spawn
          VLLM_ALLOW_LONG_MAX_MODEL_LEN: "1"
@@ -610,24 +610,6 @@ See the [Profiling Single-Stage Diffusion](../../../docs/contributing/profiling.

 ---

-## Pre-commit conventions
-
-New library files must pass the local gates in
-[docs/contributing/README.md](../../../docs/contributing/README.md#linting).
-That page is the full hook list (SPDX, forbidden imports including Hugging Face
-Hub / Triton / pickle, `torch.cuda`, mypy, test marks, markdownlint, Buildkite,
-shellcheck). In particular:
-
- SPDX copyright is `vLLM-Omni project` (stale `vLLM project` is rewritten).
- Use `import regex as re` and `pybase64` in `vllm_omni/`; do not import stdlib
-  `re` or `base64`. Hugging Face Hub downloads go through
-  `vllm.transformers_utils.repo_utils`.
- Do not add `torch.cuda.*` call sites; use `current_omni_platform`.
- New `tests/**/test_*.py` files need a CI level mark and a hardware mark.
- Do not expand `CHECK_IMPORTS[*].allowed_files` or `ALLOWED_FILES` without review.
- GitHub Actions skips SPDX/shellcheck/mypy-3.10/test-marks/markdownlint; run
-  `pre-commit` locally.
-
 ## Iterative Development Tips

 1. **Start minimal**: Basic generation first, no parallelism/caching
@@ -138,12 +138,9 @@ A shared buffer silently corrupts audio across concurrent requests — the sympt
   - Load codec weights (may need lazy loading from separate checkpoint)
   - Implement `forward()`: codec codes -> audio waveform
   - Return `OmniOutput` with `multimodal_outputs`
-5. **Define and register the pipeline topology** in
-   `vllm_omni/model_executor/models/<model>/pipeline.py`
-6. **Create the deploy YAML** under `vllm_omni/deploy/` for placement,
-   memory sizing, connectors, and runtime overrides
-7. **Create stage input processor** for prompt building and inter-stage handoff
-8. **Write end2end.py** test script
+5. **Create stage config YAML** defining both stages, memory allocation, and model paths
+6. **Create stage input processor** for prompt building
+7. **Write end2end.py** test script

 ### Critical Parameters to Get Right

@@ -177,7 +174,7 @@ These bugs appear in almost every new TTS PR. Check all before the first push. S
 - **All return paths must emit `model_outputs`** — if any early-return branch skips setting `model_outputs`, the serving layer silently drops that step's audio (fish speech: `fix: ensure ALL return paths emit model_outputs`)
 - **Per-request state isolation** — for batched concurrent requests, key all state by request ID; a shared buffer corrupts audio across requests (fish speech: `fix: per-request vocode + delta emission`)
 - **Codec tensor device** — move codec codes to the codec decoder's device before calling decode; mismatches cause silent CPU fallback or crashes (fish speech: `fix: use model device for CUDA stream`)
- **AR stage `max_num_seqs`** — set to at least 4 in production deploy configs; for single-stage models this is the only stage. For two-stage models, Stage 0 (AR) needs `max_num_seqs ≥ 4` to pipeline concurrent requests; Stage 1 (codec decoder) is model-specific and may intentionally use `max_num_seqs: 1`. Defaulting the AR stage to 1 causes audio gaps under concurrency because the codec window round-robins across requests (RFC #2568)
+- **AR stage `max_num_seqs`** — set to at least 4 in production configs; for single-stage models this is the only stage. For two-stage models, Stage 0 (AR) needs `max_num_seqs ≥ 4` to pipeline concurrent requests; Stage 1 (codec decoder) typically uses `max_num_seqs: 1` intentionally. Default of 1 everywhere causes audio gaps under concurrency because the codec window round-robins across requests (RFC #2568)

 ### Optional Dependency Handling

@@ -193,18 +190,18 @@ pattern, signature constraints, and MOSS-TTS-Nano reference.
 When the upstream model cannot be cleanly split into an AR stage and a
 separate decoder, run the full pipeline inside a single AR worker and
 stream audio through a per-request `inference_stream()` generator keyed by
-`_omni_req_id`. Define one `StagePipelineConfig` with
-`execution_type=StageExecutionType.LLM_AR`, `engine_output_type="audio"`,
-`final_output=True`, and `owns_tokenizer=True`. Set `async_chunk: false` in
-the deploy YAML. Only extract params from
+`_omni_req_id`. Stage config must set `worker_type: ar`,
+`engine_output_type: audio`, `final_output: true`, `is_comprehension: true`,
+and `async_chunk: false` at the top level. Only extract params from
 `additional_information` that you actually forward, or pre-commit fails
 `ruff F841`.

 Full walkthrough with the complete `forward()` / `_create_stream_gen()`
-skeleton plus pipeline/deploy definitions:
+skeleton and stage-config fields:
 [references/single-stage-ar.md](references/single-stage-ar.md). For an
 in-tree reference, look for any single-stage AR model under
-`vllm_omni/model_executor/models/`, such as MOSS-TTS-Nano.
+`vllm_omni/model_executor/models/` — e.g. the MOSS-TTS-Nano integration when
+it lands.

 **VoxCPM2 is a different pattern** and should not reuse this skeleton — it
 runs the base LM under vLLM PagedAttention with external side-computation.
@@ -213,8 +210,7 @@ See `plan/voxcpm2_native_ar_design.md`.
 ### Deliverables

 - Model files in `vllm_omni/model_executor/models/<model_name>/`
- Registered `pipeline.py` topology
- Deploy YAML under `vllm_omni/deploy/`
+- Stage config YAML
 - Working `end2end.py` at `examples/offline_inference/text_to_speech/<model>/end2end.py`
 - New section in `examples/offline_inference/text_to_speech/README.md` (table row + per-model section). Do **not** create a top-level `examples/offline_inference/<model>/` dir or a per-model `README.md` inside `text_to_speech/<model>/` — the hub README is the documented surface and the mkdocs `generate_examples` hook only descends one level into `examples/<category>/`.

@@ -404,29 +400,21 @@ See [vllm-omni-test skill](../vllm-omni-test/SKILL.md) § **Runtime send helpers

 ### Steps

-1. **Update the pipeline topology** so the producing stage declares its async
-   handoff processor with `async_chunk_process_next_stage_input_func`.
-2. **Update the deploy YAML** to enable async chunk and configure the connector:
+1. **Update stage config YAML**:
   ```yaml
   async_chunk: true
-
-   connectors:
-     connector_of_shared_memory:
-       name: SharedMemoryConnector
-       extra:
-         codec_streaming: true
-         codec_chunk_frames: 25
-         codec_left_context_frames: 25
+   codec_chunk_frames: 25      # frames per chunk
+   codec_left_context_frames: 25  # overlap for smooth boundaries
   ```
-3. **Implement chunk handling in Stage 1**:
+2. **Implement chunk handling in Stage 1**:
   - Accept partial input (chunk of codec codes)
   - Handle left context for smooth audio boundaries
   - Return partial audio in `OmniOutput`
-4. **Test streaming**:
+3. **Test streaming**:
   - Verify audio quality matches non-streaming output
   - Check for artifacts at chunk boundaries
   - Measure TTFA (time to first audio)
-5. **Update online serving** to support `stream=true` with PCM output
+4. **Update online serving** to support `stream=true` with PCM output

 ### Streaming Architecture

@@ -447,8 +435,7 @@ Stage 0 (AR)                    Stage 1 (Decoder)

 ### Deliverables

- Updated pipeline async handoff processor and deploy config with
-  `async_chunk: true`
+- Updated stage config with async_chunk enabled
 - Smooth streaming audio without boundary artifacts
 - TTFA metrics

@@ -520,15 +507,14 @@ Use this checklist when integrating a new TTS model:
 - [ ] Config classes created with `model_type` registration
 - [ ] Stage 0 (AR) implemented and generates correct tokens
 - [ ] Stage 1 (Decoder) produces correct audio from tokens — dtype float32 for codec decoder
- [ ] AR stage `max_num_seqs` ≥ 4 in the production deploy config unless the model has a tested lower limit
+- [ ] Stage 1 `max_num_seqs` ≥ 4 in production config (default 1 causes gaps under concurrency)
 - [ ] Optional dependency fallbacks handled at `load_weights()` time (torchaudio/soundfile/etc.)
 - [ ] Streaming: codec codes accumulated across AR steps (not reset per step)
 - [ ] Streaming: delta audio emitted per chunk, not full re-decoded waveform
 - [ ] Streaming: all `forward()` return paths emit `model_outputs`
 - [ ] Streaming: per-request state keyed by request ID (not shared across requests)
 - [ ] Streaming: codec tensors moved to codec decoder device before decode
- [ ] Pipeline topology defined in `pipeline.py` and registered in `OMNI_PIPELINES`
- [ ] Deploy YAML created under `vllm_omni/deploy/`
+- [ ] Stage config YAML created
 - [ ] `end2end.py` produces audio matching reference quality
 - [ ] README.md written

@@ -545,8 +531,7 @@ Use this checklist when integrating a new TTS model:
 - [ ] Documentation added (offline + online docs, nav, supported models)

 ### Phase 4: Async Chunk
- [ ] Pipeline declares the async handoff processor
- [ ] Deploy config sets `async_chunk: true` and connector chunk parameters
+- [ ] Stage config updated with `async_chunk: true`
 - [ ] Stage 1 handles partial chunks correctly
 - [ ] No audio artifacts at chunk boundaries
 - [ ] Streaming via API (`stream=true`) works
@@ -563,7 +548,7 @@ Use this checklist when integrating a new TTS model:
 - [ ] `pre-commit run --files <changed>` passes before every push
 - [ ] Every commit has `Signed-off-by` matching the author email (`git commit -s`)
 - [ ] `git config user.email` matches the email registered on your GitHub account
- [ ] Hook list, failure table, and DCO recovery: [references/precommit-dco.md](references/precommit-dco.md)
+- [ ] Details and failure-recovery commands: [references/precommit-dco.md](references/precommit-dco.md)

 ## References

@@ -30,18 +30,6 @@ but the changes are correct — stage the modified files and re-commit.
 | `ruff F841` | Variable extracted but never forwarded to model call | Remove the extraction or wire it through |
 | `ruff E402` | Import added below function definitions | Move to top-level import block |
 | `ruff format` | Line length, spacing, quote style | Accept auto-fix, stage, re-commit |
-| `check-spdx-header` | Missing header, or copyright still says `vLLM project` | Two-line Omni header (`vLLM-Omni project`); restage the rewrite |
-| `check-forbidden-imports` | Stdlib `re`/`base64`, pickle, Hugging Face Hub API, or direct Triton/TileLang | `import regex as re` and `pybase64`; use `vllm.transformers_utils.repo_utils`. Do **not** add the file to `allowed_files` without review |
-| `check-torch-cuda-call` | New `torch.cuda.*` call site | Use `current_omni_platform` / `OmniPlatform`; do not grow `ALLOWED_FILES` without review |
-| `check-tts-adapter-migration` | New `self._tts_model_type` branch in `serving_speech.py` | Put per-model logic in `tts_adapters/`. Lower `MAX_MODEL_TYPE_BRANCHES` when removing branches; do not raise it without review |
-| `check-test-ci-coverage` | New `tests/**/test_*.py` missing level or hardware mark | Add `core_model`/`advanced_model`/… plus `cpu`/`cuda`/`hardware_test(` |
-| `mypy-3.10` | Type error on changed `vllm_omni/` files | Fix the types; model trees are excluded. Extra versions: `pre-commit run --hook-stage manual mypy-3.12` |
-| `markdownlint-cli2` | Docs/README markdown lint | Accept auto-fix under `docs/` / `recipes/` / root README |
-| `check-buildkite` | Invalid `.buildkite/*.yml` | Fix the YAML; do not grow `SKIP_FILES` without review |
-| `shellcheck` | No `shellcheck` on PATH, or script warning | `apt-get`/`dnf`/`brew install shellcheck`, or `shellcheck.exe` on Windows PATH |
-
-Canonical policy, CI `SKIP` list, and allowlist locations:
-[docs/contributing/README.md](../../../docs/contributing/README.md#linting).

 ## DCO sign-off

@@ -86,51 +86,12 @@ class YourModelForCausalLM(nn.Module):
 - Handle both `"audio"` (incremental) and `"result"` (final combined) event
  types from upstream models.

-## Pipeline and deploy config
+## Stage config

-Define the fixed single-stage topology in `pipeline.py`:
-
-```python
-from vllm_omni.config.stage_config import (
-    PipelineConfig,
-    StageExecutionType,
-    StagePipelineConfig,
-)
-
-YOUR_TTS_PIPELINE = PipelineConfig(
-    model_type="your_model_name",
-    default_deploy_config_name="your_model_name.yaml",
-    model_arch="YourModelForCausalLM",
-    stages=(
-        StagePipelineConfig(
-            stage_id=0,
-            model_stage="your_model_name",
-            execution_type=StageExecutionType.LLM_AR,
-            input_sources=(),
-            owns_tokenizer=True,
-            engine_output_type="audio",
-            final_output=True,
-            final_output_type="audio",
-        ),
-    ),
-)
-```
-
-Register it in `vllm_omni/config/pipeline_registry.py`. Keep placement and
-runtime sizing in `vllm_omni/deploy/your_model_name.yaml`:
-
-```yaml
-async_chunk: false
-
-stages:
-  - stage_id: 0
-    devices: "0"
-    max_num_seqs: 4
-    gpu_memory_utilization: 0.8
-```
-
-Do not move `execution_type`, output ownership, tokenizer ownership, or model
-architecture into the deploy YAML; those are pipeline topology.
+Single stage with `worker_type: ar`, `engine_output_type: audio`,
+`final_output: true`, `is_comprehension: true`, and `async_chunk: false` at
+the top level. Omitting any of these causes silent misclassification in the
+serving layer.

 ## Lint discipline

@@ -140,5 +101,8 @@ pre-commit.

 ## Reference implementation

-Use `vllm_omni/model_executor/models/moss_tts_nano/pipeline.py` and
-`vllm_omni/deploy/moss_tts_nano.yaml` as the in-tree reference.
+Look for any single-stage AR model under
+`vllm_omni/model_executor/models/` — e.g. `moss_tts_nano/` when its
+integration lands. If none is in tree yet, follow the skeleton above and
+cross-check against the `is_comprehension: true` / `async_chunk: false`
+dispatch in `vllm_omni/entrypoints/openai/serving_speech.py`.
@@ -1,135 +0,0 @@
---
-name: find-simplifications
-description: Find evidence-backed simplification candidates in vLLM-Omni and, when requested, turn them into focused proposals or code changes. Use for audits of dead, duplicated, speculative, over-generalized, unnecessarily defensive, or hand-rolled code. Use review-pr for ordinary correctness review and diffusion-perf-opt for performance-first optimization.
---
-
-# Find vLLM-Omni Simplifications
-
-Find a small number of well-proven ways to reduce code, state, APIs, or maintenance cost without weakening supported behavior. Treat this as an architecture and ownership audit, not a dead-code search or style cleanup.
-
-The default deliverable is a read-only report. Do not add TODOs, design documents, issues, or code unless the user asks for those changes.
-
-## Establish the Contract
-
-Before judging a candidate:
-
-1. Read the repository instructions supplied by the host.
-2. Read [`docs/design/architecture_overview.md`](../../../docs/design/architecture_overview.md).
-3. Select only the relevant active module and feature documents from [`docs/design/index.md`](../../../docs/design/index.md). Archived design pages are historical context, not current contracts.
-4. Identify the comparison base with `git merge-base HEAD origin/main`; do not assume the current branch represents the intended baseline.
-5. If tests or CI coverage may change, use [`vllm-omni-test`](../vllm-omni-test/SKILL.md) for test placement, markers, and commands.
-
-Separate an implementation accident from an intentional boundary. In particular:
-
- vLLM-Omni extends and sometimes overrides upstream vLLM. A similar upstream implementation is evidence for reuse only after comparing API, lifecycle, and multi-stage semantics.
- Registries, import strings, model configuration, deployment YAML, plugins, and optional dependencies create dynamic consumers that a static reference count can miss.
- Hardware backends, model families, execution modes, and connector implementations may be intentionally parallel. Do not propose collapsing one only because it is inactive in the local environment.
- Stage, replica, request, cache, and transport state can look redundant while representing different owners. Prove that two fields or barriers encode the same fact before merging them.
- A shorter hot path is not a simplification if it adds synchronization, tensor copies, host materialization, recompilation, or a measurable quality/performance regression.
-
-## Strong Candidates
-
-A strong candidate removes a meaningful surface and has a clear replacement or deletion boundary. Examples include:
-
- A public method, configuration option, registry entry, route, message field, or event has no production consumer and no compatibility obligation.
- Tests or documentation are the only consumers of behavior that is not part of a supported contract.
- Multiple layers mirror the same request, lifecycle, cache-validity, readiness, or topology state.
- AR, diffusion, platform, or model-specific implementations duplicate a stable common operation and can share it without hiding performance-critical differences.
- An inherited upstream vLLM primitive is reimplemented locally without an Omni-specific semantic difference.
- Compatibility or fallback branches protect environments the project no longer supports.
- Serialization, IPC, output formatting, or connector code materializes the same payload more than once or converts between equivalent representations.
- A helper, abstraction, package split, or extension point has only one real implementation and adds more indirection than policy.
- Hand-written infrastructure can be replaced by an existing project dependency, Python standard-library feature, PyTorch primitive, or upstream vLLM facility with net deletion and equal observability.
- Tests maintain large mocks, snapshots, or expected data solely for an unused API or representation.
-
-Do not elevate typo fixes, formatting, isolated renames, or vague complexity complaints into simplification candidates. Bundle small cleanups only when they support one substantive removal.
-
-## Survey by Ownership Boundary
-
-For broad audits, cover the largest or riskiest production deltas first. Useful domains are:
-
- `vllm_omni/engine/`: orchestration, stage pools, request state, output convergence, cancellation, and replica lifecycle.
- `vllm_omni/worker/` and AR model execution: upstream vLLM overlays, scheduler/cache state, collective RPC, adapters, and weight loading.
- `vllm_omni/diffusion/`: request/step execution, batching, output materialization, IPC, offload, parallelism, and model pipelines.
- `vllm_omni/entrypoints/`: duplicated validation/defaulting, offline/online parity, streaming, and route compatibility.
- Connectors and distributed code: ownership, copies, barriers, handles, cleanup, and failure propagation across process/device/node boundaries.
- Platform backends: genuine vendor differences versus copied control flow that has drifted.
- Configuration, registries, recipes, and examples: duplicate sources of truth and options that never reach a runtime consumer.
- Tests and CI: redundant fixtures, mocks of obsolete contracts, and expensive coverage that can move to a cheaper level without losing the guarded behavior.
-
-When the user explicitly requests a repository-wide or many-candidate audit and parallel agent work is available and authorized, divide these domains among agents and require the same evidence format from each. Otherwise survey them sequentially.
-
-## Prove or Reject Each Candidate
-
-Use `rg` first, then read every relevant caller and implementation. Search exact Python symbols plus serialized names, route paths, configuration keys, registry strings, YAML values, and CLI spellings.
-
-Classify evidence:
-
- **Production:** `vllm_omni/`, runtime configuration, registries, serving entrypoints, connectors, recipes used for supported deployments, and executable loader paths.
- **Validation/support:** `tests/`, benchmarks, examples, docs, CI, and developer tooling.
- **External/dynamic:** upstream vLLM contracts, third-party plugins, model repositories, optional backends, and string-loaded objects. State what was checked and what remains unknown.
-
-For each candidate, answer:
-
-1. What exact surface would disappear or merge?
-2. Who owns the state or behavior today?
-3. Which production consumers exist, including dynamic consumers?
-4. What supported behavior, compatibility, performance, memory, or observability could change?
-5. What is the smallest validation that would catch a bad simplification?
-6. Is the result net deletion after tests, adapters, migration glue, and documentation are counted?
-
-Reject or downgrade the candidate when a live consumer exists and removal is actually a feature decision; when an active design contract explains the separation; when the change only moves complexity; or when hardware/model evidence is unavailable for a performance-sensitive claim.
-
-## Lifecycle and Data-Movement Audits
-
-For asynchronous or distributed code, map the ownership graph before recommending deletion:
-
-```text
-request admission -> orchestrator -> stage/replica -> worker/device
-  -> connector or IPC boundary -> output aggregation -> terminal cleanup
-```
-
-Associate every lock, event, sentinel, queue, readiness flag, timeout, abort path, and cache marker with an owner and transition. Coalesce mechanisms only when they represent the same state and have the same failure boundary. Preserve separate mechanisms when they protect publication versus rollback, local versus remote ownership, first-terminal-outcome arbitration, or cleanup after partial failure.
-
-For tensors and media, also trace device, process, and ownership transitions. Count GPU-to-CPU copies, shared-memory/object-store handles, serialization, decode/encode steps, and unlink/release responsibility. Prefer eliminating a transfer or representation over merely hiding it behind a helper.
-
-## Dependency Replacements
-
-Prefer facilities already available in the repository before adding a dependency. For a proposed replacement:
-
- Name the exact local behavior it covers and any semantics that remain in glue code.
- Check maintenance, license, optional-dependency boundaries, platform support, and transitive footprint.
- Compare net deletion, test burden, import/startup cost, and runtime behavior.
- Benchmark when the replaced code is on a model, scheduler, connector, serialization, or serving hot path.
-
-A wrapper that retains the same state machine or conversion logic is not a simplification.
-
-## Deliver the Result
-
-Report only candidates supported by concrete evidence. For each one include:
-
- **Surface:** files and symbols involved.
- **Evidence:** production consumers found, dynamic paths checked, and relevant design contract.
- **Simplification:** exactly what to remove, merge, inline, or reuse.
- **Benefit:** deleted API/state/code, reduced data movement, or reduced maintenance/test burden.
- **Risk and validation:** behavior that could change and the narrowest useful tests or measurements.
- **Confidence:** high or medium, with the unresolved evidence named for medium-confidence items.
-
-Also list representative ideas that were rejected when that prevents repeated investigation. Prefer three high-confidence candidates over a long speculative inventory.
-
-If the user asks for a durable design proposal, place it under `docs/design/feature/` and register it in `docs/design/index.md`; use current design-document conventions and keep implementation details proportional to the decision. If the user asks for implementation, make the smallest coherent change, update affected tests/docs, and preserve public compatibility unless the user explicitly accepts a breaking change.
-
-## Folding Work from Another Branch
-
-Diff the source branch against its own merge base with `origin/main`, not against the current feature branch. Port only independently justified candidates. Consolidate overlaps into the candidate with stronger evidence, and do not preserve a candidate count by carrying weaker duplicates.
-
-## Validation
-
-Match validation to the outgoing diff:
-
- Documentation or skill changes: run the repository skill validator when available, check links/paths, search for stale source-specific terminology, and run `git diff --check`.
- Python changes: run the narrowest relevant pytest coverage through the repository environment, then lint/format the changed files.
- Distributed, model, hardware, performance, or accuracy changes: run available CPU/static checks and state the exact GPU/NPU/model gap; never present simulated evidence as device validation.
- Before submission, use [`precheck-pr`](../precheck-pr/SKILL.md) for the branch-level self-review.
-
-When summarizing, distinguish checks that passed from checks that were not runnable, and state the snapshot or branch against which the audit was performed.
@@ -67,10 +67,6 @@ Ask: "Quick mode or full mode?" Then walk the checklist for the detected PR type

 **Also run the Examples-Policy check on every PR** using [references/examples-policy.md](references/examples-policy.md). Inspect only Python paths introduced by the diff. Treat a new model-, checkpoint-, vendor-, or family-specific Python example as blocking; do not report pre-existing example debt.

-**Also run the Simplification pass on every PR** using [find-simplifications](../find-simplifications/SKILL.md). Keep it diff-scoped: inspect added or modified public APIs, state, abstractions, fallback and compatibility paths, data movement, and only the adjacent ownership needed to prove a candidate. Do not expand the pass into a repository-wide audit. Zero candidates is a valid pass; report only evidence-backed opportunities. Mark a candidate as blocking only when it proves a correctness or merge-readiness problem, such as newly unreachable code. Otherwise report it as a warning.
-
-**Also confirm local pre-commit gates** from [docs/contributing/README.md](../../../docs/contributing/README.md#linting). GitHub Actions `SKIP` does not prove they passed. Full new-hook list: Omni SPDX (`vLLM-Omni project`); forbidden imports (stdlib `re`/`base64`, pickle, Hugging Face Hub API, Triton/TileLang); no new `torch.cuda` call sites; shellcheck (macOS/Windows must install the binary); mypy-3.10; test files have CI level + hardware marks; TTS `_tts_model_type` branches in `serving_speech.py` must not increase; markdownlint on `docs/`; Buildkite YAML schema. ✗ for growing `allowed_files` / `ALLOWED_FILES` or raising `MAX_MODEL_TYPE_BRANCHES` without review.
-
 ### Step 5: Print Report

 ```
@@ -84,7 +80,6 @@ Pre-check report for <branch>
  PR title format    ✓
  Code quality       ⚠ 1 broad except, 2 Any hints
  Examples policy    ✗ new model-specific Python example
-  Simplification     ⚠ helper duplicates an existing owner
  PR desc integrity  ✓
  Registry/config    ✓
  Dead code          ⚠ 2 warnings
@@ -164,7 +164,6 @@ Diffusion models live under `vllm_omni/diffusion/`. In addition to the New Model
 - [ ] **PR body matches diff:** description doesn't claim changes not in the diff
 - [ ] **Branch is rebased:** `git merge-base HEAD origin/main` is recent, no merge conflicts
 - [ ] **CI gates passing:** DCO, pre-commit, build — check `gh pr view --json statusCheckRollup` if a PR already exists
- [ ] **Local pre-commit gates:** full list in [Linting](../../../../docs/contributing/README.md#linting). Blocking when the diff introduces: stale `vLLM project` SPDX; stdlib `re`/`base64` or pickle in library code; new `torch.cuda` call sites; `tests/**/test_*.py` without level+hardware marks; new `_tts_model_type` branches in `serving_speech.py`; invalid `.buildkite` YAML. macOS/Windows need a native `shellcheck`. ✗ for growing `CHECK_IMPORTS[*].allowed_files`, `ALLOWED_FILES`, or `MAX_MODEL_TYPE_BRANCHES` without review.

 ### Full (adds)

@@ -31,12 +31,9 @@ self-check.
 - [`diffusion-perf-opt`](diffusion-perf-opt/SKILL.md): guides diffusion model
  performance optimization, including profiling traces, parallel strategies,
  stage timing analysis, and benchmark-driven tuning
- [`find-simplifications`](find-simplifications/SKILL.md): finds evidence-backed
-  opportunities to remove or merge dead, duplicated, speculative,
-  over-generalized, or unnecessarily defensive vLLM-Omni code
 - [`precheck-pr`](precheck-pr/SKILL.md): self-checks a branch before creating a
-  PR by validating title format, dead code, simplification opportunities,
-  accuracy and performance claims, and merge readiness
+  PR by validating title format, dead code, accuracy and performance claims,
+  and merge readiness
 - [`quantization`](quantization/SKILL.md): guides quantization method selection,
  model integration, checkpoint loading, and quality/performance validation
  for vLLM-Omni
@@ -21,10 +21,7 @@ Make every finding:
 - **Calibrated:** match severity to user and maintainer impact.

 Do not report unrelated backlog, style already enforced by pre-commit, or a
-missing test that would not protect changed behavior. Do report new allowlist
-or budget entries in `check_forbidden_imports.py` / `check_torch_cuda.py` /
-`check_tts_adapter.py` / `check_buildkite.py` unless the PR justifies them:
-those are policy changes, not lint noise.
+missing test that would not protect changed behavior.

 ## Select the input and depth

@@ -95,13 +92,12 @@ If docs and live code disagree, verify the code/tests and report the drift.

 | Reference | Read when |
 | --- | --- |
-| [model-addition-checklist.md](references/checks/model-addition-checklist.md) | A model, architecture, loader, processor, registry, pipeline config, or deploy config is added. |
+| [model-addition-checklist.md](references/checks/model-addition-checklist.md) | A model, architecture, loader, processor, registry, or stage config is added. |
 | [perf-verification.md](references/checks/perf-verification.md) | The PR makes a latency, throughput, memory, or quality claim. |
 | [test-quality-evaluation.md](references/checks/test-quality-evaluation.md) | Tests change, are absent for risky code, or may not exercise production behavior. |
 | [tests-docs-checklist.md](references/checks/tests-docs-checklist.md) | Coverage, CI markers, examples, user docs, or PR evidence need review. |
 | [verification.md](references/checks/verification.md) | Hardware, a server, or a runnable affected path is available for active verification. |
 | [examples-policy.md](../precheck-pr/references/examples-policy.md) | The PR adds, copies, or renames Python under `examples/`; apply the canonical policy shared with `precheck-pr`. |
-| [find-simplifications](../find-simplifications/SKILL.md) | Every review; run a diff-scoped subtraction and simplification pass after correctness blockers. |

 ### Delivery and reviewer coordination

@@ -184,13 +180,9 @@ promotion gate. Candidate or draft rules are questions, not blockers, unless
 current code, tests, or policy enforce them. Inspect both sides of any config,
 registry, serialization, connector, cache, or stage boundary.

-Read and apply [find-simplifications](../find-simplifications/SKILL.md) on every
-review. Constrain it to the diff and the adjacent ownership, callers, or
-consumers needed to prove a candidate. Check whether added or expanded helpers,
-classes, state, fallback and compatibility branches, data movement, or public
-behavior can be deleted, merged, moved, or inlined. Zero candidates is a valid
-result. Do not widen the review into repository backlog or report speculative
-style preferences as simplification findings.
+When a diff adds or expands a helper, class, fallback, compatibility branch, or
+public behavior, run a subtraction pass: remove out-of-scope behavior and check
+whether each new abstraction can be deleted, merged, moved, or inlined.

 ### 6. Verify the changed path

@@ -1,7 +1,7 @@
 # Model Addition Checklist

 Read this reference when a PR adds or expands a model architecture, pipeline,
-loader, processor, registry entry, pipeline config, or deploy config.
+loader, processor, registry entry, or stage configuration.

 Official docs: [model contribution guides](https://docs.vllm.ai/projects/vllm-omni/en/latest/contributing/model/),
 [adding an omni model](https://docs.vllm.ai/projects/vllm-omni/en/latest/contributing/model/adding_omni_model/),
@@ -3,7 +3,7 @@
 Primary design: [vLLM-Omni Configuration](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/module/vllm_omni_config/).

 Use for config construction, deploy YAML, registries, schema, defaults,
-aliases, CLI projection, pipeline config, and topology. Inspect the reviewed
+aliases, CLI projection, stage config, and topology. Inspect the reviewed
 page's status: while its contract remains deferred or draft, current code and
 tests—not proposed precedence rules—are authoritative.

@@ -111,17 +111,6 @@ Mark early findings as preliminary and continue. This is not a GitHub comment.
  but do not publish review events without separate authorization.
 - Record DCO, pre-commit, required CI, and mergeability. Pending or unknown gates
  do not block source review.
- GitHub Actions `SKIP` omits SPDX, shellcheck, markdownlint, mypy-3.10, and
-  test-mark coverage. A green GHA pre-commit job does not prove those local
-  gates passed. New files still need the full Linting list: Omni SPDX
-  (`vLLM-Omni project`), no stdlib `re`/`base64` in `vllm_omni/`, no new
-  pickle / Hugging Face Hub API / `torch.cuda` call sites, test marks, TTS
-  adapter ratchet, Buildkite schema, and native shellcheck on macOS/Windows.
-  See [Linting](https://vllm-omni.readthedocs.io/en/latest/contributing/#linting).
- Expanding `CHECK_IMPORTS[*].allowed_files`, `ALLOWED_FILES`,
-  `MAX_MODEL_TYPE_BRANCHES`, or Buildkite `SKIP_FILES` is a policy change.
-  Do not rubber-stamp allowlist/budget growth; require justification and
-  prefer fixing the call site.
 - Treat a failed gate as its own evidence. Do not restate its formatting/lint
  output as a new code-review finding.
 - Open CI logs only when the first failing step overlaps the frozen diff or
@@ -48,7 +48,7 @@ compatibility changes.

 | Signal | Read | Optional repo-local skill |
 | --- | --- | --- |
-| New or expanded model, loader, processor, registry, pipeline config, or deploy config | [model-addition-checklist.md](../checks/model-addition-checklist.md) | [`add-tts-model`](../../../add-tts-model/SKILL.md) or [`add-diffusion-model`](../../../add-diffusion-model/SKILL.md) |
+| New or expanded model, loader, processor, registry, or stage config | [model-addition-checklist.md](../checks/model-addition-checklist.md) | [`add-tts-model`](../../../add-tts-model/SKILL.md) or [`add-diffusion-model`](../../../add-diffusion-model/SKILL.md) |
 | Latency, throughput, memory, scaling, precision, or quality claim | [perf-verification.md](../checks/perf-verification.md) | [`diffusion-perf-opt`](../../../diffusion-perf-opt/SKILL.md) for diffusion |
 | Tests changed, absent for risky behavior, or test-only | [test-quality-evaluation.md](../checks/test-quality-evaluation.md) | [`vllm-omni-test`](../../../vllm-omni-test/SKILL.md) |
 | CI, examples, docs, public behavior, or contributor evidence | [tests-docs-checklist.md](../checks/tests-docs-checklist.md) | None |
@@ -110,10 +110,10 @@ After choosing offline/online/docs/perf, classify the **product under test** and
 |-----------|------------------------------|----------------------------|----------------------------------------|
 | **What it is** | Multimodal LLM pipeline (thinker/talker/stages; text + vision + audio I/O) | Speech synthesis / voice models | Generative diffusion (noise → image, audio, text, or video) |
 | **Examples** | Qwen2.5-Omni, Qwen3-Omni | Qwen3-TTS, VoxCPM2, Higgs-Audio, Step-Audio2 | Qwen-Image, BAGEL, Wan2.2, HunyuanVideo |
-| **Offline runner** | `omni_runner` + `omni_runner_handler`, `generate_multimodal` | `Omni(...).generate` with deploy YAML + TTS params | `Omni(...).generate` + `OmniDiffusionSamplingParams` |
+| **Offline runner** | `omni_runner` + `omni_runner_handler`, `generate_multimodal` | `Omni(...).generate` or stage YAML + TTS params | `Omni(...).generate` + `OmniDiffusionSamplingParams` |
 | **Online client** | `openai_client.send_omni_request` (chat completions, modalities) | `openai_client.send_audio_speech_request` (`/v1/audio/speech`) | `send_diffusion_request` (chat/T2I), `send_video_diffusion_request` (`/v1/videos`, X2V), or `send_images_generations_http_request` / `send_images_edits_http_request` (DALL-E routes) |
 | **Typical assertions** | Stage outputs, text/audio keywords via `OmniRunnerHandler` / response handler | WAV bytes, stream chunks, speech endpoint contract | Image/video dimensions, `final_output_type`, `assert_diffusion_response` |
-| **Deploy YAML** | Per-model deploy configs (`ci/qwen3_omni_moe.yaml`, …) | `qwen3_tts.yaml`, `voxcpm2.yaml`, … | Often default serve; parallel/offload YAML for heavy DiT |
+| **Stage / deploy YAML** | Per-model omni stage configs (`ci/qwen3_omni_moe.yaml`, …) | `qwen3_tts.yaml`, `voxcpm2.yaml`, … | Often default serve; parallel/offload YAML for heavy DiT |
 | **Nightly group** (`test-nightly.yml`) | **Omni Model Test** — `-m "full_model and omni"` | **TTS Model Test** — `-m "full_model and tts"` | **Diffusion X2I(&A&T)** *or* **Diffusion X2V** (see Step 3 table; same `diffusion` marker, different YAML group / file shard) |
 | **L4 pressure** | Expansion per modality/model as needed | Expansion + accuracy/perf in TTS group | X2I: merge feature combos per [#1832](https://github.com/vllm-project/vllm-omni/issues/1832); X2V: separate nightly group |

@@ -274,7 +274,6 @@ def test_text_to_video_001(omni_server, openai_client) -> None:

 **3. Cross-cutting rules**

- New `.py` files need the Omni SPDX header (`Copyright contributors to the vLLM-Omni project`, not `vLLM project`). `tests/` may keep stdlib `re`/`base64`; pickle is still banned unless the file is already on the pickle allowlist. Every collected `tests/**/test_*.py` needs a CI **level** mark and a **hardware** mark/helper (`check-test-ci-coverage` runs locally; GHA skips it). Do not grow `allowed_files` to land a test. Policy: [docs/contributing/README.md](../../../docs/contributing/README.md#linting).
 - Reuse existing fixtures for the chosen scenario; do not mix “online client” assumptions into offline `OmniRunner` tests without a clear reason.
 - Avoid external network dependency in assertions unless the scenario is explicitly “online serving” or doc examples that require a model hub (then align with CI secrets/cache).
 - Keep **one test function = one intent** (one modality combo, one endpoint contract, or one acceleration combo).
@@ -79,6 +79,8 @@
 /vllm_omni/model_executor/models/ @tzhouam @gcanlin @Sy0307 @amy-why-3459 @linyueqian
 /vllm_omni/model_extras/ @tzhouam @gcanlin @princepride
 /vllm_omni/plugins/ @gcanlin @tjtanaa @xuechendi
+# Config override within model_executor — docs/design/module/vllm_omni_config.md
+/vllm_omni/model_executor/stage_configs/ @lishunyang12 @alex-jw-brooks

 # Execution platforms (hardware backends) — docs/design/module/execution_platforms.md
 /vllm_omni/platforms/ @gcanlin @tjtanaa @xuechendi
@@ -83,7 +83,7 @@ body:

      omni = Omni(
          model="Qwen/Qwen-Image",
-          deploy_config="/path/to/deploy_config.yaml",
+          stage_configs_path="/path/to/stage_configs.yaml",
      )

      prompts = [{"prompt": "A scenic watercolor painting of a lighthouse at sunset"}]
@@ -45,7 +45,7 @@ pull_request_rules:
        > # For mypy (substitute "3.10" with the failing version if needed)
        > pre-commit run --hook-stage manual mypy-3.10
        > # For markdownlint
-        > pre-commit run markdownlint-cli2
+        > pre-commit run --hook-stage manual markdownlint
        > ```
        > </details>

@@ -24,7 +24,9 @@ jobs:
          python-version: "3.12"
          cache: 'pip'
      - uses: pre-commit/action@v3.0.1
-        # Don't run historical-debt hooks against the whole tree in CI yet.
-        # They still run locally on changed files.
+        # Don't run the pytest mark check against everything in the CI
+        # for now since a lot of files are still missing them. This check
+        # is used to help contributors remember to add the marks when they
+        # commit.
        env:
-          SKIP: check-test-ci-coverage,markdownlint-cli2,shellcheck,check-spdx-header,mypy-3.10
+          SKIP: check-test-ci-coverage
@@ -242,9 +242,9 @@ data/
 datasets/
 *.csv
 *.json
-!recipes/cosmos3/negative_prompt.json
 !tests/dfx/perf/tests/*.json
 !apps/ComfyUI-vLLM-Omni/example_workflows/*.json
+!tests/assets/soulxsinger/*.json
 *.jsonl
 *.parquet

@@ -278,6 +278,3 @@ tests/.ci_generated/

 # Local Lance precision-matching dump scripts (not part of the repo)
 lance_compare/
-
-# Linting binaries downloaded by local pre-commit hooks
-shellcheck*/
@@ -1,17 +0,0 @@
-# Keep these rules aligned with vLLM so MkDocs Material syntax is tolerated.
-MD007:
-  indent: 4
-MD013: false
-# GitHub READMEs start with a centered logo, not an H1.
-MD041: false
-MD024:
-  siblings_only: true
-MD025:
-  # Allow front matter title to be different from the first heading in the document.
-  front_matter_title: ""
-MD031:
-  list_items: false
-MD033: false
-MD046: false
-MD052: false
-MD059: false
@@ -24,7 +24,7 @@ repos:
    - id: ruff-format

  - repo: https://github.com/crate-ci/typos
-    rev: v1.49.0
+    rev: typos-dict-v0.13.13
    hooks:
      - id: typos
        # only for staged files
@@ -38,19 +38,7 @@ repos:
      - id: actionlint
        files: ^\.github/workflows/.*\.ya?ml$

-  - repo: https://github.com/DavidAnson/markdownlint-cli2
-    rev: v0.23.2
-    hooks:
-      - id: markdownlint-cli2
-        language_version: lts
-        args: [--fix]
-        files: (^docs/|^recipes/|(^|/)README\.md$|^CONTRIBUTING\.md$)
-        # Agent skill docs and CLAUDE.md are not user-facing docs/READMEs.
-        exclude: (^|/)CLAUDE\.md$|^\.claude/|^\.cursor/

-  # Keep `local` last so `suggestion` stays the final hook. Autofix repos
-  # (ruff, typos, markdownlint, trailing-whitespace, etc.) must run first;
-  # otherwise their "files were modified" output displaces the SKIP tip.
  - repo: local
    hooks:
    - id: signoff-commit
@@ -66,45 +54,6 @@ repos:
      verbose: true
      stages: [commit-msg]

-    # TODO: Use https://github.com/pre-commit/mirrors-mypy when mypy setup
-    # is less awkward. Local wrapper groups files so follow_imports=skip on
-    # tests does not leak into library code.
-    # mypy-3.10 runs on git commit (changed files). CI SKIPs it because
-    # --all-files is not clean yet. Extra versions are manual-stage only
-    # (not in default `pre-commit run --all-files`):
-    #   pre-commit run --hook-stage manual mypy-3.12
-    - id: mypy-3.10
-      name: Run mypy for Python 3.10
-      entry: python tools/pre_commit/mypy.py "3.10"
-      <<: &mypy_common
-        language: python
-        types_or: [python, pyi]
-        require_serial: true
-        additional_dependencies:
-          - mypy==1.11.1
-          - regex
-          - types-cachetools
-          - types-setuptools
-          - types-PyYAML
-          - types-requests
-          - types-torch
-          - pydantic
-    - id: mypy-3.11
-      name: Run mypy for Python 3.11
-      entry: python tools/pre_commit/mypy.py "3.11"
-      <<: *mypy_common
-      stages: [manual]
-    - id: mypy-3.12
-      name: Run mypy for Python 3.12
-      entry: python tools/pre_commit/mypy.py "3.12"
-      <<: *mypy_common
-      stages: [manual]
-    - id: mypy-3.13
-      name: Run mypy for Python 3.13
-      entry: python tools/pre_commit/mypy.py "3.13"
-      <<: *mypy_common
-      stages: [manual]
-
    - id: check-test-ci-coverage
      name: Ensure test files have pytestmarks
      entry: python tools/pre_commit/check_test_marks.py
@@ -122,45 +71,7 @@ repos:
      # pre-commit hides output from passing hooks unless the hook is verbose.
      verbose: true

-    - id: shellcheck
-      name: Lint shell scripts
-      # language: script breaks on Windows (shebang path loses slashes).
-      # Invoke the vLLM-style wrapper with bash so Linux CI and Win/Git Bash work.
-      entry: bash
-      args: [tools/pre_commit/shellcheck.sh]
-      language: system
-      types: [shell]
-
-    - id: check-spdx-header
-      name: Check SPDX headers
-      entry: python tools/pre_commit/check_spdx_header.py
-      language: python
-      types_or: [python, pyi, rust, proto, shell]
-      files: \.(py|pyi|rs|proto|sh)$
-
-    - id: check-forbidden-imports
-      name: Check forbidden imports
-      entry: python tools/pre_commit/check_forbidden_imports.py
-      language: python
-      types: [python]
-      additional_dependencies: [regex]
-
-    - id: check-torch-cuda-call
-      name: Prevent new torch.cuda API calls
-      entry: python tools/pre_commit/check_torch_cuda.py
-      language: python
-      types: [python]
-      additional_dependencies: [regex]
-
-    - id: check-buildkite
-      name: Validate Buildkite Pipelines
-      entry: python tools/pre_commit/check_buildkite.py
-      language: python
-      files: ^\.buildkite/.*\.ya?ml$
-      additional_dependencies: [pyyaml, check-jsonschema==0.38.0]
-
-    # Keep `suggestion` as the final hook. Run after autofix hooks so the
-    # bypass/SKIP tip is not displaced.
+    # Keep `suggestion` last
    - id: suggestion
      name: Suggestion
      entry: bash -c 'echo "To bypass all the pre-commit hooks, add --no-verify to git commit. To skip a specific hook, prefix the commit command with SKIP=<hook-id>."'
@@ -168,3 +79,10 @@ repos:
      verbose: true
      pass_filenames: false
    # Insert new entries above the `suggestion` entry
+
+    - id: check-pickle-imports
+      name: Prevent new pickle/cloudpickle imports
+      entry: python tools/pre_commit/check_pickle_imports.py
+      language: python
+      types: [python]
+      additional_dependencies: [regex]
@@ -1,11 +1,5 @@
 # Contributing to vLLM-Omni

-You may find information about contributing to vLLM-Omni on [Contributing](https://vllm-omni.readthedocs.io/en/latest/contributing/).
-
-Local `pre-commit` gates (SPDX, forbidden imports, `torch.cuda`, shellcheck,
-mypy, test marks, TTS adapter ratchet, markdownlint, Buildkite schema, and
-how to extend allowlists) are documented in the
-[Linting](https://vllm-omni.readthedocs.io/en/latest/contributing/#linting)
-section of that guide.
+You may find information about contributing to vLLM-Omni on [Contributing](https://vllm-omni.readthedocs.io/en/latest/contributing/)

 Before submitting a PR, run the [precheck-pr skill](https://github.com/vllm-project/vllm-omni/blob/main/.claude/skills/precheck-pr/SKILL.md) with the code agent for a self-check against project conventions.
@@ -12,10 +12,10 @@ Easy, fast, and cheap omni-modality model serving for everyone
 | <a href="https://vllm-omni.readthedocs.io/en/latest/"><b>Documentation</b></a> | <a href="https://deepwiki.com/vllm-project/vllm-omni"><b>DeepWiki</b></a> | <a href="https://discuss.vllm.ai"><b>User Forum</b></a> | <a href="https://slack.vllm.ai"><b>Developer Slack</b></a> | <a href="docs/assets/WeChat.jpg"><b>WeChat</b></a> | <a href="https://arxiv.org/abs/2602.02204"><b>Paper</b></a> | <a href="https://docs.google.com/presentation/d/1aPj0OGl_-ZVoib-Qne5dGDAlrRFB-PdHl6E-EE99g8E/edit?usp=sharing"><b>Slides</b></a> |
 </p>

+
 ---

 *Latest News* 🔥
-
 - [2026/08] [VeRL-Omni](https://github.com/verl-project/verl-omni) `v0.2.0` is released: faster diffusion RL powered by vLLM-Omni (request-level/step-wise batching with FA3), rebuilt Qwen3-Omni multimodal training (DPO & GSPO), plus LTX-2.3, Qwen-Image-Edit support and more. See the [release notes](https://github.com/verl-project/verl-omni/releases/tag/v0.2.0).
 - [2026/08] We released [0.26.0](https://github.com/vllm-project/vllm-omni/releases/tag/v0.26.0) - aligned with the vLLM 0.26 release line, featuring [MiniMax H3](recipes/MiniMaxAI/MiniMax-H3.md) joint video/audio generation, an experimental full-duplex realtime runtime for [MiniCPM-o 4.5](recipes/OpenBMB/MiniCPM-o-4_5.md), distributed layerwise diffusion offload, and broader model, hardware, streaming, TTS, and quantization support.
 - [2026/07] We released [0.24.0](https://github.com/vllm-project/vllm-omni/releases/tag/v0.24.0) - aligned with the vLLM 0.24 release line, expanding production-ready coverage across TTS, speech, diffusion, image/video generation, and robot-policy serving, with major Omni stage runtime refactoring, diffusion request-level batching, async output materialization, quantization/cache/memory improvements, and broad CUDA/ROCm/XPU/NPU support.
@@ -89,18 +89,11 @@ If you use vLLM-Omni for your research, please cite our [paper](https://arxiv.or
 ```

 ## Join the Community
-
 Feel free to ask questions, provide feedbacks and discuss with fellow users of vLLM-Omni in `#sig-omni` slack channel at [slack.vllm.ai](https://slack.vllm.ai) or vLLM user forum at [discuss.vllm.ai](https://discuss.vllm.ai).

 ## Star History

-<a href="https://www.star-history.com/?repos=vllm-project%2Fvllm-omni&type=date&legend=top-left">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=vllm-project/vllm-omni&type=date&theme=dark&legend=top-left&sealed_token=ExgLDZJoQEg27Zfhhut2LqN0GYO6Fw2PWLwPE6JYBUp2BgM3hmsYlwaIVopnUEfbRXidQ4nisumrTdKYydiKhy1SZXipw47qY2_tiUDhCpsPXeXtPuEVKVzBwKs3pw0tiHsJgtSfwXx5yjHXck0Y2SblzFWeJYCkTe1WLGTbUAOIETjXXQJjyCGZvKz5" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=vllm-project/vllm-omni&type=date&legend=top-left&sealed_token=ExgLDZJoQEg27Zfhhut2LqN0GYO6Fw2PWLwPE6JYBUp2BgM3hmsYlwaIVopnUEfbRXidQ4nisumrTdKYydiKhy1SZXipw47qY2_tiUDhCpsPXeXtPuEVKVzBwKs3pw0tiHsJgtSfwXx5yjHXck0Y2SblzFWeJYCkTe1WLGTbUAOIETjXXQJjyCGZvKz5" />
-    <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=vllm-project/vllm-omni&type=date&legend=top-left&sealed_token=ExgLDZJoQEg27Zfhhut2LqN0GYO6Fw2PWLwPE6JYBUp2BgM3hmsYlwaIVopnUEfbRXidQ4nisumrTdKYydiKhy1SZXipw47qY2_tiUDhCpsPXeXtPuEVKVzBwKs3pw0tiHsJgtSfwXx5yjHXck0Y2SblzFWeJYCkTe1WLGTbUAOIETjXXQJjyCGZvKz5" />
-  </picture>
-</a>
+[![Star History Chart](https://api.star-history.com/svg?repos=vllm-project/vllm-omni&type=date&legend=top-left)](https://www.star-history.com/#vllm-project/vllm-omni&type=date&legend=top-left)

 ## License

@@ -18,8 +18,8 @@ vllm serve Qwen/Qwen3-TTS-12Hz-1.7B-Base --omni --port 8000
 ```

 The server auto-loads its Deploy YAML from `vllm_omni/deploy/qwen3_tts.yaml`
-(Pipeline + Deploy schema introduced in #2383). No explicit `--deploy-config`
-flag is needed for a registered model.
+(Pipeline + Deploy schema introduced in #2383). No `--stage-configs-path` or
+`--deploy-config` flag is needed for any registered model.

 ### 2. Run the benchmark (`vllm bench serve --omni`)

@@ -113,7 +113,6 @@ nav:
    - Feature Design:
      - Runtime and Stage Execution:
        - Disaggregated Inference: design/feature/disaggregated_inference.md
-        - Host Weight Runtime: design/feature/host_weight_runtime.md
        - Async Chunk: design/feature/async_chunk.md
        - Async Diffusion Output: design/feature/async_diffusion_output.md
        - Async Omni Output Materialization: design/feature/omni_async_output_materialization.md
@@ -170,7 +169,6 @@ nav:
        - Offloader: design/module/diffusion/offloader.md
      - Execution Platforms: design/module/execution_platforms.md
      - Cache Management: design/module/cache_management.md
-      - Host Weight Runtime: design/module/host_weight_runtime.md
      - Quantization: design/module/quantization.md
      - Observability: design/module/observability.md
      - Profiling: design/module/profiling.md
@@ -114,6 +114,10 @@ Configuration classes.
 - [vllm_omni.model_executor.models.qwen3_tts.tokenizer_25hz.configuration_qwen3_tts_tokenizer_v1.Qwen3TTSTokenizerV1DecoderDiTConfig][]
 - [vllm_omni.model_executor.models.qwen3_tts.tokenizer_25hz.configuration_qwen3_tts_tokenizer_v1.Qwen3TTSTokenizerV1EncoderConfig][]
 - [vllm_omni.transformers_utils.configs.cosyvoice3.CosyVoice3Config][]
+- [vllm_omni.transformers_utils.configs.mammoth_moda2.Mammothmoda2Config][]
+- [vllm_omni.transformers_utils.configs.mammoth_moda2.Mammothmoda2Qwen2_5_VLConfig][]
+- [vllm_omni.transformers_utils.configs.mammoth_moda2.Mammothmoda2Qwen2_5_VLTextConfig][]
+- [vllm_omni.transformers_utils.configs.mammoth_moda2.Mammothmoda2Qwen2_5_VLVisionConfig][]
 - [vllm_omni.transformers_utils.configs.omnivoice.OmniVoiceConfig][]
 - [vllm_omni.transformers_utils.configs.voxcpm2.VoxCPM2Config][]

@@ -4,12 +4,11 @@ This section lists the most common options for running vLLM-Omni.

 For options within a vLLM Engine, please refer to the [vLLM 0.26 configuration guide](https://docs.vllm.ai/en/v0.26.0/configuration/index.html).

-Each model defines fixed topology in a registered `PipelineConfig` and runtime
-overrides in a deploy YAML.
+Currently, the main options are maintained by stage configs for each model.

 For a specific example, see the [Qwen2.5-Omni deploy config](gh-file:vllm_omni/deploy/qwen2_5_omni.yaml). The matching frozen pipeline topology lives at [vllm_omni/model_executor/models/qwen2_5_omni/pipeline.py](gh-file:vllm_omni/model_executor/models/qwen2_5_omni/pipeline.py).

-For an introduction, see [Pipeline and deploy configurations](./stage_configs.md).
+For introduction, please check [Introduction for stage config](./stage_configs.md)

 ## Memory Configuration

@@ -1,6 +1,6 @@
 # Composable parallel strategies

-In vLLM-Omni, the `composable_parallel` system layers a declarative *parallel strategy* on top of the registered pipeline and deploy config. A strategy YAML maps each pipeline stage (by its `model_stage` name) to a stack of axis declarations — one per parallelism dimension — that the engine translates into per-stage parallel sizing (`tensor_parallel_size`, `data_parallel_size`, `pipeline_parallel_size`, expert-parallel toggle, replica count) and, when relevant, an orchestrator-wide load-balancer policy.
+In vLLM-Omni, the `composable_parallel` system layers a declarative *parallel strategy* on top of the existing stage configs. A strategy YAML maps each pipeline stage (by its `model_stage` name) to a stack of axis declarations — one per parallelism dimension — that the engine translates into per-stage parallel sizing (`tensor_parallel_size`, `data_parallel_size`, `pipeline_parallel_size`, expert-parallel toggle, replica count) and, when relevant, an orchestrator-wide load-balancer policy.

 Strategies are intentionally narrow: each one only writes the axes it declares, leaving every other engine arg untouched. This makes a strategy file a small, reusable overlay you can swap independently of the deploy YAML (see `configuration/stage_configs.md`).

@@ -195,7 +195,7 @@ Because `omni_lb_policy` is read once at `AsyncOmniEngine` construction — not

 Default: no default — required for every entry under `strategies:`.

-Strategy keys MUST be `model_stage` *names* (strings), the same labels defined by [`StagePipelineConfig.model_stage`](stage_configs.md#pipeline-configuration). Integer `stage_id` values are not accepted; the resolver matches on `model_stage` exactly (`_resolve_stage` in `vllm_omni/config/composable_parallel/apply.py`).
+Strategy keys MUST be `model_stage` *names* (strings), the same labels stage configs use for `engine_args.model_stage` (see [`model_stage` in `stage_configs.md`](stage_configs.md#engine_argsmodel_stage)). Integer `stage_id` values are not accepted; the resolver matches on `model_stage` exactly (`_resolve_stage` in `vllm_omni/config/composable_parallel/apply.py`).

 ## Common pitfalls

@@ -80,15 +80,19 @@ When multiple stages share the same GPU, you must ensure the sum of their `gpu_m

 **Example: Two stages on GPU 0**
 ```yaml
-stages:
+stage_args:
  - stage_id: 0
-    devices: "0"
-    gpu_memory_utilization: 0.6  # Uses 60% of GPU 0
+    runtime:
+      devices: "0"
+    engine_args:
+      gpu_memory_utilization: 0.6  # Uses 60% of GPU 0

  - stage_id: 1
-    devices: "0"
-    gpu_memory_utilization: 0.3  # Uses 30% of GPU 0
-    # Total: 90% of GPU 0 (safe, leaves 10% buffer)
+    runtime:
+      devices: "0"
+    engine_args:
+      gpu_memory_utilization: 0.3  # Uses 30% of GPU 0
+      # Total: 90% of GPU 0 (safe, leaves 10% buffer)
 ```

 **Important:** If stages run on different GPUs, each can use up to 1.0 independently.
@@ -99,12 +103,14 @@ When using `tensor_parallel_size > 1`, the model is split across multiple GPUs,

 **Example: 2-way tensor parallelism**
 ```yaml
-stages:
+stage_args:
  - stage_id: 0
-    devices: "0,1"  # Uses both GPUs
-    tensor_parallel_size: 2
-    gpu_memory_utilization: 0.6  # 60% per GPU
-    # Model is split, so each GPU uses ~30% of model memory
+    runtime:
+      devices: "0,1"  # Uses both GPUs
+    engine_args:
+      tensor_parallel_size: 2
+      gpu_memory_utilization: 0.6  # 60% per GPU
+      # Model is split, so each GPU uses ~30% of model memory
 ```

 ## Examples
@@ -112,25 +118,27 @@ stages:
 ### Qwen3-Omni-MoE on 2x H100-80GB

 ```yaml
-base_config: /path/to/vllm_omni/deploy/qwen3_omni_moe.yaml
-
-stages:
+stage_args:
  - stage_id: 0  # Thinker stage with TP=2
-    devices: "0,1"
-    tensor_parallel_size: 2
-    gpu_memory_utilization: 0.6  # 48GB per GPU
+    runtime:
+      devices: "0,1"
+    engine_args:
+      tensor_parallel_size: 2
+      gpu_memory_utilization: 0.6  # 48GB per GPU

  - stage_id: 1  # Talker stage
-    devices: "1"
-    gpu_memory_utilization: 0.3  # 24GB on GPU 1
+    runtime:
+      devices: "1"
+    engine_args:
+      gpu_memory_utilization: 0.3  # 24GB on GPU 1

  - stage_id: 2  # Code2Wav stage
-    devices: "0"
-    gpu_memory_utilization: 0.1  # 8GB on GPU 0
+    runtime:
+      devices: "0"
+    engine_args:
+      gpu_memory_utilization: 0.1  # 8GB on GPU 0
 ```
-**Note:** Stage 0 uses GPUs 0 and 1, so the combined utilization is `0.7` on
-GPU 0 and `0.9` on GPU 1. Keep the sum of all resident stages below `1.0` on
-each device.
+**Note:** In this configuration, stages 0 and 2 share GPU 0, but they run at different times in the pipeline, so their memory usage doesn't overlap.

 ## Troubleshooting

@@ -3,46 +3,7 @@
 In vLLM-Omni, a model's `PipelineConfig` defines its fixed stage topology, while a deploy configuration controls how those stages run.

 !!! note
-    Default deploy config YAMLs (for example, `vllm_omni/deploy/qwen2_5_omni.yaml`, `vllm_omni/deploy/qwen3_omni_moe.yaml`, and `vllm_omni/deploy/qwen3_tts.yaml`) are bundled and loaded automatically when `--deploy-config` is omitted. The resolved pipeline selects its default through `default_deploy_config_name`.
-
-## Pipeline configuration
-
-`PipelineConfig` and its `StagePipelineConfig` entries are Python definitions
-owned by the model implementation and registered in `OMNI_PIPELINES`. They
-describe fixed model topology and are not accepted in deploy YAMLs.
-
-Common `PipelineConfig` fields include:
-
-| Field | Description |
-|-------|-------------|
-| `model_type` | Pipeline identifier used during model and config resolution. |
-| `default_deploy_config_name` | Bundled deploy YAML loaded when the user does not pass `deploy_config`. |
-| `model_arch` | Default Hugging Face architecture for the pipeline. |
-| `hf_architectures` | Architecture names used to identify checkpoints whose `model_type` is shared. |
-| `hf_config_predicate` | Optional predicate used to select between pipelines with otherwise identical HF metadata. |
-| `diffusers_class_name` | Diffusers `_class_name` used to identify Diffusers-style repositories. |
-| `stages` | Ordered tuple of fixed `StagePipelineConfig` definitions. |
-
-Common `StagePipelineConfig` fields include:
-
-| Field | Description |
-|-------|-------------|
-| `stage_id` | Stable stage identifier. |
-| `model_stage` | Logical stage name used by runtime and strategy resolution. |
-| `execution_type` | `LLM_AR`, `LLM_GENERATION`, or `DIFFUSION`. |
-| `input_sources` | Upstream stage IDs that provide this stage's inputs. |
-| `final_output` / `final_output_type` | Whether the stage produces a user-visible output and its modality. |
-| `owns_tokenizer` | Whether this stage owns the pipeline tokenizer. |
-| `model_arch`, `hf_config_name` | Stage-specific model architecture and nested HF config selector. |
-| `engine_output_type` | Runtime output representation such as `text`, `latent`, or `audio`. |
-| `custom_process_input_func` | Processor applied to this stage's incoming payload. |
-| `custom_process_next_stage_input_func` | Processor used for full-payload handoff to the next stage. |
-| `async_chunk_process_next_stage_input_func` | Processor used for async chunk handoff. |
-| `sampling_constraints` | Model-owned sampling constraints that deploy defaults cannot override. |
-
-To add or change topology, define and register a new pipeline variant. Use
-deploy YAML only for runtime placement, resource sizing, connectors, and other
-deployment overrides.
+    Default deploy config YAMLs (for example, `vllm_omni/deploy/qwen2_5_omni.yaml`, `vllm_omni/deploy/qwen3_omni_moe.yaml`, and `vllm_omni/deploy/qwen3_tts.yaml`) are bundled and loaded automatically when `--deploy-config` is omitted. The model registry resolves the right pipeline and deploy YAML by `model_type`.

 ## Deploy configuration schema

@@ -52,53 +13,43 @@ The new deploy schema lives under `vllm_omni/deploy/` and is paired with a froze
 |-------|------|----------|---------|-------------|
 | `base_config` | str (path) | optional | — | Overlay parent (relative or absolute). `stages:` / `platforms:` deep-merged by stage_id; other scalars overlay-wins. Intended for user-authored overlays; prod yamls stay flat. |
 | `async_chunk` | bool | optional | `true` | Enable chunked streaming between stages. Pin to `false` if the pipeline runs end-to-end. |
-| `session_mode` | str | optional | `"turn"` | Session behavior. Use `"duplex"` only with a pipeline that enables duplex control. |
-| `active_stream_window` | int | optional | `0` | Number of active downstream stream slots; `0` preserves all-stream cycling. |
-| `duplex_session` | dict | optional | runtime defaults | Full-duplex session lifecycle, buffering, replay, and capacity limits. |
 | `connectors` | dict | optional | `null` | Named connector specs (`{name, extra}`). Referenced by each stage's `input_connectors` / `output_connectors`. See [Connector schema](#connector-schema). |
 | `edges` | list | optional | `null` | Explicit edge list for the KV transfer graph. Auto-derived from stage inputs if omitted. |
-| `stages` | list | optional | `[]` | Per-stage runtime overrides matched by `stage_id`. Pipeline stages are still created from `PipelineConfig` when this list is empty. |
+| `stages` | list | required | — | Per-stage engine args + wiring (see [Stage fields](#stage-fields)). |
 | `platforms` | dict | optional | `null` | Keyed by `npu` / `rocm` / `xpu`, each contains a `stages:` list with per-platform overrides applied on top of the CUDA defaults. |
 | `pipeline` | str | optional | `null` | Override the auto-detected pipeline registry key (used for structural variants like `qwen2_5_omni_thinker_only`). |
-| `trust_remote_code` | bool \| null | optional | `null` | **Pipeline-wide.** Trust HF remote code on model load; applies to every stage when specified. |
+| `trust_remote_code` | bool | optional | `true` | **Pipeline-wide.** Trust HF remote code on model load; applies to every stage. |
 | `distributed_executor_backend` | str \| null | optional | `null` | **Pipeline-wide.** Distributed executor backend forwarded to vLLM (`"mp"`, `"ray"`, `"external_launcher"`). If omitted, vLLM auto-selects backend from runtime topology. |
 | `dtype` | str \| null | optional | `null` | **Pipeline-wide.** Model dtype for every stage. |
 | `quantization` | str \| null | optional | `null` | **Pipeline-wide.** Quantization method for every stage. |
-| `enable_prefix_caching` | bool \| null | optional | `null` | **Pipeline-wide.** Prefix cache toggle applied to every stage when specified. |
+| `enable_prefix_caching` | bool | optional | `false` | **Pipeline-wide.** Prefix cache toggle applied to every stage. |
 | `enable_chunked_prefill` | bool \| null | optional | `null` | **Pipeline-wide.** Chunked prefill toggle applied to every stage. |
-| `data_parallel_size` | int \| null | optional | `null` | **Pipeline-wide.** DP degree for every stage. |
-| `pipeline_parallel_size` | int \| null | optional | `null` | **Pipeline-wide.** PP degree for every stage. |
-| `custom_voice_dir` | str \| null | optional | `null` | **Pipeline-wide.** Directory containing custom voice profiles for supported TTS models. |
+| `data_parallel_size` | int | optional | `1` | **Pipeline-wide.** DP degree for every stage. |
+| `pipeline_parallel_size` | int | optional | `1` | **Pipeline-wide.** PP degree for every stage. |

-For fields whose deploy default is `null`, the deploy layer contributes no
-override. The effective value may still come from a platform section, an
-explicit CLI or stage override, or the downstream vLLM engine default.
-
-Note: for the diffusion path, an omitted `distributed_executor_backend` selects
-`uni` on a single GPU (in-process worker, no MessageQueue / `/dev/shm` output
-segments) and `mp` when `num_gpus > 1`. Set `mp` explicitly to keep a worker
-subprocess on one GPU. `ray` / `external_launcher` are not fully supported yet.
+Note: for diffusion path, `distributed_executor_backend` currently defaults to
+`mp`, and `ray` / `external_launcher` are not fully supported yet.

 ### Stage fields

-Each entry under `stages:` accepts any `StageDeployConfig` field directly (no nested `engine_args:`). Only fields whose value legitimately varies across stages live here; pipeline-wide settings (trust_remote_code, distributed_executor_backend, dtype, quantization, prefix/chunked prefill, DP/PP sizes) are declared at the top level and applied to every stage. Unknown keys fall through to `engine_extras:` and are forwarded to the engine. Frequently used fields are listed below; the source-of-truth schema is `StageDeployConfig` in `vllm_omni/config/stage_config.py`.
+Each entry under `stages:` accepts any `StageDeployConfig` field directly (no nested `engine_args:`). Only fields whose value legitimately varies across stages live here; pipeline-wide settings (trust_remote_code, distributed_executor_backend, dtype, quantization, prefix/chunked prefill, DP/PP sizes) are declared at the top level and applied to every stage. Unknown keys fall through to `engine_extras:` and are forwarded to the engine.

 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
 | `stage_id` | int | required | — | Stage identity; matched against `PipelineConfig.stages[*].stage_id`. |
-| `max_num_seqs` | int \| null | optional | `null` | Max concurrent sequences per stage. |
-| `gpu_memory_utilization` | float \| null | optional | `null` | Per-stage total memory target; used for automatic KV-cache sizing. |
+| `max_num_seqs` | int | optional | `64` | Max concurrent sequences per stage. |
+| `gpu_memory_utilization` | float | optional | `0.9` | Per-stage total memory target; used for automatic KV-cache sizing. |
 | `kv_cache_memory_bytes` | int \| null | optional | `null` | Explicit per-rank KV-cache budget in bytes; overrides automatic sizing. |
-| `tensor_parallel_size` | int \| null | optional | `null` | TP degree for this stage. |
-| `enforce_eager` | bool \| null | optional | `null` | Disable CUDA graphs. |
-| `max_num_batched_tokens` | int \| null | optional | `null` | Per-stage prefill/token budget; also contributes to the native maximum in-flight token limit. |
+| `tensor_parallel_size` | int | optional | `1` | TP degree for this stage. |
+| `enforce_eager` | bool | optional | `false` | Disable CUDA graphs. |
+| `max_num_batched_tokens` | int | optional | `32768` | Per-stage prefill/token budget; also contributes to the native maximum in-flight token limit. |
 | `max_model_len` | int \| null | optional | `null` | Per-sequence context or KV length; `-1` enables native cache-capacity auto-fitting, while values above the HF default auto-set `VLLM_ALLOW_LONG_MAX_MODEL_LEN=1`. |
 | `async_scheduling` | bool \| null | optional | `null` | Per-stage async scheduling toggle. |
-| `devices` | str \| null | optional | `null` | Device list assigned to this stage. |
+| `devices` | str | optional | `"0"` | `CUDA_VISIBLE_DEVICES`-style device list. |
 | `output_connectors` | dict \| null | optional | `null` | Keyed by `to_stage_<n>`; values are names registered under top-level `connectors:`. |
 | `input_connectors` | dict \| null | optional | `null` | Keyed by `from_stage_<n>`; values are names registered under top-level `connectors:`. |
 | `default_sampling_params` | dict \| null | optional | `null` | Baseline sampling params. Deep-merged with pipeline `sampling_constraints` (pipeline wins). |
-| `engine_extras` | dict | optional | `{}` | Catch-all for engine fields not listed above; deep-merged across overlays and forwarded to the stage engine. |
+| `engine_extras` | dict | optional | `{}` | Catch-all for keys not listed above; deep-merged across overlays. Also carries per-stage overrides of pipeline-wide settings (e.g. stage-specific `dtype`). |

 ### Connector schema

@@ -110,7 +61,7 @@ connectors:
    name: <ConnectorClassName>     # required — class registered in vllm_omni.distributed
    extra:                         # optional — forwarded to the connector's __init__
      <key>: <value>
-      # Additional connector-specific options
+      ...
 ```

 | Connector class | Use case | `extra` keys |
@@ -285,3 +236,288 @@ vllm serve Qwen/Qwen2.5-Omni-7B --omni --port 8091 --deploy-config /path/to/depl

 !!! important
    We are actively iterating on the definition of deployment configurations, and we welcome feedback from users and developers.
+
+## Legacy stage configuration reference
+
+The remainder of this page documents the deprecated `stage_args` schema for models that have not migrated to deploy configurations. The following historical Qwen2.5-Omni configuration illustrates that schema; current Qwen2.5-Omni deployments should use `vllm_omni/deploy/qwen2_5_omni.yaml` instead.
+
+```python
+# Historical stage configuration for Qwen2.5-Omni.
+stage_args:
+  - stage_id: 0 # mark the unique id for each stage
+    runtime: # The disaggregated configuration
+      process: true  # Run this stage in a separate process
+      devices: "0" # Logical device index for this stage (mapped through CUDA_VISIBLE_DEVICES / ASCEND_RT_VISIBLE_DEVICES if set)
+    engine_args: # Engine arguments for a certain engine
+      model_stage: thinker
+      max_num_seqs: 1
+      model_arch: Qwen2_5OmniForConditionalGeneration # The model implementation registered in model_executor/models/registry.py
+      worker_type: ar # The specific worker used
+      scheduler_cls: vllm_omni.core.sched.omni_ar_scheduler.OmniARScheduler # The specific scehduler used
+      gpu_memory_utilization: 0.8 # The gpu memory allocation for the stage within a single chip
+      enforce_eager: true  # Now we only support eager mode
+      trust_remote_code: true # Needed by huggingface config parsing
+      engine_output_type: latent  # It claims that the stage will input latent hiddenstates besides token ids
+      enable_prefix_caching: false # For request with hiddenstates output, the prefix caching is not supported now
+    is_comprehension: true # If the stage is a text or multimodal comprehension module. If it is, the AsyncOmni will use its tokenizer as default
+    final_output: true # If the stage has output as part of final outputs. If it is false, which means that the stage only works as a intermediate role.
+    final_output_type: text # What is the final output type. It can be text and audio now.
+    default_sampling_params: # sampling parameters for the stage. Their meaning aligns with vLLM.
+      temperature: 0.0
+      top_p: 1.0
+      top_k: -1
+      max_tokens: 2048
+      seed: 42
+      detokenize: True
+      repetition_penalty: 1.1
+  - stage_id: 1
+    runtime:
+      process: true
+      devices: "1"
+    engine_args:
+      model_stage: talker
+      max_num_seqs: 3
+      model_arch: Qwen2_5OmniForConditionalGeneration
+      worker_type: ar
+      scheduler_cls: vllm_omni.core.sched.omni_ar_scheduler.OmniARScheduler
+      gpu_memory_utilization: 0.8
+      enforce_eager: true
+      trust_remote_code: true
+      enable_prefix_caching: false
+      engine_output_type: latent
+    engine_input_source: [0]
+    default_sampling_params:
+      temperature: 0.9
+      top_p: 0.8
+      top_k: 40
+      max_tokens: 2048
+      seed: 42
+      detokenize: True
+      repetition_penalty: 1.05
+      stop_token_ids: [8294]
+  - stage_id: 2
+    runtime:
+      process: true
+      devices: "0"            # Example: use a different GPU than the previous stage; use "0" if single GPU
+    engine_args:
+      model_stage: code2wav
+      max_num_seqs: 1
+      model_arch: Qwen2_5OmniForConditionalGeneration
+      worker_type: generation
+      scheduler_cls: vllm_omni.core.sched.omni_generation_scheduler.OmniGenerationScheduler
+      gpu_memory_utilization: 0.15
+      enforce_eager: true
+      trust_remote_code: true
+      enable_prefix_caching: false
+      engine_output_type: audio
+    engine_input_source: [1]
+    final_output: true
+    final_output_type: audio
+    default_sampling_params:
+      temperature: 0.0
+      top_p: 1.0
+      top_k: -1
+      max_tokens: 2048
+      seed: 42
+      detokenize: True
+      repetition_penalty: 1.1
+
+# Top-level runtime config (concise): default windows and stage edges
+runtime:
+  enabled: true
+
+  edges:
+    - from: 0                   # thinker → talker: trigger only after receiving full input (-1)
+      to: 1
+    - from: 1                   # talker → code2wav: trigger only after receiving full input (-1)
+      to: 2
+
+```
+
+## Legacy stage configuration arguments
+
+Each stage in the `stage_args` list contains the following configuration options:
+
+### `stage_id`
+
+A unique identifier for each stage in the multi-stage pipeline. Stages are numbered sequentially starting from 0, and this ID is used to reference stages in inter-stage dependencies (e.g., `engine_input_source`).
+
+### `prompt_expand_func` (Optional)
+
+A custom Python function hook for the LLM stage (Stage 0) that expands a single incoming prompt object into multiple prompts. This is primarily used for multi-modal Classifier-Free Guidance (CFG), where it generates the necessary companion requests (like a negative text prompt) and tags them with internal roles (e.g., `cfg_text`). This ensures the upstream LLM generates the needed contextual hidden states for both the conditional and unconditional generations simultaneously.
+
+### `cfg_kv_collect_func` (Optional)
+
+A custom Python function hook for downstream diffusion stages (Stage 1+) to collect, map, and process the KV caches transferred from the companion requests fired by `prompt_expand_func`. It aggregates the hidden condition states cleanly (e.g., binding them as `cfg_text_past_key_values` and `cfg_text_kv_metadata`), allowing the diffusion runtime to perform CFG smoothly without redundantly evaluating text paths on the DiT workers.
+
+### `runtime`
+
+Configuration for disaggregated execution of the stage, controlling how the stage is deployed and executed.
+
+#### `runtime.process`
+
+Whether to run this stage in a separate process. When set to `true`, the stage will be executed in an isolated process, enabling better resource isolation and parallel execution across different stages. This is essential for multi-GPU deployments where different stages run on different devices.
+
+Default: `true`
+
+#### `runtime.devices`
+
+Logical device indices for this stage, specified as a string. Values are **logical indices** (`0`, `1`, `2`, ...) — not physical GPU IDs — and are mapped through the platform's visibility env var (`CUDA_VISIBLE_DEVICES` on CUDA, `ASCEND_RT_VISIBLE_DEVICES` on NPU) before being applied via `torch.cuda.set_device()` (or the equivalent).
+
+Example: if `CUDA_VISIBLE_DEVICES=0,2,4` is set in the environment, then `devices: "0"` selects physical GPU 0 (the first visible), `devices: "1"` selects physical GPU 2, and `devices: "0,1"` makes physical GPUs 0 and 2 available to the stage. If no visibility env var is set, logical and physical IDs coincide.
+
+Default: `"0"`
+
+#### `engine_args.max_num_seqs`
+
+The maximum number of sequences for concurrent processing in this stage. For
+LLM stages, this controls the vLLM scheduler's maximum concurrent sequences.
+For diffusion stages, this controls scheduler wave capacity in both request
+batch mode and step batch mode. `max_num_seqs: 1` is the serial/conservative
+path; values above `1` allow compatible requests to batch when the selected
+diffusion pipeline supports that batching mode.
+
+Default: `1`
+
+#### `engine_args.request_batch_max_wait_ms`
+
+The maximum time, in milliseconds, that a diffusion request-mode stage may wait
+before the first `schedule()` of a new scheduler wave so compatible requests can
+accumulate for request-level batching. This only applies to diffusion pipelines
+that support request-level batching with `step_execution` disabled.
+
+Use this together with `max_num_seqs > 1` for bursty serving traffic. `0`
+disables admission waiting and preserves the lowest first-request latency.
+For diffusion execution and batching tuning, see
+[Diffusion Execution Modes](../user_guide/diffusion/execution_modes.md).
+
+Default: `0.0`
+
+### `engine_args`
+
+Engine arguments for configuring the LLM engine, diffusion engine, or other engine types used by this stage.
+
+#### `engine_args.model_stage`
+
+The name identifier for this model stage within the multi-stage architecture. This is used internally to distinguish different stages of the same model (e.g., "thinker", "talker", "code2wav" in Qwen2.5-Omni).
+
+#### `engine_args.model_arch`
+
+The model architecture class name that is registered in `model_executor/models/registry.py`. This specifies which model implementation to use for this stage. The class must be registered in the model registry for vLLM-Omni to locate and instantiate it.
+
+#### `engine_args.worker_cls`
+
+The specific worker class to use for this stage. This determines how the model computations are executed. Examples include `vllm_omni.worker.gpu_ar_worker.GPUARWorker` for autoregressive stages and `vllm_omni.worker.gpu_generation_worker.GPUGenerationWorker` for diffusion-based stages.
+
+#### `engine_args.scheduler_cls`
+
+The scheduler class to use for this stage. The scheduler manages request queuing, batching, and execution order. Examples include `vllm_omni.core.sched.omni_ar_scheduler.OmniARScheduler` for standard stages and `vllm_omni.core.sched.omni_generation_scheduler.OmniGenerationScheduler` for diffusion stages.
+
+#### `engine_args.gpu_memory_utilization`
+
+The fraction of GPU memory to allocate for this stage within a single GPU chip. This is a value between 0.0 and 1.0, where 0.8 means 80% of the GPU memory will be used by this stage. This allows fine-grained control over memory allocation when multiple stages share the same GPU or when reserving memory for other operations.
+
+Default: `0.8`
+
+!!! tip "Memory Configuration Guide"
+    For detailed information on how to calculate memory requirements and properly configure `gpu_memory_utilization`, see the [GPU Memory Calculation and Configuration Guide](./gpu_memory_utilization.md).
+
+#### `engine_args.enforce_eager`
+
+Whether to enforce eager execution mode. When set to `true`, the engine will run in eager mode without using CUDA graphs or other compilation optimizations. Currently, vLLM-Omni only supports eager mode.
+
+Default: `true`
+
+#### `engine_args.trust_remote_code`
+
+Whether to trust remote code when loading models from Hugging Face. This is required for models that use custom code in their configuration files. Set to `true` when loading models that require custom model implementations.
+
+Default: `true`
+
+#### `engine_args.engine_output_type`
+
+Specifies the type of output produced by this stage's engine. This determines what kind of data flows to downstream stages. Possible values include `latent` (hidden states), `text` (tokenized text), and `audio` (audio waveforms). When set to `latent`, the stage outputs latent hidden states in addition to token IDs, which are consumed by downstream stages.
+
+Default: `latent`
+
+#### `engine_args.enable_prefix_caching`
+
+Whether to enable prefix caching for this stage. Prefix caching can improve performance by caching KV cache for common prompt prefixes. However, for requests that output hidden states (when `engine_output_type` is `latent`), prefix caching is not currently supported and should be set to `false`.
+
+Default: `false`
+
+### `is_comprehension`
+
+Whether this stage is a text or multimodal comprehension module. When set to `true`, the stage acts as a comprehension module that processes input text or multimodal content. If this is the first comprehension stage, `AsyncOmni` will use its tokenizer as the default tokenizer for the entire pipeline.
+
+Default: `true`
+
+### `final_output`
+
+Whether this stage produces output that is part of the final outputs returned to the user. When set to `false`, the stage only works as an intermediate stage, processing data that flows to downstream stages but not contributing directly to the final response.
+
+Default: `true`
+
+### `final_output_type`
+
+The type of final output produced by this stage. This specifies what format the output will be in when returned to the user. Currently supported values are `text` (for text generation) and `audio` (for audio generation).
+
+Default: `text`
+
+### `default_sampling_params`
+
+Default sampling parameters for this stage. These parameters control the generation behavior and align with vLLM's sampling parameter semantics. These defaults are used when no explicit sampling parameters are provided in the request.
+
+#### `default_sampling_params.temperature`
+
+Sampling temperature for controlling randomness. Lower values (e.g., 0.0) make the output more deterministic and focused, while higher values increase randomness.
+
+Default: `0.0`
+
+#### `default_sampling_params.top_p`
+
+Nucleus sampling parameter. Only tokens with cumulative probability mass up to `top_p` are considered. This helps filter out low-probability tokens while maintaining diversity.
+
+Default: `1.0`
+
+#### `default_sampling_params.top_k`
+
+Top-k sampling parameter. Only the top `k` most likely tokens are considered. Set to `-1` to disable top-k filtering and consider all tokens.
+
+Default: `-1`
+
+#### `default_sampling_params.max_tokens`
+
+Maximum number of tokens to generate in this stage. This limits the length of the output sequence.
+
+Default: `2048`
+
+#### `default_sampling_params.seed`
+
+Random seed for reproducible generation. When set, the random number generator will be initialized with this seed to ensure consistent outputs across runs.
+
+Default: `42`
+
+#### `default_sampling_params.detokenize`
+
+Whether to detokenize the output tokens into text. When set to `true`, token IDs are converted back to readable text strings.
+
+Default: `True`
+
+#### `default_sampling_params.repetition_penalty`
+
+Penalty applied to tokens that have already appeared in the generated sequence. Values greater than 1.0 discourage repetition, while values less than 1.0 encourage it. A value of 1.0 applies no penalty.
+
+Default: `1.1`
+
+### `tts_args` (TTS stages only)
+
+Configuration for Text-to-Speech specific parameters. This section is only applicable to TTS model stages (e.g., `qwen3_tts`).
+
+#### `tts_args.max_instructions_length`
+
+Maximum character length for voice style/emotion instructions. Instructions exceeding this limit will be rejected with a validation error.
+
+Default: `500`
+
+This value can be overridden at runtime using the `--tts-max-instructions-length` CLI parameter when starting the server.
@@ -46,7 +46,7 @@ class Omni:

    Args:
        model: Model name or path
-        deploy_config: Optional path to a deploy configuration
+        stage_configs: Optional stage configurations
        **kwargs: Additional arguments passed to the engine

    Example:
@@ -44,149 +44,6 @@ vLLM-Omni's `pre-commit` hooks will now run automatically every time you commit.
    pre-commit run --show-diff-on-failure --color=always --all-files  # runs on all files (short for --all-files)
    ```

-!!! warning
-    GitHub Actions `pre-commit` **skips** several local gates so a whole-tree
-    `--all-files` run stays green while historical debt is cleaned up. The
-    current `SKIP` list in
-    [`.github/workflows/pre-commit.yml`](https://github.com/vllm-project/vllm-omni/blob/main/.github/workflows/pre-commit.yml)
-    is `check-test-ci-coverage`, `markdownlint-cli2`, `shellcheck`,
-    `check-spdx-header`, and `mypy-3.10`. Those hooks still run on **your
-    commit** for changed files. A passing GitHub pre-commit check does not mean
-    they passed locally. Hooks **not** on that list (forbidden imports,
-    `torch.cuda`, TTS adapter ratchet, Buildkite schema, Ruff, typos, …) run in
-    both places.
-
-The hooks below are new relative to the previous Omni config (Ruff, typos,
-actionlint, YAML/whitespace, DCO sign-off, and the pickle-only checker were
-already there). `check-pickle-imports` is gone: pickle is now one rule inside
-`check-forbidden-imports`.
-
-| Hook id | Enforces | GitHub Actions |
-| ------- | -------- | -------------- |
-| `markdownlint-cli2` | Markdown in `docs/`, `recipes/`, `README.md`, `CONTRIBUTING.md` (not `.claude/` / `.cursor/` / `CLAUDE.md`) | skipped |
-| `mypy-3.10` | Type-check changed `vllm_omni/` files (model trees excluded). `tests/` uses `--follow-imports skip` | skipped |
-| `mypy-3.11` / `3.12` / `3.13` | Same checker, extra Python versions | not installed; `pre-commit run --hook-stage manual mypy-3.12` |
-| `check-test-ci-coverage` | Every `tests/**/test_*.py` has a CI level mark and a hardware mark/helper | skipped |
-| `check-tts-adapter-migration` | `self._tts_model_type` branches in `serving_speech.py` must not increase | runs |
-| `shellcheck` | `*.sh` quoting / undefined vars | skipped |
-| `check-spdx-header` | Omni SPDX header on `.py` / `.pyi` / `.sh` / `.rs` / `.proto` | skipped |
-| `check-forbidden-imports` | pickle, stdlib `re`/`base64`, Triton, TileLang, Hugging Face Hub download/API | runs |
-| `check-torch-cuda-call` | Direct `torch.cuda.*` helpers outside platform adapters | runs |
-| `check-buildkite` | `.buildkite/*.yml` against the Buildkite schema | runs |
-
-Related config (not a new hook id): Ruff `TID251` also bans `librosa` and several
-`torch.cuda.*` names; typos is pinned and ignores git-describe hashes (`+g` +
-hex) and NumPy `writeable`. Keep the `suggestion` hook last in
-`.pre-commit-config.yaml` so autofix output does not bury the SKIP tip.
-
-#### SPDX headers
-
-Source files must start with:
-
-```text
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-```
-
-Rust and proto files use `//` instead of `#`. Empty files are exempt. A stale
-`Copyright contributors to the vLLM project` line is **rewritten in place** to
-the Omni copyright; the hook then exits non-zero so you restage the rewrite.
-
-#### Forbidden imports
-
-Under `vllm_omni/`, do not use:
-
- stdlib `re` → `import regex as re`
- stdlib `base64` → `import pybase64` (or `import pybase64 as base64`)
- `pickle` / `cloudpickle` (also banned in most tests)
- `from huggingface_hub import snapshot_download` / `hf_hub_download` / `HfApi`
-  / similar → `vllm.transformers_utils.repo_utils`
- direct `triton` / `tilelang` → `vllm.triton_utils` / `vllm.tilelang_utils`
-
-`examples/`, `tests/`, `benchmarks/`, `apps/`, `docs/`, `tools/`, `scripts/`,
-`.buildkite/`, and `.github/` may keep stdlib `re` and `base64`
-(`_NON_LIBRARY_DIRS`). Pickle is stricter: tests are not exempt unless the
-file is on the pickle allowlist.
-
-#### `torch.cuda` call sites
-
-Prefer `current_omni_platform` / `OmniPlatform`. Platform adapters under
-`vllm_omni/platforms/` are allowed; other files must not add new
-`torch.cuda.*` helpers (`device_count`, `synchronize`, `empty_cache`,
-`device()`, `manual_seed`, and similar). `import torch` is fine.
-
-#### shellcheck
-
-The hook does **not** download a binary. Install `shellcheck` with a signed
-package manager, then re-run:
-
- Debian/Ubuntu/WSL: `sudo apt-get install shellcheck`
- Fedora: `sudo dnf install ShellCheck`
- macOS: `brew install shellcheck`
- Git Bash (MINGW): `scoop install shellcheck` so `shellcheck.exe` is on PATH.
-  WSL is Linux: use `apt-get`, not a Windows `.exe`.
-
-If no native binary is found, the wrapper prints those commands (and
-[the upstream install page](https://github.com/koalaman/shellcheck?tab=readme-ov-file#installing))
-and exits 1. AMD and other vendor scripts are **not** excluded.
-
-#### mypy
-
-`mypy-3.10` runs on commit for changed files. `[tool.mypy]` uses Python 3.12,
-`ignore_missing_imports = true`, and `follow_imports = "silent"`. Wrapper
-`tools/pre_commit/mypy.py` skips `vllm_omni/model_executor/models/` and
-`vllm_omni/diffusion/models/`, and type-checks `tests/` with
-`--follow-imports skip`. Extra versions:
-
-```bash
-pre-commit run --hook-stage manual mypy-3.12
-```
-
-#### Test CI marks
-
-`check-test-ci-coverage` requires each collected test module under `tests/` to
-have at least one CI **level** mark (`core_model`, `advanced_model`,
-`full_model`, `local_model`, or `slow`) and a **hardware** mark (`cpu`, `cuda`,
-`H100`, …) or helper (`hardware_test(` / `hardware_marks(`). GitHub Actions
-skips this hook; local commit does not. See the
-[test writing guide](./ci/test_writing_guide.md).
-
-#### TTS adapter ratchet
-
-`check-tts-adapter-migration` counts `self._tts_model_type` comparisons in
-`vllm_omni/entrypoints/openai/serving_speech.py`. The count must stay at or
-below `MAX_MODEL_TYPE_BRANCHES` in
-[`tools/pre_commit/check_tts_adapter.py`](https://github.com/vllm-project/vllm-omni/blob/main/tools/pre_commit/check_tts_adapter.py).
-New per-model behavior belongs in
-`vllm_omni/entrypoints/openai/tts_adapters/`. Removing branches **must** lower
-the budget in the same change; raising it is a reviewable policy edit.
-
-#### Markdownlint and Buildkite
-
-`markdownlint-cli2` auto-fixes `docs/`, `recipes/`, and the root README /
-CONTRIBUTING (rules in `.markdownlint.yaml`). Skill files under `.claude/` and
-`.cursor/` are excluded.
-
-`check-buildkite` validates `.buildkite/*.yml` against the official schema
-after the same expansion `upload_pipeline.py` uses. Omni-only keys such as
-`mirror_hardwares` are stripped or rendered first. A few files are skipped in
-`SKIP_FILES` inside `tools/pre_commit/check_buildkite.py`.
-
-#### Extending allowlists and budgets
-
-Prefer fixing the call site. Growing an allowlist or raising a budget is a
-policy change and needs review — do not edit these just to make the hook pass.
-
-| Gate | File | What to edit |
-| ---- | ---- | ------------ |
-| pickle, `re`, `base64`, Hugging Face Hub, Triton/TileLang | [`tools/pre_commit/check_forbidden_imports.py`](https://github.com/vllm-project/vllm-omni/blob/main/tools/pre_commit/check_forbidden_imports.py) | `CHECK_IMPORTS[<rule>].allowed_files`. Use `allowed_dirs` only when a whole tree should stay exempt. |
-| `torch.cuda` | [`tools/pre_commit/check_torch_cuda.py`](https://github.com/vllm-project/vllm-omni/blob/main/tools/pre_commit/check_torch_cuda.py) | `ALLOWED_FILES`, or `ALLOWED_PREFIXES` for a platform adapter tree. |
-| TTS `_tts_model_type` branches | [`tools/pre_commit/check_tts_adapter.py`](https://github.com/vllm-project/vllm-omni/blob/main/tools/pre_commit/check_tts_adapter.py) | `MAX_MODEL_TYPE_BRANCHES` (down only, unless the PR justifies a raise). |
-| Buildkite skip list | [`tools/pre_commit/check_buildkite.py`](https://github.com/vllm-project/vllm-omni/blob/main/tools/pre_commit/check_buildkite.py) | `SKIP_FILES` for pipelines that cannot be expanded. |
-
-To skip one hook for a single commit (discouraged): `SKIP=<hook-id> git commit`.
-To bypass every hook: `git commit --no-verify` (also discouraged).
-
 ### Documentation

 MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file, `mkdocs.yml`.
@@ -305,14 +162,12 @@ Only specific types of PRs will be reviewed. The PR title is prefixed appropriat
 Before submitting a PR, run the [precheck-pr skill](https://github.com/vllm-project/vllm-omni/blob/main/.claude/skills/precheck-pr/SKILL.md) with the code agent for a self-review against project conventions:

 The skill offers two modes:
-
 - **Quick (~3 min):** catches showstoppers — PR title format, missing benchmark claims, rebase status
 - **Full (~10 min):** thorough maintainer-grade review — dead code scan, copy-paste detection, import hygiene

 The precheck covers five PR types: Bug Fix, Performance, New Model, Diffusion Model, and General. Each type has a tailored checklist that validates evidence quality (repro steps, A/B benchmarks, registry entries, etc.). See the [precheck-pr skill](https://github.com/vllm-project/vllm-omni/blob/main/.claude/skills/precheck-pr/SKILL.md) for the full checklist.

 ### Local Test
-
 Please run the L1 and L2 test cases locally first and attach the results before contacting us to add the "ready" label. Please refer to the [test instructions](./ci/test_execution_guide.md) for running the test cases.

 ### Automatic skip-ci (docs and pytest skip marks)
@@ -334,7 +189,7 @@ These PR shapes all trigger skip-ci:
 Skip-ci does **not** apply when the diff also touches product code (for example `vllm_omni/`), or when test files change assertions, imports, fixtures, or other non-skip logic. If the diff cannot be resolved (non-PR branches outside `main`), CI runs as usual.

 !!! note
-    Skipping L2/L3 does **not** disable the Docker image build step. Nightly (L4) upload can still run when the PR has a `nightly-test` label or on scheduled `main` builds with `NIGHTLY=1`. Weekly (L5) upload can still run with `weekly-test`, `WEEKLY=1`, or `NON_CRITICAL=1`. Bootstrap child steps live in `bootstrap-upload-steps.yml`; the hook entry step runs `upload_pipeline.py --upload <platform>/bootstrap-upload-steps.yml`, which injects `if` by step `key` from skip-ci before upload. See [CI Settings — Diff-aware CI](./ci/ci_settings.md#diff-aware-ci) and [Test System Overview](./ci/test_system_overview.md).
+    Skipping L2/L3 does **not** disable the Docker image build step. Nightly (L4) upload can still run when the PR has a `nightly-test` label or on scheduled `main` builds with `NIGHTLY=1`. Bootstrap child steps live in `bootstrap-upload-steps.yml`; the hook entry step runs `upload_pipeline.py --upload <platform>/bootstrap-upload-steps.yml`, which injects `if` by step `key` from skip-ci before upload. See [CI Settings — Diff-aware CI](./ci/ci_settings.md#diff-aware-ci) and [Test System Overview](./ci/test_system_overview.md).

 ### Code Quality

@@ -8,7 +8,7 @@ For CI levels (L1–L5) and triggers, see [Test System Overview](./test_system_o

 Canonical layout (prefer these paths for new changes):

-```text
+```
 .buildkite/
 ├── common/                          # Shared across platforms
 │   ├── scripts/
@@ -48,7 +48,7 @@ Canonical layout (prefer these paths for new changes):
    └── scripts/
 ```

-### Placement rules
+**Placement rules**

 | Rule | Detail |
 | ---- | ------ |
@@ -81,14 +81,7 @@ There are still **legacy copies** at `.buildkite/*.yaml` (without the `cuda/` pr
    | L2 | `cuda/test-ready.yml` | `ready` label |
    | L3 | `cuda/test-merge.yml` | `merge-test` label / main merge |
    | L4 | `cuda/test-nightly.yml` | `nightly-test` label or `NIGHTLY=1` |
-    | L5 | `cuda/test-weekly.yml` | `weekly-test` label, `WEEKLY=1`, or `NON_CRITICAL=1` (see step `if`s below) |
-
-    On scheduled `main` builds, `test-weekly.yml` is uploaded when **`WEEKLY=1` or `NON_CRITICAL=1`**. Inside that file:
-
-    - **Reliability** / **Perf Test** / **Simple · CPU Coverage Test** → `WEEKLY=1` (or PR label `weekly-test` for Reliability/Perf). Pipeline upload for scheduled env vars still requires `main`.
-    - **E2E Tests** group (slow Omni/TTS/Diffusion sweeps) → `NON_CRITICAL=1`
-
-    **`--e2e`:** when uploading ready/merge on `main` with **`WEEKLY=1`**, bootstrap passes `--e2e` so only the **E2E Test** group is kept (same flag `run_cov_split.sh` uses to enable per-model coverage).
+    | L5 | `cuda/test-weekly.yml` | `weekly-test` label or `WEEKLY=1` |

    **Upload:** `upload_pipeline.py --upload` expands uploader-only keys before Buildkite upload.

@@ -119,8 +112,6 @@ There are still **legacy copies** at `.buildkite/*.yaml` (without the `cuda/` pr

    **Test YAML:** `npu/test-npu-ready.yml` (L2), `test-npu-nightly.yml` (L4).

-    **L2 trigger:** PR label `ready` (CUDA/AMD L2). PR labels `ready` + `npu-test` trigger NPU CI only.
-
    **Upload:** same as CUDA—`upload_pipeline.py --upload`.

    **Hardware in YAML:** `mirror_hardwares` preset (string), expanded to `agents`, top-level `image`, and `plugins`. Presets: `a2b3_npu_1`, `a2b3_npu_4`, `a3_npu_2` in `common/ci_mirror_hardwares.yml`.
@@ -213,15 +204,15 @@ Label triggers (`ready`, `merge-test`) are unchanged—diff-aware logic only red
 | Diff shape | Path | Default L2/L3 |
 | --- | --- | --- |
 | Product code / non-whitelisted paths | normal CI | all on |
-| Docs and/or qualifying skip-mark only | `skip_all` | all off (scheduled `main` NIGHTLY/WEEKLY/`NON_CRITICAL` exceptions below) |
+| Docs and/or qualifying skip-mark only | `skip_all` | all off (scheduled `main` NIGHTLY/WEEKLY exceptions below) |
 | Whitelisted CI YAML only | yaml-gated (`skip_l2_l3`) | per platform/level matrix |
 | Docs/skip-mark **+** whitelisted CI YAML | yaml-gated (`skip_l2_l3`) | same as CI-YAML-only (does **not** widen to normal CI) |
 | Non-qualifying skip-mark and no CI YAML | normal CI | all on |
 | Diff unavailable | normal CI | all on |

-**`skip_all` exceptions (CUDA/NPU bootstrap only):** PR labels (`nightly-test`, `merge-test`, `weekly-test`, `ready`, …) do **not** revive jobs under `skip_all`. On `main`, scheduled `NIGHTLY=1` still builds the image and uploads L4; `WEEKLY=1` or `NON_CRITICAL=1` still builds the image and uploads L5 (CUDA). `WEEKLY=1` on `main` also uploads L2/L3 with `--e2e`.
+**`skip_all` exceptions (CUDA/NPU bootstrap only):** PR labels (`nightly-test`, `merge-test`, `npu-test`, `weekly-test`, …) do **not** revive jobs. On `main`, scheduled `NIGHTLY=1` still builds the image and uploads L4 plus L2/L3 (with `--e2e`); `WEEKLY=1` still builds the image and uploads L5 (CUDA).

-**Yaml-gated nightly/weekly:** L4/L5 upload steps keep their normal label / `NIGHTLY` / `WEEKLY` / `NON_CRITICAL` conditions (for example PR `nightly-test` still uploads nightly). Only L2/L3 upload steps are matrix-gated.
+**Yaml-gated nightly/weekly:** L4/L5 upload steps keep their normal label / `NIGHTLY` / `WEEKLY` conditions (for example PR `nightly-test` still uploads nightly). Only L2/L3 upload steps are matrix-gated.

 ##### Whitelisted CI YAML → platform

@@ -294,12 +285,12 @@ CUDA **L2** (`.buildkite/cuda/test-ready.yml`) and **L3** (`.buildkite/cuda/test
 | `source_file_dependencies` | List of path **prefixes**. If any changed file equals a prefix or starts with `prefix/`, keep the step (or group); otherwise omit it. |
 | `mirror_hardwares` | Expand to `agents` + `plugins` (+ optional `image`) from `ci_mirror_hardwares.yml`. |

-### Policy
+**Policy**

 - **Always uploaded** (no key): groups outside **E2E Test**—Simple Test, Diffusion unit tests, Engine/Model Executor, Distributed, Custom Pipeline, Entrypoints (L2), LoRA / Entrypoints (L3).
 - **Diff-gated**: every **E2E Test** leaf job. List the smallest prefix set per step—pytest file(s), model code under `vllm_omni/model_executor/models/` or `vllm_omni/diffusion/models/`, plus `stage_input_processors/` and `vllm_omni/deploy/*.yaml` when applicable. A **group** may define the key instead; the whole group drops if no prefix matches.

-### YAML examples
+**YAML examples**

 ```yaml
      - label: "Diffusion · Qwen Image Test"
@@ -321,7 +312,7 @@ CUDA **L2** (`.buildkite/cuda/test-ready.yml`) and **L3** (`.buildkite/cuda/test
        mirror_hardwares: l4_4
 ```

-### Local dry-run
+**Local dry-run**

 ```bash
 python3 .buildkite/common/scripts/upload_pipeline.py .buildkite/cuda/test-ready.yml
@@ -333,19 +324,18 @@ On PR builds, `upload_pipeline.py` logs `skip '…' (no changes under …)` for

 ### Labels and grouping

- Use **groups** for dashboard readability; keep **E2E Test** as the group name CUDA diff filtering expects for `--e2e` weekly runs on main (`WEEKLY=1`).
+- Use **groups** for dashboard readability; keep **E2E Test** as the group name CUDA diff filtering expects for `--e2e` nightly runs on main.
 - Prefix labels by model domain: **Omni ·**, **TTS ·**, **Diffusion ·**, **Simple ·**, etc., matching existing steps.

 ### Per-model coverage

 Pilot (v1): one Merge-tier (L3) job in `.buildkite/cuda/test-merge.yml` uploads
 per-model, per-entry-mode coverage as Buildkite artifacts — "TTS · Qwen3-TTS Base
-Test". Coverage + artifact upload run only when bootstrap uploaded that job with
-`--e2e` (`WEEKLY=1` and `BUILDKITE_BRANCH=main`, via `run_cov_split.sh`); otherwise
-the same job runs plain pytest without `--cov`. It runs on a single GPU so the
-pilot is cheap to reproduce.
-
-**L1 package coverage (CPU):** ready/merge Simple Test jobs run without `--cov`. Scheduled weekly on `main` with `WEEKLY=1` runs **Simple · CPU Coverage Test** in `.buildkite/cuda/test-weekly.yml` (`pytest -m 'core_model and cpu'` + Cobertura XML artifact).
+Test". It runs on a single GPU so the pilot is cheap to reproduce. (A second
+diffusion pilot, "Diffusion · Bagel Test", was retired from merge; reintroduce
+another diffusion coverage job if a second pilot is needed again.) This is a
+pilot, not a rollout: no dashboard/visualization lives in this repo, and nothing
+is gated on coverage.

 **Naming convention**: `coverage-<model_id>-<mode>-<step_id>.xml.gz`, where
 `<model_id>` is the model's directory name under
@@ -364,8 +354,8 @@ imported. A run covering zero lines produces the same 7 MB. gzip takes it to
 roughly 410 KB and changes nothing about the data.

 `<step_id>` is what keeps two steps that cover the same model apart. Artifacts are
-scoped to the build, and a weekly build can carry ready/merge (with `--e2e`) and
-weekly tiers at once, so several same-model steps land in one namespace — `qwen3_tts` already has
+scoped to the build, and a nightly build carries the ready, merge and nightly tiers
+at once, so several same-model steps land in one namespace — `qwen3_tts` already has
 both a Base and a CustomVoice job, and `minicpmo_4_5` a base and a duplex one. Two
 uploads on one path do not fail loudly: an exact-name download can report the path
 as ambiguous, and a glob download fetches every match concurrently and renames each
@@ -435,7 +425,7 @@ just confirming both files exist.
 | Check | Command / location |
 | ----- | ------------------ |
 | CUDA render | `python3 .buildkite/common/scripts/upload_pipeline.py .buildkite/cuda/test-<level>.yml` |
-| No leaked uploader keys | Pipe the render into `grep -E 'mirror_hardwares\|source_file_dependencies'` — expect empty |
+| No leaked uploader keys | `… \| grep -E 'mirror_hardwares|source_file_dependencies'` → empty |
 | Skip-ci / upload unit tests | `pytest tests/buildkite/` |
 | Local job replay (CUDA L2+) | `tools/run_ready_jobs.sh`, `tools/run_merge_jobs.sh`, `tools/nightly/run_nightly_jobs.sh` (read YAML from `cuda/`) |

@@ -6,7 +6,7 @@ When you open a PR against vLLM-Omni, several CI checks run automatically:

 | Check | Platform | What it does |
 | ----- | -------- | ------------ |
-| **pre-commit** | GitHub Actions | Runs Ruff, formatting, typos, YAML validation, forbidden imports, `torch.cuda`, TTS adapter ratchet, and Buildkite schema. Local-only gates (SPDX, shellcheck, markdownlint, mypy-3.10, test marks) are in the workflow `SKIP` env — see [Linting](../README.md#linting). |
+| **pre-commit** | GitHub Actions | Runs linting (Ruff), formatting, spell-checking (typos), and YAML validation. |
 | **Build Wheel** | GitHub Actions | Builds Python wheels for Python 3.11 and 3.12 on Ubuntu. Skipped for docs-only or Markdown-only changes (controlled by `paths-ignore` in the workflow). |
 | **DCO** | GitHub | Verifies every commit has a `Signed-off-by` line. |
 | **docs/readthedocs.org:vllm-omni** | Read the Docs | Builds the MkDocs documentation site. |
@@ -29,13 +29,6 @@ pre-commit run --all-files

 Then commit the fixes and push.

-A green GitHub pre-commit job can still miss SPDX, shellcheck, mypy-3.10,
-markdownlint, and test-mark coverage because CI skips those IDs. If your
-**local** commit hook fails, follow [Linting](../README.md#linting) for the
-full hook list (forbidden imports, `torch.cuda`, TTS adapter ratchet, and
-Buildkite schema still run in GHA). Do not grow allowlists or raise
-`MAX_MODEL_TYPE_BRANCHES` without review.
-
 ### DCO failures

 Every commit must include a `Signed-off-by` line. If you forgot, amend your commits:
@@ -1,15 +1,14 @@
 When you want to add L4-level ***performance test*** cases, add entries to JSON files under `tests/dfx/perf/tests/` and run them via `tests/dfx/perf/scripts/run_benchmark.py` (omni / TTS) or `run_diffusion_benchmark.py` (diffusion).

-#### Config file layout (in-tree examples)
+**Config file layout (in-tree examples)**

 | Model type | Runner | Example JSON files |
 | ---------- | ------ | ------------------ |
-| Omni (nightly) | `run_benchmark.py` | `test_qwen3_omni_no_async_chunk.json`, `test_qwen3_omni_async_chunk.json` (`full_model` in `mark`) |
-| Omni (weekly) | `run_benchmark.py` | `test_qwen3_omni_vllm_text.json`, `test_qwen3_omni_multi_replicas.json` (`slow` in `mark`; **Perf Test** in `test-weekly.yml`) |
+| Omni | `run_benchmark.py` | `test_qwen3_omni_no_async_chunk.json`, `test_qwen3_omni_async_chunk.json`, `test_qwen3_omni_vllm_text.json`, `test_qwen3_omni_multi_replicas.json` |
 | TTS | `run_benchmark.py` | `test_tts.json`, `test_voxcpm2.json`, `test_higgs_audio_v3.json` |
 | Diffusion | `run_diffusion_benchmark.py` | `test_qwen_image_vllm_omni.json`, `test_bagel_vllm_omni.json`, `test_wan22_i2v_vllm_omni.json`, `test_cosmos3_vllm_omni.json`, … |

-#### How runners pick cases
+**How runners pick cases**

 Without **`--test-config-file`**, each runner scans all `*.json` under `tests/dfx/perf/tests/` but only keeps its own model type:

@@ -18,9 +17,9 @@ Without **`--test-config-file`**, each runner scans all `*.json` under `tests/df

 Diffusion cases are detected when the JSON has `server_type` (typically `"vllm-omni"`) or `"diffusion"` in the `mark` array. Omni / TTS JSON has neither.

-#### Running perf cases
+**Running perf cases**

-Pass **`--test-config-file`** to run one JSON file as-is, or omit it for the bulk scan above and filter with pytest **`-m`** on each case's JSON `mark` (for example `pytest … run_benchmark.py -m "full_model and tts and H100"` or `-m "slow and omni and H100"` for weekly Omni configs).
+Pass **`--test-config-file`** to run one JSON file as-is, or omit it for the bulk scan above and filter with pytest **`-m`** on each case's JSON `mark` (for example `pytest … run_benchmark.py -m "full_model and tts and H100"`).

 ```JSON
 {
@@ -32,7 +31,7 @@ Pass **`--test-config-file`** to run one JSON file as-is, or omit it for the bul
    ],
    "server_params": {
        "model": "Qwen/Qwen3-Omni-30B-A3B-Instruct",
-        "stage_config_name": "qwen3_omni_moe.yaml"
+        "stage_config_name": "qwen3_omni.yaml"
    },
    "benchmark_params": [
        {
@@ -56,22 +55,20 @@ Pass **`--test-config-file`** to run one JSON file as-is, or omit it for the bul
 }
 ```

-#### Parameter Explanation
+**Parameter Explanation**

-##### Overview
+*Overview*

-| Field              | Required       | Description                                  |
-| ------------------ | -------------- | -------------------------------------------- |
-| test_name          | Yes            | Unique identifier for the test case          |
-| mark               | No             | Pytest marks; see **`mark` field** below     |
-| server_params      | Yes            | Server-side configuration parameters         |
-| benchmark_params   | Yes            | Benchmark running parameters                 |
-| server_type        | Diffusion only | Routes case to run_diffusion_benchmark.py    |
-| benchmark_endpoint | Diffusion only | Benchmark API path                           |
+| Field            | Required | Description                                                     |
+| ---------------- | -------- | --------------------------------------------------------------- |
+| test_name        | Yes      | Unique identifier for the test case                             |
+| mark             | No       | Pytest marks for this case (see **`mark` field** below). Omit only for configs not meant to be filtered by `-m`. |
+| server_params    | Yes      | Server-side configuration parameters                            |
+| benchmark_params | Yes      | Benchmark running parameters (supports multiple configurations) |
+| server_type      | Diffusion only | When set (e.g. `"vllm-omni"`), routes the case to `run_diffusion_benchmark.py`. |
+| benchmark_endpoint | Diffusion only | API path for the benchmark client (e.g. `/v1/videos`, `/v1/images/generations`). |

-Omit `mark` only for configs not meant to be filtered by `-m`. `server_type` is typically `"vllm-omni"`. `benchmark_endpoint` examples: `/v1/videos`, `/v1/images/generations`.
-
-#### `mark` field
+**`mark` field**

 Optional top-level field on each perf JSON **case object** (one per `test_name`). `run_benchmark.py` and `run_diffusion_benchmark.py` read it via `tests.dfx.conftest.resolve_pytest_marks` and attach the marks to the corresponding `pytest.param`, so you can filter locally with `-m`.

@@ -122,11 +119,11 @@ Multi-GPU diffusion (example: Cosmos3 with `cfg-parallel-size=2`):
 - Diffusion perf: include `"diffusion"` in the `mark` array
 - HunyuanImage local-weight cases: add `"local_model"` to the `mark` array

-#### Parametrization IDs
+**Parametrization IDs**

 Each `(server, benchmark index)` pair becomes one `pytest.param` with id `{test_name}-{suffix}`. The suffix comes from `benchmark_params[].name` when set (for example `test_tts-p0`, `test_omni-p1`); otherwise it is derived from fields like `task` / `eval_phase`.

-#### Benchmark result filenames
+**Benchmark result filenames**

 Result files use the **runtime** hardware label from `get_runtime_resource_label()` (detected GPU/NPU name on the machine that ran the job), **not** `mark.hardware_marks.res`. On the default H100 CI pool, `H100` is **omitted** from filenames (`resource_label_for_filename`).

@@ -135,7 +132,7 @@ Examples:
 - Omni/TTS: `result_{test_name}_{optional_hw}_{dataset}_....json` under `BENCHMARK_DIR`
 - Diffusion: one aggregate `diffusion_result_{config_stem}_{optional_hw}_{timestamp}.json` per source JSON file (array of all runs from that file)

-#### Local commands
+**Local commands**

 ```bash
 # Bulk load + filter by JSON mark
@@ -149,19 +146,18 @@ pytest -s -v tests/dfx/perf/scripts/run_benchmark.py \
  --test-config-file tests/dfx/perf/tests/test_qwen3_omni_async_chunk.json
 ```

-<!-- markdownlint-disable-next-line MD051 -->
 See also [Markers for Tests](#markers-for-tests) for registered hardware markers (`H100`, `L4`, `cuda`, `distributed_cuda`, …).

-#### `server_params` Configuration
+**`server_params` Configuration**

-##### Basic Parameters
+*Basic Parameters*

-| Parameter         | Required | Example                   | Description                    |
-| ----------------- | -------- | ------------------------- | ------------------------------ |
-| model             | Yes      | Qwen/Qwen3-Omni-30B-A3B…  | Model name or path             |
-| stage_config_name | Yes      | qwen3_omni_moe.yaml       | Deploy configuration file name |
+| Parameter         | Required | Example                            | Description                   |
+| ----------------- | -------- | ---------------------------------- | ----------------------------- |
+| model             | Yes      | "Qwen/Qwen3-Omni-30B-A3B-Instruct" | Model name or path            |
+| stage_config_name | Yes      | "qwen3_omni.yaml"                  | Stage configuration file name |

-##### Dynamic Configuration (update/delete)
+*Dynamic Configuration (update/delete)*

 Supports incremental modifications based on the basic configuration:

@@ -170,40 +166,38 @@ Supports incremental modifications based on the basic configuration:
 | update    | Update or add configuration items    |
 | delete    | Delete specified configuration items |

-##### Example
+**Example**:

-```json
+```
 "update": {
    "async_chunk": true,  // Enable asynchronous chunk processing
-    "stages": {
+    "stage_args": {
        "0": {
-            "max_num_seqs": 64
+            "engine_args.custom_process_next_stage_input_func": "vllm_omni.model_executor.stage_input_processors.qwen3_omni.thinker2talker_async_chunk"
        }
    }
 },
 "delete": {
-    "stages": {
-        "2": ["max_num_batched_tokens"]  // Delete this deploy override for stage 2
+    "stage_args": {
+        "2": ["custom_process_input_func"]  // Delete this configuration for stage 2
    }
 }
 ```

-#### `benchmark_params` Configuration
+**`benchmark_params` Configuration**

 You can add any benchmark running parameters you need here. For all optional parameters, refer to the [benchmark documentation](https://github.com/vllm-project/vllm-omni/blob/main/docs/cli/bench/serve.md). General modifications are as follows:

-1. Change the --xxx-xx-xx running parameters to xxx_xx_xx format and fill them as keys in the JSON file.
-2. For boolean variables in the running parameters, modify them to forms such as ignore_eos: true/false and fill them into the JSON file.
-3. Optionally add a `baseline` object (see **Baseline thresholds** below). If you omit `baseline` or leave it empty, the performance test still runs but does not assert metric thresholds from this field.
-4. Set `"name"` on each `benchmark_params` entry for stable pytest ids and readable result keys.
-5. The qps and concurrency modes are recommended to be mutually exclusive. For detailed explanations, see the table below:
+1.  Change the --xxx-xx-xx running parameters to xxx_xx_xx format and fill them as keys in the JSON file.
+2.  For boolean variables in the running parameters, modify them to forms such as ignore_eos: true/false and fill them into the JSON file.
+3.  Optionally add a `baseline` object (see **Baseline thresholds** below). If you omit `baseline` or leave it empty, the performance test still runs but does not assert metric thresholds from this field.
+4.  Set `"name"` on each `benchmark_params` entry for stable pytest ids and readable result keys.
+5.  The qps and concurrency modes are recommended to be mutually exclusive. For detailed explanations, see the table below:

-| Parameter       | Type          | Required | Example/Values       | Description                          |
-| --------------- | ------------- | -------- | -------------------- | ------------------------------------ |
-| name            | string        | No       | `"1024x1024_steps4"` | Stable suffix for pytest param id    |
-| num_prompts     | int / array   | Yes      | 10, [10, 20, 30]     | Number of requests (scalar or sweep) |
-| request_rate    | float / array | No       | 0.5, [0.5, 1, inf]   | Queries per second (QPS mode)        |
-| max_concurrency | int / array   | No       | 1, [1, 2, 3]         | Max in-flight requests               |
-| baseline        | object        | No       | see below            | Optional hardware-nested thresholds  |
-
-`num_prompts`, `request_rate`, and `max_concurrency` accept scalars or arrays; single values expand to match sweep length. QPS and concurrency modes are mutually exclusive. `baseline` top-level keys must be hardware pytest markers from `pyproject.toml`; metric names and values are free-form (scalars or sweep-aligned lists). Omit `baseline` to run without threshold assertions.
+| Parameter       | Type        | Required | Example/Values  | Description                                                                                                                                                                                                                                                          |
+| --------------- | ----------- | -------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| name            | string      | No       | `"1024x1024_steps4"` | Stable suffix for pytest param id and logs. |
+| num_prompts     | int / array | Yes      | 10,[10, 20, 30] | Number of requests. Supports single values or arrays. If a single value is used, it will be automatically expanded to match the number of qps or max_concurrency, e.g., [10,10,10]. If an array is used, its length must match the number of qps or max_concurrency. |
+| request_rate    | float / array | No  | 0.5, [0.5, 1, inf] | Queries per second. Supports single values or arrays. If a single value is used, it will be automatically expanded to match the number of num_prompts, e.g., [1,1,1]. If an array is used, its length must match the number of num_prompts.                          |
+| max_concurrency | int / array | No       | 1, [1, 2, 3]    | Maximum concurrent in-flight requests. Same array / expansion rules as `request_rate` (mutually exclusive with QPS mode).                                                                                                                                                                                                             |
+| baseline        | object      | No       | see below       | Optional thresholds. **Hardware-nested only**: top-level keys must be `[hardware-resource]` pytest markers from `pyproject.toml` (`get_hardware_mark_list()`). Under each hardware key, metric names are free-form; values are scalars or sweep-aligned lists. Example: `{"H100": {"throughput_qps": […], "custom_stage_ms": 1.0}, "A3": {…}}`. Runtime filename aliases (`_RUNTIME_DEVICE_ALIASES`) are separate and do not expand this allowlist. |
@@ -1,20 +1,13 @@
 # Test Execution Guide
-
 ## Setting Up the Test Environment
-
 ### Creating a Container
-
 vLLM-Omni provides an official Docker image for deployment. These images are built upon vLLM Docker images and are available on [Docker Hub](https://hub.docker.com/r/vllm/vllm-omni/tags). The version of vLLM-Omni indicates which vLLM release it is based on.
 For a local test environment, you can follow the steps below to create a container:
-
 ## Installing Dependencies
-
 ### vLLM & vLLM-Omni
-
 vLLM-Omni is built based on vLLM. You can follow [install guide](../../getting_started/installation/README.md) to build your local environment.

 ### Test Case Dependencies
-
 When running test cases, you may need to install the following dependencies:

 ```bash
@@ -23,7 +16,6 @@ apt-get install -y espeak-ng jq
 ```

 ## Running Tests
-
 Our test scripts use the pytest framework. First, please use `git clone https://github.com/vllm-project/vllm-omni.git` to download the vllm-omni source code. Then, in the root directory of vllm-omni, you can run the following commands in your local test environment to execute the corresponding test cases.

 ### CI job runners (L2–L4): logs, timing, and timeouts
@@ -33,7 +25,7 @@ Our test scripts use the pytest framework. First, please use `git clone https://
 **Log layout** (default under `logs/ready_jobs`, `logs/merge_jobs`, or `logs/nightly_jobs`; override with `--log-dir`):

 | Path | Description |
-| ------ | ------------- |
+|------|-------------|
 | `jobs/*.sh` | Generated per-step bash wrappers |
 | `jobs/.job_timeouts` | Job key → `timeout_in_minutes` from Buildkite YAML (when set) |
 | `<job_key>.log` | Tee output for each job |
@@ -41,7 +33,7 @@ Our test scripts use the pytest framework. First, please use `git clone https://

 **Timing:** while each job runs, stderr prints `finished in …` or `failed after …`. When all jobs finish, a summary is printed and written to `timing_summary.log`, for example:

-```text
+```
 === Job timing summary ===
  TTS_VoxCPM2_Test  25m 40s  OK
  Omni_Qwen3-Omni_Test  8m 05s  TIMED OUT
@@ -122,6 +114,7 @@ Failed jobs: 1/2
    pytest -s -v -m "advanced_model and distributed_cuda and L4" --run-level=advanced_model
    ```

+
 === "L4 level"

    **Recommended:** run CI-aligned nightly jobs from the repo root via [`tools/nightly/run_nightly_jobs.sh`](https://github.com/vllm-project/vllm-omni/blob/main/tools/nightly/run_nightly_jobs.sh). The script reads [`.buildkite/cuda/test-nightly.yml`](https://github.com/vllm-project/vllm-omni/blob/main/.buildkite/cuda/test-nightly.yml), generates per-step bash wrappers, runs pytest (perf jobs first, then aggregates perf JSON into Excel), and tees logs under `logs/nightly_jobs/` (see [CI job runners](#ci-job-runners-l2l4-logs-timing-and-timeouts); `generate_nightly_perf_excel` is included in the timing summary). Requires `bash`, `python3`, and PyYAML (`pip install pyyaml`).
@@ -167,7 +160,7 @@ Failed jobs: 1/2
    pytest -sv tests/dfx/perf/scripts/run_benchmark.py --test-config-file tests/dfx/perf/tests/test_tts.json
    pytest -sv tests/dfx/perf/scripts/run_diffusion_benchmark.py --test-config-file tests/dfx/perf/tests/test_cosmos3_vllm_omni.json
    ```
-    Nightly **Perf Test** jobs in [``test-nightly.yml``](https://github.com/vllm-project/vllm-omni/blob/main/.buildkite/cuda/test-nightly.yml) use ``--test-config-file`` only (no ``-m``). Weekly **Perf Test** in [``test-weekly.yml``](https://github.com/vllm-project/vllm-omni/blob/main/.buildkite/cuda/test-weekly.yml) runs ``test_qwen3_omni_vllm_text.json`` and ``test_qwen3_omni_multi_replicas.json`` (JSON ``mark`` includes ``slow``). E2e L4 function tests use ``full_model`` + ``--run-level full_model``. Example:
+    Nightly **Perf Test** jobs in ``test-nightly.yml`` use ``--test-config-file`` only (no ``-m``). E2e L4 function tests still use ``full_model`` + ``--run-level full_model`` (see [test-nightly.yml](https://github.com/vllm-project/vllm-omni/blob/main/.buildkite/test-nightly.yml)). Example:

 === "L5 level"

@@ -193,13 +186,9 @@ Failed jobs: 1/2

    ```

-    The latest L5 CI jobs are in [test-weekly.yml](https://github.com/vllm-project/vllm-omni/blob/main/.buildkite/cuda/test-weekly.yml):
-
-    - **Reliability** (+ invalid-parameter), **Perf Test** (Omni vLLM Text / Multi-Replica), and **Simple · CPU Coverage Test** → `WEEKLY=1` (or PR label `weekly-test` for Reliability/Perf). Scheduled upload of those env-gated steps still requires `main`.
-    - **E2E Tests** (slow Omni / TTS / Diffusion sweeps) → `NON_CRITICAL=1` (pipeline upload also accepts `WEEKLY=1` / `weekly-test`; the group `if` still needs `NON_CRITICAL`)
+    The latest L5 CI jobs (reliability + invalid-parameter weekly steps) are in [test-weekly.yml](https://github.com/vllm-project/vllm-omni/blob/main/.buildkite/cuda/test-weekly.yml).

 You can find more information about markers in [Test Writing Guide — Markers for Tests](./test_writing_guide.md#markers-for-tests).

 ## Adding New Test Cases
-
 Please refer to the [Test System Overview](./test_system_overview.md) and [Test Writing Guide](./test_writing_guide.md).
@@ -12,7 +12,8 @@ Through five levels (L1-L5) and common (Common) specifications, the system clari
      <th>Level</th>
      <th>Scope & Focus</th>
      <th>Model Coverage Strategy</th>
-      <th>Module Strategy</th>
+      <th>Feature Coverage Strategy</th>
+      <th>Interface Coverage Strategy</th>
      <th>Tags</th>
      <th>Time Cost</th>
      <th>Test Dir</th>
@@ -30,6 +31,7 @@ Through five levels (L1-L5) and common (Common) specifications, the system clari
      <td>/</td>
      <td>/</td>
      <td>/</td>
+      <td>/</td>
      <td><a href="https://github.com/vllm-project/vllm-omni/blob/main/.github/PULL_REQUEST_TEMPLATE.md">PR Checklist</a></td>
      <td>/</td>
      <td>/</td>
@@ -41,6 +43,7 @@ Through five levels (L1-L5) and common (Common) specifications, the system clari
      <td>/</td>
      <td>/</td>
      <td>/</td>
+      <td>/</td>
      <td><a href="./failures.md">CI Failures</a></td>
      <td>/</td>
      <td>/</td>
@@ -50,6 +53,7 @@ Through five levels (L1-L5) and common (Common) specifications, the system clari
      <td>Unit tests for components like entrypoints, models</td>
      <td>/</td>
      <td>/</td>
+      <td>/</td>
      <td><code>core_model and cpu</code></td>
      <td rowspan="2">&lt;15min</td>
      <td>
@@ -67,8 +71,9 @@ Through five levels (L1-L5) and common (Common) specifications, the system clari
    <tr>
      <td><strong>L2</strong><br>(E2E across models & GPU-required UT)</td>
      <td>Online (basic deployment scenarios):<br>dummy, normal inference function (output format, stream), some instance startup UT</td>
-      <td>Key models + online basic scenarios; request success, non-empty output, format match (no Whisper/accuracy)</td>
-      <td>Key features and modules that require launching instances (prefer random weights)</td>
+      <td>High-priority models + online basic scenarios; request success, non-empty output, format match (no Whisper/accuracy)</td>
+      <td>High-priority features and component tests that require launching instances</td>
+      <td>High-priority interfaces (using random lightweight models)</td>
      <td><code>core_model and hardware_test(H100, L4, etc.) and omni/tts/diffusion</code></td>
      <td>
        <strong>Model E2E:</strong><br>
@@ -90,8 +95,9 @@ Through five levels (L1-L5) and common (Common) specifications, the system clari
    <tr>
      <td><strong>L3</strong><br>(Important Perf & Integration & Accuracy)</td>
      <td>Online & Offline (multiple deployment scenarios):<br>real model, normal inference function, normal accuracy</td>
-      <td>Key models + key online/offline scenarios; real weights, Whisper/similarity, preset voice gender, basic accuracy</td>
-      <td>Key features and modules that require launching instances (using real weights)</td>
+      <td>High/medium-priority models + key online/offline scenarios; real weights, Whisper/similarity, preset voice gender, basic accuracy</td>
+      <td>Medium-priority features and component tests that require launching instances</td>
+      <td>Medium-priority interfaces (using random lightweight models)</td>
      <td><code>advanced_model and hardware_test(H100, L4, etc.) and omni/tts/diffusion</code></td>
      <td>&lt;30min</td>
      <td>
@@ -114,8 +120,9 @@ Through five levels (L1-L5) and common (Common) specifications, the system clari
    <tr>
      <td><strong>L4</strong><br>(Perf & Integration & Accuracy)</td>
      <td>Online: full functional scenarios + performance test + doc test + accuracy test</td>
-      <td>Key models: function, performance, accuracy, and doc testing</td>
-      <td>Other features and modules that require launching instances (using real weights)</td>
+      <td>High-priority models: function, performance, accuracy, and doc testing<br>Medium-priority models: function and doc testing</td>
+      <td>Low-priority features and component tests that require launching instances</td>
+      <td>Low-priority interfaces (using real weights)</td>
      <td><code>full_model and hardware_test(H100, L4, etc.) and omni/tts/diffusion</code></td>
      <td>&lt;3 hour</td>
      <td>
@@ -140,10 +147,11 @@ Through five levels (L1-L5) and common (Common) specifications, the system clari
      <td>GPU</td>
    </tr>
    <tr>
-      <td><strong>L5</strong><br>(Stability & Reliability & selected Perf)</td>
-      <td>Online: long-term stability + reliability; coverage test</td>
-      <td>Long-term stability and reliability testing for key models<br>Non-critical scenario performance and accuracy testing for key models<br>Other models: function and doc testing</td>
+      <td><strong>L5</strong><br>(Stability & Reliability)</td>
+      <td>Online: long-term stability test + reliability test</td>
+      <td>Long-term stability and reliability testing for high-priority models<br>Low-priority models: function and doc testing</td>
      <td>/</td>
+      <td>Invalid-parameter validation for high-priority interfaces</td>
      <td><code>slow and hardware_test(H100, L4, etc.) and omni/tts/diffusion</code></td>
      <td> Depends on reality </td>
      <td>
@@ -170,8 +178,8 @@ For per-level test authoring (markers, examples), see [Test Writing Guide](./tes

 Before entering specific testing levels, the project establishes two common specifications aimed at standardizing the development process and quickly locating issues.

-1. ***PR Checklist ([`.github/PULL_REQUEST_TEMPLATE.md`](https://github.com/vllm-project/vllm-omni/blob/main/.github/PULL_REQUEST_TEMPLATE.md))***: This template defines the self-check items that must be completed before submitting a code review (Pull Request). It ensures that each code change meets basic requirements such as code style, dependency updates, and documentation synchronization before entering the automated testing pipeline, serving as the first manual line of defense for quality assurance.
-2. ***CI Failure Explanation ([CI Failures](./failures.md))***: This document archives and explains common failure patterns in the Continuous Integration (CI) pipeline, error log interpretation, and preliminary troubleshooting steps. It helps developers and testers quickly diagnose the causes of automated test failures, improving problem-solving efficiency.
+1.  ***PR Checklist ([`.github/PULL_REQUEST_TEMPLATE.md`](https://github.com/vllm-project/vllm-omni/blob/main/.github/PULL_REQUEST_TEMPLATE.md))***: This template defines the self-check items that must be completed before submitting a code review (Pull Request). It ensures that each code change meets basic requirements such as code style, dependency updates, and documentation synchronization before entering the automated testing pipeline, serving as the first manual line of defense for quality assurance.
+2.  ***CI Failure Explanation ([CI Failures](./failures.md))***: This document archives and explains common failure patterns in the Continuous Integration (CI) pipeline, error log interpretation, and preliminary troubleshooting steps. It helps developers and testers quickly diagnose the causes of automated test failures, improving problem-solving efficiency.

 ## Notes

@@ -17,46 +17,45 @@ Summary:
 - **Reliability:** `tests/dfx/reliability/`
 - Do **not** add new top-level `tests/` directories unrelated to a component (or to `e2e` / `dfx` / `helpers` / `examples` / `buildkite`)

-Deploy YAMLs: `vllm_omni/deploy/` via `tests.helpers.stage_config.get_deploy_config_path` (see [pipeline and deploy configs](../../configuration/stage_configs.md)).
+Deploy YAMLs: `vllm_omni/deploy/` via `tests.helpers.stage_config.get_deploy_config_path` (see [stage configs](../../configuration/stage_configs.md)).

 ## Markers for Tests

 By adding markers before test functions, tests can later be executed uniformly by simply declaring the corresponding marker type.

 ### Current Markers
-
 Defined in `pyproject.toml`:

-| Marker             | Description                                                                                             |
-| ------------------ | ------------------------------------------------------------------------------------------------------- |
-| `core_model`       | L1&L2 tests (run in each PR)                                                                            |
-| `advanced_model`   | L3 tests (run on each merge to main)                                                                    |
-| `full_model`       | L4 tests (run nightly)                                                                                  |
-| `diffusion`        | Diffusion model tests                                                                                   |
-| `omni`             | Omni multimodal model tests                                                                             |
-| `tts`              | TTS model tests                                                                                         |
-| `cache`            | Cache backend tests                                                                                     |
-| `parallel`         | Parallelism/distributed tests                                                                           |
-| `cpu`              | Tests that run on CPU                                                                                   |
-| `gpu`              | Tests that run on GPU *                                                                                 |
-| `cuda`             | Tests that run on CUDA *                                                                                |
-| `rocm`             | Tests that run on AMD/ROCm *                                                                            |
-| `xpu`              | Tests that run on Intel XPU *                                                                           |
-| `npu`              | Tests that run on NPU/Ascend *                                                                          |
-| `H100`             | Tests that require H100 GPU  *                                                                          |
-| `L4`               | Tests that require L4 GPU *                                                                             |
-| `MI325`            | Tests that require MI325 GPU (AMD/ROCm) *                                                               |
-| `A2`               | Tests that require A2 NPU *                                                                             |
-| `A3`               | Tests that require A3 NPU *                                                                             |
-| `distributed_cuda` | Tests that require multi cards on CUDA platform *                                                       |
-| `distributed_rocm` | Tests that require multi cards on ROCm platform  *                                                      |
-| `distributed_npu`  | Tests that require multi cards on NPU platform  *                                                       |
-| `skipif_cuda`      | Skip if the num of CUDA cards is less than the required *                                               |
-| `skipif_rocm`      | Skip if the num of ROCm cards is less than the required *                                               |
-| `skipif_npu`       | Skip if the num of NPU cards is less than the required *                                                |
-| `slow`             | Slow tests (may skip in quick CI)                                                                       |
+| Marker             | Description                                               |
+| ------------------ | --------------------------------------------------------- |
+| `core_model`       | L1&L2 tests (run in each PR)                              |
+| `advanced_model`   | L3 tests (run on each merge to main)                 |
+| `full_model`       | L4 tests (run nightly) |
+| `diffusion`        | Diffusion model tests                                     |
+| `omni`             | Omni multimodal model tests |
+| `tts`              | TTS model tests     |
+| `cache`            | Cache backend tests                                       |
+| `parallel`         | Parallelism/distributed tests                             |
+| `cpu`              | Tests that run on CPU                                     |
+| `gpu`              | Tests that run on GPU *                                   |
+| `cuda`             | Tests that run on CUDA *                                  |
+| `rocm`             | Tests that run on AMD/ROCm *                              |
+| `xpu`              | Tests that run on Intel XPU *                             |
+| `npu`              | Tests that run on NPU/Ascend *                            |
+| `H100`             | Tests that require H100 GPU  *                            |
+| `L4`               | Tests that require L4 GPU *                               |
+| `MI325`            | Tests that require MI325 GPU (AMD/ROCm) *                 |
+| `A2`               | Tests that require A2 NPU *                               |
+| `A3`               | Tests that require A3 NPU *                               |
+| `distributed_cuda` | Tests that require multi cards on CUDA platform *         |
+| `distributed_rocm` | Tests that require multi cards on ROCm platform  *        |
+| `distributed_npu`  | Tests that require multi cards on NPU platform  *         |
+| `skipif_cuda`      | Skip if the num of CUDA cards is less than the required * |
+| `skipif_rocm`      | Skip if the num of ROCm cards is less than the required * |
+| `skipif_npu`       | Skip if the num of NPU cards is less than the required *  |
+| `slow`             | Slow tests (may skip in quick CI)                         |
 | `benchmark`        | Benchmark tests (decorator on runner test functions; perf JSON uses `full_model` + type marker instead) |
-| `local_model`      | Tests requiring local / non-HF-hub model weights                                                        |
+| `local_model`      | Tests requiring local / non-HF-hub model weights          |

 \* Means those markers are auto-added by `@hardware_test` (parametrization decorator) or `hardware_marks` (only returning the list of marks for flexibility).

@@ -82,13 +81,13 @@ This decorator is intended to make hardware-aware, cross-platform test authoring

 1. **Applies platform and resource markers**  
   Adds the appropriate pytest markers for each specified hardware platform (e.g., `cuda`, `rocm`, `xpu`, `npu`) and resource type (e.g., `L4`, `H100`, `MI325`, `B60`, `A2`, `A3`).
-   ```python
+   ```
   @pytest.mark.cuda
   @pytest.mark.L4
   ```
 2. **Handles multi-card (distributed) scenarios**  
   For tests requiring multiple cards, it automatically adds distributed markers such as `distributed_cuda`, `distributed_rocm`, or `distributed_npu`.
-   ```python
+   ```
   @pytest.mark.distributed_cuda(num_cards=num_cards)
   ```
 3. **Supports flexible card requirements**  
@@ -98,11 +97,11 @@ This decorator is intended to make hardware-aware, cross-platform test authoring
   On CUDA, adds a skip marker (`skipif_cuda`) if the system does not have the required number of devices.
   Support for `skipif_rocm` and `skipif_npu` will be implemented later.

+
 5. **Works with pytest filtering**  
   Allows tests to be filtered and selected at runtime using standard pytest marker expressions (e.g., `-m "distributed_cuda and L4"`).

 ##### Example usage for decorator
-
 - Single call for multiple platforms:
    ```python
    @hardware_test(
@@ -221,7 +220,6 @@ If you want to add support for a new platform (e.g., "tpu" for a new accelerator
   ```

 **Summary**:  
-
 - Add pytest markers for your new platform/resources  
 - Implement a marker function (`xxx_marks`)  
 - Plug into `hardware_marks`  
@@ -239,46 +237,47 @@ L1 and L2 level testing form the foundation of the quality assurance system. L1

 L2 level testing builds upon L1 by introducing GPU resources and verifying that the end-to-end (E2E) process of the model in basic deployment scenarios is smooth. For example, it uses dummy models to confirm that core interfaces like the inference pipeline, output format, and streaming response work properly. The common goal of these two levels is to provide developers with rapid feedback, discovering and fixing issues early in the development cycle.

+
+
 #### 1.2 Testing Content and Scope

- ***L1 (Unit & Logic Testing)***:
-    - ***Scope***: Tests internal functions and methods of core components such as `entrypoints`, `models`.
-        - ***Focus***: Branch coverage, exception handling, algorithm logic correctness. Does not involve external dependencies or the complete service stack.
-        - ***Time Cost***: Execution time is controlled within ***15 minutes*** to ensure fast feedback.
- ***L2 (Basic End-to-End Testing)***:
-    - ***Scope***: Covers two basic deployment scenarios: `online` (serving) and `offline` (inference).
-        - ***Focus***: Uses `dummy` weights (via deploy YAML patching at `core_model`) or lightweight real models to verify that the entire chain from request input to result output works normally, including output data structure, streaming (stream) support, and **cheap payload checks** at `--run-level core_model` (see below). Also includes some unit tests that require launching independent service instances.
-        - ***L2 response validation (`core_model`)***: Implemented in `tests/helpers/assertions.py` and invoked by `OpenAIClientHandler` based on `--run-level`. At L2 we require **request success** plus minimal output sanity—not full accuracy:
-            - **Speech / TTS** (`assert_audio_speech_response`): decoded audio must be present and non-empty (or exceed `min_audio_bytes` when set in `request_config`); `response_format` must match the returned content-type (e.g. `wav`, `pcm`). Whisper transcript similarity, PCM HNR, and preset-voice gender checks run only at L3+.
-            - **Diffusion** (`assert_diffusion_response`): at least one non-empty image, video, or audio artifact. Resolution/frame-count parity and other deep checks run only at L3+.
-            - **Omni multimodal** (`assert_omni_response`): L2 asserts successful completion; keyword, transcript, and cross-modal similarity checks run only at L3+.
-        - ***Characteristic***: Requires ***GPU*** resources to perform model computations.
+-   ***L1 (Unit & Logic Testing)***:
+-   -   ***Scope***: Tests internal functions and methods of core components such as `entrypoints`, `models`.
+    -   ***Focus***: Branch coverage, exception handling, algorithm logic correctness. Does not involve external dependencies or the complete service stack.
+    -   ***Time Cost***: Execution time is controlled within ***15 minutes*** to ensure fast feedback.
+-   ***L2 (Basic End-to-End Testing)***:
+-   -   ***Scope***: Covers two basic deployment scenarios: `online` (serving) and `offline` (inference).
+    -   ***Focus***: Uses `dummy` weights (via deploy YAML patching at `core_model`) or lightweight real models to verify that the entire chain from request input to result output works normally, including output data structure, streaming (stream) support, and **cheap payload checks** at `--run-level core_model` (see below). Also includes some unit tests that require launching independent service instances.
+    -   ***L2 response validation (`core_model`)***: Implemented in `tests/helpers/assertions.py` and invoked by `OpenAIClientHandler` based on `--run-level`. At L2 we require **request success** plus minimal output sanity—not full accuracy:
+        -   **Speech / TTS** (`assert_audio_speech_response`): decoded audio must be present and non-empty (or exceed `min_audio_bytes` when set in `request_config`); `response_format` must match the returned content-type (e.g. `wav`, `pcm`). Whisper transcript similarity, PCM HNR, and preset-voice gender checks run only at L3+.
+        -   **Diffusion** (`assert_diffusion_response`): at least one non-empty image, video, or audio artifact. Resolution/frame-count parity and other deep checks run only at L3+.
+        -   **Omni multimodal** (`assert_omni_response`): L2 asserts successful completion; keyword, transcript, and cross-modal similarity checks run only at L3+.
+    -   ***Characteristic***: Requires ***GPU*** resources to perform model computations.

 #### 1.3 Test Directory and Execution Files

 A clear directory structure is key to managing test cases efficiently. See the **Test Dir** column in [Test System Overview](./test_system_overview.md) for the canonical placement rules.

- ***L1 (component / unit)***: `tests/{component_name}/…` mirroring `vllm_omni/{component_name}/` (e.g. `tests/diffusion/`, `tests/entrypoints/`). Do **not** invent new top-level `tests/` folders unrelated to a component.
- ***L2 (basic model E2E)***:
-    - Online serving: `tests/e2e/online_serving/test_{model_name}.py`
-    - Offline inference: `tests/e2e/offline_inference/test_{model_name}.py`
- ***Feature-level integration*** (cross-cutting, not a single-model smoke): `tests/e2e/features/<feature>/` (e.g. `fullduplex/`, `custom_pipeline/`, `rlhf_test/`).
+-   ***L1 (component / unit)***: `tests/{component_name}/…` mirroring `vllm_omni/{component_name}/` (e.g. `tests/diffusion/`, `tests/entrypoints/`). Do **not** invent new top-level `tests/` folders unrelated to a component.
+-   ***L2 (basic model E2E)***:
+    -   Online serving: `tests/e2e/online_serving/test_{model_name}.py`
+    -   Offline inference: `tests/e2e/offline_inference/test_{model_name}.py`
+-   ***Feature-level integration*** (cross-cutting, not a single-model smoke): `tests/e2e/features/<feature>/` (e.g. `fullduplex/`, `custom_pipeline/`, `rlhf_test/`).

 #### 1.4 Execution Method and Example

- ***Trigger Timing***: **`PR with ready label`**. That is, when a developer adds a "ready for review" or similar label to a PR on platforms like GitHub, L1 and L2 tests are automatically triggered.
- ***Diff-aware step skipping***: On L2, **E2E Test** jobs may be omitted at pipeline upload when the PR diff does not touch their [`source_file_dependencies`](ci_settings.md#step-filtering) prefixes; non-E2E groups still always upload. See [CI Settings — Diff-aware CI](ci_settings.md#diff-aware-ci).
- ***Execution Environment***: L1 uses ***CPU*** environment; L2 requires ***GPU*** environment.
- ***Script Example***:
+-   ***Trigger Timing***: **`PR with ready label`**. That is, when a developer adds a "ready for review" or similar label to a PR on platforms like GitHub, L1 and L2 tests are automatically triggered.
+-   ***Diff-aware step skipping***: On L2, **E2E Test** jobs may be omitted at pipeline upload when the PR diff does not touch their [`source_file_dependencies`](ci_settings.md#step-filtering) prefixes; non-E2E groups still always upload. See [CI Settings — Diff-aware CI](ci_settings.md#diff-aware-ci).
+-   ***Execution Environment***: L1 uses ***CPU*** environment; L2 requires ***GPU*** environment.
+-   ***Script Example***:

 <details>
 <summary> L1 Test Examples</summary>

 Examples from `tests/model_executor/models/qwen2_5_omni/test_audio_length.py`
-
 ```python
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project

 import pytest

@@ -332,7 +331,6 @@ def test_cap_and_align_mel_length_no_mismatch(repeats, code_len, max_mel_frames)
    if max_mel_frames is not None and int(max_mel_frames) > 0 and int(max_mel_frames) >= repeats:
        assert target_mel_len <= int(max_mel_frames)
 ```
-
 </details>

 <details>
@@ -340,7 +338,7 @@ def test_cap_and_align_mel_length_no_mismatch(repeats, code_len, max_mel_frames)
 You can refer to Test Examples in the L3 section to see example test cases that incorporate both L2 and L3 testing logic.
 </details>

- ***Run Command***:
+-   -   ***Run Command***:

    `pytest -s -v /tests/e2e/online_serving/test_{model_name}.py`
    `pytest -s -v -m 'core_model and cpu' --run-level=core_model`
@@ -353,34 +351,36 @@ L3 level testing executes after code is merged into the main branch. Its core pu

 . It acts as the "quality gatekeeper" for the main branch, ensuring that no merge breaks the core capabilities of the model service. Testing needs to provide clear conclusions within a relatively short time (<30min), balancing test depth with feedback speed.

+
+
 #### 2.2 Testing Content and Scope

- ***Deployment Scenarios***: Covers richer `online` and `offline` deployment configurations, which may include different hardware configurations, batch sizes, concurrency levels, etc.
- ***Core Verification***:
-    1. ***Inference Functionality***: Ensures real models can perform forward computation normally and return results.
-    2. ***Accuracy Compliance***: Verifies that the model's evaluation metrics (e.g., accuracy) meet the expected baseline, preventing code changes from introducing accuracy issues.
-    3. ***Important Performance***: Verifies whether performance (e.g., P99 latency, throughput) in core scenarios meets preset thresholds.
- ***L3 response validation (`advanced_model`)***: At `--run-level advanced_model`, `tests/helpers/assertions.py` adds semantic checks on top of L2 payload gates (see L1 & L2 above):
-    - **Speech / TTS** (`assert_audio_speech_response`): Whisper transcript of returned audio vs `request_config["input"]` (cosine similarity &gt; 0.9 when input text is set); optional `min_audio_bytes` floor; PCM harmonic-to-noise ratio when `response_format` is `pcm`; **preset voice gender** via `_assert_preset_voice_gender_from_audio` when `voice` matches a known preset in `_PRESET_VOICE_GENDER_MAP` (pitch/F0-based classifier; skipped for unknown voices or `pcm` output).
-    - **Omni multimodal** (`assert_omni_response`): non-empty text/audio outputs; `key_words` in transcript or text; text–audio similarity / containment; preset **`speaker`** gender check (same helper as TTS).
-    - **Diffusion** (`assert_*_diffusion_response`): image/video dimension and frame-count parity with request parameters where configured.
-    - **Accuracy suites**: pixel/video similarity and metric baselines under `/tests/e2e/accuracy/` (separate from inline helper assertions).
+-   ***Deployment Scenarios***: Covers richer `online` and `offline` deployment configurations, which may include different hardware configurations, batch sizes, concurrency levels, etc.
+-   ***Core Verification***:
+-   1.  ***Inference Functionality***: Ensures real models can perform forward computation normally and return results.
+    2.  ***Accuracy Compliance***: Verifies that the model's evaluation metrics (e.g., accuracy) meet the expected baseline, preventing code changes from introducing accuracy issues.
+    3.  ***Important Performance***: Verifies whether performance (e.g., P99 latency, throughput) in core scenarios meets preset thresholds.
+-   ***L3 response validation (`advanced_model`)***: At `--run-level advanced_model`, `tests/helpers/assertions.py` adds semantic checks on top of L2 payload gates (see L1 & L2 above):
+    -   **Speech / TTS** (`assert_audio_speech_response`): Whisper transcript of returned audio vs `request_config["input"]` (cosine similarity &gt; 0.9 when input text is set); optional `min_audio_bytes` floor; PCM harmonic-to-noise ratio when `response_format` is `pcm`; **preset voice gender** via `_assert_preset_voice_gender_from_audio` when `voice` matches a known preset in `_PRESET_VOICE_GENDER_MAP` (pitch/F0-based classifier; skipped for unknown voices or `pcm` output).
+    -   **Omni multimodal** (`assert_omni_response`): non-empty text/audio outputs; `key_words` in transcript or text; text–audio similarity / containment; preset **`speaker`** gender check (same helper as TTS).
+    -   **Diffusion** (`assert_*_diffusion_response`): image/video dimension and frame-count parity with request parameters where configured.
+    -   **Accuracy suites**: pixel/video similarity and metric baselines under `/tests/e2e/accuracy/` (separate from inline helper assertions).

 #### 2.3 Test Directory and Execution Files

- ***Functional / model E2E***:
-    - Online serving: `tests/e2e/online_serving/test_{model_name}_expansion.py`
-    - Offline inference: `tests/e2e/offline_inference/test_{model_name}_expansion.py`
-    - Accuracy / similarity: `tests/e2e/accuracy/`
-    - (`_expansion.py` holds broader scenario coverage than the L2 smoke file.)
- ***Feature-level integration***: `tests/e2e/features/<feature>/` (not under a new top-level `tests/` directory).
+-   ***Functional / model E2E***:
+    -   Online serving: `tests/e2e/online_serving/test_{model_name}_expansion.py`
+    -   Offline inference: `tests/e2e/offline_inference/test_{model_name}_expansion.py`
+    -   Accuracy / similarity: `tests/e2e/accuracy/`
+    -   (`_expansion.py` holds broader scenario coverage than the L2 smoke file.)
+-   ***Feature-level integration***: `tests/e2e/features/<feature>/` (not under a new top-level `tests/` directory).

 #### 2.4 Execution Method and Example

- ***Trigger Timing***: **`PR Merged`**. Automatically triggered after code review is approved and merged into the main branch (typically via `merge-test` label on the PR before merge).
- ***Diff-aware step skipping***: Same [`source_file_dependencies`](ci_settings.md#step-filtering) mechanism as L2—**all E2E Test** leaf steps are diff-gated; other L3 groups always upload. See [CI Settings — Diff-aware CI](ci_settings.md#diff-aware-ci).
- ***Execution Environment***: ***GPU*** servers.
- ***Script Example***:
+-   ***Trigger Timing***: **`PR Merged`**. Automatically triggered after code review is approved and merged into the main branch (typically via `merge-test` label on the PR before merge).
+-   ***Diff-aware step skipping***: Same [`source_file_dependencies`](ci_settings.md#step-filtering) mechanism as L2—**all E2E Test** leaf steps are diff-gated; other L3 groups always upload. See [CI Settings — Diff-aware CI](ci_settings.md#diff-aware-ci).
+-   ***Execution Environment***: ***GPU*** servers.
+-   ***Script Example***:

 ???+ example "Test Examples"

@@ -496,9 +496,9 @@ L3 level testing executes after code is merged into the main branch. Its core pu

    **Audio output debugging**: Deep validation may transcribe returned audio via `convert_audio_bytes_to_text` (Whisper). If an audio keyword or text–audio similarity assertion fails, set `VLLM_OMNI_KEEP_REQUEST_MEDIA=1` before running pytest to keep the intermediate WAV files for inspection (see [Test helper environment variables](test_system_overview.md#test-helper-environment-variables)).

- ***Run Command (L3 merge)***: `pytest -s -v /tests/e2e/online_serving/test_{model_name}.py -m advanced_model --run-level=advanced_model`
+-   ***Run Command (L3 merge)***: `pytest -s -v /tests/e2e/online_serving/test_{model_name}.py -m advanced_model --run-level=advanced_model`

- ***Run Command (L4 nightly expansion)***: `pytest -s -v /tests/e2e/online_serving/test_{model_name}_expansion.py -m full_model --run-level=full_model`
+-   ***Run Command (L4 nightly expansion)***: `pytest -s -v /tests/e2e/online_serving/test_{model_name}_expansion.py -m full_model --run-level=full_model`

 ### L4 Level Testing - Full Functionality, Performance, and Documentation Testing

@@ -506,25 +506,27 @@ L3 level testing executes after code is merged into the main branch. Its core pu

 L4 level testing is a comprehensive quality audit before a version release. It expands upon L3, executing ***full*** functional scenarios, conducting systematic ***performance stress tests***, and simultaneously verifying the correctness of accompanying ***example documentation***. Its purpose is to perform deep validation of the system during off-peak nighttime hours, providing quality trend reports for daytime development and data support for release decisions.

+
+
 #### 3.2 Testing Content and Scope

- ***Full Functionality Testing***: Executes all test cases defined in `test_{model_name}_expansion.py`, covering all implemented features, positive flows, boundary conditions, and exception handling.
- ***Performance Testing***: JSON configs under `tests/dfx/perf/tests/` drive Omni, TTS, and diffusion serving benchmarks via `run_benchmark.py` or `run_diffusion_benchmark.py`, measuring throughput, latency, and related metrics under configured workloads.
- ***Documentation Testing***: Verifies whether the example code provided to users is runnable and its results match the description.
+-   ***Full Functionality Testing***: Executes all test cases defined in `test_{model_name}_expansion.py`, covering all implemented features, positive flows, boundary conditions, and exception handling.
+-   ***Performance Testing***: Uses `tests/dfx/perf/tests/test_qwen3_omni_*.json` (Omni), `test_tts.json` / `test_voxcpm2.json` / `test_higgs_audio_v3.json` (TTS), and diffusion configs `tests/dfx/perf/tests/test_*_vllm_omni.json` (passed to `run_benchmark.py` or `run_diffusion_benchmark.py` via `--test-config-file` in nightly **Perf Test** steps) to drive throughput, latency, and memory benchmarks. Each JSON **case** may declare an optional top-level **`mark`** array: exactly one ``hardware_marks`` object plus pytest marker name strings (`full_model`, `omni` / `tts` / `diffusion`, …). Runners attach those marks to each parametrized `(server, benchmark index)` pair so **local** bulk runs can filter with `-m` (for example `-m "full_model and H100 and diffusion"`). Nightly CI perf jobs select workloads by **`--test-config-file`**, not `-m`. Details are in the Performance Tests example below.
+-   ***Documentation Testing***: Verifies whether the example code provided to users is runnable and its results match the description.

 #### 3.3 Test Directory and Execution Files

- ***Functional Testing***: Same directories as L3.
- ***Performance Test Configuration***: `tests/dfx/perf/tests/test_qwen3_omni_*.json`, `test_tts.json`, `test_voxcpm2.json`, `test_higgs_audio_v3.json`, and diffusion configs `tests/dfx/perf/tests/test_*_vllm_omni.json` (e.g. `test_qwen_image_vllm_omni.json`, `test_cosmos3_vllm_omni.json`). Optional per-case `mark` for local `-m` filtering is documented in Section 3.4 Performance Tests.
- ***Documentation Example Tests***:
-    - `tests/examples/online_serving/test_{model_name}.py`
-    - `tests/examples/offline_inference/test_{model_name}.py`
+-   ***Functional Testing***: Same directories as L3.
+-   ***Performance Test Configuration***: `tests/dfx/perf/tests/test_qwen3_omni_*.json`, `test_tts.json`, `test_voxcpm2.json`, `test_higgs_audio_v3.json`, and diffusion configs `tests/dfx/perf/tests/test_*_vllm_omni.json` (e.g. `test_qwen_image_vllm_omni.json`, `test_cosmos3_vllm_omni.json`). Optional per-case `mark` for local `-m` filtering is documented in Section 3.4 Performance Tests.
+-   ***Documentation Example Tests***:
+    -   `tests/examples/online_serving/test_{model_name}.py`
+    -   `tests/examples/offline_inference/test_{model_name}.py`

 #### 3.4 Execution Method and Example

- ***Trigger Timing***: **`Nightly`**, automatically executed every night.
- ***Execution Environment***: ***GPU*** server clusters to meet the resource demands of performance testing.
- ***Script Example***:
+-   ***Trigger Timing***: **`Nightly`**, automatically executed every night.
+-   ***Execution Environment***: ***GPU*** server clusters to meet the resource demands of performance testing.
+-   ***Script Example***:

 ??? example "Test Examples: Documentation Example Tests"

@@ -538,7 +540,7 @@ L4 level testing is a comprehensive quality audit before a version release. It e

    --8<-- "docs/contributing/ci/test_examples/l4_functionality_tests.inc.md"

- ***Run Command***: (Specific commands would depend on the performance testing tool and configuration defined in `nightly.json`).
+-   ***Run Command***: (Specific commands would depend on the performance testing tool and configuration defined in `nightly.json`).

 ### L5 Level Testing - Stability and Reliability Testing

@@ -546,43 +548,40 @@ L4 level testing is a comprehensive quality audit before a version release. It e

 L5 level testing focuses on the performance of model services under ***long-running*** and ***abnormal fault*** scenarios. It aims to uncover deep-seated issues that only manifest under sustained pressure or extreme conditions, such as memory leaks, resource contention, gradual performance degradation, and lack of fault tolerance mechanisms. This is the final, yet crucial, line of defense for ensuring service high availability and production environment robustness.

+
+
 #### 4.2 Testing Content and Scope

- ***Long-term Stability (Stability) Testing***: Uses JSON under `tests/dfx/stability/tests/` (for example `test_qwen3_omni.json` and `test_wan22.json`) to run the service under moderate load for an extended period (e.g., over 12 hours), monitoring whether metrics like memory/VRAM usage, response time, and throughput degrade over time, and whether the service process remains stable.
- ***Reliability Testing***: Uses pytest suites under `tests/dfx/reliability/` to inject controlled faults against a **live** `vllm_omni serve` instance (same **`omni_server` / `omni_server_function`** fixture style as E2E). Current suites emphasize **GPU memory pressure** (CUDA sidecar “memory hog”), **worker / runtime process kill** (`SIGKILL` on `VLLM::Worker` for Qwen3-Omni, `multiprocessing.spawn` for Wan2.2 video workers, or `vLLM-Omni::` for HunyuanImage DiT workers), **large multimodal chat**, **`/v1/videos`**, **`/v1/images/generations`**, or **`/v1/audio/speech`** jobs under OOM, **`/health` → 503** and **fast-fail / non-hanging concurrent** requests after kill, and **OpenAI-style 5xx error contracts** (e.g. text vs text+audio under OOM). **Post-fault recovery** checks exist where enabled (some cases may be `skip` while issues are tracked). See Section 4.3 for file-level responsibilities and Section 4.4 Test Examples (Reliability) for CI markers (`slow`, `hardware_test`, POSIX-only kill).
+-   ***Long-term Stability (Stability) Testing***: Uses JSON under `tests/dfx/stability/tests/` (for example `test_qwen3_omni.json` and `test_wan22.json`) to run the service under moderate load for an extended period (e.g., over 12 hours), monitoring whether metrics like memory/VRAM usage, response time, and throughput degrade over time, and whether the service process remains stable.
+-   ***Reliability Testing***: Uses pytest suites under `tests/dfx/reliability/` to inject controlled faults against a **live** `vllm_omni serve` instance (same **`omni_server` / `omni_server_function`** fixture style as E2E). Current suites emphasize **GPU memory pressure** (CUDA sidecar “memory hog”), **worker / runtime process kill** (`SIGKILL` on `VLLM::Worker` for Qwen3-Omni, `multiprocessing.spawn` for Wan2.2 video workers, or `vLLM-Omni::` for HunyuanImage DiT workers), **large multimodal chat**, **`/v1/videos`**, **`/v1/images/generations`**, or **`/v1/audio/speech`** jobs under OOM, **`/health` → 503** and **fast-fail / non-hanging concurrent** requests after kill, and **OpenAI-style 5xx error contracts** (e.g. text vs text+audio under OOM). **Post-fault recovery** checks exist where enabled (some cases may be `skip` while issues are tracked). See the Reliability `<details>` block in Section 4.4 for file-level responsibilities and CI markers (`slow`, `hardware_test`, POSIX-only kill).

 #### 4.3 Test Directory and Execution Files

- ***Stability Test Configuration***: `tests/dfx/stability/tests/test_qwen3_omni.json`, `tests/dfx/stability/tests/test_wan22.json` (one JSON per model / runner family)
- ***Reliability Test Suite*** (`tests/dfx/reliability/`):
-    - `test_reliability_qwen3_omni.py` — Qwen3-Omni chat / multimodal reliability (GPU OOM, process kill, recovery, error contract under `--async-chunk` vs default).
-    - `test_reliability_wan22.py` — Wan2.2 I2V video API reliability (`/v1/videos` under OOM and process kill, recovery).
-    - `test_reliability_hunyuan_image.py` — HunyuanImage-3.0-Instruct DiT-only reliability (`/v1/images/generations` under OOM and process kill; deploy `hunyuan_image3_dit.yaml`, H100 × 4).
-    - `helpers.py` — Shared primitives used by current suites: raw HTTP probes for `/v1/chat/completions` and `/health`, OpenAI-style error parsing, GPU OOM sidecar (`inject_gpu_oom` / `stop_gpu_oom_hogs`), and `pgrep`-based process-kill injector construction (`make_process_kill_fault_injector`).
-    - `conftest.py` — `fault_injector` and `omni_server_after_fault` / `omni_server_after_fault_function` fixtures to run a callable **after** the server is ready.
-    - `README.md` — Short local run commands for this directory.
+-   ***Stability Test Configuration***: `tests/dfx/stability/tests/test_qwen3_omni.json`, `tests/dfx/stability/tests/test_wan22.json` (one JSON per model / runner family)
+-   ***Reliability Test Suite*** (`tests/dfx/reliability/`):
+    -   `test_reliability_qwen3_omni.py` — Qwen3-Omni chat / multimodal reliability (GPU OOM, process kill, recovery, error contract under `--async-chunk` vs default).
+    -   `test_reliability_wan22.py` — Wan2.2 I2V video API reliability (`/v1/videos` under OOM and process kill, recovery).
+    -   `test_reliability_hunyuan_image.py` — HunyuanImage-3.0-Instruct DiT-only reliability (`/v1/images/generations` under OOM and process kill; deploy `hunyuan_image3_dit.yaml`, H100 × 4).
+    -   `helpers.py` — Shared primitives used by current suites: raw HTTP probes for `/v1/chat/completions` and `/health`, OpenAI-style error parsing, GPU OOM sidecar (`inject_gpu_oom` / `stop_gpu_oom_hogs`), and `pgrep`-based process-kill injector construction (`make_process_kill_fault_injector`).
+    -   `conftest.py` — `fault_injector` and `omni_server_after_fault` / `omni_server_after_fault_function` fixtures to run a callable **after** the server is ready.
+    -   `README.md` — Short local run commands for this directory.

 #### 4.4 Execution Method and Example

- ***Trigger Timing***: **`Weekly`** (weekly) or **`Days before Release`** (several days before a major release). Due to long execution times, the frequency is lower.
- ***Run Command***:
-    - ***Stability***: `pytest -s -v tests/dfx/stability/scripts/test_stability_qwen3_omni.py` or `pytest -s -v tests/dfx/stability/scripts/test_stability_wan22.py` (or add `test_stability_<model>.py` alongside a matching JSON config)
-    - ***Reliability***: `pytest -s -v tests/dfx/reliability/test_reliability_<model>.py -m slow` (current suites: `qwen3_omni`, `wan22`, `hunyuan_image`).
- ***Script Example***:
-
+-   ***Trigger Timing***: **`Weekly`** (weekly) or **`Days before Release`** (several days before a major release). Due to long execution times, the frequency is lower.
+-   ***Execution Environment***: ***GPU*** servers, requiring a stable and exclusive testing environment.
+-   ***Script Example***:
 <details>
 <summary> Test Examples</summary>

-##### Stability
-
-When you want to add L5-level stability test cases, add or extend the appropriate JSON file under `tests/dfx/stability/tests/` (for example `test_qwen3_omni.json` for Omni bench traffic, or `test_wan22.json` for diffusion `/v1/videos` workloads). Pair the JSON with `tests/dfx/stability/scripts/test_stability_<model>.py`. The following illustrates the Qwen3-Omni shape:
+When you want to add L5-level stability test cases, add or extend the appropriate JSON file under `tests/dfx/stability/tests/` (for example `test_qwen3_omni.json` for Omni bench traffic, or `test_wan22.json` for diffusion `/v1/videos` workloads). The following illustrates the Qwen3-Omni shape:

 ```json
 {
    "test_name": "test_qwen3_omni_stability",
    "server_params": {
        "model": "Qwen/Qwen3-Omni-30B-A3B-Instruct",
-        "stage_config_name": "qwen3_omni_moe.yaml"
+        "stage_config_name": "qwen3_omni.yaml"
    },
    "benchmark_params": [
        {
@@ -601,61 +600,108 @@ When you want to add L5-level stability test cases, add or extend the appropriat
 }
 ```

-###### Parameter Explanation
+##### Parameter Explanation

 ***Overview***

 | Field            | Required | Description                                                                 |
 | ---------------- | -------- | --------------------------------------------------------------------------- |
 | test_name        | Yes      | Unique identifier for the stability test case                               |
-| server_params    | Yes      | Server-side configuration parameters (model, deploy configuration, etc.)    |
+| server_params    | Yes      | Server-side configuration parameters (model, stage configuration, etc.)     |
 | benchmark_params | Yes      | Stability benchmark running parameters (supports multiple configurations)   |

-###### server_params Configuration
+##### server_params Configuration

-Basic parameters:
+###### Basic Parameters

 | Parameter         | Required | Example                            | Description                         |
 | ----------------- | -------- | ---------------------------------- | ----------------------------------- |
 | model             | Yes      | "Qwen/Qwen3-Omni-30B-A3B-Instruct" | Model name or path                  |
-| stage_config_name | Yes      | "qwen3_omni_moe.yaml"              | Deploy configuration file name      |
+| stage_config_name | Yes      | "qwen3_omni.yaml"                  | Stage configuration file name       |

-Dynamic configuration (`update` / `delete`) supports incremental modifications based on the basic configuration:
+###### Dynamic Configuration (update/delete)
+
+Supports incremental modifications based on the basic configuration:

 | Operation | Description                          |
 | --------- | ------------------------------------ |
 | update    | Update or add configuration items    |
 | delete    | Delete specified configuration items |

-***Example***: You can refer to Test Examples in L4 §3.4.
+***Example***:
+You can refer to Test Examples in L4 §3.4

-###### benchmark_params Configuration
+##### benchmark_params Configuration

 For stability testing, the key parameters are:

- **duration_sec**: Total duration (in seconds) during which benchmark traffic is sent. The stability benchmark will keep sending batches until this duration is reached.
- **request_rate** / **max_concurrency**: Exactly one of them must be specified. They control how the traffic is generated for each batch:
-    - `request_rate`: Number of requests per second. The benchmark will send `num_prompts_per_batch` requests at the given rate.
-    - `max_concurrency`: Maximum number of concurrent requests. When this is used, `request_rate` is set to `inf` internally.
- **num_prompts_per_batch**: Number of prompts sent in each batch. Multiple batches will be executed sequentially within `duration_sec`.
+-   **duration_sec**: Total duration (in seconds) during which benchmark traffic is sent. The stability benchmark will keep sending batches until this duration is reached.
+-   **request_rate** / **max_concurrency**: Exactly one of them must be specified. They control how the traffic is generated for each batch:
+    -   `request_rate`: Number of requests per second. The benchmark will send `num_prompts_per_batch` requests at the given rate.
+    -   `max_concurrency`: Maximum number of concurrent requests. When this is used, `request_rate` is set to `inf` internally.
+-   **num_prompts_per_batch**: Number of prompts sent in each batch. Multiple batches will be executed sequentially within `duration_sec`.

 All other optional parameters follow the same rules as in L4 §3.4.

-##### Reliability
+</details>

-Add pytest modules under `tests/dfx/reliability/` (for example `test_reliability_qwen3_omni.py`, `test_reliability_wan22.py`, `test_reliability_hunyuan_image.py`). Reuse `helpers.py` and `conftest.py` rather than duplicating OOM / process-kill / raw HTTP plumbing.
+<details>
+<summary> Reliability test suite (<code>tests/dfx/reliability</code>)</summary>

-###### Parametrization and markers
+##### Purpose and relationship to stability
+
+Reliability tests are **short fault-injection** integration runs (L5 **(b)** in `tests/dfx/reliability/README.md`). They complement **stability** JSON-driven long runs: instead of hours of steady traffic, they **perturb** the server (GPU OOM sidecar, fatal signals on selected processes) and check **failure mode** and **latency bounds** (e.g. chat or `/v1/videos` must not hang under concurrent fault-time load).
+
+##### Directory layout
+
+| Path | Responsibility |
+| ---- | -------------- |
+| `helpers.py` | Shared helpers used by current reliability suites: raw `POST`/`GET` probes (`/v1/chat/completions`, `/health`), OpenAI error parsing (`extract_openai_error_contract_from_bytes`), GPU OOM sidecar lifecycle (`inject_gpu_oom`, `stop_gpu_oom_hogs`), and process-kill injector builder (`make_process_kill_fault_injector`). |
+| `conftest.py` | Pytest fixtures: indirect `fault_injector`, `omni_server_after_fault` / `omni_server_after_fault_function` (run injector after server is ready, then yield server). |
+| `test_reliability_qwen3_omni.py` | Qwen3-Omni: OOM vs **text vs text+audio** error contract, large multimodal chat under OOM, concurrent pressure, **SIGKILL** on `VLLM::Worker`, `/health` → 503 + fast-fail + concurrent chat; optional OOM recovery scenario (may be skipped while tracked in issues). |
+| `test_reliability_wan22.py` | Wan2.2 I2V: large `/v1/videos` under OOM, **SIGKILL** on `multiprocessing.spawn` chain, health / fast-fail / concurrent video requests; optional recovery test (may be skipped). |
+| `test_reliability_hunyuan_image.py` | HunyuanImage DiT-only: large `/v1/images/generations` under OOM, **SIGKILL** on `vLLM-Omni::` workers and serve/tree targets, health / fast-fail / concurrent image requests; some OOM/recovery cases may be skipped while tracked in issues. |
+| `README.md` | Minimal run / collect examples. |
+
+##### Parametrization and markers

 - Each test module defines a **`RELIABILITY_SCENARIOS`** list (`test_name`, `server_params`: model, `stage_config_name` or diffusion `server_args`, etc.). **`create_reliability_omni_server_params()`** in `tests/dfx/conftest.py` resolves stage paths (including XPU substitutions where applicable) and builds **`OmniServerParams`** lists consumed by **`@pytest.mark.parametrize(..., indirect=True)`** on `omni_server` or `omni_server_function`.
 - Cases are tagged **`@pytest.mark.slow`** for weekly / selective CI. GPU-heavy suites use **`@hardware_test(res={"cuda": "H100"}, num_cards=...)`** (Qwen3-Omni **2**× H100; Wan2.2 **1**× H100; HunyuanImage DiT **4**× H100).
 - **Process-kill** tests use **`@pytest.mark.skipif(os.name == "nt", ...)`** because injection uses POSIX **`pgrep` / `kill`**.

-###### Adding a new model suite
+##### CI trigger
+
+Weekly Buildkite (`.buildkite/cuda/test-weekly.yml`) runs one step per model suite (trigger: `WEEKLY=1` or PR label `weekly-test`), for example:
+
+| Buildkite step | Test file | CI hardware |
+| -------------- | --------- | ----------- |
+| Reliability Test - qwen3-omni | `test_reliability_qwen3_omni.py` | H100 × 2 (`mithril-h100-pool`) |
+| Reliability Test - wan22 | `test_reliability_wan22.py` | H100 × 2 (`mithril-h100-pool`) |
+| Reliability Test - hunyuan-image | `test_reliability_hunyuan_image.py` | H100 × 4 (`mithril-h100-pool`) |
+
+```bash
+pytest -s -v tests/dfx/reliability/test_reliability_qwen3_omni.py -m "slow"
+pytest -s -v tests/dfx/reliability/test_reliability_wan22.py -m "slow"
+pytest -s -v tests/dfx/reliability/test_reliability_hunyuan_image.py -m "slow"
+```
+
+##### Local commands
+
+```bash
+pytest --collect-only tests/dfx/reliability
+pytest -s -v tests/dfx/reliability/test_reliability_qwen3_omni.py -m slow
+pytest -s -v tests/dfx/reliability/test_reliability_wan22.py -m slow
+pytest -s -v tests/dfx/reliability/test_reliability_hunyuan_image.py -m slow
+```
+
+##### Adding a new model suite

 1. Add `test_reliability_<model>.py` under `tests/dfx/reliability/`.
-2. Define **`RELIABILITY_SCENARIOS`** and pass them through **`create_reliability_omni_server_params()`** with the correct deploy or e2e deploy-config directory (same pattern as existing files).
-3. Reuse **`helpers`** for OOM / kill / raw HTTP; prefer **`assert_fault_exception()`** and **`resolve_oom_device_spec()`** from `tests/dfx/conftest.py` for consistent device selection vs deploy YAML.
+2. Define **`RELIABILITY_SCENARIOS`** and pass them through **`create_reliability_omni_server_params()`** with the correct deploy or e2e stage-config directory (same pattern as existing files).
+3. Reuse **`helpers`** for OOM / kill / raw HTTP; prefer **`assert_fault_exception()`** and **`resolve_oom_device_spec()`** from `tests/dfx/conftest.py` for consistent device selection vs stage YAML.
 4. Register **`slow`** (and **`hardware_test`** if needed); extend **`.buildkite/cuda/test-weekly.yml`** when the suite should run in weekly L5.

 </details>
+
+-   -   ***Stability***: `pytest -s -v tests/dfx/stability/scripts/test_stability_qwen3_omni.py` or `pytest -s -v tests/dfx/stability/scripts/test_stability_wan22.py` (or add `test_stability_<model>.py` alongside a matching JSON config)
+    -   ***Reliability***: `pytest -s -v tests/dfx/reliability/test_reliability_<model>.py -m slow` (current suites: `qwen3_omni`, `wan22`, `hunyuan_image`; add `test_reliability_<suite>.py` and a matching step in `.buildkite/cuda/test-weekly.yml` for new models)
@@ -9,7 +9,7 @@ This guide walks through the process of adding a new multi-stage model to vLLM-O
 3. [Step-by-Step Implementation](#step-by-step-implementation)
 4. [Key Components](#key-components)
 5. [Model Registration](#model-registration)
-6. [Pipeline and Deploy Configuration](#pipeline-and-deploy-configuration)
+6. [Stage Configuration](#stage-configuration)
 7. [Stage Input Processors](#stage-input-processors)
 8. [Testing](#testing)
 9. [Adding a Model Recipe](#adding-a-model-recipe)
@@ -316,28 +316,18 @@ _OMNI_MODELS = {

 The registry uses lazy loading, so the model class is imported only when needed.

-## Pipeline and Deploy Configuration
+## Stage Configuration

-Define fixed topology in `vllm_omni/model_executor/models/<model>/pipeline.py`
-with `PipelineConfig` and `StagePipelineConfig`, then register it in
-`vllm_omni/config/pipeline_registry.py`. For a complete example, see the
-[Qwen3-Omni pipeline](gh-file:vllm_omni/model_executor/models/qwen3_omni/pipeline.py).
+Create a YAML configuration file in `vllm_omni/deploy/`. For a complete example, see the [Qwen3-Omni configuration file](gh-file:vllm_omni/deploy/qwen3_omni_moe.yaml).

-### Pipeline topology fields
+### Key Configuration Fields

- **`model_stage`**: Logical stage name ("thinker", "talker", "code2wav", etc.)
- **`execution_type`**: Runtime family (`LLM_AR`, `LLM_GENERATION`, or `DIFFUSION`)
- **`model_arch`**: Stage architecture name, when different from the pipeline default
- **`input_sources`**: Upstream stage IDs that provide input to this stage
- **`custom_process_input_func`**: Function that processes inputs from previous stages
- **`final_output`**: Whether this stage produces user-facing output
- **`final_output_type`**: Output modality ("text", "audio", "image", etc.)
- **`owns_tokenizer`**: Whether this stage owns the pipeline tokenizer
-
-Create the matching runtime defaults in `vllm_omni/deploy/<model>.yaml` and set
-`PipelineConfig.default_deploy_config_name` to that file. The deploy YAML owns
-GPU placement, memory sizing, parallelism, connectors, and sampling defaults;
-it must not redefine topology fields.
+- **`model_stage`**: Which stage to run ("thinker", "talker", "code2wav", etc.)
+- **`model_arch`**: The model architecture name (must match registry)
+- **`engine_input_source`**: List of stage IDs that provide input to this stage
+- **`custom_process_input_func`**: Function to process inputs from previous stages
+- **`final_output`**: Whether this stage produces the final output (True/False)
+- **`final_output_type`**: Type of final output ("text", "audio", "image", etc.)

 ## Stage Input Processors

@@ -384,7 +374,7 @@ The stage transition process follows these steps:

 2. **Transition Detection**: The orchestrator checks if there's a next stage and calls `process_engine_inputs()` on it

-3. **Input Processing**: The stage input processor registered by the pipeline (implemented under `vllm_omni/model_executor/stage_input_processors/`) handles the transition:
+3. **Input Processing**: The stage input processor configured in stage YAML (under `vllm_omni/model_executor/stage_input_processors/`) handles the transition:
   ```python
   def process_engine_inputs(
       self, stage_list: list[Any], prompt: OmniTokensPrompt | TextPrompt = None
@@ -587,7 +577,7 @@ Adding a new model to vLLM-Omni involves:
 1. **Create model directory structure** with stage implementations
 2. **Implement unified model class** that orchestrates stages
 3. **Register model** in `registry.py`
-4. **Define pipeline topology and deploy defaults** in `pipeline.py` and `vllm_omni/deploy/`
+4. **Create stage configuration** YAML file
 5. **Implement stage input processors** for stage transitions
 6. **Write tests** to verify functionality
 7. **Add model recipe** to the [vllm-project/recipes](https://github.com/vllm-project/recipes) repository (see [Adding a Model Recipe](#adding-a-model-recipe) section)
@@ -600,8 +590,7 @@ For a complete reference implementation, see:
 - **Thinker**: `vllm_omni/model_executor/models/qwen3_omni/qwen3_omni_moe_thinker.py`
 - **Talker**: `vllm_omni/model_executor/models/qwen3_omni/qwen3_omni_moe_talker.py`
 - **Code2Wav**: `vllm_omni/model_executor/models/qwen3_omni/qwen3_omni_code2wav.py`
- **Pipeline topology**: `vllm_omni/model_executor/models/qwen3_omni/pipeline.py`
- **Deploy config**: `vllm_omni/deploy/qwen3_omni_moe.yaml`
+- **Stage config**: `vllm_omni/deploy/qwen3_omni_moe.yaml`
 - **Input processors**: `vllm_omni/model_executor/stage_input_processors/qwen3_omni.py`
 - **Registry**: `vllm_omni/model_executor/models/registry.py`
 - **Testing**: `vllm_omni/tests/e2e/offline_inference/test_qwen3_omni.py`
@@ -609,4 +598,4 @@ For a complete reference implementation, see:
 For more information, see:
 - [Architecture Overview](../../design/architecture_overview.md)
 - [Supported Models](../../models/supported_models.md)
- [Pipeline and Deploy Configuration Guide](../../configuration/stage_configs.md)
+- [Stage Configuration Guide](../../configuration/stage_configs.md)
@@ -20,7 +20,7 @@ pattern, refer to MOSS-TTS-Nano.
 4. [Step-by-Step Implementation](#step-by-step-implementation)
 5. [Key Components](#key-components)
 6. [Model Registration](#model-registration)
-7. [Pipeline and Deploy Configuration](#pipeline-and-deploy-configuration)
+7. [Stage Configuration](#stage-configuration)
 8. [Stage Input Processors](#stage-input-processors)
 9. [Online Serving Integration](#online-serving-integration)
 10. [Single-Stage Models](#single-stage-models)
@@ -78,7 +78,7 @@ Profile before optimizing.
 new TTS model must pass all three levels:

 | Layer | Catches | Tool |
-| ------- | --------- | ------ |
+|-------|---------|------|
 | Offline RTF / duration | Throughput regressions, missing audio, wrong sample rate | `end2end.py`, pytest e2e |
 | Browser streaming playback | Delta-vs-cumulative bugs, chunk boundary glitches, TTFP regressions | Gradio demo over `/v1/audio/speech?stream=true` |
 | Concurrent requests | Per-request state leaks, codec window round-robin gaps | `max_num_seqs>1` smoke with 4+ parallel prompts |
@@ -94,10 +94,10 @@ the symptom is crosstalk or truncation under load, nothing in single-request tes
 vLLM-Omni supports TTS models as multi-stage pipelines where each stage runs independently
 and can be placed on different devices. Qwen3-TTS has two stages:

-| Stage | Name                | Input           | Output                   |
-| ----- | ------------------- | --------------- | ------------------------ |
-| 0     | Code Predictor (AR) | Text tokens     | Discrete RVQ codec codes |
-| 1     | Code2Wav (Decoder)  | RVQ codec codes | Audio waveform           |
+| Stage | Name | Input | Output |
+|-------|------|-------|--------|
+| 0 | Code Predictor (AR) | Text tokens | Discrete RVQ codec codes |
+| 1 | Code2Wav (Decoder) | RVQ codec codes | Audio waveform |

 Each stage is a separate model class configured independently via YAML. The two stages
 are connected by the `async_chunk` framework, which enables inter-stage streaming for
@@ -170,7 +170,7 @@ and Qwen3-Omni).

 When adding a new TTS model, create the following structure:

-```text
+```
 vllm_omni/model_executor/models/
  your_model_name/
    __init__.py
@@ -201,7 +201,7 @@ it would not be picked up — the hub README is the documented surface.
 **Qwen3-TTS reference files:**

 | File | Purpose |
-| ------ | --------- |
+|------|---------|
 | `models/qwen3_tts/qwen3_tts.py` | Unified model class |
 | `models/qwen3_tts/qwen3_tts_code_predictor_vllm.py` | Stage 0 - optimized AR |
 | `models/qwen3_tts/qwen3_tts_code2wav.py` | Stage 1 - decoder |
@@ -427,92 +427,111 @@ _OMNI_MODELS = {

 The registry uses lazy loading - model classes are only imported when needed.

-## Pipeline and Deploy Configuration
+## Stage Configuration

-Define fixed topology in `models/<model>/pipeline.py`. The execution type
-selects the scheduler and worker family:
+Each stage has a `worker_type` that determines how it is scheduled:

- `StageExecutionType.LLM_AR` uses the autoregressive runtime with PagedAttention.
- `StageExecutionType.LLM_GENERATION` uses the generation runtime for stages such as audio decoders.
+- `worker_type: ar` - autoregressive stage, uses `OmniARScheduler` with PagedAttention
+- `worker_type: generation` - non-AR stage (e.g. decoder), uses `OmniGenerationScheduler`

-Key topology fields belong to `StagePipelineConfig`:
+Key configuration fields:

 | Field | Description |
 |-------|-------------|
-| `model_stage` | Logical stage name (`ar_stage`, `decoder`, etc.). |
-| `execution_type` | Runtime family for this stage. |
-| `input_sources` | Upstream stage IDs that provide input. |
-| `model_arch` | Stage-specific architecture name, when it differs from the pipeline default. |
-| `engine_output_type` | Output representation such as `latent` or `audio`. |
-| `custom_process_next_stage_input_func` | Processor for full-payload stage handoff. |
-| `async_chunk_process_next_stage_input_func` | Processor for streaming chunk handoff. |
-| `final_output` / `final_output_type` | Whether this stage produces user-facing output and its modality. |
-| `owns_tokenizer` | Whether this stage supplies the pipeline tokenizer. |
+| `model_stage` | Which stage to initialize (`ar_stage`, `decoder`, etc.) |
+| `model_arch` | Architecture name, must match `registry.py` |
+| `engine_input_source` | List of upstream stage IDs that provide input (e.g. `[0]`) |
+| `engine_output_type` | Output type: `latent` for intermediate, `audio` for final |
+| `custom_process_next_stage_input_func` | Async chunk processor function path (streaming only) |
+| `final_output` | Whether this stage produces the final user-facing output |
+| `final_output_type` | Type of final output (`audio`, `text`, etc.) |

-For example, a two-stage TTS topology can be defined as:
+!!! note
+    New in-tree models should define frozen topology in `models/<model>/pipeline.py`,
+    register it in `vllm_omni/config/pipeline_registry.py`, and put deployment
+    knobs in `vllm_omni/deploy/<model>.yaml`. Use `--deploy-config` to load a
+    custom deployment YAML.

-```python
-from vllm_omni.config.stage_config import (
-    PipelineConfig,
-    StageExecutionType,
-    StagePipelineConfig,
-)
-
-_PROC = "vllm_omni.model_executor.stage_input_processors.your_model_name"
-
-YOUR_TTS_PIPELINE = PipelineConfig(
-    model_type="your_model_name",
-    default_deploy_config_name="your_model_name.yaml",
-    model_arch="YourTTSModelForConditionalGeneration",
-    stages=(
-        StagePipelineConfig(
-            stage_id=0,
-            model_stage="ar_stage",
-            execution_type=StageExecutionType.LLM_AR,
-            input_sources=(),
-            owns_tokenizer=True,
-            engine_output_type="latent",
-            custom_process_next_stage_input_func=f"{_PROC}.ar2decoder",
-            async_chunk_process_next_stage_input_func=f"{_PROC}.ar2decoder_async_chunk",
-        ),
-        StagePipelineConfig(
-            stage_id=1,
-            model_stage="decoder",
-            execution_type=StageExecutionType.LLM_GENERATION,
-            input_sources=(0,),
-            model_arch="YourTTSDecoder",
-            engine_output_type="audio",
-            final_output=True,
-            final_output_type="audio",
-        ),
-    ),
-)
-```
-
-Register the pipeline in `vllm_omni/config/pipeline_registry.py`. Runtime
-placement and sizing belong in `vllm_omni/deploy/your_model_name.yaml`:
+### Batch mode

 ```yaml
-async_chunk: true
+# stage_configs/your_model_name.yaml

-stages:
+stage_args:
  - stage_id: 0
-    devices: "0"
-    max_num_seqs: 64
+    stage_type: llm
+    runtime:
+      devices: "0"
+    engine_args:
+      model_stage: ar_stage
+      max_num_seqs: 64
+      model_arch: YourTTSModelForConditionalGeneration
+      worker_type: ar
+      scheduler_cls: vllm_omni.core.sched.omni_ar_scheduler.OmniARScheduler
+      engine_output_type: latent
    default_sampling_params:
      temperature: 0.9
      top_k: 50
      max_tokens: 2048

  - stage_id: 1
-    devices: "0"
-    max_num_seqs: 1
+    stage_type: llm
+    runtime:
+      devices: "0"
+    engine_args:
+      model_stage: decoder
+      model_arch: YourTTSModelForConditionalGeneration
+      worker_type: generation
+      scheduler_cls: vllm_omni.core.sched.omni_generation_scheduler.OmniGenerationScheduler
+      engine_output_type: audio
+    engine_input_source: [0]
+    final_output: true
+    final_output_type: audio
 ```

-Set `async_chunk: false` for end-to-end handoff. The registered pipeline
-selects the full-payload or async chunk processor; processor paths and topology
-must not be moved into the deploy YAML. Use `--deploy-config` to load a custom
-deployment overlay.
+### Streaming mode (async_chunk)
+
+Add `async_chunk: true` at the top level and specify `custom_process_next_stage_input_func`
+on Stage 0 to define how intermediate outputs are chunked and forwarded:
+
+```yaml
+# stage_configs/your_model_name_async_chunk.yaml
+
+async_chunk: true
+
+stage_args:
+  - stage_id: 0
+    stage_type: llm
+    runtime:
+      devices: "0"
+    engine_args:
+      model_stage: ar_stage
+      max_num_seqs: 64
+      model_arch: YourTTSModelForConditionalGeneration
+      worker_type: ar
+      scheduler_cls: vllm_omni.core.sched.omni_ar_scheduler.OmniARScheduler
+      engine_output_type: latent
+      custom_process_next_stage_input_func: >
+        vllm_omni.model_executor.stage_input_processors.your_model_name.ar2decoder_async_chunk
+    default_sampling_params:
+      temperature: 0.9
+      top_k: 50
+      max_tokens: 2048
+
+  - stage_id: 1
+    stage_type: llm
+    runtime:
+      devices: "0"
+    engine_args:
+      model_stage: decoder
+      model_arch: YourTTSModelForConditionalGeneration
+      worker_type: generation
+      scheduler_cls: vllm_omni.core.sched.omni_generation_scheduler.OmniGenerationScheduler
+      engine_output_type: audio
+    engine_input_source: [0]
+    final_output: true
+    final_output_type: audio
+```

 ## Stage Input Processors

@@ -528,9 +547,9 @@ Understanding what's available in stage outputs:
 - `stage_list[source_id].engine_outputs` - list of `EngineCoreOutput` objects
 - Each `EngineCoreOutput` has `outputs` - list of `RequestOutput` objects
 - Each `RequestOutput` has:
-    - `token_ids` - generated token IDs
-    - `multimodal_output` - dict with keys matching your model's `OmniOutput.multimodal_outputs`
-    - `prompt_token_ids` - original prompt token IDs
+  - `token_ids` - generated token IDs
+  - `multimodal_output` - dict with keys matching your model's `OmniOutput.multimodal_outputs`
+  - `prompt_token_ids` - original prompt token IDs

 ### Batch mode (non-streaming)

@@ -610,7 +629,6 @@ def ar2decoder_async_chunk(
 ```

 Key points:
-
 - `transfer_manager` is the `OmniChunkTransferAdapter` that owns the chunk lifecycle
 - Each call appends one AR decode step's output; a chunk is emitted every `chunk_size` steps
 - The final (possibly partial) chunk is flushed when `is_finished` is true
@@ -665,7 +683,6 @@ Create `vllm_omni/entrypoints/openai/tts_adapters/your_model.py`:

 ```python
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """YourModel serving adapter."""

 from typing import TYPE_CHECKING
@@ -804,7 +821,7 @@ directly from the model's own generator.

 ### Directory structure

-```text
+```
 vllm_omni/model_executor/models/your_model_name/
    __init__.py
    modeling_your_model_name.py    # unified class: load_weights + forward + streaming
@@ -815,40 +832,32 @@ vllm_omni/deploy/your_model_name.yaml

 No stage input processor is needed.

-### Pipeline and deploy config
+### Stage config

-Use a single `LLM_AR` stage that owns the tokenizer and produces final audio:
-
-```python
-YOUR_TTS_PIPELINE = PipelineConfig(
-    model_type="your_model_name",
-    default_deploy_config_name="your_model_name.yaml",
-    model_arch="YourModelForCausalLM",
-    stages=(
-        StagePipelineConfig(
-            stage_id=0,
-            model_stage="your_model_stage_key",
-            execution_type=StageExecutionType.LLM_AR,
-            input_sources=(),
-            owns_tokenizer=True,
-            engine_output_type="audio",
-            final_output=True,
-            final_output_type="audio",
-        ),
-    ),
-)
-```
-
-The deploy YAML controls runtime behavior. Set `max_num_seqs` to at least 4
-for concurrent production use:
+Use a single stage with `worker_type: ar`. The `is_comprehension: true` field and the
+top-level `async_chunk: false` are required — omitting them causes silent
+misclassification in the serving layer. Set `max_num_seqs` to at least 4 for
+concurrent production use.

 ```yaml
+# stage_configs/your_model_name.yaml
 async_chunk: false

-stages:
+stage_args:
  - stage_id: 0
-    devices: "0"
-    max_num_seqs: 4
+    stage_type: llm
+    is_comprehension: true          # required for serving_speech.py dispatch
+    runtime:
+      devices: "0"
+    engine_args:
+      model_stage: your_model_stage_key
+      model_arch: YourModelForCausalLM
+      worker_type: ar
+      scheduler_cls: vllm_omni.core.sched.omni_ar_scheduler.OmniARScheduler
+      engine_output_type: audio
+      max_num_seqs: 4               # min 4 for concurrent requests; default 1 causes gaps
+    final_output: true
+    final_output_type: audio
 ```

 ### Generator-based streaming pattern
@@ -952,17 +961,10 @@ is correct. Stage the modified files and commit again — do not revert the chan
 Common failures and fixes:

 | Check | Cause | Fix |
-| ------- | ------- | ----- |
+|-------|-------|-----|
 | `ruff F841` | Local variable assigned but never used | Remove the extraction or forward it to the model call |
 | `ruff E402` | Module-level import not at top of file | Move import to the top-level import block |
 | `ruff format` | Line length, spacing, or quote style | Accept the auto-fix, stage, and re-commit |
-| `check-spdx-header` | Missing header, or copyright still says `vLLM project` | Use `Copyright contributors to the vLLM-Omni project`; restage the rewrite |
-| `check-forbidden-imports` | Stdlib `re`/`base64`, pickle, Hugging Face Hub API, or direct Triton/TileLang | `import regex as re` and `pybase64`; do not grow the allowlist without review |
-| `check-torch-cuda-call` | New `torch.cuda.*` call site | Use `current_omni_platform`; do not grow `ALLOWED_FILES` without review |
-| `check-tts-adapter-migration` | New `_tts_model_type` branch in `serving_speech.py` | Put logic in `tts_adapters/`; lower `MAX_MODEL_TYPE_BRANCHES` when removing branches |
-| `check-test-ci-coverage` | Test file missing level or hardware mark | Add `core_model`/… plus `cpu`/`cuda`/`hardware_test(` |
-| `shellcheck` | Native `shellcheck` missing, or script warning | Install via apt/dnf/brew (or `shellcheck.exe` on Windows). See [Linting](../README.md#linting) |
-| `mypy-3.10` / `markdownlint-cli2` / `check-buildkite` | Types, docs markdown, or Buildkite YAML | See [Linting](../README.md#linting) |

 ### DCO sign-off

@@ -1017,7 +1019,7 @@ Adding a TTS model to vLLM-Omni involves:
 ### Qwen3-TTS Reference Files

 | File | Purpose |
-| ------ | --------- |
+|------|---------|
 | `models/qwen3_tts/qwen3_tts.py` | Unified model class |
 | `models/qwen3_tts/qwen3_tts_code_predictor_vllm.py` | AR stage with vLLM fused ops |
 | `models/qwen3_tts/qwen3_tts_code2wav.py` | Decoder stage with `chunked_decode_streaming()` |
@@ -1029,4 +1031,4 @@ For more information, see:

 - [Architecture Overview](../../design/architecture_overview.md)
 - [Async Chunk Design](../../design/feature/async_chunk.md)
- [Pipeline and Deploy Configuration Guide](../../configuration/stage_configs.md)
+- [Stage Configuration Guide](../../configuration/stage_configs.md)
@@ -335,8 +335,8 @@ The single resolution boundary is implemented by
 `StageConfigFactory.create_from_model()` and
 `VllmOmniConfig.from_pipeline_config()` in
 [`vllm_omni/config`](https://github.com/vllm-project/vllm-omni/tree/main/vllm_omni/config).
-The legacy `stage_args` YAML path has been removed. Model topology now resolves
-through `PipelineConfig`, with runtime overrides supplied by `DeployConfig`.
+The legacy `stage_args` YAML path remains only for models that have not yet
+migrated to `PipelineConfig` and `DeployConfig`.

 In the typed path, each stage configuration derives from
 `BaseVllmOmniStageConfig` and is specialized as
@@ -211,39 +211,38 @@ In sequential mode, each stage must wait for the previous stage to complete enti

 ## Configuration

-Enable async chunk mode in the deploy YAML:
+Enable async_chunk in stage configuration YAML:

 ```yaml
 async_chunk: true
+stage_args:
+  - stage_id: 0
+    engine_args:
+      custom_process_next_stage_input_func: vllm_omni.model_executor.stage_input_processors.qwen3_omni.thinker2talker_async_chunk
+  - stage_id: 1
+    engine_args:
+      custom_process_next_stage_input_func: vllm_omni.model_executor.stage_input_processors.qwen3_omni.talker2code2wav_async_chunk
 ```

-The registered `PipelineConfig` owns the async handoff processor functions.
-For Qwen3-Omni these are `thinker2talker_async_chunk` and
-`talker2code2wav_async_chunk`; deploy YAML only selects the mode and runtime
-sizing.
-
-### Configuration ownership
+### Stage Configuration

 - `async_chunk: bool`: Enable/disable async chunk mode
- `async_chunk_process_next_stage_input_func: str`: Pipeline-owned chunk processor path
- `execution_type: StageExecutionType`: Pipeline-owned runtime family
- `connectors: dict`: Deploy-owned connector definitions
+- `custom_process_next_stage_input_func: str`: Path to custom chunk processing function; receives `(transfer_manager, pooling_output, request)`. For qwen3-omni: `thinker2talker_async_chunk`, `talker2code2wav_async_chunk`
+- `stage_connector_config: dict`: Connector configuration
+- `worker_type: str`: Model type, e.g. `"ar"` or `"generation"` (used by OmniChunkTransferAdapter for mode-specific payload handling)
 - `max_num_seqs: int`: Maximum number of sequences for concurrent processing in the stage

+
 ### Connector Configuration

 ```yaml
 connectors:
-  connector_of_shared_memory:
-    name: SharedMemoryConnector
-
-stages:
-  - stage_id: 0
-    output_connectors:
-      to_stage_1: connector_of_shared_memory
-  - stage_id: 1
-    input_connectors:
-      from_stage_0: connector_of_shared_memory
+  - from_stage: 0
+    to_stage: 1
+    spec:
+      name: SharedMemoryConnector
+      extra:
+        stage_id: 0
 ```

 ### Code2Wav Batch Configuration
@@ -251,10 +250,13 @@ stages:
 For optimal performance with async_chunk, the code2wav stage should be configured with batching:

 ```yaml
-stages:
+stage_args:
  - stage_id: 2  # code2wav stage
-    devices: "1"
-    max_num_seqs: 64  # Enables batched audio generation
+    runtime:
+      devices: "1"
+    engine_args:
+      model_stage: code2wav
+      max_num_seqs: 64  # Enables batched audio generation
 ```

 ## Related Files
@@ -124,8 +124,8 @@ When `execute_model_batch` returns a `COMPUTE_DONE` with a single `async_output_
 1. **Drain Before Memory Release (`drain_async_outputs` / `_ASYNC_OUTPUT_DRAIN_TIMEOUT_S`)**:
   When workers transition into sleep states (`handle_sleep_task`) or invoke memory-releasing methods, `WorkerProc.drain_async_outputs()` blocks up to `_ASYNC_OUTPUT_DRAIN_TIMEOUT_S` (10.0s) until all in-flight background D2H/SHM packing tasks finish. This acts as a synchronization barrier preventing worker sleep cycles from releasing device tensors while the side CUDA stream is still actively reading them. Draining typically completes within 10–50 ms under normal operation.

-2. **Timeout Diagnostics (`_async_output_timeout()`)**:
-   The engine waits for `wait_output_ready()` with a timeout of `_async_output_timeout()` — 600.0s by default, overridable per run with the `VLLM_OMNI_ASYNC_OUTPUT_TIMEOUT` environment variable (a non-numeric or non-positive value is ignored with a warning and the default applies, since this resolves on the request path). If a timeout occurs, the executor logs detailed diagnostic bookkeeping (pending futures, cached outputs, and batch split maps) to identify whether the stall occurred in the worker, pump, or waiter. The packing itself takes milliseconds, but the wait is queued behind the step's GPU work, so its wall-clock duration tracks step time; the bound is generous because a hung engine is surfaced by the worker monitor and `check_health()`, not by this timeout.
+2. **Timeout Diagnostics (`_ASYNC_OUTPUT_TIMEOUT`)**:
+   The engine waits for `wait_output_ready()` with a timeout of `_ASYNC_OUTPUT_TIMEOUT` (30.0s). If a timeout occurs, the executor logs detailed diagnostic bookkeeping (pending futures, cached outputs, and batch split maps) to identify whether the stall occurred in the worker, pump, or waiter.

 3. **Queue Serialization & Atomic Future Resolution**:
   - `result_mq` writes are serialized with `_result_mq_lock` to protect the single-writer `MessageQueue` against concurrent writes from the worker main loop (`COMPUTE_DONE`) and background thread (`OUTPUT_READY`).
@@ -61,8 +61,7 @@ unstructured keyword dictionaries:
 - `quant` is consumed by FlashInfer and TRTLLM with backend-specific value
  validation;
 - `skip_softmax` is consumed by TRTLLM; and
- `block_sparse` is consumed by block-sparse backends such as RainFusion; and
- `fastvideo_vsa_topk` is consumed by FastVideo VSA.
+- `block_sparse` is consumed by block-sparse backends such as RainFusion.

 A backend reads only the fields it owns and rejects incompatible values. New
 options should be added to a shared typed spec only when more than one backend
@@ -88,19 +87,3 @@ An implementation change is complete only when it:
   corresponding user guide; and
 6. updates the overview matrix without moving algorithm details back into the
   landing page.
-
-## FastVideo VSA model metadata
-
-FastVideo VSA support is scoped to `FastVideo/FastWan2.2-TI2V-5B-Diffusers`, whose text-to-video and image-to-video modes both use `Wan22Pipeline`. It operates on a flattened DiT sequence but partitions tokens in
-the original latent video grid. Wan integrations therefore attach the
-post-patch `(T, H, W)` shape as `vsa_dit_seq_shape` attention metadata. The
-backend validates that `T * H * W` equals the sequence length, derives the
-runtime block count, and selects the configured top-k key/value blocks for
-each query block.
-
-Checkpoint-specific compensation remains model-owned. Wan layers pass an
-optional learned `gate_compress` projection through attention metadata when
-the checkpoint contains those weights. Checkpoints without the projection do
-not allocate or execute it. When top-k selects every block, native checkpoints
-route to SDPA, while FastVideo DMD checkpoints preserve the VSA all-block path
-to retain checkpoint semantics.
@@ -59,18 +59,19 @@ This `metadata` must be passed through the control plane so `get()` can locate t

 ## Configuration Model

-Define connectors at the top level of the deploy YAML:
+Define connectors in runtime:

 ```yaml
-connectors:
-  connector_of_shared_memory:
-    name: SharedMemoryConnector
+runtime:
+  connectors:
+    connector_of_shared_memory:
+      name: SharedMemoryConnector
 ```

 Wire stages to connectors:

 ```yaml
-stages:
+stage_args:
  - stage_id: 0
    output_connectors:
      to_stage_1: connector_of_shared_memory
@@ -1,386 +0,0 @@
-# Host Weight Runtime
-
-The Host Weight Runtime is a loader-facing feature for reusing immutable,
-runtime-ready model weights across workers on one host. It lets a model
-integration replace repeated checkpoint loading and transformation with an
-exact lookup of a previously published host representation, while keeping the
-canonical model source authoritative.
-
-This feature is shared infrastructure. Diffusion, autoregressive, speech, and
-future model integrations may depend on the top-level
-`vllm_omni.host_weight_runtime` package without depending on one another's
-loader or execution stack. The internal component and filesystem contracts are
-specified in the [Host Weight Runtime module design](../module/host_weight_runtime.md).
-
-## Status
-
-The first implementation provides contracts and a CPU local-filesystem store.
-The initial diffusion consumer contract additionally defines typed,
-representation-independent final-layout identity/restoration mechanics plus a
-concrete BF16-with-preserved-FP32 policy for MiniMax H3. It remains
-library-only: no loader or DLO path selects, publishes, restores, or transports
-that artifact yet.
-
-V1 includes:
-
- exact runtime-weight identity and immutable manifests;
- coordinated local lookup and one-producer publication;
- descriptor-backed safetensors mmap leases;
- preferred and required resolution policy;
- explicit, separately reported post-load publication;
- validation, deny, quarantine, cleanup, and capacity controls; and
- typed reports for every terminal resolution outcome.
-
-V1 does not include:
-
- a public CLI, loader activation, or default-on model integration;
- lease handoff to DLO or another transport consumer;
- FP8, quantized, merged-adaptation, or additional model producers;
- CUDA registration, pinned staging, H2D scheduling, or GPU kernels;
- a remote artifact provider or cross-node coordination;
- automatic eviction; or
- a change to DLO AllGather or no-AllGather behavior.
-
-## Motivation and use cases
-
-Model loading can create the same final host representation repeatedly. This
-is especially expensive when loading performs checkpoint decoding, tensor
-renaming, TP slicing, quantization, packing, or scale construction before GPU
-transfer. Independent workers may then retain private CPU copies of identical
-runtime weights.
-
-The Host Weight Runtime is useful when:
-
- multiple same-node workers request semantically identical final weights;
- constructing those weights is materially more expensive than validating and
-  mapping a local artifact;
- the runtime layout can be identified exactly and reproduced deterministically;
- the workers can share immutable file-backed pages through the OS page cache;
-  and
- canonical loading remains available when policy permits fallback.
-
-Typical consumers include same-node diffusion replicas, DLO host-weight
-sources, and future transformed or quantized model loaders. Request routing and
-replica orchestration remain outside this feature.
-
-This feature is not zero-copy GPU execution. A lease exposes stable CPU tensor
-views and mapped ranges. A separate transport still decides whether to use
-registered mmap, private pinned staging, synchronous copies, or asynchronous
-H2D transfer.
-
-## Resolution behavior
-
-The loader resolves the immutable canonical source and computes the exact
-requested identity before asking the runtime for a representation.
-
-```mermaid
-flowchart TD
-    L["Loader resolves canonical source"] --> I["Compute exact WeightArtifactIdentity"]
-    I --> M{"Runtime mode"}
-    M -->|"disabled"| C["Canonical loader"]
-    M -->|"preferred or required"| A{"Validated local artifact?"}
-    A -->|"yes"| R["Return HostWeightLease"]
-    A -->|"no"| X["Remote exact artifact (future)"]
-    X --> P{"Registered producer available?"}
-    P -->|"yes"| B["Build, validate, and publish atomically"]
-    B --> R
-    P -->|"no or recoverable failure"| F{"Policy permits fallback?"}
-    F -->|"preferred"| C
-    F -->|"required"| E["Fail startup"]
-    P -->|"nonretryable failure"| E
-    C --> W{"Post-load publication enabled?"}
-    W -->|"yes"| B2["Publish final model through POST_LOAD_ONLY producer"]
-    B2 --> CL["Close validated publication lease"]
-    CL --> R2["Return separate publication report"]
-    R2 --> D
-    W -->|"no"| D["Keep canonical model"]
-```
-
-The modes are:
-
-| Mode | Observable behavior |
-| --- | --- |
-| `disabled` | Use canonical loading directly without probing storage, identity, credentials, or topology. |
-| `preferred` | Return an exact lease when available; otherwise use canonical fallback only for a miss, invalid cache entry, or typed retryable failure. |
-| `required` | Fail when an exact lease cannot be acquired. |
-
-During pre-load resolution, an unsupported capability, semantic identity
-collision, producer failure, or publication failure is nonretryable and remains
-visible even in preferred mode. A post-load publication failure is likewise
-visible in its own report, but cannot revise the canonical-fallback outcome.
-Storage policy must never disguise a semantic or configuration error as a cache
-miss.
-
-## Loader and restoration sequence
-
-The model integration owns the end-to-end loading transaction. The runtime
-does not construct a model or invoke the canonical loader.
-
-```mermaid
-sequenceDiagram
-    participant L as Loader adapter
-    participant R as HostWeightRuntime
-    participant S as HostWeightStore
-    participant P as WeightProducer
-    participant X as WeightRestorer
-    participant T as GPU transport
-
-    L->>L: Resolve canonical revision and exact identity
-    L->>R: resolve(identity, producer)
-    R->>S: lookup(exact identity)
-    alt validated hit
-        S-->>R: HostWeightLease
-        R-->>L: lease and LOCAL_HIT report
-        L->>X: plan_restore(model, lease)
-        X-->>L: validation-only restore plan
-        L->>X: commit() once
-    else miss with allowed producer
-        R->>S: get_or_build(identity, producer)
-        S->>P: produce(store-scoped writer)
-        P-->>S: final-layout tensors and metadata
-        S-->>R: validated HostWeightLease
-        R-->>L: lease and LOCAL_PRODUCTION report
-        L->>X: plan_restore(model, lease)
-        X-->>L: validation-only restore plan
-        L->>X: commit() once
-    else policy permits canonical fallback
-        R-->>L: CANONICAL_FALLBACK
-        L->>L: Run canonical loader
-        opt explicit post-load publication enabled
-            L->>R: publish_after_load(identity, POST_LOAD_ONLY producer)
-            R->>S: get_or_build(identity, producer)
-            S-->>R: validated HostWeightLease or typed failure
-            R->>R: close publication lease
-            R-->>L: separate publication report
-        end
-    else required or nonretryable failure
-        R-->>L: FAILED report
-    end
-    L->>T: consume final CPU tensors and any lease
-    T-->>L: transfer teardown complete
-    L->>L: close lease when one was acquired
-```
-
-`plan_restore()` must not mutate the model or lease. `commit() -> None` is the
-sole one-shot model mutation. If planning fails, canonical fallback may reuse
-the untouched model. If commit begins and fails, the partially hydrated model
-must be discarded and canonical fallback must construct a fresh model.
-
-`publish_after_load()` is synchronous in V1 and accepts only a
-`POST_LOAD_ONLY` producer. Its report is separate from the terminal resolution,
-so a publication failure cannot rewrite a successful canonical fallback. A
-successful publication closes the store-returned lease inside the runtime and
-warms only future startups. It does not restore, rebind, or otherwise mutate the
-canonically loaded model serving the current startup.
-`allow_local_build` gates producers during pre-load resolution, while
-`allow_post_load_publish` independently gates this explicit post-load path.
-
-## Exact representation identity
-
-The store performs exact lookup. It never silently converts one representation
-into another or substitutes the first backing that responds.
-
-Identity includes:
-
- immutable model revision and source fingerprint;
- model component and ownership boundary;
- representation name, dtype, and format metadata;
- final tensor layout and semantic parallel coordinates;
- static adaptation identity; and
- producer implementation, manifest, and restorer schema versions.
-
-The requested representation is selected by the loader. The store chooses
-where to obtain that exact representation: validated local artifact, future
-remote materialization, or a registered producer.
-
-### Parallelism
-
-Parallel coordinates are included only when they change bytes, shape, layout,
-or component ownership.
-
-| Dimension | Identity and sharing rule |
-| --- | --- |
-| DP | Exclude DP rank for replicated weights so same-node replicas can acquire the same artifact. Include a coordinate only if DP changes weight ownership. |
-| TP | Include TP size and rank when each rank owns different tensor slices or packed layouts. Each distinct TP shard is a separate exact artifact. |
-| SP | Include SP size and backend when they change the weight layout. Exclude SP rank when all SP ranks consume identical bytes. |
-| PP | Encode component ownership or stage-local layout when PP changes which weights belong to the consumer. |
-| EP | Encode expert ownership and layout whenever ranks own different expert weights. |
-
-The runtime does not infer these rules from process-group topology. The model
-adapter is responsible for constructing a correct identity.
-
-### Quantization and adaptations
-
-Runtime BF16, FP8, packed quantized weights, and future formats are distinct
-representations. Conversion is performed by an explicitly versioned producer,
-never by cache coercion. A producer must publish the final layout consumed by
-its matching restorer.
-
-Dynamic LoRA overlays are not part of a reusable base-weight artifact. A
-statically merged adapter is cacheable only as a separate identity containing
-the adapter fingerprint and merge semantics.
-
-### Initial diffusion final-layout contract
-
-The shared diffusion contract covers complete final-layout DiT parameters and
-persistent buffers. Text encoders, VAEs, non-persistent derived state, and other
-pipeline components remain outside the artifact. One explicit representation
-policy selects allowed dtypes, tensor roles, physical layout identity, producer
-ABI, manifest schema, and restoration schema.
-
-The contract is intentionally separate from loader activation:
-
- `FinalLayoutRequest` contains typed loader identity/configuration fingerprints,
-  TP coordinate, and conservative SP semantics. It has no open metadata bag,
-  DP coordinate, SP rank, device identity, DLO transfer mode, registration
-  policy, or store path.
- `FinalLayoutArtifactSpec` binds one `WeightRepresentation` and runtime-layout
-  name to explicit producer/restorer schemas and a canonical, versioned
-  implementation ABI descriptor. Compatibility never depends on reflective
-  source inspection.
- `PreparedWeightSource` snapshots immutable revisions or exact local file
-  content plus a typed checkpoint-adapter identity before ordinary
-  materialization. Source replacement before or during production fails
-  publication. A hash-looking symlink basename is trusted only for an explicit
-  Hugging Face Hub source whose repository ID and
-  `models--.../snapshots/<revision> -> blobs/<hash>` topology validate; every
-  local or otherwise unverified symlink target is content-hashed.
- the tensor ownership digest records exact runtime names, kinds, shapes,
-  semantic roles, dtypes, and strides from a CPU or meta model skeleton;
- `FinalLayoutTensorRestorer` accepts only an exact lease identity, validates
-  complete policy-defined coverage without mutation, and returns a one-shot
-  commit plan;
- each model declares one dtype-neutral `FinalLayoutModelContract` with an
-  explicit implementation version and a post-commit validator; and
- `FinalLayoutBF16Producer` accepts only the matching identity context and a
-  finalized CPU model. It is `POST_LOAD_ONLY` and `SINGLE_PROCESS` per exact TP
-  coordinate. Its BF16 policy preserves model-declared FP32 parameters and
-  buffers and revalidates MiniMax H3 mixed-precision invariants.
-
-Other representations reuse source identity, typed parallel identity, tensor
-ownership, and exact restoration only when their policy proves those semantics.
-For example, runtime FP8 needs a separate policy/producer for generated scales,
-quantization metadata, and Cutlass physical layouts; it is not enabled by
-changing a dtype string on the BF16 producer.
-
-This stage makes no startup, sharing, or DLO performance claim. A following
-consumer PR owns disabled/preferred/required precedence, mixed-component loader
-transactions, warm-hit restoration, and transactional lease handoff. A TP2
-prewarm deployment will require a matching TP2 producer cohort to populate both
-TP-coordinate identities even though the store coordinates each artifact
-independently.
-
-## Host sharing and GPU transport
-
-Every process receives its own virtual mappings and `HostWeightLease`, but
-workers mapping the same local artifact can share physical file-backed pages
-through the OS page cache. This avoids independent private tensor allocations;
-it does not guarantee that process PSS reports exactly one model copy.
-
-The ownership boundary is:
-
- the store owns immutable artifact files, publication, and lifecycle;
- the kernel owns page-cache residency and placement;
- the lease owns process-local mappings and the shared artifact lock; and
- transport owns page registration, page locking, private staging, H2D copies,
-  streams, device buffers, and lease release ordering.
-
-DLO AllGather and no-AllGather remain transport and execution choices. A DLO
-integration may consume a lease, but the Host Weight Runtime does not choose a
-parallel collective or orchestrate DP requests. See the
-[DLO feature design](offloader/distributed_layerwise_offload.md).
-
-## Locality and NUMA policy
-
-The V1 backend is node-local. It accepts an allowlist of known local disk
-filesystems plus tmpfs/ramfs, records the detected kernel filesystem type, and
-rejects known remote or unknown filesystems. NFS, CIFS, Lustre, Ceph, and other
-cross-node mounts cannot silently satisfy the local backend because their
-page-cache and advisory-lock behavior does not provide the required node-local
-contract.
-
-A NUMA-specific root creates a separate storage domain but does not by itself
-place page-cache pages on that NUMA node. A topology-aware integration must
-also pin workers, establish local first touch or prefault, perform transport
-registration in the same domain, and collect residency evidence.
-
-Tmpfs artifacts consume host memory and may consume swap. They must be
-accounted as memory-backed storage rather than ordinary disk capacity.
-
-## Concurrency and timeouts
-
-One process per exact identity owns a build; other workers wait and then acquire
-leases for the published artifact. Publication is invisible until all payloads
-and metadata are validated, hashed, fsynced, and atomically renamed.
-
-`coordination_timeout_seconds` bounds filesystem lock acquisition. It does not
-cancel synchronous validation, a producer that has already started, or atomic
-publication. A hung in-process producer therefore blocks its owning process and
-must be handled by external process supervision. Enforceable producer
-cancellation requires a future process-isolated producer contract.
-
-Leases keep a shared artifact lock for their lifetime. A forked child may close
-its inherited descriptors but cannot unlock the parent process's lease. Cleanup
-uses a nonblocking exclusive lock and reports an active lease instead of
-removing live mappings.
-
-## Failure and fallback contract
-
-| Condition | Preferred mode | Required mode |
-| --- | --- | --- |
-| Exact local hit | Return lease | Return lease |
-| Local miss | Try later backing or canonical fallback | Try later backing or fail |
-| Invalid or denied artifact | Quarantine/rebuild when possible; otherwise canonical fallback | Quarantine/rebuild or fail |
-| Retryable lock, domain, or capacity failure | Canonical fallback | Fail |
-| Unsupported producer or backend | Fail | Fail |
-| Identity collision | Fail | Fail |
-| Pre-load producer or atomic publication failure | Fail | Fail |
-| Post-load publication failure after canonical fallback | Keep canonical model; report publication failure | Not reached through required resolution |
-| Restore planning failure | Canonical fallback may reuse untouched model | Fail |
-| Restore commit failure | Discard model; fallback requires a fresh instance | Fail |
-
-Cache failures should normally reduce performance rather than availability,
-but only when the typed failure explicitly permits fallback. Canonical source,
-authentication, configuration, and semantic errors remain visible.
-
-## Consumer integration requirements
-
-A consumer PR must:
-
-1. Resolve an immutable canonical model source before cache lookup.
-2. Construct the exact final representation identity, including relevant
-   parallel, quantization, and adaptation semantics.
-3. Register a deterministic producer for that identity or support lookup-only
-   operation.
-4. Provide a validation-only restorer with a one-shot commit.
-5. Keep GPU transport outside the producer, store, and restorer contracts.
-6. Handle preferred fallback and required failure without reusing a model after
-   a failed restore commit.
-7. Retain the lease until every transport operation that may access mapped
-   memory has completed.
-8. Emit and test the terminal resolution report and any separate post-load
-   publication report.
-
-Consumer validation must prove:
-
- output parity with canonical loading;
- exact warm-hit work avoidance;
- correct TP/SP/PP/EP ownership and layout identity;
- correct BF16, FP8, quantized, or adaptation semantics;
- shared-backing evidence when host-memory savings are claimed;
- clean unmapping, unregistration, and artifact-lock release; and
- startup, host-memory, and transport effects for the claimed deployment.
-
-## Rollout
-
-The rollout is intentionally staged:
-
-1. Land the neutral contracts and local filesystem store.
-2. Add one model-specific producer/restorer integration with parity evidence.
-3. Connect eligible DLO or other transport paths without moving transport
-   ownership into the runtime.
-4. Add additional final-layout and quantized producers independently.
-5. Introduce remote materialization only through the same local lease contract.
-
-The architectural decisions and deferred work are tracked in
-[RFC #6414](https://github.com/vllm-project/vllm-omni/issues/6414).
@@ -43,21 +43,291 @@ DLO weight collective.

 Host storage is selected separately from the transfer protocol. The loader can
 produce a direct-checkpoint mmap plan for a proven-compatible runtime layout;
-otherwise it uses the ordinary loader. Consequently, no-AllGather replicas on
-the same node can share immutable checkpoint pages when direct mmap is
-selected, while the ordinary-loader fallback still keeps a private runtime
-copy per process.
+otherwise it uses the ordinary loader. In no-AllGather mode, the Phase B host
+weight cache can explicitly normalize supported final ordinary-loader DiT
+tensors into an immutable node-local mmap entry. Ordinary pinned weights remain
+the default after checkpoint mmap fallback when the cache is not selected; cache
+publication and validation add startup and disk lifecycle costs. Replicas can
+share either proven-compatible checkpoint pages or, when selected, equivalent
+final runtime layouts. Under the existing
+pinned-memory policy, the backend attempts to make the complete final mapping
+directly H2D-copyable when the platform provides registration, avoiding the
+recurrent host packing otherwise required by mmap. An optional positive limit
+adds a per-worker safety ceiling. CUDA is the first implementation.

 The Phase A shared-mmap support boundary is TP1. TP greater than one is an
 ordinary-loader compatibility path: DLO can consume the resulting TP-local
-tensors, but those configurations do not use checkpoint mmap and must not be
-used to claim shared-mmap host-memory savings.
+tensors. Direct checkpoint mmap still does not cover TP, but the Phase B cache
+can share each final TP coordinate among equivalent processes.

-The compatibility matrix below describes the current implementation. The
-unit-level guards are covered, but not every parallelism combination has a
-full model-and-hardware end-to-end test.
+The compatibility matrix below defines the current implementation boundary.
+Hardware and performance qualification is tracked separately from this
+long-lived design contract.

-## Design
+## Architecture
+
+DLO is divided into four planes: configuration, loader-owned host storage,
+backend setup, and the per-block inference hot path. Keeping these decisions
+separate is intentional. In particular, an mmap cache is a host-storage choice;
+it does not imply a DLO AllGather, and disabling DLO AllGather does not decide
+whether the host source is private memory, checkpoint mmap, or host weight cache
+mmap. The shared control plane is described once below; the AllGather and
+no-AllGather startup and hot paths are then shown separately.
+
+### Component ownership
+
+The map includes optional mode-specific components, but the ownership rules
+and loader-to-backend boundary are shared.
+
+```mermaid
+flowchart TB
+    CLI["CLI / EngineArgs"] --> Config["OmniDiffusionConfig<br/>validation and operator policy"]
+    Config --> Runner["DiffusionModelRunner<br/>startup coordinator"]
+
+    subgraph LoaderPlane["Loader-owned host-storage plane"]
+        Loader["DiffusersPipelineLoader"]
+        Checkpoint["checkpoint mmap preflight"]
+        Ordinary["ordinary load + callbacks + calibration"]
+        HostWeightCache["host_weight_cache<br/>final-layout publication / join"]
+        Contract["HostWeightPlan<br/>backing + bindings + transforms"]
+        Loader --> Checkpoint
+        Loader -->|"registered final layout requested"| Ordinary
+        Checkpoint -->|"compatible"| Contract
+        Checkpoint -->|"fallback"| Ordinary
+        Ordinary -->|"host weight cache enabled"| HostWeightCache
+        HostWeightCache -->|"enabled and compatible"| Contract
+    end
+
+    Runner -->|"load_model"| Loader
+    Loader -->|"pipeline + optional HostWeightPlan"| Runner
+
+    Config --> Factory["get_offload_backend<br/>OffloadConfig normalization"]
+    Runner -->|"device + optional plan"| Factory
+    Factory --> Backend["DistributedLayerwiseOffloadBackend<br/>resource and transfer owner"]
+    Topology["existing DP / SP process groups"] --> Backend
+    Discovery["ModuleDiscovery + optional OffloadPlan"] --> Backend
+    Contract -.->|"passed once by the runner"| Backend
+
+    Backend -.->|"host weight cache + pinned-memory policy"| Registration["host_registration<br/>platform-neutral lifecycle"]
+    Registration --> CUDA["CUDA registration backend"]
+    Backend --> Hooks["DistributedLayerwiseOffloadHook<br/>one circular hook per streamed block"]
+    Forward["pipeline.forward"] --> Hooks
+    Hooks --> DataPath["two device slots<br/>H2D only or H2D + AllGather"]
+
+    Shutdown["DiffusionWorker.shutdown"] -->|"disable before process-group teardown"| Backend
+```
+
+| Component | Owns | Must not own |
+| --- | --- | --- |
+| CLI, engine arguments, and `OmniDiffusionConfig` | User policy, defaults, validation, and propagation to every worker | Checkpoint inspection, cache publication, or buffer allocation |
+| `OffloadConfig.from_od_config()` | Offload-strategy selection, effective DLO group size, AllGather policy, resident-layer count, pinned-memory policy, and optional registration ceiling | Host-weight compatibility decisions |
+| `DiffusersPipelineLoader` | Ordinary loading lifecycle and the decision to return an optional `HostWeightPlan` | DLO process groups or block-stream scheduling |
+| Checkpoint mmap planner | Proving that checkpoint tensors can represent the required runtime layout before ordinary DiT materialization is skipped | Host weight cache identity or transfer policy |
+| `host_weight_cache` | Normalizing final ordinary-loader tensors into an immutable node-local entry and returning a validated plan | Model mutation, host registration, H2D, or collectives |
+| `HostWeightPlan` | The one-way loader-to-offloader contract: backing kind, tensor bindings, source coverage, and any bounded transforms | Cache construction or runtime scheduling |
+| `ModuleDiscovery` and model `OffloadPlan` | Discovering DiT/components and declaring block, resident, and on-demand paths | Loader or cache behavior embedded in model pipelines |
+| `DistributedLayerwiseOffloadBackend` | Consuming the exact plan, selecting the existing group, mapping/repointing storage, allocating shared buffers and streams, optional host registration, installing hooks, and cleanup | Re-running loader compatibility checks or orchestrating replicas |
+| `DistributedLayerwiseOffloadHook` | The block hot path: prefetch, optional DLO AllGather, readiness events, parameter repointing, and replacement with offload placeholders | Cache keys, manifest validation, or request routing |
+| `host_registration` and platform backend | All-or-nothing registration lifecycle for existing immutable mappings | Choosing which weights are cached or changing the two-slot device-buffer contract |
+| `DiffusionWorker` | Calling backend teardown before destroying the distributed environment | Managing backend-owned mappings or registrations directly |
+
+The configuration fields are routed to the component that can enforce their
+contract. The cache root and lock timeout are consumed by the loader.
+`dlo_use_host_weight_cache` explicitly selects final-layout cache publication
+instead of direct-checkpoint mmap. It defaults to false so the ordinary
+pinned-loader path remains available without requiring an opt-out.
+With `pin_cpu_memory=True`, selecting the host weight cache deliberately chooses
+the transform-complete layout even when direct checkpoint mmap is available,
+because only that final layout can be registered without deferred transforms.
+The backend consumes `dlo_host_weight_cache_pin_limit_gib` as an optional
+registration ceiling; zero applies no additional ceiling and does not select
+the cache by itself.
+`dlo_use_allgather` controls loader plan routing because the host weight cache
+is no-AllGather-only, and it selects the backend transfer protocol. This is
+coordination through typed configuration and `HostWeightPlan`, not through
+model-specific global state.
+
+### Runtime host-layout identity (v1)
+
+Host weight cache v1 identifies the loader-produced host representation, not
+the topology used later to move weights to devices. These are separate
+contracts:
+
+- `RuntimeHostLayout` describes tensor ownership and representation after the
+  ordinary loader has applied its parallel-aware transforms. This is the
+  layout stored in the host weight cache.
+- `DLOTransferLayout` describes whether each worker copies its local weights
+  directly or participates in the existing DLO AllGather protocol. It is not
+  part of the host weight cache in v1; AllGather continues to use its existing
+  process-owned host shards.
+
+The v1 physical-sharing invariant is one cache entry per TP coordinate,
+shared by equivalent DP and SP consumers on the same node. The identity
+therefore includes TP world size and TP rank, because different TP coordinates
+own different tensors. It excludes DP world size/rank and SP rank, because
+those dimensions do not change the final tensor ownership supported by v1.
+SP world size and implementation details remain conservative compatibility
+guards until equivalent layouts across those configurations are proven.
+
+PP, HSDP/DTensor, expert parallelism, and CFG parallelism are rejected rather
+than assigned speculative cache identities. Supporting one of these layouts
+requires first defining its loader-produced ownership, representation, and
+sharing domain; it does not follow automatically from supporting its runtime
+collectives. Consequently, this phase implements a TP-coordinate runtime host
+layout, not a general parallel-layout cache.
+
+### Shared startup and lifecycle
+
+The shared control path selects host backing and transfers its ownership to
+the backend before either transfer mode installs hooks:
+
+```mermaid
+sequenceDiagram
+    participant C as OmniDiffusionConfig
+    participant R as DiffusionModelRunner
+    participant L as DiffusersPipelineLoader
+    participant B as DLO backend
+    participant W as DiffusionWorker
+
+    C->>R: validated offload policy
+    R->>L: load_model(config)
+    L->>L: select and validate host backing
+    L-->>R: pipeline + optional HostWeightPlan
+    R->>B: enable(config, device, optional plan)
+    B->>B: discover modules and consume host backing
+    B-->>R: mode-specific backend is ready
+    W->>B: shutdown calls disable()
+    B->>B: synchronize, unregister, remove hooks, close mappings
+```
+
+The loader returns a plan only after its contract is valid: checkpoint plans
+have preflight-proven source coverage and metadata, while host weight cache
+plans also have full manifest, file, and mapped-content validation. The runner
+then transfers ownership exactly once with
+`model_loader.take_host_weight_plan()`. If no plan is returned, the backend
+requires materialized ordinary-loader tensors. If a plan caused ordinary DiT
+materialization to be skipped, failure to create or enable its consumer is a
+hard startup error rather than a fallback to uninitialized parameters.
+
+At inference time, the model pipeline remains the caller: normal block forward
+calls activate the installed hooks. Both modes use one copy stream and two
+shared device slots sized for the largest streamed block. The hooks do not
+call the loader or cache.
+
+### AllGather startup and hot path
+
+```mermaid
+sequenceDiagram
+    participant B as DLO backend
+    participant H as block hooks
+    participant G as existing DP or SP group
+
+    B->>B: choose existing group and prepare persistent local shards
+    B->>B: allocate two device slots and a communication stream
+    B->>H: install hooks and prime the first block
+    loop each streamed block
+        H->>H: copy the next local shard to the alternate slot
+        H->>G: all_gather_into_tensor(next block)
+        G-->>H: complete next block is ready
+        H->>H: execute current block and rotate slots
+    end
+```
+
+AllGather uses the existing DP group when DP is greater than one, otherwise
+the existing SP group when SP is greater than one. TP is never selected as
+DLO's weight-sharding group. Every participating rank must request blocks in
+the same order; fast P2P reduces communication cost but does not remove that
+lockstep contract. An effective group size of one issues no collective and
+uses rank-local transfer.
+
+### No-AllGather startup and hot path
+
+```mermaid
+sequenceDiagram
+    participant L as DiffusersPipelineLoader
+    participant C as host_weight_cache
+    participant B as DLO backend
+    participant P as platform registration
+    participant H as block hooks
+
+    alt host weight cache explicitly selected
+        L->>L: load, mutate, validate, and calibrate final tensors
+        L->>C: publish or join final-layout entry
+        C-->>L: validated host weight cache plan or fail-closed fallback
+        L-->>B: cache plan or materialized fallback via runner
+    else automatic checkpoint selection
+        L->>L: checkpoint mmap preflight
+        alt loader selects a compatible checkpoint plan
+            L-->>B: checkpoint plan via runner
+        else ordinary loading
+            L->>L: load, mutate, validate, and calibrate final tensors
+            L-->>B: materialized tensors via runner
+        end
+    end
+    B->>B: consume complete rank-local block sources
+    opt host weight cache plan and pinned-memory policy
+        B->>P: register the complete immutable mapping
+        P-->>B: direct-H2D source or bounded-staging fallback
+    end
+    B->>H: install hooks and prime the first block
+    loop each streamed block
+        alt registered host weight cache mapping
+            H->>H: copy complete next block directly to device
+        else pageable mmap mapping
+            H->>H: pack into a bounded staging slot, then copy to device
+        else ordinary runtime tensors
+            H->>H: copy complete next block to device
+        end
+        H->>H: execute current block and rotate slots
+    end
+```
+
+No-AllGather creates no DLO weight group and issues no DLO collective.
+Workers may therefore schedule requests independently. Ordinary TP and SP
+collectives remain inside model execution; host registration changes only
+the source of the complete-block H2D copy.
+
+### Host backing and transfer composition
+
+| Loader-selected host backing | Backend transfer mode | Setup result | Per-block hot path |
+| --- | --- | --- | --- |
+| Ordinary runtime tensors | AllGather group larger than one | Each rank retains a pinned local weight shard | shard H2D → DLO AllGather → device slot |
+| Checkpoint mmap | AllGather group larger than one | Each rank prepares its persistent shard, then releases the source mapping | shard H2D → DLO AllGather → device slot |
+| Ordinary runtime tensors | Rank-local / no-AllGather | Each rank retains the complete loader-produced local layout | complete-block H2D → device slot |
+| Checkpoint mmap, or host weight cache with pinned memory disabled/registration unavailable | Rank-local / no-AllGather | Immutable mapping plus two bounded host-staging slots | mmap views → staging slot → device slot |
+| Host weight cache mmap with pinned memory enabled and registration available | Rank-local / no-AllGather | Complete mapping is registered by the platform backend | registered mmap views → device slot |
+
+The three axes therefore remain independent:
+
+1. **Offload policy:** whether DLO is enabled and which layers are resident.
+2. **Host backing:** ordinary tensors, checkpoint mmap, or final host weight cache
+   mmap, selected by the loader.
+3. **Transfer protocol:** rank-local H2D or H2D plus DLO AllGather, selected by
+   the backend from validated configuration and existing topology.
+
+### Failure and lifecycle boundaries
+
+- Invalid option combinations fail during configuration validation.
+- Checkpoint mmap preflight failure falls back before ordinary loading is
+  skipped.
+- Host weight cache incompatibility, timeout, or publication failure retains
+  the already-valid ordinary tensors.
+- Host-registration failure rolls back and retains bounded staging. A rollback
+  failure aborts startup because unmapping a range still owned by the platform
+  would be unsafe.
+- During shutdown, DLO synchronizes outstanding device work, unregisters host
+  mappings, removes hooks, and closes mmap handles only after safe unregister;
+  the worker destroys its process groups afterward.
+
+DLO deliberately does not own DP replica placement, independent-engine request
+routing, cross-engine admission control, or cross-node cache distribution.
+Those belong to an external router/orchestrator. It also does not replace TP or
+SP model collectives; it only adds an optional weight collective over an
+already-existing DP or SP group.
+
+## Shared design
+
+The following topology and loader contracts apply to both transfer modes.

 ### DLO consumes the existing parallel topology

@@ -65,15 +335,10 @@ DLO does not create a new DP, TP, or SP topology. It reads the configured
 `DiffusionParallelConfig` and attaches offload hooks to the DiT blocks after the
 standard distributed groups have been initialized.

-The DLO weight-sharding group is selected as follows:
-
-1. Use the existing DP group when `data_parallel_size > 1`.
-2. When DP is one and SP is greater than one, use the SP group.
-3. Otherwise, run rank-locally without a DLO process group.
-
-TP is deliberately not used as DLO's AllGather group. HSDP has its own
-parameter-sharding lifecycle and is not allowed to be sharded a second time by
-DLO's AllGather path.
+AllGather mode selects one existing group for DLO weight sharding; no-AllGather
+mode creates no DLO group. Neither mode changes ordinary TP or SP model
+collectives. The mode-specific group and scheduling contracts are described
+below.

 ### The loader owns host-weight planning

@@ -105,7 +370,24 @@ flags such as `_supports_mmap_loading` or parameter attributes for mmap-only
 transforms. Model-specific direct-layout knowledge, when required, lives in a
 checkpoint adapter beside the ordinary loader.

-### AllGather path
+## AllGather design
+
+### Group selection
+
+The DLO weight-sharding group is selected in this order:
+
+1. Use the existing DP group when `data_parallel_size > 1`.
+2. When DP is one and SP is greater than one, use the existing SP group.
+3. Otherwise, use an effective group size of one and issue no collective.
+
+TP is deliberately not used as DLO's AllGather group. HSDP has its own
+parameter-sharding lifecycle and cannot be sharded a second time by DLO.
+
+### Sharded transfer and double buffering
+
+The loader may provide ordinary runtime tensors or a compatible checkpoint
+plan. During backend setup, either source is normalized into persistent local
+shards. The final-layout host weight cache is not selected in AllGather mode.

 With the default `dlo_use_allgather=True`, each rank stores approximately
 `1 / group_size` of each streamable block in pinned host memory. The next
@@ -113,6 +395,15 @@ block's shard is copied to a device buffer and reconstructed with
 `all_gather_into_tensor` on a communication stream while the current block is
 executing.

+![AllGather DLO sharded host weights and lockstep reconstruction](../../figures/dlo/dlo_allgather_sharded_host.svg)
+
+The figure uses DP2 with TP2 to expose both parallel dimensions. DLO creates
+one AllGather group across the DP replicas for each TP coordinate; TP0 workers
+reconstruct TP0 blocks together and TP1 workers reconstruct TP1 blocks
+together. Ordinary TP collectives remain inside each DP replica. Unlike the
+no-AllGather host weight cache path, these persistent pinned host shards are
+process-owned, and every participating rank must follow the same block order.
+
 ```text
 Compute:    [Block N]             [Block N+1]          [Block N+2]
 H2D:                      [shard N+1]           [shard N+2]
@@ -138,11 +429,29 @@ When DP is greater than one, the engine can process one request per DP rank in
 the same denoising wave. Because AllGather is a collective, all participating
 requests must take the same execution path at every denoising step.

-### Rank-local path without DLO AllGather
+Fast NVLink/NVSwitch changes collective cost, not this execution contract. For
+independently scheduled replicas—even on one NVSwitch baseboard—no-AllGather
+plus shared mmap storage avoids coupling their request schedules and failure
+domains.
+
+## No-AllGather design
+
+### Rank-local transfer

 With `--dlo-no-use-allgather`, DLO forces its internal offload shard size to
 one and streams complete blocks using H2D copies only. The host backing may be
-either a loader-approved checkpoint mapping or ordinary runtime tensors.
+a loader-approved checkpoint mapping, a normalized host weight cache mapping, or
+ordinary runtime tensors.
+
+![No-AllGather DLO shared host weights and independent runtime orchestration](../../figures/dlo/dlo_no_allgather_shared_host.svg)
+
+The figure uses TP2 to make per-coordinate physical sharing explicit. Each
+engine contains two rank-local workers and devices. The cache keeps one
+immutable entry per TP coordinate, so equivalent TP0 workers across engines
+share the TP0 entry and equivalent TP1 workers share the separate TP1 entry.
+An external router or orchestrator chooses each engine's requests; DLO
+coordinates only the worker-local mapping, hooks, transfer streams, events,
+and device slots.

 For direct mmap, each process retains immutable safetensors views and uses two
 bounded pinned host staging slots. Processes on the same node that map the same
@@ -151,10 +460,17 @@ the persistent private full-model copy per pure-DP process, but each process
 still packs and transfers every complete block. Sharing is node-local; each
 node has its own page cache.

-When direct mmap preflight fails, the regular model loader remains responsible
-for preparing each rank's weights, including TP-local tensors or HSDP-managed
-parameters. In that fallback, each pure-DP process keeps a private full runtime
-copy.
+For a host weight cache mapping, the default pinned-memory policy attempts to
+replace those host slots with direct copies from the shared final tensor views.
+Disabling pinned memory or a failed registration retains staging behavior.
+
+When direct mmap preflight fails or the host weight cache is selected, the
+regular model loader remains responsible for preparing each rank's weights,
+including TP-local tensors or HSDP-managed parameters. Ordinary pinned tensors
+remain the default without cache selection. When the host weight cache is
+explicitly selected,
+supported CPU layouts enter the cache; unsupported layouts keep one private
+runtime copy per process.

 This mode means:

@@ -165,18 +481,109 @@ This mode means:
 - TP/HSDP/SP collectives, if configured, are not disabled by this flag; only
  DLO's additional weight AllGather is disabled.
 - Pure DP deployments share one checkpoint-backed copy per node when direct
-  mmap is selected; the ordinary-loader fallback keeps one private runtime
-  copy per rank.
+  mmap is selected. The host weight cache can share equivalent ordinary-loader
+  outputs; its fallback keeps one private runtime copy per rank.
 - The scheduler does not require a synchronized DP request wave for DLO.

+### Post-load host weight cache
+
+The Phase B cache preserves the same ownership boundary. DLO neither derives
+cache keys nor interprets model loaders. No-AllGather DLO first attempts a
+compatible direct-checkpoint mmap plan. When that plan is unavailable, every
+rank completes the ordinary loader, custom callbacks, post-load processing,
+strict validation, and calibration. When cache use or registration is
+explicitly selected, the loader:
+
+1. discovers final CPU DiT parameters and persistent buffers;
+2. rejects unsupported non-contiguous, aliased, quantized, distributed, or
+   ambiguous layouts before changing the model;
+3. hashes tensor names, metadata, and final bytes;
+4. builds or joins one content-addressed entry under a strict POSIX lock; and
+5. returns a `HostWeightPlan(backing_kind="host_weight_cache")` only after file,
+   manifest, and remapped-tensor content validation succeeds.
+
+The identity excludes DP size/rank and SP rank. It includes TP world size/rank
+and conservative SP implementation/world-size guards. DP replicas and
+equivalent SP ranks can therefore share; different TP coordinates cannot.
+Final tensor content is authoritative, so an unmodeled loader/config change
+that changes bytes creates a different entry instead of risking silent
+sharing.
+
+Publication writes sharded safetensors and a JSON manifest into a same-
+filesystem temporary directory, flushes them, and atomically renames the
+directory. The manifest includes per-file SHA-256 digests and the final tensor
+content digest. Kernel `flock` ownership distinguishes a live writer from a
+stale lock file: process death releases the lock automatically. Stale temporary
+entries are removed only by the next lock owner. A bounded wait or any cache
+error retains the already-valid ordinary tensors.
+
+DLO maps this plan without moving the DiT to `meta` and without rerunning any
+post-load hook. It changes tensor storage while preserving `Parameter` objects,
+then runs the existing `gc.collect()`/`malloc_trim()` cleanup before installing
+streaming hooks. The source mappings remain open through DLO disable. With
+pinned memory disabled, or when registration is unavailable, they feed the
+existing bounded two-slot host-staging path. Every streamed block is first
+packed from pageable mmap storage into a staging slot and is then copied to the
+device. This removes model-sized private pinned storage, but adds a recurrent
+host-to-host copy and can amplify TP synchronization waits when several ranks
+compete for host bandwidth.
+
+This version is deliberately steady-state-oriented. It requires roughly one
+local-disk model copy per runtime identity, has no eviction, and still performs
+ordinary loading plus full content-hash passes in every rank. Cache publication
+or validation failure falls back to the already-valid ordinary host tensors.
+Skip-load-on-hit is a separate follow-up after loader side effects can be
+modeled safely.
+
+### Registered host weight cache transfer
+
+Selecting the host weight cache with `pin_cpu_memory=True` opts a worker into
+registration of the complete mapping when its platform supports it. It also
+changes loader selection: no-AllGather uses the ordinary loader and final-layout
+host weight cache even when a TP1 direct-checkpoint plan is available. A
+checkpoint binding can carry a deferred adapter such as
+grouped-QKV reordering. Registering that raw source would not remove the
+adapter's recurrent CPU allocation/copy, whereas the host weight cache contains
+the transform-complete final tensors.
+
+After mapping and validating every final tensor, DLO groups source storages by
+backing file, page-aligns their address ranges, and coalesces overlapping or
+adjacent ranges within that mapping. When a positive per-worker ceiling is
+configured, the complete byte count is checked against it before any platform
+mutation. The CUDA backend
+first requires `cudaDevAttrHostRegisterReadOnlySupported`, then registers every
+range with the read-only host-registration flag and verifies that PyTorch
+recognizes every mapped tensor as pinned. A device without that capability
+retains bounded staging; vLLM-Omni does not replace immutable mappings with a
+writable or copy-on-write CUDA-specific layout. Other registration failures
+roll back any ranges already registered and preserve the existing two-slot
+staging path. Partial direct transfer is deliberately unsupported. A rollback
+failure aborts worker initialization so a still-registered range is retained
+until process/context teardown rather than being unsafely unmapped.
+
+On success, the hooks copy each immutable tensor view directly into its offset
+in the existing flattened rotating device buffer on the copy stream. Parameter
+repointing, two-block HBM residency, and H2D/compute overlap are unchanged. The
+direct path trades recurrent host packing for finer-grained H2D operations. A
+packed cache schema should be considered only if that additional format and
+publication complexity becomes necessary.
+
+Registration is per process and platform context; physical file-cache pages
+remain shared and are not copied into one private host allocation per worker.
+The operator must nevertheless budget page-locked memory and satisfy the
+platform and OS registration limits for every worker. During shutdown, DLO
+first synchronizes outstanding device work, unregisters all ranges, and then
+closes the safetensors mappings. Worker teardown invokes this cleanup before
+destroying the distributed environment and platform context.
+
 ## Parallelism compatibility

 | Parallelism | DLO + AllGather | DLO without AllGather |
 |---|---|---|
-| **DP** | Supported primary path. DLO shards host weights across the DP group and can run DP multi-concurrency. | Supported rank-local path. Compatible TP1 replicas can share checkpoint pages on each node; fallback runtime tensors remain private. |
-| **SP** | Supported in the implementation. With DP=1, DLO uses the SP group for host-weight sharding; SP still shards sequence/activation work. | SP remains active, but DLO keeps standard-loader rank-local weights and adds no SP weight collective. |
-| **TP > 1** | Outside the Phase A shared-mmap support scope. The loader falls back before mutation, preserves TP-local layouts, and DLO may apply DP/SP host sharding to those ordinary runtime tensors. | Outside the Phase A shared-mmap support scope. The ordinary TP-aware loader produces rank-local tensors, which DLO streams without an additional weight collective; DP replicas retain private runtime storage. |
-| **HSDP** | Rejected. HSDP has already sharded parameters, so DLO AllGather would double-shard them. | Accepted by configuration. HSDP owns parameter sharding and its own gathers; DLO only stages rank-local parameters. End-to-end coverage is limited. |
+| **DP** | Supported primary path. DLO shards host weights across the DP group and can run DP multi-concurrency. | Supported rank-local path. Compatible TP1 replicas can share checkpoint pages; the optional host weight cache shares equivalent final layouts while excluding DP rank from its identity. CUDA workers may register the complete final mapping for direct H2D. |
+| **SP** | Supported in the implementation. With DP=1, DLO uses the SP group for host-weight sharding; SP still shards sequence/activation work. | SP remains active without a DLO weight collective. Host weight cache v1 excludes SP rank and includes conservative SP implementation/world-size guards. Registered transfer does not remove ordinary SP activation/attention collectives. |
+| **TP > 1** | Outside the Phase A direct-mmap scope. The loader preserves TP-local layouts and DLO may apply DP/SP host sharding to ordinary runtime tensors. | The ordinary TP-aware loader produces rank-local tensors. Host weight cache v1 creates one entry per TP coordinate, shareable by equivalent DP/SP processes. Registering those final mappings avoids the recurrent staging copy but does not remove ordinary TP collectives. |
+| **HSDP** | Rejected. HSDP has already sharded parameters, so DLO AllGather would double-shard them. | Accepted only with ordinary-loader rank-local tensors. HSDP owns parameter sharding and its own gathers; host weight cache v1 rejects HSDP/DTensor layouts. |

 ### Combined dimensions

@@ -192,7 +599,9 @@ This mode means:
 - **HSDP + DP or TP:** rejected independently by the diffusion parallel
  configuration.

-## Request and loading constraints
+## Mode constraints
+
+### AllGather constraints

 AllGather DP multi-concurrency requires:

@@ -200,109 +609,54 @@ AllGather DP multi-concurrency requires:
 - the same `num_inference_steps` for all requests in a wave; and
 - identical request arguments that affect the collective execution path.

+Per-tensor online FP8 linears can use DLO AllGather after the ordinary loader
+finalizes their runtime weights and scales. Other online methods must use
+`--dlo-no-use-allgather` or disable online quantization until their runtime
+layouts are validated.
+
+### No-AllGather constraints
+
 The no-AllGather path does not impose these DLO-specific synchronized-wave
-requirements.
+requirements. Host weight cache v1 is no-AllGather only and rejects all
+quantization configurations, HSDP/DTensor, expert parallelism, CFG
+parallelism, PP, non-contiguous tensors, and tied/shared storage.
+
+### Shared loading constraint

 Direct checkpoint mmap can back either transfer path. It is currently limited
 to proven TP1, non-HSDP, non-online-quantized layouts. Other layouts use the
-ordinary loader. Per-tensor online FP8 linears can use DLO AllGather after the
-ordinary loader finalizes their runtime weights and scales; DLO then shards and
-reconstructs those tensors with their recorded layouts. Other online methods
-must use `--dlo-no-use-allgather` or disable online quantization until their
-runtime layouts are validated.
+ordinary loader.

-A normalized runtime mmap cache, built through the ordinary loader, is the
-proposed general mechanism for sharing transformed TP or quantized layouts.
-That cache and its publication/lifecycle protocol are intentionally outside
-this phase; see [RFC #6195](https://github.com/vllm-project/vllm-omni/issues/6195).
+## Validation status

-## Validation coverage
-
-Current source-level validation includes:
-
- HSDP + DLO + AllGather rejection;
- HSDP + DLO without AllGather acceptance at configuration level;
- loader preflight fallback for TP, HSDP, online quantization, unknown custom
-  loaders, missing keys, and shape/dtype mismatches;
- ordinary-loader fallback for per-tensor online FP8 linears followed by DLO
-  sharding of finalized weights and scales;
- exact loader-to-backend plan transfer and ordinary-loader fallback;
- rank-local mmap source retention, bounded two-slot staging, and adapter
-  transforms without parameter-side flags;
- resident-layer requests requiring no-AllGather;
- DP request-wave validation for denoising-step compatibility;
- sharding, double-buffer, AllGather-size, and heterogeneous-block regression
-  tests.
-
-### B300 parallel-topology smoke matrix
-
-A four-GPU B300 smoke test covered MiniMax-H3 FL2VA with the same prompt, seed,
-CUDNN attention backend, 256x256 output, two denoising steps, and
-`dlo_resident_layers=0`. The TP2 rows used DiT DP2xTP2 with the text encoder and
-VAEs at TP1. They validate the ordinary-loader fallback only, not direct mmap
-or shared-mmap host-memory savings.
-
-| Configuration | Result | Warm E2E | Peak device memory | Host PSS |
-|---|---:|---:|---:|---:|
-| DP4xTP1 AllGather | Passed, 4 concurrent requests | 2.87 s / 4 requests | 13.84 GiB | 211.99 GiB |
-| DP4xTP1 no-AllGather | Passed, 1 request | 15.02 s | 13.23 GiB | 187.77 GiB |
-| DP2xTP2 AllGather | Passed, 2 concurrent requests | 4.16 s / 2 requests | 12.50 GiB | 211.97 GiB |
-| DP2xTP2 no-AllGather | Passed, 1 request | 3.51 s | 11.88 GiB | 314.01 GiB |
-
-Within each topology, the AllGather and no-AllGather video and audio outputs
-were byte-identical. All four runs completed without an `ERROR` or traceback
-and released their device allocations. For DP4xTP1, no-AllGather direct mmap
-reduced total PSS by 24.22 GiB (11.4%) and `Private_Dirty` from 211.33 to
-125.32 GiB (40.7%) relative to AllGather. For DP2xTP2, preflight selected the
-ordinary loader as designed; no-AllGather PSS was 314.01 GiB, about 48% above
-AllGather, because DP replicas did not share checkpoint-backed runtime
-weights. This is a functional and memory smoke test, not a production-quality
-performance or output-quality benchmark.
-
-### Host-memory measurement
-
-A two-worker MiniMax-H3 FL2VA measurement on one L20X node compared the
-ordinary-loader fallback with direct mmap. Both runs used
-DP=2, TP=1, no DLO AllGather, BF16 weights, two denoising steps, and a
-256x256 four-second request. The ordinary-loader workers were sampled after
-initialization. The mmap workers were sampled after one completed request, so
-the checkpoint working set had been faulted into the page cache; this is the
-more conservative point for mmap.
-
-The values below come from `/proc/<worker>/smaps_rollup` and include the whole
-worker, not only the DiT. The stable rank-to-rank difference comes from other
-pipeline components, so each worker should be compared with the same worker in
-the other storage mode.
-
-| Worker | Ordinary RSS | mmap RSS | Ordinary PSS | mmap PSS | PSS reduction |
-|---|---:|---:|---:|---:|---:|
-| DP worker 0 | 168.27 GiB | 132.76 GiB | 167.84 GiB | 101.43 GiB | 66.40 GiB |
-| DP worker 1 | 116.19 GiB | 79.97 GiB | 115.73 GiB | 48.64 GiB | 67.09 GiB |
-| **Two-worker total** | — | — | **283.56 GiB** | **150.08 GiB** | **133.48 GiB (47.1%)** |
-
-The direct-mmap workers each reported 62.45 GiB `Shared_Clean` but only
-31.20 GiB `Pss_File`, which is the proportional charge expected when the same
-resident checkpoint pages are mapped by two workers. `Private_Dirty` also fell
-from 167.53 to 70.24 GiB for worker 0 and from 115.40 to 17.44 GiB for worker
-1, a reduction of about 97–98 GiB per worker. RSS understates this benefit
-because it counts a shared physical page in every process that maps it; summed
-PSS is the appropriate node-memory comparison.
-
-The highest-value missing coverage is broader end-to-end numerical and
-lifecycle comparison against ordinary layerwise offload for DP+SP,
-HSDP+SP+no-AllGather, and TP greater than one across additional models and
-target CUDA/NCCL or CANN/HCCL hardware. That broader TP coverage does not
-change the Phase A direct-mmap TP1 support boundary.
+Historical test counts and hardware measurements are intentionally not kept
+in this design document because they can drift as the implementation changes.
+Revalidation must run against the final commit and publish commit-pinned
+artifacts before making hardware or performance claims. Track that work in
+[issue #6231](https://github.com/vllm-project/vllm-omni/issues/6231).

 ## Recommendations

- Use **DP + DLO AllGather** for the supported throughput and host-memory
-  scaling path.
+### AllGather
+
+- Use **DP + DLO AllGather** when ranks already execute the same block path in
+  lockstep and belong to the same fast P2P domain. It shards persistent host
+  weights across that group.
 - Use **SP + DLO AllGather** for long-sequence workloads when DP concurrency is
  not the goal.
+
+### No-AllGather
+
 - Use **no-AllGather** when independent replica execution is required. TP1
-  direct-mmap deployments can share checkpoint pages per node; other layouts
-  retain the ordinary loader's private host memory behavior and are outside
-  the Phase A shared-mmap support scope.
- Prefer **HSDP alone** for production HSDP deployments until the combined
-  HSDP + DLO no-AllGather path has broader end-to-end coverage.
+  direct-mmap deployments can share checkpoint pages per node. Enable the
+  host weight cache only when independent replicas have repeated final layouts
+  and benchmark the target CPU/memory topology, especially for matching
+  coordinates across multiple TP engines. With the default pinned-memory
+  policy, supported CUDA workers prefer registered direct H2D. Configure a
+  positive ceiling when an explicit page-locking bound is required, or disable
+  pinned memory when pageable staging is operationally preferable.
+
+### HSDP
+
+- Do not combine HSDP with DLO AllGather or host weight cache v1. HSDP with
+  no-AllGather remains an ordinary-loader rank-local path.
@@ -32,25 +32,26 @@ mooncake_master \

 ## Configuration

-Define the connector at the top level of the deploy YAML:
+Define the connector in runtime:

 ```yaml
-connectors:
-  connector_of_mooncake:
-    name: MooncakeStoreConnector
-    extra:
-      host: "127.0.0.1"
-      metadata_server: "http://<MASTER_IP>:8080/metadata"
-      master: "<MASTER_IP>:50051"
-      segment: 512000000
-      localbuf: 64000000
-      proto: "tcp"
+runtime:
+  connectors:
+    connector_of_mooncake:
+      name: MooncakeStoreConnector
+      extra:
+        host: "127.0.0.1"
+        metadata_server: "http://<MASTER_IP>:8080/metadata"
+        master: "<MASTER_IP>:50051"
+        segment: 512000000
+        localbuf: 64000000
+        proto: "tcp"
 ```

 Wire stages to the connector:

 ```yaml
-stages:
+stage_args:
  - stage_id: 0
    output_connectors:
      to_stage_1: connector_of_mooncake
@@ -21,25 +21,26 @@ InfiniBand/RoCE NICs).

 ## Configuration

-Define the connector at the top level of the deploy YAML:
+Define the connector in runtime:

 ```yaml
-connectors:
-  rdma_connector:
-    name: MooncakeTransferEngineConnector
-    extra:
-      host: "auto"                  # Auto-detect local RDMA IP
-      zmq_port: 50051               # ZMQ base port (see "Port Offset Scheme" below)
-      protocol: "rdma"              # "rdma" or "tcp"
-      device_name: ""               # RDMA device (e.g., "mlx5_0"), empty for auto-detect
-      memory_pool_size: 4294967296  # 4 GB (CPU); use 2147483648 (2 GB) for GPU
-      memory_pool_device: "cpu"     # "cpu" for pinned memory (recommended), "cuda" for GPUDirect RDMA
+runtime:
+  connectors:
+    rdma_connector:
+      name: MooncakeTransferEngineConnector
+      extra:
+        host: "auto"                  # Auto-detect local RDMA IP
+        zmq_port: 50051               # ZMQ base port (see "Port Offset Scheme" below)
+        protocol: "rdma"              # "rdma" or "tcp"
+        device_name: ""               # RDMA device (e.g., "mlx5_0"), empty for auto-detect
+        memory_pool_size: 4294967296  # 4 GB (CPU); use 2147483648 (2 GB) for GPU
+        memory_pool_device: "cpu"     # "cpu" for pinned memory (recommended), "cuda" for GPUDirect RDMA
 ```

 Wire stages to the connector:

 ```yaml
-stages:
+stage_args:
  - stage_id: 0
    output_connectors:
      to_stage_1: rdma_connector
@@ -414,7 +415,7 @@ A receiver connector:
 - allocates receive buffers from its own pool
 - requests metadata or transfer service from the sender

-The role is not inferred dynamically. It is injected from the deploy connector wiring:
+The role is not inferred dynamically. It is injected by the stage configuration layer:

 - incoming edge for a stage -> `role="receiver"`
 - outgoing edge for a stage -> `role="sender"`
@@ -13,9 +13,10 @@ segment name is returned in metadata.
 ## Configuration

 ```yaml
-connectors:
-  connector_of_shared_memory:
-    name: SharedMemoryConnector
+runtime:
+  connectors:
+    connector_of_shared_memory:
+      name: SharedMemoryConnector
 ```

 ## Notes
@@ -65,22 +65,23 @@ dscli stop --worker_address "${WORKER_IP}:31501"

 ## Configuration

-Define the connector at the top level of the deploy YAML:
+Define the connector in runtime:

 ```yaml
-connectors:
-  connector_of_yuanrong:
-    name: YuanrongConnector
-    extra:
-      host: "127.0.0.1"
-      port: 31501
-      get_sub_timeout_ms: 1000
+runtime:
+  connectors:
+    connector_of_yuanrong:
+      name: YuanrongConnector
+      extra:
+        host: "127.0.0.1"
+        port: 31501
+        get_sub_timeout_ms: 1000
 ```

 Wire stages to the connector:

 ```yaml
-stages:
+stage_args:
  - stage_id: 0
    output_connectors:
      to_stage_1: connector_of_yuanrong
@@ -94,23 +94,26 @@ For Ascend P2P, configure the connector with `protocol: "ascend"` and an NPU
 memory pool:

 ```yaml
-connectors:
-  yuanrong_te_connector:
-    name: YuanrongTransferEngineConnector
-    extra:
-      host: "auto"
-      zmq_port: 50051
-      rpc_port: "auto"
-      protocol: "ascend"
-      device_name: "auto"
-      memory_pool_size: 1073741824
-      memory_pool_device: "npu"
-
-edges:
-  - from: 0
-    to: 1
+runtime:
+  enabled: true
+  defaults:
    window_size: -1
    max_inflight: 1
+  connectors:
+    yuanrong_te_connector:
+      name: YuanrongTransferEngineConnector
+      extra:
+        host: "auto"
+        zmq_port: 50051
+        rpc_port: "auto"
+        protocol: "ascend"
+        device_name: "auto"
+        memory_pool_size: 1073741824
+        memory_pool_device: "npu"
+  edges:
+    - from: 0
+      to: 1
+      window_size: -1
 ```

 Important fields:
@@ -138,27 +141,31 @@ For AR 4-way TP sending KV cache to DiT 4-way TP, set the stage TP topology in
 both stage `omni_kv_config` blocks:

 ```yaml
-stages:
+stage_args:
  - stage_id: 0
-    devices: "0,1,2,3"
-    tensor_parallel_size: 4
-    omni_kv_config:
-      need_send_cache: true
-      rank_mapping:
-        from_tp: 4
-        to_tp: 4
+    runtime:
+      devices: "0,1,2,3"
+    engine_args:
+      tensor_parallel_size: 4
+      omni_kv_config:
+        need_send_cache: true
+        rank_mapping:
+          from_tp: 4
+          to_tp: 4
    output_connectors:
      to_stage_1: yuanrong_te_connector

  - stage_id: 1
-    devices: "4,5,6,7"
-    parallel_config:
-      tensor_parallel_size: 4
-    omni_kv_config:
-      need_recv_cache: true
-      rank_mapping:
-        from_tp: 4
-        to_tp: 4
+    runtime:
+      devices: "4,5,6,7"
+    engine_args:
+      parallel_config:
+        tensor_parallel_size: 4
+      omni_kv_config:
+        need_recv_cache: true
+        rank_mapping:
+          from_tp: 4
+          to_tp: 4
    input_connectors:
      from_stage_0: yuanrong_te_connector
 ```
@@ -41,7 +41,7 @@ With this in mind, consider the set of blocks in a 2D layout, where the row repr

 ### Example
 !!! note "Note 3"
-    Prefix caching in vLLM-Omni currently is only supported on AutoRegressive stages with one kv-cache group. Configure it with the pipeline-wide `enable_prefix_caching` field in the deploy config.
+    Prefix caching in vLLM-Omni currently is only supported on AutoRegressive stages with one kv-cache group. It can be enabled/disabled per-stage via the `enable_prefix_caching` parameter in the model's stage config.

 The way in which vLLM-Omni ties into vLLM's prefix caching is best understood by example. Say that we have the following:

@@ -0,0 +1,165 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="850" viewBox="0 0 1280 850" role="img" aria-labelledby="title desc">
+  <title id="title">AllGather DLO sharded host weights and lockstep device reconstruction</title>
+  <desc id="desc">An external orchestrator submits one synchronized wave to a DP2 by TP2 diffusion engine. Each DP replica contains TP0 and TP1 workers with private pinned host shards and two rotating GPU weight slots. DLO AllGather groups connect matching TP coordinates across DP replicas, reconstructing full rank-local blocks on each device in lockstep. Ordinary TP groups remain within each DP replica.</desc>
+  <defs>
+    <marker id="request-arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#7c3aed"/>
+    </marker>
+    <marker id="h2d-arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#d97706"/>
+    </marker>
+    <marker id="collective-arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#7c3aed"/>
+    </marker>
+    <style>
+      .canvas { fill: #ffffff; stroke: #e2e8f0; }
+      .node { fill: #f8fafc; stroke: #cbd5e1; }
+      .engine { fill: #ffffff; stroke: #cbd5e1; }
+      .replica { fill: #f8fafc; stroke: #cbd5e1; }
+      .router { fill: #f5f3ff; stroke: #c4b5fd; }
+      .scope { fill: #f8fafc; stroke: #cbd5e1; }
+      .host { fill: #fff7ed; stroke: #fdba74; }
+      .shard { fill: #d97706; }
+      .gpu { fill: #f0fdf4; stroke: #86efac; }
+      .slot-current { fill: #16a34a; }
+      .slot-next { fill: #bbf7d0; stroke: #22c55e; }
+      .lockstep { fill: #f5f3ff; stroke: #c4b5fd; }
+      .title { font: 700 25px system-ui, -apple-system, Segoe UI, sans-serif; fill: #0f172a; }
+      .subtitle { font: 500 13px system-ui, -apple-system, Segoe UI, sans-serif; fill: #64748b; }
+      .section { font: 700 15px system-ui, -apple-system, Segoe UI, sans-serif; fill: #1e293b; }
+      .section-sub { font: 500 11.5px system-ui, -apple-system, Segoe UI, sans-serif; fill: #64748b; }
+      .eyebrow { font: 700 10px system-ui, -apple-system, Segoe UI, sans-serif; letter-spacing: .8px; fill: #64748b; }
+      .box-title { font: 700 12px system-ui, -apple-system, Segoe UI, sans-serif; fill: #1e293b; }
+      .box-text { font: 500 10.5px system-ui, -apple-system, Segoe UI, sans-serif; fill: #475569; }
+      .shard-title { font: 700 13px system-ui, -apple-system, Segoe UI, sans-serif; fill: #ffffff; }
+      .shard-text { font: 500 10.5px system-ui, -apple-system, Segoe UI, sans-serif; fill: #ffffff; }
+      .slot-title { font: 700 10px system-ui, -apple-system, Segoe UI, sans-serif; fill: #ffffff; }
+      .slot-text { font: 500 9px system-ui, -apple-system, Segoe UI, sans-serif; fill: #ffffff; }
+      .slot-next-title { font: 700 10px system-ui, -apple-system, Segoe UI, sans-serif; fill: #166534; }
+      .slot-next-text { font: 500 9px system-ui, -apple-system, Segoe UI, sans-serif; fill: #166534; }
+      .request-label { font: 600 10.5px system-ui, -apple-system, Segoe UI, sans-serif; fill: #6d28d9; }
+      .h2d-label { font: 600 10.5px system-ui, -apple-system, Segoe UI, sans-serif; fill: #b45309; }
+      .collective-label { font: 700 10px system-ui, -apple-system, Segoe UI, sans-serif; fill: #6d28d9; }
+      .lock-title { font: 700 12px system-ui, -apple-system, Segoe UI, sans-serif; fill: #6d28d9; }
+      .lock-text { font: 500 10.5px system-ui, -apple-system, Segoe UI, sans-serif; fill: #5b21b6; }
+      .request-path { fill: none; stroke: #7c3aed; stroke-width: 2; marker-end: url(#request-arrow); }
+      .h2d-path { fill: none; stroke: #d97706; stroke-width: 2; marker-end: url(#h2d-arrow); }
+      .collective-path { fill: none; stroke: #7c3aed; stroke-width: 2.5; marker-start: url(#collective-arrow); marker-end: url(#collective-arrow); }
+    </style>
+  </defs>
+
+  <rect x="12" y="12" width="1256" height="826" rx="14" class="canvas"/>
+
+  <text id="title-text" x="40" y="50" class="title">AllGather DLO: sharded host weights, lockstep reconstruction</text>
+  <text x="40" y="74" class="subtitle">DP2 &#215; TP2 shown: DLO groups span DP replicas per TP coordinate; ordinary TP stays within each replica</text>
+
+  <!-- The external control plane submits one synchronized DP wave. -->
+  <rect x="390" y="94" width="500" height="68" rx="10" class="router"/>
+  <text x="640" y="121" text-anchor="middle" class="section">External router / orchestrator</text>
+  <text x="640" y="144" text-anchor="middle" class="section-sub">submits one synchronized DP wave &#183; outside vLLM-Omni DLO</text>
+
+  <rect x="30" y="184" width="1220" height="634" rx="14" class="node"/>
+  <text x="52" y="211" class="eyebrow">ONE NODE &#183; ONE SYNCHRONIZED ENGINE, PROCESS-OWNED HOST SHARDS</text>
+
+  <path d="M 640 162 L 640 232" class="request-path"/>
+  <text x="654" y="202" class="request-label">request wave</text>
+
+  <!-- One engine contains two DP replicas that execute in lockstep. -->
+  <rect x="45" y="232" width="1190" height="262" rx="12" class="engine"/>
+  <text x="68" y="261" class="section">One synchronized diffusion engine &#183; DP2 &#215; TP2</text>
+  <text x="68" y="281" class="section-sub">two DP requests follow the same block order; DLO reuses existing DP groups at each TP coordinate</text>
+
+  <!-- DP replica 0. -->
+  <rect x="65" y="296" width="515" height="186" rx="10" class="replica"/>
+  <text x="82" y="318" class="box-title">DP replica 0 &#183; request 0</text>
+  <text x="563" y="318" text-anchor="end" class="section-sub">ordinary TP group</text>
+
+  <rect x="82" y="332" width="473" height="64" rx="8" class="gpu"/>
+  <text x="98" y="351" class="eyebrow">TP0 &#183; GPU 0</text>
+  <text x="98" y="376" class="box-text">DLO backend &#183; local shard H2D</text>
+  <rect x="250" y="340" width="132" height="44" rx="6" class="slot-current"/>
+  <text x="316" y="357" text-anchor="middle" class="slot-title">SLOT 0 &#183; CURRENT</text>
+  <text x="316" y="374" text-anchor="middle" class="slot-text">full TP-local N &#183; compute</text>
+  <rect x="397" y="340" width="142" height="44" rx="6" class="slot-next"/>
+  <text x="468" y="357" text-anchor="middle" class="slot-next-title">SLOT 1 &#183; PREFETCH</text>
+  <text x="468" y="374" text-anchor="middle" class="slot-next-text">full TP-local N+1 after AG</text>
+
+  <rect x="82" y="410" width="473" height="64" rx="8" class="gpu"/>
+  <text x="98" y="429" class="eyebrow">TP1 &#183; GPU 1</text>
+  <text x="98" y="454" class="box-text">DLO backend &#183; local shard H2D</text>
+  <rect x="250" y="418" width="132" height="44" rx="6" class="slot-current"/>
+  <text x="316" y="435" text-anchor="middle" class="slot-title">SLOT 0 &#183; CURRENT</text>
+  <text x="316" y="452" text-anchor="middle" class="slot-text">full TP-local N &#183; compute</text>
+  <rect x="397" y="418" width="142" height="44" rx="6" class="slot-next"/>
+  <text x="468" y="435" text-anchor="middle" class="slot-next-title">SLOT 1 &#183; PREFETCH</text>
+  <text x="468" y="452" text-anchor="middle" class="slot-next-text">full TP-local N+1 after AG</text>
+
+  <!-- DP replica 1. -->
+  <rect x="700" y="296" width="515" height="186" rx="10" class="replica"/>
+  <text x="717" y="318" class="box-title">DP replica 1 &#183; request 1</text>
+  <text x="1198" y="318" text-anchor="end" class="section-sub">ordinary TP group</text>
+
+  <rect x="725" y="332" width="473" height="64" rx="8" class="gpu"/>
+  <text x="741" y="351" class="eyebrow">TP0 &#183; GPU 2</text>
+  <text x="741" y="376" class="box-text">DLO backend &#183; local shard H2D</text>
+  <rect x="893" y="340" width="132" height="44" rx="6" class="slot-current"/>
+  <text x="959" y="357" text-anchor="middle" class="slot-title">SLOT 0 &#183; CURRENT</text>
+  <text x="959" y="374" text-anchor="middle" class="slot-text">full TP-local N &#183; compute</text>
+  <rect x="1040" y="340" width="142" height="44" rx="6" class="slot-next"/>
+  <text x="1111" y="357" text-anchor="middle" class="slot-next-title">SLOT 1 &#183; PREFETCH</text>
+  <text x="1111" y="374" text-anchor="middle" class="slot-next-text">full TP-local N+1 after AG</text>
+
+  <rect x="725" y="410" width="473" height="64" rx="8" class="gpu"/>
+  <text x="741" y="429" class="eyebrow">TP1 &#183; GPU 3</text>
+  <text x="741" y="454" class="box-text">DLO backend &#183; local shard H2D</text>
+  <rect x="893" y="418" width="132" height="44" rx="6" class="slot-current"/>
+  <text x="959" y="435" text-anchor="middle" class="slot-title">SLOT 0 &#183; CURRENT</text>
+  <text x="959" y="452" text-anchor="middle" class="slot-text">full TP-local N &#183; compute</text>
+  <rect x="1040" y="418" width="142" height="44" rx="6" class="slot-next"/>
+  <text x="1111" y="435" text-anchor="middle" class="slot-next-title">SLOT 1 &#183; PREFETCH</text>
+  <text x="1111" y="452" text-anchor="middle" class="slot-next-text">full TP-local N+1 after AG</text>
+
+  <!-- DLO collectives connect matching TP coordinates across DP replicas. -->
+  <text x="640" y="350" text-anchor="middle" class="collective-label">DLO AG &#183; TP0 GROUP</text>
+  <path d="M 555 364 L 725 364" class="collective-path"/>
+  <text x="640" y="428" text-anchor="middle" class="collective-label">DLO AG &#183; TP1 GROUP</text>
+  <path d="M 555 442 L 725 442" class="collective-path"/>
+
+  <!-- All participants must reach the same collective in the same order. -->
+  <rect x="365" y="516" width="550" height="48" rx="8" class="lockstep"/>
+  <circle cx="395" cy="540" r="12" fill="#7c3aed"/>
+  <text x="395" y="545" text-anchor="middle" font-family="system-ui, sans-serif" font-size="15" font-weight="700" fill="#ffffff">&#8644;</text>
+  <text x="420" y="536" class="lock-title">DLO AllGather requires lockstep block order</text>
+  <text x="420" y="553" class="lock-text">every participant enters each block collective in the same sequence</text>
+
+  <!-- Each replica copies two process-owned host shards before reconstruction. -->
+  <path d="M 455 650 C 412 625, 340 610, 340 575 L 340 540 C 340 516, 318 500, 300 482" class="h2d-path"/>
+  <text x="276" y="618" text-anchor="middle" class="h2d-label">local shard H2D &#215;2</text>
+  <path d="M 825 650 C 868 625, 940 610, 940 575 L 940 540 C 940 516, 962 500, 980 482" class="h2d-path"/>
+  <text x="1004" y="618" text-anchor="middle" class="h2d-label">local shard H2D &#215;2</text>
+
+  <!-- Persistent host shards are private to workers, not mmap-shared. -->
+  <rect x="58" y="650" width="242" height="140" rx="10" class="scope"/>
+  <text x="78" y="676" class="eyebrow">GROUP TOPOLOGY</text>
+  <text x="78" y="702" class="box-title">DP2 &#215; TP2</text>
+  <text x="78" y="725" class="box-text">DLO groups: same TP coordinate</text>
+  <text x="78" y="746" class="box-text">across DP replicas</text>
+  <text x="78" y="767" class="box-text">TP stays the model-parallel group.</text>
+
+  <rect x="330" y="650" width="620" height="140" rx="10" class="host"/>
+  <text x="350" y="676" class="eyebrow">PROCESS-OWNED PINNED HOST SHARDS &#183; NOT HOST WEIGHT CACHE MMAP</text>
+  <rect x="370" y="692" width="260" height="60" rx="8" class="shard"/>
+  <text x="500" y="716" text-anchor="middle" class="shard-title">DP replica 0 &#183; private</text>
+  <text x="500" y="738" text-anchor="middle" class="shard-text">TP0 shard 0/2 &#183; TP1 shard 0/2</text>
+  <rect x="650" y="692" width="260" height="60" rx="8" class="shard"/>
+  <text x="780" y="716" text-anchor="middle" class="shard-title">DP replica 1 &#183; private</text>
+  <text x="780" y="738" text-anchor="middle" class="shard-text">TP0 shard 1/2 &#183; TP1 shard 1/2</text>
+  <text x="640" y="773" text-anchor="middle" class="box-text">Across each DLO group, shards total approximately one rank-local runtime block copy</text>
+
+  <rect x="980" y="650" width="242" height="140" rx="10" class="scope"/>
+  <text x="1000" y="676" class="eyebrow">HOT PATH &#183; PER WORKER</text>
+  <text x="1000" y="702" class="box-title">Prefetch next block</text>
+  <text x="1000" y="725" class="box-text">local pinned shard &#8594; GPU</text>
+  <text x="1000" y="746" class="box-text">DLO AllGather &#8594; full block</text>
+  <text x="1000" y="767" class="box-text">rotate slots; overlap compute</text>
+</svg>
@@ -0,0 +1,202 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="850" viewBox="0 0 1280 850" role="img" aria-labelledby="title desc">
+  <title id="title">No-AllGather DLO shared host weights and independent runtime orchestration</title>
+  <desc id="desc">An external orchestrator routes requests to two independently scheduled TP2 diffusion engines on one node. Each engine contains two rank-local workers and devices, with private loaders, mmap views, DLO runtime hooks, streams, events, and rotating GPU slots. Equivalent TP0 workers across engines map one immutable TP0 entry in the host weight cache, while equivalent TP1 workers map a separate TP1 entry, without a cross-engine DLO AllGather.</desc>
+  <defs>
+    <marker id="request-arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#7c3aed"/>
+    </marker>
+    <marker id="mapping-arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#d97706"/>
+    </marker>
+    <marker id="runtime-arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#2563eb"/>
+    </marker>
+    <style>
+      .canvas { fill: #ffffff; stroke: #e2e8f0; }
+      .node { fill: #f8fafc; stroke: #cbd5e1; }
+      .engine { fill: #ffffff; stroke: #cbd5e1; }
+      .router { fill: #f5f3ff; stroke: #c4b5fd; }
+      .scope { fill: #f8fafc; stroke: #cbd5e1; }
+      .cache { fill: #fff7ed; stroke: #fdba74; }
+      .payload { fill: #d97706; }
+      .loader { fill: #f1f5f9; stroke: #cbd5e1; }
+      .mapping { fill: #fffbeb; stroke: #f59e0b; }
+      .hook { fill: #eff6ff; stroke: #60a5fa; }
+      .gpu { fill: #f0fdf4; stroke: #86efac; }
+      .device { fill: #ffffff; stroke: #86efac; }
+      .slot-current { fill: #16a34a; }
+      .slot-next { fill: #bbf7d0; stroke: #22c55e; }
+      .no-collective { fill: #fef2f2; stroke: #fca5a5; }
+      .title { font: 700 25px system-ui, -apple-system, Segoe UI, sans-serif; fill: #0f172a; }
+      .subtitle { font: 500 13px system-ui, -apple-system, Segoe UI, sans-serif; fill: #64748b; }
+      .section { font: 700 15px system-ui, -apple-system, Segoe UI, sans-serif; fill: #1e293b; }
+      .section-sub { font: 500 11.5px system-ui, -apple-system, Segoe UI, sans-serif; fill: #64748b; }
+      .eyebrow { font: 700 10px system-ui, -apple-system, Segoe UI, sans-serif; letter-spacing: .8px; fill: #64748b; }
+      .box-title { font: 700 12px system-ui, -apple-system, Segoe UI, sans-serif; fill: #1e293b; }
+      .box-text { font: 500 10.5px system-ui, -apple-system, Segoe UI, sans-serif; fill: #475569; }
+      .payload-title { font: 700 14px system-ui, -apple-system, Segoe UI, sans-serif; fill: #ffffff; }
+      .payload-text { font: 500 11px system-ui, -apple-system, Segoe UI, sans-serif; fill: #ffffff; }
+      .device-title { font: 700 9px system-ui, -apple-system, Segoe UI, sans-serif; fill: #166534; }
+      .slot-text { font: 700 8px system-ui, -apple-system, Segoe UI, sans-serif; fill: #ffffff; }
+      .slot-next-text { font: 700 8px system-ui, -apple-system, Segoe UI, sans-serif; fill: #166534; }
+      .arrow-label { font: 600 10.5px system-ui, -apple-system, Segoe UI, sans-serif; fill: #475569; }
+      .request-label { font: 600 10.5px system-ui, -apple-system, Segoe UI, sans-serif; fill: #6d28d9; }
+      .mapping-label { font: 600 10.5px system-ui, -apple-system, Segoe UI, sans-serif; fill: #b45309; }
+      .no-title { font: 700 12px system-ui, -apple-system, Segoe UI, sans-serif; fill: #b91c1c; }
+      .no-text { font: 500 10.5px system-ui, -apple-system, Segoe UI, sans-serif; fill: #7f1d1d; }
+      .request-path { fill: none; stroke: #7c3aed; stroke-width: 2; marker-end: url(#request-arrow); }
+      .mapping-path { fill: none; stroke: #d97706; stroke-width: 2; marker-end: url(#mapping-arrow); }
+      .runtime-path { fill: none; stroke: #2563eb; stroke-width: 2; marker-end: url(#runtime-arrow); }
+      .startup-path { fill: none; stroke: #94a3b8; stroke-width: 1.5; stroke-dasharray: 4 3; marker-end: url(#runtime-arrow); }
+    </style>
+  </defs>
+
+  <rect x="12" y="12" width="1256" height="826" rx="14" class="canvas"/>
+
+  <text id="title-text" x="40" y="50" class="title">No-AllGather DLO: TP-coordinate host sharing, independent engines</text>
+  <text x="40" y="74" class="subtitle">TP2 shown: each engine owns two devices; equivalent workers share one host payload per TP coordinate</text>
+
+  <!-- The control plane remains outside DLO. -->
+  <rect x="390" y="94" width="500" height="68" rx="10" class="router"/>
+  <text x="640" y="121" text-anchor="middle" class="section">External router / orchestrator</text>
+  <text x="640" y="144" text-anchor="middle" class="section-sub">independent request placement &#183; outside vLLM-Omni DLO</text>
+
+  <!-- One node contains independent engine runtimes over one shared physical backing. -->
+  <rect x="30" y="184" width="1220" height="634" rx="14" class="node"/>
+  <text x="52" y="211" class="eyebrow">ONE NODE &#183; PROCESS-LOCAL ENGINES OVER SHARED PHYSICAL HOST MEMORY</text>
+
+  <!-- Independent request routing from the external orchestrator. -->
+  <path d="M 500 162 C 456 181, 400 204, 332 232" class="request-path"/>
+  <text x="416" y="194" class="request-label">request A</text>
+  <path d="M 780 162 C 824 181, 880 204, 948 232" class="request-path"/>
+  <text x="864" y="194" class="request-label">request B</text>
+
+  <!-- Independent engine A. -->
+  <rect x="45" y="232" width="575" height="250" rx="12" class="engine"/>
+  <text x="68" y="261" class="section">Independent engine A</text>
+  <text x="68" y="281" class="section-sub">TP2 &#183; two rank-local workers &#183; own request schedule and DLO state</text>
+
+  <rect x="68" y="310" width="98" height="130" rx="8" class="loader"/>
+  <text x="117" y="335" text-anchor="middle" class="eyebrow">STARTUP &#215;2</text>
+  <text x="117" y="359" text-anchor="middle" class="box-title">rank-local</text>
+  <text x="117" y="377" text-anchor="middle" class="box-title">loaders</text>
+  <text x="117" y="402" text-anchor="middle" class="box-text">final transforms</text>
+  <text x="117" y="421" text-anchor="middle" class="box-text">publish / join</text>
+
+  <rect x="180" y="310" width="112" height="130" rx="8" class="mapping"/>
+  <text x="236" y="335" text-anchor="middle" class="eyebrow">HOST VIEWS &#215;2</text>
+  <text x="236" y="359" text-anchor="middle" class="box-title">TP0 mmap</text>
+  <text x="236" y="377" text-anchor="middle" class="box-title">TP1 mmap</text>
+  <text x="236" y="402" text-anchor="middle" class="box-text">process-local</text>
+  <text x="236" y="421" text-anchor="middle" class="box-text">optional registration</text>
+
+  <rect x="306" y="310" width="120" height="130" rx="8" class="hook"/>
+  <text x="366" y="335" text-anchor="middle" class="eyebrow">RUNTIME &#215;2</text>
+  <text x="366" y="359" text-anchor="middle" class="box-title">DLO backends</text>
+  <text x="366" y="377" text-anchor="middle" class="box-title">+ block hooks</text>
+  <text x="366" y="402" text-anchor="middle" class="box-text">private streams</text>
+  <text x="366" y="421" text-anchor="middle" class="box-text">events + state</text>
+
+  <rect x="440" y="310" width="157" height="130" rx="8" class="gpu"/>
+  <text x="518" y="330" text-anchor="middle" class="eyebrow">TWO DEVICES</text>
+  <rect x="450" y="340" width="137" height="42" rx="6" class="device"/>
+  <text x="518" y="353" text-anchor="middle" class="device-title">TP0 &#183; GPU A0</text>
+  <rect x="457" y="359" width="58" height="16" rx="4" class="slot-current"/>
+  <text x="486" y="370" text-anchor="middle" class="slot-text">SLOT 0 NOW</text>
+  <rect x="521" y="359" width="58" height="16" rx="4" class="slot-next"/>
+  <text x="550" y="370" text-anchor="middle" class="slot-next-text">SLOT 1 NEXT</text>
+  <rect x="450" y="389" width="137" height="42" rx="6" class="device"/>
+  <text x="518" y="402" text-anchor="middle" class="device-title">TP1 &#183; GPU A1</text>
+  <rect x="457" y="408" width="58" height="16" rx="4" class="slot-current"/>
+  <text x="486" y="419" text-anchor="middle" class="slot-text">SLOT 0 NOW</text>
+  <rect x="521" y="408" width="58" height="16" rx="4" class="slot-next"/>
+  <text x="550" y="419" text-anchor="middle" class="slot-next-text">SLOT 1 NEXT</text>
+
+  <path d="M 166 375 L 180 375" class="startup-path"/>
+  <path d="M 292 375 L 306 375" class="runtime-path"/>
+  <path d="M 426 375 L 440 375" class="runtime-path"/>
+
+  <!-- Independent engine B. -->
+  <rect x="660" y="232" width="575" height="250" rx="12" class="engine"/>
+  <text x="683" y="261" class="section">Independent engine B</text>
+  <text x="683" y="281" class="section-sub">TP2 &#183; two rank-local workers &#183; own request schedule and DLO state</text>
+
+  <rect x="683" y="310" width="98" height="130" rx="8" class="loader"/>
+  <text x="732" y="335" text-anchor="middle" class="eyebrow">STARTUP &#215;2</text>
+  <text x="732" y="359" text-anchor="middle" class="box-title">rank-local</text>
+  <text x="732" y="377" text-anchor="middle" class="box-title">loaders</text>
+  <text x="732" y="402" text-anchor="middle" class="box-text">final transforms</text>
+  <text x="732" y="421" text-anchor="middle" class="box-text">publish / join</text>
+
+  <rect x="795" y="310" width="112" height="130" rx="8" class="mapping"/>
+  <text x="851" y="335" text-anchor="middle" class="eyebrow">HOST VIEWS &#215;2</text>
+  <text x="851" y="359" text-anchor="middle" class="box-title">TP0 mmap</text>
+  <text x="851" y="377" text-anchor="middle" class="box-title">TP1 mmap</text>
+  <text x="851" y="402" text-anchor="middle" class="box-text">process-local</text>
+  <text x="851" y="421" text-anchor="middle" class="box-text">optional registration</text>
+
+  <rect x="921" y="310" width="120" height="130" rx="8" class="hook"/>
+  <text x="981" y="335" text-anchor="middle" class="eyebrow">RUNTIME &#215;2</text>
+  <text x="981" y="359" text-anchor="middle" class="box-title">DLO backends</text>
+  <text x="981" y="377" text-anchor="middle" class="box-title">+ block hooks</text>
+  <text x="981" y="402" text-anchor="middle" class="box-text">private streams</text>
+  <text x="981" y="421" text-anchor="middle" class="box-text">events + state</text>
+
+  <rect x="1055" y="310" width="157" height="130" rx="8" class="gpu"/>
+  <text x="1133" y="330" text-anchor="middle" class="eyebrow">TWO DEVICES</text>
+  <rect x="1065" y="340" width="137" height="42" rx="6" class="device"/>
+  <text x="1133" y="353" text-anchor="middle" class="device-title">TP0 &#183; GPU B0</text>
+  <rect x="1072" y="359" width="58" height="16" rx="4" class="slot-current"/>
+  <text x="1101" y="370" text-anchor="middle" class="slot-text">SLOT 0 NOW</text>
+  <rect x="1136" y="359" width="58" height="16" rx="4" class="slot-next"/>
+  <text x="1165" y="370" text-anchor="middle" class="slot-next-text">SLOT 1 NEXT</text>
+  <rect x="1065" y="389" width="137" height="42" rx="6" class="device"/>
+  <text x="1133" y="402" text-anchor="middle" class="device-title">TP1 &#183; GPU B1</text>
+  <rect x="1072" y="408" width="58" height="16" rx="4" class="slot-current"/>
+  <text x="1101" y="419" text-anchor="middle" class="slot-text">SLOT 0 NOW</text>
+  <rect x="1136" y="408" width="58" height="16" rx="4" class="slot-next"/>
+  <text x="1165" y="419" text-anchor="middle" class="slot-next-text">SLOT 1 NEXT</text>
+
+  <path d="M 781 375 L 795 375" class="startup-path"/>
+  <path d="M 907 375 L 921 375" class="runtime-path"/>
+  <path d="M 1041 375 L 1055 375" class="runtime-path"/>
+
+  <!-- The runtimes are deliberately not coupled by a DLO collective. -->
+  <rect x="365" y="516" width="550" height="44" rx="8" class="no-collective"/>
+  <circle cx="395" cy="538" r="12" fill="#dc2626"/>
+  <path d="M 389 532 L 401 544 M 401 532 L 389 544" stroke="#ffffff" stroke-width="2.2"/>
+  <text x="420" y="534" class="no-title">No cross-engine DLO AllGather</text>
+  <text x="420" y="551" class="no-text">shared host pages do not couple request order, progress, or failure domains</text>
+  <text x="640" y="592" text-anchor="middle" class="section-sub">Ordinary TP / SP model collectives, when configured, remain inside each engine</text>
+
+  <!-- Each engine maps both TP-coordinate payloads from the shared host cache. -->
+  <path d="M 455 650 C 412 625, 340 610, 340 570 L 340 525 C 340 478, 278 454, 236 440" class="mapping-path"/>
+  <text x="286" y="617" text-anchor="middle" class="mapping-label">TP0 + TP1 mappings</text>
+  <path d="M 825 650 C 868 625, 940 610, 940 570 L 940 525 C 940 478, 893 454, 851 440" class="mapping-path"/>
+  <text x="994" y="617" text-anchor="middle" class="mapping-label">TP0 + TP1 mappings</text>
+
+  <!-- One node-local physical backing, visually beneath its consumers. -->
+  <rect x="58" y="650" width="242" height="140" rx="10" class="scope"/>
+  <text x="78" y="676" class="eyebrow">SHARING SCOPE</text>
+  <text x="78" y="702" class="box-title">TP2: two coordinate entries</text>
+  <text x="78" y="725" class="box-text">one physical copy per coordinate</text>
+  <text x="78" y="746" class="box-text">A/TP0 + B/TP0 &#8594; TP0 entry</text>
+  <text x="78" y="767" class="box-text">A/TP1 + B/TP1 &#8594; TP1 entry</text>
+
+  <rect x="330" y="650" width="620" height="140" rx="10" class="cache"/>
+  <text x="350" y="676" class="eyebrow">NODE-LOCAL IMMUTABLE HOST WEIGHT CACHE &#183; ONE COPY PER TP COORDINATE</text>
+  <rect x="370" y="692" width="260" height="60" rx="8" class="payload"/>
+  <text x="500" y="717" text-anchor="middle" class="payload-title">TP0 physical payload</text>
+  <text x="500" y="738" text-anchor="middle" class="payload-text">shared by A/TP0 + B/TP0</text>
+  <rect x="650" y="692" width="260" height="60" rx="8" class="payload"/>
+  <text x="780" y="717" text-anchor="middle" class="payload-title">TP1 physical payload</text>
+  <text x="780" y="738" text-anchor="middle" class="payload-text">shared by A/TP1 + B/TP1</text>
+  <text x="640" y="773" text-anchor="middle" class="box-text">Identity includes final layout + TP coordinate; engine and DP replica are excluded</text>
+
+  <rect x="980" y="650" width="242" height="140" rx="10" class="scope"/>
+  <text x="1000" y="676" class="eyebrow">WHAT STAYS PRIVATE</text>
+  <text x="1000" y="702" class="box-title">Per worker / process</text>
+  <text x="1000" y="725" class="box-text">mmap object and validation state</text>
+  <text x="1000" y="746" class="box-text">optional host registration</text>
+  <text x="1000" y="767" class="box-text">hooks, streams, events, GPU slots</text>
+</svg>
@@ -18,7 +18,6 @@ implementation contract; it is not, by itself, a general support claim.
 ### Runtime and stage execution

 - [Disaggregated Inference](feature/disaggregated_inference.md)
- [Host Weight Runtime](feature/host_weight_runtime.md)
 - [Async Chunk](feature/async_chunk.md)
 - [Async Diffusion Output](feature/async_diffusion_output.md)
 - [Async Omni Output Materialization](feature/omni_async_output_materialization.md)
@@ -89,15 +88,14 @@ The design contracts separate selection mechanics from backend algorithms:
 - [Model Integration](module/model_integration.md)
 - [Autoregressive Runtime](module/ar_runtime.md)
 - Diffusion
-    - [Overview](module/diffusion/index.md)
-    - [Runtime](module/diffusion/diffusion_runtime.md)
-    - [Model Integration](module/diffusion/diffusion_model_integration.md)
-    - [Continuous Batching](module/diffusion/continuous_batching.md)
-    - [Parallelism](module/diffusion/parallelism.md)
-    - [Offloader](module/diffusion/offloader.md)
+  - [Overview](module/diffusion/index.md)
+  - [Runtime](module/diffusion/diffusion_runtime.md)
+  - [Model Integration](module/diffusion/diffusion_model_integration.md)
+  - [Continuous Batching](module/diffusion/continuous_batching.md)
+  - [Parallelism](module/diffusion/parallelism.md)
+  - [Offloader](module/diffusion/offloader.md)
 - [Execution Platforms](module/execution_platforms.md)
 - [Cache Management](module/cache_management.md)
- [Host Weight Runtime](module/host_weight_runtime.md)
 - [Quantization](module/quantization.md)
 - [Observability](module/observability.md)
 - [Profiling](module/profiling.md)
@@ -1,281 +0,0 @@
---
-title: Host Weight Runtime
-kind: module
-status: draft
-owners:
-  - "@hsliuustc0106"
-primary_code_paths:
-  - vllm_omni/host_weight_runtime/**
-related_code_paths:
-  - vllm_omni/diffusion/model_loader/**
-  - vllm_omni/diffusion/offloader/**
-depends_on:
-  - model_integration.md
-  - quantization.md
-validation_paths:
-  - tests/host_weight_runtime/**
-upstream_refs:
-  - https://github.com/vllm-project/vllm-omni/issues/6414
-last_reviewed: 2026-08-21
---
-
-# Host Weight Runtime
-
-The Host Weight Runtime is a loader-adjacent, transport-independent foundation
-for reusing immutable, runtime-ready model weights. It separates the semantic
-question—"are these exactly the weights this loader requested?"—from the
-physical question—"where is the validated host representation stored?"
-
-The runtime can save repeated checkpoint loading, transformation, and peak host
-memory when several workers need the same final representation. It also creates
-a second, versioned path for reconstructing a valid model, so a cache miss or
-recoverable store failure normally falls back to the canonical loader.
-
-This module does not enable host-weight caching for any model by itself. A model
-integration must still provide an exact identity, a producer, and a restorer.
-For feature behavior and consumer integration requirements, see the
-[Host Weight Runtime feature design](../feature/host_weight_runtime.md).
-
-## Component boundary
-
-```mermaid
-flowchart LR
-    LA["Model loader adapter"] -->|"exact identity + policy"| RT["HostWeightRuntime"]
-    RT -->|"lookup / get_or_build"| ST["HostWeightStore"]
-    PR["WeightProducer"] -->|"runtime-ready tensors"| ST
-    ST -->|"validated mmap views"| LE["HostWeightLease"]
-    LE --> RE["WeightRestorer"]
-    RE --> MO["Restored host model"]
-    MO --> TR["DLO or another GPU transport"]
-
-    CS["Canonical model source"] --> PR
-    LA -. "fallback" .-> CS
-```
-
-The contracts have deliberately narrow ownership:
-
- `HostWeightRuntime` applies resolution and fallback policy and emits one
-  terminal resolution report. Explicit post-load publication emits a separate
-  report and closes its store-returned lease before returning; it does not
-  revise the completed resolution.
-  The runtime does not own a model or call the canonical loader.
- `HostWeightStore` owns artifact lookup, coordinated construction,
-  publication, validation, quarantine, and lifecycle.
- `HostWeightLease` owns process-local tensor views, mapped-file resources, and
-  the shared artifact lock that stabilizes their lifetime.
- `WeightProducer` creates one declared final-layout representation. It writes
-  only through a store-scoped writer and cannot publish paths directly.
- `WeightRestorer` validates a lease-to-model plan without mutation. Its
-  one-shot `commit() -> None` is the sole model-mutating phase. Concrete
-  restorers remain with the model or quantization integration.
- GPU transport owns page registration, private staging, H2D scheduling, and
-  lease release. DLO must not parse manifests or manage store artifacts.
-
-## Exact semantic identity
-
-Storage lookup is exact; the store never coerces one representation into
-another. `WeightArtifactIdentity` includes:
-
- immutable model revision and source-file fingerprint;
- component and ownership boundary;
- runtime representation, dtype, and representation metadata;
- final tensor layout and semantic parallel coordinates;
- static adaptation identity; and
- producer version, implementation fingerprint, manifest schema, and restorer
-  schema.
-
-The identity excludes transfer policy such as registered mmap versus private
-pinned staging. Those paths move the same host representation and must not
-produce duplicate artifacts.
-
-Parallel coordinates follow semantics rather than process topology:
-
- TP size and rank are included when they change tensor contents or shape.
- DP rank is excluded for replicated weights.
- SP size and backend are included when they affect layout. SP rank is excluded
-  only when all SP ranks consume an identical representation.
- PP, EP, or future parallel modes must be added by the model adapter whenever
-  they change component ownership or tensor layout.
-
-Dynamic LoRA overlays are not cached as base weights. A statically merged
-adapter is a distinct artifact identity with its own fingerprint.
-
-## Deterministic resolution
-
-The loader first resolves the canonical source and computes the exact requested
-identity. The runtime then follows this order:
-
-```text
-validated local artifact
-    -> exact remote artifact materialized locally (future)
-    -> registered local producer
-    -> canonical loader fallback, if policy permits
-```
-
-An already published local artifact wins because it avoids network transfer and
-is already in node-accessible storage. "Wins" means the highest-priority valid
-representation, not whichever backing responds first.
-
-Configuration modes are:
-
- `disabled`: return the canonical-direct outcome without probing a root,
-  credentials, topology, or identity;
- `preferred`: recoverable store failures may return canonical fallback; and
- `required`: fail when no exact lease can be acquired.
-
-Failure-to-action policy is centralized in `HostWeightRuntime`. A clean miss or
-invalid cache artifact may fall back in preferred mode. A typed failure may do
-so only when it is marked retryable; unsupported capabilities, identity
-collisions, producer failures, and publication failures remain visible as
-startup failures.
-
-`coordination_timeout_seconds` bounds acquisition of lookup and build locks; it
-is not a hard wall-clock deadline for in-process validation, production, or
-atomic publication. Once this V1 implementation becomes the producer, the
-synchronous producer and publication run to completion. A hung producer blocks
-its owning process and requires external process supervision; enforceable
-producer cancellation requires a future process-isolated producer contract. A
-waiter timing out never cancels another process's valid build.
-
-Remote providers are represented by protocols but are explicitly unsupported
-in the first implementation. Pre-load `resolve()` invokes only
-`PRE_LOAD_SAFE` producers. A loader that completed canonical materialization
-may explicitly call `publish_after_load()` with a `POST_LOAD_ONLY` producer
-when `allow_post_load_publish` is enabled.
-
-`allow_local_build` controls producer use during pre-load resolution;
-`allow_post_load_publish` independently controls the explicit post-load entry
-point. This permits lookup-only warm starts that populate a missing artifact
-only after the canonical loader has established the current model.
-
-Post-load publication is synchronous in V1, but its outcome is independent of
-the already completed resolution. A store failure is returned in a separate
-publication report and cannot turn a valid canonical model into a failed
-resolution. On success, the runtime closes the validated store lease before
-returning the report. Post-load publication only warms future startups; it does
-not restore, rebind, or otherwise mutate the canonically loaded model serving
-the current startup.
-
-## Restoration transaction boundary
-
-`WeightRestorer.plan_restore()` is validation-only: it must not modify the model
-or lease. The returned plan may be committed exactly once, `commit()` returns
-`None`, and commit is the sole phase allowed to mutate the model. Registration,
-staging, and GPU transfer remain transport responsibilities rather than restore
-side effects.
-
-If planning fails, preferred-mode canonical fallback may reuse the untouched
-model. If commit begins and then fails, the model is considered partially
-hydrated and must be discarded; canonical fallback must construct a fresh model
-instance instead of reusing it.
-
-## Filesystem domain and artifact lifecycle
-
-A storage domain describes physical locality and policy; it is not part of
-semantic identity. The first implementation supports node- or NUMA-scoped
-roots on verified local disk filesystems or tmpfs. The detected kernel
-filesystem type is preserved in `domain.json` and inspection output. Known
-remote filesystems and unknown filesystem types are rejected rather than being
-silently treated as local disk, because cross-node page cache and advisory-lock
-semantics do not satisfy this backend's contract. A NUMA root alone does not
-guarantee page placement; CPU pinning, local first-touch/prefault, and residency
-evidence belong to a later topology-aware integration.
-
-```text
-<domain>/
-├── domain.json
-├── domain-policy.json
-├── locks/
-│   ├── <identity>.build.lock
-│   └── <identity>.artifact.lock
-├── artifacts/<identity>/
-│   ├── READY.json
-│   ├── manifest.json
-│   └── *.safetensors
-├── tmp/
-├── quarantine/
-└── deny/
-```
-
-Lock files live outside replaceable artifact directories. Every cooperative
-mutation follows one lock order: build lock, then exclusive artifact lock.
-Lookup acquires a shared artifact lock, validates `READY` and the manifest,
-opens payloads with non-following descriptor-based access, creates mmap-backed
-views, and transfers that shared lock to the lease.
-
-Lease acquisition rechecks the producer and restorer schemas against the exact
-identity. Malformed safetensors payloads are reported as typed invalid
-artifacts and denied rather than escaping the resolution policy as raw parser
-exceptions.
-
-Each `FileLock` records its creator PID. A forked child closes an inherited lock
-descriptor without issuing `LOCK_UN`, because `flock` state belongs to the
-shared open-file description and unlocking in the child would also release the
-parent's active lease lock.
-
-Publication follows this lifecycle:
-
-```text
-ABSENT -> invisible temporary build -> fully hashed and fsynced
-       -> atomic rename -> READY
-
-READY -> denied -> quarantined -> explicit removal
-```
-
-`READY.json` is written last in the temporary directory. Readers therefore see
-either a complete validated artifact or a miss, never an in-progress build.
-Failed process-local builds are left invisible and a later build owner removes
-their stale temporary directories. Explicit cleanup is nonblocking and reports
-an active builder or lease instead of unlinking live mappings.
-
-## Validation and capacity
-
-Every publication computes full file and tensor hashes. Local lookup supports:
-
- `manifest_and_metadata`, which validates identity, immutable publication
-  metadata, file descriptors, sizes, tensor keys, shapes, dtypes, and strides;
-  and
- `full_checksum`, which additionally reads and hashes every payload file.
-
-Filesystem verity is modeled but unsupported. Invalid artifacts receive an
-external deny marker before their shared lookup lock is released; a build owner
-then quarantines the immutable directory under the exclusive lock.
-Lookup checks the marker both before validation and after constructing the
-lease so a weaker overlapping lookup cannot return a lease after a stronger
-validation has denied the artifact.
-
-`inspect_domain()` and `inspect_artifact()` return typed, read-only snapshots.
-Inspection validation does not create a deny marker. Reported lock activity is
-point-in-time evidence only; kernel locks are not a persistent owner registry.
-
-Capacity policy covers all store-owned bytes, including ready, temporary, and
-quarantined data. The local writer preflights `max_artifact_bytes`,
-`max_store_bytes`, and `min_free_bytes`, and preallocates payloads where the
-filesystem supports it. `ENOSPC` remains a normal typed store failure because
-concurrent preflight is inherently racy. Automatic eviction and strict
-concurrent reservations are not implemented.
-
-For tmpfs, artifact bytes are host-memory consumption and may consume swap;
-they must not be reported operationally as ordinary disk capacity. The store
-owns files and reports capacity. The kernel controls page-cache residency, and
-transport controls registration or page locking.
-
-## First implementation scope
-
-The foundation implements a CPU local filesystem store and
-`SINGLE_PROCESS` production for one exact artifact. It intentionally adds no:
-
- public CLI or DLO configuration;
- BF16, FP8, or model-specific producer/restorer;
- change to DLO AllGather or no-AllGather behavior;
- CUDA registration, pinned staging, or H2D scheduling;
- remote provider, group-cohort producer, artifact bundle, eviction, or
-  cross-node coordination.
-
-Consumer PRs must prove ordinary-loader parity, warm-hit work avoidance,
-parallel-layout correctness, clean teardown, shared-backing evidence, and
-representation-specific startup and memory behavior. Generic foundation tests
-remain CPU-only and make no production performance claim.
-
-The complete rationale and staged rollout are tracked in
-[RFC #6414](https://github.com/vllm-project/vllm-omni/issues/6414).
@@ -42,7 +42,7 @@ and execution behavior to stable runtime contracts.
 ### MODEL-INV-001: Registration is explicit

 **Rule:** A model integration MUST declare how its model class, loader, input
-processor, and pipeline configuration are selected.
+processor, and stage configuration are selected.

 ### MODEL-INV-002: Model code does not route stages

@@ -10,8 +10,9 @@ owners:
 primary_code_paths:
  - vllm_omni/config/**
  - vllm_omni/deploy/**
-  - vllm_omni/model_executor/models/*/pipeline.py
-related_code_paths: []
+  - vllm_omni/model_executor/stage_configs/**
+related_code_paths:
+  - vllm_omni/platforms/*/stage_configs/**
 depends_on: []
 validation_paths:
  - tests/config/**
@@ -94,7 +95,7 @@ parallel input is effective for a diffusion stage.
 ## Safe-change guide while deferred

 Changes should trace every affected producer to its runtime consumer and test
-the structured pipeline, CLI, and deployment paths that are actually supported.
+the structured, legacy, CLI, and deployment paths that are actually supported.
 For inherited vLLM fields, tests should separately cover constructor behavior
 and effective `EngineArgs` projection. Do not infer a stable contract from
 this placeholder page.
@@ -111,7 +111,7 @@ This post walks through each optimization in the same order they are typically e

 For both Qwen3-Omni and Qwen3-TTS, batching is a pipeline-level optimization:

- Requests are grouped per stage using `stages[].max_num_seqs`
+- Requests are grouped per stage using `runtime.max_batch_size`
 - Each stage executes batch inference with its own scheduler/worker
 - Stage outputs are routed to downstream stages with per-request mapping preserved

@@ -171,7 +171,7 @@ At concurrency 10, batching alone brings Qwen3-TTS RTF from 2.19 (slower than re

 In decode-heavy serving, repeatedly launching many small kernels from CPU can become a visible overhead. CUDA Graph reduces this overhead by capturing and replaying stable execution graphs.

-In deploy configs, this is represented by `enforce_eager: false` for stages where graph capture is desired (Thinker/Talker), while Code2Wav keeps eager mode depending on stage behavior.
+In stage configs, this is represented by `enforce_eager: false` for stages where graph capture is desired (Thinker/Talker), while Code2Wav keeps eager mode depending on stage behavior.

 ### CUDA Graph results on top of batching

@@ -320,7 +320,7 @@ In the async chunk pipeline, the standard `codec_chunk_frames` is 25 (each chunk

 **Dynamic initial chunk sizing (default behavior):**

-Rather than using a fixed initial chunk size, vLLM-Omni dynamically selects it based on current server load. The initial chunk size is chosen from power-of-2 steps [2, 4, 8, 16] based on load factor (`active_requests / max_num_seqs`):
+Rather than using a fixed initial chunk size, vLLM-Omni dynamically selects it based on current server load. The initial chunk size is chosen from power-of-2 steps [2, 4, 8, 16] based on load factor (`active_requests / max_batch_size`):

 | Server load | Initial chunk frames | Rationale |
 | --- | --- | --- |
@@ -349,15 +349,16 @@ This overrides the dynamic calculation for that request.
 **Config (server-side):**

 ```yaml
-connectors:
-  connector_of_shared_memory:
-    name: SharedMemoryConnector
-    extra:
-      codec_streaming: true
-      codec_chunk_frames: 25              # standard chunk size (~2s of audio)
-      codec_left_context_frames: 25
-      # initial chunk is computed dynamically by default
-      # set initial_codec_chunk_frames: 2 to force a fixed value
+runtime:
+  connectors:
+    connector_of_shared_memory:
+      name: SharedMemoryConnector
+      extra:
+        codec_streaming: true
+        codec_chunk_frames: 25              # standard chunk size (~2s of audio)
+        codec_left_context_frames: 25
+        # initial chunk is computed dynamically by default
+        # set initial_codec_chunk_frames: 2 to force a fixed value
 ```

 The 64 ms TTFP result reported above for Qwen3-TTS at concurrency 1 uses the dynamic initial chunk, which picks `initial_codec_chunk_frames=2` at low load. At higher concurrency the dynamic sizing increases the initial chunk to maintain decode efficiency.
@@ -407,7 +408,7 @@ vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct \

 Notes:

- `stages[].max_num_seqs` controls stage-level batching.
+- `runtime.max_batch_size` controls stage-level batching.
 - Thinker/Talker commonly use `enforce_eager: false` for CUDA Graph paths.
 - Code2Wav often remains eager (`enforce_eager: true`) depending on runtime behavior.
 - Qwen3-Omni defaults `VLLM_USE_FLASHINFER_MOE_FP16=0`. The Triton has been more stable & faster
@@ -425,26 +426,33 @@ vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct \

 ```yaml
 async_chunk: true
-stages:
+stage_args:
  - stage_id: 0  # thinker
-    max_num_seqs: 64
-    enforce_eager: false
-    max_num_batched_tokens: 32768
+    runtime:
+      max_batch_size: 64
+    engine_args:
+      enforce_eager: false
+      max_num_batched_tokens: 32768
+      custom_process_next_stage_input_func: >-
+        vllm_omni.model_executor.stage_input_processors.qwen3_omni.thinker2talker_async_chunk

  - stage_id: 1  # talker
-    max_num_seqs: 64
-    enforce_eager: false
-    max_num_batched_tokens: 32768
+    runtime:
+      max_batch_size: 64
+    engine_args:
+      enforce_eager: false
+      max_num_batched_tokens: 32768
+      custom_process_next_stage_input_func: >-
+        vllm_omni.model_executor.stage_input_processors.qwen3_omni.talker2code2wav_async_chunk

  - stage_id: 2  # code2wav
-    max_num_seqs: 64
-    enforce_eager: true
-    max_num_batched_tokens: 51200
+    runtime:
+      max_batch_size: 64
+    engine_args:
+      enforce_eager: true
+      max_num_batched_tokens: 51200
 ```

-The async handoff processors are fixed by the registered Qwen3-Omni
-`PipelineConfig`; deploy YAML only selects `async_chunk` and runtime sizing.
-
 #### Reproduce Qwen3-Omni benchmarks

 ```bash
@@ -475,7 +483,7 @@ vllm-omni serve Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice \

 The default config (`qwen3_tts.yaml`) enables the full optimization stack:

- Batching with `max_num_seqs: 10` on the Talker stage
+- Batching with `max_batch_size: 10` on the Talker stage
 - CUDA Graph on the Talker (`enforce_eager: false`)
 - Async chunk with streaming transport

@@ -492,29 +500,33 @@ vllm-omni serve Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice \

 ```yaml
 async_chunk: true
-stages:
+stage_args:
  - stage_id: 0  # Talker (AR decoder)
-    max_num_seqs: 10
-    enforce_eager: false
-    max_num_batched_tokens: 512
+    runtime:
+      max_batch_size: 10
+    engine_args:
+      enforce_eager: false
+      max_num_batched_tokens: 512
+      custom_process_next_stage_input_func: >-
+        vllm_omni.model_executor.stage_input_processors.qwen3_tts.talker2code2wav_async_chunk

  - stage_id: 1  # Code2Wav (vocoder)
-    max_num_seqs: 1
-    enforce_eager: true
-    max_num_batched_tokens: 8192
+    runtime:
+      max_batch_size: 1
+    engine_args:
+      enforce_eager: true
+      max_num_batched_tokens: 8192

-connectors:
-  connector_of_shared_memory:
-    name: SharedMemoryConnector
-    extra:
-      codec_streaming: true
-      codec_chunk_frames: 25
-      codec_left_context_frames: 25
+runtime:
+  connectors:
+    connector_of_shared_memory:
+      name: SharedMemoryConnector
+      extra:
+        codec_streaming: true
+        codec_chunk_frames: 25
+        codec_left_context_frames: 25
 ```

-The async Talker-to-Code2Wav processor is defined by the registered Qwen3-TTS
-pipeline rather than the deploy YAML.
-
 #### Reproduce Qwen3-TTS benchmarks

 ```bash
@@ -66,7 +66,7 @@ from vllm_omni.entrypoints.omni import Omni
 if __name__ == "__main__":
    omni = Omni(
        model="Tongyi-MAI/Z-Image-Turbo",
-        # deploy_config="./deploy-config.yaml",  # Optional deploy override
+        # stage_configs_path="./stage-config.yaml",  # See below
    )
    prompts = [
        "a cup of coffee on a table",
@@ -39,7 +39,6 @@ th {
 | `WanImageToVideoPipeline` | Wan2.2-I2V | `Wan-AI/Wan2.2-I2V-A14B-Diffusers` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
 | `LingBotWorldCausalDMDPipeline` | LingBot-World 2.0 v1 (experimental) | `robbyant/lingbot-world-v2-14b-causal-fast-diffusers` | Experimental | | | | — |
 | `Cosmos3OmniDiffusersPipeline` | Cosmos3 T2I, T2V, I2V, V2V, T2V with sound, action policy | `nvidia/Cosmos3-Nano`, `nvidia/Cosmos3-Super` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
-| `SanaWmPipeline` | SANA-WM | `BBBBruce/SANA-WM_bidirectional-stage1-diffusers` | ✅︎ | | | | [Repository](https://github.com/vllm-project/vllm-omni/blob/main/recipes/NVIDIA/SANA-WM.md) |
 | `Wan22S2VPipeline` | Wan2.2-S2V | `Wan-AI/Wan2.2-S2V-14B` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
 | `Wan22VACEPipeline` | Wan2.1-VACE | `Wan-AI/Wan2.1-VACE-1.3B-diffusers`, `Wan-AI/Wan2.1-VACE-14B-diffusers` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
 | `Wan22VACEPipeline` | Wan2.2-VACE | `Pyros13/Wan2.2-VACE-Fun-A14B-Diffusers` | ✅︎ |   |   |   | — |
@@ -68,12 +67,17 @@ th {
 | `OmniVoiceModel` | OmniVoice | `k2-fsa/OmniVoice` | ✅︎ | | | | — |
 | `VoxCPM2TalkerForConditionalGeneration` | VoxCPM2 | `openbmb/VoxCPM2` | ✅︎ | | | | — |
 | `DotsTTSForConditionalGeneration` | dots.tts | `rednote-hilab/dots.tts-soar` | ✅︎ | | | | — |
+| `MammothModa2ForConditionalGeneration` | MammothModa2-Preview | `bytedance-research/MammothModa2-Preview` | ✅︎ | ✅︎ | | | — |
+| `MammothModa2ForConditionalGeneration` | MammothModa2-Dev (AR-only image understanding) | `bytedance-research/MammothModa2-Dev` | ✅︎ | | | | — |
 | `Flux2KleinPipeline` | FLUX.2-klein | `black-forest-labs/FLUX.2-klein-4B`, `black-forest-labs/FLUX.2-klein-9B` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
 | `FluxKontextPipeline` | FLUX.1-Kontext-dev | `black-forest-labs/FLUX.1-Kontext-dev` | ✅︎ | ✅︎ | | | — |
 | `FluxPipeline` | FLUX.1-dev | `black-forest-labs/FLUX.1-dev` | ✅︎ | ✅︎ | | ✅︎ | — |
 | `FluxPipeline` | FLUX.1-schnell | `black-forest-labs/FLUX.1-schnell` | ✅︎ | ✅︎ | | ✅︎ | — |
 | `OmniGen2Pipeline` | OmniGen2 | `OmniGen2/OmniGen2` | ✅︎ | ✅︎ | | ✅︎ | — |
 | `StableAudioPipeline` | Stable-Audio-Open | `stabilityai/stable-audio-open-1.0` | ✅︎ | ✅︎ | | ✅︎ | — |
+| `SoulXSingerPipeline` | SoulX-Singer (SVS) | `Soul-AILab/SoulX-Singer` | ✅︎ | | | | — |
+| `SoulXSingerSVCPipeline` | SoulX-Singer-SVC | `Soul-AILab/SoulX-Singer` (`model-svc.pt`) | ✅︎ | | | | — |
+| `AudioXPipeline` | AudioX | `zhangj1an/AudioX` | ✅︎ | ✅︎ | | | — |
 | `MiniMaxMusic3ForConditionalGeneration` | MiniMax Music 3 (text-to-music) | `MiniMaxAI/MiniMax-Music3` | ✅︎ | | | | — |
 | `Qwen3TTSForConditionalGeneration` | Qwen3-TTS-12Hz-1.7B-CustomVoice | `Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice` | ✅︎ | | | | [Published](https://recipes.vllm.ai/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice) |
 | `Qwen3TTSForConditionalGeneration` | Qwen3-TTS-12Hz-1.7B-VoiceDesign | `Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
@@ -104,7 +108,6 @@ th {
 | `ErnieImagePipeline` | ERNIE-Image | `baidu/ERNIE-Image`, `baidu/ERNIE-Image-Turbo` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
 | `GepardTalkerForConditionalGeneration` | Gepard-1.0 | `nineninesix/gepard-1.0` | ✅︎ | | | | — |
 |`HiDreamImagePipeline` | HiDream-I1-Full | `HiDream-ai/HiDream-I1-Full` | ✅︎ | ✅︎ | | | — |
-| `HiDreamO1ImagePipeline` | HiDream-O1-Image | `HiDream-ai/HiDream-O1-Image` | ✅︎ | | | | — |

 The `Recipe` column links the corresponding deployment recipe. `Published` is
 preferred when a corresponding `recipes.vllm.ai` page exists; otherwise the
@@ -123,14 +123,7 @@ When `stream=false` or omitted, the endpoint returns the standard image edit res
    }
  ],
  "output_format": null,
-  "size": null,
-  "metrics": {
-    "stage_durations": {
-      "queue_wait_ms": 1.0,
-      "stage_0_gen_ms": 2.0
-    },
-    "peak_memory_mb": 1024.0
-  }
+  "size": null
 }
 ```

@@ -688,7 +688,7 @@ for result in response.json()["results"]:
 |-----------|--------|---------|-------------|
 | `tts_batch_max_items` | engine kwarg | 32 | Maximum number of items per batch request |

-All items are fanned out to `generate()` concurrently. The engine's stage worker automatically batches them up to the configured `max_num_seqs` and queues the rest — no client-side throttling needed.
+All items are fanned out to `generate()` concurrently. The engine's stage worker automatically batches them up to the configured `max_batch_size` and queues the rest — no client-side throttling needed.

 For best throughput, set both stages' `max_num_seqs` above 1 via `--stage-overrides`. On the current Qwen3-TTS CustomVoice benchmark, stage 1 performed best at `max_num_seqs: 10`:

@@ -10,7 +10,7 @@ Each server instance runs a single model specified at startup with `vllm serve <

 ```bash
 vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct \
-    --deploy-config vllm_omni/deploy/qwen3_omni_moe.yaml \
+    --deploy-config vllm_omni/deploy/qwen3_omni.yaml \
    --omni \
    --port 8000 \
    --trust-remote-code
@@ -161,21 +161,11 @@ are not implemented yet. Models may expose additional V2V controls through
 `extra_params`. For example, Cosmos3 supports
 `condition_frame_indexes_vision` and `condition_video_keep` to select which
 decoded reference frames are used as clean conditioning. Cosmos3 transfer mode
-also accepts `edge`, `blur`, `depth`, `seg`, or `wsm` control hints. Each hint
-may specify its own `control_path` and `control_weight`. Request-level transfer
-options include
-`control_guidance`, `control_guidance_interval`,
-`emphasize_control_in_prompt`, `num_video_frames_per_chunk`,
-`num_conditional_frames`, `show_control_condition`, and `show_input`. Transfer
-uses its transfer-specific system prompt and, by default, appends a
-control-adherence directive to the positive prompt. It adds duration/FPS and
-resolution metadata to both CFG branches but does not add a negative prompt
-automatically. The Cosmos3 recipe includes an optional reference negative
-prompt and shows how to pass it. Set `emphasize_control_in_prompt`,
-`use_duration_template`, or `use_resolution_template` to `false` to disable the
-corresponding addition. `negative_metadata_mode` accepts `same`, `inverse`, or
-`none` and defaults to `same` for transfer. See the Cosmos3 recipe for complete
-examples.
+also accepts `edge`, `blur`, `depth`, `seg`, or `wsm` control hints plus
+transfer options such as `control_path`, `control_guidance`,
+`control_guidance_interval`, `num_video_frames_per_chunk`,
+`num_conditional_frames`, `show_control_condition`, and `show_input`; see the
+Cosmos3 recipe for complete examples.

 HTTP redirects for `image_reference.image_url` follow vLLM's
 `VLLM_MEDIA_URL_ALLOW_REDIRECTS` setting. Before starting the server, set it to
@@ -20,7 +20,6 @@ For the internal selector, registry, and platform contract, see
 | Install and use SageAttention 2.2 or SageAttention3 | [SageAttention](attention_backends/sage.md) |
 | Match training or rollout kernels loaded from Hugging Face | [Hugging Face Hub Backends](attention_backends/huggingface_hub.md) |
 | Use block-sparse video attention on Ascend NPU | [RainFusion](attention_backends/rainfusion.md) |
-| Use FastVideo VSA with FastWan2.2-TI2V-5B on CUDA | [FastVideo VSA](attention_backends/fastvideo_vsa.md) |

 ## Backend options

@@ -36,7 +35,6 @@ For the internal selector, registry, and platform contract, see
 | `FLASH_ATTN_HUB` | Hub kernel | FlashAttention 2 from Hugging Face `kernels` | [Hugging Face Hub Backends](attention_backends/huggingface_hub.md) |
 | `FLASH_ATTN_3_HUB` | Hub kernel | FlashAttention 3 from Hugging Face `kernels` on Hopper or newer | [Hugging Face Hub Backends](attention_backends/huggingface_hub.md) |
 | `RAINFUSION_ATTN` | Block sparse | MindIE-SD RainFusion video attention on Ascend NPU | [RainFusion](attention_backends/rainfusion.md) |
-| `FASTVIDEO_VSA` | Block sparse | FastVideo variable sparse self-attention for FastWan2.2-TI2V-5B on CUDA | [FastVideo VSA](attention_backends/fastvideo_vsa.md) |

 ## Configuration

@@ -107,7 +105,6 @@ Backend-specific typed blocks are documented with their consumers:
  and [TRTLLM SAGE](attention_backends/trtllm.md#sage-quantization).
 - `skip_softmax`: [TRTLLM Skip-Softmax](attention_backends/trtllm.md#skip-softmax).
 - `block_sparse`: [RainFusion](attention_backends/rainfusion.md#configuration).
- `fastvideo_vsa_topk`: [FastVideo VSA](attention_backends/fastvideo_vsa.md#choose-top-k).

 ## Platform defaults

@@ -1,125 +0,0 @@
-# FastVideo VSA
-
-FastVideo Variable Sparse Attention (VSA) accelerates the `FastVideo/FastWan2.2-TI2V-5B-Diffusers` model's
-self-attention by partitioning the post-patch latent grid into spatiotemporal
-blocks. For every query block, VSA scores the key/value blocks and computes
-attention only against the selected top-k blocks.
-
-The supported checkpoint provides both text-to-video and image-to-video modes through `Wan22Pipeline`; the separate Wan I2V-14B, S2V, and VACE pipelines are outside this backend's supported scope.
-
-VSA is a CUDA-only, explicitly selected backend. It requires the
-`fastvideo-kernel` package and currently supports non-causal self-attention
-with equal query and key/value sequence lengths. Unsupported shapes, masks,
-dtypes, sequence-parallel execution, or kernel failures fall back to
-`TORCH_SDPA` and emit a warning with the reason.
-
-## Enable the backend
-
-For online serving, select the backend with the existing attention backend
-flag. Use `--fastvideo-vsa-topk` to set the number of key/value blocks retained
-for every query block:
-
-```bash
-vllm-omni serve <model> \
-  --diffusion-attention-backend FASTVIDEO_VSA \
-  --fastvideo-vsa-topk 64
-```
-
-The backwards-compatible environment variable selects the backend with the
-default `topk=64`:
-
-```bash
-export DIFFUSION_ATTENTION_BACKEND=FASTVIDEO_VSA
-vllm-omni serve <model>
-```
-
-To tune top-k, pass the CLI backend and top-k flags together as shown above,
-or use the equivalent structured configuration:
-
-```bash
-vllm-omni serve <model> \
-  --diffusion-attention-config \
-  '{"default":{"backend":"FASTVIDEO_VSA","fastvideo_vsa_topk":64}}'
-```
-
-Do not combine `--diffusion-attention-backend` with an explicit
-`diffusion_attention_config.default.backend`. The top-k value must be positive
-and is valid only when the default backend is `FASTVIDEO_VSA`.
-
-For a deploy YAML stage, use either the shorthand fields:
-
-```yaml
-stages:
-  - stage_id: 0
-    diffusion_attention_backend: FASTVIDEO_VSA
-    fastvideo_vsa_topk: 64
-```
-
-or the structured configuration:
-
-```yaml
-stages:
-  - stage_id: 0
-    diffusion_attention_config:
-      default:
-        backend: FASTVIDEO_VSA
-        fastvideo_vsa_topk: 64
-```
-
-## Choose top-k
-
-At runtime the backend logs the sequence shape and derived block count:
-
-```text
-FASTVIDEO_VSA routing: seq_len=27280, dit_seq_shape=(31, 22, 40),
-block_size=(4, 8, 8), num_blocks=120, topk=64, keep_ratio=53.3%,
-checkpoint_mode=native, route=VSA
-```
-
-Use `num_blocks` as the upper bound when tuning top-k. Top-k is the number of
-key/value blocks retained for each query block, not the number of tokens or
-the total number of blocks processed by the layer.
-
- A smaller top-k increases sparsity and may reduce attention computation, but
-  it can remove relevant blocks and reduce visual quality or temporal
-  consistency. Routing and padding overhead can also make a smaller value
-  slower for some shapes.
- A larger top-k retains more context and generally approaches dense-attention
-  quality, but reduces the potential speedup and increases memory traffic.
- `topk > num_blocks` is invalid for the runtime shape and falls back to SDPA.
- For a native checkpoint, `topk == num_blocks` routes to SDPA because scoring
-  every block provides no sparsity benefit.
- For a FastVideo DMD checkpoint, `topk == num_blocks` stays on the VSA
-  all-block path so the checkpoint keeps its trained compensation semantics.
-
-There is no universally optimal value. Resolution, frame count, GPU, kernel
-version, and checkpoint all affect both quality and latency. Start from the
-logged `num_blocks`, test several keep ratios on the target workload, and
-compare output quality against the same checkpoint running dense attention.
-
-## Checkpoint behavior
-
-The backend does not expose a user-selectable gate mode. Wan checkpoints that
-contain learned `to_gate_compress` weights use that projection automatically.
-When those weights are absent, the unused projection is removed and VSA uses
-the sparse branch without learned compensation.
-
-FastVideo DMD checkpoints use their fixed distilled timestep schedule. Native
-Wan checkpoints keep their normal scheduler and inference-step configuration;
-selecting VSA does not turn a native checkpoint into a distilled model.
-
-## Verify routing and fallback
-
-Check the startup and first-forward logs instead of assuming that selecting
-the backend guarantees sparse execution:
-
- `route=VSA` means top-k block selection is active.
- `route=VSA_ALL_BLOCKS` means the FastVideo DMD checkpoint retained all
-  blocks through the VSA kernel.
- `route=SDPA` or `FASTVIDEO_VSA falling back to SDPA: ...` means dense SDPA
-  executed; the warning includes the reason.
-
-The current kernel requires CUDA tensors in FP16 or BF16, 256-token blocks,
-standard `head_size**-0.5` scaling, equal Q/K/V head counts, no attention mask,
-and no active sequence-parallel context. NPU and XPU paths do not execute the
-FastVideo VSA CUDA kernel.
@@ -49,6 +49,7 @@ higher-priority strategy is selected.
 | StableDiffusion3Pipeline | `stabilityai/stable-diffusion-3.5-medium` | `SD3Transformer2DModel` | — | yes | — | `transformer_blocks` |
 | Wan22I2VPipeline | `Wan-AI/Wan2.2-I2V-A14B-Diffusers` | `WanTransformer3DModel` | yes | yes | — | `blocks` |
 | Wan22Pipeline | `Wan-AI/Wan2.2-T2V-A14B-Diffusers` | `WanTransformer3DModel` | yes | yes | — | `blocks` |
+| SoulXSingerPipeline / SoulXSingerSVCPipeline | `Soul-AILab/SoulX-Singer` | `DiffLlama` | yes | yes | — | `layers` |
 | BagelPipeline | `ByteDance-Seed/BAGEL-7B-MoT` | `Qwen2MoTModel` | — | yes | — | `layers`, customized modules |
 | Cosmos3OmniDiffusersPipeline | `nvidia/Cosmos3-Nano`, `nvidia/Cosmos3-Super` | `Cosmos3VFMTransformer`, `Cosmos3LanguageModel` | yes | yes | yes | `layers`, `gen_layers` |

@@ -207,16 +207,18 @@ outputs = omni.generate(
 )
 ```

-## Deploy Configuration
+## Stage Configuration

 Use the equivalent engine arguments in a deployment YAML:

 ```yaml
-stages:
+stage_args:
  - stage_id: 0
-    step_execution: false
-    max_num_seqs: 4
-    request_batch_max_wait_ms: 20
+    stage_type: diffusion
+    engine_args:
+      step_execution: false
+      max_num_seqs: 4
+      request_batch_max_wait_ms: 20
 ```

 For step execution, set `step_execution: true` and remove
@@ -1,156 +1,127 @@
 # Distributed Layerwise Offloading

-Distributed layerwise offloading (DLO) extends block streaming to multi-device
-deployments. With AllGather enabled, each rank stores roughly `1 / dp_size` of
-the host weights and reconstructs each layer at runtime. Without AllGather,
-each rank streams a complete block independently. Compatible TP1 deployments
-can share checkpoint-backed host pages among processes on the same node;
-otherwise DLO streams the ordinary loader's rank-local tensors.
+Distributed layerwise offloading (DLO) streams DiT blocks through two device
+buffers instead of keeping the complete DiT in HBM. It supports sharded host
+weights with AllGather or independently streamed rank-local weights. The
+no-AllGather path can optionally share node-local host weights through mmap.

-See the [DLO feature design](../../../design/feature/offloader/distributed_layerwise_offload.md)
-for the implementation contract and compatibility matrix.
+See the [shared DLO component architecture](../../../design/feature/offloader/distributed_layerwise_offload.md#architecture)
+for ownership and lifecycle coordination. The mode-specific internals are
+documented separately in the
+[AllGather design](../../../design/feature/offloader/distributed_layerwise_offload.md#allgather-design)
+and
+[no-AllGather design](../../../design/feature/offloader/distributed_layerwise_offload.md#no-allgather-design).

-## Execution model
+## Choose a mode

-DLO overlaps three operations with a fixed two-block device buffer:
+| Mode | Use when | Host weights | Runtime synchronization |
+| --- | --- | --- | --- |
+| DLO AllGather (default) | DP ranks execute the same block path in lockstep | About `1 / dp_size` per rank | DLO weight AllGather |
+| no-AllGather | Ranks or engines must schedule independently | Complete rank-local layout | No DLO weight collective |
+| no-AllGather + host weight cache | Equivalent independent workers share one node | Shared final mmap layout per TP coordinate | No DLO weight collective |
+| host weight cache + host registration | The platform supports registration and recurrent staging is too expensive | Shared registered mmap layout | No DLO weight collective |

-```text
-Compute stream:  [Layer N]          [Layer N+1]        [Layer N+2]
-H2D stream:      [H2D shard N+1]    [H2D shard N+2]
-AllGather:       [AG N+1]           [AG N+2]
-Slots:           slot 0: Layer N    slot 1: Layer N+1
-```
-
-AllGather communicates only request-independent weight shards, so data-
-parallel ranks may process different requests concurrently.
+AllGather is normally the best choice for synchronized DP. Host weight cache mode
+targets independently scheduled replicas, especially repeated TP engines on
+one node.

 ## Usage

 ```bash
-# Four ranks with sharded host weights and AllGather
+# Sharded host weights with DLO AllGather
 vllm serve /path/to/model --omni \
  --enable-distributed-layerwise-offload \
  --data-parallel-size 4

-# Standard-loader rank-local weights, without DLO AllGather
+# Independently streamed rank-local weights
 vllm serve /path/to/model --omni \
  --enable-distributed-layerwise-offload \
-  --data-parallel-size 4 \
  --dlo-no-use-allgather

-# Sequence parallel deployment
+# Share final host weights; prefer registered direct H2D under the pinned-memory policy
 vllm serve /path/to/model --omni \
  --enable-distributed-layerwise-offload \
-  --usp 4
+  --dlo-no-use-allgather \
+  --dlo-use-host-weight-cache
+
+# Apply an 80 GiB per-worker safety ceiling to the same registration attempt
+vllm serve /path/to/model --omni \
+  --enable-distributed-layerwise-offload \
+  --tensor-parallel-size 2 \
+  --dlo-no-use-allgather \
+  --dlo-use-host-weight-cache \
+  --dlo-host-weight-cache-pin-limit-gib 80
 ```

-```python
-from vllm_omni import Omni
-
-omni = Omni(
-    model="/path/to/model",
-    enable_distributed_layerwise_offload=True,
-    dlo_use_allgather=True,
-)
-```
-
-## Flags
+## Relevant options

 | Flag | Meaning | Default |
 | --- | --- | --- |
 | `--enable-distributed-layerwise-offload` | Enable DLO | `false` |
-| `--data-parallel-size N` | DP ranks and AllGather weight-sharding group | `1` |
-| `--dlo-use-allgather` | Shard host weights and reconstruct with AllGather | `true` |
-| `--dlo-no-use-allgather` | Stream complete rank-local blocks without a DLO weight collective | `false` |
-| `--dlo-resident-layers N` | Keep N leading main-DiT blocks on device; requires no-AllGather and model-declared resident paths | `0` |
+| `--dlo-no-use-allgather` | Stream complete rank-local blocks independently | `false` |
+| `--dlo-use-host-weight-cache` | Use the final-layout cache and prefer registration when pinned memory is enabled | `false` |
+| `--dlo-host-weight-cache-pin-limit-gib GIB` | Optional per-worker registration ceiling; zero means no additional ceiling | `0` |
+| `--dlo-resident-layers N` | Keep eligible leading DiT blocks resident in HBM | `0` |

-## Host-weight loading
+No-AllGather DLO automatically uses a compatible checkpoint mmap plan. When
+checkpoint mmap is unavailable, it preserves ordinary pinned loader weights by
+default. `--dlo-use-host-weight-cache` explicitly selects the transform-complete
+final-layout cache. Under the default `pin_cpu_memory=True` policy, DLO attempts
+to register the complete immutable mapping for direct H2D. Setting
+`pin_cpu_memory=False` through structured or programmatic configuration retains
+the staged mmap path instead. A positive pin limit is only an optional safety
+ceiling and does not select the cache. The cache uses
+`~/.cache/vllm-omni/dlo-host-weights`. Programmatic configuration may override
+`dlo_host_weight_cache_dir` and the writer lock timeout; these advanced storage
+controls are intentionally not separate CLI flags.

-The diffusion loader chooses host storage before DLO is enabled. It first
-attempts to build a complete, validated direct-checkpoint mmap plan. If names,
-coverage, shape, dtype, topology, or loader-callback compatibility cannot be
-proven, it runs the ordinary model loader instead. DLO consumes that result and
-does not make a second checkpoint-compatibility decision.
+## Operational notes

-The shared-mmap optimization in this phase is supported only with TP1. TP
-greater than one falls back before model mutation to ordinary TP-aware loading.
-DLO may still consume those TP-local tensors, but this is a compatibility path:
-it does not share checkpoint-backed runtime weights across DP replicas and
-provides no shared-mmap host-memory guarantee.
+- All workers that should share must see the same local, disk-backed cache
+  directory. Do not use tmpfs or a cross-node filesystem for this version.
+- Cache entries are immutable and validated before use. A cache or registration
+  failure keeps the ordinary loader weights or falls back to bounded staging.
+- The bounded-staging fallback is a memory-first mode: recurrent pageable-mmap to
+  pinned-slot copies can reduce throughput, especially across concurrent TP
+  engines. Use it intentionally by disabling pinned host memory, or when the
+  active platform cannot register the immutable mapping.
+- When a positive registration ceiling is configured, it must cover the
+  complete page-aligned mapping reported in the worker log. Registration is
+  all-or-nothing. Zero applies no additional ceiling.
+- CUDA is the first registration backend and requires read-only host
+  registration support for immutable cache mappings. Platforms or devices
+  without that capability continue to use bounded staging; pinned-memory policy
+  requests direct H2D but does not guarantee it.
+- Registration is process-local but does not duplicate the underlying file
+  pages. Each worker must still satisfy its platform and OS page-locking limits.
+- Shutdown unregisters host ranges before closing their mmap handles.
+- Host weight cache v1 has no automatic eviction. Stop all users of an entry
+  before deleting it.

-The mmap plan skips only dedicated DiT weight sources. Other component sources,
-such as a text encoder loaded through the shared diffusion loader, continue to
-use their ordinary component loader. A checkpoint source that mixes DiT and
-non-DiT weights falls back completely rather than leaving an unplanned
-component uninitialized.
+## Scheduling constraints

-With direct checkpoint mmap, the loader:
+AllGather ranks must request blocks in the same collective order. Concurrent DP
+requests may use different prompts, but they must follow the same denoising and
+block-execution path and set the same explicit `num_inference_steps`.

-1. saves non-persistent buffers such as RoPE frequencies;
-2. moves the normally created transformer to the meta device;
-3. loads checkpoint tensors as mmap views backed by the shared OS page cache;
-4. applies any loader-owned bounded layout adapters while packing blocks;
-5. restores saved non-persistent buffers; and
-6. preserves `post_load_weights()` and `validate_loaded_weights()` lifecycle
-   hooks.
-
-For AllGather with a group larger than one, each process copies only its
-persistent shard and then releases the source mapping. For no-AllGather, each
-process keeps the mapping open and packs complete blocks through two bounded
-pinned staging slots. Processes mapping the same files on one node share the
-immutable pages; no-AllGather still performs a complete-block H2D copy in each
-process.
-
-When the effective DLO group size is one, `dlo_use_allgather=True` does not
-perform a collective and uses the same rank-local transfer behavior.
-
-## Declarative topology
-
-Models may declare an `OffloadPlan` instead of embedding offload logic:
-
-```python
-from vllm_omni.diffusion.offloader import OffloadPlan
-
-
-class MyPipeline(nn.Module):
-    _dit_modules = ["transformer"]
-    _offload_plan = OffloadPlan(
-        block_attrs={"transformer": ("blocks",)},
-        offload_submodules={"context_encoder": "layers"},
-    )
-```
-
-When no plan exists, discovery falls back to
-`_layerwise_offload_blocks_attrs` and then heuristic attribute lookup.
-
-## Data-parallel concurrency
-
-With `data_parallel_size > 1` and AllGather enabled, the scheduler can process
-up to `dp_size` requests per denoising step. Every concurrent request must set
-the same explicit `num_inference_steps`; `None` is rejected because every rank
-must enter each collective.
+No-AllGather workers do not have this DLO lockstep requirement. Ordinary TP or
+SP model collectives still synchronize ranks within each engine.

 ## Limitations

- Direct checkpoint mmap currently requires TP1. TP greater than one is
-  outside the Phase A shared-mmap support scope and falls back before model
-  mutation to the ordinary TP-aware loader. DLO can stream that runtime layout,
-  but it provides no shared-mmap host-memory benefit or guarantee.
- HSDP plus AllGather is rejected to avoid double sharding. HSDP without
-  AllGather has limited end-to-end validation.
+- Direct checkpoint mmap currently requires TP1. The host weight cache can share
+  final ordinary-loader layouts between matching TP coordinates at TP1 or TP>1.
 - Per-tensor online FP8 linears use the ordinary loader and can run with either
-  DLO transfer path. With AllGather, every rank temporarily materializes the
-  complete FP8 model in host memory before DLO retains only its shard. Other
-  online quantization methods require no-AllGather until their runtime layouts
-  are validated.
- Resident leading layers require `--dlo-no-use-allgather` and a model
-  `OffloadPlan` that declares eligible `resident_dit_paths`.
- DP concurrency requires an explicit, identical inference-step count.
-
-Sharing transformed TP or quantized runtime layouts through a normalized mmap
-cache is a follow-up design in
-[RFC #6195](https://github.com/vllm-project/vllm-omni/issues/6195), not part of
-the direct-checkpoint path.
+  DLO transfer path. Other online quantization methods require no-AllGather
+  until their runtime layouts are validated.
+- Host weight cache v1 rejects quantized, non-contiguous, aliased/tied,
+  device-only, HSDP, expert-parallel, CFG-parallel, and PP layouts.
+- HSDP plus DLO AllGather is unsupported, and host weight cache v1 rejects HSDP.
+- The host weight cache changes steady-state host backing, not startup loading:
+  each worker still performs ordinary loading and full content validation.
+- Skip-load-on-hit, cache eviction, and cross-node sharing remain follow-up
+  work in
+  [RFC #6195](https://github.com/vllm-project/vllm-omni/issues/6195).

 See the [Cosmos3 DistOffload recipe](https://github.com/vllm-project/vllm-omni/blob/main/recipes/cosmos3/Cosmos3-DistOffload.md)
 for an end-to-end example.
@@ -152,8 +152,7 @@ In `DiffusionParallelConfig`:
 **Constraints:**

 - `hsdp_replicate_size × hsdp_shard_size == world_size`
- HSDP cannot be used with Tensor Parallelism, ordinary Data Parallelism,
-  Pipeline Parallelism, or Expert Parallelism.
+- HSDP cannot be used with Tensor Parallelism (`tensor_parallel_size` must be 1)

 ---

@@ -24,7 +24,7 @@ stages:

 For an experimental whole-transformer compile scope, set
 `--diffusion-compile-granularity full` or use
-`diffusion_compile_granularity: full` in the deploy configuration. Full scope may
+`diffusion_compile_granularity: full` in the stage configuration. Full scope may
 still contain graph breaks; it does not force one graph. It is rejected when
 HSDP, sequence parallelism, CPU offload, or layerwise offload is enabled. Use
 regional scope with those features.
@@ -124,12 +124,12 @@ The following tables show which models support each feature:
 | **FLUX.2-dev**           |     ✅     |     ✅      |           ✅           |       ✅        |         ✅         |          ❌          |   ✅    |             ✅             |          ✅           |       ❌        |        ❌         |
 | **GLM-Image**            |     ❌     |     ❌      |           ❌           |       ✅        |         ✅         |          ❌          |   ✅    |             ❌             |          ❌           |       ❌        |        ❌         |
 | **Hidream-I1-Full**        |     ❌     |     ❌      |           ❌           |       ❌        |         ✅         |          ❌          |   ❌    |             ❌             |          ❌           |       ❌        |        ❌         |
-| **HiDream-O1-Image**     |     ❌     |     ✅      |           ❌           |       ❌        |         ✅         |          ❌          |   ❌    |             ❌             |          ❌           |       ❌        |        ❌         |
 | **HunyuanImage3**        |     ❌     |     ✅      |           ❌           |       ❌        |         ✅         |          ❌          |   ❌    |             ❌             |          ❌           |       ✅        |        ✅*        |
 | **Krea 2**               |     ❌     |     ✅      |           ❌           |       ❌        |         ❌         |          ❌          |   ✅    |             ✅             |      ✅ (decode)      |       ❌        |        ❌         |
 | **LongCat-Image**        |     ✅     |     ✅      |           ✅           |       ✅        |         ✅         |          ❌          |   ❌    |             ✅             |          ❌           |       ❌        |        ❌         |
 | **LongCat-Image-Edit**   |     ✅     |     ✅      |           ✅           |       ✅        |         ✅         |          ❌          |   ❌    |             ✅             |          ❌           |       ❌        |        ❌         |
 | **MagiHuman**            |     ❌     |     ❌      |           ❌           |       ❓        |         ✅         |          ❌          |   ❌    |             ✅             |          ❌           |       ❌        |        ❌         |
+| **MammothModa2(T2I)**    |     ❌     |     ❌      |           ❌           |       ❌        |         ❌         |          ❌          |   ❌    |             ❌             |          ❌           |       ❌        |        ❌         |
 | **Nextstep_1(T2I)**      |     ❓     |     ❓      |           ❌           |       ✅        |         ✅         |          ❌          |   ❌    |             ✅             |          ❌           |       ❌        |        ❌         |
 | **OmniGen2**             |     ❌     |     ✅      |           ✅           |       ❌        |         ✅         |          ❌          |   ❌    |             ❌             |          ❌           |       ❌        |        ❌         |
 | **Ovis-Image**           |     ❌     |     ✅      |           ❌           |       ✅        |         ❌         |          ❌          |   ❌    |             ✅             |          ❌           |       ❌        |        ❌         |
@@ -168,14 +168,6 @@ The following tables show which models support each feature:
 | **Cosmos3**                  |     ❌     |     ✅      |           ✅           |       ✅        |         ✅         |         ❌         |   ✅    |             ✅             |  ✅ (encode/decode)   |       ✅        |        ❌         |
 | **LongCat-Video-Avatar-1.5** |     ❌     |     ❌      |           ❌           |       ❌        |         ❌         |         ❌         |   ❌    |             ❌             |          ❌           |       ❌        |        ❌         |
 | **MiniMax-H3**               | ✅ (FL2VA) |     ✅      |           ✅           |       ❌        |       ✅ (DiT/TE)  |         ❌         |   ✅    |             ✅             |       ✅ (tile)       |      ✅ (DiT)      |        ❌         |
-| **SANA-WM**                  |     ❌     |     ❌      |          ❌<sup>5</sup> |       ✅        |         ✅         |         ❌         |   ❌    |             ❌             |          ❌           |       ❌        |        ❌         |
-
-> Notes:
-> 5. SANA-WM cannot support sequence parallelism: its bidirectional gated delta
->    recurrence carries state across frames, so a rank cannot denoise a slice of
->    the token sequence in isolation. Doing so would need a distributed scan or
->    an all-gather before every GDN block. The remaining ❌ columns are simply
->    unvalidated on this model, not known-broken.

 > **Step execution note:** Helios supports single-request step execution only;
 > use `max_num_seqs=1`.
@@ -183,7 +175,7 @@ The following tables show which models support each feature:
 **Frame Interpolation Support**

 - **Supported**: Wan2.2 text-to-video, image-to-video, and TI2V pipelines
- **Not supported**: Wan2.1-VACE, LTX-2, LTX-2.3, LTX-2.5, Helios, HunyuanVideo-1.5, DreamID-Omni, SANA-WM
+- **Not supported**: Wan2.1-VACE, LTX-2, LTX-2.3, LTX-2.5, Helios, HunyuanVideo-1.5, DreamID-Omni

 ### AudioGen

@@ -22,7 +22,7 @@ MiMo-Audio provides multiple task variants for audio understanding and generatio

 ## Setup

-See the [pipeline and deploy configuration documentation](https://docs.vllm.ai/projects/vllm-omni/en/latest/configuration/stage_configs/) to configure memory allocation for your hardware.
+Please refer to the [stage configuration documentation](https://docs.vllm.ai/projects/vllm-omni/en/latest/configuration/stage_configs/) to configure memory allocation appropriately for your hardware setup.

 ### Environment Variables

@@ -188,7 +188,7 @@ Note: This task uses hardcoded message lists in the script.

 ### Other

- If the model or deploy config fails to load, check the [pipeline and deploy configuration documentation](https://docs.vllm.ai/projects/vllm-omni/en/latest/configuration/stage_configs/) for memory and GPU settings.
+- If the model or stage config fails to load, check [stage configuration documentation](https://docs.vllm.ai/projects/vllm-omni/en/latest/configuration/stage_configs/) for memory and GPU settings.
 - For errors when reading/writing WAV (e.g. unsupported format), ensure input files are standard WAV/MP3 and that `soundfile` is linked to a working libsndfile (see above).

 ## Notes
@@ -4,7 +4,7 @@ Source <https://github.com/vllm-project/vllm-omni/tree/main/examples/offline_inf


 ## Setup
-See the [pipeline and deploy configuration documentation](https://docs.vllm.ai/projects/vllm-omni/en/latest/configuration/stage_configs/) to configure memory allocation for your hardware.
+Please refer to the [stage configuration documentation](https://docs.vllm.ai/projects/vllm-omni/en/latest/configuration/stage_configs/) to configure memory allocation appropriately for your hardware setup.

 ## Run examples

@@ -4,8 +4,7 @@ Source <https://github.com/vllm-project/vllm-omni/tree/main/examples/offline_inf


 ## Setup
-Use `--deploy-config` for deployment overrides such as stage memory allocation.
-See the [pipeline and deploy configuration documentation](https://docs.vllm.ai/projects/vllm-omni/en/latest/configuration/stage_configs/).
+Please refer to the [stage configuration documentation](https://docs.vllm.ai/projects/vllm-omni/en/latest/configuration/stage_configs/) to configure memory allocation appropriately for your hardware setup.

 ## Run examples

@@ -74,8 +73,8 @@ For true stage-level concurrency -- where downstream stages (Talker, Code2Wav)
 start **before** the upstream stage (Thinker) finishes -- use the async_chunk
 example. This requires:

-1. A deploy YAML with ``async_chunk: true`` (for example, an overlay based on
-   ``vllm_omni/deploy/qwen3_omni_moe.yaml``).
+1. A stage config YAML with ``async_chunk: true`` (e.g.
+   ``qwen3_omni_moe_async_chunk.yaml``).
 2. Hardware that matches the config (e.g. 2x H100 for the default 3-stage
   config).

@@ -101,11 +100,11 @@ bash run_multiple_prompts_async_chunk.sh --max-in-flight 4
 python end2end_async_chunk.py --query-type text --modalities text
 ```

-#### Custom deploy config
+#### Custom stage config
 ```bash
 python end2end_async_chunk.py \
    --query-type use_audio \
-    --deploy-config /path/to/your_async_chunk.yaml
+    --stage-configs-path /path/to/your_async_chunk.yaml
 ```

 > **Note**: The synchronous ``end2end.py`` (using ``Omni``) is still the
@@ -69,7 +69,7 @@ python examples/offline_inference/text_to_speech/voxcpm2/end2end.py \

 ### Notes
 - Output: 48 kHz mono WAV.
- Deploy config: `vllm_omni/deploy/voxcpm2.yaml` (default).
+- Stage config: `vllm_omni/model_executor/stage_configs/voxcpm2.yaml` (default).

 ---

@@ -152,7 +152,7 @@ python examples/offline_inference/text_to_speech/fish_speech/end2end.py \
    --text "Hello, this is a streaming test." \
    --streaming
 ```
-Streaming requires `async_chunk: true` in the deploy config.
+Streaming requires `async_chunk: true` in the stage config.

 ### Notes
 - Output: 44.1 kHz mono WAV.
@@ -274,7 +274,7 @@ python examples/offline_inference/text_to_speech/qwen3_tts/end2end.py \
    --streaming \
    --output-dir /tmp/out_stream
 ```
-Streaming requires `async_chunk: true` in the deploy config.
+Streaming requires `async_chunk: true` in the stage config.

 ### Batched decoding
 The Code2Wav stage supports batched decoding through the SpeechTokenizer. Configure both stages with `max_num_seqs > 1` via `--stage-overrides` and pass multiple prompts via `--txt-prompts`:
@@ -271,7 +271,7 @@ The script supports the following arguments:
 vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni --port 8091
 ```

-If you have a custom deploy config file:
+If you have custom stage configs file:
 ```bash
 vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni --port 8091 --deploy-config /path/to/deploy_config_file
 ```
@@ -419,7 +419,7 @@ curl -X POST http://localhost:8091/v1/audio/speech \
        "response_format": "pcm"
    }' --no-buffer | play -t raw -r 24000 -e signed -b 16 -c 1 -
 ```
-Raw PCM streaming requires `stream_format="audio"`, `response_format="pcm"`, and `async_chunk: true` in the deploy config (default in `qwen3_tts.yaml`). `speed` is not supported when streaming.
+Raw PCM streaming requires `stream_format="audio"`, `response_format="pcm"`, and `async_chunk: true` on the stage config (default in `qwen3_tts.yaml`). `speed` is not supported when streaming.

 ### Streaming WebSocket
 The `/v1/audio/speech/stream` endpoint accepts text incrementally and synthesizes the buffered text as one continuous request on `input.done`:
@@ -92,7 +92,7 @@ warmup_quack_fp8([(14040, 2048, 6144), (14040, 2048, 2048)])
 | FLUX.1 | `black-forest-labs/FLUX.1-dev`, `black-forest-labs/FLUX.1-schnell` | Yes | Yes | All layers | None | |
 | FLUX.2-dev | `black-forest-labs/FLUX.2-dev` | Yes | Not validated | All layers | None | ✅︎ |
 | FLUX.2-klein | `black-forest-labs/FLUX.2-klein-4B` | Yes | Yes | All layers | None | |
-| HunyuanImage-3.0 | `tencent/HunyuanImage-3.0`, `tencent/HunyuanImage-3.0-Instruct` | Yes | Yes | All layers; use the Hunyuan deploy config for multi-stage runs | None | |
+| HunyuanImage-3.0 | `tencent/HunyuanImage-3.0`, `tencent/HunyuanImage-3.0-Instruct` | Yes | Yes | All layers; use the Hunyuan stage config for multi-stage runs | None | |
 | HunyuanVideo-1.5 | `hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v`, `720p_t2v`, `480p_i2v` | Yes | Yes | All layers | None | |
 | Cosmos3 | `nvidia/Cosmos3-Nano`, `nvidia/Cosmos3-Super` | Yes | Not validated | All layers | None | |
 | MiniMax-H3 | `MiniMaxAI/MiniMax-H3` (`FL2VA` / `Ref2VA`) | Yes | Not validated | `quantization="fp8"` quantizes eligible DiT and text-encoder linears; mixed-precision input/output heads stay FP32 | None | ✅︎ |
@@ -92,4 +92,4 @@ For HunyuanImage-3.0, use the Hunyuan-specific adaptation linked above.
 2. The `ascend` quantization method expects weights produced by the Ascend
   tooling; it is not a load-time CUDA quantizer.
 3. Keep the quantized checkpoint aligned with the same model architecture and
-   pipeline and deploy config used for BF16 inference.
+   stage config used for BF16 inference.
@@ -83,23 +83,23 @@ Online serving:
 vllm serve <your-model> --omni --diffusion-kv-cache-dtype fp8
 ```

-Deploy config:
+Stage config:

 ```yaml
-stages:
+stage_args:
  - stage_id: 0
-    diffusion_kv_cache_dtype: "fp8"
-    diffusion_kv_cache_skip_steps: "0,1"
-    diffusion_kv_cache_skip_layers: "0-2"
+    stage_type: diffusion
+    engine_args:
+      model_stage: dit
+      diffusion_kv_cache_dtype: "fp8"
+      diffusion_kv_cache_skip_steps: "0,1"
+      diffusion_kv_cache_skip_layers: "0-2"
 ```

-The `model_stage` and diffusion execution type belong to the registered
-`PipelineConfig`; the deploy YAML only carries runtime overrides.
-
-The legacy keyword aliases `kv_cache_dtype`, `kv_cache_skip_steps`, and
-`kv_cache_skip_layers` remain accepted when constructing
-`OmniDiffusionConfig` directly. They are not deploy YAML fields; prefer the
-`diffusion_*` names for new code.
+Legacy YAML keys `kv_cache_dtype`, `kv_cache_skip_steps`, and
+`kv_cache_skip_layers` are still accepted when constructing
+`OmniDiffusionConfig` (for example via `from_kwargs`); prefer the `diffusion_*`
+names for new configs.

 ## Parameters

@@ -17,7 +17,7 @@ Shared plumbing (corpus/WAV IO, tokenizer loading, the CFG cond/uncond
 pair contract) lives in `common.py`; each task script keeps only its own
 prompt recipe and flow. Note `text_to_audio.py` here drives the Audex
 two-stage AR pipeline — for diffusion text-to-audio models (Stable Audio
-Open) use the generic
+Open, AudioX) use the generic
 `examples/offline_inference/text_to_audio/text_to_audio.py` instead.

 ## text_to_speech.py — text → speech
@@ -7,7 +7,7 @@ thinker generates interleaved 4-codebook <audiocodec_N> RVQ tokens under an
 RVQ phase mask, and the external XCodec1 checkpoint decodes them to a 16 kHz
 mono WAV.

-(For DIFFUSION text-to-audio models — Stable Audio Open — use
+(For DIFFUSION text-to-audio models — Stable Audio Open, AudioX — use
 ``examples/offline_inference/text_to_audio/text_to_audio.py`` instead; Audex
 TTA is a two-stage autoregressive pipeline with a different interface.)

@@ -2,8 +2,7 @@

 ## Setup

-Use `--deploy-config` for deployment overrides such as stage memory allocation.
-See the [pipeline and deploy configuration documentation](https://docs.vllm.ai/projects/vllm-omni/en/latest/configuration/stage_configs/).
+Please refer to the [stage configuration documentation](https://docs.vllm.ai/projects/vllm-omni/en/latest/configuration/stage_configs/) to configure memory allocation appropriately for your hardware setup.

 > **Note**
 > Covo-Audio code2wav requires `torchdiffeq`. Install it with: `pip install torchdiffeq`
@@ -42,7 +41,7 @@ python end2end.py -m /path/to/Covo-Audio-Chat --output-dir ./my_output
 | `--sampling-rate` | | `16000` | Sampling rate for audio loading (Hz) |
 | `--output-dir` | | `./output_audio` | Output directory for generated files |
 | `--num-prompts` | | `1` | Number of prompts to generate |
-| `--deploy-config` | | (auto) | Optional path to a deploy YAML override |
+| `--stage-configs-path` | | (auto) | Path to stage configs YAML file |
 | `--log-stats` | | `false` | Enable detailed statistics logging |
 | `--stage-init-timeout` | | `300` | Stage initialization timeout (seconds) |
 | `--batch-timeout` | | `5` | Batching timeout (seconds) |
@@ -53,6 +53,7 @@ from typing import Any
 import torch
 from PIL import Image

+from vllm_omni.diffusion.data import DiffusionParallelConfig
 from vllm_omni.entrypoints.omni import Omni
 from vllm_omni.inputs.data import OmniDiffusionSamplingParams
 from vllm_omni.outputs import OmniRequestOutput
@@ -138,6 +139,12 @@ async def main():

    # ---- Torch setup ----
    generator = torch.Generator(device=current_omni_platform.device_type).manual_seed(args.seed)
+    parallel_config = DiffusionParallelConfig(
+        ulysses_degree=args.ulysses_degree,
+        ring_degree=args.ring_degree,
+        cfg_parallel_size=args.cfg_parallel_size,
+        tensor_parallel_size=args.tensor_parallel_size,
+    )

    # ---- Cache Config ----
    if args.cache_backend == "cache_dit":
@@ -164,10 +171,7 @@ async def main():
        vae_use_tiling=args.vae_use_tiling,
        cache_backend=args.cache_backend,
        cache_config=cache_config,
-        ulysses_degree=args.ulysses_degree,
-        ring_degree=args.ring_degree,
-        cfg_parallel_size=args.cfg_parallel_size,
-        tensor_parallel_size=args.tensor_parallel_size,
+        parallel_config=parallel_config,
        enforce_eager=args.enforce_eager,
        enable_cpu_offload=args.enable_cpu_offload,
        diffusion_load_format="dummy",
@@ -154,6 +154,8 @@ def _positive_finite(value: float, flag: str) -> float:
 def build_omni_kwargs(
    args: argparse.Namespace,
    paths: LingBotPaths,
+    *,
+    parallel_config: Any,
 ) -> dict[str, Any]:
    """Build Omni configuration without overriding checkpoint class discovery."""

@@ -165,7 +167,7 @@ def build_omni_kwargs(
    return {
        "model": model,
        "flow_shift": flow_shift,
-        "tensor_parallel_size": args.tensor_parallel_size,
+        "parallel_config": parallel_config,
        "enforce_eager": args.enforce_eager,
        "model_config": {"lingbot_action_root": str(paths.action_root)},
    }
@@ -260,10 +262,12 @@ def main(argv: Sequence[str] | None = None) -> Path:
    # helper tests work on machines without the native vLLM runtime.
    from diffusers.utils import export_to_video

+    from vllm_omni.diffusion.data import DiffusionParallelConfig
    from vllm_omni.entrypoints.omni import Omni
    from vllm_omni.inputs.data import OmniDiffusionSamplingParams

-    omni_kwargs = build_omni_kwargs(args, paths)
+    parallel_config = DiffusionParallelConfig(tensor_parallel_size=args.tensor_parallel_size)
+    omni_kwargs = build_omni_kwargs(args, paths, parallel_config=parallel_config)
    omni = Omni(**omni_kwargs)
    try:
        outputs = omni.generate(
Author	SHA1	Message	Date
Hongsheng Liu	58eebee14b	[Diffusion] Simplify DLO host plan setup Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-19 23:00:31 +08:00
Hongsheng Liu	6bcd350301	[Diffusion] Prefer host-cache registration when pinned Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-19 18:13:44 +08:00
Hongsheng Liu	859003fb97	[Diffusion] Gate CUDA read-only host registration Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-19 11:23:36 +08:00
Hongsheng Liu	42c6ae9007	[Diffusion] Document TP host layout identity Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-19 11:23:36 +08:00
Hongsheng Liu	16642dc2e8	[Diffusion] Make DLO host weight cache opt-in Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-19 11:23:36 +08:00
Hongsheng Liu	75af33a76f	[Diffusion] Address DLO host cache review feedback Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-19 11:23:36 +08:00
Hongsheng Liu	44d3245a6d	[Diffusion] Clear handled CUDA registration errors Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-19 11:23:36 +08:00
Hongsheng Liu	010b3c1d74	[Diffusion] Make no-AllGather host weight cache automatic Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-19 11:23:36 +08:00
Hongsheng Liu	3bb7547a0f	[Diffusion] Rename runtime cache to host weight cache Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-19 11:23:36 +08:00
Hongsheng Liu	ee665fcfc3	[Docs] Add AllGather DLO architecture diagram Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-19 11:23:16 +08:00
Hongsheng Liu	649558e1a1	[Docs] Show TP2 devices in DLO architecture Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-19 11:23:16 +08:00
Hongsheng Liu	3b9727c1e1	[Docs] Reorder no-AllGather architecture diagram Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-19 11:23:16 +08:00
Hongsheng Liu	47153d86e6	[Docs] Visualize no-AllGather shared host weights Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-19 11:23:16 +08:00
Hongsheng Liu	1ccdc2e80e	[Docs] Separate DLO transfer mode design Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-19 11:23:16 +08:00
Hongsheng Liu	8f93a74951	[Docs] Remove stale DLO validation results Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-19 11:22:52 +08:00
Hongsheng Liu	4acb3b1387	[Docs] Add DLO component architecture Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-19 11:21:59 +08:00
Hongsheng Liu	6b7b5368f2	[Diffusion] Clarify runtime cache module boundary Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-19 11:21:59 +08:00
Hongsheng Liu	6751c1f404	[Diffusion] Address runtime cache review feedback Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-19 11:21:59 +08:00
Hongsheng Liu	c1196216a3	[Diffusion] Stabilize runtime cache identities Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-19 11:21:28 +08:00
Hongsheng Liu	23ab14a15b	[Diffusion] Register runtime cache for direct DLO H2D Avoid recurrent mmap-to-pinned packing in no-AllGather DLO by registering transform-complete runtime-cache mappings under an explicit per-worker budget. Copy mapped tensors directly into the rotating device buffers while preserving bounded-staging fallback and ordered shutdown cleanup. Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-19 11:21:28 +08:00
Hongsheng Liu	67f15e73cd	[Diffusion] Document runtime cache hardware tradeoffs Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-19 11:21:28 +08:00
Hongsheng Liu	59549968cf	[Diffusion] Tighten runtime cache compatibility guards Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-19 11:21:28 +08:00
Hongsheng Liu	d30ccdc315	[Diffusion] Add node-local runtime weight cache for DLO Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-19 11:21:01 +08:00