@xstate/effect 0.1.0-alpha.7 → 1.0.0-alpha.11

package/README.md

@@ -9,14 +9,18 @@ Combine XState's event-driven workflows with Effect services, scopes, clocks and
 
 This package is experimental. It targets XState v6 alpha 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@latest xstate@alpha 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 -->
@@ -29,7 +33,7 @@ A release waits for approval, expires after 30 seconds, and allows cancellation
 import { Context, Effect, Schema } from 'effect';
 import {
   createEffectActor,
-  fromEffect,
+  createEffectLogic,
   send,
   setupEffect,
   waitFor
@@ -40,7 +44,7 @@ export class Deployments extends Context.Service<
   { readonly deploy: (release: string) => Effect.Effect<string, Error> }
 >()('@app/Deployments') {}
 
-const deploy = fromEffect({
+const deploy = createEffectLogic({
   schemas: { input: Schema.Struct({ release: Schema.String }) },
   effect: ({ input }) => Deployments.use((api) => api.deploy(input.release))
 });
@@ -121,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 |
@@ -134,7 +142,7 @@ Start Effect-backed logic with `createEffectActor` inside an Effect scope.
 | [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. |
 
-Runnable copies live in [examples/effect-workflows](../../examples/effect-workflows). Their tests verify the docs use the same code.
+Try the runnable examples in [examples/effect-workflows](../../examples/effect-workflows).
 
 ## Actors
 
@@ -183,13 +191,13 @@ The actor's later errors are observed through `join` or snapshots. Invalid input
 
 ## Effect actor logic
 
-<!-- fromEffect, fromEffectStream, fromEffectEventStream from src/fromEffect.ts -->
+<!-- createEffectLogic, createEffectStreamLogic, createEffectEventStreamLogic from src/effectLogic.ts -->
 
 | 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. |
+| `createEffectLogic` | Run a task; its success value is the actor's output. |
+| `createEffectStreamLogic` | Expose the latest stream item as snapshot context. |
+| `createEffectEventStreamLogic` | Relay stream items to the parent as events. |
 
 For example, a progress stream can feed an upload UI:
 
@@ -197,10 +205,14 @@ For example, a progress stream can feed an upload UI:
 
 ```ts
 import { Effect, Option, Stream } from 'effect';
-import { createEffectActor, fromEffectStream, snapshots } from '@xstate/effect';
+import {
+  createEffectActor,
+  createEffectStreamLogic,
+  snapshots
+} from '@xstate/effect';
 
 // Demo upload progress. Replace with your upload SDK's progress stream.
-const uploadProgress = fromEffectStream(Stream.make(0, 25, 60, 100));
+const uploadProgress = createEffectStreamLogic(Stream.make(0, 25, 60, 100));
 
 const program = Effect.gen(function* () {
   const actor = yield* createEffectActor(uploadProgress);
@@ -229,16 +241,20 @@ See [Effect actor logic](docs/effect-logic.md) for tasks and a stream that drive
 <!-- effect action contract from src/setupEffect.ts; spawn guard from src/internal.ts -->
 
 - Register background Effect actions in `setupEffect({ actions })`; enqueue them with explicit arguments.
-- Invoke `fromEffect` logic when the machine needs to wait for a result.
+- Invoke `createEffectLogic` logic when the machine needs to wait for a result.
 - Register spawned Effect logic in `actors`, then use `enq.spawn(args.actors.worker)`.
 
 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.
@@ -250,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/fromEffect.ts -->
+<!-- span names and attributes from src/internal.ts and src/effectLogic.ts -->
 
-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.
+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,7 +1,7 @@
 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";
+import { ActorStoppedError, type UnwrapEffectFailure } from "./errors.js";
 /** The event type accepted by an actor's `send` method. */
 export type SendableEventFrom<TActor extends AnyActorRef> = Parameters<TActor['send']>[0];
 /** The event type an actor emits through `actor.on(...)`. */
@@ -56,11 +56,11 @@ 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.
  */
-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

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,11 @@ 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>>;
 }
+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;
 }

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
@@ -34,11 +38,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;
@@ -53,8 +60,7 @@ export declare class EffectActor<TLogic extends AnyActorLogic> implements ActorR
     inspect(observer: Observer<InspectionEvent> | ((event: InspectionEvent) => void)): Subscription;
     [symbolObservable](): this;
     toJSON(): {
-        xstate$$type: number;
-        id: string;
+        $actor: string;
     };
 }
 export {};

package/dist/declarations/src/{fromEffect.d.ts → effectLogic.d.ts}

@@ -1,11 +1,12 @@
 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;
 /**
- * Type-level marker attached to logic created by `fromEffect`,
- * `fromEffectStream` and `fromEffectEventStream`. It carries the logic's
+ * Type-level marker attached to logic created by `createEffectLogic`,
+ * `createEffectStreamLogic` and `createEffectEventStreamLogic`. It carries the logic's
  * failure type and its Effect service requirements, which is how
  * `RequirementsFrom` collects the `R` channel of `createEffectActor` without
  * inspecting the logic at runtime.
@@ -17,15 +18,14 @@ export interface EffectLogicBrand<TError, TRequirements> {
     };
 }
 /**
- * Snapshot of a `fromEffect` actor. The actor holds no context of its own: it
+ * 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`.
  */
 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
@@ -41,7 +41,7 @@ export type EffectSourceArgs<TInput> = {
     readonly emit: (event: AnyEventObject) => void;
 };
 /**
- * What `fromEffect` accepts as its Effect: either an Effect value, or a
+ * 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.
  */
@@ -58,7 +58,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>;
@@ -67,7 +67,7 @@ type EffectSchemaValidationConfig<TSchemas extends EffectActorSchemas> = {
     readonly schemas: TSchemas;
 };
 /**
- * Actor logic produced by `fromEffect` and `fromEffectEventStream`. It is
+ * Actor logic produced by `createEffectLogic` and `createEffectEventStreamLogic`. It is
  * ordinary XState actor logic carrying {@link EffectLogicBrand}, so a machine
  * can invoke or spawn it, and `createEffectActor` can collect its
  * requirements.
@@ -76,17 +76,17 @@ export type EffectActorLogic<TOutput, TError, TInput, TRequirements> = ActorLogi
     readonly id?: string;
 } & EffectLogicBrand<TError, TRequirements>;
 /**
- * Snapshot of a `fromEffectStream` actor. `context` holds the most recent
+ * 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.
  */
 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 `fromEffectStream`. Its snapshot is an
+ * 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.
  */
@@ -95,9 +95,7 @@ export type EffectStreamActorLogic<TItem, TError, TInput, TRequirements> = Actor
 } & 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.
@@ -105,29 +103,29 @@ export type EffectStreamActorLogic<TItem, TError, TInput, TRequirements> = Actor
  * 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<{
+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 fromEffect<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>>;
-export declare function fromEffect<const TOutputSchema extends EffectSchemaLike, TError = unknown, TInput = undefined, TRequirements = never>(config: Omit<EffectSourceConfig<SchemaOutput<TOutputSchema>, TError, TInput, TRequirements>, 'schemas' | 'validator'> & EffectSchemaValidationConfig<{
+}): 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;
 }>): EffectActorLogic<SchemaOutput<TOutputSchema>, TError, TInput, TRequirements>;
-export declare function fromEffect<TOutput, TError = unknown, TInput = undefined, TRequirements = never>(config: EffectSourceConfig<TOutput, TError, TInput, TRequirements> & {
+export declare function createEffectLogic<TOutput, TError = unknown, TInput = undefined, TRequirements = never>(config: EffectSourceConfig<TOutput, TError, TInput, TRequirements> & {
     schemas?: undefined;
 }): EffectActorLogic<TOutput, TError, TInput, TRequirements>;
-export declare function fromEffect<TOutput, TError = unknown, TRequirements = never>(effect: Effect.Effect<TOutput, TError, TRequirements>): EffectActorLogic<TOutput, TError, undefined, TRequirements>;
-export declare function fromEffect<TOutput, TError = unknown, TInput = undefined, TRequirements = never>(effect: (args: EffectSourceArgs<TInput>) => Effect.Effect<TOutput, TError, TRequirements>): EffectActorLogic<TOutput, TError, TInput, TRequirements>;
+export declare function createEffectLogic<TOutput, TError = unknown, TRequirements = never>(effect: Effect.Effect<TOutput, TError, TRequirements>): EffectActorLogic<TOutput, TError, undefined, TRequirements>;
+export declare function createEffectLogic<TOutput, TError = unknown, TInput = undefined, TRequirements = never>(effect: (args: EffectSourceArgs<TInput>) => Effect.Effect<TOutput, TError, TRequirements>): EffectActorLogic<TOutput, TError, TInput, TRequirements>;
 /**
- * What `fromEffectStream` and `fromEffectEventStream` accept as their stream:
+ * 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.
  */
@@ -153,29 +151,29 @@ type StreamRequirements<T> = T extends Stream.Stream<any, any, infer R> ? R : ne
  * `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<{
+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;
 }> & {
     stream: TStream | ((args: EffectSourceArgs<SchemaOutput<TInputSchema>>) => TStream);
 }): EffectStreamActorLogic<StreamItem<TStream>, StreamError<TStream>, SchemaOutput<TInputSchema>, StreamRequirements<TStream>>;
-export declare function fromEffectStream<TItem, TError = unknown, TInput = undefined, TRequirements = never>(config: EffectStreamConfig<TItem, TError, TInput, TRequirements> & {
+export declare function createEffectStreamLogic<TItem, TError = unknown, TInput = undefined, TRequirements = never>(config: EffectStreamConfig<TItem, TError, TInput, TRequirements> & {
     schemas?: undefined;
 }): EffectStreamActorLogic<TItem, TError, TInput, TRequirements>;
-export declare function fromEffectStream<TItem, TError = unknown, TInput = undefined, TRequirements = never>(stream: EffectStreamSource<TItem, TError, TInput, TRequirements>): EffectStreamActorLogic<TItem, TError, TInput, TRequirements>;
+export declare function createEffectStreamLogic<TItem, TError = unknown, TInput = undefined, TRequirements = never>(stream: EffectStreamSource<TItem, TError, TInput, TRequirements>): EffectStreamActorLogic<TItem, TError, TInput, TRequirements>;
 /**
  * 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`. Its resources close
+ * it fails. Accepts the same forms as `createEffectStreamLogic`. 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<{
+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;
 }> & {
     stream: TStream | ((args: EffectSourceArgs<SchemaOutput<TInputSchema>>) => TStream);
 }): EffectActorLogic<undefined, StreamError<TStream>, SchemaOutput<TInputSchema>, StreamRequirements<TStream>>;
-export declare function fromEffectEventStream<TEvent extends EventObject, TError = unknown, TInput = undefined, TRequirements = never>(config: EffectStreamConfig<TEvent, TError, TInput, TRequirements> & {
+export declare function createEffectEventStreamLogic<TEvent extends EventObject, TError = unknown, TInput = undefined, TRequirements = never>(config: EffectStreamConfig<TEvent, TError, TInput, TRequirements> & {
     schemas?: undefined;
 }): EffectActorLogic<undefined, TError, TInput, TRequirements>;
-export declare function fromEffectEventStream<TEvent extends EventObject, TError = unknown, TInput = undefined, TRequirements = never>(stream: EffectStreamSource<TEvent, TError, TInput, TRequirements>): EffectActorLogic<undefined, TError, TInput, TRequirements>;
+export declare function createEffectEventStreamLogic<TEvent extends EventObject, TError = unknown, TInput = undefined, TRequirements = never>(stream: EffectStreamSource<TEvent, TError, TInput, TRequirements>): EffectActorLogic<undefined, TError, TInput, TRequirements>;
 export {};

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

@@ -1,13 +1,17 @@
 import { Cause } from 'effect';
 import type { Snapshot } from 'xstate';
+/** Preserves an Effect failure, defect or interruption through XState error routing. */
+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. */
 export declare class EffectInterruptedError extends EffectInterruptedError_base<{
     readonly cause: Cause.Cause<never>;
 }> {
@@ -19,7 +23,7 @@ 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.
  */
 export declare class ActorStoppedError extends ActorStoppedError_base<{
     readonly actorId: string;
@@ -37,4 +41,17 @@ declare const NotReadyError_base: new <A extends Record<string, any> = {}>(args:
 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. */
+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

@@ -1,11 +1,12 @@
-export { fromEffect, fromEffectEventStream, fromEffectStream, type EffectActorLogic, type EffectLogicBrand, type EffectSnapshot, type EffectSource, type EffectSourceArgs, type EffectStreamSource, type EffectStreamActorLogic, type EffectStreamSnapshot } from "./fromEffect.js";
+export { createEffectLogic, createEffectEventStreamLogic, createEffectStreamLogic, type EffectActorLogic, type EffectLogicBrand, type EffectSnapshot, type EffectSource, type EffectSourceArgs, type EffectStreamSource, type EffectStreamActorLogic, type EffectStreamSnapshot } from "./effectLogic.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 { 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,2 @@
+declare const _default: import("@oxlint/plugins").Plugin;
+export default _default;

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

@@ -0,0 +1,39 @@
+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. */
+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.
+ */
+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 {};

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

@@ -1,8 +1,8 @@
 import { Schema } from 'effect';
 import type { SetupSchemas, SetupStateSchema, SetupStateSchemas, StandardSchemaV1 } from 'xstate';
 /**
- * An Effect `Schema` accepted by this package. `setupEffect`, `fromEffect`,
- * `fromEffectStream` and `fromEffectEventStream` convert it to a Standard
+ * An Effect `Schema` accepted by this package. `setupEffect`, `createEffectLogic`,
+ * `createEffectStreamLogic` and `createEffectEventStreamLogic` convert it to a Standard
  * Schema, so XState infers the decoded `Schema.Type` without an explicit call
  * to `Schema.toStandardSchemaV1`.
  */