refactor(api): drop assignment_basis - state-only semantics (spec 048 P3) #896

Merged
chris merged 5 commits from spec/048-p3-basis-drop into main 2026-09-27 02:03:13 +02:00
Owner

Summary

Spec 048 P3 (final phase): retires the spec 045 assignment_basis column so occurrence state alone carries the semantics (accepted = user-confirmed via explicit owner action or owner-activated strong-band policy; tentative = system-assigned awaiting owner review; superseded = released). Forensics remain in class_instance_review_decisions. Worker untouched.

Checklist items (from the P2 merge review) — all done

  1. Basis predicates → state-only. matchCandidateToExistingInstance anchors and consensusPasses core are now state='accepted' only; every other double-basis read converted or deleted.
  2. acceptedOccurrenceExists verified + documented. Kept accepted-only ("already user-confirmed on this instance?"), with an explicit doc note: tentative rows are upgraded through the guarded owner paths (upsert / guarded ON CONFLICT DO UPDATE) or counted as live assignments by the insert-only no-steal arms — never conflicts.
  3. Write arms cleaned. occurrenceBasis / BASIS_* removed from CandidateDecisionContext, the accept unit, insertOccurrenceNoSteal (H2 MERGE USING + PG ON CONFLICT arms), reviveSupersededOccurrence, upsertCandidateOccurrence, and all call sites; SQL column lists write state only.
  4. tentativeAssignments review endpoint retired. The owner-wide ClassInstanceService.tentativeAssignments(userAccountId) method had no controller mapping, no web caller, and no test caller — deleted (state-based auto-assigned views replaced it in P2).
  5. Reconcile/scan pending-work definition. FaceRecognitionProgressService.tentativeWithEmbedding, FaceRecognitionReconcileScheduler steady-state count and PeopleDiscoveryRecognitionScheduler owner scan now only count faces with NO live occurrence (accepted OR tentative) as pending work — an assigned face cannot re-arm recognition churn. Regression tests added for both schedulers.
  6. Migration V142 (V142__retire_occurrence_assignment_basis.sql): latest on main was V141 (verified; no other lane had taken V142). Drops the basis-partial index idx_class_instance_occurrences_auto_assigned_instance and the column, DROP ... IF EXISTS for idempotency, RAISE NOTICE reports column/index presence before and after. No state-partial replacement index is created: V074's composite idx_class_instance_occurrences_instance_state (class_instance_id, state, accepted_at DESC) already serves every class_instance_id + state='tentative' access (autoAssignedCount subqueries, listing counts, carousel ref checks) — documented in the migration. No backfill (state complete since V141).
  7. KNOWN_ISSUES.md: no new entry (planned work, spec 048).
  8. Regression suite — all green locally (see below).

Grep-proof (zero remaining basis reads)

grep -rn "assignment_basis|assignmentBasis|occurrenceBasis|BASIS_" apps/api apps/web

Remaining hits are only:

  • frozen migration history (V139 created it, V141 wrote it, V142 drops it);
  • the new Spec048BasisRetirementMigrationPostgresTest asserting the column is absent.

Regression coverage (final gate)

  • Revival loop: 1-core stash + in-band candidate → pending, zero writes (spec 047 PG suite, green).
  • Holger bulk cap: 60-face candidate → pending on every silent path (spec 047 cap PG suite, green).
  • Symmetric bands full matrix: strong policy-on/off × named/stash, medium consensus → tentative (spec 048 PG suite, green).
  • Disband releases tentatives + core-only signature (H2 + PG).
  • Merge/split move both states with states intact (H2 + PG).
  • Export split shapes: assignments / tentativeAssignments (listener suite, green).
  • Face mirror transitions: tentative absorb ⇒ owner_recognized; user confirm ⇒ accepted; release ⇒ owner_tentative.
  • Assign-over-tentative upgrade ⇒ accepted (+ user_confirmed semantics), move-of-tentative = confirm, confirm-upgrade supersedes the covered group card.
  • Automatic paths never touch already-assigned faces (unassigned-only mixed-refs test).
  • V142 migration re-run idempotency (new PG test: column + index absent, V074 index present, flyway history, re-execute twice).
  • Retired superseded migration tests: AssignmentBasisMigrationPostgresTest (V139 column no longer exists) and Spec048TentativeStateMigrationPostgresTest (V141 cannot be re-executed after V142 dropped the column; fresh-DB Flyway ordering still applies V141 before V142 in every PG test).
  • New scheduler regressions: a face with a live tentative occurrence is not pending work.

