effect-machine 0.10.0 → 0.11.0

package/README.md

@@ -208,7 +208,7 @@ machine
 
 ### Event Postpone
 
-`.postpone()` — gen_statem-style event postpone. When a matching event arrives in the given state, it is buffered. After the next state transition (tag change), buffered events drain in FIFO order:
+`.postpone()` — gen_statem-style event postpone. When a matching event arrives in the given state, it is buffered. After the next state transition (tag change), buffered events drain in FIFO order, looping until stable:
 
 ```ts
 machine
@@ -257,6 +257,31 @@ 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.
 
+### Persistence
+
+Persistence is composed from primitives — no built-in adapter or framework:
+
+```ts
+// Snapshot persistence — observe state changes, save externally
+yield * actor.changes.pipe(Stream.runForEach((state) => saveSnapshot(actor.id, state)));
+
+// Event journal — observe transitions
+yield * actor.transitions.pipe(Stream.runForEach(({ event }) => appendEvent(actor.id, event)));
+
+// Restore from snapshot
+const savedState = yield * loadSnapshot(id);
+const actor = yield * Machine.spawn(machine, { hydrate: savedState });
+
+// Restore from event log
+const events = yield * loadEvents(id);
+const state = yield * Machine.replay(machine, events);
+const actor = yield * Machine.spawn(machine, { hydrate: state });
+
+// Restore from snapshot + tail events
+const state = yield * Machine.replay(machine, tailEvents, { from: snapshot });
+const actor = yield * Machine.spawn(machine, { hydrate: state });
+```
+
 ### System Observation
 
 React to actors joining and leaving the system:
@@ -296,21 +321,6 @@ expect(result.states.map((s) => s._tag)).toEqual(["Idle", "Loading", "Done"]);
 yield * assertPath(machine, events, ["Idle", "Loading", "Done"]);
 ```
 
-## Documentation
-
-See the [primer](./primer/) for comprehensive documentation:
-
-| Topic       | File                                      | Description                    |
-| ----------- | ----------------------------------------- | ------------------------------ |
-| Overview    | [index.md](./primer/index.md)             | Navigation and quick reference |
-| Basics      | [basics.md](./primer/basics.md)           | Core concepts                  |
-| Handlers    | [handlers.md](./primer/handlers.md)       | Transitions, guards, reply     |
-| Effects     | [effects.md](./primer/effects.md)         | spawn, background, timeouts    |
-| Testing     | [testing.md](./primer/testing.md)         | simulate, harness, assertions  |
-| Actors      | [actors.md](./primer/actors.md)           | ActorSystem, ActorRef          |
-| Persistence | [persistence.md](./primer/persistence.md) | Snapshots, event sourcing      |
-| Gotchas     | [gotchas.md](./primer/gotchas.md)         | Common mistakes                |
-
 ## API Quick Reference
 
 ### Building
@@ -330,58 +340,41 @@ See the [primer](./primer/) for comprehensive documentation:
 | `.final(State.X)`                         | Mark final state                                            |
 | `.build({ slot: impl })`                  | Provide implementations, returns `BuiltMachine` (terminal)  |
 | `.build()`                                | Finalize no-slot machine, returns `BuiltMachine` (terminal) |
-| `.persist(config)`                        | Enable persistence                                          |
-
-### State Constructors
-
-| Method                                 | Purpose                        |
-| -------------------------------------- | ------------------------------ |
-| `State.X.derive(source)`               | Pick target fields from source |
-| `State.X.derive(source, { field: v })` | Pick fields + apply overrides  |
-| `State.$is("X")(value)`                | Type guard                     |
-| `State.$match(value, { X: fn, ... })`  | Pattern matching               |
 
 ### Running
 
-| Method                       | Purpose                                                                                                 |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------- |
-| `Machine.spawn(machine)`     | Single actor, no registry. Caller manages lifetime via `actor.stop`. Auto-cleans up if `Scope` present. |
-| `Machine.spawn(machine, id)` | Same as above with custom ID                                                                            |
-| `system.spawn(id, machine)`  | Registry, lookup by ID, bulk ops, persistence. Cleans up on system teardown.                            |
-
-### Testing
-
-| Function                                   | Description                                                      |
-| ------------------------------------------ | ---------------------------------------------------------------- |
-| `simulate(machine, events)`                | Run events, get all states (accepts `Machine` or `BuiltMachine`) |
-| `createTestHarness(machine)`               | Step-by-step testing (accepts `Machine` or `BuiltMachine`)       |
-| `assertPath(machine, events, path)`        | Assert exact path                                                |
-| `assertReaches(machine, events, tag)`      | Assert final state                                               |
-| `assertNeverReaches(machine, events, tag)` | Assert state never visited                                       |
+| Method                                   | Purpose                                                                                                 |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `Machine.spawn(machine)`                 | Single actor, no registry. Caller manages lifetime via `actor.stop`. Auto-cleans up if `Scope` present. |
+| `Machine.spawn(machine, id)`             | Same as above with custom ID                                                                            |
+| `Machine.spawn(machine, { hydrate: s })` | Restore from saved state — re-runs spawn effects for that state                                         |
+| `Machine.replay(machine, events)`        | Fold events through handlers to compute state (for event sourcing restore)                              |
+| `system.spawn(id, machine)`              | Registry, lookup by ID, bulk ops. Cleans up on system teardown.                                         |
 
 ### Actor
 
