@xstate/effect 1.0.0-alpha.9 → 1.0.0-beta.0

package/README.md

@@ -7,18 +7,20 @@ Combine XState's event-driven workflows with Effect services, scopes, clocks and
 - 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.
+This package is experimental. It targets XState v6 beta and Effect 4.
 
 In these docs, "transition effects" are the executable effect descriptors (`ExecutableEffect`) that an XState transition returns. "Effect" means an Effect.ts program.
 
 ## Installation
 
-<!-- package name and peer dependencies from package.json -->
+<!-- package name, zero direct runtime dependencies and required versus optional peers from package.json -->
 
 ```bash
-npm install @xstate/effect@alpha xstate@alpha effect@^4
+npm install @xstate/effect@beta xstate@beta effect@^4
 ```
 
+`@xstate/effect` has zero direct runtime dependencies. Effect and XState are its only required peers. Lint tooling is opt-in and installed as development dependencies.
+
 ## XState Effect: Quick start
 
 <!-- public API from src/index.ts; actor lifetime from src/createEffectActor.ts -->
@@ -123,6 +125,10 @@ Start Effect-backed logic with `createEffectActor` inside an Effect scope.
 
 </details>
 
+<!-- declared Effect action typing from src/setupEffect.ts -->
+
+Declared Effect actions infer context and event types from `setupEffect({ schemas })`, including schemas inherited through `extend`. See [Action argument types](docs/schemas-and-actions.md#action-argument-types) for custom arguments and safe defaults.
+
 ## Guides
 
 | Guide | Examples |
@@ -185,7 +191,7 @@ The actor's later errors are observed through `join` or snapshots. Invalid input
 
 ## Effect actor logic
 
-<!-- createEffectLogic, createEffectStreamLogic, createEffectEventStreamLogic from src/createEffectLogic.ts -->
+<!-- createEffectLogic, createEffectStreamLogic, createEffectEventStreamLogic from src/effectLogic.ts -->
 
 | Function | Behavior |
 | --- | --- |
@@ -240,11 +246,15 @@ See [Effect actor logic](docs/effect-logic.md) for tasks and a stream that drive
 
 See [schemas and actions](docs/schemas-and-actions.md) for a complete audit example, runtime schema constraints and inline-source pitfalls.
 
+<!-- lint plugin export from package.json; rule from src/oxlint.ts -->
+
+Enable `xstate-effect/no-inline-effect` with the compiled `@xstate/effect/oxlint` plugin to catch discarded inline Effects and unsupported inline spawned Effect logic. See [Oxlint configuration](docs/schemas-and-actions.md#declared-sources) for installation and the rule's syntactic limits.
+
 ## Atoms and React
 
 <!-- atom surface from src/atom.ts -->
 
-`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.
+`createActorAtoms` from `@xstate/effect/atom` exposes `actor`, `snapshot`, `result`, `send` and `select`. Machine logic also exposes `state`; tasks and streams do not. Its `Atom.runtime` must provide the logic's services. Pass `{ input }` when the logic requires input; missing or mismatched input is a type error.
 
 - Read atoms with `@effect/atom-react` in React, or an `AtomRegistry` elsewhere.
 - The registry owns their lifetime; dispose it when its owner shuts down.
@@ -256,16 +266,17 @@ See [atoms and React](docs/atoms-and-react.md) for complete examples with import
 
 <!-- error types from src/errors.ts; timeout failure from src/actor.ts -->
 
+- Use `sendAndAwait` from `@xstate/effect/test` to acknowledge a specific event, including ignored events.
 - 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.
+- `EffectFailure<E>` carries the original `Cause<E>` in task and stream error snapshots, including defects and self-interruption.
 - Timed waits fail with Effect's `Cause.TimeoutError`.
-- `join` preserves a task's typed failure. Unexpected machine errors have type `unknown`.
+- `join` replays the original Cause and preserves a task's typed failure. Unexpected machine errors have type `unknown`.
 
-See [testing and errors](docs/testing-and-errors.md) for executable deadline, retry and failure examples. Persisted snapshots record actor state; pass one to `createEffectActor(logic, { snapshot })` to resume the actor. See [persisting and restoring](docs/actors.md#persisting-and-restoring).
+See [testing and errors](docs/testing-and-errors.md) for executable deadline, retry and failure examples. Persisted snapshots record actor state; pass one to `createEffectActor(logic, { snapshot })` to resume the actor. Use `createSnapshotCodec` with a full bidirectional Effect schema for validated JSON persistence of versioned machines. See [persisting and restoring](docs/actors.md#persisting-and-restoring).
 
 ## Tracing
 
-<!-- span names and attributes from src/internal.ts and src/createEffectLogic.ts -->
+<!-- span names and attributes from src/internal.ts and src/effectLogic.ts -->
 
 Hosted work uses spans named `createEffectLogic`, `createEffectStreamLogic`, `createEffectEventStreamLogic` 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,12 +1,24 @@
 import { Cause, Duration, Effect, Stream } from 'effect';
 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. */
+import { ActorStoppedError, type UnwrapEffectFailure } from "./errors.js";
+/**
+ * The event type accepted by an actor's `send` method.
+ *
+ * @experimental
+ */
 export type SendableEventFrom<TActor extends AnyActorRef> = Parameters<TActor['send']>[0];
-/** The event type an actor emits through `actor.on(...)`. */
+/**
+ * The event type an actor emits through `actor.on(...)`.
+ *
+ * @experimental
+ */
 export type EmittedEventFrom<TActor> = TActor extends EffectActor<infer TLogic> ? EmittedFrom<TLogic> : TActor extends Actor<infer TLogic> ? EmittedFrom<TLogic> : TActor extends ActorRef<any, any, infer TEmitted, any> ? TEmitted : AnyEventObject;
-/** Options for {@link waitFor}. */
+/**
+ * Options for {@link waitFor}.
+ *
+ * @experimental
+ */
 export interface WaitForOptions {
     /**
      * Fails with `Cause.TimeoutError` when no snapshot satisfies the predicate
@@ -19,6 +31,8 @@ export interface WaitForOptions {
  * is enqueued, like `actor.send(event)`, and processed on the actor's own
  * fiber. An event that cannot be delivered (for example to a stopped actor)
  * is reported as a dead letter, observable with {@link deadLetters}.
+ *
+ * @experimental
  */
 export declare const send: {
     <TActor extends AnyActorRef>(event: SendableEventFrom<TActor>): (actor: TActor) => Effect.Effect<void>;
@@ -29,12 +43,16 @@ export declare const send: {
  * when the actor completes or stops, and emits the error snapshot before
  * ending when the actor errors. Interrupting the stream unsubscribes from the
  * actor.
+ *
+ * @experimental
  */
 export declare function snapshots<TActor extends AnyActorRef>(actor: TActor): Stream.Stream<SnapshotFrom<TActor>>;
 /**
  * Streams every event an actor emits, as delivered to `actor.on('*', …)`. The
  * stream ends when the actor completes, errors or stops. Interrupting the
  * stream removes the listener.
+ *
+ * @experimental
  */
 export declare function emitted<TActor extends AnyActorRef>(actor: TActor): Stream.Stream<EmittedEventFrom<TActor>>;
 /**
@@ -43,6 +61,8 @@ export declare function emitted<TActor extends AnyActorRef>(actor: TActor): Stre
  * `ActorStoppedError` if the actor stops or errors first, and with
  * `Cause.TimeoutError` when `options.timeout` elapses. Interrupting the Effect
  * unsubscribes from the actor.
+ *
+ * @experimental
  */
 export declare const waitFor: {
     <TActor extends AnyActorRef, TNarrowed extends SnapshotFrom<TActor>>(predicate: (snapshot: SnapshotFrom<TActor>) => snapshot is TNarrowed): (actor: TActor) => Effect.Effect<TNarrowed, ActorStoppedError>;
@@ -56,15 +76,19 @@ export declare const waitFor: {
 };
 /**
  * Joins an actor's final result, like `Fiber.join`: succeeds with its `output`
- * when it is done, fails with `snapshot.error` when it errors, and fails with
+ * when it is done, replays an Effect actor's original Cause when it errors, and fails with
  * `ActorStoppedError` when it stops without output. Waits for a still-active
- * actor to settle.
+ * actor to settle. Ordinary XState errors remain typed failures.
+ *
+ * @experimental
  */
-export declare function join<TActor extends AnyActorRef>(actor: TActor): Effect.Effect<OutputFrom<TActor>, ErrorFrom<TActor> | ActorStoppedError>;
+export declare function join<TActor extends AnyActorRef>(actor: TActor): Effect.Effect<OutputFrom<TActor>, UnwrapEffectFailure<ErrorFrom<TActor>> | ActorStoppedError>;
 /**
  * Streams the inspection events of the actor's system, as delivered to
  * `system.inspect(…)`. The stream runs until it is interrupted or its scope
  * closes.
+ *
+ * @experimental
  */
 export declare function inspect(actor: AnyActorRef): Stream.Stream<InspectionEvent>;
 /**
@@ -73,5 +97,7 @@ export declare function inspect(actor: AnyActorRef): Stream.Stream<InspectionEve
  * 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.
+ *
+ * @experimental
  */
 export declare function deadLetters(actor: AnyActorRef): Stream.Stream<EventRejection>;

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

@@ -1,11 +1,17 @@
 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`. */
+/**
+ * The owning Effect actor's scope, supplied by `createEffectActor`.
+ *
+ * @experimental
+ */
 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.
+ *
+ * @experimental
  */
 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,8 +1,8 @@
 import { AsyncResult, Atom } from 'effect/reactivity';
-import type { AnyActorLogic, ErrorFrom, EventFromLogic, SnapshotFrom } from 'xstate';
+import { type AnyStateMachine, type AnyActorLogic, type ErrorFrom, type EventFromLogic, type SnapshotFrom } from 'xstate';
 import { type EffectActorOptionsArgs } from "./createEffectActor.js";
 import type { EffectActor } from "./effectActor.js";
-import { NotReadyError } from "./errors.js";
+import { NotReadyError, type UnwrapEffectFailure } from "./errors.js";
 import { type TaggedStateFrom } from "./state.js";
 import type { RequirementsFrom } from "./types.js";
 export { NotReadyError } from "./errors.js";
@@ -11,7 +11,7 @@ export { NotReadyError } from "./errors.js";
  * `effect/reactivity`. Read them with the atom bindings for your
  * framework, such as `@effect/atom-react`.
  */
-export interface ActorAtoms<TLogic extends AnyActorLogic, ER = never> {
+interface BaseActorAtoms<TLogic extends AnyActorLogic, ER> {
     /**
      * The running actor. It starts when the atom is first read and stops when
      * the atom is released, that is, when nothing reads or mounts it anymore.
@@ -23,7 +23,7 @@ export interface ActorAtoms<TLogic extends AnyActorLogic, ER = never> {
      * The snapshot as a result: a `Failure` carrying the actor's error once
      * the actor's status is `error`, so an error boundary can handle it.
      */
-    readonly result: Atom.Atom<AsyncResult.AsyncResult<SnapshotFrom<TLogic>, ER | ErrorFrom<TLogic>>>;
+    readonly result: Atom.Atom<AsyncResult.AsyncResult<SnapshotFrom<TLogic>, ER | UnwrapEffectFailure<ErrorFrom<TLogic>>>>;
     /**
      * Sends an event to the actor synchronously. Set it with the event, for
      * example through `useAtomSet` in React. Its value reports the last send:
@@ -33,12 +33,12 @@ export interface ActorAtoms<TLogic extends AnyActorLogic, ER = never> {
     readonly send: Atom.Writable<AsyncResult.AsyncResult<void, ER | NotReadyError>, EventFromLogic<TLogic>>;
     /** Derives an atom of a value selected from the snapshot. */
     readonly select: <T>(selector: (snapshot: SnapshotFrom<TLogic>) => T) => Atom.Atom<AsyncResult.AsyncResult<T, ER>>;
-    /**
-     * The snapshot as a tagged union over the machine's states, for
-     * `Match.tag` or a `switch` on `_tag`. See `taggedState`.
-     */
-    readonly state: Atom.Atom<AsyncResult.AsyncResult<TaggedStateFrom<SnapshotFrom<TLogic>>, ER>>;
 }
+/** @experimental */
+export type ActorAtoms<TLogic extends AnyActorLogic, ER = never> = BaseActorAtoms<TLogic, ER> & ([TLogic] extends [AnyStateMachine] ? {
+    /** The machine snapshot as a tagged union over its states. */
+    readonly state: Atom.Atom<AsyncResult.AsyncResult<TaggedStateFrom<SnapshotFrom<TLogic>>, ER>>;
+} : {});
 interface MissingRequirements<T> {
     readonly 'The runtime does not provide services the logic requires': T;
 }
@@ -53,5 +53,7 @@ interface MissingRequirements<T> {
  * when the atom is released. Wrap the atoms with `Atom.keepAlive` to pin the
  * actor for the registry's lifetime, or with `Atom.family` to create one
  * actor per input.
+ *
+ * @experimental
  */
 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

@@ -1,21 +1,30 @@
 import { Effect, Scope } from 'effect';
-import { type ActorOptions, type AnyActorLogic, type InputFrom, type RequiredActorOptionsFor, type RequiredActorOptionsKeys } from 'xstate';
+import { type AnyActorLogic, type InputFrom, type RestorablePersistedSnapshotFor, type RequiredActorOptionsKeys, type Snapshot } from 'xstate';
 import { EffectActor } from "./effectActor.js";
 import type { RequirementsFrom } from "./types.js";
-/** Options for {@link createEffectActor}. */
+/**
+ * Options for {@link createEffectActor}.
+ *
+ * @experimental
+ */
 export type EffectActorOptions<TLogic extends AnyActorLogic> = {
     readonly input?: InputFrom<TLogic>;
     /**
      * A snapshot from `actor.getPersistedSnapshot()`. The actor resumes in that
      * state without re-running entry actions, and pending timers keep their
-     * original deadlines, as with XState's `createActor(logic, { snapshot })`.
+     * original deadlines, as with `restoreActor(logic, snapshot)` from
+     * `xstate/persist`.
      * State-machine children resume their persisted state and completed
      * children stay done. Effect tasks and streams that were running, at the
      * root or as children, start again from the beginning. A restored actor
      * does not need `input`.
      */
-    readonly snapshot?: ActorOptions<TLogic>['snapshot'];
-} & RequiredActorOptionsFor<TLogic>;
+    readonly snapshot?: Snapshot<unknown> & Partial<RestorablePersistedSnapshotFor<TLogic>>;
+} & ([RequiredActorOptionsKeys<TLogic>] extends [never] ? {} : {
+    [K in RequiredActorOptionsKeys<TLogic>]: unknown;
+} | {
+    snapshot: Snapshot<unknown> & Partial<RestorablePersistedSnapshotFor<TLogic>>;
+});
 export type EffectActorOptionsArgs<TLogic extends AnyActorLogic> = [
     RequiredActorOptionsKeys<TLogic>
 ] extends [never] ? [options?: EffectActorOptions<TLogic>] : [options: EffectActorOptions<TLogic>];
@@ -32,5 +41,7 @@ export type EffectActorOptionsArgs<TLogic extends AnyActorLogic> = [
  * The actor is a scoped resource: it stops, and every Effect it hosts is
  * interrupted, when the enclosing `Scope` closes. The returned Effect never
  * fails; the actor's own outcome is its snapshot status, read with `join`.
+ *
+ * @experimental
  */
 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

@@ -1,13 +1,17 @@
-import { Queue } from 'effect';
-import type { ActorRef, AnyActor, AnyActorLogic, EmittedFrom, EventFromLogic, InspectionEvent, Observer, Snapshot, SnapshotFrom, Subscription } from 'xstate';
-/** A mailbox item that reports a failed fire-and-forget action. */
-export interface ActionFailure {
-    readonly [actionFailure]: true;
-    readonly error: unknown;
+import { Exit, Queue } from 'effect';
+import { ActorStoppedError, EventRejectedError } from "./errors.js";
+import type { ActorRef, AnyActor, AnyActorLogic, EmittedFrom, EventFromLogic, InspectionEvent, Observer, PersistedSnapshotOf, SnapshotFrom, Subscription } from 'xstate';
+export interface Receipt<TSnapshot> {
+    resume?: (exit: Exit.Exit<TSnapshot, ActorStoppedError | EventRejectedError>) => void;
 }
-export declare const actionFailure: unique symbol;
-export declare function isActionFailure(value: unknown): value is ActionFailure;
-export type MailboxItem<TEvent> = TEvent | ActionFailure;
+export type MailboxItem<TEvent, TSnapshot> = {
+    readonly kind: 'event';
+    readonly event: TEvent;
+    readonly receipt?: Receipt<TSnapshot>;
+} | {
+    readonly kind: 'actionFailure';
+    readonly error: unknown;
+};
 declare const symbolObservable: typeof Symbol.observable;
 /**
  * Calls a listener and reports an exception it throws without letting it
@@ -19,6 +23,8 @@ export declare function safeCall<T>(fn: ((arg: T) => void) | undefined, arg?: T)
  * contract (`send`, `getSnapshot`, `subscribe`, `on`), so it works with
  * `useSelector`, this package's actor functions and the inspection APIs, while
  * the actor itself is driven by an Effect fiber over pure transitions.
+ *
+ * @experimental
  */
 export declare class EffectActor<TLogic extends AnyActorLogic> implements ActorRef<SnapshotFrom<TLogic>, EventFromLogic<TLogic>, EmittedFrom<TLogic>> {
     readonly logic: TLogic;
@@ -34,11 +40,14 @@ export declare class EffectActor<TLogic extends AnyActorLogic> implements ActorR
     private readonly _observers;
     private readonly _listeners;
     private _settled;
-    constructor(logic: TLogic, root: AnyActor, snapshot: SnapshotFrom<TLogic>, _mailbox: Queue.Queue<MailboxItem<EventFromLogic<TLogic>>>, _stopExecution: () => void, _inspectors: Set<(event: InspectionEvent) => void>);
+    private readonly _pending;
+    constructor(logic: TLogic, root: AnyActor, snapshot: SnapshotFrom<TLogic>, _mailbox: Queue.Queue<MailboxItem<EventFromLogic<TLogic>, SnapshotFrom<TLogic>>>, _stopExecution: () => void, _inspectors: Set<(event: InspectionEvent) => void>);
     getSnapshot(): SnapshotFrom<TLogic>;
-    getPersistedSnapshot(): Snapshot<unknown>;
+    getPersistedSnapshot(): PersistedSnapshotOf<TLogic>;
     /** Sends an event; the actor processes it on its own fiber. */
     send(event: EventFromLogic<TLogic>): void;
+    private _deliveryError;
+    private _stoppedError;
     /** Stops the actor, its children and every Effect it hosts. */
     stop(): this;
     subscribe(observer: Observer<SnapshotFrom<TLogic>>): Subscription;

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

@@ -1,5 +1,6 @@
 import { Effect, Stream } from 'effect';
 import { type ActorLogicValidator, type ActorLogic, type AnyActorRef, type AnyActorSystem, type AnyEventObject, type EventObject, type Snapshot, type StandardSchemaV1 } from 'xstate';
+import { EffectFailure } from "./errors.js";
 import type { EffectRequirements } from "./types.js";
 import { type EffectSchemaLike, type ToStandardSchema, type ValidateEffectActorSchemas } from "./schema.js";
 declare const effectLogicBrand: unique symbol;
@@ -9,6 +10,8 @@ declare const effectLogicBrand: unique symbol;
  * failure type and its Effect service requirements, which is how
  * `RequirementsFrom` collects the `R` channel of `createEffectActor` without
  * inspecting the logic at runtime.
+ *
+ * @experimental
  */
 export interface EffectLogicBrand<TError, TRequirements> {
     readonly [effectLogicBrand]: {
@@ -19,19 +22,22 @@ export interface EffectLogicBrand<TError, TRequirements> {
 /**
  * Snapshot of a `createEffectLogic` actor. The actor holds no context of its own: it
  * is `active` while the Effect runs, `done` with the Effect's success value as
- * `output`, or `error` with the Effect's failure, defect or
- * `EffectInterruptedError` as `error`.
+ * `output`, or `error` with the original `Cause` wrapped in `EffectFailure` as `error`.
+ *
+ * @experimental
  */
 export type EffectSnapshot<TOutput, TError, TInput> = Snapshot<TOutput> & {
     readonly context: undefined;
     readonly input: TInput | undefined;
-    readonly error: TError | undefined;
+    readonly error: EffectFailure<TError> | undefined;
 };
 /**
  * Argument passed to the function form of an Effect source. It gives the
  * source the actor's `input`, its own reference (`self`), the actor `system`,
  * and `emit` for publishing events that `actor.on(...)` and `emitted(actor)`
  * observe.
+ *
+ * @experimental
  */
 export type EffectSourceArgs<TInput> = {
     readonly input: TInput;
@@ -44,6 +50,8 @@ export type EffectSourceArgs<TInput> = {
  * What `createEffectLogic` accepts as its Effect: either an Effect value, or a
  * function of {@link EffectSourceArgs} returning one. The function form is
  * called once per actor start, so it sees that actor's input.
+ *
+ * @experimental
  */
 export type EffectSource<TOutput, TError, TInput, TRequirements> = Effect.Effect<TOutput, TError, TRequirements> | ((args: EffectSourceArgs<TInput>) => Effect.Effect<TOutput, TError, TRequirements>);
 type EffectActorSchemas = {
@@ -58,7 +66,7 @@ type EffectSourceConfig<TOutput, TError, TInput, TRequirements, TSchemas extends
 };
 type SchemaOutput<TSchema extends EffectSchemaLike> = StandardSchemaV1.InferOutput<ToStandardSchema<TSchema>>;
 type EffectSuccess<T> = T extends Effect.Effect<infer A, any, any> ? A : never;
-type EffectFailure<T> = T extends Effect.Effect<any, infer E, any> ? E : never;
+type EffectError<T> = T extends Effect.Effect<any, infer E, any> ? E : never;
 type EffectSchemaValidationConfig<TSchemas extends EffectActorSchemas> = {
     readonly validator: ActorLogicValidator;
     readonly schemas: TSchemas & ValidateEffectActorSchemas<TSchemas>;
@@ -71,6 +79,8 @@ type EffectSchemaValidationConfig<TSchemas extends EffectActorSchemas> = {
  * ordinary XState actor logic carrying {@link EffectLogicBrand}, so a machine
  * can invoke or spawn it, and `createEffectActor` can collect its
  * requirements.
+ *
+ * @experimental
  */
 export type EffectActorLogic<TOutput, TError, TInput, TRequirements> = ActorLogic<EffectSnapshot<TOutput, TError, TInput>, EventObject, TInput, AnyActorSystem> & {
     readonly id?: string;
@@ -79,44 +89,48 @@ export type EffectActorLogic<TOutput, TError, TInput, TRequirements> = ActorLogi
  * Snapshot of a `createEffectStreamLogic` actor. `context` holds the most recent
  * stream item, or `undefined` before the first one. The actor reaches `done`
  * with no output when the stream completes, and `error` when it fails.
+ *
+ * @experimental
  */
 export type EffectStreamSnapshot<TItem, TError, TInput> = Snapshot<undefined> & {
     readonly context: TItem | undefined;
     readonly input: TInput | undefined;
-    readonly error: TError | undefined;
+    readonly error: EffectFailure<TError> | undefined;
 };
 /**
  * Actor logic produced by `createEffectStreamLogic`. Its snapshot is an
  * {@link EffectStreamSnapshot}, so the parent reads the latest item from the
  * child's `context` rather than from events.
+ *
+ * @experimental
  */
 export type EffectStreamActorLogic<TItem, TError, TInput, TRequirements> = ActorLogic<EffectStreamSnapshot<TItem, TError, TInput>, EventObject, TInput, AnyActorSystem> & {
     readonly id?: string;
 } & EffectLogicBrand<TError, TRequirements>;
 /**
  * Creates actor logic that runs an Effect. The actor completes with the
- * Effect's success value as its output and fails with the Effect's error, its
- * squashed defect, or an `EffectInterruptedError` when the Effect interrupts
- * itself. Stopping the actor interrupts the Effect without an error. Accepts
+ * Effect's success value as its output and fails with the original `Cause` wrapped in `EffectFailure`. Stopping the actor interrupts the Effect without an error. Accepts
  * 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.
+ *
+ * @experimental
  */
 export declare function createEffectLogic<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;
     output: TOutputSchema;
 }>): EffectActorLogic<SchemaOutput<TOutputSchema>, TError, SchemaOutput<TInputSchema>, TRequirements>;
-export declare function createEffectLogic<const TInputSchema extends EffectSchemaLike, TEffect extends Effect.Effect<any, any, any>>(config: Omit<EffectSourceConfig<EffectSuccess<TEffect>, EffectFailure<TEffect>, SchemaOutput<TInputSchema>, EffectRequirements<TEffect>, {
+export declare function createEffectLogic<const TInputSchema extends EffectSchemaLike, TEffect extends Effect.Effect<any, any, any>>(config: Omit<EffectSourceConfig<EffectSuccess<TEffect>, EffectError<TEffect>, SchemaOutput<TInputSchema>, EffectRequirements<TEffect>, {
     input: TInputSchema;
 }>, 'effect' | 'schemas' | 'validator'> & EffectSchemaValidationConfig<{
     input: TInputSchema;
     output?: never;
 }> & {
     effect: TEffect | ((args: EffectSourceArgs<SchemaOutput<TInputSchema>>) => TEffect);
-}): EffectActorLogic<EffectSuccess<TEffect>, EffectFailure<TEffect>, SchemaOutput<TInputSchema>, EffectRequirements<TEffect>>;
+}): EffectActorLogic<EffectSuccess<TEffect>, EffectError<TEffect>, SchemaOutput<TInputSchema>, EffectRequirements<TEffect>>;
 export declare function createEffectLogic<const TOutputSchema extends EffectSchemaLike, TError = unknown, TInput = undefined, TRequirements = never>(config: Omit<EffectSourceConfig<SchemaOutput<TOutputSchema>, TError, TInput, TRequirements>, 'schemas' | 'validator'> & EffectSchemaValidationConfig<{
     input?: never;
     output: TOutputSchema;
@@ -130,6 +144,8 @@ export declare function createEffectLogic<TOutput, TError = unknown, TInput = un
  * What `createEffectStreamLogic` and `createEffectEventStreamLogic` accept as their stream:
  * either a Stream value, or a function of {@link EffectSourceArgs} returning
  * one. The function form is called once per actor start.
+ *
+ * @experimental
  */
 export type EffectStreamSource<TItem, TError, TInput, TRequirements> = Stream.Stream<TItem, TError, TRequirements> | ((args: EffectSourceArgs<TInput>) => Stream.Stream<TItem, TError, TRequirements>);
 type EffectStreamConfig<TItem, TError, TInput, TRequirements, TSchemas extends {
@@ -152,6 +168,8 @@ type StreamRequirements<T> = T extends Stream.Stream<any, any, infer R> ? R : ne
  * {@link EffectSourceArgs} returning one, or a config object with `id`,
  * `schemas`, `validator` and `stream`. Its resources close when the stream
  * completes, fails or is interrupted.
+ *
+ * @experimental
  */
 export declare function createEffectStreamLogic<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;
@@ -168,6 +186,8 @@ export declare function createEffectStreamLogic<TItem, TError = unknown, TInput
  * has no output: it reaches `done` when the stream completes and `error` when
  * it fails. Accepts the same forms as `createEffectStreamLogic`. Its resources close
  * when the stream completes, fails or is interrupted.
+ *
+ * @experimental
  */
 export declare function createEffectEventStreamLogic<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/errors.d.ts

@@ -1,12 +1,24 @@
 import { Cause } from 'effect';
 import type { Snapshot } from 'xstate';
+/**
+ * Preserves an Effect failure, defect or interruption through XState error routing.
+ *
+ * @experimental
+ */
+export declare class EffectFailure<E> extends Error {
+    #private;
+    readonly cause: Cause.Cause<E>;
+    readonly _tag = "EffectFailure";
+    static is(value: unknown): value is EffectFailure<unknown>;
+    constructor(cause: Cause.Cause<E>);
+}
 declare const EffectInterruptedError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
     readonly _tag: "EffectInterruptedError";
 } & Readonly<A>;
 /**
- * The failure an Effect-backed actor reports when its Effect was interrupted
- * by something other than the actor being stopped, such as `Effect.interrupt`,
- * losing an `Effect.race`, or an `Effect.timeout` that interrupts.
+ * @deprecated Inspect `EffectFailure.cause` for interruption instead.
+ *
+ * @experimental
  */
 export declare class EffectInterruptedError extends EffectInterruptedError_base<{
     readonly cause: Cause.Cause<never>;
@@ -19,7 +31,9 @@ declare const ActorStoppedError_base: new <A extends Record<string, any> = {}>(a
 /**
  * Reported by `waitFor` when the actor stops or errors before a snapshot
  * matches, and by `join` when the actor stops without output. `join` reports
- * an errored actor's own `snapshot.error` instead.
+ * an errored actor's outcome instead, preserving an Effect failure's Cause.
+ *
+ * @experimental
  */
 export declare class ActorStoppedError extends ActorStoppedError_base<{
     readonly actorId: string;
@@ -33,8 +47,27 @@ declare const NotReadyError_base: new <A extends Record<string, any> = {}>(args:
 /**
  * Reported by the `send` atom of `createActorAtoms` when an event is sent
  * before the actor's runtime has finished building.
+ *
+ * @experimental
  */
 export declare class NotReadyError extends NotReadyError_base {
     get message(): string;
 }
+export type UnwrapEffectFailure<E> = E extends EffectFailure<infer Failure> ? Failure : E;
+declare const EventRejectedError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
+    readonly _tag: "EventRejectedError";
+} & Readonly<A>;
+/**
+ * An event rejected at the actor's delivery boundary.
+ *
+ * @experimental
+ */
+export declare class EventRejectedError extends EventRejectedError_base<{
+    readonly actorId: string;
+    readonly event: {
+        readonly type: string;
+    };
+    readonly reason: string;
+}> {
+}
 export {};

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

@@ -3,9 +3,10 @@ export { createEffectActor, type EffectActorOptions } from "./createEffectActor.
 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 { ActorStoppedError, EventRejectedError, EffectFailure, EffectInterruptedError } from "./errors.js";
 export { setupEffect, type EffectAction, type EffectActionArgs, type EffectSetupReturn } from "./setupEffect.js";
 export { type RequirementsFrom } from "./types.js";
 export { taggedState, type StateTag, type TaggedState, type TaggedStateFrom } from "./state.js";
 export { type ErrorFrom } from 'xstate';
-export { type EffectSchema, type EffectSchemaLike, type EffectSetupSchemas, type EffectSetupStateSchema } from "./schema.js";
+export { type EffectSchema, type EffectSchemaLike, type EffectSetupSchemas, type EffectSetupStateSchema, type ToStandardSetupSchemas, type ToStandardSetupStates } from "./schema.js";
+export { createSnapshotCodec, SnapshotCodecError } from "./persistence.js";

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

@@ -0,0 +1,3 @@
+/** @experimental */
+declare const _default: import("@oxlint/plugins").Plugin;
+export default _default;

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

@@ -0,0 +1,45 @@
+import { Effect, Schema } from 'effect';
+import type { AnyStateMachine, RestorablePersistedSnapshotFor, Snapshot } from 'xstate';
+type SnapshotData<TMachine extends AnyStateMachine> = {
+    readonly status: Snapshot<unknown>['status'];
+    readonly context: unknown;
+    readonly value: unknown;
+    readonly children: Readonly<Record<string, unknown>>;
+    readonly machine: {
+        readonly id: TMachine['id'];
+        readonly version: string;
+    };
+};
+declare const SnapshotCodecError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "SnapshotCodecError";
+} & Readonly<A>;
+/**
+ * A malformed transport, unsupported JSON value or missing persistence metadata.
+ *
+ * @experimental
+ */
+export declare class SnapshotCodecError extends SnapshotCodecError_base<{
+    readonly stage: 'encode' | 'decode';
+    readonly path: string;
+    readonly reason: string;
+}> {
+    get message(): string;
+}
+/**
+ * Binds a full bidirectional snapshot schema to a versioned machine. The schema
+ * owns rich values and supported historical versions. Decoding never migrates;
+ * restore or `machineVersions` remains responsible for migration.
+ *
+ * @experimental
+ */
+export declare function createSnapshotCodec<TMachine extends AnyStateMachine & {
+    readonly version: string;
+}, P extends SnapshotData<TMachine>, Encoded, RD, RE>(machine: TMachine, schema: Schema.Codec<P, Encoded, RD, RE> & (unknown extends RE ? {
+    readonly 'A bidirectional codec is required': never;
+} : unknown)): {
+    encode(snapshot: P | (Snapshot<unknown> & RestorablePersistedSnapshotFor<TMachine> & {
+        readonly context: P["context"];
+    })): Effect.Effect<string, SnapshotCodecError | Schema.SchemaError, RE>;
+    decode(json: string): Effect.Effect<P & Snapshot<unknown> & RestorablePersistedSnapshotFor<TMachine>, SnapshotCodecError | Schema.SchemaError, RD>;
+};
+export {};