English for Automerge Developers

Automerge treats application data like a JSON document with full CRDT-based merge guarantees and history tracking, so conversations about it mix data-modeling vocabulary with the same conflict-free replication concepts common across the local-first ecosystem.

Key Vocabulary

Document — an Automerge data structure representing the entire state of an application (or part of it) as a JSON-like object, with every change tracked and mergeable, rather than a single mutable blob overwritten on each save. “We’re not just overwriting a JSON blob on save — the document tracks every individual change, which is exactly what lets two offline edits merge automatically later.”

Change / changeset — an individual, atomic modification to a document, recorded with enough metadata (author, timestamp, causal history) to be merged deterministically with changes made concurrently elsewhere. “Each edit is captured as its own change, so when two people were offline and both edited the title, Automerge can merge both changesets instead of one silently overwriting the other.”

History / time travel — the ability to inspect or reconstruct any prior state of a document by replaying its recorded changes, since nothing is destructively overwritten. “We can actually recover this — nothing was destructively overwritten, so we can use the document’s history to time-travel back to the state before the bad edit.”

Merge — the deterministic process of combining two divergent copies of a document (each with changes the other hasn’t seen) into a single consistent result, without manual conflict resolution in most cases. “Both branches diverged while offline, but the merge resolves automatically since Automerge’s CRDT guarantees give us a consistent result without a manual conflict step.”

Actor ID — a unique identifier assigned to each device or session making changes to a document, used internally to establish a deterministic ordering when merging concurrent changes. “Every change is tagged with an actor ID, which is part of how Automerge decides deterministic ordering when two changes touch the same field at the same time.”

Common Phrases

• “Is this document tracking individual changes, or are we still just overwriting the whole blob on save?”
• “Can we recover this using the document’s history, or was that data actually lost?”
• “Does this merge automatically, or does this particular data shape need custom conflict handling?”
• “Are we tagging changes with a consistent actor ID across devices, or could that be causing the ordering issue?”

Example Sentences

Explaining the model to a new engineer: “Every edit becomes its own recorded change here, not just an overwrite — that’s what makes it possible to merge two people’s offline edits without losing either one.”

Discussing a recovery scenario: “We don’t need a separate backup system for this — the document’s history already lets us reconstruct any prior state before the accidental deletion.”

Reviewing a data model: “This nested structure might not merge cleanly under concurrent edits — let’s check whether this needs a more CRDT-friendly shape before we commit to it.”

Professional Tips

• Emphasize that a document in Automerge isn’t just JSON storage — it’s change-tracked JSON, and that distinction is central to explaining why offline merging works at all.
• Use change granularity to debug merge surprises — inspecting the actual recorded changes is far more productive than guessing at what “should” have happened.
• Highlight history as a built-in undo and audit trail, since teams often don’t realize they get this capability for free with a CRDT-based document model.
• Flag data shapes early in design review that might merge poorly under concurrent edits — some structures (like ambiguous array reorderings) need deliberate design to merge cleanly.

Practice Exercise

1. Explain to a teammate why change-tracked documents allow offline edits to merge automatically.
2. Describe how document history could be used to recover from an accidental bad edit without a separate backup.
3. Write a sentence flagging a data structure in a design review that might not merge cleanly under concurrent edits.