-| Method                           | Description                                 |
-| -------------------------------- | ------------------------------------------- |
-| `actor.send(event)`              | Fire-and-forget (queue event)               |
-| `actor.cast(event)`              | Alias for send (OTP gen_server:cast)        |
-| `actor.call(event)`              | Request-reply, returns `ProcessEventResult` |
-| `actor.ask<R>(event)`            | Typed domain reply from handler             |
-| `actor.snapshot`                 | Get current state                           |
-| `actor.matches(tag)`             | Check state tag                             |
-| `actor.can(event)`               | Can handle event?                           |
-| `actor.changes`                  | Stream of changes                           |
-| `actor.waitFor(State.X)`         | Wait for state (constructor or fn)          |
-| `actor.awaitFinal`               | Wait final state                            |
-| `actor.sendAndWait(ev, State.X)` | Send + wait for state                       |
-| `actor.subscribe(fn)`            | Sync callback                               |
-| `actor.sync.send(event)`         | Sync fire-and-forget (for UI)               |
-| `actor.sync.stop()`              | Sync stop                                   |
-| `actor.sync.snapshot()`          | Sync get state                              |
-| `actor.sync.matches(tag)`        | Sync check state tag                        |
-| `actor.sync.can(event)`          | Sync can handle event?                      |
-| `actor.system`                   | Access the actor's `ActorSystem`            |
-| `actor.children`                 | Child actors (`ReadonlyMap`)                |
+| Method                           | Description                                     |
+| -------------------------------- | ----------------------------------------------- |
+| `actor.send(event)`              | Fire-and-forget (queue event)                   |
+| `actor.cast(event)`              | Alias for send (OTP gen_server:cast)            |
+| `actor.call(event)`              | Request-reply, returns `ProcessEventResult`     |
+| `actor.ask<R>(event)`            | Typed domain reply from handler                 |
+| `actor.snapshot`                 | Get current state                               |
+| `actor.matches(tag)`             | Check state tag                                 |
+| `actor.can(event)`               | Can handle event?                               |
+| `actor.changes`                  | Stream of state changes                         |
+| `actor.transitions`              | Stream of `{ fromState, toState, event }` edges |
+| `actor.waitFor(State.X)`         | Wait for state (constructor or fn)              |
+| `actor.awaitFinal`               | Wait final state                                |
+| `actor.sendAndWait(ev, State.X)` | Send + wait for state                           |
+| `actor.subscribe(fn)`            | Sync callback                                   |
+| `actor.sync.send(event)`         | Sync fire-and-forget (for UI)                   |
+| `actor.sync.stop()`              | Sync stop                                       |
+| `actor.sync.snapshot()`          | Sync get state                                  |
+| `actor.sync.matches(tag)`        | Sync check state tag                            |
+| `actor.sync.can(event)`          | Sync can handle event?                          |
+| `actor.system`                   | Access the actor's `ActorSystem`                |
+| `actor.children`                 | Child actors (`ReadonlyMap`)                    |
 
 ### ActorSystem
 
@@ -394,6 +387,16 @@ See the [primer](./primer/) for comprehensive documentation:
 | `system.subscribe(fn)` | Sync callback for spawn/stop events         |
 | `system.events`        | Async `Stream<SystemEvent>` for spawn/stop  |
 
+### Testing
+
+| Function                                   | Description                                                      |
+| ------------------------------------------ | ---------------------------------------------------------------- |
+| `simulate(machine, events)`                | Run events, get all states (accepts `Machine` or `BuiltMachine`) |
+| `createTestHarness(machine)`               | Step-by-step testing (accepts `Machine` or `BuiltMachine`)       |
+| `assertPath(machine, events, path)`        | Assert exact path                                                |
+| `assertReaches(machine, events, tag)`      | Assert final state                                               |
+| `assertNeverReaches(machine, events, tag)` | Assert state never visited                                       |
+
 ## License
 
 MIT

