fix(core): bound the declared quantization mode string at load

[inureyes]

Summary

quantization.mode was the one value in the quantization block that nothing in mlxcel-core bounded. #972 bounded group_size and bits and deliberately left the mode out of scope, and the only bound that existed anywhere was gemma4's private SUPPORTED_QUANT_SCHEMES. This adds mlxcel_core::layers::validate_quantization_mode, an allowlist mirroring MLX's own string_to_quantization_mode, and wires it into every path a declared mode can reach a kernel through.

An unrecognized mode was neither rejected nor defaulted. On the shared loader path it took the block-float branch of reconcile_quantization_layout, which on a genuine affine tensor re-derives the group size back onto the declared value, so nothing looked reconciled and not even the divergence warning fired. The string was then stored verbatim and handed to quantized_matmul / gather_qmm / dequantize on every forward pass. Those cross the cxx bridge as UniquePtr<MlxArray> rather than Result, so MLX's std::invalid_argument was an uncatchable std::terminate at the first forward pass, after the model had already loaded without a warning.

Two decisions the issue asked to be made explicitly

Exact comparison: no trimming, no case folding. MLX compares the raw string byte-for-byte and has no normalization of its own, so " Affine" parses in gemma4's old check and throws in the kernel. Normalizing before the comparison would accept a spelling that is then stored and forwarded unchanged, which is exactly the gap being closed. mlxcel also does not silently rewrite declared metadata (the #467 policy is to warn, not override), so there is no correct place to put a normalized value even if one were computed. gemma4's mode check becomes stricter as a result, which is the right direction; its quant_method check keeps the permissive normalization it has always had, because a quant_method never reaches an MLX kernel.

An empty string is a declared value, not "not declared". "mode": "" survives obj.get("mode").and_then(|v| v.as_str()) as Some(""), reaches gather_qmm, and aborts. "Not declared" is the absence of the key, which every config reader already resolves to "affine" before anything is validated. gemma4 used to accept an empty mode; it no longer does.

Item 6: affine with no .biases

Rejected at load rather than repaired, and generalized to MLX's full precondition. Repairing via infer_quantization_mode would swap one uncatchable abort for another: relabelling a genuinely affine plane as block-float makes MLX throw Scale type must be uint8 but received type float16 instead. It also guesses, and silently overrides a declaration, which is what #467 exists to prevent.

validate_quantization_biases instead enforces both halves of MLX's validate_mode_with_type: affine requires .biases, every block-float mode requires their absence. Because the predicate is MLX's own, it can only refuse a load that was already going to abort. It is a provable no-op for every caller that goes through UnifiedLinear::from_weights / QuantizedEmbedding::from_weights, which derive the mode from bias presence via infer_quantization_mode and are consistent by construction. Only a caller threading a config-declared mode can trip it, which today is gpt-oss alone.

What changed

• src/lib/mlxcel-core/src/layers.rs: new SUPPORTED_QUANTIZATION_MODES, validate_quantization_mode and validate_quantization_biases; called from reconcile_quantization_layout (covering every UnifiedLinear and UnifiedEmbedding, and making the mode == "affine" branch total rather than a silent fallthrough), from UnifiedLinear::from_weights_with_mode and QuantizedEmbedding::from_weights_with_mode for the bias half, and from QuantizedWeight::new_with_mode, which becomes Result (it had no callers).
• src/models/switch_layers.rs: SwitchLinear::from_stacked_parts bounds the mode next to the existing validate_quantization_params, covering both the pre-stacked and per-expert layouts reached through the pub from_weights_with_mode. Adds the shared HOSTILE_QUANT_MODES table beside HOSTILE_QUANT_PARAMS.
• src/models/gpt_oss.rs: Quantization::validate stops discarding the mode and walks the top-level pair plus every per-prefix override, so a hostile mode is blamed on the prefix that declared it. ExpertLinear::from_weights bounds the mode and the bias pairing where it stores them.
• src/models/config.rs: QuantizationArgs::get_mode returns Result<&str, String>. It has no production callers and is the obvious thing for the next family to reach for, so the bound belongs on the signature.
• src/models/mod.rs: pub mod config;. See below.
• src/models/gemma4.rs: SUPPORTED_QUANT_SCHEMES is now the core constant rather than a private copy, and the mode comparison delegates to the core function. gemma4 keeps its quant_method and ModelOpt-NVFP4 policy, which is genuinely gemma4-shaped and covers fix: externally quantized 4-bit Gemma 4 (OptiQ) decodes to degenerate output that is trapped entirely in reasoning_content #467.

One premise corrected

The issue lists QuantizedEmbedding::from_weights_with_mode among the entry points that "never reach reconcile_quantization_layout". It does reach it, through reconcile_quantization_layout_logged, so the mode allowlist covers it via item 2 with no separate call needed. Only the bias-pairing half had to be added there. The numbered proposal's own item 3 lists a different (correct) set of four, naming ExpertLinear::from_weights in its place; all five surfaces are covered either way.

Test plan

Real-model runs, since CI runs no cargo test:

• models/gpt-oss-20b-mxfp4 loads and generates unchanged. The one local checkpoint whose declared mode reaches a kernel: top-level mxfp4 for the 72 expert planes, 98 affine per-prefix overrides, and 24 mode-less overrides that must keep resolving to affine rather than inheriting mxfp4.
• Synthetic hostile configs (symlink farms in a scratchpad, the checkpoint itself untouched) fail at load with a message naming the four modes: hostile top level with valid overrides (the live gap, since the experts read Quantization::defaults), hostile per-prefix mode with a valid top level, and affine declared over the bias-less expert planes.
• models/minicpm-v-4.6-mxfp4 (block-float through reconcile_quantization_layout) unchanged.
• models/gemma-4-31b-it-nvfp4 (ModelOpt NVFP4, the fix: externally quantized 4-bit Gemma 4 (OptiQ) decodes to degenerate output that is trapped entirely in reasoning_content #467 path) unchanged.
• models/qwen3-30b-a3b-4bit and models/qwen3.5-2b-4bit (affine MoE and affine dense) unchanged.
• cargo fmt --all -- --check
• cargo clippy --release --all-targets --features metal,accelerate -- -D warnings (the release form; make verify-clippy uses the debug profile, which would cold-build MLX here)
• cargo test --release --features metal,accelerate --no-fail-fast

Regression tests drive real load paths and assert on the returned Result without running a forward pass, because an MLX throw would abort the test binary rather than fail it. Each hostile case is paired with a positive control that loads first.

Closes #973