feat: scripts/verify_arch.py + make verify-arch

Cross-checks the README "Architecture" forward-pass bullets against
the actual GGUF metadata. After correcting the MTP claim in 732c3be
it was worth confirming no other quiet inaccuracies in the
quantitative bullets. All thirteen claims (block_count, context,
embedding/FFN, attention head counts + key/value lengths, RoPE
dimension count, full_attention_interval, SSM state/dt/group, vocab)
verify clean on both qwen35- and qwen36-stamped bundles.

The script encodes the (claim, expected, gguf-key) mapping as a
reusable artifact — useful after future re-stamps, re-conversions,
or upstream converter updates that might silently drift metadata.
Exit non-zero on mismatch.

Not added to `make check` (which is meant to be cheap + pre-commit
hookable); reading the 17 GB tensor file requires the LFS smudge
and a few seconds of I/O. Exposed as a dedicated `make verify-arch`
target instead. README "What's here" table picks up the new entry;
CHANGELOG documents the audit + script.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

CHANGELOG.md

@@ -7,6 +7,23 @@ and documentation**, not the underlying base model.
 
 ## [Unreleased]
 
+### Added
+- `scripts/verify_arch.py` + `make verify-arch`. After correcting the
+  MTP bullet (see Fixed below) it was worth confirming the remaining
+  Architecture forward-pass bullets weren't carrying any other quiet
+  inaccuracies. Cross-checked all thirteen quantitative claims
+  (layer count, hidden / FFN dims, head counts, head_dim, RoPE
+  factor, hybrid stack interval, SSM dims, vocab, context) against
+  the actual GGUF metadata keys; every one verified clean on both
+  the qwen35- and qwen36-stamped bundles. The script captures that
+  mapping as a reusable artifact: pass it a path to a Thanatos-27B
+  (or compatible) GGUF and it prints each bullet alongside the
+  metadata key it derives from, exiting non-zero on mismatch.
+  Useful after future re-stamps / re-conversions / upstream
+  converter updates. Not folded into `make check` because it has
+  to read the 17 GB tensor file (LFS smudge required) — run on
+  demand.
+
 ### Fixed
 - README "Multi-token prediction (MTP)" bullet corrected. The
   earlier wording — "MTP head trained for speculative decoding" —

Makefile

@@ -26,7 +26,7 @@ MODEL ?= $(TAG)
 
 PRECISION ?= F16
 
-.PHONY: help build load-bundle heal-hf smoke smoke-tools bench check hooks mmproj clean
+.PHONY: help build load-bundle heal-hf smoke smoke-tools bench check hooks mmproj verify-arch clean
 
 help:  ## Show this help.
 	@awk 'BEGIN {FS = ":.*##"; printf "Targets:\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2 }' $(MAKEFILE_LIST)
@@ -61,6 +61,9 @@ mmproj:  ## Fetch the vision projector for llama.cpp (Ollama vision is broken up
 check:  ## Lint shell + python files; block dot-pattern footgun.
 	./scripts/check.sh
 
+verify-arch:  ## Cross-check README "Architecture" bullets against GGUF metadata.
+	./scripts/verify_arch.py
+
 hooks:  ## Install scripts/check.sh as the git pre-commit hook.
 	./scripts/install-hooks.sh
 

README.md

