QUEUEZ

ordering a feed by its sequence, because on a real recorded session the clock goes backwards.

A feed's sequence is the only ordering a consumer can trust, and this is the number that says so: on a session recorded from a real public push feed, in offset order, the wall clock steps backwards 547 times out of 2,024, by as much as 26 seconds, while the offset never does. Every rule here asserts on sequence continuity and none of them looks at a clock. The consumer stores its offset in the sink in the same transaction as the write, which is tested by failing the second write and asserting the first was rolled back, because that is the only crash a transaction is for.

Tests
79
Python
3.11 to 3.13
Release
v0.1.0

The demo, as it really ran

$ uv run python examples/the_clock_goes_backwards.py

2025 events, recorded from a real public feed, in offset order.

  the sequence is monotone with 0 gaps
  the Unix second in payload.timestamp goes BACKWARDS 547 times,
  by up to 26 seconds. The ISO instant in meta.dt goes backwards
  13 times, by up to 0.012 seconds.

  offset 6463284365 says 1787992234 and 2026-08-29T08:30:35.458Z
  offset 6463284366 says 1787992208 and 2026-08-29T08:30:35.473Z
  so the Unix second went back 26 seconds there while the ISO instant
  went FORWARD 0.015 seconds. They disagree about the direction too.

  A gap detector built on time reports gaps that are not there and misses the
  ones that are. Every rule here asserts on the sequence and none looks at a clock.

The two also disagree about size, on 1576 of 2025 events:
  the ISO instant sits between 0.036s and 27.5s after the
  Unix second, and never before it.

Now the same session with four failures injected, 2035 events:

  2022 applied
  12 ignored, the resent window arriving twice
  1 applied as a correction of a consumed record
  2 gaps suspected while events were arriving
  3 offsets that never arrived at all

  The injected gap was 3 offsets wide, so one of those
  suspected gaps was not a gap: it was the out-of-order delivery, resolving when
  the offset behind it turned up. Alerting on the first number pages somebody
  for a feed that is working.

Replaying the whole tape a second time applies 0 events and
ignores 2035. At-least-once delivery makes that ordinary.

Output captured on 2026-08-30. It is committed to the repository and a test fails when it stops matching a live run, so this page cannot quietly drift from the code it describes.

Read it

The rest of the toolset