feat(people): re-arm face recognition on person edits (spec 038) #760

Merged
chris merged 2 commits from feat/people-merge-suggestions into main 2026-09-18 22:47:31 +02:00
Owner

Spec 038. Based on origin/main 80437ff7.

What / why

Person edits (rename/merge/split/dissolve, face assign/remove/confirm) change the assignment set that face recognition matches against, but recognition only armed on NEW embedding evidence (face_recognition_cursor watermark, V121). Already-seen owner_tentative faces were never re-matched after users named/merged persons. This PR adds owner-scoped dirty markers + a reconcile scheduler that re-enqueues owner_face_recognition deliberately WITHOUT the unseen-embedding guard (job completion stamps the cursor, so no infinite loop).

  • V126__face_recognition_dirty.sql (owner_id PK/FK media_owner_profiles, marked_at)
  • FaceRecognitionDirtyMarkService: idempotent upsert (ANSI MERGE — H2 rejects ON CONFLICT DO UPDATE; PostgreSQL-compatible)
  • Mark points inside the edit transactions: ClassInstanceService renamePerson / mergePeopleRecords / removeMediaFromPerson (x2) / confirmMediaForPerson / moveMediaToPerson / nameFaceAsPerson / assignFaceToPerson + generic occurrence remove/confirm/move (people-guarded); ClassInstanceDiscoveryService updateInstance / dissolveInstance / mergeInstance / splitInstance (people-guarded)
  • FaceRecognitionReconcileScheduler (fixedDelay 60s): drop marker when no owner_tentative faces (steady state), skip while a recognition job is queued/leased/running, else enqueue + delete marker
  • Task A (merge-suggestion endpoints): already live since 72f06e61 (generic GET/POST /api/discovery/domains/{domainKey}/merge-suggestion[/reject], threshold 0.5, rejection filtering, deterministic ranking, full test coverage). Removed orphaned legacy PersonMergeSuggestionView types from discovery.ts.
  • Bounded fixes to latent SQL bugs in personDetail paths exposed by new tests (same class as 919370f1): missing :domainKey/:classKey bindings in personMedia/personSummary; dr2.detection_confidence -> dr2.confidence; dr.confidence alias for representativeFaces mapper; media_owner_profiles.display_name in H2 test schema.

Test plan

  • rtk ./gradlew :apps:api:compileJava — green
  • Full rtk ./gradlew :apps:api:test — green (incl. new FaceRecognitionReconcileSchedulerTest, ClassInstanceServiceTest dirty-mark cases, existing People / MergeSuggestion / FaceRecognition suites)
  • apps/web npm run check — 0 errors
  • Migration naming/style consistent with V121-V125; no Python changes, no cursor-semantics changes
Spec 038. Based on origin/main 80437ff7. ## What / why Person edits (rename/merge/split/dissolve, face assign/remove/confirm) change the assignment set that face recognition matches against, but recognition only armed on NEW embedding evidence (face_recognition_cursor watermark, V121). Already-seen owner_tentative faces were never re-matched after users named/merged persons. This PR adds owner-scoped dirty markers + a reconcile scheduler that re-enqueues owner_face_recognition deliberately WITHOUT the unseen-embedding guard (job completion stamps the cursor, so no infinite loop). - V126__face_recognition_dirty.sql (owner_id PK/FK media_owner_profiles, marked_at) - FaceRecognitionDirtyMarkService: idempotent upsert (ANSI MERGE — H2 rejects ON CONFLICT DO UPDATE; PostgreSQL-compatible) - Mark points inside the edit transactions: ClassInstanceService renamePerson / mergePeopleRecords / removeMediaFromPerson (x2) / confirmMediaForPerson / moveMediaToPerson / nameFaceAsPerson / assignFaceToPerson + generic occurrence remove/confirm/move (people-guarded); ClassInstanceDiscoveryService updateInstance / dissolveInstance / mergeInstance / splitInstance (people-guarded) - FaceRecognitionReconcileScheduler (fixedDelay 60s): drop marker when no owner_tentative faces (steady state), skip while a recognition job is queued/leased/running, else enqueue + delete marker - Task A (merge-suggestion endpoints): already live since 72f06e61 (generic GET/POST /api/discovery/domains/{domainKey}/merge-suggestion[/reject], threshold 0.5, rejection filtering, deterministic ranking, full test coverage). Removed orphaned legacy PersonMergeSuggestionView types from discovery.ts. - Bounded fixes to latent SQL bugs in personDetail paths exposed by new tests (same class as 919370f1): missing :domainKey/:classKey bindings in personMedia/personSummary; dr2.detection_confidence -> dr2.confidence; dr.confidence alias for representativeFaces mapper; media_owner_profiles.display_name in H2 test schema. ## Test plan - [x] rtk ./gradlew :apps:api:compileJava — green - [x] Full rtk ./gradlew :apps:api:test — green (incl. new FaceRecognitionReconcileSchedulerTest, ClassInstanceServiceTest dirty-mark cases, existing *People* / *MergeSuggestion* / *FaceRecognition* suites) - [x] apps/web npm run check — 0 errors - [x] Migration naming/style consistent with V121-V125; no Python changes, no cursor-semantics changes
feat(people): re-arm face recognition on person edits (spec 038)
All checks were successful
Build and Deploy / Detect changed services and test scopes (push) Successful in 3s
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 / Build plants worker image (push) Has been skipped
Build and Deploy / Build people 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 1m18s
4ef699a912
Task B — recognition dirty-mark + scheduled reconcile:
- V126__face_recognition_dirty.sql: owner-scoped dirty markers
  (owner_id PK FK media_owner_profiles, marked_at timestamptz)
