feat(api,web): reader sweep + tentative confirm flows (spec 048 P2) #894

Merged
chris merged 4 commits from spec/048-p2-readers-ui into main 2026-09-27 00:47:47 +02:00
Owner

Summary

Spec 048 P2: the reader sweep to content = accepted+tentative / anchors = accepted-only, tentative-aware confirm/move/remove lifecycle, and the web flows that make "Confirmed" honest and auto-assigned faces curatable. Worker untouched; no migration (V141 already shipped in P1).

CT reader sweep (files/sites)

  • ClassInstanceDiscoveryService: occurrences() listing; similarity/ranking cluster (suggestSimilarInstances, personRanking, mergeSuggestion, mergeTargetRankings + their counts/embedding reads); setRepresentativeMedia. matchCandidateToExistingInstance anchors, consensus core, export split (WorkerJobEnqueueService, already state-derived) and the disband signature stay accepted-only.
  • ClassInstanceService: person listing visibility/counts/representative already CT from the merge-gate fix; P2 adds archive-emptiness (archiveEmptyUnnamedCandidates / archivableGenericUnnamedCandidateIds — a tentative-only unnamed instance is NOT empty), remove/move selections (activeOccurrencesForMedia), currentAssignmentForFace, assignment-provenance lists, markGenericPeopleOccurrenceRemoved, updateGenericPeopleRepresentativeFace.
  • EmbeddingKnnService: native nearestPerInstance now CT (closes the 047 residual).
  • DiscoveryService: instance timeline days + items (person markers) CT.
  • ClassInstanceFaceThumbnailService: CT.
  • CollaborativeClassInstancePeopleBridge: owner/shared person face views CT; per-face assignment_state derives auto_assigned from the tentative state so shared views label them "Auto-assigned" (seeding of contributions stays accepted-only).
  • Per-row assignmentState derivation switched from assignment_basis to the occurrence state (state is the semantics; P3 drops the column); autoAssignedCount and the carousel auto-assigned-ref clause follow.

Lifecycle / confirm semantics

  • Move = confirmation (moveOccurrences): an owner move of a tentative occurrence re-points it and writes state='accepted' + assignment_basis='user_confirmed'.
  • Remove covers tentatives (removeOccurrences, unassignFace, markGenericPeopleOccurrenceRemoved): row goes removed; the face is released to owner_tentative when no live occurrence remains (new releasePeopleFaceIfUnassigned).
  • Card reject releases the tentatives the card created (PeopleDomainCandidateDecisionStrategy.afterRejection supersedes by candidate_id before the face-release check).
  • Bulk confirm (confirmOccurrences): selection includes tentatives, upgrades them in place (accepted + user_confirmed), and supersedes a pending card whose refs are a subset of the confirmed faces (silent supersede — same machinery as the skew guard, no rejection). Cards not fully covered are still accepted onto the instance as before.
  • Ref-scoped confirm (confirmTentativeCandidates via /class-instances/{id}/candidates/confirm): a reported residual — the insert-only path could skip faces that already carry a tentative occurrence on the target — is closed with a guarded in-place upgrade (PG ON CONFLICT ... DO UPDATE ... WHERE state='tentative' AND same instance AND :allowTentativeUpgrade; H2 MERGE ... WHEN MATCHED AND (superseded OR tentative-same-target)). The guard is only enabled for owner-triggered confirms, so every automated path stays strictly insert-only (unassigned-faces-only invariant).

Web

  • Confirmed tab/filter and per-media labels are state-derived end-to-end; TS assignmentState unions extended (auto_assigned, partially_auto_assigned) for person/media/face-assignment/resolved/shared views.
  • Person page bulk Confirm covers auto_assigned items too (button count, selection, confirm call) and hits confirmOccurrences (upgrade + card supersede).
  • Per-face Confirm/Remove for auto-assigned faces on the person page: MediaGrid gains an optional itemActions prop rendered with the existing circular icon-button idiom; actions call the existing per-face endpoints (assignFaceToPerson to this person = confirm, unassignFace = remove) and refresh the person detail. No new design patterns; StashDisbandSplit untouched.
  • Card accept/reject already routes through decideCandidate/candidate endpoints, which now upgrade/release tentatives server-side — no web change needed.

