@typeonce/ritmo 0.7.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: {
@@ -63,8 +64,10 @@ import type { Descriptor } from "./Descriptor.ts"
 import type * as Entity from "./Entity.ts"
 import type * as Inspector from "./Inspector.ts"
 import * as Cells from "./internal/cells.ts"
+import { sameValue } from "./internal/equal.ts"
 import * as DebugInternal from "./internal/debug.ts"
 import { makeQueryEngine } from "./internal/queries.ts"
+import { requirementIndex } from "./internal/requirements.ts"
 import * as Streams from "./internal/streams.ts"
 import { ABSENT, makeWorld } from "./internal/world.ts"
 import type { WorldHooks } from "./internal/world.ts"
@@ -83,9 +86,11 @@ import type { Registry, Schema } from "./Schema.ts"
 import type {
   DespawnedReadView,
   EventReadView,
+  ResourceChangedView,
   EventWriteView,
   LookupApi,
-  QueryHandle,
+  QueryIteration,
+  QueryLookups,
   RelationFailureReadView,
   RemovedReadView,
   TransitionEventReadView,
@@ -115,7 +120,7 @@ import type {
  *   services: Game.Runtime.services(
  *     Game.Runtime.service(Logger, { log: console.log })
  *   )
- * })
+ * }).value
  *
  * runtime.tick(updateSchedule)
  * ```
@@ -154,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
@@ -190,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,
@@ -201,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>
@@ -634,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>>
   /**
@@ -658,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
 }
 
 /**
@@ -682,7 +703,7 @@ export interface Runtime<
  *   resources: {
  *     score: 0
  *   }
- * })
+ * }).value
  * ```
  */
 /**
@@ -693,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>,
@@ -705,7 +743,9 @@ const makeValidatedRuntime = <
   readonly resources: Partial<Record<string, unknown>>
   readonly machines: RuntimeMachines<any> | undefined
   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)
@@ -720,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.
@@ -801,8 +844,48 @@ const makeValidatedRuntime = <
     options.machineDefinitions.map((machine, index) => [machine.key, index] as const)
   )
 
+  /** Machines the runtime was given an initial value for. */
+  const providedMachineKeys = new Set<symbol>()
   for (const provision of machineEntries) {
     currentMachines.set(provision.machine.key, provision.initial)
+    providedMachineKeys.add(provision.machine.key)
+  }
+
+  /**
+   * Sub-states by parent machine key, in definition order, and the value
+   * each enters whenever its parent enters the state it exists in (its
+   * runtime-provided value). A sub-state has no current value while its
+   * parent is elsewhere, and never one when the runtime does not provide it.
+   */
+  const subStates = new Map<symbol, Array<Machine.StateMachine.Any>>()
+  const subStateEntry = new Map<symbol, unknown>()
+  for (const machine of options.machineDefinitions) {
+    if (machine.within === undefined) continue
+    const siblings = subStates.get(machine.within.machine.key)
+    if (siblings === undefined) subStates.set(machine.within.machine.key, [machine])
+    else siblings.push(machine)
+    if (!currentMachines.has(machine.key)) continue
+    subStateEntry.set(machine.key, currentMachines.get(machine.key))
+  }
+  // Definition order puts a parent before its sub-states, so a sub-state of
+  // an inactive sub-state is cleared too.
+  for (const machine of options.machineDefinitions) {
+    if (machine.within !== undefined && currentMachines.get(machine.within.machine.key) !== machine.within.state) {
+      currentMachines.delete(machine.key)
+    }
+  }
+
+  /**
+   * Scope despawn triggers by machine key, in scope definition order
+   * (`Game.EntityScope(name, { despawnOnExit, despawnOnEnter })`).
+   */
+  const scopeTriggers = new Map<symbol, Array<{ readonly trigger: EntityScopeModule.Trigger; readonly scope: EntityScopeModule.EntityScope.Any }>>()
+  for (const scope of options.scopeDefinitions) {
+    for (const trigger of scope.despawnOn) {
+      const triggers = scopeTriggers.get(trigger.machine.key)
+      if (triggers === undefined) scopeTriggers.set(trigger.machine.key, [{ trigger, scope }])
+      else triggers.push({ trigger, scope })
+    }
   }
 
   const appendRelationFailure = (
@@ -842,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) {
@@ -859,13 +946,96 @@ const makeValidatedRuntime = <
     systems.add(commandOrigin)
   }
 
