1 ADR 0107 carousel suggestions named targets
Forgejo Actions edited this page 2026-10-08 20:17:06 +00:00

ADR 0107: Carousel suggestions and merge cards require a named target

Status: accepted Date: 2026-10-08

Context

Suggestion cards of type cluster_person_match and existing_person_match point at an existing class instance, and that target may be UNNAMED (display_name NULL or blank). Unnamed instances are uncuration debt — a group the owner has not identified yet — but the suggestions carousel renders them with live rerank titles ('similar to '), which disguises the unnamed target as curated. The owner read those cards as curated suggestions and decided on 2026-10-08 that they must not appear at all until the target has a name. The same reasoning applies to merge cards: proposing a merge into an instance whose only label is the display fallback 'Unnamed' is noise. This is a product decision, not a defect — no state is wrong, only what is worth showing.

Decision

Filter at READ TIME, in exactly three places: candidatesPaged (the shared fetchCandidateRows window that backs both the paged and the legacy unbounded listing) and countCandidates both gain the predicate (c.existing_instance_id IS NULL OR NULLIF(TRIM(ci.display_name), '') IS NOT NULL), byte-identical in both statements so totalRemaining stays consistent with the visible cards; mergeSuggestion drops instance rows with a blank/NULL display_name before pairing, so an unnamed instance is never a merge party while named x named pairs are untouched. new_person_cluster rows keep existing_instance_id NULL and stay fully visible. Because nothing is persisted, a card RETURNS THE MOMENT its target instance is named — no backfill, no re-run, no worker change, no migration, no schema change. The pickers (personRanking, mergeTargetRankings, suggestSimilarInstances) get NO new gate and keep their full candidate sets including unnamed instances: the owner explicitly wants faces still attachable to unnamed groups through the assignment dialogs, so un-named group growth remains possible (suggestSimilarInstances' pre-existing blank-query fallback, which already listed only named instances, is untouched). Sort order, scoring and the includeTotal contract are unchanged; the display fallback 'Unnamed' stays in the code and is simply never suggested.

Consequences

The suggestions carousel and the domain candidate listing stop showing match cards against uncuration-debt targets, so every visible match card now names a real person — and naming an instance immediately brings its cards back (read-time, so the fix is self-healing and reversible per instance). Merge suggestions never propose 'Unnamed' as a party, which can reduce the number of merge cards on libraries with many untitled groups until those are named. totalRemaining shrinks with the same predicate, so the carousel's has-more walk and pool-exhaustion heuristic stay truthful. Because a stash can only ever be an UNNAMED instance (stashInstance refuses named ones and a rename clears stashed_at), candidates targeting a stash — the cards spec 047 deliberately re-surfaced — are hidden in practice under this rule; their state stays pending and decidable by id, and they return if the target is ever named, so this overlays spec 047 rather than amending it. The pickers keep their full candidate sets, so the assignment dialogs can still create or extend unnamed groups — the two surfaces deliberately diverge (listing is curated, picking is complete). Worker emission, candidate state machine and persistence are untouched: hidden cards remain pending and decidable by id. Tests cover the hide (blank and NULL target names, both sort orders), the return-after-naming property, the new_person_cluster regression, and mergeSuggestion skipping an unnamed party.