@turing-machine-js/machine 5.0.0 → 6.0.0

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

@@ -270,7 +270,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/machine",
-  "version": "5.0.0",
+  "version": "6.0.0",
   "description": "A convenient Turing machine",
   "engines": {
     "npm": ">=7.0.0"
@@ -34,5 +34,5 @@
       "default": "./dist/index.mjs"
     }
   },
-  "gitHead": "ccf9a4743965c2a4ea6340ce1de8f6596e094251"
+  "gitHead": "6c7b2ac3055470b56c6882471767c746f5a9d7fb"
 }