@typeonce/ritmo 0.8.0 → 0.9.0

package/src/Runtime.ts

@@ -23,7 +23,8 @@
  *   Game.Runtime.service(Random, { next: Math.random })
  * )
  *
- * // Viewport is a constructed resource, so the runtime comes back as a Result.
+ * // make always returns a Result. Viewport is a constructed resource, so
+ * // validating it can fail and the Result must be checked.
  * const runtime = Game.Runtime.make({
  *   services,
  *   resources: {
@@ -88,7 +89,8 @@ import type {
   ResourceChangedView,
   EventWriteView,
   LookupApi,
-  QueryHandle,
+  QueryIteration,
+  QueryLookups,
   RelationFailureReadView,
   RemovedReadView,
   TransitionEventReadView,
@@ -118,7 +120,7 @@ import type {
  *   services: Game.Runtime.services(
  *     Game.Runtime.service(Logger, { log: console.log })
  *   )
- * })
+ * }).value
  *
  * runtime.tick(updateSchedule)
  * ```
@@ -157,6 +159,17 @@ export type RuntimeResources<S extends Schema.Any> = Partial<{
       : Schema.ResourceValue<S, K>
 }>
 
+/**
+ * Rejects keys of `Provided` that are not resource keys of the schema, naming
+ * each one. A misspelled key next to known ones would otherwise compile and
+ * be dropped.
+ */
+export type ExactResources<S extends Schema.Any, Provided> = {
+  readonly [K in Exclude<keyof Provided, keyof Schema.Resources<S>>]: {
+    readonly __fixResources__: `${K & string} is not a resource key of this schema: use a key of the fragment's resources: { ... }`
+  }
+}
+
 type ConstructedKeys<S extends Schema.Any, Provided> = {
   readonly [K in keyof Provided]: K extends keyof Schema.Resources<S>
     ? Schema.Resources<S>[K] extends DescriptorModule.ConstructedDescriptor<"resource", string, any, any, any> ? K : never
@@ -193,8 +206,9 @@ export type WithDebug<R, Enabled, S extends Schema.Any, Root> =
   : R & Partial<Debug.Member<S, Root>>
 
 /**
- * The runtime returned by `make`, wrapped in a `Result` exactly when a
- * provided resource goes through a constructor and can therefore fail.
+ * What `make` returns: always a `Result`. It is a `Success` when nothing
+ * provided can fail, so `.value` is the runtime; when a provided resource
+ * goes through a constructor, it may be a `Failure` and must be checked.
  */
 export type MakeRuntimeResult<
   S extends Schema.Any,
@@ -204,7 +218,7 @@ export type MakeRuntimeResult<
   Machines extends Record<string, unknown>,
   Enabled = undefined
 > = [ConstructedKeys<S, Provided>] extends [never]
-  ? WithDebug<Runtime<S, Services, ProvidedResources<S, Provided>, Root, Machines>, Enabled, S, Root>
+  ? Result.Success<WithDebug<Runtime<S, Services, ProvidedResources<S, Provided>, Root, Machines>, Enabled, S, Root>>
   : Result.Result<
       WithDebug<Runtime<S, Services, ProvidedResources<S, Provided>, Root, Machines>, Enabled, S, Root>,
       RuntimeConstructionError<S, Provided>
@@ -637,12 +651,16 @@ export interface Runtime<
    * resources are skipped.
    *
    * Callable only when every component and resource is constructed or
-   * transient; see the `Snapshot` module.
+   * transient; see the `Snapshot` module. Take it between ticks: calling it
+   * while a schedule is running (from a system, a service, or a trace
+   * callback) throws.
    */
   readonly snapshot: Snapshot.Gate<S, () => Snapshot.WorldSnapshot>
   /**
    * Replaces the world with a snapshot after validating it against the
-   * schema. On failure nothing changes. See the `Snapshot` module.
+   * schema. On failure nothing changes. See the `Snapshot` module. Restore
+   * between ticks: calling it while a schedule is running throws. A current
+   * resource the save lacks keeps its value.
    */
   readonly restore: Snapshot.Gate<S, (data: unknown) => Result.Result<void, Snapshot.RestoreError>>
   /**
@@ -661,7 +679,7 @@ export interface Runtime<
    * The event must belong to the schema. Calling it while a schedule is
    * running is a defect and throws: inside a tick, emit from a system.
    */
-  readonly send: <D extends Schema.EventDescriptor<S>>(descriptor: D, value: Descriptor.Value<D>) => void
+  readonly send: <D extends Schema.EventDescriptor<S>>(descriptor: D, value: ReadonlyValue<Descriptor.Value<D>>) => void
 }
 
 /**
@@ -685,7 +703,7 @@ export interface Runtime<
  *   resources: {
  *     score: 0
  *   }
- * })
+ * }).value
  * ```
  */
 /**
@@ -696,6 +714,23 @@ export interface Runtime<
  */
 export const streamCapacity = 65_536
 
