mudler / mudler/vllm.cpp

check-symbol-anchors deduplicates by (path, symbol), so its count is sites-minus-duplicates and a repair can UNMASK a stale citation

Open
#2,971 0 comments 0 reactions 0 assignees View on GitHub

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

  1. 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.
  2. Whichever is chosen, add a fixture to the --self-test corpus with the SAME
    citation at two sites and assert the reported count, so the choice is
    executable rather than a comment.
  3. Re-derive scripts/record-anchor-baseline.json once 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.