@typeonce/effect-machine 0.1.0 → 0.2.0

package/dist/Machine.d.ts

@@ -4,6 +4,7 @@
  * @since 4.0.0
  */
 import type * as Cause from "effect/Cause";
+import type * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
 import { type Pipeable } from "effect/Pipeable";
@@ -30,6 +31,7 @@ export type TypeId = "~effect/Machine";
  * @since 4.0.0
  */
 export declare const TypeId: TypeId;
+declare const MachineOutputStatesTypeId: unique symbol;
 /**
  * Type identifier used for the synthetic event passed to startup lifecycle
  * actions.
@@ -76,26 +78,68 @@ type IsAny<A> = 0 extends (1 & A) ? true : false;
  *
  * **Gotchas**
  *
- * History states, delayed transitions, and declarative first-class guards are
- * not part of the current API. Conditional behavior can be expressed in typed
- * handlers with ordinary TypeScript control flow.
+ * History states and declarative first-class guards are not part of the
+ * current API. Conditional behavior can be expressed in typed handlers with
+ * ordinary TypeScript control flow. Use `after` for cancellable state-scoped
+ * delayed events.
  *
  * @category models
  * @since 4.0.0
  */
-export interface Machine<States extends Machine.StateSchemas, Events extends ReadonlyArray<Machine.TaggedSchema>, Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], OutputStates extends Machine.StateIdentifier<States> = never> extends Pipeable {
+export interface Machine<States extends Machine.StateSchemas, Events extends ReadonlyArray<Machine.TaggedSchema>, Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], OutputStates extends Machine.StateIdentifier<States> = never, InputEvents extends ReadonlyArray<Machine.TaggedSchema> = Events> extends Pipeable {
     readonly [TypeId]: TypeId;
+    /** @internal Prevents output implementation evidence from being widened. */
+    readonly [MachineOutputStatesTypeId]: Readonly<Record<OutputStates, true>>;
+    /**
+     * State tree that defines the machine topology and state value schemas.
+     *
+     * @since 4.0.0
+     */
     readonly states: States;
-    readonly events: Events;
+    /**
+     * Events accepted through public machine input boundaries.
+     *
+     * @since 4.0.0
+     */
+    readonly events: InputEvents;
+    /**
+     * Events reserved for invokes, child emissions, and other machine-local work.
+     *
+     * @since 4.0.0
+     */
+    readonly internalEvents: ReadonlyArray<Machine.TaggedSchema>;
+    /**
+     * Events that the machine may emit to its parent or external adapter.
+     *
+     * @since 4.0.0
+     */
     readonly emits: Emits;
+    /**
+     * Optional schema used to decode the machine input before initialization.
+     *
+     * @since 4.0.0
+     */
     readonly input: Input | undefined;
+    /**
+     * Optional stable identity used by runtime and persistence integrations.
+     *
+     * @since 4.0.0
+     */
     readonly id: string | undefined;
     /** @internal */
     readonly stateNodes: Machine.StateNodes;
     /** @internal */
     readonly makeTargetBuilder: <Source extends Machine.StateIdentifier<States>>(source: Source) => Machine.TargetBuilder<States, Source>;
+    /** @internal */
     readonly handlers: Machine.StateConfigs<States, Events, Emits, UnhandledStates, Machine.TagOf<Events[number]>, E, R>;
-    readonly handle: Machine.Handler<States, Events, Emits, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, OutputStates>;
+    /**
+     * Adds typed state handlers and returns the refined machine definition.
+     * Successive calls implement the remaining unhandled states while retaining
+     * accumulated errors, services, final states, and output evidence.
+     *
+     * @since 4.0.0
+     */
+    readonly handle: Machine.Handler<States, Events, Emits, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, OutputStates, InputEvents>;
     /** @internal */
     readonly initial: (...args: [...Machine.InputArgs<Input>]) => Machine.InitialResult<States, InitialE, InitialR>;
 }
