2 ADR 0098 occurrence state is the sole confirmation axis
Forgejo Actions edited this page 2026-10-03 23:11:42 +00:00

ADR 0098: Occurrence state is the sole confirmation axis

Status: accepted Date: 2026-09-27 Supersedes: 0097 Notes: Amended by ADR 0102 (2026-10-03, semisupervised-v1 only): exactly two clauses above change scope. (1) 'silent automation consumes only unassigned faces ... capped at 25 faces per candidate': the consumption-restriction half now reads 'silent automation consumes only unassigned faces AND movable live tentative faces' under clusteringMethod=semisupervised-v1 — tentatives join the unlabeled clustering pool, can be re-proposed onto a different person, and can be released; they are never anchors, never in centroids, never cannot-link or step-1 sources, and accepted rows remain untouchable (the 25-face cap wording itself is unchanged and still does not apply to semisupervised-v1). (2) 'scheduler pending-work counts faces with no live occurrence (accepted or tentative)': pending work ALSO counts faces whose ONLY live occurrence is state='tentative' (the reconciliation scheduler keeps the dirty marker for such owners so cluster shifts re-cluster); no other clause is amended, and tentative = system-assigned awaiting owner (never confirmed) stands.

Context

ADR 0097 introduced class_instance_occurrences.assignment_basis (user_confirmed|auto_assigned) to distinguish owner-confirmed from system-assigned faces while keeping the accepted lifecycle state dual-meaning. The 045->048 arc (specs 045-048, PRs 876/885/887/888/890/892/893/894/896) replaced that compromise: V141 added the occurrence lifecycle state 'tentative', V142 retired the basis column entirely. Owner-confirmed invariant now holds structurally: accepted means confirmed (explicit owner action or owner-activated strong-band policy); tentative means system-assigned awaiting owner (never an anchor, never in centroids, visible as Auto-assigned); bands are fully symmetric for named and stashed targets; silent automation consumes only unassigned faces and is capped at 25 faces per candidate.

Decision

Occurrence state is the sole confirmation axis: accepted|tentative|superseded|removed. assignment_basis is dropped (V142); forensics live in class_instance_review_decisions action strings. Rollback note: emergency rollback to a pre-V142 API image requires ALTER TABLE class_instance_occurrences ADD COLUMN assignment_basis TEXT (nullable, no backfill) because pre-P3 code writes the column. Anchor/consensus/disband-signature predicates are accepted-only by state; scheduler pending-work counts faces with no live occurrence (accepted or tentative).

Consequences

V141-backfill predicate lost its dedicated regression test when V142 dropped the column (accepted residual risk, historical migration). decideAssignments in ClassInstanceService is candidate dead code after the tentativeAssignments endpoint retirement - verify and remove in cleanup. Anchor-side occurrence_count stays accepted-only (display-only). Tracked follow-ups: per-face crops/curation UX for tentatives on media overlay, worker-side DBSCAN chaining quality (distinct persons bridged pre-stash), stale-card sweep if carousel noise accumulates.