@turing-machine-js/machine 4.0.0 → 6.0.0

package/CHANGELOG.md

@@ -4,6 +4,69 @@ 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)
+
+- **Hook renamed: `onDebugBreak` → `onPause`** on `run()` ([#110](https://github.com/mellonis/turing-machine-js/issues/110)). Hard rename, no deprecation alias. The hook signature, payload shape, and dispatch semantics are unchanged — only the option key on `run()` differs. Resolution of the [#109 RFC](https://github.com/mellonis/turing-machine-js/issues/109): the hook now describes the consumer's relationship (this is where you can pause) rather than the engine's event (a debug break fired). The `m.debugBreak` payload field is unchanged.
+- **`haltState.debug.after` now throws on assignment** ([#108](https://github.com/mellonis/turing-machine-js/issues/108) part 2). Halt is terminal — there is no iteration-after-halt for an after-fire to anchor on. Symmetric `{ before: true, after: true }` writes also throw; use `{ before: true }`. Symbol-list filters on `haltState.debug.before` remain silent no-ops as in v4.
+
+### Fixed
+
+- **Halting iter's `state.debug.after` now fires** ([#108](https://github.com/mellonis/turing-machine-js/issues/108) part 1). Previously `pendingAfterFromPrev` set after the halting iter's yield was discarded when the `while (!state.isHalt)` loop exited — losing that after-fire. `run()` now drains a final after-fire after the loop when the prior yield armed one. Observable: a debugger UI sees a "we just halted because of state X's after-filter" event that was silent before.
+
+### Added
+
+- **`run({ debug: boolean })` flag** ([#106](https://github.com/mellonis/turing-machine-js/issues/106)). Master switch for `onPause` dispatch. When `false`, suppresses all pause-fires (before, after, and the post-loop after-drain) 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); only `run()`'s hook dispatch is gated. Useful for toggling "debug mode" without editing `state.debug = ...` across the state graph.
+
+### Migration
+
+```diff
+  await machine.run({
+    initialState,
+-   onDebugBreak: (m) => { ... },
++   onPause: (m) => { ... },
+  });
+```
+
+```diff
+- haltState.debug = { before: true, after: true }; // throws in v5
++ haltState.debug = { before: true };
+```
+
 ## [4.0.0] - 2026-05-07
 
 ### Added

package/README.md

@@ -256,13 +256,13 @@ 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.
 
-`run()` is async and accepts an `onDebugBreak` hook:
+`run()` is async and accepts an `onPause` hook:
 
 ```ts
 await machine.run({
   initialState,
   onStep: (m) => { /* logger sees every step */ },
-  onDebugBreak: async (m) => {
+  onPause: async (m) => {
     // Awaited at every break — hold execution until you resolve.
     if (m.debugBreak?.before) console.log('before:', m.state.name);
     if (m.debugBreak?.after)  console.log('after:',  m.state.name);
@@ -270,9 +270,9 @@ 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 `onDebugBreak` is not provided, breaks fire-and-resume invisibly — the trajectory is identical to running without `debug` set.
+If `onPause` is not provided, breaks fire-and-resume invisibly — the trajectory is identical to running without `debug` set.
 
 **Filter semantics:** `true` is a wildcard (match any symbol). `[ifOtherSymbol]` is NOT a wildcard — it matches only the catch-all resolution case (same meaning as in transition keys).
 

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,9 +33,38 @@ export default class TuringMachine {
         tapeBlock?: TapeBlock;
     });
     get tapeBlock(): TapeBlock;
-    run({ initialState, stepsLimit, onStep, onDebugBreak, }: 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
+         * be async.
+         */
         onStep?: (machineState: MachineState) => void;
-        onDebugBreak?: (machineState: MachineState) => void | Promise<void>;
+        /**
+         * 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. 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>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/machine",
-  "version": "4.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": "6641f9e8fd9073771ffd1768a7a5931ff93349a6"
+  "gitHead": "6c7b2ac3055470b56c6882471767c746f5a9d7fb"
 }