check-symbol-anchors deduplicates by (path, symbol), so its count is sites-minus-duplicates and a repair can UNMASK a stale citation
Nobody has claimed this yet.
- Dominant language
- C++
- Stars
- 423
- Forks
- 53
- Avg merge
- 20h 26m
- Merged PRs (30d)
- 310
Description
Row: -
Owed by the model matrix. .agents/specs/upstream-pin-advance-e126687.md lists it
under ## Owed.
Found by wave MATRIX while repairing #2819. Not fixed here: the repair is a
change to a checker's reporting contract, and #2819's branch is a records-only
change across a keyed matrix.
The defect
scripts/check-symbol-anchors.py keys its report on (path, symbol):
seen: set[tuple[str, str]] = set()
...
if key not in seen:
...
seen.add(key)
So a citation that appears at N sites is reported ONCE. Its summary line
("N stale or unresolvable symbol anchor(s)") therefore counts DISTINCT
citations, and a reader takes it for a count of stale SITES. Nothing in the
output says which reading is correct.
What it cost
#2819 measured the e126687a9a advance as "fifteen citations go stale" and
built a per-file repair list from that report. Sweeping every
.agents/model-matrix.md citation directly against the pin instead — 313
distinct citations, git show <pin>:<path> per path, whole-word symbol match —
finds a SIXTEENTH stale matrix site the report never named:
$ grep -n 'gritlm.py' .agents/model-matrix.md
255:| `MODEL-TEXT-gritlm-grit-lm` | `GritLM` | ... `vllm/model_executor/models/gritlm.py::GritLM` ...
334:| `MODEL-EMBED-gritlm-grit-lm` | `GritLM` | ... `vllm/model_executor/models/gritlm.py::GritLM` ...
The checker reported line 255 only. MODEL-EMBED-gritlm-grit-lm cites the same
deleted file and was invisible, because vLLM registers GritLM in both
_TEXT_GENERATION_MODELS and _EMBEDDING_MODELS and our matrix mirrors that
with two rows.
The same masking hid two more sites in .agents/sync/2026-09-03-e126687-advance.md
(:268 cpu_fused_moe.py::select_experts, :274 kv_cache_utils.py::get_num_blocks).
They only appeared in the report AFTER the spec-side copies of those two
citations were repaired — repairing one site UNMASKED another, which is the
worst possible failure shape for a rot budget, because the count can go UP as
you fix things.
Why this is not cosmetic
scripts/record-anchor-baseline.json is a ratchet over bucket counts. A
deduplicated count cannot ratchet honestly: two repaired sites and one newly
unmasked site read as "one fewer", and one repaired site that unmasks its own
duplicate reads as no progress at all.
What is owed
- Report every SITE, or say in the summary line that the count is distinct
citations and print the site count beside it. Either is defensible; silence
between the two is not. - Whichever is chosen, add a fixture to the
--self-testcorpus with the SAME
citation at two sites and assert the reported count, so the choice is
executable rather than a comment. - Re-derive
scripts/record-anchor-baseline.jsononce the count changes
meaning.
Positive control for the sweep above
The direct sweep distinguishes both failure modes and was controlled in the same
command shape:
vllm/v1/core/kv_cache_utils.py::get_num_blocks -> SYMBOL MISSING
vllm/v1/core/kv_cache_utils.py::unify_hybrid_kv_cache_specs -> SYMBOL PRESENT
vllm/model_executor/models/llama.py::LlamaForCausalLM -> SYMBOL PRESENT
vllm/model_executor/models/gritlm.py::GritLM -> FILE ABSENT
FOLLOWING_AGENTS_PROTOCOL
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with scripts/check-symbol-anchors.py, its --self-test corpus, and scripts/record-anchor-baseline.json. Reproduce the duplicate-site behavior described for .agents/model-matrix.md and the sync citation, then choose and implement an explicit count contract with a two-site fixture. Re-derive the baseline after the reported meaning is settled.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- testing, tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100