Module clock 

v2.6 #3 Slice B: Hybrid Logical Clock (HLC) for convergent team sync.

An HLC stamps every event with a timestamp that is (a) globally lexicographically sortable, (b) monotonic on a single brain, and (c) CAUSAL across brains — receiving a remote event advances the local clock past it, so any later local event sorts after everything observed. Replaying a merged event log in HLC order is therefore deterministic on every brain, which makes the projection converge field-by-field (last-writer-in-HLC-order wins) without per-field bookkeeping. This generalizes the single-brain (ts, rowid) causal order to the multi-brain case.

The canonical wire/storage form is "{wall_ms:013}.{counter:010}.{node}" — zero-padded so plain string comparison equals causal comparison. 13 digits covers epoch-millis through year 5138; 10 digits covers the full u32 counter range (the counter only grows within a single ms, then resets). The 10-digit width is also wide enough for the v9 migration to backfill a row’s rowid into the counter slot (wall = 0), so old events sort before new ones by a consistent string width.

Structs

Hlc

A Hybrid Logical Clock timestamp.

Functions

now

Generate the next local HLC timestamp (monotonic). Within the same wall millisecond the counter increments; a newer wall clock resets it to 0.

observe

Observe a remote HLC (on sync import): advance the local clock past max(physical, local, remote) so every subsequent local event sorts AFTER everything received — the causality guarantee that makes total-order replay deterministic across brains.

set_node

Set this process’s HLC node id once at startup (first call wins). Use the machine part of the write origin so equal (wall, counter) ties break by machine — a globally consistent total order. Empty input is ignored.