package/dist/actor.d.ts

@@ -1,11 +1,8 @@
 import { EffectsDef, GuardsDef, MachineContext } from "./slot.js";
-import { PersistentMachine } from "./persistence/persistent-machine.js";
 import { ActorStoppedError, DuplicateActorError, NoReplyError } from "./errors.js";
 import { ProcessEventError, ProcessEventHooks, ProcessEventResult, processEventCore, resolveTransition, runSpawnEffects } from "./internal/transition.js";
-import { PersistentActorRef } from "./persistence/persistent-actor.js";
-import { ActorMetadata, PersistenceAdapterTag, PersistenceError, RestoreResult, VersionConflictError } from "./persistence/adapter.js";
 import { BuiltMachine, Machine, MachineRef } from "./machine.js";
-import { Deferred, Effect, Layer, Option, Queue, Ref, Scope, ServiceMap, Stream, SubscriptionRef } from "effect";
+import { Deferred, Effect, Layer, Option, PubSub, Queue, Ref, Scope, ServiceMap, Stream, SubscriptionRef } from "effect";
 import * as effect_Tracer0 from "effect/Tracer";
 
 //#region src/actor.d.ts
@@ -39,6 +36,15 @@ interface ActorRefSync<State extends {
   readonly matches: (tag: State["_tag"]) => boolean;
   readonly can: (event: Event) => boolean;
 }
