@typeonce/effect-machine 0.16.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,7 +132,6 @@ const makeWithHandlers = (
   machine.stateNodes = self.stateNodes
   machine.makeTargetBuilder = self.makeTargetBuilder
   machine.handlers = handlers
-  machine.invoke = makeBoundInvoke
   Protocol.copyProtocol(self, machine)
   return machine
 }
@@ -139,6 +139,7 @@ const makeWithHandlers = (
 type DefinitionBranch = {
   readonly target: (selector: unknown) => unknown
   readonly resolve?: (context: any, enqueue: unknown) => unknown
+  readonly declinable?: boolean
 }
 
 type CapturedBranch = DefinitionBranch & {
@@ -156,6 +157,189 @@ type CapturedNamedBranch = {
   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 =>
@@ -172,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,
@@ -194,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") {
@@ -212,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
@@ -239,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,
@@ -309,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,
@@ -352,7 +543,14 @@ const runCapturedBranch = (
   const resolverContext = { ...context }
   if (branch.selection.kind === "none") delete resolverContext.target
   else resolverContext.target = selectedTarget
+  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
 }
@@ -394,7 +592,7 @@ const captureNamedBranches = (
     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: target })
+    return Object.freeze({ key, title: title ?? key, selection: plainTargetSelection(target) })
   }))
 }
 
@@ -474,17 +672,24 @@ const validateSelectedBranchResult = (
 }
 
 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
+  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") {
@@ -499,7 +704,18 @@ const captureTransition = (
       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 branching transition for state "${path}" on "${String(trigger)}" must select one declared branch`
@@ -518,6 +734,7 @@ const captureTransition = (
     }
     return {
       reenter,
+      declinable,
       targets: [
         ...new Set(
           branches.flatMap((branch) => branch.selection.path === undefined ? [] : [branch.selection.path])
@@ -544,6 +761,7 @@ const captureTransition = (
   })
   return {
     reenter,
+    declinable,
     targets: branch.selection.path === undefined ? [] : [branch.selection.path],
     branches: [{
       type: "direct" as const,
@@ -1185,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 = (
@@ -1207,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 => {
@@ -1237,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
     },
@@ -1297,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>>
@@ -1311,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
 }
@@ -1324,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],
@@ -1335,7 +1573,7 @@ type MakeResult<
   Machine.TerminalOutput<States>,
   Emits,
   InputEvents,
-  ParentEvents
+  Machine.ParentEventsOf<ParentDeclaration>
 >
 
 interface Make {
@@ -1347,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>,
@@ -1360,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
 }
@@ -1376,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
@@ -1384,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)
@@ -1405,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
@@ -1428,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>> =>