[Bugfix][Spec Decode][V1] Guard stale async spec prev rows

[paulbrav]

Purpose

Fix an async speculative decoding batch-change failure mode where stale previous-batch row indices can outlive the tensors they index.

In async scheduling, prev_positions maps current request rows to rows from the previous worker batch. The existing code handled -1 for new requests, but it did not guard positive stale indices when the previous sampled-token/count tensors are shorter than the old batch mapping. That can misattribute sampled counts or index out of bounds during input staging / token-count correction.

This PR makes those paths treat out-of-range previous rows the same way as new or non-participating rows.

Summary

• Bounds-check prev_positions against valid_sampled_token_count before gathering accepted-token counts in update_num_computed_tokens_for_batch_change.
• Handle the empty valid-count tensor case explicitly.
• Bounds-check prev_positions against prev_sampled_token_ids in GPUModelRunner._prepare_input_ids.
• Add focused regression tests for stale positive previous positions and the empty valid-count edge case.

Why this is a draft

The original failure was observed in a DGX Spark deployment running DeepSeek V4 Flash DSpark, while this PR currently contributes focused CPU-runnable regression tests for the worker/spec-decode bookkeeping paths. I am opening this as a draft to get early maintainer feedback on whether this should remain a separate worker-side guard or be folded into adjacent async-spec scheduling work before marking it ready for review.

Scope and non-duplicate framing

This is narrower than #40768. That PR addresses -1 placeholder materialization at the scheduler boundary. This PR addresses stale positive previous-row indices inside V1 worker/spec-decode bookkeeping after async batch changes.

This is also distinct from #41481, which warms spec-decode helper kernels and touches update_num_computed_tokens_for_batch_change for startup latency, not for stale-row correctness.

An adversarial placement review considered moving the guard into _compute_prev_positions, but the consumers have different validity bounds: input staging is bounded by prev_sampled_token_ids, while token-count correction is bounded by valid_sampled_token_count. Guarding at each consumer keeps the invariant local to the tensor being indexed.

Files changed

• vllm/v1/spec_decode/utils.py

  • Guard previous-row gathers with 0 <= prev_position < valid_count_len.
  • Avoid indexing empty valid_sampled_token_count.

• vllm/v1/worker/gpu_model_runner.py

  • Guard deferred correction lookup by sampled-count length.
  • Guard async input staging lookup by prev_sampled_token_ids length.

• tests/v1/spec_decode/test_async_batch_change.py

  • Regression tests for stale positive prev_positions and empty valid counts.

• tests/v1/worker/test_gpu_model_runner.py

  • Regression tests for bounded sampled-count lookup and async input staging.

Test Plan

PYTHONPATH=. VLLM_TARGET_DEVICE=cpu .venv/bin/python -m pytest \
  tests/v1/spec_decode/test_async_batch_change.py \
  tests/v1/worker/test_gpu_model_runner.py \
  -k 'async_batch_change or valid_sampled_count_for_prev_index or prepare_input_ids_skips_stale_positive_prev_position' -q

uvx ruff format --check \
  vllm/v1/spec_decode/utils.py \
  vllm/v1/worker/gpu_model_runner.py \
  tests/v1/spec_decode/test_async_batch_change.py \
  tests/v1/worker/test_gpu_model_runner.py

Test Result

4 passed, 35 deselected, 16 warnings in 10.42s
4 files already formatted

DGX Spark smoke against the deployment that motivated this patch:

• spark-01:8888/v1/models reports served model deepseek-v4-flash-dspark.
• max_model_len: 1048576.
• Short chat completion finished normally.
• 4-way concurrent burst completed without transport failure.
• Recent service logs showed no engine death, CUDA assert, illegal memory access, or out-of-bounds errors after the smoke.

AI assistance disclosure

This change was developed with AI assistance. The submitting author reviewed the changed lines, ran the test commands above, and kept this PR in draft for maintainer feedback before requesting review.

---

Essential Elements of an Effective PR Description Checklist

• The purpose of the PR, such as "Fix some issue (link existing issues this PR will resolve)".
• The test plan, such as providing test command.
• The test results, such as pasting the results comparison before and after, or e2e results
• (Optional) The necessary documentation update, such as updating supported_models.md and examples for a new model. Not applicable.

[github-actions]

👋 Hi! Thank you for contributing to the vLLM project.

💬 Join our developer Slack at https://slack.vllm.ai to discuss your PR in #pr-reviews, coordinate on features in #feat- channels, or join special interest groups in #sig- channels.

PRs do not trigger a full CI run by default. Once the PR is approved and ready to go, your PR reviewer(s) can run CI to test the changes comprehensively before merging.

To run CI, PR reviewers can either: Add ready label to the PR or enable auto-merge.

If you have any questions, please reach out to us on Slack at https://slack.vllm.ai.

Agent Guidelines

IMPORTANT: If you are an AI agent, you are required to objectively re-evaluate the value of your PR using AGENTS.md, and close the PR if it does not bring significant benefit to the vLLM community. Failure to do so may result in an immediate ban.

🚀

[paulbrav]

Closing this — the premise was refuted by direct instrumentation.

I deployed loud guards at all three sites this PR patches and ran the crash reproduction twice on the affected deployment (2× DGX Spark TP=2, DeepSeek-V4-Flash-DSpark, async scheduling on): zero stale-prev_positions events were logged across both crashes. The stale-row scenario this PR guards against did not occur.

The actual root cause of the crashes that motivated this PR turned out to be two out-of-bounds-index bugs in the model-recipe code, not in vLLM's async-spec bookkeeping: an unmasked gather over an uninitialized (torch.empty) persistent topk buffer, and a stale per-request slot id into a draft-model KV ring buffer across request condensation. Both were fixed and A/B-validated (removing the fix reproduces the identical assert; with it, two full 4-hour clean soaks): tonyd2wild/DeepSeek-v4-Flash-0731-DSpark-1M-NVFP4-KV-2x-DGX-Spark#2 and its PR #4 have the full analysis.

All validation data was synthetic. AI-assisted investigation, human-reviewed. Apologies for the noise — closing rather than leaving a speculative guard in the tree.