+/**
+ * Brings a parsed save to `migrations.latest`: runs every step after its
+ * game version, checking the structure after each.
+ */
+const migrateSave = (save: Snapshot.WorldSnapshot, saves: Snapshot.Migrations | undefined): Result.Result<Snapshot.WorldSnapshot, Snapshot.RestoreError> => {
+  const latest = saves?.latest ?? 0
+  if (save.gameVersion > latest) return Result.failure({ _tag: "NewerGameVersion", gameVersion: save.gameVersion, latest })
+  let current = save
+  for (const step of saves?.steps ?? []) {
+    if (step.to <= current.gameVersion) continue
+    const next = Snapshot.parse({ ...step.migrate(current), gameVersion: step.to })
+    if (!next.ok) return next
+    current = next.value
+  }
+  return Result.success(current)
+}
+
 const makeValidatedRuntime = <
   S extends Schema.Any,
   Services extends Record<string, unknown>,
@@ -710,6 +745,7 @@ const makeValidatedRuntime = <
   readonly machineDefinitions: ReadonlyArray<Machine.StateMachine.Any>
   readonly scopeDefinitions: ReadonlyArray<EntityScopeModule.EntityScope.Any>
   readonly debug: Debug.Option | undefined
+  readonly saves: Snapshot.Migrations | undefined
 }): Runtime<S, Services, Resources, Root, Machines> => {
   const world = makeWorld(options.schema, streamCapacity)
   const queries = makeQueryEngine(world)
@@ -724,7 +760,10 @@ const makeValidatedRuntime = <
    * Machine-keyed committed, pending, and previous values.
    */
   const currentMachines = new Map<symbol, unknown>()
-  const pendingMachines = new Map<symbol, { value: unknown; skipIfSame: boolean }>()
+  /** Queued next values; with `debug`, `by` is the system that queued it, for the `next-state-replaced` lint. */
+  const pendingMachines = new Map<symbol, { value: unknown; skipIfSame: boolean; by?: string }>()
+  /** Requests dropped because their sub-state stopped existing: skipped by the marker that queued them. */
+  const discardedPending = new WeakSet<object>()
   const previousMachines = new Map<symbol, unknown>()
   /**
    * Machine keys changed by transitions applied during the current schedule run.
@@ -886,6 +925,10 @@ const makeValidatedRuntime = <
    */
   const commandUses = new Map<string, Set<string>>()
   const ranSystems = new Set<string>()
+  /** With `debug`, the system running now: who queued a next state. */
+  let runningSystem = "(host)"
+  /** With `debug`, next states one system queued and another replaced before the marker. */
+  const nextStateReplacements = new Map<string, Debug.NextStateReplacement>()
   const noteCommand = (kind: string, name: string): void => {
     let uses = commandUses.get(commandOrigin)
     if (uses === undefined) {
@@ -925,6 +968,39 @@ const makeValidatedRuntime = <
       requirementViolations.set(key, { system: commandOrigin, command, component, missing, entity, count: (seen?.count ?? 0) + 1 })
     }
   }
+  const streamLosses = new Map<string, Debug.StreamLoss>()
+  const watchStreamLoss = <V extends { all(): unknown; lagged(): boolean }>(view: V, system: string, stream: string, paused: boolean): V => {
+    const key = `${system}/${stream}`
+    const entry = (): { -readonly [K in keyof Debug.StreamLoss]: Debug.StreamLoss[K] } => {
+      let found = streamLosses.get(key)
+      if (found === undefined) {
+        found = { system, stream, lostRuns: 0, checksLagged: false, paused }
+        streamLosses.set(key, found)
+      }
+      return found as { -readonly [K in keyof Debug.StreamLoss]: Debug.StreamLoss[K] }
+    }
+    return {
+      ...view,
+      all: () => {
+        const status = entry()
+        if (view.lagged()) status.lostRuns += 1
+        return view.all()
+      },
+      lagged: () => {
+        entry().checksLagged = true
+        return view.lagged()
+      }
+    }
+  }
+  const staleTargets = new Map<string, Debug.StaleTarget>()
+  const reportStaleTarget = (command: Debug.StaleTarget["command"], entity: number): void => {
+    if (tracing) recordEffect({ kind: "staleTarget", entity, command })
+    if (debugEnabled) {
+      const key = `${commandOrigin}/${command}`
+      const seen = staleTargets.get(key)
+      staleTargets.set(key, { system: commandOrigin, command, entity, count: (seen?.count ?? 0) + 1 })
+    }
+  }
   const holds = (id: number) => {
     const record = world.records.get(id)
     return (descriptor: Descriptor<"component", string, any>): boolean =>
@@ -1007,6 +1083,9 @@ const makeValidatedRuntime = <
         world.writeComponent(id, descriptor, value)
       }
     },
