W-569: stem query suffixes so inflected words reach their keywords

[wr]

Replaces #184, which GitHub auto-closed when its base branch was deleted by the #183 squash-merge. Same commits, rebased onto main.

:ghosted: returned nothing, while :ghosting: returned 👻. The keyword was in the corpus the whole time — the query couldn't reach it. FzyScorer.score rejects any needle longer than its haystack:

guard n > 0, m > 0, n <= m else { return nil }

ghosted is 7 characters, ghost is 5. The match dies before the DP runs, so no scoring change reaches it.

What works now

:ghosted     →  👻
:deployed    →  🚀
:launching   →  🚀
:cursed      →  🤬 🖕   (via "curse")
:parties     →  🎉

Design

QueryStemmer.stems(of:) returns candidate spellings, not one canonical stem — -ing alone can't distinguish shipping (undo a doubled consonant) from celebrating (restore a dropped e) from blocking (plain trim).

It runs only when the raw query found nothing, so a query that already works keeps byte-identical ranking and pays nothing.

FuzzyMatcher.acceptedStems then decides which candidate to search, and the ordering rules are the substance of this PR — each one exists because the previous version had a concrete counterexample:

rule	without it
Drop candidates absent from the corpus	movies → movy matches 🎑 (m‑o‑v‑y in "moon_viewing_ceremony") and shadows movie → 🎥
Exact corpus term beats a mere prefix	skies → skie prefixes "skier", so ⛷️ wins and sky is never tried
Then prefer the longer candidate	hoped → hop returns rabbits and shadows hope; bared → bar shadows bare
-ies ranks above the generic trims, -ied below	skies is sky + s (the plural of ski is skis), but skied is ski + ed — one rule for both gets one of them wrong

stemMatch is a plain character compare with no DP, so gating costs far less than the fzy pass it guards.

Cost

Bounded at three cheap prefix sweeps plus one fuzzy sweep, and only on a query that already returned nothing. Queries that match directly are untouched.

Test plan

• 297 tests pass
• QueryStemmerTests — 10 cases over the rules: plain stems, -ies/-ied → y, restored e, consonant doubling, press never becoming pres, uninflected queries yielding nothing, no stem below 3 characters
• FuzzyMatcherTests.stemsAreOrderedByHowSolidlyTheyExist — the ordering table above, including both skies and skied
• inventedStemDoesNotShadowTheRealOne, stemsThatAreNotWordsYieldNothing, longerStemChangesWhatSurfaces, stemmingOnlyRunsWhenTheQueryFoundNothing

Review

Three rounds of adversarial review found four real ordering defects (movies, untied, bared/hoped, skied); all are fixed and covered by tests. A fifth reported case, copses → 🚓, was not actioned: copse is absent from the corpus in every form, so there is no correct result to return.

Refs W-569

[linear-code]

W-569

[wr-claude-reviewer]

Clean implementation. The design decisions are well-reasoned — gating on empty results means the hot path is untouched, and ranking by corpus existence before length prevents the movies → movy → 🎑 shadow problem. The commit series telling the story of each ordering rule as it was added (with the counterexample it fixed) is exactly the right level of detail.

A few things I traced through explicitly:

• stemMatch returning .exact early on the first exact hit is correct; it continues scanning after .prefix because an exact match may still exist later in the pool.
• The undoubled guard (stem.count > minStem, not >=) ensures the result is ≥ 3 chars after dropping the doubled consonant — correct.
• The hasSuffix(["s","s"]) guard on trim("s") correctly blocks press → pres without blocking stars → star (only one trailing s).
• The -ied rule going last (after all trim calls) means corpus-exact results from the direct trims always appear in acceptedStems before the -ied reconstruct, even when both are present — the skied ordering is correct.
• Swapping "cursed" out of queryWithNoRealMatchReturnsNothing is the right call; it now returns results via "curse".

Nit: QueryStemmer.swift imports Foundation but nothing in the file requires it — all types and methods ([Character], Array, String, !"aeiou".contains(last)) are stdlib. Minor, zero runtime impact, but can be dropped.