[II] Define per-cache DCP block-table geometry

[voipmonitor]

Behavior

Each KV-cache specification defines the number of token-position shards it
stores under decode context parallelism and the block-table width required by
its runtime manager. The GPU model runner consumes those interfaces instead of
reimplementing cache-type rules.

Attention caches preserve the configured full, partial, or replicated DCP
layout. Recurrent caches such as MambaSpec report one token-position shard;
tensor parallelism may still partition their feature dimensions.

Technical reason

Recurrent state is indexed by global sequence position but is not partitioned
by token position across DCP ranks. Applying the configured DCP size to its
block-table width underallocates addressable columns. With
max_model_len=1,000,000, recurrent block_size=768, seven speculative
blocks, and DCP16, align mode requires 1,310 columns. A DCP-scaled table cannot
address the first recurrent-state checkpoint boundary after 63,744 tokens.

The cache-spec interface is also the single source of truth for replicated and
partially sharded attention groups supported by Infernal Invocation.

Compatibility

• DCP-sharded attention groups keep their configured geometry.
• dcp_replicated=True groups retain DCP1 token-position geometry.
• dcp_kv_shard_count retains explicit partial-shard geometry.
• DCP1 behavior and physical KV-cache allocation are unchanged.
• The Kimi-K3 TP16/DCP16 profile adds approximately 58.6 KiB of worker
  block-table storage per rank.

Validation

• All repository pre-commit hooks pass for the three changed files, including
  Ruff, formatting, mypy, SPDX, forbidden-import, and configuration checks.
• Five cache-geometry tests pass, covering sharded attention, replicated
  attention, Mamba state, aggregate cache specs, and the 1,310-column
  regression.
• The complete prefix-cache unit suite passes: 93 tests.
• A no-weight 17-group cache reproducer completes 1,000,000 tokens in 1,302
  allocation steps; all non-null physical blocks have one owner and 17 of 499
  pages remain free.
• The source-locked image
  voipmonitor/vllm@sha256:acdfb8460672c730c4df470a81eb86ca83995390e7f74360615dacc1e5ca2fb3
  passes TP16/DCP16 full-model qualification with the official Kimi-K3 MXFP4
  target. Target-only decode is 55.719 tok/s, DSpark target execution is 31.416
  cycles/s, and DFlash target execution is 29.160 cycles/s. The corresponding
  immutable-control differences are +0.05%, -0.005%, and -0.12%.
• Uncached 8,192-, 32,768-, and 65,535-token prefills measure 3,627, 3,695, and
  3,538 tok/s. A 500,224-token DFlash request returns HTTP 200 with all captured
  log probabilities finite.

The complete source lock and machine-readable receipts are recorded in
the Kimi-K3 runtime specification.

Official vLLM relationship

Official vLLM already encodes the recurrent-state invariant through
MambaSpec.max_num_blocks_per_req. The broader official-vLLM implementation
must additionally carry per-group cache topology through allocation,
scheduling, block tables, slot mapping, and DFlash metadata because upstream
does not have Infernal Invocation's shared shard-count helper.

The prepared official-vLLM branch is
fix/dcp-cache-topology-contract-20260821.
It differs from open vLLM PR vllm-project#48392 by fully replicating draft token positions
and running draft attention locally, rather than replicating KV heads while
retaining DCP-sharded positions and DCP attention collectives.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c9bf5081-943b-4e0a-8b82-5ffcd5ddc545

📥 Commits

Reviewing files that changed from the base of the PR and between d6e0bb7 and 6b18a8a.

📒 Files selected for processing (2)

• tests/v1/core/test_kv_cache_utils.py
• vllm/v1/kv_cache_interface.py

Included review availability: Your plan includes up to 1 review per rolling hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The change makes MambaSpec use one DCP token-position shard and adds a regression test for shard count and maximum request blocks at world size 16.

Changes

Mamba DCP sharding

Layer / File(s)	Summary
Mamba shard sizing and regression coverage vllm/v1/kv_cache_interface.py, tests/v1/core/test_kv_cache_utils.py	get_kv_cache_dcp_shard_count returns one token-position shard for MambaSpec. The test checks one shard and 1,310 maximum request blocks for the configured world size and cache settings.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 6b18a

This localized change corrects recurrent cache block-table sizing under DCP and includes targeted regression and end-to-end validation; no actionable merge-blocking risk remains beyond normal checks and review.

Possibly related PRs

• local-inference-lab/vllm#393: Related Mamba KV-cache handling changes in prefill chunk alignment and cache-state integrity.

Suggested reviewers: heheda12345, lukealonso

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: defining per-cache DCP block-table geometry.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/ii-mamba-dcp-replicated-block-tables-20260817

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}