@typeonce/effect-machine 0.12.0 → 0.14.0

package/src/internal/testing/machine/verification.ts

@@ -29,7 +29,6 @@ import type {
   StateCoverageItem,
   Trace,
   TraceStep,
-  TransitionCoverageItem,
   VerificationLaw,
   VerificationLawGroup,
   VerificationViolation,
@@ -40,6 +39,7 @@ import { toArbitraryWithReport } from "./arbitrary.js"
 import type { FiniteModel } from "./finiteModel.js"
 import * as ReferenceModel from "./referenceModel.js"
 import { rawConfigurationPaths, run } from "./trace.js"
+import { makeTransitionCoverageCollector, sameTransitionTrigger } from "./transitionCoverage.js"
 
 export {
   advanceCommand,
@@ -469,18 +469,21 @@ const normalizeTraces = <M extends AnyMachine>(
 ): ReadonlyArray<Trace<M>> =>
   Array.isArray(traceOrTraces) ? traceOrTraces as ReadonlyArray<Trace<M>> : [traceOrTraces as Trace<M>]
 
-const sameCoverageTrigger = (
-  left: Machine.Machine.TransitionTrigger,
-  right: Machine.Machine.TransitionTrigger
-): boolean =>
-  left.type === right.type && (left.type !== "event" || right.type === "event" && left.event === right.event)
-
-const targetWithinDeclaredBounds = (
+const targetWithinSelection = (
   target: string | undefined,
-  bounds: Machine.Machine.TransitionTargets
-): boolean =>
-  target === undefined || bounds.type === "dynamic" ||
-  bounds.paths.some((path) => target === path || target.startsWith(`${path}.`))
+  branch: Machine.Machine.TransitionBranch,
+  nodeByPath: ReadonlyMap<string, Machine.Machine.StateNode>
+): boolean => {
+  const selection = branch.selection
+  if (selection.kind === "none") return target === undefined
+  if (target === undefined || selection.path === undefined) return false
+  if (target === selection.path) return true
+  const selectedNode = nodeByPath.get(selection.path)
+  return selection.kind === "state" &&
+    (selection.scope === "local" || selection.scope === "branch") &&
+    (selectedNode?.type === "compound" || selectedNode?.type === "parallel") &&
+    target.startsWith(`${selection.path}.`)
+}
 
 const finiteTagValues = (ast: SchemaAST.AST): ReadonlyArray<PropertyKey> | undefined => {
   if (SchemaAST.isLiteral(ast)) {
@@ -560,24 +563,7 @@ export const coverage = <M extends AnyMachine>(
   const entryHits = new Set<number>()
   const exitHits = new Set<number>()
 
-  const definitions = Machine.transitionDefinitions(machine).map(
-    (
-      definition,
-      index
-    ): TransitionCoverageItem<
-      StateNodePath<M>,
-      Machine.Machine.TagOf<Machine.Machine.Events<M>[number]>,
-      StateNodePath<M>
-    > => ({
-      id: `transition:${index}:${formatValue(definition)}`,
-      index,
-      source: definition.source,
-      trigger: definition.trigger,
-      reenter: definition.reenter,
-      targets: definition.targets
-    })
-  )
-  const transitionHits = new Set<number>()
+  const transitionCoverage = makeTransitionCoverageCollector(machine)
 
   const declaredEvents = publicEventTags(machine)
   const declaredEventTags = declaredEvents.tags
@@ -635,6 +621,7 @@ export const coverage = <M extends AnyMachine>(
   }
 
   const observeMicrostep = (microstep: Microstep<M, any>): void => {
+    transitionCoverage.observeMicrostep(microstep)
     microsteps += 1
     if (microstep.changed) changedMicrosteps += 1
     raisedEvents += microstep.raisedEvents.length
@@ -652,13 +639,6 @@ export const coverage = <M extends AnyMachine>(
         historyTargets += 1
         if (retained.resolvedTarget !== undefined) resolvedHistoryTargets += 1
       }
-      const definitionIndex = definitions.findIndex((definition) =>
-        definition.source === retained.source &&
-        definition.reenter === retained.reenter &&
-        sameCoverageTrigger(definition.trigger, retained.trigger) &&
-        targetWithinDeclaredBounds(retained.target, definition.targets)
-      )
-      if (definitionIndex !== -1) transitionHits.add(definitionIndex)
     }
   }
 
@@ -698,7 +678,7 @@ export const coverage = <M extends AnyMachine>(
       entry: coverageSummary(activeNodes, entryHits),
       exit: coverageSummary(activeNodes, exitHits)
     },
-    transitions: coverageSummary(definitions, transitionHits),
+    transitions: transitionCoverage.summary(),
     events: declaredEvents.diagnostics.length === 0
       ? {
         available: true,
@@ -966,12 +946,6 @@ const sameValue = (left: unknown, right: unknown): boolean => formatValue(left)
 const samePaths = (left: ReadonlyArray<string>, right: ReadonlyArray<string>): boolean =>
   left.length === right.length && left.every((path, index) => path === right[index])
 
-const sameTrigger = (
-  left: Machine.Machine.TransitionTrigger,
-  right: Machine.Machine.TransitionTrigger
-): boolean =>
-  left.type === right.type && (left.type !== "event" || right.type === "event" && left.event === right.event)
-
 const makeNodeUtilities = (nodes: ReadonlyArray<PublicStateNode>) => {
   const byPath = new Map(nodes.map((node) => [node.path, node]))
   const depth = (path: string): number => {
@@ -1015,9 +989,10 @@ export const verify = <M extends AnyMachine>(
   options: VerifyOptions = {}
 ): Effect.Effect<void, VerificationError> => {
   const selected = new Set<VerificationLawGroup>(
-    options.laws ?? ["configuration", "microsteps", "completion", "history", "targetBounds"]
+    options.laws ?? ["configuration", "microsteps", "completion", "history", "definitions"]
   )
   const nodes = Machine.stateNodes(machine) as ReadonlyArray<PublicStateNode>
+  const initialDefinition = Machine.initialDefinition(machine)
   const definitions = Machine.transitionDefinitions(machine)
   const { ancestors, byPath, depth, isDescendantOrSelf } = makeNodeUtilities(nodes)
   const violations: Array<VerificationViolation> = []
@@ -1493,34 +1468,197 @@ export const verify = <M extends AnyMachine>(
       return direction === "entry" ? leftOrder - rightOrder : rightOrder - leftOrder
     })
 
-  const validateTransitionBounds = (
+  const transitionBranch = (
+    transition: Microstep<M>["transitions"][number]
+  ): Machine.Machine.TransitionBranch | undefined => {
+    const definition = definitions.find((candidate) =>
+      candidate.source === transition.source && candidate.reenter === transition.reenter &&
+      sameTransitionTrigger(candidate.trigger, transition.trigger)
+    )
+    return definition === undefined || !Number.isSafeInteger(transition.branchIndex) || transition.branchIndex < 0 ||
+        transition.branchIndex >= definition.branches.length
+      ? undefined
+      : definition.branches[transition.branchIndex]
+  }
+
+  const validateTransitionDefinition = (
     transition: Microstep<M>["transitions"][number],
     location: VerificationLocation
-  ): void => {
-    if (!selected.has("targetBounds")) return
+  ): Machine.Machine.TransitionBranch | undefined => {
+    if (!selected.has("definitions")) return undefined
     const definition = definitions.find((candidate) =>
       candidate.source === transition.source && candidate.reenter === transition.reenter &&
-      sameTrigger(candidate.trigger, transition.trigger)
+      sameTransitionTrigger(candidate.trigger, transition.trigger)
     )
     if (definition === undefined) {
       add(
-        "targetBounds.definition",
+        "definitions.transition",
         location,
         `retained transition from "${transition.source}" has no public definition`,
         transition.source
       )
-      return
+      return undefined
+    }
+    if (
+      !Number.isSafeInteger(transition.branchIndex) || transition.branchIndex < 0 ||
+      transition.branchIndex >= definition.branches.length
+    ) {
+      add(
+        "definitions.branchIndex",
+        location,
+        `retained transition from "${transition.source}" selected invalid branch index ${transition.branchIndex}`,
+        transition.source
+      )
+      return undefined
     }
-    if (transition.target === undefined || definition.targets.type === "dynamic") return
-    if (!definition.targets.paths.some((bound) => isDescendantOrSelf(String(transition.target), String(bound)))) {
+    const branch = definition.branches[transition.branchIndex]!
+    if (!targetWithinSelection(transition.target, branch, byPath)) {
+      const expected = branch.selection.kind === "none"
+        ? "an explicitly targetless result"
+        : `selection ${branch.selection.kind}:${branch.selection.scope}:${String(branch.selection.path)}`
       add(
-        "targetBounds.target",
+        "definitions.selection",
         location,
-        `transition target "${String(transition.target)}" is outside declared bounds ` +
-          `[${definition.targets.paths.join(", ")}]`,
-        String(transition.target)
+        `transition branch ${transition.branchIndex} from "${transition.source}" returned ` +
+          `target "${String(transition.target)}" outside ${expected}`,
+        transition.target === undefined ? transition.source : String(transition.target)
       )
     }
+    return branch
+  }
+
+  const validateTransitionResolutions = (
+    transitions: Microstep<M>["transitions"],
+    branches: ReadonlyArray<Machine.Machine.TransitionBranch | undefined>,
+    location: VerificationLocation
+  ): void => {
+    if (!selected.has("definitions")) return
+
+    const choiceResolution = (
+      start: string,
+      afterIndex: number,
+      nested: boolean
+    ): { readonly found: boolean; readonly target: string | undefined } => {
+      const seen = new Set<string>()
+      let choice = start
+      let cursor = afterIndex + 1
+      let first = true
+      while (!seen.has(choice)) {
+        seen.add(choice)
+        let choiceIndex = -1
+        for (let index = cursor; index < transitions.length; index++) {
+          const candidate = transitions[index]!
+          if (
+            candidate.trigger.type === "choice" &&
+            (candidate.source === choice || first && nested && isDescendantOrSelf(String(candidate.source), choice))
+          ) {
+            choiceIndex = index
+            break
+          }
+        }
+        if (choiceIndex === -1) return { found: false, target: undefined }
+        const transition = transitions[choiceIndex]!
+        if (branches[choiceIndex] === undefined) return { found: false, target: undefined }
+        const target = transition.target === undefined ? undefined : String(transition.target)
+        if (target === undefined) return { found: true, target: undefined }
+        const targetNode = byPath.get(target)
+        if (targetNode?.type === "choice") {
+          choice = target
+          cursor = choiceIndex + 1
+          first = false
+          continue
+        }
+        return {
+          found: true,
+          target: targetNode?.type === "history" ? targetNode.parent : target
+        }
+      }
+      return { found: false, target: undefined }
+    }
+
+    transitions.forEach((transition, index) => {
+      if (branches[index] === undefined) return
+      const target = transition.target === undefined ? undefined : String(transition.target)
+      const resolvedTarget = transition.resolvedTarget === undefined ? undefined : String(transition.resolvedTarget)
+      const targetNode = target === undefined ? undefined : byPath.get(target)
+      let expected = target
+      let explanation = target === undefined ? "an unresolved targetless transition" : `target "${target}"`
+
+      if (transition.trigger.type === "choice") {
+        explanation = target === undefined ? "a targetless choice edge" : `choice edge target "${target}"`
+      } else if (targetNode?.type === "history") {
+        expected = targetNode.parent
+        explanation = `history owner "${String(targetNode.parent)}"`
+      } else if (targetNode?.type === "choice") {
+        const resolution = choiceResolution(targetNode.path, index, false)
+        if (!resolution.found) {
+          add(
+            "definitions.resolution",
+            location,
+            `transition from "${transition.source}" targets choice "${target}" without an exact retained route`,
+            target
+          )
+          return
+        }
+        expected = resolution.target
+        explanation = expected === undefined ?
+          `targetless route from choice "${target}"` :
+          `choice route from "${target}" to "${expected}"`
+      } else if (
+        resolvedTarget !== target &&
+        (targetNode?.type === "compound" || targetNode?.type === "parallel")
+      ) {
+        const resolution = choiceResolution(targetNode.path, index, true)
+        if (resolution.found) {
+          expected = resolution.target
+          explanation = expected === undefined ?
+            `targetless nested choice route from "${target}"` :
+            `nested choice route from "${target}" to "${expected}"`
+        }
+      }
+
+      if (resolvedTarget !== expected) {
+        add(
+          "definitions.resolution",
+          location,
+          `transition branch ${transition.branchIndex} from "${transition.source}" resolved to ` +
+            `"${String(transition.resolvedTarget)}" instead of ${explanation}`,
+          resolvedTarget ?? target ?? String(transition.source)
+        )
+      }
+    })
+  }
+
+  const initialChoiceRouteRoot = (): string | undefined => {
+    const routing = trace.initial.plan.microsteps[0]
+    if (
+      routing === undefined || routing.changed ||
+      routing.transitions.length === 0 ||
+      !routing.transitions.every((transition) => transition.trigger.type === "choice")
+    ) {
+      return undefined
+    }
+
+    const reachableScopes: Array<string> = [initialDefinition.target]
+    let terminalRoot: string | undefined
+    for (const transition of routing.transitions) {
+      const source = String(transition.source)
+      const branch = transitionBranch(transition)
+      if (
+        branch === undefined || !targetWithinSelection(transition.target, branch, byPath) ||
+        !reachableScopes.some((scope) => isDescendantOrSelf(source, scope))
+      ) {
+        return undefined
+      }
+      const target = transition.target === undefined ? undefined : String(transition.target)
+      if (target === undefined) return undefined
+      const targetNode = byPath.get(target)
+      const scope = targetNode?.type === "history" ? targetNode.parent : target
+      if (scope === undefined) return undefined
+      reachableScopes.push(scope)
+      terminalRoot = ancestors(scope)[0]
+    }
+    return terminalRoot
   }
 
   const validateMicrostep = (
@@ -1675,7 +1813,8 @@ export const verify = <M extends AnyMachine>(
         }
       }
     }
-    for (const transition of microstep.transitions) validateTransitionBounds(transition, location)
+    const branches = microstep.transitions.map((transition) => validateTransitionDefinition(transition, location))
+    validateTransitionResolutions(microstep.transitions, branches, location)
   }
 
   const validatePlanCompletion = (
@@ -1711,6 +1850,24 @@ export const verify = <M extends AnyMachine>(
 
   const initialLocation: VerificationLocation = { eventIndex: undefined }
   const starting = inspectSnapshot(trace.initial.startingState, initialLocation, "initial starting state")
+  if (selected.has("definitions")) {
+    const startingRoots = starting.paths.filter((path) => byPath.get(path)?.parent === undefined)
+    const routedRoot = startingRoots.length === 1 && startingRoots[0] !== initialDefinition.target
+      ? initialChoiceRouteRoot()
+      : undefined
+    if (
+      startingRoots.length !== 1 ||
+      startingRoots[0] !== initialDefinition.target && startingRoots[0] !== routedRoot
+    ) {
+      add(
+        "definitions.initial",
+        initialLocation,
+        `initial starting state selected roots [${startingRoots.join(", ")}] without an exact route from ` +
+          `declared root "${initialDefinition.target}"`,
+        startingRoots[0] ?? initialDefinition.target
+      )
+    }
+  }
   validateSnapshotMetadata(starting, initialLocation, "initial starting state")
   validateTraceConfiguration(
     starting,
@@ -1845,6 +2002,7 @@ const formatMicrosteps = <M extends AnyMachine>(microsteps: ReadonlyArray<Micros
       source: transition.source,
       trigger: transition.trigger,
       reenter: transition.reenter,
+      branchIndex: transition.branchIndex,
       target: transition.target,
       resolvedTarget: transition.resolvedTarget
     }))

package/src/testing/MachineTest.ts

@@ -231,8 +231,20 @@ export interface Scenarios<M extends AnyMachine> {
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(Reset),
- *   initial: () => States.initial.Idle.from()
- * }).handle({ Idle: { on: { Reset: () => States.initial.Idle.from() } } })
+ *   initial: {
+ *     target: (to) => to.Idle(),
+ *     resolve: ({ target }) => target.from()
+ *   }
+ * }).handle({
+ *   Idle: {
+ *     on: {
+ *       Reset: Machine.transition({
+ *         target: (to) => to.full.Idle(),
+ *         resolve: ({ target }) => target.from()
+ *       })
+ *     }
+ *   }
+ * })
  *
  * const generated = MachineTest.scenarios(machine, { maxEvents: 5 })
  * ```
@@ -480,7 +492,10 @@ export { ProbeUnavailableError } from "../internal/testing/machine/verification.
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(),
- *   initial: () => States.initial.Idle.from()
+ *   initial: {
+ *     target: (to) => to.Idle(),
+ *     resolve: ({ target }) => target.from()
+ *   }
  * }).handle({ Idle: {} })
  *
  * const program = Effect.gen(function*() {
@@ -1090,7 +1105,10 @@ export const Invariant: {
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(),
- *   initial: () => States.initial.Count(new Count({ value: 0 }))
+ *   initial: {
+ *     target: (to) => to.Count(),
+ *     resolve: ({ target }) => target(new Count({ value: 0 }))
+ *   }
  * }).handle({ Count: {} })
  *
  * const nonNegative = MachineTest.invariants(machine).state(
@@ -1357,6 +1375,17 @@ export interface Exploration<M extends AnyMachine, Key extends ExplorationKey =
   readonly start: Graph.NodeIndex
   readonly limits: ResolvedExplorationLimits
   readonly stats: ExplorationStats
+  /**
+   * Exact declared transition branches witnessed by concretely planned work.
+   * This is observed evidence, not a claim that every reachable branch was
+   * explored. Startup and state-limit plans count; unplanned depth- and
+   * transition-limit frontiers do not.
+   */
+  readonly transitionCoverage: TransitionCoverage<
+    StateNodePath<M>,
+    Machine.Machine.TagOf<Machine.Machine.Events<M>[number]>,
+    StateNodePath<M>
+  >
   readonly completeness: ExplorationCompleteness<M, Key>
 }
 
@@ -1391,7 +1420,10 @@ export type ExploreOptions<M extends AnyMachine, Key extends ExplorationKey = Ex
  *
  * Invariants are checked against startup and every concretely planned edge,
  * so a failure retains a shortest discovered counterexample. Staged actions
- * and runtime activities are not executed.
+ * and runtime activities are not executed. `transitionCoverage` includes
+ * startup and every event plan that was actually computed, including a plan
+ * retained at a state-limit frontier. Depth- and transition-limit frontiers
+ * have no plan and therefore contribute no transition hits.
  *
  * **Example**
  *
@@ -1408,10 +1440,19 @@ export type ExploreOptions<M extends AnyMachine, Key extends ExplorationKey = Ex
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(Increment),
- *   initial: () => States.initial.Count(new Count({ value: 0 }))
+ *   initial: {
+ *     target: (to) => to.Count(),
+ *     resolve: ({ target }) => target(new Count({ value: 0 }))
+ *   }
  * }).handle({
- *   Count: { on: { Increment: ({ state }) =>
- *     States.initial.Count(new Count({ value: state.value + 1 })) } }
+ *   Count: {
+ *     on: {
+ *       Increment: Machine.transition({
+ *         target: (to) => to.full.Count(),
+ *         resolve: ({ state, target }) => target(new Count({ value: state.value + 1 }))
+ *       })
+ *     }
+ *   }
  * })
  *
  * const explored = MachineTest.explore(machine, {
@@ -1592,7 +1633,10 @@ export type RunServices<M extends AnyMachine> = IsAny<
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(),
- *   initial: () => States.initial.Idle.from()
+ *   initial: {
+ *     target: (to) => to.Idle(),
+ *     resolve: ({ target }) => target.from()
+ *   }
  * }).handle({ Idle: {} })
  *
  * const trace = MachineTest.run(machine, { events: [] })
@@ -1647,9 +1691,9 @@ export interface StateCoverage<Path extends string = string> {
  * One stable transition-definition identity in definition order.
  *
  * @category models
- * @since 0.4.0
+ * @since 0.14.0
  */
-export interface TransitionCoverageItem<
+export interface TransitionDefinitionCoverageItem<
   SourcePath extends string = string,
   EventTag extends PropertyKey = PropertyKey,
   TargetPath extends string = SourcePath
@@ -1659,7 +1703,43 @@ export interface TransitionCoverageItem<
   readonly source: SourcePath
   readonly trigger: Machine.Machine.TransitionTrigger<EventTag>
   readonly reenter: boolean
-  readonly targets: Machine.Machine.TransitionTargets<TargetPath>
+  readonly branches: ReadonlyArray<Machine.Machine.TransitionBranch<TargetPath>>
+}
+
+/**
+ * One statically declared transition branch together with its owning
+ * definition identity.
+ *
+ * @category models
+ * @since 0.14.0
+ */
+export interface TransitionBranchCoverageItem<
+  SourcePath extends string = string,
+  EventTag extends PropertyKey = PropertyKey,
+  TargetPath extends string = SourcePath
+> {
+  readonly id: string
+  readonly definitionIndex: number
+  readonly branchIndex: number
+  readonly source: SourcePath
+  readonly trigger: Machine.Machine.TransitionTrigger<EventTag>
+  readonly reenter: boolean
+  readonly branch: Machine.Machine.TransitionBranch<TargetPath>
+}
+
+/**
+ * Definition-level and exact branch-level transition coverage.
+ *
+ * @category models
+ * @since 0.14.0
+ */
+export interface TransitionCoverage<
+  SourcePath extends string = string,
+  EventTag extends PropertyKey = PropertyKey,
+  TargetPath extends string = SourcePath
+> {
+  readonly definitions: CoverageSummary<TransitionDefinitionCoverageItem<SourcePath, EventTag, TargetPath>>
+  readonly branches: CoverageSummary<TransitionBranchCoverageItem<SourcePath, EventTag, TargetPath>>
 }
 
 /**
@@ -1782,12 +1862,10 @@ export interface HistoryCoverageEvidence<Path extends string = string> {
  */
 export interface Coverage<M extends AnyMachine> {
   readonly states: StateCoverage<StatePath<M>>
-  readonly transitions: CoverageSummary<
-    TransitionCoverageItem<
-      StateNodePath<M>,
-      Machine.Machine.TagOf<Machine.Machine.Events<M>[number]>,
-      StateNodePath<M>
-    >
+  readonly transitions: TransitionCoverage<
+    StateNodePath<M>,
+    Machine.Machine.TagOf<Machine.Machine.Events<M>[number]>,
+    StateNodePath<M>
   >
   readonly events: EventCoverage<Machine.Machine.TagOf<Machine.Machine.InputEvents<M>[number]>>
   readonly scenarios: ScenarioCoverage
@@ -1802,10 +1880,10 @@ export interface Coverage<M extends AnyMachine> {
 }
 
 /**
- * Computes deterministic, definition-aware coverage from completed planner
- * traces. Finite declared sets report hits and misses; scenarios and logical
- * configurations report observations only because their complete spaces are
- * generally infinite.
+ * Computes deterministic, definition- and branch-aware coverage from
+ * completed planner traces. Finite declared sets report hits and misses;
+ * scenarios and logical configurations report observations only because their
+ * complete spaces are generally infinite.
  *
  * **Example**
  *
@@ -1819,7 +1897,10 @@ export interface Coverage<M extends AnyMachine> {
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(),
- *   initial: () => States.initial.Idle.from()
+ *   initial: {
+ *     target: (to) => to.Idle(),
+ *     resolve: ({ target }) => target.from()
+ *   }
  * }).handle({ Idle: {} })
  *
  * const report = Effect.map(
@@ -1946,7 +2027,7 @@ export type VerificationLawGroup =
   | "microsteps"
   | "completion"
   | "history"
-  | "targetBounds"
+  | "definitions"
 
 /**
  * Stable identifiers for individual planner laws.
@@ -1979,8 +2060,11 @@ export type VerificationLaw =
   | "history.value"
   | "history.shallow"
   | "history.deep"
-  | "targetBounds.definition"
-  | "targetBounds.target"
+  | "definitions.initial"
+  | "definitions.transition"
+  | "definitions.branchIndex"
+  | "definitions.selection"
+  | "definitions.resolution"
 
 /**
  * One independently observed violation in a planner trace.
@@ -2017,7 +2101,10 @@ export interface VerifyOptions {
 
 /**
  * Verifies an executed trace using only public machine inspection and raw
- * snapshot data. The verifier deliberately does not reuse planner
+ * snapshot data. Retained transitions are checked against their exact static
+ * branch, target selection, and resolved route. Startup is checked against
+ * the declared initial root or an exact retained initial-choice route. The
+ * verifier deliberately does not reuse planner
  * normalization, encoding, finality, or other internal helpers.
  *
  * Every selected law is evaluated and returned in one structured error so a
@@ -2035,7 +2122,10 @@ export interface VerifyOptions {
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(),
- *   initial: () => States.initial.Idle.from()
+ *   initial: {
+ *     target: (to) => to.Idle(),
+ *     resolve: ({ target }) => target.from()
+ *   }
  * }).handle({ Idle: {} })
  *
  * const checked = Effect.gen(function*() {

package/src/unstable/cluster/ClusterMachine.ts

@@ -316,7 +316,10 @@ export const layerMemory: Layer.Layer<Storage> = internal.layerMemory
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(),
- *   initial: () => States.initial.Idle.from()
+ *   initial: {
+ *     target: (to) => to.Idle(),
+ *     resolve: ({ target }) => target.from()
+ *   }
  * }).handle({ Idle: {} })
  *
  * const adapter = ClusterMachine.make("IdleMachine", machine, { version: "1" })