Harden machine operation totality (#28)

Author: SandroMaglione

.changeset/wise-machines-harden.md

@@ -0,0 +1,5 @@
+---
+"@typeonce/effect-machine": patch
+---
+
+Harden planning, snapshot round trips, and logical runtime resumption for valid typed machines. Initial choices no longer retain abandoned roots, history fallbacks resolve nested choices before snapshot normalization, and the independent finite-model oracle follows nested choice initializers.

src/internal/machinePlanner.ts

@@ -463,7 +463,8 @@ const resolveHistoryTarget = Effect.fnUntraced(function*(
       }),
       actions: completed.actions,
       raisedEvents: completed.raisedEvents,
-      emittedEvents: completed.emittedEvents
+      emittedEvents: completed.emittedEvents,
+      transitions: []
     }
   }
 
@@ -481,7 +482,37 @@ const resolveHistoryTarget = Effect.fnUntraced(function*(
   if (collected.state === undefined || isHistoryTarget(collected.state) || !isSnapshot(collected.state)) {
     throw new Error(`Machine history default for "${target.path}" must return a complete snapshot containing its owner`)
   }
-  const fallbackConfiguration = yield* normalizeConfigurationEffect(machine, collected.state as any)
+  const fallbackChoice = choiceFromTarget(collected.state)
+  const choiceResolution = fallbackChoice === undefined
+    ? undefined
+    : yield* resolveChoiceTarget(
+      machine,
+      {
+        active: new Set(),
+        values: new Map(),
+        outputs: new Map(),
+        history: configuration.history
+      },
+      collected.state,
+      event
+    )
+  let fallbackConfiguration = choiceResolution === undefined
+    ? yield* normalizeConfigurationEffect(machine, collected.state as any)
+    : yield* normalizeTargetConfigurationEffect(machine, {
+      active: new Set(),
+      values: new Map(),
+      outputs: new Map(),
+      history: configuration.history
+    }, choiceResolution.target as any)
+  for (const additionalTarget of choiceResolution?.additionalTargets ?? []) {
+    fallbackConfiguration = yield* normalizeTargetConfigurationEffect(
+      machine,
+      fallbackConfiguration,
+      additionalTarget as
+        | Machine.Snapshot<any>
+        | Machine.Target<any, string>
+    )
+  }
   if (!fallbackConfiguration.active.has(target.parent)) {
     throw new Error(
       `Machine history default for "${target.path}" returned a configuration that does not contain owner state "${target.parent}"`
@@ -494,9 +525,10 @@ const resolveHistoryTarget = Effect.fnUntraced(function*(
       snapshot: snapshot as any,
       values: values as any
     }),
-    actions: collected.actions,
-    raisedEvents: collected.raisedEvents,
-    emittedEvents: collected.emittedEvents
+    actions: [...collected.actions, ...(choiceResolution?.actions ?? [])],
+    raisedEvents: [...collected.raisedEvents, ...(choiceResolution?.raisedEvents ?? [])],
+    emittedEvents: [...collected.emittedEvents, ...(choiceResolution?.emittedEvents ?? [])],
+    transitions: choiceResolution?.transitions ?? []
   }
 })
 
@@ -1090,6 +1122,14 @@ const withChoiceValues = (target: unknown, values: Readonly<Record<string, unkno
   })
 }
 
