fix(sync): change-feed trigger guard + remaining sync spec amendments (F8, PR-4) #1369
Loading…
Reference in a new issue
No description provided.
Delete branch "fix/sync-trigger-guard-amendments"
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?
PR-4 (last implementation lane) of the oracle sync-hardening plan — F8 + the remaining sync spec amendments. Base: origin/main
a8d132d4. F1–F7 already merged (#1364–#1367). No Android changes, no changes to SyncIntentService/SyncPullApplier/history code.A. F8 — change-feed trigger maintenance point (V180)
Ruling: WIDEN (oracle preference ratified).
V180__sync_trigger_fire_on_every_update.sqlre-createstrg_media_items_change_seqasBEFORE INSERT OR UPDATE(unqualified). V176 is untouched (applied in production). The failure mode: the V176UPDATE OF <15 columns>list was a silent second schema-maintenance point — a future writer or migration updating only unlisted columns would skip allocation AND the feed; the committed change would never be delivered (exactly the ADR 0117 invisible-gap mode, entering through the schema instead of the writer).Investigation that decided it:
apps/api/src/main/java, incl. CTE forms): exactly 5 mutating call sites in 4 classes —UploadCommitService.commit— INSERT (fires regardless);TrashServicetrash/restore/permanentlyDelete/emptyTrash — lifecycle cols +updated_at(all watched);SyncIntentServiceexecuteTrash/executeRestore/executeReinstateFromTrash — lifecycle cols +updated_at(all watched);WorkerResultServicemetadata acceptance — watched cols +metadata_status+updated_atin ONE statement (the only unwatched column any writer sets — and it never fires alone);MediaMaintenanceService.clearOwnerLibrary— hard DELETE + epoch bump (epoch is the signal).No JPA/Hibernate entity exists (spring-data-jdbc, raw JdbcClient everywhere; verified: no
@Entity/@Tablefor media_items, no@Version). The only never-watched columns in the entire schema aremetadata_statusandpreview_status— no writer touches ONLY those, so widening changes zero behavior on every existing path and purely removes the future trap.ChangeBinderrule 1 re-binds bound rows to the fresh seq — a refresh, not a misbind;SyncPullApplier/first-sync pre-binder re-derive the same verdicts). Thesync_seqcounter-row lock is already taken by every watched write (every upload commit, every metadata result, every trash/restore/purge); ADR 0117 explicitly accepts row-lock serialization at household scale. Correctness (never silently skip) outranks minor noise.NEW.change_seq = OLD.change_seq→ NOT DISTINCT FROM OLD → falls through to allocation (fresh seq); an explicitly assigned seq passes through verbatim (the V176 backfill contract). No code path assignschange_seqmanually — re-verified: the only assignment in the tree is the V176 backfill, which ran before any trigger existed.Tests (
SyncChangeFeedIntegrationTest11 → 14, real Flyway chain):updateOfOnlyUnwatchedColumnStillAllocatesAndEmits—metadata_status-only UPDATE allocates + emits after V180 (the V176-shaped column list silently skipped exactly this); payload fields unchanged.changeFeedTriggerFiresForEveryInsertAndUpdateWithoutColumnList— schema-level guard:pg_get_triggerdefmust be column-unrestricted; a future re-narrowing fails loudly instead of silently skipping.carriedOverSeqAllocatesButExplicitAssignmentPassesThrough— pins the guard's two branches under the widened event.B. Spec amendments (spec-query + official exporter; byte-identical check vs clean-main export apart from 065/044 — same pattern as #1367)
permanently_deleted; entry stays listed with explicit re-upload copy, no revert button; ISSUE-190 noted)SyncChangeQueryService) actually 400s only negatives and answers unknown/large cursors with an empty 200 — spec corrected to match code: negative = 400; unknown/large = valid past-the-end, empty 200; epoch is the sole invalidation signalNote: PR #1366's body/comments are empty on Forgejo (report not retrievable), so items 1–3 use the exact drafted texts as carried in the lane briefing (which quotes the PR-4 task).
spec-md/specs/065/spec.md+spec-md/specs/044/spec.mdregenerated with the official exporter and verified byte-identical to a fresh export; the 14 other drifted export files on clean main are pre-existing and left to CI (as in #1365/#1367).Validation
:apps:api:test --rerun-tasks— 198 suites / 2315 tests, 0 failures, 0 errors (9 pre-existing skips). The first run hit the known ISSUE-169 flake (PersonRelationServicePostgresTest.theChosenRepresentativeWinsOverTheLatestOccurrence) — green on isolated rerun (26/26) and on the clean--rerun-taskspass.KNOWN_ISSUES
ISSUE-201 (
high/mitigated/area:api, ref[fix/sync-trigger-guard-amendments]) — trigger column-list maintenance point, fixed (widened + guarded).