From a02b04d4b20facfcc5154ed9b9b45ee8c6b72fe1 Mon Sep 17 00:00:00 2001
From: mukmckenzie <mukmckenzie@users.noreply.github.com>
Date: Fri, 16 Oct 2026 11:38:28 -0700
Subject: [PATCH 1/7] feat(gguf): serve GLM-5.3-Flash GGUF checkpoints on
 glm5-next

Adds the llama.cpp glm5-next GGUF reader (unsloth GLM-5.3-Flash-GGUF, both
the glm5-next and the older glm5next arch spellings) on the GGUF quant
kind from #690:

- parse_gguf_config derives the text config from the GGUF KV metadata,
  with per-block attention.head_count_kv laying out the KDA/DSA hybrid,
  the trailing MTP block dropped like the HF loader drops it, and the
  MLA head widths from the *_length_mla keys.
- iter_gguf_weights maps every tensor to the glm5_next state dict and
  undoes the converter transforms: A_log stored as -exp(A_log) is
  inverted, the per-head attn_k_b/attn_v_b pair (k transposed) fuses
  into the dense kv_b_proj layout the MLA absorption reads, and the
  q|k|v conv kernels concatenate on the channel axis. The mixed-type
  fused KDA in_proj (Q8_0 q|k|v + BF16 b|f_a|g_a) rides #702 segments;
  the routed experts load as GGUF expert banks at their shipped types
  (unsloth dynamic quants: IQ3_S gate/up + IQ4_XS down, Q8_0 outlier
  layers pass through natively).
- passes quant_config to embed_tokens so the Q8_0 token_embd serves
  packed; registers Glm5NextGGUFForCausalLM and claims it in the AOT
  table.

Verified end to end against unsloth GLM-5.3-Flash-UD-IQ4_XS (5 split
shards): the full engine on a 32GB GPU serves coherent output with the
experts off host banks. Text-only, TP=1.

Part of #671.
---
 python/freetoken/kernel/aot_models.py         |   2 +-
 python/freetoken/models/gguf/config.py        |   3 +
 python/freetoken/models/glm5_next/__init__.py |   4 +
 python/freetoken/models/glm5_next/gguf.py     | 360 ++++++++++++++++++
 python/freetoken/models/glm5_next/model.py    |   2 +
 python/freetoken/models/register.py           |  10 +
 tests/models/test_glm5_next_gguf.py           | 305 +++++++++++++++
 7 files changed, 685 insertions(+), 1 deletion(-)
 create mode 100644 python/freetoken/models/glm5_next/gguf.py
 create mode 100644 tests/models/test_glm5_next_gguf.py

diff --git a/python/freetoken/kernel/aot_models.py b/python/freetoken/kernel/aot_models.py
index fd67d56541..dff23e117c 100644
--- a/python/freetoken/kernel/aot_models.py
+++ b/python/freetoken/kernel/aot_models.py
@@ -281,7 +281,7 @@ def expert_bank_row_bytes(fmt: str, hidden_size: int, moe_intermediate_size: int
         # KDA conv/recurrent state lives in the LinearStatePool, not paged KV.
         name="RedHatAI/GLM-5.3-Flash-NVFP4",
         architecture="Glm5NextForCausalLM",
-        arch_aliases=("Glm5NextForConditionalGeneration",),
+        arch_aliases=("Glm5NextForConditionalGeneration", "Glm5NextGGUFForCausalLM"),  # GGUF expert rows differ per layer and reach the fused copy as runtime sizes
         hidden_size=4096,
         kv_groups=(),
         top_k=8,
diff --git a/python/freetoken/models/gguf/config.py b/python/freetoken/models/gguf/config.py
index 5b780fe0ef..5767d4eb1c 100644
--- a/python/freetoken/models/gguf/config.py
+++ b/python/freetoken/models/gguf/config.py
@@ -19,6 +19,9 @@
 GGUF_ARCH_TO_REGISTRY: dict[str, str] = {
     "gemma4": "Gemma4GGUFForCausalLM",
     "glm4moe": "Glm4MoeGGUFForCausalLM",
+    # glm5-next: the llama.cpp spelling; glm5next: unsloth's first release
+    "glm5-next": "Glm5NextGGUFForCausalLM",
+    "glm5next": "Glm5NextGGUFForCausalLM",
     "llama": "LlamaGGUFForCausalLM",
     "minimax-m2": "MiniMaxM2GGUFForCausalLM",
     "minimax-m3": "MiniMaxM3GGUFForCausalLM",
diff --git a/python/freetoken/models/glm5_next/__init__.py b/python/freetoken/models/glm5_next/__init__.py
index 7eee33dfee..0c548da7f6 100644
--- a/python/freetoken/models/glm5_next/__init__.py
+++ b/python/freetoken/models/glm5_next/__init__.py
@@ -1,4 +1,5 @@
 from .config import VisionConfig, parse_config, parse_vision_config
+from .gguf import iter_gguf_weights, parse_gguf_config, to_gguf
 from .model import Glm5NextForCausalLM, Glm5NextForConditionalGeneration
 from .vision import Glm5NextVisionModel
 from .weight import iter_expert_pieces, iter_vision_weights, iter_weights, nvfp4_expert_spec
@@ -10,8 +11,11 @@
     "Glm5NextVisionModel",
     "VisionConfig",
     "parse_config",
+    "parse_gguf_config",
     "parse_vision_config",
     "iter_vision_weights",
+    "iter_gguf_weights",
     "iter_weights",
+    "to_gguf",
     "iter_expert_pieces",
 ]
diff --git a/python/freetoken/models/glm5_next/gguf.py b/python/freetoken/models/glm5_next/gguf.py
new file mode 100644
index 0000000000..e3bf275ad4
--- /dev/null
+++ b/python/freetoken/models/glm5_next/gguf.py
@@ -0,0 +1,360 @@
+"""GLM-5.3-Flash from a llama.cpp ``glm5-next`` GGUF (unsloth ``GLM-5.3-Flash-GGUF``): config from the GGUF metadata, tensor names, and the converter's transforms undone.
+
+The GGUF geometry is identical to the HF checkpoint (34 KDA linear-attention layers,
+11 NoPE-MLA/DSA layers with a kpool-compressed indexer on a 3+1 hybrid block layout,
+mHC x4 residual streams, 288-expert sigmoid/noaux_tc MoE with a shared expert and
+clamped SwiGLU), so ``parse_gguf_config`` derives a text-config-shaped namespace from
+the GGUF KV metadata (plus a tensor-name census for the facts the KV predates) and
+reuses ``glm5_next.config.parse_config`` wholesale.
+
+The llama.cpp converter (unsloth's glm5-next writer; tensor names identical across
+the ``glm5-next`` and the older ``glm5next`` arch spellings) stores KDA's ``A_log``
+pre-transformed as ``-exp(A_log)`` -- inverted at load -- and splits the MLA
+``kv_b_proj`` into per-head 3-D ``attn_k_b`` / ``attn_v_b`` tensors (k stored
+transposed, [heads, kv_lora, nope] next to [heads, v, kv_lora]); both halves ship
+BF16, so they dequantize and fuse into the dense layout the module's MLA absorption
+reads. The trailing MTP block (``blk.N.nextn.*``, ``nextn_predict_layers == 1``) is
+dropped exactly like the HF loader drops the never-read MTP layer; routed experts
+serve from the GGUF expert banks (``freetoken.models.gguf.experts``).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import replace
+from types import SimpleNamespace
+from typing import TYPE_CHECKING, Iterator
+
+import torch
+
+from freetoken.models.gguf.reader import GgufTensorInfo, gguf_tensor_index, gguf_tensor_names
+from freetoken.models.gguf.tensors import float_tensor, fused, matrix
+
+from .config import parse_config
+
+if TYPE_CHECKING:
+    from freetoken.models.config import ModelConfig
+    from freetoken.models.gguf.config import GgufConfigShim
+
+# HF config fields the GGUF metadata does not carry (GLM-5.3-Flash's config.json values).
+_FAMILY_DEFAULTS = dict(
+    hidden_act="silu",
+    attention_bias=False,
+    # NoPE means no rope on the main attention; the indexer's interleaved rope is a
+    # served-model fact the GGUF KV predates, and getting it wrong scores the indexer
+    # keys incorrectly (DSA retrieval degrades to garbage).
+    indexer_rope_interleave=True,
+)
+
+# checkpoint module leaf (glm5_next HF naming, language-model rooted) -> GGUF tensors
+_LAYER_LEAVES: dict[str, tuple[str, ...]] = {
+    # KDA input projections (the six leaves of the fused in_proj)
+    "self_attn.q_proj": ("attn_q",),
+    "self_attn.k_proj": ("attn_k",),
+    "self_attn.v_proj": ("attn_v",),
+    "self_attn.b_proj": ("ssm_beta",),
+    "self_attn.f_a_proj": ("ssm_f_a",),
+    "self_attn.g_a_proj": ("ssm_g_a",),
+    "self_attn.f_b_proj": ("ssm_f_b",),
+    "self_attn.g_b_proj": ("ssm_g_b",),
+    # both layer kinds name their output projection the same
+    "self_attn.o_proj": ("attn_output",),
+    # DSA (MLA) projections
+    "self_attn.q_a_proj": ("attn_q_a",),
+    "self_attn.q_b_proj": ("attn_q_b",),
+    "self_attn.kv_a_proj_with_mqa": ("attn_kv_a_mqa",),
+    # both halves are float in every release: the module keeps its dense bf16 kv_b
+    "self_attn.kv_b_proj": ("attn_k_b", "attn_v_b"),
+    # kpool indexer
+    "self_attn.indexer.wq_b": ("indexer.attn_q_b",),
+    "self_attn.indexer.wk": ("indexer.attn_k",),
+    "self_attn.indexer.weights_proj": ("indexer.proj",),
+    # dense MLP of the leading blocks
+    "mlp.gate_proj": ("ffn_gate",),
+    "mlp.up_proj": ("ffn_up",),
+    "mlp.down_proj": ("ffn_down",),
+    # shared expert of the MoE blocks
+    "mlp.shared_experts.gate_proj": ("ffn_gate_shexp",),
+    "mlp.shared_experts.up_proj": ("ffn_up_shexp",),
+    "mlp.shared_experts.down_proj": ("ffn_down_shexp",),
+    # routed experts (GGUF expert banks)
+    "mlp.experts.0.gate_proj": ("ffn_gate_exps",),
+    "mlp.experts.0.up_proj": ("ffn_up_exps",),
+    "mlp.experts.0.down_proj": ("ffn_down_exps",),
+}
+_TOP_LEAVES: dict[str, tuple[str, ...]] = {
+    # checkpoint-space names: the language-model root is already applied when to_gguf runs
+    "model.language_model.embed_tokens": ("token_embd",),
+    "lm_head": ("output",),
+}
+_LAYER_RE = re.compile(r"^model\.language_model\.layers\.(\d+)\.(.+)$")
+
+
+def to_gguf(name: str, tensors: dict[str, int]) -> tuple[str, ...]:
+    """Checkpoint module name -> the GGUF tensors (without ``.weight``) that store it; empty for modules the GGUF has no matrix for."""
+    if name in _TOP_LEAVES:
+        return _TOP_LEAVES[name]
+    m = _LAYER_RE.match(name)
+    if m is None:
+        return ()
+    return tuple(f"blk.{m.group(1)}.{leaf}" for leaf in _LAYER_LEAVES.get(m.group(2), ()))
+
+
+def _layer_types(shim: "GgufConfigShim", num_layers: int) -> tuple[str, ...]:
+    """Per-decoder-layer kinds: DSA where the MLA projections sit, KDA elsewhere.
+
+    The new writer carries ``attention.head_count_kv`` as a per-block list (0 on the
+    KDA blocks, 1 on the MLA ones); the older spelling predates it, so fall back to a
+    tensor-name census (``attn_q_a`` is DSA-only). A metadata-only GGUF (an FTW's
+    ``source_metadata.gguf``) has neither the list nor the tensor table, and only the
+    new writer's files can convert."""
+    from .args import DSA_LAYER, KDA_LAYER
+
+    md = shim.metadata
+    per_block = md.get(f"{shim.model_type}.attention.head_count_kv")
+    if per_block is not None and len(per_block) >= num_layers:
+        return tuple(DSA_LAYER if int(kv) else KDA_LAYER for kv in per_block[:num_layers])
+    names = gguf_tensor_names(shim.model_path)
+    if not names:
+        raise ValueError(
+            f"{shim.model_path}: metadata-only GGUF without attention.head_count_kv; "
+            "the layer layout cannot be recovered (reconvert from a current writer)"
+        )
+    return tuple(
+        DSA_LAYER if f"blk.{i}.attn_q_a.weight" in names else KDA_LAYER for i in range(num_layers)
+    )
+
+
+def _head_dims(shim: "GgufConfigShim") -> tuple[int, int]:
+    """(qk_nope, v) head widths: the new writer's ``*_length_mla`` KVs, else the q_b/v_b rows."""
+    md = shim.metadata
+    prefix = shim.model_type
+    nope, v = md.get(f"{prefix}.attention.key_length_mla"), md.get(f"{prefix}.attention.value_length_mla")
+    if nope is None or v is None:
+        index = gguf_tensor_index(shim.model_path)
+        q_b = next((i for i in index.values() if i.name.endswith("attn_q_b.weight")), None)
+        v_b = next((i for i in index.values() if i.name.endswith("attn_v_b.weight")), None)
+        if q_b is None or v_b is None:
+            raise ValueError(f"{shim.model_path}: GGUF lacks attn_q_b/attn_v_b to size the MLA heads")
+        heads = int(md[f"{prefix}.attention.head_count"])
+        nope, v = q_b.ne[1] // heads, v_b.ne[1]
+    return int(nope), int(v)
+
+
+def parse_gguf_config(shim: "GgufConfigShim") -> ModelConfig:
+    md = shim.metadata
+    prefix = shim.model_type
+
+    def kv(key: str, default=None):
+        return md.get(f"{prefix}.{key}", default)
+
+    def need(key: str):
+        val = kv(key)
+        if val is None:
+            raise KeyError(f"missing GGUF metadata key {prefix}.{key}")
+        return val
+
+    # block_count also counts the MTP block a GGUF carries after the decoder
+    n_mtp = int(kv("nextn_predict_layers", 0) or 0)
+    num_layers = int(need("block_count")) - n_mtp
+    layer_types = _layer_types(shim, num_layers)
+    first_dense = int(need("leading_dense_block_count"))
+
+    heads = int(need("attention.head_count"))
+    qk_nope, v_head = _head_dims(shim)
+    # NoPE: the main attention carries no rotary dims (rope survives only in the indexer)
+    assert int(kv("rope.dimension_count", 0) or 0) == 0, "glm5-next GGUF: unexpected rotary dims on the main attention"
+
+    # KDA head count: one q/k/v head set of kda.head_dim each; the conv channels or the
+    # beta rows count them, falling back to the shared head_count (the two coincide on
+    # every release) when the tensor table is gone (metadata-only GGUF).
+    kda_head_dim = int(need("kda.head_dim"))
+    index = gguf_tensor_index(shim.model_path)
+    conv_q = next((i for i in index.values() if i.name.endswith("ssm_conv1d_q.weight")), None)
+    kda_heads = conv_q.ne[2] // kda_head_dim if conv_q is not None else heads
+
+    kpool = int(kv("attention.indexer.kpool", 1) or 1)
+    # the compressor tensors exist exactly when the indexer pools; a metadata-only GGUF
+    # keeps the fact only through kpool > 1
+    names = gguf_tensor_names(shim.model_path)
+    kpool_compress = any(n.endswith("indexer_compressor_gate.weight") for n in names) if names else kpool > 1
+    indexer_types_kv = kv("attention.indexer.types")
+    if indexer_types_kv is not None and len(indexer_types_kv) >= num_layers:
+        indexer_types = tuple("full" if b else "disabled" for b in indexer_types_kv[:num_layers])
+    else:
+        # every release carries all-"full" in the HF config (the engine builds only the DSA-owned indexers)
+        indexer_types = ("full",) * num_layers
+
+    clamp = need("swiglu_clamp_exp")
+    text = SimpleNamespace(
+        **_FAMILY_DEFAULTS,
+        num_hidden_layers=num_layers,
+        layer_types=tuple(layer_types),
+        mlp_layer_types=("dense",) * first_dense + ("sparse",) * (num_layers - first_dense),
+        first_k_dense_replace=first_dense,
+        hidden_size=int(need("embedding_length")),
+        num_attention_heads=heads,
+        vocab_size=int(shim.vocab_size),
+        intermediate_size=int(need("feed_forward_length")),
+        rms_norm_eps=float(need("attention.layer_norm_rms_epsilon")),
+        max_position_embeddings=int(need("context_length")),
+        q_lora_rank=int(need("attention.q_lora_rank")),
+        kv_lora_rank=int(need("attention.kv_lora_rank")),
+        qk_nope_head_dim=qk_nope,
+        qk_rope_head_dim=0,
+        v_head_dim=v_head,
+        mla_use_nope=True,
+        index_n_heads=int(need("attention.indexer.head_count")),
+        index_head_dim=int(need("attention.indexer.key_length")),
+        index_topk=int(need("attention.indexer.top_k")),
+        indexer_types=indexer_types,
+        index_kpool=kpool,
+        index_kpool_compress=kpool_compress,
+        # old converters predate the key; both released checkpoints set it true
+        index_kpool_always_select_tail=bool(kv("attention.indexer.kpool_select_tail", True)),
+        linear_attn_config={
+            "num_heads": kda_heads,
+            "head_dim": kda_head_dim,
+            "short_conv_kernel_size": int(need("ssm.conv_kernel")),
+            "gate_lower_bound": float(need("kda.gate_lower_bound")),
+        },
+        mhc=True,
+        hc_mult=int(need("hyper_connection.count")),
+        hc_sinkhorn_iters=int(need("hyper_connection.sinkhorn_iterations")),
+        hc_eps=float(need("hyper_connection.epsilon")),
+        n_routed_experts=int(need("expert_count")),
+        n_shared_experts=int(kv("expert_shared_count", 1) or 1),
+        num_experts_per_tok=int(need("expert_used_count")),
+        moe_intermediate_size=int(need("expert_feed_forward_length")),
+        norm_topk_prob=bool(need("expert_weights_norm")),
+        routed_scaling_factor=float(need("expert_weights_scale")),
+        n_group=int(kv("expert_group_count", 1) or 1),
+        topk_group=int(kv("expert_group_used_count", 1) or 1),
+        tie_word_embeddings=bool(shim.tie_word_embeddings),
+        swiglu_limit=float(clamp[0] if isinstance(clamp, list) else clamp),
+    )
+    hf_like = SimpleNamespace(
+        text_config=text,
+        model_type="glm5_next",
+        architectures=list(shim.architectures),
+        vision_config=None,
+        image_token_id=None,
+    )
+    config = parse_config(hf_like)
+    return replace(config, expert_quant="gguf")
+
+
+# ----------------------------------------------------------------------------------------------
+# Weights
+# ----------------------------------------------------------------------------------------------
+
+def _kv_b(kb: GgufTensorInfo, vb: GgufTensorInfo, num_heads: int, kv_lora: int) -> torch.Tensor:
+    """Per-head k [kv_lora, nope] (stored transposed) + v [v, kv_lora] -> the module's fused dense [heads * (nope + v), kv_lora]."""
+    k = float_tensor(kb).transpose(1, 2)  # [heads, nope, kv_lora]
+    fused_w = torch.cat([k, float_tensor(vb)], dim=1)
+    assert fused_w.shape[0] == num_heads, (fused_w.shape, num_heads)
+    return fused_w.reshape(num_heads * fused_w.shape[1], kv_lora).to(torch.bfloat16).contiguous()
+
+
+def iter_gguf_weights(
+    model_path: str,
+    device: torch.device,
+    *,
+    include_moe_experts: bool,
+    include_non_moe: bool,
+    include_vision: bool = True,
+) -> Iterator[tuple[str, torch.Tensor]]:
+    """The dense state dict from the GGUF; the routed experts load as offload banks (``freetoken.models.gguf.experts``)."""
+    if not include_non_moe:
+        return
+    from freetoken.utils import cached_load_hf_config
+
+    config = parse_gguf_config(cached_load_hf_config(model_path))
+    args = config.glm5_args
+    index = gguf_tensor_index(model_path)
+    hidden = config.hidden_size
+
+    def t(name: str) -> GgufTensorInfo:
+        return index[name if name in index else f"{name}.weight"]
+
+    def bf16(name: str) -> torch.Tensor:
+        return float_tensor(t(name)).to(torch.bfloat16)
+
+    yield from fused("model.embed_tokens", [t("token_embd")], [matrix(t("token_embd"))], hidden)
+    yield from fused("lm_head", [t("output")], [matrix(t("output"))], hidden)
+    yield "model.norm.weight", bf16("output_norm")
+
+    for layer in range(config.num_layers):
+        blk, pre = f"blk.{layer}", f"model.layers.{layer}"
+        yield f"{pre}.input_layernorm.weight", bf16(f"{blk}.attn_norm")
+        yield f"{pre}.post_attention_layernorm.weight", bf16(f"{blk}.ffn_norm")
+        # mHC mixing tensors, fp32 on every layer
+        for sub in ("attn", "ffn"):
+            for part in ("fn", "base", "scale"):
+                yield f"{pre}.hc_{sub}_{part}", float_tensor(t(f"{blk}.hc_{sub}_{part}"))
+
+        if args.is_kda_layer(layer):
+            sa = f"{pre}.self_attn"
+            p, h, d = args.linear_num_heads * args.linear_head_dim, args.linear_num_heads, args.linear_head_dim
+            group = [t(f"{blk}.{n}") for n in ("attn_q", "attn_k", "attn_v", "ssm_beta", "ssm_f_a", "ssm_g_a")]
+            yield from fused(f"{sa}.in_proj", group, [matrix(i) for i in group], hidden)
+            # the GGUF conv kernels already carry the [channels, 1, kernel] singleton dim
+            conv = torch.cat([float_tensor(t(f"{blk}.ssm_conv1d_{q}")) for q in ("q", "k", "v")], dim=0)
+            yield f"{sa}.conv1d.weight", conv.to(torch.bfloat16)
+            for proj, src, k in (("f_b_proj", "ssm_f_b", d), ("g_b_proj", "ssm_g_b", d), ("o_proj", "attn_output", p)):
+                info = t(f"{blk}.{src}")
+                yield from fused(f"{sa}.{proj}", [info], [matrix(info)], k)
+            # the converter stores A_log pre-transformed as -exp(A_log); the kernels want the raw log
+            yield f"{sa}.A_log", torch.log(-float_tensor(t(f"{blk}.ssm_a")))
+            yield f"{sa}.dt_bias", float_tensor(t(f"{blk}.ssm_dt.bias"))
+            yield f"{sa}.o_norm.weight", bf16(f"{blk}.ssm_norm")
+        else:
+            sa = f"{pre}.self_attn"
+            for proj, src, k in (
+                ("q_a_proj", "attn_q_a", hidden),
+                ("q_b_proj", "attn_q_b", args.q_lora_rank),
+                ("kv_a_proj_with_mqa", "attn_kv_a_mqa", hidden),
+                ("o_proj", "attn_output", args.num_heads * args.v_head_dim),
+            ):
+                info = t(f"{blk}.{src}")
+                yield from fused(f"{sa}.{proj}", [info], [matrix(info)], k)
+            yield f"{sa}.kv_b_proj.weight", _kv_b(
+                t(f"{blk}.attn_k_b"), t(f"{blk}.attn_v_b"), args.num_heads, args.kv_lora_rank
+            )
+            yield f"{sa}.q_a_layernorm.weight", bf16(f"{blk}.attn_q_a_norm")
+            yield f"{sa}.kv_a_layernorm.weight", bf16(f"{blk}.attn_kv_a_norm")
+            for proj, src in (
+                ("indexer.wq_b", "indexer.attn_q_b"),
+                ("indexer.wk", "indexer.attn_k"),
+                ("indexer.weights_proj", "indexer.proj"),
+            ):
+                info = t(f"{blk}.{src}")
+                yield from fused(f"{sa}.{proj}", [info], [matrix(info)], int(info.ne[0]))
+            yield f"{sa}.indexer.k_norm.weight", bf16(f"{blk}.indexer.k_norm")
+            yield f"{sa}.indexer.k_norm.bias", bf16(f"{blk}.indexer.k_norm.bias")
+            yield f"{sa}.indexer.index_kpool_compress_gate", bf16(f"{blk}.indexer_compressor_gate")
+            yield f"{sa}.indexer.index_kpool_compress_ape", float_tensor(t(f"{blk}.indexer_compressor_ape"))
+
+        mlp = f"{pre}.mlp"
+        if layer < config.first_k_dense_replace:
+            for proj, src, k in (
+                ("gate_proj", "ffn_gate", hidden),
+                ("up_proj", "ffn_up", hidden),
+                ("down_proj", "ffn_down", config.intermediate_size),
+            ):
+                info = t(f"{blk}.{src}")
+                yield from fused(f"{mlp}.{proj}", [info], [matrix(info)], k)
+        else:
+            yield f"{mlp}.gate.weight", bf16(f"{blk}.ffn_gate_inp")
+            yield f"{mlp}.e_score_correction_bias", float_tensor(t(f"{blk}.exp_probs_b.bias"))
+            shared_i = config.moe_intermediate_size * max(1, config.n_shared_experts)
+            for proj, src, k in (
+                ("gate_proj", "ffn_gate_shexp", hidden),
+                ("up_proj", "ffn_up_shexp", hidden),
+                ("down_proj", "ffn_down_shexp", shared_i),
+            ):
+                info = t(f"{blk}.{src}")
+                yield from fused(f"{mlp}.shared_experts.{proj}", [info], [matrix(info)], k)
+
+
+__all__ = ["iter_gguf_weights", "parse_gguf_config", "to_gguf"]
diff --git a/python/freetoken/models/glm5_next/model.py b/python/freetoken/models/glm5_next/model.py
index d2bfa684c1..d92977dea2 100644
--- a/python/freetoken/models/glm5_next/model.py
+++ b/python/freetoken/models/glm5_next/model.py
@@ -142,6 +142,8 @@ def __init__(self, config: ModelConfig, *, prefix: str = "model"):
         self.embed_tokens = VocabParallelEmbedding(
             num_embeddings=config.vocab_size,
             embedding_dim=config.hidden_size,
+            quant_config=config.quant,
+            prefix=f"{prefix}.embed_tokens",
         )
         self.layers = OPList(
             [Glm5NextDecoderLayer(config, i, prefix=f"{prefix}.layers.{i}") for i in range(config.num_layers)]
diff --git a/python/freetoken/models/register.py b/python/freetoken/models/register.py
index 42c6f3f548..b892d5cfcf 100644
--- a/python/freetoken/models/register.py
+++ b/python/freetoken/models/register.py
@@ -418,6 +418,16 @@ class ModelSpec:
         "Glm5NextForCausalLM",
         packed_modules_mapping=_GLM5_NEXT_PACKED,
     ),
+    # llama.cpp glm5-next GGUF (unsloth GLM-5.3-Flash-GGUF; text only): the same model
+    # classes with every tensor in its packed ggml type
+    "Glm5NextGGUFForCausalLM": ModelSpec(
+        "freetoken.models.glm5_next",
+        "Glm5NextForCausalLM",
+        parse_config="parse_gguf_config",
+        iter_weights="iter_gguf_weights",
+        checkpoint_roots=_LANGUAGE_MODEL_ROOT,
+        packed_modules_mapping=_GLM5_NEXT_PACKED,
+    ),
 }
 
 