+interface ResolvedChoiceTransition {
+  readonly source: string
+  readonly trigger: Machine.TransitionTrigger
+  readonly reenter: false
+  readonly target: string
+  readonly resolvedTarget: string
+}
+
 const resolveChoiceTarget = Effect.fnUntraced(function*(
   machine: Machine.Any,
   configuration: ActiveConfiguration,
@@ -1101,13 +1141,7 @@ const resolveChoiceTarget = Effect.fnUntraced(function*(
   const actions: Array<DeferredAction> = []
   const raisedEvents: Array<unknown> = []
   const emittedEvents: Array<unknown> = []
-  const transitions: Array<{
-    readonly source: string
-    readonly trigger: Machine.TransitionTrigger
-    readonly reenter: false
-    readonly target: string
-    readonly resolvedTarget: string
-  }> = []
+  const transitions: Array<ResolvedChoiceTransition> = []
   let iterations = 0
 
   while (pending.length > 0) {
@@ -1231,6 +1265,7 @@ const collectEvaluatedTransition = Effect.fnUntraced(function*<
     readonly actions: ReadonlyArray<DeferredAction>
     readonly raisedEvents: ReadonlyArray<unknown>
     readonly emittedEvents: ReadonlyArray<unknown>
+    readonly transitions: ReadonlyArray<ResolvedChoiceTransition>
   } | undefined
   const reenteredHistoryParent = choiceResolvedTarget !== undefined && isHistoryTarget(choiceResolvedTarget) &&
     selection.transition.reenter && state.active.has(choiceResolvedTarget.parent)
@@ -1269,6 +1304,7 @@ const collectEvaluatedTransition = Effect.fnUntraced(function*<
   const additionalHistoryActions: Array<DeferredAction> = []
   const additionalHistoryRaisedEvents: Array<unknown> = []
   const additionalHistoryEmittedEvents: Array<unknown> = []
+  const additionalHistoryChoiceTransitions: Array<ResolvedChoiceTransition> = []
   const additionalChoiceTargets: Array<
     Machine.Snapshot<States> | Machine.Target<States, Machine.StateIdentifier<States>>
   > = []
@@ -1287,6 +1323,7 @@ const collectEvaluatedTransition = Effect.fnUntraced(function*<
     additionalHistoryActions.push(...resolved.actions)
     additionalHistoryRaisedEvents.push(...resolved.raisedEvents)
     additionalHistoryEmittedEvents.push(...resolved.emittedEvents)
+    additionalHistoryChoiceTransitions.push(...resolved.transitions)
   }
   const targetPath = target === undefined
     ? undefined
@@ -1331,7 +1368,11 @@ const collectEvaluatedTransition = Effect.fnUntraced(function*<
       changed,
       exitPaths: [],
       entryPaths: [],
-      choiceTransitions: choiceResolution?.transitions ?? []
+      choiceTransitions: [
+        ...(choiceResolution?.transitions ?? []),
+        ...(historyResolution?.transitions ?? []),
+        ...additionalHistoryChoiceTransitions
+      ]
     } as EvaluatedTransition<States, Event, E, R, Context>
   }
 
@@ -1380,7 +1421,11 @@ const collectEvaluatedTransition = Effect.fnUntraced(function*<
         )
       )
       : getEntryPaths(machine, stateAfterTransition, boundary),
-    choiceTransitions: choiceResolution?.transitions ?? []
+    choiceTransitions: [
+      ...(choiceResolution?.transitions ?? []),
+      ...(historyResolution?.transitions ?? []),
+      ...additionalHistoryChoiceTransitions
+    ]
   } as EvaluatedTransition<States, Event, E, R, Context>
 })
 
@@ -1553,6 +1598,7 @@ export const planInitial: <
     const initialHistoryActions: Array<DeferredAction> = []
     const initialHistoryRaisedEvents: Array<unknown> = []
     const initialHistoryEmittedEvents: Array<unknown> = []
+    const initialHistoryChoiceTransitions: Array<ResolvedChoiceTransition> = []
     const resolvedInitialTargets: Array<unknown> = []
     for (
       const target of choiceResolution === undefined
@@ -1568,6 +1614,7 @@ export const planInitial: <
       initialHistoryActions.push(...history.actions)
       initialHistoryRaisedEvents.push(...history.raisedEvents)
       initialHistoryEmittedEvents.push(...history.emittedEvents)
+      initialHistoryChoiceTransitions.push(...history.transitions)
     }
     let resolvedConfiguration = choiceResolution === undefined
       ? yield* normalizeConfigurationEffect<States>(machine, state as Machine.Snapshot<States>)
@@ -1585,19 +1632,7 @@ export const planInitial: <
         additionalTarget as Machine.Snapshot<States> | Machine.Target<States, Machine.StateIdentifier<States>>
       )
     }
