@typeonce/effect-machine 0.11.0 → 0.13.0

package/dist/internal/machine/runtime.js

@@ -17,6 +17,7 @@ import * as Scope from "effect/Scope";
 import * as Stream from "effect/Stream";
 import * as SynchronizedRef from "effect/SynchronizedRef";
 import { ChildAlreadyExistsError, StoppedError } from "./errors.js";
+import * as InspectionRuntime from "./inspectionRuntime.js";
 /** @internal */
 export const activeSnapshotObserver = Symbol.for("effect/Machine/activeSnapshotObserver");
 /** @internal */
@@ -30,17 +31,22 @@ export const isAcknowledgedMessage = (message) => typeof message === "object" &&
 export const messageEvent = (message) => isAcknowledgedMessage(message) ? message.event : message;
 const succeedAcknowledgedMessage = (message, delivery) => {
     if (message !== undefined && isAcknowledgedMessage(message)) {
-        Deferred.doneUnsafe(message.deferred, Effect.succeed(delivery));
+        if (message.deferred !== undefined) {
+            Deferred.doneUnsafe(message.deferred, Effect.succeed(delivery));
+        }
+        message.inspection?.complete(delivery);
     }
 };
 const failAcknowledgedMessage = (message, cause) => {
     if (message !== undefined && isAcknowledgedMessage(message)) {
-        Deferred.doneUnsafe(message.deferred, Effect.failCause(cause));
+        if (message.deferred !== undefined)
+            Deferred.doneUnsafe(message.deferred, Effect.failCause(cause));
     }
 };
 const stopAcknowledgedMessage = (message) => {
     if (message !== undefined && isAcknowledgedMessage(message)) {
-        Deferred.doneUnsafe(message.deferred, Effect.fail(new StoppedError()));
+        if (message.deferred !== undefined)
+            Deferred.doneUnsafe(message.deferred, Effect.fail(new StoppedError()));
     }
 };
 const offerChildObservation = (observer, value) => {
@@ -112,7 +118,10 @@ const registerChild = (registry, key, token, ref, descriptor) => {
         publishRegistryChange(registry);
     return true;
 };
-const isProcessAddress = (value) => typeof value === "object" && value !== null && "send" in value && typeof value.send === "function";
+const isMachineTarget = (value) => typeof value === "object" && value !== null && "send" in value && typeof value.send === "function";
+const sendMachineTarget = (target, event, source, causedBy) => "inspectionSubject" in target && "sendInspected" in target && typeof target.sendInspected === "function"
+    ? target.sendInspected(event, source, causedBy)
+    : target.send(event);
 const executionIsChildless = (execution) => execution?._tag === "Childless" || execution?.childless === true;
 const offerCompactMailbox = (mailbox, event) => {
     const items = mailbox.items ?? [];
@@ -205,6 +214,63 @@ const makeProcessRuntime = Effect.sync(() => {
         nextSessionId: Effect.sync(() => `machine:${sessionIdCounter++}`)
     };
 });
+const inspectionSubject = (logic, id, sessionId) => ({
+    id,
+    sessionId,
+    kind: logic.inspection?.kind ?? "Logic"
+});
+const messageCausation = (message, initializing) => initializing
+    ? { _tag: "Initialization" }
+    : message !== undefined && isAcknowledgedMessage(message) && message.inspection !== undefined
+        ? { _tag: "Macrostep", macrostepId: message.inspection.macrostepId }
+        : undefined;
+const makeInspectedMessage = (inspection, subject, event, source, causedBy, deferred) => {
+    const deliveryId = inspection.nextDeliveryId();
+    const macrostepId = inspection.nextMacrostepId();
+    const inspected = {
+        deliveryId,
+        macrostepId,
+        source,
+        event,
+        causedBy,
+        complete: (delivery) => {
+            const microsteps = InspectionRuntime.microsteps(delivery.plan);
+            inspection.publishUnsafe({
+                _tag: "EventProcessed",
+                subject,
+                macrostepId,
+                deliveryId,
+                source,
+                event,
+                before: { status: "active", state: delivery.before },
+                after: { status: "active", state: delivery.after },
+                handled: microsteps.some((microstep) => microstep.transitions.length > 0),
+                configurationChanged: microsteps.some((microstep) => microstep.changed),
+                microsteps
+            });
+        }
+    };
+    return {
+        [AcknowledgedMessageTypeId]: true,
+        event,
+        ...(deferred === undefined ? undefined : { deferred }),
+        inspection: inspected
+    };
+};
+const publishInspectedSent = (inspection, subject, message) => {
+    if (!isAcknowledgedMessage(message) || message.inspection === undefined)
+        return;
+    const delivery = message.inspection;
+    inspection.publishUnsafe({
+        _tag: "EventSent",
+        subject,
+        deliveryId: delivery.deliveryId,
+        source: delivery.source,
+        target: InspectionRuntime.endpoint(subject),
+        event: delivery.event,
+        causedBy: delivery.causedBy
+    });
+};
 class OwnedChildRuntimeImpl {
     registry;
     self;
@@ -252,13 +318,14 @@ class OwnedChildRuntimeImpl {
             });
             const parent = {
                 ...this.self,
-                send: (event) => options.sendParent(isCurrent, event)
+                send: (event) => options.sendParent(isCurrent, event),
+                sendInspected: (event, source, causedBy) => isCurrent() ? sendMachineTarget(this.self, event, source, causedBy) : Effect.void
             };
             const startOptions = {
                 detached: true,
                 id: options.id,
                 sendParent: (event) => options.sendParent(isCurrent, event),
-                onOutcome: (outcome) => options.onOutcome(isCurrent, outcome),
+                onOutcome: (outcome) => options.onOutcome(isCurrent, outcome, startedChild?.sessionId),
                 ...(options.onSnapshot === undefined
                     ? undefined
                     : { onSnapshot: (snapshot) => options.onSnapshot(isCurrent, snapshot) }),
@@ -269,7 +336,19 @@ class OwnedChildRuntimeImpl {
                 onStopSync: () => unregisterChild(this.registry, options.id, token),
                 skipStoppedOutcome: true,
                 parent,
-                runtime: this.runtime
+                runtime: this.runtime,
+                origin: { _tag: "Invoke", ownerPath: options.path, invokeId: options.duplicateId },
+                ...(options.activityKind === undefined || this.runtime.inspection === undefined ||
+                    this.self.inspectionSubject === undefined
+                    ? undefined
+                    : {
+                        activity: {
+                            id: options.duplicateId,
+                            owner: this.self.inspectionSubject,
+                            ownerPath: options.path,
+                            kind: options.activityKind
+                        }
+                    })
             };
             const execution = logic.execution;
             const synchronous = this.services !== undefined && options.onSnapshot === undefined &&
@@ -320,6 +399,8 @@ class OwnedChildRuntimeImpl {
 }
 const noChildChanges = Stream.succeed(Option.none()).pipe(Stream.concat(Stream.never));
 const noParentSend = (_event) => Effect.void;
+const noInspectInitial = (_paths, _microsteps) => { };
+const noCausation = () => undefined;
 const EmissionsClosed = Symbol("effect/Machine/EmissionsClosed");
 const makeEmissionRuntime = () => {
     let emissions;
@@ -450,7 +531,7 @@ const makeChildRuntimeSync = (self, runtime, services) => {
             })), Effect.as(takeChildObservations(observer)));
         }))));
     };
