query: relational verbs ("calls"/"callers"/"uses") hijack seed selection and bury the real identifier's callers (upstream Graphify-Labs#2507)

[filipechagas]

Upstream issue

Filed 2026-08-06: Graphify-Labs#2507 (same path fork #1 took for upstream Graphify-Labs#1682: upstream issue → fork spec → implementation → optional upstream PR). The 2026-08-06 sweep found no prior upstream issue covering demoting a relational-intent verb as a seed term.

The upstream issue references:

1. Upstream issue 1445 / PR 1596 — the per-term seed guarantee. This is the amplifier: it turns the verb's junk prefix-match into a guaranteed seed slot that bypasses the gap cutoff.
2. Issue 1900 / PR 1597 — the stopword precedent. Note carefully: PR 1597's tests affirmatively pinned "calls" as a kept content term, so this proposal challenges a deliberate upstream design point, not an oversight — the upstream issue must argue against that decision explicitly, not just around it.
3. Open issue 2381 and open PR 2113 — the nearest live work (seed-path exclusion and per-term recovery bounding, respectively). Position term demotion as complementary: it fixes the cause (a non-content term holding a seed slot at all) where they bound the blast radius of a bad seed.

Framing hook for the upstream issue: _infer_context_filters already proves the system knows "calls" is relational intent for the query — phrasing A emitted Context: call (heuristic) — but that signal never reaches _query_terms/_pick_seeds, so the same word is simultaneously treated as an edge-filter directive and as an identifier competing for a guaranteed seat.

Related but not overlapping: open issue 2384 (node-kind priors) — adjacent seeding-quality work, distinct mechanism.

Problem Statement

When a user asks the semantic query command a natural-language impact question — the single most common question shape for an AI assistant consuming the graph — the answer is wrong or buried, and it fails silently: output renders, fills the token budget, and looks authoritative while containing zero of the correct nodes.

Measured 2026-08-06 on fork v0.9.34 against the api.lawnstarter.com graph @ d2d4bed7ae (46,406 nodes / 139,497 edges). Ground truth, grep-verified: ChargeCustomerService has exactly 3 production callers — ChargeCustomerCancellationFee, Jobs/Customer/BillingCharge, BalanceCustomerAccountService.

Phrasing	Seeds chosen	Result
"Who calls ChargeCustomerService?"	['ChargeCustomerService', '.callStoreWithAmount()'] + Context: call (heuristic)	0/3 callers; 15 nodes, all test noise from the junk seed's neighborhood, ~1,583 tok
"callers of ChargeCustomerService"	['ChargeCustomerService', '.it_ignores_initiator_for_non_ops_callers()']	3/3 present but buried in 42 shown of 147 nodes, ~1,617 tok
"what code uses ChargeCustomerService to charge a customer"	5 seeds incl. .charge(), coder.md, a test method	0/3; 2,307-node explosion, 52 shown, ~1,600 tok

This is not a regression from the fork's PHP call-edge work: baseline v0.9.28 failed the same phrasings with the same .callStoreWithAmount() junk anchor. The fork's richer calls edge set just raises the stakes — good seeds now lead somewhere, so bad seeds cost more.

It is failure mode #2 of 3 that the PE-78803 spike's Recommendation 2 requires resolved before adoption (#1, the PHP calls gap, is fixed and shipped; #3, node-identity stub shadowing, is a separate problem — do not conflate).

Repro (~60s, no LLM cost — never run graphify update in ~/working/lawn/api itself; its graphify-out/ is the preserved v0.9.28 baseline):

cd ~/working/lawn/api && git worktree add --detach /tmp/api-sq d2d4bed7ae
cd /tmp/api-sq && graphify update . --no-cluster
graphify query "Who calls ChargeCustomerService?"   # observe the .callStoreWithAmount() seed

Root-cause hypothesis

⚠️ This is a code-read hypothesis corroborated by the observed seed lists. It has NOT been stepped through (no instrumented run of _score_query/_pick_seeds on the repro graph yet). Verify before building — the diagnosing-bugs loop on the repro graph is the intended first implementation step.

All line references are to graphify/serve.py on fork branch origin/v8.

1. Relational verbs survive as content terms. _query_terms (line 253) drops _QUERY_STOPWORDS (line 221) — a question-word/filler list. "calls", "callers", "uses", "listens" are not in it, so they flow into scoring as if they were identifiers.
2. "calls" prefix-matches a junk anchor. Scoring tiers (lines 275–277): exact 1000 / prefix 100 / substring 1.0, IDF-weighted (_compute_idf, line 281). The normalized label callstorewithamount literally starts with calls, so .callStoreWithAmount() takes the prefix tier for the term "calls" (line 559; amplified ×10 in the per-term singleton tier, line 583). Similarly "callers" substring-matches .it_ignores_initiator_for_non_ops_callers() — the singleton score also accumulates substring hits (line 590), so a junk node can win a term's best_seed_by_term slot on substring alone.
3. The BFS path drift on vague Chinese queries: 40-node corpus, 12 unrelated nodes returned for "rate_limit_check 怎么用？" Graphify-Labs/graphify#1445 per-term guarantee then locks the junk in. _pick_seeds (line 633) first applies the top-score + 20%-gap window with label dedup (query: homonymous generic symbols (e.g. many GET() route handlers) all get seeded, flooding results — related to #1303 Graphify-Labs/graphify#1766), then — lines 702–722 — appends best_seed_by_term[term] for every distinct query term, bypassing the gap cutoff entirely. The guarantee that protects real multi-term queries from starvation also guarantees the verb's junk anchor a seed slot no matter how dominant the real identifier's score was.
4. BFS floods the budget from the junk seed. The pipeline (_query_graph_text, line 1090: _query_terms → _score_query → _pick_seeds at line 1108 → _bfs/_dfs → _subgraph_to_text, default 2,000-token budget) then spends the budget on the junk seed's test-file neighborhood.
5. The sharp asymmetry: _infer_context_filters (line 789, _CONTEXT_HINTS line 727) already recognizes "calls"/"callers"/"uses"-adjacent words as relational intent — phrasing A emitted Context: call (heuristic). But that recognition only filters traversal edges; it never demotes the same word as a seed term. A term consumed as relation intent arguably should not also compete as an identifier — or at minimum should lose the per-term guarantee.

