ihsm 0.1.1 → 0.1.22

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

@@ -1,5 +1,5 @@
 /** @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, TopStateArg, TraceWriter, DispatchErrorCallback, Transition, TransitionResolver, TransitionHost, TransitionRoutineExecuteOptions, TransitionRoutinePlan, TransitionTracer, Disposable, EventObserver, TransitionTraceHost } from './types';
+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';
 export declare enum TraceLevel {
     PRODUCTION = 0,
     DEBUG = 1,
@@ -103,6 +103,8 @@ export declare class InitializationError<C extends ActorConfig = ActorConfig> ex
 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;
@@ -144,7 +146,15 @@ export declare function splitServiceArgs(args: readonly unknown[]): {
     callArgs: unknown[];
     timeoutMs: number | undefined;
 };
-export declare function serviceCallWithTimeout<T>(promise: Promise<T>, method: string, timeoutMs: number): Promise<T>;
+/**
+ * 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 */
@@ -154,6 +164,18 @@ export declare function createSelfNotifications(machine: DispatchableMachine, to
 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;
@@ -168,6 +190,15 @@ export declare const dispatchContext: {
     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);
@@ -202,6 +233,9 @@ export declare class HsmObject<C extends ActorConfig> implements HsmWithTracing<
     topStateName: string;
     readonly ctxTypeName: string;
     traceWriter: TraceWriter;
+    readonly actorUuid: string;
+    readonly actorName: string;
+    readonly actorPath: string;
     /** @internal */
     _instance: Instance<C>;
     /** @internal */
@@ -216,10 +250,14 @@ export declare class HsmObject<C extends ActorConfig> implements HsmWithTracing<
     dispatchErrorCallback: DispatchErrorCallback<C>;
     private _traceLevel;
     private _traceDomainStack;
-    constructor(TopState: StateClass<C>, instance: Instance<C>, traceWriter: TraceWriter, traceLevel: TraceLevel, dispatchErrorCallback: DispatchErrorCallback<C>);
+    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;
@@ -232,7 +270,18 @@ export declare class HsmObject<C extends ActorConfig> implements HsmWithTracing<
     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;
@@ -247,26 +296,56 @@ export declare class HsmObject<C extends ActorConfig> implements HsmWithTracing<
     _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> {
+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, transitionResolver?: TransitionResolver<C>);
+    }, 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;
@@ -281,8 +360,11 @@ 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>): ActorHandleFor<C, K>;
+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>;
@@ -291,3 +373,4 @@ export declare function makeChildActor<ParentT extends TopStateArg<ActorConfig>,
     readonly parent: ParentActor<ParentT>;
 };
 export { kHandlerMachine, kParentLink } from './types';
+export { configureRunSeed, getRunSeed, getRunNamespace, actorNameFromTopState, mintActorIdentity, rootActorPath, childActorPath } from './identity';