Problem

quant.h (single-header) and src/engine/*.c (split sources / libturboquant) implement the same inference logic independently. They have diverged, causing:

• SmolLM2-1.7B server inference regression after 91814d4 (Phi-3 CPU fallback) #77: SmolLM2-1.7B produces garbage via quant-server (libturboquant) but works perfectly via quant.h
• Phi-3 support not propagated from quant.h to libturboquant (quant-server broken) #67: Phi-3 support had to be ported manually from quant.h to split sources, introducing a regression
• Every new feature (chat-cache, fused QKV, LongRoPE) requires manual porting between the two codebases

Root cause of #77: tq_forward() in src/engine/tq_transformer.c has numerical instability at layer 7 (hidden state max=18,359) that does not exist in quant.h's identical function. This proves the two implementations have diverged.

Proposal: SQLite-style amalgamation

Make quant.h the single source of truth. Auto-generate split sources from it.

Current (broken)

quant.h  ←── manual edits
    ↕ manual sync (humans port changes)
src/engine/*.c  ←── manual edits, diverged

Proposed

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 sketch

# tools/split_header.py
# 1. Parse quant.h sections by marker comments:
#    // --- SECTION: transformer ---
#    // --- END SECTION ---
# 2. Extract each section into corresponding .c file
# 3. Generate appropriate #include headers
# 4. Add "DO NOT EDIT — auto-generated from quant.h" header

Benefits

1. Zero sync bugs — split sources are always identical to quant.h
2. Single place to fix bugs — fix in quant.h, regenerate
3. GPU backends unaffected — Metal/CUDA kernels stay separate (they call into the generated code)
4. CI can verify — python tools/split_header.py && git diff --exit-code src/engine/

Migration path

1. Add section markers to quant.h (non-breaking)
2. Write split_header.py
3. Regenerate src/engine/*.c from quant.h
4. Verify: same binary output for SmolLM2, Phi-3.5
5. Add CI step: fail if generated files are stale
6. Delete manual src/engine/*.c from version control (generated only)

Precedent

• SQLite: sqlite3.c amalgamation is the canonical source; split files are for development
• stb libraries: single-header is the distribution format
• Dear ImGui: single compilation unit is the recommended build

Impact

This would immediately fix #77 and prevent all future sync-divergence bugs. The quant.h path is proven correct (35/35 tests, coherent output for SmolLM2 + Phi-3.5 + Llama). Making it authoritative eliminates an entire class of bugs.

Proposed by ClawTeam based on root-cause analysis of #77