Time-travel · dive 01

Time is the address

A wall-clock instant is an exact id position — two bounds, one floor, one ceiling, and nothing approximate.

The stream log proved that within one brand, byte-order == snowflake-order == mint order. A consequence falls out of it: a %DateTime{} is not something you search the log for — it maps to an exact position in the id space. Every entry id is "<ms>-<seq>", a millisecond and a 22-bit tail, so an instant dt becomes a pair of bounds: minid_floor/1 the half-open lower edge, maxid_ceil/1 the inclusive upper inverse. Move the instant on the right and watch each edge stay exact — not "close enough."

The two edges The floor and the ceil Why exact Pattern & implementation References

An instant · the two edges

Both edges derive from the same true Unix-millisecond of dt; they differ only in the sequence tail — 0 for the floor, the maximal 0x3FFFFF for the ceiling.

The two edges, exact by construction

An instant dt compiles to two bounds, and each edge is exact — it draws the line at the right millisecond, not near it.

minid_floor(dt) → "<ms>-0" is the smallest id at or after dt. The ms is the true Unix-millisecond of dt; the tail -0 is the lowest sequence at that millisecond. As an XRANGE from it is the half-open lower edge: it excludes every entry minted in an earlier millisecond and includes everything at dt onward — a dt − 1ms entry is out, a dt entry is in.

maxid_ceil(dt) → "<ms>-<0x3FFFFF>" is the largest id mintable at or before dt. The same true ms, and the tail 0x3FFFFF is the maximal 22-bit node|seq — the ceiling of the snowflake's tail slice. As an XRANGE to it is the inclusive upper edge: it admits every entry whose mint millisecond is ≤ dt (any sequence at that ms is ≤ 0x3FFFFF by construction) and excludes the first entry of dt + 1ms — a dt entry reads back, a dt + 1ms entry does not.

The floor and the ceil, extracted

The real minid_floor/1 and maxid_ceil/1 — the two halves of the address arithmetic. Notice what they share: the same ms derivation. They differ only in the tail, which is exactly what makes one the half-open lower edge and the other the inclusive upper edge.

# echo_mq — EchoMQ.Stream
# The maximal 22-bit `node|seq` tail (0x3FFFFF) — the largest seq an xadd id can
# carry at one millisecond. It is the ceiling maxid_ceil/1 uses; minid_floor/1
# uses 0, the floor. The two edges differ ONLY in this tail.
@max_seq 0x3FFFFF

# The MINID floor id "<ms>-0" for a horizon dt: the smallest entry id at or after
# the instant. ms is the true Unix-ms of dt; the tail -0 is the lowest sequence at
# that ms. The half-open [dt, …) lower edge is EXACT: a dt-1ms entry is OUT, a dt
# entry is IN. NEVER a raw snowflake integer to the wire — the wire wants ms-seq.
def minid_floor(%DateTime{} = dt) do
  ms = EchoData.Snowflake.unix_ms(EchoData.Snowflake.min_for(dt))
  "#{ms}-0"
end

# The INCLUSIVE upper-bound id "<ms>-#{@max_seq}" for a window end dt — the inverse
# of minid_floor/1, the LARGEST id mintable at or before dt. The SAME true ms; the
# seq is the maximal tail (0x3FFFFF). So XRANGE … "<ms>-#{@max_seq}" admits every
# entry whose mint ms is <= dt and excludes the first entry of dt+1ms: the inclusive
# [.., dt] edge is EXACT — a dt entry reads back, a dt+1ms entry does not.
def maxid_ceil(%DateTime{} = dt) do
  ms = EchoData.Snowflake.unix_ms(EchoData.Snowflake.min_for(dt))
  "#{ms}-#{@max_seq}"
end

The ms is computed the same way in both — unix_ms(min_for(dt)), which equals DateTime.to_unix(dt, :millisecond). The bound is derived from the instant and the known snowflake layout; nothing is reverse-engineered at read time.

Why exact — and why ms-seq, never the raw integer

The edges are exact for one structural reason: the stream is mint-ordered, and one brand makes byte-order == snowflake-order. Were two brands interleaved on a stream, byte-order would no longer equal mint-order across them, and a millisecond bound would no longer cleanly separate “before dt” from “at dt.” The kind door that admits a single brand (EVT) per stream is what keeps the time address sound. The address arithmetic and the kind door are the same theorem read from two sides.

And the bound is always the wire's "<ms>-<seq>" shape, never the raw snowflake integer behind it. A snowflake is a 63-bit integer; handing it to XRANGE would be a silent malformation — wrong in a way the single-node store would not loudly reject. minid_floor/1 and maxid_ceil/1 exist precisely to hold that discipline: they translate an instant into ms-seq, and nothing else touches a bound. It is the same care the trim path takes for its MINID floor.

Sweep the instant · the bounds it compiles to

instant — dt

Pattern & implementation

the pattern (Redis Patterns Applied)

A time-range query over a stream uses the entry's ms-seq id as the range bound; XRANGE start end is half-open/inclusive on the ids you give it. Streams & Events teaches the time-range read.

the implementation (echo_mq)

minid_floor/1 and maxid_ceil/1 derive those bounds from a %DateTime{} — the floor the half-open lower edge, the ceil the inclusive upper inverse — so an instant is an exact id position, sound because the stream is mint-ordered under one brand.

The pattern hands you a range read; the implementation hands you the address — the two edges that turn a wall-clock instant into exact id bounds.

Recap — the instant is an address

A %DateTime{} is an exact address into a mint-ordered log. minid_floor/1 gives the half-open lower edge "<ms>-0"; maxid_ceil/1 gives the inclusive upper edge "<ms>-<0x3FFFFF>" from the same true millisecond. Both are exact because one brand makes byte-order equal mint-order, and both speak the wire's ms-seq shape rather than a raw integer. The next dive composes the two edges into the two reads.

Next in the module: The two reads — read_since/5 and read_window/6, the open and closed windows over the byte-frozen read/6.

References

Where the floor and ceil bounds are grounded, and the id layout they rest on.

Sources

Valkey — XRANGE — the start/end id bounds the floor and ceil become.
Valkey — Introduction to Streams — the ms-seq entry id layout the bounds are expressed in.
Lamport — Time, Clocks, and the Ordering of Events — the order the id encodes.

Related in this course

The order theorem — the theorem that makes the address exact.
The two reads — the floor and ceil composed into read_since/5 and read_window/6.
Time-travel — the module hub.
The Branded Component System · the Bus — the manuscript chapter this module realizes.