ihsm 0.0.26 → 0.1.21

package/lib/esm/index.js

@@ -1,746 +1,9 @@
-import { HsmObject } from './internal/hsm.js';
-import { hasInitialState, quoteError, defineStateName as defineStateNameInternal, getStateName } from './internal/utils.js';
-// 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}.
+ * ihsm — hierarchical state machines for TypeScript.
  *
- * 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
- */
-export 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 || (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
- */
-export 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);
-    }
-}
-/**
- * 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
- */
-export 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;
-    }
-}
-/**
- * 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
- */
-export 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;
-    }
-}
-/**
- * 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
- */
-export 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;
-    }
-}
-/**
- * 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
- */
-export 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;
-    }
-}
-/**
- * Thrown when {@link StateEvents.onExit} or {@link StateEvents.onEntry} throws during a transition.
- *
- * @category Error
- */
-export 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;
-    }
-}
-/**
- * Thrown when an event handler body throws and {@link StateEvents.onError} does not recover.
- *
- * @category Error
- */
-export 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);
-    }
-}
-/**
- * Thrown when no handler matches the dispatched event and {@link StateEvents.onUnhandled} rethrows.
- *
- * @category Error
- */
-export 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}`);
-    }
-}
-/**
- * Thrown at **class definition** time when {@link InitialState} is applied twice to one parent.
- *
- * @category Error
- */
-export 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 '${getStateName(Object.getPrototypeOf(targetState.prototype).constructor)}' must not have more than one initial state`);
-        this.name = 'InitialStateError';
-        this.targetStateName = getStateName(targetState);
-    }
-}
-/**
- * Thrown when {@link StateEvents.onError} itself throws, leaving the machine unrecoverable.
- *
- * @category Error
- */
-export 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 ${quoteError(cause)}`, cause);
-    }
-}
-/**
- * Thrown when {@link StateEvents.onEntry} fails during the initial `@InitialState` walk at startup.
- *
- * @category Error
- */
-export 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 ${getStateName(failedState)} has thrown ${quoteError(cause)} during initialization`, cause);
-        this.failedState = failedState;
-    }
-}
-/**
- * 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
- */
-export class FatalErrorState extends TopState {
-}
-defineStateNameInternal(TopState, 'TopState');
-defineStateNameInternal(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 {}
- * ```
- */
-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,
-    });
-}
-/**
- * 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
- */
-export function defineStateName(state, name) {
-    defineStateNameInternal(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
- */
-export function registerStateNames(exports) {
-    for (const [exportName, value] of Object.entries(exports)) {
-        if (isStateClass(value)) {
-            defineStateNameInternal(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. */
-export 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 */
-export const defaultTraceWriter = new ConsoleTraceWriter();
-const defaultTraceLevel = TraceLevel.DEBUG;
-/** @internal */
-export const 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
- */
-export function makeHsm(topState, ctx, initialize = defaultInitialize, traceLevel = defaultTraceLevel, traceWriter = 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 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
+ * Curated public runtime surface; protocol types live in {@link ./types}.
  */
-export function makeActor(topState, ctx, port, options = {}, ..._disjointGuard) {
-    const { initialize = defaultInitialize, traceLevel = defaultTraceLevel, traceWriter = defaultTraceWriter, dispatchErrorCallback = defaultDispatchErrorCallback } = options;
-    const hsm = instantiate(topState, ctx, initialize, traceLevel, traceWriter, dispatchErrorCallback, port);
-    return narrowToActor(hsm);
-}
+export { TraceLevel, asError, quoteUnknown, quoteError, getInitialState, hasInitialState, getTransitionKey, defineStateName, getStateName, Port, RequestingPort, TopState, HsmError, RuntimeError, TransitionError, EventHandlerError, UnhandledEventError, InitialStateError, FatalError, InitializationError, FatalErrorState, InitialState, registerStateNames, ProtocolCollisionError, ReservedNames, buildProtocolIndex, CallTimeoutError, SelfCallDeadlockError, TransitionTableError, planTransitionClasses, executeTransitionRoutine, createTransitionTracer, transitionTraceLines, RuntimeTransitionResolver, isRequestingPort, isServiceCallOptions, splitServiceArgs, serviceCallWithTimeout, currentTraceAnchor, defaultTraceWriter, defaultInitialize, defaultDispatchErrorCallback, makeActor, asParentActor, makeChildActor, kHandlerMachine, kParentLink, configureRunSeed, getRunSeed, getRunNamespace, mintActorIdentity, } from './internal/runtime.js';
+export { createConsoleInstrumentation } from './internal/console-instrumentation.js';
+export { registerCollector, clearCollectors, getCollectorCount } from './internal/instrumentation.js';
 //# sourceMappingURL=index.js.map