fix(vocab): stop reading the whole vocabulary for similar terms (#277)

[HugoFara]

Fixes #277.

Root cause

FindSimilarTerms::execute() selected every term of the language into PHP and built a LetterPairProfile for each — letter pairs plus phonetic normalisation — before the 0.33 threshold threw almost all of them away. Fine for a hand-built vocabulary; fatal for one seeded from a dictionary import. The reported fatal at PreparedStatement.php:209 is the row-accumulation loop in fetchAll(), exactly as @sarahmccuan guessed in the issue.

Both branches of GET /api/v1/terms/for-edit reach it through getSimilarTermsForEdit(), so every word click paid for it.

Fix

The admission test moves into SQL, so the rows that come back are the ones that stood a chance. Two ways in, matching the two ways rankByCoverage() admits a candidate:

• Word family — WoLemmaLC = ? OR WoTextLC = ?, mirroring sharesWordFamily(), so irregular forms still get in whatever they score on spelling.
• Letter-pair overlap — Dice is 2|A∩B| / (|A|+|B|), so clearing a threshold t needs |A∩B| >= t(|A|+|B|)/2; dropping the candidate's own pair count, unknown until it is read, leaves the weaker t|B|/2 that a sum of LIKE tests can check. A term pair never spans a space, so it belongs to a candidate's pair set exactly when it is a substring of the candidate.

A LIMIT backs that up, with the scan ordered by shared-pair count so a vocabulary large enough to reach the cap loses its weakest matches rather than whichever have the lowest WoID. The rows then go back into WoID order before ranking, because rankByCoverage() breaks ties on whichever candidate it saw first — below the cap the results are unchanged.

QueryBuilder::whereRaw() and selectRaw() gained an optional $bindings array. The prefilter needs placeholders, and hand-writing the SQL would have gone around the builder's automatic WoUsID multi-user scoping. Both signatures stay backward compatible — the one existing whereRaw() caller passes SQL only.

Measured, on a seeded 200k-term vocabulary

	before	after
peak memory	174 MB	8 MB
latency	0.8–1.2 s	0.2–0.5 s
suggestions	—	identical on all 5 probes

At PHP's default memory_limit=128M the old path reproduces the reported Allowed memory size ... exhausted; the new one returns its 10 suggestions at a 4 MB peak.

Known narrowing

The bound covers the character half of the score. A term whose spelling has almost nothing in common with the searched one but whose pronunciation does is no longer admitted on phonetics alone. With the defaults (minRanking = 0.33, phoneticWeight = 0.3) the phonetic side alone tops out at 0.30 and cannot clear the threshold anyway. It is documented on buildCandidateFilter().

Tests

Eight new tests: five for the prefilter — including a property test that it never drops a term the ranking would keep, plus word-family admission, the threshold scaling with term length, the short-term short circuit, and %/_ escaping — and two for whereRaw() binding order.

Psalm 0 errors, PHPCS 0 errors and 0 warnings, PHPUnit 9098 pass. Live checks also confirm 100%_off returns nothing rather than erroring, and a term too short for a letter pair short-circuits without a query.