effect-machine 0.3.2 → 0.4.0

package/README.md

@@ -183,6 +183,29 @@ machine.task(State.Loading, ({ effects, state }) => effects.fetchData({ url: sta
 });
 ```
 
+### Child Actors
+
+Spawn children from `.spawn()` handlers with `self.spawn`. Children are state-scoped — auto-stopped on state exit:
+
+```ts
+machine
+  .spawn(State.Active, ({ self }) =>
+    Effect.gen(function* () {
+      const child = yield* self.spawn("worker-1", workerMachine).pipe(Effect.orDie);
+      yield* child.send(WorkerEvent.Start);
+      // child auto-stopped when parent exits Active state
+    }),
+  )
+  .build();
+
+// Access children externally via actor.system
+const parent = yield * Machine.spawn(parentMachine);
+yield * parent.send(Event.Activate);
+const child = yield * parent.system.get("worker-1"); // Option<ActorRef>
+```
+
+Every actor always has a system — `Machine.spawn` creates an implicit one if no `ActorSystem` is in context.
+
 ### Testing
 
 Test transitions without actors:
@@ -273,6 +296,7 @@ See the [primer](./primer/) for comprehensive documentation:
 | `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`   |
 
 ## License
 

package/dist/actor.d.ts

@@ -1,8 +1,8 @@
 import { EffectsDef, GuardsDef, MachineContext } from "./slot.js";
 import { PersistentMachine } from "./persistence/persistent-machine.js";
+import { DuplicateActorError } from "./errors.js";
 import { ProcessEventError, ProcessEventHooks, ProcessEventResult, processEventCore, resolveTransition, runSpawnEffects } from "./internal/transition.js";
 import { PersistentActorRef } from "./persistence/persistent-actor.js";
-import { DuplicateActorError } from "./errors.js";
 import { ActorMetadata, PersistenceAdapterTag, PersistenceError, RestoreResult, VersionConflictError } from "./persistence/adapter.js";
 import { BuiltMachine, Machine, MachineRef } from "./machine.js";
 import { Context, Effect, Layer, Option, Queue, Ref, Scope, Stream, SubscriptionRef } from "effect";
@@ -101,6 +101,11 @@ interface ActorRef<State extends {
    * 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.
+   */
+  readonly system: ActorSystem;
 }
 /** Base type for stored actors (internal) */
 type AnyState = {
@@ -234,7 +239,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>) => 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<E>, stoppedRef: Ref.Ref<boolean>, listeners: Listeners<S>, stop: Effect.Effect<void>, system: ActorSystem) => ActorRef<S, E>;
 /**
  * Create and start an actor for a machine
  */

package/dist/actor.js

@@ -24,7 +24,7 @@ const notifyListeners = (listeners, state) => {
 /**
 * Build core ActorRef methods shared between regular and persistent actors.
 */
-const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listeners, stop) => {
+const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listeners, stop, system) => {
 	const send = Effect.fn("effect-machine.actor.send")(function* (event) {
 		if (yield* Ref.get(stoppedRef)) return;
 		yield* Queue.offer(eventQueue, event);
@@ -88,7 +88,8 @@ const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listen
 			return () => {
 				listeners.delete(fn);
 			};
-		}
+		},
+		system
 	};
 };
 /**
@@ -96,13 +97,25 @@ const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listen
 */
 const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machine) {
 	yield* Effect.annotateCurrentSpan("effect_machine.actor.id", id);
+	const existingSystem = yield* Effect.serviceOption(ActorSystem);
+	let system;
+	let implicitSystemScope;
+	if (Option.isSome(existingSystem)) system = existingSystem.value;
+	else {
+		const scope = yield* Scope.make();
+		system = yield* make().pipe(Effect.provideService(Scope.Scope, scope));
+		implicitSystemScope = scope;
+	}
 	const inspectorValue = Option.getOrUndefined(yield* Effect.serviceOption(Inspector));
 	const eventQueue = yield* Queue.unbounded();
 	const stoppedRef = yield* Ref.make(false);
-	const self = { send: Effect.fn("effect-machine.actor.self.send")(function* (event) {
-		if (yield* Ref.get(stoppedRef)) return;
-		yield* Queue.offer(eventQueue, event);
-	}) };
+	const self = {
+		send: Effect.fn("effect-machine.actor.self.send")(function* (event) {
+			if (yield* Ref.get(stoppedRef)) return;
+			yield* Queue.offer(eventQueue, event);
+		}),
+		spawn: (childId, childMachine) => system.spawn(childId, childMachine).pipe(Effect.provideService(ActorSystem, system))
+	};
 	yield* Effect.annotateCurrentSpan("effect_machine.actor.initial_state", machine.initial._tag);
 	yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
 		type: "@machine.spawn",
@@ -117,7 +130,8 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 	const ctx = {
 		state: machine.initial,
 		event: initEvent,
-		self
+		self,
+		system
 	};
 	const { effects: effectSlots } = machine._slots;
 	for (const bg of machine.backgroundEffects) {
@@ -125,12 +139,13 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 			state: machine.initial,
 			event: initEvent,
 			self,
-			effects: effectSlots
+			effects: effectSlots,
+			system
 		}).pipe(Effect.provideService(machine.Context, ctx)));
 		backgroundFibers.push(fiber);
 	}
 	const stateScopeRef = { current: yield* Scope.make() };
-	yield* runSpawnEffectsWithInspection(machine, machine.initial, initEvent, self, stateScopeRef.current, id, inspectorValue);
+	yield* runSpawnEffectsWithInspection(machine, machine.initial, initEvent, self, stateScopeRef.current, id, inspectorValue, system);
 	if (machine.finalStates.has(machine.initial._tag)) {
 		yield* Scope.close(stateScopeRef.current, Exit.void);
 		yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
@@ -141,9 +156,10 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 			timestamp
 		}));
 		yield* Ref.set(stoppedRef, true);
-		return buildActorRefCore(id, machine, stateRef, eventQueue, stoppedRef, listeners, Ref.set(stoppedRef, true).pipe(Effect.withSpan("effect-machine.actor.stop"), Effect.asVoid));
+		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);
 	}
-	const loopFiber = yield* Effect.forkDaemon(eventLoop(machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, id, inspectorValue));
+	const loopFiber = yield* Effect.forkDaemon(eventLoop(machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, id, inspectorValue, system));
 	return buildActorRefCore(id, machine, stateRef, eventQueue, stoppedRef, listeners, Effect.gen(function* () {
 		const finalState = yield* SubscriptionRef.get(stateRef);
 		yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
@@ -156,12 +172,13 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 		yield* Fiber.interrupt(loopFiber);
 		yield* Scope.close(stateScopeRef.current, Exit.void);
 		yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
-	}).pipe(Effect.withSpan("effect-machine.actor.stop"), Effect.asVoid));
+		if (implicitSystemScope !== void 0) yield* Scope.close(implicitSystemScope, Exit.void);
+	}).pipe(Effect.withSpan("effect-machine.actor.stop"), Effect.asVoid), system);
 });
 /**
 * Main event loop for the actor
 */
-const eventLoop = Effect.fn("effect-machine.actor.eventLoop")(function* (machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, actorId, inspector) {
+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 currentState = yield* SubscriptionRef.get(stateRef);
@@ -169,7 +186,7 @@ const eventLoop = Effect.fn("effect-machine.actor.eventLoop")(function* (machine
 			"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))) {
+		} })(processEvent(machine, currentState, event, stateRef, self, listeners, stateScopeRef, actorId, inspector, system))) {
 			yield* Ref.set(stoppedRef, true);
 			yield* Scope.close(stateScopeRef.current, Exit.void);
 			yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
@@ -181,7 +198,7 @@ const eventLoop = Effect.fn("effect-machine.actor.eventLoop")(function* (machine
 * Process a single event, returning true if the actor should stop.
 * Wraps processEventCore with actor-specific concerns (inspection, listeners, state ref).
 */
-const processEvent = Effect.fn("effect-machine.actor.processEvent")(function* (machine, currentState, event, stateRef, self, listeners, stateScopeRef, actorId, inspector) {
+const processEvent = Effect.fn("effect-machine.actor.processEvent")(function* (machine, currentState, event, stateRef, self, listeners, stateScopeRef, actorId, inspector, system) {
 	yield* emitWithTimestamp(inspector, (timestamp) => ({
 		type: "@machine.event",
 		actorId,
@@ -189,7 +206,7 @@ const processEvent = Effect.fn("effect-machine.actor.processEvent")(function* (m
 		event,
 		timestamp
 	}));
-	const result = yield* processEventCore(machine, currentState, event, self, stateScopeRef, inspector === void 0 ? void 0 : {
+	const result = yield* processEventCore(machine, currentState, event, self, stateScopeRef, system, inspector === void 0 ? void 0 : {
 		onSpawnEffect: (state) => emitWithTimestamp(inspector, (timestamp) => ({
 			type: "@machine.effect",
 			actorId,
@@ -242,7 +259,7 @@ const processEvent = Effect.fn("effect-machine.actor.processEvent")(function* (m
 * Wraps the core runSpawnEffects with inspection events and spans.
 * @internal
 */
-const runSpawnEffectsWithInspection = Effect.fn("effect-machine.actor.spawnEffects")(function* (machine, state, event, self, stateScope, actorId, inspector) {
+const runSpawnEffectsWithInspection = Effect.fn("effect-machine.actor.spawnEffects")(function* (machine, state, event, self, stateScope, actorId, inspector, system) {
 	yield* emitWithTimestamp(inspector, (timestamp) => ({
 		type: "@machine.effect",
 		actorId,
@@ -250,7 +267,7 @@ const runSpawnEffectsWithInspection = Effect.fn("effect-machine.actor.spawnEffec
 		state,
 		timestamp
 	}));
-	yield* runSpawnEffects(machine, state, event, self, stateScope, inspector === void 0 ? void 0 : (info) => emitWithTimestamp(inspector, (timestamp) => ({
+	yield* runSpawnEffects(machine, state, event, self, stateScope, system, inspector === void 0 ? void 0 : (info) => emitWithTimestamp(inspector, (timestamp) => ({
 		type: "@machine.error",
 		actorId,
 		phase: info.phase,

package/dist/cluster/entity-machine.js

@@ -1,6 +1,6 @@
 import { processEventCore, runSpawnEffects } from "../internal/transition.js";
-import "../actor.js";
-import { Effect, Queue, Ref, Scope } from "effect";
+import { ActorSystem } from "../actor.js";
+import { Effect, Option, Queue, Ref, Scope } from "effect";
 import { Entity } from "@effect/cluster";
 
 //#region src/cluster/entity-machine.ts
@@ -13,8 +13,8 @@ import { Entity } from "@effect/cluster";
 * Process a single event through the machine using shared core.
 * Returns the new state after processing.
 */
-const processEvent = Effect.fn("effect-machine.cluster.processEvent")(function* (machine, stateRef, event, self, stateScopeRef, hooks) {
-	const result = yield* processEventCore(machine, yield* Ref.get(stateRef), event, self, stateScopeRef, hooks);
+const processEvent = Effect.fn("effect-machine.cluster.processEvent")(function* (machine, stateRef, event, self, stateScopeRef, system, hooks) {
+	const result = yield* processEventCore(machine, yield* Ref.get(stateRef), event, self, stateScopeRef, system, hooks);
 	if (result.transitioned) yield* Ref.set(stateRef, result.newState);
 	return result.newState;
 });
@@ -51,19 +51,25 @@ const EntityMachine = { layer: (entity, machine, options) => {
 	const layer = Effect.fn("effect-machine.cluster.layer")(function* () {
 		const entityId = yield* Effect.serviceOption(Entity.CurrentAddress).pipe(Effect.map((opt) => opt._tag === "Some" ? opt.value.entityId : ""));
 		const initialState = options?.initializeState !== void 0 ? options.initializeState(entityId) : machine.initial;
+		const existingSystem = yield* Effect.serviceOption(ActorSystem);
+		if (Option.isNone(existingSystem)) return yield* Effect.die("EntityMachine requires ActorSystem in context");
+		const system = existingSystem.value;
 		const internalQueue = yield* Queue.unbounded();
-		const self = { send: 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);
+			}),
+			spawn: (childId, childMachine) => system.spawn(childId, childMachine).pipe(Effect.provideService(ActorSystem, system))
+		};
 		const stateRef = yield* Ref.make(initialState);
 		const stateScopeRef = { current: yield* Scope.make() };
-		yield* runSpawnEffects(machine, initialState, { _tag: "$init" }, self, stateScopeRef.current, options?.hooks?.onError);
+		yield* runSpawnEffects(machine, initialState, { _tag: "$init" }, self, stateScopeRef.current, system, options?.hooks?.onError);
 		const runInternalEvent = Effect.fn("effect-machine.cluster.internalEvent")(function* () {
-			yield* processEvent(machine, stateRef, yield* Queue.take(internalQueue), self, stateScopeRef, options?.hooks);
+			yield* processEvent(machine, stateRef, yield* Queue.take(internalQueue), self, stateScopeRef, system, options?.hooks);
 		});
 		yield* Effect.forkScoped(Effect.forever(runInternalEvent()));
 		return entity.of({
-			Send: (envelope) => processEvent(machine, stateRef, envelope.payload.event, self, stateScopeRef, options?.hooks),
+			Send: (envelope) => processEvent(machine, stateRef, envelope.payload.event, self, stateScopeRef, system, options?.hooks),
 			GetState: () => Ref.get(stateRef)
 		});
 	});

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 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 { PersistentActorRef, createPersistentActor, restorePersistentActor } from "./persistence/persistent-actor.js";
 import { AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError } from "./errors.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";

package/dist/internal/transition.d.ts

@@ -1,5 +1,6 @@
 import { EffectsDef, GuardsDef, MachineContext } from "../slot.js";
 import { BuiltMachine, Machine, MachineRef, SpawnEffect, Transition } from "../machine.js";
+import { ActorSystem } from "../actor.js";
 import { Cause, Effect, Scope } from "effect";
 
 //#region src/internal/transition.d.ts
@@ -28,7 +29,7 @@ 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>) => 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) => Effect.Effect<S, 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.
@@ -44,7 +45,7 @@ declare const executeTransition: <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>, currentState: S, event: E, self: MachineRef<E>) => Effect.Effect<{
+}, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, currentState: S, event: E, self: MachineRef<E>, system: ActorSystem) => Effect.Effect<{
   newState: S;
   transitioned: boolean;
   reenter: boolean;
@@ -102,7 +103,7 @@ declare const processEventCore: <S extends {
   readonly _tag: string;
 }, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, currentState: S, event: E, self: MachineRef<E>, stateScopeRef: {
   current: Scope.CloseableScope;
-}, hooks?: ProcessEventHooks<S, E> | undefined) => Effect.Effect<{
+}, system: ActorSystem, hooks?: ProcessEventHooks<S, E> | undefined) => Effect.Effect<{
   newState: S;
   previousState: S;
   transitioned: boolean;
@@ -118,7 +119,7 @@ declare const runSpawnEffects: <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>, state: S, event: E, self: MachineRef<E>, stateScope: Scope.CloseableScope, onError?: ((info: ProcessEventError<S, E>) => Effect.Effect<void>) | undefined) => Effect.Effect<void, never, Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>>;
+}, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, state: S, event: E, self: MachineRef<E>, stateScope: Scope.CloseableScope, system: ActorSystem, onError?: ((info: ProcessEventError<S, E>) => Effect.Effect<void>) | undefined) => Effect.Effect<void, never, Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>>;
 /**
  * Resolve which transition should fire for a given state and event.
  * Uses indexed O(1) lookup. First matching transition wins.

package/dist/internal/transition.js

@@ -23,11 +23,12 @@ import { Cause, Effect, Exit, Scope } from "effect";
 *
 * @internal
 */
-const runTransitionHandler = Effect.fn("effect-machine.runTransitionHandler")(function* (machine, transition, state, event, self) {
+const runTransitionHandler = Effect.fn("effect-machine.runTransitionHandler")(function* (machine, transition, state, event, self, system) {
 	const ctx = {
 		state,
 		event,
-		self
+		self,
+		system
 	};
 	const { guards, effects } = machine._slots;
 	const handlerCtx = {
@@ -50,7 +51,7 @@ const runTransitionHandler = Effect.fn("effect-machine.runTransitionHandler")(fu
 *
 * @internal
 */
-const executeTransition = Effect.fn("effect-machine.executeTransition")(function* (machine, currentState, event, self) {
+const executeTransition = Effect.fn("effect-machine.executeTransition")(function* (machine, currentState, event, self, system) {
 	const transition = resolveTransition(machine, currentState, event);
 	if (transition === void 0) return {
 		newState: currentState,
@@ -58,7 +59,7 @@ const executeTransition = Effect.fn("effect-machine.executeTransition")(function
 		reenter: false
 	};
 	return {
-		newState: yield* runTransitionHandler(machine, transition, currentState, event, self),
+		newState: yield* runTransitionHandler(machine, transition, currentState, event, self, system),
 		transitioned: true,
 		reenter: transition.reenter === true
 	};
@@ -75,8 +76,8 @@ const executeTransition = Effect.fn("effect-machine.executeTransition")(function
 *
 * @internal
 */
-const processEventCore = Effect.fn("effect-machine.processEventCore")(function* (machine, currentState, event, self, stateScopeRef, hooks) {
-	const result = yield* executeTransition(machine, currentState, event, self).pipe(Effect.catchAllCause((cause) => {
+const processEventCore = Effect.fn("effect-machine.processEventCore")(function* (machine, currentState, event, self, stateScopeRef, system, hooks) {
+	const result = yield* executeTransition(machine, currentState, event, self, system).pipe(Effect.catchAllCause((cause) => {
 		if (Cause.isInterruptedOnly(cause)) return Effect.interrupt;
 		const onError = hooks?.onError;
 		if (onError === void 0) return Effect.failCause(cause).pipe(Effect.orDie);
@@ -101,7 +102,7 @@ const processEventCore = Effect.fn("effect-machine.processEventCore")(function*
 		stateScopeRef.current = yield* Scope.make();
 		if (hooks?.onTransition !== void 0) yield* hooks.onTransition(currentState, newState, event);
 		if (hooks?.onSpawnEffect !== void 0) yield* hooks.onSpawnEffect(newState);
-		yield* runSpawnEffects(machine, newState, { _tag: INTERNAL_ENTER_EVENT }, self, stateScopeRef.current, hooks?.onError);
+		yield* runSpawnEffects(machine, newState, { _tag: INTERNAL_ENTER_EVENT }, self, stateScopeRef.current, system, hooks?.onError);
 	}
 	return {
 		newState,
@@ -116,12 +117,13 @@ const processEventCore = Effect.fn("effect-machine.processEventCore")(function*
 *
 * @internal
 */
-const runSpawnEffects = Effect.fn("effect-machine.runSpawnEffects")(function* (machine, state, event, self, stateScope, onError) {
+const runSpawnEffects = Effect.fn("effect-machine.runSpawnEffects")(function* (machine, state, event, self, stateScope, system, onError) {
 	const spawnEffects = findSpawnEffects(machine, state._tag);
 	const ctx = {
 		state,
 		event,
-		self
+		self,
+		system
 	};
 	const { effects: effectSlots } = machine._slots;
 	const reportError = onError;
@@ -130,7 +132,8 @@ const runSpawnEffects = Effect.fn("effect-machine.runSpawnEffects")(function* (m
 			state,
 			event,
 			self,
-			effects: effectSlots
+			effects: effectSlots,
+			system
 		}).pipe(Effect.provideService(machine.Context, ctx), Effect.catchAllCause((cause) => {
 			if (Cause.isInterruptedOnly(cause)) return Effect.interrupt;
 			if (reportError === void 0) return Effect.failCause(cause).pipe(Effect.orDie);

package/dist/internal/utils.d.ts

@@ -1,3 +1,4 @@
+import { ActorSystem } from "../actor.js";
 import { Effect } from "effect";
 
 //#region src/internal/utils.d.ts
@@ -48,5 +49,12 @@ declare const getTag: (constructorOrValue: {
 })) => string;
 /** Check if a value is an Effect */
 declare const isEffect: (value: unknown) => value is Effect.Effect<unknown, unknown, unknown>;
+/**
+ * Stub ActorSystem that dies on any method call.
+ * Used in contexts where spawning/system access isn't supported
+ * (testing simulation, persistent actor replay).
+ * @internal
+ */
+declare const stubSystem: ActorSystem;
 //#endregion
-export { ArgsOf, INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, InstanceOf, TagOf, TaggedConstructor, TransitionResult, getTag, isEffect };
+export { ArgsOf, INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, InstanceOf, TagOf, TaggedConstructor, TransitionResult, getTag, isEffect, stubSystem };

package/dist/internal/utils.js

@@ -26,6 +26,21 @@ const getTag = (constructorOrValue) => {
 };
 /** Check if a value is an Effect */
 const isEffect = (value) => typeof value === "object" && value !== null && Effect.EffectTypeId in value;
+/**
+* Stub ActorSystem that dies on any method call.
+* Used in contexts where spawning/system access isn't supported
+* (testing simulation, persistent actor replay).
+* @internal
+*/
+const stubSystem = {
+	spawn: () => Effect.die("spawn not supported in stub system"),
+	restore: () => Effect.die("restore not supported in stub system"),
+	get: () => Effect.die("get not supported in stub system"),
+	stop: () => Effect.die("stop not supported in stub system"),
+	listPersisted: () => Effect.die("listPersisted not supported in stub system"),
+	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 };
+export { INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, getTag, isEffect, stubSystem };

package/dist/machine.d.ts

@@ -3,9 +3,10 @@ import { TransitionResult } from "./internal/utils.js";
 import { BrandedEvent, BrandedState, TaggedOrConstructor } from "./internal/brands.js";
 import { MachineEventSchema, MachineStateSchema, VariantsUnion } from "./schema.js";
 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 } from "./actor.js";
+import { ActorRef, ActorSystem } from "./actor.js";
 import { Cause, Context, Effect, Schedule, Schema, Scope } from "effect";
 
 //#region src/machine.d.ts
@@ -17,6 +18,11 @@ declare namespace machine_d_exports {
  */
 interface MachineRef<Event> {
   readonly send: (event: Event) => Effect.Effect<void>;
+  readonly spawn: <S2 extends {
+    readonly _tag: string;
+  }, E2 extends {
+    readonly _tag: string;
+  }, R2>(id: string, machine: BuiltMachine<S2, E2, R2>) => Effect.Effect<ActorRef<S2, E2>, DuplicateActorError, R2>;
 }
 /**
  * Handler context passed to transition handlers
@@ -35,6 +41,7 @@ interface StateHandlerContext<State, Event, ED extends EffectsDef> {
   readonly event: Event;
   readonly self: MachineRef<Event>;
   readonly effects: EffectSlots<ED>;
+  readonly system: ActorSystem;
 }
 /**
  * Transition handler function

package/dist/persistence/adapter.d.ts

@@ -1,5 +1,5 @@
-import { PersistentActorRef } from "./persistent-actor.js";
 import { DuplicateActorError } from "../errors.js";
+import { PersistentActorRef } from "./persistent-actor.js";
 import { Context, Effect, Option, Schema } from "effect";
 
 //#region src/persistence/adapter.d.ts

package/dist/persistence/persistent-actor.js

@@ -1,9 +1,9 @@
 import { Inspector } from "../inspection.js";
-import { INTERNAL_INIT_EVENT } from "../internal/utils.js";
+import { INTERNAL_INIT_EVENT, stubSystem } from "../internal/utils.js";
 import { processEventCore, resolveTransition, runSpawnEffects, runTransitionHandler } from "../internal/transition.js";
 import { emitWithTimestamp } from "../internal/inspection.js";
 import { PersistenceAdapterTag } from "./adapter.js";
-import { buildActorRefCore, notifyListeners } from "../actor.js";
+import { ActorSystem, buildActorRefCore, notifyListeners } from "../actor.js";
 import { Cause, Clock, Effect, Exit, Fiber, Option, Queue, Ref, Schedule, Scope, SubscriptionRef } from "effect";
 
 //#region src/persistence/persistent-actor.ts
@@ -20,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);
+		if (transition !== void 0) state = yield* runTransitionHandler(machine, transition, state, persistedEvent.event, self, stubSystem);
 		version = persistedEvent.version;
 	}
 	return {
@@ -31,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) => {
+const buildPersistentActorRef = (id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, listeners, stop, adapter, system) => {
 	const { machine, persistence } = persistentMachine;
 	const typedMachine = machine;
 	const persist = Effect.gen(function* () {
@@ -45,12 +45,15 @@ 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 dummySelf = {
+				send: Effect.fn("effect-machine.persistentActor.replay.send")((_event) => Effect.void),
+				spawn: () => Effect.die("spawn not supported in replay")
+			};
 			const maybeSnapshot = yield* adapter.loadSnapshot(id, persistence.stateSchema);
 			if (Option.isSome(maybeSnapshot)) {
 				const snapshot = maybeSnapshot.value;
 				if (snapshot.version <= targetVersion) {
 					const events = yield* adapter.loadEvents(id, persistence.eventSchema, snapshot.version);
-					const dummySelf = { send: Effect.fn("effect-machine.persistentActor.replay.send")((_event) => Effect.void) };
 					const result = yield* replayEvents(typedMachine, snapshot.state, events, dummySelf, targetVersion);
 					yield* SubscriptionRef.set(stateRef, result.state);
 					yield* Ref.set(versionRef, result.version);
@@ -59,7 +62,6 @@ const buildPersistentActorRef = (id, persistentMachine, stateRef, versionRef, ev
 			} else {
 				const events = yield* adapter.loadEvents(id, persistence.eventSchema);
 				if (events.length > 0) {
-					const dummySelf = { send: Effect.fn("effect-machine.persistentActor.replay.send")((_event) => Effect.void) };
 					const result = yield* replayEvents(typedMachine, typedMachine.initial, events, dummySelf, targetVersion);
 					yield* SubscriptionRef.set(stateRef, result.state);
 					yield* Ref.set(versionRef, result.version);
@@ -69,7 +71,7 @@ const buildPersistentActorRef = (id, persistentMachine, stateRef, versionRef, ev
 		}
 	});
 	return {
-		...buildActorRefCore(id, typedMachine, stateRef, eventQueue, stoppedRef, listeners, stop),
+		...buildActorRefCore(id, typedMachine, stateRef, eventQueue, stoppedRef, listeners, stop, system),
 		persist,
 		version,
 		replayTo
@@ -84,13 +86,19 @@ const createPersistentActor = Effect.fn("effect-machine.persistentActor.spawn")(
 	const adapter = yield* PersistenceAdapterTag;
 	const { machine, persistence } = persistentMachine;
 	const typedMachine = machine;
+	const existingSystem = yield* Effect.serviceOption(ActorSystem);
+	if (Option.isNone(existingSystem)) return yield* Effect.die("PersistentActor requires ActorSystem in context");
+	const system = existingSystem.value;
 	const inspector = Option.getOrUndefined(yield* Effect.serviceOption(Inspector));
 	const eventQueue = yield* Queue.unbounded();
 	const stoppedRef = yield* Ref.make(false);
-	const self = { send: Effect.fn("effect-machine.persistentActor.self.send")(function* (event) {
-		if (yield* Ref.get(stoppedRef)) return;
-		yield* Queue.offer(eventQueue, event);
-	}) };
+	const self = {
+		send: Effect.fn("effect-machine.persistentActor.self.send")(function* (event) {
+			if (yield* Ref.get(stoppedRef)) return;
+			yield* Queue.offer(eventQueue, event);
+		}),
+		spawn: (childId, childMachine) => system.spawn(childId, childMachine).pipe(Effect.provideService(ActorSystem, system))
+	};
 	let resolvedInitial;
 	let initialVersion;
 	if (Option.isSome(initialSnapshot)) {
@@ -131,7 +139,8 @@ const createPersistentActor = Effect.fn("effect-machine.persistentActor.spawn")(
 	const initCtx = {
 		state: resolvedInitial,
 		event: initEvent,
-		self
+		self,
+		system
 	};
 	const { effects: effectSlots } = typedMachine._slots;
 	for (const bg of typedMachine.backgroundEffects) {
@@ -139,12 +148,13 @@ const createPersistentActor = Effect.fn("effect-machine.persistentActor.spawn")(
 			state: resolvedInitial,
 			event: initEvent,
 			self,
-			effects: effectSlots
+			effects: effectSlots,
+			system
 		}).pipe(Effect.provideService(typedMachine.Context, initCtx)));
 		backgroundFibers.push(fiber);
 	}
 	const stateScopeRef = { current: yield* Scope.make() };
-	yield* runSpawnEffectsWithInspection(typedMachine, resolvedInitial, initEvent, self, stateScopeRef.current, id, inspector);
+	yield* runSpawnEffectsWithInspection(typedMachine, resolvedInitial, initEvent, self, stateScopeRef.current, id, inspector, system);
 	if (typedMachine.finalStates.has(resolvedInitial._tag)) {
 		yield* Scope.close(stateScopeRef.current, Exit.void);
 		yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
@@ -157,9 +167,9 @@ 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);
+		return buildPersistentActorRef(id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, listeners, Ref.set(stoppedRef, true).pipe(Effect.withSpan("effect-machine.persistentActor.stop"), Effect.asVoid), adapter, system);
 	}
-	const loopFiber = yield* Effect.forkDaemon(persistentEventLoop(id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, self, listeners, adapter, createdAt, stateScopeRef, backgroundFibers, snapshotQueue, snapshotEnabledRef, persistenceQueue, snapshotFiber, persistenceFiber, inspector));
+	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));
 	return buildPersistentActorRef(id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, listeners, Effect.gen(function* () {
 		const finalState = yield* SubscriptionRef.get(stateRef);
 		yield* emitWithTimestamp(inspector, (timestamp) => ({
@@ -174,12 +184,12 @@ const createPersistentActor = Effect.fn("effect-machine.persistentActor.spawn")(
 		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);
+	}).pipe(Effect.withSpan("effect-machine.persistentActor.stop"), Effect.asVoid), adapter, system);
 });
 /**
 * 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) {
+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 { machine, persistence } = persistentMachine;
 	const typedMachine = machine;
 	const hooks = inspector === void 0 ? void 0 : {
@@ -219,7 +229,7 @@ const persistentEventLoop = Effect.fn("effect-machine.persistentActor.eventLoop"
 			event,
 			timestamp
 		}));
-		const result = yield* processEventCore(typedMachine, currentState, event, self, stateScopeRef, hooks);
+		const result = yield* processEventCore(typedMachine, currentState, event, self, stateScopeRef, system, hooks);
 		if (!result.transitioned) continue;
 		const newVersion = currentVersion + 1;
 		yield* Ref.set(versionRef, newVersion);
@@ -259,7 +269,7 @@ const persistentEventLoop = Effect.fn("effect-machine.persistentActor.eventLoop"
 * Run spawn effects with inspection and tracing.
 * @internal
 */
-const runSpawnEffectsWithInspection = Effect.fn("effect-machine.persistentActor.spawnEffects")(function* (machine, state, event, self, stateScope, actorId, inspector) {
+const runSpawnEffectsWithInspection = Effect.fn("effect-machine.persistentActor.spawnEffects")(function* (machine, state, event, self, stateScope, actorId, inspector, system) {
 	yield* emitWithTimestamp(inspector, (timestamp) => ({
 		type: "@machine.effect",
 		actorId,
@@ -267,7 +277,7 @@ const runSpawnEffectsWithInspection = Effect.fn("effect-machine.persistentActor.
 		state,
 		timestamp
 	}));
-	yield* runSpawnEffects(machine, state, event, self, stateScope, inspector === void 0 ? void 0 : (info) => emitWithTimestamp(inspector, (timestamp) => ({
+	yield* runSpawnEffects(machine, state, event, self, stateScope, system, inspector === void 0 ? void 0 : (info) => emitWithTimestamp(inspector, (timestamp) => ({
 		type: "@machine.error",
 		actorId,
 		phase: info.phase,

package/dist/slot.d.ts

@@ -1,3 +1,4 @@
+import { ActorSystem } from "./actor.js";
 import { Context, Effect, Schema } from "effect";
 
 //#region src/slot.d.ts
@@ -45,6 +46,7 @@ interface MachineContext<State, Event, Self> {
   readonly state: State;
   readonly event: Event;
   readonly self: Self;
+  readonly system: ActorSystem;
 }
 /**
  * Shared Context tag for all machines.

package/dist/testing.js

@@ -1,3 +1,4 @@
+import { stubSystem } from "./internal/utils.js";
 import { AssertionError } from "./errors.js";
 import { BuiltMachine } from "./machine.js";
 import { executeTransition } from "./internal/transition.js";
@@ -26,11 +27,14 @@ import { Effect, SubscriptionRef } from "effect";
 */
 const simulate = Effect.fn("effect-machine.simulate")(function* (input, events) {
 	const machine = input instanceof BuiltMachine ? input._inner : input;
-	const dummySelf = { send: Effect.fn("effect-machine.testing.simulate.send")((_event) => Effect.void) };
+	const dummySelf = {
+		send: Effect.fn("effect-machine.testing.simulate.send")((_event) => Effect.void),
+		spawn: () => Effect.die("spawn not supported in simulation")
+	};
 	let currentState = machine.initial;
 	const states = [currentState];
 	for (const event of events) {
-		const result = yield* executeTransition(machine, currentState, event, dummySelf);
+		const result = yield* executeTransition(machine, currentState, event, dummySelf, stubSystem);
 		if (!result.transitioned) continue;
 		currentState = result.newState;
 		states.push(currentState);
@@ -110,13 +114,16 @@ const assertNeverReaches = Effect.fn("effect-machine.assertNeverReaches")(functi
 */
 const createTestHarness = Effect.fn("effect-machine.createTestHarness")(function* (input, options) {
 	const machine = input instanceof BuiltMachine ? input._inner : input;
-	const dummySelf = { send: Effect.fn("effect-machine.testing.harness.send")((_event) => Effect.void) };
+	const dummySelf = {
+		send: Effect.fn("effect-machine.testing.harness.send")((_event) => Effect.void),
+		spawn: () => Effect.die("spawn not supported in test harness")
+	};
 	const stateRef = yield* SubscriptionRef.make(machine.initial);
 	return {
 		state: stateRef,
 		send: Effect.fn("effect-machine.testHarness.send")(function* (event) {
 			const currentState = yield* SubscriptionRef.get(stateRef);
-			const result = yield* executeTransition(machine, currentState, event, dummySelf);
+			const result = yield* executeTransition(machine, currentState, event, dummySelf, stubSystem);
 			if (!result.transitioned) return currentState;
 			const newState = result.newState;
 			yield* SubscriptionRef.set(stateRef, newState);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-machine",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/cevr/effect-machine.git"
@@ -41,21 +41,21 @@
     "release": "bun run build && changeset publish"
   },
   "dependencies": {
-    "effect": "^3.19.15"
+    "effect": "^3.19.16"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.5.2",
     "@changesets/cli": "^2.29.8",
-    "@effect/cluster": "^0.56.1",
+    "@effect/cluster": "^0.56.2",
     "@effect/experimental": "^0.58.0",
-    "@effect/language-service": "^0.72.0",
+    "@effect/language-service": "^0.73.0",
     "@effect/rpc": "^0.73.0",
-    "@types/bun": "latest",
+    "@types/bun": "1.3.8",
     "concurrently": "^9.2.1",
     "effect-bun-test": "^0.1.0",
-    "lefthook": "^2.0.15",
-    "oxfmt": "^0.26.0",
-    "oxlint": "^1.41.0",
+    "lefthook": "^2.1.0",
+    "oxfmt": "^0.28.0",
+    "oxlint": "^1.43.0",
     "tsdown": "^0.20.3",
     "typescript": "^5.9.3"
   },
@@ -70,5 +70,8 @@
     "@effect/rpc": {
       "optional": true
     }
+  },
+  "overrides": {
+    "effect": "^3.19.16"
   }
 }