Suppose a second consumer comes to the engine. Not the demo’s worker — say, an IDE extension, or an in-process educational debugger without a Web Worker. What from article (2)’s protocol does it carry over? It doesn’t need the watchdog timer — there’s no thread boundary. It doesn’t need a message queue — the handlers live in the same thread. But the “step flag”, the “pause coordination”, the “paused event with multiple causes” — all of that, it does need. And it, without having read article (2), will reinvent the whole thing.

This article is about why coordination keeps getting reinvented. Not because the worker is “special”, but because in v6 coordination had no home of its own in the library. v7 gave it one: a companion class, DebugSession, sitting next to TuringMachine in the same package.

What the worker reinvented

Re-read article (2)’s protocol through the new lens. Four mechanisms:

1. idle/busy around the async throttle in onIter — wrapping for the watchdog timer.
2. stepRequested flag inside the worker — the “step” modeled as a one-shot request.
3. Synthetic paused event on click-Pause — handling an external pause command.
4. intervalMs field on resume — reading the speed “at click time”, not “at run start”.

Sort them by ownership. The first and the fourth are about the worker: the watchdog timer lives on the main thread because there’s a boundary between threads; intervalMs arrives with every resume because the interval input and the engine sit on different threads. The second and third are about coordination: the step modeled as a one-shot event, the translation of an external pause command into a standard event. Web Workers have nothing to do with any of that — the same mechanisms would be needed in any debugger that switches the engine between paused and running.

Two out of four mechanisms — candidates for lifting out of the consumer and into the library. The worker would be left with two: the watchdog wrapping and the speed parameter on resume. That isn’t “reinvention of coordination” anymore — it’s an adapter between two interfaces: between the worker’s message protocol and the session’s API.

Where coordination can live

In v6, there were two places to put coordination:

• On the consumer side. Every new debugger builds it from scratch. With only one consumer, its choice of where to put coordination looks principled: there’s nothing to compare it against. Two consumers would highlight the duplication; three would confirm the pattern.
• In the engine’s hooks. This temptation is laid out in article (2): widening onStep to an async signature (v6.2.0) conflated observation with coordination. The appearance of a dedicated onIter hook (v6.4.0) solved the “where does the throttle live” question, but didn’t lift the underlying constraint: a hook is a notification point, not a state machine. A hook has no internal state of its own, no lifecycle, no control methods — it hands the listener the current moment and awaits the listener’s Promise. Coordination, however, is exactly a state machine: “pause on breakpoint → continue / step-in / step-over / step-out / stop”. For step-over and step-out, where the next pause lands is determined by stack depth.

The third option didn’t appear in v6 because the question wasn’t forced yet. With two consumers (or three, or N) the answer becomes obvious: coordination lives in a sibling class next to the engine. Not down the dependency graph (in the consumer), not inside the engine class itself (as yet another hook), but sideways — in a companion class on the same level of the library.

A side effect that’s also evidence: in v7, TuringMachine.run() is sync-and-void again — no callbacks. In v4 the same method became async to host the async pause hook (onDebugBreak, renamed to onPause in v5). Lifting coordination out erased that reason, and the signature reverted to its earlier shape. If async had been intrinsic to the engine, removing onPause wouldn’t have restored run() to its pre-v4 shape — but it did. So the async in run() was carried for that hook, not for the engine’s own execution logic.

What DebugSession owns

