feat(sync)!: run sync on the sync-v2 engine and plain tables

[mohamede1945]

Stacked on #322 (the sync-v2 engine). This is port step 2 of 5. The review's findings have landed as new commits (see "Review fixes").

Summary

Moves persistence onto sync-v2's plain tables and wires the new engine in behind QuranDataService. The public API is unchanged apart from the deliberate changes listed below. The old syncengine stays compiled for its shared types, but it never runs; it gets deleted in step 4.

• Persistence:
  • Domain tables are plain data (notes plus note_range, collections, verse-in-collection, reading bookmarks, reading sessions), plus sync_item/sync_meta.
  • Every local write goes through the repository rules (trim, note creation-time nudge, one highlight color per verse, newest-20 sessions). The importer goes through them too.
  • App-facing queries hide archived notes and system collections.
  • Schema version 2: a version-1 database is dropped and recreated. This is pre-release, with no backward compatibility.
• Wiring: SyncClient runs SyncEngineV2 through a new SyncScheduler.
  • Same triggers as before: 5 s after a local change, 30 s after app start, immediately, and every 30 min.
  • Backoff that honours the engine's retryable and retryAfterMillis.
  • The scheduler never stops syncing after retries (S21).
  • Pulls continue during a push backoff.
  • syncStatus semantics are the same as feat(sync): add immediate sync trigger and sync status #317.
• Auth:
  • The account id comes from the token's sub, and switching accounts wipes local sync data (S3).
  • A 401 forces one token refresh; if the refresh fails, the session ends (S25).
  • A transient refresh error keeps the session.
• Engine rule fixes found while wiring:
  • a collection renamed here and deleted remotely comes back with its verses;
  • identical new notes created on two devices are linked, not duplicated.
• Bugs the ported tests caught:
  • replacing a bookmark's only collection moved its lastUpdated;
  • addReadingSession threw for a visit older than the newest 20.

Review fixes

Each fix is its own commit, with a regression test:

• 401 refresh storm: after a forced refresh, a 401 again fails the run without retries. There is at most one refresh per run.
• Transient refresh errors: only a TechnicalFailure caused by a network error or a timeout keeps the session. Anything else ends it, as before.
• Collection order: newest first by creation time again. Synced collections keep their own clientCreatedAt.
• syncStatus during a push backoff: a pull-only run keeps the 403 Failed until a run that pushes succeeds.
• "Sync now": a request during a run now runs right after it, and a request while a retry is pending runs at once.
• Leaks: QuranDataService.clear() closes the sync client, which stops the scheduler's command loop and closes the HTTP client.
• Tests:
  • the lifecycle tests' sync-token and account checks are restored;
  • a refused refresh after a 401 ends the session;
  • ERR-06 now covers the catalog's race, an edit made while the GET is held;
  • ERR-03 expects exactly one 504;
  • a TXT-09 variant where the phone's spelling is newer;
  • bookmark dates for memberships that come from the server;
  • the order of reading sessions visited at the same time.
• Docs: sync-v2's ensureFavorites and prune are documented as production API.

Integration suite

The integration suite goes from 57 knownIssues to 2, with no scenario going from pass to fail. The flip commits remove the pins area by area. The two that remain:

• S4 (NOTE-12): the public Note model exposes only the first range. The iOS model change is step 5.
• S14 (IMP-10): logout clears the import history. Step 3.

About 15 scenarios had their premise adapted to the new engine; each change is explained in its commit message. For example, ERR-06's race can no longer happen, because the remote delete is merged before the push.

Public API changes (iOS/Android follow-ups)

• updateNote(id, body[, timestamp]): the range parameters are removed, because ranges are immutable.
• updateCollection/deleteCollection throw ReadOnlyCollectionException. updateCollection throws DuplicateCollectionNameException.
• Collection.isReadOnly is added.
• PageReadingBookmark.mushafId is added: 5, 6 or 7, the representative mushaf of the server's group.
• Shared.h:
  • SharedNote_ is renamed to SharedNote and SharedCollection_ to SharedCollection, so iOS renames Note_ to Note;
  • 56 plumbing classes are removed;
  • no sync-v2 types are exposed.
• Behaviour changes:
  • notes hides archived notes;
  • bookmark ids are "sura:ayah";
  • names starting with system: are rejected;
  • surah and juz reading bookmarks set on the web show as empty.

Tests

• ./gradlew allTests --continue passes on every module and target:

  • sync-v2: 177 JVM;
  • auth: 139 per target;
  • persistence: 171 JVM, 180 on iOS;
  • sync-pipelines: 296 JVM, 73 on Android host and iOS.

• :umbrella:linkDebugFrameworkIosSimulatorArm64 and :demo:android:assembleDebug succeed.

• The integration suite passed 3 runs in a row with --rerun.

• Persistence tests went from 247 to 171. 155 were dropped:

  • 152 tested removed sync plumbing (pending ops, ACKs, tombstones, replay, write guards);
  • 3 covered seeded highlight collections, which no longer exist.

  The rest were rewritten for the new tables, and new tests cover the new write rules.

Open

• Held items are silent. An item the server refuses is held, and syncStatus still reports Succeeded. No public API lists held items yet; that is planned together with sync history.

🤖 Generated with Claude Code

Cleanup (rebased 2026-10-14)

• Removed 34 sync-v2 tests that replay integration scenarios exactly, now that the scenarios run on sync-v2.
• Merged LIFE-14 with its server-rejection variant.
• 2 persistence test deletes and 5 merges.
• Fixed comments that later changes made stale.
• Fixed the Apple demo (Note_ → Note), which this PR had broken.
• Added a README Sync section on the architecture: the sync-v2 engine, persistence on plain tables, the wiring, scheduler triggers and backoff, auth, and syncStatus.