fix(api): admit owner_recognized faces with re-armed pending embeddings in owner-face-embeddings feed #987

Merged
chris merged 2 commits from fix/face-feed-owner-recognized into main 2026-10-02 18:21:26 +02:00
Owner

Problem

After a soft people clustering reset ("Personen-Clustering zurücksetzen"), face recognition goes silent for the affected owner.

PeopleClusteringResetService (soft reset) removes occurrences but deliberately leaves faces in discovery_results.state = 'owner_recognized' — its own comment says "the face stays in the recognition pool" — and re-arms their embeddings as pending_face_embeddings rows (provenance sourceType='people_clustering_reset').

However, the pending branch of the OwnerFaceEmbeddingsController feed's UNION ALL CTE filtered dr.state = 'owner_tentative' only. The re-armed owner_recognized faces matched the pending-embedding join but were rejected by the state predicate, making them invisible to every subsequent recognition run.

Verified production impact: ~17,970 owner_recognized faces of the affected owner were excluded. The worker then clustered an 8,681-face pool whose density graph had zero triangles and correctly emitted 0 candidates — recognition produced no suggestions at all.

Same bug family as ISSUE-082 (confirmed anchors disappeared from matching after auto-accept, fixed in PR #976).

Root cause

Branch 2 of the CTE in OwnerFaceEmbeddingsController#getOwnerFaceEmbeddings:

FROM discovery_results dr
JOIN pending_face_embeddings pfe ON pfe.face_annotation_id = dr.id
WHERE dr.owner_id = :ownerId
  AND dr.domain_key = 'people'
  AND dr.state = 'owner_tentative'   -- ← excludes owner_recognized orphans

The soft reset's contract is: occurrences go away, the face stays in the recognition pool via a re-armed pending embedding. The feed's pending branch broke that contract by admitting only owner_tentative.

Fix

Widen the pending branch state filter:

AND dr.state IN ('owner_tentative', 'owner_recognized')

Nothing else changes:

  • Accepted-preference dedup is preserved. Both branches keep rn = 1 per (face_annotation_id, model_name, model_version); the global ranked CTE prefers source='accepted' over 'pending'. A face that regains a live accepted occurrence still resolves to its accepted embedding even when a re-armed pending row coexists (pinned by test).
  • The feed stays closed for truly orphaned faces. An owner_recognized face with neither a pending embedding nor an accepted occurrence is still excluded (pinned by test).
  • No reset-service changes, no state transitions of existing rows, no worker changes.

Test evidence

All in OwnerFaceEmbeddingsControllerTest (Testcontainers Postgres, mirroring the existing suite):

Test Covers
returnsOwnerRecognizedFaceWithReArmedPendingEmbedding Regression: fails on main, passes with fix (verified locally by reverting the controller change)
doesNotReturnOwnerRecognizedFaceWithoutPendingEmbeddingOrAcceptedOccurrence Feed stays closed for faces without evidence
acceptedOccurrenceStillWinsOverPendingEmbeddingForSameFace Dedup: accepted embedding wins when both sources exist
3 pre-existing tests Unchanged behavior preserved

Local runs:

  • rtk ./gradlew :apps:api:test --tests '*OwnerFaceEmbeddings*' → 6/6 passed
  • rtk ./gradlew :apps:api:test --tests 'dev.memories.api.people.*' → 199/199 passed, 0 failures (21 test classes, 2m16s)
## Problem After a soft people clustering reset ("Personen-Clustering zurücksetzen"), face recognition goes silent for the affected owner. `PeopleClusteringResetService` (soft reset) removes occurrences but **deliberately** leaves faces in `discovery_results.state = 'owner_recognized'` — its own comment says *"the face stays in the recognition pool"* — and re-arms their embeddings as `pending_face_embeddings` rows (provenance `sourceType='people_clustering_reset'`). However, the **pending branch** of the `OwnerFaceEmbeddingsController` feed's UNION ALL CTE filtered `dr.state = 'owner_tentative'` only. The re-armed `owner_recognized` faces matched the pending-embedding join but were rejected by the state predicate, making them **invisible to every subsequent recognition run**. **Verified production impact:** ~17,970 `owner_recognized` faces of the affected owner were excluded. The worker then clustered an 8,681-face pool whose density graph had **zero triangles** and correctly emitted **0 candidates** — recognition produced no suggestions at all. Same bug family as ISSUE-082 (confirmed anchors disappeared from matching after auto-accept, fixed in PR #976). ## Root cause Branch 2 of the CTE in `OwnerFaceEmbeddingsController#getOwnerFaceEmbeddings`: ```sql FROM discovery_results dr JOIN pending_face_embeddings pfe ON pfe.face_annotation_id = dr.id WHERE dr.owner_id = :ownerId AND dr.domain_key = 'people' AND dr.state = 'owner_tentative' -- ← excludes owner_recognized orphans ``` The soft reset's contract is: occurrences go away, the face stays in the recognition pool via a re-armed pending embedding. The feed's pending branch broke that contract by admitting only `owner_tentative`. ## Fix Widen the pending branch state filter: ```sql AND dr.state IN ('owner_tentative', 'owner_recognized') ``` Nothing else changes: - **Accepted-preference dedup is preserved.** Both branches keep `rn = 1` per `(face_annotation_id, model_name, model_version)`; the global `ranked` CTE prefers `source='accepted'` over `'pending'`. A face that regains a live accepted occurrence still resolves to its accepted embedding even when a re-armed pending row coexists (pinned by test). - **The feed stays closed for truly orphaned faces.** An `owner_recognized` face with neither a pending embedding nor an accepted occurrence is still excluded (pinned by test). - No reset-service changes, no state transitions of existing rows, no worker changes. ## Test evidence All in `OwnerFaceEmbeddingsControllerTest` (Testcontainers Postgres, mirroring the existing suite): | Test | Covers | |---|---| | `returnsOwnerRecognizedFaceWithReArmedPendingEmbedding` | Regression: **fails on main, passes with fix** (verified locally by reverting the controller change) | | `doesNotReturnOwnerRecognizedFaceWithoutPendingEmbeddingOrAcceptedOccurrence` | Feed stays closed for faces without evidence | | `acceptedOccurrenceStillWinsOverPendingEmbeddingForSameFace` | Dedup: accepted embedding wins when both sources exist | | 3 pre-existing tests | Unchanged behavior preserved | Local runs: - `rtk ./gradlew :apps:api:test --tests '*OwnerFaceEmbeddings*'` → **6/6 passed** - `rtk ./gradlew :apps:api:test --tests 'dev.memories.api.people.*'` → **199/199 passed, 0 failures** (21 test classes, 2m16s)
fix(api): admit owner_recognized faces with re-armed pending embeddings in owner-face-embeddings feed
Some checks failed
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 3s
Build and Deploy / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Failing after 1m33s
f8a6ffd400
The pending branch of the owner-face-embeddings UNION ALL CTE filtered
discovery_results.state = 'owner_tentative' only. But PeopleClusteringResetService
(soft reset, 'Personen-Clustering zuruecksetzen') removes occurrences while
deliberately leaving faces in 'owner_recognized' — its own comment says 'the face
stays in the recognition pool' — and re-arms their embeddings as
pending_face_embeddings rows (provenance sourceType='people_clustering_reset').
Those re-armed faces were therefore invisible to every subsequent recognition run.

Verified in production: 17,970 owner_recognized faces of the affected owner were
excluded from the feed; the worker then clustered an 8,681-face pool whose density
graph had zero triangles and correctly emitted 0 candidates — recognition went
silent after any clustering reset. Same bug family as ISSUE-082 (confirmed anchors
disappeared from matching after auto-accept, fixed in PR #976).

Fix: widen the pending branch to dr.state IN ('owner_tentative', 'owner_recognized').
Nothing else changes: a face that regains a live accepted occurrence still resolves
to its accepted embedding — both branches keep rn=1 per
(face_annotation_id, model_name, model_version), and the global ranked CTE prefers
source='accepted' over 'pending'. Faces with no evidence (no pending embedding, no
accepted occurrence) remain excluded, so the feed stays closed for truly orphaned
faces.

Regression tests (Testcontainers Postgres, mirroring the existing suite):
- owner_recognized + re-armed pending embedding is fed (fails on main, passes with fix)
- owner_recognized without evidence is NOT fed
- accepted occurrence still wins over a coexisting pending row for the same face
chore: re-trigger CI (Testcontainers/docker-infra flake in prior run)
All checks were successful
Build and Deploy / Detect changed services and test scopes (push) Successful in 2s
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 4m37s
6af236b944
chris merged commit cfe9627022 into main 2026-10-02 18:21:26 +02:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
chris/memories!987
No description provided.