feat(api,people-worker): spec 045 P0-P2 — tentative stash auto-assign, no anchor growth #876
Loading…
Reference in a new issue
No description provided.
Delete branch "spec/045-stash-shadow-auto-assign-with-tentative-basis-and-no-anchor-growth"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Problem
"Stash away" on people clusters (spec 039) silently auto-accepts future matched faces as
state=acceptedoccurrences — including weak single-face candidates that bypass the spec 040 suggestion-only guard for stashed targets. Every accepted face is exported to the people worker as a matching anchor, so one wrong absorbed face compounds: centroid drift, distinct persons merging into one stash, and the UI hardcoding every stash face as "Confirmed" even though the owner never confirmed it.Decision (ADR 0097)
Stash auto-assignments become tentative: a new confirmation-axis column
class_instance_occurrences.assignment_basis(user_confirmed|auto_assigned). Auto-assigned faces absorb quietly (spec 039 promise preserved) but are never Confirmed and never worker anchors — the stash anchor set is itsuser_confirmedcore. The axis is a column, not a new state enum value, so all lifecycle paths that supersede overstate='accepted'(disband, dissolve, merge, split) keep covering auto-assigned faces. Stash decisions become insert-only (no face stealing). ADR:docs/adr/0097-stash-auto-assignments-are-tentative-and-never-anchors.json.What P0–P2 do
P0 — migration
V139__occurrence_assignment_basis.sql(additive, zero behavior change on apply):assignment_basis TEXT NOT NULL DEFAULT 'user_confirmed' CHECK (... IN ('user_confirmed','auto_assigned')).idx_class_instance_occurrences_auto_assigned_instanceon(class_instance_id) WHERE assignment_basis='auto_assigned'(serves the P1 split and the P2 guard).details.action='auto_accepted_stashed_target'on a currently stashed instance becomeauto_assigned; original stash-time faces (action='stashed') and all non-stash acceptances stayuser_confirmed.DOblockRAISE NOTICEs backfilled rows + totalauto_assignedpopulation for operator verification.auto_accepted_stashed_targetwas introduced together with stashes (commit8c324330, migration V128 / spec 039). No earlier action ever meant "stash auto-accept", so the backfill is complete and deterministic — anyauto_accepted_existing_instance_candidateon a stashed instance (possible when an instance was stashed later) deliberately staysuser_confirmed.P1 — break the anchor loop
enqueueOwnerFaceRecognitionJobnow splits the export: stashed instances contribute onlyuser_confirmedfaces toassignments(anchors); theirauto_assignedfaces go to a new optional payload fieldtentativeAssignments. Unstashed instances keep the pre-045 shape._handle_owner_face_recognitionreadstentativeAssignments(missing field → empty): those faces join the assigned-faces set (excluded from clustering, weak suggestions and re-proposal — no churn loop) but neverassignments(no centroids, no best-match math).persistWorkerCandidates: an old worker that ignores the new field re-proposes faces already auto-assigned to the same stashed shadow. Those candidates are now superseded silently (no review decision) instead of being rejected asall_faces_already_assigned/ lost-insert-race once per recognition run.P2 — tentative auto-assign + insert-only stash
occurrenceBasisthreaded throughCandidateDecisionContext → acceptPendingCandidatesIntoExistingInstance → acceptCandidateOccurrences → insertOccurrenceNoSteal(H2MERGEand PGON CONFLICTarms) andupsertCandidateOccurrence. Every existing caller defaults touser_confirmed(zero behavior change); the stash shadow auto-accept passesauto_assigned.decideCandidatestash branch:allowMove=false(insert-only). A stash never steals / re-homes a face already accepted on another instance; an all-conflict stale candidate fails loudly as 409 (IllegalStateException→ApiExceptionHandler), leaving the face where it was.accepted, so the reconcile scheduler reaches its steady-state branch and enqueues nothing — pinned by an explicit test (tentativeAutoAssignDoesNotArmRecognitionChurnLoop).Skew matrix
tentativeAssignmentsand re-proposes auto-assigned faces → API supersedes the re-proposal silently (skew guard). No candidate/decision spam; assign remainsauto_assigned.assignments→ new worker treats them as normal anchors (missing field → empty tentative set). No crash; behavior identical to status quo until the API rolls.Test evidence
rtk ./gradlew :apps:api:test --no-daemon→ 1194 tests, 0 failures, 9 skipped (post-rebase onorigin/main@dda31c88).AssignmentBasisMigrationPostgresTest(Testcontainers + real Flyway chain): backfill matches only the shadow action on stashed instances; stash-time/other-action/no-decision rows stayuser_confirmed; re-run idempotent; default + CHECK + partial index +flyway_schema_historyassertions.Spec045StashTentativePostgresTest: insert-only stash does not steal a face from another instance (409 + face stays), stash decision writesuser_confirmed, shadow auto-accept writesauto_assigned, old-worker re-proposal superseded with no decision spam.ClassInstanceDiscoveryServiceTest: shadow/weak auto-accept writeauto_assigned; stash decision writesuser_confirmed; skew re-proposal superseded silently; dissolve supersedesauto_assignedoccurrences and releases faces (lifecycle safety); churn-loop guard.PeopleDiscoveryPostCompletionListenerTest: export split incl. emptytentativeAssignmentsfor unstashed owners.PYTHONPATH=src python3 -m pytest tests -q→ 103 passed (newtests/test_tentative_assignments.py: backward-compat missing field, no re-proposal, no anchor/centroid/weak-consensus contribution, no clustering-pool contribution) +python3 -m compileallclean.Backfill count report
Verified via the migration test (seeded pre-V139 state): exactly the provenance-matched rows flip (
auto_assignedtotal = 1 in the fixture scenario; unrelated actions/instances unchanged). On a live database V139 emitsRAISE NOTICE 'V139 spec 045 assignment_basis backfill: N occurrence(s) backfilled ...; M total auto_assigned occurrence(s) after backfill'— runalembic-style via the normal Flyway deploy and read the migration log for N/M.Follow-ups (explicitly out of scope for this PR)
origin/basis in occurrence views (replace hardcoded "accepted"/Confirmed inClassInstanceService),autoAssignedCount, web labels, filter stash-targeted cards from the carousel.requireUnstashedTargetguard.new_person_clusterre-proposal (noexistingInstanceId) during the old-worker skew window is not covered by the P1 guard — it stays pending. It disappears as soon as the worker is updated (tentative faces leave the unassigned pool); P3's carousel filtering should cover the residual display.Notes
docs/dev/versioning.md) is pipeline-computed versions — "Agents never manually set version".KNOWN_ISSUES.mdentry (this is a tracked fix, spec 045).docs(spec): add spec 045 stash tentative basis + ADR 0097.