Single Source of Truth: auto-generate split sources from quant.h

[unamedkr]

Summary

Make quant.h the canonical source and auto-generate src/engine/*.c from it, eliminating the sync-divergence bug class that caused #77 (SmolLM2 numerical instability in libturboquant).

Problem

quant.h and src/engine/*.c implement the same forward pass independently. They have diverged:

• quant.h: SmolLM2 works (23 tok/s), Phi-3.5 works (6.5 tok/s)
• libturboquant: SmolLM2 produces garbage (layer 7 max=18,359), Phi-3.5 crashes

Every new architecture (Phi-3, Gemma-4, Qwen3) requires manual porting between the two codebases. This is the #1 source of bugs.

Proposed Solution

quant.h (single source of truth)
    ↓ tools/split_header.py (automated)
src/engine/tq_transformer.c  ← auto-generated
src/engine/tq_generate.c     ← auto-generated
src/engine/tq_model.c        ← auto-generated

Implementation

1. Add section markers to quant.h:

   // --- SECTION: transformer ---
   float* tq_forward(tq_model_t* model, ...) { ... }
   // --- END SECTION ---

2. Write tools/split_header.py that extracts sections into .c files

3. CI check: python tools/split_header.py && git diff --exit-code src/engine/

Precedent

• SQLite: sqlite3.c amalgamation is the canonical source
• stb libraries: single-header is the distribution format

Impact

• Immediately fixes SmolLM2-1.7B server inference regression after 91814d4 (Phi-3 CPU fallback) #77 and prevents all future sync-divergence bugs
• New architecture support lands in one place, works everywhere
• GPU backends (Metal/CUDA) remain separate — they call into the generated code

Priority: P1

---

Root-cause analysis from ClawTeam Claw-5 (Researcher) investigation