Add exact GLM-5.3 DFlash7 Python-overlay runtime

docs/GLM53_DFLASH7_PYTHON_OVERLAY_SPARKCACHE_TP4_QUICKSTART.md

@@ -0,0 +1,90 @@
+# Serve GLM-5.3 with external DFlash7 and the exact Python-overlay runtime
+
+Status: **implemented**, not qualified. The image builder, profile resolver,
+and four-rank dry-run contract pass without GPUs. No image digest from this
+path has completed TP4/DCP1 model loading, semantic generation, SparkCache
+store/restart/restore, or concurrency qualification.
+
+## Runtime contract
+
+| Role | Exact identity |
+|---|---|
+| vLLM native extensions and wheel metadata | `da4d7be6c97434f6942292ed8abbf4b32dc44355` |
+| vLLM Python source | `0b67266a0f37d6146a8403fb8482403c62f412d5`, tree `ba9484ccb33aa56e90ff2f447f15ca9b9da97639` |
+| B12X | `b1d541f9e71a35f030d45fae437630fff7507c2a`, tree `c69cdec1c59a08e8e0e549f930fa8abcfb5134ae` |
+| SparkCache reconstructed-page placement | `5d571018de5b63a9a90e5c11e6d6e86bbff4a957`, tree `e864ed9ad64f771188fdb59aa9738e348134d636` |
+| Target | `local-inference-lab/GLM-5.3-Flash-NVFP4@520de24eabf507659eaef7c70f14fd584527facc` |
+| External draft | `incoai/GLM-5.3-Flash-DFlash2@dc77ff1c99eeb2df044ee3d4f0094eb033fee410`, BF16 weights SHA-256 `b33c03475ba7322cf398828f2d8d1be376df30dc05c6b40c28c8ea8da23e410b` |
+
+The serving contract uses seven speculative tokens, draft TP4, target FP8 KV,
+32 sequences, and 256-token vLLM blocks. SparkCache selects
+`tail-cow-v1`, which maps opaque GLM pages to the `page-tail-cow-v1`
+namespace, and uses the canonical CUDA restore keys.
+
+## Build the image
+
+Run on Linux ARM64 from a clean checkout containing this guide:
+
+```bash
+IMAGE='sparkring-glm53-sparkcache:dflash7-vllm-python-0b67266-native-da4d7be-b12x-b1d541f-arm64' \
+BUILD_RECEIPT="$PWD/glm53-dflash7-python-overlay-image-receipt.json" \
+bash runtime/glm53-flash-dflash7-python-overlay/build-image.sh
+```
+
+The builder verifies the public da4 image, the 31-file Python overlay, retained
+native ELFs and dispatch operators, B12X, SparkCache clean source, the CUDA
+placement library, four exact vLLM patches, and the eleven-file lease contract.
+It does not push the image.
+
+## Choose the target loader
+
+Two profiles share the same image and DFlash7 cache identity:
+
+| Profile | Status | Loader behavior |
+|---|---|---|
+| `glm53-flash-dflash7-python-overlay-safetensors-sparkcache-tp4-dcp1.example.json` | **implemented**, not qualified | Uses global safetensors for target and draft. This follows the qualified-compatible loader shape but still requires live qualification on the composed 0b image. |
+| `glm53-flash-dflash7-python-overlay-fastsafetensors-sparkcache-tp4-dcp1.example.json` | **research-only** | Uses global fastsafetensors with queue size one. vLLM also sends DFlash loading through that global loader, and DFlash materializes all yielded GPU tensors in a dictionary. Live peak-memory and loading qualification are required. |
+
+Do not describe the fastsafetensors profile as qualified until the external
+draft loads successfully at TP4 with measured peak GPU memory, or vLLM gains a
+separately enforced draft-loader contract.
+
+## Resolve the profile and inspect the plan
+
+Copy `scripts/config/glm53-flash-tp4-site.example.yaml`
+outside version control and replace every address, interface, SSH target,
+device, host path, and image identity. Select one profile template:
+
+```bash
+receipt="$PWD/glm53-dflash7-python-overlay-image-receipt.json"
+image='sparkring-glm53-sparkcache:dflash7-vllm-python-0b67266-native-da4d7be-b12x-b1d541f-arm64'
+profile_template='scripts/config/glm53-flash-dflash7-python-overlay-safetensors-sparkcache-tp4-dcp1.example.json'
+
+python scripts/prepare_glm53_dflash7_python_overlay_profile.py \
+  --profile-template "$profile_template" \
+  --site-template /path/to/resolved-glm53-site.yaml \
+  --image "$image" \
+  --image-id "$(jq -r .image_id "$receipt")" \
+  --cuda-placement-library-sha256 "$(jq -r .artifacts.sparkcache_cuda_placement_sha256 "$receipt")" \
+  --native-elf-manifest-sha256 "$(jq -r .runtime_contract.native_elf_manifest_sha256 "$receipt")" \
+  --native-dispatch-manifest-sha256 "$(jq -r .runtime_contract.native_dispatch_manifest_sha256 "$receipt")" \
+  --source-receipt-sha256 "$(jq -r .artifacts.source_receipt_sha256 "$receipt")" \
+  --profile-output /path/to/glm53-dflash7-profile.json \
+  --site-output /path/to/glm53-dflash7-site.yaml
+
+python scripts/sparkring_generic_launcher.py \
+  --site /path/to/glm53-dflash7-site.yaml \
+  --profile /path/to/glm53-dflash7-profile.json \
+  plan
+```
+
+`plan` is offline. Inspect every rank action before a lifecycle command.
+
+## Cache namespace impact
+
+The external DFlash weights SHA-256 is stored as
+`spark_cache_draft_checkpoint_sha256`. It cannot share entries with embedded
+MTP profiles. `tail-cow-v1` also separates these entries from snapshot-v1
+manifests. The two target-loader profiles share a namespace because loader
+choice does not change target or draft model state; each profile uses a
+different cache root and one-shot clear token while qualification is pending.

