[Bugfix][QSA] Clamp metadata token counts for graph padding

[Leonccaa]

Purpose

Graph-padding requests can make query_start_loc_cpu[-1] exceed num_actual_tokens. QSA's Torch builder then constructs logical positions beyond its output view; the Triton compressed-cache path can read beyond the real slot-mapping input. Clamp the mapped-token count to min(query_end, num_actual_tokens) in both builders.

Adapted from vllm-project/vllm#58040, at 645c156e3163a0a55a3057bd9844fe9a765e0dc0, with upstream author attribution preserved in the commit. This backport retains 1Cat's three-output metadata interface. The source PR targets vLLM; this PR targets 1CatAI. Searches of open 1CatAI PRs for 58040, metadata padding, and QSA found no equivalent clamp. #647 addresses a different grouped-page4 null-block/NaN path. Fork review: Leonccaa/1Cat-vLLM#20.

The regression uses real CommonAttentionMetadata and request mapping. It covers Torch/Triton, one-token decode/four-token verify-shaped inputs, zero/three padding requests, and plain/compressed/circular slot mapping. CUDA cases capture a graph, replay three times, update sequence lengths and replay again, checking exact metadata and output guards. Mapping backing capacity still includes padded offsets, as required by the existing helper.

Test Plan

# In the source checkout and project virtual environment:
python -m pytest tests/models/qwen4_exp/test_qsa_metadata_padding.py -q --tb=short
pre-commit run --files vllm/models/qwen4_exp/common/qsa_cache.py tests/models/qwen4_exp/test_qsa_metadata_padding.py
git diff --check

GPU supplemental validation used four V100 32 GB GPUs and the existing deployment image at b4fef533ec, with this PR's exact qsa_cache.py mounted read-only (SHA256 e1065b0f5e1f2a7015e3200c21739edb98114f7b79e96ab63833b47615b19bf0). It is not a full rebuild of current upstream main. Local harness paths below are validation artifacts, not added repository files:

/opt/venv/bin/python -m pytest /audit/tests/test_qsa_metadata_padding.py /audit/tests/test_qsa_e4m3.py -q --tb=short
/usr/local/cuda/bin/compute-sanitizer --tool memcheck --error-exitcode 99 /opt/venv/bin/python /audit/tools/memcheck_metadata.py --baseline
/usr/local/cuda/bin/compute-sanitizer --tool memcheck --error-exitcode 99 /opt/venv/bin/python /audit/tools/memcheck_metadata.py
bash "$AUDIT_ROOT/tools/run_graph_ab.sh"  # host-side orchestration of the two KV arms

Test Result

• CPU negative control: 6 failed, 6 passed, 12 skipped; all padded Torch cases fail before the fix. Fixed CPU: 12 passed, 12 skipped (CUDA unavailable on the development host).
• Final GPU metadata/E4M3 tests: 31 passed: 24 metadata cases and 7 existing E4M3 kernel cases (21.54 s).
• Compute Sanitizer negative control: three 8-byte global out-of-bounds reads in compressed slot mapping; the summary reports five errors including subsequent launch errors, exit 99. Fixed control: correct metadata, zero errors. Output sentinels alone are not treated as proof of read safety.
• Full-model TP4/MTP3 regression: FP16 graph/eager and calibrated E4M3 graph/eager each completed 9 requests × 64 tokens. E4M3 main/draft scale checks passed 24/24 and 2/2.
• Same-process controls: each KV type completed three rounds of 9 × 64 tokens: patched A1, repeated patched A2, then guarded old builder B. All four workers executed B 826 times each, with zero calls where the clamp would change the mapped-token count. Token parity remains not established; see below. The first FP16 two-round attempt was also non-identical (5/9 exact) and was retained rather than discarded.
• Applicable pre-commit hooks and git diff --check: passed.

Exact token matches across nine requests per round:

KV cache	Patched A1 vs A2	Patched A1 vs old B	Patched A2 vs old B
FP16	7/9	7/9	9/9
Calibrated E4M3	9/9	8/9	8/9

FP16 varies even without switching the builder. The E4M3 mismatch is unresolved (batch size 4, backup-explanation prompt, first difference at output token index 2). No cause is asserted for that mismatch. The successful exit of the supplemental three-round harness means the runs completed and results were recorded; it does not mean numerical parity passed. This PR is ready for review; the validation limits above remain applicable.

Validation limits: graph/eager outputs were token-identical for only 4/9 requests per KV type, so full-model graph/eager token parity is not established. All recorded full-model metadata shapes had query_end <= num_actual_tokens; the failing padding boundary is reproduced by the dedicated metadata/memcheck tests, not by the full-model runs. The baseline model A/B guards against the unsafe boundary and swaps the host metadata builder after initial graph capture; it is not a separately recaptured unpatched full-model run. These results do not attribute historical hangs or output changes to this bug, or make a performance or model-quality claim.

AI assistance: OpenAI Codex adapted the patch, authored regression coverage and ran validation. Human review remains pending; no merge or resident deployment of this patch is requested.