effect-machine 0.9.0 → 0.10.0

package/{dist-v3 → v3/dist}/actor.js

@@ -1,13 +1,13 @@
 import { Inspector } from "./inspection.js";
 import { INTERNAL_INIT_EVENT } from "./internal/utils.js";
-import { DuplicateActorError } from "./errors.js";
+import { ActorStoppedError, DuplicateActorError, NoReplyError } from "./errors.js";
 import { isPersistentMachine } from "./persistence/persistent-machine.js";
-import { processEventCore, resolveTransition, runSpawnEffects } from "./internal/transition.js";
 import { emitWithTimestamp } from "./internal/inspection.js";
+import { processEventCore, resolveTransition, runSpawnEffects, shouldPostpone } from "./internal/transition.js";
 import { PersistenceAdapterTag, PersistenceError } from "./persistence/adapter.js";
 import { createPersistentActor, restorePersistentActor } from "./persistence/persistent-actor.js";
 import { Cause, Context, Deferred, Effect, Exit, Fiber, Layer, MutableHashMap, Option, PubSub, Queue, Ref, Runtime, Scope, Stream, SubscriptionRef } from "effect";
-//#region src-v3/actor.ts
+//#region src/actor.ts
 /**
 * Actor system: spawning, lifecycle, and event processing.
 *
@@ -31,10 +31,50 @@ const notifyListeners = (listeners, state) => {
 /**
 * Build core ActorRef methods shared between regular and persistent actors.
 */