docs/PREREQUISITES.md

@@ -6,6 +6,7 @@ hardware and operator conditions required by the
 [GLM-5.3 Flash SparkCache quickstart](GLM53_FLASH_DFLASH2_BF16_SPARKCACHE_TP4_QUICKSTART.md),
 [source-built GLM-5.3 e10536a quickstart](GLM53_E10536A_SPARKCACHE_TP4_QUICKSTART.md),
 [GLM-5.3 adaptive-MTP and live-tensor KDA quickstart](GLM53_B12X_KDA_ADAPTIVE_MTP_SPARKCACHE_TP4_QUICKSTART.md),
+[GLM-5.3 DFlash7 Python-overlay quickstart](GLM53_DFLASH7_PYTHON_OVERLAY_SPARKCACHE_TP4_QUICKSTART.md),
 [GLM-5.3 Flash cache-disabled quickstart](GLM53_FLASH_DFLASH2_BF16_TP4_QUICKSTART.md),
 [DeepSeek quickstart](DEEPSEEK_V4_FLASH_QUICKSTART.md),
 [Qwen3.8-27B pair quickstart](QWEN38_27B_EXL3_K5K6_PAIR_QUICKSTART.md), and

runtime/README.md

@@ -13,6 +13,7 @@ credentials, or a live-deployment result.
 | [`glm53-flash/`](glm53-flash/README.md) | GLM-5.3 Flash target, BF16 DFlash2, vLLM, B12X, patched NCCL, and SparkCache identity and attestation contract |
 | [`glm53-flash-e10536a/`](glm53-flash-e10536a/README.md) | Implemented source builder for vLLM e10536a with internal MTP5 and opt-in adaptive depth; live serving unqualified |
 | [`glm53-flash-b12x-kda-adaptive-mtp/`](glm53-flash-b12x-kda-adaptive-mtp/README.md) | Implemented source builder for adaptive MTP and live-tensor B12X KDA at vLLM `0b67266a`; live serving unqualified |
+| [`glm53-flash-dflash7-python-overlay/`](glm53-flash-dflash7-python-overlay/README.md) | Implemented public-base builder for external DFlash7 with vLLM `0b67266a` Python over retained `da4d7be` native extensions; live serving unqualified |
 | [`deepseek0731-gb10/`](deepseek0731-gb10/README.md) | DeepSeek-V4-Flash-0731 GB10 parser, K5 sparse-row, and native PR431 image layer |
 | [`qwen38/`](qwen38/README.md) | Public-source ARM64 image builder for the Qwen3.8-27B EXL3 K5/K6 pair and cycle profiles |
 | [`faststart-lock.json`](faststart-lock.json) | Immutable ARM64 base-image and model-identity pins |

runtime/glm53-flash-dflash7-python-overlay/README.md

