fix(retain): bound entity-resolution candidate scoring (#3211)

[nicoloboschi]

Fixes #3211.

The symptom

Every fuzzy candidate is scored with difflib.SequenceMatcher in a synchronous loop on the event-loop thread, and candidate volume per query text was bounded only by what the trigram probe returned. On a bank whose index is polluted by many near-identical names, one resolution batch becomes minutes of uninterrupted CPU: /health cannot answer, the orchestrator kills the worker mid-op, and the requeued op wedges the next one.

Reproduction

A 100-mention batch driven through _resolve_from_candidates with mock candidates, alongside a 10 ms heartbeat task standing in for the health endpoint:

candidate rows	before	after
200k	2.13 s @ 99% CPU, 0 heartbeats, one 2.12 s stall	0.27 s, max stall 11 ms
1M	10.61 s @ 99% CPU, 0 heartbeats, one 10.6 s stall	0.38 s, max stall 14 ms

Cost scales linearly with candidates, which is how a real polluted bank reaches minutes.

The fix

1. Cap candidates per query text in SQL, ranked by the similarity score the probe already computes — CROSS JOIN LATERAL (… ORDER BY similarity(…) DESC LIMIT $3) on PG, ROW_NUMBER() OVER (PARTITION BY q.query_text ORDER BY JARO_WINKLER …) on Oracle. New HINDSIGHT_API_RETAIN_ENTITY_RESOLUTION_MAX_CANDIDATES, default 200.
2. Yield to the event loop every 256 scored candidates, so responsiveness does not depend on the cap being configured sanely.
3. Backstop truncation in _resolve_from_candidates with an O(1)-per-candidate ordering key, for candidate sets built without a DB score (the full strategy's Python substring matching).

The new PG query was verified against a real PostgreSQL + pg_trgm on a throwaway instance: the cap is honoured per query text and the best trigram match ranks first.

Behaviour change beyond the cap

The PG rewrite drops SELECT DISTINCT ON (e.id), which deduplicated across query texts: an entity matching two mentions in the same batch was silently dropped as a candidate for one of them. On a 2-text / 2001-entity fixture the old query returned 1004 + 997 rows instead of 2001 each. The LATERAL form dedups per (query text, entity), which is what the grouping downstream expects.

Resolution results are otherwise unchanged for any mention with ≤ 200 candidates. Above that, candidates ranked below the top 200 by trigram similarity are no longer scored — they could previously win on the co-occurrence/temporal boost, but a match that far down the similarity ranking is noise.

Tests

hindsight-api-slim/tests/test_entity_resolver_candidate_cap.py — scoring is capped at the configured maximum, truncation keeps the exact match, a concurrent task keeps getting scheduled during a wide batch (the regression the issue asks for), and both dialects' SQL carries the cap.