@typeonce/effect-machine 0.11.0 → 0.13.0

package/src/internal/machine/atom.ts

@@ -139,6 +139,32 @@ export const emissions = <State, Event, Error, Output, StartError, Emitted>(
   )
 }
 
+export const inspection = <State, Event, Error, Output, StartError, Emitted>(
+  self: MachineAtom<State, Event, Error, Output, StartError, Emitted>
+): Stream.Stream<Machine.Inspection.Event, StartError, AtomRegistry.AtomRegistry> => {
+  const prepared = preparedByMachineAtom.get(self as object)
+  if (prepared === undefined) return Stream.empty
+  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.inspection)
+      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> =>

package/src/internal/machine/cluster.ts

@@ -317,7 +317,7 @@ export const make = <
             if (initial.commands.length > 0) {
               return yield* fail(
                 "UnsupportedProcessLocal",
-                "Machine actor commands require a managed local process"
+                "Machine commands require a managed local process"
               )
             }
             current = initial.state
@@ -329,7 +329,7 @@ export const make = <
             if (planned.commands.length > 0) {
               return yield* fail(
                 "UnsupportedProcessLocal",
-                "Machine actor commands require a managed local process"
+                "Machine commands require a managed local process"
               )
             }
             current = planned.next

package/src/internal/machine/commandRuntime.ts

