From 3c8ce912bc9a606219ab746585489cb07e54be67 Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Sun, 16 Aug 2026 11:25:29 +0000 Subject: [PATCH] fix(records): the #995 row landed twice, and neither copy was well-formed (#1022) Merging #997 left `main` RED on `check-agent-record.py` for every branch: ERROR: .agents/issue-index.md: issue #995 listed twice. Under `merge=union` a duplicate is what two branches appending the same issue look like Three defects, one cause, one repair. 1. DUPLICATE KEY. Line 270 arrived with 332aed738 (#996), where the author recorded the env-doc red they hit while gating #986. Line 272 arrived with 45b022cdc (#997), the fix for that same red. #997 did the right thing -- it discarded the union driver's clean auto-merge and re-appended against its pinned base 3ce1cf7c7, asserting the prefix property by hand. But `main` then advanced to 332aed738, which had already added a #995 row, and GitHub's squash-merge applied #997's append on top without seeing it. Neither author could have seen the other's row at the time they wrote theirs. 2. MISSING TRAILING PIPE. Line 272 was the only row of 254 that did not end in `|`: a 3-cell row in a 4-column table. `check-agent-record.py` never reported it, because it exits on the first error and the duplicate came first. 3. UNESCAPED PIPE. Line 270 carried a raw `|` inside the code span `git diff origin/main...HEAD | grep '^+.*VT_MOE_EXPERT'`, splitting it into 5 rendered cells. No checker catches this at all. A cell-count histogram over the whole file reads {6: 252, 7: 1, 5: 1} -- the only two malformed rows in the index were the two #995 duplicates. Merging them by key repairs all three at once. The merged row carries BOTH sides' content, per the keyed-record rule: the discoverer's provenance (found while gating #986, proved pre-existing with a matched-arm check rather than asserted, and deliberately not fixed in flow) and the fixer's resolution (documented in docs/ENVIRONMENT.md rather than allowlisted, with the reason). EXCEPTION ARGUED, not waived: this change DELETES a row and EDITS another, which is what `check-issue-index-append-only.py` exists to forbid. The append-only contract cannot repair a duplicate -- appending a third #995 row makes the checker angrier, and the file only becomes well-formed again by removing one. The rule is preserved in substance: 252 unrelated rows are asserted byte-identical AND in the same order, the surviving row sits at the EARLIER of the two positions so every subsequent row keeps the offset it was appended against, and no key is added or lost. Verified mechanically, not by eye: 254 -> 253 rows, #995 exactly 1x, every row 6 parts, unrelated rows compared as a list. Note that gate reported `OK: issue index append-only` against the UNCOMMITTED repair -- it diffs merge-base..HEAD, so it graded an empty diff. That is the instrument reporting on the state it was given, not on the change. Re-run after this commit for a verdict about it. This is the DUPLICATE case, which the checker does catch. It is not #1002 (append-only checker blind to an INTERLEAVE, which preserves uniqueness and fails only the prefix property). #1002 stays open on its own terms. Both are consequences of a record surface every PR writes. Closes #1022. FOLLOWING_AGENTS_PROTOCOL Following-Agents-Protocol: true AI-Assisted: true Assisted-by: AGENT:claude-opus-5 [claude-code] --- .agents/issue-index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.agents/issue-index.md b/.agents/issue-index.md index 5e44e992f..31cb73d3f 100644 --- a/.agents/issue-index.md +++ b/.agents/issue-index.md @@ -267,6 +267,5 @@ rather than merged. `scripts/check-agent-record.py` gates both. | [#940](https://github.com/mudler/vllm.cpp/issues/940) | `MODEL-TEXT-nemotron-h-nemotron-hfor-causal-lm` | The FP8 W8A8 linear path is not a shared seam: `ResidentFp8`, `MatmulFp8CutlassD` and `MatmulFp8CutlassPreQuantD` lived in the anonymous namespace of `src/vllm/model_executor/models/qwen3_5.cpp` (`:1458`, `:1495`, `:1517` @ `c7cb59fbb`), so a second model could reach them only by copying them — the hand-rolled parallel path AGENTS.md §"Shared seams" forbids. NVFP4 already had `dense_nvfp4_gemm.h` + `compressed_tensors/schemes/nvfp4.h`; FP8 had neither half. Forced by `MODEL-NEMOTRON-H` ([#517](https://github.com/mudler/vllm.cpp/issues/517)), whose 46 FP8 W8A8 mamba `in_proj`/`out_proj` projections are 36.6% of decode bytes and 27.6% of GEMM FLOPs, and whose `in_proj` produces the fused `zxbcdt` the conv and the SSD scan consume — so that block cannot be split and has no device path at all without the seam. Extracted to `dense_fp8_gemm.h` + `quantization/fp8.h` with Qwen3.5 byte-identity as the gate; spec [`vt-fp8-shared-seam.md`](specs/vt-fp8-shared-seam.md) | bug | | [#974](https://github.com/mudler/vllm.cpp/issues/974) | — | The FP8 W8A8 resident helpers move weight bytes host->device without `vllm::load_stats::AddDeviceUpload` and without the post-upload `AdoptDeviceBytesAsHost`, while every other resident-weight helper in the same file performs both: `ResidentWeight` (`src/vllm/model_executor/models/qwen3_5.cpp:1009,1016 @ c7cb59fbb`) and `ResidentNvfp4` (`:1106,1111,1116,1121`), whose own comment states the obligation against [#150](https://github.com/mudler/vllm.cpp/issues/150). Affects `ResidentFp8` (`:1458`, now `dense_fp8_gemm.h`), `ResidentFp8Qkv` (`:1555`) and `ResidentFp8Qkvz` (`:3440`). Two unmeasured consequences: load accounting is short by the whole fp8 tower, and its device pages are never re-tagged, which is the shape of the GB10 weight-residency penalty on the 27B decode gap's largest attributed bucket. Found while extracting those entry points in [#940](https://github.com/mudler/vllm.cpp/issues/940) and deliberately NOT fixed there: a byte-identity gate cannot see a device -behaviour change hidden in a move. Listed under `## Owed` in [`vt-fp8-shared-seam.md`](specs/vt-fp8-shared-seam.md) | bug | | [#986](https://github.com/mudler/vllm.cpp/issues/986) | `LTX25-DFR-PIPELINE` | `DFRPipeline` (`dfr_pipeline.py` + `dfr_layout.py` @ `fd4ded7f`) has no representation in this tree — `git grep -i dfr` over `src include tests examples docs` returns ZERO product hits, against 87 `ltx2` hits in `ltx2.cpp` alone as the positive control ([#604](https://github.com/mudler/vllm.cpp/issues/604)). It matters beyond its own feature because it is the **ONLY** upstream consumer of the temporal x2 latent upsampler this project already ships: [`ltx25-temporal-upsampler.md`](specs/ltx25-temporal-upsampler.md) section 7 records the operator as ported, loader-parsed and gated but *"not reachable from any shipped pipeline"*, and `docs/FEATURES.md` carries that as `Temporal x2 ups gated, UNDRIVEN`. No issue tracked that state — `undriven` returned zero hits across open and closed issues. DFR also needs the generated-keyframe-slot READBACK that [#920](https://github.com/mudler/vllm.cpp/issues/920) refused by name and left owed after it CLOSED, so the debt had a spec bullet and no open issue; it needs the LAYOUT and the EXTRACTION but **not** the standalone single-frame decode, because DFR never decodes its slots — it hands them to the spatial upsampler (`dfr_pipeline.py:348`) and feeds them back as `initial_keyframes` (`:364`). Spec [`ltx25-dfr-pipeline.md`](specs/ltx25-dfr-pipeline.md). Campaign [#644](https://github.com/mudler/vllm.cpp/issues/644) | feature | -| [#995](https://github.com/mudler/vllm.cpp/issues/995) | `ENG-EXPERT-STREAM` | `check-env-doc` and `test_check_env_doc` RED in `scripts/agent-preflight.sh` on **every** branch based on `3005447f8`: `VT_MOE_EXPERT_STREAM`, `VT_MOE_EXPERT_STREAM_SLOTS` and `VT_MOE_EXPERT_STREAM_SLOT_BYTES` are read from `src/vllm/model_executor/models/qwen3_5.cpp` (`:5145`, `:5164` @ `3005447f8`) and appear in neither `docs/ENVIRONMENT.md` (`grep -c` returns **0**) nor `scripts/env-doc-allowlist.txt`. Arrived with [#993](https://github.com/mudler/vllm.cpp/pull/993). Found while gating [#986](https://github.com/mudler/vllm.cpp/issues/986) and proved pre-existing with a matched-arm check rather than asserted: the three sites are in a file that branch does not touch, and `git diff origin/main...HEAD | grep '^+.*VT_MOE_EXPERT'` returns nothing. NOT fixed in flow: documenting a knob means stating its default and when to touch it, and the expert-streamer's slot accounting belongs to the row that added it, so a plausible-sounding entry written by a passer-by is how `docs/ENVIRONMENT.md` stops being trustworthy. It is a PRE-FLIGHT gate, so it fails before every edit and presents to each author as a red their own diff caused, which is the shape [#965](https://github.com/mudler/vllm.cpp/issues/965) and [#968](https://github.com/mudler/vllm.cpp/issues/968) both took | bug | +| [#995](https://github.com/mudler/vllm.cpp/issues/995) | `ENG-EXPERT-STREAM` | `check-env-doc` and `test_check_env_doc` were RED on `origin/main`, so every branch cut from it inherited a preflight failure its own diff did not cause: `VT_MOE_EXPERT_STREAM`, `VT_MOE_EXPERT_STREAM_SLOTS` and `VT_MOE_EXPERT_STREAM_SLOT_BYTES` are read from `src/vllm/model_executor/models/qwen3_5.cpp` (`:5145`, `:5195`, `:5189` @ `4496ef196`) and appeared in neither `docs/ENVIRONMENT.md` (`grep -c` returned **0**) nor `scripts/env-doc-allowlist.txt`. They arrived with the `ENG-EXPERT-STREAM` W4 wiring commit `3005447f8` ([#993](https://github.com/mudler/vllm.cpp/pull/993)). Found while gating [#986](https://github.com/mudler/vllm.cpp/issues/986) and proved pre-existing with a matched-arm check rather than asserted: the three sites are in a file that branch does not touch, and `git diff origin/main...HEAD \| grep '^+.*VT_MOE_EXPERT'` returns nothing. It is a PRE-FLIGHT gate, so it failed before every edit and presented to each author in turn as a red their own diff caused -- the shape [#965](https://github.com/mudler/vllm.cpp/issues/965) and [#968](https://github.com/mudler/vllm.cpp/issues/968) both took. The discoverer deliberately did NOT fix it in flow: documenting a knob means stating its default and when to touch it, and the expert-streamer's slot accounting belongs to the row that added it, so a plausible-sounding entry written by a passer-by is how `docs/ENVIRONMENT.md` stops being trustworthy. FIXED in [#997](https://github.com/mudler/vllm.cpp/pull/997) by DOCUMENTING all three in `docs/ENVIRONMENT.md`, not by allowlisting them: a knob that changes the host memory a MoE decode reserves and disables the default-on grouped-MoE path is a deployment surface, not a kernel-internal micro-tuning switch | bug | | [#987](https://github.com/mudler/vllm.cpp/issues/987) | `LTX25-RETAKE` | Two `ltx-2.5` refusal messages state reasons that are no longer true. (a) `src/vllm/multimodal/ltx2_video.cpp:1608 @ 0e1bee42f` says "nothing reads `ref_video_dir` at all", and MiniMax-H3 has always consumed the directory in full (`ReadReferenceClipChw`, `src/vllm/multimodal/minimax_h3_video.cpp:135 @ 0e1bee42f`, called at `:650`); [#975](https://github.com/mudler/vllm.cpp/issues/975) inherited the wider claim from this message. The claim that holds is narrower: the LTX-2.5 engine never reads the directory's CONTENTS. (b) `ltx2_video.cpp:1636-1638 @ 0e1bee42f` says "there is no AUDIO_VAE_ENCODER key filter", and `c2019b0e3` landed `Ltx2AudioVaeEncoderKeyRules()` (`include/vllm/model_executor/models/ltx2_audio_input.h:73 @ 0e1bee42f`) with a live call through `Ltx2EncodeAudioToLatent`. Both rewritten in the `WHAT IS *NOT* THE REASON` shape in the same flow, with one assertion tied to the LOCAL fact that the LTX side now reads the directory | bug | -| [#995](https://github.com/mudler/vllm.cpp/issues/995) | `ENG-EXPERT-STREAM` | `check-env-doc` and `test_check_env_doc` are RED on `origin/main`, so every branch cut from it inherits a preflight failure its own diff did not cause: `VT_MOE_EXPERT_STREAM`, `VT_MOE_EXPERT_STREAM_SLOTS` and `VT_MOE_EXPERT_STREAM_SLOT_BYTES` are read from `src/vllm/model_executor/models/qwen3_5.cpp` (`:5145`, `:5195`, `:5189` @ `4496ef196`) and appear in neither `docs/ENVIRONMENT.md` nor `scripts/env-doc-allowlist.txt`. They arrived with the `ENG-EXPERT-STREAM` W4 wiring commit `3005447f8` ([#993](https://github.com/mudler/vllm.cpp/pull/993)). Same shape as [#965](https://github.com/mudler/vllm.cpp/issues/965)/[#968](https://github.com/mudler/vllm.cpp/issues/968): a pre-existing red presenting to each author in turn as their own. Fixed by DOCUMENTING all three in `docs/ENVIRONMENT.md`, not by allowlisting them — a knob that changes the host memory a MoE decode reserves and disables the default-on grouped-MoE path is a deployment surface, not a kernel-internal micro-tuning switch | bug