Add verified page restore, shared prefixes, and tail-only publication

DEEPSEEK_V4_LIVE_VALIDATION.md

@@ -124,7 +124,7 @@ filling a 200 GiB root or qualify model-serving load behavior.
 This evidence qualifies one TP2/DCP1 development appliance. Model-serving load
 behavior and arbitrary DeepSeek-V4 deployments are unsupported. Block-page
 storage has bounded NVMe maintenance for end-of-prefill asynchronous
-snapshots. Native restore, streaming snapshots, and DCP-sharded block pages
+snapshots. SparkCache CUDA restore, streaming snapshots, and DCP-sharded block pages
 are unsupported by this profile. The qualified service used the Python
 asynchronous restore path; every chunk was
 checksum-verified before its pages were installed.

GLM52_A2_LIVE_VALIDATION.md

@@ -97,4 +97,4 @@ diagnostic.
 This record qualifies only the exact `0.1.0a2` wheel and GLM TP4/DCP4 lane.
 It does not qualify the `0.1.0a2` DeepSeek TP2/DCP1 or TP4/DCP1 profiles, a
 different runtime image, a different checkpoint, another scheduler budget,
-streaming snapshots, or native restore.
+streaming snapshots, or SparkCache CUDA restore.

GLM53_FLASH_DFLASH7_LIVE_VALIDATION.md

@@ -170,7 +170,7 @@ visible `message.content` must equal `SPARKCACHE_GLM53_OK` byte for byte.
 
 This evidence does not qualify another SparkCache source tree, vLLM source
 contract, target or draft checkpoint, parallel topology, scheduler budget,
-cache geometry, native direct restore, streaming snapshots, or MTP profile.
+cache geometry, SparkCache direct CUDA restore, streaming snapshots, or MTP profile.
 It does not establish throughput neutrality or restore performance for spans
 larger than 8,192 tokens. Full reasoning-trace equality is not a semantic
 oracle for this GLM runtime. The historical canary establishes successful

GLM53_NATIVE_RESTORE_PERFORMANCE_VALIDATION.md

@@ -1,10 +1,14 @@
-# GLM-5.3 native restore and shared-prefix validation
+# GLM-5.3 SparkCache CUDA restore and shared-prefix validation
+
+The repository path retains its compatibility filename so existing evidence
+links remain valid. In this record, SparkCache CUDA restore and SparkCache CUDA
+placement are the canonical capability and data-movement terms.
 
 Date: 2026-08-29
 
 ## Status
 
-Native direct restore, verified multi-group recovery, bounded shared GPU-prefix
+SparkCache direct CUDA restore, verified multi-group recovery, bounded shared GPU-prefix
 reuse, C2/C8/C16 completion, shared-trunk C16 completion, and continued
 generation are **qualified** for the exact GLM-5.3 Flash TP4/DCP1 runtime
 identified below.
@@ -31,7 +35,7 @@ qualification requires a receipt produced by the equality validator in
 | vLLM source revision | `local-inference-lab/vllm@da4d7be6c97434f6942292ed8abbf4b32dc44355` |
 | Serving topology | GLM-5.3 Flash, TP4/DCP1, one rank on each of `spark-r0` through `spark-r3` |
 | Scheduler capacity | `--max-num-seqs 32` |
-| Restore concurrency | Two host restore workers and two native placement lanes per rank |
+| Restore concurrency | Two host restore workers and two SparkCache CUDA placement lanes per rank |
 | Native staging | Two 256 MiB mapped-host arenas per rank |
 | Persistent prefix | 131,072 tokens and 813,068,464 encoded bytes per rank |
 | Runtime receipt | `evidence/glm53-flash-dflash7-bf16/hotlease-2b86fb9-runtime.json` |
@@ -48,7 +52,7 @@ The direct page-placement implementation is identified by these commits:
 | Responsibility | Revision |
 |---|---|
 | Restore phase timing | `175f9401984a03744d7fe1a985d7c2ef6035f949` |
