fix(android): record sync intents ONLY on legacy-call failure (record-on-failure, F1) #1365

Merged
chris merged 1 commit from fix/sync-intent-ledger-hygiene into main 2026-10-24 22:37:51 +02:00
Owner

PR-2 of the 4-PR sync hardening plan (oracle finding F1, HIGH). Base: origin/main ca438b67 (0.10.4) per orchestrator.

Problem

The three delete/restore call sites (TimelineViewModel multi-select delete, MediaViewerViewModel delete/restore, TrashViewModel restore) performed the mutation via the LEGACY endpoints and recorded an intent into the Room queue ("record-first", PR-C). The replayed intent's CAS was necessarily stale (expectedLifecycleState=active vs. item already trashed) → every engine drain seeded the ledger with meaningless conflict_state_changed REJECTED rows → reject copy surfaced for actions that had SUCCEEDED.

Design — record-on-failure (oracle option b, ratified)

The queue becomes the durable RETRY channel, not shadow bookkeeping:

  • Legacy call succeeds → no intent row (delta pull mirrors the change).
  • Legacy call fails (network/5xx/401 — landing uncertain) → durable retry queued, surviving process death (existing Room table), drained by the existing engine infrastructure verbatim.
  • Retry carries NO CAS (expectedLifecycleState=null): the landing is unknown, so only the server's idempotent C4 goal table may judge the replay (delete-already-deleted / restore-already-active = idempotent ACCEPT). This eliminates the stale-CAS noise class entirely. Verified against SyncIntentService.reconcileDelete/reconcileRestore decision tables.
  • 403 Forbidden stays unqueued (a replay could only be rejected not_owner — ledger hygiene).
  • Queue-write failures stay swallowed: the visible inline error is the user's retry path; the queued row is the durability backstop.
  • Immediate-delete UX is untouched (legacy calls still fire first).

Rejected alternative (oracle option a, intents-only): dropping the legacy calls would delay deletion until the next engine drain; a pull-before-drain would resurrect the just-deleted item in the timeline — broken UX, not viable. Documented in the spec amendment.

Ledger hygiene for existing noise: existing bogus REJECTED rows are historical — left in place as honest history; the drain/purge housekeeping ages them out. No one-time cleanup (a deletion would falsify history and buys nothing).

Untouched by design: RemovedHistoryViewModel (S11 revert) records unconditionally — its queue write IS the action (intents-only path); also fixed in passing: TrashViewModel.mutate (shared by restore/permanentDelete) now takes an explicit retry type, so a failed permanent delete never queues (it is not an S3 v1 intent type).

