effect-machine 0.3.1 → 0.4.0

package/dist/persistence/adapters/in-memory.js

@@ -0,0 +1,176 @@
+import { PersistenceAdapterTag, PersistenceError, VersionConflictError } from "../adapter.js";
+import { Effect, Layer, Option, Ref, Schema } from "effect";
+
+//#region src/persistence/adapters/in-memory.ts
+/**
+* Create an in-memory persistence adapter.
+* Useful for testing and development.
+*/
+const make = Effect.gen(function* () {
+	const storage = yield* Ref.make(/* @__PURE__ */ new Map());
+	const registry = yield* Ref.make(/* @__PURE__ */ new Map());
+	const getOrCreateStorage = Effect.fn("effect-machine.persistence.inMemory.getOrCreateStorage")(function* (id) {
+		return yield* Ref.modify(storage, (map) => {
+			const existing = map.get(id);
+			if (existing !== void 0) return [existing, map];
+			const newStorage = {
+				snapshot: Option.none(),
+				events: []
+			};
+			const newMap = new Map(map);
+			newMap.set(id, newStorage);
+			return [newStorage, newMap];
+		});
+	});
+	const updateStorage = Effect.fn("effect-machine.persistence.inMemory.updateStorage")(function* (id, update) {
+		yield* Ref.update(storage, (map) => {
+			const existing = map.get(id);
+			if (existing === void 0) return map;
+			const newMap = new Map(map);
+			newMap.set(id, update(existing));
+			return newMap;
+		});
+	});
+	return {
+		saveSnapshot: Effect.fn("effect-machine.persistence.inMemory.saveSnapshot")(function* (id, snapshot, schema) {
+			const actorStorage = yield* getOrCreateStorage(id);
+			if (Option.isSome(actorStorage.snapshot)) {
+				const existingVersion = actorStorage.snapshot.value.version;
+				if (snapshot.version < existingVersion) return yield* new VersionConflictError({
+					actorId: id,
+					expectedVersion: existingVersion,
+					actualVersion: snapshot.version
+				});
+			}
+			const encoded = yield* Schema.encode(schema)(snapshot.state).pipe(Effect.mapError((cause) => new PersistenceError({
+				operation: "saveSnapshot",
+				actorId: id,
+				cause,
+				message: "Failed to encode state"
+			})));
+			yield* updateStorage(id, (s) => ({
+				...s,
+				snapshot: Option.some({
+					data: encoded,
+					version: snapshot.version,
+					timestamp: snapshot.timestamp
+				})
+			}));
+		}),
+		loadSnapshot: Effect.fn("effect-machine.persistence.inMemory.loadSnapshot")(function* (id, schema) {
+			const actorStorage = yield* getOrCreateStorage(id);
+			if (Option.isNone(actorStorage.snapshot)) return Option.none();
+			const stored = actorStorage.snapshot.value;
+			const decoded = yield* Schema.decode(schema)(stored.data).pipe(Effect.mapError((cause) => new PersistenceError({
+				operation: "loadSnapshot",
+				actorId: id,
+				cause,
+				message: "Failed to decode state"
+			})));
+			return Option.some({
+				state: decoded,
+				version: stored.version,
+				timestamp: stored.timestamp
+			});
+		}),
+		appendEvent: Effect.fn("effect-machine.persistence.inMemory.appendEvent")(function* (id, event, schema) {
+			yield* getOrCreateStorage(id);
+			const encoded = yield* Schema.encode(schema)(event.event).pipe(Effect.mapError((cause) => new PersistenceError({
+				operation: "appendEvent",
+				actorId: id,
+				cause,
+				message: "Failed to encode event"
+			})));
+			yield* updateStorage(id, (s) => ({
+				...s,
+				events: [...s.events, {
+					data: encoded,
+					version: event.version,
+					timestamp: event.timestamp
+				}]
+			}));
+		}),
+		loadEvents: Effect.fn("effect-machine.persistence.inMemory.loadEvents")(function* (id, schema, afterVersion) {
+			const actorStorage = yield* getOrCreateStorage(id);
+			const decoded = [];
+			for (const stored of actorStorage.events) {
+				if (afterVersion !== void 0 && stored.version <= afterVersion) continue;
+				const event = yield* Schema.decode(schema)(stored.data).pipe(Effect.mapError((cause) => new PersistenceError({
+					operation: "loadEvents",
+					actorId: id,
+					cause,
+					message: "Failed to decode event"
+				})));
+				decoded.push({
+					event,
+					version: stored.version,
+					timestamp: stored.timestamp
+				});
+			}
+			return decoded;
+		}),
+		deleteActor: Effect.fn("effect-machine.persistence.inMemory.deleteActor")(function* (id) {
+			yield* Ref.update(storage, (map) => {
+				const newMap = new Map(map);
+				newMap.delete(id);
+				return newMap;
+			});
+			yield* Ref.update(registry, (map) => {
+				const newMap = new Map(map);
+				newMap.delete(id);
+				return newMap;
+			});
+		}),
+		listActors: Effect.fn("effect-machine.persistence.inMemory.listActors")(function* () {
+			const map = yield* Ref.get(registry);
+			return Array.from(map.values());
+		}),
+		saveMetadata: Effect.fn("effect-machine.persistence.inMemory.saveMetadata")(function* (metadata) {
+			yield* Ref.update(registry, (map) => {
+				const newMap = new Map(map);
+				newMap.set(metadata.id, metadata);
+				return newMap;
+			});
+		}),
+		deleteMetadata: Effect.fn("effect-machine.persistence.inMemory.deleteMetadata")(function* (id) {
+			yield* Ref.update(registry, (map) => {
+				const newMap = new Map(map);
+				newMap.delete(id);
+				return newMap;
+			});
+		}),
+		loadMetadata: Effect.fn("effect-machine.persistence.inMemory.loadMetadata")(function* (id) {
+			const meta = (yield* Ref.get(registry)).get(id);
+			return meta !== void 0 ? Option.some(meta) : Option.none();
+		})
+	};
+}).pipe(Effect.withSpan("effect-machine.persistence.inMemory.make"));
+/**
+* Create an in-memory persistence adapter effect.
+* Returns the adapter directly for custom layer composition.
+*/
+const makeInMemoryPersistenceAdapter = make;
+/**
+* In-memory persistence adapter layer.
+* Data is not persisted across process restarts.
+*
+* NOTE: Each `Effect.provide(InMemoryPersistenceAdapter)` creates a NEW adapter
+* with empty storage. For tests that need persistent storage across multiple
+* runPromise calls, use `makeInMemoryPersistenceAdapter` with a shared scope.
+*
+* @example
+* ```ts
+* const program = Effect.gen(function* () {
+*   const system = yield* ActorSystemService;
+*   const actor = yield* system.spawn("my-actor", persistentMachine);
+*   // ...
+* }).pipe(
+*   Effect.provide(InMemoryPersistenceAdapter),
+*   Effect.provide(ActorSystemDefault),
+* );
+* ```
+*/
+const InMemoryPersistenceAdapter = Layer.effect(PersistenceAdapterTag, make);
+
+//#endregion
+export { InMemoryPersistenceAdapter, makeInMemoryPersistenceAdapter };

