feat(people): stash away + disband semantics for cluster suggestions (spec 039) #766
Loading…
Reference in a new issue
No description provided.
Delete branch "feat/stash-disband-api"
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?
Spec 039 T001 (backend). Based on origin/main
105331b5.What / why
Two distinct owner actions replace the single 'reject' semantics for people cluster suggestions and unnamed person instances (user-approved design):
class_instances.stashed_atset, V128).auto_accepted_stashed_target; insert-only/steal-guard semantics unchanged). Named targets stay policy-gated.mergeSuggestion(both sides + embedding/pending-embedding queries) andsuggestSimilarInstances(embedding + both name fallbacks).GET /api/discovery/domains/people/class-instances?stashed=falseis the default;stashed=truereturns ONLY shadows (for the stashed section);ClassInstanceView.stashed/ClassInstanceRecordView.stashedexposed.stashed_at;POST /api/discovery/class-instances/{id}/unstash; stash via decideCandidate with a supplied displayName also names+unstashes.class_instance_disband_decisionsso the IDENTICAL cluster is never re-proposed (anti-spam). Non-identical re-clusters stay allowed.persistWorkerCandidatesbefore inserting people-domainnew_person_clustercandidates; suppressed faces are EXCLUDED from the owner_tentative→owner_recognized transition so they can form different re-clusters.cluster_person_matchis never suppressed.POST /api/discovery/class-instances/{id}/disband= signature + dissolve (dissolve marks recognition dirty); stash does NOT mark dirty (assignments unchanged).CHECK-constraint handling (no constraint change)
V073 domains kept: a stash IS an acceptance into a shadow (candidate.state 'accepted', review decision 'accepted' with action=stashed); a disband IS a rejection with a signature (candidate.state 'rejected', review decision 'rejected' with action=disbanded). The richer outcome surfaces via the decision result ('stashed'/'disbanded') and review-decision details — no DB migration of the CHECK constraints needed.
Migration
V128__people_stash_disband.sql:
ALTER TABLE class_instances ADD COLUMN IF NOT EXISTS stashed_at TIMESTAMPTZ NULL+class_instance_disband_decisions (owner_id, face_signature)with index. No worker changes (suppression is API-side).Test plan
rtk ./gradlew :apps:api:compileJavagreenrtk ./gradlew :apps:api:test --tests 'dev.memories.api.discovery.*' --tests 'dev.memories.api.people.*'greenrtk ./gradlew :apps:api:testgreen (932 tests)Two distinct owner actions replace the single 'reject' semantics for people cluster suggestions and unnamed person instances: 1. Stash away (default): the cluster is a REAL person the owner does not want to curate. The instance stays 'active' as an unnamed shadow (stashed_at set). It keeps absorbing future matches (shadow auto-accept bypasses the auto-accept policy flag for stashed targets, insert-only/steal-guard semantics unchanged), is excluded from merge suggestions + similar-instance suggestions, is hidden from default people views (stashed=false default; stashed=true returns ONLY shadows), and can be re-curated anytime: naming (updateInstance / applyDisplayNameIfUnnamed) clears stashed_at, or POST /unstash. 2. Disband: the cluster is GARBAGE (photos of different persons). Faces are released back to the unassigned pool (owner_tentative) via the existing dissolve path, and the cluster's face signature — sha256 hex over faceAnnotationIds sorted ascending joined by ',' (occurrence-key fallback for non-face refs) — is negative-logged into class_instance_disband_decisions so the IDENTICAL cluster is never re-proposed. Suppression happens in persistWorkerCandidates before insertion of people-domain new_person_cluster candidates; suppressed faces are excluded from the owner_tentative → owner_recognized transition so they can still form DIFFERENT re-clusters. Only new_person_cluster is suppressed (cluster_person_match targets an existing person). Non-identical re-clusters stay allowed. No state CHECK-constraint change (V073 domain kept): a stash IS an acceptance into a shadow (candidate.state 'accepted', review decision 'accepted' with action=stashed), a disband IS a rejection with a signature (candidate.state 'rejected', review decision 'rejected' with action=disbanded). The richer outcome surfaces via the decision result ('stashed'/'disbanded') and review-decision details. New endpoints: POST /api/discovery/class-instances/{id}/stash (unnamed + active only, named → 400, NO recognition dirty mark — assignments unchanged), /unstash, /disband (signature + dissolve; dissolve marks recognition dirty). V128 migration: class_instances.stashed_at + class_instance_disband_decisions (owner_id, face_signature) index. Tests (ClassInstanceDiscoveryServiceTest, 10 new): stash-via-decision creates unnamed shadow w/ accepted occurrences + 'stashed' review action; displayName on stash names and unstashes; disband releases faces and writes the exact signature; identical-cluster suppression with faces kept tentative; superset re-cluster persists; stash/unstash endpoint guards (named → 400); disband endpoint signature + dissolve + re-suppression; listing filters (stashed flag / false hides / true only shadows); shadow auto-accept with policy disabled + named target still policy-gated; mergeSuggestion excludes stashed instances; rename clears stashed_at. H2 test schemas extended (stashed_at + disband table).