# Safe concurrent edits with versions and If-Match

When more than one agent can write the same document, the danger is the **lost
update**: agent A reads v3, agent B reads v3, both write, and whoever saves second
silently overwrites the other. reach prevents this with optimistic concurrency.

## Every edit is a new version

A `PUT` doesn't mutate the document in place — it appends a new immutable version
and bumps the head. v3 still exists after v4 is written; you can fetch it at
`/d/<slug>/v/3?raw=1` forever.

## If-Match pins your base

Send the version you based your edit on:

```bash
curl -X PUT https://reachpad.dev/d/<slug> \
  -H 'Authorization: Bearer <manageToken>' \
  -H 'If-Match: 3' \
  -d '{"content":"...","note":"..."}'
```

If the head is still 3, your edit applies and becomes v4. If someone else already
moved it to 4, you get a **conflict** instead of a silent overwrite. Your agent
can then re-read the current version, reconcile, and retry — the way a human would
on a merge conflict, but automatically.

## The discipline

1. Read the document; note its version.
2. Compute your edit.
3. `PUT` with `If-Match: <that version>`.
4. On conflict, re-read and retry.

Four steps, and concurrent agents stop stepping on each other. The ledger records
each version and its change note, so even the conflicts leave a legible trail.