Local-first treats the device copy as authoritative; the network is optional

What it is

Opening a document, typing a word, ticking a box — the authoritative result of those acts is written in this device’s store. The cloud is another replica to align with later, not “ask it first or it does not count”. That structure is local-first: local storage is the authoritative replica, network sync is a supplement. No net, authority still sits here; net up, authority sends its changes to other authorities.

This is not the same as “queue the request offline, submit to the server as authority once online”. In the queue model the local copy is an outbound buffer and the server is real. In local-first the on-disk copy is real until conflict is resolved; a sync failure cannot void words already written.

Why it happens

When the server is authority, every write’s causal chain is “request → permission → local display”. The network is a required edge; break it and the chain stops. Local-first rewrites the chain as “intent → local commit → (when convenient) exchange with other replicas”. The commit beat does not pass through the radio, so instantaneous causation and cross-session keep are the same storage layer, not two expedients.

Replicas converge by exchange, not by asking. Exchange may be a CRDT, an op log plus merge, or a sync protocol. The algorithm’s name is not the point. The point is who is allowed to say “already written”: the local commit record, or a remote 200. Treat 200 as commit and offline writing does not exist philosophically, only as a costume of pending-send. Treat local commit as commit and a downed cloud is sync delay, not save failure.

Where it stops holding

Money, identity, unique stock — objects that need one global arbiter — cannot treat every phone as authority; local-first stops at “drafts and personal workspace”, payment still walks a central authority. Regulated data may be forbidden to live on-device only. Read-only distribution (a magazine, a course pack) has no local authority to write. Several devices on one account each acting as authority with no exchange split into mutually unrecognising truths — local-first includes the sync supplement; it is not “never network”. Volatile browser storage (a temporary partition the OS may wipe) cannot bear the name authority; authority has to land where the user understands “this is the file”.

Applying it

• Bind “saved” to local commit finishing, not to a sync dot turning green. Sync is another lamp.
• On sync failure the written content remains, still editable. The error is “not yet synced to other devices”, not “save failed”.
• Pick storage that can commit with the radio off (an on-device database, a user-visible file). Do not put authority in a session that must handshake first.
• How to check: write a paragraph offline, kill the app, reopen. The words are there, and there is no “unsaved”. Sync appears only after the network returns. Contrast: if the same product can only enter “pending send” offline and pending evaporates after a kill, that is a queue buffer, not an authoritative replica.

Related

• Same group: I3.10.2 Core actions must still work with the radio off, not just remain readable · I3.10.3 Eventual consistency needs a graspable convergence story · I3.10.4 Long offline stretches explode into mass conflicts on reconnect
• Nearby: I3.03 Offline state · I3.06 State persistence
• Search terms: local-first · authoritative replica · CRDT