effect-machine 0.8.0 → 0.10.0

package/README.md

@@ -74,8 +74,12 @@ const orderMachine = Machine.make({
 const program = Effect.gen(function* () {
   const actor = yield* Machine.spawn(orderMachine);
 
+  // fire-and-forget
   yield* actor.send(OrderEvent.Process);
-  yield* actor.send(OrderEvent.Ship({ trackingId: "TRACK-123" }));
+
+  // request-reply — get ProcessEventResult back
+  const result = yield* actor.call(OrderEvent.Ship({ trackingId: "TRACK-123" }));
+  console.log(result.transitioned); // true
 
   const state = yield* actor.waitFor(OrderState.Shipped);
   console.log(state); // Shipped { orderId: "order-1", trackingId: "TRACK-123" }
@@ -183,6 +187,53 @@ machine.task(State.Loading, ({ effects, state }) => effects.fetchData({ url: sta
 });
 ```
 
+### State Timeouts
+
+`.timeout()` — gen_statem-style state timeouts. Timer starts on state entry, cancels on exit:
+
+```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,
+  });
+```
+
+`.reenter()` restarts the timer with fresh state values.
+
+### Event Postpone
+
+`.postpone()` — gen_statem-style event postpone. When a matching event arrives in the given state, it is buffered. After the next state transition (tag change), buffered events drain in FIFO order:
+
+```ts
+machine
+  .postpone(State.Connecting, Event.Data) // single event
+  .postpone(State.Connecting, [Event.Data, Event.Cmd]); // multiple events
+```
+
+Reply-bearing events (`call`/`ask`) in the postpone buffer are settled with `ActorStoppedError` on stop/interrupt/final-state.
+
+### ask / reply
+
+Handlers can return a domain reply via `{ state, reply }`:
+
+```ts
+.on(State.Active, Event.GetCount, ({ state }) => ({
+  state, // stay in same state
+  reply: state.count, // domain value returned to caller
+}))
+
+// Caller side:
+const count = yield* actor.ask<number>(Event.GetCount);
+```
+
+`ask` fails with `NoReplyError` if the handler doesn't provide a reply, and `ActorStoppedError` if the actor stops while the request is pending.
+
 ### Child Actors
 
 Spawn children from `.spawn()` handlers with `self.spawn`. Children are state-scoped — auto-stopped on state exit:
@@ -253,7 +304,7 @@ See the [primer](./primer/) for comprehensive documentation:
 | ----------- | ----------------------------------------- | ------------------------------ |
 | Overview    | [index.md](./primer/index.md)             | Navigation and quick reference |
 | Basics      | [basics.md](./primer/basics.md)           | Core concepts                  |
-| Handlers    | [handlers.md](./primer/handlers.md)       | Transitions and guards         |
+| Handlers    | [handlers.md](./primer/handlers.md)       | Transitions, guards, reply     |
 | Effects     | [effects.md](./primer/effects.md)         | spawn, background, timeouts    |
 | Testing     | [testing.md](./primer/testing.md)         | simulate, harness, assertions  |
 | Actors      | [actors.md](./primer/actors.md)           | ActorSystem, ActorRef          |
@@ -273,6 +324,8 @@ See the [primer](./primer/) for comprehensive documentation:
 | `.reenter(State.X, Event.Y, handler)`     | Force re-entry on same state                                |
 | `.spawn(State.X, handler)`                | State-scoped effect                                         |
 | `.task(State.X, run, { onSuccess })`      | State-scoped task                                           |
+| `.timeout(State.X, { duration, event })`  | State timeout (gen_statem)                                  |
+| `.postpone(State.X, Event.Y)`             | Postpone event in state (gen_statem)                        |
 | `.background(handler)`                    | Machine-lifetime effect                                     |
 | `.final(State.X)`                         | Mark final state                                            |
 | `.build({ slot: impl })`                  | Provide implementations, returns `BuiltMachine` (terminal)  |
@@ -308,20 +361,27 @@ See the [primer](./primer/) for comprehensive documentation:
 
 ### Actor
 
-| Method                           | Description                        |
-| -------------------------------- | ---------------------------------- |
-| `actor.send(event)`              | Queue event                        |
-| `actor.sendSync(event)`          | Fire-and-forget (sync, for UI)     |
-| `actor.snapshot`                 | Get current state                  |
-| `actor.matches(tag)`             | Check state tag                    |
-| `actor.can(event)`               | Can handle event?                  |
-| `actor.changes`                  | Stream of changes                  |
-| `actor.waitFor(State.X)`         | Wait for state (constructor or fn) |
-| `actor.awaitFinal`               | Wait final state                   |
-| `actor.sendAndWait(ev, State.X)` | Send + wait for state              |
-| `actor.subscribe(fn)`            | Sync callback                      |
-| `actor.system`                   | Access the actor's `ActorSystem`   |
-| `actor.children`                 | Child actors (`ReadonlyMap`)       |
+| Method                           | Description                                 |
+| -------------------------------- | ------------------------------------------- |
+| `actor.send(event)`              | Fire-and-forget (queue event)               |
+| `actor.cast(event)`              | Alias for send (OTP gen_server:cast)        |
+| `actor.call(event)`              | Request-reply, returns `ProcessEventResult` |
+| `actor.ask<R>(event)`            | Typed domain reply from handler             |
+| `actor.snapshot`                 | Get current state                           |
+| `actor.matches(tag)`             | Check state tag                             |
+| `actor.can(event)`               | Can handle event?                           |
+| `actor.changes`                  | Stream of changes                           |
+| `actor.waitFor(State.X)`         | Wait for state (constructor or fn)          |
+| `actor.awaitFinal`               | Wait final state                            |
+| `actor.sendAndWait(ev, State.X)` | Send + wait for state                       |
+| `actor.subscribe(fn)`            | Sync callback                               |
+| `actor.sync.send(event)`         | Sync fire-and-forget (for UI)               |
+| `actor.sync.stop()`              | Sync stop                                   |
+| `actor.sync.snapshot()`          | Sync get state                              |
+| `actor.sync.matches(tag)`        | Sync check state tag                        |
+| `actor.sync.can(event)`          | Sync can handle event?                      |
+| `actor.system`                   | Access the actor's `ActorSystem`            |
+| `actor.children`                 | Child actors (`ReadonlyMap`)                |
 
 ### ActorSystem
 

package/dist/_virtual/_rolldown/runtime.js

@@ -2,17 +2,12 @@
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
 	let target = {};
-	for (var name in all) {
-		__defProp(target, name, {
-			get: all[name],
-			enumerable: true
-		});
-	}
-	if (!no_symbols) {
-		__defProp(target, Symbol.toStringTag, { value: "Module" });
-	}
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
 	return target;
 };
-
 //#endregion
-export { __exportAll };
+export { __exportAll };

package/dist/actor.d.ts

@@ -1,88 +1,85 @@
 import { EffectsDef, GuardsDef, MachineContext } from "./slot.js";
 import { PersistentMachine } from "./persistence/persistent-machine.js";
-import { DuplicateActorError } from "./errors.js";
+import { ActorStoppedError, DuplicateActorError, NoReplyError } from "./errors.js";
 import { ProcessEventError, ProcessEventHooks, ProcessEventResult, processEventCore, resolveTransition, runSpawnEffects } from "./internal/transition.js";
 import { PersistentActorRef } from "./persistence/persistent-actor.js";
 import { ActorMetadata, PersistenceAdapterTag, PersistenceError, RestoreResult, VersionConflictError } from "./persistence/adapter.js";
 import { BuiltMachine, Machine, MachineRef } from "./machine.js";
-import { Effect, Layer, Option, Queue, Ref, Scope, ServiceMap, Stream, SubscriptionRef } from "effect";
+import { Deferred, Effect, Layer, Option, Queue, Ref, Scope, ServiceMap, Stream, SubscriptionRef } from "effect";
 import * as effect_Tracer0 from "effect/Tracer";
 
 //#region src/actor.d.ts
+/** Discriminated mailbox request */
+type QueuedEvent<E> = {
+  readonly _tag: "send";
+  readonly event: E;
+} | {
+  readonly _tag: "call";
+  readonly event: E;
+  readonly reply: Deferred.Deferred<ProcessEventResult<{
+    readonly _tag: string;
+  }>, ActorStoppedError>;
+} | {
+  readonly _tag: "ask";
+  readonly event: E;
+  readonly reply: Deferred.Deferred<unknown, NoReplyError | ActorStoppedError>;
+};
 /**
  * Reference to a running actor.
  */
+/**
+ * Sync projection of ActorRef for non-Effect boundaries (React hooks, framework callbacks).
+ */
+interface ActorRefSync<State extends {
+  readonly _tag: string;
+}, Event> {
+  readonly send: (event: Event) => void;
+  readonly stop: () => void;
+  readonly snapshot: () => State;
+  readonly matches: (tag: State["_tag"]) => boolean;
+  readonly can: (event: Event) => boolean;
+}
 interface ActorRef<State extends {
   readonly _tag: string;
 }, Event> {
-  /**
-   * Unique identifier for this actor
-   */
   readonly id: string;
-  /**
-   * Send an event to the actor
-   */
+  /** Send an event (fire-and-forget). */
   readonly send: (event: Event) => Effect.Effect<void>;
+  /** Fire-and-forget alias for send (OTP gen_server:cast). */
+  readonly cast: (event: Event) => Effect.Effect<void>;
   /**
-   * Observable state of the actor
+   * Serialized request-reply (OTP gen_server:call).
+   * Event is processed through the queue; caller gets ProcessEventResult back.
    */
-  readonly state: SubscriptionRef.SubscriptionRef<State>;
+  readonly call: (event: Event) => Effect.Effect<ProcessEventResult<State>>;
   /**
-   * Stop the actor gracefully
+   * Typed request-reply. Event is processed through the queue; caller gets
+   * the domain value returned by the handler's `reply` field.
+   * Fails with NoReplyError if the handler doesn't provide a reply.
    */
+  readonly ask: <R>(event: Event) => Effect.Effect<R, NoReplyError | ActorStoppedError>;
+  /** Observable state. */
+  readonly state: SubscriptionRef.SubscriptionRef<State>;
+  /** Stop the actor gracefully. */
   readonly stop: Effect.Effect<void>;
-  /**
-   * Stop the actor (fire-and-forget).
-   * Signals graceful shutdown without waiting for completion.
-   * Use when stopping from sync contexts (e.g. framework cleanup hooks).
-   */
-  readonly stopSync: () => void;
-  /**
-   * Get current state snapshot (Effect)
-   */
+  /** Get current state snapshot. */
   readonly snapshot: Effect.Effect<State>;
-  /**
-   * Get current state snapshot (sync)
-   */
-  readonly snapshotSync: () => State;
-  /**
-   * Check if current state matches tag (Effect)
-   */
+  /** Check if current state matches tag. */
   readonly matches: (tag: State["_tag"]) => Effect.Effect<boolean>;
-  /**
-   * Check if current state matches tag (sync)
-   */
-  readonly matchesSync: (tag: State["_tag"]) => boolean;
-  /**
-   * Check if event can be handled in current state (Effect)
-   */
+  /** Check if event can be handled in current state. */
   readonly can: (event: Event) => Effect.Effect<boolean>;
-  /**
-   * Check if event can be handled in current state (sync)
-   */
-  readonly canSync: (event: Event) => boolean;
-  /**
-   * Stream of state changes
-   */
+  /** Stream of state changes. */
   readonly changes: Stream.Stream<State>;
-  /**
-   * Wait for a state that matches predicate or state variant (includes current snapshot).
-   * Accepts a predicate function or a state constructor/value (e.g. `State.Active`).
-   */
+  /** Wait for a state matching predicate or variant (includes current snapshot). */
   readonly waitFor: {
     (predicate: (state: State) => boolean): Effect.Effect<State>;
     (state: {
       readonly _tag: State["_tag"];
     }): Effect.Effect<State>;
   };
-  /**
-   * Wait for a final state (includes current snapshot)
-   */
+  /** Wait for a final state (includes current snapshot). */
   readonly awaitFinal: Effect.Effect<State>;
-  /**
-   * Send event and wait for predicate, state variant, or final state.
-   * Accepts a predicate function or a state constructor/value (e.g. `State.Active`).
-   */
+  /** Send event and wait for predicate, state variant, or final state. */
   readonly sendAndWait: {
     (event: Event, predicate: (state: State) => boolean): Effect.Effect<State>;
     (event: Event, state: {
@@ -90,26 +87,13 @@ interface ActorRef<State extends {
     }): Effect.Effect<State>;
     (event: Event): Effect.Effect<State>;
   };
-  /**
-   * Send event synchronously (fire-and-forget).
-   * No-op on stopped actors. Use when you need to send from sync contexts
-   * (e.g. framework hooks, event handlers).
-   */
-  readonly sendSync: (event: Event) => void;
-  /**
-   * Subscribe to state changes (sync callback)
-   * Returns unsubscribe function
-   */
+  /** Subscribe to state changes (sync callback). Returns unsubscribe function. */
   readonly subscribe: (fn: (state: State) => void) => () => void;
-  /**
-   * The actor system this actor belongs to.
-   * Every actor always has a system — either inherited from context or implicitly created.
-   */
+  /** Sync helpers for non-Effect boundaries. */
+  readonly sync: ActorRefSync<State, Event>;
+  /** The actor system this actor belongs to. */
   readonly system: ActorSystem;
-  /**
-   * Child actors spawned via `self.spawn` in this actor's handlers.
-   * State-scoped children are auto-removed on state exit.
-   */
+  /** Child actors spawned via `self.spawn` in this actor's handlers. */
   readonly children: ReadonlyMap<string, ActorRef<AnyState, unknown>>;
 }
 /** Base type for stored actors (internal) */
@@ -275,7 +259,7 @@ declare const buildActorRefCore: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef, EFD extends EffectsDef>(id: string, machine: Machine<S, E, R, any, any, GD, EFD>, stateRef: SubscriptionRef.SubscriptionRef<S>, eventQueue: Queue.Queue<E>, stoppedRef: Ref.Ref<boolean>, listeners: Listeners<S>, stop: Effect.Effect<void>, system: ActorSystem, childrenMap: ReadonlyMap<string, ActorRef<AnyState, unknown>>) => ActorRef<S, E>;
+}, R, GD extends GuardsDef, EFD extends EffectsDef>(id: string, machine: Machine<S, E, R, any, any, GD, EFD>, stateRef: SubscriptionRef.SubscriptionRef<S>, eventQueue: Queue.Queue<QueuedEvent<E>>, stoppedRef: Ref.Ref<boolean>, listeners: Listeners<S>, stop: Effect.Effect<void>, system: ActorSystem, childrenMap: ReadonlyMap<string, ActorRef<AnyState, unknown>>, pendingReplies: Set<Deferred.Deferred<unknown, unknown>>) => ActorRef<S, E>;
 /**
  * Create and start an actor for a machine
  */
@@ -284,9 +268,11 @@ declare const createActor: <S extends {
 }, E extends {
   readonly _tag: string;
 }, R, GD extends GuardsDef, EFD extends EffectsDef>(id: string, machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>) => Effect.Effect<ActorRef<S, E>, never, Exclude<R, MachineContext<S, E, MachineRef<E>>> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, effect_Tracer0.ParentSpan> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope> | Exclude<Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>, effect_Tracer0.ParentSpan>>;
+/** Fail all pending call/ask Deferreds with ActorStoppedError. Safe to call multiple times. */
+declare const settlePendingReplies: (pendingReplies: Set<Deferred.Deferred<unknown, unknown>>, actorId: string) => Effect.Effect<void, never, never>;
 /**
  * Default ActorSystem layer
  */
 declare const Default: Layer.Layer<ActorSystem, never, never>;
 //#endregion
-export { ActorRef, ActorSystem, Default, Listeners, type ProcessEventError, type ProcessEventHooks, type ProcessEventResult, SystemEvent, SystemEventListener, buildActorRefCore, createActor, notifyListeners, processEventCore, resolveTransition, runSpawnEffects };
+export { ActorRef, ActorRefSync, ActorSystem, Default, Listeners, type ProcessEventError, type ProcessEventHooks, type ProcessEventResult, QueuedEvent, SystemEvent, SystemEventListener, buildActorRefCore, createActor, notifyListeners, processEventCore, resolveTransition, runSpawnEffects, settlePendingReplies };

package/dist/actor.js

@@ -1,13 +1,12 @@
 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 { emitWithTimestamp } from "./internal/inspection.js";
-import { processEventCore, resolveTransition, runSpawnEffects } from "./internal/transition.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, Deferred, Effect, Exit, Fiber, Layer, MutableHashMap, Option, PubSub, Queue, Ref, Scope, Semaphore, ServiceMap, Stream, SubscriptionRef } from "effect";
-
 //#region src/actor.ts
 /**
 * Actor system: spawning, lifecycle, and event processing.
@@ -32,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) {
@@ -71,30 +110,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: SubscriptionRef.changes(stateRef),
 		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
 	};
@@ -117,11 +164,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);
@@ -175,9 +227,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.forkDetach(eventLoop(machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, id, inspectorValue, system));
+	const pendingReplies = /* @__PURE__ */ new Set();
+	const loopFiber = yield* Effect.forkDetach(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) => ({
@@ -188,31 +241,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).
 */
@@ -252,7 +378,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);
@@ -267,10 +396,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.
@@ -454,6 +589,5 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 * Default ActorSystem layer
 */
 const Default = Layer.effect(ActorSystem, make());
-
 //#endregion
-export { ActorSystem, Default, buildActorRefCore, createActor, notifyListeners, processEventCore, resolveTransition, runSpawnEffects };
+export { ActorSystem, Default, buildActorRefCore, createActor, notifyListeners, processEventCore, resolveTransition, runSpawnEffects, settlePendingReplies };

package/dist/cluster/entity-machine.d.ts

@@ -1,7 +1,6 @@
 import { EffectsDef, GuardsDef } from "../slot.js";
 import { ProcessEventHooks } from "../internal/transition.js";
 import { Machine } from "../machine.js";
-import "../actor.js";
 import { Layer } from "effect";
 import { Entity } from "effect/unstable/cluster";
 import { Rpc } from "effect/unstable/rpc";