fix: scale per-term exact/prefix score tiers by squared term coverage (#1602)

[fkhawajagh]

Fixes #1602. Follows up on the discussion there; builds on the per-term seed guarantee from #1596 (d56ee83) and fixes the scoring half that was left open.

Root cause

In a multi-term query, a single generic term that exactly equals a short leaf label (home vs a home() controller action, list vs a list() function) receives _EXACT_MATCH_BONUS x IDF and outscores every node matching several of the query's terms by roughly 10x. _pick_seeds' 20% gap cutoff then discards the genuinely relevant candidates. #1596 guarantees each term still contributes a seed, which stops the starvation; but nothing in _score_nodes rewarded matching more of the query, so the collision still owned the top of the ranking (and path-style consumers of scored[0] have no per-term backstop).

The change

_score_nodes now scales the per-term exact/prefix tier contributions by squared term coverage:

score += tiered * (matched_terms / total_terms) ** 2

Design decisions, each of which came out of testing against a real graph (below):

1. Squared, not linear. The exact tier is 10x the prefix tier; at linear coverage a 1-of-10-terms exact hit still edges out a 3-of-10-terms prefix+substring match. The regression test pins this coupling: retuning either tier constant re-fails it.
2. Coverage counts label hits only (exact/prefix/substring). Source-path hits still score, but do not count toward coverage. Without this, a colliding leaf that lives in the target's own directory (the common case) wins back most of its exact tier via path fragments: on the regression scenario the leaf scored 122.5 vs the target's 66.3 when path hits counted, vs 30.9 / 40.1 when they do not.
3. Substring and source bonuses stay unscaled, as does the full-query tier (a full-label match already implies full coverage).
4. Query tokens are deduped, order-preserving, as _pick_seeds already does. A repeated query word previously double-added every tier; under coverage scaling it would also inflate the matched ratio, quadratically restoring the collision (a query with list twice re-ranked the list() leaf above the intended target, 154.0 vs 84).
5. Single-term and full-coverage queries are unchanged (coverage == 1), so identifier lookups keep exact-match dominance. A test pins the exact pre-change score.

Results on a real graph

Production graph: 5,700 nodes / 7,899 edges (Phoenix/Elixir codebase plus design docs; the graph both #1602 repros came from). Methodology: run _query_terms -> _score_nodes -> _pick_seeds (the _query_graph_text flow) on base v8 (8a608d1, which already includes #1596) and on this branch, and diff the top of the ranking and the seed set.

Identifier queries: byte-identical

ClientLive.Index and DashboardLive produce identical rankings and identical seeds before and after. Example (ClientLive.Index):

rank	before	after
1	60028.71 ClientLive.Index	60028.71 ClientLive.Index
2	60026.57 ClientLive.Index (doc)	60026.57 ClientLive.Index (doc)
3	594.28 ClientLive.Form	148.57 ClientLive.Form

(Partial-coverage neighbors like ClientLive.Form scale down as intended; rank order and seeds are unchanged.)

Natural-language query: seeds byte-identical

dashboard KPI alerts seeds ['Dashboard COI Alerts Integration', 'dashboard_live.ex', 'Dashboard (/) Rebuild Implementation Plan', 'Placement-location seam for overlap alerts', 'kpi.ex'] both before and after.

Repro 1: dashboard home page LiveView content KPI cards alerts today grid

Before (v8 with #1596):

6087.92  home()                                   <- 1-term exact collision, rank 1
 703.97  grid_view()
 703.97  gridline_size_pct()
 626.73  Home / Today Dashboard (Iris)            <- intended cluster, below gap window
 621.12  Home Today Mock
seeds: home() first; cluster recovered only via the per-term guarantee

After:

  72.94  Home / Today Dashboard (Iris)            <- intended cluster, rank 1
  71.92  Dashboard (/) Rebuild to Home-Today Mock (Design)
  63.23  home()                                   <- collision dampened 6087.9 -> 63.2 (96x)
  36.91  Home Today Mock
seeds: ['Home / Today Dashboard (Iris)', 'Dashboard (/) Rebuild to Home-Today Mock (Design)', 'home()', ...]

The relevant cluster is now inside the gap window on its own merit, not only via the per-term guarantee, and it also becomes the top-ranked answer for scored[0] consumers.

Repro 2: ClientLive.Index clients list columns

Before: three list() nodes at 4871.72 vs ClientLive.Index at 600.72 (8.1x, outside the 20% gap window; seeded only via the per-term guarantee).

After: list() drops to 194.87 (25x reduction) and ClientLive.Index at 101.52 is back inside the gap window. list() still ranks first (it is a legitimate 1-of-5 exact match), but its dominance collapses from 8.1x to 1.9x and the intended identifier is seeded through the gap window itself.

Known residual (why #1596 stays load-bearing)

A relevant node matched only via interior substrings (camelCase mid-label terms) still scores below a dampened collision: flat substring scores are ~1 x IDF per term vs exact/n^2 for the collision. The per-term seed guarantee from #1596 covers exactly this class, which is now documented in _pick_seeds' docstring alongside the coverage note. A symmetric coverage boost for the flat tier would be a larger behavioral change than this PR wants to take on; happy to explore it separately if you think it is worth it.

One more trade-off worth naming: on very long queries (10+ content terms after stopword filtering), a node matching exactly one term via prefix (100/n^2) can score below a node matching one term via substring (flat 1.0). Both are weak candidates for such queries, and the per-term guarantee still seeds each term's best node (single-term coverage == 1), but it is a place where the eval could be extended if you want stricter tier monotonicity.

Tests

• New regression test reproducing the second query: single generic term exact-matching a short leaf label hijacks seed selection in multi-term queries #1602 repro: the query contains the target's literal identifier, yet three same-directory list() leaves outrank it on base v8. Fails on v8, passes with this change, with a 30% score margin so IDF drift will not flake it.
• New no-change test pinning the exact full-coverage score (query "FooBarService" class), so identifier dominance is provably untouched.
• tests/test_serve.py: 78/78 pass. ruff check: clean. The full suite's only failures on this machine are environment-specific (local provider env vars, XAML grammar) and reproduce identically on the unpatched base.