DEV Community: Ruslan Gilmullin

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.