Recipe

Hybrid Logical Clocks

Hybrid logical clocks (HLCs) combine the monotonicity of Lamport timestamps with the wall-clock alignment of NTP, giving you a single 64-bit timestamp that is causally consistent across nodes while still being human-readable. This recipe shows how to wire HLCs into a Meridian-backed event log so distributed writes order deterministically without leaning on a central sequencer.

1.Structure the timestamp

Pack a physical wall-clock component (48 bits of milliseconds since epoch) with a logical counter (16 bits) into a single 64-bit value. The physical part dominates ordering when clocks agree; the counter breaks ties when events happen within the same millisecond.

type HLC = bigint; // 48 bits pt | 16 bits lc

function encode(pt: number, lc: number): HLC {
  return (BigInt(pt) << 16n) | BigInt(lc & 0xffff);
}

function decode(hlc: HLC) {
  return {
    pt: Number(hlc >> 16n),
    lc: Number(hlc & 0xffffn),
  };
}

2.Update on local events

When a node generates an event, sample the wall clock and compare against the last seen HLC. If the wall clock advanced, reset the logical counter; otherwise increment it. This guarantees the emitted timestamp is strictly greater than any prior local timestamp, regardless of clock skew.

3.Merge on receive

On message receipt, take the max of the local physical clock, the remote physical component, and the current wall clock. The logical counter follows the same max rule and increments. This is the heart of the HLC contract: causality is preserved across arbitrary network partitions and clock drift up to your skew bound.