fix(discovery): carousel suggestions and merge cards require named targets #1077

Merged
chris merged 1 commit from fix/suggestions-require-named-targets into main 2026-10-08 22:16:56 +02:00
Owner

TL;DR: Owner decision 2026-10-08 — carousel suggestion cards (cluster_person_match / existing_person_match) and merge cards now appear only when the target instance is NAMED (display_name non-blank). Pure read-time filter in candidatesPaged, countCandidates and mergeSuggestion: nothing is persisted, so naming the instance brings the cards straight back. new_person_cluster (no target at all) stays fully visible, the pickers stay complete, worker/DB untouched. New ADR 0107.

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 mergeSuggestion keine 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 == null und die Legacy-Wrapper), direkt nach der bestehenden lifecycle_state-Bedingung; der LEFT JOIN ci (owner/domain/class gematcht) existierte schon:

AND (c.existing_instance_id IS NULL OR ci.lifecycle_state = 'active')
-- Owner decision 2026-10-08 (ADR 0107): match cards surface ONLY when the
-- target instance is NAMED … read-time: a card returns the moment the
-- instance is named.
AND (c.existing_instance_id IS NULL OR NULLIF(TRIM(ci.display_name), '') IS NOT NULL)

new_person_cluster trägt existing_instance_id IS NULL → bleibt vollständig sichtbar; TRIM deckt Leerstring und nur-Whitespace-Namen ab; bei nicht matchendem Join wird wie bei lifecycle_state ohnehin ausgeschlossen.

2. countCandidates — byte-identische Kopie derselben Zeile, damit totalRemaining exakt 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 der instanceRows, vor dem Pairing):

