effect-machine 0.9.0 → 0.10.0

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

@@ -1,12 +1,14 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+import { Inspector } from "./inspection.js";
 import { getTag } from "./internal/utils.js";
 import { ProvisionValidationError, SlotProvisionError } from "./errors.js";
 import { persist } from "./persistence/persistent-machine.js";
+import { emitWithTimestamp } from "./internal/inspection.js";
 import { MachineContextTag } from "./slot.js";
 import { findTransitions, invalidateIndex } from "./internal/transition.js";
 import { createActor } from "./actor.js";
 import { Cause, Effect, Exit, Option, Scope } from "effect";
-//#region src-v3/machine.ts
+//#region src/machine.ts
 var machine_exports = /* @__PURE__ */ __exportAll({
 	BuiltMachine: () => BuiltMachine,
 	Machine: () => Machine,
@@ -14,6 +16,15 @@ var machine_exports = /* @__PURE__ */ __exportAll({
 	make: () => make,
 	spawn: () => spawn
 });
+const emitTaskInspection = (input) => Effect.flatMap(Effect.serviceOptional(Inspector).pipe(Effect.option), (inspector) => Option.isNone(inspector) ? Effect.void : emitWithTimestamp(inspector.value, (timestamp) => ({
+	type: "@machine.task",
+	actorId: input.actorId,
+	state: input.state,
+	taskName: input.taskName,
+	phase: input.phase,
+	error: input.error,
+	timestamp
+})));
 /**
 * A finalized machine ready for spawning.
 *
@@ -53,6 +64,7 @@ var Machine = class Machine {
 	/** @internal */ _spawnEffects;
 	/** @internal */ _backgroundEffects;
 	/** @internal */ _finalStates;
+	/** @internal */ _postponeRules;
 	/** @internal */ _guardsSchema;
 	/** @internal */ _effectsSchema;
 	/** @internal */ _guardHandlers;
@@ -77,6 +89,9 @@ var Machine = class Machine {
 	get finalStates() {
 		return this._finalStates;
 	}
+	get postponeRules() {
+		return this._postponeRules;
+	}
 	get guardsSchema() {
 		return this._guardsSchema;
 	}
@@ -90,6 +105,7 @@ var Machine = class Machine {
 		this._spawnEffects = [];
 		this._backgroundEffects = [];
 		this._finalStates = /* @__PURE__ */ new Set();
+		this._postponeRules = [];
 		this._guardsSchema = guardsSchema;
 		this._effectsSchema = effectsSchema;
 		this._guardHandlers = /* @__PURE__ */ new Map();
@@ -116,6 +132,15 @@ var Machine = class Machine {
 			})) : {}
 		};
 	}
