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

package/dist/utilities/stateGraph.d.ts

@@ -0,0 +1,91 @@
+import State from '../classes/State';
+import TapeBlock from '../classes/TapeBlock';
+import { type Graph } from './graph';
+/**
+ * Walks the reachable graph from `initialState` and returns a serializable
+ * `Graph`. The walk is a BFS that visits each State exactly once (keyed by
+ * the State's internal id) and emits one `GraphNode` per State plus
+ * synthetic halt-marker nodes per callable-subtree frame.
+ *
+ * Round-trips losslessly with `fromGraph` in the sense that running the
+ * rebuilt machine on the same input produces the same output — but State
+ * instance identities are NOT preserved across the cycle.
+ *
+ * See `classes/State.ts` for the runtime model these graph nodes describe;
+ * see `utilities/graphFormats.ts` for the Mermaid-flavored serialization
+ * built on top of `Graph`.
+ */
+export declare function toGraph(initialState: State, tapeBlock: TapeBlock): Graph;
+/**
+ * Inverse of `toGraph`: rebuilds a State graph (and a fresh TapeBlock with
+ * the graph's alphabets) from a serialized Graph. Round-trips with `toGraph`
+ * in the sense that running the rebuilt machine on the same input gives the
+ * same output, but the rebuilt State instances have *new* internal IDs.
+ *
+ * Under the v7 callable-subtree model (#174), graph nodes split into:
+ *   - Wrapper nodes (`isWrapper: true`, no transitions) — reconstructed via
+ *     `bareStates[bareStateId].withOverriddenHaltState(finalStates[overriddenHaltStateId])`.
+ *   - Bare/regular nodes — constructed as normal States with transitions.
+ *   - Halt + halt-marker nodes — collapse to the singleton `haltState`.
+ */
+export declare function fromGraph(graph: Graph): {
+    start: State;
+    tapeBlock: TapeBlock;
+    states: Record<number, State>;
+};
+/**
+ * One entry in the `StateMap` returned by `collectStates` (#195).
+ *
+ * - `state`: the live `State` instance for this Graph node. For the halt
+ *   singleton at id `0`, this is the engine-wide `haltState` — toggling
+ *   `state.debug` on that entry affects every machine in the process.
+ * - `transitionSymbols`: per-pattern Symbols in `#symbolToDataMap` insertion
+ *   order, aligned positionally with `GraphTransition.id` patternIx. For
+ *   wrappers and the halt singleton this is `[]` (no own transitions).
+ */
+export type StateMapEntry = {
+    state: State;
+    transitionSymbols: symbol[];
+};
+/**
+ * Numeric `GraphNode.id` → `StateMapEntry`. Returned by `collectStates`
+ * (#195). Halt markers (synthetic nodes with `id = -frameId`) are NOT
+ * included — they're visualization-only and all collapse to the
+ * `haltState` singleton already exposed at id `0`.
+ */
+export type StateMap = Map<number, StateMapEntry>;
+/**
+ * Returns a `Map<number, {state, transitionSymbols}>` keyed by engine
+ * `GraphNode.id`, giving downstream tooling direct access to the `State`
+ * 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
+ * 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.
+ * Consumers filtering the catch-all path identity-compare against the
+ * engine-exported `ifOtherSymbol`.
+ *
+ * **Unbound-`Reference` slots.** `toGraph` increments `patternIx` even
+ * 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
+ * on the Graph side, dense on the `transitionSymbols` side — same
+ * indexing.
+ *
+ * **Coverage.** Map keys are the State-backed subset of `graph.nodes`:
+ * regulars + bares + wrappers + the halt singleton (id `0`). Synthetic
+ * halt markers (id `-frameId`) are excluded — they all reach the same
+ * `haltState` object at runtime, and the named consumer
+ * ([machines-demo#37](https://github.com/mellonis/machines-demo/issues/37))
+ * surfaces halt-pause via a separate UI control, not via clicks on
+ * halt glyphs. If a future consumer needs uniform-by-id lookup, the
+ * helper can be extended additively.
+ *
+ * **Halt-singleton warning.** `result.get(0)!.state === haltState` — the
+ * process-wide halt. Toggling `.debug` on that entry affects every
+ * machine in the runtime, not just the one this map was built from.
+ */
+export declare function collectStates(initialState: State, tapeBlock: TapeBlock): StateMap;

package/package.json

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