@typeonce/effect-machine 0.3.0 → 0.5.0

package/dist/Machine.js

@@ -1,23 +1,16 @@
 /**
  * Schema-first machine definitions.
  *
- * @since 4.0.0
+ * @since 0.4.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";
+import * as internal from "./internal/machine/machine.js";
+import { InitialEventTypeId } from "./internal/machine/machine.js";
 /**
  * Runtime type identifier attached to `Machine` values.
  *
  * @category type IDs
- * @since 4.0.0
+ * @since 0.4.0
  */
 export const TypeId = "~effect/Machine";
 /**
@@ -25,21 +18,21 @@ export const TypeId = "~effect/Machine";
  * actions.
  *
  * @category type IDs
- * @since 4.0.0
+ * @since 0.4.0
  */
-export const InitialEventTypeId = internalPlanner.InitialEventTypeId;
+export { InitialEventTypeId };
 /**
  * Synthetic event value used while the machine settles its initial state.
  *
  * @category constructors
- * @since 4.0.0
+ * @since 0.4.0
  */
-export const InitialEvent = internalPlanner.InitialEvent;
+export const InitialEvent = { _tag: InitialEventTypeId };
 /**
  * Returns `true` if a value is the synthetic machine initial event.
  *
  * @category guards
- * @since 4.0.0
+ * @since 0.4.0
  */
 export const isInitialEvent = (u) => hasProperty(u, "_tag") && u._tag === InitialEventTypeId;
 export { 
@@ -48,7 +41,7 @@ export {
  * exists for the current machine.
  *
  * @category errors
- * @since 4.0.0
+ * @since 0.4.0
  */
 ChildAlreadyExistsError, 
 /**
@@ -56,7 +49,7 @@ ChildAlreadyExistsError,
  * number of macrostep iterations.
  *
  * @category errors
- * @since 4.0.0
+ * @since 0.4.0
  */
 InfiniteTransitionError, 
 /**
@@ -64,7 +57,7 @@ InfiniteTransitionError,
  * structural configuration declared for a machine boundary.
  *
  * @category errors
- * @since 4.0.0
+ * @since 0.4.0
  */
 MachineSchemaDecodeError, 
 /**
@@ -72,7 +65,7 @@ MachineSchemaDecodeError,
  * its declared state or output schemas.
  *
  * @category errors
- * @since 4.0.0
+ * @since 0.4.0
  */
 MachineSchemaEncodeError, 
 /**
@@ -80,7 +73,7 @@ MachineSchemaEncodeError,
  * requires a managed machine process.
  *
  * @category errors
- * @since 4.0.0
+ * @since 0.4.0
  */
 ProcessLocalError, 
 /**
@@ -88,7 +81,7 @@ ProcessLocalError,
  * logic after the initial state has been computed.
  *
  * @category errors
- * @since 4.0.0
+ * @since 0.4.0
  */
 StartupError, 
 /**
@@ -96,359 +89,31 @@ StartupError,
  * producing an output.
  *
  * @category errors
- * @since 4.0.0
+ * @since 0.4.0
  */
-StoppedError } from "./internal/machineErrors.js";
+StoppedError } from "./internal/machine/machine.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 InvokeTypeId = internal.InvokeTypeId;
+const SnapshotBuilderStateTypeId = internal.SnapshotBuilderStateTypeId;
 const SnapshotBuilderConstructionTypeId = Symbol("effect/Machine/SnapshotBuilderConstruction");
 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.internalEvents = self.internalEvents;
