ADR 0103: Unified quality score ranks and displays every discovery suggestion
Status: accepted Date: 2026-10-04
Context
Since spec 040 the candidate listing ranks cluster_person_match cards above all other candidate types (code comment 'Carousel prioritization (product decision)'), because merge confidence (1 - distance to the person centroid, suggestion-band bounded) and new_person_cluster confidence (mean member-to-centroid coherence, observed 0.82..1.0) live on incomparable scales. Under semisupervised-v1 this ordering buries every New-person card: live state 2026-10-04 showed 341 pending merge cards (241 of them supersede-exempt backing cards for live tentative occurrences, growing monotonically across runs) ahead of 4738 pending new_person_cluster cards - the first New-person card at sort position 342 while the carousel fetches 5 per page, so the owner effectively never sees one. Investigation also ruled out the alternatives: the stash-filter hides 0 pending New-person cards, the envelope never rejects v2 results, and raw silhouette is unusable as the ranking key (high variance on size-2 clusters, incomparable units across types), while per-run min-max/percentile normalization would reshuffle persisted cards whenever any unrelated photo arrives.
Decision
Every semisupervised-v1 candidate carries an OPTIONAL qualityScore in [0,1], computed once in the Python worker at clustering time from one feature set with one set of weights for BOTH card types. Features (each clamped to [0,1]): cohesion = clamp01((_cluster_confidence(members) - 0.55) / 0.40), neutral 0.5 for single-member groups; isolation = for cluster_person_match clamp01(1 - d_best) (identical semantics to today's confidence), for new_person_cluster clamp01((d_nearest_external_identity - mean_intra_cluster_distance) / 0.15) with 1.0 when no identity exists at all; ambiguity = clamp01((d_second_best - d_best) / 0.10) over qualifying/external identities with 1.0 when no second identity exists; size = 1 - exp(-n/3) over member count n. qualityScore = round(0.35cohesion + 0.25isolation + 0.25ambiguity + 0.15size, 6). These weights and anchors are v1 constants pending outcome-based refit (owner accept/reject log -> offline Platt-style recalibration); the score is deterministic within a run and stable across runs for unchanged candidates (no per-run normalization, so persisted cards never reshuffle). Transport: the envelope field is optional and does NOT bump SEMISUPERVISED_CONTRACT_VERSION (releasedTentativeFaces precedent); existing confidence/distance validators and their byte-pinned semantics are untouched; persistence adds a nullable quality_score column (NUMERIC(8,6) CHECK 0..1, migration V153) beside confidence, and the payload jsonb carries the worker candidate free. Listing: both ORDER BY branches of candidatesPaged lead with quality_score DESC NULLS LAST before the existing confidence/recency tiebreaks; the type-first CASE is removed and the sort parameter name 'confidence' keeps its API name with the updated semantics. UI: the suggestion card figure renders qualityScore (fallback: confidence; both absent -> no figure) instead of the previous similarity sources (live person-ranking row or confidence); per-target picker chips keep their live person-ranking similarity because that measures the target person, not the card. Unscored/review-only cluster_person_match candidates, legacy-method candidates, and existing_person_match rows carry no score (NULL sorts after scored cards; UI falls back).
Consequences
New-person and merge cards interleave in one calibrated order; tests pinning the type-first grouping and golden worker fixtures are rewritten to the new field. Supersede-exempt merge cards backing live tentatives keep their pre-ADR NULL score until the owner decides them - they rank below scored cards in the interim and no SQL backfill is faithful, because the ambiguity feature needs second-best identity distances only the worker knows; fresh New-person cards are re-stamped every run (~10 min), so the reported invisibility is fixed immediately. Adding a candidate-level optional field requires extending validateClassInstanceCandidate plus the B/C semantic validators (finite, [0,1], present-with-scored-B not required). Legacy clustering methods are byte-unchanged and simply emit no score. The follow-up to make the score predictive rather than heuristic is an outcome log plus an offline weight refit shipped as a constant bump.
Memories Wiki
Using Memories
- Accounts, the Library Hub, and Data Export
- Albums and Automatic Suggestions
- Explore and Discovery Domains
- The Media Viewer
- People and Faces
- Places and Map
- Plants (In Development)
- Datenschutzerklärung (Privacy Policy)
- Fast, Progressive Image Loading
- Search
- Sharing and Households
- Timeline and Photos
- Uploading and Import
Self-Hosting
- Backup and Restore
- CLI Password Reset
- Deployment Architecture
- Known Issues and Operator Diagnostics
- Map Tiles and Place Data Privacy
- Storage Layout
- Upgrades and Versioning
- Workers
Reference