-    const configuration: ActiveConfiguration = initialChoice === undefined
-      ? resolvedConfiguration
-      : {
-        ...resolvedConfiguration,
-        active: new Set([
-          ...resolvedConfiguration.active,
-          ...Object.keys(initialChoice.values).filter((path) => {
-            const node = getNode(machine, path)
-            return node.type !== "choice" && node.type !== "history"
-          })
-        ]),
-        values: new Map([...Object.entries(initialChoice.values), ...resolvedConfiguration.values])
-      }
+    const configuration: ActiveConfiguration = resolvedConfiguration
     validateInitialConfiguration(machine, configuration)
     const startingState = snapshotFromConfiguration<States>(machine, configuration)
     const initialEntryPaths = getInitialEntryPaths(machine, configuration)
@@ -1634,7 +1669,7 @@ export const planInitial: <
         choiceResolution === undefined ? [] : [{
           next: configuration,
           event: InitialEvent,
-          transitions: choiceResolution.transitions,
+          transitions: [...choiceResolution.transitions, ...initialHistoryChoiceTransitions],
           actions: [...choiceResolution.actions, ...initialHistoryActions] as ReadonlyArray<Effect.Effect<void, E, R>>,
           raisedEvents: [
             ...choiceResolution.raisedEvents,

src/internal/machineTestReferenceModel.ts

@@ -622,6 +622,20 @@ const choiceResolvedTargetPath = (index: ModelIndex, path: string): string => {
   })!
 }
 
+const choiceChainResolvedTargetPath = (index: ModelIndex, path: string): string => {
+  let current = getState(index, path)
+  const seen = new Set<string>()
+  while (current.node._tag === "Choice") {
+    if (seen.has(current.path)) return choiceResolvedTargetPath(index, current.path)
+    seen.add(current.path)
+    const selected = getState(index, current.node.selected)
+    const nestedChoice = entryChoicePath(index, selected.path)
+    if (nestedChoice === undefined) return choiceResolvedTargetPath(index, current.path)
+    current = getState(index, nestedChoice)
+  }
+  return current.path
+}
+
 const isPathInSubtree = (path: string, root: string): boolean => path === root || path.startsWith(`${root}.`)
 
 const expandSelection = (
@@ -898,7 +912,7 @@ const transitionRecord = (index: ModelIndex, transition: FiniteTransition): Refe
     ? runtimeTargetPath(index, transition)
     : entryChoicePath(index, transition.target) === undefined
     ? runtimeTargetPath(index, transition)
-    : choiceResolvedTargetPath(index, entryChoicePath(index, transition.target)!)
+    : choiceChainResolvedTargetPath(index, entryChoicePath(index, transition.target)!)
 })
 
 const choiceTransitionRecords = (index: ModelIndex, path: string): ReadonlyArray<ReferenceTransition> => {
@@ -909,26 +923,25 @@ const choiceTransitionRecords = (index: ModelIndex, path: string): ReadonlyArray
     if (seen.has(current.path)) break
     seen.add(current.path)
     const selected = getState(index, current.node.selected)
-    const selectedTarget = selected.node._tag === "Choice"
-      ? selected.path
-      : choiceResolvedTargetPath(index, current.path)
+    const nestedChoice = entryChoicePath(index, selected.path)
+    const selectedTarget = nestedChoice ?? choiceResolvedTargetPath(index, current.path)
     records.push({
       source: current.path,
       trigger: { type: "choice" },
       reenter: false,
       target: selectedTarget,
       resolvedTarget: choiceResolvedTargetPath(index, current.path)
     })
-    current = getState(index, resolveChoicePath(index, selected.path))
+    if (nestedChoice === undefined) break
+    current = getState(index, nestedChoice)
   }
   return records
 }
 
 const initialChoiceTransitionRecords = (index: ModelIndex, path: string): ReadonlyArray<ReferenceTransition> => {
   const current = getState(index, path)
   if (current.node._tag === "Choice") {
-    const records = choiceTransitionRecords(index, current.path)
-    return [...records, ...initialChoiceTransitionRecords(index, resolveChoicePath(index, current.path))]
+    return choiceTransitionRecords(index, current.path)
   }
   if (current.node._tag === "Compound") {
     return initialChoiceTransitionRecords(index, initialChildPath(current))

test/MachineChoice.test.ts

@@ -66,6 +66,47 @@ describe("Machine choice pseudo-states", () => {
       ])
     }))
 