+  /**
+   * `Schema.requires`, checked when commands are applied. Types reject a
+   * breaking command when they can see it; this catches the rest: a query
+   * proof gone stale within one flush (another system's command applied in
+   * between), erased types, and raw ids. A breaking command is skipped
+   * whole, traced, and reported by the `requirement-violated` lint.
+   */
+  const requirements = requirementIndex(options.schema)
+  /** With `debug`, skipped commands by system, command, and requirement, for the lint. */
+  const requirementViolations = new Map<string, Debug.RequirementViolation>()
+  const violateRequirement = (
+    command: Debug.RequirementViolation["command"],
+    entity: number,
+    [component, missing]: readonly [string, string]
+  ): void => {
+    if (tracing) recordEffect({ kind: "requirementViolated", entity, command, component, missing })
+    if (debugEnabled) {
+      const key = `${commandOrigin}/${command}/${component}/${missing}`
+      const seen = requirementViolations.get(key)
+      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 =>
+      record !== undefined && world.has(record, world.ordinalOf(descriptor))
+  }
+  /** The first requirement `components` break, as `[requirer, missing]`. */
+  const missingIn = (
+    components: ReadonlyArray<Entity.StagedComponent>,
+    alsoHeld: (descriptor: Descriptor<"component", string, any>) => boolean
+  ): readonly [string, string] | undefined => {
+    for (const [descriptor] of components) {
+      for (const required of requirements.requires.get(descriptor.name) ?? []) {
+        if (!alsoHeld(required) && !components.some(([staged]) => staged.name === required.name)) {
+          return [descriptor.name, required.name]
+        }
+      }
+    }
+    return undefined
+  }
+
   /**
    * World adapter used by deferred commands.
    */
   const commandWorld: Command.InternalWorld<S> = {
     spawnEntity(id, components) {
+      if (!requirements.empty) {
+        const missing = missingIn(components, () => false)
+        if (missing !== undefined) {
+          violateRequirement("spawn", id, missing)
+          return false
+        }
+      }
       if (debugEnabled) for (const [descriptor] of components) noteCommand("spawns", descriptor.name)
       world.spawnEntity(id, components)
+      return true
     },
     destroyEntity(id) {
       if (debugEnabled) {
@@ -883,13 +1053,38 @@ const makeValidatedRuntime = <
       if (debugEnabled) noteCommand("despawnsScope", scope.name)
       world.destroyEntityScope(scope.key)
     },
-    removeComponent(id, descriptor) {
-      if (debugEnabled) noteCommand("removes", descriptor.name)
-      world.removeComponent(id, descriptor)
+    removeComponents(id, descriptors) {
+      if (!requirements.empty && world.records.has(id)) {
+        const held = holds(id)
+        for (const descriptor of descriptors) {
+          for (const requirer of requirements.requiredBy.get(descriptor.name) ?? []) {
+            if (held(requirer) && !descriptors.some((removed) => removed.name === requirer.name)) {
+              violateRequirement("remove", id, [requirer.name, descriptor.name])
+              return
+            }
+          }
+        }
+      }
+      for (const descriptor of descriptors) {
+        if (debugEnabled) noteCommand("removes", descriptor.name)
+        world.removeComponent(id, descriptor)
+      }
+    },
+    insertComponents(id, entries) {
+      if (!requirements.empty && world.records.has(id)) {
+        const missing = missingIn(entries, holds(id))
+        if (missing !== undefined) {
+          violateRequirement("insert", id, missing)
+          return
+        }
+      }
+      for (const [descriptor, value] of entries) {
+        if (debugEnabled) noteCommand("inserts", descriptor.name)
+        world.writeComponent(id, descriptor, value)
+      }
     },
-    writeComponent(id, descriptor, value) {
-      if (debugEnabled) noteCommand("inserts", descriptor.name)
-      world.writeComponent(id, descriptor, value)
+    reportStaleTarget(command, id) {
+      reportStaleTarget(command, id)
     },
     tryRelate(id, relation, target) {
       if (debugEnabled) {
@@ -1024,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>> = []
@@ -1082,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)) {
@@ -1091,6 +1312,15 @@ const makeValidatedRuntime = <
     }
   const writeResource = journalStoreWrite(resources, resourceOriginals)
 
+  /**
+   * Resource change ticks for `changedResource` readers. Only resources some
+   * system reads with `changedResource` are compared at commit; a reader's
+   * first run reports a change anyway, so writes before it registers are not
+   * needed.
+   */
+  const watchedResources = new Set<symbol>()
+  const resourceChangedAt = new Map<symbol, number>()
+
   const journalMachine = (key: symbol): void => {
     if (!machineOriginals.has(key)) {
       machineOriginals.set(key, pendingMachines.get(key) ?? absentValue)
@@ -1103,6 +1333,23 @@ 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())
+        }
+      }
+    }
     if (emittedEvents.size > 0) {
       const published = world.advanceTick()
       for (const [key, values] of emittedEvents) {
@@ -1139,12 +1386,71 @@ 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>,
     write: (key: symbol, value: unknown) => void
   ) => Cells.storeWrite(store, descriptor.key, write, DescriptorModule.constructorOf(descriptor))
 
+  const makeResourceChangedView = (descriptor: Descriptor<"resource", string, any>, reader: ReaderState): ResourceChangedView<unknown> => {
+    const key = descriptor.key
+    watchedResources.add(key)
+    const read = Cells.storeRead(resources, key)
+    return {
+      get: () => read.get(),
+      // `since` is the previous completed run; 0 before the first one.
+      changed: () => reader.since === 0 || (resourceChangedAt.get(key) ?? 0) > reader.since
+    }
+  }
+
   const makeEventReadView = <T>(descriptorKey: symbol, reader: ReaderState): EventReadView<T> => ({
     all() {
       return events.since(descriptorKey, reader.streamSince) as ReadonlyArray<ReadonlyValue<T>>
@@ -1211,19 +1517,49 @@ const makeValidatedRuntime = <
   })
 
   const makeMachineReadView = <M extends Machine.StateMachine.Any>(stateMachine: M): MachineReadView<M> => ({
-    get: () => currentMachines.get(stateMachine.key) as Machine.StateMachine.Value<M>,
+    get: () => currentMachines.get(stateMachine.key) as Machine.CurrentValue<M>,
     is: (value) => currentMachines.get(stateMachine.key) === value
   })
 
+  /** Queues a next value; a sub-state whose parent is in another state queues nothing and fails. */
+  const queueMachine = <M extends Machine.StateMachine.Any>(stateMachine: M, value: unknown, skipIfSame: boolean): Machine.SetResult<M> => {
+    const within = stateMachine.within
+    if (within !== undefined && !currentMachines.has(stateMachine.key)) {
+      return Result.failure({
+        _tag: "SubStateInactive",
+        machine: stateMachine.name,
+        parent: within.machine.name,
+        requires: within.state
+      } satisfies Machine.SubStateInactive) as Machine.SetResult<M>
+    }
+    journalMachine(stateMachine.key)
+    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>
+  }
+
   const makeNextMachineWriteView = <M extends Machine.StateMachine.Any>(stateMachine: M): NextMachineWriteView<M> => ({
     getPending: () => pendingMachines.get(stateMachine.key)?.value as Machine.StateMachine.Value<M> | undefined,
     set(value) {
-      journalMachine(stateMachine.key)
-      pendingMachines.set(stateMachine.key, { value, skipIfSame: false })
+      return queueMachine(stateMachine, value, false)
     },
     setIfChanged(value) {
-      journalMachine(stateMachine.key)
-      pendingMachines.set(stateMachine.key, { value, skipIfSame: true })
+      return queueMachine(stateMachine, value, true)
     },
     reset() {
       journalMachine(stateMachine.key)
@@ -1275,25 +1611,32 @@ 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"
           ? Cells.storeRead(resources, access.descriptor.key)
-          : makeResourceWriteView(access.descriptor, resources, writeResource)),
+          : access.mode === "changed"
+            ? makeResourceChangedView(access.descriptor, reader)
+            : 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.
@@ -1486,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
       }
@@ -1501,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
@@ -1626,6 +1974,36 @@ const makeValidatedRuntime = <
     }
   }
 
+  /**
+   * Despawns the scopes whose trigger matches a committed transition: leaving
+   * `snapshot.from` or entering `snapshot.to`. It runs right after the
+   * commit, so `onExit` systems still saw the members and entities spawned by
+   * `onEnter` survive. Members are the entities in the scope at that moment:
+   * commands queued by `onExit` systems and not yet applied are not.
+   */
+  const despawnTriggeredScopes = (machineKey: symbol, snapshot: Machine.TransitionSnapshot): void => {
+    const triggers = scopeTriggers.get(machineKey)
+    if (triggers === undefined) return
+    const applied: Array<Debug.AppliedCommand> = []
+    for (const { trigger, scope } of triggers) {
+      const matches = trigger.phase === "exit" ? trigger.state === snapshot.from : trigger.state === snapshot.to
+      if (!matches) continue
+      const origin = `${trigger.phase === "exit" ? "onExit" : "onEnter"}(${trigger.machine.name}=${String(trigger.state)})`
+      const effects: Array<Debug.Effect> = []
+      commandEffects = tracing ? effects : undefined
+      commandOrigin = origin
+      try {
+        commandWorld.destroyEntityScope(scope)
+      } finally {
+        commandEffects = undefined
+      }
+      if (tracing) applied.push({ tag: `despawnScope ${scope.name}`, system: origin, effects })
+    }
+    if (applied.length > 0) {
+      emit({ type: "deferred", frame: frameCount, tick: world.currentTick(), schedule: currentSchedule(), marker: "applyStateTransitions", commands: applied })
+    }
+  }
+
   /**
    * Applies queued commands, then queued machine transitions, running the
    * matching exit, transition, and enter schedules from the bundle.
@@ -1643,7 +2021,17 @@ const makeValidatedRuntime = <
 
     const schedules = bundle?.entries ?? []
     for (const [machineKey, pending] of scheduledTransitions) {
-      pendingMachines.delete(machineKey)
+      if (discardedPending.has(pending)) {
+        // Discarded earlier in this marker: its parent left the state it exists in.
+        continue
+      }
+      // 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
@@ -1653,45 +2041,52 @@ const makeValidatedRuntime = <
         continue
       }
 
-      previousMachines.set(machineKey, current)
       const snapshot = {
         from: current as Machine.StateValue,
         to: pending.value as Machine.StateValue
       }
 
-      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
-          }
+      // 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)
+      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
       }
 
-      currentMachines.set(machineKey, pending.value)
-      changedMachines.add(machineKey)
-      transitionEvents.append(machineKey, world.advanceTick(), [snapshot])
-      if (tracing) traceTransition(machineKey, snapshot, "applied")
+      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
@@ -1703,6 +2098,89 @@ const makeValidatedRuntime = <
           }
         }
       }
+      const enteredSchedules = runSubStateEnters(entered, schedules)
+      if (!enteredSchedules.ok) return enteredSchedules
+    }
+    return succeeded
+  }
+
+  /**
+   * Commits one machine's value (`undefined` for a sub-state that stops
+   * existing): records the change and its transition event, traces it, and
+   * despawns the scopes it triggers.
+   */
+  const commitMachine = (machineKey: symbol, from: unknown, to: unknown): void => {
+    const snapshot = { from, to } as unknown as Machine.TransitionSnapshot
+    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)
+    }
+    changedMachines.add(machineKey)
+    transitionEvents.append(machineKey, world.advanceTick(), [snapshot])
+    if (tracing) traceTransition(machineKey, snapshot, "applied")
+    despawnTriggeredScopes(machineKey, snapshot)
+  }
+
+  type TransitionSchedules = ReadonlyArray<Machine.StateMachine.AnyTransitionSchedule<S, Root>>
+
+  /** Runs every schedule of `phase` for `machineKey` in `state`, in bundle order. */
+  const runPhase = (
+    machineKey: symbol,
+    phase: "enter" | "exit",
+    state: unknown,
+    snapshot: Machine.TransitionSnapshot,
+    schedules: TransitionSchedules
+  ): Result.Result<void, SystemFailure> => {
+    for (const schedule of schedules) {
+      const transition = schedule.transition
+      if (transition.phase === phase && transition.machine.key === machineKey && transition.state === state) {
+        const result = runTransitionSchedule(schedule, snapshot)
+        if (!result.ok) return result
+      }
+    }
+    return succeeded
+  }
+
+  /** The sub-states with a value that exist in `state` of `parentKey`, and theirs, deepest first. */
+  const activeSubStatesIn = (parentKey: symbol, state: unknown): Array<Machine.StateMachine.Any> => {
+    const result: Array<Machine.StateMachine.Any> = []
+    for (const sub of subStates.get(parentKey) ?? []) {
+      const value = currentMachines.get(sub.key)
+      if (sub.within!.state !== state || value === undefined) continue
+      result.push(...activeSubStatesIn(sub.key, value), sub)
+    }
+    return result
+  }
+
+  /**
+   * Gives the sub-states of `parentKey` that exist in `state` their entry
+   * value, and theirs, parents first. Returns what it entered, in that order.
+   */
+  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(key, "enter", value, snapshot, schedules)
+      if (!result.ok) {
+        if (tracing) traceTransition(key, snapshot, "enterFailed")
+        return result
+      }
     }
     return succeeded
   }
