effect-machine 0.8.0 → 0.10.0

package/dist/cluster/entity-machine.js

@@ -2,7 +2,6 @@ import { processEventCore, runSpawnEffects } from "../internal/transition.js";
 import { ActorSystem } from "../actor.js";
 import { Effect, Option, Queue, Ref, Scope } from "effect";
 import { Entity } from "effect/unstable/cluster";
-
 //#region src/cluster/entity-machine.ts
 /**
 * EntityMachine adapter - wires a machine to a cluster Entity layer.
@@ -55,10 +54,12 @@ 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);
@@ -75,6 +76,5 @@ const EntityMachine = { layer: (entity, machine, options) => {
 	});
 	return entity.toLayer(layer());
 } };
-
 //#endregion
-export { EntityMachine };
+export { EntityMachine };

package/dist/cluster/index.js

@@ -1,4 +1,3 @@
 import { EntityMachine } from "./entity-machine.js";
 import { toEntity } from "./to-entity.js";
-
-export { EntityMachine, toEntity };
+export { EntityMachine, toEntity };

package/dist/cluster/to-entity.js

@@ -1,7 +1,6 @@
 import { MissingSchemaError } from "../errors.js";
 import { Entity } from "effect/unstable/cluster";
 import { Rpc } from "effect/unstable/rpc";
-
 //#region src/cluster/to-entity.ts
 /**
 * Generate Entity definition from a machine.
@@ -48,6 +47,5 @@ const toEntity = (machine, options) => {
 		success: stateSchema
 	}), Rpc.make("GetState", { success: stateSchema })]);
 };
-
 //#endregion
-export { toEntity };
+export { toEntity };

package/dist/errors.d.ts

@@ -42,5 +42,16 @@ declare const AssertionError_base: Schema.ErrorClass<AssertionError, Schema.Tagg
 }>, effect_Cause0.YieldableError>;
 /** Assertion failed in testing utilities */
 declare class AssertionError extends AssertionError_base {}
+declare const ActorStoppedError_base: Schema.ErrorClass<ActorStoppedError, Schema.TaggedStruct<"ActorStoppedError", {
+  readonly actorId: Schema.String;
+}>, effect_Cause0.YieldableError>;
+/** Actor was stopped while a call/ask was pending */
+declare class ActorStoppedError extends ActorStoppedError_base {}
+declare const NoReplyError_base: Schema.ErrorClass<NoReplyError, Schema.TaggedStruct<"NoReplyError", {
+  readonly actorId: Schema.String;
+  readonly eventTag: Schema.String;
+}>, effect_Cause0.YieldableError>;
+/** ask() was used but the transition handler did not call reply */
+declare class NoReplyError extends NoReplyError_base {}
 //#endregion
-export { AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError };
+export { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, NoReplyError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError };

package/dist/errors.js

@@ -1,5 +1,4 @@
 import { Schema } from "effect";
-
 //#region src/errors.ts
 /**
 * Typed error classes for effect-machine.
@@ -33,6 +32,12 @@ var ProvisionValidationError = class extends Schema.TaggedErrorClass()("Provisio
 }) {};
 /** Assertion failed in testing utilities */
 var AssertionError = class extends Schema.TaggedErrorClass()("AssertionError", { message: Schema.String }) {};