+  it.effect("does not retain an abandoned initial root after a full choice target", () =>
+    Effect.gen(function*() {
+      class Outside extends Schema.TaggedClass<Outside>("InitialChoiceOutside")("InitialChoiceOutside", {}) {}
+      const states = Machine.defineStates({
+        Flow: {
+          schema: Flow,
+          initial: "Routing",
+          states: { Routing: { type: "choice" }, Approved }
+        },
+        Outside
+      })
+      const entries: Array<string> = []
+      const routed = Machine.make({
+        states: states.states,
+        events: [],
+        initial: () => states.initial.Flow(new Flow({ score: 80 }), (flow) => flow.Routing())
+      }).handle({
+        Flow: {
+          entry: () => Machine.action(Effect.sync(() => entries.push("Flow"))),
+          states: {
+            Routing: {
+              choice: {
+                targets: ["Outside"],
+                transition: ({ target }) => target.full.Outside(new Outside({}))
+              }
+            }
+          }
+        },
+        Outside: { entry: () => Machine.action(Effect.sync(() => entries.push("Outside"))) }
+      })
+
+      const plan = yield* Machine.planInitial(routed)
+      assert.deepStrictEqual(Machine.configuration(routed, plan.startingState).map(({ path }) => path), ["Outside"])
+      assert.deepStrictEqual(plan.initialEntryPaths, ["Outside"])
+      yield* Machine.runActions(plan.actions, {
+        raise: () => Effect.void,
+        sendParent: () => Effect.void
+      })
+      assert.deepStrictEqual(entries, ["Outside"])
+    }))
+
   it.effect("targets a choice from an event and preserves that event", () =>
     Effect.gen(function*() {
       const initial = yield* Machine.planInitial(machine)
@@ -497,6 +538,61 @@ describe("Machine choice pseudo-states", () => {
       assert.strictEqual(plan.state.state.path, "Flow.Active")
     }))
 
+  it.effect("resolves a nested choice inside a first-use history fallback", () =>
+    Effect.gen(function*() {
+      class Active extends Schema.TaggedClass<Active>("FallbackChoiceActive")("FallbackChoiceActive", {}) {}
+      class Outside extends Schema.TaggedClass<Outside>("FallbackChoiceOutside")("FallbackChoiceOutside", {}) {}
+      class Resume extends Schema.TaggedClass<Resume>("FallbackChoiceResume")("FallbackChoiceResume", {}) {}
+      const states = Machine.defineStates({
+        Flow: {
+          schema: Flow,
+          initial: "Active",
+          states: {
+            Active,
+            Routing: { type: "choice" },
+            Recent: { type: "history" }
+          }
+        },
+        Outside
+      })
+      const historyChoice = Machine.make({
+        states: states.states,
+        events: [Resume],
+        initial: () => states.initial.Outside(new Outside({}))
+      }).handle({
+        Flow: {
+          history: {
+            Recent: {
+              default: ({ target }) => target.Flow(new Flow({ score: 1 }), (flow) => flow.Routing())
+            }
+          },
+          states: {
+            Routing: {
+              choice: {
+                targets: ["Flow.Active"],
+                transition: ({ target }) => target.local.Active(new Active({}))
+              }
+            }
+          }
+        },
+        Outside: {
+          on: { FallbackChoiceResume: ({ target }) => target.history.Flow.Recent() }
+        }
+      })
+
+      const initial = yield* Machine.planInitial(historyChoice)
+      const resumed = yield* Machine.plan(historyChoice, initial.state, new Resume({}))
+      assert.strictEqual(resumed.next.path, "Flow")
+      if (resumed.next.path === "Flow") assert.strictEqual(resumed.next.state.path, "Flow.Active")
+      assert.deepStrictEqual(
+        resumed.microsteps[0]?.transitions.map(({ source, trigger }) => ({ source, trigger: trigger.type })),
+        [
+          { source: "Outside", trigger: "event" },
+          { source: "Flow.Routing", trigger: "choice" }
+        ]
+      )
+    }))
+
   it("inspects declared choice edges without executing the resolver", () => {
     assert.deepStrictEqual(Machine.transitionDefinitions(machine).filter(({ trigger }) => trigger.type === "choice"), [
       {