Add files using upload-large-folder tool

.gitattributes

@@ -1,35 +1 @@
-*.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
+*.gguf filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,7 @@
+.venv/
+sources/
+upstream-metadata/
+*.partial-*
+.*.repeat-check
+__pycache__/
+*.pyc

.python-version

@@ -0,0 +1 @@
+3.14.6

DeepSeek-V4-Flash-0731-DSpark-Drafter-MXFP4-Q8_0.gguf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5c8a1ce75e4797c170e22ac65080281a1b694c77f2e4fa7a703fbf09c5de0e33
+size 10897110272

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

LICENSE.code

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alessandro Bologna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,138 @@
+---
+license: mit
+library_name: gguf
+base_model: deepseek-ai/DeepSeek-V4-Flash-0731
+base_model_relation: quantized
+tags:
+  - gguf
+  - deepseek-v4
+  - dspark
+  - speculative-decoding
+  - draft-model
+  - auxiliary-model
+---
+
+# DeepSeek V4 Flash 0731 DSpark Drafter GGUF
+
+This repository contains only the **DSpark auxiliary drafter** extracted from
+DeepSeek V4 Flash 0731. It is not a standalone language model and does not
+contain the target model weights.
+
+The GGUF is built from the official
+[`deepseek-ai/DeepSeek-V4-Flash-0731`](https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash-0731)
+checkpoint using the standalone Python scripts included here. The complete
+source manifest, build recipe, structural parser, numeric verifier, dependency
+pin, and build results are published alongside the artifact.
+
+## Artifact
+
+| File | Bytes | SHA-256 |
+|---|---:|---|
+| `DeepSeek-V4-Flash-0731-DSpark-Drafter-MXFP4-Q8_0.gguf` | 10,897,110,272 | `5c8a1ce75e4797c170e22ac65080281a1b694c77f2e4fa7a703fbf09c5de0e33` |
+
+The artifact uses GGUF v3 with the custom architecture
+`deepseek_v4_flash_dspark_draft` and contains 81 tensors:
+
+| Output type | Tensors | Transformation |
+|---|---:|---|
+| F32 | 45 | BF16 expanded exactly to F32, or source F32 bytes preserved |
+| F16 | 2 | BF16 Markov heads rounded to F16 |
+| Q8_0 | 25 | FP8 E4M3 weights with E8M0 block scales dequantized, then quantized to Q8_0 |
+| MXFP4 | 9 | Routed-expert FP4 nibbles and E8M0 scales repacked without requantization |
+
+The MXFP4 transformation is bit-preserving. Q8_0 and F16 transformations are
+lossy and are checked against explicit numeric error bounds. This repository
+does not claim that the complete conversion is lossless.
+
+## Pinned source
+
+- Repository: `deepseek-ai/DeepSeek-V4-Flash-0731`
+- Revision: `9e165c30e2704aec5d9d593cce3eebd58bbef1cb`
+- Input: only safetensors shards 46, 47, and 48
+- Total source size: 10,863,342,388 bytes
+
+Exact file sizes and SHA-256 values are in
+[`manifest/source.json`](manifest/source.json). The downloader and converter
+refuse any source that does not match them.
+
+## Reproduce
+
+The reference build used Linux aarch64, Python 3.14.6, NumPy 2.5.1, uv 0.11.29,
+and Hugging Face CLI 1.24.0. The NumPy wheel is pinned by hash in
+`requirements-linux-aarch64-py314.lock`. The upstream checkpoint is public, so
+a Hugging Face token is not required for source download.
+
+```bash
+uv venv --python 3.14.6 .venv
+uv pip install --python .venv/bin/python \
+  --require-hashes --only-binary=:all: \
+  -r requirements-linux-aarch64-py314.lock
+
+.venv/bin/python scripts/download_sources.py --destination sources
+.venv/bin/python -m unittest discover -s tests -v
+.venv/bin/python scripts/reproduce.py \
+  --sources sources \
+  --recipe mxfp4-q8_0 \
+  --manifest-dir manifest \
+  --repeat-check
+sha256sum -c SHA256SUMS
+```
+
+`--repeat-check` performs a second clean conversion and requires its complete
+GGUF SHA-256 to match the verified first build byte for byte. The converter
+memory-maps the source shards and processes FP8 tensors in bounded bands. It
+does not require PyTorch, CUDA, safetensors, a GGUF package, or a GPU.
+
+## Verification
+
+The included verifier checks pinned source hashes and tensor inventories, GGUF
+structure and metadata, exact F32/F16 bytes, exact MXFP4 repacking, and Q8_0
+encoding plus reconstruction error against a fresh FP8 source decode.
+
+Reference-build results:
+
+| Check | Result |
+|---|---:|
+| Tensor count | 81 |
+| Exact F32/F16 tensors | 47 |
+| Exact MXFP4 tensors | 9 |
+| Maximum Q8_0 block-relative error | 0.00396728515625 |
+| Q8_0 limit | 0.01 |
+| Repeat build | byte-identical |
+
+Machine-readable observations are in
+[`manifest/validation.json`](manifest/validation.json) and
+[`manifest/build.json`](manifest/build.json).
+
+## Compatibility and limitations
+
+- This is an auxiliary drafter, not a complete checkpoint.
+- A consumer must explicitly support the
+  `deepseek_v4_flash_dspark_draft` GGUF architecture and `dspark.*` tensor
+  namespace defined by the checked-in recipe.
+- Generic GGUF support alone is insufficient. No compatibility with llama.cpp,
+  Ollama, LM Studio, vLLM, or other runtimes is implied.
+- The drafter must be paired with a compatible DeepSeek V4 Flash 0731 target
+  model. No universal quality, acceptance-rate, or speed claim is made across
+  target quantizations or runtimes.
+- This is a community conversion, not an official DeepSeek release or
+  endorsement.
+
+## DSpark configuration
+
+The pinned source configuration defines block size 5, target layers 40, 41,
+and 42, Markov rank 256, hidden size 4096, and vocabulary size 129,280. These
+values are embedded in the GGUF metadata and validated during the build.
+
+## License and references
+
+The source-derived weights remain under DeepSeek's MIT terms in
+[`LICENSE`](LICENSE). The newly authored conversion and verification scripts
+are under [`LICENSE.code`](LICENSE.code). The pinned checkpoint's
+[upstream license](https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash-0731/blob/9e165c30e2704aec5d9d593cce3eebd58bbef1cb/LICENSE)
+and the DS4/GGML attribution in
+[`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) provide the applicable notices.
+
+- [Official DeepSeek V4 Flash 0731 checkpoint](https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash-0731)
+- [DeepSeek V4 technical report](https://arxiv.org/abs/2606.19348)
+- [DeepSpec](https://github.com/deepseek-ai/DeepSpec)

SHA256SUMS

@@ -0,0 +1 @@
+5c8a1ce75e4797c170e22ac65080281a1b694c77f2e4fa7a703fbf09c5de0e33  DeepSeek-V4-Flash-0731-DSpark-Drafter-MXFP4-Q8_0.gguf

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,52 @@
+# Third-party notices
+
+This repository contains a transformed subset of the weights published in
+[`deepseek-ai/DeepSeek-V4-Flash-0731`](https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash-0731)
+at commit `9e165c30e2704aec5d9d593cce3eebd58bbef1cb`.
+
+DeepSeek publishes that repository under the MIT License. Its copyright and
+permission notice are available in the pinned checkpoint's
+[upstream license](https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash-0731/blob/9e165c30e2704aec5d9d593cce3eebd58bbef1cb/LICENSE).
+
+The standalone conversion and verification scripts are newly authored for
+this repository and published under the repository's declared MIT license.
+
+The conversion scripts implement publicly documented numeric and file formats.
+The Q2_K encoder in `scripts/convert.py` is a Python port of the unweighted
+`ds4q_write_q2_k_block_ref` path and its numeric helpers from
+[`antirez/ds4` at commit `453a5faa899759d0edf7729d595c4c39cddfcfca`](https://github.com/antirez/ds4/blob/453a5faa899759d0edf7729d595c4c39cddfcfca/gguf-tools/quants.c).
+That source identifies its block layout and search procedure as derived from
+the MIT-licensed GGML/llama.cpp quantizers.
+
+The applicable DS4/GGML MIT notice is:
+
+> Copyright (c) 2026 The ds4.c authors  
+> Copyright (c) 2023-2026 The ggml authors
+>
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in
+> all copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+> SOFTWARE.
+
+No PyTorch, llama.cpp, or GGUF Python package is required at build time.
+
+Format references:
+
+- [DeepSeek-V3 FP8 block scaling implementation](https://github.com/deepseek-ai/DeepSeek-V3/blob/main/inference/kernel.py)
+- [OCP Microscaling Formats specification](https://www.opencompute.org/documents/ocp-microscaling-formats-mx-v1-0-spec-final-pdf)
+- [GGUF format documentation](https://github.com/ggml-org/ggml/blob/master/docs/gguf.md)
+- [DS4 reference quantizer](https://github.com/antirez/ds4/blob/453a5faa899759d0edf7729d595c4c39cddfcfca/gguf-tools/quants.c)
+- [DeepSpec](https://github.com/deepseek-ai/DeepSpec)

manifest/build.json

@@ -0,0 +1,38 @@
+{
+  "artifact": {
+    "filename": "DeepSeek-V4-Flash-0731-DSpark-Drafter-MXFP4-Q8_0.gguf",
+    "sha256": "5c8a1ce75e4797c170e22ac65080281a1b694c77f2e4fa7a703fbf09c5de0e33",
+    "size": 10897110272
+  },
+  "build_inputs": {
+    "manifest/source.json": "bd7744f0efffd71d45e6233bfd8008e02acf422e01d701f82277d8821938b9c5",
+    "requirements-linux-aarch64-py314.lock": "f66db1728c9a0702b511a12bfe8cffbfab0fba4fbbf56f10d0e1d96ee70ee66d",
+    "scripts/convert.py": "319dc5083a5dc1b0a3cbce16702ae2378594b415ecf3f4198b2b84662fe31c43",
+    "scripts/download_sources.py": "2c39fff99a0c91b3ad099a5d685c394563e7b7a963b0a88cd1f668ee6bee51d1",
+    "scripts/formats.py": "4963ff62387bdbdbf0276b9db98e53da04ae621cb2cad231330cfff9f1533149",
+    "scripts/recipe.py": "661bf7b14ee5f2fc46770b5494cf6641407b5268c83ef5de6fc2d3e77e25b937",
+    "scripts/reproduce.py": "05956fbff7c6e32c9eeab6a959fc3d4dcd29d04a097296ea66cd000c64bfaa45",
+    "scripts/verify.py": "9073c95f157bee37c0fdea5d26b029b9495ef63f1c46e1d2022afdceb5cc9cc0"
+  },
+  "environment": {
+    "machine": "aarch64",
+    "numpy": "2.5.1",
+    "platform": "Linux-6.17.0-1026-nvidia-aarch64-with-glibc2.39",
+    "python": "3.14.6"
+  },
+  "format": {
+    "architecture": "deepseek_v4_flash_dspark_draft",
+    "gguf_version": 3,
+    "recipe": "mxfp4-q8_0",
+    "recipe_version": 1
+  },
+  "repeat_build": {
+    "performed": true,
+    "sha256": "5c8a1ce75e4797c170e22ac65080281a1b694c77f2e4fa7a703fbf09c5de0e33",
+    "status": "byte-identical"
+  },
+  "source": {
+    "repository": "deepseek-ai/DeepSeek-V4-Flash-0731",
+    "revision": "9e165c30e2704aec5d9d593cce3eebd58bbef1cb"
+  }
+}

manifest/source.json

@@ -0,0 +1,19 @@
+{
+  "files": {
+    "model-00046-of-00048.safetensors": {
+      "sha256": "5db924ca907e0d93acd975bd5079c3662717f9ac709f23d079bd8f816d29d9dd",
+      "size": 3610455184
+    },
+    "model-00047-of-00048.safetensors": {
+      "sha256": "62816173f9f6e136b20b48e3b6f16613ac9ea02b5603f636928b253244a548bd",
+      "size": 3560111960
+    },
+    "model-00048-of-00048.safetensors": {
+      "sha256": "cc43742bd24ae6bcdea343a91442f6f66aed2cfebcc6b235470204851ce2f8a9",
+      "size": 3692775244
+    }
+  },
+  "repository": "deepseek-ai/DeepSeek-V4-Flash-0731",
+  "revision": "9e165c30e2704aec5d9d593cce3eebd58bbef1cb",
+  "total_size": 10863342388
+}

manifest/validation.json

@@ -0,0 +1,46 @@
+{
+  "artifact": {
+    "filename": "DeepSeek-V4-Flash-0731-DSpark-Drafter-MXFP4-Q8_0.gguf",
+    "sha256": "5c8a1ce75e4797c170e22ac65080281a1b694c77f2e4fa7a703fbf09c5de0e33",
+    "size": 10897110272
+  },
+  "gguf": {
+    "alignment": 32,
+    "data_start": 5824,
+    "tensor_count": 81,
+    "types": {
+      "F16": 2,
+      "F32": 45,
+      "MXFP4": 9,
+      "Q8_0": 25
+    },
+    "version": 3
+  },
+  "recipe": "mxfp4-q8_0",
+  "source": {
+    "files": {
+      "model-00046-of-00048.safetensors": {
+        "sha256": "5db924ca907e0d93acd975bd5079c3662717f9ac709f23d079bd8f816d29d9dd",
+        "size": 3610455184
+      },
+      "model-00047-of-00048.safetensors": {
+        "sha256": "62816173f9f6e136b20b48e3b6f16613ac9ea02b5603f636928b253244a548bd",
+        "size": 3560111960
+      },
+      "model-00048-of-00048.safetensors": {
+        "sha256": "cc43742bd24ae6bcdea343a91442f6f66aed2cfebcc6b235470204851ce2f8a9",
+        "size": 3692775244
+      }
+    },
+    "repository": "deepseek-ai/DeepSeek-V4-Flash-0731",
+    "revision": "9e165c30e2704aec5d9d593cce3eebd58bbef1cb"
+  },
+  "validation": {
+    "f16_exact_tensors": 2,
+    "f32_exact_tensors": 45,
+    "mxfp4_exact_tensors": 9,
+    "q8_0_limit": 0.01,
+    "q8_0_max_block_relative_error": 0.00396728515625,
+    "status": "pass"
+  }
+}

requirements-linux-aarch64-py314.lock

@@ -0,0 +1,4 @@
+# CPython 3.14 / Linux aarch64 reference-build dependency.
+# Wheel: numpy-2.5.1-cp314-cp314-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl
+numpy==2.5.1 \
+    --hash=sha256:caf3e317d33d60c37986b452613f4ab51246d0691350c03d0cb4a898627f4a95

scripts/convert.py

@@ -0,0 +1,653 @@
+#!/usr/bin/env python3
+"""Deterministically convert the pinned DSpark tensors into one GGUF v3 file."""
+
+from __future__ import annotations
+
+import argparse
+import math
+import os
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from typing import BinaryIO
+
+import numpy as np
+
+from formats import SafeTensorSet, sha256_path, verify_source_files, write_gguf
+from recipe import (
+    DEFAULT_RECIPE,
+    KIND_FP8_TO_Q8_0,
+    KIND_FUSED_EXPERTS_MXFP4,
+    KIND_FUSED_EXPERTS_Q2_K,
+    KIND_MARKOV_F16,
+    KIND_PLAIN_F32,
+    KIND_RELABEL_F32,
+    N_EXPERTS,
+    RECIPES,
+    ArtifactRecipe,
+    TensorRecipe,
+    build_plan,
+    resolve_recipe,
+    source_paths,
+)
+
+
+def _e4m3_value(byte: int) -> np.float32:
+    sign = -1.0 if byte & 0x80 else 1.0
+    exponent = (byte >> 3) & 0x0F
+    mantissa = byte & 0x07
+    if exponent == 0x0F and mantissa == 0x07:
+        return np.float32(np.nan)
+    if exponent == 0:
+        return np.float32(sign * (mantissa / 8.0) * math.ldexp(1.0, 1 - 7))
+    return np.float32(sign * (1.0 + mantissa / 8.0) * math.ldexp(1.0, exponent - 7))
+
+
+E4M3_TABLE = np.array([_e4m3_value(byte) for byte in range(256)], dtype=np.float32)
+E8M0_TABLE = np.array(
+    [
+        np.float32(np.nan) if byte == 0xFF else np.float32(math.ldexp(1.0, byte - 127))
+        for byte in range(256)
+    ],
+    dtype=np.float32,
+)
+FP4_TABLE = np.array(
+    [
+        0.0,
+        0.5,
+        1.0,
+        1.5,
+        2.0,
+        3.0,
+        4.0,
+        6.0,
+        0.0,
+        -0.5,
+        -1.0,
+        -1.5,
+        -2.0,
+        -3.0,
+        -4.0,
+        -6.0,
+    ],
+    dtype=np.float32,
+)
+
+Q2_K_BLOCK_SIZE = 256
+Q2_K_BLOCK_BYTES = 84
+# Both routed shapes contain at most 4,096 rows. Each task keeps one decoded
+# expert resident at a time; the bounded worker count limits the larger set of
+# NumPy fitting temporaries while avoiding tiny-band dispatch overhead across
+# the 2,304 experts in the full artifact.
+EXPERT_ROW_BATCH = 4096
+Q2_K_EXPERT_WORKERS = max(1, min(8, os.cpu_count() or 1))
+
+
+def bf16_bits_to_f32(bits: np.ndarray) -> np.ndarray:
+    """Convert little-endian BF16 payloads exactly by placing them in F32 high bits."""
+
+    wide = np.asarray(bits, dtype="<u2").astype("<u4")
+    wide <<= np.uint32(16)
+    return wide.view("<f4")
+
+
+def round_away_from_zero(values: np.ndarray) -> np.ndarray:
+    values = np.asarray(values, dtype=np.float32)
+    truncated = np.trunc(values).astype(np.float32, copy=False)
+    fraction = np.abs(values - truncated)
+    return np.where(
+        fraction >= np.float32(0.5),
+        truncated + np.copysign(np.float32(1.0), values),
+        truncated,
+    ).astype(np.float32, copy=False)
+
+
+def nearest_int_f32(values: np.ndarray) -> np.ndarray:
+    """Port ds4q_nearest_int's binary32 round-to-nearest-even bit trick."""
+
+    f32 = np.asarray(values, dtype=np.float32)
+    if not np.isfinite(f32).all() or np.any(np.abs(f32) > np.float32(4_194_303.0)):
+        raise ValueError("nearest-int input is outside the DS4 reference range")
+    shifted = np.add(f32, np.float32(12_582_912.0), dtype=np.float32)
+    bits = shifted.view(np.int32)
+    return ((bits & np.int32(0x007F_FFFF)) - np.int32(0x0040_0000)).astype(
+        np.int32, copy=False
+    )
+
+
+def _make_qkx2_quants(
+    groups: np.ndarray,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Vectorized binary32 port of DS4's unweighted 16-value Q2_K fit."""
+
+    x = np.asarray(groups, dtype=np.float32)
+    if x.ndim != 2 or x.shape[1] != 16:
+        raise ValueError("Q2_K fitting groups must have shape (n, 16)")
+    weights = np.abs(x).astype(np.float32, copy=False)
+    minimum = x[:, 0].copy()
+    maximum = x[:, 0].copy()
+    for index in range(1, 16):
+        minimum = np.minimum(minimum, x[:, index])
+        maximum = np.maximum(maximum, x[:, index])
+    minimum = np.where(minimum > 0, np.float32(0.0), minimum).astype(
+        np.float32, copy=False
+    )
+    constant = maximum == minimum
+    value_range = np.subtract(maximum, minimum, dtype=np.float32)
+    safe_range = np.where(constant, np.float32(1.0), value_range).astype(
+        np.float32, copy=False
+    )
+    inverse_scale = np.divide(np.float32(3.0), safe_range, dtype=np.float32)
+    scale = np.divide(np.float32(1.0), inverse_scale, dtype=np.float32)
+    normalized = np.multiply(
+        np.subtract(x, minimum[:, None], dtype=np.float32),
+        inverse_scale[:, None],
+        dtype=np.float32,
+    )
+    labels = np.clip(nearest_int_f32(normalized), 0, 3).astype(np.uint8)
+    scale[constant] = np.float32(0.0)
+    labels[constant] = np.uint8(0)
+
+    sum_w = weights[:, 0].copy()
+    sum_x = np.multiply(weights[:, 0], x[:, 0], dtype=np.float32)
+    for index in range(1, 16):
+        sum_w = np.add(sum_w, weights[:, index], dtype=np.float32)
+        sum_x = np.add(
+            sum_x,
+            np.multiply(weights[:, index], x[:, index], dtype=np.float32),
+            dtype=np.float32,
+        )
+
+    best_error = np.zeros(x.shape[0], dtype=np.float32)
+    for index in range(16):
+        reconstructed = np.add(
+            np.multiply(scale, labels[:, index], dtype=np.float32),
+            minimum,
+            dtype=np.float32,
+        )
+        difference = np.abs(
+            np.subtract(reconstructed, x[:, index], dtype=np.float32)
+        ).astype(np.float32, copy=False)
+        best_error = np.add(
+            best_error,
+            np.multiply(weights[:, index], difference, dtype=np.float32),
+            dtype=np.float32,
+        )
+
+    for step in range(16):
+        candidate_numerator = np.add(
+            np.add(
+                np.float32(-0.5),
+                np.multiply(np.float32(0.1), np.float32(step), dtype=np.float32),
+                dtype=np.float32,
+            ),
+            np.float32(3.0),
+            dtype=np.float32,
+        )
+        candidate_range = np.subtract(maximum, minimum, dtype=np.float32)
+        safe_candidate_range = np.where(
+            constant, np.float32(1.0), candidate_range
+        ).astype(np.float32, copy=False)
+        candidate_inverse = np.divide(
+            candidate_numerator, safe_candidate_range, dtype=np.float32
+        )
+        candidate_labels = np.clip(
+            nearest_int_f32(
+                np.multiply(
+                    np.subtract(x, minimum[:, None], dtype=np.float32),
+                    candidate_inverse[:, None],
+                    dtype=np.float32,
+                )
+            ),
+            0,
+            3,
+        ).astype(np.uint8)
+
+        sum_l = np.zeros(x.shape[0], dtype=np.float32)
+        sum_l2 = np.zeros(x.shape[0], dtype=np.float32)
+        sum_xl = np.zeros(x.shape[0], dtype=np.float32)
+        for index in range(16):
+            weighted_label = np.multiply(
+                weights[:, index], candidate_labels[:, index], dtype=np.float32
+            )
+            sum_l = np.add(sum_l, weighted_label, dtype=np.float32)
+            sum_l2 = np.add(
+                sum_l2,
+                np.multiply(
+                    weighted_label, candidate_labels[:, index], dtype=np.float32
+                ),
+                dtype=np.float32,
+            )
+            sum_xl = np.add(
+                sum_xl,
+                np.multiply(weighted_label, x[:, index], dtype=np.float32),
+                dtype=np.float32,
+            )
+
+        determinant = np.subtract(
+            np.multiply(sum_w, sum_l2, dtype=np.float32),
+            np.multiply(sum_l, sum_l, dtype=np.float32),
+            dtype=np.float32,
+        )
+        valid = np.logical_and(~constant, determinant > 0)
+        safe_determinant = np.where(valid, determinant, np.float32(1.0)).astype(
+            np.float32, copy=False
+        )
+        candidate_scale = np.divide(
+            np.subtract(
+                np.multiply(sum_w, sum_xl, dtype=np.float32),
+                np.multiply(sum_x, sum_l, dtype=np.float32),
+                dtype=np.float32,
+            ),
+            safe_determinant,
+            dtype=np.float32,
+        )
+        candidate_minimum = np.divide(
+            np.subtract(
+                np.multiply(sum_l2, sum_x, dtype=np.float32),
+                np.multiply(sum_l, sum_xl, dtype=np.float32),
+                dtype=np.float32,
+            ),
+            safe_determinant,
+            dtype=np.float32,
+        )
+        positive_minimum = np.logical_and(valid, candidate_minimum > 0)
+        safe_sum_l2 = np.where(positive_minimum, sum_l2, np.float32(1.0)).astype(
+            np.float32, copy=False
+        )
+        zero_minimum_scale = np.divide(sum_xl, safe_sum_l2, dtype=np.float32)
+        candidate_scale = np.where(
+            positive_minimum, zero_minimum_scale, candidate_scale
+        ).astype(np.float32, copy=False)
+        candidate_minimum = np.where(
+            positive_minimum, np.float32(0.0), candidate_minimum
+        ).astype(np.float32, copy=False)
+
+        current_error = np.zeros(x.shape[0], dtype=np.float32)
+        for index in range(16):
+            reconstructed = np.add(
+                np.multiply(
+                    candidate_scale, candidate_labels[:, index], dtype=np.float32
+                ),
+                candidate_minimum,
+                dtype=np.float32,
+            )
+            difference = np.abs(
+                np.subtract(reconstructed, x[:, index], dtype=np.float32)
+            ).astype(np.float32, copy=False)
+            current_error = np.add(
+                current_error,
+                np.multiply(weights[:, index], difference, dtype=np.float32),
+                dtype=np.float32,
+            )
+        improved = np.logical_and(valid, current_error < best_error)
+        labels[improved] = candidate_labels[improved]
+        best_error[improved] = current_error[improved]
+        scale[improved] = candidate_scale[improved]
+        minimum[improved] = candidate_minimum[improved]
+
+    return scale, np.negative(minimum, dtype=np.float32), labels
+
+
+def quantize_q2_k(values: np.ndarray) -> np.ndarray:
+    """Encode rows as unweighted GGML Q2_K blocks using the DS4 reference path."""
+
+    rows = np.asarray(values, dtype=np.float32)
+    if rows.ndim != 2 or rows.shape[1] % Q2_K_BLOCK_SIZE:
+        raise ValueError("Q2_K input must be 2D with columns divisible by 256")
+    if not np.isfinite(rows).all():
+        raise ValueError("Q2_K input contains NaN or infinity")
+    blocks = rows.reshape(-1, Q2_K_BLOCK_SIZE)
+    groups = blocks.reshape(-1, 16)
+    scales, mins, labels = _make_qkx2_quants(groups)
+    scales = scales.reshape(-1, 16)
+    mins = mins.reshape(-1, 16)
+    labels = labels.reshape(-1, Q2_K_BLOCK_SIZE)
+
+    max_scale = np.maximum(np.max(scales, axis=1), np.float32(0.0)).astype(
+        np.float32, copy=False
+    )
+    max_min = np.maximum(np.max(mins, axis=1), np.float32(0.0)).astype(
+        np.float32, copy=False
+    )
+    scale_inverse = np.zeros_like(max_scale)
+    min_inverse = np.zeros_like(max_min)
+    np.divide(
+        np.float32(15.0),
+        max_scale,
+        out=scale_inverse,
+        where=max_scale > 0,
+    )
+    np.divide(np.float32(15.0), max_min, out=min_inverse, where=max_min > 0)
+    scale_codes = nearest_int_f32(
+        np.multiply(scales, scale_inverse[:, None], dtype=np.float32)
+    )
+    min_codes = nearest_int_f32(
+        np.multiply(mins, min_inverse[:, None], dtype=np.float32)
+    )
+    if np.any(scale_codes < 0) or np.any(scale_codes > 15):
+        raise ValueError("Q2_K scale code is outside four bits")
+    if np.any(min_codes < 0) or np.any(min_codes > 15):
+        raise ValueError("Q2_K minimum code is outside four bits")
+    packed_scales = scale_codes.astype(np.uint8) | (
+        min_codes.astype(np.uint8) << np.uint8(4)
+    )
+
+    d_bits = (
+        np.divide(max_scale, np.float32(15.0), dtype=np.float32)
+        .astype("<f2")
+        .view("<u2")
+    )
+    dmin_bits = (
+        np.divide(max_min, np.float32(15.0), dtype=np.float32).astype("<f2").view("<u2")
+    )
+    d = d_bits.view("<f2").astype(np.float32)
+    dmin = dmin_bits.view("<f2").astype(np.float32)
+    group_d = np.multiply(
+        d[:, None], packed_scales & np.uint8(0x0F), dtype=np.float32
+    ).reshape(-1)
+    group_min = np.multiply(
+        dmin[:, None], packed_scales >> np.uint8(4), dtype=np.float32
+    ).reshape(-1)
+    fitted_groups = labels.reshape(-1, 16)
+    nonzero = group_d != 0
+    normalized = np.divide(
+        np.add(groups[nonzero], group_min[nonzero, None], dtype=np.float32),
+        group_d[nonzero, None],
+        dtype=np.float32,
+    )
+    fitted_groups[nonzero] = np.clip(nearest_int_f32(normalized), 0, 3).astype(np.uint8)
+
+    encoded = np.zeros((blocks.shape[0], Q2_K_BLOCK_BYTES), dtype=np.uint8)
+    encoded[:, :16] = packed_scales
+    for start in (0, 128):
+        packed = (
+            labels[:, start : start + 32]
+            | (labels[:, start + 32 : start + 64] << np.uint8(2))
+            | (labels[:, start + 64 : start + 96] << np.uint8(4))
+            | (labels[:, start + 96 : start + 128] << np.uint8(6))
+        )
+        offset = 16 + start // 4
+        encoded[:, offset : offset + 32] = packed
+    encoded[:, 80:82] = d_bits.astype("<u2", copy=False).view(np.uint8).reshape(-1, 2)
+    encoded[:, 82:84] = (
+        dmin_bits.astype("<u2", copy=False).view(np.uint8).reshape(-1, 2)
+    )
+    return encoded
+
+
+def decode_source_mxfp4(
+    packed: np.ndarray,
+    scales: np.ndarray,
+    rows: int,
+    cols: int,
+) -> np.ndarray:
+    """Decode one bounded row band of the pinned OCP E2M1/E8M0 source."""
+
+    if cols % 32:
+        raise ValueError("source MXFP4 column count must be divisible by 32")
+    blocks = cols // 32
+    packed_blocks = np.asarray(packed, dtype=np.uint8).reshape(rows, blocks, 16)
+    scale_codes = np.asarray(scales, dtype=np.uint8).reshape(rows, blocks)
+    if np.any(scale_codes == 0xFF):
+        raise ValueError("source MXFP4 contains reserved E8M0 NaN scale 0xff")
+    codes = np.empty((rows, blocks, 32), dtype=np.uint8)
+    codes[..., 0::2] = packed_blocks & np.uint8(0x0F)
+    codes[..., 1::2] = packed_blocks >> np.uint8(4)
+    decoded = FP4_TABLE[codes]
+    decoded *= E8M0_TABLE[scale_codes][..., None]
+    return decoded.reshape(rows, cols)
+
+
+def quantize_q8_0(values: np.ndarray) -> np.ndarray:
+    """Encode flat F32 data as GGML Q8_0 using Rust/C-style half-away rounding."""
+
+    flat = np.asarray(values, dtype=np.float32).reshape(-1)
+    if flat.size % 32:
+        raise ValueError("Q8_0 input length must be divisible by 32")
+    blocks = flat.reshape(-1, 32)
+    if not np.isfinite(blocks).all():
+        raise ValueError("Q8_0 input contains NaN or infinity")
+    maxima = np.max(np.abs(blocks), axis=1).astype(np.float32, copy=False)
+    scales = maxima / np.float32(127.0)
+    inverse = np.zeros_like(scales)
+    np.divide(np.float32(1.0), scales, out=inverse, where=scales != 0)
+    quantized = round_away_from_zero(blocks * inverse[:, None])
+    if np.any(quantized < -127) or np.any(quantized > 127):
+        raise ValueError("Q8_0 quantization produced an out-of-range code")
+    codes = quantized.astype(np.int8)
+    encoded = np.empty((blocks.shape[0], 34), dtype=np.uint8)
+    encoded[:, :2] = scales.astype("<f2").view(np.uint8).reshape(-1, 2)
+    encoded[:, 2:] = codes.view(np.uint8)
+    return encoded
+
+
+def repack_mxfp4(
+    packed: np.ndarray,
+    scales: np.ndarray,
+    rows: int,
+    cols: int,
+) -> np.ndarray:
+    """Purely permute source FP4 nibbles into GGML's 17-byte MXFP4 blocks."""
+
+    if cols % 32:
+        raise ValueError("MXFP4 column count must be divisible by 32")
+    blocks = cols // 32
+    packed_blocks = np.asarray(packed, dtype=np.uint8).reshape(rows, blocks, 16)
+    scale_rows = np.asarray(scales, dtype=np.uint8).reshape(rows, blocks)
+    if np.any(scale_rows == 0xFF):
+        raise ValueError("MXFP4 source contains reserved E8M0 NaN scale 0xff")
+
+    low_codes = np.empty((rows, blocks, 16), dtype=np.uint8)
+    high_codes = np.empty((rows, blocks, 16), dtype=np.uint8)
+    low_bytes = packed_blocks[..., :8]
+    high_bytes = packed_blocks[..., 8:]
+    low_codes[..., 0::2] = low_bytes & np.uint8(0x0F)
+    low_codes[..., 1::2] = low_bytes >> np.uint8(4)
+    high_codes[..., 0::2] = high_bytes & np.uint8(0x0F)
+    high_codes[..., 1::2] = high_bytes >> np.uint8(4)
+
+    encoded = np.empty((rows, blocks, 17), dtype=np.uint8)
+    encoded[..., 0] = scale_rows
+    encoded[..., 1:] = low_codes | (high_codes << np.uint8(4))
+    return encoded
+
+
+class TensorProducer:
+    def __init__(self, source: SafeTensorSet):
+        self.source = source
+
+    def __call__(self, tensor: TensorRecipe, handle: BinaryIO) -> int:
+        print(f"[convert] {tensor.out_name} ({tensor.byte_len:,} bytes)", flush=True)
+        if tensor.kind == KIND_PLAIN_F32:
+            return self._plain_f32(tensor, handle)
+        if tensor.kind == KIND_RELABEL_F32:
+            return self._copy_f32(tensor, handle)
+        if tensor.kind == KIND_FP8_TO_Q8_0:
+            return self._fp8_to_q8_0(tensor, handle)
+        if tensor.kind == KIND_FUSED_EXPERTS_MXFP4:
+            return self._fused_experts_mxfp4(tensor, handle)
+        if tensor.kind == KIND_FUSED_EXPERTS_Q2_K:
+            return self._fused_experts_q2_k(tensor, handle)
+        if tensor.kind == KIND_MARKOV_F16:
+            return self._markov_f16(tensor, handle)
+        raise ValueError(f"unsupported tensor recipe kind: {tensor.kind}")
+
+    def _plain_f32(self, tensor: TensorRecipe, handle: BinaryIO) -> int:
+        if not tensor.src_is_bf16:
+            raw = self.source.raw(tensor.src_name)
+            try:
+                return handle.write(raw)
+            finally:
+                raw.release()
+        bits = self.source.array(tensor.src_name, "<u2").reshape(-1)
+        data = bf16_bits_to_f32(bits).tobytes(order="C")
+        return handle.write(data)
+
+    def _copy_f32(self, tensor: TensorRecipe, handle: BinaryIO) -> int:
+        raw = self.source.raw(tensor.src_name)
+        try:
+            return handle.write(raw)
+        finally:
+            raw.release()
+
+    def _fp8_to_q8_0(self, tensor: TensorRecipe, handle: BinaryIO) -> int:
+        weights = self.source.array(tensor.weight_name, np.uint8).reshape(
+            tensor.rows, tensor.cols
+        )
+        scale_codes = self.source.array(tensor.scale_name, np.uint8).reshape(
+            (tensor.rows + 127) // 128,
+            (tensor.cols + 127) // 128,
+        )
+        written = 0
+        for block_row in range(scale_codes.shape[0]):
+            row_start = block_row * 128
+            row_end = min(row_start + 128, tensor.rows)
+            decoded = E4M3_TABLE[weights[row_start:row_end]]
+            column_scales = np.repeat(E8M0_TABLE[scale_codes[block_row]], 128)[
+                : tensor.cols
+            ]
+            if not np.isfinite(column_scales).all():
+                raise ValueError(f"{tensor.scale_name}: contains reserved E8M0 NaN")
+            decoded *= column_scales[None, :]
+            encoded = quantize_q8_0(decoded)
+            written += handle.write(encoded.tobytes(order="C"))
+        return written
+
+    def _fused_experts_mxfp4(self, tensor: TensorRecipe, handle: BinaryIO) -> int:
+        written = 0
+        for expert in range(N_EXPERTS):
+            prefix = f"{tensor.name_prefix}.ffn.experts.{expert}.{tensor.expert_kind}"
+            packed = self.source.array(f"{prefix}.weight", np.uint8)
+            scales = self.source.array(f"{prefix}.scale", np.uint8)
+            encoded = repack_mxfp4(
+                packed,
+                scales,
+                tensor.rows,
+                tensor.cols,
+            )
+            written += handle.write(encoded.tobytes(order="C"))
+        return written
+
+    def _fused_experts_q2_k(self, tensor: TensorRecipe, handle: BinaryIO) -> int:
+        written = 0
+        with ThreadPoolExecutor(max_workers=Q2_K_EXPERT_WORKERS) as executor:
+            for start in range(0, N_EXPERTS, Q2_K_EXPERT_WORKERS):
+                futures = [
+                    executor.submit(self._encode_q2_k_expert, tensor, expert)
+                    for expert in range(
+                        start, min(start + Q2_K_EXPERT_WORKERS, N_EXPERTS)
+                    )
+                ]
+                # Results are written in expert order, independent of worker
+                # completion order, so concurrency cannot change GGUF bytes.
+                for future in futures:
+                    written += handle.write(future.result())
+        return written
+
+    def _encode_q2_k_expert(self, tensor: TensorRecipe, expert: int) -> bytes:
+        prefix = f"{tensor.name_prefix}.ffn.experts.{expert}.{tensor.expert_kind}"
+        packed = self.source.array(f"{prefix}.weight", np.uint8).reshape(
+            tensor.rows, tensor.cols // 2
+        )
+        scales = self.source.array(f"{prefix}.scale", np.uint8).reshape(
+            tensor.rows, tensor.cols // 32
+        )
+        chunks: list[bytes] = []
+        for row_start in range(0, tensor.rows, EXPERT_ROW_BATCH):
+            row_end = min(row_start + EXPERT_ROW_BATCH, tensor.rows)
+            decoded = decode_source_mxfp4(
+                packed[row_start:row_end],
+                scales[row_start:row_end],
+                row_end - row_start,
+                tensor.cols,
+            )
+            chunks.append(quantize_q2_k(decoded).tobytes(order="C"))
+        return b"".join(chunks)
+
+    def _markov_f16(self, tensor: TensorRecipe, handle: BinaryIO) -> int:
+        bits = self.source.array(tensor.src_name, "<u2").reshape(-1)
+        chunk_elements = 8 * 1024 * 1024
+        written = 0
+        for start in range(0, bits.size, chunk_elements):
+            f32 = bf16_bits_to_f32(bits[start : start + chunk_elements])
+            f16 = f32.astype("<f2")
+            written += handle.write(f16.tobytes(order="C"))
+        return written
+
+
+def convert(
+    source_dir: Path,
+    output: Path,
+    *,
+    force: bool = False,
+    recipe: ArtifactRecipe | str | None = None,
+) -> tuple[int, str]:
+    artifact_recipe = resolve_recipe(recipe)
+    source_dir = source_dir.resolve()
+    output = output.resolve()
+    if output.exists() and not force:
+        raise FileExistsError(
+            f"output already exists: {output}; pass --force to replace it"
+        )
+    output.parent.mkdir(parents=True, exist_ok=True)
+    print("[convert] validating pinned source sizes and SHA-256 values", flush=True)
+    verify_source_files(source_dir)
+    plan = build_plan(artifact_recipe)
+    temporary = output.with_name(f".{output.name}.partial-{os.getpid()}")
+    if temporary.exists():
+        raise FileExistsError(f"temporary output already exists: {temporary}")
+    try:
+        with SafeTensorSet(source_paths(source_dir)) as source:
+            source.validate_plan(plan)
+            print(
+                f"[convert] source layout valid; writing {len(plan)} tensors",
+                flush=True,
+            )
+            write_gguf(temporary, plan, TensorProducer(source))
+        size = temporary.stat().st_size
+        digest = sha256_path(temporary)
+        os.replace(temporary, output)
+        directory_fd = os.open(output.parent, os.O_RDONLY | os.O_DIRECTORY)
+        try:
+            os.fsync(directory_fd)
+        finally:
+            os.close(directory_fd)
+    except Exception:
+        temporary.unlink(missing_ok=True)
+        raise
+    print(f"[convert] wrote {output} ({size:,} bytes)", flush=True)
+    print(f"[convert] SHA-256 {digest}", flush=True)
+    return size, digest
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--sources", type=Path, required=True, help="Pinned shard directory"
+    )
+    parser.add_argument(
+        "--recipe",
+        choices=sorted(RECIPES),
+        default=DEFAULT_RECIPE.name,
+        help=f"Artifact recipe (default: {DEFAULT_RECIPE.name})",
+    )
+    parser.add_argument(
+        "--output",
+        type=Path,
+        help="Output GGUF path (default: the selected recipe's canonical filename)",
+    )
+    parser.add_argument(
+        "--force", action="store_true", help="Replace an existing output"
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    recipe = resolve_recipe(args.recipe)
+    output = args.output if args.output is not None else Path(recipe.output_filename)
+    convert(args.sources, output, force=args.force, recipe=recipe)
+
+
+if __name__ == "__main__":
+    main()

scripts/download_sources.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""Download exactly the three pinned upstream DSpark shards and verify them."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import shutil
+import subprocess
+from pathlib import Path
+
+from recipe import SOURCE_FILES, SOURCE_REPOSITORY, SOURCE_REVISION
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        while chunk := handle.read(8 * 1024 * 1024):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def download(destination: Path, hf_executable: str) -> None:
+    destination.mkdir(parents=True, exist_ok=True)
+    command = [
+        hf_executable,
+        "download",
+        SOURCE_REPOSITORY,
+        "--revision",
+        SOURCE_REVISION,
+        "--local-dir",
+        str(destination),
+    ]
+    for name in SOURCE_FILES:
+        command.extend(["--include", name])
+    subprocess.run(command, check=True)
+    for name, expected in SOURCE_FILES.items():
+        path = destination / name
+        if not path.is_file():
+            raise FileNotFoundError(f"download did not produce {path}")
+        size = path.stat().st_size
+        digest = _sha256(path)
+        if size != expected["size"] or digest != expected["sha256"]:
+            raise ValueError(
+                f"{name}: expected {expected['size']} bytes/{expected['sha256']}, "
+                f"found {size}/{digest}"
+            )
+        print(f"[download] verified {name}: {size:,} bytes {digest}", flush=True)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--destination", type=Path, default=Path("sources"))
+    parser.add_argument(
+        "--hf",
+        default=shutil.which("hf"),
+        help="Path to the hf executable (the pinned public source needs no token)",
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    if not args.hf:
+        raise SystemExit("hf CLI not found on PATH; pass --hf /path/to/hf")
+    download(args.destination, args.hf)
+
+
+if __name__ == "__main__":
+    main()

scripts/formats.py

@@ -0,0 +1,456 @@
+#!/usr/bin/env python3
+"""Minimal safetensors and GGUF v3 I/O used by the reproducible build."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import mmap
+import os
+import struct
+from dataclasses import dataclass
+from pathlib import Path
+from typing import BinaryIO, Callable, Iterable
+
+import numpy as np
+
+from recipe import (
+    GGML_F16,
+    GGML_F32,
+    GGML_MXFP4,
+    GGML_Q2_K,
+    GGML_Q8_0,
+    GGUF_METADATA,
+    SOURCE_FILES,
+    TensorRecipe,
+    source_expectations,
+)
+
+
+ALIGNMENT = 32
+GGUF_VALUE_U32 = 4
+GGUF_VALUE_I32 = 5
+GGUF_VALUE_STRING = 8
+GGUF_VALUE_ARRAY = 9
+
+_DTYPE_BYTES = {
+    "F8_E4M3": 1,
+    "F8_E8M0": 1,
+    "I8": 1,
+    "BF16": 2,
+    "F16": 2,
+    "F32": 4,
+}
+
+
+def align_up(value: int, alignment: int = ALIGNMENT) -> int:
+    return (value + alignment - 1) // alignment * alignment
+
+
+def sha256_path(path: Path, chunk_size: int = 8 * 1024 * 1024) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        while chunk := handle.read(chunk_size):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def verify_source_files(source_dir: Path) -> dict[str, dict[str, int | str]]:
+    observed: dict[str, dict[str, int | str]] = {}
+    for name, expected in SOURCE_FILES.items():
+        path = source_dir / name
+        if not path.is_file():
+            raise FileNotFoundError(f"missing pinned source shard: {path}")
+        size = path.stat().st_size
+        if size != expected["size"]:
+            raise ValueError(f"{name}: expected {expected['size']} bytes, found {size}")
+        digest = sha256_path(path)
+        if digest != expected["sha256"]:
+            raise ValueError(
+                f"{name}: expected SHA-256 {expected['sha256']}, found {digest}"
+            )
+        observed[name] = {"size": size, "sha256": digest}
+    return observed
+
+
+@dataclass(frozen=True)
+class SafeTensorInfo:
+    dtype: str
+    shape: tuple[int, ...]
+    start: int
+    end: int
+    shard_index: int
+
+
+class SafeTensorSet:
+    """Read-only mmap index spanning the three pinned safetensors shards."""
+
+    def __init__(self, paths: Iterable[Path]):
+        self._files: list[BinaryIO] = []
+        self._maps: list[mmap.mmap] = []
+        self._index: dict[str, SafeTensorInfo] = {}
+        try:
+            for shard_index, path in enumerate(paths):
+                handle = path.open("rb")
+                mapping = mmap.mmap(handle.fileno(), 0, access=mmap.ACCESS_READ)
+                self._files.append(handle)
+                self._maps.append(mapping)
+                self._index_shard(path, shard_index, mapping)
+        except Exception:
+            self.close()
+            raise
+
+    def _index_shard(self, path: Path, shard_index: int, mapping: mmap.mmap) -> None:
+        if len(mapping) < 8:
+            raise ValueError(f"{path}: shorter than safetensors header length")
+        header_len = struct.unpack_from("<Q", mapping, 0)[0]
+        data_start = 8 + header_len
+        if data_start > len(mapping):
+            raise ValueError(f"{path}: safetensors header overruns file")
+        try:
+            header = json.loads(mapping[8:data_start])
+        except (UnicodeDecodeError, json.JSONDecodeError) as error:
+            raise ValueError(f"{path}: invalid safetensors header: {error}") from error
+        if not isinstance(header, dict):
+            raise ValueError(f"{path}: safetensors header is not an object")
+        for name, raw in header.items():
+            if name == "__metadata__" or not name.startswith("mtp."):
+                continue
+            if name in self._index:
+                raise ValueError(f"duplicate tensor across shards: {name}")
+            if not isinstance(raw, dict):
+                raise ValueError(f"{path}: tensor {name} metadata is not an object")
+            dtype = raw.get("dtype")
+            shape = raw.get("shape")
+            offsets = raw.get("data_offsets")
+            if (
+                not isinstance(dtype, str)
+                or not isinstance(shape, list)
+                or not all(isinstance(dim, int) and dim >= 0 for dim in shape)
+                or not isinstance(offsets, list)
+                or len(offsets) != 2
+                or not all(
+                    isinstance(offset, int) and offset >= 0 for offset in offsets
+                )
+            ):
+                raise ValueError(f"{path}: malformed metadata for tensor {name}")
+            relative_start, relative_end = offsets
+            start = data_start + relative_start
+            end = data_start + relative_end
+            if relative_start > relative_end or end > len(mapping):
+                raise ValueError(f"{path}: tensor {name} data range overruns shard")
+            if dtype in _DTYPE_BYTES:
+                count = 1
+                for dim in shape:
+                    count *= dim
+                expected_bytes = count * _DTYPE_BYTES[dtype]
+                if end - start != expected_bytes:
+                    raise ValueError(
+                        f"{path}: tensor {name} needs {expected_bytes} bytes, "
+                        f"data range contains {end - start}"
+                    )
+            self._index[name] = SafeTensorInfo(
+                dtype=dtype,
+                shape=tuple(shape),
+                start=start,
+                end=end,
+                shard_index=shard_index,
+            )
+
+    def close(self) -> None:
+        for mapping in reversed(getattr(self, "_maps", [])):
+            try:
+                mapping.close()
+            except BufferError:
+                pass
+        for handle in reversed(getattr(self, "_files", [])):
+            handle.close()
+        self._maps = []
+        self._files = []
+
+    def __enter__(self) -> "SafeTensorSet":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def info(self, name: str) -> SafeTensorInfo:
+        try:
+            return self._index[name]
+        except KeyError as error:
+            raise KeyError(f"source tensor not found: {name}") from error
+
+    def raw(self, name: str) -> memoryview:
+        info = self.info(name)
+        return memoryview(self._maps[info.shard_index])[info.start : info.end]
+
+    def array(self, name: str, dtype: np.dtype | str) -> np.ndarray:
+        info = self.info(name)
+        return np.frombuffer(
+            self._maps[info.shard_index],
+            dtype=dtype,
+            count=(info.end - info.start) // np.dtype(dtype).itemsize,
+            offset=info.start,
+        ).reshape(info.shape)
+
+    def validate_plan(self, plan: Iterable[TensorRecipe]) -> None:
+        expected_names: set[str] = set()
+        for tensor in plan:
+            for name, dtype, shape in source_expectations(tensor):
+                if name in expected_names:
+                    raise ValueError(
+                        f"recipe consumes source tensor more than once: {name}"
+                    )
+                expected_names.add(name)
+                info = self.info(name)
+                if info.dtype != dtype:
+                    raise ValueError(
+                        f"{name}: expected dtype {dtype}, found {info.dtype}"
+                    )
+                if info.shape != shape:
+                    raise ValueError(
+                        f"{name}: expected shape {shape}, found {info.shape}"
+                    )
+        observed_names = self.names()
+        if observed_names != expected_names:
+            missing = sorted(expected_names - observed_names)
+            unexpected = sorted(observed_names - expected_names)
+            raise ValueError(
+                "source tensor inventory differs from the recipe: "
+                f"missing={missing[:5]}, unexpected={unexpected[:5]}"
+            )
+
+    def names(self) -> frozenset[str]:
+        return frozenset(self._index)
+
+
+def _write_string(handle: BinaryIO, value: str) -> None:
+    encoded = value.encode("utf-8")
+    handle.write(struct.pack("<Q", len(encoded)))
+    handle.write(encoded)
+
+
+def write_gguf(
+    path: Path,
+    plan: tuple[TensorRecipe, ...],
+    produce: Callable[[TensorRecipe, BinaryIO], int],
+) -> None:
+    """Write deterministic GGUF v3 data, streaming each tensor in plan order."""
+
+    with path.open("wb", buffering=8 * 1024 * 1024) as handle:
+        handle.write(b"GGUF")
+        handle.write(struct.pack("<IQQ", 3, len(plan), len(GGUF_METADATA)))
+        for key, kind, value in GGUF_METADATA:
+            _write_string(handle, key)
+            if kind == "u32":
+                handle.write(struct.pack("<II", GGUF_VALUE_U32, int(value)))
+            elif kind == "string":
+                handle.write(struct.pack("<I", GGUF_VALUE_STRING))
+                _write_string(handle, str(value))
+            elif kind == "array_i32":
+                values = tuple(int(item) for item in value)
+                handle.write(
+                    struct.pack("<IIQ", GGUF_VALUE_ARRAY, GGUF_VALUE_I32, len(values))
+                )
+                for item in values:
+                    handle.write(struct.pack("<i", item))
+            else:
+                raise ValueError(f"unsupported GGUF metadata kind: {kind}")
+
+        relative_offset = 0
+        relative_offsets: list[int] = []
+        for tensor in plan:
+            relative_offsets.append(relative_offset)
+            relative_offset = align_up(relative_offset + tensor.byte_len)
+        for tensor, offset in zip(plan, relative_offsets, strict=True):
+            _write_string(handle, tensor.out_name)
+            handle.write(struct.pack("<I", len(tensor.dims)))
+            for dim in tensor.dims:
+                handle.write(struct.pack("<Q", dim))
+            handle.write(struct.pack("<IQ", tensor.ggml_type, offset))
+
+        data_start = align_up(handle.tell())
+        handle.write(b"\0" * (data_start - handle.tell()))
+        relative_written = 0
+        for tensor in plan:
+            before = handle.tell()
+            produced = produce(tensor, handle)
+            observed = handle.tell() - before
+            if produced != observed or observed != tensor.byte_len:
+                raise ValueError(
+                    f"{tensor.out_name}: expected {tensor.byte_len} bytes, "
+                    f"producer reported {produced} and wrote {observed}"
+                )
+            relative_written += observed
+            padded = align_up(relative_written)
+            handle.write(b"\0" * (padded - relative_written))
+            relative_written = padded
+        handle.flush()
+        os.fsync(handle.fileno())
+
+
+@dataclass(frozen=True)
+class GgufTensor:
+    name: str
+    dims: tuple[int, ...]
+    ggml_type: int
+    relative_offset: int
+    byte_len: int
+    absolute_offset: int
+
+
+class GgufReader:
+    def __init__(self, path: Path):
+        self.path = path
+        self._file = path.open("rb")
+        self._map = mmap.mmap(self._file.fileno(), 0, access=mmap.ACCESS_READ)
+        self.metadata: dict[str, object] = {}
+        self.tensors: tuple[GgufTensor, ...] = ()
+        self.directory_end = 0
+        self.data_start = 0
+        try:
+            self._parse()
+        except Exception:
+            self.close()
+            raise
+
+    def close(self) -> None:
+        try:
+            self._map.close()
+        except BufferError:
+            pass
+        self._file.close()
+
+    def __enter__(self) -> "GgufReader":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def _unpack(self, fmt: str, cursor: int) -> tuple[tuple[object, ...], int]:
+        size = struct.calcsize(fmt)
+        if cursor + size > len(self._map):
+            raise ValueError("GGUF directory is truncated")
+        return struct.unpack_from(fmt, self._map, cursor), cursor + size
+
+    def _string(self, cursor: int) -> tuple[str, int]:
+        (length,), cursor = self._unpack("<Q", cursor)
+        end = cursor + int(length)
+        if end > len(self._map):
+            raise ValueError("GGUF string overruns file")
+        try:
+            value = self._map[cursor:end].decode("utf-8")
+        except UnicodeDecodeError as error:
+            raise ValueError(f"GGUF string is not UTF-8: {error}") from error
+        return value, end
+
+    def _parse(self) -> None:
+        if self._map[:4] != b"GGUF":
+            raise ValueError("not a GGUF file")
+        (version, tensor_count, kv_count), cursor = self._unpack("<IQQ", 4)
+        if version != 3:
+            raise ValueError(f"expected GGUF v3, found v{version}")
+        for _ in range(int(kv_count)):
+            key, cursor = self._string(cursor)
+            (value_type,), cursor = self._unpack("<I", cursor)
+            if value_type == GGUF_VALUE_U32:
+                (value,), cursor = self._unpack("<I", cursor)
+            elif value_type == GGUF_VALUE_STRING:
+                value, cursor = self._string(cursor)
+            elif value_type == GGUF_VALUE_ARRAY:
+                (element_type, length), cursor = self._unpack("<IQ", cursor)
+                if element_type != GGUF_VALUE_I32:
+                    raise ValueError(f"unsupported GGUF array type {element_type}")
+                values = []
+                for _ in range(int(length)):
+                    (item,), cursor = self._unpack("<i", cursor)
+                    values.append(item)
+                value = tuple(values)
+            else:
+                raise ValueError(f"unsupported GGUF metadata type {value_type}")
+            if key in self.metadata:
+                raise ValueError(f"duplicate GGUF metadata key {key}")
+            self.metadata[key] = value
+
+        directory: list[tuple[str, tuple[int, ...], int, int]] = []
+        for _ in range(int(tensor_count)):
+            name, cursor = self._string(cursor)
+            (ndim,), cursor = self._unpack("<I", cursor)
+            dims = []
+            for _ in range(int(ndim)):
+                (dim,), cursor = self._unpack("<Q", cursor)
+                dims.append(int(dim))
+            (ggml_type, relative_offset), cursor = self._unpack("<IQ", cursor)
+            directory.append((name, tuple(dims), int(ggml_type), int(relative_offset)))
+
+        self.directory_end = cursor
+        self.data_start = align_up(cursor)
+        tensors: list[GgufTensor] = []
+        seen: set[str] = set()
+        previous_end = self.data_start
+        for name, dims, ggml_type, relative_offset in directory:
+            if name in seen:
+                raise ValueError(f"duplicate GGUF tensor {name}")
+            seen.add(name)
+            byte_len = ggml_nbytes(dims, ggml_type)
+            absolute_offset = self.data_start + relative_offset
+            if absolute_offset % ALIGNMENT:
+                raise ValueError(f"tensor {name} is not {ALIGNMENT}-byte aligned")
+            if absolute_offset < previous_end:
+                raise ValueError(f"tensor {name} overlaps the previous tensor")
+            if absolute_offset + byte_len > len(self._map):
+                raise ValueError(f"tensor {name} overruns GGUF file")
+            tensors.append(
+                GgufTensor(
+                    name=name,
+                    dims=dims,
+                    ggml_type=ggml_type,
+                    relative_offset=relative_offset,
+                    byte_len=byte_len,
+                    absolute_offset=absolute_offset,
+                )
+            )
+            previous_end = absolute_offset + byte_len
+        self.tensors = tuple(tensors)
+
+    def tensor(self, name: str) -> GgufTensor:
+        for tensor in self.tensors:
+            if tensor.name == name:
+                return tensor
+        raise KeyError(f"GGUF tensor not found: {name}")
+
+    def tensor_array(self, tensor: GgufTensor, dtype: np.dtype | str) -> np.ndarray:
+        return np.frombuffer(
+            self._map,
+            dtype=dtype,
+            count=tensor.byte_len // np.dtype(dtype).itemsize,
+            offset=tensor.absolute_offset,
+        )
+
+    def bytes_at(self, start: int, end: int) -> bytes:
+        if start < 0 or start > end or end > len(self._map):
+            raise ValueError("GGUF byte range is outside the file")
+        return self._map[start:end]
+
+
+def ggml_nbytes(dims: tuple[int, ...], ggml_type: int) -> int:
+    elements = 1
+    for dim in dims:
+        elements *= dim
+    if ggml_type == GGML_F32:
+        return elements * 4
+    if ggml_type == GGML_F16:
+        return elements * 2
+    if ggml_type == GGML_Q8_0:
+        if elements % 32:
+            raise ValueError("Q8_0 tensor is not block aligned")
+        return elements // 32 * 34
+    if ggml_type == GGML_Q2_K:
+        if elements % 256:
+            raise ValueError("Q2_K tensor is not block aligned")
+        return elements // 256 * 84
+    if ggml_type == GGML_MXFP4:
+        if elements % 32:
+            raise ValueError("MXFP4 tensor is not block aligned")
+        return elements // 32 * 17
+    raise ValueError(f"unsupported GGML tensor type {ggml_type}")

scripts/recipe.py

@@ -0,0 +1,519 @@
+#!/usr/bin/env python3
+"""Immutable source manifest and deterministic DSpark GGUF tensor recipe."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterator
+
+
+REPOSITORY_ROOT = Path(__file__).resolve().parents[1]
+SOURCE_MANIFEST_PATH = REPOSITORY_ROOT / "manifest" / "source.json"
+with SOURCE_MANIFEST_PATH.open(encoding="utf-8") as _manifest_handle:
+    _SOURCE_MANIFEST = json.load(_manifest_handle)
+
+SOURCE_REPOSITORY = str(_SOURCE_MANIFEST["repository"])
+SOURCE_REVISION = str(_SOURCE_MANIFEST["revision"])
+SOURCE_FILES = {
+    str(name): {"size": int(properties["size"]), "sha256": str(properties["sha256"])}
+    for name, properties in _SOURCE_MANIFEST["files"].items()
+}
+if sum(int(properties["size"]) for properties in SOURCE_FILES.values()) != int(
+    _SOURCE_MANIFEST["total_size"]
+):
+    raise ValueError(
+        f"{SOURCE_MANIFEST_PATH}: total_size does not match its file entries"
+    )
+
+ARCHITECTURE = "deepseek_v4_flash_dspark_draft"
+GENERAL_NAME = "DeepSeek-V4-Flash-0731-DSpark-Drafter"
+RECIPE_VERSION = 1
+
+BLOCK_SIZE = 5
+MARKOV_RANK = 256
+NOISE_TOKEN_ID = 128_799
+TARGET_LAYER_IDS = (40, 41, 42)
+LAYER_COUNT = 3
+HEAD_LAYER = 2
+N_EMBD = 4096
+N_EXPERTS = 256
+VOCAB_SIZE = 129_280
+
+GGML_F32 = 0
+GGML_F16 = 1
+GGML_Q8_0 = 8
+GGML_Q2_K = 10
+GGML_MXFP4 = 39
+GGML_TYPE_NAMES = {
+    GGML_F32: "F32",
+    GGML_F16: "F16",
+    GGML_Q8_0: "Q8_0",
+    GGML_Q2_K: "Q2_K",
+    GGML_MXFP4: "MXFP4",
+}
+
+KIND_PLAIN_F32 = "plain_f32"
+KIND_RELABEL_F32 = "relabel_f32"
+KIND_FP8_TO_Q8_0 = "fp8_to_q8_0"
+KIND_FUSED_EXPERTS_MXFP4 = "fused_experts_mxfp4"
+KIND_FUSED_EXPERTS_Q2_K = "fused_experts_q2_k"
+KIND_MARKOV_F16 = "markov_f16"
+
+RECIPE_MXFP4_Q8_0 = "mxfp4-q8_0"
+RECIPE_Q2_K_Q8_0 = "q2_k-q8_0"
+
+
+@dataclass(frozen=True)
+class ArtifactRecipe:
+    """One output policy over the shared canonical tensor/source plan."""
+
+    name: str
+    output_filename: str
+    routed_expert_kind: str
+    routed_expert_type: int
+    expected_tensor_bytes: int
+    expected_file_size: int
+    expected_type_counts: tuple[tuple[int, int], ...]
+    q2_k_error_limit: float | None = None
+
+    def manifest_filename(self, kind: str) -> str:
+        if kind not in {"build", "validation"}:
+            raise ValueError(f"unknown manifest kind: {kind}")
+        if self.name == RECIPE_MXFP4_Q8_0:
+            return f"{kind}.json"
+        return f"{kind}-{self.name}.json"
+
+
+MXFP4_Q8_0_RECIPE = ArtifactRecipe(
+    name=RECIPE_MXFP4_Q8_0,
+    output_filename="DeepSeek-V4-Flash-0731-DSpark-Drafter-MXFP4-Q8_0.gguf",
+    routed_expert_kind=KIND_FUSED_EXPERTS_MXFP4,
+    routed_expert_type=GGML_MXFP4,
+    expected_tensor_bytes=10_897_104_284,
+    expected_file_size=10_897_110_272,
+    expected_type_counts=(
+        (GGML_F32, 45),
+        (GGML_F16, 2),
+        (GGML_Q8_0, 25),
+        (GGML_MXFP4, 9),
+    ),
+)
+Q2_K_Q8_0_RECIPE = ArtifactRecipe(
+    name=RECIPE_Q2_K_Q8_0,
+    output_filename="DeepSeek-V4-Flash-0731-DSpark-Drafter-Q2_K-Q8_0.gguf",
+    routed_expert_kind=KIND_FUSED_EXPERTS_Q2_K,
+    routed_expert_type=GGML_Q2_K,
+    expected_tensor_bytes=6_971_235_740,
+    expected_file_size=6_971_241_728,
+    expected_type_counts=(
+        (GGML_F32, 45),
+        (GGML_F16, 2),
+        (GGML_Q8_0, 25),
+        (GGML_Q2_K, 9),
+    ),
+    q2_k_error_limit=0.50,
+)
+RECIPES = {recipe.name: recipe for recipe in (MXFP4_Q8_0_RECIPE, Q2_K_Q8_0_RECIPE)}
+DEFAULT_RECIPE = MXFP4_Q8_0_RECIPE
+OUTPUT_FILENAME = DEFAULT_RECIPE.output_filename
+
+
+def resolve_recipe(recipe: ArtifactRecipe | str | None = None) -> ArtifactRecipe:
+    if recipe is None:
+        return DEFAULT_RECIPE
+    if isinstance(recipe, ArtifactRecipe):
+        return recipe
+    try:
+        return RECIPES[recipe]
+    except KeyError as error:
+        choices = ", ".join(sorted(RECIPES))
+        raise ValueError(
+            f"unknown recipe {recipe!r}; choose one of: {choices}"
+        ) from error
+
+
+@dataclass(frozen=True)
+class TensorRecipe:
+    out_name: str
+    kind: str
+    dims: tuple[int, ...]
+    ggml_type: int
+    src_name: str = ""
+    src_is_bf16: bool = False
+    src_shape: tuple[int, ...] = ()
+    weight_name: str = ""
+    scale_name: str = ""
+    rows: int = 0
+    cols: int = 0
+    name_prefix: str = ""
+    expert_kind: str = ""
+
+    @property
+    def elements(self) -> int:
+        value = 1
+        for dim in self.dims:
+            value *= dim
+        return value
+
+    @property
+    def byte_len(self) -> int:
+        if self.ggml_type == GGML_F32:
+            return self.elements * 4
+        if self.ggml_type == GGML_F16:
+            return self.elements * 2
+        if self.ggml_type == GGML_Q8_0:
+            if self.elements % 32:
+                raise ValueError(
+                    f"{self.out_name}: Q8_0 element count is not block aligned"
+                )
+            return self.elements // 32 * 34
+        if self.ggml_type == GGML_Q2_K:
+            if self.elements % 256:
+                raise ValueError(
+                    f"{self.out_name}: Q2_K element count is not block aligned"
+                )
+            return self.elements // 256 * 84
+        if self.ggml_type == GGML_MXFP4:
+            if self.elements % 32:
+                raise ValueError(
+                    f"{self.out_name}: MXFP4 element count is not block aligned"
+                )
+            return self.elements // 32 * 17
+        raise ValueError(f"{self.out_name}: unsupported GGML type {self.ggml_type}")
+
+
+def _plain(
+    out_name: str,
+    src_name: str,
+    *,
+    bf16: bool,
+    dims: tuple[int, ...],
+    src_shape: tuple[int, ...] | None = None,
+) -> TensorRecipe:
+    return TensorRecipe(
+        out_name=out_name,
+        kind=KIND_PLAIN_F32,
+        dims=dims,
+        ggml_type=GGML_F32,
+        src_name=src_name,
+        src_is_bf16=bf16,
+        src_shape=dims if src_shape is None else src_shape,
+    )
+
+
+def _fp8(
+    out_name: str,
+    weight_name: str,
+    scale_name: str,
+    rows: int,
+    cols: int,
+) -> TensorRecipe:
+    return TensorRecipe(
+        out_name=out_name,
+        kind=KIND_FP8_TO_Q8_0,
+        dims=(cols, rows),
+        ggml_type=GGML_Q8_0,
+        weight_name=weight_name,
+        scale_name=scale_name,
+        rows=rows,
+        cols=cols,
+    )
+
+
+def _layer_plan(layer: int, artifact_recipe: ArtifactRecipe) -> list[TensorRecipe]:
+    prefix = f"mtp.{layer}"
+    out: list[TensorRecipe] = [
+        _plain(
+            f"dspark.{layer}.attn_sinks.weight",
+            f"{prefix}.attn.attn_sink",
+            bf16=False,
+            dims=(64,),
+        ),
+        _plain(
+            f"dspark.{layer}.attn_norm.weight",
+            f"{prefix}.attn_norm.weight",
+            bf16=True,
+            dims=(N_EMBD,),
+        ),
+        _plain(
+            f"dspark.{layer}.ffn_norm.weight",
+            f"{prefix}.ffn_norm.weight",
+            bf16=True,
+            dims=(N_EMBD,),
+        ),
+        _plain(
+            f"dspark.{layer}.attn_kv_a_norm.weight",
+            f"{prefix}.attn.kv_norm.weight",
+            bf16=True,
+            dims=(512,),
+        ),
+        _plain(
+            f"dspark.{layer}.attn_q_a_norm.weight",
+            f"{prefix}.attn.q_norm.weight",
+            bf16=True,
+            dims=(1024,),
+        ),
+        _fp8(
+            f"dspark.{layer}.attn_kv.weight",
+            f"{prefix}.attn.wkv.weight",
+            f"{prefix}.attn.wkv.scale",
+            512,
+            N_EMBD,
+        ),
+        _fp8(
+            f"dspark.{layer}.attn_q_a.weight",
+            f"{prefix}.attn.wq_a.weight",
+            f"{prefix}.attn.wq_a.scale",
+            1024,
+            N_EMBD,
+        ),
+        _fp8(
+            f"dspark.{layer}.attn_q_b.weight",
+            f"{prefix}.attn.wq_b.weight",
+            f"{prefix}.attn.wq_b.scale",
+            32768,
+            1024,
+        ),
+        _fp8(
+            f"dspark.{layer}.attn_output_a.weight",
+            f"{prefix}.attn.wo_a.weight",
+            f"{prefix}.attn.wo_a.scale",
+            8192,
+            N_EMBD,
+        ),
+        _fp8(
+            f"dspark.{layer}.attn_output_b.weight",
+            f"{prefix}.attn.wo_b.weight",
+            f"{prefix}.attn.wo_b.scale",
+            N_EMBD,
+            8192,
+        ),
+        _fp8(
+            f"dspark.{layer}.ffn_gate_shexp.weight",
+            f"{prefix}.ffn.shared_experts.w1.weight",
+            f"{prefix}.ffn.shared_experts.w1.scale",
+            2048,
+            N_EMBD,
+        ),
+        _fp8(
+            f"dspark.{layer}.ffn_up_shexp.weight",
+            f"{prefix}.ffn.shared_experts.w3.weight",
+            f"{prefix}.ffn.shared_experts.w3.scale",
+            2048,
+            N_EMBD,
+        ),
+        _fp8(
+            f"dspark.{layer}.ffn_down_shexp.weight",
+            f"{prefix}.ffn.shared_experts.w2.weight",
+            f"{prefix}.ffn.shared_experts.w2.scale",
+            N_EMBD,
+            2048,
+        ),
+        _plain(
+            f"dspark.{layer}.ffn_gate_inp.weight",
+            f"{prefix}.ffn.gate.weight",
+            bf16=True,
+            dims=(N_EMBD, N_EXPERTS),
+            src_shape=(N_EXPERTS, N_EMBD),
+        ),
+        _plain(
+            f"dspark.{layer}.exp_probs_b.bias",
+            f"{prefix}.ffn.gate.bias",
+            bf16=False,
+            dims=(N_EXPERTS,),
+        ),
+    ]
+
+    for expert_kind, output_suffix, rows, cols in (
+        ("w1", "ffn_gate_exps", 2048, N_EMBD),
+        ("w3", "ffn_up_exps", 2048, N_EMBD),
+        ("w2", "ffn_down_exps", N_EMBD, 2048),
+    ):
+        out.append(
+            TensorRecipe(
+                out_name=f"dspark.{layer}.{output_suffix}.weight",
+                kind=artifact_recipe.routed_expert_kind,
+                dims=(cols, rows, N_EXPERTS),
+                ggml_type=artifact_recipe.routed_expert_type,
+                rows=rows,
+                cols=cols,
+                name_prefix=prefix,
+                expert_kind=expert_kind,
+            )
+        )
+
+    for suffix in ("hc_attn_fn", "hc_ffn_fn"):
+        out.append(
+            TensorRecipe(
+                out_name=f"dspark.{layer}.{suffix}.weight",
+                kind=KIND_RELABEL_F32,
+                dims=(16384, 24),
+                ggml_type=GGML_F32,
+                src_name=f"{prefix}.{suffix}",
+                rows=24,
+                cols=16384,
+            )
+        )
+    for suffix in ("hc_attn_base", "hc_ffn_base"):
+        out.append(
+            _plain(
+                f"dspark.{layer}.{suffix}.weight",
+                f"{prefix}.{suffix}",
+                bf16=False,
+                dims=(24,),
+            )
+        )
+    for suffix in ("hc_attn_scale", "hc_ffn_scale"):
+        out.append(
+            _plain(
+                f"dspark.{layer}.{suffix}.weight",
+                f"{prefix}.{suffix}",
+                bf16=False,
+                dims=(3,),
+            )
+        )
+    return out
+
+
+def _global_plan() -> list[TensorRecipe]:
+    head = f"mtp.{HEAD_LAYER}"
+    out = [
+        _fp8(
+            "dspark.main_proj.weight",
+            "mtp.0.main_proj.weight",
+            "mtp.0.main_proj.scale",
+            N_EMBD,
+            12288,
+        ),
+        _plain(
+            "dspark.main_norm.weight",
+            "mtp.0.main_norm.weight",
+            bf16=True,
+            dims=(N_EMBD,),
+        ),
+        _plain(
+            "dspark.norm.weight",
+            f"{head}.norm.weight",
+            bf16=True,
+            dims=(N_EMBD,),
+        ),
+    ]
+    for suffix in ("markov_w1", "markov_w2"):
+        out.append(
+            TensorRecipe(
+                out_name=f"dspark.{suffix}.weight",
+                kind=KIND_MARKOV_F16,
+                dims=(MARKOV_RANK, VOCAB_SIZE),
+                ggml_type=GGML_F16,
+                src_name=f"{head}.markov_head.{suffix}.weight",
+            )
+        )
+    out.extend(
+        [
+            TensorRecipe(
+                out_name="dspark.hc_head_fn.weight",
+                kind=KIND_RELABEL_F32,
+                dims=(16384, 4),
+                ggml_type=GGML_F32,
+                src_name=f"{head}.hc_head_fn",
+                rows=4,
+                cols=16384,
+            ),
+            _plain(
+                "dspark.hc_head_base.weight",
+                f"{head}.hc_head_base",
+                bf16=False,
+                dims=(4,),
+            ),
+            _plain(
+                "dspark.hc_head_scale.weight",
+                f"{head}.hc_head_scale",
+                bf16=False,
+                dims=(1,),
+            ),
+            _plain(
+                "dspark.confidence_head.weight",
+                f"{head}.confidence_head.proj.weight",
+                bf16=True,
+                dims=(4352,),
+                src_shape=(1, 4352),
+            ),
+        ]
+    )
+    return out
+
+
+def build_plan(
+    recipe: ArtifactRecipe | str | None = None,
+) -> tuple[TensorRecipe, ...]:
+    artifact_recipe = resolve_recipe(recipe)
+    tensors: list[TensorRecipe] = []
+    for layer in range(LAYER_COUNT):
+        tensors.extend(_layer_plan(layer, artifact_recipe))
+    tensors.extend(_global_plan())
+    if len(tensors) != 81:
+        raise AssertionError(f"recipe contains {len(tensors)} tensors, expected 81")
+    if len({tensor.out_name for tensor in tensors}) != len(tensors):
+        raise AssertionError("recipe contains duplicate output tensor names")
+    tensor_bytes = sum(tensor.byte_len for tensor in tensors)
+    if tensor_bytes != artifact_recipe.expected_tensor_bytes:
+        raise AssertionError(
+            f"{artifact_recipe.name}: tensor payload is {tensor_bytes}, "
+            f"expected {artifact_recipe.expected_tensor_bytes}"
+        )
+    type_counts = tuple(
+        (ggml_type, sum(tensor.ggml_type == ggml_type for tensor in tensors))
+        for ggml_type, _expected in artifact_recipe.expected_type_counts
+    )
+    if type_counts != artifact_recipe.expected_type_counts:
+        raise AssertionError(
+            f"{artifact_recipe.name}: type inventory {type_counts} does not match "
+            f"{artifact_recipe.expected_type_counts}"
+        )
+    return tuple(tensors)
+
+
+def source_expectations(
+    tensor: TensorRecipe,
+) -> Iterator[tuple[str, str, tuple[int, ...]]]:
+    if tensor.kind == KIND_PLAIN_F32:
+        yield tensor.src_name, "BF16" if tensor.src_is_bf16 else "F32", tensor.src_shape
+    elif tensor.kind == KIND_RELABEL_F32:
+        yield tensor.src_name, "F32", (tensor.rows, tensor.cols)
+    elif tensor.kind == KIND_FP8_TO_Q8_0:
+        yield tensor.weight_name, "F8_E4M3", (tensor.rows, tensor.cols)
+        yield (
+            tensor.scale_name,
+            "F8_E8M0",
+            ((tensor.rows + 127) // 128, (tensor.cols + 127) // 128),
+        )
+    elif tensor.kind in {KIND_FUSED_EXPERTS_MXFP4, KIND_FUSED_EXPERTS_Q2_K}:
+        for expert in range(N_EXPERTS):
+            prefix = f"{tensor.name_prefix}.ffn.experts.{expert}.{tensor.expert_kind}"
+            yield f"{prefix}.weight", "I8", (tensor.rows, tensor.cols // 2)
+            yield f"{prefix}.scale", "F8_E8M0", (tensor.rows, tensor.cols // 32)
+    elif tensor.kind == KIND_MARKOV_F16:
+        yield tensor.src_name, "BF16", (VOCAB_SIZE, MARKOV_RANK)
+    else:
+        raise ValueError(f"unknown recipe kind {tensor.kind}")
+
+
+def source_paths(source_dir: Path) -> tuple[Path, ...]:
+    return tuple(source_dir / name for name in SOURCE_FILES)
+
+
+GGUF_METADATA = (
+    ("general.architecture", "string", ARCHITECTURE),
+    ("general.name", "string", GENERAL_NAME),
+    ("general.source.url", "string", f"https://huggingface.co/{SOURCE_REPOSITORY}"),
+    ("general.source.revision", "string", SOURCE_REVISION),
+    ("general.license", "string", "MIT"),
+    ("dspark.recipe_version", "u32", RECIPE_VERSION),
+    ("dspark.block_size", "u32", BLOCK_SIZE),
+    ("dspark.markov_rank", "u32", MARKOV_RANK),
+    ("dspark.noise_token_id", "u32", NOISE_TOKEN_ID),
+    ("dspark.target_layer_ids", "array_i32", TARGET_LAYER_IDS),
+    ("dspark.layer_count", "u32", LAYER_COUNT),
+)

scripts/reproduce.py

@@ -0,0 +1,227 @@
+#!/usr/bin/env python3
+"""Run the pinned conversion, included verification, and optional repeat build."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import platform
+import sys
+import tempfile
+from pathlib import Path
+
+import numpy as np
+
+from convert import convert
+from recipe import (
+    ARCHITECTURE,
+    DEFAULT_RECIPE,
+    RECIPES,
+    REPOSITORY_ROOT,
+    RECIPE_VERSION,
+    SOURCE_REPOSITORY,
+    SOURCE_REVISION,
+    ArtifactRecipe,
+    resolve_recipe,
+)
+from verify import verify, write_report
+
+
+def _write_json(path: Path, value: object) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(f".{path.name}.partial-{os.getpid()}")
+    with temporary.open("w", encoding="utf-8", newline="\n") as handle:
+        json.dump(value, handle, indent=2, sort_keys=True)
+        handle.write("\n")
+        handle.flush()
+        os.fsync(handle.fileno())
+    os.replace(temporary, path)
+
+
+def _update_sha256sums(path: Path, digest: str, filename: str) -> None:
+    entries: dict[str, str] = {}
+    if path.exists():
+        with path.open(encoding="ascii") as handle:
+            for line_number, line in enumerate(handle, 1):
+                stripped = line.rstrip("\n")
+                if not stripped:
+                    continue
+                existing_digest, separator, existing_filename = stripped.partition("  ")
+                if (
+                    separator != "  "
+                    or len(existing_digest) != 64
+                    or any(
+                        character not in "0123456789abcdef"
+                        for character in existing_digest
+                    )
+                    or not existing_filename
+                ):
+                    raise ValueError(
+                        f"{path}:{line_number}: malformed SHA256SUMS entry"
+                    )
+                entries[existing_filename] = existing_digest
+    entries[filename] = digest
+    temporary = path.with_name(f".{path.name}.partial-{os.getpid()}")
+    with temporary.open("w", encoding="ascii", newline="\n") as handle:
+        for entry_filename in sorted(entries):
+            handle.write(f"{entries[entry_filename]}  {entry_filename}\n")
+        handle.flush()
+        os.fsync(handle.fileno())
+    os.replace(temporary, path)
+
+
+def _build_input_hashes() -> dict[str, str]:
+    relative_paths = [
+        Path("requirements-linux-aarch64-py314.lock"),
+        Path("manifest/source.json"),
+        *(
+            Path("scripts") / name
+            for name in (
+                "convert.py",
+                "download_sources.py",
+                "formats.py",
+                "recipe.py",
+                "reproduce.py",
+                "verify.py",
+            )
+        ),
+    ]
+    hashes: dict[str, str] = {}
+    for relative_path in relative_paths:
+        path = REPOSITORY_ROOT / relative_path
+        digest = hashlib.sha256()
+        with path.open("rb") as handle:
+            while chunk := handle.read(1024 * 1024):
+                digest.update(chunk)
+        hashes[relative_path.as_posix()] = digest.hexdigest()
+    return hashes
+
+
+def reproduce(
+    source_dir: Path,
+    output: Path,
+    manifest_dir: Path,
+    *,
+    force: bool,
+    repeat_check: bool,
+    recipe: ArtifactRecipe | str | None = None,
+) -> None:
+    artifact_recipe = resolve_recipe(recipe)
+    output = output.resolve()
+    if output.exists() and not force:
+        raise FileExistsError(
+            f"output already exists: {output}; pass --force to replace it"
+        )
+    output.parent.mkdir(parents=True, exist_ok=True)
+    build_input_hashes = _build_input_hashes()
+
+    repeat_digest: str | None = None
+    with tempfile.TemporaryDirectory(
+        prefix=f".{output.name}.candidate-", dir=output.parent
+    ) as candidate_directory:
+        candidate = Path(candidate_directory) / output.name
+        size, digest = convert(source_dir, candidate, recipe=artifact_recipe)
+        report = verify(source_dir, candidate, recipe=artifact_recipe)
+        artifact = report["artifact"]
+        if artifact["size"] != size or artifact["sha256"] != digest:
+            raise ValueError("converter and verifier disagree on artifact identity")
+
+        if repeat_check:
+            with tempfile.TemporaryDirectory(
+                prefix=f".{output.name}.repeat-", dir=output.parent
+            ) as repeat_directory:
+                repeat_output = Path(repeat_directory) / output.name
+                repeat_size, repeat_digest = convert(
+                    source_dir, repeat_output, recipe=artifact_recipe
+                )
+                if repeat_size != size or repeat_digest != digest:
+                    raise ValueError(
+                        "repeat build is not byte-identical: "
+                        f"first={size}/{digest}, second={repeat_size}/{repeat_digest}"
+                    )
+
+        os.replace(candidate, output)
+        directory_fd = os.open(output.parent, os.O_RDONLY | os.O_DIRECTORY)
+        try:
+            os.fsync(directory_fd)
+        finally:
+            os.close(directory_fd)
+
+    manifest_dir = manifest_dir.resolve()
+    write_report(manifest_dir / artifact_recipe.manifest_filename("validation"), report)
+    build = {
+        "artifact": artifact,
+        "build_inputs": build_input_hashes,
+        "environment": {
+            "machine": platform.machine(),
+            "numpy": np.__version__,
+            "platform": platform.platform(),
+            "python": platform.python_version(),
+        },
+        "format": {
+            "architecture": ARCHITECTURE,
+            "gguf_version": 3,
+            "recipe": artifact_recipe.name,
+            "recipe_version": RECIPE_VERSION,
+        },
+        "repeat_build": {
+            "performed": repeat_check,
+            "sha256": repeat_digest,
+            "status": "byte-identical" if repeat_check else "not-run",
+        },
+        "source": {
+            "repository": SOURCE_REPOSITORY,
+            "revision": SOURCE_REVISION,
+        },
+    }
+    _write_json(manifest_dir / artifact_recipe.manifest_filename("build"), build)
+    _update_sha256sums(output.parent / "SHA256SUMS", digest, output.name)
+    print(f"[reproduce] PASS: {output.name} {size:,} bytes {digest}", flush=True)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--sources", type=Path, required=True)
+    parser.add_argument(
+        "--recipe",
+        choices=sorted(RECIPES),
+        default=DEFAULT_RECIPE.name,
+        help=f"Artifact recipe (default: {DEFAULT_RECIPE.name})",
+    )
+    parser.add_argument(
+        "--output",
+        type=Path,
+        help="Output path (default: the selected recipe's canonical filename)",
+    )
+    parser.add_argument("--manifest-dir", type=Path, default=Path("manifest"))
+    parser.add_argument("--force", action="store_true")
+    parser.add_argument(
+        "--repeat-check",
+        action="store_true",
+        help="Build a second clean GGUF and require a byte-identical SHA-256",
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    recipe = resolve_recipe(args.recipe)
+    output = args.output if args.output is not None else Path(recipe.output_filename)
+    try:
+        reproduce(
+            args.sources,
+            output,
+            args.manifest_dir,
+            force=args.force,
+            repeat_check=args.repeat_check,
+            recipe=recipe,
+        )
+    except Exception as error:
+        print(f"[reproduce] ERROR: {error}", file=sys.stderr)
+        raise SystemExit(1) from error
+
+
+if __name__ == "__main__":
+    main()

scripts/verify.py

@@ -0,0 +1,613 @@
+#!/usr/bin/env python3
+"""Independently verify GGUF structure and every tensor against pinned sources."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import os
+from pathlib import Path
+
+import numpy as np
+
+from formats import (
+    ALIGNMENT,
+    GgufReader,
+    SafeTensorSet,
+    align_up,
+    sha256_path,
+    verify_source_files,
+)
+from recipe import (
+    DEFAULT_RECIPE,
+    GGML_F16,
+    GGML_F32,
+    GGML_MXFP4,
+    GGML_Q2_K,
+    GGML_Q8_0,
+    GGML_TYPE_NAMES,
+    GGUF_METADATA,
+    KIND_PLAIN_F32,
+    N_EXPERTS,
+    RECIPES,
+    SOURCE_REPOSITORY,
+    SOURCE_REVISION,
+    ArtifactRecipe,
+    TensorRecipe,
+    build_plan,
+    resolve_recipe,
+    source_paths,
+)
+
+
+def _decode_e4m3_table() -> np.ndarray:
+    values = []
+    for byte in range(256):
+        sign = -1.0 if byte & 0x80 else 1.0
+        exponent = (byte >> 3) & 0x0F
+        mantissa = byte & 0x07
+        if exponent == 0x0F and mantissa == 0x07:
+            value = np.nan
+        elif exponent == 0:
+            value = sign * (mantissa / 8.0) * math.ldexp(1.0, -6)
+        else:
+            value = sign * (1.0 + mantissa / 8.0) * math.ldexp(1.0, exponent - 7)
+        values.append(np.float32(value))
+    return np.array(values, dtype=np.float32)
+
+
+VERIFY_E4M3 = _decode_e4m3_table()
+VERIFY_E8M0 = np.array(
+    [
+        np.float32(np.nan) if code == 0xFF else np.float32(math.ldexp(1.0, code - 127))
+        for code in range(256)
+    ],
+    dtype=np.float32,
+)
+VERIFY_FP4 = np.array(
+    [
+        0.0,
+        0.5,
+        1.0,
+        1.5,
+        2.0,
+        3.0,
+        4.0,
+        6.0,
+        0.0,
+        -0.5,
+        -1.0,
+        -1.5,
+        -2.0,
+        -3.0,
+        -4.0,
+        -6.0,
+    ],
+    dtype=np.float32,
+)
+# Independently decode and compare at most one routed expert at a time.
+VERIFY_EXPERT_ROW_BATCH = 4096
+
+
+def decode_q2_k_blocks(encoded: np.ndarray) -> np.ndarray:
+    """Independently decode GGML Q2_K's 84-byte/256-value block layout."""
+
+    blocks = np.asarray(encoded, dtype=np.uint8)
+    if blocks.ndim != 2 or blocks.shape[1] != 84:
+        raise ValueError("Q2_K payload must have shape (n, 84)")
+    scale_bytes = blocks[:, :16]
+    d = blocks[:, 80:82].copy().reshape(-1).view("<f2").astype(np.float32)
+    dmin = blocks[:, 82:84].copy().reshape(-1).view("<f2").astype(np.float32)
+    if not np.isfinite(d).all() or not np.isfinite(dmin).all():
+        raise ValueError("Q2_K payload contains a non-finite block scale")
+
+    codes = np.empty((blocks.shape[0], 256), dtype=np.uint8)
+    for start in (0, 128):
+        offset = 16 + start // 4
+        packed = blocks[:, offset : offset + 32]
+        codes[:, start : start + 32] = packed & np.uint8(0x03)
+        codes[:, start + 32 : start + 64] = (packed >> np.uint8(2)) & np.uint8(0x03)
+        codes[:, start + 64 : start + 96] = (packed >> np.uint8(4)) & np.uint8(0x03)
+        codes[:, start + 96 : start + 128] = packed >> np.uint8(6)
+
+    group_scales = np.multiply(
+        d[:, None], scale_bytes & np.uint8(0x0F), dtype=np.float32
+    )
+    group_mins = np.multiply(
+        dmin[:, None], scale_bytes >> np.uint8(4), dtype=np.float32
+    )
+    decoded = np.subtract(
+        np.multiply(
+            group_scales[..., None],
+            codes.reshape(-1, 16, 16),
+            dtype=np.float32,
+        ),
+        group_mins[..., None],
+        dtype=np.float32,
+    )
+    return decoded.reshape(-1, 256)
+
+
+def _decode_source_mxfp4_rows(
+    packed: np.ndarray,
+    scale_codes: np.ndarray,
+    rows: int,
+    cols: int,
+) -> np.ndarray:
+    if cols % 32:
+        raise ValueError("source MXFP4 column count must be divisible by 32")
+    block_count = cols // 32
+    source = np.asarray(packed, dtype=np.uint8).reshape(rows, block_count, 16)
+    scales = np.asarray(scale_codes, dtype=np.uint8).reshape(rows, block_count)
+    if np.any(scales == 0xFF):
+        raise ValueError("source MXFP4 contains reserved E8M0 NaN scale 0xff")
+    codes = np.empty((rows, block_count, 32), dtype=np.uint8)
+    codes[..., 0::2] = source & np.uint8(0x0F)
+    codes[..., 1::2] = source >> np.uint8(4)
+    decoded = VERIFY_FP4[codes]
+    decoded *= VERIFY_E8M0[scales][..., None]
+    return decoded.reshape(rows, cols)
+
+
+def _expected_metadata() -> dict[str, object]:
+    expected: dict[str, object] = {}
+    for key, kind, value in GGUF_METADATA:
+        if kind == "array_i32":
+            expected[key] = tuple(int(item) for item in value)
+        elif kind == "u32":
+            expected[key] = int(value)
+        else:
+            expected[key] = str(value)
+    return expected
+
+
+def _assert_equal(name: str, observed: np.ndarray, expected: np.ndarray) -> None:
+    if observed.shape != expected.shape:
+        raise ValueError(
+            f"{name}: expected shape {expected.shape}, found {observed.shape}"
+        )
+    if not np.array_equal(observed, expected):
+        mismatch = np.flatnonzero(observed.reshape(-1) != expected.reshape(-1))
+        first = int(mismatch[0]) if mismatch.size else -1
+        raise ValueError(f"{name}: exact comparison failed at element {first}")
+
+
+def _verify_f32(
+    source: SafeTensorSet,
+    reader: GgufReader,
+    tensor: TensorRecipe,
+) -> None:
+    output = reader.tensor_array(reader.tensor(tensor.out_name), "<u4")
+    if tensor.kind == KIND_PLAIN_F32 and tensor.src_is_bf16:
+        bits = source.array(tensor.src_name, "<u2").reshape(-1)
+        expected = bits.astype("<u4") << np.uint32(16)
+    else:
+        expected = source.array(tensor.src_name, "<u4").reshape(-1)
+    _assert_equal(tensor.out_name, output, expected)
+
+
+def _verify_markov_f16(
+    source: SafeTensorSet,
+    reader: GgufReader,
+    tensor: TensorRecipe,
+) -> None:
+    output = reader.tensor_array(reader.tensor(tensor.out_name), "<u2")
+    bits = source.array(tensor.src_name, "<u2").reshape(-1)
+    chunk = 8 * 1024 * 1024
+    for start in range(0, bits.size, chunk):
+        stop = min(start + chunk, bits.size)
+        f32_bits = bits[start:stop].astype("<u4") << np.uint32(16)
+        expected = f32_bits.view("<f4").astype("<f2").view("<u2")
+        _assert_equal(
+            f"{tensor.out_name}[{start}:{stop}]",
+            output[start:stop],
+            expected,
+        )
+
+
+def _verify_q8_0(
+    source: SafeTensorSet,
+    reader: GgufReader,
+    tensor: TensorRecipe,
+) -> float:
+    info = reader.tensor(tensor.out_name)
+    encoded = reader.tensor_array(info, np.uint8).reshape(-1, 34)
+    weights = source.array(tensor.weight_name, np.uint8).reshape(
+        tensor.rows, tensor.cols
+    )
+    scale_codes = source.array(tensor.scale_name, np.uint8).reshape(
+        (tensor.rows + 127) // 128,
+        (tensor.cols + 127) // 128,
+    )
+    max_relative_error = np.float32(0.0)
+    block_cursor = 0
+    for block_row in range(scale_codes.shape[0]):
+        row_start = block_row * 128
+        row_end = min(row_start + 128, tensor.rows)
+        reference = VERIFY_E4M3[weights[row_start:row_end]]
+        column_scales = np.repeat(VERIFY_E8M0[scale_codes[block_row]], 128)[
+            : tensor.cols
+        ]
+        if not np.isfinite(reference).all() or not np.isfinite(column_scales).all():
+            raise ValueError(f"{tensor.out_name}: non-finite pinned FP8 source")
+        reference *= column_scales[None, :]
+        reference_blocks = reference.reshape(-1, 32)
+        block_count = reference_blocks.shape[0]
+        output_blocks = encoded[block_cursor : block_cursor + block_count]
+        maxima = np.max(np.abs(reference_blocks), axis=1).astype(np.float32, copy=False)
+        expected_scales = maxima / np.float32(127.0)
+        expected_scale_bits = expected_scales.astype("<f2").view("<u2")
+        observed_scale_bits = output_blocks[:, :2].copy().reshape(-1).view("<u2")
+        _assert_equal(
+            f"{tensor.out_name}/scale-bits-{block_cursor}",
+            observed_scale_bits,
+            expected_scale_bits,
+        )
+        inverse = np.zeros_like(expected_scales)
+        np.divide(
+            np.float32(1.0),
+            expected_scales,
+            out=inverse,
+            where=expected_scales != 0,
+        )
+        normalized = reference_blocks * inverse[:, None]
+        truncated = np.trunc(normalized).astype(np.float32, copy=False)
+        fraction = np.abs(normalized - truncated)
+        expected_codes = np.where(
+            fraction >= np.float32(0.5),
+            truncated + np.copysign(np.float32(1.0), normalized),
+            truncated,
+        ).astype(np.int8)
+        observed_codes = output_blocks[:, 2:].view(np.int8)
+        _assert_equal(
+            f"{tensor.out_name}/codes-{block_cursor}",
+            observed_codes,
+            expected_codes,
+        )
+        stored_scale = (
+            output_blocks[:, :2].copy().reshape(-1).view("<f2").astype(np.float32)
+        )
+        if not np.isfinite(stored_scale).all():
+            raise ValueError(f"{tensor.out_name}: non-finite Q8_0 scale")
+        codes = output_blocks[:, 2:].view(np.int8).astype(np.float32)
+        decoded = stored_scale[:, None] * codes
+        denominator = np.maximum(
+            np.max(np.abs(reference_blocks), axis=1), np.float32(1e-6)
+        )
+        relative = np.abs(reference_blocks - decoded) / denominator[:, None]
+        if not np.isfinite(relative).all():
+            raise ValueError(f"{tensor.out_name}: non-finite Q8_0 error")
+        max_relative_error = np.maximum(max_relative_error, np.max(relative))
+        block_cursor += block_count
+    if block_cursor != encoded.shape[0]:
+        raise ValueError(f"{tensor.out_name}: Q8_0 block count mismatch")
+    result = float(max_relative_error)
+    if result > 0.01:
+        raise ValueError(
+            f"{tensor.out_name}: Q8_0 max relative error {result:.6f} > 0.01"
+        )
+    return result
+
+
+def _expected_mxfp4_codes(packed: np.ndarray, rows: int, cols: int) -> np.ndarray:
+    blocks = cols // 32
+    packed_blocks = np.asarray(packed, dtype=np.uint8).reshape(rows, blocks, 16)
+    low = np.empty((rows, blocks, 16), dtype=np.uint8)
+    high = np.empty((rows, blocks, 16), dtype=np.uint8)
+    low[..., 0::2] = packed_blocks[..., :8] & np.uint8(0x0F)
+    low[..., 1::2] = packed_blocks[..., :8] >> np.uint8(4)
+    high[..., 0::2] = packed_blocks[..., 8:] & np.uint8(0x0F)
+    high[..., 1::2] = packed_blocks[..., 8:] >> np.uint8(4)
+    return low | (high << np.uint8(4))
+
+
+def _verify_mxfp4(
+    source: SafeTensorSet,
+    reader: GgufReader,
+    tensor: TensorRecipe,
+) -> None:
+    blocks = tensor.cols // 32
+    output = reader.tensor_array(reader.tensor(tensor.out_name), np.uint8).reshape(
+        N_EXPERTS, tensor.rows, blocks, 17
+    )
+    for expert in range(N_EXPERTS):
+        prefix = f"{tensor.name_prefix}.ffn.experts.{expert}.{tensor.expert_kind}"
+        packed = source.array(f"{prefix}.weight", np.uint8)
+        scales = source.array(f"{prefix}.scale", np.uint8).reshape(tensor.rows, blocks)
+        if np.any(scales == 0xFF):
+            raise ValueError(f"{prefix}.scale: contains reserved E8M0 NaN")
+        _assert_equal(
+            f"{tensor.out_name}/expert-{expert}/scale",
+            output[expert, ..., 0],
+            scales,
+        )
+        expected_codes = _expected_mxfp4_codes(packed, tensor.rows, tensor.cols)
+        _assert_equal(
+            f"{tensor.out_name}/expert-{expert}/codes",
+            output[expert, ..., 1:],
+            expected_codes,
+        )
+
+
+def _verify_q2_k(
+    source: SafeTensorSet,
+    reader: GgufReader,
+    tensor: TensorRecipe,
+    error_limit: float,
+) -> float:
+    blocks_per_row = tensor.cols // 256
+    output = reader.tensor_array(reader.tensor(tensor.out_name), np.uint8).reshape(
+        N_EXPERTS, tensor.rows, blocks_per_row, 84
+    )
+    max_relative_error = np.float32(0.0)
+    source_scale_blocks = tensor.cols // 32
+    for expert in range(N_EXPERTS):
+        prefix = f"{tensor.name_prefix}.ffn.experts.{expert}.{tensor.expert_kind}"
+        packed = source.array(f"{prefix}.weight", np.uint8).reshape(
+            tensor.rows, tensor.cols // 2
+        )
+        scales = source.array(f"{prefix}.scale", np.uint8).reshape(
+            tensor.rows, source_scale_blocks
+        )
+        for row_start in range(0, tensor.rows, VERIFY_EXPERT_ROW_BATCH):
+            row_end = min(row_start + VERIFY_EXPERT_ROW_BATCH, tensor.rows)
+            row_count = row_end - row_start
+            reference = _decode_source_mxfp4_rows(
+                packed[row_start:row_end],
+                scales[row_start:row_end],
+                row_count,
+                tensor.cols,
+            ).reshape(-1, 256)
+            encoded = output[expert, row_start:row_end].reshape(-1, 84)
+            decoded = decode_q2_k_blocks(encoded)
+            if not np.isfinite(reference).all() or not np.isfinite(decoded).all():
+                raise ValueError(f"{tensor.out_name}: non-finite Q2_K comparison")
+            denominator = np.max(np.abs(reference), axis=1)
+            absolute_error = np.max(np.abs(reference - decoded), axis=1)
+            relative = np.zeros_like(absolute_error)
+            np.divide(
+                absolute_error,
+                denominator,
+                out=relative,
+                where=denominator != 0,
+            )
+            relative[np.logical_and(denominator == 0, absolute_error != 0)] = np.inf
+            max_relative_error = np.maximum(max_relative_error, np.max(relative))
+    result = float(max_relative_error)
+    if result > error_limit:
+        raise ValueError(
+            f"{tensor.out_name}: Q2_K max block-relative error "
+            f"{result:.6f} > {error_limit:.6f}"
+        )
+    return result
+
+
+def _verify_zero_padding(reader: GgufReader) -> None:
+    header_padding = reader.bytes_at(reader.directory_end, reader.data_start)
+    if any(header_padding):
+        raise ValueError("non-zero GGUF padding before tensor data")
+    tensors = reader.tensors
+    for index, tensor in enumerate(tensors):
+        data_end = tensor.absolute_offset + tensor.byte_len
+        next_start = (
+            tensors[index + 1].absolute_offset
+            if index + 1 < len(tensors)
+            else reader.data_start + align_up(tensor.relative_offset + tensor.byte_len)
+        )
+        padding = reader.bytes_at(data_end, next_start)
+        if any(padding):
+            raise ValueError(f"non-zero GGUF alignment padding after {tensor.name}")
+
+
+def verify(
+    source_dir: Path,
+    gguf_path: Path,
+    *,
+    recipe: ArtifactRecipe | str | None = None,
+) -> dict[str, object]:
+    artifact_recipe = resolve_recipe(recipe)
+    source_dir = source_dir.resolve()
+    gguf_path = gguf_path.resolve()
+    print("[verify] validating pinned source sizes and SHA-256 values", flush=True)
+    sources = verify_source_files(source_dir)
+    plan = build_plan(artifact_recipe)
+    max_q8_error = 0.0
+    max_q2_k_error = 0.0
+    exact_f32 = 0
+    exact_f16 = 0
+    exact_mxfp4 = 0
+    q2_k_tensors = 0
+    q8_tensors = 0
+    with (
+        SafeTensorSet(source_paths(source_dir)) as source,
+        GgufReader(gguf_path) as reader,
+    ):
+        source.validate_plan(plan)
+        expected_metadata = _expected_metadata()
+        if reader.metadata != expected_metadata:
+            raise ValueError(
+                f"GGUF metadata mismatch: expected {expected_metadata}, found {reader.metadata}"
+            )
+        observed_names = tuple(tensor.name for tensor in reader.tensors)
+        expected_names = tuple(tensor.out_name for tensor in plan)
+        if observed_names != expected_names:
+            raise ValueError("GGUF tensor order or names do not match the recipe")
+        expected_relative_offset = 0
+        for recipe_tensor, gguf_tensor in zip(plan, reader.tensors, strict=True):
+            if gguf_tensor.relative_offset != expected_relative_offset:
+                raise ValueError(
+                    f"{recipe_tensor.out_name}: expected relative offset "
+                    f"{expected_relative_offset}, found {gguf_tensor.relative_offset}"
+                )
+            expected_relative_offset = align_up(
+                expected_relative_offset + recipe_tensor.byte_len
+            )
+            if gguf_tensor.dims != recipe_tensor.dims:
+                raise ValueError(
+                    f"{recipe_tensor.out_name}: expected dims {recipe_tensor.dims}, "
+                    f"found {gguf_tensor.dims}"
+                )
+            if gguf_tensor.ggml_type != recipe_tensor.ggml_type:
+                raise ValueError(
+                    f"{recipe_tensor.out_name}: expected type {recipe_tensor.ggml_type}, "
+                    f"found {gguf_tensor.ggml_type}"
+                )
+            print(f"[verify] {recipe_tensor.out_name}", flush=True)
+            if recipe_tensor.ggml_type == GGML_F32:
+                _verify_f32(source, reader, recipe_tensor)
+                exact_f32 += 1
+            elif recipe_tensor.ggml_type == GGML_F16:
+                _verify_markov_f16(source, reader, recipe_tensor)
+                exact_f16 += 1
+            elif recipe_tensor.ggml_type == GGML_Q8_0:
+                q8_tensors += 1
+                max_q8_error = max(
+                    max_q8_error, _verify_q8_0(source, reader, recipe_tensor)
+                )
+            elif recipe_tensor.ggml_type == GGML_MXFP4:
+                _verify_mxfp4(source, reader, recipe_tensor)
+                exact_mxfp4 += 1
+            elif recipe_tensor.ggml_type == GGML_Q2_K:
+                if artifact_recipe.q2_k_error_limit is None:
+                    raise ValueError(
+                        f"{artifact_recipe.name}: Q2_K tensor has no error limit"
+                    )
+                q2_k_tensors += 1
+                max_q2_k_error = max(
+                    max_q2_k_error,
+                    _verify_q2_k(
+                        source,
+                        reader,
+                        recipe_tensor,
+                        artifact_recipe.q2_k_error_limit,
+                    ),
+                )
+            else:
+                raise ValueError(f"unsupported GGML type {recipe_tensor.ggml_type}")
+        _verify_zero_padding(reader)
+        expected_file_size = reader.data_start + align_up(
+            plan[-1].byte_len + reader.tensors[-1].relative_offset
+        )
+        actual_file_size = gguf_path.stat().st_size
+        if expected_file_size != artifact_recipe.expected_file_size:
+            raise ValueError(
+                f"{artifact_recipe.name}: recipe computes file size "
+                f"{expected_file_size}, expected {artifact_recipe.expected_file_size}"
+            )
+        if actual_file_size != expected_file_size:
+            raise ValueError(
+                f"GGUF size mismatch: expected {expected_file_size}, found {actual_file_size}"
+            )
+        data_start = reader.data_start
+
+    all_type_counts = {
+        GGML_F32: exact_f32,
+        GGML_F16: exact_f16,
+        GGML_Q8_0: q8_tensors,
+        GGML_Q2_K: q2_k_tensors,
+        GGML_MXFP4: exact_mxfp4,
+    }
+    observed_type_counts = tuple(
+        (ggml_type, all_type_counts[ggml_type])
+        for ggml_type, _count in artifact_recipe.expected_type_counts
+    )
+    unexpected_types = {
+        ggml_type: count
+        for ggml_type, count in all_type_counts.items()
+        if count and ggml_type not in dict(artifact_recipe.expected_type_counts)
+    }
+    if observed_type_counts != artifact_recipe.expected_type_counts or unexpected_types:
+        raise ValueError(
+            f"unexpected tensor type inventory for {artifact_recipe.name}: "
+            f"observed={observed_type_counts}, unexpected={unexpected_types}, "
+            f"expected={artifact_recipe.expected_type_counts}"
+        )
+
+    type_report = {
+        GGML_TYPE_NAMES[ggml_type]: count
+        for ggml_type, count in artifact_recipe.expected_type_counts
+    }
+    validation: dict[str, object] = {
+        "f32_exact_tensors": exact_f32,
+        "f16_exact_tensors": exact_f16,
+        "q8_0_max_block_relative_error": max_q8_error,
+        "q8_0_limit": 0.01,
+        "status": "pass",
+    }
+    if exact_mxfp4:
+        validation["mxfp4_exact_tensors"] = exact_mxfp4
+    if q2_k_tensors:
+        validation.update(
+            {
+                "q2_k_tensors": q2_k_tensors,
+                "q2_k_max_block_relative_error": max_q2_k_error,
+                "q2_k_limit": artifact_recipe.q2_k_error_limit,
+            }
+        )
+
+    report: dict[str, object] = {
+        "artifact": {
+            "filename": gguf_path.name,
+            "size": gguf_path.stat().st_size,
+            "sha256": sha256_path(gguf_path),
+        },
+        "source": {
+            "repository": SOURCE_REPOSITORY,
+            "revision": SOURCE_REVISION,
+            "files": sources,
+        },
+        "gguf": {
+            "version": 3,
+            "data_start": data_start,
+            "alignment": ALIGNMENT,
+            "tensor_count": len(plan),
+            "types": type_report,
+        },
+        "recipe": artifact_recipe.name,
+        "validation": validation,
+    }
+    print(json.dumps(report, indent=2, sort_keys=True), flush=True)
+    return report
+
+
+def write_report(path: Path, report: dict[str, object]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(f".{path.name}.partial-{os.getpid()}")
+    with temporary.open("w", encoding="utf-8", newline="\n") as handle:
+        json.dump(report, handle, indent=2, sort_keys=True)
+        handle.write("\n")
+        handle.flush()
+        os.fsync(handle.fileno())
+    os.replace(temporary, path)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--sources", type=Path, required=True)
+    parser.add_argument(
+        "--recipe",
+        choices=sorted(RECIPES),
+        default=DEFAULT_RECIPE.name,
+        help=f"Artifact recipe (default: {DEFAULT_RECIPE.name})",
+    )
+    parser.add_argument(
+        "--gguf",
+        type=Path,
+        help="GGUF path (default: the selected recipe's canonical filename)",
+    )
+    parser.add_argument("--report", type=Path)
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    recipe = resolve_recipe(args.recipe)
+    gguf = args.gguf if args.gguf is not None else Path(recipe.output_filename)
+    report = verify(args.sources, gguf, recipe=recipe)
+    if args.report:
+        write_report(args.report, report)
+
+
+if __name__ == "__main__":
+    main()

tests/test_recipe.py

@@ -0,0 +1,306 @@
+from __future__ import annotations
+
+# ruff: noqa: E402
+
+import json
+import io
+import struct
+import sys
+import tempfile
+import time
+import unittest
+from pathlib import Path
+from unittest import mock
+
+import numpy as np
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "scripts"))
+
+import convert as convert_module
+from convert import (
+    E4M3_TABLE,
+    TensorProducer,
+    decode_source_mxfp4,
+    quantize_q2_k,
+    quantize_q8_0,
+    repack_mxfp4,
+    round_away_from_zero,
+)
+from formats import GgufReader, SafeTensorSet, write_gguf
+from recipe import (
+    ARCHITECTURE,
+    GGML_Q2_K,
+    GGML_F16,
+    GGML_F32,
+    GGML_MXFP4,
+    GGML_Q8_0,
+    GGUF_METADATA,
+    KIND_PLAIN_F32,
+    MXFP4_Q8_0_RECIPE,
+    Q2_K_Q8_0_RECIPE,
+    TensorRecipe,
+    build_plan,
+    source_expectations,
+)
+from reproduce import _update_sha256sums
+from verify import decode_q2_k_blocks
+
+
+class RecipeTests(unittest.TestCase):
+    def test_plan_inventory_and_source_coverage(self) -> None:
+        mxfp4_plan = build_plan(MXFP4_Q8_0_RECIPE)
+        q2_k_plan = build_plan(Q2_K_Q8_0_RECIPE)
+        self.assertEqual(len(mxfp4_plan), 81)
+        self.assertEqual(len(q2_k_plan), 81)
+        mxfp4_counts = {
+            kind: sum(tensor.ggml_type == kind for tensor in mxfp4_plan)
+            for kind in (GGML_F32, GGML_F16, GGML_Q8_0, GGML_MXFP4)
+        }
+        self.assertEqual(
+            mxfp4_counts,
+            {GGML_F32: 45, GGML_F16: 2, GGML_Q8_0: 25, GGML_MXFP4: 9},
+        )
+        q2_k_counts = {
+            kind: sum(tensor.ggml_type == kind for tensor in q2_k_plan)
+            for kind in (GGML_F32, GGML_F16, GGML_Q8_0, GGML_Q2_K)
+        }
+        self.assertEqual(
+            q2_k_counts,
+            {GGML_F32: 45, GGML_F16: 2, GGML_Q8_0: 25, GGML_Q2_K: 9},
+        )
+        self.assertEqual(sum(tensor.byte_len for tensor in mxfp4_plan), 10_897_104_284)
+        self.assertEqual(sum(tensor.byte_len for tensor in q2_k_plan), 6_971_235_740)
+        self.assertEqual(
+            tuple((tensor.out_name, tensor.dims) for tensor in q2_k_plan),
+            tuple((tensor.out_name, tensor.dims) for tensor in mxfp4_plan),
+        )
+        inputs = [
+            name
+            for tensor in mxfp4_plan
+            for name, _dtype, _shape in source_expectations(tensor)
+        ]
+        self.assertEqual(len(inputs), 4_705)
+        self.assertEqual(len(set(inputs)), 4_705)
+        self.assertEqual(mxfp4_plan[0].out_name, "dspark.0.attn_sinks.weight")
+        self.assertEqual(mxfp4_plan[-1].out_name, "dspark.confidence_head.weight")
+
+    def test_0731_metadata_and_recipe_outputs_are_stable(self) -> None:
+        self.assertEqual(ARCHITECTURE, "deepseek_v4_flash_dspark_draft")
+        self.assertEqual(
+            GGUF_METADATA,
+            (
+                ("general.architecture", "string", "deepseek_v4_flash_dspark_draft"),
+                ("general.name", "string", "DeepSeek-V4-Flash-0731-DSpark-Drafter"),
+                (
+                    "general.source.url",
+                    "string",
+                    "https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash-0731",
+                ),
+                (
+                    "general.source.revision",
+                    "string",
+                    "9e165c30e2704aec5d9d593cce3eebd58bbef1cb",
+                ),
+                ("general.license", "string", "MIT"),
+                ("dspark.recipe_version", "u32", 1),
+                ("dspark.block_size", "u32", 5),
+                ("dspark.markov_rank", "u32", 256),
+                ("dspark.noise_token_id", "u32", 128_799),
+                ("dspark.target_layer_ids", "array_i32", (40, 41, 42)),
+                ("dspark.layer_count", "u32", 3),
+            ),
+        )
+        self.assertEqual(
+            MXFP4_Q8_0_RECIPE.output_filename,
+            "DeepSeek-V4-Flash-0731-DSpark-Drafter-MXFP4-Q8_0.gguf",
+        )
+        self.assertEqual(
+            Q2_K_Q8_0_RECIPE.output_filename,
+            "DeepSeek-V4-Flash-0731-DSpark-Drafter-Q2_K-Q8_0.gguf",
+        )
+        self.assertEqual(MXFP4_Q8_0_RECIPE.expected_file_size, 10_897_110_272)
+        self.assertEqual(Q2_K_Q8_0_RECIPE.expected_file_size, 6_971_241_728)
+        self.assertEqual(
+            Q2_K_Q8_0_RECIPE.expected_file_size
+            - Q2_K_Q8_0_RECIPE.expected_tensor_bytes,
+            MXFP4_Q8_0_RECIPE.expected_file_size
+            - MXFP4_Q8_0_RECIPE.expected_tensor_bytes,
+        )
+        self.assertEqual(MXFP4_Q8_0_RECIPE.manifest_filename("build"), "build.json")
+        self.assertEqual(
+            Q2_K_Q8_0_RECIPE.manifest_filename("build"),
+            "build-q2_k-q8_0.json",
+        )
+
+    def test_e4m3_known_values(self) -> None:
+        self.assertEqual(float(E4M3_TABLE[0x00]), 0.0)
+        self.assertEqual(float(E4M3_TABLE[0x01]), 2**-9)
+        self.assertEqual(float(E4M3_TABLE[0x38]), 1.0)
+        self.assertEqual(float(E4M3_TABLE[0x40]), 2.0)
+        self.assertEqual(float(E4M3_TABLE[0xB8]), -1.0)
+        self.assertTrue(np.isnan(E4M3_TABLE[0x7F]))
+
+    def test_q8_rounds_half_away_from_zero(self) -> None:
+        values = np.zeros(32, dtype=np.float32)
+        values[:5] = [127.0, 0.5, 1.5, -0.5, -1.5]
+        encoded = quantize_q8_0(values)
+        scale = encoded[0, :2].copy().view("<f2")[0]
+        codes = encoded[0, 2:].view(np.int8)
+        self.assertEqual(float(scale), 1.0)
+        np.testing.assert_array_equal(codes[:5], [127, 1, 2, -1, -2])
+
+    def test_q8_rounding_does_not_promote_values_below_half(self) -> None:
+        below_half = np.nextafter(np.float32(0.5), np.float32(0.0), dtype=np.float32)
+        values = np.array(
+            [below_half, -below_half, np.float32(0.5), np.float32(-0.5)],
+            dtype=np.float32,
+        )
+        np.testing.assert_array_equal(
+            round_away_from_zero(values),
+            np.array([0.0, -0.0, 1.0, -1.0], dtype=np.float32),
+        )
+
+    def test_mxfp4_low16_high16_layout_and_nan_rejection(self) -> None:
+        codes = np.arange(32, dtype=np.uint8) & np.uint8(0x0F)
+        packed = codes[0::2] | (codes[1::2] << np.uint8(4))
+        encoded = repack_mxfp4(packed, np.array([127], dtype=np.uint8), 1, 32)
+        self.assertEqual(int(encoded[0, 0, 0]), 127)
+        expected = codes[:16] | (codes[16:] << np.uint8(4))
+        np.testing.assert_array_equal(encoded[0, 0, 1:], expected)
+        with self.assertRaisesRegex(ValueError, "0xff"):
+            repack_mxfp4(packed, np.array([0xFF], dtype=np.uint8), 1, 32)
+
+    def test_q2_k_matches_ds4_reference_block_and_decodes_independently(self) -> None:
+        values = np.empty((1, 256), dtype=np.float32)
+        for index in range(256):
+            raw = ((index * 37) % 31) - 15
+            multiplier = 1 << ((index // 16) % 4)
+            values[0, index] = (
+                np.float32(0.0)
+                if index % 19 == 0
+                else np.float32(raw) * np.float32(multiplier) * np.float32(0.125)
+            )
+        expected = bytes.fromhex(
+            "123357ee124467fe124357ef124467ff"
+            "9194e9294e8294e4294e8294d4294e42"
+            "e4e9ba4e93a4e93a4e9b94e5394e53a4"
+            "4e8294e4694d8294e4294e4690d4294d9"
+            "3a4e53a4f5394a53a4f5394e5fa7b5fe038193c"
+        )
+        encoded = quantize_q2_k(values)
+        self.assertEqual(encoded.tobytes(), expected)
+        self.assertEqual(encoded[0, :16].tobytes(), expected[:16])
+        decoded = decode_q2_k_blocks(encoded)
+        relative_error = np.max(np.abs(values - decoded)) / np.max(np.abs(values))
+        self.assertLess(float(relative_error), Q2_K_Q8_0_RECIPE.q2_k_error_limit)
+
+        batched = quantize_q2_k(np.concatenate((values, -values), axis=0))
+        separate = np.concatenate(
+            (quantize_q2_k(values), quantize_q2_k(-values)), axis=0
+        )
+        np.testing.assert_array_equal(batched, separate)
+
+    def test_threaded_q2_experts_are_written_in_canonical_order(self) -> None:
+        rows = 1
+        cols = 256
+
+        def source_arrays(expert: int) -> tuple[np.ndarray, np.ndarray]:
+            codes = (np.arange(cols, dtype=np.uint16) + expert * 3).astype(np.uint8)
+            codes &= np.uint8(0x0F)
+            packed = codes[0::2] | (codes[1::2] << np.uint8(4))
+            scales = np.full(cols // 32, 127 + expert, dtype=np.uint8)
+            return packed, scales
+
+        class DelayedSource:
+            def array(self, name: str, _dtype: object) -> np.ndarray:
+                expert = int(name.split(".experts.", 1)[1].split(".", 1)[0])
+                packed, scales = source_arrays(expert)
+                if name.endswith(".weight"):
+                    # Later experts finish first, exercising ordered futures.
+                    time.sleep(0.01 * (3 - expert))
+                    return packed
+                return scales
+
+        tensor = TensorRecipe(
+            out_name="dspark.test.ffn_gate_exps.weight",
+            kind=convert_module.KIND_FUSED_EXPERTS_Q2_K,
+            dims=(cols, rows, 4),
+            ggml_type=GGML_Q2_K,
+            rows=rows,
+            cols=cols,
+            name_prefix="mtp.blocks.40",
+            expert_kind="w1",
+        )
+        output = io.BytesIO()
+        with (
+            mock.patch.object(convert_module, "N_EXPERTS", 4),
+            mock.patch.object(convert_module, "Q2_K_EXPERT_WORKERS", 4),
+        ):
+            written = TensorProducer(DelayedSource())._fused_experts_q2_k(
+                tensor, output
+            )
+
+        expected = bytearray()
+        for expert in range(4):
+            packed, scales = source_arrays(expert)
+            decoded = decode_source_mxfp4(packed, scales, rows, cols)
+            expected.extend(quantize_q2_k(decoded).tobytes(order="C"))
+        self.assertEqual(written, 4 * 84)
+        self.assertEqual(output.getvalue(), bytes(expected))
+
+    def test_sha256sums_update_preserves_other_recipe(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "SHA256SUMS"
+            legacy_digest = "1" * 64
+            q2_digest = "2" * 64
+            _update_sha256sums(path, legacy_digest, "legacy.gguf")
+            _update_sha256sums(path, q2_digest, "q2.gguf")
+            self.assertEqual(
+                path.read_text(encoding="ascii"),
+                f"{legacy_digest}  legacy.gguf\n{q2_digest}  q2.gguf\n",
+            )
+
+    def test_tiny_gguf_round_trip(self) -> None:
+        tensor = TensorRecipe(
+            out_name="dspark.test.weight",
+            kind=KIND_PLAIN_F32,
+            dims=(4,),
+            ggml_type=GGML_F32,
+            src_name="mtp.test",
+            src_shape=(4,),
+        )
+        data = struct.pack("<4f", 1.0, 2.0, 3.0, 4.0)
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "tiny.gguf"
+
+            def produce(_tensor: TensorRecipe, handle: object) -> int:
+                return handle.write(data)
+
+            write_gguf(path, (tensor,), produce)
+            with GgufReader(path) as reader:
+                self.assertEqual(reader.tensors[0].name, tensor.out_name)
+                self.assertEqual(reader.tensors[0].dims, tensor.dims)
+                self.assertEqual(reader.tensors[0].ggml_type, GGML_F32)
+                observed = reader.tensor_array(reader.tensors[0], "<f4").copy()
+            np.testing.assert_array_equal(observed, [1.0, 2.0, 3.0, 4.0])
+            self.assertEqual(path.stat().st_size % 32, 0)
+
+    def test_safetensors_rejects_bad_offsets(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "bad.safetensors"
+            header = {
+                "mtp.bad": {
+                    "dtype": "F32",
+                    "shape": [1],
+                    "data_offsets": [0, 8],
+                }
+            }
+            encoded = json.dumps(header, separators=(",", ":")).encode()
+            path.write_bytes(struct.pack("<Q", len(encoded)) + encoded + b"\0" * 4)
+            with self.assertRaisesRegex(ValueError, "overruns|needs"):
+                SafeTensorSet([path])
+
+
+if __name__ == "__main__":
+    unittest.main()