Group flat page snapshots into authenticated macro objects

README.md

@@ -180,8 +180,19 @@ source boundary, retaining at most 64 aliases. Alias graphs participate in TTL,
 LRU, capacity accounting, invalidation, and orphan collection.
 
 Opaque hybrid page storage, identified by `block_pages_v1`, encodes a complete
-boundary snapshot and partitions its bytes across chunk files. Those byte
-partitions are not independently usable token ranges.
+boundary snapshot. Schema-capable flat publication uses the authenticated
+`sparkcache-page-snapshot-manifest/v2` root and partition that opaque byte
+stream into content-addressed objects of at most 64 MiB. The root separately
+records the 256-token logical chunk size and count used by identity and
+admission; physical extents are not independently usable token ranges.
+
+Version 1 flat manifests, which store one encoded `.spcc` file per logical
+chunk, remain readable. The v2 representation does not change `CacheIdentity`,
+digest salts, logical chunk geometry, or either the default flat namespace or
+the opt-in `page-tail-cow-v1` namespace. A schema-incompatible reader does not
+reinterpret a v2 root as v1: strict manifest validation makes it a cache miss. Consequently,
+a mixed-version rollback can lose a reusable cache entry but cannot serve it
+under the wrong storage contract.
 
 Concurrent requests for one persistent digest are coalesced around one restore.
 After every worker finishes, patched vLLM retains the verified multi-group block
@@ -251,17 +262,20 @@ 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.
 
-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.
+SparkCache CUDA restore reads `.spcc` objects into alternating mapped
+arenas, hashes complete files in place, validates authenticated extents, and
+overlaps read work with CUDA submission. For a flat v2 page root it also
+re-authenticates the persisted manifest identity before placement, submits one
+bounded object at a time, and verifies the complete snapshot digest before the
+parked request may resume.
 
 ## Repository map and development validation
 
 | Path | Responsibility |
 |---|---|
 | `sparkcache/spark_context_cache_connector.py` | scheduler admission, worker I/O, all-rank availability, restore coalescing, shared-prefix coordination, and vLLM callbacks |
 | `sparkcache/persistent_context_cache/cache_manifest.py` | exact manifests, row-prefix aliases, immutable chunks, lookup, invalidation, capacity, and garbage collection |
-| `sparkcache/spark_context_cache_native_hybrid_restore.py` | authenticated direct reads, slab planning, and mapped-arena page placement |
+| `sparkcache/spark_context_cache_cuda_hybrid_restore.py` | authenticated CUDA reads, slab planning, and mapped-arena page placement |
 | `sparkcache/spark_context_cache_restore_timing.py` | machine-readable asynchronous restore timing |
 | `sparkcache/runtime_patches/` | exact-hash vLLM source contracts and GPU-free patch execution tests |
 | `sparkcache/native/` | C++/CUDA ABI, parser, reference implementation, kernel, and probes |
@@ -309,6 +323,19 @@ 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.
 
