feat(api): allow stashing named people instances (name is discarded) #1225

Merged
chris merged 2 commits from feat/stash-named-person-api into main 2026-10-14 22:13:59 +02:00
Owner

Spec 039 stash-away for NAMED people instances (owner decision: the name is discarded).

What changed

  • Public stashInstance(UUID, UUID) (endpoint path) no longer throws IllegalArgumentException("Only unnamed..."). It sets stashed_at = now AND clears display_name in the same UPDATE: no backup column, no flag, no migration. A stashed named person becomes a 1:1 ordinary unnamed shadow, so every stash invariant (incl. ADR 0107 candidate-card hiding against unnamed targets) holds unchanged.
  • Aliases untouched: neither stash nor unstash touches the aliases column — alias entries survive the stash and the discarded name (documented, deliberately unchanged).
  • Recognition NOT marked dirty on stash (assignments unchanged) — unchanged.
  • decideCandidate-onlyUnnamed guard unchanged: private stashInstance(UUID, UUID, boolean onlyUnnamed, boolean discardDisplayName) keeps its display_name IS NULL/blank predicate for the fresh/pre-linked shadow arm (a named instance matches 0 rows there and is silently left unstashed, e.g. a stash decision that supplied a displayName). That arm never discards a name; only the endpoint path does.
  • unstashInstance clears stashed_at only — the discarded name is NOT restored; the person re-enters default views unnamed (Javadoc updated).
  • DiscoveryController stash/unstash endpoint Javadocs updated.
  • ClassInstanceView / OpenAPI schema unchanged — displayName is simply null after a stash.

Tests (apps/api)

  • stashEndpointStashesNamedActivePeopleInstanceAndDiscardsTheName: named stash succeeds, stashed_at set, display_name NULL, aliases preserved, stashed listing only.
  • unstashReturnsFormerlyNamedPersonToDefaultListAsUnnamed: unstash returns it to the default listing, still unnamed.
  • decideCandidateStashGuardStillKeepsNamedInstancesUnstashed: guard still leaves named instances unstashed; same instance stashable via endpoint.
  • stashEndpointStashesUnnamedActivePeopleInstanceAndUnstashClearsMarker: unnamed baseline unchanged.
  • rtk ./gradlew :apps:api:test (full api suite) green; --tests ClassInstanceDiscovery: 329 tests, 0 failures.

No merge — orchestrator reviews and adds ADR/spec notes on this branch.

Spec 039 stash-away for NAMED people instances (owner decision: the name is discarded). ## What changed - Public stashInstance(UUID, UUID) (endpoint path) no longer throws IllegalArgumentException("Only unnamed..."). It sets stashed_at = now AND clears display_name in the same UPDATE: no backup column, no flag, no migration. A stashed named person becomes a 1:1 ordinary unnamed shadow, so every stash invariant (incl. ADR 0107 candidate-card hiding against unnamed targets) holds unchanged. - Aliases untouched: neither stash nor unstash touches the aliases column — alias entries survive the stash and the discarded name (documented, deliberately unchanged). - Recognition NOT marked dirty on stash (assignments unchanged) — unchanged. - decideCandidate-onlyUnnamed guard unchanged: private stashInstance(UUID, UUID, boolean onlyUnnamed, boolean discardDisplayName) keeps its display_name IS NULL/blank predicate for the fresh/pre-linked shadow arm (a named instance matches 0 rows there and is silently left unstashed, e.g. a stash decision that supplied a displayName). That arm never discards a name; only the endpoint path does. - unstashInstance clears stashed_at only — the discarded name is NOT restored; the person re-enters default views unnamed (Javadoc updated). - DiscoveryController stash/unstash endpoint Javadocs updated. - ClassInstanceView / OpenAPI schema unchanged — displayName is simply null after a stash. ## Tests (apps/api) - stashEndpointStashesNamedActivePeopleInstanceAndDiscardsTheName: named stash succeeds, stashed_at set, display_name NULL, aliases preserved, stashed listing only. - unstashReturnsFormerlyNamedPersonToDefaultListAsUnnamed: unstash returns it to the default listing, still unnamed. - decideCandidateStashGuardStillKeepsNamedInstancesUnstashed: guard still leaves named instances unstashed; same instance stashable via endpoint. - stashEndpointStashesUnnamedActivePeopleInstanceAndUnstashClearsMarker: unnamed baseline unchanged. - rtk ./gradlew :apps:api:test (full api suite) green; --tests *ClassInstanceDiscovery*: 329 tests, 0 failures. No merge — orchestrator reviews and adds ADR/spec notes on this branch.
feat(api): allow stashing named people instances (name is discarded)
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 4s
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 Android CI 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 / Android unit tests and debug APK (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 12m44s
637010a119
Remove the endpoint-layer 400 that rejected stashing named people
instances (spec 039 "stash away"). The owner decision discards the
name: the public stashInstance path now clears display_name in the same
UPDATE (stashed_at set, display_name NULL, no backup column / no
migration) so a stashed named person becomes a 1:1 ordinary unnamed
shadow. Aliases are untouched (they survive the stash and the discarded
name); recognition stays untouched (assignments unchanged).

The decideCandidate-onlyUnnamed guard is unchanged: it only applies its
display_name IS NULL/blank predicate for the fresh/pre-linked shadow arm
(a named instance still matches 0 rows there and is silently left
unstashed); that arm never discards a name.

Javadocs updated at both stash sites, unstashInstance and the
DiscoveryController stash/unstash endpoints (the discarded name is not
restored by unstash). ClassInstanceView/OpenAPI schema unchanged —
displayName is simply null after a stash.

Tests: named stash succeeds and lands in the stashed listing, unstash
returns it to the default list unnamed, decideCandidate guard still
keeps named instances unstashed, unnamed stash path unchanged.
docs: ADR 0112 (stashing a named person discards the name) + KNOWN_ISSUES entry for legacy decideCandidate quirk
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 3s
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 Android CI 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 / Android unit tests and debug APK (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 16m44s
d3c5fd139a
chris merged commit f0fd524626 into main 2026-10-14 22:13:59 +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!1225
No description provided.