fix(api): stash always creates/extends a shadow; mint-time suppression of confirmed-elsewhere cards #1052

Merged
chris merged 2 commits from fix/stash-occupancy-and-suppression into main 2026-10-06 10:36:23 +02:00
Owner

Problem

Two production symptoms from one acceptance-contract gap (ISSUE-105):

1. Stash no-op loop. occupiedForInsertOnlyStash counted state='removed' clustering-reset orphan rows (3,059 live) as occupied. A stash press on such a card resolved as the zero-write all_faces_already_assigned outcome: no shadow created, no rejectedTargetedPair signature written — so the worker re-emitted the identical card on the next recognition run (~10 min cadence). 47 of 194 real stash presses did nothing.

2. Ghost suggestion cards (TOCTOU). Worker job payloads snapshot face→person assignments at enqueue time while the API applies them against live state minutes later. Cards were minted holding faces the owner had since confirmed elsewhere (2 live cards held 3 faces accepted on person "Holger"), and re-minted every run.

Fix (API-only; workers and web untouched)

Stash press contract, new: always create or extend a shadow, except one case.

Face occupancy on a card ref Stash press behavior
removed row (clustering-reset orphan) revived in place (same row id) onto the shadow, accepted — removed ≠ assigned
no row inserted onto the shadow
live tentative on another instance released (superseded, ADR 0102 owner arm) and re-homed onto the shadow
card pre-linked to a stashed shadow absorbs into that shadow (absorbed_into_existing_stash), never a sibling shadow
live accepted on another instance sole no-steal exception: whole card suppressed — suppressed_confirmed_elsewhere, state rejected, no shadow minted
  • Every stash outcome (success included) stamps the rejectedTargetedPair signature so the worker import never re-emits the same (candidateType, face set, target) pairing.
  • Mint-time guard in persistWorkerCandidates: a people candidate holding a face live-accepted on a non-target instance is skipped whole — never inserted as a partial card. Tentative-elsewhere stays re-proposable (ADR 0102 movability); removed/superseded/missing refs pass. The SQL uses IS DISTINCT FROM so targetless new-person cards are guarded too.
  • AcceptOutcome gained stashResolutionOutcome; zero-write resolutions pick the honest outcome (absorbed_into_existing_stash on the absorb arm, legacy all_faces_already_assigned fallback for non-stash paths).

Web contract (for the paired web PR)

Success = state stashed + classInstanceId. absorbed_into_existing_stash = success-like. suppressed_confirmed_elsewhere = no stash created (card leaves the carousel). all_faces_already_assigned remains for non-stash decision types.

Tests

  • New: mint guard (accepted-elsewhere card skipped whole; tentative-elsewhere card kept), stash occupancy re-home (removed orphan revived in place; live tentative released + re-homed), absorb path (pre-linked stashed target, signature verified), suppression-with-signature (pre-linked card, target recorded in the pair).
  • Updated to new semantics: H2 backing-card pair (own-tentative re-homes; mixed card suppressed whole), generic-evidence conflict, unassigned-alongside-assigned, and the mint-guard predecessor test (ghost card now suppressed at mint, not left pending).
  • PostgreSQL parity (spec 045): no-steal → suppressed_confirmed_elsewhere; own-backing-card → re-homes onto fresh shadow; mixed → suppressed whole; removed → revived in place with signature. Pr718 B2/B4 mint their stale cards directly (pre-confirmation snapshot) since post-confirmation submissions are now suppressed at mint — their owner-move accept paths still verified.
  • rtk ./gradlew :apps:api:test: 1572 tests, 0 failures, 0 errors, 9 skipped (pre-existing skips).

Docs

  • specs/045 S2 + specs/047 S2: 2026-10-06 amendment superseding the 2026-10-03 zero-write clarification for owner stash presses.
  • ADR 0097 notes: boundary clarification (no-steal applies to user-confirmed state only; removed ≠ assigned).
  • KNOWN_ISSUES.md: ISSUE-105 high mitigated (worker/web pairing follow-up noted).
  • Version 1.21.67 → 1.21.68.
