fix(discovery): ranking endpoints honor pinned/accepted representative thumbnails #1092

Merged
chris merged 1 commit from fix/ranking-thumbnail-representative into main 2026-10-10 20:37:39 +02:00
Owner

Symptom

The people-picker dropdown ("choose another person") in the discovery suggestions UI shows the newest tentative face of a person instead of the user-selected / confirmed thumbnail. Introduced behaviorally by #1088 (picker reuses the card's prefetched ranking rows) + #1089 (ranking latency fix made the fast path reliable): the ranking path now wins where it used to time out into the fallback. The SQL itself predates #1089.

Root cause

All three ranking endpoints (personRanking, mergeTargetRankings, mergeSuggestion) re-derived thumbnail_url with a subquery that ignores class_instances.representative_occurrence_id and orders by newest of EITHER state:

WHERE cio3.state IN ('accepted','tentative')
ORDER BY COALESCE(cio3.accepted_at, cio3.created_at) DESC LIMIT 1

So a newer tentative (auto-assigned, unconfirmed) face outranked the pinned or accepted representative.

Fix shape

One shared constant REPRESENTATIVE_FACE_THUMBNAIL_SUBQUERY interpolated into the same three statements (still one statement each), selecting:

  1. Pinned representative first — ORDER BY CASE WHEN cio3.id = ci.representative_occurrence_id THEN 0 ELSE 1 END (the pin is accepted-only by construction, see setRepresentativeOccurrence);
  2. Accepted-first — CASE WHEN cio3.state='accepted' THEN 0 ELSE 1 END, recency only as tiebreaker within a state;
  3. Named instances never serve a tentative crop — WHERE-level exclusion mirroring ISSUE-095 (ClassInstanceService.representativeEnrichmentForPeople), falling back to null; unnamed instances keep the tentative crop as last-resort fallback (accepted ranks first).

Thumbnail selection only: scores, ADR 0109 multi-representant ranking semantics, occurrence counts, row sets, response DTO shapes and the #1089 batching/deferral statement budget are untouched. No schema changes.

Test evidence

Regression tests in ClassInstanceDiscoveryServiceTest (new Fixture helpers insert face annotations WITH face_thumbnail derived assets, occurrences with explicit state + timestamp offsets, and pin occurrences):

Test Failing-before (unmodified main) After fix
pinned representative beats newer tentative face FAIL (returned tentative URL) pass
accepted beats newer tentative (no pin) FAIL (returned tentative URL) pass
named person, only tentative → no tentative crop FAIL (returned tentative URL) pass
unnamed person, only tentative → tentative fallback kept pass (pins preserved behavior) pass
mergeTargetRankings same rule (pinned + accepted targets) FAIL pass
mergeSuggestion same rule (pinned + accepted pair) FAIL pass

Failing-before proof produced by running the final test shapes with only the production change stashed: 11 tests completed, 10 failed (each assertion runs twice in the Gradle console; 5 of 6 distinct tests failed, the 6th pins intentionally-preserved behavior).

Suite results (rtk ./gradlew :apps:api:test):

  • ClassInstanceDiscoveryServiceTest: 297 tests, 0 failures, 0 errors (incl. personRankingRunsConstantNumberOfStatementsRegardlessOfFaceCount 50-faces ≤ 7 statements, and personRankingDefersPersonEmbeddingScanByComposerCoverageNotRepPresence)
  • full module: 144 suites, 1678 tests, 0 failures, 0 errors (9 pre-existing skips in unrelated suites)

Residual risk

KNOWN_ISSUES.md ISSUE-112 (low): suggestSimilarInstances (a different endpoint — the /instances/similar search, not the three pickers) carries the same newest-of-either-state subquery in three places; left untouched to keep this PR thumbnail-selection-only for the picker regression.

Branch based on latest origin/main (0461b5fc). No merge performed, no docker/deploy actions.

