fix(people): return known-person faces in owner-face-embeddings (fix empty similarity suggestions) #714

Merged
chris merged 2 commits from fix/face-embeddings-known-persons into main 2026-09-07 19:42:41 +02:00
Owner

Root cause

OwnerFaceEmbeddingsController (worker endpoint GET /api/worker/jobs/{jobId}/owner-face-embeddings) filters its accepted branch on discovery_results.state = 'owner_tentative' only. But accepted faces transition owner_tentative → owner_recognized via the V117 backfill + ClassInstanceDiscoveryService (L886-912) once their occurrence is accepted. Known-person faces therefore disappeared from the embedding fetch — the worker only ever saw still-tentative faces, producing empty similarity suggestions.

Fix

Accepted branch state filter: AND dr.state IN ('owner_tentative', 'owner_recognized') (one line). Pending branch unchanged (still owner_tentative only). No response-shape change, no dedup/ranking change, workers/people untouched.

ID-space proof (why no personId merge is needed)

class_instance_occurrences.occurrence_key stores discovery_results.id as text (V118 backfill joins on cio.occurrence_key = pfe.face_annotation_id::text; fixture inserts occurrence_key = faceAnnotationId.toString()). dr.id is the faceAnnotationId returned by this endpoint, and it is the same value used as the assignments key in the job payload (WorkerJobEnqueueService L187: cio.occurrence_key AS "faceAnnotationId"). Face→person mapping therefore already travels via the job payload assignments; no response change needed.

Assignments stay in the job payload

No size cap on job payload — documented no-premature-optimization (current stock ~3 embeddings per owner, ref ISSUE-027). Revisit only if payload size ever becomes real.

Scope notes

  • Spec 035 T007 (dedicated DiscoveryController embeddings endpoint) is not this PR — separate task.
  • Data-stock caveat: persons with zero embeddings (Rikke, Jesper) remain unmatched until embedding regeneration — separate decision, tracked separately.
  • workers/people (incl. main.py) unchanged. No migration changes. WorkerJobEnqueueService unchanged.

Tests

New OwnerFaceEmbeddingsControllerTest (Testcontainers + Flyway, mirrors PendingEmbeddingReconciliationSchedulerTest):

  • recognized (accepted-occurrence + coe embedding) face returned, tentative face returned, total 2 rows, owner B's accepted face absent (no cross-owner leak)
  • job payload assignments maps recognized face → person record

Verification: targeted test green; :apps:api:compileJava green; full cleanTest suite green — 772 tests, 0 failures, 0 errors (ISSUE-026 CI blindspot compensation).

Version bump: 1.21.26 → 1.21.27.

## Root cause `OwnerFaceEmbeddingsController` (worker endpoint `GET /api/worker/jobs/{jobId}/owner-face-embeddings`) filters its **accepted** branch on `discovery_results.state = 'owner_tentative'` only. But accepted faces transition `owner_tentative → owner_recognized` via the V117 backfill + `ClassInstanceDiscoveryService` (L886-912) once their occurrence is accepted. Known-person faces therefore disappeared from the embedding fetch — the worker only ever saw still-tentative faces, producing empty similarity suggestions. ## Fix Accepted branch state filter: `AND dr.state IN ('owner_tentative', 'owner_recognized')` (one line). Pending branch unchanged (still `owner_tentative` only). No response-shape change, no dedup/ranking change, workers/people untouched. ## ID-space proof (why no personId merge is needed) `class_instance_occurrences.occurrence_key` stores `discovery_results.id` as text (V118 backfill joins on `cio.occurrence_key = pfe.face_annotation_id::text`; fixture inserts `occurrence_key = faceAnnotationId.toString()`). `dr.id` **is** the `faceAnnotationId` returned by this endpoint, and it is the same value used as the `assignments` key in the job payload (`WorkerJobEnqueueService` L187: `cio.occurrence_key AS "faceAnnotationId"`). Face→person mapping therefore already travels via the job payload `assignments`; no response change needed. ## Assignments stay in the job payload No size cap on job payload — documented no-premature-optimization (current stock ~3 embeddings per owner, ref ISSUE-027). Revisit only if payload size ever becomes real. ## Scope notes - Spec 035 T007 (dedicated DiscoveryController embeddings endpoint) is **not** this PR — separate task. - Data-stock caveat: persons with zero embeddings (Rikke, Jesper) remain unmatched until embedding regeneration — separate decision, tracked separately. - `workers/people` (incl. `main.py`) unchanged. No migration changes. `WorkerJobEnqueueService` unchanged. ## Tests New `OwnerFaceEmbeddingsControllerTest` (Testcontainers + Flyway, mirrors `PendingEmbeddingReconciliationSchedulerTest`): - recognized (accepted-occurrence + coe embedding) face **returned**, tentative face returned, total 2 rows, owner B's accepted face **absent** (no cross-owner leak) - job payload `assignments` maps recognized face → person record Verification: targeted test green; `:apps:api:compileJava` green; full `cleanTest` suite green — **772 tests, 0 failures, 0 errors** (ISSUE-026 CI blindspot compensation). Version bump: 1.21.26 → 1.21.27.
chore: bump version to 1.21.27
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 people worker image (push) Has been skipped
Build and Deploy / Smoke ML worker (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 / 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 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) Successful in 1m42s
651bf9295d
chris merged commit 44db0e0a3e into main 2026-09-07 19:42:41 +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!714
No description provided.