fix(query): score the rationale attribute as its own tier (#2293)

[andytsai821201-spec]

Fixes #2293.

Summary

The extraction spec stores the WHY of a concept as a rationale attribute on the node, not as a node. _score_query never read it and _node_search_text never indexed it, so for a "why does X …" question the node that literally states the answer was neither a trigram candidate nor a seed unless the asker already knew its label. #2293 measured 0 / 5 answers reached on a 5.5k-node corpus where all five answer nodes existed.

This implements the fix the issue proposes, minimally (+~40 lines of code): a rationale scoring tier and the matching search-text field.

Fix

• _RATIONALE_MATCH_BONUS = 0.75 — below the label substring tier (1.0), above the source-path tier (0.5). A term found in the rationale adds to the node's score and to the per-term singleton that seats seeds, but — exactly like the source tier — never to term coverage, so a long rationale adds recall without restoring a coverage-scaled exact tier it did not earn.
• _node_rationale_text(data) — one normalizer (diacritics folded, lower-cased); tolerates the list an extractor may emit; "" when absent.
• _node_search_text — appends that text as a trailing NUL-separated field, only when present, so the trigram prefilter remains a complete candidate generator for the scorer (the docstring's contract) and every existing field position — including the explain/_find_node cannot resolve node IDs containing punctuation or non-ASCII text (concept:*, merge-graphs ::, Hangul) #2467 folded-id slot — is unchanged.

Nodes without a rationale score exactly as before. No new flag, no LLM, one extra dict lookup per candidate node.

Before / after (the #2293 shape)

Node FAB visibility rule with rationale "Hidden when the mini card is dismissed and while the geolocation popover is open, because that popover opens upward into the DirectionsFAB's space."; neighbors DirectionsFAB, GeolocationButton, MiniCard.

query "why is the directions button hidden when the geolocation popover opens"

before:  Start: ['GeolocationButton', 'DirectionsFAB']            <- answer node absent
after:   Start: ['GeolocationButton', 'DirectionsFAB', 'FAB visibility rule']

Tests (all watched failing first)

• rationale-only match ranks the node; label shares no token with the query
• tier order: label substring > rationale > source path
• rationale hit does not count toward coverage (a gains a sub-unit nudge over b, not ¾ of an exact tier)
• list-valued rationale tolerated
• _node_search_text carries the field; without a rationale the 5-field layout is unchanged
• end to end: the "why" question above seats the rationale node as a seed

tests/test_serve.py: 152 passed. Full suite: 5,170 passed; the 15 failures present (test_ollama_retry_cap.py missing openai, test_skillgen.py audit baselines) reproduce identically on pristine v8 in this environment.

Relation to existing work

• Design credit to @nuboxworld-byte — the tier placement, the no-coverage rule and the search-text requirement are all from query scores labels only, never the rationale attribute — so "why" questions cannot reach the node that answers them #2293's "Suggested fix". Their PR fix(query): score the rationale attribute, not just labels (#2293) #2294 implements the same idea, but its diff carries the whole repository (+252,795 / −5,138 across 766 files) from a base mismatch and cannot be reviewed or merged as-is; this is a fresh minimal implementation against v8. Happy to close this in favour of fix(query): score the rationale attribute, not just labels (#2293) #2294 if it gets rebased.
• fix(query): downweight rationale prefix seeds #2975 (downweight rationale prefix seeds) concerns nodes whose label is docstring prose. This tier is substring-level at 0.75× — well below the 100× prefix bonus that PR targets — so it cannot create that dominance; the two compose.
• Out of scope, as query scores labels only, never the rationale attribute — so "why" questions cannot reach the node that answers them #2293 itself notes: _pick_seeds' gap cutoff can still drop a rationale-scored node that ranks 2nd–4th. That is a separate, more opinionated change.

🤖 Generated with Claude Code

[graphify-labs]

Graphify reviewed this change.

Looks safe to merge — no coupling regressions and no blocking issues, checked against the code graph (not a self-assessment).

Formal verification. 1 change(s) tested, no difference found (not proven).

---

Graphify review — findings

Adds a rationale scoring tier so "why" questions match the answer text stored on a node's rationale attribute rather than its label: _node_rationale_text folds diacritics and joins list-valued rationales, and _score_query awards _RATIONALE_MATCH_BONUS (0.75) per matching term — ranked below a label-substring hit, above a source-path hit, and excluded from term coverage so a long rationale boosts recall without reclaiming the exact-label tier. _node_search_text appends the rationale last and only when present, keeping the trigram prefilter a complete candidate generator while leaving every existing field position unchanged.

No blocking issues surfaced.

Analysis details — impact, health, verification

Impact & health

Graphify review

Impact — 582 functions depend on the 340 functions this change touches.

Health — this change adds coupling hotspots:

• new: dispatch_command() — 2 callers, 123 callees
• new: _query_graph_text() — 21 callers, 9 callees
• new: _score_query() — 15 callers, 6 callees
• new: _query_terms() — 20 callers, 3 callees
• new: run_benchmark() — 16 callers, 3 callees
• new: _build_server() — 2 callers, 16 callees
• new: _load_graph() — 9 callers, 3 callees
• new: _query_subgraph_tokens() — 7 callers, 3 callees
• …and 9 more — each is listed as a finding

Verification — 582 functions in the blast radius were not formally verified this run (proofs are advisory here).

Gate & verification

graphify gate

PASS — objectively clean (no health regressions, tests not run — proofs not run this pass (advisory)). Grounded, not self-assessed.

Advisory (not blocking):

• verification_scope: 407 function(s) in the blast radius were not formally verified this run

Formal verification

No difference found (not proven): No behavior difference found in \_node\_search\_text (not a proof).

The verifier ran both versions of \_node\_search\_text on many inputs and saw identical behavior every time. Strong evidence the change is safe, but evidence, not a proof.

Guarantee: Empirical: differential testing (both versions run on many generated inputs). A divergence on an untested input remains possible, so this is 'no counterexample found', not 'proven equivalent'.

Note: An input the sampler did not try could still differ.

Could not verify: Could not verify \_score\_query.

The verifier did not have enough to check \_score\_query, so it is saying so rather than guessing. No false assurance is the whole point.

Guarantee: No guarantee either way, this is an honest abstention, not a pass.

Note: Reason: not verifiable: all 45 sampled inputs raised on both versions — the function never executed, so 'no divergence' would be vacuous (mostly TypeError — names the real obstacle, not a sampling gap)

· 1 grounded finding(s) anchored inline below; 16 more finding(s) on lines outside this diff (see the check run).

[graphify-labs]

⚠️ Health regression — _node_search_text()

high coupling complexity (Ca·Ce = 15).

Grounded coupling-delta finding (deterministic), not an LLM guess.