## Problem Two production symptoms from one acceptance-contract gap (ISSUE-105): **1. Stash no-op loop.** `occupiedForInsertOnlyStash` counted `state='removed'` clustering-reset orphan rows (3,059 live) as *occupied*. A stash press on such a card resolved as the zero-write `all_faces_already_assigned` outcome: no shadow created, no `rejectedTargetedPair` signature written — so the worker re-emitted the identical card on the next recognition run (~10 min cadence). 47 of 194 real stash presses did nothing. **2. Ghost suggestion cards (TOCTOU).** Worker job payloads snapshot face→person assignments at enqueue time while the API applies them against live state minutes later. Cards were minted holding faces the owner had *since* confirmed elsewhere (2 live cards held 3 faces accepted on person "Holger"), and re-minted every run. ## Fix (API-only; workers and web untouched) Stash press contract, new: **always create or extend a shadow**, except one case. | Face occupancy on a card ref | Stash press behavior | |---|---| | `removed` row (clustering-reset orphan) | revived **in place** (same row id) onto the shadow, `accepted` — *removed ≠ assigned* | | no row | inserted onto the shadow | | live `tentative` on another instance | released (`superseded`, ADR 0102 owner arm) and **re-homed** onto the shadow | | card pre-linked to a stashed shadow | **absorbs** into that shadow (`absorbed_into_existing_stash`), never a sibling shadow | | live `accepted` on another instance | **sole no-steal exception**: whole card suppressed — `suppressed_confirmed_elsewhere`, state `rejected`, no shadow minted | - Every stash outcome (success included) stamps the `rejectedTargetedPair` signature so the worker import never re-emits the same (candidateType, face set, target) pairing. - **Mint-time guard** in `persistWorkerCandidates`: a people candidate holding a face live-`accepted` on a non-target instance is skipped whole — never inserted as a partial card. Tentative-elsewhere stays re-proposable (ADR 0102 movability); `removed`/`superseded`/missing refs pass. The SQL uses `IS DISTINCT FROM` so targetless new-person cards are guarded too. - `AcceptOutcome` gained `stashResolutionOutcome`; zero-write resolutions pick the honest outcome (`absorbed_into_existing_stash` on the absorb arm, legacy `all_faces_already_assigned` fallback for non-stash paths). ## Web contract (for the paired web PR) Success = state `stashed` + `classInstanceId`. `absorbed_into_existing_stash` = success-like. `suppressed_confirmed_elsewhere` = no stash created (card leaves the carousel). `all_faces_already_assigned` remains for non-stash decision types. ## Tests - New: mint guard (accepted-elsewhere card skipped whole; tentative-elsewhere card kept), stash occupancy re-home (removed orphan revived in place; live tentative released + re-homed), absorb path (pre-linked stashed target, signature verified), suppression-with-signature (pre-linked card, target recorded in the pair). - Updated to new semantics: H2 backing-card pair (own-tentative re-homes; mixed card suppressed whole), generic-evidence conflict, unassigned-alongside-assigned, and the mint-guard predecessor test (ghost card now suppressed at mint, not left pending). - PostgreSQL parity (spec 045): no-steal → `suppressed_confirmed_elsewhere`; own-backing-card → re-homes onto fresh shadow; mixed → suppressed whole; removed → revived in place with signature. Pr718 B2/B4 mint their stale cards directly (pre-confirmation snapshot) since post-confirmation submissions are now suppressed at mint — their owner-move accept paths still verified. - `rtk ./gradlew :apps:api:test`: **1572 tests, 0 failures, 0 errors, 9 skipped** (pre-existing skips). ## Docs - specs/045 S2 + specs/047 S2: 2026-10-06 amendment superseding the 2026-10-03 zero-write clarification for owner stash presses. - ADR 0097 `notes`: boundary clarification (no-steal applies to user-confirmed state only; removed ≠ assigned). - KNOWN_ISSUES.md: ISSUE-105 `high` `mitigated` (worker/web pairing follow-up noted). - Version 1.21.67 → 1.21.68.
Root causes (production, Oct 2026):
- occupiedForInsertOnlyStash counted state='removed' clustering-reset
  orphan rows (3059 live) as occupied, so 47 of 194 owner stash presses
  resolved as the zero-write all_faces_already_assigned no-op — no shadow,
  no rejectedTargetedPair signature, identical cards re-emitted every run.
- Worker job payloads snapshot face assignments at enqueue while the API
  applies them minutes later: TOCTOU minted ghost suggestion cards holding
  faces the owner had since confirmed elsewhere (2 live cards held 3 faces
  accepted on person "Holger").

Fix (API-only; workers/web unchanged):
- Stash press ALWAYS creates or extends a shadow. Occupancy is live
  accepted/tentative only:
  - removed row / missing row  -> revived in place / inserted onto the
    shadow (reviveRemovedOccurrence, removed != assigned);
  - live tentative elsewhere   -> released (superseded, ADR 0102 owner
    arm) and re-homed onto the shadow;
  - pre-linked stashed target  -> absorb into THAT shadow (outcome
    absorbed_into_existing_stash), never a sibling shadow.
- Accepted-elsewhere is the sole no-steal exception: the whole card
  resolves suppressed_confirmed_elsewhere (state rejected, no shadow) with
  the rejectedTargetedPair signature so the worker import never re-emits
  the pairing. Every stash outcome stamps the signature (success
  included).
- persistWorkerCandidates mint-time guard: people candidates holding a
  face live-accepted on a non-target instance are skipped whole; stale
  re-proposals of confirmed faces are never inserted again. Uses
  IS DISTINCT FROM so targetless new-person cards are guarded too.
- AcceptOutcome gains stashResolutionOutcome; zero-write resolutions pick
  the honest outcome via CandidateDecisionContext.stashResolutionOverride.

Tests: mint guard (accepted skipped / tentative kept), stash occupancy
(re-homed removed + tentative), absorb path, suppression signature on all
outcomes; updated legacy zero-write expectations (Pr718 B2/B4 mint their
stale cards directly now); specs 045/047 amended, ADR 0097 note added.
Version 1.21.68.
chore: record ISSUE-105 (stash no-op loop + ghost cards) as mitigated
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 2s
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 8m14s
99d0b941f8
chris merged commit 9ebb4c3407 into main 2026-10-06 10:36:23 +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!1052
No description provided.