@turing-machine-js/machine 5.0.0 → 6.0.1

package/CHANGELOG.md

@@ -4,6 +4,39 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.0.0] - 2026-05-09
+
+### Changed (BREAKING)
+
+- **`onPause` dispatch order rewritten** ([#119](https://github.com/mellonis/turing-machine-js/issues/119)). `onPause(after, K)` now fires on iter K's *own* yield, alongside `onPause(before, K)` and `onStep(K)` — instead of v5's behavior of firing on iter K+1's yield with a `prevYield` substitution. The set of dispatched calls per run and per-iter semantics are unchanged; only the cross-hook *sequence* differs. Per-iter lifecycle inside `run()` is now `before → step → after`. Consumers using both `onStep` and `onPause` and asserting cross-hook ordering must update; consumers treating the hooks as independent observers see no change.
+
+  Subordinate consequences:
+  - `onPause(after)` carries the iteration's own `MachineState` directly — no `prevYield` substitution dance.
+  - `runStepByStep` no longer tracks `pendingAfterFromPrev` across yields; `debugBreak.after` on a yield refers to *that* iter's after-arm.
+  - The v5 post-loop after-fire drain (#108 part 1) collapses — the halting iter's after rides along on its own yield like any other iter.
+  - The generator's return type narrows back from `Generator<MachineState, MachineState | null>` to `Generator<MachineState>`; `for..of` consumers (the canonical pattern) are unaffected.
+
+### Closes
+
+- [#107](https://github.com/mellonis/turing-machine-js/issues/107) — "expose un-substituted `machineState` for after-break consumers" disappears as a problem: there is no substitution to expose around.
+
+### Migration
+
+No call-site change to `run()`'s API:
+
+```ts
+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);
+  },
+});
+```
+
+Tests asserting the v5 sequence (`pause(after K-1) → pause(before K) → step(K)`) need updating to the v6 sequence (`pause(before K) → step(K) → pause(after K)`).
+
 ## [5.0.0] - 2026-05-09
 
 ### Changed (BREAKING)

package/README.md

@@ -46,12 +46,42 @@ await machine.run({
     [ifOtherSymbol]: {
       command: [{ movement: movements.right }],
     },
-  }),
+  }, 'replaceB'),
 });
 
 console.log(tape.symbols.join('').trim()); // a*c*a
 ```
 
+The state graph for the example above:
+
+```mermaid
+flowchart LR
+    S(("**replaceB**"))
+    H((("**halt**")))
+    S -- "b → *, R" --> S
+    S -- "_ → keep, L" --> H
+    S -- "any other → keep, R" --> S
+```
+
+*Reading the labels: `read → write, move`. `_` is the blank symbol.*
+
+<details>
+<summary>📊 Same diagram, generated by <code>toMermaid()</code> (the engine's actual output)</summary>
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","a","b","c","*"]]
+  s0(((halt)))
+  s1(("replaceB"))
+  s1 -- "b → */R" --> s1
+  s1 -- "- → ·/L" --> s0
+  s1 -- "* → ·/R" --> s1
+```
+
+Engine notation: `read → write/move`; `·` = keep, `⌫` = erase, `*` = `ifOtherSymbol` catch-all, `-` = the blank symbol. `(((double-paren)))` = halt; `(("round"))` = the initial state passed to `toGraph`; `["square"]` = a state reachable from the initial state.
+
+</details>
+
 A `State` is keyed by JS `Symbol`s returned from `tapeBlock.symbol(pattern)` — the pattern lists the expected symbol under each tape's head. `ifOtherSymbol` is the fallback key when nothing else matches; transitioning into `haltState` stops the run.
 
 For multi-tape machines, pass one element per tape: `tapeBlock.symbol(['0', 'a'])` matches only when tape 1 is at `'0'` and tape 2 is at `'a'`.
