Monotonic Clock Offset Sync Agent Skill

Two clocks, one offset, estimated from round trips

Every device in a synchronised room runs its own clock with its own drift, so "resume at 1234"

means nothing until both ends agree what time it is. A pong that carries back the client's send

time plus the peer's own receive and send times has everything needed to estimate one-way latency,

and from that the offset between the two clocks:

// adapted — names generalized; the lock, the sample-validity checks and the accessors are elided
val receivedAt = elapsedRealtime()                       // MONOTONIC, injected by the caller
val roundTrip = receivedAt - clientTime
val peerProcessing = peerSendTime - peerReceiveTime
// Time the peer spent thinking is not time on the wire, so it comes out before the halving.
val networkRoundTrip = max(0L, roundTrip - peerProcessing)
val sampleOffset = peerSendTime + networkRoundTrip / 2.0 - receivedAt

if (networkRoundTrip < bestRoundTripMs) bestRoundTripMs = networkRoundTrip
val weight = if (networkRoundTrip <= bestRoundTripMs + GOOD_SAMPLE_MARGIN_MS) 0.25 else 0.05
offsetMs = offsetMs?.let { it + weight * (sampleOffset - it) } ?: sampleOffset

offsetMs is nullable and that nullability is the feature: everything downstream has to say what it

does when the clock has not been calibrated yet.

Traps

Halving the whole round trip charges the peer's think-time to the network. A relay that queues

a frame for 40 ms adds 40 ms to the measured round trip; halve that and the one-way estimate is

20 ms too large, permanently, on every sample the peer is slow to answer. The peer's receive and

send times are in the message precisely so the difference can be removed first. If the peer does not

report both, you cannot subtract it — and you should treat the resulting offset as a floor rather

than pretending it is exact.

The local source must be monotonic, and it must be injected rather than read. An offset is a

difference between two readings of the same local clock; a wall clock that a network time correction

steps backwards makes that difference meaningless and the derived position jump. Take the source as

a constructor parameter — () -> Long — so each platform passes its own and a test passes a

variable it controls. Reading a wall clock directly inside the estimator also makes it untestable,

which is how a wrong formula survives.

"Not calibrated yet" must fall back to the raw value, never to a guess. Each accessor answers

the uncalibrated case explicitly: the "what time is it" accessor returns null, and the position

correction returns its input unchanged. A wrong seek is worse than a slightly late one — a listener

notices a jump instantly and does not notice a 200 ms lag at all. The same rule covers a peer that

sends 0 for its timestamp: 0 means *unknown*, so it must short-circuit to the raw position, not run

through the arithmetic where it becomes "however long ago the epoch was".

Weighted, not averaged — which is why the first pings must come in a burst. A flat mean lets one

congested frame drag the whole room; weighting each sample by how close its round trip is to the

best seen (0.25 when it is good, 0.05 when it is not) keeps a bad frame at the noise level. The cost

is that the estimate moves slowly: the first sample *sets* the offset outright and every later one

shifts it by at most a quarter. So the ping loop has to send its first few close together and only

then open up to its steady interval, or someone joining in the first seconds seeks against an

estimate built from one sample.

Reject a sample before folding it in, not after. Five cheap checks pay for themselves: a

non-positive send time, a send time in the local future, a sample older than a cap, a peer whose

send time precedes its own receive time, and a peer *receive* time of zero. That last one is the

guard tests forget, and it has the nastiest tail: unguarded, the peer's think-time becomes its whole

send time, the network round trip collapses to zero, the best-seen baseline pins itself there for

the life of the session, and every later sample is weighted down to noise. The other four produce an

offset wrong by minutes, and once folded in it stays — the weighting that protects against noise

also means a poisoned estimate takes many good samples to walk back.

Make "the clock became usable" an event. The fold returns true only for the *first* accepted

sample. That boolean is what lets the layer above announce that corrected positions are now

available, and it exists because there is otherwise no way to distinguish "offset is zero" from "no

offset yet" once the value has been unwrapped. Callers that need the distinction must read the

nullable value, not a defaulted one.

The formula is a contract between peers, so its test numbers are copied, not recomputed. Every

client in the room has to derive the same position from the same message; an arithmetic cleanup that

shifts the result by a few milliseconds is a desync, not a refactor. Pin the expected values as

literals taken from the reference implementation and say in the test why they may not be

"simplified". Related: position-based-group-sync is what consumes this offset, and

borrowed-wire-protocol-discipline is the same rule applied to the message shapes.

Verifying it

The estimator is small and its correctness is mostly about which clock feeds it, so check the clock

sources across the tree rather than reading the arithmetic again:

grep -rnE 'TimeSource\.Monotonic|elapsedRealtime' --include='*.kt' . | grep -v '/build/'
grep -rn 'currentTimeMillis()\|Clock\.System\.now()' --include='*.kt' . | grep -v '/build/' | cut -d: -f1 | sort -u
grep -rnE 'roundTrip|RoundTrip|[Oo]ffset[Mm]s' --include='*.kt' . | grep -v '/build/'

The first is the monotonic census: expect the injected source, its default anchored at a process-start

mark, the ping that stamps its own send time, and the test substituting a plain variable — all in the

sync module, plus any monotonic anchor elsewhere that is not feeding the estimator at all. Those are

legitimate and the third command is what tells them apart: a file that takes a mark but never shows

up in the arithmetic census is not a second estimator. The second lists *files* holding a wall clock; the two lists must be disjoint, and a file

appearing in both is the defect this skill exists for. The third collects the arithmetic itself: count

the hits per file and expect one file to hold effectively all of them. The stray matches — an

*OffsetMs field on some response model, a test named …RoundTrip… — are noise, not a second

estimator; a *second* file with the arithmetic in it is the thing to worry about, because two copies

of this formula drift.

Then read the test file rather than trusting the code comments: it should assert a null reading

*before* any sample, an exact wall time after one, an unchanged position while the stream is not

running, and an unchanged position after a reset. If a test only asserts that the offset is "close

to" something, it cannot catch the halving mistake at the top of the traps, which is worth exactly

half the peer's queueing delay and nothing else.