Eventual consistency needs a graspable convergence story

What it is

Local-first admits: the truth on this device right now and the truth on the cloud or another device may differ for a while. They will be eventually consistent. People have to understand how “eventually” arrives: what is not yet sent, what is merging, what is already aligned. If sync is only a spinner and then copy that suddenly swaps, convergence is a black box — the model cannot predict whose words the next glance will see.

Understanding is not being able to recite a CRDT. It is being able to answer three sentences: have my edits left, have others’ edits arrived, is what I see the aligned copy.

Why it happens

Eventual consistency turns “the same copy” from an instantaneous promise into a process in time. The process has a direction: unsent → sending → aligned, or unpulled → merging → aligned. Each step is a named state. A black box crushes those steps into “syncing” and replaces pixels at the end. People cannot tell whether the replacement was “mine stayed, theirs joined” or “mine was covered”. The next offline decision will run on the wrong assumption.

Graspable convergence externalises the process as a few stable signals: count of unsent, time of last alignment, names of objects being merged. Signals must be monotonic: unsent only falls, never jumps back without cause; alignment time only moves forward. Non-monotonic is read as the system lying. If a merge will change a sentence already seen, the process needs a graspable hook at the moment of change (“a version from the computer”), not a silent ask that people diff it themselves afterward.

Where it stops holding

A single-device tool that never syncs to any cloud has no convergence process to tell. A strongly consistent central-authority product should not pretend eventual consistency — its story is “ask, then show”. Convergence may run in the background so long as a query can still get those three sentences; every step need not be an animation. Extremely high-frequency character collaboration (shared cursors) assumes “aligned” by default and opens the process view only on delay or conflict, or the process itself becomes noise. Encrypted sync that cannot show change provenance on the UI should at least show “aligned / not aligned”; encryption is not a reason to hide both states.

Applying it

• Give sync three queryable values: unsent count, objects waiting to pull or merge, time of last alignment.
• “Aligned” lights only when this device and the connected replicas have no unexchanged change. Do not use the completion colour before that.
• When a merge changes visible text, name the direction (“edits from another device were added”). Do not swap the sentence in silence.
• How to check: two devices, each offline, each edit a paragraph. Restore one; watch whether the convergence signal walks from “has unsent” to “aligned”, and whether a person can say where the other paragraph came from when it appears. A spinner-only sync after which sentences have changed with no stage name is a black box. Ask someone who has not seen the implementation “are both sides the same now” — no answer means not graspable.

Related

• Same group: I3.10.1 Local-first treats the device copy as authoritative; the network is optional · I3.10.2 Core actions must still work with the radio off, not just remain readable · I3.10.4 Long offline stretches explode into mass conflicts on reconnect
• Nearby: I3.04 Sync conflicts · I3.11 Sync conflict merge
• Search terms: eventual consistency · sync convergence · local-first