## The problem: a blind overwrite
Picture a **shared household app**: two partners keep shopping lists, chore checklists and notes on their own phones, and both phones often work offline. Alex changes the quantity of "oat milk" from 1 to 2 on the train; meanwhile Sam, at home and online, renames it to "oat milk, barista". Alex's phone reconnects an hour later and sends the item.
If the server simply stores whatever arrives, it has no way to know that Alex's edit was made on a copy that is now out of date. Depending on what Alex's phone sends, Sam's rename either disappears or survives by luck. The HTTP specification calls this the **lost update** problem: two clients act on the same resource in parallel and the second write erases the first without anyone being told.
## The revision: what it is and who assigns it
The fix is to make every edit say which version of the record it was made from. That version label is the **base revision**.
- **A revision** is a value the server changes on every accepted write to a record: an integer counter (`41`, `42`, ...) or an opaque **entity tag** (ETag), often derived from the stored content.
- **The server issues it.** Only the server sees every write in one order, so only its label means the same thing to both phones. The phone's clock or a counter kept on the phone cannot play this role.
- **The phone stores it with the row.** When the phone pulls a record, or gets a write accepted, it saves the revision next to its local copy.
- **The edit sends it back** as `baseRevision`. This turns a plain write into a **conditional write**: apply it only if the record is still at that revision.
## The conditional write, step by step
1. The phone loads the item at revision 41 and stores `rev = 41` with it.
2. The user edits offline. The phone records the change and its base, 41.
3. On sync, the phone sends the changed fields plus `baseRevision: 41`.
4. The server compares 41 with the record's current revision.
5. **Match:** it applies the change, sets the revision to 42, and returns 42. The phone stores 42 as the row's new base.
6. **Mismatch** (say the record is at 43): another write landed in between. The server does not blindly apply the edit. It runs the policy chosen for that data type: merge the fields, keep one value, or reject with its current copy so the phone (and maybe the user) can resolve it.
Over plain HTTP the base often travels as a precondition, and a mismatch is typically reported as 412 Precondition Failed; a sync API may instead return a conflict answer with the current state in its body, which is what a 409 Conflict is meant to carry. The header mechanics are not the point here. The point is that the server receives a base and compares it.
## What breaks the scheme in practice
- **Sending the whole record.** If the phone sends every field, the untouched ones carry old values. Sam's rename looks like something Alex changed back, so it is either overwritten or flagged as a conflict that never happened. Send only the fields the user changed.
- **Not chaining revisions.** If two edits to one item are queued offline, the second must use the revision returned for the first. Sending the original base again makes the phone conflict with its own earlier write.
- **Forgetting pulled changes.** When the phone pulls a partner's change to a row, the stored base must move to the new revision, or the next local edit is judged stale.
- **A lost response.** The write succeeded but the reply never arrived, so the replay's base now looks stale. The server must recognise the repeat, through the idempotency key the queue stored with the write, or because HTTP allows a success answer when the requested change has already been applied, rather than reporting a conflict.
- **Treating a mismatch as failure.** A stale base is a signal, not an error. For most fields the server can still merge; only some cases need a person.
## Choosing the label
| Label | How it is made | Good for | Watch out for |
|---|---|---|---|
| Revision counter | Server increments it per record on each write | Easy to log, compare and debug | Must be per record, not one global number |
| Entity tag | Server derives it, often from content | Fits HTTP conditional requests | Opaque: the phone can only compare it for equality |
| Phone timestamp | Phone's clock at edit time | Nothing, as a base | Says when, not which version was seen |
A stale base is detected the same way for every data type in the app. What happens next, whether that is a merge, last-write-wins or the user's choice, is decided per data type, and that is where the real design work starts.