Spec amendment (spec 044 only)

  • specs/044-android-backup-app/spec.json S3 "Intent path" bullet rewritten to the ratified transitional reality (legacy = immediate mutation path; intents = record-on-failure durable retry; endpoint exists for sync-visible mutations from other/queued contexts), provenance marked RE-AMENDED 2026-10-24, intent-ledger hygiene; description tail gains a FURTHER AMENDED sentence. Edited and verified through spec-query (sanctioned writer reproduces the file byte-identically).
  • spec-md/specs/044/spec.md regenerated with the official exporter (scripts/spec-query.py export --out spec-md, same as the CI job); verified the regenerated file differs from the pre-edit export only in the amendment itself. Unrelated pre-existing drift in other spec-md files left to CI (exporter script is byte-identical to main's).
  • Spec 065 untouched (collected later, per lane boundaries).

Tests (all green)

:core:test + :app:testDebugUnitTest → 805 tests, 0 failures (664 app + 141 core). New cases:

  • Failure path records intent: timeline multi-select (5xx + 401 variants), viewer trash/restore, trash-screen restore — each asserts the exact row (type, id, expectedLifecycleState=null).
  • Success records NOTHING: all three call sites, plus viewer/trash 403 pins (no doomed intents).
  • Permanent delete never queues, even on failure.
  • Queue-write failure swallowed: trash loop / viewer / trash screen keep their visible failure, never crash, never stick busy.
  • Drain + replay: existing ClientIntentQueueTest idempotency suite untouched and green; new CAS-free-row drain test pins the verbatim null-CAS replay and the idempotent ACCEPT.

Notes for the orchestrator

  • KNOWN_ISSUES.md: the pre-assigned ISSUE-194 was taken by the merged issues-audit (PR #1361; main now has ISSUE-194/195/197) — appended as ISSUE-198 (next free) with a historical note; expect a trivial merge conflict in that file against current main.
  • :app:lintDebug fails with 42 errors identical on clean main (pre-existing, not in this lane's gate).
  • Branch is based on ca438b67 as pinned; no file overlap with main's 7 newer commits except the KNOWN_ISSUES append noted above.
PR-2 of the 4-PR sync hardening plan (oracle finding **F1**, HIGH). Base: origin/main ca438b67 (0.10.4) per orchestrator. ## Problem The three delete/restore call sites (TimelineViewModel multi-select delete, MediaViewerViewModel delete/restore, TrashViewModel restore) performed the mutation via the LEGACY endpoints **and** recorded an intent into the Room queue ("record-first", PR-C). The replayed intent's CAS was necessarily stale (`expectedLifecycleState=active` vs. item already `trashed`) → every engine drain seeded the ledger with meaningless `conflict_state_changed` REJECTED rows → reject copy surfaced for actions that had SUCCEEDED. ## Design — record-on-failure (oracle option b, ratified) The queue becomes the durable **RETRY** channel, not shadow bookkeeping: - Legacy call **succeeds** → **no** intent row (delta pull mirrors the change). - Legacy call **fails** (network/5xx/401 — landing uncertain) → durable retry queued, surviving process death (existing Room table), drained by the existing engine infrastructure verbatim. - Retry carries **NO CAS** (`expectedLifecycleState=null`): the landing is unknown, so only the server's idempotent C4 goal table may judge the replay (delete-already-deleted / restore-already-active = idempotent ACCEPT). This eliminates the stale-CAS noise class entirely. Verified against `SyncIntentService.reconcileDelete/reconcileRestore` decision tables. - **403 Forbidden stays unqueued** (a replay could only be rejected `not_owner` — ledger hygiene). - Queue-write failures stay swallowed: the visible inline error is the user's retry path; the queued row is the durability backstop. - Immediate-delete UX is untouched (legacy calls still fire first). **Rejected alternative (oracle option a, intents-only):** dropping the legacy calls would delay deletion until the next engine drain; a pull-before-drain would resurrect the just-deleted item in the timeline — broken UX, not viable. Documented in the spec amendment. **Ledger hygiene for existing noise:** existing bogus REJECTED rows are historical — **left in place** as honest history; the drain/purge housekeeping ages them out. No one-time cleanup (a deletion would falsify history and buys nothing). **Untouched by design:** `RemovedHistoryViewModel` (S11 revert) records unconditionally — its queue write IS the action (intents-only path); also fixed in passing: `TrashViewModel.mutate` (shared by restore/permanentDelete) now takes an explicit retry type, so a failed permanent delete never queues (it is not an S3 v1 intent type). ## Spec amendment (spec 044 only) - `specs/044-android-backup-app/spec.json` S3 "Intent path" bullet rewritten to the ratified transitional reality (legacy = immediate mutation path; intents = record-on-failure durable retry; endpoint exists for sync-visible mutations from other/queued contexts), provenance marked `RE-AMENDED 2026-10-24, intent-ledger hygiene`; description tail gains a FURTHER AMENDED sentence. Edited and verified through `spec-query` (sanctioned writer reproduces the file byte-identically). - `spec-md/specs/044/spec.md` regenerated with the official exporter (`scripts/spec-query.py export --out spec-md`, same as the CI job); verified the regenerated file differs from the pre-edit export only in the amendment itself. Unrelated pre-existing drift in other spec-md files left to CI (exporter script is byte-identical to main's). - Spec 065 untouched (collected later, per lane boundaries). ## Tests (all green) `:core:test` + `:app:testDebugUnitTest` → **805 tests, 0 failures** (664 app + 141 core). New cases: - **Failure path records intent**: timeline multi-select (5xx + 401 variants), viewer trash/restore, trash-screen restore — each asserts the exact row `(type, id, expectedLifecycleState=null)`. - **Success records NOTHING**: all three call sites, plus viewer/trash 403 pins (no doomed intents). - **Permanent delete never queues**, even on failure. - **Queue-write failure swallowed**: trash loop / viewer / trash screen keep their visible failure, never crash, never stick busy. - **Drain + replay**: existing `ClientIntentQueueTest` idempotency suite untouched and green; new CAS-free-row drain test pins the verbatim null-CAS replay and the idempotent ACCEPT. ## Notes for the orchestrator - `KNOWN_ISSUES.md`: the pre-assigned **ISSUE-194** was taken by the merged issues-audit (PR #1361; main now has ISSUE-194/195/197) — appended as **ISSUE-198** (next free) with a historical note; expect a trivial merge conflict in that file against current main. - `:app:lintDebug` fails with 42 errors **identical on clean main** (pre-existing, not in this lane's gate). - Branch is based on ca438b67 as pinned; no file overlap with main's 7 newer commits except the KNOWN_ISSUES append noted above.
fix(android): record sync intents ONLY on legacy-call failure (record-on-failure, F1)
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 / 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 / Deploy review instance (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 5s
Build and Deploy / Android unit tests and debug APK (push) Successful in 3m31s
66780fb830
The app delete/restore surfaces recorded an intent for EVERY successful
legacy mutation (spec 065 PR-C record-first), so the replayed intent's CAS
was always stale (expectedLifecycleState=active against an already-trashed
item) and every engine drain seeded the ledger with meaningless
conflict_state_changed REJECTED rows — reject copy surfaced for actions
that had succeeded (oracle finding F1, HIGH).

Ratified design (oracle option b): the intent queue becomes the durable
RETRY channel, not shadow bookkeeping:
- Legacy mutation succeeds -> NO intent row (the delta pull mirrors the
  change; the drain never replays a landed mutation).
- Legacy call fails (network/5xx/401 — landing uncertain) -> durable retry
  queued with NO CAS: the server's idempotent C4 goal table must judge the
  replay (delete-already-deleted / restore-already-active = idempotent
  ACCEPT), eliminating the stale-CAS noise class entirely.
- 403 Forbidden stays unqueued: a replay could only be rejected not_owner.
- Queue-write failures stay swallowed: the visible inline error is the
  user's retry path; the queued row is the durability backstop.
- Existing bogus REJECTED rows are left as honest history (drain/purge
  housekeeping ages them out); no one-time cleanup.
- RemovedHistoryViewModel (spec 065 S11) is deliberately untouched: its
  revert's queue write IS the action (intents-only path).

Alternative (oracle option a, intents-only) rejected and documented in
spec 044 S3: dropping the legacy calls would delay deletion until the next
engine drain, so a pull-before-drain would resurrect the just-deleted item
in the timeline — broken UX, not viable.

Call sites: TimelineViewModel.trashSelected (multi-select delete),
MediaViewerViewModel.trash/restore, TrashViewModel.restore (restore only —
permanent delete is not an S3 v1 intent type and is never queued).

Spec: specs/044 S3 Intent-path bullet re-amended via spec-query (sanctioned
writer verified byte-identical); spec-md/specs/044 regenerated with the
official exporter (scripts/spec-query.py export, same as CI). Spec 065
untouched (collected later).

Tests: 12 new (10 app VM failure/success/no-queue/swallowed-write cases
across all three call sites + CAS-free drain replay + a 403 unqueued pin);
:core:test + :app:testDebugUnitTest = 805 tests, 0 failures.

KNOWN_ISSUES: appended (next free number; the pre-assigned ISSUE-194 was
taken by the merged KNOWN_ISSUES audit PR #1361).

Reference: fix/sync-intent-ledger-hygiene (PR-2 of the 4-PR sync
hardening plan, finding F1).
chris force-pushed fix/sync-intent-ledger-hygiene from 66780fb830
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 / 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 / Deploy review instance (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 5s
Build and Deploy / Android unit tests and debug APK (push) Successful in 3m31s
to 35e831b818
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 / 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 / Deploy review instance (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 5s
Build and Deploy / Android unit tests and debug APK (push) Successful in 3m25s
2026-10-24 22:33:24 +02:00
Compare
chris merged commit 05c432db24 into main 2026-10-24 22:37:51 +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!1365
No description provided.