feat(people): stash away + disband semantics for cluster suggestions (spec 039) #766

Merged
chris merged 1 commit from feat/stash-disband-api into main 2026-09-19 12:24:43 +02:00
Owner

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):

  1. Stash away (default action) — the cluster is a REAL person the owner doesn't want to curate:
    • Instance stays 'active' as an unnamed shadow (class_instances.stashed_at set, V128).
    • Shadow auto-accept: existing-instance candidates targeting a stashed instance auto-accept silently REGARDLESS of the auto-accept policy flag (details marker auto_accepted_stashed_target; insert-only/steal-guard semantics unchanged). Named targets stay policy-gated.
    • Excluded from mergeSuggestion (both sides + embedding/pending-embedding queries) and suggestSimilarInstances (embedding + both name fallbacks).
    • Hidden from default people views: GET /api/discovery/domains/people/class-instances?stashed=false is the default; stashed=true returns ONLY shadows (for the stashed section); ClassInstanceView.stashed / ClassInstanceRecordView.stashed exposed.
    • Re-curating: naming via PATCH (updateInstance) clears stashed_at; POST /api/discovery/class-instances/{id}/unstash; stash via decideCandidate with a supplied displayName also names+unstashes.
  2. Disband — the cluster is GARBAGE (photos of different persons):
    • Faces released back to the unassigned pool (owner_tentative) via the existing dissolve path.
    • The cluster's face signature — sha256 hex over faceAnnotationIds sorted ascending joined by ',' (occurrence-key fallback for non-face refs), same derivation on both the candidate and instance side — is negative-logged into class_instance_disband_decisions so the IDENTICAL cluster is never re-proposed (anti-spam). Non-identical re-clusters stay allowed.
    • Suppression in persistWorkerCandidates before inserting people-domain new_person_cluster candidates; suppressed faces are EXCLUDED from the owner_tentative→owner_recognized transition so they can form different re-clusters. cluster_person_match is 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

  • 10 new tests in ClassInstanceDiscoveryServiceTest: stash-via-decision creates unnamed shadow with accepted occurrences + 'stashed' review action; displayName-on-stash names+unstashes; disband releases faces + writes exact signature; identical-cluster suppression keeps faces tentative; superset re-cluster persists; stash/unstash endpoint guards (named → 400); disband endpoint signature + dissolve + re-suppression; listing filters (flag/false/true); shadow auto-accept with policy disabled + named target still policy-gated; mergeSuggestion excludes stashed; rename clears stashed_at
  • rtk ./gradlew :apps:api:compileJava green
  • rtk ./gradlew :apps:api:test --tests 'dev.memories.api.discovery.*' --tests 'dev.memories.api.people.*' green
  • Full rtk ./gradlew :apps:api:test green (932 tests)
  • H2 test schemas updated (stashed_at on class_instances in 10 schema files + disband table where persistWorkerCandidates runs)
  • Existing spec-038 dirty-mark and policy auto-accept tests untouched and green; workers/people + KNOWN_ISSUES.md + specs/ untouched
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): 1. **Stash away** (default action) — the cluster is a REAL person the owner doesn't want to curate: - Instance stays 'active' as an unnamed shadow (`class_instances.stashed_at` set, V128). - **Shadow auto-accept**: existing-instance candidates targeting a stashed instance auto-accept silently REGARDLESS of the auto-accept policy flag (details marker `auto_accepted_stashed_target`; insert-only/steal-guard semantics unchanged). Named targets stay policy-gated. - Excluded from `mergeSuggestion` (both sides + embedding/pending-embedding queries) and `suggestSimilarInstances` (embedding + both name fallbacks). - Hidden from default people views: `GET /api/discovery/domains/people/class-instances?stashed=false` is the default; `stashed=true` returns ONLY shadows (for the stashed section); `ClassInstanceView.stashed` / `ClassInstanceRecordView.stashed` exposed. - Re-curating: naming via PATCH (updateInstance) clears `stashed_at`; `POST /api/discovery/class-instances/{id}/unstash`; stash via decideCandidate with a supplied displayName also names+unstashes. 2. **Disband** — the cluster is GARBAGE (photos of different persons): - Faces released back to the unassigned pool (owner_tentative) via the existing dissolve path. - The cluster's face signature — sha256 hex over faceAnnotationIds sorted ascending joined by ',' (occurrence-key fallback for non-face refs), same derivation on both the candidate and instance side — is negative-logged into `class_instance_disband_decisions` so the IDENTICAL cluster is never re-proposed (anti-spam). Non-identical re-clusters stay allowed. - Suppression in `persistWorkerCandidates` before inserting people-domain `new_person_cluster` candidates; suppressed faces are EXCLUDED from the owner_tentative→owner_recognized transition so they can form different re-clusters. `cluster_person_match` is 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 - [x] 10 new tests in ClassInstanceDiscoveryServiceTest: stash-via-decision creates unnamed shadow with accepted occurrences + 'stashed' review action; displayName-on-stash names+unstashes; disband releases faces + writes exact signature; identical-cluster suppression keeps faces tentative; superset re-cluster persists; stash/unstash endpoint guards (named → 400); disband endpoint signature + dissolve + re-suppression; listing filters (flag/false/true); shadow auto-accept with policy disabled + named target still policy-gated; mergeSuggestion excludes stashed; rename clears stashed_at - [x] `rtk ./gradlew :apps:api:compileJava` green - [x] `rtk ./gradlew :apps:api:test --tests 'dev.memories.api.discovery.*' --tests 'dev.memories.api.people.*'` green - [x] Full `rtk ./gradlew :apps:api:test` green (932 tests) - [x] H2 test schemas updated (stashed_at on class_instances in 10 schema files + disband table where persistWorkerCandidates runs) - [x] Existing spec-038 dirty-mark and policy auto-accept tests untouched and green; workers/people + KNOWN_ISSUES.md + specs/ untouched
feat(people): stash away + disband semantics for cluster suggestions (spec 039)
All checks were successful
Build and Deploy / Detect changed services and test scopes (push) Successful in 3s
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build converter worker 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 / 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 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 1m54s
8c324330d4
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).
chris merged commit 491db1174e into main 2026-09-19 12:24:43 +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!766
No description provided.