Document DSpark 3-stage speculative drafter sidecar

README.md

@@ -15,6 +15,8 @@ tags:
   - deepseek
   - deepseek-v4
   - mtp
+  - dspark
+  - speculative-decoding
 ---
 
 # hipfire DeepSeek V4 Flash (mq2lloyd)
@@ -52,10 +54,33 @@ The runtime SWA K and V state (window = 128) is **F32** and is allocated live at
 |------|------|---------|
 | `deepseek-v4-flash.mq2lloyd` | 86,184,307,283 B (≈86.2 GB) | Main model — 43 layers, 256 routed + 1 shared expert per layer, attention, embed, lm_head |
 | `deepseek-v4-flash-mtp.mq2lloyd` | 1,998,047,355 B (≈2.0 GB) | Single MTP layer (`num_nextn_predict_layers = 1`), opened automatically when present alongside the main file. Used for optional speculative decode. |
+| `deepseek-v4-flash-dspark.mq2lloyd` | 5,996,334,814 B (≈6.0 GB) | **DSpark 3-stage speculative drafter** (`mtp.0/1/2`), opened automatically via the `<stem>-dspark.<ext>` sibling convention. Wins over the single MTP head under `--spec dspark` / `--spec auto`. See the DSpark section below. |
+
+## DSpark speculative drafter (`-dspark` sidecar)
+
+`deepseek-v4-flash-dspark.mq2lloyd` is an optional multi-token draft module that replaces the single in-trunk MTP head with a **3-stage chain** (`mtp.0 → mtp.1 → mtp.2`) proposing a block of 5 tokens per step. It is additive to the main file and to the MTP companion — attach whichever you want; DSpark auto-wins over MTP when both are present.
+
+Verified by enumerating the file's tensor table (`hfq_dump`): **2 376 tensors, arch_id = 9**, same mixed-precision scheme as the main file:
+
+```
+  2304  qt=19 (MQ2G256Lloyd)   – 256 routed experts × 3 (w1/w2/w3) × 3 draft stages
+    31  qt=3  (Q8F16)          – per-stage attention, shared experts, main_proj, markov heads, confidence head
+    41  qt=1  (F16)            – norms, mHC gating (hc_head_*), main_norm
+```
+
+The three stages are near-symmetric full DeepSeek-V4 blocks (791 / 789 / 796 tensors) with role-specific heads:
+
+- **`mtp.0`** — owns the embed/main-hidden entry: `main_proj` (Linear 12288→4096, no bias) + `main_norm` (RMS). Draft input comes from `main_proj` + a noise block (`dspark_noise_token_id = 128799`), not the MTP head's `e_proj`/`h_proj` mixing.
+- **`mtp.1`** — middle draft block.
+- **`mtp.2`** — owns the output heads: `hc_head_{base,fn,scale}`, `markov_head.{markov_w1, markov_w2}` (Embed 129280→256 / Linear 256→129280) for the Markov token-bias prior, and `confidence_head.proj` (Linear 4352→1, fp32) driving confidence-truncated acceptance.
+
+Config (from the file's metadata blob): `dspark_block_size = 5`, `dspark_target_layer_ids = [40, 41, 42]`, `dspark_markov_rank = 256`, `dspark_noise_token_id = 128799`.
+
+Enable it with `hipfire run deepseek-v4-flash --spec dspark` (force) or `--spec auto` (DSpark preferred when the sidecar is present). Acceptance can be tuned with `--dspark-conf-threshold <0..1>` (deepseek4 default 0.3).
 
 ## Loading
 
-This model is registered in [hipfire's CLI registry](https://github.com/Kaden-Schutt/hipfire/blob/master/cli/registry.json) under `deepseek-v4-flash` (aliases: `deepseek4`, `deepseek-v4`). The registry entry pulls both the main file and the MTP companion together.
+This model is registered in [hipfire's CLI registry](https://github.com/Kaden-Schutt/hipfire/blob/master/cli/registry.json) under `deepseek-v4-flash` (aliases: `deepseek4`, `deepseek-v4`). The registry entry pulls the main file together with both the MTP and DSpark companions.
 
 ```bash
 # 1. Install hipfire (one-time):
@@ -84,6 +109,7 @@ cargo build --release -p hipfire-arch-deepseek4 --example deepseek4_chat
 # Pull the files (uses `hf` CLI or hipfire's registry-driven pull above):
 hf download nwoolmer/hipfire-deepseek-v4-flash \
     deepseek-v4-flash.mq2lloyd deepseek-v4-flash-mtp.mq2lloyd \
+    deepseek-v4-flash-dspark.mq2lloyd \
     --local-dir ~/.hipfire/models/
 
 # Direct chat binary (DSML chat template, EOS stop, multi-turn KV):
@@ -142,7 +168,7 @@ Cold-process load — weight upload from both HFQ files — is **~44 s** on the
 
 - **GPU**: AMD RDNA3 / RDNA3.5 with HIP + WMMA. **Validated on gfx1151 (Radeon 8060S, Strix Halo)** for this build of the V4F weights. The engine has gfx1100 (RX 7900-class) kernels in tree but they were not exercised against this specific file; RDNA1/2 (gfx1010 / gfx103x) and gfx12 are tracked targets of the broader hipfire project but not recommended for running this model.
 - **OS**: Linux with `amdgpu` kernel driver. Built and measured against **ROCm 7.2.1 / HIP 7.2**.
-- **Memory**: 86.2 GB for the main file + ~2 GB for the MTP companion + several GB working set during decode. Strix Halo class systems with 128 GB UMA are the comfortable target; discrete-GPU configs need ~96 GB+ of VRAM.
+- **Memory**: 86.2 GB for the main file + ~2 GB for the MTP companion + ~6 GB for the optional DSpark drafter + several GB working set during decode. Strix Halo class systems with 128 GB UMA are the comfortable target; discrete-GPU configs need ~96 GB+ of VRAM.
 - **Tested context length**: end-to-end inference was exercised at prompts up to ~1.2 k tokens and generations up to 256 tokens. Upstream's stated max position (1 048 576 via YaRN) was not exercised here.
 
 ## License