Module spec 

Qwen3.5 MTP (NextN) greedy speculative decode (research/mtp/MTP-PLAN.md §A/§B/§C/§D).

Greedy spec decode is MATHEMATICALLY EXACT: the accepted+bonus token stream is token-for-token identical to plain greedy generate. This module provides:

• mtp_head_forward (§A, T=1): one NextN draft-token forward.
• decode_step_t (§D.3, T=K+1): batched target verify forward, all-column logits.
• generate_spec (§B): the draft/verify/accept/rollback orchestrator. Cache snapshot/rollback lives in cache.rs (§D.4). The MTP head uses its OWN scratch KV (§D.6), PERSISTENT over the committed sequence (see MtpScratch).

Structs

DsparkAnchorRecord

One compact, anchor-bounded DSpark supervision record. tokens[0] is the anchor at p and hidden is its predecessor carrier h[p-1], matching the live NextN/DSpark pairing. Target rows p..p+gamma-1 score tokens p+1..p+gamma. They are the full-target softmax’s top-k entries; target_tail_probs[j] is the probability mass outside those rows. All flattened target arrays are [gamma, top_k] in row-major order.

OptiForkGateStats

OptiForkStateIdentity

SpecSampling

Scratch KV for the MTP block (one full-attn layer).

SpecSession

SpecTelemetry

Always-on per-draft-position acceptance telemetry (lane/accept-telemetry, 2026-08-05 — the llama.cpp #26389 / vLLM spec-decode counter schema, upstream-sweeps 2026-08-05). Lives on the SpecSession and accumulates across bursts; the serve worker diffs a stashed copy per burst for its per-model /metrics aggregation and per-request usage. Same normalization as the [spec-stats] line: p-min-discarded chain tokens are counted in NEITHER drafted nor accepted.

Enums

OptiForkGateMode

Explicit OPTIPIPE diagnostic control. Forced modes are set only by optipipe-gate; the increment-2 controller can also be armed by the server’s fresh-process research door.

Constants

SPEC_TELEM_POS

Tracked draft positions for SpecTelemetry (serve K defaults to 3; the run-spec gate sweeps K=1..8, and MEMRA_SPEC_CAPMAX defaults to 7 — 8 covers every tuned config).

Traits

SpecConstraint

GRAMMAR HOOK for constrained spec decode (lane/constrained-full, 2026-08-03). The engine stays llguidance-agnostic: the server adapts its per-session grammar state behind this trait. CONTRACT (the verify-side truncation rule — token-identical to constrained plain greedy decode): the exactness walk runs UNMASKED first; the hook then (a) truncates acceptance at the first grammar-illegal accepted token, and (b) when the truncation fired or the bonus is illegal, the engine recomputes that slot as the MASKED argmax of the target’s own verify column (an unmasked argmax that is grammar-legal IS the masked argmax — masking only removes tokens — so the common case pays nothing). consume advances the state with each EMITTED token in order; EOS handling is the implementor’s job (skip).

Functions

optipipe_gate_stats

reset_optipipe_gate_stats

set_optipipe_controller_threshold

Arm the increment-2 diagnostic controller. The threshold applies to the uncalibrated two-token draft-probability product. Serving can call this only through its explicit fresh-process research door; the absent-door default remains byte-for-byte disabled.

set_optipipe_gate_mode

Arm or disarm the forced harness. Serving uses only set_optipipe_controller_threshold.