Vector Clocks, Explained With a Budget

In short: When the same data is edited on several devices, "keep the newest" is unreliable, because device clocks disagree and messages arrive late. Vector clocks record what each device had seen, so a system can tell a genuine conflict from an update that simply arrived late. I explain them with a budget, plus three bugs that taught me to handle all four possible outcomes.

My budget lives on a desktop, a laptop and a VPS. Suppose the grocery limit is edited on the laptop, and later a change to the same limit arrives from the desktop. Should the incoming change replace the one I have?

The obvious answer is "compare timestamps, keep the newer one". It's wrong, for two reasons:

• Clocks disagree. The laptop's clock can be minutes off the desktop's. "Newer by the timestamp" can mean "made on the machine whose clock runs fast".
• Arrival order isn't creation order. A change made yesterday can arrive after a change made today, if the machine that made it was offline.

What I actually need to know is not when each change happened, but whether one change knew about the other. That's what a vector clock records.

A vector clock is a counter per machine

Every change carries a small map: for each machine, how many of that machine's changes had been seen when this change was made.

{desktop: 2, laptop: 1}

reads: "this change was made by a machine that had seen the desktop's first two changes and the laptop's first one."

Three operations are all there is:

1. Local change: take the current clock and add one to your own counter.
2. Receive: merge by taking the maximum of each counter (not the sum: summing would invent changes that never happened).
3. Compare two clocks, counter by counter.

Comparing: four answers, not two

func (vc VectorClock) Compare(other VectorClock) ClockRelation {
	hasLess, hasGreater := false, false
	keys := make(map[string]struct{})
	for nodeID := range vc {
		keys[nodeID] = struct{}{}
	}
	for nodeID := range other {
		keys[nodeID] = struct{}{}
	}

	for nodeID := range keys {
		if vc[nodeID] < other[nodeID] { // a missing key reads as 0
			hasLess = true
		} else if vc[nodeID] > other[nodeID] {
			hasGreater = true
		}
	}

	switch {
	case hasLess && hasGreater:
		return Concurrent
	case hasLess:
		return Before
	case hasGreater:
		return After
	default:
		return Equal
	}
}

Comparing over the union of both clocks' keys matters: a machine missing from one clock counts as zero, and both sides reach the same answer however the maps are built.

Stored	Incoming	Relation	What it means for the grocery limit
{desktop:1}	{desktop:2}	Before	The incoming edit saw mine and changed it further: apply it
{desktop:2}	{desktop:1}	After	The incoming edit is older, arriving late: ignore it
{desktop:2}	{desktop:2}	Equal	Same edit, delivered twice: ignore it
{desktop:1}	{laptop:1}	Concurrent	Neither saw the other: a real conflict

Note the last row. {laptop:1} isn't "less" than {desktop:2} just because 1 < 2. A clock is newer only if it's at least as large in every counter. One bigger number means nothing.

Bug 1: treating it as a yes/no question

My first version of the sync handler asked only "is this a conflict?" Anything that wasn't concurrent got applied. That merged two very different cases:

• Before: the incoming edit is newer. Applying it is right.
• After: the incoming edit is older, delivered late. Applying it silently reverts my budget to stale data.

This is precisely the situation vector clocks exist for, and my code threw the answer away. The fix was to handle all four relations explicitly.

Bug 2: comparing a change to itself

An early version compared the incoming change with... the incoming change. A clock is always Equal to itself, so the conflict branch could never run. The code compiled, the tests passed, and conflict detection was dead code. The tests only checked cases where no conflict was expected, so nothing noticed.

Bug 3: a local edit that didn't move forward

When I make a change on the laptop, the new clock must come after everything the laptop already has for that item. The rule is: copy the item's current clock, then increment your own counter.

I hit both ways of getting this wrong:

• Starting from an empty clock. My second edit to an item looked Concurrent with my first, a conflict with myself.
• Forgetting to copy. In Go, a map inside a struct is shared when the struct is copied. Incrementing "my copy" of the clock incremented the stored one too, so old and new compared Equal, and the other machine ignored the edit.

Where this shows up in real systems

• Offline-first apps. Field-service, inspection, sales and healthcare apps used where connectivity is patchy all face the same question when a device reconnects: is this change newer, older, or in conflict with what the server has?
• Replicated databases. Amazon's Dynamo paper used vector clocks to detect conflicting writes across replicas, and Riak built on the same idea.
• Anywhere "last save wins" is the default. Multi-device note-taking, CRMs, shared spreadsheets: without causality tracking, a late-arriving save silently overwrites newer work, and users call it data loss.

What I took away

• Wall-clock time answers "when"; distributed systems usually need "what did you know".
• A comparison with four outcomes deserves four branches. Collapsing them is how stale data wins.
• When a test only covers the cases where nothing interesting happens, it can pass forever while the interesting code never runs.

Next: Retries Are Normal: Building an Idempotent Sync API.

---

About this series: I'm learning distributed systems by building a real application, with an AI assistant as coach and pair programmer. It explains, reviews and sometimes writes code; I verify every claim against tests and measurements, and every bug and number here is real.

I write about building reliable software in Go, from the code up. If you're working on similar problems, I'd like to hear from you: get in touch or connect with me on LinkedIn.