feat(api): canonical representative thumbnail per ADR 0114 #1277

Merged
chris merged 3 commits from feat/rep-thumb-api into main 2026-10-17 01:21:43 +02:00
Owner

Single canonical representative-thumbnail entry point (ClassInstanceRepresentativeService): manual pin (manual_selection provenance) -> medoid of the largest cluster (persisted medoid_face_annotation_id V170 for people, one embedding cluster over class_occurrence_embeddings elsewhere) -> deterministic terminal ladder (accepted-first, ADR 0103 quality else confidence, captured recency, id). All former per-service ladder copies routed through it (listing, detail, people enrichment, ranking preview URLs with ISSUE-140 batching kept, relations, collaborative bridge owner reps, self-person avatar, face-picker marker); manual pins now honored on listings that ignored them; auto-pin removed; setRepresentativeMedia resolves canonical occurrence on the chosen media; re-pinning idempotently re-enqueues the generate_discovery_thumbnail crop; thumbnail pointer accepts fail closed unless the payload occurrence is the current canonical representative; missing-crop sweeps enqueue canonical crops only (payload occurrenceId). Depends on the worker PR shipping medoidFaceAnnotationId but is absent-legal until then (older workers fall to the terminal ladder). rtk :apps:api:test 2164 tests 0 failures.

Single canonical representative-thumbnail entry point (ClassInstanceRepresentativeService): manual pin (manual_selection provenance) -> medoid of the largest cluster (persisted medoid_face_annotation_id V170 for people, one embedding cluster over class_occurrence_embeddings elsewhere) -> deterministic terminal ladder (accepted-first, ADR 0103 quality else confidence, captured recency, id). All former per-service ladder copies routed through it (listing, detail, people enrichment, ranking preview URLs with ISSUE-140 batching kept, relations, collaborative bridge owner reps, self-person avatar, face-picker marker); manual pins now honored on listings that ignored them; auto-pin removed; setRepresentativeMedia resolves canonical occurrence on the chosen media; re-pinning idempotently re-enqueues the generate_discovery_thumbnail crop; thumbnail pointer accepts fail closed unless the payload occurrence is the current canonical representative; missing-crop sweeps enqueue canonical crops only (payload occurrenceId). Depends on the worker PR shipping medoidFaceAnnotationId but is absent-legal until then (older workers fall to the terminal ladder). rtk :apps:api:test 2164 tests 0 failures.
docs(adr): 0114 representative thumbnail = manual pin or medoid of largest cluster
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 3s
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build Android CI image (push) Has been skipped
Build and Deploy / Run scoped PR tests (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 plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Android unit tests and debug APK (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
5df46e40dc
One shared ClassInstanceRepresentativeService resolves every class-instance
representative (manual manual_selection pin -> medoid of largest cluster [persisted
ADR 0109 rep rows with medoid face id, else one embedding cluster over
class_occurrence_embeddings] -> deterministic terminal ladder). All surfaces
routed through it: generic instances() listing (now HONORS the manual pin),
instance detail views, people browse enrichment, personRanking /
mergeTargetRankings / mergeSuggestion / suggestSimilarInstances preview URLs
(ISSUE-140 batching kept, sixth copied SQL fragment deleted), person-relation
chips, the self-person avatar fallback, the face-crop picker's current marker
and the owner-side collaborative bridge representatives.

Removals/behavior changes (deliberate, one-time):
- auto-pin of the first accepted occurrence removed (ClassInstanceService);
  legacy non-manual pointers stop winning (no data migration).
- setRepresentativeMedia resolves the canonical occurrence ON the chosen media
  (terminal ladder pick), not blindly the latest accepted one.
- re-pinning enqueues the generate_discovery_thumbnail crop job for the new
  canonical occurrence (idempotent).
- thumbnail_derived_asset_id accept paths validate the payload occurrence is
  the CURRENT canonical representative (last-write-wins removed); the missing
  crop sweeps enqueue canonical-occurrence-only crops (payload carries
  occurrenceId).
- person instance representatives persist medoidFaceAnnotationId (additive,
  absent-legal) => V170; envelope validation fail-closed when malformed.
test(api): pin ADR 0114 ladder + align fixtures with canonical representative semantics
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 3s
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Build Android CI image (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 / Android unit tests and debug APK (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 2m39s
563bb2245e
- new ClassInstanceRepresentativeServiceTest (13 H2 cases): manual pin wins on
  listing/detail, non-manual pins fall through, named/tentative guard, largest-
  cluster medoid + tie-break + vanished-face fall-through, singleton cluster,
  non-people embedding medoid (summed cosine center), terminal ladder
  (quality > confidence > recency), re-pin enqueue idempotency, auto-pin gone,
  canonical-occurrence crop guard.
- updated tests that pinned the OLD newest-fallback / auto-pin / no-crop-URL
  behaviors; statement budgets raised for the shared resolver per chunk.
- H2 fixture schemas carry V170 medoid column, class_instances representative
  columns, discovery_results quality columns and the shared-resolution tables
  (IF NOT EXISTS) so every affected module's fixture stays in sync.
- MLResultAcceptanceTest instance-mode pointer test now seeds the canonical
  occurrence and wires the discovery service (production guard wiring).
- spec 026 amendment node + S4/AC6 inline annotations, design-doc amendment
  note, KNOWN_ISSUES ISSUE-167 mitigation entry.

rtk ./gradlew :apps:api:test — 2164 tests, 0 failures.
chore(specs): drop stray backup artifact
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 3s
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Build plants worker image (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 Android CI image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Build people 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 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 2m46s
411d5ca65d
chris force-pushed feat/rep-thumb-api from 411d5ca65d
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 3s
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Build plants worker image (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 Android CI image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Build people 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 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 2m46s
to cf9048dad1
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 / Smoke API and media worker (push) Has been skipped
Build and Deploy / Build plants worker image (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 Android CI image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Android unit tests and debug APK (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 3m7s
2026-10-17 01:17:33 +02:00
Compare
chris merged commit 79af0a7d8f into main 2026-10-17 01:21:43 +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!1277
No description provided.