Deploy-window closure

  • Old readers + new writers: tentative rows are invisible to pre-P2 readers only for content lists — acceptable and bounded because P2 ships in the same train; anchors were already accepted-only since P0.
  • Old worker/new API and old API/new worker unchanged from P0-P1 (payload shapes byte-identical).
  • Supersede-on-confirm writes no review decision (consistent with the other supersede paths; the review-decision CHECK does not admit a superseded value and P2 adds no migration).

Tests

  • rtk ./gradlew :apps:api:test --no-daemon → 1279 tests, 0 failures, 9 skipped.
  • New: occurrences listing CT; suggestSimilarInstances CT; face thumbnails CT; PG nativePerInstanceIncludesTentativeOccurrence; PG archive-emptiness keeps a tentative-only unnamed source active; PG move-of-tentative → accepted+user_confirmed and remove → released; H2 confirm-upgrade + covered-card supersede; H2 + PG ref-scoped in-place upgrade (id preserved); H2 move/remove/unassign tentative variants.
  • Web: npm run check → 0 errors (20 pre-existing warnings); npm run build → success.
  • No dedicated new tests for the bridge view SQL and instance-timeline SQL (no unit harness for those query paths); both are join-predicate CT changes covered by compile + existing suites — flagged for the P3 regression sweep.

Notes for P3 (T004)

  • Drop assignment_basis: write sites (accept unit, revive, upsert, ClassInstanceService confirm/move assignments), remaining reads (per-row derivation still selects the column in CTEs, allFaceRefsAlreadyAcceptedOnInstance no longer uses it, anchors/consensus predicates), migration + H2 schema, and the spec-045 tests that seed basis.
  • Regression suite: revival loop, Holger cap, disband releases, merge/split move both, export shapes, face mirror, automatic-paths-never-touch-assigned, plus the new P2 flows (move/remove/confirm upgrades, card supersede, ref-scoped upgrade).
  • Optional: a bridge/timeline-specific test harness (flagged above).