+	from(stateOrStates, build) {
+		build(new TransitionScope(this, Array.isArray(stateOrStates) ? stateOrStates : [stateOrStates]));
+		return this;
+	}
+	/** @internal */
+	scopeTransition(states, event, handler, reenter) {
+		for (const state of states) this.addTransition(state, event, handler, reenter);
+		return this;
+	}
 	on(stateOrStates, event, handler) {
 		const states = Array.isArray(stateOrStates) ? stateOrStates : [stateOrStates];
 		for (const s of states) this.addTransition(s, event, handler, false);
@@ -190,14 +215,41 @@ var Machine = class Machine {
 	*/
 	task(state, run, options) {
 		const handler = Effect.fn("effect-machine.task")(function* (ctx) {
+			yield* emitTaskInspection({
+				actorId: ctx.actorId,
+				state: ctx.state,
+				taskName: options.name,
+				phase: "start"
+			});
 			const exit = yield* Effect.exit(run(ctx));
 			if (Exit.isSuccess(exit)) {
+				yield* emitTaskInspection({
+					actorId: ctx.actorId,
+					state: ctx.state,
+					taskName: options.name,
+					phase: "success"
+				});
 				yield* ctx.self.send(options.onSuccess(exit.value, ctx));
 				yield* Effect.yieldNow();
 				return;
 			}
 			const cause = exit.cause;
-			if (Cause.isInterruptedOnly(cause)) return;
+			if (Cause.isInterruptedOnly(cause)) {
+				yield* emitTaskInspection({
+					actorId: ctx.actorId,
+					state: ctx.state,
+					taskName: options.name,
+					phase: "interrupt"
+				});
+				return;
+			}
+			yield* emitTaskInspection({
+				actorId: ctx.actorId,
+				state: ctx.state,
+				taskName: options.name,
+				phase: "failure",
+				error: Cause.pretty(cause)
+			});
 			if (options.onFailure !== void 0) {
 				yield* ctx.self.send(options.onFailure(cause, ctx));
 				yield* Effect.yieldNow();
@@ -208,6 +260,36 @@ var Machine = class Machine {
 		return this.spawn(state, handler);
 	}
 	/**
+	* State timeout — gen_statem's `state_timeout`.
+	*
+	* Entering the state starts a timer. Leaving cancels it (via state scope).
+	* `.reenter()` restarts the timer with fresh state values.
+	* Compiles to `.task()` internally — preserves `@machine.task` inspection events.
+	*
+	* @example
+	* ```ts
+	* machine
+	*   .timeout(State.Loading, {
+	*     duration: Duration.seconds(30),
+	*     event: Event.Timeout,
+	*   })
+	*   // Dynamic duration from state
+	*   .timeout(State.Retrying, {
+	*     duration: (state) => Duration.seconds(state.backoff),
+	*     event: Event.GiveUp,
+	*   })
+	* ```
+	*/
+	timeout(state, config) {
+		const stateTag = getTag(state);
+		const resolveDuration = typeof config.duration === "function" ? config.duration : () => config.duration;
+		const resolveEvent = typeof config.event === "function" ? config.event : () => config.event;
+		return this.task(state, (ctx) => Effect.sleep(resolveDuration(ctx.state)), {
+			onSuccess: (_, ctx) => resolveEvent(ctx.state),
+			name: `$timeout:${stateTag}`
+		});
+	}
+	/**
 	* Machine-lifetime effect that is forked on actor spawn and runs until the actor stops.
 	* Use effect slots defined via `Slot.Effects` for the actual work.
 	*
@@ -231,6 +313,35 @@ var Machine = class Machine {
 		this._backgroundEffects.push({ handler });
 		return this;
 	}
+	/**
+	* Postpone events — gen_statem's event postpone.
+	*
+	* When a matching event arrives in the given state, it is buffered instead of
+	* processed. After the next state transition (tag change), all buffered events
+	* are drained through the loop in FIFO order.
+	*
+	* Reply-bearing events (from `call`/`ask`) in the postpone buffer are settled
+	* with `ActorStoppedError` on stop/interrupt/final-state.
+	*
+	* @example
+	* ```ts
+	* machine
+	*   .postpone(State.Connecting, Event.Data)           // single event
+	*   .postpone(State.Connecting, [Event.Data, Event.Cmd]) // multiple events
+	* ```
+	*/
+	postpone(state, events) {
+		const stateTag = getTag(state);
+		const eventList = Array.isArray(events) ? events : [events];
+		for (const ev of eventList) {
+			const eventTag = getTag(ev);
+			this._postponeRules.push({
+				stateTag,
+				eventTag
+			});
+		}
+		return this;
+	}
 	final(state) {
 		const stateTag = getTag(state);
 		this._finalStates.add(stateTag);
@@ -262,6 +373,7 @@ var Machine = class Machine {
 			result._finalStates = new Set(this._finalStates);
 			result._spawnEffects = [...this._spawnEffects];
 			result._backgroundEffects = [...this._backgroundEffects];
+			result._postponeRules = [...this._postponeRules];
 			const anyHandlers = handlers;
 			if (this._guardsSchema !== void 0) for (const name of Object.keys(this._guardsSchema.definitions)) result._guardHandlers.set(name, anyHandlers[name]);
 			if (this._effectsSchema !== void 0) for (const name of Object.keys(this._effectsSchema.definitions)) result._effectHandlers.set(name, anyHandlers[name]);
@@ -277,6 +389,20 @@ var Machine = class Machine {
 		return new Machine(config.initial, config.state, config.event, config.guards, config.effects);
 	}
 };
+var TransitionScope = class {
+	constructor(machine, states) {
+		this.machine = machine;
+		this.states = states;
+	}
+	on(event, handler) {
+		this.machine.scopeTransition(this.states, event, handler, false);
+		return this;
+	}
+	reenter(event, handler) {
+		this.machine.scopeTransition(this.states, event, handler, true);
+		return this;
+	}
+};
 const make = Machine.make;
 const spawn = Effect.fn("effect-machine.spawn")(function* (built, id) {
 	const actor = yield* createActor(id ?? `actor-${Math.random().toString(36).slice(2)}`, built._inner);

package/{dist-v3 → v3/dist}/persistence/adapter.d.ts

@@ -1,8 +1,8 @@
 import { DuplicateActorError } from "../errors.js";
 import { PersistentActorRef } from "./persistent-actor.js";
-import { Effect, Option, Schema } from "effect";
+import { Context, Effect, Option, Schema } from "effect";
 
-//#region src-v3/persistence/adapter.d.ts
+//#region src/persistence/adapter.d.ts
 /**
  * Metadata for a persisted actor.
  * Used for discovery and filtering during bulk restore.
@@ -106,17 +106,30 @@ interface PersistenceAdapter {
    */
   readonly loadMetadata?: (id: string) => Effect.Effect<Option.Option<ActorMetadata>, PersistenceError>;
 }
-declare const PersistenceError_base: any;
+declare const PersistenceError_base: Schema.TaggedErrorClass<PersistenceError, "PersistenceError", {
+  readonly _tag: Schema.tag<"PersistenceError">;
+} & {
+  operation: typeof Schema.String;
+  actorId: typeof Schema.String;
+  cause: Schema.optional<typeof Schema.Unknown>;
+  message: Schema.optional<typeof Schema.String>;
+}>;
 /**
  * Error type for persistence operations
  */
 declare class PersistenceError extends PersistenceError_base {}
-declare const VersionConflictError_base: any;
+declare const VersionConflictError_base: Schema.TaggedErrorClass<VersionConflictError, "VersionConflictError", {
+  readonly _tag: Schema.tag<"VersionConflictError">;
+} & {
+  actorId: typeof Schema.String;
+  expectedVersion: typeof Schema.Number;
+  actualVersion: typeof Schema.Number;
+}>;
 /**
  * Version conflict error — snapshot version doesn't match expected
  */
 declare class VersionConflictError extends VersionConflictError_base {}
-declare const PersistenceAdapterTag_base: any;
+declare const PersistenceAdapterTag_base: Context.TagClass<PersistenceAdapterTag, "effect-machine/src/persistence/adapter/PersistenceAdapterTag", PersistenceAdapter>;
 /**
  * PersistenceAdapter service tag
  */

package/{dist-v3 → v3/dist}/persistence/adapter.js

@@ -1,5 +1,5 @@
 import { Context, Schema } from "effect";
-//#region src-v3/persistence/adapter.ts
+//#region src/persistence/adapter.ts
 /**
 * Error type for persistence operations
 */

package/{dist-v3 → v3/dist}/persistence/adapters/in-memory.d.ts

@@ -1,7 +1,7 @@
 import { PersistenceAdapter, PersistenceAdapterTag } from "../adapter.js";
 import { Effect, Layer } from "effect";
 
-//#region src-v3/persistence/adapters/in-memory.d.ts
+//#region src/persistence/adapters/in-memory.d.ts
 /**
  * Create an in-memory persistence adapter effect.
  * Returns the adapter directly for custom layer composition.

package/{dist-v3 → v3/dist}/persistence/adapters/in-memory.js

@@ -1,6 +1,6 @@
 import { PersistenceAdapterTag, PersistenceError, VersionConflictError } from "../adapter.js";
 import { Effect, Layer, Option, Ref, Schema } from "effect";
-//#region src-v3/persistence/adapters/in-memory.ts
+//#region src/persistence/adapters/in-memory.ts
 /**
 * Create an in-memory persistence adapter.
 * Useful for testing and development.

package/{dist-v3 → v3/dist}/persistence/persistent-actor.d.ts

@@ -1,10 +1,11 @@
+import { EffectsDef, GuardsDef, MachineContext } from "../slot.js";
 import { PersistentMachine } from "./persistent-machine.js";
-import { EffectsDef, GuardsDef } from "../slot.js";
-import { PersistedEvent, PersistenceError, Snapshot, VersionConflictError } from "./adapter.js";
+import { PersistedEvent, PersistenceAdapterTag, PersistenceError, Snapshot, VersionConflictError } from "./adapter.js";
+import { MachineRef } from "../machine.js";
 import { ActorRef } from "../actor.js";
-import { Effect, Option } from "effect";
+import { Effect, Option, Scope } from "effect";
 
-//#region src-v3/persistence/persistent-actor.d.ts
+//#region src/persistence/persistent-actor.d.ts
 /**
  * Extended ActorRef with persistence capabilities
  */
@@ -35,7 +36,7 @@ declare const createPersistentActor: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(id: string, persistentMachine: PersistentMachine<S, E, R>, initialSnapshot: Option.Option<Snapshot<S>>, initialEvents: readonly PersistedEvent<E>[]) => Effect.Effect<PersistentActorRef<S, E, R>, unknown, unknown>;
+}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(id: string, persistentMachine: PersistentMachine<S, E, R>, initialSnapshot: Option.Option<Snapshot<S>>, initialEvents: readonly PersistedEvent<E>[]) => Effect.Effect<PersistentActorRef<S, E, R>, PersistenceError, PersistenceAdapterTag | Exclude<R, MachineContext<S, E, MachineRef<E>>> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>>;
 /**
  * Restore an actor from persistence.
  * Returns None if no persisted state exists.
@@ -44,6 +45,6 @@ declare const restorePersistentActor: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R>(id: string, persistentMachine: PersistentMachine<S, E, R>) => Effect.Effect<Option.None<PersistentActorRef<S, E, R>> | Option.Some<PersistentActorRef<S, E, R>>, unknown, unknown>;
+}, R>(id: string, persistentMachine: PersistentMachine<S, E, R>) => Effect.Effect<Option.None<PersistentActorRef<S, E, R>> | Option.Some<PersistentActorRef<S, E, R>>, PersistenceError, PersistenceAdapterTag | Exclude<R, MachineContext<S, E, MachineRef<E>>> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>>;
 //#endregion
 export { PersistentActorRef, createPersistentActor, restorePersistentActor };

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

@@ -1,11 +1,12 @@
 import { Inspector } from "../inspection.js";
 import { INTERNAL_INIT_EVENT, stubSystem } from "../internal/utils.js";
-import { processEventCore, resolveTransition, runSpawnEffects, runTransitionHandler } from "../internal/transition.js";
+import { NoReplyError } from "../errors.js";
 import { emitWithTimestamp } from "../internal/inspection.js";
+import { processEventCore, resolveTransition, runSpawnEffects, runTransitionHandler, shouldPostpone } from "../internal/transition.js";
 import { PersistenceAdapterTag } from "./adapter.js";
-import { ActorSystem, buildActorRefCore, notifyListeners } from "../actor.js";
-import { Cause, Clock, Effect, Exit, Fiber, Option, Queue, Ref, Schedule, Scope, SubscriptionRef } from "effect";
-//#region src-v3/persistence/persistent-actor.ts
+import { ActorSystem, buildActorRefCore, notifyListeners, settlePendingReplies } from "../actor.js";
+import { Cause, Clock, Deferred, Effect, Exit, Fiber, Option, Queue, Ref, Schedule, Scope, SubscriptionRef } from "effect";
+//#region src/persistence/persistent-actor.ts
 /** Get current time in milliseconds using Effect Clock */
 const now = Clock.currentTimeMillis;
 /**
@@ -19,7 +20,7 @@ const replayEvents = Effect.fn("effect-machine.persistentActor.replayEvents")(fu
 	for (const persistedEvent of events) {
 		if (stopVersion !== void 0 && persistedEvent.version > stopVersion) break;
 		const transition = resolveTransition(machine, state, persistedEvent.event);
-		if (transition !== void 0) state = yield* runTransitionHandler(machine, transition, state, persistedEvent.event, self, stubSystem);
+		if (transition !== void 0) state = (yield* runTransitionHandler(machine, transition, state, persistedEvent.event, self, stubSystem, "restore")).newState;
 		version = persistedEvent.version;
 	}
 	return {
@@ -30,7 +31,7 @@ const replayEvents = Effect.fn("effect-machine.persistentActor.replayEvents")(fu
 /**
 * Build PersistentActorRef with all methods
 */
-const buildPersistentActorRef = (id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, listeners, stop, adapter, system, childrenMap) => {
+const buildPersistentActorRef = (id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, listeners, stop, adapter, system, childrenMap, pendingReplies) => {
 	const { machine, persistence } = persistentMachine;
 	const typedMachine = machine;
 	const persist = Effect.gen(function* () {
@@ -44,8 +45,10 @@ const buildPersistentActorRef = (id, persistentMachine, stateRef, versionRef, ev
 	const version = Ref.get(versionRef).pipe(Effect.withSpan("effect-machine.persistentActor.version"));
 	const replayTo = Effect.fn("effect-machine.persistentActor.replayTo")(function* (targetVersion) {
 		if (targetVersion <= (yield* Ref.get(versionRef))) {
+			const dummySend = Effect.fn("effect-machine.persistentActor.replay.send")((_event) => Effect.void);
 			const dummySelf = {
-				send: Effect.fn("effect-machine.persistentActor.replay.send")((_event) => Effect.void),
+				send: dummySend,
+				cast: dummySend,
 				spawn: () => Effect.die("spawn not supported in replay")
 			};
 			const maybeSnapshot = yield* adapter.loadSnapshot(id, persistence.stateSchema);
@@ -70,7 +73,7 @@ const buildPersistentActorRef = (id, persistentMachine, stateRef, versionRef, ev
 		}
 	});
 	return {
-		...buildActorRefCore(id, typedMachine, stateRef, eventQueue, stoppedRef, listeners, stop, system, childrenMap),
+		...buildActorRefCore(id, typedMachine, stateRef, eventQueue, stoppedRef, listeners, stop, system, childrenMap, pendingReplies),
 		persist,
 		version,
 		replayTo
@@ -92,11 +95,16 @@ const createPersistentActor = Effect.fn("effect-machine.persistentActor.spawn")(
 	const eventQueue = yield* Queue.unbounded();
 	const stoppedRef = yield* Ref.make(false);
 	const childrenMap = /* @__PURE__ */ new Map();
+	const selfSend = Effect.fn("effect-machine.persistentActor.self.send")(function* (event) {
+		if (yield* Ref.get(stoppedRef)) return;
+		yield* Queue.offer(eventQueue, {
+			_tag: "send",
+			event
+		});
+	});
 	const self = {
-		send: Effect.fn("effect-machine.persistentActor.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 +153,7 @@ const createPersistentActor = Effect.fn("effect-machine.persistentActor.spawn")(
 	const backgroundFibers = [];
 	const initEvent = { _tag: INTERNAL_INIT_EVENT };
 	const initCtx = {
+		actorId: id,
 		state: resolvedInitial,
 		event: initEvent,
 		self,
@@ -153,6 +162,7 @@ const createPersistentActor = Effect.fn("effect-machine.persistentActor.spawn")(
 	const { effects: effectSlots } = typedMachine._slots;
 	for (const bg of typedMachine.backgroundEffects) {
 		const fiber = yield* Effect.forkDaemon(bg.handler({
+			actorId: id,
 			state: resolvedInitial,
 			event: initEvent,
 			self,
@@ -175,9 +185,10 @@ const createPersistentActor = Effect.fn("effect-machine.persistentActor.spawn")(
 			finalState: resolvedInitial,
 			timestamp
 		}));
-		return buildPersistentActorRef(id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, listeners, Ref.set(stoppedRef, true).pipe(Effect.withSpan("effect-machine.persistentActor.stop"), Effect.asVoid), adapter, system, childrenMap);
+		return buildPersistentActorRef(id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, listeners, Ref.set(stoppedRef, true).pipe(Effect.withSpan("effect-machine.persistentActor.stop"), Effect.asVoid), adapter, system, childrenMap, /* @__PURE__ */ new Set());
 	}
-	const loopFiber = yield* Effect.forkDaemon(persistentEventLoop(id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, self, listeners, adapter, createdAt, stateScopeRef, backgroundFibers, snapshotQueue, snapshotEnabledRef, persistenceQueue, snapshotFiber, persistenceFiber, inspector, system));
+	const pendingReplies = /* @__PURE__ */ new Set();
+	const loopFiber = yield* Effect.forkDaemon(persistentEventLoop(id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, self, listeners, adapter, createdAt, stateScopeRef, backgroundFibers, snapshotQueue, snapshotEnabledRef, persistenceQueue, snapshotFiber, persistenceFiber, inspector, system, pendingReplies));
 	return buildPersistentActorRef(id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, listeners, Effect.gen(function* () {
 		const finalState = yield* SubscriptionRef.get(stateRef);
 		yield* emitWithTimestamp(inspector, (timestamp) => ({
@@ -188,16 +199,17 @@ const createPersistentActor = Effect.fn("effect-machine.persistentActor.spawn")(
 		}));
 		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" });
 		yield* Fiber.interrupt(snapshotFiber);
 		yield* Fiber.interrupt(persistenceFiber);
-	}).pipe(Effect.withSpan("effect-machine.persistentActor.stop"), Effect.asVoid), adapter, system, childrenMap);
+	}).pipe(Effect.withSpan("effect-machine.persistentActor.stop"), Effect.asVoid), adapter, system, childrenMap, pendingReplies);
 });
 /**
 * Main event loop for persistent actor
 */
-const persistentEventLoop = Effect.fn("effect-machine.persistentActor.eventLoop")(function* (id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, self, listeners, adapter, createdAt, stateScopeRef, backgroundFibers, snapshotQueue, snapshotEnabledRef, persistenceQueue, snapshotFiber, persistenceFiber, inspector, system) {
+const persistentEventLoop = Effect.fn("effect-machine.persistentActor.eventLoop")(function* (id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, self, listeners, adapter, createdAt, stateScopeRef, backgroundFibers, snapshotQueue, snapshotEnabledRef, persistenceQueue, snapshotFiber, persistenceFiber, inspector, system, pendingReplies) {
 	const { machine, persistence } = persistentMachine;
 	const typedMachine = machine;
 	const hooks = inspector === void 0 ? void 0 : {
@@ -226,10 +238,28 @@ const persistentEventLoop = Effect.fn("effect-machine.persistentActor.eventLoop"
 			timestamp
 		}))
 	};
+	const postponed = [];
+	const pendingDrain = [];
+	const hasPostponeRules = machine.postponeRules.length > 0;
 	while (true) {
-		const event = yield* Queue.take(eventQueue);
+		const queued = pendingDrain.length > 0 ? pendingDrain.shift() : yield* Queue.take(eventQueue);
+		const event = queued.event;
 		const currentState = yield* SubscriptionRef.get(stateRef);
 		const currentVersion = yield* Ref.get(versionRef);
+		if (hasPostponeRules && shouldPostpone(typedMachine, currentState._tag, event._tag)) {
+			postponed.push(queued);
+			if (queued._tag === "call") yield* Deferred.succeed(queued.reply, {
+				newState: currentState,
+				previousState: currentState,
+				transitioned: false,
+				lifecycleRan: false,
+				isFinal: false,
+				hasReply: false,
+				reply: void 0,
+				postponed: true
+			});
+			continue;
+		}
 		yield* emitWithTimestamp(inspector, (timestamp) => ({
 			type: "@machine.event",
 			actorId: id,
@@ -237,7 +267,13 @@ const persistentEventLoop = Effect.fn("effect-machine.persistentActor.eventLoop"
 			event,
 			timestamp
 		}));
-		const result = yield* processEventCore(typedMachine, currentState, event, self, stateScopeRef, system, hooks);
+		const result = yield* processEventCore(typedMachine, currentState, event, self, stateScopeRef, system, id, hooks);
+		if (queued._tag === "call") yield* Deferred.succeed(queued.reply, result);
+		else if (queued._tag === "ask") if (result.hasReply) yield* Deferred.succeed(queued.reply, result.reply);
+		else yield* Deferred.fail(queued.reply, new NoReplyError({
+			actorId: id,
+			eventTag: event._tag
+		}));
 		if (!result.transitioned) continue;
 		const newVersion = currentVersion + 1;
 		yield* Ref.set(versionRef, newVersion);
@@ -265,12 +301,15 @@ const persistentEventLoop = Effect.fn("effect-machine.persistentActor.eventLoop"
 				timestamp
 			}));
 			yield* Ref.set(stoppedRef, true);
+			postponed.length = 0;
+			yield* settlePendingReplies(pendingReplies, id);
 			yield* Scope.close(stateScopeRef.current, Exit.void);
 			yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
 			yield* Fiber.interrupt(snapshotFiber);
 			yield* Fiber.interrupt(persistenceFiber);
 			return;
 		}
+		if (result.lifecycleRan && postponed.length > 0) pendingDrain.push(...postponed.splice(0));
 	}
 });
 /**
@@ -285,7 +324,7 @@ const runSpawnEffectsWithInspection = Effect.fn("effect-machine.persistentActor.
 		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,

package/{dist-v3 → v3/dist}/persistence/persistent-machine.d.ts

@@ -2,7 +2,7 @@ import { EventBrand, StateBrand } from "../internal/brands.js";
 import { Machine } from "../machine.js";
 import { Schedule, Schema } from "effect";
 
-//#region src-v3/persistence/persistent-machine.d.ts
+//#region src/persistence/persistent-machine.d.ts
 type BrandedState = {
   readonly _tag: string;
 } & StateBrand;

package/{dist-v3 → v3/dist}/persistence/persistent-machine.js

@@ -1,5 +1,5 @@
 import { MissingSchemaError } from "../errors.js";
-//#region src-v3/persistence/persistent-machine.ts
+//#region src/persistence/persistent-machine.ts
 /**
 * Type guard to check if a value is a PersistentMachine
 */

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

@@ -1,7 +1,7 @@
 import { FullEventBrand, FullStateBrand } from "./internal/brands.js";
 import { Schema } from "effect";
 
-//#region src-v3/schema.d.ts
+//#region src/schema.d.ts
 /**
  * Extract the TypeScript type from a TaggedStruct schema
  */

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

@@ -1,6 +1,6 @@
 import { InvalidSchemaError, MissingMatchHandlerError } from "./errors.js";
 import { Schema } from "effect";
-//#region src-v3/schema.ts
+//#region src/schema.ts
 /**
 * Schema-first State/Event definitions for effect-machine.
 *
@@ -58,7 +58,10 @@ const buildMachineSchema = (definition) => {
 			constructor.derive = (source, partial) => {
 				const result = { _tag: tag };
 				for (const key of fieldNames) if (key in source) result[key] = source[key];
-				if (partial !== void 0) for (const [key, value] of Object.entries(partial)) result[key] = value;
+				if (partial !== void 0) for (const [key, value] of Object.entries(partial)) {
+					if (key === "_tag") continue;
+					result[key] = value;
+				}
 				return result;
 			};
 			constructors[tag] = constructor;

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

@@ -1,7 +1,7 @@
 import { ActorSystem } from "./actor.js";
-import { Effect, Schema } from "effect";
+import { Context, Effect, Schema } from "effect";
 
-//#region src-v3/slot.d.ts
+//#region src/slot.d.ts
 /** Schema fields definition (like Schema.Struct.Fields) */
 type Fields = Record<string, Schema.Schema.All>;
 /** Extract the encoded type from schema fields (used for parameters) */
@@ -43,6 +43,7 @@ type EffectSlots<D extends EffectsDef> = { readonly [K in keyof D & string]: Eff
  * Shared across all machines via MachineContextTag.
  */
 interface MachineContext<State, Event, Self> {
+  readonly actorId: string;
   readonly state: State;
   readonly event: Event;
   readonly self: Self;
@@ -53,7 +54,7 @@ interface MachineContext<State, Event, Self> {
  * Single module-level tag instead of per-machine allocation.
  * @internal
  */
-declare const MachineContextTag: any;
+declare const MachineContextTag: Context.Tag<MachineContext<any, any, any>, MachineContext<any, any, any>>;
 /**
  * Guard handler implementation.
  * Receives params and context, returns Effect<boolean>.

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

@@ -1,5 +1,5 @@
 import { Context } from "effect";
-//#region src-v3/slot.ts
+//#region src/slot.ts
 /**
 * Slot module - schema-based, parameterized guards and effects.
 *

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

@@ -1,9 +1,9 @@
+import { EffectsDef, GuardsDef, MachineContext } from "./slot.js";
 import { AssertionError } from "./errors.js";
-import { EffectsDef, GuardsDef } from "./slot.js";
-import { BuiltMachine, Machine } from "./machine.js";
+import { BuiltMachine, Machine, MachineRef } from "./machine.js";
 import { Effect, SubscriptionRef } from "effect";
 
-//#region src-v3/testing.d.ts
+//#region src/testing.d.ts
 /** Accept either Machine or BuiltMachine for testing utilities. */
 type MachineInput<S, E, R, GD extends GuardsDef, EFD extends EffectsDef> = Machine<S, E, R, any, any, GD, EFD> | BuiltMachine<S, E, R>;
 /**
@@ -40,7 +40,7 @@ declare const simulate: <S extends {
 }, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[]) => Effect.Effect<{
   states: S[];
   finalState: S;
-}, never, Exclude<R, unknown>>;
+}, never, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
 /**
  * Assert that a machine can reach a specific state given a sequence of events
  */
@@ -48,7 +48,7 @@ declare const assertReaches: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], expectedTag: string) => Effect.Effect<any, unknown, unknown>;
+}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], expectedTag: string) => Effect.Effect<S, AssertionError, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
 /**
  * Assert that a machine follows a specific path of state tags
  *
@@ -65,7 +65,10 @@ declare const assertPath: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], expectedPath: readonly string[]) => Effect.Effect<any, unknown, unknown>;
+}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], expectedPath: readonly string[]) => Effect.Effect<{
+  states: S[];
+  finalState: S;
+}, AssertionError, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
 /**
  * Assert that a machine never reaches a specific state given a sequence of events
  *
@@ -83,7 +86,10 @@ declare const assertNeverReaches: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], forbiddenTag: string) => Effect.Effect<any, unknown, unknown>;
+}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, events: readonly E[], forbiddenTag: string) => Effect.Effect<{
+  states: S[];
+  finalState: S;
+}, AssertionError, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
 /**
  * Create a controllable test harness for a machine
  */
@@ -129,7 +135,7 @@ declare const createTestHarness: <S extends {
   readonly _tag: string;
 }, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: MachineInput<S, E, R, GD, EFD>, options?: TestHarnessOptions<S, E> | undefined) => Effect.Effect<{
   state: SubscriptionRef.SubscriptionRef<S>;
-  send: (event: E) => Effect.Effect<S, never, never>;
+  send: (event: E) => Effect.Effect<S, never, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
   getState: Effect.Effect<S, never, never>;
 }, never, never>;
 //#endregion