refactor(VT-FP8-SHARED-SEAM): the FP8 W8A8 linear path becomes a seam a second model can reach (#940)

[localai-bot]

Closes #940.

Spec: .agents/specs/vt-fp8-shared-seam.md.
Owning row: MODEL-TEXT-nemotron-h-nemotron-hfor-causal-lm (#517), which is what forces it.

What was wrong

AGENTS.md §"Shared seams": "If a shared seam cannot represent the upstream behavior, extend it or record one exact tracked exception. Never hand-roll a parallel path."

NVFP4 honoured that. FP8 W8A8 did not: Fp8Weight was in a header, but everything that made it usable sat in the anonymous namespace of one .cpp.

Entry point	Was (qwen3_5.cpp @ c7cb59fbb)	Is
ResidentFp8	:1458	models/dense_fp8_gemm.h
DenseCublasLtFp8Enabled	:1478	models/dense_fp8_gemm.h
MatmulFp8CutlassD	:1495 (guard :1497-1498)	models/dense_fp8_gemm.h
MatmulFp8CutlassPreQuantD	:1517 (guard :1519-1520)	models/dense_fp8_gemm.h
policy layer	did not exist	layers/quantization/fp8.h (Fp8W8A8LinearMethod, MakeLinearMethod)

A second model had three options and the policy forbids two. #517 is that second model: 46 FP8 W8A8 mamba projections, 36.6% of decode bytes and 27.6% of GEMM FLOPs, and its in_proj produces the fused zxbcdt the conv and the SSD scan consume, so the block cannot be split and has no device path at all without this.

Correspondence with dense_nvfp4_gemm.h

dense_nvfp4_gemm.h	dense_fp8_gemm.h
preamble: upstream chain, scope, known duplication	same shape, chain cites compressed_tensors_w8a8_fp8.py:60,201-207, modelopt.py:444,531-537, fp8.py:267,446
MarlinW4A16Enabled() lever	DenseCublasLtFp8Enabled() lever (same spelling, same default)
ResidentNvfp4 :294	ResidentFp8
MatmulNvfp4MarlinD :506	MatmulFp8CutlassD
MatmulNvfp4W4A16D :730 dispatcher	MatmulFp8CutlassPreQuantD (the QuantizedActivation overload)
schemes/nvfp4.h:35 Nvfp4W4A16LinearMethod	quantization/fp8.h Fp8W8A8LinearMethod
schemes/nvfp4.h:97 MakeLinearMethod	quantization/fp8.h MakeLinearMethod (overloaded on the weight type)

Two deliberate divergences, both argued in the spec:

1. Path is quantization/fp8.h, not quantization/schemes/fp8.h. The FP8 W8A8 linear path is not a shared seam: residency and GEMM entry points live inside qwen3_5.cpp, so a second model cannot reach them without hand-rolling a parallel path #940 writes "schemes/nvfp4.h" for a file that lives at compressed_tensors/schemes/nvfp4.h, so it is shorthand; inventing a quantization/schemes/ directory mirrors nothing upstream. fp8.py sits directly under quantization/ in vLLM, and layers/quantization/modelopt_mixed_precision.h is the local precedent.
2. The seam is templated on Dev/DBuf. qwen3_5.cpp keeps its own anonymous-namespace copies of those types (the KNOWN DUPLICATION dense_nvfp4_gemm.h:45-50 records). A non-template header could only have been copied into that file, which is the seam-dead-beside-the-path failure The FP8 W8A8 linear path is not a shared seam: residency and GEMM entry points live inside qwen3_5.cpp, so a second model cannot reach them without hand-rolling a parallel path #940 exists to prevent. One definition, two instantiations instead.

The call-site change

qwen3_5.cpp loses 69 lines and gains a using plus two one-line adapters. Its ~14 call sites are unchanged text.

using dense_fp8::DenseCublasLtFp8Enabled;

DBuf MatmulFp8CutlassD(Dev d, const Tensor& x, const Fp8Weight& w, DType out_dtype) {
  return dense_fp8::MatmulFp8CutlassD<DBuf>(d, x, w, out_dtype);
}

DBuf MatmulFp8CutlassPreQuantD(Dev d, const Tensor& a_fp8, const Fp8Weight& w,
                               DType out_dtype) {
  return dense_fp8::MatmulFp8CutlassPreQuantD<DBuf>(d, a_fp8, w, out_dtype);
}

No numerics, tolerance, guard or dispatch condition changed. The CUDA-only VT_CHECK travelled with the code it guards.

Gate: Qwen3.5 byte-identity

Baseline measured in a clean detached worktree at c7cb59fbb; after at a0693813a. Identical counts for every pre-existing suite.

Suite	Before	After
test_qwen3_5_gdn_spec_routing	test cases: 6 | 6 passed, assertions: 52 | 52 passed, SUCCESS!	6 / 52, SUCCESS!
test_ops_fp8_cpu	4 / 56, SUCCESS!	4 / 56, SUCCESS!
test_qwen27_paged_forward	29 / 765, SUCCESS!	29 / 765, SUCCESS!
test_qwen27_dense_forward	9 / 583, SUCCESS!	9 / 583, SUCCESS!
test_linear_method	6 / 76, SUCCESS!	8 / 88, SUCCESS! (two new cases, declared additive)

Full CPU gate at a0693813a: clean Ninja configure + cmake --build build -j 12, exit 0, 0 warnings under -Werror; ctest -j 4 485/485 passed, 0 failed in 828.96 s (2 skipped: test_modelopt_mixed_precision_checkpoint, test_voxtral_e2e, both absent-fixture skips). Disk 91% before, 99% at peak, 91% after teardown.

Mutation table: the seam is LIVE, not dead beside the path

Every row rebuilt from source, compile_exit and error: count reported, binary sha distinct from baseline, case count non-zero. No TEST_CASE name contains a comma.

GPU arm in progress on dgx (GB10 sm_121a, cutlass-fp8: ENABLED); this section is filled before the PR leaves draft.

Found and deliberately NOT fixed

ResidentFp8 (and its siblings ResidentFp8Qkv / ResidentFp8Qkvz) Alloc + Copy the fp8 weight bytes to the device without vllm::load_stats::AddDeviceUpload and without the post-upload AdoptDeviceBytesAsHost. Every other resident-weight helper in the same file does both: ResidentWeight (qwen3_5.cpp:1009,1016 @ c7cb59fbb) and ResidentNvfp4 (:1106,1111,1116,1121), and dense_nvfp4_gemm.h:294-328 carries the comment explaining why the pair is mandatory (ENG-LOAD-DIRECT-UPLOAD, #150). So the 35B fp8 tower's upload is missing from load accounting and its pages are never re-tagged, which is the shape of the GB10 weight-residency ATS penalty. Carried across unchanged: repairing it inside an extraction is exactly the behaviour change a byte-identity gate cannot see. Recorded in the spec under §Found, not fixed; filed separately.

Separately, not a new find: the CUDA-only refusal keys on kMatmulFp8CublasLt while the ops it would run (kQuantFp8Static, kMatmulFp8Cutlass) have CPU reference arms since #468/#842. That is already recorded in vt-fp8-w8a8-cpu-arm.md §Residual gap and pinned at tests/vt/test_ops_fp8_cpu.cpp:445-453. Carried unchanged; the new CPU case re-pins it at the model tier.

Not in scope

Wiring NemotronH to the seam (A2-Q under #517), ResidentFp8Qkv/Qkvz and the merged-QKV(z) path, and any widening of the device predicate.

FOLLOWING_AGENTS_PROTOCOL

Following-Agents-Protocol: true
AI-Assisted: true
Assisted-by: AGENT:claude-opus-5 [claude-code]

[localai-bot]

Superseded by the branch row/VT-FP8-SHARED-SEAM-940, same work, corrected history.

Commit 427029223 on this branch edited include/vllm/ (three wrong upstream/local anchors in comments) without touching docs/USAGE.md, and check-doc-checkpoint.py is PER-COMMIT over the PR range (ci.yml:433), so that commit is red wherever it sits in history. Repairing it needs a rewrite, and this repo does not force-push, so the corrected history went to a new branch instead and this one is closed rather than left dangling.