Honor the DFlash draft load config

runtime/glm53-flash-adaptive-mtp-python-overlay/Containerfile

@@ -83,6 +83,17 @@ RUN python3 "${PYTHON_OVERLAY_ROOT}/overlay_contract.py" \
       verify-files \
       --root /usr/local/lib/python3.12/dist-packages \
       --stage target
+COPY bundle/runtime/patches/010-dflash-draft-load-config.patch \
+  ${PYTHON_OVERLAY_ROOT}/patches/010-dflash-draft-load-config.patch
+RUN root=/usr/local/lib/python3.12/dist-packages; \
+    target="${root}/vllm/v1/worker/gpu/spec_decode/dflash/utils.py"; \
+    before="$(sha256sum "${target}" | cut -d' ' -f1)"; \
+    printf 'dflash_loader_preimage_sha256=%s\n' "${before}"; \
+    test "${before}" = 2301c8199b73ed893dfbd3ae14ad125816f100b2d2ed034215b1f2d9aa2c23c5; \
+    patch --batch --forward -p1 -d "${root}" \
+      < "${PYTHON_OVERLAY_ROOT}/patches/010-dflash-draft-load-config.patch"; \
+    test "$(sha256sum "${target}" | cut -d' ' -f1)" = \
+      98acbae2b3bb4482d83f9637c163ce7c92707ccdf6561b7e431f23337f151cf4
 
 COPY --from=b12x-wheel /out/wheels/ /opt/sparkring/wheelhouse/
 RUN uv pip install --system --reinstall --no-deps \
@@ -164,6 +175,8 @@ LABEL org.opencontainers.image.title="SparkRing GLM-5.3 adaptive-MTP Python over
       org.sparkring.vllm.python.commit="${VLLM_PYTHON_COMMIT}" \
       org.sparkring.vllm.python.tree="${VLLM_PYTHON_TREE}" \
       org.sparkring.vllm.python-overlay-manifest-sha256="${OVERLAY_MANIFEST_SHA256}" \
+      org.sparkring.vllm.dflash-draft-loader-patch-sha256="39b567013ee7aed79f63200ed460129587933dc77fb430decdf19f78178de279" \
+      org.sparkring.vllm.dflash-draft-loader-postimage-sha256="98acbae2b3bb4482d83f9637c163ce7c92707ccdf6561b7e431f23337f151cf4" \
       org.sparkring.vllm.native-elf-manifest-sha256="${NATIVE_ELF_MANIFEST_SHA256}" \
       org.sparkring.vllm.native-dispatch-manifest-sha256="${NATIVE_DISPATCH_MANIFEST_SHA256}" \
       org.jovian.b12x.commit="${B12X_COMMIT}" \

runtime/glm53-flash-adaptive-mtp-python-overlay/README.md

@@ -53,6 +53,25 @@ commits into a temporary build context, builds a pure B12X wheel and the
 SparkCache CUDA placement library, creates the composed image, and writes a local
 receipt. It does not push an image or contact serving hosts.
 
+## External DFlash loader separation
+
+Status: **implemented, not qualified**. The composed vLLM runtime passes
+`SpeculativeConfig.draft_load_config` to the DFlash model loader. An external
+BF16 DFlash2 checkpoint can therefore retain the standard safetensors loader
+while the NVFP4 target uses fastsafetensors:
+
+```text
+--load-format fastsafetensors
+--speculative-config '{"method":"dflash","model":"/mtp-draft","num_speculative_tokens":7,"draft_tensor_parallel_size":4,"kv_cache_dtype":"auto","draft_sample_method":"probabilistic","rejection_sample_method":"standard","draft_load_config":{"load_format":"safetensors"}}'
+```
+
+Mount the exact external checkpoint read-only at `/mtp-draft`. The draft
+loader config is optional: omitting it inherits the target `LoadConfig`, which
+means both models use fastsafetensors under the command above. The separated
+configuration requires `fastsafetensors==0.3.3` for the target and no
+InstantTensor mount or environment setting. Four-rank model loading,
+generation, draft counters, and peak device memory remain unqualified.
+
 ## Resolve and inspect the four-rank plan
 
 Copy the sanitized site template outside version control and replace its

