This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
ADR 0119: Anchor-quality-gated identity evidence for semisupervised clustering (semisupervised-v6)
Status: proposed Date: 2026-11-13
Context
Incident (2026-11-13, owner 38a79de6, people domain, semisupervised-v5, clustering_max_distance 0.35 after recalibration). William's instance (28d20e79-ae8a-41a9-8168-1512f7abbb23, 9-year-old boy) attracted 12 wrong tentative assignments. Face-by-face forensics: every wrong tentative was qualified via single-anchor adjacency to one of 7 William anchors; 4 of those 7 sit below the instance's detection_confidence Q1 (instance median 0.775, Q1 0.699; the attractor anchors measure 0.546–0.651; instance minimum 0.502). The owner visually confirmed the attractors are profile / back-of-head shots. Root cause class: low-quality accepted faces acting as identity evidence — as v5 anchor-adjacency evidence (_pair_threshold_adjacency L×U view), as labeled partition nodes in hac_average_partition, and as ADR 0108 representative material (built from ALL accepted faces regardless of detection quality; _person_representatives_with_fingerprints selects on assignment + non-zero embedding only).
Geometry cannot fix this class. Children under ~10 are weakly separated in the w600k-v2-aligned space: Holger(6)↔William(9) anchor cross-distance median is 0.867 (well separated at the anchor level), yet face-to-face nearest distances across DIFFERENT real children routinely land 0.21–0.40 — inside the production gate of 0.35. No embedding-threshold recalibration separates faces the space itself cannot separate; the observed distinguisher was anchor quality, not distance. Cross-gender misreads compound at young ages (MiVOLO reads many toddler faces as female — the open ISSUE-224 pattern; measured: 788 female-reads inside a male-dominant child instance, and those faces are geometrically kernel-close to the instance — i.e. misreads, not contamination).
Spec-050 semantics (verified against the shipped text and PeopleClusteringResetService): qualifying(u) = identities with ≥1 anchor/representative within clustering_max_distance of u; wholeGroup = intersection over members; v5 evidence = union of rep-adjacency (_build_rep_graph U×R) and anchor adjacency. Tentatively-assigned faces are zero-anchor unlabeled pool members (ADR 0102 amendment): they are re-fed every run, may be re-proposed to a different person, and Core retargets by superseding the old tentative occurrence. Soft reset preserves discovery_results.state='accepted' (only non-owner-confirmed states reset) — so a reset alone can NOT clear contaminated anchors, and the fix must change EVIDENCE (what qualifies), never assignment state.
Owner constraints: no manual DB surgery; the fix must be systematic — pipeline quality/attribute gates plus a systematic, operator-light cleanup path for already-contaminated anchors.
Decision
V1 — Anchor quality gate: absolute, evidence-only, both evidence views. A new owner setting anchor_min_confidence (V-new migration on discovery_domains, NUMERIC(3,2), finite [0,1], people default 0.65, 0.0 = off — the ADR 0108 representative_split_distance=2.0 off-switch pattern). Faces with detection_confidence < threshold are excluded from all three evidence roles in the gated method: (a) anchor-adjacency evidence, (b) ADR 0108 representative/medoid construction (selection filtered before _representative_fingerprint — see V3), (c) the labeled partition node set (a weak anchor no longer co-groups pool faces it attracted). They remain accepted assigned faces — weak identity evidence, not wrong assignments; nothing is un-assigned, no occurrence state changes, pool membership is untouched (a weak-detection unassigned face still reaches C/A cards; that is a suggestion-quality question, not an identity-evidence one — non-goal). Absolute, not percentile: percentile gates are unstable for small instances (a 3-anchor person always loses its worst anchor even at 0.9), non-deterministic across curation states, and divorced from the detector's own confidence semantics. 0.65 sits between the observed instance Q1 (0.699) and the attractor cluster (0.546–0.651) — it cuts exactly the measured attractors while keeping the bulk; the CV sweep (V6) validates 0.60/0.65/0.70 before default. Fail-open on missing confidence: the gate applies only where the feed carries a value (old Core → no field → gate inert, logged); a gate that silently dropped every anchor of an old feed would be a coverage bug, not a safety net. Anchor floor: if the gate would empty a person's anchor set entirely, retain exactly the single highest-confidence anchor (and the single-centroid representative in the same degenerate case) — a person must never become evidence-invisible; logged as documented degradation.
V2 — New registry method semisupervised-v6, contract version 5, legacy byte-identical. The ADR 0116 V1 shape verbatim: register SEMISUPERVISED_V6_METHOD in CLUSTERING_METHODS/SINGLE_PASS_METHODS; contract_version_for_method stamps 5 for v6 (evidence qualification changes which cards exist — wholeGroup shapes move — an identity-structure change, so v6 candidates compare only within their own contract generation); WorkerJobEnqueueService snapshots version 5, the worker refuses v6@≤4 via unsupported_clustering_contract, Core's WorkerResultSemisupervisedEnvelope accepts v6@5 and rejects mismatches. discovery_domains.clustering_method allowlist (PeopleClusteringResetController) gains v6; the isSemisupervised matrix gains a row. Implementation shape: _semisupervised_v6_candidates reuses the v5 flow with three injected differences — a gated anchor map (shared _anchor_labels gains an optional min_confidence=None parameter; None = byte-identical, so v1–v5 call sites are untouched), a gated representative build (_person_representatives_with_fingerprints gains the same optional parameter), and the gated labeled node set fed to hac_average_partition. ADR 0122 V3 amendment: v6 representatives are per-cluster medoids of the gated selection (ADR 0122) — the handler builds them with scheme="medoid", the V168 fingerprint carries the representative-scheme tag, scoring and contract stay untouched. _semisupervised_v5_candidates, _emit_group_candidates, _build_rep_graph, _pair_threshold_adjacency are never modified. v1/v2/v3/v4/v5 stay byte-identical, selectable, and pinned by the existing golden fixtures; rollback = stay on (or return to) v5.
V3 — Feed extension and the V168 fingerprint cache. GET /api/worker/jobs/{id}/owner-face-embeddings ships detectionConfidence (from discovery_results.confidence) as an additive optional per-embedding-row field; Core validation is fail-open (absent = old worker, no error); old workers ignore it. Because the V168/ADR 0113-V6 fingerprint hashes the selected faceAnnotationId set, applying the gate to the selection before hashing makes the cache content-addressed and self-invalidating: first v6 run → fingerprint mismatch vs the persisted ungated set → one-time representative recompute per (owner, domain, model pair) → envelope full-replaces the table with gated reps + gated fingerprints → steady state cached again. No V168 change, no migration beyond the settings column. If a threshold change leaves the selected id set identical (no face crosses the line), the fingerprint — correctly — stays equal and the cache hits: the threshold does not need to be hashed, only its effect. Method switching is symmetric and safe: switching a domain back to v5 recomputes ungated reps on the first run for the same reason. ADR 0122 V3/V4 amendment: the v6 fingerprint additionally carries the representative-scheme tag (centroid | medoid) — the medoid switch changes none of the hashed inputs (same face ids, split, model pair), so the tag is what makes a persisted centroid decomposition invalid for a medoid run; switching schemes recomputes once for the same content-addressed reason. One-time full recompute per domain is accepted cost (the decomposition is per-person O(n²)/O(n³) but household-scale; measured class ≈ minutes). Side benefit: excluding weak anchors shrinks L, so the partition and the L×U adjacency pass get cheaper, not dearer.
V4 — Attribute cross-check: corroborated-only, post-grouping, explicitly secondary. Extend the ADR 0118 gate family (envelope + post-processing, own operator flag, default off — the V3 precedent: never grouping semantics): (a) gender demotes only with geometric corroboration — a card is demoted to review-only when the faces' dominant gender read contradicts the target person's dominant gender profile AND the geometric evidence is contested (e.g. raw distance to all same-profile anchors above the gate while an opposite-profile person's representative sits within it, or the runner-up margin < 0.05). Gender alone NEVER demotes: the measured 788 female-reads in a male-dominant child instance are kernel-close misreads, and demoting on gender alone would nuke legitimate toddler coverage exactly where MiVOLO is noisiest (ISSUE-224). (b) Age tightens the B-mint gate, not assignment: the existing generation-gap gate widens to a per-person age-band demotion for NEW B-card mints (|median implied birth year − person profile| beyond a CV-calibrated margin), never retroactively against accepted faces (MAE 7.5 y per face; only aggregated profiles gate — unchanged). Honest limit, stated up front: neither gate would have caught THIS incident — the competing children are the same age and the same gender. The anchor quality gate (V1) is the fix for the observed failure class; V4 is defense-in-depth for the adjacent classes (cross-gender child confusion, generational relatives already covered by 0118).
V5 — Systematic cleanup of existing contamination: self-healing tentatives + a requalification audit job, never auto-removal. Two mechanisms, both evidence-side: (1) Tentatives self-heal under v6 by construction. Wrong tentatives are zero-anchor pool members (spec-050/ADR 0102 amendment): the first v6 run re-clusters them against the gated anchor/rep sets; those that no longer qualify for William lose their wholeGroup and surface as C cards (new person) or B cards for the correct child, and Core retargets via the existing superseding path. No new code. (2) people_anchor_requalify — a new owner-scoped audit job type (modeled on the spec-068 backfill flow family: operator-triggered, additive job type, no schema change beyond settings). Per accepted face of person P: if the face lies beyond clustering_max_distance from ALL of P's surviving (gated) anchors AND all of P's gated representatives, emit a review card — 'assignment evidence invalidated — confirm or remove'. Never auto-remove, never auto-demote an accepted assignment; the card is the operator-light surface the owner asked for. This is a present-tense cohesion check, not historical replay (reconstructing which anchor qualified which face in past runs is not persisted anywhere and is not worth a provenance schema). Reset+rerecognize is REJECTED as the cleanup vehicle: soft reset preserves accepted states (verified) so it cannot clear contaminated anchors, and hard reset destroys owner confirmations — the exact work the constraint protects.
V6 — Threshold recalibration is re-opened, decided by the gated sweep, not by argument. Excluding weak anchors lowers effective evidence coverage, so the 0.35 recalibration (tightened from 0.40 when weak attractors inflated wrong-suggest) may now be over-tight — 0.40 plausibly becomes safe again because the noisy attractors are gone. Decision protocol: extend workers/people/experiments/assignment_cv/ with a gated v6 lane (it imports production _pair_threshold_adjacency / hac_average_partition / representative build — parity by construction) and run the shadow-aware sweep (--include-stashed, the shipped v5 lane discipline) over anchor_min_confidence ∈ {0.60, 0.65, 0.70} × clustering_max_distance ∈ {0.35, 0.40, 0.45} before the v6 default is chosen. Acceptance gates (ADR 0116 discipline): the G1 set, zero per-person regressions vs the ungated v5 lane at the incumbent 0.35, and the incident fixture below. Do not assume 0.40; measure it.
V7 — Rollout: dark ship → operator A/B → any default consideration. The ADR 0116 V8 shape: registry/allowlist/matrix/stamp additions dark-ship first; the operator opts in per domain via discovery_domains.clustering_method='semisupervised-v6'; a v5 → v6 → v5 A/B cycle with a candidate-key churn report is mandatory before any default change (cluster boundaries legitimately move when evidence sets shrink — churn at switchover is expected and must be reported, not suppressed); in-flight safety is inherited (jobs snapshot settings immutably). DEFAULT_CLUSTERING_METHOD is untouched by this ADR.
REJECTED ALTERNATIVES. (1) Setting-gated behavior inside v5: v5 is a shipped, golden-pinned method; a knob that moves its candidate keys without a contract stamp breaks cross-stamp comparability and the byte-identical legacy discipline (ADR 0116's 'v3 code is never modified' applied to v5). (2) Silent evidence change inside v5: outright contract violation. (3) Percentile gates: unstable, curation-state-dependent, unpredictable fingerprints. (4) Reset-based cleanup: verified ineffective for accepted anchors (soft) or destructive (hard). (5) Gender-alone demotion: measured to be wrong on this very library. (6) Cannot-link/graph-edge changes for attribute conflicts: rejected on ADR 0118's evidence — grouping-semantics changes force contract churn and don't address the failure class.
ADR 0123 amendment: the pool-side complement of this gate is ADR 0123 (emission-scoped, demotion semantics — pool faces below pool_min_confidence/pool_min_quality stay recognized and marked but never mint automatic suggestions; this gate shapes WHO anchors identity, 0123 shapes WHO receives suggestions).
Consequences
Expected quality: the attractor mechanism is removed at the source — wrong-child faces that qualified only through sub-Q1 anchors stop qualifying (C/A outcomes instead of wrong B), while the Holger↔William anchor separation (0.867 median) keeps legitimate assignments safe. Coverage risk concentrates in persons whose anchors are mostly weak (children photographed at play); the anchor floor (V1) and the fail-open feed rule bound it, and the CV sweep quantifies it before any default moves. Costs: (1) one-time representative recompute per domain on first v6 run (V168 cache self-invalidates — accepted); (2) one additive feed field per embedding row (one float; negligible vs the 512-d vector); (3) one more (method, contractVersion) matrix row on worker and Core; (4) one new job type (people_anchor_requalify) and one settings column + controller exposure; (5) switchover churn — expected, measured by the mandatory A/B report; already-persisted v5 candidates are never retro-affected (results persist per job stamp). Risks: gate set too high silently shrinks evidence for children (mitigation: CV sweep + owner-tunable + off-switch + anchor floor); detection_confidence semantics drift if the detector model is ever upgraded (revisit trigger below); the requalify audit may emit cards for legitimately-idiosyncratic faces (profile shots correctly assigned) — accepted review traffic, owner decides. Revisit triggers: CV shows per-person regressions or coverage collapse at all candidate thresholds; recurrence of the attractor incident under v6; a detector model change that shifts the confidence distribution (then recalibrate anchor_min_confidence or fold quality into a re-detection pass); spec-068/ISSUE-224 resolution changing the gender-misread landscape (may allow strengthening V4).
Tests. (1) Golden: existing test_clustering_golden.py fixtures for v1–v5 unchanged and green (byte-identical pin); new v6 golden fixture incl. determinism under permuted feed order. (2) Gate units: gated _anchor_labels selection; gate applied before fingerprint (fingerprint changes when a gated face leaves the selection, unchanged when threshold moves but selection doesn't); representative build excludes gated faces; partition labeled-node set excludes gated anchors; anchor floor retains the best anchor of an all-weak person; fail-open when detectionConfidence absent. (3) Envelope/feed: additive detectionConfidence fail-open; v6@5 accepted, v6@4 rejected, non-v6 stamps against v6 payloads rejected (WorkerResultSemisupervisedEnvelope H2 tests); enqueue snapshot carries version 5 + threshold. (4) CV: gated v6 lane vs shadow-aware v5 lane across the V6 sweep grid; G1 gates; zero per-person regressions; incident regression fixture — the 12 William wrong-tentatives must not qualify under v6 at the chosen defaults. (5) Requalify: audit job emits confirm-or-remove cards for gated-out accepted faces, never mutates occurrence state; superseding path (tentative retarget) exercised end-to-end (Spec050 Postgres harness).
Non-goals. No grouping-semantics change beyond evidence selection (merge rule, gates, card shapes, qualityScore, pessimistic scoring unchanged). No removal or demotion of accepted assignments without owner action. No gender/age-based grouping or cannot-link edges. No re-detection, re-embedding, or quality-score changes to detection itself. No percentile gates. No changes to v1–v5 code paths. No historical evidence provenance (which anchor qualified which face in past runs is not reconstructed). No default-method change.
Links: 0108 (representative construction gains a gated selection, off-switch pattern), 0113 (rep graph + V168 fingerprint cache — self-invalidation argument), 0116 (registry/coexistence/contract-bump/A-B discipline this ADR copies), 0118 (gate family V4 extends; corroborated-only gender is its direct consequence), 0101/0102 (tentative pool semantics that make V5's self-healing work), spec-050 (gate semantics verified), ISSUE-224 (open record this closes methodologically).
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