feat(speculative): Muse Glimmer DFlash assistant drafter on the round loop

[inureyes]

Adds the Muse Glimmer assistant drafter (meta-models/Muse-Glimmer-30B-assistant, model_type: muse_glimmer_assistant) to the existing DFlash round loop, with the Muse target adapter and the server dispatch, so mlxcel-server -m <Muse-Glimmer-30B> --model-draft <assistant> serves text-only requests speculatively at B = 1.

What changed

• mlxcel-core drafter::dflash::muse: config (flat; num_target_layers and vocab_size are Options checked against the bound target, because the published config.json carries neither), five sliding-attention layers with per-head q/k norms under a bidirectional sliding mask over absolute positions (|q - k| <= 2048), encoder.fc plus encoder.output_norm_enc, and a Drafter adapter that binds the target's raw embedding table and untied lm_head. The context cache is a temporal window rather than a RotatingKVCache: a wrapped ring returns physical slot order and the mask needs absolute key positions. muse_glimmer_assistant resolves to DrafterKind::Dflash; its markers join the standalone-model rejection.
• Muse target (src/models/muse_glimmer_speculative.rs): residual-stream capture before the final norm, trim rollback over the mixed caches, sliding caches armed with clamp(block * 8, 32, 128) rows of speculative buffer floored at the block size, the block-versus-chain exactness probe as the gate. MuseGlimmerTextWrapper and the VLM wrapper hand out embed_tokens_module (raw table, not the embed_norm lookup) and lm_head_module (no softcap). prefill_forward_with_capture_layers keeps the trait default on purpose: a Muse verify output carries no rollback state (the trim reads cache offsets), so there is nothing prompt-sized to skip.
• Round loop: DFlashGenerator reads Drafter::configured_block_size / prefer_requested_block_size and, for a drafter that declares a depth below the requested width without insisting on it, runs the MTP loop's BlockThroughputController between the two. The Muse assistant starts at 4 rows under the checkpoint's 16-row ceiling (measurement below). Qwen 3.5 DFlash (no depth) and DSpark (prefers the requested width) keep a fixed width; pinned by dflash_round_loop_starts_at_the_configured_depth.
• Server (the PR feat(speculative): LFM2 / LFM2.5 DSpark drafter on the DFlash loop #1751 review item): DFlashTargetModel::supports_batched() replaces the hardcoded LFM2 arm in the batched variant gate, required_drafter_family() replaces the DSpark boolean and refuses a mismatched pairing by name for both LFM2 and Muse, and the module doc no longer describes per-family policy living outside the trait. run_dflash_burst's three arms and model_variant_label cover MuseGlimmerVLM. The Muse startup guard admits exactly the assistant drafter (--draft-kind dflash or unset), still rejecting adapters, KV modes, TP/PP and draft flags without a drafter.
• Docs: docs/supported-models.md (DFlash row for Muse, family paragraph, the "not a speculative target" sentence replaced), docs/speculative-acceptance.md, and the README speculative bullet.

Pre-merge review round (commit 796604f1)

Three findings were fixed in this PR; the rest are listed below as reported and not fixed.

• HIGH, fixed. The exactness gate probed a width the loop does not run at. The verify width became adaptive in this change, so a Muse run warms up at the drafter's declared depth of four rows and widens to the requested ceiling only when a measurement window pays for it, while the burst gate called exactness_allows(block_size) with the ceiling alone. The forward width selects which quantized-matmul kernel MLX dispatches, so a pass at the ceiling is not evidence about the depth: docs/benchmarks.md records the same comparison reading 20.6 percent disagreement at width 8 and 0.0 percent at width 32. probed_verify_widths now names the widths a run can settle on and dflash_exactness_allows_every_width requires all of them. On this host the probe declines at width 4 as well (162404 of 404096 logit bytes differ, against 187123 at width 16), so the gate had been reporting a verdict for a width the loop would have left after the warm-up. Pinned by probed_widths_cover_the_warm_up_depth_and_the_ceiling.
• HIGH, fixed. The speculative buffer could be narrower than the block it buffers. speculative_buffer_size was the Gemma 4 rule verbatim, clamp(block * 8, 32, 128), and the buffer is the slack past max_size that lets a verify block be appended across the ring boundary and rewound. --draft-block-size is not bounded above anywhere on the way in, so at 129 rows and above the cap handed the block less slack than it needed: the append overwrites still-visible window rows, RotatingKVCache::trim rewinds the offsets without restoring them, and the sequence continues from a window with holes in it with no error anywhere. The rule now floors at the block size, a no-op at every width a real run reaches. Pinned by speculative_buffer_never_falls_below_the_block_it_buffers. The rollback also names a short rewind through tracing::error! rather than only a debug_assert, and a verify that captured no residual stream for a drafter slot now says so instead of handing over a zero slab that reads as a residual stream.
• MEDIUM, fixed. Config dimensions were unbounded and the encoder projected rows it was about to discard. MuseAssistantConfig::validate now bounds every dimension it hands MLX as an i32, so a malformed config.json naming one past the wrap point fails as a load message rather than reaching MLX as a negative extent, which crosses the cxx bridge as an abort (config_refuses_dimensions_that_would_wrap_an_i32). And the drafter's forward drops the rows past the sliding window before the encoder runs rather than after: encoder.fc and output_norm_enc are both per-row so the context is unchanged, but at -c 16384 the incoming residual slab is 1.1 GB in f16 and seven eighths of it was being cast and projected only to be sliced away.

Reported and not fixed:

• MEDIUM. --draft-block-size has no upper bound. resolve_draft_block_size returns an override verbatim ("no further validation here; concrete generators enforce their own minimums"), which is family-wide and predates this change. The buffer floor above removes the silent-corruption consequence for Muse, but an absurd width still allocates an absurd verify block. A shared clamp belongs in resolve_draft_block_size or the server startup validation and would touch every DFlash and MTP family.
• MEDIUM. The burst's decline line names the requested ceiling (block_size=16) while the probe verdict immediately above it names the width that actually failed (block_size=4). The burst message is shared by all DFlash families and it points the reader at the verdict line, so it is left alone rather than made family-specific.
• MEDIUM. MuseAssistantContextCache::append rebuilds the whole window every round (concatenate, slice, contiguous, then two ffi::copy), so a steady-state round copies roughly 2 x 2048 x 8 x 128 x 2 bytes per drafter layer. A ring with a rotate-on-read, or RotatingKVCache taught to report absolute key positions, would drop it. It is a fraction of one target verify forward and does not move the measurements below.
• LOW. MuseAssistantDrafter::bind does not re-run validate_target_compat the way Glm4MoeLiteMtpDrafter::bind does. Every current caller (run_dflash_on_target, the batched arm, speculative_bench, the scheduler hook) validates first, and putting it in bind would repeat a full-vocabulary probe matmul on every burst.
• LOW. MuseAssistantModel::forward guards its cache-count invariant with debug_assert_eq! and zip, which truncates silently in release. The only constructor of that vector is make_caches.
• LOW. The mtp_exactness_gate probe key is (block_size, hidden_size, num_hidden_layers), which cannot tell two Muse checkpoints of the same shape apart within one process. Pre-existing and shared with the MTP and DSpark arms.

Real-checkpoint validation (M5 Max, GPU generation 17; models/muse-glimmer-30b-4bit with models/muse-glimmer-30b-assistant-bf16, port 19343)

Re-run at 796604f1 against a mlxcel-server rebuilt after the rebase onto e3ca8afc and after the review fixes; no source file is newer than the binary. Driver: validate_muse.py starts target/release/mlxcel-server -m models/muse-glimmer-30b-4bit --port 19343 -c 16384 --parallel 1 [--model-draft models/muse-glimmer-30b-assistant-bf16], sends POST /v1/chat/completions with temperature: 0, max_tokens: 256, logprobs: true, and compares logprobs.content[].token between arms. Three text prompts: a 66-token tides prompt, a 1968-token log prompt whose 256-token answer crosses the 2048-token sliding window during decode, and a 2660-token log prompt whose caches wrap during the prefill; plus one image_url request.

1. Shipped default (no env override): the probe declines on this host at the warm-up width (MTP declined: verify block position 0 differs from the single-token chain in 162404 of 404096 logit bytes. Disabling qmv_wide did not make it exact either. block_size=4), the burst logs DFlash speculative dispatch declined for seq ...: the block-versus-chain exactness probe did not pass at block_size=16 once per request and serves classically. All three prompts: IDENTICAL, 256 of 256 tokens against the same server without --model-draft. This is the documented generation-15-and-newer condition, the same as LFM2 DSpark on this host.
2. MLXCEL_MTP_ALLOW_INEXACT=1: cross-window-decode IDENTICAL (256 tokens, 47 rounds, 209 of 213 proposals accepted, mean accepted 4.45, 60.5 tok/s decode against 22.5 tok/s classic end to end); wrapped-in-prefill IDENTICAL (256 tokens, 47 rounds, 209 of 214 accepted, mean 4.45, 60.6 tok/s against 20.1); tides DIVERGES at token 59 (Earth's rotation against centrifugal force, 109 rounds, 146 of 375 accepted, mean accepted 1.34, 38.4 tok/s decode against 31.6 classic end to end). The divergence is the byte-identity the probe declined, observed after overriding it, which is why the override is not the default.
3. Image request under --model-draft: one WARN ... DFlash speculative dispatch declined for seq seq-4: multimodal VLM request detected ... line, served classically, HTTP 200.
4. timings on every speculative response carry draft_kind: dflash, draft_rounds, draft_n, draft_n_accepted; mean accepted length is above 1 on every prompt (1.34 to 4.45) and every speculative arm decodes faster than the classic arm of the same prompt.
5. Verify-width measurement that set the 4-row start (an earlier sweep on the same pairing, all under the override, three natural prompts: tides, a code request, a history question): fixed 16 rows 13.0 / 18.1 / 12.4 tok/s (1.87 / 3.40 / 1.80 accepted per round) against 18.1 tok/s classic; 8 rows 24.9 / 30.5 / 21.7; 4 rows 33.6 / 41.3 / 31.6; 2 rows 30.0 / 33.1 / 31.7 (first proposal accepted 74 to 82 percent of rounds). The 2660-token log prompt accepts 14 of 15 at 16 rows, which is what the comparator widens for; on the natural prompts its 16-row challenge windows measured 0.012 to 0.024 tokens per ms against 0.030 to 0.037 at 4 rows and were not adopted. Two alternatives were measured and rejected: capturing the residual stream one layer earlier (HF hidden_states[i] indexing) changed nothing (1.83 / 3.47 / 1.50), and feeding the drafter the embed_norm-wrapped embedding halved acceptance (1.28 / 1.35 / 0.90).

Not in this PR

• Batched (B > 1) Muse windows decline through supports_batched(); multimodal requests decline; draft_window_size is accepted and unused (the issue's out-of-scope list).
• No initial_block_size on DFlashGenerator::new and no dflash_round_loop_initial_block_size_four test: the drafter-declared depth plus the throughput comparator covers the first-round narrowing the issue asked for, and is what the measurement supports.
• The registry drafters entry for LFM2 was already absent before this change and is left as is.

Checks

cargo fmt --all -- --check; cargo clippy --lib --tests and cargo clippy -p mlxcel-core --lib --tests with -D warnings, both under --features metal,accelerate. Tests under --profile test-fast --features metal,accelerate: -p mlxcel-core drafter::dflash (86 passed) and the root crate filtered on muse_glimmer (109), models::muse_glimmer (21), server::batch::speculative_burst (67), server::startup (80), models::detection (63), cli::speculative_args (22), server::batch::dflash_target (4). The --workspace gate was not run locally because the machine is shared; the narrow scopes plus CI cover it.

Closes #1343