-
+/** Actor was stopped while a call/ask was pending */
+var ActorStoppedError = class extends Schema.TaggedErrorClass()("ActorStoppedError", { actorId: Schema.String }) {};
+/** ask() was used but the transition handler did not call reply */
+var NoReplyError = class extends Schema.TaggedErrorClass()("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/dist/index.d.ts

@@ -1,13 +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 { AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError } from "./errors.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 "./persistence/index.js";
 import { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, ProvideHandlers, SpawnEffect, StateHandlerContext, TaskOptions, Transition, machine_d_exports } from "./machine.js";
-import { ActorRef, ActorSystem, Default, SystemEvent, SystemEventListener } from "./actor.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 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, type PersistOptions, type PersistedEvent, type PersistenceAdapter, PersistenceAdapterTag, type PersistenceConfig, PersistenceError, type PersistentActorRef, type PersistentMachine, 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 };
+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/dist/index.js

@@ -1,5 +1,5 @@
 import { Inspector, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector } from "./inspection.js";
-import { AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError } from "./errors.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";
@@ -10,5 +10,4 @@ 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 { Default as ActorSystemDefault, ActorSystem as ActorSystemService, AssertionError, DuplicateActorError, Event, InMemoryPersistenceAdapter, Inspector as InspectorService, InvalidSchemaError, machine_exports as Machine, MissingMatchHandlerError, MissingSchemaError, PersistenceAdapterTag, PersistenceError, ProvisionValidationError, Slot, SlotProvisionError, State, UnprovidedSlotsError, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createPersistentActor, createTestHarness, isPersistentMachine, makeInMemoryPersistenceAdapter, makeInspector, makeInspectorEffect, restorePersistentActor, simulate, tracingInspector };
+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/inspection.js

@@ -1,5 +1,4 @@
 import { Effect, Option, ServiceMap } from "effect";
-
 //#region src/inspection.ts
 /**
 * Inspector service tag - optional service for machine introspection
@@ -139,6 +138,5 @@ const consoleInspector = () => makeInspector((event) => {
 const collectingInspector = (events) => ({ onInspect: (event) => {
 	events.push(event);
 } });
-
 //#endregion
-export { Inspector, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector };
+export { Inspector, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector };

package/dist/internal/inspection.js

@@ -1,5 +1,4 @@
 import { Clock, Effect } from "effect";
-
 //#region src/internal/inspection.ts
 /**
 * Emit an inspection event with timestamp from Clock.
@@ -17,6 +16,5 @@ const emitWithTimestamp = Effect.fn("effect-machine.emitWithTimestamp")(function
 	});
 	if (Effect.isEffect(result)) yield* result.pipe(Effect.catchCause(() => Effect.void));
 });
-
 //#endregion
-export { emitWithTimestamp };
+export { emitWithTimestamp };

package/dist/internal/transition.d.ts

@@ -29,7 +29,11 @@ declare const runTransitionHandler: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, transition: Transition<S, E, GD, EFD, R>, state: S, event: E, self: MachineRef<E>, system: ActorSystem, actorId: string) => Effect.Effect<S, never, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
+}, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, transition: Transition<S, E, GD, EFD, R>, state: S, event: E, self: MachineRef<E>, system: ActorSystem, actorId: string) => Effect.Effect<{
+  newState: S;
+  hasReply: boolean;
+  reply: unknown;
+}, never, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
 /**
  * Execute a transition for a given state and event.
  * Handles transition resolution, handler invocation, and guard/effect slot creation.
@@ -49,6 +53,8 @@ declare const executeTransition: <S extends {
   newState: S;
   transitioned: boolean;
   reenter: boolean;
+  hasReply: boolean;
+  reply: unknown;
 }, never, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
 /**
  * Optional hooks for event processing inspection/tracing.
@@ -84,7 +90,22 @@ interface ProcessEventResult<S> {
   readonly lifecycleRan: boolean;
   /** Whether new state is final */
   readonly isFinal: boolean;
+  /** Whether the handler provided a reply (structural, not value-based) */
+  readonly hasReply: boolean;
+  /** Domain reply value from handler (used by ask). Only meaningful when hasReply is true. */
+  readonly reply?: unknown;
+  /** Whether the event was postponed (buffered for retry after next state change) */
+  readonly postponed: boolean;
 }