@@ -143,6 +173,16 @@ tape.right();       // move head right; auto-extends with blanks at the edge
 tape.symbol = 'X';  // write the cell under head
 ```
 
+For visualization-friendly UIs, `Tape` exposes a fixed-width viewport centered on the head:
+
+```javascript
+const tape = new Tape({ alphabet, symbols: ['a', 'b', 'c'], viewportWidth: 7 });
+tape.viewport;       // 7-cell snapshot centered on the head, padded with blanks
+tape.viewportWidth;  // 7 (the constructor bumps even values to the next odd)
+```
+
+`viewportWidth` defaults to `1` and must be ≥ 1; `tape.viewport` always has exactly `viewportWidth` cells regardless of how many symbols the tape actually holds. Useful for rendering a sliding window in a UI; ignore if you only need `tape.symbols` / `tape.position`.
+
 ### TapeBlock
 
 A bundle of one or more `Tape`s that the machine reads/writes together in lock-step. Construct via either factory:
@@ -186,8 +226,7 @@ A node in the transition graph. Construct with a definition object whose keys ar
 ```javascript
 const s = new State({
   [tapeBlock.symbol(['1'])]: { command: { symbol: '0', movement: movements.right } },
-  [tapeBlock.symbol(['$'])]: { nextState: haltState },
-  [ifOtherSymbol]:           { command: { movement: movements.right } },
+  [tapeBlock.symbol(['$'])]: { command: { movement: movements.left }, nextState: haltState },
 }, 'name');
 ```
 
@@ -198,6 +237,32 @@ Notable members and statics:
 - **`State.toGraph(state, tapeBlock)`** — walks the reachable graph from `state` and returns a serializable `Graph` (states, transitions, alphabets).
 - **`State.fromGraph(graph)`** — inverse of `toGraph`: rebuilds `State` instances + a fresh `TapeBlock` from a `Graph`. Round-trips together with `toMermaid` / `fromMermaid`.
 
+For visualization, pair `State.toGraph` with `toMermaid` to render the graph in any Mermaid-aware viewer (GitHub, VS Code, mermaid.live):
+
+```javascript
+import { State, toMermaid } from '@turing-machine-js/machine';
+
+const graph = State.toGraph(s, tapeBlock);
+console.log(toMermaid(graph));
+```
+
+The string `toMermaid` produces is a real Mermaid flowchart that renders in-place anywhere Mermaid is supported:
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","0","1","$"]]
+  s0(((halt)))
+  s1(("name"))
+  s1 -- "1 → 0/R" --> s1
+  s1 -- "$ → ·/L" --> s0
+```
+
+*Edge labels are `read → write/move`. `·` is the keep-current-symbol marker (no write); `L` / `R` / `S` are head moves.*
+
+> 💡 **Mermaid renders at most one edge per source/target pair.** If a state has two distinct transitions back to itself (or two parallel transitions to the same target), only one shows in the diagram. The string output is correct — this is a viewer-side limitation. For graphs with multiple parallel edges, paste the `toMermaid` output into [mermaid.live](https://mermaid.live) and switch to the `stateDiagram-v2` renderer, or post-process the output to your preferred format.
+
+`fromMermaid` parses the same format back into a `Graph`. The round-trip is **behaviorally** lossless — the rebuilt graph runs to the same outputs on the same inputs (tested in `test/round-trip.spec.ts` for the binary-numbers libraries). It is *not* bytewise lossless: state IDs auto-reassign on each rebuild, and for `withOverrodeHaltState` wrappers the composite name gains a `>${override.name}` suffix on each pass (e.g., `scanToX>eraseHere` becomes `scanToX>eraseHere>eraseHere` on a second round-trip — tracked in [#138](https://github.com/mellonis/turing-machine-js/issues/138)).
+
 ### Reference
 
 A forward-declaration handle, used when a `State` needs to point at another `State` that doesn't exist yet (cyclic graphs). Construct unbound, pass as `nextState`, call `.bind(actualState)` once that state has been built.
@@ -209,7 +274,33 @@ const b = new State({ [symbol(['y'])]: { nextState: a  } }, 'b');
 ref.bind(b);   // a's transition now resolves to b at run time
 ```
 
-`reference.ref` returns the bound state and throws if the reference is still unbound when the machine runs.
+The resulting cycle:
+
+```mermaid
+flowchart LR
+    a(("**a**"))
+    b(("**b**"))
+    a -- "x" --> b
+    b -- "y" --> a
+```
+
+<details>
+<summary>📊 Same diagram, generated by <code>toMermaid()</code></summary>
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","x","y"]]
+  s1(("a"))
+  s2["b"]
+  s1 -- "x → ·/S" --> s2
+  s2 -- "y → ·/S" --> s1
+```
+
+`a` is round (the initial state passed to `toGraph`); `b` is square (reachable from `a`).
+
+</details>
+
+`reference.ref` returns the bound state and throws if the reference is still unbound when the machine runs. `bind()` is sticky — the first call wins; subsequent calls are silent no-ops that return the existing binding.
 
 ### TuringMachine
 
@@ -227,8 +318,118 @@ for (const step of machine.runStepByStep({ initialState })) {
 }
 ```
 
+Each yielded `step` (`MachineState`) has these fields:
+
+| Field | Type | Meaning |
+|---|---|---|
+| `step` | `number` | 1-indexed iteration number |
+| `state` | `State` | the state about to execute |
+| `currentSymbols` | `string[]` | per-tape head symbols, before the command applies |
+| `nextSymbols` | `string[]` | per-tape symbols that will be written |
+| `movements` | `symbol[]` | per-tape head moves (`movements.left/right/stay`) |
+| `nextState` | `State` | the state that will execute next |
+| `debugBreak?` | `{ before?: true, after?: true }` | only set when `state.debug` matched on this iter — see *Debugging breakpoints* below |
+
 `stepsLimit` (default `1e5`) guards against runaway loops — exceeding it throws.
 
+## Subroutine composition with `withOverrodeHaltState`
+
+`state.withOverrodeHaltState(other)` returns a copy of `state` whose would-be halt transitions fall through to `other` at run time. The original is left untouched. This is the engine's only composition primitive — bigger machines are built by stacking smaller halt-on-completion subroutines.
+
+```javascript
+import { Alphabet, State, TapeBlock, TuringMachine, Tape, haltState, ifOtherSymbol, movements, symbolCommands } from '@turing-machine-js/machine';
+
+const alphabet = new Alphabet([' ', 'a', 'b', 'X']);
+const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
+const { symbol } = tapeBlock;
+
+// Reusable subroutine 1: walk right until 'X', halt on it.
+const scanToX = new State({
+  [symbol(['X'])]: { nextState: haltState },
+  [ifOtherSymbol]: { command: { movement: movements.right } },
+}, 'scanToX');
+
+// Reusable subroutine 2: erase the head cell, halt.
+const eraseHere = new State({
+  [ifOtherSymbol]: { command: { symbol: symbolCommands.erase }, nextState: haltState },
+}, 'eraseHere');
+
+// Compose: scan to X, then ERASE it. scanToX is unmodified.
+const scanThenErase = scanToX.withOverrodeHaltState(eraseHere);
+
+const tape = new Tape({ alphabet, symbols: ['a', 'b', 'X', 'b', 'a'] });
+tapeBlock.replaceTape(tape);
+await new TuringMachine({ tapeBlock }).run({ initialState: scanThenErase });
+
+console.log(tape.symbols.join('')); // "ab ba" — the X at index 2 is gone, head landed there.
+```
+
+What changes between *running `scanToX` standalone* and *running the composed wrapper*:
+
+```mermaid
+flowchart LR
+    subgraph standalone["scanToX (standalone) — halts at X"]
+        direction LR
+        a1(("scanToX"))
+        h1(((halt)))
+        a1 -- "X → keep, S" --> h1
+        a1 -- "any other → keep, R" --> a1
+    end
+    subgraph composed["scanToX.withOverrodeHaltState(eraseHere) — halt is intercepted"]
+        direction LR
+        a2(("scanToX"))
+        b2(("eraseHere"))
+        h2(((halt)))
+        a2 -. "X → keep, S<br/>intercepted" .-> b2
+        a2 -- "any other → keep, R" --> a2
+        b2 -- "any → erase, S" --> h2
+    end
+```
+
+<details>
+<summary>📊 Both diagrams, generated by <code>toMermaid()</code></summary>
+
+`toMermaid(toGraph(scanToX, tapeBlock))` — the standalone subroutine:
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","a","b","X"]]
+  s0(((halt)))
+  s1(("scanToX"))
+  s1 -- "X → ·/S" --> s0
+  s1 -- "* → ·/R" --> s1
+```
+
+`toMermaid(toGraph(scanThenErase, tapeBlock))` — the wrapped composition:
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","a","b","X"]]
+  s0(((halt)))
+  s1["scanToX"]
+  s2["eraseHere"]
+  s3(("scanToX>eraseHere"))
+  s1 -- "X → ·/S" --> s0
+  s1 -- "* → ·/R" --> s1
+  s2 -- "* → ⌫/S" --> s0
+  s3 -- "X → ·/S" --> s0
+  s3 -- "* → ·/R" --> s1
+  s3 -. onHalt .-> s2
+```
+
+**Reading guide** — the wrapped diagram is denser than the simplified hand-drawn version above. To parse it:
+
+1. **Three non-halt nodes:** the wrapper `scanToX>eraseHere` (round, the initial state); `scanToX` (square, the original subroutine — unmodified); `eraseHere` (square, the override target). The wrapper appears as a *separate* state from `scanToX`-the-original because `withOverrodeHaltState` returns a new `State` instance — even though it shares the transition map.
+2. **Solid edges from the wrapper duplicate `scanToX`'s edges.** That's because the wrapper inherits the same `symbolToDataMap`. Importantly, the wrapper's `* → ·/R` edge points at *`scanToX`-the-original*, not at the wrapper itself — so after the first iteration, control transfers to `scanToX` and stays there.
+3. **The dotted `onHalt` edge is attached to the wrapper** but it doesn't fire on a single edge at runtime. Instead, the runtime pushes `eraseHere` onto an internal stack at startup, and *any* halt-bound transition reachable during the run (whether on the wrapper itself or on `scanToX`) gets redirected to `eraseHere` via stack-pop. The dotted edge is the engine's static fingerprint of "this graph was wrapped by `withOverrodeHaltState`."
+4. **What actually fires at runtime, on tape `['a','b','X','b','a']`:** the wrapper runs once, transferring to `scanToX`; `scanToX` self-loops on `* → ·/R` until it sees `X`; the `X → ·/S` edge tries to go to halt; the runtime pops `eraseHere` off the stack and substitutes it; `eraseHere` erases the cell and halts. The wrapper's own `X → ·/S → halt` edge in the diagram is *never traversed* because control left the wrapper after iteration 1.
+
+> 💡 **The engine's emit could be more user-friendly here.** Tracked in [#138](https://github.com/mellonis/turing-machine-js/issues/138) — the wrapper's duplicated edges and the misleading single-edge `onHalt` placement are candidates for a cleaner `toMermaid` output.
+
+</details>
+
+Wrappers nest: `inner.withOverrodeHaltState(middle).withOverrodeHaltState(outer)` chains halt-redirects through `middle → outer → halt`. `library-binary-numbers/src/index.ts`'s `minusOne` (the `~(~x + 1)` composition) uses a 4-deep nest of wrappers.
+
 ## Debugging breakpoints (v4+)
 
 Any `State` can carry a runtime-mutable `debug` config that pauses execution at chosen points.
@@ -254,7 +455,9 @@ haltState.debug = { before: true };
 myState.debug = null;
 ```
 
-The `debug` field is mutable — toggle breakpoints at runtime without rebuilding the graph. The internal cell is shared with `state.withOverrodeHaltState(...)` wrappers, so an assignment on the original is visible from every wrapper.
+> ⚠️ **`haltState.debug.after` throws.** Halt is terminal — there is no iteration-after-halt for an after-fire to anchor on. Assigning a truthy `.after` to `haltState.debug` (including `{ before: true, after: true }`) throws at write time. Symbol-list filters on `haltState.debug.before` are silent no-ops, since halt has no head symbol; only the wildcard `true` activates.
+
+The `debug` field is mutable — toggle breakpoints at runtime without rebuilding the graph. The internal cell is shared with `state.withOverrodeHaltState(...)` wrappers, so an assignment on the original is visible from every wrapper. Plain-object input (`state.debug = { before: true }`) is wrapped in a `DebugConfig` instance automatically; the wrapper's per-property setters validate and freeze the stored array, so `state.debug.before.push(...)` throws `TypeError`.
 
 `run()` is async and accepts an `onPause` hook:
 
@@ -270,7 +473,7 @@ await machine.run({
 });
 ```
 
-For `after` calls, `m` is the previous yield's snapshot — `m.state` is the state whose `after` filter fired. For `before` calls, `m` is the current iteration. `onStep` always sees the original (un-substituted) yield.
+Both `before` and `after` for the same iteration fire on the iteration's own yield, in the order **before → step → after**. `m.state` is always the iteration's own state; the `m.debugBreak` flag (`{before: true}` or `{after: true}`) tells the consumer which timing fired.
 
 If `onPause` is not provided, breaks fire-and-resume invisibly — the trajectory is identical to running without `debug` set.
 

package/dist/classes/TuringMachine.d.ts

@@ -12,13 +12,15 @@ export type MachineState = {
     movements: symbol[];
     nextState: State;
     /**
-     * Set only when this iteration boundary is a debug break.
+     * Set only when this iteration is a debug break point.
      * Field is OMITTED entirely when no break fires (no `debugBreak: undefined`).
      * At least one of `before` / `after` is `true` when the field is present.
      *
-     * For consumers of the `runStepByStep` generator the `state` field reflects
-     * the current iteration regardless of timing; `run()` substitutes the prior
-     * yield's snapshot for `after` calls so consumers see the source state.
+     * Both flags refer to THIS iter — `before` means the iter's `state.debug.before`
+     * matched, `after` means the iter's `state.debug.after` matched. `run()`
+     * dispatches the two timings as separate `onPause` calls (before-call has
+     * `debugBreak: {before: true}` only; after-call has `debugBreak: {after: true}`
+     * only) so consumers can distinguish without ambiguity.
      */
     debugBreak?: {
         before?: true;
@@ -31,7 +33,7 @@ export default class TuringMachine {
         tapeBlock?: TapeBlock;
     });
     get tapeBlock(): TapeBlock;
-    run({ initialState, stepsLimit, onStep, onPause, }: RunParameter & {
+    run({ initialState, stepsLimit, onStep, onPause, debug, }: RunParameter & {
         /**
          * Sync, ~free hook fired on every iteration. Use for logging/tracing —
          * the hot loop runs this without a microtask boundary, so it must not
@@ -39,16 +41,31 @@ export default class TuringMachine {
          */
         onStep?: (machineState: MachineState) => void;
         /**
-         * Async hook fired only when `state.debug[when]` matches at the current
+         * Async hook fired when `state.debug[when]` matches at the current
          * iteration. The promise is awaited inline, so the consumer can suspend
          * execution by deferring its resolution. Use for pause-capable inspection
          * (debugger UIs, conditional breakpoints in tests).
          *
-         * Renamed from `onDebugBreak` in v5.0.0. The `m.debugBreak` payload field
-         * keeps its name (it describes the engine's reason for pausing).
+         * Renamed from `onDebugBreak` in v5.0.0. In v6.0.0 the dispatch order
+         * was changed so that `before` and `after` for the SAME iter fire on the
+         * same yield (per-iter lifecycle: before → step → after); previously the
+         * `after` of iter K fired on iter K+1's tick with a substituted source
+         * view. The `m.debugBreak` payload field keeps its name (it describes the
+         * engine's reason for pausing).
          */
         onPause?: (machineState: MachineState) => void | Promise<void>;
+        /**
+         * Master switch for `onPause` dispatch. When `false`, suppresses all
+         * pause-fires (before and after) regardless of `state.debug` assignments.
+         * `onStep` is unaffected. Defaults to `true`.
+         *
+         * The `m.debugBreak` field is still populated on yields by the underlying
+         * generator (it's a property of the iteration, not of the consumer); only
+         * `run()`'s hook dispatch is gated. Direct `runStepByStep` consumers see
+         * the metadata regardless.
+         */
+        debug?: boolean;
     }): Promise<void>;
-    runStepByStep({ initialState, stepsLimit }: RunParameter): Generator<MachineState, MachineState | null>;
+    runStepByStep({ initialState, stepsLimit }: RunParameter): Generator<MachineState>;
 }
 export {};

package/dist/index.cjs

@@ -790,10 +790,21 @@ class State {
     }
     /** @internal — invoked by DebugConfig setters via module-private symbol. */
     [(_State_id = new WeakMap(), _State_name = new WeakMap(), _State_overrodeHaltState = new WeakMap(), _State_symbolToDataMap = new WeakMap(), _State_debugRef = new WeakMap(), validateDebugFilter)](fieldName, filter) {
-        if (filter === undefined || filter === true)
+        if (filter === undefined)
             return;
-        // haltState has no own transitions; symbol-list filters on it are silent
-        // no-ops at the engine level (spec §8.6), so accept any list shape here.
+        // #108 part 2: `.after` on haltState has no semantic anchor — halt is
+        // terminal, so there is no iteration-after-halt for an after-fire to
+        // attach to. Reject any truthy assignment (true OR list) at write time
+        // so misuse surfaces immediately rather than silently no-op'ing.
+        if (this.isHalt && fieldName === 'after') {
+            throw new Error('haltState.debug.after is not supported: halt is terminal, so there is '
+                + 'no iteration-after-halt for an after-fire to anchor on. Use '
+                + '{ before: true } to pause on halt entry.');
+        }
+        if (filter === true)
+            return;
+        // haltState has no own transitions; symbol-list filters on `before` are
+        // silent no-ops at the engine level (spec §8.6), so accept any list shape.
         if (this.isHalt)
             return;
         for (const sym of filter) {
@@ -1035,22 +1046,21 @@ class TuringMachine {
     get tapeBlock() {
         return __classPrivateFieldGet(this, _TuringMachine_tapeBlock, "f");
     }
-    async run({ initialState, stepsLimit = 1e5, onStep, onDebugBreak, }) {
+    async run({ initialState, stepsLimit = 1e5, onStep, onPause, debug = true, }) {
         const generator = this.runStepByStep({ initialState, stepsLimit });
-        let prevYield = null;
         for (const machineState of generator) {
-            // 'after' (from prev step) — fire FIRST, with prev yield substituted as the source view.
-            if (machineState.debugBreak?.after && onDebugBreak && prevYield) {
-                await onDebugBreak({ ...prevYield, debugBreak: { after: true } });
-            }
-            // 'before' (current step) — pass current machineState with only the before flag.
-            if (machineState.debugBreak?.before && onDebugBreak) {
-                await onDebugBreak({ ...machineState, debugBreak: { before: true } });
+            // Per-iter lifecycle: before → step → after. All three operate on the
+            // same yielded MachineState, so the consumer sees a coherent ordering
+            // within each iteration without cross-tick coordination.
+            if (debug && machineState.debugBreak?.before && onPause) {
+                await onPause({ ...machineState, debugBreak: { before: true } });
             }
             if (onStep instanceof Function) {
                 onStep(machineState);
             }
-            prevYield = machineState;
+            if (debug && machineState.debugBreak?.after && onPause) {
+                await onPause({ ...machineState, debugBreak: { after: true } });
+            }
         }
     }
     *runStepByStep({ initialState, stepsLimit = 1e5 }) {
@@ -1064,7 +1074,6 @@ class TuringMachine {
                 stack.push(state.overrodeHaltState);
             }
             let i = 0;
-            let pendingAfterFromPrev = false;
             while (!state.isHalt) {
                 if (i === stepsLimit) {
                     throw new Error('Long execution');
@@ -1074,8 +1083,12 @@ class TuringMachine {
                 const command = state.getCommand(symbol);
                 let nextState = state.getNextState(symbol).ref;
                 try {
+                    // Both before and after refer to THIS iter (#119 / v6.0.0).
+                    // The halting iter's after-fire just rides along on the iter's
+                    // own yield — no post-loop drain needed.
                     const beforeMatch = matchFilter(state.debug?.before, symbol)
                         || (nextState.isHalt && nextState.debug?.before === true);
+                    const afterMatch = matchFilter(state.debug?.after, symbol);
                     const nextStateForYield = nextState.isHalt && stack.length
                         ? stack.slice(-1)[0]
                         : nextState;
@@ -1099,17 +1112,15 @@ class TuringMachine {
                         movements: command.tapesCommands.map((tapeCommand) => tapeCommand.movement),
                         nextState: nextStateForYield,
                     };
-                    if (pendingAfterFromPrev || beforeMatch) {
+                    if (beforeMatch || afterMatch) {
                         const dbg = {};
-                        if (pendingAfterFromPrev)
-                            dbg.after = true;
                         if (beforeMatch)
                             dbg.before = true;
+                        if (afterMatch)
+                            dbg.after = true;
                         yielded.debugBreak = dbg;
                     }
                     yield yielded;
-                    // Re-evaluate 'after' for THIS visit, to fire on the NEXT yield.
-                    pendingAfterFromPrev = matchFilter(state.debug?.after, symbol);
                     __classPrivateFieldGet(this, _TuringMachine_tapeBlock, "f").applyCommand(command, executionSymbol);
                     if (nextState.isHalt && stack.length) {
                         nextState = stack.pop();

package/dist/index.mjs

@@ -788,10 +788,21 @@ class State {
     }
     /** @internal — invoked by DebugConfig setters via module-private symbol. */
     [(_State_id = new WeakMap(), _State_name = new WeakMap(), _State_overrodeHaltState = new WeakMap(), _State_symbolToDataMap = new WeakMap(), _State_debugRef = new WeakMap(), validateDebugFilter)](fieldName, filter) {
-        if (filter === undefined || filter === true)
+        if (filter === undefined)
             return;
-        // haltState has no own transitions; symbol-list filters on it are silent
-        // no-ops at the engine level (spec §8.6), so accept any list shape here.
+        // #108 part 2: `.after` on haltState has no semantic anchor — halt is
+        // terminal, so there is no iteration-after-halt for an after-fire to
+        // attach to. Reject any truthy assignment (true OR list) at write time
+        // so misuse surfaces immediately rather than silently no-op'ing.
+        if (this.isHalt && fieldName === 'after') {
+            throw new Error('haltState.debug.after is not supported: halt is terminal, so there is '
+                + 'no iteration-after-halt for an after-fire to anchor on. Use '
+                + '{ before: true } to pause on halt entry.');
+        }
+        if (filter === true)
+            return;
+        // haltState has no own transitions; symbol-list filters on `before` are
+        // silent no-ops at the engine level (spec §8.6), so accept any list shape.
         if (this.isHalt)
             return;
         for (const sym of filter) {
@@ -1033,22 +1044,21 @@ class TuringMachine {
     get tapeBlock() {
         return __classPrivateFieldGet(this, _TuringMachine_tapeBlock, "f");
     }
-    async run({ initialState, stepsLimit = 1e5, onStep, onDebugBreak, }) {
+    async run({ initialState, stepsLimit = 1e5, onStep, onPause, debug = true, }) {
         const generator = this.runStepByStep({ initialState, stepsLimit });
-        let prevYield = null;
         for (const machineState of generator) {
-            // 'after' (from prev step) — fire FIRST, with prev yield substituted as the source view.
-            if (machineState.debugBreak?.after && onDebugBreak && prevYield) {
-                await onDebugBreak({ ...prevYield, debugBreak: { after: true } });
-            }
-            // 'before' (current step) — pass current machineState with only the before flag.
-            if (machineState.debugBreak?.before && onDebugBreak) {
-                await onDebugBreak({ ...machineState, debugBreak: { before: true } });
+            // Per-iter lifecycle: before → step → after. All three operate on the
+            // same yielded MachineState, so the consumer sees a coherent ordering
+            // within each iteration without cross-tick coordination.
+            if (debug && machineState.debugBreak?.before && onPause) {
+                await onPause({ ...machineState, debugBreak: { before: true } });
             }
             if (onStep instanceof Function) {
                 onStep(machineState);
             }
-            prevYield = machineState;
+            if (debug && machineState.debugBreak?.after && onPause) {
+                await onPause({ ...machineState, debugBreak: { after: true } });
+            }
         }
     }
     *runStepByStep({ initialState, stepsLimit = 1e5 }) {
@@ -1062,7 +1072,6 @@ class TuringMachine {
                 stack.push(state.overrodeHaltState);
             }
             let i = 0;
-            let pendingAfterFromPrev = false;
             while (!state.isHalt) {
                 if (i === stepsLimit) {
                     throw new Error('Long execution');
@@ -1072,8 +1081,12 @@ class TuringMachine {
                 const command = state.getCommand(symbol);
                 let nextState = state.getNextState(symbol).ref;
                 try {
+                    // Both before and after refer to THIS iter (#119 / v6.0.0).
+                    // The halting iter's after-fire just rides along on the iter's
+                    // own yield — no post-loop drain needed.
                     const beforeMatch = matchFilter(state.debug?.before, symbol)
                         || (nextState.isHalt && nextState.debug?.before === true);
+                    const afterMatch = matchFilter(state.debug?.after, symbol);
                     const nextStateForYield = nextState.isHalt && stack.length
                         ? stack.slice(-1)[0]
                         : nextState;
@@ -1097,17 +1110,15 @@ class TuringMachine {
                         movements: command.tapesCommands.map((tapeCommand) => tapeCommand.movement),
                         nextState: nextStateForYield,
                     };
-                    if (pendingAfterFromPrev || beforeMatch) {
+                    if (beforeMatch || afterMatch) {
                         const dbg = {};
-                        if (pendingAfterFromPrev)
-                            dbg.after = true;
                         if (beforeMatch)
                             dbg.before = true;
+                        if (afterMatch)
+                            dbg.after = true;
                         yielded.debugBreak = dbg;
                     }
                     yield yielded;
-                    // Re-evaluate 'after' for THIS visit, to fire on the NEXT yield.
-                    pendingAfterFromPrev = matchFilter(state.debug?.after, symbol);
                     __classPrivateFieldGet(this, _TuringMachine_tapeBlock, "f").applyCommand(command, executionSymbol);
                     if (nextState.isHalt && stack.length) {
                         nextState = stack.pop();

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@turing-machine-js/machine",
-  "version": "5.0.0",
+  "version": "6.0.1",
   "description": "A convenient Turing machine",
   "engines": {
     "npm": ">=7.0.0"
   },
-  "author": "Ruslan Gilmullin <mellonis14@gmain.com>",
+  "author": "Ruslan Gilmullin <mellonis@yandex.ru>",
   "homepage": "https://github.com/mellonis/turing-machine-js#readme",
   "license": "GPL-3.0-or-later",
   "publishConfig": {
@@ -34,5 +34,5 @@
       "default": "./dist/index.mjs"
     }
   },
-  "gitHead": "ccf9a4743965c2a4ea6340ce1de8f6596e094251"
+  "gitHead": "d7ebca4e8379a548e3ca97eb83e96387de2cda32"
 }