ihsm 0.0.23 → 0.1.1

package/lib/cjs/internal/runtime.js

@@ -0,0 +1,1906 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.kParentLink = exports.kHandlerMachine = exports.defaultInitialize = exports.defaultTraceWriter = exports.Machine = exports.HsmObject = exports.RuntimeTransitionResolver = exports.TransitionTableError = exports.dispatchContext = exports.SelfCallDeadlockError = exports.kMachine = exports.CallTimeoutError = exports.ReservedNames = exports.StateGraph = exports.ProtocolCollisionError = exports.FatalErrorState = exports.InitializationError = exports.FatalError = exports.InitialStateError = exports.UnhandledEventError = exports.EventHandlerError = exports.TransitionError = exports.RuntimeError = exports.HsmError = exports.TopState = exports.RequestingPort = exports.Port = exports.TraceLevel = void 0;
+exports.asError = asError;
+exports.quoteUnknown = quoteUnknown;
+exports.quoteError = quoteError;
+exports.getInitialState = getInitialState;
+exports.hasInitialState = hasInitialState;
+exports.getTransitionKey = getTransitionKey;
+exports.defineStateName = defineStateName;
+exports.getStateName = getStateName;
+exports.lookupEventHandler = lookupEventHandler;
+exports.InitialState = InitialState;
+exports.registerStateNames = registerStateNames;
+exports.cacheProtocolIndex = cacheProtocolIndex;
+exports.protocolIndexFor = protocolIndexFor;
+exports.buildProtocolIndex = buildProtocolIndex;
+exports.isServiceCallOptions = isServiceCallOptions;
+exports.splitServiceArgs = splitServiceArgs;
+exports.serviceCallWithTimeout = serviceCallWithTimeout;
+exports.createActorHandle = createActorHandle;
+exports.getSelfNotificationsProto = getSelfNotificationsProto;
+exports.createSelfNotifications = createSelfNotifications;
+exports.planTransitionClasses = planTransitionClasses;
+exports.executeTransitionRoutine = executeTransitionRoutine;
+exports.createTransitionTracer = createTransitionTracer;
+exports.transitionTraceLines = transitionTraceLines;
+exports.executePendingTransition = executePendingTransition;
+exports.createInitTask = createInitTask;
+exports.createNotificationTask = createNotificationTask;
+exports.createServiceTask = createServiceTask;
+exports.isRequestingPort = isRequestingPort;
+exports.defaultDispatchErrorCallback = defaultDispatchErrorCallback;
+exports.spawnActor = spawnActor;
+exports.makeActor = makeActor;
+exports.asParentActor = asParentActor;
+exports.makeChildActor = makeChildActor;
+const types_1 = require("./types");
+//#region TraceLevel
+var TraceLevel;
+(function (TraceLevel) {
+    TraceLevel[TraceLevel["PRODUCTION"] = 0] = "PRODUCTION";
+    TraceLevel[TraceLevel["DEBUG"] = 1] = "DEBUG";
+    TraceLevel[TraceLevel["VERBOSE_DEBUG"] = 2] = "VERBOSE_DEBUG";
+})(TraceLevel || (exports.TraceLevel = TraceLevel = {}));
+//#endregion
+//#region utils
+/** @internal */
+function asError(err) {
+    return err instanceof Error ? err : new Error(String(err));
+}
+/** @internal */
+function quoteUnknown(err) {
+    return quoteError(asError(err));
+}
+/** @internal */
+function quoteError(err) {
+    return `${err.name}${err.message ? `: ${err.message}` : ' with no error message'}`;
+}
+/** @internal */
+function getInitialState(State) {
+    return State._initialState;
+}
+/** @internal */
+function hasInitialState(State) {
+    return Object.prototype.hasOwnProperty.call(State, '_initialState');
+}
+/** @internal */
+function getTransitionKey(FromState, ToState) {
+    return `${getStateName(FromState)}=>${getStateName(ToState)}`;
+}
+function defineStateName(state, displayName) {
+    Object.defineProperty(state, '_stateName', {
+        value: displayName,
+        writable: false,
+        configurable: false,
+        enumerable: false,
+    });
+}
+/** @internal — prefers an own explicit name registered for minified browser bundles. */
+function getStateName(state) {
+    if (Object.prototype.hasOwnProperty.call(state, '_stateName')) {
+        return state._stateName;
+    }
+    return state.name;
+}
+//#endregion
+//#region ports
+/** Production port: timers, randomness, and deferred self-notifications for one machine.
+ * @typeParam T - Root state **constructor** (`typeof DoorTop`), not the instance type. */
+class Port {
+    actor;
+    _deferFactory;
+    _timerSeq = 0;
+    _timeoutHandles = new Map();
+    _intervalHandles = new Map();
+    /** Schedule a one-shot callback after `millis` milliseconds (platform timer). */
+    setTimeout(callback, millis) {
+        const id = ++this._timerSeq;
+        const handle = globalThis.setTimeout(() => {
+            this._timeoutHandles.delete(id);
+            callback();
+        }, Math.max(0, millis ?? 0));
+        this._timeoutHandles.set(id, handle);
+        return id;
+    }
+    /** Cancel a timer previously returned by {@link Port.setTimeout}. */
+    clearTimeout(id) {
+        if (id === undefined) {
+            return;
+        }
+        const handle = this._timeoutHandles.get(id);
+        if (handle !== undefined) {
+            globalThis.clearTimeout(handle);
+            this._timeoutHandles.delete(id);
+        }
+    }
+    /** Schedule a repeating callback every `millis` milliseconds. */
+    setInterval(callback, millis) {
+        const id = ++this._timerSeq;
+        const handle = globalThis.setInterval(callback, Math.max(0, millis ?? 0));
+        this._intervalHandles.set(id, handle);
+        return id;
+    }
+    /** Cancel an interval previously returned by {@link Port.setInterval}. */
+    clearInterval(id) {
+        if (id === undefined) {
+            return;
+        }
+        const handle = this._intervalHandles.get(id);
+        if (handle !== undefined) {
+            globalThis.clearInterval(handle);
+            this._intervalHandles.delete(id);
+        }
+    }
+    /** Pseudorandom number in `[0, 1)` — delegates to `Math.random()`. */
+    random() {
+        return Math.random();
+    }
+    /** Cryptographic-quality random in `[0, 1)` when the platform provides it. */
+    cryptoRandom() {
+        const crypto = globalThis.crypto;
+        return crypto.random?.() ?? Math.random();
+    }
+    /** Generate a UUID v4 string via `crypto.randomUUID()`. */
+    randomUUID() {
+        return globalThis.crypto.randomUUID();
+    }
+    /** Fill `array` with cryptographically strong random bytes. */
+    getRandomValues(array) {
+        globalThis.crypto.getRandomValues(array);
+        return array;
+    }
+    /** @internal Wired by {@link Machine.bindPort} — do not call from application code. */
+    bindDeferredNotifications(factory) {
+        this._deferFactory = factory;
+    }
+    defer(ms) {
+        if (this._deferFactory === undefined) {
+            throw new Error('ihsm: port.defer requires actor binding — pass the port to makeActor / makeTestActor');
+        }
+        return this._deferFactory(ms);
+    }
+}
+exports.Port = Port;
+const kRequestingPort = Symbol('ihsm.requestingPort');
+class RequestingPort extends Port {
+}
+exports.RequestingPort = RequestingPort;
+RequestingPort[kRequestingPort] = true;
+//#endregion
+//#region Errors
+class TopState {
+    ctx;
+    hsm;
+    notify;
+    notifyNow;
+    constructor() {
+        throw new Error('Fatal error: States cannot be instantiated');
+    }
+    onExit() { }
+    onEntry() { }
+    onError(error) {
+        throw error;
+    }
+    onUnhandled(error) {
+        throw error;
+    }
+}
+exports.TopState = TopState;
+class HsmError extends Error {
+    name;
+    topStateName;
+    stateName;
+    context;
+    cause;
+    constructor(name, hsm, message, cause) {
+        super(message);
+        this.name = name;
+        this.topStateName = hsm.topStateName;
+        this.stateName = hsm.currentStateName;
+        this.context = hsm.ctx;
+        this.cause = cause;
+    }
+}
+exports.HsmError = HsmError;
+class RuntimeError extends HsmError {
+    eventName;
+    eventPayload;
+    constructor(errorName, hsm, message, cause) {
+        super(errorName, hsm, message, cause);
+        this.eventName = hsm.eventName;
+        this.eventPayload = hsm.eventPayload;
+    }
+}
+exports.RuntimeError = RuntimeError;
+class TransitionError extends RuntimeError {
+    failedStateName;
+    failedCallback;
+    fromStateName;
+    toStateName;
+    constructor(hsm, cause, failedStateName, failedCallback, fromStateName, toStateName) {
+        super('TransitionError', hsm, `${failedStateName}.${failedCallback}() has failed while executing a transition from ${fromStateName} to ${toStateName}`, cause);
+        this.failedStateName = failedStateName;
+        this.failedCallback = failedCallback;
+        this.fromStateName = fromStateName;
+        this.toStateName = toStateName;
+    }
+}
+exports.TransitionError = TransitionError;
+class EventHandlerError extends RuntimeError {
+    constructor(hsm, cause) {
+        super('EventHandlerError', hsm, `an error was thrown while executing event handler #${hsm.eventName} in state ${hsm.currentStateName}`, cause);
+    }
+}
+exports.EventHandlerError = EventHandlerError;
+class UnhandledEventError extends RuntimeError {
+    constructor(hsm) {
+        super('UnhandledEventError', hsm, `event #${hsm.eventName} was unhandled in state ${hsm.currentStateName}`);
+    }
+}
+exports.UnhandledEventError = UnhandledEventError;
+class InitialStateError extends Error {
+    targetStateName;
+    constructor(targetState) {
+        super(`State '${getStateName(Object.getPrototypeOf(targetState.prototype).constructor)}' must not have more than one initial state`);
+        this.name = 'InitialStateError';
+        this.targetStateName = getStateName(targetState);
+    }
+}
+exports.InitialStateError = InitialStateError;
+class FatalError extends RuntimeError {
+    constructor(hsm, cause) {
+        super('FatalError', hsm, `onError() has thrown ${quoteError(cause)}`, cause);
+    }
+}
+exports.FatalError = FatalError;
+class InitializationError extends HsmError {
+    failedState;
+    constructor(hsm, failedState, cause) {
+        super('InitializationError', hsm, `state ${getStateName(failedState)} has thrown ${quoteError(cause)} during initialization`, cause);
+        this.failedState = failedState;
+    }
+}
+exports.InitializationError = InitializationError;
+class FatalErrorState extends TopState {
+}
+exports.FatalErrorState = FatalErrorState;
+defineStateName(TopState, 'TopState');
+defineStateName(FatalErrorState, 'FatalErrorState');
+/** @internal */
+function lookupEventHandler(hsm, eventName) {
+    let state = hsm.currentState;
+    while (true) {
+        const prototype = state.prototype;
+        if (Object.prototype.hasOwnProperty.call(prototype, eventName)) {
+            return prototype[eventName];
+        }
+        if (state === TopState) {
+            return undefined;
+        }
+        state = Object.getPrototypeOf(state);
+    }
+}
+function InitialState(TargetState) {
+    const ParentOfTargetState = Object.getPrototypeOf(TargetState.prototype).constructor;
+    if (hasInitialState(ParentOfTargetState))
+        throw new InitialStateError(TargetState);
+    Object.defineProperty(TargetState, '_isInitialState', {
+        value: true,
+        writable: false,
+        configurable: false,
+        enumerable: false,
+    });
+    Object.defineProperty(ParentOfTargetState, '_initialState', {
+        value: TargetState,
+        writable: false,
+        configurable: false,
+        enumerable: false,
+    });
+}
+function registerStateNames(exports) {
+    for (const [exportName, value] of Object.entries(exports)) {
+        if (typeof value !== 'function')
+            continue;
+        const prototype = value.prototype;
+        if (typeof prototype !== 'object' || prototype === null || !TopState.prototype.isPrototypeOf(prototype))
+            continue;
+        defineStateName(value, exportName);
+        StateGraph.forRoot(findRootState(value)).register(value);
+    }
+}
+//#endregion
+//#region protocol-index
+//#region Protocol collision errors
+/** Thrown at construction when `Config`, state handlers, and the protocol index disagree. */
+class ProtocolCollisionError extends Error {
+    stateClass;
+    symbol;
+    // prettier-ignore
+    constructor(message, stateClass, symbol) {
+        super(message);
+        this.stateClass = stateClass;
+        this.symbol = symbol;
+        this.name = 'ProtocolCollisionError';
+    }
+    static reservedOnState(stateClass, symbol) {
+        return new ProtocolCollisionError(`ihsm: state class "${stateClass}" defines reserved symbol "${symbol}" — rename the protocol method; reserved symbols are: ${exports.ReservedNames.join(', ')}`, stateClass, symbol);
+    }
+}
+exports.ProtocolCollisionError = ProtocolCollisionError;
+//#endregion
+//#region State graph
+const stateGraphKey = Symbol('ihsm.stateGraph');
+function findRootState(state) {
+    let current = state;
+    while (true) {
+        const parent = Object.getPrototypeOf(current);
+        if (parent === TopState) {
+            return current;
+        }
+        const grandparent = Object.getPrototypeOf(parent);
+        if (grandparent === TopState) {
+            return current;
+        }
+        current = parent;
+    }
+}
+function handlerBucket(handler) {
+    const source = Function.prototype.toString.call(handler);
+    if (handler.constructor.name === 'AsyncFunction' || /\basync\b/.test(source)) {
+        return 'services';
+    }
+    if (/\breturn\s+[^(;]/.test(source)) {
+        return 'services';
+    }
+    return 'notifications';
+}
+/** Per–root-state registry of state classes for protocol scanning. */
+class StateGraph {
+    states = new Set();
+    register(state) {
+        this.states.add(state);
+    }
+    collect(topState) {
+        if (this.states.size > 0) {
+            return [...this.states];
+        }
+        return StateGraph.collectAlongPrototypeChain(topState);
+    }
+    static forRoot(root) {
+        const host = root;
+        let graph = host[stateGraphKey];
+        if (graph === undefined) {
+            graph = new StateGraph();
+            host[stateGraphKey] = graph;
+        }
+        return graph;
+    }
+    static collectAlongPrototypeChain(topState) {
+        const collected = new Set();
+        let current = topState;
+        while (current !== undefined && current !== TopState) {
+            collected.add(current);
+            current = Object.getPrototypeOf(current);
+            if (current === TopState)
+                break;
+        }
+        return [...collected];
+    }
+}
+exports.StateGraph = StateGraph;
+//#endregion
+//#region Protocol index cache
+const indexByRoot = new WeakMap();
+function cacheProtocolIndex(topState, index) {
+    indexByRoot.set(topState, index);
+    return index;
+}
+function protocolIndexFor(topState) {
+    return indexByRoot.get(topState);
+}
+//#endregion
+//#region Protocol index
+const reservedSet = new Set(['ctx', 'hsm', 'notify', 'notifyNow', 'onEntry', 'onExit', 'onError', 'onUnhandled']);
+exports.ReservedNames = ['ctx', 'hsm', 'notify', 'notifyNow', 'onEntry', 'onExit', 'onError', 'onUnhandled'];
+const lifecycleHooks = new Set(['onEntry', 'onExit', 'onError', 'onUnhandled']);
+class ProtocolIndexImpl {
+    slots;
+    constructor(slots) {
+        this.slots = slots;
+    }
+    get(name) {
+        return this.slots.get(name);
+    }
+    *entries(kind) {
+        for (const [name, slot] of this.slots) {
+            if (kind === 'root' && (slot.bucket === 'services' || slot.bucket === 'notifications')) {
+                yield [name, slot];
+            }
+            else if (kind === 'inbound' && slot.bucket !== 'internalServices') {
+                yield [name, slot];
+            }
+            else if (kind === 'child' || kind === 'test') {
+                yield [name, slot];
+            }
+        }
+    }
+}
+/** Build a protocol index by scanning handler methods on the state graph (`async` → services, otherwise notifications). */
+function buildProtocolIndex(topState) {
+    const states = StateGraph.forRoot(findRootState(topState)).collect(topState);
+    for (const state of states) {
+        const prototype = state.prototype;
+        for (const name of Object.getOwnPropertyNames(prototype)) {
+            if (!reservedSet.has(name) || lifecycleHooks.has(name) || name === 'constructor')
+                continue;
+            if (typeof prototype[name] === 'function') {
+                throw ProtocolCollisionError.reservedOnState(getStateName(state), name);
+            }
+        }
+    }
+    const slots = new Map();
+    const seen = new Set();
+    for (const state of states) {
+        const prototype = state.prototype;
+        for (const name of Object.getOwnPropertyNames(prototype)) {
+            if (reservedSet.has(name) || lifecycleHooks.has(name) || name === 'constructor')
+                continue;
+            const handler = prototype[name];
+            if (typeof handler !== 'function' || seen.has(name))
+                continue;
+            seen.add(name);
+            const bucket = handlerBucket(handler);
+            slots.set(name, { bucket, name });
+        }
+    }
+    return new ProtocolIndexImpl(slots);
+}
+//#endregion
+//#region handles
+/** Thrown when a service client call exceeds `{ timeoutMs }`. */
+class CallTimeoutError extends Error {
+    method;
+    // prettier-ignore
+    constructor(method) {
+        super(`ihsm: service "${method}" timed out`);
+        this.method = method;
+        this.name = 'CallTimeoutError';
+    }
+}
+exports.CallTimeoutError = CallTimeoutError;
+exports.kMachine = Symbol('ihsm.machine');
+function isServiceCallOptions(value) {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    const record = value;
+    if (!('timeoutMs' in record)) {
+        return false;
+    }
+    const timeoutMs = record.timeoutMs;
+    return timeoutMs === undefined || (typeof timeoutMs === 'number' && Number.isFinite(timeoutMs) && timeoutMs >= 0);
+}
+function splitServiceArgs(args) {
+    if (args.length === 0) {
+        return { callArgs: [], timeoutMs: undefined };
+    }
+    const last = args[args.length - 1];
+    if (!isServiceCallOptions(last)) {
+        return { callArgs: [...args], timeoutMs: undefined };
+    }
+    const timeoutMs = last.timeoutMs;
+    if (timeoutMs === undefined) {
+        return { callArgs: [...args], timeoutMs: undefined };
+    }
+    return { callArgs: args.slice(0, -1), timeoutMs };
+}
+function serviceCallWithTimeout(promise, method, timeoutMs) {
+    if (timeoutMs === 0) {
+        return Promise.reject(new CallTimeoutError(method));
+    }
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new CallTimeoutError(method));
+        }, timeoutMs);
+        promise.then(value => {
+            clearTimeout(timer);
+            resolve(value);
+        }, err => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+const facetProtoCache = new WeakMap();
+/**
+ * Build (and cache) the frozen prototype for one facet of one embodiment.
+ * Delivery mode is fixed by the facet — `call` dispatches services, `notify`
+ * the default queue, `notifyNow` the priority queue — so the runtime no longer
+ * needs to infer it per handler at the call site.
+ */
+function getFacetProto(topState, index, kind, facet) {
+    let map = facetProtoCache.get(topState);
+    if (map === undefined) {
+        map = new Map();
+        facetProtoCache.set(topState, map);
+    }
+    const cacheKey = `${kind}:${facet}`;
+    let proto = map.get(cacheKey);
+    if (proto === undefined) {
+        const built = Object.create(null);
+        // Dispatch mode is fixed by the facet, not by the handler's signature, so
+        // every member visible to this embodiment kind is exposed on every facet.
+        // The static types (`NotifyFacet` / `CallFacet`) are the gate that decides
+        // which members are legal to reach through which facet; the runtime never
+        // needs to guess service-vs-notification from the handler's return type.
+        const queue = facet === 'notifyNow' ? 'priority' : 'default';
+        for (const [name] of index.entries(kind)) {
+            if (facet === 'call') {
+                built[name] = function (...args) {
+                    const { callArgs, timeoutMs } = splitServiceArgs(args);
+                    const promise = this[exports.kMachine].dispatchService(name, callArgs);
+                    return timeoutMs === undefined ? promise : serviceCallWithTimeout(promise, name, timeoutMs);
+                };
+            }
+            else {
+                built[name] = function (...args) {
+                    this[exports.kMachine].dispatchNotification(name, args, queue);
+                };
+            }
+        }
+        proto = Object.freeze(built);
+        map.set(cacheKey, proto);
+    }
+    return proto;
+}
+function createFacet(machine, topState, index, kind, facet) {
+    const facetHandle = Object.create(getFacetProto(topState, index, kind, facet));
+    Object.defineProperty(facetHandle, exports.kMachine, { value: machine, enumerable: false });
+    return facetHandle;
+}
+/** @internal */
+function createActorHandle(machine, topState, index, kind) {
+    // Faceted surface only — protocol members live under `notify` / `notifyNow`
+    // / `call`. There are no flat methods on the handle, so `actor.theEvent()`
+    // is a compile-time and runtime error; callers must go through a facet.
+    const handle = {};
+    Object.defineProperty(handle, exports.kMachine, { value: machine, enumerable: false });
+    if (kind === 'test') {
+        Object.defineProperty(handle, 'ctx', {
+            enumerable: true,
+            get() {
+                return machine.ctx;
+            },
+        });
+    }
+    Object.defineProperty(handle, 'notify', { value: createFacet(machine, topState, index, kind, 'notify'), enumerable: true });
+    Object.defineProperty(handle, 'notifyNow', { value: createFacet(machine, topState, index, kind, 'notifyNow'), enumerable: true });
+    Object.defineProperty(handle, 'call', { value: createFacet(machine, topState, index, kind, 'call'), enumerable: true });
+    handle.hsm = machine.actorHsmFor(kind);
+    return handle;
+}
+const selfProtoCache = new WeakMap();
+/** @internal */
+function getSelfNotificationsProto(topState, index, queue) {
+    let map = selfProtoCache.get(topState);
+    if (map === undefined) {
+        map = new Map();
+        selfProtoCache.set(topState, map);
+    }
+    let proto = map.get(queue);
+    if (proto === undefined) {
+        const built = Object.create(null);
+        // Self-send always uses notification dispatch (you cannot await a service
+        // on yourself); `SelfNotifications<C>` is the static gate for which members
+        // are reachable, so expose every member visible to the handler embodiment.
+        for (const [name] of index.entries('inbound')) {
+            built[name] = function (...args) {
+                this[exports.kMachine].dispatchNotification(name, args, queue);
+            };
+        }
+        proto = Object.freeze(built);
+        map.set(queue, proto);
+    }
+    return proto;
+}
+function createSelfNotifications(machine, topState, index, queue) {
+    const handle = Object.create(getSelfNotificationsProto(topState, index, queue));
+    Object.defineProperty(handle, exports.kMachine, { value: machine, enumerable: false });
+    return handle;
+}
+//#region dispatch-guard
+/// <reference types="node" />
+/** Thrown in debug builds when a service targets the machine currently dispatching. */
+class SelfCallDeadlockError extends Error {
+    constructor() {
+        super('ihsm: awaiting a service on your own machine from inside your own dispatch deadlocks');
+        this.name = 'SelfCallDeadlockError';
+    }
+}
+exports.SelfCallDeadlockError = SelfCallDeadlockError;
+/**
+ * Lazy Node AsyncLocalStorage for non-production deadlock detection.
+ * State lives in a closure — no exported mutable slot.
+ */
+exports.dispatchContext = (() => {
+    let storage = undefined;
+    function get() {
+        if (storage !== undefined) {
+            return storage ?? undefined;
+        }
+        if (typeof process === 'undefined' || process.versions?.node === undefined) {
+            storage = null;
+            return undefined;
+        }
+        try {
+            // Dynamic require — no unconditional `node:async_hooks` import (browser-safe bundle).
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const hooks = require('node:async_hooks');
+            storage = new hooks.AsyncLocalStorage();
+            return storage;
+        }
+        catch {
+            storage = null;
+            return undefined;
+        }
+    }
+    function resetInit() {
+        storage = undefined;
+    }
+    function markUnavailable() {
+        storage = null;
+    }
+    return { get, resetInit, markUnavailable };
+})();
+//#region transition-routines
+/** Thrown when a generated transition table's graph hash does not match the scanned hierarchy. */
+class TransitionTableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TransitionTableError';
+    }
+}
+exports.TransitionTableError = TransitionTableError;
+/** Compute the LCA transition path (same algorithm as `dispatch.production.ts`). */
+function planTransitionClasses(srcState, destState) {
+    const src = srcState;
+    let dst = destState;
+    let srcPath = [];
+    const end = TopState;
+    const srcIndex = new Map();
+    const dstPath = [];
+    let cur = src;
+    let i = 0;
+    while (cur !== end) {
+        srcPath.push(cur);
+        srcIndex.set(cur, i);
+        cur = Object.getPrototypeOf(cur);
+        ++i;
+    }
+    cur = dst;
+    while (cur !== end) {
+        const index = srcIndex.get(cur);
+        if (index !== undefined) {
+            srcPath = srcPath.slice(0, index);
+            break;
+        }
+        dstPath.unshift(cur);
+        cur = Object.getPrototypeOf(cur);
+    }
+    while (hasInitialState(dst)) {
+        dst = getInitialState(dst);
+        dstPath.push(dst);
+    }
+    let finalState;
+    if (dstPath.length !== 0) {
+        finalState = dstPath[dstPath.length - 1];
+    }
+    else if (srcPath.length !== 0) {
+        finalState = Object.getPrototypeOf(srcPath[srcPath.length - 1]);
+    }
+    else {
+        finalState = undefined;
+    }
+    return { exit: srcPath, entry: dstPath, finalState };
+}
+async function invokeLifecycleHook(hsm, instance, state, hook, fromStateName, toStateName, style, tracer) {
+    const statePrototype = state.prototype;
+    const stateName = getStateName(state);
+    const hasHook = Object.prototype.hasOwnProperty.call(statePrototype, hook);
+    if ((style === 'verbose' || style === 'debug') && !hasHook) {
+        if (style === 'verbose') {
+            tracer?.traceHookSkipped(stateName, hook);
+        }
+        return;
+    }
+    try {
+        const res = statePrototype[hook].call(instance);
+        if (res) {
+            await res;
+        }
+        if (style === 'verbose') {
+            tracer?.traceHookDone(stateName, hook);
+        }
+    }
+    catch (cause) {
+        if (style === 'verbose') {
+            tracer?.traceHookError(stateName, hook, cause);
+        }
+        throw new TransitionError(hsm, asError(cause), stateName, hook, fromStateName, toStateName);
+    }
+}
+/**
+ * Execute a planned transition path with production or verbose semantics.
+ *
+ * Used by the runtime dispatch layer, generated transition tables (`@ihsm/tools`), and oracle tests.
+ */
+async function executeTransitionRoutine(hsm, instance, plan, srcState, dstState, options = {}) {
+    const style = options.style ?? 'production';
+    const tracer = options.tracer;
+    const fromStateName = getStateName(srcState);
+    const toStateName = getStateName(dstState);
+    if (style === 'verbose' || style === 'debug') {
+        tracer?.traceTransitionStart(fromStateName, toStateName);
+    }
+    for (const state of plan.exit) {
+        await invokeLifecycleHook(hsm, instance, state, 'onExit', fromStateName, toStateName, style, tracer);
+    }
+    for (const state of plan.entry) {
+        await invokeLifecycleHook(hsm, instance, state, 'onEntry', fromStateName, toStateName, style, tracer);
+    }
+    const applyState = (next) => {
+        if (options.setCurrentState) {
+            options.setCurrentState(next);
+        }
+        else if ('currentState' in hsm) {
+            hsm.currentState = next;
+        }
+    };
+    if (style === 'verbose') {
+        const finalState = plan.entry.length !== 0 ? plan.entry[plan.entry.length - 1] : plan.exit.length !== 0 ? Object.getPrototypeOf(plan.exit[plan.exit.length - 1]) : srcState;
+        tracer?.traceTransitionDone(getStateName(finalState));
+        applyState(finalState);
+        return;
+    }
+    if (style === 'debug' && plan.finalState) {
+        tracer?.traceTransitionDone(getStateName(plan.finalState));
+        applyState(plan.finalState);
+        return;
+    }
+    if (plan.finalState) {
+        applyState(plan.finalState);
+    }
+}
+function createTransitionTracer(hsm) {
+    return {
+        traceTransitionStart(fromStateName, toStateName) {
+            hsm._tracePush(`transition from ${fromStateName} to ${toStateName}`, `started transition from ${fromStateName} to ${toStateName} `);
+        },
+        traceHookDone(stateName, hook) {
+            hsm._traceWrite(`${stateName}.${hook}() done`);
+        },
+        traceHookSkipped(stateName, hook) {
+            hsm._traceWrite(`${stateName}.${hook}() skipped: default empty implementation`);
+        },
+        traceHookError(stateName, hook, cause) {
+            hsm._tracePopError(`${stateName}.${hook}() has thrown ${quoteUnknown(cause)}`);
+        },
+        traceTransitionDone(finalStateName) {
+            hsm._tracePopDone(`final state is ${finalStateName}`);
+        },
+    };
+}
+/** Collect canonical transition trace lines (for oracle comparison). */
+function transitionTraceLines(lines) {
+    return lines
+        .map(line => {
+        const idx = line.indexOf(': ');
+        return idx >= 0 ? line.slice(idx + 2) : line;
+    })
+        .filter(line => line.startsWith('started transition from ') || line.endsWith('.onExit() done') || line.endsWith('.onEntry() done') || line.includes('.onExit() skipped:') || line.includes('.onEntry() skipped:') || line.includes('.onExit() has thrown') || line.includes('.onEntry() has thrown') || line.startsWith('done: final state is ') || (line.startsWith('failure: ') && line.includes('.onExit() has thrown')) || (line.startsWith('failure: ') && line.includes('.onEntry() has thrown')));
+}
+//#region actor-dispatch
+class RuntimeTransitionRoutine {
+    plan;
+    constructor(plan) {
+        this.plan = plan;
+    }
+    async execute(hsm, srcState, dstState) {
+        const style = hsm.traceLevel === TraceLevel.PRODUCTION ? 'production' : hsm.traceLevel === TraceLevel.DEBUG ? 'debug' : 'verbose';
+        await executeTransitionRoutine(hsm, hsm._instance, this.plan, srcState, dstState, {
+            style,
+            ...(style !== 'production' ? { tracer: createTransitionTracer(hsm) } : {}),
+            setCurrentState: state => {
+                hsm.currentState = state;
+            },
+        });
+    }
+}
+class RuntimeTransitionResolver {
+    cache = new Map();
+    hasCached(src, dest) {
+        return this.cache.has(getTransitionKey(src, dest));
+    }
+    resolve(src, dest) {
+        const key = getTransitionKey(src, dest);
+        let routine = this.cache.get(key);
+        if (routine === undefined) {
+            routine = new RuntimeTransitionRoutine(planTransitionClasses(src, dest));
+            this.cache.set(key, routine);
+        }
+        return routine;
+    }
+}
+exports.RuntimeTransitionResolver = RuntimeTransitionResolver;
+/** @internal */
+async function executePendingTransition(host, resolver) {
+    if (host._transitionState === undefined) {
+        if (host.traceLevel === TraceLevel.VERBOSE_DEBUG) {
+            host._traceWrite('no transition requested');
+        }
+        return;
+    }
+    try {
+        const srcState = host.currentState;
+        const destState = host._transitionState;
+        if (host.traceLevel === TraceLevel.VERBOSE_DEBUG) {
+            host._traceWrite(`requested transition from ${getStateName(srcState)} to ${getStateName(destState)} `);
+            const runtimeResolver = resolver;
+            if (runtimeResolver.hasCached(srcState, destState)) {
+                host._traceWrite(`transition cache hit for ${getStateName(srcState)} to ${getStateName(destState)} `);
+            }
+            else {
+                host._traceWrite(`transition cache miss for ${getStateName(srcState)} to ${getStateName(destState)} `);
+            }
+        }
+        try {
+            await resolver.resolve(srcState, destState).execute(host, srcState, destState);
+        }
+        catch (transitionError) {
+            host.currentState = FatalErrorState;
+            throw transitionError;
+        }
+    }
+    finally {
+        host._transitionState = undefined;
+    }
+}
+//#region Service / notification dispatch tasks
+async function completePendingTransitions(host, resolver, onComplete) {
+    await executePendingTransition(host, resolver);
+    onComplete();
+}
+async function doError(host, resolver, err, onComplete) {
+    host._transitionState = undefined;
+    const messageHandler = host.currentState.prototype.onError;
+    try {
+        const result = messageHandler.call(host._instance, new EventHandlerError(host, err));
+        if (result) {
+            await result;
+        }
+        await completePendingTransitions(host, resolver, onComplete);
+    }
+    catch (recoveryErr) {
+        if (recoveryErr instanceof TransitionError) {
+            throw new FatalError(host, recoveryErr);
+        }
+        const recoveryError = asError(recoveryErr);
+        host.transition(FatalErrorState);
+        await completePendingTransitions(host, resolver, onComplete);
+        throw new FatalError(host, recoveryError);
+    }
+}
+async function doUnhandledEvent(host, resolver, error, onComplete) {
+    try {
+        const result = host.currentState.prototype.onUnhandled.call(host._instance, error);
+        if (result) {
+            await result;
+        }
+        await completePendingTransitions(host, resolver, onComplete);
+    }
+    catch (recoveryErr) {
+        if (recoveryErr instanceof TransitionError) {
+            host.currentState = FatalErrorState;
+            throw recoveryErr;
+        }
+        await doError(host, resolver, asError(recoveryErr), onComplete);
+    }
+}
+async function invokeHandler(host, resolver, name, args, options = {}) {
+    const recover = options.recover ?? false;
+    const finishEvent = () => {
+        host._currentEventName = undefined;
+        host._currentEventPayload = undefined;
+    };
+    host._currentEventName = name;
+    host._currentEventPayload = [...args];
+    try {
+        const eventHandler = lookupEventHandler(host, name);
+        if (!eventHandler) {
+            await doUnhandledEvent(host, resolver, new UnhandledEventError(host), finishEvent);
+            return undefined;
+        }
+        try {
+            const result = eventHandler.call(host._instance, ...args);
+            const settled = result instanceof Promise ? await result : result;
+            await completePendingTransitions(host, resolver, finishEvent);
+            return settled;
+        }
+        catch (recoveryErr) {
+            if (recoveryErr instanceof UnhandledEventError) {
+                await doUnhandledEvent(host, resolver, recoveryErr, finishEvent);
+                return undefined;
+            }
+            if (recoveryErr instanceof TransitionError) {
+                finishEvent();
+                throw recoveryErr;
+            }
+            if (recover) {
+                await doError(host, resolver, asError(recoveryErr), finishEvent);
+                return undefined;
+            }
+            finishEvent();
+            throw asError(recoveryErr);
+        }
+    }
+    catch (err) {
+        finishEvent();
+        throw err;
+    }
+}
+async function executeInitProduction(hsm) {
+    let currState = hsm.topState;
+    try {
+        while (true) {
+            const proto = currState.prototype;
+            if (proto.hasOwnProperty('onEntry')) {
+                proto.onEntry.call(hsm._instance);
+            }
+            if (hasInitialState(currState)) {
+                currState = getInitialState(currState);
+            }
+            else
+                break;
+        }
+        hsm.currentState = currState;
+    }
+    catch (cause) {
+        if (cause instanceof TransitionError) {
+            throw cause;
+        }
+        hsm.currentState = FatalErrorState;
+        throw new InitializationError(hsm, currState, asError(cause));
+    }
+}
+async function executeInitDebug(hsm) {
+    hsm._traceWrite('begin initialization');
+    try {
+        let currState = hsm.topState;
+        hsm._tracePush(`initialize`, `started initialization from ${getStateName(hsm.topState)}`);
+        try {
+            while (true) {
+                if (Object.prototype.hasOwnProperty.call(currState.prototype, 'onEntry')) {
+                    currState.prototype['onEntry'].call(hsm._instance);
+                }
+                if (hasInitialState(currState)) {
+                    currState = getInitialState(currState);
+                }
+                else {
+                    break;
+                }
+            }
+            hsm._tracePopDone(`final state is ${getStateName(currState)}`);
+            hsm.currentState = currState;
+        }
+        catch (cause) {
+            if (cause instanceof TransitionError) {
+                throw cause;
+            }
+            hsm._tracePopError(`initialization failed from top state '${getStateName(hsm.topState)}' as ${getStateName(currState)}.onEntry() handler has raised ${quoteUnknown(cause)}; final state is ${getStateName(FatalErrorState)}`);
+            hsm.currentState = FatalErrorState;
+            throw new InitializationError(hsm, currState, asError(cause));
+        }
+    }
+    finally {
+        hsm._traceWrite('end initialization');
+    }
+}
+async function executeInitVerbose(hsm) {
+    hsm._traceWrite('begin initialization');
+    try {
+        let currState = hsm.topState;
+        hsm._tracePush(`initialize`, `started initialization from ${getStateName(hsm.topState)}`);
+        try {
+            while (true) {
+                if (Object.prototype.hasOwnProperty.call(currState.prototype, 'onEntry')) {
+                    currState.prototype['onEntry'].call(hsm._instance);
+                    hsm._traceWrite(`${getStateName(currState)}.onEntry() done`);
+                }
+                else {
+                    hsm._traceWrite(`skip ${getStateName(currState)}.onEntry(): default empty implementation`);
+                }
+                if (hasInitialState(currState)) {
+                    const newInitialState = getInitialState(currState);
+                    hsm._traceWrite(`${getStateName(currState)} initial state is ${getStateName(newInitialState)}`);
+                    currState = newInitialState;
+                }
+                else {
+                    hsm._traceWrite(`${getStateName(currState)} has no initial state; final state is ${getStateName(currState)}`);
+                    break;
+                }
+            }
+            hsm._tracePopDone(`final state is ${getStateName(currState)}`);
+            hsm.currentState = currState;
+        }
+        catch (cause) {
+            if (cause instanceof TransitionError) {
+                throw cause;
+            }
+            hsm._tracePopError(`initialization failed from top state '${getStateName(hsm.topState)}' as ${getStateName(currState)}.onEntry() handler has raised ${quoteUnknown(cause)}; final state is ${getStateName(FatalErrorState)}`);
+            hsm.currentState = FatalErrorState;
+            throw new InitializationError(hsm, currState, asError(cause));
+        }
+    }
+    finally {
+        hsm._traceWrite('end initialization');
+    }
+}
+async function dispatchEventProduction(hsm, resolver, eventName, ...eventPayload) {
+    await invokeHandler(hsm, resolver, eventName, eventPayload, { recover: true });
+}
+function debugFinishEventDispatch(hsm) {
+    hsm._traceWrite(`end event dispatch`);
+    hsm._currentEventName = undefined;
+    hsm._currentEventPayload = undefined;
+}
+async function debugDoError(hsm, resolver, err, onComplete) {
+    hsm._transitionState = undefined;
+    hsm._tracePush(`error recovery`, `started error recovery`);
+    try {
+        hsm._tracePush('execute', 'started #onError handler execution');
+        const result = hsm.currentState.prototype.onError.call(hsm._instance, new EventHandlerError(hsm, err));
+        if (result) {
+            await result;
+        }
+        hsm._tracePopDone('error handler execution successful');
+        await completePendingTransitions(hsm, resolver, () => {
+            hsm._tracePopDone('error recovery successful');
+            onComplete();
+        });
+    }
+    catch (recoveryErr) {
+        hsm._tracePopError(`error handler execution failure: ${quoteUnknown(recoveryErr)}`);
+        if (recoveryErr instanceof TransitionError) {
+            hsm._tracePopError(`error recovery failure: ${quoteUnknown(recoveryErr)}`);
+            throw new FatalError(hsm, recoveryErr);
+        }
+        const recoveryError = asError(recoveryErr);
+        hsm.transition(FatalErrorState);
+        await completePendingTransitions(hsm, resolver, () => {
+            hsm._tracePopError(`error recovery failure: ${quoteUnknown(recoveryError)}`);
+            onComplete();
+        });
+        throw new FatalError(hsm, recoveryError);
+    }
+}
+async function debugDoUnhandledEvent(hsm, resolver, error, onComplete) {
+    hsm._tracePush('unhandled recovery', `started unhandled event recovery`);
+    try {
+        hsm._tracePush('execute', 'started #onUnhandled handler execution');
+        const result = hsm.currentState.prototype.onUnhandled.call(hsm._instance, error);
+        if (result) {
+            await result;
+        }
+        hsm._tracePopDone('unhandled handler execution successful');
+        await completePendingTransitions(hsm, resolver, () => {
+            hsm._tracePopDone('unhandled event recovery successful');
+            onComplete();
+        });
+    }
+    catch (recoveryErr) {
+        hsm._tracePopError(`unhandled event recovery failure: ${quoteUnknown(recoveryErr)}`);
+        if (recoveryErr instanceof TransitionError) {
+            hsm.currentState = FatalErrorState;
+            hsm._tracePopError(`unhandled event recovery failure: ${quoteUnknown(recoveryErr)}`);
+            throw recoveryErr;
+        }
+        try {
+            await debugDoError(hsm, resolver, asError(recoveryErr), () => {
+                hsm._tracePopDone('unhandled event recovery successful');
+                onComplete();
+            });
+        }
+        catch (nestedErr) {
+            hsm._tracePopError(`unhandled event recovery failure: ${quoteUnknown(nestedErr)}`);
+            throw nestedErr;
+        }
+    }
+}
+async function dispatchEventDebug(hsm, resolver, eventName, ...eventPayload) {
+    const eventLabel = String(eventName);
+    hsm._traceWrite(`begin event dispatch of #${eventLabel}`);
+    hsm._tracePush(`#${eventLabel}`, `started event dispatch`);
+    hsm._currentEventName = eventLabel;
+    hsm._currentEventPayload = eventPayload;
+    try {
+        const eventHandler = lookupEventHandler(hsm, eventName);
+        if (!eventHandler) {
+            try {
+                await debugDoUnhandledEvent(hsm, resolver, new UnhandledEventError(hsm), () => {
+                    hsm._tracePopDone('event dispatch successful');
+                    debugFinishEventDispatch(hsm);
+                });
+                return;
+            }
+            catch (recoveryErr) {
+                hsm._tracePopError(`event dispatch failed: ${quoteUnknown(recoveryErr)}`);
+                debugFinishEventDispatch(hsm);
+                throw recoveryErr;
+            }
+        }
+        try {
+            hsm._tracePush('execute', 'started event handler execution');
+            const result = eventHandler.call(hsm._instance, ...eventPayload);
+            if (result) {
+                await result;
+            }
+            hsm._tracePopDone('event handler execution successful');
+            await completePendingTransitions(hsm, resolver, () => {
+                hsm._tracePopDone(`event dispatch successful`);
+                debugFinishEventDispatch(hsm);
+            });
+        }
+        catch (recoveryErr) {
+            hsm._tracePopError(quoteUnknown(recoveryErr));
+            if (recoveryErr instanceof UnhandledEventError) {
+                try {
+                    await debugDoUnhandledEvent(hsm, resolver, recoveryErr, () => {
+                        hsm._tracePopDone('event dispatch successful');
+                        debugFinishEventDispatch(hsm);
+                    });
+                    return;
+                }
+                catch (nestedErr) {
+                    hsm._tracePopError(`event dispatch failed: ${quoteUnknown(nestedErr)}`);
+                    debugFinishEventDispatch(hsm);
+                    throw nestedErr;
+                }
+            }
+            else if (recoveryErr instanceof TransitionError) {
+                hsm._tracePopError(`event dispatch failed: ${quoteUnknown(recoveryErr)}`);
+                debugFinishEventDispatch(hsm);
+                throw recoveryErr;
+            }
+            else {
+                try {
+                    await debugDoError(hsm, resolver, asError(recoveryErr), () => {
+                        hsm._tracePopDone('event dispatch successful');
+                        debugFinishEventDispatch(hsm);
+                    });
+                }
+                catch (nestedErr) {
+                    hsm._tracePopError(`event dispatch failed: ${quoteUnknown(nestedErr)}`);
+                    debugFinishEventDispatch(hsm);
+                    throw nestedErr;
+                }
+            }
+        }
+    }
+    catch (err) {
+        debugFinishEventDispatch(hsm);
+        throw err;
+    }
+}
+function verboseFinishEventDispatch(hsm) {
+    hsm._traceWrite(`end event dispatch`);
+    hsm._currentEventName = undefined;
+    hsm._currentEventPayload = undefined;
+}
+async function verboseDoError(hsm, resolver, err, onComplete) {
+    hsm._transitionState = undefined;
+    hsm._tracePush(`error recovery`, `started error recovery`);
+    hsm._tracePush(`lookup`, `started lookup of #onError event handler`);
+    let errorLookupState = hsm.currentState;
+    let messageHandler;
+    while (errorLookupState != TopState) {
+        const errorPrototype = errorLookupState.prototype;
+        if (Object.prototype.hasOwnProperty.call(errorPrototype, 'onError')) {
+            hsm._tracePopDone(`found in state ${getStateName(errorLookupState)}`);
+            messageHandler = errorPrototype['onError'];
+            break;
+        }
+        hsm._traceWrite(`not found in state ${getStateName(errorLookupState)}`);
+        errorLookupState = Object.getPrototypeOf(errorLookupState);
+    }
+    if (messageHandler === undefined) {
+        hsm._tracePopDone(`found in state ${getStateName(TopState)}`);
+        messageHandler = TopState.prototype.onError;
+    }
+    try {
+        hsm._tracePush('execute', 'started #onError handler execution');
+        const result = messageHandler.call(hsm._instance, new EventHandlerError(hsm, err));
+        if (result) {
+            await result;
+        }
+        hsm._tracePopDone('error handler execution successful');
+        await completePendingTransitions(hsm, resolver, () => {
+            hsm._tracePopDone('error recovery successful');
+            onComplete();
+        });
+    }
+    catch (recoveryErr) {
+        hsm._tracePopError(`error handler execution failure: ${quoteUnknown(recoveryErr)}`);
+        if (recoveryErr instanceof TransitionError) {
+            hsm._tracePopError(`error recovery failure: ${quoteUnknown(recoveryErr)}`);
+            throw recoveryErr;
+        }
+        const recoveryError = asError(recoveryErr);
+        hsm.transition(FatalErrorState);
+        await completePendingTransitions(hsm, resolver, () => {
+            hsm._tracePopError(`error recovery failure: ${quoteUnknown(recoveryError)}`);
+            onComplete();
+        });
+        throw new FatalError(hsm, recoveryError);
+    }
+}
+async function verboseDoUnhandledEvent(hsm, resolver, error, onComplete) {
+    hsm._tracePush('unhandled recovery', `started unhandled event recovery`);
+    let unhandledLookupState = hsm.currentState;
+    hsm._tracePush(`lookup`, `started lookup of #onUnhandled event handler`);
+    let messageHandler;
+    while (true) {
+        const unhandledPrototype = unhandledLookupState.prototype;
+        if (Object.prototype.hasOwnProperty.call(unhandledPrototype, 'onUnhandled')) {
+            hsm._tracePopDone(`found in state ${getStateName(unhandledLookupState)}`);
+            messageHandler = unhandledPrototype.onUnhandled;
+            break;
+        }
+        hsm._traceWrite(`not found in state ${getStateName(unhandledLookupState)}`);
+        unhandledLookupState = Object.getPrototypeOf(unhandledLookupState);
+        if (unhandledLookupState == TopState) {
+            hsm._tracePopDone(`found in state ${getStateName(unhandledLookupState)}`);
+            messageHandler = unhandledPrototype.onUnhandled;
+            break;
+        }
+    }
+    try {
+        hsm._tracePush('execute', 'started #onUnhandled handler execution');
+        const result = messageHandler.call(hsm._instance, error);
+        if (result) {
+            await result;
+        }
+        hsm._tracePopDone('unhandled handler execution successful');
+        await completePendingTransitions(hsm, resolver, () => {
+            hsm._tracePopDone('unhandled event recovery successful');
+            onComplete();
+        });
+    }
+    catch (recoveryErr) {
+        hsm._tracePopError(`unhandled event recovery failure: ${quoteUnknown(recoveryErr)}`);
+        if (recoveryErr instanceof TransitionError) {
+            hsm.currentState = FatalErrorState;
+            hsm._tracePopError(`unhandled event recovery failure: ${quoteUnknown(recoveryErr)}`);
+            throw recoveryErr;
+        }
+        try {
+            await verboseDoError(hsm, resolver, asError(recoveryErr), () => {
+                hsm._tracePopDone('unhandled event recovery successful');
+                onComplete();
+            });
+        }
+        catch (nestedErr) {
+            hsm._tracePopError(`unhandled event recovery failure: ${quoteUnknown(nestedErr)}`);
+            throw nestedErr;
+        }
+    }
+}
+async function dispatchEventVerbose(hsm, resolver, eventName, ...eventPayload) {
+    const eventLabel = String(eventName);
+    hsm._traceWrite(`begin event dispatch of #${eventLabel}`);
+    hsm._tracePush(`#${eventLabel}`, `started event dispatch`);
+    hsm._currentEventName = eventLabel;
+    hsm._currentEventPayload = eventPayload;
+    try {
+        const eventHandler = lookupEventHandler(hsm, eventName);
+        if (!eventHandler) {
+            hsm._traceWrite(`event #${eventLabel} is unhandled in state ${hsm.currentStateName}`);
+            try {
+                await verboseDoUnhandledEvent(hsm, resolver, new UnhandledEventError(hsm), () => {
+                    hsm._tracePopDone('event dispatch successful');
+                    verboseFinishEventDispatch(hsm);
+                });
+                return;
+            }
+            catch (recoveryErr) {
+                hsm._tracePopError(`event dispatch failed: ${quoteUnknown(recoveryErr)}`);
+                verboseFinishEventDispatch(hsm);
+                throw recoveryErr;
+            }
+        }
+        try {
+            hsm._tracePush('execute', 'started event handler execution');
+            const result = eventHandler.call(hsm._instance, ...eventPayload);
+            if (result) {
+                await result;
+            }
+            hsm._tracePopDone('event handler execution successful');
+            await completePendingTransitions(hsm, resolver, () => {
+                hsm._tracePopDone(`event dispatch successful`);
+                verboseFinishEventDispatch(hsm);
+            });
+        }
+        catch (recoveryErr) {
+            hsm._tracePopError(quoteUnknown(recoveryErr));
+            if (recoveryErr instanceof UnhandledEventError) {
+                hsm._traceWrite(`event #${eventLabel} is unhandled in state ${hsm.currentStateName}`);
+                try {
+                    await verboseDoUnhandledEvent(hsm, resolver, recoveryErr, () => {
+                        hsm._tracePopDone('event dispatch successful');
+                        verboseFinishEventDispatch(hsm);
+                    });
+                    return;
+                }
+                catch (nestedErr) {
+                    hsm._tracePopError(`event dispatch failed: ${quoteUnknown(nestedErr)}`);
+                    verboseFinishEventDispatch(hsm);
+                    throw nestedErr;
+                }
+            }
+            else if (recoveryErr instanceof TransitionError) {
+                hsm._tracePopError(`event dispatch failed: ${quoteUnknown(recoveryErr)}`);
+                verboseFinishEventDispatch(hsm);
+                throw recoveryErr;
+            }
+            else {
+                try {
+                    await verboseDoError(hsm, resolver, asError(recoveryErr), () => {
+                        hsm._tracePopDone('event dispatch successful');
+                        verboseFinishEventDispatch(hsm);
+                    });
+                }
+                catch (nestedErr) {
+                    hsm._tracePopError(`event dispatch failed: ${quoteUnknown(nestedErr)}`);
+                    verboseFinishEventDispatch(hsm);
+                    throw nestedErr;
+                }
+            }
+        }
+    }
+    catch (err) {
+        verboseFinishEventDispatch(hsm);
+        throw err;
+    }
+}
+const productionDispatchStrategy = {
+    executeInit: executeInitProduction,
+    dispatchEvent: dispatchEventProduction,
+};
+const debugDispatchStrategy = {
+    executeInit: executeInitDebug,
+    dispatchEvent: dispatchEventDebug,
+};
+const verboseDispatchStrategy = {
+    executeInit: executeInitVerbose,
+    dispatchEvent: dispatchEventVerbose,
+};
+function dispatchStrategyFor(traceLevel) {
+    switch (traceLevel) {
+        case TraceLevel.PRODUCTION:
+            return productionDispatchStrategy;
+        case TraceLevel.DEBUG:
+            return debugDispatchStrategy;
+        case TraceLevel.VERBOSE_DEBUG:
+            return verboseDispatchStrategy;
+    }
+}
+//#endregion
+/** @internal */
+function createInitTask(host, resolver) {
+    const strategy = dispatchStrategyFor(host.traceLevel);
+    return (done) => {
+        strategy
+            .executeInit(host)
+            .then(() => executePendingTransition(host, resolver))
+            .then(() => done())
+            .catch((err) => {
+            host.dispatchErrorCallback(host, asError(err));
+            done();
+        });
+    };
+}
+/** @internal */
+function createNotificationTask(host, resolver, name, args) {
+    const strategy = dispatchStrategyFor(host.traceLevel);
+    return (done) => {
+        strategy
+            .dispatchEvent(host, resolver, name, ...args)
+            .catch((err) => host.dispatchErrorCallback(host, asError(err)))
+            .finally(() => done());
+    };
+}
+/** @internal */
+function createServiceTask(host, resolver, name, args, resolve, reject) {
+    const machine = host;
+    return (done) => {
+        const run = () => invokeHandler(host, resolver, name, args)
+            .then(resolve)
+            .catch((err) => {
+            reject(asError(err));
+        })
+            .catch((err) => host.dispatchErrorCallback(host, asError(err)))
+            .finally(() => done());
+        if (host.traceLevel === TraceLevel.PRODUCTION) {
+            void run();
+            return;
+        }
+        const storage = exports.dispatchContext.get();
+        if (storage === undefined) {
+            void run();
+            return;
+        }
+        void storage.run({ machine }, run);
+    };
+}
+//#endregion
+//#region hsm
+/** @internal */
+class HsmObject {
+    topState;
+    topStateName;
+    ctxTypeName;
+    traceWriter;
+    /** @internal */
+    _instance;
+    /** @internal */
+    _jobs;
+    /** @internal */
+    _hiPriorityJobs;
+    _isRunning = false;
+    _transitionState;
+    _currentEventName;
+    _currentEventPayload;
+    _observers;
+    dispatchErrorCallback;
+    _traceLevel;
+    _traceDomainStack;
+    constructor(TopState, instance, traceWriter, traceLevel, dispatchErrorCallback) {
+        this._instance = instance;
+        this._transitionState = undefined;
+        this._traceLevel = traceLevel;
+        this._currentEventName = undefined;
+        this._currentEventPayload = undefined;
+        this._traceDomainStack = [];
+        this._jobs = [];
+        this._hiPriorityJobs = [];
+        this._isRunning = false;
+        this.topState = TopState;
+        this.topStateName = getStateName(TopState);
+        this.ctxTypeName = Object.getPrototypeOf(instance.ctx).constructor.name;
+        this.currentState = TopState;
+        this.traceWriter = traceWriter;
+        this.dispatchErrorCallback = dispatchErrorCallback;
+    }
+    get ctx() {
+        return this._instance.ctx;
+    }
+    set ctx(ctx) {
+        this._instance.ctx = ctx;
+    }
+    get port() {
+        return this._instance.portRef;
+    }
+    get eventName() {
+        return this._currentEventName ?? '';
+    }
+    get eventPayload() {
+        return this._currentEventPayload ?? [];
+    }
+    get currentStateName() {
+        return getStateName(Object.getPrototypeOf(this._instance).constructor);
+    }
+    get currentState() {
+        return Object.getPrototypeOf(this._instance).constructor;
+    }
+    set currentState(newState) {
+        Object.setPrototypeOf(this._instance, newState.prototype);
+    }
+    subscribe(observer) {
+        if (this._observers === undefined)
+            this._observers = new Set();
+        this._observers.add(observer);
+        return {
+            dispose: () => {
+                this._observers?.delete(observer);
+            },
+        };
+    }
+    _notifyObservers(eventName, eventPayload) {
+        if (this._observers === undefined || this._observers.size === 0)
+            return;
+        const message = { event: String(eventName), payload: [...eventPayload] };
+        for (const observer of this._observers)
+            observer(message);
+    }
+    recordObserverEvent(eventName, eventPayload) {
+        this._notifyObservers(eventName, eventPayload);
+    }
+    transition(nextState) {
+        this._transitionState = nextState;
+    }
+    unhandled() {
+        throw new UnhandledEventError(this);
+    }
+    get traceLevel() {
+        return this._traceLevel;
+    }
+    set traceLevel(traceLevel) {
+        this._traceLevel = traceLevel;
+    }
+    sync() {
+        return new Promise(resolve => {
+            this.pushTask((doneCallback) => {
+                resolve();
+                doneCallback();
+            });
+        });
+    }
+    pushTask(t) {
+        this.enqueueTask(t, this._jobs);
+    }
+    pushHiPriorityTask(t) {
+        this.enqueueTask(t, this._hiPriorityJobs);
+    }
+    unshiftHiPriorityTask(t) {
+        this._hiPriorityJobs.unshift(t);
+        if (this._isRunning)
+            return;
+        this._isRunning = true;
+        this.dequeue();
+    }
+    enqueueTask(t, queue) {
+        queue.push(t);
+        if (this._isRunning)
+            return;
+        this._isRunning = true;
+        this.dequeue();
+    }
+    restore(state, ctx) {
+        this.currentState = state;
+        this.ctx = ctx;
+    }
+    dequeue() {
+        if (this._hiPriorityJobs.length == 0 && this._jobs.length == 0) {
+            this._isRunning = false;
+            return;
+        }
+        const task = this._hiPriorityJobs.length > 0 ? this._hiPriorityJobs.shift() : this._jobs.shift();
+        this.exec(task);
+    }
+    exec(task) {
+        setTimeout(() => this.runTask(task).then(() => this.dequeue()), 0);
+    }
+    runTask(task) {
+        return new Promise(resolve => {
+            task(() => {
+                this.drainHiPriority().then(resolve);
+            });
+        });
+    }
+    drainHiPriority() {
+        if (this._hiPriorityJobs.length === 0) {
+            return Promise.resolve();
+        }
+        const task = this._hiPriorityJobs.shift();
+        return this.runTask(task).then(() => this.drainHiPriority());
+    }
+    _tracePush(d, msg) {
+        this._traceDomainStack.push(d);
+        this.traceWriter.write(this, msg);
+    }
+    _tracePopDone(msg) {
+        this.traceWriter.write(this, `done: ${msg}`);
+        this._traceDomainStack.pop();
+    }
+    _tracePopError(msg) {
+        this.traceWriter.write(this, `failure: ${msg}`);
+        this._traceDomainStack.pop();
+    }
+    _traceWrite(msg) {
+        this.traceWriter.write(this, msg);
+    }
+    get traceHeader() {
+        return `${this._traceDomainStack.length === 0 ? '' : this._traceDomainStack.join('|') + '|'}`;
+    }
+}
+exports.HsmObject = HsmObject;
+//#region machine
+class Machine extends HsmObject {
+    transitionResolver;
+    _dispatchStrategy;
+    protocolIndex;
+    handlerFacade;
+    selfActor;
+    selfImmediate;
+    actorFacades = new Map();
+    constructor(topState, instance, protocolIndex, traceWriter, traceLevel, dispatchErrorCallback, initialize, transitionResolver) {
+        super(topState, instance, traceWriter, traceLevel, dispatchErrorCallback);
+        Object.defineProperty(instance, types_1.kHandlerMachine, { value: this, enumerable: false, writable: false, configurable: false });
+        this.protocolIndex = protocolIndex;
+        cacheProtocolIndex(topState, protocolIndex);
+        this.transitionResolver = transitionResolver ?? new RuntimeTransitionResolver();
+        this._dispatchStrategy = dispatchStrategyFor(traceLevel);
+        this.selfActor = createSelfNotifications(this, topState, protocolIndex, 'default');
+        this.selfImmediate = createSelfNotifications(this, topState, protocolIndex, 'priority');
+        this.handlerFacade = this.buildHandlerFacade(instance);
+        instance.hsm = this.handlerFacade;
+        Object.defineProperty(instance, 'notify', { value: this.selfActor, enumerable: true, configurable: true });
+        Object.defineProperty(instance, 'notifyNow', { value: this.selfImmediate, enumerable: true, configurable: true });
+        this.bindPort(instance.portRef);
+        if (initialize) {
+            this.pushTask(createInitTask(this, this.transitionResolver));
+        }
+    }
+    get traceLevel() {
+        return super.traceLevel;
+    }
+    set traceLevel(traceLevel) {
+        super.traceLevel = traceLevel;
+        this._dispatchStrategy = dispatchStrategyFor(traceLevel);
+    }
+    dispatchService(name, args) {
+        if (this.traceLevel !== TraceLevel.PRODUCTION) {
+            const storage = exports.dispatchContext.get();
+            const token = storage?.getStore();
+            if (token?.machine === this) {
+                throw new SelfCallDeadlockError();
+            }
+        }
+        this.recordObserverEvent(name, args);
+        return new Promise((resolve, reject) => {
+            this.pushTask(createServiceTask(this, this.transitionResolver, name, args, resolve, reject));
+        });
+    }
+    dispatchNotification(name, args, queue) {
+        this.recordObserverEvent(name, args);
+        const task = createNotificationTask(this, this.transitionResolver, name, args);
+        if (queue === 'priority') {
+            this.pushHiPriorityTask(task);
+        }
+        else {
+            this.pushTask(task);
+        }
+    }
+    actorHsmFor(kind) {
+        let facade = this.actorFacades.get(kind);
+        if (facade === undefined) {
+            facade = this.buildActorHsm(kind);
+            this.actorFacades.set(kind, facade);
+        }
+        return facade;
+    }
+    scheduleNotification(ms, name, args) {
+        const enqueue = () => {
+            this.dispatchNotification(name, args, 'default');
+        };
+        const port = this._instance.portRef;
+        if (port === undefined) {
+            throw new Error('ihsm: deferred notification requires a port');
+        }
+        port.setTimeout(enqueue, ms);
+    }
+    /** @internal Binds deferred self-notifications to a port instance. */
+    bindPort(portRef) {
+        if (portRef instanceof Port) {
+            portRef.bindDeferredNotifications(ms => this.createDeferredSelfNotifications(ms));
+        }
+    }
+    buildHandlerFacade(instance) {
+        const machine = this;
+        const facade = {
+            get ctx() {
+                return machine.ctx;
+            },
+            transition: next => machine.transition(next),
+            get port() {
+                return instance.portRef;
+            },
+            unhandled: () => machine.unhandled(),
+            get eventName() {
+                return machine.eventName;
+            },
+            get eventPayload() {
+                return machine.eventPayload;
+            },
+            get currentState() {
+                return machine.currentState;
+            },
+            get currentStateName() {
+                return machine.currentStateName;
+            },
+            get topState() {
+                return machine.topState;
+            },
+            get topStateName() {
+                return machine.topStateName;
+            },
+            get traceHeader() {
+                return machine.traceHeader;
+            },
+            get traceLevel() {
+                return machine.traceLevel;
+            },
+            set traceLevel(level) {
+                machine.traceLevel = level;
+            },
+            get traceWriter() {
+                return machine.traceWriter;
+            },
+            set traceWriter(writer) {
+                machine.traceWriter = writer;
+            },
+            get dispatchErrorCallback() {
+                return machine.dispatchErrorCallback;
+            },
+            set dispatchErrorCallback(cb) {
+                machine.dispatchErrorCallback = cb;
+            },
+        };
+        return facade;
+    }
+    createDeferredSelfNotifications(ms) {
+        const machine = this;
+        const proto = Object.create(null);
+        for (const [name, slot] of this.protocolIndex.entries('inbound')) {
+            if (slot.bucket === 'notifications' || slot.bucket === 'internalNotifications') {
+                proto[name] = (...args) => {
+                    machine.scheduleNotification(ms, name, args);
+                };
+            }
+        }
+        for (const [name, slot] of this.protocolIndex.entries('root')) {
+            if (slot.bucket === 'notifications') {
+                proto[name] = (...args) => {
+                    machine.scheduleNotification(ms, name, args);
+                };
+            }
+        }
+        return Object.create(Object.freeze(proto));
+    }
+    buildActorHsm(kind) {
+        const machine = this;
+        const includeState = kind !== 'root';
+        const includeOwner = kind === 'child' || kind === 'test';
+        const facade = {
+            sync: () => machine.sync(),
+            get currentStateName() {
+                return machine.currentStateName;
+            },
+            get topStateName() {
+                return machine.topStateName;
+            },
+            get traceLevel() {
+                return machine.traceLevel;
+            },
+            set traceLevel(level) {
+                machine.traceLevel = level;
+            },
+            get traceWriter() {
+                return machine.traceWriter;
+            },
+            set traceWriter(writer) {
+                machine.traceWriter = writer;
+            },
+            get traceHeader() {
+                return machine.traceHeader;
+            },
+        };
+        if (includeState) {
+            Object.defineProperties(facade, {
+                currentState: {
+                    enumerable: true,
+                    get() {
+                        return machine.currentState;
+                    },
+                },
+                topState: {
+                    enumerable: true,
+                    get() {
+                        return machine.topState;
+                    },
+                },
+            });
+        }
+        if (includeOwner) {
+            Object.defineProperties(facade, {
+                restore: {
+                    enumerable: true,
+                    value: (state, ctx) => machine.restore(state, ctx),
+                },
+                dispatchErrorCallback: {
+                    enumerable: true,
+                    get() {
+                        return machine.dispatchErrorCallback;
+                    },
+                    set(cb) {
+                        machine.dispatchErrorCallback = cb;
+                    },
+                },
+            });
+        }
+        return facade;
+    }
+}
+exports.Machine = Machine;
+//#region factories
+function isRequestingPort(port) {
+    if (port === null || typeof port !== 'object') {
+        return false;
+    }
+    const ctor = Object.getPrototypeOf(port)?.constructor;
+    if (ctor === undefined) {
+        return false;
+    }
+    return ctor[kRequestingPort] === true;
+}
+class ConsoleTraceWriter {
+    write(hsm, msg) {
+        if (typeof msg === 'string') {
+            console.log(`${hsm.traceHeader}${hsm.currentStateName}: ${msg}`);
+        }
+        else {
+            console.log(msg);
+        }
+    }
+}
+/** @internal */
+exports.defaultTraceWriter = new ConsoleTraceWriter();
+/** @internal */
+exports.defaultInitialize = true;
+/** @internal */
+function defaultDispatchErrorCallback(hsm, err) {
+    hsm.traceWriter.write(hsm, `An event dispatch has failed; error ${err.name}: ${err.message} has not been managed`);
+    hsm.traceWriter.write(hsm, err);
+    throw err;
+}
+/** @internal Spawn with embodiment kind — used by factories and `ihsm/testing`. */
+function spawnActor(kind, topState, ctx, port, options) {
+    const { initialize = exports.defaultInitialize, traceLevel = TraceLevel.DEBUG, traceWriter = exports.defaultTraceWriter, dispatchErrorCallback = defaultDispatchErrorCallback, transitions } = options;
+    const protocolIndex = buildProtocolIndex(topState);
+    const boundPort = (port ?? new Port());
+    const instance = {
+        ctx,
+        hsm: undefined,
+        portRef: boundPort,
+    };
+    Object.setPrototypeOf(instance, topState.prototype);
+    const machine = new Machine(topState, instance, protocolIndex, traceWriter, traceLevel, dispatchErrorCallback, initialize, transitions ?? new RuntimeTransitionResolver());
+    const portKind = isRequestingPort(boundPort) ? 'child' : kind === 'root' ? 'inbound' : kind;
+    boundPort.actor = createActorHandle(machine, topState, protocolIndex, portKind);
+    return createActorHandle(machine, topState, protocolIndex, kind);
+}
+/** Production black-box — public protocol only (generated handle). */
+function makeActor(topState, ctx, port, options = {}) {
+    return spawnActor('root', topState, ctx, port, options);
+}
+function asParentActor(handler) {
+    const machine = handler[types_1.kHandlerMachine];
+    if (machine === undefined) {
+        throw new Error('ihsm: asParentActor requires an active handler machine');
+    }
+    return {
+        top: machine.topState,
+        [types_1.kParentLink]: machine,
+    };
+}
+/** Parent composes a child machine — returns full child protocol shell with `parent` set. */
+function makeChildActor(parent, childTop, childCtx, port, options = {}) {
+    const child = spawnActor('child', childTop, childCtx, port, options);
+    Object.defineProperty(child, 'parent', { value: parent, enumerable: true, writable: false, configurable: true });
+    return child;
+}
+var types_2 = require("./types");
+Object.defineProperty(exports, "kHandlerMachine", { enumerable: true, get: function () { return types_2.kHandlerMachine; } });
+Object.defineProperty(exports, "kParentLink", { enumerable: true, get: function () { return types_2.kParentLink; } });
+//# sourceMappingURL=runtime.js.map