+/**
+ * Check if an event should be postponed in the current state.
+ * @internal
+ */
+declare const shouldPostpone: <S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}, R>(machine: Machine<S, E, R, any, any, any, any>, stateTag: string, eventTag: string) => boolean;
 /**
  * Process a single event through the machine.
  *
@@ -109,6 +130,9 @@ declare const processEventCore: <S extends {
   transitioned: boolean;
   lifecycleRan: boolean;
   isFinal: boolean;
+  hasReply: boolean;
+  reply: unknown;
+  postponed: boolean;
 }, never, Exclude<R, MachineContext<S, E, MachineRef<E>>> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>>;
 /**
  * Run spawn effects for a state (forked into state scope, auto-cancelled on state exit).
@@ -157,4 +181,4 @@ declare const findSpawnEffects: <S extends {
   readonly _tag: string;
 }, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(machine: Machine<S, E, R, any, any, GD, EFD>, stateTag: string) => ReadonlyArray<SpawnEffect<S, E, EFD, R>>;
 //#endregion
-export { ProcessEventError, ProcessEventHooks, ProcessEventResult, TransitionExecutionResult, executeTransition, findSpawnEffects, findTransitions, invalidateIndex, processEventCore, resolveTransition, runSpawnEffects, runTransitionHandler };
+export { ProcessEventError, ProcessEventHooks, ProcessEventResult, TransitionExecutionResult, executeTransition, findSpawnEffects, findTransitions, invalidateIndex, processEventCore, resolveTransition, runSpawnEffects, runTransitionHandler, shouldPostpone };

package/dist/internal/transition.js

@@ -1,7 +1,6 @@
 import { INTERNAL_ENTER_EVENT, isEffect } from "./utils.js";
 import { BuiltMachine } from "../machine.js";
 import { Cause, Effect, Exit, Scope } from "effect";
-
 //#region src/internal/transition.ts
 /**
 * Transition execution and indexing.
@@ -38,8 +37,18 @@ const runTransitionHandler = Effect.fn("effect-machine.runTransitionHandler")(fu
 		guards,
 		effects
 	};
-	const result = transition.handler(handlerCtx);
-	return isEffect(result) ? yield* result.pipe(Effect.provideService(machine.Context, ctx)) : result;
+	const raw = transition.handler(handlerCtx);
+	const resolved = isEffect(raw) ? yield* raw.pipe(Effect.provideService(machine.Context, ctx)) : raw;
+	if (resolved !== null && typeof resolved === "object" && "state" in resolved && "reply" in resolved && !("_tag" in resolved)) return {
+		newState: resolved.state,
+		hasReply: true,
+		reply: resolved.reply
+	};
+	return {
+		newState: resolved,
+		hasReply: false,
+		reply: void 0
+	};
 });
 /**
 * Execute a transition for a given state and event.
@@ -57,15 +66,28 @@ const executeTransition = Effect.fn("effect-machine.executeTransition")(function
 	if (transition === void 0) return {
 		newState: currentState,
 		transitioned: false,
-		reenter: false
+		reenter: false,
+		hasReply: false,
+		reply: void 0
 	};
+	const { newState, hasReply, reply } = yield* runTransitionHandler(machine, transition, currentState, event, self, system, actorId);
 	return {
-		newState: yield* runTransitionHandler(machine, transition, currentState, event, self, system, actorId),
+		newState,
 		transitioned: true,
-		reenter: transition.reenter === true
+		reenter: transition.reenter === true,
+		hasReply,
+		reply
 	};
 });
 /**
+* Check if an event should be postponed in the current state.
+* @internal
+*/
+const shouldPostpone = (machine, stateTag, eventTag) => {
+	for (const rule of machine.postponeRules) if (rule.stateTag === stateTag && rule.eventTag === eventTag) return true;
+	return false;
+};
+/**
 * Process a single event through the machine.
 *
 * Handles:
@@ -94,7 +116,10 @@ const processEventCore = Effect.fn("effect-machine.processEventCore")(function*
 		previousState: currentState,
 		transitioned: false,
 		lifecycleRan: false,
-		isFinal: false
+		isFinal: false,
+		hasReply: false,
+		reply: void 0,
+		postponed: false
 	};
 	const newState = result.newState;
 	const runLifecycle = newState._tag !== currentState._tag || result.reenter;
@@ -110,7 +135,10 @@ const processEventCore = Effect.fn("effect-machine.processEventCore")(function*
 		previousState: currentState,
 		transitioned: true,
 		lifecycleRan: runLifecycle,
-		isFinal: machine.finalStates.has(newState._tag)
+		isFinal: machine.finalStates.has(newState._tag),
+		hasReply: result.hasReply,
+		reply: result.reply,
+		postponed: false
 	};
 });
 /**
@@ -236,6 +264,5 @@ const findTransitions = (input, stateTag, eventTag) => {
 const findSpawnEffects = (machine, stateTag) => {
 	return getIndex(machine).spawn.get(stateTag) ?? [];
 };
-
 //#endregion
-export { executeTransition, findSpawnEffects, findTransitions, invalidateIndex, processEventCore, resolveTransition, runSpawnEffects, runTransitionHandler };
+export { executeTransition, findSpawnEffects, findTransitions, invalidateIndex, processEventCore, resolveTransition, runSpawnEffects, runTransitionHandler, shouldPostpone };

package/dist/internal/utils.d.ts

@@ -26,7 +26,12 @@ type TaggedConstructor<T extends {
 /**
  * Transition handler result - either a new state or Effect producing one
  */
