1 ADR 0102 tentative occurrences are movable unlabeled pool members
Forgejo Actions edited this page 2026-10-03 23:11:42 +00:00

ADR 0102: Tentative occurrences are movable unlabeled pool members under semisupervised-v1

Status: accepted Date: 2026-10-03 Supersedes: 0101 Notes: Owner decisions i (C card with tentative faces; confirm retargets old tentative occurrence to the new person) and ii (outcome-A tentative faces are released back to unassigned) are the product decisions this ADR records; both were fixed by the review that produced this revision of spec 050.

Context

ADR 0101 froze the tentative-assignment semantics of ALLOCATE_TENTATIVE_KEEP_PENDING to the worker export contract that existed for the LEGACY methods: faces tentatively auto-assigned to a person were exported in tentativeAssignments and treated by the worker as assigned (excluded from the clustering pool, no anchors, no re-proposal) to avoid candidate churn. That freeze made a WRONG automatic tentative assignment sticky: the face could never be re-proposed onto a different person when clusters shifted, an owner-confirming a C (new_person_cluster) card that contained a face tentatively held by another person was silently blocked by the no-steal filter, and a tentative face that ended in outcome A (isolated singleton, no candidate) stayed invisible-milestoned to its old person forever. Tentatives carried too much inertia: they behaved like accepted rows to the worker even though ADR 0098 explicitly reserves acceptance semantics for the accepted state.

Decision

Under clusteringMethod=semisupervised-v1 ONLY, faces with a LIVE TENTATIVE occurrence (occurrence state='tentative'; mirror discovery_results.state='owner_recognized') behave like UNASSIGNED faces with zero anchor power: (1) FEED — OwnerFaceEmbeddingsController branch 1 widens cio.state='accepted' to state IN ('accepted','tentative'); a tentative-occurrence face is fed only when its occurrence carries class_occurrence_embeddings rows, and accepted-level dedup still wins over pending rows. (2) POOL — the worker no longer adds tentativeAssignments faces to its assigned_faces set under single_pass methods (legacy methods byte-unchanged): tentatives join the unlabeled clustering pool, may appear in B/C candidates, have ZERO influence on other faces' assignments (never anchors, never centroids, never cannot-link or step-1 labels) and are subject to outcome A like any unlabeled face. (3) RELEASE SIGNAL — the result envelope carries an OPTIONAL releasedTentativeFaces: [faceId, ...] (plain unique canonical ids, subset of the job's own tentative set, duplicates/malformed rejected, optional field so SEMISUPERVISED_CONTRACT_VERSION stays 1) listing tentative faces that ended in outcome A. (4) APPLY — Core validates the envelope field and applies it via the EXISTING PeopleOccurrenceReleaseStrategy.releaseOccurrences (mirror reset to owner_tentative + embedding re-buffering; a bare occurrence-only supersede would strand the face invisible; idempotent no-op for already released/accepted-elsewhere faces). (5) ABSORB — a cluster_person_match candidate whose EVERY ref already holds a live occurrence (accepted OR tentative) on its OWN target instance inserts the card feed-through state='superseded' in the same transaction (no review decision, not added to processedFaceIds): same-instance replay is a card-level no-op and the carousel never shows a duplicate card for an already-live tentative; the superseded row stays in place and history lives in class_instance_review_decisions/audit_events, the candidates table does not accumulate (unique one-row-per-(worker_job_id, idempotency_key, candidate_index)). (6) RETARGET — the semisupervised unambiguous-scored B allocation arm (and ONLY that arm; later the explicit owner C-confirm) runs inside the ONE locked acceptance primitive an explicit tentatives-are-movable context flag: immediately before the assigned-refs filter, tentative occurrences of THIS candidate's refs that sit on a DIFFERENT instance are superseded (SQL: domain/owner/occurrence_type/occurrence_key IN refs, state='tentative', class_instance_id<>target, and NOT an occurrence written by this worker job), the existing reviveSupersededOccurrence path re-points the row to the target in place, and a defensive invariant throws when the release hit rows but ZERO occurrences were written (whole-transaction rollback). Accepted rows are NEVER touched (existing no-steal stays absolute) and this job's own rows are never released. (7) OLD-CARD REPAIR — after a successful retarget the OLD backing card's occurrence_refs are repaired via persistActionableSubset so refs, evidence and live tentatives still agree; owner-confirming the old card can never silently skip a face that already moved. (8) C-CONFIRM — owner-accepting a pending new_person_cluster card releases conflicting tentatives on OTHER instances the same way (target = newly minted or owner-chosen instance) before the new occurrences are written; release can throw nothing new: no-steal for ACCEPTED rows stays untouched. (9) SCHEDULER — FaceRecognitionReconcileScheduler's steady-state early-return additionally keeps the dirty marker (and enqueues) when the owner has faces whose ONLY live occurrence is state='tentative', so a clusters-shifted owner is not dropped without a re-clustering run; the 10-minute re-arm debounce and marker-delete-after-enqueue discipline are unchanged. ADR 0101 remains in force in every other clause (method/version snapshotting, envelope validation, A/B/C shapes, ambiguous explicit-target rule, backing-card/rollback/reset barriers); the ONLY superseded clause is its 'eligible unassigned' pool eligibility sentence — the pool is anchors minus nothing: confirmed anchors label, tentatives and unassigned faces are unlabelled members.

Consequences

Faces tentatively auto-assigned to person X can be re-proposed onto person Y by a later clustering run (card-level no-op for same-target replays, retarget for shifted targets) and by owner-confirming a C card that spans them (old X row superseded, single occurrence row on the new person, mirror stay owner_recognized). Owner decision surface grows by exactly two cases: C-cards MAY contain tentative faces (confirm retargets them) and a tentative face isolated in outcome A is released back to unassigned — both previously impossible. The legacy pinned behaviors (tentatives excluded from the legacy pool, never weak-consensus support, no legacy re-proposal churn; test_tentative_assignments.py and test_constrained_forward_clustering.py pins) remain byte-identical because only single_pass-gated code and semisupervised-routed persistence changed. releasedTentativeFaces is optional and unversioned; older Core results without it simply never release and the field is validated for shape only. Superseding history stays one-row-in-place: the candidates table does not accumulate superseded rows per face (history lives in audit_events and the decided row itself). Scheduler steady-state now keeps dirty markers for tentative-only owners (bounded: marker deleted after exactly one enqueue, 10-minute re-arm debounce).