fix(GATE-SYMBOL-ANCHORS): cite the symbol, and gate that it is still there (#1143, #1139)

[localai-bot]

A line number is a coordinate into a moving file. src/vllm/entrypoints/model_loader.cpp is cited by line from 109 sites in 45 files, and one 45-line insertion near its top moved 203 of those references at once (#1143). A pin advance left three vllm/v1/worker/** line anchors on KV-WARMUP-PROFILE pointing at a set_attn call, a torch.zeros argument and a comment about max_split_size_mb, and two had already been copied into a header and a spec (#1139). Same defect, two scales.

Of the four available answers, this takes the fourth: adopt the symbol convention, gate it, convert a verified subset, record the rest.

Repairing all 109 fixes today and guarantees tomorrow, and it would launder pre-existing debt, because rewriting a citation from the current tree makes a wrong one and a broken one indistinguishable — the exact thing #1143 says nobody can do. Gating LINE anchors needs a stored expectation table, which is a file every pull request must edit and therefore the lock AGENTS.md ## Records calls a defective gate; reading the expectation out of the cited file instead is the #911 tautology that reported 27/27 FRESH over five anchors pointing at unrelated code.

What decided it is that the convention already exists here. 539 path::Symbol citations were already written, .agents/model-matrix.md uses the form for every upstream model anchor, and not one had ever been checked. So this finishes something half-adopted rather than starting a flag day, and the gate lands green over 93 in-repo anchors.

The shape is what makes it not a tautology, not care. The expectation is the symbol name, written by the citing author, read from the CITING file; only the evidence comes from the cited one. Nothing is derived from the file under test and nothing is stored centrally, so a citation's expectation rides in the file that owns the claim and N pull requests never write one file.

That immunity had a hole, and the fresh review found it. When the citing and the cited file are the SAME file, the two sides collapse: the expectation is read from the file under test, and the citation span itself supplied the evidence, because the search ran over the whole body. `a.cpp::GhostSymbol` written inside a.cpp read as FRESH over a symbol that existed nowhere else. Zero of this tree's anchors are self-citations today and none is satisfied only by a citation span, so nothing was laundered — but .agents/porting.md now tells authors to write the full path, which makes a file documenting its own symbols the most natural next thing anyone writes. Every citation span is now stripped from the cited file before the search, which also closes the cross-file form where a.cpp names Ghost only inside its own citation of b.cpp. test_verdict_depends_on_the_citing_text could not see either door, because it uses two DIFFERENT files; two new cases close it from both sides.

The vacuity guard was a floor of ZERO over a population of ninety. One added FROZEN_PREFIXES entry, or one narrowed CITATION_RE, takes the count from 93 to 1 and a zero-guard stays green the whole way down — the mute-switch shape this repository has been burned by. There is now a recorded floor with headroom (85, a ratchet no change has to edit, so not a per-PR record lock), and the three buckets must SUM to the citation count. --min-checked drives the comparison in a fixture tree so the floor itself is executable.

Three more findings, each with a mutation. An untracked file carrying a stale anchor is invisible and an untracked cited file produces a false "path does not exist"; the skip stays, because scanning the working tree would change what the gate's subject is, but untracked files carrying citations are now COUNTED and PRINTED — the same discipline frozen_files already gets, and the lesson this change reported about itself now applies to the tool and not only to its fixtures. An ambiguous basename was counted and dropped, silently skipping five live citations; it is checked against every candidate and reported only when none contains the symbol. And CITATION_RE opened with `[A-Za-z0-9_], so any path beginning with . matched zero times — latent until somebody cites a spec or a workflow by symbol, which .agents/porting.md now invites.

The measurement

The opt-in upstream mode resolves vllm/... citations against the parity pin, read with git show <pin>:<path>: 364 upstream anchors checked, 353 fresh, 0 stale, across the same pin advance that broke every line anchor #1139 examined. The 11 that did not resolve name a file vLLM deleted and dedupe to 10 reported lines; they are #1199.

"0 stale" says nothing until the corpus is shown capable of going stale. The perturbation control appends Zq to every cited symbol and reports in-repo checked 93 (fresh 0, stale 93) and upstream checked 364 (fresh 0, stale 353, file absent 11): not one of the 446 fresh anchors survives the rename.

Every absolute was re-measured, and the first set did not reproduce

The first record was right about every DELTA and wrong about every ABSOLUTE, which is what a number quoted from an earlier run looks like. Upstream was recorded as 354/343 and reproduces as 364/353. check-agent-record.py was recorded as ENGINE=161 and reports ENGINE=162. The residue was recorded as 106 in 46 falling to 86 in 34 and reproduces as 112 in 47 falling to 92 in 35. The body said 85 in-repo anchors in prose and 86 in its table.

The residue instrument is now written down precisely enough to rerun. Population is git ls-tree -r --name-only <rev> minus .agents/completed/**, .agents/issue-index.md, .agents/benchmark-record.md and .agents/parity-ledger.md; counted is every occurrence of model_loader\.cpp:[0-9]:

excl=(':!.agents/completed' ':!.agents/issue-index.md'
      ':!.agents/benchmark-record.md' ':!.agents/parity-ledger.md')
git grep -I -o -E 'model_loader\.cpp:[0-9]' <rev> -- "${excl[@]}" | wc -l
git grep -I -l -E 'model_loader\.cpp:[0-9]' <rev> -- "${excl[@]}" | wc -l

112 in 47 at the branch base and again at origin/main; 92 in 35 on this branch; 93 in 35 at this merged head, because main independently added one back. 20 converted here.

Converted, and repaired

26 anchors in 16 files, each verified by locating the symbol and confirming the surrounding sentence is still true of it. Most were stale: MakeScheduler cited at 176 lives at 812, SelectQueueForModel cited at 75-104 lives at 148, async_engine cited at 800-811 lives at 1342.

Two conversions were WEAKER than what they replaced and are repaired. A symbol occurring eight times localises nothing: ::max_num_batched_tokens_ named the value being traced rather than the hop, and is now ::MakeScheduler, which is the hop. ::Qwen3_5MTPKind named the enum where the selection is a ternary on the factory flag, and is now ::is_dense_model, which is the thing that decides.

#1139 closes here. Its last cell is a CELL inside an existing .agents/engine-matrix.md row: it adds no row and moves no counter, so it cannot collide with a concurrent session that appends one, and check-agent-record.py reports ENGINE=162 before and after. All three replacement anchors resolve at the pin; the upstream count moved 360 to 364 checked and 349 to 353 fresh with stale still zero.

Two gates were red and no report said so

tests/scripts/test_check_pr_size.py was RED at the reviewed head. Registering a newly created checker in CREATION_MUTATIONS is required — without it the evidence machinery refuses the checker as "absent at BASE and has no closed creation mutation" — and that registration is asserted against an exact expected set the registration never joined. Closed here, which is also the semantic mutation evidence the checker demands for its own edit. The new comment block had also been inserted between an existing comment and its entries; it now sits beside its own.

scripts/check-doc-checkpoint.py reds on commit 4182facff for changing include/vllm/v1/core/sched/scheduler.h without docs/USAGE.md. The path rule does not care that the edit is inside a comment. That obligation is paid: docs/USAGE.md now documents the gate a contributor has to satisfy and the citation form it requires, so the SQUASHED commit carries both halves — verified on a probe squash of this branch, rc=0. The per-commit range verdict on the BRANCH cannot be repaired by any further commit, because 4182facff is immutable and only a history rewrite would move it, and no force-push was taken to make a range report agree with a tree that is already correct. This is the argued exception, and it is visible debt rather than success: a reviewer who rejects the reasoning does not merge the change.

Not done, and named

What	Where it lives now
93 tracked model_loader.cpp line references (20 converted here)	#1143, still OPEN
four specs asserting loader behaviour the loader no longer has	#1198, filed; the fourth (gguf-mtp-spec-decode.md) added by comment
ten upstream citations naming vLLM files deleted at the pin	#1199, filed
a typo in a ONE-component directory falls through to the upstream bucket	deliberate: a miss, never a false accusation, recorded under ## Owed

Gates

Gate	rc
scripts/check-symbol-anchors.py	0 — 618 citations, 93 in-repo checked, 93 fresh, 0 stale, 0 missing local, buckets sum 618 vs 618, floor 85
scripts/check-symbol-anchors.py --self-test	0 — 10 fixtures, 0 failures
tests/scripts/test_check_symbol_anchors.py	0 — 21 cases
tests/scripts/test_check_pr_size.py	0 — 46 cases (was 1 failure at the reviewed head)
scripts/check-symbol-anchors.py --upstream-root <vllm>	1 — 364 upstream checked, 353 fresh, 0 stale, 11 file-absent (#1199)
scripts/check-agent-record.py	0 — ENGINE=162 MODEL=377 QUANT=82 KERNEL=52 BACKEND=85
scripts/check-issue-index-append-only.py	0
scripts/check-commit-style.py --range origin/main..HEAD	0
scripts/check-commit-trailers.py --range origin/main..HEAD	0
scripts/check-doc-checkpoint.py --base origin/main --head HEAD	1 — commit 4182facff, argued above; the squashed shape is 0
scripts/agent-preflight.sh	1 — 81 ok, 1 FAIL (doc-checkpoint range), 0 SKIP

tests/scripts/test_cpu_x86_llamacpp_floor.py was previously reported as "a SKIP, not a pass". It has no skip path: grep -i skip over that file returns nothing. It RAN and failed, and its failure count moved with box load, which is what makes it environmental rather than a verdict on this change. On this run, at 87% disk and lighter load, it ran to a verdict and PASSED — it is one of the 81.

Thirteen mutations, each applied (moved sha256 plus a non-empty git diff --stat), each compiling, each over 21 executed cases taken from the LAST Ran N tests line, all caught, all restored byte-for-byte. Two did not report honestly on the first pass and both are recorded: M11 (a dropped bucket) was not caught at all, because this tree has zero missing local paths and the arithmetic stayed intact until the case grew a fixture tree populating all three buckets; M12's catch depended on the iteration order of a hash set, so by_base is now built over a sorted walk and it was re-run three times. The DISABLED_CREATION_CHECKER stub fails 20 of the 21 cases, so the creation contract is rejected rather than satisfied.

No C++ was recompiled because every C++ edit is inside a // comment.

Closes #1139. #1143, #1198 and #1199 stay OPEN and own the residue named above.

FOLLOWING_AGENTS_PROTOCOL

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