-    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);
-    Model.copyProtocol(self, 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
+ * @since 0.4.0
  */
-export const isMachine = (u) => hasProperty(u, TypeId);
+export const isMachine = internal.isMachine;
 /**
  * Returns `true` if a state snapshot is final for a machine.
  *
  * @category guards
- * @since 4.0.0
+ * @since 0.4.0
  */
-export const isFinal = (machine, state) => internalPlanner.isFinal(machine, state);
-const withFrom = (method, kind) => {
-    Object.defineProperty(method, "from", {
-        value: (...args) => {
-            const omitted = args.length === 0 || (kind === "nested" && args.length === 1 && typeof args[0] === "function");
-            const input = omitted ? {} : args[0];
-            const rest = omitted ? args : args.slice(1);
-            return Model.markStateConstruction(method(Model.makeStateInput(input), ...rest));
-        },
-        enumerable: false
-    });
-    return method;
-};
-const makeSnapshotBuilder = (states, options) => {
-    const builder = {};
-    for (const key of Object.keys(states)) {
-        if (states[key].type === "history") {
-            continue;
-        }
-        const path = options.prefix === "" ? key : `${options.prefix}.${key}`;
-        const node = Model.getStateNodeDefinition(path, states[key]);
-        builder[key] = withFrom((value, selector) => makeSnapshotForNode(states[key], key, value, selector, options), node.states === undefined ? "leaf" : "nested");
-    }
-    return builder;
-};
-const makeParallelSnapshotBuilder = (states, options, regions) => {
-    const builder = {};
-    Object.defineProperty(builder, SnapshotBuilderStateTypeId, {
-        value: regions,
-        enumerable: false
-    });
-    Object.defineProperty(builder, SnapshotBuilderConstructionTypeId, {
-        value: Model.isStateConstruction(builder),
-        enumerable: false
-    });
-    for (const key of Object.keys(states)) {
-        if (states[key].type === "history") {
-            continue;
-        }
-        if (hasProperty(regions, key)) {
-            continue;
-        }
-        const path = options.prefix === "" ? key : `${options.prefix}.${key}`;
-        const node = Model.getStateNodeDefinition(path, states[key]);
-        builder[key] = withFrom((value, selector) => {
-            const nextRegions = {};
-            for (const regionKey of Object.keys(regions)) {
-                nextRegions[regionKey] = regions[regionKey];
-            }
-            nextRegions[key] = makeSnapshotForNode(states[key], key, value, selector, options);
-            const next = makeParallelSnapshotBuilder(states, options, nextRegions);
-            return Model.isStateConstruction(builder) ? Model.markStateConstruction(next) : next;
-        }, node.states === undefined ? "leaf" : "nested");
-    }
-    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 (states[key].type === "history") {
-            continue;
-        }
-        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 }, {});
-        const selected = selector(builder);
-        snapshot.states = getParallelSnapshotBuilderRegions(path, node.states, selected);
-        return Model.isStateConstruction(selected) ? Model.markStateConstruction(snapshot) : snapshot;
-    }
-    const childStates = options.mode === "initial" && node.initial !== undefined
-        ? { [node.initial]: node.states[node.initial] }
-        : node.states;
-    const selected = selector(makeSnapshotBuilder(childStates, { ...options, prefix: path }));
-    snapshot.state = selected;
-    return Model.isStateConstruction(selected) ? Model.markStateConstruction(snapshot) : 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 getTargetBuilderDefinition = (states, targetPath) => {
-    let children = states;
-    let path = "";
-    let definition;
-    for (const key of targetPath.split(".")) {
-        if (!hasProperty(children, key)) {
-            throw new Error(`Machine expected state path "${targetPath}" to exist`);
-        }
-        definition = children[key];
-        path = path === "" ? key : `${path}.${key}`;
-        const node = Model.getStateNodeDefinition(path, definition);
-        children = node.states ?? {};
-    }
-    return definition;
-};
-const makeParallelTarget = (states, node, value, selector, values) => {
-    if (selector === undefined) {
-        throw new Error(`Machine expected parallel target "${node.path}" builder to provide every active region`);
-    }
-    const snapshot = makeSnapshotForNode(getTargetBuilderDefinition(states, node.path), node.key, value, selector, { mode: "full", prefix: node.parent ?? "" });
-    return Model.makeTarget(node.path, value, {
-        snapshot: snapshot,
-        values: values
-    });
-};
-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 = (states, stateNodes, parentPath, values, source) => {
-    const parent = getTargetBuilderNode(stateNodes, parentPath);
-    const builder = {};
-    for (const childPath of parent.children) {
-        const child = getTargetBuilderNode(stateNodes, childPath);
-        builder[child.key] = withFrom((value, selector) => {
-            if (child.type === "atomic" || child.type === "final") {
-                return makeTargetWithValues(child.path, value, values);
-            }
-            if (child.type === "parallel") {
-                if (source !== child.path && !source.startsWith(`${child.path}.`)) {
-                    return makeParallelTarget(states, child, value, selector, values);
-                }
-                if (selector === undefined) {
-                    throw new Error(`Machine expected target "${child.path}" builder to provide an active child state`);
-                }
-                return selector(makeLocalTargetChildBuilder(states, stateNodes, child.path, extendTargetValues(values, child.path, value), source));
-            }
-            if (selector === undefined) {
-                throw new Error(`Machine expected target "${child.path}" builder to provide an active child state`);
-            }
-            return selector(makeLocalTargetChildBuilder(states, stateNodes, child.path, extendTargetValues(values, child.path, value), source));
-        }, child.type === "atomic" || child.type === "final" ? "leaf" : "nested");
-    }
-    return builder;
-};
-const makeLocalTargetBuilder = (states, stateNodes, source) => {
-    const scope = getLocalTargetScope(stateNodes, source);
-    if (scope === undefined) {
-        return {};
-    }
-    const builder = makeLocalTargetChildBuilder(states, stateNodes, scope, undefined, source);
-    builder.with = withFrom((value, selector) => {
-        if (selector === undefined) {
-            throw new Error(`Machine expected target "${scope}" builder to provide an active child state`);
-        }
-        return selector(makeLocalTargetChildBuilder(states, stateNodes, scope, { [scope]: value }, source));
-    }, "nested");
-    return builder;
-};
-const addBranchTargetChildren = (builder, states, stateNodes, parentPath, values, source) => {
-    const parent = getTargetBuilderNode(stateNodes, parentPath);
-    for (const childPath of parent.children) {
-        const child = getTargetBuilderNode(stateNodes, childPath);
-        builder[child.key] = makeBranchTargetNodeBuilder(states, stateNodes, child.path, values, source);
-    }
-};
-const makeBranchTargetNodeBuilder = (states, stateNodes, path, values, source) => {
-    const node = getTargetBuilderNode(stateNodes, path);
-    if (node.type === "atomic" || node.type === "final") {
-        return withFrom((value) => makeTargetWithValues(node.path, value, values), "leaf");
-    }
-    const builder = withFrom((value, selector) => {
-        if (node.type === "parallel") {
-            if (source !== node.path && !source.startsWith(`${node.path}.`)) {
-                return makeParallelTarget(states, node, value, selector, values);
-            }
-            if (selector === undefined) {
-                throw new Error(`Machine expected target "${node.path}" builder to provide an active child state`);
-            }
-            const nextBuilder = {};
-            addBranchTargetChildren(nextBuilder, states, stateNodes, node.path, extendTargetValues(values, node.path, value), source);
-            return selector(nextBuilder);
-        }
-        if (selector === undefined) {
-            throw new Error(`Machine expected target "${node.path}" builder to provide an active child state`);
-        }
-        const nextBuilder = {};
-        addBranchTargetChildren(nextBuilder, states, stateNodes, node.path, extendTargetValues(values, node.path, value), source);
-        return selector(nextBuilder);
-    }, "nested");
-    if (node.type !== "parallel" || source === node.path || source.startsWith(`${node.path}.`)) {
-        addBranchTargetChildren(builder, states, stateNodes, node.path, values, source);
-    }
-    return builder;
-};
-const makeBranchTargetBuilder = (states, stateNodes, source) => {
-    const rootPath = source.split(".")[0];
-    const root = getTargetBuilderNode(stateNodes, rootPath);
-    return {
-        [root.key]: makeBranchTargetNodeBuilder(states, stateNodes, root.path, undefined, source)
-    };
-};
-const makeHistoryTargetBuilder = (states, prefix) => {
-    const builder = {};
-    for (const key of Object.keys(states)) {
-        const path = prefix === "" ? key : `${prefix}.${key}`;
-        const definition = states[key];
-        if (definition.type === "history") {
-            const parent = getParentPathRuntime(path);
-            builder[key] = () => Model.makeHistoryTarget(path, parent);
-            continue;
-        }
-        if (typeof definition === "object" && definition !== null && hasProperty(definition, "states")) {
-            builder[key] = makeHistoryTargetBuilder(definition.states, path);
-        }
-    }
-    return builder;
-};
-const getParentPathRuntime = (path) => {
-    const separator = path.lastIndexOf(".");
-    if (separator < 0) {
-        throw new Error(`Machine expected history state "${path}" to have an active parent`);
-    }
-    return path.slice(0, separator);
-};
-const makeTargetBuilder = (states, stateNodes) => {
-    const full = makeSnapshotBuilder(states, { mode: "full", prefix: "" });
-    const history = makeHistoryTargetBuilder(states, "");
-    return (source) => ({
-        local: makeLocalTargetBuilder(states, stateNodes, source),
-        branch: makeBranchTargetBuilder(states, stateNodes, source),
-        full,
-        history
-    });
-};
+export const isFinal = internal.isFinal;
 /**
  * Defines a state tree while preserving literal state paths.
  *
@@ -481,19 +146,9 @@ const makeTargetBuilder = (states, stateNodes) => {
  * ```
  *
  * @category constructors
- * @since 4.0.0
+ * @since 0.4.0
  */
