effect-machine 0.19.0 → 0.20.0

package/README.md

@@ -2,14 +2,9 @@
 
 Type-safe state machines for [Effect](https://effect.website).
 
-Complex workflows usually fail the same way: one `status` field, a few side booleans, and effects scattered across callbacks. `effect-machine` gives you one typed model for state, events, and transitions, then runs it as a real actor.
+Effect Machine gives one actor a schema-first state model, a typed event mailbox, scoped Effect work, typed input and output, supervision, persistence hooks, inspection, and framework-neutral Atom integration.
 
-Use it when a feature has:
-
-- multiple valid and invalid states
-- async work tied to state entry
-- retries, timeouts, cancellation, or backpressure
-- logic you want to reuse in-process, in tests, and in distributed systems
+Use it when a feature has several valid states, invalid transitions, state-owned async work, timeouts, cancellation, actor coordination, or UI views that need precise subscriptions.
 
 ## Install
 
@@ -17,244 +12,247 @@ Use it when a feature has:
 bun add effect-machine effect
 ```
 
-`effect` is a peer dependency. The repository validates the package with
-`@effect/tsgo`, the latest Effect release candidate, type-aware oxlint, and Bun tests.
+`effect` is a required peer dependency.
+
+## Imports
+
+```ts
+import { Event, Machine, State } from "effect-machine";
+import * as ActorAtom from "effect-machine/atom";
+import { EntityMachine, toEntity } from "effect-machine/cluster";
+```
+
+Use `effect-machine` for local machines and actors. Use `effect-machine/atom` for React, Solid, or another Effect Atom binding. Use `effect-machine/cluster` for distributed entity machines.
 
-## Core Pattern
+## First machine
 
-States and events are schemas. Types, validation, and serialization from one place.
+States and events are Effect schemas.
 
 ```ts
-import { Cause, Context, Effect, Schema } from "effect";
+import { Effect, Schema } from "effect";
 import { Event, Machine, State } from "effect-machine";
 
-const CheckoutState = State({
-  ReviewingCart: { cartId: Schema.String, totalCents: Schema.Number },
-  ChargingCard: { cartId: Schema.String, totalCents: Schema.Number },
-  Confirmed: { cartId: Schema.String, receiptId: Schema.String },
-  Failed: { cartId: Schema.String, reason: Schema.String },
+const DownloadState = State({
+  Idle: {},
+  Downloading: { url: Schema.String },
+  Done: { url: Schema.String, bytes: Schema.Finite },
+  Failed: { url: Schema.String, message: Schema.String },
 });
 
-const CheckoutEvent = Event({
-  Submit: {},
-  Charged: { receiptId: Schema.String },
-  Declined: { reason: Schema.String },
-  Cancel: {},
+const DownloadEvent = Event({
+  Start: { url: Schema.String },
+  Completed: { bytes: Schema.Finite },
+  Failed: { message: Schema.String },
 });
 
-class PaymentService extends Context.Service<
-  PaymentService,
-  {
-    readonly chargeCard: (
-      cartId: string,
-      totalCents: number,
-    ) => Effect.Effect<{ readonly receiptId: string }>;
-  }
->()("app/PaymentService") {}
-
-const checkoutMachine = Machine.make({
-  state: CheckoutState,
-  event: CheckoutEvent,
-  initial: CheckoutState.ReviewingCart({ cartId: "cart_123", totalCents: 4200 }),
+const downloadMachine = Machine.make({
+  state: DownloadState,
+  event: DownloadEvent,
+  initial: DownloadState.Idle,
 })
-  .on(CheckoutState.ReviewingCart, CheckoutEvent.Submit, ({ state }) =>
-    CheckoutState.ChargingCard.with(state),
-  )
-  .on(CheckoutState.ChargingCard, CheckoutEvent.Charged, ({ state, event }) =>
-    CheckoutState.Confirmed.with(state, { receiptId: event.receiptId }),
+  .on(DownloadState.Idle, DownloadEvent.Start, ({ event }) =>
+    DownloadState.Downloading({ url: event.url }),
   )
-  .on(CheckoutState.ChargingCard, CheckoutEvent.Declined, ({ state, event }) =>
-    CheckoutState.Failed.with(state, { reason: event.reason }),
+  .on(DownloadState.Downloading, DownloadEvent.Completed, ({ state, event }) =>
+    DownloadState.Done.with(state, { bytes: event.bytes }),
   )
-  .onAny(CheckoutEvent.Cancel, ({ state }) =>
-    CheckoutState.Failed.with(state, { reason: "cancelled" }),
-  )
-  .task(
-    CheckoutState.ChargingCard,
-    ({ state }) =>
-      Effect.flatMap(PaymentService, (payment) =>
-        payment.chargeCard(state.cartId, state.totalCents),
-      ),
-    {
-      onSuccess: ({ receiptId }) => CheckoutEvent.Charged({ receiptId }),
-      onFailure: (cause) => CheckoutEvent.Declined({ reason: Cause.pretty(cause) }),
-    },
+  .on(DownloadState.Downloading, DownloadEvent.Failed, ({ state, event }) =>
+    DownloadState.Failed.with(state, { message: event.message }),
   )
-  .final(CheckoutState.Confirmed)
-  .final(CheckoutState.Failed);
+  .final(DownloadState.Done, ({ state }) => state.bytes)
+  .final(DownloadState.Failed, () => 0);
+
+const program = Effect.scoped(
+  Machine.scoped(
+    Effect.gen(function* () {
+      const actor = yield* Machine.spawn(downloadMachine);
+      yield* actor.start;
+      yield* actor.send(DownloadEvent.Start({ url: "/report.pdf" }));
+      yield* actor.send(DownloadEvent.Completed({ bytes: 1024 }));
+      return yield* actor.awaitOutput;
+    }),
+  ),
+);
 ```
 
-A few things to notice:
+An empty variant is a value such as `DownloadState.Idle`. A non-empty variant is a constructor such as `DownloadState.Downloading({ url })`.
+
+`State.with(source, fields)` copies matching fields into the target variant. It prevents manual context spreading across different states.
 
-- Empty variants are values: `State.Idle`. Non-empty are constructors: `State.Loading({ url })`.
-- `State.with(source, overrides)` carries overlapping fields forward without manual copying.
-- `.onAny(...)` is a fallback; a specific `.on(...)` wins.
-- `.spawn(...)` runs work on state entry and cancels it on state exit.
+## Effect is the composition layer
 
-The builder also supports `.timeout(state, { duration, event })`, `.postpone(state, event)` for buffering, and `.reenter(...)` for re-running lifecycle on same-state transitions.
+Effect Machine does not add an action queue or a second context system.
 
-## Effect Services
+| Work                                  | API                                          |
+| ------------------------------------- | -------------------------------------------- |
+| Unconditional state change            | `.on`, `.reenter`, or `.immediate`           |
+| Conditional state change              | `.when`, `.reenterWhen`, or `.immediateWhen` |
+| Work that produces a completion event | `.task`                                      |
+| State-owned stream or resource        | `.spawn`                                     |
+| Actor-owned stream or resource        | `.background`                                |
+| Autonomous machine sequence           | `Machine.run` with `Effect.flatMap`          |
+| Interactive multi-phase flow          | Parent machine with child actors             |
 
-Task, spawn, and background handlers can use standard Effect services. The machine type records each service requirement.
+Effect requirements remain in `R`. A machine cannot start until the application provides every required service. Effectful transition handlers must have `never` in their error channel. Convert expected failures to states or events.
+
+Read [the Effect model](./docs/effect-model.md) and [async work ownership](./docs/async-work.md).
+
+## Guards and stable state
+
+Register ordered candidates for one state and event. The first passing guard wins. An unguarded candidate is the fallback.
 
 ```ts
-const actor =
-  yield *
-  Machine.spawn(checkoutMachine).pipe(
-    Effect.provideService(PaymentService, {
-      chargeCard: (cartId) => Effect.succeed({ receiptId: `rcpt_${cartId}` }),
-    }),
-  );
-yield * actor.start;
+machine
+  .when(
+    State.Checking,
+    Event.Continue,
+    function hasStock({ state }) {
+      return state.stock > 0;
+    },
+    () => State.Accepted,
+  )
+  .on(State.Checking, Event.Continue, () => State.Rejected)
+  .immediate(State.Accepted, ({ state }) => State.Ready.with(state));
 ```
 
-`Machine.spawn` captures the current Effect context. A later `actor.start` keeps those services. Use a different layer or service value in each test or runtime.
-
-Transition handlers in `.on()` and `.reenter()` stay pure. Use services only in `.task()`, `.spawn()`, and `.background()`.
+The predicate can return a Boolean or `Effect<boolean, never, R>`. Its requirements flow into the machine type. `actor.can(event)` evaluates the same predicate with the actor's captured context. `ActorAtom.can(actor, event)` exposes the result to React and Solid. The inspector uses the predicate function name.
 
-## Running Actors
+Immediate transitions run until the state is stable. Subscribers see only the stable state. The runtime stops an accidental eventless loop after 100 edges.
 
-`Machine.spawn` allocates an actor but does not start it. Call `actor.start` to fork the event loop, background effects, and spawn effects. Events sent before `start()` are queued.
+## Effect services and tasks
 
 ```ts
-const program = Effect.gen(function* () {
-  const actor = yield* Machine.spawn(checkoutMachine);
-  yield* actor.start;
-
-  yield* actor.send(CheckoutEvent.Submit);
-  const finalState = yield* actor.awaitFinal;
+class Api extends Context.Service<
+  Api,
+  { readonly load: (id: string) => Effect.Effect<Data, ApiError> }
+>()("app/Api") {}
+
+machine.task(State.Loading, ({ state }) => Effect.flatMap(Api, (api) => api.load(state.id)), {
+  name: "load-data",
+  onSuccess: (data) => Event.Loaded({ data }),
+  onFailure: (error) => Event.LoadFailed({ message: String(error) }),
 });
 
-Effect.runPromise(
-  Effect.scoped(program).pipe(
-    Effect.provideService(PaymentService, {
-      chargeCard: (cartId) => Effect.succeed({ receiptId: `rcpt_${cartId}` }),
-    }),
-  ),
-);
+const actor = yield * Machine.spawn(machine).pipe(Effect.provide(ApiLive));
+yield * actor.start;
 ```
 
-Key actor operations:
+The actor captures the Effect context during allocation. It keeps those services when it starts later.
 
-- `start` forks the event loop (idempotent, required after `Machine.spawn`)
-- `send(event)` queues and returns immediately
-- `call(event)` returns full transition info
-- `ask(event)` returns a typed domain reply (requires `Event.reply(...)`)
-- `waitFor(...)` / `awaitFinal` for coordination
-- `stop` interrupts now; `drain` processes the remaining queue first
-- `awaitExit` completes when the actor stops
+`onFailure` receives the typed Effect error. A defect does not enter `onFailure`. It stops the actor or starts supervision.
 
-For named actors or shared lookup, use an actor system. `system.spawn` auto-starts — no `actor.start` needed:
+## Input, output, and composition
 
 ```ts
-import { ActorSystemDefault, ActorSystemService } from "effect-machine";
+const checkoutMachine = Machine.make({
+  state: CheckoutState,
+  event: CheckoutEvent,
+  initial: (input: CheckoutInput) => CheckoutState.Reviewing(input),
+}).final(CheckoutState.Done, ({ state }) => ({ receiptId: state.receiptId }));
 
-const program = Effect.gen(function* () {
-  const system = yield* ActorSystemService;
-  const actor = yield* system.spawn("checkout-123", checkoutMachine);
-  yield* actor.send(CheckoutEvent.Submit);
-}).pipe(Effect.provide(ActorSystemDefault));
+const program = Machine.run(cartMachine).pipe(
+  Effect.flatMap((cart) => Machine.run(checkoutMachine, { input: cart })),
+);
 ```
 
-### Typed Replies
+`Machine.run` starts one actor, waits for output, and always stops it. Interruption releases actor resources. The final actor state remains available when you use `Machine.spawn` and retain the actor reference.
 
-Events can declare typed reply schemas:
+Use a parent machine when a UI must route between phases, keep shared values, or support back navigation. Read [Actors and systems](./docs/actors.md).
 
-```ts
-const CartEvent = Event({
-  GetTotal: Event.reply({}, Schema.Number),
-});
+## ActorRef
 
-machine.on(State.Active, CartEvent.GetTotal, ({ state }) => Machine.reply(state, state.totalCents));
+| Member                      | Use                                                |
+| --------------------------- | -------------------------------------------------- |
+| `start`                     | Start a direct actor                               |
+| `send(event)`               | Queue an event                                     |
+| `call(event)`               | Process an event and return transition information |
+| `ask(event)`                | Return a typed reply from an `Event.reply` event   |
+| `waitFor(state)`            | Wait for a state constructor or predicate          |
+| `sendAndWait(event, state)` | Send and wait for a state                          |
+| `snapshot`                  | Read the current state as an Effect                |
+| `awaitFinal`                | Wait for the final state                           |
+| `awaitOutput`               | Wait for typed output                              |
+| `awaitExit`                 | Wait for `Final`, `Stopped`, or `Defect`           |
+| `drain`                     | Process queued events and stop                     |
+| `subscribe`                 | Observe state with a host callback                 |
+| `client`                    | Use the actor outside Effect                       |
+| `system`                    | Access named actors                                |
+| `children`                  | Read direct child actors                           |
 
-const total = yield * actor.ask(CartEvent.GetTotal); // number
-```
+`Machine.spawn` returns an unstarted actor. `system.spawn` starts the actor.
 
-## Testing
+Use `actor.client` in a JavaScript callback or application that does not run inside Effect. `client.can(event)` returns a Promise and supports Effect predicates. `client.canSync(event)` supports Boolean predicates only. React and Solid should use Actor Atoms.
 
-Test transitions without spawning actors:
+## Atom, React, and Solid
 
 ```ts
-import { simulate } from "effect-machine";
-
-const result =
-  yield *
-  simulate(checkoutMachine, [
-    CheckoutEvent.Submit,
-    CheckoutEvent.Charged({ receiptId: "rcpt_123" }),
-  ]);
+import * as ActorAtom from "effect-machine/atom";
 
-expect(result.states.map((s) => s._tag)).toEqual(["ReviewingCart", "ChargingCard", "Confirmed"]);
+const stateAtom = ActorAtom.make(actor);
+const countAtom = ActorAtom.select(stateAtom, (state) => state.count);
 ```
 
-`simulate` and `createTestHarness` test transition logic. They do not run `.spawn()` or `.background()` effects.
+The selected Atom stays writable. Writes send machine events. A selector publishes only when its selected value changes.
 
-## React, Solid, and Vue
+The React example uses `useAtomSuspense` and Motion. The Solid example uses `useAtomResource`, Suspense, and `solid-transition-group`. Both include performance tests. Both retain exit-animation data in the terminal machine state.
 
-Use the Effect Atom adapter to connect one actor to any Effect Atom framework binding. The actor remains the state owner. Atom writes send typed events.
+Read [Atom and UI integration](./docs/atom-and-ui.md) and browse [all examples](./examples/README.md).
 
-```ts
-import { useAtomSet, useAtomValue } from "@effect/atom-react";
-import * as ActorAtom from "effect-machine/atom";
+## Persistence, supervision, and inspection
 
-const checkoutAtom = ActorAtom.make(actor);
+- Recovery resolves state during actor startup.
+- Durability saves committed transitions.
+- Supervision restarts defects within an Effect `Schedule` budget.
+- Inspection reports events, named transition operations, transitions, named guards, tasks, Effects, errors, stops, and actor generations.
 
-function CheckoutTotal() {
-  const totalCents = useAtomValue(checkoutAtom, (state) =>
-    "totalCents" in state ? state.totalCents : 0,
-  );
-  const send = useAtomSet(checkoutAtom);
+Read [Persistence and supervision](./docs/persistence-and-supervision.md) and [Inspection](./docs/inspection.md).
 
-  return <button onClick={() => send(CheckoutEvent.Submit)}>Pay {totalCents}</button>;
-}
-```
+## Testing
 
-`useAtomValue` subscribes to the selected value. It does not render again when another state field changes. Use `ActorAtom.select` when you need a reusable selector or a custom equality function:
+Use `simulate` or `createTestHarness` for transition paths. Spawn a real actor for tasks, services, resources, persistence, supervision, inspection, and actor topology.
 
 ```ts
-const totalAtom = ActorAtom.select(
-  checkoutAtom,
-  (state) => ("totalCents" in state ? { cents: state.totalCents } : { cents: 0 }),
-  (value, next) => value.cents === next.cents,
-);
+const result = yield * simulate(machine, events, { input });
+yield * assertPath(machine, events, ["Idle", "Loading", "Done"]);
+yield * assertNeverReaches(machine, events, "Failed");
 ```
 
-The selected Atom stays writable. `useAtomSet(totalAtom)` still sends checkout events. Solid uses the same Atom with `@effect/atom-solid`. Vue uses the same Atom with `@effect/atom-vue`.
-
-Runnable React and Solid package examples are in `examples/react` and `examples/solid`.
+Read [Testing](./docs/testing.md).
 
-```bash
-bun run example:react
-bun run example:solid
-```
+## XState migration
 
-Each example creates the actor through `Atom.make(Machine.scoped(...))`. React reads it with `useAtomSuspense`. Solid reads it with `useAtomResource` inside a Suspense boundary. The Atom scope owns actor cleanup.
+The [migration guide](./docs/xstate-migration.md) covers context, assign, actions, invoked promise and callback actors, root routers, actor registries, selectors, inspection, persistence, and exit animation values. Its patterns come from a large XState kiosk application.
 
-Each example has a framework performance test. The React test counts component renders. The Solid test counts reactive computations. Both tests prove that an unrelated selector does not update.
+## Cluster entities
 
-The React example uses Motion `AnimatePresence`. The Solid example uses `solid-transition-group`. Both examples keep the old screen mounted for a 200 ms exit after the machine enters `Done`.
+Use `effect-machine/cluster` to expose a machine through Effect Cluster. It supports typed send, ask, state reads, state watches, input adapters, snapshot persistence, and journal persistence.
 
-The terminal `Done` state keeps the displayed `count` and `label`. The old screen stays valid without a local retained-value hook. Keep exit data in the terminal state or handle the terminal variant in the selector. Do not cache the last non-null selector value.
+Read [Cluster entities](./docs/cluster.md).
 
-## Cluster
+## Examples
 
-When the same machine needs to run behind `@effect/cluster`, turn it into an entity:
+The examples directory is a Bun workspace.
 
-```ts
-import { EntityMachine, toEntity } from "effect-machine/cluster";
-
-const CheckoutEntity = toEntity(checkoutMachine, { type: "Checkout" });
-
-const CheckoutEntityLayer = EntityMachine.layer(CheckoutEntity, checkoutMachine, {
-  initializeState: (entityId) => CheckoutState.ReviewingCart({ cartId: entityId, totalCents: 0 }),
-  persistence: { strategy: "journal" },
-});
+```bash
+bun run examples:gate
+bun run example:react
+bun run example:solid
 ```
 
-Persistence strategies:
+The [example matrix](./examples/README.md) links every pattern to executable code.
+
+## Documentation
 
-- **Snapshot** — saves state periodically, restores on reactivation
-- **Journal** — appends events on each RPC, replays on reactivation
+- [Effect model](./docs/effect-model.md)
+- [Async work](./docs/async-work.md)
+- [Actors and systems](./docs/actors.md)
+- [Atom and UI integration](./docs/atom-and-ui.md)
+- [Persistence and supervision](./docs/persistence-and-supervision.md)
+- [Inspection](./docs/inspection.md)
+- [Testing](./docs/testing.md)
+- [Migration from XState](./docs/xstate-migration.md)
+- [Cluster entities](./docs/cluster.md)
+- [AI agent reference](./SKILL.md)
 
 ## License
 

package/dist/actor.d.ts

@@ -5,17 +5,31 @@ import { Lifecycle, Machine } from "./machine.js";
 import { ProcessEventResult } from "./internal/transition.js";
 import { Context, Effect, Layer, Option, Scope, Stream, SubscriptionRef } from "effect";
 //#region src/actor.d.ts
-/**
- * Sync projection of ActorRef for non-Effect boundaries (React hooks, framework callbacks).
- */
+/** JavaScript client for code that does not run inside Effect. */
+interface ActorClient<State extends {
+  readonly _tag: string;
+}, Event, Output = State> {
+  readonly send: (event: Event) => void;
+  readonly stop: () => void;
+  readonly getSnapshot: () => State;
+  readonly matches: (tag: State["_tag"]) => boolean;
+  readonly canSync: (event: Event) => boolean;
+  readonly can: (event: Event) => Promise<boolean>;
+  readonly getLifecycle: () => ActorLifecycle<State, Output>;
+  readonly getLatestTransition: () => TransitionInfo<State, Event> | undefined;
+  readonly subscribe: (listener: (state: State) => void) => () => void;
+}
+/** @deprecated Use `ActorClient`. */
 interface ActorRefSync<State extends {
   readonly _tag: string;
-}, Event> {
+}, Event, Output = State> {
   readonly send: (event: Event) => void;
   readonly stop: () => void;
   readonly snapshot: () => State;
   readonly matches: (tag: State["_tag"]) => boolean;
   readonly can: (event: Event) => boolean;
+  readonly lifecycle: () => ActorLifecycle<State, Output>;
+  readonly latestTransition: () => TransitionInfo<State, Event> | undefined;
 }
 /**
  * Information about a successful transition.
@@ -26,9 +40,19 @@ interface TransitionInfo<State, Event> {
   readonly toState: State;
   readonly event: Event;
 }
+/** Observable actor lifecycle. Domain state remains available through `actor.state`. */
+type ActorLifecycle<State, Output = State> = {
+  readonly _tag: "Created";
+} | {
+  readonly _tag: "Starting";
+  readonly generation: number;
+} | {
+  readonly _tag: "Active";
+  readonly generation: number;
+} | ActorExit<State, Output>;
 interface ActorRef<State extends {
   readonly _tag: string;
-}, Event> {
+}, Event, Output = State> {
   readonly id: string;
   /** Send an event (fire-and-forget). */
   readonly send: (event: Event) => Effect.Effect<void>;
@@ -36,7 +60,7 @@ interface ActorRef<State extends {
    * Serialized request-reply (OTP gen_server:call).
    * Event is processed through the queue; caller gets ProcessEventResult back.
    */
-  readonly call: (event: Event) => Effect.Effect<ProcessEventResult<State>>;
+  readonly call: (event: Event) => Effect.Effect<ProcessEventResult<State, Event>>;
   /**
    * Typed request-reply. Accepts only events with a reply schema
    * (defined via `Event.reply()`). Return type is inferred from the schema.
@@ -45,6 +69,10 @@ interface ActorRef<State extends {
   readonly ask: <E extends Event & ReplyTypeBrand<unknown>>(event: E) => Effect.Effect<ExtractReply<E>, NoReplyError | ActorStoppedError>;
   /** Observable state. */
   readonly state: SubscriptionRef.SubscriptionRef<State>;
+  /** Observable actor lifecycle. */
+  readonly lifecycle: SubscriptionRef.SubscriptionRef<ActorLifecycle<State, Output>>;
+  /** The latest accepted edge. This value remains available after actor exit. */
+  readonly latestTransition: SubscriptionRef.SubscriptionRef<TransitionInfo<State, Event> | undefined>;
   /** Stop the actor gracefully. */
   readonly stop: Effect.Effect<void>;
   /**
@@ -60,7 +88,7 @@ interface ActorRef<State extends {
   readonly snapshot: Effect.Effect<State>;
   /** Check if current state matches tag. */
   readonly matches: (tag: State["_tag"]) => Effect.Effect<boolean>;
-  /** Check if event can be handled in current state. */
+  /** Check if an event has an enabled transition. Supports Boolean and Effect predicates. */
   readonly can: (event: Event) => Effect.Effect<boolean>;
   /** Stream of state changes. */
   readonly changes: Stream.Stream<State>;
@@ -81,6 +109,8 @@ interface ActorRef<State extends {
   };
   /** Wait for a final state (includes current snapshot). */
   readonly awaitFinal: Effect.Effect<State>;
+  /** Wait for the domain output of a final state. */
+  readonly awaitOutput: Effect.Effect<Output, ActorStoppedError>;
   /** Send event and wait for predicate, state variant, or final state. */
   readonly sendAndWait: {
     (event: Event, predicate: (state: State) => boolean): Effect.Effect<State>;
@@ -91,18 +121,20 @@ interface ActorRef<State extends {
   };
   /** Subscribe to state changes (sync callback). Returns unsubscribe function. */
   readonly subscribe: (fn: (state: State) => void) => () => void;
+  /** JavaScript client for callbacks and applications outside Effect. */
+  readonly client: ActorClient<State, Event, Output>;
   /**
    * Wait for this actor's terminal exit. Resolves with the exit reason.
    * Set exactly once when the actor terminates (final, stop, drain, or defect).
    */
-  readonly awaitExit: Effect.Effect<ActorExit<State>>;
+  readonly awaitExit: Effect.Effect<ActorExit<State, Output>>;
   /**
    * Drain: process all remaining events in the queue, then stop.
    * Unlike `stop` (which interrupts immediately), `drain` lets the actor finish its work.
    */
   readonly drain: Effect.Effect<void>;
-  /** Sync helpers for non-Effect boundaries. */
-  readonly sync: ActorRefSync<State, Event>;
+  /** @deprecated Use `client`. */
+  readonly sync: ActorRefSync<State, Event, Output>;
   /** The actor system this actor belongs to. */
   readonly system: ActorSystemService;
   /** Child actors spawned via `self.spawn` in this actor's handlers. */
@@ -147,14 +179,14 @@ interface ActorSystemService {
    * const actor = yield* system.spawn("my-actor", machine);
    * ```
    */
-  readonly spawn: <S extends {
-    readonly _tag: string;
-  }, E extends {
-    readonly _tag: string;
-  }, R>(id: string, machine: Machine<S, E, R, any, any>, options?: {
-    readonly supervision?: Supervision.Policy;
-    readonly lifecycle?: Lifecycle<S, E>;
-  }) => Effect.Effect<ActorRef<S, E>, DuplicateActorError, R>;
+  readonly spawn: {
+    <S extends AnyState, E extends {
+      readonly _tag: string;
+    }, R, Output>(id: string, machine: Machine<S, E, R, any, any, void, Output>, options?: SystemSpawnOptions<S, E, void>): Effect.Effect<ActorRef<S, E, Output>, DuplicateActorError, R>;
+    <S extends AnyState, E extends {
+      readonly _tag: string;
+    }, R, Input, Output>(id: string, machine: Machine<S, E, R, any, any, Input, Output>, options: SystemSpawnOptions<S, E, Input>): Effect.Effect<ActorRef<S, E, Output>, DuplicateActorError, R>;
+  };
   /**
    * Get an existing actor by ID
    */
@@ -179,6 +211,15 @@ interface ActorSystemService {
    */
   readonly subscribe: (fn: SystemEventListener) => () => void;
 }
+type SystemSpawnOptions<S, E, Input> = {
+  readonly supervision?: Supervision.Policy;
+  readonly lifecycle?: Lifecycle<S, E>;
+  readonly hydrate?: S;
+} & ([Input] extends [void] ? {
+  readonly input?: never;
+} : {
+  readonly input: Input;
+});
 declare const ActorSystem_base: Context.ServiceClass<ActorSystem, "effect-machine/actor/ActorSystem", ActorSystemService>;
 /**
  * ActorSystem service tag
@@ -203,16 +244,18 @@ declare const createActor: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R>(id: string, machine: Machine<S, E, R, any, any>, options?: {
-  initialState?: S;
+}, R, O>(id: string, machine: Machine<S, E, R, any, any, any, O>, options: {
+  initialState: S;
+  machineInitial: S;
+  hydrated?: boolean;
   supervision?: Supervision.Policy;
   lifecycle?: Lifecycle<S, E>;
   /** @internal Called by system after each restart — emits ActorRestarted system event */
   onRestart?: (generation: number, exit: ActorExit<unknown>) => Effect.Effect<void>;
-} | undefined) => Effect.Effect<ActorRef<S, E>, never, R>;
+}) => Effect.Effect<ActorRef<S, E, O>, never, R>;
 /**
  * Default ActorSystem layer
  */
 declare const Default: Layer.Layer<ActorSystem, never, never>;
 //#endregion
-export { ActorRef, ActorRefSync, ActorScope, ActorSystem, ActorSystemService, Default, type ProcessEventResult, SystemEvent, SystemEventListener, TransitionInfo, createActor };
+export { ActorClient, ActorLifecycle, ActorRef, ActorRefSync, ActorScope, ActorSystem, ActorSystemService, Default, type ProcessEventResult, SystemEvent, SystemEventListener, SystemSpawnOptions, TransitionInfo, createActor };