package/dist/persistence/index.d.ts

@@ -0,0 +1,5 @@
+import { PersistenceConfig, PersistentMachine, isPersistentMachine, persist } from "./persistent-machine.js";
+import { PersistentActorRef, createPersistentActor, restorePersistentActor } from "./persistent-actor.js";
+import { ActorMetadata, PersistedEvent, PersistenceAdapter, PersistenceAdapterTag, PersistenceError, RestoreFailure, RestoreResult, Snapshot, VersionConflictError } from "./adapter.js";
+import { InMemoryPersistenceAdapter, makeInMemoryPersistenceAdapter } from "./adapters/in-memory.js";
+export { type ActorMetadata, InMemoryPersistenceAdapter, type PersistedEvent, type PersistenceAdapter, PersistenceAdapterTag, type PersistenceConfig, PersistenceError, type PersistentActorRef, type PersistentMachine, type RestoreFailure, type RestoreResult, type Snapshot, VersionConflictError, createPersistentActor, isPersistentMachine, makeInMemoryPersistenceAdapter, persist, restorePersistentActor };

package/dist/persistence/index.js

@@ -0,0 +1,6 @@
+import { isPersistentMachine, persist } from "./persistent-machine.js";
+import { PersistenceAdapterTag, PersistenceError, VersionConflictError } from "./adapter.js";
+import { createPersistentActor, restorePersistentActor } from "./persistent-actor.js";
+import { InMemoryPersistenceAdapter, makeInMemoryPersistenceAdapter } from "./adapters/in-memory.js";
+
+export { InMemoryPersistenceAdapter, PersistenceAdapterTag, PersistenceError, VersionConflictError, createPersistentActor, isPersistentMachine, makeInMemoryPersistenceAdapter, persist, restorePersistentActor };

