fix(discovery): carousel suggestions and merge cards require named targets #1077
Loading…
Reference in a new issue
No description provided.
Delete branch "fix/suggestions-require-named-targets"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Owner-Entscheidung (2026-10-08)
Unbenannte Instanzen sind unkuratiert — eine Gruppe, die der Owner noch nicht identifiziert hat. Die UI rendert solche Karten derzeit mit Live-Rerank-Titeln („similar to <benannter Person>"), was das unbenannte Ziel als kuratiert verkleidet; der Owner hat das als kuratierte Vorschläge missverstanden. Produktregel: Bis die Instanz einen Namen trägt, ist sie keine Vorschlag-Karte wert. Aus demselben Grund schlägt
mergeSuggestionkeine Verschmelzung in „Unnamed" vor.Begründung im ADR:
docs/adr/0107-carousel-suggestions-named-targets.json(Schema wie 0106).Änderung (nur
apps/api/…/ClassInstanceDiscoveryService.java)1. Page-Query —
fetchCandidateRows(gemeinsame Basis für den gepaggerten Pfad,limit == nullund die Legacy-Wrapper), direkt nach der bestehendenlifecycle_state-Bedingung; der LEFT JOINci(owner/domain/class gematcht) existierte schon:new_person_clusterträgtexisting_instance_id IS NULL→ bleibt vollständig sichtbar;TRIMdeckt Leerstring und nur-Whitespace-Namen ab; bei nicht matchendem Join wird wie beilifecycle_stateohnehin ausgeschlossen.2.
countCandidates— byte-identische Kopie derselben Zeile, damittotalRemainingexakt die sichtbaren Karten zählt (Seite und Total bleiben konsistent,poolExhausted/Short-Page-Heuristik des Carousels bleiben wahr).3.
mergeSuggestion— unbenannte Instanzen scheiden als Merge-Parteien aus (Filter beim Sammeln derinstanceRows, vor dem Pairing):Die Anzeige-Fallback
'Unnamed'(DomainSuggestionsCarousel.svelte) bleibt im Code — er wird nur nie mehr vorgeschlagen. Andere Endpunkte wurden nicht angefasst.4. Pickers bleiben vollständig:
personRanking,mergeTargetRankingsundsuggestSimilarInstancessind ungeändert (bewusste Owner-Entscheidung: kein Gate in Pickern — Wachstum unbenannter Gruppen über die Zuordnungs-Dialoge bleibt möglich). Vorbefund, nicht Teil dieses PRs und nicht verändert:suggestSimilarInstanceslistet in seinem Blank-Query-Fallback („fall back to listing named instances", eine SQL-Zeiledisplay_name IS NOT NULL AND display_name <> '') nur Benanntes, seine Similarity- und Name-Query-Pfade bleiben vollständig;matchCandidateToExistingInstanceverlangt in seiner Anchor-Query ebenfalls einen Namen. Beides bestand vor diesem PR.Kein Worker-Change, keine Migration, keine Sortier-/Score-Änderung, kein KNOWN_ISSUES-Eintrag (Produktentscheidung, kein Bug).
Read-time-Verhalten
Es wird nichts persistiert und kein Zustand geschrieben: die Karte kehrt zurück, sobald die Instanz benannt wird (kein Backfill, kein Worker-Lauf). Umgekehrt verschwindet eine bereits sichtbare Karte, wenn ihre Ziel-Instanz leer benannt wird. Test (b) belegt beides über denselben Fixture-Row.
Konsequenz, die der Owner kennen sollte: Stash-Ziele
stashInstanceerlaubt nur unbenannte Instanzen (benannt → 400) und ein Rename räumtstashed_at— ein Stash ist definitionsgemäß immer unbenannt. Die Folge: Karten, die auf einen Stash zielen (genau die Spec-047-Regel „consensus-failed/beyond-band stash cards surface"), sind nach ADR 0107 im Live-Betrieb immer verborgen; der Candidate bleibtpendingund per id entscheidbar, und sobald ein Ziel je benannt wird, kehrt die Karte zurück. Spec 047 wird dadurch nicht geändert, nur durch die neuere Owner-Regel überlagert — die betroffenen Tests decken beide Regeln nun getrennt ab (siehe Testbefund).Testbefund
Neu (5 Tests,
ClassInstanceDiscoveryServiceTest):pagedListingHidesMatchCardsWithUnnamedTargetsAndCountsThemOut— (a) NULL- und blank-Ziel in beiden Sortierungen (null/confidence) hidden, benanntes Ziel sichtbar,totalRemaining == 0obwohl 3 Rows existieren, identisch für denlimit == null-Pfad.namingTheTargetBringsTheHiddenMatchCardBackOnRead— (b) Read-Time: vor dem Rename hidden +totalRemaining == 1(beilimit=1, 2 sichtbare Rows), nachUPDATE display_name = ' Rikke ') alle 3 sichtbar +totalRemaining == 2— der Count sieht die Zeile also im selben Read.newPersonClusterWithoutTargetInstanceStaysVisible— (c) Regression inkl. Fixture-Guard (existing_instance_id IS NULL), beide Sortierungen.mergeSuggestionSkipsUnnamedAndBlankParties— (d) NULL- und blank-Partei sind näher (d = 0) als das einzige benannte Paar (d = 0,02) und würden ohne Filter deterministisch gewinnen; Ergebnis ist exakt {Alice, Bob}.mergeSuggestionReturnsNullWhenOnlyOneSideIsNamed— (d) nur eine benannte Partei →nullstatt „in Unnamed verschmelzen".Angepasste Fixtures (4 bestehende Tests, dokumentiert):
mergeSuggestionExcludesStashedInstances— beide Parteien bekommen Namen (sonst keine Parteien mehr);stashed_atwird direkt per SQL gesetzt, weil die publicstashInstancebenannte Instanzen zu Recht ablehnt. Testinhalt (Stash ≠ Paarung) unverändert.carouselSurfacesCandidatesTargetingStashedInstances— erweitert: (1) unbenannter Stash → Karte hidden (Live-Realität, ADR 0107), (2) Shadow direkt per SQL benannt → Karte sichtbar (Spec 047 weiterhin gedeckt),totalRemaining-Parität danachisZero().ambiguousCandidateIsNotAutoAssignedIntoStashedShadow— Shadow nach dem Stash direkt SQL-benannt, damit die Spec-047-Listing-Assertion erreichbar bleibt (Rest des Tests unverändert).stashAbsorptionRequiresCoreConsensusWithinBand— gleiches SQL-Naming des Shadows; die Absorption selbst schaut nie aufdisplay_name.Ergebnisse (lokal, dieser Branch):
rtk ./gradlew :apps:api:test --tests '*ClassInstanceDiscovery*'→ grün (275 Tests).rtk ./gradlew :apps:api:test(volle Suite) →BUILD SUCCESSFUL in 4m 49s, 142 Suites / 1632 Tests / 0 Failures / 0 Errors (9 Skips, vorhandene).discovery-review,discovery-instance-tentative,instance-split-move, desktop+mobile) → 220 passed, 0 failed — ohne Fixture-Anpassung, weil die Specs die API vollständig mocken und kein UI-Code geändert wurde (kein Web-Fixture-Change nötig).Consumer von
candidatesPagedGenau drei:
GET /discovery/class-instance-candidates,GET /discovery/domains/{domainKey}/class-instance-candidates(beide dieselbe Listing-Fläche, Web-Clientlib/api/discovery.ts) und die Legacy-Wrappercandidates/pendingCandidates, die nur noch von Tests aufgerufen werden. Kein überraschender Consumer (dieconstrained*Density*-Methoden inClassInstanceServicehaben Parameter namenscandidates, keine Service-Methode — Falsch-Positiv der Caller-Suche).countCandidateshat ausschließlichcandidatesPaged` als Caller.