test(ds4): preserve reference-exact speculative verification

server/CMakeLists.txt

@@ -1185,6 +1185,16 @@ if(DFLASH27B_TESTS)
     endif()
 
     # ─── Unit tests (no GPU, no model files) ────────────────────────────
+    find_package(Python3 COMPONENTS Interpreter QUIET)
+    if(Python3_Interpreter_FOUND)
+        add_test(
+            NAME ds4_exact_verify_parser
+            COMMAND "${Python3_EXECUTABLE}" -m unittest discover
+                -s "${CMAKE_CURRENT_SOURCE_DIR}/tests"
+                -p test_ds4_exact_verify_parity.py
+                -v)
+    endif()
+
     # The production CUDA and ROCm images share this entrypoint. Keep native
     # server defaults intact unless an operator explicitly supplies an env
     # override; otherwise container launches can silently disable features

server/docs/DS4.md

@@ -316,6 +316,23 @@ verification with full rollback snapshots for byte-identity checks. Neither
 fused verification nor the separate
 `--ds4-expert-top-k 4` approximation should be presented as byte-identical AR.
 
+For a model-backed reference-exact gate, run
+`server/scripts/test_ds4_exact_verify_parity.py`. It starts matched greedy AR
+and reference-exact servers, compares every generated token ID, and fails if
+the reference run did not execute speculative work with at least one rejected
+draft prefix and full-snapshot rollback. The gate requires SHA-256 identities
+for the server binary, target GGUF, DSpark GGUF, and prompt file.
+Use the same `hip:0` device, exact prefill, q=4, prompt, context, seed, and token
+limit for both arms. A passing run retains both server logs and a JSON manifest
+and refuses to overwrite that final evidence. Failed attempts keep their logs
+under a unique `failed-*` subdirectory without occupying the final filenames,
+so the same `--log-dir` can be rerun after correcting the failure.
+`DFLASH_DS4_EXACT_VERIFY_TRACE` is a default-off diagnostic used by that gate
+to emit the complete generated-token trace; it does not make the fused
+throughput profile exact. The two arms share a sanitized DS4 execution-policy
+environment. Only the reference arm enables DSpark, selects its draft, and
+enables reference-exact verification.
+
 DSpark can verify against in-process heterogeneous expert placement. The
 drafter remains local to its selected GPU backend; a failed draft load is
 reported and falls back to normal autoregressive decode. The target cache and

server/docs/ENVIRONMENT.md

@@ -98,6 +98,7 @@ consolidation of this list into CLI flags is tracked as follow-up work.
 - `DFLASH_DS4_DRAFT_BACKEND` - deepseek4_backend.cpp
 - `DFLASH_DS4_DRAFT_GPU` - deepseek4_backend.cpp
 - `DFLASH_DS4_DSPARK_DEBUG` - deepseek4_graph.cpp
+- `DFLASH_DS4_EXACT_VERIFY_TRACE` - deepseek4_backend.cpp
 - `DFLASH_DS4_FUSED_VERIFY` - deepseek4_dspark_spec.cpp, deepseek4_loader.cpp
 - `DFLASH_DS4_HOTNESS_CSV` - deepseek4_backend.cpp
 - `DFLASH_DS4_MOE_TP` - deepseek4_backend.cpp