ADR 0104: Constrained average-linkage clustering as opt-in semisupervised-v2 (DRAFT - pending user design approval)
Status: accepted Date: 2026-10-05
Context
PR #1033 (branch experiment/linkage-comparison) secured a reviewed offline comparison: production semisupervised-v1 greedy complete-linkage cliques vs constrained standard HAC average-linkage vs a HAC complete control, on synthetic 512-dim embeddings with the EXACT production outcome-gate code shared by all three methods and the clique transcription asserted bit-identical to _semisupervised_candidates on every sweep row. Approved results (multimodal, threshold 0.45, pair precision 100% in these synthetic cases only): pair recall production 36.04%/51.80% vs hac-average 47.75%/74.77% vs hac-complete 35.14%/45.95% (seeds 20261005/20261105); threshold 0.35 shows no advantage for any method; hard-negative anchor ablation (0/2/4 anchor faces of one pair removed) precision production 83.33/80.95/76.27 vs HAC 100/91.40/84.91. Results are SYNTHETIC-ONLY evidence: no universal dominance, no safety, and no default-threshold claim; 0.45 is not automatically transferable. Documented confound: production reuses anchors during greedy growth while HAC partitions first and gates afterwards, so production-vs-HAC does NOT isolate the linkage rule (only hac-average vs hac-complete does).
Current production (clustering.py, method semisupervised-v1, contract version 1): per (modelName, modelVersion) pair a blockwise threshold graph (never a full N x N matrix, ISSUE-081); anchors are owner-confirmed assignments only; greedy complete-linkage clique growth in ascending-seed order with reusable anchors and emission-time consumption of unlabeled faces; outcome gates per group: A singleton -> unassigned; B requires wholeGroup identity = intersection over unlabeled members of the identities with at least one within-threshold anchor adjacency (X qualifies iff EVERY unlabeled member has SOME confirmed anchor of X adjacent; anchors need not be the same face), any alternative qualifying identity on any member demotes the card to ambiguous review-only; C = no wholeGroup identity plus at least 2 unlabeled members -> new_person_cluster suggestion; ADR 0103 qualityScore ranks cards; ONE owner control discovery_domains.clustering_max_distance (V150 default 0.35, finite [0,2]) snapshotted into immutable job payloads; deterministic byte-identical output. Known user-facing issue motivating this ADR: many C clusters are 2-face fragments.
Decision
STATUS: ACCEPTED by user 2026-10-05 ("weiter und auch implementieren"). Implementation authorized along the design gates below; rollout stays owner-opt-in per domain with v1 untouched.
D1 (decided by user 2026-10-05): Introduce constrained average-linkage clustering as a NEW registry method id (e.g. semisupervised-v2) alongside semisupervised-v1. v1 stays byte-unchanged; the owner opts in per domain via settings.clusteringMethod. A supported (method, contractVersion) matrix in Core routes and validates; unsupported combinations fail closed. Envelope needs no new fields (gates and card shapes unchanged). Integration surface beyond the registry is explicitly inventoried (not exhaustive without implementation planning): enqueue settings snapshot (WorkerJobEnqueueService), processing-mode routing + envelope validation + forged-marker rejection (WorkerResultService), persistence stamps and tentative semantics (ClassInstanceDiscoveryService), settings allowlist (PeopleClusteringResetController), operator status/admin UI method options.
D2 (decided by user 2026-10-05): Rollout threshold stays the stored clustering_max_distance (default 0.35). No recalibration ships with the new method; recalibration toward ~0.45 is a SEPARATE, evidence-based follow-up (currently synthetic-only evidence). Rollback therefore also restores 0.35 - no shared-setting thrash.
D3 (decided by user 2026-10-05 - keep reviewed gate): wholeGroup semantics under average linkage remain the REVIEWED gate unless the user chooses otherwise: X qualifies iff every unlabeled member of the group has at least one confirmed anchor of X within threshold adjacency (anchor adjacencies are read from the graph, NOT from HAC group membership - an anchor partitioned elsewhere still qualifies). Mean-based identity attachment is explicitly NOT proposed (no reviewed evidence). Mean-based identity attachment is NOT pursued; revisiting it later requires its own investigation and an explicit ADR amendment. The ADR as a whole remains DRAFT pending overall user design approval.
D4 (decided by user 2026-10-05: design gate): Scalability is a DESIGN GATE before any implementation: specify the constrained merge/update rule and numerical evaluation order, then prove the scalable algorithm (candidate: NN-chain with lazy distance evaluation for the reducible monotone linkages average/complete, no full N x N matrix, honoring ISSUE-081) produces EXACTLY the same partition as the reference HAC - including the stable tie-break (smallest min-member-index pair) - verified by adversarial parity fixtures against the experiment reference. Alternatives (threshold-graph component decomposition - exact for the raw graph because cross-component pairs all exceed threshold, but unbounded giant-component sizes; or a hybrid size cap falling back to greedy cliques - rejected for now: two behavioral regimes, conflicts with the spec-050 no-fallback principle) are evaluated inside this gate, not assumed. The spec-050 'ONE clustering pass' contract must be re-read against the chosen approach; component decomposition is judged internal to one pass but this interpretation needs explicit approval.
D5: The change replaces BOTH the search strategy AND anchor consumption semantics: HAC partitions anchors together with unlabeled faces (conflict rule: groups with different non-empty confirmed identity sets never merge; equal sets may) and gates afterwards, versus greedy reusable-anchor growth. It is NOT a one-line linkage swap. Consequences: anchor-containing groups can emit C; groups can emit nothing; run-global physical-face uniqueness and emission-based cross-model consumption are preserved; per-model-pair graph/partition stays. Card confidence, qualityScore (ADR 0103 heuristic retained, no refit authorized), candidate keys, ambiguity shapes and policy-qualified auto-confirm can change WHERE GROUP COMPOSITION CHANGES - accepted as the point of the change (fewer wrong 2-face fragments), with churn measured during the design gate, not assumed. Two-face clusters per se are acceptable to the user; WRONG fragmentation is the target.
D6: Rollback = future-job algorithm selection via the domain setting. NOT covered by existing guarantees: already-queued/running v2 jobs still complete and persist v2 results (jobs snapshot settings immutably); cards backing live tentative occurrences are supersede-exempt; owner confirmations are never undone. An explicit switch fence / in-flight job handling (drain, cancel, or version-stamped staleness for method switches) is part of the implementation planning this ADR requires; switch-back with both methods having outstanding jobs is a mandatory test case.
D7: Explicitly out of scope: no weak extra pass, no multi-pass restructuring, no qualityScore refit, no concurrent ranking change, no private-library benchmarking, no legacy method changes. Synthetic-only results justify a DESIGN, not a rollout.
Consequences
If accepted and implemented: owners opt into average-linkage grouping per domain while v1 remains available and byte-identical; expected effect (synthetic-only so far) is fewer wrong 2-face fragments, at the cost of cross-run membership churn whenever a late-arriving photo changes global merge order. Identity safety rests on the explicit group-level confirmed-identity conflict rule (necessary under average linkage: removing cannot-link edges alone does not prevent a mean <= threshold merge whose far pair crosses identities); it guarantees no group mixes confirmed identities but does NOT by itself guarantee correct unlabeled membership or B/C outcomes. The design gate (D4) must be passed before any code is written; if exact scalable equivalence cannot be proven, this ADR returns to draft with a different scalability story. Any Spec-050 contract text amendment ('ONE pass', method registry, no-fallback principle) and ADR 0102/0103 scope notes (currently v1-specific) happen as explicit spec/ADR edits in the implementation spec - not silently. Test burden: parity fixtures vs the experiment reference (tie-breaks included), scenario suite (multimodal, hard_negatives, pair_fragment, permutation, thinning, anchor ablation), byte-determinism under fixed numeric environment, envelope/Core matrix validation, method-switch lifecycle tests (in-flight jobs, switch-back, supersede-exempt backing cards, tentative retarget/release per ADR 0102 amendment). If rejected: PR #1033 remains the record of evidence; production clustering is untouched either way.
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