feat(api): occurrence tentative state + symmetric bands (spec 048 P0-P1) #893

Merged
chris merged 8 commits from spec/048-accepted-means-confirmed into main 2026-09-26 22:19:22 +02:00
Owner

Summary

Spec 048 P0+P1. accepted now always means user-confirmed (explicit owner action OR owner-activated strong-band policy); system assignments live in the new occurrence lifecycle state tentative (assigned, awaiting owner review, never an anchor). Bands are symmetric for named and stash targets, the worker export split is state-derived, and the structural invariant "automatic writes consume only unassigned faces" is pinned by tests. assignment_basis is still written in lockstep (tentative ⇔ auto_assigned) and dropped later in P3 — no readers were removed in this lane. Worker and web untouched.

Migration (V141, next free after V140)

V141__occurrence_tentative_state.sql:

  1. idempotent named-constraint swap: class_instance_occurrences_state_check widened to (accepted|tentative|superseded|removed);
  2. backfill SET state='tentative' WHERE state='accepted' AND assignment_basis='auto_assigned';
  3. face mirror: those occurrences' discovery_results rows (accepted → owner_recognized, joined by occurrence_key = discovery_results.id);
  4. RAISE NOTICE count report (occurrences backfilled, faces mirrored).

Write arms were updated in the same PR so nothing orphans: the accept unit threads occurrenceState alongside the basis through insertOccurrenceNoSteal (H2 MERGE USING + PG ON CONFLICT), reviveSupersededOccurrence and upsertCandidateOccurrence; dissolve supersede, merge/split moves, overlap removal and the rejection guard all cover tentative; the disband negative signature stays accepted-only (confirmed core).

Gate matrix (implemented)