@@ -0,0 +1,43 @@
+# GLM-5.3 DFlash7 public-base Python overlay
+
+Status: **implemented**, not qualified. The builder constructs and verifies an
+ARM64 image but no image digest from this path has completed four-rank serving
+qualification.
+
+The image combines these exact roles:
+
+- retained vLLM native extensions and wheel metadata from
+  `da4d7be6c97434f6942292ed8abbf4b32dc44355`;
+- the 31-file vLLM Python delta at
+  `0b67266a0f37d6146a8403fb8482403c62f412d5`;
+- B12X `b1d541f9e71a35f030d45fae437630fff7507c2a`;
+- SparkCache reconstructed-page placement source
+  `5d571018de5b63a9a90e5c11e6d6e86bbff4a957`, Git tree
+  `e864ed9ad64f771188fdb59aa9738e348134d636`;
+- external BF16 DFlash2 weights with SHA-256
+  `b33c03475ba7322cf398828f2d8d1be376df30dc05c6b40c28c8ea8da23e410b`.
+
+The image builder shares the byte allowlist, retained-native verifier, exact
+SparkCache patch chain, and eleven-file lease contract with
+`runtime/glm53-flash-adaptive-mtp-python-overlay/`. Prepared image metadata is
+rendered for external DFlash7; it does not claim adaptive MTP.
+
+Build on Linux ARM64:
+
+```bash
+IMAGE='sparkring-glm53-sparkcache:dflash7-vllm-python-0b67266-native-da4d7be-b12x-b1d541f-arm64' \
+BUILD_RECEIPT="$PWD/glm53-dflash7-python-overlay-image-receipt.json" \
+bash runtime/glm53-flash-dflash7-python-overlay/build-image.sh
+```
+
+The script does not push the image. Its receipt verifies mixed vLLM
+provenance, B12X, target loader dependencies, NCCL, SparkCache CUDA placement,
+the clean SparkCache source receipt, and the vLLM lease contract. DFlash model
+files remain operator-mounted and are verified by the runtime profile.
+
+Two executable profiles use external DFlash at depth seven and TP4, FP8 target
+KV, 256-token vLLM blocks, 32 sequences, and SparkCache page-tail copy-on-write
+publication with CUDA restore. The global safetensors profile is implemented
+but unqualified on the composed 0b image. The global fastsafetensors profile is
+research-only until external-draft loading and peak GPU memory pass live gates.
+See `docs/GLM53_DFLASH7_PYTHON_OVERLAY_SPARKCACHE_TP4_QUICKSTART.md`.