- FaceRecognitionDirtyMarkService: idempotent upsert via ANSI MERGE
  (works on PostgreSQL prod and H2 regression suite; H2 rejects
  INSERT ... ON CONFLICT DO UPDATE)
- ClassInstanceService: mark dirty inside the edit transaction from
  renamePerson, mergePeopleRecords, removeMediaFromPerson (both
  overloads), confirmMediaForPerson, moveMediaToPerson,
  nameFaceAsPerson, assignFaceToPerson, and the generic occurrence
  remove/confirm/move curation endpoints (people-domain guarded)
- ClassInstanceDiscoveryService: mark dirty from updateInstance
  (rename), dissolveInstance, mergeInstance, splitInstance — guarded
  to domain_key='people'; new optional constructor dep, null-safe in
  existing test constructions
- FaceRecognitionReconcileScheduler (@Scheduled fixedDelay 60s):
  for each dirty owner, drop the marker when no owner_tentative faces
  remain (steady state), skip while an owner_face_recognition job is
  queued/leased/running, otherwise enqueue via
  WorkerJobEnqueueService.enqueueOwnerFaceRecognitionJob and delete
  the marker. Deliberately NOT gated on unseen-embedding evidence:
  the purpose is re-matching previously considered faces against the
  changed assignment set. Job completion stamps the face recognition
  cursor (V121 semantics unchanged), so no infinite loop.
- Tests: FaceRecognitionReconcileSchedulerTest (enqueue+delete,
  no-evidence re-arm, active-job skip, steady-state drop, multi-owner,
  idempotent upsert); ClassInstanceServiceTest dirty-mark cases
  (merge/rename/confirm mark once idempotently; generic domain does
  not; face naming marks)

Task A — merge-suggestion endpoints: already live since 72f06e61
(GET/POST /api/discovery/domains/{domainKey}/merge-suggestion[/reject]
+ ClassInstanceDiscoveryService.mergeSuggestion/rejectMergeSuggestion,
threshold 0.5, rejection filtering, deterministic ranking). Removed
the orphaned legacy PersonMergeSuggestionView/Person types from
discovery.ts.

Bounded fixes to dead-ish detail paths exposed by the new tests
(same bug class as 919370f1):
- personMedia/personSummary: bind missing :domainKey/:classKey params
- personSummary: dr2.detection_confidence -> dr2.confidence
- representativeFaces: alias dr.confidence AS detection_confidence
  for the row mapper
- test schema: media_owner_profiles.display_name column added

Validation: :apps:api:compileJava, full :apps:api:test (green),
web npm run check (0 errors).
chore: version bump 1.21.47
All checks were successful
Build and Deploy / Detect changed services and test scopes (push) Successful in 3s
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 / Build plants worker image (push) Has been skipped
Build and Deploy / Build people 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 2m36s
fa24903be4
chris merged commit 27848ed4e5 into main 2026-09-18 22:47:31 +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!760
No description provided.