@typeonce/effect-machine 0.8.0 → 0.10.0

package/src/internal/machine/activities.ts

@@ -4,8 +4,7 @@
  * @since 0.4.0
  */
 
-/** @internal */
-export const ActivityMetadataTypeId: unique symbol = Symbol.for("effect/Machine/ActivityMetadata")
+import * as Duration from "effect/Duration"
 
 /** @internal */
 export type StaticActivityMetadata =
@@ -21,8 +20,7 @@ export type StaticActivityMetadata =
   }
   | {
     readonly type: "timer"
-    readonly duration: string
-    readonly event: string
+    readonly duration: string | "dynamic"
   }
   | {
     readonly type: "machine"
@@ -33,20 +31,10 @@ export type StaticActivityMetadata =
   }
 
 /** @internal */
-export type ActivityDefinition<Source extends string = string> =
-  | ({
-    readonly source: Source
-    readonly id: string
-  } & StaticActivityMetadata)
-  | {
-    readonly source: Source
-    readonly type: "dynamic"
-  }
-
-interface ActivityDescriptor {
+export type ActivityDefinition<Source extends string = string> = {
+  readonly source: Source
   readonly id: string
-  readonly [ActivityMetadataTypeId]: StaticActivityMetadata
-}
+} & StaticActivityMetadata
 
 interface InspectableMachine {
   readonly handlers: unknown
@@ -62,31 +50,60 @@ const isObject = (value: unknown): value is object =>
 
 const getProperty = (value: unknown, key: PropertyKey): unknown => isObject(value) ? Reflect.get(value, key) : undefined
 
-const hasActivityMetadata = (value: unknown): value is ActivityDescriptor =>
-  isObject(value) && typeof getProperty(value, "id") === "string" &&
-  isObject(getProperty(value, ActivityMetadataTypeId))
-
 const appendStaticDefinition = (
   definitions: Array<ActivityDefinition>,
   source: string,
   descriptor: unknown
 ): void => {
-  if (!hasActivityMetadata(descriptor)) {
+  if (!isObject(descriptor)) return
+  const child = getProperty(descriptor, "child")
+  if (isObject(child)) {
+    const id = getProperty(child, "id")
+    if (typeof id !== "string") return
+    const machine = getProperty(child, "machine")
+    const machineId = getProperty(machine, "id")
+    definitions.push({
+      source,
+      id,
+      type: "machine",
+      child: { id, machineId: typeof machineId === "string" ? machineId : null }
+    })
     return
   }
-  definitions.push({
-    source,
-    id: descriptor.id,
-    ...descriptor[ActivityMetadataTypeId]
-  })
+  const id = getProperty(descriptor, "id")
+  if (typeof id !== "string") return
+  if (Reflect.has(descriptor, "effect")) {
+    definitions.push({
+      source,
+      id,
+      type: "effect",
+      outcomes: {
+        success: "dynamic",
+        failure: Reflect.has(descriptor, "onFailure") ? "dynamic" : "none"
+      }
+    })
+    return
+  }
+  if (Reflect.has(descriptor, "after")) {
+    const after = getProperty(descriptor, "after")
+    definitions.push({
+      source,
+      id,
+      type: "timer",
+      duration: typeof after === "function" ? "dynamic" : Duration.format(Duration.fromInputUnsafe(after as any))
+    })
+    return
+  }
+  if (Reflect.has(descriptor, "logic")) {
+    definitions.push({ source, id, type: "process" })
+  }
 }
 
 /**
  * Collects state-owned activity descriptions without executing user code.
  *
- * Function-valued invoke definitions depend on an entry context and are
- * therefore represented as dynamic. Static descriptors are returned in state
- * definition order and descriptor array order.
+ * Source factories are inspected without execution. Static descriptors are
+ * returned in state definition order and descriptor array order.
  *
  * @internal
  */
@@ -94,9 +111,7 @@ export const activityDefinitions = (machine: InspectableMachine): ReadonlyArray<
   const definitions: Array<ActivityDefinition> = []
   for (const node of machine.stateNodes.byPath.values()) {
     const invoke = getProperty(getProperty(machine.handlers, node.path), "invoke")
-    if (typeof invoke === "function") {
-      definitions.push({ source: node.path, type: "dynamic" })
-    } else if (Array.isArray(invoke)) {
+    if (Array.isArray(invoke)) {
       for (const descriptor of invoke) {
         appendStaticDefinition(definitions, node.path, descriptor)
       }

package/src/internal/machine/atom.ts

@@ -72,9 +72,9 @@ type MachineStartError<InitialE, E, InitialR, R, RuntimeError = never> =
   | Machine.StoppedError
   | RuntimeError
 
-const runMachineAtomEffect = <State, Event, Error, Output, StartError, Requirements>(
+const runMachineAtomEffect = <State, Event, Error, Output, Emitted, StartError, Requirements>(
   get: Atom.AtomContext,
-  start: Effect.Effect<Machine.MachineRef<State, Event, Error, Output>, StartError, Requirements>
+  start: Effect.Effect<Machine.MachineRef<State, Event, Error, Output, Emitted>, StartError, Requirements>
 ): Effect.Effect<never, StartError, Requirements> =>
   Effect.scoped(
     Effect.acquireRelease(start, (ref) => ref.stop).pipe(
@@ -96,7 +96,8 @@ const startMachineAtomEffect = <
   FinalStates extends Machine.Machine.StateIdentifier<States> = never,
   Output = never,
   OutputStates extends Machine.Machine.StateIdentifier<States> = never,
-  InputEvents extends ReadonlyArray<Machine.Machine.TaggedSchema> = Events
+  InputEvents extends ReadonlyArray<Machine.Machine.TaggedSchema> = Events,
+  ParentEvents extends ReadonlyArray<Machine.Machine.TaggedSchema> = readonly []
 >(
   get: Atom.AtomContext,
   machine:
@@ -113,20 +114,22 @@ const startMachineAtomEffect = <
       Output,
       Emits,
       OutputStates,
-      InputEvents
+      InputEvents,
+      ParentEvents
     >
     & EnsureExecutable<States, UnhandledStates, OutputStates>,
   args: [...Machine.Machine.InputArgs<Input>]
 ): Effect.Effect<
   Machine.MachineRef<
     Machine.Machine.Snapshot<States>,
-    Machine.Machine.EventOf<InputEvents>,
+    Machine.Machine.EventInputOf<InputEvents>,
     MachineRuntimeError<E, R>,
-    Output
+    Output,
+    Machine.Machine.EmittedEventOf<Emits>
   >,
   MachineStartError<InitialE, E, InitialR, R>,
   MachineRequirements<InitialR, R, Machine.Machine.EventOf<Events>, Machine.Machine.EmitOf<Emits>>
-> => runMachineAtomEffect(get, internalMachine.start(machine, ...args))
+> => runMachineAtomEffect(get, internalMachine.start(machine as any, ...args) as any)
 
 const resumeMachineAtomEffect = (
   get: Atom.AtomContext,
@@ -137,6 +140,24 @@ const resumeMachineAtomEffect = (
 type RefState<Ref> = Ref extends Machine.MachineRef<infer State, any, any, any> ? State : never
 type RefError<Ref> = Ref extends Machine.MachineRef<any, any, infer Error, any> ? Error : never
 type RefOutput<Ref> = Ref extends Machine.MachineRef<any, any, any, infer Output> ? Output : never
+type RefEmitted<Ref> = Ref extends Machine.MachineRef<any, any, any, any, infer Emitted> ? Emitted : never
+
+export const emissions = <State, Event, Error, Output, StartError, Emitted>(
+  self: MachineAtom<State, Event, Error, Output, StartError, Emitted>
+): Stream.Stream<Emitted, StartError, AtomRegistry.AtomRegistry> =>
+  Atom.toStreamResult(self.ref).pipe(Stream.flatMap((ref) => ref.emissions))
+
+export const childEmissions = <Child extends Machine.ChildMachine.Any, StartError>(
+  self: ChildMachineAtom<Child, StartError>
+): Stream.Stream<RefEmitted<Machine.ChildMachine.Ref<Child>>, StartError, AtomRegistry.AtomRegistry> =>
+  Atom.toStreamResult(self.ref).pipe(
+    Stream.flatMap(
+      Option.match({
+        onNone: () => Stream.empty,
+        onSome: (ref) => ref.emissions
+      })
+    )
+  )
 
 const makeRuntimeResultAtom = <State, Error, Output, StartError>(
   snapshot: Atom.Atom<AsyncResult.AsyncResult<Machine.RuntimeSnapshot<State, Error, Output>, StartError>>
@@ -585,10 +606,11 @@ type EnsureMachineExecutable<M extends Machine.Machine.Any> = IsAny<Machine.Mach
 
 type ResumedMachineAtomOf<M extends Machine.Machine.Any, RuntimeError> = MachineAtom<
   Machine.Machine.Snapshot<Machine.Machine.States<M>>,
-  Machine.Machine.InputEvent<M>,
+  Machine.Machine.EventInput<Machine.Machine.InputEvent<M>>,
   MachineRuntimeError<Machine.Machine.Error<M>, Machine.Machine.Services<M>>,
   Machine.Machine.Output<M>,
-  Machine.MachineSchemaDecodeError | RuntimeError
+  Machine.MachineSchemaDecodeError | RuntimeError,
+  Machine.Machine.EmittedEvent<M>
 >
 
 export const make: {
@@ -605,7 +627,8 @@ export const make: {
     FinalStates extends Machine.Machine.StateIdentifier<States> = never,
     Output = never,
     OutputStates extends Machine.Machine.StateIdentifier<States> = never,
-    InputEvents extends ReadonlyArray<Machine.Machine.TaggedSchema> = Events
+    InputEvents extends ReadonlyArray<Machine.Machine.TaggedSchema> = Events,
+    ParentEvents extends ReadonlyArray<Machine.Machine.TaggedSchema> = readonly []
   >(
     machine:
       & Machine.Machine<
@@ -621,7 +644,8 @@ export const make: {
         Output,
         Emits,
         OutputStates,
-        InputEvents
+        InputEvents,
+        ParentEvents
       >
       & EnsureNoExternalRequirements<
         MachineRequirements<
@@ -635,10 +659,11 @@ export const make: {
     ...args: [...Machine.Machine.InputArgs<Input>]
   ): MachineAtom<
     Machine.Machine.Snapshot<States>,
-    Machine.Machine.EventOf<InputEvents>,
+    Machine.Machine.EventInputOf<InputEvents>,
     MachineRuntimeError<E, R>,
     Output,
-    MachineStartError<InitialE, E, InitialR, R>
+    MachineStartError<InitialE, E, InitialR, R>,
+    Machine.Machine.EmittedEventOf<Emits>
   >
 } = ((machine: Machine.Machine.Any, ...args: ReadonlyArray<unknown>) => {
   const ref = Atom.make((get) => startMachineAtomEffect(get, machine as any, args as []))

package/src/internal/machine/cluster.ts

@@ -14,6 +14,7 @@ import { Rpc } from "effect/unstable/rpc"
 import type * as Machine from "../../Machine.js"
 import type { Checkpoint, ClusterMachine, LoadResult } from "../../unstable/cluster/ClusterMachine.js"
 import * as internalMachine from "./machine.js"
+import * as Protocol from "./protocol.js"
 import type { EnsureExecutable } from "./readiness.js"
 
 type EntityAddress = EntityAddress.EntityAddress
@@ -248,7 +249,7 @@ export const make = <
     OutputStates,
     InputEvents
   >
-  const eventSchema = Schema.Union(machine.events as MachineEvents<M>)
+  const eventSchema = Schema.Union(Protocol.inputEventSchemas(machine) as MachineEvents<M>)
   const rpc = Rpc.make("send", {
     payload: eventSchema,
     success: SendResult

package/src/internal/machine/command.ts

@@ -47,8 +47,8 @@ export const makeCollector = <Event>(machine: Machine.Any): Collected<Event> =>
       emit: (event) => {
         emittedEvents.push(decodeEmitSync(machine, event))
       },
-      sendTo: (child: unknown, event: unknown) => {
-        commands.push({ _tag: "SendTo", child: child as any, event })
+      sendTo: (target: unknown, event: unknown) => {
+        commands.push({ _tag: "SendTo", target: target as any, event })
       },
       stop: (child: unknown) => {
         commands.push({ _tag: "Stop", child: child as any })

package/src/internal/machine/commandRuntime.ts

@@ -10,6 +10,9 @@ import type { RuntimeCommand } from "./command.js"
 import { decodeEmit, decodeEvent } from "./protocol.js"
 import type { ProcessScope } from "./runtime.js"
 
+const isActorRef = (target: unknown): target is { readonly send: (event: unknown) => Effect.Effect<void, unknown> } =>
+  typeof target === "object" && target !== null && "send" in target && typeof target.send === "function"
+
 export const makeLiveRuntime = <Events, Emits>(
   machine: Machine.Any,
   scope: ProcessScope<Events>
@@ -18,9 +21,9 @@ export const makeLiveRuntime = <Events, Emits>(
     decodeEvent(machine, event).pipe(
       Effect.flatMap((event) => scope.self.send(event as Events))
     ),
-  sendParent: (event) =>
+  emit: (event) =>
     decodeEmit(machine, event).pipe(
-      Effect.flatMap((event) => scope.sendParent(event))
+      Effect.flatMap((event) => scope.emit(event))
     )
 })
 
@@ -30,7 +33,9 @@ export const runCommands = <Event>(
 ) =>
   Effect.forEach(commands, (command) =>
     command._tag === "SendTo"
-      ? scope.sendTo(command.child as never, command.event)
+      ? isActorRef(command.target)
+        ? command.target.send(command.event)
+        : scope.sendTo(command.target as never, command.event)
       : scope.stopChild(command.child as never), { discard: true })
 
 export const runEmittedEvents = <Events, Emits>(
@@ -38,6 +43,6 @@ export const runEmittedEvents = <Events, Emits>(
   runtime: Runtime<Events, Emits>
 ) =>
   Effect.all(
-    Array.from(events, (event) => runtime.sendParent(event)),
+    Array.from(events, (event) => runtime.emit(event)),
     { discard: true }
   )

package/src/internal/machine/configuration.ts

@@ -8,7 +8,7 @@ import * as Cause from "effect/Cause"
 import * as Effect from "effect/Effect"
 import * as Option from "effect/Option"
 import { hasProperty } from "effect/Predicate"
-import type { Machine } from "../../Machine.js"
+import type { ActorRef, Machine } from "../../Machine.js"
 import { MachineSchemaDecodeError } from "./errors.js"
 import {
   decodeBoundary,
@@ -252,8 +252,26 @@ export interface ActiveConfiguration {
   readonly values: ReadonlyMap<string, unknown>
   readonly outputs: ReadonlyMap<string, unknown>
   readonly history: ReadonlyMap<string, HistoryRecord>
+  readonly actorScope?: PlanningActorScope
 }
 
+export interface PlanningActorScope {
+  readonly self: ActorRef<any>
+  readonly parent: ActorRef<any> | undefined
+}
+
+export const withActorScope = (
+  configuration: ActiveConfiguration,
+  actorScope: PlanningActorScope
+): ActiveConfiguration => ({
+  ...configuration,
+  actorScope: { self: actorScope.self, parent: actorScope.parent }
+})
+
+export const getActorScope = (
+  configuration: ActiveConfiguration
+): PlanningActorScope | undefined => configuration.actorScope
+
 export interface FinalCompletion {
   readonly path: string
   readonly output: unknown
@@ -1178,8 +1196,8 @@ export const resolveFinalOutputEffect: <
   const node = getNode(machine, path)
   const output = getStateConfigByPath(machine, path)?.output?.({
     state: configuration.values.get(path),
-    parent: getParentValue(machine, configuration, path),
-    parents: getParentValues(machine, configuration, path),
+    containingState: getParentValue(machine, configuration, path),
+    ancestors: getParentValues(machine, configuration, path),
     event,
     outputs
   } as any)
@@ -1331,8 +1349,8 @@ const resolveFinalOutputSync = <const Events extends ReadonlyArray<Machine.Tagge
   const node = getNode(machine, path)
   const output = getStateConfigByPath(machine, path)?.output?.({
     state: configuration.values.get(path),
-    parent: getParentValue(machine, configuration, path),
-    parents: getParentValues(machine, configuration, path),
+    containingState: getParentValue(machine, configuration, path),
+    ancestors: getParentValues(machine, configuration, path),
     event,
     outputs
   } as any)

package/src/internal/machine/errors.ts

@@ -25,7 +25,7 @@ export class MachineSchemaEncodeError extends Data.TaggedError("MachineSchemaEnc
  */
 export class MachineSchemaDecodeError extends Data.TaggedError("MachineSchemaDecodeError")<{
   readonly machineId: string | undefined
-  readonly boundary: "input" | "event" | "emit" | "state" | "output" | "history" | "configuration"
+  readonly boundary: "input" | "event" | "emission" | "state" | "output" | "history" | "configuration"
   readonly state?: string
   readonly event?: string
   readonly cause: Schema.SchemaError | Cause.Cause<unknown>

package/src/internal/machine/executionPlan.ts

@@ -4,7 +4,8 @@
  * @since 0.4.0
  */
 
-import type { Machine } from "../../Machine.js"
+import * as Effect from "effect/Effect"
+import type { ActorRef, Machine } from "../../Machine.js"
 import { getTargetBuilder, type RuntimeCommand } from "./command.js"
 import {
   type ActiveConfiguration,
@@ -17,10 +18,13 @@ import {
   isDescendantOf,
   normalizeConfigurationSync,
   normalizeTargetConfigurationSync,
+  type PlanningActorScope,
   snapshotFromConfiguration,
-  validateInitialConfiguration
+  validateInitialConfiguration,
+  withActorScope
 } from "./configuration.js"
-import { InfiniteTransitionError } from "./errors.js"
+import { InfiniteTransitionError, StoppedError } from "./errors.js"
+import * as InvocationEvent from "./invocationEvent.js"
 import {
   broadenTransitionBoundary,
   type EvaluatedTransition,
@@ -42,7 +46,7 @@ import {
   validateDeclaredTransitionTarget
 } from "./planner.js"
 import { decodeEmitSync, decodeEventSync, decodeInputSync, decodeStateValueSync } from "./protocol.js"
-import { isSnapshot, isTarget, TargetSnapshotTypeId } from "./topology.js"
+import { isNoTarget, isSnapshot, isTarget, TargetSnapshotTypeId } from "./topology.js"
 
 interface IndexedExecutionDescriptor {
   readonly flat: boolean
@@ -63,6 +67,29 @@ interface IndexedExecutionDescriptor {
   >
 }
 
+const planningActorScopes = new WeakMap<Machine.Any, PlanningActorScope>()
+
+const getPlanningActorScope = (machine: Machine.Any): PlanningActorScope => {
+  const cached = planningActorScopes.get(machine)
+  if (cached !== undefined) return cached
+  const self: ActorRef<unknown> = {
+    id: machine.id ?? "Machine",
+    sessionId: "Machine.plan",
+    send: () => Effect.fail(new StoppedError())
+  }
+  const scope = { self, parent: undefined }
+  planningActorScopes.set(machine, scope)
+  return scope
+}
+
+const getActorContext = (
+  machine: Machine.Any,
+  actorScope: PlanningActorScope | undefined
+): PlanningActorScope =>
+  actorScope === undefined
+    ? getPlanningActorScope(machine)
+    : { self: actorScope.self, parent: actorScope.parent }
+
 const indexedStateConfigKeys: ReadonlySet<PropertyKey> = new Set([
   "initial",
   "invoke",
@@ -335,18 +362,20 @@ const makeIndexedTransitionContext = (
   descriptor: IndexedExecutionDescriptor,
   configuration: OwnedIndexedState,
   sourceIndex: number,
-  event: any
+  event: any,
+  actorScope?: PlanningActorScope
 ): any => {
   const source = descriptor.nodes[sourceIndex]!
   const parentIndex = descriptor.parentIndices[sourceIndex]!
-  const parents: Record<string, unknown> = {}
+  const ancestors: Record<string, unknown> = {}
   for (const ancestorIndex of descriptor.ancestorIndices[sourceIndex]!) {
-    parents[descriptor.nodes[ancestorIndex]!.path] = configuration.values[ancestorIndex]
+    ancestors[descriptor.nodes[ancestorIndex]!.path] = configuration.values[ancestorIndex]
   }
   return {
+    ...getActorContext(machine, actorScope),
     state: configuration.values[sourceIndex],
-    parent: parentIndex < 0 ? undefined : configuration.values[parentIndex],
-    parents,
+    containingState: parentIndex < 0 ? undefined : configuration.values[parentIndex],
+    ancestors,
     event,
     snapshot: snapshotFromIndexedState(descriptor, configuration),
     target: getTargetBuilder(machine, source.path)
@@ -398,7 +427,7 @@ const collectIndexedTransition = (
   let commands: Array<RuntimeCommand> | undefined
   let raisedEvents: Array<any> | undefined
   let emittedEvents: Array<unknown> | undefined
-  const state = transition(context, {
+  const result = transition(context, {
     raise: (event: unknown) => {
       ;(raisedEvents ??= []).push(decodeEventSync(machine, event))
     },
@@ -406,14 +435,14 @@ const collectIndexedTransition = (
       ;(emittedEvents ??= []).push(decodeEmitSync(machine, event))
     },
     sendTo: (child: unknown, event: unknown) => {
-      ;(commands ??= []).push({ _tag: "SendTo", child: child as any, event })
+      ;(commands ??= []).push({ _tag: "SendTo", target: child as any, event })
     },
     stop: (child: unknown) => {
       ;(commands ??= []).push({ _tag: "Stop", child: child as any })
     }
   })
   return {
-    state,
+    state: isNoTarget(result) ? undefined : result,
     commands: commands ?? emptyExecutionValues,
     raisedEvents: raisedEvents ?? emptyExecutionValues,
     emittedEvents: emittedEvents ?? emptyExecutionValues
@@ -424,7 +453,8 @@ const selectIndexedEventTransitions = (
   machine: Machine.Any,
   descriptor: IndexedExecutionDescriptor,
   configuration: OwnedIndexedState,
-  event: any
+  event: any,
+  actorScope?: PlanningActorScope
 ): ReadonlyArray<IndexedSelectedTransition> => {
   const selected: Array<IndexedSelectedTransition> = []
   for (const leafIndex of configuration.activeLeaves) {
@@ -445,7 +475,8 @@ const selectIndexedEventTransitions = (
             descriptor,
             configuration,
             sourceIndex,
-            event
+            event,
+            actorScope
           )
         })
       }
@@ -628,7 +659,8 @@ const planIndexedFlatState = (
   descriptor: IndexedExecutionDescriptor,
   configuration: OwnedIndexedState,
   decoded: { readonly _tag: PropertyKey },
-  retainMicrosteps: boolean
+  retainMicrosteps: boolean,
+  actorScope?: PlanningActorScope
 ): ExecutionMacrostep<OwnedIndexedState> => {
   let current = configuration
   let event: any = decoded
@@ -680,9 +712,10 @@ const planIndexedFlatState = (
         machine,
         transition.transition,
         {
+          ...getActorContext(machine, actorScope),
           state: current.values[sourceIndex],
-          parent: undefined,
-          parents: {},
+          containingState: undefined,
+          ancestors: {},
           event,
           snapshot: snapshotFromIndexedState(descriptor, current),
           target: getTargetBuilder(machine, sourcePath)
@@ -773,11 +806,42 @@ const planIndexedState = (
   descriptor: IndexedExecutionDescriptor,
   configuration: OwnedIndexedState,
   input: unknown,
-  retainMicrosteps: boolean
+  retainMicrosteps: boolean,
+  actorScope?: PlanningActorScope
 ): ExecutionMacrostep<OwnedIndexedState> => {
+  if (InvocationEvent.isInvocationEvent(input)) {
+    // Invocation lifecycle transitions retain the generic planner as their
+    // semantic reference. Ordinary machine events and initialization stay on
+    // the indexed representation; only the private lifecycle macrostep crosses
+    // the representation boundary.
+    const planned = planConfiguration(
+      machine as any,
+      actorScope === undefined
+        ? activeConfigurationFromIndexedState(descriptor, configuration)
+        : withActorScope(activeConfigurationFromIndexedState(descriptor, configuration), actorScope),
+      input
+    )
+    return {
+      next: ownedIndexedStateFromActive(descriptor, planned.next),
+      commands: planned.commands,
+      emittedEvents: planned.emittedEvents,
+      microsteps: planned.microsteps.map((step) => ({
+        next: ownedIndexedStateFromActive(descriptor, step.next),
+        event: step.event,
+        commands: step.commands,
+        raisedEvents: step.raisedEvents,
+        emittedEvents: step.emittedEvents,
+        exitPaths: step.exitPaths,
+        entryPaths: step.entryPaths,
+        changed: step.changed
+      })),
+      done: planned.done,
+      output: planned.output
+    }
+  }
   const decoded = decodeEventSync(machine, input)
   if (descriptor.flat) {
-    return planIndexedFlatState(machine, descriptor, configuration, decoded, retainMicrosteps)
+    return planIndexedFlatState(machine, descriptor, configuration, decoded, retainMicrosteps, actorScope)
   }
   if (descriptor.finalIndices.some((index) => configuration.active[index] === 1)) {
     const active = activeConfigurationFromIndexedState(descriptor, configuration)
@@ -798,7 +862,7 @@ const planIndexedState = (
     }
   }
 
-  const selections = selectIndexedEventTransitions(machine, descriptor, configuration, decoded)
+  const selections = selectIndexedEventTransitions(machine, descriptor, configuration, decoded, actorScope)
   if (selections.length === 0) {
     return {
       next: configuration,
@@ -866,7 +930,7 @@ const planIndexedState = (
     }
     raisedIndex += 1
     currentEvent = raised
-    const raisedSelections = selectIndexedEventTransitions(machine, descriptor, current, raised)
+    const raisedSelections = selectIndexedEventTransitions(machine, descriptor, current, raised, actorScope)
     if (raisedSelections.length === 0) continue
     const step = indexedMicrostep(machine, descriptor, current, raised, raisedSelections)
     current = step.next
@@ -884,10 +948,12 @@ export interface CompiledExecutionPlan {
   readonly plan: (
     state: unknown,
     event: unknown,
-    retainMicrosteps?: boolean
+    retainMicrosteps?: boolean,
+    actorScope?: PlanningActorScope
   ) => ExecutionMacrostep
   readonly initial?: (
-    args: ReadonlyArray<unknown>
+    args: ReadonlyArray<unknown>,
+    actorScope?: PlanningActorScope
   ) => {
     readonly state: Machine.Snapshot<any>
     readonly configuration: unknown
@@ -904,7 +970,14 @@ const makeActiveExecutionPlan = (machine: Machine.Any): CompiledExecutionPlan =>
   fromConfiguration: (configuration) => configuration,
   toConfiguration: (state) => state as ActiveConfiguration,
   snapshot: (state) => snapshotFromConfiguration(machine, state as ActiveConfiguration),
-  plan: (state, event) => planConfiguration(machine as any, state as ActiveConfiguration, event as any)
+  plan: (state, event, _retainMicrosteps, actorScope) =>
+    planConfiguration(
+      machine as any,
+      actorScope === undefined
+        ? state as ActiveConfiguration
+        : withActorScope(state as ActiveConfiguration, actorScope),
+      event as any
+    )
 })
 
 const makeIndexedExecutionPlan = (
@@ -914,16 +987,17 @@ const makeIndexedExecutionPlan = (
   fromConfiguration: (configuration) => ownedIndexedStateFromActive(indexed, configuration),
   toConfiguration: (state) => activeConfigurationFromIndexedState(indexed, state as OwnedIndexedState),
   snapshot: (state) => snapshotFromIndexedState(indexed, state as OwnedIndexedState),
-  plan: (state, event, retainMicrosteps = false) =>
-    planIndexedState(machine, indexed, state as OwnedIndexedState, event, retainMicrosteps),
-  initial: (args) => {
+  plan: (state, event, retainMicrosteps = false, actorScope) =>
+    planIndexedState(machine, indexed, state as OwnedIndexedState, event, retainMicrosteps, actorScope),
+  initial: (args, actorScope) => {
     const inputArgs = machine.input === undefined
       ? args
       : args.length === 0
       ? (decodeInputSync(machine, machine.input, undefined), args)
       : [decodeInputSync(machine, machine.input, args[0])]
     const initial = machine.initial(...inputArgs as any)
-    const active = normalizeConfigurationSync(machine, initial as Machine.Snapshot<any>)
+    const normalized = normalizeConfigurationSync(machine, initial as Machine.Snapshot<any>)
+    const active = actorScope === undefined ? normalized : withActorScope(normalized, actorScope)
     validateInitialConfiguration(machine, active)
     const completed = completeConfigurationSync(machine, active, InitialEvent).configuration
     const configuration = ownedIndexedStateFromActive(indexed, completed)