-| Native hybrid-page placement | `71f367be07788d611698a251fe866d678b0034ae` |
+| SparkCache CUDA page placement | `71f367be07788d611698a251fe866d678b0034ae` |
 | Multi-slab restore and exact-prefix discovery | `8e7f5fc62fd4fffdd661aca9ea634cf130c45d1a` |
 | Direct pipelined slab restore | `94c44930a13df5c668d777e0270e7d8203069d7c` |
 | Authenticated span-table bound | `9dbf73c0caab89b24346567e2769752ac746e114` |
@@ -62,7 +66,7 @@ source-tree SHA-256 `b3e84d...` identified in the table above.
 
 ## Implemented restore path
 
-Native restore reads immutable `.spcc` objects directly into alternating
+SparkCache CUDA restore reads immutable `.spcc` objects directly into alternating
 mapped-host arenas with `pread`, hashes every complete file in place, validates
 its authenticated extent table, and submits only validated spans to the CUDA
 page-placement kernel. Read work and CUDA submission overlap across slabs.
@@ -96,7 +100,7 @@ historical canary found the expected marker suffix, and HTTP health remained
 ### Eight concurrent 16K prefixes
 
 The Python/Torch placement path produced 1.54--1.57 second submission spikes;
-eight clients completed in 9.45--10.64 seconds. Native placement submitted in
+eight clients completed in 9.45--10.64 seconds. SparkCache CUDA placement submitted in
 6--15 ms, and two restore lanes completed eight clients in approximately
 1.2--2.1 seconds. This diagnostic isolates page placement as the dominant
 serialized cost in that workload; it is not a separate deployment

MULTI_MODEL_LIVE_VALIDATION.md

@@ -141,6 +141,6 @@ three recorded profiles.
 
 This record does not qualify another wheel, source tree, runtime image,
 checkpoint, scheduler budget, topology, cache geometry, or vLLM source
-contract. DeepSeek DCP2 and DCP4, streaming snapshots, native restore in these
+contract. DeepSeek DCP2 and DCP4, streaming snapshots, SparkCache CUDA restore in these
 profiles, buddy replication, and longest-stored-prefix reuse for a growing
 conversation remain unsupported or research-only as stated in `README.md`.

README.md

@@ -24,9 +24,9 @@ Python-placement restore. The source deployment separately qualifies native
 131,072-token restore and bounded shared-prefix reuse. See
 [the public image record](deploy/glm53_flash/IMAGE_ANNOUNCEMENT.md),
 [the GLM-5.3 validation](GLM53_FLASH_DFLASH7_LIVE_VALIDATION.md), and
-[the native restore record](GLM53_NATIVE_RESTORE_PERFORMANCE_VALIDATION.md).
+[the SparkCache CUDA restore record](GLM53_NATIVE_RESTORE_PERFORMANCE_VALIDATION.md).
 
-The public image does not contain the model checkpoints. Native restore and
+The public image does not contain the model checkpoints. SparkCache CUDA restore and
 shared GPU-prefix qualification belong to a later source-bound runtime that has
 no published OCI digest.
 
@@ -147,7 +147,7 @@ timing.
 | Prefix and concurrency | Comparison | Recorded result |
 |---|---|---|
 | 8,192 tokens, C1 | qualified Python page restore | 147.2–194.0 ms cache service per rank |
-| 16,384 tokens, C8 | Python/Torch placement vs native placement | 9.45–10.64 s vs 1.2–2.1 s client latency |
+| 16,384 tokens, C8 | Python/Torch placement vs SparkCache CUDA placement | 9.45–10.64 s vs 1.2–2.1 s client latency |
 | 131,072 tokens, C1 | reconstruction pipeline vs cold direct mapped-arena restore | 1.29–1.46 s vs 131–250 ms cache service per rank; a host-warm restore reached 104–165 ms |
 | 131,072-token shared prefix, C16 | independent restores vs shared verified GPU blocks | rank-local work fell from 16 × 813 MB to 1 × 813 MB; standard-chat client p50 fell from 3.363 s to 2.980 s |
 | 131,072-token shared prefix, pretokenized C16 | standalone measurement | 2.698 s client p50 and 2.701 s maximum |
