effect-machine 0.3.2 → 0.6.0

package/README.md

@@ -183,6 +183,53 @@ 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.
+
+### System Observation
+
+React to actors joining and leaving the system:
+
+```ts
+const system = yield * ActorSystemService;
+
+// Sync callback — like ActorRef.subscribe
+const unsub = system.subscribe((event) => {
+  // event._tag: "ActorSpawned" | "ActorStopped"
+  console.log(`${event._tag}: ${event.id}`);
+});
+
+// Sync snapshot of all registered actors
+const actors = system.actors; // ReadonlyMap<string, ActorRef>
+
+// Async stream (each subscriber gets own queue)
+yield *
+  system.events.pipe(
+    Stream.tap((e) => Effect.log(e._tag, e.id)),
+    Stream.runDrain,
+  );
+```
+
 ### Testing
 
 Test transitions without actors:
@@ -273,6 +320,19 @@ 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`   |
+| `actor.children`                 | Child actors (`ReadonlyMap`)       |
+
+### ActorSystem
+
+| Method / Property      | Description                                 |
+| ---------------------- | ------------------------------------------- |
+| `system.spawn(id, m)`  | Spawn actor                                 |
+| `system.get(id)`       | Get actor by ID                             |
+| `system.stop(id)`      | Stop actor by ID                            |
+| `system.actors`        | Sync snapshot of all actors (`ReadonlyMap`) |
+| `system.subscribe(fn)` | Sync callback for spawn/stop events         |
+| `system.events`        | Async `Stream<SystemEvent>` for spawn/stop  |
 
 ## 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,11 +101,37 @@ 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;
+  /**
+   * Child actors spawned via `self.spawn` in this actor's handlers.
+   * State-scoped children are auto-removed on state exit.
+   */
+  readonly children: ReadonlyMap<string, ActorRef<AnyState, unknown>>;
 }
 /** Base type for stored actors (internal) */
 type AnyState = {
   readonly _tag: string;
 };
+/**
+ * Events emitted by the ActorSystem when actors are spawned or stopped.
+ */
+type SystemEvent = {
+  readonly _tag: "ActorSpawned";
+  readonly id: string;
+  readonly actor: ActorRef<AnyState, unknown>;
+} | {
+  readonly _tag: "ActorStopped";
+  readonly id: string;
+  readonly actor: ActorRef<AnyState, unknown>;
+};
+/**
+ * Listener callback for system events.
+ */
+type SystemEventListener = (event: SystemEvent) => void;
 /**
  * Actor system for managing actor lifecycles
  */
@@ -169,6 +195,21 @@ interface ActorSystem {
    * Stop an actor by ID
    */
   readonly stop: (id: string) => Effect.Effect<boolean>;
+  /**
+   * Async stream of system events (actor spawned/stopped).
+   * Each subscriber gets their own queue — late subscribers miss prior events.
+   */
+  readonly events: Stream.Stream<SystemEvent>;
+  /**
+   * Sync snapshot of all currently registered actors.
+   * Returns a new Map on each access (not live).
+   */
+  readonly actors: ReadonlyMap<string, ActorRef<AnyState, unknown>>;
+  /**
+   * Subscribe to system events synchronously.
+   * Returns an unsubscribe function.
+   */
+  readonly subscribe: (fn: SystemEventListener) => () => void;
   /**
    * List all persisted actor metadata.
    * Returns empty array if adapter doesn't support registry.
@@ -234,7 +275,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, childrenMap: ReadonlyMap<string, ActorRef<AnyState, unknown>>) => ActorRef<S, E>;
 /**
  * Create and start an actor for a machine
  */
@@ -248,4 +289,4 @@ declare const createActor: <S extends {
  */
 declare const Default: Layer.Layer<ActorSystem, never, never>;
 //#endregion
-export { ActorRef, ActorSystem, Default, Listeners, type ProcessEventError, type ProcessEventHooks, type ProcessEventResult, buildActorRefCore, createActor, notifyListeners, processEventCore, resolveTransition, runSpawnEffects };
+export { ActorRef, ActorSystem, Default, Listeners, type ProcessEventError, type ProcessEventHooks, type ProcessEventResult, SystemEvent, SystemEventListener, buildActorRefCore, createActor, notifyListeners, processEventCore, resolveTransition, runSpawnEffects };

package/dist/actor.js

@@ -6,10 +6,18 @@ import { processEventCore, resolveTransition, runSpawnEffects } from "./internal
 import { emitWithTimestamp } from "./internal/inspection.js";
 import { PersistenceAdapterTag, PersistenceError } from "./persistence/adapter.js";
 import { createPersistentActor, restorePersistentActor } from "./persistence/persistent-actor.js";
-import { Cause, Context, Deferred, Effect, Exit, Fiber, Layer, MutableHashMap, Option, Queue, Ref, Runtime, Scope, SubscriptionRef } from "effect";
+import { Cause, Context, Deferred, Effect, Exit, Fiber, Layer, MutableHashMap, Option, PubSub, Queue, Ref, Runtime, Scope, Stream, SubscriptionRef } from "effect";
 
 //#region src/actor.ts
 /**
+* Actor system: spawning, lifecycle, and event processing.
+*
+* Combines:
+* - ActorRef interface (running actor handle)
+* - ActorSystem service (spawn/stop/get actors)
+* - Actor creation and event loop
+*/
+/**
 * ActorSystem service tag
 */
 const ActorSystem = Context.GenericTag("@effect/machine/ActorSystem");
@@ -24,7 +32,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, childrenMap) => {
 	const send = Effect.fn("effect-machine.actor.send")(function* (event) {
 		if (yield* Ref.get(stoppedRef)) return;
 		yield* Queue.offer(eventQueue, event);
@@ -88,7 +96,9 @@ const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listen
 			return () => {
 				listeners.delete(fn);
 			};
-		}
+		},
+		system,
+		children: childrenMap
 	};
 };
 /**
@@ -96,13 +106,34 @@ 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 childrenMap = /* @__PURE__ */ new Map();
+	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) => Effect.gen(function* () {
+			const child = yield* system.spawn(childId, childMachine).pipe(Effect.provideService(ActorSystem, system));
+			childrenMap.set(childId, child);
+			const maybeScope = yield* Effect.serviceOption(Scope.Scope);
+			if (Option.isSome(maybeScope)) yield* Scope.addFinalizer(maybeScope.value, Effect.sync(() => {
+				childrenMap.delete(childId);
+			}));
+			return child;
+		})
+	};
 	yield* Effect.annotateCurrentSpan("effect_machine.actor.initial_state", machine.initial._tag);
 	yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
 		type: "@machine.spawn",
@@ -117,7 +148,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 +157,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 +174,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, childrenMap);
 	}
-	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 +190,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, childrenMap);
 });
 /**
 * 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 +204,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 +216,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 +224,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 +277,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 +285,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,
@@ -260,39 +295,58 @@ const runSpawnEffectsWithInspection = Effect.fn("effect-machine.actor.spawnEffec
 		timestamp
 	})));
 });
-/**
-* Internal implementation
-*/
+/** Notify all system event listeners (sync). */
+const notifySystemListeners = (listeners, event) => {
+	for (const listener of listeners) try {
+		listener(event);
+	} catch {}
+};
 const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
-	const actors = MutableHashMap.empty();
+	const actorsMap = MutableHashMap.empty();
 	const withSpawnGate = (yield* Effect.makeSemaphore(1)).withPermits(1);
+	const eventPubSub = yield* PubSub.unbounded();
+	const eventListeners = /* @__PURE__ */ new Set();
+	const emitSystemEvent = (event) => Effect.sync(() => notifySystemListeners(eventListeners, event)).pipe(Effect.andThen(PubSub.publish(eventPubSub, event)), Effect.catchAllCause(() => Effect.void), Effect.asVoid);
 	yield* Effect.addFinalizer(() => {
 		const stops = [];
-		MutableHashMap.forEach(actors, (actor) => {
+		MutableHashMap.forEach(actorsMap, (actor) => {
 			stops.push(actor.stop);
 		});
-		return Effect.all(stops, { concurrency: "unbounded" }).pipe(Effect.asVoid);
+		return Effect.all(stops, { concurrency: "unbounded" }).pipe(Effect.andThen(PubSub.shutdown(eventPubSub)), Effect.asVoid);
 	});
 	/** Check for duplicate ID, register actor, attach scope cleanup if available */
 	const registerActor = Effect.fn("effect-machine.actorSystem.register")(function* (id, actor) {
-		if (MutableHashMap.has(actors, id)) {
+		if (MutableHashMap.has(actorsMap, id)) {
 			yield* actor.stop;
 			return yield* new DuplicateActorError({ actorId: id });
 		}
-		MutableHashMap.set(actors, id, actor);
+		const actorRef = actor;
+		MutableHashMap.set(actorsMap, id, actorRef);
+		yield* emitSystemEvent({
+			_tag: "ActorSpawned",
+			id,
+			actor: actorRef
+		});
 		const maybeScope = yield* Effect.serviceOption(Scope.Scope);
 		if (Option.isSome(maybeScope)) yield* Scope.addFinalizer(maybeScope.value, Effect.gen(function* () {
+			if (MutableHashMap.has(actorsMap, id)) {
+				yield* emitSystemEvent({
+					_tag: "ActorStopped",
+					id,
+					actor: actorRef
+				});
+				MutableHashMap.remove(actorsMap, id);
+			}
 			yield* actor.stop;
-			MutableHashMap.remove(actors, id);
 		}));
 		return actor;
 	});
 	const spawnRegular = Effect.fn("effect-machine.actorSystem.spawnRegular")(function* (id, built) {
-		if (MutableHashMap.has(actors, id)) return yield* new DuplicateActorError({ actorId: id });
+		if (MutableHashMap.has(actorsMap, id)) return yield* new DuplicateActorError({ actorId: id });
 		return yield* registerActor(id, yield* createActor(id, built._inner));
 	});
 	const spawnPersistent = Effect.fn("effect-machine.actorSystem.spawnPersistent")(function* (id, persistentMachine) {
-		if (MutableHashMap.has(actors, id)) return yield* new DuplicateActorError({ actorId: id });
+		if (MutableHashMap.has(actorsMap, id)) return yield* new DuplicateActorError({ actorId: id });
 		const adapter = yield* PersistenceAdapterTag;
 		const maybeSnapshot = yield* adapter.loadSnapshot(id, persistentMachine.persistence.stateSchema);
 		return yield* registerActor(id, yield* createPersistentActor(id, persistentMachine, maybeSnapshot, yield* adapter.loadEvents(id, persistentMachine.persistence.eventSchema, Option.isSome(maybeSnapshot) ? maybeSnapshot.value.version : void 0)));
@@ -311,13 +365,19 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 	});
 	const restore = (id, persistentMachine) => withSpawnGate(restoreImpl(id, persistentMachine));
 	const get = Effect.fn("effect-machine.actorSystem.get")(function* (id) {
-		return yield* Effect.sync(() => MutableHashMap.get(actors, id));
+		return yield* Effect.sync(() => MutableHashMap.get(actorsMap, id));
 	});
 	const stop = Effect.fn("effect-machine.actorSystem.stop")(function* (id) {
-		const maybeActor = MutableHashMap.get(actors, id);
+		const maybeActor = MutableHashMap.get(actorsMap, id);
 		if (Option.isNone(maybeActor)) return false;
-		yield* maybeActor.value.stop;
-		MutableHashMap.remove(actors, id);
+		const actor = maybeActor.value;
+		MutableHashMap.remove(actorsMap, id);
+		yield* emitSystemEvent({
+			_tag: "ActorStopped",
+			id,
+			actor
+		});
+		yield* actor.stop;
 		return true;
 	});
 	const listPersisted = Effect.fn("effect-machine.actorSystem.listPersisted")(function* () {
@@ -329,7 +389,7 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 		const restored = [];
 		const failed = [];
 		for (const id of ids) {
-			if (MutableHashMap.has(actors, id)) continue;
+			if (MutableHashMap.has(actorsMap, id)) continue;
 			const result = yield* Effect.either(restore(id, persistentMachine));
 			if (result._tag === "Left") failed.push({
 				id,
@@ -371,6 +431,20 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 		restore,
 		get,
 		stop,
+		events: Stream.fromPubSub(eventPubSub),
+		get actors() {
+			const snapshot = /* @__PURE__ */ new Map();
+			MutableHashMap.forEach(actorsMap, (actor, id) => {
+				snapshot.set(id, actor);
+			});
+			return snapshot;
+		},
+		subscribe: (fn) => {
+			eventListeners.add(fn);
+			return () => {
+				eventListeners.delete(fn);
+			};
+		},
 		listPersisted,
 		restoreMany,
 		restoreAll

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,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 { 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";
 import { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, ProvideHandlers, SpawnEffect, StateHandlerContext, Transition, machine_d_exports } from "./machine.js";
-import { ActorRef, ActorSystem, Default } from "./actor.js";
+import { ActorRef, 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, SpawnEvent, StopEvent, TransitionEvent, collectingInspector, consoleInspector, makeInspector } 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, 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 TestHarness, type TestHarnessOptions, type Transition, type TransitionEvent, UnprovidedSlotsError, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, consoleInspector, createPersistentActor, createTestHarness, isPersistentMachine, makeInMemoryPersistenceAdapter, makeInspector, restorePersistentActor, simulate };
+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, 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 TestHarness, type TestHarnessOptions, type Transition, type TransitionEvent, UnprovidedSlotsError, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, consoleInspector, createPersistentActor, createTestHarness, isPersistentMachine, makeInMemoryPersistenceAdapter, makeInspector, restorePersistentActor, simulate };

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

@@ -1,4 +1,4 @@
-import { Effect } from "effect";
+import { Effect, Stream } from "effect";
 
 //#region src/internal/utils.ts
 /**
@@ -26,6 +26,26 @@ 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"),
+	events: Stream.empty,
+	get actors() {
+		return /* @__PURE__ */ new Map();
+	},
+	subscribe: () => () => {},
+	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, childrenMap) => {
 	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, childrenMap),
 		persist,
 		version,
 		replayTo
@@ -84,13 +86,28 @@ 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 childrenMap = /* @__PURE__ */ new Map();
+	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) => Effect.gen(function* () {
+			const child = yield* system.spawn(childId, childMachine).pipe(Effect.provideService(ActorSystem, system));
+			childrenMap.set(childId, child);
+			const maybeScope = yield* Effect.serviceOption(Scope.Scope);
+			if (Option.isSome(maybeScope)) yield* Scope.addFinalizer(maybeScope.value, Effect.sync(() => {
+				childrenMap.delete(childId);
+			}));
+			return child;
+		})
+	};
 	let resolvedInitial;
 	let initialVersion;
 	if (Option.isSome(initialSnapshot)) {
@@ -131,7 +148,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 +157,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 +176,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, childrenMap);
 	}
-	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 +193,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, childrenMap);
 });
 /**
 * 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 +238,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 +278,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 +286,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.6.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"
   }
 }