DEV Community: Ruslan Gilmullin

A pause with two sides: the hook contract and the worker protocol

Ruslan Gilmullin — Thu, 21 May 2026 22:43:35 +0000

Suppose you’re writing a Turing-machine interpreter that runs in a Web Worker. The UI needs to show a trace — how the machine steps from state to state, what gets written to the tape, how the head moves. For the user to keep up with what’s on screen, the engine needs a short delay between iterations — milliseconds, regularly, on every step. That’s a throttle of the engine between iterations — regular and predictable, not the “Pause” of the UI button (which stops the machine until the user clicks “Continue”).

So where exactly in the iteration cycle does the worker apply that throttle? There are two candidates, and the choice between them pins two contracts at once: the engine’s hooks and the protocol between worker and main thread. Pick the right point, and you design both sides at once; pick the wrong one, and you break both. This article is about that choice.

Setup

turing-machine-js is a Turing-machine interpreter. The engine has an onStep hook — the handler runs after each machine step. That’s all the engine background you need for this article. For the rest of the engine’s design and previous API changes, see “Three majors, two mistakes: designing a pause API for a Turing-machine interpreter” (1) and “Two majors, one README, one demo: two cheap design reviews” (2).

The first real consumer of the engine is machines-demo, an interactive debugger. The user’s machine runs in a Web Worker; the UI on the main thread shows the trace. The same demo that, in article (2), surfaced two engine majors (#109, #108). This article is the next episode in the life of the same engine: v6.2 → v6.3 → v6.4.

The demo has a RUNNING_AUTO mode: the user picks an interval, clicks “Start”, and the machine steps automatically. Originally the mode was straightforward — the main thread drove step-by-step execution (via runner.step(), a wrapper over the engine’s runStepByStep() in the worker), with setTimeout(intervalMs) inserted between steps for the trace. Simple, and it worked — until the user set a breakpoint.

Breakpoints in the engine fire inside machine.run(): the iteration loop lives in the engine itself, and on hitting a debug-marked state, it pauses itself. runStepByStep(), on the other hand, is a generator: the consumer drives the loop, and breakpoints are invisible to it. machines-demo#43 was this hole — the user sets a breakpoint in RUNNING_AUTO mode, clicks “Start”, and the breakpoint is ignored. For breakpoints to fire, RUNNING_AUTO had to switch from runStepByStep() to run().

But run() keeps its iteration loop inside the engine and doesn’t yield control back. Previously the throttle lived between runner.step() calls on the main thread — that is, on the consumer side, where the consumer controlled the interval between steps. With the switch to run(), that consumer-side gap is gone — the throttle has to either be moved inside the engine (into an existing or new hook) or be dropped. That became the design question.

One more architectural detail we need: the main thread holds a watchdog timer over the worker. If the worker stays silent on messages longer than WORKER_TIMEOUT_MS, the main thread considers it hung (e.g., the user’s machine never reaches halt) and kills it. Whatever place we put the throttle in has to live with that timer.

Where the throttle can live

Two candidates:

Inside onStep — the synchronous hook the engine calls after each step. Its current signature is (state) => void. You could widen it to (state) => void | Promise<void>, and then the handler can await the delay right there.
At the iteration boundary — add a new hook, designed for async waits. Naming aside, what matters is that it fires once at the end of each engine iteration, and the engine awaits the returned Promise.

Both candidates answer “where does the throttle live”. But at the same time they dictate what the worker-main protocol looks like.

If the throttle sits in onStep, it ends up in the middle of each engine iteration — at the point where onStep is called. Everything else in the protocol has to be pinned to that same point: the watchdog timer and the user’s click on “Pause” both hang off this mid-iter delay.

If the throttle sits at the iteration boundary, the worker has a moment at the end of every iteration — the engine isn’t running, it’s awaiting a Promise. In that moment, it’s easy to make peace with the watchdog timer and to be ready for a click on “Pause”.

Now both contracts, one at a time.

Contract “Inside `onStep`”

v6.2.0 took the first path — it widened onStep’s signature from (state) => void to (state) => void | Promise<void>. The handler could now await the delay right where it used to only look at state. From the worker’s side it looked clean — one hook, one wait point, no new entities.

Within a few hours, I marked v6.2.0 as deprecated on npm. Not “a newer version is out, upgrade at your convenience”, but an explicit warning: this version is wrong.

v6.3.0 reverted the signature widening. The reason was straightforward: onStep was meant as an observation hook, not a coordination one. It runs synchronously, in the middle of each iteration, so the consumer can look at state and record it somewhere. Adding await to its signature glues two different jobs into one: observe and hold the engine. A reader of the signature can no longer tell: is this hook “look at this state” or “hold the engine here”? The hook’s purpose stops being visible from the signature.

The symptom that something was wrong showed up in the docs. The README had to explain how to use the widened onStep. An honest paragraph opened with a hedge: “onStep is an observation hook, but you can return a Promise from it, and the engine will await it before the next iteration.” Neither the “but” nor the second half could be cut. The docs were doing exactly what’s described in article (2): prose was pushing on shape — and the shape cracked.

v6.4.0 added a separate hook — onIter. Signature: (state) => void | Promise<void>. Contract: fires once at the end of every iteration, asynchronously, unconditionally. The name — iteration boundary — describes what the hook does (gives a point at the end of an iteration where you can wait), not why a consumer would use it. And it can be used in different ways: for throttling between trace steps, for syncing with the UI, for aborting a run (e.g., via AbortSignal).

The engine’s hook contract now distinguishes three jobs:

— onStep — synchronous, mid-iteration. Observation of state.
— onPause — asynchronous, conditional (fires only on breakpoints). The boundary between running and stopped.
— onIter — asynchronous, unconditional (fires on every iteration). Coordination: holding the engine for the consumer’s async work.

Three hooks, three jobs. Observation shouldn’t hold the engine; for that, there’s a separate asynchronous hook. Holding shouldn’t hide inside an observation hook; for that, there’s onIter. A pause from a breakpoint is its own scenario altogether; for that, there’s onPause, whose firing event is spelled out in its name.

Contract “At the iteration boundary”

Where the throttle lives is now clear: inside the onIter handler. But the onIter handler runs inside the worker, while the user’s pause comes from outside — from the main thread, on a click. They need a protocol.

This protocol has four mechanisms: a pair of idle/busy messages, a stepRequested flag, a synthetic paused event, and an intervalMs field in resume. Each one closes a specific problem that the throttle’s location creates.

The `idle` and `busy` messages: pausing the watchdog

The watchdog timer mentioned earlier starts to get in the way once we’re in onIter.

A throttle in onIter, on every iteration, can easily exceed the timeout — especially if the user dials intervalMs to “slow” (the demo lets you set the interval to, say, two seconds). The result is a false alarm: the worker isn’t hung, it’s just waiting.

The solution: the worker itself tells the main thread when it’s “working” and when it’s “waiting”. Before await-ing the throttle in onIter, the worker sends an idle message. After the throttle resolves, it sends a busy. The main thread suspends the watchdog for the gap between idle and busy. The watchdog still catches real hangs (e.g., an unreachable halt state) but no longer confuses them with legitimate trace slowdown.

Without this wrapping, the watchdog has two bad options. Either pick a generous threshold — then real hangs go undetected (or detected too late). Or pick a tight threshold — and you raise the probability of a false alarm (the worker gets killed on a legitimate delay). The idle/busy messages resolve both at once.

Step is a flag inside the worker, not engine state

When the user clicks “Step”, the main thread sends the worker a resume message with a step: true flag — “advance the machine one iteration and pause again”. The implementation: the worker sets stepRequested = true. On the next onIter, the handler sees the flag, resets it to false, synthesizes a paused event, and waits again. The machine has run exactly one iteration.

The key point: “step” is a flag inside the worker, not part of the engine’s state. The engine doesn’t know what “step” means — it simply finds itself in a waiting state again on the next iteration. The coordination lives outside the engine. onIter remains a thin await hook — it doesn’t mutate the engine, it only pauses the engine’s execution. That’s what made onIter viable as a contract: there’s no “step-specific logic” in it, only a Promise the worker controls itself. If “step” had been part of the engine’s state, the onIter contract would have to extend to “and also flip this flag”, and the hook would stop being thin.

No throttle needed when Step is clicked

When the user clicks “Step”, a throttle is redundant — the user plays the role of the timer, clicking as many times and as fast as they need. The implementation reflects this: on Step, intervalMs is ignored, and the onIter handler doesn’t insert a wait. This is the cleanest expression of “observation ≠ coordination” inside the worker: when the user is in control, the engine follows.

Synthetic pause on click

The scenario: the machine is in RUNNING_AUTO — the engine is running with onIter awaiting intervalMs between iterations. The user clicks the “Pause” button in the UI. The click arrives on the main thread. The main thread sends the worker a pause message. At that moment, the worker is holding the engine in a throttle — the Promise hasn’t resolved yet. What do we do?

The solution is to synthesize the same kind of pause as one from a breakpoint. The UI already has a handler in place: on paused from the worker, it switches to “stopped”. If the “Pause” click went down a different path, a second branch with the same behavior would appear. That’s why the worker synthesizes paused — to the UI, a “Pause” click is indistinguishable from a breakpoint firing.

The worker cancels the throttle (resolves it forcibly, ahead of schedule), sets stepRequested = false, and, from inside onIter after returning from the wait, dispatches a paused event — synthetic, not one that arose from the engine’s normal flow. Under the hood, the two scenarios differ (one cancels the throttle, the other lets it finish naturally), but the contract from outside is one — a single “pause” scenario.

`intervalMs` is a parameter of `resume`, not `run()`

The throttle in onIter is sized by intervalMs. Where does the worker get that value from? Not from the parameters passed to run() at start. From the latest resume message: each one arrives carrying a current intervalMs from the main thread.

The reason is that the user must be able to change the delay between throttles during the run. The value in the UI is read at click time, not at run() start; the next resume carries the new value, and starting with the next iteration, the throttle adjusts. A small cost for the protocol, a big win for the UX.

Duality, explicit

The throttle lives in one point of an iteration. From the engine’s perspective, that point is the onIter handler: a hook called once at the end of each iteration, asynchronously. From the protocol’s perspective, the same point is the gap between idle and busy messages — a gap where the watchdog is suspended, a “Pause” click can softly cancel the throttle, and intervalMs is read from the latest resume.

One point, two APIs. Every downstream design choice depends on this one. Put it in the middle of an observation hook, and you break both sides at once: the docs on a widened onStep can’t be written without a “but”, the idle/busy wrapping has nothing to attach to (the same hook stands for both observation and waiting), and the synthetic paused event has to be dispatched from an unnatural place. Without a clean iteration boundary, both the hook and the protocol suffer.

Conclusion

Separating observation from coordination is the reason the engine’s hook contract distinguishes three jobs instead of merging them into one. Gluing them together is the temptation v6.2.0 succumbed to. And the only thing that let me realize the approach was wrong within a few hours was that the engine’s README couldn’t be written honestly, and the demo’s smoke test wouldn’t pass. Two almost-free design reviews (article (2)).

Code: turing-machine-js (engine, v6.2 → v6.4) and machines-demo (the demo).

Two majors, one README, one demo: two cheap design reviews

Ruslan Gilmullin — Tue, 19 May 2026 08:35:03 +0000

Writing the docs is what surfaced both mistakes. There’s a meta-lesson in there about how docs are the cheapest design review you can run, but that’s another post.

This is “that other post” — and the first thing it has to do is correct the teaser. The teaser oversells. Docs caught one of the two mistakes. The other was caught by the first real consumer of the API, which I was building in parallel. The two reviews worked in tandem: docs review the shape of an API, the consumer reviews the use of it. Together they catch what tests can’t see.

If you ship anything behind an interface — a library, a CLI, any entity behind a contract — these are the two reviews you don’t want to skip.

Recap

“Three majors, two mistakes” covers the engine and the v4 pause API — onStep, onDebugBreak, per-state debug flags — in detail. I’ll lean on it here without rehashing it. The v4 → v6 trajectory shipped three breaking majors: a hook rename, a halt-semantics hardening, and a dispatch-tick collapse. The first two surfaced in the demo. The third surfaced in the docs.

The demo case: v4 → v5

While shipping v4 I started building machines-demo — an interactive Turing-machine debugger and the engine's first non-test client.

The demo is a natural first consumer: it has a dual purpose. The product goal — public distribution and showing the engine in action. The technical goal — road-testing changes and validating concepts against a live API surface. Both goals make building the demo an integral part of the release cycle, not an optional add-on.

The demo used both hooks at once: onStep populated a per-iteration command buffer for the trace UI; onDebugBreak drove the pause/resume cycle.

The demo built. The tests passed. But it was uncomfortable to write, for two reasons.

First, onDebugBreak’s after-fire came with data from the previous yield — the same data the previous onStep had already shown. The demo processed the same thing twice, and the question “why two hooks for one event?” was being asked not by me but by the code itself, in a way. I filed turing-machine-js#109 as an RFC about the relationship between these hooks, listing four sketches; the resolution narrowed to naming. onDebugBreak framed the purpose of use as “debugging”, while the consumer’s verb was “pause”. Shameless rename, no alias. v5.

Second, the demo’s UI gained a “pause before halt” scenario — letting the user glimpse the machine’s final state before it shuts down. The natural implementation: a debug flag on haltState itself. The first test case set haltState.debug = { before: true, after: true } because the symmetry looked right. Only before fired. Worse: the after-fire on the iteration that led to halt never reached the consumer — the loop exited as soon as state.isHalt became true. turing-machine-js#108 split it in two: restore the lost after-fire (bug); throw on assignment to haltState.debug.after (API).

Both complaints came from the consumer side. The demo didn’t surface a code bug — it surfaced an API interaction format. The names didn’t fit the use. Being permissive in input didn’t match what the user was trying to do. The tests verified behavior against the engine’s own internal model — ok, green. The demo verified behavior against the consumer’s mental model — and produced two specific complaints (not ok).

The docs case: v5 → v6

v5 shipped. The README needed updating. The new dispatch-order section had to explain — in words — when each of onPause(before), onStep, and onPause(after) fired relative to the iteration they described.

The first honest paragraph went something like:

onPause(after, K) fires on iteration K+1’s yield, with the payload substituted from iteration K’s snapshot, before onPause(before, K+1) or onStep(K+1) fire.

I stared at that sentence for a while. There was no shorter version. The reader wasn’t supposed to need a sentence about substitution.

The code worked. The tests passed. The demo consumed the hooks correctly. The mistake wasn’t in any of those — it was in the shape of the dispatch, and that shape was only visible when you had to put it into words.

The fix collapsed the lifecycle: before(K) → step(K) → after(K) on the same yield. No substitution. No cross-iteration scheduling. No final drain for the halting iteration (in “Three majors, two mistakes” I called it “post-loop drain”; I’d probably shorten it to “final drain” now). The README paragraph now reads:

On iteration K’s yield, hooks fire in lifecycle order.

And that’s the kind of sentence the reader glides past without effort. turing-machine-js#119 shipped as v6.

A direct quote from the previous article:

The code worked, the tests passed, and the docs were correct. The shape was just wrong.

What I’d add: the docs were correct only on the condition that the reader accepted three explanatory sentences they shouldn’t have had to read. That’s not “correct docs” — that’s docs apologizing for the shape.

The docs review caught the shape, not the use. The demo worked. The tests passed. This time, only prose pressure uncovered the issues hiding in the implementation.

Three reviews, three layers

Here’s what each one checks:

Tests verify code against itself. Internal consistency. The engine yields what the engine should yield. Green tests are the baseline.
The first real consumer verifies code against a consumer’s mental model. Does the API format match what the user is trying to do? Reviewing real interaction with the API forced API changes: a rename and a halt-after restriction.
The docs as *prose* (not JSDoc — a connected README narrative) verify code against the author’s own explanation. Does the design have an honest one-paragraph description? Without one, we had to look hard at the substitution dance — and abandon it.

Each review catches what the layer below misses. Tests don’t catch shape; the consumer doesn’t catch interaction problems it can skillfully bypass; the docs don’t catch UX wrinkles they don’t have to mention.

The cost is asymmetric. Building a real consumer is the most expensive of the three reviews; writing the docs is the cheapest. Still, even the most expensive costs less than reworking the API after the problems surface for users — hence “cheap” in the title. The real consumer has to be built before the major cut — it’s the only review that makes the API comfortable to use. Docs then paper over what’s left.

Heuristics for the next major

Build the first real consumer before cutting the major. Not a test fixture — a consumer with its own mental model. The difficulties it encounters are the same difficulties your users will encounter later.
Write the dispatch-order paragraph before locking the dispatch order. If you can’t describe in one sentence what fires when, the dispatch is wrong. Decisions of this kind belong at the design stage, not documentation — when not a single line of code has been written yet.
Read the docs back as a stranger. If a paragraph reads as an apology for the shape, the docs are working — they’ve revealed a shape mistake. Fix the shape, not the paragraph.

Three majors. One README. One demo. The tests had nothing to say.

Code: turing-machine-js (engine) and machines-demo (the first non-test consumer where v4 → v5 surfaced).

Three majors, two mistakes: designing a pause API for a Turing-machine interpreter

Ruslan Gilmullin — Tue, 19 May 2026 08:34:35 +0000

I spent the last two weeks shipping four breaking major versions of @turing-machine-js/machine — v3, v4, v5, v6 — and the most interesting part wasn’t any single feature. It was watching the same API surface (a pause/breakpoint hook on the run loop) get redesigned twice in three versions, each time because the previous shape exposed something it shouldn’t have.

This post is the post-mortem. If you’re designing pause/step/breakpoint APIs for a generator-loop interpreter, scheduler, or DSL runtime, the mistakes I made are easy to make and worth seeing in someone else’s code first.

The setup

The engine runs a Turing machine. Internally it's a generator: each yield corresponds to one step (one transition firing on one tape symbol). The driver loop looks roughly like this:

async function run({ initialState, onStep }) {
  for (const m of runStepByStep({ initialState })) {
    await onStep?.(m);
    if (m.state.isHalt) return;
  }
}

MachineState (m) is a snapshot per iteration: the state about to execute, the current and next symbols, the moves the heads will make. A consumer (a logger, a UI, a test) can hang off onStep to observe.

What I wanted to add in v4 was a way to pause execution at chosen points — like a breakpoint in a debugger. Any State should be able to carry a debug config:

myState.debug = { before: [symA], after: [symA] };

...and the run loop should give the consumer a chance to inspect the machine and decide when to resume.

v4: ship it

The v4 shape was straightforward. I made run() async, added an onDebugBreak hook, and routed it like this:

await machine.run({
  initialState,
  onStep: (m) => { /* every step */ },
  onDebugBreak: async (m) => {
    if (m.debugBreak?.before) console.log('before:', m.state.name);
    if (m.debugBreak?.after)  console.log('after:',  m.state.name);
    // hold here until promise resolves
  },
});

The per-state debug field is mutable. state.debug = { before: true } sets a pre-step break; before: [symA] filters by what the head is reading. The hook is awaited, so any consumer can implement “freeze until the human clicks Resume” by simply not resolving the promise.

I also wanted breakpoints on halt:

haltState.debug = { before: true };  // pause before exit

That worked. Symbol-list filters on haltState were silent no-ops, because haltState has no head symbol to filter by. Fine, I thought — be permissive in input, the wildcard true is the one that matters.

Two things in this design were wrong. I didn’t notice either until I started writing docs and a UI on top.

Mistake 1: the hook describes the engine, not the consumer

onDebugBreak reads, on paper, like a perfectly reasonable name. The engine fires a “debug break”; you hook into it.

But what does the consumer do in that hook? They pause. They inspect. They wait for input. They resume. The hook isn’t really notifying you that a thing happened — it’s offering you a cooperation point.

The name onDebugBreak carries one specific framing: “debugging”. But the same hook is exactly what you want for a step-through visualization, a slow-motion playback control, an animation tween, a “press space to advance” UI. None of those are debugging. They’re all pausing.

This sounds like a small thing. It’s not, because once consumers see the name they design around it: their code path is called handleDebugBreak, their state machine has a debugging boolean, their UI button says “Stop debugging”. The name leaks into every consumer’s vocabulary.

I wrote an RFC (turing-machine-js#109) and renamed it in v5. Hard rename, no deprecation alias:

await machine.run({
    initialState,
-   onDebugBreak: (m) => { ... },
+   onPause: (m) => { ... },
  });

The payload field m.debugBreak stayed — it’s metadata describing why this yield fired ({ before: true } or { after: true }), and “break” works fine inside the payload. But the hook name is the consumer’s contract: onPause describes what they do, not what the engine does.

Rule for next time: when naming a hook, name the consumer’s verb, not the engine’s event. Hooks are cooperation points, not event listeners.

Restriction: `haltState.debug.after` is nonsense

The second v4 mistake hid under an instinct to be permissive in input. haltState.debug.after accepted writes silently. It just didn’t fire.

Why? Because the after semantics in this engine mean “fire on the iteration after the one where the filter matched”. That makes perfect sense for normal states — you transition out of state K, the next iter (K+1) runs, and at that yield the consumer is told “by the way, K’s after-filter fired last step”. But halt is terminal. There is no K+1 after halt. The after event has nothing to anchor on.

I’d silently swallowed haltState.debug.after = true in v4. Worse, I’d let { before: true, after: true } through — half the assignment was meaningful, half was a no-op, and nothing told the consumer.

In v5 I made both throw at write time (turing-machine-js#108 part 2):

- haltState.debug = { before: true, after: true }; // v5: throws — 'after' on halt has nothing to anchor on
+ haltState.debug = { before: true };

Rule for next time: if a configuration has no semantics, throw early. Silently no-op input looks user-friendly until a consumer spends an afternoon wondering why their UI doesn’t fire on halt. “Be permissive” is a false economy when permissiveness silences a real mistake.

While I was in there, I also fixed a related bug: the halting iter’s own after filter wasn’t firing either (turing-machine-js#108 part 1). The driver loop exited as soon as state.isHalt became true — and the after-event from the previous iter, which would normally fire on this final yield, got dropped on the floor. v5 added a post-loop drain to fire it.

I’ll come back to this.

And one v5 bonus: a master switch on run() for the whole pause system.

await machine.run({ initialState, debug: false, onPause: ... });

When false, all pause-fires are suppressed regardless of what state.debug says across the graph (turing-machine-js#106). You can A/B “debug mode” without rewriting the graph or clearing every state.debug field. The flag dispatches onPause; the underlying m.debugBreak payload field still populates on the generator’s yields (it’s a property of the iteration, not of how run() chose to surface it).

Mistake 2: the substitution dance

This is the one I’m proudest to have caught, because the code worked, the tests passed, and the docs were correct. The shape was just wrong.

In v4 and v5, after K (the after-fire for iteration K) actually fired on iteration K+1’s yield. The driver loop carried a pendingAfterFromPrev flag across yields, and on the next iter’s yield it dispatched the after hook first, then the before hook, then onStep. The hook for K’s after-fire had to see K’s state — not K+1’s. So I substituted the previous yield’s snapshot into the m.state field of K+1’s yield, just for the duration of the after dispatch.

This worked. But it had three knock-on effects:

The substitution leaked. Consumers wanted access to the un-substituted, “real” iteration state (the one the step hook saw) — see turing-machine-js#107. Some users were reading raw MachineState.debugBreak from runStepByStep directly and were surprised that m.state referred to the iter on which the after-fired-from, not the iter that produced it.
The halt case needed a special path. As mentioned: the halting iter’s own after fires after the loop exits. v5 added a post-loop drain to handle it. That drain is its own code path, with its own substitution, separate from the in-loop dispatch.
The generator’s return type widened. Because the post-loop drain needed to return a final yielded value out of the iterator, runStepByStep’s return type became Generator<MachineState, MachineState | null> — a yield type and a return type. The canonical for..of consumer doesn’t see the return value, but anyone reading the type signature now had to understand why there were two slots.

All of this came from one design choice: dispatching after K on iter K+1’s yield instead of on iter K’s own yield.

In v6 I collapsed it (turing-machine-js#119). The per-iter lifecycle is now plainly before → step → after. The after fire rides on the same yield as the iter that produced it. No substitution. No pendingAfterFromPrev. No post-loop drain. The generator return type narrows back to Generator<MachineState>.

// v6
await machine.run({
  initialState,
  onStep: (m) => { /* unchanged */ },
  onPause: (m) => {
    if (m.debugBreak?.before) console.log('before:', m.state.name);
    if (m.debugBreak?.after)  console.log('after:',  m.state.name);
  },
});

The dispatch order across hooks changed (any test asserting pause(after K-1) → pause(before K) → step(K) had to flip to pause(before K) → step(K) → pause(after K)), but the set of dispatched calls and per-iter semantics are unchanged. Consumers treating the hooks as independent observers see no change at all (turing-machine-js#107 — “expose un-substituted state” — disappeared as a problem: there’s no substitution to expose around).

Rule for next time: if your hook payload requires substituting state from a different iteration than the one that’s yielding, the dispatch sequence is wrong. Lifecycle phases (before, step, after) belong on the iter they describe. The substitution wasn’t a clever trick — it was a leak telling me the events were on the wrong tick.

What I’d carry to the next pause/breakpoint API

Name hooks for the consumer's verb, not the engine's event. onPause, not onDebugBreak. onProgress, not onChunkReceived. The name leaks into every consumer's mental model — pick the framing you want them to inherit.
Throw on impossible configurations early. “Permissive in input” is fine for shapes that might be meaningful; it's a trap for shapes that can't be. haltState.debug.after = true had no possible semantics. Silently swallowing it cost an afternoon to one user before I noticed.
Per-iter phases belong on the iter they describe. If you're tempted to dispatch after K on K+1's yield, ask what payload you have to substitute to make it look right. The substitution is the signal.
A master switch is cheap and worth it. A boolean on the entry point to flip the whole feature off (without rewriting graph-level flags) makes the feature safe to ship to production and toggle in tests. run({ debug: false }) was one of the smaller v5 adds and one of the most-used by downstream consumers.
Breaking changes are worth the major bump. Three majors in two weeks sounds expensive. It isn't, if the lockstep downstream is one repo (in my case @post-machine-js/machine, which bumped its peer dep ^4.0.0 → ^6.0.0 and renamed its own internal __onDebugBreak → __onPause in step). API ergonomics compound across every consumer for the life of the library — pay the migration cost while the API is young.

The v6 shape is the one I should have shipped in v4. I didn't have the vocabulary then — I was thinking “expose the engine's events” instead of “design the consumer's contract”. Writing the docs is what surfaced both mistakes. There's a meta-lesson in there about how docs are the cheapest design review you can run, but that's another post.

Code: turing-machine-js (engine) and post-machine-js (a Post machine built on top, kept in lockstep). The interactive demo at demo.machines.mellonis.ru consumes the v6 onPause hook for its Step / Run / Stop controls.