[jianc99]

Supersedes #536 (thanks @wmTJc9IK0Q); closes #527.

Where #536 served the header's count when the family listed it ({512,
256} for Qwen3.8-Flash-Next), this serves every count up to the family's
that the MoE kernels route and the router's 8-column tiles hold, which
the installer derives from the header into the config, so a start reads
one layout.

A family's layout fixed its routed experts, and every start held a
GGUF's header to that count (gguf::requireMetadata), so a release that
keeps fewer experts than its family was refused by the installer's model
check and at every start. ISTA-DASLab's Coder release of
Qwen3.8-Flash-Next (Qwen3.8-Flash-Next-GSQ-RCO-Coder-GGUF) keeps 256 of
its 512 routed experts, 10 still taken per token, and stopped at "GGUF
metadata does not match the target: expert_count 256 (expected 512)"
(#527). #536 first served it by a list of the counts each family states.

The routing, grouping and expert kernels, the expert store, the planner
and the memory plan already take the count at run time. The installer
now derives it into a MoE GGUF's config.json, as it derives every other
size the descriptor reads (gguf.model_config: num_experts, the header's
expert_count), and describeSourceModel puts it in the family's layout
before the descriptor is made (ggufRoutedExperts, from the text config
and the family's layout). Sizing, planning and loading read that one
layout, and the model check takes the same path. A count is served when
it is:

• at most the family's, as a pruned release holds no more experts than
  its family;
• a shape the MoE kernels route (ops::MoeShape::valid), from the experts
  each token takes to SPLASH_MOE_WIDE_EXPERT_SLOTS;
• a multiple of 8: the router is a float projection, and addGgufFloat
  refuses one whose columns do not fill whole 8-column tiles.

Qwen3.8-Flash-Next so serves 16 to 512 experts in steps of 8, and
Qwen3.6-35B-A3B and Qwen3.5-122B-A10B 8 to 256. A refusal names the
family and that range ("text config num_experts: GGUF 264,
Qwen3.6-35B-A3B a multiple of 8 from 8 to 256"). Every other dimension
is the family's, and every start's planner still holds the header's
expert_count and each router and expert tensor to the count, so a config
that disagrees with its GGUF is refused. A config without the count,
which an earlier release derived, states the family's; an MLX target's
count must still be the family's. No runtime header, kernel or op
changes, and DEVELOPMENT.md states the rule under GGUF targets.

The one side effect: install/gguf.py's hash keys the derived metadata,
so each installed GGUF derives it again locally at its first start after
the upgrade, which prints "the GGUF metadata adapter changed". Nothing
is downloaded, and the digests of unchanged files come from their
records. If the derivation fails, the start keeps the installed
assembly, whose config without the count states the family's.

Tests: model-configuration's testPrunedExperts runs the start path
(inspectModelRoot): a Qwen3.8-Flash-Next GGUF config of 256 experts is
the family's layout but for its experts, with the family's draft; 16 and
512 are served, 8, 12 and 520 are refused with "a multiple of 8 from 16
to 512" and true as not a number, and a config without the count states
512; a Qwen3.6-35B-A3B GGUF serves 8 and 128 and refuses 264 ("from 8 to
256"), and an MLX one of 128 is refused. testConfigurationCheck finds a
config and metadata pruned to 256 experts, as the Coder's are, to be
Qwen3.8-Flash-Next with and without the draft, and refuses that config
with the unpruned header (expert_count 512 (expected 256)); the test's
MoE GGUF configs, the 35B's and the 122B's, state the 256 experts the
installer now derives. test_gguf_metadata derives the config and the
metadata from one header in each case: expert_count 128 is
Qwen3.6-35B-A3B, 264 is refused, and the Flash-Next fixture config is
the one derived from its fixture header.

At the top of this stack, on the 64 GB M5 Pro, make all and
check-native-build build without a warning; check-source,
test-engine-cpu (model configuration with its pruned experts) and
check-python (1321 tests OK, 27 skipped; ruff clean) pass; and test-real
passes on the Qwen3.6-35B-A3B UD-Q4_K_M and Ornith-1.5-122B UD-Q2_K_XL
GGUFs. On the M5 Max (36 GB), ISTA-DASLab's Qwen3.8-Flash-Next Q2_0
passes test-http-real. Earlier, on the M5 Max with #539's previous head
and the same changes, make check and test-sanitizers passed, and so did
test-http-real on the Coder IQ1_M
(ISTA-DASLab/Qwen3.8-Flash-Next-GSQ-RCO-Coder-GGUF:IQ1_M), also with
--verify-rows all.

Before that, with the change on 1.4.0 (1482f6b), on the M5 Max (36 GB),
prepare, run offline over the Coder IQ1_M and ISTA Q2_0 installations
made by 1.4.0, printed "the GGUF metadata adapter changed" for each and
exited 0. Of each installation only config.json, its copy under
tokenizer/ and model.json's records of them changed, the config gaining
num_experts 256 and 512 respectively, and each then started to Ready.

Stacked on #560; review the commit after it.

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}