ihsm 0.1.1 → 0.1.21

package/lib/esm/internal/runtime.js

@@ -1,4 +1,6 @@
 import { kHandlerMachine, kParentLink } from './types.js';
+import { actorNameFromTopState, childActorPath, mintActorIdentity, rootActorPath } from './identity.js';
+import { getActiveInstrumentation, getTaskMeta, notifyActorCreated, notifyActorSpawned, notifyEnqueue, notifyError, notifyLog, notifyMacrostepBegin, notifyMacrostepEnd, notifyMicrostepBegin, notifyMicrostepEnd, notifyOutboundCallBegin, notifyOutboundCallEnd, notifyPortCallBegin, notifyPortCallEnd, setTaskMeta } from './instrumentation.js';
 //#region TraceLevel
 export var TraceLevel;
 (function (TraceLevel) {
@@ -220,6 +222,20 @@ export class FatalErrorState extends TopState {
 defineStateName(TopState, 'TopState');
 defineStateName(FatalErrorState, 'FatalErrorState');
 /** @internal */
+export function lookupHandlerState(hsm, eventName) {
+    let state = hsm.currentState;
+    while (true) {
+        const prototype = state.prototype;
+        if (Object.prototype.hasOwnProperty.call(prototype, eventName)) {
+            return getStateName(state);
+        }
+        if (state === TopState) {
+            return undefined;
+        }
+        state = Object.getPrototypeOf(state);
+    }
+}
+/** @internal */
 export function lookupEventHandler(hsm, eventName) {
     let state = hsm.currentState;
     while (true) {
@@ -444,19 +460,29 @@ export function splitServiceArgs(args) {
     }
     return { callArgs: args.slice(0, -1), timeoutMs };
 }
-export function serviceCallWithTimeout(promise, method, timeoutMs) {
+/**
+ * Race a service-call promise against a `timeoutMs` deadline.
+ *
+ * The deadline is armed through `timer` — the actor's port timer service — so that under a
+ * {@link TestPort} virtual clock a call timeout is driven by `port.advance(...)` and stays
+ * fully deterministic. When no port timer is available the host timer is used (production
+ * `Port` already delegates to the host timer, so behaviour there is unchanged).
+ */
+export function serviceCallWithTimeout(promise, method, timeoutMs, timer) {
     if (timeoutMs === 0) {
         return Promise.reject(new CallTimeoutError(method));
     }
+    const arm = (callback) => (timer !== undefined ? timer.setTimeout(callback, timeoutMs) : globalThis.setTimeout(callback, timeoutMs));
+    const disarm = (handle) => (timer !== undefined ? timer.clearTimeout(handle) : globalThis.clearTimeout(handle));
     return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => {
+        const handle = arm(() => {
             reject(new CallTimeoutError(method));
-        }, timeoutMs);
+        });
         promise.then(value => {
-            clearTimeout(timer);
+            disarm(handle);
             resolve(value);
         }, err => {
-            clearTimeout(timer);
+            disarm(handle);
             reject(err);
         });
     });
@@ -488,8 +514,17 @@ function getFacetProto(topState, index, kind, facet) {
             if (facet === 'call') {
                 built[name] = function (...args) {
                     const { callArgs, timeoutMs } = splitServiceArgs(args);
-                    const promise = this[kMachine].dispatchService(name, callArgs);
-                    return timeoutMs === undefined ? promise : serviceCallWithTimeout(promise, name, timeoutMs);
+                    const machine = this[kMachine];
+                    const begin = machine.beginOutboundCall?.(name, machine.actorUuid);
+                    const promise = machine.dispatchService(name, callArgs).then(value => {
+                        machine.endOutboundCall?.(begin, 'ok');
+                        return value;
+                    }, cause => {
+                        const err = asError(cause);
+                        machine.endOutboundCall?.(begin, 'error', err);
+                        throw err;
+                    });
+                    return timeoutMs === undefined ? promise : serviceCallWithTimeout(promise, name, timeoutMs, machine.callTimer);
                 };
             }
             else {
@@ -526,6 +561,12 @@ export function createActorHandle(machine, topState, index, kind) {
     Object.defineProperty(handle, 'notify', { value: createFacet(machine, topState, index, kind, 'notify'), enumerable: true });
     Object.defineProperty(handle, 'notifyNow', { value: createFacet(machine, topState, index, kind, 'notifyNow'), enumerable: true });
     Object.defineProperty(handle, 'call', { value: createFacet(machine, topState, index, kind, 'call'), enumerable: true });
+    Object.defineProperty(handle, 'id', {
+        enumerable: true,
+        get() {
+            return machine.actorUuid;
+        },
+    });
     handle.hsm = machine.actorHsmFor(kind);
     return handle;
 }
@@ -567,6 +608,18 @@ export class SelfCallDeadlockError extends Error {
         this.name = 'SelfCallDeadlockError';
     }
 }
+function errorPhaseFromError(err) {
+    if (err instanceof TransitionError) {
+        return err.failedCallback === 'onEntry' ? 'onEntry' : 'onExit';
+    }
+    if (err instanceof UnhandledEventError)
+        return 'unhandled';
+    if (err instanceof InitializationError)
+        return 'initialize';
+    if (err instanceof EventHandlerError)
+        return 'handler';
+    return 'handler';
+}
 /**
  * Lazy Node AsyncLocalStorage for non-production deadlock detection.
  * State lives in a closure — no exported mutable slot.
@@ -601,6 +654,45 @@ export const dispatchContext = (() => {
     }
     return { get, resetInit, markUnavailable };
 })();
+/**
+ * Best-effort current runtime trace anchor (`actorUuid`, `macrostepId`, `stepSeq`) for user code.
+ * Returns `undefined` when called outside an active handler dispatch turn.
+ */
+export function currentTraceAnchor() {
+    const token = dispatchContext.get()?.getStore();
+    if (token?.actorUuid === undefined)
+        return undefined;
+    return {
+        actorUuid: token.actorUuid,
+        macrostepId: token.macrostepId,
+        stepSeq: token.stepSeq,
+    };
+}
+/** Lazy ALS carrying the currently-executing proxied port call (when instrumentation is active). */
+const portCallContext = (() => {
+    let storage = undefined;
+    function get() {
+        if (storage !== undefined) {
+            return storage ?? undefined;
+        }
+        if (typeof process === 'undefined' || process.versions?.node === undefined) {
+            storage = null;
+            return undefined;
+        }
+        try {
+            // Dynamic require — keeps browser bundles free of `node:async_hooks`.
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const hooks = require('node:async_hooks');
+            storage = new hooks.AsyncLocalStorage();
+            return storage;
+        }
+        catch {
+            storage = null;
+            return undefined;
+        }
+    }
+    return { get };
+})();
 //#region transition-routines
 /** Thrown when a generated transition table's graph hash does not match the scanned hierarchy. */
 export class TransitionTableError extends Error {
@@ -651,10 +743,14 @@ export function planTransitionClasses(srcState, destState) {
     }
     return { exit: srcPath, entry: dstPath, finalState };
 }
-async function invokeLifecycleHook(hsm, instance, state, hook, fromStateName, toStateName, style, tracer) {
+async function invokeLifecycleHook(hsm, instance, state, hook, fromStateName, toStateName, style, tracer, hookEvents) {
     const statePrototype = state.prototype;
     const stateName = getStateName(state);
     const hasHook = Object.prototype.hasOwnProperty.call(statePrototype, hook);
+    // Emit hook tracer callbacks for real (own) hooks at verbose, or always for a structural seam
+    // (instrumentation) whose entry/exit spans are not TraceLevel-gated (spec §4.8). Skipped default
+    // hooks are never eventized.
+    const emitHookEvents = (style === 'verbose' || hookEvents) && hasHook;
     if ((style === 'verbose' || style === 'debug') && !hasHook) {
         if (style === 'verbose') {
             tracer?.traceHookSkipped(stateName, hook);
@@ -662,16 +758,19 @@ async function invokeLifecycleHook(hsm, instance, state, hook, fromStateName, to
         return;
     }
     try {
+        if (emitHookEvents) {
+            tracer?.traceHookStart?.(stateName, hook);
+        }
         const res = statePrototype[hook].call(instance);
         if (res) {
             await res;
         }
-        if (style === 'verbose') {
+        if (emitHookEvents) {
             tracer?.traceHookDone(stateName, hook);
         }
     }
     catch (cause) {
-        if (style === 'verbose') {
+        if (emitHookEvents) {
             tracer?.traceHookError(stateName, hook, cause);
         }
         throw new TransitionError(hsm, asError(cause), stateName, hook, fromStateName, toStateName);
@@ -685,16 +784,27 @@ async function invokeLifecycleHook(hsm, instance, state, hook, fromStateName, to
 export async function executeTransitionRoutine(hsm, instance, plan, srcState, dstState, options = {}) {
     const style = options.style ?? 'production';
     const tracer = options.tracer;
+    const hookEvents = options.hookEvents ?? false;
     const fromStateName = getStateName(srcState);
     const toStateName = getStateName(dstState);
-    if (style === 'verbose' || style === 'debug') {
-        tracer?.traceTransitionStart(fromStateName, toStateName);
-    }
+    // The structural transition span fires whenever a tracer is attached (the instrumentation seam is
+    // not TraceLevel-gated); the console tracer is only ever supplied off-PRODUCTION, so this is a
+    // no-op there unless an explicit instrumentation tracer is present.
+    tracer?.traceTransitionStart(fromStateName, toStateName);
     for (const state of plan.exit) {
-        await invokeLifecycleHook(hsm, instance, state, 'onExit', fromStateName, toStateName, style, tracer);
+        await invokeLifecycleHook(hsm, instance, state, 'onExit', fromStateName, toStateName, style, tracer, hookEvents);
     }
+    let initializeOpened = false;
     for (const state of plan.entry) {
-        await invokeLifecycleHook(hsm, instance, state, 'onEntry', fromStateName, toStateName, style, tracer);
+        if (!initializeOpened && state !== dstState) {
+            tracer?.traceInitializeStart?.(toStateName);
+            initializeOpened = true;
+        }
+        await invokeLifecycleHook(hsm, instance, state, 'onEntry', fromStateName, toStateName, style, tracer, hookEvents);
+    }
+    if (initializeOpened) {
+        const finalName = plan.finalState !== undefined ? getStateName(plan.finalState) : toStateName;
+        tracer?.traceInitializeDone?.(finalName);
     }
     const applyState = (next) => {
         if (options.setCurrentState) {
@@ -717,6 +827,8 @@ export async function executeTransitionRoutine(hsm, instance, plan, srcState, ds
     }
     if (plan.finalState) {
         applyState(plan.finalState);
+        // Close the structural transition span on the PRODUCTION path (verbose/debug returned above).
+        tracer?.traceTransitionDone(getStateName(plan.finalState));
     }
 }
 export function createTransitionTracer(hsm) {
@@ -724,6 +836,12 @@ export function createTransitionTracer(hsm) {
         traceTransitionStart(fromStateName, toStateName) {
             hsm._tracePush(`transition from ${fromStateName} to ${toStateName}`, `started transition from ${fromStateName} to ${toStateName} `);
         },
+        traceInitializeStart(stateName) {
+            hsm._tracePush(`initialize ${stateName}`, `started initialize drill-down from ${stateName}`);
+        },
+        traceInitializeDone(finalStateName) {
+            hsm._tracePopDone(`done initialize drill-down at ${finalStateName}`);
+        },
         traceHookDone(stateName, hook) {
             hsm._traceWrite(`${stateName}.${hook}() done`);
         },
@@ -755,9 +873,15 @@ class RuntimeTransitionRoutine {
     }
     async execute(hsm, srcState, dstState) {
         const style = hsm.traceLevel === TraceLevel.PRODUCTION ? 'production' : hsm.traceLevel === TraceLevel.DEBUG ? 'debug' : 'verbose';
+        const machine = hsm;
+        const instTracer = machine.instrumentation?.transition;
+        const tracer = instTracer ?? (style !== 'production' ? createTransitionTracer(hsm) : undefined);
         await executeTransitionRoutine(hsm, hsm._instance, this.plan, srcState, dstState, {
             style,
-            ...(style !== 'production' ? { tracer: createTransitionTracer(hsm) } : {}),
+            ...(tracer !== undefined ? { tracer } : {}),
+            // The instrumentation seam's entry/exit spans are structural (not TraceLevel-gated); the
+            // console tracer keeps its verbose-only gating.
+            hookEvents: instTracer !== undefined,
             setCurrentState: state => {
                 hsm.currentState = state;
             },
@@ -1350,42 +1474,60 @@ export function createInitTask(host, resolver) {
             .then(() => executePendingTransition(host, resolver))
             .then(() => done())
             .catch((err) => {
-            host.dispatchErrorCallback(host, asError(err));
+            host.reportDispatchError(asError(err));
             done();
         });
     };
 }
+/**
+ * Run a dispatch body inside the ambient `dispatchContext` token so that any `notify`/`call`/timer
+ * the handler issues can be attributed to the running `(macrostepId, stepSeq)` (CORE-B, §5.6.3).
+ * Falls back to a plain run when no ALS is available (browser) or the host predates the seam.
+ */
+function runWithinDispatch(host, run) {
+    const machine = host;
+    const wants = machine.needsDispatchContext?.() ?? host.traceLevel !== TraceLevel.PRODUCTION;
+    if (!wants) {
+        run();
+        return;
+    }
+    const storage = dispatchContext.get();
+    if (storage === undefined) {
+        run();
+        return;
+    }
+    const token = machine.buildDispatchToken?.() ?? { machine: host };
+    storage.run(token, run);
+}
+function currentPortCallToken() {
+    const storage = portCallContext.get();
+    return storage?.getStore();
+}
 /** @internal */
 export function createNotificationTask(host, resolver, name, args) {
     const strategy = dispatchStrategyFor(host.traceLevel);
     return (done) => {
-        strategy
-            .dispatchEvent(host, resolver, name, ...args)
-            .catch((err) => host.dispatchErrorCallback(host, asError(err)))
-            .finally(() => done());
+        runWithinDispatch(host, () => {
+            void strategy
+                .dispatchEvent(host, resolver, name, ...args)
+                .catch((err) => host.reportDispatchError(asError(err)))
+                .finally(() => done());
+        });
     };
 }
 /** @internal */
 export function createServiceTask(host, resolver, name, args, resolve, reject) {
-    const machine = host;
     return (done) => {
         const run = () => invokeHandler(host, resolver, name, args)
             .then(resolve)
             .catch((err) => {
             reject(asError(err));
         })
-            .catch((err) => host.dispatchErrorCallback(host, asError(err)))
+            .catch((err) => host.reportDispatchError(asError(err)))
             .finally(() => done());
-        if (host.traceLevel === TraceLevel.PRODUCTION) {
+        runWithinDispatch(host, () => {
             void run();
-            return;
-        }
-        const storage = dispatchContext.get();
-        if (storage === undefined) {
-            void run();
-            return;
-        }
-        void storage.run({ machine }, run);
+        });
     };
 }
 //#endregion
@@ -1396,6 +1538,9 @@ export class HsmObject {
     topStateName;
     ctxTypeName;
     traceWriter;
+    actorUuid;
+    actorName;
+    actorPath;
     /** @internal */
     _instance;
     /** @internal */
@@ -1410,7 +1555,9 @@ export class HsmObject {
     dispatchErrorCallback;
     _traceLevel;
     _traceDomainStack;
-    constructor(TopState, instance, traceWriter, traceLevel, dispatchErrorCallback) {
+    _instrumentationHost;
+    _drainWaiters = [];
+    constructor(TopState, instance, traceWriter, traceLevel, dispatchErrorCallback, identity) {
         this._instance = instance;
         this._transitionState = undefined;
         this._traceLevel = traceLevel;
@@ -1420,6 +1567,9 @@ export class HsmObject {
         this._jobs = [];
         this._hiPriorityJobs = [];
         this._isRunning = false;
+        this.actorUuid = identity.uuid;
+        this.actorName = identity.name;
+        this.actorPath = identity.path;
         this.topState = TopState;
         this.topStateName = getStateName(TopState);
         this.ctxTypeName = Object.getPrototypeOf(instance.ctx).constructor.name;
@@ -1436,6 +1586,14 @@ export class HsmObject {
     get port() {
         return this._instance.portRef;
     }
+    /** The bound port when it provides a timer service, so service-call timeouts honour a virtual clock. */
+    get callTimer() {
+        const port = this._instance.portRef;
+        if (port !== undefined && typeof port.setTimeout === 'function' && typeof port.clearTimeout === 'function') {
+            return port;
+        }
+        return undefined;
+    }
     get eventName() {
         return this._currentEventName ?? '';
     }
@@ -1483,14 +1641,37 @@ export class HsmObject {
     set traceLevel(traceLevel) {
         this._traceLevel = traceLevel;
     }
+    /**
+     * Resolve when the actor next reaches stability (mailbox fully drained).
+     *
+     * The resolver fires at the queue-drain point — *after* {@link InstrumentationHost.onQueuesDrained}
+     * — so the closing `macrostep.end` and the macrostep-boundary reset are observable before `sync()`
+     * resolves, and a subsequent external stimulus deterministically starts its own macrostep. The
+     * pushed task is a no-op (internal) whose only purpose is to guarantee a drain cycle occurs.
+     */
     sync() {
         return new Promise(resolve => {
-            this.pushTask((doneCallback) => {
-                resolve();
+            this._drainWaiters.push(resolve);
+            const task = (doneCallback) => {
                 doneCallback();
-            });
+            };
+            setTaskMeta(task, { internal: true });
+            this.pushTask(task);
         });
     }
+    /** Invoke the user dispatch-error callback, first notifying instrumentation (pure observer). */
+    reportDispatchError(err) {
+        this._instrumentationHost?.onDispatchError(err);
+        this.dispatchErrorCallback(this, err);
+    }
+    flushDrainWaiters() {
+        if (this._drainWaiters.length === 0)
+            return;
+        const waiters = this._drainWaiters;
+        this._drainWaiters = [];
+        for (const resolve of waiters)
+            resolve();
+    }
     pushTask(t) {
         this.enqueueTask(t, this._jobs);
     }
@@ -1518,6 +1699,8 @@ export class HsmObject {
     dequeue() {
         if (this._hiPriorityJobs.length == 0 && this._jobs.length == 0) {
             this._isRunning = false;
+            this._instrumentationHost?.onQueuesDrained();
+            this.flushDrainWaiters();
             return;
         }
         const task = this._hiPriorityJobs.length > 0 ? this._hiPriorityJobs.shift() : this._jobs.shift();
@@ -1527,10 +1710,32 @@ export class HsmObject {
         setTimeout(() => this.runTask(task).then(() => this.dequeue()), 0);
     }
     runTask(task) {
+        this._instrumentationHost?.onTaskBegin(task);
+        let outcome = 'ok';
         return new Promise(resolve => {
-            task(() => {
-                this.drainHiPriority().then(resolve);
-            });
+            const runBody = () => {
+                task(() => {
+                    this.drainHiPriority()
+                        .then(() => {
+                        this._instrumentationHost?.onTaskEnd(task, outcome);
+                        resolve();
+                    })
+                        .catch((_err) => {
+                        outcome = 'error';
+                        this._instrumentationHost?.onTaskEnd(task, outcome);
+                        resolve();
+                    });
+                });
+            };
+            try {
+                runBody();
+            }
+            catch (err) {
+                outcome = 'error';
+                this._instrumentationHost?.onTaskEnd(task, outcome);
+                resolve();
+                throw asError(err);
+            }
         });
     }
     drainHiPriority() {
@@ -1558,18 +1763,51 @@ export class HsmObject {
     get traceHeader() {
         return `${this._traceDomainStack.length === 0 ? '' : this._traceDomainStack.join('|') + '|'}`;
     }
+    get traceFrames() {
+        return this._traceDomainStack.map(name => ({ name, kind: classifyFrameKind(name) }));
+    }
+}
+/** Best-effort classification of a live trace-domain name into a structured {@link TraceFrame.kind}. */
+function classifyFrameKind(name) {
+    if (name.startsWith('#'))
+        return 'event';
+    if (name === 'execute')
+        return 'handler';
+    if (name === 'initialize' || name.startsWith('initialize'))
+        return 'initialize';
+    if (name.startsWith('transition'))
+        return 'transition';
+    if (name.includes('onEntry'))
+        return 'onEntry';
+    if (name.includes('onExit'))
+        return 'onExit';
+    return 'handler';
 }
 //#region machine
 export class Machine extends HsmObject {
     transitionResolver;
+    identity;
+    instrumentation;
     _dispatchStrategy;
     protocolIndex;
     handlerFacade;
     selfActor;
     selfImmediate;
     actorFacades = new Map();
-    constructor(topState, instance, protocolIndex, traceWriter, traceLevel, dispatchErrorCallback, initialize, transitionResolver) {
-        super(topState, instance, traceWriter, traceLevel, dispatchErrorCallback);
+    _macrostepCounter = 0;
+    _currentMacrostep;
+    _microstepFromState;
+    _childSpawnCounters = new Map();
+    _nextTraceCallId = 0;
+    _proxiedPort;
+    constructor(topState, instance, protocolIndex, traceWriter, traceLevel, dispatchErrorCallback, initialize, identity, instrumentation, transitionResolver) {
+        super(topState, instance, traceWriter, traceLevel, dispatchErrorCallback, identity);
+        this.identity = identity;
+        this.instrumentation = instrumentation;
+        if (instrumentation !== undefined) {
+            this._instrumentationHost = this;
+            notifyActorCreated(instrumentation, identity);
+        }
         Object.defineProperty(instance, kHandlerMachine, { value: this, enumerable: false, writable: false, configurable: false });
         this.protocolIndex = protocolIndex;
         cacheProtocolIndex(topState, protocolIndex);
@@ -1583,7 +1821,227 @@ export class Machine extends HsmObject {
         Object.defineProperty(instance, 'notifyNow', { value: this.selfImmediate, enumerable: true, configurable: true });
         this.bindPort(instance.portRef);
         if (initialize) {
-            this.pushTask(createInitTask(this, this.transitionResolver));
+            const initTask = createInitTask(this, this.transitionResolver);
+            setTaskMeta(initTask, { event: 'initialize', queue: 'default', triggerKind: 'init', internal: false });
+            this.pushTask(initTask);
+        }
+    }
+    allocateChildSpawnIndex(childTopName) {
+        const childName = actorNameFromTopState(childTopName);
+        const index = this._childSpawnCounters.get(childName) ?? 0;
+        this._childSpawnCounters.set(childName, index + 1);
+        return index;
+    }
+    needsDispatchContext() {
+        return this.instrumentation !== undefined || this.traceLevel !== TraceLevel.PRODUCTION;
+    }
+    buildDispatchToken() {
+        return {
+            machine: this,
+            actorUuid: this.actorUuid,
+            macrostepId: this._currentMacrostep?.id,
+            stepSeq: this._currentMacrostep?.stepSeq,
+        };
+    }
+    readDispatchCause(kind) {
+        const storage = dispatchContext.get();
+        const token = storage?.getStore();
+        if (token?.actorUuid === undefined)
+            return undefined;
+        return {
+            actorUuid: token.actorUuid,
+            macrostepId: token.macrostepId,
+            stepSeq: token.stepSeq,
+            kind,
+        };
+    }
+    nextTraceCallId() {
+        this._nextTraceCallId += 1;
+        return this._nextTraceCallId;
+    }
+    beginPortCall(method) {
+        if (this.instrumentation === undefined)
+            return undefined;
+        const cause = this.readDispatchCause('wire');
+        const info = {
+            callId: this.nextTraceCallId(),
+            method,
+            cause,
+        };
+        notifyPortCallBegin(this.instrumentation, info);
+        return info;
+    }
+    endPortCall(begin, outcome, error) {
+        if (this.instrumentation === undefined || begin === undefined)
+            return;
+        const info = {
+            callId: begin.callId,
+            method: begin.method,
+            outcome,
+            error,
+        };
+        notifyPortCallEnd(this.instrumentation, info);
+    }
+    beginOutboundCall(service, targetUuid) {
+        if (this.instrumentation === undefined)
+            return undefined;
+        const portToken = currentPortCallToken();
+        const cause = this.readDispatchCause('wire') ?? portToken?.cause;
+        const info = {
+            callId: this.nextTraceCallId(),
+            service,
+            targetUuid,
+            cause,
+        };
+        notifyOutboundCallBegin(this.instrumentation, info);
+        return info;
+    }
+    endOutboundCall(begin, outcome, error) {
+        if (this.instrumentation === undefined || begin === undefined)
+            return;
+        const info = {
+            callId: begin.callId,
+            service: begin.service,
+            outcome,
+            error,
+        };
+        notifyOutboundCallEnd(this.instrumentation, info);
+    }
+    slotBucket(eventName) {
+        return this.protocolIndex.get(eventName)?.bucket ?? 'notifications';
+    }
+    onTaskBegin(task) {
+        const meta = getTaskMeta(task);
+        if (meta?.internal === true || this.instrumentation === undefined)
+            return;
+        if (this._currentMacrostep === undefined) {
+            const id = `${this.actorUuid}:${++this._macrostepCounter}`;
+            const trigger = meta?.event ?? 'unknown';
+            const triggerKind = meta?.triggerKind ?? (this._jobs.length + this._hiPriorityJobs.length > 0 ? 'self' : 'external');
+            this._currentMacrostep = {
+                id,
+                trigger,
+                triggerKind,
+                startState: this.currentStateName,
+                stepSeq: -1,
+                transitioned: false,
+                outcome: 'ok',
+                cause: meta?.cause,
+            };
+            notifyMacrostepBegin(this.instrumentation, {
+                id,
+                actor: this.identity,
+                trigger,
+                triggerKind,
+                startState: this.currentStateName,
+                cause: meta?.cause,
+                delayMs: meta?.delayMs,
+            });
+        }
+        const macrostep = this._currentMacrostep;
+        macrostep.stepSeq += 1;
+        const seq = macrostep.stepSeq;
+        const fromState = this.currentStateName;
+        this._microstepFromState = fromState;
+        // Stamp seq + fromState on the task so onTaskEnd pairs correctly even when nested priority
+        // drains mutate the shared macrostep counter between this task's begin and end.
+        if (meta !== undefined) {
+            meta.seq = seq;
+            meta.fromState = fromState;
+        }
+        else {
+            setTaskMeta(task, { seq, fromState });
+        }
+        const eventName = meta?.event ?? this.eventName ?? 'unknown';
+        const handlerState = lookupHandlerState(this, eventName);
+        const storage = dispatchContext.get();
+        const runMicrostep = () => {
+            notifyMicrostepBegin(this.instrumentation, {
+                macrostepId: macrostep.id,
+                seq,
+                event: eventName,
+                bucket: this.slotBucket(eventName),
+                queue: meta?.queue ?? 'default',
+                fromState: this.currentStateName,
+                handlerState,
+                cause: meta?.cause,
+            });
+        };
+        if (storage !== undefined && this.needsDispatchContext()) {
+            storage.run(this.buildDispatchToken(), runMicrostep);
+        }
+        else {
+            runMicrostep();
+        }
+    }
+    onTaskEnd(task, outcome) {
+        const meta = getTaskMeta(task);
+        if (meta?.internal === true || this.instrumentation === undefined || this._currentMacrostep === undefined)
+            return;
+        const macrostep = this._currentMacrostep;
+        const fromState = meta?.fromState ?? this._microstepFromState ?? macrostep.startState;
+        const seq = meta?.seq ?? macrostep.stepSeq;
+        const transitioned = this.currentStateName !== fromState;
+        if (transitioned)
+            macrostep.transitioned = true;
+        if (outcome === 'error')
+            macrostep.outcome = 'error';
+        notifyMicrostepEnd(this.instrumentation, {
+            macrostepId: macrostep.id,
+            seq,
+            toState: this.currentStateName,
+            transitioned,
+            async: false,
+            outcome,
+        });
+    }
+    onDispatchError(err) {
+        if (this.instrumentation === undefined)
+            return;
+        notifyError(this.instrumentation, {
+            phase: errorPhaseFromError(err),
+            errorClass: err.name,
+            error: err,
+            recovered: false,
+        });
+    }
+    onQueuesDrained() {
+        if (this.instrumentation === undefined || this._currentMacrostep === undefined)
+            return;
+        const macrostep = this._currentMacrostep;
+        notifyMacrostepEnd(this.instrumentation, {
+            id: macrostep.id,
+            endState: this.currentStateName,
+            steps: macrostep.stepSeq + 1,
+            transitioned: macrostep.transitioned,
+            outcome: macrostep.outcome,
+        });
+        this._currentMacrostep = undefined;
+    }
+    resolveEnqueueCause() {
+        const inherited = this.readDispatchCause('message');
+        if (inherited === undefined) {
+            return { actorUuid: this.actorUuid, kind: 'cause' };
+        }
+        if (inherited.actorUuid !== this.actorUuid) {
+            return inherited;
+        }
+        return { ...inherited, kind: 'cause' };
+    }
+    enqueueWithInstrumentation(task, event, queue, triggerKind) {
+        const cause = this.resolveEnqueueCause();
+        setTaskMeta(task, { event, queue, cause, triggerKind });
+        notifyEnqueue(this.instrumentation, {
+            event,
+            queue,
+            cause,
+            targetUuid: this.actorUuid,
+        });
+        if (queue === 'priority') {
+            this.pushHiPriorityTask(task);
+        }
+        else {
+            this.pushTask(task);
         }
     }
     get traceLevel() {
@@ -1603,12 +2061,22 @@ export class Machine extends HsmObject {
         }
         this.recordObserverEvent(name, args);
         return new Promise((resolve, reject) => {
-            this.pushTask(createServiceTask(this, this.transitionResolver, name, args, resolve, reject));
+            const task = createServiceTask(this, this.transitionResolver, name, args, resolve, reject);
+            if (this.instrumentation !== undefined) {
+                this.enqueueWithInstrumentation(task, name, 'default', 'call');
+                return;
+            }
+            this.pushTask(task);
         });
     }
     dispatchNotification(name, args, queue) {
         this.recordObserverEvent(name, args);
         const task = createNotificationTask(this, this.transitionResolver, name, args);
+        if (this.instrumentation !== undefined) {
+            const triggerKind = this._currentMacrostep === undefined ? 'external' : 'self';
+            this.enqueueWithInstrumentation(task, name, queue, triggerKind);
+            return;
+        }
         if (queue === 'priority') {
             this.pushHiPriorityTask(task);
         }
@@ -1625,14 +2093,60 @@ export class Machine extends HsmObject {
         return facade;
     }
     scheduleNotification(ms, name, args) {
-        const enqueue = () => {
-            this.dispatchNotification(name, args, 'default');
-        };
         const port = this._instance.portRef;
         if (port === undefined) {
             throw new Error('ihsm: deferred notification requires a port');
         }
-        port.setTimeout(enqueue, ms);
+        if (this.instrumentation === undefined) {
+            port.setTimeout(() => this.dispatchNotification(name, args, 'default'), ms);
+            return;
+        }
+        // Capture the arming step's dispatch token now (the timer fires later while the actor is idle,
+        // so the ambient token is gone by then). The fired macrostep links back to it as `timer` (§5.3.1).
+        const armed = this.readDispatchCause('timer');
+        const cause = armed ?? { actorUuid: this.actorUuid, kind: 'timer' };
+        port.setTimeout(() => this.enqueueTimerNotification(name, args, cause, ms), ms);
+    }
+    enqueueTimerNotification(name, args, cause, delayMs) {
+        this.recordObserverEvent(name, args);
+        const task = createNotificationTask(this, this.transitionResolver, name, args);
+        setTaskMeta(task, { event: name, queue: 'default', cause, triggerKind: 'timer', delayMs });
+        notifyEnqueue(this.instrumentation, { event: name, queue: 'default', cause, delayMs, targetUuid: this.actorUuid });
+        this.pushTask(task);
+    }
+    _actorLogger;
+    /** Severity-typed handler logger surfaced as `this.hsm.log.*` (CORE-F, §4.10.1). */
+    get logger() {
+        if (this._actorLogger === undefined) {
+            const emit = (severity, message, attributes) => this.emitUserLog(severity, message, attributes);
+            this._actorLogger = {
+                trace: (m, a) => emit('trace', m, a),
+                debug: (m, a) => emit('debug', m, a),
+                info: (m, a) => emit('info', m, a),
+                warn: (m, a) => emit('warn', m, a),
+                error: (m, a) => emit('error', m, a),
+                fatal: (m, a) => emit('fatal', m, a),
+            };
+        }
+        return this._actorLogger;
+    }
+    emitUserLog(severity, message, attributes) {
+        const isError = message instanceof Error;
+        const text = isError ? message.message : message;
+        const body = `${this.traceHeader}${this.currentStateName}: ${text}`;
+        // User logs fire on intent and are never TraceLevel-gated; mirror to the TraceWriter for console.
+        this.traceWriter.write(this, body);
+        if (this.instrumentation === undefined)
+            return;
+        const record = {
+            severity,
+            body,
+            attributes,
+            frames: this.traceFrames,
+            error: isError ? message : undefined,
+            source: 'user',
+        };
+        notifyLog(this.instrumentation, record);
     }
     /** @internal Binds deferred self-notifications to a port instance. */
     bindPort(portRef) {
@@ -1648,7 +2162,50 @@ export class Machine extends HsmObject {
             },
             transition: next => machine.transition(next),
             get port() {
-                return instance.portRef;
+                const rawPort = instance.portRef;
+                if (machine.instrumentation === undefined || rawPort === undefined || typeof rawPort !== 'object') {
+                    return rawPort;
+                }
+                if (machine._proxiedPort !== undefined)
+                    return machine._proxiedPort;
+                const proxy = new Proxy(rawPort, {
+                    get(target, prop, receiver) {
+                        const value = Reflect.get(target, prop, receiver);
+                        if (typeof value !== 'function')
+                            return value;
+                        const method = String(prop);
+                        return (...args) => {
+                            const begin = machine.beginPortCall(method);
+                            if (begin === undefined) {
+                                return Reflect.apply(value, target, args);
+                            }
+                            const call = () => Reflect.apply(value, target, args);
+                            const storage = portCallContext.get();
+                            try {
+                                const result = storage !== undefined ? storage.run({ machine, callId: begin.callId, method, cause: begin.cause }, call) : call();
+                                if (result instanceof Promise) {
+                                    return result.then((value) => {
+                                        machine.endPortCall(begin, 'ok');
+                                        return value;
+                                    }, (cause) => {
+                                        const err = asError(cause);
+                                        machine.endPortCall(begin, 'error', err);
+                                        throw err;
+                                    });
+                                }
+                                machine.endPortCall(begin, 'ok');
+                                return result;
+                            }
+                            catch (cause) {
+                                const err = asError(cause);
+                                machine.endPortCall(begin, 'error', err);
+                                throw err;
+                            }
+                        };
+                    },
+                });
+                machine._proxiedPort = proxy;
+                return proxy;
             },
             unhandled: () => machine.unhandled(),
             get eventName() {
@@ -1672,6 +2229,24 @@ export class Machine extends HsmObject {
             get traceHeader() {
                 return machine.traceHeader;
             },
+            get traceFrames() {
+                return machine.traceFrames;
+            },
+            get log() {
+                return machine.logger;
+            },
+            get id() {
+                return machine.actorUuid;
+            },
+            get actorUuid() {
+                return machine.actorUuid;
+            },
+            get actorName() {
+                return machine.actorName;
+            },
+            get actorPath() {
+                return machine.actorPath;
+            },
             get traceLevel() {
                 return machine.traceLevel;
             },
@@ -1739,6 +2314,18 @@ export class Machine extends HsmObject {
             get traceHeader() {
                 return machine.traceHeader;
             },
+            get id() {
+                return machine.actorUuid;
+            },
+            get actorUuid() {
+                return machine.actorUuid;
+            },
+            get actorName() {
+                return machine.actorName;
+            },
+            get actorPath() {
+                return machine.actorPath;
+            },
         };
         if (includeState) {
             Object.defineProperties(facade, {
@@ -1808,9 +2395,16 @@ export function defaultDispatchErrorCallback(hsm, err) {
     throw err;
 }
 /** @internal Spawn with embodiment kind — used by factories and `ihsm/testing`. */
-export function spawnActor(kind, topState, ctx, port, options) {
+export function spawnActor(kind, topState, ctx, port, options, spawnContext = {}) {
     const { initialize = defaultInitialize, traceLevel = TraceLevel.DEBUG, traceWriter = defaultTraceWriter, dispatchErrorCallback = defaultDispatchErrorCallback, transitions } = options;
     const protocolIndex = buildProtocolIndex(topState);
+    const topStateName = getStateName(topState);
+    const parentMachine = spawnContext.parentMachine;
+    // Tracing is a cross-cutting concern: the actor adopts the globally-registered collector(s) at
+    // spawn (no per-actor `instrumentation` option). Snapshotting here keeps "no collector" actors
+    // at zero overhead while still sharing one collector instance across a parent and its children.
+    const resolvedInstrumentation = getActiveInstrumentation();
+    const identity = parentMachine !== undefined ? mintActorIdentity('child', childActorPath(parentMachine.actorPath, topStateName, parentMachine.allocateChildSpawnIndex(topStateName)), parentMachine.actorUuid) : mintActorIdentity(kind, rootActorPath(topStateName));
     const boundPort = (port ?? new Port());
     const instance = {
         ctx,
@@ -1818,7 +2412,26 @@ export function spawnActor(kind, topState, ctx, port, options) {
         portRef: boundPort,
     };
     Object.setPrototypeOf(instance, topState.prototype);
-    const machine = new Machine(topState, instance, protocolIndex, traceWriter, traceLevel, dispatchErrorCallback, initialize, transitions ?? new RuntimeTransitionResolver());
+    const machine = new Machine(topState, instance, protocolIndex, traceWriter, traceLevel, dispatchErrorCallback, initialize, identity, resolvedInstrumentation, transitions ?? new RuntimeTransitionResolver());
+    if (resolvedInstrumentation !== undefined) {
+        const token = dispatchContext.get()?.getStore();
+        const parentCause = token?.actorUuid !== undefined
+            ? {
+                actorUuid: token.actorUuid,
+                macrostepId: token.macrostepId,
+                stepSeq: token.stepSeq,
+                kind: 'spawn',
+            }
+            : {
+                actorUuid: identity.parentUuid ?? identity.uuid,
+                kind: 'spawn',
+            };
+        const spawnInfo = {
+            parent: parentCause,
+            child: identity,
+        };
+        notifyActorSpawned(resolvedInstrumentation, spawnInfo);
+    }
     const portKind = isRequestingPort(boundPort) ? 'child' : kind === 'root' ? 'inbound' : kind;
     boundPort.actor = createActorHandle(machine, topState, protocolIndex, portKind);
     return createActorHandle(machine, topState, protocolIndex, kind);
@@ -1839,9 +2452,11 @@ export function asParentActor(handler) {
 }
 /** Parent composes a child machine — returns full child protocol shell with `parent` set. */
 export function makeChildActor(parent, childTop, childCtx, port, options = {}) {
-    const child = spawnActor('child', childTop, childCtx, port, options);
+    const parentMachine = parent[kParentLink];
+    const child = spawnActor('child', childTop, childCtx, port, options, { parentMachine: parentMachine });
     Object.defineProperty(child, 'parent', { value: parent, enumerable: true, writable: false, configurable: true });
     return child;
 }
 export { kHandlerMachine, kParentLink } from './types.js';
+export { configureRunSeed, getRunSeed, getRunNamespace, actorNameFromTopState, mintActorIdentity, rootActorPath, childActorPath } from './identity.js';
 //# sourceMappingURL=runtime.js.map