@@ -1739,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
@@ -1764,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)
@@ -1835,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, () => {
@@ -1846,6 +2331,7 @@ const makeValidatedRuntime = <
       }), schedules)
     } finally {
       ticking = false
+      inTick = false
     }
   }
 
@@ -1860,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 })
@@ -1876,7 +2364,8 @@ const makeValidatedRuntime = <
       case "resource":
         return resources.has(requirement.key)
       case "stateMachine":
-        return currentMachines.has(requirement.key)
+        // An inactive sub-state has no value but is provided.
+        return providedMachineKeys.has(requirement.key) || currentMachines.has(requirement.key)
     }
   }
 
@@ -1900,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
+    }
   }
 
   /**
@@ -1938,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)) {
@@ -1956,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(),
@@ -1973,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>()
@@ -1992,6 +2491,11 @@ const makeValidatedRuntime = <
         if (!value.ok) return Result.failure({ _tag: "InvalidComponent", entityId: entity.id, name, error: value.error })
         components.push([descriptor, value.value])
       }
+      // Transient components are never saved, so a requirement on one is not checked here.
+      const missing = missingIn(components, DescriptorModule.isTransient)
+      if (missing !== undefined) {
+        return Result.failure({ _tag: "MissingRequiredComponent", entityId: entity.id, name: missing[1], requiredBy: missing[0] })
+      }
       entities.push({ id: entity.id, components })
     }
     const validatedResources: Array<readonly [symbol, unknown]> = []
@@ -2028,17 +2532,35 @@ const makeValidatedRuntime = <
         }
       }
     }
-    const machineValues: Array<readonly [symbol, Machine.StateValue]> = []
+    const restoredMachines = new Map(currentMachines)
     for (const [name, value] of Object.entries(saved.machines)) {
       const machine = machinesByName.get(name)
       if (!machine) return Result.failure({ _tag: "UnknownMachine", name })
       if (!machine.values.includes(value)) return Result.failure({ _tag: "InvalidMachineState", name, value })
-      machineValues.push([machine.key, value])
+      restoredMachines.set(machine.key, value)
+    }
+    // A save has no value for a sub-state whose parent is elsewhere; one that
+    // has a value must have its parent in the state it exists in. A sub-state
+    // missing while its parent is there enters its entry value.
+    for (const machine of options.machineDefinitions) {
+      const within = machine.within
+      if (within === undefined) continue
+      const active = restoredMachines.get(within.machine.key) === within.state
+      if (Object.hasOwn(saved.machines, machine.name)) {
+        if (!active) {
+          return Result.failure({ _tag: "InactiveSubState", name: machine.name, parent: within.machine.name, requires: within.state })
+        }
+      } else if (active && subStateEntry.has(machine.key)) {
+        restoredMachines.set(machine.key, subStateEntry.get(machine.key))
+      } else {
+        restoredMachines.delete(machine.key)
+      }
     }
 
     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)
@@ -2066,14 +2588,19 @@ const makeValidatedRuntime = <
       world.tryRelate(source, relation, target)
     }
     for (const [id, key] of memberships) world.assignEntityScope(id, key)
-    for (const [key, value] of validatedResources) resources.set(key, value)
-    for (const [key, value] of machineValues) currentMachines.set(key, value)
+    for (const [key, value] of validatedResources) {
+      resources.set(key, value)
+      resourceChangedAt.set(key, world.currentTick())
+    }
+    currentMachines.clear()
+    for (const [key, value] of restoredMachines) currentMachines.set(key, value)
     // Locals are not saved: each system starts over from its factory.
     localSlots.forEach(({ slot }, index) => { (slot.context as { local: unknown }).local = rebuiltLocals[index] })
     return succeeded
   }
 
   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
@@ -2217,11 +2744,17 @@ const makeValidatedRuntime = <
       schema: options.schema,
       machines: [...new Set(machinesByName.values())],
       currentMachine: (machine) => currentMachines.get(machine.key) as Machine.StateValue | undefined,
+      providesMachine: (machine) => providedMachineKeys.has(machine.key),
+      scopes: options.scopeDefinitions,
       providedServices: Object.keys(providedServices),
       externallyWrittenEvents: new Set([...externallyWrittenEvents, ...hostEvents]),
       relationMutations,
       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)
     }),
@@ -2262,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.
@@ -2276,7 +2810,7 @@ const makeValidatedRuntime = <
  *   ),
  *   resources: { Score: 0 },
  *   machines: Game.Runtime.machines(Game.Runtime.machine(Flow, "Menu"))
- * })
+ * }).value
  * ```
  */
 export const make = <
@@ -2289,17 +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
@@ -2310,9 +2843,44 @@ export const make = <
     resources: validated.value,
     machines: options.machines,
     machineDefinitions: options.machineDefinitions ?? [],
-    debug: options.debug
+    scopeDefinitions: options.scopeDefinitions ?? [],
+    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)
+  }
 }
 
 /**
@@ -2324,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
@@ -2336,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
@@ -2366,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