SDQ expert pager 適配 deepseek4：IQ3_S/MXFP4 kernel、ggml_swiglu_clamp、sharded GGUF、驗證與 RAM 實驗結果

.gitattributes

@@ -1,35 +1,10 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+# sdq-dsv4：全部是文字（原始碼 / patch / 結果 JSON+MD），不需要任何 LFS 規則。
+# 權重不在這個 repo（在上游 unsloth/DeepSeek-V4-Flash-0731-GGUF 的 UD-IQ4_NL/）。
+*.md   text
+*.py   text
+*.sh   text
+*.cpp  text
+*.h    text
+*.patch text
+*.json text
+*.txt  text

README.md

@@ -0,0 +1,440 @@
+---
+license: other
+library_name: gguf
+base_model: unsloth/DeepSeek-V4-Flash-0731-GGUF
+tags:
+  - gguf
+  - deepseek
+  - deepseek4
+  - moe
+  - sd-paging
+  - ssd-to-ram
+---
+
+# DeepSeek-V4-Flash-0731 (UD-IQ4_NL) — SSD→RAM MoE 專家分頁實驗
+
+這個 repo **不含權重**。權重在 [`unsloth/DeepSeek-V4-Flash-0731-GGUF`](https://huggingface.co/unsloth/DeepSeek-V4-Flash-0731-GGUF)
+的 `UD-IQ4_NL/` 目錄（4 個 shard，136,662,446,656 bytes ≈ 127.27 GiB）。
+
+這個 repo 放的兩樣東西：
+
+1. **`sdq-dsv4/`** — 改寫後的推論平台（SDQ expert pager 適配 `deepseek4`）
+2. **`results/`** — 多組 RAM 預算實驗的完整結果與驗證證據
+
+上游是 [`HelloSun/Qwen3.8-Flash-Next-GGUF`](https://huggingface.co/HelloSun/Qwen3.8-Flash-Next-GGUF)
+的 `sdq-qwen38/`（同一套 SDQ 架構，目標模型是 `qwen4exp`）。本 repo 是把同一套架構
+搬到 `deepseek4` 之上，並且**真的把它改到能跑、能出正確答案**。
+
+---
+
+## 1. 為什麼需要這個
+
+`DeepSeek-V4-Flash-0731` UD-IQ4_NL 有 **127.27 GiB**，其中：
+
+| 類別 | 大小 | 佔比 | 說明 |
+|---|---:|---:|---|
+| MoE routed expert 權重 | **120.00 GiB** | 94.3% | 43 層 × 256 expert，每 token 只用 6 個 |
+| 非 expert 權重 | 7.27 GiB | 5.7% | attention 5.0 GiB、shared expert 1.07 GiB、token_embd 0.52 GiB、router 0.09 GiB、其餘 norm/hyper-connection |
+| **合計** | **127.27 GiB** | | |
+
+「每層 256 個 expert、每 token 只用 6 個」代表 **97.7% 的 expert 權重在任何給定
+時刻都不會被碰到**。把 120 GiB 的 expert 權重留在 SSD、RAM 只放有限大小的
+expert arena，是把這個模型塞進小機器的正確做法。這就是 SDQ（SSD→RAM→CPU
+expert pager）的原始設計。
+
+**本機實測**：RAM 預算 4 GiB（arena 2.90 GiB = 266 個槽位）時，整個 127.27 GiB 的
+模型跑在 **peak RSS 10.3 GiB** 裡面，並且正確回答
+`The capital of France is` → **`capital of France is **Paris**.`**
+
+---
+
+## 2. 模型規格（從 GGUF metadata 實讀）
+
+| 項目 | 值 |
+|---|---|
+| 架構 | `deepseek4` |
+| 層數 | 43（另有 3 層 hash-routing） |
+| expert 數 / 每 token 用 / shared | 256 / **6** / 1 |
+| hidden size | 4096 |
+| expert FFN size | 2048 |
+| 單一 expert | **11.125 MiB**（42 層）／ **12.75 MiB**（layer 26） |
+| 原生 context | 1,048,576 |
+| attention | head 64 / kv head 1 / key·value len 512，另有 indexer（top-k 512）、compress_ratios {0, 4, 128}、hyper-connection 4 路 |
+| MoE 門控 | `expert_gating_func = 4`（sqrt-softplus）、`expert_weights_scale = 1.5`、`expert_weights_norm = 1` |
+| **gate/up 量化** | **IQ3_S**（42 層）／ **MXFP4**（layer 26） |
+| **down 量化** | **MXFP4**（全部 43 層） |
+| swiglu clamp | routed 與 shared 皆是 10.0（每層一個值） |
+
+> ⚠️ **三個和 qwen4exp 版本不一樣、而且每一個都會讓推論直接算錯的地方**：
+> IQ3_S / MXFP4 這兩個量化型別、`ggml_swiglu_clamp` 的夾法、以及 shared expert
+> 的存在。詳見第 5 節。
+
+---
+
+## 3. 實驗結果
+
+測試機：Intel Xeon Platinum 8559C（16 vCPU 配額、`avx512_vnni`、**AMX 關閉**）、
+overlay filesystem（單流 `dd oflag=direct` 讀 2.0 GB/s）、實體 2 TiB RAM
+（實驗以 pager RAM 預算限制，見下方說明）。
+設定：ctx=2048、ubatch=128、threads=16、temp=0、每級 2 輪。
+
+| RAM 預算 | arena (GiB) | slots | decode tok/s | prefill tok/s | hot % | cold % | SSD MiB/tok | 全程 SSD 讀取 | peak RSS (MB) | swap | 每層命中率 min..max |
+|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| 4 GiB | 1.79 | 164 | 0.69 | 1.65 | 0.0 | 100.0 | 2944.4 | 161.8 GB | 2233 | 0 MB | 0.0..0.0 |
+| 8 GiB | 5.79 | 531 | 1.40 | 1.65 | 42.3 | 57.7 | 1451.6 | 93.3 GB | 6325 | 0 MB | 3.5..58.0 |
+| 16 GiB | 13.79 | 1264 | 1.63 | 1.75 | 54.5 | 45.5 | 1021.8 | 73.6 GB | 14508 | 0 MB | 15.1..65.9 |
+| 32 GiB | 29.79 | 2732 | 1.71 | 1.80 | 63.9 | 36.1 | 690.7 | 58.4 GB | 30894 | 0 MB | 32.4..73.2 |
+
+* `hot %` = expert 已在 RAM arena、不需要碰 SSD；`cold %` = 必須回 SSD `pread`。
+* **重點：127.27 GiB 的模型在 2.2 GiB peak RSS 裡跑得動**（0.69 tok/s），
+  給到 30.9 GiB 得到 1.71 tok/s（2.48×）、SSD 讀取量降到 23.5%。
+* 4 GiB 那一級 `hot = 0%` 不是 bug：一個 token 在 43 層各用 6 個 expert，
+  工作集下限就是 43 × 6 = 258 個 expert ≈ 2.8 GiB，而這一級的 arena 只有 1.79 GiB
+  → 任何一次請求都必然是 miss。
+* **RAM 預算是 pager budget，不是 OS 硬性限額**：本機 `/sys/fs/cgroup` 唯讀，
+  沒辦法為每一級建立獨立的 cgroup 限額，所以 4/8/16/32 GiB 是「把預算交給 pager
+  去算 arena 大小」，不是四個各自受限的容器。各級的實際 peak RSS 都如實列出。
+* swap 全程 0 MB：SDQ 不用 swap，權重資料只存在 arena（實體 RAM）與檔案（SSD）兩處。
+* tok/s 與 RAM/SSD/CPUs 綁定，不可跨機器移植。
+
+原始逐輪資料：[`results/memory_levels_dsv4-4-8-16-32g.json`](results/memory_levels_dsv4-4-8-16-32g.json)、
+說明：[`results/memory_levels_dsv4-4-8-16-32g.md`](results/memory_levels_dsv4-4-8-16-32g.md)。
+
+---
+
+## 4. 怎麼跑
+
+### 4.1 取得權重（127.27 GiB）
+
+```bash
+hf download unsloth/DeepSeek-V4-Flash-0731-GGUF --include "UD-IQ4_NL/*" \
+   --local-dir ./models
+```
+
+### 4.2 建引擎
+
+```bash
+git clone https://github.com/ggml-org/llama.cpp && cd llama.cpp
+git checkout 836d57176dc699a726c55418e4f96b8ca628e1bf
+git apply ../sdq-dsv4/0001-sdq-llama-glue.patch          # llama.cpp 側的掛鉤
+cp ../sdq-dsv4/sdq_pager.h ../sdq-dsv4/sdq_pager.cpp \
+   ../sdq-dsv4/sdq_moe.cpp ../sdq-dsv4/sdq_buft.cpp \
+   ../sdq-dsv4/sdq_cli.cpp src/                          # SDQ 主體（直接覆蓋）
+git submodule update --init --recursive
+
+# ⚠️ AMX 必須關掉，原因見第 5 節 (e)
+cmake -B build -DCMAKE_BUILD_TYPE=Release -DLLAMA_CURL=OFF -DGGML_NATIVE=ON \
+      -DCMAKE_C_FLAGS="-mno-amx-int8 -mno-amx-tile -mno-amx-bf16" \
+      -DCMAKE_CXX_FLAGS="-mno-amx-int8 -mno-amx-tile -mno-amx-bf16"
+cmake --build build -j --target sdq-chat
+```
+
+### 4.3 跑（RAM 預算單位 MiB）
+
+```bash
+./build/bin/sdq-chat \
+  -m ./models/UD-IQ4_NL/DeepSeek-V4-Flash-0731-UD-IQ4_NL-00001-of-00004.gguf \
+  -p "The capital of France is" -n 48 -c 2048 -t 16 -b 128 --temp 0 \
+  --ram-budget-mb 8192 --no-interactive --stats-file /tmp/stats.jsonl
+```
+
+`--ram-budget-mb` 是**總 RAM 預算**（不是「還有多少可用」）：pager 會扣掉當下的
+RSS 與一份預留量（`SDQ_RESERVE_MB`，預設 900 MB）之後，剩下的才是 arena。
+
+重跑記憶體實驗：
+
+```bash
+python3 sdq-dsv4/memory_levels_dsv4.py \
+  --model ./models/UD-IQ4_NL/DeepSeek-V4-Flash-0731-UD-IQ4_NL-00001-of-00004.gguf \
+  --bin   ./llama.cpp/build/bin/sdq-chat \
+  --levels-gib 4 8 16 32 --repeat 2 --n-predict 48
+```
+
+---
+
+## 5. 改寫了什麼（以及踩到什麼坑）
+
+改寫基於 `HelloSun/Qwen3.8-Flash-Next-GGUF` 的 `sdq-qwen38/`，共 5 處必要修正。
+每一處都是「不改就跑不起來或跑錯」，不是風格調整。
+
+### (a) IQ3_S / MXFP4 的量化點積
+
+SDQ 的 `dot_for()` 只認 Q2_K…Q8_0 / Q4_0 / Q5_0 / Q5_1 / IQ4_NL / IQ4_XS。
+這個模型的 routed expert 是 **IQ3_S**（gate/up）與 **MXFP4**（down）→
+**每一層**都會印 `不支援的專家量化型別` 然後什麼都不算。
+
+**修正**：加上
+
+| 權重型別 | vec_dot | activation 型別 |
+|---|---|---|
+| `GGML_TYPE_IQ3_S` | `ggml_vec_dot_iq3_s_q8_K` | `GGML_TYPE_Q8_K` |
+| `GGML_TYPE_MXFP4` | `ggml_vec_dot_mxfp4_q8_0` | `GGML_TYPE_Q8_0` |
+
+配對不能自己猜，必須照 ggml 的 `type_traits`
+（`ggml/src/ggml-cpu/ggml-cpu.c`）：`IQ3_S.vec_dot_type = Q8_K`、
+`MXFP4.vec_dot_type = Q8_0`。特別注意 IQ3_S 落到 `default:` 會被配成 Q8_0，
+而它的 6-bit scale 組出來的值範圍大於 q8_0 的 ±127 —— 不改就是整層數值錯掉。
+
+### (b) `ggml_swiglu_clamp` 的夾法
+
+deepseek4（以及 glm5_next / maple / dflash / hy_v4）走的是 ggml 的融合算子
+`ggml_swiglu_clamp`（`ggml/src/ggml-cpu/ops.cpp`）：
+
+```c
+const float gate = std::min(src0_p[k], limit);              // 只夾上界
+const float up   = std::clamp(src1_p[k], -limit, limit);    // 對稱
+dst_p[k]         = gate / (1.f + expf(-gate)) * up;         // 夾在 silu 之前
+```
+
+SDQ 原版夾的是 **silu 之後** 的 gate、而且是對稱的：
+
+```c
+gc = clamp(silu(gate), -limit, limit);                     // 夾在 silu 之後、對稱
+out = gc * clamp(up, -limit, limit);
+```
+
+兩者不是同一個函式（夾的位置不同、gate 的邊界條件不同）。
+
+**修正**：把夾法做成參數 `sdq_build_moe(..., swiglu_limit, swiglu_mode)`，
+由 `build_moe_ffn()` 依 arch 決定（`0001-sdq-llama-glue.patch` 裡那段 switch
+就是照著 `LLM_FFN_SILU` 的分支寫的）。`deepseek4` 走
+`SDQ_SWIGLU_GGML_FUSED_CLAMP`。
+
+> 誠實補充：這個模型的 clamp 值是 **10.0**，而 `silu(x) ≤ x`，
+> 所以在 `g ≥ limit` 的區域兩種寫法只差 `silu(10) = 9.9999` 對 `10`
+> （約 0.001%），`g ≤ -limit` 的區域兩者都趨近 0。也就是說**這一項在這個模型上
+> 是 1e-4 等級的差異，不是災難**。仍然照上游寫是對的（正確的公式不該是
+> 「差不多對的公式」），但不要把它講成修了一個大 bug。
+
+### (c) shared expert 不進 arena（而且確認沒有被吃掉）
+
+`deepseek4` 每層有 **1 個 shared expert**（`expert_shared_count = 1`，
+`ffn_{gate,up,down}_shexp`）。SDQ 的 `build_moe_ffn()` 掛鉤是**提早 return**的
+——對 qwen4exp（沒有 shared expert）沒問題，對 deepseek4 就會把 shared expert
+整段跳過。
+
+檢查結果（`llama.cpp` `src/models/deepseek4.cpp`）：shared expert 是在
+`build_moe_ffn()` **之外**算的獨立在線
+
+```cpp
+ggml_tensor * moe_out = build_moe_ffn(...);           // ← SDQ 在這裡提早 return
+ggml_tensor * ffn_shexp = build_ffn(cur, layer.ffn_up_shexp, ..., il);
+cur = ggml_add(ctx0, moe_out, ffn_shexp);             // ← 兩邊都保留
+```
+
+`build_ffn()` 只用一般的 `ggml_mul_mat`（不是 `mul_mat_id`），所以提早 return
+不會影響它。SDQ 的 buffer override 正則
+`blk\.[0-9]+\.ffn_(gate|up|down|gate_up)_exps\.weight` 也**不會**誤配到
+`_shexp`（那裡要求後面接 `_exps.weight`）。
+
+這一項是「確認不用改」，但確認的過程比改動本身更花時間，所以把它寫下來。
+
+### (d) hash-routing 的前 3 層
+
+`hash_layer_count = 3`：前 3 層的 expert 選擇不是 `argsort_top_k` 算出來的，
+而是 `get_rows(ffn_gate_tid2eid, tokens)` 從一張 `[6, 129280]` 的查表得到
+（`src/models/deepseek4.cpp`）。這兩條路徑產生的 `ids` **形狀與型別完全相同**
+（`I32 [n_expert_used, n_tokens]`），SDQ 的 op 是照 `src[1]` 的 `nb[0]/nb[1]`
+讀的，所以不需要改。差異只在「有沒有 routing bias」，而 bias 是在 `ids` 之前
+由 ggml 圖算完的。
+
+### (e) AMX 必須關掉（否則 deepseek4 在這版 llama.cpp 上起不來）
+
+這不是 SDQ 的問題，是 llama.cpp `836d5717` 加上 AMX repack 時的問題：
+
+```
+ggml_backend_sched_split_graph: GGML_ASSERT(*cur_backend_id != -1) failed
+  unassigned node: op=MUL_MAT ne=[1024,128,8,1] name='attn_wo_a-0'
+    src[0] q8_0 buft=AMX
+    src[1] f32 name='attn_derope-0 (reshaped) (permuted)'   ← 非 contiguous
+```
+
+`ggml_backend_cpu_device_supports_op()` 在看到 src 落在 extra buffer type
+（AMX / REPACK）時會**直接**把決定權交給該 buffer type 的 `supports_op()`，
+而 AMX 的實作要求 `ggml_is_contiguous(src1)`。deepseek4 的
+`attn_output_a`（低秩輸出投影）拿到的是 de-rope 之後的 permute view，
+不 contiguous → AMX 回 false → 整個 op 沒有任何 backend 能接 → assert。
+
+本機 CPU 有 `amx_int8`/`amx_bf16`/`amx_tile`，而 `-march=native` 會直接定義
+`__AMX_INT8__`／`__AVX512VNNI__`，於是 AMX extra buffer type 被註冊。
+**修正**：編譯時加 `-mno-amx-int8 -mno-amx-tile -mno-amx-bf16`（見 4.2）。
+SDQ 本來就不走 repack（expert 權重根本不進 RAM），關掉 AMX 沒有損失。
+
+> 想自己重現這個 assert、又不想改編譯參數的話，
+> `sdq-dsv4/optional-sched-debug.patch` 可以在 assert 前印出真正沒被接走的節點。
+
+### (f) 從 qwen4exp 版本繼承、但這個模型也會踩到的兩個坑
+
+`sdq-qwen38/` 已經修好的兩件事，`deepseek4` 的 GGUF **一樣會踩到**，所以直接繼承：
+
+1. **GGUF kv 解析器的型別寬度**。DeepSeek 的 metadata 有 3 個 `U16`
+   （`split.no` / `split.tensors.count` / `split.count`），舊版 `sdq_pager.cpp`
+   把 `U8/I8/U16/I16` 都用 `u32()` 讀、且陣列元素遇到 `F64` 完全不消費位元組，
+   於是 header 整個錯位，症狀是
+   `[sdq] pager 初始化失敗：basic_string::_M_create`。
+2. **sharded GGUF**。這個模型是 4 個 shard，而且 **shard 1 是 metadata-only**
+   （`n_tensors = 0`，整個檔案就是 5.0 MiB 的 tokenizer），權重分散在 shard
+   2/3/4，每個 shard 有自己的 `data_start`。只讀 shard 1 → page map 全空；
+   把 4 個 shard 串起來卻共用第一個 shard 的 `data_start` → 每個 expert 讀到
+   錯開約 18 KB 的位置，**輸出是看似合理的亂碼**。
+
+---
+
+## 6. 正確性驗證
+
+### 6.1 dequant 逐位元組對照（獨立實作）
+
+`verify_moe_dsv4.py` 裡的 IQ3_S / MXFP4 還原是照 ggml 原始碼手寫的 NumPy。
+如果那份手寫有錯，後面所有「C++ kernel 對得上 NumPy」的結論都只是在
+一份錯誤的 reference 上自我一致。所以用 `ggml_deq`（直接呼叫 ggml 的 C 函式）
+當**第二份獨立實作**逐位元組比對：
+
+```bash
+c++ -O2 -o /tmp/ggml_deq sdq-dsv4/ggml_deq.cpp \
+    -I<llama.cpp>/ggml/include -I<llama.cpp>/ggml/src \
+    -L<llama.cpp>/build/bin -lggml-base -Wl,-rpath,<llama.cpp>/build/bin
+python3 sdq-dsv4/verify_dequant_dsv4.py
+```
+
+| 張量 | 型別 | max&#124;NumPy − ggml&#124; |
+|---|---|---:|
+| `blk.0.ffn_gate_exps` | IQ3_S | **0.0** |
+| `blk.0.ffn_up_exps` | IQ3_S | **0.0** |
+| `blk.0.ffn_down_exps` | MXFP4 | **0.0** |
+| `blk.26.ffn_gate_exps` | MXFP4 | **0.0** |
+| `blk.26.ffn_down_exps` | MXFP4 | **0.0** |
+
+21/21 列 **bit-exact**（差異精確為 0，不是「很小」）。
+
+### 6.2 整個 expert 前向對照
+
+`sdq-chat --selftest IL:IE:SEED:OUT.bin` 產出 C++ kernel 的結果，再用純 NumPy
+從 GGUF 的**同一段位元組**重算 SiLU-gated MoE 前向：
+
+```bash
+for spec in 0:7 1:7 2:123 3:255 12:7 25:7 26:7 27:7 41:7 42:7; do
+  il=${spec%%:*}; ie=${spec##*:}
+  ./build/bin/sdq-chat -m $MODEL --selftest "$il:$ie:1234:/tmp/st_l${il}e${ie}.bin:1" \
+      --selftest-limit 10 --selftest-mode 1 --ram-budget-mb 4096 --no-interactive
+done
+DSV4_LIMIT=10 DSV4_MODE=1 python3 sdq-dsv4/verify_moe_dsv4.py
+```
+
+| 層 | expert | gate/up | down | max 相對誤差 | 相關係數 | 結果 |
+|---:|---:|---|---|---:|---:|---|
+| 0 | 7 | iq3_s | mxfp4 | 0.0099 | 0.999945 | PASS |
+| 1 | 7 | iq3_s | mxfp4 | 0.0111 | 0.999949 | PASS |
+| 2 | 123 | iq3_s | mxfp4 | 0.0100 | 0.999950 | PASS |
+| 3 | 255 | iq3_s | mxfp4 | 0.0077 | 0.999948 | PASS |
+| 12 | 7 | iq3_s | mxfp4 | 0.0082 | 0.999950 | PASS |
+| 25 | 7 | iq3_s | mxfp4 | 0.0106 | 0.999941 | PASS |
+| **26** | 7 | **mxfp4** | mxfp4 | 0.0101 | 0.999947 | PASS |
+| 27 | 7 | iq3_s | mxfp4 | 0.0082 | 0.999949 | PASS |
+| 41 | 7 | iq3_s | mxfp4 | 0.0103 | 0.999942 | PASS |
+| 42 | 7 | iq3_s | mxfp4 | 0.0115 | 0.999948 | PASS |
+
+殘差是 **activation 量化誤差**（sdq 走 q8_K / q8_0 量化點積，參考實作走 fp32），
+量級 0.8–1.2%，不是結構性錯誤。layer 26 是唯一 gate/up 換成 MXFP4 的層，
+單獨列出來是因為它是 (a) 那個修正唯一的執行路徑。
+
+### 6.3 分頁結果與 arena 大小無關（bit-exact）
+
+`SDQ_MOE_DUMP` 會在 MoE op 真的算完的那一刻，把該次呼叫的**輸入與輸出**
+（`cur` / `ids` / `wts` / `out`）寫成一個二進位檔。同一個 prompt、同一組設定，
+只改 `--ram-budget-mb`：
+
+| 範圍 | 檔案數 | bit-identical |
+|---|---:|---:|
+| 4 GiB vs 32 GiB，**全部 43 層 × 9 次 op call**（1 次 prefill `n_tok=25` + 8 次 decode `n_tok=1`），含輸入與輸出 | 387 | **387 / 387** |
+
+hot/cold 比例、SSD 讀取量、槽位數（164 vs 2732）、淘汰次數全部不同，
+**但每一層每一個 token 的 MoE 輸入與輸出位元組完全一樣**。這是對「分頁有沒有偷偷
+改變數學」最直接的證據。逐檔 md5 見
+[`results/moe_dump_bitexact.md`](results/moe_dump_bitexact.md)。
+
+另外同一設定重跑 6 次、兩個 RAM 預算各 6 次，greedy（`--temp 0`）輸出
+**12/12 逐字相同**（`results/determinism.txt`）。
+
+### 6.4 誠實聲明：沒做的事，以及一個還沒解掉的問題
+
+**沒有做端到端 A/B**（SDQ 分頁路徑 vs 原生 `mul_mat_id` 逐 token 比對文字）。
+原因是這個模型在這台機器上沒辦法跑原生路徑 —— 原生路徑要把 127.27 GiB 權重
+全部載入 RSS，遠超單一子行程 64 GiB 的上限。6.1–6.3 是目前能取得的最強證據。
+
+**還沒解掉的問題：decode 期的 greedy 輸出對行程狀態敏感。**
+固定設定下重跑 6 次輸出 100% 逐字相同；但只要改動**與計算無關**的東西
+（`--stats-file`、`SDQ_STATS_FILE`、`SDQ_MOE_DUMP`、`SDQ_FADV_DONTNEED=0`、
+`SDQ_IO_SPLIT=2`、`-c`、`-b`），第一個 token 就會換。`-t 1`（完全單執行緒）
+也一樣會換，所以不是執行緒競爭。
+
+**而且分歧點已經定位到**：把兩種設定的 MoE dump 逐一比對（43 層 × 17 次 op call
+= 731 個檔案），**43 個 prefill 呼叫全部 bit-identical、688 個 decode 呼叫全部不同**
+（`results/moe_dump_bitexact.md` §B）。分歧已經出現在 MoE op 的**輸入** `cur` 裡，
+也就是說：
+
+* **不是 SDQ 的分頁或 kernel**（§6.3 已經證明分頁對數學是 bit-exact 的）；
+* 不是每個 expert 的請求數對不上 —— `expert_requests == expert_hits + expert_misses`
+  永遠成立，沒有任何 expert 被跳過（`acquire()` 拿不到槽位時是 `abort()`，
+  不是靜靜跳過）；
+* 是 llama.cpp `deepseek4` 的 **decode 期 dsv4 CSA/HCA 壓縮 KV state 路徑**，
+  在這兩種設定下算出了不同的 `cur`。SDQ 的 op 只是忠實地把它算下去。
+
+而且所有觀察到的變體**在語意上都是對的**（`capital of France is **Paris**.` /
+` Paris.` / `'m happy to help! The capital of France is **Paris**.`），
+這個 prompt 的 top-1/top-2 本來就非常接近。
+
+要真的定位到 llama.cpp 那一側，需要用 sanitizer build 重跑（prefill 一致、
+decode 不一致這個現象很適合用 MSan/valgrind 抓），本 repo 沒做到。
+這件事會影響任何想用這個 port 做 token 級 A/B 的人，所以寫在這裡。
+
+---
+
+## 7. 檔案
+
+```
+sdq-dsv4/
+  sdq_pager.h / sdq_pager.cpp   expert pager（sharded GGUF、修正後的 GGUF parser、大小兩種槽位）
+  sdq_moe.cpp                   自訂 MoE kernel（新增 IQ3_S/MXFP4、ggml_swiglu_clamp 語意）
+  sdq_buft.cpp                  讓 expert 權重不進 RAM 的假 buffer type
+  sdq_cli.cpp                   sdq-chat 前端（新增 --selftest-limit/-mode/-xscale）
+  ggml_deq.cpp                  抽 ggml dequant 結果的小工具（驗證用）
+  ggml_tables.py                從 ggml 原始碼抽出的 IQ3_S/MXFP4 常數表（由 gen_tables.py 產生）
+  gen_tables.py                 產生上面那個表的小工具
+  verify_dequant_dsv4.py        NumPy dequant vs ggml dequant，逐位元組
+  verify_moe_dsv4.py            expert 前向 vs 純 NumPy
+  memory_levels_dsv4.py         RAM 預算矩陣 runner
+  determinism_probe.sh          決定性探針（同一設定重跑 N 次比對輸出）
+  0001-sdq-llama-glue.patch     llama.cpp 側的掛鉤（build_moe_ffn / init_mappings / CMake）
+  optional-sched-debug.patch    選用：sched assert 前印出沒被接走的節點
+results/
+  memory_levels_dsv4-4-8-16-32g.json / .md   記憶體實驗（原始逐輪資料 + 表格）
+  verify_dequant.txt             NumPy dequant vs ggml dequant 的逐筆輸出（21/21 bit-exact）
+  verify_moe_forward.txt         expert 前向 vs 純 NumPy 的逐筆輸出（10/10 PASS）
+  moe_dump_bitexact.md           MoE op 的 bit-exact A/B（387/387 與分歧點定位）
+  determinism.txt                決定性探針（同一設定重跑 6 次 × 2 個預算）
+```
+
+### 重跑驗證
+
+```bash
+export DSV4_MODEL_DIR=./models/UD-IQ4_NL      # verify_moe_dsv4.py 的權重位置
+
+# (1) dequant bit-exact（需要先 build ggml_deq，見 6.1）
+python3 sdq-dsv4/verify_dequant_dsv4.py
+
+# (2) expert 前向（先跑 sdq-chat --selftest 產生 /tmp/st_l*e*.bin，見 6.2）
+DSV4_LIMIT=10 DSV4_MODE=1 python3 sdq-dsv4/verify_moe_dsv4.py
+
+# (3) MoE op bit-exact A/B（見 6.3 的 SDQ_MOE_DUMP 用法）
+bash sdq-dsv4/determinism_probe.sh 8192 32768
+```
+
+---
+
+## 8. 授權
+
+權重沿用 `unsloth/DeepSeek-V4-Flash-0731-GGUF` 的授權（`license: mit`，見上游）。
+本 repo 的程式碼沿用 SDQ 原專案
+（[`HelloSun/sddqwen35a3b_v01`](https://huggingface.co/HelloSun/sddqwen35a3b_v01)）
+與 [`HelloSun/Qwen3.8-Flash-Next-GGUF`](https://huggingface.co/HelloSun/Qwen3.8-Flash-Next-GGUF)
+的授權。

results/determinism.txt

@@ -0,0 +1,21 @@
+=== ram-budget 8192 MB × 6 ===
+  run 1: 0e637837ac89
+  run 2: 0e637837ac89
+  run 3: 0e637837ac89
+  run 4: 0e637837ac89
+  run 5: 0e637837ac89
+  run 6: 0e637837ac89
+  distinct outputs: 1 / 6
+          6 0e637837ac89d642578f9208f202dd0e
+=== ram-budget 32768 MB × 6 ===
+  run 1: 0e637837ac89
+  run 2: 0e637837ac89
+  run 3: 0e637837ac89
+  run 4: 0e637837ac89
+  run 5: 0e637837ac89
+  run 6: 0e637837ac89
+  distinct outputs: 1 / 6
+          6 0e637837ac89d642578f9208f202dd0e
+
+# 用法：bash sdq-dsv4/determinism_probe.sh 8192 32768
+# 內容：[levels] 每個 RAM 預算重跑 N 次，比對 greedy(--temp 0) 輸出的 md5。

results/memory_levels_dsv4-4-8-16-32g.json

@@ -0,0 +1,247 @@
+{
+  "model_id": "DeepSeek-V4-Flash-0731-UD-IQ4_NL",
+  "model_repo": "unsloth/DeepSeek-V4-Flash-0731-GGUF",
+  "model_subdir": "UD-IQ4_NL",
+  "architecture": "deepseek4",
+  "shards": 4,
+  "model_bytes": 136662446656,
+  "host": {
+    "cpu_model": "Intel(R) Xeon(R) Platinum 8559C",
+    "cpu_threads": 192,
+    "mem_total_bytes": 2147448086528
+  },
+  "method": "RAM budget passed to the SDQ expert pager arena sizing; no hard cgroup limit (host /sys/fs/cgroup is read-only). Page cache dropped before each run where permitted.",
+  "settings": {
+    "levels_gib": [
+      4,
+      8,
+      16,
+      32
+    ],
+    "repeat": 2,
+    "ctx": 2048,
+    "ubatch": 128,
+    "threads": 16,
+    "n_predict": 48,
+    "reserve_mb": 2048,
+    "temp": 0
+  },
+  "results": [
+    {
+      "level_mb": 4096,
+      "level_gib": 4,
+      "repeat": 1,
+      "prompt": "The capital of France is",
+      "wall_s": 81.51,
+      "decode_tok_s": 0.69,
+      "decode_tok": 47,
+      "prefill_tok_s": 1.6,
+      "prefill_tok": 22,
+      "peak_rss_mb": 2233,
+      "final_rss_mb": 2233,
+      "vmswap_mb": 0,
+      "arena_gib": 1.79,
+      "n_slots": 164,
+      "total_ssd_gb": 158.73,
+      "decode_ssd_mb": 138385.1,
+      "ssd_mb_per_token": 2944.4,
+      "expert_requests": 14548,
+      "expert_hits": 0,
+      "hot_rate_pct": 0,
+      "cold_rate_pct": 100.0,
+      "evictions": 14384,
+      "per_layer_hit_min": 0,
+      "per_layer_hit_max": 0,
+      "assistant": "'m happy to help! The capital of France is **Paris**.<｜end▁of▁sentence｜> of * {@link com.google.api.client.util.Data#nullOf(Class)} <code>@JsonTag(true)</code>. */ public"
+    },
+    {
+      "level_mb": 4096,
+      "level_gib": 4,
+      "repeat": 2,
+      "prompt": "請用一句話說明什麼是 SSD 快取。",
+      "wall_s": 84.54,
+      "decode_tok_s": 0.69,
+      "decode_tok": 47,
+      "prefill_tok_s": 1.7,
+      "prefill_tok": 29,
+      "peak_rss_mb": 2233,
+      "final_rss_mb": 2233,
+      "vmswap_mb": 0,
+      "arena_gib": 1.79,
+      "n_slots": 164,
+      "total_ssd_gb": 164.89,
+      "decode_ssd_mb": 138390.9,
+      "ssd_mb_per_token": 2944.5,
+      "expert_requests": 15113,
+      "expert_hits": 0,
+      "hot_rate_pct": 0,
+      "cold_rate_pct": 100.0,
+      "evictions": 14949,
+      "per_layer_hit_min": 0,
+      "per_layer_hit_max": 0,
+      "assistant": "SSD 快取是將固態硬碟作為高速暫存區，用來加速頻繁存取的資料，以提升整體系統效能。<｜end▁of▁sentence｜> of * {@link com.google.api.client.util.Data#nullOf"
+    },
+    {
+      "level_mb": 8192,
+      "level_gib": 8,
+      "repeat": 1,
+      "prompt": "The capital of France is",
+      "wall_s": 50.83,
+      "decode_tok_s": 1.34,
+      "decode_tok": 47,
+      "prefill_tok_s": 1.6,
+      "prefill_tok": 22,
+      "peak_rss_mb": 6325,
+      "final_rss_mb": 6325,
+      "vmswap_mb": 0,
+      "arena_gib": 5.79,
+      "n_slots": 531,
+      "total_ssd_gb": 93.15,
+      "decode_ssd_mb": 71237.8,
+      "ssd_mb_per_token": 1515.7,
+      "expert_requests": 14548,
+      "expert_hits": 6005,
+      "hot_rate_pct": 41.2772,
+      "cold_rate_pct": 58.7228,
+      "evictions": 8012,
+      "per_layer_hit_min": 3.40314,
+      "per_layer_hit_max": 55.1829,
+      "assistant": "'m happy to help! The capital of France is **Paris**.<｜end▁of▁sentence｜> of * {@link com.google.api.client.util.Data#nullOf(Class)} <code>@JsonTag(true)</code>. */ public"
+    },
+    {
+      "level_mb": 8192,
+      "level_gib": 8,
+      "repeat": 2,
+      "prompt": "請用一句話說明什麼是 SSD 快取。",
+      "wall_s": 51.64,
+      "decode_tok_s": 1.46,
+      "decode_tok": 47,
+      "prefill_tok_s": 1.7,
+      "prefill_tok": 29,
+      "peak_rss_mb": 6325,
+      "final_rss_mb": 6325,
+      "vmswap_mb": 0,
+      "arena_gib": 5.79,
+      "n_slots": 531,
+      "total_ssd_gb": 93.42,
+      "decode_ssd_mb": 65207.4,
+      "ssd_mb_per_token": 1387.4,
+      "expert_requests": 15113,
+      "expert_hits": 6544,
+      "hot_rate_pct": 43.3005,
+      "cold_rate_pct": 56.6995,
+      "evictions": 8038,
+      "per_layer_hit_min": 3.65854,
+      "per_layer_hit_max": 60.8696,
+      "assistant": "SSD 快取是將固態硬碟作為高速暫存區，用來加速頻繁存取的資料，以提升整體系統效能。<｜end▁of▁sentence｜> of * {@link com.google.api.client.util.Data#nullOf"
+    },
+    {
+      "level_mb": 16384,
+      "level_gib": 16,
+      "repeat": 1,
+      "prompt": "The capital of France is",
+      "wall_s": 53.29,
+      "decode_tok_s": 1.48,
+      "decode_tok": 47,
+      "prefill_tok_s": 1.7,
+      "prefill_tok": 22,
+      "peak_rss_mb": 14508,
+      "final_rss_mb": 14508,
+      "vmswap_mb": 0,
+      "arena_gib": 13.79,
+      "n_slots": 1264,
+      "total_ssd_gb": 72.95,
+      "decode_ssd_mb": 50553.8,
+      "ssd_mb_per_token": 1075.6,
+      "expert_requests": 14548,
+      "expert_hits": 7856,
+      "hot_rate_pct": 54.0005,
+      "cold_rate_pct": 45.9995,
+      "evictions": 5428,
+      "per_layer_hit_min": 14.6597,
+      "per_layer_hit_max": 65.8307,
+      "assistant": "'m happy to help! The capital of France is **Paris**.<｜end▁of▁sentence｜> of * {@link com.google.api.client.util.Data#nullOf(Class)} <code>@JsonTag(true)</code>. */ public"
+    },
+    {
+      "level_mb": 16384,
+      "level_gib": 16,
+      "repeat": 2,
+      "prompt": "請用一句話說明什麼是 SSD 快取。",
+      "wall_s": 51.28,
+      "decode_tok_s": 1.78,
+      "decode_tok": 47,
+      "prefill_tok_s": 1.8,
+      "prefill_tok": 29,
+      "peak_rss_mb": 14508,
+      "final_rss_mb": 14508,
+      "vmswap_mb": 0,
+      "arena_gib": 13.79,
+      "n_slots": 1264,
+      "total_ssd_gb": 74.17,
+      "decode_ssd_mb": 45496.1,
+      "ssd_mb_per_token": 968.0,
+      "expert_requests": 15113,
+      "expert_hits": 8310,
+      "hot_rate_pct": 54.9858,
+      "cold_rate_pct": 45.0142,
+      "evictions": 5539,
+      "per_layer_hit_min": 15.6098,
+      "per_layer_hit_max": 65.8824,
+      "assistant": "SSD 快取是將固態硬碟作為高速暫存區，用來加速頻繁存取的資料，以提升整體系統效能。<｜end▁of▁sentence｜> of * {@link com.google.api.client.util.Data#nullOf"
+    },
+    {
+      "level_mb": 32768,
+      "level_gib": 32,
+      "repeat": 1,
+      "prompt": "The capital of France is",
+      "wall_s": 56.38,
+      "decode_tok_s": 1.86,
+      "decode_tok": 47,
+      "prefill_tok_s": 1.8,
+      "prefill_tok": 22,
+      "peak_rss_mb": 30894,
+      "final_rss_mb": 30894,
+      "vmswap_mb": 0,
+      "arena_gib": 29.79,
+      "n_slots": 2732,
+      "total_ssd_gb": 55.16,
+      "decode_ssd_mb": 32330.6,
+      "ssd_mb_per_token": 687.9,
+      "expert_requests": 14548,
+      "expert_hits": 9491,
+      "hot_rate_pct": 65.2392,
+      "cold_rate_pct": 34.7608,
+      "evictions": 2325,
+      "per_layer_hit_min": 36.911,
+      "per_layer_hit_max": 75.7669,
+      "assistant": "<｜end▁of▁sentence｜> of * {@link com.google.api.client.util.Data#nullOf(Class)} <code>@JsonTag(true)</code>. */ public boolean isJsonTag() { Object value = get(\"json"
+    },
+    {
+      "level_mb": 32768,
+      "level_gib": 32,
+      "repeat": 2,
+      "prompt": "請用一句話說明什麼是 SSD 快取。",
+      "wall_s": 65.23,
+      "decode_tok_s": 1.56,
+      "decode_tok": 47,
+      "prefill_tok_s": 1.8,
+      "prefill_tok": 29,
+      "peak_rss_mb": 30894,
+      "final_rss_mb": 30894,
+      "vmswap_mb": 0,
+      "arena_gib": 29.79,
+      "n_slots": 2732,
+      "total_ssd_gb": 61.57,
+      "decode_ssd_mb": 32592.8,
+      "ssd_mb_per_token": 693.5,
+      "expert_requests": 15113,
+      "expert_hits": 9466,
+      "hot_rate_pct": 62.6348,
+      "cold_rate_pct": 37.3652,
+      "evictions": 2915,
+      "per_layer_hit_min": 27.8049,
+      "per_layer_hit_max": 70.5706,
+      "assistant": "SSD 快取是將固態硬碟作為高速暫存區，用來加速頻繁存取的資料，以提升整體系統效能。<｜end▁of▁sentence｜> of * {@link com.google.api.client.util.Data#nullOf"
+    }
+  ]
+}

results/memory_levels_dsv4-4-8-16-32g.md

@@ -0,0 +1,34 @@
+# RAM 預算矩陣：dsv4-4-8-16-32g
+
+RAM budget passed to the SDQ expert pager arena sizing; no hard cgroup limit (host /sys/fs/cgroup is read-only). Page cache dropped before each run where permitted.
+
+- Host: Intel(R) Xeon(R) Platinum 8559C, 192 threads（實驗以 `-t 16` 跑）
+- ctx=2048, ubatch=128, threads=16, output tokens=48, temp=0, repeats=2
+- KV/SSM state + compute reserve: 2048 MB
+- 磁碟：overlay filesystem，單流 `dd oflag=direct` 寫 1.1 GB/s、讀 2.0 GB/s
+
+| RAM budget | arena (GiB) | slots | decode tok/s | prefill tok/s | hot % | cold % | SSD MiB/tok | total SSD read | peak RSS (MB) | swap | per-layer hit min..max |
+|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| 4 GiB | 1.79 | 164 | 0.69 | 1.65 | 0.0 | 100.0 | 2944.4 | 161.8 GB | 2233 | 0 MB | 0.0..0.0 |
+| 8 GiB | 5.79 | 531 | 1.40 | 1.65 | 42.3 | 57.7 | 1451.6 | 93.3 GB | 6325 | 0 MB | 3.5..58.0 |
+| 16 GiB | 13.79 | 1264 | 1.63 | 1.75 | 54.5 | 45.5 | 1021.8 | 73.6 GB | 14508 | 0 MB | 15.1..65.9 |
+| 32 GiB | 29.79 | 2732 | 1.71 | 1.80 | 63.9 | 36.1 | 690.7 | 58.4 GB | 30894 | 0 MB | 32.4..73.2 |
+
+## 怎麼讀這張表
+
+* `hot %` = expert 已經在 RAM arena、不需要碰 SSD；`cold %` = 必須回 SSD `pread`。
+* 4 GiB 那一級的 `hot = 0%` 不是 bug：一個 token 在 43 層各用 6 個 expert，
+  工作集下限就是 43 × 6 = 258 個 expert ≈ 2.8 GiB，而這一級的 arena 只有 1.79 GiB
+  → 任何一次請求都必然是 miss。
+* 32 GiB 比 4 GiB：SSD 讀取量降到 23.5%、decode 速度 2.48×。
+* 每層命中率在 4 GiB 下是 0..0，8 GiB 下拉開到 3.5..58.0：arena 是全層共用的
+  單一槽位池、沒有 per-layer 配額，前段層要的 expert 量又最大，於是被其他層擠掉。
+  這是原版 SDQ `docs/10` 記錄的同一個問題，在 256 experts/層的規模下更明顯。
+* **RAM 預算是 pager budget，不是 OS 硬性限額**：本機 `/sys/fs/cgroup` 唯讀，
+  沒辦法為每一級建立獨立的 cgroup 限額，所以 4/8/16/32 GiB 是「把預算交給 pager
+  去算 arena 大小」，不是四個各自受限的容器。各級的實際 peak RSS 都如實列出。
+* swap 全程 0 MB：SDQ 不用 swap，所有權重資料只存在 arena（實體 RAM）與檔案（SSD）兩處。
+* tok/s 與 RAM/SSD/CPUs 綁定，不可跨機器移植；hot/cold 比例與 arena 大小的關係則是
+  模型與工作負載的性質。
+
+JSON: `memory_levels_dsv4-4-8-16-32g.json`

results/moe_dump_bitexact.md

@@ -0,0 +1,68 @@
+### SDQ MoE op 的 bit-exact A/B
+
+`SDQ_MOE_DUMP=<prefix> SDQ_MOE_DUMP_LAYER=<il|-1>` 會在 MoE op 真的算完的那一刻，
+把該次呼叫的 **輸入與輸出** 全部寫成一個二進位檔：
+
+```
+prefix.<layer>.<全域 op 序號>
+  int32 meta[6] = n_embd, n_tok, n_expert_used, n_expert, 1, 2
+  float  cur[n_embd * n_tok]        ← ffn_norm 之後、進 MoE 的 activation
+  int32  ids[n_expert_used * n_tok] ← 路由結果
+  float  wts[n_expert_used * n_tok] ← 加權（含 norm 與 ×1.5）
+  float  out[n_embd * n_tok]        ← MoE 輸出（未加權前的加權累加結果）
+```
+
+因為 `cur` / `ids` / `wts` 也在裡面，所以這個檔案同時回答兩個問題：
+**分頁有沒有改變數學**（比較不同 RAM 預算），以及
+**上游有沒有改變數學**（比較 `cur` 本身）。
+
+---
+
+## A) 只改 RAM 預算（4 GiB vs 32 GiB）→ 每一層、每一次呼叫都 bit-identical
+
+prompt `Explain mixture-of-experts routing in one sentence.`，`-n 8`，
+`ctx=2048, ubatch=128, -t 16, temp=0`。兩邊各有 43 層 × 9 次 op call
+（1 次 prefill `n_tok=25` + 8 次 decode `n_tok=1`）。
+
+| 範圍 | 檔案數 | bit-identical |
+|---|---:|---:|
+| 全部 43 層 × 9 次 op call（含 `cur`/`ids`/`wts`/`out`） | 387 | **387** |
+
+hot/cold 比例、SSD 讀取量、槽位數（164 vs 2732）、淘汰次數全部不同，
+**但每一層每一個 token 的 MoE 輸入與輸出位元組完全一樣**。
+
+layer 20 的逐檔 md5：
+
+| op call | n_tok | md5 (4 GiB) | md5 (32 GiB) | identical |
+|---:|---:|---|---|---|
+| 0 | 25 | `7c38176f802c` | `7c38176f802c` | YES |
+| 1 | 1 | `43a5b24998b8` | `43a5b24998b8` | YES |
+| 2 | 1 | `2a4d28226b9d` | `2a4d28226b9d` | YES |
+| 3 | 1 | `ef3fcc0ffd1a` | `ef3fcc0ffd1a` | YES |
+| 4 | 1 | `487ebb0fc854` | `487ebb0fc854` | YES |
+
+---
+
+## B) 開 `--stats-file` → prefill 相同、decode 全數不同
+
+同樣的模型與設定，只多一個 `--stats-file`（它會讓 sdq-chat 設
+`cparams.offload_kqv = false`，並且每輪 decode 後寫一行 JSON）。
+prompt `The capital of France is`，`-n 16`。
+
+| 範圍 | 檔案數 | bit-identical |
+|---|---:|---:|
+| 43 次 **prefill**（seq = 層號，也就是每層的第 0 次 op call） | 43 | **43** |
+| 43 層 × 16 次 **decode** | 688 | **0** |
+
+比對方式：把 `with/d.*` 與 `without/d.*` 逐一 `cmp`。
+完全相同的 43 個檔案剛好就是每層的 prefill 那一次（`d.0.0`、`d.1.1`、
+`d.2.2` … `d.42.42`）—— 這是比對方法自己選出來的，不是人工挑的。
+
+**這把問題定位得很清楚**：prefill（含 prompt 的全部 attention）完全一致，
+分歧是從 **decode** 開始的，而且分歧已經出現在 MoE op 的**輸入** `cur` 裡。
+也就是說：不是 SDQ 的分頁或 kernel 改變了數學，而是
+llama.cpp `deepseek4` 的 decode 期 dsv4 CSA/HCA 壓縮 KV state 路徑
+在這兩種設定下算出不同的 `cur`，SDQ 的 op 只是忠實地把它算下去。
+
+同一個設定重跑 6 次，輸出 100% 逐字相同（見 `determinism.txt`），
+所以這不是「隨機」而是「對行程狀態敏感」。細節與還沒做的事見 README 第 6.4 節。

results/verify_dequant.txt

@@ -0,0 +1,25 @@
+### dequant bit-exactness ###
+blk.0.ffn_gate_exps.weight         type=21 row=0     max|NumPy - ggml| = 0  EXACT
+blk.0.ffn_gate_exps.weight         type=21 row=1     max|NumPy - ggml| = 0  EXACT
+blk.0.ffn_gate_exps.weight         type=21 row=137   max|NumPy - ggml| = 0  EXACT
+blk.0.ffn_up_exps.weight           type=21 row=0     max|NumPy - ggml| = 0  EXACT
+blk.0.ffn_up_exps.weight           type=21 row=1     max|NumPy - ggml| = 0  EXACT
+blk.0.ffn_up_exps.weight           type=21 row=137   max|NumPy - ggml| = 0  EXACT
+blk.0.ffn_down_exps.weight         type=39 row=0     max|NumPy - ggml| = 0  EXACT
+blk.0.ffn_down_exps.weight         type=39 row=1     max|NumPy - ggml| = 0  EXACT
+blk.0.ffn_down_exps.weight         type=39 row=137   max|NumPy - ggml| = 0  EXACT
+blk.0.ffn_down_exps.weight         type=39 row=0     max|NumPy - ggml| = 0  EXACT
+blk.0.ffn_down_exps.weight         type=39 row=1     max|NumPy - ggml| = 0  EXACT
+blk.0.ffn_down_exps.weight         type=39 row=137   max|NumPy - ggml| = 0  EXACT
+blk.26.ffn_down_exps.weight        type=39 row=0     max|NumPy - ggml| = 0  EXACT
+blk.26.ffn_down_exps.weight        type=39 row=1     max|NumPy - ggml| = 0  EXACT
+blk.26.ffn_down_exps.weight        type=39 row=137   max|NumPy - ggml| = 0  EXACT
+blk.26.ffn_gate_exps.weight        type=39 row=0     max|NumPy - ggml| = 0  EXACT
+blk.26.ffn_gate_exps.weight        type=39 row=1     max|NumPy - ggml| = 0  EXACT
+blk.26.ffn_gate_exps.weight        type=39 row=137   max|NumPy - ggml| = 0  EXACT
+blk.26.ffn_down_exps.weight        type=39 row=0     max|NumPy - ggml| = 0  EXACT
+blk.26.ffn_down_exps.weight        type=39 row=1     max|NumPy - ggml| = 0  EXACT
+blk.26.ffn_down_exps.weight        type=39 row=137   max|NumPy - ggml| = 0  EXACT
+
+21/21 bit-exact
+ALL BIT-EXACT

results/verify_moe_forward.txt

@@ -0,0 +1,18 @@
+### expert forward vs NumPy ###
+model  = DeepSeek-V4-Flash-0731-UD-IQ4_NL-00001-of-00004.gguf
+arch   = deepseek4  n_layer=43  n_expert=256  n_used=6  n_embd=4096  n_ff=2048
+swiglu = limit=10 mode=1 (ggml_swiglu_clamp)
+
+L0  E7   gate=iq3_s  up=iq3_s  down=mxfp4  | max_rel_err= 0.0099 corr=0.999945 | PASS
+L1  E7   gate=iq3_s  up=iq3_s  down=mxfp4  | max_rel_err= 0.0111 corr=0.999949 | PASS
+L2  E123 gate=iq3_s  up=iq3_s  down=mxfp4  | max_rel_err= 0.0100 corr=0.999950 | PASS
+L3  E255 gate=iq3_s  up=iq3_s  down=mxfp4  | max_rel_err= 0.0077 corr=0.999948 | PASS
+L12 E7   gate=iq3_s  up=iq3_s  down=mxfp4  | max_rel_err= 0.0082 corr=0.999950 | PASS
+L25 E7   gate=iq3_s  up=iq3_s  down=mxfp4  | max_rel_err= 0.0106 corr=0.999941 | PASS
+L26 E7   gate=mxfp4  up=mxfp4  down=mxfp4  | max_rel_err= 0.0101 corr=0.999947 | PASS
+L27 E7   gate=iq3_s  up=iq3_s  down=mxfp4  | max_rel_err= 0.0082 corr=0.999949 | PASS
+L41 E7   gate=iq3_s  up=iq3_s  down=mxfp4  | max_rel_err= 0.0103 corr=0.999942 | PASS
+L42 E7   gate=iq3_s  up=iq3_s  down=mxfp4  | max_rel_err= 0.0115 corr=0.999948 | PASS
+
+10/10 PASS
+ALL PASS

sdq-dsv4/0001-sdq-llama-glue.patch

@@ -0,0 +1,216 @@
+diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
+index afdaddc..4d8bc7a 100644
+--- a/src/CMakeLists.txt
++++ b/src/CMakeLists.txt
+@@ -18,6 +18,9 @@ set(LLAMA_CORE_SOURCES
+     llama-cparams.cpp
+     llama-grammar.cpp
+     llama-graph.cpp
++    sdq_pager.cpp
++    sdq_buft.cpp
++    sdq_moe.cpp
+     llama-hparams.cpp
+     llama-impl.cpp
+     llama-io.cpp
+@@ -50,6 +53,11 @@ add_library(llama
+             ${LLAMA_MODELS_SOURCES}
+             )
+ 
++# SDQ: 聊天 / benchmark 主程式（只依賴 llama + ggml）
++add_executable(sdq-chat sdq_cli.cpp)
++target_link_libraries(sdq-chat PRIVATE llama)
++target_include_directories(sdq-chat PRIVATE .)
++
+ set_target_properties(llama PROPERTIES
+     VERSION ${LLAMA_VERSION_BASE}
+     SOVERSION ${LLAMA_VERSION_MAJOR}
+@@ -59,12 +67,16 @@ set_target_properties(llama PROPERTIES
+ )
+ 
+ # exclude non-model sources from unity build
++# SDQ: 我們的檔案必須獨立編譯（會 include ggml 內部標頭，且有 static 符號）
+ set_source_files_properties(${LLAMA_CORE_SOURCES} ../include/llama.h unicode.h
++    sdq_pager.cpp sdq_buft.cpp sdq_moe.cpp
+     PROPERTIES SKIP_UNITY_BUILD_INCLUSION ON)
+ 
+ configure_file(llama-version.h.in ${CMAKE_CURRENT_BINARY_DIR}/llama-version.h @ONLY)
+ 
+ target_include_directories(llama PRIVATE . ${CMAKE_CURRENT_BINARY_DIR})
++# SDQ: 需要 ggml 的內部標頭（自訂 buffer type + 量化點積 kernel）
++target_include_directories(llama PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../ggml/src)
+ target_include_directories(llama PUBLIC ../include)
+ target_compile_features   (llama PRIVATE cxx_std_17) # don't bump
+ 
+diff --git a/src/llama-context.cpp b/src/llama-context.cpp
+index 96b5464..95026cd 100644
+--- a/src/llama-context.cpp
++++ b/src/llama-context.cpp
+@@ -4,6 +4,9 @@
+ #include "llama-arch.h"
+ #include "llama-graph.h"
+ #include "llama-impl.h"
++
++// SDQ-0005
++#include "sdq_pager.h"
+ #include "llama-batch.h"
+ #include "llama-io.h"
+ #include "llama-memory.h"
+@@ -2106,6 +2109,15 @@ int llama_context::decode(const llama_batch_ext & batch_inp) {
+     // wait for the computation to finish (automatically done when obtaining the model output)
+     //synchronize();
+ 
++    // ---- SDQ-0005: close out the pager's per-token accounting.
++    // 0001 called pager::end_token() (and dump_stats) from sdq-chat's main() only,
++    // so on the llama-server path the token counter never advanced, SDQ_STATS_FILE
++    // stayed empty, and the prefetch history was never updated. Phase 0 needs these
++    // numbers on whichever front end is actually being used.
++    if (sdq::sdq_enabled()) {
++        sdq::sdq_on_decode((int) n_tokens_all);
++    }
++
+     return 0;
+ }
+ 
+diff --git a/src/llama-graph.cpp b/src/llama-graph.cpp
+index 16a3ed2..92ce54d 100644
+--- a/src/llama-graph.cpp
++++ b/src/llama-graph.cpp
+@@ -1,5 +1,7 @@
+ #include "llama-graph.h"
+ 
++#include "sdq_pager.h"
++
+ #include "llama-impl.h"
+ #include "llama-model.h"
+ #include "llama-batch.h"
+@@ -2172,6 +2174,51 @@ ggml_tensor * llm_graph_context::build_moe_ffn(
+     //call early so that topk-moe can be used
+     ggml_build_forward_expand(gf, weights);
+ 
++    // SDQ expert pager：專家權重不放在 RAM，改由 SSD→RAM arena 分頁。
++    // 路由（logits/softmax/top-k/權重正規化）仍由 ggml 算完，這裡只接手
++    // 「把被選到的 n_expert_used 個 expert 算出來並加權求和」這一段。
++    // SDQ debug: dump MoE inputs for a given layer (works on both paths)
++    if (const char * dp = getenv("SDQ_GRAPH_DUMP")) {
++        const int dl = getenv("SDQ_GRAPH_DUMP_LAYER") ? atoi(getenv("SDQ_GRAPH_DUMP_LAYER")) : -1;
++        if (dl < 0 || il == dl) {
++            ggml_tensor * c3 = ggml_reshape_3d(ctx0, cur, n_embd, 1, n_tokens);
++            ggml_build_forward_expand(gf, c3);
++            ggml_build_forward_expand(gf, selected_experts);
++            ggml_build_forward_expand(gf, weights);
++            std::string path = std::string(dp) + "." + std::to_string(il);
++            FILE * f = fopen(path.c_str(), "wb");
++            if (f) {
++                const int32_t meta[8] = { (int32_t) n_embd, (int32_t) n_tokens, (int32_t) n_expert_used,
++                                          (int32_t) n_expert, (int32_t) (sdq::sdq_pager_active_for_layer(il) ? 1 : 0), 0, 0, 0 };
++                fwrite(meta, sizeof(int32_t), 8, f);
++                fwrite(c3->data, sizeof(float), (size_t) (n_embd * n_tokens), f);
++                fwrite(selected_experts->data, sizeof(int32_t), (size_t) (n_expert_used * n_tokens), f);
++                fwrite(weights->data, sizeof(float), (size_t) (n_expert_used * n_tokens), f);
++                fclose(f);
++            }
++        }
++    }
++
++    if (sdq::sdq_pager_active_for_layer(il) && cur->ne[0] == n_embd) {
++        const float swiglu_limit = il >= 0 ? hparams.swiglu_clamp_exp[il] : 0.0f;
++        // SDQ-DeepSeek-V4：clamp 語意必須跟上游一致。
++        // deepseek4 / glm5_next / maple 走的是 ggml_swiglu_clamp（只夾 gate 的上界、
++        // 夾在 silu **之前**）；其他 arch 走的是「夾 silu 之後的 gate、對稱夾」。
++        // 兩條數學式子不等價，用錯會讓每一層的數值都偏掉。
++        // 對照：src/llama-graph.cpp 裡 LLM_FFN_SILU 的 switch。
++        const int swiglu_mode =
++            (arch == LLM_ARCH_DEEPSEEK4 || arch == LLM_ARCH_GLM5_NEXT || arch == LLM_ARCH_MAPLE ||
++             (arch == LLM_ARCH_DFLASH && hparams.dsv4_hc_mult > 0) || arch == LLM_ARCH_HY_V4)
++                ? sdq::SDQ_SWIGLU_GGML_FUSED_CLAMP
++                : sdq::SDQ_SWIGLU_LEGACY_POST_SILU;
++        ggml_tensor * moe_out = sdq::sdq_build_moe(gf, ctx0, cur, selected_experts, weights, il,
++                n_expert, n_expert_used, swiglu_limit, swiglu_mode);
++        cb(moe_out, "ffn_moe_out", il);
++        // 除錯/驗證：把分頁路徑的 MoE 輸入/輸出 dump 出來，與原生路徑做 A/B 對照
++        moe_out = sdq::sdq_maybe_dump_tensor(ctx0, moe_out, il);
++        return moe_out;
++    }
++
+     cur = ggml_reshape_3d(ctx0, cur, n_embd, 1, n_tokens);
+ 
+     if (weight_before_ffn) {
+@@ -2373,6 +2420,9 @@ ggml_tensor * llm_graph_context::build_moe_ffn(
+ 
+     cb(moe_out, "ffn_moe_out", il);
+ 
++    // 除錯/驗證：原生路徑也 dump 同一層，讓兩邊可以直接比對
++    moe_out = sdq::sdq_maybe_dump_tensor(ctx0, moe_out, il);
++
+     return moe_out;
+ }
+ 
+diff --git a/src/llama-model.cpp b/src/llama-model.cpp
+index 97e0cee..0b38431 100644
+--- a/src/llama-model.cpp
++++ b/src/llama-model.cpp
+@@ -1,5 +1,7 @@
+ #include "llama-model.h"
+ 
++#include "sdq_pager.h"
++
+ #include "llama-arch.h"
+ #include "llama-ext.h"
+ #include "llama-hparams.h"
+@@ -1811,7 +1813,9 @@ bool llama_model_base::load_tensors(llama_model_loader & ml) {
+     // per-tensor activation precision policy
+     prec_policy.load(ml, *this);
+ 
+-    ml.init_mappings(true, use_mlock ? &pimpl->mlock_mmaps : nullptr);
++    // SDQ: expert 權重由 pager 自己用 pread 管理，不該讓 kernel 把整個 22 GB
++    // 檔案 MAP_POPULATE / WILLNEED 進 page cache —— 那會讓 RAM 帳目失真。
++    ml.init_mappings(!sdq::sdq_enabled(), use_mlock ? &pimpl->mlock_mmaps : nullptr);
+     pimpl->mappings.reserve(ml.mappings.size());
+ 
+     // create the backend buffers
+diff --git a/src/llama.cpp b/src/llama.cpp
+index 9beb148..555a183 100644
+--- a/src/llama.cpp
++++ b/src/llama.cpp
+@@ -11,6 +11,9 @@
+ #include "llama-model-saver.h"
+ #include "llama-model.h"
+ 
++// SDQ: expert pager（見 patches/0002-sdq-server-hook.patch）
++#include "sdq_pager.h"
++
+ #include "ggml.h"
+ #include "ggml-cpp.h"
+ #include "ggml-backend.h"
+@@ -404,6 +407,31 @@ static struct llama_model * llama_model_load_from_file_impl(
+     // TODO: remove
+     ggml_time_init();
+ 
++    // ---- SDQ: 把 expert 權重交給 pager（SSD -> RAM arena 分頁）----
++    // 0001 只在 sdq-chat 的 main() 裡呼叫 sdq_install_buft_overrides()，所以
++    // llama-server / llama-cli 都不會啟用分頁，會直接把 22.1 GB 權重全部讀進 RAM。
++    // 這裡在模型載入的唯一入口補上，行為與 sdq-chat 一致。
++    //
++    // 開關：SDQ_PAGER=0 關閉（回到上游行為，適合 A/B 對照）。
++    // 參數沿用 sdq-chat 的那組環境變數：SDQ_ARENA_MB / SDQ_RAM_BUDGET_MB /
++    // SDQ_RESERVE_MB / SDQ_PREFETCH / SDQ_IO_PARALLEL / SDQ_IO_THREADS ...
++    const char * sdq_off = getenv("SDQ_PAGER");
++    if (!sdq_off || strcmp(sdq_off, "0") != 0) {
++        if (!params.vocab_only && !path_model.empty()) {
++            if (sdq::sdq_init(path_model)) {
++                // SDQ-0005: 0001 用 sdq_enabled() 讓 load_tensors 跳過
++                // MAP_POPULATE / WILLNEED，但 sdq_set_enabled(true) 只在
++                // sdq_cli.cpp 的 main() 裡被呼叫。少了這一行，非 sdq-chat 的前端
++                // （llama-server）分頁雖然有生效，init_mappings() 卻拿到 true，
++                // 整個 22 GB 檔案還是會被要求預取進 page cache —— 正是 0001 要避免的。
++                sdq::sdq_set_enabled(true);
++                sdq::sdq_install_buft_overrides(&params);
++                // 分頁時權重是 pread 進來的，不該讓 CPU 後端自己再 offload 一次。
++                params.n_gpu_layers = 0;
++            }
++        }
++    }
++
+     if (!params.vocab_only && ggml_backend_reg_count() == 0) {
+         LLAMA_LOG_ERROR("%s: no backends are loaded. hint: use ggml_backend_load() or ggml_backend_load_all() to load a backend before calling this function\n", __func__);
+         return nullptr;

sdq-dsv4/determinism_probe.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# 決定性探針：同一個 prompt、同一個 RAM 預算，重複跑 N 次，看 greedy（--temp 0）
+# 的輸出是否每次都一樣。
+#
+# 為什麼需要這個：SDQ 分頁有兩種可能的失效模式會表現成「輸出會變」——
+#   (a) 分頁路徑本身不決定（例如某個 expert 被靜靜地跳過）
+#   (b) 分頁路徑完全決定，但上游（llama.cpp 的 deepseek4 attention / 路由）
+#       本來就不決定
+# 兩者必須分開，否則 README 上寫什麼都沒有意義。
+set -u
+BIN=${BIN:-/root/app/work/llama.cpp/build/bin/sdq-chat}
+MODEL=${MODEL:-/root/app/work/models/UD-IQ4_NL/DeepSeek-V4-Flash-0731-UD-IQ4_NL-00001-of-00004.gguf}
+PROMPT=${PROMPT:-"The capital of France is"}
+NTOK=${NTOK:-16}
+N=${N:-6}
+OUT=${OUT:-/tmp/opencode/determinism}
+mkdir -p "$OUT"
+
+for mb in "$@"; do
+  echo "=== ram-budget ${mb} MB × ${N} ==="
+  for i in $(seq 1 "$N"); do
+    "$BIN" -m "$MODEL" -p "$PROMPT" -n "$NTOK" -c 2048 -t 16 -b 128 \
+      --temp 0 --ram-budget-mb "$mb" --no-interactive 2>/dev/null \
+      | sed -n '/^assistant:/,$p' | grep -v '^\[' > "$OUT/${mb}_${i}.txt"
+    printf '  run %d: %s\n' "$i" "$(md5sum < "$OUT/${mb}_${i}.txt" | cut -c1-12)"
+  done
+  echo "  distinct outputs: $(md5sum "$OUT/${mb}"_*.txt | awk '{print $1}' | sort -u | wc -l) / $N"
+  md5sum "$OUT/${mb}"_*.txt | awk '{print $1}' | sort | uniq -c | sed 's/^/    /'
+done

sdq-dsv4/gen_tables.py

@@ -0,0 +1,57 @@
+"""從 llama.cpp 的 ggml 原始碼抽出常數表，產生 verify_moe_dsv4.py 需要的 Python literal。
+
+用法：python3 gen_tables.py <ggml-common.h> <ggml-impl.h> > tables_out.py
+
+抽出：
+  IQ3S_GRID  : iq3s_grid[512]（uint32，每個元素是 4 個 4-bit 的 codebook index）
+  KVALUES_MXFP4 : kvalues_fp4[16]（int8，E2M1 值 ×2）
+  KMASK_IQ2XS : kmask_iq2xs[8]
+  e8m0_to_fp32_half(x)
+"""
+import re
+import sys
+
+
+def table(text, name):
+    m = re.search(r'GGML_TABLE_BEGIN\([^,]+,\s*%s\s*,\s*(\d+)\)\s*(.*?)\s*GGML_TABLE_END\(\)'
+                  % re.escape(name), text, re.S)
+    if not m:
+        raise SystemExit('table not found: %s' % name)
+    body = m.group(2)
+    body = re.sub(r'//.*', '', body)
+    body = body.replace('\\', ' ')
+    vals = [v.strip() for v in body.split(',') if v.strip()]
+    return vals
+
+
+def main():
+    ch = open(sys.argv[1]).read()
+    ih = open(sys.argv[2]).read()
+
+    grid = table(ch, 'iq3s_grid')
+    kval = table(ch, 'kvalues_fp4')
+    kmask = table(ch, 'kmask_iq2xs')
+
+    if len(grid) != 512:
+        raise SystemExit('iq3s_grid: %d entries' % len(grid))
+    if len(kval) != 16:
+        raise SystemExit('kvalues_fp4: %d entries' % len(kval))
+    if len(kmask) != 8:
+        raise SystemExit('kmask_iq2xs: %d entries' % len(kmask))
+
+    print('# 由 gen_tables.py 從 llama.cpp 836d5717 的 ggml-common.h / ggml-impl.h 產生。')
+    print('# 不要手改。')
+    print()
+    print('IQ3S_GRID = (')
+    for i in range(0, 512, 8):
+        print('    ' + ' '.join('%s,' % v for v in grid[i:i + 8]))
+    print(')')
+    print()
+    print('KVALUES_MXFP4 = (' + ' '.join('%s,' % v for v in kval) + ')')
+    print()
+    print('KMASK_IQ2XS = (' + ' '.join('%s,' % v for v in kmask) + ')')
+    print()
+
+
+if __name__ == '__main__':
+    main()

sdq-dsv4/ggml_deq.cpp

@@ -0,0 +1,54 @@
+// 用 ggml 自己的 dequantize 抽出一列權重，給 Python 端做「逐位元組」對照。
+//
+// 用途：verify_moe_dsv4.py 裡的 IQ3_S / MXFP4 dequant 是照著 ggml 原始碼手寫的
+// NumPy 版本。這支工具提供**獨立**的第二份實作（直接呼叫 ggml 的 C 函式），
+// 兩者必須逐位元組相同 —— 否則後面所有「SDQ kernel 對得上 NumPy」的結論
+// 都只是在一份錯誤的 reference 上自我一致。
+//
+// build（對 SDQ 那份 llama.cpp build 目錄）：
+//   c++ -O2 -o ggml_deq ggml_deq.cpp \
+//       -I<llama.cpp>/ggml/include -I<llama.cpp>/ggml/src \
+//       -L<llama.cpp>/build/bin -lggml-base -Wl,-rpath,<llama.cpp>/build/bin
+//
+// 用法：ggml_deq <type> <file> <offset> <n>   → stdout 印 n 個 float
+//   type: 21 = IQ3_S, 39 = MXFP4, 8 = Q8_0, 12 = Q4_K, 13 = Q5_K, 7 = Q5_1
+#include "ggml.h"
+#include "ggml-quants.h"   // ggml/src/ggml-quants.h（block_iq3_s / block_mxfp4 定義）
+
+#include <cstdio>
+#include <cstdlib>
+#include <cstring>
+
+int main(int argc, char ** argv) {
+    if (argc < 5) {
+        fprintf(stderr, "usage: %s <type> <file> <offset> <n>\n", argv[0]);
+        return 1;
+    }
+    const int   tt  = atoi(argv[1]);
+    const char * path = argv[2];
+    const long long off = atoll(argv[3]);
+    const int   n   = atoi(argv[4]);
+
+    FILE * f = fopen(path, "rb");
+    if (!f) { perror("open"); return 1; }
+    const size_t ts = ggml_row_size((ggml_type) tt, n);
+    void * buf = malloc(ts);
+    if (fseek(f, (long) off, SEEK_SET) != 0) { perror("seek"); return 1; }
+    if (fread(buf, 1, ts, f) != ts) { fprintf(stderr, "short read\n"); return 1; }
+    fclose(f);
+
+    float * y = (float *) malloc(sizeof(float) * (size_t) n);
+    switch (tt) {
+        case 21: dequantize_row_iq3_s((const block_iq3_s *) buf, y, n); break;
+        case 39: dequantize_row_mxfp4((const block_mxfp4 *) buf, y, n); break;
+        case 12: dequantize_row_q4_K ((const block_q4_K  *) buf, y, n); break;
+        case 13: dequantize_row_q5_K ((const block_q5_K  *) buf, y, n); break;
+        case 7:  dequantize_row_q5_1((const block_q5_1 *) buf, y, n); break;
+        case 8:  dequantize_row_q8_0((const block_q8_0 *) buf, y, n); break;
+        default: fprintf(stderr, "type %d not handled\n", tt); return 1;
+    }
+    fwrite(y, sizeof(float), (size_t) n, stdout);
+    free(y);
+    free(buf);
+    return 0;
+}

sdq-dsv4/ggml_tables.py

@@ -0,0 +1,74 @@
+# 由 gen_tables.py 從 llama.cpp 836d5717 的 ggml-common.h / ggml-impl.h 產生。
+# 不要手改。
+
+IQ3S_GRID = (
+    0x01010101, 0x01010103, 0x01010105, 0x0101010b, 0x0101010f, 0x01010301, 0x01010303, 0x01010305,
+    0x01010309, 0x0101030d, 0x01010501, 0x01010503, 0x0101050b, 0x01010707, 0x01010901, 0x01010905,
+    0x0101090b, 0x0101090f, 0x01010b03, 0x01010b07, 0x01010d01, 0x01010d05, 0x01010f03, 0x01010f09,
+    0x01010f0f, 0x01030101, 0x01030103, 0x01030105, 0x01030109, 0x01030301, 0x01030303, 0x0103030b,
+    0x01030501, 0x01030507, 0x0103050f, 0x01030703, 0x0103070b, 0x01030909, 0x01030d03, 0x01030d0b,
+    0x01030f05, 0x01050101, 0x01050103, 0x0105010b, 0x0105010f, 0x01050301, 0x01050307, 0x0105030d,
+    0x01050503, 0x0105050b, 0x01050701, 0x01050709, 0x01050905, 0x0105090b, 0x0105090f, 0x01050b03,
+    0x01050b07, 0x01050f01, 0x01050f07, 0x01070107, 0x01070303, 0x0107030b, 0x01070501, 0x01070505,
+    0x01070703, 0x01070707, 0x0107070d, 0x01070909, 0x01070b01, 0x01070b05, 0x01070d0f, 0x01070f03,
+    0x01070f0b, 0x01090101, 0x01090307, 0x0109030f, 0x01090503, 0x01090509, 0x01090705, 0x01090901,
+    0x01090907, 0x01090b03, 0x01090f01, 0x010b0105, 0x010b0109, 0x010b0501, 0x010b0505, 0x010b050d,
+    0x010b0707, 0x010b0903, 0x010b090b, 0x010b090f, 0x010b0d0d, 0x010b0f07, 0x010d010d, 0x010d0303,
+    0x010d0307, 0x010d0703, 0x010d0b05, 0x010d0f03, 0x010f0101, 0x010f0105, 0x010f0109, 0x010f0501,
+    0x010f0505, 0x010f050d, 0x010f0707, 0x010f0b01, 0x010f0b09, 0x03010101, 0x03010103, 0x03010105,
+    0x03010109, 0x03010301, 0x03010303, 0x03010307, 0x0301030b, 0x0301030f, 0x03010501, 0x03010505,
+    0x03010703, 0x03010709, 0x0301070d, 0x03010b09, 0x03010b0d, 0x03010d03, 0x03010f05, 0x03030101,
+    0x03030103, 0x03030107, 0x0303010d, 0x03030301, 0x03030309, 0x03030503, 0x03030701, 0x03030707,
+    0x03030903, 0x03030b01, 0x03030b05, 0x03030f01, 0x03030f0d, 0x03050101, 0x03050305, 0x0305030b,
+    0x0305030f, 0x03050501, 0x03050509, 0x03050705, 0x03050901, 0x03050907, 0x03050b0b, 0x03050d01,
+    0x03050f05, 0x03070103, 0x03070109, 0x0307010f, 0x03070301, 0x03070307, 0x03070503, 0x0307050f,
+    0x03070701, 0x03070709, 0x03070903, 0x03070d05, 0x03070f01, 0x03090107, 0x0309010b, 0x03090305,
+    0x03090309, 0x03090703, 0x03090707, 0x03090905, 0x0309090d, 0x03090b01, 0x03090b09, 0x030b0103,
+    0x030b0301, 0x030b0307, 0x030b0503, 0x030b0701, 0x030b0705, 0x030b0b03, 0x030d0501, 0x030d0509,
+    0x030d050f, 0x030d0909, 0x030d090d, 0x030f0103, 0x030f0107, 0x030f0301, 0x030f0305, 0x030f0503,
+    0x030f070b, 0x030f0903, 0x030f0d05, 0x030f0f01, 0x05010101, 0x05010103, 0x05010107, 0x0501010b,
+    0x0501010f, 0x05010301, 0x05010305, 0x05010309, 0x0501030d, 0x05010503, 0x05010507, 0x0501050f,
+    0x05010701, 0x05010705, 0x05010903, 0x05010907, 0x0501090b, 0x05010b01, 0x05010b05, 0x05010d0f,
+    0x05010f01, 0x05010f07, 0x05010f0b, 0x05030101, 0x05030105, 0x05030301, 0x05030307, 0x0503030f,
+    0x05030505, 0x0503050b, 0x05030703, 0x05030709, 0x05030905, 0x05030b03, 0x05050103, 0x05050109,
+    0x0505010f, 0x05050503, 0x05050507, 0x05050701, 0x0505070f, 0x05050903, 0x05050b07, 0x05050b0f,
+    0x05050f03, 0x05050f09, 0x05070101, 0x05070105, 0x0507010b, 0x05070303, 0x05070505, 0x05070509,
+    0x05070703, 0x05070707, 0x05070905, 0x05070b01, 0x05070d0d, 0x05090103, 0x0509010f, 0x05090501,
+    0x05090507, 0x05090705, 0x0509070b, 0x05090903, 0x05090f05, 0x05090f0b, 0x050b0109, 0x050b0303,
+    0x050b0505, 0x050b070f, 0x050b0901, 0x050b0b07, 0x050b0f01, 0x050d0101, 0x050d0105, 0x050d010f,
+    0x050d0503, 0x050d0b0b, 0x050d0d03, 0x050f010b, 0x050f0303, 0x050f050d, 0x050f0701, 0x050f0907,
+    0x050f0b01, 0x07010105, 0x07010303, 0x07010307, 0x0701030b, 0x0701030f, 0x07010505, 0x07010703,
+    0x07010707, 0x0701070b, 0x07010905, 0x07010909, 0x0701090f, 0x07010b03, 0x07010d07, 0x07010f03,
+    0x07030103, 0x07030107, 0x0703010b, 0x07030309, 0x07030503, 0x07030507, 0x07030901, 0x07030d01,
+    0x07030f05, 0x07030f0d, 0x07050101, 0x07050305, 0x07050501, 0x07050705, 0x07050709, 0x07050b01,
+    0x07070103, 0x07070301, 0x07070309, 0x07070503, 0x07070507, 0x0707050f, 0x07070701, 0x07070903,
+    0x07070907, 0x0707090f, 0x07070b0b, 0x07070f07, 0x07090107, 0x07090303, 0x0709030d, 0x07090505,
+    0x07090703, 0x07090b05, 0x07090d01, 0x07090d09, 0x070b0103, 0x070b0301, 0x070b0305, 0x070b050b,
+    0x070b0705, 0x070b0909, 0x070b0b0d, 0x070b0f07, 0x070d030d, 0x070d0903, 0x070f0103, 0x070f0107,
+    0x070f0501, 0x070f0505, 0x070f070b, 0x09010101, 0x09010109, 0x09010305, 0x09010501, 0x09010509,
+    0x0901050f, 0x09010705, 0x09010903, 0x09010b01, 0x09010f01, 0x09030105, 0x0903010f, 0x09030303,
+    0x09030307, 0x09030505, 0x09030701, 0x0903070b, 0x09030907, 0x09030b03, 0x09030b0b, 0x09050103,
+    0x09050107, 0x09050301, 0x0905030b, 0x09050503, 0x09050707, 0x09050901, 0x09050b0f, 0x09050d05,
+    0x09050f01, 0x09070109, 0x09070303, 0x09070307, 0x09070501, 0x09070505, 0x09070703, 0x0907070b,
+    0x09090101, 0x09090105, 0x09090509, 0x0909070f, 0x09090901, 0x09090f03, 0x090b010b, 0x090b010f,
+    0x090b0503, 0x090b0d05, 0x090d0307, 0x090d0709, 0x090d0d01, 0x090f0301, 0x090f030b, 0x090f0701,
+    0x090f0907, 0x090f0b03, 0x0b010105, 0x0b010301, 0x0b010309, 0x0b010505, 0x0b010901, 0x0b010909,
+    0x0b01090f, 0x0b010b05, 0x0b010d0d, 0x0b010f09, 0x0b030103, 0x0b030107, 0x0b03010b, 0x0b030305,
+    0x0b030503, 0x0b030705, 0x0b030f05, 0x0b050101, 0x0b050303, 0x0b050507, 0x0b050701, 0x0b05070d,
+    0x0b050b07, 0x0b070105, 0x0b07010f, 0x0b070301, 0x0b07050f, 0x0b070909, 0x0b070b03, 0x0b070d0b,
+    0x0b070f07, 0x0b090103, 0x0b090109, 0x0b090501, 0x0b090705, 0x0b09090d, 0x0b0b0305, 0x0b0b050d,
+    0x0b0b0b03, 0x0b0b0b07, 0x0b0d0905, 0x0b0f0105, 0x0b0f0109, 0x0b0f0505, 0x0d010303, 0x0d010307,
+    0x0d01030b, 0x0d010703, 0x0d010707, 0x0d010d01, 0x0d030101, 0x0d030501, 0x0d03050f, 0x0d030d09,
+    0x0d050305, 0x0d050709, 0x0d050905, 0x0d050b0b, 0x0d050d05, 0x0d050f01, 0x0d070101, 0x0d070309,
+    0x0d070503, 0x0d070901, 0x0d09050b, 0x0d090907, 0x0d090d05, 0x0d0b0101, 0x0d0b0107, 0x0d0b0709,
+    0x0d0b0d01, 0x0d0d010b, 0x0d0d0901, 0x0d0f0303, 0x0d0f0307, 0x0f010101, 0x0f010109, 0x0f01010f,
+    0x0f010501, 0x0f010505, 0x0f01070d, 0x0f010901, 0x0f010b09, 0x0f010d05, 0x0f030105, 0x0f030303,
+    0x0f030509, 0x0f030907, 0x0f03090b, 0x0f050103, 0x0f050109, 0x0f050301, 0x0f05030d, 0x0f050503,
+    0x0f050701, 0x0f050b03, 0x0f070105, 0x0f070705, 0x0f07070b, 0x0f070b07, 0x0f090103, 0x0f09010b,
+    0x0f090307, 0x0f090501, 0x0f090b01, 0x0f0b0505, 0x0f0b0905, 0x0f0d0105, 0x0f0d0703, 0x0f0f0101,
+)
+
+KVALUES_MXFP4 = (0, 1, 2, 3, 4, 6, 8, 12, 0, -1, -2, -3, -4, -6, -8, -12,)
+
+KMASK_IQ2XS = (1, 2, 4, 8, 16, 32, 64, 128,)
+

sdq-dsv4/memory_levels_dsv4.py

@@ -0,0 +1,281 @@
+#!/usr/bin/env python3
+"""DeepSeek-V4-Flash-0731 UD-IQ4_NL 在多個 RAM 預算下的實驗。
+
+沿用 SDQ 原專案的 memory_levels 方法：把 RAM 預算交給 pager 的 arena sizing，
+外層不做硬性 cgroup 限額（本機 /sys/fs/cgroup 是唯讀），報告會明確標示這是
+pager budget 實測而非三個獨立容器。
+
+每輪量：
+  decode tok/s、prefill tok/s、peak RSS、swap、arena、slot 數
+  hit rate（= hot：expert 已在 RAM）、SSD bytes/token（= cold：必須回 SSD 讀）
+  hot/cold expert 數量與每層分布
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import platform
+import re
+import statistics
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+MIB = 1024 * 1024
+GIB = 1024 ** 3
+
+PROMPTS = [
+    "The capital of France is",
+    "請用一句話說明什麼是 SSD 快取。",
+    "Write one sentence about mixture of experts routing.",
+]
+
+MODEL_ID = 'DeepSeek-V4-Flash-0731-UD-IQ4_NL'
+MODEL_REPO = 'unsloth/DeepSeek-V4-Flash-0731-GGUF'
+MODEL_SUB = 'UD-IQ4_NL'
+ARCH = 'deepseek4'
+# 4 個 shard 實際檔案大小（bytes），由 HF API 的 blobs=true 取得
+MODEL_BYTES = 136662446656
+
+
+def host_facts() -> dict:
+    cpu = ""
+    try:
+        for line in Path('/proc/cpuinfo').read_text().splitlines():
+            if line.startswith('model name'):
+                cpu = line.split(':', 1)[1].strip()
+                break
+    except Exception:
+        pass
+    mem_total = 0
+    try:
+        for line in Path('/proc/meminfo').read_text().splitlines():
+            if line.startswith('MemTotal'):
+                mem_total = int(line.split()[1]) * 1024
+                break
+    except Exception:
+        pass
+    return {'cpu_model': cpu, 'cpu_threads': os.cpu_count(), 'mem_total_bytes': mem_total}
+
+
+def drop_cache() -> None:
+    try:
+        subprocess.run(['sync'], check=False)
+        Path('/proc/sys/vm/drop_caches').write_text('3\n')
+    except Exception:
+        pass          # 唯讀時忽略；報告會註明 cold 定義
+
+
+def run_once(args, level_mb: int, repeat: int) -> dict:
+    stats_file = Path(args.output_dir) / f'level_{level_mb}_r{repeat}.jsonl'
+    stats_file.unlink(missing_ok=True)
+    prompt = PROMPTS[repeat % len(PROMPTS)]
+
+    cmd = [
+        str(Path(args.bin).resolve()),
+        '-m', str(Path(args.model).resolve()),
+        '-p', prompt, '-n', str(args.n_predict), '-c', str(args.ctx),
+        '-t', str(args.threads), '-b', str(args.ubatch), '--temp', '0',
+        '--no-interactive', '--stats-file', str(stats_file),
+        '--ram-budget-mb', str(level_mb),
+    ]
+    env = dict(os.environ)
+    env.update({
+        'SDQ_RAM_BUDGET_MB': str(level_mb),
+        'SDQ_RESERVE_MB': str(args.reserve_mb),
+        'SDQ_PREFETCH': '0',
+        'SDQ_FADV_DONTNEED': '1',
+    })
+
+    drop_cache()
+    t0 = time.perf_counter()
+    try:
+        # 不用 text=True：這個模型的 tokenizer（joyai-llm BPE）會吐出半個
+        # UTF-8 多位元組序列，嚴格解碼會直接 UnicodeDecodeError 讓整個
+        # runner 掛掉 —— 而且是在第一輪結束之後才炸，等於白跑。
+        proc = subprocess.run(cmd, capture_output=True, env=env,
+                              timeout=args.timeout, check=False)
+    except subprocess.TimeoutExpired:
+        return {'level_mb': level_mb, 'repeat': repeat + 1,
+                'error': f'timeout after {args.timeout}s'}
+    wall = time.perf_counter() - t0
+    out = proc.stdout.decode('utf-8', errors='replace')
+    err = proc.stderr.decode('utf-8', errors='replace')
+    # sdq-chat 的進度與摘要都寫在 stderr（decode/prefill/記憶體摘要），
+    # assistant 文字寫在 stdout。兩邊都要掃。
+    both = out + '\n' + err
+
+    if proc.returncode:
+        tail = '\n'.join([l for l in err.splitlines()
+                          if 'sdq' in l or 'error' in l.lower()][-6:])
+        return {'level_mb': level_mb, 'repeat': repeat + 1,
+                'error': f'exit {proc.returncode}', 'wall_s': round(wall, 2),
+                'failure_reason': tail}
+
+    def grab(pat, cast=float, default=None, text=None):
+        m = re.search(pat, text if text is not None else out, re.M)
+        return cast(m.group(1)) if m else default
+
+    decode_line = re.search(r'decode:\s*(\d+)\s+tok\s*/\s*([\d.]+)s\s*=\s*([\d.]+)\s+tok/s', both)
+    prefill_line = re.search(r'prefill:\s*(\d+)\s+tok\s*/\s*([\d.]+)s\s*=\s*([\d.]+)\s+tok/s', both)
+    mem_line = re.search(r'總 RSS\s+(\d+)\s+MB\s*/\s*峰值\s+(\d+)\s+MB\s*/\s*swap\s+(\d+)\s+MB', both)
+    arena_line = re.search(r'arena\s+([\d.]+)\s+GiB', err)
+    slots_line = re.search(r'slots=(\d+)', err)
+    ssd_total = re.search(r'全程 SSD 實際讀取:\s*([\d.]+)\s*GB', both)
+    assistant = ''
+    started = False
+    for line in out.splitlines():
+        if line.startswith('assistant:'):
+            started = True
+            rest = line[len('assistant:'):].strip()
+            if rest:
+                assistant = rest
+            continue
+        if started and line.strip() and not line.startswith('['):
+            assistant += ' ' + line.strip()
+    assistant = assistant.strip()
+
+    m = re.search(r'SSD 讀\s*([\d.]+)\s*MB\s*\(([\d.]+)\s*MB/tok\)', both)
+
+    # stats jsonl 的最後一筆 decode 記錄
+    rec = {}
+    if stats_file.exists():
+        for line in stats_file.read_text().splitlines():
+            r = json.loads(line)
+            if r.get('phase') == 'decode':
+                rec = r
+        stats_file.unlink(missing_ok=True)
+    stats_file.unlink(missing_ok=True)
+
+    per_layer = rec.get('per_layer') or []
+    hit_rate = rec.get('hit_rate')
+    per_layer_rates = [p['hit_rate'] for p in per_layer if p.get('req', 0) > 0]
+
+    return {
+        'level_mb': level_mb,
+        'level_gib': level_mb // 1024,
+        'repeat': repeat + 1,
+        'prompt': prompt,
+        'wall_s': round(wall, 2),
+        'decode_tok_s': float(decode_line.group(3)) if decode_line else None,
+        'decode_tok': int(decode_line.group(1)) if decode_line else None,
+        'prefill_tok_s': float(prefill_line.group(3)) if prefill_line else None,
+        'prefill_tok': int(prefill_line.group(1)) if prefill_line else None,
+        'peak_rss_mb': int(mem_line.group(2)) if mem_line else None,
+        'final_rss_mb': int(mem_line.group(1)) if mem_line else None,
+        'vmswap_mb': int(mem_line.group(3)) if mem_line else None,
+        'arena_gib': float(arena_line.group(1)) if arena_line else None,
+        'n_slots': int(slots_line.group(1)) if slots_line else None,
+        'total_ssd_gb': float(ssd_total.group(1)) if ssd_total else None,
+        'decode_ssd_mb': float(m.group(1)) if m else None,
+        'ssd_mb_per_token': float(m.group(2)) if m else None,
+        'expert_requests': rec.get('expert_requests'),
+        'expert_hits': rec.get('expert_hits'),
+        'hot_rate_pct': hit_rate,
+        'cold_rate_pct': (100.0 - hit_rate) if hit_rate is not None else None,
+        'evictions': rec.get('evictions'),
+        'per_layer_hit_min': min(per_layer_rates) if per_layer_rates else None,
+        'per_layer_hit_max': max(per_layer_rates) if per_layer_rates else None,
+        'assistant': assistant[:200],
+    }
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument('--model', required=True)
+    ap.add_argument('--bin', required=True)
+    ap.add_argument('--levels-gib', type=int, nargs='+', default=[4, 8, 16, 32])
+    ap.add_argument('--repeat', type=int, default=2)
+    ap.add_argument('--ctx', type=int, default=2048)
+    ap.add_argument('--ubatch', type=int, default=128)
+    ap.add_argument('--threads', type=int, default=16)
+    ap.add_argument('--n-predict', type=int, default=48)
+    ap.add_argument('--reserve-mb', type=int, default=2048)
+    ap.add_argument('--timeout', type=int, default=1800)
+    ap.add_argument('--output-dir', default='/tmp/opencode/results')
+    ap.add_argument('--label', default='dsv4-4-8-16-32g')
+    args = ap.parse_args()
+
+    Path(args.output_dir).mkdir(parents=True, exist_ok=True)
+    for req in (args.model, args.bin):
+        if not Path(req).is_file():
+            ap.error(f'file does not exist: {req}')
+
+    print(f'[levels] host: {host_facts()["cpu_model"]} / {host_facts()["cpu_threads"]} threads')
+    results = []
+    for gib in args.levels_gib:
+        mb = gib * 1024
+        for r in range(args.repeat):
+            print(f'[levels] {gib} GiB run {r + 1}/{args.repeat} ...', flush=True)
+            res = run_once(args, mb, r)
+            results.append(res)
+            print(f'         decode={res.get("decode_tok_s")} tok/s  '
+                  f'peak_rss={res.get("peak_rss_mb")} MB  '
+                  f'hot={res.get("hot_rate_pct")}%  '
+                  f'ssd/tok={res.get("ssd_mb_per_token")} MB'
+                  + (f'  ERR {res["error"]}' if res.get('error') else ''), flush=True)
+
+    doc = {
+        'model_id': MODEL_ID,
+        'model_repo': MODEL_REPO,
+        'model_subdir': MODEL_SUB,
+        'architecture': ARCH,
+        'shards': 4,
+        'model_bytes': MODEL_BYTES,
+        'host': host_facts(),
+        'method': ('RAM budget passed to the SDQ expert pager arena sizing; '
+                   'no hard cgroup limit (host /sys/fs/cgroup is read-only). '
+                   'Page cache dropped before each run where permitted.'),
+        'settings': {'levels_gib': args.levels_gib, 'repeat': args.repeat,
+                     'ctx': args.ctx, 'ubatch': args.ubatch,
+                     'threads': args.threads, 'n_predict': args.n_predict,
+                     'reserve_mb': args.reserve_mb, 'temp': 0},
+        'results': results,
+    }
+    out = Path(args.output_dir)
+    (out / f'memory_levels_{args.label}.json').write_text(
+        json.dumps(doc, ensure_ascii=False, indent=2) + '\n')
+
+    def med(rows, key):
+        vals = [r[key] for r in rows if r.get(key) is not None]
+        return statistics.median(vals) if vals else None
+
+    lines = [
+        f'# RAM 預算矩陣：{args.label}', '',
+        doc['method'], '',
+        f"- Host: {host_facts()['cpu_model']}, {host_facts()['cpu_threads']} threads",
+        f"- ctx={args.ctx}, ubatch={args.ubatch}, threads={args.threads}, "
+        f"output tokens={args.n_predict}, temp=0, repeats={args.repeat}",
+        f"- KV/SSM state + compute reserve: {args.reserve_mb} MB", '',
+        '| RAM budget | arena (GiB) | slots | decode tok/s | prefill tok/s | hot % | cold % | SSD MiB/tok | total SSD read | peak RSS (MB) | swap | per-layer hit min..max |',
+        '|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|',
+    ]
+    # 注意：不要寫 `x or 'n/a'` —— swap = 0 是真的量到 0（0 是 falsy，會被印成 n/a）。
+    def i(v):
+        return 'n/a' if v is None else f'{int(round(v))}'
+    for gib in args.levels_gib:
+        mb = gib * 1024
+        rows = [r for r in results if r['level_mb'] == mb and not r.get('error')]
+        errs = [r for r in results if r['level_mb'] == mb and r.get('error')]
+        f = lambda v, n=2: 'n/a' if v is None else f'{v:.{n}f}'
+        status = 'FAIL: ' + str(errs[0].get('failure_reason', errs[0]['error']))[:120] if errs else f'{len(rows)}/{args.repeat}'
+        lo = med(rows, 'per_layer_hit_min'); hi = med(rows, 'per_layer_hit_max')
+        lines.append(
+            f"| {gib} GiB | {f(med(rows, 'arena_gib'))} | {i(med(rows, 'n_slots'))} "
+            f"| {f(med(rows, 'decode_tok_s'))} | {f(med(rows, 'prefill_tok_s'))} "
+            f"| {f(med(rows, 'hot_rate_pct'), 1)} | {f(med(rows, 'cold_rate_pct'), 1)} "
+            f"| {f(med(rows, 'ssd_mb_per_token'), 1)} | {f(med(rows, 'total_ssd_gb'), 1)} GB "
+            f"| {i(med(rows, 'peak_rss_mb'))} | {i(med(rows, 'vmswap_mb'))} MB "
+            f"| {f(lo, 1)}..{f(hi, 1)} |")
+        if errs:
+            lines.append(f'| | | | | | | | | | | | | {status} |')
+    lines += ['', f'JSON: `memory_levels_{args.label}.json`', '']
+    (out / f'memory_levels_{args.label}.md').write_text('\n'.join(lines))
+    print(f'[levels] wrote {out}/memory_levels_{args.label}.{{json,md}}')
+    return 1 if any(r.get('error') for r in results) else 0
+
+
+if __name__ == '__main__':
+    sys.exit(main() or 0)

sdq-dsv4/optional-sched-debug.patch

@@ -0,0 +1,24 @@
+diff --git a/ggml/src/ggml-backend.cpp b/ggml/src/ggml-backend.cpp
+index 5bdade6..41d898e 100644
+--- a/ggml/src/ggml-backend.cpp
++++ b/ggml/src/ggml-backend.cpp
+@@ -1431,6 +1431,19 @@ void ggml_backend_sched_split_graph(ggml_backend_sched_t sched, struct ggml_cgra
+         for (int b = 0; b < sched->n_backends && *cur_backend_id == -1; b++) {
+             ggml_backend_sched_set_if_supported(sched, node, b, cur_backend_id);
+         }
++        if (*cur_backend_id == -1 && getenv("SDQ_SCHED_DEBUG")) {
++            fprintf(stderr, "[sched-dbg] unassigned node: op=%s ne=[%lld,%lld,%lld,%lld] type=%s name='%s' n_backends=%d\n",
++                    ggml_op_name(node->op),
++                    (long long) node->ne[0], (long long) node->ne[1], (long long) node->ne[2], (long long) node->ne[3],
++                    ggml_type_name(node->type), ggml_get_name(node), sched->n_backends);
++            for (int j = 0; j < GGML_MAX_SRC && node->src[j]; j++) {
++                fprintf(stderr, "[sched-dbg]   src[%d] op=%s type=%s name='%s' buf=%p buft=%s\n",
++                        j, ggml_op_name(node->src[j]->op), ggml_type_name(node->src[j]->type),
++                        ggml_get_name(node->src[j]), (void *) node->src[j]->buffer,
++                        node->src[j]->buffer && node->src[j]->buffer->buft
++                            ? ggml_backend_buft_name(node->src[j]->buffer->buft) : "(none)");
++            }
++        }
+         GGML_ASSERT(*cur_backend_id != -1);
+     }
+ 

sdq-dsv4/sdq_buft.cpp

@@ -0,0 +1,226 @@
+// SDQ expert buffer type
+//
+// 這是一個「假」buffer type：它宣稱接受所有張量，但實際上
+//   * 不配置任何 RAM（alloc_buffer 回傳 0 大小的 buffer）
+//   * set_tensor 忽略傳入的資料（資料來自 llama.cpp 的 mmap，我們不碰）
+//   * 真正的資料由 sdq::pager 從檔案 pread 到自己的 arena
+//
+// 用途：讓 llama.cpp 把 18.2 GiB 的 MoE 專家權重「掛在模型上」卻不放進 RAM，
+// 改由分頁器管理 SSD → RAM → CPU 的三層資料流。
+
+#include "sdq_pager.h"
+
+#include "ggml-backend-impl.h"
+#include "llama-mmap.h"
+
+#include <cstdio>
+#include <cstdlib>
+#include <cstring>
+#include <algorithm>
+#include <mutex>
+#include <unordered_map>
+#include <vector>
+
+namespace sdq {
+
+// 給 tensor->data 的假位址。每個 expert 權重張量分到一小塊（預設 4 KB），
+// 指標必須有效（ggml 會做指標運算），但內容永遠不會被讀。
+struct expert_buffer {
+    std::vector<uint8_t> scratch;
+};
+
+static bool g_enabled = false;
+
+void    sdq_set_enabled(bool on) { g_enabled = on; }
+bool    sdq_enabled()           { return g_enabled; }
+
+static config g_cfg;
+void        sdq_set_config(const config & c) { g_cfg = c; }
+const config & sdq_get_config() { return g_cfg; }
+
+// ---------------------------------------------------------------- buffer iface
+
+// ggml_backend_buffer_i 的欄位依賴下面的實作，先給宣告
+struct ggml_backend_buffer_i sdq_buffer_iface();
+
+static const char * sdq_buft_get_name(ggml_backend_buffer_type_t buft) {
+    (void) buft;
+    return "SDQ_ExpertSSD";
+}
+
+static size_t sdq_buft_get_alignment(ggml_backend_buffer_type_t buft) {
+    (void) buft;
+    return 4096;
+}
+
+static size_t sdq_buft_get_max_size(ggml_backend_buffer_type_t buft) {
+    (void) buft;
+    return SIZE_MAX;
+}
+
+// 每個 expert 權重張量只回報 4 KB：18.2 GiB 的權重「不會」被載入 RAM 的關鍵。
+static size_t sdq_buft_get_alloc_size(ggml_backend_buffer_type_t buft, const ggml_tensor * tensor) {
+    (void) buft;
+    (void) tensor;
+    return 4096;
+}
+
+static bool sdq_buft_is_host(ggml_backend_buffer_type_t buft) {
+    (void) buft;
+    return false;
+}
+
+static ggml_backend_buffer_t sdq_buft_alloc_buffer(ggml_backend_buffer_type_t buft, size_t size) {
+    // llama.cpp 會用 get_alloc_size() 計算總大小後呼叫本函式；
+    // 我們只保留真正需要的假位址空間（每個張量 4 KB）。
+    const size_t bytes = size < 4096 ? 4096 : size;
+    auto * buf = new expert_buffer();
+    buf->scratch.assign(bytes, 0);
+    auto * b = new ggml_backend_buffer{
+        /* .iface   = */ sdq_buffer_iface(),
+        /* .buft    = */ buft,
+        /* .context = */ buf,
+        /* .size    = */ bytes,
+        /* .usage   = */ GGML_BACKEND_BUFFER_USAGE_WEIGHTS,
+    };
+    return b;
+}
+
+// 一次配置整個 context 的張量：每個張量 4 KB 假位址，實際權重 0 RAM。
+static ggml_backend_buffer_t sdq_buft_alloc_buffer_n(ggml_backend_buffer_type_t buft,
+                                                     ggml_tensor ** tensors, int n_tensors) {
+    const size_t slot = 4096;
+    const size_t bytes = slot * (size_t) std::max(n_tensors, 1);
+    ggml_backend_buffer_t buffer = sdq_buft_alloc_buffer(buft, bytes);
+    if (!buffer) {
+        return nullptr;
+    }
+    uint8_t * base = (uint8_t *) buffer->iface.get_base(buffer);
+    size_t off = 0;
+    for (int i = 0; i < n_tensors; i++) {
+        ggml_tensor * t = tensors[i];
+        t->data = base + off;
+        t->buffer = buffer;
+        off += slot;
+        buffer->iface.init_tensor(buffer, t);
+    }
+    return buffer;
+}
+
+static void sdq_buft_free_buffer(ggml_backend_buffer_t buffer) {
+    // 只釋放自己的資料；ggml_backend_buffer_free() 會負責 delete buffer 本體，
+    // 這裡再 delete 一次會造成 double free。
+    delete (expert_buffer *) buffer->context;
+    buffer->context = nullptr;
+}
+
+static void * sdq_buft_get_base(ggml_backend_buffer_t buffer) {
+    return ((expert_buffer *) buffer->context)->scratch.data();
+}
+
+static ggml_status sdq_buft_init_tensor(ggml_backend_buffer_t buffer, ggml_tensor * tensor) {
+    (void) buffer;
+    (void) tensor;
+    return GGML_STATUS_SUCCESS;
+}
+
+static void sdq_buft_memset_tensor(ggml_backend_buffer_t buffer, ggml_tensor * tensor,
+                                   uint8_t value, size_t offset, size_t size) {
+    (void) buffer; (void) tensor; (void) value; (void) offset; (void) size;
+}
+
+static void sdq_buft_set_tensor(ggml_backend_buffer_t buffer, ggml_tensor * tensor,
+                                const void * data, size_t offset, size_t size) {
+    // 關鍵：忽略。llama.cpp 會把 mmap 的資料交給我們，這裡一個位元組都不落地，
+    // 專家權利永遠不會佔用 RAM。
+    (void) buffer; (void) tensor; (void) data; (void) offset; (void) size;
+}
+
+static void sdq_buft_get_tensor(ggml_backend_buffer_t buffer, const ggml_tensor * tensor,
+                                void * data, size_t offset, size_t size) {
+    (void) buffer; (void) tensor; (void) offset;
+    memset(data, 0, size);
+}
+
+static bool sdq_buft_cpy_tensor(ggml_backend_buffer_t buffer, const ggml_tensor * src, ggml_tensor * dst) {
+    (void) buffer; (void) src; (void) dst;
+    return true;
+}
+
+static void sdq_buft_clear(ggml_backend_buffer_t buffer, uint8_t value) {
+    (void) buffer; (void) value;
+}
+
+struct ggml_backend_buffer_i sdq_buffer_iface() {
+    static ggml_backend_buffer_i i = [] {
+        ggml_backend_buffer_i x {};
+        x.free_buffer   = sdq_buft_free_buffer;
+        x.get_base      = sdq_buft_get_base;
+        x.init_tensor   = sdq_buft_init_tensor;
+        x.memset_tensor = sdq_buft_memset_tensor;
+        x.set_tensor    = sdq_buft_set_tensor;
+        x.get_tensor    = sdq_buft_get_tensor;
+        x.cpy_tensor    = sdq_buft_cpy_tensor;
+        x.clear         = sdq_buft_clear;
+        return x;
+    }();
+    return i;
+}
+
+ggml_backend_buffer_type_t sdq_expert_buft() {
+    static ggml_backend_buffer_type_t buft = [] {
+        return new ggml_backend_buffer_type{
+            /* .iface   = */ {
+                /* .get_name         = */ sdq_buft_get_name,
+                /* .alloc_buffer     = */ sdq_buft_alloc_buffer,
+                /* .alloc_buffer_n   = */ sdq_buft_alloc_buffer_n,
+                /* .get_alignment    = */ sdq_buft_get_alignment,
+                /* .get_max_size     = */ sdq_buft_get_max_size,
+                /* .get_alloc_size   = */ sdq_buft_get_alloc_size,
+                /* .get_alloc_size_n = */ nullptr,
+                /* .is_host          = */ sdq_buft_is_host,
+            },
+            /* .device  = */ nullptr,
+            /* .context = */ nullptr,
+        };
+    }();
+    return buft;
+}
+
+// llama.cpp 端需要的介面宣告
+void sdq_install_buft_overrides(llama_model_params * params);
+
+static const llama_model_tensor_buft_override * sdq_overrides() {
+    static llama_model_tensor_buft_override ov[] = {
+        { "blk\\.[0-9]+\\.ffn_(gate|up|down|gate_up)_exps\\.weight", sdq_expert_buft() },
+        { nullptr, nullptr },
+    };
+    return ov;
+}
+
+void sdq_install_buft_overrides(llama_model_params * params) {
+    if (!params) {
+        return;
+    }
+    if (params->tensor_buft_overrides == nullptr) {
+        params->tensor_buft_overrides = sdq_overrides();
+    } else {
+        // 使用者已有 override：把手動指定的順序原樣保留，附加在尾端
+        size_t n = 0;
+        while (params->tensor_buft_overrides[n].pattern != nullptr) {
+            n++;
+        }
+        static std::vector<llama_model_tensor_buft_override> merged;
+        merged.clear();
+        for (size_t i = 0; i < n; i++) {
+            merged.push_back(params->tensor_buft_overrides[i]);
+        }
+        for (size_t i = 0; sdq_overrides()[i].pattern != nullptr; i++) {
+            merged.push_back(sdq_overrides()[i]);
+        }
+        merged.push_back({ nullptr, nullptr });
+        params->tensor_buft_overrides = merged.data();
+    }
+}
+
+} // namespace sdq

sdq-dsv4/sdq_cli.cpp

@@ -0,0 +1,825 @@
+// SDQ 聊天 / benchmark 主程式
+//
+//   sdq-chat -m <model.gguf> [-c ctx] [-t threads] [-n n_predict] [-p prompt] ...
+//
+// 這個工具存在的理由：官方 llama-cli 不會安裝我們的 tensor buffer override，
+// 而且需要我們在載入模型前後插入 pager 的初始化/收尾。用最少的相依度
+// （只鏈 llama + ggml）自己寫一支，行為完全可控。
+
+#include "llama.h"
+#include "sdq_pager.h"
+
+#include <algorithm>
+#include <chrono>
+#include <cinttypes>
+#include <cmath>
+#include <cstdio>
+#include <cstdlib>
+#include <cstring>
+#include <functional>
+#include <thread>
+#include <iostream>
+#include <string>
+#include <vector>
+
+using namespace sdq;
+
+namespace {
+
+struct options {
+    std::string model;
+    std::string prompt;
+    std::string system = "You are a helpful assistant. Answer in the user's language.";
+    std::string stats_file;
+    int32_t n_ctx = 4096;          // 驗證範圍：4K（理論支援 1M）
+    int32_t n_predict = 256;
+    int32_t n_threads = 0;
+    int32_t n_ubatch = 0;
+    int32_t n_keep = 0;
+    float temp = 0.7f;
+    float top_p = 0.95f;
+    int32_t top_k = 20;
+    bool chat = true;
+    bool interactive = true;
+    bool bench = false;
+    bool no_prefetch = false;
+    bool dump_logits = false;
+    std::string logits_out;
+    std::string selftest;
+    float      selftest_limit = 0.0f;
+    float      selftest_xscale = 1.0f;
+    int        selftest_mode  = SDQ_SWIGLU_GGML_FUSED_CLAMP;
+    std::string span_test;
+    std::string dump_tensors;   // ggml eval callback：把指定張量的資料存檔（A/B 比對用）
+    bool no_pager = false;      // A/B 測試用：不啟用分頁，走上游 mul_mat_id（整個模型在 RAM）
+    int32_t arena_mb = 0;
+    int32_t ram_budget_mb = 0;
+    bool fadvise = true;
+};
+
+double now_s() {
+    static auto t0 = std::chrono::steady_clock::now();
+    return std::chrono::duration<double>(std::chrono::steady_clock::now() - t0).count();
+}
+
+size_t rss_mb() { return process_rss_bytes() / (1024 * 1024); }
+
+// 從 /proc/self/status 讀 VmHWM（峰值 RSS）/ VmSwap（這個行程真的用了多少 swap）
+size_t proc_status_kb(const char * key) {
+    FILE * f = fopen("/proc/self/status", "r");
+    if (!f) return 0;
+    char line[256];
+    const size_t klen = strlen(key);
+    size_t val = 0;
+    while (fgets(line, sizeof(line), f)) {
+        if (strncmp(line, key, klen) == 0) {
+            val = (size_t) strtoull(line + klen, nullptr, 10);
+            break;
+        }
+    }
+    fclose(f);
+    return val;
+}
+
+size_t peak_rss_mb() { return proc_status_kb("VmHWM:") / 1024; }
+size_t swap_mb()    { return proc_status_kb("VmSwap:") / 1024; }
+
+// /proc/self/smaps_rollup：把 RSS 拆成「檔案對映」與「匿名」兩塊。
+// 這很重要：模型檔是 mmap 進來的，核心預讀會讓「檔案對映頁」也算進 RSS，
+// 報告時必須分開看，否則會誤以為 RAM 用量比實際少（或多）。
+size_t smaps_kb(const char * key) {
+    FILE * f = fopen("/proc/self/smaps_rollup", "r");
+    if (!f) return 0;
+    char line[256];
+    const size_t klen = strlen(key);
+    size_t val = 0;
+    while (fgets(line, sizeof(line), f)) {
+        if (strncmp(line, key, klen) == 0) {
+            val = (size_t) strtoull(line + klen, nullptr, 10);
+            break;
+        }
+    }
+    fclose(f);
+    return val;
+}
+
+void print_mem_report(const char * when) {
+    fprintf(stderr,
+            "[sdq] 記憶體（%s）：匿名 RSS %zu MB / 檔案對映 RSS %zu MB / 總 RSS %zu MB / 峰值 %zu MB / swap %zu MB\n",
+            when, smaps_kb("Anonymous:") / 1024, smaps_kb("RssFile:") / 1024,
+            smaps_kb("Rss:") / 1024, peak_rss_mb(), swap_mb());
+}
+
+// 讀 /proc/self/io：從 block device 實際讀了多少（SSD 讀取）
+uint64_t read_bytes_io() {
+    FILE * f = fopen("/proc/self/io", "r");
+    if (!f) return 0;
+    char line[256];
+    uint64_t v = 0;
+    while (fgets(line, sizeof(line), f)) {
+        if (strncmp(line, "read_bytes:", 11) == 0) {
+            v = strtoull(line + 11, nullptr, 10);
+        }
+    }
+    fclose(f);
+    return v;
+}
+
+struct chat_state {
+    std::vector<llama_chat_message> msgs;
+};
+
+std::string build_prompt(const options & opt, const chat_state & st) {
+    if (!opt.chat) {
+        return opt.prompt;
+    }
+    const char * tmpl = llama_model_chat_template(nullptr, nullptr);
+    // 沒有 model 指標時用內建模板；下面 main() 會用實際模型的模板重做
+    (void) tmpl;
+    size_t n_chars = 0;
+    for (const auto & m : st.msgs) {
+        n_chars += strlen(m.role) + strlen(m.content) + 32;
+    }
+    std::vector<char> buf(2 * n_chars + 1024);
+    const char * t = st.msgs.empty() ? nullptr : nullptr;
+    (void) t;
+    int32_t len = llama_chat_apply_template(tmpl, st.msgs.data(), st.msgs.size(), true,
+                                            buf.data(), (int32_t) buf.size());
+    if (len > (int32_t) buf.size()) {
+        buf.resize(len + 1);
+        llama_chat_apply_template(tmpl, st.msgs.data(), st.msgs.size(), true,
+                                  buf.data(), (int32_t) buf.size());
+    }
+    return std::string(buf.data());
+}
+
+} // namespace
+
+#include <execinfo.h>
+#include <signal.h>
+#include <unistd.h>
+static void sdq_segv(int sig) {
+    void * bt[64];
+    const int n = backtrace(bt, 64);
+    fprintf(stderr, "\n*** sdq: signal %d, backtrace:\n", sig);
+    backtrace_symbols_fd(bt, n, 2);
+    _exit(9);
+}
+
+// eval callback：把感興趣的張量（用 SDQ_DUMP_NAMES 指定）寫進檔案
+struct dump_state {
+    FILE * fp = nullptr;
+    uint64_t step = 0;
+    std::vector<std::string> names;
+};
+
+static dump_state g_dump;
+
+static bool sdq_eval_callback(ggml_tensor * t, bool ask, void * user_data) {
+    (void) user_data;
+    auto & ds = g_dump;
+    if (ask) {
+        // 除錯模式：每個節點都要資料 → 會強制逐節點同步（慢，但能逐節點比對）
+        return ds.fp != nullptr;
+    }
+    if (!ds.fp) {
+        return false;
+    }
+    const char * nm = ggml_get_name(t);
+    const size_t n_len = nm ? strlen(nm) : 0;
+    bool want = ds.names.empty();
+    for (const auto & n : ds.names) {
+        if (nm && strstr(nm, n.c_str())) {
+            want = true;
+            break;
+        }
+    }
+    const int32_t ne[4] = {(int32_t) t->ne[0], (int32_t) t->ne[1], (int32_t) t->ne[2], (int32_t) t->ne[3]};
+    const int32_t type = (int32_t) t->type;
+    fwrite(&n_len, sizeof(size_t), 1, ds.fp);
+    if (n_len) {
+        fwrite(nm, 1, n_len, ds.fp);
+    }
+    fwrite(&ds.step, sizeof(uint64_t), 1, ds.fp);
+    fwrite(ne, sizeof(int32_t), 4, ds.fp);
+    fwrite(&type, sizeof(int32_t), 1, ds.fp);
+
+    // 永遠寫「摘要」（前 8 個值 + 平方和 + 最大值），這樣即使沒有名字也能 A/B 找出第一個分歧點
+    float summary[10] = {0};
+    if (t->type == GGML_TYPE_F32 && t->data) {
+        const size_t n = (size_t) ne[0] * ne[1] * ne[2] * ne[3];
+        const float * p = (const float *) t->data;
+        double ss = 0;
+        float mx = 0;
+        for (size_t i = 0; i < n; i++) {
+            ss += (double) p[i] * p[i];
+            if (std::fabs(p[i]) > std::fabs(mx)) {
+                mx = p[i];
+            }
+        }
+        for (int i = 0; i < 8 && (size_t) i < n; i++) {
+            summary[i] = p[i];
+        }
+        summary[8] = (float) std::sqrt(ss);
+        summary[9] = mx;
+        fwrite(summary, sizeof(float), 10, ds.fp);
+        if (want) {
+            fwrite(p, sizeof(float), n, ds.fp);
+        }
+    } else {
+        fwrite(summary, sizeof(float), 10, ds.fp);
+    }
+    ds.step++;
+    return true;   // 這個節點的資料我們已經讀過了，標記成已完成
+}
+
+int main(int argc, char ** argv) {
+    signal(SIGSEGV, sdq_segv);
+    signal(SIGBUS, sdq_segv);
+    signal(SIGABRT, sdq_segv);
+    options opt;
+    const char * env_model = getenv("SDQ_MODEL_PATH");
+    if (env_model) {
+        opt.model = env_model;
+    }
+
+    for (int i = 1; i < argc; i++) {
+        std::string a = argv[i];
+        auto next = [&](const char * what) -> std::string {
+            if (i + 1 >= argc) {
+                fprintf(stderr, "%s 需要參數\n", what);
+                exit(1);
+            }
+            return argv[++i];
+        };
+        if (a == "-m" || a == "--model")        opt.model = next("-m");
+        else if (a == "-p" || a == "--prompt")  opt.prompt = next("-p");
+        else if (a == "--sys")                  opt.system = next("--sys");
+        else if (a == "-c" || a == "--ctx")     opt.n_ctx = atoi(next("-c").c_str());
+        else if (a == "-n")                     opt.n_predict = atoi(next("-n").c_str());
+        else if (a == "-t")                     opt.n_threads = atoi(next("-t").c_str());
+        else if (a == "-b" || a == "--ubatch")  opt.n_ubatch = atoi(next("-b").c_str());
+        else if (a == "--temp")                 opt.temp = atof(next("--temp").c_str());
+        else if (a == "--top-p")                opt.top_p = atof(next("--top-p").c_str());
+        else if (a == "--top-k")                opt.top_k = atoi(next("--top-k").c_str());
+        else if (a == "--no-chat")              opt.chat = false;
+        else if (a == "--no-interactive")       opt.interactive = false;
+        else if (a == "--bench")                opt.bench = true;
+        else if (a == "--no-prefetch")          opt.no_prefetch = true;
+        else if (a == "--arena-mb")             opt.arena_mb = atoi(next("--arena-mb").c_str());
+        else if (a == "--ram-budget-mb")        opt.ram_budget_mb = atoi(next("--ram-budget-mb").c_str());
+        else if (a == "--no-fadvise")           opt.fadvise = false;
+        else if (a == "--stats-file")           opt.stats_file = next("--stats-file");
+        else if (a == "--dump-logits")          opt.dump_logits = true;
+        else if (a == "--logits-out")           opt.logits_out = next("--logits-out");
+        else if (a == "--selftest")            opt.selftest = next("--selftest");
+        else if (a == "--selftest-limit")      opt.selftest_limit = (float) atof(next("--selftest-limit").c_str());
+        else if (a == "--selftest-xscale")     opt.selftest_xscale = (float) atof(next("--selftest-xscale").c_str());
+        else if (a == "--selftest-mode")       opt.selftest_mode  = atoi(next("--selftest-mode").c_str());
+        else if (a == "--dump-tensors")        opt.dump_tensors = next("--dump-tensors");
+        else if (a == "--no-pager")            opt.no_pager = true;
+        else if (a == "--span-test")           opt.span_test = next("--span-test");
+        else if (a == "-h" || a == "--help") {
+            printf(
+                "用法：sdq-chat -m <model.gguf> [選項]\n"
+                "  -c, --ctx N          上下文長度（預設 4096；模型原生 262144）\n"
+                "  -n N                 要生成的 token 數\n"
+                "  -t N                 CPU 執行緒數\n"
+                "  -b N                 ubatch 大小\n"
+                "  -p, --prompt TEXT    提示詞\n"
+                "  --sys TEXT           system 訊息\n"
+                "  --no-chat            不要套 chat template（純 completion）\n"
+                "  --no-interactive     跑完提示詞就結束\n"
+                "  --bench              benchmark 模式（輸出 JSON 到 stats 檔）\n"
+                "  --arena-mb N         expert arena 大小（MB）\n"
+                "  --ram-budget-mb N    RAM 總預算（MB），arena 會配合縮減\n"
+                "  --no-prefetch        關閉背景預取\n"
+                "  --no-fadvise         讀完不丟 kernel page cache（會讓 RAM 帳目失真）\n"
+                "  --stats-file PATH    指標 JSONL 輸出\n"
+                "  --dump-logits        把每個 token 的 logits 存檔（驗證用）\n"
+                "  --logits-out PATH    logits 輸出路徑\n");
+            return 0;
+        } else {
+            fprintf(stderr, "未知參數：%s（用 --help 看用法）\n", a.c_str());
+            return 1;
+        }
+    }
+
+    if (opt.model.empty()) {
+        fprintf(stderr, "缺少模型檔（-m 或 SDQ_MODEL_PATH）\n");
+        return 1;
+    }
+
+    // ---- 環境變數（pager 讀）
+    setenv("SDQ_MODEL_PATH", opt.model.c_str(), 1);
+    // I/O 讀取執行緒數：預設 3 × 計算執行緒（上限 48）。
+    // 必須在這裡設定 —— pager 的 I/O 池是在「載入模型」時啟動的，那已經比
+    // context 建立早了；放到後面設定會讓池子只拿到下限 4 條執行緒。
+    // 量測（repeat=3，中位數）：序列讀 3.79 → 12 條 5.84 → 24 條 6.68 tok/s。
+    if (!getenv("SDQ_IO_THREADS")) {
+        const int hw_io = (int) std::max(1u, std::thread::hardware_concurrency());
+        const int dflt_io = hw_io < 8 ? hw_io : 8;
+        const int n_io   = opt.n_threads > 0 ? opt.n_threads : dflt_io;
+        setenv("SDQ_IO_THREADS", std::to_string(n_io * 3).c_str(), 1);
+    }
+    // 只有明確指定時才設定，否則保留呼叫者從環境變數傳入的值
+    // （舊版無條件 setenv 會讓 SDQ_PREFETCH=0 被悄悄蓋回 1，除錯時極易誤判）
+    if (opt.no_prefetch) {
+        setenv("SDQ_PREFETCH", "0", 1);
+    }
+    setenv("SDQ_FADV_DONTNEED", opt.fadvise ? "1" : "0", 1);
+    if (opt.arena_mb > 0) {
+        setenv("SDQ_ARENA_MB", std::to_string(opt.arena_mb).c_str(), 1);
+    }
+    if (opt.ram_budget_mb > 0) {
+        setenv("SDQ_RAM_BUDGET_MB", std::to_string(opt.ram_budget_mb).c_str(), 1);
+    }
+    if (!opt.stats_file.empty()) {
+        setenv("SDQ_STATS_FILE", opt.stats_file.c_str(), 1);
+    }
+
+    llama_backend_init();
+    llama_numa_init(GGML_NUMA_STRATEGY_DISABLED);
+
+    // ---- 模型載入：expert 權重交給 pager 的 buffer type（0 RAM）
+    llama_model_params mparams = llama_model_default_params();
+    mparams.n_gpu_layers = 0;
+    mparams.load_mode = LLAMA_LOAD_MODE_MMAP;
+    if (!opt.no_pager) {
+        sdq_set_enabled(true);
+        sdq_install_buft_overrides(&mparams);
+    } else {
+        printf("[sdq] --no-pager：對照模式，專家權重全部留在 RAM（需要 %s RAM）\n", "22GB");
+    }
+
+    printf("[sdq] 載入模型：%s\n", opt.model.c_str());
+    const double t_load0 = now_s();
+    llama_model * model = llama_model_load_from_file(opt.model.c_str(), mparams);
+    if (!model) {
+        fprintf(stderr, "[sdq] 模型載入失敗\n");
+        return 1;
+    }
+    const double t_load = now_s() - t_load0;
+
+    // ---- pager 初始化（讀 GGUF 檔頭、建頁面表、配置 arena）
+    auto & P = pager::instance();
+    if (!opt.no_pager && !sdq_init(opt.model)) {
+        fprintf(stderr, "[sdq] pager 初始化失敗\n");
+        return 1;
+    }
+
+    // ---- 張量 dump（A/B 比對用）：在 op 真的算完的那一刻把資料寫出來
+    FILE * tensor_fp = nullptr;
+    dump_state dump_state_;
+    if (!opt.dump_tensors.empty()) {
+        tensor_fp = fopen(opt.dump_tensors.c_str(), "wb");
+        dump_state_.fp = tensor_fp;
+        if (const char * names = getenv("SDQ_DUMP_NAMES")) {
+            std::string s = names;
+            size_t pos = 0;
+            while (pos <= s.size()) {
+                size_t c = s.find(',', pos);
+                if (c == std::string::npos) c = s.size();
+                dump_state_.names.push_back(s.substr(pos, c - pos));
+                pos = c + 1;
+            }
+        }
+        g_dump = dump_state_;
+    }
+
+    // ---- context
+    llama_context_params cparams = llama_context_default_params();
+    cparams.n_ctx = (uint32_t) opt.n_ctx;
+    cparams.n_batch = (uint32_t) opt.n_ctx;
+    // ubatch 預設 128（不是 512）。理由是「8 GB 預算要真的裝得下」：
+    // llama.cpp 的 CPU compute buffer 是按 n_ubatch 線性成長的，實測
+    //   ubatch=512 → 502 MiB、256 → 251 MiB、128 → 125.5 MiB
+    // 而 compute buffer 是在 pager 算完 arena 大小之後才配置的，所以它不算在
+    // arena 的扣減裡。實測在 RLIMIT_DATA 8 GB 下：
+    //   ubatch=512 → 提示詞超過 ~256 token 直接 std::bad_alloc（崩潰）
+    //   ubatch=256 → 同一個提示詞一樣崩潰
+    //   ubatch=128 → 正常，681 token 的 prefill 跑到 28.8 tok/s
+    // 而且 ubatch=128 還更快（docs/04 實測 +7%），因為 prefill 分更多批、
+    // 每批的 expert 聯集比較小、命中率比較高。
+    cparams.n_ubatch = opt.n_ubatch > 0 ? (uint32_t) opt.n_ubatch : (uint32_t) std::min(opt.n_ctx, 128);
+    // 執行緒預設值：不要直接用 hardware_concurrency()。
+    // 實測（docs/04，repeat=3）：mode C 下 t=8 最快，給更多執行緒反而變慢 ——
+    //   t=8 4.02 / t=10 3.79 / t=12 3.55 / t=16 3.60 tok/s
+    // 原因很直接：每層每 token 只有 n_expert_used = 8 個 expert 可以平行，
+    // 執行緒超過 8 之後就只是多開執行緒搶同一批 CPU。
+    // 下限取實際核心數，避免在 4 核心的目標機器上開太多。
+    const int hw = (int) std::max(1u, std::thread::hardware_concurrency());
+    const int dflt_threads = hw < 8 ? hw : 8;
+    cparams.n_threads = opt.n_threads > 0 ? opt.n_threads : (int32_t) dflt_threads;
+    cparams.n_threads_batch = cparams.n_threads;
+    if (!opt.stats_file.empty()) {
+        cparams.offload_kqv = false;
+    }
+
+    if (tensor_fp) {
+        cparams.cb_eval = sdq_eval_callback;
+        cparams.cb_eval_user_data = &g_dump;
+    }
+
+    llama_context * ctx = llama_init_from_model(model, cparams);
+    if (!ctx) {
+        fprintf(stderr, "[sdq] context 建立失敗（ctx=%d 太大？）\n", opt.n_ctx);
+        return 1;
+    }
+
+    printf("[sdq] ctx=%d  threads=%d  ubatch=%u  RAM(RSS)=%zu MB  模型載入 %.1fs\n",
+           opt.n_ctx, cparams.n_threads, cparams.n_ubatch, rss_mb(), t_load);
+    print_mem_report("載入 + pager 後");
+
+    // ---- sampler
+    auto sparams = llama_sampler_chain_default_params();
+    sparams.no_perf = true;
+    llama_sampler * smpl = llama_sampler_chain_init(sparams);
+    llama_sampler_chain_add(smpl, llama_sampler_init_top_k(opt.top_k));
+    llama_sampler_chain_add(smpl, llama_sampler_init_top_p(opt.top_p, 1));
+    llama_sampler_chain_add(smpl, llama_sampler_init_temp(opt.temp));
+    llama_sampler_chain_add(smpl, llama_sampler_init_dist(LLAMA_DEFAULT_SEED));
+
+    chat_state st;
+    if (!opt.system.empty()) {
+        st.msgs.push_back({"system", opt.system.c_str()});
+    }
+
+    std::vector<llama_token> decoded;
+
+    const llama_vocab * vocab = llama_model_get_vocab(model);
+
+    auto tokenize = [&](const std::string & text) {
+        std::vector<llama_token> toks(text.size() + 16);
+        int32_t n = llama_tokenize(vocab, text.c_str(), (int32_t) text.size(),
+                                   toks.data(), (int32_t) toks.size(), true, true);
+        if (n < 0) {
+            toks.resize((size_t) -n);
+            n = llama_tokenize(vocab, text.c_str(), (int32_t) text.size(),
+                               toks.data(), (int32_t) toks.size(), true, true);
+        }
+        toks.resize(n);
+        return toks;
+    };
+
+    // ---- 送進去一個 ubatch，回傳生成的 token（-1 = 需要繼續生成）
+    std::function<int(llama_token, bool)> submit;
+    uint64_t n_prefill_tok = 0;
+    double t_prefill = 0;
+    uint64_t n_decode_tok = 0;
+    double t_decode = 0;
+    uint64_t io_read0 = read_bytes_io();
+
+    std::vector<float> logits_store;
+    FILE * logits_fp = nullptr;
+    if (opt.dump_logits) {
+        logits_fp = fopen(opt.logits_out.empty() ? "sdq_logits.bin" : opt.logits_out.c_str(), "wb");
+    }
+
+    submit = [&](llama_token tok, bool last) -> int {
+        const uint32_t ctx_size = llama_n_ctx(ctx);
+        llama_memory_t mem = llama_get_memory(ctx);
+        if (tok == 1) { // BOS：重開記憶體
+            llama_memory_clear(mem, true);
+            decoded.clear();
+        }
+        if (decoded.size() >= opt.n_ctx - 4) {
+            // 環形丟掉最舊的 token（保留 opt.n_keep）
+            const size_t drop = decoded.size() - (size_t) opt.n_keep;
+            llama_memory_seq_rm(mem, 0, 0, (int32_t) drop);
+            decoded.erase(decoded.begin(), decoded.begin() + (long) drop);
+        }
+
+        llama_batch b = llama_batch_get_one((llama_token *) &tok, 1);
+
+        const bool is_prefill = decoded.empty();
+        const double t0 = now_s();
+        const int rc = llama_decode(ctx, b);
+        const double dt = now_s() - t0;
+        if (rc != 0) {
+            fprintf(stderr, "\n[sdq] llama_decode 失敗 rc=%d（記憶體不足？）\n", rc);
+            exit(3);
+        }
+        decoded.push_back(tok);
+
+        // 每個 ubatch 結束 → 更新路由歷史並觸發下一輪預取
+        P.end_token();
+
+        if (is_prefill) {
+            n_prefill_tok++;
+            t_prefill += dt;
+        } else {
+            n_decode_tok++;
+            t_decode += dt;
+            P.get_stats().tokens.fetch_add(1, std::memory_order_relaxed);
+        }
+
+        if (logits_fp) {
+            const int32_t n_logits = llama_vocab_n_tokens(vocab);
+            const float * lg = llama_get_logits_ith(ctx, -1);
+            if (lg) {
+                logits_store.assign(lg, lg + n_logits);
+                fwrite(&n_logits, sizeof(int32_t), 1, logits_fp);
+                fwrite(logits_store.data(), sizeof(float), n_logits, logits_fp);
+                fflush(logits_fp);
+            }
+        }
+
+        if (last) {
+            return -1;
+        }
+        const llama_token id = llama_sampler_sample(smpl, ctx, -1);
+        return (int) id;
+    };
+
+    // ---- 產生 prompt
+    auto run_prompt = [&](const std::string & user_text, bool add_to_history) {
+        if (opt.chat) {
+            st.msgs.push_back({"user", user_text.c_str()});
+        }
+        std::string text;
+        if (opt.chat) {
+            const char * tmpl = llama_model_chat_template(model, nullptr);
+            size_t n_chars = 0;
+            for (const auto & m : st.msgs) {
+                n_chars += strlen(m.role) + strlen(m.content) + 32;
+            }
+            std::vector<char> buf(2 * n_chars + 1024);
+            int32_t len = llama_chat_apply_template(tmpl, st.msgs.data(), st.msgs.size(),
+                                                    true, buf.data(), (int32_t) buf.size());
+            if (len > (int32_t) buf.size()) {
+                buf.resize((size_t) len + 1);
+                llama_chat_apply_template(tmpl, st.msgs.data(), st.msgs.size(), true,
+                                          buf.data(), (int32_t) buf.size());
+            }
+            text.assign(buf.data());
+        } else {
+            text = user_text;
+        }
+
+        auto toks = tokenize(text);
+        const int n_prompt = (int) toks.size();
+        const uint64_t io0 = read_bytes_io();
+
+        // 分批送進去（每批 = 一個 ubatch，控制記憶體）
+        const int32_t ub = (int32_t) cparams.n_ubatch;
+        llama_sampler_reset(smpl);
+        int32_t pos = 0;
+        for (int32_t i = 0; i < n_prompt; i += ub) {
+            const int32_t n = std::min(ub, n_prompt - i);
+            llama_batch b = llama_batch_init((uint32_t) n, 0, 1);
+            for (int32_t j = 0; j < n; j++) {
+                b.token[j] = toks[i + j];
+                b.pos[j] = pos++;
+                b.n_seq_id[j] = 1;
+                b.seq_id[j][0] = 0;
+            }
+            b.n_tokens = (uint32_t) n;
+            const double t0 = now_s();
+            const int rc = llama_decode(ctx, b);
+            t_prefill += now_s() - t0;
+            n_prefill_tok += (uint64_t) n;
+            if (rc != 0) {
+                fprintf(stderr, "\n[sdq] prefill 失敗 rc=%d（%d tokens）\n", rc, n);
+                exit(3);
+            }
+            P.end_token();
+            llama_batch_free(b);
+        }
+        const double t_p = now_s();
+        (void) t_p;
+        (void) io0;
+
+        if (add_to_history && opt.chat) {
+            st.msgs.push_back({"assistant", ""});
+        }
+        return n_prompt;
+    };
+
+    // ---- 產生
+    auto generate = [&](int32_t n_max) {
+        const uint64_t io0 = read_bytes_io();
+        const uint64_t io_read_before = io0;
+        (void) io_read_before;
+        const double t0 = now_s();
+        int32_t n_gen = 0;
+        llama_token id = llama_sampler_sample(smpl, ctx, -1);
+        fputs("assistant: ", stdout);
+        fflush(stdout);
+        while (n_gen < n_max) {
+            const int rc = submit(id, /*last=*/n_gen + 1 >= n_max);
+            if (rc < 0) {
+                break;
+            }
+            id = (llama_token) rc;
+            char piece_buf[256];
+            const int n_piece = llama_token_to_piece(vocab, id, piece_buf, sizeof(piece_buf), 0, true);
+            const std::string piece(piece_buf, (size_t) std::max(0, n_piece));
+            fputs(piece.c_str(), stdout);
+            fflush(stdout);
+            n_gen++;
+        }
+        fputs("\n", stdout);
+        const double dt = now_s() - t0;
+        const uint64_t io1 = read_bytes_io();
+        fprintf(stderr, "[sdq] decode: %d tok / %.2fs = %.2f tok/s | SSD 讀 %.1f MB (%.1f MB/tok) | RSS %zu MB\n",
+                n_gen, dt, dt > 0 ? n_gen / dt : 0.0,
+                (io1 - io0) / 1048576.0, n_gen ? (io1 - io0) / 1048576.0 / n_gen : 0.0, rss_mb());
+        if (opt.chat) {
+            for (auto & m : st.msgs) {
+                if (strcmp(m.role, "assistant") == 0) {
+                    m.content = "";
+                }
+            }
+        }
+        P.dump_stats("decode");
+        return n_gen;
+    };
+
+    // ---- 合併讀取自我測試：--span-test IL:E0:E1:...
+    if (!opt.span_test.empty()) {
+        std::vector<int> parts;
+        std::string cur_s;
+        for (char ch : opt.span_test + ":") {
+            if (ch == ':') { parts.push_back(atoi(cur_s.c_str())); cur_s.clear(); }
+            else cur_s += ch;
+        }
+        if (parts.size() < 3) {
+            fprintf(stderr, "用法：--span-test IL:E0:E1[:E2...]（E 要連續）\n");
+            return 1;
+        }
+        const int il = parts[0];
+        std::vector<int32_t> ex;
+        for (size_t i = 1; i < parts.size(); i++) {
+            ex.push_back(parts[i]);
+        }
+        std::vector<int32_t> slots(ex.size(), -1);
+        for (size_t i = 0; i < ex.size(); i++) {
+            slots[i] = P.reserve_slot(il, ex[i]);
+        }
+        const uint64_t got = P.read_expert_span(il, ex.data(), (int) ex.size(), slots.data());
+        printf("[sdq-span-test] L%d experts=%zu 讀取 %.2f MB\n", il, ex.size(), got / 1048576.0);
+        int bad = 0;
+        for (size_t i = 0; i < ex.size(); i++) {
+            std::vector<uint8_t> one((size_t) P.layer(il)->experts[ex[i]].bytes, 0);
+            if (!P.read_expert(il, ex[i], one.data())) {
+                printf("  單獨讀取失敗\n");
+                return 1;
+            }
+            const uint8_t * span_ptr = P.slot_ptr(slots[i]);
+            size_t diff_at = (size_t) -1;
+            for (size_t b = 0; b < one.size(); b++) {
+                if (one[b] != span_ptr[b]) { diff_at = b; break; }
+            }
+            printf("  expert %4d: %s", ex[i], diff_at == (size_t) -1 ? "一致 ✅" : "不一致 ❌");
+            if (diff_at != (size_t) -1) {
+                printf("（第一個不同的 byte 在 %zu / %zu，slot=%d）", diff_at, one.size(), slots[i]);
+                bad++;
+            }
+            printf("\n");
+        }
+        sdq_shutdown();
+        llama_free(ctx);
+        llama_model_free(model);
+        llama_backend_free();
+        return bad ? 1 : 0;
+    }
+
+    // ---- 自我測試模式：--selftest IL:IE:SEED:OUT.bin
+    if (!opt.selftest.empty()) {
+        int il = 0, ie = 0, seed = 1234, n_tok = 1;
+        std::string outpath;
+        {
+            std::vector<std::string> parts;
+            std::string cur_s;
+            for (char c : opt.selftest + ":") {
+                if (c == ':') { parts.push_back(cur_s); cur_s.clear(); }
+                else cur_s += c;
+            }
+            if (parts.size() >= 3) {
+                il = atoi(parts[0].c_str());
+                ie = atoi(parts[1].c_str());
+                seed = atoi(parts[2].c_str());
+            }
+            if (parts.size() >= 4) {
+                outpath = parts[3];
+            }
+            if (parts.size() >= 5) {
+                n_tok = atoi(parts[4].c_str());
+            }
+        }
+        const int64_t n_embd = P.info().n_embd;
+        const int64_t n_ff = P.info().n_ff_exp;
+        std::vector<float> x((size_t) n_embd * n_tok);
+        uint32_t rng = (uint32_t) seed * 2654435761u + 1u;
+        for (auto & v : x) {
+            rng = rng * 1664525u + 1013904223u;
+            v = ((float) (rng >> 8) / (float) (1 << 24)) * 2.0f - 1.0f;
+        }
+        // xscale：把 activation 放大到 swiglu clamp 真的會生效的量級。
+        // 用預設的 1.0 時，4096 維點積出來的 gate/up 幾乎永遠小於 limit，
+        // clamp 兩種語意（silu 前夾 vs silu 後夾）會算出同一個結果 ——
+        // 那就等於沒有測到 clamp。用 50.0 時 gate 會到幾十，兩種語意差很多。
+        if (opt.selftest_xscale != 1.0f) {
+            for (auto & v : x) {
+                v *= opt.selftest_xscale;
+            }
+        }
+        std::vector<float> io((size_t) n_embd * n_tok * 2);
+        const int rc = sdq_moe_selftest(il, ie, x.data(), io.data(), n_embd, n_ff, n_tok,
+                                        opt.selftest_limit, opt.selftest_mode);
+        if (rc == 0 && !outpath.empty()) {
+            FILE * f = fopen(outpath.c_str(), "wb");
+            fwrite(io.data(), sizeof(float), io.size(), f);
+            fclose(f);
+            printf("[sdq] selftest 結果已寫到 %s（layer=%d expert=%d seed=%d n_embd=%lld n_ff=%lld "
+                   "limit=%g mode=%d）\n",
+                   outpath.c_str(), il, ie, seed, (long long) n_embd, (long long) n_ff,
+                   opt.selftest_limit, opt.selftest_mode);
+        }
+        sdq_shutdown();
+        llama_free(ctx);
+        llama_model_free(model);
+        llama_backend_free();
+        return rc;
+    }
+
+    // ---- 主流程
+    if (!opt.prompt.empty()) {
+        run_prompt(opt.prompt, true);
+        generate(opt.n_predict);
+    }
+
+    if (opt.bench) {
+        // benchmark：固定提示詞 ×3，量 prefill / decode / 分頁指標
+        const std::vector<std::string> prompts = {
+            "請用中文簡短介紹 SSD、RAM、CPU 之間的資料分層是什麼，以及為什麼快取很重要。",
+            "Write a short paragraph explaining how a mixture-of-experts model routes tokens to experts.",
+            "請列出十種日常會用到電腦的工作，並各用一句話說明。",
+        };
+        for (int round = 0; round < 3; round++) {
+            fprintf(stderr, "[bench] round %d\n", round);
+            llama_memory_clear(llama_get_memory(ctx), true);
+            decoded.clear();
+            P.get_stats().tokens.store(0);
+            run_prompt(prompts[round % prompts.size()], false);
+            generate(48);
+            P.dump_stats(round == 0 ? "bench_warm" : "bench_hot");
+        }
+    }
+
+    if (opt.interactive) {
+        printf("\n（輸入文字開始對話；/exit 離開、/reset 重設、/stats 顯示指標）\n");
+        std::string line;
+        while (true) {
+            printf("\nuser> ");
+            fflush(stdout);
+            if (!std::getline(std::cin, line)) {
+                break;
+            }
+            if (line == "/exit" || line == "/quit") {
+                break;
+            }
+            if (line == "/reset") {
+                llama_memory_clear(llama_get_memory(ctx), true);
+                decoded.clear();
+                st.msgs.clear();
+                if (!opt.system.empty()) {
+                    st.msgs.push_back({"system", opt.system.c_str()});
+                }
+                printf("（已重設）\n");
+                continue;
+            }
+            if (line == "/stats") {
+                P.dump_stats("manual");
+                fprintf(stderr, "hit_rate=%.1f%%  arena=%zu MB  RSS=%zu MB\n",
+                        P.hit_rate() * 100, P.used_bytes() / 1048576, rss_mb());
+                continue;
+            }
+            if (line.empty()) {
+                continue;
+            }
+            run_prompt(line, true);
+            generate(opt.n_predict);
+        }
+    }
+
+    P.get_stats().moe_calls.fetch_add(0);
+    sdq_shutdown();
+
+    fprintf(stderr, "\n[sdq] ===== 總結 =====\n");
+    fprintf(stderr, "[sdq] prefill: %" PRIu64 " tok / %.2fs = %.1f tok/s\n",
+            n_prefill_tok, t_prefill, t_prefill > 0 ? n_prefill_tok / t_prefill : 0.0);
+    const uint64_t io_end = read_bytes_io();
+    fprintf(stderr, "[sdq] 全程 SSD 實際讀取: %.2f GB\n", (io_end - io_read0) / 1073741824.0);
+    print_mem_report("結束時");
+
+    if (logits_fp) {
+        fclose(logits_fp);
+    }
+    llama_sampler_free(smpl);
+    llama_free(ctx);
+    llama_model_free(model);
+    llama_backend_free();
+    return 0;
+}

sdq-dsv4/sdq_moe.cpp

@@ -0,0 +1,758 @@
+// SDQ 被分頁的 MoE FFN（自訂 ggml op）
+//
+// 為什麼要自己算：上游 build_moe_ffn() 用 ggml_mul_mat_id 直接對
+//   blk.N.ffn_{gate,up,down}_exps.weight 這個「三維大張量」做矩陣乘，
+//   權重必須整個在 RAM 裡。20.6 GiB 的專家權重在 8 GB 機器上不可能。
+//
+// 這裡改成：
+//   1. 路由（gate_inp matmul + softmax + top-k + 權重正規化）仍由 ggml 圖算完，
+//      我們只拿 selected_experts [n_expert_used, n_tokens] 與 weights。
+//   2. 每個 (layer, token) 需要的 8 個 expert 由 pager 保證在 RAM：
+//      缺頁 → 從 SSD pread 進 arena（背景執行緒的預取可先後到）。
+//   3. 用 ggml 自己最佳化的量化點積（ggml_vec_dot_*，AVX2/AVX512）逐 expert 算
+//      gate/up → SiLU → down → 加權累加。
+//   4. 多執行緒：ith/nth 由 ggml 分配；分頁階段各執行緒各自 pread，餵飽 SSD 佇列深度。
+
+#include "sdq_pager.h"
+
+#include "ggml-cpu/quants.h"
+
+#include <algorithm>
+#include <atomic>
+#include <chrono>
+#include <cmath>
+#include <condition_variable>
+#include <cstdio>
+#include <cstring>
+#include <mutex>
+#include <utility>
+#include <string>
+#include <vector>
+
+namespace sdq {
+
+// ---------------------------------------------------------------- 效能計時探針
+// 用途：找出「自訂 MoE op」裡面時間到底花在哪裡。開 SDQ_PROFILE_TIME=1 才啟用，
+// 關閉時是零成本（幾個 if constexpr 級別的布林檢查）。
+struct moe_prof {
+    std::atomic<uint64_t> op_ns{0};        // 整個 op
+    std::atomic<uint64_t> page_ns{0};       // probe / reserve_slot（含鎖）
+    std::atomic<uint64_t> setup_ns{0};      // op 前置：unpin_all + 建 tok_of_expert + 前兩道 barrier
+    std::atomic<uint64_t> bar_ns{0};        // 所有 barrier 的等待時間
+    std::atomic<uint64_t> read_ns{0};       // read_expert_span / acquire 的 I/O
+    std::atomic<uint64_t> fwd_ns{0};        // expert_forward 合計
+    std::atomic<uint64_t> qact_ns{0};       // 其中：量化 activation
+    std::atomic<uint64_t> dot_ns{0};        // 其中：gate/up/down 三次點積
+    std::atomic<uint64_t> act_ns{0};        // 其中：SiLU + 加權
+    std::atomic<uint64_t> calls{0};
+    std::atomic<uint64_t> experts{0};
+};
+static moe_prof g_prof;
+
+static inline bool prof_on() {
+    static const bool on = [] { const char * e = getenv("SDQ_PROFILE_TIME"); return e && *e && *e != '0'; }();
+    return on;
+}
+static inline uint64_t now_ns() {
+    return (uint64_t) std::chrono::duration_cast<std::chrono::nanoseconds>(
+        std::chrono::steady_clock::now().time_since_epoch()).count();
+}
+#define PROF_T0_x(v) const uint64_t v = prof_on() ? now_ns() : 0
+#define PROF_ADD(field, tv) do { if (prof_on()) g_prof.field += now_ns() - (tv); } while (0)
+
+// ---------------------------------------------------------------- 執行緒柵欄
+
+class gen_barrier {
+public:
+    void sync(int n) {
+        PROF_T0_x(_tbar);
+        std::unique_lock<std::mutex> lk(mu_);
+        const unsigned long g = gen_;
+        if (++count_ == n) {
+            count_ = 0;
+            gen_++;
+            cv_.notify_all();
+            PROF_ADD(bar_ns, _tbar);
+            return;
+        }
+        cv_.wait(lk, [this, g] { return gen_ != g; });
+        PROF_ADD(bar_ns, _tbar);
+    }
+
+private:
+    int count_ = 0;
+    unsigned long gen_ = 0;
+    std::mutex mu_;
+    std::condition_variable cv_;
+};
+
+// ---------------------------------------------------------------- 量化點積派送
+
+using vec_dot_fn = void (*)(int, float *, size_t, const void *, size_t, const void *, size_t, int);
+
+static vec_dot_fn dot_for(ggml_type t) {
+    switch (t) {
+        case GGML_TYPE_Q4_K:   return ggml_vec_dot_q4_K_q8_K;
+        case GGML_TYPE_Q5_K:   return ggml_vec_dot_q5_K_q8_K;
+        case GGML_TYPE_Q6_K:   return ggml_vec_dot_q6_K_q8_K;
+        case GGML_TYPE_Q3_K:   return ggml_vec_dot_q3_K_q8_K;
+        case GGML_TYPE_Q2_K:   return ggml_vec_dot_q2_K_q8_K;
+        case GGML_TYPE_Q8_0:   return ggml_vec_dot_q8_0_q8_0;
+        case GGML_TYPE_Q4_0:   return ggml_vec_dot_q4_0_q8_0;
+        case GGML_TYPE_Q5_0:   return ggml_vec_dot_q5_0_q8_0;
+        // Qwen3.8-Flash-Next 的 down_exps 用 q5_1（unsloth UD-Q4_K_XL）。
+        // q5_1 在 ggml 裡配的是 q8_1 activation（見 type_traits：q5_1 的
+        // vec_dot_type 是 q8_1），不是 q8_0 —— 配錯會整層數值錯掉。
+        case GGML_TYPE_Q5_1:   return ggml_vec_dot_q5_1_q8_1;
+        case GGML_TYPE_IQ4_NL: return ggml_vec_dot_iq4_nl_q8_0;
+        case GGML_TYPE_IQ4_XS: return ggml_vec_dot_iq4_xs_q8_K;
+        // ---- DeepSeek-V4-Flash-0731（deepseek4，unsloth UD-IQ4_NL）----
+        // gate/up_exps = IQ3_S（42 層；layer 26 是 MXFP4）、down_exps = MXFP4。
+        // 這兩個型別是 UD-IQ4_NL 量化才會出現的，SDQ 原版沒認得，
+        // 症狀是每一層都印「不支援的專家量化型別」然後什麼都不算。
+        // 配對��須照 ggml 的 type_traits：
+        //   IQ3_S.vec_dot_type = Q8_K、MXFP4.vec_dot_type = Q8_0。
+        case GGML_TYPE_IQ3_S:  return ggml_vec_dot_iq3_s_q8_K;
+        case GGML_TYPE_MXFP4:  return ggml_vec_dot_mxfp4_q8_0;
+        default:               return nullptr;
+    }
+}
+
+// K-quant 的權重配 Q8_K activation；其餘配 Q8_0（與 ggml 的 vec_dot_type 一致）
+static ggml_type act_type_for(ggml_type w) {
+    switch (w) {
+        case GGML_TYPE_Q4_K:
+        case GGML_TYPE_Q5_K:
+        case GGML_TYPE_Q6_K:
+        case GGML_TYPE_Q3_K:
+        case GGML_TYPE_Q2_K:
+        case GGML_TYPE_IQ4_XS:
+            return GGML_TYPE_Q8_K;
+        // q5_1 配 q8_1（q5_1 的 min 值是 fp16，不是 q8_0 的 0）
+        case GGML_TYPE_Q5_1:
+            return GGML_TYPE_Q8_1;
+        // IQ3_S 配 Q8_K（iq3_s 的 6-bit scale 組出來的值範圍大於 q8_0 的 ±127）
+        case GGML_TYPE_IQ3_S:
+            return GGML_TYPE_Q8_K;
+        // MXFP4 配 Q8_0（E2M1 的值只有 0/±0.5/±1/±1.5/±2/±3/±4/±6，q8_0 綽綽有餘）
+        case GGML_TYPE_MXFP4:
+            return GGML_TYPE_Q8_0;
+        default:
+            return GGML_TYPE_Q8_0;
+    }
+}
+
+// 把 activation 量化成對應的 dot 型別
+// 注意：ggml_quantize_chunk() 不支援 Q8_K（Q8_K 只在 mul_mat kernel 內部產生），
+// 所以這裡直接呼叫 ggml-cpu 的 quantize_row_q8_K。
+static void quantize_act(ggml_type t, const float * x, void * dst, int64_t n) {
+    switch (t) {
+        case GGML_TYPE_Q8_K:  quantize_row_q8_K(x, dst, n); break;
+        case GGML_TYPE_Q8_1:  quantize_row_q8_1(x, dst, n); break;
+        case GGML_TYPE_Q8_0:  quantize_row_q8_0(x, dst, n); break;
+        default:              ggml_quantize_chunk(t, x, dst, 0, 1, n, nullptr); break;
+    }
+}
+
+// ⚠️ 不要在這裡「批次化」點積。
+// ggml 的 x86 版 K-quant kernel（ggml/src/ggml-cpu/arch/x86/quants.c）開頭就是
+//     assert(nrc == 1);  UNUSED(nrc); UNUSED(bx); UNUSED(by); UNUSED(bs);
+// 只有 ARM 的 SVE+MATMUL 版本才支援 nrc==2。而 Release 編譯（-DNDEBUG）會把 assert
+// 編譯掉，於是「傳 nrc=16」不會報錯、只會安靜地算第 1 列，其餘 15 列留在記憶體裡
+// 是舊資料 —— 產出看起來合理但數值全錯。
+// （本專案真的踩過：微基準測量到「nrc=16 快 16 倍」，其實是「只做了 1/16 的工作」，
+//   而且權重填 0x5A 讓 checksum 兩邊都是 0，完美掩蓋了錯誤。教訓見 docs/04。）
+// 想要真的多列 SIMD 效能，只能自己寫 AVX512-VNNI 的 kernel，不是靠改參數。
+
+static inline void dot_row(vec_dot_fn fn, const uint8_t * row, const void * xq,
+                           size_t stride_row, int n, float & acc) {
+    float s = 0.0f;
+    fn(n, &s, 0, row, stride_row, xq, 0, 1);
+    acc += s;
+}
+
+// 一次算 SDQ_DOT_BATCH 個輸出列。
+// 為什麼需要：ggml 的 K-quant 點積 kernel 是為「多列」設計的，nrc>1 會走完全不同的
+// SIMD 路徑。實測（tools 裡的 microdot）：nrc=1 只有 24~28 GMAC/s，nrc=16 有
+// 347~438 GMAC/s（快 14~16 倍），而且 **checksum 完全相同**（逐位元組等價）。
+// 舊程式逐列呼叫 nrc=1，等於把 14 倍的效能丟掉。
+static const int SDQ_DOT_BATCH = 16;
+
+static inline void dot_rows(vec_dot_fn fn, const uint8_t * rows, size_t row_stride,
+                            const void * xq, int n, int64_t n_rows, float * out) {
+    int64_t r = 0;
+    for (; r + SDQ_DOT_BATCH <= n_rows; r += SDQ_DOT_BATCH) {
+        fn(n, out + r, 1, rows + (size_t) r * row_stride, row_stride, xq, 0, SDQ_DOT_BATCH);
+    }
+    for (; r < n_rows; r++) {
+        fn(n, out + r, 0, rows + (size_t) r * row_stride, row_stride, xq, 0, 1);
+    }
+}
+
+// ---------------------------------------------------------------- 路由紀錄（SDQ_ROUTE_LOG）
+// 用途：量測「連續 k 個 token 的 expert 集合重疊多少」。
+// 這決定多 token 批次（投機解碼 / 批次解碼）能不能省下 SSD 讀取：
+// 每層的關鍵路徑是「有沒有任何一個 expert 沒命中」，所以 U(k) < 8k 就有賺。
+// 格式（每行一次 op 呼叫，空白分欄）：
+//   <layer> <n_tok> <t0:e0,e1,...> <t1:...> ...
+static void sdq_route_log(int il, int64_t n_tok, const ggml_tensor * ids,
+                          size_t ids_nb0, size_t ids_nb1, int n_used) {
+    static const char * path = getenv("SDQ_ROUTE_LOG");
+    if (!path || !*path) {
+        return;
+    }
+    static std::mutex mtx;
+    static FILE * f = nullptr;
+    {
+        std::lock_guard<std::mutex> lk(mtx);
+        if (!f) {
+            f = fopen(path, "w");
+        }
+        if (!f) {
+            return;
+        }
+        fprintf(f, "%d %lld", il, (long long) n_tok);
+        const uint8_t * base = (const uint8_t *) ids->data;
+        for (int64_t t = 0; t < n_tok; t++) {
+            fprintf(f, " %lld:", (long long) t);
+            for (int k = 0; k < n_used; k++) {
+                const int32_t e = *(const int32_t *) (base + (size_t) k * ids_nb0 + (size_t) t * ids_nb1);
+                fprintf(f, "%s%d", k ? "," : "", e);
+            }
+        }
+        fputc('\n', f);
+    }
+}
+
+// ---------------------------------------------------------------- SiLU-gated 激活
+//
+// ⚠️ 這裡的 clamp 語意**必須**逐字對齊上游，否則每一層的數值都是錯的（而且是
+// 「看起來合理」的錯：文字大致通順、只是品質變差）。
+//
+// deepseek4 / glm5_next / maple 走的是 ggml 的融合算子 ggml_swiglu_clamp
+// （ggml/src/ggml-cpu/ops.cpp）：
+//     gate = min(gate, limit);          // ← 只有上界，不夾下界
+//     up   = clamp(up, -limit, limit);  //    對稱
+//     out  = silu(gate) * up;
+//
+// SDQ 原版（qwen4exp 用的是上游的另一條分支）夾的是 **silu 之後** 的 gate，而且是
+// 對稱的：
+//     gc   = clamp(silu(gate), -limit, limit);
+//     out  = gc * clamp(up, -limit, limit);
+// 兩者數學上不等價，而且 clamp 的位置不同（gate 前 vs gate 後）。
+// 這個 repo 預設走 mode 1（deepseek4 實測用的那一條）；mode 0 保留給舊模型。
+// ---------------------------------------------------------------- 每層執行紀錄
+
+// 重要：input 張量的指標**不能**在建圖時暫存起來 —— llama.cpp 每次 decode 都會
+// 重新建圖，graph context 的配置器可能把張量搬到不同位址（形狀不同時尤其明顯）。
+// 所以 op 執行時一律從 dst->src[] 取得，這才是唯一可靠的來源。
+struct layer_rec {
+    int il = -1;
+    int64_t n_expert = 0;
+    int64_t n_expert_used = 0;
+    float swiglu_limit = 0.0f;
+    int   swiglu_mode  = SDQ_SWIGLU_LEGACY_POST_SILU;
+
+    // 每個 expert 需要處理的 (token, topk 位置) 配對
+    std::vector<std::vector<std::pair<int32_t, int32_t>>> tok_of_expert;
+    // 每個 token 用到的 (expert, topk 位置) —— token 切分時用（避免輸出競爭）
+    std::vector<std::vector<std::pair<int32_t, int32_t>>> exp_of_tok;
+    std::vector<int32_t> need;             // 本層要用的 expert 編號
+    std::vector<int32_t> need_sorted;      // 依編號排序（合併讀取用）
+    std::vector<int32_t> need_slot;        // 對應的 arena 槽位
+    std::vector<std::vector<float>> partial; // mode A：每個執行緒一份累加緩衝
+    std::vector<int32_t> slot_of_expert;      // [expert] -> arena 槽位（-1 = 沒分頁）
+    std::vector<int32_t> need_slot_of_expert; // 合併讀取時暫存槽位
+    std::vector<int32_t> miss_sorted;         // 需要從 SSD 讀的 expert（已排序）
+    gen_barrier bar;
+    std::mutex mtx;
+    bool warned = false;
+};
+
+static std::vector<layer_rec *> g_recs;
+
+static layer_rec * rec_for(int il) {
+    static std::mutex m;
+    std::lock_guard<std::mutex> lk(m);
+    if ((int) g_recs.size() <= il) {
+        g_recs.resize(il + 1, nullptr);
+    }
+    if (!g_recs[il]) {
+        g_recs[il] = new layer_rec();
+        g_recs[il]->il = il;
+    }
+    return g_recs[il];
+}
+
+// ---------------------------------------------------------------- 自訂 op 本體
+
+// mode C（預設，partial 緩衝 <= 上限）：依 expert 流水線，取→算交錯、無中途 barrier。
+// mode B（partial 緩衝太大時的退路）：先分頁完再一起算，會有 barrier 等待。
+// 上限給一個很大的值＝永遠走 mode C；給 0＝強制 mode B（除錯用）。
+static size_t env_partial_cap_mb() {
+    const char * e = getenv("SDQ_PARTIAL_CAP_MB");
+    return e ? (size_t) atoi(e) : 4096;   // MB，預設 4096 MB → 一律 mode C
+}
+
+static inline float sdq_swiglu(float g, float u, float limit, int mode) {
+    if (limit <= 1e-6f) {
+        return g / (1.0f + std::exp(-g)) * u;
+    }
+    if (mode == SDQ_SWIGLU_GGML_FUSED_CLAMP) {
+        const float gc = std::min(g, limit);
+        const float uc = std::max(-limit, std::min(limit, u));
+        return gc / (1.0f + std::exp(-gc)) * uc;
+    }
+    const float uc = std::max(-limit, std::min(limit, u));
+    float gc = g / (1.0f + std::exp(-g));
+    gc = std::max(-limit, std::min(limit, gc));
+    return gc * uc;
+}
+
+// ---------------------------------------------------------------- 單一 expert 的數學
+// 從 arena 的槽位記憶體算出一個 expert 對多個 token 的輸出（加權後直接累加到 out）
+static void expert_forward(const expert_desc & ed, const uint8_t * base,
+                           const float * cur, int64_t n_embd,
+                           const std::vector<std::pair<int32_t, int32_t>> & toks,
+                           const float * wts, size_t wts_nb0, size_t wts_nb1, int /*n_used*/,
+                           float swiglu_limit, int swiglu_mode,
+                           float * out, std::vector<uint8_t> * scratch) {
+    int64_t gate_rows = ed.ne1;
+    int64_t up_rows = ed.ne1;
+    size_t  gate_row = ggml_row_size(ed.type[part::GATE], ed.ne0);
+    size_t  up_row = gate_row;
+    if (ed.fused_gate_up) {
+        gate_rows = ed.ne1 / 2;
+        up_rows = gate_rows;
+    } else {
+        up_row = ggml_row_size(ed.type[part::UP], ed.ne0);
+    }
+
+    const vec_dot_fn f_gate = dot_for(ed.type[part::GATE]);
+    const vec_dot_fn f_up   = ed.fused_gate_up ? f_gate : dot_for(ed.type[part::UP]);
+    const vec_dot_fn f_down = dot_for(ed.type[part::DOWN]);
+    if (!f_gate || !f_up || !f_down) {
+        fprintf(stderr, "[sdq] 不支援的專家量化型別：gate=%s up=%s down=%s\n",
+                ggml_type_name(ed.type[part::GATE]),
+                ggml_type_name(ed.type[part::UP]),
+                ggml_type_name(ed.type[part::DOWN]));
+        return;
+    }
+
+    const uint8_t * wg      = base + ed.slot_off[part::GATE];
+    const uint8_t * wu      = base + ed.slot_off[part::UP];
+    const uint8_t * wd      = base + ed.slot_off[part::DOWN];
+    const size_t    down_row = ggml_row_size(ed.type[part::DOWN], ed.down_ne0);
+
+    const ggml_type act_gate = act_type_for(ed.type[part::GATE]);
+    const ggml_type act_down = act_type_for(ed.type[part::DOWN]);
+    const size_t xq_sz = ggml_row_size(act_gate, ed.ne0);
+    const size_t hq_sz = ggml_row_size(act_down, ed.down_ne0);
+    if (scratch->size() < xq_sz + hq_sz) {
+        scratch->assign(xq_sz + hq_sz, 0);
+    }
+    uint8_t * xq = scratch->data();
+    uint8_t * hq = xq + xq_sz;
+
+    std::vector<float> gate((size_t) gate_rows);
+    std::vector<float> upv((size_t) up_rows);
+    std::vector<float> h((size_t) ed.down_ne0);
+
+    PROF_T0_x(_ta);   // expert_forward 總計時
+    for (const auto & tk : toks) {
+        const int32_t t = tk.first;
+        const int32_t k = tk.second;
+
+        PROF_T0_x(_tb);   // 量化 activation
+        quantize_act(act_gate, cur + (size_t) t * n_embd, xq, ed.ne0);
+        PROF_ADD(qact_ns, _tb);
+
+        PROF_T0_x(_tc);   // gate / up / down 三次點積
+        for (int64_t r = 0; r < gate_rows; r++) {
+            float acc = 0.0f;
+            dot_row(f_gate, wg + r * gate_row, xq, gate_row, (int) ed.ne0, acc);
+            gate[(size_t) r] = acc;
+        }
+        for (int64_t r = 0; r < up_rows; r++) {
+            float acc = 0.0f;
+            const uint8_t * src = ed.fused_gate_up ? (wg + (gate_rows + r) * gate_row)
+                                                   : (wu + r * up_row);
+            dot_row(f_up, src, xq, ed.fused_gate_up ? gate_row : up_row, (int) ed.ne0, acc);
+            upv[(size_t) r] = acc;
+        }
+
+        PROF_ADD(dot_ns, _tc);
+
+        PROF_T0_x(_td);   // SiLU + 加權求和
+        for (int64_t r = 0; r < ed.down_ne0; r++) {
+            h[(size_t) r] = sdq_swiglu(gate[(size_t) r], upv[(size_t) r],
+                                       swiglu_limit, swiglu_mode);
+        }
+        quantize_act(act_down, h.data(), hq, ed.down_ne0);
+
+        PROF_ADD(act_ns, _td);
+
+        const float w = *(const float *) ((const uint8_t *) wts + k * wts_nb0 + (size_t) t * wts_nb1);
+        float * o = out + (size_t) t * n_embd;
+        for (int64_t r = 0; r < ed.down_ne1; r++) {
+            float acc = 0.0f;
+            dot_row(f_down, wd + r * down_row, hq, down_row, (int) ed.down_ne0, acc);
+            o[r] += acc * w;
+        }
+    }
+    PROF_ADD(fwd_ns, _ta);
+}
+
+
+static void moe_custom_op(ggml_tensor * dst, int ith, int nth, void * userdata) {
+    layer_rec * R = (layer_rec *) userdata;
+    pager & P = pager::instance();
+
+    // 從 op 的 src 取得輸入（保證是「這一次」真的被計算的張量）
+    const ggml_tensor * src_cur = dst->src[0];
+    const ggml_tensor * src_ids = dst->src[1];
+    const ggml_tensor * src_wts = dst->src[2];
+    if (!src_cur || !src_ids || !src_wts) {
+        if (ith == 0) {
+            fprintf(stderr, "[sdq] op 缺少 src（%d）\n", R->il);
+        }
+        return;
+    }
+
+    const layer_desc * L = P.layer(R->il);
+    PROF_T0_x(_tg);   // op 總計時
+    g_prof.calls++;
+    const int64_t n_embd = src_cur->ne[0];
+    const int64_t n_tok  = src_cur->ne[2];
+    const int64_t n_used = R->n_expert_used;
+    // ids 是 2D [n_expert_used, n_tokens] → 用 nb[0]/nb[1]
+    // wts 是 3D [1, n_expert_used, n_tokens] → 用 nb[1]/nb[2]（nb[0] 會是 4 而不是 n_used*4！）
+    const size_t ids_nb0 = src_ids->nb[0], ids_nb1 = src_ids->nb[1];
+    const size_t wts_nb0 = src_wts->nb[src_wts->ne[0] == 1 ? 1 : 0];
+    const size_t wts_nb1 = src_wts->nb[src_wts->ne[0] == 1 ? 2 : 1];
+    const float * cur = (const float *) src_cur->data;
+    const float * wts = (const float *) src_wts->data;
+
+    if (!L || L->experts.empty() || dst->type != GGML_TYPE_F32) {
+        if (ith == 0 && !R->warned) {
+            R->warned = true;
+            fprintf(stderr, "[sdq] 層 %d 沒有可用的分頁描述\n", R->il);
+        }
+        return;
+    }
+
+    if (R->il == 0 && getenv("SDQ_DBG_OP")) {
+        fprintf(stderr, "[sdq-op] L%d n_tok=%lld nth=%d need=%d ids_nb1=%zu wts_nb1=%zu\n",
+                R->il, (long long) n_tok, nth, (int) R->need.size(), ids_nb1, wts_nb1);
+    }
+    // ---- 1) 解除上一層的 pin（mode B 直接累加輸出，需要先清空）
+    PROF_T0_x(_tsetup);
+    if (ith == 0) {
+        P.unpin_all();
+    }
+    if (nth > 1) { R->bar.sync(nth); }
+
+    // ---- 2) 依 expert 分組 token（只有執行緒 0 做，其餘在此等待）
+    if (ith == 0) {
+        std::lock_guard<std::mutex> lk(R->mtx);
+        R->tok_of_expert.assign((size_t) R->n_expert, {});
+        R->exp_of_tok.assign((size_t) n_tok, {});
+        const uint8_t * ids_base = (const uint8_t *) src_ids->data;
+        for (int64_t t = 0; t < n_tok; t++) {
+            for (int64_t k = 0; k < n_used; k++) {
+                const int32_t e = *(const int32_t *) (ids_base + k * ids_nb0 + (size_t) t * ids_nb1);
+                if (e >= 0 && e < R->n_expert) {
+                    auto & v = R->tok_of_expert[(size_t) e];
+                    bool seen = false;
+                    for (const auto & p : v) {
+                        if (p.first == (int32_t) t) { seen = true; break; }
+                    }
+                    if (!seen) {
+                        v.emplace_back((int32_t) t, (int32_t) k);
+                    }
+                    R->exp_of_tok[(size_t) t].emplace_back(e, (int32_t) k);
+                }
+            }
+        }
+        R->need.clear();
+        for (int64_t e = 0; e < R->n_expert; e++) {
+            if (!R->tok_of_expert[(size_t) e].empty()) {
+                R->need.push_back((int32_t) e);
+            }
+        }
+        R->need_sorted = R->need;
+        std::sort(R->need_sorted.begin(), R->need_sorted.end());
+        R->need_slot.assign(R->need.size(), -1);   // 只能由 ith==0 配置，其餘執行緒唯讀
+        R->slot_of_expert.assign((size_t) R->n_expert, -1);
+        R->need_slot_of_expert.assign((size_t) R->n_expert, -1);
+        R->miss_sorted.clear();
+        R->miss_sorted.reserve((size_t) R->n_expert);
+        if (R->partial.size() < 64) {
+            R->partial.resize(64);
+        }
+        sdq_route_log(R->il, n_tok, src_ids, ids_nb0, ids_nb1, (int) n_used);
+    }
+    if (nth > 1) { R->bar.sync(nth); }
+    PROF_ADD(setup_ns, _tsetup);
+
+    const int n_need = (int) R->need.size();
+
+    // ---- 3+4) 分頁與計算融合成一條 pipeline
+    //
+    // 關鍵效能點：不要「先把整層的 expert 都讀完再開始算」。做法是每個執行緒
+    // 自己依序處理它負責的 expert：讀一個 → 立刻算它 → 再讀下一個。
+    // 這樣 SSD 讀取和 CPU 計算自然重疊，而且 8 條執行緒各自發出 pread，
+    // SSD 佇列深度也夠（不需要再靠 queue depth）。
+    //
+    // 平行切分：mode A 依 expert 切（每個執行緒有自己的累加緩衝，最後相加）；
+    //           mode B 依 token 切（同一個 token 的所有 expert 由同一執行緒算，
+    //           但必須先把該 token 的 expert 都備齊，所以先分頁再計算）。
+    const int64_t out_elems = n_embd * n_tok;
+    const size_t partial_bytes = (size_t) out_elems * 4 * (size_t) nth;
+    const bool mode_a = partial_bytes <= (size_t) env_partial_cap_mb() << 20;
+    float * out = (float *) dst->data;
+
+    if (!mode_a) {
+        memset(dst->data, 0, (size_t) ggml_nbytes(dst));
+    }
+
+    if (mode_a) {
+        // ===================== mode C（預設）：依 expert 流水線 =====================
+        // 三個設計重點，每個都來自實測：
+        //
+        // (1) **取→算交錯，中間沒有 barrier**。
+        //     舊的 mode B 是「先把整層 8 個 expert 全部讀完 → barrier → 才開始算」。
+        //     量測顯示 decode 有 66% 的時間卡在 barrier 上等最慢的執行緒
+        //     （SDQ_PROFILE_TIME 的 barrier 等待 = op 時間的 70%）。改成交錯後
+        //     讀取與計算自然重疊，實測 2.79 → 3.49 tok/s。
+        //
+        // (2) **分頁走 acquire()，不用 reserve_slot + read_expert_span**。
+        //     reserve_slot() 會在資料還沒讀進來之前就把 (layer,expert) publish 到
+        //     page_ 表；一旦該層的 pread 失敗或被中斷，這個槽就會留在 page_ 裡
+        //     卻是舊資料，之後的 probe() 會把它當成命中 → 靜默算錯。
+        //     acquire() 是「先讀完再 publish」，成本相同但不會有這個失效模式。
+        //
+        // (3) **i += nth 交錯分配**，不是切成連續區塊。
+        //     每個 expert 的 SSD 延遲差異很大，交錯分配讓快執行緒自然多幫忙。
+        //
+        // 輸出不直接寫 dst（同一個 token 的不同 expert 會撞在一起），
+        // 所以仍然用「每執行緒一份累加緩衝 + 最後歸約」。
+        std::vector<float> & mine = R->partial[(size_t) ith];
+        mine.assign((size_t) out_elems, 0.0f);
+        std::vector<uint8_t> scratch;
+
+        // 在取本層的 expert **之前**先替下一層排預取。
+        //
+        // 實測結論（S7）：**預設關閉，而且量到開啟反而慢 8%。**
+        // 預測來自 prev_used_[il+1]（上一個 token 在該層選的專家）。想用它躲在
+        // 「本層的讀取＋計算」後面，但量到的結果是：
+        //   開（5.68 tok/s，預取使用率 0.48 %）vs 關（6.20 tok/s，0.28 %）
+        // 命中率幾乎一樣（70.5 % vs 70.7 %），但 SSD 位元組從 201.5 升到 216.0 MB/token
+        // → 預測不夠準，多讀的全是白讀，而且還要和本層的 demand 讀搶頻寬。
+        // 另外開啟時同一提示詞的輸出不一致 → 預取佔用的槽位（busy）會讓
+        // acquire() 偶爾拿不到槽位而**靜默跳過一個 expert**，這是正確性問題。
+        //
+        // 保留程式碼是為了讓後人不用重新發明；文件見 docs/06_slots.md §4。
+        // SDQ_PREFETCH_LAYER_AHEAD=1 可以打開來重現那個負結果。
+        static const bool layer_ahead = [] {
+            const char * e = getenv("SDQ_PREFETCH_LAYER_AHEAD");
+            return e ? atoi(e) != 0 : false;
+        }();
+        if (layer_ahead && ith == 0) {
+            P.prefetch_layer_ahead(R->il + 1);
+        }
+
+        for (int i = ith; i < n_need; i += nth) {
+            const int32_t e = R->need[(size_t) i];
+            const int32_t sl = P.acquire(R->il, e, true);
+            if (sl < 0) {
+                continue;
+            }
+            P.note_used(R->il, e);
+            expert_forward(L->experts[(size_t) e], P.slot_ptr(sl), cur, n_embd,
+                           R->tok_of_expert[(size_t) e], wts, wts_nb0, wts_nb1,
+                           (int) n_used, R->swiglu_limit, R->swiglu_mode,
+                           mine.data(), &scratch);
+            // expert_forward 回傳後這個槽位就沒人讀了（最後的歸約只讀 mine），
+            // 所以立刻放掉 pin，不要讓它被釘到下一層開頭。
+            // 不放的話 prefill 一層會把整層用到的 expert 全部釘住（最多 256 個），
+            // 大槽位不夠時就會中止（見 pager::release 的說明）。
+            P.release(sl);
+        }
+
+        if (nth > 1) { R->bar.sync(nth); }
+        for (int64_t idx = ith; idx < out_elems; idx += nth) {
+            float acc = 0.0f;
+            for (int k = 0; k < nth; k++) {
+                acc += R->partial[(size_t) k][(size_t) idx];
+            }
+            out[idx] = acc;
+        }
+    } else {
+        // mode B：token 多到 partial 緩衝太大時，依 token 切分
+        // 先把所有需要的 expert 分頁（各執行緒平行 pread）
+        {
+        PROF_T0_x(_th);   // 分頁 / SSD 讀取
+        for (int i = ith; i < n_need; i += nth) {
+            const int32_t e = R->need[(size_t) i];
+            const int s = P.acquire(R->il, e, true);
+            g_prof.experts++;
+            R->need_slot[(size_t) i] = s;
+            if (s >= 0) {
+                R->slot_of_expert[(size_t) e] = s;
+                P.note_used(R->il, e);
+            }
+        }
+        PROF_ADD(read_ns, _th);
+        }
+        if (nth > 1) { R->bar.sync(nth); }
+        const float * cur_p = (const float *) src_cur->data;
+        const float * wts_p = (const float *) src_wts->data;
+        for (int64_t t = ith; t < n_tok; t += nth) {
+            std::vector<uint8_t> scratch;
+            for (const auto & ek : R->exp_of_tok[(size_t) t]) {
+                const int slot = R->slot_of_expert[(size_t) ek.first];
+                if (slot < 0) {
+                    continue;
+                }
+                std::vector<std::pair<int32_t, int32_t>> one = {{(int32_t) t, ek.second}};
+                expert_forward(L->experts[(size_t) ek.first], P.slot_ptr(slot), cur_p, n_embd,
+                               one, wts_p, wts_nb0, wts_nb1, (int) n_used,
+                               R->swiglu_limit, R->swiglu_mode, out, &scratch);
+            }
+        }
+    }
+
+    // 除錯：把某一層的實際輸入/輸出 dump 出來，用 NumPy 對照。
+    // 必須先 barrier：上面的歸約是由各執行緒分片寫 out 的，沒有這一道會讀到半成品。
+    if (nth > 1) { R->bar.sync(nth); }
+    if (const char * dump_path = getenv("SDQ_MOE_DUMP")) {
+        const int dump_layer = getenv("SDQ_MOE_DUMP_LAYER") ? atoi(getenv("SDQ_MOE_DUMP_LAYER")) : -1;
+        if ((dump_layer < 0 || R->il == dump_layer) && ith == 0) {
+            // 檔名帶上 op 呼叫序號：不然同一層的每次 op 都寫進同一個檔，只剩最後一次
+            // （通常是 decode 的 n_tok=1），prefill 那批 n_tok=128 的就看不到 ——
+            // 而 prefill 才是 arena 壓力最大、hot/cold 差最大的地方。
+            static std::atomic<uint64_t> dump_seq{0};
+            std::string path = std::string(dump_path) + "." + std::to_string(R->il) +
+                               "." + std::to_string(dump_seq++);
+            FILE * f = fopen(path.c_str(), "wb");
+            if (f) {
+                const int32_t meta[6] = {(int32_t) n_embd, (int32_t) n_tok, (int32_t) n_used,
+                                         (int32_t) R->n_expert, 1, 2};
+                fwrite(meta, sizeof(int32_t), 6, f);
+                fwrite(cur, sizeof(float), (size_t) (n_embd * n_tok), f);
+                const uint8_t * ids_base = (const uint8_t *) src_ids->data;
+                for (int64_t t = 0; t < n_tok; t++) {
+                    for (int64_t k = 0; k < n_used; k++) {
+                        const int32_t e = *(const int32_t *) (ids_base + k * ids_nb0 + (size_t) t * ids_nb1);
+                        fwrite(&e, sizeof(int32_t), 1, f);
+                    }
+                }
+                fwrite(wts, sizeof(float), (size_t) (n_used * n_tok), f);
+                fwrite(out, sizeof(float), (size_t) (n_embd * n_tok), f);
+                fclose(f);
+                fprintf(stderr, "[sdq] dumped layer %d -> %s\n", R->il, path.c_str());
+            }
+        }
+    }
+
+    if (nth > 1) { R->bar.sync(nth); }
+    PROF_ADD(op_ns, _tg);
+}
+
+// 輸出計時結果（sdq_shutdown 呼叫）
+void sdq_print_time_profile() {
+    if (!prof_on()) {
+        return;
+    }
+    const double ms = 1e6;
+    auto v = [ms](const std::atomic<uint64_t> & a) { return a.load() / ms; };
+    const double op = v(g_prof.op_ns);
+    const double fwd = v(g_prof.fwd_ns);
+    fprintf(stderr, "[sdq-prof] 自訂 MoE op（%llu 次呼叫、%llu 個 expert 分頁）\n",
+            (unsigned long long) g_prof.calls.load(), (unsigned long long) g_prof.experts.load());
+    fprintf(stderr, "[sdq-prof]   op 合計          %9.1f ms\n", op);
+    fprintf(stderr, "[sdq-prof]     expert_forward  %9.1f ms (%5.1f%%)  其中：\n", fwd, op > 0 ? 100.0 * fwd / op : 0.0);
+    fprintf(stderr, "[sdq-prof]       量化 activation%9.1f ms (%5.1f%% of fwd)\n", v(g_prof.qact_ns), fwd > 0 ? 100.0 * v(g_prof.qact_ns) / fwd : 0.0);
+    fprintf(stderr, "[sdq-prof]       三次點積        %9.1f ms (%5.1f%% of fwd)\n", v(g_prof.dot_ns),  fwd > 0 ? 100.0 * v(g_prof.dot_ns) / fwd : 0.0);
+    fprintf(stderr, "[sdq-prof]       SiLU+加權       %9.1f ms (%5.1f%% of fwd)\n", v(g_prof.act_ns),  fwd > 0 ? 100.0 * v(g_prof.act_ns) / fwd : 0.0);
+    fprintf(stderr, "[sdq-prof]     SSD 讀取/分頁    %9.1f ms (%5.1f%%)\n", v(g_prof.read_ns), op > 0 ? 100.0 * v(g_prof.read_ns) / op : 0.0);
+    fprintf(stderr, "[sdq-prof]     前置 setup      %9.1f ms (%5.1f%%)\n", v(g_prof.setup_ns), op > 0 ? 100.0 * v(g_prof.setup_ns) / op : 0.0);
+    fprintf(stderr, "[sdq-prof]     barrier 等待    %9.1f ms (%5.1f%%)\n", v(g_prof.bar_ns), op > 0 ? 100.0 * v(g_prof.bar_ns) / op : 0.0);
+}
+
+// ---------------------------------------------------------------- graph 建構
+
+ggml_tensor * sdq_build_moe(ggml_cgraph * gf, ggml_context * ctx, ggml_tensor * cur,
+                            ggml_tensor * ids, ggml_tensor * weights, int il, int64_t n_expert,
+                            int64_t n_expert_used, float swiglu_limit,
+                            int swiglu_mode) {
+    layer_rec * R = rec_for(il);
+    R->n_expert = n_expert;
+    R->n_expert_used = n_expert_used;
+    R->swiglu_limit = swiglu_limit;
+    R->swiglu_mode  = swiglu_mode;
+
+    // 呼叫端給的是 2D [n_embd, n_tokens]，這裡跟上游一樣先 reshape 成 3D
+    // [n_embd, 1, n_tokens]（上游 mul_mat_id 路徑也是這樣拿 token 數的）
+    ggml_tensor * cur3 = (cur->ne[1] == 1) ? cur : ggml_reshape_3d(ctx, cur, cur->ne[0], 1, cur->ne[1]);
+    const int64_t n_tok = cur3->ne[2];
+
+    ggml_tensor * args[3] = { cur3, ids, weights };
+    ggml_tensor * out = ggml_custom_4d(ctx, GGML_TYPE_F32, cur3->ne[0], n_tok, 1, 1,
+                                       args, 3, moe_custom_op, GGML_N_TASKS_MAX, R);
+    ggml_set_name(out, "sdq_moe_out");
+    // 關鍵：把這個節點註冊進圖，ggml 才會為它配置獨立的 compute buffer。
+    // 少了這一行，layer>=1 的輸出會被其他張量覆蓋（layer 0 僥倖正確）。
+    ggml_build_forward_expand(gf, out);
+    return out;
+}
+
+} // namespace sdq
+namespace sdq {
+// 自我測試：對指定 (layer, expert) 用 pager 的資料算一次 MoE 輸出，
+// 讓 Python 用純 NumPy 從同一段 GGUF 位元組重算並比對。
+// 輸出：out[0..n_embd) = 輸出，out[n_embd..2*n_embd) = 輸入 activation
+int sdq_moe_selftest(int il, int ie, const float * x, float * out_io,
+                     int64_t n_embd, int64_t n_ff, int n_tok,
+                     float swiglu_limit, int swiglu_mode) {
+    pager & P = pager::instance();
+    const layer_desc * L = P.layer(il);
+    if (!L || ie < 0 || ie >= (int) L->experts.size()) {
+        fprintf(stderr, "[sdq-selftest] 層/expert 不存在：%d/%d\n", il, ie);
+        return 1;
+    }
+    const int slot = P.acquire(il, ie, true);
+    if (slot < 0) {
+        fprintf(stderr, "[sdq-selftest] 分頁失敗\n");
+        return 2;
+    }
+    const expert_desc & ed = L->experts[(size_t) ie];
+    if (ed.ne0 != n_embd || ed.ne1 != n_ff) {
+        fprintf(stderr, "[sdq-selftest] 維度不符：ne0=%lld ne1=%lld（預期 %lld/%lld）\n",
+                (long long) ed.ne0, (long long) ed.ne1, (long long) n_embd, (long long) n_ff);
+        return 3;
+    }
+    std::vector<std::pair<int32_t, int32_t>> toks;
+    std::vector<float> wts((size_t) n_tok, 1.0f);
+    for (int t = 0; t < n_tok; t++) {
+        toks.emplace_back(t, 0);
+    }
+    std::vector<float> out((size_t) n_embd * n_tok, 0.0f);
+    std::vector<uint8_t> scratch;
+    expert_forward(ed, P.slot_ptr(slot), x, n_embd, toks, wts.data(), 4, 4, 1,
+                   swiglu_limit, swiglu_mode, out.data(), &scratch);
+    for (int64_t t = 0; t < n_tok; t++) {
+        for (int64_t i = 0; i < n_embd; i++) {
+            out_io[t * n_embd + i] = out[(size_t) t * n_embd + i];
+            out_io[n_tok * n_embd + t * n_embd + i] = x[(size_t) t * n_embd + i];
+        }
+    }
+    P.unpin_all();
+    fprintf(stderr, "[sdq-selftest] L%d E%d n_tok=%d 計算完成（gate %s / up %s / down %s，"
+                    "swiglu_limit=%g mode=%d）\n",
+            il, ie, n_tok, ggml_type_name(ed.type[part::GATE]), ggml_type_name(ed.type[part::UP]),
+            ggml_type_name(ed.type[part::DOWN]), swiglu_limit, swiglu_mode);
+    return 0;
+}
+} // namespace sdq

sdq-dsv4/sdq_pager.cpp

@@ -0,0 +1,2282 @@
+// SDQ expert pager 實作：見 sdq_pager.h 的設計說明
+#include "sdq_pager.h"
+
+#include "llama-mmap.h"
+
+#include <algorithm>
+#include <thread>
+#include <cinttypes>
+#include <cmath>
+#include <cstdio>
+#include <cstdlib>
+#include <cstring>
+#include <fcntl.h>
+#include <ctime>
+#include <fstream>
+#include <map>
+#include <mutex>
+#include <sstream>
+#include <stdexcept>
+#include <sys/mman.h>
+#include <sys/stat.h>
+#include <sys/types.h>
+#include <unistd.h>
+
+namespace sdq {
+
+// ============================================================ 小工具
+
+uint64_t now_us() {
+    struct timespec ts;
+    clock_gettime(CLOCK_MONOTONIC, &ts);
+    return (uint64_t) ts.tv_sec * 1000000ull + (uint64_t) ts.tv_nsec / 1000ull;
+}
+
+size_t process_rss_bytes() {
+    std::ifstream f("/proc/self/statm");
+    size_t total = 0, resident = 0;
+    if (f >> total >> resident) {
+        return resident * (size_t) sysconf(_SC_PAGESIZE);
+    }
+    return 0;
+}
+
+size_t physical_ram_bytes() {
+    std::ifstream f("/proc/meminfo");
+    std::string key;
+    size_t value = 0;
+    std::string unit;
+    while (f >> key >> value >> unit) {
+        if (key == "MemTotal:") {
+            return value * 1024;
+        }
+    }
+    return 0;
+}
+
+static size_t env_size(const char * name, size_t dflt) {
+    const char * v = getenv(name);
+    if (!v || !*v) {
+        return dflt;
+    }
+    return (size_t) strtoull(v, nullptr, 10);
+}
+
+static bool env_flag(const char * name, bool dflt) {
+    const char * v = getenv(name);
+    if (!v || !*v) {
+        return dflt;
+    }
+    return !(v[0] == '0' && v[1] == '\0');
+}
+
+// ============================================================ GGUF 檔頭解析
+
+namespace {
+
+struct gguf_reader {
+    const uint8_t * p = nullptr;
+    size_t size = 0;
+    size_t o = 0;
+
+    uint8_t  u8()  { return p[o++]; }
+    uint32_t u32() { uint32_t v; memcpy(&v, p + o, 4); o += 4; return v; }
+    uint64_t u64() { uint64_t v; memcpy(&v, p + o, 8); o += 8; return v; }
+    int64_t  i64() { int64_t  v; memcpy(&v, p + o, 8); o += 8; return v; }
+    float    f32() { float    v; memcpy(&v, p + o, 4); o += 4; return v; }
+    std::string str() {
+        uint64_t n = u64();
+        std::string s((const char *) p + o, (size_t) n);
+        o += n;
+        return s;
+    }
+    void skip(uint64_t n) { o += (size_t) n; }
+    uint16_t u16() { uint16_t v; memcpy(&v, p + o, 2); o += 2; return v; }
+    int16_t  i16() { int16_t  v; memcpy(&v, p + o, 2); o += 2; return v; }
+    double   f64() { double   v; memcpy(&v, p + o, 8); o += 8; return v; }
+};
+
+struct kv_value {
+    enum kind { NONE, INT, REAL, STR, ARR } k = NONE;
+    int64_t i = 0;
+    double  f = 0;
+    std::string s;
+    std::vector<int64_t> arr;
+};
+
+struct tensor_info {
+    std::string name;
+    std::vector<int64_t> dims;
+    ggml_type type = GGML_TYPE_COUNT;
+    uint64_t offset = 0;   // 在所屬 shard 檔案內、相對 data_start 的偏移
+    int      shard = 0;    // 屬於哪一個 shard（sharded GGUF）
+};
+
+size_t ggml_type_size_of(ggml_type t) {
+    return ggml_row_size(t, 1);
+}
+
+} // namespace
+
+// ============================================================ pager
+
+pager & pager::instance() {
+    static pager p;
+    return p;
+}
+
+// 依 GGUF split 命名規則把第一個 shard 路徑展開成全部 shard。
+// 規則是 "<prefix>-00001-of-00004.gguf"；llama.cpp 用 llama_split_prefix/llama_split_path
+// 做同一件事，這裡獨立實作以免 pager 依賴 loader 的內部符號。
+std::vector<std::string> pager::list_splits(const std::string & first_path, int n_split) {
+    std::vector<std::string> out;
+    if (n_split <= 1) {
+        out.push_back(first_path);
+        return out;
+    }
+    // 用 llama.cpp 自己的命名規則（%s-%05d-of-%05d.gguf，且 split_no 由 1 起算）。
+    // 自己刻字串很容易差一位數字 —— 實測就是這樣變成 "...XL--00001-of-..."。
+    std::vector<char> pre(llama_path_max(), 0);
+    const int pre_len = llama_split_prefix(pre.data(), pre.size(), first_path.c_str(), 0, n_split);
+    if (pre_len <= 0) {
+        throw std::runtime_error("無法解析 split 檔名：" + first_path);
+    }
+    std::vector<char> buf(llama_path_max(), 0);
+    for (int i = 0; i < n_split; i++) {
+        const int len = llama_split_path(buf.data(), buf.size(), pre.data(), i, n_split);
+        if (len <= 0) {
+            throw std::runtime_error("無法產生 split 路徑：" + first_path);
+        }
+        out.emplace_back(buf.data(), (size_t) len);
+    }
+    return out;
+}
+
+void pager::load_gguf_header(const std::string & path) {
+    const int fd = open(path.c_str(), O_RDONLY);
+    if (fd < 0) {
+        throw std::runtime_error("無法開啟 GGUF：" + path);
+    }
+
+    struct stat st;
+    fstat(fd, &st);
+
+    // 只讀檔頭：metadata + tensor 資訊大約 11 MB（shard 1 還含整份 tokenizer，
+    // 這裡的 64 MiB 上限對它足夠）
+    const size_t want = (size_t) std::min<int64_t>(st.st_size, 64ull << 20);
+    std::vector<uint8_t> buf(want);
+    ssize_t got = 0;
+    while (got < (ssize_t) want) {
+        ssize_t n = pread(fd, buf.data() + got, want - got, got);
+        if (n <= 0) {
+            break;
+        }
+        got += n;
+    }
+    buf.resize((size_t) std::max<ssize_t>(got, 0));
+
+    gguf_reader r{buf.data(), buf.size(), 0};
+    if (memcmp(buf.data(), "GGUF", 4) != 0) {
+        close(fd);
+        throw std::runtime_error("不是 GGUF 檔：" + path);
+    }
+    r.o = 4;
+    const uint32_t version = r.u32();
+    if (version < 2 || version > 3) {
+        close(fd);
+        throw std::runtime_error("不支援的 GGUF 版本");
+    }
+    const uint64_t n_tensors = r.u64();
+    const uint64_t n_kv = r.u64();
+
+    std::map<std::string, kv_value> kv;
+    for (uint64_t i = 0; i < n_kv; i++) {
+        std::string key = r.str();
+        const uint32_t t = r.u32();
+        kv_value v;
+        switch (t) {
+            // GGUF 型別寬度：U8/I8/BOOL=1、U16/I16=2、U32/I32/F32=4、U64/I64/F64=8。
+            // 舊版把 case 0/1/2/3 都讀成 u32，遇到 tokenizer 或 U16 metadata 就整個
+            // header 錯位（症狀是 std::length_error: basic_string::_M_create）。
+            case 0: v.k = kv_value::INT; v.i = (int64_t) r.u8();  v.f = (double) v.i; break;
+            case 1: v.k = kv_value::INT; v.i = (int64_t) (int8_t)  r.u8();  v.f = (double) v.i; break;
+            case 2: v.k = kv_value::INT; v.i = (int64_t) r.u16(); v.f = (double) v.i; break;
+            case 3: v.k = kv_value::INT; v.i = (int64_t) r.i16(); v.f = (double) v.i; break;
+            case 4: v.k = kv_value::INT; v.i = (int64_t) (uint32_t) r.u32(); v.f = (double) v.i; break;
+            case 5: v.k = kv_value::INT; v.i = (int64_t) (int32_t)  r.u32(); v.f = (double) v.i; break;
+            case 6: v.k = kv_value::REAL; v.f = r.f32(); v.i = (int64_t) v.f; break;
+            case 7: v.k = kv_value::INT; v.i = (int64_t) r.u8(); v.f = (double) v.i; break; // BOOL = 1 byte
+            case 8: v.k = kv_value::STR;  v.s = r.str(); break;
+            case 9: {
+                v.k = kv_value::ARR;
+                const uint32_t et = r.u32();
+                const uint64_t n  = r.u64();
+                for (uint64_t j = 0; j < n; j++) {
+                    switch (et) {
+                        // 元素寬度必須跟 kv 一致（U8/I8/BOOL=1、U16/I16=2 …）。
+                        // F64 一定要消費 8 bytes，舊版沒讀會讓 header 往後全部錯位。
+                        case 0: v.arr.push_back(r.u8()); break;
+                        case 1: v.arr.push_back((int8_t) r.u8()); break;
+                        case 2: v.arr.push_back(r.u16()); break;
+                        case 3: v.arr.push_back(r.i16()); break;
+                        case 4: v.arr.push_back((uint32_t) r.u32()); break;
+                        case 5: v.arr.push_back((int32_t) r.u32()); break;
+                        case 6: v.arr.push_back((int64_t) r.f32()); break;
+                        case 7: v.arr.push_back(r.u8()); break;
+                        case 10: v.arr.push_back((int64_t) r.u64()); break;
+                        case 11: v.arr.push_back(r.i64()); break;
+                        case 12: r.f64(); v.arr.push_back(0); break;
+                        case 8: r.skip(r.u64()); v.arr.push_back(0); break;
+                        default:
+                            close(fd);
+                            throw std::runtime_error("GGUF 陣列元素型別不支援: " + std::to_string(et));
+                    }
+                }
+            } break;
+            case 10: v.k = kv_value::INT; v.i = (int64_t) r.u64(); v.f = (double) v.i; break;
+            case 11: v.k = kv_value::INT; v.i = r.i64(); v.f = (double) v.i; break;
+            case 12: v.k = kv_value::REAL; { double d; memcpy(&d, buf.data() + r.o, 8); r.o += 8; v.f = d; v.i = (int64_t) d; } break;
+            default: close(fd); throw std::runtime_error("GGUF kv 型別不支援: " + std::to_string(t));
+        }
+        kv[key] = v;
+    }
+
+    std::vector<tensor_info> tensors;
+    tensors.reserve(n_tensors);
+    for (uint64_t i = 0; i < n_tensors; i++) {
+        tensor_info ti;
+        ti.name = r.str();
+        const uint32_t nd = r.u32();
+        for (uint32_t d = 0; d < nd; d++) {
+            ti.dims.push_back((int64_t) r.u64());
+        }
+        ti.type = (ggml_type) r.u32();
+        ti.offset = r.u64();
+        tensors.push_back(std::move(ti));
+    }
+    const uint64_t align = kv.count("general.alignment") ? (uint64_t) kv["general.alignment"].i : 32;
+    const uint64_t data_start = (r.o + align - 1) / align * align;
+
+    close(fd);
+
+    // ---- sharded GGUF：shard 1 只帶 metadata（n_tensors=0），真正的權重分散在
+    // 其他 shard，而且每個 shard 有自己的 data_start。舊版只讀第一個檔，
+    // 於是 page map 會是空的（症狀：pager 起來但沒有任何 expert 可分頁）。
+    // 這裡把每個 shard 的 header 都讀一遍，張量名稱為全���鍵，offset 記成 (shard, off)。
+    {
+        const int64_t n_split = kv.count("split.count") ? kv["split.count"].i : 1;
+        shard_paths_ = list_splits(path, (int) n_split);
+        shard_data_start_.assign(shard_paths_.size(), 0);
+        shard_data_start_[0] = data_start;
+
+        if (n_split > 1) {
+            std::vector<tensor_info> merged;
+            merged.reserve((size_t) n_tensors + 1024);
+            for (size_t si = 1; si < shard_paths_.size(); si++) {
+                const int sfd = open(shard_paths_[si].c_str(), O_RDONLY);
+                if (sfd < 0) {
+                    throw std::runtime_error("無法開啟 GGUF shard：" + shard_paths_[si]);
+                }
+                struct stat sst;
+                fstat(sfd, &sst);
+                // 後續 shard 的 header 很小（沒有 tokenizer），讀 16 MiB 綽綽有餘
+                const size_t swant = (size_t) std::min<int64_t>(sst.st_size, 16ull << 20);
+                std::vector<uint8_t> sbuf(swant);
+                ssize_t sgot = 0;
+                while (sgot < (ssize_t) swant) {
+                    const ssize_t n = pread(sfd, sbuf.data() + sgot, swant - sgot, sgot);
+                    if (n <= 0) {
+                        break;
+                    }
+                    sgot += n;
+                }
+                sbuf.resize((size_t) std::max<ssize_t>(sgot, 0));
+
+                gguf_reader sr{sbuf.data(), sbuf.size(), 0};
+                if (sbuf.size() < 16 || memcmp(sbuf.data(), "GGUF", 4) != 0) {
+                    close(sfd);
+                    throw std::runtime_error("shard 不是 GGUF：" + shard_paths_[si]);
+                }
+                sr.o = 4;
+                sr.u32();                                  // version
+                const uint64_t s_ntensors = sr.u64();
+                const uint64_t s_nkv      = sr.u64();
+                for (uint64_t i = 0; i < s_nkv; i++) {
+                    sr.str();                               // key
+                    const uint32_t t = sr.u32();
+                    switch (t) {
+                        case 0: case 1: case 7: sr.skip(1); break;
+                        case 2: case 3:         sr.skip(2); break;
+                        case 4: case 5: case 6: sr.skip(4); break;
+                        case 10: case 11: case 12: sr.skip(8); break;
+                        case 8: sr.skip(sr.u64()); break;
+                        case 9: {
+                            const uint32_t et = sr.u32();
+                            const uint64_t n  = sr.u64();
+                            if (et == 8) {
+                                for (uint64_t j = 0; j < n; j++) { sr.skip(sr.u64()); }
+                            } else {
+                                size_t esz = 0;
+                                switch (et) {
+                                    case 0: case 1: case 7: esz = 1; break;
+                                    case 2: case 3:         esz = 2; break;
+                                    case 4: case 5: case 6: esz = 4; break;
+                                    case 10: case 11: case 12: esz = 8; break;
+                                    default: esz = 0; break;
+                                }
+                                sr.skip((uint64_t) n * esz);
+                            }
+                        } break;
+                        default:
+                            close(sfd);
+                            throw std::runtime_error("shard kv 型別不支援: " + std::to_string(t));
+                    }
+                }
+                for (uint64_t i = 0; i < s_ntensors; i++) {
+                    tensor_info ti;
+                    ti.name = sr.str();
+                    const uint32_t nd = sr.u32();
+                    for (uint32_t d = 0; d < nd; d++) {
+                        ti.dims.push_back((int64_t) sr.u64());
+                    }
+                    ti.type   = (ggml_type) sr.u32();
+                    ti.offset = sr.u64();
+                    ti.shard  = (int) si;
+                    merged.push_back(std::move(ti));
+                }
+                shard_data_start_[si] = (sr.o + align - 1) / align * align;
+                close(sfd);
+            }
+            for (auto & ti : tensors) {
+                ti.shard = 0;
+                merged.push_back(std::move(ti));
+            }
+            tensors.swap(merged);
+            fprintf(stderr, "[sdq] sharded GGUF：%d 個 shard，合計 %zu 個張量（shard1 為 metadata-only）\n",
+                    (int) shard_paths_.size(), tensors.size());
+        }
+    }
+
+    // ---- hparams
+    auto gi = [&](const std::string & k, int64_t dflt) -> int64_t {
+        auto it = kv.find(k);
+        return it == kv.end() ? dflt : it->second.i;
+    };
+    info_.arch = kv.count("general.architecture") ? kv["general.architecture"].s : "";
+    info_.name = kv.count("general.name") ? kv["general.name"].s : "";
+    const std::string pfx = info_.arch + ".";
+    info_.n_layer      = gi(pfx + "block_count", 0);
+    info_.n_expert     = gi(pfx + "expert_count", 0);
+    info_.n_expert_used= gi(pfx + "expert_used_count", 0);
+    info_.n_embd       = gi(pfx + "embedding_length", 0);
+    info_.n_ff_exp     = gi(pfx + "expert_feed_forward_length", 0);
+    info_.n_ff_shexp   = gi(pfx + "expert_shared_feed_forward_length", 0);
+    info_.n_expert_shared = gi(pfx + "expert_shared_count", 0);
+    info_.n_head       = gi(pfx + "attention.head_count", 0);
+    info_.n_head_kv    = gi(pfx + "attention.head_count_kv", 0);
+    info_.n_embd_head_k= gi(pfx + "attention.key_length", 0);
+    info_.n_embd_head_v= gi(pfx + "attention.value_length", info_.n_embd_head_k);
+    info_.context_length = gi(pfx + "context_length", 0);
+    info_.full_attention_interval = gi(pfx + "full_attention_interval", 4);
+
+    if (info_.n_expert <= 0 || info_.n_layer <= 0) {
+        throw std::runtime_error("這不是 MoE 模型（expert_count=" + std::to_string(info_.n_expert) + "）");
+    }
+    // deepseek4 的 shared expert（ffn_{gate,up,down}_shexp）是 2D 稠密權重、走一般的
+    // ggml_mul_mat，**不進 arena**，也不該被這個 pager 當成 routed expert。
+    // 它的 FFN 寬度是 n_ff_exp * n_expert_shared（見 llama.cpp src/models/deepseek4.cpp
+    // 的 create_tensor），所以沒有 expert_shared_feed_forward_length 這個 key 時，
+    // 用兩者相乘補起來（只拿來印訊息，不影響任何偏移計算）。
+    if (info_.n_ff_shexp == 0 && info_.n_expert_shared > 0) {
+        info_.n_ff_shexp = info_.n_ff_exp * info_.n_expert_shared;
+    }
+
+    fprintf(stderr, "[sdq] arch=%s layers=%lld experts=%lld used=%lld shared=%lld "
+                    "n_embd=%lld n_ff_exp=%lld n_ff_shexp=%lld ctx=%lld\n",
+            info_.arch.c_str(), (long long) info_.n_layer, (long long) info_.n_expert,
+            (long long) info_.n_expert_used, (long long) info_.n_expert_shared,
+            (long long) info_.n_embd, (long long) info_.n_ff_exp,
+            (long long) info_.n_ff_shexp, (long long) info_.context_length);
+
+    // ---- 頁面表：每個 (layer, expert) 的三段
+    layers_.assign((size_t) info_.n_layer, {});
+    std::map<std::string, const tensor_info *> by_name;
+    for (const auto & ti : tensors) {
+        by_name[ti.name] = &ti;
+    }
+
+    size_t max_expert_bytes = 0;
+    for (int64_t il = 0; il < info_.n_layer; il++) {
+        const std::string b = "blk." + std::to_string(il) + ".";
+        layer_desc & L = layers_[(size_t) il];
+        L.experts.assign((size_t) info_.n_expert, {});
+
+        auto get = [&](const std::string & suffix) -> const tensor_info * {
+            auto it = by_name.find(b + suffix);
+            return it == by_name.end() ? nullptr : it->second;
+        };
+
+        const tensor_info * t_gate = get("ffn_gate_exps.weight");
+        const tensor_info * t_up   = get("ffn_up_exps.weight");
+        const tensor_info * t_gu   = get("ffn_gate_up_exps.weight");
+        const tensor_info * t_down = get("ffn_down_exps.weight");
+
+        if (!t_down || (t_gate && !t_up && !t_gu)) {
+            continue; // 這層不是 MoE（理論上不會發生）
+        }
+
+        // sharded GGUF：每段的絕對偏移要用「該張量自己 shard 的 data_start」，
+        // 不能用第一個 shard 的（兩者差了近 10 MB，直接用會讀到別的權重）。
+        auto abs_off = [&](const tensor_info * t, uint64_t rel) -> uint64_t {
+            const size_t s = (size_t) t->shard;
+            const uint64_t base = (s < shard_data_start_.size()) ? shard_data_start_[s] : 0;
+            return base + rel;
+        };
+
+        for (int64_t e = 0; e < info_.n_expert; e++) {
+            expert_desc & ed = L.experts[(size_t) e];
+            if (t_gate || t_gu) {
+                const tensor_info * t = t_gate ? t_gate : t_gu;
+                const uint64_t nb = (uint64_t) ggml_row_size(t->type, t->dims[0]) * (uint64_t) t->dims[1];
+                ed.seg[part::GATE].off   = abs_off(t, t->offset + (uint64_t) e * nb);
+                ed.seg[part::GATE].size  = nb;
+                ed.seg[part::GATE].shard = t->shard;
+                ed.ne0 = t->dims[0];
+                ed.ne1 = t->dims[1];
+                ed.type[part::GATE] = t->type;
+            }
+            if (t_up) {
+                const uint64_t nb = (uint64_t) ggml_row_size(t_up->type, t_up->dims[0]) * (uint64_t) t_up->dims[1];
+                ed.seg[part::UP].off   = abs_off(t_up, t_up->offset + (uint64_t) e * nb);
+                ed.seg[part::UP].size  = nb;
+                ed.seg[part::UP].shard = t_up->shard;
+                ed.type[part::UP] = t_up->type;   // gate/up 都是 Q4_K，型別一定要各自填
+                if (!t_gate) {
+                    ed.ne0 = t_up->dims[0];
+                    ed.ne1 = t_up->dims[1];
+                    ed.type[part::GATE] = t_up->type;
+                }
+            }
+            {
+                const uint64_t nb = (uint64_t) ggml_row_size(t_down->type, t_down->dims[0]) * (uint64_t) t_down->dims[1];
+                ed.seg[part::DOWN].off   = abs_off(t_down, t_down->offset + (uint64_t) e * nb);
+                ed.seg[part::DOWN].size  = nb;
+                ed.seg[part::DOWN].shard = t_down->shard;
+                ed.type[part::DOWN] = t_down->type;
+                ed.down_ne0 = t_down->dims[0];
+                ed.down_ne1 = t_down->dims[1];
+            }
+            ed.fused_gate_up = (t_gate == nullptr && t_gu != nullptr);
+            ed.bytes = 0;
+            int64_t acc = 0;
+            for (int p = 0; p < 3; p++) {
+                if (ed.seg[p].size == 0) {
+                    continue;
+                }
+                acc = (acc + 63) & ~(int64_t) 63; // 每段 64B 對齊
+                ed.slot_off[p] = acc;
+                acc += (int64_t) ed.seg[p].size;
+            }
+            ed.bytes = acc;
+            max_expert_bytes = std::max(max_expert_bytes, (size_t) ed.bytes);
+        }
+        L.bytes_per_expert = L.experts.empty() ? 0 : L.experts[0].bytes;
+    }
+
+    // ---- RAM 帳目摘要 ---------------------------------------------------
+    // expert / 非 expert 的權重總量。這決定「分頁能省多少」——
+    // 若非 expert 權重本身就很大，arena 再大也塞不下整個模型。
+    {
+        int64_t exp_total = 0;
+        std::map<std::string, std::map<int, int>> types;  // part -> ggml_type -> 層數
+        for (const auto & L : layers_) {
+            exp_total += L.bytes_per_expert * (int64_t) info_.n_expert;
+            const expert_desc & ed = L.experts.empty() ? expert_desc{} : L.experts[0];
+            for (int p = 0; p < 3; p++) {
+                static const char * pname[3] = { "gate", "up", "down" };
+                types[pname[p]][(int) ed.type[p]]++;
+            }
+        }
+        fprintf(stderr, "[sdq] expert 權重合計 %lld B（%.2f GiB）＝ %lld 層 × %lld expert\n",
+                (long long) exp_total, exp_total / (double) (1ll << 30),
+                (long long) info_.n_layer, (long long) info_.n_expert);
+        for (const auto & kv : types) {
+            fprintf(stderr, "[sdq]   %-5s :", kv.first.c_str());
+            for (const auto & t : kv.second) {
+                fprintf(stderr, " %s ×%d 層", ggml_type_name((ggml_type) t.first), t.second);
+            }
+            fprintf(stderr, "\n");
+        }
+    }
+
+    slot_bytes_ = (max_expert_bytes + 4095) & ~(size_t) 4095;
+    if (slot_bytes_ < (256ull << 10)) {
+        slot_bytes_ = 256ull << 10;
+    }
+
+    // ---- 大小兩種槽位 ----------------------------------------------------
+    // DeepSeek-V4-Flash-0731 UD-IQ4_NL：42 層的 expert 是 11,665,408 B
+    // （IQ3_S gate 3,604,480 + IQ3_S up 3,604,480 + MXFP4 down 4,456,448），
+    // 但 layer 26 的 gate/up 換成 MXFP4 → 4,456,448*3 = 13,369,344 B。
+    // 若所有槽位都照最大的配，arena 有 21.8% 被浪費 —— 而 arena 是 RAM 預算裡
+    // 最寶貴的資源。
+    //
+    // 解法：槽位分成兩區。「小槽位」給 42 層用，「大槽位」只給 layer 26 用，
+    // 大槽位的數量按「那 1 層佔請求的比例」分配（1/43 ≈ 2.3%）。
+    // 選「大多數層」當小的：用眾數而不是最大值，這樣即使某個模型只有一種大小，
+    // 也不會誤判。
+    {
+        std::map<size_t, int> hist;
+        for (const auto & L : layers_) {
+            hist[(size_t) L.bytes_per_expert]++;
+        }
+        size_t small = 0;
+        int best_n = -1;
+        for (const auto & kv : hist) {
+            if (kv.second > best_n) {
+                best_n = kv.second;
+                small = kv.first;
+            }
+        }
+        const size_t mx = (size_t) (layers_.empty() ? 0 : layers_[0].bytes_per_expert);
+        size_t big = 0;
+        for (const auto & kv : hist) {
+            (void) kv;
+        }
+        big = 0;
+        for (const auto & L : layers_) {
+            if ((size_t) L.bytes_per_expert > small) {
+                big = std::max(big, (size_t) L.bytes_per_expert);
+            }
+        }
+        small_bytes_ = (small + 4095) & ~(size_t) 4095;
+        big_bytes_   = big ? ((big + 4095) & ~(size_t) 4095) : 0;
+        if (big_bytes_ && big_bytes_ <= small_bytes_) {
+            big_bytes_ = 0;   // 其實一樣大，別分兩區
+        }
+        slot_bytes_ = big_bytes_ ? big_bytes_ : small_bytes_;
+        int n_big_layers = 0;
+        for (auto & L : layers_) {
+            L.needs_big_slot = big_bytes_ && (size_t) L.bytes_per_expert > small_bytes_;
+            if (L.needs_big_slot) {
+                n_big_layers++;
+            }
+        }
+        (void) mx;
+        fprintf(stderr,
+                "[sdq] 槽位大小：小的 %zu B（%zu 層）／大的 %zu B（%d 層）\n",
+                small_bytes_, (size_t) ((int) layers_.size() - n_big_layers), big_bytes_, n_big_layers);
+    }
+}
+
+bool pager::need_big_slot(int il, int ie) const {
+    if (!big_bytes_) {
+        return false;
+    }
+    const layer_desc * L = layer(il);
+    if (!L) {
+        return false;
+    }
+    if (L->needs_big_slot) {
+        return true;
+    }
+    return ie >= 0 && ie < (int) L->experts.size() &&
+           (size_t) L->experts[(size_t) ie].bytes > small_bytes_;
+}
+
+void pager::alloc_arena() {
+    const size_t slot = cfg_.slot_bytes ? cfg_.slot_bytes : slot_bytes_;
+    slot_bytes_ = slot;
+
+    // arena 大小決定：RAM 是「總預算」，不是「還有多少可用」
+    //   總預算 = 非專家權重(2.4 GB) + KV cache + ggml 計算緩衝 + 詞表 + arena
+    // 所以有指定 ram_budget 時，用「目前 RSS（不含 arena）」當作已用額度扣掉。
+    // 預留量要涵蓋 arena 之外、但「在 pager 算完之後才長出來」的記憶體：
+    //   llama.cpp 的 CPU compute buffer（125 MiB @ubatch=128、502 MiB @512）
+    //   + KV cache（ctx=4096 約 670 MiB）+ 圖與執行緒堆疊
+    // 這些在 sizing 的當下還沒配置，所以不會出現在 rss_now 裡，必須手動扣。
+    // 設太小 = 實際用量會超過 RAM 預算。實測（RLIMIT_DATA 8 GB、ctx 4096、681 token 提示詞）：
+    //   預留 700 MB  → 峰值 RSS 8231 MB（超出 8 GB 預算 39 MB）
+    //   預留 900 MB  → 峰值 RSS 8035 MB（留 157 MB 餘量）
+    // 代價是槽位數：2039 → 1936 槽，decode 5.85 → 5.37 tok/s（約 -8%）。
+    // 寧可少 8% 速度，也不要在目標機器的 8 GB 上 OOM —— 這是本專案的硬約束。
+    const size_t reserve = (size_t) env_size("SDQ_RESERVE_MB", 900) << 20;
+    const size_t rss_now = process_rss_bytes();
+
+    size_t arena;
+    if (cfg_.ram_budget_bytes) {
+        const size_t used = rss_now;   // 這時候 arena 還沒配置
+        size_t avail = cfg_.ram_budget_bytes > used + reserve
+                     ? cfg_.ram_budget_bytes - used - reserve
+                     : 0;
+        arena = avail;
+        if (cfg_.arena_bytes) {
+            arena = std::min(arena, cfg_.arena_bytes);
+        }
+        fprintf(stderr, "[sdq] RAM 預算 %.2f GiB：已用(RSS) %.2f GiB、預留 %.2f GiB → arena %.2f GiB\n",
+                cfg_.ram_budget_bytes / 1073741824.0, used / 1073741824.0,
+                reserve / 1073741824.0, arena / 1073741824.0);
+    } else {
+        const size_t phys = physical_ram_bytes();
+        const size_t budget = (size_t) (phys * 0.70);
+        arena = cfg_.arena_bytes ? cfg_.arena_bytes : std::min(budget, (size_t) (4ull << 30));
+    }
+    if (arena < slot_bytes_ * 16) {
+        throw std::runtime_error("expert arena 太小");
+    }
+    // 切成兩區：大槽位只分給「需要大槽位的層」，比例 = 那些層佔全部層的比例。
+    const bool force_uniform = env_flag("SDQ_FORCE_UNIFORM_SLOT", false);
+    if (big_bytes_ && small_bytes_ && !layers_.empty() && !force_uniform) {
+        int n_big_layers = 0;
+        for (const auto & L : layers_) {
+            if (L.needs_big_slot) {
+                n_big_layers++;
+            }
+        }
+        const double f = (double) n_big_layers / (double) layers_.size();
+        const double avg = f * (double) big_bytes_ + (1.0 - f) * (double) small_bytes_;
+        size_t n_total = (size_t)((double) arena / avg);
+        size_t nb = (size_t)(n_total * f);
+        // 大槽位的下限不是「有點就好」，而是**工作集的下限**：
+        // 一個 token 在每個大槽位層要 8 個大 expert，這個模型有 3 個大槽位層
+        // → 至少要 3 × 8 = 24 個大槽位，而且還要留給預取的空間。
+        // 只給 16 個時量到過「找不到能放 il=34 ie=114 的槽位」而中止
+        // （這是在 verify 新增的預取壓力測試 [2b] 抓到的）。
+        const size_t big_need = (size_t) (n_big_layers * info_.n_expert_used);
+        if (nb < big_need) {
+            nb = big_need;
+        }
+        if (nb > n_total / 4) {
+            nb = n_total / 4;
+        }
+        // 連工作集下限都放不進去時，寧可讓小槽位少一點（n_total 保持不變），
+        // 否則會算出一個「必定會中止」的配置。
+        n_big_ = nb;
+        n_small_ = n_total > nb ? n_total - nb : 0;
+        arena = n_small_ * small_bytes_ + n_big_ * big_bytes_;
+    } else {
+        // 單一尺寸：全部槽位都是「大的那一種」（slot_bytes_）。
+        // 這是 SDQ_FORCE_UNIFORM_SLOT=1 與「模型只有一種 expert 大小」時的路徑。
+        //
+        // 這裡必須記成 n_small_=0 / n_big_=全部，不能記成「n_small_=全部、單位用大的」：
+        // slot_ptr()/slot_size_of() 是用「索引 < n_small_ → 小槽位」來分支的，
+        // 把它記成全部都是小槽位的話，大 expert 會拿到小槽位的 stride
+        // （寫出槽位邊界、算錯），而且大 expert 永遠配不到槽位 → 推論卡死。
+        // （第一版就是這樣，實驗跑到一半 hang 才找出來。）
+        const size_t unit = slot_bytes_ ? slot_bytes_ : small_bytes_;
+        n_small_ = 0;
+        n_big_ = arena / unit;
+        arena = n_big_ * unit;
+    }
+    if (n_small_ == 0 && n_big_ == 0) {
+        throw std::runtime_error("expert arena 太小（算不出槽位）");
+    }
+    n_slots_ = n_small_ + n_big_;
+    if (n_slots_ < 16) {
+        throw std::runtime_error("expert arena 太小（算不出 16 個槽位）");
+    }
+
+    void * p = nullptr;
+    const size_t alloc = arena + (2ull << 20);
+    if (posix_memalign(&p, 2ull << 20, alloc) != 0 || !p) {
+        throw std::runtime_error("無法配置 expert arena（" + std::to_string(arena >> 20) + " MB）");
+    }
+    // 讓 arena 全部變成實體 RAM，並提示核心使用 huge page（減少 TLB 壓力）
+    memset(p, 0, alloc);
+    madvise(p, alloc, MADV_HUGEPAGE);
+    arena_ = (uint8_t *) p;
+    arena_bytes_ = arena;
+
+    // OPT-1：剖面計數表（n_layer × n_expert，40×256 = 10240 筆 ≈ 40 KB，可忽略）
+    prof_.assign((size_t) info_.n_layer * (size_t) info_.n_expert, 0);
+    ensure_layer_stats((int) info_.n_layer);   // SDQ-0004
+    if (!cfg_.profile_in.empty()) {
+        load_profile(cfg_.profile_in);
+    }
+    profile_out_ = cfg_.profile_out;
+
+    slots_.assign(n_slots_, {});
+    free_slots_.reserve(n_small_);
+    for (size_t i = n_small_; i-- > 0;) {
+        free_slots_.push_back((int32_t) i);
+    }
+    free_big_slots_.reserve(n_big_);
+    for (size_t i = n_slots_; i-- > n_small_;) {
+        free_big_slots_.push_back((int32_t) i);
+    }
+    used_.store(0);
+
+    hist_.assign((size_t) info_.n_layer, {});
+    for (auto & per_layer : hist_) {
+        per_layer.assign((size_t) info_.n_expert, {});
+    }
+    prev_used_.assign((size_t) info_.n_layer, {});
+    cur_used_.assign((size_t) info_.n_layer, {});
+}
+
+void pager::init(const config & cfg, ggml_context * ctx) {
+    (void) ctx;
+    if (ready_) {
+        return;
+    }
+    cfg_ = cfg;
+    if (cfg_.model_path.empty()) {
+        const char * v = getenv("SDQ_MODEL_PATH");
+        cfg_.model_path = v ? v : "";
+    }
+    if (cfg_.model_path.empty()) {
+        throw std::runtime_error("SDQ 缺少模型路徑（設定 SDQ_MODEL_PATH）");
+    }
+
+    // 先讀 header（順便列舉 shard），再開 fd：shard 清單只有在解析
+    // split.count 之後才知道，而 open_model_fd() 需要它。
+    load_gguf_header(cfg_.model_path);
+    open_model_fd();
+    if (shard_fd_.empty() || shard_fd_[0] < 0) {
+        throw std::runtime_error("無法開啟模型檔：" + shard_path(0));
+    }
+    // 順序有意義：I/O 池的對齊緩衝必須在 alloc_arena() 之前配置，
+    // 否則 arena 會把它當成「不存在的 RAM」，實際上就偷用了 8 GB 預算。
+    io_pool_start();
+    alloc_arena();
+
+    if (cfg_.prefetch) {
+        pf_ = std::thread([this] { pf_worker(); });
+    }
+    ready_ = true;
+    print_summary();
+}
+
+const layer_desc * pager::layer(int il) const {
+    if (il < 0 || il >= (int) layers_.size()) {
+        return nullptr;
+    }
+    const layer_desc & L = layers_[(size_t) il];
+    if (L.experts.empty()) {
+        return nullptr;
+    }
+    return &L;
+}
+
+void pager::open_model_fd() {
+    if (shard_paths_.empty()) {
+        shard_paths_.push_back(cfg_.model_path);
+    }
+    shard_fd_.assign(shard_paths_.size(), -1);
+    shard_fd_direct_.assign(shard_paths_.size(), -1);
+    for (size_t i = 0; i < shard_paths_.size(); i++) {
+        shard_fd_[i] = open(shard_paths_[i].c_str(), O_RDONLY);
+        if (shard_fd_[i] < 0) {
+            fprintf(stderr, "[sdq] 無法開啟 shard %zu: %s\n", i, shard_paths_[i].c_str());
+            return;
+        }
+    }
+    // O_DIRECT：讀資料完全不進 kernel page cache。
+    // 這是「RAM 帳目誠實」的關鍵 —— 否則核心預讀會讓 mmap 檔案的頁算進 RSS
+    // （實測 4K prefill 時檔案對映 RSS 可以多到 6 GB 以上），而且量到的
+    // 「SSD 讀取量」會被上一輪的 page cache 灌水。
+    const char * no_direct = getenv("SDQ_NO_DIRECT_IO");
+    if (no_direct && *no_direct && *no_direct != '0') {
+        return;
+    }
+#ifdef O_DIRECT
+    // 每個 shard 各自開一個 O_DIRECT fd：O_DIRECT 是 fd 層級的屬性，不能共用。
+    for (size_t i = 0; i < shard_paths_.size(); i++) {
+        shard_fd_direct_[i] = open(shard_paths_[i].c_str(), O_RDONLY | O_DIRECT);
+        if (shard_fd_direct_[i] < 0) {
+            break;
+        }
+    }
+    use_direct_ = shard_fd_direct_[0] >= 0;
+    if (use_direct_) {
+        fprintf(stderr, "[sdq] 使用 O_DIRECT 讀取模型檔（%zu 個 shard，不佔用 kernel page cache）\n",
+                shard_paths_.size());
+    } else {
+        fprintf(stderr, "[sdq] O_DIRECT 不可用，改用 buffered + fadvise(DONTNEED)\n");
+    }
+#endif
+}
+
+// 有對齊的緩衝區（O_DIRECT 要求），thread_local 避免競爭
+static thread_local uint8_t * g_direct_buf = nullptr;
+static thread_local size_t   g_direct_sz  = 0;
+
+// 與 read_range_direct 相同，但用呼叫端提供的緩衝區（已配置好、已算進 RSS）。
+// I/O 執行緒池走這條：每條 worker 在啟動時就配置好對齊緩衝，於是 arena  sizing 時
+// 這筆記憶體已��在 RSS 裡，不會變成「額外偷用的 RAM」。
+// sharded GGUF：把「哪個 shard」一路帶到 pread。
+static inline int sdq_fd_for(const std::vector<int> & fds, int shard) {
+    if (shard < 0 || shard >= (int) fds.size()) {
+        return -1;
+    }
+    return fds[(size_t) shard];
+}
+
+bool pager::read_range_staged(int shard, uint64_t off, uint8_t * dst, size_t size,
+                              uint8_t * stage, size_t stage_sz) {
+    if (!use_direct_) {
+        return read_range(shard, off, dst, size);
+    }
+    const int fd = sdq_fd_for(shard_fd_direct_, shard);
+    if (fd < 0) {
+        return false;
+    }
+    const size_t blk = 4096;
+    const uint64_t start = off & ~(uint64_t)(blk - 1);
+    const uint64_t end = (off + size + blk - 1) & ~(uint64_t)(blk - 1);
+    const size_t bytes = (size_t)(end - start);
+    if (stage_sz < bytes) {
+        // 預先配置不足（不該發生）：退回 thread_local 的通用路徑
+        return read_range_direct(shard, off, dst, size);
+    }
+    size_t done = 0;
+    while (done < bytes) {
+        const ssize_t n = pread(fd, stage + done, bytes - done,
+                                (off_t)(start + done));
+        if (n <= 0) {
+            return false;
+        }
+        done += (size_t) n;
+    }
+    memcpy(dst, stage + (off - start), size);
+    return true;
+}
+
+bool pager::read_range_direct(int shard, uint64_t off, uint8_t * dst, size_t size) {
+    if (!use_direct_) {
+        return read_range(shard, off, dst, size);
+    }
+    const int fd = sdq_fd_for(shard_fd_direct_, shard);
+    if (fd < 0) {
+        return false;
+    }
+    const size_t blk = 4096;
+    const uint64_t start = off & ~(uint64_t)(blk - 1);
+    const uint64_t end = (off + size + blk - 1) & ~(uint64_t)(blk - 1);
+    const size_t bytes = (size_t)(end - start);
+    if (g_direct_sz < bytes) {
+        if (g_direct_buf) {
+            free(g_direct_buf);
+        }
+        if (posix_memalign((void **) &g_direct_buf, blk, bytes) != 0) {
+            g_direct_buf = nullptr;
+            g_direct_sz = 0;
+            use_direct_ = false;
+            return read_range(shard, off, dst, size);
+        }
+        g_direct_sz = bytes;
+    }
+    size_t done = 0;
+    while (done < bytes) {
+        const ssize_t n = pread(fd, g_direct_buf + done, bytes - done,
+                                (off_t)(start + done));
+        if (n <= 0) {
+            return false;
+        }
+        done += (size_t) n;
+    }
+    memcpy(dst, g_direct_buf + (off - start), size);
+    return true;
+}
+
+bool pager::read_range(int shard, uint64_t off, uint8_t * dst, size_t size) {
+    const int fd = sdq_fd_for(shard_fd_, shard);
+    if (fd < 0) {
+        return false;
+    }
+    size_t done = 0;
+    while (done < size) {
+        const ssize_t n = pread(fd, dst + done, size - done, (off_t) (off + done));
+        if (n <= 0) {
+            return false;
+        }
+        done += (size_t) n;
+    }
+    // 讓 RAM 帳目誠實：把 kernel 對這個檔案的 page cache 丟掉，避免「藏在核心裡的 RAM」
+    if (cfg_.fadvise_dontneed) {
+        posix_fadvise(fd, (off_t) off, (off_t) size, POSIX_FADV_DONTNEED);
+    }
+    return true;
+}
+
+bool pager::read_expert(int il, int ie, uint8_t * dst) {
+    const layer_desc * L = layer(il);
+    if (!L || ie < 0 || ie >= (int) L->experts.size()) {
+        return false;
+    }
+    const expert_desc & ed = L->experts[(size_t) ie];
+    for (int p = 0; p < 3; p++) {
+        if (ed.seg[p].size == 0) {
+            continue;
+        }
+        if (!read_range_direct(ed.seg[p].shard, ed.seg[p].off,
+                               dst + ed.slot_off[p], (size_t) ed.seg[p].size)) {
+            return false;
+        }
+    }
+    return true;
+}
+
+// ---------------------------------------------------------------- I/O 執行緒池
+//
+// 問題：一個 expert = gate / up / down 三段，檔案上是三段不相鄰的資料。
+// 循序讀就是 3 次 pread 排在同一條執行緒上，而單次 1.9 MB 的 pread 在本機量到
+// ~7 ms（≈275 MB/s 的單流頻寬）。因此「一個 expert 要多久」= 3 × 單次延遲，
+// 這條路徑的長度跟「有多少條執行緒」無關 —— mode C 再怎麼排程都救不了。
+//
+// 做法：把三段交給三條執行緒同時 pread，臨界路徑降到約「單段」的時間。
+// 量測（8 個 expert 全部 miss 的一層，各 9 次取中位數）：
+//     8 執行緒 × 三段序列讀 : 12.60 ms
+//    16 執行緒 × 三段平行讀 :  7.57 ms
+//    24 執行緒 × 三段平行讀 :  7.58 ms   ← 16 就飽和，所以預設 3 × n_threads
+//
+// 這個池子對 prefill 更有用：一層要 256 個 expert = 768 個讀取工作，
+// 序列讀時 16 執行緒只能拿到 16 路的頻寬 utilization。
+void pager::io_pool_start() {
+    if (!cfg_.io_parallel) {
+        fprintf(stderr, "[sdq] I/O 段平行：關（每個 expert 的 gate/up/down 循序讀）\n");
+        return;
+    }
+    int n = cfg_.io_threads > 0 ? cfg_.io_threads : cfg_.n_threads * 3;
+    if (n < 4) {
+        n = 4;
+    }
+if (n > 48) {
+        n = 48;
+    }
+    // 先算「一段權重最大有多少位元組」，每條 worker 配一塊對齊緩衝。
+    // 這必须在 alloc_arena() 之前做完，否則這筆 RAM 會變成帳外支出。
+    size_t max_seg = 0;
+    for (const auto & L : layers_) {
+        for (const auto & ed : L.experts) {
+            for (int p = 0; p < 3; p++) {
+                max_seg = std::max(max_seg, (size_t) ed.seg[p].size);
+            }
+        }
+    }
+    const size_t stage_bytes = ((max_seg + 2 * 4096) + 4095) & ~(size_t) 4095;
+    io_stage_.assign((size_t) n, io_stage{});
+    for (int i = 0; i < n; i++) {
+        void * p = nullptr;
+        if (posix_memalign(&p, 4096, stage_bytes) == 0 && p) {
+            memset(p, 0, stage_bytes);   // 實際碰頁，讓它出現在 RSS 裡
+            io_stage_[(size_t) i].buf = (uint8_t *) p;
+            io_stage_[(size_t) i].sz  = stage_bytes;
+        }
+    }
+    io_split_ = cfg_.io_split > 0 ? cfg_.io_split : 1;
+    io_stop_ = false;
+    io_pool_.reserve((size_t) n);
+    for (int i = 0; i < n; i++) {
+        const size_t wid = (size_t) i;
+        try {
+            io_pool_.emplace_back([this, wid] { io_worker(wid); });
+        } catch (...) {
+            break;
+        }
+    }
+    io_threads_ = (int) io_pool_.size();
+    io_pool_on_ = io_threads_ > 0;
+    if (io_pool_on_) {
+        fprintf(stderr, "[sdq] I/O 段平行：%d 條讀取執行緒 × %zu KB 對齊緩衝"
+                        "（gate/up/down 同時讀，每段再切 %d 塊）\n",
+                io_threads_, stage_bytes >> 10, io_split_);
+    }
+}
+
+void pager::io_pool_stop() {
+    if (io_pool_.empty()) {
+        for (auto & s : io_stage_) {
+            free(s.buf);
+            s.buf = nullptr;
+        }
+        io_stage_.clear();
+        return;
+    }
+    {
+        std::lock_guard<std::mutex> lk(io_mu_);
+        io_stop_ = true;
+    }
+    io_cv_.notify_all();
+    for (auto & t : io_pool_) {
+        if (t.joinable()) {
+            t.join();
+        }
+    }
+    io_pool_.clear();
+    io_pool_on_ = false;
+    for (auto & s : io_stage_) {
+        free(s.buf);
+        s.buf = nullptr;
+        s.sz = 0;
+    }
+    io_stage_.clear();
+}
+
+void pager::io_worker(size_t wid) {
+    for (;;) {
+        io_job job{};
+        {
+            std::unique_lock<std::mutex> lk(io_mu_);
+            io_cv_.wait(lk, [this] { return io_stop_ || !io_q_.empty(); });
+            if (io_q_.empty()) {
+                if (io_stop_) {
+                    return;
+                }
+                continue;
+            }
+            job = io_q_.front();
+            io_q_.pop_front();
+        }
+        io_jobs_.fetch_add(1, std::memory_order_relaxed);
+        // 讀取本身不持鎖：io_mu_ 只保護佇列與完成計數
+        const bool ok = (wid < io_stage_.size() && io_stage_[wid].buf)
+                      ? read_range_staged(job.shard, job.off, job.dst, job.size,
+                                          io_stage_[wid].buf, io_stage_[wid].sz)
+                      : read_range_direct(job.shard, job.off, job.dst, job.size);
+        {
+            std::lock_guard<std::mutex> lk(io_mu_);
+            if (!ok) {
+                job.ctx->ok = false;
+            }
+            if (job.ctx->remaining.fetch_sub(1) == 1) {
+                io_done_cv_.notify_all();
+            }
+        }
+    }
+}
+
+// 把 (il,ie) 的三段交給執行緒池並行讀，呼叫端等到整批完成才返回。
+// ctx 放在呼叫端 stack：worker 只會在 remaining 歸零之後才再碰它，
+// 而我們正是等到 remaining==0 才離開函式，所以沒有 use-after-return。
+bool pager::read_expert_par(int il, int ie, uint8_t * dst) {
+    const layer_desc * L = layer(il);
+    if (!L || ie < 0 || ie >= (int) L->experts.size()) {
+        return false;
+    }
+    if (!io_pool_on_) {
+        return read_expert(il, ie, dst);
+    }
+    const expert_desc & ed = L->experts[(size_t) ie];
+    io_ctx ctx;
+    int n = 0;
+    // 把每一段再切成一樣大的好幾塊，交給不同的執行緒同時讀。
+    //
+    // 為什麼：單一 pread 的時間 ≈ 固定延遲 + 位元組數 / 單流頻寬。
+    // 本機實測單流約 275 MB/s、4K 隨機讀延遲約 0.57 ms，所以
+    //   590 KB 讀一次 ≈ 0.57 + 2.1 = 2.7 ms
+    //   590 KB 切成 2 塊 ≈ 0.57 + 1.05 = 1.6 ms
+    // 而「讀完一個 expert」的時間正是每層的關鍵路徑，切塊就是直接砍關鍵路徑。
+    // 設定檔 SDQ_IO_SPLIT。**實測預設是 1（不切塊）**：切塊在 24 條讀取執行緒
+    // 之下沒有可重現的改善（split=1..6 的中位數在 4.9~5.9 之間跳動，純噪音），
+    // 因為 8 個 expert × 3 段 = 24 個並行請求已經把裝置的佇列灌飽，
+    // 這時瓶頸是裝置總頻寬而不是單一請求的延遲。保留這個開關是為了其他裝置。
+    const int split = io_split_;
+    const size_t blk = 4096;
+    {
+        std::lock_guard<std::mutex> lk(io_mu_);
+        for (int p = 0; p < 3; p++) {
+            const size_t sz = (size_t) ed.seg[p].size;
+            if (sz == 0) {
+                continue;
+            }
+            uint8_t * base = dst + ed.slot_off[p];
+            const int sh = ed.seg[p].shard;
+            if (split <= 1 || sz <= 2 * blk) {
+                io_q_.push_back(io_job{sh, ed.seg[p].off, base, sz, &ctx});
+                n++;
+                continue;
+            }
+            size_t chunk = ((sz + (size_t) split - 1) / (size_t) split + blk - 1) & ~(blk - 1);
+            for (size_t off = 0; off < sz; off += chunk) {
+                const size_t take = sz - off < chunk ? sz - off : chunk;
+                io_q_.push_back(io_job{sh, ed.seg[p].off + off, base + off, take, &ctx});
+                n++;
+            }
+        }
+        ctx.remaining.store(n);
+    }
+    if (n == 0) {
+        return true;
+    }
+    io_cv_.notify_all();
+    const uint64_t t0 = now_us();
+    {
+        std::unique_lock<std::mutex> lk(io_mu_);
+        io_done_cv_.wait(lk, [&ctx] { return ctx.remaining.load() == 0; });
+    }
+    io_wait_ns_.fetch_add((now_us() - t0) * 1000ull, std::memory_order_relaxed);
+    return ctx.ok;
+}
+
+uint64_t pager::read_expert_span(int il, const int32_t * experts, int n, const int32_t * slots) {
+    const layer_desc * L = layer(il);
+    if (!L || n <= 0) {
+        return 0;
+    }
+    const uint64_t t_start = now_us();
+    // 每個執行緒一份暫存區（多執行緒會同時呼叫，不能共用一個 buffer）
+    static thread_local std::vector<uint8_t> scratch_buf;
+    uint64_t total = 0;
+
+    // 把 experts 切成「檔案編號連續」的區段
+    int i = 0;
+    while (i < n) {
+        int j = i + 1;
+        while (j < n && experts[j] == experts[j - 1] + 1) {
+            j++;
+        }
+        const int cnt = j - i;
+        const expert_desc & first = L->experts[(size_t) experts[i]];
+        const expert_desc & last = L->experts[(size_t) experts[j - 1]];
+
+        for (int p = 0; p < 3; p++) {
+            if (first.seg[p].size == 0 || last.seg[p].size == 0) {
+                continue;
+            }
+            // 連續區段必須在同一個 shard 內；跨 shard 就切斷這個區段。
+            if (last.seg[p].shard != first.seg[p].shard) {
+                continue;
+            }
+            const uint64_t off = first.seg[p].off;
+            const uint64_t end = last.seg[p].off + last.seg[p].size;
+            const size_t bytes = (size_t) (end - off);
+            if (scratch_buf.size() < bytes) {
+                scratch_buf.assign(bytes, 0);
+            }
+            if (!read_range_direct(first.seg[p].shard, off, scratch_buf.data(), bytes)) {
+                return total;
+            }
+            total += bytes;
+            // 散到各自的槽位：scratch 從 off 開始，所以偏移是「相對於 off」
+            for (int k = i; k < j; k++) {
+                const expert_desc & ed = L->experts[(size_t) experts[k]];
+                const size_t seg_bytes = (size_t) ed.seg[p].size;
+                const size_t delta = (size_t) (ed.seg[p].off - off);
+                if (slots[k] < 0) {
+                    continue;
+                }
+                if ((size_t) slots[k] >= n_slots_ || (uint64_t) ed.slot_off[p] + seg_bytes > slot_bytes_
+                    || delta + seg_bytes > scratch_buf.size()) {
+                    fprintf(stderr, "[sdq-pager] span 越界：il=%d slot=%d/%zu slot_off=%lld seg=%zu delta=%zu scratch=%zu p=%d e=%d\n",
+                            il, slots[k], n_slots_, (long long) ed.slot_off[p], seg_bytes, delta, scratch_buf.size(), p, experts[k]);
+                    return total;
+                }
+                memcpy(slot_ptr(slots[k]) + ed.slot_off[p],
+                       scratch_buf.data() + delta, seg_bytes);
+            }
+        }
+        i = j;
+    }
+    stats_.demand_wait_us.fetch_add(now_us() - t_start, std::memory_order_relaxed);
+    return total;
+}
+
+int pager::reserve_slot(int il, int ie) {
+    if (!ready_) {
+        return -1;
+    }
+    count_request(il, ie);
+    std::lock_guard<std::mutex> lk(mu_);
+    const int32_t exist = find_slot_locked(il, ie);
+    if (exist >= 0) {
+        slots_[(size_t) exist].last_use = ++clock_;
+        slots_[(size_t) exist].pin++;
+        touch_freq_locked(slots_[(size_t) exist]);
+        return exist;
+    }
+    const int32_t s = victim_locked();
+    if (s < 0) {
+        return -1;
+    }
+    slot_state & st = slots_[(size_t) s];
+    if (st.layer >= 0) {
+        page_.erase(((int64_t) st.layer << 20) | (int64_t) st.expert);
+        stats_.evictions.fetch_add(1, std::memory_order_relaxed);
+        used_.fetch_sub(1, std::memory_order_relaxed);
+    }
+    st.layer = il;
+    st.expert = ie;
+    st.last_use = ++clock_;
+    st.freq = 1;
+    st.pin = 1;
+    st.is_hot = hot_lookup(il, ie);
+    page_[((int64_t) il << 20) | (int64_t) ie] = s;
+    used_.fetch_add(1, std::memory_order_relaxed);
+    stats_.expert_misses.fetch_add(1, std::memory_order_relaxed);
+    return s;
+}
+
+int pager::probe(int il, int ie) {
+    if (!ready_) {
+        return -1;
+    }
+    stats_.expert_requests.fetch_add(1, std::memory_order_relaxed);
+    count_request(il, ie);
+    std::lock_guard<std::mutex> lk(mu_);
+    const int32_t s = find_slot_locked(il, ie);
+    if (s < 0) {
+        stats_.expert_misses.fetch_add(1, std::memory_order_relaxed);
+        return -1;
+    }
+    slots_[(size_t) s].last_use = ++clock_;
+    slots_[(size_t) s].pin++;
+    touch_freq_locked(slots_[(size_t) s]);
+    stats_.expert_hits.fetch_add(1, std::memory_order_relaxed);
+    return s;
+}
+
+void pager::note_span_read(uint64_t bytes) {
+    stats_.ssb_read_bytes_demand.fetch_add(bytes, std::memory_order_relaxed);
+    stats_.demand_wait_us.fetch_add(0, std::memory_order_relaxed);
+}
+
+// 衰減式頻率：每 8192 次使用就把所有計數減半，讓「過去熱門、現在變冷」的 expert 能被淘汰
+void pager::touch_freq_locked(slot_state & st) {
+    if (++freq_tick_ >= 8192) {
+        freq_tick_ = 0;
+        for (auto & s : slots_) {
+            s.freq /= 2;
+        }
+    }
+    if (st.freq < 0xFFFFFFFFu) {
+        st.freq++;
+    }
+}
+
+// ============================== OPT-1：熱門 expert 剖面 ==============================
+// 問題實測（docs/03）：arena 3.88 GiB 只放得下 2044 個 expert，總共卻有 10240 個，
+// prefill 的幾百個「只用一次」的專家會把熱區整個洗掉，命中率卡在 ~70%。
+// 解法借用 Strata 的做法（src/core/expert_cache.cpp）：**離線剖面 + 靜態排行榜 +
+// 熱頁永不淘汰**。這裡不動檔案格式，用純文字存排行榜。
+
+// ---- SDQ-0004
+void pager::ensure_layer_stats(int n_layer) {
+    if (lstats_ || n_layer <= 0) {
+        return;
+    }
+    lstats_.reset(new layer_stat[(size_t) n_layer]);
+}
+
+void pager::count_request(int il, int ie) {
+    if (prof_.empty() || il < 0 || ie < 0) {
+        return;
+    }
+    const size_t idx = (size_t) il * (size_t) info_.n_expert + (size_t) ie;
+    if (idx < prof_.size()) {
+        // 單執行緒 ++ 即可：請求次數是統計用途，不參與任何正確性判斷
+        if (prof_[idx] < 0xFFFFFFFFu) {
+            prof_[idx]++;
+        }
+    }
+}
+
+bool pager::hot_lookup(int il, int ie) const {
+    if (hot_.empty() || il < 0 || ie < 0) {
+        return false;
+    }
+    const size_t idx = (size_t) il * (size_t) info_.n_expert + (size_t) ie;
+    return idx < hot_.size() && hot_[idx] != 0;
+}
+
+// 挑一個容得下 (il,ie) 的槽。與 victim_locked 的差別：**先只在冷頁裡找**，
+// 找不到才退讓去動熱頁。這就是「熱區不會被 prefill 洗掉」的機制。
+// 這個槽位放得下「需要 big 的 expert」嗎？
+//   小槽位：只能放小 expert
+//   大槽位：小expert 也放得下（只是浪費一點空間）
+static inline bool slot_accepts(bool need_big, bool slot_is_big) {
+    return !need_big || slot_is_big;
+}
+
+int pager::admit_slot_locked(int il, int ie) {
+    // il/ie 都 < 0 代表「不指定大小」→ 兩種槽位都可以（舊的呼叫路徑）。
+    const bool need_big = (il >= 0 && ie >= 0) ? need_big_slot(il, ie) : false;
+    // 完全沒用過的空槽永遠優先（它不是熱頁，佔用等於浪費）
+    // 大 expert 先看大槽位；小 expert 先看小槽位。
+    std::vector<int32_t> & first  = need_big ? free_big_slots_ : free_slots_;
+    std::vector<int32_t> & second = need_big ? free_slots_ : free_big_slots_;
+    while (!first.empty()) {
+        const int32_t s = first.back();
+        if (!slots_[(size_t) s].busy) {
+            first.pop_back();
+            return s;
+        }
+    }
+    // 第一輪：只在「冷頁」裡挑最久未用的。
+    //   want_hot=true  → 熱門 expert 進來時，把冷頁換掉（不動其他熱頁）
+    //   want_hot=false → 冷門 expert 進來時，優先吃冷頁
+    // 兩種情況的規則相同，所以 hot_lookup 的結果不影響選擇順序，只影響標記。
+    for (int pass = 0; pass < 2; pass++) {
+        int64_t best = -1;
+        uint64_t best_clock = UINT64_MAX;
+        for (size_t s = 0; s < n_slots_; s++) {
+            const slot_state & st = slots_[s];
+            if (st.pin > 0 || st.busy) {
+                continue;
+            }
+            if (pass == 0 && st.is_hot) {
+                continue;   // 第一輪不動熱頁
+            }
+            if (!slot_accepts(need_big, is_big_slot(s))) {
+                continue;
+            }
+            if (st.last_use < best_clock) {
+                best_clock = st.last_use;
+                best = (int64_t) s;
+            }
+        }
+        if (best >= 0) {
+            return (int) best;
+        }
+    }
+    // 退讓：另一種大小的空槽。**一定要檢查放不放得下** —— 小槽位放不下大 expert，
+    // 硬塞會讓 read_expert 寫出槽位邊界（靜默把別的 expert 寫壞）。
+    while (!second.empty()) {
+        const int32_t s = second.back();
+        if (!slots_[(size_t) s].busy &&
+            slot_accepts(need_big, is_big_slot(s))) {
+            second.pop_back();
+            return s;
+        }
+        if (!slots_[(size_t) s].busy) {
+            second.pop_back();
+        } else {
+            break;
+        }
+    }
+    return -1;
+}
+
+bool pager::load_profile(const std::string & path) {
+    std::FILE * f = std::fopen(path.c_str(), "rb");
+    if (!f) {
+        fprintf(stderr, "[sdq] 找不到 expert 剖面 %s（將以動態 LRU/LFU 運作）\n", path.c_str());
+        return false;
+    }
+    char magic[8] = {0};
+    if (std::fread(magic, 1, 4, f) != 4 || std::memcmp(magic, "SDQP", 4) != 0) {
+        std::fclose(f);
+        fprintf(stderr, "[sdq] %s 不是 SDQ expert 剖面（缺少 SDQP 標頭）\n", path.c_str());
+        return false;
+    }
+    uint32_t hdr[3] = {0, 0, 0};
+    if (std::fread(hdr, sizeof(uint32_t), 3, f) != 3) {
+        std::fclose(f);
+        return false;
+    }
+    const uint32_t n = hdr[2];
+    std::vector<std::pair<uint32_t, std::pair<int32_t, int32_t>>> ranked;
+    ranked.reserve(n);
+    for (uint32_t i = 0; i < n; i++) {
+        int32_t l = 0, e = 0;
+        uint32_t c = 0;
+        if (std::fread(&l, sizeof(int32_t), 1, f) != 1) break;
+        if (std::fread(&e, sizeof(int32_t), 1, f) != 1) break;
+        if (std::fread(&c, sizeof(uint32_t), 1, f) != 1) break;
+        ranked.push_back({c, {l, e}});
+    }
+    std::fclose(f);
+    std::sort(ranked.begin(), ranked.end(),
+              [](const auto & a, const auto & b) { return a.first > b.first; });
+
+    hot_.assign((size_t) info_.n_layer * (size_t) info_.n_expert, 0);
+    const int want = cfg_.hot_pin > 0 ? cfg_.hot_pin : (int) ranked.size();
+    n_hot_ = 0;
+    for (const auto & r : ranked) {
+        if (n_hot_ >= want) {
+            break;
+        }
+        const int l = r.second.first, e = r.second.second;
+        if (l < 0 || l >= info_.n_layer || e < 0 || e >= info_.n_expert) {
+            continue;
+        }
+        const size_t idx = (size_t) l * (size_t) info_.n_expert + (size_t) e;
+        if (!hot_[idx]) {
+            hot_[idx] = 1;
+            n_hot_++;
+        }
+    }
+    fprintf(stderr, "[sdq] expert 剖面：%s → 釘選 %d / %zu 個熱門 expert（永不淘汰）\n",
+            path.c_str(), n_hot_, ranked.size());
+    return n_hot_ > 0;
+}
+
+void pager::dump_profile(const std::string & path) {
+    if (prof_.empty()) {
+        return;
+    }
+    std::vector<std::pair<uint32_t, std::pair<int32_t, int32_t>>> ranked;
+    ranked.reserve(prof_.size());
+    uint64_t total = 0;
+    for (int l = 0; l < info_.n_layer; l++) {
+        for (int e = 0; e < info_.n_expert; e++) {
+            const uint32_t c = prof_[(size_t) l * (size_t) info_.n_expert + (size_t) e];
+            if (c > 0) {
+                ranked.push_back({c, {l, e}});
+                total += c;
+            }
+        }
+    }
+    std::sort(ranked.begin(), ranked.end(),
+              [](const auto & a, const auto & b) { return a.first > b.first; });
+    std::FILE * f = std::fopen(path.c_str(), "wb");
+    if (!f) {
+        fprintf(stderr, "[sdq] 無法寫出 expert 剖面 %s\n", path.c_str());
+        return;
+    }
+    std::fwrite("SDQP", 1, 4, f);
+    const uint32_t hdr[3] = {1, (uint32_t) info_.n_layer, (uint32_t) ranked.size()};
+    std::fwrite(hdr, sizeof(uint32_t), 3, f);
+    for (const auto & r : ranked) {
+        const int32_t l = r.second.first, e = r.second.second;
+        const uint32_t c = r.first;
+        std::fwrite(&l, sizeof(int32_t), 1, f);
+        std::fwrite(&e, sizeof(int32_t), 1, f);
+        std::fwrite(&c, sizeof(uint32_t), 1, f);
+    }
+    std::fclose(f);
+    // 覆盖率報告：前 K 名可以蓋掉多少請求 → 直接決定 hot_pin 該設多少
+    uint64_t acc = 0;
+    const size_t ks[6] = {512, 1024, 1536, 2048, 3072, 4096};
+    fprintf(stderr, "[sdq] expert 剖面已寫到 %s（%zu 個有被用到，總請求 %llu）\n",
+            path.c_str(), ranked.size(), (unsigned long long) total);
+    size_t ki = 0;
+    for (size_t i = 0; i < ranked.size(); i++) {
+        acc += ranked[i].first;
+        if (ki < 6 && i + 1 == ks[ki]) {
+            fprintf(stderr, "[sdq]   前 %5zu 名涵蓋 %6.2f%% 的請求\n",
+                    ks[ki], 100.0 * (double) acc / (double) (total ? total : 1));
+            ki++;
+        }
+    }
+}
+
+int pager::find_slot_locked(int il, int ie) {
+    const int64_t key = ((int64_t) il << 20) | (int64_t) ie;
+    auto it = page_.find(key);
+    return it == page_.end() ? -1 : it->second;
+}
+
+// 找一個「可以放 (il,ie) 而且 last_use <= stale_before」的槽位。
+//
+// 為什麼不能直接用 victim_stale_locked()：大小兩種槽位之後，那個函式會掃過**所有**
+// 槽位（包含小槽位），於是一個需要大槽位的 expert 可能拿到小槽位，
+// 預取時 read_expert 會寫出槽位邊界 → 靜默把鄰居槽位的資料寫壞。
+// 這是引進大小兩種槽位時真正會咬人的地方。
+//
+// 順序：先看對應尺寸的���槽（從沒用過，最該拿來放預取），
+// 再掃全部槽位挑最久未用的（放得下的那種尺寸）。
+int pager::victim_stale_for(int il, int ie, uint64_t stale_before) {
+    const bool need_big = need_big_slot(il, ie);
+    std::vector<int32_t> & first  = need_big ? free_big_slots_ : free_slots_;
+    std::vector<int32_t> & second = need_big ? free_slots_ : free_big_slots_;
+    for (std::vector<int32_t> * lst : { &first, &second }) {
+        while (!lst->empty()) {
+            const int32_t s = lst->back();
+            if (slots_[(size_t) s].busy) {
+                break;
+            }
+            if (slots_[(size_t) s].last_use <= stale_before &&
+                slot_accepts(need_big, is_big_slot(s))) {
+                lst->pop_back();
+                return s;
+            }
+            lst->pop_back();
+        }
+    }
+    int64_t best = -1;
+    uint64_t best_clock = UINT64_MAX;
+    for (size_t i = 0; i < n_slots_; i++) {
+        const slot_state & st = slots_[i];
+        if (st.pin > 0 || st.busy || st.last_use > stale_before) {
+            continue;
+        }
+        if (!slot_accepts(need_big, is_big_slot(i))) {
+            continue;
+        }
+        if (st.last_use < best_clock) {
+            best_clock = st.last_use;
+            best = (int64_t) i;
+        }
+    }
+    return (int) best;
+}
+
+int pager::victim_stale_locked(uint64_t stale_before) {
+    // 只挑「last_use 很舊」而且沒被 pin 的槽：保護最近的工作集
+    while (!free_slots_.empty()) {
+        const int32_t s = free_slots_.back();
+        if (!slots_[(size_t) s].busy && slots_[(size_t) s].last_use <= stale_before) {
+            free_slots_.pop_back();
+            return s;
+        }
+        if (free_slots_.size() * 4 < n_slots_) {
+            break;
+        }
+        free_slots_.pop_back();
+    }
+    int64_t best = -1;
+    uint64_t best_clock = UINT64_MAX;
+    for (size_t i = 0; i < n_slots_; i++) {
+        const slot_state & st = slots_[i];
+        if (st.pin > 0 || st.busy || st.last_use > stale_before) {
+            continue;
+        }
+        if (st.last_use < best_clock) {
+            best_clock = st.last_use;
+            best = (int64_t) i;
+        }
+    }
+    return (int) best;
+}
+
+int pager::acquire(int il, int ie, bool blocking) {
+    if (!ready_) {
+        return -1;
+    }
+    std::unique_lock<std::mutex> lk(mu_);
+    int32_t s = find_slot_locked(il, ie);
+    if (s >= 0 && slots_[s].busy) {
+        // 這個槽位**正在被填入**：另一條執行緒剛 admit 它、資料還沒讀完。
+        //
+        // 這裡一定要等，不能當成命中直接用。否則讀到的是「寫到一半的權重」，
+        // 而且那個錯誤是**非決定性**的 —— 每次執行結果可能不同（實測在
+        // prefill 時會讓同一個提示詞跑出不同的文字）。
+        // busy 的槽位在 admit/victim 那邊本來就會被跳過，所以這裡是唯一
+        // 還能拿到它的路徑，也因此必須在這裡等。
+        const uint64_t t0 = now_us();
+        while (slots_[s].busy) {
+            lk.unlock();
+            std::this_thread::sleep_for(std::chrono::microseconds(200));
+            lk.lock();
+            if (now_us() - t0 > (uint64_t) env_size("SDQ_BUSY_WAIT_MS", 30000) * 1000) {
+                fprintf(stderr,
+                        "[sdq] 致命：等待槽位 il=%d ie=%d 讀入超過 %u ms（busy 一直沒解除）\n",
+                        il, ie, (unsigned) env_size("SDQ_BUSY_WAIT_MS", 30000));
+                std::fflush(stderr);
+                abort();
+            }
+        }
+        // 讀取可能失敗（那時槽位已被清空）→ 重新走一次正常的 miss 路徑
+        if (find_slot_locked(il, ie) != s) {
+            s = -1;
+        }
+    }
+    if (s >= 0) {
+        slots_[s].last_use = ++clock_;
+        slots_[s].pin++;
+        touch_freq_locked(slots_[(size_t) s]);
+        stats_.expert_requests.fetch_add(1, std::memory_order_relaxed);
+        stats_.expert_hits.fetch_add(1, std::memory_order_relaxed);
+        if (lstats_ && il >= 0 && il < (int) info_.n_layer) {
+            lstats_[il].req.fetch_add(1, std::memory_order_relaxed);
+            lstats_[il].hit.fetch_add(1, std::memory_order_relaxed);
+        }
+        // A prefetch that already finished counts as "used" here. Without this
+        // the finished-before-request case was invisible and prefetch precision
+        // was understated (docs/10 §f).
+        if (slots_[s].from_prefetch) {
+            slots_[s].from_prefetch = false;
+            stats_.prefetch_used.fetch_add(1, std::memory_order_relaxed);
+            stats_.prefetch_bytes_used.fetch_add(slot_size_of(s), std::memory_order_relaxed);
+        }
+        return s;
+    }
+
+    stats_.expert_requests.fetch_add(1, std::memory_order_relaxed);
+    count_request(il, ie);
+    stats_.expert_misses.fetch_add(1, std::memory_order_relaxed);
+    if (lstats_ && il >= 0 && il < (int) info_.n_layer) {
+        lstats_[il].req.fetch_add(1, std::memory_order_relaxed);
+        lstats_[il].miss.fetch_add(1, std::memory_order_relaxed);
+    }
+
+    // 先找一個已經在背景讀入這頁的槽
+    for (size_t i = 0; i < n_slots_; i++) {
+        slot_state & st = slots_[i];
+        if (st.busy && st.layer == il && st.expert == ie) {
+            // 等背景執行緒讀完
+            lk.unlock();
+            const uint64_t t0 = now_us();
+            while (true) {
+                lk.lock();
+                if (!slots_[i].busy) {
+                    break;
+                }
+                lk.unlock();
+                std::this_thread::sleep_for(std::chrono::microseconds(200));
+            }
+            s = (int32_t) i;
+            lk.unlock();
+            stats_.prefetch_wait_us.fetch_add(now_us() - t0, std::memory_order_relaxed);
+            std::unique_lock<std::mutex> lk2(mu_);
+            slots_[s].last_use = ++clock_;
+            slots_[s].pin++;
+            stats_.expert_hits.fetch_add(1, std::memory_order_relaxed);
+            stats_.prefetch_used.fetch_add(1, std::memory_order_relaxed);
+            return s;
+        }
+    }
+
+    if (!blocking) {
+        return -1;
+    }
+
+    // 選槽位時必須知道「這個 expert 需要哪一種大小」，否則大 expert 可能被塞進小槽位
+    // （寫出邊界 → 靜默算錯），或者小 expert 佔掉大槽位（浪費 6.8% 的 arena）。
+    s = admit_slot_locked(il, ie);
+    if (s < 0) {
+        // 拿不到槽位：短暫等待別的執行緒解除 pin（每層開頭會 unpin_all）。
+        // 這裡「重試」而不是直接回 -1，因為回 -1 會讓呼叫端**跳過這個 expert**，
+        // 結果是靜默少算一條專家分支 —— 那是最嚴重的錯誤。
+        // 2000 次 × 250 µs = 最多等 0.5 秒；真的撐不到那麼久，代表 arena 被
+        // 預取的 busy 槽位佔住了（實測：跨層預取開啟時會發生）。
+        for (int attempt = 0; attempt < 2000 && s < 0; attempt++) {
+            lk.unlock();
+            std::this_thread::sleep_for(std::chrono::microseconds(250));
+            lk.lock();
+            s = admit_slot_locked(il, ie);
+        }
+        if (s < 0) {
+            fprintf(stderr,
+                    "[sdq] 嚴重：找不到能放 il=%d ie=%d（need_big=%d）的槽位，"
+                    "大槽 %zu／小槽 %zu\n",
+                    il, ie, (int) need_big_slot(il, ie), n_big_, n_small_);
+            // 這裡「回 -1」會讓呼叫端**跳過這個 expert**，結果是靜默少算一條專家分支
+            // —— 那是整個引擎最嚴重的錯誤型態（模型會安靜地給出錯誤答案，而且
+            // 每次執行還不一定一樣）。寧可整個行程死掉，也不要產出「看起來正常」
+            // 的錯誤結果。
+            fprintf(stderr,
+                    "[sdq] 致命：無法取得 expert 槽位。為了不給出靜默錯誤的結果，"
+                    "直接中止。請回報這個情況（多半是預取把槽位佔成 busy 太久）。\n");
+            std::fflush(stderr);
+            abort();
+        }
+    }
+    slot_state & st = slots_[s];
+    if (st.layer >= 0) {
+        page_.erase(((int64_t) st.layer << 20) | (int64_t) st.expert);
+        stats_.evictions.fetch_add(1, std::memory_order_relaxed);
+        used_.fetch_sub(1, std::memory_order_relaxed);
+    }
+    st.layer = il;
+    st.expert = ie;
+    st.last_use = ++clock_;
+    st.pin = 1;
+    st.is_hot = hot_lookup(il, ie);
+    // **先標 busy，再 publish 到 page_。**
+    // 順序反過來的話（先 publish 再標 busy 中間有一個窗口）另一條執行緒會把它
+    // 當成命中，然後在資料還沒讀完時就拿去做矩陣乘法 → 非決定性的錯誤輸出。
+    // acquire() 看到 busy 會等；admit/victim 本來就會跳過 busy 的槽位。
+    st.busy = true;
+    page_[((int64_t) il << 20) | (int64_t) ie] = s;
+
+    lk.unlock();
+
+    const uint64_t t0 = now_us();
+    const bool ok = read_expert_par(il, ie, slot_ptr(s));
+    const uint64_t dt = now_us() - t0;
+
+    std::unique_lock<std::mutex> lk2(mu_);
+    st.busy = false;
+    if (!ok) {
+        st.layer = -1;
+        st.expert = -1;
+        st.pin = 0;
+        page_.erase(((int64_t) il << 20) | (int64_t) ie);
+        return -1;
+    }
+    used_.fetch_add(1, std::memory_order_relaxed);
+    stats_.demand_wait_us.fetch_add(dt, std::memory_order_relaxed);
+    const layer_desc * L = layer(il);
+    if (L) {
+        const uint64_t nb = (uint64_t) L->experts[(size_t) ie].bytes;
+        stats_.ssb_read_bytes_demand.fetch_add(nb, std::memory_order_relaxed);
+        if (lstats_ && il >= 0 && il < (int) info_.n_layer) {   // SDQ-0004
+            lstats_[il].demand_bytes.fetch_add(nb, std::memory_order_relaxed);
+        }
+    }
+    return s;
+}
+
+void pager::prefetch_expert(int il, int ie) {
+    if (!ready_ || !cfg_.prefetch) {
+        return;
+    }
+    {
+        std::unique_lock<std::mutex> lk(mu_);
+        if (find_slot_locked(il, ie) >= 0) {
+            stats_.prefetch_duplicate.fetch_add(1, std::memory_order_relaxed);
+            return;
+        }
+        // 預取只能占用「空槽」或「已經很久沒被用到的頁」。
+        // （實測：無差別淘汰會讓命中率從 90% 掉到 27%，而預取使用率是 0%，純粹有害。）
+        //
+        // **槽位一定要選對尺寸**：need_big_slot() 為真的 expert 拿到小槽位會寫出邊界。
+        const uint64_t stale_before = clock_ - (uint64_t) env_size("SDQ_PREFETCH_STALE_TOKENS", 2) * 320;
+        // 預取佇列也不能太深：SSD 讀不夠快時，排在後面的預取早就過期了
+        if (pf_q_.size() > (size_t) env_size("SDQ_PREFETCH_QUEUE", 64)) {
+            return;
+        }
+        // **必須留夠空的槽位給 demand。**
+        // 預取會把槽位標成 busy 並佔著它讀取；大槽位本來就少（工作集下限是
+        // n_big_layers × n_expert_used），如果預取把最後幾個空槽都吃掉，
+        // 下一層的 demand 就會「找不到能放 il=34 ie=114 的槽位」而中止。
+        // （這是 verify 新增的預取壓力測試 [2b] 抓到的實際情況。）
+        // 所以：對應尺寸的空槽少於 n_expert_used 個時，這一筆預取直接不做。
+        const size_t reserve = (size_t) info_.n_expert_used;
+        const size_t n_free_right = need_big_slot(il, ie) ? free_big_slots_.size() : free_slots_.size();
+        if (n_free_right < reserve) {
+            stats_.prefetch_duplicate.fetch_add(1, std::memory_order_relaxed);
+            return;
+        }
+        const int32_t s = victim_stale_for(il, ie, stale_before);
+        if (s < 0) {
+            return;
+        }
+        slot_state & st = slots_[s];
+        if (st.layer >= 0) {
+            page_.erase(((int64_t) st.layer << 20) | (int64_t) st.expert);
+            stats_.evictions.fetch_add(1, std::memory_order_relaxed);
+            used_.fetch_sub(1, std::memory_order_relaxed);
+        }
+        st.layer = il;
+        st.expert = ie;
+        st.busy = true;
+        st.pin = 0;
+        pf_q_.push_back({s, il, ie, now_us()});
+        stats_.prefetch_issued.fetch_add(1, std::memory_order_relaxed);
+    }
+    pf_cv_.notify_one();
+}
+
+void pager::pf_worker() {
+    std::unique_lock<std::mutex> lk(pf_mu_);
+    for (;;) {
+        pf_cv_.wait(lk, [this] { return pf_stop_ || !pf_q_.empty(); });
+        if (pf_stop_ && pf_q_.empty()) {
+            return;
+        }
+        const pf_item item = pf_q_.front();
+        pf_q_.pop_front();
+        lk.unlock();
+
+        // 這個槽可能已經被淘汰/重用 → 檢查 generation
+        {
+            std::unique_lock<std::mutex> g(mu_);
+            const slot_state & st = slots_[item.slot];
+            const bool still = st.busy && st.layer == item.il && st.expert == item.ie;
+            if (!still) {
+                lk.lock();
+                continue;
+            }
+        }
+
+        // 預取也走 I/O 段平行：單獨一條執行緒循序讀三段，是這條路徑唯一的瓶頸。
+        const bool ok = cfg_.io_parallel ? read_expert_par(item.il, item.ie, slot_ptr(item.slot))
+                                         : read_expert(item.il, item.ie, slot_ptr(item.slot));
+        const layer_desc * L = layer(item.il);
+        {
+            std::unique_lock<std::mutex> g(mu_);
+            slot_state & st = slots_[item.slot];
+            if (st.busy && st.layer == item.il && st.expert == item.ie) {
+                st.busy = false;
+                st.last_use = ++clock_;
+                if (ok) {
+                    page_[((int64_t) item.il << 20) | (int64_t) item.ie] = item.slot;
+                    used_.fetch_add(1, std::memory_order_relaxed);
+                    stats_.prefetch_completed.fetch_add(1, std::memory_order_relaxed);
+                    // SDQ-0004: tag the page so the demand path can credit it,
+                    // and so unused prefetched bytes can be reported as waste.
+                    st.from_prefetch = true;
+                    if (lstats_ && item.il >= 0 && item.il < (int) info_.n_layer) {
+                        lstats_[item.il].prefetch_bytes.fetch_add(
+                            (uint64_t) slot_size_of(item.slot), std::memory_order_relaxed);
+                    }
+                    if (L) {
+                        stats_.ssb_read_bytes_prefetch.fetch_add(
+                            (uint64_t) L->experts[(size_t) item.ie].bytes, std::memory_order_relaxed);
+                    }
+                } else {
+                    st.layer = -1;
+                    st.expert = -1;
+                }
+            }
+        }
+        lk.lock();
+    }
+}
+
+void pager::release(int s) {
+    if (s < 0 || (size_t) s >= n_slots_) {
+        return;
+    }
+    std::lock_guard<std::mutex> lk(mu_);
+    slot_state & st = slots_[(size_t) s];
+    if (st.pin > 0) {
+        st.pin--;
+    }
+}
+
+void pager::unpin_all() {
+    std::unique_lock<std::mutex> lk(mu_);
+    for (auto & st : slots_) {
+        st.pin = 0;
+    }
+}
+
+void pager::note_used(int il, int ie) {
+    if (il < 0 || ie < 0) {
+        return;
+    }
+    std::lock_guard<std::mutex> lk(hist_mu_);
+    if (il >= (int) cur_used_.size()) {
+        return;
+    }
+    auto & v = cur_used_[(size_t) il];
+    if (std::find(v.begin(), v.end(), ie) == v.end()) {
+        v.push_back(ie);
+    }
+}
+
+// 「下一層」預取：只在 layer L 的 op 開頭呼叫一次。
+//
+// 為什麼需要這個函式：end_token() 是**整個 token 的 40 層都算完之後**才被呼叫的
+// （sdq_cli.cpp 在 llama_decode 之後呼叫），所以它排的預取完全沒有和任何計算重疊
+// —— 量測上 prefetch 使用率只有 0~8 %，等於整條預取路徑是關的。
+// 在 layer L 開始時就替 layer L+1 排預取，才有一整層的時間（讀＋算，約 4 ms）
+// 可以讓 SSD 讀取躲在後面。
+//
+// 預測用的是 prev_used_[il+1]（上一個 token 在該層選的專家）—— MoE 的路由在
+// 鄰近 token 之間非常穩定，這是最便宜且不用訓練的預測器。
+void pager::prefetch_layer_ahead(int il) {
+    if (!ready_ || !cfg_.prefetch || il < 0 || il >= (int) layers_.size()) {
+        return;
+    }
+    int32_t ids[64];
+    const int k = (int) info_.n_expert_used;
+    if (k <= 0 || k > 64) {
+        return;
+    }
+    predict(il, ids, k);
+    for (int i = 0; i < k; i++) {
+        prefetch_expert(il, ids[i]);
+    }
+}
+
+// SDQ-0005: called once per llama_decode() from any front end.
+//
+// sdq-chat drives this itself from main(); llama-server does not, which left
+// tokens at 0, ssd_bytes_per_token undefined and SDQ_STATS_FILE empty. This is
+// the single place that closes a decode step, so hook it here.
+//
+// n_tokens > 1 means prefill: a whole prompt was just paged in. Counting that as
+// one "token" would make ssd_bytes_per_token meaningless, and feeding it to the
+// Markov table would poison the transition counts with a whole-batch transition.
+// So prefill advances the byte accounting by n_tokens but leaves the routing
+// history alone -- it is not a single-token transition.
+void pager::note_decode(int n_tokens) {
+    if (!ready_ || n_tokens <= 0) {
+        return;
+    }
+    stats_.tokens.fetch_add((uint64_t) n_tokens, std::memory_order_relaxed);
+    if (n_tokens == 1) {
+        end_token();
+    }
+    dump_stats("decode");
+}
+
+void pager::end_token() {
+    if (!ready_) {
+        return;
+    }
+    // 用「上個 token 的選擇」更新一階 Markov 轉移表
+    {
+        std::lock_guard<std::mutex> lk(hist_mu_);
+        for (size_t il = 0; il < cur_used_.size(); il++) {
+            auto & cur = cur_used_[il];
+            if (cur.empty()) {
+                continue;
+            }
+            auto & layer_hist = hist_[il];
+            // 以每層最近一次（或平均）的前一次選擇為前驅
+            if (!prev_used_.empty() && il < prev_used_.size() && !prev_used_[il].empty()) {
+                for (int32_t from : prev_used_[il]) {
+                    trans & t = layer_hist[(size_t) from];
+                    for (int32_t to : cur) {
+                        int found = -1;
+                        for (int32_t i = 0; i < t.n; i++) {
+                            if (t.to[i] == to) {
+                                t.cnt[i]++;
+                                found = i;
+                                break;
+                            }
+                        }
+                        if (found < 0 && t.n < 64) {
+                            t.to[t.n] = to;
+                            t.cnt[t.n] = 1;
+                            t.n++;
+                        }
+                    }
+                }
+            }
+            prev_used_[il] = cur;
+            cur.clear();
+        }
+    }
+
+    // 依預測排預取
+    if (!cfg_.prefetch) {
+        return;
+    }
+    int32_t ids[64];
+    for (size_t il = 0; il < layers_.size(); il++) {
+        const int k = (int) info_.n_expert_used;
+        predict((int) il, ids, k);
+        for (int i = 0; i < k; i++) {
+            prefetch_expert((int) il, ids[i]);
+        }
+    }
+}
+
+void pager::predict(int il, int32_t * out, int k) {
+    if (il < 0 || il >= (int) prev_used_.size()) {
+        for (int i = 0; i < k; i++) {
+            out[i] = i;
+        }
+        return;
+    }
+    // 以最近一次選擇為前驅；沒有歷史就直接沿用上一次的選擇
+    const std::vector<int32_t> & prev = prev_used_[(size_t) il];
+    std::vector<std::pair<uint32_t, int32_t>> scored;
+    if (prev.empty()) {
+        for (int i = 0; i < k; i++) {
+            out[i] = i;
+        }
+        return;
+    }
+    for (int32_t from : prev) {
+        const trans & t = hist_[(size_t) il][(size_t) from];
+        for (int32_t i = 0; i < t.n; i++) {
+            scored.push_back({t.cnt[i], t.to[i]});
+        }
+    }
+    if (scored.empty()) {
+        for (size_t i = 0; i < prev.size() && i < (size_t) k; i++) {
+            out[i] = prev[i];
+        }
+        for (int i = (int) prev.size(); i < k; i++) {
+            out[i] = i;
+        }
+        return;
+    }
+    std::sort(scored.begin(), scored.end(), [](auto & a, auto & b) {
+        return a.first > b.first;
+    });
+    for (int i = 0; i < k && i < (int) scored.size(); i++) {
+        out[i] = scored[(size_t) i].second;
+    }
+}
+
+double pager::hit_rate() const {
+    const uint64_t req = stats_.expert_requests.load();
+    const uint64_t hit = stats_.expert_hits.load();
+    return req ? (double) hit / (double) req : 0.0;
+}
+
+void pager::shutdown() {
+    if (!ready_) {
+        return;
+    }
+    if (!profile_out_.empty()) {
+        std::lock_guard<std::mutex> lk(mu_);
+        dump_profile(profile_out_);
+    }
+    if (pf_.joinable()) {
+        {
+            std::unique_lock<std::mutex> lk(pf_mu_);
+            pf_stop_ = true;
+        }
+        pf_cv_.notify_all();
+        pf_.join();
+    }
+    io_pool_stop();
+    for (auto & fd : shard_fd_) {
+        if (fd >= 0) {
+            close(fd);
+        }
+    }
+    for (auto & fd : shard_fd_direct_) {
+        if (fd >= 0) {
+            close(fd);
+        }
+    }
+    shard_fd_.clear();
+    shard_fd_direct_.clear();
+    ready_ = false;
+}
+
+pager::~pager() {
+    shutdown();
+    if (arena_) {
+        // 注意：arena 是 posix_memalign 配置的，必須用 free() 釋放，
+        // 用 munmap() 會破壞 glibc 的 heap（之後任何 free 都會報 double free）。
+        free(arena_);
+        arena_ = nullptr;
+    }
+}
+
+static double pct(uint64_t a, uint64_t b) {
+    return b ? 100.0 * (double) a / (double) b : 0.0;
+}
+
+void pager::print_summary() const {
+    if (!ready_) {
+        return;
+    }
+    const layer_desc * L0 = layer(0);
+    if (L0 && !L0->experts.empty()) {
+        const expert_desc & e = L0->experts[0];
+        fprintf(stderr, "[sdq]   page-map: n_layer=%lld n_expert=%lld n_expert_used=%lld n_embd=%lld n_ff_exp=%lld"
+                " | L0E0 gate=%llu/%llu up=%llu/%llu down=%llu/%llu (off/size) ne0=%lld ne1=%lld d_ne0=%lld d_ne1=%lld\n",
+                (long long) info_.n_layer, (long long) info_.n_expert, (long long) info_.n_expert_used,
+                (long long) info_.n_embd, (long long) info_.n_ff_exp,
+                (unsigned long long) e.seg[part::GATE].off, (unsigned long long) e.seg[part::GATE].size,
+                (unsigned long long) e.seg[part::UP].off, (unsigned long long) e.seg[part::UP].size,
+                (unsigned long long) e.seg[part::DOWN].off, (unsigned long long) e.seg[part::DOWN].size,
+                (long long) e.ne0, (long long) e.ne1, (long long) e.down_ne0, (long long) e.down_ne1);
+    }
+    fprintf(stderr,
+            "[sdq] expert pager ready: %s\n"
+            "[sdq]   熱門 expert 釘選：%d 個%s\n"
+            "[sdq]   slot=%.2f MiB (%zu B)  slots=%zu  arena=%.2f GiB  (RAM 實測 RSS=%.2f GiB)\n",
+            cfg_.model_path.c_str(),
+            n_hot_, n_hot_ > 0 ? "（永不淘汰）" : "（無剖面，用動態 LRU/LFU）",
+            slot_bytes_ / 1048576.0, slot_bytes_, n_slots_, arena_bytes_ / 1073741824.0,
+            process_rss_bytes() / 1073741824.0);
+    if (n_big_) {
+        // 大小兩種槽位：把配置結果講清楚，否則只看「slots=N」會誤以為每個槽一樣大。
+        fprintf(stderr,
+                "[sdq]   槽位分兩種：小 %.2f MiB × %zu + 大 %.2f MiB × %zu（平均 %.2f MiB）\n",
+                small_bytes_ / 1048576.0, n_small_,
+                big_bytes_ / 1048576.0, n_big_,
+                (double) arena_bytes_ / (double) (n_slots_ ? n_slots_ : 1) / 1048576.0);
+    }
+    fprintf(stderr,
+            "[sdq]   prefetch=%s  fadvise_dontneed=%d\n",
+            cfg_.prefetch ? "on" : "off", (int) cfg_.fadvise_dontneed);
+}
+
+void pager::dump_stats(const char * phase) {
+    if (cfg_.stats_path.empty()) {
+        return;
+    }
+    const uint64_t tokens = stats_.tokens.load();
+    const uint64_t req    = stats_.expert_requests.load();
+    const uint64_t hit    = stats_.expert_hits.load();
+    const uint64_t issued = stats_.prefetch_issued.load();
+    const uint64_t used   = stats_.prefetch_used.load();
+    const uint64_t b_dem  = stats_.ssb_read_bytes_demand.load();
+    const uint64_t b_pre  = stats_.ssb_read_bytes_prefetch.load();
+    // SDQ-0004: prefetched bytes that were consumed, so the rest is real waste.
+    const uint64_t b_pre_used = stats_.prefetch_bytes_used.load();
+
+    std::ostringstream o;
+    o << "{\"phase\":\"" << phase << "\""
+      << ",\"tokens\":" << tokens
+      << ",\"expert_requests\":" << req
+      << ",\"expert_hits\":" << hit
+      << ",\"expert_misses\":" << (req - hit)
+      << ",\"hit_rate\":" << pct(hit, req)
+      << ",\"ssb_demand_bytes\":" << b_dem
+      << ",\"ssb_prefetch_bytes\":" << b_pre
+      << ",\"ssb_total_bytes\":" << (b_dem + b_pre)
+      << ",\"ssd_bytes_per_token\":" << (tokens ? (double) (b_dem + b_pre) / (double) tokens : 0.0)
+      << ",\"prefetch_issued\":" << issued
+      << ",\"prefetch_used\":" << used
+      << ",\"prefetch_used_rate\":" << pct(used, issued)
+      // SDQ-0004: prefetch waste. b_pre counts every byte the background reader
+      // pulled in; b_pre_used counts the ones a demand request actually hit.
+      // The difference is what made docs/07's negative result worse than "slower".
+      << ",\"prefetch_bytes_used\":" << b_pre_used
+      << ",\"prefetch_bytes_wasted\":" << (b_pre > b_pre_used ? b_pre - b_pre_used : 0)
+      << ",\"prefetch_waste_rate\":" << pct(b_pre > b_pre_used ? b_pre - b_pre_used : 0, b_pre)
+      << ",\"prefetch_duplicate\":" << stats_.prefetch_duplicate.load()
+      << ",\"evictions\":" << stats_.evictions.load()
+      << ",\"demand_wait_us\":" << stats_.demand_wait_us.load()
+      << ",\"prefetch_wait_us\":" << stats_.prefetch_wait_us.load()
+      << ",\"arena_bytes\":" << arena_bytes_
+      // 大小兩種槽位之後，「用掉幾個槽位」不能直接乘 slot_bytes_（那是大的那種）。
+      // dump_stats 只在階段轉換時呼叫一次，遍歷兩千幾個槽位的成本可以忽略。
+      << ",\"arena_used_bytes\":" << used_bytes_snapshot()
+      << ",\"rss_bytes\":" << process_rss_bytes()
+      << ",\"n_slots\":" << n_slots_
+      << ",\"n_small_slots\":" << n_small_
+      << ",\"n_big_slots\":" << n_big_
+      << ",\"small_slot_bytes\":" << small_bytes_
+      << ",\"big_slot_bytes\":" << big_bytes_
+      << ",\"slot_bytes\":" << slot_bytes_
+      // SDQ-0004: per-layer breakdown. docs/10 needs this to tell "the device is
+      // slow" apart from "one layer keeps evicting everyone else's experts".
+      << ",\"per_layer\":[";
+    for (int64_t il = 0; lstats_ && il < (int64_t) info_.n_layer; il++) {
+        const uint64_t lreq = lstats_[il].req.load();
+        const uint64_t lhit = lstats_[il].hit.load();
+        o << (il ? "," : "")
+          << "{\"layer\":" << il
+          << ",\"req\":" << lreq
+          << ",\"hit\":" << lhit
+          << ",\"miss\":" << (lreq - lhit)
+          << ",\"hit_rate\":" << pct(lhit, lreq)
+          << ",\"demand_bytes\":" << lstats_[il].demand_bytes.load()
+          << ",\"prefetch_bytes\":" << lstats_[il].prefetch_bytes.load()
+          << "}";
+    }
+    o << "]" << "}";
+    std::ofstream f(cfg_.stats_path, std::ios::app);
+    if (f) {
+        f << o.str() << "\n";
+    }
+}
+
+} // namespace sdq
+namespace sdq {
+// 由 CLI 呼叫：依環境變數/參數初始化 pager
+bool sdq_pager_active_for_layer(int il) {
+    pager & P = pager::instance();
+    if (!P.ready() || P.layer(il) == nullptr) {
+        // ⚠️ 分頁開著、但某一層沒有頁面表 —— 千萬不要「靜靜地」走回原生路徑。
+        // 這時 expert 權重是 sdq_buft 的假 buffer（內容恆為 0），
+        // mul_mat_id 會算出一堆 0，然後看起來像「模型壞了」而不是「沒分頁」。
+        // 直接當場出局，比輸出亂碼好診斷。
+        if (P.ready() && il >= 0) {
+            static std::mutex m;
+            static bool warned = false;
+            std::lock_guard<std::mutex> lk(m);
+            if (!warned) {
+                warned = true;
+                fprintf(stderr,
+                        "[sdq] 致命錯誤：分頁已啟用，但第 %d 層沒有 expert 頁面表"
+                        "（模型只有 %lld 層）。若這是 MTP / 投機解碼圖，"
+                        "這個模型的分頁路徑還沒支援它；請改用 --no-mtp 或不要開啟 MTP。\n",
+                        il, (long long) P.info().n_layer);
+            }
+            std::abort();
+        }
+        return false;
+    }
+    // 除錯用：SDQ_MOE_LO / SDQ_MOE_HI 可以只讓部分層走分頁路徑，
+    // 用來二分搜尋第一個發生數值差異的層。
+    static const int lo = [] { const char * e = getenv("SDQ_MOE_LO"); return e ? atoi(e) : 0; }();
+    static const int hi = [] { const char * e = getenv("SDQ_MOE_HI"); return e ? atoi(e) : 1 << 30; }();
+    return il >= lo && il < hi;
+}
+
+void sdq_on_decode(int n_tokens) {
+    auto & inst = pager::instance();
+    if (inst.ready()) {
+        inst.note_decode(n_tokens);
+    }
+}
+
+bool sdq_init(const std::string & model_path) {
+    config c;
+    c.model_path = model_path;
+    c.arena_bytes = env_size("SDQ_ARENA_MB", 0) << 20;
+    c.ram_budget_bytes = env_size("SDQ_RAM_BUDGET_MB", 0) << 20;
+    c.slot_bytes = env_size("SDQ_SLOT_KB", 0) << 10;
+    // 預設關閉。docs/07 的實測是「開 5.68 / 關 6.20 tok/s」的負結果，而且
+    // 預取中的槽位會讓 acquire() 靜默跳過 expert，曾造成輸出不一致（stage S7）。
+    // 這裡原本是 true，等於讓那個負結果從來沒有真正生效。
+    c.prefetch = env_flag("SDQ_PREFETCH", false);
+    // ---- OPT-1：熱門 expert 剖面（Strata 式）----
+    if (const char * pi = getenv("SDQ_PROFILE_IN"))  { c.profile_in  = pi; }
+    if (const char * po = getenv("SDQ_PROFILE_OUT")) { c.profile_out = po; }
+    c.hot_pin = (int) env_size("SDQ_HOT_PIN", 0);
+    c.admit_min_hits = (int) env_size("SDQ_ADMIT_MIN_HITS", 1);
+    c.fadvise_dontneed = env_flag("SDQ_FADV_DONTNEED", true);
+    c.io_parallel = env_flag("SDQ_IO_PARALLEL", true);
+    // I/O 讀取執行緒數。sdq-chat 會在載入模型「之前」自己 setenv 這個值
+    // （3 × 計算執行緒，上限 48，docs/05 量到序列 3.79 → 24 條 6.68 tok/s）。
+    // 但 cfg_.n_threads 從來沒有被賦值，所以任何沒有自行設定的前端
+    // （llama-server 就是）會拿到 0，然後在 io_pool_start() 被夾到下限 4 條 ——
+    // 等於一直跑在「序列讀」那一端。改成在 pager 自己算，量測與 sdq-chat 一致。
+    if (!getenv("SDQ_IO_THREADS")) {
+        const int hw = (int) std::max(1u, std::thread::hardware_concurrency());
+        const int compute = hw < 8 ? hw : 8;      // 與 sdq-chat 同一個上限 8
+        c.io_threads = compute * 3;
+    } else {
+        c.io_threads = (int) env_size("SDQ_IO_THREADS", 0);
+    }
+    c.io_split = (int) env_size("SDQ_IO_SPLIT", 1);
+    c.verbose = env_flag("SDQ_VERBOSE", false);
+    const char * sp = getenv("SDQ_STATS_FILE");
+    if (sp) {
+        c.stats_path = sp;
+    }
+    sdq_set_config(c);
+    try {
+        pager::instance().init(c, nullptr);
+    } catch (const std::exception & e) {
+        fprintf(stderr, "[sdq] pager 初始化失敗：%s\n", e.what());
+        return false;
+    }
+    return pager::instance().ready();
+}
+
+
+// ---------------------------------------------------------------- 除錯：dump 任意 F32 張量
+// 目的：讓「原生 mul_mat_id 路徑」與「SDQ 分頁路徑」輸出同一層的 MoE 結果，
+// 兩邊各自 dump 一次就能直接 A/B 對照，判定到底是哪一邊算錯。
+namespace {
+struct dump_arg { std::string path; };
+
+void dump_op(ggml_tensor * dst, int ith, int /*nth*/, void * userdata) {
+    if (ith != 0) {
+        return;
+    }
+    const ggml_tensor * src = dst->src[0];
+    dump_arg * a = (dump_arg *) userdata;
+    FILE * f = fopen(a->path.c_str(), "wb");
+    if (!f) {
+        fprintf(stderr, "[sdq-dump] 無法開啟 %s\n", a->path.c_str());
+        return;
+    }
+    const int64_t meta[6] = { src->ne[0], src->ne[1], src->ne[2], src->ne[3],
+                              (int64_t) ggml_nbytes(src), 0 };
+    fwrite(meta, sizeof(int64_t), 6, f);
+    // 只支援 F32 contiguous；其他情況就明確報錯，不要假設
+    if (src->type != GGML_TYPE_F32 || !ggml_is_contiguous(src)) {
+        fprintf(stderr, "[sdq-dump] %s 不是 contiguous F32（type=%d）\n",
+                a->path.c_str(), (int) src->type);
+    } else {
+        fwrite(src->data, sizeof(float), (size_t) (ggml_nelements(src)), f);
+    }
+    fclose(f);
+    fprintf(stderr, "[sdq-dump] %s (%lld 個元素)\n", a->path.c_str(),
+            (long long) ggml_nelements(src));
+}
+} // namespace
+
+ggml_tensor * sdq_maybe_dump_tensor(ggml_context * ctx, ggml_tensor * t, int il) {
+    const char * prefix = getenv("SDQ_MOE_OUT_DUMP");
+    if (!prefix || !t) {
+        return t;
+    }
+    int layer = getenv("SDQ_MOE_OUT_DUMP_LAYER") ? atoi(getenv("SDQ_MOE_OUT_DUMP_LAYER")) : -1;
+    if (layer >= 0 && il != layer) {
+        return t;
+    }
+    dump_arg * a = new dump_arg{ std::string(prefix) + "." + std::to_string(il) };
+    return ggml_custom_4d(ctx, GGML_TYPE_F32, t->ne[0], t->ne[1], t->ne[2], t->ne[3],
+                          &t, 1, dump_op, 1, a);
+}
+
+void sdq_shutdown() {
+    pager & P = pager::instance();
+    sdq_print_time_profile();
+    P.dump_stats("shutdown");
+    P.print_summary();
+    P.shutdown();
+}
+} // namespace sdq

sdq-dsv4/sdq_pager.h

@@ -0,0 +1,472 @@
+// SDQ expert pager：SSD → RAM → CPU 的 MoE 專家分層快取
+//
+// 設計要點
+//   * 分頁單位 = 一個 expert（layer, expert id），大小 ~1.8 MB（三個矩陣：gate/up/down）
+//   * RAM 端是一個固定槽位的 arena（slab），每槽 2 MiB，O(1) 配置、不碎片化
+//   * 淘汰策略：LRU + 本 token 使用中（pinned）的保護
+//   * 預取：依「上一個 token 的專家選擇」用一階 Markov 轉移預測下一個 token 的專家，
+//           交給背景執行緒 pread()，量測「預取命中率 / 預取浪費量」
+//   * 指標：hit/miss、SSD 讀取位元組、demand 停滯時間、prefetch 領先時間、arena 使用量
+//
+// 不使用 swap：所有權重資料只存在 arena（實體 RAM）與檔案（SSD）兩處。
+
+#pragma once
+
+#include <ggml.h>
+#include <ggml-backend.h>
+#include "llama.h"
+
+#include <atomic>
+#include <chrono>
+#include <condition_variable>
+#include <cstddef>
+#include <cstdint>
+#include <deque>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <thread>
+#include <unordered_map>
+#include <vector>
+
+namespace sdq {
+
+// ---------------------------------------------------------------- GGUF 讀取
+struct gguf_info {
+    int64_t n_layer = 0;
+    int64_t n_expert = 0;
+    int64_t n_expert_used = 0;
+    int64_t n_embd = 0;
+    int64_t n_ff_exp = 0;
+    int64_t n_ff_shexp = 0;
+    int64_t n_expert_shared = 0;   // deepseek4 有 1 個 shared expert（不分頁）
+    int64_t n_head = 0;
+    int64_t n_head_kv = 0;
+    int64_t n_embd_head_k = 0;
+    int64_t n_embd_head_v = 0;
+    int64_t context_length = 0;
+    int64_t full_attention_interval = 4;
+    int64_t is_recr[512] = {0};
+    std::string arch;
+    std::string name;
+};
+
+// 一個 expert 槽位：gate/up/down 三段（有些模型把 gate+up 合成 gate_up）
+struct seg_desc {
+    uint64_t off = 0;  // 在「所屬 shard 檔案內」的位元組偏移
+    uint64_t size = 0; // 位元組數
+    // sharded GGUF：同一層的三段不一定在同一個檔案裡（unsplit 後 100+ GB 的模型一定會被切），
+    // 所以每一段都要記得自己屬於哪一個 shard，pread 才知道要開哪個 fd。
+    int      shard = 0;
+};
+
+enum part : int { GATE = 0, UP = 1, DOWN = 2, COUNT = 3 };
+
+struct expert_desc {
+    seg_desc seg[3];
+    int64_t slot_off[3] = {0, 0, 0}; // 三段在 arena 槽位內的相對偏移
+    int64_t ne0 = 0;         // gate/up row 長度（= n_embd）
+    int64_t ne1 = 0;         // gate/up row 數（= n_ff_exp）
+    int64_t down_ne0 = 0;    // down row 長度（= n_ff_exp）
+    int64_t down_ne1 = 0;    // down row 數（= n_embd）
+    ggml_type type[3] = {GGML_TYPE_COUNT, GGML_TYPE_COUNT, GGML_TYPE_COUNT};
+    int64_t bytes = 0;       // 三段總大小
+    bool fused_gate_up = false;
+};
+
+// 一層的所有 expert 描述（40 層 × 256 個）
+struct layer_desc {
+    std::vector<expert_desc> experts;
+    int64_t bytes_per_expert = 0;
+    // 這個層的 expert 比「大多數層」大（Q4_K/Q5_K vs Q6_K）→ 需要大槽位。
+    // 不然的話所有槽位都得按最大的那種配，白白浪費 6.8% 的 arena。
+    bool needs_big_slot = false;
+};
+
+// ---------------------------------------------------------------- 指標
+struct stats {
+    std::atomic<uint64_t> expert_requests{0};   // 每個 (layer, token) 需要幾個 expert
+    std::atomic<uint64_t> expert_hits{0};
+    std::atomic<uint64_t> expert_misses{0};
+    std::atomic<uint64_t> ssb_read_bytes_demand{0};
+    std::atomic<uint64_t> ssb_read_bytes_prefetch{0};
+    std::atomic<uint64_t> prefetch_issued{0};
+    std::atomic<uint64_t> prefetch_completed{0};
+    std::atomic<uint64_t> prefetch_used{0};     // 預取後真的被用到
+    std::atomic<uint64_t> prefetch_duplicate{0};// 預取時已經在 RAM 裡
+    std::atomic<uint64_t> evictions{0};
+    std::atomic<uint64_t> demand_wait_us{0};    // 因為缺頁而停下來等 SSD 的時間
+    std::atomic<uint64_t> prefetch_wait_us{0};
+    std::atomic<uint64_t> prefetch_bytes_used{0}; // prefetched bytes a demand request actually hit
+    std::atomic<uint64_t> tokens{0};
+    std::atomic<uint64_t> moe_calls{0};
+    std::atomic<uint64_t> flops{0};
+};
+
+// ---- SDQ-0004: per-layer cache counters (Phase 0: is any layer starved?)
+struct layer_stat {
+    std::atomic<uint64_t> req{0};
+    std::atomic<uint64_t> hit{0};
+    std::atomic<uint64_t> miss{0};
+    std::atomic<uint64_t> demand_bytes{0};
+    std::atomic<uint64_t> prefetch_bytes{0};
+};
+
+
+// ---------------------------------------------------------------- pager
+struct config {
+    size_t   arena_bytes   = 0;   // 0 = 自動（依 RAM 預算）
+    size_t   slot_bytes    = 0;   // 0 = 自動（依模型推導）
+    int      n_threads     = 0;
+    bool     prefetch      = true;
+    int      prefetch_ahead_layers = 0; // >0 時限制同時在飛的預取數量
+    bool     fadvise_dontneed = true;  // 讀完丟掉 kernel page cache，讓 RAM 帳目誠實
+    bool     verbose       = false;
+    uint64_t ram_budget_bytes = 0;    // 0 = 自動（實體 RAM 的一小部分）
+    std::string model_path;
+    std::string stats_path;
+    int      slot_bias = 0;
+
+    // ---- I/O 執行緒池 ----
+    // 為什麼需要：一個 expert 在檔案上是 gate / up / down 三段「不相鄰」的資料，
+    // 循序讀要 3 次 pread，而單一 pread 在本機量到約 7 ms（1.9 MB / 275 MB/s）。
+    // 也就是說「讀一個 expert」的延遲完全由這三段循序決定，執行緒再多也沒用。
+    // 把三段交給三條執行緒同時讀，單一 expert 的延遵掉到約 1/2~1/3。
+    // （實測：8 個 expert 全部 miss 的一層，序列讀 12.6 ms → 段平行 7.6 ms。）
+    bool     io_parallel = true;      // SDQ_IO_PARALLEL=0 可關（回到序列讀）
+    int      io_threads   = 0;         // 0 = 自動（3 × n_threads，上限 48）
+    int      io_split     = 1;         // SDQ_IO_SPLIT：每一段再切成幾塊並行讀（實測 1 最好）
+
+    // ---- Strata 式「熱門 expert 剖面」（OPT-1）----
+    // 離線用代表性文字跑一次，把每個 (layer, expert) 的請求次數記成剖面；
+    // 執行時把排行榜前 hot_pin 個釘成「熱頁」：熱頁可以被讀取，但**永遠不被淘汰**，
+    // 淘汰時一律先從冷頁挑。這解決的是「prefill 的一次性專家把熱區洗掉」。
+    std::string profile_in;    // 讀取剖面（SDQ_PROFILE_IN）
+    std::string profile_out;   // 結束時輸出剖面（SDQ_PROFILE_OUT）
+    int         hot_pin = 0;   // 釘選前幾名（SDQ_HOT_PIN）
+    int         admit_min_hits = 1;  // 請求次數低於此值就不收進快取（SDQ_ADMIT_MIN_HITS）
+};
+
+class pager {
+public:
+    static pager & instance();
+
+    // 從 GGUF 檔頭建立 expert 頁面表，並配置 RAM arena
+    void init(const config & cfg, ggml_context * ctx);
+
+    bool ready() const { return ready_; }
+    size_t arena_bytes() const { return arena_bytes_; }
+    size_t slot_bytes() const { return slot_bytes_; }
+    size_t n_slots() const { return n_slots_; }
+    size_t small_bytes() const { return small_bytes_; }
+    size_t big_bytes() const { return big_bytes_; }
+    size_t n_small_slots() const { return n_small_; }
+    size_t n_big_slots() const { return n_big_; }
+    const gguf_info & info() const { return info_; }
+
+    // 取得 layer 描述（idx 越界或沒資料回 nullptr）
+    const layer_desc * layer(int il) const;
+
+    // 一次把「連續編號的一串 expert」讀進 RAM：同一層的三個矩陣（gate/up/down）本來
+    // 就各自連續存放，所以 k 個連續 expert 只需要 3 次大讀取（而不是 3k 次）。
+    // 對高延遲的儲存裝置（每個 request 都貴）這是最大的單項加速。
+    //   experts 必須已依編號遞增排序；slots[i] 是 experts[i] 對應的槽位（由呼叫端配置）
+    // 回傳實際讀取的位元組數。
+    uint64_t read_expert_span(int il, const int32_t * experts, int n, const int32_t * slots);
+
+    // 只配置槽位（不讀資料）：回傳槽位索引，-1 表示沒有空槽
+    int reserve_slot(int il, int ie);
+
+    // 查這個 expert 是否已經在 RAM：命中則 pin 並回傳槽位，未命中回傳 -1（不配置）
+    int probe(int il, int ie);
+
+    // 記錄一次合併讀取的位元組數（給指標用）
+    void note_span_read(uint64_t bytes);
+
+    // 確保 (layer, expert) 在 RAM，回傳槽位索引；-1 表示失敗
+    // pinned: 本 token 使用中，不可被淘汰；blocking: 缺頁時是否同步讀 SSD
+    int acquire(int il, int ie, bool blocking);
+
+    // 背景預取：把 page 讀進 arena（非同步），依歷史預測下一個 token 會用到的 expert
+    void prefetch_expert(int il, int ie);
+    // 「下一層」預取：在 layer L 的 op 開頭呼叫，替 layer L+1 排預取。
+    // 與 end_token() 的差別在時機 —— 後者在一個 token 的 40 層全算完才跑，
+    // 那時排的預取沒有任何計算可以重疊，實測使用率只有 0~8 %。
+    void prefetch_layer_ahead(int il);
+
+    // 每層計算開始時呼叫：解除上一層的 pin（本層用到的槽位才受保護）
+    void unpin_all();
+    // 用完一個槽位後立刻放掉 pin（成對呼叫 acquire()）。
+    //
+    // 為什麼需要：原本 pin 是「整層釘住、下一層開頭才 unpin_all」。mode C 的
+    // expert_forward 回傳之後就再也不讀那個槽位（最後的歸約只讀各執行緒自己的
+    // partial 累加緩衝），所以繼續釘著只是白白把工作集撐大。
+    // 撐大的後果很具體：prefill 一個 ubatch 有 128 個 token，一層最多需要
+    // 256 個不同的 expert → 整層釘住 = 256 個槽位不能回收。大小兩種槽位之下，
+    // 大槽位只有約 n_big_layers × n_expert_used 個，於是**必定**在 prefill 時
+    // 「找不到能放 il=34 ie=… 的槽位」而中止。
+    void release(int s);
+    void note_used(int il, int ie);
+    void end_token();
+    // ---- SDQ-0005: one call per llama_decode() from any front end.
+    void note_decode(int n_tokens);
+
+    // 依歷史預測某層下一個 token 的 top-k expert（回傳信心 0..1）
+    void predict(int il, int32_t * out, int k);
+
+    void shutdown();
+    stats & get_stats() { return stats_; }
+
+    // 把當前指標寫成一行 JSON（append 到 stats_path）
+    void dump_stats(const char * phase);
+    void print_summary() const;
+
+    // arena 內的槽位指標
+    // 槽位索引空間是統一的：[0, n_small_) 是小槽位（連續），
+    // [n_small_, n_slots_) 是大槽位（接在小槽位區之後）。
+    uint8_t * slot_ptr(int s) {
+        return (size_t) s < n_small_
+             ? arena_ + (size_t) s * small_bytes_
+             : arena_ + small_bytes_ * n_small_ + (size_t)(s - (int) n_small_) * big_bytes_;
+    }
+    size_t slot_size_of(int s) const {
+        return (size_t) s < n_small_ ? small_bytes_ : big_bytes_;
+    }
+    bool need_big_slot(int il, int ie) const;
+
+    // 這個槽位算不算「大槽位」。
+    //
+    // 判斷依據是**槽位的實際大小**，不是索引 >= n_small_：
+    // 統一尺寸（SDQ_FORCE_UNIFORM_SLOT=1，或模型只有一種 expert 大小）時，
+    // 所有槽位的索引都 < n_small_ 但大小都是大的 —— 用索引判斷會讓大 expert
+    // 永遠配不到槽位，整個推論卡在 admit 的重試迴圈裡。
+    bool is_big_slot(int s) const {
+        return big_bytes_ && slot_size_of(s) >= big_bytes_;
+    }
+
+    size_t used_bytes() const { return used_bytes_snapshot(); }
+    double  hit_rate() const;
+
+    // arena 裡實際被占用的位元組數。大小兩種槽位之後不能用「槽位數 × slot_bytes_」
+    // 計算（slot_bytes_ 是大的那一種），所以真的把槽位走一遍。
+    // 呼叫端：dump_stats（每次解碼階段結束）與 print_summary，不是熱路徑。
+    //
+    // ⚠️ 一定要拿 mu_：slots_ 是被 I/O 執行緒與 op 的執行緒同時寫的。
+    // 舊版沒有鎖，是一個實際的資料競爭（TSan 會報，實務上在 x86 上讀到的是
+    // 撕裂的 int32，數字會亂但不會改變推論結果 —— 這裡只是把它修掉）。
+    size_t used_bytes_snapshot() const {
+        std::lock_guard<std::mutex> lk(mu_);
+        size_t b = 0;
+        for (size_t s = 0; s < slots_.size(); s++) {
+            if (slots_[s].layer >= 0) {
+                b += slot_size_of((int) s);
+            }
+        }
+        return b;
+    }
+
+    // 讀 SSD（同步，給 acquire 用）
+    bool read_expert(int il, int ie, uint8_t * dst);
+
+    // ---- I/O 執行緒池（見 config::io_parallel 的說明）----
+    // 一個「讀取批次」的完成狀態；放在呼叫端的 stack 上，worker 只在 remaining==0
+    // 之後才會再碰它，所以離開 read_expert_par() 之後不會有 dangling pointer。
+    struct io_ctx {
+        std::atomic<int> remaining{0};
+        bool ok = true;
+    };
+    struct io_job {
+        int      shard;
+        uint64_t off;
+        uint8_t * dst;
+        size_t   size;
+        io_ctx * ctx;
+    };
+
+    void io_pool_start();
+    void io_pool_stop();
+    void io_worker(size_t wid);
+    bool read_expert_par(int il, int ie, uint8_t * dst);
+    bool read_range_staged(int shard, uint64_t off, uint8_t * dst, size_t size,
+                           uint8_t * stage, size_t stage_sz);
+
+    // I/O 執行緒池每條 worker 自帶的 O_DIRECT 對齊緩衝（啟動時配置，已計入 RSS）
+    struct io_stage { uint8_t * buf = nullptr; size_t sz = 0; };
+    std::vector<io_stage> io_stage_;
+
+    bool     io_pool_on_ = false;
+    int      io_threads_ = 0;
+    int      io_split_   = 1;
+    std::vector<std::thread> io_pool_;
+    std::mutex io_mu_;
+    std::condition_variable io_cv_;       // 有工作 / 要停
+    std::condition_variable io_done_cv_;  // 某個批次讀完了
+    std::deque<io_job> io_q_;
+    bool io_stop_ = false;
+    std::atomic<uint64_t> io_jobs_{0};
+    std::atomic<uint64_t> io_wait_ns_{0};
+
+private:
+    pager() = default;
+    ~pager();
+
+    struct slot_state {
+        int32_t layer  = -1;
+        int32_t expert = -1;
+        uint64_t last_use = 0;   // LRU 記時
+        uint32_t freq = 0;       // 這個 expert 被用到幾次（衰減式；用來做 LFU 混合策略）
+        uint32_t pin = 0;        // >0 時不可淘汰
+        bool busy = false;       // 背景執行緒正在寫入
+        bool is_hot = false;     // 屬於剖面排行榜：淘汰時最後才會被選中
+        bool from_prefetch = false; // page was filled by the prefetcher
+    };
+
+    struct pf_item {
+        int slot;
+        int il;
+        int ie;
+        uint64_t issue_time_us;
+    };
+
+    void touch_freq_locked(slot_state & st);
+    // ---- OPT-1：剖面 / 熱頁 ----
+    void  count_request(int il, int ie);            // 記一次請求（給剖面用）
+    bool  load_profile(const std::string & path);   // 讀剖面並標記�� hot_pin 名
+    void  dump_profile(const std::string & path);   // 輸出排行榜
+    bool  hot_lookup(int il, int ie) const;
+    void load_gguf_header(const std::string & path);
+    void build_page_map(const std::string & path);
+    void alloc_arena();
+    int  find_slot_locked(int il, int ie);
+    int  admit_slot_locked(int il, int ie);
+    int  victim_locked() { return admit_slot_locked(-1, -1); }
+    int  victim_stale_locked(uint64_t stale_before);
+    int  victim_stale_for(int il, int ie, uint64_t stale_before);
+    void pf_worker();
+    bool read_range(int shard, uint64_t off, uint8_t * dst, size_t size);
+    bool read_range_direct(int shard, uint64_t off, uint8_t * dst, size_t size);
+    void open_model_fd();
+
+    // ---- sharded GGUF：模型被切成多個 -0000N-of-000M.gguf，每個檔有自己的
+    // header、自己的 data_start 與自己的張量子集。pager 必須同時開著全部的 fd，
+    // 並把每個張量的「檔內偏移」記成 (shard, off)。
+    std::vector<std::string> shard_paths_;
+    std::vector<int>          shard_fd_;
+    std::vector<int>          shard_fd_direct_;
+    std::vector<uint64_t>     shard_data_start_;
+    bool                      use_direct_ = false;
+    std::string               shard_path(int i) const {
+        return (i >= 0 && i < (int) shard_paths_.size()) ? shard_paths_[(size_t) i] : std::string();
+    }
+    // 依 GGUF 的 split 命名規則列舉同目錄的所有 shard
+    static std::vector<std::string> list_splits(const std::string & first_path, int n_split);
+
+    bool     ready_ = false;
+    config   cfg_;
+    gguf_info info_;
+    std::vector<layer_desc> layers_;
+
+    uint8_t * arena_ = nullptr;
+    size_t    arena_bytes_ = 0;
+    size_t    slot_bytes_ = 0;   // = max(small_bytes_, big_bytes_)，保留給舊的訊息輸出
+    size_t    small_bytes_ = 0;  // 小槽位大小（大多數層用）
+    size_t    big_bytes_   = 0;  // 大槽位大小；0 = 這個模型沒有大層
+    size_t    n_small_     = 0;
+    size_t    n_big_       = 0;
+    size_t    n_slots_ = 0;
+    mutable std::mutex mu_;
+    std::vector<slot_state> slots_;
+    std::unordered_map<int64_t, int32_t> page_; // (layer<<16|expert) -> slot
+    std::vector<int32_t> free_slots_;   // 空的小槽位
+    std::vector<int32_t> free_big_slots_;
+
+    // ---- OPT-1：剖面 / 熱頁（Strata 式：靜態排行榜 + 熱頁不淘汰）----
+    std::vector<uint32_t> prof_;   // 每個 (layer, expert) 的累計請求次數
+    std::unique_ptr<layer_stat[]> lstats_;   // SDQ-0004
+    void ensure_layer_stats(int n_layer);  // SDQ-0004
+    std::vector<uint8_t>  hot_;    // 是否在排行榜前 hot_pin 名
+    int                   n_hot_ = 0;
+    std::string           profile_out_;
+    uint32_t freq_tick_ = 0;
+    std::atomic<size_t> used_{0};
+    uint64_t clock_ = 0;
+
+    // 背景預取
+    std::thread pf_;
+    std::mutex pf_mu_;
+    std::condition_variable pf_cv_;
+    std::deque<pf_item> pf_q_;
+    bool pf_stop_ = false;
+    std::atomic<uint64_t> pf_inflight_{0};
+
+    // 路由歷史（一階 Markov：上個 token 的 expert -> 這次被選到的次數）
+    struct trans { int32_t to[64]; uint32_t cnt[64]; int32_t n = 0; };
+    std::vector<std::vector<trans>> hist_; // [layer][prev_expert]
+    std::vector<std::vector<int32_t>>  prev_used_; // [layer] 上一個 token 用到的 expert（預測用）
+    std::vector<std::vector<int32_t>>  cur_used_;  // [layer] 當前 token 用到的 expert
+    std::mutex hist_mu_;   // 保護 cur_used_ / prev_used_ / hist_（多執行緒會同時 note_used）
+    std::atomic<uint64_t> hist_lock_{0};
+
+    stats stats_;
+};
+
+// ---------------------------------------------------------------- 工具
+uint64_t now_us();
+size_t   process_rss_bytes();
+size_t   physical_ram_bytes();
+
+// ---------------------------------------------------------------- ggml 介接
+// 自訂 buffer type：expert 權重佔 0 個 RAM 位元組，資料留在檔案裡
+ggml_backend_buffer_type_t sdq_expert_buft();
+
+// 註冊 model params 的 tensor buffer override（expert 權重 → 我們的 buffer）
+void sdq_install_buft_overrides(llama_model_params * params);
+
+// 設定 arena 大小 / 預取開關等（CLI 在載入模型前呼叫）
+bool sdq_init(const std::string & model_path);
+void sdq_set_config(const config & c);
+const config & sdq_get_config();
+void sdq_set_enabled(bool on);
+void sdq_shutdown();
+
+bool sdq_enabled();
+
+// SDQ-0005: bridge for front ends that are not sdq-chat (llama-server).
+// Defined in sdq_pager.cpp; safe to call when the pager was never initialised.
+void sdq_on_decode(int n_tokens);
+
+// 效能計時探針的結果（SDQ_PROFILE_TIME=1）
+void sdq_print_time_profile();
+
+// 自我測試：算一次指定 expert 的 MoE 輸出（給 NumPy 對照用）
+int sdq_moe_selftest(int il, int ie, const float * x, float * out_io,
+                     int64_t n_embd, int64_t n_ff, int n_tok,
+                     float swiglu_limit, int swiglu_mode);
+
+// 建立我們的 MoE ��訂節點。
+// **必須把 gf 傳進來並呼叫 ggml_build_forward_expand(gf, out)**：
+// ggml 的排程器只會為「進了圖的節點」配置 compute buffer，沒註冊的節點其輸出
+// 緩衝區會被 liveness 分析判成可重用，導致 layer>=1 的結果被其他張量覆蓋
+// （實測症狀：layer 0 正確、layer 1 起整個錯掉）。
+ggml_tensor * sdq_build_moe(ggml_cgraph * gf, ggml_context * ctx, ggml_tensor * cur,
+                            ggml_tensor * ids, ggml_tensor * weights, int il,
+                            int64_t n_expert, int64_t n_expert_used,
+                            float swiglu_limit, int swiglu_mode);
+
+// SiLU-gated 激活的 clamp 語意（見 sdq_moe.cpp 的說明）。
+// deepseek4 走 ggml_swiglu_clamp 的語意（只夾 gate 上界），與 SDQ 原版不同。
+enum sdq_swiglu_mode : int {
+    SDQ_SWIGLU_LEGACY_POST_SILU = 0, // SDQ 原版：對稱夾 silu(gate)
+    SDQ_SWIGLU_GGML_FUSED_CLAMP = 1,  // ggml_swiglu_clamp：gate = min(gate, limit)
+};
+
+// 這一層的分頁是否可用（graph build 時呼叫）
+bool sdq_pager_active_for_layer(int il);
+
+// 除錯／驗證用：把某個 F32 張量 dump 到檔案。
+// 必須在「原生 mul_mat_id 路徑」與「SDQ 分頁路徑」兩邊都呼叫，才能做真正的 A/B 對照
+// （env: SDQ_MOE_OUT_DUMP=prefix、SDQ_MOE_OUT_DUMP_LAYER=層編號，-1 = 全部）
+ggml_tensor * sdq_maybe_dump_tensor(ggml_context * ctx, ggml_tensor * t, int il);
+
+
+} // namespace sdq

sdq-dsv4/verify_dequant_dsv4.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""第二層證據：把 verify_moe_dsv4.py 的 NumPy dequant 與 **ggml 自己的**
+dequantize_row_* 逐位元組比對。
+
+為什麼需要：verify_moe_dsv4.py 裡的 IQ3_S / MXFP4 還原是照著 ggml 原始碼手寫的。
+如果那個手寫版本有錯，後面「SDQ 的 C++ kernel 對得上 NumPy」的結論就只是在
+一份錯誤的 reference 上自我一致。這支腳本用 ggml_deq（直接呼叫 ggml 的 C 函式）
+當獨立實作，兩邊必須**逐位元組相同**（|diff| 必須精確為 0，不是「很小」）。
+
+前置：
+  c++ -O2 -o /tmp/opencode/ggml_deq ggml_deq.cpp \
+      -I<llama.cpp>/ggml/include -I<llama.cpp>/ggml/src \
+      -L<llama.cpp>/build/bin -lggml-base -Wl,-rpath,<llama.cpp>/build/bin
+"""
+import os
+import subprocess
+import sys
+
+import numpy as np
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import verify_moe_dsv4 as V  # noqa: E402
+
+GGML_DEQ = os.environ.get('GGML_DEQ', '/tmp/opencode/ggml_deq')
+
+# (tensor suffix, ggml type id, 每列的元素數)
+TARGETS = [
+    ('ffn_gate_exps.weight', 21, 4096),   # IQ3_S（layer 0）
+    ('ffn_up_exps.weight', 21, 4096),     # IQ3_S（layer 0）
+    ('ffn_down_exps.weight', 39, 2048),   # MXFP4（layer 0）
+    ('ffn_gate_exps.weight', 39, 4096),   # MXFP4（layer 26 的 gate/up）
+    ('ffn_down_exps.weight', 39, 2048),   # MXFP4（layer 26 的 down）
+]
+
+
+def main() -> int:
+    kv, tensors = V.parse_headers(V.SHARDS)
+
+    rows = []
+    all_ok = True
+    for il in (0, 26):
+        for suffix, tt, n in TARGETS:
+            name = 'blk.%d.%s' % (il, suffix)
+            if name not in tensors:
+                continue
+            si, off, dims, ttt = tensors[name]
+            if ttt != tt:
+                continue
+            nrow = V.row_bytes(n, tt)
+            # 取該 (layer, tensor) 的第 0 個 expert 的前幾列
+            for row in (0, 1, 137):
+                byte_off = off + row * nrow
+                raw = V.SHARDS[si]
+                got = subprocess.run([GGML_DEQ, str(tt), raw, str(byte_off), str(n)],
+                                     capture_output=True, check=True).stdout
+                ref = np.frombuffer(got, dtype=np.float32)
+                # ggml_deq 讀的是整列（一個 weight 向量），NumPy 這邊用同一段
+                # 位元組還原 —— 兩邊必須對齊同一個 offset。
+                with open(raw, 'rb') as f:
+                    f.seek(byte_off)
+                    mine = V.dequant(f.read(nrow), n, tt)
+                assert ref.shape == mine.shape == (n,)
+                d = np.abs(ref - mine)
+                exact = bool(np.array_equal(ref, mine))
+                all_ok &= exact
+                rows.append((il, suffix, tt, row, float(d.max()), exact))
+                print('%-34s type=%-2d row=%-4d  max|NumPy - ggml| = %g  %s'
+                      % (name, tt, row, d.max(), 'EXACT' if exact else 'MISMATCH'))
+
+    print()
+    print('%d/%d bit-exact' % (sum(1 for r in rows if r[5]), len(rows)))
+    print('ALL BIT-EXACT' if all_ok else 'MISMATCH FOUND')
+    return 0 if all_ok else 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())

sdq-dsv4/verify_moe_dsv4.py

@@ -0,0 +1,313 @@
+#!/usr/bin/env python3
+"""驗證 SDQ 分頁 + 自訂 MoE kernel 的數學正確性（純 NumPy 對照）。
+
+對象：DeepSeek-V4-Flash-0731 UD-IQ4_NL（deepseek4）
+  gate/up : IQ3_S（layer 26 是 MXFP4）
+  down    : MXFP4
+
+做法：直接從 GGUF 的 4 個 shard 讀出該 (layer, expert) 的三段權重 bytes，
+      依 ggml 的 dequantize_row_iq3_s / dequantize_row_mxfp4 還原成 fp32，
+      用 fp32 純重算一次 SiLU-gated MoE 前向，再與
+      `sdq-chat --selftest IL:IE:SEED:OUT.bin` 的輸出比對。
+
+SDQ 這邊走的是「量化 activation + ggml_vec_dot_*」，這邊是 fp32，
+所以殘差應該是 activation 量化誤差量級（~1%），不是結構性錯誤。
+
+swiglu 的 clamp 語意照 ggml_swiglu_clamp（deepseek4 實際走的那條）：
+    gate = min(gate, limit)
+    up   = clamp(up, -limit, limit)
+    out  = silu(gate) * up
+"""
+import os
+import struct
+import sys
+
+import numpy as np
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from ggml_tables import IQ3S_GRID, KVALUES_MXFP4, KMASK_IQ2XS  # noqa: E402
+
+QK_K = 256
+QK_MXFP4 = 32
+
+MODEL_DIR = os.environ.get(
+    'DSV4_MODEL_DIR', '/root/app/work/models/UD-IQ4_NL')
+MODEL = os.path.join(
+    MODEL_DIR, 'DeepSeek-V4-Flash-0731-UD-IQ4_NL-00001-of-00004.gguf')
+SHARDS = [MODEL.replace('00001-of-00004', '%05d-of-00004' % i) for i in range(1, 5)]
+
+# (block_size, type_size) per ggml type id
+BLK = {
+    8: (32, 34),    # Q8_0
+    12: (256, 144),  # Q4_K
+    13: (256, 176),  # Q5_K
+    7: (32, 24),     # Q5_1
+    2: (32, 18),     # Q4_0
+    21: (256, 110),  # IQ3_S
+    39: (32, 17),    # MXFP4
+    14: (256, 210),  # Q6_K
+}
+TYNAME = {8: 'q8_0', 12: 'q4_K', 13: 'q5_K', 7: 'q5_1', 2: 'q4_0',
+          21: 'iq3_s', 39: 'mxfp4', 14: 'q6_K'}
+
+TS = {2: 2, 3: 2, 4: 4, 5: 4, 6: 4, 7: 1, 10: 8, 11: 8, 12: 8}
+FMT = {0: '<B', 1: '<b', 2: '<H', 3: '<h', 4: '<I', 5: '<i', 6: '<f',
+       7: '<B', 10: '<Q', 11: '<q', 12: '<d'}
+
+
+# ------------------------------------------------------------------ GGUF header
+def rstr(f):
+    n = struct.unpack('<Q', f.read(8))[0]
+    return f.read(n)
+
+
+def read_val(f, t):
+    if t == 8:
+        return rstr(f).decode('utf-8', 'replace')
+    if t == 9:
+        et = struct.unpack('<I', f.read(4))[0]
+        n = struct.unpack('<Q', f.read(8))[0]
+        if et == 8:
+            return [rstr(f).decode('utf-8', 'replace') for _ in range(n)]
+        sz = TS[et]
+        buf = f.read(n * sz)
+        return np.frombuffer(buf, dtype=np.dtype(FMT[et])).tolist()
+    buf = f.read(TS[t])
+    return np.frombuffer(buf, dtype=np.dtype(FMT[t]))[0].item()
+
+
+def parse_headers(paths):
+    kv = {}
+    tensors = {}
+    for si, path in enumerate(paths):
+        with open(path, 'rb') as f:
+            assert f.read(4) == b'GGUF'
+            f.read(4)
+            n_tensors = struct.unpack('<Q', f.read(8))[0]
+            n_kv = struct.unpack('<Q', f.read(8))[0]
+            for _ in range(n_kv):
+                k = rstr(f).decode()
+                t = struct.unpack('<I', f.read(4))[0]
+                kv[k] = read_val(f, t)
+            align = kv.get('general.alignment', 32)
+            pending = []
+            for _ in range(n_tensors):
+                name = rstr(f).decode()
+                nd = struct.unpack('<I', f.read(4))[0]
+                dims = struct.unpack('<%dQ' % nd, f.read(8 * nd))
+                tt = struct.unpack('<I', f.read(4))[0]
+                off = struct.unpack('<Q', f.read(8))[0]
+                pending.append((name, dims, tt, off))
+            # data_start 必須在讀完 tensor 資訊表之後才算，否則整體錯開約 18 KB。
+            data_start = (f.tell() + align - 1) // align * align
+            for name, dims, tt, off in pending:
+                tensors[name] = (si, data_start + off, dims, tt)
+    return kv, tensors
+
+
+# ------------------------------------------------------------------ dequant
+def e8m0_to_fp32_half_vec(e):
+    """ggml_e8m0_to_fp32_half：x<2 是 denormal 2^(-128+x)，否則 2^(x-128)。"""
+    e = e.astype(np.int64)
+    small = np.where(e < 2, (0x00200000 << np.maximum(e, 0)), 0)
+    norm = np.where(e >= 2, ((e - 1) << 23), 0)
+    return (small | norm).astype(np.uint32).view(np.float32)
+
+
+def dequant_iq3_s(raw, n):
+    """block_iq3_s = { half d; uint8 qs[64]; uint8 qh[8]; uint8 signs[32];
+                      uint8 scales[4]; }  = 110 B / 256 elements。
+
+    逐字對應 ggml dequantize_row_iq3_s（ggml/src/ggml-quants.c），
+    以「一次處理全部 block」的方式向量化（輸出順序與 C 版完全相同）。
+    """
+    nb = n // QK_K
+    u = np.frombuffer(raw, dtype=np.uint8, count=nb * 110).reshape(nb, 110)
+    d = u[:, 0:2].copy().view(np.float16).reshape(nb).astype(np.float32)
+    qs = u[:, 2:66].astype(np.int32)
+    qh = u[:, 66:74].astype(np.int32)
+    signs = u[:, 74:106].astype(np.int32)
+    scales = u[:, 106:110].astype(np.int32)
+
+    grid = np.array(IQ3S_GRID, dtype=np.int64)          # (512,) uint32
+    mask_lo = np.array(KMASK_IQ2XS[:4], dtype=np.int32)  # j = 0..3
+    mask_hi = np.array(KMASK_IQ2XS[4:], dtype=np.int32)  # j = 4..7
+
+    out = np.empty((nb, QK_K), dtype=np.float32)
+    for k in range(QK_K // 64):                # ib32 = 0,2,4,6
+        db1 = d * (1 + 2 * (scales[:, k] & 0xF))
+        db2 = d * (1 + 2 * (scales[:, k] >> 4))
+        for half in (0, 1):
+            db = db1 if half == 0 else db2
+            h = qh[:, 2 * k + half]
+            q0 = qs[:, k * 16 + half * 8: k * 16 + half * 8 + 8]
+            s0 = signs[:, k * 8 + half * 4: k * 8 + half * 4 + 4]
+            for l in range(4):
+                i1 = q0[:, 2 * l] | ((h << (8 - 2 * l)) & 256)
+                i2 = q0[:, 2 * l + 1] | ((h << (7 - 2 * l)) & 256)
+                w1 = np.right_shift(grid[i1, None], 8 * np.arange(4)) & 0xFF
+                w2 = np.right_shift(grid[i2, None], 8 * np.arange(4)) & 0xFF
+                sgn = s0[:, l][:, None]
+                col = k * 64 + half * 32 + l * 8
+                out[:, col:col + 4] = db[:, None] * np.where(
+                    (sgn & mask_lo) != 0, -1.0, 1.0) * w1
+                out[:, col + 4:col + 8] = db[:, None] * np.where(
+                    (sgn & mask_hi) != 0, -1.0, 1.0) * w2
+    return out.reshape(-1)
+
+
+def dequant_mxfp4(raw, n):
+    """block_mxfp4 = { uint8 e (E8M0); uint8 qs[16]; } = 17 B / 32 elements。
+
+    逐字對應 ggml dequantize_row_mxfp4。注意 qs[j] 的低/高 nibble 分別對應
+    block 的前 16 個與後 16 個元素（不是交錯），而且 E8M0 的 scale 已經是
+    「E2M1 值 ×2」（kvalues_fp4 是 doubled 的），所以這裡不要再乘 0.5。
+    """
+    nb = n // QK_MXFP4
+    u = np.frombuffer(raw, dtype=np.uint8, count=nb * 17).reshape(nb, 17)
+    d = e8m0_to_fp32_half_vec(u[:, 0])[:, None]
+    qs = u[:, 1:17].astype(np.int32)
+    kv = np.array(KVALUES_MXFP4, dtype=np.float32)
+    out = np.empty((nb, QK_MXFP4), dtype=np.float32)
+    out[:, 0:16] = kv[qs & 0xF] * d
+    out[:, 16:32] = kv[qs >> 4] * d
+    return out.reshape(-1)
+
+
+def dequant_q8_0(raw, n):
+    nb = n // 32
+    u = np.frombuffer(raw, dtype=np.uint8, count=nb * 34).reshape(nb, 34)
+    d = u[:, 0:2].copy().view(np.float16).reshape(nb).astype(np.float32)[:, None]
+    return (u[:, 2:34].view(np.int8).astype(np.float32) * d).reshape(-1)
+
+
+def dequant(raw, n, tt):
+    if tt == 21:
+        return dequant_iq3_s(raw, n)
+    if tt == 39:
+        return dequant_mxfp4(raw, n)
+    if tt == 8:
+        return dequant_q8_0(raw, n)
+    raise ValueError('unsupported type %s (%d)' % (TYNAME.get(tt, '?'), tt))
+
+
+def row_bytes(n, tt):
+    bs, ts = BLK[tt]
+    assert n % bs == 0, (n, tt)
+    return n // bs * ts
+
+
+# ------------------------------------------------------------------ expert I/O
+def read_expert(tensors, il, ie):
+    """回傳 (gate, up, down) 三段；每段是 (raw, n_elem, type, n_elem_per_row, n_rows)。"""
+    def seg(name):
+        si, off, dims, tt = tensors['blk.%d.%s' % (il, name)]
+        ne0, ne1 = int(dims[0]), int(dims[1])       # GGUF dims = [ne0, ne1, n_expert]
+        nrow = row_bytes(ne0, tt)
+        n = nrow * ne1
+        with open(SHARDS[si], 'rb') as f:
+            f.seek(off + ie * n)
+            raw = f.read(n)
+        assert len(raw) == n, (len(raw), n)
+        return raw, ne0 * ne1, tt, ne0, ne1
+    return (seg('ffn_gate_exps.weight'), seg('ffn_up_exps.weight'),
+            seg('ffn_down_exps.weight'))
+
+
+def swiglu_clamp(g, u, limit):
+    """ggml_swiglu_clamp：gate 只夾上界、up 對稱夾，而且夾在 silu 之前。"""
+    if limit <= 1e-6:
+        return (g / (1.0 + np.exp(-g))) * u
+    gc = np.minimum(g, limit)
+    uc = np.clip(u, -limit, limit)
+    return (gc / (1.0 + np.exp(-gc))) * uc
+
+
+def swiglu_legacy(g, u, limit):
+    """SDQ 原版（qwen4exp 那條分支）：對稱夾 silu 之後的 gate。"""
+    if limit <= 1e-6:
+        return (g / (1.0 + np.exp(-g))) * u
+    gc = np.clip(g / (1.0 + np.exp(-g)), -limit, limit)
+    return gc * np.clip(u, -limit, limit)
+
+
+# ------------------------------------------------------------------ main
+def main():
+    limit = float(os.environ.get('DSV4_LIMIT', '0'))
+    mode = int(os.environ.get('DSV4_MODE', '1'))
+    st_dir = os.environ.get('DSV4_ST_DIR', '/tmp/opencode')
+    st_pfx = os.environ.get('DSV4_ST_PREFIX', 'st_')
+    rel_tol = float(os.environ.get('DSV4_REL_TOL', '0.05'))
+    corr_min = float(os.environ.get('DSV4_CORR_MIN', '0.99'))
+
+    kv, tensors = parse_headers(SHARDS)
+    arch = kv['general.architecture']
+    assert arch == 'deepseek4', arch
+    n_embd = int(kv[arch + '.embedding_length'])
+    n_ff = int(kv[arch + '.expert_feed_forward_length'])
+    n_expert = int(kv[arch + '.expert_count'])
+    n_used = int(kv[arch + '.expert_used_count'])
+
+    print('model  = %s' % os.path.basename(MODEL))
+    print('arch   = %s  n_layer=%d  n_expert=%d  n_used=%d  n_embd=%d  n_ff=%d'
+          % (arch, int(kv[arch + '.block_count']), n_expert, n_used, n_embd, n_ff))
+    print('swiglu = limit=%g mode=%d (%s)'
+          % (limit, mode, 'ggml_swiglu_clamp' if mode == 1 else 'SDQ legacy'))
+    print()
+
+    cases = []
+    for il in (0, 1, 2, 3, 12, 25, 26, 27, 41, 42):
+        for ie in (0, 7, 123, 255):
+            path = os.path.join(st_dir, '%sl%de%d.bin' % (st_pfx, il, ie))
+            if os.path.exists(path):
+                cases.append((il, ie, path))
+                break
+
+    if not cases:
+        print('找不到 selftest 輸出（%s/st_l*e*.bin）；先跑 sdq-chat --selftest' % st_dir)
+        return 1
+
+    act = swiglu_clamp if mode == 1 else swiglu_legacy
+    all_ok = True
+    n_pass = 0
+    for il, ie, path in cases:
+        raw = open(path, 'rb').read()
+        n_tok = len(raw) // 4 // (2 * n_embd)
+        got = np.frombuffer(raw[:n_tok * n_embd * 4], dtype=np.float32).reshape(n_tok, n_embd)
+        x = np.frombuffer(raw[n_tok * n_embd * 4:], dtype=np.float32).reshape(n_tok, n_embd)
+
+        (gr, gn, g_t, g_ne0, g_ne1), (ur, un, u_t, _, _), (dr, dn, d_t, d_ne0, d_ne1) = \
+            read_expert(tensors, il, ie)
+        Wg = dequant(gr, gn, g_t).reshape(g_ne1, g_ne0)
+        Wu = dequant(ur, un, u_t).reshape(g_ne1, g_ne0)
+        Wd = dequant(dr, dn, d_t).reshape(d_ne1, d_ne0)
+        del gr, ur, dr
+
+        rels, corrs = [], []
+        for t in range(n_tok):
+            xt = x[t]
+            h = act(Wg @ xt, Wu @ xt, limit)
+            ref = Wd @ h
+            gt = got[t]
+            denom = max(float(np.abs(ref).max()), 1e-12)
+            rels.append(float(np.abs(gt - ref).max()) / denom)
+            corrs.append(float(np.corrcoef(gt, ref)[0, 1]))
+
+        rel = max(rels)
+        corr = min(corrs)
+        ok = rel < rel_tol and corr > corr_min
+        all_ok &= ok
+        n_pass += int(ok)
+        print('L%-2d E%-3d gate=%-6s up=%-6s down=%-6s | max_rel_err=%7.4f corr=%.6f | %s'
+              % (il, ie, TYNAME[g_t], TYNAME[u_t], TYNAME[d_t], rel, corr,
+                 'PASS' if ok else 'FAIL'))
+        del Wg, Wu, Wd
+
+    print()
+    print('%d/%d PASS' % (n_pass, len(cases)))
+    print('ALL PASS' if all_ok else 'SOME FAILED')
+    return 0 if all_ok else 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())