QuranDataService syncs through :sync-v2, a generic, git-like engine. This page is a map; the KDoc on each class
is the reference.
- Working: the plain domain tables (
collections.sq,notes.sq,sessions.sq,readingBookmarks.sq). The repositories in:persistencewrite them without any sync columns. - Base:
sync_itemholds, per item, its remote id and the state both sides last agreed on. A row with a base and no domain row is a local delete. - Sync state:
sync_metaholds the token (the GET head), the account, the outbox (the last POST batch, saved before it is sent), the wipe epoch, and the hold bookkeeping.sync_runholds sync-pipelines' run history; the engine only wipes it with the rest.
A run compares three states of each item, all in the same canonical shape (State): working, base, and remote (what
GET /v1/sync returns). Every step is idempotent, so a crash anywhere is repaired by the next run.
SyncEngineV2.sync (one at a time):
- Fetch:
SyncApireads every page ofGET /v1/syncsince the token. A POST whose response was lost is resolved from the outbox (OutboxResolver). - Merge: per type, in dependency order (
syncTypes),Reconcilerruns natural-key revival, the three-way merge (Merger: an edit beats a delete, both ways), the linking of equal new items (SyncType.linkKey; notes bynoteIdentity, as the legacy importer matches), andUniquenessRepair, then writes back in one transaction with the new token. - Push:
PushPlannerdiffs base against working (deletes, then updates, then creates; children wait for their parent's remote id), andPusherposts batches of at most 100. Server errors are handled as the table inSyncErrors.ktsays; an item the server keeps refusing, or one that fails local validation, is held (Holds) with its dependents instead of blocking the rest. A hold ends when the user edits the item (or deletes it, unless the hold is on its delete), the engine's version changes (sync-pipelines passesENGINE_VERSION, changed with a library update), or it expires.SyncEngineV2.held(database, types)lists the held and waiting items as the next push would plan them, so a UI can read them between syncs (sync_itemQueries.holdInputschanges with every table they depend on).SyncEngineV2.unsynced(database, types)reads them and the items the next push sends in one transaction:PushPlanner.previewplans as the push does without writing, so it lists what a push sends, one entry per item, children deferred until their parent's CREATE included.
A run's SyncResult carries what it pushed and pulled (the local rows its merges created, changed or deleted to
take remote changes).
A logout or account switch bumps the wipe epoch (Generation), so a sync in flight can't write back wiped data.
Each synced type is a SyncType (sync-v2/.../types): its table, canonical state, natural key, and mapping to and
from the server's resources. To add one, see AGENTS.md.
SyncClientruns the engine for the signed-in account: it refreshes the token once on a 401, backs pushes off on a 403 that may be the token's scope, and reports each run toQuranDataService.syncStatusandsyncHistory.SyncSchedulerdecides when runs happen (app start, local change, "sync now", periodic) and retries failures with backoff.AGENTS.mdlists the timings.SessionLifecycleCoordinator(SyncLifecycleGate) stops a run's requests once a logout or reset begins.
The integration tests (sync-pipelines/src/jvmTest/.../pipeline/integration) run devices against a fake sync server,
one test per scenario; AGENTS.md says how to write one.