This note exists because videos/lamis-mukta-dreaming-memory/application originally described if_rev as validated by matching the pattern in Lamis Mukta's talk, without ever comparing it to the alternative (locking). Matching a talk's description isn't evidence of correctness. Flagged 2026-07-18 and corrected there; this note is the actual open comparison, unresolved.
Optimistic concurrency control (OCC) via compare-and-swap on a revision token: read the current rev, write only if it still matches, get a 409 on mismatch, re-read and retry. "Hash-before-write" (as it got called in conversation) is a loose description of this — the token doesn't have to be a content hash, and isn't necessarily one in the current implementation. The precise term is optimistic concurrency / compare-and-swap, not hashing specifically.
A traditional database-style approach: acquire an exclusive lock on the key before editing, hold it until the write completes, release it. No other writer can touch the key in the meantime, so there's no conflict to detect or retry — the guarantee is upfront rather than checked after the fact.
This doesn't exist in gdata-server today. Adding it would mean a lock-acquire/release protocol, plus — critically — a lease/timeout mechanism, because something has to reclaim the lock if the holder crashes, stalls, or is simply an LLM agent turn that takes far longer than expected. Without a lease, a stalled holder blocks the key indefinitely, which is worse than OCC's worst case (a failed write that must be retried).
Optimistic (current) — no lock state to manage, no stale-lock cleanup, works statelessly over HTTP/MCP, never blocks an unrelated reader or writer. Cost is paid only when a real collision happens (a retry). Downside: under genuine repeated contention this wastes work and can in principle starve a writer; correctness depends on every client actually doing the read-modify-write-with-if_rev dance rather than skipping it.
Pessimistic locking — a writer that acquires the lock is guaranteed to finish without conflict; no wasted retries. Downside: needs a lease/timeout protocol that doesn't exist today, and that protocol interacts badly with LLM agents specifically — turn duration is unpredictable, sessions can be killed mid-task by the user, and a lock held by a session that never cleanly finishes needs the same kind of recovery logic optimistic concurrency avoids needing at all. Also blocks other access to the key for the duration, which matters more as more things (interactive sessions, a future scheduled maintenance pass) touch the same store.
Per John, 2026-07-18: almost all writes originate from a single actor at a time — John, acting through whichever agent (Claude, Codex, Envoy) he's using at that moment. The one plausible source of genuine concurrent access is a scheduled process running unattended — the not-yet-built Envoy maintenance/dreaming pass (envoy/todo, action item B) — which would run overnight, while John is asleep and not editing anything himself.
That matters to the comparison: true write-write contention on the same key is rare in this system, not routine. Optimistic concurrency's downside (wasted retry work) is cheap precisely because collisions are rare. Locking's downside (a lease/timeout protocol, and its specifically bad fit with unpredictable agent-turn duration) would be paid on every write regardless of whether contention exists that time or not.
Rather than choosing one model for every write, scope any locking to the one scenario where it would actually matter: an advisory lock or "maintenance window" flag held only by the scheduled overnight pass while it runs, checked (or enforced) against interactive writes during that window. That would give a hard guarantee exactly where the rare real contention case lives, without adding lease-management overhead to the common single-writer case. Not evaluated in any depth — named here so it isn't lost.
Unresolved. No recommendation is being made beyond laying out the factors above. Revisit before committing engineering effort either direction, and specifically before scheduling the maintenance pass (action item B in the application note above), since that's the one scenario where the choice might actually matter in practice. Neither action item B or C depends on this being resolved first.
• gdata-server — where if_rev is implemented.
• README/mcp-note-editing — documents if_rev usage as a mechanic, not as a justified design choice.
• envoy/todo — "Regular maintenance emails", the scheduled process that is the actual source of potential concurrent access.