+Flat page publication uses the same 64-MiB extent ceiling. Publication retains
+at most two extent payloads per durable batch; Python restore retains at most
+four extent payloads in addition to the assembled snapshot. SparkCache CUDA
+restore avoids that assembled snapshot and authenticates one extent in a
+mapped arena before submitting its copy spans. A flat 813,068,464-byte
+snapshot therefore requires 13 payload objects rather than 512 logical-chunk
+files; the manifest remains the atomic visibility point.
+
+Flat macro publication and its SparkCache CUDA restore path are
+**implemented and GPU-free tested, not live qualified**. The object-count
+geometry above follows the format contract; it is not a claim of measured
+latency improvement.
+
 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

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": "a2add45a9f97446f6c2a843355161da9a5499ff7501b4750d2163591785d7345"
+    "source_sha256": "3f0d9b0aca8fb5cbb82dae3aa9daa2ed384e9edbced854930c0099e3d169f4bf"
   },
   "model": {
     "repository": "deepseek-ai/DeepSeek-V4-Flash-0731",

deploy/glm52_35bpw/profile.json

@@ -5,7 +5,7 @@
   "published_runtime_base": "ghcr.io/fujitsupolycom/gb10-vllm-serving@sha256:6fc26fdad81a18f0fff67ce0a05f6d90165625ea2e1cac8a6f39bfb462017028",
   "base_image_requirement": "exact GLM-5.2 3.5-bpw R7 image recorded by the source container inspection",
   "sparkcache": {
-    "source_sha256": "a2add45a9f97446f6c2a843355161da9a5499ff7501b4750d2163591785d7345"
+    "source_sha256": "3f0d9b0aca8fb5cbb82dae3aa9daa2ed384e9edbced854930c0099e3d169f4bf"
   },
   "model": {
     "repository": "brandonmusic/GLM-5.2-EXL3-TR3v4-3.5bpw-MTP78",

deploy/glm52_35bpw/profile.py

@@ -72,8 +72,8 @@ def _resolve_compat_option(
         if not _LEGACY_CUDA_RESTORE_WARNING_EMITTED:
             _LEGACY_CUDA_RESTORE_WARNING_EMITTED = True
             warnings.warn(
-                "SparkCache native-restore profile names are deprecated; use"
-                " SparkCache CUDA restore names",
+                "legacy SparkCache CUDA profile names are deprecated; use"
+                " canonical SparkCache CUDA restore names",
                 FutureWarning,
                 stacklevel=3,
             )

sparkcache/README.md

@@ -38,7 +38,7 @@ SparkCache reads and writes only the rank's local filesystem.
 | `persistent_context_cache/cache_manifest.py` | `ManifestStore`; exact manifests, row-prefix aliases, durable publication, lookup, restore, invalidation, and maintenance |
 | `spark_context_cache_cuda_placement.py` | `CudaPlacementAdapter`; attested SparkCache CUDA placement transaction |
 | `spark_context_cache_cuda_restore.py` | bounded read/hash/slab orchestration for SparkCache CUDA placement |
-| `spark_context_cache_native_hybrid_restore.py` | authenticated direct reads and multi-slab mapped-arena placement for opaque HMA pages |
+| `spark_context_cache_cuda_hybrid_restore.py` | authenticated CUDA reads and multi-slab mapped-arena placement for opaque HMA pages |
 | `spark_context_cache_restore_timing.py` | `sparkcache-restore-timing/v1` asynchronous restore records |
 | `streaming/factory.py` | scheduler and worker adapters for write-behind publication |
 | `replication/` | carrier-independent transaction protocol; no network adapter is implemented |
@@ -101,8 +101,8 @@ SparkCache CUDA restore uses these optional connector settings:
 - `spark_cache_cuda_restore_io_workers`.
 
 The equivalent environment variables begin with
-`SPARK_CONTEXT_CACHE_CUDA_`. Legacy `native` configuration, environment, CLI,
-and profile names remain accepted as compatibility aliases. A legacy-only
+`SPARK_CONTEXT_CACHE_CUDA_`. Legacy-key configuration, environment, CLI, and
+profile names remain accepted as compatibility aliases. A legacy-key-only
 configuration warns once per process. Supplying canonical and legacy values
 that disagree rejects startup. Generated configurations use only the CUDA
 names. The terminology change does not alter cache identity or stored bytes.
@@ -232,7 +232,7 @@ when placement completes and intentionally excludes that bookkeeping.
   `recurrent_boundary_granularity` advertises SparkCache's 256-token publication
   boundary to the exact vLLM scheduler without changing vLLM's native hash
   geometry.
-  SparkCache defers a new recurrent request until a later cached scheduler step,
+  SparkCache defers a recurrent request until a later cached scheduler step,
   when the preceding forward's hand-off can be observed. It latches one matching
   entry for every recurrent group, including a partial-tail CoW target when the
   boundary lies inside a recurrent page. Valid entries for an earlier checkpoint
@@ -266,7 +266,7 @@ when placement completes and intentionally excludes that bookkeeping.
 
 ## Optional paths
 
-- **SparkCache direct CUDA restore — implemented.** Requires the checksum-attested
+- **SparkCache CUDA restore — implemented.** Requires the checksum-attested
   `libspark_cache_placement` artifact and remains disabled unless the launch
   supplies its path, SHA-256, and a supported mapped-host arena size. The
   `glm53-flash-hybrid` profile supports authenticated multi-slab page restore;
@@ -291,7 +291,7 @@ and chunk geometry.
 
 GLM-5.3 Flash opaque pages are qualified at TP4/DCP1 with BF16 DFlash2 using
 seven draft tokens. Source revision
-`2b86fb9d02fa3595cca5caa864b81aedce44b8bb` qualifies SparkCache direct CUDA restore,
+`2b86fb9d02fa3595cca5caa864b81aedce44b8bb` qualifies SparkCache CUDA restore,
 multi-group recovery, and shared GPU-prefix reuse through C16 under a
 32-sequence scheduler ceiling. Sparse row-prefix aliases have GPU-free coverage
 but no live model-serving qualification.