Engine Inference Core E2: DeepSeek V3 / V3.2 / V4 (MLA + MoE)

[tlkahn]

E2 - DeepSeek V3 / V3.2 / V4 (MLA + MoE; separate families)

Port DeepSeek generate families from mlx-lm (deepseek_v3.py / deepseek_v32.py + mla.py), not from mlx-serve ds4.zig. Safetensors + standard mlx-c ops only.

Spec: doc/plans/engine-inference-core.md § E2

Part of: #56
Depends on: E1 (#104)

Decision 5 superseded (2026-07-20): mlx-lm implements DeepSeek V3/V3.2/V4 natively on safetensors - no GGUF or ds4 engine. Target checkpoint: mlx-community/DeepSeek-V4-Flash-4bit.

Decision 11 (2026-07-20): do not collapse variants into MODEL_DEEPSEEK_V4. Enum grain:

• deepseek_v3 -> MODEL_DEEPSEEK_V3 (MLA + MoE)
• deepseek_v3_2 / deepseek_v32 -> MODEL_DEEPSEEK_V32 (MLA + MoE + DSA)
• deepseek_v4 -> MODEL_DEEPSEEK_V4 (own value; characterize Flash before any alias)

Shared code is primitives (fwd_mla_*, MultiLinear, MoE gate, sanitize), not one family tag. A1 interim debt still maps all four strings to MODEL_DEEPSEEK_V4 - correct before or at start of E2 (#109).

Sub-issues

• E2: Family split correction (decision 11) + DeepSeek config fields #109 Family split correction (decision 11) + DeepSeek config fields (do first)
• E2: MultiLinear (fwd_multi_linear) primitive for MLA #110 MultiLinear (fwd_multi_linear)
• E2: MLA attention + MLA KV cache #111 MLA attention + MLA KV cache
• E2: DeepSeek weight sanitization + weights_expected_names #112 Weight sanitization + weights_expected_names
• E2: Dense/MoE layer mixing + DeepSeek V3 forward wiring #113 Dense/MoE layer mixing + V3 forward wiring
• E2: V3.2 DSA indexer (MODEL_DEEPSEEK_V32) #114 V3.2 DSA indexer (MODEL_DEEPSEEK_V32)
• E2: V4 characterization + forward (DeepSeek-V4-Flash-4bit) #115 V4 characterization + forward
• E2: DeepSeek parity gates (mlx-lm oracle) #116 DeepSeek parity gates (oracle = mlx-lm)

Suggested order

1. E2: Family split correction (decision 11) + DeepSeek config fields #109 family split/config
2. E2: MultiLinear (fwd_multi_linear) primitive for MLA #110 MultiLinear, E2: DeepSeek weight sanitization + weights_expected_names #112 sanitize (can parallelize after E2: Family split correction (decision 11) + DeepSeek config fields #109)
3. E2: MLA attention + MLA KV cache #111 MLA (needs E2: MultiLinear (fwd_multi_linear) primitive for MLA #110)
4. E2: Dense/MoE layer mixing + DeepSeek V3 forward wiring #113 V3 forward (needs E1 + E2: MLA attention + MLA KV cache #111 + E2: DeepSeek weight sanitization + weights_expected_names #112)
5. E2: V3.2 DSA indexer (MODEL_DEEPSEEK_V32) #114 V3.2 indexer, E2: V4 characterization + forward (DeepSeek-V4-Flash-4bit) #115 V4 (after E2: Dense/MoE layer mixing + DeepSeek V3 forward wiring #113 base)
6. E2: DeepSeek parity gates (mlx-lm oracle) #116 parity (as each family lands)

Acceptance

• V3-class checkpoint generates and passes temp-0 parity vs mlx-lm
• V3.2 path exists as a real family fork (indexer + dual cache), not a boolean on collapsed V4
• V4 either characterized-and-implemented or explicitly aliased only after Flash inspection
• Reject/log strings name the actual family