@@ -137,6 +137,7 @@ The 27B is **dense**: every parameter participates in every forward pass. It's s
 | `scripts/fetch_vision.sh` | Pulls the vision projector (`mmproj-F16.gguf`) for llama.cpp (Ollama vision is broken upstream — see [Vision](#vision)). Renamed from `fetch_mmproj.sh` because HF's Ollama bridge auto-indexed the script as a vision projector layer (filename pattern match). |
 | `scripts/check.sh` | Local lint: `bash -n`, `pyflakes`, `py_compile`, footgun-grep, plus `Modelfile`-vs-bridge-files sync check |
 | `scripts/check_bridge_sync.py` | Verifies the `Modelfile` `TEMPLATE` / `SYSTEM` / `PARAMETER` directives stay in sync with the root-level `template` / `system` / `params` files. Run as part of `make check`; called from the pre-commit hook. |
+| `scripts/verify_arch.py` | Cross-checks the README "Architecture" forward-pass bullets (layer count, head counts, hidden / FFN dims, RoPE factor, SSM dims, vocab, context) against the actual GGUF metadata keys. Run as `make verify-arch`. Handles both `qwen35`- and `qwen36`-stamped bundles; exit non-zero if any value mismatches. Not part of `make check` because it loads the 17 GB GGUF (LFS smudge required); run on demand. |
 | `scripts/install-hooks.sh` | Installs `check.sh` as a git pre-commit hook |
 | `Makefile` | Convenience wrapper — `make help` lists targets |
 | `LICENSE`, `CITATION.cff` | Apache-2.0 license and citation metadata |

scripts/verify_arch.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""
+Thanatos-27B — verify the README "Architecture" forward-pass bullets
+against the actual GGUF metadata.
+
+Reads either the qwen35- or qwen36-stamped bundle (or any GGUF that
+declares one of those `general.architecture` values), prints each
+README claim alongside the metadata key it derives from, and exits
+non-zero if any value mismatches the expected README claim. Useful
+as a manual audit after the bundle is re-stamped or after upstream
+re-conversion.
+
+Usage:
+    python3 scripts/verify_arch.py                              # default bundle
+    python3 scripts/verify_arch.py Thanatos-27B.Q4_K_M.gguf
+    python3 scripts/verify_arch.py /path/to/some-other.gguf
+
+Exit code 0 = all claims verify, 1 = at least one mismatch.
+
+Note: this does NOT verify the 27B parameter count directly (no such
+KV in the GGUF) — that comes from llama.cpp's `case 64: LLM_TYPE_27B`
+branch in `src/models/qwen35.cpp`, not from the file itself.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from gguf import GGUFReader
+
+EXPECTED = {
+    "block_count": (64, "64 transformer layers"),
+    "context_length": (262144, "262 144 native context"),
+    "embedding_length": (5120, "Hidden size 5120"),
+    "feed_forward_length": (17408, "FFN intermediate 17408"),
+    "attention.head_count": (24, "Gated Attention: 24 Q-heads"),
+    "attention.head_count_kv": (4, "Gated Attention: 4 KV-heads (GQA)"),
+    "attention.key_length": (256, "Gated Attention: head_dim 256 (key)"),
+    "attention.value_length": (256, "Gated Attention: head_dim 256 (value)"),
+    "rope.dimension_count": (64, "Partial RoPE: 64 of 256 dims (factor 0.25)"),
+    "full_attention_interval": (4, "Hybrid stack: every 4th layer is full attention (16 cycles)"),
+    "ssm.state_size": (128, "Gated DeltaNet: head_dim 128"),
+    "ssm.time_step_rank": (48, "Gated DeltaNet: 48 V-heads"),
+    "ssm.group_count": (16, "Gated DeltaNet: 16 QK-heads"),
+}
+EXPECTED_VOCAB = 248320
+EXPECTED_ARCHS = {"qwen35", "qwen36"}
+
+
+def read_scalar(reader: GGUFReader, key: str):
+    f = reader.fields.get(key)
+    if f is None:
+        return None
+    arr = f.parts[f.data[0]]
+    val = arr.tolist() if hasattr(arr, "tolist") else arr
+    if isinstance(val, list) and len(val) == 1:
+        return val[0]
+    return val
+
+
+def read_arch(reader: GGUFReader) -> str:
+    f = reader.fields["general.architecture"]
+    return bytes(f.parts[f.data[0]]).decode()
+
+
+def main() -> int:
+    if len(sys.argv) > 2:
+        print(f"usage: {sys.argv[0]} [path/to/Thanatos-27B.Q4_K_M.gguf]", file=sys.stderr)
+        return 2
+    root = Path(__file__).resolve().parent.parent
+    default_paths = [
+        root / "Thanatos-27B.Q4_K_M.qwen35.gguf",
+        root / "Thanatos-27B.Q4_K_M.qwen36.gguf",
+        root / "Thanatos-27B.Q4_K_M.gguf",
+    ]
+    if len(sys.argv) == 2:
+        path = Path(sys.argv[1])
+    else:
+        path = next((p for p in default_paths if p.exists() and p.stat().st_size > 1024), None)
+        if path is None:
+            print("[!] no Thanatos-27B GGUF found in repo root; pass a path explicitly", file=sys.stderr)
+            return 2
+
+    print(f"[*] reading: {path}")
+    reader = GGUFReader(str(path), "r")
+
+    arch = read_arch(reader)
+    if arch not in EXPECTED_ARCHS:
+        print(f"[!] unexpected general.architecture: {arch!r} (expected one of {EXPECTED_ARCHS})", file=sys.stderr)
+        return 1
+    print(f"[*] general.architecture: {arch}")
+    print()
+
+    mismatches = 0
+    fmt = "  {marker} {claim:55s}  {key:35s} = {actual}"
+    for suffix, (expected, claim) in EXPECTED.items():
+        key = f"{arch}.{suffix}"
+        actual = read_scalar(reader, key)
+        ok = actual == expected
+        marker = "[ ok ]" if ok else "[FAIL]"
+        print(fmt.format(marker=marker, claim=claim, key=key, actual=actual))
+        if not ok:
+            mismatches += 1
+
+    # Vocab count comes from the tokenizer tokens array length, not a scalar KV.
+    f = reader.fields.get("tokenizer.ggml.tokens")
+    vocab_actual = len(f.data) if f is not None else None
+    ok = vocab_actual == EXPECTED_VOCAB
+    marker = "[ ok ]" if ok else "[FAIL]"
+    print(fmt.format(marker=marker, claim=f"Vocab {EXPECTED_VOCAB}", key="tokenizer.ggml.tokens (length)", actual=vocab_actual))
+    if not ok:
+        mismatches += 1
+
+    print()
+    if mismatches:
+        print(f"[!] {mismatches} mismatch(es) — README Architecture claims disagree with GGUF metadata.")
+        return 1
+    print("[+] all Architecture claims verify against GGUF metadata.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())