The class sits in packages/machine/src/classes/DebugSession.ts, alongside TuringMachine. Constructed directly — new DebugSession(machine, {initialState}). The engine knows nothing about the session; the session knows about the engine only through its public sync generator runStepByStep, plus one package-private accessor keyed by the symbol MACHINE_STATE_INTERNAL, which sibling modules can read and the public index.ts doesn’t re-export. Same package-private-via-Symbol pattern as STATE_INTERNAL (turing-machine-js#180) — it lets the session reach the per-iter halt-stack snapshot without exposing it through the public API.

The session listens for four events, each with its own dispatch contract:

• step — fire-and-forget. Sync, hot-loop observation; the listener’s Promise (if any) is not awaited. One-to-one with the v6 onStep contract.
• iter — awaited. Per-iter coordination: a throttle between iterations, step-boundary synthesis, anywhere the engine genuinely needs to wait on the listener. One-to-one with the v6 onIter contract from article (2).
• pause — listeners are called fire-and-forget (just like for step and halt: the Promise that an async listener would return isn’t awaited). But after dispatching them, the session itself blocks on its own internal Promise — and until that Promise resolves, the #drive loop doesn’t pull the next step out of the generator. The Promise is resolved by one of the session’s control methods: continue() / stepIn() / stepOver() / stepOut() / stop(). All of them, by design, are called from outside — a UI click, a message from the main thread (when the session lives in a worker), or a timer.
• halt — fire-and-forget. Terminal session event.

Session controls mirror DevTools conventions where that makes sense. pause() is an external pause request; it fires on the before-side of the next iter with cause: 'manual'. stepIn() — pause on the next iter. stepOver() — pause on the next iter where depth <= clickTimeDepth: frames the current iter pushes onto the stack are played through to return without stopping. stepOut() — pause when the halt-stack depth drops below the click-time depth (depth < clickTimeDepth): the current wrapper has finished, control has passed to its override. stepOut() from depth 0 throws an exception: “step out of nothing” is a programming error in the consumer’s code, not a silent no-op. setRunInterval(ms) sets a per-iter delay (in ms) between iterations. stop() is terminal — the session resolves. The session is single-use: start() is called once; to re-run, construct a fresh session.

Breakpoint detection also moved here. In v6 the runStepByStep generator itself decided which iteration should “fire” by state.debug. In v7 the generator yields a minimal MachineState, and the session reads the current tape symbol via MACHINE_STATE_INTERNAL, checks it against the before/after filters in state.debug with matchFilter, and dispatches pause itself with cause: 'breakpoint'. The engine’s generator has no “debug” logic left — it’s pure execution. The session, in turn, carries all three pause causes (breakpoint, step, manual) in one descriptor PauseInfo { side, cause } with the precedence order breakpoint > step > manual for when several causes coincide on one iter.

This is exactly the “coordination as a state machine” that didn’t fit into a hook: internal state (the pause-Promise that holds the engine, the currently active step-in/over/out mode, the halt-stack depth captured at click time), control methods, a lifecycle — all in one object with its own constructor and its own start() method.

What stays in the worker

After the coordination lift, the worker isn’t empty. What it’s now responsible for:

• The Web Worker boundary itself — the message protocol, the user-code sandbox, the lifecycle of build / run / step requests. The worker is the natural home for that layer.
• A per-iter delay wrapped with idle/busy messages for the WORKER_TIMEOUT_MS watchdog. The session has its own simple throttle — setRunInterval(ms). But it doesn’t fit the worker: that wait runs inside the session’s #drive loop, and there’s no way to bracket it with idle/busy from the outside — and without the bracketing, the main-thread watchdog trips on a legitimate delay as if the worker were hung. So the worker implements the wait in its own listener for the iter event (which the session awaits asynchronously): inside the listener, an idle / busy pair brackets await setTimeout(intervalMs) exactly where it needs to be.
• Holding and updating intervalMs. The “withPause is read at click time” semantics from article (2) didn’t go anywhere — the interval input in the UI is a consumer-level concern. The worker keeps the current value in its own local variable and updates it on every resume message from the main thread.
• Translating UI clicks to session methods: Pause click → activeSession.pause(), Step click → activeSession.stepIn(), Continue click → activeSession.continue(). The worker no longer synthesizes paused from onIter — all pauses (breakpoint, step, manual) come back through the single pause event on the session, with a cause discriminant.

The line is clean. What stayed is what the session can’t own without stepping onto the consumer’s territory. What left was never worker-specific to begin with — it was coordination, disguised as worker-specifics. A different consumer — an in-process debugger built into an IDE, a DAP server, an educational demo without a Worker — will compose DebugSession differently (no postMessage, no watchdog), but consume the same session API.

The lift generalizes

PostMachine.debugRun() returns a PostDebugSession, which wraps the engine’s DebugSession. Same four events, same step methods, same lifecycle. On top: wrapping MachineState in post-specific arrivalPath / candidatePaths, and filtering by the PostMachine breakpoint registry before forwarding pause events outward. The demo’s worker handles both sessions through a structural SessionLike type — both look the same from the outside.

This is companion-of-companion: the pattern generalizes one library level up. The engine library lifts coordination once into its own companion class; the next library on top of it lifts its own specifics into its own companion class wrapping the engine’s. Evidence that “companion class” isn’t a one-off trick under one library — it’s a reproducible shape.

What follows from this

In the lineage of articles about the engine’s API, three lessons appear in a row:

• From article (1): naming the lifecycle pins decisions about the shape of the API — name the states correctly, and the surface lands in the right shape on its own.
• From article (2): observation and coordination are different jobs, and each one needs its own hook contract with its own dispatch semantics.
• From this one: when N consumers reinvent the same coordination scaffolding on top of your hooks, your hook contract isn’t incomplete — it’s at the wrong granularity. A coordination state machine is a neighbor to hooks, not an extension of them.

The diagnostic for a library author: if you find yourself widening a hook’s signature so the consumer can do work the consumer already has to do (v6.2.0’s major from article (2)) — or if the same handler shape repeats from consumer to consumer without meaningful differences (the case that triggered this refactor) — then the hook is being asked to do something a hook fundamentally can’t.

For this engine, that landed as a clean boundary: a public sync runStepByStep, its coordination companion DebugSession, and any consumer — the demo’s worker, a DAP server, an in-process debug panel — writes an adapter between its own entry point and the session API, not a reinvented coordination layer.

Code: turing-machine-js (engine, v7 — DebugSession), post-machine-js (PostDebugSession), and machines-demo (the demo worker, rewritten around the session in PR #80).

And right away I wanted a regression test: run a machine through the round-trip and check that what comes out is the same machine. That word “same” is where it all started.

Byte-for-byte? No: node ids are runtime instance ids, and fromGraph assigns them fresh. The same structure? Sometimes yes, sometimes no — depending on how the composition is built. Behaves the same? That’s a different check entirely, one that never touches the graph.

It turned out “the same” isn’t one question but three, and each has its own API to answer it. These three answers I added to the library over years, one at a time, and for a long time never spelled out to myself that they’re three separate boundaries, not one stretchy “equals”. Object, graph, behaviour — three guises of one machine, and on a flat machine they all give the same answer. Composition is where the answers diverge. What follows: what the engine ships for this, where the boundaries run, and how v7 packed two guises of the three into graph form, leaving the third to a separate function, equivalentOn.

What does the engine actually ship?

Before pulling the three guises apart, an inventory.

There are three layers in the engine that the question “is it the same machine?” lands on:

Runtime objects. State is a node in the machine’s graph. It has a name, transitions (for each possible tape symbol — the next state, what to write, where to move), and identity: two different States are two different objects, no matter how similar their transition tables look.

The graph as serialization. State.toGraph(state, tapeBlock) walks the reachable states and returns a Graph — plain data: nodes with names and transitions, indexed by numeric ids. State.fromGraph(graph) takes that data back and returns {start, tapeBlock, states}. On top of the graph there’s toMermaid(graph) and fromMermaid(text), a mapping into Mermaid flowchart syntax and back. The parser is strict: it accepts only what the emitter produces.

Behavioural equivalence. equivalentOn(reference, candidate, cases) in utilities/equivalence.ts — runs both machines on a set of test inputs, compares outputs and per-step snapshots. A separate module, knows nothing about the graph.

Three layers, three “is it the same?” questions. The rest of this post is about how they diverge.

Flat machine: the boring case

On a flat machine — no composition — all three guises coincide.

Object-wise: one State equals another only if it’s the same instance (===). That’s the basic JavaScript semantics; the engine doesn’t add anything.

Graph-wise: take toGraph, run it through JSON and back, rebuild via fromGraph — you get a twin with the same names and transitions. The match isn’t byte-for-byte but up to node-id renaming: node ids are runtime State ids, reassigned on every fromGraph rebuild. There’s a regression test for this in the repo (turing-machine-js#139). It’s not “looks the same” — it’s the same structure.

Behaviour-wise: equivalentOn runs both machines on the test inputs and confirms “yes, the same”.

The boring case. All three guises coincide because there’s no place where they could diverge. Composition is that place.

Composition: where it gets interesting

Composition in this engine looks like this:

const wrapper = bareState.withOverriddenHaltState(overrideState);

wrapper is a new State. It delegates transition lookup to its bareState, but substitutes the halt-exit: instead of the machine halting, it transitions into overrideState.

Conceptually a wrapper is “run the bare as a subroutine, on exit jump to overrideState”. The composition’s name follows a rule: for a bare named A and an override named B, the wrapper gets the name A(B). The how and why of that exact name is its own article, “Seven arrows, 429 trees” (1).

Here is where the three guises start to diverge.

Object-wise: wrapper and bare are two different States. wrapper !== bareState. That’s the consequence of withOverriddenHaltState returning a new instance.

Graph-wise: the wrapper has no transitions of its own. They live on the bare. If you visualise the graph, the wrapper is a delegation node, not a transition node.

Behaviour-wise: wrapper and bare are not equivalent. They have different halt-exits. On any input the trace matches step for step up to the bare’s halt-exit — and diverges exactly at that moment.

A wrapper exists as a separate object precisely so it can hold that substitution. Next question: how does the graph encode it, so that fromGraph can rebuild it?

How composition lands in the graph

I wanted the graph to carry the composition itself — that kills two birds. First, fromGraph rebuilds the machine straight from the structure instead of guessing the composition from a runtime hint. Second, the graph stays readable: the composition shows up on the diagram itself rather than dissolving into a flat list of transitions. In v7 (turing-machine-js#180) a wrapper emits two nodes:

• Wrapper node — a call-site with no transitions, shape [[wrapper-name]], its bareStateId field pointing at the bare.
• Bare node — a regular node with transitions, shape [bareState-name], placed inside a Mermaid subgraph “callable subtree of NAME”.

In full, for scanToX(eraseHere):

That’s enough for fromGraph to rebuild the wrapper from the structure: here’s the call-site, here’s the bare it points to. The graph encodes the composition rather than hinting at it.

Under the hood (skippable). The halt-exit of each frame is a separate isHaltMarker node with id = -frameId; at runtime it collapses into the singleton haltState, but on the graph it lives separately, otherwise the whole machine “absorbs” into one halt node. When a single bare is reachable from several wrappers, frames are computed by union-find over bare-reachability (the subgraph is labelled “callable subtree of A” or “callable scope: A ∪ B”). The start of the machine is marked by a sentinel idle([idle]) with a dotted enter arrow — an anchor the parser reads to find the start state. Transition labels follow a small format [reads] → [writes]/[moves] — one cell per tape.

Is it the same machine after a round-trip?

For a simple composition — one wrapper, one bare, a tree that doesn’t overlap with others — the round-trip is reproducible up to id renaming. The graph keeps nodes, names, transitions; fromGraph reassembles the same machine. The composite name scanToX(eraseHere) does ride along in the graph — it’s the wrapper node’s label — but fromGraph doesn’t read it: it recomputes the composite from the bare and the override, through the single place where mutating a name is permitted, the Symbol accessor STATE_INTERNAL (turing-machine-js#180). So names never accumulate: on every rebuild the name is computed from the structure, not stacked on top of the previous one. That’s exactly what the regression test on simple wrappers checks.

Reproducibility breaks on a shared bare — when one and the same State serves as the bare of several wrappers. Not a contrivance: in library-binary-numbers the minusOne algorithm is built so that invertNumber ends up as the bare of two wrappers, an outer and an inner one (the full graph). One object, two call-sites.

This doesn’t break the structure: toGraph walks the reachable states exactly once, keyed by instance id, so a shared bare is one node, and the two wrappers just point at it with two arrows; fromGraph rebuilds exactly one shared instance for both wrappers. The shared bare itself survives the round-trip. What doesn’t is the reproducibility of the serialization: a second rebuild can give a graph that won’t line up with the original even if you ignore the ids.

The same shape in miniature, on scanToX — one bare under two wrappers:

Under the hood (skippable). Node ids are runtime instance ids; fromGraph assigns them fresh. “Reproducible” here means: serialize, rebuild, serialize again, and compare the two graphs, ignoring the id values themselves. For a simple wrapper a second toGraph gives the same layout up to renaming. For a shared bare, say one shared by two wrappers, the ids can come out in a different order after the rebuild, and nodes are emitted sorted by id — the layout shifts, and ignoring the ids no longer helps.

And here the graph stops being the answer to lean on. equivalentOn, though, gives allAgree: true on both machines: by behaviour — the same. The boundary is simple: reproducibility of the serialization only for simple wrappers, behavioural equivalence always.

Where equivalentOn lives

equivalentOn(reference, candidate, cases) lives in utilities/equivalence.ts. reference and candidate are Runnables ({ state, getTapeBlock }), cases is an array of test inputs; it runs both machines, compares outputs and per-step snapshots, and returns a report { results, allAgree }: the per-step results plus an overall yes/no in allAgree.

What matters is that it doesn’t live in utilities/stateGraph.ts, where toGraph/fromGraph are. These are different modules, different layers of the library. equivalentOn knows nothing about the graph; it doesn’t care whether a wrapper is emitted as a call-site or as a single node, what frames its transitions live in. It only looks at observable behaviour.

That’s its role. When the reproducibility of toGraph/fromGraph is shaky (a bare shared by two wrappers), equivalentOn answers the question the consumer actually has: “after the rebuild — is this the same machine by behaviour?”. The graph is a serialization tool; behaviour is the contract.

The trap is easy to fall into: checking sameness with === on State instances. After a rebuild that gives false — fromGraph always makes fresh instances — even though the behaviour is identical. A false regression out of nowhere. equivalentOn exists precisely so that doesn’t happen — but only if you know it’s there.

Tags: data rides with the graph, identity stays local

A small but symptomatic v7 addition — tags (turing-machine-js#186). State got an API: state.tag('hot', 'subroutine-entry'), state.tags, state.untag(...). Tags are string labels on an instance. They’re for tooling on top of the machine: toMermaid colours and groups nodes by them via classDef, and consumers like post-machine-js use them to mark subroutine entry points. They don’t affect the machine’s semantics.

What’s important about them for the three guises:

• Behaviourally — they don’t count. equivalentOn doesn’t look at tags. A machine with tags and a machine without them, on the same transitions, are behaviourally the same.
• Graph-wise — they survive round-trip. GraphNode.tags is serialised; toMermaid emits tags in the node label via <br> and as classDef for hash-based colour grouping in the rendering; fromMermaid reads from the label (<br> is the source of truth, classDef is decorative).
• Object-wise — they’re local to the instance. Tags live on a specific State, not on the bare. Two wrappers share one bare, but each has its own set of tags. Tag one, and both the other wrapper and the bare itself stay untagged.

A clean boundary: data describing a graph node rides with the graph; instance identity stays local to a specific construction. Tags land in the middle: behaviour doesn’t see them (equivalentOn is blind to them), but they outlast === identity — that resets on every rebuild, while tags ride with the graph and survive the round-trip.

What I came away with

I didn’t design the three guises all at once — they accumulated one at a time, and only in hindsight did it become clear that they’re different projections of a single entity, not one stretchy “equals”.

The object guise JavaScript gives for free: === and instanceof just work. The behavioural one I got almost for free — equivalentOn is just running two machines on tests. The graph guise I had to design: without it fromGraph couldn’t restore anything from a serialized machine, and it’s precisely for its sake that v7 packed composition into the graph data.

Two things dawned on me late. Bijective naming of compositions isn’t decoration but a precondition: while names are ambiguous, the graph loses one of the ways of checking for “same” before fromGraph even runs. The article (1) is about this same ambiguity. And behavioural equivalence has to live apart from the graph: equivalentOn knows nothing about toGraph, and that’s right — a consumer more often needs the behavioural answer than a byte-for-byte round-trip.

Tags, too, suggested a simple check: what survives the round-trip describes a graph node, what doesn’t describes a specific instance. When I add a field, I look at which guise it lands in — that’s what decides in what sense it makes two machines “the same.”

Code: turing-machine-js (engine with v7 graph utilities). The interactive demo at demo.machines.mellonis.ru draws machines via toMermaid and highlights the current transition.

What I really mean is: two distinct wrapper states in @turing-machine-js/machine, constructed differently, with different runtime behavior, and with byte-identical state.name. I’ve been developing the library as a hobby since 2019, and I’d missed this for seven years.

I caught it sideways, starting from what looked like a Mermaid cleanup ticket. It ended in a redesign of how state composition is encoded in the name. And along the way I learned that tucked inside that redesign is the number $C_7=429$.

Where it started

Composition in the engine is one primitive: bareState.withOverrodeHaltState(overrideState). It returns a copy of bareState whose would-be halt transitions fall through to overrideState. From here on I’ll call bareState the bare state and the returned copy a wrapper over it. Composition via wrapping is the only way to build a bigger machine out of smaller halt-on-completion subroutines.

The wrapper’s name, in the old API, was formed like this:

state.#name = `${this.name}>${override.name}`;

So A.withOverrodeHaltState(B) is named A>B. Simple, readable: “A, then B.”

That line shipped in 2019 and hadn’t been touched since. It’s the name logs use, the name error messages use, the name tests compare against, and the name any user-facing diagnostic surfaces.

The investigation began with the Mermaid output. turing-machine-js#138 asked for a cleaner emit. Before v7, toMermaid rendered a wrapper as a separate node whose transitions were duplicated from the bare — visually it looked like the wrapper had a life of its own. But the wrapper’s transitions are the bare’s — even #symbolToDataMap is the same reference, not a copy. What it does own is call-frame semantics: push the override onto the halt-stack on entry, pop on the bare’s halt. Behaviorally, the wrapper adds one thing on top of the bare: where halt goes.

Roughly, this is what it looked like:

A and A>B are two nodes with literally the same outgoing transition to A1, plus the wrapper gets a dashed onHalt arrow to B. The reader sees “two distinct machines,” when behaviorally it’s one machine with a single point of divergence — where halt goes.

The first fix attempt looked reasonable: render the wrapper as a single node that reuses the bare’s transitions, with the override-halt as a separate arrow:

One A>B node, transitions reused from the bare’s graph, override-halt as a separate dashed arrow from halt to B. Clean, compact, no visual noise. Almost worked.

Almost worked — then broke

Take minusOne from library-binary-numbers — it’s built by nested wrapping:

const minusOne = invertNumber
  .withOverrodeHaltState(
    plusOne
      .withOverrodeHaltState(
        invertNumber
          .withOverrodeHaltState(normalizeNumber),
      ),
  );

Composite name: invertNumber>plusOne>invertNumber>normalizeNumber — three > separators in real code, and already one base (invertNumber) appears twice. When a name gets longer, it’s tempting to read it as a walking instruction. Take A>B>B>A>A>B>B>A (seven separators): each letter is a bare state you land in after the previous one halts. The sequence of bases visited should equal the name.

Except that’s wishful reading. The name doesn’t formally determine the traversal. It resembles it. And only if the chain was constructed the one specific way I happened to picture when I wrote the naming rule in 2019.

The catch

Take a smaller example: A>B>A. How many ways to build it?

At least two:

// Construction 1
const c1 = A.withOverrodeHaltState(B.withOverrodeHaltState(A));

// Construction 2
const c2 = A.withOverrodeHaltState(B).withOverrodeHaltState(A);

Both flatten to the string A>B>A under ${this.name}>${override.name}. But the wrapper topologies differ — each construction builds its own binary tree (internal • nodes are withOverrodeHaltState applications, leaves are plain State instances):

And the runtime behavior differs too:

• Construction 1 (A.wohs(B.wohs(A))): A’s halt goes to a wrapper “B with halt redirected to A”. Runtime walk: A → B → A.
• Construction 2 (A.wohs(B).wohs(A)): the wrapper “A with halt redirected to B” is wrapped once more — halt now goes to A. Runtime walk: A → A. The inner B override is dead: only the outermost .wohs()’s override makes it onto the halt stack.

Same name. Just because the flat > separator doesn’t remember where in the construction tree each arrow sat. And there was a tree there.

The tree we forgot

withOverrodeHaltState is a binary operation: a left argument (this) and a right argument (override). Each application is a new node in the tree. The node has two children: the bare and the override. If a child is itself a wrapper, the tree continues there with another node; otherwise it’s a plain State — a leaf. After N applications: N wrapper-nodes and N+1 leaves — standard binary-tree property. For minusOne above: 3 applications (3 wrapper-nodes), 4 leaves (invertNumber, plusOne, invertNumber, normalizeNumber). Here’s the tree explicitly:

The name, meanwhile, is flat: a concatenation joined by >. A binary tree gets serialized into a string, and the string can be reversed back into the tree only if the naming convention is bijective. The flat > notation isn’t.

How many trees can correspond to one name with N separators? The standard answer from combinatorics: the Catalan number $C_N$.

$C_n=\frac{1}{n+1}\left(\genfrac{}{}{0px}{}{2n}{n}\right)$ — the sequence that counts: the number of binary trees with n+1 leaves, the number of balanced-paren strings of length 2n, the number of Dyck paths of length 2n, the number of triangulations of an (n+2)-gon, and a dozen other isomorphic combinatorial objects. The kind of number that turns up everywhere.

The most direct angle for our case: parenthesization. For an arbitrary binary operator •, the number of ways to parenthesize a • b • c • ... (with n+1 operands) is $C_n$. withOverrodeHaltState is exactly such an operator — each parenthesization corresponds to a distinct composition tree.

The first eight values: $C_0=1$, $C_1=1$, $C_2=2$, $C_3=5$, $C_4=14$, $C_5=42$, $C_6=132$, ${𝑪}_7=429$.

For our A>B>B>A>A>B>B>A, that means 429 different construction trees, each with its own parent-child wiring, all collapsing to the same string. And 429 isn’t a theoretical upper bound — it’s the exact number of distinct structures hiding behind that one name.

A smaller example — A>B>C>D (three separators). By the formula, $C_3=5$; here are the five construction trees, written as code:

// 1. fully left-associative
((A.wohs(B)).wohs(C)).wohs(D)

// 2.
(A.wohs(B.wohs(C))).wohs(D)

// 3.
(A.wohs(B)).wohs(C.wohs(D))

// 4.
A.wohs((B.wohs(C)).wohs(D))

// 5. fully right-associative
A.wohs(B.wohs(C.wohs(D)))

All five collapse to the same flat string A>B>C>D. Under the paren notation v7 will ship, each gets a distinct name — more on that below.

The fix is parens

If a flat separator throws the tree away, parens keep it. v7 (turing-machine-js#148) changes the naming rule to:

state.#name = `${this.name}(${override.name})`;

A.withOverrodeHaltState(B) is now named A(B). Back to our two A>B>A constructions:

// Construction 1: A(B(A))
const c1 = A.withOverrodeHaltState(B.withOverrodeHaltState(A));

// Construction 2: A(B)(A) — in pure paren notation
const c2 = A.withOverrodeHaltState(B).withOverrodeHaltState(A);

Same characters, different brackets, different trees. Names distinguish them. Bijection!

And this isn’t an invented convention. Balanced-paren strings of length 2n are the canonical encoding of binary trees with n+1 leaves in combinatorics — the same bijection underlying one of the foundational counting results for Catalan numbers. A better convention wasn’t designed — what gets recovered is the structure the > notation was always discarding.

The cost: state names from users can no longer contain ( or ) — the State constructor throws. Parens are reserved for composition. In exchange, > is no longer reserved and is fine in user-provided names again.

The other half of the story

The clean paren bijection above is about naming. v7 also cleans up the runtime alongside. turing-machine-js#176 adds chain-collapse: inside withOverrodeHaltState, we now do bare = this.#bareState ?? this. So A.wohs(B).wohs(A) is recognized as “wrapping an already-wrapped A” — the inner override (B) is dead at runtime anyway (only the outermost wrapper’s override gets pushed onto the halt-stack), and instead of A(B)(A) you get A(A).

So in actual v7, Construction 2 doesn’t give you A(B)(A) — at construction time it collapses to A(A). Paren naming on its own is bijective (one tree, one name); chain-collapse adds a step on top, removing trees that are indistinguishable at runtime. The composite name in v7 describes how the machine behaves, not how it was built.

And while we were touching the operator: the method gets renamed. withOverrodeHaltState → withOverriddenHaltState (turing-machine-js#149). Past-tense overrode never fit the idiom — it should have been the past participle overridden. A seven-year grammar typo on a public API. Hard cutover, no alias.

Other places this shows up

Non-injective serialization is a general pattern. If your codebase has a “name” formed by flat-separator concatenation of something tree-shaped, the odds of a C_n bug aren’t zero. A few examples:

• File-extension chains — .tar.gz, .spec.ts, .d.ts. Works by convention because the extensions are well-known. Put a dot in the filename and the ambiguity is immediate: is my.app.tar.gz the basename my.app with extension .tar.gz, or the basename my.app.tar with extension .gz? Different tools answer differently.
• DB column aliases with _ separators: user_address_country. If user_address is already a table name (underscore is part of the identifier), then user_address_country is ambiguous: is it user.address_country or user_address.country? Fix via qualified namespacing or explicit aliases.
• Module paths in Java/Python — com.example.foo.Bar. Could be class Bar in package com.example.foo or nested class foo.Bar in package com.example. Resolved by convention (uppercase = class), not by the naming itself.

Code-review heuristic: if your “identifier” is a flat-separator concatenation of something tree-shaped, look for the C_n bug. It’s almost always latent: in production the names happen not to collide on the actual data, but architecturally the hole is always there.

In my library the C_n bug hid for seven years because no one was trying to catch the engine on a name collision. To find it, you’d have to know to construct two structurally distinct trees and check whether their names differ. Nobody writes that test until they hear the collision is possible.

What v7 ships

Three tickets that were planned as three separate changes but, on closer look, are the same thought:

• Paren-based naming (turing-machine-js#148). The bijection between composition trees and their names.

• Cleaner Mermaid emit (turing-machine-js#138, turing-machine-js#174). Wrappers emit as separate [[composite-name]] nodes; the bare’s reachable subtree becomes a subgraph callable subtree of NAME block. The structural clarity of the name shows up as visual clarity in the diagram:

  Wrapper — call site; bare’s body — callable subtree; halt — return. Composition in the engine literally became a function call.

• withOverrodeHaltState → withOverriddenHaltState (turing-machine-js#149). Grammar on a public API.

All three are one idea: composition is tree-shaped, and its representations should keep the tree, not smear it.

Closing

A visualization cleanup turned into a naming overhaul. That’s the same pattern I described in “Two majors, one README, one demo”: a design review tests can’t run catches what tests can’t see. There it was docs and the first consumer. Here it’s visualization. The genre is the same: put yourself in front of the task of showing the structure, and if the structure is bent, it starts protruding. Tests don’t do that — tests check behavior, and structural bentness is usually visible only in the representation.

Seven arrows, 429 trees. A name that looked like a traversal trace turned out to be one of 429 possible ones. v7 gives each its own name — and lets the visualization show how that tree actually grew. That the wrapper IS a call-frame and deserves its own type — that’s another story (turing-machine-js#213).

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:

1. 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.
2. 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).

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

1. 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.
2. 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.
3. 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).

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:

1. 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.

2. 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.

3. 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

1. 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.

2. 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.

3. 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.

4. 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.

5. 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.