-const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listeners, stop, system, childrenMap) => {
+const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listeners, stop, system, childrenMap, pendingReplies) => {
 	const send = Effect.fn("effect-machine.actor.send")(function* (event) {
 		if (yield* Ref.get(stoppedRef)) return;
-		yield* Queue.offer(eventQueue, event);
+		yield* Queue.offer(eventQueue, {
+			_tag: "send",
+			event
+		});
+	});
+	const call = Effect.fn("effect-machine.actor.call")(function* (event) {
+		if (yield* Ref.get(stoppedRef)) {
+			const currentState = yield* SubscriptionRef.get(stateRef);
+			return {
+				newState: currentState,
+				previousState: currentState,
+				transitioned: false,
+				lifecycleRan: false,
+				isFinal: machine.finalStates.has(currentState._tag)
+			};
+		}
+		const reply = yield* Deferred.make();
+		pendingReplies.add(reply);
+		yield* Queue.offer(eventQueue, {
+			_tag: "call",
+			event,
+			reply
+		});
+		return yield* Deferred.await(reply).pipe(Effect.ensuring(Effect.sync(() => pendingReplies.delete(reply))), Effect.catchTag("ActorStoppedError", () => SubscriptionRef.get(stateRef).pipe(Effect.map((currentState) => ({
+			newState: currentState,
+			previousState: currentState,
+			transitioned: false,
+			lifecycleRan: false,
+			isFinal: machine.finalStates.has(currentState._tag)
+		})))));
+	});
+	const ask = Effect.fn("effect-machine.actor.ask")(function* (event) {
+		if (yield* Ref.get(stoppedRef)) return yield* new ActorStoppedError({ actorId: id });
+		const reply = yield* Deferred.make();
+		pendingReplies.add(reply);
+		yield* Queue.offer(eventQueue, {
+			_tag: "ask",
+			event,
+			reply
+		});
+		return yield* Deferred.await(reply).pipe(Effect.ensuring(Effect.sync(() => pendingReplies.delete(reply))));
 	});
 	const snapshot = SubscriptionRef.get(stateRef).pipe(Effect.withSpan("effect-machine.actor.snapshot"));
 	const matches = Effect.fn("effect-machine.actor.matches")(function* (tag) {
@@ -72,30 +112,38 @@ const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listen
 	return {
 		id,
 		send,
+		cast: send,
+		call,
+		ask,
 		state: stateRef,
 		stop,
-		stopSync: () => Effect.runFork(stop),
 		snapshot,
-		snapshotSync: () => Effect.runSync(SubscriptionRef.get(stateRef)),
 		matches,
-		matchesSync: (tag) => Effect.runSync(SubscriptionRef.get(stateRef))._tag === tag,
 		can,
-		canSync: (event) => {
-			return resolveTransition(machine, Effect.runSync(SubscriptionRef.get(stateRef)), event) !== void 0;
-		},
 		changes: stateRef.changes,
 		waitFor,
 		awaitFinal,
 		sendAndWait,
-		sendSync: (event) => {
-			if (!Effect.runSync(Ref.get(stoppedRef))) Effect.runSync(Queue.offer(eventQueue, event));
-		},
 		subscribe: (fn) => {
 			listeners.add(fn);
 			return () => {
 				listeners.delete(fn);
 			};
 		},
+		sync: {
+			send: (event) => {
+				if (!Effect.runSync(Ref.get(stoppedRef))) Effect.runSync(Queue.offer(eventQueue, {
+					_tag: "send",
+					event
+				}));
+			},
+			stop: () => Effect.runFork(stop),
+			snapshot: () => Effect.runSync(SubscriptionRef.get(stateRef)),
+			matches: (tag) => Effect.runSync(SubscriptionRef.get(stateRef))._tag === tag,
+			can: (event) => {
+				return resolveTransition(machine, Effect.runSync(SubscriptionRef.get(stateRef)), event) !== void 0;
+			}
+		},
 		system,
 		children: childrenMap
 	};
@@ -118,11 +166,16 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 	const eventQueue = yield* Queue.unbounded();
 	const stoppedRef = yield* Ref.make(false);
 	const childrenMap = /* @__PURE__ */ new Map();
+	const selfSend = Effect.fn("effect-machine.actor.self.send")(function* (event) {
+		if (yield* Ref.get(stoppedRef)) return;
+		yield* Queue.offer(eventQueue, {
+			_tag: "send",
+			event
+		});
+	});
 	const self = {
-		send: Effect.fn("effect-machine.actor.self.send")(function* (event) {
-			if (yield* Ref.get(stoppedRef)) return;
-			yield* Queue.offer(eventQueue, event);
-		}),
+		send: selfSend,
+		cast: selfSend,
 		spawn: (childId, childMachine) => Effect.gen(function* () {
 			const child = yield* system.spawn(childId, childMachine).pipe(Effect.provideService(ActorSystem, system));
 			childrenMap.set(childId, child);
@@ -145,6 +198,7 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 	const backgroundFibers = [];
 	const initEvent = { _tag: INTERNAL_INIT_EVENT };
 	const ctx = {
+		actorId: id,
 		state: machine.initial,
 		event: initEvent,
 		self,
@@ -153,6 +207,7 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 	const { effects: effectSlots } = machine._slots;
 	for (const bg of machine.backgroundEffects) {
 		const fiber = yield* Effect.forkDaemon(bg.handler({
+			actorId: id,
 			state: machine.initial,
 			event: initEvent,
 			self,
@@ -174,9 +229,10 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 		}));
 		yield* Ref.set(stoppedRef, true);
 		if (implicitSystemScope !== void 0) yield* Scope.close(implicitSystemScope, Exit.void);
-		return buildActorRefCore(id, machine, stateRef, eventQueue, stoppedRef, listeners, Ref.set(stoppedRef, true).pipe(Effect.withSpan("effect-machine.actor.stop"), Effect.asVoid), system, childrenMap);
+		return buildActorRefCore(id, machine, stateRef, eventQueue, stoppedRef, listeners, Ref.set(stoppedRef, true).pipe(Effect.withSpan("effect-machine.actor.stop"), Effect.asVoid), system, childrenMap, /* @__PURE__ */ new Set());
 	}
-	const loopFiber = yield* Effect.forkDaemon(eventLoop(machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, id, inspectorValue, system));
+	const pendingReplies = /* @__PURE__ */ new Set();
+	const loopFiber = yield* Effect.forkDaemon(eventLoop(machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, id, inspectorValue, system, pendingReplies));
 	return buildActorRefCore(id, machine, stateRef, eventQueue, stoppedRef, listeners, Effect.gen(function* () {
 		const finalState = yield* SubscriptionRef.get(stateRef);
 		yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
@@ -187,31 +243,104 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 		}));
 		yield* Ref.set(stoppedRef, true);
 		yield* Fiber.interrupt(loopFiber);
+		yield* settlePendingReplies(pendingReplies, id);
 		yield* Scope.close(stateScopeRef.current, Exit.void);
 		yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
 		if (implicitSystemScope !== void 0) yield* Scope.close(implicitSystemScope, Exit.void);
-	}).pipe(Effect.withSpan("effect-machine.actor.stop"), Effect.asVoid), system, childrenMap);
+	}).pipe(Effect.withSpan("effect-machine.actor.stop"), Effect.asVoid), system, childrenMap, pendingReplies);
+});
+/** Fail all pending call/ask Deferreds with ActorStoppedError. Safe to call multiple times. */
+const settlePendingReplies = (pendingReplies, actorId) => Effect.sync(() => {
+	const error = new ActorStoppedError({ actorId });
+	for (const deferred of pendingReplies) Effect.runFork(Deferred.fail(deferred, error));
+	pendingReplies.clear();
 });
 /**
-* Main event loop for the actor
+* Main event loop for the actor.
+* Includes postpone buffer — events matching postpone rules are buffered
+* and drained after state tag changes (gen_statem semantics).
 */