@@ -10,16 +10,13 @@ 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>
 ): Runtime<Events, Emits> => ({
   raise: (event) =>
     decodeEvent(machine, event).pipe(
-      Effect.flatMap((event) => scope.self.send(event as Events))
+      Effect.flatMap((event) => scope.sendTo(scope.self, event as Events))
     ),
   emit: (event) =>
     decodeEmit(machine, event).pipe(
@@ -33,9 +30,7 @@ export const runCommands = <Event>(
 ) =>
   Effect.forEach(commands, (command) =>
     command._tag === "SendTo"
-      ? isActorRef(command.target)
-        ? command.target.send(command.event)
-        : scope.sendTo(command.target as never, command.event)
+      ? scope.sendTo(command.target as never, command.event)
       : scope.stopChild(command.child as never), { discard: true })
 
 export const runEmittedEvents = <Events, Emits>(

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 { ActorRef, Machine } from "../../Machine.js"
+import type { Machine, MachineTarget } from "../../Machine.js"
 import { MachineSchemaDecodeError } from "./errors.js"
 import {
   decodeBoundary,
@@ -17,7 +17,14 @@ import {
   decodeStateValue,
   decodeStateValueSync
 } from "./protocol.js"
-import { getNode, getStateNodeSchema, isSnapshot, isTarget, TargetSnapshotTypeId } from "./topology.js"
+import {
+  getNode,
+  getStateNodeSchema,
+  type InitialTarget as InitialTargetInstruction,
+  isSnapshot,
+  isTarget,
+  TargetSnapshotTypeId
+} from "./topology.js"
 
 export interface HistoryRecord {
   readonly mode: "shallow" | "deep"
@@ -252,25 +259,25 @@ export interface ActiveConfiguration {
   readonly values: ReadonlyMap<string, unknown>
   readonly outputs: ReadonlyMap<string, unknown>
   readonly history: ReadonlyMap<string, HistoryRecord>
-  readonly actorScope?: PlanningActorScope
+  readonly machineReferences?: PlanningMachineReferences
 }
 
-export interface PlanningActorScope {
-  readonly self: ActorRef<any>
-  readonly parent: ActorRef<any> | undefined
+export interface PlanningMachineReferences {
+  readonly self: MachineTarget<any>
+  readonly parent: MachineTarget<any> | undefined
 }
 
-export const withActorScope = (
+export const withMachineReferences = (
   configuration: ActiveConfiguration,
-  actorScope: PlanningActorScope
+  machineReferences: PlanningMachineReferences
 ): ActiveConfiguration => ({
   ...configuration,
-  actorScope: { self: actorScope.self, parent: actorScope.parent }
+  machineReferences: { self: machineReferences.self, parent: machineReferences.parent }
 })
 
-export const getActorScope = (
+export const getMachineReferences = (
   configuration: ActiveConfiguration
-): PlanningActorScope | undefined => configuration.actorScope
+): PlanningMachineReferences | undefined => configuration.machineReferences
 
 export interface FinalCompletion {
   readonly path: string
@@ -952,7 +959,8 @@ const configurationFromTargetPathSync = (
   current: ActiveConfiguration,
   path: string,
   value: unknown,
-  providedValues: Readonly<Record<string, unknown>> | undefined
+  providedValues: Readonly<Record<string, unknown>> | undefined,
+  allowIncomplete = false
 ): ActiveConfiguration => {
   const node = getNode(machine, path)
   const active = new Set<string>()
@@ -998,12 +1006,29 @@ const configurationFromTargetPathSync = (
     }
   }
 
-  if (node.type === "compound" || node.type === "parallel") {
+  if (!allowIncomplete && (node.type === "compound" || node.type === "parallel")) {
     throw new Error(`Machine target "${node.path}" must include an active child state`)
   }
   return { active, values, outputs, history: current.history }
 }
 
+/** Builds the selected path and its ancestors without requiring nested active
+ * children. The planner completes those children through declared initial
+ * topology and `initialize` handlers before normalization continues. */
+export const configurationFromInitialTargetSync = (
+  machine: Machine.Any,
+  current: ActiveConfiguration,
+  target: InitialTargetInstruction
+): ActiveConfiguration =>
+  configurationFromTargetPathSync(
+    machine,
+    current,
+    target.path,
+    target.value,
+    target.values as Readonly<Record<string, unknown>> | undefined,
+    true
+  )
+
 const configurationFromTargetSnapshotSync = (
   machine: Machine.Any,
   current: ActiveConfiguration,

package/src/internal/machine/executionPlan.ts

@@ -5,7 +5,7 @@
  */
 
 import * as Effect from "effect/Effect"
-import type { ActorRef, Machine } from "../../Machine.js"
+import type { Machine, MachineTarget } from "../../Machine.js"
 import { getTargetBuilder, type RuntimeCommand } from "./command.js"
 import {
   type ActiveConfiguration,
@@ -18,10 +18,10 @@ import {
   isDescendantOf,
   normalizeConfigurationSync,
   normalizeTargetConfigurationSync,
-  type PlanningActorScope,
+  type PlanningMachineReferences,
   snapshotFromConfiguration,
   validateInitialConfiguration,
-  withActorScope
+  withMachineReferences
 } from "./configuration.js"
 import { InfiniteTransitionError, StoppedError } from "./errors.js"
 import * as InvocationEvent from "./invocationEvent.js"
@@ -38,6 +38,7 @@ import {
   normalizeTransition,
   planConfiguration,
   removeConflictingTransitions,
+  resolveInitialTarget,
   type SelectedTransition,
   sortEntryPaths,
   sortEvaluatedTransitions,
@@ -46,7 +47,7 @@ import {
   validateDeclaredTransitionTarget
 } from "./planner.js"
 import { decodeEmitSync, decodeEventSync, decodeInputSync, decodeStateValueSync } from "./protocol.js"
-import { isNoTarget, isSnapshot, isTarget, TargetSnapshotTypeId } from "./topology.js"
+import { isInitialTarget, isNoTarget, isSnapshot, isTarget, TargetSnapshotTypeId } from "./topology.js"
 
 interface IndexedExecutionDescriptor {
   readonly flat: boolean
@@ -67,31 +68,31 @@ interface IndexedExecutionDescriptor {
   >
 }
 
-const planningActorScopes = new WeakMap<Machine.Any, PlanningActorScope>()
+const planningMachineReferences = new WeakMap<Machine.Any, PlanningMachineReferences>()
 
-const getPlanningActorScope = (machine: Machine.Any): PlanningActorScope => {
-  const cached = planningActorScopes.get(machine)
+const getPlanningMachineReferences = (machine: Machine.Any): PlanningMachineReferences => {
+  const cached = planningMachineReferences.get(machine)
   if (cached !== undefined) return cached
-  const self: ActorRef<unknown> = {
+  const self: MachineTarget<unknown> = {
     id: machine.id ?? "Machine",
     sessionId: "Machine.plan",
     send: () => Effect.fail(new StoppedError())
   }
   const scope = { self, parent: undefined }
-  planningActorScopes.set(machine, scope)
+  planningMachineReferences.set(machine, scope)
   return scope
 }
 
-const getActorContext = (
+const resolveMachineReferences = (
   machine: Machine.Any,
-  actorScope: PlanningActorScope | undefined
-): PlanningActorScope =>
-  actorScope === undefined
-    ? getPlanningActorScope(machine)
-    : { self: actorScope.self, parent: actorScope.parent }
+  machineReferences: PlanningMachineReferences | undefined
+): PlanningMachineReferences =>
+  machineReferences === undefined
+    ? getPlanningMachineReferences(machine)
+    : { self: machineReferences.self, parent: machineReferences.parent }
 
 const indexedStateConfigKeys: ReadonlySet<PropertyKey> = new Set([
-  "initial",
+  "initialize",
   "invoke",
   "on",
   "output"
@@ -363,7 +364,7 @@ const makeIndexedTransitionContext = (
   configuration: OwnedIndexedState,
   sourceIndex: number,
   event: any,
-  actorScope?: PlanningActorScope
+  machineReferences?: PlanningMachineReferences
 ): any => {
   const source = descriptor.nodes[sourceIndex]!
   const parentIndex = descriptor.parentIndices[sourceIndex]!
@@ -372,7 +373,7 @@ const makeIndexedTransitionContext = (
     ancestors[descriptor.nodes[ancestorIndex]!.path] = configuration.values[ancestorIndex]
   }
   return {
-    ...getActorContext(machine, actorScope),
+    ...resolveMachineReferences(machine, machineReferences),
     state: configuration.values[sourceIndex],
     containingState: parentIndex < 0 ? undefined : configuration.values[parentIndex],
     ancestors,
@@ -402,6 +403,7 @@ const emptyExecutionValues: ReadonlyArray<never> = Object.freeze([])
 export interface ExecutionMicrostep<State = unknown> {
   readonly next: State
   readonly event: unknown
+  readonly transitions?: ReadonlyArray<Machine.RetainedTransition>
   readonly commands: ReadonlyArray<RuntimeCommand>
   readonly raisedEvents: ReadonlyArray<unknown>
   readonly emittedEvents: ReadonlyArray<unknown>
@@ -454,7 +456,7 @@ const selectIndexedEventTransitions = (
   descriptor: IndexedExecutionDescriptor,
   configuration: OwnedIndexedState,
   event: any,
-  actorScope?: PlanningActorScope
+  machineReferences?: PlanningMachineReferences
 ): ReadonlyArray<IndexedSelectedTransition> => {
   const selected: Array<IndexedSelectedTransition> = []
   for (const leafIndex of configuration.activeLeaves) {
@@ -476,7 +478,7 @@ const selectIndexedEventTransitions = (
             configuration,
             sourceIndex,
             event,
-            actorScope
+            machineReferences
           )
         })
       }
@@ -530,13 +532,22 @@ const collectIndexedEvaluatedTransition = (
   selection: IndexedSelectedTransition
 ): IndexedEvaluatedTransition => {
   const transitionResult = collectIndexedTransition(machine, selection.transition.transition, selection.context)
-  const target = transitionResult.state
+  const unresolvedTarget = transitionResult.state
   validateDeclaredTransitionTarget(
     selection.sourcePath,
     selection.trigger,
     selection.transition.targets,
-    target
+    unresolvedTarget
   )
+  const initialResolution = unresolvedTarget !== undefined && isInitialTarget(unresolvedTarget)
+    ? resolveInitialTarget(
+      machine,
+      activeConfigurationFromIndexedState(descriptor, state),
+      unresolvedTarget,
+      (selection.context as any).event
+    )
+    : undefined
+  const target = initialResolution?.target ?? unresolvedTarget
   if (target !== undefined && !isTarget(target) && !isSnapshot(target)) {
     throw new Error("Machine expected indexed transition target to be a snapshot or target builder result")
   }
@@ -547,16 +558,16 @@ const collectIndexedEvaluatedTransition = (
   if (!changed) {
     return {
       selection,
-      unresolvedTarget: target as any,
+      unresolvedTarget: unresolvedTarget as any,
       target: target as any,
       next,
-      commands: transitionResult.commands,
-      raisedEvents: transitionResult.raisedEvents,
-      emittedEvents: transitionResult.emittedEvents,
+      commands: [...transitionResult.commands, ...(initialResolution?.commands ?? [])],
+      raisedEvents: [...transitionResult.raisedEvents, ...(initialResolution?.raisedEvents ?? [])],
+      emittedEvents: [...transitionResult.emittedEvents, ...(initialResolution?.emittedEvents ?? [])],
       changed: false,
       exitPaths: [],
       entryPaths: [],
-      choiceTransitions: []
+      choiceTransitions: initialResolution?.transitions ?? []
     }
   }
 
@@ -570,16 +581,16 @@ const collectIndexedEvaluatedTransition = (
     : naturalBoundary
   return {
     selection,
-    unresolvedTarget: target as any,
+    unresolvedTarget: unresolvedTarget as any,
     target: target as any,
     next,
-    commands: transitionResult.commands,
-    raisedEvents: transitionResult.raisedEvents,
-    emittedEvents: transitionResult.emittedEvents,
+    commands: [...transitionResult.commands, ...(initialResolution?.commands ?? [])],
+    raisedEvents: [...transitionResult.raisedEvents, ...(initialResolution?.raisedEvents ?? [])],
+    emittedEvents: [...transitionResult.emittedEvents, ...(initialResolution?.emittedEvents ?? [])],
     changed: true,
     exitPaths: getExitPaths(machine, activeConfigurationFromIndexedState(descriptor, state), boundary),
     entryPaths: getEntryPaths(machine, activeConfigurationFromIndexedState(descriptor, next), boundary),
-    choiceTransitions: []
+    choiceTransitions: initialResolution?.transitions ?? []
   }
 }
 
@@ -588,13 +599,22 @@ const indexedMicrostep = (
   descriptor: IndexedExecutionDescriptor,
   state: OwnedIndexedState,
   event: any,
-  selections: ReadonlyArray<IndexedSelectedTransition>
+  selections: ReadonlyArray<IndexedSelectedTransition>,
+  retainTransitions: boolean
 ): ExecutionMicrostep<OwnedIndexedState> => {
+  const retain = (transition: IndexedEvaluatedTransition): Machine.RetainedTransition => ({
+    source: transition.selection.sourcePath,
+    trigger: transition.selection.trigger,
+    reenter: transition.selection.transition.reenter,
+    target: transition.unresolvedTarget === undefined ? undefined : getTargetNodePath(transition.unresolvedTarget),
+    resolvedTarget: transition.target === undefined ? undefined : getTargetNodePath(transition.target)
+  })
   if (selections.length === 1) {
     const transition = collectIndexedEvaluatedTransition(machine, descriptor, state, selections[0]!)
     return {
       next: transition.next,
       event,
+      ...(retainTransitions ? { transitions: [retain(transition)] } : undefined),
       commands: transition.commands,
       raisedEvents: transition.raisedEvents,
       emittedEvents: transition.emittedEvents,
@@ -645,6 +665,7 @@ const indexedMicrostep = (
   return {
     next,
     event,
+    ...(retainTransitions ? { transitions: transitions.map(retain) } : undefined),
     commands,
     raisedEvents,
     emittedEvents,
@@ -660,7 +681,7 @@ const planIndexedFlatState = (
   configuration: OwnedIndexedState,
   decoded: { readonly _tag: PropertyKey },
   retainMicrosteps: boolean,
-  actorScope?: PlanningActorScope
+  machineReferences?: PlanningMachineReferences
 ): ExecutionMacrostep<OwnedIndexedState> => {
   let current = configuration
   let event: any = decoded
@@ -712,7 +733,7 @@ const planIndexedFlatState = (
         machine,
         transition.transition,
         {
-          ...getActorContext(machine, actorScope),
+          ...resolveMachineReferences(machine, machineReferences),
           state: current.values[sourceIndex],
           containingState: undefined,
           ancestors: {},
@@ -762,6 +783,17 @@ const planIndexedFlatState = (
       const step: ExecutionMicrostep<OwnedIndexedState> = {
         next,
         event,
+        ...(retainMicrosteps
+          ? {
+            transitions: [{
+              source: sourcePath,
+              trigger: { type: "event", event: event._tag },
+              reenter: transition.reenter,
+              target: target === undefined ? undefined : getTargetNodePath(target as any),
+              resolvedTarget: target === undefined ? undefined : getTargetNodePath(target as any)
+            }]
+          }
+          : undefined),
         commands: transitionResult.commands,
         raisedEvents: transitionResult.raisedEvents,
         emittedEvents: transitionResult.emittedEvents,
@@ -807,7 +839,7 @@ const planIndexedState = (
   configuration: OwnedIndexedState,
   input: unknown,
   retainMicrosteps: boolean,
-  actorScope?: PlanningActorScope
+  machineReferences?: PlanningMachineReferences
 ): ExecutionMacrostep<OwnedIndexedState> => {
   if (InvocationEvent.isInvocationEvent(input)) {
     // Invocation lifecycle transitions retain the generic planner as their
@@ -816,9 +848,9 @@ const planIndexedState = (
     // the representation boundary.
     const planned = planConfiguration(
       machine as any,
-      actorScope === undefined
+      machineReferences === undefined
         ? activeConfigurationFromIndexedState(descriptor, configuration)
-        : withActorScope(activeConfigurationFromIndexedState(descriptor, configuration), actorScope),
+        : withMachineReferences(activeConfigurationFromIndexedState(descriptor, configuration), machineReferences),
       input
     )
     return {
@@ -828,6 +860,7 @@ const planIndexedState = (
       microsteps: planned.microsteps.map((step) => ({
         next: ownedIndexedStateFromActive(descriptor, step.next),
         event: step.event,
+        transitions: step.transitions,
         commands: step.commands,
         raisedEvents: step.raisedEvents,
         emittedEvents: step.emittedEvents,
@@ -841,7 +874,7 @@ const planIndexedState = (
   }
   const decoded = decodeEventSync(machine, input)
   if (descriptor.flat) {
-    return planIndexedFlatState(machine, descriptor, configuration, decoded, retainMicrosteps, actorScope)
+    return planIndexedFlatState(machine, descriptor, configuration, decoded, retainMicrosteps, machineReferences)
   }
   if (descriptor.finalIndices.some((index) => configuration.active[index] === 1)) {
     const active = activeConfigurationFromIndexedState(descriptor, configuration)
@@ -862,7 +895,7 @@ const planIndexedState = (
     }
   }
 
-  const selections = selectIndexedEventTransitions(machine, descriptor, configuration, decoded, actorScope)
+  const selections = selectIndexedEventTransitions(machine, descriptor, configuration, decoded, machineReferences)
   if (selections.length === 0) {
     return {
       next: configuration,
@@ -874,7 +907,7 @@ const planIndexedState = (
     }
   }
 
-  const first = indexedMicrostep(machine, descriptor, configuration, decoded, selections)
+  const first = indexedMicrostep(machine, descriptor, configuration, decoded, selections, retainMicrosteps)
   let current = first.next
   let currentEvent: any = decoded
   const commands = [...first.commands]
@@ -930,9 +963,9 @@ const planIndexedState = (
     }
     raisedIndex += 1
     currentEvent = raised
-    const raisedSelections = selectIndexedEventTransitions(machine, descriptor, current, raised, actorScope)
+    const raisedSelections = selectIndexedEventTransitions(machine, descriptor, current, raised, machineReferences)
     if (raisedSelections.length === 0) continue
-    const step = indexedMicrostep(machine, descriptor, current, raised, raisedSelections)
+    const step = indexedMicrostep(machine, descriptor, current, raised, raisedSelections, retainMicrosteps)
     current = step.next
     commands.push(...step.commands)
     raisedEvents.push(...step.raisedEvents)
@@ -949,11 +982,11 @@ export interface CompiledExecutionPlan {
     state: unknown,
     event: unknown,
     retainMicrosteps?: boolean,
-    actorScope?: PlanningActorScope
+    machineReferences?: PlanningMachineReferences
   ) => ExecutionMacrostep
   readonly initial?: (
     args: ReadonlyArray<unknown>,
-    actorScope?: PlanningActorScope
+    machineReferences?: PlanningMachineReferences
   ) => {
     readonly state: Machine.Snapshot<any>
     readonly configuration: unknown
@@ -970,12 +1003,12 @@ const makeActiveExecutionPlan = (machine: Machine.Any): CompiledExecutionPlan =>
   fromConfiguration: (configuration) => configuration,
   toConfiguration: (state) => state as ActiveConfiguration,
   snapshot: (state) => snapshotFromConfiguration(machine, state as ActiveConfiguration),
-  plan: (state, event, _retainMicrosteps, actorScope) =>
+  plan: (state, event, _retainMicrosteps, machineReferences) =>
     planConfiguration(
       machine as any,
-      actorScope === undefined
+      machineReferences === undefined
         ? state as ActiveConfiguration
-        : withActorScope(state as ActiveConfiguration, actorScope),
+        : withMachineReferences(state as ActiveConfiguration, machineReferences),
       event as any
     )
 })
@@ -987,9 +1020,9 @@ 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, actorScope) =>
-    planIndexedState(machine, indexed, state as OwnedIndexedState, event, retainMicrosteps, actorScope),
-  initial: (args, actorScope) => {
+  plan: (state, event, retainMicrosteps = false, machineReferences) =>
+    planIndexedState(machine, indexed, state as OwnedIndexedState, event, retainMicrosteps, machineReferences),
+  initial: (args, machineReferences) => {
     const inputArgs = machine.input === undefined
       ? args
       : args.length === 0
@@ -997,7 +1030,7 @@ const makeIndexedExecutionPlan = (
       : [decodeInputSync(machine, machine.input, args[0])]
     const initial = machine.initial(...inputArgs as any)
     const normalized = normalizeConfigurationSync(machine, initial as Machine.Snapshot<any>)
-    const active = actorScope === undefined ? normalized : withActorScope(normalized, actorScope)
+    const active = machineReferences === undefined ? normalized : withMachineReferences(normalized, machineReferences)
     validateInitialConfiguration(machine, active)
     const completed = completeConfigurationSync(machine, active, InitialEvent).configuration
     const configuration = ownedIndexedStateFromActive(indexed, completed)

package/src/internal/machine/initialization.ts

@@ -0,0 +1,73 @@
+/** Internal builders for schema-valued default state entry. */
+
+import { hasProperty } from "effect/Predicate"
+import type { Machine } from "../../Machine.js"
+import { SnapshotBuilderStateTypeId } from "./symbols.js"
+import * as Topology from "./topology.js"
+
+const getNode = (machine: Machine.Any, path: string): Machine.StateNode => {
+  const node = machine.stateNodes.byPath.get(path)
+  if (node === undefined) {
+    throw new Error(`Machine expected state path "${path}" to exist`)
+  }
+  return node
+}
+
+const withFrom = <Method extends (value: unknown) => unknown>(method: Method) => {
+  Object.defineProperty(method, "from", {
+    value: (...args: ReadonlyArray<unknown>) => method(Topology.makeStateInput(args.length === 0 ? {} : args[0])),
+    enumerable: false
+  })
+  return method as Method & { readonly from: (...args: ReadonlyArray<unknown>) => unknown }
+}
+
+const makeCompletion = (values: Readonly<Record<string, unknown>>): object => {
+  const completion = {}
+  Object.defineProperty(completion, SnapshotBuilderStateTypeId, {
+    value: values,
+    enumerable: false
+  })
+  return completion
+}
+
+const makeParallelBuilder = (
+  machine: Machine.Any,
+  node: Machine.StateNode,
+  values: Readonly<Record<string, unknown>>
+): object => {
+  const builder = makeCompletion(values) as Record<string | symbol, unknown>
+  for (const childPath of node.children) {
+    const child = getNode(machine, childPath)
+    if (child.schema === undefined || hasProperty(values, child.key)) continue
+    builder[child.key] = withFrom((value: unknown) => {
+      const nextValues: Record<string, unknown> = Object.assign({}, values)
+      nextValues[child.key] = value
+      return makeParallelBuilder(machine, node, nextValues)
+    })
+  }
+  return builder
+}
+
+export const makeStateInitializeBuilder = (machine: Machine.Any, path: string): object => {
+  const node = getNode(machine, path)
+  if (node.type === "parallel") {
+    return makeParallelBuilder(machine, node, {})
+  }
+  if (node.type !== "compound") {
+    throw new Error(`Machine state "${path}" cannot initialize child states`)
+  }
+  const child = getNode(machine, node.initial)
+  if (child.schema === undefined) {
+    throw new Error(`Machine state "${path}" has no schema-valued initial child`)
+  }
+  return withFrom((value: unknown) => makeCompletion({ [child.key]: value }))
+}
+
+export const getStateInitializeValues = (path: string, result: unknown): Readonly<Record<string, unknown>> => {
+  if (typeof result !== "object" || result === null || !hasProperty(result, SnapshotBuilderStateTypeId)) {
+    throw new Error(`Machine initialize handler for "${path}" must return its builder result`)
+  }
+  return (result as { readonly [SnapshotBuilderStateTypeId]: Readonly<Record<string, unknown>> })[
+    SnapshotBuilderStateTypeId
+  ]
+}