@xstate/effect 0.1.0-alpha.2 → 0.1.0-alpha.5

package/README.md

@@ -1,8 +1,13 @@
 # @xstate/effect
 
-Effect integration for XState v6.
+Combine XState's event-driven workflows with Effect services, scopes, clocks and tracing.
 
-This package is experimental and targets XState v6 alpha and Effect 4 RC.
+- Model approval, cancellation, deadlines and retry as explicit states and events.
+- Invoke Effect tasks when their result determines the next state.
+- Provide services once for the actor and its child logic.
+- Keep actor lifetime inside your Effect application.
+
+This package is experimental. It targets XState v6 alpha and Effect 4 RC.
 
 ## Installation
 
@@ -12,600 +17,249 @@ This package is experimental and targets XState v6 alpha and Effect 4 RC.
 npm install @xstate/effect@alpha xstate@alpha effect@rc
 ```
 
-## Quick start
+## XState Effect: Quick start
 
 <!-- public API from src/index.ts; actor lifetime from src/createEffectActor.ts -->
 
-`createEffectActor` runs an XState actor as an Effect interpreter over pure transitions: each step is `transition(snapshot, event)`, and an Effect fiber owns the mailbox, the timers and the actions it produces. The actor is a scoped resource: it stops when the enclosing `Scope` closes. `fromEffect` turns an Effect into actor logic that a machine can invoke. The machine itself is an ordinary v6 machine.
+A release waits for approval, expires after 30 seconds, and allows cancellation during deployment. A failed deployment waits for an explicit retry:
+
+<!-- example from examples/effect-workflows/src/approval.ts -->
 
 ```ts
 import { Context, Effect, Schema } from 'effect';
-import { createEffectActor, fromEffect, waitFor } from '@xstate/effect';
-import { setup } from 'xstate';
+import {
+  createEffectActor,
+  fromEffect,
+  send,
+  setupEffect,
+  waitFor
+} from '@xstate/effect';
 
