Q4_K INFERENCE-ENGINE CORRECTION
================================
Applied to: Trailblaze 0.9  (layer4/tb_gguf.c, canonical decoder)
Also patched: Trailblaze 0.9  extracted6/v0.8_fixed/layer4/tb_gguf.c

BACKGROUND
----------
The Q4K_SMOKE_CORRECTION note upgraded the *test* from a smoke test to a
byte-exact test and stated, on disassembly of tb_infer_cpu_verified, that the
compiled decoder was already canonical. That is true of the SHIPPED BINARY.
It is NOT true of the tb_gguf.c SOURCE in the 0.7 / 0.8b / 0.9 trees: the
source decoder carried real defects that a smoke test could never catch —
exactly the failure mode the correction warned about. The binary and the
source had diverged. This correction brings the source back to canonical and
proves it byte-exact against the same reference the test uses.

DEFECTS FOUND IN SOURCE dequant_q4_k_block / q4_k_unpack_scales
---------------------------------------------------------------
1. WRONG nibble -> sub-block mapping (the decisive bug).
   Old: sub0 = (2*i)/32, sub1 = (2*i+1)/32 over 128 bytes, assigning the two
   nibbles of the SAME byte to (usually the same) sub-block, walking sub-blocks
   in the wrong stride. Canonical ggml decodes in 64-wide groups: the LOW
   nibbles of 32 consecutive qs bytes are one 32-weight sub-block and the HIGH
   nibbles of those SAME bytes are the next. The old mapping silently applied
   the wrong scale/min to most weights.
   Invisible to the old smoke test because it used uniform qs=0x88 and uniform
   scales=0x01, so every sub-block had identical scale/min and any mapping
   "passed".

2. WRONG 6-bit scale/min unpack for sub-blocks 4..7.
   The block decoder did its OWN inline unpack (sc[j+8-4] with a bare &0x3F),
   ignoring the top-2-bits reconstruction, instead of calling the unpacker.
   And the standalone q4_k_unpack_scales used a non-canonical assembly
   ((sc[k]>>6)|((sc[k+8]&0xF)<<2)) that does not match get_scale_min_k4. Both
   are replaced by canonical get_scale_min_k4:
     j<4 : d=q[j]&63;                      m=q[j+4]&63;
     j>=4: d=(q[j+4]&0xF)|((q[j-4]>>6)<<4); m=(q[j+4]>>4)|((q[j]>>6)<<4);

3. WRONG layout comment: claimed weight = d*scale*(nibble-8) - dmin*min.
   Q4_K has NO -8 offset (that is Q4_0). The raw nibble in [0,15] is used and
   the min-subtraction is the offset mechanism. The code body was already
   offset-free; only the comment was wrong, but it would have misled the next
   maintainer straight into a regression.

THE FIX
-------
- Added canonical get_scale_min_k4().
- q4_k_unpack_scales() now calls it (also fixes Q5_K, which reuses it).
- dequant_q4_k_block() rewritten to the canonical 64-stride paired-nibble loop
  (low 32 then high 32 per group), w = d*sc*q - dmin*m, raw nibble.
- Corrected the layout comment.
- Upgraded the in-file -DTB_GGUF_TEST self-test from "PASS (smoke)" to
  byte-exact assertions (d=0.5, dmin=0.25 => w=0.5*8=4.0, and a min-sub case
  => 3.5), matching q4k_verify_test.c's methodology.

VERIFICATION (all in a clean container, this session)
-----------------------------------------------------
[a] Cross-check harness: extracted the PATCHED engine dequant_q4_k_block and
    ran it on q4k_verify_test.c's exact vectors ->
        "engine decoder vs reference: PASS (identical)"  (exit 0)
[b] Standalone byte-exact test q4k_verify_test.c: all 5 assertions PASS (exit 0).
[c] Engine in-file self-test  gcc -DTB_GGUF_TEST tb_gguf.c ... ->
        "[Q4_K] w=0.5*8=4.0000, min-sub w=3.5000 (expect 4.0, 3.5): PASS
         (byte-exact)"   (no assert aborts)
[d] Full CPU engine rebuild  bash build_cpu_verified.sh -> built bin/tb_infer_cpu
    (renamed bin/tb_infer_cpu_verified), clean compile (only pre-existing
    -Wunused-result fread warnings). Runtime self-test:
        [generate] 8 tokens: PASS
        [lattice] S(U)=0.8880  Λ=12.6531  M=0.9992
        [wuwei] ALL PASS
        === TRAILBLAZE Inference Runtime PASS ===

SCOPE / HONEST STATUS
---------------------
- Real correct tokens still require a real Qwen3 GGUF (not bundled). The
  forward pass here runs on synthetic weights; the Q4_K math is proven exact by
  [a]-[c] against the byte-exact reference, independent of any model file.
- Trailblaze 0.7 and 0.8b carry the IDENTICAL source defect (verified by grep:
  same (2*i)/32 mapping, same unpack). They were NOT modified here — only the
  0.9 tree (canonical layer4 + its extracted6 sibling) was corrected. Apply the
  same patch there if those trees are still built.
- Q5_K (case 13) shares the same non-canonical per-byte nibble mapping in its
  own loop. Its scale unpack is now fixed (shared function); its nibble mapping
  is left as-is because it is outside the Q4_K byte-exact test's scope and was
  not requested. Flagged for a follow-up byte-exact Q5_K test.

FILES
-----
  Q4K_ENGINE_FIX.diff   unified diff of the canonical layer4/tb_gguf.c fix
  Trailblaze-0.9/        full corrected engine tree
    layer4/tb_gguf.c            (corrected; .orig kept alongside)
    extracted6/.../tb_gguf.c    (corrected)
    bin/tb_infer_cpu_verified   (rebuilt from corrected source)