+/**
+ * Information about a successful transition.
+ * Emitted on the `transitions` stream after each accepted event.
+ */
+interface TransitionInfo<State, Event> {
+  readonly fromState: State;
+  readonly toState: State;
+  readonly event: Event;
+}
 interface ActorRef<State extends {
   readonly _tag: string;
 }, Event> {
@@ -70,6 +76,14 @@ interface ActorRef<State extends {
   readonly can: (event: Event) => Effect.Effect<boolean>;
   /** Stream of state changes. */
   readonly changes: Stream.Stream<State>;
+  /**
+   * Stream of accepted transitions (edge stream).
+   *
+   * Emits `{ fromState, toState, event }` on every successful transition,
+   * including same-state reenters. PubSub-backed — late subscribers miss
+   * past edges. This is observational, not a durability guarantee.
+   */
+  readonly transitions: Stream.Stream<TransitionInfo<State, Event>>;
   /** Wait for a state matching predicate or variant (includes current snapshot). */
   readonly waitFor: {
     (predicate: (state: State) => boolean): Effect.Effect<State>;
@@ -123,54 +137,17 @@ interface ActorSystem {
   /**
    * Spawn a new actor with the given machine.
    *
-   * For regular machines, returns ActorRef.
-   * For persistent machines (created with Machine.persist), returns PersistentActorRef.
-   *
-   * All effect slots must be provided via `.build()` before spawning.
-   *
    * @example
    * ```ts
-   * // Regular machine (built)
    * const built = machine.build({ fetchData: ... })
    * const actor = yield* system.spawn("my-actor", built);
-   *
-   * // Persistent machine (auto-detected)
-   * const persistentActor = yield* system.spawn("my-actor", persistentMachine);
-   * persistentActor.persist; // available
-   * persistentActor.version; // available
-   * ```
-   */
-  readonly spawn: {
-    <S extends {
-      readonly _tag: string;
-    }, E extends {
-      readonly _tag: string;
-    }, R>(id: string, machine: BuiltMachine<S, E, R>): Effect.Effect<ActorRef<S, E>, DuplicateActorError, R>;
-    <S extends {
-      readonly _tag: string;
-    }, E extends {
-      readonly _tag: string;
-    }, R>(id: string, machine: PersistentMachine<S, E, R>): Effect.Effect<PersistentActorRef<S, E, R>, PersistenceError | VersionConflictError | DuplicateActorError, R | PersistenceAdapterTag>;
-  };
-  /**
-   * Restore an actor from persistence.
-   * Returns None if no persisted state exists for the given ID.
-   *
-   * @example
-   * ```ts
-   * const maybeActor = yield* system.restore("order-1", persistentMachine);
-   * if (Option.isSome(maybeActor)) {
-   *   const actor = maybeActor.value;
-   *   const state = yield* actor.snapshot;
-   *   console.log(`Restored to state: ${state._tag}`);
-   * }
    * ```
    */
-  readonly restore: <S extends {
+  readonly spawn: <S extends {
     readonly _tag: string;
   }, E extends {
     readonly _tag: string;
-  }, R>(id: string, machine: PersistentMachine<S, E, R>) => Effect.Effect<Option.Option<PersistentActorRef<S, E, R>>, PersistenceError | DuplicateActorError, R | PersistenceAdapterTag>;
+  }, R>(id: string, machine: BuiltMachine<S, E, R>) => Effect.Effect<ActorRef<S, E>, DuplicateActorError, R>;
   /**
    * Get an existing actor by ID
    */
@@ -194,53 +171,6 @@ interface ActorSystem {
    * Returns an unsubscribe function.
    */
   readonly subscribe: (fn: SystemEventListener) => () => void;
-  /**
-   * List all persisted actor metadata.
-   * Returns empty array if adapter doesn't support registry.
-   *
-   * @example
-   * ```ts
-   * const actors = yield* system.listPersisted();
-   * for (const meta of actors) {
-   *   console.log(`${meta.id}: ${meta.stateTag} (v${meta.version})`);
-   * }
-   * ```
-   */
-  readonly listPersisted: () => Effect.Effect<ReadonlyArray<ActorMetadata>, PersistenceError, PersistenceAdapterTag>;
-  /**
-   * Restore multiple actors by ID.
-   * Returns both successfully restored actors and failures.
-   *
-   * @example
-   * ```ts
-   * const result = yield* system.restoreMany(["order-1", "order-2"], orderMachine);
-   * console.log(`Restored: ${result.restored.length}, Failed: ${result.failed.length}`);
-   * ```
-   */
-  readonly restoreMany: <S extends {
-    readonly _tag: string;
-  }, E extends {
-    readonly _tag: string;
-  }, R>(ids: ReadonlyArray<string>, machine: PersistentMachine<S, E, R>) => Effect.Effect<RestoreResult<S, E, R>, never, R | PersistenceAdapterTag>;
-  /**
-   * Restore all persisted actors for a machine type.
-   * Uses adapter registry if available, otherwise returns empty result.
-   *
-   * @example
-   * ```ts
-   * const result = yield* system.restoreAll(orderMachine, {
-   *   filter: (meta) => meta.stateTag !== "Done"
-   * });
-   * console.log(`Restored ${result.restored.length} active orders`);
-   * ```
-   */
-  readonly restoreAll: <S extends {
-    readonly _tag: string;
-  }, E extends {
-    readonly _tag: string;
-  }, R>(machine: PersistentMachine<S, E, R>, options?: {
-    filter?: (meta: ActorMetadata) => boolean;
-  }) => Effect.Effect<RestoreResult<S, E, R>, PersistenceError, R | PersistenceAdapterTag>;
 }
 /**
  * ActorSystem service tag
@@ -253,13 +183,13 @@ type Listeners<S> = Set<(state: S) => void>;
  */
 declare const notifyListeners: <S>(listeners: Listeners<S>, state: S) => void;
 /**
- * Build core ActorRef methods shared between regular and persistent actors.
+ * Build core ActorRef methods.
  */
 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<QueuedEvent<E>>, stoppedRef: Ref.Ref<boolean>, listeners: Listeners<S>, stop: Effect.Effect<void>, system: ActorSystem, childrenMap: ReadonlyMap<string, ActorRef<AnyState, unknown>>, pendingReplies: Set<Deferred.Deferred<unknown, unknown>>) => ActorRef<S, E>;
+}, R, GD extends GuardsDef, EFD extends EffectsDef>(id: string, machine: Machine<S, E, R, any, any, GD, EFD>, stateRef: SubscriptionRef.SubscriptionRef<S>, eventQueue: Queue.Queue<QueuedEvent<E>>, stoppedRef: Ref.Ref<boolean>, listeners: Listeners<S>, stop: Effect.Effect<void>, system: ActorSystem, childrenMap: ReadonlyMap<string, ActorRef<AnyState, unknown>>, pendingReplies: Set<Deferred.Deferred<unknown, unknown>>, transitionsPubSub?: PubSub.PubSub<TransitionInfo<S, E>>) => ActorRef<S, E>;
 /**
  * Create and start an actor for a machine
  */
@@ -267,7 +197,9 @@ declare const createActor: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef, EFD extends EffectsDef>(id: string, machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>) => Effect.Effect<ActorRef<S, E>, never, Exclude<R, MachineContext<S, E, MachineRef<E>>> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, effect_Tracer0.ParentSpan> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope> | Exclude<Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>, effect_Tracer0.ParentSpan>>;
+}, R, GD extends GuardsDef, EFD extends EffectsDef>(id: string, machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, options?: {
+  initialState?: S;
+} | undefined) => Effect.Effect<ActorRef<S, E>, never, Exclude<R, MachineContext<S, E, MachineRef<E>>> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, effect_Tracer0.ParentSpan> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope> | Exclude<Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>, effect_Tracer0.ParentSpan>>;
 /** Fail all pending call/ask Deferreds with ActorStoppedError. Safe to call multiple times. */
 declare const settlePendingReplies: (pendingReplies: Set<Deferred.Deferred<unknown, unknown>>, actorId: string) => Effect.Effect<void, never, never>;
 /**
@@ -275,4 +207,4 @@ declare const settlePendingReplies: (pendingReplies: Set<Deferred.Deferred<unkno
  */
 declare const Default: Layer.Layer<ActorSystem, never, never>;
 //#endregion
-export { ActorRef, ActorRefSync, ActorSystem, Default, Listeners, type ProcessEventError, type ProcessEventHooks, type ProcessEventResult, QueuedEvent, SystemEvent, SystemEventListener, buildActorRefCore, createActor, notifyListeners, processEventCore, resolveTransition, runSpawnEffects, settlePendingReplies };
+export { ActorRef, ActorRefSync, ActorSystem, Default, Listeners, type ProcessEventError, type ProcessEventHooks, type ProcessEventResult, QueuedEvent, SystemEvent, SystemEventListener, TransitionInfo, buildActorRefCore, createActor, notifyListeners, processEventCore, resolveTransition, runSpawnEffects, settlePendingReplies };

package/dist/actor.js

@@ -1,11 +1,8 @@
 import { Inspector } from "./inspection.js";
 import { INTERNAL_INIT_EVENT } from "./internal/utils.js";
 import { ActorStoppedError, DuplicateActorError, NoReplyError } from "./errors.js";
-import { isPersistentMachine } from "./persistence/persistent-machine.js";
 import { emitWithTimestamp } from "./internal/inspection.js";
 import { processEventCore, resolveTransition, runSpawnEffects, shouldPostpone } from "./internal/transition.js";
-import { PersistenceAdapterTag, PersistenceError } from "./persistence/adapter.js";
-import { createPersistentActor, restorePersistentActor } from "./persistence/persistent-actor.js";
 import { Cause, Deferred, Effect, Exit, Fiber, Layer, MutableHashMap, Option, PubSub, Queue, Ref, Scope, Semaphore, ServiceMap, Stream, SubscriptionRef } from "effect";
 //#region src/actor.ts
 /**
@@ -29,9 +26,9 @@ const notifyListeners = (listeners, state) => {
 	} catch {}
 };
 /**
-* Build core ActorRef methods shared between regular and persistent actors.
+* Build core ActorRef methods.
 */
-const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listeners, stop, system, childrenMap, pendingReplies) => {
+const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listeners, stop, system, childrenMap, pendingReplies, transitionsPubSub) => {
 	const send = Effect.fn("effect-machine.actor.send")(function* (event) {
 		if (yield* Ref.get(stoppedRef)) return;
 		yield* Queue.offer(eventQueue, {
@@ -119,6 +116,7 @@ const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listen
 		matches,
 		can,
 		changes: SubscriptionRef.changes(stateRef),
+		transitions: transitionsPubSub !== void 0 ? Stream.fromPubSub(transitionsPubSub) : Stream.empty,
 		waitFor,
 		awaitFinal,
 		sendAndWait,
@@ -149,7 +147,8 @@ const buildActorRefCore = (id, machine, stateRef, eventQueue, stoppedRef, listen
 /**
 * Create and start an actor for a machine
 */
-const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machine) {
+const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machine, options) {
+	const initial = options?.initialState ?? machine.initial;
 	yield* Effect.annotateCurrentSpan("effect_machine.actor.id", id);
 	const existingSystem = yield* Effect.serviceOption(ActorSystem);
 	let system;
@@ -184,20 +183,20 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 			return child;
 		})
 	};
-	yield* Effect.annotateCurrentSpan("effect_machine.actor.initial_state", machine.initial._tag);
+	yield* Effect.annotateCurrentSpan("effect_machine.actor.initial_state", initial._tag);
 	yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
 		type: "@machine.spawn",
 		actorId: id,
-		initialState: machine.initial,
+		initialState: initial,
 		timestamp
 	}));
