Prerequisites

Why Wall Clocks Fail

The intuitive approach to ordering distributed events is to stamp each with the local time and sort. This fails for reasons that are physical rather than implementational.

The Happens-Before Relation

Rather than asking about absolute time, we ask whether one event could possibly have influenced another. This defines a partial order over events.

Concurrency Means Independence

If neither event happens before the other, they are concurrent. This is a statement about causal independence, not about simultaneous occurrence.

Lamport Clocks

A Lamport clock is a single counter per node, maintained by two simple rules. It is the minimal mechanism that respects happens-before.

class LamportClock {
    constructor(nodeId) {
        this.nodeId = nodeId;
        this.counter = 0;
    }

    tick() {
        this.counter += 1;
        return this.counter;
    }

    send() {
        return {
            nodeId: this.nodeId,
            timestamp: this.tick()
        };
    }

    receive(messageStamp) {
        this.counter = Math.max(
            this.counter,
            messageStamp.timestamp
        ) + 1;

        return this.counter;
    }

    compare(other) {
        if (this.counter !== other.timestamp) {
            return this.counter - other.timestamp;
        }

        return this.nodeId.localeCompare(other.nodeId);
    }
}

The Guarantee and Its Limit

The converse does not hold. A smaller counter does not prove causal precedence, because two independent nodes can reach the same counter values without any interaction.

Vector Clocks

A vector clock replaces the single counter with one counter per node. Each node tracks what it knows about every other node's progress, which is enough to detect concurrency.

class VectorClock {
    constructor(nodeId, initial = {}) {
        this.nodeId = nodeId;
        this.vector = { ...initial };
        this.vector[nodeId] = this.vector[nodeId] ?? 0;
    }

    tick() {
        this.vector[this.nodeId] += 1;
        return { ...this.vector };
    }

    merge(incoming) {
        const nodes = new Set([
            ...Object.keys(this.vector),
            ...Object.keys(incoming)
        ]);

        for (const node of nodes) {
            this.vector[node] = Math.max(
                this.vector[node] ?? 0,
                incoming[node] ?? 0
            );
        }

        this.vector[this.nodeId] += 1;
        return { ...this.vector };
    }
}

Comparing Two Vectors

function compareVectors(a, b) {
    const nodes = new Set([
        ...Object.keys(a),
        ...Object.keys(b)
    ]);

    let aGreater = false;
    let bGreater = false;

    for (const node of nodes) {
        const av = a[node] ?? 0;
        const bv = b[node] ?? 0;

        if (av > bv) aGreater = true;
        if (bv > av) bGreater = true;
    }

    if (aGreater && bGreater) return "concurrent";
    if (aGreater)             return "a-after-b";
    if (bGreater)             return "b-after-a";

    return "equal";
}

Worked Comparison

Consider two replicas that both update a record while partitioned from each other.

Version Vectors

Version vectors apply the same principle to replicated data items rather than to events. Counters are keyed by replica, and the vector travels with the value.

{
    "key": "cart:user-4821",
    "siblings": [
        {
            "value": { "items": ["sku-501", "sku-733"] },
            "versionVector": { "replica-east": 4, "replica-west": 2 },
            "writtenAt": "2026-09-24T05:31:02Z"
        },
        {
            "value": { "items": ["sku-501", "sku-910"] },
            "versionVector": { "replica-east": 3, "replica-west": 3 },
            "writtenAt": "2026-09-24T05:31:07Z"
        }
    ],
    "conflictDetected": true,
    "resolutionRequired": "application"
}

The Cost of Vectors

Vector clocks carry a real cost that grows with participant count, which is the principal reason they are not used universally.

Hybrid Logical Clocks

Logical clocks capture causality but produce values meaningless to humans and unusable for time-range queries. Hybrid logical clocks combine physical time with a logical counter.

class HybridLogicalClock {
    constructor() {
        this.physical = 0;
        this.logical = 0;
    }

    now() {
        const wall = Date.now();

        if (wall > this.physical) {
            this.physical = wall;
            this.logical = 0;
        } else {
            this.logical += 1;
        }

        return { physical: this.physical, logical: this.logical };
    }

    update(remote) {
        const wall = Date.now();
        const maxPhysical = Math.max(
            wall,
            this.physical,
            remote.physical
        );

        if (maxPhysical === this.physical &&
            maxPhysical === remote.physical) {
            this.logical = Math.max(this.logical, remote.logical) + 1;
        } else if (maxPhysical === this.physical) {
            this.logical += 1;
        } else if (maxPhysical === remote.physical) {
            this.logical = remote.logical + 1;
        } else {
            this.logical = 0;
        }

        this.physical = maxPhysical;
        return { physical: this.physical, logical: this.logical };
    }
}

Choosing a Mechanism

Resolving Detected Conflicts

Detection is only half the work. Once concurrency is identified, the application must decide what the correct outcome is.

function resolveCartConflict(siblings) {
    const mergedItems = new Map();
    const removedItems = new Set();

    for (const sibling of siblings) {
        for (const item of sibling.value.items) {
            mergedItems.set(item.sku, {
                sku: item.sku,
                quantity: Math.max(
                    mergedItems.get(item.sku)?.quantity ?? 0,
                    item.quantity
                )
            });
        }

        for (const sku of sibling.value.removed ?? []) {
            removedItems.add(sku);
        }
    }

    for (const sku of removedItems) {
        mergedItems.delete(sku);
    }

    return {
        items: Array.from(mergedItems.values()),
        removed: Array.from(removedItems),
        versionVector: mergeVectors(
            siblings.map(s => s.versionVector)
        )
    };
}

Causal Tracing in Practice

Beyond conflict detection, causal metadata is valuable for understanding what actually happened across services during an incident.

{
    "eventId": "evt-9f41",
    "service": "order-service",
    "hlc": { "physical": 1790005872341, "logical": 3 },
    "causedBy": ["evt-8c17", "evt-8c22"],
    "traceId": "trace-4b2f",
    "operation": "order.confirmed"
}

Common Pitfalls

Monitoring

Common Design Mistakes

System Design Interview Discussion

Design Checklist

Knowledge Check

Summary

Physical clocks cannot order events across machines, because drift, synchronization error, and backward adjustments mean timestamps do not reliably reflect what happened first. Building conflict resolution on them silently discards valid writes.

The happens-before relation replaces absolute time with causal influence, defined through program order, message passing, and transitivity. Events unrelated by this relation are concurrent, regardless of how far apart they occurred.

Lamport clocks provide a total order consistent with causality using a single counter, but the implication runs only one way. They cannot distinguish concurrency, so they impose an order on conflicts rather than revealing them.

Vector clocks and version vectors track one counter per node or replica, making concurrency detectable when neither vector dominates. This costs space linear in participants, which is why keying by replica and pruning stale entries matter. Hybrid logical clocks offer causal ordering with readable timestamps but still cannot detect conflicts.