Sync & optimistic updates

datadata is online-optimistic: every change applies to the local view immediately, and the server remains the single source of truth.

The life of a change

A client calls updateDocument. The change is applied to the local overlay instantly and sent to the server tagged with a client event id.
The server validates the change (schema, guards, limits), assigns the document’s next sequence number, persists it, and appends it to the document’s event log.
The server broadcasts the change to every subscriber of that document. The originating client recognizes its own event id in the broadcast and retires the optimistic entry — the local view and the confirmed view now agree.

If the server rejects the change — a failed guard, a validation error — the client discards the optimistic entry and the local view falls back to the confirmed server state. The UI sees a clean signal, not corruption.

Reading

getDocument returns the merged view: confirmed server state with any pending optimistic changes overlaid. Subscriptions deliver an initial full snapshot (doc:init) followed by incremental patches (doc:patch) — see the wire protocol.

The initial snapshot doesn’t have to travel over the socket: a server-rendered page can fetch documents over plain HTTP and hand them to the client as preloaded state. The subscription then carries the preloaded sequence, and the server confirms with no data transfer — unless changes arrived between the HTTP fetch and the subscribe, in which case it sends a fresh snapshot.

A system document, sys:client-docs-status, exposes the client’s own bookkeeping — subscription states, pending optimistic counts, errors — as a subscribable document, which is what the devtools panel renders.

What “optimistic” does not mean

Optimistic updates mask network latency; they are not an offline mode. A client that loses its connection can keep reading, but there is no durable queue that replays writes after a long disconnect.