ADR 0123: Pool-emission-quality gate: weak pool faces are recognized and marked, but never mint automatic suggestions (amends ADR 0119)
Status: proposed Date: 2026-11-14
Context
ADR 0119 gates IDENTITY EVIDENCE: accepted anchors below anchor_min_confidence stop anchoring (no anchor-adjacency, no labeled partition node), and representative builds select only gate-passing rows. The POOL — unassigned and tentative faces, the ones suggestions are minted FROM — is deliberately ungated: every pool face clusters, and a card may claim any pool member.
The owner's requirement (2026-11-14): faces of poor quality — blurred crops, poor detection scores — must stay recognized and marked, but must NOT produce automatic person-assignment suggestions. The owner retains manual assignment (the similarity-sorted person picker, suggestSimilarInstances, is untouched). The intuition: a suggestion whose evidential basis is a bad crop cannot be high-quality.
Two per-face quality signals already exist with full owner-library coverage (28,082 faces, zero NULLs):
discovery_results.confidence— the face DETECTOR's confidence (the same signal ADR 0119 gates anchors on; shipped into the worker feed as additivedetectionConfidenceper row).discovery_results.quality_score(V138) — 0.7 * sharpness + 0.3 * exposure computed deterministically on the rendered 512 px face crop; a direct 'blurred/underexposed crop' measure. NOT yet in the worker feed (the feed carries detectionConfidence only).
Measured evidence against the blunt version of the gate (2026-11-14 CV probe, shadow-aware, best ADR 0122 V6 cell medoid | gate 0.60 | 0.40, card mints only if EVERY member face passes):
| threshold | wrong B-cards | correct B-cards | verdict |
|---|---|---|---|
| none | 35 | 5434 | reference |
| conf >= 0.5 | 35 | 5434 | no effect |
| conf >= 0.6 | 31 (-11%) | 5153 (-5%) | mildly positive |
| quality >= 0.20 | 32 (-9%) | 4961 (-9%) | neutral |
| quality >= 0.25 | 29 (-17%) | 4308 (-21%) | negative |
| conf 0.6 + quality 0.25 | 25 (-29%) | 4115 (-24%) | ~neutral |
Hard DROPPING of suggestions is a bad trade on this library: the residual wrong-suggestion class is embedding-space confusion (children/family in w600k-v2-aligned, the known limitation), not bad crops. But the probe misses the owner's actual intent: the requirement is not 'fewer cards' — it is 'weak-basis faces must not drive AUTOMATIC assignment'. That is a demotion, not a deletion: the face stays recognized, stays marked, and the owner decides manually. The measured cost of a demotion is fundamentally different from a drop: no correct suggestion is lost, it merely changes channel (auto-assign vs review).
This ADR therefore implements the demotion semantics. The thresholds remain owner-tunable because the trade is library-dependent; the defaults are set from the probe's knee (conf 0.60 / quality 0.25 were the smallest values with measurable wrong-card reduction) but ship DISABLED (NULL) like ADR 0119's gate did, so production flips them deliberately.
Decision
V1 — Pool-emission gate (semisupervised-v6 only): two optional settings, pool_min_confidence and pool_min_quality (discovery_domains columns, NULL = gate off, fail-open like ADR 0119). A pool face is EMISSION-ELIGIBLE iff (a) its feed row has no detectionConfidence (fail-open) or it is >= pool_min_confidence, and (b) its feed row has no qualityScore (fail-open) or it is >= pool_min_quality. The gate is EMISSION-scoped, exactly as the owner specified: gated pool faces remain full partition members (they cluster, they densify groups, they absorb neighbors — none of that changes), they remain marked in the UI (occurrence stays pending/unassigned → face-review surface), and manual assignment by similarity is untouched. What changes is only the worker's candidate emission: a card (B, C, or review-only) may not CLAIM a gated face; its faceAnnotationIds/occurrenceRefs exclude gated members, and a group whose members are ALL gated mints nothing (that group has no admissible evidence basis — the owner's ' Grundlage schlechte Qualität' case). Gated faces are not consumed by cards they cannot appear in, so they stay re-proposable in later runs once reassigned or re-quality-scored.
V2 — Feed extension (additive, ADR 0119 pattern): OwnerFaceEmbeddingsController adds dr.quality_score AS quality_score to both UNION branches and, when non-NULL, ships qualityScore (float [0,1]) on each embedding row beside the existing detectionConfidence. Absent key or NULL = not gated (fail-open; old feeds unaffected). No shape change, no new endpoint, no cache interaction — the V168 fingerprint hashes face-id sets of ASSIGNED rows only, and the pool gate changes no representative input (V1 keeps pool faces in the partition), so representative digests are untouched and there is no one-time recompute.
V3 — Worker emission enforcement point: _emit_group_candidates gains an optional emission_eligible predicate (set of pool offsets that may be claimed), threaded from the v6 candidates handler only (v1-v5 byte-identical, no parameter passed). Semantics: per group, member offsets are partitioned into eligible and gated; candidates are built from ELIGIBLE members only. wholeGroup computation uses only eligible members' qualifying sets (a gated member cannot vote its identity into a card); a group with zero eligible members emits nothing; a group with eligible members emits a card whose refs list only eligible faces. The partition itself is untouched — gated faces still co-group and their presence can still CREATE a qualifying group (their embeddings densify), but they cannot be claimed by the resulting card. This is the exact 'recognized + marked, no auto-suggestion' contract.
V4 — Settings threading (V188 pattern): the API enqueue snapshots pool_min_confidence/pool_min_quality into settings for semisupervised-v6 jobs only (absent key = off for every other method and for older workers). Worker validation mirrors ADR 0119: finite [0,1] enforced, outside-window or non-numeric logs a warning and disables the gate. Admin UI: two number inputs in the Admin Discovery clustering section beside the anchor gate field (same component, !1503 pattern), operatorStatus exposes both values with the anchor gate status.
V5 — Defaults and rollout: both settings ship NULL (gate disabled). The probe's knee values (pool_min_confidence = 0.60, pool_min_quality = 0.25) are the documented recommended starting point; the owner flips them per domain when ready. No migration beyond the two new columns (V189). Rollback = set NULL; no recluster needed (the gate acts at emission only — the next run reflects it). CV acceptance before default-enablement: rerun the shadow-aware sweep's best cell with the demotion semantics active in the harness lane, assert (a) zero hard-error-rate regression on evaluated cards, (b) gated faces' manual-assignment visibility intact (occurrence states unchanged), (c) card faceAnnotationIds never contain a gated face. The e3403b1b invariant and William's 12 tentatives fixtures carry over from ADR 0122 V6 unchanged.
V6 — Relationship to ADR 0119: the anchor gate (evidence) and this pool gate (emission) are independent knobs. The anchor gate shapes WHO anchors identity; the pool gate shapes WHO receives suggestions. They share the fail-open discipline, the settings threading, the admin UI section, and the v6-only scoping; they gate different ends of the same pipeline. ADR 0119 is amended by one sentence: 'the pool-side complement of this gate is ADR 0123 (emission-scoped, demotion semantics).'
V7 — Sharpness floor (owner decision 2026-11-14, after two confirmed production cases): the quality blend's exposure term lets well-lit but visually flat crops pass any quality floor. Two owner-verified cards carried sharpness 0.005/0.017 (Laplacian variance 2.7/8.6 against the 500 ceiling) yet quality 0.264/0.251 — saved almost entirely by the exposure term, faces visually unrecognizable. The gate therefore gains a THIRD, independent signal: the crop's SHARPNESS component, reported separately by the media worker (additive sharpness key beside qualityScore in the face-thumbnail submission — faceCropQuality already computes it; expose, don't re-derive), persisted in discovery_results.face_sharpness (V190, NUMERIC(5,4), NULL = unknown, fail-open), shipped in the worker feed as additive sharpness, and enforced as pool_min_sharpness (same shape as the other two floors: discovery_domains column, NUMERIC(3,2)... actually NUMERIC(4,3) for headroom at 0.0x resolution, v6-only snapshot poolMinSharpness, worker-side finite [0,1] validation, emission-scoped, demotion semantics identical to V1). Default NULL = off. Recommended default from the two confirmed cases: 0.03 (b46f54ba's 0.017 and bcb49cee's 0.005 sit far below; genuinely readable crops start around 0.05+ by the Laplacian-ceiling calibration). A face is emission-eligible iff it passes ALL THREE floors independently — quality, detection confidence, and sharpness. Backfill: no bulk recompute needed — the media worker refreshes quality on every thumbnail re-render, so sharpness fills in organically per face; existing NULL-sharpness faces stay fail-open until their next render (owner may run the existing thumbnail backfill to fill immediately).
Consequences
Quality: weak-basis faces stop driving automatic assignment immediately at the next run (no recluster prerequisite); they remain visible in the face-review surface so the owner decides manually — the exact requested behavior. The measured -29% wrong-card reduction at the recommended thresholds comes on top of ADR 0122's sweep gain; correct cards are demoted, not destroyed, so the probe's -24% 'correct card' cost converts into review-channel volume, not lost assignments. Blur detection needs no new detector: V138's crop quality score is the blur proxy, already computed with 100% coverage.
Costs: (1) feed rows grow by one optional float; (2) two discovery_domains columns + two admin fields; (3) one optional predicate threaded through the v6 emission path — v1-v5 untouched, golden fixtures unchanged; (4) review-only volume may grow when the gate first flips on (weak faces that used to ride auto-suggestions now land in review) — bounded by the probe's face-level threshold quantiles (conf < 0.6 ~ 7% of faces, quality < 0.25 ~ 21% on this library; intersection smaller).
Risks: gating a face that WAS the only member binding a group to an identity can flip that group's outcome (e.g. wholeGroup empty → C/new-person) — this is the intended semantics (the card's basis was the weak face) but changes card shapes vs the previous run; candidates remain comparable within their stamp generation, and contract version stays 5 (no envelope/wire change; the gate is emission-scoped like the review-only demotion already is). Stacked with the anchor gate, an all-weak-library edge could reduce suggestions broadly — the NULL default plus per-domain tuning is the guard.
Revisit triggers: owner finds review volume excessive (raise thresholds toward drop semantics or revisit the demote channel); embedding-model upgrade changes which faces are weak (probe rerun per ADR 0122 V6 practice); auto-accept policy interactions (a demoted card can never auto-accept — verify the auto-accept retrospective ignores review-only candidates, which it already does).
Tests. (1) Feed: rows carry qualityScore when quality_score is non-NULL; NULL/absent tolerated; both UNION branches covered. (2) Worker: eligible-predicate units — gated member excluded from refs but present in partition; all-gated group emits nothing; mixed group claims eligible members only; qualifying-set computation ignores gated members; fail-open on absent detectionConfidence/qualityScore; thresholds outside [0,1] disable the gate; v1-v5 call sites byte-identical (no predicate passed). (3) Settings threading: v6 jobs snapshot both keys; v1-v5 jobs don't; out-of-window values disable. (4) API: persists settings columns; operatorStatus exposes them; admin UI round-trip. (5) E2E golden: best-cell fixture with gate on — card refs exclude gated faces; occurrence states unchanged for gated faces (recognized + marked). (6) CV: harness lane with demotion semantics — hard-error rate no regression, manual-visibility assertion.
Rejected alternatives. (1) Hard drop of suggestions from weak faces (the probe's strict all-members-pass) — measured worse: -17% wrong for -21% correct at quality 0.25; loses the owner's manual channel. (2) Excluding gated faces from the partition/clustering entirely — loses density evidence and contradicts 'recognized and marked'; also orphans faces from re-proposal (the ISSUE-082 family). (3) Blur detector in the media worker — unnecessary; V138 quality score already measures crop sharpness/exposure deterministically. (4) API-side filtering of cards post-submission — emission is the worker's responsibility; API-side filters would desync card refs from worker evidence and complicate audit. (5) One combined 'pool_quality' knob mixing both signals — two signals have different semantics (detector certainty vs crop quality); separate knobs keep the CV axes clean and the operator story honest.
Non-goals. No anchor-gate change (ADR 0119 stands). No scoring, envelope, contract, or cache change (emission-scoped). No v1-v5 behavior change. No auto-accept policy change (review-only cards already never auto-accept). No new quality model. No default enablement (owner flips per domain).
Links: 0119 — amended: anchor gate (evidence-side) gains its pool-side complement (emission-side); shared fail-open/threading/UI discipline. 0122 — its V6 sweep cell is the measurement base; the probe extends that harness. 0108/0114 — representative/evidence machinery untouched (pool faces stay in the partition; digests unchanged). V138 — the quality_score column this ADR surfaces into the worker feed. spec-050 — tentative/pending semantics unchanged: gated faces stay pending and re-proposable. 0103 — qualityScore card field distinct from the face-crop quality score (name collision noted; different tables, different roles).
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