@@ -207,7 +251,17 @@ export type ExecutionServices<Requirements> = Exclude<PlanningServices<Requireme
  * @since 4.0.0
  */
 export interface Runtime<in Events, in Emits> {
+    /**
+     * Queues an event for the current machine macrostep.
+     *
+     * @since 4.0.0
+     */
     readonly raise: (event: Events) => Effect.Effect<void, MachineSchemaDecodeError | StoppedError>;
+    /**
+     * Emits an event through the running machine's parent boundary.
+     *
+     * @since 4.0.0
+     */
     readonly sendParent: (event: Emits) => Effect.Effect<void, MachineSchemaDecodeError | StoppedError>;
 }
 /**
@@ -321,6 +375,15 @@ type DefineStateNodeInput<Node> = Node extends Machine.TaggedSchema ? Node : Nod
 type ValidateDefinedStates<States extends Machine.StateSchemas> = [States] extends [
     Machine.ValidateStateSchemas<States>
 ] ? [] : [validation: Machine.ValidateStateSchemas<States>];
+type EventProtocolError<Message extends string, Tag extends PropertyKey = never> = {
+    readonly "~effect/Machine/EventProtocolError": Message;
+    readonly tag: Tag;
+};
+type DuplicateEventTag<Events extends ReadonlyArray<Machine.TaggedSchema>, Seen extends PropertyKey = never> = number extends Events["length"] ? never : Events extends readonly [
+    infer Head extends Machine.TaggedSchema,
+    ...infer Tail extends ReadonlyArray<Machine.TaggedSchema>
+] ? Machine.TagOf<Head> extends infer Tag extends PropertyKey ? Tag extends Seen ? Tag | DuplicateEventTag<Tail, Seen> : DuplicateEventTag<Tail, Seen | Tag> : never : never;
+type ValidateEventProtocol<InputEvents extends ReadonlyArray<Machine.TaggedSchema>, InternalEvents extends ReadonlyArray<Machine.TaggedSchema>, DuplicateInput extends PropertyKey = DuplicateEventTag<InputEvents>, DuplicateInternal extends PropertyKey = DuplicateEventTag<InternalEvents>, Overlap extends PropertyKey = Extract<Machine.TagOf<InputEvents[number]>, Machine.TagOf<InternalEvents[number]>>> = [DuplicateInput] extends [never] ? [DuplicateInternal] extends [never] ? [Overlap] extends [never] ? [] : [validation: EventProtocolError<"Public and internal event tags must be disjoint", Overlap>] : [validation: EventProtocolError<"Internal event tags must be unique", DuplicateInternal>] : [validation: EventProtocolError<"Public event tags must be unique", DuplicateInput>];
 declare const SnapshotBuilderStateTypeId: unique symbol;
 type SnapshotBuilderComplete<Regions> = {
     readonly [SnapshotBuilderStateTypeId]: Regions;
@@ -433,7 +496,7 @@ type SpawnIdError<Options extends SpawnOptions> = "id" extends keyof Options ? O
     readonly id?: infer Id;
 } ? [Id] extends [undefined] ? never : ChildAlreadyExistsError : ChildAlreadyExistsError : never;
 type SpawnError<Options extends SpawnOptions> = SpawnIdError<Options>;
-type SpawnResult<State, Event, Error, Requirements, Output, SpawnError, InitialError = never> = Effect.Effect<MachineRef<State, Event, Error | InitialError, Output>, SpawnError | InitialError, MachineRuntimeRequirement | SpawnRequirements<Requirements>>;
+type SpawnResult<State, Event, Error, Requirements, Output, SpawnError, InitialError = never> = Effect.Effect<MachineRef<State, Event, Error, Output>, SpawnError | InitialError, MachineRuntimeRequirement | SpawnRequirements<Requirements>>;
 /**
  * Represents the active or terminal lifecycle state of a running machine.
  *
@@ -520,17 +583,33 @@ export type RuntimeOutcome<State, Error = never, Output = never> = {
  * @since 4.0.0
  */
 export interface MachineRef<out State, in Event, out Error = never, out Output = never> {
+    /** Stable machine definition id, or a generated fallback when none was declared. */
     readonly id: string;
+    /** Unique identity for this running machine instance. */
     readonly sessionId: string;
+    /** Reads the latest logical state. */
     readonly state: Effect.Effect<State>;
+    /** Reads the latest lifecycle snapshot. */
     readonly snapshot: Effect.Effect<RuntimeSnapshot<State, Error, Output>>;
+    /** Streams lifecycle snapshots published after subscription. */
     readonly changes: Stream.Stream<RuntimeSnapshot<State, Error, Output>>;
+    /** Waits for machine output or fails when execution fails or is stopped. */
     readonly join: Effect.Effect<Output, Error | StoppedError>;
+    /** Stops this machine instance and its owned child processes. */
     readonly stop: Effect.Effect<void>;
+    /** Accepts an event for asynchronous processing by the running machine. */
     readonly send: (event: Event) => Effect.Effect<void, StoppedError>;
-    /** Returns the current directly owned child for a typed descriptor. */
+    /**
+     * Returns the current directly owned child for a typed descriptor.
+     *
+     * @since 4.0.0
+     */
     readonly child: <Child extends ChildMachine.Any>(child: Child) => Effect.Effect<Option.Option<ChildMachine.Ref<Child>>>;
-    /** Streams activation, replacement, and removal of a directly owned child. */
+    /**
+     * Streams activation, replacement, and removal of a directly owned child.
+     *
+     * @since 4.0.0
+     */
     readonly childChanges: <Child extends ChildMachine.Any>(child: Child) => Stream.Stream<Option.Option<ChildMachine.Ref<Child>>>;
 }
 /**
@@ -540,7 +619,9 @@ export interface MachineRef<out State, in Event, out Error = never, out Output =
  * @since 4.0.0
  */
 export interface Logic<State, Event, out Error = never, out Requirements = never, out Output = never, out InitialError = never> {
+    /** Creates the initial process state and may spawn scoped child processes. */
     initial(scope: Logic.Scope<Event>): Effect.Effect<State, InitialError, Requirements>;
+    /** Runs the stateful process loop until it produces output or fails. */
     run(context: Logic.Context<State, Event>): Effect.Effect<Output, Error, Requirements>;
 }
 /**
@@ -556,9 +637,13 @@ export declare namespace Logic {
      * @since 4.0.0
      */
     interface Address<in Event> {
+        /** Parent-local address id. */
         readonly id: string;
+        /** Unique identity for this running child instance. */
         readonly sessionId: string;
+        /** Stops the addressed child process. */
         readonly stop: Effect.Effect<void>;
+        /** Sends an event to the addressed child process. */
         readonly send: (event: Event) => Effect.Effect<void, StoppedError>;
     }
     /**
@@ -568,10 +653,8 @@ export declare namespace Logic {
      * @since 4.0.0
      */
     interface Spawn {
-        <ChildState, ChildEvent, ChildError, ChildRequirements, ChildOutput, ChildInitialError = never>(logic: Logic<ChildState, ChildEvent, ChildError, ChildRequirements, ChildOutput, ChildInitialError>): Effect.Effect<MachineRef<ChildState, ChildEvent, ChildError | ChildInitialError, ChildOutput>, ChildInitialError, Exclude<ChildRequirements, Scope.Scope>>;
-        <ChildState, ChildEvent, ChildError, ChildRequirements, ChildOutput, ChildInitialError = never>(logic: Logic<ChildState, ChildEvent, ChildError, ChildRequirements, ChildOutput, ChildInitialError>, options: {
-            readonly id: string;
-        }): Effect.Effect<MachineRef<ChildState, ChildEvent, ChildError | ChildInitialError, ChildOutput>, ChildAlreadyExistsError | ChildInitialError, Exclude<ChildRequirements, Scope.Scope>>;
+        <ChildState, ChildEvent, ChildError, ChildRequirements, ChildOutput, ChildInitialError = never>(logic: Logic<ChildState, ChildEvent, ChildError, ChildRequirements, ChildOutput, ChildInitialError>): Effect.Effect<MachineRef<ChildState, ChildEvent, ChildError, ChildOutput>, ChildInitialError, Exclude<ChildRequirements, Scope.Scope>>;
+        <ChildState, ChildEvent, ChildError, ChildRequirements, ChildOutput, Options extends SpawnOptions, ChildInitialError = never>(logic: Logic<ChildState, ChildEvent, ChildError, ChildRequirements, ChildOutput, ChildInitialError>, options: Options & ChildAddress.OptionsCompatibility<Options, ChildEvent>): Effect.Effect<MachineRef<ChildState, ChildEvent, ChildError, ChildOutput>, SpawnIdError<Options> | ChildInitialError, Exclude<ChildRequirements, Scope.Scope>>;
     }
     /**
      * Machine-local capabilities available while process logic initializes.
@@ -586,12 +669,18 @@ export declare namespace Logic {
      * @since 4.0.0
      */
     interface Scope<Event> {
+        /** Address of the process being initialized. */
         readonly self: Address<Event>;
+        /** Address of the owning process, when one exists. */
         readonly parent: Address<unknown> | undefined;
+        /** Starts a child process owned by this scope. */
         readonly spawn: Spawn;
+        /** Sends an untyped event to the owning process. */
         readonly sendParent: (event: unknown) => Effect.Effect<void, StoppedError>;
-        readonly sendTo: <Address extends string>(id: Address, event: ChildAddress.Event<Address>) => Effect.Effect<void, StoppedError>;
-        readonly stopChild: (id: string) => Effect.Effect<void>;
+        /** Sends an event through a typed parent-local child address. */
+        readonly sendTo: <Address extends ChildAddress<never>>(id: Address, event: ChildAddress.Event<Address>) => Effect.Effect<void, StoppedError>;
+        /** Stops a child process selected by its parent-local address. */
+        readonly stopChild: <Event>(id: ChildAddress<Event>) => Effect.Effect<void>;
     }
     /**
      * Machine-local capabilities available while stateful process logic runs.
@@ -600,15 +689,22 @@ export declare namespace Logic {
      * @since 4.0.0
      */
     interface Context<State, Event> extends Scope<Event> {
+        /** Waits for the next event delivered to this process. */
         readonly receive: Effect.Effect<Event>;
+        /** Reads the current process state. */
         readonly state: Effect.Effect<State>;
+        /** Replaces the current process state. */
         readonly setState: (state: State) => Effect.Effect<void>;
+        /** Updates the current process state effectfully and atomically. */
         readonly updateState: <E, R>(update: (state: State) => Effect.Effect<State, E, R>) => Effect.Effect<void, E, R>;
     }
 }
 declare const ChildAddressTypeId = "~effect/Machine/ChildAddress";
 declare const ChildAddressCompatibilityErrorTypeId = "~effect/Machine/ChildAddressCompatibilityError";
 declare const ChildMachineTypeId = "~effect/Machine/ChildMachine";
+type InvokeLifecycleId = string & {
+    readonly [ChildAddressTypeId]?: never;
+};
 /**
  * Typed descriptor for a complete machine invoked as a child.
  *
@@ -623,7 +719,9 @@ declare const ChildMachineTypeId = "~effect/Machine/ChildMachine";
  */
 export interface ChildMachine<Id extends string, M extends Machine.Any> {
     readonly [ChildMachineTypeId]: typeof ChildMachineTypeId;
+    /** Parent-local id used to address the invoked child. */
     readonly id: Id;
+    /** Complete machine definition carried by this descriptor. */
     readonly machine: M;
 }
 /**
@@ -645,7 +743,7 @@ export declare namespace ChildMachine {
      * @category utility types
      * @since 4.0.0
      */
-    type Ref<Child> = Child extends ChildMachine<string, infer M> ? M extends Machine<infer States, infer Events, any, any, infer E, infer R, infer InitialE, infer InitialR, any, infer Output, any, any> ? MachineRef<Machine.Snapshot<States>, Machine.EventOf<Events>, E | InitialE | ActionError<R | InitialR> | InfiniteTransitionError | MachineSchemaDecodeError | StartupError | StoppedError, Output | undefined> : never : never;
+    type Ref<Child> = Child extends ChildMachine<string, infer M> ? M extends Machine<infer States, infer Events, any, any, infer E, infer R, infer InitialE, infer InitialR, any, infer Output, any, any, infer InputEvents> ? MachineRef<Machine.Snapshot<States>, Machine.EventOf<InputEvents>, E | ActionError<R> | InfiniteTransitionError | MachineSchemaDecodeError | StoppedError, Output> : never : never;
     /**
      * Event accepted by the child selected by a descriptor.
      *
@@ -738,10 +836,47 @@ export declare namespace Machine {
     /**
      * Any schema-first machine.
      *
+     * This is an erased structural view for APIs that store machines without
+     * knowing their protocols. Generic APIs should capture `M extends Any` to
+     * preserve the concrete machine type. The private output-implementation
+     * proof is intentionally omitted so erasing a machine cannot manufacture
+     * that proof on another concrete `Machine` type.
+     *
      * @category models
      * @since 4.0.0
      */
