fix(quantize): Q5_K readers decoded an invented layout — every Q5_K tensor on the CPU path and in apr import was wrong (PMAT-1101)

[noahgift]

Q5_K readers decoded an invented layout (PMAT-1101). P0 correctness, blocks #3091

What was wrong. ggml's block_q5_K stores 256 values in 176 bytes: d, dmin, 12 bytes of 6-bit scales and mins, qh[32], then qs[128]. Sub-blocks 2c and 2c+1 share the same 32 qs bytes, low nibbles first and then high nibbles. The fifth bit of value l in sub-block s is bit s of qh[l]. Three aprender readers each did something different:

Reader	Used by	What it did
realizar dequantize_q5_k + fused_q5k_dot	every CPU Q5_K matmul (apr run / serve / chat)	read the two nibbles of one byte as neighbouring values, and took the fifth bit from qh[4s + l/8]
aprender-quant dequantize_q5_k_to_f32	apr import (GGUF → APR)	gave each sub-block its own 16 qs bytes
aprender-quant quantize_q5_k	quantizing to Q5_K	packed the same wrong way

Measured on Qwen3.5-0.8B-Q4_K_M, where attn_qkv and ssm_out are Q5_K:

• On blk.0.attn_qkv (6144×1024), realizar and gguf-py (llama.cpp's own Python reader) disagree on 5,959,751 of 6,291,456 values (max |Δ| 0.59).
• Layer-0 QKV projection sum: realizar +26.64, llama.cpp −17.06, gguf-py −17.10. After the fix realizar gives −17.0967, and layers 0–2 of the CPU: Qwen3.5 / Qwen3.8 hybrid GGUFs are refused entirely — no fallback exists #3091 op-by-op trace match llama.cpp.

Why nothing caught it. Every Q5_K test compared one aprender reader against another. realizar's dequantizer and fused dot shared one invented layout; aprender-quant's quantizer and dequantizer shared another.

Fix

• realizar: a single block walker, for_each_q5k_value, emits values in ggml order. dequantize_q5_k and fused_q5k_dot both go through it, so the two can no longer disagree.
• aprender-quant: the reader and the packer now use ggml's layout.

FALSIFY-QDOT-007 (contracts/quantized-dot-product-v1.yaml, both copies) pins the readers to the 256 values gguf-py produced from a real super-block that llama.cpp quantized. The fixture is embedded in the tests.

• realizar quantize::tests::q5k_ggml::*: dequant is bit-exact; the fused dot with a one-hot activation returns each value exactly; the parallel matvec matches the gguf-py dot.
• aprender-quant tests::test_q5k_ggml_*: dequant is bit-exact; a quantize round-trip on data whose sub-blocks all differ stays within 0.15.

Mutation check. Each change below was reverted locally, and the tests went red every time:

• realizar nibble shift: RED
• realizar qh bit: RED
• aprender-quant reader: RED
• aprender-quant packer (sub-block halves swapped): RED

The packer mutant survived the existing ramp round-trip test, because a ramp gives every sub-block the same 5-bit codes. That is why the distinct-sub-block test exists.

Local gates

• Formatting and tests:
  • cargo fmt --check ✓
  • cargo test -p aprender-quant --lib ✓
  • cargo test -p aprender-serve --lib -- quantize::: 2223 passed
  • the four Q5_K integration targets ✓ (quantize_coverage, property_quantize, gguf_quantize_coverage, quantize_property_tests)
• Contracts and repo checks:
  • pv validate, both contract copies ✓
  • cargo test -p aprender-contracts --lib ✓
  • check_baseline_ratchets.sh ✓
  • cargo deny check advisories ✓
  • guard_tree.sh --no-cargo ✓, except check_complexity_ratchet.sh: the local pmat is not the pinned 3.39.0, so that failure is the instrument, not the code.
• Clippy:
  • cargo clippy -p aprender-quant --all-targets -- -D warnings -A unused-variables ✓
  • cargo clippy -p aprender-serve --lib --tests reports 5 errors that already exist on main, none in files this PR touches.

Not in this PR: the CUDA Q5_K kernels in aprender-gpu (q5k/gemv.rs, q5k/gemm.rs) carry two more wrong layouts. They are tracked in a separate issue and will get a GPU-side golden test.

Refs #3091

Pmat-Ticket: PMAT-1101

🤖 Generated with Claude Code

[github-actions]

§13.11 rung 1 — quorum shadow verdict

S13-SHADOW pr=3110 head=634436f33548f5736b55d02215a8e1b2695e3ef1 verdict=REFUSE class=Q1 arm_rc=1

Shadow mode: this records a verdict and merges nothing. A refusal
to arm is not a block (§13 adds zero rows to §7) — the pull request is
exactly as green as it was.

[noahgift]

Landed on main via train #3127 (cb829fc) — this branch's head is an ancestor of the train head a6148ab (PMAT-1098, 0.67.0).