Tests

  • rtk ./gradlew :apps:api:test --no-daemon → 1278 tests, 0 failures, 9 skipped (one known-flaky CandidateDecisionConcurrencyTest repetition can fail on retry; it is green in isolation and BUILD stays successful — same flake observed on the P2 CI run).
  • apps/web: npm run check → 0 errors (comment-only changes); npm run build → success.

Notes

  • No version bump (pipeline-computed).
  • Deploy window: V142 ships with the API image; Flyway runs it at startup before traffic; readers/writers in this branch are state-only, and the previous image never wrote or required basis after the P0-P2 train.
## Summary Spec 048 P3 (final phase): retires the spec 045 `assignment_basis` column so occurrence **state alone carries the semantics** (accepted = user-confirmed via explicit owner action or owner-activated strong-band policy; tentative = system-assigned awaiting owner review; superseded = released). Forensics remain in `class_instance_review_decisions`. Worker untouched. ## Checklist items (from the P2 merge review) — all done 1. **Basis predicates → state-only.** `matchCandidateToExistingInstance` anchors and `consensusPasses` core are now `state='accepted'` only; every other double-basis read converted or deleted. 2. **`acceptedOccurrenceExists` verified + documented.** Kept accepted-only ("already user-confirmed on this instance?"), with an explicit doc note: tentative rows are upgraded through the guarded owner paths (upsert / guarded ON CONFLICT DO UPDATE) or counted as live assignments by the insert-only no-steal arms — never conflicts. 3. **Write arms cleaned.** `occurrenceBasis` / `BASIS_*` removed from `CandidateDecisionContext`, the accept unit, `insertOccurrenceNoSteal` (H2 `MERGE USING` + PG `ON CONFLICT` arms), `reviveSupersededOccurrence`, `upsertCandidateOccurrence`, and all call sites; SQL column lists write `state` only. 4. **`tentativeAssignments` review endpoint retired.** The owner-wide `ClassInstanceService.tentativeAssignments(userAccountId)` method had no controller mapping, no web caller, and no test caller — deleted (state-based auto-assigned views replaced it in P2). 5. **Reconcile/scan pending-work definition.** `FaceRecognitionProgressService.tentativeWithEmbedding`, `FaceRecognitionReconcileScheduler` steady-state count and `PeopleDiscoveryRecognitionScheduler` owner scan now only count faces with **NO live occurrence (accepted OR tentative)** as pending work — an assigned face cannot re-arm recognition churn. Regression tests added for both schedulers. 6. **Migration V142** (`V142__retire_occurrence_assignment_basis.sql`): latest on main was V141 (verified; no other lane had taken V142). Drops the basis-partial index `idx_class_instance_occurrences_auto_assigned_instance` and the column, `DROP ... IF EXISTS` for idempotency, `RAISE NOTICE` reports column/index presence before and after. **No state-partial replacement index** is created: V074's composite `idx_class_instance_occurrences_instance_state (class_instance_id, state, accepted_at DESC)` already serves every `class_instance_id + state='tentative'` access (autoAssignedCount subqueries, listing counts, carousel ref checks) — documented in the migration. No backfill (state complete since V141). 7. **KNOWN_ISSUES.md**: no new entry (planned work, spec 048). 8. **Regression suite** — all green locally (see below). ## Grep-proof (zero remaining basis reads) ``` grep -rn "assignment_basis|assignmentBasis|occurrenceBasis|BASIS_" apps/api apps/web ``` Remaining hits are only: - frozen migration history (`V139` created it, `V141` wrote it, `V142` drops it); - the new `Spec048BasisRetirementMigrationPostgresTest` asserting the column is absent. ## Regression coverage (final gate) - Revival loop: 1-core stash + in-band candidate → pending, zero writes (spec 047 PG suite, green). - Holger bulk cap: 60-face candidate → pending on every silent path (spec 047 cap PG suite, green). - Symmetric bands full matrix: strong policy-on/off × named/stash, medium consensus → tentative (spec 048 PG suite, green). - Disband releases tentatives + core-only signature (H2 + PG). - Merge/split move both states with states intact (H2 + PG). - Export split shapes: `assignments` / `tentativeAssignments` (listener suite, green). - Face mirror transitions: tentative absorb ⇒ owner_recognized; user confirm ⇒ accepted; release ⇒ owner_tentative. - Assign-over-tentative upgrade ⇒ accepted (+ user_confirmed semantics), move-of-tentative = confirm, confirm-upgrade supersedes the covered group card. - Automatic paths never touch already-assigned faces (unassigned-only mixed-refs test). - **V142 migration re-run idempotency** (new PG test: column + index absent, V074 index present, flyway history, re-execute twice). - Retired superseded migration tests: `AssignmentBasisMigrationPostgresTest` (V139 column no longer exists) and `Spec048TentativeStateMigrationPostgresTest` (V141 cannot be re-executed after V142 dropped the column; fresh-DB Flyway ordering still applies V141 before V142 in every PG test). - New scheduler regressions: a face with a live tentative occurrence is not pending work. ## Tests - `rtk ./gradlew :apps:api:test --no-daemon` → **1278 tests, 0 failures, 9 skipped** (one known-flaky `CandidateDecisionConcurrencyTest` repetition can fail on retry; it is green in isolation and BUILD stays successful — same flake observed on the P2 CI run). - `apps/web`: `npm run check` → 0 errors (comment-only changes); `npm run build` → success. ## Notes - No version bump (pipeline-computed). - Deploy window: V142 ships with the API image; Flyway runs it at startup before traffic; readers/writers in this branch are state-only, and the previous image never wrote or required basis after the P0-P2 train.
Spec 048 P3: occurrence state alone carries the confirmation semantics
(accepted=user-confirmed, tentative=system-assigned, superseded=released);
forensics live in class_instance_review_decisions. V142 drops the redundant
spec 045 column and its basis-partial index, and removes the column from all
H2 regression schemas. No state-partial replacement index is created: the
V074 composite index (class_instance_id, state, accepted_at DESC) already
serves every tentative read. Idempotent-safe DROP ... IF EXISTS with
RAISE NOTICE count-report before/after. ClassInstanceView docs now describe
autoAssignedCount as the tentative occurrence count.
Spec 048 P3 (zero remaining basis reads — grep-proof):
- matchCandidateToExistingInstance anchors and consensusPasses core are
  state-only (accepted); basis predicates removed everywhere else.
