ihsm 0.0.26 → 0.1.21

package/lib/esm/internal/runtime.d.ts

@@ -0,0 +1,376 @@
+/** @internal Consolidated ihsm runtime (no pure types — see ./types.ts). */
+import type { ActorConfig, ActorContextOf, ActorConfigOf, ActorOptions, ChildActor, ChildHsm, DispatchableMachine, EmbodimentKind, ErrorHost, ExternalActor, ExternalHsm, HandlerHsm, HsmWithTracing, InboundActor, InboundHsm, Instance, NotificationQueue, ParentActor, PlannedTransition, IPort, MachinePortInput, Properties, ProtocolIndex, RandomService, ReservedName, SelfNotifications, ServiceCallOptions, StateClass, StateEvents, Task, TimerService, TopStateArg, TraceWriter, DispatchErrorCallback, Transition, TransitionResolver, TransitionHost, TransitionRoutineExecuteOptions, TransitionRoutinePlan, TransitionTracer, Disposable, EventObserver, TransitionTraceHost, ActorIdentity, ActorLogger, Instrumentation, OutboundCallBegin, TraceFrame } from './types.js';
+export declare enum TraceLevel {
+    PRODUCTION = 0,
+    DEBUG = 1,
+    VERBOSE_DEBUG = 2
+}
+/** @internal */
+export declare function asError(err: unknown): Error;
+/** @internal */
+export declare function quoteUnknown(err: unknown): string;
+/** @internal */
+export declare function quoteError(err: Error): string;
+/** @internal */
+export declare function getInitialState<C extends ActorConfig>(State: StateClass<C>): StateClass<C>;
+/** @internal */
+export declare function hasInitialState<C extends ActorConfig>(State: StateClass<C>): boolean;
+/** @internal */
+export declare function getTransitionKey<C extends ActorConfig>(FromState: StateClass<C>, ToState: StateClass<C>): string;
+export declare function defineStateName<C extends ActorConfig>(state: StateClass<C>, displayName: string): void;
+/** @internal — prefers an own explicit name registered for minified browser bundles. */
+export declare function getStateName<C extends ActorConfig>(state: StateClass<C>): string;
+/** Production port: timers, randomness, and deferred self-notifications for one machine.
+ * @typeParam T - Root state **constructor** (`typeof DoorTop`), not the instance type. */
+export declare class Port<T extends TopStateArg = TopStateArg> implements IPort<ActorConfigOf<T>>, RandomService {
+    readonly __topState: T;
+    actor: InboundActor<ActorConfigOf<T>> | ChildActor<ActorConfigOf<T>>;
+    private _deferFactory?;
+    protected _timerSeq: number;
+    protected readonly _timeoutHandles: Map<number, NodeJS.Timeout>;
+    protected readonly _intervalHandles: Map<number, NodeJS.Timeout>;
+    /** Schedule a one-shot callback after `millis` milliseconds (platform timer). */
+    setTimeout(callback: () => void, millis?: number): number;
+    /** Cancel a timer previously returned by {@link Port.setTimeout}. */
+    clearTimeout(id: number | undefined): void;
+    /** Schedule a repeating callback every `millis` milliseconds. */
+    setInterval(callback: () => void, millis?: number): number;
+    /** Cancel an interval previously returned by {@link Port.setInterval}. */
+    clearInterval(id: number | undefined): void;
+    /** Pseudorandom number in `[0, 1)` — delegates to `Math.random()`. */
+    random(): number;
+    /** Cryptographic-quality random in `[0, 1)` when the platform provides it. */
+    cryptoRandom(): number;
+    /** Generate a UUID v4 string via `crypto.randomUUID()`. */
+    randomUUID(): string;
+    /** Fill `array` with cryptographically strong random bytes. */
+    getRandomValues<T extends ArrayBufferView>(array: T): T;
+    /** @internal Wired by {@link Machine.bindPort} — do not call from application code. */
+    bindDeferredNotifications(factory: (ms: number) => SelfNotifications<ActorConfigOf<T>>): void;
+    defer(ms: number): SelfNotifications<ActorConfigOf<T>>;
+}
+export declare abstract class RequestingPort<T extends TopStateArg = TopStateArg> extends Port<T> {
+    actor: ChildActor<ActorConfigOf<T>>;
+}
+export declare abstract class TopState<C extends ActorConfig = ActorConfig> implements StateEvents<C> {
+    readonly ctx: ActorContextOf<C>;
+    readonly hsm: HandlerHsm<C>;
+    readonly notify: SelfNotifications<C>;
+    readonly notifyNow: SelfNotifications<C>;
+    constructor();
+    onExit(): Promise<void> | void;
+    onEntry(): Promise<void> | void;
+    onError(error: RuntimeError<C>): Promise<void> | void;
+    onUnhandled(error: UnhandledEventError<C>): Promise<void> | void;
+}
+export declare abstract class HsmError<C extends ActorConfig = ActorConfig> extends Error {
+    name: string;
+    topStateName: string;
+    stateName: string;
+    context: ActorContextOf<C>;
+    cause?: Error;
+    protected constructor(name: string, hsm: ErrorHost<C>, message: string, cause?: Error);
+}
+export declare abstract class RuntimeError<C extends ActorConfig = ActorConfig, EventName extends string = string> extends HsmError<C> {
+    eventName: EventName;
+    eventPayload: unknown[];
+    protected constructor(errorName: string, hsm: ErrorHost<C>, message: string, cause?: Error);
+}
+export declare class TransitionError<C extends ActorConfig = ActorConfig, EventName extends string = string> extends RuntimeError<C, EventName> {
+    failedStateName: string;
+    failedCallback: 'onExit' | 'onEntry';
+    fromStateName: string;
+    toStateName: string;
+    constructor(hsm: ErrorHost<C>, cause: Error, failedStateName: string, failedCallback: 'onExit' | 'onEntry', fromStateName: string, toStateName: string);
+}
+export declare class EventHandlerError<C extends ActorConfig = ActorConfig, EventName extends string = string> extends RuntimeError<C, EventName> {
+    constructor(hsm: ErrorHost<C>, cause: Error);
+}
+export declare class UnhandledEventError<C extends ActorConfig = ActorConfig, EventName extends string = string> extends RuntimeError<C, EventName> {
+    constructor(hsm: ErrorHost<C>);
+}
+export declare class InitialStateError<C extends ActorConfig = ActorConfig> extends Error {
+    targetStateName: string;
+    constructor(targetState: StateClass<C>);
+}
+export declare class FatalError<C extends ActorConfig = ActorConfig, EventName extends string = string> extends RuntimeError<C, EventName> {
+    constructor(hsm: ErrorHost<C>, cause: Error);
+}
+export declare class InitializationError<C extends ActorConfig = ActorConfig> extends HsmError<C> {
+    failedState: StateClass<C>;
+    constructor(hsm: ErrorHost<C>, failedState: StateClass<C>, cause: Error);
+}
+export declare class FatalErrorState extends TopState {
+}
+/** @internal */
+export declare function lookupHandlerState<C extends ActorConfig>(hsm: HsmWithTracing<C>, eventName: PropertyKey): string | undefined;
+/** @internal */
+export declare function lookupEventHandler<C extends ActorConfig>(hsm: HsmWithTracing<C>, eventName: PropertyKey): ((...args: any[]) => unknown) | undefined;
+export declare function InitialState<C extends ActorConfig>(TargetState: StateClass<C>): void;
+export declare function registerStateNames(exports: Record<string, unknown>): void;
+/** Thrown at construction when `Config`, state handlers, and the protocol index disagree. */
+export declare class ProtocolCollisionError extends Error {
+    readonly stateClass?: string | undefined;
+    readonly symbol?: string | undefined;
+    private constructor();
+    static reservedOnState(stateClass: string, symbol: ReservedName): ProtocolCollisionError;
+}
+/** Per–root-state registry of state classes for protocol scanning. */
+export declare class StateGraph {
+    private readonly states;
+    register(state: StateClass): void;
+    collect(topState: StateClass): StateClass[];
+    static forRoot(root: StateClass): StateGraph;
+    private static collectAlongPrototypeChain;
+}
+export declare function cacheProtocolIndex(topState: object, index: ProtocolIndex): ProtocolIndex;
+export declare function protocolIndexFor(topState: object): ProtocolIndex | undefined;
+export declare const ReservedNames: readonly ["ctx", "hsm", "notify", "notifyNow", "onEntry", "onExit", "onError", "onUnhandled"];
+/** Build a protocol index by scanning handler methods on the state graph (`async` → services, otherwise notifications). */
+export declare function buildProtocolIndex(topState: StateClass): ProtocolIndex;
+/** Thrown when a service client call exceeds `{ timeoutMs }`. */
+export declare class CallTimeoutError extends Error {
+    readonly method: string;
+    constructor(method: string);
+}
+export declare const kMachine: unique symbol;
+/** @internal Actor handle prototype bag used when wiring generated facets. */
+export interface HandleOwn extends Record<symbol | string, unknown> {
+    [kMachine]: DispatchableMachine;
+    ctx?: unknown;
+    hsm: unknown;
+    parent?: ParentActor;
+}
+export declare function isServiceCallOptions(value: unknown): value is ServiceCallOptions;
+export declare function splitServiceArgs(args: readonly unknown[]): {
+    callArgs: unknown[];
+    timeoutMs: number | undefined;
+};
+/**
+ * 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 declare function serviceCallWithTimeout<T>(promise: Promise<T>, method: string, timeoutMs: number, timer?: TimerService): Promise<T>;
+/** @internal */
+export declare function createActorHandle(machine: DispatchableMachine, topState: object, index: ProtocolIndex, kind: EmbodimentKind): HandleOwn;
+/** @internal */
+export declare function getSelfNotificationsProto(topState: object, index: ProtocolIndex, queue: NotificationQueue): object;
+export declare function createSelfNotifications(machine: DispatchableMachine, topState: object, index: ProtocolIndex, queue: NotificationQueue): HandleOwn;
+/** Thrown in debug builds when a service targets the machine currently dispatching. */
+export declare class SelfCallDeadlockError extends Error {
+    constructor();
+}
+type DispatchToken = {
+    machine: DispatchableMachine;
+    actorUuid?: string;
+    macrostepId?: string;
+    stepSeq?: number;
+};
+interface InstrumentationHost {
+    onTaskBegin(task: Task): void;
+    onTaskEnd(task: Task, outcome: 'ok' | 'error'): void;
+    onQueuesDrained(): void;
+    onDispatchError(err: Error): void;
+}
+type AsyncLocalStorageCtor = new <T>() => {
+    run<R>(store: T, fn: () => R): R;
+    getStore(): T | undefined;
+};
+type DispatchAsyncLocalStorage = InstanceType<AsyncLocalStorageCtor>;
+/**
+ * Lazy Node AsyncLocalStorage for non-production deadlock detection.
+ * State lives in a closure — no exported mutable slot.
+ */
+export declare const dispatchContext: {
+    get: () => DispatchAsyncLocalStorage | undefined;
+    resetInit: () => void;
+    markUnavailable: () => void;
+};
+/**
+ * Best-effort current runtime trace anchor (`actorUuid`, `macrostepId`, `stepSeq`) for user code.
+ * Returns `undefined` when called outside an active handler dispatch turn.
+ */
+export declare function currentTraceAnchor(): {
+    readonly actorUuid: string;
+    readonly macrostepId?: string;
+    readonly stepSeq?: number;
+} | undefined;
+/** Thrown when a generated transition table's graph hash does not match the scanned hierarchy. */
+export declare class TransitionTableError extends Error {
+    constructor(message: string);
+}
+/** Compute the LCA transition path (same algorithm as `dispatch.production.ts`). */
+export declare function planTransitionClasses<C extends ActorConfig>(srcState: StateClass<C>, destState: StateClass<C>): PlannedTransition<C>;
+/**
+ * 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 declare function executeTransitionRoutine<C extends ActorConfig>(hsm: TransitionHost<C>, instance: object, plan: TransitionRoutinePlan<C> | PlannedTransition<C>, srcState: StateClass<C>, dstState: StateClass<C>, options?: TransitionRoutineExecuteOptions<C>): Promise<void>;
+export declare function createTransitionTracer(hsm: TransitionTraceHost): TransitionTracer;
+/** Collect canonical transition trace lines (for oracle comparison). */
+export declare function transitionTraceLines(lines: readonly string[]): string[];
+export declare class RuntimeTransitionResolver<C extends ActorConfig = ActorConfig> implements TransitionResolver<C> {
+    private readonly cache;
+    hasCached(src: StateClass<C>, dest: StateClass<C>): boolean;
+    resolve(src: StateClass<C>, dest: StateClass<C>): Transition<C>;
+}
+/** @internal */
+export declare function executePendingTransition<C extends ActorConfig>(host: HsmWithTracing<C>, resolver: TransitionResolver<C>): Promise<void>;
+/** @internal */
+export declare function createInitTask<C extends ActorConfig>(host: HsmWithTracing<C>, resolver: TransitionResolver<C>): Task;
+/** @internal */
+export declare function createNotificationTask<C extends ActorConfig>(host: HsmWithTracing<C>, resolver: TransitionResolver<C>, name: string, args: readonly unknown[]): Task;
+/** @internal */
+export declare function createServiceTask<C extends ActorConfig>(host: HsmWithTracing<C>, resolver: TransitionResolver<C>, name: string, args: readonly unknown[], resolve: (value: unknown) => void, reject: (error: Error) => void): Task;
+/** @internal */
+export declare class HsmObject<C extends ActorConfig> implements HsmWithTracing<C> {
+    topState: StateClass<C>;
+    topStateName: string;
+    readonly ctxTypeName: string;
+    traceWriter: TraceWriter;
+    readonly actorUuid: string;
+    readonly actorName: string;
+    readonly actorPath: string;
+    /** @internal */
+    _instance: Instance<C>;
+    /** @internal */
+    _jobs: Task[];
+    /** @internal */
+    _hiPriorityJobs: Task[];
+    private _isRunning;
+    _transitionState?: StateClass<C>;
+    _currentEventName?: string;
+    _currentEventPayload?: unknown[];
+    private _observers?;
+    dispatchErrorCallback: DispatchErrorCallback<C>;
+    private _traceLevel;
+    private _traceDomainStack;
+    protected _instrumentationHost?: InstrumentationHost;
+    private _drainWaiters;
+    constructor(TopState: StateClass<C>, instance: Instance<C>, traceWriter: TraceWriter, traceLevel: TraceLevel, dispatchErrorCallback: DispatchErrorCallback<C>, identity: ActorIdentity);
+    get ctx(): ActorContextOf<C>;
+    set ctx(ctx: ActorContextOf<C>);
+    get port(): unknown;
+    /** The bound port when it provides a timer service, so service-call timeouts honour a virtual clock. */
+    get callTimer(): TimerService | undefined;
+    get eventName(): string;
+    get eventPayload(): unknown[];
+    get currentStateName(): string;
+    get currentState(): StateClass<C>;
+    set currentState(newState: StateClass<C>);
+    subscribe(observer: EventObserver): Disposable;
+    private _notifyObservers;
+    protected recordObserverEvent(eventName: string | number | symbol, eventPayload: unknown[]): void;
+    transition(nextState: StateClass<C>): void;
+    unhandled(): never;
+    get traceLevel(): TraceLevel;
+    set traceLevel(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(): Promise<void>;
+    /** Invoke the user dispatch-error callback, first notifying instrumentation (pure observer). */
+    reportDispatchError(err: Error): void;
+    private flushDrainWaiters;
+    pushTask(t: Task): void;
+    pushHiPriorityTask(t: Task): void;
+    unshiftHiPriorityTask(t: Task): void;
+    private enqueueTask;
+    restore(state: StateClass<C>, ctx: ActorContextOf<C>): void;
+    private dequeue;
+    private exec;
+    private runTask;
+    private drainHiPriority;
+    _tracePush(d: string, msg: string): void;
+    _tracePopDone(msg: string): void;
+    _tracePopError(msg: string): void;
+    _traceWrite(msg: any): void;
+    get traceHeader(): string;
+    get traceFrames(): readonly TraceFrame[];
+}
+export declare class Machine<C extends ActorConfig> extends HsmObject<C> implements InstrumentationHost {
+    readonly transitionResolver: TransitionResolver<C>;
+    readonly identity: ActorIdentity;
+    readonly instrumentation?: Instrumentation<C>;
+    private _dispatchStrategy;
+    private readonly protocolIndex;
+    private readonly handlerFacade;
+    private readonly selfActor;
+    private readonly selfImmediate;
+    private readonly actorFacades;
+    private _macrostepCounter;
+    private _currentMacrostep?;
+    private _microstepFromState?;
+    private readonly _childSpawnCounters;
+    private _nextTraceCallId;
+    private _proxiedPort?;
+    constructor(topState: StateClass<C>, instance: {
+        ctx: ActorContextOf<C>;
+        hsm: HandlerHsm<C>;
+        portRef?: unknown;
+    }, protocolIndex: ProtocolIndex, traceWriter: TraceWriter, traceLevel: TraceLevel, dispatchErrorCallback: DispatchErrorCallback<C>, initialize: boolean, identity: ActorIdentity, instrumentation: Instrumentation<C> | undefined, transitionResolver?: TransitionResolver<C>);
+    allocateChildSpawnIndex(childTopName: string): number;
+    needsDispatchContext(): boolean;
+    buildDispatchToken(): DispatchToken;
+    private readDispatchCause;
+    private nextTraceCallId;
+    private beginPortCall;
+    private endPortCall;
+    beginOutboundCall(service: string, targetUuid?: string): OutboundCallBegin | undefined;
+    endOutboundCall(begin: OutboundCallBegin | undefined, outcome: 'ok' | 'error', error?: Error): void;
+    private slotBucket;
+    onTaskBegin(task: Task): void;
+    onTaskEnd(task: Task, outcome: 'ok' | 'error'): void;
+    onDispatchError(err: Error): void;
+    onQueuesDrained(): void;
+    private resolveEnqueueCause;
+    private enqueueWithInstrumentation;
+    get traceLevel(): TraceLevel;
+    set traceLevel(traceLevel: TraceLevel);
+    dispatchService(name: string, args: unknown[]): Promise<unknown>;
+    dispatchNotification(name: string, args: unknown[], queue: NotificationQueue): void;
+    actorHsmFor(kind: EmbodimentKind): ExternalHsm<C> | InboundHsm<C> | ChildHsm<C>;
+    private scheduleNotification;
+    private enqueueTimerNotification;
+    private _actorLogger?;
+    /** Severity-typed handler logger surfaced as `this.hsm.log.*` (CORE-F, §4.10.1). */
+    get logger(): ActorLogger;
+    private emitUserLog;
+    /** @internal Binds deferred self-notifications to a port instance. */
+    bindPort(portRef: unknown): void;
+    private buildHandlerFacade;
+    private createDeferredSelfNotifications;
+    private buildActorHsm;
+}
+export declare function isRequestingPort(port: unknown): boolean;
+/** @internal */
+export declare const defaultTraceWriter: TraceWriter;
+/** @internal */
+export declare const defaultInitialize = true;
+/** @internal */
+export declare function defaultDispatchErrorCallback<C extends ActorConfig>(hsm: Properties<C>, err: Error): void;
+type ActorHandleFor<C extends ActorConfig, K extends EmbodimentKind> = K extends 'root' ? ExternalActor<C> : K extends 'inbound' ? InboundActor<C> : ChildActor<C>;
+type SpawnContext<C extends ActorConfig = ActorConfig> = {
+    readonly parentMachine?: Machine<C>;
+};
+/** @internal Spawn with embodiment kind — used by factories and `ihsm/testing`. */
+export declare function spawnActor<C extends ActorConfig, K extends EmbodimentKind>(kind: K, topState: TopStateArg<C>, ctx: ActorContextOf<C>, port: MachinePortInput<C> | undefined, options: ActorOptions<C>, spawnContext?: SpawnContext<C>): ActorHandleFor<C, K>;
+/** Production black-box — public protocol only (generated handle). */
+export declare function makeActor<T extends TopStateArg<ActorConfig>>(topState: T, ctx: ActorContextOf<ActorConfigOf<T>>, port?: MachinePortInput<ActorConfigOf<T>>, options?: ActorOptions<ActorConfigOf<T>>): ExternalActor<ActorConfigOf<T>>;
+export declare function asParentActor<T extends TopStateArg<ActorConfig>>(handler: TopState<ActorConfigOf<T>>): ParentActor<T>;
+/** Parent composes a child machine — returns full child protocol shell with `parent` set. */
+export declare function makeChildActor<ParentT extends TopStateArg<ActorConfig>, ChildT extends TopStateArg<ActorConfig>>(parent: ParentActor<ParentT>, childTop: ChildT, childCtx: ActorContextOf<ActorConfigOf<ChildT>>, port?: MachinePortInput<ActorConfigOf<ChildT>>, options?: ActorOptions<ActorConfigOf<ChildT>>): ChildActor<ActorConfigOf<ChildT>> & {
+    readonly parent: ParentActor<ParentT>;
+};
+export { kHandlerMachine, kParentLink } from './types.js';
+export { configureRunSeed, getRunSeed, getRunNamespace, actorNameFromTopState, mintActorIdentity, rootActorPath, childActorPath } from './identity.js';