feat(people): exact-ID face-data recovery endpoint for PR#718 incident #719
Loading…
Reference in a new issue
No description provided.
Delete branch "fix/face-recovery-endpoint"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
What
Owner-scoped exact-ID face-data recovery endpoint closing the deferred-repair gap tracked as ISSUE-031 (incident fixed by PR #718, merged
eef360d1/ v1.21.29).requireSuperAdminUserId, same pattern as the other/admin/discovery/*endpoints).ProcessingIssueService). Dry-run is read-only and needs no maintenance window.Recovery contract (implemented verbatim)
state='accepted'people/person candidates for the owner,ORDER BY created_at,LIMIT 500, idempotent + resumable by rerun.existing_instance_id, elseclass_instance_review_decisions.details->>'classInstanceId'from the acceptance decision. Both missing, or target not active (owner+domain+class+lifecycle='active') →ambiguous_skipped. Never creates instances.faceAnnotationIds fromoccurrence_refs ∪ representative_evidence. NomediaItemId:indexinference.superseded/rejected/ owner-domain mismatch →faces_unresolved(reported, never invented). Accepted occurrence already on a different instance →conflict_skipped(insert-only, review-718 invariant I1 — no steal, no UPDATE-move).state='removed'occurrences are never resurrected.ON CONFLICT (domain_key, owner_id, occurrence_type, occurrence_key) DO NOTHING RETURNING id— occurrence_typeface_annotation, key<faceId>, ref enriched withscope(PR#718 shape), provenancesourceType:"incident_recovery_pr718".embeddings_flushed(equivalent to theOccurrenceCreatedEvent/flush-listener outcome, but deterministic within the recovery transaction).dryRun=true= steps 1–4 read-only, zero writes. Non-dry-run appends an audit row toclass_instance_review_decisions(CHECK constraint respected, decisionaccepted,sourceType:"incident_recovery_pr718").Report:
dryRun, nextCursor, candidatesRemaining, batchScanned, candidatesApplied, occurrencesCreated, occurrencesAlreadyPresent, facesUnresolved, facesRemovedSkipped, noFacesRecorded, conflictSkipped, ambiguousSkipped, embeddingsFlushed.Changelog (QA round 2, head
615b8217)(created_at, id)— requestcursorparam, responsenextCursor+candidatesRemaining; one call = one atomic batch ≤500; termination =candidatesRemaining=0.dryRundefault → explicit-safetrue.no_faces_recordedsplit fromambiguous_skipped;faces_removed_skippedown counter.:apps:api:test: 799 tests, 0 failures. Worker untouched.Changelog (QA round 3)
nextCursoris exposed via@JsonProperty, verified by a MockMvc + real-PostgreSQL HTTP round-trip test.FaceRecoveryServiceTest18,DiscoveryControllerTest49, full:apps:api:test804 tests, 0 failures.Tests
FaceRecoveryServiceTest— Testcontainers real PostgreSQL + full Flyway chain (fixture style ofPr718IntegrityRegressionTest), 9 cases, all green:goldenIncident…idempotentSecondRun…occurrences_created=0,already_present=1, no re-flushmultiFaceMediaFacesMapToTheirExactInstancesconflictFaceAcceptedElsewhere…conflict_skipped, original assignment untouchedmissingAndSupersededFaces…faces_unresolved, nothing inventedremovedOccurrenceIsNeverResurrectedstate='removed'stays removedcandidateWithoutResolvableTarget…ambiguous_skipped, zero instance creationcrossOwnerCandidateFaces…dryRunWritesNothing…Full
rtk ./gradlew :apps:api:test: 792 tests, 0 failures (superset incl. all 79 pre-existing suite tests). No worker changes.Ops runbook (post-merge, ops lane only)
PeopleDiscoveryRecognitionSchedulerdoes NOT honoroperator_state;POST /api/admin/discovery/domains/people/operator-policywithenabled=falsealone does NOT stop recognition-job enqueueing. Either stop the scheduler bean/worker container or empirically verify that no newowner_face_recognitionjobs are claimed. Keep scheduler/workers quiescent through steps 2–5.pg_dumpof the V115 people-table list (class_instances,class_instance_occurrences,class_instance_occurrence_candidates,class_instance_review_decisions,class_occurrence_embeddings,pending_face_embeddings,discovery_results, plus collaborative tables as listed inV115__clear_person_domain.sql).POST …/recover-faces?ownerId=<uuid>&dryRun=truewithout a cursor (omittingdryRunalso defaults to dry-run — omission is explicit-safe and never writes). Continue withPOST …/recover-faces?ownerId=<uuid>&dryRun=true&cursor=<nextCursor>untilcandidatesRemaining=0; verify aggregate reported counts across ALL pages (occurrencesCreated= would-create volume; sanity-checkconflictSkipped,ambiguousSkipped, andfacesUnresolved). One call = one atomic batch of ≤500 accepted candidates ordered(created_at, id); at completionnextCursoris null. Repeat the full walk per owner (endpoint is owner-scoped by design).POST …/recover-faces?ownerId=<uuid>&dryRun=false(maintenance mode must be off — service enforcesrequireWritable). Continue withPOST …/recover-faces?ownerId=<uuid>&dryRun=false&cursor=<nextCursor>untilcandidatesRemaining=0, for every owner. Aggregate all pages; do not stop after the first batch. Reruns without a cursor are safe (idempotent, zero new writes) but re-examine the first batch.class_instance_occurrencesfor a recovered face and confirmpending_face_embeddingsdrained (embeddingsFlushed).KNOWN_ISSUES
ISSUE-031 will be updated by this PR once merged: recovery endpoint delivered; issue stays open until the ops recovery run completes.
Notes / deviations
OccurrenceCreatedEventper row — same end state, deterministic, avoids transactional-listener-after-commit semantics inside a batch admin operation.PendingEmbeddingFlushListenerremains untouched for the production acceptance path.maintenanceModeServicenull-guarded for direct-service test construction; the controller always injects the real bean.QA (tes-2) blocker: selection never advanced — rerun re-scanned the same first 500 accepted candidates forever; candidates 501+ unreachable; 'rerun until candidates_scanned=0' could not terminate. - Keyset cursor on (created_at, id): request params cursor ('<createdAtInstant>|<candidateId>' or null = start); response report gains nextCursor + candidatesRemaining (0 = drained, nextCursor null). One call = one atomic batch of <=500; false 'per-candidate transactions' javadoc corrected. - dryRun default flipped to explicit-safe TRUE (omission never writes); endpoint + runbook documented. - Report nit: no_faces_recorded distinct from ambiguous_skipped; faces_removed_skipped own counter (state='removed' no longer conflated with unresolved). - PG typed-null fix: CAST(:afterCreatedAt AS timestamptz)/(:afterId AS uuid) keyset predicates. - Tests (all real PG): 505-candidate cursor walk to completion + drained-rerun no-op writes; malformed cursor rejected; dry-run cursor paging writes nothing; 403 for non-super-admin; delegation + maintenance-mode blocks dryRun=false / allows true; golden shape now asserts occurrence_ref scope enrichment + provenance sourceType=incident_recovery_pr718. FaceRecoveryServiceTest 14/14 green; DiscoveryControllerTest green; full :apps:api:test 799 tests 0 failures; worker untouched.