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
66
Python
3.11 to 3.13
Release
v0.1.0
Licence
MIT

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 wall clock goes BACKWARDS 547 times, by up to 26 seconds

  offset 6463284365 says 1787992234
  offset 6463284366 says 1787992208, which is 26 seconds earlier

  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.

Each event also carries two clocks, and they disagree on 1576 of 2025:
  the ISO instant sits between 0.036s and 27.5s after the other,
  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-29. 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