Conflict resolution

Conflict Resolution

Instructions

Any bidirectional sync has conflicts. The question is not "will we have them" but "how do we resolve them predictably". Pick a policy per entity, make it explicit, and show pending or conflicted states in the UI.

1. Conflict Models

Model	Works by	Good for
Last-write-wins (LWW)	Highest timestamp wins per record	Settings, profile fields, simple data
Field-level LWW	Per-field timestamps merge	User profile with independently edited fields
Three-way merge	Base + ours + theirs -> merged	Documents, code-like content
Vector clocks	Track causality	Systems with unreliable clocks
CRDTs	Conflict-free data types	Collaborative docs, shared sets
Manual	Ask the user	Irreducible conflicts, high-stakes data

2. Last-Write-Wins

The easiest policy. Each update carries a server-authoritative timestamp or revision.

data class Article(val id: String, val title: String, val body: String, val rev: Long, val updatedAt: Instant)

fun resolve(local: Article, remote: Article): Article =
    if (remote.rev >= local.rev) remote else local

Trap: naive wall-clock LWW drops edits when devices have skewed clocks. Use server-assigned revisions or hybrid logical clocks (HLC).

3. Field-Level LWW

Good when different fields are edited on different devices.

record: { title: {v:"A", ts:t1}, body: {v:"B", ts:t2} }

On merge, pick the higher timestamp per field. Keep the change envelope small by sending only changed fields.

4. Three-Way Merge

When you know the base version the client started from, the server can merge:

merge(base, ours, theirs) =
  if ours == base: theirs
  elif theirs == base: ours
  elif ours == theirs: ours
  else: conflict -> policy (prefer ours, prefer theirs, prompt user)

For text, use a diff/patch library. For structured records, do it field-by-field.

5. Vector Clocks

When wall clocks cannot be trusted and causality matters:

• Each replica keeps a vector {replicaId: counter}.
• On update, increment the local replica's counter.
• On merge, compare vectors:
  • If A <= B (every component), B is newer.
  • If neither dominates, concurrent -> conflict.

Vector clocks detect conflicts; they do not resolve them. Pair with a resolution policy.

6. CRDTs (Conflict-Free Replicated Data Types)

CRDTs guarantee automatic merge without conflicts:

• Counters (G-Counter, PN-Counter) -- increments merge by summing per replica.
• Sets (OR-Set, LWW-Set) -- add/remove operations merge deterministically.
• Text (RGA, Yjs, Automerge) -- concurrent edits merge into a consistent sequence.
• Maps -- nested CRDTs.

Use Yjs, Automerge, or a language-native port. Cost: payload growth from metadata, operation history, and garbage collection.

7. Pragmatic Recipe for Most Apps

1. Default to server-assigned revisions + LWW at the record level.
2. Switch to field-level LWW for profile-like entities with independent edits.
3. Switch to three-way merge for documents with structured content.
4. Reserve CRDTs for truly collaborative content (multi-cursor docs, shared boards).
5. Always have a manual fallback for high-stakes data (medical, financial).

8. Client UI for Conflicts

Do not fail silently. Conflicts need affordances:

• Pending state: local change sent, awaiting ack.
• Synced state: server ack received.
• Conflict state: show both versions, let the user pick, or default to policy with undo.
• Keep an in-app history/log of conflict resolutions for 7-30 days.

enum SyncState: Equatable {
    case synced
    case pending
    case conflict(local: Article, remote: Article)
    case failed(reason: String)
}

9. Deterministic Behavior

• Every merge function is pure and testable. Write unit tests that exercise LWW, concurrent edits, and deletions.
• Deletes need special handling: use tombstones so a delete does not get resurrected by a stale offline edit.
• Document idempotency: applying the same resolution twice must yield the same state.

10. Anti-Patterns

• Silent server overwrites. The user loses work without signal.
• Client-side timestamps as the source of truth without clock validation.
• Mixing CRDTs and LWW within one entity.
• Resolving conflicts in UI code. Keep the policy in a domain function; the UI presents outcomes.
• Letting tombstones accumulate forever. Garbage collect.

11. Testing Conflicts

• Simulate two clients editing the same record offline, then reconnecting in either order.
• Property-based tests for merge commutativity (merge(a,b) == merge(b,a)) where applicable.
• Fuzz the resolution function with random histories.
• In CI, run an end-to-end scenario with two emulated devices against a test server.

Checklist

• A conflict policy is chosen and documented per entity.
• Server-assigned revisions or HLCs are used, not wall clocks alone.
• Delete operations use tombstones with a GC policy.
• Merge functions are pure, unit-tested, and idempotent.
• UI surfaces pending, synced, and conflict states.
• CRDTs are used only where justified; not as a default.
• Conflict rate is monitored per entity; spikes trigger review.
• End-to-end scenarios simulate concurrent offline edits.