## Summary Spec 048 P2: the reader sweep to **content = accepted+tentative / anchors = accepted-only**, tentative-aware confirm/move/remove lifecycle, and the web flows that make "Confirmed" honest and auto-assigned faces curatable. Worker untouched; no migration (V141 already shipped in P1). ## CT reader sweep (files/sites) - `ClassInstanceDiscoveryService`: `occurrences()` listing; similarity/ranking cluster (`suggestSimilarInstances`, `personRanking`, `mergeSuggestion`, `mergeTargetRankings` + their counts/embedding reads); `setRepresentativeMedia`. `matchCandidateToExistingInstance` anchors, consensus core, export split (WorkerJobEnqueueService, already state-derived) and the disband signature stay accepted-only. - `ClassInstanceService`: person listing visibility/counts/representative already CT from the merge-gate fix; P2 adds archive-emptiness (`archiveEmptyUnnamedCandidates` / `archivableGenericUnnamedCandidateIds` — a tentative-only unnamed instance is NOT empty), remove/move selections (`activeOccurrencesForMedia`), `currentAssignmentForFace`, assignment-provenance lists, `markGenericPeopleOccurrenceRemoved`, `updateGenericPeopleRepresentativeFace`. - `EmbeddingKnnService`: native `nearestPerInstance` now CT (closes the 047 residual). - `DiscoveryService`: instance timeline days + items (person markers) CT. - `ClassInstanceFaceThumbnailService`: CT. - `CollaborativeClassInstancePeopleBridge`: owner/shared person face views CT; per-face `assignment_state` derives `auto_assigned` from the tentative state so shared views label them "Auto-assigned" (seeding of contributions stays accepted-only). - Per-row `assignmentState` derivation switched from `assignment_basis` to the occurrence **state** (state is the semantics; P3 drops the column); `autoAssignedCount` and the carousel auto-assigned-ref clause follow. ## Lifecycle / confirm semantics - **Move = confirmation** (`moveOccurrences`): an owner move of a tentative occurrence re-points it and writes `state='accepted'` + `assignment_basis='user_confirmed'`. - **Remove covers tentatives** (`removeOccurrences`, `unassignFace`, `markGenericPeopleOccurrenceRemoved`): row goes `removed`; the face is released to `owner_tentative` when no live occurrence remains (new `releasePeopleFaceIfUnassigned`). - **Card reject releases** the tentatives the card created (`PeopleDomainCandidateDecisionStrategy.afterRejection` supersedes by `candidate_id` before the face-release check). - **Bulk confirm** (`confirmOccurrences`): selection includes tentatives, upgrades them in place (`accepted` + `user_confirmed`), and **supersedes a pending card whose refs are a subset of the confirmed faces** (silent supersede — same machinery as the skew guard, no rejection). Cards not fully covered are still accepted onto the instance as before. - **Ref-scoped confirm** (`confirmTentativeCandidates` via `/class-instances/{id}/candidates/confirm`): a reported residual — the insert-only path could skip faces that already carry a tentative occurrence on the target — is closed with a **guarded in-place upgrade** (PG `ON CONFLICT ... DO UPDATE ... WHERE state='tentative' AND same instance AND :allowTentativeUpgrade`; H2 `MERGE ... WHEN MATCHED AND (superseded OR tentative-same-target)`). The guard is only enabled for owner-triggered confirms, so every automated path stays strictly insert-only (unassigned-faces-only invariant). ## Web - Confirmed tab/filter and per-media labels are state-derived end-to-end; TS `assignmentState` unions extended (`auto_assigned`, `partially_auto_assigned`) for person/media/face-assignment/resolved/shared views. - Person page bulk Confirm covers `auto_assigned` items too (button count, selection, confirm call) and hits `confirmOccurrences` (upgrade + card supersede). - **Per-face Confirm/Remove for auto-assigned faces** on the person page: `MediaGrid` gains an optional `itemActions` prop rendered with the existing circular icon-button idiom; actions call the existing per-face endpoints (`assignFaceToPerson` to this person = confirm, `unassignFace` = remove) and refresh the person detail. No new design patterns; StashDisbandSplit untouched. - Card accept/reject already routes through `decideCandidate`/candidate endpoints, which now upgrade/release tentatives server-side — no web change needed. ## Deploy-window closure - Old readers + new writers: tentative rows are invisible to pre-P2 readers only for content lists — acceptable and bounded because P2 ships in the same train; anchors were already accepted-only since P0. - Old worker/new API and old API/new worker unchanged from P0-P1 (payload shapes byte-identical). - Supersede-on-confirm writes no review decision (consistent with the other supersede paths; the review-decision CHECK does not admit a `superseded` value and P2 adds no migration). ## Tests - `rtk ./gradlew :apps:api:test --no-daemon` → **1279 tests, 0 failures, 9 skipped**. - New: occurrences listing CT; suggestSimilarInstances CT; face thumbnails CT; PG `nativePerInstanceIncludesTentativeOccurrence`; PG archive-emptiness keeps a tentative-only unnamed source active; PG move-of-tentative → accepted+user_confirmed and remove → released; H2 confirm-upgrade + covered-card supersede; H2 + PG ref-scoped in-place upgrade (id preserved); H2 move/remove/unassign tentative variants. - Web: `npm run check` → 0 errors (20 pre-existing warnings); `npm run build` → success. - No dedicated new tests for the bridge view SQL and instance-timeline SQL (no unit harness for those query paths); both are join-predicate CT changes covered by compile + existing suites — flagged for the P3 regression sweep. ## Notes for P3 (T004) - Drop `assignment_basis`: write sites (accept unit, revive, upsert, ClassInstanceService confirm/move assignments), remaining reads (per-row derivation still selects the column in CTEs, `allFaceRefsAlreadyAcceptedOnInstance` no longer uses it, anchors/consensus predicates), migration + H2 schema, and the spec-045 tests that seed basis. - Regression suite: revival loop, Holger cap, disband releases, merge/split move both, export shapes, face mirror, automatic-paths-never-touch-assigned, plus the new P2 flows (move/remove/confirm upgrades, card supersede, ref-scoped upgrade). - Optional: a bridge/timeline-specific test harness (flagged above).
Spec 048 P2 (reader sweep to accepted+tentative, content vs anchor split):
- occurrences() listing, person/instance timeline days, face thumbnails,
  similarity/ranking cluster (suggestSimilarInstances, personRanking,
  mergeSuggestion, mergeTargetRankings and their counts), archive-emptiness
  (a tentative-only unnamed instance is NOT empty), assignment-provenance
  lists, currentAssignmentForFace, setRepresentativeMedia, collaborative
  bridge owner/shared person views (tentatives surface labeled
  'auto_assigned'), and EmbeddingKnnService native per-instance reads now
  include tentative occurrences.