-export const defineStates = ((states) => ({
-    states: states,
-    initial: makeSnapshotBuilder(states, { mode: "initial", prefix: "" }),
-    get: ((snapshot, path) => Model.getSnapshotByPath(snapshot, path).pipe(Option.map((snapshot) => snapshot.value))),
-    getWithParents: ((snapshot, path) => {
-        const parents = {};
-        return Model.getSnapshotByPath(snapshot, path, parents).pipe(Option.map((snapshot) => ({ value: snapshot.value, parents })));
-    }),
-    getSnapshot: Model.getSnapshotByPath,
-    matches: (snapshot, path) => Option.isSome(Model.getSnapshotByPath(snapshot, path))
-}));
+export const defineStates = internal.defineStates;
 /**
  * Creates a schema-first machine definition.
  *
@@ -542,24 +197,49 @@ export const defineStates = ((states) => ({
  *
  * @see {@link defineStates} for typed initial snapshot builders.
  * @category constructors
- * @since 4.0.0
+ * @since 0.4.0
  */
-export const make = ((config) => {
-    const self = Object.create(Proto);
-    self.states = config.states;
-    self.events = config.events;
-    self.internalEvents = config.internalEvents ?? [];
-    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);
-    Model.setProtocol(self);
-    return self;
-});
+export const make = internal.make;
+/**
+ * Constructs an event from a schema owned by a machine's protocol.
+ *
+ * **Details**
+ *
+ * The schema constructor runs exactly once. The resulting decoded event is
+ * trusted by this machine and definitions derived from it with `handle`, so
+ * repeated delivery does not decode the same already-constructed value again.
+ * Events supplied through ordinary `send` and `plan` calls remain untrusted
+ * and continue through full runtime schema validation.
+ * Treat the returned event as immutable after construction.
+ *
+ * The schema must be one of the machine's configured public or internal event
+ * schemas, or a case schema belonging to a configured `Schema.TaggedUnion`.
+ *
+ * **Example**
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ * import { Machine } from "@typeonce/effect-machine"
+ *
+ * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
+ * class Increment extends Schema.TaggedClass<Increment>("Increment")("Increment", {
+ *   by: Schema.Number
+ * }) {}
+ *
+ * const States = Machine.defineStates({ Idle })
+ * const counter = Machine.make({
+ *   states: States.states,
+ *   events: [Increment],
+ *   initial: () => States.initial.Idle.from()
+ * }).handle({ Idle: { on: { Increment: () => States.initial.Idle.from() } } })
+ *
+ * const increment = Machine.event(counter, Increment, { by: 1 })
+ * ```
+ *
+ * @category constructors
+ * @since 0.4.0
+ */
+export const event = internal.event;
 /**
  * Encodes a decoded machine snapshot into a normalized data representation.
  *
@@ -583,11 +263,31 @@ export const make = ((config) => {
  * guarantee JSON-compatible values; schemas used with JSON-backed storage must
  * have JSON-compatible encoded representations.
  *
+ * **Example**
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import { Machine } from "@typeonce/effect-machine"
+ *
+ * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
+ * const States = Machine.defineStates({ Idle })
+ * const machine = Machine.make({
+ *   states: States.states,
+ *   events: [],
+ *   initial: () => States.initial.Idle.from()
+ * }).handle({ Idle: {} })
+ *
+ * const encoded = Effect.gen(function*() {
+ *   const initial = yield* Machine.planInitial(machine)
+ *   return yield* Machine.encodeSnapshot(machine, initial.state)
+ * })
+ * ```
+ *
  * @see {@link decodeSnapshot} for restoring an encoded snapshot.
  * @category encoding
- * @since 4.0.0
+ * @since 0.4.0
  */
-export const encodeSnapshot = Model.encodeSnapshot;
+export const encodeSnapshot = internal.encodeSnapshot;
 /**
  * Decodes a normalized data representation into a validated machine snapshot.
  *
@@ -607,11 +307,32 @@ export const encodeSnapshot = Model.encodeSnapshot;
  * Decoding restores logical statechart data only. It does not restart invoked
  * processes, recreate spawned children, or restore a previous `MachineRef`.
  *
+ * **Example**
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import { Machine } from "@typeonce/effect-machine"
+ *
+ * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
+ * const States = Machine.defineStates({ Idle })
+ * const machine = Machine.make({
+ *   states: States.states,
+ *   events: [],
+ *   initial: () => States.initial.Idle.from()
+ * }).handle({ Idle: {} })
+ *
+ * const roundTrip = Effect.gen(function*() {
+ *   const initial = yield* Machine.planInitial(machine)
+ *   const encoded = yield* Machine.encodeSnapshot(machine, initial.state)
+ *   return yield* Machine.decodeSnapshot(machine, encoded)
+ * })
+ * ```
+ *
  * @see {@link encodeSnapshot} for creating the normalized representation.
  * @category decoding
- * @since 4.0.0
+ * @since 0.4.0
  */
-export const decodeSnapshot = Model.decodeSnapshot;
+export const decodeSnapshot = internal.decodeSnapshot;
 /**
  * Creates an invoked child process configuration for an active state.
  *
@@ -653,9 +374,9 @@ export const decodeSnapshot = Model.decodeSnapshot;
  * @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
+ * @since 0.4.0
  */
-export const invoke = (config) => ({ ...config, [InvokeTypeId]: undefined });
+export const invoke = internal.invoke;
 /**
  * Invokes one Effect and maps its typed outcome into machine-local events.
  *
@@ -669,20 +390,29 @@ export const invoke = (config) => ({ ...config, [InvokeTypeId]: undefined });
  * Declare mapped outcomes in `internalEvents` unless they are also legitimate
  * public commands.
  *
+ * **Example**
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import { Machine } from "@typeonce/effect-machine"
+ *
+ * class Loaded extends Schema.TaggedClass<Loaded>("Loaded")("Loaded", {
+ *   value: Schema.String
+ * }) {}
+ *
+ * const load = Machine.invokeEffect({
+ *   id: "load",
+ *   effect: Effect.succeed("ready"),
+ *   onSuccess: (value) => new Loaded({ value })
+ * })
+ * ```
+ *
  * @see {@link invoke} for arbitrary child process logic.
  * @see {@link after} for a state-scoped delayed event.
  * @category constructors
- * @since 4.0.0
+ * @since 0.4.0
  */
-export const invokeEffect = (config) => ((config) => invoke({
-    id: config.id,
-    src: () => effect(config.onFailure === undefined
-        ? Effect.map(config.effect, config.onSuccess)
-        : Effect.matchEffect(config.effect, {
-            onFailure: (error) => Effect.succeed(config.onFailure(error)),
-            onSuccess: (value) => Effect.succeed(config.onSuccess(value))
-        }))
-}))(config);
+export const invokeEffect = internal.invokeEffect;
 /**
  * Creates a cancellable state-scoped delayed event.
  *
@@ -690,13 +420,21 @@ export const invokeEffect = (config) => ((config) => invoke({
  * that state exits. The delayed value should normally be declared in
  * `internalEvents`.
  *
+ * **Example**
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ * import { Machine } from "@typeonce/effect-machine"
+ *
+ * class TimedOut extends Schema.TaggedClass<TimedOut>("TimedOut")("TimedOut", {}) {}
+ *
+ * const timeout = Machine.after("5 seconds", new TimedOut({}))
+ * ```
+ *
  * @category constructors
- * @since 4.0.0
+ * @since 0.4.0
  */
-export const after = (duration, event, options) => invoke({
-    id: options?.id ?? `Machine.after:${String(event._tag)}`,
-    src: () => effect(Effect.as(Effect.sleep(duration), event))
-});
+export const after = internal.after;
 /**
  * Constructs another tagged case from compatible source fields.
  *
@@ -708,12 +446,9 @@ export const after = (duration, event, options) => invoke({
  * remains authoritative at runtime.
  *
  * @category constructors
- * @since 4.0.0
+ * @since 0.4.0
  */
-export const retag = (target, source, ...args) => {
-    const { _tag: _, ...fields } = source;
-    return target.make({ ...fields, ...(args[0] ?? {}) });
-};
+export const retag = internal.retag;
 /**
  * Creates an invoked child process from a complete statechart machine.
  *
@@ -737,155 +472,159 @@ export const retag = (target, source, ...args) => {
  * @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
+ * @since 0.4.0
  */
-export const invokeMachine = ((config) => {
-    const machine = config.child.machine;
-    return {
-        id: config.child.id,
-        address: config.child.id,
-        descriptor: config.child,
-        src: () => machine.input === undefined
-            ? internalProcess.toProcessLogic(machine)
-            : internalProcess.toProcessLogic(machine, config.input),
-        snapshot: config.snapshot,
-        onDone: config.onDone,
-        [InvokeTypeId]: undefined
-    };
-});
+export const invokeMachine = internal.invokeMachine;
 /**
- * Plans the initial state for a machine without running deferred actions.
+ * Plans the initial state for a machine without executing actor commands.
  *
  * **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`.
+ * The returned plan contains the settled initial snapshot, actor commands,
+ * emitted events, optional final output, and every startup microstep. Planning
+ * may evaluate transition logic and follow completion, eventless, and
+ * raised-event steps. Transition callbacks are evaluated synchronously.
+ * `startingState` and `initialEntryPaths` describe the normalized
+ * configuration before entry callbacks and settlement begin.
  *
  * **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.
+ * `start` executes the closed command list as part of the managed actor commit
+ * protocol. Manual planners may inspect commands but need a running actor scope
+ * to execute child-addressed operations.
+ *
+ * **Example**
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import { Machine } from "@typeonce/effect-machine"
+ *
+ * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
+ * const States = Machine.defineStates({ Idle })
+ * const machine = Machine.make({
+ *   states: States.states,
+ *   events: [],
+ *   initial: () => States.initial.Idle.from()
+ * }).handle({ Idle: {} })
+ *
+ * const initialState = Effect.map(Machine.planInitial(machine), (plan) => plan.state)
+ * ```
  *
  * @see {@link plan} for planning a received event.
  * @see {@link start} for the managed runtime protocol.
  * @category constructors
- * @since 4.0.0
+ * @since 0.4.0
  */
-export const planInitial = internalPlanner.planInitial;
+export const planInitial = internal.planInitial;
 /**
- * Returns the event tags handled by the current state snapshot.
+ * Returns every compiled state node in definition order.
+ *
+ * **Details**
+ *
+ * The result includes atomic, compound, parallel, final, history, and choice
+ * nodes together with their resolved descriptive annotations. Use each node's
+ * `parent` property to reconstruct the complete hierarchy. Pseudo-states are
+ * intentionally omitted from `children` because they can never appear in an
+ * active configuration.
  *
  * @category getters
- * @since 4.0.0
+ * @since 0.4.0
  */
-export const enabled = (machine, state) => internalPlanner.enabled(machine, state);
+export const stateNodes = internal.stateNodes;
 /**
- * Plans the next state snapshot without running deferred actions.
+ * Returns every registered transition handler in state definition order.
  *
  * **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**
+ * Event handlers retain their handler-key order within each source state and
+ * are followed by eventless and completion handlers. This function does not
+ * execute handlers. Object-form event, eventless, and completion handlers with
+ * a `targets` declaration expose those possible paths; handlers without one
+ * remain dynamic.
  *
- * `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
+ * @category getters
+ * @since 0.4.0
  */
-export const plan = internalPlanner.plan;
+export const transitionDefinitions = internal.transitionDefinitions;
 /**
- * Defers an effectful action until the current machine step is planned.
+ * Returns serializable descriptions of every state-owned activity.
  *
  * **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. Pass a second argument when the planning Effect should return that
- * value after staging.
+ * Static `invoke`, `invokeEffect`, `after`, and `invokeMachine` descriptors
+ * expose stable ownership and lifecycle metadata without serializing runtime
+ * values. Function-valued invoke factories are represented as dynamic and are
+ * never evaluated during inspection.
  *
- * **Example** (Typed staged action)
+ * @category getters
+ * @since 0.4.0
+ */
+export const activityDefinitions = internal.activityDefinitions;
+/**
+ * Returns every state node active in a decoded snapshot, in definition order.
  *
- * ```ts
- * import { Context, Effect } from "effect"
- * import { Machine } from "@typeonce/effect-machine"
+ * **Details**
  *
- * class Audit extends Context.Service<Audit, {
- *   readonly write: Effect.Effect<void, "AuditError">
- * }>()("example/Audit") {}
+ * Active compound ancestors and parallel regions are included together with
+ * their active descendants. History and choice pseudo-states are never active
+ * and are not returned.
  *
- * const writeAudit = Machine.action(
- *   Effect.flatMap(Audit, (audit) => audit.write)
- * )
- * ```
+ * @category getters
+ * @since 0.4.0
+ */
+export const configuration = internal.configuration;
+/**
+ * Returns the event tags handled by the current state snapshot.
  *
- * @see {@link plan} for inspecting staged actions without executing them.
- * @category combinators
- * @since 4.0.0
+ * @category getters
+ * @since 0.4.0
  */
-export const action = ((effect, ...next) => {
-    const staged = internalPlanner.action(effect);
-    return next.length === 0 ? staged : Effect.as(staged, next[0]);
-});
-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")
-});
+export const enabled = internal.enabled;
 /**
- * Runs staged machine actions sequentially with the supplied runtime.
+ * Plans the next state snapshot synchronously.
  *
- * **When to use**
+ * **Details**
  *
- * Use when you implement a commit protocol around `plan` or `planInitial` and
- * need to execute their staged actions before publishing the planned snapshot.
+ * 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**
  *
- * 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.
+ * `plan` returns data; it does not implement the actor commit protocol.
+ * `start` executes child commands, publishes `next`, and then delivers
+ * `emittedEvents`. Events with no enabled transition are ignored and produce
+ * an unchanged plan.
  *
- * @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.
+ * **Example**
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import { Machine } from "@typeonce/effect-machine"
+ *
+ * class Off extends Schema.TaggedClass<Off>("Off")("Off", {}) {}
+ * class On extends Schema.TaggedClass<On>("On")("On", {}) {}
+ * class Toggle extends Schema.TaggedClass<Toggle>("Toggle")("Toggle", {}) {}
+ * const States = Machine.defineStates({ Off, On })
+ * const machine = Machine.make({
+ *   states: States.states,
+ *   events: [Toggle],
+ *   initial: () => States.initial.Off.from()
+ * }).handle({ Off: { on: { Toggle: () => States.initial.On.from() } }, On: {} })
+ *
+ * const nextState = Effect.gen(function*() {
+ *   const initial = yield* Machine.planInitial(machine)
+ *   return (yield* Machine.plan(machine, initial.state, new Toggle({}))).next
+ * })
+ * ```
  *
+ * @see {@link planInitial} for planning machine startup.
+ * @see {@link start} for managed execution and lifecycle observation.
  * @category combinators
- * @since 4.0.0
+ * @since 0.4.0
  */
-export const runtime = () => internalPlanner.runtime();
+export const plan = internal.plan;
 /**
  * Creates a one-shot child process from an Effect.
  *
@@ -926,12 +665,9 @@ export const runtime = () => internalPlanner.runtime();
  * @see {@link transition} for event-driven state.
  * @see {@link logic} for direct control over intermediate snapshots.
  * @category constructors
- * @since 4.0.0
+ * @since 0.4.0
  */
-export const effect = (effect) => ({
-    initial: () => Effect.void,
-    run: () => effect
-});
+export const effect = internal.effect;
 /**
  * Creates advanced stateful process logic from explicit initialization and
  * execution methods.
@@ -958,14 +694,9 @@ export const effect = (effect) => ({
  * @see {@link effect} for one-shot work.
  * @see {@link transition} for event-driven state.
  * @category constructors
- * @since 4.0.0
+ * @since 0.4.0
  */
-export const logic = (options) => ({
-    initial: (scope) => typeof options.initial === "function"
-        ? options.initial(scope)
-        : Effect.succeed(options.initial),
-    run: options.run
-});
+export const logic = internal.logic;
 /**
  * Creates child process logic from an initial state and a transition function.
  *
@@ -979,15 +710,24 @@ export const logic = (options) => ({
  * Each received event runs the transition Effect against the latest state. The
  * resulting state is published before the next queued event is processed.
  *
+ * **Example**
+ *
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Machine } from "@typeonce/effect-machine"
+ *
+ * const counter = Machine.transition(
+ *   0,
+ *   (count, event: { readonly by: number }) => Effect.succeed(count + event.by)
+ * )
+ * ```
+ *
  * @see {@link effect} for one-shot work.
  * @see {@link logic} for direct process lifecycle control.
  * @category constructors
- * @since 4.0.0
+ * @since 0.4.0
  */
-export const transition = (initial, transition) => logic({
-    initial,
-    run: ({ receive, updateState }) => receive.pipe(Effect.flatMap((event) => updateState((state) => transition(state, event))), Effect.forever)
-});
+export const transition = internal.transition;
 /**
  * Creates a typed descriptor for a complete child machine.
  *
@@ -995,13 +735,9 @@ export const transition = (initial, transition) => logic({
  * constructed descriptors for the same pair address the same invoked child.
  *
  * @category constructors
- * @since 4.0.0
+ * @since 0.4.0
  */
-export const child = (id, machine) => ({
-    [ChildMachineTypeId]: ChildMachineTypeId,
-    id,
-    machine
-});
+export const child = internal.child;
 /**
  * Creates a typed parent-local address for lower-level child process logic.
  *
@@ -1009,51 +745,50 @@ export const child = (id, machine) => ({
  * the address with `spawn`, `invoke`, or `sendTo`.
  *
  * @category constructors
- * @since 4.0.0
+ * @since 0.4.0
  */
-export const childAddress = (id) => id;
+export const childAddress = internal.childAddress;
 /**
  * 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.
+ * Use from lower-level process logic to create children that should be
+ * addressed or stopped by the owning process 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.
+ * This Effect requires a managed process runtime. A named child id must be
+ * unique for the current parent 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
+ * @since 0.4.0
  */