+    reportStaleTarget(command, id) {
+      reportStaleTarget(command, id)
+    },
     tryRelate(id, relation, target) {
       if (debugEnabled) {
         noteRelationMutation(relation)
@@ -1140,7 +1219,7 @@ const makeValidatedRuntime = <
     return lookup
   }
 
-  const makeQueryHandle = <Q extends Query.Query.Any<Root>>(query: Q, reader: ReaderState, lookup: LookupApi<S, Root>): QueryHandle<S, Q> => {
+  const makeQueryHandle = <Q extends Query.Query.Any<Root>>(query: Q, reader: ReaderState, lookup: LookupApi<S, Root>): QueryIteration<S, Q> & QueryLookups<S, Q> => {
     const each = () => queries.each(query, reader.since) as ReadonlyArray<QueryMatch<S, Q>>
     const matching = (ids: ReadonlyArray<Entity.EntityId<S, Root>>): Array<QueryMatch<S, Q>> => {
       const matches: Array<QueryMatch<S, Q>> = []
@@ -1198,6 +1277,32 @@ const makeValidatedRuntime = <
   const machineOriginals = new Map<symbol, { value: unknown; skipIfSame: boolean } | typeof absentValue>()
   const emittedEvents = new Map<symbol, Array<unknown>>()
 
+  /**
+   * The open phase, or `undefined`. A transition's exit phase (the exit
+   * schedules of the sub-states it ends and of the state it leaves, then its
+   * `onTransition` schedules) commits or rolls back as one: when one of its
+   * systems fails, the writes, events, queued next states, queued commands,
+   * and stream positions of the systems that ran before it are undone too, so
+   * the retry at a later marker starts from the same state.
+   */
+  interface Phase {
+    readonly tick: number
+    readonly commands: number
+    readonly origins: number
+    readonly resources: Map<symbol, unknown>
+    readonly resourceChangedAt: Map<symbol, number | undefined>
+    readonly machines: Map<symbol, { value: unknown; skipIfSame: boolean } | typeof absentValue>
+    readonly readers: Map<ReaderState, readonly [since: number, lastRun: number, streamSince: number, streamLastRun: number]>
+  }
+  let phase: Phase | undefined
+
+  /** Keeps a reader's position from before the phase, the first time the phase moves it. */
+  const journalReader = (reader: ReaderState): void => {
+    if (phase !== undefined && !phase.readers.has(reader)) {
+      phase.readers.set(reader, [reader.since, reader.lastRun, reader.streamSince, reader.streamLastRun])
+    }
+  }
+
   const journalStoreWrite = (store: Map<symbol, unknown>, originals: Map<symbol, unknown>) =>
     (key: symbol, value: unknown): void => {
       if (!originals.has(key)) {
@@ -1228,10 +1333,19 @@ const makeValidatedRuntime = <
 
   const commitSystemTransaction = (): void => {
     world.commitTransaction()
+    if (phase !== undefined) {
+      for (const [key, before] of resourceOriginals) {
+        if (!phase.resources.has(key)) phase.resources.set(key, before)
+      }
+      for (const [key, before] of machineOriginals) {
+        if (!phase.machines.has(key)) phase.machines.set(key, before)
+      }
+    }
     if (watchedResources.size > 0) {
       for (const [key, before] of resourceOriginals) {
         if (!watchedResources.has(key)) continue
         if (before === absentValue || !sameValue(before, resources.get(key))) {
+          if (phase !== undefined && !phase.resourceChangedAt.has(key)) phase.resourceChangedAt.set(key, resourceChangedAt.get(key))
           resourceChangedAt.set(key, world.currentTick())
         }
       }
@@ -1272,6 +1386,54 @@ const makeValidatedRuntime = <
     emittedEvents.clear()
   }
 
+  /**
+   * Runs `run` as one phase: on failure, or a thrown defect, everything the
+   * systems in it committed is undone.
+   */
+  const runAsPhase = (run: () => Result.Result<void, SystemFailure>): Result.Result<void, SystemFailure> => {
+    const opened: Phase = {
+      tick: world.currentTick(),
+      commands: pendingCommands.length,
+      origins: pendingOrigins.length,
+      resources: new Map(),
+      resourceChangedAt: new Map(),
+      machines: new Map(),
+      readers: new Map()
+    }
+    phase = opened
+    world.beginPhase()
+    let result: Result.Result<void, SystemFailure> | undefined
+    try {
+      result = run()
+    } finally {
+      phase = undefined
+      if (result?.ok === true) {
+        world.commitPhase()
+      } else {
+        world.rollbackPhase()
+        restoreStore(resources, opened.resources)
+        for (const [key, value] of opened.machines) {
+          if (value === absentValue) pendingMachines.delete(key)
+          else pendingMachines.set(key, value)
+        }
+        for (const [key, tick] of opened.resourceChangedAt) {
+          if (tick === undefined) resourceChangedAt.delete(key)
+          else resourceChangedAt.set(key, tick)
+        }
+        for (const [reader, [since, lastRun, streamSince, streamLastRun]] of opened.readers) {
+          reader.since = since
+          reader.lastRun = lastRun
+          reader.streamSince = streamSince
+          reader.streamLastRun = streamLastRun
+        }
+        events.retract(opened.tick)
+        pendingCommands.length = opened.commands
+        pendingOrigins.length = opened.origins
+      }
+    }
+    return result
+  }
+
   const makeResourceWriteView = (
     descriptor: Descriptor<"resource", string, any>,
     store: Map<symbol, unknown>,
@@ -1371,7 +1533,23 @@ const makeValidatedRuntime = <
       } satisfies Machine.SubStateInactive) as Machine.SetResult<M>
     }
     journalMachine(stateMachine.key)
-    pendingMachines.set(stateMachine.key, { value, skipIfSame })
+    if (debugEnabled) {
+      const previous = pendingMachines.get(stateMachine.key)
+      // A set from a transition schedule waits for the next marker: it replaces nothing queued for this one.
+      if (previous?.by !== undefined && previous.by !== runningSystem && previous.value !== value && activeTransitions.size === 0) {
+        const key = `${stateMachine.name}/${previous.by}/${runningSystem}/${String(previous.value)}/${String(value)}`
+        const seen = nextStateReplacements.get(key)
+        nextStateReplacements.set(key, {
+          machine: stateMachine.name,
+          replaced: { system: previous.by, value: previous.value as Machine.StateValue },
+          by: { system: runningSystem, value: value as Machine.StateValue },
+          count: (seen?.count ?? 0) + 1
+        })
+      }
+      pendingMachines.set(stateMachine.key, { value, skipIfSame, by: runningSystem })
+    } else {
+      pendingMachines.set(stateMachine.key, { value, skipIfSame })
+    }
     return (within === undefined ? undefined : succeeded) as Machine.SetResult<M>
   }
 
@@ -1433,9 +1611,14 @@ const makeValidatedRuntime = <
   const makeContext = (system: SystemDefinition<any, any, any>, reader: ReaderState, queue: Command.CommandQueue<S, Root>): SystemContext<any> => {
     const spec = system.spec
     const lookup = makeLookup(reader)
+    const paused = (spec.pauseWhen as ReadonlyArray<unknown>).length > 0
+    /** On a debug runtime, records reads after a loss and calls of `lagged()`, for the `stream-loss-unread` lint. */
+    const watch = <V extends { all(): unknown; lagged(): boolean }>(view: V, stream: string): V =>
+      debugEnabled ? watchStreamLoss(view, system.name, stream, paused) : view
     return {
       local: (spec.local as (() => unknown) | undefined)?.(),
-      queries: mapRecord(spec.queries as Record<string, Query.Query.Any<Root>>, (query) => makeQueryHandle(query, reader, lookup)),
+      // A filtered query hands out the same object; its type hides the lookups.
+      queries: mapRecord(spec.queries as Record<string, Query.Query.Any<Root>>, (query) => makeQueryHandle(query, reader, lookup) as never),
       lookup,
       resources: mapRecord(spec.resources as Record<string, any>, (access) =>
         access.mode === "read"
@@ -1445,15 +1628,15 @@ const makeValidatedRuntime = <
             : makeResourceWriteView(access.descriptor, resources, writeResource)),
       events: mapRecord(spec.events as Record<string, any>, (access) =>
         access.mode === "read"
-          ? makeEventReadView(access.descriptor.key, reader)
+          ? watch(makeEventReadView(access.descriptor.key, reader), `events ${access.descriptor.name}`)
           : makeEventWriteView(access.descriptor.key)),
       machines: mapRecord(spec.machines as Record<string, any>, (access) => makeMachineReadView(access.machine)),
       nextMachines: mapRecord(spec.nextMachines as Record<string, any>, (access) => makeNextMachineWriteView(access.machine)),
-      transitionEvents: mapRecord(spec.transitionEvents as Record<string, any>, (access) => makeTransitionEventReadView(access.machine, reader)),
+      transitionEvents: mapRecord(spec.transitionEvents as Record<string, any>, (access) => watch(makeTransitionEventReadView(access.machine, reader), `transition events ${access.machine.name}`)),
       transitions: mapRecord(spec.transitions as Record<string, any>, (access) => makeTransitionReadView(access.machine)),
-      removed: mapRecord(spec.removed as Record<string, any>, (access) => makeRemovedReadView(access.descriptor, reader)),
-      despawned: mapRecord(spec.despawned as Record<string, any>, () => makeDespawnedReadView(reader)),
-      relationFailures: mapRecord(spec.relationFailures as Record<string, any>, (access) => makeRelationFailureReadView(access.relation, reader)),
+      removed: mapRecord(spec.removed as Record<string, any>, (access) => watch(makeRemovedReadView(access.descriptor, reader), `removed ${access.descriptor.name}`)),
+      despawned: mapRecord(spec.despawned as Record<string, any>, () => watch(makeDespawnedReadView(reader), "despawned")),
+      relationFailures: mapRecord(spec.relationFailures as Record<string, any>, (access) => watch(makeRelationFailureReadView(access.relation, reader), `relation failures ${access.relation.name}`)),
       services: mapRecord(spec.services as Record<string, any>, (access) =>
         providedServices[access.descriptor.name as keyof Services]),
       // The queue serves every declared permission set; the spec's types narrow it.
@@ -1646,6 +1829,7 @@ const makeValidatedRuntime = <
         // neither holds them nor receives a backlog when it runs again.
         const skipped = slotOf(system, true)
         if (tracing) traceSkipped(system, condition, skipped.reader, false)
+        journalReader(skipped.reader)
         skipped.reader.streamLastRun = world.currentTick()
         return succeeded
       }
@@ -1661,7 +1845,11 @@ const makeValidatedRuntime = <
       }
     }
     const { context, commands, reader } = slotOf(system, true)
-    if (debugEnabled) ranSystems.add(system.name)
+    if (debugEnabled) {
+      ranSystems.add(system.name)
+      runningSystem = system.name
+    }
+    journalReader(reader)
     // Changes stamped after the previous completed run are visible to this run.
     reader.since = reader.lastRun
     reader.streamSince = reader.streamLastRun
@@ -1833,11 +2021,17 @@ const makeValidatedRuntime = <
 
     const schedules = bundle?.entries ?? []
     for (const [machineKey, pending] of scheduledTransitions) {
-      if (pendingMachines.get(machineKey) !== pending) {
+      if (discardedPending.has(pending)) {
         // Discarded earlier in this marker: its parent left the state it exists in.
         continue
       }
-      pendingMachines.delete(machineKey)
+      // A transition schedule earlier in this marker may have queued a newer
+      // value for this machine: that one waits for the next marker.
+      if (pendingMachines.get(machineKey) === pending) pendingMachines.delete(machineKey)
+      /** Keeps this request queued after a failure, unless a newer one replaced it. */
+      const requeue = () => {
+        if (!pendingMachines.has(machineKey)) pendingMachines.set(machineKey, pending)
+      }
       const current = currentMachines.get(machineKey)
       if (current === undefined) {
         continue
@@ -1855,48 +2049,44 @@ const makeValidatedRuntime = <
       // Sub-states that exist in the state being left exit first, deepest
       // first: their exit schedules run before the parent's, while they
       // still have their values, and they lose them at the parent's commit.
+      // The exit phase is one transaction: a failure undoes all of it, and
+      // the transition stays queued for a later attempt.
       const leaving = activeSubStatesIn(machineKey, snapshot.from)
-      for (const sub of leaving) {
-        const value = currentMachines.get(sub.key)
-        const result = runPhase(sub.key, "exit", value, { from: value, to: undefined } as unknown as Machine.TransitionSnapshot, schedules)
-        if (!result.ok) {
-          pendingMachines.set(machineKey, pending)
-          if (tracing) traceTransition(machineKey, snapshot, "failed")
-          return result
-        }
-      }
-
-      for (const schedule of schedules) {
-        const transition = schedule.transition
-        if (transition.phase === "exit" && transition.machine.key === machineKey && transition.state === snapshot.from) {
-          const result = runTransitionSchedule(schedule, snapshot)
-          if (!result.ok) {
-            // The transition did not happen; keep it queued for a later attempt.
-            pendingMachines.set(machineKey, pending)
-            if (tracing) traceTransition(machineKey, snapshot, "failed")
-            return result
-          }
+      const exited = runAsPhase(() => {
+        for (const sub of leaving) {
+          const value = currentMachines.get(sub.key)
+          const result = runPhase(sub.key, "exit", value, { from: value, to: undefined } as unknown as Machine.TransitionSnapshot, schedules)
+          if (!result.ok) return result
         }
-      }
-      for (const schedule of schedules) {
-        const transition = schedule.transition
-        if (
-          transition.phase === "transition"
-          && transition.machine.key === machineKey
-          && transition.from === snapshot.from
-          && transition.to === snapshot.to
-        ) {
-          const result = runTransitionSchedule(schedule, snapshot)
-          if (!result.ok) {
-            pendingMachines.set(machineKey, pending)
-            if (tracing) traceTransition(machineKey, snapshot, "failed")
-            return result
+        const left = runPhase(machineKey, "exit", snapshot.from, snapshot, schedules)
+        if (!left.ok) return left
+        for (const schedule of schedules) {
+          const transition = schedule.transition
+          if (
+            transition.phase === "transition"
+            && transition.machine.key === machineKey
+            && transition.from === snapshot.from
+            && transition.to === snapshot.to
+          ) {
+            const result = runTransitionSchedule(schedule, snapshot)
+            if (!result.ok) return result
           }
         }
+        return succeeded
+      })
+      if (!exited.ok) {
+        requeue()
+        if (tracing) traceTransition(machineKey, snapshot, "failed")
+        return exited
       }
 
       for (const sub of leaving) commitMachine(sub.key, currentMachines.get(sub.key), undefined)
       commitMachine(machineKey, current, pending.value)
+      // Sub-states that exist in the entered state enter their value together
+      // with the parent, parents first, before any onEnter schedule runs: a
+      // failing onEnter cannot leave them without a value, and their scope
+      // triggers fire before what the onEnter schedules spawn.
+      const entered = commitSubStates(machineKey, snapshot.to)
 
       for (const schedule of schedules) {
         const transition = schedule.transition
@@ -1908,9 +2098,8 @@ const makeValidatedRuntime = <
           }
         }
       }
-      // Sub-states that exist in the entered state enter their value, parents first.
-      const entered = enterSubStates(machineKey, snapshot.to, schedules)
-      if (!entered.ok) return entered
+      const enteredSchedules = runSubStateEnters(entered, schedules)
+      if (!enteredSchedules.ok) return enteredSchedules
     }
     return succeeded
   }
@@ -1925,6 +2114,8 @@ const makeValidatedRuntime = <
     if (from !== undefined) previousMachines.set(machineKey, from)
     if (to === undefined) {
       currentMachines.delete(machineKey)
+      const discarded = pendingMachines.get(machineKey)
+      if (discarded !== undefined) discardedPending.add(discarded)
       pendingMachines.delete(machineKey)
     } else {
       currentMachines.set(machineKey, to)
@@ -1968,22 +2159,28 @@ const makeValidatedRuntime = <
 
   /**
    * Gives the sub-states of `parentKey` that exist in `state` their entry
-   * value, then runs their `onEnter` schedules and enters their own
-   * sub-states.
+   * value, and theirs, parents first. Returns what it entered, in that order.
    */
-  const enterSubStates = (parentKey: symbol, state: unknown, schedules: TransitionSchedules): Result.Result<void, SystemFailure> => {
+  const commitSubStates = (parentKey: symbol, state: unknown): Array<readonly [symbol, unknown]> => {
+    const entered: Array<readonly [symbol, unknown]> = []
     for (const sub of subStates.get(parentKey) ?? []) {
       if (sub.within!.state !== state || currentMachines.has(sub.key) || !subStateEntry.has(sub.key)) continue
       const value = subStateEntry.get(sub.key)
       commitMachine(sub.key, undefined, value)
+      entered.push([sub.key, value], ...commitSubStates(sub.key, value))
+    }
+    return entered
+  }
+
+  /** Runs the onEnter schedules of sub-states entered by {@link commitSubStates}, in that order. */
+  const runSubStateEnters = (entered: ReadonlyArray<readonly [symbol, unknown]>, schedules: TransitionSchedules): Result.Result<void, SystemFailure> => {
+    for (const [key, value] of entered) {
       const snapshot = { from: undefined, to: value } as unknown as Machine.TransitionSnapshot
-      const result = runPhase(sub.key, "enter", value, snapshot, schedules)
+      const result = runPhase(key, "enter", value, snapshot, schedules)
       if (!result.ok) {
-        if (tracing) traceTransition(sub.key, snapshot, "enterFailed")
+        if (tracing) traceTransition(key, snapshot, "enterFailed")
         return result
       }
-      const nested = enterSubStates(sub.key, value, schedules)
-      if (!nested.ok) return nested
     }
     return succeeded
   }
@@ -2020,8 +2217,14 @@ const makeValidatedRuntime = <
     return succeeded
   }
 
-  /** Whether a schedule is running now: `send` is not allowed meanwhile. */
+  /** Whether `runtime.tick` is on the stack: a nested `tick` is a defect. */
   let ticking = false
+  /**
+   * Whether a tick is advancing its frame or running its schedules (in
+   * `tick` and `tryTick`): `send`, `snapshot`, and `restore` are defects
+   * meanwhile. It is cleared before `tick.end` is announced to host listeners.
+   */
+  let inTick = false
 
   /**
    * Runs one schedule. A failing system stops the schedule; systems that
@@ -2045,7 +2248,7 @@ const makeValidatedRuntime = <
   let hostEvents = new Set<string>()
 
   const send = (descriptor: Descriptor<"event", string, any>, value: unknown): void => {
-    if (ticking) throw new Error(`runtime.send(${descriptor.name}) was called while a schedule is running: emit from a system instead`)
+    if (inTick) throw new Error(`runtime.send(${descriptor.name}) was called while a schedule is running: emit from a system instead`)
     if (!eventsByKey.has(descriptor.key)) throw new Error(`runtime.send: ${descriptor.name} is not an event of this runtime's schema`)
     const published = world.advanceTick()
     events.append(descriptor.key, published, [value], true)
@@ -2116,6 +2319,7 @@ const makeValidatedRuntime = <
     if (ticking) throw new Error("runtime.tick cannot run inside another tick")
     if (debugEnabled) reportUnread("next-tick")
     ticking = true
+    inTick = true
     try {
       advanceFrame()
       return watchResult(observedTick(schedules, () => {
@@ -2127,6 +2331,7 @@ const makeValidatedRuntime = <
       }), schedules)
     } finally {
       ticking = false
+      inTick = false
     }
   }
 
@@ -2141,9 +2346,11 @@ const makeValidatedRuntime = <
     try {
       result = run()
     } catch (defect) {
+      inTick = false
       emitHost({ type: "tick.end", schedules, frame: frameCount, outcome: "defect", error: defect })
       throw defect
     }
+    inTick = false
     emitHost(result.ok
       ? { type: "tick.end", schedules, frame: frameCount, outcome: "ok" }
       : { type: "tick.end", schedules, frame: frameCount, outcome: "failed", error: result.error })
@@ -2182,8 +2389,14 @@ const makeValidatedRuntime = <
       return watchResult(Result.failure({ kind: "TickOrderViolation" as const, issues }), [schedule])
     }
 
-    advanceFrame()
-    return watchResult(observedTick([schedule], () => runScheduleUnsafe(schedule)), [schedule]) as Result.Result<void, Schedule.FailureOf<Selected>>
+    if (inTick) throw new Error("runtime.tryTick cannot run inside another tick")
+    inTick = true
+    try {
+      advanceFrame()
+      return watchResult(observedTick([schedule], () => runScheduleUnsafe(schedule)), [schedule]) as Result.Result<void, Schedule.FailureOf<Selected>>
+    } finally {
+      inTick = false
+    }
   }
 
   /**
@@ -2220,6 +2433,7 @@ const makeValidatedRuntime = <
   for (const provision of machineEntries) machinesByName.set(provision.machine.name, provision.machine)
 
   const snapshot = (): Snapshot.WorldSnapshot => {
+    if (inTick) throw new Error("runtime.snapshot was called while a schedule is running: it would capture writes a failing system rolls back; take it between ticks")
     const savedResources: Record<string, unknown> = {}
     for (const [name, descriptor] of resourcesByName) {
       if (!DescriptorModule.isTransient(descriptor) && resources.has(descriptor.key)) {
@@ -2238,6 +2452,7 @@ const makeValidatedRuntime = <
     }
     return {
       version: Snapshot.version,
+      gameVersion: options.saves?.latest ?? 0,
       nextEntity: world.nextEntityValue(),
       entities: world.exportEntities(DescriptorModule.isTransient),
       relations: world.exportRelations(),
@@ -2255,7 +2470,9 @@ const makeValidatedRuntime = <
   const restore = (data: unknown): Result.Result<void, Snapshot.RestoreError> => {
     const parsed = Snapshot.parse(data)
     if (!parsed.ok) return parsed
-    const saved = parsed.value
+    const migrated = migrateSave(parsed.value, options.saves)
+    if (!migrated.ok) return migrated
+    const saved = migrated.value
 
     // Validate everything before touching the world.
     const ids = new Set<number>()
@@ -2343,6 +2560,7 @@ const makeValidatedRuntime = <
     const scoped = new Set<number>()
     const memberships: Array<readonly [number, symbol]> = []
     for (const [name, members] of Object.entries(saved.scopes)) {
+      if (!options.scopeDefinitions.some((scope) => scope.name === name)) return Result.failure({ _tag: "UnknownScope", name })
       for (const id of members) {
         if (!ids.has(id) || scoped.has(id)) return Result.failure({ _tag: "InvalidScope", name, entityId: id })
         scoped.add(id)
@@ -2382,6 +2600,7 @@ const makeValidatedRuntime = <
   }
 
   const tracedRestore = (data: unknown): Result.Result<void, Snapshot.RestoreError> => {
+    if (inTick) throw new Error("runtime.restore was called while a schedule is running: the running systems' queued commands would land on the restored world; restore between ticks")
     const result = restore(data)
     if (tracing) emit({ type: "restore", frame: frameCount, tick: world.currentTick(), ok: result.ok })
     return result
@@ -2533,6 +2752,9 @@ const makeValidatedRuntime = <
       commandUses,
       ranSystems,
       requirementViolations: [...requirementViolations.values()],
+      nextStateReplacements: [...nextStateReplacements.values()],
+      staleTargets: [...staleTargets.values()],
+      streamLosses: [...streamLosses.values()],
       hasResource: (descriptor) => resources.has(descriptor.key),
       schedules: [...scheduleNames].map(([schedule, name]) => [name, schedule as ExecutableScheduleDefinition<S>] as const)
     }),
@@ -2573,8 +2795,9 @@ const makeValidatedRuntime = <
  * Creates a runtime for a fully built schema and a set of external services.
  *
  * Resources owned by constructed descriptors take raw input and are validated
- * here; when any are provided the runtime comes back as a `Result`. Otherwise
- * the runtime is returned directly.
+ * here. The runtime always comes back as a `Result`: typed `Success` when
+ * nothing provided can fail (read `.value`), and a `Result` to check when a
+ * constructed resource is provided.
  *
  * The runtime does not own the outer frame loop. It only owns ECS state plus
  * the host-provided services that systems are allowed to depend on.
@@ -2587,7 +2810,7 @@ const makeValidatedRuntime = <
  *   ),
  *   resources: { Score: 0 },
  *   machines: Game.Runtime.machines(Game.Runtime.machine(Flow, "Menu"))
- * })
+ * }).value
  * ```
  */
 export const make = <
@@ -2600,19 +2823,16 @@ export const make = <
 >(options: {
   readonly schema: S
   readonly services: ProvidedServices
-  readonly resources?: Resources
+  readonly resources?: Resources & ExactResources<S, Resources>
   readonly machines?: ProvidedMachines
   readonly machineDefinitions?: ReadonlyArray<Machine.StateMachine.Any>
   /** Scopes whose members a committed state change despawns; `Game.Runtime.make` passes every `Game.EntityScope`. */
   readonly scopeDefinitions?: ReadonlyArray<EntityScopeModule.EntityScope.Any>
   /** Attaches a `debug` handle to the runtime, timed by `hostClock`; see the `Debug` module. */
   readonly debug?: Enabled
+  /** The game's save migrations (`Snapshot.migrations`), applied by `restore`. */
+  readonly saves?: Snapshot.Migrations
 }): MakeRuntimeResult<S, Simplify<RuntimeServicesOf<ProvidedServices>>, Resources, Root, RuntimeMachinesOf<ProvidedMachines>, Enabled> => {
-  const fallible = Object.entries(options.schema.resources).some(([key, descriptor]) =>
-    options.resources !== undefined
-    && (options.resources as Record<string, unknown>)[key] !== undefined
-    && DescriptorModule.hasConstructor(descriptor)
-  )
   const validated = collectConstructedRegistryValues(options.schema.resources, options.resources)
   if (!validated.ok) {
     return Result.failure({ resources: validated.error }) as never
@@ -2624,9 +2844,43 @@ export const make = <
     machines: options.machines,
     machineDefinitions: options.machineDefinitions ?? [],
     scopeDefinitions: options.scopeDefinitions ?? [],
-    debug: options.debug
+    debug: options.debug,
+    saves: options.saves
   })
-  return (fallible ? Result.success(runtime) : runtime) as never
+  return Result.success(runtime) as never
+}
+
+/** Names listed more than once in `Names` (a tuple), in order of their second listing. */
+type RepeatedNames<Names extends ReadonlyArray<string>, Seen extends string = never> =
+  Names extends readonly [infer Head extends string, ...infer Tail extends ReadonlyArray<string>]
+    ? (string extends Head ? never : Head extends Seen ? Head : never) | RepeatedNames<Tail, Seen | Head>
+    : never
+
+type ProvidedServiceNames<Entries extends ReadonlyArray<ServiceProvision>> = {
+  readonly [K in keyof Entries]: Entries[K] extends ServiceProvision<infer D> ? D["name"] : string
+}
+type ProvidedMachineNames<Entries extends ReadonlyArray<MachineProvision>> = {
+  readonly [K in keyof Entries]: Entries[K] extends MachineProvision<infer M> ? M["name"] : string
+}
+
+/** Rejects a service provided twice: only the last would be used. */
+type UniqueServices<Entries extends ReadonlyArray<ServiceProvision>> =
+  [RepeatedNames<ProvidedServiceNames<Entries>>] extends [never] ? unknown : {
+    readonly __fixServices__: `${RepeatedNames<ProvidedServiceNames<Entries>>} is provided twice: keep one Game.Runtime.service(...) for it`
+  }
+
+/** Rejects a machine started twice: only the last initial value would be used. */
+type UniqueMachines<Entries extends ReadonlyArray<MachineProvision>> =
+  [RepeatedNames<ProvidedMachineNames<Entries>>] extends [never] ? unknown : {
+    readonly __fixMachines__: `${RepeatedNames<ProvidedMachineNames<Entries>>} is provided twice: keep one Game.Runtime.machine(...) for it`
+  }
+
+const rejectRepeated = (names: ReadonlyArray<string>, kind: "service" | "machine"): void => {
+  const seen = new Set<string>()
+  for (const name of names) {
+    if (seen.has(name)) throw new Error(`${name} is provided twice: keep one Game.Runtime.${kind}(...) for it`)
+    seen.add(name)
+  }
 }
 
 /**
@@ -2638,6 +2892,8 @@ export const make = <
  *
  * The helper keeps the runtime map keyed by service descriptors instead of
  * ad hoc strings, so the provision site cannot drift from the declaration site.
+ * Each service is provided once: a second provision of the same one does not
+ * compile.
  *
  * @example
  * ```ts
@@ -2650,7 +2906,8 @@ export const make = <
  */
 export const services = <
   const Entries extends ReadonlyArray<ServiceProvision>
->(...entries: Entries): RuntimeServices<ServiceEntriesToRecord<Entries>> => {
+>(...entries: Entries & UniqueServices<Entries>): RuntimeServices<ServiceEntriesToRecord<Entries>> => {
+  rejectRepeated(entries.map((entry) => entry.descriptor.name), "service")
   const provided: Record<string, unknown> = {}
   for (const { descriptor, implementation } of entries) {
     provided[descriptor.name] = implementation
@@ -2680,11 +2937,14 @@ export const service = <
  * Builds the machine initialization environment from machine definitions.
  *
  * Use this when gameplay phases need a known committed starting state before
- * any schedule runs, for example `"Boot"`, `"Menu"`, or `"Playing"`.
+ * any schedule runs, for example `"Boot"`, `"Menu"`, or `"Playing"`. Each
+ * machine is provided once: a second provision of the same one does not
+ * compile.
  */
 export const machines = <
   const Entries extends ReadonlyArray<MachineProvision>
->(...entries: Entries): RuntimeMachines<MachineEntriesToRecord<Entries>> => {
+>(...entries: Entries & UniqueMachines<Entries>): RuntimeMachines<MachineEntriesToRecord<Entries>> => {
+  rejectRepeated(entries.map((entry) => entry.machine.name), "machine")
   const provided: Record<string, unknown> = {}
   for (const { machine, initial } of entries) {
     provided[machine.name] = initial