@@ -237,7 +237,7 @@ and recovery behavior are derived and tested.
 |---|---|---|
 | `vllm-project/vllm@fcc614141e5e9ab18cb304c476f7feed2a9552e3` with `patches/vllm/` | **implemented** | Exact patch inputs are published; no standalone public runtime builder is provided |
 | vLLM build `e2666d9a6` with `patches/vllm-e2666d9a6/` | **qualified** | DeepSeek-V4 and GLM-5.2 builders verify source, patch, and postimage hashes |
-| `local-inference-lab/vllm@da4d7be6c97434f6942292ed8abbf4b32dc44355` with `patches/vllm-da4d7be/` | **qualified** | GLM-5.3 HMA recovery, native restore, and bounded shared-prefix attachment |
+| `local-inference-lab/vllm@da4d7be6c97434f6942292ed8abbf4b32dc44355` with `patches/vllm-da4d7be/` | **qualified** | GLM-5.3 HMA recovery, SparkCache CUDA restore, and bounded shared-prefix attachment |
 
 The GLM-5.3 contract at
 [`vllm-kv-block-lease-contract-da4d7be.json`](sparkcache/runtime_patches/vllm-kv-block-lease-contract-da4d7be.json)
@@ -251,7 +251,7 @@ Native loading requires an explicit library path and SHA-256. CUDA 13 builds
 run a GPU-free byte-exact reference test and a CUDA hybrid-page probe before
 model-serving qualification.
 
-Native direct restore reads `.spcc` objects into alternating mapped arenas,
+SparkCache direct CUDA restore reads `.spcc` objects into alternating mapped arenas,
 hashes complete files in place, validates authenticated extents, and overlaps
 read work with CUDA submission.
 
@@ -298,6 +298,17 @@ byte-identical opaque pages. Restore reconstructs and verifies the complete
 snapshot before Python or native page placement. Arbitrary earlier-prefix
 aliases cannot be derived from opaque page snapshots.
 
+Page-delta publication writes `sparkcache-page-delta-manifest/v2` metadata over
+authenticated byte extents of at most 64 MiB. This physical grouping reduces
+the 1,024 delta files implied by a 262,144-token logical boundary to at most 24
+objects for a 1,575,821,491-byte delta. Reads retain at most four extent
+payloads in addition to one assembled delta buffer. The logical admission and
+digest boundary remains 256 tokens. Version 1 page-delta manifests remain
+readable; cache identity, digest salts, and the `page-tail-cow-v1` namespace do
+not change. Restore still materializes one authenticated delta buffer and the
+verified reconstructed snapshot before placement. Direct placement from base
+and delta extents is unsupported by this schema.
+
 Opaque HMA snapshots cannot be shortened by truncating chunk lists. SparkCache
 therefore uses the page-semantic format and distinct namespace described above.
 At most two page deltas may form one graph; the following publication compacts

ROADMAP.md

@@ -27,7 +27,7 @@ GPU-free coverage proves copy-on-write extension, bounded page-delta
 compaction, recurrent/sliding boundary geometry, corruption removal,
 reference-aware maintenance, and verified reconstruction. Live GLM-5.3
 qualification must still measure publication bytes, cold restore latency,
-native-placement latency after page reconstruction, SSD writes, and continued
+SparkCache CUDA-placement latency after page reconstruction, SSD writes, and continued
 generation across repeated conversation extensions.
 
 ### Per-entry retention controls
@@ -54,14 +54,14 @@ verification before vLLM schedules the request. It must reuse the bounded
 asynchronous-load machinery without claiming an external hit until all ranks
 confirm completion.
 
-### Native restore expansion
+### SparkCache CUDA restore expansion
 
 **Status: research-only qualification work.** Native multi-group page restore
 is implemented and source-runtime-qualified for the recorded GLM-5.3 TP4/DCP1
 profile. Tail page deltas reconstruct a fully verified snapshot before Python
-or native placement, but that path has no live performance qualification.
+or SparkCache CUDA placement, but that path has no live performance qualification.
 
-DeepSeek-V4 opaque HMA pages retain their verified Python restore path. Native
+DeepSeek-V4 opaque HMA pages retain their verified Python restore path. CUDA
 support for that profile must describe all five page groups, preserve each
 group's semantic reuse window, and prove byte identity before changing its
 qualified deployment contract.

deploy/deepseek_v4/README.md

