1 ADR 0121 similarity suggestions rank above new person clusters
Forgejo Actions edited this page 2026-11-01 22:57:58 +00:00

ADR 0121: Similarity suggestions rank above new-person clusters; qualityScore stays the ranking key within each group

Status: accepted Date: 2026-11-01

Context

ADR 0103 made the worker-computed qualityScore the primary sort key of both ORDER BY branches of the discovery candidate listing (candidatesPaged), which interleaves card types in one calibrated order. Owner product decision 2026-11-01: the live carousel still front-loads the WRONG kind of decision. Confirming a similarity card (cluster_person_match / existing_person_match, UI title "Aehnelt {name}" — transliterates "Ähnelt", i.e. "resembles") is a cheap, high-value one-tap action — the person already exists — while a new-person card asks the owner to mint a new identity, which is the more expensive and more rarely-correct action on a card that may be a duplicate of an existing person. With both types scored on the same anchors, high-quality new-person clusters routinely outrank usable similarity cards in pure quality order, so the owner works through new-person cards before ever seeing the "Aehnelt X" confirmations.

Decision

Both ORDER BY branches of candidatesPaged lead with a type-first PRIMARY key: CASE WHEN c.candidate_type IN ('cluster_person_match', 'existing_person_match') THEN 0 ELSE 1 END ASC — all similarity cards rank above all new-person cards. WITHIN each group the ordering is exactly ADR 0103's quality_score DESC NULLS LAST followed by the existing per-branch tiebreaks (confidence/occurrence-count/recency for sort=confidence; confidence CASE/recency for the default branch), unchanged. Plain columns and CASE only, portable across PostgreSQL and the H2 test suite. This supersedes ONLY the ordering aspect of ADR 0103: the unified qualityScore itself (feature set, weights, transport, persistence, UI figure) stays exactly as accepted and remains the ranking key inside each group. It is a partial revival of the spec 040 "Carousel prioritization" type-first grouping that ADR 0103 removed — but with two structural guards ADR 0103's original complaint demanded: the grouping can no longer bury new-person cards under UNSCORED similarity rows, because NULLS LAST still pins the no-score populations (supersede-exempt merge cards backing live tentatives, legacy-method rows) below scored cards WITHIN the similarity group.

Consequences

The candidate listing has two ordered groups; a pool with many scored similarity cards precedes every new-person card — that is the accepted trade-off of the owner decision, and the quality ranking within groups means the BEST similarity cards surface first. The supersede-exempt NULL-score merge-card population no longer blocks the similarity group's scored rows (NULLS LAST), but unscored legacy similarity rows rank below scored similarity rows and above ALL new-person rows only by their recency/confidence tiebreaks — if a future regression re-creates a large no-score similarity pool, new-person cards sink below it again; the listing javadoc and the ADR flag this as the failure shape to watch. Tests pinning ADR 0103's interleaving are rewritten to the two-group order; embedded exact-SQL assertions are updated to the new clause. No schema, worker, transport, or migration change: the key is a read-time ORDER BY prefix only. The follow-up to revisit (outcome-based weight refit from ADR 0103) is unaffected and, once the score is predictive, the owner may re-evaluate whether the type gate should soften.