Prepare core transition evidence for MachineTest (#128)

Author: SandroMaglione

.changeset/retain-transition-branch-evidence.md

@@ -0,0 +1,7 @@
+---
+"@typeonce/effect-machine": minor
+---
+
+Retain exact static and runtime transition evidence for testing and visualization. Transition branch inspection now includes the selected target kind and scope, retained planner transitions identify the zero-based branch that executed, and `Machine.initialDefinition` exposes the root startup selection without executing its resolver.
+
+Use `branchIndex` to associate a retained transition with the corresponding entry in `Machine.transitionDefinitions(machine).branches`. Direct transitions use index `0`; conditional cases retain their declaration index and `otherwise` follows the final case.

examples/platformer/src/machine.test.ts

@@ -164,7 +164,12 @@ describe("platformer history integration", () => {
         reenter: true,
         branches: [{
           type: "direct",
-          target: "Character.locomotion.Playing.Airborne.airJump.AirJumpWallLock"
+          target: "Character.locomotion.Playing.Airborne.airJump.AirJumpWallLock",
+          selection: {
+            path: "Character.locomotion.Playing.Airborne.airJump.AirJumpWallLock",
+            kind: "state",
+            scope: "local"
+          }
         }]
       })
       expect(definitions.every(({ branches }) => branches.length > 0)).toBe(true)

src/Machine.ts

@@ -259,6 +259,8 @@ export interface Machine<
 
   /** @internal */
   readonly initial: (...args: [...Machine.InputArgs<Input>]) => Machine.InitialResult<States, InitialE, InitialR>
+  /** @internal */
+  readonly initialDefinition: Machine.InitialDefinition
 }
 
 export {
@@ -2413,6 +2415,8 @@ export declare namespace Machine {
     readonly invoke: any
     /** @internal */
     readonly initial: any
+    /** @internal */
+    readonly initialDefinition: InitialDefinition
   }
 
   /**
@@ -3157,22 +3161,42 @@ export declare namespace Machine {
       readonly outcome: "done" | "failure" | "snapshot"
     }
 
+  /** Static topology selected by a transition branch. */
+  export interface TransitionTargetSelection<
+    Path extends string | undefined = string | undefined,
+    Kind extends Topology.TargetSelectionKind = Topology.TargetSelectionKind,
+    Scope extends Topology.TargetSelectionScope | undefined = Topology.TargetSelectionScope | undefined
+  > {
+    readonly path: Path
+    readonly kind: Kind
+    readonly scope: Scope
+  }
+
   /** One statically captured branch of a transition definition. */
   export type TransitionBranch<Path extends string = string> =
     | {
       readonly type: "direct"
       readonly target: Path | undefined
+      readonly selection: TransitionTargetSelection<Path | undefined>
     }
     | {
       readonly type: "case"
       readonly title: string
       readonly target: Path | undefined
+      readonly selection: TransitionTargetSelection<Path | undefined>
     }
     | {
       readonly type: "otherwise"
       readonly target: Path | undefined
+      readonly selection: TransitionTargetSelection<Path | undefined>
     }
 
+  /** The statically selected root entry for machine startup. */
+  export interface InitialDefinition<Path extends string = string> {
+    readonly target: Path
+    readonly selection: TransitionTargetSelection<Path, "state" | "initial", "initial">
+  }
+
   /**
    * Inspectable registration for a transition handler.
    *
@@ -3223,6 +3247,8 @@ export declare namespace Machine {
     readonly source: SourcePath
     readonly trigger: TransitionTrigger<EventTag>
     readonly reenter: boolean
+    /** Zero-based index of the selected static branch. */
+    readonly branchIndex: number
     /** Path returned by the handler, including a history pseudo-state. */
     readonly target: TargetPath | undefined
     /** Concrete path used after resolving history, otherwise equal to `target`. */
@@ -8232,6 +8258,20 @@ export const stateNodes: <M extends Machine.Any>(machine: M) => ReadonlyArray<
   >
 > = internal.stateNodes
 
+/**
+ * Returns the statically selected root entry used during machine startup.
+ *
+ * This function does not execute the initial resolver or require machine
+ * input. `kind: "initial"` means that the selected root enters its declared
+ * initial configuration.
+ *
+ * @category getters
+ * @since 0.14.0
+ */
+export const initialDefinition: <M extends Machine.Any>(machine: M) => Machine.InitialDefinition<
+  Machine.RootStateIdentifier<Machine.StateIdentifier<Machine.States<M>>>
+> = internal.initialDefinition
+
 /**
  * Returns every registered transition handler in state definition order.
  *

src/internal/machine/executionPlan.ts

@@ -424,12 +424,13 @@ export interface ExecutionMacrostep<State = unknown> {
 const collectIndexedTransition = (
   machine: Machine.Any,
   transition: TransitionHandler<any, any, any, any>,
-  context: any
+  context: any,
+  evaluate?: NonNullable<MicrostepTransition<any, any, any, any>["evaluate"]>
 ) => {
   let commands: Array<RuntimeCommand> | undefined
   let raisedEvents: Array<any> | undefined
   let emittedEvents: Array<unknown> | undefined
-  const result = transition(context, {
+  const enqueue = {
     raise: (event: unknown) => {
       ;(raisedEvents ??= []).push(decodeEventSync(machine, event))
     },
@@ -442,9 +443,13 @@ const collectIndexedTransition = (
     stop: (child: unknown) => {
       ;(commands ??= []).push({ _tag: "Stop", child: child as any })
     }
-  })
+  }
+  const evaluated = evaluate === undefined
+    ? { result: transition(context, enqueue), branchIndex: 0 }
+    : evaluate(context, enqueue)
   return {
-    state: isNoTarget(result) ? undefined : result,
+    state: isNoTarget(evaluated.result) ? undefined : evaluated.result,
+    branchIndex: evaluated.branchIndex,
     commands: commands ?? emptyExecutionValues,
     raisedEvents: raisedEvents ?? emptyExecutionValues,
     emittedEvents: emittedEvents ?? emptyExecutionValues
@@ -531,7 +536,12 @@ const collectIndexedEvaluatedTransition = (
   state: OwnedIndexedState,
   selection: IndexedSelectedTransition
 ): IndexedEvaluatedTransition => {
-  const transitionResult = collectIndexedTransition(machine, selection.transition.transition, selection.context)
+  const transitionResult = collectIndexedTransition(
+    machine,
+    selection.transition.transition,
+    selection.context,
+    selection.transition.evaluate
+  )
   const unresolvedTarget = transitionResult.state
   validateDeclaredTransitionTarget(
     selection.sourcePath,
@@ -558,6 +568,7 @@ const collectIndexedEvaluatedTransition = (
   if (!changed) {
     return {
       selection,
+      branchIndex: transitionResult.branchIndex,
       unresolvedTarget: unresolvedTarget as any,
       target: target as any,
       next,
@@ -581,6 +592,7 @@ const collectIndexedEvaluatedTransition = (
     : naturalBoundary
   return {
     selection,
+    branchIndex: transitionResult.branchIndex,
     unresolvedTarget: unresolvedTarget as any,
     target: target as any,
     next,
@@ -606,6 +618,7 @@ const indexedMicrostep = (
     source: transition.selection.sourcePath,
     trigger: transition.selection.trigger,
     reenter: transition.selection.transition.reenter,
+    branchIndex: transition.branchIndex,
     target: transition.unresolvedTarget === undefined ? undefined : getTargetNodePath(transition.unresolvedTarget),
     resolvedTarget: transition.target === undefined ? undefined : getTargetNodePath(transition.target)
   })
@@ -740,7 +753,8 @@ const planIndexedFlatState = (
           event,
           snapshot: snapshotFromIndexedState(descriptor, current),
           target: getTargetBuilder(machine, sourcePath)
-        }
+        },
+        transition.evaluate
       )
       const target = transitionResult.state
       validateDeclaredTransitionTarget(
@@ -789,6 +803,7 @@ const planIndexedFlatState = (
               source: sourcePath,
               trigger: { type: "event", event: event._tag },
               reenter: transition.reenter,
+              branchIndex: transitionResult.branchIndex,
               target: target === undefined ? undefined : getTargetNodePath(target as any),
               resolvedTarget: target === undefined ? undefined : getTargetNodePath(target as any)
             }]

src/internal/machine/machine.ts

@@ -119,6 +119,7 @@ const cloneWithHandlers = (
   machine.input = self.input
   machine.id = self.id
   machine.initial = self.initial
+  machine.initialDefinition = self.initialDefinition
   machine.stateNodes = self.stateNodes
   machine.makeTargetBuilder = self.makeTargetBuilder
   machine.handlers = handlers
@@ -139,6 +140,15 @@ type CapturedBranch = DefinitionBranch & {
   readonly selection: Topology.TargetSelection
 }
 
+const transitionTargetSelection = (
+  selection: Topology.TargetSelection
+): Machine.TransitionTargetSelection =>
+  Object.freeze({
+    path: selection.path,
+    kind: selection.kind,
+    scope: selection.scope
+  })
+
 const makeSelectionMethod = (
   kind: Topology.TargetSelectionKind,
   path: string | undefined,
@@ -349,6 +359,27 @@ const captureTransition = (
       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
+          }
+        }
+      }
+      return {
+        result: runCapturedBranch(otherwise, context, enqueue, stateNodes, path),
+        branchIndex: cases.length
+      }
+    }
     return {
       reenter,
       targets: [
@@ -357,32 +388,37 @@ const captureTransition = (
         )
       ],
       branches: [
-        ...cases.map((branch) => ({ type: "case" as const, title: branch.title!, target: branch.selection.path })),
-        { type: "otherwise" as const, target: otherwise.selection.path }
-      ],
-      transition: (context: Record<string, any>, enqueue: unknown) => {
-        const predicateContext = { ...context }
-        delete predicateContext.target
-        for (const branch of cases) {
-          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 runCapturedBranch(branch, context, enqueue, stateNodes, path, { value: result.value })
-          }
+        ...cases.map((branch) => ({
+          type: "case" as const,
+          title: branch.title!,
+          target: branch.selection.path,
+          selection: transitionTargetSelection(branch.selection)
+        })),
+        {
+          type: "otherwise" as const,
+          target: otherwise.selection.path,
+          selection: transitionTargetSelection(otherwise.selection)
         }
-        return runCapturedBranch(otherwise, context, enqueue, stateNodes, path)
-      }
+      ],
+      evaluate,
+      transition: (context: Record<string, any>, enqueue: unknown) => evaluate(context, enqueue).result
     }
   }
   const branch = captureDefinitionBranch(transition, selector, path, trigger)
+  const evaluate = (context: Record<string, any>, enqueue: unknown) => ({
+    result: runCapturedBranch(branch, context, enqueue, stateNodes, path),
+    branchIndex: 0
+  })
   return {
     reenter,
     targets: branch.selection.path === undefined ? [] : [branch.selection.path],
-    branches: [{ type: "direct" as const, target: branch.selection.path }],
-    transition: (context: Record<string, any>, enqueue: unknown) =>
-      runCapturedBranch(branch, context, enqueue, stateNodes, path)
+    branches: [{
+      type: "direct" as const,
+      target: branch.selection.path,
+      selection: transitionTargetSelection(branch.selection)
+    }],
+    evaluate,
+    transition: (context: Record<string, any>, enqueue: unknown) => evaluate(context, enqueue).result
   }
 }
 
@@ -1067,19 +1103,28 @@ const compileInitial = (
   definition: unknown,
   states: Machine.StateTree,
   stateNodes: Machine.StateNodes
-): (input?: unknown) => unknown => {
+): {
+  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)
-  return (input?: unknown) => {
-    const result = branch.resolve === undefined
-      ? branch.builder()
-      : branch.resolve({ input, target: branch.builder }, undefined)
-    validateInitialSelection(result, branch.selection)
-    return result
+  return {
+    initial: (input?: unknown) => {
+      const result = branch.resolve === undefined
+        ? branch.builder()
+        : branch.resolve({ input, target: branch.builder }, undefined)
+      validateInitialSelection(result, branch.selection)
+      return result
+    },
+    definition: Object.freeze({
+      target: branch.selection.path!,
+      selection: transitionTargetSelection(branch.selection) as Machine.InitialDefinition["selection"]
+    })
   }
 }
 
@@ -1221,7 +1266,9 @@ export const make: Make = (<
   self.input = config.input
   self.id = config.id
   self.stateNodes = Topology.compileStateNodes(config.states)
-  self.initial = compileInitial(config.initial, config.states, self.stateNodes)
+  const compiledInitial = compileInitial(config.initial, config.states, self.stateNodes)
+  self.initial = compiledInitial.initial
+  self.initialDefinition = compiledInitial.definition
   self.makeTargetBuilder = makeTargetBuilder(config.states, self.stateNodes)
   self.handlers = Object.create(null)
   self.handle = makeHandle(self)
@@ -1427,6 +1474,15 @@ export const stateNodes = <M extends Machine.Any>(
     >
   >
 
+export const initialDefinition = <M extends Machine.Any>(
+  machine: M
+): Machine.InitialDefinition<
+  Machine.RootStateIdentifier<Machine.StateIdentifier<Machine.States<M>>>
+> =>
+  machine.initialDefinition as Machine.InitialDefinition<
+    Machine.RootStateIdentifier<Machine.StateIdentifier<Machine.States<M>>>
+  >
+
 export const transitionDefinitions = <M extends Machine.Any>(
   machine: M
 ): ReadonlyArray<