Band Named target Stash target
STRONG dist ≤ V104 min_distance AND conf ≥ V104 min_confidence policy ON → accepted (user_confirmed); policy OFF → tentative policy ON → accepted (user_confirmed core, no consensus — threshold is the guard); policy OFF → tentative
MEDIUM ≤ suggest_max, not strong consensus (≥2 user_confirmed core faces, ≥2 within min(0.5, suggest_max)) → tentative (policy-independent); else card same → tentative; else card
BEYOND suggest_max card card
ABSTAIN (no embeddings) card card
  • Cap 25 (SILENT_ACTION_MAX_CANDIDATE_FACES, #892) gates every silent path, including the new strong-policy-off arm; oversized → pending card, never rejected.
  • Spec 040 preserved: weakMatch=true stays suggestions-only on named targets (stashes keep the spec 039 promise via the symmetric gates).
  • Unassigned-only invariant: automatic paths are insert-only + filter live (accepted OR tentative) refs; an already-assigned face is never moved or upgraded by automation (new test with mixed refs asserts skippedCount=1 and the assigned face keeps its tentative state).
  • Anchor purity: export split and matchCandidateToExistingInstance anchors / consensus core are accepted-only (basis predicate kept during P1); the skew guard and ref filtering accept accepted-or-tentative.

Visible behavior changes

  • Policy OFF = nothing auto-confirms anywhere: strong-band matches (named AND stash) now land as tentative instead of accepted; the face mirror shows owner_recognized (not accepted). This is the headline semantic change.
  • Stash strong band can confirm again (spec 048 supersedes spec 047's whole-band consensus): with the owner policy ON, a strong match auto-accepts into the stash core (user_confirmed), no consensus needed; medium stays consensus-gated → tentative.
  • Named medium tier is policy-independent: the owner policy governs confirmation only; consensus-gated tentative assignment happens regardless (per S1 band symmetry).

Skew matrix

API Worker Behavior
new new Export split by state; anchors accepted-only; tentative faces ride tentativeAssignments
new old Re-proposals of a live occurrence (accepted OR tentative) on the target are superseded silently
old new Missing tentativeAssignments degrades to empty (unchanged); no crash
old old Unchanged except the new gates

Tests

  • Full API suite: rtk ./gradlew :apps:api:test --no-daemon → 1265 tests, 0 failures, 9 skipped.
  • New PG: Spec048TentativeStateMigrationPostgresTest (V141 re-run: predicate matrix, face mirror, idempotency, constraint swap, flyway history) and Spec048SymmetricBandsPostgresTest (strong policy matrix named+stash; medium tentative + face mirror; disband releases tentatives with core-only signature via a release-strategy-wired service; merge/split move tentatives; skew re-proposal of a live tentative superseded).
  • H2 parity: strong matrix, named strong policy-off, disband releases tentatives (empty-core fingerprint when no confirmed core exists), merge moves tentatives, unassigned-only mixed-refs, carousel/listing state reads.
  • Existing spec 045/047 PG+H2 fixtures updated to the new semantics; revival-loop and bulk-cap regression suites re-run green.

Notes

  • No version bump (pipeline-computed).
  • CI scoped detection scopes feature branches from merge-base(main, HEAD); this changeset includes a migration + api/worker/* path, which classifies it as a fallback-smoke changeset (compile + web/CLI/ML smoke) — the API unit steps are skipped by the workflow's own condition. Full API suite verified locally; covered on main by the deploy/daily-full-tests lanes.
  • For P2 (T003): occurrence readers (person media, counts, representative selection, knn) still filter accepted; they need accepted+tentative reads, honest "Confirmed" tab, cards-for-tentatives accept/reject and person-page bulk confirm (which must upgrade an existing tentative occurrence in place). For P3 (T004): drop assignment_basis and the remaining basis predicates, plus the regression suite (revival loop, Holger cap, disband releases, merge/split, export shapes, face mirror, automatic-paths-never-touch-assigned).
## Summary Spec 048 P0+P1. **`accepted` now always means user-confirmed** (explicit owner action OR owner-activated strong-band policy); system assignments live in the new occurrence lifecycle state **`tentative`** (assigned, awaiting owner review, never an anchor). Bands are symmetric for named and stash targets, the worker export split is state-derived, and the structural invariant "automatic writes consume only unassigned faces" is pinned by tests. `assignment_basis` is still written in lockstep (tentative ⇔ auto_assigned) and dropped later in P3 — no readers were removed in this lane. Worker and web untouched. ## Migration (V141, next free after V140) `V141__occurrence_tentative_state.sql`: 1. idempotent named-constraint swap: `class_instance_occurrences_state_check` widened to `(accepted|tentative|superseded|removed)`; 2. backfill `SET state='tentative' WHERE state='accepted' AND assignment_basis='auto_assigned'`; 3. face mirror: those occurrences' `discovery_results` rows (`accepted` → `owner_recognized`, joined by `occurrence_key = discovery_results.id`); 4. `RAISE NOTICE` count report (occurrences backfilled, faces mirrored). Write arms were updated in the same PR so nothing orphans: the accept unit threads `occurrenceState` alongside the basis through `insertOccurrenceNoSteal` (H2 MERGE USING + PG ON CONFLICT), `reviveSupersededOccurrence` and `upsertCandidateOccurrence`; dissolve supersede, merge/split moves, overlap removal and the rejection guard all cover `tentative`; the disband negative signature stays accepted-only (confirmed core). ## Gate matrix (implemented) | Band | Named target | Stash target | |---|---|---| | STRONG `dist ≤ V104 min_distance AND conf ≥ V104 min_confidence` | policy ON → **accepted** (user_confirmed); policy OFF → **tentative** | policy ON → **accepted** (user_confirmed core, no consensus — threshold is the guard); policy OFF → **tentative** | | MEDIUM `≤ suggest_max, not strong` | consensus (≥2 user_confirmed core faces, ≥2 within `min(0.5, suggest_max)`) → **tentative** (policy-independent); else card | same → **tentative**; else card | | BEYOND `suggest_max` | card | card | | ABSTAIN (no embeddings) | card | card | - Cap 25 (`SILENT_ACTION_MAX_CANDIDATE_FACES`, #892) gates **every** silent path, including the new strong-policy-off arm; oversized → pending card, never rejected. - Spec 040 preserved: `weakMatch=true` stays suggestions-only on named targets (stashes keep the spec 039 promise via the symmetric gates). - **Unassigned-only invariant**: automatic paths are insert-only + filter live (accepted OR tentative) refs; an already-assigned face is never moved or upgraded by automation (new test with mixed refs asserts `skippedCount=1` and the assigned face keeps its tentative state). - Anchor purity: export split and `matchCandidateToExistingInstance` anchors / consensus core are accepted-only (basis predicate kept during P1); the skew guard and ref filtering accept accepted-or-tentative. ## Visible behavior changes - **Policy OFF = nothing auto-confirms anywhere**: strong-band matches (named AND stash) now land as `tentative` instead of `accepted`; the face mirror shows `owner_recognized` (not accepted). This is the headline semantic change. - **Stash strong band can confirm again** (spec 048 supersedes spec 047's whole-band consensus): with the owner policy ON, a strong match auto-accepts into the stash core (`user_confirmed`), no consensus needed; medium stays consensus-gated → tentative. - **Named medium tier is policy-independent**: the owner policy governs confirmation only; consensus-gated tentative assignment happens regardless (per S1 band symmetry). ## Skew matrix | API | Worker | Behavior | |---|---|---| | new | new | Export split by state; anchors accepted-only; tentative faces ride `tentativeAssignments` | | new | old | Re-proposals of a live occurrence (accepted OR tentative) on the target are superseded silently | | old | new | Missing `tentativeAssignments` degrades to empty (unchanged); no crash | | old | old | Unchanged except the new gates | ## Tests - Full API suite: `rtk ./gradlew :apps:api:test --no-daemon` → **1265 tests, 0 failures, 9 skipped**. - New PG: `Spec048TentativeStateMigrationPostgresTest` (V141 re-run: predicate matrix, face mirror, idempotency, constraint swap, flyway history) and `Spec048SymmetricBandsPostgresTest` (strong policy matrix named+stash; medium tentative + face mirror; disband releases tentatives with core-only signature via a release-strategy-wired service; merge/split move tentatives; skew re-proposal of a live tentative superseded). - H2 parity: strong matrix, named strong policy-off, disband releases tentatives (empty-core fingerprint when no confirmed core exists), merge moves tentatives, unassigned-only mixed-refs, carousel/listing state reads. - Existing spec 045/047 PG+H2 fixtures updated to the new semantics; revival-loop and bulk-cap regression suites re-run green. ## Notes - No version bump (pipeline-computed). - CI scoped detection scopes feature branches from `merge-base(main, HEAD)`; this changeset includes a migration + `api/worker/*` path, which classifies it as a **fallback-smoke** changeset (compile + web/CLI/ML smoke) — the API unit steps are skipped by the workflow's own condition. Full API suite verified locally; covered on main by the deploy/daily-full-tests lanes. - For P2 (T003): occurrence readers (person media, counts, representative selection, knn) still filter `accepted`; they need accepted+tentative reads, honest "Confirmed" tab, cards-for-tentatives accept/reject and person-page bulk confirm (which must upgrade an existing tentative occurrence in place). For P3 (T004): drop `assignment_basis` and the remaining basis predicates, plus the regression suite (revival loop, Holger cap, disband releases, merge/split, export shapes, face mirror, automatic-paths-never-touch-assigned).
Spec 048 P0: 'accepted' now always means user-confirmed; system assignments
live in the new occurrence state 'tentative'.
- widen the class_instance_occurrences state CHECK to
  (accepted|tentative|superseded|removed) via an idempotent named-constraint
  swap;
- provenance backfill: accepted + assignment_basis='auto_assigned' ->
  tentative;
- face mirror: those occurrences' discovery_results rows accepted ->
  owner_recognized (joined by occurrence_key = discovery_results.id);
- RAISE NOTICE count report for occurrences backfilled + faces mirrored.
Basis stays written in lockstep (tentative ⇔ auto_assigned); P3 drops the
column. H2 regression schema mirrors the widened CHECK.
Spec 048 P0+P1 write paths:
- Occurrence state threaded through the unified accept unit alongside the
  basis (insertOccurrenceNoSteal H2 MERGE + PG ON CONFLICT, revive, upsert);
  default accepted, system assignments write tentative.
- Stash branch is symmetric with named targets: strong band + policy ON ->
  accepted (user_confirmed core, no consensus — threshold is the guard);
  strong + policy OFF -> tentative; medium band -> consensus -> tentative;
  beyond band/abstain/oversized -> pending card. Cap 25 gates every silent
  path. Insert-only keeps the unassigned-only invariant structural.
- Named strong with policy OFF now assigns tentative (policy is the
  confirmation switch); named medium is consensus-gated and
  policy-independent (policy governs confirmation only).
- Face mirror centralized in afterAcceptance: accepted occurrence -> face
  accepted; tentative occurrence -> face owner_recognized.
- Lifecycle covers tentative: dissolve supersede, merge/split moves, overlap
  removal, candidate-rejection guard; disband signature stays accepted-only.
- Export split is state-derived (tentative -> tentativeAssignments; payload
  shapes unchanged); anchors and consensus core are accepted-only; skew guard
  and ref filtering accept accepted-or-tentative (unassigned-only automation).
- New PostgreSQL Spec048TentativeStateMigrationPostgresTest (V141 re-run:
  predicate matrix, face mirror, idempotency, constraint swap) and
  Spec048SymmetricBandsPostgresTest (strong policy matrix named+stash, medium
  tentative + face mirror, disband releases tentatives with core-only
  signature, merge/split move tentatives, skew re-proposal of a live tentative).
- H2 parity: strong policy matrix, named strong policy-off tentative, disband
  releases tentatives (empty-core fingerprint), merge moves tentatives,
  unassigned-only automation skips/keeps assigned faces, state-based listings
  and export.
- Existing spec 045/047 fixtures and assertions updated to the new semantics
  (live occurrence helpers include tentative; band-config seeding; state
  assertions).
chore(spec): mark spec 048 tasks T001-T002 done
All checks were successful
Build and Deploy / Run scoped PR tests (push) Successful in 2m1s
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
a040598c2c
Merge-gate blockers (PR #893, spec 048 invariant accepted => confirmed):
- upsertGenericPeopleOccurrence UPDATE now sets
  assignment_basis='user_confirmed' — assigning a face that already carries a
  tentative occurrence previously produced accepted+auto_assigned (invariant
  violation). The INSERT arm already defaults to user_confirmed (V139).
- confirmOccurrences UPDATE now sets assignment_basis='user_confirmed'
  (P2-proofing: when the person-page selection is extended to tentatives, the
  basis flip must be in the same statement).
- Content reads treat accepted+tentative as live assignments so tentative-only
  instances do not vanish from the product: people listing visibility +
  media/occurrence counts + representative selection, person enrichment,
  personMedia/facesForMedia/faceAssignment, representativeFaces,
  chooseRepresentativeFace, personSummary, assigned-face guard.
  Anchors/consensus stay accepted-only (P1); the remaining readers
  (knn/CT, assignment provenance lists, archive-emptiness, remove/move
  selection) stay for the P2 sweep.
ownerAssignmentOverTentativeOccurrenceUpgradesToAcceptedUserConfirmed in
ClassInstanceServiceTest (H2) and Spec048SymmetricBandsPostgresTest (PG):
owner assignment over a medium-band tentative occurrence flips state accepted
AND basis user_confirmed, mirrors the face to accepted, shows Confirmed with
autoAssignedCount 0 in person detail, and facesForMedia reports accepted.
Fixture lockstep: ClassInstanceServiceTest insertFaceOccurrenceWithBasis now
derives occurrence state from the basis (tentative <=> auto_assigned) and
gains a basis-by-occurrence-key helper.
docs(spec): confirm named medium band is policy-independent (048 S1 ruling)
All checks were successful
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
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 1m55s
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
d3a9747bb4
chris merged commit 5b3c79fbbd into main 2026-09-26 22:19:22 +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!893
No description provided.