-const eventLoop = Effect.fn("effect-machine.actor.eventLoop")(function* (machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, actorId, inspector, system) {
-	while (true) {
-		const event = yield* Queue.take(eventQueue);
+const eventLoop = Effect.fn("effect-machine.actor.eventLoop")(function* (machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, actorId, inspector, system, pendingReplies) {
+	const postponed = [];
+	const hasPostponeRules = machine.postponeRules.length > 0;
+	const processQueued = Effect.fn("effect-machine.actor.processQueued")(function* (queued) {
+		const event = queued.event;
 		const currentState = yield* SubscriptionRef.get(stateRef);
-		if (yield* Effect.withSpan("effect-machine.event.process", { attributes: {
+		if (hasPostponeRules && shouldPostpone(machine, currentState._tag, event._tag)) {
+			postponed.push(queued);
+			if (queued._tag === "call") {
+				const postponedResult = {
+					newState: currentState,
+					previousState: currentState,
+					transitioned: false,
+					lifecycleRan: false,
+					isFinal: false,
+					hasReply: false,
+					reply: void 0,
+					postponed: true
+				};
+				yield* Deferred.succeed(queued.reply, postponedResult);
+			}
+			return {
+				shouldStop: false,
+				stateChanged: false
+			};
+		}
+		const { shouldStop, result } = yield* Effect.withSpan("effect-machine.event.process", { attributes: {
 			"effect_machine.actor.id": actorId,
 			"effect_machine.state.current": currentState._tag,
 			"effect_machine.event.type": event._tag
-		} })(processEvent(machine, currentState, event, stateRef, self, listeners, stateScopeRef, actorId, inspector, system))) {
+		} })(processEvent(machine, currentState, event, stateRef, self, listeners, stateScopeRef, actorId, inspector, system));
+		switch (queued._tag) {
+			case "call":
+				yield* Deferred.succeed(queued.reply, result);
+				break;
+			case "ask":
+				if (result.hasReply) yield* Deferred.succeed(queued.reply, result.reply);
+				else yield* Deferred.fail(queued.reply, new NoReplyError({
+					actorId,
+					eventTag: event._tag
+				}));
+				break;
+		}
+		return {
+			shouldStop,
+			stateChanged: result.lifecycleRan
+		};
+	});
+	while (true) {
+		const { shouldStop, stateChanged } = yield* processQueued(yield* Queue.take(eventQueue));
+		if (shouldStop) {
 			yield* Ref.set(stoppedRef, true);
+			settlePostponedBuffer(postponed, pendingReplies, actorId);
+			yield* settlePendingReplies(pendingReplies, actorId);
 			yield* Scope.close(stateScopeRef.current, Exit.void);
 			yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
 			return;
 		}
+		if (stateChanged && postponed.length > 0) {
+			const drained = postponed.splice(0);
+			for (const entry of drained) if ((yield* processQueued(entry)).shouldStop) {
+				yield* Ref.set(stoppedRef, true);
+				settlePostponedBuffer(postponed, pendingReplies, actorId);
+				yield* settlePendingReplies(pendingReplies, actorId);
+				yield* Scope.close(stateScopeRef.current, Exit.void);
+				yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
+				return;
+			}
+		}
 	}
 });
 /**
+* Settle all reply-bearing entries in the postpone buffer on shutdown.
+* Call entries already had their Deferred settled with the postponed result
+* (so their pendingReplies entry is already removed). Ask/send entries
+* with Deferreds are settled via the pendingReplies registry.
+*/
+const settlePostponedBuffer = (postponed, _pendingReplies, _actorId) => {
+	postponed.length = 0;
+};
+/**
 * Process a single event, returning true if the actor should stop.
 * Wraps processEventCore with actor-specific concerns (inspection, listeners, state ref).
 */
@@ -223,7 +352,7 @@ const processEvent = Effect.fn("effect-machine.actor.processEvent")(function* (m
 		event,
 		timestamp
 	}));
-	const result = yield* processEventCore(machine, currentState, event, self, stateScopeRef, system, inspector === void 0 ? void 0 : {
+	const result = yield* processEventCore(machine, currentState, event, self, stateScopeRef, system, actorId, inspector === void 0 ? void 0 : {
 		onSpawnEffect: (state) => emitWithTimestamp(inspector, (timestamp) => ({
 			type: "@machine.effect",
 			actorId,
@@ -251,7 +380,10 @@ const processEvent = Effect.fn("effect-machine.actor.processEvent")(function* (m
 	});
 	if (!result.transitioned) {
 		yield* Effect.annotateCurrentSpan("effect_machine.transition.matched", false);
-		return false;
+		return {
+			shouldStop: false,
+			result
+		};
 	}
 	yield* Effect.annotateCurrentSpan("effect_machine.transition.matched", true);
 	yield* SubscriptionRef.set(stateRef, result.newState);
@@ -266,10 +398,16 @@ const processEvent = Effect.fn("effect-machine.actor.processEvent")(function* (m
 				finalState: result.newState,
 				timestamp
 			}));
-			return true;
+			return {
+				shouldStop: true,
+				result
+			};
 		}
 	}
-	return false;
+	return {
+		shouldStop: false,
+		result
+	};
 });
 /**
 * Run spawn effects with actor-specific inspection and tracing.
@@ -284,7 +422,7 @@ const runSpawnEffectsWithInspection = Effect.fn("effect-machine.actor.spawnEffec
 		state,
 		timestamp
 	}));
-	yield* runSpawnEffects(machine, state, event, self, stateScope, system, inspector === void 0 ? void 0 : (info) => emitWithTimestamp(inspector, (timestamp) => ({
+	yield* runSpawnEffects(machine, state, event, self, stateScope, system, actorId, inspector === void 0 ? void 0 : (info) => emitWithTimestamp(inspector, (timestamp) => ({
 		type: "@machine.error",
 		actorId,
 		phase: info.phase,
@@ -305,13 +443,13 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 	const withSpawnGate = (yield* Effect.makeSemaphore(1)).withPermits(1);
 	const eventPubSub = yield* PubSub.unbounded();
 	const eventListeners = /* @__PURE__ */ new Set();
-	const emitSystemEvent = (event) => Effect.sync(() => notifySystemListeners(eventListeners, event)).pipe(Effect.andThen(PubSub.publish(eventPubSub, event)), Effect.catchAllCause(() => Effect.void), Effect.asVoid);
+	const emitSystemEvent = (event) => Effect.sync(() => notifySystemListeners(eventListeners, event)).pipe(Effect.zipRight(PubSub.publish(eventPubSub, event)), Effect.catchAllCause(() => Effect.void), Effect.asVoid);
 	yield* Effect.addFinalizer(() => {
 		const stops = [];
 		MutableHashMap.forEach(actorsMap, (actor) => {
 			stops.push(actor.stop);
 		});
-		return Effect.all(stops, { concurrency: "unbounded" }).pipe(Effect.andThen(PubSub.shutdown(eventPubSub)), Effect.asVoid);
+		return Effect.all(stops, { concurrency: "unbounded" }).pipe(Effect.zipRight(PubSub.shutdown(eventPubSub)), Effect.asVoid);
 	});
 	/** Check for duplicate ID, register actor, attach scope cleanup if available */
 	const registerActor = Effect.fn("effect-machine.actorSystem.register")(function* (id, actor) {
@@ -454,4 +592,4 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 */
 const Default = Layer.scoped(ActorSystem, make());
 //#endregion
-export { ActorSystem, Default, buildActorRefCore, createActor, notifyListeners, processEventCore, resolveTransition, runSpawnEffects };
+export { ActorSystem, Default, buildActorRefCore, createActor, notifyListeners, processEventCore, resolveTransition, runSpawnEffects, settlePendingReplies };

package/{dist-v3 → v3/dist}/cluster/entity-machine.d.ts

@@ -5,7 +5,7 @@ import { Layer } from "effect";
 import { Entity } from "@effect/cluster";
 import { Rpc } from "@effect/rpc";
 
-//#region src-v3/cluster/entity-machine.d.ts
+//#region src/cluster/entity-machine.d.ts
 /**
  * Options for EntityMachine.layer
  */

package/{dist-v3 → v3/dist}/cluster/entity-machine.js

@@ -2,7 +2,7 @@ import { processEventCore, runSpawnEffects } from "../internal/transition.js";
 import { ActorSystem } from "../actor.js";
 import { Effect, Option, Queue, Ref, Scope } from "effect";
 import { Entity } from "@effect/cluster";
-//#region src-v3/cluster/entity-machine.ts
+//#region src/cluster/entity-machine.ts
 /**
 * EntityMachine adapter - wires a machine to a cluster Entity layer.
 *
@@ -13,7 +13,7 @@ import { Entity } from "@effect/cluster";
 * Returns the new state after processing.
 */
 const processEvent = Effect.fn("effect-machine.cluster.processEvent")(function* (machine, stateRef, event, self, stateScopeRef, system, hooks) {
-	const result = yield* processEventCore(machine, yield* Ref.get(stateRef), event, self, stateScopeRef, system, hooks);
+	const result = yield* processEventCore(machine, yield* Ref.get(stateRef), event, self, stateScopeRef, system, "*", hooks);
 	if (result.transitioned) yield* Ref.set(stateRef, result.newState);
 	return result.newState;
 });
@@ -54,15 +54,17 @@ const EntityMachine = { layer: (entity, machine, options) => {
 		if (Option.isNone(existingSystem)) return yield* Effect.die("EntityMachine requires ActorSystem in context");
 		const system = existingSystem.value;
 		const internalQueue = yield* Queue.unbounded();
+		const clusterSend = Effect.fn("effect-machine.cluster.self.send")(function* (event) {
+			yield* Queue.offer(internalQueue, event);
+		});
 		const self = {
-			send: Effect.fn("effect-machine.cluster.self.send")(function* (event) {
-				yield* Queue.offer(internalQueue, event);
-			}),
+			send: clusterSend,
+			cast: clusterSend,
 			spawn: (childId, childMachine) => system.spawn(childId, childMachine).pipe(Effect.provideService(ActorSystem, system))
 		};
 		const stateRef = yield* Ref.make(initialState);
 		const stateScopeRef = { current: yield* Scope.make() };
-		yield* runSpawnEffects(machine, initialState, { _tag: "$init" }, self, stateScopeRef.current, system, options?.hooks?.onError);
+		yield* runSpawnEffects(machine, initialState, { _tag: "$init" }, self, stateScopeRef.current, system, entityId, options?.hooks?.onError);
 		const runInternalEvent = Effect.fn("effect-machine.cluster.internalEvent")(function* () {
 			yield* processEvent(machine, stateRef, yield* Queue.take(internalQueue), self, stateScopeRef, system, options?.hooks);
 		});

package/{dist-v3 → v3/dist}/cluster/to-entity.d.ts

@@ -2,7 +2,7 @@ import { Machine } from "../machine.js";
 import { Schema } from "effect";
 import { Rpc } from "@effect/rpc";
 
-//#region src-v3/cluster/to-entity.d.ts
+//#region src/cluster/to-entity.d.ts
 /**
  * Options for toEntity.
  */

package/{dist-v3 → v3/dist}/cluster/to-entity.js

@@ -1,7 +1,7 @@
 import { MissingSchemaError } from "../errors.js";
 import { Entity } from "@effect/cluster";
 import { Rpc } from "@effect/rpc";
-//#region src-v3/cluster/to-entity.ts
+//#region src/cluster/to-entity.ts
 /**
 * Generate Entity definition from a machine.
 *

package/v3/dist/errors.d.ts

@@ -0,0 +1,76 @@
+import { Schema } from "effect";
+
+//#region src/errors.d.ts
+declare const DuplicateActorError_base: Schema.TaggedErrorClass<DuplicateActorError, "DuplicateActorError", {
+  readonly _tag: Schema.tag<"DuplicateActorError">;
+} & {
+  actorId: typeof Schema.String;
+}>;
+/** Attempted to spawn/restore actor with ID already in use */
+declare class DuplicateActorError extends DuplicateActorError_base {}
+declare const UnprovidedSlotsError_base: Schema.TaggedErrorClass<UnprovidedSlotsError, "UnprovidedSlotsError", {
+  readonly _tag: Schema.tag<"UnprovidedSlotsError">;
+} & {
+  slots: Schema.Array$<typeof Schema.String>;
+}>;
+/** Machine has unprovided effect slots */
+declare class UnprovidedSlotsError extends UnprovidedSlotsError_base {}
+declare const MissingSchemaError_base: Schema.TaggedErrorClass<MissingSchemaError, "MissingSchemaError", {
+  readonly _tag: Schema.tag<"MissingSchemaError">;
+} & {
+  operation: typeof Schema.String;
+}>;
+/** Operation requires schemas attached to machine */
+declare class MissingSchemaError extends MissingSchemaError_base {}
+declare const InvalidSchemaError_base: Schema.TaggedErrorClass<InvalidSchemaError, "InvalidSchemaError", {
+  readonly _tag: Schema.tag<"InvalidSchemaError">;
+}>;
+/** State/Event schema has no variants */
+declare class InvalidSchemaError extends InvalidSchemaError_base {}
+declare const MissingMatchHandlerError_base: Schema.TaggedErrorClass<MissingMatchHandlerError, "MissingMatchHandlerError", {
+  readonly _tag: Schema.tag<"MissingMatchHandlerError">;
+} & {
+  tag: typeof Schema.String;
+}>;
+/** $match called with missing handler for tag */
+declare class MissingMatchHandlerError extends MissingMatchHandlerError_base {}
+declare const SlotProvisionError_base: Schema.TaggedErrorClass<SlotProvisionError, "SlotProvisionError", {
+  readonly _tag: Schema.tag<"SlotProvisionError">;
+} & {
+  slotName: typeof Schema.String;
+  slotType: Schema.Literal<["guard", "effect"]>;
+}>;
+/** Slot handler not found at runtime (internal error) */
+declare class SlotProvisionError extends SlotProvisionError_base {}
+declare const ProvisionValidationError_base: Schema.TaggedErrorClass<ProvisionValidationError, "ProvisionValidationError", {
+  readonly _tag: Schema.tag<"ProvisionValidationError">;
+} & {
+  missing: Schema.Array$<typeof Schema.String>;
+  extra: Schema.Array$<typeof Schema.String>;
+}>;
+/** Machine.build() validation failed - missing or extra handlers */
+declare class ProvisionValidationError extends ProvisionValidationError_base {}
+declare const AssertionError_base: Schema.TaggedErrorClass<AssertionError, "AssertionError", {
+  readonly _tag: Schema.tag<"AssertionError">;
+} & {
+  message: typeof Schema.String;
+}>;
+/** Assertion failed in testing utilities */
+declare class AssertionError extends AssertionError_base {}
+declare const ActorStoppedError_base: Schema.TaggedErrorClass<ActorStoppedError, "ActorStoppedError", {
+  readonly _tag: Schema.tag<"ActorStoppedError">;
+} & {
+  actorId: typeof Schema.String;
+}>;
+/** Actor was stopped while a call/ask was pending */
+declare class ActorStoppedError extends ActorStoppedError_base {}
+declare const NoReplyError_base: Schema.TaggedErrorClass<NoReplyError, "NoReplyError", {
+  readonly _tag: Schema.tag<"NoReplyError">;
+} & {
+  actorId: typeof Schema.String;
+  eventTag: typeof Schema.String;
+}>;
+/** ask() was used but the transition handler did not call reply */
+declare class NoReplyError extends NoReplyError_base {}
+//#endregion
+export { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, NoReplyError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError };

package/{dist-v3 → v3/dist}/errors.js

@@ -1,5 +1,5 @@
 import { Schema } from "effect";
-//#region src-v3/errors.ts
+//#region src/errors.ts
 /**
 * Typed error classes for effect-machine.
 *
@@ -32,5 +32,12 @@ var ProvisionValidationError = class extends Schema.TaggedError()("ProvisionVali
 }) {};
 /** Assertion failed in testing utilities */
 var AssertionError = class extends Schema.TaggedError()("AssertionError", { message: Schema.String }) {};
+/** Actor was stopped while a call/ask was pending */
+var ActorStoppedError = class extends Schema.TaggedError()("ActorStoppedError", { actorId: Schema.String }) {};
+/** ask() was used but the transition handler did not call reply */
+var NoReplyError = class extends Schema.TaggedError()("NoReplyError", {
+	actorId: Schema.String,
+	eventTag: Schema.String
+}) {};
 //#endregion
-export { AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError };
+export { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, NoReplyError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError };

package/v3/dist/index.d.ts

@@ -0,0 +1,13 @@
+import { EffectHandlers, EffectSlot, EffectSlots, EffectsDef, EffectsSchema, GuardHandlers, GuardSlot, GuardSlots, GuardsDef, GuardsSchema, MachineContext, Slot } from "./slot.js";
+import { Event, MachineEventSchema, MachineStateSchema, State } from "./schema.js";
+import { PersistenceConfig, PersistentMachine, isPersistentMachine } from "./persistence/persistent-machine.js";
+import { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, NoReplyError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError } from "./errors.js";
+import { ProcessEventResult } from "./internal/transition.js";
+import { PersistentActorRef, createPersistentActor, restorePersistentActor } from "./persistence/persistent-actor.js";
+import { ActorMetadata, PersistedEvent, PersistenceAdapter, PersistenceAdapterTag, PersistenceError, RestoreFailure, RestoreResult, Snapshot, VersionConflictError } from "./persistence/adapter.js";
+import { InMemoryPersistenceAdapter, makeInMemoryPersistenceAdapter } from "./persistence/adapters/in-memory.js";
+import { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, ProvideHandlers, SpawnEffect, StateHandlerContext, TaskOptions, Transition, machine_d_exports } from "./machine.js";
+import { ActorRef, ActorRefSync, ActorSystem, Default, SystemEvent, SystemEventListener } from "./actor.js";
+import { SimulationResult, TestHarness, TestHarnessOptions, assertNeverReaches, assertPath, assertReaches, createTestHarness, simulate } from "./testing.js";
+import { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, InspectionEvent, Inspector, InspectorHandler, SpawnEvent, StopEvent, TaskEvent, TracingInspectorOptions, TransitionEvent, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector } from "./inspection.js";
+export { type ActorMetadata, type ActorRef, type ActorRefSync, ActorStoppedError, type ActorSystem, Default as ActorSystemDefault, ActorSystem as ActorSystemService, type AnyInspectionEvent, AssertionError, type BackgroundEffect, type BuiltMachine, DuplicateActorError, type EffectEvent, type EffectSlots, type EffectsDef, type EffectsSchema, type ErrorEvent, Event, type EventReceivedEvent, type GuardHandlers, type GuardSlot, type GuardSlots, type GuardsDef, type GuardsSchema, type HandlerContext, InMemoryPersistenceAdapter, type InspectionEvent, type Inspector, type InspectorHandler, Inspector as InspectorService, InvalidSchemaError, machine_d_exports as Machine, type MachineContext, type MachineEventSchema, type MachineRef, type MachineStateSchema, type Machine as MachineType, type MakeConfig, MissingMatchHandlerError, MissingSchemaError, NoReplyError, type PersistOptions, type PersistedEvent, type PersistenceAdapter, PersistenceAdapterTag, type PersistenceConfig, PersistenceError, type PersistentActorRef, type PersistentMachine, type ProcessEventResult, type ProvideHandlers, ProvisionValidationError, type RestoreFailure, type RestoreResult, type SimulationResult, Slot, type EffectHandlers as SlotEffectHandlers, type EffectSlot as SlotEffectSlot, SlotProvisionError, type Snapshot, type SpawnEffect, type SpawnEvent, State, type StateHandlerContext, type StopEvent, type SystemEvent, type SystemEventListener, type TaskEvent, type TaskOptions, type TestHarness, type TestHarnessOptions, type TracingInspectorOptions, type Transition, type TransitionEvent, UnprovidedSlotsError, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createPersistentActor, createTestHarness, isPersistentMachine, makeInMemoryPersistenceAdapter, makeInspector, makeInspectorEffect, restorePersistentActor, simulate, tracingInspector };

package/v3/dist/index.js

@@ -0,0 +1,13 @@
+import { Inspector, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector } from "./inspection.js";
+import { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, NoReplyError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError } from "./errors.js";
+import { isPersistentMachine } from "./persistence/persistent-machine.js";
+import { Slot } from "./slot.js";
+import { machine_exports } from "./machine.js";
+import { PersistenceAdapterTag, PersistenceError, VersionConflictError } from "./persistence/adapter.js";
+import { createPersistentActor, restorePersistentActor } from "./persistence/persistent-actor.js";
+import { ActorSystem, Default } from "./actor.js";
+import { Event, State } from "./schema.js";
+import { assertNeverReaches, assertPath, assertReaches, createTestHarness, simulate } from "./testing.js";
+import { InMemoryPersistenceAdapter, makeInMemoryPersistenceAdapter } from "./persistence/adapters/in-memory.js";
+import "./persistence/index.js";
+export { ActorStoppedError, Default as ActorSystemDefault, ActorSystem as ActorSystemService, AssertionError, DuplicateActorError, Event, InMemoryPersistenceAdapter, Inspector as InspectorService, InvalidSchemaError, machine_exports as Machine, MissingMatchHandlerError, MissingSchemaError, NoReplyError, PersistenceAdapterTag, PersistenceError, ProvisionValidationError, Slot, SlotProvisionError, State, UnprovidedSlotsError, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createPersistentActor, createTestHarness, isPersistentMachine, makeInMemoryPersistenceAdapter, makeInspector, makeInspectorEffect, restorePersistentActor, simulate, tracingInspector };

package/{dist-v3 → v3/dist}/inspection.d.ts

@@ -1,6 +1,6 @@
-import { Schema } from "effect";
+import { Context, Effect, Schema } from "effect";
 
-//#region src-v3/inspection.d.ts
+//#region src/inspection.d.ts
 /**
  * Resolve a type param: if it's a Schema, extract `.Type`; otherwise use as-is.
  */
@@ -45,6 +45,18 @@ interface EffectEvent<S> {
   readonly state: S;
   readonly timestamp: number;
 }
+/**
+ * Event emitted when a task lifecycle phase occurs
+ */
+interface TaskEvent<S> {
+  readonly type: "@machine.task";
+  readonly actorId: string;
+  readonly state: S;
+  readonly taskName?: string;
+  readonly phase: "start" | "success" | "failure" | "interrupt";
+  readonly error?: string;
+  readonly timestamp: number;
+}
 /**
  * Event emitted when a transition handler or spawn effect fails with a defect
  */
@@ -69,7 +81,7 @@ interface StopEvent<S> {
 /**
  * Union of all inspection events
  */
-type InspectionEvent<S, E> = SpawnEvent<S> | EventReceivedEvent<S, E> | TransitionEvent<S, E> | EffectEvent<S> | ErrorEvent<S, E> | StopEvent<S>;
+type InspectionEvent<S, E> = SpawnEvent<S> | EventReceivedEvent<S, E> | TransitionEvent<S, E> | EffectEvent<S> | TaskEvent<S> | ErrorEvent<S, E> | StopEvent<S>;
 /**
  * Convenience alias for untyped inspection events.
  * Useful for general-purpose inspectors that don't need specific state/event types.
@@ -81,19 +93,23 @@ type AnyInspectionEvent = InspectionEvent<{
 }, {
   readonly _tag: string;
 }>;
+/**
+ * Inspector handler — sync callback or Effect-returning callback.
+ */
+type InspectorHandler<S, E> = (event: InspectionEvent<S, E>) => void | Effect.Effect<void, never, never>;
 /**
  * Inspector interface for observing machine behavior
  */
 interface Inspector<S, E> {
-  readonly onInspect: (event: InspectionEvent<S, E>) => void;
+  readonly onInspect: InspectorHandler<S, E>;
 }
 /**
  * Inspector service tag - optional service for machine introspection
  * Uses `any` types to allow variance flexibility when providing the service
  */
-declare const Inspector: any;
+declare const Inspector: Context.Tag<Inspector<any, any>, Inspector<any, any>>;
 /**
- * Create an inspector from a callback function.
+ * Create an inspector from a sync callback function.
  *
  * Type params accept either raw tagged types or Schema constructors:
  * - `makeInspector(cb)` — defaults to `AnyInspectionEvent`
@@ -104,7 +120,36 @@ declare const makeInspector: <S = {
   readonly _tag: string;
 }, E = {
   readonly _tag: string;
-}>(onInspect: (event: InspectionEvent<ResolveType<S>, ResolveType<E>>) => void) => Inspector<ResolveType<S>, ResolveType<E>>;
+}>(onInspect: InspectorHandler<ResolveType<S>, ResolveType<E>>) => Inspector<ResolveType<S>, ResolveType<E>>;
+/**
+ * Create an inspector from an Effect-returning callback function.
+ */
+declare const makeInspectorEffect: <S = {
+  readonly _tag: string;
+}, E = {
+  readonly _tag: string;
+}>(onInspect: (event: InspectionEvent<ResolveType<S>, ResolveType<E>>) => Effect.Effect<void, never, never>) => Inspector<ResolveType<S>, ResolveType<E>>;
+/**
+ * Combine multiple inspectors into one. All run concurrently per event.
+ * Individual inspector failures are swallowed.
+ */
+declare const combineInspectors: <S, E>(...inspectors: ReadonlyArray<Inspector<S, E>>) => Inspector<S, E>;
+/**
+ * Options for the tracing inspector.
+ */
+interface TracingInspectorOptions<S, E> {
+  readonly spanName?: string | ((event: InspectionEvent<S, E>) => string);
+  readonly attributes?: (event: InspectionEvent<S, E>) => Readonly<Record<string, string | number | boolean>>;
+  readonly eventName?: (event: InspectionEvent<S, E>) => string;
+}
+/**
+ * Inspector that emits OpenTelemetry spans and events for each inspection event.
+ */
+declare const tracingInspector: <S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}>(options?: TracingInspectorOptions<S, E>) => Inspector<S, E>;
 /**
  * Console inspector that logs events in a readable format
  */
@@ -122,4 +167,4 @@ declare const collectingInspector: <S extends {
   readonly _tag: string;
 }>(events: InspectionEvent<S, E>[]) => Inspector<S, E>;
 //#endregion
-export { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, InspectionEvent, Inspector, SpawnEvent, StopEvent, TransitionEvent, collectingInspector, consoleInspector, makeInspector };
+export { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, InspectionEvent, Inspector, InspectorHandler, SpawnEvent, StopEvent, TaskEvent, TracingInspectorOptions, TransitionEvent, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector };