@typeonce/effect-machine 0.1.0

package/dist/Machine.js

@@ -0,0 +1,923 @@
+/**
+ * Schema-first machine definitions.
+ *
+ * @since 4.0.0
+ */
+import * as Effect from "effect/Effect";
+import * as Inspectable from "effect/Inspectable";
+import * as Option from "effect/Option";
+import { Prototype as PipeablePrototype } from "effect/Pipeable";
+import { hasProperty } from "effect/Predicate";
+import { ProcessLocalError as ProcessLocalErrorValue } from "./internal/machineErrors.js";
+import * as Model from "./internal/machineModel.js";
+import * as internalPlanner from "./internal/machinePlanner.js";
+import * as internalProcess from "./internal/machineProcess.js";
+import * as internalRuntime from "./internal/machineRuntime.js";
+/**
+ * Runtime type identifier attached to `Machine` values.
+ *
+ * @category type IDs
+ * @since 4.0.0
+ */
+export const TypeId = "~effect/Machine";
+/**
+ * Type identifier used for the synthetic event passed to startup lifecycle
+ * actions.
+ *
+ * @category type IDs
+ * @since 4.0.0
+ */
+export const InitialEventTypeId = internalPlanner.InitialEventTypeId;
+/**
+ * Synthetic event value used while the machine settles its initial state.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const InitialEvent = internalPlanner.InitialEvent;
+/**
+ * Returns `true` if a value is the synthetic machine initial event.
+ *
+ * @category guards
+ * @since 4.0.0
+ */
+export const isInitialEvent = (u) => hasProperty(u, "_tag") && u._tag === InitialEventTypeId;
+export { 
+/**
+ * Error returned by `spawn` when a child process with the same id already
+ * exists for the current machine.
+ *
+ * @category errors
+ * @since 4.0.0
+ */
+ChildAlreadyExistsError, 
+/**
+ * Error returned when a machine does not stabilize within the maximum
+ * number of macrostep iterations.
+ *
+ * @category errors
+ * @since 4.0.0
+ */
+InfiniteTransitionError, 
+/**
+ * Error returned when a machine contract value does not match the schema or
+ * structural configuration declared for a machine boundary.
+ *
+ * @category errors
+ * @since 4.0.0
+ */
+MachineSchemaDecodeError, 
+/**
+ * Error returned when a decoded machine snapshot cannot be encoded through
+ * its declared state or output schemas.
+ *
+ * @category errors
+ * @since 4.0.0
+ */
+MachineSchemaEncodeError, 
+/**
+ * Error returned when standalone action execution attempts an operation that
+ * requires a managed machine process.
+ *
+ * @category errors
+ * @since 4.0.0
+ */
+ProcessLocalError, 
+/**
+ * Error returned when a machine fails while running startup lifecycle
+ * logic after the initial state has been computed.
+ *
+ * @category errors
+ * @since 4.0.0
+ */
+StartupError, 
+/**
+ * Error returned by `join` when a running machine is stopped before
+ * producing an output.
+ *
+ * @category errors
+ * @since 4.0.0
+ */
+StoppedError } from "./internal/machineErrors.js";
+const RuntimeRequirementTypeId = "~effect/Machine/RuntimeRequirement";
+const ActionRequirementTypeId = "~effect/Machine/ActionRequirement";
+const RuntimeCompatibilityErrorTypeId = "~effect/Machine/RuntimeCompatibilityError";
+const InvokeTypeId = Symbol.for("effect/Machine/Invoke");
+const SnapshotBuilderStateTypeId = Symbol("effect/Machine/SnapshotBuilderState");
+const ChildAddressTypeId = "~effect/Machine/ChildAddress";
+const ChildAddressCompatibilityErrorTypeId = "~effect/Machine/ChildAddressCompatibilityError";
+const ChildMachineTypeId = "~effect/Machine/ChildMachine";
+const Proto = {
+    ...Inspectable.BaseProto,
+    ...PipeablePrototype,
+    [TypeId]: TypeId,
+    toJSON() {
+        return {
+            _id: "Machine"
+        };
+    }
+};
+const cloneWithHandlers = (self, handlers) => {
+    const machine = Object.create(Proto);
+    machine.states = self.states;
+    machine.events = self.events;
+    machine.emits = self.emits;
+    machine.input = self.input;
+    machine.id = self.id;
+    machine.initial = self.initial;
+    machine.stateNodes = self.stateNodes;
+    machine.makeTargetBuilder = self.makeTargetBuilder;
+    machine.handlers = handlers;
+    machine.handle = makeHandle(machine);
+    return machine;
+};
+const flattenHandlers = (handlers, states, prefix, config) => {
+    for (const key of Object.keys(config)) {
+        const path = prefix === "" ? key : `${prefix}.${key}`;
+        if (!hasProperty(states, key)) {
+            throw new Error(`Machine received handler for unknown state "${path}"`);
+        }
+        const nodeConfig = config[key];
+        if (typeof nodeConfig !== "object" || nodeConfig === null) {
+            throw new Error(`Machine expected state "${path}" handler to be an object`);
+        }
+        const { states: childConfig, ...stateConfig } = nodeConfig;
+        handlers[path] = stateConfig;
+        if (childConfig !== undefined) {
+            const node = Model.getStateNodeDefinition(path, states[key]);
+            if (node.states === undefined) {
+                throw new Error(`Machine expected state "${path}" to declare child states`);
+            }
+            if (typeof childConfig !== "object" || childConfig === null) {
+                throw new Error(`Machine expected state "${path}" child handlers to be an object`);
+            }
+            flattenHandlers(handlers, node.states, path, childConfig);
+        }
+    }
+};
+const makeHandle = (self) => ((config) => {
+    const handlers = Object.assign(Object.create(null), self.handlers);
+    flattenHandlers(handlers, self.states, "", config);
+    return cloneWithHandlers(self, handlers);
+});
+/**
+ * Returns `true` if a value is a `Machine`.
+ *
+ * @category guards
+ * @since 4.0.0
+ */
+export const isMachine = (u) => hasProperty(u, TypeId);
+/**
+ * Returns `true` if a state snapshot is final for a machine.
+ *
+ * @category guards
+ * @since 4.0.0
+ */
+export const isFinal = (machine, state) => internalPlanner.isFinal(machine, state);
+const makeSnapshotBuilder = (states, options) => {
+    const builder = {};
+    for (const key of Object.keys(states)) {
+        builder[key] = (value, selector) => makeSnapshotForNode(states[key], key, value, selector, options);
+    }
+    return builder;
+};
+const makeParallelSnapshotBuilder = (states, options, regions) => {
+    const builder = {};
+    Object.defineProperty(builder, SnapshotBuilderStateTypeId, {
+        value: regions,
+        enumerable: false
+    });
+    for (const key of Object.keys(states)) {
+        if (hasProperty(regions, key)) {
+            continue;
+        }
+        builder[key] = (value, selector) => {
+            const nextRegions = {};
+            for (const regionKey of Object.keys(regions)) {
+                nextRegions[regionKey] = regions[regionKey];
+            }
+            nextRegions[key] = makeSnapshotForNode(states[key], key, value, selector, options);
+            return makeParallelSnapshotBuilder(states, options, nextRegions);
+        };
+    }
+    return builder;
+};
+const getParallelSnapshotBuilderRegions = (path, states, builder) => {
+    if (typeof builder !== "object" || builder === null || !hasProperty(builder, SnapshotBuilderStateTypeId)) {
+        throw new Error(`Machine expected parallel state "${path}" builder callback to return a builder`);
+    }
+    const regions = builder[SnapshotBuilderStateTypeId];
+    for (const key of Object.keys(states)) {
+        if (!hasProperty(regions, key)) {
+            throw new Error(`Machine expected parallel state "${path}" builder callback to provide region "${key}"`);
+        }
+    }
+    return regions;
+};
+const makeSnapshotForNode = (definition, key, value, selector, options) => {
+    const path = options.prefix === "" ? key : `${options.prefix}.${key}`;
+    const node = Model.getStateNodeDefinition(path, definition);
+    const snapshot = {
+        path,
+        value
+    };
+    if (node.states === undefined) {
+        return snapshot;
+    }
+    if (selector === undefined) {
+        throw new Error(`Machine expected state "${path}" builder to provide active child states`);
+    }
+    if (node.type === "parallel") {
+        const builder = makeParallelSnapshotBuilder(node.states, { ...options, prefix: path }, {});
+        snapshot.states = getParallelSnapshotBuilderRegions(path, node.states, selector(builder));
+        return snapshot;
+    }
+    const childStates = options.mode === "initial" && node.initial !== undefined
+        ? { [node.initial]: node.states[node.initial] }
+        : node.states;
+    snapshot.state = selector(makeSnapshotBuilder(childStates, { ...options, prefix: path }));
+    return snapshot;
+};
+const getTargetBuilderNode = (stateNodes, path) => {
+    const node = stateNodes.byPath.get(path);
+    if (node === undefined) {
+        throw new Error(`Machine expected state path "${path}" to exist`);
+    }
+    return node;
+};
+const getLocalTargetScope = (stateNodes, source) => {
+    let current = source;
+    while (current !== undefined) {
+        const node = stateNodes.byPath.get(current);
+        if (node === undefined) {
+            return undefined;
+        }
+        if (node.type === "compound") {
+            return node.path;
+        }
+        current = node.parent;
+    }
+    return undefined;
+};
+const hasTargetValues = (values) => values !== undefined && Object.keys(values).length > 0;
+const makeTargetWithValues = (path, value, values) => hasTargetValues(values)
+    ? Model.makeTarget(path, value, { values: values })
+    : Model.makeTarget(path, value);
+const extendTargetValues = (values, path, value) => {
+    const next = {};
+    if (values !== undefined) {
+        for (const key of Object.keys(values)) {
+            next[key] = values[key];
+        }
+    }
+    next[path] = value;
+    return next;
+};
+const makeLocalTargetChildBuilder = (stateNodes, parentPath, values) => {
+    const parent = getTargetBuilderNode(stateNodes, parentPath);
+    const builder = {};
+    for (const childPath of parent.children) {
+        const child = getTargetBuilderNode(stateNodes, childPath);
+        builder[child.key] = (value, selector) => {
+            if (child.type === "atomic" || child.type === "final") {
+                return makeTargetWithValues(child.path, value, values);
+            }
+            if (selector === undefined) {
+                throw new Error(`Machine expected target "${child.path}" builder to provide an active child state`);
+            }
+            return selector(makeLocalTargetChildBuilder(stateNodes, child.path, extendTargetValues(values, child.path, value)));
+        };
+    }
+    return builder;
+};
+const makeLocalTargetBuilder = (stateNodes, source) => {
+    const scope = getLocalTargetScope(stateNodes, source);
+    if (scope === undefined) {
+        return {};
+    }
+    const builder = makeLocalTargetChildBuilder(stateNodes, scope, undefined);
+    builder.with = (value, selector) => {
+        if (selector === undefined) {
+            throw new Error(`Machine expected target "${scope}" builder to provide an active child state`);
+        }
+        return selector(makeLocalTargetChildBuilder(stateNodes, scope, { [scope]: value }));
+    };
+    return builder;
+};
+const addBranchTargetChildren = (builder, stateNodes, parentPath, values) => {
+    const parent = getTargetBuilderNode(stateNodes, parentPath);
+    for (const childPath of parent.children) {
+        const child = getTargetBuilderNode(stateNodes, childPath);
+        builder[child.key] = makeBranchTargetNodeBuilder(stateNodes, child.path, values);
+    }
+};
+const makeBranchTargetNodeBuilder = (stateNodes, path, values) => {
+    const node = getTargetBuilderNode(stateNodes, path);
+    if (node.type === "atomic" || node.type === "final") {
+        return (value) => makeTargetWithValues(node.path, value, values);
+    }
+    const builder = ((value, selector) => {
+        if (selector === undefined) {
+            throw new Error(`Machine expected target "${node.path}" builder to provide an active child state`);
+        }
+        const nextBuilder = {};
+        addBranchTargetChildren(nextBuilder, stateNodes, node.path, extendTargetValues(values, node.path, value));
+        return selector(nextBuilder);
+    });
+    addBranchTargetChildren(builder, stateNodes, node.path, values);
+    return builder;
+};
+const makeBranchTargetBuilder = (stateNodes, source) => {
+    const rootPath = source.split(".")[0];
+    const root = getTargetBuilderNode(stateNodes, rootPath);
+    return {
+        [root.key]: makeBranchTargetNodeBuilder(stateNodes, root.path, undefined)
+    };
+};
+const makeTargetBuilder = (states, stateNodes) => {
+    const full = makeSnapshotBuilder(states, { mode: "full", prefix: "" });
+    return (source) => ({
+        local: makeLocalTargetBuilder(stateNodes, source),
+        branch: makeBranchTargetBuilder(stateNodes, source),
+        full
+    });
+};
+const getSnapshotByPath = (snapshot, path, parents) => {
+    if (snapshot.path === path) {
+        return Option.some(snapshot);
+    }
+    if (!path.startsWith(`${snapshot.path}.`)) {
+        return Option.none();
+    }
+    if (parents !== undefined) {
+        parents[snapshot.path] = snapshot.value;
+    }
+    if (hasProperty(snapshot, "state") && Model.isSnapshot(snapshot.state)) {
+        return getSnapshotByPath(snapshot.state, path, parents);
+    }
+    if (hasProperty(snapshot, "states") && typeof snapshot.states === "object" && snapshot.states !== null) {
+        for (const child of Object.values(snapshot.states)) {
+            if (Model.isSnapshot(child)) {
+                const result = getSnapshotByPath(child, path, parents);
+                if (Option.isSome(result)) {
+                    return result;
+                }
+            }
+        }
+    }
+    return Option.none();
+};
+/**
+ * Defines a state tree while preserving literal state paths.
+ *
+ * **When to use**
+ *
+ * Use when you want to pass a state tree to `make` and also get typed
+ * snapshot builders for initial states and tests.
+ *
+ * **Details**
+ *
+ * The returned `states` property is the same object passed to `defineStates`.
+ * The returned `initial` builder creates snapshots without user-authored path
+ * strings and enforces compound and parallel initial-state rules.
+ *
+ * **Example** (Atomic initial snapshot)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ * import { Machine } from "effect/unstable/machine"
+ *
+ * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
+ *
+ * const States = Machine.defineStates({ idle: Idle })
+ *
+ * Machine.make({
+ *   states: States.states,
+ *   events: [],
+ *   initial: () => States.initial.idle(new Idle({}))
+ * })
+ * ```
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const defineStates = (states, ..._validation) => ({
+    states: states,
+    initial: makeSnapshotBuilder(states, { mode: "initial", prefix: "" }),
+    get: ((snapshot, path) => getSnapshotByPath(snapshot, path).pipe(Option.map((snapshot) => snapshot.value))),
+    getWithParents: ((snapshot, path) => {
+        const parents = {};
+        return getSnapshotByPath(snapshot, path, parents).pipe(Option.map((snapshot) => ({ value: snapshot.value, parents })));
+    }),
+    getSnapshot: getSnapshotByPath,
+    matches: (snapshot, path) => Option.isSome(getSnapshotByPath(snapshot, path))
+});
+/**
+ * Creates a schema-first machine definition.
+ *
+ * **Details**
+ *
+ * State and event schemas provide runtime boundary validation while their
+ * decoded types drive handler, state, event, target, error, and service
+ * inference. State-tree validation is applied whether `states` comes from
+ * `defineStates` or is passed inline. Call `handle` on the returned definition
+ * to implement state behavior with ordinary TypeScript control flow.
+ *
+ * **Example** (Typed counter machine)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ * import { Machine } from "effect/unstable/machine"
+ *
+ * class Count extends Schema.TaggedClass<Count>("Count")("Count", {
+ *   value: Schema.Number
+ * }) {}
+ *
+ * class Increment extends Schema.TaggedClass<Increment>("Increment")("Increment", {
+ *   by: Schema.Number
+ * }) {}
+ *
+ * const States = Machine.defineStates({ Count })
+ *
+ * const counter = Machine.make({
+ *   states: States.states,
+ *   events: [Increment],
+ *   initial: () => States.initial.Count(new Count({ value: 0 }))
+ * }).handle({
+ *   Count: {
+ *     on: {
+ *       Increment: ({ event, state }) =>
+ *         States.initial.Count(new Count({ value: state.value + event.by }))
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @see {@link defineStates} for typed initial snapshot builders.
+ * @category constructors
+ * @since 4.0.0
+ */
+export const make = (config, ..._validation) => {
+    const self = Object.create(Proto);
+    self.states = config.states;
+    self.events = config.events;
+    self.emits = config.emits ?? [];
+    self.input = config.input;
+    self.id = config.id;
+    self.initial = config.initial;
+    self.stateNodes = Model.compileStateNodes(config.states);
+    self.makeTargetBuilder = makeTargetBuilder(config.states, self.stateNodes);
+    self.handlers = Object.create(null);
+    self.handle = makeHandle(self);
+    return self;
+};
+/**
+ * Encodes a decoded machine snapshot into a normalized data representation.
+ *
+ * **When to use**
+ *
+ * Use when you need to store or transport a statechart snapshot independently
+ * of its local machine runtime.
+ *
+ * **Details**
+ *
+ * Each active state value and completed output is encoded with the schema
+ * declared for its state path. The result contains no process-local runtime
+ * state.
+ *
+ * **Gotchas**
+ *
+ * The encoded snapshot does not contain the machine definition, machine
+ * version, running children, invoked process state, services, or subscriptions.
+ * Store machine identity and migration metadata alongside the result when the
+ * snapshot crosses deployment versions. Schema encoding does not by itself
+ * guarantee JSON-compatible values; schemas used with JSON-backed storage must
+ * have JSON-compatible encoded representations.
+ *
+ * @see {@link decodeSnapshot} for restoring an encoded snapshot.
+ * @category encoding
+ * @since 4.0.0
+ */
+export const encodeSnapshot = Model.encodeSnapshot;
+/**
+ * Decodes a normalized data representation into a validated machine snapshot.
+ *
+ * **When to use**
+ *
+ * Use when you need to resume planning from a snapshot loaded from storage or
+ * received over a transport boundary.
+ *
+ * **Details**
+ *
+ * Decoding resolves every path against the supplied machine, decodes values
+ * with their state and output schemas, validates compound and parallel state
+ * relationships, and rebuilds the recursive in-memory snapshot.
+ *
+ * **Gotchas**
+ *
+ * Decoding restores logical statechart data only. It does not restart invoked
+ * processes, recreate spawned children, or restore a previous `MachineRef`.
+ *
+ * @see {@link encodeSnapshot} for creating the normalized representation.
+ * @category decoding
+ * @since 4.0.0
+ */
+export const decodeSnapshot = Model.decodeSnapshot;
+/**
+ * Creates an invoked child process configuration for an active state.
+ *
+ * **When to use**
+ *
+ * Use to run a child process while a machine remains in a state. Successful
+ * outputs are sent directly to the parent machine as events; `void` sends
+ * nothing. Unrecovered child failures fail the owning machine. Active
+ * snapshots can optionally be mapped to progress events.
+ *
+ * **Gotchas**
+ *
+ * Invoked child processes run while their owning state is active and are
+ * stopped before the state exits. An unrecovered child failure fails the owning
+ * machine; recover inside the child Effect when failure should become an event.
+ * The `src` callback is intentionally independent from its parent state. When
+ * construction depends on the typed state, lifecycle event, or runtime, use
+ * the state config factory form `invoke: (context) => Machine.invoke(...)` and
+ * close over that context from `src`.
+ *
+ * **Example** (Effect output as a parent event)
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import { Machine } from "effect/unstable/machine"
+ *
+ * class Loaded extends Schema.TaggedClass<Loaded>("Loaded")("Loaded", {
+ *   value: Schema.String
+ * }) {}
+ *
+ * const load = Machine.invoke({
+ *   id: "load",
+ *   src: () => Machine.effect(Effect.succeed(new Loaded({ value: "ready" })))
+ * })
+ * ```
+ *
+ * @see {@link effect} for one-shot child effects.
+ * @see {@link spawn} for children whose lifetime is controlled by actions.
+ * @category constructors
+ * @since 4.0.0
+ */
+export const invoke = (config) => ({ ...config, [InvokeTypeId]: undefined });
+/**
+ * Creates an invoked child process from a complete statechart machine.
+ *
+ * **When to use**
+ *
+ * Use when a state should own another statechart machine and communicate with
+ * it through typed child events, emissions, snapshots, or terminal output.
+ *
+ * **Details**
+ *
+ * Child emissions are delivered directly to the parent as events. Active
+ * snapshots and terminal output can be mapped to parent events. The owning
+ * state controls the child lifetime.
+ *
+ * **Gotchas**
+ *
+ * Active invoked machines must have unique child addresses. A machine starts
+ * after its owning state's entry actions, so those actions cannot send events
+ * to a newly entered child. Unrecovered child failures fail the parent.
+ *
+ * @see {@link invoke} for invoking lower-level process logic.
+ * @see {@link sendTo} for sending events to the invoked machine.
+ * @category constructors
+ * @since 4.0.0
+ */
+export const invokeMachine = ((config) => {
+    const machine = config.child.machine;
+    return {
+        id: config.child.id,
+        addressable: true,
+        src: () => machine.input === undefined
+            ? internalProcess.toProcessLogic(machine)
+            : internalProcess.toProcessLogic(machine, config.input),
+        snapshot: config.snapshot,
+        onDone: config.onDone,
+        [InvokeTypeId]: undefined
+    };
+});
+/**
+ * Plans the initial state for a machine without running deferred actions.
+ *
+ * **Details**
+ *
+ * The returned plan contains the settled initial snapshot, staged actions,
+ * emitted events, and optional final output. Planning may evaluate transition
+ * logic and follow completion, eventless, and raised-event steps, but it does
+ * not execute effects passed to `action`.
+ *
+ * **Gotchas**
+ *
+ * Callers that execute a plan manually must run actions sequentially before
+ * publishing its state or delivering its emitted events. `start` performs this
+ * protocol automatically.
+ *
+ * @see {@link plan} for planning a received event.
+ * @see {@link start} for the managed runtime protocol.
+ * @category constructors
+ * @since 4.0.0
+ */
+export const planInitial = internalPlanner.planInitial;
+/**
+ * Returns the event tags handled by the current state snapshot.
+ *
+ * @category getters
+ * @since 4.0.0
+ */
+export const enabled = (machine, state) => internalPlanner.enabled(machine, state);
+/**
+ * Plans the next state snapshot without running deferred actions.
+ *
+ * **Details**
+ *
+ * Planning selects child transitions before conflicting ancestors, permits
+ * non-conflicting transitions in parallel regions, processes completion and
+ * eventless transitions, and drains raised events in FIFO order. Exit paths
+ * are deepest-first and entry paths are parent-first.
+ *
+ * **Gotchas**
+ *
+ * `plan` returns data; it does not implement the runtime commit protocol. Run
+ * actions sequentially, publish `next` only after they succeed, and then
+ * deliver `emittedEvents`. A failed action must retain the previously
+ * published state and suppress emissions. Events with no enabled transition
+ * are ignored and produce an unchanged plan.
+ *
+ * @see {@link planInitial} for planning machine startup.
+ * @see {@link start} for managed execution and lifecycle observation.
+ * @category combinators
+ * @since 4.0.0
+ */
+export const plan = internalPlanner.plan;
+/**
+ * Defers an effectful action until the current machine step is planned.
+ *
+ * **Details**
+ *
+ * The action's error and service requirements are retained in the machine
+ * type without becoming requirements of `plan` or `planInitial`. The managed
+ * runtime executes staged actions sequentially before publishing the planned
+ * state.
+ *
+ * **Example** (Typed staged action)
+ *
+ * ```ts
+ * import { Context, Effect } from "effect"
+ * import { Machine } from "effect/unstable/machine"
+ *
+ * class Audit extends Context.Service<Audit, {
+ *   readonly write: Effect.Effect<void, "AuditError">
+ * }>()("example/Audit") {}
+ *
+ * const writeAudit = Machine.action(
+ *   Effect.flatMap(Audit, (audit) => audit.write)
+ * )
+ * ```
+ *
+ * @see {@link plan} for inspecting staged actions without executing them.
+ * @category combinators
+ * @since 4.0.0
+ */
+export const action = (effect) => internalPlanner.action(effect);
+const processLocal = (operation) => Effect.die(new ProcessLocalErrorValue({ operation }));
+const standaloneProcessRuntime = internalRuntime.MachineRuntime.of({
+    self: {
+        id: "Machine.runActions",
+        sessionId: "Machine.runActions",
+        stop: processLocal("stop self"),
+        send: () => processLocal("send to self")
+    },
+    parent: undefined,
+    spawn: () => processLocal("spawn"),
+    sendParent: () => processLocal("send to parent"),
+    sendTo: () => processLocal("send to child"),
+    stopChild: () => processLocal("stop child"),
+    failCause: () => processLocal("fail process")
+});
+/**
+ * Runs staged machine actions sequentially with the supplied runtime.
+ *
+ * **When to use**
+ *
+ * Use when you implement a commit protocol around `plan` or `planInitial` and
+ * need to execute their staged actions before publishing the planned snapshot.
+ *
+ * **Gotchas**
+ *
+ * This function only runs actions. The caller remains responsible for
+ * publishing the planned state and delivering planned emitted events after all
+ * actions succeed. Process-local operations such as `spawn`, `sendTo`, and
+ * `stopChild` fail with `ProcessLocalError` because no managed machine process
+ * owns the actions.
+ *
+ * @see {@link plan} for creating a transition plan.
+ * @see {@link planInitial} for creating an initial plan.
+ * @category running
+ * @since 4.0.0
+ */
+export const runActions = (actions, runtime) => internalRuntime.provideMachineRuntime(internalPlanner.runActions(actions, runtime), standaloneProcessRuntime).pipe(Effect.catchDefect((defect) => defect instanceof ProcessLocalErrorValue
+    ? Effect.fail(defect)
+    : Effect.die(defect)));
+/**
+ * Returns the typed runtime capability for the current machine.
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+export const runtime = () => internalPlanner.runtime();
+/**
+ * Creates a one-shot child process from an Effect.
+ *
+ * **When to use**
+ *
+ * Use when you need side effects that produce one typed output or error.
+ *
+ * **Details**
+ *
+ * The Effect may run arbitrary side effects. Its success value is the process
+ * output, its typed error is preserved, and its services are inferred. When
+ * invoked, the output is sent to the owning machine as an event unless it is
+ * `void`.
+ *
+ * **Gotchas**
+ *
+ * This process has no incoming event protocol. Its Effect runs once. Use
+ * `transition` for a process that receives events over time and `logic` for
+ * direct machine-local communication or intermediate snapshots.
+ *
+ * **Example** (Recover a child failure as output)
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import { Machine } from "effect/unstable/machine"
+ *
+ * class LoadFailed extends Schema.TaggedClass<LoadFailed>("LoadFailed")("LoadFailed", {
+ *   reason: Schema.String
+ * }) {}
+ *
+ * const load = Machine.effect(
+ *   Effect.fail("unavailable").pipe(
+ *     Effect.catch((reason) => Effect.succeed(new LoadFailed({ reason })))
+ *   )
+ * )
+ * ```
+ *
+ * @see {@link transition} for event-driven state.
+ * @see {@link logic} for direct control over intermediate snapshots.
+ * @category constructors
+ * @since 4.0.0
+ */
+export const effect = (effect) => ({
+    initial: () => Effect.void,
+    run: () => effect
+});
+/**
+ * Creates advanced stateful process logic from explicit initialization and
+ * execution methods.
+ *
+ * **When to use**
+ *
+ * Use when you need a machine-scoped process to publish intermediate snapshots
+ * directly.
+ *
+ * **Details**
+ *
+ * Initialization produces the first state before `run` starts. The running
+ * context receives events, reads or updates state, manages child processes,
+ * and can communicate with its owning machine. Errors and service requirements
+ * from both phases remain in the returned `Logic` type.
+ *
+ * **Gotchas**
+ *
+ * This is the low-level process constructor. Parent messages sent directly
+ * through its scope are intentionally `unknown` because the logic does not know
+ * which machine will eventually own it. Prefer typed output, typed child
+ * addresses, or invoke snapshot mapping when possible.
+ *
+ * @see {@link effect} for one-shot work.
+ * @see {@link transition} for event-driven state.
+ * @category constructors
+ * @since 4.0.0
+ */
+export const logic = (options) => ({
+    initial: (scope) => typeof options.initial === "function"
+        ? options.initial(scope)
+        : Effect.succeed(options.initial),
+    run: options.run
+});
+/**
+ * Creates child process logic from an initial state and a transition function.
+ *
+ * **When to use**
+ *
+ * Use when a child process only needs sequential event-driven state updates and
+ * does not need direct control over intermediate snapshots or child ownership.
+ *
+ * **Details**
+ *
+ * Each received event runs the transition Effect against the latest state. The
+ * resulting state is published before the next queued event is processed.
+ *
+ * @see {@link effect} for one-shot work.
+ * @see {@link logic} for direct process lifecycle control.
+ * @category constructors
+ * @since 4.0.0
+ */
+export const transition = (initial, transition) => logic({
+    initial,
+    run: ({ receive, updateState }) => receive.pipe(Effect.flatMap((event) => updateState((state) => transition(state, event))), Effect.forever)
+});
+/**
+ * Creates a typed parent-local child address or complete machine descriptor.
+ *
+ * **When to use**
+ *
+ * Use with a complete machine to create the descriptor shared by
+ * `invokeMachine`, `sendTo`, and child lookup APIs. The one-argument form
+ * creates an event-only address for lower-level process logic.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export const child = ((id, machine) => machine === undefined
+    ? id
+    : { [ChildMachineTypeId]: ChildMachineTypeId, id, machine });
+/**
+ * Spawns a child process owned by the currently running machine.
+ *
+ * **When to use**
+ *
+ * Use to create child processes from machine actions when the child
+ * should be addressed or stopped by the owning machine instead of tied to a
+ * single state's `invoke` lifecycle.
+ *
+ * **Gotchas**
+ *
+ * This effect requires the machine runtime, so it only runs from machine
+ * actions. A named child id must be unique for the current parent machine until
+ * that child stops.
+ *
+ * @see {@link invoke} for children that start and stop with a state.
+ * @see {@link sendTo} for sending events to named children.
+ * @category runtime
+ * @since 4.0.0
+ */
+export const spawn = ((logic, options) => Effect.flatMap(internalRuntime.MachineRuntime, (runtime) => options === undefined ? runtime.spawn(logic) : runtime.spawn(logic, options)));
+/**
+ * Sends an event to a named child process of the running machine.
+ *
+ * @category runtime
+ * @since 4.0.0
+ */
+export const sendTo = ((child, event) => Effect.flatMap(internalRuntime.MachineRuntime, (runtime) => runtime.sendTo(typeof child === "string" ? child : child.id, event)));
+/**
+ * Stops a named child process of the running machine.
+ *
+ * @category runtime
+ * @since 4.0.0
+ */
+export const stopChild = ((child) => Effect.flatMap(internalRuntime.MachineRuntime, (runtime) => runtime.stopChild(typeof child === "string" ? child : child.id)));
+/**
+ * Returns a stream of terminal lifecycle outcomes for a running machine.
+ *
+ * @category combinators
+ * @since 4.0.0
+ */
+export const watch = (ref) => internalRuntime.watch(ref);
+/**
+ * Starts a machine.
+ *
+ * **When to use**
+ *
+ * Use when you want asynchronous event delivery, lifecycle snapshots, `join`,
+ * and machine-owned spawned or invoked children.
+ *
+ * **Details**
+ *
+ * For each accepted event the runtime plans the complete macrostep, runs staged
+ * actions sequentially, stops invokes for exited states, publishes the new
+ * state, delivers emitted events, and then starts invokes for entered states.
+ * If an action fails, the previous published state is retained and emissions
+ * from that plan are suppressed.
+ *
+ * **Gotchas**
+ *
+ * The returned handle's `send` operation only enqueues events. Transition
+ * failures are reported through the runtime snapshot, `changes`, and `join`
+ * rather than being returned by `send`. Sending after the machine reaches any
+ * terminal state fails immediately with `StoppedError`.
+ *
+ * @see {@link plan} for inspecting the same transition plan without executing it.
+ * @see {@link watch} for classified terminal outcomes.
+ * @category constructors
+ * @since 4.0.0
+ */
+export const start = internalProcess.start;
+//# sourceMappingURL=Machine.js.map