-export const spawn = ((logic, options) => Effect.flatMap(internalRuntime.MachineRuntime, (runtime) => options === undefined ? runtime.spawn(logic) : runtime.spawn(logic, options)));
+export const spawn = internal.spawn;
 /**
  * Sends an event to a named child process of the running machine.
  *
  * @category runtime
- * @since 4.0.0
+ * @since 0.4.0
  */
-export const sendTo = ((child, event) => Effect.flatMap(internalRuntime.MachineRuntime, (runtime) => runtime.sendTo(child, event)));
+export const sendTo = internal.sendTo;
 /**
  * Stops a named child process of the running machine.
  *
  * @category runtime
- * @since 4.0.0
+ * @since 0.4.0
  */
-export const stopChild = ((child) => Effect.flatMap(internalRuntime.MachineRuntime, (runtime) => runtime.stopChild(child)));
+export const stopChild = internal.stopChild;
 /**
  * Returns a stream of terminal lifecycle outcomes for a running machine.
  *
  * @category combinators
- * @since 4.0.0
+ * @since 0.4.0
  */
-export const watch = (ref) => internalRuntime.watch(ref);
+export const watch = internal.watch;
 /**
  * Starts a machine.
  *
@@ -1064,11 +799,10 @@ export const watch = (ref) => internalRuntime.watch(ref);
  *
  * **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.
+ * For each accepted event the runtime plans the complete synchronous
+ * macrostep, executes closed actor commands, stops invokes for exited states,
+ * publishes the new state, delivers emitted events, and then starts invokes
+ * for entered states.
  *
  * **Gotchas**
  *
@@ -1077,10 +811,82 @@ export const watch = (ref) => internalRuntime.watch(ref);
  * rather than being returned by `send`. Sending after the machine reaches any
  * terminal state fails immediately with `StoppedError`.
  *
+ * **Example**
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import { Machine } from "@typeonce/effect-machine"
+ *
+ * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
+ * const States = Machine.defineStates({ Idle })
+ * const machine = Machine.make({
+ *   states: States.states,
+ *   events: [],
+ *   initial: () => States.initial.Idle.from()
+ * }).handle({ Idle: {} })
+ *
+ * const state = Effect.gen(function*() {
+ *   const ref = yield* Machine.start(machine)
+ *   return yield* ref.state
+ * })
+ * ```
+ *
  * @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
+ * @since 0.4.0
+ */
+export const start = internal.start;
+/**
+ * Starts a fresh managed runtime from a decoded logical snapshot.
+ *
+ * **Details**
+ *
+ * `resume` validates and normalizes the supplied snapshot before publishing it
+ * as the first state. It does not call the machine's initial function, replay
+ * entry or transition actions, re-deliver raised or emitted events, or
+ * re-evaluate historical completion and eventless transitions. Active-state
+ * invokes start once in ancestor and document order with {@link InitialEvent};
+ * delayed invokes restart their complete duration and invoked machines start
+ * from their own initial state.
+ *
+ * Only logical state, completion, and history metadata are resumed. Queues,
+ * scopes, subscriptions, fibers, spawned children, invoke progress, and prior
+ * runtime status are process-local and are not restored. A final snapshot
+ * immediately produces a completed ref with its current-machine output.
+ *
+ * Decode encoded data explicitly with {@link decodeSnapshot} before calling
+ * this function. Stable snapshots are hosted as supplied; newly enabled
+ * eventless or completion transitions in a changed machine definition are not
+ * evaluated merely because the runtime was resumed; only ordinary subsequent
+ * transition planning can enter and stabilize states.
+ *
+ * **Example**
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import { Machine } from "@typeonce/effect-machine"
+ *
+ * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
+ * const States = Machine.defineStates({ Idle })
+ * const machine = Machine.make({
+ *   states: States.states,
+ *   events: [],
+ *   initial: () => States.initial.Idle.from()
+ * }).handle({ Idle: {} })
+ *
+ * const resumed = Effect.gen(function*() {
+ *   const initial = yield* Machine.planInitial(machine)
+ *   const encoded = yield* Machine.encodeSnapshot(machine, initial.state)
+ *   const snapshot = yield* Machine.decodeSnapshot(machine, encoded)
+ *   return yield* Machine.resume(machine, snapshot)
+ * })
+ * ```
+ *
+ * @see {@link decodeSnapshot} for the schema and transport boundary.
+ * @see {@link start} for ordinary initial startup.
+ * @category constructors
+ * @since 0.4.0
  */
-export const start = internalProcess.start;
+export const resume = internal.resume;
 //# sourceMappingURL=Machine.js.map