Constraints on any fix

• Must not break the BFS path drift on vague Chinese queries: 40-node corpus, 12 unrelated nodes returned for "rate_limit_check 怎么用？" Graphify-Labs/graphify#1445 per-term seed guarantee. It exists so one term's incidental exact match can't starve the other terms' seeds. Regression sentinel: tests/test_serve.py:810 (test_pick_seeds_diversity_recovers_starved_term).
• No blanket stopwording of "calls"/"callers"/"uses". These can be legitimate identifiers in some corpus (a calls table, a callers() method); adding them to _QUERY_STOPWORDS is the naive fix that regresses someone. Any demotion must be conditional (e.g. only when the term was consumed as relational intent by _resolve_context_filters, or only when other terms produced strong identifier matches).
• Protected behavior is defined by the existing tests around _pick_seeds and _score_query, all on origin/v8:
  • tests/test_serve.py:772–807 — core _pick_seeds gap-window behavior (graphify query: seed scoring returns low-relevance nodes, causing multi-call token cascade Graphify-Labs/graphify#897)
  • tests/test_serve.py:810 — BFS path drift on vague Chinese queries: 40-node corpus, 12 unrelated nodes returned for "rate_limit_check 怎么用？" Graphify-Labs/graphify#1445 starvation recovery (see above)
  • tests/test_serve.py:135, 180 — query: single generic term exact-matching a short leaf label hijacks seed selection in multi-term queries Graphify-Labs/graphify#1602 coverage scaling; single-identifier queries stay byte-identical
  • tests/test_serve.py:845, 862, 873 — query: homonymous generic symbols (e.g. many GET() route handlers) all get seeded, flooding results — related to #1303 Graphify-Labs/graphify#1766 homonymous-label seed dedup, incl. that the per-term guarantee cannot reintroduce a deduped generic label
  • tests/test_serve.py:385 — non-English (German) query seeds a content node, not heading noise
  • tests/test_serve.py:1119, 1128, 1138 — property tests pinning _score_query's ranked output and best_seed_by_term to the legacy per-token semantics (via the _reference_best_seed_by_term oracle at line 1054)
  • tests/bench_query_scoring.py — non-CI microbenchmark that asserts equality of ranked/best_seed_by_term/seeds between legacy and single-pass paths before timing; a fix that changes seeding semantics must update its equality baseline deliberately, not accidentally
• The fix lands on a branch off v8. The graph is rebuilt fresh in a throwaway worktree for grading (see repro); the preserved v0.9.28 baseline graph in ~/working/lawn/api/graphify-out/ must not be touched.

Acceptance Criteria

Graded on the repro graph (api.lawnstarter.com @ d2d4bed7ae, fork build reinstalled from current v8 head first):

1. "Who calls ChargeCustomerService?" → output contains all 3 known callers (ChargeCustomerCancellationFee, Jobs/Customer/BillingCharge, BalanceCustomerAccountService), within the default 2,000-token budget, without the .callStoreWithAmount() (or equivalent verb-prefix junk) seed.
2. "callers of ChargeCustomerService" → all 3 callers present and not buried: they appear in the shown portion of the output, and the shown node set is not dominated by an unrelated seed's neighborhood (the ~147-node / 42-shown haystack shrinks materially).
3. "what code uses ChargeCustomerService to charge a customer" → all 3 callers found; no multi-thousand-node explosion (the 2,307-node traversal is the failure bar), within budget.
4. No-regression check: graphify explain for "What listens to CustomerWasCharged?" — passed pre-fix at ~417 tokens — still returns the correct listener(s) at comparable token cost.
5. Full existing pytest suite green, explicitly including every test cited in Constraints above.
6. New red-→-green tests derived from the 3-phrasing table (the fork has a pytest suite; the table converts directly into fixtures — a corpus with a ChargeX-like service, a verb-prefix decoy like callStoreWithAmount, and 3 known callers).

"Low noise" operationally: the 3 correct callers are within the rendered (shown) node list, and no single junk seed contributes the majority of shown nodes.

Suggested labels

• needs-triage — now: the hypothesis is unverified and the new upstream issue is not yet filed; per docs/agents/triage-labels.md this is "maintainer needs to evaluate".
• Promote to ready-for-agent once (a) the hypothesis is confirmed by an instrumented step-through on the repro graph, (b) the new upstream issue is filed and linked above, and (c) a Solution/Implementation Decisions spec is added — the same bar fork issue PHP: resolve instance-method calls edges from typed receivers (upstream Graphify-Labs#1682) #1 met before it carried that label.

Prior art / references

• Fork issue PHP: resolve instance-method calls edges from typed receivers (upstream Graphify-Labs#1682) #1 + fork PR feat(php): resolve instance-method calls edges from typed receivers (#1) #17 + upstream PR 2492 — the spec-first path this issue imitates.
• Follow-up spike (Finding 5 is the semantic-query evidence): brain/eng/docs/spikes/2026-08-06-PE-78803-re-run-the-graphify-poc-gate-with-the-lawnstarter-fork.md.
• Original spike (baseline numbers, Recommendation 2 adoption bar): Confluence page 6517260331.
• Seeding lineage referenced in code: upstream BFS path drift on vague Chinese queries: 40-node corpus, 12 unrelated nodes returned for "rate_limit_check 怎么用？" Graphify-Labs/graphify#1445 (per-term guarantee), query: single generic term exact-matching a short leaf label hijacks seed selection in multi-term queries Graphify-Labs/graphify#1602 (coverage scaling), query: homonymous generic symbols (e.g. many GET() route handlers) all get seeded, flooding results — related to #1303 Graphify-Labs/graphify#1766 (label dedup), perf(serve): collapse T+1 per-term scoring passes into one traversal Graphify-Labs/graphify#1918 (single-pass refactor).

[filipechagas]

Instrumented step-through results (2026-08-06)

Verified on the pinned repro graph (/tmp/api-d2d4bed, 48,529 nodes / 139,497 edges, installed 0.9.34 build — seeding functions byte-identical to origin/v8; driver scripts in /tmp/gfy-diag/). The live CLI reproduced the measured 3-phrasing table exactly (same seeds, 15 nodes, 0/3 callers).

Per-step verdicts on the root-cause hypothesis above:

• Step 1 — verbs survive stopwording: CONFIRMED. calls, callers, uses, listens all absent from _QUERY_STOPWORDS; _query_terms returned ['calls', 'chargecustomerservice'] etc.
• Step 2 — prefix match admits the junk anchor: CONFIRMED, mechanism corrected. The match does NOT fire in the plain per-token prefix tier (line 559) — norm label .callstorewithamount() has a leading dot. It fires in the joined-singlet tier (serve.py:577–587) via label_tokens.startswith('calls'), worth 100×10×IDF(5.776) = 5,775.7. That tier exists only to feed best_seed_by_term. The callers junk won on substring alone (singleton 9.691). The real identifier ranks PHP: resolve instance-method calls edges from typed receivers (upstream Graphify-Labs#1682) #1 combined at 97,290 — junk never outranks it anywhere except in its own term's slot.
• Step 3 — the BFS path drift on vague Chinese queries: 40-node corpus, 12 unrelated nodes returned for "rate_limit_check 怎么用？" Graphify-Labs/graphify#1445 guarantee locks the junk in: CONFIRMED, strongest result. In all three phrasings the gap-window-only seed list is exactly ['ChargeCustomerService']. Every junk seed entered solely via best_seed_by_term, with combined scores 5.78–103.5 vs gap floors 443.1–673.9.
• Step 4 — junk-seed BFS floods the budget: CONFIRMED for phrasing A, MODIFIED for B/C. A: junk seed contributes 14 of 15 nodes. B: the burying is mostly the real seed's own unfiltered neighborhood (128 of 147; junk adds 21). C: the explosion is dominated by the guarantee-seeded generic noun customer → Customer hub, 2,206 of 2,307 nodes. Verb demotion alone does not fix C.
• Step 5 — the system already knows "calls" is relational: CONFIRMED for A only, sharpened. callers and uses appear in neither _CONTEXT_HINTS nor its aliases (B and C infer []). A fix keyed on "term consumed as relational intent" covers calls but not callers/uses.

Co-causes discovered (affect the acceptance criteria):

1. Inbound calls edges land on method nodes, and the class→method edge has context=None, so the call context filter disconnects a class from its own methods — even with perfect seeding, phrasing A finds 0/3 under the current filter.
2. BalanceCustomerAccountService has no calls edge to ChargeCustomerService at all (reachable at depth 2 only via references/import edges) — acceptance criterion 1 cannot be met by call-filtered traversal alone.
3. Clearly wrong call edges exist in the neighborhood (.parent() --calls--> .setUp(), .handle() --calls--> test methods) — failure-mode-PHP: (new Service())->method() resolves as EXTRACTED with FQN corroboration #3 territory, feeding the "all test noise" impression.

Implication for the fix design: demoting relational verbs from the per-term guarantee is necessary but not sufficient — the design must also handle guarantee-seeded generic nouns (phrasing C) and the context-filter class/method disconnection (phrasing A).

[filipechagas]

Solution / Implementation Decisions spec

Prototype of the full design measured 2026-08-06 on the pinned repro graph (48,529 nodes / 139,497 edges, CLI-faithful undirected load + BFS depth 2, 2,000-token budget; driver /tmp/gfy-diag/proto.py). All line references are graphify/serve.py on v8 head (ff970bb, 0.9.35), which is byte-identical in the seeding functions to the code the step-through comment above verified.

Phrasing	Current v8	With this design
"Who calls ChargeCustomerService?"	15 nodes, 0/3 callers, .callStoreWithAmount() seeded	128 nodes, 3/3 callers rendered, no junk seed
"callers of ChargeCustomerService"	147 nodes / 42 shown, junk test-method seed	128 nodes / 46 shown, 3/3 rendered, junk gone
"what code uses ChargeCustomerService to charge a customer"	2,307 nodes, 0/3	138 nodes, 3/3 rendered (residual: coder.md seed, ~10 nodes — below the "majority of shown nodes" bar)

Solution

Three surgical changes to the query pipeline, each independently toggleable and default-inert outside _query_graph_text:

1. C1 — demote relational-intent terms from the BFS path drift on vague Chinese queries: 40-node corpus, 12 unrelated nodes returned for "rate_limit_check 怎么用？" Graphify-Labs/graphify#1445 per-term guarantee. A new module-level _RELATIONAL_INTENT_TERMS vocabulary (all _CONTEXT_HINTS words + all _CONTEXT_FILTER_ALIASES keys + the caller/use/listen families). _query_graph_text filters these terms out of best_seed_by_term before calling _pick_seeds. The term still competes in scoring and the gap window — this is not stopwording; a corpus-legit calls identifier with a real exact match stays seedable on merit, and stays fully reachable via explain/path (which never take this code path).
2. C2 — skip the guarantee for a term already covered by a picked seed. In _pick_seeds' guarantee loop (line 714), skip term t when t is a substring of an already-selected seed's norm_label (the scorer's own weakest-tier predicate). This implements the guarantee's stated purpose literally: it exists so no term is starved (BFS path drift on vague Chinese queries: 40-node corpus, 12 unrelated nodes returned for "rate_limit_check 怎么用？" Graphify-Labs/graphify#1445, line 658); a term the seed list already matches is not starved. This is what kills phrasing C's customer→hub explosion (2,206 of 2,307 nodes) and the charge→.charge() junk — ChargeCustomerService's own label covers both terms.
3. C3 — heuristic-context-filter starvation fallback. In _query_graph_text (line 1113), when the resolved filter came from the heuristic (filter_source == "heuristic") and the filtered traversal discovers no nodes beyond the seeds, retraverse unfiltered and annotate the header (Context: call (heuristic; relaxed — no matches beyond seeds)). Explicit --context filters never fall back. This rescues phrasing A from the measured co-cause: the class node has zero call-context edges of its own (calls land on method nodes; class→method edges carry context=None), so the call filter strands a perfectly-seeded class at exactly 1 node. Precedent: upstream query seeds can be hijacked by test/doc rationale nodes — make seed-path exclusion configurable with tests/ as the default Graphify-Labs/graphify#2381 specifies the same "retry unfiltered once" shape for its seed-path filter.

Implementation Decisions

• C1 lives in _query_graph_text, not _score_query or _pick_seeds. Filtering best_seed_by_term between the two calls leaves _score_query byte-identical (protects the tests/test_serve.py:1119/1128 legacy-equality property tests outright) and leaves _pick_seeds' signature/semantics unchanged for every existing caller (protects :1138 and tests/bench_query_scoring.py, whose legacy and optimized arms both route through the same _pick_seeds).
• C1 all-relational fallback. If filtering would empty a non-empty best_seed_by_term (query consists only of relational-intent words, e.g. graphify query "calls"), keep the unfiltered map — mirroring _query_terms' existing all-stopword fallback (line 271). The gap window seeds such queries anyway; this just preserves the guarantee for them.
• Vocabulary is derived, plus a documented extension set. _RELATIONAL_INTENT_TERMS = {hint words} ∪ {alias keys} ∪ {caller, callers, use, uses, used, using, usage, listen, listens, listener, listeners}. The extension exists because the step-through showed callers/uses appear in neither _CONTEXT_HINTS (line 725) nor _CONTEXT_FILTER_ALIASES (line 735) — an intent-consumed-only rule misses 2 of the 3 measured phrasings. _CONTEXT_HINTS itself is deliberately untouched: extending it would change traversal-filter inference for phrasings B/C, a separate behavior with its own blast radius.
• C2 is a new keyword-only _pick_seeds parameter, default off (e.g. skip_covered_terms: bool = False), passed True only by _query_graph_text. Every existing direct caller and test sees identical behavior. The coverage predicate is term in seed_norm_label — exactly the substring tier _score_query uses (line 561), so "covered" means "this seed would have matched the term in scoring".
• C2 ordering: the check runs against the gap-window seeds and guarantee seeds appended so far, in the loop's existing sorted-term order, after the existing query: homonymous generic symbols (e.g. many GET() route handlers) all get seeded, flooding results — related to #1303 Graphify-Labs/graphify#1766 label-dedup gate. The BFS path drift on vague Chinese queries: 40-node corpus, 12 unrelated nodes returned for "rate_limit_check 怎么用？" Graphify-Labs/graphify#1445 refinement this encodes: at least one seed matches each term with any match at all — previously enforced as "each term's own singleton winner gets a slot", now as "…unless an already-picked seed already matches the term".
• C3 fires only on total starvation (len(nodes) <= len(start_nodes)), not on "few nodes" — a conservative threshold with no tuning constant, applied identically to BFS and DFS modes. The header annotation keeps the failure mode visible instead of silent.
• Untouched: _QUERY_STOPWORDS (the "no blanket stopwording" constraint — test_query_terms_strips_search_punctuation still pins "what calls extract?" → ['calls', 'extract']), all scoring tiers and IDF, _CONTEXT_HINTS, _filter_graph_by_context, explain/path/find_node (verified: explain resolves via _find_node, cli.py:1342–1369 — none of the changed code).
• Release: version bump + CHANGELOG entry on the fork (serve-only change; no extraction-cache bump needed).

Testing Decisions

• Seam: new tests drive _query_graph_text / _pick_seeds / _score_query through their public shapes, same as the existing seeding tests.
• Red-first from the 3-phrasing table on the synthetic fixture sketched in upstream query: relational-intent verbs ("calls"/"uses") survive stopwording, prefix-match unrelated identifiers, and the #1445 per-term guarantee seats the junk match as a seed Graphify-Labs/graphify#2507 (service + 3 callers + callStoreWithAmount decoy + busy test neighborhood + a Customer-style hub + coder.md-style prefix decoy):
  1. "Who calls X?" → decoy not seeded; callers rendered (C1).
  2. "callers of X" → agent-noun demotion (C1 extension set).
  3. "what code uses X to charge a customer" → no hub seed, node count bounded (C2), callers rendered.
  4. Covered-term skip preserves BFS path drift on vague Chinese queries: 40-node corpus, 12 unrelated nodes returned for "rate_limit_check 怎么用？" Graphify-Labs/graphify#1445: a starved term whose match no seed covers is still recovered (refined-invariant test, pinning that C2 cannot reintroduce starvation).
  5. Heuristic filter starves (class seed, context=None member edges) → unfiltered fallback, header annotated (C3).
  6. Explicit --context never falls back (C3 guard).
  7. All-relational query ("calls") keeps its guarantee (C1 fallback).
• Regression sentinels, run unchanged: tests/test_serve.py:772–807 (graphify query: seed scoring returns low-relevance nodes, causing multi-call token cascade Graphify-Labs/graphify#897), :810 (BFS path drift on vague Chinese queries: 40-node corpus, 12 unrelated nodes returned for "rate_limit_check 怎么用？" Graphify-Labs/graphify#1445), :135/:180 (query: single generic term exact-matching a short leaf label hijacks seed selection in multi-term queries Graphify-Labs/graphify#1602), :845/:862/:873 (query: homonymous generic symbols (e.g. many GET() route handlers) all get seeded, flooding results — related to #1303 Graphify-Labs/graphify#1766), :385 (query: German full-sentence questions pick wrong BFS seeds — stopwords outscore the actual keyword Graphify-Labs/graphify#1900), :1119/:1128/:1138 (perf(serve): collapse T+1 per-term scoring passes into one traversal Graphify-Labs/graphify#1918 equality), plus tests/bench_query_scoring.py's equality gate — all pass on v8 head today (129/129 in test_serve.py) and none needs a baseline change under this design, because every new behavior is opt-in at the _query_graph_text layer.
• Grading protocol: reinstall from the fix branch, rebuild a throwaway worktree graph (never ~/working/lawn/api itself), re-run the 3-phrasing table + the explain "What listens to CustomerWasCharged?" no-regression check (~417 tok pre-fix; structurally unaffected but re-graded anyway).

Out of Scope

• Missing BalanceCustomerAccountService → ChargeCustomerService calls edge (co-cause 2). Root-caused: the receiver property is declared untyped with a @var docblock and assigned in the constructor body (BalanceCustomerAccountService.php:14–20); _resolve_php_member_calls binds this.<prop> only from typed properties and constructor-promoted params (extract.py:3346), and docblock receivers are documented out-of-scope of PHP: resolve instance-method calls edges from typed receivers (upstream Graphify-Labs#1682) #1's spec. Filed separately as PHP: docblock-typed property assigned in the constructor body binds no receiver type — missing calls edge (co-cause 2 of #37) #38. Acceptance criterion 1 does not depend on it: with C3's unfiltered fallback the caller is reachable (and measured rendered) via its references/import edges.
• Wrong call edges (.parent() --calls--> .setUp(), .handle() --calls--> <test methods>) — failure mode PHP: (new Service())->method() resolves as EXTRACTED with FQN corroboration #3 territory; filed separately as PHP: clearly-wrong calls edges in the repro neighborhood (.parent() --calls--> .setUp(); .handle() --calls--> test methods) — failure mode #3 evidence #39 with the probe evidence; deliberately not conflated here.
• Structural-edge passthrough for context filters (letting contains/method edges pass a call filter so class seeds can traverse to their methods) — the deeper fix behind C3's fallback; even with it, criterion 1 stays unreachable under a hard filter until the extraction gap above is fixed, so it is follow-up work, likely upstream.
• code still earns a guarantee seed (coder.md, prefix match). Accepted residual: not relational intent, not covered by the identifier seed; measured blast radius ~10 of 138 nodes, below every acceptance bar. Upstream query seeds can be hijacked by test/doc rationale nodes — make seed-path exclusion configurable with tests/ as the default Graphify-Labs/graphify#2381/feat(query): exclude test paths from default seeds Graphify-Labs/graphify#2403 (test-path seed exclusion) and fix: bound per-term query seed recovery Graphify-Labs/graphify#2113 (bounded recovery) are complementary if they land.
• Relation-aware answer ranking (using the inferred call intent to rank inbound callers first). Phrasing B's residual 128-node haystack is the real seed's own neighborhood; shrinking it is this future work, not seed hygiene.

Further Notes

• Upstream positioning: this implements candidate direction 2 from query: relational-intent verbs ("calls"/"uses") survive stopwording, prefix-match unrelated identifiers, and the #1445 per-term guarantee seats the junk match as a seed Graphify-Labs/graphify#2507 (guarantee demotion — the minimal change to the composition failure), extended with C2 because the step-through proved verb demotion alone cannot fix phrasing C, and C3 because the context-filter co-cause otherwise caps phrasing A at 1 node even with perfect seeds. Upstream fix(serve): drop question/filler stopwords from query terms Graphify-Labs/graphify#1597 deliberately pinned calls as a kept content term — C1 honors that decision (the word still scores; it only loses its unconditional seat).
• Criterion 2's "haystack shrinks materially": measured 147→128 nodes / 42→46 shown. The junk seed's neighborhood is fully gone; what remains is the real seed's own neighborhood, whose pruning is the relation-aware-ranking follow-up above. The primary clauses (3/3 rendered, no unrelated-seed domination) pass.
• Prototype grading table above is reproducible via /tmp/gfy-diag/proto.py (volatile; the fixture-based tests supersede it).

[filipechagas]

Spec: demote relational-intent terms from seed guarantee, skip covered terms, relax starving heuristic context filters

Consolidated spec in /to-spec format. Supersedes the "Solution / Implementation Decisions spec" comment above (same design, fuller: user stories, seam decisions, no volatile line references). Test seams below were confirmed with the maintainer.

Problem Statement

When someone asks the knowledge graph a natural-language impact question — "Who calls ChargeCustomerService?", "callers of X", "what code uses X" — the answer comes back wrong or buried, and it fails silently: the output renders, fills the token budget, and looks authoritative while containing zero (or a buried fraction) of the correct nodes. This is the single most common question shape for an AI assistant consuming the graph, and it is failure mode #2 of 3 blocking the PE-78803 adoption gate.

The verified mechanism (step-through comment above): relational verbs and generic nouns survive stopwording, their junk matches lose everywhere on merit, but the per-term seed guarantee grants each query term an unconditional seed slot — so a verb's prefix-decoy, a test method, or a hub class enters the traversal anyway and floods or starves the output. A co-cause compounds it: when the question triggers the heuristic call context filter, the filtered traversal cannot leave a class-node seed at all (calls attach to method nodes; class-to-member edges carry no context), so even perfect seeding returns a near-empty answer.

Solution

Ask the same three questions and get the right answer within the default token budget:

• The junk seeds disappear: a relational word ("calls", "callers", "uses") no longer buys an unrelated decoy a guaranteed seat, and a generic noun already covered by the main identifier match ("customer", "charge" inside ChargeCustomerService) no longer spawns a redundant hub seed.
• The real identifier's neighborhood is what fills the budget, so all ground-truth callers render in the shown portion.
• When the inferred context filter would strand the traversal at the seeds themselves, the query transparently relaxes it (annotated in the header) instead of returning a confident near-empty answer. An explicitly requested filter is always honored.
• Nothing is stopworded: relational words still score, still compete for seeds on merit, and symbols literally named calls/uses remain findable.

Measured on the pinned 48.5k-node api.lawnstarter.com repro graph, the prototyped design takes the three acceptance phrasings from 0/3, 3/3-buried, 0/3-exploded to 3/3 rendered, 3/3 rendered, 3/3 rendered with the 2,307-node explosion reduced to 138 nodes.

User Stories

1. As an AI assistant consuming the graph, I want "Who calls ChargeCustomerService?" to render all known production callers within the default token budget, so that I can answer impact questions correctly on the first try.
2. As an AI assistant, I want "callers of X" to work the same way even though "callers" never triggers the context-filter heuristic, so that phrasing variations don't change answer quality.
3. As an AI assistant, I want "what code uses X to charge a customer" to avoid multi-thousand-node traversal explosions, so that the answer isn't 95% an unrelated hub's neighborhood.
4. As an AI assistant, I want a relational verb's incidental prefix/substring decoy (e.g. callStoreWithAmount for "calls") to never enter the seed list through the per-term guarantee, so that the budget isn't spent on an unrelated test neighborhood.
5. As an AI assistant, I want a query term that an already-picked seed's label plainly matches to claim no additional guaranteed seed, so that "charge a customer" doesn't re-seed .charge() and the Customer hub when ChargeCustomerService is already seeded.
6. As an AI assistant, I want a genuinely starved term — one no picked seed's label matches — to still receive its guaranteed seed, so that the original starvation protection survives this change.
7. As an AI assistant, I want the correct callers to appear in the shown portion of the output, not just the traversed set, so that truncation doesn't hide the answer.
8. As an AI assistant, I want a heuristically inferred context filter that yields no nodes beyond the seeds to fall back to an unfiltered traversal, so that a class-node seed still reaches its callers through member and reference edges.
9. As an AI assistant, I want the header to state when a heuristic filter was relaxed, so that I can tell a filtered answer from a fallback answer.
10. As a developer passing an explicit context filter flag, I want my filter honored even when it produces a tiny result, so that the tool never second-guesses an explicit instruction.
11. As a developer whose corpus legitimately contains a symbol named calls or uses, I want that symbol to keep scoring and to win seeds on merit (exact-match dominance intact), so that the fix doesn't blanket-stopword my identifiers.
12. As a developer, I want symbols named calls/uses/code to stay fully findable through node lookup and path tools, so that demotion in one pipeline never hides a node elsewhere.
13. As a developer running a single-identifier lookup, I want the results byte-identical to today, so that the change affects only multi-term natural-language queries.
14. As a developer asking a question made only of relational words (e.g. querying just "calls"), I want the per-term guarantee retained for it, so that the query still seeds something sensible.
15. As a developer asking questions in German or other supported languages, I want seeding behavior unchanged, so that the existing non-English protections keep holding.
16. As a developer relying on homonymous-label dedup, I want the guarantee changes layered after the existing label-dedup gate, so that generic labels still contribute at most one seed.
17. As a developer using depth-first traversal mode, I want the same starvation-fallback semantics as breadth-first, so that mode choice doesn't change filter behavior.
18. As a maintainer, I want every existing seeding regression sentinel (gap window, starvation recovery, coverage scaling, label dedup, non-English, legacy-equality property tests, benchmark equality gate) to pass without baseline edits, so that the change is provably additive.
19. As a maintainer, I want the new behaviors expressed as opt-ins wired only from the query pipeline, so that every other caller of the scorer and seed picker is untouched by construction.
20. As a maintainer, I want the relational-intent vocabulary derived from the existing context-hint and alias tables plus one documented extension set, so that there is a single auditable definition rather than scattered word lists.
21. As a maintainer, I want the traversal-filter inference vocabulary left unchanged, so that this fix cannot alter which queries get context-filtered in the first place.
22. As a maintainer, I want a changelog entry and version bump describing the behavior change, so that consumers can correlate output changes with a release.
23. As an implementing agent, I want red-first tests derived from the measured three-phrasing table on a synthetic fixture, so that the acceptance criteria are executable before any production code changes.
24. As an implementing agent, I want the residual imperfections documented (the code→coder.md guarantee seed; the real seed's own 128-node haystack), so that I don't chase them as bugs in this change.
25. As an upstream contributor, I want the fix shaped as the minimal change to the guarantee's composition failure (upstream issue 2507, direction 2), so that it remains upstreamable alongside open upstream work on bounded recovery and seed-path exclusion.

Implementation Decisions

• Three independent changes, each toggleable and default-inert, all activated only from the natural-language query pipeline:

  • C1 — relational-intent demotion. A module-level frozenset of relational-intent terms; the query pipeline removes these terms from the per-term winner map between scoring and seed selection. The scorer's and picker's public signatures and semantics are unchanged for all existing callers. From the prototype, the vocabulary definition (the decision-rich part):

    _RELATIONAL_INTENT_TERMS = frozenset(
        {word for _ctx, hints in CONTEXT_HINTS for word in hints}
        | set(CONTEXT_FILTER_ALIASES)          # alias keys, e.g. "invocation", "imports"
        | {"caller", "callers", "use", "uses", "used", "using", "usage",
           "listen", "listens", "listener", "listeners"}
    )

    The extension set exists because the step-through proved "callers" and "uses" appear in neither existing table, so an intent-consumed-only rule misses two of the three measured phrasings.

  • C1 all-relational fallback: if demotion would empty a non-empty winner map, keep it unfiltered — mirroring the existing all-stopword fallback in query-term extraction.

  • C2 — covered-term guarantee skip. A new keyword-only, default-off parameter on the seed picker. In the guarantee loop, a term is skipped when it is a substring of an already-picked seed's normalized label — the same predicate as the scorer's weakest match tier, so "covered" means "this seed would have matched the term in scoring". Runs in the existing sorted-term order, after the existing label-dedup gate. This refines the starvation invariant to: every term with any match is matched by at least one seed (previously: every term's own singleton winner gets a slot).

  • C3 — heuristic-filter starvation fallback. After traversal, when the active context filters came from the heuristic (not explicit arguments) and the traversal discovered no nodes beyond the seeds, retraverse the unfiltered graph and append a relaxation note to the Context: header. Applies identically to both traversal modes. Explicit filters never fall back. Threshold is deliberately "zero expansion" — no tuning constant.

• What is deliberately untouched: the query stopword list (no blanket stopwording — upstream deliberately pinned "calls" as a kept content term), all scoring tiers and IDF weighting, the context-hint vocabulary that drives traversal-filter inference, edge filtering itself, and the node-lookup/path/explain flows (verified to share none of the changed code).
• Why demotion happens between scoring and picking rather than inside either: it keeps the single-pass scorer byte-identical (its legacy-equality property tests and the benchmark equality gate hold without edits) and keeps the picker inert for every caller that doesn't opt in.
• Release: fork version bump + changelog entry; no extraction or cache implications (serve-side only).

Testing Decisions

• Seams (confirmed with the maintainer): two.
  1. Primary — the query-pipeline text seam: fixture graph in, rendered text out. Assertions read only external output: seed labels via the Start: header, caller presence via rendered node lines, node counts and the relaxation note via the header. All three phrasing tests, the fallback tests, and the explicit-filter guard test live here.
  2. Secondary — the existing scorer→picker composition seam used by all prior seeding tests: the refined guarantee invariant (covered term skipped; uncovered starved term still recovered) is asserted directly on seed lists, exactly where the starvation-recovery and dedup-guarantee prior art already sits.
• A good test asserts external behavior only: what renders, which seeds are chosen, what the header says — never vocabulary-set membership, internal map contents, or loop order (vocabulary tweaks must not be test-breaking).
• Red-first from the measured three-phrasing table on a synthetic fixture (per the sketch in the upstream issue): a service class, three known callers, a camelCase verb-prefix decoy with a busy test-method neighborhood, a generic-noun hub class, and a doc file that prefix-matches "code". Each positive case pairs with a decoy asserted absent, following the fork's established good-test shape.
• Enumerated new tests: (1) who-calls phrasing seeds no decoy and renders all callers; (2) agent-noun phrasing ("callers of") likewise; (3) generic-noun phrasing seeds no hub and stays bounded; (4) covered-term skip preserves starvation recovery for uncovered terms; (5) heuristic-filter starvation falls back unfiltered with annotated header; (6) explicit filter never falls back; (7) all-relational query keeps its guarantee.
• Regression sentinels run unchanged — the gap-window suite, starvation recovery, coverage scaling, homonymous-label dedup (including the guarantee-cannot-reintroduce-dupe case), the non-English seeding test, the legacy-equality property tests, and the benchmark's equality gate. All pass on the current branch head today; the opt-in design means none needs a deliberate baseline change.
• Graded acceptance on the pinned repro corpus after reinstalling from the fix branch: the three-phrasing table plus the listener-question no-regression check at comparable token cost.

Out of Scope

• The missing caller edge for the docblock-typed, constructor-assigned property receiver — extraction-side gap, filed as PHP: docblock-typed property assigned in the constructor body binds no receiver type — missing calls edge (co-cause 2 of #37) #38. The acceptance criteria do not depend on it: with C3 the affected caller is reachable (and was measured rendered) through reference/import edges.
• Clearly wrong call edges near the repro neighborhood (model accessor "calling" test fixtures; production code "calling" test methods) — failure mode PHP: (new Service())->method() resolves as EXTRACTED with FQN corroboration #3 evidence, filed as PHP: clearly-wrong calls edges in the repro neighborhood (.parent() --calls--> .setUp(); .handle() --calls--> test methods) — failure mode #3 evidence #39; deliberately not conflated.
• Structural-edge passthrough for context filters (letting containment/member edges pass a call filter) — the deeper fix behind C3's fallback; insufficient on its own until PHP: docblock-typed property assigned in the constructor body binds no receiver type — missing calls edge (co-cause 2 of #37) #38 lands, so deferred, likely upstream.
• The code term's residual guarantee seed (a doc-file prefix decoy, measured ~10 of 138 nodes) — below every acceptance bar; complementary upstream work (test-path seed exclusion, bounded recovery) would shrink it further if it lands.
• Relation-aware answer ranking (using inferred intent to rank inbound callers first) — the remaining haystack in the "callers of" phrasing is the real seed's own neighborhood; pruning it is future work, not seed hygiene.
• Extending the traversal-filter inference vocabulary ("callers"/"uses" triggering the call filter) — separate behavior change with its own blast radius.

Further Notes

• Measured prototype results (2026-08-06, pinned repro graph, CLI-faithful undirected load, depth 2, 2,000-token budget): phrasing A 15 nodes/0-of-3 with decoy seed → 128 nodes/3-of-3, no decoy; phrasing B 147 nodes/3-of-3-buried with junk seed → 128 nodes/3-of-3, junk gone; phrasing C 2,307 nodes/0-of-3 → 138 nodes/3-of-3. Per-change attribution: C1 alone fixes B; C1+C2 fixes C; C3 is required for A.
• Upstream positioning: implements direction 2 of upstream issue 2507 (guarantee demotion — the minimal change to the composition failure), extended with C2 because verb demotion alone provably cannot fix the generic-noun phrasing, and C3 because the context-filter co-cause otherwise caps the who-calls phrasing at one node even with perfect seeds. The relaxation-retry shape follows the precedent set by upstream's seed-path-exclusion proposal.
• This spec was produced from the verified step-through on this issue plus a live prototype graded against the real corpus; the prototype is superseded by the fixture tests above.

[filipechagas]

Fresh acceptance grading — measured on the pinned repro corpus, superseding the prototype table

Implementation complete on feat/seeding-fix-37 @ 457b31e (v0.9.36; C1 #40, C2 #41, C3 #42, release+grading #43 — all closed). CLI reinstalled from the branch (graphify --version → 0.9.36), graded against /tmp/api-d2d4bed at the pinned rev d2d4bed7ae (no rebuild — zero extraction changes; the preserved baseline graph was never touched). Ground truth re-verified independently: grep -rln ChargeCustomerService app/ returns exactly the 3 known production callers.

#	Phrasing	Nodes (pre → post)	Seeds (Start:)	Callers shown	Header note	~tok
1	"Who calls ChargeCustomerService?"	15 → 128	['ChargeCustomerService']	3 of 3 (was 0 of 3)	call (heuristic; relaxed — no matches beyond seeds)	1617
2	"callers of ChargeCustomerService"	147 → 128	['ChargeCustomerService']	3 of 3 (was 3-of-3 buried under junk-seed haystack)	none	1601
3	"what code uses ChargeCustomerService to charge a customer"	2,307 → 138 (−94%)	['ChargeCustomerService', 'coder.md']	3 of 3 (was 0 of 3)	none	1601

• Criterion 4 (explain listener no-regression): explain "CustomerWasCharged" → RefreshCustomerPropertiesCanSelfReactivate (imports + .handle() references), 417 tok — identical to the pre-fix figure.
• The prototype's predicted table (128/128/138, 3-of-3 across the board) reproduced exactly.
• Junk seeds demonstrably demoted, not stopworded: both decoys (callStoreWithAmount, it_ignores_initiator_for_non_ops_callers) still exist as graph nodes; they just no longer get guarantee seats.
• Documented residual confirmed and bounded: the code → coder.md guarantee seed contributes 10/138 traversed, 6/44 shown (14%) in phrasing 3 — below every acceptance bar, per the spec's Out of Scope.
• Suite: 4,177 passed, zero baseline edits (git diff --stat 725d082..HEAD -- tests/ = 2 new files only); every Constraints sentinel re-run by name; bench equality gate holds.

Next: fork PR merging feat/seeding-fix-37 into v8, then the upstream PR against Graphify-Labs referencing upstream Graphify-Labs#2507.