-	const stateRef = yield* SubscriptionRef.make(machine.initial);
+	const stateRef = yield* SubscriptionRef.make(initial);
 	const listeners = /* @__PURE__ */ new Set();
 	const backgroundFibers = [];
 	const initEvent = { _tag: INTERNAL_INIT_EVENT };
 	const ctx = {
 		actorId: id,
-		state: machine.initial,
+		state: initial,
 		event: initEvent,
 		self,
 		system
@@ -206,7 +205,7 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 	for (const bg of machine.backgroundEffects) {
 		const fiber = yield* Effect.forkDetach(bg.handler({
 			actorId: id,
-			state: machine.initial,
+			state: initial,
 			event: initEvent,
 			self,
 			effects: effectSlots,
@@ -215,14 +214,14 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 		backgroundFibers.push(fiber);
 	}
 	const stateScopeRef = { current: yield* Scope.make() };
-	yield* runSpawnEffectsWithInspection(machine, machine.initial, initEvent, self, stateScopeRef.current, id, inspectorValue, system);
-	if (machine.finalStates.has(machine.initial._tag)) {
+	yield* runSpawnEffectsWithInspection(machine, initial, initEvent, self, stateScopeRef.current, id, inspectorValue, system);
+	if (machine.finalStates.has(initial._tag)) {
 		yield* Scope.close(stateScopeRef.current, Exit.void);
 		yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
 		yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
 			type: "@machine.stop",
 			actorId: id,
-			finalState: machine.initial,
+			finalState: initial,
 			timestamp
 		}));
 		yield* Ref.set(stoppedRef, true);
@@ -230,7 +229,8 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 		return buildActorRefCore(id, machine, stateRef, eventQueue, stoppedRef, listeners, Ref.set(stoppedRef, true).pipe(Effect.withSpan("effect-machine.actor.stop"), Effect.asVoid), system, childrenMap, /* @__PURE__ */ new Set());
 	}
 	const pendingReplies = /* @__PURE__ */ new Set();
-	const loopFiber = yield* Effect.forkDetach(eventLoop(machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, id, inspectorValue, system, pendingReplies));
+	const transitionsPubSub = yield* PubSub.unbounded();
+	const loopFiber = yield* Effect.forkDetach(eventLoop(machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, id, inspectorValue, system, pendingReplies, transitionsPubSub));
 	return buildActorRefCore(id, machine, stateRef, eventQueue, stoppedRef, listeners, Effect.gen(function* () {
 		const finalState = yield* SubscriptionRef.get(stateRef);
 		yield* emitWithTimestamp(inspectorValue, (timestamp) => ({
@@ -245,7 +245,7 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 		yield* Scope.close(stateScopeRef.current, Exit.void);
 		yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
 		if (implicitSystemScope !== void 0) yield* Scope.close(implicitSystemScope, Exit.void);
-	}).pipe(Effect.withSpan("effect-machine.actor.stop"), Effect.asVoid), system, childrenMap, pendingReplies);
+	}).pipe(Effect.withSpan("effect-machine.actor.stop"), Effect.asVoid), system, childrenMap, pendingReplies, transitionsPubSub);
 });
 /** Fail all pending call/ask Deferreds with ActorStoppedError. Safe to call multiple times. */
 const settlePendingReplies = (pendingReplies, actorId) => Effect.sync(() => {
@@ -258,7 +258,7 @@ const settlePendingReplies = (pendingReplies, actorId) => Effect.sync(() => {
 * Includes postpone buffer — events matching postpone rules are buffered
 * and drained after state tag changes (gen_statem semantics).
 */
-const eventLoop = Effect.fn("effect-machine.actor.eventLoop")(function* (machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, actorId, inspector, system, pendingReplies) {
+const eventLoop = Effect.fn("effect-machine.actor.eventLoop")(function* (machine, stateRef, eventQueue, stoppedRef, self, listeners, backgroundFibers, stateScopeRef, actorId, inspector, system, pendingReplies, transitionsPubSub) {
 	const postponed = [];
 	const hasPostponeRules = machine.postponeRules.length > 0;
 	const processQueued = Effect.fn("effect-machine.actor.processQueued")(function* (queued) {
@@ -301,6 +301,11 @@ const eventLoop = Effect.fn("effect-machine.actor.eventLoop")(function* (machine
 				}));
 				break;
 		}
+		if (result.transitioned) yield* PubSub.publish(transitionsPubSub, {
+			fromState: result.previousState,
+			toState: result.newState,
+			event
+		});
 		return {
 			shouldStop,
 			stateChanged: result.lifecycleRan
@@ -316,15 +321,21 @@ const eventLoop = Effect.fn("effect-machine.actor.eventLoop")(function* (machine
 			yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
 			return;
 		}
-		if (stateChanged && postponed.length > 0) {
+		let drainTriggered = stateChanged;
+		while (drainTriggered && postponed.length > 0) {
+			drainTriggered = false;
 			const drained = postponed.splice(0);
-			for (const entry of drained) if ((yield* processQueued(entry)).shouldStop) {
-				yield* Ref.set(stoppedRef, true);
-				settlePostponedBuffer(postponed, pendingReplies, actorId);
-				yield* settlePendingReplies(pendingReplies, actorId);
-				yield* Scope.close(stateScopeRef.current, Exit.void);
-				yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
-				return;
+			for (const entry of drained) {
+				const drain = yield* processQueued(entry);
+				if (drain.shouldStop) {
+					yield* Ref.set(stoppedRef, true);
+					settlePostponedBuffer(postponed, pendingReplies, actorId);
+					yield* settlePendingReplies(pendingReplies, actorId);
+					yield* Scope.close(stateScopeRef.current, Exit.void);
+					yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
+					return;
+				}
+				if (drain.stateChanged) drainTriggered = true;
 			}
 		}
 	}
@@ -480,25 +491,7 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 		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(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)));
-	});
-	const spawnImpl = Effect.fn("effect-machine.actorSystem.spawn")(function* (id, machine) {
-		if (isPersistentMachine(machine)) return yield* spawnPersistent(id, machine);
-		return yield* spawnRegular(id, machine);
-	});
-	function spawn(id, machine) {
-		return withSpawnGate(spawnImpl(id, machine));
-	}
-	const restoreImpl = Effect.fn("effect-machine.actorSystem.restore")(function* (id, persistentMachine) {
-		const maybeActor = yield* restorePersistentActor(id, persistentMachine);
-		if (Option.isSome(maybeActor)) yield* registerActor(id, maybeActor.value);
-		return maybeActor;
-	});
-	const restore = (id, persistentMachine) => withSpawnGate(restoreImpl(id, persistentMachine));
+	const spawn = (id, machine) => withSpawnGate(spawnRegular(id, machine));
 	const get = Effect.fn("effect-machine.actorSystem.get")(function* (id) {
 		return yield* Effect.sync(() => MutableHashMap.get(actorsMap, id));
 	});
@@ -515,55 +508,8 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 		yield* actor.stop;
 		return true;
 	});
-	const listPersisted = Effect.fn("effect-machine.actorSystem.listPersisted")(function* () {
-		const adapter = yield* PersistenceAdapterTag;
-		if (adapter.listActors === void 0) return [];
-		return yield* adapter.listActors();
-	});
-	const restoreMany = Effect.fn("effect-machine.actorSystem.restoreMany")(function* (ids, persistentMachine) {
-		const restored = [];
-		const failed = [];
-		for (const id of ids) {
-			if (MutableHashMap.has(actorsMap, id)) continue;
-			const result = yield* Effect.result(restore(id, persistentMachine));
-			if (result._tag === "Failure") failed.push({
-				id,
-				error: result.failure
-			});
-			else if (Option.isSome(result.success)) restored.push(result.success.value);
-			else failed.push({
-				id,
-				error: new PersistenceError({
-					operation: "restore",
-					actorId: id,
-					message: "No persisted state found"
-				})
-			});
-		}
-		return {
-			restored,
-			failed
-		};
-	});
-	const restoreAll = Effect.fn("effect-machine.actorSystem.restoreAll")(function* (persistentMachine, options) {
-		const adapter = yield* PersistenceAdapterTag;
-		if (adapter.listActors === void 0) return {
-			restored: [],
-			failed: []
-		};
-		const machineType = persistentMachine.persistence.machineType;
-		if (machineType === void 0) return yield* new PersistenceError({
-			operation: "restoreAll",
-			actorId: "*",
-			message: "restoreAll requires explicit machineType in persistence config"
-		});
-		let filtered = (yield* adapter.listActors()).filter((meta) => meta.machineType === machineType);
-		if (options?.filter !== void 0) filtered = filtered.filter(options.filter);
-		return yield* restoreMany(filtered.map((meta) => meta.id), persistentMachine);
-	});
 	return ActorSystem.of({
 		spawn,
-		restore,
 		get,
 		stop,
 		events: Stream.fromPubSub(eventPubSub),
@@ -579,10 +525,7 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 			return () => {
 				eventListeners.delete(fn);
 			};
-		},
-		listPersisted,
-		restoreMany,
-		restoreAll
+		}
 	});
 });
 /**

package/dist/index.d.ts

@@ -1,13 +1,9 @@
 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 { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaError, MissingMatchHandlerError, MissingSchemaError, NoReplyError, ProvisionValidationError, SlotProvisionError, UnprovidedSlotsError } from "./errors.js";
 import { ProcessEventResult } from "./internal/transition.js";
-import { PersistentActorRef, createPersistentActor, restorePersistentActor } from "./persistence/persistent-actor.js";
-import { ActorMetadata, PersistedEvent, PersistenceAdapter, PersistenceAdapterTag, PersistenceError, RestoreFailure, RestoreResult, Snapshot, VersionConflictError } from "./persistence/adapter.js";
-import { InMemoryPersistenceAdapter, makeInMemoryPersistenceAdapter } from "./persistence/adapters/in-memory.js";
-import { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, PersistOptions, ProvideHandlers, SpawnEffect, StateHandlerContext, TaskOptions, Transition, machine_d_exports } from "./machine.js";
-import { ActorRef, ActorRefSync, ActorSystem, Default, SystemEvent, SystemEventListener } from "./actor.js";
+import { BackgroundEffect, BuiltMachine, HandlerContext, Machine, MachineRef, MakeConfig, ProvideHandlers, SpawnEffect, StateHandlerContext, TaskOptions, Transition, machine_d_exports } from "./machine.js";
+import { ActorRef, ActorRefSync, ActorSystem, Default, SystemEvent, SystemEventListener, TransitionInfo } from "./actor.js";
 import { SimulationResult, TestHarness, TestHarnessOptions, assertNeverReaches, assertPath, assertReaches, createTestHarness, simulate } from "./testing.js";
 import { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, InspectionEvent, Inspector, InspectorHandler, SpawnEvent, StopEvent, TaskEvent, TracingInspectorOptions, TransitionEvent, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector } from "./inspection.js";
-export { type ActorMetadata, type ActorRef, type ActorRefSync, ActorStoppedError, type ActorSystem, Default as ActorSystemDefault, ActorSystem as ActorSystemService, type AnyInspectionEvent, AssertionError, type BackgroundEffect, type BuiltMachine, DuplicateActorError, type EffectEvent, type EffectSlots, type EffectsDef, type EffectsSchema, type ErrorEvent, Event, type EventReceivedEvent, type GuardHandlers, type GuardSlot, type GuardSlots, type GuardsDef, type GuardsSchema, type HandlerContext, InMemoryPersistenceAdapter, type InspectionEvent, type Inspector, type InspectorHandler, Inspector as InspectorService, InvalidSchemaError, machine_d_exports as Machine, type MachineContext, type MachineEventSchema, type MachineRef, type MachineStateSchema, type Machine as MachineType, type MakeConfig, MissingMatchHandlerError, MissingSchemaError, NoReplyError, type PersistOptions, type PersistedEvent, type PersistenceAdapter, PersistenceAdapterTag, type PersistenceConfig, PersistenceError, type PersistentActorRef, type PersistentMachine, type ProcessEventResult, type ProvideHandlers, ProvisionValidationError, type RestoreFailure, type RestoreResult, type SimulationResult, Slot, type EffectHandlers as SlotEffectHandlers, type EffectSlot as SlotEffectSlot, SlotProvisionError, type Snapshot, type SpawnEffect, type SpawnEvent, State, type StateHandlerContext, type StopEvent, type SystemEvent, type SystemEventListener, type TaskEvent, type TaskOptions, type TestHarness, type TestHarnessOptions, type TracingInspectorOptions, type Transition, type TransitionEvent, UnprovidedSlotsError, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createPersistentActor, createTestHarness, isPersistentMachine, makeInMemoryPersistenceAdapter, makeInspector, makeInspectorEffect, restorePersistentActor, simulate, tracingInspector };
+export { type ActorRef, type ActorRefSync, ActorStoppedError, type ActorSystem, Default as ActorSystemDefault, ActorSystem as ActorSystemService, type AnyInspectionEvent, AssertionError, type BackgroundEffect, type BuiltMachine, DuplicateActorError, type EffectEvent, type EffectSlots, type EffectsDef, type EffectsSchema, type ErrorEvent, Event, type EventReceivedEvent, type GuardHandlers, type GuardSlot, type GuardSlots, type GuardsDef, type GuardsSchema, type HandlerContext, type InspectionEvent, type Inspector, type InspectorHandler, Inspector as InspectorService, InvalidSchemaError, machine_d_exports as Machine, type MachineContext, type MachineEventSchema, type MachineRef, type MachineStateSchema, type Machine as MachineType, type MakeConfig, MissingMatchHandlerError, MissingSchemaError, NoReplyError, type ProcessEventResult, type ProvideHandlers, ProvisionValidationError, type SimulationResult, Slot, type EffectHandlers as SlotEffectHandlers, type EffectSlot as SlotEffectSlot, SlotProvisionError, type SpawnEffect, type SpawnEvent, State, type StateHandlerContext, type StopEvent, type SystemEvent, type SystemEventListener, type TaskEvent, type TaskOptions, type TestHarness, type TestHarnessOptions, type TracingInspectorOptions, type Transition, type TransitionEvent, type TransitionInfo, UnprovidedSlotsError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, simulate, tracingInspector };