@typeonce/effect-machine 0.15.0 → 0.17.0

package/src/internal/machine/machine.ts

@@ -19,6 +19,8 @@ import type {
   MachineRef,
   MachineSchemaDecodeError,
   MachineSchemaEncodeError,
+  Parent,
+  ParentMode,
   Runtime,
   RuntimeOutcome,
   SpawnOptions,
@@ -49,6 +51,7 @@ export {
 export { ChildMachineLogicTypeId, InitialEventTypeId, SnapshotBuilderStateTypeId } from "./symbols.js"
 
 const TypeId = "~effect/Machine"
+const ParentTypeId = "~effect/Machine/Parent"
 export const InvokeTypeId: unique symbol = Symbol.for("effect/Machine/Invoke")
 export const TransitionTypeId: unique symbol = Symbol.for("effect/Machine/Transition")
 const ChildMachineTypeId = "~effect/Machine/ChildMachine"
@@ -112,8 +115,6 @@ const Proto = {
   }
 }
 
-const makeBoundInvoke = (config: unknown): unknown => config
-
 const makeWithHandlers = (
   self: Definition.Any,
   handlers: Machine.StateConfigs<any, any, any, any, any, any, any>
@@ -123,7 +124,7 @@ const makeWithHandlers = (
   machine.events = self.events
   machine.internalEvents = self.internalEvents
   machine.emittedEvents = self.emittedEvents
-  machine.parentEvents = self.parentEvents
+  machine.parent = self.parent
   machine.input = self.input
   machine.id = self.id
   machine.initial = self.initial
@@ -131,22 +132,214 @@ const makeWithHandlers = (
   machine.stateNodes = self.stateNodes
   machine.makeTargetBuilder = self.makeTargetBuilder
   machine.handlers = handlers
-  machine.invoke = makeBoundInvoke
   Protocol.copyProtocol(self, machine)
   return machine
 }
 
 type DefinitionBranch = {
-  readonly title?: string
-  readonly when?: (context: any) => Option.Option<unknown>
   readonly target: (selector: unknown) => unknown
   readonly resolve?: (context: any, enqueue: unknown) => unknown
+  readonly declinable?: boolean
 }
 
 type CapturedBranch = DefinitionBranch & {
   readonly selection: Topology.TargetSelection
 }
 
+type BranchDeclaration = {
+  readonly title?: string
+  readonly target: unknown
+}
+
+type CapturedNamedBranch = {
+  readonly key: string
+  readonly title: string
+  readonly selection: Topology.TargetSelection
+}
+
+const TransitionBuilderDescriptorTypeId: unique symbol = Symbol("effect/Machine/TransitionBuilderDescriptor")
+
+type DirectTransitionDescriptor = {
+  readonly [TransitionBuilderDescriptorTypeId]: typeof TransitionBuilderDescriptorTypeId
+  readonly type: "direct"
+  readonly selection: Topology.TargetSelection
+  readonly resolve?: (context: any, enqueue: unknown) => unknown
+  readonly reenter: boolean
+  readonly declinable: boolean
+}
+
+type BranchesTransitionDescriptor = {
+  readonly [TransitionBuilderDescriptorTypeId]: typeof TransitionBuilderDescriptorTypeId
+  readonly type: "branches"
+  readonly declarations: unknown
+  readonly resolve: (context: any, enqueue: unknown) => unknown
+  readonly reenter: boolean
+  readonly declinable: boolean
+}
+
+type TransitionBuilderDescriptor = DirectTransitionDescriptor | BranchesTransitionDescriptor
+
+const InitialBuilderDescriptorTypeId: unique symbol = Symbol("effect/Machine/InitialBuilderDescriptor")
+
+type InitialBuilderDescriptor = {
+  readonly [InitialBuilderDescriptorTypeId]: typeof InitialBuilderDescriptorTypeId
+  readonly selection: Topology.TargetSelection
+  readonly resolve: (context: any) => unknown
+}
+
+const plainTargetSelection = (selection: Topology.TargetSelection): Topology.TargetSelection =>
+  selection.kind === "none"
+    ? Topology.noneTargetSelection
+    : Topology.makeTargetSelection(selection.kind, selection.path, selection.scope)
+
+const transitionOptions = (options: unknown): { readonly reenter: boolean; readonly declinable: boolean } => {
+  const configuration = typeof options === "object" && options !== null
+    ? options as { readonly reenter?: unknown; readonly declinable?: unknown }
+    : {}
+  return {
+    reenter: configuration.reenter === true,
+    declinable: configuration.declinable === true
+  }
+}
+
+const makeDirectTransitionDescriptor = (
+  selection: Topology.TargetSelection,
+  resolve: ((context: any, enqueue: unknown) => unknown) | undefined,
+  options: unknown
+): DirectTransitionDescriptor => {
+  const shared: Omit<DirectTransitionDescriptor, "resolve"> = {
+    [TransitionBuilderDescriptorTypeId]: TransitionBuilderDescriptorTypeId,
+    type: "direct",
+    selection: plainTargetSelection(selection),
+    ...transitionOptions(options)
+  }
+  return resolve === undefined
+    ? Object.freeze(shared)
+    : Object.freeze({ ...shared, resolve })
+}
+
+const decorateTransitionSelection = (selection: Topology.TargetSelection): Topology.TargetSelection =>
+  Object.freeze({
+    ...selection,
+    resolve: (resolve: (context: any, enqueue: unknown) => unknown, options?: unknown) =>
+      makeDirectTransitionDescriptor(selection, resolve, options),
+    reenter: () => makeDirectTransitionDescriptor(selection, undefined, { reenter: true })
+  })
+
+const noneTransitionSelection = decorateTransitionSelection(Topology.noneTargetSelection)
+
+const makeInitialBuilderDescriptor = (
+  selection: Topology.TargetSelection,
+  resolve: (context: any) => unknown
+): InitialBuilderDescriptor =>
+  Object.freeze({
+    [InitialBuilderDescriptorTypeId]: InitialBuilderDescriptorTypeId,
+    selection: plainTargetSelection(selection),
+    resolve
+  })
+
+const decorateInitialSelection = (selection: Topology.TargetSelection): Topology.TargetSelection =>
+  Object.freeze({
+    ...selection,
+    resolve: (resolve: (context: any) => unknown) => makeInitialBuilderDescriptor(selection, resolve)
+  })
+
+const decorateInitialSelectorNode = (node: unknown): unknown => {
+  if (Topology.isTargetSelection(node)) return decorateInitialSelection(node)
+  if (typeof node === "function") {
+    const wrapped = ((...args: ReadonlyArray<unknown>) => decorateInitialSelection(node(...args))) as
+      & ((...args: ReadonlyArray<unknown>) => unknown)
+      & Record<string, unknown>
+    for (const key of Object.keys(node)) {
+      wrapped[key] = decorateInitialSelectorNode((node as unknown as Record<string, unknown>)[key])
+    }
+    return Object.freeze(wrapped)
+  }
+  if (typeof node === "object" && node !== null) {
+    const wrapped: Record<string, unknown> = {}
+    for (const key of Object.keys(node)) {
+      wrapped[key] = decorateInitialSelectorNode((node as Record<string, unknown>)[key])
+    }
+    return Object.freeze(wrapped)
+  }
+  return node
+}
+
+const decorateTransitionSelectorNode = (node: unknown): unknown => {
+  if (Topology.isTargetSelection(node)) {
+    return node === Topology.noneTargetSelection ? noneTransitionSelection : decorateTransitionSelection(node)
+  }
+  if (typeof node === "function") {
+    const wrapped = ((...args: ReadonlyArray<unknown>) => decorateTransitionSelection(node(...args))) as
+      & ((...args: ReadonlyArray<unknown>) => unknown)
+      & Record<string, unknown>
+    for (const key of Object.keys(node)) {
+      wrapped[key] = decorateTransitionSelectorNode((node as unknown as Record<string, unknown>)[key])
+    }
+    return Object.freeze(wrapped)
+  }
+  if (typeof node === "object" && node !== null) {
+    const wrapped: Record<string, unknown> = {}
+    for (const key of Object.keys(node)) {
+      wrapped[key] = decorateTransitionSelectorNode((node as Record<string, unknown>)[key])
+    }
+    return Object.freeze(wrapped)
+  }
+  return node
+}
+
+const makeTransitionSelector = (
+  stateNodes: Machine.StateNodes,
+  source: string
+): unknown => {
+  const selector = {
+    ...decorateTransitionSelectorNode(makeTargetSelector(stateNodes, source)) as Record<string, unknown>
+  }
+  selector.branches = (declarations: unknown) =>
+    Object.freeze({
+      resolve: (
+        resolve: (context: any, enqueue: unknown) => unknown,
+        options?: unknown
+      ): BranchesTransitionDescriptor =>
+        Object.freeze({
+          [TransitionBuilderDescriptorTypeId]: TransitionBuilderDescriptorTypeId,
+          type: "branches",
+          declarations,
+          resolve,
+          ...transitionOptions(options)
+        })
+    })
+  return Object.freeze(selector)
+}
+
+const normalizeTransitionBuilder = (
+  transition: (selector: unknown) => unknown,
+  stateNodes: Machine.StateNodes,
+  path: string
+): unknown => {
+  const result = transition(makeTransitionSelector(stateNodes, path))
+  if (Topology.isTargetSelection(result)) {
+    const selection = plainTargetSelection(result)
+    return { target: () => selection }
+  }
+  if (!hasProperty(result, TransitionBuilderDescriptorTypeId)) return result
+  const descriptor = result as TransitionBuilderDescriptor
+  if (descriptor.type === "branches") {
+    return {
+      branches: () => descriptor.declarations,
+      resolve: descriptor.resolve,
+      reenter: descriptor.reenter,
+      declinable: descriptor.declinable
+    }
+  }
+  return {
+    target: () => descriptor.selection,
+    resolve: descriptor.resolve,
+    reenter: descriptor.reenter,
+    declinable: descriptor.declinable
+  }
+}
+
 const transitionTargetSelection = (
   selection: Topology.TargetSelection
 ): Machine.TransitionTargetSelection =>
@@ -163,6 +356,12 @@ const makeSelectionMethod = (
 ): () => Topology.TargetSelection =>
 () => Topology.makeTargetSelection(kind, path, scope)
 
+const makeSelectionValue = (
+  kind: Topology.TargetSelectionKind,
+  path: string | undefined,
+  scope: Topology.TargetSelectionScope
+): Topology.TargetSelection => Topology.makeTargetSelection(kind, path, scope)
+
 const addSelectionChildren = (
   builder: Record<string, unknown>,
   stateNodes: Machine.StateNodes,
@@ -185,7 +384,7 @@ const makeSelectionNode = (
   const method = makeSelectionMethod(kind, path, scope) as unknown as Record<string, unknown>
   if (node.type !== "atomic" && node.type !== "final" && node.type !== "choice" && node.type !== "history") {
     Object.defineProperty(method, "initial", {
-      value: makeSelectionMethod("initial", path, scope),
+      value: makeSelectionValue("initial", path, scope),
       enumerable: true
     })
     if (scope === "local" || scope === "branch") {
@@ -203,7 +402,7 @@ const makeHistorySelectionTree = (
   for (const node of stateNodes.byPath.values()) {
     if (node.parent !== parent) continue
     if (node.type === "history") {
-      builder[node.key] = makeSelectionMethod("history", node.path, "full")
+      builder[node.key] = makeSelectionValue("history", node.path, "full")
     } else if (node.type !== "choice") {
       const children = makeHistorySelectionTree(stateNodes, node.path)
       if (Object.keys(children).length > 0) builder[node.key] = children
@@ -230,12 +429,12 @@ const makeTargetSelector = (
   if (localScope !== undefined) {
     const localScopeNode = getTargetBuilderNode(stateNodes, localScope)
     if (localScopeNode.schema !== undefined) {
-      local.with = makeSelectionMethod("state", localScope, "local")
+      local.with = makeSelectionValue("state", localScope, "local")
     }
     addSelectionChildren(local, stateNodes, localScope, "local")
   }
   return {
-    none: makeSelectionMethod("none", undefined, "local"),
+    none: Topology.noneTargetSelection,
     local,
     branch,
     full,
@@ -300,7 +499,8 @@ const getSelectionBuilder = (
   return builder
 }
 
-const constructSelectedTarget = (builder: any): unknown => typeof builder === "function" ? builder() : builder.from()
+const constructSelectedTarget = (builder: any): unknown =>
+  typeof builder?.from === "function" ? builder.from() : builder()
 
 const validateResolvedSelection = (
   result: unknown,
@@ -336,90 +536,219 @@ const runCapturedBranch = (
   context: Record<string, any>,
   enqueue: unknown,
   stateNodes: Machine.StateNodes,
-  source: string,
-  match?: { readonly value: unknown }
+  source: string
 ): unknown => {
   const selectedTarget = getSelectionBuilder(context.target, branch.selection, stateNodes, source)
   if (branch.resolve === undefined) return constructSelectedTarget(selectedTarget)
   const resolverContext = { ...context }
   if (branch.selection.kind === "none") delete resolverContext.target
   else resolverContext.target = selectedTarget
-  if (match !== undefined) resolverContext.match = match.value
+  if (branch.declinable === true) resolverContext.decline = Topology.makeDeclined
   const resolved = branch.resolve(resolverContext, enqueue)
+  if (Topology.isDeclined(resolved)) {
+    if (branch.declinable !== true) {
+      throw new Error(`Machine transition for state "${source}" returned decline without declaring declinable: true`)
+    }
+    return resolved
+  }
   validateResolvedSelection(resolved, branch.selection, stateNodes)
   return resolved === undefined ? constructSelectedTarget(selectedTarget) : resolved
 }
 
+const isArrayIndexKey = (key: string): boolean => {
+  const index = Number(key)
+  return Number.isInteger(index) && index >= 0 && index < 0xffff_ffff && String(index) === key
+}
+
+const captureNamedBranches = (
+  declarations: unknown,
+  path: string,
+  trigger: PropertyKey
+): ReadonlyArray<CapturedNamedBranch> => {
+  if (typeof declarations !== "object" || declarations === null || Array.isArray(declarations)) {
+    throw new Error(`Machine branching transition for state "${path}" on "${String(trigger)}" requires a branch record`)
+  }
+  if (Object.getOwnPropertySymbols(declarations).length > 0) {
+    throw new Error(`Machine branching transition for state "${path}" on "${String(trigger)}" cannot use symbol keys`)
+  }
+  const keys = Object.keys(declarations)
+  if (keys.length === 0) {
+    throw new Error(`Machine branching transition for state "${path}" on "${String(trigger)}" requires a branch`)
+  }
+  return Object.freeze(keys.map((key) => {
+    if (key.length === 0 || isArrayIndexKey(key)) {
+      throw new Error(
+        `Machine branching transition for state "${path}" on "${String(trigger)}" requires non-index string branch keys`
+      )
+    }
+    const declaration = (declarations as Record<string, unknown>)[key]
+    if (typeof declaration !== "object" || declaration === null || !hasProperty(declaration, "target")) {
+      throw new Error(`Machine transition branch "${key}" requires a target selection`)
+    }
+    const { target, title } = declaration as BranchDeclaration
+    if (!Topology.isTargetSelection(target)) {
+      throw new Error(`Machine transition branch "${key}" must select exactly one target`)
+    }
+    if (title !== undefined && (typeof title !== "string" || title.length === 0)) {
+      throw new Error(`Machine transition branch "${key}" title must be a non-empty string`)
+    }
+    return Object.freeze({ key, title: title ?? key, selection: plainTargetSelection(target) })
+  }))
+}
+
+const wrapSelectedBranchBuilder = (
+  builder: unknown,
+  owner: object,
+  branchIndex: number,
+  branchKey: string
+): unknown => {
+  if (typeof builder === "function") {
+    const wrapped = (...args: ReadonlyArray<unknown>) =>
+      Topology.makeSelectedBranch(owner, branchIndex, branchKey, builder(...args))
+    for (const property of Reflect.ownKeys(builder)) {
+      if (
+        property === "length" || property === "name" || property === "prototype" || property === "caller" ||
+        property === "arguments"
+      ) continue
+      const descriptor = Object.getOwnPropertyDescriptor(builder, property)
+      if (descriptor === undefined) continue
+      if ("value" in descriptor && typeof descriptor.value === "function") {
+        descriptor.value = wrapSelectedBranchBuilder(descriptor.value, owner, branchIndex, branchKey)
+      }
+      Object.defineProperty(wrapped, property, descriptor)
+    }
+    return wrapped
+  }
+  if (typeof builder === "object" && builder !== null) {
+    const wrapped: Record<PropertyKey, unknown> = {}
+    for (const property of Reflect.ownKeys(builder)) {
+      const descriptor = Object.getOwnPropertyDescriptor(builder, property)
+      if (descriptor === undefined) continue
+      if ("value" in descriptor && typeof descriptor.value === "function") {
+        descriptor.value = wrapSelectedBranchBuilder(descriptor.value, owner, branchIndex, branchKey)
+      }
+      Object.defineProperty(wrapped, property, descriptor)
+    }
+    return wrapped
+  }
+  throw new Error(`Machine could not construct transition branch "${branchKey}"`)
+}
+
+const makeBranchSelectors = (
+  context: Record<string, any>,
+  branches: ReadonlyArray<CapturedNamedBranch>,
+  owner: object,
+  stateNodes: Machine.StateNodes,
+  source: string
+): Readonly<Record<string, unknown>> => {
+  const select: Record<string, unknown> = Object.create(null)
+  for (let branchIndex = 0; branchIndex < branches.length; branchIndex++) {
+    const branch = branches[branchIndex]!
+    select[branch.key] = wrapSelectedBranchBuilder(
+      getSelectionBuilder(context.target, branch.selection, stateNodes, source),
+      owner,
+      branchIndex,
+      branch.key
+    )
+  }
+  return Object.freeze(select)
+}
+
+const validateSelectedBranchResult = (
+  result: unknown,
+  selection: Topology.TargetSelection,
+  stateNodes: Machine.StateNodes
+): void => {
+  if (selection.kind === "none") {
+    if (!Topology.isNoTarget(result)) {
+      throw new Error("Machine targetless branch must return its selected targetless builder")
+    }
+    return
+  }
+  if (result === undefined) {
+    throw new Error(`Machine transition branch selected "${selection.path}" without constructing its target`)
+  }
+  validateResolvedSelection(result, selection, stateNodes)
+}
+
 const captureTransition = (
-  transition: unknown,
+  rawTransition: unknown,
   stateNodes: Machine.StateNodes,
   path: string,
   trigger: PropertyKey
 ): unknown => {
+  if (typeof rawTransition !== "function") {
+    throw new Error(
+      `Machine transition for state "${path}" on "${String(trigger)}" must be a target-first callback`
+    )
+  }
+  const transition = normalizeTransitionBuilder(rawTransition as (selector: unknown) => unknown, stateNodes, path)
   if (typeof transition !== "object" || transition === null) {
     throw new Error(`Machine transition for state "${path}" on "${String(trigger)}" must be an object`)
   }
   const definition = transition as Record<PropertyKey, unknown>
   const selector = makeTargetSelector(stateNodes, path)
   const reenter = definition.reenter === true
-  if (Array.isArray(definition.cases)) {
-    const rawCases = definition.cases as ReadonlyArray<unknown>
-    if (definition.cases.length === 0 || !hasProperty(definition, "otherwise")) {
+  const declinable = definition.declinable === true
+  if (hasProperty(definition, "branches")) {
+    const branching = definition as { readonly branches: unknown; readonly resolve?: unknown }
+    if (typeof branching.branches !== "function" || typeof branching.resolve !== "function") {
       throw new Error(
-        `Machine conditional transition for state "${path}" on "${String(trigger)}" requires cases and otherwise`
+        `Machine branching transition for state "${path}" on "${String(trigger)}" requires branches and resolve`
       )
     }
-    const cases = rawCases.map((branch) => {
-      const captured = captureDefinitionBranch(branch, selector, path, trigger)
-      if (typeof captured.title !== "string" || captured.title.length === 0 || typeof captured.when !== "function") {
+    const resolve = branching.resolve
+    const branches = captureNamedBranches(branching.branches(selector), path, trigger)
+    const owner = Object.freeze({})
+    const evaluate = (context: Record<string, any>, enqueue: unknown) => {
+      const resolverContext = { ...context }
+      delete resolverContext.target
+      resolverContext.select = makeBranchSelectors(context, branches, owner, stateNodes, path)
+      if (declinable) resolverContext.decline = Topology.makeDeclined
+      const selected = resolve(resolverContext, enqueue)
+      if (Topology.isDeclined(selected)) {
+        if (!declinable) {
+          throw new Error(
+            `Machine branching transition for state "${path}" on "${
+              String(trigger)
+            }" returned decline without declaring declinable: true`
+          )
+        }
+        return { result: selected, branchIndex: -1, branchKey: undefined }
+      }
+      if (!Topology.isSelectedBranch(selected) || selected.owner !== owner) {
         throw new Error(
-          `Machine conditional transition case for state "${path}" on "${String(trigger)}" requires title and when`
+          `Machine branching transition for state "${path}" on "${String(trigger)}" must select one declared branch`
         )
       }
-      return captured
-    })
-    const otherwise = captureDefinitionBranch(definition.otherwise, selector, path, trigger)
-    const evaluate = (context: Record<string, any>, enqueue: unknown) => {
-      const predicateContext = { ...context }
-      delete predicateContext.target
-      for (let branchIndex = 0; branchIndex < cases.length; branchIndex++) {
-        const branch = cases[branchIndex]!
-        const result = branch.when!(predicateContext)
-        if (!Option.isOption(result)) {
-          throw new Error(`Machine conditional transition case "${branch.title}" must return Option`)
-        }
-        if (Option.isSome(result)) {
-          return {
-            result: runCapturedBranch(branch, context, enqueue, stateNodes, path, { value: result.value }),
-            branchIndex
-          }
-        }
+      const branch = branches[selected.branchIndex]
+      if (branch === undefined || selected.branchKey !== branch.key) {
+        throw new Error(`Machine branching transition returned invalid branch evidence`)
       }
+      validateSelectedBranchResult(selected.result, branch.selection, stateNodes)
       return {
-        result: runCapturedBranch(otherwise, context, enqueue, stateNodes, path),
-        branchIndex: cases.length
+        result: selected.result,
+        branchIndex: selected.branchIndex,
+        branchKey: selected.branchKey
       }
     }
     return {
       reenter,
+      declinable,
       targets: [
         ...new Set(
-          [...cases, otherwise].flatMap((branch) => branch.selection.path === undefined ? [] : [branch.selection.path])
+          branches.flatMap((branch) => branch.selection.path === undefined ? [] : [branch.selection.path])
         )
       ],
-      branches: [
-        ...cases.map((branch) => ({
-          type: "case" as const,
-          title: branch.title!,
+      branches: branches.map((branch) =>
+        Object.freeze({
+          type: "branch" as const,
+          key: branch.key,
+          title: branch.title,
           target: branch.selection.path,
           selection: transitionTargetSelection(branch.selection)
-        })),
-        {
-          type: "otherwise" as const,
-          target: otherwise.selection.path,
-          selection: transitionTargetSelection(otherwise.selection)
-        }
-      ],
+        })
+      ),
       evaluate,
       transition: (context: Record<string, any>, enqueue: unknown) => evaluate(context, enqueue).result
     }
@@ -427,10 +756,12 @@ const captureTransition = (
   const branch = captureDefinitionBranch(transition, selector, path, trigger)
   const evaluate = (context: Record<string, any>, enqueue: unknown) => ({
     result: runCapturedBranch(branch, context, enqueue, stateNodes, path),
-    branchIndex: 0
+    branchIndex: 0,
+    branchKey: undefined
   })
   return {
     reenter,
+    declinable,
     targets: branch.selection.path === undefined ? [] : [branch.selection.path],
     branches: [{
       type: "direct" as const,
@@ -465,7 +796,7 @@ const captureInvokeDefinition = (
   if (Array.isArray(invoke)) return invoke.map((item) => captureInvokeDefinition(item, stateNodes, path))
   if (typeof invoke !== "object" || invoke === null) return invoke
   const captured = { ...(invoke as Record<PropertyKey, unknown>) }
-  for (const key of ["onDone", "onFailure", "onSnapshot"] as const) {
+  for (const key of ["onElement", "onDone", "onFailure", "onSnapshot"] as const) {
     if (captured[key] !== undefined) {
       captured[key] = captureTransition(captured[key], stateNodes, path, key)
     }
@@ -1072,10 +1403,12 @@ const makeInitialSelector = (stateNodes: Machine.StateNodes): unknown => {
   const selector: Record<string, unknown> = {}
   for (const node of stateNodes.byPath.values()) {
     if (node.parent === undefined && node.type !== "history" && node.type !== "choice") {
-      selector[node.key] = makeSelectionNode(stateNodes, node.path, "initial")
+      selector[node.key] = node.type === "atomic" || node.type === "final"
+        ? makeSelectionMethod("state", node.path, "initial")
+        : Object.freeze({ initial: makeSelectionValue("initial", node.path, "initial") })
     }
   }
-  return selector
+  return Object.freeze(selector)
 }
 
 const getInitialSelectionBuilder = (
@@ -1094,15 +1427,37 @@ const getInitialSelectionBuilder = (
 }
 
 const captureInitialBranch = (
-  branch: unknown,
-  selector: unknown,
+  definition: unknown,
+  stateNodes: Machine.StateNodes,
   initialBuilder: Record<string, any>
-): CapturedBranch & { readonly builder: (...args: ReadonlyArray<any>) => unknown } => {
-  const captured = captureDefinitionBranch(branch, selector, "<machine>", "initial")
-  if (captured.selection.kind !== "state" && captured.selection.kind !== "initial") {
+): {
+  readonly selection: Topology.TargetSelection
+  readonly resolve?: (context: any) => unknown
+  readonly builder: (...args: ReadonlyArray<any>) => unknown
+} => {
+  if (typeof definition !== "function") {
+    throw new Error("Machine initial definition must be a target-first callback")
+  }
+  const result = definition(decorateInitialSelectorNode(makeInitialSelector(stateNodes)))
+  let selection: Topology.TargetSelection
+  let resolve: ((context: any) => unknown) | undefined
+  if (Topology.isTargetSelection(result)) {
+    selection = plainTargetSelection(result)
+  } else if (hasProperty(result, InitialBuilderDescriptorTypeId)) {
+    const descriptor = result as InitialBuilderDescriptor
+    selection = descriptor.selection
+    resolve = descriptor.resolve
+  } else {
+    throw new Error("Machine initial definition must select exactly one target")
+  }
+  if (selection.kind !== "state" && selection.kind !== "initial") {
     throw new Error("Machine initial target must select a top-level state or its declared initial entry")
   }
-  return { ...captured, builder: getInitialSelectionBuilder(initialBuilder, captured.selection) }
+  const captured = {
+    selection,
+    builder: getInitialSelectionBuilder(initialBuilder, selection)
+  }
+  return resolve === undefined ? Object.freeze(captured) : Object.freeze({ ...captured, resolve })
 }
 
 const validateInitialSelection = (result: unknown, selection: Topology.TargetSelection): void => {
@@ -1124,17 +1479,13 @@ const compileInitial = (
   readonly initial: (input?: unknown) => unknown
   readonly definition: Machine.InitialDefinition
 } => {
-  if (typeof definition !== "object" || definition === null) {
-    throw new Error("Machine initial definition must be an object")
-  }
-  const selector = makeInitialSelector(stateNodes)
   const initialBuilder = makeSnapshotBuilder(states, { mode: "initial", prefix: "" }) as Record<string, any>
-  const branch = captureInitialBranch(definition, selector, initialBuilder)
+  const branch = captureInitialBranch(definition, stateNodes, initialBuilder)
   return {
     initial: (input?: unknown) => {
       const result = branch.resolve === undefined
-        ? branch.builder()
-        : branch.resolve({ input, target: branch.builder }, undefined)
+        ? constructSelectedTarget(branch.builder)
+        : branch.resolve({ input, target: branch.builder })
       validateInitialSelection(result, branch.selection)
       return result
     },
@@ -1184,7 +1535,7 @@ type MakeConfig<
   InitialE,
   InitialR,
   InternalEvents extends ReadonlyArray<Machine.TaggedSchema>,
-  ParentEvents extends ReadonlyArray<Machine.TaggedSchema>
+  ParentDeclaration extends Parent.Any | undefined
 > = {
   readonly id?: string
   readonly states: States & DefineStateTreeInput<NoInfer<States>>
@@ -1198,7 +1549,7 @@ type MakeConfig<
       NoInfer<InternalEvents>
     >
   readonly emittedEvents?: Machine.EventProtocol<"emitted", Emits>
-  readonly parentEvents?: Machine.EventProtocol<"public", ParentEvents>
+  readonly parent?: ParentDeclaration
   readonly input?: Input
   readonly initial: unknown
 }
@@ -1211,7 +1562,7 @@ type MakeResult<
   InitialE,
   InitialR,
   InternalEvents extends ReadonlyArray<Machine.TaggedSchema>,
-  ParentEvents extends ReadonlyArray<Machine.TaggedSchema>
+  ParentDeclaration extends Parent.Any | undefined
 > = Definition<
   States,
   readonly [...InputEvents, ...InternalEvents],
@@ -1222,7 +1573,7 @@ type MakeResult<
   Machine.TerminalOutput<States>,
   Emits,
   InputEvents,
-  ParentEvents
+  Machine.ParentEventsOf<ParentDeclaration>
 >
 
 interface Make {
@@ -1234,11 +1585,11 @@ interface Make {
     InitialE = never,
     InitialR = never,
     const InternalEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly [],
-    const ParentEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly []
+    const ParentDeclaration extends Parent.Any | undefined = undefined
   >(
-    config: MakeConfig<States, InputEvents, Emits, Input, InitialE, InitialR, InternalEvents, ParentEvents>,
+    config: MakeConfig<States, InputEvents, Emits, Input, InitialE, InitialR, InternalEvents, ParentDeclaration>,
     ..._validation: ValidateDefinedStates<NoInfer<States>>
-  ): MakeResult<States, InputEvents, Emits, Input, InitialE, InitialR, InternalEvents, ParentEvents>
+  ): MakeResult<States, InputEvents, Emits, Input, InitialE, InitialR, InternalEvents, ParentDeclaration>
   <
     const States extends Machine.StateSchemas,
     const InputEvents extends ReadonlyArray<Machine.TaggedSchema>,
@@ -1247,10 +1598,13 @@ interface Make {
     InitialE = never,
     InitialR = never,
     const InternalEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly [],
-    const ParentEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly []
+    const ParentDeclaration extends Parent.Any | undefined = undefined
   >(
     config:
-      & Omit<MakeConfig<States, InputEvents, Emits, Input, InitialE, InitialR, InternalEvents, ParentEvents>, "states">
+      & Omit<
+        MakeConfig<States, InputEvents, Emits, Input, InitialE, InitialR, InternalEvents, ParentDeclaration>,
+        "states"
+      >
       & { readonly states: InvalidDefinedStateTreeInput<States> }
   ): never
 }
@@ -1263,7 +1617,7 @@ export const make: Make = (<
   InitialE = never,
   InitialR = never,
   const InternalEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly [],
-  const ParentEvents extends ReadonlyArray<Machine.TaggedSchema> = readonly []
+  const ParentDeclaration extends Parent.Any | undefined = undefined
 >(
   config: {
     readonly id?: string
@@ -1271,18 +1625,18 @@ export const make: Make = (<
     readonly events: Machine.EventProtocol<"public", InputEvents>
     readonly internalEvents?: Machine.EventProtocol<"internal", InternalEvents>
     readonly emittedEvents?: Machine.EventProtocol<"emitted", Emits>
-    readonly parentEvents?: Machine.EventProtocol<"public", ParentEvents>
+    readonly parent?: ParentDeclaration
     readonly input?: Input
     readonly initial: unknown
   }
-): MakeResult<States, InputEvents, Emits, Input, InitialE, InitialR, InternalEvents, ParentEvents> => {
+): MakeResult<States, InputEvents, Emits, Input, InitialE, InitialR, InternalEvents, ParentDeclaration> => {
   StateDefinition.validateStateDefinitions(config.states, "Machine.make")
   const self = Object.create(Proto)
   self.states = config.states
   self.events = config.events
   self.internalEvents = config.internalEvents ?? Protocol.makeEventProtocol("internal", [] as const)
   self.emittedEvents = config.emittedEvents ?? Protocol.makeEventProtocol("emitted", [] as const)
-  self.parentEvents = config.parentEvents ?? Protocol.makeEventProtocol("public", [] as const)
+  self.parent = config.parent
   self.input = config.input
   self.id = config.id
   self.stateNodes = Topology.compileStateNodes(config.states)
@@ -1292,7 +1646,6 @@ export const make: Make = (<
   self.makeTargetBuilder = makeTargetBuilder(config.states, self.stateNodes)
   self.handlers = Object.create(null)
   self.handle = makeHandle(self)
-  self.invoke = makeBoundInvoke
   Protocol.setProtocol(self)
   return self
 }) as Make
@@ -1315,6 +1668,27 @@ export const events = <const Inputs extends ReadonlyArray<Machine.EventProtocolI
     flattenEventProtocolInputs("public", inputs)
   ) as Machine.EventProtocol<"public", Machine.EventProtocolInputSchemasOf<"public", Inputs>>
 
+const makeParent = <
+  const Mode extends ParentMode,
+  const Events extends ReadonlyArray<Machine.TaggedSchema>
+>(
+  mode: Mode,
+  events: Machine.EventProtocol<"public", Events>
+): Parent<Mode, Events> => {
+  if (!Protocol.isEventProtocol(events, "public")) {
+    throw new Error("Machine parent declarations require a protocol created with Machine.events")
+  }
+  return Object.freeze({ [ParentTypeId]: ParentTypeId, mode, events })
+}
+
+export const parent = <const Events extends ReadonlyArray<Machine.TaggedSchema>>(
+  events: Machine.EventProtocol<"public", Events>
+): Parent<"required", Events> => makeParent("required", events)
+
+export const optionalParent = <const Events extends ReadonlyArray<Machine.TaggedSchema>>(
+  events: Machine.EventProtocol<"public", Events>
+): Parent<"optional", Events> => makeParent("optional", events)
+
 export const internalEvents = <const Inputs extends ReadonlyArray<Machine.EventProtocolInput<"internal">>>(
   ...inputs: Inputs
 ): Machine.EventProtocol<"internal", Machine.EventProtocolInputSchemasOf<"internal", Inputs>> =>