[Spec] Share the grammar mask build and verify-tree staging across spec workers

[hnyls2002]

Summary

• Add spec_utils.build_grammar_vocab_mask() — bitmask build, non_blocking upload, and clearing the stale extend-stage mask, which EAGLE and NGRAM each spelled out separately
• Add spec_utils.StagedGrammarTree — the three verify-tree tensors copied D2H under one event, replacing the hand-rolled _async_d2h x3 + event + synchronize() in the EAGLE verify path
• No behavior change

Background

• Grammar-constrained spec verify needs the draft tree on the host, then builds one bitmask row per verify position and uploads it before sampling
• Each worker reimplements the tail (generate_token_bitmask -> .to(device, non_blocking=True) -> clear sampling_info.vocab_mask), and the copy discipline that keeps it off the critical path is easy to get wrong: the copies must be staged before the target verify launch and resolved after it, and the upload must be non_blocking or the pinned bitmask silently degrades to a blocking copy
• Two more workers are adding grammar support ([DFLASH] Support grammar-constrained decoding in speculative verify #30096, [DSPARK] Grammar-constrained decoding, incl. tool_choice=auto #31753); with these helpers they only need to supply their own tree

Notes for reviewers

• StagedGrammarTree is deliberately narrow — it copies on the current stream and relies on record_stream rather than cloning, because the tree copies must stay ordered behind the draft kernels and ahead of the verify launch. The general side-stream variant is kv_canarys FutureTensors, whose clone-per-tensor and dedicated stream are wrong for a per-step verify path
• NGRAM does not stage anything — its tree is derived on the host ([Spec] Derive NGRAM grammar tree links on the host instead of reading back retrive_next_token #32380) — so it calls the mask helper directly, which is what makes the split useful
• The device tree links stay: eagle_sample and the mamba / gdn / kda / hybrid-linear backends read them

Accuracy Tests

• NGRAM + JSON-schema decode: occupancy 92.17% / 725.1 tok/s / accept length 7.97, matching the 92.21% / 725.7 / 7.97 measured before the refactor
• NGRAM constrained smoke on the final build: JSON schema yields { "name": "Paris", "population": 2148000 }, a regex constraint yields an exactly-matching string, and unconstrained decode is unaffected

---

CI States

Latest PR Test (Base): ❌ Run #30153858856
Latest PR Test (Extra): ❌ Run #30153858796

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[hnyls2002]

/rerun-test test_spec_ngram.py test_eagle_constrained_decoding.py test_spec_standalone.py

[github-actions]

Results for /rerun-test test_spec_ngram.py test_eagle_constrained_decoding.py test_spec_standalone.py:

🚀 1-gpu-h100 (3 tests): ✅ View workflow run

cd test/ && python3 registered/spec/test_spec_ngram.py
cd test/ && python3 registered/spec/eagle/test_eagle_constrained_decoding.py
cd test/ && python3 registered/spec/test_spec_standalone.py

[hnyls2002]

/rerun-test test_spec_ngram.py test_eagle_constrained_decoding.py test_spec_standalone.py

[github-actions]

Results for /rerun-test test_spec_ngram.py test_eagle_constrained_decoding.py test_spec_standalone.py:

🚀 1-gpu-h100 (3 tests): ✅ View workflow run

cd test/ && python3 registered/spec/test_spec_ngram.py
cd test/ && python3 registered/spec/eagle/test_eagle_constrained_decoding.py
cd test/ && python3 registered/spec/test_spec_standalone.py

[hnyls2002]

/rerun-test test_spec_ngram.py test_eagle_constrained_decoding.py test_spec_standalone.py

[github-actions]

Results for /rerun-test test_spec_ngram.py test_eagle_constrained_decoding.py test_spec_standalone.py:

🚀 1-gpu-h100 (3 tests): ✅ View workflow run

cd test/ && python3 registered/spec/test_spec_ngram.py
cd test/ && python3 registered/spec/eagle/test_eagle_constrained_decoding.py
cd test/ && python3 registered/spec/test_spec_standalone.py

[hnyls2002]

/rerun-test test_spec_eagle.py test_spec_eagle_topk.py test_frozen_kv_mtp.py

[github-actions]

Results for /rerun-test test_spec_eagle.py test_spec_eagle_topk.py test_frozen_kv_mtp.py:

🚀 1-gpu-5090 (2 tests): ❌ View workflow run

cd test/ && python3 registered/spec/eagle/test_spec_eagle.py
cd test/ && python3 registered/spec/eagle/test_spec_eagle_topk.py

🚀 1-gpu-h100 (1 test): ✅ View workflow run

cd test/ && python3 registered/spec/test_frozen_kv_mtp.py