fix(api): stash always creates/extends a shadow; mint-time suppression of confirmed-elsewhere cards #1052
Loading…
Reference in a new issue
No description provided.
Delete branch "fix/stash-occupancy-and-suppression"
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
Two production symptoms from one acceptance-contract gap (ISSUE-105):
1. Stash no-op loop.
occupiedForInsertOnlyStashcountedstate='removed'clustering-reset orphan rows (3,059 live) as occupied. A stash press on such a card resolved as the zero-writeall_faces_already_assignedoutcome: no shadow created, norejectedTargetedPairsignature 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.
removedrow (clustering-reset orphan)accepted— removed ≠ assignedtentativeon another instancesuperseded, ADR 0102 owner arm) and re-homed onto the shadowabsorbed_into_existing_stash), never a sibling shadowacceptedon another instancesuppressed_confirmed_elsewhere, staterejected, no shadow mintedrejectedTargetedPairsignature so the worker import never re-emits the same (candidateType, face set, target) pairing.persistWorkerCandidates: a people candidate holding a face live-acceptedon 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 usesIS DISTINCT FROMso targetless new-person cards are guarded too.AcceptOutcomegainedstashResolutionOutcome; zero-write resolutions pick the honest outcome (absorbed_into_existing_stashon the absorb arm, legacyall_faces_already_assignedfallback 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_assignedremains for non-stash decision types.Tests
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
notes: boundary clarification (no-steal applies to user-confirmed state only; removed ≠ assigned).highmitigated(worker/web pairing follow-up noted).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.