From e85124db50c15d8adbab48b5c90e10b6593fe85b Mon Sep 17 00:00:00 2001
From: bong-water-water-bong <bong-water-water-bong@1bit.gg>
Date: Tue, 10 Nov 2026 16:27:56 -0400
Subject: [PATCH] npu-pack: a qwen35 GGUF is packed by an in-tree converter,
 and the GGUF converter refuses what it cannot name (Fixes #2013)

tools/qwen35_to_q4nx.py is the converter the dev box's 27B container names in
its own metadata; it lived only in a lane worktree. It now refuses a rotated
(prism.hadamard.*) or PTQ1_0 input before writing, and its verify compares the
conv1d value-band direction on bf16-rounded sums.

tools/gguf_to_q4nx.py lists every tensor kind it has no name for in one
refusal (a suffix-less blk.N.ssm_a was a ValueError), names the architecture
and the converter that does pack it, refuses an unknown ggml tensor type by
number instead of an enum traceback, and leaves no empty output directory.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
---
 CMakeLists.txt               |   5 +
 docs/npu.md                  |  30 ++
 tests/gguf_to_q4nx_test.py   |  78 +++++
 tests/qwen35_to_q4nx_test.py | 213 +++++++++++++
 tools/gguf_to_q4nx.py        |  74 ++++-
 tools/qwen35_to_q4nx.py      | 576 +++++++++++++++++++++++++++++++++++
 6 files changed, 971 insertions(+), 5 deletions(-)
 create mode 100755 tests/qwen35_to_q4nx_test.py
 create mode 100755 tools/qwen35_to_q4nx.py

diff --git a/CMakeLists.txt b/CMakeLists.txt
index f2af8544f..84763a7df 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -322,6 +322,11 @@ add_python_test(tool_selftest_whisper_encoder_baseline ${CMAKE_SOURCE_DIR}/tools
 # engine#1780: the DFlash draft package's gate before a loader -- tile-grid sizes from the config, tile-header sanity and
 # the container's scalars against config.json, on a synthetic package with eight negative controls. Stdlib only.
 add_python_test(tool_selftest_dflash_draft_info ${CMAKE_SOURCE_DIR}/tools/dflash_draft_info.py --selftest)
+# engine#2013: the qwen35 (gated linear attention) GGUF -> Q4NX converter. Its own selftest (tile round-trips, the
+# value-head permutation), and a pack + verify of a small qwen35 GGUF the test writes itself, with the three inputs it
+# has to refuse. numpy only: no gguf package, no model, no device.
+add_python_test(tool_selftest_qwen35_to_q4nx ${CMAKE_SOURCE_DIR}/tools/qwen35_to_q4nx.py selftest)
+add_python_test(qwen35_to_q4nx ${CMAKE_SOURCE_DIR}/tests/qwen35_to_q4nx_test.py)
 # engine#1777: the release row's own arm, which merged unregistered -- this sweep is what found it (engine#1820).
 add_test(NAME release_check_hrx_init_reason COMMAND bash ${CMAKE_SOURCE_DIR}/tests/release_check_hrx_init_reason_test.sh ${CMAKE_SOURCE_DIR}/os/mini/release-check.sh)
 # engine#1615: every process holding the GPU/NPU device must belong to a live gpu-hold/npu-hold ticket. Three
diff --git a/docs/npu.md b/docs/npu.md
index 5337e7d9c..4dd77581b 100644
--- a/docs/npu.md
+++ b/docs/npu.md
@@ -784,6 +784,36 @@ weights over the bound. The Q6_K tensors (half of `v_proj` and `down_proj`, and
 0.079. Served on the NPU, the repacked model decoded 24/24 greedy tokens the same as a CPU
 reference of the repacked weights, with every step's logits at cosine 0.99995 or better.
 
+### What the GGUF converter refuses, and the qwen35 converter
+
+`tools/gguf_to_q4nx.py` converts qwen3, qwen3moe and qwen2. Two other inputs are refused before
+anything is written, with no output directory left behind (engine#2013):
+
+- **A GGUF of another architecture.** Every tensor kind without a Q4NX name is listed in one message,
+  with how many tensors of each there are. For `qwen35` the message points at the converter below.
+- **A tensor type the installed `gguf` package does not know.** The refusal gives the number;
+  143 is PTQ1_0, PrismML's ternary type, which `tools/ternary_to_q4_0.py` rewrites as Q4_0.
+
+`tools/qwen35_to_q4nx.py pack <model.gguf> <out dir> [--tokenizer <dir>]` packs a **qwen35** GGUF:
+layers of gated linear attention (GDN) with a full-attention layer every
+`qwen35.full_attention_interval`. It writes the names the forward looks up
+(`linear_attn.qkv_proj`, `self_attn.gate_proj`, `linear_attn.ssm_*`), reorders the 48 value heads
+from the stored order to the grouping the forward expects, and stores `ssm_alpha`/`ssm_beta` as Q8
+tiles padded to 64 rows. It reads the GGUF itself and needs only numpy. `verify <model.gguf>
+<out dir>` checks every tensor of a container against the GGUF, including the direction of the
+value-head reorder.
+
+Its input has to be a plain qwen35 GGUF in Q4_0 or Q4_1. It refuses, by name:
+
+- a file that still carries `prism.hadamard.*` keys: the weights are in a rotated basis, the tool
+  writes no sign table, and the container would load and answer wrongly;
+- PTQ1_0 tensors (ggml type 143).
+
+So a PrismML ternary GGUF needs two steps before this one: PTQ1_0 to Q4_0
+(`tools/ternary_to_q4_0.py`, which keeps the rotation) and the un-rotation, which is not in this
+tree. The 27B container on the dev box (`__metadata__.converter = qwen35_to_q4nx.py`) was made from
+an un-rotated Q4_0 GGUF.
+
 ### Routed expert stacks
 
 A MoE GGUF keeps its routed experts as one three-dimensional tensor per projection
diff --git a/tests/gguf_to_q4nx_test.py b/tests/gguf_to_q4nx_test.py
index 7b4cbc036..7eb4bbc6e 100755
--- a/tests/gguf_to_q4nx_test.py
+++ b/tests/gguf_to_q4nx_test.py
@@ -26,6 +26,7 @@
 import hashlib
 import os
 import shutil
+import struct
 import subprocess
 import sys
 import tempfile
@@ -465,6 +466,81 @@ def rope_scaling_check(gguf_path, out, kind, ok):
     return ok and good and not left
 
 
+def other_arch_check(d, rng, ok):
+    """A GGUF of an architecture this converter has no names for (engine#2013).
+
+    The first unnamed tensor used to be the whole message (`no Q4NX name for blk.0.attn_gate.weight`), a
+    suffix-less one (blk.N.ssm_a) was a ValueError, and the empty output directory stayed behind.
+    """
+    tool = os.path.join(HERE, "..", "tools", "gguf_to_q4nx.py")
+    src, out = os.path.join(d, "gdn.gguf"), os.path.join(d, "gdn-out")
+    w = gguf.GGUFWriter(src, "qwen35")
+    w.add_block_count(1)
+    f = lambda *s: rng.standard_normal(s).astype(np.float32)  # noqa: E731
+    w.add_tensor("token_embd.weight", f(512, 256))
+    w.add_tensor("output_norm.weight", f(256))
+    w.add_tensor("blk.0.attn_norm.weight", f(256))
+    w.add_tensor("blk.0.attn_gate.weight", f(256, 256))
+    w.add_tensor("blk.0.ssm_out.weight", f(256, 256))
+    w.add_tensor("blk.0.ssm_a", f(48))
+    w.write_header_to_file()
+    w.write_kv_data_to_file()
+    w.write_tensors_to_file()
+    w.close()
+    checks = []
+    for cmd in ("pack", "verify"):
+        r = subprocess.run([sys.executable, tool, cmd, src, out], capture_output=True, text=True)
+        msg = r.stdout + r.stderr
+        checks += [
+            (f"{cmd}: a qwen35 GGUF exits non-zero without a traceback", r.returncode != 0 and "Traceback" not in msg),
+            (f"{cmd}: ... keeps the first unnamed tensor's name", "no Q4NX name for blk.0.attn_gate.weight" in msg),
+            (f"{cmd}: ... lists every unnamed kind, the suffix-less one too",
+             all(k in msg for k in ("blk.N.attn_gate.weight x1", "blk.N.ssm_out.weight x1", "blk.N.ssm_a x1"))),
+            (f"{cmd}: ... names the architecture and the converter that does pack it",
+             "'qwen35'" in msg and "tools/qwen35_to_q4nx.py" in msg),
+        ]
+        if not all(g for _, g in checks):
+            print(msg[-800:])
+    checks.append(("no output directory was created for it", not os.path.exists(out)))
+    for label, good in checks:
+        print(f"{'ok  ' if good else 'FAIL'} {label}")
+        ok = ok and good
+    return ok
+
+
+def foreign_type_check(good_gguf, d, ok):
+    """A tensor type the gguf package does not know is refused by number, not as an enum ValueError (engine#2013).
+
+    The file is a valid GGUF with one tensor's type field rewritten to 143 (PTQ1_0), which is what a PrismML
+    ternary GGUF looks like to the stock reader.
+    """
+    tool = os.path.join(HERE, "..", "tools", "gguf_to_q4nx.py")
+    src, out = os.path.join(d, "t143.gguf"), os.path.join(d, "t143-out")
+    with open(good_gguf, "rb") as f:
+        raw = bytearray(f.read())
+    name = b"blk.0.attn_q.weight"
+    at = raw.index(name) + len(name) + 4 + 2 * 8      # name, n_dims (u32), two u64 dims, then the type
+    assert struct.unpack_from("<I", raw, at)[0] == int(Q.Q4_0), "the type field is not where the test expects it"
+    struct.pack_into("<I", raw, at, 143)
+    with open(src, "wb") as f:
+        f.write(raw)
+    checks = []
+    for cmd in ("pack", "verify"):
+        r = subprocess.run([sys.executable, tool, cmd, src, out], capture_output=True, text=True)
+        msg = r.stdout + r.stderr
+        checks += [
+            (f"{cmd}: ggml type 143 exits non-zero without a traceback", r.returncode != 0 and "Traceback" not in msg),
+            (f"{cmd}: ... names the number and what it is", "quantisation type 143" in msg and "PTQ1_0" in msg),
+        ]
+        if not all(g for _, g in checks):
+            print(msg[-800:])
+    checks.append(("no output directory was created for it", not os.path.exists(out)))
+    for label, good in checks:
+        print(f"{'ok  ' if good else 'FAIL'} {label}")
+        ok = ok and good
+    return ok
+
+
 def main():
     ok = golden_tile()
     ok = golden_tile8() and ok
@@ -509,6 +585,8 @@ def main():
                 print(f"FAIL moe-q8 {cmd[0]} exited {r.returncode}")
                 ok = False
         ok = moe_check(os.path.join(d, "tiny-moe.gguf"), mq8, ok)
+        ok = other_arch_check(d, rng, ok)
+        ok = foreign_type_check(src, d, ok)
         dense_3d_gguf(os.path.join(d, "dense3d.gguf"), rng)
         ok = dense_3d_pack_check(os.path.join(d, "dense3d.gguf"), os.path.join(d, "dense3d"), ok)
         ok = tokenizer_flags_check(src, out, ok)
diff --git a/tests/qwen35_to_q4nx_test.py b/tests/qwen35_to_q4nx_test.py
new file mode 100755
index 000000000..1f2dbcbbf
--- /dev/null
+++ b/tests/qwen35_to_q4nx_test.py
@@ -0,0 +1,213 @@
+#!/usr/bin/env python3
+# Copyright 2026 bong-water-water-bong
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""tools/qwen35_to_q4nx.py on a small qwen35 GGUF written here (engine#2013).
+
+usage: tests/qwen35_to_q4nx_test.py        (needs numpy; no gguf package, no model, no device)
+
+One gated-linear-attention layer and one full-attention layer, at the 16 key groups and 48 value
+heads the tool is written for and a hidden size of 256, so the file is a few megabytes.  Checks:
+
+  * pack, then verify: every tensor of both layer families comes back, 0 bad tensors;
+  * the container has the names the forward looks up, and config.json the layer types;
+  * verify notices a container packed in the stored (not reordered) v-head order;
+  * the three inputs that would give a wrong container are refused by name and leave no
+    output directory: another architecture, a file that still carries prism.hadamard.* keys,
+    and a projection stored as PTQ1_0 (ggml type 143).
+"""
+import json
+import os
+import struct
+import subprocess
+import sys
+import tempfile
+
+import numpy as np
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+TOOL = os.path.join(HERE, "..", "tools", "qwen35_to_q4nx.py")
+
+F32, Q4_0, PTQ1_0 = 0, 2, 143
+U32, F32V, STR = 4, 6, 8
+H, IM, V = 256, 512, 512            # hidden, feed-forward, vocabulary
+HD_G, NKH, NVH = 128, 16, 48        # GDN head dim, key groups, value heads (the tool's constants)
+HD_A, NH, NKV = 128, 2, 1           # attention head dim, heads, kv heads
+
+
+def gstr(s):
+    b = s.encode()
+    return struct.pack("<Q", len(b)) + b
+
+
+def write_gguf(path, kv, tensors):
+    """GGUF v3: kv is [(key, type, value)], tensors is [(name, ggml dims, type, bytes)]."""
+    head = struct.pack("<IIQQ", 0x46554747, 3, len(tensors), len(kv))
+    for k, t, v in kv:
+        head += gstr(k) + struct.pack("<I", t)
+        head += gstr(v) if t == STR else struct.pack("<I" if t == U32 else "<f", v)
+    off, infos, blobs = 0, b"", []
+    for name, dims, tt, data in tensors:
+        infos += gstr(name) + struct.pack("<I", len(dims)) + struct.pack("<%dQ" % len(dims), *dims)
+        infos += struct.pack("<IQ", tt, off)
+        pad = (-len(data)) % 32
+        blobs.append(data + b"\0" * pad)
+        off += len(data) + pad
+    body = head + infos
+    body += b"\0" * ((-len(body)) % 32)
+    with open(path, "wb") as f:
+        f.write(body)
+        for b in blobs:
+            f.write(b)
+
+
+def model(rng, arch="qwen35", extra_kv=(), qkv_type=Q4_0):
+    kv = [("general.architecture", STR, arch),
+          ("qwen35.block_count", U32, 2), ("qwen35.full_attention_interval", U32, 2),
+          ("qwen35.embedding_length", U32, H), ("qwen35.feed_forward_length", U32, IM),
+          ("qwen35.attention.head_count", U32, NH), ("qwen35.attention.head_count_kv", U32, NKV),
+          ("qwen35.attention.key_length", U32, HD_A), ("qwen35.context_length", U32, 4096),
+          ("qwen35.attention.layer_norm_rms_epsilon", F32V, 1e-6), ("qwen35.rope.freq_base", F32V, 1e7),
+          ("qwen35.ssm.state_size", U32, HD_G), ("qwen35.ssm.inner_size", U32, NVH * HD_G),
+          ("qwen35.ssm.group_count", U32, NKH), ("qwen35.ssm.conv_kernel", U32, 4),
+          ("tokenizer.ggml.bos_token_id", U32, 2), ("tokenizer.ggml.eos_token_id", U32, 1)]
+    kv += list(extra_kv)
+    out = []
+
+    def q4(name, K, N, tt=Q4_0):
+        # 32 weights per block: an fp16 scale, then 16 bytes of nibbles
+        blocks = np.zeros((N * K // 32, 18), np.uint8)
+        blocks[:, 0:2] = rng.uniform(0.01, 0.05, N * K // 32).astype("<f2").view(np.uint8).reshape(-1, 2)
+        blocks[:, 2:] = rng.integers(0, 256, (N * K // 32, 16), dtype=np.uint8)
+        data = blocks.tobytes()
+        if tt == PTQ1_0:      # 28 bytes per 128 weights; the bytes are never decoded, only refused
+            data = bytes(N * K // 128 * 28)
+        out.append((name, (K, N), tt, data))
+
+    def f32(name, *dims):
+        out.append((name, dims, F32, rng.standard_normal(int(np.prod(dims))).astype("<f4").tobytes()))
+
+    cd = (2 * NKH + NVH) * HD_G                      # q | k | v rows of the fused projection
+    q4("token_embd.weight", H, V)
+    f32("output_norm.weight", H)
+    # layer 0: gated linear attention
+    q4("blk.0.attn_qkv.weight", H, cd, qkv_type)
+    q4("blk.0.attn_gate.weight", H, NVH * HD_G)
+    q4("blk.0.ssm_out.weight", NVH * HD_G, H)
+    f32("blk.0.ssm_alpha.weight", H, NVH)
+    f32("blk.0.ssm_beta.weight", H, NVH)
+    f32("blk.0.ssm_conv1d.weight", 4, cd)
+    f32("blk.0.ssm_norm.weight", HD_G)
+    f32("blk.0.ssm_a", NVH)
+    f32("blk.0.ssm_dt.bias", NVH)
+    # layer 1: full attention, q stored per head as [q | gate]
+    q4("blk.1.attn_q.weight", H, 2 * NH * HD_A)
+    q4("blk.1.attn_k.weight", H, NKV * HD_A)
+    q4("blk.1.attn_v.weight", H, NKV * HD_A)
+    q4("blk.1.attn_output.weight", NH * HD_A, H)
+    f32("blk.1.attn_q_norm.weight", HD_A)
+    f32("blk.1.attn_k_norm.weight", HD_A)
+    for l in (0, 1):
+        f32(f"blk.{l}.attn_norm.weight", H)
+        f32(f"blk.{l}.post_attention_norm.weight", H)
+        q4(f"blk.{l}.ffn_gate.weight", H, IM)
+        q4(f"blk.{l}.ffn_up.weight", H, IM)
+        q4(f"blk.{l}.ffn_down.weight", IM, H)
+    return kv, out
+
+
+def run(*args):
+    r = subprocess.run([sys.executable, TOOL, *args], capture_output=True, text=True)
+    return r.returncode, r.stdout + r.stderr
+
+
+def main():
+    rng = np.random.default_rng(7)
+    fails = 0
+
+    def check(good, label, detail=""):
+        nonlocal fails
+        print(f"{'ok  ' if good else 'FAIL'} {label}")
+        if not good:
+            fails += 1
+            if detail:
+                print(detail[-1200:])
+
+    with tempfile.TemporaryDirectory() as d:
+        src, out = os.path.join(d, "tiny.gguf"), os.path.join(d, "q4nx")
+        with open(os.path.join(d, "tokenizer.json"), "w") as f:
+            f.write("{}")
+        write_gguf(src, *model(rng))
+
+        rc, log = run("pack", src, out)
+        check(rc == 0, "pack exits 0", log)
+        rc, log = run("verify", src, out)
+        check(rc == 0 and "0 bad tensors" in log, "verify: 0 bad tensors", log)
+
+        with open(os.path.join(out, "model.q4nx"), "rb") as f:
+            n = struct.unpack("<Q", f.read(8))[0]
+            table = json.loads(f.read(n))
+        want = {
+            "model.layers.0.linear_attn.qkv_proj.weight": [(2 * NKH + NVH) * HD_G // 32 * (H // 256), 5120],
+            "model.layers.0.self_attn.gate_proj.weight": [NVH * HD_G // 32 * (H // 256), 5120],
+            "model.layers.0.linear_attn.ssm_out_proj.weight": [H // 32 * (NVH * HD_G // 256), 5120],
+            "model.layers.0.linear_attn.ssm_alpha_proj.weight": [2, 1, 8704],     # 48 rows padded to 64
+            "model.layers.0.linear_attn.ssm_beta_proj.weight": [2, 1, 8704],
+            "model.layers.0.linear_attn.ssm_conv1d.weight": [4 * (2 * NKH + NVH) * HD_G],
+            "model.layers.0.linear_attn.ssm_norm.weight": [HD_G],
+            "model.layers.0.linear_attn.ssm_a": [NVH],
+            "model.layers.0.linear_attn.ssm_dt.bias": [NVH],
+            "model.layers.1.self_attn.q_proj.weight": [2 * NH * HD_A // 32 * (H // 256), 5120],
+            "model.layers.1.self_attn.q_norm.weight": [HD_A],
+            "model.layers.1.post_attention_layernorm.weight": [H],
+            "model.embed_tokens.weight": [V // 32 * (H // 256), 5120],
+            "model.norm.weight": [H],
+        }
+        for name, shape in want.items():
+            got = table.get(name, {}).get("shape")
+            check(got == shape, f"{name} is in the container with shape {shape}", f"got {got}")
+        check("lm_head.weight" not in table, "no lm_head tensor for a GGUF without output.weight")
+        check(table.get("__metadata__", {}).get("converter") == "qwen35_to_q4nx.py",
+              "the container names its converter")
+        with open(os.path.join(out, "config.json")) as f:
+            cfg = json.load(f)
+        check(cfg.get("layer_types") == ["linear_attention", "full_attention"], "config.json: layer_types")
+        check(cfg.get("model_type") == "qwen3_5" and cfg.get("linear_num_value_heads") == NVH
+              and cfg.get("tie_word_embeddings") is True, "config.json: model_type, value heads, tied head")
+        check(os.path.exists(os.path.join(out, "tokenizer.json")), "tokenizer.json is copied from the GGUF's directory")
+
+        # verify has to notice the one thing a wrong pack gets wrong silently: the v-head order
+        stored = os.path.join(d, "stored")
+        rc, log = run("pack", src, stored, "--no-reorder")
+        check(rc == 0, "pack --no-reorder exits 0", log)
+        rc, log = run("verify", src, stored)
+        check(rc != 0 and "BAD" in log, "verify fails a container packed in the stored v-head order", log)
+
+        def refused(label, needle, **kw):
+            p, o = os.path.join(d, label + ".gguf"), os.path.join(d, label + "-out")
+            write_gguf(p, *model(rng, **kw))
+            rc, log = run("pack", p, o)
+            check(rc != 0 and needle in log and "Traceback" not in log, f"{label}: refused, naming {needle!r}", log)
+            check(not os.path.exists(o), f"{label}: no output directory is left")
+
+        refused("other-arch", "general.architecture is 'qwen3'", arch="qwen3")
+        refused("rotated", "prism.hadamard.axis", extra_kv=[("prism.hadamard.axis", U32, 1)])
+        refused("ternary", "ggml type 143", qkv_type=PTQ1_0)
+
+    print("FAILED" if fails else "qwen35_to_q4nx: ok")
+    return 1 if fails else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/tools/gguf_to_q4nx.py b/tools/gguf_to_q4nx.py
index 6d8ab1a0c..52b5a6175 100755
--- a/tools/gguf_to_q4nx.py
+++ b/tools/gguf_to_q4nx.py
@@ -55,6 +55,11 @@
 projection; Qwen3-30B-A3B has none.
 
 Supported architectures: qwen3, qwen3moe and qwen2. Needs numpy and gguf (gguf-py).
+
+A GGUF of another architecture is refused before anything is written, with every tensor kind that
+has no Q4NX name in one message; qwen35 (gated linear attention) is tools/qwen35_to_q4nx.py's. A
+tensor type the installed gguf package does not know (PTQ1_0 is ggml type 143) is refused by
+number (engine#2013).
 """
 import argparse
 import json
@@ -158,15 +163,72 @@ def to_q4_1(t):
 def hf_name(name):
     base, _, suffix = name.rpartition(".")
     if base.startswith("blk."):
-        _, L, part = base.split(".", 2)
-        if part not in LAYER:
+        bits = base.split(".", 2)
+        # blk.N.ssm_a has no suffix, so its base is "blk.N": that is an unnamed tensor too, not a crash
+        if len(bits) < 3 or bits[2] not in LAYER:
             raise SystemExit(f"no Q4NX name for {name}")
-        return f"model.layers.{L}.{LAYER[part]}.{suffix}"
+        return f"model.layers.{bits[1]}.{LAYER[bits[2]]}.{suffix}"
     if base not in TOP:
         raise SystemExit(f"no Q4NX name for {name}")
     return f"{TOP[base]}.{suffix}"
 
 
+# Where a GGUF this converter cannot name goes instead.
+OTHER_CONVERTER = {
+    "qwen35": "tools/qwen35_to_q4nx.py packs a qwen35 GGUF (gated linear attention layers)",
+}
+# ggml tensor types the gguf package may not know, by number.
+FOREIGN_TYPES = {
+    143: "PTQ1_0, PrismML's ternary type; tools/ternary_to_q4_0.py rewrites it as Q4_0",
+}
+
+
+def open_gguf(path):
+    """gguf.GGUFReader, with an unknown tensor type refused by number instead of an enum ValueError.
+
+    The reader turns every tensor's type into gguf.GGMLQuantizationType while it parses the table, so a type the
+    installed package does not know ends the run in `ValueError: np.uint32(143) is not a valid
+    GGMLQuantizationType` and a traceback (engine#2013). It is the file's type this converter cannot read, and
+    that is what the message has to say.
+    """
+    try:
+        return gguf.GGUFReader(path)
+    except ValueError as e:
+        m = re.search(r"(\d+)\)? is not a valid GGMLQuantizationType", str(e))
+        if not m:
+            raise
+        n = int(m.group(1))
+        known = FOREIGN_TYPES.get(n)
+        raise SystemExit(
+            f"{path}: a tensor has ggml quantisation type {n}, which the installed gguf package cannot read"
+            + (f" ({known})" if known else "") + "; nothing was converted") from None
+
+
+def refuse_unnamed(r):
+    """Every tensor kind with no Q4NX name, in one refusal, before anything is written (engine#2013).
+
+    hf_name() stops at the first one, which on a GGUF of another architecture is blk.0's first unknown part: the
+    message then reads like one missing table row when the whole layer family is missing.
+    """
+    kinds = {}
+    for t in r.tensors:
+        try:
+            hf_name(t.name)
+        except SystemExit:
+            kind = re.sub(r"^blk\.\d+\.", "blk.N.", t.name)
+            kinds.setdefault(kind, [0, t.name])[0] += 1
+    if not kinds:
+        return
+    first = next(iter(kinds.values()))[1]
+    arch = field(r, "general.architecture")
+    listing = ", ".join(f"{k} x{n}" for k, (n, _) in kinds.items())
+    hint = OTHER_CONVERTER.get(str(arch))
+    raise SystemExit(
+        f"no Q4NX name for {first}: architecture {arch!r} has {len(kinds)} tensor kind(s) this converter cannot "
+        f"name ({listing}); it converts qwen3, qwen3moe and qwen2" + (f". {hint}" if hint else "")
+        + "; nothing was written")
+
+
 def field(r, key, default=None):
     f = r.fields.get(key)
     return default if f is None else f.contents()
@@ -373,7 +435,8 @@ def moe_meta(r, items, table):
 
 
 def pack(args):
-    r = gguf.GGUFReader(args.gguf)
+    r = open_gguf(args.gguf)
+    refuse_unnamed(r)            # before the output directory exists: no empty directory left behind
     refuse_unsupported_rope(r)   # before the output directory exists: no half-written container
     os.makedirs(args.out, exist_ok=True)
     items = planned(r)
@@ -460,7 +523,8 @@ def pack(args):
 
 def verify(args):
     """Every Q4NX tensor against the GGUF, dequantized."""
-    r = gguf.GGUFReader(args.gguf)
+    r = open_gguf(args.gguf)
+    refuse_unnamed(r)
     with open(os.path.join(args.out, "model.q4nx"), "rb") as f:
         n = struct.unpack("<Q", f.read(8))[0]
         hdr = json.loads(f.read(n))
diff --git a/tools/qwen35_to_q4nx.py b/tools/qwen35_to_q4nx.py
new file mode 100755
index 000000000..b872482e4
--- /dev/null
+++ b/tools/qwen35_to_q4nx.py
@@ -0,0 +1,576 @@
+#!/usr/bin/env python3
+# Copyright 2026 bong-water-water-bong
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""qwen35_to_q4nx.py -- GGUF (qwen35, un-rotated) -> Q4NX model dir for the NPU forward.
+
+Takes a plain qwen35 GGUF stored as Q4_0 or Q4_1 and writes the Q4NX directory the NPU forward
+reads (npu/q4nx.h). `tools/gguf_to_q4nx.py` covers qwen3, qwen3moe and qwen2 only: no GDN
+(linear attention) families, no v-head reorder, no Q8/F32 kinds.  This adds exactly those for
+arch qwen35, and gguf_to_q4nx.py refuses a qwen35 GGUF by pointing here (engine#2013).
+
+Two inputs are refused before anything is written:
+  * a GGUF that still carries prism.hadamard.* keys: its weights are stored in a
+    Walsh-Hadamard-rotated basis, this tool writes weights as they are and no sign table, so
+    the container would load and answer wrongly.  It has to be un-rotated first.
+  * a tensor that is not Q4_0/Q4_1 where tiles are needed (PTQ1_0, ggml type 143, is the usual
+    one): tools/ternary_to_q4_0.py rewrites PTQ1_0 as Q4_0 but keeps the rotation, so a
+    PrismML ternary file needs both steps.
+The 27B container on the dev box was made by this tool from an un-rotated Q4_0 GGUF; the
+un-rotation step itself is not in this tree.
+
+Writes, matching the forward's own readers (npu/forward/src/q4nx_forward.cpp):
+
+  q4_1 tiles [tiles, 5120]   every 2-D projection, the embedding and lm_head.  Q4_0/Q4_1
+                             convert exactly: codes kept, scale/zero to bf16.
+  Q8 tiles   [rt, kt, 8704]  ssm_alpha/beta, row-padded 48 -> 64 because the forward's
+                             deq_pad dequantises at the padded height (40 tiles x 8704 B).
+  F32        [n]             ssm_a, ssm_dt.bias (the forward memcpy's these raw).
+  BF16       [n]             every RMSNorm, ssm_norm, and ssm_conv1d transposed to [CK][CD].
+
+The v-head reorder is the H2 container's, measured against the FLM reference container
+(ssm_a cos 1.000000 interleaved vs 0.456755 identity): 48 v-heads are stored rep-major
+(`i = rep*16 + kh`) and the forward wants HF grouping (`j = kh*3 + rep`; it repeats q/k per
+v-head as `src = h / rep`), so HF head j takes stored head `perm[j] = (j%3)*16 + j//3`.
+Applied to the 48-head axis of the GDN families (head-blocks of 128 for qkv v-rows,
+gate_proj rows, conv1d v-channels, ssm_out columns; whole rows for ssm_alpha/beta; scalars
+for ssm_a/ssm_dt) and, on full-attention layers, to the per-head `[q|gate]` interleave of
+attn_q (`(h, p, d) -> (p, h, d)`, p = 2, d = head_dim).
+
+usage: qwen35_to_q4nx.py pack   <model.gguf> <out dir> [--tokenizer <dir>] [--no-reorder]
+       qwen35_to_q4nx.py verify <model.gguf> <out dir>
+"""
+import argparse
+import json
+import mmap
+import os
+import shutil
+import struct
+import sys
+
+import numpy as np
+
+ROWS, COLS, GROUP = 32, 256, 32
+F32, F16, Q4_0, Q4_1, BF16, PTQ1 = 0, 1, 2, 3, 30, 143
+BLK = {F32: (4, 1), F16: (2, 1), Q4_0: (18, 32), Q4_1: (20, 32), BF16: (2, 1), PTQ1: (28, 128)}
+NKH, NVH = 16, 48                  # k-groups, v-heads (qwen35 27B: group_count 16, inner 6144 / 128)
+
+
+# --- GGUF reader --------------------------------------------------------------------------
+class Gguf:
+    """Tensor table, an mmap, and per-type readers for the four types this model uses."""
+
+    _SZ = {0: 1, 1: 1, 2: 2, 3: 2, 4: 4, 5: 4, 6: 4, 7: 1, 8: 0, 9: 0, 10: 8, 11: 8, 12: 8}
+    _FMT = {0: "B", 1: "b", 2: "H", 3: "h", 4: "I", 5: "i", 6: "f", 7: "B", 10: "Q", 11: "q", 12: "d"}
+
+    def __init__(self, path):
+        self.path = path
+        self.f = open(path, "rb")
+        magic, _ = struct.unpack("<II", self.f.read(8))
+        if magic != 0x46554747:
+            raise SystemExit(f"{path}: not a GGUF")
+        n_t, n_kv = struct.unpack("<QQ", self.f.read(16))
+        self.kv = {}
+        for _ in range(n_kv):
+            k = self._str()
+            (t,) = struct.unpack("<I", self.f.read(4))
+            self.kv[k] = self._val(t)
+        self.tensors = {}
+        for _ in range(n_t):
+            name = self._str()
+            (nd,) = struct.unpack("<I", self.f.read(4))
+            dims = struct.unpack("<%dQ" % nd, self.f.read(8 * nd))
+            (tt,) = struct.unpack("<I", self.f.read(4))
+            (off,) = struct.unpack("<Q", self.f.read(8))
+            self.tensors[name] = (dims, tt, off)
+        pos = self.f.tell()
+        self.base = pos + (-pos) % int(self.kv.get("general.alignment", 32))
+        self.mm = mmap.mmap(self.f.fileno(), 0, access=mmap.ACCESS_READ)
+
+    def _str(self):
+        (n,) = struct.unpack("<Q", self.f.read(8))
+        return self.f.read(n).decode("utf-8", "replace")
+
+    def _val(self, t):
+        if t == 8:
+            return self._str()
+        if t == 9:
+            at, n = struct.unpack("<IQ", self.f.read(12))
+            return [self._val(at) for _ in range(n)]
+        return struct.unpack("<" + self._FMT[t], self.f.read(self._SZ[t]))[0]
+
+    def raw(self, name):
+        dims, tt, off = self.tensors[name]
+        sz, per = BLK[tt]
+        n = int(np.prod(dims))
+        return np.frombuffer(self.mm, np.uint8, count=(n // per) * sz, offset=self.base + off), dims, tt
+
+    def f32(self, name):
+        a, _, tt = self.raw(name)
+        if tt == F32:
+            return np.frombuffer(a.tobytes(), "<f4")
+        if tt == BF16:
+            return from_bf16(np.frombuffer(a.tobytes(), "<u2"))
+        raise SystemExit(f"{name}: type {tt}, expected f32/bf16")
+
+    def q4(self, name):
+        """-> codes [N, K] u8, scale [N, K/32] f32, zero [N, K/32] f32, exact for Q4_0/Q4_1."""
+        a, dims, tt = self.raw(name)
+        if tt not in (Q4_0, Q4_1):
+            raise SystemExit(f"{name}: ggml type {tt}, expected Q4_0 (2) or Q4_1 (3)"
+                             + ("; 143 is PTQ1_0: rewrite it as Q4_0 (tools/ternary_to_q4_0.py) and un-rotate it "
+                                "first" if tt == PTQ1 else ""))
+        K, N = int(dims[0]), int(dims[1])
+        b = a.reshape(N, K // 32, 18 if tt == Q4_0 else 20)
+        f16 = lambda x: np.frombuffer(x.tobytes(), "<f2").reshape(N, K // 32).astype(np.float32)  # noqa: E731
+        d = f16(b[:, :, 0:2])
+        if tt == Q4_0:
+            m, q = -8.0 * d, b[:, :, 2:18]
+        else:
+            m, q = f16(b[:, :, 2:4]), b[:, :, 4:20]
+        return np.ascontiguousarray(np.concatenate([q & 0xF, q >> 4], axis=-1).reshape(N, K)), d, m
+
+
+# --- reorders ---------------------------------------------------------------------------------
+def head_perm():
+    """HF v-head j <- stored head (j%3)*16 + j//3."""
+    j = np.arange(NVH)
+    return (j % 3) * NKH + j // 3
+
+
+def perm_rows(n, hd, off):
+    """Row gather for n head-blocks of hd rows starting at row `off` (identity elsewhere)."""
+    p = head_perm()[:n]
+    idx = np.arange(off) if off else np.arange(0)
+    return np.concatenate([idx, np.concatenate([off + b * hd + np.arange(hd) for b in p])])
+
+
+def perm_cols(n, hd, off):
+    """Column gather for n head-blocks of hd columns starting at column `off`."""
+    return np.concatenate([off + b * hd + np.arange(hd) for b in head_perm()[:n]])
+
+
+def deinterleave_qgate(n, hd):
+    """Stored [head][q|gate][hd] -> [all q][all gate]."""
+    nh = n // (2 * hd)
+    out = np.empty(n, np.int64)
+    for h in range(nh):
+        for p in range(2):
+            dst = p * nh * hd + h * hd
+            out[dst:dst + hd] = h * 2 * hd + p * hd + np.arange(hd)
+    return out
+
+
+def row_gather(codes, scale, zero, idx):
+    if idx is None:
+        return codes, scale, zero
+    return codes[idx], scale[idx], zero[idx]
+
+
+def col_gather(codes, scale, zero, hd, off):
+    """Reorder the 48 head-blocks of `hd` columns starting at column `off` (rows kept)."""
+    ci = np.concatenate([off + b * hd + np.arange(hd) for b in head_perm()])
+    gi = np.concatenate([(off + b * hd) // GROUP + np.arange(hd // GROUP) for b in head_perm()])
+    return codes[:, ci], scale[:, gi], zero[:, gi]
+
+
+# --- tiles ------------------------------------------------------------------------------------
+def bf16_bits(x):
+    u = np.asarray(x, dtype=np.float32).view(np.uint32).astype(np.uint64)
+    return ((u + 0x7FFF + ((u >> 16) & 1)) >> 16).astype(np.uint16)
+
+
+def from_bf16(b):
+    return (np.asarray(b, np.uint16).astype(np.uint32) << 16).view(np.float32)
+
+
+def tile_q4_1(codes, scale, zero):
+    N, K = codes.shape
+    RT, KT = N // ROWS, K // COLS
+
+    def plane(v):
+        return bf16_bits(v).reshape(RT, ROWS, KT, 8).transpose(0, 2, 3, 1).reshape(RT * KT, 256)
+
+    c = codes.astype(np.uint8).reshape(RT, 2, 8, 2, KT, 8, 32)
+    packed = (c[:, :, :, 0] | (c[:, :, :, 1] << 4)).transpose(0, 3, 1, 4, 5, 2).reshape(RT * KT, 4096)
+    return np.concatenate([plane(scale).view(np.uint8), plane(zero).view(np.uint8), packed], axis=1)
+
+
+def untile_q4_1(raw, N, K):
+    """[tiles, 5120] -> f32 [N, K] (npu/q4nx.h: w = code*scale + zero)."""
+    RT, KT = N // ROWS, K // COLS
+    t = np.asarray(raw).reshape(RT, KT, 5120)
+    sc = from_bf16(t[..., :512].copy().view("<u2")).reshape(RT, KT, 8, 32)
+    zr = from_bf16(t[..., 512:1024].copy().view("<u2")).reshape(RT, KT, 8, 32)
+    p = t[..., 1024:].reshape(RT, KT, 2, 8, 32, 8)
+    c = np.stack([p & 0xF, p >> 4], axis=-1).transpose(0, 2, 5, 6, 1, 3, 4).reshape(RT, 32, KT, 8, 32)
+    return (c * sc.transpose(0, 3, 1, 2)[..., None] + zr.transpose(0, 3, 1, 2)[..., None]).reshape(N, K)
+
+
+def tile_q8(w):
+    """f32 [N, K] (multiples of 32) -> [N/32, K/256, 8704]; d[g*32+r] @0, int8 codes @512 at k*32+r."""
+    N, K = w.shape
+    RT, KT = N // ROWS, K // COLS
+    out = np.empty((RT, KT, 8704), np.uint8)
+    for rt in range(RT):
+        for kt in range(KT):
+            g = w[rt * ROWS:(rt + 1) * ROWS, kt * COLS:(kt + 1) * COLS].reshape(ROWS, 8, 32)
+            d = from_bf16(bf16_bits(np.abs(g).max(-1) / 127.0))
+            d = np.where(d > 0, d, 1.0)
+            q = np.clip(np.rint(g / d[..., None]), -127, 127).astype(np.int8)
+            out[rt, kt, 0:512] = np.ascontiguousarray(bf16_bits(d).T).view(np.uint8).reshape(-1)
+            out[rt, kt, 512:] = np.ascontiguousarray(q.reshape(ROWS, COLS).T).view(np.uint8).reshape(-1)
+    return out
+
+
+# --- names ------------------------------------------------------------------------------------
+GDN = {"attn_qkv": "linear_attn.qkv_proj", "attn_gate": "self_attn.gate_proj",
+       "ssm_out": "linear_attn.ssm_out_proj",
+       "ssm_alpha": "linear_attn.ssm_alpha_proj", "ssm_beta": "linear_attn.ssm_beta_proj",
+       "ssm_conv1d": "linear_attn.ssm_conv1d", "ssm_norm": "linear_attn.ssm_norm",
+       "ssm_a": "linear_attn.ssm_a", "ssm_dt": "linear_attn.ssm_dt"}
+FULL = {"attn_q": "self_attn.q_proj", "attn_k": "self_attn.k_proj", "attn_v": "self_attn.v_proj",
+        "attn_output": "self_attn.o_proj", "attn_q_norm": "self_attn.q_norm",
+        "attn_k_norm": "self_attn.k_norm"}
+COMMON = {"attn_norm": "input_layernorm", "post_attention_norm": "post_attention_layernorm",
+          "ffn_gate": "mlp.gate_proj", "ffn_up": "mlp.up_proj", "ffn_down": "mlp.down_proj"}
+SUFFIX = {"ssm_a": "", "ssm_dt": ".bias"}
+KIND = {"ssm_a": "f32", "ssm_dt": "f32", "ssm_conv1d": "conv1d", "ssm_alpha": "q8", "ssm_beta": "q8",
+        "ssm_norm": "bf16", "attn_norm": "bf16", "post_attention_norm": "bf16",
+        "attn_q_norm": "bf16", "attn_k_norm": "bf16"}
+
+
+def plan(nl, fai):
+    out = []
+    for l in range(nl):
+        full = (l % fai) == (fai - 1)
+        fam = dict(COMMON)
+        fam.update(FULL if full else GDN)
+        for g, hf in fam.items():
+            src = f"blk.{l}.{g}{SUFFIX.get(g, '.weight')}"
+            # ssm_a / ssm_dt.bias are suffix-less / .bias in the container too (model.c looks
+            # them up by those exact names), so they carry no generic ".weight".
+            dst = f"model.layers.{l}.{hf}" + ("" if g == "ssm_a" else ".bias" if g == "ssm_dt" else ".weight")
+            out.append((src, dst, KIND.get(g, "tiles"), full, g))
+    out.append(("token_embd.weight", "model.embed_tokens.weight", "tiles", True, "emb"))
+    out.append(("output_norm.weight", "model.norm.weight", "bf16", True, "norm"))
+    if "output.weight" in GB.tensors:
+        out.append(("output.weight", "lm_head.weight", "tiles", True, "head"))
+    return [t for t in out if t[0] in GB.tensors]
+
+
+def reorder_idx(g, full, N, hd_g, hd_a):
+    """The row gather for this tensor, or None.  hd_g = the GDN head dim, hd_a = attention's."""
+    if not REORDER:
+        return None
+    if g == "attn_qkv" and not full:                     # [q(16) | k(16) | v(48)]
+        return perm_rows(NVH, hd_g, off=2 * NKH * hd_g)
+    if g == "attn_q" and full:                           # [head][q|gate][hd_a] -> [q|gate]
+        return deinterleave_qgate(N, hd_a)
+    if g == "attn_gate":                                 # z, the GDN swish gate (48 heads)
+        return perm_rows(NVH, hd_g, off=0)
+    return None
+
+
+def config(nl, fai):
+    a = lambda k, d=None: GB.kv.get(f"qwen35.{k}", d)  # noqa: E731
+    s = lambda k, d=0: int(GB.kv.get(f"qwen35.ssm.{k}", d))  # noqa: E731
+    nvh = s("inner_size") // s("state_size")
+    c = {
+        "architectures": ["Qwen3_5ForConditionalGeneration"],
+        "model_type": "qwen3_5",
+        "hidden_size": a("embedding_length"),
+        "intermediate_size": a("feed_forward_length"),
+        "num_hidden_layers": nl,
+        "num_attention_heads": a("attention.head_count"),
+        "num_key_value_heads": a("attention.head_count_kv"),
+        "head_dim": a("attention.key_length"),
+        "max_position_embeddings": a("context_length"),
+        "rms_norm_eps": float(a("attention.layer_norm_rms_epsilon")),
+        "rope_theta": float(a("rope.freq_base")),
+        "vocab_size": int(np.prod(GB.tensors["token_embd.weight"][0][1:])),
+        "bos_token_id": GB.kv.get("tokenizer.ggml.bos_token_id"),
+        "eos_token_id": GB.kv.get("tokenizer.ggml.eos_token_id"),
+        "tie_word_embeddings": "output.weight" not in GB.tensors,
+        "torch_dtype": "bfloat16",
+        "hidden_act": "silu",
+        "linear_num_key_heads": s("group_count"),
+        "linear_key_head_dim": s("state_size"),
+        "linear_value_head_dim": s("state_size"),
+        "linear_num_value_heads": nvh,
+        "linear_conv_kernel_dim": s("conv_kernel", 4),
+        "attn_output_gate": 1,
+        "layer_types": ["full_attention" if (i % fai) == (fai - 1) else "linear_attention"
+                        for i in range(nl)],
+        "partial_rotary_factor": 0.25,
+        "q4nx_weight_layout": "rm",
+        "q4nx_source": {"converter": "qwen35_to_q4nx.py", "gguf": os.path.basename(GB.path),
+                        "v_head_reorder": "hf" if REORDER else "stored"},
+    }
+    return {k: v for k, v in c.items() if v is not None}
+
+
+def refuse_unsupported(gb):
+    """The inputs this tool would turn into a wrong container, refused by name (engine#2013)."""
+    arch = gb.kv.get("general.architecture")
+    if arch != "qwen35":
+        raise SystemExit(f"{gb.path}: general.architecture is {arch!r}; this tool packs qwen35 only "
+                         "(qwen3, qwen3moe and qwen2 are tools/gguf_to_q4nx.py's)")
+    rotated = sorted(k for k in gb.kv if k.startswith("prism.hadamard"))
+    if rotated:
+        raise SystemExit(f"{gb.path}: carries {rotated[0]} ({len(rotated)} prism.hadamard key(s)), so its weights "
+                         "are stored in a Hadamard-rotated basis; this tool writes them as they are and no sign "
+                         "table, so the container would answer wrongly. Un-rotate the GGUF first")
+    tern = [name for name, (_dims, tt, _off) in gb.tensors.items() if tt == PTQ1]
+    if tern:
+        raise SystemExit(f"{gb.path}: {len(tern)} tensor(s) are ggml type 143, PTQ1_0 (first: {tern[0]}); this tool "
+                         "packs Q4_0/Q4_1 codes. Rewrite the file as Q4_0 (tools/ternary_to_q4_0.py) and un-rotate "
+                         "it first")
+    odd = {}
+    for name, (_dims, tt, _off) in gb.tensors.items():
+        if tt not in BLK:
+            odd.setdefault(tt, name)
+    if odd:
+        raise SystemExit(f"{gb.path}: " + "; ".join(f"ggml tensor type {tt} (first: {n})" for tt, n in sorted(odd.items()))
+                         + " is not one this tool reads (F32, F16, Q4_0, Q4_1, BF16, PTQ1_0)")
+
+
+def pack(args):
+    global GB, REORDER
+    GB, REORDER = Gguf(args.gguf), args.reorder
+    refuse_unsupported(GB)
+    nl = int(GB.kv["qwen35.block_count"])
+    fai = int(GB.kv.get("qwen35.full_attention_interval", 4))
+    hd_g = int(GB.kv["qwen35.ssm.state_size"])
+    hd_a = int(GB.kv["qwen35.attention.key_length"])
+    os.makedirs(args.out, exist_ok=True)
+    table, blobs, off, done = {}, [], 0, 0
+
+    def emit(name, data, dtype, shape):
+        nonlocal off
+        b = np.ascontiguousarray(data).tobytes()
+        pad = (-off) % 64
+        if pad:
+            blobs.append(b"\0" * pad)
+            off += pad
+        table[name] = {"dtype": dtype, "shape": list(shape), "data_offsets": [off, off + len(b)]}
+        blobs.append(b)
+        off += len(b)
+
+    for src, dst, kind, full, g in plan(nl, fai):
+        dims = GB.tensors[src][0]
+        N = int(dims[1]) if len(dims) > 1 else 1
+        K = int(dims[0])
+        if kind == "tiles":
+            codes, scale, zero = GB.q4(src)
+            idx = reorder_idx(g, full, N, hd_g, hd_a)
+            if idx is not None:
+                codes, scale, zero = row_gather(codes, scale, zero, idx)
+            elif g == "ssm_out" and REORDER:
+                codes, scale, zero = col_gather(codes, scale, zero, hd_g, 0)
+            d = tile_q4_1(codes, scale, zero)
+            emit(dst, d, "I8", d.shape)
+        elif kind == "q8":
+            w = GB.f32(src).reshape(N, K)
+            if REORDER:
+                w = w[head_perm()]
+            pad = np.zeros(((N + ROWS - 1) // ROWS * ROWS, K), np.float32)   # the forward's deq_pad
+            pad[:N] = w
+            d = tile_q8(pad)
+            emit(dst, d, "I8", d.shape)
+        elif kind == "conv1d":
+            ck, cd = int(dims[0]), int(dims[1])
+            m = GB.f32(src).reshape(cd, ck).T.copy()                        # [cd][ck] -> [ck][cd]
+            if REORDER:
+                m = m[:, np.concatenate([np.arange(2 * NKH * hd_g),
+                                         perm_cols(NVH, hd_g, 2 * NKH * hd_g)])]
+            emit(dst, bf16_bits(m.reshape(-1)), "BF16", [m.size])
+        elif kind == "f32":
+            v = GB.f32(src)
+            emit(dst, (v[head_perm()] if REORDER else v).astype("<f4"), "F32", [v.size])
+        else:
+            v = GB.f32(src)
+            emit(dst, bf16_bits(v), "BF16", [v.size])
+        done += 1
+        if done % 100 == 0:
+            print(f"  {done} tensors, {off / 1e9:.2f} GB", flush=True)
+
+    table["__metadata__"] = {"format": "q4nx", "source": os.path.basename(GB.path),
+                             "converter": "qwen35_to_q4nx.py"}
+    header = json.dumps(table, separators=(",", ":")).encode()
+    header += b" " * ((-len(header)) % 64)
+    with open(os.path.join(args.out, "model.q4nx"), "wb") as f:
+        f.write(struct.pack("<Q", len(header)))
+        f.write(header)
+        for b in blobs:
+            f.write(b)
+    with open(os.path.join(args.out, "config.json"), "w") as f:
+        json.dump(config(nl, fai), f, indent=2)
+        f.write("\n")
+    tok = args.tokenizer or os.path.dirname(os.path.abspath(args.gguf))
+    copied = []
+    for n in ("tokenizer.json", "tokenizer_config.json"):
+        if os.path.exists(os.path.join(tok, n)):
+            shutil.copyfile(os.path.join(tok, n), os.path.join(args.out, n))
+            copied.append(n)
+    if "tokenizer.json" not in copied:
+        print(f"WARNING: no tokenizer.json in {tok}; 1bit forward-serve will refuse {args.out}")
+    print(f"wrote {args.out}/model.q4nx ({8 + len(header) + off} bytes, {len(table) - 1} tensors)")
+
+
+def verify(args):
+    """Every tile tensor untiles back to code*scale+zero exactly, at the shape the plan asks for."""
+    global GB, REORDER
+    GB, REORDER = Gguf(args.gguf), True
+    refuse_unsupported(GB)
+    nl = int(GB.kv["qwen35.block_count"])
+    fai = int(GB.kv.get("qwen35.full_attention_interval", 4))
+    hd_g = int(GB.kv["qwen35.ssm.state_size"])
+    hd_a = int(GB.kv["qwen35.attention.key_length"])
+    with open(os.path.join(args.out, "model.q4nx"), "rb") as f:
+        n = struct.unpack("<Q", f.read(8))[0]
+        hdr = json.loads(f.read(n))
+        base = 8 + n
+    mm = np.memmap(os.path.join(args.out, "model.q4nx"), np.uint8, mode="r")
+    bad = 0
+    for src, dst, kind, full, g in plan(nl, fai):
+        lo, hi = hdr[dst]["data_offsets"]
+        raw = np.asarray(mm[base + lo:base + hi])
+        dims = GB.tensors[src][0]
+        N = int(dims[1]) if len(dims) > 1 else 1
+        K = int(dims[0])
+        if kind == "tiles":
+            # reference: the GGUF's own dequant, reordered the same way, with bf16-rounded scale/zero
+            codes, scale, zero = GB.q4(src)
+            idx = reorder_idx(g, full, N, hd_g, hd_a)
+            if idx is not None:
+                codes, scale, zero = row_gather(codes, scale, zero, idx)
+            elif g == "ssm_out":
+                codes, scale, zero = col_gather(codes, scale, zero, hd_g, 0)
+            ref = (codes.reshape(N, K // GROUP, GROUP) * from_bf16(bf16_bits(scale))[..., None]
+                   + from_bf16(bf16_bits(zero))[..., None]).reshape(N, K)
+            err = np.abs(untile_q4_1(raw, N, K) - ref)
+            ok, note = err.max() == 0, f"exact, {hdr[dst]['shape']}"
+        elif kind == "f32":
+            got = np.frombuffer(raw.tobytes(), "<f4")
+            ref = GB.f32(src)
+            exp = ref[head_perm()] if REORDER else ref
+            ok, note = np.array_equal(got, exp), "f32 exact"
+        elif kind == "conv1d":
+            ck, cd = int(dims[0]), int(dims[1])
+            got = from_bf16(raw.view("<u2")).reshape(ck, cd)
+            m = GB.f32(src).reshape(cd, ck).T.copy()             # [cd][ck] -> [ck][cd]
+            exp = m[:, np.concatenate([np.arange(2 * NKH * hd_g),
+                                       perm_cols(NVH, hd_g, 2 * NKH * hd_g)])] if REORDER else m
+            exact = np.array_equal(got, from_bf16(bf16_bits(exp)))
+            # the v-band permutation's DIRECTION, checked independently of the packer's gather:
+            # Both sides are summed from bf16-rounded values, in f64: a head's sum can cancel to near zero, and
+            # a relative tolerance between a rounded and an unrounded sum then fails a correct container.
+            gb = got[:, 2 * NKH * hd_g:].astype(np.float64).reshape(ck, NVH, hd_g).sum(-1)
+            rb = from_bf16(bf16_bits(m))[:, 2 * NKH * hd_g:].astype(np.float64).reshape(ck, NVH, hd_g).sum(-1)
+            hf = np.array_equal(gb, rb[:, head_perm()])
+            ok = exact and hf
+            where = "hf" if hf else "stored" if np.array_equal(gb, rb) else "neither"
+            note = f"bf16 {'exact' if exact else 'MISMATCH'}, v-band direction {where}"
+        elif kind == "bf16":
+            got, ref = from_bf16(raw.view("<u2")), GB.f32(src)
+            rel = np.max(np.abs(got - ref) / (np.abs(ref) + 1e-30))
+            ok, note = rel <= 2 ** -8 + 1e-6, f"bf16 max rel {rel:.3g}"
+        else:
+            ok, note = got_q8(raw, src, N, K), "Q8 (checked separately)"
+        bad += not ok
+        if not ok or ".layers.0." in dst or ".layers.3." in dst or ".layers." not in dst:
+            print(f"{'ok ' if ok else 'BAD'} {dst:52s} {note}")
+    print(f"{bad} bad tensors")
+    return 1 if bad else 0
+
+
+def got_q8(raw, src, N, K):
+    """Q8 tiles back to f32, compared against the padded, reordered BF16 source."""
+    w = GB.f32(src).reshape(N, K)
+    if REORDER:
+        w = w[head_perm()]
+    pad = np.zeros(((N + ROWS - 1) // ROWS * ROWS, K), np.float32)
+    pad[:N] = w
+    got = np.empty_like(pad)
+    rt, ktn = pad.shape[0] // ROWS, pad.shape[1] // COLS
+    t = raw.reshape(rt, ktn, 8704)
+    for r in range(rt):
+        for k in range(ktn):
+            d = from_bf16(t[r, k, :512].copy().view("<u2")).reshape(8, ROWS)
+            q = t[r, k, 512:].copy().view(np.int8).reshape(COLS, ROWS).T
+            got[r * ROWS:(r + 1) * ROWS, k * COLS:(k + 1) * COLS] = \
+                (q.reshape(ROWS, 8, 32) * d.T[..., None]).reshape(ROWS, COLS)
+    rel = np.abs(got[:N] - w).max() / (np.abs(w).max() + 1e-30)
+    print(f"     Q8 {src}: max abs err {np.abs(got[:N] - w).max():.3g} (rel to max {rel:.2e})")
+    return rel < 0.01
+
+
+def selftest(_args=None):
+    """The tile round-trips, the head permutation and the q|gate de-interleave, on small data."""
+    rng = np.random.default_rng(0)
+    N, K = 64, 512
+    codes = rng.integers(0, 16, (N, K), dtype=np.uint8)
+    scale = rng.random((N, K // GROUP)).astype(np.float32)
+    zero = (rng.random((N, K // GROUP)) - 0.5).astype(np.float32)
+    ref = (codes.reshape(N, K // GROUP, GROUP) * from_bf16(bf16_bits(scale))[..., None]
+           + from_bf16(bf16_bits(zero))[..., None]).reshape(N, K)
+    got = untile_q4_1(tile_q4_1(codes, scale, zero), N, K)
+    assert np.array_equal(got, ref), "q4_1 tile round-trip"
+    p = head_perm()
+    assert sorted(p.tolist()) == list(range(NVH)), "head_perm is not a bijection"
+    assert all(p[j] == (j % 3) * NKH + j // 3 for j in range(NVH)), "head_perm formula"
+    idx = perm_rows(NVH, 128, off=4096)
+    assert idx[:4096].tolist() == list(range(4096)) and len(idx) == 4096 + NVH * 128
+    assert sorted(idx[4096:].tolist()) == list(range(4096, 4096 + NVH * 128)), "perm_rows tail"
+    q = deinterleave_qgate(2 * 24 * 256, 256)
+    assert sorted(q.tolist()) == list(range(12288)), "deinterleave is not a bijection"
+    for h in (0, 7):                                     # head h, part p, dim d  ->  p, h, d
+        for part in (0, 1):
+            src = h * 512 + part * 256 + 3
+            assert q[part * 6144 + h * 256 + 3] == src, "deinterleave mapping"
+    w = rng.standard_normal((64, 512)).astype(np.float32)
+    back = np.zeros_like(w)
+    t = tile_q8(w)
+    for r in range(2):
+        for k in range(2):
+            d = from_bf16(t[r, k, :512].copy().view("<u2")).reshape(8, ROWS)
+            qq = t[r, k, 512:].copy().view(np.int8).reshape(COLS, ROWS).T
+            back[r * 32:(r + 1) * 32, k * 256:(k + 1) * 256] = \
+                (qq.reshape(ROWS, 8, 32) * d.T[..., None]).reshape(ROWS, COLS)
+    rel = np.abs(back - w).max() / np.abs(w).max()
+    assert rel < 0.01, f"q8 round-trip {rel}"
+    print(f"selftest ok (q4_1 exact, q8 max rel {rel:.4f}, head_perm/deinterleave bijective)")
+    return 0
+
+
+def main():
+    p = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    sub = p.add_subparsers(dest="cmd", required=True)
+    a = sub.add_parser("pack")
+    a.add_argument("gguf")
+    a.add_argument("out")
+    a.add_argument("--tokenizer")
+    a.add_argument("--no-reorder", dest="reorder", action="store_false",
+                   help="keep the stored (rep-major) v-head order")
+    b = sub.add_parser("verify")
+    b.add_argument("gguf")
+    b.add_argument("out")
+    sub.add_parser("selftest")
+    args = p.parse_args()
+    return {"pack": pack, "verify": verify, "selftest": selftest}[args.cmd](args)
+
+
+if __name__ == "__main__":
+    sys.exit(main() or 0)