Stacked on #26866.

Extends spec v2 (overlap) EAGLE tree drafting (topk > 1) to page_size > 1, and sizes + guards the req_to_token pool for the per-branch holey draft layout.

Summary

• Lay out each draft branch's region page-aligned ("holey") and duplicate the prefix partial-tail page into every branch so whole-page attention reads stay coherent (duplicate_prefix_tail_to_draft_branches).
• Implement get_alloc_len_per_decode for page_size > 1 + topk > 1 (was NotImplementedError): worst-case footprint num_new_pages_per_topk * page_size * topk.
• Widen the req_to_token row to hold that footprint, plus an always-on invariant that fails fast if a draft over-allocation would outgrow the row.
• Route topk > 1 + page_size > 1 to spec v2 and gate it to backends that implement the two-pass cascade draft-decode.

Bug

At page_size > 1 + topk > 1 the draft reserves a page-aligned per-branch footprint of 2 * get_alloc_len_per_decode (= topk * num_new_pages * page_size), far exceeding the default 4 + num_draft_tokens spec headroom the req_to_token row was sized for. One over-allocation then fails two ways:

• Free side (silent leak): release_kv_cache reads req_to_token[req][start:end]; the slice silently clamps to the row width, so over-allocated KV slots are never freed -> pool memory leak detected when the idle mem check runs.
• Access side (OOB): the holey prefix-tail gather indexes past the row -> a cryptic async CUDA gather assert that corrupts the pool first.

Fix

• _init_pools: widen extra_max_context_len to max(4 + num_draft_tokens, 2 * get_alloc_len_per_decode) for page_size > 1 + topk > 1.
• prepare_for_decode: an always-on, CPU-side invariant asserting the per-request draft over-allocation fits the req_to_token row -- a clear host error instead of a silent leak or device assert.

Repro / A-B

Both gists start a real spec server (EAGLE3 Llama-3.1-8B, fa3). SGLANG_DEBUG_REVERT_PR=26972 reverse-applies the row-widen (registered in pr_fix_toggle.py; the revert hook is moved to run before init_model_worker so init-time fixes can be reverted), demonstrating the bug against the same build:

• KV leak (page512, multi-turn): https://gist.github.com/hnyls2002/a1c9586206696433ddc1fd4845e57318
• draft over-allocation OOB (page256, long prompt): https://gist.github.com/hnyls2002/0ca55aecedcac4d0d3e46275379f3112

With the fix both pass; with SGLANG_DEBUG_REVERT_PR=26972 both deterministically trip the invariant.

Test

• test/registered/spec/eagle/test_spec_eagle_topk_page.py: EAGLE3 topk8 + page64 (spec v2) and Llama-2 topk8 + page4 (spec v1).

Related

Sibling page_size > 1 + topk > 1 fixes in other backends: #27338 (flashinfer cuda-graph kv_indices), #27360 (fa3 expand page_table).

CI States

Latest PR Test (Base): ✅ Run #27060252695
Latest PR Test (Extra): ✅ Run #27060252626