-    type Any = Machine<any, any, any, any, any, any, any, any, any, any, any, any>;
+    interface Any extends Pipeable {
+        readonly [TypeId]: TypeId;
+        readonly states: StateSchemas;
+        readonly events: ReadonlyArray<TaggedSchema>;
+        readonly internalEvents: ReadonlyArray<TaggedSchema>;
+        readonly emits: ReadonlyArray<TaggedSchema>;
+        readonly input: Schema.Top | undefined;
+        readonly id: string | undefined;
+        readonly stateNodes: StateNodes;
+        /** @internal */
+        readonly makeTargetBuilder: any;
+        /** @internal */
+        readonly handlers: any;
+        /** @internal */
+        readonly handle: any;
+        /** @internal */
+        readonly initial: any;
+    }
+    /**
+     * Extracts the complete event protocol handled inside a machine.
+     *
+     * @category utility types
+     * @since 4.0.0
+     */
+    type Event<M extends Any> = M extends Machine<any, infer Events, any, any, any, any, any, any, any, any, any, any, any> ? EventOf<Events> : never;
+    /**
+     * Extracts the event protocol accepted by public machine input boundaries.
+     *
+     * @category utility types
+     * @since 4.0.0
+     */
+    type InputEvent<M extends Any> = M extends Machine<any, any, any, any, any, any, any, any, any, any, any, any, infer InputEvents> ? EventOf<InputEvents> : never;
     /**
      * A schema whose decoded value contains a `_tag` discriminator.
      *
@@ -847,7 +982,9 @@ export declare namespace Machine {
      * @since 4.0.0
      */
     interface DefinedStates<States extends StateSchemas> {
+        /** Original state tree supplied to {@link defineStates}. */
         readonly states: States;
+        /** Type-safe builders for constructing valid initial snapshots. */
         readonly initial: InitialBuilder<States>;
         /**
          * Returns the decoded value for an active state path.
@@ -1028,6 +1165,13 @@ export declare namespace Machine {
      * @since 4.0.0
      */
     type ParentStateIdentifier<StateId extends string> = StateId extends `${infer Parent}.${infer Child}` ? Parent | (Child extends `${string}.${string}` ? `${Parent}.${ParentStateIdentifier<Child>}` : never) : never;
+    /**
+     * Extracts the nearest parent state path from a state identifier.
+     *
+     * @category utility types
+     * @since 4.0.0
+     */
+    type ImmediateParentStateIdentifier<StateId extends string> = StateId extends `${infer Head}.${infer Tail}` ? Tail extends `${string}.${string}` ? `${Head}.${ImmediateParentStateIdentifier<Tail>}` : Head : never;
     /**
      * Maps every parent state path of a state identifier to its decoded value.
      *
@@ -1037,6 +1181,13 @@ export declare namespace Machine {
     type ParentStateValues<States extends StateSchemas, StateId extends StateIdentifier<States>> = StateId extends StateIdentifier<States> ? {
         readonly [Parent in Extract<ParentStateIdentifier<StateId>, StateIdentifier<States>>]: StateByIdentifier<States, Parent>;
     } : never;
+    /**
+     * Extracts the nearest parent value, or `undefined` for a root state.
+     *
+     * @category utility types
+     * @since 4.0.0
+     */
+    type ParentStateValue<States extends StateSchemas, StateId extends StateIdentifier<States>> = StateId extends StateIdentifier<States> ? Extract<ImmediateParentStateIdentifier<StateId>, StateIdentifier<States>> extends infer Parent ? [Parent] extends [never] ? undefined : Parent extends StateIdentifier<States> ? StateByIdentifier<States, Parent> : undefined : undefined : never;
     /**
      * Represents a decoded state value together with all of its parent values.
      *
@@ -1061,9 +1212,10 @@ export declare namespace Machine {
     type DirectFinalCompletionOutput<States extends StateSchemas, StateId extends StateIdentifier<States>> = NodeByIdentifier<States, StateId> extends {
         readonly type: "final";
     } ? OutputByIdentifier<States, StateId> : never;
-    type CompoundCompletionOutput<States extends StateSchemas, Children extends StateSchemas, Prefix extends StateIdentifier<States>> = UndefinedIfNever<{
+    type CompoundCompletionOutput<States extends StateSchemas, Children extends StateSchemas, Prefix extends StateIdentifier<States>> = UndefinedIfNever<CompoundCompletionOutputRaw<States, Children, Prefix>>;
+    type CompoundCompletionOutputRaw<States extends StateSchemas, Children extends StateSchemas, Prefix extends StateIdentifier<States>> = {
         readonly [Key in Extract<keyof Children, string>]: DirectFinalCompletionOutput<States, Extract<JoinPath<Prefix, Key>, StateIdentifier<States>>>;
-    }[Extract<keyof Children, string>]>;
+    }[Extract<keyof Children, string>];
     /**
      * Extracts the output passed when a state node completes.
      *
@@ -1077,6 +1229,52 @@ export declare namespace Machine {
     } ? CompoundCompletionOutput<States, Children, StateId> : Node extends {
         readonly type: "final";
     } ? OutputByIdentifier<States, StateId> : undefined : undefined;
+    /**
+     * Extracts the schema-derived union produced by structurally terminal root
+     * states.
+     *
+     * **Details**
+     *
+     * Unlike a planned step's optional `output`, active atomic roots do not add
+     * `undefined` to the union. Output-less final and parallel roots
+     * intentionally contribute `undefined`, because that is their completed
+     * value. Handler-driven reachability can make this structural union
+     * conservative; for example, a root `onDone` handler can transition away
+     * before that root becomes the machine's terminal result.
+     *
+     * @category utility types
+     * @since 4.0.0
+     */
+    type TerminalOutput<States extends StateSchemas> = {
+        readonly [Key in Extract<keyof States, string>]: Extract<Key, StateIdentifier<States>> extends infer StateId extends StateIdentifier<States> ? NodeByIdentifier<States, StateId> extends infer Node ? Node extends {
+            readonly type: "parallel" | "final";
+        } ? OutputByIdentifier<States, StateId> : Node extends {
+            readonly states: infer Children extends StateSchemas;
+        } ? CompoundCompletionOutputRaw<States, Children, StateId> : never : never : never;
+    }[Extract<keyof States, string>];
+    /**
+     * Extracts every state path whose definition declares an output schema.
+     *
+     * @category utility types
+     * @since 4.0.0
+     */
+    type DeclaredOutputState<States extends StateSchemas> = {
+        readonly [StateId in StateIdentifier<States>]: NodeByIdentifier<States, StateId> extends {
+            readonly output: Schema.Top;
+        } ? StateId : never;
+    }[StateIdentifier<States>] & StateIdentifier<States>;
+    /**
+     * Validates that every declared output schema has a matching handler
+     * implementation before a machine is planned or started.
+     *
+     * @category utility types
+     * @since 4.0.0
+     */
+    type EnsureOutputImplementations<States extends StateSchemas, OutputStates extends StateIdentifier<States>> = [
+        Exclude<DeclaredOutputState<States>, OutputStates>
+    ] extends [never] ? unknown : {
+        readonly "~effect/Machine/MissingOutputImplementation": Exclude<DeclaredOutputState<States>, OutputStates>;
+    };
     type OutputSchema<Node> = Node extends {
         readonly output: infer Output extends Schema.Top;
     } ? Output : never;
@@ -1347,6 +1545,13 @@ export declare namespace Machine {
      * targets descendants of the source root, and `full` builds complete
      * snapshots for any root.
      *
+     * These builders control how the next active configuration is assembled; they
+     * do not directly control state re-entry. Exit and entry paths are derived
+     * from the previous and next active paths. Shared active ancestors remain
+     * entered even when a `full` target supplies their values again. Use an event
+     * transition with `reenter: true` when the source should explicitly exit and
+     * enter again.
+     *
      * @category models
      * @since 4.0.0
      */
@@ -1383,11 +1588,16 @@ export declare namespace Machine {
     /**
      * Stages an Effect to run after the current machine step is planned.
      *
+     * The two-argument overload returns `next` after staging the Effect, which is
+     * useful when a handler should stage one action and return a target without
+     * introducing an Effect generator.
+     *
      * @category models
      * @since 4.0.0
      */
     interface Action {
         <E, R>(effect: Effect.Effect<void, E, R>): Effect.Effect<void, never, ActionRequirement<E, R>>;
+        <E, R, Next>(effect: Effect.Effect<void, E, R>, next: Next): Effect.Effect<Next, never, ActionRequirement<E, R>>;
     }
     /**
      * Planning capabilities shared by transition and lifecycle callbacks.
@@ -1396,7 +1606,6 @@ export declare namespace Machine {
      * @since 4.0.0
      */
     interface PlanningCapabilities<Events, Emits> {
-        readonly action: Action;
         readonly raise: (event: Events) => Effect.Effect<void, MachineSchemaDecodeError | StoppedError, Runtime.Requirement<Events, Emits>>;
         readonly emit: (event: Emits) => Effect.Effect<void, MachineSchemaDecodeError | StoppedError, Runtime.Requirement<Events, Emits>>;
     }
@@ -1408,6 +1617,7 @@ export declare namespace Machine {
      */
     interface HandlerContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>, EventTag extends TagOf<Events[number]>, E, R> extends PlanningCapabilities<EventOf<Events>, EmitOf<Emits>> {
         readonly state: StateByIdentifier<States, StateId>;
+        readonly parent: ParentStateValue<States, StateId>;
         readonly parents: ParentStateValues<States, StateId>;
         readonly event: EventByTag<Events, EventTag>;
         readonly runtime: RuntimeEffect<Events, Emits>;
@@ -1427,6 +1637,7 @@ export declare namespace Machine {
      */
     interface StateActionContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>> extends PlanningCapabilities<EventOf<Events>, EmitOf<Emits>> {
         readonly state: StateByIdentifier<States, StateId>;
+        readonly parent: ParentStateValue<States, StateId>;
         readonly parents: ParentStateValues<States, StateId>;
         readonly event: LifecycleEvent<Events>;
         readonly runtime: RuntimeEffect<Events, Emits>;
@@ -1439,6 +1650,7 @@ export declare namespace Machine {
      */
     interface InvokeContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>> {
         readonly state: StateByIdentifier<States, StateId>;
+        readonly parent: ParentStateValue<States, StateId>;
         readonly parents: ParentStateValues<States, StateId>;
         readonly event: LifecycleEvent<Events>;
         readonly runtime: RuntimeEffect<Events, Emits>;
@@ -1473,6 +1685,7 @@ export declare namespace Machine {
      */
     interface AlwaysContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>> extends PlanningCapabilities<EventOf<Events>, EmitOf<Emits>> {
         readonly state: StateByIdentifier<States, StateId>;
+        readonly parent: ParentStateValue<States, StateId>;
         readonly parents: ParentStateValues<States, StateId>;
         readonly event: LifecycleEvent<Events>;
         readonly runtime: RuntimeEffect<Events, Emits>;
@@ -1493,6 +1706,7 @@ export declare namespace Machine {
      */
     interface DoneContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>> extends PlanningCapabilities<EventOf<Events>, EmitOf<Emits>> {
         readonly state: StateByIdentifier<States, StateId>;
+        readonly parent: ParentStateValue<States, StateId>;
         readonly parents: ParentStateValues<States, StateId>;
         readonly event: LifecycleEvent<Events>;
         readonly output: CompletionOutputByIdentifier<States, StateId>;
@@ -1514,6 +1728,7 @@ export declare namespace Machine {
      */
     interface FinalOutputContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>> {
         readonly state: StateByIdentifier<States, StateId>;
+        readonly parent: ParentStateValue<States, StateId>;
         readonly parents: ParentStateValues<States, StateId>;
         readonly event: LifecycleEvent<Events>;
     }
@@ -1537,6 +1752,7 @@ export declare namespace Machine {
      */
     interface ParallelOutputContext<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>> {
         readonly state: StateByIdentifier<States, StateId>;
+        readonly parent: ParentStateValue<States, StateId>;
         readonly parents: ParentStateValues<States, StateId>;
         readonly event: LifecycleEvent<Events>;
         readonly outputs: ParallelOutputRegions<States, StateId>;
@@ -1755,15 +1971,6 @@ export declare namespace Machine {
      * @since 4.0.0
      */
     type ConfigServices<Config> = Effect.Services<EventHandlerReturn<Config>> | Effect.Services<AlwaysReturn<Config>> | Effect.Services<DoneReturn<Config>> | Effect.Services<StateActionReturn<Config, "entry">> | Effect.Services<StateActionReturn<Config, "exit">> | InvokeRequirements<Config>;
-    /**
-     * Resolves the tag of a state config when it is final.
-     *
-     * @category utility types
-     * @since 4.0.0
-     */
-    type FinalStateFromConfig<Config, StateTag extends PropertyKey> = Config extends {
-        readonly type: "final";
-    } ? StateTag : never;
     /**
      * Configuration for invoking a child process while a state is active.
      *
@@ -1780,10 +1987,17 @@ export declare namespace Machine {
             readonly initialError: Types.Covariant<ChildInitialError>;
         };
         readonly id: string;
+        /**
+         * Optional parent-local address for sending events to this invocation.
+         *
+         * The invocation `id` is only its state-local lifecycle key. Use an
+         * explicit typed address when the parent must communicate with it.
+         */
+        readonly address?: string;
         /** @internal */
-        readonly addressable?: boolean;
+        readonly descriptor?: ChildMachine.Any;
         src(): Logic<ChildState, ChildEvent, ChildError, ChildRequirements, ChildOutput, ChildInitialError>;
-        snapshot?(context: InvokeSnapshotContext<ChildState, ChildError | ChildInitialError, ChildOutput>): Event | undefined;
+        snapshot?(context: InvokeSnapshotContext<ChildState, ChildError, ChildOutput>): Event | undefined;
         onDone?(context: InvokeDoneContext<ChildOutput>): DeliveredOutput | undefined;
     }
     /** @internal */
@@ -1828,7 +2042,6 @@ export declare namespace Machine {
      * @since 4.0.0
      */
     type ActiveStateConfig<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>, E, R> = {
-        readonly type?: "active";
         readonly entry?: (context: StateActionContext<States, Events, Emits, StateId>) => StateActionResult<any, any>;
         readonly exit?: (context: StateActionContext<States, Events, Emits, StateId>) => StateActionResult<any, any>;
         readonly invoke?: InvokeDefinition<States, Events, Emits, StateId>;
@@ -1848,7 +2061,6 @@ export declare namespace Machine {
      * @since 4.0.0
      */
     type FinalStateConfig<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>> = {
-        readonly type: "final";
         readonly entry?: (context: StateActionContext<States, Events, Emits, StateId>) => StateActionResult<any, any>;
         readonly exit?: never;
         readonly always?: never;
@@ -1861,7 +2073,9 @@ export declare namespace Machine {
      * @category models
      * @since 4.0.0
      */
-    type HandlerConfig<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>, E, R> = ActiveStateConfig<States, Events, Emits, StateId, E, R> | FinalStateConfig<States, Events, Emits, StateId>;
+    type HandlerConfig<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>, E, R> = NodeByIdentifier<States, StateId> extends {
+        readonly type: "final";
+    } ? FinalStateConfig<States, Events, Emits, StateId> : ActiveStateConfig<States, Events, Emits, StateId, E, R>;
     type HandlerChildren<Node> = Node extends {
         readonly states: infer Children extends StateSchemas;
     } ? Children : never;
@@ -1879,7 +2093,7 @@ export declare namespace Machine {
     type HandlerTree<AllStates extends StateSchemas, States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, E, R, Prefix extends string> = {
         readonly [Key in Extract<keyof States, string>]?: HandlerNode<AllStates, States[Key], Events, Emits, E, R, HandlerStateId<AllStates, JoinPath<Prefix, Key>>>;
     };
-    type HandlerNodeConfigKey = "always" | "entry" | "exit" | "invoke" | "on" | "onDone" | "output" | "states" | "type";
+    type HandlerNodeConfigKey = "always" | "entry" | "exit" | "invoke" | "on" | "onDone" | "output" | "states";
     type HandlerValidationError<Message extends string> = {
         readonly "~effect/Machine/HandlerError": Message;
     };
@@ -1954,19 +2168,11 @@ export declare namespace Machine {
         readonly [Key in Extract<Extract<keyof Config, string>, Extract<keyof States, string>>]: ConfigServices<HandlerConfigPart<Config[Key]>> | HandlerNodeChildServices<AllStates, Events, Emits, States[Key], HandlerStateId<AllStates, JoinPath<Prefix, Key>>, Config[Key], Depth>;
     }[Extract<Extract<keyof Config, string>, Extract<keyof States, string>>];
     type HandlerNodeChildServices<AllStates extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Node, Prefix extends string, Config, Depth extends ReadonlyArray<unknown>> = Depth extends readonly [] ? never : HandlerChildren<Node> extends infer Children extends StateSchemas ? [Children] extends [never] ? never : HandlerTreeServices<AllStates, Events, Emits, Children, Prefix, HandlerNodeChildrenConfig<Config>, HandlerNextDepth<Depth>> : never;
-    type HandlerTreeFinalStates<AllStates extends StateSchemas, States extends StateSchemas, Prefix extends string, Config, Depth extends ReadonlyArray<unknown> = HandlerDepth> = {
-        readonly [Key in Extract<Extract<keyof Config, string>, Extract<keyof States, string>>]: Extract<FinalStateFromConfig<HandlerConfigPart<Config[Key]>, HandlerStateId<AllStates, JoinPath<Prefix, Key>>>, StateIdentifier<AllStates>> | HandlerNodeChildFinalStates<AllStates, States[Key], HandlerStateId<AllStates, JoinPath<Prefix, Key>>, Config[Key], Depth>;
-    }[Extract<Extract<keyof Config, string>, Extract<keyof States, string>>];
-    type HandlerNodeChildFinalStates<AllStates extends StateSchemas, Node, Prefix extends string, Config, Depth extends ReadonlyArray<unknown>> = Depth extends readonly [] ? never : HandlerChildren<Node> extends infer Children extends StateSchemas ? [Children] extends [never] ? never : HandlerTreeFinalStates<AllStates, Children, Prefix, HandlerNodeChildrenConfig<Config>, HandlerNextDepth<Depth>> : never;
-    type HandlerTreeOutput<AllStates extends StateSchemas, States extends StateSchemas, Prefix extends string, Config, Depth extends ReadonlyArray<unknown> = HandlerDepth> = {
-        readonly [Key in Extract<Extract<keyof Config, string>, Extract<keyof States, string>>]: ("output" extends keyof HandlerConfigPart<Config[Key]> ? OutputByIdentifier<AllStates, HandlerStateId<AllStates, JoinPath<Prefix, Key>>> : never) | HandlerNodeChildOutput<AllStates, States[Key], HandlerStateId<AllStates, JoinPath<Prefix, Key>>, Config[Key], Depth>;
-    }[Extract<Extract<keyof Config, string>, Extract<keyof States, string>>];
-    type HandlerNodeChildOutput<AllStates extends StateSchemas, Node, Prefix extends string, Config, Depth extends ReadonlyArray<unknown>> = Depth extends readonly [] ? never : HandlerChildren<Node> extends infer Children extends StateSchemas ? [Children] extends [never] ? never : HandlerTreeOutput<AllStates, Children, Prefix, HandlerNodeChildrenConfig<Config>, HandlerNextDepth<Depth>> : never;
     type HandlerTreeOutputStates<AllStates extends StateSchemas, States extends StateSchemas, Prefix extends string, Config, Depth extends ReadonlyArray<unknown> = HandlerDepth> = {
         readonly [Key in Extract<Extract<keyof Config, string>, Extract<keyof States, string>>]: HandlerOutputStates<AllStates, HandlerStateId<AllStates, JoinPath<Prefix, Key>>, HandlerConfigPart<Config[Key]>> | HandlerNodeChildOutputStates<AllStates, States[Key], HandlerStateId<AllStates, JoinPath<Prefix, Key>>, Config[Key], Depth>;
     }[Extract<Extract<keyof Config, string>, Extract<keyof States, string>>];
     type HandlerNodeChildOutputStates<AllStates extends StateSchemas, Node, Prefix extends string, Config, Depth extends ReadonlyArray<unknown>> = Depth extends readonly [] ? never : HandlerChildren<Node> extends infer Children extends StateSchemas ? [Children] extends [never] ? never : HandlerTreeOutputStates<AllStates, Children, Prefix, HandlerNodeChildrenConfig<Config>, HandlerNextDepth<Depth>> : never;
-    type HandleTreeResult<AllStates extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Input extends Schema.Top, UnhandledStates extends StateIdentifier<AllStates>, E, R, InitialE, InitialR, FinalStates extends StateIdentifier<AllStates>, Output, OutputStates extends StateIdentifier<AllStates>, Config> = Machine<AllStates, Events, Input, Exclude<UnhandledStates, HandlerTreeStateIds<AllStates, AllStates, "", Config>>, E | HandlerTreeError<AllStates, Events, Emits, AllStates, "", Config>, ExcludeCompatibleRuntime<R | HandlerTreeServices<AllStates, Events, Emits, AllStates, "", Config>, EventOf<Events>, EmitOf<Emits>>, InitialE, InitialR, FinalStates | Extract<HandlerTreeFinalStates<AllStates, AllStates, "", Config>, StateIdentifier<AllStates>>, Output | HandlerTreeOutput<AllStates, AllStates, "", Config>, Emits, OutputStates | Extract<HandlerTreeOutputStates<AllStates, AllStates, "", Config>, StateIdentifier<AllStates>>>;
+    type HandleTreeResult<AllStates extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Input extends Schema.Top, UnhandledStates extends StateIdentifier<AllStates>, E, R, InitialE, InitialR, FinalStates extends StateIdentifier<AllStates>, Output, OutputStates extends StateIdentifier<AllStates>, InputEvents extends ReadonlyArray<TaggedSchema>, Config> = Machine<AllStates, Events, Input, Exclude<UnhandledStates, HandlerTreeStateIds<AllStates, AllStates, "", Config>>, E | HandlerTreeError<AllStates, Events, Emits, AllStates, "", Config>, ExcludeCompatibleRuntime<R | HandlerTreeServices<AllStates, Events, Emits, AllStates, "", Config>, EventOf<Events>, EmitOf<Emits>>, InitialE, InitialR, FinalStates, Output, Emits, OutputStates | Extract<HandlerTreeOutputStates<AllStates, AllStates, "", Config>, StateIdentifier<AllStates>>, InputEvents>;
     /**
      * Adds state handlers from a root state object.
      *
@@ -1979,8 +2185,8 @@ export declare namespace Machine {
      * @category combinators
      * @since 4.0.0
      */
-    interface Handler<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Input extends Schema.Top, UnhandledStates extends StateIdentifier<States>, E, R, InitialE, InitialR, FinalStates extends StateIdentifier<States>, Output, OutputStates extends StateIdentifier<States>> {
-        <const Config extends HandlerTree<States, States, Events, Emits, E, R, "">>(config: Config & HandlerTreeValidation<States, States, Events, "", Config, OutputStates | Extract<HandlerTreeOutputStates<States, States, "", Config>, StateIdentifier<States>>> & EnsureCompatibleRuntime<HandlerTreeServices<States, Events, Emits, States, "", Config>, EventOf<Events>, EmitOf<Emits>>): HandleTreeResult<States, Events, Emits, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, OutputStates, Config>;
+    interface Handler<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Input extends Schema.Top, UnhandledStates extends StateIdentifier<States>, E, R, InitialE, InitialR, FinalStates extends StateIdentifier<States>, Output, OutputStates extends StateIdentifier<States>, InputEvents extends ReadonlyArray<TaggedSchema>> {
+        <const Config extends HandlerTree<States, States, Events, Emits, E, R, "">>(config: Config & HandlerTreeValidation<States, States, Events, "", Config, OutputStates | Extract<HandlerTreeOutputStates<States, States, "", Config>, StateIdentifier<States>>> & EnsureCompatibleRuntime<HandlerTreeServices<States, Events, Emits, States, "", Config>, EventOf<Events>, EmitOf<Emits>>): HandleTreeResult<States, Events, Emits, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, OutputStates, InputEvents, Config>;
     }
     /**
      * Any state config.
@@ -2006,13 +2212,12 @@ export declare namespace Machine {
      * @since 4.0.0
      */
     interface StateConfig<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateIdentifier<States>, EventTag extends TagOf<Events[number]>, E, R> {
-        readonly type?: "final" | "active";
         readonly entry?: (context: StateActionContext<States, Events, Emits, StateId>) => StateActionResult<E, R>;
         readonly exit?: (context: StateActionContext<States, Events, Emits, StateId>) => StateActionResult<E, R>;
         readonly invoke?: InvokeDefinition<States, Events, Emits, StateId>;
         readonly always?: (context: AlwaysContext<States, Events, Emits, StateId>) => HandlerResult<States, E, R>;
         readonly onDone?: (context: DoneContext<States, Events, Emits, StateId>) => HandlerResult<States, E, R>;
-        readonly output?: ((context: FinalOutputContext<States, Events, StateId>) => any) | ((context: ParallelOutputContext<States, Events, StateId>) => any);
+        readonly output?: ((context: FinalOutputContext<States, Events, StateId>) => unknown) | ((context: ParallelOutputContext<States, Events, StateId>) => unknown);
         readonly on?: EventHandlerMap<States, Events, Emits, StateId, EventTag, E, R>;
     }
     /**
@@ -2036,7 +2241,7 @@ export declare const isMachine: (u: unknown) => u is Machine.Any;
  * @category guards
  * @since 4.0.0
  */
-export declare const isFinal: <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema>, const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, OutputStates extends Machine.StateIdentifier<States> = never>(machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits, OutputStates>, state: Machine.Snapshot<States>) => state is Machine.SnapshotContainingFinal<States, FinalStates>;
+export declare const isFinal: <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema>, const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, OutputStates extends Machine.StateIdentifier<States> = never, InputEvents extends ReadonlyArray<Machine.TaggedSchema> = Events>(machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits, OutputStates, InputEvents>, state: Machine.Snapshot<States>) => state is Machine.SnapshotContainingFinal<States, FinalStates>;
 /**
  * Defines a state tree while preserving literal state paths.
  *
@@ -2055,7 +2260,7 @@ export declare const isFinal: <const States extends Machine.StateSchemas, const
  *
  * ```ts
  * import { Schema } from "effect"
- * import { Machine } from "effect/unstable/machine"
+ * import { Machine } from "@typeonce/effect-machine"
  *
  * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
  *
@@ -2083,11 +2288,16 @@ export declare const defineStates: <const States extends Machine.StateSchemas>(s
  * `defineStates` or is passed inline. Call `handle` on the returned definition
  * to implement state behavior with ordinary TypeScript control flow.
  *
+ * Schemas in `events` define the public input protocol. Schemas in
+ * `internalEvents` are added to the complete handler protocol for invoke
+ * results, child emissions, and other machine-local deliveries. Their tags
+ * must be disjoint.
+ *
  * **Example** (Typed counter machine)
  *
  * ```ts
  * import { Schema } from "effect"
- * import { Machine } from "effect/unstable/machine"
+ * import { Machine } from "@typeonce/effect-machine"
  *
  * class Count extends Schema.TaggedClass<Count>("Count")("Count", {
  *   value: Schema.Number
@@ -2117,14 +2327,17 @@ export declare const defineStates: <const States extends Machine.StateSchemas>(s
  * @category constructors
  * @since 4.0.0
  */
-export declare const make: <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, InitialE = never, InitialR = never>(config: {
+export declare const make: <const States extends Machine.StateSchemas, const InputEvents extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, InitialE = never, InitialR = never, const InternalEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly []>(config: {
     readonly id?: string;
     readonly states: States & DefineStateTreeInput<NoInfer<States>>;
-    readonly events: Events;
+    /** Events accepted through public machine input boundaries. */
+    readonly events: InputEvents;
+    /** Events delivered only by machine-local logic. */
+    readonly internalEvents?: InternalEvents;
     readonly emits?: Emits;
     readonly input?: Input;
     readonly initial: (...args: [...Machine.InputArgs<Input>]) => Machine.InitialResult<States, InitialE, InitialR>;
-}, ..._validation: ValidateDefinedStates<NoInfer<States>>) => Machine<States, Events, Input, Machine.StateIdentifier<States>, never, never, InitialE, InitialR, Machine.FinalStateFromDefinition<States>, never, Emits>;
+}, ..._validation: [...ValidateDefinedStates<NoInfer<States>>, ...ValidateEventProtocol<NoInfer<InputEvents>, NoInfer<InternalEvents>>]) => Machine<States, readonly [...InputEvents, ...InternalEvents], Input, Machine.StateIdentifier<States>, never, never, InitialE, InitialR, Machine.FinalStateFromDefinition<States>, Machine.TerminalOutput<States>, Emits, never, InputEvents>;
 /**
  * Encodes a decoded machine snapshot into a normalized data representation.
  *
@@ -2152,7 +2365,7 @@ export declare const make: <const States extends Machine.StateSchemas, const Eve
  * @category encoding
  * @since 4.0.0
  */
-export declare const encodeSnapshot: <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never>(machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits>, snapshot: Machine.Snapshot<States>) => Effect.Effect<Machine.EncodedSnapshot, MachineSchemaEncodeError, Machine.SnapshotEncodingServices<States>>;
+export declare const encodeSnapshot: <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, OutputStates extends Machine.StateIdentifier<States> = never, InputEvents extends ReadonlyArray<Machine.TaggedSchema> = Events>(machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits, OutputStates, InputEvents>, snapshot: Machine.Snapshot<States>) => Effect.Effect<Machine.EncodedSnapshot, MachineSchemaEncodeError, Machine.SnapshotEncodingServices<States>>;
 /**
  * Decodes a normalized data representation into a validated machine snapshot.
  *
@@ -2176,7 +2389,7 @@ export declare const encodeSnapshot: <const States extends Machine.StateSchemas,
  * @category decoding
  * @since 4.0.0
  */
-export declare const decodeSnapshot: <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never>(machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits>, encoded: unknown) => Effect.Effect<Machine.Snapshot<States>, MachineSchemaDecodeError, Machine.SnapshotDecodingServices<States>>;
+export declare const decodeSnapshot: <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, OutputStates extends Machine.StateIdentifier<States> = never, InputEvents extends ReadonlyArray<Machine.TaggedSchema> = Events>(machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits, OutputStates, InputEvents>, encoded: unknown) => Effect.Effect<Machine.Snapshot<States>, MachineSchemaDecodeError, Machine.SnapshotDecodingServices<States>>;
 /**
  * Creates an invoked child process configuration for an active state.
  *
@@ -2192,6 +2405,8 @@ export declare const decodeSnapshot: <const States extends Machine.StateSchemas,
  * 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 `id` is a state-local lifecycle key, not a communication address. To
+ * send events to the invocation, pass a typed `childAddress` as `address`.
  * 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
@@ -2201,7 +2416,7 @@ export declare const decodeSnapshot: <const States extends Machine.StateSchemas,
  *
  * ```ts
  * import { Effect, Schema } from "effect"
- * import { Machine } from "effect/unstable/machine"
+ * import { Machine } from "@typeonce/effect-machine"
  *
  * class Loaded extends Schema.TaggedClass<Loaded>("Loaded")("Loaded", {
  *   value: Schema.String
@@ -2218,11 +2433,94 @@ export declare const decodeSnapshot: <const States extends Machine.StateSchemas,
  * @category constructors
  * @since 4.0.0
  */
-export declare const invoke: <ChildState, ChildEvent, ChildError = never, ChildRequirements = never, ChildOutput = never, ChildInitialError = never, Event = never, Id extends string = string>(config: {
-    readonly id: Id;
+export declare const invoke: <ChildState, ChildEvent, ChildError = never, ChildRequirements = never, ChildOutput = never, ChildInitialError = never, Event = never, Address extends ChildAddress<never> | undefined = undefined>(config: {
+    readonly id: InvokeLifecycleId;
     readonly src: () => Logic<ChildState, ChildEvent, ChildError, ChildRequirements, ChildOutput, ChildInitialError>;
-    readonly snapshot?: (context: Machine.InvokeSnapshotContext<ChildState, ChildError | ChildInitialError, ChildOutput>) => Event | undefined;
-} & ChildAddress.Compatibility<Id, ChildEvent>) => Machine.InvokeConfig<any, any, any, any, Event, ChildState, ChildEvent, ChildError, ChildRequirements, ChildOutput, ChildInitialError>;
+    readonly snapshot?: (context: Machine.InvokeSnapshotContext<ChildState, ChildError, ChildOutput>) => Event | undefined;
+} & ([Address] extends [undefined] ? {
+    readonly address?: never;
+} : {
+    readonly address: Exclude<Address, undefined>;
+} & ChildAddress.Compatibility<Exclude<Address, undefined>, NoInfer<ChildEvent>>)) => Machine.InvokeConfig<any, any, any, any, Event, ChildState, ChildEvent, ChildError, ChildRequirements, ChildOutput, ChildInitialError>;
+type InvokeEffectResult<Requirements, Event> = Machine.InvokeConfig<any, any, any, any, never, void, never, never, Requirements, Event | void, never>;
+type InvokeEffectIsInfallible<Fx extends Effect.Effect<any, any, any>> = IsAny<Effect.Error<Fx>> extends true ? false : [Effect.Error<Fx>] extends [never] ? true : false;
+type InvokeEffectConfig<Fx extends Effect.Effect<any, any, any>, SuccessEvent, FailureEvent> = {
+    readonly id: InvokeLifecycleId;
+    readonly effect: Fx;
+    readonly onSuccess: (value: NoInfer<Effect.Success<Fx>>) => SuccessEvent | void;
+} & (InvokeEffectIsInfallible<Fx> extends true ? {
+    readonly onFailure?: never;
+} : {
+    readonly onFailure: (error: NoInfer<Effect.Error<Fx>>) => FailureEvent | void;
+});
+/**
+ * Invokes one Effect and maps its typed outcome into machine-local events.
+ *
+ * **Details**
+ *
+ * This is the high-level one-shot counterpart to `invoke`. Success and typed
+ * failure values are mapped independently, so callers do not need to recover
+ * an Effect into a common event union by hand. Defects and interruption remain
+ * failures of the owning machine.
+ *
+ * Declare mapped outcomes in `internalEvents` unless they are also legitimate
+ * public commands.
+ *
+ * @see {@link invoke} for arbitrary child process logic.
+ * @see {@link after} for a state-scoped delayed event.
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const invokeEffect: <const Fx extends Effect.Effect<any, any, any>, SuccessEvent, FailureEvent = never>(config: InvokeEffectConfig<Fx, SuccessEvent, FailureEvent>) => InvokeEffectResult<Effect.Services<Fx>, SuccessEvent | (InvokeEffectIsInfallible<Fx> extends true ? never : FailureEvent)>;
+/**
+ * Creates a cancellable state-scoped delayed event.
+ *
+ * The timer starts when its owning state is entered and is interrupted when
+ * that state exits. The delayed value should normally be declared in
+ * `internalEvents`.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const after: <Event extends {
+    readonly _tag: PropertyKey;
+}>(duration: Duration.Input, event: Event, options?: {
+    readonly id?: InvokeLifecycleId;
+}) => InvokeEffectResult<never, Event>;
+type RetagFields<Target extends Machine.TaggedSchema> = Omit<Target["~type.make.in"], "_tag">;
+type RetagTargetCompatibility<Target extends Machine.TaggedSchema> = Target extends {
+    readonly fields: Schema.Struct.Fields;
+} ? "_tag" extends keyof Target["~type.make.in"] ? {} extends Pick<Target["~type.make.in"], "_tag"> ? unknown : {
+    readonly "~effect/Machine/RetagTargetError": "Target schema must supply its discriminator when make is called";
+} : unknown : {
+    readonly "~effect/Machine/RetagTargetError": "Target schema must be one tagged struct or tagged class";
+};
+type RequiredKeys<A> = {
+    readonly [Key in keyof A]-?: {} extends Pick<A, Key> ? never : Key;
+}[keyof A];
+type CompatibleSourceKeys<Fields, Source> = {
+    readonly [Key in Extract<keyof Fields, keyof Source>]: Source[Key] extends Fields[Key] ? Key : never;
+}[Extract<keyof Fields, keyof Source>];
+type RetagPatch<Target extends Machine.TaggedSchema, Source> = Partial<RetagFields<Target>> & Pick<RetagFields<Target>, Exclude<RequiredKeys<RetagFields<Target>>, CompatibleSourceKeys<RetagFields<Target>, Source>>>;
+type RetagArgs<Target extends Machine.TaggedSchema, Source> = [
+    Exclude<RequiredKeys<RetagFields<Target>>, CompatibleSourceKeys<RetagFields<Target>, Source>>
+] extends [never] ? [patch?: RetagPatch<Target, Source>] : [patch: RetagPatch<Target, Source>];
+/**
+ * Constructs another tagged case from compatible source fields.
+ *
+ * The target must be one tagged struct or tagged class whose discriminator is
+ * supplied by its constructor. Union wrappers are rejected because their
+ * `make` operation cannot select a member after the source discriminator has
+ * been discarded. Missing or incompatible required target fields must be
+ * supplied by the patch, and the target schema's normal `make` validation
+ * remains authoritative at runtime.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const retag: <const Target extends Machine.TaggedSchema, const Source extends {
+    readonly _tag: PropertyKey;
+}>(target: Target & RetagTargetCompatibility<Target>, source: Source, ...args: RetagArgs<Target, Source>) => Target["Type"];
 type InvokeMachineInput<Input extends Schema.Top> = Input extends typeof Schema.Void ? {
     readonly input?: never;
 } : {
@@ -2254,16 +2552,16 @@ type InvokeMachineInput<Input extends Schema.Top> = Input extends typeof Schema.
  * @since 4.0.0
  */
 export declare const invokeMachine: {
-    <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, SnapshotEvent = never, DoneEvent = never, Id extends string = string>(config: {
-        readonly child: ChildMachine<Id, Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits>>;
-        readonly snapshot?: (context: Machine.InvokeSnapshotContext<Machine.Snapshot<States>, E | InitialE | ActionError<R | InitialR> | InfiniteTransitionError | MachineSchemaDecodeError | StartupError | StoppedError, Output | undefined>) => SnapshotEvent | undefined;
-        readonly onDone: (context: Machine.InvokeDoneContext<Output | undefined>) => DoneEvent | undefined;
-    } & InvokeMachineInput<Input>): Machine.InvokeConfig<any, any, any, any, SnapshotEvent, Machine.Snapshot<States>, Machine.EventOf<Events>, E | ActionError<R> | InfiniteTransitionError | MachineSchemaDecodeError | StoppedError, ExcludeCompatibleRuntime<Exclude<ExecutionServices<InitialR | R>, internalRuntime.MachineRuntime>, Machine.EventOf<Events>, Machine.EmitOf<Emits>>, Output | undefined, InitialE | ActionError<InitialR | R> | MachineSchemaDecodeError | StartupError | StoppedError, Machine.EmitOf<Emits>, DoneEvent>;
-    <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, SnapshotEvent = never, Id extends string = string>(config: {
-        readonly child: ChildMachine<Id, Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits>>;
-        readonly snapshot?: (context: Machine.InvokeSnapshotContext<Machine.Snapshot<States>, E | InitialE | ActionError<R | InitialR> | InfiniteTransitionError | MachineSchemaDecodeError | StartupError | StoppedError, Output | undefined>) => SnapshotEvent | undefined;
+    <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, SnapshotEvent = never, DoneEvent = never, Id extends string = string, OutputStates extends Machine.StateIdentifier<States> = never, InputEvents extends ReadonlyArray<Machine.TaggedSchema> = Events>(config: {
+        readonly child: ChildMachine<Id, Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits, OutputStates, InputEvents> & Machine.EnsureOutputImplementations<States, OutputStates>>;
+        readonly snapshot?: (context: Machine.InvokeSnapshotContext<Machine.Snapshot<States>, E | ActionError<R> | InfiniteTransitionError | MachineSchemaDecodeError | StoppedError, Output>) => SnapshotEvent | undefined;
+        readonly onDone: (context: Machine.InvokeDoneContext<Output>) => DoneEvent | undefined;
+    } & InvokeMachineInput<Input>): Machine.InvokeConfig<any, any, any, any, SnapshotEvent, Machine.Snapshot<States>, Machine.EventOf<InputEvents>, E | ActionError<R> | InfiniteTransitionError | MachineSchemaDecodeError | StoppedError, ExcludeCompatibleRuntime<Exclude<ExecutionServices<InitialR | R>, internalRuntime.MachineRuntime>, Machine.EventOf<Events>, Machine.EmitOf<Emits>>, Output, InitialE | E | ActionError<InitialR | R> | InfiniteTransitionError | MachineSchemaDecodeError | StartupError | StoppedError, Machine.EmitOf<Emits>, DoneEvent>;
+    <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, SnapshotEvent = never, Id extends string = string, OutputStates extends Machine.StateIdentifier<States> = never, InputEvents extends ReadonlyArray<Machine.TaggedSchema> = Events>(config: {
+        readonly child: ChildMachine<Id, Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits, OutputStates, InputEvents> & Machine.EnsureOutputImplementations<States, OutputStates>>;
+        readonly snapshot?: (context: Machine.InvokeSnapshotContext<Machine.Snapshot<States>, E | ActionError<R> | InfiniteTransitionError | MachineSchemaDecodeError | StoppedError, Output>) => SnapshotEvent | undefined;
         readonly onDone?: never;
-    } & InvokeMachineInput<Input>): Machine.InvokeConfig<any, any, any, any, SnapshotEvent, Machine.Snapshot<States>, Machine.EventOf<Events>, E | ActionError<R> | InfiniteTransitionError | MachineSchemaDecodeError | StoppedError, ExcludeCompatibleRuntime<Exclude<ExecutionServices<InitialR | R>, internalRuntime.MachineRuntime>, Machine.EventOf<Events>, Machine.EmitOf<Emits>>, Output | undefined, InitialE | ActionError<InitialR | R> | MachineSchemaDecodeError | StartupError | StoppedError, Machine.EmitOf<Emits>>;
+    } & InvokeMachineInput<Input>): Machine.InvokeConfig<any, any, any, any, SnapshotEvent, Machine.Snapshot<States>, Machine.EventOf<InputEvents>, E | ActionError<R> | InfiniteTransitionError | MachineSchemaDecodeError | StoppedError, ExcludeCompatibleRuntime<Exclude<ExecutionServices<InitialR | R>, internalRuntime.MachineRuntime>, Machine.EventOf<Events>, Machine.EmitOf<Emits>>, Output, InitialE | E | ActionError<InitialR | R> | InfiniteTransitionError | MachineSchemaDecodeError | StartupError | StoppedError, Machine.EmitOf<Emits>>;
 };
 /**
  * Plans the initial state for a machine without running deferred actions.
@@ -2286,19 +2584,24 @@ export declare const invokeMachine: {
  * @category constructors
  * @since 4.0.0
  */
-export declare const planInitial: <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never>(machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits>, ...args: [...Machine.InputArgs<Input>]) => Effect.Effect<{
+export declare const planInitial: <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, OutputStates extends Machine.StateIdentifier<States> = never, InputEvents extends ReadonlyArray<Machine.TaggedSchema> = Events>(machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits, OutputStates, InputEvents> & Machine.EnsureOutputImplementations<States, OutputStates>, ...args: [...Machine.InputArgs<Input>]) => Effect.Effect<{
     readonly state: Machine.Snapshot<States>;
     readonly actions: ReadonlyArray<Effect.Effect<void, ActionError<InitialR | R>, ActionServices<InitialR | R>>>;
     readonly emittedEvents: ReadonlyArray<Machine.EmitOf<Emits>>;
-    readonly output: Output | undefined;
-}, InitialE | MachineSchemaDecodeError | StartupError, ExcludeCompatibleRuntime<PlanningServices<InitialR | R>, Machine.EventOf<Events>, Machine.EmitOf<Emits>>>;
+} & ({
+    readonly done: true;
+    readonly output: Output;
+} | {
+    readonly done: false;
+    readonly output: undefined;
+}), InitialE | E | InfiniteTransitionError | MachineSchemaDecodeError | StartupError, ExcludeCompatibleRuntime<PlanningServices<InitialR | R>, Machine.EventOf<Events>, Machine.EmitOf<Emits>>>;
 /**
  * Returns the event tags handled by the current state snapshot.
  *
  * @category getters
  * @since 4.0.0
  */
-export declare const enabled: <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema>, const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, OutputStates extends Machine.StateIdentifier<States> = never>(machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits, OutputStates>, state: Machine.Snapshot<States>) => ReadonlyArray<Machine.TagOf<Events[number]>>;
+export declare const enabled: <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema>, const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, OutputStates extends Machine.StateIdentifier<States> = never, InputEvents extends ReadonlyArray<Machine.TaggedSchema> = Events>(machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits, OutputStates, InputEvents>, state: Machine.Snapshot<States>) => ReadonlyArray<Machine.TagOf<Events[number]>>;
 /**
  * Plans the next state snapshot without running deferred actions.
  *
@@ -2322,7 +2625,7 @@ export declare const enabled: <const States extends Machine.StateSchemas, const
  * @category combinators
  * @since 4.0.0
  */
-export declare const plan: <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never>(machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits>, state: Machine.Snapshot<States>, event: Machine.EventOf<Events>) => Effect.Effect<{
+export declare const plan: <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, OutputStates extends Machine.StateIdentifier<States> = never, InputEvents extends ReadonlyArray<Machine.TaggedSchema> = Events>(machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits, OutputStates, InputEvents> & Machine.EnsureOutputImplementations<States, OutputStates>, state: Machine.Snapshot<States>, event: Machine.EventOf<InputEvents>) => Effect.Effect<{
     readonly next: Machine.Snapshot<States>;
     readonly actions: ReadonlyArray<Effect.Effect<void, ActionError<R>, ActionServices<R>>>;
     readonly emittedEvents: ReadonlyArray<Machine.EmitOf<Emits>>;
@@ -2336,8 +2639,13 @@ export declare const plan: <const States extends Machine.StateSchemas, const Eve
         readonly entryPaths: ReadonlyArray<string>;
         readonly changed: boolean;
     }>;
-    readonly output: Output | undefined;
-}, E | InfiniteTransitionError | MachineSchemaDecodeError, ExcludeCompatibleRuntime<PlanningServices<R>, Machine.EventOf<Events>, Machine.EmitOf<Emits>>>;
+} & ({
+    readonly done: true;
+    readonly output: Output;
+} | {
+    readonly done: false;
+    readonly output: undefined;
+}), E | InfiniteTransitionError | MachineSchemaDecodeError, ExcludeCompatibleRuntime<PlanningServices<R>, Machine.EventOf<Events>, Machine.EmitOf<Emits>>>;
 /**
  * Defers an effectful action until the current machine step is planned.
  *
@@ -2346,13 +2654,14 @@ export declare const plan: <const States extends Machine.StateSchemas, const Eve
  * 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.
+ * state. Pass a second argument when the planning Effect should return that
+ * value after staging.
  *
  * **Example** (Typed staged action)
  *
  * ```ts
  * import { Context, Effect } from "effect"
- * import { Machine } from "effect/unstable/machine"
+ * import { Machine } from "@typeonce/effect-machine"
  *
  * class Audit extends Context.Service<Audit, {
  *   readonly write: Effect.Effect<void, "AuditError">
@@ -2367,7 +2676,7 @@ export declare const plan: <const States extends Machine.StateSchemas, const Eve
  * @category combinators
  * @since 4.0.0
  */
-export declare const action: <E, R>(effect: Effect.Effect<void, E, R>) => Effect.Effect<void, never, ActionRequirement<E, R>>;
+export declare const action: Machine.Action;
 /**
  * Runs staged machine actions sequentially with the supplied runtime.
  *
@@ -2421,7 +2730,7 @@ export declare const runtime: <const Protocol extends Runtime.Protocol = {}>() =
  *
  * ```ts
  * import { Effect, Schema } from "effect"
- * import { Machine } from "effect/unstable/machine"
+ * import { Machine } from "@typeonce/effect-machine"
  *
  * class LoadFailed extends Schema.TaggedClass<LoadFailed>("LoadFailed")("LoadFailed", {
  *   reason: Schema.String
@@ -2468,7 +2777,7 @@ export declare const effect: <Output, Error = never, Requirements = never>(effec
  * @category constructors
  * @since 4.0.0
  */
-export declare const logic: <State, Event = any, Output = void, Error = never, Requirements = never, InitialError = never, InitialRequirements = never>(options: {
+export declare const logic: <State, Event = never, Output = void, Error = never, Requirements = never, InitialError = never, InitialRequirements = never>(options: {
     readonly initial: State | ((scope: Logic.Scope<Event>) => Effect.Effect<State, InitialError, InitialRequirements>);
     readonly run: (context: Logic.Context<State, Event>) => Effect.Effect<Output, Error, Requirements>;
 }) => Logic<State, Event, Error, Requirements | InitialRequirements, Output, InitialError>;
@@ -2492,21 +2801,25 @@ export declare const logic: <State, Event = any, Output = void, Error = never, R
  */
 export declare const transition: <State, Event, Error = never, Requirements = never>(initial: State, transition: (state: State, event: Event) => Effect.Effect<State, Error, Requirements>) => Logic<State, Event, Error, Requirements, never>;
 /**
- * Creates a typed parent-local child address or complete machine descriptor.
+ * Creates a typed descriptor for a complete child machine.
  *
- * **When to use**
+ * Descriptors identify a child by id and machine identity, so independently
+ * constructed descriptors for the same pair address the same invoked child.
  *
- * 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 declare const child: <const Id extends string, M extends Machine.Any>(id: Id, machine: M) => ChildMachine<Id, M>;
+/**
+ * Creates a typed parent-local address for lower-level child process logic.
+ *
+ * The default event protocol is `never`; provide an event type before using
+ * the address with `spawn`, `invoke`, or `sendTo`.
  *
  * @category constructors
  * @since 4.0.0
  */
-export declare const child: {
-    <const Id extends string, M extends Machine.Any>(id: Id, machine: M): ChildMachine<Id, M>;
-    <Event>(id: string): ChildAddress<Event>;
-};
+export declare const childAddress: <Event = never>(id: string) => ChildAddress<Event>;
 /**
  * Spawns a child process owned by the currently running machine.
  *
@@ -2539,7 +2852,7 @@ export declare const spawn: {
  */
 export declare const sendTo: {
     <Child extends ChildMachine.Any>(child: Child, event: ChildMachine.Event<Child>): Effect.Effect<void, StoppedError, MachineRuntimeRequirement>;
-    <Address extends string>(id: Address, event: ChildAddress.Event<Address>): Effect.Effect<void, StoppedError, MachineRuntimeRequirement>;
+    <Address extends ChildAddress<never>>(id: Address, event: ChildAddress.Event<Address>): Effect.Effect<void, StoppedError, MachineRuntimeRequirement>;
 };
 /**
  * Stops a named child process of the running machine.
@@ -2547,7 +2860,10 @@ export declare const sendTo: {
  * @category runtime
  * @since 4.0.0
  */
-export declare const stopChild: (child: string | ChildMachine.Any) => Effect.Effect<void, never, MachineRuntimeRequirement>;
+export declare const stopChild: {
+    <Event>(child: ChildAddress<Event>): Effect.Effect<void, never, MachineRuntimeRequirement>;
+    <Child extends ChildMachine.Any>(child: Child): Effect.Effect<void, never, MachineRuntimeRequirement>;
+};
 /**
  * Returns a stream of terminal lifecycle outcomes for a running machine.
  *
@@ -2583,5 +2899,5 @@ export declare const watch: <State, Event, Error = never, Output = never>(ref: M
  * @category constructors
  * @since 4.0.0
  */
-export declare const start: <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never>(machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits>, ...args: [...Machine.InputArgs<Input>]) => Effect.Effect<MachineRef<Machine.Snapshot<States>, Machine.EventOf<Events>, E | InitialE | ActionError<R | InitialR> | InfiniteTransitionError | MachineSchemaDecodeError | StartupError | StoppedError, Output | undefined>, InitialE | ActionError<InitialR | R> | MachineSchemaDecodeError | StartupError | StoppedError, ExcludeCompatibleRuntime<ExecutionServices<InitialR | R>, Machine.EventOf<Events>, Machine.EmitOf<Emits>>>;
+export declare const start: <const States extends Machine.StateSchemas, const Events extends ReadonlyArray<Machine.TaggedSchema>, const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [], const Input extends Schema.Top = typeof Schema.Void, UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>, E = never, R = never, InitialE = never, InitialR = never, FinalStates extends Machine.StateIdentifier<States> = never, Output = never, OutputStates extends Machine.StateIdentifier<States> = never, InputEvents extends ReadonlyArray<Machine.TaggedSchema> = Events>(machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits, OutputStates, InputEvents> & Machine.EnsureOutputImplementations<States, OutputStates>, ...args: [...Machine.InputArgs<Input>]) => Effect.Effect<MachineRef<Machine.Snapshot<States>, Machine.EventOf<InputEvents>, E | ActionError<R> | InfiniteTransitionError | MachineSchemaDecodeError | StoppedError, Output>, InitialE | E | ActionError<InitialR | R> | InfiniteTransitionError | MachineSchemaDecodeError | StartupError | StoppedError, ExcludeCompatibleRuntime<ExecutionServices<InitialR | R>, Machine.EventOf<Events>, Machine.EmitOf<Emits>>>;
 //# sourceMappingURL=Machine.d.ts.map