-class Api extends Context.Service<
-  Api,
-  {
-    readonly fetchUser: (id: string) => Effect.Effect<{ id: string }, Error>;
-  }
->()('@app/Api') {}
-
-const fetchUser = fromEffect({
-  schemas: {
-    input: Schema.Struct({ id: Schema.String }),
-    output: Schema.Struct({ id: Schema.String })
-  },
-  effect: ({ input }) => Api.use((api) => api.fetchUser(input.id))
+export class Deployments extends Context.Service<
+  Deployments,
+  { readonly deploy: (release: string) => Effect.Effect<string, Error> }
+>()('@app/Deployments') {}
+
+const deploy = fromEffect({
+  schemas: { input: Schema.Struct({ release: Schema.String }) },
+  effect: ({ input }) => Deployments.use((api) => api.deploy(input.release))
 });
 
-const machine = setup({ actors: { fetchUser } }).createMachine({
-  initial: 'loading',
+export const approvalMachine = setupEffect({
+  schemas: { input: Schema.Struct({ release: Schema.String }) },
+  actors: { deploy }
+}).createMachine({
+  context: ({ input }) => ({ release: input.release, url: '' }),
+  initial: 'awaitingApproval',
   states: {
-    loading: {
+    awaitingApproval: {
+      after: { 30000: { target: 'expired' } },
+      on: {
+        APPROVE: { target: 'deploying' },
+        CANCEL: { target: 'cancelled' }
+      }
+    },
+    deploying: {
       invoke: {
-        src: 'fetchUser',
-        input: { id: '42' },
-        onDone: { target: 'success' },
-        onError: { target: 'failure' }
+        src: 'deploy',
+        input: ({ context }) => ({ release: context.release }),
+        onDone: ({ context, event }) => ({
+          target: 'deployed',
+          context: { ...context, url: event.output }
+        }),
+        onError: { target: 'failed' }
+      },
+      on: { CANCEL: { target: 'cancelled' } }
+    },
+    failed: {
+      on: {
+        RETRY: { target: 'deploying' },
+        CANCEL: { target: 'cancelled' }
       }
     },
-    success: {},
-    failure: {}
+    deployed: { type: 'final' },
+    expired: { type: 'final' },
+    cancelled: { type: 'final' }
   }
 });
 
-const program = Effect.gen(function* () {
-  const actor = yield* createEffectActor(machine);
-  const snapshot = yield* waitFor(actor, (s) => s.matches('success'));
-  return snapshot.value;
+export const program = Effect.gen(function* () {
+  const actor = yield* createEffectActor(approvalMachine, {
+    input: { release: 'v1.2.0' }
+  });
+  // A UI, webhook or CLI can send this event after a person approves.
+  yield* send(actor, { type: 'APPROVE' });
+  const snapshot = yield* waitFor(actor, (s) => s.matches('deployed'), {
+    timeout: '5 seconds'
+  });
+  return snapshot.context.url;
 });
 
-await Effect.runPromise(
-  Effect.provideService(Effect.scoped(program), Api, {
-    fetchUser: (id) => Effect.succeed({ id })
-  })
-);
-```
-
-Effect-backed logic must run under `createEffectActor`. Starting it with `createActor` puts the actor in the `error` status because no Effect runtime is available.
-
-### How it runs
-
-XState's transition function is pure: `transition(snapshot, event)` returns the next snapshot and the actions to run, without running them. `createEffectActor` drives that function through XState's `createDurable` loop from an Effect fiber and interprets the actions:
-
-- the mailbox is an Effect `Queue`, so `actor.send` enqueues and the fiber processes events in order;
-- timers for `after` transitions and delayed events are `Effect.sleep` fibers in the actor's `Scope`, on the Effect `Clock`;
-- declared Effect actions run as forked Effects with the services captured at creation, without blocking the loop;
-- built-in actions (spawn, send, emit, stop) run as XState defines them, and child actors run as live XState actors whose Effects use the same host.
-
-The handle it returns is an `EffectActor`. It implements XState's `ActorRef` contract (`send`, `getSnapshot`, `subscribe`, `on`) plus `inspect`, `getPersistedSnapshot` and `stop`, so `useSelector`, this package's actor functions and the inspection APIs accept it. Because the loop runs on a fiber, `send` returns before the event is processed; read the outcome with `waitFor`, `join` or `snapshots` rather than `getSnapshot` right after a send.
-
-## Actors
-
-### Lifetime
-
-`createEffectActor(logic, options?)` returns `Effect<Actor, never, R | Scope>`, where `R` is the union of service requirements of the logic (see [Requirements](#requirements)). The actor stops, and every Effect it hosts is interrupted, when the scope closes. Use `Effect.scoped` to close the scope when the program finishes, or run the actor inside a Layer to tie it to the application's lifetime.
-
-Effects hosted by the actor see a `Scope` that closes when the actor stops. `Effect.addFinalizer` and `Effect.acquireRelease` inside an actor's Effects release with the actor, not with the Effect that registered them.
-
-Provide Layers outside `Effect.scoped`, so their resources are released after the actor has stopped:
-
-```ts
-await Effect.runPromise(program.pipe(Effect.scoped, Effect.provide(AppLayer)));
-```
-
-`actor.stop()` still works. It stops the actor and closes the actor's scope synchronously; the release step of `createEffectActor` waits for the actor scope's finalizers before the enclosing scope continues closing.
-
-### Providing an actor as a service
-
-An actor built by `createEffectActor` is a scoped Effect, so `Layer.effect` turns it into a service. The actor starts when the Layer is built and stops when the Layer's scope closes.
-
-```ts
-import { Context, Effect, Layer, ManagedRuntime } from 'effect';
-import {
-  createEffectActor,
-  send,
-  waitFor,
-  type EffectActor
-} from '@xstate/effect';
-
-class CheckoutActor extends Context.Service<
-  CheckoutActor,
-  EffectActor<typeof checkoutMachine>
->()('@app/CheckoutActor') {}
-
-const CheckoutActorLayer = Layer.effect(
-  CheckoutActor,
-  createEffectActor(checkoutMachine)
+export const result = await Effect.runPromise(
+  program.pipe(
+    Effect.scoped,
+    Effect.provideService(Deployments, {
+      // Replace this demo service with your deployment API.
+      deploy: (release) => Effect.succeed(`https://example.com/${release}`)
+    })
+  )
 );
+console.log(result); // 'https://example.com/v1.2.0'
 ```
 
-The Layer's requirements are the machine's requirements, so the services the machine needs are provided the same way as for any other Layer:
+The demo service runs locally. Replace it with your deployment API. The machine defines which events are valid in each state; Effect provides the deployment service and owns the actor's lifetime.
 
-```ts
-const AppLayer = CheckoutActorLayer.pipe(Layer.provide(PaymentsLayer));
-```
+Start Effect-backed logic with `createEffectActor` inside an Effect scope.
 
-At an edge that is not itself an Effect, build the Layer once with a `ManagedRuntime` and run individual Effects against it:
+<details>
+<summary>Runtime and cancellation details</summary>
 
-```ts
-const runtime = ManagedRuntime.make(AppLayer);
-
-const pay = runtime.runPromise(
-  Effect.gen(function* () {
-    const actor = yield* CheckoutActor;
-    yield* send(actor, { type: 'PAY' });
-    return yield* waitFor(actor, (s) => s.matches('paid'));
-  })
-);
+- `createEffectActor` runs pure XState transitions from an Effect fiber. Its mailbox processes events in order; timers use Effect's `Clock`.
+- Events are processed asynchronously. Read their outcomes with `waitFor`, `join` or `snapshots`.
+- Starting Effect-backed logic with XState's `createActor` produces an error because the Effect host is missing.
+- Leaving an invoking state interrupts its local Effect. It does not undo work already accepted by an external API; model cancellation or rollback explicitly when needed.
 
-// When the process shuts down:
-await runtime.dispose();
-```
+</details>
 
-`runtime.dispose()` closes the runtime's scope, which stops the actor and releases the Layers it was built from.
+## Guides
 
-### Clock
+| Guide | Examples |
+| --- | --- |
+| [Quick start](docs/quick-start.md) | Release approval, expiry, cancellation and retry. |
+| [Actors](docs/actors.md) | Share an actor through a Layer and ManagedRuntime. |
+| [Observing actors](docs/observing-actors.md) | Snapshot history, output and streamed reminders. |
+| [Matching states](docs/matching-states.md) | Exhaustive matching and per-state context. |
+| [Effect actor logic](docs/effect-logic.md) | Report tasks, upload progress and rollout health events. |
+| [Schemas and actions](docs/schemas-and-actions.md) | Runtime event validation and background audit entries. |
+| [Atoms and React](docs/atoms-and-react.md) | Registry ownership, approval controls and useSelector. |
+| [Testing and errors](docs/testing-and-errors.md) | TestClock, task retries, supervision and typed failures. |
 
-XState timers (`after` transitions and delayed events) use the Effect `Clock` service by default. In production this is the live clock. In tests, `TestClock` from `effect/testing` drives them:
+Runnable copies live in [examples/effect-workflows](../../examples/effect-workflows). Their tests verify the docs use the same code.
 
-```ts
-import { TestClock } from 'effect/testing';
+## Actors
 
-const program = Effect.gen(function* () {
-  const actor = yield* createEffectActor(machine);
-  yield* TestClock.adjust('5 seconds');
-  return actor.getSnapshot().value;
-});
+The actor stops and interrupts its hosted Effects when its enclosing scope closes. Use `Effect.scoped` for a bounded program, or `Layer.effect` to share an actor for an application's lifetime.
 
-await Effect.runPromise(
-  program.pipe(Effect.scoped, Effect.provide(TestClock.layer()))
-);
-```
+- Invoked Effect tasks and streams own their resources and release them on completion, failure or cancellation.
+- Background actions use the owning actor's scope.
+- Use `withActorScope` around resource acquisition to keep a resource until the owning actor stops.
 
-Timers are fibers in the actor's scope, so they are interrupted when the actor stops.
+Provide Layers outside the actor's scope, so services remain available during cleanup. Dispose a `ManagedRuntime` when its owner shuts down. See [actors](docs/actors.md).
 
 ### Requirements
 
-`RequirementsFrom<Logic>` is the `R` channel of `createEffectActor`. It collects the requirements of:
+`RequirementsFrom<TLogic>` collects services from declared Effect actions, declared actors and inline invocations, including child machines up to 10 levels deep. `createEffectActor` returns `Effect<EffectActor<TLogic>, never, R | Scope>`. Provided action and actor overrides update that service union. Actor and invocation scopes are supplied automatically.
 
-- actions registered with `setupEffect({ actions })`,
-- actors registered with `setup({ actors })` or `setupEffect({ actors })`,
-- logic used inline as `invoke.src`, at the root or in any state,
-- all of the above inside child machines, whether registered or invoked inline, up to 10 levels of machine nesting.
+<details>
+<summary>Requirement limits</summary>
 
-Past 10 levels the type stops recursing and contributes `never`, so requirements introduced deeper than that are not part of `R`. TypeScript then accepts a program that does not provide the service, and the actor fails at runtime when the missing service is requested. Flatten the machine tree, or provide those services explicitly, if a machine nests that deeply.
+Deeper requirements are not inferred. Provide them explicitly or flatten the machine tree. Inline spawned Effect logic is rejected; register it in `actors` before spawning it.
 
-`never` in the `R` channel means "no requirement collected", not "no failure possible". `createEffectActor` is typed `Effect<Actor, never, R | Scope>` and has no typed failures at all. Starting Effect-backed logic outside `createEffectActor`, spawning undeclared Effect logic, and using a service that was not collected are programming errors: they surface as the actor's `error` status, not as an Effect failure. Input rejected by a runtime `validator` is thrown while the actor is created, so `createEffectActor` dies with that error as a defect.
+The actor's later errors are observed through `join` or snapshots. Invalid input rejected during creation is a defect.
 
-Logic passed inline to `enq.spawn` lives inside a transition function body and is not visible to the type. Spawning inline Effect logic is therefore rejected at runtime; spawn a declared actor instead (`enq.spawn(args.actors.worker)`). See [Declared only](#declared-only).
+</details>
 
 ### Observing actors
 
 <!-- actor surface from src/actor.ts -->
 
-These are free functions that take any XState `ActorRef`, including the `EffectActor` handle, children read from `snapshot.children` and actors created outside this package. A bundler drops the ones a program does not import, and everything that already accepts an XState actor, such as `useSelector`, works on the same handle.
-
-| Function                                 | Returns                                                     |
-| ---------------------------------------- | ----------------------------------------------------------- |
-| `send(actor, event)`                     | `Effect<void>`                                              |
-| `snapshots(actor)`                       | `Stream<Snapshot>`: the current snapshot, then each change  |
-| `emitted(actor)`                         | `Stream<Emitted>`: events emitted with `emit`               |
-| `waitFor(actor, predicate)`              | `Effect<Snapshot, ActorStoppedError>`                       |
-| `waitFor(actor, predicate, { timeout })` | `Effect<Snapshot, ActorStoppedError \| Cause.TimeoutError>` |
-| `join(actor)`                            | `Effect<Output, ErrorFrom<Logic> \| ActorStoppedError>`     |
-| `inspect(actor)`                         | `Stream<InspectionEvent>`                                   |
-| `deadLetters(actor)`                     | `Stream<DeadLetterInspectionEvent>`                         |
-
-`send` and `waitFor` are dual: each takes the actor first, or returns a function of the actor so it can be piped.
+| Function | Use |
+| --- | --- |
+| `send` | Enqueue an event. |
+| `snapshots` | Stream the current snapshot and changes. |
+| `waitFor` | Await a snapshot predicate, optionally with a timeout. |
+| `join` | Await final output or failure. |
+| `emitted` | Stream notifications emitted by the actor. |
+| `inspect` | Stream system inspection events. |
+| `deadLetters` | Observe delivery failures. |
 
-```ts
-yield* send(actor, { type: 'PAY' });
-yield* pipe(actor, send({ type: 'PAY' }));
-```
-
-When `predicate` is a type predicate, `waitFor` narrows its result to the asserted snapshot type:
-
-```ts
-const snapshot = yield* waitFor(
-  actor,
-  (s): s is typeof s & { status: 'done' } => s.status === 'done'
-);
-```
-
-The `timeout` failure is Effect's `Cause.TimeoutError`, not the `TimeoutError` that `xstate` exports for its own delayed-transition errors.
-
-`snapshots` ends when the actor completes. If the actor errors, the stream emits the error snapshot and ends. `waitFor` and `join` fail with `ActorStoppedError` when the actor stops or errors before the awaited result; `join` fails with the actor's typed error when the actor's status is `error`.
-
-```ts
-const program = Effect.gen(function* () {
-  const actor = yield* createEffectActor(fetchUser, { input: { id: '42' } });
-  const user = yield* join(actor);
-  return user.id;
-});
-```
-
-`send` returns `Effect<void>` and never fails. It enqueues the event, like `actor.send(event)`, and XState reports an event it could not deliver as a **dead letter** with a reason: `'stopped'` for a send to a stopped actor, `'invalidEvent'` for a payload the target's schema rejects, and `'internalEvent'` for an internal event type sent from outside its owning actor. A failing `send` could not carry that reason, and a dead letter is not an actor error. Observe them instead:
-
-```ts
-const program = Effect.gen(function* () {
-  const actor = yield* createEffectActor(machine);
-  yield* Effect.forkScoped(
-    Stream.runForEach(deadLetters(actor), (event) =>
-      Effect.logWarning(`undelivered ${event.event.type}: ${event.reason}`)
-    )
-  );
-});
-```
+`send` and `waitFor` support direct and pipeable usage. See [complete observation examples](docs/observing-actors.md).
 
 ### Matching states
 
 <!-- tagged state view from src/state.ts -->
 
-`taggedState(snapshot)` views a machine snapshot as a member of a tagged union, so `Match.tag` and `Match.exhaustive` work on states. `_tag` is the state's dotted path, such as `'checkout.paying'`, and `context` is that state's context, including any per-state context schema declared in `setupEffect({ states })`. `TaggedState<typeof machine>` names the union.
-
-```ts
-import { Match, Stream } from 'effect';
-import { snapshots, taggedState, type TaggedState } from '@xstate/effect';
-
-const describe = Match.type<TaggedState<typeof checkoutMachine>>().pipe(
-  Match.tag('cart', ({ context }) => `${context.items.length} items`),
-  Match.tag('paying', ({ context }) => `paying ${context.paymentId}`),
-  Match.tag('done.paid', 'done.declined', ({ _tag }) => _tag),
-  Match.exhaustive
-);
-
-const labels = snapshots(actor).pipe(Stream.map(taggedState), Stream.map(describe));
-```
-
-A parallel state has no single path. Its tag stops at the parallel state, or is `'(machine)'` when the machine itself is parallel; match on `value` or `snapshot.matches` there. The `state` atom from `createActorAtoms` exposes the same view.
-
-## Atoms
-
-<!-- atom surface from src/atom.ts -->
-
-`@xstate/effect/atom` exposes an actor through `effect/unstable/reactivity`, so a reactive UI reads it the way it reads any other Effect state. `createActorAtoms(runtime, logic, options?)` takes an `Atom.runtime` whose Layer provides the logic's services and returns:
-
-| Atom        | Type                                                                            |
-| ----------- | ------------------------------------------------------------------------------- |
-| `actor`     | `Atom<AsyncResult<Actor>>`                                                      |
-| `snapshot`  | `Atom<AsyncResult<Snapshot>>`                                                   |
-| `result`    | `Atom<AsyncResult<Snapshot, ErrorFrom<Logic>>>`: a `Failure` once the actor errors. The runtime's own error type is also in every atom's error channel |
-| `send`      | `Writable<AsyncResult<void, NotReadyError>, Event>`: set it with an event; `NotReadyError` is exported from `@xstate/effect/atom` |
-| `select(f)` | `Atom<AsyncResult<T>>` derived from `snapshot`                                   |
-| `state`     | `Atom<AsyncResult<TaggedState>>`: the snapshot as a tagged union, see [Matching states](#matching-states) |
-
-```ts
-import { Effect, Layer } from 'effect';
-import { Atom, AtomRegistry, AsyncResult } from 'effect/unstable/reactivity';
-import { createActorAtoms } from '@xstate/effect/atom';
-
-const runtime = Atom.runtime(
-  Layer.succeed(Api, { fetchUser: (id: string) => Effect.succeed({ id }) })
-);
-const user = createActorAtoms(runtime, machine);
-const status = user.select((snapshot) => snapshot.value);
-
-const registry = AtomRegistry.make();
-registry.subscribe(
-  status,
-  (result) => {
-    if (AsyncResult.isSuccess(result)) {
-      console.log(result.value);
-    }
-  },
-  { immediate: true }
-);
-registry.set(user.send, { type: 'RETRY' });
-```
-
-The actor starts when one of its atoms is first read and stops when nothing reads or mounts them anymore. Results are `AsyncResult` values because the runtime's Layer builds asynchronously. `send` enqueues the event, like `actor.send`; setting it before the runtime is ready records a `NotReadyError` failure instead. `result` is `snapshot` with an errored actor reported as a `Failure`, for error boundaries. Wrap an atom with `Atom.keepAlive` to keep the actor for the registry's lifetime, or build the atoms inside `Atom.family` to get one actor per input.
-
-A runtime that does not provide a service the logic requires is a type error on the `runtime` argument.
-
-`effect/unstable/reactivity` is an unstable Effect module. This entry point follows it and may change independently of the rest of the package.
-
-## React
-
-`useMachine`, `useActor` and `useActorRef` call `createActor` internally, so they cannot start Effect-backed logic. In an Effect application the actor lives in the runtime and React reads it through atoms: `@xstate/effect/atom` builds them and `@effect/atom-react` provides the hooks.
-
-```tsx
-import { Suspense } from 'react';
-import { Atom } from 'effect/unstable/reactivity';
-import { useAtomSet, useAtomSuspense } from '@effect/atom-react';
-import { createActorAtoms } from '@xstate/effect/atom';
-
-const runtime = Atom.runtime(AppLayer);
-const checkout = createActorAtoms(runtime, checkoutMachine);
-const status = checkout.select((snapshot) => snapshot.value);
-
-function Checkout() {
-  const { value } = useAtomSuspense(status);
-  const send = useAtomSet(checkout.send);
-
-  return (
-    <button onClick={() => send({ type: 'PAY' })}>{String(value)}</button>
-  );
-}
-
-export function App() {
-  return (
-    <Suspense fallback={null}>
-      <Checkout />
-    </Suspense>
-  );
-}
-```
-
-`useAtomSuspense` suspends until the runtime and the actor are ready. `useAtomValue` returns the `AsyncResult` instead, for components that render their own loading state. The actor starts when the first component reads one of its atoms and stops when the last one unmounts. An owner component can hold it with `useAtomMount(checkout.actor)` while children read selectors; pin it with `Atom.keepAlive` when it must outlive the components.
-
-Without atoms, create the actor through a `ManagedRuntime` and read it with `useSelector` from `@xstate/react`, which takes an existing actor reference. `actor.send` works directly there.
+`taggedState(snapshot)` exposes `_tag`, `value`, `context` and `snapshot`. Use `TaggedState<typeof machine>` with Effect's `Match.tag` and `Match.exhaustive`. Per-state context narrows with the tag. See [matching states](docs/matching-states.md).
 
 ## Effect actor logic
 
 <!-- fromEffect, fromEffectStream, fromEffectEventStream from src/fromEffect.ts -->
 
-### `fromEffect`
+| Function | Behavior |
+| --- | --- |
+| `fromEffect` | Run a task; its success value is the actor's output. |
+| `fromEffectStream` | Expose the latest stream item as snapshot context. |
+| `fromEffectEventStream` | Relay stream items to the parent as events. |
 
-`fromEffect` accepts an Effect, a function that returns an Effect, or a config object:
+For example, a progress stream can feed an upload UI:
 
-```ts
-fromEffect(Effect.succeed('done'));
-
-fromEffect(({ input }: { input: string }) => Effect.succeed(input.length));
-
-fromEffect({
-  id: 'loadUser',
-  schemas: {
-    input: Schema.Struct({ id: Schema.String }),
-    output: Schema.Struct({ id: Schema.String })
-  },
-  effect: ({ input }) => Api.use((api) => api.fetchUser(input.id))
-});
-```
-
-The function form receives `{ input, self, system, emit }`. `emit` publishes an event that `actor.on(...)` and `emitted(actor)` observe. Either schema may be omitted; the missing type is inferred from the Effect.
-
-The actor's result maps from the Effect's exit:
-
-- Success: status `done` with the value as `output`.
-- Failure: status `error` with the `E` value as `error`. `invoke.onError` receives it typed through `ErrorFrom`.
-- Defect: status `error` with the squashed cause. Defects are not part of the typed error.
-- Interruption caused by the actor stopping or by the invoking state exiting: no error. The actor is stopped.
-- Interruption from inside the Effect, such as `Effect.interrupt`: status `error` with an `EffectInterruptedError`. An `Effect.timeout` is a failure with `Cause.TimeoutError`, not an interruption; a lost `Effect.race` inside the Effect interrupts only the loser and the actor completes with the winner.
-
-Use `Effect.timeout`, `Effect.retry` and the other Effect combinators inside the Effect. `fromEffect` does not add its own options for them.
-
-### `fromEffectStream`
-
-`fromEffectStream` exposes the latest stream item as the actor's `context` and reaches `done` when the stream completes. A stream failure puts the actor in the `error` status.
+<!-- example from examples/effect-workflows/src/latest-stream.ts -->
 
 ```ts
-fromEffectStream(Stream.make(1, 2, 3));
-
-fromEffectStream({
-  schemas: { input: Schema.Struct({ topic: Schema.String }) },
-  stream: ({ input }) => Stream.fromPubSub(topicPubSub(input.topic))
-});
-```
-
-### `fromEffectEventStream`
+import { Effect, Option, Stream } from 'effect';
+import { createEffectActor, fromEffectStream, snapshots } from '@xstate/effect';
 
-`fromEffectEventStream` relays each stream item to the parent machine as an event. It accepts the same forms as `fromEffectStream`.
+// Demo upload progress. Replace with your upload SDK's progress stream.
+const uploadProgress = fromEffectStream(Stream.make(0, 25, 60, 100));
 
-```ts
-const machine = createMachine({
-  context: { seen: 0 },
-  schemas: { events: { VALUE: types<{ value: number }>() } },
-  initial: 'active',
-  states: {
-    active: {
-      invoke: {
-        src: fromEffectEventStream(
-          Stream.make({ type: 'VALUE', value: 1 }, { type: 'VALUE', value: 2 })
-        )
-      },
-      on: {
-        VALUE: ({ context, event }) => ({
-          context: { seen: context.seen + event.value }
-        })
-      }
-    }
-  }
+const program = Effect.gen(function* () {
+  const actor = yield* createEffectActor(uploadProgress);
+  return yield* snapshots(actor).pipe(
+    Stream.filter((s) => s.context !== undefined),
+    Stream.map((s) => s.context),
+    Stream.runLast,
+    Effect.map(Option.getOrThrow)
+  );
 });
-```
-
-## Effect schemas
-
-<!-- schema conversion from src/schema.ts -->
 
-`setupEffect` accepts Effect schemas in its `schemas` and `states` options, and in `setupEffect(...).extend(...)`. XState infers the decoded `Schema.Type`; there is no need to call `Schema.toStandardSchemaV1`.
-
-```ts
-import { Effect, Schema } from 'effect';
-import { createEffectActor, setupEffect } from '@xstate/effect';
-
-const machine = setupEffect({
-  schemas: {
-    context: Schema.Struct({ count: Schema.Number }),
-    events: {
-      ADD: Schema.Struct({ value: Schema.Number })
-    }
-  }
-}).createMachine({
-  context: { count: 0 },
-  on: {
-    ADD: ({ context, event }) => ({
-      context: { count: context.count + event.value }
-    })
-  }
-});
+export const result = await Effect.runPromise(Effect.scoped(program));
+console.log(result); // 100
 ```
 
-Standard Schemas remain supported and can be mixed with Effect schemas. Schemas provide types without a `validator`; adding `standardSchemaValidator()` from `xstate/validation` enables runtime assertions.
-
-XState validation checks a value but does not replace it with a transformed value. When runtime validation is enabled, TypeScript rejects schemas whose encoded and decoded types differ, such as `Schema.NumberFromString`. Effect schemas used at this validation seam must decode synchronously and without service requirements.
-
-## Effect actions
-
-<!-- effect action contract from src/setupEffect.ts; spawn guard from src/internal.ts -->
-
-`setupEffect({ actions })` declares actions that return an Effect. An Effect action is fire-and-forget: the transition enqueues it, the transition commits, and the Effect then runs in the actor's Effect context without blocking the actor. It is interrupted when the actor stops. A failure or defect routes to the state's `onError`.
+See [Effect actor logic](docs/effect-logic.md) for tasks and a stream that drives rollout transitions.
 
-In XState v6 an action is a plain function that a transition enqueues with explicit arguments, `enq(args.actions.audit, args)`. `setupEffect` keeps that contract. The function is called synchronously during the transition, and the Effect it returns is the asynchronous boundary.
+## Schemas and actions
 
-```ts
-class Audit extends Context.Service<
-  Audit,
-  { readonly record: (count: number) => Effect.Effect<void> }
->()('@app/Audit') {}
-
-const machine = setupEffect({
-  actions: {
-    audit: ({ context }) => Audit.use((audit) => audit.record(context.count))
-  }
-}).createMachine({
-  context: { count: 1 },
-  initial: 'active',
-  states: {
-    active: {
-      on: {
-        AUDIT: (args, enq) => enq(args.actions.audit, args)
-      }
-    }
-  }
-});
-```
-
-Use Effect actions for work whose result the machine does not need: logging, telemetry, notifications, cache writes. When the result matters, invoke the Effect as an actor with `fromEffect`, so `onDone` and `onError` receive it typed and the state models the wait.
+<!-- schema conversion from src/schema.ts -->
 
-An Effect action cannot enqueue: it runs after the transition. Enqueue from the transition function, which has the machine's event types. To hand a result back to the machine from an Effect action, send an event to `self`:
-
-```ts
-const machine = setupEffect({
-  schemas: {
-    events: {
-      SAVE: Schema.Struct({}),
-      SYNCED: Schema.Struct({ version: Schema.Number })
-    }
-  },
-  actions: {
-    sync: ({ context, self }) =>
-      Effect.gen(function* () {
-        const version = yield* Api.use((api) => api.sync(context.draft));
-        yield* Effect.sync(() => self.send({ type: 'SYNCED', version }));
-      })
-  }
-}).createMachine({
-  context: { draft: '', version: 0 },
-  initial: 'active',
-  states: {
-    active: {
-      on: {
-        SAVE: (args, enq) => enq(args.actions.sync, args),
-        SYNCED: ({ context, event }) => ({
-          context: { ...context, version: event.version }
-        })
-      }
-    }
-  }
-});
-```
+`setupEffect` accepts Effect schemas for input, context, events, output and per-state context. Types are inferred without manual conversion. Add `standardSchemaValidator()` from `xstate/validation` for runtime checks.
 
 ### Declared only
 
-Anything that touches the Effect context must be a declared action or a declared actor. Only declared sources contribute to the actor's requirements, so an inline Effect infers `R = never` and fails at runtime when a service is missing. Declared actions also carry a name for inspection and `machine.provide` overrides.
-
-- Register Effect actions with `setupEffect({ actions })` and run them with `enq(args.actions.name, args)`.
-- Register spawned Effect logic with `setup({ actors })` or `setupEffect({ actors })` and spawn it with `enq.spawn(args.actors.name)`. Spawning inline Effect logic is an error at runtime.
-- Effect logic used inline as `invoke.src` runs and contributes to `RequirementsFrom`. Registering it in `actors` gives it a name.
-
-> **Warning:** An inline action that returns an Effect does not run it. `enq(() => Effect.log('saved'))` creates the Effect and discards it, because XState only awaits returned promises. Register the action with `setupEffect({ actions })` instead.
-
-Effect actions do not block the actor. The actor processes the next event while the Effect runs.
-
-## Persistence
-
-`actor.getPersistedSnapshot()` returns a serializable snapshot of the actor's state. It records state, not the progress of a running Effect. Restoring a snapshot into a new interpreter is not supported yet; the durable execution loop this package is built on is the intended path for that, and it is the next piece of work.
-
-## Testing
-
-Machines keep their normal test surface, and this package adds Effect-native ways to drive and observe them.
-
-Delays run on the Effect `Clock`, so `TestClock` advances `after` transitions and delayed sends without real time passing:
-
-```ts
-import { Effect } from 'effect';
-import { TestClock } from 'effect/testing';
-import { createEffectActor, waitFor } from '@xstate/effect';
-
-const test = Effect.gen(function* () {
-  const actor = yield* createEffectActor(machine);
-  yield* TestClock.adjust('30 seconds');
-  yield* waitFor(actor, (s) => s.matches('timedOut'));
-});
-
-await Effect.runPromise(
-  test.pipe(Effect.scoped, Effect.provide(TestClock.layer()))
-);
-```
-
-Assert with `waitFor` for a state the actor should reach, and with `join` for the actor's final output. Both fail rather than hang when the actor stops first, and `waitFor`'s `timeout` option bounds a test that would otherwise wait forever.
-
-Observe with `inspect` for every inspection event and `deadLetters` for events the system could not deliver. A test that ends with no dead letters confirms that every event it sent was accepted.
+<!-- effect action contract from src/setupEffect.ts; spawn guard from src/internal.ts -->
 
-Path generation in `xstate/graph` (`getShortestPaths`, `getSimplePaths`, `createTestModel`) operates on the machine, not on a running actor, so it works on an Effect-backed machine unchanged. Execute the generated paths against an actor from `createEffectActor`.
+- Register background Effect actions in `setupEffect({ actions })`; enqueue them with explicit arguments.
+- Invoke `fromEffect` logic when the machine needs to wait for a result.
+- Register spawned Effect logic in `actors`, then use `enq.spawn(args.actors.worker)`.
 
-## Retries and supervision
+See [schemas and actions](docs/schemas-and-actions.md) for a complete audit example, runtime schema constraints and inline-source pitfalls.
 
-`createEffectActor` is an ordinary scoped Effect, so Effect's retry combinators supervise an actor. Wrap the actor and the work that depends on it in `Effect.scoped`, then retry that unit: each attempt builds a fresh actor and the failed attempt's actor is stopped when its scope closes.
+## Atoms and React
 
-```ts
-import { Effect, Schedule } from 'effect';
-import { createEffectActor, join } from '@xstate/effect';
+<!-- atom surface from src/atom.ts -->
 
-const program = Effect.gen(function* () {
-  const actor = yield* createEffectActor(machine);
-  return yield* join(actor);
-});
+`createActorAtoms` from `@xstate/effect/atom` exposes `actor`, `snapshot`, `result`, `send`, `select` and `state`. Its `Atom.runtime` must provide the logic's services. Pass `{ input }` when the logic requires input; missing or mismatched input is a type error.
 
-const supervised = Effect.retry(Effect.scoped(program), {
-  schedule: Schedule.exponential('100 millis'),
-  times: 3
-});
-```
+- Read atoms with `@effect/atom-react` in React, or an `AtomRegistry` elsewhere.
+- The registry owns their lifetime; dispose it when its owner shuts down.
+- `useSelector` from `@xstate/react` can also read an existing `EffectActor` directly.
 
-`join` fails with the machine's typed error, so the schedule sees the actual failure. Retrying `program` without `Effect.scoped` would reuse the outer scope and leak the actors from failed attempts until that scope closes.
+See [atoms and React](docs/atoms-and-react.md) for complete examples with imports, runtime setup and cleanup.
 
-## Errors
+## Testing and errors
 
 <!-- error types from src/errors.ts; timeout failure from src/actor.ts -->
 
-| Error                    | Raised by                                                                                      | Fields                                           |
-| ------------------------ | ---------------------------------------------------------------------------------------------- | ------------------------------------------------ |
-| `ActorStoppedError`      | `waitFor`, `join` when the actor stops or errors before the awaited result                     | `actorId: string`, `snapshot: Snapshot<unknown>` |
-| `EffectInterruptedError` | Effect logic interrupted from inside, such as `Effect.interrupt`, reported as `snapshot.error` | `cause: Cause.Cause<never>`                      |
-| `Cause.TimeoutError`     | `waitFor` with `{ timeout }` when no snapshot matches in time                                  | Effect's own error; `_tag: 'TimeoutError'`       |
-
-Both package errors are `Data.TaggedError` classes, so `Effect.catchTag('ActorStoppedError', …)` matches them.
-
-The actor's own failures are not in this table. A `fromEffect` actor reports the Effect's `E` value as `snapshot.error`, typed through `ErrorFrom`, which this package re-exports from `xstate`.
+- Use `TestClock` to drive deadlines without waiting for real time.
+- `ActorStoppedError` reports a stop before an awaited result.
+- `EffectInterruptedError` reports self-interruption inside Effect logic.
+- Timed waits fail with Effect's `Cause.TimeoutError`.
+- `join` preserves a task's typed failure. Unexpected machine errors have type `unknown`.
 
-A root actor that errors does not throw globally the way `createActor(...).start()` does. Its error is a value: read it with `join`, `waitFor`, the `result` atom, or `subscribe`. An errored actor nobody observes is silent, like a failed forked fiber.
+See [testing and errors](docs/testing-and-errors.md) for executable deadline, retry and failure examples. Persisted snapshots record actor state; restoration into a new Effect interpreter is not supported yet.
 
 ## Tracing
 
 <!-- span names and attributes from src/internal.ts and src/fromEffect.ts -->
 
-Every Effect the actor hosts runs inside a span:
-
-| Span                    | Covers                                   |
-| ----------------------- | ---------------------------------------- |
-| `fromEffect`            | a `fromEffect` actor's Effect            |
-| `fromEffectStream`      | a `fromEffectStream` actor's stream      |
-| `fromEffectEventStream` | a `fromEffectEventStream` actor's stream |
-| `action.<name>`         | an Effect action registered as `<name>`  |
-
-Each span carries the attributes `xstate.actor.id` and `xstate.actor.address`. `id` is the actor's own name. `address` is its `/`-joined path of ids from the root actor, which is stable across persistence and restore, so it identifies the same logical actor across runs.
-
-Spans are recorded only when a `Tracer` is provided. Without one they cost nothing and export nothing.
+Hosted work uses spans named `fromEffect`, `fromEffectStream`, `fromEffectEventStream` and `action.<name>`. Each carries `xstate.actor.id` and `xstate.actor.address`. Provide a `Tracer` to record and export them.

package/dist/declarations/src/actor.d.ts

@@ -1,5 +1,5 @@
 import { Cause, Duration, Effect, Stream } from 'effect';
-import type { Actor, ActorRef, AnyActorRef, AnyEventObject, DeadLetterInspectionEvent, EmittedFrom, ErrorFrom, InspectionEvent, OutputFrom, SnapshotFrom } from 'xstate';
+import type { Actor, ActorRef, AnyActorRef, AnyEventObject, EmittedFrom, EventRejection, ErrorFrom, InspectionEvent, OutputFrom, SnapshotFrom } from 'xstate';
 import type { EffectActor } from "./effectActor.js";
 import { ActorStoppedError } from "./errors.js";
 /** The event type accepted by an actor's `send` method. */
@@ -68,9 +68,10 @@ export declare function join<TActor extends AnyActorRef>(actor: TActor): Effect.
  */
 export declare function inspect(actor: AnyActorRef): Stream.Stream<InspectionEvent>;
 /**
- * Streams the events the actor's system could not deliver: sends to a
- * stopped actor, invalid external events and internal events sent from
- * outside their owner. A dead letter is not an actor error. The stream runs
- * until it is interrupted or its scope closes.
+ * Streams the events the actor's system could not deliver, as reported by
+ * `system.onRejectedEvent`: sends to a stopped actor, invalid external
+ * events and internal events sent from outside their owner. A dead letter is
+ * not an actor error. The stream runs until it is interrupted or its scope
+ * closes.
  */
-export declare function deadLetters(actor: AnyActorRef): Stream.Stream<DeadLetterInspectionEvent>;
+export declare function deadLetters(actor: AnyActorRef): Stream.Stream<EventRejection>;

package/dist/declarations/src/actorScope.d.ts

@@ -0,0 +1,11 @@
+import { Context, Effect, Scope } from 'effect';
+declare const ActorScope_base: Context.ServiceClass<ActorScope, "@xstate/effect/ActorScope", Scope.Scope>;
+/** The owning Effect actor's scope, supplied by `createEffectActor`. */
+export declare class ActorScope extends ActorScope_base {
+}
+/**
+ * Acquires resources in the owning actor's scope. Their finalizers run when
+ * that actor stops, even if the invoking task finishes or is cancelled first.
+ */
+export declare function withActorScope<A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, Exclude<R, Scope.Scope> | ActorScope>;
+export {};

package/dist/declarations/src/atom.d.ts

@@ -1,6 +1,6 @@
 import { AsyncResult, Atom } from 'effect/unstable/reactivity';
 import type { AnyActorLogic, ErrorFrom, EventFromLogic, SnapshotFrom } from 'xstate';
-import { type EffectActorOptions } from "./createEffectActor.js";
+import { type EffectActorOptionsArgs } from "./createEffectActor.js";
 import type { EffectActor } from "./effectActor.js";
 import { NotReadyError } from "./errors.js";
 import { type TaggedStateFrom } from "./state.js";
@@ -45,7 +45,8 @@ interface MissingRequirements<T> {
 /**
  * Creates atoms for an actor that runs in an `Atom.runtime`. The runtime's
  * Layer must provide every service the logic requires; a missing service is
- * a type error on the `runtime` argument.
+ * a type error on the `runtime` argument. Logic with required input also
+ * requires an options object containing that input.
  *
  * The actor is created with `createEffectActor` inside the `actor` atom's
  * scope, so its lifetime follows the atom: it starts on first read and stops
@@ -53,4 +54,4 @@ interface MissingRequirements<T> {
  * actor for the registry's lifetime, or with `Atom.family` to create one
  * actor per input.
  */
-export declare function createActorAtoms<TLogic extends AnyActorLogic, R, ER = never>(runtime: Atom.AtomRuntime<R, ER> & ([RequirementsFrom<TLogic>] extends [R] ? unknown : MissingRequirements<Exclude<RequirementsFrom<TLogic>, R>>), logic: TLogic, options?: EffectActorOptions<TLogic>): ActorAtoms<TLogic, ER>;
+export declare function createActorAtoms<TLogic extends AnyActorLogic, R, ER = never>(runtime: Atom.AtomRuntime<R, ER> & ([RequirementsFrom<TLogic>] extends [R] ? unknown : MissingRequirements<Exclude<RequirementsFrom<TLogic>, R>>), logic: TLogic, ...[options]: EffectActorOptionsArgs<TLogic>): ActorAtoms<TLogic, ER>;

package/dist/declarations/src/createEffectActor.d.ts

@@ -3,15 +3,12 @@ import { type AnyActorLogic, type InputFrom } from 'xstate';
 import { EffectActor } from "./effectActor.js";
 import type { RequirementsFrom } from "./types.js";
 /** Options for {@link createEffectActor}. */
-export interface EffectActorOptions<TLogic extends AnyActorLogic> {
-    /** The actor's input. */
+export type EffectActorOptions<TLogic extends AnyActorLogic> = undefined extends InputFrom<TLogic> ? {
     readonly input?: InputFrom<TLogic>;
-}
-type RequiredInput<TLogic extends AnyActorLogic> = undefined extends InputFrom<TLogic> ? {
-    input?: InputFrom<TLogic>;
 } : {
-    input: InputFrom<TLogic>;
+    readonly input: InputFrom<TLogic>;
 };
+export type EffectActorOptionsArgs<TLogic extends AnyActorLogic> = undefined extends InputFrom<TLogic> ? [options?: EffectActorOptions<TLogic>] : [options: EffectActorOptions<TLogic>];
 /**
  * Creates and starts an actor as an Effect interpreter over pure transitions.
  *
@@ -26,5 +23,4 @@ type RequiredInput<TLogic extends AnyActorLogic> = undefined extends InputFrom<T
  * interrupted, when the enclosing `Scope` closes. The returned Effect never
  * fails; the actor's own outcome is its snapshot status, read with `join`.
  */
-export declare function createEffectActor<TLogic extends AnyActorLogic>(logic: TLogic, ...[options]: undefined extends InputFrom<TLogic> ? [options?: EffectActorOptions<TLogic>] : [options: EffectActorOptions<TLogic> & RequiredInput<TLogic>]): Effect.Effect<EffectActor<TLogic>, never, RequirementsFrom<TLogic> | Scope.Scope>;
-export {};
+export declare function createEffectActor<TLogic extends AnyActorLogic>(logic: TLogic, ...[options]: EffectActorOptionsArgs<TLogic>): Effect.Effect<EffectActor<TLogic>, never, RequirementsFrom<TLogic> | Scope.Scope>;

package/dist/declarations/src/effectActor.d.ts

@@ -48,7 +48,7 @@ export declare class EffectActor<TLogic extends AnyActorLogic> implements ActorR
     })) => void): Subscription;
     /**
      * Observes the inspection events of this actor and its children: every
-     * transition, event delivery and dead letter of the execution.
+     * actor creation and transition of the execution.
      */
     inspect(observer: Observer<InspectionEvent> | ((event: InspectionEvent) => void)): Subscription;
     [symbolObservable](): this;

package/dist/declarations/src/fromEffect.d.ts

@@ -101,6 +101,9 @@ export type EffectStreamActorLogic<TItem, TError, TInput, TRequirements> = Actor
  * an Effect, a function of {@link EffectSourceArgs} returning one, or a config
  * object with `id`, `schemas`, `validator` and `effect`. The logic must be run
  * under `createEffectActor`, which provides the Effect services it declares.
+ * Resources belong to this task's scope and close on completion, failure or
+ * interruption. Use `withActorScope` to retain a resource until the owning
+ * Effect actor stops.
  */
 export declare function fromEffect<const TInputSchema extends EffectSchemaLike, const TOutputSchema extends EffectSchemaLike, TError = unknown, TRequirements = never>(config: Omit<EffectSourceConfig<SchemaOutput<TOutputSchema>, TError, SchemaOutput<TInputSchema>, TRequirements>, 'schemas' | 'validator'> & EffectSchemaValidationConfig<{
     input: TInputSchema;
@@ -147,7 +150,8 @@ type StreamRequirements<T> = T extends Stream.Stream<any, any, infer R> ? R : ne
  * the actor's `context`. The actor reaches `done` when the stream completes
  * and `error` when it fails. Accepts a Stream, a function of
  * {@link EffectSourceArgs} returning one, or a config object with `id`,
- * `schemas`, `validator` and `stream`.
+ * `schemas`, `validator` and `stream`. Its resources close when the stream
+ * completes, fails or is interrupted.
  */
 export declare function fromEffectStream<const TInputSchema extends EffectSchemaLike, TStream extends Stream.Stream<any, any, any>>(config: Omit<EffectStreamConfig<StreamItem<TStream>, StreamError<TStream>, SchemaOutput<TInputSchema>, StreamRequirements<TStream>>, 'stream' | 'schemas' | 'validator'> & EffectSchemaValidationConfig<{
     input: TInputSchema;
@@ -162,7 +166,8 @@ export declare function fromEffectStream<TItem, TError = unknown, TInput = undef
  * Creates actor logic that runs a Stream of events and relays each item to the
  * parent machine as an event, the way `fromEventObservable` does. The actor
  * has no output: it reaches `done` when the stream completes and `error` when
- * it fails. Accepts the same forms as `fromEffectStream`.
+ * it fails. Accepts the same forms as `fromEffectStream`. Its resources close
+ * when the stream completes, fails or is interrupted.
  */
 export declare function fromEffectEventStream<const TInputSchema extends EffectSchemaLike, TStream extends Stream.Stream<EventObject, any, any>>(config: Omit<EffectStreamConfig<StreamItem<TStream>, StreamError<TStream>, SchemaOutput<TInputSchema>, StreamRequirements<TStream>>, 'stream' | 'schemas' | 'validator'> & EffectSchemaValidationConfig<{
     input: TInputSchema;

package/dist/declarations/src/index.d.ts

@@ -1,6 +1,7 @@
 export { fromEffect, fromEffectEventStream, fromEffectStream, type EffectActorLogic, type EffectLogicBrand, type EffectSnapshot, type EffectSource, type EffectSourceArgs, type EffectStreamSource, type EffectStreamActorLogic, type EffectStreamSnapshot } from "./fromEffect.js";
 export { createEffectActor, type EffectActorOptions } from "./createEffectActor.js";
 export { EffectActor } from "./effectActor.js";
+export { ActorScope, withActorScope } from "./actorScope.js";
 export { deadLetters, emitted, inspect, join, send, snapshots, waitFor, type EmittedEventFrom, type SendableEventFrom, type WaitForOptions } from "./actor.js";
 export { ActorStoppedError, EffectInterruptedError } from "./errors.js";
 export { setupEffect, type EffectAction, type EffectActionArgs, type EffectSetupReturn } from "./setupEffect.js";

package/dist/declarations/src/types.d.ts

@@ -1,6 +1,7 @@
-import type { Effect } from 'effect';
+import type { Effect, Scope } from 'effect';
 import type { EffectLogicBrand } from "./fromEffect.js";
 import { effectActionBrand } from "./brands.js";
+import type { ActorScope } from "./actorScope.js";
 /** The `R` channel of an Effect type, or `never` for anything else. */
 export type EffectRequirements<T> = T extends Effect.Effect<any, any, infer R> ? R : never;
 type RequirementsFromActions<T> = T extends Record<string, (...args: any[]) => any> ? T[keyof T] extends infer TAction ? TAction extends {
@@ -38,15 +39,16 @@ type RequirementsFromStateSchema<TSchema, TDepth extends Depth> = (TSchema exten
 /**
  * Collects the Effect service requirements of an actor logic.
  *
- * For Effect logic this is the logic's own `R`. For a state machine it is the
+ * Actor and invocation scopes are supplied by the host and excluded here.
+ * For Effect logic this is the remaining `R`. For a state machine it is the
  * union of the requirements of its registered Effect actions, its registered
  * Effect actors, the Effect logic passed inline as `invoke.src` anywhere in
  * its state tree, and — recursively — the requirements of any child machine
  * reached either way (capped at {@link MaxDepth} levels of machine nesting).
  */
-export type RequirementsFrom<T, TDepth extends Depth = MaxDepth> = T extends EffectLogicBrand<any, infer R> ? R : T extends {
+export type RequirementsFrom<T, TDepth extends Depth = MaxDepth> = T extends EffectLogicBrand<any, infer R> ? Exclude<R, ActorScope | Scope.Scope> : T extends {
     readonly _actionMap: infer TActionMap;
     readonly _actorMap: infer TActorMap;
     readonly _stateSchema: infer TStateSchema;
-} ? RequirementsFromActions<TActionMap> | ([TDepth] extends [0] ? never : RequirementsFromActors<TActorMap, PrevDepth[TDepth]> | RequirementsFromStateSchema<TStateSchema, PrevDepth[TDepth]>) : never;
+} ? Exclude<RequirementsFromActions<TActionMap>, ActorScope | Scope.Scope> | ([TDepth] extends [0] ? never : RequirementsFromActors<TActorMap, PrevDepth[TDepth]> | RequirementsFromStateSchema<TStateSchema, PrevDepth[TDepth]>) : never;
 export {};

package/dist/{state-9a718be3.js → state-14a1fecf.js}

@@ -1,4 +1,4 @@
-import { Queue, Effect, Scope, Exit, Cause, Context, Fiber, Duration, Data } from 'effect';
+import { Queue, Effect, Fiber, Scope, Exit, Cause, Context, Duration, Data } from 'effect';
 import { stopActor, terminateActor, deliverEvent } from 'xstate';
 import { createDurable } from 'xstate/durable';
 
@@ -130,7 +130,7 @@ class EffectActor {
 
   /**
    * Observes the inspection events of this actor and its children: every
-   * transition, event delivery and dead letter of the execution.
+   * actor creation and transition of the execution.
    */
   inspect(observer) {
     const handler = typeof observer === 'function' ? observer : event => observer.next?.(event);
@@ -216,7 +216,8 @@ function createEffectHost(context, scope) {
     context,
     scope,
     interruptors: new Map(),
-    subscriptions: new Map()
+    subscriptions: new Map(),
+    fibers: new Set()
   };
 }
 function bindEffectHost(target, host) {
@@ -311,9 +312,8 @@ function trackEffect(actor, host, interrupt) {
  * the actor stops or when the returned function is called; `onExit` is not
  * called after that.
  *
- * This mirrors how Effect's own `unstable/reactivity` bridges callback code:
- * `Effect.runCallbackWith` with the captured services, and a synchronous
- * interruptor kept per actor.
+ * The fiber belongs to the host scope, so closing the owning actor also
+ * waits for asynchronous invocation finalizers.
  */
 function startHostedEffect(actor, effect, spanName, onExit) {
   const host = requireEffectHost(actor);
@@ -334,15 +334,17 @@ function startHostedEffect(actor, effect, spanName, onExit) {
     untrackEffect(actor, host, cancel);
     interrupt();
   };
-  const interrupt = Effect.runCallbackWith(host.context)(traced, {
-    onExit: exit => {
-      if (!active) {
-        return;
-      }
-      active = false;
-      untrackEffect(actor, host, cancel);
-      onExit(exit);
+  const fiber = Fiber.runIn(Effect.runForkWith(host.context)(traced), host.scope);
+  const interrupt = () => fiber.interruptUnsafe();
+  host.fibers.add(fiber);
+  fiber.addObserver(exit => {
+    host.fibers.delete(fiber);
+    if (!active) {
+      return;
     }
+    active = false;
+    untrackEffect(actor, host, cancel);
+    onExit(exit);
   });
   if (active) {
     trackEffect(actor, host, cancel);
@@ -370,10 +372,13 @@ function runHostedEffect(actor, effect, spanName) {
 }
 
 /**
- * Closes the host scope immediately and runs its finalizers, with the host's
- * services, on a fiber that `createEffectActor`'s release can await.
+ * Finishes hosted task cleanup before closing the owning actor's resources.
+ * `createEffectActor`'s release awaits this fiber before its parent scope closes.
  */
 function closeEffectHost(host) {
+  if (host.closing) {
+    return;
+  }
   for (const [actor, interruptors] of host.interruptors) {
     host.interruptors.delete(actor);
     for (const interrupt of interruptors) {
@@ -382,10 +387,10 @@ function closeEffectHost(host) {
     host.subscriptions.get(actor)?.unsubscribe();
     host.subscriptions.delete(actor);
   }
-  const finalizers = Scope.closeUnsafe(host.scope, Exit.void);
-  if (finalizers) {
-    host.closing = Effect.runForkWith(host.context)(finalizers);
-  }
+  host.closing = Effect.runForkWith(host.context)(Effect.forEach([...host.fibers], fiber => Fiber.interrupt(fiber), {
+    concurrency: 'unbounded',
+    discard: true
+  }).pipe(Effect.andThen(Scope.close(host.scope, Exit.void))));
 }
 
 /**
@@ -399,6 +404,17 @@ function relayToParent(actor, event) {
   }
 }
 
+/** The owning Effect actor's scope, supplied by `createEffectActor`. */
+class ActorScope extends Context.Service()('@xstate/effect/ActorScope') {}
+
+/**
+ * Acquires resources in the owning actor's scope. Their finalizers run when
+ * that actor stops, even if the invoking task finishes or is cancelled first.
+ */
+function withActorScope(effect) {
+  return ActorScope.use(scope => Scope.provide(effect, scope));
+}
+
 const XSTATE_TIMER = 'xstate.timer';
 
 /** Options for {@link createEffectActor}. */
@@ -422,7 +438,7 @@ function createEffectActor(logic, ...[options]) {
     const parentScope = yield* Effect.scope;
     const actorScope = yield* Scope.fork(parentScope);
     const baseContext = yield* Effect.context();
-    const context = Context.add(baseContext, Scope.Scope, actorScope);
+    const context = Context.add(Context.add(baseContext, Scope.Scope, actorScope), ActorScope, actorScope);
     const host = createEffectHost(context, actorScope);
     const runFork = Effect.runForkWith(context);
     const runPromise = Effect.runPromiseWith(context);
@@ -730,4 +746,4 @@ function taggedState(snapshot) {
   };
 }
 
-export { ActorStoppedError as A, EffectInterruptedError as E, NotReadyError as N, runHostedEffect as a, EffectActor as b, createEffectActor as c, relayToParent as r, startHostedEffect as s, taggedState as t };
+export { ActorStoppedError as A, EffectInterruptedError as E, NotReadyError as N, runHostedEffect as a, EffectActor as b, createEffectActor as c, ActorScope as d, relayToParent as r, startHostedEffect as s, taggedState as t, withActorScope as w };

package/dist/xstate-effect-atom.js

@@ -1,7 +1,7 @@
 import { Cause } from 'effect';
 import { Atom, AsyncResult } from 'effect/unstable/reactivity';
-import { c as createEffectActor, N as NotReadyError, t as taggedState } from './state-9a718be3.js';
-export { N as NotReadyError } from './state-9a718be3.js';
+import { c as createEffectActor, N as NotReadyError, t as taggedState } from './state-14a1fecf.js';
+export { N as NotReadyError } from './state-14a1fecf.js';
 import 'xstate';
 import 'xstate/durable';
 
@@ -14,7 +14,8 @@ import 'xstate/durable';
 /**
  * Creates atoms for an actor that runs in an `Atom.runtime`. The runtime's
  * Layer must provide every service the logic requires; a missing service is
- * a type error on the `runtime` argument.
+ * a type error on the `runtime` argument. Logic with required input also
+ * requires an options object containing that input.
  *
  * The actor is created with `createEffectActor` inside the `actor` atom's
  * scope, so its lifetime follows the atom: it starts on first read and stops
@@ -22,7 +23,7 @@ import 'xstate/durable';
  * actor for the registry's lifetime, or with `Atom.family` to create one
  * actor per input.
  */
-function createActorAtoms(runtime, logic, options) {
+function createActorAtoms(runtime, logic, ...[options]) {
   const host = runtime;
   const actor = host.atom(createEffectActor(logic, options));
   const snapshot = Atom.make(get => {

package/dist/xstate-effect.js

@@ -1,7 +1,7 @@
 import { Schema, Effect, Stream, Exit, Cause, Queue } from 'effect';
 import { createLogic, setup } from 'xstate';
-import { s as startHostedEffect, r as relayToParent, E as EffectInterruptedError, A as ActorStoppedError, a as runHostedEffect } from './state-9a718be3.js';
-export { A as ActorStoppedError, b as EffectActor, E as EffectInterruptedError, c as createEffectActor, t as taggedState } from './state-9a718be3.js';
+import { s as startHostedEffect, r as relayToParent, E as EffectInterruptedError, A as ActorStoppedError, a as runHostedEffect } from './state-14a1fecf.js';
+export { d as ActorScope, A as ActorStoppedError, b as EffectActor, E as EffectInterruptedError, c as createEffectActor, t as taggedState, w as withActorScope } from './state-14a1fecf.js';
 import { dual } from 'effect/Function';
 import 'xstate/durable';
 
@@ -169,6 +169,9 @@ function brandLogic(logic, error, requirements) {
  * an Effect, a function of {@link EffectSourceArgs} returning one, or a config
  * object with `id`, `schemas`, `validator` and `effect`. The logic must be run
  * under `createEffectActor`, which provides the Effect services it declares.
+ * Resources belong to this task's scope and close on completion, failure or
+ * interruption. Use `withActorScope` to retain a resource until the owning
+ * Effect actor stops.
  */
 
 function fromEffect(sourceOrConfig) {
@@ -213,7 +216,7 @@ function fromEffect(sourceOrConfig) {
         return;
       }
       const effect = typeof source === 'function' ? source(createSourceArgs(input, self, system)) : source;
-      enq.effect(() => startHostedEffect(self, effect, 'fromEffect', exit => {
+      enq.effect(() => startHostedEffect(self, Effect.scoped(effect), 'fromEffect', exit => {
         if (self.getSnapshot().status !== 'active') {
           return;
         }
@@ -256,7 +259,8 @@ function toLogicSchemas(schemas) {
  * the actor's `context`. The actor reaches `done` when the stream completes
  * and `error` when it fails. Accepts a Stream, a function of
  * {@link EffectSourceArgs} returning one, or a config object with `id`,
- * `schemas`, `validator` and `stream`.
+ * `schemas`, `validator` and `stream`. Its resources close when the stream
+ * completes, fails or is interrupted.
  */
 
 function fromEffectStream(sourceOrConfig) {
@@ -303,7 +307,7 @@ function fromEffectStream(sourceOrConfig) {
           });
         }
       }));
-      enq.effect(() => startHostedEffect(self, consume, 'fromEffectStream', exit => {
+      enq.effect(() => startHostedEffect(self, Effect.scoped(consume), 'fromEffectStream', exit => {
         if (self.getSnapshot().status !== 'active') {
           return;
         }
@@ -327,7 +331,8 @@ function fromEffectStream(sourceOrConfig) {
  * Creates actor logic that runs a Stream of events and relays each item to the
  * parent machine as an event, the way `fromEventObservable` does. The actor
  * has no output: it reaches `done` when the stream completes and `error` when
- * it fails. Accepts the same forms as `fromEffectStream`.
+ * it fails. Accepts the same forms as `fromEffectStream`. Its resources close
+ * when the stream completes, fails or is interrupted.
  */
 
 function fromEffectEventStream(sourceOrConfig) {
@@ -362,7 +367,7 @@ function fromEffectEventStream(sourceOrConfig) {
       }
       const streamValue = typeof stream === 'function' ? stream(createSourceArgs(input, self, system)) : stream;
       const consume = Stream.runForEach(streamValue, value => Effect.sync(() => relayToParent(self, value)));
-      enq.effect(() => startHostedEffect(self, consume, 'fromEffectEventStream', exit => {
+      enq.effect(() => startHostedEffect(self, Effect.scoped(consume), 'fromEffectEventStream', exit => {
         if (self.getSnapshot().status !== 'active') {
           return;
         }
@@ -608,13 +613,18 @@ function inspect(actor) {
 }
 
 /**
- * Streams the events the actor's system could not deliver: sends to a
- * stopped actor, invalid external events and internal events sent from
- * outside their owner. A dead letter is not an actor error. The stream runs
- * until it is interrupted or its scope closes.
+ * Streams the events the actor's system could not deliver, as reported by
+ * `system.onRejectedEvent`: sends to a stopped actor, invalid external
+ * events and internal events sent from outside their owner. A dead letter is
+ * not an actor error. The stream runs until it is interrupted or its scope
+ * closes.
  */
 function deadLetters(actor) {
-  return Stream.filter(inspect(actor), event => event.type === '@xstate.deadletter');
+  return Stream.callback(queue => Effect.acquireRelease(Effect.sync(() => actor.system.onRejectedEvent(rejection => {
+    Queue.offerUnsafe(queue, rejection);
+  })), subscription => Effect.sync(() => {
+    subscription.unsubscribe();
+  })));
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xstate/effect",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.5",
   "type": "module",
   "description": "Effect integration for XState",
   "keywords": [
@@ -30,11 +30,11 @@
   },
   "peerDependencies": {
     "effect": "^4.0.0-rc.115",
-    "xstate": "^6.0.0-alpha.58"
+    "xstate": "^6.0.0-alpha.62"
   },
   "devDependencies": {
     "effect": "4.0.0-rc.115",
-    "xstate": "^6.0.0-alpha.58"
+    "xstate": "^6.0.0-alpha.62"
   },
   "preconstruct": {
     "entrypoints": [