fix(api): mint-time pending-overlap guard — never mint a second pending card for the same face #1055

Merged
chris merged 1 commit from fix/pending-overlap-mint-guard into main 2026-10-06 23:31:19 +02:00
Owner

Problem

Production duplicate carousel cards (verified 2026-10-06, face 60bf9b0d held by both a stash-shadow card and a named-person card): a pending card writes no occurrence rows, so the face stays unassigned, the next recognition run re-clusters it and mints a SECOND pending card for the same face against a different target. The decision path already treats overlapping pending cards as mutually exclusive (an accept runs overlapRejections and auto-rejects the sibling), so the stale sibling's decision errored (candidate-changed / Pending class-instance candidate not found) — and until then the carousel showed two cards for one face.

Fix (spec 047 S3)

Both insert paths — persistWorkerCandidates (next to PR #1052's cardHasFaceConfirmedElsewhere guard) and persistSemisupervisedCandidates — now skip a candidate WHOLE: no insert, no exception, no state change to the existing card.

Skip fires when any face_annotation ref already sits in occurrence_refs of another STILL-PENDING candidate scoped exactly like PeopleDomainCandidateDecisionStrategy.pendingCandidateRows (same owner, same domain, same class_key, state='pending', candidate_type <> 'face_detection') that targets a DIFFERENT instance (incl. targetless-vs-targeted):

  • Skip-new: the older card keeps its place and resolves through the normal decision flow; skips reduce the method's returned inserted count (per-candidate log.info + summary line when >0).
  • Same-target re-mint NOT skipped — that's the supersede / ADR 0102 absorb path's job (it REPLACES the old card).
  • Assigned-face exemption: a face with a LIVE occurrence (accepted/tentative) never trips the skip — minting over an assigned face is the designed Spec050 retarget / no-steal flow that repairs the old card. Only an UNASSIGNED face held by a pending card is the duplicate-carousel shape.
  • Intra-batch: first candidate in payload order wins; later same-face candidates of the SAME payload skipped (unconditional claim).
  • Media-only refs / face_detection artifacts / other domains: no-op by construction (no face_annotation ids); no media-ref overlap logic added.
  • Pending rows + live-occurrence face set read lazily once per persist call (zero statements for payloads without face refs).

Tests (all green: rtk ./gradlew :apps:api:test — 1581 tests, 0 failures)

8 new fixture tests in ClassInstanceDiscoveryServiceTest:

  1. existing-pending{f1} + new{f1} to a different target → not inserted (count 0), older card untouched, face not even marked considered
  2. {f1,f2} skipped while {f1} pending, {f2}-only sibling still minted (skipped candidate claims nothing)
  3. rejected predecessor → next mint proceeds normally
  4. accepted predecessor (same target) → mint proceeds (ADR 0102 absorb, not skip)
  5. intra-batch shared f1 → only the first candidate's row is minted
  6. face_detection artifact + media-only payload → both insert normally
  7. semisupervised-v1 entry point applies the identical skip
  8. assigned-face exemption: tentative-backed holder + different-target re-mint inserts (retarget flow)

Unchanged and green: PR #1052 mint-guard tests, full Spec050SemisupervisedPostgresTest (46 tests incl. the 3 retarget-split tests).

Also

  • KNOWN_ISSUES.md: ISSUE-106 (med/mitigated/area:discovery)
  • spec 047: new section S3 documenting the mint-time pending-overlap skip + assigned-face exemption
  • version: 1.21.69 → 1.21.70
## Problem Production duplicate carousel cards (verified 2026-10-06, face `60bf9b0d` held by both a stash-shadow card and a named-person card): a **pending card writes no occurrence rows**, so the face stays unassigned, the next recognition run re-clusters it and mints a SECOND pending card for the same face against a different target. The decision path already treats overlapping pending cards as mutually exclusive (an accept runs `overlapRejections` and auto-rejects the sibling), so the stale sibling's decision errored (`candidate-changed` / `Pending class-instance candidate not found`) — and until then the carousel showed two cards for one face. ## Fix (spec 047 S3) Both insert paths — `persistWorkerCandidates` (next to PR #1052's `cardHasFaceConfirmedElsewhere` guard) and `persistSemisupervisedCandidates` — now skip a candidate **WHOLE**: no insert, no exception, no state change to the existing card. Skip fires when any `face_annotation` ref already sits in `occurrence_refs` of another STILL-PENDING candidate scoped exactly like `PeopleDomainCandidateDecisionStrategy.pendingCandidateRows` (same owner, same domain, same class_key, `state='pending'`, `candidate_type <> 'face_detection'`) **that targets a DIFFERENT instance** (incl. targetless-vs-targeted): - **Skip-new**: the older card keeps its place and resolves through the normal decision flow; skips reduce the method's returned inserted count (per-candidate `log.info` + summary line when >0). - **Same-target re-mint NOT skipped** — that's the supersede / ADR 0102 absorb path's job (it REPLACES the old card). - **Assigned-face exemption**: a face with a LIVE occurrence (accepted/tentative) never trips the skip — minting over an assigned face is the designed Spec050 retarget / no-steal flow that repairs the old card. Only an UNASSIGNED face held by a pending card is the duplicate-carousel shape. - **Intra-batch**: first candidate in payload order wins; later same-face candidates of the SAME payload skipped (unconditional claim). - **Media-only refs / face_detection artifacts / other domains**: no-op by construction (no face_annotation ids); no media-ref overlap logic added. - Pending rows + live-occurrence face set read lazily **once per persist call** (zero statements for payloads without face refs). ## Tests (all green: `rtk ./gradlew :apps:api:test` — 1581 tests, 0 failures) 8 new fixture tests in `ClassInstanceDiscoveryServiceTest`: 1. existing-pending{f1} + new{f1} to a different target → not inserted (count 0), older card untouched, face not even marked considered 2. {f1,f2} skipped while {f1} pending, {f2}-only sibling still minted (skipped candidate claims nothing) 3. rejected predecessor → next mint proceeds normally 4. accepted predecessor (same target) → mint proceeds (ADR 0102 absorb, not skip) 5. intra-batch shared f1 → only the first candidate's row is minted 6. face_detection artifact + media-only payload → both insert normally 7. semisupervised-v1 entry point applies the identical skip 8. assigned-face exemption: tentative-backed holder + different-target re-mint inserts (retarget flow) Unchanged and green: PR #1052 mint-guard tests, full Spec050SemisupervisedPostgresTest (46 tests incl. the 3 retarget-split tests). ## Also - `KNOWN_ISSUES.md`: ISSUE-106 (med/mitigated/area:discovery) - spec 047: new section S3 documenting the mint-time pending-overlap skip + assigned-face exemption - version: 1.21.69 → 1.21.70
fix(api): mint-time pending-overlap guard — never mint a second pending card for the same face
All checks were successful
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) Successful in 7m58s
0adb7b5605
Production duplicate carousel cards (face 60bf9b0d held by two pending
cards): a pending card writes no occurrence rows, so the face stays
unassigned and every recognition run re-mints a second pending card for
it against a different target; the decision path then treats the pair as
mutually exclusive and the stale sibling's decision errored.

