Skip to content

Data Diff and Merge Tool

Tool — instantiates Asynchronous Replica Convergence

Compares two divergent copies against their common ancestor, auto-merges the changes that don't overlap, and surfaces the ones that do as explicit, reviewable conflicts.

Data Diff and Merge Tool takes two copies of the same object that have drifted apart and produces one reconciled copy — by first computing exactly where they differ, then composing them under an explicit merge policy. Its defining move, and what separates it from an automatic conflict-free merge, is that it makes divergence visible and adjudicable: changes on disjoint fields are merged silently, but where both sides edited the same thing it does not guess — it raises a conflict that a rule or a person resolves. It is the reconciliation path for state that has no built-in conflict-free algebra, where a human-legible before/after is worth more than a hands-off merge.

Example

Head office and a regional manager each hold an offline copy of the same 3,000-SKU price list, last synced Monday. Over the week HQ adds 40 seasonal SKUs and retires a discontinued line; the manager marks 60 local items down for a clearance event. On Friday the tool reconciles the two copies against Monday's version — a three-way diff — so it can tell who changed what, not merely that the copies differ. The new SKUs, the retirement, and 58 of the markdowns touch disjoint rows and merge automatically. Two items, though, were repriced by both: HQ set a new list price while the manager set a clearance price. The tool does not silently pick one; it flags those two rows as conflicts, shows all three values (base, HQ, regional) side by side, and lets the pricing lead decide. The output is a single merged list plus a short, auditable record of what merged cleanly and what was arbitrated.

How it works

The distinguishing method is the three-way comparison and the clean/conflicting split:

  • Anchor on a common ancestor. Diff each copy against the last shared version, not against each other, so the tool learns who changed what rather than only that they differ.
  • Classify every change. Edits on disjoint fields are non-overlapping and safely composable; edits touching the same cell from both sides are overlapping.
  • Merge the clean, isolate the rest. Apply the merge policy to non-overlapping changes automatically; collect overlapping ones into an explicit conflict set with every side shown.
  • Emit a reviewable result. Produce the merged copy plus a diff/merge record of what was auto-applied and what was resolved.

Tuning parameters

  • Comparison granularity — row, field, or character level; finer granularity turns would-be conflicts into clean merges but costs metadata and can split one logical decision into two.
  • Ancestor model — three-way (against a common base) versus two-way (copy against copy); three-way merges far more safely, two-way is cheaper but treats every difference as a candidate conflict.
  • Default merge policy — for non-overlapping changes: union, prefer-ours, or prefer-theirs; sets what happens without human input.
  • Conflict sensitivity — whether identical concurrent edits or formatting-only changes count as conflicts; loosening cuts noise but risks a wrong silent merge.
  • Auto-resolve rules — codified shortcuts ("regional markdown beats base price") that shrink the conflict set — powerful, and dangerous when a rule outlives the assumption behind it.

When it helps, and when it misleads

Its strength is a legible, auditable reconciliation: a person can see precisely what diverged and sign off on how it was settled — exactly what high-stakes or regulated data needs, where a silent automatic merge would be unacceptable. Its central failure mode is the semantic merge conflict — a change that merges cleanly by structure but is wrong by meaning, because two edits on different fields were really one coupled decision.[1] It also scales poorly as conflict volume grows: a tool that dumps thousands of conflicts on a human each sync has merely relocated the bottleneck. The classic misuse is trusting a clean auto-merge on semantically coupled fields, or tuning auto-resolve rules until the conflict set is empty and calling that convergence. The discipline is to reserve auto-merge for genuinely independent fields, keep the merge record, and route the conflicts no rule should settle to Exception Queue Review.

How it implements the components

  • state_equivalence_test — the diff is the equivalence test at field granularity: it reports exactly where the two copies agree and where they have drifted.
  • state_merge_policy — the codified rules for composing non-overlapping changes into one copy (union, prefer-side).
  • conflict_resolution_rule — the tool's automatic tier: three-way auto-resolution and take-ours / take-theirs for the overlaps it can settle mechanically.

It does not carry the causal_context_or_version_frontier that decides which edits are truly concurrent (Version-Vector or Dotted-Context Exchange), run the scalable drift_detection_signal scan that finds divergence cheaply (Merkle-Tree Divergence Scan), or walk the unresolved_conflict_escalation_path for conflicts it cannot settle — that is Exception Queue Review.

Notes

The line between this tool and an automatic CRDT-Like State Merge is what happens to concurrent edits of the same value: a CRDT resolves them by a fixed algebra with no human in the loop, while this tool deliberately stops and asks — trading hands-off convergence for a decision record. Choose it when being able to explain the merge matters more than never pausing for one.

References

[1] A semantic merge conflict — two changes a line- or field-level merge combines without complaint but that are logically incompatible — is the standard argument for review over blind auto-merge: structural cleanliness is not semantic correctness. ↩