ihsm 0.0.26 → 0.1.1

package/lib/cjs/index.js

@@ -1,767 +1,56 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defaultInitialize = exports.defaultTraceWriter = exports.FatalErrorState = exports.InitializationError = exports.FatalError = exports.InitialStateError = exports.UnhandledEventError = exports.EventHandlerError = exports.TransitionError = exports.RuntimeError = exports.HsmError = exports.TopState = exports.Port = exports.BasePort = exports.TraceLevel = void 0;
-exports.InitialState = InitialState;
-exports.defineStateName = defineStateName;
-exports.registerStateNames = registerStateNames;
-exports.defaultDispatchErrorCallback = defaultDispatchErrorCallback;
-exports.makeHsm = makeHsm;
-exports.makeActor = makeActor;
-const hsm_1 = require("./internal/hsm");
-const utils_1 = require("./internal/utils");
-// export type DispatchErrorCallback<Context, Protocol extends {} | undefined> = (hsm: Hsm<Context, Protocol>, traceWriter: TraceWriter, err: Error) => void;
-/**
- * Controls how much diagnostic detail the runtime emits through {@link TraceWriter}.
- *
- * Set at construction via {@link makeHsm} or mutate {@link Properties.traceLevel} on a
- * live instance. Changing the level swaps the internal dispatch tracer implementation.
- *
- * @category Factory
- */
-var TraceLevel;
-(function (TraceLevel) {
-    /**
-     * Production mode: minimal tracing overhead, no verbose dispatch steps.
-     * Use in hot paths and shipped bundles when trace output is disabled.
-     */
-    TraceLevel[TraceLevel["PRODUCTION"] = 0] = "PRODUCTION";
-    /**
-     * Debug mode: transition boundaries, handler entry/exit, and error summaries.
-     * Default for {@link makeHsm}. Suitable for development and integration tests.
-     */
-    TraceLevel[TraceLevel["DEBUG"] = 1] = "DEBUG";
-    /**
-     * Verbose debug: includes prototype-chain lookup walks, cache hits/misses, and
-     * nested trace domains. Use when correlating handler code with tutorial trace panels.
-     */
-    TraceLevel[TraceLevel["VERBOSE_DEBUG"] = 2] = "VERBOSE_DEBUG";
-})(TraceLevel || (exports.TraceLevel = TraceLevel = {}));
-/**
- * Abstract base class for **any** port — production or test.
- *
- * It takes the machine's root {@link TopState} as its single type argument and derives the
- * context and internal protocol from it (via {@link MachineContext} / {@link MachineInternal}),
- * so the `TopState` is the one place those types are declared. Extend {@link Port} (not `BasePort`
- * directly) for production ports so timer and random services are available.
- *
- * The {@link BasePort.actor | actor} link is **bound lazily** by the runtime: construct the port
- * with no arguments and pass the instance to a factory, which wires the actor in afterwards.
- *
- * @typeParam T - The machine's root {@link TopState} subclass (e.g. `ConnTop`)
- *
- * @category Port
- */
-class BasePort {
-    /**
-     * @inheritdoc PortHandle.actor
-     *
-     * Set once by the runtime right after the machine is built; `undefined` before binding.
-     */
-    actor;
-    /** @inheritdoc PortHandle.hsm */
-    hsm() {
-        return this.actor;
-    }
-    /**
-     * Post an internal event inward through the bound {@link BasePort.actor | actor}.
-     *
-     * This is the one channel a port (or a test driving the port) uses to feed the machine its
-     * internal protocol. Because emission is explicit — never a side effect of the outbound call
-     * the machine made — a single mock works across many tests: the test decides *when* (and
-     * whether) to push each internal event.
-     *
-     * @param eventName - Internal event to post
-     * @param payload - Arguments for the event
-     * @throws If called before the actor has been bound by a factory
-     */
-    send(eventName, ...payload) {
-        if (this.actor === undefined) {
-            throw new Error('ihsm: port.send called before the actor was bound — pass the port to makeActor/makeHsm/makeTestActor first');
-        }
-        this.actor.post(eventName, ...payload);
-    }
-}
-exports.BasePort = BasePort;
-/**
- * Production port base with standard JavaScript timer and random services.
- *
- * Extend this class for domain ports in production code. It inherits the lazily-bound
- * {@link BasePort.actor | actor}, {@link BasePort.hsm | hsm}, and {@link BasePort.send | send}
- * from {@link BasePort}, and adds {@link Port.setTimeout | setTimeout} /
- * {@link Port.setInterval | setInterval} / {@link Port.clearTimeout | clearTimeout} /
- * {@link Port.clearInterval | clearInterval} plus the {@link RandomService} methods
- * ({@link Port.random | random}, {@link Port.cryptoRandom | cryptoRandom},
- * {@link Port.randomUUID | randomUUID}, {@link Port.getRandomValues | getRandomValues}).
- *
- * {@link State.deferredPost} delegates to {@link Port.setTimeout}. When no custom port is
- * supplied the runtime instantiates a plain `Port` for that purpose.
- *
- * @typeParam T - The machine's root {@link TopState} subclass (e.g. `ConnTop`)
- *
- * @example A minimal domain port
- * ```ts
- * class ConnPortImpl extends ihsm.Port<ConnTop> implements ConnPort {
- *   private nextId = 1;
- *   connect(host: string): ihsm.ResultWithSubscription<number> {
- *     const id = this.nextId++;
- *     return { value: id, subscription: { dispose: () => {} } };
- *   }
- *   disconnect(id: number): void {}
- * }
- * const port = new ConnPortImpl();
- * const conn = ihsm.makeActor(ConnTop, ctx, port);   // binds port.actor
- * ```
- *
- * @category Port
- */
-class Port extends BasePort {
-    _timerSeq = 0;
-    _timeoutHandles = new Map();
-    _intervalHandles = new Map();
-    /**
-     * Schedule `callback` after `millis` milliseconds — same argument order as `globalThis.setTimeout`.
-     *
-     * @returns An opaque handle for {@link Port.clearTimeout}
-     */
-    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 pending {@link Port.setTimeout} handle. No-op when `id` is `undefined` or unknown. */
-    clearTimeout(id) {
-        if (id === undefined) {
-            return;
-        }
-        const handle = this._timeoutHandles.get(id);
-        if (handle !== undefined) {
-            globalThis.clearTimeout(handle);
-            this._timeoutHandles.delete(id);
-        }
-    }
-    /**
-     * Schedule `callback` every `millis` milliseconds — same argument order as `globalThis.setInterval`.
-     *
-     * @returns An opaque handle for {@link Port.clearInterval}
-     */
-    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 a pending {@link Port.setInterval} handle. No-op when `id` is `undefined` or unknown. */
-    clearInterval(id) {
-        if (id === undefined) {
-            return;
-        }
-        const handle = this._intervalHandles.get(id);
-        if (handle !== undefined) {
-            globalThis.clearInterval(handle);
-            this._intervalHandles.delete(id);
-        }
-    }
-    /** @inheritdoc RandomService.random */
-    random() {
-        return Math.random();
-    }
-    /** @inheritdoc RandomService.cryptoRandom */
-    cryptoRandom() {
-        const crypto = globalThis.crypto;
-        return crypto.random?.() ?? Math.random();
-    }
-    /** @inheritdoc RandomService.randomUUID */
-    randomUUID() {
-        return globalThis.crypto.randomUUID();
-    }
-    /** @inheritdoc RandomService.getRandomValues */
-    getRandomValues(array) {
-        // crypto.getRandomValues accepts a narrower union than ArrayBufferView; the runtime call is safe.
-        globalThis.crypto.getRandomValues(array);
-        return array;
-    }
-}
-exports.Port = Port;
-/**
- * Abstract root class for every state in the hierarchy.
- *
- * States are **never constructed directly** — the runtime binds one instance object whose
- * prototype moves along the class chain. Subclass `TopState` (or a child state), implement
- * your `Protocol` methods, and pass the root class to {@link makeHsm}.
- *
- * Forwards {@link State} / {@link Properties} APIs and default {@link StateEvents} behavior.
- *
- * @category State machine
- */
-class TopState {
-    /** Domain context (injected by runtime — do not assign in constructors). */
-    ctx;
-    /** Handler view of the machine (`this` inside methods delegates here for core operations). */
-    hsm;
-    constructor() {
-        throw new Error('Fatal error: States cannot be instantiated');
-    }
-    /**
-     * Outbound boundary — the `port` instance passed to {@link makeActor} / {@link testing!makeTestActor};
-     * all impure I/O flows through here.
-     *
-     * Typed `undefined` for machines created without a port (the default), so existing
-     * port-less machines are unaffected. At runtime a {@link Port} always backs such
-     * machines — it is what {@link State.deferredPost} uses for its timer service.
-     */
-    get port() {
-        return this.hsm.port;
-    }
-    /** @inheritdoc Properties.eventName */
-    get eventName() {
-        return this.hsm.eventName;
-    }
-    /** @inheritdoc Properties.eventPayload */
-    get eventPayload() {
-        return this.hsm.eventPayload;
-    }
-    /** @inheritdoc Properties.traceHeader */
-    get traceHeader() {
-        return this.hsm.traceHeader;
-    }
-    /** @inheritdoc Properties.topState */
-    get topState() {
-        return this.hsm.topState;
-    }
-    /** @inheritdoc Properties.currentStateName */
-    get currentStateName() {
-        return this.hsm.currentStateName;
-    }
-    /** @inheritdoc Properties.currentState */
-    get currentState() {
-        return this.hsm.currentState;
-    }
-    /** @inheritdoc Properties.ctxTypeName */
-    get ctxTypeName() {
-        return this.hsm.ctxTypeName;
-    }
-    /** @inheritdoc Properties.traceLevel */
-    set traceLevel(value) {
-        this.hsm.traceLevel = value;
-    }
-    /** @inheritdoc Properties.traceLevel */
-    get traceLevel() {
-        return this.hsm.traceLevel;
-    }
-    /** @inheritdoc Properties.topStateName */
-    get topStateName() {
-        return this.hsm.topStateName;
-    }
-    /** @inheritdoc Properties.traceWriter */
-    get traceWriter() {
-        return this.hsm.traceWriter;
-    }
-    /** @inheritdoc Properties.traceWriter */
-    set traceWriter(value) {
-        this.hsm.traceWriter = value;
-    }
-    /** @inheritdoc Properties.dispatchErrorCallback */
-    get dispatchErrorCallback() {
-        return this.hsm.dispatchErrorCallback;
-    }
-    /** @inheritdoc Properties.dispatchErrorCallback */
-    set dispatchErrorCallback(value) {
-        this.hsm.dispatchErrorCallback = value;
-    }
-    /** @inheritdoc State.transition */
-    transition(nextState) {
-        this.hsm.transition(nextState);
-    }
-    /** @inheritdoc State.unhandled */
-    unhandled() {
-        this.hsm.unhandled();
-    }
-    /** @inheritdoc State.sleep */
-    sleep(millis) {
-        return this.hsm.sleep(millis);
-    }
-    /** @inheritdoc Base.post */
-    post(eventName, ...eventPayload) {
-        this.hsm.post(eventName, ...eventPayload);
-    }
-    /** @inheritdoc State.deferredPost */
-    deferredPost(millis, eventName, ...eventPayload) {
-        this.hsm.deferredPost(millis, eventName, ...eventPayload);
-    }
-    /** @inheritdoc State.postNow */
-    postNow(eventName, ...eventPayload) {
-        this.hsm.postNow(eventName, ...eventPayload);
-    }
-    /** @inheritdoc StateEvents.onExit */
-    onExit() { }
-    /** @inheritdoc StateEvents.onEntry */
-    onEntry() { }
-    /** @inheritdoc StateEvents.onError */
-    onError(error) {
-        throw error;
-    }
-    /** @inheritdoc StateEvents.onUnhandled */
-    onUnhandled(error) {
-        throw error;
-    }
-}
-exports.TopState = TopState;
-/**
- * Base class for all ihsm runtime errors carrying machine context.
- *
- * @typeParam Context - Domain context at failure time
- * @typeParam Protocol - Vocabulary type (for typed subclasses)
- *
- * @category Error
- */
-class HsmError extends Error {
-    /** Discriminator matching the class name (`EventHandlerError`, etc.). */
-    name;
-    /** {@link Properties.topStateName} when the error was constructed. */
-    topStateName;
-    /** {@link Properties.currentStateName} when the error was constructed. */
-    stateName;
-    /** Snapshot of {@link State.ctx} when the error was constructed. */
-    context;
-    /** Original thrown value when this error wraps a handler or lifecycle failure. */
-    cause;
-    constructor(name, hsm, message, cause) {
-        super(message);
-        this.name = name;
-        this.topStateName = hsm.topStateName;
-        this.stateName = hsm.currentStateName;
-        this.context = hsm.ctx;
-        this.cause = cause;
-    }
-}
-exports.HsmError = HsmError;
-/**
- * Error base for failures during **event dispatch**, with correlated event metadata.
- *
- * @typeParam Context - Domain context
- * @typeParam Protocol - Vocabulary interface
- * @typeParam EventName - Event or service key being processed
- *
- * @category Error
- */
-class RuntimeError extends HsmError {
-    /** Event or service name that was active when the failure occurred. */
-    eventName;
-    /** Client-supplied arguments (excluding resolve/reject for services). */
-    eventPayload;
-    constructor(errorName, hsm, message, cause) {
-        super(errorName, hsm, message, cause);
-        this.eventName = hsm.eventName;
-        this.eventPayload = hsm.eventPayload;
-    }
-}
-exports.RuntimeError = RuntimeError;
-/**
- * Thrown when {@link StateEvents.onExit} or {@link StateEvents.onEntry} throws during a transition.
- *
- * @category Error
- */
-class TransitionError extends RuntimeError {
-    failedStateName;
-    failedCallback;
-    fromStateName;
-    toStateName;
-    /**
-     * @param hsm - Machine view at failure time
-     * @param cause - Error thrown from the lifecycle hook
-     * @param failedStateName - Display name of the state whose hook failed
-     * @param failedCallback - Which hook failed (`onExit` or `onEntry`)
-     * @param fromStateName - Leaf state before the transition
-     * @param toStateName - Requested destination state
-     */
-    constructor(hsm, cause, failedStateName, failedCallback, fromStateName, toStateName) {
-        super('TransitionError', hsm, `${failedStateName}.${failedCallback}() has failed while executing a transition from ${fromStateName} to ${toStateName}`, cause);
-        this.failedStateName = failedStateName;
-        this.failedCallback = failedCallback;
-        this.fromStateName = fromStateName;
-        this.toStateName = toStateName;
-    }
-}
-exports.TransitionError = TransitionError;
-/**
- * Thrown when an event handler body throws and {@link StateEvents.onError} does not recover.
- *
- * @category Error
- */
-class EventHandlerError extends RuntimeError {
-    /**
-     * @param hsm - Machine view with {@link eventName} set to the failing handler
-     * @param cause - Error thrown from handler code
-     */
-    constructor(hsm, cause) {
-        super('EventHandlerError', hsm, `an error was thrown while executing event handler #${hsm.eventName} in state ${hsm.currentStateName}`, cause);
-    }
-}
-exports.EventHandlerError = EventHandlerError;
-/**
- * Thrown when no handler matches the dispatched event and {@link StateEvents.onUnhandled} rethrows.
- *
- * @category Error
- */
-class UnhandledEventError extends RuntimeError {
-    /** @param hsm - Machine view with the unmatched {@link eventName} */
-    constructor(hsm) {
-        super('UnhandledEventError', hsm, `event #${hsm.eventName} was unhandled in state ${hsm.currentStateName}`);
-    }
-}
-exports.UnhandledEventError = UnhandledEventError;
-/**
- * Thrown at **class definition** time when {@link InitialState} is applied twice to one parent.
- *
- * @category Error
- */
-class InitialStateError extends Error {
-    /** Display name of the state passed to the duplicate {@link InitialState} call. */
-    targetStateName;
-    /** @param targetState - The state class whose parent already has an initial substate */
-    constructor(targetState) {
-        super(`State '${(0, utils_1.getStateName)(Object.getPrototypeOf(targetState.prototype).constructor)}' must not have more than one initial state`);
-        this.name = 'InitialStateError';
-        this.targetStateName = (0, utils_1.getStateName)(targetState);
-    }
-}
-exports.InitialStateError = InitialStateError;
-/**
- * Thrown when {@link StateEvents.onError} itself throws, leaving the machine unrecoverable.
- *
- * @category Error
- */
-class FatalError extends RuntimeError {
-    /**
-     * @param hsm - Machine view at failure time
-     * @param cause - Error thrown from `onError`
-     */
-    constructor(hsm, cause) {
-        super('FatalError', hsm, `onError() has thrown ${(0, utils_1.quoteError)(cause)}`, cause);
-    }
-}
-exports.FatalError = FatalError;
-/**
- * Thrown when {@link StateEvents.onEntry} fails during the initial `@InitialState` walk at startup.
- *
- * @category Error
- */
-class InitializationError extends HsmError {
-    failedState;
-    /**
-     * @param hsm - Partially initialized machine
-     * @param failedState - State class whose `onEntry` threw
-     * @param cause - Original error from `onEntry`
-     */
-    constructor(hsm, failedState, cause) {
-        super('InitializationError', hsm, `state ${(0, utils_1.getStateName)(failedState)} has thrown ${(0, utils_1.quoteError)(cause)} during initialization`, cause);
-        this.failedState = failedState;
-    }
-}
-exports.InitializationError = InitializationError;
-/**
- * Terminal sink state class used when the runtime cannot recover from an error.
- *
- * Assign or transition here from custom {@link StateEvents.onError} handlers when you need a
- * well-defined quiescent state. Display name is pre-registered as `'FatalErrorState'`.
- *
- * @category State machine
- */
-class FatalErrorState extends TopState {
-}
-exports.FatalErrorState = FatalErrorState;
-(0, utils_1.defineStateName)(TopState, 'TopState');
-(0, utils_1.defineStateName)(FatalErrorState, 'FatalErrorState');
-/**
- * Declares `TargetState` as the **initial substate** of its direct parent composite.
- *
- * Apply as a TypeScript decorator or call as a function at class definition time. Exactly **one**
- * initial child is allowed per parent; a second mark throws {@link InitialStateError}.
- *
- * @typeParam Context - Domain context type
- * @typeParam Protocol - Vocabulary interface
- * @param TargetState - Child state class whose **parent** is `Object.getPrototypeOf(TargetState.prototype).constructor`
- *
- * @throws {@link InitialStateError} when the parent already has an initial substate
- *
- * @remarks
- * During {@link makeHsm} initialization, the runtime descends `@InitialState` chains from the
- * root until the deepest initial leaf is active, running {@link StateEvents.onEntry} along the path.
- *
- * @example
- * ```ts
- * class Composite extends TopState {}
- *
- * @InitialState
- * class Idle extends Composite {}
- * ```
- */
-function InitialState(TargetState) {
-    const ParentOfTargetState = Object.getPrototypeOf(TargetState.prototype).constructor;
-    if ((0, utils_1.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,
-    });
-}
-/**
- * Assigns a stable **display name** to a single state class.
- *
- * Minifiers rewrite `Class.name` in production browser bundles; explicit registration keeps
- * {@link Properties.currentStateName}, trace output, and error messages readable everywhere.
- *
- * @typeParam Context - Domain context type
- * @typeParam Protocol - Vocabulary interface
- * @param state - State class constructor to tag
- * @param name - Non-empty display string used in traces and errors (not required to match `Class.name`)
- *
- * @remarks
- * Stored as a non-enumerable own property — never inherited by subclasses from the prototype chain.
- * {@link registerStateNames} is preferred when every state is a named export from one module.
- *
- * @example
- * ```ts
- * class Door extends TopState {}
- * defineStateName(Door, 'Door');
- * ```
- *
- * @category State machine
- */
-function defineStateName(state, name) {
-    (0, utils_1.defineStateName)(state, name);
-}
-/**
- * Registers display names for **every** state class in an exports object, using each **export key** as the name.
- *
- * @param exports - Module namespace (`import * as machine`) or object literal of state classes.
- *   Non-constructor exports (constants, functions, types) are silently skipped
- *
- * @remarks
- * Export keys survive minification even when class identifiers are mangled — this is the recommended
- * approach for browser bundles without `keep_classnames`. Call once at module load after all state
- * classes are defined.
- *
- * @example Single module
- * ```ts
- * export class DoorTop extends TopState {}
- * export class Open extends DoorTop {}
- * export class Closed extends DoorTop {}
- * registerStateNames({ DoorTop, Open, Closed });
- * ```
- *
- * @example Re-exporting namespace
- * ```ts
- * import * as machine from './machine';
- * registerStateNames(machine);
- * ```
- *
- * @category State machine
- */
-function registerStateNames(exports) {
-    for (const [exportName, value] of Object.entries(exports)) {
-        if (isStateClass(value)) {
-            (0, utils_1.defineStateName)(value, exportName);
-        }
-    }
-}
-/** @internal — structural guard: a constructor whose prototype derives from {@link TopState}. */
-function isStateClass(value) {
-    if (typeof value !== 'function')
-        return false;
-    const prototype = value.prototype;
-    return typeof prototype === 'object' && prototype !== null && TopState.prototype.isPrototypeOf(prototype);
-}
-/** @internal */
-class ConsoleTraceWriter {
-    write(hsm, Message) {
-        if (typeof Message == 'string') {
-            console.log(`${hsm.traceHeader}${hsm.currentStateName}: ${Message}`);
-        }
-        else {
-            console.log(Message);
-        }
-    }
-}
-/** @internal — shared by the core factories and (via re-export) the `ihsm/testing` factories. */
-function defaultDispatchErrorCallback(hsm, err) {
-    const writer = hsm.traceWriter;
-    writer.write(hsm, `An event dispatch has failed; error ${err.name}: ${err.message} has not been managed`);
-    writer.write(hsm, err);
-    throw err;
-}
-/** @internal */
-exports.defaultTraceWriter = new ConsoleTraceWriter();
-const defaultTraceLevel = TraceLevel.DEBUG;
-/** @internal */
-exports.defaultInitialize = true;
-/**
- * Creates and optionally initializes a hierarchical state machine **actor** bound to `ctx`.
- *
- * The returned {@link Hsm} is the single runtime object: external clients call `post` / `call` /
- * `sync`; the active state is the instance prototype chain updated by {@link State.transition}.
- *
- * @typeParam Context - Domain context type (inferred from `ctx` when passed inline)
- * @typeParam Protocol - Event/service vocabulary (inferred from `topState` when it implements `Protocol`)
- * @param topState - Root state **class** constructor (must extend {@link TopState})
- * @param ctx - Mutable domain object shared by all states; stored on the instance as {@link Hsm.ctx}
- * @param initialize - When `true` (default), enqueue the initial walk: descend `@InitialState`
- *   chains from `topState` and run {@link StateEvents.onEntry} on each entered state until the
- *   initial leaf is active. When `false`, prototype starts at `topState` with **no** entry hooks
- * @param traceLevel - Initial {@link TraceLevel} (default {@link TraceLevel.DEBUG})
- * @param traceWriter - {@link TraceWriter} implementation (default: prefixes strings with state name and logs to `console`)
- * @param dispatchErrorCallback - Last-resort error hook (default: trace + rethrow)
- * @returns Client handle implementing {@link Hsm} for the same `Context` and `Protocol`
- *
- * @remarks
- * - Await {@link Hsm.sync} after creation when `initialize: true` before asserting initial state
- * - Zero runtime npm dependencies; safe to embed in browsers when state names are registered
- * - Transition LCA paths are cached per machine instance for the lifetime of the actor
- *
- * @example Minimal door machine
- * ```ts
- * const door = makeHsm(DoorTop, { openCount: 0 });
- * await door.sync();
- * door.post('open');
- * await door.sync();
- * ```
- *
- * @example Custom tracing in tests
- * ```ts
- * const writer = { write: (_hsm, msg) => logs.push(msg) };
- * const sm = makeHsm(Top, ctx, true, TraceLevel.VERBOSE_DEBUG, writer);
- * await sm.sync();
- * ```
- *
- * @category Factory
- */
-function makeHsm(topState, ctx, initialize = exports.defaultInitialize, traceLevel = defaultTraceLevel, traceWriter = exports.defaultTraceWriter, dispatchErrorCallback = defaultDispatchErrorCallback, port) {
-    return instantiate(topState, ctx, initialize, traceLevel, traceWriter, dispatchErrorCallback, port);
-}
-/** @internal — single construction path shared by {@link makeHsm}, {@link makeActor}, {@link testing!makeTestActor}. */
-function instantiate(topState, ctx, initialize, traceLevel, traceWriter, dispatchErrorCallback, port) {
-    const instance = {
-        hsm: undefined,
-        ctx: ctx,
-    };
-    Object.setPrototypeOf(instance, topState.prototype);
-    instance.hsm = new hsm_1.HsmObject(topState, instance, traceWriter, traceLevel, dispatchErrorCallback, initialize);
-    // A port is always present: the supplied instance, otherwise a Port that backs
-    // `deferredPost`'s timer service. Its `actor` is bound here, lazily — synchronously, before
-    // the queued initialization walk, so `this.port` is available inside the first `onEntry`.
-    const boundPort = port ?? new Port();
-    boundPort.actor = instance.hsm;
-    instance.portRef = boundPort;
-    return instance.hsm;
-}
-/**
- * @internal
- *
- * Wrap a live machine in a **structural, public-only** {@link Actor} facade (proposal T5).
- *
- * Replaces the old `hsm as unknown as Actor<…>` double cast. The returned object is annotated
- * `Actor<Context, Public>`, so the compiler verifies it implements **exactly** the public surface —
- * a regression that leaked an internal member would fail to compile, and if {@link Hsm} gains a
- * member this factory stops compiling until the facade forwards it. Each forwarded `post` / `call`
- * is narrowed from the merged-protocol instance down to the public protocol with a single local
- * cast; properties delegate through get/set accessors so reads and writes still hit the live machine.
- */
-function narrowToActor(hsm) {
-    const actor = {
-        get ctx() {
-            return hsm.ctx;
-        },
-        get currentState() {
-            return hsm.currentState;
-        },
-        get currentStateName() {
-            return hsm.currentStateName;
-        },
-        get topState() {
-            return hsm.topState;
-        },
-        get topStateName() {
-            return hsm.topStateName;
-        },
-        get ctxTypeName() {
-            return hsm.ctxTypeName;
-        },
-        get traceHeader() {
-            return hsm.traceHeader;
-        },
-        get eventName() {
-            return hsm.eventName;
-        },
-        get eventPayload() {
-            return hsm.eventPayload;
-        },
-        get traceLevel() {
-            return hsm.traceLevel;
-        },
-        set traceLevel(level) {
-            hsm.traceLevel = level;
-        },
-        get traceWriter() {
-            return hsm.traceWriter;
-        },
-        set traceWriter(writer) {
-            hsm.traceWriter = writer;
-        },
-        get dispatchErrorCallback() {
-            return hsm.dispatchErrorCallback;
-        },
-        set dispatchErrorCallback(cb) {
-            hsm.dispatchErrorCallback = cb;
-        },
-        post: hsm.post.bind(hsm),
-        call: hsm.call.bind(hsm),
-        sync: hsm.sync.bind(hsm),
-        restore: hsm.restore.bind(hsm),
-    };
-    return actor;
-}
-/**
- * Creates an actor exposing only its **public** protocol, with an optional outbound {@link Port}.
- *
- * Like {@link makeHsm} but separates the public, client-callable protocol from an
- * `InternalProtocol` that only the port may post inward. The returned {@link Actor} surfaces
- * just the public events; handlers (and the port) may post the merged {@link Dispatch} protocol.
- *
- * The trailing `Disjoint` guard is a compile-time gate: if `Public` and `Internal` share an event
- * name, the call fails to type-check, pointing at the overlapping keys.
- *
- * @typeParam Context - Domain context type
- * @typeParam Public - Public, client-callable protocol
- * @typeParam Internal - Internal protocol — only postable by the port / handlers
- * @typeParam P - Concrete {@link Port} type assigned to `this.port`
- * @param topState - Root state class; `Context` / `Public` / `Internal` are inferred from it (see {@link TopStateArg})
- * @param ctx - Mutable domain object shared by all states
- * @param port - Outbound port instance (its `actor` is bound by the factory; use {@link Port} if none)
- * @param options - Optional tuning: `initialize` / `traceLevel` / `traceWriter` / … (see {@link ActorOptions})
- * @returns A public-only {@link Actor} handle
- *
- * @example
- * ```ts
- * const conn = makeActor(ConnTop, new ConnCtx(), port, { traceLevel: TraceLevel.PRODUCTION });
- * ```
- *
- * @category Factory
- */
-function makeActor(topState, ctx, port, options = {}, ..._disjointGuard) {
-    const { initialize = exports.defaultInitialize, traceLevel = defaultTraceLevel, traceWriter = exports.defaultTraceWriter, dispatchErrorCallback = defaultDispatchErrorCallback } = options;
-    const hsm = instantiate(topState, ctx, initialize, traceLevel, traceWriter, dispatchErrorCallback, port);
-    return narrowToActor(hsm);
-}
+exports.kParentLink = exports.kHandlerMachine = exports.makeChildActor = exports.asParentActor = exports.makeActor = exports.defaultDispatchErrorCallback = exports.defaultInitialize = exports.defaultTraceWriter = exports.serviceCallWithTimeout = exports.splitServiceArgs = exports.isServiceCallOptions = exports.isRequestingPort = exports.RuntimeTransitionResolver = exports.transitionTraceLines = exports.createTransitionTracer = exports.executeTransitionRoutine = exports.planTransitionClasses = exports.TransitionTableError = exports.SelfCallDeadlockError = exports.CallTimeoutError = exports.buildProtocolIndex = exports.ReservedNames = exports.ProtocolCollisionError = exports.registerStateNames = exports.InitialState = exports.FatalErrorState = exports.InitializationError = exports.FatalError = exports.InitialStateError = exports.UnhandledEventError = exports.EventHandlerError = exports.TransitionError = exports.RuntimeError = exports.HsmError = exports.TopState = exports.RequestingPort = exports.Port = exports.getStateName = exports.defineStateName = exports.getTransitionKey = exports.hasInitialState = exports.getInitialState = exports.quoteError = exports.quoteUnknown = exports.asError = exports.TraceLevel = void 0;
+/**
+ * ihsm — hierarchical state machines for TypeScript.
+ *
+ * Curated public runtime surface; protocol types live in {@link ./types}.
+ */
+var runtime_1 = require("./internal/runtime");
+Object.defineProperty(exports, "TraceLevel", { enumerable: true, get: function () { return runtime_1.TraceLevel; } });
+Object.defineProperty(exports, "asError", { enumerable: true, get: function () { return runtime_1.asError; } });
+Object.defineProperty(exports, "quoteUnknown", { enumerable: true, get: function () { return runtime_1.quoteUnknown; } });
+Object.defineProperty(exports, "quoteError", { enumerable: true, get: function () { return runtime_1.quoteError; } });
+Object.defineProperty(exports, "getInitialState", { enumerable: true, get: function () { return runtime_1.getInitialState; } });
+Object.defineProperty(exports, "hasInitialState", { enumerable: true, get: function () { return runtime_1.hasInitialState; } });
+Object.defineProperty(exports, "getTransitionKey", { enumerable: true, get: function () { return runtime_1.getTransitionKey; } });
+Object.defineProperty(exports, "defineStateName", { enumerable: true, get: function () { return runtime_1.defineStateName; } });
+Object.defineProperty(exports, "getStateName", { enumerable: true, get: function () { return runtime_1.getStateName; } });
+Object.defineProperty(exports, "Port", { enumerable: true, get: function () { return runtime_1.Port; } });
+Object.defineProperty(exports, "RequestingPort", { enumerable: true, get: function () { return runtime_1.RequestingPort; } });
+Object.defineProperty(exports, "TopState", { enumerable: true, get: function () { return runtime_1.TopState; } });
+Object.defineProperty(exports, "HsmError", { enumerable: true, get: function () { return runtime_1.HsmError; } });
+Object.defineProperty(exports, "RuntimeError", { enumerable: true, get: function () { return runtime_1.RuntimeError; } });
+Object.defineProperty(exports, "TransitionError", { enumerable: true, get: function () { return runtime_1.TransitionError; } });
+Object.defineProperty(exports, "EventHandlerError", { enumerable: true, get: function () { return runtime_1.EventHandlerError; } });
+Object.defineProperty(exports, "UnhandledEventError", { enumerable: true, get: function () { return runtime_1.UnhandledEventError; } });
+Object.defineProperty(exports, "InitialStateError", { enumerable: true, get: function () { return runtime_1.InitialStateError; } });
+Object.defineProperty(exports, "FatalError", { enumerable: true, get: function () { return runtime_1.FatalError; } });
+Object.defineProperty(exports, "InitializationError", { enumerable: true, get: function () { return runtime_1.InitializationError; } });
+Object.defineProperty(exports, "FatalErrorState", { enumerable: true, get: function () { return runtime_1.FatalErrorState; } });
+Object.defineProperty(exports, "InitialState", { enumerable: true, get: function () { return runtime_1.InitialState; } });
+Object.defineProperty(exports, "registerStateNames", { enumerable: true, get: function () { return runtime_1.registerStateNames; } });
+Object.defineProperty(exports, "ProtocolCollisionError", { enumerable: true, get: function () { return runtime_1.ProtocolCollisionError; } });
+Object.defineProperty(exports, "ReservedNames", { enumerable: true, get: function () { return runtime_1.ReservedNames; } });
+Object.defineProperty(exports, "buildProtocolIndex", { enumerable: true, get: function () { return runtime_1.buildProtocolIndex; } });
+Object.defineProperty(exports, "CallTimeoutError", { enumerable: true, get: function () { return runtime_1.CallTimeoutError; } });
+Object.defineProperty(exports, "SelfCallDeadlockError", { enumerable: true, get: function () { return runtime_1.SelfCallDeadlockError; } });
+Object.defineProperty(exports, "TransitionTableError", { enumerable: true, get: function () { return runtime_1.TransitionTableError; } });
+Object.defineProperty(exports, "planTransitionClasses", { enumerable: true, get: function () { return runtime_1.planTransitionClasses; } });
+Object.defineProperty(exports, "executeTransitionRoutine", { enumerable: true, get: function () { return runtime_1.executeTransitionRoutine; } });
+Object.defineProperty(exports, "createTransitionTracer", { enumerable: true, get: function () { return runtime_1.createTransitionTracer; } });
+Object.defineProperty(exports, "transitionTraceLines", { enumerable: true, get: function () { return runtime_1.transitionTraceLines; } });
+Object.defineProperty(exports, "RuntimeTransitionResolver", { enumerable: true, get: function () { return runtime_1.RuntimeTransitionResolver; } });
+Object.defineProperty(exports, "isRequestingPort", { enumerable: true, get: function () { return runtime_1.isRequestingPort; } });
+Object.defineProperty(exports, "isServiceCallOptions", { enumerable: true, get: function () { return runtime_1.isServiceCallOptions; } });
+Object.defineProperty(exports, "splitServiceArgs", { enumerable: true, get: function () { return runtime_1.splitServiceArgs; } });
+Object.defineProperty(exports, "serviceCallWithTimeout", { enumerable: true, get: function () { return runtime_1.serviceCallWithTimeout; } });
+Object.defineProperty(exports, "defaultTraceWriter", { enumerable: true, get: function () { return runtime_1.defaultTraceWriter; } });
+Object.defineProperty(exports, "defaultInitialize", { enumerable: true, get: function () { return runtime_1.defaultInitialize; } });
+Object.defineProperty(exports, "defaultDispatchErrorCallback", { enumerable: true, get: function () { return runtime_1.defaultDispatchErrorCallback; } });
+Object.defineProperty(exports, "makeActor", { enumerable: true, get: function () { return runtime_1.makeActor; } });
+Object.defineProperty(exports, "asParentActor", { enumerable: true, get: function () { return runtime_1.asParentActor; } });
+Object.defineProperty(exports, "makeChildActor", { enumerable: true, get: function () { return runtime_1.makeChildActor; } });
+Object.defineProperty(exports, "kHandlerMachine", { enumerable: true, get: function () { return runtime_1.kHandlerMachine; } });
+Object.defineProperty(exports, "kParentLink", { enumerable: true, get: function () { return runtime_1.kParentLink; } });
 //# sourceMappingURL=index.js.map