# Mission: Data Synchronisation

## Why
General competence, not a specific deliverable. Martin expects to build **server-authoritative
command logs** in production — the client keeps a log of commands, applies them optimistically,
and treats the server's reply as the only authoritative state, with the UI a projection of
`authoritative state + not-yet-confirmed commands`. They also want to understand **CRDTs** well
enough to use one for the most frequent conflicts inside such a system, and to reason about
**multiplayer** (many users on the same objects), not only one user on many devices. The canonical
vocabulary is the means: it lets a design be argued from Replicache, Figma, Linear and Kleppmann
rather than invented in-house.

## Success looks like
- Can describe the lifecycle of one command — **pending → in-flight → confirmed / rejected** — and
  say what the UI shows at each stage, and what happens to later pending commands when an earlier
  one is rejected.
- Can explain **rebase** in the sync-engine sense: server state advances, pending commands replay
  on top, and the replayed result may differ from the optimistic one.
- Can choose between **state-based and operation-based** replication for a given feature, and say
  what each requires of the network (idempotency, ordering, causal delivery).
- Can say what a **CRDT** buys and costs relative to a single authoritative server, and when
  "server decides" is the correct answer.
- Can place **local-first** on the map: which of the Ink & Switch ideals it targets, and what it
  gives up.

## Constraints
- Stack is secondary. Examples in **TypeScript** by default because the sync-engine literature
  (Replicache, Zero, TanStack DB, Figma's client) is written in it, but nothing depends on it.
- Glossary-first: introduce the canonical term, then use it. Map Martin's working terms
  (dirty / committing / committed) onto the literature's terms explicitly.
- Prescriptions only where attributable to a source; where practice diverges (Figma vs. CRDTs vs.
  OT), name the camps.

## Out of scope
- **Operational Transformation** beyond an *extremely* brief sketch: what it is, where it came
  from (Ellis & Gibbs 1989), why Figma and the CRDT camp both moved away from it. No transformation
  functions, no TP1/TP2.
- Text-editing CRDTs (RGA, YATA, Peritext) — sequence CRDTs are a specialism; note them, don't
  build them.
- Database-internal replication (WAL shipping, Raft/Paxos) — Kleppmann's notes cover it if needed,
  but the mission is the application layer.
- Byzantine / adversarial peers.

## Revision log
- **2026-09-11, session 1** — drafted from Martin's initial notes. Confirmed same day: general
  competence; directions A (server-authoritative command log) and C (CRDTs + local-first);
  multiplayer in scope; OT limited to a brief sketch; stack unimportant.