@@ -15,7 +15,7 @@ DeepSeek-V4 SparkCache profiles.
   size 256;
 - 524,288-token request limit and 32 sequences;
 - 200 GiB high / 180 GiB low rank-local NVMe watermarks; and
-- Python verified restore with streaming and native placement disabled.
+- Python verified restore with streaming and SparkCache CUDA placement disabled.
 
 The launcher rejects DCP2/DCP4 because neither DSpark nor the opaque five-group
 HMA page format defines safe DCP ownership. See `DCP_SUPPORT.md`.

deploy/deepseek_v4/entrypoint.sh

@@ -52,7 +52,7 @@ print(json.dumps({
             "SPARKCACHE_MAX_SPAN_TOKENS", "524288"
         )),
         "spark_cache_streaming_snapshots": False,
-        "spark_cache_native_restore": False,
+        "spark_cache_cuda_restore": False,
     },
 }, separators=(",", ":")))
 PY

deploy/deepseek_v4/test_tp4_profile.py

@@ -145,7 +145,7 @@ def test_transfer_config_is_bounded_python_hma_restore() -> None:
     assert extra["spark_cache_model_profile"] == "deepseek-v4-fp8-hma"
     assert extra["spark_cache_draft_policy"] == "colocated_target"
     assert extra["spark_cache_streaming_snapshots"] is False
-    assert extra["spark_cache_native_restore"] is False
+    assert extra["spark_cache_cuda_restore"] is False
     assert extra["spark_cache_max_bytes"] == MAX_BYTES == 200 * 1024**3
     assert extra["spark_cache_low_watermark_bytes"] == LOW_WATERMARK_BYTES
     assert LOW_WATERMARK_BYTES == 180 * 1024**3
@@ -174,14 +174,13 @@ def test_transform_accepts_all_four_physical_ranks() -> None:
         environment = _environment(transformed)
         assert environment["MASTER_PORT"] == "29600"
         assert "SPARK_CONTEXT_CACHE_ENABLE" not in environment
-        assert "SPARK_CONTEXT_CACHE_ENABLE" in environment[
-            "SPARKRING_EXPLICITLY_UNSET"
-        ]
+        assert "SPARK_CONTEXT_CACHE_ENABLE" in environment["SPARKRING_EXPLICITLY_UNSET"]
         assert environment["PYTHONPATH"].startswith("/opt/sparkcache-src:")
         assert "/opt/sparkcache-src/sparkcache" not in environment["PYTHONPATH"]
-        assert transformed["Config"]["Labels"][
-            "org.sparkcache.deployment-profile"
-        ] == "deepseek-v4-flash-0731-tp4-dcp1"
+        assert (
+            transformed["Config"]["Labels"]["org.sparkcache.deployment-profile"]
+            == "deepseek-v4-flash-0731-tp4-dcp1"
+        )
 
 
 def test_cluster_preflight_accepts_one_homogeneous_four_rank_ring() -> None:
@@ -243,9 +242,7 @@ def test_cluster_preflight_rejects_collective_port_drift() -> None:
 @pytest.mark.parametrize("degree", (2, 4))
 def test_transform_rejects_hma_dcp_greater_than_one(degree: int) -> None:
     inspection = _source()
-    inspection["Config"]["Cmd"].extend(
-        ("--decode-context-parallel-size", str(degree))
-    )
+    inspection["Config"]["Cmd"].extend(("--decode-context-parallel-size", str(degree)))
     with pytest.raises(ProfileTransformError, match="DCP1"):
         transform_inspection(inspection, checkpoint_sha256=CHECKPOINT)
 

deploy/deepseek_v4/tp4_profile.json