diff --git a/tests/models/test_glm5_next_gguf.py b/tests/models/test_glm5_next_gguf.py
new file mode 100644
index 0000000000..085fffd727
--- /dev/null
+++ b/tests/models/test_glm5_next_gguf.py
@@ -0,0 +1,305 @@
+"""glm5-next GGUF: config parse and weight-reader mapping against a synthetic checkpoint.
+
+Builds a tiny two-layer (KDA + DSA) glm5-next GGUF in tmp -- geometry scaled down but
+every tensor, KV key and converter quirk of the real writer present (A_log stored as
+``-exp(A_log)``, the per-head ``attn_k_b``/``attn_v_b`` split with k transposed, the
+per-block ``head_count_kv`` list, the trailing MTP block) -- then checks the config the
+shim derives and the state dict the reader yields: names complete against the model's,
+kv_b fused to the module's dense layout, A_log inverted, conv1d concatenation.
+"""
+
+from __future__ import annotations
+
+import struct
+
+import pytest
+import torch
+
+from freetoken.distributed import set_tp_info, try_get_tp_info
+
+# GGUF v3 value types (the vendored gguf-py GGUFValueType numbering)
+_T_UINT32, _T_FLOAT32, _T_BOOL, _T_STRING, _T_ARRAY, _T_UINT64 = 4, 6, 7, 8, 9, 10
+
+
+def _tp1():
+    if try_get_tp_info() is None:
+        set_tp_info(rank=0, size=1)
+
+
+def _pack_val(v):
+    if isinstance(v, str):
+        b = v.encode()
+        return struct.pack("<Q", len(b)) + b
+    if isinstance(v, bool):
+        return struct.pack("<B", int(v))
+    if isinstance(v, int):
+        return struct.pack("<I", v)
+    if isinstance(v, float):
+        return struct.pack("<f", v)
+    if isinstance(v, (list, tuple)):
+        assert v and all(isinstance(x, type(v[0])) for x in v), "homogeneous arrays only"
+        elem_type = {int: _T_UINT32, float: _T_FLOAT32, bool: _T_BOOL, str: _T_STRING}[type(v[0])]
+        body = b"".join(_pack_val(x) for x in v)
+        return struct.pack("<I", elem_type) + struct.pack("<Q", len(v)) + body
+    raise TypeError(v)
+
+
+def _gguf_writer(path, kvs, tensors):
+    """A minimal GGUF v3 writer: header + KV section + tensor infos + data, little-endian."""
+    kv_blob = b"".join(
+        struct.pack("<Q", len(k.encode())) + k.encode() + struct.pack("<I", t) + _pack_val(v)
+        for k, (t, v) in kvs.items()
+    )
+
+    infos, data, offset = b"", b"", 0
+    ALIGN = 32
+    for name, (ggml_type, ne, payload) in tensors:
+        ne = tuple(ne)
+        infos += struct.pack("<Q", len(name.encode())) + name.encode()
+        infos += struct.pack("<I", len(ne)) + b"".join(struct.pack("<Q", d) for d in ne)
+        infos += struct.pack("<I", ggml_type)
+        pad = (-offset) % ALIGN
+        infos += struct.pack("<Q", offset + pad)
+        offset += pad + len(payload)
+        data += b"\x00" * pad + payload
+
+    with open(path, "wb") as f:
+        f.write(b"GGUF" + struct.pack("<I", 3))
+        f.write(struct.pack("<Q", len(tensors)) + struct.pack("<Q", len(kvs)))
+        f.write(kv_blob)
+        f.write(infos)
+        f.write(b"\x00" * ((-f.tell()) % ALIGN))
+        f.write(data)
+
+
+# ggml type ids
+_F32, _Q8_0, _IQ3_S, _IQ4_XS, _BF16 = 0, 8, 21, 23, 30
+
+
+def _make_gguf(path, *, n_layers=2, n_mtp=1, arch="glm5-next", head_kv_list=None):
+    """A miniature glm5-next layout: layer 0 KDA, layer 1 DSA, one trailing MTP block."""
+    import numpy as np
+
+    # hidden/q_lora keep Q8_0 rows a multiple of 32, expert rows a multiple of 256 (IQ3_S/IQ4_XS blocks)
+    H, D, KDA_H, KDA_D = 8, 32, 4, 8
+    QKV = KDA_H * KDA_D  # 32
+    I, E, V = 512, 4, 64
+
+    rng = np.random.default_rng(0)
+    f32 = lambda *shape: rng.standard_normal(shape).astype(np.float32)
+    bf16 = lambda n: (rng.standard_normal(n).astype(np.float32).view(np.uint32) >> 16).astype(np.uint16).tobytes()
+    q8 = lambda k, rows: np.zeros(rows * (k // 32) * 34, dtype=np.uint8).tobytes()  # placeholder packed rows
+    iq3 = lambda k, rows, e: np.zeros(rows * e * (k // 256) * 110, dtype=np.uint8).tobytes()
+    iq4 = lambda k, rows, e: np.zeros(rows * e * (k // 256) * 144, dtype=np.uint8).tobytes()
+
+    kv_heads = head_kv_list if head_kv_list is not None else ([0, 1] + [1] * n_mtp)
+    hidden = H * D  # 128
+    q_lora = 32
+    kvs = {
+        "general.architecture": (_T_STRING, arch),
+        "general.name": (_T_STRING, "glm5-next-test"),
+        f"{arch}.block_count": (_T_UINT32, n_layers + n_mtp),
+        f"{arch}.context_length": (_T_UINT32, 512),
+        f"{arch}.embedding_length": (_T_UINT32, hidden),
+        f"{arch}.feed_forward_length": (_T_UINT32, I),
+        f"{arch}.attention.head_count": (_T_UINT32, H),
+        f"{arch}.attention.head_count_kv": (_T_ARRAY, kv_heads),
+        f"{arch}.attention.layer_norm_rms_epsilon": (_T_FLOAT32, 1e-6),
+        f"{arch}.attention.q_lora_rank": (_T_UINT32, q_lora),
+        f"{arch}.attention.kv_lora_rank": (_T_UINT32, D),
+        f"{arch}.attention.key_length_mla": (_T_UINT32, D // 2),
+        f"{arch}.attention.value_length_mla": (_T_UINT32, D // 2),
+        f"{arch}.attention.indexer.head_count": (_T_UINT32, 2),
+        f"{arch}.attention.indexer.key_length": (_T_UINT32, 8),
+        f"{arch}.attention.indexer.top_k": (_T_UINT32, 64),
+        f"{arch}.attention.indexer.kpool": (_T_UINT32, 4),
+        f"{arch}.attention.indexer.types": (_T_ARRAY, [True] * (n_layers + n_mtp)),
+        f"{arch}.ssm.conv_kernel": (_T_UINT32, 4),
+        f"{arch}.kda.head_dim": (_T_UINT32, KDA_D),
+        f"{arch}.kda.gate_lower_bound": (_T_FLOAT32, -5.0),
+        f"{arch}.leading_dense_block_count": (_T_UINT32, 0),
+        f"{arch}.expert_count": (_T_UINT32, E),
+        f"{arch}.expert_used_count": (_T_UINT32, 2),
+        f"{arch}.expert_shared_count": (_T_UINT32, 1),
+        f"{arch}.expert_feed_forward_length": (_T_UINT32, I // 2),
+        f"{arch}.expert_weights_norm": (_T_BOOL, True),
+        f"{arch}.expert_weights_scale": (_T_FLOAT32, 2.5),
+        f"{arch}.hyper_connection.count": (_T_UINT32, 2),
+        f"{arch}.hyper_connection.sinkhorn_iterations": (_T_UINT32, 20),
+        f"{arch}.hyper_connection.epsilon": (_T_FLOAT32, 1e-6),
+        f"{arch}.swiglu_clamp_exp": (_T_ARRAY, [10.0] * (n_layers + n_mtp)),
+        f"{arch}.nextn_predict_layers": (_T_UINT32, n_mtp),
+        "tokenizer.ggml.tokens": (_T_ARRAY, ["<unk>"] * V),
+        "tokenizer.ggml.model": (_T_STRING, "gpt2"),
+    }
+
+    tensors = [
+        ("token_embd.weight", (_Q8_0, (hidden, V), q8(hidden, V))),
+        ("output.weight", (_Q8_0, (hidden, V), q8(hidden, V))),
+        ("output_norm.weight", (_F32, (hidden,), f32(hidden).tobytes())),
+    ]
+    for blk in range(n_layers + n_mtp):
+        is_dsa = kv_heads[blk] == 1
+        tensors.append((f"blk.{blk}.attn_norm.weight", (_F32, (hidden,), f32(hidden).tobytes())))
+        tensors.append((f"blk.{blk}.ffn_norm.weight", (_F32, (hidden,), f32(hidden).tobytes())))
+        for sub in ("attn", "ffn"):
+            tensors.append((f"blk.{blk}.hc_{sub}_fn.weight", (_F32, (2 * hidden, 8), f32(8, 2 * hidden).tobytes())))
+            tensors.append((f"blk.{blk}.hc_{sub}_base.weight", (_F32, (8,), f32(8).tobytes())))
+            tensors.append((f"blk.{blk}.hc_{sub}_scale.weight", (_F32, (3,), f32(3).tobytes())))
+        if is_dsa:
+            tensors.append((f"blk.{blk}.attn_q_a.weight", (_Q8_0, (hidden, q_lora), q8(hidden, q_lora))))
+            tensors.append((f"blk.{blk}.attn_q_b.weight", (_Q8_0, (q_lora, H * (D // 2)), q8(q_lora, H * (D // 2)))))
+            tensors.append((f"blk.{blk}.attn_kv_a_mqa.weight", (_BF16, (hidden, D), bf16(hidden * D))))
+            tensors.append((f"blk.{blk}.attn_k_b.weight", (_BF16, (D // 2, D, H), bf16(D * (D // 2) * H))))
+            tensors.append((f"blk.{blk}.attn_v_b.weight", (_BF16, (D, D // 2, H), bf16(D * (D // 2) * H))))
+            tensors.append((f"blk.{blk}.attn_output.weight", (_Q8_0, (H * (D // 2), hidden), q8(H * (D // 2), hidden))))
+            tensors.append((f"blk.{blk}.attn_q_a_norm.weight", (_F32, (q_lora,), f32(q_lora).tobytes())))
+            tensors.append((f"blk.{blk}.attn_kv_a_norm.weight", (_F32, (D,), f32(D).tobytes())))
+            tensors.append((f"blk.{blk}.indexer.attn_q_b.weight", (_BF16, (q_lora, 16), bf16(q_lora * 16))))
+            tensors.append((f"blk.{blk}.indexer.attn_k.weight", (_BF16, (hidden, 8), bf16(hidden * 8))))
+            tensors.append((f"blk.{blk}.indexer.k_norm.weight", (_F32, (8,), f32(8).tobytes())))
+            tensors.append((f"blk.{blk}.indexer.k_norm.bias", (_F32, (8,), f32(8).tobytes())))
+            tensors.append((f"blk.{blk}.indexer.proj.weight", (_F32, (hidden, 2), f32(hidden, 2).tobytes())))
+            tensors.append((f"blk.{blk}.indexer_compressor_gate.weight", (_F32, (hidden, 8), f32(hidden, 8).tobytes())))
+            tensors.append((f"blk.{blk}.indexer_compressor_ape.weight", (_F32, (8, 4), f32(8, 4).tobytes())))
+        else:
+            for name in ("attn_q", "attn_k", "attn_v", "ssm_beta", "ssm_f_a", "ssm_g_a"):
+                out_rows = QKV if name in ("attn_q", "attn_k", "attn_v") else (KDA_H if name == "ssm_beta" else KDA_D)
+                gt = _Q8_0 if name in ("attn_q", "attn_k", "attn_v") else _BF16
+                payload = q8(hidden, out_rows) if gt == _Q8_0 else bf16(out_rows * hidden)
+                tensors.append((f"blk.{blk}.{name}.weight", (gt, (hidden, out_rows), payload)))
+            tensors.append((f"blk.{blk}.ssm_f_b.weight", (_BF16, (KDA_D, QKV), bf16(KDA_D * QKV))))
+            tensors.append((f"blk.{blk}.ssm_g_b.weight", (_BF16, (KDA_D, QKV), bf16(KDA_D * QKV))))
+            tensors.append((f"blk.{blk}.attn_output.weight", (_Q8_0, (QKV, hidden), q8(QKV, hidden))))
+            for q in ("q", "k", "v"):
+                tensors.append((f"blk.{blk}.ssm_conv1d_{q}.weight", (_F32, (4, 1, QKV), f32(4, 1, QKV).tobytes())))
+            tensors.append((f"blk.{blk}.ssm_a", (_F32, (KDA_H,), (-np.abs(f32(KDA_H)) - 0.1).tobytes())))
+            tensors.append((f"blk.{blk}.ssm_dt.bias", (_F32, (QKV,), f32(QKV).tobytes())))
+            tensors.append((f"blk.{blk}.ssm_norm.weight", (_F32, (KDA_D,), f32(KDA_D).tobytes())))
+        # every decoder block here is MoE (leading_dense_block_count 0)
+        tensors.append((f"blk.{blk}.ffn_gate_inp.weight", (_F32, (hidden, E), f32(hidden, E).tobytes())))
+        tensors.append((f"blk.{blk}.exp_probs_b.bias", (_F32, (E,), f32(E).tobytes())))
+        tensors.append((f"blk.{blk}.ffn_gate_exps.weight", (_IQ3_S, (hidden, I // 2, E), iq3(hidden, I // 2, E))))
+        tensors.append((f"blk.{blk}.ffn_up_exps.weight", (_IQ3_S, (hidden, I // 2, E), iq3(hidden, I // 2, E))))
+        tensors.append((f"blk.{blk}.ffn_down_exps.weight", (_IQ4_XS, (I // 2, hidden, E), iq4(I // 2, hidden, E))))
+        for p in ("gate", "up"):
+            tensors.append((f"blk.{blk}.ffn_{p}_shexp.weight", (_Q8_0, (hidden, I // 2), q8(hidden, I // 2))))
+        tensors.append((f"blk.{blk}.ffn_down_shexp.weight", (_Q8_0, (I // 2, hidden), q8(I // 2, hidden))))
+    _gguf_writer(path, kvs, tensors)
+
+
+@pytest.fixture(scope="module")
+def glm_gguf(tmp_path_factory):
+    path = tmp_path_factory.mktemp("glm5gguf") / "glm5-test.gguf"
+    _make_gguf(str(path))
+    return str(path)
+
+
+def _shim(path):
+    from freetoken.models.gguf.config import build_gguf_shim
+
+    return build_gguf_shim(path)
+
+
+def test_shim_routes_the_architecture(glm_gguf):
+    shim = _shim(glm_gguf)
+    assert shim.architectures == ["Glm5NextGGUFForCausalLM"]
+    assert shim.vocab_size == 64
+    assert shim.tie_word_embeddings is False
+
+
+def test_parse_gguf_config_matches_layer_census(glm_gguf):
+    from freetoken.models.glm5_next.args import DSA_LAYER, KDA_LAYER
+    from freetoken.models.glm5_next.gguf import parse_gguf_config
+
+    config = parse_gguf_config(_shim(glm_gguf))
+    args = config.glm5_args
+    # the trailing MTP block is dropped, and head_count_kv lays out KDA|DSA
+    assert config.num_layers == 2
+    assert args.layer_types == (KDA_LAYER, DSA_LAYER)
+    assert config.first_k_dense_replace == 0
+    assert config.num_experts == 4 and config.num_experts_per_tok == 2
+    assert args.qk_nope_head_dim == 16 and args.v_head_dim == 16 and args.qk_rope_head_dim == 0
+    assert args.index_kpool == 4 and args.index_kpool_compress and args.index_kpool_always_select_tail
+    assert args.indexer_rope_interleave  # the served fact the GGUF KV predates
+    assert config.expert_quant == "gguf"
+    assert config.swiglu_limit == 10.0
+
+
+def test_legacy_arch_spelling_routes_identically(tmp_path):
+    path = tmp_path / "glm5-legacy.gguf"
+    _make_gguf(str(path), arch="glm5next")
+    assert _shim(str(path)).architectures == ["Glm5NextGGUFForCausalLM"]
+
+
+def test_head_count_kv_fallback_uses_tensor_census(tmp_path):
+    """The pre-list writer (unsloth's first release) is laid out from the tensor names."""
+    from freetoken.models.glm5_next.args import DSA_LAYER, KDA_LAYER
+    from freetoken.models.glm5_next.gguf import _layer_types
+
+    path = tmp_path / "glm5-nolist.gguf"
+    _make_gguf(str(path))
+    shim = _shim(str(path))
+    stripped = type(shim)(
+        architectures=shim.architectures,
+        model_path=shim.model_path,
+        model_type=shim.model_type,
+        metadata={k: v for k, v in shim.metadata.items() if not k.endswith("attention.head_count_kv")},
+        vocab_size=shim.vocab_size,
+        tie_word_embeddings=shim.tie_word_embeddings,
+    )
+    assert _layer_types(stripped, 2) == (KDA_LAYER, DSA_LAYER)
+
+
+def test_reader_state_dict_matches_model(glm_gguf):
+    _tp1()
+    from dataclasses import replace
+
+    from freetoken.models.glm5_next import Glm5NextForCausalLM
+    from freetoken.models.glm5_next.gguf import iter_gguf_weights, parse_gguf_config
+    from freetoken.models.register import checkpoint_quant_config, get_model_spec
+
+    shim = _shim(glm_gguf)
+    config = parse_gguf_config(shim)
+    spec = get_model_spec(shim.architectures[0])
+    config = replace(config, quant=checkpoint_quant_config(glm_gguf, shim, spec))
+    model = Glm5NextForCausalLM(config)
+    want = model.state_dict()
+    got = dict(iter_gguf_weights(glm_gguf, torch.device("cpu"), include_moe_experts=False, include_non_moe=True))
+    assert set(want) == set(got), f"missing={sorted(set(want) - set(got))[:6]} extra={sorted(set(got) - set(want))[:6]}"
+    for k in sorted(want):
+        assert tuple(want[k].shape) == tuple(got[k].shape), k
+
+
+def test_converter_transforms_are_undone(glm_gguf):
+    from freetoken.models.gguf.reader import gguf_tensor_index
+    from freetoken.models.gguf.tensors import float_tensor
+    from freetoken.models.glm5_next.gguf import iter_gguf_weights
+
+    got = dict(iter_gguf_weights(glm_gguf, torch.device("cpu"), include_moe_experts=False, include_non_moe=True))
+    index = gguf_tensor_index(glm_gguf)
+    # A_log: the converter stores -exp(A_log); the reader inverts to the raw log
+    stored = float_tensor(index["blk.0.ssm_a"])
+    assert torch.allclose(got["model.layers.0.self_attn.A_log"], torch.log(-stored))
+    # kv_b: per-head k [lora, nope] (transposed) + v [v, lora] fuse to [heads*(nope+v), lora]
+    k = float_tensor(index["blk.1.attn_k_b.weight"]).transpose(1, 2)
+    v = float_tensor(index["blk.1.attn_v_b.weight"])
+    expect = torch.cat([k, v], dim=1).reshape(-1, 32).to(torch.bfloat16)
+    assert torch.equal(got["model.layers.1.self_attn.kv_b_proj.weight"], expect)
+    # conv1d: q|k|v conv kernels concatenate on the channel axis
+    conv = torch.cat([float_tensor(index[f"blk.0.ssm_conv1d_{q}.weight"]) for q in ("q", "k", "v")], dim=0)
+    assert torch.equal(got["model.layers.0.self_attn.conv1d.weight"], conv.to(torch.bfloat16))
+
+
+def test_to_gguf_maps_the_fused_and_packed_modules(glm_gguf):
+    from freetoken.models.glm5_next.gguf import to_gguf
+
+    assert to_gguf("model.language_model.embed_tokens", {}) == ("token_embd",)
+    assert to_gguf("lm_head", {}) == ("output",)
+    for leaf, gguf_name in (
+        ("q_proj", "attn_q"), ("k_proj", "attn_k"), ("v_proj", "attn_v"),
+        ("b_proj", "ssm_beta"), ("f_a_proj", "ssm_f_a"), ("g_a_proj", "ssm_g_a"),
+    ):
+        assert to_gguf(f"model.language_model.layers.0.self_attn.{leaf}", {}) == (f"blk.0.{gguf_name}",)
+    assert to_gguf("model.language_model.layers.3.mlp.experts.0.gate_proj", {}) == ("blk.3.ffn_gate_exps",)
+    assert to_gguf("model.language_model.layers.3.mlp.gate", {}) == ()

From e08af5aee08b9bfcdc0a6b4074f98f211475969c Mon Sep 17 00:00:00 2001
From: Mukkesh Ganesh <mukmckenzie@gmail.com>
Date: Mon, 19 Oct 2026 18:42:12 -0700
Subject: [PATCH 2/7] fix(gguf): refuse unread scale tensors in glm5-next ggufs

check_scales at config parse like the llama, qwen3 and gemma4 loaders
(review on #721): a .scale / .input_scale outside an NVFP4 weight now
fails with a clear error instead of loading silently unread.
---
 python/freetoken/models/glm5_next/gguf.py | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/python/freetoken/models/glm5_next/gguf.py b/python/freetoken/models/glm5_next/gguf.py
index e3bf275ad4..cb21fb4e3c 100644
--- a/python/freetoken/models/glm5_next/gguf.py
+++ b/python/freetoken/models/glm5_next/gguf.py
@@ -28,7 +28,7 @@
 import torch
 
 from freetoken.models.gguf.reader import GgufTensorInfo, gguf_tensor_index, gguf_tensor_names
-from freetoken.models.gguf.tensors import float_tensor, fused, matrix
+from freetoken.models.gguf.tensors import check_scales, float_tensor, fused, matrix
 
 from .config import parse_config
 
@@ -141,10 +141,16 @@ def _head_dims(shim: "GgufConfigShim") -> tuple[int, int]:
     return int(nope), int(v)
 
 
+def _check_supported(shim: "GgufConfigShim") -> None:
+    check_scales(shim.model_path)
+
+
 def parse_gguf_config(shim: "GgufConfigShim") -> ModelConfig:
     md = shim.metadata
     prefix = shim.model_type
 
+    _check_supported(shim)
+
     def kv(key: str, default=None):
         return md.get(f"{prefix}.{key}", default)
 

From b0ee0d2da1089aa7cd29c511b03a8e6e84ac9569 Mon Sep 17 00:00:00 2001
From: Mukkesh Ganesh <mukmckenzie@gmail.com>
Date: Mon, 19 Oct 2026 19:40:08 -0700
Subject: [PATCH 3/7] fix(gguf): serve the quantized tensors of unsloth dynamic
 glm5-next quants

unsloth's UD quants quantize tensors the AesSedAI-style files keep float:
the MLA kv_b halves (Q8_0), the mHC mixers and the indexer's wk /
weights_proj / compressor gate. kv_b_proj joins the registry's
unquantized_modules (glm_moe_dsa keeps its kv_b dense for the MLA
absorption for the same reason) and the reader dequantizes through the
vendored gguf-py reference on every float-expecting read; wq_b keeps
serving its checkpoint quant packed (attention.py keeps wk and
weights_proj dense). Regression test stores the kv_b halves Q8_0.
---
 python/freetoken/models/glm5_next/gguf.py | 57 ++++++++++++++---------
 python/freetoken/models/register.py       |  3 ++
 tests/models/test_glm5_next_gguf.py       | 39 ++++++++++++++--
 3 files changed, 73 insertions(+), 26 deletions(-)

diff --git a/python/freetoken/models/glm5_next/gguf.py b/python/freetoken/models/glm5_next/gguf.py
index cb21fb4e3c..aaf16a92a8 100644
--- a/python/freetoken/models/glm5_next/gguf.py
+++ b/python/freetoken/models/glm5_next/gguf.py
@@ -11,9 +11,9 @@
 the ``glm5-next`` and the older ``glm5next`` arch spellings) stores KDA's ``A_log``
 pre-transformed as ``-exp(A_log)`` -- inverted at load -- and splits the MLA
 ``kv_b_proj`` into per-head 3-D ``attn_k_b`` / ``attn_v_b`` tensors (k stored
-transposed, [heads, kv_lora, nope] next to [heads, v, kv_lora]); both halves ship
-BF16, so they dequantize and fuse into the dense layout the module's MLA absorption
-reads. The trailing MTP block (``blk.N.nextn.*``, ``nextn_predict_layers == 1``) is
+transposed, [heads, kv_lora, nope] next to [heads, v, kv_lora]); the halves may be
+quantized (dynamic quants store them Q8_0), so they dequantize and fuse into the
+dense layout the module's MLA absorption reads. The trailing MTP block (``blk.N.nextn.*``, ``nextn_predict_layers == 1``) is
 dropped exactly like the HF loader drops the never-read MTP layer; routed experts
 serve from the GGUF expert banks (``freetoken.models.gguf.experts``).
 """
@@ -25,10 +25,12 @@
 from types import SimpleNamespace
 from typing import TYPE_CHECKING, Iterator
 
+import numpy as np
 import torch
 
+from freetoken.layers.quantization.ggml_types import is_quantized
 from freetoken.models.gguf.reader import GgufTensorInfo, gguf_tensor_index, gguf_tensor_names
-from freetoken.models.gguf.tensors import check_scales, float_tensor, fused, matrix
+from freetoken.models.gguf.tensors import check_scales, fused, matrix
 
 from .config import parse_config
 
@@ -63,7 +65,8 @@
     "self_attn.q_a_proj": ("attn_q_a",),
     "self_attn.q_b_proj": ("attn_q_b",),
     "self_attn.kv_a_proj_with_mqa": ("attn_kv_a_mqa",),
-    # both halves are float in every release: the module keeps its dense bf16 kv_b
+    # two tensors, dequantized and fused at load: the module keeps its dense bf16 kv_b
+    # (exempted in the registry's unquantized_modules, so quantized halves are fine too)
     "self_attn.kv_b_proj": ("attn_k_b", "attn_v_b"),
     # kpool indexer
     "self_attn.indexer.wq_b": ("indexer.attn_q_b",),
@@ -254,10 +257,24 @@ def need(key: str):
 # Weights
 # ----------------------------------------------------------------------------------------------
 
+def _float(info: GgufTensorInfo) -> torch.Tensor:
+    """A float tensor in torch order, dequantizing packed ggml rows: dynamic quants quantize
+    tensors the module consumes as floats (the kv_b halves, the mHC mixers, the compressor gate)."""
+    if not is_quantized(info.ggml_type):
+        from freetoken.models.gguf.tensors import float_tensor
+
+        return float_tensor(info)
+    from freetoken.third_party.gguf import quants
+    from freetoken.third_party.gguf.constants import GGMLQuantizationType
+
+    flat = quants.dequantize(np.array(info.data()), GGMLQuantizationType(info.ggml_type))
+    return torch.from_numpy(flat).view(*reversed(info.ne))
+
+
 def _kv_b(kb: GgufTensorInfo, vb: GgufTensorInfo, num_heads: int, kv_lora: int) -> torch.Tensor:
     """Per-head k [kv_lora, nope] (stored transposed) + v [v, kv_lora] -> the module's fused dense [heads * (nope + v), kv_lora]."""
-    k = float_tensor(kb).transpose(1, 2)  # [heads, nope, kv_lora]
-    fused_w = torch.cat([k, float_tensor(vb)], dim=1)
+    k = _float(kb).transpose(1, 2)  # [heads, nope, kv_lora]
+    fused_w = torch.cat([k, _float(vb)], dim=1)
     assert fused_w.shape[0] == num_heads, (fused_w.shape, num_heads)
     return fused_w.reshape(num_heads * fused_w.shape[1], kv_lora).to(torch.bfloat16).contiguous()
 
@@ -284,7 +301,7 @@ def t(name: str) -> GgufTensorInfo:
         return index[name if name in index else f"{name}.weight"]
 
     def bf16(name: str) -> torch.Tensor:
-        return float_tensor(t(name)).to(torch.bfloat16)
+        return _float(t(name)).to(torch.bfloat16)
 
     yield from fused("model.embed_tokens", [t("token_embd")], [matrix(t("token_embd"))], hidden)
     yield from fused("lm_head", [t("output")], [matrix(t("output"))], hidden)
@@ -297,7 +314,7 @@ def bf16(name: str) -> torch.Tensor:
         # mHC mixing tensors, fp32 on every layer
         for sub in ("attn", "ffn"):
             for part in ("fn", "base", "scale"):
-                yield f"{pre}.hc_{sub}_{part}", float_tensor(t(f"{blk}.hc_{sub}_{part}"))
+                yield f"{pre}.hc_{sub}_{part}", _float(t(f"{blk}.hc_{sub}_{part}"))
 
         if args.is_kda_layer(layer):
             sa = f"{pre}.self_attn"
@@ -305,14 +322,14 @@ def bf16(name: str) -> torch.Tensor:
             group = [t(f"{blk}.{n}") for n in ("attn_q", "attn_k", "attn_v", "ssm_beta", "ssm_f_a", "ssm_g_a")]
             yield from fused(f"{sa}.in_proj", group, [matrix(i) for i in group], hidden)
             # the GGUF conv kernels already carry the [channels, 1, kernel] singleton dim
-            conv = torch.cat([float_tensor(t(f"{blk}.ssm_conv1d_{q}")) for q in ("q", "k", "v")], dim=0)
+            conv = torch.cat([_float(t(f"{blk}.ssm_conv1d_{q}")) for q in ("q", "k", "v")], dim=0)
             yield f"{sa}.conv1d.weight", conv.to(torch.bfloat16)
             for proj, src, k in (("f_b_proj", "ssm_f_b", d), ("g_b_proj", "ssm_g_b", d), ("o_proj", "attn_output", p)):
                 info = t(f"{blk}.{src}")
                 yield from fused(f"{sa}.{proj}", [info], [matrix(info)], k)
             # the converter stores A_log pre-transformed as -exp(A_log); the kernels want the raw log
-            yield f"{sa}.A_log", torch.log(-float_tensor(t(f"{blk}.ssm_a")))
-            yield f"{sa}.dt_bias", float_tensor(t(f"{blk}.ssm_dt.bias"))
+            yield f"{sa}.A_log", torch.log(-_float(t(f"{blk}.ssm_a")))
+            yield f"{sa}.dt_bias", _float(t(f"{blk}.ssm_dt.bias"))
             yield f"{sa}.o_norm.weight", bf16(f"{blk}.ssm_norm")
         else:
             sa = f"{pre}.self_attn"
@@ -329,17 +346,15 @@ def bf16(name: str) -> torch.Tensor:
             )
             yield f"{sa}.q_a_layernorm.weight", bf16(f"{blk}.attn_q_a_norm")
             yield f"{sa}.kv_a_layernorm.weight", bf16(f"{blk}.attn_kv_a_norm")
-            for proj, src in (
-                ("indexer.wq_b", "indexer.attn_q_b"),
-                ("indexer.wk", "indexer.attn_k"),
-                ("indexer.weights_proj", "indexer.proj"),
-            ):
-                info = t(f"{blk}.{src}")
-                yield from fused(f"{sa}.{proj}", [info], [matrix(info)], int(info.ne[0]))
+            # wq_b serves its checkpoint quant (packed); wk / weights_proj are dense modules
+            # (glm_moe_dsa's indexer reasoning), dequantized at load when the file quantized them
+            yield from fused(f"{sa}.indexer.wq_b", [t(f"{blk}.indexer.attn_q_b")], [matrix(t(f"{blk}.indexer.attn_q_b"))], args.q_lora_rank)
+            yield f"{sa}.indexer.wk.weight", _float(t(f"{blk}.indexer.attn_k")).to(torch.bfloat16)
+            yield f"{sa}.indexer.weights_proj.weight", _float(t(f"{blk}.indexer.proj")).to(torch.bfloat16)
             yield f"{sa}.indexer.k_norm.weight", bf16(f"{blk}.indexer.k_norm")
             yield f"{sa}.indexer.k_norm.bias", bf16(f"{blk}.indexer.k_norm.bias")
             yield f"{sa}.indexer.index_kpool_compress_gate", bf16(f"{blk}.indexer_compressor_gate")
-            yield f"{sa}.indexer.index_kpool_compress_ape", float_tensor(t(f"{blk}.indexer_compressor_ape"))
+            yield f"{sa}.indexer.index_kpool_compress_ape", _float(t(f"{blk}.indexer_compressor_ape"))
 
         mlp = f"{pre}.mlp"
         if layer < config.first_k_dense_replace:
@@ -352,7 +367,7 @@ def bf16(name: str) -> torch.Tensor:
                 yield from fused(f"{mlp}.{proj}", [info], [matrix(info)], k)
         else:
             yield f"{mlp}.gate.weight", bf16(f"{blk}.ffn_gate_inp")
-            yield f"{mlp}.e_score_correction_bias", float_tensor(t(f"{blk}.exp_probs_b.bias"))
+            yield f"{mlp}.e_score_correction_bias", _float(t(f"{blk}.exp_probs_b.bias"))
             shared_i = config.moe_intermediate_size * max(1, config.n_shared_experts)
             for proj, src, k in (
                 ("gate_proj", "ffn_gate_shexp", hidden),
diff --git a/python/freetoken/models/register.py b/python/freetoken/models/register.py
index b892d5cfcf..0ef6b0a4a3 100644
--- a/python/freetoken/models/register.py
+++ b/python/freetoken/models/register.py
@@ -427,6 +427,9 @@ class ModelSpec:
         iter_weights="iter_gguf_weights",
         checkpoint_roots=_LANGUAGE_MODEL_ROOT,
         packed_modules_mapping=_GLM5_NEXT_PACKED,
+        # the MLA kv_b ships as two per-head tensors (attn_k_b transposed + attn_v_b), quantized in
+        # dynamic quants (unsloth UD); the reader dequantizes and fuses them into the dense module
+        unquantized_modules=("*.self_attn.kv_b_proj",),
     ),
 }
 
diff --git a/tests/models/test_glm5_next_gguf.py b/tests/models/test_glm5_next_gguf.py
index 085fffd727..5beb551317 100644
--- a/tests/models/test_glm5_next_gguf.py
+++ b/tests/models/test_glm5_next_gguf.py
@@ -76,12 +76,13 @@ def _gguf_writer(path, kvs, tensors):
 _F32, _Q8_0, _IQ3_S, _IQ4_XS, _BF16 = 0, 8, 21, 23, 30
 
 
-def _make_gguf(path, *, n_layers=2, n_mtp=1, arch="glm5-next", head_kv_list=None):
+def _make_gguf(path, *, n_layers=2, n_mtp=1, arch="glm5-next", head_kv_list=None, kv_b_q8_0=False):
     """A miniature glm5-next layout: layer 0 KDA, layer 1 DSA, one trailing MTP block."""
     import numpy as np
 
-    # hidden/q_lora keep Q8_0 rows a multiple of 32, expert rows a multiple of 256 (IQ3_S/IQ4_XS blocks)
-    H, D, KDA_H, KDA_D = 8, 32, 4, 8
+    # hidden/q_lora keep Q8_0 rows a multiple of 32, expert rows a multiple of 256 (IQ3_S/IQ4_XS
+    # blocks); the kv_b halves block on nope/v head rows, so D doubles when they store Q8_0
+    H, D, KDA_H, KDA_D = 8, 64 if kv_b_q8_0 else 32, 4, 8
     QKV = KDA_H * KDA_D  # 32
     I, E, V = 512, 4, 64
 
@@ -150,8 +151,12 @@ def _make_gguf(path, *, n_layers=2, n_mtp=1, arch="glm5-next", head_kv_list=None
             tensors.append((f"blk.{blk}.attn_q_a.weight", (_Q8_0, (hidden, q_lora), q8(hidden, q_lora))))
             tensors.append((f"blk.{blk}.attn_q_b.weight", (_Q8_0, (q_lora, H * (D // 2)), q8(q_lora, H * (D // 2)))))
             tensors.append((f"blk.{blk}.attn_kv_a_mqa.weight", (_BF16, (hidden, D), bf16(hidden * D))))
-            tensors.append((f"blk.{blk}.attn_k_b.weight", (_BF16, (D // 2, D, H), bf16(D * (D // 2) * H))))
-            tensors.append((f"blk.{blk}.attn_v_b.weight", (_BF16, (D, D // 2, H), bf16(D * (D // 2) * H))))
+            if kv_b_q8_0:
+                tensors.append((f"blk.{blk}.attn_k_b.weight", (_Q8_0, (D // 2, D, H), q8(D // 2, D * H))))
+                tensors.append((f"blk.{blk}.attn_v_b.weight", (_Q8_0, (D, D // 2, H), q8(D, (D // 2) * H))))
+            else:
+                tensors.append((f"blk.{blk}.attn_k_b.weight", (_BF16, (D // 2, D, H), bf16(D * (D // 2) * H))))
+                tensors.append((f"blk.{blk}.attn_v_b.weight", (_BF16, (D, D // 2, H), bf16(D * (D // 2) * H))))
             tensors.append((f"blk.{blk}.attn_output.weight", (_Q8_0, (H * (D // 2), hidden), q8(H * (D // 2), hidden))))
             tensors.append((f"blk.{blk}.attn_q_a_norm.weight", (_F32, (q_lora,), f32(q_lora).tobytes())))
             tensors.append((f"blk.{blk}.attn_kv_a_norm.weight", (_F32, (D,), f32(D).tobytes())))
@@ -271,6 +276,30 @@ def test_reader_state_dict_matches_model(glm_gguf):
         assert tuple(want[k].shape) == tuple(got[k].shape), k
 
 
+def test_quantized_kv_b_halves_serve_dense(tmp_path):
+    """Dynamic quants (unsloth UD) store the per-head kv_b halves Q8_0, not bf16: the
+    module stays dense -- the reader dequantizes and fuses -- instead of refusing it."""
+    _tp1()
+    from dataclasses import replace
+
+    from freetoken.models.glm5_next import Glm5NextForCausalLM
+    from freetoken.models.glm5_next.gguf import iter_gguf_weights, parse_gguf_config
+    from freetoken.models.register import checkpoint_quant_config, get_model_spec
+
+    path = str(tmp_path / "glm5-kvq8.gguf")
+    _make_gguf(path, kv_b_q8_0=True)
+    shim = _shim(path)
+    spec = get_model_spec(shim.architectures[0])
+    config = replace(parse_gguf_config(shim), quant=checkpoint_quant_config(path, shim, spec))
+    model = Glm5NextForCausalLM(config)
+    assert config.quant.scheme_for("model.layers.1.self_attn.kv_b_proj") is None
+    got = dict(iter_gguf_weights(path, torch.device("cpu"), include_moe_experts=False, include_non_moe=True))
+    want = model.state_dict()
+    assert set(want) == set(got), f"missing={sorted(set(want) - set(got))[:6]} extra={sorted(set(got) - set(want))[:6]}"
+    for k in sorted(want):
+        assert tuple(want[k].shape) == tuple(got[k].shape), k
+
+
 def test_converter_transforms_are_undone(glm_gguf):
     from freetoken.models.gguf.reader import gguf_tensor_index
     from freetoken.models.gguf.tensors import float_tensor

From 137697e0847f95729966ba95a4fa99c211a6a8a3 Mon Sep 17 00:00:00 2001
From: Mukkesh Ganesh <mukmckenzie@gmail.com>
Date: Mon, 19 Oct 2026 20:05:10 -0700
Subject: [PATCH 4/7] fix(gguf): treat the glm5 pre-tokenizer spelling like
 glm4

llama-vocab.cpp maps both spellings to CHATGLM4 with ignore_merges;
unsloth writes glm4 and AesSedAI's writer glm5 for the same vocabulary.
Without the mapping a glm5 file loads but silently mis-tokenizes
(tok_compare: 22,840/153,725 vocab words differ from the HF reference;
0 everywhere with it).
---
 python/freetoken/models/gguf/tokenizer.py |  7 +--
 tests/models/test_gguf_tokenizer.py       | 56 +++++++++++++++++++++++
 2 files changed, 60 insertions(+), 3 deletions(-)
 create mode 100644 tests/models/test_gguf_tokenizer.py

diff --git a/python/freetoken/models/gguf/tokenizer.py b/python/freetoken/models/gguf/tokenizer.py
index 3945c05db6..26e447aad2 100644
--- a/python/freetoken/models/gguf/tokenizer.py
+++ b/python/freetoken/models/gguf/tokenizer.py
@@ -23,7 +23,7 @@
 ))
 
 # Llama 3 and GLM pre-tokenizers, whose HF tokenizer and llama.cpp take a word that is one vocabulary token as is instead of merging it
-_IGNORE_MERGES_PRE = frozenset(("llama3", "llama-v3", "llama-bpe", "glm4"))
+_IGNORE_MERGES_PRE = frozenset(("llama3", "llama-v3", "llama-bpe", "glm4", "glm5"))
 
 
 def _add_bos(meta: dict) -> bool:
@@ -81,11 +81,12 @@ def load_gguf_tokenizer(model_path: str):
     meta = load_gguf_metadata(model_path)
     fast = _fix_added_tokens(fast, meta)
     pre = meta.get("tokenizer.ggml.pre") if meta.get("tokenizer.ggml.model") == "gpt2" else None
-    if pre == "glm4":
+    if pre in ("glm4", "glm5"):
+        # llama.cpp spells the same GLM pre-tokenizer "glm4" and "glm5" (llama-vocab.cpp maps both
+        # to CHATGLM4 with ignore_merges); transformers maps no split for either
         from tokenizers import Regex, pre_tokenizers
         from transformers.integrations.gguf.gguf_tokenizer_mapping import GGUF_PRE_TOKENIZER_SPLITS
 
-        # transformers maps no split for glm4, which the HF tokenizer and llama.cpp split like Llama 3
         fast.pre_tokenizer = pre_tokenizers.Sequence([
             pre_tokenizers.Split(Regex(GGUF_PRE_TOKENIZER_SPLITS["llama3"]), behavior="isolated"),
             pre_tokenizers.ByteLevel(add_prefix_space=False, use_regex=False),
diff --git a/tests/models/test_gguf_tokenizer.py b/tests/models/test_gguf_tokenizer.py
new file mode 100644
index 0000000000..d7b592efb6
--- /dev/null
+++ b/tests/models/test_gguf_tokenizer.py
@@ -0,0 +1,56 @@
+"""The GGUF tokenizer: pre-tokenizer spellings llama.cpp writes and how FreeToken maps them."""
+
+from __future__ import annotations
+
+import struct
+
+# GGUF v3 value types (the vendored gguf-py GGUFValueType numbering)
+_T_UINT32, _T_FLOAT32, _T_STRING, _T_ARRAY = 4, 6, 8, 9
+
+# a byte-level BPE with no merges: "Hello" is one vocabulary token, and without
+# ignore_merges the encoder falls back to its four characters
+_TOKENS = ["d", "o", "n", "'", "t", "don't", "Hello", "H", "e", "l", "!"]
+
+
+def _pack_val(v):
+    if isinstance(v, str):
+        b = v.encode()
+        return struct.pack("<Q", len(b)) + b
+    if isinstance(v, int):
+        return struct.pack("<I", v)
+    if isinstance(v, float):
+        return struct.pack("<f", v)
+    if isinstance(v, list):
+        elem = {int: _T_UINT32, float: _T_FLOAT32, str: _T_STRING}[type(v[0])]
+        return struct.pack("<I", elem) + struct.pack("<Q", len(v)) + b"".join(_pack_val(x) for x in v)
+    raise TypeError(v)
+
+
+def _tokenizer_gguf(path, pre: str) -> str:
+    """A header-only GGUF carrying a gpt2 tokenizer with the given ``tokenizer.ggml.pre``."""
+    kvs = {
+        "general.architecture": (_T_STRING, "glm5-next"),
+        "tokenizer.ggml.model": (_T_STRING, "gpt2"),
+        "tokenizer.ggml.pre": (_T_STRING, pre),
+        "tokenizer.ggml.tokens": (_T_ARRAY, list(_TOKENS)),
+        "tokenizer.ggml.token_type": (_T_ARRAY, [1] * len(_TOKENS)),
+        "tokenizer.ggml.scores": (_T_ARRAY, [0.0] * len(_TOKENS)),
+    }
+    with open(path, "wb") as f:
+        f.write(b"GGUF" + struct.pack("<I", 3) + struct.pack("<Q", 0) + struct.pack("<Q", len(kvs)))
+        for k, (t, v) in kvs.items():
+            f.write(struct.pack("<Q", len(k.encode())) + k.encode() + struct.pack("<I", t) + _pack_val(v))
+    return str(path)
+
+
+def test_glm5_pre_routes_like_glm4(tmp_path):
+    """llama.cpp maps its "glm4" and "glm5" spellings to the same pre-tokenizer (CHATGLM4
+    with ignore_merges); a glm5 file must encode exactly like the glm4 one."""
+    from freetoken.models.gguf.tokenizer import load_gguf_tokenizer
+
+    glm4 = load_gguf_tokenizer(_tokenizer_gguf(tmp_path / "tok4.gguf", "glm4"))
+    glm5 = load_gguf_tokenizer(_tokenizer_gguf(tmp_path / "tok5.gguf", "glm5"))
+    for text in ("Hello!", "don't", "don't Hello!"):
+        assert glm4.encode(text) == glm5.encode(text), text
+    # the treatment bites: the whole-word token wins over the character fallback
+    assert glm5.encode("Hello!") == [_TOKENS.index("Hello"), _TOKENS.index("!")]

From 18489891512f4b9558daefe962d6a8260ea5506d Mon Sep 17 00:00:00 2001
From: Mukkesh Ganesh <mukmckenzie@gmail.com>
Date: Mon, 19 Oct 2026 20:34:16 -0700
Subject: [PATCH 5/7] fix(gguf): size the mmq tail padding by ggml type and k

pad_rows added one zero row of k columns, which covers the bytes MMQ
reads past the last row only when k is at least half a padding unit
(512); glm5-next's KDA f_b / g_b (k = linear head dim 128, Q8_0 in
dynamic quants) are the first packed tensors below that and died at the
first mul_mat. pad_rows now takes the ggml type and returns enough whole
rows to cover mmq_tail_bytes for any (type, k), consistently in the
reader's fused(), the gguf linear and embedding params and the expert
host banks. Found serving the real unsloth UD-IQ4_XS: the dry load
never runs a forward.
---
 .../layers/quantization/embedding/gguf.py          |  2 +-
 python/freetoken/layers/quantization/ggml_types.py |  5 +++--
 .../freetoken/layers/quantization/linear/gguf.py   |  2 +-
 python/freetoken/models/gguf/experts.py            |  8 ++++----
 python/freetoken/models/gguf/tensors.py            |  2 +-
 tests/models/test_glm5_next_gguf.py                | 14 ++++++++++++++
 6 files changed, 24 insertions(+), 9 deletions(-)

diff --git a/python/freetoken/layers/quantization/embedding/gguf.py b/python/freetoken/layers/quantization/embedding/gguf.py
index 56c72c2d6a..98f12dd9cc 100644
--- a/python/freetoken/layers/quantization/embedding/gguf.py
+++ b/python/freetoken/layers/quantization/embedding/gguf.py
@@ -45,4 +45,4 @@ class GGUFEmbeddingMethod(EmbeddingMethod):
     def create_weights(self, layer: Any) -> None:
         (ggml_type,) = gguf_types(self.cfg.scheme)
         h = self.cfg.embedding_dim
-        layer.weight = torch.empty(self.cfg.num_embeddings + pad_rows(h), row_bytes(ggml_type, h), dtype=torch.uint8)
+        layer.weight = torch.empty(self.cfg.num_embeddings + pad_rows(ggml_type, h), row_bytes(ggml_type, h), dtype=torch.uint8)
diff --git a/python/freetoken/layers/quantization/ggml_types.py b/python/freetoken/layers/quantization/ggml_types.py
index 262c5668d3..95c2779311 100644
--- a/python/freetoken/layers/quantization/ggml_types.py
+++ b/python/freetoken/layers/quantization/ggml_types.py
@@ -44,9 +44,10 @@ def row_bytes(ggml_type: int, k: int) -> int:
     return k // block * size
 
 
-def pad_rows(k: int) -> int:
+def pad_rows(ggml_type: int, k: int) -> int:
     """Zero rows to append after a packed [rows, K] matrix so ggml's tail reads stay inside it."""
-    return 0 if k % MATRIX_ROW_PADDING == 0 else 1
+    tail = mmq_tail_bytes(ggml_type, k)
+    return 0 if tail == 0 else max(1, -(-tail // row_bytes(ggml_type, k)))
 
 
 def mmq_tail_bytes(ggml_type: int, k: int) -> int:
diff --git a/python/freetoken/layers/quantization/linear/gguf.py b/python/freetoken/layers/quantization/linear/gguf.py
index 41f61edf88..badbe92b49 100644
--- a/python/freetoken/layers/quantization/linear/gguf.py
+++ b/python/freetoken/layers/quantization/linear/gguf.py
@@ -54,7 +54,7 @@ def create_weights(self, layer: Any) -> None:
         k = g.in_features
         for i, s in enumerate(segs):
             if is_quantized(s.ggml_type):
-                setattr(layer, segment_param(i), torch.empty(s.rows + pad_rows(k), row_bytes(s.ggml_type, k), dtype=torch.uint8))
+                setattr(layer, segment_param(i), torch.empty(s.rows + pad_rows(s.ggml_type, k), row_bytes(s.ggml_type, k), dtype=torch.uint8))
             else:
                 setattr(layer, segment_param(i), torch.empty(s.rows, k))
         if g.scheme.weight.scale is not None:
diff --git a/python/freetoken/models/gguf/experts.py b/python/freetoken/models/gguf/experts.py
index c21fff9fa2..0efb5982fb 100644
--- a/python/freetoken/models/gguf/experts.py
+++ b/python/freetoken/models/gguf/experts.py
@@ -40,10 +40,10 @@ def _drop_page_cache(info: GgufTensorInfo) -> None:
         pass
 
 
-def _device_bank(shape: tuple[int, ...], k: int, dtype: torch.dtype, device: torch.device) -> torch.Tensor:
+def _device_bank(shape: tuple[int, ...], ggml_type: int, k: int, dtype: torch.dtype, device: torch.device) -> torch.Tensor:
     """An [E, rows, row] device bank; a zero row follows the last one when ggml's MMQ tiles read past it."""
     experts, rows, row = shape
-    flat = torch.empty(experts * rows + pad_rows(k), row, dtype=dtype, device=device)
+    flat = torch.empty(experts * rows + pad_rows(ggml_type, k), row, dtype=dtype, device=device)
     flat[experts * rows :].zero_()
     return flat[: experts * rows].view(shape)
 
@@ -101,8 +101,8 @@ def load_gguf_expert_banks(model_path: str, num_layers: int, *, first_layer: int
                 banks = {role: bank.tensor for role, bank in host.items()}
             else:
                 banks = {
-                    "gate_up": _device_bank(gate_up_shape, gate.ne[0], rows[0].dtype, device),
-                    "down": _device_bank(tuple(d.shape), down.ne[0], d.dtype, device),
+                    "gate_up": _device_bank(gate_up_shape, gate.ggml_type, gate.ne[0], rows[0].dtype, device),
+                    "down": _device_bank(tuple(d.shape), down.ggml_type, down.ne[0], d.dtype, device),
                 }
                 if scaled:
                     banks["global"] = torch.empty(experts, 4, dtype=torch.float32, device=device)
diff --git a/python/freetoken/models/gguf/tensors.py b/python/freetoken/models/gguf/tensors.py
index 83452d957a..f2cb0e0038 100644
--- a/python/freetoken/models/gguf/tensors.py
+++ b/python/freetoken/models/gguf/tensors.py
@@ -85,7 +85,7 @@ def fused(prefix: str, infos: list[GgufTensorInfo], parts: list[torch.Tensor], k
         rows = parts[seg.first_part : seg.first_part + seg.num_parts]
         zeros = pad if i == len(segs) - 1 else 0
         if is_quantized(seg.ggml_type):
-            zeros += pad_rows(k)
+            zeros += pad_rows(seg.ggml_type, k)
             dtype = torch.uint8
         else:
             rows = [r.to(torch.bfloat16) for r in rows]
diff --git a/tests/models/test_glm5_next_gguf.py b/tests/models/test_glm5_next_gguf.py
index 5beb551317..39ed222b61 100644
--- a/tests/models/test_glm5_next_gguf.py
+++ b/tests/models/test_glm5_next_gguf.py
@@ -332,3 +332,17 @@ def test_to_gguf_maps_the_fused_and_packed_modules(glm_gguf):
         assert to_gguf(f"model.language_model.layers.0.self_attn.{leaf}", {}) == (f"blk.0.{gguf_name}",)
     assert to_gguf("model.language_model.layers.3.mlp.experts.0.gate_proj", {}) == ("blk.3.ffn_gate_exps",)
     assert to_gguf("model.language_model.layers.3.mlp.gate", {}) == ()
+
+
+def test_fused_covers_the_mmq_tail():
+    """A packed segment must cover the bytes MMQ reads past the last row: the KDA f_b / g_b
+    (K = linear head dim 128) are the family's first K below half a padding unit."""
+    from types import SimpleNamespace
+
+    from freetoken.layers.quantization.ggml_types import mmq_tail_bytes, row_bytes
+    from freetoken.models.gguf.tensors import fused
+
+    k = 128
+    part = torch.zeros(96, row_bytes(8, k), dtype=torch.uint8)  # Q8_0
+    out = dict(fused("l0.self_attn.f_b_proj", [SimpleNamespace(ggml_type=8)], [part], k))
+    assert out["l0.self_attn.f_b_proj.weight"].numel() >= 96 * row_bytes(8, k) + mmq_tail_bytes(8, k)

From 1d61f1224f33e3f80e15ecda7b6c5db593fff548 Mon Sep 17 00:00:00 2001
From: Mukkesh Ganesh <mukmckenzie@gmail.com>
Date: Mon, 19 Oct 2026 22:20:06 -0700
Subject: [PATCH 6/7] fix(gguf): take the older glm5-next writer variants in
 stride

Two long-tail writer variants the full check sweep found (the GSQ-RCO
lineage alone is ~57k downloads/month):

- the conv kernels with a trailing unit dim: llama.cpp's glm5-next
  loader tries that 4-D shape before the 3-D one, so trailing unit dims
  in ne are dropped on float reads (they carry no elements).
- attention.head_count_kv as the generic scalar (all blocks): wrong for
  the hybrid -- llama.cpp broadcasts it and then fails tensor creation
  -- so only the list is trusted and a scalar falls to the tensor-name
  census like the pre-list writer.
---
 python/freetoken/models/glm5_next/gguf.py |  16 +-
 tests/models/test_glm5_next_gguf.py       | 705 ++++++++++++----------
 2 files changed, 383 insertions(+), 338 deletions(-)

diff --git a/python/freetoken/models/glm5_next/gguf.py b/python/freetoken/models/glm5_next/gguf.py
index aaf16a92a8..7fb8f825f2 100644
--- a/python/freetoken/models/glm5_next/gguf.py
+++ b/python/freetoken/models/glm5_next/gguf.py
@@ -115,7 +115,10 @@ def _layer_types(shim: "GgufConfigShim", num_layers: int) -> tuple[str, ...]:
 
     md = shim.metadata
     per_block = md.get(f"{shim.model_type}.attention.head_count_kv")
-    if per_block is not None and len(per_block) >= num_layers:
+    # the new writer carries the per-block KDA/MLA layout as a list; the generic GGUF spelling is a
+    # scalar (all blocks), which is wrong for the hybrid -- llama.cpp broadcasts it and then fails
+    # tensor creation -- so only a list is trusted and everything else falls to the census
+    if isinstance(per_block, list) and len(per_block) >= num_layers:
         return tuple(DSA_LAYER if int(kv) else KDA_LAYER for kv in per_block[:num_layers])
     names = gguf_tensor_names(shim.model_path)
     if not names:
@@ -259,16 +262,21 @@ def need(key: str):
 
 def _float(info: GgufTensorInfo) -> torch.Tensor:
     """A float tensor in torch order, dequantizing packed ggml rows: dynamic quants quantize
-    tensors the module consumes as floats (the kv_b halves, the mHC mixers, the compressor gate)."""
+    tensors the module consumes as floats (the kv_b halves, the mHC mixers, the compressor gate).
+    Trailing unit dims in ``ne`` are dropped -- some writers ship the conv kernels 4-D
+    (llama.cpp's glm5-next loader tries that shape first) and a trailing 1 carries no elements."""
+    ne = info.ne
+    while len(ne) > 1 and ne[-1] == 1:
+        ne = ne[:-1]
     if not is_quantized(info.ggml_type):
         from freetoken.models.gguf.tensors import float_tensor
 
-        return float_tensor(info)
+        return float_tensor(info).reshape(tuple(reversed(ne)))
     from freetoken.third_party.gguf import quants
     from freetoken.third_party.gguf.constants import GGMLQuantizationType
 
     flat = quants.dequantize(np.array(info.data()), GGMLQuantizationType(info.ggml_type))
-    return torch.from_numpy(flat).view(*reversed(info.ne))
+    return torch.from_numpy(flat).view(*reversed(ne))
 
 
 def _kv_b(kb: GgufTensorInfo, vb: GgufTensorInfo, num_heads: int, kv_lora: int) -> torch.Tensor:
diff --git a/tests/models/test_glm5_next_gguf.py b/tests/models/test_glm5_next_gguf.py
index 39ed222b61..fb6b24c60a 100644
--- a/tests/models/test_glm5_next_gguf.py
+++ b/tests/models/test_glm5_next_gguf.py
@@ -1,337 +1,340 @@
-"""glm5-next GGUF: config parse and weight-reader mapping against a synthetic checkpoint.
-
-Builds a tiny two-layer (KDA + DSA) glm5-next GGUF in tmp -- geometry scaled down but
-every tensor, KV key and converter quirk of the real writer present (A_log stored as
-``-exp(A_log)``, the per-head ``attn_k_b``/``attn_v_b`` split with k transposed, the
-per-block ``head_count_kv`` list, the trailing MTP block) -- then checks the config the
-shim derives and the state dict the reader yields: names complete against the model's,
-kv_b fused to the module's dense layout, A_log inverted, conv1d concatenation.
-"""
-
-from __future__ import annotations
-
-import struct
-
-import pytest
-import torch
-
-from freetoken.distributed import set_tp_info, try_get_tp_info
-
-# GGUF v3 value types (the vendored gguf-py GGUFValueType numbering)
-_T_UINT32, _T_FLOAT32, _T_BOOL, _T_STRING, _T_ARRAY, _T_UINT64 = 4, 6, 7, 8, 9, 10
-
-
-def _tp1():
-    if try_get_tp_info() is None:
-        set_tp_info(rank=0, size=1)
-
-
-def _pack_val(v):
-    if isinstance(v, str):
-        b = v.encode()
-        return struct.pack("<Q", len(b)) + b
-    if isinstance(v, bool):
-        return struct.pack("<B", int(v))
-    if isinstance(v, int):
-        return struct.pack("<I", v)
-    if isinstance(v, float):
-        return struct.pack("<f", v)
-    if isinstance(v, (list, tuple)):
-        assert v and all(isinstance(x, type(v[0])) for x in v), "homogeneous arrays only"
-        elem_type = {int: _T_UINT32, float: _T_FLOAT32, bool: _T_BOOL, str: _T_STRING}[type(v[0])]
-        body = b"".join(_pack_val(x) for x in v)
-        return struct.pack("<I", elem_type) + struct.pack("<Q", len(v)) + body
-    raise TypeError(v)
-
-
-def _gguf_writer(path, kvs, tensors):
-    """A minimal GGUF v3 writer: header + KV section + tensor infos + data, little-endian."""
-    kv_blob = b"".join(
-        struct.pack("<Q", len(k.encode())) + k.encode() + struct.pack("<I", t) + _pack_val(v)
-        for k, (t, v) in kvs.items()
-    )
-
-    infos, data, offset = b"", b"", 0
-    ALIGN = 32
-    for name, (ggml_type, ne, payload) in tensors:
-        ne = tuple(ne)
-        infos += struct.pack("<Q", len(name.encode())) + name.encode()
-        infos += struct.pack("<I", len(ne)) + b"".join(struct.pack("<Q", d) for d in ne)
-        infos += struct.pack("<I", ggml_type)
-        pad = (-offset) % ALIGN
-        infos += struct.pack("<Q", offset + pad)
-        offset += pad + len(payload)
-        data += b"\x00" * pad + payload
-
-    with open(path, "wb") as f:
-        f.write(b"GGUF" + struct.pack("<I", 3))
-        f.write(struct.pack("<Q", len(tensors)) + struct.pack("<Q", len(kvs)))
-        f.write(kv_blob)
-        f.write(infos)
-        f.write(b"\x00" * ((-f.tell()) % ALIGN))
-        f.write(data)
-
-
-# ggml type ids
-_F32, _Q8_0, _IQ3_S, _IQ4_XS, _BF16 = 0, 8, 21, 23, 30
-
-
-def _make_gguf(path, *, n_layers=2, n_mtp=1, arch="glm5-next", head_kv_list=None, kv_b_q8_0=False):
-    """A miniature glm5-next layout: layer 0 KDA, layer 1 DSA, one trailing MTP block."""
-    import numpy as np
-
-    # hidden/q_lora keep Q8_0 rows a multiple of 32, expert rows a multiple of 256 (IQ3_S/IQ4_XS
-    # blocks); the kv_b halves block on nope/v head rows, so D doubles when they store Q8_0
-    H, D, KDA_H, KDA_D = 8, 64 if kv_b_q8_0 else 32, 4, 8
-    QKV = KDA_H * KDA_D  # 32
-    I, E, V = 512, 4, 64
-
-    rng = np.random.default_rng(0)
-    f32 = lambda *shape: rng.standard_normal(shape).astype(np.float32)
-    bf16 = lambda n: (rng.standard_normal(n).astype(np.float32).view(np.uint32) >> 16).astype(np.uint16).tobytes()
-    q8 = lambda k, rows: np.zeros(rows * (k // 32) * 34, dtype=np.uint8).tobytes()  # placeholder packed rows
-    iq3 = lambda k, rows, e: np.zeros(rows * e * (k // 256) * 110, dtype=np.uint8).tobytes()
-    iq4 = lambda k, rows, e: np.zeros(rows * e * (k // 256) * 144, dtype=np.uint8).tobytes()
-
-    kv_heads = head_kv_list if head_kv_list is not None else ([0, 1] + [1] * n_mtp)
-    hidden = H * D  # 128
-    q_lora = 32
-    kvs = {
-        "general.architecture": (_T_STRING, arch),
-        "general.name": (_T_STRING, "glm5-next-test"),
-        f"{arch}.block_count": (_T_UINT32, n_layers + n_mtp),
-        f"{arch}.context_length": (_T_UINT32, 512),
-        f"{arch}.embedding_length": (_T_UINT32, hidden),
-        f"{arch}.feed_forward_length": (_T_UINT32, I),
-        f"{arch}.attention.head_count": (_T_UINT32, H),
-        f"{arch}.attention.head_count_kv": (_T_ARRAY, kv_heads),
-        f"{arch}.attention.layer_norm_rms_epsilon": (_T_FLOAT32, 1e-6),
-        f"{arch}.attention.q_lora_rank": (_T_UINT32, q_lora),
-        f"{arch}.attention.kv_lora_rank": (_T_UINT32, D),
-        f"{arch}.attention.key_length_mla": (_T_UINT32, D // 2),
-        f"{arch}.attention.value_length_mla": (_T_UINT32, D // 2),
-        f"{arch}.attention.indexer.head_count": (_T_UINT32, 2),
-        f"{arch}.attention.indexer.key_length": (_T_UINT32, 8),
-        f"{arch}.attention.indexer.top_k": (_T_UINT32, 64),
-        f"{arch}.attention.indexer.kpool": (_T_UINT32, 4),
-        f"{arch}.attention.indexer.types": (_T_ARRAY, [True] * (n_layers + n_mtp)),
-        f"{arch}.ssm.conv_kernel": (_T_UINT32, 4),
-        f"{arch}.kda.head_dim": (_T_UINT32, KDA_D),
-        f"{arch}.kda.gate_lower_bound": (_T_FLOAT32, -5.0),
-        f"{arch}.leading_dense_block_count": (_T_UINT32, 0),
-        f"{arch}.expert_count": (_T_UINT32, E),
-        f"{arch}.expert_used_count": (_T_UINT32, 2),
-        f"{arch}.expert_shared_count": (_T_UINT32, 1),
-        f"{arch}.expert_feed_forward_length": (_T_UINT32, I // 2),
-        f"{arch}.expert_weights_norm": (_T_BOOL, True),
-        f"{arch}.expert_weights_scale": (_T_FLOAT32, 2.5),
-        f"{arch}.hyper_connection.count": (_T_UINT32, 2),
-        f"{arch}.hyper_connection.sinkhorn_iterations": (_T_UINT32, 20),
-        f"{arch}.hyper_connection.epsilon": (_T_FLOAT32, 1e-6),
-        f"{arch}.swiglu_clamp_exp": (_T_ARRAY, [10.0] * (n_layers + n_mtp)),
-        f"{arch}.nextn_predict_layers": (_T_UINT32, n_mtp),
-        "tokenizer.ggml.tokens": (_T_ARRAY, ["<unk>"] * V),
-        "tokenizer.ggml.model": (_T_STRING, "gpt2"),
-    }
-
-    tensors = [
-        ("token_embd.weight", (_Q8_0, (hidden, V), q8(hidden, V))),
-        ("output.weight", (_Q8_0, (hidden, V), q8(hidden, V))),
-        ("output_norm.weight", (_F32, (hidden,), f32(hidden).tobytes())),
-    ]
-    for blk in range(n_layers + n_mtp):
-        is_dsa = kv_heads[blk] == 1
-        tensors.append((f"blk.{blk}.attn_norm.weight", (_F32, (hidden,), f32(hidden).tobytes())))
-        tensors.append((f"blk.{blk}.ffn_norm.weight", (_F32, (hidden,), f32(hidden).tobytes())))
-        for sub in ("attn", "ffn"):
-            tensors.append((f"blk.{blk}.hc_{sub}_fn.weight", (_F32, (2 * hidden, 8), f32(8, 2 * hidden).tobytes())))
-            tensors.append((f"blk.{blk}.hc_{sub}_base.weight", (_F32, (8,), f32(8).tobytes())))
-            tensors.append((f"blk.{blk}.hc_{sub}_scale.weight", (_F32, (3,), f32(3).tobytes())))
-        if is_dsa:
-            tensors.append((f"blk.{blk}.attn_q_a.weight", (_Q8_0, (hidden, q_lora), q8(hidden, q_lora))))
-            tensors.append((f"blk.{blk}.attn_q_b.weight", (_Q8_0, (q_lora, H * (D // 2)), q8(q_lora, H * (D // 2)))))
-            tensors.append((f"blk.{blk}.attn_kv_a_mqa.weight", (_BF16, (hidden, D), bf16(hidden * D))))
-            if kv_b_q8_0:
-                tensors.append((f"blk.{blk}.attn_k_b.weight", (_Q8_0, (D // 2, D, H), q8(D // 2, D * H))))
-                tensors.append((f"blk.{blk}.attn_v_b.weight", (_Q8_0, (D, D // 2, H), q8(D, (D // 2) * H))))
-            else:
-                tensors.append((f"blk.{blk}.attn_k_b.weight", (_BF16, (D // 2, D, H), bf16(D * (D // 2) * H))))
-                tensors.append((f"blk.{blk}.attn_v_b.weight", (_BF16, (D, D // 2, H), bf16(D * (D // 2) * H))))
-            tensors.append((f"blk.{blk}.attn_output.weight", (_Q8_0, (H * (D // 2), hidden), q8(H * (D // 2), hidden))))
-            tensors.append((f"blk.{blk}.attn_q_a_norm.weight", (_F32, (q_lora,), f32(q_lora).tobytes())))
-            tensors.append((f"blk.{blk}.attn_kv_a_norm.weight", (_F32, (D,), f32(D).tobytes())))
-            tensors.append((f"blk.{blk}.indexer.attn_q_b.weight", (_BF16, (q_lora, 16), bf16(q_lora * 16))))
-            tensors.append((f"blk.{blk}.indexer.attn_k.weight", (_BF16, (hidden, 8), bf16(hidden * 8))))
-            tensors.append((f"blk.{blk}.indexer.k_norm.weight", (_F32, (8,), f32(8).tobytes())))
-            tensors.append((f"blk.{blk}.indexer.k_norm.bias", (_F32, (8,), f32(8).tobytes())))
-            tensors.append((f"blk.{blk}.indexer.proj.weight", (_F32, (hidden, 2), f32(hidden, 2).tobytes())))
-            tensors.append((f"blk.{blk}.indexer_compressor_gate.weight", (_F32, (hidden, 8), f32(hidden, 8).tobytes())))
-            tensors.append((f"blk.{blk}.indexer_compressor_ape.weight", (_F32, (8, 4), f32(8, 4).tobytes())))
-        else:
-            for name in ("attn_q", "attn_k", "attn_v", "ssm_beta", "ssm_f_a", "ssm_g_a"):
-                out_rows = QKV if name in ("attn_q", "attn_k", "attn_v") else (KDA_H if name == "ssm_beta" else KDA_D)
-                gt = _Q8_0 if name in ("attn_q", "attn_k", "attn_v") else _BF16
-                payload = q8(hidden, out_rows) if gt == _Q8_0 else bf16(out_rows * hidden)
-                tensors.append((f"blk.{blk}.{name}.weight", (gt, (hidden, out_rows), payload)))
-            tensors.append((f"blk.{blk}.ssm_f_b.weight", (_BF16, (KDA_D, QKV), bf16(KDA_D * QKV))))
-            tensors.append((f"blk.{blk}.ssm_g_b.weight", (_BF16, (KDA_D, QKV), bf16(KDA_D * QKV))))
-            tensors.append((f"blk.{blk}.attn_output.weight", (_Q8_0, (QKV, hidden), q8(QKV, hidden))))
-            for q in ("q", "k", "v"):
-                tensors.append((f"blk.{blk}.ssm_conv1d_{q}.weight", (_F32, (4, 1, QKV), f32(4, 1, QKV).tobytes())))
-            tensors.append((f"blk.{blk}.ssm_a", (_F32, (KDA_H,), (-np.abs(f32(KDA_H)) - 0.1).tobytes())))
-            tensors.append((f"blk.{blk}.ssm_dt.bias", (_F32, (QKV,), f32(QKV).tobytes())))
-            tensors.append((f"blk.{blk}.ssm_norm.weight", (_F32, (KDA_D,), f32(KDA_D).tobytes())))
-        # every decoder block here is MoE (leading_dense_block_count 0)
-        tensors.append((f"blk.{blk}.ffn_gate_inp.weight", (_F32, (hidden, E), f32(hidden, E).tobytes())))
-        tensors.append((f"blk.{blk}.exp_probs_b.bias", (_F32, (E,), f32(E).tobytes())))
-        tensors.append((f"blk.{blk}.ffn_gate_exps.weight", (_IQ3_S, (hidden, I // 2, E), iq3(hidden, I // 2, E))))
-        tensors.append((f"blk.{blk}.ffn_up_exps.weight", (_IQ3_S, (hidden, I // 2, E), iq3(hidden, I // 2, E))))
-        tensors.append((f"blk.{blk}.ffn_down_exps.weight", (_IQ4_XS, (I // 2, hidden, E), iq4(I // 2, hidden, E))))
-        for p in ("gate", "up"):
-            tensors.append((f"blk.{blk}.ffn_{p}_shexp.weight", (_Q8_0, (hidden, I // 2), q8(hidden, I // 2))))
-        tensors.append((f"blk.{blk}.ffn_down_shexp.weight", (_Q8_0, (I // 2, hidden), q8(I // 2, hidden))))
-    _gguf_writer(path, kvs, tensors)
-
-
-@pytest.fixture(scope="module")
-def glm_gguf(tmp_path_factory):
-    path = tmp_path_factory.mktemp("glm5gguf") / "glm5-test.gguf"
-    _make_gguf(str(path))
-    return str(path)
-
-
-def _shim(path):
-    from freetoken.models.gguf.config import build_gguf_shim
-
-    return build_gguf_shim(path)
-
-
-def test_shim_routes_the_architecture(glm_gguf):
-    shim = _shim(glm_gguf)
-    assert shim.architectures == ["Glm5NextGGUFForCausalLM"]
-    assert shim.vocab_size == 64
-    assert shim.tie_word_embeddings is False
-
-
-def test_parse_gguf_config_matches_layer_census(glm_gguf):
-    from freetoken.models.glm5_next.args import DSA_LAYER, KDA_LAYER
-    from freetoken.models.glm5_next.gguf import parse_gguf_config
-
-    config = parse_gguf_config(_shim(glm_gguf))
-    args = config.glm5_args
-    # the trailing MTP block is dropped, and head_count_kv lays out KDA|DSA
-    assert config.num_layers == 2
-    assert args.layer_types == (KDA_LAYER, DSA_LAYER)
-    assert config.first_k_dense_replace == 0
-    assert config.num_experts == 4 and config.num_experts_per_tok == 2
-    assert args.qk_nope_head_dim == 16 and args.v_head_dim == 16 and args.qk_rope_head_dim == 0
-    assert args.index_kpool == 4 and args.index_kpool_compress and args.index_kpool_always_select_tail
-    assert args.indexer_rope_interleave  # the served fact the GGUF KV predates
-    assert config.expert_quant == "gguf"
-    assert config.swiglu_limit == 10.0
-
-
-def test_legacy_arch_spelling_routes_identically(tmp_path):
-    path = tmp_path / "glm5-legacy.gguf"
-    _make_gguf(str(path), arch="glm5next")
-    assert _shim(str(path)).architectures == ["Glm5NextGGUFForCausalLM"]
-
-
-def test_head_count_kv_fallback_uses_tensor_census(tmp_path):
-    """The pre-list writer (unsloth's first release) is laid out from the tensor names."""
-    from freetoken.models.glm5_next.args import DSA_LAYER, KDA_LAYER
-    from freetoken.models.glm5_next.gguf import _layer_types
-
-    path = tmp_path / "glm5-nolist.gguf"
-    _make_gguf(str(path))
-    shim = _shim(str(path))
-    stripped = type(shim)(
-        architectures=shim.architectures,
-        model_path=shim.model_path,
-        model_type=shim.model_type,
-        metadata={k: v for k, v in shim.metadata.items() if not k.endswith("attention.head_count_kv")},
-        vocab_size=shim.vocab_size,
-        tie_word_embeddings=shim.tie_word_embeddings,
-    )
-    assert _layer_types(stripped, 2) == (KDA_LAYER, DSA_LAYER)
-
-
-def test_reader_state_dict_matches_model(glm_gguf):
-    _tp1()
-    from dataclasses import replace
-
-    from freetoken.models.glm5_next import Glm5NextForCausalLM
-    from freetoken.models.glm5_next.gguf import iter_gguf_weights, parse_gguf_config
-    from freetoken.models.register import checkpoint_quant_config, get_model_spec
-
-    shim = _shim(glm_gguf)
-    config = parse_gguf_config(shim)
-    spec = get_model_spec(shim.architectures[0])
-    config = replace(config, quant=checkpoint_quant_config(glm_gguf, shim, spec))
-    model = Glm5NextForCausalLM(config)
-    want = model.state_dict()
-    got = dict(iter_gguf_weights(glm_gguf, torch.device("cpu"), include_moe_experts=False, include_non_moe=True))
-    assert set(want) == set(got), f"missing={sorted(set(want) - set(got))[:6]} extra={sorted(set(got) - set(want))[:6]}"
-    for k in sorted(want):
-        assert tuple(want[k].shape) == tuple(got[k].shape), k
-
-
-def test_quantized_kv_b_halves_serve_dense(tmp_path):
-    """Dynamic quants (unsloth UD) store the per-head kv_b halves Q8_0, not bf16: the
-    module stays dense -- the reader dequantizes and fuses -- instead of refusing it."""
-    _tp1()
-    from dataclasses import replace
-
-    from freetoken.models.glm5_next import Glm5NextForCausalLM
-    from freetoken.models.glm5_next.gguf import iter_gguf_weights, parse_gguf_config
-    from freetoken.models.register import checkpoint_quant_config, get_model_spec
-
-    path = str(tmp_path / "glm5-kvq8.gguf")
-    _make_gguf(path, kv_b_q8_0=True)
-    shim = _shim(path)
-    spec = get_model_spec(shim.architectures[0])
-    config = replace(parse_gguf_config(shim), quant=checkpoint_quant_config(path, shim, spec))
-    model = Glm5NextForCausalLM(config)
-    assert config.quant.scheme_for("model.layers.1.self_attn.kv_b_proj") is None
-    got = dict(iter_gguf_weights(path, torch.device("cpu"), include_moe_experts=False, include_non_moe=True))
-    want = model.state_dict()
-    assert set(want) == set(got), f"missing={sorted(set(want) - set(got))[:6]} extra={sorted(set(got) - set(want))[:6]}"
-    for k in sorted(want):
-        assert tuple(want[k].shape) == tuple(got[k].shape), k
-
-
-def test_converter_transforms_are_undone(glm_gguf):
-    from freetoken.models.gguf.reader import gguf_tensor_index
-    from freetoken.models.gguf.tensors import float_tensor
-    from freetoken.models.glm5_next.gguf import iter_gguf_weights
-
-    got = dict(iter_gguf_weights(glm_gguf, torch.device("cpu"), include_moe_experts=False, include_non_moe=True))
-    index = gguf_tensor_index(glm_gguf)
-    # A_log: the converter stores -exp(A_log); the reader inverts to the raw log
-    stored = float_tensor(index["blk.0.ssm_a"])
-    assert torch.allclose(got["model.layers.0.self_attn.A_log"], torch.log(-stored))
-    # kv_b: per-head k [lora, nope] (transposed) + v [v, lora] fuse to [heads*(nope+v), lora]
-    k = float_tensor(index["blk.1.attn_k_b.weight"]).transpose(1, 2)
-    v = float_tensor(index["blk.1.attn_v_b.weight"])
-    expect = torch.cat([k, v], dim=1).reshape(-1, 32).to(torch.bfloat16)
-    assert torch.equal(got["model.layers.1.self_attn.kv_b_proj.weight"], expect)
-    # conv1d: q|k|v conv kernels concatenate on the channel axis
-    conv = torch.cat([float_tensor(index[f"blk.0.ssm_conv1d_{q}.weight"]) for q in ("q", "k", "v")], dim=0)
-    assert torch.equal(got["model.layers.0.self_attn.conv1d.weight"], conv.to(torch.bfloat16))
-
-
-def test_to_gguf_maps_the_fused_and_packed_modules(glm_gguf):
-    from freetoken.models.glm5_next.gguf import to_gguf
-
-    assert to_gguf("model.language_model.embed_tokens", {}) == ("token_embd",)
-    assert to_gguf("lm_head", {}) == ("output",)
-    for leaf, gguf_name in (
-        ("q_proj", "attn_q"), ("k_proj", "attn_k"), ("v_proj", "attn_v"),
-        ("b_proj", "ssm_beta"), ("f_a_proj", "ssm_f_a"), ("g_a_proj", "ssm_g_a"),
-    ):
-        assert to_gguf(f"model.language_model.layers.0.self_attn.{leaf}", {}) == (f"blk.0.{gguf_name}",)
-    assert to_gguf("model.language_model.layers.3.mlp.experts.0.gate_proj", {}) == ("blk.3.ffn_gate_exps",)
-    assert to_gguf("model.language_model.layers.3.mlp.gate", {}) == ()
+"""glm5-next GGUF: config parse and weight-reader mapping against a synthetic checkpoint.
+
+Builds a tiny two-layer (KDA + DSA) glm5-next GGUF in tmp -- geometry scaled down but
+every tensor, KV key and converter quirk of the real writer present (A_log stored as
+``-exp(A_log)``, the per-head ``attn_k_b``/``attn_v_b`` split with k transposed, the
+per-block ``head_count_kv`` list, the trailing MTP block) -- then checks the config the
+shim derives and the state dict the reader yields: names complete against the model's,
+kv_b fused to the module's dense layout, A_log inverted, conv1d concatenation.
+"""
+
+from __future__ import annotations
+
+import struct
+
+import pytest
+import torch
+
+from freetoken.distributed import set_tp_info, try_get_tp_info
+
+# GGUF v3 value types (the vendored gguf-py GGUFValueType numbering)
+_T_UINT32, _T_FLOAT32, _T_BOOL, _T_STRING, _T_ARRAY, _T_UINT64 = 4, 6, 7, 8, 9, 10
+
+
+def _tp1():
+    if try_get_tp_info() is None:
+        set_tp_info(rank=0, size=1)
+
+
+def _pack_val(v):
+    if isinstance(v, str):
+        b = v.encode()
+        return struct.pack("<Q", len(b)) + b
+    if isinstance(v, bool):
+        return struct.pack("<B", int(v))
+    if isinstance(v, int):
+        return struct.pack("<I", v)
+    if isinstance(v, float):
+        return struct.pack("<f", v)
+    if isinstance(v, (list, tuple)):
+        assert v and all(isinstance(x, type(v[0])) for x in v), "homogeneous arrays only"
+        elem_type = {int: _T_UINT32, float: _T_FLOAT32, bool: _T_BOOL, str: _T_STRING}[type(v[0])]
+        body = b"".join(_pack_val(x) for x in v)
+        return struct.pack("<I", elem_type) + struct.pack("<Q", len(v)) + body
+    raise TypeError(v)
+
+
+def _gguf_writer(path, kvs, tensors):
+    """A minimal GGUF v3 writer: header + KV section + tensor infos + data, little-endian."""
+    kv_blob = b"".join(
+        struct.pack("<Q", len(k.encode())) + k.encode() + struct.pack("<I", t) + _pack_val(v)
+        for k, (t, v) in kvs.items()
+    )
+
+    infos, data, offset = b"", b"", 0
+    ALIGN = 32
+    for name, (ggml_type, ne, payload) in tensors:
+        ne = tuple(ne)
+        infos += struct.pack("<Q", len(name.encode())) + name.encode()
+        infos += struct.pack("<I", len(ne)) + b"".join(struct.pack("<Q", d) for d in ne)
+        infos += struct.pack("<I", ggml_type)
+        pad = (-offset) % ALIGN
+        infos += struct.pack("<Q", offset + pad)
+        offset += pad + len(payload)
+        data += b"\x00" * pad + payload
+
+    with open(path, "wb") as f:
+        f.write(b"GGUF" + struct.pack("<I", 3))
+        f.write(struct.pack("<Q", len(tensors)) + struct.pack("<Q", len(kvs)))
+        f.write(kv_blob)
+        f.write(infos)
+        f.write(b"\x00" * ((-f.tell()) % ALIGN))
+        f.write(data)
+
+
+# ggml type ids
+_F32, _Q8_0, _IQ3_S, _IQ4_XS, _BF16 = 0, 8, 21, 23, 30
+
+
+def _make_gguf(path, *, n_layers=2, n_mtp=1, arch="glm5-next", head_kv_list=None, kv_b_q8_0=False,
+                 head_kv_scalar=False, conv_unit_dim=False):
+    """A miniature glm5-next layout: layer 0 KDA, layer 1 DSA, one trailing MTP block."""
+    import numpy as np
+
+    # hidden/q_lora keep Q8_0 rows a multiple of 32, expert rows a multiple of 256 (IQ3_S/IQ4_XS
+    # blocks); the kv_b halves block on nope/v head rows, so D doubles when they store Q8_0
+    H, D, KDA_H, KDA_D = 8, 64 if kv_b_q8_0 else 32, 4, 8
+    QKV = KDA_H * KDA_D  # 32
+    I, E, V = 512, 4, 64
+
+    rng = np.random.default_rng(0)
+    f32 = lambda *shape: rng.standard_normal(shape).astype(np.float32)
+    bf16 = lambda n: (rng.standard_normal(n).astype(np.float32).view(np.uint32) >> 16).astype(np.uint16).tobytes()
+    q8 = lambda k, rows: np.zeros(rows * (k // 32) * 34, dtype=np.uint8).tobytes()  # placeholder packed rows
+    iq3 = lambda k, rows, e: np.zeros(rows * e * (k // 256) * 110, dtype=np.uint8).tobytes()
+    iq4 = lambda k, rows, e: np.zeros(rows * e * (k // 256) * 144, dtype=np.uint8).tobytes()
+
+    kv_heads = head_kv_list if head_kv_list is not None else ([0, 1] + [1] * n_mtp)
+    hidden = H * D  # 128
+    q_lora = 32
+    kvs = {
+        "general.architecture": (_T_STRING, arch),
+        "general.name": (_T_STRING, "glm5-next-test"),
+        f"{arch}.block_count": (_T_UINT32, n_layers + n_mtp),
+        f"{arch}.context_length": (_T_UINT32, 512),
+        f"{arch}.embedding_length": (_T_UINT32, hidden),
+        f"{arch}.feed_forward_length": (_T_UINT32, I),
+        f"{arch}.attention.head_count": (_T_UINT32, H),
+        # the generic GGUF spelling is a scalar (all blocks); the new writer's list carries the layout
+        f"{arch}.attention.head_count_kv": (_T_UINT32, 1) if head_kv_scalar else (_T_ARRAY, kv_heads),
+        f"{arch}.attention.layer_norm_rms_epsilon": (_T_FLOAT32, 1e-6),
+        f"{arch}.attention.q_lora_rank": (_T_UINT32, q_lora),
+        f"{arch}.attention.kv_lora_rank": (_T_UINT32, D),
+        f"{arch}.attention.key_length_mla": (_T_UINT32, D // 2),
+        f"{arch}.attention.value_length_mla": (_T_UINT32, D // 2),
+        f"{arch}.attention.indexer.head_count": (_T_UINT32, 2),
+        f"{arch}.attention.indexer.key_length": (_T_UINT32, 8),
+        f"{arch}.attention.indexer.top_k": (_T_UINT32, 64),
+        f"{arch}.attention.indexer.kpool": (_T_UINT32, 4),
+        f"{arch}.attention.indexer.types": (_T_ARRAY, [True] * (n_layers + n_mtp)),
+        f"{arch}.ssm.conv_kernel": (_T_UINT32, 4),
+        f"{arch}.kda.head_dim": (_T_UINT32, KDA_D),
+        f"{arch}.kda.gate_lower_bound": (_T_FLOAT32, -5.0),
+        f"{arch}.leading_dense_block_count": (_T_UINT32, 0),
+        f"{arch}.expert_count": (_T_UINT32, E),
+        f"{arch}.expert_used_count": (_T_UINT32, 2),
+        f"{arch}.expert_shared_count": (_T_UINT32, 1),
+        f"{arch}.expert_feed_forward_length": (_T_UINT32, I // 2),
+        f"{arch}.expert_weights_norm": (_T_BOOL, True),
+        f"{arch}.expert_weights_scale": (_T_FLOAT32, 2.5),
+        f"{arch}.hyper_connection.count": (_T_UINT32, 2),
+        f"{arch}.hyper_connection.sinkhorn_iterations": (_T_UINT32, 20),
+        f"{arch}.hyper_connection.epsilon": (_T_FLOAT32, 1e-6),
+        f"{arch}.swiglu_clamp_exp": (_T_ARRAY, [10.0] * (n_layers + n_mtp)),
+        f"{arch}.nextn_predict_layers": (_T_UINT32, n_mtp),
+        "tokenizer.ggml.tokens": (_T_ARRAY, ["<unk>"] * V),
+        "tokenizer.ggml.model": (_T_STRING, "gpt2"),
+    }
+
+    tensors = [
+        ("token_embd.weight", (_Q8_0, (hidden, V), q8(hidden, V))),
+        ("output.weight", (_Q8_0, (hidden, V), q8(hidden, V))),
+        ("output_norm.weight", (_F32, (hidden,), f32(hidden).tobytes())),
+    ]
+    for blk in range(n_layers + n_mtp):
+        is_dsa = kv_heads[blk] == 1
+        tensors.append((f"blk.{blk}.attn_norm.weight", (_F32, (hidden,), f32(hidden).tobytes())))
+        tensors.append((f"blk.{blk}.ffn_norm.weight", (_F32, (hidden,), f32(hidden).tobytes())))
+        for sub in ("attn", "ffn"):
+            tensors.append((f"blk.{blk}.hc_{sub}_fn.weight", (_F32, (2 * hidden, 8), f32(8, 2 * hidden).tobytes())))
+            tensors.append((f"blk.{blk}.hc_{sub}_base.weight", (_F32, (8,), f32(8).tobytes())))
+            tensors.append((f"blk.{blk}.hc_{sub}_scale.weight", (_F32, (3,), f32(3).tobytes())))
+        if is_dsa:
+            tensors.append((f"blk.{blk}.attn_q_a.weight", (_Q8_0, (hidden, q_lora), q8(hidden, q_lora))))
+            tensors.append((f"blk.{blk}.attn_q_b.weight", (_Q8_0, (q_lora, H * (D // 2)), q8(q_lora, H * (D // 2)))))
+            tensors.append((f"blk.{blk}.attn_kv_a_mqa.weight", (_BF16, (hidden, D), bf16(hidden * D))))
+            if kv_b_q8_0:
+                tensors.append((f"blk.{blk}.attn_k_b.weight", (_Q8_0, (D // 2, D, H), q8(D // 2, D * H))))
+                tensors.append((f"blk.{blk}.attn_v_b.weight", (_Q8_0, (D, D // 2, H), q8(D, (D // 2) * H))))
+            else:
+                tensors.append((f"blk.{blk}.attn_k_b.weight", (_BF16, (D // 2, D, H), bf16(D * (D // 2) * H))))
+                tensors.append((f"blk.{blk}.attn_v_b.weight", (_BF16, (D, D // 2, H), bf16(D * (D // 2) * H))))
+            tensors.append((f"blk.{blk}.attn_output.weight", (_Q8_0, (H * (D // 2), hidden), q8(H * (D // 2), hidden))))
+            tensors.append((f"blk.{blk}.attn_q_a_norm.weight", (_F32, (q_lora,), f32(q_lora).tobytes())))
+            tensors.append((f"blk.{blk}.attn_kv_a_norm.weight", (_F32, (D,), f32(D).tobytes())))
+            tensors.append((f"blk.{blk}.indexer.attn_q_b.weight", (_BF16, (q_lora, 16), bf16(q_lora * 16))))
+            tensors.append((f"blk.{blk}.indexer.attn_k.weight", (_BF16, (hidden, 8), bf16(hidden * 8))))
+            tensors.append((f"blk.{blk}.indexer.k_norm.weight", (_F32, (8,), f32(8).tobytes())))
+            tensors.append((f"blk.{blk}.indexer.k_norm.bias", (_F32, (8,), f32(8).tobytes())))
+            tensors.append((f"blk.{blk}.indexer.proj.weight", (_F32, (hidden, 2), f32(hidden, 2).tobytes())))
+            tensors.append((f"blk.{blk}.indexer_compressor_gate.weight", (_F32, (hidden, 8), f32(hidden, 8).tobytes())))
+            tensors.append((f"blk.{blk}.indexer_compressor_ape.weight", (_F32, (8, 4), f32(8, 4).tobytes())))
+        else:
+            for name in ("attn_q", "attn_k", "attn_v", "ssm_beta", "ssm_f_a", "ssm_g_a"):
+                out_rows = QKV if name in ("attn_q", "attn_k", "attn_v") else (KDA_H if name == "ssm_beta" else KDA_D)
+                gt = _Q8_0 if name in ("attn_q", "attn_k", "attn_v") else _BF16
+                payload = q8(hidden, out_rows) if gt == _Q8_0 else bf16(out_rows * hidden)
+                tensors.append((f"blk.{blk}.{name}.weight", (gt, (hidden, out_rows), payload)))
+            tensors.append((f"blk.{blk}.ssm_f_b.weight", (_BF16, (KDA_D, QKV), bf16(KDA_D * QKV))))
+            tensors.append((f"blk.{blk}.ssm_g_b.weight", (_BF16, (KDA_D, QKV), bf16(KDA_D * QKV))))
+            tensors.append((f"blk.{blk}.attn_output.weight", (_Q8_0, (QKV, hidden), q8(QKV, hidden))))
+            for q in ("q", "k", "v"):
+                conv_ne = (4, 1, QKV, 1) if conv_unit_dim else (4, 1, QKV)
+                tensors.append((f"blk.{blk}.ssm_conv1d_{q}.weight", (_F32, conv_ne, f32(4, 1, QKV).tobytes())))
+            tensors.append((f"blk.{blk}.ssm_a", (_F32, (KDA_H,), (-np.abs(f32(KDA_H)) - 0.1).tobytes())))
+            tensors.append((f"blk.{blk}.ssm_dt.bias", (_F32, (QKV,), f32(QKV).tobytes())))
+            tensors.append((f"blk.{blk}.ssm_norm.weight", (_F32, (KDA_D,), f32(KDA_D).tobytes())))
+        # every decoder block here is MoE (leading_dense_block_count 0)
+        tensors.append((f"blk.{blk}.ffn_gate_inp.weight", (_F32, (hidden, E), f32(hidden, E).tobytes())))
+        tensors.append((f"blk.{blk}.exp_probs_b.bias", (_F32, (E,), f32(E).tobytes())))
+        tensors.append((f"blk.{blk}.ffn_gate_exps.weight", (_IQ3_S, (hidden, I // 2, E), iq3(hidden, I // 2, E))))
+        tensors.append((f"blk.{blk}.ffn_up_exps.weight", (_IQ3_S, (hidden, I // 2, E), iq3(hidden, I // 2, E))))
+        tensors.append((f"blk.{blk}.ffn_down_exps.weight", (_IQ4_XS, (I // 2, hidden, E), iq4(I // 2, hidden, E))))
+        for p in ("gate", "up"):
+            tensors.append((f"blk.{blk}.ffn_{p}_shexp.weight", (_Q8_0, (hidden, I // 2), q8(hidden, I // 2))))
+        tensors.append((f"blk.{blk}.ffn_down_shexp.weight", (_Q8_0, (I // 2, hidden), q8(I // 2, hidden))))
+    _gguf_writer(path, kvs, tensors)
+
+
+@pytest.fixture(scope="module")
+def glm_gguf(tmp_path_factory):
+    path = tmp_path_factory.mktemp("glm5gguf") / "glm5-test.gguf"
+    _make_gguf(str(path))
+    return str(path)
+
+
+def _shim(path):
+    from freetoken.models.gguf.config import build_gguf_shim
+
+    return build_gguf_shim(path)
+
+
+def test_shim_routes_the_architecture(glm_gguf):
+    shim = _shim(glm_gguf)
+    assert shim.architectures == ["Glm5NextGGUFForCausalLM"]
+    assert shim.vocab_size == 64
+    assert shim.tie_word_embeddings is False
+
+
+def test_parse_gguf_config_matches_layer_census(glm_gguf):
+    from freetoken.models.glm5_next.args import DSA_LAYER, KDA_LAYER
+    from freetoken.models.glm5_next.gguf import parse_gguf_config
+
+    config = parse_gguf_config(_shim(glm_gguf))
+    args = config.glm5_args
+    # the trailing MTP block is dropped, and head_count_kv lays out KDA|DSA
+    assert config.num_layers == 2
+    assert args.layer_types == (KDA_LAYER, DSA_LAYER)
+    assert config.first_k_dense_replace == 0
+    assert config.num_experts == 4 and config.num_experts_per_tok == 2
+    assert args.qk_nope_head_dim == 16 and args.v_head_dim == 16 and args.qk_rope_head_dim == 0
+    assert args.index_kpool == 4 and args.index_kpool_compress and args.index_kpool_always_select_tail
+    assert args.indexer_rope_interleave  # the served fact the GGUF KV predates
+    assert config.expert_quant == "gguf"
+    assert config.swiglu_limit == 10.0
+
+
+def test_legacy_arch_spelling_routes_identically(tmp_path):
+    path = tmp_path / "glm5-legacy.gguf"
+    _make_gguf(str(path), arch="glm5next")
+    assert _shim(str(path)).architectures == ["Glm5NextGGUFForCausalLM"]
+
+
+def test_head_count_kv_fallback_uses_tensor_census(tmp_path):
+    """The pre-list writer (unsloth's first release) is laid out from the tensor names."""
+    from freetoken.models.glm5_next.args import DSA_LAYER, KDA_LAYER
+    from freetoken.models.glm5_next.gguf import _layer_types
+
+    path = tmp_path / "glm5-nolist.gguf"
+    _make_gguf(str(path))
+    shim = _shim(str(path))
+    stripped = type(shim)(
+        architectures=shim.architectures,
+        model_path=shim.model_path,
+        model_type=shim.model_type,
+        metadata={k: v for k, v in shim.metadata.items() if not k.endswith("attention.head_count_kv")},
+        vocab_size=shim.vocab_size,
+        tie_word_embeddings=shim.tie_word_embeddings,
+    )
+    assert _layer_types(stripped, 2) == (KDA_LAYER, DSA_LAYER)
+
+
+def test_reader_state_dict_matches_model(glm_gguf):
+    _tp1()
+    from dataclasses import replace
+
+    from freetoken.models.glm5_next import Glm5NextForCausalLM
+    from freetoken.models.glm5_next.gguf import iter_gguf_weights, parse_gguf_config
+    from freetoken.models.register import checkpoint_quant_config, get_model_spec
+
+    shim = _shim(glm_gguf)
+    config = parse_gguf_config(shim)
+    spec = get_model_spec(shim.architectures[0])
+    config = replace(config, quant=checkpoint_quant_config(glm_gguf, shim, spec))
+    model = Glm5NextForCausalLM(config)
+    want = model.state_dict()
+    got = dict(iter_gguf_weights(glm_gguf, torch.device("cpu"), include_moe_experts=False, include_non_moe=True))
+    assert set(want) == set(got), f"missing={sorted(set(want) - set(got))[:6]} extra={sorted(set(got) - set(want))[:6]}"
+    for k in sorted(want):
+        assert tuple(want[k].shape) == tuple(got[k].shape), k
+
+
+def test_quantized_kv_b_halves_serve_dense(tmp_path):
+    """Dynamic quants (unsloth UD) store the per-head kv_b halves Q8_0, not bf16: the
+    module stays dense -- the reader dequantizes and fuses -- instead of refusing it."""
+    _tp1()
+    from dataclasses import replace
+
+    from freetoken.models.glm5_next import Glm5NextForCausalLM
+    from freetoken.models.glm5_next.gguf import iter_gguf_weights, parse_gguf_config
+    from freetoken.models.register import checkpoint_quant_config, get_model_spec
+
+    path = str(tmp_path / "glm5-kvq8.gguf")
+    _make_gguf(path, kv_b_q8_0=True)
+    shim = _shim(path)
+    spec = get_model_spec(shim.architectures[0])
+    config = replace(parse_gguf_config(shim), quant=checkpoint_quant_config(path, shim, spec))
+    model = Glm5NextForCausalLM(config)
+    assert config.quant.scheme_for("model.layers.1.self_attn.kv_b_proj") is None
+    got = dict(iter_gguf_weights(path, torch.device("cpu"), include_moe_experts=False, include_non_moe=True))
+    want = model.state_dict()
+    assert set(want) == set(got), f"missing={sorted(set(want) - set(got))[:6]} extra={sorted(set(got) - set(want))[:6]}"
+    for k in sorted(want):
+        assert tuple(want[k].shape) == tuple(got[k].shape), k
+
+
+def test_converter_transforms_are_undone(glm_gguf):
+    from freetoken.models.gguf.reader import gguf_tensor_index
+    from freetoken.models.gguf.tensors import float_tensor
+    from freetoken.models.glm5_next.gguf import iter_gguf_weights
+
+    got = dict(iter_gguf_weights(glm_gguf, torch.device("cpu"), include_moe_experts=False, include_non_moe=True))
+    index = gguf_tensor_index(glm_gguf)
+    # A_log: the converter stores -exp(A_log); the reader inverts to the raw log
+    stored = float_tensor(index["blk.0.ssm_a"])
+    assert torch.allclose(got["model.layers.0.self_attn.A_log"], torch.log(-stored))
+    # kv_b: per-head k [lora, nope] (transposed) + v [v, lora] fuse to [heads*(nope+v), lora]
+    k = float_tensor(index["blk.1.attn_k_b.weight"]).transpose(1, 2)
+    v = float_tensor(index["blk.1.attn_v_b.weight"])
+    expect = torch.cat([k, v], dim=1).reshape(-1, 32).to(torch.bfloat16)
+    assert torch.equal(got["model.layers.1.self_attn.kv_b_proj.weight"], expect)
+    # conv1d: q|k|v conv kernels concatenate on the channel axis
+    conv = torch.cat([float_tensor(index[f"blk.0.ssm_conv1d_{q}.weight"]) for q in ("q", "k", "v")], dim=0)
+    assert torch.equal(got["model.layers.0.self_attn.conv1d.weight"], conv.to(torch.bfloat16))
+
+
+def test_to_gguf_maps_the_fused_and_packed_modules(glm_gguf):
+    from freetoken.models.glm5_next.gguf import to_gguf
+
+    assert to_gguf("model.language_model.embed_tokens", {}) == ("token_embd",)
+    assert to_gguf("lm_head", {}) == ("output",)
+    for leaf, gguf_name in (
+        ("q_proj", "attn_q"), ("k_proj", "attn_k"), ("v_proj", "attn_v"),
+        ("b_proj", "ssm_beta"), ("f_a_proj", "ssm_f_a"), ("g_a_proj", "ssm_g_a"),
+    ):
+        assert to_gguf(f"model.language_model.layers.0.self_attn.{leaf}", {}) == (f"blk.0.{gguf_name}",)
+    assert to_gguf("model.language_model.layers.3.mlp.experts.0.gate_proj", {}) == ("blk.3.ffn_gate_exps",)
+    assert to_gguf("model.language_model.layers.3.mlp.gate", {}) == ()
 
 
 def test_fused_covers_the_mmq_tail():
@@ -346,3 +349,37 @@ def test_fused_covers_the_mmq_tail():
     part = torch.zeros(96, row_bytes(8, k), dtype=torch.uint8)  # Q8_0
     out = dict(fused("l0.self_attn.f_b_proj", [SimpleNamespace(ggml_type=8)], [part], k))
     assert out["l0.self_attn.f_b_proj.weight"].numel() >= 96 * row_bytes(8, k) + mmq_tail_bytes(8, k)
+
+
+def test_scalar_head_count_kv_falls_back_to_census(tmp_path):
+    """The generic GGUF spelling of head_count_kv is a scalar (all blocks), which is wrong for the
+    hybrid -- llama.cpp broadcasts it and then fails tensor creation; the census recovers the layout."""
+    from freetoken.models.glm5_next.args import DSA_LAYER, KDA_LAYER
+    from freetoken.models.glm5_next.gguf import _layer_types, parse_gguf_config
+
+    path = str(tmp_path / "glm5-scalar.gguf")
+    _make_gguf(path, head_kv_scalar=True)
+    shim = _shim(path)
+    assert _layer_types(shim, 2) == (KDA_LAYER, DSA_LAYER)
+    assert parse_gguf_config(shim).num_layers == 2
+
+
+def test_conv_kernels_with_a_trailing_unit_dim(tmp_path):
+    """Some writers ship the conv kernels 4-D; llama.cpp's glm5-next loader tries that shape first."""
+    _tp1()
+    from dataclasses import replace
+
+    from freetoken.models.glm5_next import Glm5NextForCausalLM
+    from freetoken.models.glm5_next.gguf import iter_gguf_weights, parse_gguf_config
+    from freetoken.models.register import checkpoint_quant_config, get_model_spec
+
+    path = str(tmp_path / "glm5-conv4d.gguf")
+    _make_gguf(path, conv_unit_dim=True)
+    shim = _shim(path)
+    spec = get_model_spec(shim.architectures[0])
+    config = replace(parse_gguf_config(shim), quant=checkpoint_quant_config(path, shim, spec))
+    model = Glm5NextForCausalLM(config)
+    got = dict(iter_gguf_weights(path, torch.device("cpu"), include_moe_experts=False, include_non_moe=True))
+    want = model.state_dict()
+    assert set(want) == set(got)
+    assert tuple(want["model.layers.0.self_attn.conv1d.weight"].shape) == tuple(got["model.layers.0.self_attn.conv1d.weight"].shape)

From b9e484979a0a4e5aa9078ad8fb7df6d3b0d706e5 Mon Sep 17 00:00:00 2001
From: Mukkesh Ganesh <mukmckenzie@gmail.com>
Date: Mon, 19 Oct 2026 22:30:54 -0700
Subject: [PATCH 7/7] fix(gguf): glm5-next review cleanups

- refuse instead of guessing metadata the model cannot express: the
  scalar attention.head_count_kv spelling (llama.cpp broadcasts it and
  then fails tensor creation; every public file carries the list),
  missing *_length_mla keys through need(), non-uniform
  swiglu_clamp_exp / swiglu_clamp_shexp, indexer.types with non-full
  layers, expert_gating_func other than sigmoid, and rope dims as a
  NotImplementedError instead of an assert.
- call check_scales directly; aot_models comment on its own line.
- drop the GGUF test files; coverage will be handled across families.
---
 python/freetoken/kernel/aot_models.py     |   3 +-
 python/freetoken/models/glm5_next/gguf.py |  80 ++---
 tests/models/test_gguf_tokenizer.py       |  56 ----
 tests/models/test_glm5_next_gguf.py       | 385 ----------------------
 4 files changed, 31 insertions(+), 493 deletions(-)
 delete mode 100644 tests/models/test_gguf_tokenizer.py
 delete mode 100644 tests/models/test_glm5_next_gguf.py

diff --git a/python/freetoken/kernel/aot_models.py b/python/freetoken/kernel/aot_models.py
index dff23e117c..a68c868ea7 100644
--- a/python/freetoken/kernel/aot_models.py
+++ b/python/freetoken/kernel/aot_models.py
@@ -281,7 +281,8 @@ def expert_bank_row_bytes(fmt: str, hidden_size: int, moe_intermediate_size: int
         # KDA conv/recurrent state lives in the LinearStatePool, not paged KV.
         name="RedHatAI/GLM-5.3-Flash-NVFP4",
         architecture="Glm5NextForCausalLM",
-        arch_aliases=("Glm5NextForConditionalGeneration", "Glm5NextGGUFForCausalLM"),  # GGUF expert rows differ per layer and reach the fused copy as runtime sizes
+        # GGUF expert rows differ per layer and reach the fused copy as runtime sizes
+        arch_aliases=("Glm5NextForConditionalGeneration", "Glm5NextGGUFForCausalLM"),
         hidden_size=4096,
         kv_groups=(),
         top_k=8,
diff --git a/python/freetoken/models/glm5_next/gguf.py b/python/freetoken/models/glm5_next/gguf.py
index 7fb8f825f2..73eb0a82ce 100644
--- a/python/freetoken/models/glm5_next/gguf.py
+++ b/python/freetoken/models/glm5_next/gguf.py
@@ -4,8 +4,7 @@
 11 NoPE-MLA/DSA layers with a kpool-compressed indexer on a 3+1 hybrid block layout,
 mHC x4 residual streams, 288-expert sigmoid/noaux_tc MoE with a shared expert and
 clamped SwiGLU), so ``parse_gguf_config`` derives a text-config-shaped namespace from
-the GGUF KV metadata (plus a tensor-name census for the facts the KV predates) and
-reuses ``glm5_next.config.parse_config`` wholesale.
+the GGUF KV metadata and reuses ``glm5_next.config.parse_config`` wholesale.
 
 The llama.cpp converter (unsloth's glm5-next writer; tensor names identical across
 the ``glm5-next`` and the older ``glm5next`` arch spellings) stores KDA's ``A_log``
@@ -104,58 +103,28 @@ def to_gguf(name: str, tensors: dict[str, int]) -> tuple[str, ...]:
 
 
 def _layer_types(shim: "GgufConfigShim", num_layers: int) -> tuple[str, ...]:
-    """Per-decoder-layer kinds: DSA where the MLA projections sit, KDA elsewhere.
+    """Per-decoder-layer kinds: DSA where the MLA projections sit, KDA elsewhere, from the
+    per-block ``attention.head_count_kv`` list (0 on the KDA blocks, 1 on the MLA ones).
 
-    The new writer carries ``attention.head_count_kv`` as a per-block list (0 on the
-    KDA blocks, 1 on the MLA ones); the older spelling predates it, so fall back to a
-    tensor-name census (``attn_q_a`` is DSA-only). A metadata-only GGUF (an FTW's
-    ``source_metadata.gguf``) has neither the list nor the tensor table, and only the
-    new writer's files can convert."""
+    Every public glm5-next GGUF carries the list (the generic scalar spelling cannot express
+    the hybrid; llama.cpp broadcasts it and then fails tensor creation), so anything else is
+    refused rather than guessed at."""
     from .args import DSA_LAYER, KDA_LAYER
 
-    md = shim.metadata
-    per_block = md.get(f"{shim.model_type}.attention.head_count_kv")
-    # the new writer carries the per-block KDA/MLA layout as a list; the generic GGUF spelling is a
-    # scalar (all blocks), which is wrong for the hybrid -- llama.cpp broadcasts it and then fails
-    # tensor creation -- so only a list is trusted and everything else falls to the census
-    if isinstance(per_block, list) and len(per_block) >= num_layers:
-        return tuple(DSA_LAYER if int(kv) else KDA_LAYER for kv in per_block[:num_layers])
-    names = gguf_tensor_names(shim.model_path)
-    if not names:
+    per_block = shim.metadata.get(f"{shim.model_type}.attention.head_count_kv")
+    if not isinstance(per_block, list) or len(per_block) < num_layers:
         raise ValueError(
-            f"{shim.model_path}: metadata-only GGUF without attention.head_count_kv; "
-            "the layer layout cannot be recovered (reconvert from a current writer)"
+            f"{shim.model_path}: glm5-next GGUF lacks the per-block attention.head_count_kv list "
+            "the KDA/MLA hybrid layout needs (reconvert with a current llama.cpp)"
         )
-    return tuple(
-        DSA_LAYER if f"blk.{i}.attn_q_a.weight" in names else KDA_LAYER for i in range(num_layers)
-    )
-
-
-def _head_dims(shim: "GgufConfigShim") -> tuple[int, int]:
-    """(qk_nope, v) head widths: the new writer's ``*_length_mla`` KVs, else the q_b/v_b rows."""
-    md = shim.metadata
-    prefix = shim.model_type
-    nope, v = md.get(f"{prefix}.attention.key_length_mla"), md.get(f"{prefix}.attention.value_length_mla")
-    if nope is None or v is None:
-        index = gguf_tensor_index(shim.model_path)
-        q_b = next((i for i in index.values() if i.name.endswith("attn_q_b.weight")), None)
-        v_b = next((i for i in index.values() if i.name.endswith("attn_v_b.weight")), None)
-        if q_b is None or v_b is None:
-            raise ValueError(f"{shim.model_path}: GGUF lacks attn_q_b/attn_v_b to size the MLA heads")
-        heads = int(md[f"{prefix}.attention.head_count"])
-        nope, v = q_b.ne[1] // heads, v_b.ne[1]
-    return int(nope), int(v)
-
-
-def _check_supported(shim: "GgufConfigShim") -> None:
-    check_scales(shim.model_path)
+    return tuple(DSA_LAYER if int(kv) else KDA_LAYER for kv in per_block[:num_layers])
 
 
 def parse_gguf_config(shim: "GgufConfigShim") -> ModelConfig:
     md = shim.metadata
     prefix = shim.model_type
 
-    _check_supported(shim)
+    check_scales(shim.model_path)
 
     def kv(key: str, default=None):
         return md.get(f"{prefix}.{key}", default)
@@ -173,9 +142,10 @@ def need(key: str):
     first_dense = int(need("leading_dense_block_count"))
 
     heads = int(need("attention.head_count"))
-    qk_nope, v_head = _head_dims(shim)
+    qk_nope, v_head = int(need("attention.key_length_mla")), int(need("attention.value_length_mla"))
     # NoPE: the main attention carries no rotary dims (rope survives only in the indexer)
-    assert int(kv("rope.dimension_count", 0) or 0) == 0, "glm5-next GGUF: unexpected rotary dims on the main attention"
+    if int(kv("rope.dimension_count", 0) or 0) != 0:
+        raise NotImplementedError("glm5-next GGUF: rotary dims on the main attention are not served")
 
     # KDA head count: one q/k/v head set of kda.head_dim each; the conv channels or the
     # beta rows count them, falling back to the shared head_count (the two coincide on
@@ -191,13 +161,21 @@ def need(key: str):
     names = gguf_tensor_names(shim.model_path)
     kpool_compress = any(n.endswith("indexer_compressor_gate.weight") for n in names) if names else kpool > 1
     indexer_types_kv = kv("attention.indexer.types")
-    if indexer_types_kv is not None and len(indexer_types_kv) >= num_layers:
-        indexer_types = tuple("full" if b else "disabled" for b in indexer_types_kv[:num_layers])
-    else:
-        # every release carries all-"full" in the HF config (the engine builds only the DSA-owned indexers)
-        indexer_types = ("full",) * num_layers
+    if indexer_types_kv is not None and not all(indexer_types_kv):
+        # llama.cpp reads False as "no full indexer on this layer", which the model cannot express
+        raise NotImplementedError(f"{shim.model_path}: glm5-next GGUF with layers that lack a full indexer is not served")
+    indexer_types = ("full",) * num_layers
 
+    # the clamp is per-layer in the GGUF (and the shared expert carries its own array); the model
+    # takes one value, so anything non-uniform is refused instead of silently taking the first
     clamp = need("swiglu_clamp_exp")
+    clamp_vals = list(clamp) if isinstance(clamp, list) else [clamp]
+    clamp_shexp = kv("swiglu_clamp_shexp")
+    shexp_vals = list(clamp_shexp) if isinstance(clamp_shexp, list) else [clamp_shexp] if clamp_shexp is not None else []
+    if len(set(map(float, clamp_vals + shexp_vals))) != 1:
+        raise NotImplementedError(f"{shim.model_path}: non-uniform swiglu_clamp_exp / swiglu_clamp_shexp is not served")
+    if int(kv("expert_gating_func", 2) or 2) != 2:
+        raise NotImplementedError(f"{shim.model_path}: expert_gating_func other than sigmoid (2) is not served")
     text = SimpleNamespace(
         **_FAMILY_DEFAULTS,
         num_hidden_layers=num_layers,
@@ -243,7 +221,7 @@ def need(key: str):
         n_group=int(kv("expert_group_count", 1) or 1),
         topk_group=int(kv("expert_group_used_count", 1) or 1),
         tie_word_embeddings=bool(shim.tie_word_embeddings),
-        swiglu_limit=float(clamp[0] if isinstance(clamp, list) else clamp),
+        swiglu_limit=float(clamp_vals[0]),
     )
     hf_like = SimpleNamespace(
         text_config=text,
diff --git a/tests/models/test_gguf_tokenizer.py b/tests/models/test_gguf_tokenizer.py
deleted file mode 100644
index d7b592efb6..0000000000
--- a/tests/models/test_gguf_tokenizer.py
+++ /dev/null
@@ -1,56 +0,0 @@
-"""The GGUF tokenizer: pre-tokenizer spellings llama.cpp writes and how FreeToken maps them."""
-
-from __future__ import annotations
-
-import struct
-
-# GGUF v3 value types (the vendored gguf-py GGUFValueType numbering)
-_T_UINT32, _T_FLOAT32, _T_STRING, _T_ARRAY = 4, 6, 8, 9
-
-# a byte-level BPE with no merges: "Hello" is one vocabulary token, and without
-# ignore_merges the encoder falls back to its four characters
-_TOKENS = ["d", "o", "n", "'", "t", "don't", "Hello", "H", "e", "l", "!"]
-
-
-def _pack_val(v):
-    if isinstance(v, str):
-        b = v.encode()
-        return struct.pack("<Q", len(b)) + b
-    if isinstance(v, int):
-        return struct.pack("<I", v)
-    if isinstance(v, float):
-        return struct.pack("<f", v)
-    if isinstance(v, list):
-        elem = {int: _T_UINT32, float: _T_FLOAT32, str: _T_STRING}[type(v[0])]
-        return struct.pack("<I", elem) + struct.pack("<Q", len(v)) + b"".join(_pack_val(x) for x in v)
-    raise TypeError(v)
-
-
-def _tokenizer_gguf(path, pre: str) -> str:
-    """A header-only GGUF carrying a gpt2 tokenizer with the given ``tokenizer.ggml.pre``."""
-    kvs = {
-        "general.architecture": (_T_STRING, "glm5-next"),
-        "tokenizer.ggml.model": (_T_STRING, "gpt2"),
-        "tokenizer.ggml.pre": (_T_STRING, pre),
-        "tokenizer.ggml.tokens": (_T_ARRAY, list(_TOKENS)),
-        "tokenizer.ggml.token_type": (_T_ARRAY, [1] * len(_TOKENS)),
-        "tokenizer.ggml.scores": (_T_ARRAY, [0.0] * len(_TOKENS)),
-    }
-    with open(path, "wb") as f:
-        f.write(b"GGUF" + struct.pack("<I", 3) + struct.pack("<Q", 0) + struct.pack("<Q", len(kvs)))
-        for k, (t, v) in kvs.items():
-            f.write(struct.pack("<Q", len(k.encode())) + k.encode() + struct.pack("<I", t) + _pack_val(v))
-    return str(path)
-
-
-def test_glm5_pre_routes_like_glm4(tmp_path):
-    """llama.cpp maps its "glm4" and "glm5" spellings to the same pre-tokenizer (CHATGLM4
-    with ignore_merges); a glm5 file must encode exactly like the glm4 one."""
-    from freetoken.models.gguf.tokenizer import load_gguf_tokenizer
-
-    glm4 = load_gguf_tokenizer(_tokenizer_gguf(tmp_path / "tok4.gguf", "glm4"))
-    glm5 = load_gguf_tokenizer(_tokenizer_gguf(tmp_path / "tok5.gguf", "glm5"))
-    for text in ("Hello!", "don't", "don't Hello!"):
-        assert glm4.encode(text) == glm5.encode(text), text
-    # the treatment bites: the whole-word token wins over the character fallback
-    assert glm5.encode("Hello!") == [_TOKENS.index("Hello"), _TOKENS.index("!")]
diff --git a/tests/models/test_glm5_next_gguf.py b/tests/models/test_glm5_next_gguf.py
deleted file mode 100644
index fb6b24c60a..0000000000
--- a/tests/models/test_glm5_next_gguf.py
+++ /dev/null
@@ -1,385 +0,0 @@
-"""glm5-next GGUF: config parse and weight-reader mapping against a synthetic checkpoint.
-
-Builds a tiny two-layer (KDA + DSA) glm5-next GGUF in tmp -- geometry scaled down but
-every tensor, KV key and converter quirk of the real writer present (A_log stored as
-``-exp(A_log)``, the per-head ``attn_k_b``/``attn_v_b`` split with k transposed, the
-per-block ``head_count_kv`` list, the trailing MTP block) -- then checks the config the
-shim derives and the state dict the reader yields: names complete against the model's,
-kv_b fused to the module's dense layout, A_log inverted, conv1d concatenation.
-"""
-
-from __future__ import annotations
-
-import struct
-
-import pytest
-import torch
-
-from freetoken.distributed import set_tp_info, try_get_tp_info
-
-# GGUF v3 value types (the vendored gguf-py GGUFValueType numbering)
-_T_UINT32, _T_FLOAT32, _T_BOOL, _T_STRING, _T_ARRAY, _T_UINT64 = 4, 6, 7, 8, 9, 10
-
-
-def _tp1():
-    if try_get_tp_info() is None:
-        set_tp_info(rank=0, size=1)
-
-
-def _pack_val(v):
-    if isinstance(v, str):
-        b = v.encode()
-        return struct.pack("<Q", len(b)) + b
-    if isinstance(v, bool):
-        return struct.pack("<B", int(v))
-    if isinstance(v, int):
-        return struct.pack("<I", v)
-    if isinstance(v, float):
-        return struct.pack("<f", v)
-    if isinstance(v, (list, tuple)):
-        assert v and all(isinstance(x, type(v[0])) for x in v), "homogeneous arrays only"
-        elem_type = {int: _T_UINT32, float: _T_FLOAT32, bool: _T_BOOL, str: _T_STRING}[type(v[0])]
-        body = b"".join(_pack_val(x) for x in v)
-        return struct.pack("<I", elem_type) + struct.pack("<Q", len(v)) + body
-    raise TypeError(v)
-
-
-def _gguf_writer(path, kvs, tensors):
-    """A minimal GGUF v3 writer: header + KV section + tensor infos + data, little-endian."""
-    kv_blob = b"".join(
-        struct.pack("<Q", len(k.encode())) + k.encode() + struct.pack("<I", t) + _pack_val(v)
-        for k, (t, v) in kvs.items()
-    )
-
-    infos, data, offset = b"", b"", 0
-    ALIGN = 32
-    for name, (ggml_type, ne, payload) in tensors:
-        ne = tuple(ne)
-        infos += struct.pack("<Q", len(name.encode())) + name.encode()
-        infos += struct.pack("<I", len(ne)) + b"".join(struct.pack("<Q", d) for d in ne)
-        infos += struct.pack("<I", ggml_type)
-        pad = (-offset) % ALIGN
-        infos += struct.pack("<Q", offset + pad)
-        offset += pad + len(payload)
-        data += b"\x00" * pad + payload
-
-    with open(path, "wb") as f:
-        f.write(b"GGUF" + struct.pack("<I", 3))
-        f.write(struct.pack("<Q", len(tensors)) + struct.pack("<Q", len(kvs)))
-        f.write(kv_blob)
-        f.write(infos)
-        f.write(b"\x00" * ((-f.tell()) % ALIGN))
-        f.write(data)
-
-
-# ggml type ids
-_F32, _Q8_0, _IQ3_S, _IQ4_XS, _BF16 = 0, 8, 21, 23, 30
-
-
-def _make_gguf(path, *, n_layers=2, n_mtp=1, arch="glm5-next", head_kv_list=None, kv_b_q8_0=False,
-                 head_kv_scalar=False, conv_unit_dim=False):
-    """A miniature glm5-next layout: layer 0 KDA, layer 1 DSA, one trailing MTP block."""
-    import numpy as np
-
-    # hidden/q_lora keep Q8_0 rows a multiple of 32, expert rows a multiple of 256 (IQ3_S/IQ4_XS
-    # blocks); the kv_b halves block on nope/v head rows, so D doubles when they store Q8_0
-    H, D, KDA_H, KDA_D = 8, 64 if kv_b_q8_0 else 32, 4, 8
-    QKV = KDA_H * KDA_D  # 32
-    I, E, V = 512, 4, 64
-
-    rng = np.random.default_rng(0)
-    f32 = lambda *shape: rng.standard_normal(shape).astype(np.float32)
-    bf16 = lambda n: (rng.standard_normal(n).astype(np.float32).view(np.uint32) >> 16).astype(np.uint16).tobytes()
-    q8 = lambda k, rows: np.zeros(rows * (k // 32) * 34, dtype=np.uint8).tobytes()  # placeholder packed rows
-    iq3 = lambda k, rows, e: np.zeros(rows * e * (k // 256) * 110, dtype=np.uint8).tobytes()
-    iq4 = lambda k, rows, e: np.zeros(rows * e * (k // 256) * 144, dtype=np.uint8).tobytes()
-
-    kv_heads = head_kv_list if head_kv_list is not None else ([0, 1] + [1] * n_mtp)
-    hidden = H * D  # 128
-    q_lora = 32
-    kvs = {
-        "general.architecture": (_T_STRING, arch),
-        "general.name": (_T_STRING, "glm5-next-test"),
-        f"{arch}.block_count": (_T_UINT32, n_layers + n_mtp),
-        f"{arch}.context_length": (_T_UINT32, 512),
-        f"{arch}.embedding_length": (_T_UINT32, hidden),
-        f"{arch}.feed_forward_length": (_T_UINT32, I),
-        f"{arch}.attention.head_count": (_T_UINT32, H),
-        # the generic GGUF spelling is a scalar (all blocks); the new writer's list carries the layout
-        f"{arch}.attention.head_count_kv": (_T_UINT32, 1) if head_kv_scalar else (_T_ARRAY, kv_heads),
-        f"{arch}.attention.layer_norm_rms_epsilon": (_T_FLOAT32, 1e-6),
-        f"{arch}.attention.q_lora_rank": (_T_UINT32, q_lora),
-        f"{arch}.attention.kv_lora_rank": (_T_UINT32, D),
-        f"{arch}.attention.key_length_mla": (_T_UINT32, D // 2),
-        f"{arch}.attention.value_length_mla": (_T_UINT32, D // 2),
-        f"{arch}.attention.indexer.head_count": (_T_UINT32, 2),
-        f"{arch}.attention.indexer.key_length": (_T_UINT32, 8),
-        f"{arch}.attention.indexer.top_k": (_T_UINT32, 64),
-        f"{arch}.attention.indexer.kpool": (_T_UINT32, 4),
-        f"{arch}.attention.indexer.types": (_T_ARRAY, [True] * (n_layers + n_mtp)),
-        f"{arch}.ssm.conv_kernel": (_T_UINT32, 4),
-        f"{arch}.kda.head_dim": (_T_UINT32, KDA_D),
-        f"{arch}.kda.gate_lower_bound": (_T_FLOAT32, -5.0),
-        f"{arch}.leading_dense_block_count": (_T_UINT32, 0),
-        f"{arch}.expert_count": (_T_UINT32, E),
-        f"{arch}.expert_used_count": (_T_UINT32, 2),
-        f"{arch}.expert_shared_count": (_T_UINT32, 1),
-        f"{arch}.expert_feed_forward_length": (_T_UINT32, I // 2),
-        f"{arch}.expert_weights_norm": (_T_BOOL, True),
-        f"{arch}.expert_weights_scale": (_T_FLOAT32, 2.5),
-        f"{arch}.hyper_connection.count": (_T_UINT32, 2),
-        f"{arch}.hyper_connection.sinkhorn_iterations": (_T_UINT32, 20),
-        f"{arch}.hyper_connection.epsilon": (_T_FLOAT32, 1e-6),
-        f"{arch}.swiglu_clamp_exp": (_T_ARRAY, [10.0] * (n_layers + n_mtp)),
-        f"{arch}.nextn_predict_layers": (_T_UINT32, n_mtp),
-        "tokenizer.ggml.tokens": (_T_ARRAY, ["<unk>"] * V),
-        "tokenizer.ggml.model": (_T_STRING, "gpt2"),
-    }
-
-    tensors = [
-        ("token_embd.weight", (_Q8_0, (hidden, V), q8(hidden, V))),
-        ("output.weight", (_Q8_0, (hidden, V), q8(hidden, V))),
-        ("output_norm.weight", (_F32, (hidden,), f32(hidden).tobytes())),
-    ]
-    for blk in range(n_layers + n_mtp):
-        is_dsa = kv_heads[blk] == 1
-        tensors.append((f"blk.{blk}.attn_norm.weight", (_F32, (hidden,), f32(hidden).tobytes())))
-        tensors.append((f"blk.{blk}.ffn_norm.weight", (_F32, (hidden,), f32(hidden).tobytes())))
-        for sub in ("attn", "ffn"):
-            tensors.append((f"blk.{blk}.hc_{sub}_fn.weight", (_F32, (2 * hidden, 8), f32(8, 2 * hidden).tobytes())))
-            tensors.append((f"blk.{blk}.hc_{sub}_base.weight", (_F32, (8,), f32(8).tobytes())))
-            tensors.append((f"blk.{blk}.hc_{sub}_scale.weight", (_F32, (3,), f32(3).tobytes())))
-        if is_dsa:
-            tensors.append((f"blk.{blk}.attn_q_a.weight", (_Q8_0, (hidden, q_lora), q8(hidden, q_lora))))
-            tensors.append((f"blk.{blk}.attn_q_b.weight", (_Q8_0, (q_lora, H * (D // 2)), q8(q_lora, H * (D // 2)))))
-            tensors.append((f"blk.{blk}.attn_kv_a_mqa.weight", (_BF16, (hidden, D), bf16(hidden * D))))
-            if kv_b_q8_0:
-                tensors.append((f"blk.{blk}.attn_k_b.weight", (_Q8_0, (D // 2, D, H), q8(D // 2, D * H))))
-                tensors.append((f"blk.{blk}.attn_v_b.weight", (_Q8_0, (D, D // 2, H), q8(D, (D // 2) * H))))
-            else:
-                tensors.append((f"blk.{blk}.attn_k_b.weight", (_BF16, (D // 2, D, H), bf16(D * (D // 2) * H))))
-                tensors.append((f"blk.{blk}.attn_v_b.weight", (_BF16, (D, D // 2, H), bf16(D * (D // 2) * H))))
-            tensors.append((f"blk.{blk}.attn_output.weight", (_Q8_0, (H * (D // 2), hidden), q8(H * (D // 2), hidden))))
-            tensors.append((f"blk.{blk}.attn_q_a_norm.weight", (_F32, (q_lora,), f32(q_lora).tobytes())))
-            tensors.append((f"blk.{blk}.attn_kv_a_norm.weight", (_F32, (D,), f32(D).tobytes())))
-            tensors.append((f"blk.{blk}.indexer.attn_q_b.weight", (_BF16, (q_lora, 16), bf16(q_lora * 16))))
-            tensors.append((f"blk.{blk}.indexer.attn_k.weight", (_BF16, (hidden, 8), bf16(hidden * 8))))
-            tensors.append((f"blk.{blk}.indexer.k_norm.weight", (_F32, (8,), f32(8).tobytes())))
-            tensors.append((f"blk.{blk}.indexer.k_norm.bias", (_F32, (8,), f32(8).tobytes())))
-            tensors.append((f"blk.{blk}.indexer.proj.weight", (_F32, (hidden, 2), f32(hidden, 2).tobytes())))
-            tensors.append((f"blk.{blk}.indexer_compressor_gate.weight", (_F32, (hidden, 8), f32(hidden, 8).tobytes())))
-            tensors.append((f"blk.{blk}.indexer_compressor_ape.weight", (_F32, (8, 4), f32(8, 4).tobytes())))
-        else:
-            for name in ("attn_q", "attn_k", "attn_v", "ssm_beta", "ssm_f_a", "ssm_g_a"):
-                out_rows = QKV if name in ("attn_q", "attn_k", "attn_v") else (KDA_H if name == "ssm_beta" else KDA_D)
-                gt = _Q8_0 if name in ("attn_q", "attn_k", "attn_v") else _BF16
-                payload = q8(hidden, out_rows) if gt == _Q8_0 else bf16(out_rows * hidden)
-                tensors.append((f"blk.{blk}.{name}.weight", (gt, (hidden, out_rows), payload)))
-            tensors.append((f"blk.{blk}.ssm_f_b.weight", (_BF16, (KDA_D, QKV), bf16(KDA_D * QKV))))
-            tensors.append((f"blk.{blk}.ssm_g_b.weight", (_BF16, (KDA_D, QKV), bf16(KDA_D * QKV))))
-            tensors.append((f"blk.{blk}.attn_output.weight", (_Q8_0, (QKV, hidden), q8(QKV, hidden))))
-            for q in ("q", "k", "v"):
-                conv_ne = (4, 1, QKV, 1) if conv_unit_dim else (4, 1, QKV)
-                tensors.append((f"blk.{blk}.ssm_conv1d_{q}.weight", (_F32, conv_ne, f32(4, 1, QKV).tobytes())))
-            tensors.append((f"blk.{blk}.ssm_a", (_F32, (KDA_H,), (-np.abs(f32(KDA_H)) - 0.1).tobytes())))
-            tensors.append((f"blk.{blk}.ssm_dt.bias", (_F32, (QKV,), f32(QKV).tobytes())))
-            tensors.append((f"blk.{blk}.ssm_norm.weight", (_F32, (KDA_D,), f32(KDA_D).tobytes())))
-        # every decoder block here is MoE (leading_dense_block_count 0)
-        tensors.append((f"blk.{blk}.ffn_gate_inp.weight", (_F32, (hidden, E), f32(hidden, E).tobytes())))
-        tensors.append((f"blk.{blk}.exp_probs_b.bias", (_F32, (E,), f32(E).tobytes())))
-        tensors.append((f"blk.{blk}.ffn_gate_exps.weight", (_IQ3_S, (hidden, I // 2, E), iq3(hidden, I // 2, E))))
-        tensors.append((f"blk.{blk}.ffn_up_exps.weight", (_IQ3_S, (hidden, I // 2, E), iq3(hidden, I // 2, E))))
-        tensors.append((f"blk.{blk}.ffn_down_exps.weight", (_IQ4_XS, (I // 2, hidden, E), iq4(I // 2, hidden, E))))
-        for p in ("gate", "up"):
-            tensors.append((f"blk.{blk}.ffn_{p}_shexp.weight", (_Q8_0, (hidden, I // 2), q8(hidden, I // 2))))
-        tensors.append((f"blk.{blk}.ffn_down_shexp.weight", (_Q8_0, (I // 2, hidden), q8(I // 2, hidden))))
-    _gguf_writer(path, kvs, tensors)
-
-
-@pytest.fixture(scope="module")
-def glm_gguf(tmp_path_factory):
-    path = tmp_path_factory.mktemp("glm5gguf") / "glm5-test.gguf"
-    _make_gguf(str(path))
-    return str(path)
-
-
-def _shim(path):
-    from freetoken.models.gguf.config import build_gguf_shim
-
-    return build_gguf_shim(path)
-
-
-def test_shim_routes_the_architecture(glm_gguf):
-    shim = _shim(glm_gguf)
-    assert shim.architectures == ["Glm5NextGGUFForCausalLM"]
-    assert shim.vocab_size == 64
-    assert shim.tie_word_embeddings is False
-
-
-def test_parse_gguf_config_matches_layer_census(glm_gguf):
-    from freetoken.models.glm5_next.args import DSA_LAYER, KDA_LAYER
-    from freetoken.models.glm5_next.gguf import parse_gguf_config
-
-    config = parse_gguf_config(_shim(glm_gguf))
-    args = config.glm5_args
-    # the trailing MTP block is dropped, and head_count_kv lays out KDA|DSA
-    assert config.num_layers == 2
-    assert args.layer_types == (KDA_LAYER, DSA_LAYER)
-    assert config.first_k_dense_replace == 0
-    assert config.num_experts == 4 and config.num_experts_per_tok == 2
-    assert args.qk_nope_head_dim == 16 and args.v_head_dim == 16 and args.qk_rope_head_dim == 0
-    assert args.index_kpool == 4 and args.index_kpool_compress and args.index_kpool_always_select_tail
-    assert args.indexer_rope_interleave  # the served fact the GGUF KV predates
-    assert config.expert_quant == "gguf"
-    assert config.swiglu_limit == 10.0
-
-
-def test_legacy_arch_spelling_routes_identically(tmp_path):
-    path = tmp_path / "glm5-legacy.gguf"
-    _make_gguf(str(path), arch="glm5next")
-    assert _shim(str(path)).architectures == ["Glm5NextGGUFForCausalLM"]
-
-
-def test_head_count_kv_fallback_uses_tensor_census(tmp_path):
-    """The pre-list writer (unsloth's first release) is laid out from the tensor names."""
-    from freetoken.models.glm5_next.args import DSA_LAYER, KDA_LAYER
-    from freetoken.models.glm5_next.gguf import _layer_types
-
-    path = tmp_path / "glm5-nolist.gguf"
-    _make_gguf(str(path))
-    shim = _shim(str(path))
-    stripped = type(shim)(
-        architectures=shim.architectures,
-        model_path=shim.model_path,
-        model_type=shim.model_type,
-        metadata={k: v for k, v in shim.metadata.items() if not k.endswith("attention.head_count_kv")},
-        vocab_size=shim.vocab_size,
-        tie_word_embeddings=shim.tie_word_embeddings,
-    )
-    assert _layer_types(stripped, 2) == (KDA_LAYER, DSA_LAYER)
-
-
-def test_reader_state_dict_matches_model(glm_gguf):
-    _tp1()
-    from dataclasses import replace
-
-    from freetoken.models.glm5_next import Glm5NextForCausalLM
-    from freetoken.models.glm5_next.gguf import iter_gguf_weights, parse_gguf_config
-    from freetoken.models.register import checkpoint_quant_config, get_model_spec
-
-    shim = _shim(glm_gguf)
-    config = parse_gguf_config(shim)
-    spec = get_model_spec(shim.architectures[0])
-    config = replace(config, quant=checkpoint_quant_config(glm_gguf, shim, spec))
-    model = Glm5NextForCausalLM(config)
-    want = model.state_dict()
-    got = dict(iter_gguf_weights(glm_gguf, torch.device("cpu"), include_moe_experts=False, include_non_moe=True))
-    assert set(want) == set(got), f"missing={sorted(set(want) - set(got))[:6]} extra={sorted(set(got) - set(want))[:6]}"
-    for k in sorted(want):
-        assert tuple(want[k].shape) == tuple(got[k].shape), k
-
-
-def test_quantized_kv_b_halves_serve_dense(tmp_path):
-    """Dynamic quants (unsloth UD) store the per-head kv_b halves Q8_0, not bf16: the
-    module stays dense -- the reader dequantizes and fuses -- instead of refusing it."""
-    _tp1()
-    from dataclasses import replace
-
-    from freetoken.models.glm5_next import Glm5NextForCausalLM
-    from freetoken.models.glm5_next.gguf import iter_gguf_weights, parse_gguf_config
-    from freetoken.models.register import checkpoint_quant_config, get_model_spec
-
-    path = str(tmp_path / "glm5-kvq8.gguf")
-    _make_gguf(path, kv_b_q8_0=True)
-    shim = _shim(path)
-    spec = get_model_spec(shim.architectures[0])
-    config = replace(parse_gguf_config(shim), quant=checkpoint_quant_config(path, shim, spec))
-    model = Glm5NextForCausalLM(config)
-    assert config.quant.scheme_for("model.layers.1.self_attn.kv_b_proj") is None
-    got = dict(iter_gguf_weights(path, torch.device("cpu"), include_moe_experts=False, include_non_moe=True))
-    want = model.state_dict()
-    assert set(want) == set(got), f"missing={sorted(set(want) - set(got))[:6]} extra={sorted(set(got) - set(want))[:6]}"
-    for k in sorted(want):
-        assert tuple(want[k].shape) == tuple(got[k].shape), k
-
-
-def test_converter_transforms_are_undone(glm_gguf):
-    from freetoken.models.gguf.reader import gguf_tensor_index
-    from freetoken.models.gguf.tensors import float_tensor
-    from freetoken.models.glm5_next.gguf import iter_gguf_weights
-
-    got = dict(iter_gguf_weights(glm_gguf, torch.device("cpu"), include_moe_experts=False, include_non_moe=True))
-    index = gguf_tensor_index(glm_gguf)
-    # A_log: the converter stores -exp(A_log); the reader inverts to the raw log
-    stored = float_tensor(index["blk.0.ssm_a"])
-    assert torch.allclose(got["model.layers.0.self_attn.A_log"], torch.log(-stored))
-    # kv_b: per-head k [lora, nope] (transposed) + v [v, lora] fuse to [heads*(nope+v), lora]
-    k = float_tensor(index["blk.1.attn_k_b.weight"]).transpose(1, 2)
-    v = float_tensor(index["blk.1.attn_v_b.weight"])
-    expect = torch.cat([k, v], dim=1).reshape(-1, 32).to(torch.bfloat16)
-    assert torch.equal(got["model.layers.1.self_attn.kv_b_proj.weight"], expect)
-    # conv1d: q|k|v conv kernels concatenate on the channel axis
-    conv = torch.cat([float_tensor(index[f"blk.0.ssm_conv1d_{q}.weight"]) for q in ("q", "k", "v")], dim=0)
-    assert torch.equal(got["model.layers.0.self_attn.conv1d.weight"], conv.to(torch.bfloat16))
-
-
-def test_to_gguf_maps_the_fused_and_packed_modules(glm_gguf):
-    from freetoken.models.glm5_next.gguf import to_gguf
-
-    assert to_gguf("model.language_model.embed_tokens", {}) == ("token_embd",)
-    assert to_gguf("lm_head", {}) == ("output",)
-    for leaf, gguf_name in (
-        ("q_proj", "attn_q"), ("k_proj", "attn_k"), ("v_proj", "attn_v"),
-        ("b_proj", "ssm_beta"), ("f_a_proj", "ssm_f_a"), ("g_a_proj", "ssm_g_a"),
-    ):
-        assert to_gguf(f"model.language_model.layers.0.self_attn.{leaf}", {}) == (f"blk.0.{gguf_name}",)
-    assert to_gguf("model.language_model.layers.3.mlp.experts.0.gate_proj", {}) == ("blk.3.ffn_gate_exps",)
-    assert to_gguf("model.language_model.layers.3.mlp.gate", {}) == ()
-
-
-def test_fused_covers_the_mmq_tail():
-    """A packed segment must cover the bytes MMQ reads past the last row: the KDA f_b / g_b
-    (K = linear head dim 128) are the family's first K below half a padding unit."""
-    from types import SimpleNamespace
-
-    from freetoken.layers.quantization.ggml_types import mmq_tail_bytes, row_bytes
-    from freetoken.models.gguf.tensors import fused
-
-    k = 128
-    part = torch.zeros(96, row_bytes(8, k), dtype=torch.uint8)  # Q8_0
-    out = dict(fused("l0.self_attn.f_b_proj", [SimpleNamespace(ggml_type=8)], [part], k))
-    assert out["l0.self_attn.f_b_proj.weight"].numel() >= 96 * row_bytes(8, k) + mmq_tail_bytes(8, k)
-
-
-def test_scalar_head_count_kv_falls_back_to_census(tmp_path):
-    """The generic GGUF spelling of head_count_kv is a scalar (all blocks), which is wrong for the
-    hybrid -- llama.cpp broadcasts it and then fails tensor creation; the census recovers the layout."""
-    from freetoken.models.glm5_next.args import DSA_LAYER, KDA_LAYER
-    from freetoken.models.glm5_next.gguf import _layer_types, parse_gguf_config
-
-    path = str(tmp_path / "glm5-scalar.gguf")
-    _make_gguf(path, head_kv_scalar=True)
-    shim = _shim(path)
-    assert _layer_types(shim, 2) == (KDA_LAYER, DSA_LAYER)
-    assert parse_gguf_config(shim).num_layers == 2
-
-
-def test_conv_kernels_with_a_trailing_unit_dim(tmp_path):
-    """Some writers ship the conv kernels 4-D; llama.cpp's glm5-next loader tries that shape first."""
-    _tp1()
-    from dataclasses import replace
-
-    from freetoken.models.glm5_next import Glm5NextForCausalLM
-    from freetoken.models.glm5_next.gguf import iter_gguf_weights, parse_gguf_config
-    from freetoken.models.register import checkpoint_quant_config, get_model_spec
-
-    path = str(tmp_path / "glm5-conv4d.gguf")
-    _make_gguf(path, conv_unit_dim=True)
-    shim = _shim(path)
-    spec = get_model_spec(shim.architectures[0])
-    config = replace(parse_gguf_config(shim), quant=checkpoint_quant_config(path, shim, spec))
-    model = Glm5NextForCausalLM(config)
-    got = dict(iter_gguf_weights(path, torch.device("cpu"), include_moe_experts=False, include_non_moe=True))
-    want = model.state_dict()
-    assert set(want) == set(got)
-    assert tuple(want["model.layers.0.self_attn.conv1d.weight"].shape) == tuple(got["model.layers.0.self_attn.conv1d.weight"].shape)