## Symptom The people-picker dropdown ("choose another person") in the discovery suggestions UI shows the **newest tentative** face of a person instead of the user-selected / confirmed thumbnail. Introduced behaviorally by #1088 (picker reuses the card's prefetched ranking rows) + #1089 (ranking latency fix made the fast path reliable): the ranking path now wins where it used to time out into the fallback. The SQL itself predates #1089. ## Root cause All three ranking endpoints (`personRanking`, `mergeTargetRankings`, `mergeSuggestion`) re-derived `thumbnail_url` with a subquery that ignores `class_instances.representative_occurrence_id` and orders by newest of EITHER state: ```sql WHERE cio3.state IN ('accepted','tentative') ORDER BY COALESCE(cio3.accepted_at, cio3.created_at) DESC LIMIT 1 ``` So a newer tentative (auto-assigned, unconfirmed) face outranked the pinned or accepted representative. ## Fix shape One shared constant `REPRESENTATIVE_FACE_THUMBNAIL_SUBQUERY` interpolated into the same three statements (still one statement each), selecting: 1. **Pinned representative first** — `ORDER BY CASE WHEN cio3.id = ci.representative_occurrence_id THEN 0 ELSE 1 END` (the pin is accepted-only by construction, see `setRepresentativeOccurrence`); 2. **Accepted-first** — `CASE WHEN cio3.state='accepted' THEN 0 ELSE 1 END`, recency only as tiebreaker within a state; 3. **Named instances never serve a tentative crop** — WHERE-level exclusion mirroring ISSUE-095 (`ClassInstanceService.representativeEnrichmentForPeople`), falling back to null; **unnamed** instances keep the tentative crop as last-resort fallback (accepted ranks first). Thumbnail selection only: scores, ADR 0109 multi-representant ranking semantics, occurrence counts, row sets, response DTO shapes and the #1089 batching/deferral statement budget are untouched. No schema changes. ## Test evidence Regression tests in `ClassInstanceDiscoveryServiceTest` (new Fixture helpers insert face annotations WITH `face_thumbnail` derived assets, occurrences with explicit state + timestamp offsets, and pin occurrences): | Test | Failing-before (unmodified main) | After fix | |---|---|---| | pinned representative beats newer tentative face | FAIL (returned tentative URL) | pass | | accepted beats newer tentative (no pin) | FAIL (returned tentative URL) | pass | | named person, only tentative → no tentative crop | FAIL (returned tentative URL) | pass | | unnamed person, only tentative → tentative fallback kept | pass (pins preserved behavior) | pass | | mergeTargetRankings same rule (pinned + accepted targets) | FAIL | pass | | mergeSuggestion same rule (pinned + accepted pair) | FAIL | pass | Failing-before proof produced by running the final test shapes with only the production change stashed: `11 tests completed, 10 failed` (each assertion runs twice in the Gradle console; 5 of 6 distinct tests failed, the 6th pins intentionally-preserved behavior). Suite results (`rtk ./gradlew :apps:api:test`): - `ClassInstanceDiscoveryServiceTest`: **297 tests, 0 failures, 0 errors** (incl. `personRankingRunsConstantNumberOfStatementsRegardlessOfFaceCount` 50-faces ≤ 7 statements, and `personRankingDefersPersonEmbeddingScanByComposerCoverageNotRepPresence`) - full module: **144 suites, 1678 tests, 0 failures, 0 errors** (9 pre-existing skips in unrelated suites) ## Residual risk KNOWN_ISSUES.md ISSUE-112 (low): `suggestSimilarInstances` (a different endpoint — the /instances/similar search, not the three pickers) carries the same newest-of-either-state subquery in three places; left untouched to keep this PR thumbnail-selection-only for the picker regression. Branch based on latest origin/main (0461b5fc). No merge performed, no docker/deploy actions.
fix(discovery): ranking endpoints honor pinned/accepted representative thumbnails
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 4s
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 9m53s
9e11330dc9
The people-picker ranking endpoints (personRanking, mergeTargetRankings,
mergeSuggestion) derived representativePreviewUrl with a subquery that
picked the NEWEST face of either state (accepted OR tentative) and
ignored class_instances.representative_occurrence_id. After #1088
(frontend reuses the prefetched ranking rows in the picker) and #1089
(ranking latency fix made the fast path reliable), the newest tentative
face of a person started surfacing as the picker preview instead of the
user-selected/confirmed thumbnail.

The thumbnail subquery (shared now via
REPRESENTATIVE_FACE_THUMBNAIL_SUBQUERY, interpolated into all three
statements) mirrors the people-page rule (ISSUE-095,
ClassInstanceService.representativeEnrichmentForPeople):

1. pinned representative_occurrence_id first (accepted-only by
   construction, see setRepresentativeOccurrence);
2. otherwise accepted-first (CASE state='accepted' THEN 0 ELSE 1 END),
   recency only breaks ties within a state;
3. named instances never serve a tentative crop (WHERE-level exclusion,
   null fallback); unnamed instances keep the tentative crop as
   last-resort fallback (accepted ranks first).

Thumbnail selection only: scores, ADR 0109 ranking semantics,
occurrence counts, row sets, response DTOs and the #1089 batching/
deferral statement budget are unchanged (CountingJdbcClient guards
still pass). Regression tests fail on unmodified main (5 of 6; the
unnamed-fallback test pins preserved behavior and passed before too).
KNOWN_ISSUES.md: ISSUE-112 records the same bug class remaining in
suggestSimilarInstances (out of scope here).
chris merged commit 37dab11ab5 into main 2026-10-10 20:37:39 +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!1092
No description provided.