runtime/glm53-flash-dflash7-python-overlay/build-image.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+# Build a GLM-5.3 SparkCache image by replacing only attested Python sources.
+set -euo pipefail
+
+here="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+repo_root="$(git -C "${here}" rev-parse --show-toplevel)"
+pins="${here}/pins.json"
+shared_overlay="${repo_root}/runtime/glm53-flash-adaptive-mtp-python-overlay"
+engine="${CONTAINER_ENGINE:-docker}"
+image="${IMAGE:-sparkring-glm53-sparkcache:dflash7-vllm-python-0b67266-native-da4d7be-b12x-b1d541f-arm64}"
+receipt_path="${BUILD_RECEIPT:-${PWD}/glm53-dflash7-python-overlay-image-receipt.json}"
+
+fatal() {
+  printf 'FATAL: %s\n' "$*" >&2
+  exit 78
+}
+
+read_pin() {
+  python3 - "${pins}" "$1" <<'PY'
+import json
+import sys
+
+value = json.load(open(sys.argv[1], encoding="utf-8"))
+for component in sys.argv[2].split("."):
+    value = value[int(component)] if isinstance(value, list) else value[component]
+print(value)
+PY
+}
+
+tracked_inputs=(
+  runtime/glm53-flash-dflash7-python-overlay
+  runtime/glm53-flash-adaptive-mtp-python-overlay
+  LICENSE
+)
+git -C "${repo_root}" diff --quiet HEAD -- "${tracked_inputs[@]}" ||
+  fatal "builder inputs differ from the checked-out SparkRing revision"
+untracked="$(git -C "${repo_root}" ls-files --others --exclude-standard -- "${tracked_inputs[@]}")"
+[[ -z "${untracked}" ]] ||
+  fatal "builder inputs include untracked files: ${untracked%%$'\n'*}"
+
+public_base="$(read_pin public_base.reference)"
+public_base_id="$(read_pin public_base.image_id)"
+arm_builder="$(read_pin builder.arm_builder)"
+vllm_native_commit="$(read_pin vllm.native_commit)"
+vllm_python_commit="$(read_pin vllm.python_commit)"
+vllm_python_tree="$(read_pin vllm.python_tree)"
+overlay_manifest_sha256="$(read_pin vllm.overlay_manifest_sha256)"
+b12x_commit="$(read_pin b12x.commit)"
+b12x_tree="$(read_pin b12x.tree)"
+sparkcache_commit="$(read_pin sparkcache.commit)"
+sparkcache_tree="$(read_pin sparkcache.tree)"
+sparkcache_source_sha256="$(read_pin sparkcache.source_tree_sha256)"
+sparkring_revision="$(git -C "${repo_root}" rev-parse HEAD)"
+
+"${engine}" pull --platform linux/arm64 "${public_base}"
+python3 "${here}/verify_image.py" \
+  --engine "${engine}" --pins "${pins}" --base-image "${public_base}" >/dev/null
+
+workspace="$(mktemp -d)"
+context="${workspace}/context"
+cleanup() {
+  # `workspace` is created by mktemp in this process and never accepts caller input.
+  rm -rf -- "${workspace}"
+}
+trap cleanup EXIT
+
+python3 "${here}/prepare_context.py" \
+  --repo-root "${repo_root}" "${context}" >/dev/null
+python3 "${here}/prepare_context.py" --verify "${context}" >/dev/null
+source_receipt_sha256="$(sha256sum "${context}/receipt.json" | cut -d' ' -f1)"
+mkdir -p "${context}/base-probe"
+"${engine}" run --rm --entrypoint python3 \
+  --volume "${shared_overlay}:/contract:ro" \
+  --volume "${pins}:/dflash-pins.json:ro" \
+  --volume "${context}/base-probe:/out" \
+  "${public_base}" \
+  /contract/overlay_contract.py \
+  --pins /dflash-pins.json \
+  --manifest /contract/vllm-python-overlay.json \
+  record-base \
+  --site-root /usr/local/lib/python3.12/dist-packages \
+  --console-script /usr/local/bin/vllm \
+  --output /out/retained-native.json >/dev/null
+native_elf_manifest_sha256="$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1], encoding="utf-8"))["native_elf_manifest_sha256"])' "${context}/base-probe/retained-native.json")"
+native_dispatch_manifest_sha256="$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1], encoding="utf-8"))["native_dispatch_manifest_sha256"])' "${context}/base-probe/retained-native.json")"
+cuda_placement_stage="sparkring-sparkcache-cuda-placement:${sparkcache_commit:0:12}-${sparkring_revision:0:12}"
+"${engine}" build \
+  --platform linux/arm64 \
+  --target sparkcache-cuda-placement \
+  --file "${context}/bundle/runtime/Containerfile" \
+  --build-arg "ARM_BUILDER=${arm_builder}" \
+  --tag "${cuda_placement_stage}" \
+  "${context}"
+sparkcache_cuda_placement_sha256="$("${engine}" run --rm --entrypoint sha256sum \
+  "${cuda_placement_stage}" \
+  /build/sparkcache-cuda-placement/build-cuda/libspark_cache_placement.so | cut -d' ' -f1)"
+
+"${engine}" build \
+  --platform linux/arm64 \
+  --file "${context}/bundle/runtime/Containerfile" \
+  --build-arg "PUBLIC_BASE=${public_base}" \
+  --build-arg "PUBLIC_BASE_ID=${public_base_id}" \
+  --build-arg "ARM_BUILDER=${arm_builder}" \
+  --build-arg "VLLM_NATIVE_COMMIT=${vllm_native_commit}" \
+  --build-arg "VLLM_PYTHON_COMMIT=${vllm_python_commit}" \
+  --build-arg "VLLM_PYTHON_TREE=${vllm_python_tree}" \
+  --build-arg "B12X_COMMIT=${b12x_commit}" \
+  --build-arg "B12X_TREE=${b12x_tree}" \
+  --build-arg "SPARKCACHE_COMMIT=${sparkcache_commit}" \
+  --build-arg "SPARKCACHE_TREE=${sparkcache_tree}" \
+  --build-arg "SPARKCACHE_SOURCE_SHA256=${sparkcache_source_sha256}" \
+  --build-arg "SPARKRING_REVISION=${sparkring_revision}" \
+  --build-arg "SOURCE_RECEIPT_SHA256=${source_receipt_sha256}" \
+  --build-arg "OVERLAY_MANIFEST_SHA256=${overlay_manifest_sha256}" \
+  --build-arg "NATIVE_ELF_MANIFEST_SHA256=${native_elf_manifest_sha256}" \
+  --build-arg "NATIVE_DISPATCH_MANIFEST_SHA256=${native_dispatch_manifest_sha256}" \
+  --build-arg "SPARKCACHE_CUDA_PLACEMENT_SHA256=${sparkcache_cuda_placement_sha256}" \
+  --tag "${image}" \
+  "${context}"
+
+python3 "${here}/verify_image.py" \
+  --engine "${engine}" --pins "${pins}" --image "${image}" \
+  --output "${receipt_path}" >/dev/null
+printf 'image=%s\nreceipt=%s\n' "${image}" "${receipt_path}"
+"${engine}" image inspect --format '{{.Id}}' "${image}"