package/dist/persistence/persistent-actor.d.ts

@@ -0,0 +1,50 @@
+import { EffectsDef, GuardsDef, MachineContext } from "../slot.js";
+import { PersistentMachine } from "./persistent-machine.js";
+import { PersistedEvent, PersistenceAdapterTag, PersistenceError, Snapshot, VersionConflictError } from "./adapter.js";
+import { MachineRef } from "../machine.js";
+import { ActorRef } from "../actor.js";
+import { Effect, Option, Scope } from "effect";
+
+//#region src/persistence/persistent-actor.d.ts
+/**
+ * Extended ActorRef with persistence capabilities
+ */
+interface PersistentActorRef<S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}, R = never> extends ActorRef<S, E> {
+  /**
+   * Force an immediate snapshot save
+   */
+  readonly persist: Effect.Effect<void, PersistenceError | VersionConflictError>;
+  /**
+   * Get the current persistence version
+   */
+  readonly version: Effect.Effect<number>;
+  /**
+   * Replay events to restore actor to a specific version.
+   * Note: This only computes state; does not re-run transition effects.
+   */
+  readonly replayTo: (version: number) => Effect.Effect<void, PersistenceError, R>;
+}
+/**
+ * Create a persistent actor from a PersistentMachine.
+ * Restores from existing snapshot if available, otherwise starts fresh.
+ */
+declare const createPersistentActor: <S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(id: string, persistentMachine: PersistentMachine<S, E, R>, initialSnapshot: Option.Option<Snapshot<S>>, initialEvents: readonly PersistedEvent<E>[]) => Effect.Effect<PersistentActorRef<S, E, R>, PersistenceError, PersistenceAdapterTag | Exclude<R, MachineContext<S, E, MachineRef<E>>> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>>;
+/**
+ * Restore an actor from persistence.
+ * Returns None if no persisted state exists.
+ */
+declare const restorePersistentActor: <S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}, R>(id: string, persistentMachine: PersistentMachine<S, E, R>) => Effect.Effect<Option.None<PersistentActorRef<S, E, R>> | Option.Some<PersistentActorRef<S, E, R>>, PersistenceError, PersistenceAdapterTag | Exclude<R, MachineContext<S, E, MachineRef<E>>> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>>;
+//#endregion
+export { PersistentActorRef, createPersistentActor, restorePersistentActor };

package/dist/persistence/persistent-actor.js