.stream()
.filter(row -> text(row.get("display_name")) != null)   // text() == null für NULL/blank
.toList();

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, mergeTargetRankings und suggestSimilarInstances sind 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: suggestSimilarInstances listet in seinem Blank-Query-Fallback („fall back to listing named instances", eine SQL-Zeile display_name IS NOT NULL AND display_name <> '') nur Benanntes, seine Similarity- und Name-Query-Pfade bleiben vollständig; matchCandidateToExistingInstance verlangt 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

stashInstance erlaubt nur unbenannte Instanzen (benannt → 400) und ein Rename räumt stashed_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 bleibt pending und 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 == 0 obwohl 3 Rows existieren, identisch für den limit == null-Pfad.
  • namingTheTargetBringsTheHiddenMatchCardBackOnRead — (b) Read-Time: vor dem Rename hidden + totalRemaining == 1 (bei limit=1, 2 sichtbare Rows), nach UPDATE 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 → null statt „in Unnamed verschmelzen".

Angepasste Fixtures (4 bestehende Tests, dokumentiert):

  • mergeSuggestionExcludesStashedInstances — beide Parteien bekommen Namen (sonst keine Parteien mehr); stashed_at wird direkt per SQL gesetzt, weil die public stashInstance benannte 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 danach isZero().
  • 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 auf display_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).
  • Web Playwright (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 candidatesPaged

Genau drei: GET /discovery/class-instance-candidates, GET /discovery/domains/{domainKey}/class-instance-candidates (beide dieselbe Listing-Fläche, Web-Client lib/api/discovery.ts) und die Legacy-Wrapper candidates/pendingCandidates, die nur noch von Tests aufgerufen werden. Kein überraschender Consumer (die constrained*Density*-Methoden in ClassInstanceServicehaben Parameter namenscandidates, keine Service-Methode — Falsch-Positiv der Caller-Suche). countCandidateshat ausschließlichcandidatesPaged` als Caller.

> **TL;DR:** Owner decision 2026-10-08 — carousel suggestion cards (`cluster_person_match` / `existing_person_match`) and merge cards now appear **only when the target instance is NAMED** (`display_name` non-blank). Pure **read-time** filter in `candidatesPaged`, `countCandidates` and `mergeSuggestion`: nothing is persisted, so **naming the instance brings the cards straight back**. `new_person_cluster` (no target at all) stays fully visible, **the pickers stay complete**, worker/DB untouched. New ADR `0107`. ## 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 `mergeSuggestion` keine 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 == null` und die Legacy-Wrapper), direkt nach der bestehenden `lifecycle_state`-Bedingung; der LEFT JOIN `ci` (owner/domain/class gematcht) existierte schon: ```sql AND (c.existing_instance_id IS NULL OR ci.lifecycle_state = 'active') -- Owner decision 2026-10-08 (ADR 0107): match cards surface ONLY when the -- target instance is NAMED … read-time: a card returns the moment the -- instance is named. AND (c.existing_instance_id IS NULL OR NULLIF(TRIM(ci.display_name), '') IS NOT NULL) ``` `new_person_cluster` trägt `existing_instance_id IS NULL` → bleibt vollständig sichtbar; `TRIM` deckt Leerstring **und** nur-Whitespace-Namen ab; bei nicht matchendem Join wird wie bei `lifecycle_state` ohnehin ausgeschlossen. **2. `countCandidates`** — byte-identische Kopie derselben Zeile, damit `totalRemaining` exakt 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 der `instanceRows`, vor dem Pairing): ```java .stream() .filter(row -> text(row.get("display_name")) != null) // text() == null für NULL/blank .toList(); ``` 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`, `mergeTargetRankings` und `suggestSimilarInstances` sind **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:* `suggestSimilarInstances` listet in seinem **Blank-Query-Fallback** („fall back to listing named instances", eine SQL-Zeile `display_name IS NOT NULL AND display_name <> ''`) nur Benanntes, seine Similarity- und Name-Query-Pfade bleiben vollständig; `matchCandidateToExistingInstance` verlangt 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 `stashInstance` erlaubt nur unbenannte Instanzen (benannt → 400) und ein Rename räumt `stashed_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 bleibt `pending` und 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 == 0` obwohl 3 Rows existieren, identisch für den `limit == null`-Pfad. - `namingTheTargetBringsTheHiddenMatchCardBackOnRead` — (b) Read-Time: vor dem Rename hidden + `totalRemaining == 1` (bei `limit=1`, 2 sichtbare Rows), nach `UPDATE 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 → `null` statt „in Unnamed verschmelzen". **Angepasste Fixtures (4 bestehende Tests, dokumentiert):** - `mergeSuggestionExcludesStashedInstances` — beide Parteien bekommen Namen (sonst keine Parteien mehr); `stashed_at` wird direkt per SQL gesetzt, weil die public `stashInstance` benannte 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 danach `isZero()`. - `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 auf `display_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). - Web Playwright (`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 `candidatesPaged` Genau drei: `GET /discovery/class-instance-candidates`, `GET /discovery/domains/{domainKey}/class-instance-candidates` (beide dieselbe Listing-Fläche, Web-Client `lib/api/discovery.ts`) und die Legacy-Wrapper `candidates`/`pendingCandidates`, die nur noch von Tests aufgerufen werden. **Kein überraschender Consumer** (die `constrained*Density*-Methoden in `ClassInstanceService` haben Parameter namens `candidates`, keine Service-Methode — Falsch-Positiv der Caller-Suche). `countCandidates` hat ausschließlich `candidatesPaged` als Caller.
fix(discovery): carousel suggestions and merge cards require named targets
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 2s
Build and Deploy / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 5m16s
e350244edb
Owner decision 2026-10-08 (ADR 0107): cluster_person_match /
existing_person_match cards and merge cards surface only when the target
instance is NAMED (display_name non-blank). Read-time filter in
fetchCandidateRows, countCandidates (byte-identical predicate) and
mergeSuggestion's instanceRows; new_person_cluster unaffected, pickers
untouched, no worker/migration change — naming brings cards back.
chris merged commit b89ea39148 into main 2026-10-08 22:16:56 +02:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
chris/memories!1077
No description provided.