Table of contents
ADR 0101: Single-pass semi-supervised face clustering
Status: superseded Date: 2026-10-02 Superseded by: 0102
Context
FINAL owner contract supersedes prior drafts. Exactly one semi-supervised clustering of confirmed anchors and eligible unassigned physical faces. A: isolated singleton stays unassigned. B: anchor plus even one unlabeled face may attach to an existing identity. C: an unlabeled pair or larger group is a new-person suggestion only. No minimum-size parameter or floor, nearest-anchor preliminary pass, margin, weak pass, fallback or Core rematching. One clustering distance parameter controls granularity indirectly. Implementation and transactional safety passed the independent oracle gate on the integrated branch (backend lifecycle + worker + web), including golden seam tests fed with byte-exact real-worker payloads. Consumer-side worker interface: immutable job payload settings {clusteringMethod:'semisupervised-v1', clusteringContractVersion:1, maxDistance finite [0,2]}; result envelope carries clusteringMethod+clusteringContractVersion even when candidates are empty; candidate stamps are consistency-only. B = cluster_person_match with existingInstanceId and distinct physical faceAnnotationIds; finite distance + confidence=clamp(1-distance) when a centroid is usable, else reviewOnly:true with no score. Ambiguous B: ambiguous=true, reviewOnly=true, may carry the suggested target's score; conflictingPersonIds = sorted ALL qualifying identity ids INCLUDING the suggested target, compatiblePersonIds = sorted whole-group-compatible ids. C = new_person_cluster with >=2 distinct ids, no target, optional internal-coherence confidence. Interface incompatibilities are reported as rejections, never diverged from.
Decision
Required contract, NOT a claim of completed implementation: semisupervised-v1 jobs snapshot clusteringContractVersion=1 and finite maxDistance in [0,2] from people discovery_domains.clustering_max_distance (additive migration V150, people default 0.35, no table-wide default, no other-domain rows). GET/PATCH /api/admin/people/clustering-max-distance is operator-authorized and validates finite [0,2]; null resets to the default; updates never mutate existing queued jobs (enqueue snapshots the configured value + method + contractVersion into new-method job payloads; legacy payloads stay byte-unchanged). Immutable job settings, not candidate stamps or current operator settings, determine result interpretation. The result envelope must contain matching method/version even when candidates are empty and candidate stamps must agree. The complete result is validated BEFORE any write: unique physical faces within/across candidates, agreeing canonical refs and membership, valid finite scores, and method-specific shapes; empty results still validate the envelope. Legacy payload shapes on a semisupervised job (existing_person_match, legacy weak marker) and forged new-method markers on legacy jobs are rejected; legacy methods keep legacy semantics even after the operator switches the domain method, and old-worker fallback output never silently runs legacy semantics for a new job. B is cluster_person_match with explicit suggested existingInstanceId; missing usable identity score means reviewOnly. Any competing labels mean ambiguous=true and reviewOnly=true, conflictingPersonIds contains ALL qualifying identities including the suggested target, compatiblePersonIds contains whole-group-compatible identities; both sorted. Ambiguous or unscored B receives only a pending card, no automatic allocation. Ambiguous acceptance requires an explicit owner-selected target (never a default to the suggested identity). Unambiguous scored B confirms only if the effective owner auto-accept policy is enabled AND identity confidence meets its threshold; otherwise the source-first locked acceptance primitive runs the ALLOCATE_TENTATIVE_KEEP_PENDING outcome: it revalidates unassigned refs, writes tentative occurrences for those only, persists the actual actionable subset into the candidate's refs/payload membership/evidence, records the allocation as a provenance event (decisionSemantics=allocation, never an accepted owner review), and leaves the candidate pending as the live actionable backing card. No old strong/medium distance bands, consensus, 25-face cap or minimum-size floor apply to the new method; stashes follow the same rule; the policy threshold is the only confirmation gate. C is new_person_cluster with at least two distinct physical ids, no target or assignment flags, optional internal coherence confidence; pending only, never Core rematched. Each live new-method tentative must retain its pending backing card: same-target replay preserves the original card; partial overlap preserves original ownership and creates a card only for newly allocated refs; cards backing live tentatives are exempt from face-overlap superseding while unallocated suggestions keep normal dedup. Different-target replay cannot steal. Confirm upgrades the card's actionable subset; reject releases only card-owned tentatives; refs already confirmed/assigned elsewhere are excluded from the actionable subset. Reset atomically releases occurrences and invalidates their cards; stale pre-reset in-flight job results are rejected (cannot resurrect assignments). All writes for a candidate are transactional, including 26/100-face groups, with stable source-first lock order and no intermediate commits. Legacy job/method semantics remain unchanged.
Consequences
Verified on the integrated branch and passed by the independent oracle gate (backend lifecycle + worker + web lanes, golden seam tests with byte-exact real-worker payloads): result-envelope/mode validation through the real WorkerResultService (H2 unit + PG integration) including empty envelopes, legacy-shape and forged-marker rejection, cross-candidate duplicate physical faces, C-shape and score checks (ambiguous review-only cards may carry the suggested target's score; non-ambiguous review-only must not; clamp tolerance 1e-5); ALLOCATE_TENTATIVE_KEEP_PENDING inside the one source-first locked acceptance primitive with actionable-subset persistence and allocation provenance events (audit_events, no accepted review-decision fiction); rejected-pair suppression before allocation; owner-scoped tenant clustering lock (V151) serializes reset vs result application fail-closed; backing-card invariant (same-target replay preserves the original card, partial overlap splits cards, automatic confirmed acceptance and end-of-job superseding protect backing cards, reject releases only card-owned tentatives, confirm upgrades in place); 26-face B keeps ONE candidate with full semantics; ambiguous large B assigns nothing; next-job integration through the actual enqueue service exports B faces in tentativeAssignments (assignments only after owner accept, evidence recoverable after reject); stored clustering_max_distance lands in the actual queued payload and updates never mutate queued jobs. Similarity/confidence is NOT calibrated correctness probability — it gates confirmation only through the owner policy threshold. Cannot-link separates fixed identities within a clique but does not resolve alternative-label ambiguity; ambiguity stays review-only until the owner picks an explicit target (bulk confirm refuses ambiguous cards; decideCandidate requires an explicit target). Pending C suggestions can recur/deduplicate and must not strand pending B backing cards. Only persisted live assignments remove eligible faces from freshly queued unassigned proposals. Legacy methods and their tests remain byte-unchanged (worker differential-parity harness); the 25-face cap continues to apply ONLY to legacy silent actions. Admin UI control (method option + single maxDistance control with 404 degradation) is included in this branch; endpoint contract GET/PATCH /api/admin/people/clustering-max-distance {maxDistance:number|null} -> {maxDistance:'0.22', min:'0', max:'2'} (super-admin; null resets to default; invalid/out-of-range 400). ROLLOUT CONSTRAINT: API and people-worker deploy together BEFORE switching the domain method — a skewed worker produces bounded dead jobs (3 attempts, visible processing issue with unsupported_clustering_contract / envelope-rejection codes), never silent legacy processing. No historical incident causality or absolute churn-elimination claim is established by this ADR.
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