@@ -0,0 +1,358 @@
+import { Inspector } from "../inspection.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 { 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
+/** Get current time in milliseconds using Effect Clock */
+const now = Clock.currentTimeMillis;
+/**
+* Replay persisted events to compute state.
+* Supports async handlers - used for initial restore.
+* @internal
+*/
+const replayEvents = Effect.fn("effect-machine.persistentActor.replayEvents")(function* (machine, startState, events, self, stopVersion) {
+	let state = startState;
+	let version = 0;
+	for (const persistedEvent of events) {
+		if (stopVersion !== void 0 && persistedEvent.version > stopVersion) break;
+		const transition = resolveTransition(machine, state, persistedEvent.event);
+		if (transition !== void 0) state = yield* runTransitionHandler(machine, transition, state, persistedEvent.event, self, stubSystem);
+		version = persistedEvent.version;
+	}
+	return {
+		state,
+		version
+	};
+});
+/**
+* Build PersistentActorRef with all methods
+*/
+const buildPersistentActorRef = (id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, listeners, stop, adapter, system) => {
+	const { machine, persistence } = persistentMachine;
+	const typedMachine = machine;
+	const persist = Effect.gen(function* () {
+		const snapshot = {
+			state: yield* SubscriptionRef.get(stateRef),
+			version: yield* Ref.get(versionRef),
+			timestamp: yield* now
+		};
+		yield* adapter.saveSnapshot(id, snapshot, persistence.stateSchema);
+	}).pipe(Effect.withSpan("effect-machine.persistentActor.persist"));
+	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 result = yield* replayEvents(typedMachine, snapshot.state, events, dummySelf, targetVersion);
+					yield* SubscriptionRef.set(stateRef, result.state);
+					yield* Ref.set(versionRef, result.version);
+					notifyListeners(listeners, result.state);
+				}
+			} else {
+				const events = yield* adapter.loadEvents(id, persistence.eventSchema);
+				if (events.length > 0) {
+					const result = yield* replayEvents(typedMachine, typedMachine.initial, events, dummySelf, targetVersion);
+					yield* SubscriptionRef.set(stateRef, result.state);
+					yield* Ref.set(versionRef, result.version);
+					notifyListeners(listeners, result.state);
+				}
+			}
+		}
+	});
+	return {
+		...buildActorRefCore(id, typedMachine, stateRef, eventQueue, stoppedRef, listeners, stop, system),
+		persist,
+		version,
+		replayTo
+	};
+};
+/**
+* Create a persistent actor from a PersistentMachine.
+* Restores from existing snapshot if available, otherwise starts fresh.
+*/
+const createPersistentActor = Effect.fn("effect-machine.persistentActor.spawn")(function* (id, persistentMachine, initialSnapshot, initialEvents) {
+	yield* Effect.annotateCurrentSpan("effect_machine.actor.id", id);
+	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);
+		}),
+		spawn: (childId, childMachine) => system.spawn(childId, childMachine).pipe(Effect.provideService(ActorSystem, system))
+	};
+	let resolvedInitial;
+	let initialVersion;
+	if (Option.isSome(initialSnapshot)) {
+		const result = yield* replayEvents(typedMachine, initialSnapshot.value.state, initialEvents, self);
+		resolvedInitial = result.state;
+		initialVersion = initialEvents.length > 0 ? result.version : initialSnapshot.value.version;
+	} else if (initialEvents.length > 0) {
+		const result = yield* replayEvents(typedMachine, typedMachine.initial, initialEvents, self);
+		resolvedInitial = result.state;
+		initialVersion = result.version;
+	} else {
+		resolvedInitial = typedMachine.initial;
+		initialVersion = 0;
+	}
+	yield* Effect.annotateCurrentSpan("effect_machine.actor.initial_state", resolvedInitial._tag);
+	const stateRef = yield* SubscriptionRef.make(resolvedInitial);
+	const versionRef = yield* Ref.make(initialVersion);
+	const listeners = /* @__PURE__ */ new Set();
+	let createdAt;
+	if (Option.isSome(initialSnapshot)) {
+		const existingMeta = adapter.loadMetadata !== void 0 ? yield* adapter.loadMetadata(id) : Option.none();
+		createdAt = Option.isSome(existingMeta) ? existingMeta.value.createdAt : initialSnapshot.value.timestamp;
+	} else createdAt = yield* now;
+	yield* emitWithTimestamp(inspector, (timestamp) => ({
+		type: "@machine.spawn",
+		actorId: id,
+		initialState: resolvedInitial,
+		timestamp
+	}));
+	const snapshotEnabledRef = yield* Ref.make(true);
+	const persistenceQueue = yield* Queue.unbounded();
+	const persistenceFiber = yield* Effect.forkDaemon(persistenceWorker(persistenceQueue));
+	yield* Queue.offer(persistenceQueue, saveMetadata(id, resolvedInitial, initialVersion, createdAt, persistence, adapter));
+	const snapshotQueue = yield* Queue.unbounded();
+	const snapshotFiber = yield* Effect.forkDaemon(snapshotWorker(id, persistence, adapter, snapshotQueue, snapshotEnabledRef));
+	const backgroundFibers = [];
+	const initEvent = { _tag: INTERNAL_INIT_EVENT };
+	const initCtx = {
+		state: resolvedInitial,
+		event: initEvent,
+		self,
+		system
+	};
+	const { effects: effectSlots } = typedMachine._slots;
+	for (const bg of typedMachine.backgroundEffects) {
+		const fiber = yield* Effect.forkDaemon(bg.handler({
+			state: resolvedInitial,
+			event: initEvent,
+			self,
+			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, system);
+	if (typedMachine.finalStates.has(resolvedInitial._tag)) {
+		yield* Scope.close(stateScopeRef.current, Exit.void);
+		yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
+		yield* Fiber.interrupt(snapshotFiber);
+		yield* Fiber.interrupt(persistenceFiber);
+		yield* Ref.set(stoppedRef, true);
+		yield* emitWithTimestamp(inspector, (timestamp) => ({
+			type: "@machine.stop",
+			actorId: id,
+			finalState: resolvedInitial,
+			timestamp
+		}));
+		return buildPersistentActorRef(id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, listeners, Ref.set(stoppedRef, true).pipe(Effect.withSpan("effect-machine.persistentActor.stop"), Effect.asVoid), adapter, system);
+	}
+	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) => ({
+			type: "@machine.stop",
+			actorId: id,
+			finalState,
+			timestamp
+		}));
+		yield* Ref.set(stoppedRef, true);
+		yield* Fiber.interrupt(loopFiber);
+		yield* Scope.close(stateScopeRef.current, Exit.void);
+		yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
+		yield* Fiber.interrupt(snapshotFiber);
+		yield* Fiber.interrupt(persistenceFiber);
+	}).pipe(Effect.withSpan("effect-machine.persistentActor.stop"), Effect.asVoid), adapter, system);
+});
+/**
+* Main event loop for persistent actor
+*/
+const persistentEventLoop = Effect.fn("effect-machine.persistentActor.eventLoop")(function* (id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, self, listeners, adapter, createdAt, stateScopeRef, backgroundFibers, snapshotQueue, snapshotEnabledRef, persistenceQueue, snapshotFiber, persistenceFiber, inspector, system) {
+	const { machine, persistence } = persistentMachine;
+	const typedMachine = machine;
+	const hooks = inspector === void 0 ? void 0 : {
+		onSpawnEffect: (state) => emitWithTimestamp(inspector, (timestamp) => ({
+			type: "@machine.effect",
+			actorId: id,
+			effectType: "spawn",
+			state,
+			timestamp
+		})),
+		onTransition: (from, to, ev) => emitWithTimestamp(inspector, (timestamp) => ({
+			type: "@machine.transition",
+			actorId: id,
+			fromState: from,
+			toState: to,
+			event: ev,
+			timestamp
+		})),
+		onError: (info) => emitWithTimestamp(inspector, (timestamp) => ({
+			type: "@machine.error",
+			actorId: id,
+			phase: info.phase,
+			state: info.state,
+			event: info.event,
+			error: Cause.pretty(info.cause),
+			timestamp
+		}))
+	};
+	while (true) {
+		const event = yield* Queue.take(eventQueue);
+		const currentState = yield* SubscriptionRef.get(stateRef);
+		const currentVersion = yield* Ref.get(versionRef);
+		yield* emitWithTimestamp(inspector, (timestamp) => ({
+			type: "@machine.event",
+			actorId: id,
+			state: currentState,
+			event,
+			timestamp
+		}));
+		const result = yield* processEventCore(typedMachine, currentState, event, self, stateScopeRef, system, hooks);
+		if (!result.transitioned) continue;
+		const newVersion = currentVersion + 1;
+		yield* Ref.set(versionRef, newVersion);
+		yield* SubscriptionRef.set(stateRef, result.newState);
+		notifyListeners(listeners, result.newState);
+		if (persistence.journalEvents) {
+			const persistedEvent = {
+				event,
+				version: newVersion,
+				timestamp: yield* now
+			};
+			const journalTask = adapter.appendEvent(id, persistedEvent, persistence.eventSchema).pipe(Effect.catchAll((e) => Effect.logWarning(`Failed to journal event for actor ${id}`, e)), Effect.asVoid);
+			yield* Queue.offer(persistenceQueue, journalTask);
+		}
+		yield* Queue.offer(persistenceQueue, saveMetadata(id, result.newState, newVersion, createdAt, persistence, adapter));
+		if (yield* Ref.get(snapshotEnabledRef)) yield* Queue.offer(snapshotQueue, {
+			state: result.newState,
+			version: newVersion
+		});
+		if (result.lifecycleRan && result.isFinal) {
+			yield* emitWithTimestamp(inspector, (timestamp) => ({
+				type: "@machine.stop",
+				actorId: id,
+				finalState: result.newState,
+				timestamp
+			}));
+			yield* Ref.set(stoppedRef, true);
+			yield* Scope.close(stateScopeRef.current, Exit.void);
+			yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
+			yield* Fiber.interrupt(snapshotFiber);
+			yield* Fiber.interrupt(persistenceFiber);
+			return;
+		}
+	}
+});
+/**
+* Run spawn effects with inspection and tracing.
+* @internal
+*/
+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,
+		effectType: "spawn",
+		state,
+		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,
+		state: info.state,
+		event: info.event,
+		error: Cause.pretty(info.cause),
+		timestamp
+	})));
+});
+/**
+* Persistence worker (journaling + metadata).
+*/
+const persistenceWorker = Effect.fn("effect-machine.persistentActor.persistenceWorker")(function* (queue) {
+	while (true) yield* yield* Queue.take(queue);
+});
+/**
+* Snapshot scheduler worker (runs in background).
+*/
+const snapshotWorker = Effect.fn("effect-machine.persistentActor.snapshotWorker")(function* (id, persistence, adapter, queue, enabledRef) {
+	const driver = yield* Schedule.driver(persistence.snapshotSchedule);
+	while (true) {
+		const { state, version } = yield* Queue.take(queue);
+		if (!(yield* Ref.get(enabledRef))) continue;
+		if (!(yield* driver.next(state).pipe(Effect.match({
+			onFailure: () => false,
+			onSuccess: () => true
+		})))) {
+			yield* Ref.set(enabledRef, false);
+			continue;
+		}
+		yield* saveSnapshot(id, state, version, persistence, adapter);
+	}
+});
+/**
+* Save a snapshot after state transition.
+* Called by snapshot scheduler.
+*/
+const saveSnapshot = Effect.fn("effect-machine.persistentActor.saveSnapshot")(function* (id, state, version, persistence, adapter) {
+	const snapshot = {
+		state,
+		version,
+		timestamp: yield* now
+	};
+	yield* adapter.saveSnapshot(id, snapshot, persistence.stateSchema).pipe(Effect.catchAll((e) => Effect.logWarning(`Failed to save snapshot for actor ${id}`, e)));
+});
+/**
+* Save or update actor metadata if adapter supports registry.
+* Called on spawn and state transitions.
+*/
+const saveMetadata = Effect.fn("effect-machine.persistentActor.saveMetadata")(function* (id, state, version, createdAt, persistence, adapter) {
+	const save = adapter.saveMetadata;
+	if (save === void 0) return;
+	const lastActivityAt = yield* now;
+	yield* save({
+		id,
+		machineType: persistence.machineType ?? "unknown",
+		createdAt,
+		lastActivityAt,
+		version,
+		stateTag: state._tag
+	}).pipe(Effect.catchAll((e) => Effect.logWarning(`Failed to save metadata for actor ${id}`, e)));
+});
+/**
+* Restore an actor from persistence.
+* Returns None if no persisted state exists.
+*/
+const restorePersistentActor = Effect.fn("effect-machine.persistentActor.restore")(function* (id, persistentMachine) {
+	const adapter = yield* PersistenceAdapterTag;
+	const { persistence } = persistentMachine;
+	const maybeSnapshot = yield* adapter.loadSnapshot(id, persistence.stateSchema);
+	const events = yield* adapter.loadEvents(id, persistence.eventSchema, Option.isSome(maybeSnapshot) ? maybeSnapshot.value.version : void 0);
+	if (Option.isNone(maybeSnapshot) && events.length === 0) return Option.none();
+	const actor = yield* createPersistentActor(id, persistentMachine, maybeSnapshot, events);
+	return Option.some(actor);
+});
+
+//#endregion
+export { createPersistentActor, restorePersistentActor };