-    const sendTo = (child, event) => {
+    const sendTo = (child, event, source, causedBy) => {
         const id = typeof child === "string" ? child : child.id;
         return Effect.suspend(() => {
             if (registry.closed) {
@@ -458,7 +539,7 @@ const makeChildRuntimeSync = (self, runtime, services) => {
             }
             const entry = registry.children.get(id);
             return entry !== undefined && matchesChild(entry, child)
-                ? entry.ref.send(event)
+                ? sendMachineTarget(entry.ref, event, source, causedBy)
                 : Effect.void;
         });
     };
@@ -502,7 +583,8 @@ const makeChildRuntimeSync = (self, runtime, services) => {
                 }).pipe(Effect.andThen(register(key, token, child, spawnOptions?.descriptor)), Effect.flatMap((registered) => registered ? Effect.void : requestChildStop)),
                 onStop: unregister(key, token),
                 parent: self,
-                runtime
+                runtime,
+                origin: { _tag: "Spawn", address: spawnOptions?.id }
             }).pipe(Effect.onExit((exit) => Exit.isFailure(exit)
                 ? unregister(key, token).pipe(Effect.andThen(startedChild === undefined ? Effect.void : startedChild.stop))
                 : Effect.void), Scope.provide(registry.scope));
@@ -526,6 +608,13 @@ const startGenericInternal = Effect.fnUntraced(function* (logic, options) {
     const { detached, id: requestedId, onOutcome, onReady, onReadySync, onSnapshot, onStop, onStopSync, parent, runtime, sendParent: overrideSendParent } = options;
     const sessionId = options.sessionId ?? (yield* runtime.nextSessionId);
     const id = requestedId ?? sessionId;
+    const inspector = runtime.inspection;
+    const subject = inspector === undefined ? undefined : inspectionSubject(logic, id, sessionId);
+    const activity = inspector === undefined || options.activity === undefined
+        ? undefined
+        : { ...options.activity, sessionId };
+    let initialEntryPaths;
+    let initialMicrosteps;
     const queue = yield* Queue.unbounded();
     const emissions = options.emissions ?? makeEmissionRuntime();
     const termination = yield* Deferred.make();
@@ -534,6 +623,15 @@ const startGenericInternal = Effect.fnUntraced(function* (logic, options) {
     let initializing = true;
     let inFlightMessage;
     const requestStop = Deferred.succeed(termination, { _tag: "Stopped" }).pipe(Effect.asVoid);
+    const offerDirect = (message) => Queue.offer(queue, message).pipe(Effect.flatMap((accepted) => accepted ? Effect.void : Effect.fail(new StoppedError())));
+    const offerInspected = inspector === undefined ? undefined : (event, source, causedBy, deferred) => Effect.suspend(() => {
+        const message = inspector.isActive()
+            ? makeInspectedMessage(inspector, subject, event, source, causedBy, deferred)
+            : deferred === undefined
+                ? event
+                : { [AcknowledgedMessageTypeId]: true, event, deferred };
+        return offerDirect(message).pipe(Effect.tap(() => Effect.sync(() => publishInspectedSent(inspector, subject, message))));
+    });
     const self = {
         id,
         sessionId,
@@ -545,17 +643,21 @@ const startGenericInternal = Effect.fnUntraced(function* (logic, options) {
         stop: Effect.suspend(() => initializing
             ? requestStop
             : requestStop.pipe(Effect.andThen(Effect.never))),
-        send: (event) => Queue.offer(queue, event).pipe(Effect.flatMap((accepted) => accepted ? Effect.void : Effect.fail(new StoppedError())))
+        send: inspector === undefined
+            ? (event) => offerDirect(event)
+            : (event) => offerInspected(event, undefined, undefined),
+        ...(inspector === undefined
+            ? undefined
+            : { inspectionSubject: subject, sendInspected: offerInspected })
     };
     const sendAcknowledged = logic.execution?._tag !== "Compiled"
         ? undefined
-        : (event) => Effect.uninterruptibleMask((restore) => Deferred.make().pipe(Effect.flatMap((deferred) => Queue.offer(queue, {
-            [AcknowledgedMessageTypeId]: true,
-            event,
-            deferred
-        }).pipe(Effect.flatMap((accepted) => accepted
-            ? restore(Deferred.await(deferred))
-            : Effect.fail(new StoppedError())))), Effect.map((delivery) => delivery)));
+        : (event) => Effect.uninterruptibleMask((restore) => Deferred.make().pipe(Effect.flatMap((deferred) => {
+            const offered = inspector === undefined
+                ? offerDirect({ [AcknowledgedMessageTypeId]: true, event, deferred })
+                : offerInspected(event, undefined, undefined, deferred);
+            return offered.pipe(Effect.andThen(restore(Deferred.await(deferred))));
+        }), Effect.map((delivery) => delivery)));
     let { changes: childChanges, close: closeChildren, get: getChild, owned: ownedChildren, sendTo, spawn, stop: stopChild } = childlessRuntime;
     if (!executionIsChildless(logic.execution)) {
         ;
@@ -569,24 +671,68 @@ const startGenericInternal = Effect.fnUntraced(function* (logic, options) {
             stop: stopChild
         } = yield* makeChildRuntime(self, runtime));
     }
-    const cleanupStartupFailure = (exit) => Exit.isFailure(exit)
-        ? closeChildren(exit).pipe(Effect.andThen(emissions.close()))
-        : Effect.void;
+    const cleanupStartupFailure = (exit) => {
+        if (Exit.isSuccess(exit))
+            return Effect.void;
+        if (inspector !== undefined) {
+            inspector.publishUnsafe(activity === undefined
+                ? { _tag: "StartFailed", subject: subject, cause: exit.cause }
+                : { _tag: "ActivityStopped", subject: activity.owner, activity, exit });
+        }
+        return closeChildren(exit).pipe(Effect.andThen(emissions.close()), Effect.andThen(options.inspectionRoot === true && inspector !== undefined ? inspector.close : Effect.void));
+    };
     const cleanup = onStopSync === undefined ? onStop ?? Effect.void : Effect.sync(onStopSync);
-    const sendParent = overrideSendParent ?? (parent === undefined ? noParentSend : parent.send);
+    const currentCausation = inspector === undefined
+        ? noCausation
+        : () => messageCausation(inFlightMessage, initializing);
+    const sendParent = overrideSendParent ?? (parent === undefined
+        ? noParentSend
+        : inspector === undefined
+            ? parent.send
+            : (event) => sendMachineTarget(parent, event, subject, currentCausation()));
+    const emit = inspector === undefined
+        ? emissions.emit
+        : (event) => emissions.emit(event).pipe(Effect.tap(() => Effect.sync(() => inspector.publishUnsafe({
+            _tag: "Emitted",
+            subject: subject,
+            emission: event,
+            causedBy: currentCausation()
+        }))));
+    const sendToTarget = inspector === undefined
+        ? ((target, event) => isMachineTarget(target) ? target.send(event) : sendTo(target, event))
+        : ((target, event) => isMachineTarget(target)
+            ? sendMachineTarget(target, event, subject, currentCausation())
+            : sendTo(target, event, subject, currentCausation()));
     const scope = {
         self,
         parent,
         spawn,
         sendParent,
-        emit: emissions.emit,
-        sendTo: ((target, event) => isProcessAddress(target) ? target.send(event) : sendTo(target, event)),
+        emit,
+        sendTo: sendToTarget,
         stopChild,
         failCause: (cause) => Deferred.succeed(termination, {
             _tag: "Failure",
             cause: cause
-        }).pipe(Effect.asVoid)
+        }).pipe(Effect.asVoid),
+        inspectInitial: inspector === undefined
+            ? noInspectInitial
+            : (paths, microsteps = []) => {
+                initialEntryPaths = paths;
+                initialMicrosteps = microsteps;
+            }
     };
+    if (inspector !== undefined) {
+        inspector.publishUnsafe(activity === undefined
+            ? {
+                _tag: "Created",
+                subject: subject,
+                parent: parent?.inspectionSubject,
+                origin: options.origin ?? { _tag: "Root" },
+                definition: logic.inspection?.definition
+            }
+            : { _tag: "ActivityStarted", subject: activity.owner, activity });
+    }
     const initial = yield* logic.initial(scope).pipe(Effect.onExit(cleanupStartupFailure), Effect.ensuring(Effect.sync(() => {
         initializing = false;
     })));
@@ -599,6 +745,15 @@ const startGenericInternal = Effect.fnUntraced(function* (logic, options) {
             state: initial
         }
     });
+    if (activity === undefined) {
+        inspector?.publishUnsafe({
+            _tag: "Initialized",
+            subject: subject,
+            snapshot: { status: "active", state: initial },
+            initialEntryPaths: initialEntryPaths ?? [],
+            microsteps: InspectionRuntime.microsteps({ microsteps: initialMicrosteps ?? [] })
+        });
+    }
     const publishSnapshot = onSnapshot === undefined
         ? (snapshot) => snapshot.changes === undefined
             ? Effect.succeed(snapshot)
@@ -658,16 +813,46 @@ const startGenericInternal = Effect.fnUntraced(function* (logic, options) {
         terminalizing: true,
         changes: current.changes
     })).pipe(Effect.flatMap(publishSnapshot), Effect.flatMap(completeIfTerminal), Effect.asVoid);
-    const setActiveState = (state) => updateSnapshot((snapshot) => Effect.succeed(snapshot.status === "active"
+    const setActiveStateDirect = (state) => updateSnapshot((snapshot) => Effect.succeed(snapshot.status === "active"
         ? {
             status: "active",
             state
         }
         : undefined)).pipe(Effect.asVoid);
+    const setActiveState = inspector === undefined ?
+        setActiveStateDirect :
+        (state) => SynchronizedRef.get(current).pipe(Effect.flatMap((before) => updateSnapshot((snapshot) => Effect.succeed(snapshot.status === "active"
+            ? {
+                status: "active",
+                state
+            }
+            : undefined)).pipe(Effect.tap((after) => Effect.sync(() => {
+            if (logic.inspection?.kind === "Machine" || after === undefined)
+                return;
+            inspector.publishUnsafe({
+                _tag: "StateChanged",
+                subject: subject,
+                before: before.snapshot.state,
+                after: state,
+                causedByDeliveryId: inFlightMessage !== undefined && isAcknowledgedMessage(inFlightMessage)
+                    ? inFlightMessage.inspection?.deliveryId
+                    : undefined
+            });
+        })))), Effect.asVoid);
     const terminalizeWith = (snapshot, exit, completeDone) => {
         const notifyOutcome = onOutcome === undefined || (snapshot.status === "stopped" && options.skipStoppedOutcome === true)
             ? Effect.void
             : Effect.suspend(() => onOutcome(classifyOutcome(snapshot))).pipe(Effect.exit, Effect.asVoid);
+        const closeEmissionsAndInspect = inspector === undefined
+            ? emissions.close()
+            : emissions.close().pipe(Effect.andThen(Effect.sync(() => inspector.publishUnsafe(activity === undefined
+                ? { _tag: "Terminated", subject: subject, snapshot }
+                : {
+                    _tag: "ActivityStopped",
+                    subject: activity.owner,
+                    activity,
+                    exit: snapshot.status === "stopped" ? Exit.interrupt() : exit
+                }))));
         return Effect.uninterruptible(Effect.sync(() => {
             while (true) {
                 const pending = Queue.takeUnsafe(queue);
@@ -675,7 +860,7 @@ const startGenericInternal = Effect.fnUntraced(function* (logic, options) {
                     break;
                 stopAcknowledgedMessage(pending.value);
             }
-        }).pipe(Effect.andThen(Queue.shutdown(queue)), Effect.andThen(closeChildren(exit)), Effect.andThen(setAndPublishSnapshot(snapshot)), Effect.andThen(emissions.close()), Effect.andThen(Effect.sync(() => {
+        }).pipe(Effect.andThen(Queue.shutdown(queue)), Effect.andThen(closeChildren(exit)), Effect.andThen(setAndPublishSnapshot(snapshot)), Effect.andThen(closeEmissionsAndInspect), Effect.andThen(Effect.sync(() => {
             if (Exit.isFailure(exit)) {
                 failAcknowledgedMessage(inFlightMessage, exit.cause);
             }
@@ -683,7 +868,7 @@ const startGenericInternal = Effect.fnUntraced(function* (logic, options) {
                 stopAcknowledgedMessage(inFlightMessage);
             }
             inFlightMessage = undefined;
-        })), Effect.andThen(notifyOutcome), Effect.andThen(cleanup), Effect.andThen(completeDone)));
+        })), Effect.andThen(notifyOutcome), Effect.andThen(cleanup), Effect.andThen(options.inspectionRoot === true && inspector !== undefined ? inspector.close : Effect.void), Effect.andThen(completeDone)));
     };
     const reserveStoppedSnapshot = reserveTerminalSnapshot((snapshot) => ({
         status: "stopped",
@@ -726,20 +911,52 @@ const startGenericInternal = Effect.fnUntraced(function* (logic, options) {
             inFlightMessage = undefined;
         }
     };
+    const receive = inspector === undefined || logic.execution?._tag === "Compiled"
+        ? Queue.take(queue).pipe(Effect.map(messageEvent))
+        : Queue.take(queue).pipe(Effect.tap((message) => Effect.sync(() => {
+            inFlightMessage = message;
+        })), Effect.map(messageEvent));
+    const poll = inspector === undefined || logic.execution?._tag === "Compiled"
+        ? Queue.poll(queue).pipe(Effect.map(Option.map(messageEvent)))
+        : Queue.poll(queue).pipe(Effect.tap((message) => Effect.sync(() => {
+            if (Option.isSome(message))
+                inFlightMessage = message.value;
+        })), Effect.map(Option.map(messageEvent)));
+    const updateStateDirect = (f) => updateSnapshot((snapshot) => snapshot.status === "active"
+        ? f(snapshot.state).pipe(Effect.map((state) => ({
+            status: "active",
+            state
+        })))
+        : Effect.succeed(undefined)).pipe(Effect.asVoid);
+    const updateState = inspector === undefined
+        ? updateStateDirect
+        : (f) => SynchronizedRef.get(current).pipe(Effect.flatMap((before) => updateSnapshot((snapshot) => snapshot.status === "active"
+            ? f(snapshot.state).pipe(Effect.map((state) => ({
+                status: "active",
+                state
+            })))
+            : Effect.succeed(undefined)).pipe(Effect.tap((after) => Effect.sync(() => {
+            if (logic.inspection?.kind === "Machine" || after?.status !== "active")
+                return;
+            inspector.publishUnsafe({
+                _tag: "StateChanged",
+                subject: subject,
+                before: before.snapshot.state,
+                after: after.state,
+                causedByDeliveryId: inFlightMessage !== undefined && isAcknowledgedMessage(inFlightMessage)
+                    ? inFlightMessage.inspection?.deliveryId
+                    : undefined
+            });
+        })))), Effect.asVoid);
     const context = {
         ...scope,
         ...(logic.execution?._tag === "Compiled" && !logic.execution.childless ? { ownedChildren } : undefined),
         ...acknowledgedContext,
-        receive: Queue.take(queue).pipe(Effect.map(messageEvent)),
-        poll: Queue.poll(queue).pipe(Effect.map(Option.map(messageEvent))),
+        receive,
+        poll,
         state: SynchronizedRef.get(current).pipe(Effect.map((current) => current.snapshot.state)),
         setState: setActiveState,
-        updateState: (f) => updateSnapshot((snapshot) => snapshot.status === "active"
-            ? f(snapshot.state).pipe(Effect.map((state) => ({
-                status: "active",
-                state
-            })))
-            : Effect.succeed(undefined)).pipe(Effect.asVoid)
+        updateState
     };
     const getOrCreateChanges = SynchronizedRef.modifyEffect(current, (current) => {
         if (current.snapshot.status !== "active") {
@@ -765,6 +982,9 @@ const startGenericInternal = Effect.fnUntraced(function* (logic, options) {
     const ref = {
         id,
         sessionId,
+        ...(inspector === undefined
+            ? undefined
+            : { inspectionSubject: subject, sendInspected: offerInspected }),
         state: SynchronizedRef.get(current).pipe(Effect.map((current) => current.snapshot.state)),
         snapshot: SynchronizedRef.get(current).pipe(Effect.map((current) => current.snapshot)),
         changes: changesStream,
@@ -852,7 +1072,11 @@ class CompiledProcess {
     services;
     id;
     sessionId;
+    inspectionSubject;
     send;
+    sendInspected(event, source, causedBy) {
+        return this.offerEvent(event, source, causedBy);
+    }
     [acknowledgedSend](event) {
         return this.sendAcknowledgedEffect(event);
     }
@@ -884,41 +1108,125 @@ class CompiledProcess {
     inFlightMessage;
     externalEmissions;
     emissionsPubSub;
+    activity;
+    initialEntryPaths;
+    initialMicrosteps;
+    initializing;
     constructor(logic, options, services, sessionId) {
         this.logic = logic;
         this.options = options;
         this.services = services;
         this.sessionId = sessionId;
         this.id = options.id ?? sessionId;
+        const inspector = options.runtime.inspection;
+        if (inspector !== undefined) {
+            this.inspectionSubject = inspectionSubject(logic, this.id, sessionId);
+            this.initializing = true;
+            if (options.activity !== undefined)
+                this.activity = { ...options.activity, sessionId };
+        }
         this.externalEmissions = options.emissions;
-        this.send = (event) => this.offerMessage(event);
+        this.send = inspector === undefined
+            ? (event) => this.offerMessage(event)
+            : (event) => this.offerEvent(event, undefined, undefined);
         this.address = {
             id: this.id,
             sessionId,
             stop: Effect.suspend(() => this.stopFromProcess()),
-            send: this.send
+            send: this.send,
+            ...(inspector === undefined
+                ? undefined
+                : {
+                    inspectionSubject: this.inspectionSubject,
+                    sendInspected: (event, source, causedBy) => this.offerEvent(event, source, causedBy)
+                })
         };
     }
+    get inspector() {
+        return this.options.runtime.inspection;
+    }
+    causation() {
+        return messageCausation(this.inFlightMessage, this.initializing === true);
+    }
+    publishCreated() {
+        const inspector = this.inspector;
+        const subject = this.inspectionSubject;
+        if (inspector === undefined || subject === undefined)
+            return;
+        inspector.publishUnsafe(this.activity === undefined
+            ? {
+                _tag: "Created",
+                subject,
+                parent: this.options.parent?.inspectionSubject,
+                origin: this.options.origin ?? { _tag: "Root" },
+                definition: this.logic.inspection?.definition
+            }
+            : { _tag: "ActivityStarted", subject: this.activity.owner, activity: this.activity });
+    }
+    publishInitialized(state) {
+        this.initializing = false;
+        if (this.activity !== undefined)
+            return;
+        const inspector = this.inspector;
+        const subject = this.inspectionSubject;
+        if (inspector === undefined || subject === undefined)
+            return;
+        inspector.publishUnsafe({
+            _tag: "Initialized",
+            subject,
+            snapshot: { status: "active", state },
+            initialEntryPaths: this.initialEntryPaths ?? [],
+            microsteps: InspectionRuntime.microsteps({ microsteps: this.initialMicrosteps ?? [] })
+        });
+    }
+    publishStartFailed(cause) {
+        this.initializing = false;
+        const inspector = this.inspector;
+        const subject = this.inspectionSubject;
+        if (inspector === undefined || subject === undefined)
+            return;
+        inspector.publishUnsafe(this.activity === undefined
+            ? { _tag: "StartFailed", subject, cause }
+            : {
+                _tag: "ActivityStopped",
+                subject: this.activity.owner,
+                activity: this.activity,
+                exit: Exit.failCause(cause)
+            });
+    }
     get execution() {
         return this.logic.execution;
     }
     initializeCompiledSync() {
+        this.publishCreated();
         if (!this.execution.childless) {
             this.childRuntime = makeChildRuntimeSync(this.address, this.options.runtime, this.services);
         }
         const parent = this.options.parent;
-        const sendParent = this.options.sendParent ?? (parent === undefined ? noParentSend : parent.send);
+        const sendParent = this.options.sendParent ?? (parent === undefined
+            ? noParentSend
+            : this.inspector === undefined
+                ? parent.send
+                : (event) => sendMachineTarget(parent, event, this.inspectionSubject, this.causation()));
         this.processScope = {
             self: this.address,
             parent,
             spawn: this.childRuntime.spawn,
             sendParent,
             emit: (event) => this.emitEvent(event),
-            sendTo: ((target, event) => isProcessAddress(target)
-                ? target.send(event)
-                : this.childRuntime.sendTo(target, event)),
+            sendTo: ((target, event) => isMachineTarget(target)
+                ? this.inspector === undefined
+                    ? target.send(event)
+                    : sendMachineTarget(target, event, this.inspectionSubject, this.causation())
+                : this.childRuntime.sendTo(target, event, this.inspectionSubject, this.causation())),
             stopChild: this.childRuntime.stop,
-            failCause: (cause) => this.failCause(cause)
+            failCause: (cause) => this.failCause(cause),
+            inspectInitial: this.inspector === undefined
+                ? noInspectInitial
+                : (paths, microsteps = []) => {
+                    this.initialEntryPaths = paths;
+                    this.initialMicrosteps = microsteps;
+                }
         };
         const compiledInitial = this.execution.initialSync;
         let initialized;
@@ -927,6 +1235,7 @@ class CompiledProcess {
         }
         catch (error) {
             this.runState = "Idle";
+            this.publishStartFailed(Cause.fail(error));
             return Effect.fail(error);
         }
         this.runState = "Idle";
@@ -936,6 +1245,7 @@ class CompiledProcess {
             changes: undefined,
             snapshot: { status: "active", state: initialized.state }
         };
+        this.publishInitialized(initialized.state);
         this.compiledContext = new CompiledProcessContextImpl(this.processScope, this.childRuntime.owned, this);
         if ("executionState" in initialized) {
             this.compiledContext.executionState = initialized.executionState;
@@ -957,29 +1267,46 @@ class CompiledProcess {
     initialize() {
         const self = this;
         return Effect.gen(function* () {
+            self.publishCreated();
             if (!self.execution.childless) {
                 self.childRuntime = yield* makeChildRuntime(self.address, self.options.runtime, self.services);
             }
             const parent = self.options.parent;
-            const sendParent = self.options.sendParent ?? (parent === undefined ? noParentSend : parent.send);
+            const sendParent = self.options.sendParent ?? (parent === undefined
+                ? noParentSend
+                : self.inspector === undefined
+                    ? parent.send
+                    : (event) => sendMachineTarget(parent, event, self.inspectionSubject, self.causation()));
             self.processScope = {
                 self: self.address,
                 parent,
                 spawn: self.childRuntime.spawn,
                 sendParent,
                 emit: (event) => self.emitEvent(event),
-                sendTo: ((target, event) => isProcessAddress(target)
-                    ? target.send(event)
-                    : self.childRuntime.sendTo(target, event)),
+                sendTo: ((target, event) => isMachineTarget(target)
+                    ? self.inspector === undefined
+                        ? target.send(event)
+                        : sendMachineTarget(target, event, self.inspectionSubject, self.causation())
+                    : self.childRuntime.sendTo(target, event, self.inspectionSubject, self.causation())),
                 stopChild: self.childRuntime.stop,
-                failCause: (cause) => self.failCause(cause)
+                failCause: (cause) => self.failCause(cause),
+                inspectInitial: self.inspector === undefined
+                    ? noInspectInitial
+                    : (paths, microsteps = []) => {
+                        self.initialEntryPaths = paths;
+                        self.initialMicrosteps = microsteps;
+                    }
             };
             const cleanupStartupFailure = (exit) => Exit.isFailure(exit) ? self.childRuntime.close(exit) : Effect.void;
             const compiledInitial = self.execution.initial;
             const initializeEffect = compiledInitial === undefined
                 ? self.logic.initial(self.processScope).pipe(Effect.map((state) => ({ state, done: undefined, output: undefined })))
                 : compiledInitial(self.processScope);
-            const initialized = yield* initializeEffect.pipe(Effect.onExit(cleanupStartupFailure), Effect.ensuring(Effect.sync(() => {
+            const initialized = yield* initializeEffect.pipe(Effect.onExit((exit) => {
+                if (Exit.isFailure(exit))
+                    self.publishStartFailed(exit.cause);
+                return cleanupStartupFailure(exit);
+            }), Effect.ensuring(Effect.sync(() => {
                 self.runState = "Idle";
             })));
             const initial = initialized.state;
@@ -989,6 +1316,7 @@ class CompiledProcess {
                 changes: undefined,
                 snapshot: { status: "active", state: initial }
             };
+            self.publishInitialized(initial);
             if (self.execution.drain._tag === "Process") {
                 self.processContext = {
                     ...self.processScope,
@@ -1103,11 +1431,19 @@ class CompiledProcess {
             : Effect.void));
     }
     sendAcknowledgedEffect(event) {
-        return Effect.uninterruptibleMask((restore) => Deferred.make().pipe(Effect.flatMap((deferred) => this.offerMessage({
-            [AcknowledgedMessageTypeId]: true,
-            event,
-            deferred
-        }).pipe(Effect.andThen(restore(Deferred.await(deferred)))))));
+        return Effect.uninterruptibleMask((restore) => Deferred.make().pipe(Effect.flatMap((deferred) => this.offerEvent(event, undefined, undefined, deferred).pipe(Effect.andThen(restore(Deferred.await(deferred)))))));
+    }
+    offerEvent(event, source, causedBy, deferred) {
+        return Effect.suspend(() => {
+            const inspector = this.inspector;
+            const subject = this.inspectionSubject;
+            const message = inspector?.isActive() === true && subject !== undefined
+                ? makeInspectedMessage(inspector, subject, event, source, causedBy, deferred)
+                : deferred === undefined
+                    ? event
+                    : { [AcknowledgedMessageTypeId]: true, event, deferred };
+            return this.offerMessage(message);
+        });
     }
     offerMessage(message) {
         return Effect.uninterruptible(Effect.suspend(() => {
@@ -1115,6 +1451,10 @@ class CompiledProcess {
                 return Effect.fail(new StoppedError());
             }
             offerCompactMailbox(this.mailbox, message);
+            const inspector = this.inspector;
+            const subject = this.inspectionSubject;
+            if (inspector !== undefined && subject !== undefined)
+                publishInspectedSent(inspector, subject, message);
             this.offerRevision += 1;
             if (this.runState === "Draining") {
                 return Effect.void;
@@ -1153,6 +1493,7 @@ class CompiledProcess {
             this.lifecycle !== "Active" ||
             (this.options.onOutcome !== undefined && this.options.skipStoppedOutcome !== true) ||
             this.options.onStop !== undefined ||
+            this.inspector !== undefined ||
             this.current.changes !== undefined ||
             this.current.terminalizing || this.current.snapshot.status !== "active") {
             return false;
@@ -1278,9 +1619,21 @@ class CompiledProcess {
                 (requested._tag === "Stopped" && this.options.skipStoppedOutcome === true)
                 ? Effect.void
                 : Effect.suspend(() => this.options.onOutcome(classifyOutcome(snapshot))).pipe(Effect.exit, Effect.asVoid);
+            const inspector = this.inspector;
+            const subject = this.inspectionSubject;
+            const closeEmissionsAndInspect = inspector === undefined || subject === undefined
+                ? this.closeEmissions()
+                : this.closeEmissions().pipe(Effect.andThen(Effect.sync(() => inspector.publishUnsafe(this.activity === undefined
+                    ? { _tag: "Terminated", subject, snapshot }
+                    : {
+                        _tag: "ActivityStopped",
+                        subject: this.activity.owner,
+                        activity: this.activity,
+                        exit: snapshot.status === "stopped" ? Exit.interrupt() : exit
+                    }))));
             return Effect.uninterruptible(Effect.sync(() => {
                 closeCompactMailbox(this.mailbox);
-            }).pipe(Effect.andThen(this.childRuntime.close(exit)), Effect.andThen(this.setAndPublishSnapshot(snapshot)), Effect.andThen(this.closeEmissions()), Effect.andThen(Effect.sync(() => {
+            }).pipe(Effect.andThen(this.childRuntime.close(exit)), Effect.andThen(this.setAndPublishSnapshot(snapshot)), Effect.andThen(closeEmissionsAndInspect), Effect.andThen(Effect.sync(() => {
                 if (requested._tag === "Failure") {
                     failAcknowledgedMessage(this.inFlightMessage, requested.cause);
                 }
@@ -1288,7 +1641,9 @@ class CompiledProcess {
                     stopAcknowledgedMessage(this.inFlightMessage);
                 }
                 this.inFlightMessage = undefined;
-            })), Effect.andThen(notifyOutcome), Effect.andThen(this.options.onStop ?? Effect.void), Effect.andThen(Effect.sync(() => {
+            })), Effect.andThen(notifyOutcome), Effect.andThen(this.options.onStop ?? Effect.void), Effect.andThen(this.options.inspectionRoot === true && this.inspector !== undefined
+                ? this.inspector.close
+                : Effect.void), Effect.andThen(Effect.sync(() => {
                 this.options.onStopSync?.();
                 this.runState = "Idle";
                 this.worker = undefined;
@@ -1320,11 +1675,21 @@ class CompiledProcess {
             : PubSub.publish(snapshot.changes, Exit.succeed(undefined)).pipe(Effect.asVoid);
     }
     emitEvent(event) {
-        if (this.externalEmissions !== undefined)
-            return this.externalEmissions.emit(event);
-        return Effect.suspend(() => this.emissionsPubSub === undefined || this.emissionsPubSub === EmissionsClosed
-            ? Effect.void
-            : PubSub.publish(this.emissionsPubSub, event).pipe(Effect.asVoid));
+        const publish = this.externalEmissions !== undefined ?
+            this.externalEmissions.emit(event) :
+            Effect.suspend(() => this.emissionsPubSub === undefined || this.emissionsPubSub === EmissionsClosed
+                ? Effect.void
+                : PubSub.publish(this.emissionsPubSub, event).pipe(Effect.asVoid));
+        const inspector = this.inspector;
+        const subject = this.inspectionSubject;
+        if (inspector === undefined || subject === undefined)
+            return publish;
+        return publish.pipe(Effect.tap(() => Effect.sync(() => inspector.publishUnsafe({
+            _tag: "Emitted",
+            subject,
+            emission: event,
+            causedBy: this.causation()
+        }))));
     }
     shutdownEmissions() {
         return this.closeEmissions();
@@ -1533,7 +1898,11 @@ const startCompactCompiledInternal = Effect.fnUntraced(function* (logic, options
         options.onReady === undefined && options.onSnapshot === undefined
         ? process.initializeCompiledSync()
         : process.initialize();
-    return yield* initialize.pipe(Effect.onExit((exit) => Exit.isFailure(exit) ? process.shutdownEmissions() : Effect.void));
+    return yield* initialize.pipe(Effect.onExit((exit) => Exit.isFailure(exit)
+        ? process.shutdownEmissions().pipe(Effect.andThen(options.inspectionRoot === true && options.runtime.inspection !== undefined
+            ? options.runtime.inspection.close
+            : Effect.void))
+        : Effect.void));
 });
 const startLogicInternal = ((logic, options) => logic.execution?._tag === "Compiled"
     ? startCompactCompiledInternal(logic, options)
@@ -1579,6 +1948,8 @@ export const startProcess = Effect.fnUntraced(function* (logic, options) {
 const prepareProcessWithStrategy = Effect.fnUntraced(function* (logic, strategy, options) {
     const runtime = yield* makeProcessRuntime;
     const sessionId = yield* runtime.nextSessionId;
+    const inspection = yield* InspectionRuntime.make(sessionId);
+    runtime.inspection = inspection;
     const emissions = makeEmissionRuntime();
     const started = yield* Deferred.make();
     const internalOptions = options === undefined
@@ -1586,14 +1957,18 @@ const prepareProcessWithStrategy = Effect.fnUntraced(function* (logic, strategy,
             detached: true,
             emissions,
             runtime,
-            sessionId
+            sessionId,
+            inspectionRoot: true,
+            origin: { _tag: "Root" }
         }
         : {
             ...options,
             detached: true,
             emissions,
             runtime,
-            sessionId
+            sessionId,
+            inspectionRoot: true,
+            origin: { _tag: "Root" }
         };
     const initialize = strategy === "generic"
         ? startGenericInternal(logic, internalOptions)
@@ -1608,6 +1983,7 @@ const prepareProcessWithStrategy = Effect.fnUntraced(function* (logic, strategy,
         sessionId,
         changes: Stream.unwrap(Deferred.await(started).pipe(Effect.map((ref) => ref.changes))),
         emissions: emissions.stream,
+        inspection: inspection.stream,
         start
     };
 });