@typeonce/effect-machine 0.9.0 → 0.11.0

package/src/internal/machine/atom.ts

@@ -7,11 +7,12 @@
 import * as Data from "effect/Data"
 import * as Effect from "effect/Effect"
 import * as Equal from "effect/Equal"
+import * as Fiber from "effect/Fiber"
 import * as Option from "effect/Option"
 import type * as Schema from "effect/Schema"
 import type * as Scope from "effect/Scope"
 import * as Stream from "effect/Stream"
-import { AsyncResult, Atom, type AtomRegistry } from "effect/unstable/reactivity"
+import { AsyncResult, Atom, AtomRegistry } from "effect/unstable/reactivity"
 import type * as Machine from "../../Machine.js"
 import type { Bound, ChildMachineAtom, MachineAtom } from "../../unstable/reactivity/AtomMachine.js"
 import * as internalMachine from "./machine.js"
@@ -72,9 +73,14 @@ type MachineStartError<InitialE, E, InitialR, R, RuntimeError = never> =
   | Machine.StoppedError
   | RuntimeError
 
-const runMachineAtomEffect = <State, Event, Error, Output, StartError, Requirements>(
+const preparedByMachineAtom = new WeakMap<
+  object,
+  Atom.Atom<AsyncResult.AsyncResult<Machine.Prepared<any, any, any, any, any, any, any>, any>>
+>()
+
+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(
@@ -83,50 +89,16 @@ const runMachineAtomEffect = <State, Event, Error, Output, StartError, Requireme
     )
   )
 
-const startMachineAtomEffect = <
-  const States extends Machine.Machine.StateSchemas,
-  const Events extends ReadonlyArray<Machine.Machine.TaggedSchema>,
-  const Emits extends ReadonlyArray<Machine.Machine.TaggedSchema> = any,
-  const Input extends Schema.Top = typeof Schema.Void,
-  UnhandledStates extends Machine.Machine.StateIdentifier<States> = Machine.Machine.StateIdentifier<States>,
-  E = never,
-  R = never,
-  InitialE = never,
-  InitialR = never,
-  FinalStates extends Machine.Machine.StateIdentifier<States> = never,
-  Output = never,
-  OutputStates extends Machine.Machine.StateIdentifier<States> = never,
-  InputEvents extends ReadonlyArray<Machine.Machine.TaggedSchema> = Events
->(
+const startPreparedMachineAtomEffect = <State, Event, Error, Output, Emitted, StartError, Requirements>(
   get: Atom.AtomContext,
-  machine:
-    & Machine.Machine<
-      States,
-      Events,
-      Input,
-      UnhandledStates,
-      E,
-      R,
-      InitialE,
-      InitialR,
-      FinalStates,
-      Output,
-      Emits,
-      OutputStates,
-      InputEvents
+  prepared: Atom.Atom<
+    AsyncResult.AsyncResult<
+      Machine.Prepared<State, Event, Error, Output, Emitted, StartError, Requirements>,
+      never
     >
-    & EnsureExecutable<States, UnhandledStates, OutputStates>,
-  args: [...Machine.Machine.InputArgs<Input>]
-): Effect.Effect<
-  Machine.MachineRef<
-    Machine.Machine.Snapshot<States>,
-    Machine.Machine.EventInputOf<InputEvents>,
-    MachineRuntimeError<E, R>,
-    Output
-  >,
-  MachineStartError<InitialE, E, InitialR, R>,
-  MachineRequirements<InitialR, R, Machine.Machine.EventOf<Events>, Machine.Machine.EmitOf<Emits>>
-> => runMachineAtomEffect(get, internalMachine.start(machine, ...args))
+  >
+): Effect.Effect<never, StartError, Requirements> =>
+  runMachineAtomEffect(get, get.result(prepared).pipe(Effect.flatMap((prepared) => prepared.start)))
 
 const resumeMachineAtomEffect = (
   get: Atom.AtomContext,
@@ -137,6 +109,47 @@ 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> => {
+  const prepared = preparedByMachineAtom.get(self as object)
+  if (prepared === undefined) {
+    return Atom.toStreamResult(self.ref).pipe(Stream.flatMap((ref) => ref.emissions))
+  }
+  return Stream.unwrap(
+    Effect.gen(function*() {
+      const registry = yield* AtomRegistry.AtomRegistry
+      const releasePrepared = yield* Effect.sync(() => registry.mount(prepared))
+      yield* Effect.addFinalizer(() => Effect.sync(releasePrepared))
+      const machine = yield* Atom.getResult(prepared)
+      const pull = yield* Stream.toPull(machine.emissions as Stream.Stream<Emitted>)
+      const firstPull = yield* pull.pipe(Effect.forkScoped({ startImmediately: true }))
+      const releaseRef = yield* Effect.sync(() => registry.mount(self.ref))
+      yield* Effect.addFinalizer(() => Effect.sync(releaseRef))
+      yield* Atom.getResult(self.ref)
+      let first = true
+      return Stream.fromPull(Effect.succeed(Effect.suspend(() => {
+        if (!first) return pull
+        first = false
+        return Fiber.join(firstPull)
+      })))
+    })
+  )
+}
+
+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>>
@@ -588,7 +601,8 @@ type ResumedMachineAtomOf<M extends Machine.Machine.Any, RuntimeError> = Machine
   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 +619,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 +636,8 @@ export const make: {
         Output,
         Emits,
         OutputStates,
-        InputEvents
+        InputEvents,
+        ParentEvents
       >
       & EnsureNoExternalRequirements<
         MachineRequirements<
@@ -638,11 +654,15 @@ export const make: {
     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 []))
-  return makeFromRefAtom(ref as any)
+  const prepared = Atom.make(() => internalMachine.prepare(machine as any, ...(args as [])))
+  const ref = Atom.make((get) => startPreparedMachineAtomEffect(get, prepared as any))
+  const result = makeFromRefAtom(ref as any)
+  preparedByMachineAtom.set(result, prepared as any)
+  return result
 }) as any
 
 export const resume: {
@@ -663,8 +683,11 @@ const makeWithRuntime = (
   machine: Machine.Machine.Any,
   args: ReadonlyArray<unknown>
 ): MachineAtom<any, any, any, any, any> => {
-  const ref = runtime.atom((get) => startMachineAtomEffect(get, machine as any, args as []))
-  return makeFromRefAtom(ref as any)
+  const prepared = runtime.atom(() => internalMachine.prepare(machine as any, ...(args as [])))
+  const ref = runtime.atom((get) => startPreparedMachineAtomEffect(get, prepared as any))
+  const result = makeFromRefAtom(ref as any)
+  preparedByMachineAtom.set(result, prepared as any)
+  return result
 }
 
 const resumeWithRuntime = (

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,12 @@ 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,
@@ -43,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
@@ -64,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",
@@ -336,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)
@@ -399,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))
     },