Both insert paths (persistWorkerCandidates and persistSemisupervisedCandidates)
now skip a candidate WHOLE — no insert, no exception, no state change to
the existing card — when any face_annotation ref already sits in a
still-pending candidate for the same owner + domain + class_key
(state='pending', candidate_type <> 'face_detection', mirroring
PeopleDomainCandidateDecisionStrategy.pendingCandidateRows) that targets
a DIFFERENT instance (spec 047 S3):

- skip-new: the older card keeps its place; skipped candidates reduce
  the returned inserted count (per-candidate + summary log lines);
- same-target re-mints stay on the supersede / ADR 0102 absorb path;
- faces with a LIVE occurrence (accepted/tentative) are exempt — minting
  over an assigned face is the Spec050 retarget / no-steal flow that
  repairs the old card (keeps the retarget-split tests green);
- intra-batch: first candidate in payload order wins (unconditional);
- media-only refs / face_detection artifacts: no-op by construction;
- pending rows read lazily once per persist call (no statement for
  payloads without face refs).

Tests: 8 new fixture tests in ClassInstanceDiscoveryServiceTest covering
skip-different-target, partial-batch sibling, decided predecessors
(rejected + accepted), intra-batch first-wins, media-only/artifact
non-trips, the assigned-face exemption, and the semisupervised entry
point. Full :apps:api:test green (1581 tests, incl. PR #1052 mint-guard
and Spec050 retarget suites). Version 1.21.70, KNOWN_ISSUES ISSUE-106.
chris merged commit a9b7633939 into main 2026-10-06 23:31:19 +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!1055
No description provided.