-type TransitionResult<State, R> = State | Effect.Effect<State, never, R>;
+/** Reply tuple returned from transition handlers for ask support */
+interface TransitionReply<State> {
+  readonly state: State;
+  readonly reply: unknown;
+}
+type TransitionResult<State, R> = State | TransitionReply<State> | Effect.Effect<State | TransitionReply<State>, never, R>;
 /**
  * Internal event tags used for lifecycle effect contexts.
  * Prefixed with $ to distinguish from user events.
@@ -57,4 +62,4 @@ declare const isEffect: (value: unknown) => value is Effect.Effect<unknown, unkn
  */
 declare const stubSystem: ActorSystem;
 //#endregion
-export { ArgsOf, INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, InstanceOf, TagOf, TaggedConstructor, TransitionResult, getTag, isEffect, stubSystem };
+export { ArgsOf, INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, InstanceOf, TagOf, TaggedConstructor, TransitionReply, TransitionResult, getTag, isEffect, stubSystem };

package/dist/internal/utils.js

@@ -1,5 +1,4 @@
 import { Effect, Stream } from "effect";
-
 //#region src/internal/utils.ts
 /**
 * Internal utilities for effect-machine.
@@ -50,6 +49,5 @@ const stubSystem = {
 	restoreMany: () => Effect.die("restoreMany not supported in stub system"),
 	restoreAll: () => Effect.die("restoreAll not supported in stub system")
 };
-
 //#endregion
-export { INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, getTag, isEffect, stubSystem };
+export { INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, getTag, isEffect, stubSystem };

package/dist/machine.d.ts

@@ -5,19 +5,20 @@ import { MachineEventSchema, MachineStateSchema, VariantsUnion } from "./schema.
 import { PersistenceConfig, PersistentMachine } from "./persistence/persistent-machine.js";
 import { DuplicateActorError } from "./errors.js";
 import { findTransitions } from "./internal/transition.js";
-import "./persistence/index.js";
 import { ActorRef, ActorSystem } from "./actor.js";
-import { Cause, Effect, Schedule, Schema, Scope, ServiceMap } from "effect";
+import { Cause, Duration, Effect, Schedule, Schema, Scope, ServiceMap } from "effect";
 
 //#region src/machine.d.ts
 declare namespace machine_d_exports {
-  export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, PersistenceConfig, PersistentMachine, ProvideHandlers, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, Transition, TransitionHandler, findTransitions, make, spawn };
+  export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, PersistenceConfig, PersistentMachine, ProvideHandlers, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, findTransitions, make, spawn };
 }
 /**
  * Self reference for sending events back to the machine
  */
 interface MachineRef<Event> {
   readonly send: (event: Event) => Effect.Effect<void>;
+  /** Fire-and-forget alias for send (OTP gen_server:cast). */
+  readonly cast: (event: Event) => Effect.Effect<void>;
   readonly spawn: <S2 extends {
     readonly _tag: string;
   }, E2 extends {
@@ -87,6 +88,18 @@ interface TaskOptions<State, Event, ED extends EffectsDef, A, E1, ES, EF> {
   readonly onFailure?: (cause: Cause.Cause<E1>, ctx: StateHandlerContext<State, Event, ED>) => EF;
   readonly name?: string;
 }
+/**
+ * Configuration for `.timeout()` — gen_statem-style state timeouts.
+ *
+ * Entering the state starts a timer. Leaving cancels it.
+ * `.reenter()` restarts the timer with fresh state values.
+ */
+interface TimeoutConfig<State, Event> {
+  /** Duration before firing. Static or derived from current state. */
+  readonly duration: Duration.Input | ((state: State) => Duration.Input);
+  /** Event to send when the timer fires. Static or derived from current state. */
+  readonly event: Event | ((state: State) => Event);
+}
 type IsAny<T> = 0 extends 1 & T ? true : false;
 type IsUnknown<T> = unknown extends T ? ([T] extends [unknown] ? true : false) : false;
 type NormalizeR<T> = IsAny<T> extends true ? T : IsUnknown<T> extends true ? never : T;
@@ -153,6 +166,11 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
   /** @internal */
   readonly _finalStates: Set<string>;
   /** @internal */
+  readonly _postponeRules: Array<{
+    readonly stateTag: string;
+    readonly eventTag: string;
+  }>;
+  /** @internal */
   readonly _guardsSchema?: GuardsSchema<GD>;
   /** @internal */
   readonly _effectsSchema?: EffectsSchema<EFD>;
@@ -176,6 +194,10 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
   get spawnEffects(): ReadonlyArray<SpawnEffect<State, Event, EFD, R>>;
   get backgroundEffects(): ReadonlyArray<BackgroundEffect<State, Event, EFD, R>>;
   get finalStates(): ReadonlySet<string>;
+  get postponeRules(): ReadonlyArray<{
+    readonly stateTag: string;
+    readonly eventTag: string;
+  }>;
   get guardsSchema(): GuardsSchema<GD> | undefined;
   get effectsSchema(): EffectsSchema<EFD> | undefined;
   /** @internal */
@@ -231,6 +253,28 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
    * Interrupts do not emit failure events.
    */
   task<NS extends VariantsUnion<_SD> & BrandedState, A, E1, ES extends VariantsUnion<_ED> & BrandedEvent, EF extends VariantsUnion<_ED> & BrandedEvent>(state: TaggedOrConstructor<NS>, run: (ctx: StateHandlerContext<NS, VariantsUnion<_ED> & BrandedEvent, EFD>) => Effect.Effect<A, E1, Scope.Scope>, options: TaskOptions<NS, VariantsUnion<_ED> & BrandedEvent, EFD, A, E1, ES, EF>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  /**
+   * 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<NS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>, config: TimeoutConfig<NS, VariantsUnion<_ED> & BrandedEvent>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
   /**
    * 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.
@@ -252,6 +296,24 @@ declare class Machine<State, Event, R = never, _SD extends Record<string, Schema
    * ```
    */
   background(handler: StateEffectHandler<State, Event, EFD, Scope.Scope>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
+  /**
+   * 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<NS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>, events: TaggedOrConstructor<VariantsUnion<_ED> & BrandedEvent> | ReadonlyArray<TaggedOrConstructor<VariantsUnion<_ED> & BrandedEvent>>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
   final<NS extends VariantsUnion<_SD> & BrandedState>(state: TaggedOrConstructor<NS>): Machine<State, Event, R, _SD, _ED, GD, EFD>;
   /**
    * Finalize the machine. Returns a `BuiltMachine` — the only type accepted by `Machine.spawn`.
@@ -289,4 +351,4 @@ declare const spawn: {
   }, R>(machine: BuiltMachine<S, E, R>, id: string): Effect.Effect<ActorRef<S, E>, never, R>;
 };
 //#endregion
-export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, type PersistenceConfig, type PersistentMachine, ProvideHandlers, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, Transition, TransitionHandler, findTransitions, machine_d_exports, make, spawn };
+export { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, type PersistenceConfig, type PersistentMachine, ProvideHandlers, SlotContext, SpawnEffect, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, Transition, TransitionHandler, findTransitions, machine_d_exports, make, spawn };

package/dist/machine.js

@@ -8,7 +8,6 @@ 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/machine.ts
 var machine_exports = /* @__PURE__ */ __exportAll({
 	BuiltMachine: () => BuiltMachine,
@@ -65,6 +64,7 @@ var Machine = class Machine {
 	/** @internal */ _spawnEffects;
 	/** @internal */ _backgroundEffects;
 	/** @internal */ _finalStates;
+	/** @internal */ _postponeRules;
 	/** @internal */ _guardsSchema;
 	/** @internal */ _effectsSchema;
 	/** @internal */ _guardHandlers;
@@ -89,6 +89,9 @@ var Machine = class Machine {
 	get finalStates() {
 		return this._finalStates;
 	}
+	get postponeRules() {
+		return this._postponeRules;
+	}
 	get guardsSchema() {
 		return this._guardsSchema;
 	}
@@ -102,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();
@@ -260,6 +264,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.
 	*
@@ -283,6 +317,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);
@@ -314,6 +377,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]);
@@ -344,39 +408,11 @@ var TransitionScope = class {
 	}
 };
 const make = Machine.make;
-/**
-* Spawn an actor directly without ActorSystem ceremony.
-* Accepts only `BuiltMachine` (call `.build()` first).
-*
-* **Single actor, no registry.** Caller manages lifetime via `actor.stop`.
-* If a `Scope` exists in context, cleanup attaches automatically on scope close.
-*
-* For registry, lookup by ID, persistence, or multi-actor coordination,
-* use `ActorSystemService` / `system.spawn` instead.
-*
-* @example
-* ```ts
-* // Fire-and-forget — caller manages lifetime
-* const actor = yield* Machine.spawn(machine.build());
-* yield* actor.send(Event.Start);
-* yield* actor.awaitFinal;
-* yield* actor.stop;
-*
-* // Scope-aware — auto-cleans up on scope close
-* yield* Effect.scoped(Effect.gen(function* () {
-*   const actor = yield* Machine.spawn(machine.build());
-*   yield* actor.send(Event.Start);
-*   // actor.stop called automatically when scope closes
-* }));
-* ```
-*/
-const spawnImpl = Effect.fn("effect-machine.spawn")(function* (built, id) {
+const spawn = Effect.fn("effect-machine.spawn")(function* (built, id) {
 	const actor = yield* createActor(id ?? `actor-${Math.random().toString(36).slice(2)}`, built._inner);
 	const maybeScope = yield* Effect.serviceOption(Scope.Scope);
 	if (Option.isSome(maybeScope)) yield* Scope.addFinalizer(maybeScope.value, actor.stop);
 	return actor;
 });
-const spawn = spawnImpl;
-
 //#endregion
-export { BuiltMachine, Machine, findTransitions, machine_exports, make, spawn };
+export { BuiltMachine, Machine, findTransitions, machine_exports, make, spawn };

package/dist/persistence/adapter.js

@@ -1,5 +1,4 @@
 import { Schema, ServiceMap } from "effect";
-
 //#region src/persistence/adapter.ts
 /**
 * Error type for persistence operations
@@ -22,6 +21,5 @@ var VersionConflictError = class extends Schema.TaggedErrorClass()("VersionConfl
 * PersistenceAdapter service tag
 */
 var PersistenceAdapterTag = class extends ServiceMap.Service()("effect-machine/src/persistence/adapter/PersistenceAdapterTag") {};
-
 //#endregion
-export { PersistenceAdapterTag, PersistenceError, VersionConflictError };
+export { PersistenceAdapterTag, PersistenceError, VersionConflictError };