runtime/glm53-flash-adaptive-mtp-python-overlay/overlay_contract.py

@@ -4,6 +4,7 @@
 from __future__ import annotations
 
 import argparse
+import ast
 import hashlib
 import importlib.metadata
 import inspect
@@ -118,6 +119,118 @@ def final_file_hashes(pins: dict[str, Any]) -> dict[str, str]:
     return result
 
 
+def validate_dflash_loader_source(source: str) -> None:
+    """Require DFlash to pass its optional draft LoadConfig to get_model."""
+
+    tree = ast.parse(source)
+    function = next(
+        (
+            node
+            for node in tree.body
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+            and node.name == "load_dflash_model"
+        ),
+        None,
+    )
+    if function is None:
+        raise ContractError("DFlash loader source omits load_dflash_model")
+    calls = [
+        node
+        for node in ast.walk(function)
+        if isinstance(node, ast.Call)
+        and isinstance(node.func, ast.Name)
+        and node.func.id == "get_model"
+    ]
+    if len(calls) != 1:
+        raise ContractError("DFlash loader must contain exactly one get_model call")
+    keyword = next(
+        (item for item in calls[0].keywords if item.arg == "load_config"),
+        None,
+    )
+    value = None if keyword is None else keyword.value
+    if not (
+        isinstance(value, ast.Attribute)
+        and value.attr == "draft_load_config"
+        and isinstance(value.value, ast.Name)
+        and value.value.id == "speculative_config"
+    ):
+        raise ContractError(
+            "DFlash get_model must consume speculative_config.draft_load_config"
+        )
+
+
+def validate_optional_load_config_fallback(source: str) -> None:
+    """Require get_model(None) to retain the enclosing vLLM LoadConfig."""
+
+    tree = ast.parse(source)
+    function = next(
+        (
+            node
+            for node in tree.body
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+            and node.name == "get_model"
+        ),
+        None,
+    )
+    if function is None:
+        raise ContractError("model-loader source omits get_model")
+    calls = [
+        node
+        for node in ast.walk(function)
+        if isinstance(node, ast.Call)
+        and isinstance(node.func, ast.Name)
+        and node.func.id == "get_model_loader"
+    ]
+    if len(calls) != 1 or len(calls[0].args) != 1:
+        raise ContractError("get_model must select exactly one model loader")
+    selected = calls[0].args[0]
+    if not (
+        isinstance(selected, ast.BoolOp)
+        and isinstance(selected.op, ast.Or)
+        and len(selected.values) == 2
+        and isinstance(selected.values[0], ast.Name)
+        and selected.values[0].id == "load_config"
+        and isinstance(selected.values[1], ast.Attribute)
+        and selected.values[1].attr == "load_config"
+        and isinstance(selected.values[1].value, ast.Name)
+        and selected.values[1].value.id == "vllm_config"
+    ):
+        raise ContractError(
+            "get_model must fall back from a missing draft LoadConfig to "
+            "vllm_config.load_config"
+        )
+
+
+def verify_vllm_runtime_patch_files(
+    root: Path,
+    pins: dict[str, Any],
+) -> list[dict[str, str]]:
+    """Verify installed runtime-patch postimages and loader semantics."""
+
+    verified = []
+    for record in pins["vllm"].get("runtime_patches", ()):
+        relative = safe_relative_path(record["target"])
+        path = root / relative
+        observed = sha256_file(path)
+        if observed != record["postimage_sha256"]:
+            raise ContractError(
+                f"vLLM runtime patch postimage mismatch for {relative}: "
+                f"expected {record['postimage_sha256']}, got {observed}"
+            )
+        compile(path.read_bytes(), str(path), "exec")
+        if relative.as_posix() == "vllm/v1/worker/gpu/spec_decode/dflash/utils.py":
+            validate_dflash_loader_source(path.read_text(encoding="utf-8"))
+        verified.append(
+            {
+                "path": relative.as_posix(),
+                "sha256": observed,
+            }
+        )
+    loader = root / "vllm/model_executor/model_loader/__init__.py"
+    validate_optional_load_config_fallback(loader.read_text(encoding="utf-8"))
+    return verified
+
+
 def verify_overlay_files(
     root: Path,
     manifest: dict[str, Any],
@@ -372,12 +485,14 @@ def composed_report(
     verified = verify_overlay_files(root, manifest, stage="final", pins=pins)
     compile_overlay_files(root, manifest)
     verify_retained_native(site_root, console_script, base_record)
+    runtime_patches = verify_vllm_runtime_patch_files(root, pins)
     return {
         "schema": "sparkring-glm53-public-python-overlay-verification/v1",
         "status": "implemented",
         "vllm_python_files_verified": len(verified),
         "vllm_python_commit": pins["vllm"]["python_commit"],
         "vllm_native_commit": pins["vllm"]["native_commit"],
+        "vllm_runtime_patches": runtime_patches,
         "b12x": verify_b12x_contract(pins),
         "dependencies": verify_dependencies(pins),
         "native_elf_manifest_sha256": base_record["native_elf_manifest_sha256"],

runtime/glm53-flash-adaptive-mtp-python-overlay/patches/010-dflash-draft-load-config.patch

@@ -0,0 +1,13 @@
+diff --git a/vllm/v1/worker/gpu/spec_decode/dflash/utils.py b/vllm/v1/worker/gpu/spec_decode/dflash/utils.py
+index b9e6ea02f..84c7d54ac 100644
+--- a/vllm/v1/worker/gpu/spec_decode/dflash/utils.py
++++ b/vllm/v1/worker/gpu/spec_decode/dflash/utils.py
+@@ -46,5 +46,7 @@ def load_dflash_model(target_model: nn.Module, vllm_config: VllmConfig) -> nn.M
+     )
+     with set_model_tag("dflash_head"):
+         dflash_model = get_model(
+-            vllm_config=draft_vllm_config, model_config=draft_model_config
++            vllm_config=draft_vllm_config,
++            model_config=draft_model_config,
++            load_config=speculative_config.draft_load_config,
+         )

runtime/glm53-flash-adaptive-mtp-python-overlay/pins.json

@@ -28,6 +28,17 @@
     "python_tree": "ba9484ccb33aa56e90ff2f447f15ca9b9da97639",
     "overlay_manifest": "runtime/glm53-flash-adaptive-mtp-python-overlay/vllm-python-overlay.json",
     "overlay_manifest_sha256": "e5e528288b173399611a4930fecc4182b7208bc1564881d52ca5d2c5c4ae0f6a",
+    "runtime_patches": [
+      {
+        "status": "implemented",
+        "path": "runtime/glm53-flash-adaptive-mtp-python-overlay/patches/010-dflash-draft-load-config.patch",
+        "target": "vllm/v1/worker/gpu/spec_decode/dflash/utils.py",
+        "sha256": "39b567013ee7aed79f63200ed460129587933dc77fb430decdf19f78178de279",
+        "preimage_sha256": "2301c8199b73ed893dfbd3ae14ad125816f100b2d2ed034215b1f2d9aa2c23c5",
+        "postimage_sha256": "98acbae2b3bb4482d83f9637c163ce7c92707ccdf6561b7e431f23337f151cf4",
+        "contract": "DFlash passes SpeculativeConfig.draft_load_config to get_model; None retains the target LoadConfig fallback."
+      }
+    ],
     "native_source_objects": {
       "csrc": "9ada29088768f1bc08dadd2eed3c9738eb9ac8a1",
       "cmake": "5e5bbdbe1c1b3a479656d8d6a41cc32a1982c43d",

runtime/glm53-flash-adaptive-mtp-python-overlay/prepare_context.py

@@ -72,6 +72,7 @@ def clone_detached(
     destination.mkdir(parents=True)
     run(("git", "init", "--quiet", str(destination)))
     run(("git", "-C", str(destination), "config", "core.autocrlf", "false"))
+    run(("git", "-C", str(destination), "config", "core.longpaths", "true"))
     run(("git", "-C", str(destination), "remote", "add", "origin", repository))
     run(
         (
@@ -172,6 +173,39 @@ def verify_vllm_lineage(
             raise PrepareError(f"vLLM base blob mismatch: {path}")
 
 
+def verify_vllm_runtime_patches(
+    source: Path,
+    pins: dict[str, Any],
+    patch_root: Path,
+) -> None:
+    """Verify each exact-input runtime patch and restore the clean source."""
+
+    for record in pins["vllm"].get("runtime_patches", ()):
+        patch = patch_root / Path(record["path"]).name
+        target = source / record["target"]
+        if sha256_file(patch) != record["sha256"]:
+            raise PrepareError(f"vLLM runtime patch mismatch: {record['path']}")
+        if sha256_file(target) != record["preimage_sha256"]:
+            raise PrepareError(
+                f"vLLM runtime patch preimage mismatch: {record['target']}"
+            )
+        run(("git", "-C", str(source), "apply", "--check", str(patch)))
+        run(("git", "-C", str(source), "apply", str(patch)))
+        try:
+            observed = sha256_file(target)
+            if observed != record["postimage_sha256"]:
+                raise PrepareError(
+                    f"vLLM runtime patch postimage mismatch: {record['target']}"
+                )
+        finally:
+            run(("git", "-C", str(source), "apply", "--reverse", str(patch)))
+    verify_git_source(
+        source,
+        commit=pins["vllm"]["python_commit"],
+        tree=pins["vllm"]["python_tree"],
+    )
+
+
 def copy_overlay(source: Path, destination: Path, manifest: dict[str, Any]) -> None:
     target = manifest["target"]["commit"]
     for record in manifest["files"]:
@@ -241,6 +275,8 @@ def prepare(output: Path, *, repository_root: Path = ROOT) -> dict[str, Any]:
     )
     verify_vllm_lineage(vllm, pins, manifest)
     copy_overlay(vllm, overlay, manifest)
+    patch_root = HERE / "patches"
+    verify_vllm_runtime_patches(vllm, pins, patch_root)
 
     b12x = sources / "b12x"
     clone_detached(
@@ -283,6 +319,11 @@ def prepare(output: Path, *, repository_root: Path = ROOT) -> dict[str, Any]:
         "README.md",
     ):
         copy_file(HERE / filename, runtime / filename)
+    runtime_patches = []
+    for patch in pins["vllm"].get("runtime_patches", ()):
+        name = Path(patch["path"]).name
+        copy_file(patch_root / name, runtime / "patches" / name)
+        runtime_patches.append(f"bundle/runtime/patches/{name}")
     copy_file(repository_root / "LICENSE", runtime / "SparkRing-LICENSE")
 
     receipt_inputs = tuple(
@@ -297,7 +338,7 @@ def prepare(output: Path, *, repository_root: Path = ROOT) -> dict[str, Any]:
             "README.md",
             "SparkRing-LICENSE",
         )
-    )
+    ) + tuple(runtime_patches)
     receipt = {
         "schema": RECEIPT_SCHEMA,
         "status": "implemented",
@@ -318,6 +359,7 @@ def prepare(output: Path, *, repository_root: Path = ROOT) -> dict[str, Any]:
                 "source_tree_sha256": observed_sparkcache,
             },
         },
+        "vllm_runtime_patches": pins["vllm"].get("runtime_patches", []),
         "files": {relative: sha256_file(output / relative) for relative in receipt_inputs},
     }
     (output / "receipt.json").write_text(
@@ -344,6 +386,15 @@ def verify_context(context: Path) -> dict[str, Any]:
         tree=pins["vllm"]["python_tree"],
     )
     verify_vllm_lineage(context / "bundle/sources/vllm", pins, manifest)
+    if receipt.get("vllm_runtime_patches") != pins["vllm"].get(
+        "runtime_patches", []
+    ):
+        raise PrepareError("prepared context vLLM runtime patch receipt differs")
+    verify_vllm_runtime_patches(
+        context / "bundle/sources/vllm",
+        pins,
+        context / "bundle/runtime/patches",
+    )
     verify_git_source(
         context / "bundle/sources/b12x",
         commit=pins["b12x"]["commit"],