@@ -407,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
@@ -425,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) {
@@ -446,7 +475,8 @@ const selectIndexedEventTransitions = (
             descriptor,
             configuration,
             sourceIndex,
-            event
+            event,
+            actorScope
           )
         })
       }
@@ -629,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
@@ -681,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)
@@ -774,7 +806,8 @@ 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
@@ -783,7 +816,9 @@ const planIndexedState = (
     // the representation boundary.
     const planned = planConfiguration(
       machine as any,
-      activeConfigurationFromIndexedState(descriptor, configuration),
+      actorScope === undefined
+        ? activeConfigurationFromIndexedState(descriptor, configuration)
+        : withActorScope(activeConfigurationFromIndexedState(descriptor, configuration), actorScope),
       input
     )
     return {
@@ -806,7 +841,7 @@ const planIndexedState = (
   }
   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)
@@ -827,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,
@@ -895,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
@@ -913,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
@@ -933,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 = (
@@ -943,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)

package/src/internal/machine/invocation.ts

@@ -235,9 +235,10 @@ export const startAll = (
     .filter((path) => configuration.active.has(path))
     .flatMap((path) => {
       const context = {
+        ...(Configuration.getActorScope(configuration) ?? { self: scope.self, parent: scope.parent }),
         state: configuration.values.get(path),
-        parent: Configuration.getParentValue(machine, configuration, path),
-        parents: Configuration.getParentValues(machine, configuration, path),
+        containingState: Configuration.getParentValue(machine, configuration, path),
+        ancestors: Configuration.getParentValues(machine, configuration, path),
         event
       }
       return InvocationEvent.definitions(Configuration.getStateConfigByPath(machine, path)?.invoke).map((definition) =>