Offline-first sync and replication

Revisions. Every change to a document makes a new revision N-hash: N is one more than the parent’s, the hash is derived from the parent revision, the deleted flag and the body — CouchDB computes an MD5 over these and the attachments; this page uses a 128-bit hash built from four seeded 32-bit hashes, which behaves the same way (deterministic, so the same edit to the same parent always gets the same id). A deletion is a revision with _deleted: true, a tombstone. A PUT must name a leaf as its _rev, or it gets 409 Conflict.

Revision trees and the winner. A document is a tree of revisions; concurrent edits are branches. Every replica chooses the same winning revision from the leaves, without talking to anyone: a leaf that is not deleted beats a deleted one; then the leaf with the longer history (the higher N); then the leaf whose revision hash sorts higher as a string (Replication and conflict model; in CouchDB’s source the leaves are compared by {not Deleted, RevPos, RevId}). The other live leaves are _conflicts, the deleted ones _deleted_conflicts. When every leaf is deleted the document is deleted.

Replication follows the CouchDB replication protocol: read the checkpoint (a _local document named after the replication) from both ends and start from it only if both have one; read the source’s changes feed since then, in batches, with style=all_docs (each changed document once, at its latest sequence, with all its leaves); ask the target _revs_diff which revisions it lacks; fetch those from the source with their _revisions history (open_revs / _bulk_get); write them to the target with _bulk_docs and new_edits: false, which grafts the history onto the target’s tree without making new revisions; save the checkpoint on both ends. Each device runs a push and a pull replication, as PouchDB’s sync does (PouchDB: replication); the pull waits on a longpoll _changes request. A request without an answer fails the session, which restarts from the checkpoint.

Conflict resolution follows the pattern in the CouchDB and PouchDB guides: read the conflicting leaves, compute one body, write it as a new revision on the winning branch and write a deletion on every other live leaf. The strategies: keep the winner; last writer wins by the time each revision was written on its device (an application’s updatedAt field — kept beside the body here); a field-level three-way merge against the lowest common ancestor in the tree (two-way when the ancestor’s body is gone or the leaves share no ancestor); and an application merge that also treats lists as sets.

Compaction and stemming. Compaction removes the bodies of revisions that are not leaves; the ids stay. _revs_limit (default 1000) keeps only that many revision ids along each branch; a replica whose newest revision has been forgotten everywhere else cannot connect its history and gets a second root — a conflict between a revision and its own descendant.

The single-leader cache follows Cloud Firestore’s documented behaviour (offline data): writes apply to the local view at once and listeners see them with hasPendingWrites (listening); offline writes queue and are sent in order; the server applies each write to its current document — update merges fields, so the last arrival wins per field; serverTimestamp() is filled in at commit, and until then a listener sees an estimate from the local clock, the previous value or null (adding data); arrayUnion is applied at the server; a write the rules refuse is removed from the queue and the local view rolls back (Security Rules).

For sync built on CRDTs instead — data types whose replicas merge without conflicts — see Clocks, CRDTs and gossip.

Two documents to start with and three replicas in a star (no device-to-device replication, although CouchDB allows it). Bodies are small flat JSON objects; no attachments, no design documents, no validate_doc_update, no filtered replication, no _purge.

Revision hashes are not CouchDB’s MD5, so the ids differ from a real server’s for the same edits (the rules that use them are the same). The checkpoint comparison is simplified to "both ends have one, take the older"; CouchDB compares session histories. Batches are counted in changes; timeouts and retries are fixed and much shorter than a real replicator’s back-off.

PouchDB’s own revision ids and defaults may differ from CouchDB’s between versions; this page follows CouchDB.

The single-leader model is reduced to what the scenarios need: one document store, two rules standing in for Security Rules, one write in flight per client, no queries, no transactions or batched writes (which need the server), no multi-tab persistence and no cache eviction. Atlas Device Sync (Realm), another single-leader design with its own merge rules, is not modelled.