- occurrenceBasis/BASIS_* removed from CandidateDecisionContext, the accept
  unit, insertOccurrenceNoSteal (H2 MERGE USING + PG ON CONFLICT), revive,
  upsert and all call sites; SQL column lists write state only.
- acceptedOccurrenceExists keeps accepted-only semantics with an explicit
  doc note: tentative rows are upgraded through the guarded owner paths or
  counted as live assignments by the insert-only no-steal arms, never
  conflicts.
- ClassInstanceService confirm/move/assign-over-tentative write state only
  (accepted), CTE selects drop the basis column.
- Retired the unused owner-wide tentativeAssignments service method (no
  controller endpoint, no web caller).
- Reconcile/scan pending-work predicates count only faces with NO live
  occurrence (accepted OR tentative): an assigned face must not re-arm
  recognition churn (FaceRecognitionProgressService, reconcile scheduler,
  people discovery scheduler).
- New Spec048BasisRetirementMigrationPostgresTest: V142 drops the column and
  the basis-partial index idempotently (re-run x2), V074 composite index
  remains, flyway history 142 recorded.
- Retired the two superseded migration tests: AssignmentBasisMigrationPostgres-
  Test (V139 column no longer exists) and Spec048TentativeStateMigration-
  PostgresTest (V141 cannot be re-executed after V142 dropped the column);
  fresh-DB Flyway ordering still applies V141 before V142 in every PG test.
- Scheduler regressions: an owner_tentative face with a live tentative
  occurrence is not pending work (reconcile drops the marker without
  enqueueing; the fallback scan enqueues nothing).
- Fixtures/tests migrated to state-only: tentative occurrence helpers,
  occurrenceState readers, export split fixture, symmetry/cap/045/047 suites.
Spec 048 P3: TS doc comments now describe assignmentState/autoAssignedCount in
occurrence-state terms (tentative), not the retired assignment_basis column.
chore(spec): mark spec 048 task T004 done
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 6s
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) Successful in 3m4s
cc9d970aed
chris merged commit 8fb1618539 into main 2026-09-27 02:03:13 +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!896
No description provided.