Hybrid Logical Clocks and Practical Time-Aware Ordering

Learning outcomes

Pure Lamport clocks give causal-compatible order but no approximate wall time. Raw wall clocks give human-meaningful time but can move backward or disagree. A Hybrid Logical Clock (HLC) combines a physical-time-derived component with a logical counter, allowing the clock to stay near physical time while maintaining the logical monotonicity needed for causality-aware protocols.

1. Why hybridize logical and physical time?

Many systems need timestamps that are easy to compare with retention windows, logs, or time-based snapshots, yet also need local/message ordering to remain monotonic when physical clocks wobble. The HLC work by Kulkarni and colleagues addresses this gap. An HLC maintains a logical clock whose main component stays close to the node's physical/NTP clock and uses a counter to preserve ordering when physical time does not advance enough.

The simplified representation in this lesson is a pair (l,c). The first component l tracks the maximum relevant physical/logical time seen; c orders events that share that l value.

2. Local-event update

On a local event, compare the current HLC physical component with the current physical-clock reading. If physical time advanced beyond the HLC, adopt it and reset the logical counter. If physical time stayed equal or moved backward, keep the HLC physical component and increment the logical counter. The HLC therefore remains monotonic even when the physical input is temporarily non-monotonic.

physical_now > hlc.l : hlc = (physical_now, 0)
physical_now <= hlc.l: hlc = (hlc.l, hlc.c + 1)

3. Receive-event update

A receive event must be later than the receiver's current HLC, the sender's attached HLC, and the receiver's current physical reading. The algorithm chooses the maximum physical component and then advances the logical counter according to which source or sources supplied that maximum. This keeps the receive timestamp greater than the send timestamp while retaining proximity to physical time.

4. What HLC does and does not prove

This distinction is essential. Some production databases use HLC-like metadata inside larger transaction/replication protocols. Their externally visible guarantees come from the whole protocol, not from the clock data type alone.

5. Deliberately wrong approach — “HLC means timestamps are trustworthy enough for every invariant”

An HLC can make causal ordering robust to ordinary physical-clock regressions, but it does not convert approximate time into a universal concurrency token. If AtlasMart uses only an HLC comparison to decide who owns the last inventory unit, concurrent requests can still need coordination or a conflict rule. If compliance requires traceability to UTC within a bound, the operator still needs monitored clock synchronization and uncertainty/error policy.

The safer framing is: HLC is ordering metadata with physical-time structure. Then separately state the consistency protocol, clock-health assumptions, allowable skew, failure behavior, and business invariant.

6. AtlasMart lab — HLC through clock regression and a message

from dataclasses import dataclass

@dataclass(order=True, frozen=True)
class HLC:
    physical: int
    logical: int

class HLCNode:
    def __init__(self, name):
        self.name = name
        self.hlc = HLC(0, 0)

    def local(self, physical_now):
        old = self.hlc
        l = max(old.physical, physical_now)
        c = old.logical + 1 if l == old.physical else 0
        self.hlc = HLC(l, c)
        return self.hlc

    def receive(self, physical_now, remote):
        old = self.hlc
        l = max(old.physical, remote.physical, physical_now)
        if l == old.physical == remote.physical:
            c = max(old.logical, remote.logical) + 1
        elif l == old.physical:
            c = old.logical + 1
        elif l == remote.physical:
            c = remote.logical + 1
        else:
            c = 0
        self.hlc = HLC(l, c)
        return self.hlc

A, B = HLCNode("A"), HLCNode("B")

print("A local event at physical 1000:", A.local(1000))
print("A clock source moves backward to 980:", A.local(980))
msg = A.local(990)
print("A sends message while physical says 990:", msg)

print("\nB physical clock is 970 when message arrives")
recv = B.receive(970, msg)
print("B receive HLC:", recv)
print("B local at physical 975:", B.local(975))

print("\nproperties shown by this simulation")
print("- HLC did not move backward when physical input moved backward")
print("- receive timestamp is greater than the sent timestamp")
print("- physical component remains near the supplied physical-clock values in this toy history")
print("- scalar HLC order still does NOT prove that two unrelated events were causal")

Expected output

A local event at physical 1000: HLC(physical=1000, logical=0)
A clock source moves backward to 980: HLC(physical=1000, logical=1)
A sends message while physical says 990: HLC(physical=1000, logical=2)

B physical clock is 970 when message arrives
B receive HLC: HLC(physical=1000, logical=3)
B local at physical 975: HLC(physical=1000, logical=4)

properties shown by this simulation
- HLC did not move backward when physical input moved backward
- receive timestamp is greater than the sent timestamp
- physical component remains near the supplied physical-clock values in this toy history
- scalar HLC order still does NOT prove that two unrelated events were causal

Node A's physical input falls from 1000 to 980, yet its HLC remains at physical component 1000 and advances the logical counter. The message carries that state to B, whose own physical input is only 970; B's receive HLC advances beyond the send. The simulation deliberately avoids claiming a real-world skew bound.

Verification checklist

• Physical inputs are synthetic integers; the host clock is untouched.
• A's HLC never decreases during the backward physical input.
• B's receive HLC is greater than A's sent HLC.
• The physical component remains near the sample physical values in this small model.
• The lesson explicitly states that scalar HLC comparison does not detect concurrency.

7. Production judgment and next bridge

HLCs are useful when a system wants logically safe ordering that remains time-like: change streams, snapshot timestamps, version metadata, or distributed transaction protocols can benefit. Record the exact HLC algorithm and comparison semantics because implementations vary. Persist and recover clock state carefully if protocol correctness depends on monotonicity, and test restarts plus large clock regressions in isolated simulation.

Lesson 5 moves from clock structures to application contracts. Version numbers, ETags, timestamps, and idempotency keys answer different questions: “has this resource changed?”, “may I overwrite this exact representation?”, “approximately when?”, and “has this logical request already produced a side effect?” Mixing them creates subtle lost updates and duplicate actions.

Authoritative references

• Kulkarni et al. — Logical Physical Clocks / Hybrid Logical Clocks — primary HLC design and its relationship to logical and physical clocks
• Lamport — Time, Clocks, and the Ordering of Events — foundational logical-clock and physical-clock framing
• RFC 5905 — NTPv4 — physical clock synchronization and discipline context that HLC does not replace