ihsm 0.0.26 → 0.1.21

package/lib/esm/internal/runtime.js

@@ -0,0 +1,2462 @@
+import { kHandlerMachine, kParentLink } from './types.js';
+import { actorNameFromTopState, childActorPath, mintActorIdentity, rootActorPath } from './identity.js';
+import { getActiveInstrumentation, getTaskMeta, notifyActorCreated, notifyActorSpawned, notifyEnqueue, notifyError, notifyLog, notifyMacrostepBegin, notifyMacrostepEnd, notifyMicrostepBegin, notifyMicrostepEnd, notifyOutboundCallBegin, notifyOutboundCallEnd, notifyPortCallBegin, notifyPortCallEnd, setTaskMeta } from './instrumentation.js';
+//#region TraceLevel
+export var TraceLevel;
+(function (TraceLevel) {
+    TraceLevel[TraceLevel["PRODUCTION"] = 0] = "PRODUCTION";
+    TraceLevel[TraceLevel["DEBUG"] = 1] = "DEBUG";
+    TraceLevel[TraceLevel["VERBOSE_DEBUG"] = 2] = "VERBOSE_DEBUG";
+})(TraceLevel || (TraceLevel = {}));
+//#endregion
+//#region utils
+/** @internal */
+export function asError(err) {
+    return err instanceof Error ? err : new Error(String(err));
+}
+/** @internal */
+export function quoteUnknown(err) {
+    return quoteError(asError(err));
+}
+/** @internal */
+export function quoteError(err) {
+    return `${err.name}${err.message ? `: ${err.message}` : ' with no error message'}`;
+}
+/** @internal */
+export function getInitialState(State) {
+    return State._initialState;
+}
+/** @internal */
+export function hasInitialState(State) {
+    return Object.prototype.hasOwnProperty.call(State, '_initialState');
+}
+/** @internal */
+export function getTransitionKey(FromState, ToState) {
+    return `${getStateName(FromState)}=>${getStateName(ToState)}`;
+}
+export 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. */
+export 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. */
+export 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);
+    }
+}
+const kRequestingPort = Symbol('ihsm.requestingPort');
+export class RequestingPort extends Port {
+}
+RequestingPort[kRequestingPort] = true;
+//#endregion
+//#region Errors
+export 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;
+    }
+}
+export 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;
+    }
+}
+export class RuntimeError extends HsmError {
+    eventName;
+    eventPayload;
+    constructor(errorName, hsm, message, cause) {
+        super(errorName, hsm, message, cause);
+        this.eventName = hsm.eventName;
+        this.eventPayload = hsm.eventPayload;
+    }
+}
+export 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;
+    }
+}
+export 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);
+    }
+}
+export class UnhandledEventError extends RuntimeError {
+    constructor(hsm) {
+        super('UnhandledEventError', hsm, `event #${hsm.eventName} was unhandled in state ${hsm.currentStateName}`);
+    }
+}
+export 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);
+    }
+}
+export class FatalError extends RuntimeError {
+    constructor(hsm, cause) {
+        super('FatalError', hsm, `onError() has thrown ${quoteError(cause)}`, cause);
+    }
+}
+export 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;
+    }
+}
+export class FatalErrorState extends TopState {
+}
+defineStateName(TopState, 'TopState');
+defineStateName(FatalErrorState, 'FatalErrorState');
+/** @internal */
+export function lookupHandlerState(hsm, eventName) {
+    let state = hsm.currentState;
+    while (true) {
+        const prototype = state.prototype;
+        if (Object.prototype.hasOwnProperty.call(prototype, eventName)) {
+            return getStateName(state);
+        }
+        if (state === TopState) {
+            return undefined;
+        }
+        state = Object.getPrototypeOf(state);
+    }
+}
+/** @internal */
+export 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);
+    }
+}
+export 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,
+    });
+}
+export 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. */
+export 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: ${ReservedNames.join(', ')}`, stateClass, symbol);
+    }
+}
+//#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. */
+export 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];
+    }
+}
+//#endregion
+//#region Protocol index cache
+const indexByRoot = new WeakMap();
+export function cacheProtocolIndex(topState, index) {
+    indexByRoot.set(topState, index);
+    return index;
+}
+export function protocolIndexFor(topState) {
+    return indexByRoot.get(topState);
+}
+//#endregion
+//#region Protocol index
+const reservedSet = new Set(['ctx', 'hsm', 'notify', 'notifyNow', 'onEntry', 'onExit', 'onError', 'onUnhandled']);
+export const 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). */
+export 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 }`. */
+export class CallTimeoutError extends Error {
+    method;
+    // prettier-ignore
+    constructor(method) {
+        super(`ihsm: service "${method}" timed out`);
+        this.method = method;
+        this.name = 'CallTimeoutError';
+    }
+}
+export const kMachine = Symbol('ihsm.machine');
+export 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);
+}
+export 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 };
+}
+/**
+ * Race a service-call promise against a `timeoutMs` deadline.
+ *
+ * The deadline is armed through `timer` — the actor's port timer service — so that under a
+ * {@link TestPort} virtual clock a call timeout is driven by `port.advance(...)` and stays
+ * fully deterministic. When no port timer is available the host timer is used (production
+ * `Port` already delegates to the host timer, so behaviour there is unchanged).
+ */
+export function serviceCallWithTimeout(promise, method, timeoutMs, timer) {
+    if (timeoutMs === 0) {
+        return Promise.reject(new CallTimeoutError(method));
+    }
+    const arm = (callback) => (timer !== undefined ? timer.setTimeout(callback, timeoutMs) : globalThis.setTimeout(callback, timeoutMs));
+    const disarm = (handle) => (timer !== undefined ? timer.clearTimeout(handle) : globalThis.clearTimeout(handle));
+    return new Promise((resolve, reject) => {
+        const handle = arm(() => {
+            reject(new CallTimeoutError(method));
+        });
+        promise.then(value => {
+            disarm(handle);
+            resolve(value);
+        }, err => {
+            disarm(handle);
+            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 machine = this[kMachine];
+                    const begin = machine.beginOutboundCall?.(name, machine.actorUuid);
+                    const promise = machine.dispatchService(name, callArgs).then(value => {
+                        machine.endOutboundCall?.(begin, 'ok');
+                        return value;
+                    }, cause => {
+                        const err = asError(cause);
+                        machine.endOutboundCall?.(begin, 'error', err);
+                        throw err;
+                    });
+                    return timeoutMs === undefined ? promise : serviceCallWithTimeout(promise, name, timeoutMs, machine.callTimer);
+                };
+            }
+            else {
+                built[name] = function (...args) {
+                    this[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, kMachine, { value: machine, enumerable: false });
+    return facetHandle;
+}
+/** @internal */
+export 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, 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 });
+    Object.defineProperty(handle, 'id', {
+        enumerable: true,
+        get() {
+            return machine.actorUuid;
+        },
+    });
+    handle.hsm = machine.actorHsmFor(kind);
+    return handle;
+}
+const selfProtoCache = new WeakMap();
+/** @internal */
+export 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[kMachine].dispatchNotification(name, args, queue);
+            };
+        }
+        proto = Object.freeze(built);
+        map.set(queue, proto);
+    }
+    return proto;
+}
+export function createSelfNotifications(machine, topState, index, queue) {
+    const handle = Object.create(getSelfNotificationsProto(topState, index, queue));
+    Object.defineProperty(handle, 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. */
+export class SelfCallDeadlockError extends Error {
+    constructor() {
+        super('ihsm: awaiting a service on your own machine from inside your own dispatch deadlocks');
+        this.name = 'SelfCallDeadlockError';
+    }
+}
+function errorPhaseFromError(err) {
+    if (err instanceof TransitionError) {
+        return err.failedCallback === 'onEntry' ? 'onEntry' : 'onExit';
+    }
+    if (err instanceof UnhandledEventError)
+        return 'unhandled';
+    if (err instanceof InitializationError)
+        return 'initialize';
+    if (err instanceof EventHandlerError)
+        return 'handler';
+    return 'handler';
+}
+/**
+ * Lazy Node AsyncLocalStorage for non-production deadlock detection.
+ * State lives in a closure — no exported mutable slot.
+ */
+export const 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 };
+})();
+/**
+ * Best-effort current runtime trace anchor (`actorUuid`, `macrostepId`, `stepSeq`) for user code.
+ * Returns `undefined` when called outside an active handler dispatch turn.
+ */
+export function currentTraceAnchor() {
+    const token = dispatchContext.get()?.getStore();
+    if (token?.actorUuid === undefined)
+        return undefined;
+    return {
+        actorUuid: token.actorUuid,
+        macrostepId: token.macrostepId,
+        stepSeq: token.stepSeq,
+    };
+}
+/** Lazy ALS carrying the currently-executing proxied port call (when instrumentation is active). */
+const portCallContext = (() => {
+    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 — keeps browser bundles free of `node:async_hooks`.
+            // 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;
+        }
+    }
+    return { get };
+})();
+//#region transition-routines
+/** Thrown when a generated transition table's graph hash does not match the scanned hierarchy. */
+export class TransitionTableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TransitionTableError';
+    }
+}
+/** Compute the LCA transition path (same algorithm as `dispatch.production.ts`). */
+export 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, hookEvents) {
+    const statePrototype = state.prototype;
+    const stateName = getStateName(state);
+    const hasHook = Object.prototype.hasOwnProperty.call(statePrototype, hook);
+    // Emit hook tracer callbacks for real (own) hooks at verbose, or always for a structural seam
+    // (instrumentation) whose entry/exit spans are not TraceLevel-gated (spec §4.8). Skipped default
+    // hooks are never eventized.
+    const emitHookEvents = (style === 'verbose' || hookEvents) && hasHook;
+    if ((style === 'verbose' || style === 'debug') && !hasHook) {
+        if (style === 'verbose') {
+            tracer?.traceHookSkipped(stateName, hook);
+        }
+        return;
+    }
+    try {
+        if (emitHookEvents) {
+            tracer?.traceHookStart?.(stateName, hook);
+        }
+        const res = statePrototype[hook].call(instance);
+        if (res) {
+            await res;
+        }
+        if (emitHookEvents) {
+            tracer?.traceHookDone(stateName, hook);
+        }
+    }
+    catch (cause) {
+        if (emitHookEvents) {
+            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.
+ */
+export async function executeTransitionRoutine(hsm, instance, plan, srcState, dstState, options = {}) {
+    const style = options.style ?? 'production';
+    const tracer = options.tracer;
+    const hookEvents = options.hookEvents ?? false;
+    const fromStateName = getStateName(srcState);
+    const toStateName = getStateName(dstState);
+    // The structural transition span fires whenever a tracer is attached (the instrumentation seam is
+    // not TraceLevel-gated); the console tracer is only ever supplied off-PRODUCTION, so this is a
+    // no-op there unless an explicit instrumentation tracer is present.
+    tracer?.traceTransitionStart(fromStateName, toStateName);
+    for (const state of plan.exit) {
+        await invokeLifecycleHook(hsm, instance, state, 'onExit', fromStateName, toStateName, style, tracer, hookEvents);
+    }
+    let initializeOpened = false;
+    for (const state of plan.entry) {
+        if (!initializeOpened && state !== dstState) {
+            tracer?.traceInitializeStart?.(toStateName);
+            initializeOpened = true;
+        }
+        await invokeLifecycleHook(hsm, instance, state, 'onEntry', fromStateName, toStateName, style, tracer, hookEvents);
+    }
+    if (initializeOpened) {
+        const finalName = plan.finalState !== undefined ? getStateName(plan.finalState) : toStateName;
+        tracer?.traceInitializeDone?.(finalName);
+    }
+    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);
+        // Close the structural transition span on the PRODUCTION path (verbose/debug returned above).
+        tracer?.traceTransitionDone(getStateName(plan.finalState));
+    }
+}
+export function createTransitionTracer(hsm) {
+    return {
+        traceTransitionStart(fromStateName, toStateName) {
+            hsm._tracePush(`transition from ${fromStateName} to ${toStateName}`, `started transition from ${fromStateName} to ${toStateName} `);
+        },
+        traceInitializeStart(stateName) {
+            hsm._tracePush(`initialize ${stateName}`, `started initialize drill-down from ${stateName}`);
+        },
+        traceInitializeDone(finalStateName) {
+            hsm._tracePopDone(`done initialize drill-down at ${finalStateName}`);
+        },
+        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). */
+export 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';
+        const machine = hsm;
+        const instTracer = machine.instrumentation?.transition;
+        const tracer = instTracer ?? (style !== 'production' ? createTransitionTracer(hsm) : undefined);
+        await executeTransitionRoutine(hsm, hsm._instance, this.plan, srcState, dstState, {
+            style,
+            ...(tracer !== undefined ? { tracer } : {}),
+            // The instrumentation seam's entry/exit spans are structural (not TraceLevel-gated); the
+            // console tracer keeps its verbose-only gating.
+            hookEvents: instTracer !== undefined,
+            setCurrentState: state => {
+                hsm.currentState = state;
+            },
+        });
+    }
+}
+export 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;
+    }
+}
+/** @internal */
+export 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 */
+export function createInitTask(host, resolver) {
+    const strategy = dispatchStrategyFor(host.traceLevel);
+    return (done) => {
+        strategy
+            .executeInit(host)
+            .then(() => executePendingTransition(host, resolver))
+            .then(() => done())
+            .catch((err) => {
+            host.reportDispatchError(asError(err));
+            done();
+        });
+    };
+}
+/**
+ * Run a dispatch body inside the ambient `dispatchContext` token so that any `notify`/`call`/timer
+ * the handler issues can be attributed to the running `(macrostepId, stepSeq)` (CORE-B, §5.6.3).
+ * Falls back to a plain run when no ALS is available (browser) or the host predates the seam.
+ */
+function runWithinDispatch(host, run) {
+    const machine = host;
+    const wants = machine.needsDispatchContext?.() ?? host.traceLevel !== TraceLevel.PRODUCTION;
+    if (!wants) {
+        run();
+        return;
+    }
+    const storage = dispatchContext.get();
+    if (storage === undefined) {
+        run();
+        return;
+    }
+    const token = machine.buildDispatchToken?.() ?? { machine: host };
+    storage.run(token, run);
+}
+function currentPortCallToken() {
+    const storage = portCallContext.get();
+    return storage?.getStore();
+}
+/** @internal */
+export function createNotificationTask(host, resolver, name, args) {
+    const strategy = dispatchStrategyFor(host.traceLevel);
+    return (done) => {
+        runWithinDispatch(host, () => {
+            void strategy
+                .dispatchEvent(host, resolver, name, ...args)
+                .catch((err) => host.reportDispatchError(asError(err)))
+                .finally(() => done());
+        });
+    };
+}
+/** @internal */
+export function createServiceTask(host, resolver, name, args, resolve, reject) {
+    return (done) => {
+        const run = () => invokeHandler(host, resolver, name, args)
+            .then(resolve)
+            .catch((err) => {
+            reject(asError(err));
+        })
+            .catch((err) => host.reportDispatchError(asError(err)))
+            .finally(() => done());
+        runWithinDispatch(host, () => {
+            void run();
+        });
+    };
+}
+//#endregion
+//#region hsm
+/** @internal */
+export class HsmObject {
+    topState;
+    topStateName;
+    ctxTypeName;
+    traceWriter;
+    actorUuid;
+    actorName;
+    actorPath;
+    /** @internal */
+    _instance;
+    /** @internal */
+    _jobs;
+    /** @internal */
+    _hiPriorityJobs;
+    _isRunning = false;
+    _transitionState;
+    _currentEventName;
+    _currentEventPayload;
+    _observers;
+    dispatchErrorCallback;
+    _traceLevel;
+    _traceDomainStack;
+    _instrumentationHost;
+    _drainWaiters = [];
+    constructor(TopState, instance, traceWriter, traceLevel, dispatchErrorCallback, identity) {
+        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.actorUuid = identity.uuid;
+        this.actorName = identity.name;
+        this.actorPath = identity.path;
+        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;
+    }
+    /** The bound port when it provides a timer service, so service-call timeouts honour a virtual clock. */
+    get callTimer() {
+        const port = this._instance.portRef;
+        if (port !== undefined && typeof port.setTimeout === 'function' && typeof port.clearTimeout === 'function') {
+            return port;
+        }
+        return undefined;
+    }
+    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;
+    }
+    /**
+     * Resolve when the actor next reaches stability (mailbox fully drained).
+     *
+     * The resolver fires at the queue-drain point — *after* {@link InstrumentationHost.onQueuesDrained}
+     * — so the closing `macrostep.end` and the macrostep-boundary reset are observable before `sync()`
+     * resolves, and a subsequent external stimulus deterministically starts its own macrostep. The
+     * pushed task is a no-op (internal) whose only purpose is to guarantee a drain cycle occurs.
+     */
+    sync() {
+        return new Promise(resolve => {
+            this._drainWaiters.push(resolve);
+            const task = (doneCallback) => {
+                doneCallback();
+            };
+            setTaskMeta(task, { internal: true });
+            this.pushTask(task);
+        });
+    }
+    /** Invoke the user dispatch-error callback, first notifying instrumentation (pure observer). */
+    reportDispatchError(err) {
+        this._instrumentationHost?.onDispatchError(err);
+        this.dispatchErrorCallback(this, err);
+    }
+    flushDrainWaiters() {
+        if (this._drainWaiters.length === 0)
+            return;
+        const waiters = this._drainWaiters;
+        this._drainWaiters = [];
+        for (const resolve of waiters)
+            resolve();
+    }
+    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;
+            this._instrumentationHost?.onQueuesDrained();
+            this.flushDrainWaiters();
+            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) {
+        this._instrumentationHost?.onTaskBegin(task);
+        let outcome = 'ok';
+        return new Promise(resolve => {
+            const runBody = () => {
+                task(() => {
+                    this.drainHiPriority()
+                        .then(() => {
+                        this._instrumentationHost?.onTaskEnd(task, outcome);
+                        resolve();
+                    })
+                        .catch((_err) => {
+                        outcome = 'error';
+                        this._instrumentationHost?.onTaskEnd(task, outcome);
+                        resolve();
+                    });
+                });
+            };
+            try {
+                runBody();
+            }
+            catch (err) {
+                outcome = 'error';
+                this._instrumentationHost?.onTaskEnd(task, outcome);
+                resolve();
+                throw asError(err);
+            }
+        });
+    }
+    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('|') + '|'}`;
+    }
+    get traceFrames() {
+        return this._traceDomainStack.map(name => ({ name, kind: classifyFrameKind(name) }));
+    }
+}
+/** Best-effort classification of a live trace-domain name into a structured {@link TraceFrame.kind}. */
+function classifyFrameKind(name) {
+    if (name.startsWith('#'))
+        return 'event';
+    if (name === 'execute')
+        return 'handler';
+    if (name === 'initialize' || name.startsWith('initialize'))
+        return 'initialize';
+    if (name.startsWith('transition'))
+        return 'transition';
+    if (name.includes('onEntry'))
+        return 'onEntry';
+    if (name.includes('onExit'))
+        return 'onExit';
+    return 'handler';
+}
+//#region machine
+export class Machine extends HsmObject {
+    transitionResolver;
+    identity;
+    instrumentation;
+    _dispatchStrategy;
+    protocolIndex;
+    handlerFacade;
+    selfActor;
+    selfImmediate;
+    actorFacades = new Map();
+    _macrostepCounter = 0;
+    _currentMacrostep;
+    _microstepFromState;
+    _childSpawnCounters = new Map();
+    _nextTraceCallId = 0;
+    _proxiedPort;
+    constructor(topState, instance, protocolIndex, traceWriter, traceLevel, dispatchErrorCallback, initialize, identity, instrumentation, transitionResolver) {
+        super(topState, instance, traceWriter, traceLevel, dispatchErrorCallback, identity);
+        this.identity = identity;
+        this.instrumentation = instrumentation;
+        if (instrumentation !== undefined) {
+            this._instrumentationHost = this;
+            notifyActorCreated(instrumentation, identity);
+        }
+        Object.defineProperty(instance, 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) {
+            const initTask = createInitTask(this, this.transitionResolver);
+            setTaskMeta(initTask, { event: 'initialize', queue: 'default', triggerKind: 'init', internal: false });
+            this.pushTask(initTask);
+        }
+    }
+    allocateChildSpawnIndex(childTopName) {
+        const childName = actorNameFromTopState(childTopName);
+        const index = this._childSpawnCounters.get(childName) ?? 0;
+        this._childSpawnCounters.set(childName, index + 1);
+        return index;
+    }
+    needsDispatchContext() {
+        return this.instrumentation !== undefined || this.traceLevel !== TraceLevel.PRODUCTION;
+    }
+    buildDispatchToken() {
+        return {
+            machine: this,
+            actorUuid: this.actorUuid,
+            macrostepId: this._currentMacrostep?.id,
+            stepSeq: this._currentMacrostep?.stepSeq,
+        };
+    }
+    readDispatchCause(kind) {
+        const storage = dispatchContext.get();
+        const token = storage?.getStore();
+        if (token?.actorUuid === undefined)
+            return undefined;
+        return {
+            actorUuid: token.actorUuid,
+            macrostepId: token.macrostepId,
+            stepSeq: token.stepSeq,
+            kind,
+        };
+    }
+    nextTraceCallId() {
+        this._nextTraceCallId += 1;
+        return this._nextTraceCallId;
+    }
+    beginPortCall(method) {
+        if (this.instrumentation === undefined)
+            return undefined;
+        const cause = this.readDispatchCause('wire');
+        const info = {
+            callId: this.nextTraceCallId(),
+            method,
+            cause,
+        };
+        notifyPortCallBegin(this.instrumentation, info);
+        return info;
+    }
+    endPortCall(begin, outcome, error) {
+        if (this.instrumentation === undefined || begin === undefined)
+            return;
+        const info = {
+            callId: begin.callId,
+            method: begin.method,
+            outcome,
+            error,
+        };
+        notifyPortCallEnd(this.instrumentation, info);
+    }
+    beginOutboundCall(service, targetUuid) {
+        if (this.instrumentation === undefined)
+            return undefined;
+        const portToken = currentPortCallToken();
+        const cause = this.readDispatchCause('wire') ?? portToken?.cause;
+        const info = {
+            callId: this.nextTraceCallId(),
+            service,
+            targetUuid,
+            cause,
+        };
+        notifyOutboundCallBegin(this.instrumentation, info);
+        return info;
+    }
+    endOutboundCall(begin, outcome, error) {
+        if (this.instrumentation === undefined || begin === undefined)
+            return;
+        const info = {
+            callId: begin.callId,
+            service: begin.service,
+            outcome,
+            error,
+        };
+        notifyOutboundCallEnd(this.instrumentation, info);
+    }
+    slotBucket(eventName) {
+        return this.protocolIndex.get(eventName)?.bucket ?? 'notifications';
+    }
+    onTaskBegin(task) {
+        const meta = getTaskMeta(task);
+        if (meta?.internal === true || this.instrumentation === undefined)
+            return;
+        if (this._currentMacrostep === undefined) {
+            const id = `${this.actorUuid}:${++this._macrostepCounter}`;
+            const trigger = meta?.event ?? 'unknown';
+            const triggerKind = meta?.triggerKind ?? (this._jobs.length + this._hiPriorityJobs.length > 0 ? 'self' : 'external');
+            this._currentMacrostep = {
+                id,
+                trigger,
+                triggerKind,
+                startState: this.currentStateName,
+                stepSeq: -1,
+                transitioned: false,
+                outcome: 'ok',
+                cause: meta?.cause,
+            };
+            notifyMacrostepBegin(this.instrumentation, {
+                id,
+                actor: this.identity,
+                trigger,
+                triggerKind,
+                startState: this.currentStateName,
+                cause: meta?.cause,
+                delayMs: meta?.delayMs,
+            });
+        }
+        const macrostep = this._currentMacrostep;
+        macrostep.stepSeq += 1;
+        const seq = macrostep.stepSeq;
+        const fromState = this.currentStateName;
+        this._microstepFromState = fromState;
+        // Stamp seq + fromState on the task so onTaskEnd pairs correctly even when nested priority
+        // drains mutate the shared macrostep counter between this task's begin and end.
+        if (meta !== undefined) {
+            meta.seq = seq;
+            meta.fromState = fromState;
+        }
+        else {
+            setTaskMeta(task, { seq, fromState });
+        }
+        const eventName = meta?.event ?? this.eventName ?? 'unknown';
+        const handlerState = lookupHandlerState(this, eventName);
+        const storage = dispatchContext.get();
+        const runMicrostep = () => {
+            notifyMicrostepBegin(this.instrumentation, {
+                macrostepId: macrostep.id,
+                seq,
+                event: eventName,
+                bucket: this.slotBucket(eventName),
+                queue: meta?.queue ?? 'default',
+                fromState: this.currentStateName,
+                handlerState,
+                cause: meta?.cause,
+            });
+        };
+        if (storage !== undefined && this.needsDispatchContext()) {
+            storage.run(this.buildDispatchToken(), runMicrostep);
+        }
+        else {
+            runMicrostep();
+        }
+    }
+    onTaskEnd(task, outcome) {
+        const meta = getTaskMeta(task);
+        if (meta?.internal === true || this.instrumentation === undefined || this._currentMacrostep === undefined)
+            return;
+        const macrostep = this._currentMacrostep;
+        const fromState = meta?.fromState ?? this._microstepFromState ?? macrostep.startState;
+        const seq = meta?.seq ?? macrostep.stepSeq;
+        const transitioned = this.currentStateName !== fromState;
+        if (transitioned)
+            macrostep.transitioned = true;
+        if (outcome === 'error')
+            macrostep.outcome = 'error';
+        notifyMicrostepEnd(this.instrumentation, {
+            macrostepId: macrostep.id,
+            seq,
+            toState: this.currentStateName,
+            transitioned,
+            async: false,
+            outcome,
+        });
+    }
+    onDispatchError(err) {
+        if (this.instrumentation === undefined)
+            return;
+        notifyError(this.instrumentation, {
+            phase: errorPhaseFromError(err),
+            errorClass: err.name,
+            error: err,
+            recovered: false,
+        });
+    }
+    onQueuesDrained() {
+        if (this.instrumentation === undefined || this._currentMacrostep === undefined)
+            return;
+        const macrostep = this._currentMacrostep;
+        notifyMacrostepEnd(this.instrumentation, {
+            id: macrostep.id,
+            endState: this.currentStateName,
+            steps: macrostep.stepSeq + 1,
+            transitioned: macrostep.transitioned,
+            outcome: macrostep.outcome,
+        });
+        this._currentMacrostep = undefined;
+    }
+    resolveEnqueueCause() {
+        const inherited = this.readDispatchCause('message');
+        if (inherited === undefined) {
+            return { actorUuid: this.actorUuid, kind: 'cause' };
+        }
+        if (inherited.actorUuid !== this.actorUuid) {
+            return inherited;
+        }
+        return { ...inherited, kind: 'cause' };
+    }
+    enqueueWithInstrumentation(task, event, queue, triggerKind) {
+        const cause = this.resolveEnqueueCause();
+        setTaskMeta(task, { event, queue, cause, triggerKind });
+        notifyEnqueue(this.instrumentation, {
+            event,
+            queue,
+            cause,
+            targetUuid: this.actorUuid,
+        });
+        if (queue === 'priority') {
+            this.pushHiPriorityTask(task);
+        }
+        else {
+            this.pushTask(task);
+        }
+    }
+    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 = dispatchContext.get();
+            const token = storage?.getStore();
+            if (token?.machine === this) {
+                throw new SelfCallDeadlockError();
+            }
+        }
+        this.recordObserverEvent(name, args);
+        return new Promise((resolve, reject) => {
+            const task = createServiceTask(this, this.transitionResolver, name, args, resolve, reject);
+            if (this.instrumentation !== undefined) {
+                this.enqueueWithInstrumentation(task, name, 'default', 'call');
+                return;
+            }
+            this.pushTask(task);
+        });
+    }
+    dispatchNotification(name, args, queue) {
+        this.recordObserverEvent(name, args);
+        const task = createNotificationTask(this, this.transitionResolver, name, args);
+        if (this.instrumentation !== undefined) {
+            const triggerKind = this._currentMacrostep === undefined ? 'external' : 'self';
+            this.enqueueWithInstrumentation(task, name, queue, triggerKind);
+            return;
+        }
+        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 port = this._instance.portRef;
+        if (port === undefined) {
+            throw new Error('ihsm: deferred notification requires a port');
+        }
+        if (this.instrumentation === undefined) {
+            port.setTimeout(() => this.dispatchNotification(name, args, 'default'), ms);
+            return;
+        }
+        // Capture the arming step's dispatch token now (the timer fires later while the actor is idle,
+        // so the ambient token is gone by then). The fired macrostep links back to it as `timer` (§5.3.1).
+        const armed = this.readDispatchCause('timer');
+        const cause = armed ?? { actorUuid: this.actorUuid, kind: 'timer' };
+        port.setTimeout(() => this.enqueueTimerNotification(name, args, cause, ms), ms);
+    }
+    enqueueTimerNotification(name, args, cause, delayMs) {
+        this.recordObserverEvent(name, args);
+        const task = createNotificationTask(this, this.transitionResolver, name, args);
+        setTaskMeta(task, { event: name, queue: 'default', cause, triggerKind: 'timer', delayMs });
+        notifyEnqueue(this.instrumentation, { event: name, queue: 'default', cause, delayMs, targetUuid: this.actorUuid });
+        this.pushTask(task);
+    }
+    _actorLogger;
+    /** Severity-typed handler logger surfaced as `this.hsm.log.*` (CORE-F, §4.10.1). */
+    get logger() {
+        if (this._actorLogger === undefined) {
+            const emit = (severity, message, attributes) => this.emitUserLog(severity, message, attributes);
+            this._actorLogger = {
+                trace: (m, a) => emit('trace', m, a),
+                debug: (m, a) => emit('debug', m, a),
+                info: (m, a) => emit('info', m, a),
+                warn: (m, a) => emit('warn', m, a),
+                error: (m, a) => emit('error', m, a),
+                fatal: (m, a) => emit('fatal', m, a),
+            };
+        }
+        return this._actorLogger;
+    }
+    emitUserLog(severity, message, attributes) {
+        const isError = message instanceof Error;
+        const text = isError ? message.message : message;
+        const body = `${this.traceHeader}${this.currentStateName}: ${text}`;
+        // User logs fire on intent and are never TraceLevel-gated; mirror to the TraceWriter for console.
+        this.traceWriter.write(this, body);
+        if (this.instrumentation === undefined)
+            return;
+        const record = {
+            severity,
+            body,
+            attributes,
+            frames: this.traceFrames,
+            error: isError ? message : undefined,
+            source: 'user',
+        };
+        notifyLog(this.instrumentation, record);
+    }
+    /** @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() {
+                const rawPort = instance.portRef;
+                if (machine.instrumentation === undefined || rawPort === undefined || typeof rawPort !== 'object') {
+                    return rawPort;
+                }
+                if (machine._proxiedPort !== undefined)
+                    return machine._proxiedPort;
+                const proxy = new Proxy(rawPort, {
+                    get(target, prop, receiver) {
+                        const value = Reflect.get(target, prop, receiver);
+                        if (typeof value !== 'function')
+                            return value;
+                        const method = String(prop);
+                        return (...args) => {
+                            const begin = machine.beginPortCall(method);
+                            if (begin === undefined) {
+                                return Reflect.apply(value, target, args);
+                            }
+                            const call = () => Reflect.apply(value, target, args);
+                            const storage = portCallContext.get();
+                            try {
+                                const result = storage !== undefined ? storage.run({ machine, callId: begin.callId, method, cause: begin.cause }, call) : call();
+                                if (result instanceof Promise) {
+                                    return result.then((value) => {
+                                        machine.endPortCall(begin, 'ok');
+                                        return value;
+                                    }, (cause) => {
+                                        const err = asError(cause);
+                                        machine.endPortCall(begin, 'error', err);
+                                        throw err;
+                                    });
+                                }
+                                machine.endPortCall(begin, 'ok');
+                                return result;
+                            }
+                            catch (cause) {
+                                const err = asError(cause);
+                                machine.endPortCall(begin, 'error', err);
+                                throw err;
+                            }
+                        };
+                    },
+                });
+                machine._proxiedPort = proxy;
+                return proxy;
+            },
+            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 traceFrames() {
+                return machine.traceFrames;
+            },
+            get log() {
+                return machine.logger;
+            },
+            get id() {
+                return machine.actorUuid;
+            },
+            get actorUuid() {
+                return machine.actorUuid;
+            },
+            get actorName() {
+                return machine.actorName;
+            },
+            get actorPath() {
+                return machine.actorPath;
+            },
+            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;
+            },
+            get id() {
+                return machine.actorUuid;
+            },
+            get actorUuid() {
+                return machine.actorUuid;
+            },
+            get actorName() {
+                return machine.actorName;
+            },
+            get actorPath() {
+                return machine.actorPath;
+            },
+        };
+        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;
+    }
+}
+//#region factories
+export 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 */
+export const defaultTraceWriter = new ConsoleTraceWriter();
+/** @internal */
+export const defaultInitialize = true;
+/** @internal */
+export 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`. */
+export function spawnActor(kind, topState, ctx, port, options, spawnContext = {}) {
+    const { initialize = defaultInitialize, traceLevel = TraceLevel.DEBUG, traceWriter = defaultTraceWriter, dispatchErrorCallback = defaultDispatchErrorCallback, transitions } = options;
+    const protocolIndex = buildProtocolIndex(topState);
+    const topStateName = getStateName(topState);
+    const parentMachine = spawnContext.parentMachine;
+    // Tracing is a cross-cutting concern: the actor adopts the globally-registered collector(s) at
+    // spawn (no per-actor `instrumentation` option). Snapshotting here keeps "no collector" actors
+    // at zero overhead while still sharing one collector instance across a parent and its children.
+    const resolvedInstrumentation = getActiveInstrumentation();
+    const identity = parentMachine !== undefined ? mintActorIdentity('child', childActorPath(parentMachine.actorPath, topStateName, parentMachine.allocateChildSpawnIndex(topStateName)), parentMachine.actorUuid) : mintActorIdentity(kind, rootActorPath(topStateName));
+    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, identity, resolvedInstrumentation, transitions ?? new RuntimeTransitionResolver());
+    if (resolvedInstrumentation !== undefined) {
+        const token = dispatchContext.get()?.getStore();
+        const parentCause = token?.actorUuid !== undefined
+            ? {
+                actorUuid: token.actorUuid,
+                macrostepId: token.macrostepId,
+                stepSeq: token.stepSeq,
+                kind: 'spawn',
+            }
+            : {
+                actorUuid: identity.parentUuid ?? identity.uuid,
+                kind: 'spawn',
+            };
+        const spawnInfo = {
+            parent: parentCause,
+            child: identity,
+        };
+        notifyActorSpawned(resolvedInstrumentation, spawnInfo);
+    }
+    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). */
+export function makeActor(topState, ctx, port, options = {}) {
+    return spawnActor('root', topState, ctx, port, options);
+}
+export function asParentActor(handler) {
+    const machine = handler[kHandlerMachine];
+    if (machine === undefined) {
+        throw new Error('ihsm: asParentActor requires an active handler machine');
+    }
+    return {
+        top: machine.topState,
+        [kParentLink]: machine,
+    };
+}
+/** Parent composes a child machine — returns full child protocol shell with `parent` set. */
+export function makeChildActor(parent, childTop, childCtx, port, options = {}) {
+    const parentMachine = parent[kParentLink];
+    const child = spawnActor('child', childTop, childCtx, port, options, { parentMachine: parentMachine });
+    Object.defineProperty(child, 'parent', { value: parent, enumerable: true, writable: false, configurable: true });
+    return child;
+}
+export { kHandlerMachine, kParentLink } from './types.js';
+export { configureRunSeed, getRunSeed, getRunNamespace, actorNameFromTopState, mintActorIdentity, rootActorPath, childActorPath } from './identity.js';
+//# sourceMappingURL=runtime.js.map