Shaurya Singh

← work

earclock

A two-clock conformance harness for voice agents — and the four load-bearing bugs somebody else's tests found in it that mine did not.

prototype · 2026-09

A voice agent runs two clocks. The send clock is what the process knows: bytes handed to the carrier, position in the utterance it is producing. The play clock is what the human received, out of a speaker, in air. Every property anyone cares about is defined on the second one — where the interruption landed, what the caller had heard when they spoke over you, whether the disclosure was disclosed — and the agent has no sensor on it.

I got that inference wrong in both directions inside three weeks. A send loop was shipping 320 bytes of mulaw — 40ms of sound — every 20ms: twice real time, for the whole length of every reply. I changed one character, shipped it, and logged it as the root cause. It was reverted before the next call. Then telemetry measured the loop at roughly 134ms per send against a 40ms chunk, which is an underrun, not a runaway buffer. The direction of my whole story was wrong, and that audio bug is still UNKNOWN, not fixed. The essay this comes out of carries reverted as its status stamp for exactly that reason.

What survived the rollback was the distinction, not the fix. earclock is that distinction made into a harness: it gives you the play clock in simulation, then makes the assertions you need impossible to write against the wrong one.

The mechanism

A MediaSink is a simulated carrier exposing send_position, play_position and frontier_lag over simulated time. A Transcript is one record with two offsets: how far the model got, how far the caller got. An ObligationLedger registers a required disclosure on the send side and discharges it only from the ear.

The harness fails on real defects before it passes on anything. Four known-bad configurations ship inside it, and all four must be rejected every run:

shaurya@sps ~ % earclock conformance
[  REJECTED  ] pacing: 320B mulaw_8000 every 20ms
[  REJECTED  ] obligation discharged on generation
               GenerationSideDischargeError: obligation 'recording_disclosure' was
               discharged with a Chunk, not a play-side DeliveryReceipt.
               Producing audio is not delivering it.
[  REJECTED  ] interrupt index from send position
[  REJECTED  ] post-barge-in context contains unheard text

4/4 defects rejected

(Every rejected case prints its exception under it. Three of the four are elided here, and the one kept is soft-wrapped to fit — it is one line in the terminal.)

A case that stops failing is reported as SILENT_PASS and fails the run. A checker that has rotted reports the same all-clear as a checker that found nothing.

The demo runs one reply through both send loops, interrupt at the same instant, one constant different. This is its comparison table with six of the ten rows kept; chunk count, wall clock at interrupt, frontier lag and playback gaps are dropped:

shaurya@sps ~ % python examples/demo.py
                                   20ms (defect)    40ms (corrected)
  send position                           2.000s              1.000s
  play position                           1.000s              1.000s
  audio discarded unheard                 1.000s              0.000s
  generated offset (chars)                   235                 144
  delivered offset (chars)                   144                 144
  stale characters                            91                   0

Both callers heard the same 144 characters, because both heard one second of speech. The defective loop believed it had said 235. Those 91 were produced, logged as said, discarded unheard, and would have gone into the next turn as things the caller had been told. Nothing crashes. The call just stops being about the conversation the human is in.

The four bugs I didn’t find

tests/test_adversarial.py is the file somebody else wrote — ten attacks by a verifier who did not build this, whose job was to make it report an all-clear it hadn’t earned. Eight of the ten landed. Four of those eight were defects in earclock itself rather than in the code it was pointed at.

The one that matters most: an obligation cleared unheard was settled by whatever audio next crossed its old position. A clear re-bases the timeline — positions are seconds from the start of the stream, so audio sent after a barge-in occupies second numbers that already named different sound. A disclosure registered at 0.08s, barged over, discarded, then followed by unrelated small talk that pushed the play head past 0.08s was marked delivered. The compliance ledger, whose whole reason for existing is that produced is not delivered, would have certified a disclosure the caller never heard. That is the exact bug the package was built to catch, living inside the package.

The fix is a clear_epoch on the sink and on every obligation. Cross a clear and the address is stale:

shaurya@sps ~ % python
>>> sink = make_sink(codec=MULAW_8000, chunk_bytes=320, pacing_interval=0.04)
>>> ledger = ObligationLedger(sink)
>>> sink.send(320, tag="hello there")                     # 0.00-0.04s
>>> disclosure = sink.send(320, tag="this call is recorded")   # 0.04-0.08s
>>> ledger.register("recording_disclosure", text="this call is recorded", chunk=disclosure)
>>> sink.advance(0.04); sink.clear()          # only the first chunk played
>>> disclosure.cleared
True
>>> sink.send(320, tag="unrelated small talk"); sink.advance(0.04)
>>> ledger.assert_all_discharged()
OutstandingObligationError: obligations never reached the ear: recording_disclosure

The leading chunk is what makes this the real case rather than a toy: the disclosure has to sit behind something to still be in the buffer when the barge-in lands.

The other three: a clear from inside a delivery callback — the natural shape, since barge-in is detected on delivery — drove the play head past the send frontier it had just truncated, leaving frontier_lag negative. DeliveryReceipt could be forged by subclassing it and overriding is_play_side, a public property, needing no private state at all and untouched by the README’s stated limitation. And truncate_to_delivered did not leave the two offsets equal when the cut span kept a partial prefix — invisible in my own tests because every span in them was one character long, so the in-flight entry contributed nothing and the promise was free.

All four are fixed and pinned. I wrote the tests that proved this harness worked; a verifier with no stake in it broke four things those tests were shaped not to see.

What it can’t do yet

  • The fix for the headline bug traded a false discharge for a permanent false debt. An obligation that survives a clear can never be discharged, not even by a faithful re-delivery of the same disclosure, and register() refuses to reuse the id. I confirmed it: re-send it, play it fully, it stays outstanding forever. “Did this reach the ear” is now answered correctly, and the API cannot say “and then it did.”
  • assert_play_clock_offset compares values, not clocks. On a drained call the send frontier and the play head agree, so an index computed the wrong way passes. The verifier filed that as a property of the checker rather than a bug, and it is the more uncomfortable finding: the guard is blind exactly when the buffer is empty.
  • The context checker is one-sided. It catches text the caller never heard, not text the agent forgot, so an empty context passes every time. Saying nothing is always safe, which is not the same as being right.
  • The pacing tolerance has no term for how long the call runs. One chunk against one interval, 1% of slack. 320 bytes of mulaw every 39.7ms passes the build; 400 seconds later the send clock is about three seconds ahead of the ear, and a test runs that out and asserts it. An [OK] means “not wrong by a factor,” not “paced.”
  • This is not a carrier. Nothing opens a socket or watches a real playback scheduler. The model — 1x while queued, stall when empty, discard on clear — is my assumption about how a media stream behaves. If a real one smooths, resamples, or partially honours clear, the delivered offsets are wrong in a direction I can’t predict. Codecs are constant-bitrate too, and delivered_text spreads characters evenly across a chunk, which real synthesis does not.
  • Everything is synchronous and single-threaded. A single-slot live receipt and a boolean dispatching flag are the shape of a model with one play head in one thread. The first thing an event loop will do is put two of something where this code assumes one.

Two hundred and forty-six tests pass and two skip, in under a second, on the machine I am writing this on today. The skips are property cases where the seeded generator drew ratio 1.0 into the slow-loop family, which the paced family already covers. That is a measurement of this code as it stands — and the previous version of that same number was green, true, and blind to four defects until somebody else came looking.

— Shaurya

← back to work