@turing-machine-js/machine 7.0.0-alpha.4 → 7.0.0-alpha.5

package/CHANGELOG.md

@@ -4,6 +4,38 @@ 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).
 
+## [7.0.0-alpha.5] - 2026-05-25
+
+Fifth v7 pre-release. Adds per-iter `matchedTransition` to `MachineState` so consumers can resolve the firing transition by graph id without re-deriving from `(source, nextState)` ambiguous pairs ([#205](https://github.com/mellonis/turing-machine-js/issues/205)), collapses `haltState.debug` to a `boolean` and moves the halt-imminent pause to the AFTER side of the halt-triggering iter so the wording + diagram cursor agree with the just-fired transition ([#207](https://github.com/mellonis/turing-machine-js/issues/207)), and renames the `GraphTransition.id` separator from `-` to `.` for parser-friendly splitting. Published under the `next` dist-tag: `npm install @turing-machine-js/machine@next`.
+
+**Pre-release — the API surface may still shift before stable v7.0.0.** Pin to a specific alpha for reproducibility: `@turing-machine-js/machine@7.0.0-alpha.5`.
+
+### Added
+
+- **`MachineState.matchedTransition`** ([#205](https://github.com/mellonis/turing-machine-js/issues/205)) — every yielded `MachineState` from `run` / `runStepByStep` now carries `{ id: string, matchKinds: ('wildcard' | 'literal')[] }`. `id` is `${stateId}.${transitionIx}` and resolves directly in `toGraph`'s output via `graph.nodes[stateId].transitions.find(t => t.id === ...)`. For wrapper-entry iters, `id` references the BARE's transition (wrappers delegate via `bareState`). `matchKinds` is per-tape, length = tape count; `'wildcard'` iff the winning alternative held `ifOtherSymbol` at that position. Eliminates `(source, nextState)` resolution ambiguity for tools doing exact-edge highlighting, per-transition coverage maps, or wildcard-aware log formatting.
+
+- **`State.getMatchedTransition(symbol)`** ([#205](https://github.com/mellonis/turing-machine-js/issues/205)) — public method returning `{ nextState, matchedSymbol, ix }` for the symbol's transition. Same lookup `getNextState` does, plus the index — exposes the K used by `MachineState.matchedTransition.id` so callers needing both don't pay for the lookup twice.
+
+- **`TapeBlock.patternKinds(symbol, currentSymbols?)`** ([#205](https://github.com/mellonis/turing-machine-js/issues/205)) — public method returning per-tape `'wildcard' | 'literal'` for the matched alternative's selector. The engine uses it internally to populate `matchedTransition.matchKinds`; exposed for consumers wiring custom dispatch.
+
+- **`HaltState` typed alias** ([#207](https://github.com/mellonis/turing-machine-js/issues/207)) — the exported `haltState` singleton now carries a narrower TypeScript type (`State & { debug: boolean; ... }`) so `haltState.debug = true` is type-safe at the call site. Generic `State` references still see `DebugConfig` — runtime branches on `this.isHalt`.
+
+### Changed
+
+- **`GraphTransition.id` separator: `-` → `.`** ([#205](https://github.com/mellonis/turing-machine-js/issues/205)). Was `${stateId}-${patternIx}`, now `${stateId}.${patternIx}`. Aligns with `matchedTransition.id` and makes the id splittable without colliding with user-defined state names that may contain `-`. **Breaking** for any consumer parsing the old separator; alpha-channel only.
+
+- **`haltState.debug` is `boolean`** ([#207](https://github.com/mellonis/turing-machine-js/issues/207)). Was `DebugConfig` with per-side `{ before?, after? }` filters; under v7 it's a single `boolean` flag. `haltState.debug = true` enables; `false` / `null` disables. **Object-shaped writes throw** (`{ before: true }`, `{ after: true }`, etc.). The pause fires on the AFTER side of the iter whose transition leads to halt — `m.state` is the triggering state (not haltState), `m.debugBreak.after === true`. Diagram + log narratives read naturally: the halt-bound transition has fired when the pause lands, and halt is the next thing. **Breaking** — pre-alpha.5 consumers using `haltState.debug = { before: true }` must switch to `haltState.debug = true`.
+
+  ⚠️ **Chained-form `haltState.debug.before = true` silently no-ops in non-strict mode.** The getter returns the boolean; assigning `.before` to a primitive is a JS no-op outside strict mode (`TypeError` in strict). The engine setter never sees the write. Use the whole-object form (`haltState.debug = true` / `= false` / `= null`).
+
+- **`State` internal: single `#getEntry` helper for `getCommand` / `getNextState` / `getMatchedTransition`** ([#206](https://github.com/mellonis/turing-machine-js/pull/206)). Internal refactor — no public API change. All three accessors now share one `.get()` lookup + unified throw message (`"No transition for symbol at state named ..."` — was per-method messages).
+
+- **Internal: dead-code typeof check on `state.debug` in `runStepByStep` removed; `patternKinds` defensive paths now have dedicated test coverage** ([#210](https://github.com/mellonis/turing-machine-js/pull/210)). Engine-internal cleanup that bumps overall coverage to 99.35% statements / 96.58% branches / 100% functions / 99.48% lines.
+
+### Docs
+
+- ⚠️ **README + CLAUDE.md** ([#209](https://github.com/mellonis/turing-machine-js/pull/209)) — warn that chained-form `haltState.debug.before = true` silently no-ops in non-strict mode (`new Function(...)`, `<script>` without `"use strict"`). Engine can't intercept (the write happens on a primitive after the getter returned); doc steers users to the whole-object form.
+
 ## [7.0.0-alpha.4] - 2026-05-23
 
 Fourth v7 pre-release. Adds an id-keyed lookup helper for the State graph ([#195](https://github.com/mellonis/turing-machine-js/issues/195)), fixes two upstream issues surfaced while wiring the new helper into downstream tooling — a `toMermaid` label-grammar bug ([#194](https://github.com/mellonis/turing-machine-js/issues/194)) and a halt-stack lifetime bug in `runStepByStep` ([#196](https://github.com/mellonis/turing-machine-js/issues/196)) — and extracts graph serialization into its own module without API change ([#180](https://github.com/mellonis/turing-machine-js/issues/180)). Published under the `next` dist-tag: `npm install @turing-machine-js/machine@next`.

package/README.md

@@ -327,6 +327,7 @@ Each yielded `step` (`MachineState`) has these fields:
 | `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 |
+| `matchedTransition` | `{ id: string, matchKinds: ('wildcard'\|'literal')[] }` | the transition the engine picked for this iter — see *Matched transition* below |
 
 `stepsLimit` (default `1e5`) guards against runaway loops — exceeding it throws.
 
@@ -346,6 +347,35 @@ Both APIs are first-class — `run()` is built on top of `runStepByStep()` (see
 
 **Don't split one logical flow across both APIs.** A consumer that wants stepwise UI *and* hook-driven breakpoints should use `run({ onStep, onPause, debug })` exclusively. Routing some operations through `runStepByStep()` and others through `run()` means `state.debug` only flows through one of the two paths — a subtle footgun where breakpoints silently disappear on whichever code path uses the generator directly. For per-iter throttle / "wait between steps" UIs, see [Throttle pattern](#throttle-pattern).
 
+### Matched transition
+
+Every yielded `MachineState` carries a `matchedTransition` describing which transition the engine picked for that iter. The engine already resolves this via `state.getNextState(symbol)` internally; this field exposes the resolution to consumers so visualizations, log formatters, and coverage maps don't have to re-derive an ambiguous `(source, nextState)` pair (which collides when multiple transitions on the same source share a destination) or parse pattern strings from `toGraph`.
+
+```ts
+matchedTransition: {
+  id: string;                               // resolvable in toGraph
+  matchKinds: ('wildcard' | 'literal')[];   // per-tape, length = tape count
+}
+```
+
+- **`id`** — `${stateId}.${transitionIx}`. Resolvable in `toGraph`'s output: `graph.nodes[stateId].transitions` has an entry with the matching `id`. For wrapper-entry iters (source is a wrapper produced by `withOverriddenHaltState`), `id` references the **bare's** transition — the wrapper's own `transitions` array in `toGraph` is empty because wrappers delegate, and the pattern actually lives on the bare. Detect by comparing `id.split('.')[0]` against `state.id`: different → wrapper delegation.
+
+- **`matchKinds`** — per-tape match kind for the matched alternative's selector at each tape position. `'wildcard'` if the position held `ifOtherSymbol` (catch-all) in the winning alternative; `'literal'` if it held a specific symbol or symbol-list. Length always equals tape count.
+
+Example use:
+
+```javascript
+await machine.run({
+  initialState,
+  onStep: (m) => {
+    const wildcardPositions = m.matchedTransition.matchKinds  // per-tape, e.g. ['wildcard', 'literal']
+      .map((k, i) => k === 'wildcard' ? i : -1)
+      .filter((i) => i >= 0);
+    console.log(`step ${m.step}: fired transition ${m.matchedTransition.id} (wildcards at tapes: ${wildcardPositions.join(',') || 'none'})`);
+  },
+});
+```
+
 ## Subroutine composition with `withOverriddenHaltState`
 
 `state.withOverriddenHaltState(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.
@@ -467,14 +497,20 @@ myState.debug = { before: true };
 myState.debug = { before: [symA] };
 myState.debug = { before: [symA], after: [symA] };
 
-// Pause when the engine is about to enter halt (program exit OR subroutine pop):
-haltState.debug = { before: true };
+// Pause when the engine is about to enter halt (program exit OR subroutine pop).
+// haltState.debug is a `boolean` (#207) — halt is terminal, so there's only
+// one meaningful pause moment (post-triggering-iter, before halt processing).
+haltState.debug = true;
+haltState.debug = false;        // turn off
+haltState.debug = null;         // alias of false (reset)
 
-// Reset filters later — next read returns a fresh empty DebugConfig:
+// Reset filters later on a regular state — next read returns a fresh empty DebugConfig:
 myState.debug = null;
 ```
 
-> ⚠️ **`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.
+> ⚠️ **`haltState.debug` is `boolean`-only.** Any object-shaped write (`{ before: true }`, `{ after: true }`, `{ before: true, after: true }`) throws at write time. The pause fires on the AFTER side of the iter whose transition leads to halt — `m.state` is the triggering state (not haltState), `m.debugBreak.after === true`. Diagram + log narratives read naturally: the halt-bound transition has already fired when the pause lands, and halt is the next thing.
+
+> ⚠️ **Chained-form `haltState.debug.before = true` doesn't throw in non-strict mode** — this is a JavaScript primitive quirk, not engine behavior. The getter returns the boolean `false`; assigning `.before` to that boolean is a no-op in non-strict mode (silent), a `TypeError` in strict mode. The engine setter only sees whole-object writes (`haltState.debug = X`), so it can't intercept the chained form. **Always use the whole-object form: `haltState.debug = true` / `= false` / `= null`.** Modules built with `tsc` / ESM run in strict mode by default and surface this throw; `new Function(...)` and `<script>` without `"use strict"` run non-strict and silently no-op the chained write.
 
 The `debug` field is mutable — toggle breakpoints at runtime without rebuilding the graph. The internal cell is shared with `state.withOverriddenHaltState(...)` wrappers, so an assignment on the original is visible from every wrapper. `state.debug` is always a `DebugConfig` instance (lazy-initialized on first read); plain-object input (`state.debug = { before: true }`) is wrapped in a fresh `DebugConfig` automatically. The instance itself is `Object.seal`-ed — typos like `state.debug.bofore = true` throw `TypeError` instead of silently creating a useless property. Per-property setters validate and freeze the stored array, so `state.debug.before.push(...)` also throws `TypeError`.
 
@@ -708,7 +744,7 @@ Reading `['0',*] → [K,'0']/[R,R]`:
 API surface changes since v3, in past tense so the timing of each piece is explicit:
 
 - **v4** — `run()` became async (`Promise<void>`). Per-state runtime breakpoints landed (`state.debug.before` / `state.debug.after`); `run()` accepted an `onDebugBreak` hook. `MachineState` exposed on each yield.
-- **v5** — `onDebugBreak` renamed to `onPause`. New `run({ debug: boolean })` master switch suppresses all `onPause` dispatches without unsetting `state.debug` assignments. Assigning a truthy `.after` to `haltState.debug` now throws at write time (halt is terminal — no iteration-after-halt to anchor on).
+- **v5** — `onDebugBreak` renamed to `onPause`. New `run({ debug: boolean })` master switch suppresses all `onPause` dispatches without unsetting `state.debug` assignments. Assigning a truthy `.after` to `haltState.debug` now throws at write time (halt is terminal — no iteration-after-halt to anchor on). *Superseded in v7 by #207: `haltState.debug` is now `boolean`, all object-shaped writes throw.*
 - **v6** — Per-iter lifecycle reordered to `before → step → after`, all firing on the same yield. Previously `after` fired on iter K+1's tick with a `prevYield` substitution dance; that substitution is gone. The `MachineState.debugBreak` field shape is unchanged across all three versions.
 - **v6.1** — `state.debug` ergonomics: the field is now always a non-null `DebugConfig` instance (lazy-initialized on first read), so chained field writes like `state.debug.before = true` work on a fresh state without a prior whole-object assignment. The `DebugConfig` instance is `Object.seal`-ed, so typos like `state.debug.bofore = true` throw `TypeError` at write time instead of silently creating a useless property. `state.debug = null` continues to work but semantically means "reset filters" — the next read returns a fresh empty `DebugConfig` (#150).
 - **v6.2** *(superseded by v6.3.0)* — widened `onStep`'s signature to `(m) => void | Promise<void>` and added an inline `await onStep(...)` in the run loop, enabling throttle-in-`onStep` patterns. This overturned the docstring-stated contract that `onStep` is sync (microtask-free); the right place for per-iter throttling is `onPause` with self-rearm (see [Throttle pattern](#throttle-pattern)). Restored in v6.3.0.

package/dist/classes/State.d.ts

@@ -73,11 +73,35 @@ export default class State {
      * code uses). Order matches insertion order of the underlying Set.
      */
     get tags(): readonly string[];
-    /** @internal — invoked by DebugConfig setters via module-private symbol. */
+    /** @internal — invoked by DebugConfig setters via module-private symbol.
+     *  Per #207, haltState no longer flows through DebugConfig (its `debug`
+     *  setter rejects object writes before construction), so the validator
+     *  only sees non-halt states here. */
     [validateDebugFilter](fieldName: 'before' | 'after', filter: readonly symbol[] | true | undefined): void;
     getSymbol(tapeBlock: TapeBlock): symbol;
     getCommand(symbol: symbol): Command;
     getNextState(symbol: symbol): State | Reference;
+    /**
+     * Like `getNextState`, but also returns the matched Symbol and its index
+     * in this State's transition declaration order (= the `K` in `toGraph`'s
+     * `${stateId}.${K}` transition ids). Used by `TuringMachine.runStepByStep`
+     * to populate `MachineState.matchedTransition` for #205 — exposes which
+     * transition fired so consumers (UIs, log tools, coverage maps) can
+     * resolve the firing edge without re-deriving from `(source, nextState)`,
+     * which is ambiguous when multiple transitions on the same source go to
+     * the same destination.
+     *
+     * Throws (matching `getNextState` / `getCommand`) when no entry exists for
+     * the symbol. For wrappers (states produced by `withOverriddenHaltState`):
+     * the symbol-to-data map is shared with the bare via `bareState`, so the
+     * returned `ix` is a valid position into BOTH the wrapper's and the
+     * bare's transition iteration order — they're the same map.
+     */
+    getMatchedTransition(symbol: symbol): {
+        nextState: State | Reference;
+        matchedSymbol: symbol;
+        ix: number;
+    };
     withOverriddenHaltState(overriddenHaltState: State): State;
     /**
      * @internal
@@ -164,5 +188,26 @@ export default class State {
      */
     static collectStates(initialState: State, tapeBlock: TapeBlock): StateMap;
 }
-export declare const haltState: State;
+/**
+ * Typed alias for the haltState singleton (#207). Narrows `debug` from
+ * the generic-State `DebugConfig | boolean` union to plain `boolean`,
+ * giving compile-time type-safety at the singleton's call sites:
+ *
+ * ```ts
+ * haltState.debug = true;            // ok
+ * haltState.debug = false;           // ok
+ * haltState.debug = { before: true } // TS error
+ * const isOn = haltState.debug;      // typed `boolean`
+ * ```
+ *
+ * Anyone holding a `State` reference that happens to BE the singleton (e.g.
+ * via `state.getNextState(sym).ref === haltState`) sees the wider `State`
+ * type; runtime throws guide them to the right shape. The singleton export
+ * is the canonical access path.
+ */
+export type HaltState = State & {
+    get debug(): boolean;
+    set debug(value: boolean | null);
+};
+export declare const haltState: HaltState;
 export {};

package/dist/classes/TapeBlock.d.ts

@@ -23,6 +23,31 @@ export default class TapeBlock {
         currentSymbols?: string[];
         symbol: symbol;
     }): boolean;
+    /**
+     * For a Symbol returned by `this.symbol([...])` (or the catch-all
+     * `ifOtherSymbol`), returns the per-tape match kind for the
+     * **alternative that actually matched** given `currentSymbols`:
+     * `'wildcard'` if that tape position was `ifOtherSymbol` in the winning
+     * alternative, `'literal'` otherwise. Length always equals the tape
+     * count.
+     *
+     * Used by `TuringMachine.runStepByStep` to populate
+     * `MachineState.matchedTransition.matchKinds` for #205. The "winning
+     * alternative" disambiguation matters for alternations like
+     * `[[ifOtherSymbol, 'c'], ['a', 'b']]` — different alternatives can
+     * have different per-tape kinds, and only the alternative that matched
+     * the current head symbols is meaningful.
+     *
+     * - `ifOtherSymbol` (the State's catch-all transition fired): all
+     *   positions are `'wildcard'`.
+     * - Symbol with patternList: find the first alternative that matches
+     *   `currentSymbols` (same predicate as `isMatched`), return its
+     *   per-position kinds.
+     * - Symbol with no winning alternative under the given `currentSymbols`
+     *   (defensive — shouldn't happen if the caller resolved the Symbol via
+     *   the State's normal matching): fall back to all `'literal'`.
+     */
+    patternKinds(symbol: symbol, currentSymbols?: string[]): ('wildcard' | 'literal')[];
     replaceTape(tape: Tape, tapeIx?: number): void;
 }
 export {};

package/dist/classes/TuringMachine.d.ts

@@ -26,6 +26,29 @@ export type MachineState = {
         before?: true;
         after?: true;
     };
+    /**
+     * The transition the engine picked for this iter (#205). Always present
+     * — `runStepByStep` resolves it at the very start of every iter via
+     * `state.getMatchedTransition(symbol)`, well before any callback fires.
+     *
+     * - `id` — resolvable in `toGraph`'s output: `graph.nodes[…].transitions`
+     *   contains a `GraphTransition` whose `.id` equals this value. Format is
+     *   `${stateId}.${transitionIx}`. **For wrapper-entry iters (`state` is
+     *   produced by `withOverriddenHaltState`): the wrapper's own
+     *   `transitions` array in `toGraph` is empty because wrappers delegate
+     *   to the bare; this field carries the BARE's transition id, where the
+     *   pattern actually lives.** Consumers can detect this case by
+     *   comparing `id.split('.')[0]` against `state.id` — different = wrapper
+     *   delegation.
+     * - `matchKinds` — per-tape match kind for the picked transition's
+     *   pattern at each tape position. `'wildcard'` if the matched
+     *   alternative had `ifOtherSymbol` at that position, `'literal'`
+     *   otherwise. Length equals tape count.
+     */
+    matchedTransition: {
+        id: string;
+        matchKinds: ('wildcard' | 'literal')[];
+    };
 };
 export default class TuringMachine {
     #private;

package/dist/index.cjs

@@ -655,6 +655,46 @@ class TapeBlock {
             .every((everySymbol, ix) => (everySymbol === ifOtherSymbol
             || everySymbol === currentSymbols[ix])))) ?? false;
     }
+    /**
+     * For a Symbol returned by `this.symbol([...])` (or the catch-all
+     * `ifOtherSymbol`), returns the per-tape match kind for the
+     * **alternative that actually matched** given `currentSymbols`:
+     * `'wildcard'` if that tape position was `ifOtherSymbol` in the winning
+     * alternative, `'literal'` otherwise. Length always equals the tape
+     * count.
+     *
+     * Used by `TuringMachine.runStepByStep` to populate
+     * `MachineState.matchedTransition.matchKinds` for #205. The "winning
+     * alternative" disambiguation matters for alternations like
+     * `[[ifOtherSymbol, 'c'], ['a', 'b']]` — different alternatives can
+     * have different per-tape kinds, and only the alternative that matched
+     * the current head symbols is meaningful.
+     *
+     * - `ifOtherSymbol` (the State's catch-all transition fired): all
+     *   positions are `'wildcard'`.
+     * - Symbol with patternList: find the first alternative that matches
+     *   `currentSymbols` (same predicate as `isMatched`), return its
+     *   per-position kinds.
+     * - Symbol with no winning alternative under the given `currentSymbols`
+     *   (defensive — shouldn't happen if the caller resolved the Symbol via
+     *   the State's normal matching): fall back to all `'literal'`.
+     */
+    patternKinds(symbol, currentSymbols = this.currentSymbols) {
+        const tapeCount = __classPrivateFieldGet$2(this, _TapeBlock_tapes, "f").length;
+        if (symbol === ifOtherSymbol) {
+            return Array.from({ length: tapeCount }, () => 'wildcard');
+        }
+        const patternList = __classPrivateFieldGet$2(this, _TapeBlock_symbolToPatternListMap, "f").get(symbol);
+        if (patternList === undefined) {
+            return Array.from({ length: tapeCount }, () => 'literal');
+        }
+        const winning = patternList.find((pattern) => (pattern.every((everySymbol, ix) => (everySymbol === ifOtherSymbol
+            || everySymbol === currentSymbols[ix]))));
+        if (winning === undefined) {
+            return Array.from({ length: tapeCount }, () => 'literal');
+        }
+        return winning.map((everySymbol) => (everySymbol === ifOtherSymbol ? 'wildcard' : 'literal'));
+    }
     replaceTape(tape, tapeIx = 0) {
         if (__classPrivateFieldGet$2(this, _TapeBlock_tapes, "f")[tapeIx] == null) {
             throw new Error('invalid tapeIx');
@@ -789,7 +829,14 @@ function toGraph(initialState, tapeBlock) {
                     movement: decodeMovement(tc.movement.description),
                 })),
                 nextStateId: targetInternal.id,
-                id: `${stateInternal.id}-${patternIx}`,
+                // Transition id format: `${stateId}.${transitionIx}` (#205).
+                // Matches `TuringMachine.runStepByStep`'s `MachineState.
+                // matchedTransition.id` so consumers can do
+                // `graph.nodes[stateId].transitions.find(t => t.id === id)`.
+                // Was `${stateId}-${ix}` pre-#205 — the `.` separator avoids
+                // the hyphen reading as a minus sign next to negative halt-
+                // marker ids in adjacent contexts.
+                id: `${stateInternal.id}.${patternIx}`,
             });
             queue.push(target);
             patternIx += 1;
@@ -827,6 +874,9 @@ function toGraph(initialState, tapeBlock) {
             // `nodes[id]` is always populated for `id` that the BFS reached, so
             // a defensive `!node` check would be dead. `isHalt` / `isWrapper`
             // are real boundaries — both stop reach-set expansion.
+            /* c8 ignore next 3 — defensive: the push site below already filters
+               halt/wrapper targets, and the initial push is always a bare, so
+               this branch is unreachable in practice. */
             if (node.isHalt || node.isWrapper) {
                 continue;
             }
@@ -1071,7 +1121,8 @@ function fromGraph(graph) {
  * instance + per-pattern Symbol references for breakpoint setup (#195).
  *
  * **Positional alignment contract.** For any `GraphTransition` whose id
- * is `${N}-${K}`, `result.get(N)!.transitionSymbols[K]` is the Symbol
+ * is `${N}.${K}` (#205 changed the separator from `-` to `.`),
+ * `result.get(N)!.transitionSymbols[K]` is the Symbol
  * the transition fires on (reference equality, not structural). The K-th
  * entry is the K-th key from the source State's `#symbolToDataMap` in
  * insertion order, including `ifOtherSymbol` when the user wrote one.
@@ -1082,7 +1133,7 @@ function fromGraph(graph) {
  * when a transition's `nextState` is an unresolved `Reference` (it
  * `continue`s without pushing the GraphTransition). In that case
  * `transitionSymbols[K]` is still set to the K-th Map key, but no
- * `Graph.nodes[N].transitions` entry exists with id `${N}-${K}`. Sparse
+ * `Graph.nodes[N].transitions` entry exists with id `${N}.${K}`. Sparse
  * on the Graph side, dense on the `transitionSymbols` side — same
  * indexing.
  *
@@ -1170,7 +1221,7 @@ function collectStates(initialState, tapeBlock) {
         }
         // Regular or bare State — enumerate `#symbolToDataMap.keys()` for
         // the patternIx alignment. The K-th key is the Symbol that
-        // `${id}-${K}` GraphTransition fires on (positional contract).
+        // `${id}.${K}` GraphTransition fires on (positional contract).
         const state = stateById.get(id);
         const transitionSymbols = [...state[STATE_INTERNAL]().symbolToDataMap.keys()];
         result.set(id, { state, transitionSymbols });
@@ -1196,7 +1247,7 @@ var __classPrivateFieldGet$1 = (undefined && undefined.__classPrivateFieldGet) |
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _DebugConfig_ownerState, _DebugConfig_before, _DebugConfig_after, _a, _State_wrapperCache, _State_id, _State_name, _State_overriddenHaltState, _State_bareState, _State_symbolToDataMap, _State_debugRef, _State_tags;
+var _DebugConfig_ownerState, _DebugConfig_before, _DebugConfig_after, _State_instances, _a, _State_wrapperCache, _State_id, _State_name, _State_overriddenHaltState, _State_bareState, _State_symbolToDataMap, _State_debugRef, _State_haltDebug, _State_tags, _State_getEntry;
 const ifOtherSymbol = Symbol('other symbol');
 // Module-private symbol used by DebugConfig setters to call State's validator
 // without exposing the validator on the public surface.
@@ -1262,6 +1313,7 @@ class DebugConfig {
 _DebugConfig_ownerState = new WeakMap(), _DebugConfig_before = new WeakMap(), _DebugConfig_after = new WeakMap();
 class State {
     constructor(stateDefinition = null, name) {
+        _State_instances.add(this);
         _State_id.set(this, id(this));
         // Not `readonly` because `withOverriddenHaltState` and `fromGraph` set the
         // composed name on a no-arg `new State()` to bypass the constructor's
@@ -1279,6 +1331,14 @@ class State {
         // Note: toGraph / fromGraph deliberately do not serialize debug — debug is
         // a runtime concern, not part of the structural graph.
         _State_debugRef.set(this, { current: null });
+        // Storage for `haltState.debug` (#207). haltState is a singleton terminal
+        // state — it has no iter of its own, so the per-side `{ before, after }`
+        // DebugConfig shape doesn't model anything meaningful for it. Instead the
+        // halt breakpoint is a single boolean ("enabled / disabled"). The pause
+        // anchors on the iter whose transition LEADS to halt, fired at end-of-iter
+        // (after that iter's own after-pause if armed). Only used when `isHalt`;
+        // ignored on every other State (whose `#debugRef` flow is unchanged).
+        _State_haltDebug.set(this, false);
         // Out-of-band tags applied to this State (#186). Tags are visualization
         // and debugger-tooling metadata — they don't affect runtime transition
         // lookup or `equivalentOn` comparisons. Stored as a Set for de-duplication;
@@ -1349,6 +1409,17 @@ class State {
         return this;
     }
     get debug() {
+        // haltState (#207): the canonical access path is the `haltState` singleton
+        // export, which is typed `HaltState` — its `debug` getter is narrowed to
+        // `boolean`. Generic `State` references statically see `DebugConfig` and
+        // (in practice) never refer to haltState — the run loop's `state` is
+        // never haltState because halt is terminal and doesn't iterate. The cast
+        // below makes the runtime boolean return type-compatible with the
+        // declared `DebugConfig` for any rare caller that holds a State
+        // reference happening to be haltState.
+        if (this.isHalt) {
+            return __classPrivateFieldGet$1(this, _State_haltDebug, "f");
+        }
         // Lazy-init: `state.debug` is never null at read time, so chained writes
         // like `state.debug.before = true` work on a fresh state without a prior
         // whole-object assignment. The setter still accepts `null` to reset the
@@ -1359,16 +1430,47 @@ class State {
         }
         return __classPrivateFieldGet$1(this, _State_debugRef, "f").current;
     }
+    // TS signature: non-halt callers (generic `State` reference) get the
+    // `DebugConfig | object | null` surface; boolean is rejected statically.
+    // The `HaltState` typed alias on the singleton export overrides this to
+    // `boolean | null` for the canonical halt access path. Runtime checks
+    // below are defensive against type-bypass / mixed-source callers.
     set debug(value) {
-        if (value === null) {
+        // Defensive runtime cast: TS signature excludes boolean for the generic
+        // State surface, but haltState (via the HaltState alias) DOES accept
+        // boolean, and the runtime needs to handle it for the singleton path.
+        const v = value;
+        // haltState (#207): only `boolean | null` is accepted. `null` aliases
+        // to `false` (reset). Any object-shaped write throws at write-time so
+        // misuse surfaces immediately rather than silently no-op'ing — the
+        // `{before, after}` shape doesn't model anything meaningful for halt
+        // (no own iter to anchor on; halt is terminal).
+        if (this.isHalt) {
+            if (v === null || typeof v === 'boolean') {
+                __classPrivateFieldSet$1(this, _State_haltDebug, v === true, "f");
+                return;
+            }
+            throw new Error('haltState.debug only accepts boolean (or null to reset). Use '
+                + '`haltState.debug = true` to enable the halt breakpoint, false to '
+                + 'disable. The pause fires after the iter whose transition leads to '
+                + 'halt (post-iter, before halt processing).');
+        }
+        // Non-halt states: boolean writes are rejected — the per-side
+        // `{before, after}` granularity is the contract. A boolean shortcut
+        // would hide the asymmetry between before / after.
+        if (typeof v === 'boolean') {
+            throw new Error('state.debug only accepts a DebugConfig or `{ before, after }` object '
+                + '(or null to reset). Boolean assignment is reserved for `haltState`.');
+        }
+        if (v === null) {
             __classPrivateFieldGet$1(this, _State_debugRef, "f").current = null;
             return;
         }
-        if (value instanceof DebugConfig) {
-            __classPrivateFieldGet$1(this, _State_debugRef, "f").current = value;
+        if (v instanceof DebugConfig) {
+            __classPrivateFieldGet$1(this, _State_debugRef, "f").current = v;
             return;
         }
-        __classPrivateFieldGet$1(this, _State_debugRef, "f").current = new DebugConfig(this, value);
+        __classPrivateFieldGet$1(this, _State_debugRef, "f").current = new DebugConfig(this, v);
     }
     /**
      * Add one or more tags to this State (#186). Tags are out-of-band metadata
@@ -1400,25 +1502,15 @@ class State {
     get tags() {
         return Object.freeze([...__classPrivateFieldGet$1(this, _State_tags, "f")]);
     }
-    /** @internal — invoked by DebugConfig setters via module-private symbol. */
-    [(_State_id = new WeakMap(), _State_name = new WeakMap(), _State_overriddenHaltState = new WeakMap(), _State_bareState = new WeakMap(), _State_symbolToDataMap = new WeakMap(), _State_debugRef = new WeakMap(), _State_tags = new WeakMap(), validateDebugFilter)](fieldName, filter) {
+    /** @internal — invoked by DebugConfig setters via module-private symbol.
+     *  Per #207, haltState no longer flows through DebugConfig (its `debug`
+     *  setter rejects object writes before construction), so the validator
+     *  only sees non-halt states here. */
+    [(_State_id = new WeakMap(), _State_name = new WeakMap(), _State_overriddenHaltState = new WeakMap(), _State_bareState = new WeakMap(), _State_symbolToDataMap = new WeakMap(), _State_debugRef = new WeakMap(), _State_haltDebug = new WeakMap(), _State_tags = new WeakMap(), _State_instances = new WeakSet(), validateDebugFilter)](fieldName, filter) {
         if (filter === undefined)
             return;
-        // #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) {
             if (sym !== ifOtherSymbol && !__classPrivateFieldGet$1(this, _State_symbolToDataMap, "f").has(sym)) {
                 throw new Error(`State.debug.${fieldName}: symbol is not a transition key of this state `
@@ -1437,16 +1529,40 @@ class State {
         return ifOtherSymbol;
     }
     getCommand(symbol) {
-        if (__classPrivateFieldGet$1(this, _State_symbolToDataMap, "f").has(symbol)) {
-            return __classPrivateFieldGet$1(this, _State_symbolToDataMap, "f").get(symbol).command;
-        }
-        throw new Error(`No command for symbol at state named ${__classPrivateFieldGet$1(this, _State_name, "f")}`);
+        return __classPrivateFieldGet$1(this, _State_instances, "m", _State_getEntry).call(this, symbol).command;
     }
     getNextState(symbol) {
-        if (__classPrivateFieldGet$1(this, _State_symbolToDataMap, "f").has(symbol)) {
-            return __classPrivateFieldGet$1(this, _State_symbolToDataMap, "f").get(symbol).nextState;
-        }
-        throw new Error(`No nextState for symbol at state named ${__classPrivateFieldGet$1(this, _State_id, "f")}`);
+        return __classPrivateFieldGet$1(this, _State_instances, "m", _State_getEntry).call(this, symbol).nextState;
+    }
+    /**
+     * Like `getNextState`, but also returns the matched Symbol and its index
+     * in this State's transition declaration order (= the `K` in `toGraph`'s
+     * `${stateId}.${K}` transition ids). Used by `TuringMachine.runStepByStep`
+     * to populate `MachineState.matchedTransition` for #205 — exposes which
+     * transition fired so consumers (UIs, log tools, coverage maps) can
+     * resolve the firing edge without re-deriving from `(source, nextState)`,
+     * which is ambiguous when multiple transitions on the same source go to
+     * the same destination.
+     *
+     * Throws (matching `getNextState` / `getCommand`) when no entry exists for
+     * the symbol. For wrappers (states produced by `withOverriddenHaltState`):
+     * the symbol-to-data map is shared with the bare via `bareState`, so the
+     * returned `ix` is a valid position into BOTH the wrapper's and the
+     * bare's transition iteration order — they're the same map.
+     */
+    getMatchedTransition(symbol) {
+        const entry = __classPrivateFieldGet$1(this, _State_instances, "m", _State_getEntry).call(this, symbol);
+        // Iteration order on a Map is insertion order; index lookup is O(N),
+        // acceptable since this fires at most once per iter and N (transitions
+        // per state) is typically tiny. If hot-path measurement ever flags it,
+        // cache as `#symbolToIxMap` mirror.
+        let ix = 0;
+        for (const key of __classPrivateFieldGet$1(this, _State_symbolToDataMap, "f").keys()) {
+            if (key === symbol)
+                break;
+            ix += 1;
+        }
+        return { nextState: entry.nextState, matchedSymbol: symbol, ix };
     }
     withOverriddenHaltState(overriddenHaltState) {
         // Unwrap `this` if it's itself a wrapper — the chain's inner overrides
@@ -1509,7 +1625,13 @@ class State {
      * read what they need. Adding fields here is a deliberate decision —
      * each adds to the implicit contract sibling modules can rely on.
      */
-    [STATE_INTERNAL]() {
+    [(_State_getEntry = function _State_getEntry(symbol) {
+        const entry = __classPrivateFieldGet$1(this, _State_symbolToDataMap, "f").get(symbol);
+        if (entry === undefined) {
+            throw new Error(`No transition for symbol at state named ${__classPrivateFieldGet$1(this, _State_name, "f")}`);
+        }
+        return entry;
+    }, STATE_INTERNAL)]() {
         // Aliasing `this` so the nested object-literal getters/setters below
         // can read/write the enclosing State's private fields — getters in an
         // object literal can't be arrow functions, so the standard arrow-
@@ -1678,14 +1800,43 @@ class TuringMachine {
                 i += 1;
                 const symbol = state.getSymbol(__classPrivateFieldGet(this, _TuringMachine_tapeBlock, "f"));
                 const command = state.getCommand(symbol);
-                let nextState = state.getNextState(symbol).ref;
+                const matched = state.getMatchedTransition(symbol);
+                let nextState = matched.nextState.ref;
+                // For wrapper-entry iters, the wrapper's transitions in `toGraph`
+                // are empty (wrappers delegate to the bare via shared
+                // `#symbolToDataMap`); the resolvable transition id lives under
+                // the bare's stateId. `bareState` is non-null only when `state`
+                // is a wrapper produced by `withOverriddenHaltState`. Accessed
+                // via the STATE_INTERNAL package-private view (same pattern
+                // `utilities/stateGraph.ts` uses) to avoid widening the public
+                // State API for this internal need.
+                const stateInternal = state[STATE_INTERNAL]();
+                const resolvableStateId = stateInternal.bareState?.id ?? state.id;
+                const matchedTransition = {
+                    id: `${resolvableStateId}.${matched.ix}`,
+                    matchKinds: __classPrivateFieldGet(this, _TuringMachine_tapeBlock, "f").patternKinds(matched.matchedSymbol),
+                };
                 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);
+                    //
+                    // #207: `haltState.debug` is now a boolean, and pauses on the
+                    // halt-triggering iter's AFTER side (not before). The previous
+                    // before-side check (`nextState.debug?.before === true`) was
+                    // "early-warning" timing — the user paused before the halt-bound
+                    // transition fired, then had to mentally re-derive what would
+                    // happen. Now the pause anchors post-step (after the iter's own
+                    // after-pause if armed), so consumers see the just-fired halt-
+                    // bound transition + diagram cursor still on the triggering state.
+                    //
+                    // `state` here is always non-halt (halt is terminal — the run
+                    // loop never iterates with state === haltState), so `state.debug`
+                    // is always `DebugConfig` at runtime. The public getter's return
+                    // type matches that.
+                    const beforeMatch = matchFilter(state.debug?.before, symbol);
+                    const afterMatch = matchFilter(state.debug?.after, symbol)
+                        || (nextState === haltState && haltState.debug);
                     const nextStateForYield = nextState.isHalt && stack.length
                         ? stack.slice(-1)[0]
                         : nextState;
@@ -1708,6 +1859,7 @@ class TuringMachine {
                         }),
                         movements: command.tapesCommands.map((tapeCommand) => tapeCommand.movement),
                         nextState: nextStateForYield,
+                        matchedTransition,
                     };
                     if (beforeMatch || afterMatch) {
                         const dbg = {};
@@ -1851,6 +2003,8 @@ function unescapeMermaidLabel(s) {
                     const n = Number.parseInt(hex, 16);
                     return n <= 0xFFFF ? String.fromCharCode(n) : String.fromCodePoint(n);
                 }
+                /* c8 ignore next 2 — defensive: the regex shape guarantees one of
+                   named / dec / hex is always set, so this fallback is unreachable. */
                 return match;
             }
         }

package/dist/index.mjs

@@ -653,6 +653,46 @@ class TapeBlock {
             .every((everySymbol, ix) => (everySymbol === ifOtherSymbol
             || everySymbol === currentSymbols[ix])))) ?? false;
     }
+    /**
+     * For a Symbol returned by `this.symbol([...])` (or the catch-all
+     * `ifOtherSymbol`), returns the per-tape match kind for the
+     * **alternative that actually matched** given `currentSymbols`:
+     * `'wildcard'` if that tape position was `ifOtherSymbol` in the winning
+     * alternative, `'literal'` otherwise. Length always equals the tape
+     * count.
+     *
+     * Used by `TuringMachine.runStepByStep` to populate
+     * `MachineState.matchedTransition.matchKinds` for #205. The "winning
+     * alternative" disambiguation matters for alternations like
+     * `[[ifOtherSymbol, 'c'], ['a', 'b']]` — different alternatives can
+     * have different per-tape kinds, and only the alternative that matched
+     * the current head symbols is meaningful.
+     *
+     * - `ifOtherSymbol` (the State's catch-all transition fired): all
+     *   positions are `'wildcard'`.
+     * - Symbol with patternList: find the first alternative that matches
+     *   `currentSymbols` (same predicate as `isMatched`), return its
+     *   per-position kinds.
+     * - Symbol with no winning alternative under the given `currentSymbols`
+     *   (defensive — shouldn't happen if the caller resolved the Symbol via
+     *   the State's normal matching): fall back to all `'literal'`.
+     */
+    patternKinds(symbol, currentSymbols = this.currentSymbols) {
+        const tapeCount = __classPrivateFieldGet$2(this, _TapeBlock_tapes, "f").length;
+        if (symbol === ifOtherSymbol) {
+            return Array.from({ length: tapeCount }, () => 'wildcard');
+        }
+        const patternList = __classPrivateFieldGet$2(this, _TapeBlock_symbolToPatternListMap, "f").get(symbol);
+        if (patternList === undefined) {
+            return Array.from({ length: tapeCount }, () => 'literal');
+        }
+        const winning = patternList.find((pattern) => (pattern.every((everySymbol, ix) => (everySymbol === ifOtherSymbol
+            || everySymbol === currentSymbols[ix]))));
+        if (winning === undefined) {
+            return Array.from({ length: tapeCount }, () => 'literal');
+        }
+        return winning.map((everySymbol) => (everySymbol === ifOtherSymbol ? 'wildcard' : 'literal'));
+    }
     replaceTape(tape, tapeIx = 0) {
         if (__classPrivateFieldGet$2(this, _TapeBlock_tapes, "f")[tapeIx] == null) {
             throw new Error('invalid tapeIx');
@@ -787,7 +827,14 @@ function toGraph(initialState, tapeBlock) {
                     movement: decodeMovement(tc.movement.description),
                 })),
                 nextStateId: targetInternal.id,
-                id: `${stateInternal.id}-${patternIx}`,
+                // Transition id format: `${stateId}.${transitionIx}` (#205).
+                // Matches `TuringMachine.runStepByStep`'s `MachineState.
+                // matchedTransition.id` so consumers can do
+                // `graph.nodes[stateId].transitions.find(t => t.id === id)`.
+                // Was `${stateId}-${ix}` pre-#205 — the `.` separator avoids
+                // the hyphen reading as a minus sign next to negative halt-
+                // marker ids in adjacent contexts.
+                id: `${stateInternal.id}.${patternIx}`,
             });
             queue.push(target);
             patternIx += 1;
@@ -825,6 +872,9 @@ function toGraph(initialState, tapeBlock) {
             // `nodes[id]` is always populated for `id` that the BFS reached, so
             // a defensive `!node` check would be dead. `isHalt` / `isWrapper`
             // are real boundaries — both stop reach-set expansion.
+            /* c8 ignore next 3 — defensive: the push site below already filters
+               halt/wrapper targets, and the initial push is always a bare, so
+               this branch is unreachable in practice. */
             if (node.isHalt || node.isWrapper) {
                 continue;
             }
@@ -1069,7 +1119,8 @@ function fromGraph(graph) {
  * instance + per-pattern Symbol references for breakpoint setup (#195).
  *
  * **Positional alignment contract.** For any `GraphTransition` whose id
- * is `${N}-${K}`, `result.get(N)!.transitionSymbols[K]` is the Symbol
+ * is `${N}.${K}` (#205 changed the separator from `-` to `.`),
+ * `result.get(N)!.transitionSymbols[K]` is the Symbol
  * the transition fires on (reference equality, not structural). The K-th
  * entry is the K-th key from the source State's `#symbolToDataMap` in
  * insertion order, including `ifOtherSymbol` when the user wrote one.
@@ -1080,7 +1131,7 @@ function fromGraph(graph) {
  * when a transition's `nextState` is an unresolved `Reference` (it
  * `continue`s without pushing the GraphTransition). In that case
  * `transitionSymbols[K]` is still set to the K-th Map key, but no
- * `Graph.nodes[N].transitions` entry exists with id `${N}-${K}`. Sparse
+ * `Graph.nodes[N].transitions` entry exists with id `${N}.${K}`. Sparse
  * on the Graph side, dense on the `transitionSymbols` side — same
  * indexing.
  *
@@ -1168,7 +1219,7 @@ function collectStates(initialState, tapeBlock) {
         }
         // Regular or bare State — enumerate `#symbolToDataMap.keys()` for
         // the patternIx alignment. The K-th key is the Symbol that
-        // `${id}-${K}` GraphTransition fires on (positional contract).
+        // `${id}.${K}` GraphTransition fires on (positional contract).
         const state = stateById.get(id);
         const transitionSymbols = [...state[STATE_INTERNAL]().symbolToDataMap.keys()];
         result.set(id, { state, transitionSymbols });
@@ -1194,7 +1245,7 @@ var __classPrivateFieldGet$1 = (undefined && undefined.__classPrivateFieldGet) |
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _DebugConfig_ownerState, _DebugConfig_before, _DebugConfig_after, _a, _State_wrapperCache, _State_id, _State_name, _State_overriddenHaltState, _State_bareState, _State_symbolToDataMap, _State_debugRef, _State_tags;
+var _DebugConfig_ownerState, _DebugConfig_before, _DebugConfig_after, _State_instances, _a, _State_wrapperCache, _State_id, _State_name, _State_overriddenHaltState, _State_bareState, _State_symbolToDataMap, _State_debugRef, _State_haltDebug, _State_tags, _State_getEntry;
 const ifOtherSymbol = Symbol('other symbol');
 // Module-private symbol used by DebugConfig setters to call State's validator
 // without exposing the validator on the public surface.
@@ -1260,6 +1311,7 @@ class DebugConfig {
 _DebugConfig_ownerState = new WeakMap(), _DebugConfig_before = new WeakMap(), _DebugConfig_after = new WeakMap();
 class State {
     constructor(stateDefinition = null, name) {
+        _State_instances.add(this);
         _State_id.set(this, id(this));
         // Not `readonly` because `withOverriddenHaltState` and `fromGraph` set the
         // composed name on a no-arg `new State()` to bypass the constructor's
@@ -1277,6 +1329,14 @@ class State {
         // Note: toGraph / fromGraph deliberately do not serialize debug — debug is
         // a runtime concern, not part of the structural graph.
         _State_debugRef.set(this, { current: null });
+        // Storage for `haltState.debug` (#207). haltState is a singleton terminal
+        // state — it has no iter of its own, so the per-side `{ before, after }`
+        // DebugConfig shape doesn't model anything meaningful for it. Instead the
+        // halt breakpoint is a single boolean ("enabled / disabled"). The pause
+        // anchors on the iter whose transition LEADS to halt, fired at end-of-iter
+        // (after that iter's own after-pause if armed). Only used when `isHalt`;
+        // ignored on every other State (whose `#debugRef` flow is unchanged).
+        _State_haltDebug.set(this, false);
         // Out-of-band tags applied to this State (#186). Tags are visualization
         // and debugger-tooling metadata — they don't affect runtime transition
         // lookup or `equivalentOn` comparisons. Stored as a Set for de-duplication;
@@ -1347,6 +1407,17 @@ class State {
         return this;
     }
     get debug() {
+        // haltState (#207): the canonical access path is the `haltState` singleton
+        // export, which is typed `HaltState` — its `debug` getter is narrowed to
+        // `boolean`. Generic `State` references statically see `DebugConfig` and
+        // (in practice) never refer to haltState — the run loop's `state` is
+        // never haltState because halt is terminal and doesn't iterate. The cast
+        // below makes the runtime boolean return type-compatible with the
+        // declared `DebugConfig` for any rare caller that holds a State
+        // reference happening to be haltState.
+        if (this.isHalt) {
+            return __classPrivateFieldGet$1(this, _State_haltDebug, "f");
+        }
         // Lazy-init: `state.debug` is never null at read time, so chained writes
         // like `state.debug.before = true` work on a fresh state without a prior
         // whole-object assignment. The setter still accepts `null` to reset the
@@ -1357,16 +1428,47 @@ class State {
         }
         return __classPrivateFieldGet$1(this, _State_debugRef, "f").current;
     }
+    // TS signature: non-halt callers (generic `State` reference) get the
+    // `DebugConfig | object | null` surface; boolean is rejected statically.
+    // The `HaltState` typed alias on the singleton export overrides this to
+    // `boolean | null` for the canonical halt access path. Runtime checks
+    // below are defensive against type-bypass / mixed-source callers.
     set debug(value) {
-        if (value === null) {
+        // Defensive runtime cast: TS signature excludes boolean for the generic
+        // State surface, but haltState (via the HaltState alias) DOES accept
+        // boolean, and the runtime needs to handle it for the singleton path.
+        const v = value;
+        // haltState (#207): only `boolean | null` is accepted. `null` aliases
+        // to `false` (reset). Any object-shaped write throws at write-time so
+        // misuse surfaces immediately rather than silently no-op'ing — the
+        // `{before, after}` shape doesn't model anything meaningful for halt
+        // (no own iter to anchor on; halt is terminal).
+        if (this.isHalt) {
+            if (v === null || typeof v === 'boolean') {
+                __classPrivateFieldSet$1(this, _State_haltDebug, v === true, "f");
+                return;
+            }
+            throw new Error('haltState.debug only accepts boolean (or null to reset). Use '
+                + '`haltState.debug = true` to enable the halt breakpoint, false to '
+                + 'disable. The pause fires after the iter whose transition leads to '
+                + 'halt (post-iter, before halt processing).');
+        }
+        // Non-halt states: boolean writes are rejected — the per-side
+        // `{before, after}` granularity is the contract. A boolean shortcut
+        // would hide the asymmetry between before / after.
+        if (typeof v === 'boolean') {
+            throw new Error('state.debug only accepts a DebugConfig or `{ before, after }` object '
+                + '(or null to reset). Boolean assignment is reserved for `haltState`.');
+        }
+        if (v === null) {
             __classPrivateFieldGet$1(this, _State_debugRef, "f").current = null;
             return;
         }
-        if (value instanceof DebugConfig) {
-            __classPrivateFieldGet$1(this, _State_debugRef, "f").current = value;
+        if (v instanceof DebugConfig) {
+            __classPrivateFieldGet$1(this, _State_debugRef, "f").current = v;
             return;
         }
-        __classPrivateFieldGet$1(this, _State_debugRef, "f").current = new DebugConfig(this, value);
+        __classPrivateFieldGet$1(this, _State_debugRef, "f").current = new DebugConfig(this, v);
     }
     /**
      * Add one or more tags to this State (#186). Tags are out-of-band metadata
@@ -1398,25 +1500,15 @@ class State {
     get tags() {
         return Object.freeze([...__classPrivateFieldGet$1(this, _State_tags, "f")]);
     }
-    /** @internal — invoked by DebugConfig setters via module-private symbol. */
-    [(_State_id = new WeakMap(), _State_name = new WeakMap(), _State_overriddenHaltState = new WeakMap(), _State_bareState = new WeakMap(), _State_symbolToDataMap = new WeakMap(), _State_debugRef = new WeakMap(), _State_tags = new WeakMap(), validateDebugFilter)](fieldName, filter) {
+    /** @internal — invoked by DebugConfig setters via module-private symbol.
+     *  Per #207, haltState no longer flows through DebugConfig (its `debug`
+     *  setter rejects object writes before construction), so the validator
+     *  only sees non-halt states here. */
+    [(_State_id = new WeakMap(), _State_name = new WeakMap(), _State_overriddenHaltState = new WeakMap(), _State_bareState = new WeakMap(), _State_symbolToDataMap = new WeakMap(), _State_debugRef = new WeakMap(), _State_haltDebug = new WeakMap(), _State_tags = new WeakMap(), _State_instances = new WeakSet(), validateDebugFilter)](fieldName, filter) {
         if (filter === undefined)
             return;
-        // #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) {
             if (sym !== ifOtherSymbol && !__classPrivateFieldGet$1(this, _State_symbolToDataMap, "f").has(sym)) {
                 throw new Error(`State.debug.${fieldName}: symbol is not a transition key of this state `
@@ -1435,16 +1527,40 @@ class State {
         return ifOtherSymbol;
     }
     getCommand(symbol) {
-        if (__classPrivateFieldGet$1(this, _State_symbolToDataMap, "f").has(symbol)) {
-            return __classPrivateFieldGet$1(this, _State_symbolToDataMap, "f").get(symbol).command;
-        }
-        throw new Error(`No command for symbol at state named ${__classPrivateFieldGet$1(this, _State_name, "f")}`);
+        return __classPrivateFieldGet$1(this, _State_instances, "m", _State_getEntry).call(this, symbol).command;
     }
     getNextState(symbol) {
-        if (__classPrivateFieldGet$1(this, _State_symbolToDataMap, "f").has(symbol)) {
-            return __classPrivateFieldGet$1(this, _State_symbolToDataMap, "f").get(symbol).nextState;
-        }
-        throw new Error(`No nextState for symbol at state named ${__classPrivateFieldGet$1(this, _State_id, "f")}`);
+        return __classPrivateFieldGet$1(this, _State_instances, "m", _State_getEntry).call(this, symbol).nextState;
+    }
+    /**
+     * Like `getNextState`, but also returns the matched Symbol and its index
+     * in this State's transition declaration order (= the `K` in `toGraph`'s
+     * `${stateId}.${K}` transition ids). Used by `TuringMachine.runStepByStep`
+     * to populate `MachineState.matchedTransition` for #205 — exposes which
+     * transition fired so consumers (UIs, log tools, coverage maps) can
+     * resolve the firing edge without re-deriving from `(source, nextState)`,
+     * which is ambiguous when multiple transitions on the same source go to
+     * the same destination.
+     *
+     * Throws (matching `getNextState` / `getCommand`) when no entry exists for
+     * the symbol. For wrappers (states produced by `withOverriddenHaltState`):
+     * the symbol-to-data map is shared with the bare via `bareState`, so the
+     * returned `ix` is a valid position into BOTH the wrapper's and the
+     * bare's transition iteration order — they're the same map.
+     */
+    getMatchedTransition(symbol) {
+        const entry = __classPrivateFieldGet$1(this, _State_instances, "m", _State_getEntry).call(this, symbol);
+        // Iteration order on a Map is insertion order; index lookup is O(N),
+        // acceptable since this fires at most once per iter and N (transitions
+        // per state) is typically tiny. If hot-path measurement ever flags it,
+        // cache as `#symbolToIxMap` mirror.
+        let ix = 0;
+        for (const key of __classPrivateFieldGet$1(this, _State_symbolToDataMap, "f").keys()) {
+            if (key === symbol)
+                break;
+            ix += 1;
+        }
+        return { nextState: entry.nextState, matchedSymbol: symbol, ix };
     }
     withOverriddenHaltState(overriddenHaltState) {
         // Unwrap `this` if it's itself a wrapper — the chain's inner overrides
@@ -1507,7 +1623,13 @@ class State {
      * read what they need. Adding fields here is a deliberate decision —
      * each adds to the implicit contract sibling modules can rely on.
      */
-    [STATE_INTERNAL]() {
+    [(_State_getEntry = function _State_getEntry(symbol) {
+        const entry = __classPrivateFieldGet$1(this, _State_symbolToDataMap, "f").get(symbol);
+        if (entry === undefined) {
+            throw new Error(`No transition for symbol at state named ${__classPrivateFieldGet$1(this, _State_name, "f")}`);
+        }
+        return entry;
+    }, STATE_INTERNAL)]() {
         // Aliasing `this` so the nested object-literal getters/setters below
         // can read/write the enclosing State's private fields — getters in an
         // object literal can't be arrow functions, so the standard arrow-
@@ -1676,14 +1798,43 @@ class TuringMachine {
                 i += 1;
                 const symbol = state.getSymbol(__classPrivateFieldGet(this, _TuringMachine_tapeBlock, "f"));
                 const command = state.getCommand(symbol);
-                let nextState = state.getNextState(symbol).ref;
+                const matched = state.getMatchedTransition(symbol);
+                let nextState = matched.nextState.ref;
+                // For wrapper-entry iters, the wrapper's transitions in `toGraph`
+                // are empty (wrappers delegate to the bare via shared
+                // `#symbolToDataMap`); the resolvable transition id lives under
+                // the bare's stateId. `bareState` is non-null only when `state`
+                // is a wrapper produced by `withOverriddenHaltState`. Accessed
+                // via the STATE_INTERNAL package-private view (same pattern
+                // `utilities/stateGraph.ts` uses) to avoid widening the public
+                // State API for this internal need.
+                const stateInternal = state[STATE_INTERNAL]();
+                const resolvableStateId = stateInternal.bareState?.id ?? state.id;
+                const matchedTransition = {
+                    id: `${resolvableStateId}.${matched.ix}`,
+                    matchKinds: __classPrivateFieldGet(this, _TuringMachine_tapeBlock, "f").patternKinds(matched.matchedSymbol),
+                };
                 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);
+                    //
+                    // #207: `haltState.debug` is now a boolean, and pauses on the
+                    // halt-triggering iter's AFTER side (not before). The previous
+                    // before-side check (`nextState.debug?.before === true`) was
+                    // "early-warning" timing — the user paused before the halt-bound
+                    // transition fired, then had to mentally re-derive what would
+                    // happen. Now the pause anchors post-step (after the iter's own
+                    // after-pause if armed), so consumers see the just-fired halt-
+                    // bound transition + diagram cursor still on the triggering state.
+                    //
+                    // `state` here is always non-halt (halt is terminal — the run
+                    // loop never iterates with state === haltState), so `state.debug`
+                    // is always `DebugConfig` at runtime. The public getter's return
+                    // type matches that.
+                    const beforeMatch = matchFilter(state.debug?.before, symbol);
+                    const afterMatch = matchFilter(state.debug?.after, symbol)
+                        || (nextState === haltState && haltState.debug);
                     const nextStateForYield = nextState.isHalt && stack.length
                         ? stack.slice(-1)[0]
                         : nextState;
@@ -1706,6 +1857,7 @@ class TuringMachine {
                         }),
                         movements: command.tapesCommands.map((tapeCommand) => tapeCommand.movement),
                         nextState: nextStateForYield,
+                        matchedTransition,
                     };
                     if (beforeMatch || afterMatch) {
                         const dbg = {};
@@ -1849,6 +2001,8 @@ function unescapeMermaidLabel(s) {
                     const n = Number.parseInt(hex, 16);
                     return n <= 0xFFFF ? String.fromCharCode(n) : String.fromCodePoint(n);
                 }
+                /* c8 ignore next 2 — defensive: the regex shape guarantees one of
+                   named / dec / hex is always set, so this fallback is unreachable. */
                 return match;
             }
         }

package/dist/utilities/stateGraph.d.ts

@@ -60,7 +60,8 @@ export type StateMap = Map<number, StateMapEntry>;
  * instance + per-pattern Symbol references for breakpoint setup (#195).
  *
  * **Positional alignment contract.** For any `GraphTransition` whose id
- * is `${N}-${K}`, `result.get(N)!.transitionSymbols[K]` is the Symbol
+ * is `${N}.${K}` (#205 changed the separator from `-` to `.`),
+ * `result.get(N)!.transitionSymbols[K]` is the Symbol
  * the transition fires on (reference equality, not structural). The K-th
  * entry is the K-th key from the source State's `#symbolToDataMap` in
  * insertion order, including `ifOtherSymbol` when the user wrote one.
@@ -71,7 +72,7 @@ export type StateMap = Map<number, StateMapEntry>;
  * when a transition's `nextState` is an unresolved `Reference` (it
  * `continue`s without pushing the GraphTransition). In that case
  * `transitionSymbols[K]` is still set to the K-th Map key, but no
- * `Graph.nodes[N].transitions` entry exists with id `${N}-${K}`. Sparse
+ * `Graph.nodes[N].transitions` entry exists with id `${N}.${K}`. Sparse
  * on the Graph side, dense on the `transitionSymbols` side — same
  * indexing.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/machine",
-  "version": "7.0.0-alpha.4",
+  "version": "7.0.0-alpha.5",
   "description": "A convenient Turing machine",
   "engines": {
     "npm": ">=7.0.0"
@@ -38,5 +38,5 @@
       "default": "./dist/index.mjs"
     }
   },
-  "gitHead": "0183c78ea7f7212ce983e99c846fc8e1fec5e56b"
+  "gitHead": "4838b823c5b93f74a783d8652746787436b431e4"
 }