@@ -4,7 +4,7 @@
   "cache_model_profile": "deepseek-v4-fp8-hma",
   "published_runtime_base": "ghcr.io/fujitsupolycom/gb10-vllm-serving@sha256:6fc26fdad81a18f0fff67ce0a05f6d90165625ea2e1cac8a6f39bfb462017028",
   "sparkcache": {
-    "source_sha256": "4998b24f4f504aeeb9bf92769ec720e282f546e6726d89fdfd06c4efa8d17c10"
+    "source_sha256": "a2add45a9f97446f6c2a843355161da9a5499ff7501b4750d2163591785d7345"
   },
   "model": {
     "repository": "deepseek-ai/DeepSeek-V4-Flash-0731",
@@ -39,7 +39,7 @@
     "load_failure_policy": "recompute",
     "draft_policy": "colocated_target",
     "streaming_snapshots": false,
-    "native_restore": false
+    "cuda_restore": false
   },
   "vllm": {
     "commit": "e2666d9a6",

deploy/deepseek_v4/tp4_profile.py

@@ -43,9 +43,7 @@ class ProfileTransformError(DeploymentContractError):
 
 def _require_sha256(value: str, role: str) -> str:
     if _SHA256_RE.fullmatch(value) is None:
-        raise ProfileTransformError(
-            f"{role} must be 64 lowercase hexadecimal digits"
-        )
+        raise ProfileTransformError(f"{role} must be 64 lowercase hexadecimal digits")
     return value
 
 
@@ -229,7 +227,9 @@ def _validate_arguments(arguments: list[str]) -> int:
         "--disable-prefix-caching",
     ):
         if forbidden in arguments:
-            raise ProfileTransformError(f"source command contains unsupported {forbidden}")
+            raise ProfileTransformError(
+                f"source command contains unsupported {forbidden}"
+            )
     for required_flag in ("--enable-auto-tool-choice",):
         if arguments.count(required_flag) != 1:
             raise ProfileTransformError(f"source command requires {required_flag}")
@@ -241,15 +241,19 @@ def _validate_arguments(arguments: list[str]) -> int:
         kernel = json.loads(_one(arguments, "--kernel-config"))
         speculative = json.loads(_one(arguments, "--speculative-config"))
     except json.JSONDecodeError as error:
-        raise ProfileTransformError("source DeepSeek JSON argument is invalid") from error
+        raise ProfileTransformError(
+            "source DeepSeek JSON argument is invalid"
+        ) from error
     if kernel.get("enable_cutedsl_warmup") is not False:
         raise ProfileTransformError("source DeepSeek kernel config must disable warmup")
     expected_speculative = {
         "method": serving["speculation_method"],
         "num_speculative_tokens": serving["speculation_tokens"],
         "moe_backend": serving["speculation_moe_backend"],
     }
-    if any(speculative.get(key) != value for key, value in expected_speculative.items()):
+    if any(
+        speculative.get(key) != value for key, value in expected_speculative.items()
+    ):
         raise ProfileTransformError("source DeepSeek DSpark configuration differs")
     if speculative.get("draft_sample_method", "greedy") != "greedy":
         raise ProfileTransformError("source DeepSeek DSpark sampling must be greedy")
@@ -293,7 +297,7 @@ def build_kv_transfer_config(checkpoint_sha256: str) -> dict[str, Any]:
             "spark_cache_store": True,
             "spark_cache_restore": True,
             "spark_cache_streaming_snapshots": False,
-            "spark_cache_native_restore": False,
+            "spark_cache_cuda_restore": False,
             "spark_cache_max_bytes": cache["max_bytes"],
             "spark_cache_low_watermark_bytes": cache["low_watermark_bytes"],
             "spark_cache_ttl_seconds": cache["ttl_seconds"],
@@ -311,7 +315,9 @@ def _reserved_ports(environment: Iterable[str]) -> frozenset[int]:
         try:
             value = int(raw)
         except ValueError as error:
-            raise ProfileTransformError(f"environment port {name} is invalid") from error
+            raise ProfileTransformError(
+                f"environment port {name} is invalid"
+            ) from error
         validated = _port(value, name)
         assert validated is not None
         reserved.add(validated)
@@ -342,9 +348,7 @@ def transform_inspection(
     reserved = _reserved_ports(source_environment)
     api_port = _port(api_port, "api_port")
     master_port = _port(master_port, "master_port")
-    effective_api = api_port or (
-        int(_one(arguments, "--port")) if rank == 0 else None
-    )
+    effective_api = api_port or (int(_one(arguments, "--port")) if rank == 0 else None)
     effective_master = master_port or int(_one(arguments, "--master-port"))
     if effective_api is not None and effective_api == effective_master:
         raise ProfileTransformError("api_port and master_port must differ")