spec(ENG-CUDAGRAPH-BREAK): the capture seam has no break points, and the nine hand-rolled drivers each re-derive one

[localai-bot]

Scopes ENG-CUDAGRAPH-BREAK to READY: one shared vt capture seam that accepts break points, so a forward containing a host-dependent operation is still graphed except at that operation instead of falling out to eager for the whole step. Spec-only. No production code lands here.

The boundary comes from vLLM and the construction comes from SGLang, and the spec keeps those apart. vLLM's v1 default already splits at splitting_ops (vllm/config/compilation.py:60-63,517,1145 @ 555967922), so the boundary is the attention family and this row does not invent one; its mechanism is Dynamo and FX, which we have no way to reach. SGLang gets the same coverage with no compiler, and that is what ports.

Coverage AND correctness, never speed. qwen3.cpp:961-986 already declines its decode graph outright whenever the async device-token mirror is live, on its own measured battery (depth-1, graph ON PASS 78/78; depth-2, graph OFF PASS 82/82; depth-2, graph ON FAIL, slots 1-3 degenerate), because the fix its own comment names lives in one sibling driver as StepDevInputs and nowhere else. A shipped model has already lost its decode graph to this duplication. No throughput gate is declared and the prefill refutation stands unchanged: GB10 measured 3.8% host idle between launches with GPU-busy above 96%, and the 27B prefill gap at 92.5% non-GEMM glue.

Review repair

A fresh reviewer returned FAIL on 35206c295. Ten findings, all repaired in e714dc25e and a647abbe9. The two that were load-bearing:

The upstream test suite the spec said did not exist is 305 lines. ## Tests to port asserted that "SGLang's BCG carries no unit test at the pinned revision that exercises the segment container in isolation". test/registered/cuda_graph/breakable/test_breakable_cuda_graph.py @ f63458b5be carries eleven unit cases across TestBreakableCUDAGraphBasic (:30), TestCopyOutput (:172) and TestBreakGraphHelper (:230). A ## Tests to port section that asserts there is nothing to port deletes the obligation the section exists for. Every case is now mapped to the local test that owes it, with the one harness adaptation stated once. test_gsm8k_accuracy is deliberately excluded, with the reason: it is a distributional accuracy floor on a prefill path, and G1's bit-exactness against the model's own eager forward is strictly stronger.

The primitive dropped the output writeback. ## Port map §3 said eager_on_graph "appends fn to break_fns". It does not. It appends a replay_fn closure (:231-235) that calls the captured inner function and writes the result back into the capture-time destination through _copy_output (:172-201), with _weak_ref_if_tensor (:156-169) keeping that destination alive. On replay N the eager operation returns a fresh allocation whose address is not the one the next segment baked, so a container replaying the raw fn leaves segment i+1 reading capture-time data while the break function writes elsewhere. That is wrong numerics rather than a fault — the same detection class D1 records compute-sanitizer cannot see. Now stated at the GraphBreak declaration, pinned by the ported TestCopyOutput cases, recorded as D9.

The rest:

• Auxiliary-stream fork was absent everywhere. Upstream auto-joins side streams before closing a segment (:353-361) and maintains the whole wait_stream hook (:101-153, installed :310, removed :332) for that alone. It is live here: SupportsAuxStream() is true on CUDA (cuda_backend.cu:200) and both drivers this row migrates in W4 and W5 fork on it, at qwen3_5.cpp:6254 and laguna.cpp:2572. Stated on GraphCaptureScope, gated by a new test, recorded as D10.
• Four enumerations and one grep count re-derived with printed instruments. Six drivers read VLLM_CPP_CUDAGRAPH, not five; the Qwen3.5 dense getenv is :9969, not :9974; Laguna's capture switch is VT_LAGUNA_DECODE_GRAPH at :1684, not the KV cluster at :104,116,140, none of which is a capture switch; PadToCaptureSize has six call sites and the diagnostics pair six definitions. The pattern was that the Qwen3.5 dense driver was dropped from three of four enumerations though W4 migrates it. StepDevInputs is on 41 lines and occurs 47 times, not the 33 recorded, which is neither number; the four zeros reproduce under both instruments and the conclusion survives.
• D6 asserted what W0 said was not our measurement. It claimed the CUDA mid-forward re-begin "holds" and is "cheap" while ## Work breakdown W0 called the same fact strong evidence but not ours. D6 now defers to W1's exit criterion in W0's own words, drops the unmeasured cost claim, and names the A/B that would settle it.
• Anchor drift fixed (all landed inside the right construct, none exact); the upstream path spelled once in full instead of abbreviated in a table header; Risks/decisions reordered to run D1 through D10.

Rides with it: #1179

The hand-rolled driver count recorded in 9bc4d7f44 is eight and is actually nine. The ninth is the DFlash draft graph (qwen3_dflash.cpp:771,870,1038,1091,1095,1106), file-local with no header declaration, which is why an enumeration built from the model headers could not see it. #1179 named four locations; the sweep across all of .agents/ found a fifth (sglang-matrix.md:149) and three more inside eng-cudagraph-break.md itself. All eight corrected.

.agents/issue-index.md:354 (#1162) and :355 (#1163) also still say eight and are deliberately not edited — that file is append-only and carries merge=union, so an edited row is duplicated rather than merged. The appended #1179 row is the correction and names the DEDUP row's "times eight drivers" sizing explicitly.

The reframing is the substantive half, and it does not weaken the framing rule: the row still makes no throughput claim.

Verification

./scripts/agent-preflight.sh → All gates green. (79 checks ok, 0 red, exit 0). check-agent-record OK, check-commit-trailers OK, check-commit-style OK against origin/main 84b9660c0. Box load 0.86, so test_cpu_x86_llamacpp_floor is a real green and not #618's load-dependent flake.

Negative mutation, both restored byte-for-byte and the branch SHA unchanged throughout. The append-only gate reads merge_base..HEAD and never the working tree, so the mutation was built as a detached scratch commit rather than an unstaged edit — an unstaged mutation reads as a passing test against this checker. Editing an existing index row: baseline rc=0 → mutation rc=1, FAIL: .agents/issue-index.md is append-only, and this range removes or edits lines. Breaking the matrix row's spec link: check-agent-record rc=0 → rc=1 on five structured-section errors.

Not verified: every anchor in this spec is a static read of the pinned trees; nothing here was executed on a GPU, and W1's exit criterion — that CUDA permits cudaStreamEndCapture followed by cudaStreamBeginCapture mid-forward on our stream configuration — remains unmeasured by design and needs an rc lease.

Closes #1179.
Refs #1163, #1020, #1162, #1164.

FOLLOWING_AGENTS_PROTOCOL

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