- Anchors/consensus/export-split/disband signature stay accepted-only.
- Per-row assignmentState derivation switches from assignment_basis to
  occurrence state (state is the semantics; P3 drops the column), as do
  autoAssignedCount and the carousel auto-assigned-ref clause.
- Owner move = confirmation: moveOccurrences upgrades a tentative row to
  accepted + user_confirmed on the target.
- Owner remove (removeOccurrences/unassignFace/markGenericPeopleOccurrenceRemoved)
  covers tentative rows and releases the face to owner_tentative when no live
  occurrence remains; candidate rejection supersedes the tentatives its card
  created.
- confirmOccurrences upgrades tentatives in place and supersedes a pending
  card whose refs are a subset of the confirmed faces (silent supersede, not
  rejection); the ref-scoped confirmTentativeCandidates path upgrades an
  existing same-target tentative in place via a guarded ON CONFLICT DO UPDATE
  (PG) / MERGE WHEN MATCHED clause (H2), gated to owner-triggered confirms so
  automation stays insert-only.
Spec 048 P2 web:
- 'Confirmed' tab/filter and person media are state-derived on the API, so a
  tentative (auto-assigned) face never shows as Confirmed; TS assignmentState
  unions extended with auto_assigned/partially_auto_assigned (person, media,
  face-assignment and resolved/shared person views).
- Person page bulk Confirm now covers auto-assigned items (owner_tentative OR
  auto_assigned) and hits confirmOccurrences, which upgrades tentatives in
  place and supersedes covered cards.
- Per-face Confirm/Remove for auto-assigned faces on the person page: MediaGrid
  gains an optional itemActions prop rendered with the existing icon-button
  idiom; actions call the existing per-face endpoints (assignFaceToPerson to
  this person = confirm, unassignFace = remove) and refresh the person detail.
chore(spec): mark spec 048 task T003 done
Some checks failed
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 8s
Build and Deploy / Android unit tests and debug APK (push) Has been skipped
Build and Deploy / Build postgres image (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 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) Failing after 43m13s
2df0443888
fix(web): hide per-face actions during bulk curation
Some checks failed
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 5s
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) Failing after 31m17s
9fbcc041fa
Per-face Confirm/Remove buttons on the person page now also disappear while
a bulk curation action is in flight (curationBusy / confirmingSelected), so a
concurrent mutation cannot race the bulk confirm/remove.
chris merged commit 285c3f5e93 into main 2026-09-27 00:47:47 +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!894
No description provided.