@typeonce/ritmo 0.6.0 → 0.8.0

package/src/Runtime.ts

@@ -55,6 +55,7 @@
  * @groupDescription Functions
  * Public runtime constructors and helpers for services, machines, and bootstrap input.
  */
+import * as HostClockModule from "./HostClock.ts"
 import * as Command from "./Command.ts"
 import type * as Debug from "./Debug.ts"
 import * as DescriptorModule from "./Descriptor.ts"
@@ -62,8 +63,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"
@@ -74,13 +77,15 @@ import * as Relation from "./Relation.ts"
 import type * as Requirement from "./Requirement.ts"
 import * as Result from "./Result.ts"
 import * as Schedule from "./Schedule.ts"
+import * as OrderInternal from "./internal/order.ts"
 import * as EntityScopeModule from "./EntityScope.ts"
 import * as Snapshot from "./Snapshot.ts"
-import type { ExecutableScheduleDefinition } from "./Schedule.ts"
+import type { AnyScheduleOrder, ExecutableScheduleDefinition } from "./Schedule.ts"
 import type { Registry, Schema } from "./Schema.ts"
 import type {
   DespawnedReadView,
   EventReadView,
+  ResourceChangedView,
   EventWriteView,
   LookupApi,
   QueryHandle,
@@ -179,10 +184,13 @@ export type RuntimeConstructionError<S extends Schema.Any, Provided> = Simplify<
 }>
 
 /**
- * A runtime plus the `debug` handle when it was made with `debug: true`.
+ * A runtime plus the `debug` handle when it was made with `debug: { hostClock }`
+ * (optional when the option may be `undefined`).
  */
 export type WithDebug<R, Enabled, S extends Schema.Any, Root> =
-  [Enabled] extends [Debug.Option] ? R & Debug.Member<S, Root> : R
+  [Enabled] extends [undefined] ? R
+  : [Enabled] extends [Debug.Option] ? R & Debug.Member<S, Root>
+  : R & Partial<Debug.Member<S, Root>>
 
 /**
  * The runtime returned by `make`, wrapped in a `Result` exactly when a
@@ -367,23 +375,23 @@ type RequirementErrorsFor<
   : never
 
 type RequirementErrorsOfSchedule<
-  Selected extends ExecutableScheduleDefinition<any, any, any, any, any>,
+  Selected extends ExecutableScheduleDefinition<any, any, any, any, any, AnyScheduleOrder>,
   Services extends Record<string, unknown>,
   Resources extends object,
   Machines extends object
-> = Selected extends ExecutableScheduleDefinition<infer S, any, any, any, any>
+> = Selected extends ExecutableScheduleDefinition<infer S, any, any, any, any, AnyScheduleOrder>
   ? RequirementErrorsFor<Requirement.Of<Selected>, S, Services, Resources, Machines>
   : never
 
 export type ValidateSchedules<
-  Schedules extends ReadonlyArray<ExecutableScheduleDefinition<any, any, any, any, any>>,
+  Schedules extends ReadonlyArray<ExecutableScheduleDefinition<any, any, any, any, any, AnyScheduleOrder>>,
   Services extends Record<string, unknown>,
   Resources extends object,
   Machines extends object
 > = {
   readonly [K in keyof Schedules]:
     Schedules[K] & ValidateSchedule<
-      Extract<Schedules[K], ExecutableScheduleDefinition<any, any, any, any, any>>,
+      Extract<Schedules[K], ExecutableScheduleDefinition<any, any, any, any, any, AnyScheduleOrder>>,
       Services,
       Resources,
       Machines
@@ -391,7 +399,7 @@ export type ValidateSchedules<
 }
 
 export type ValidateScheduleArray<
-  Schedules extends ReadonlyArray<ExecutableScheduleDefinition<any, any, any, any, any>>,
+  Schedules extends ReadonlyArray<ExecutableScheduleDefinition<any, any, any, any, any, AnyScheduleOrder>>,
   Services extends Record<string, unknown>,
   Resources extends object,
   Machines extends object
@@ -402,18 +410,23 @@ export type ValidateScheduleArray<
     }
 
 type ValidateScheduleArgs<
-  Schedules extends ReadonlyArray<ExecutableScheduleDefinition<any, any, any, any, any>>,
+  Schedules extends ReadonlyArray<ExecutableScheduleDefinition<any, any, any, any, any, AnyScheduleOrder>>,
   Services extends Record<string, unknown>,
   Resources extends object,
   Machines extends object
 > = [RequirementErrorsOfSchedule<NoInfer<Schedules[number]>, Services, Resources, Machines>] extends [never]
-  ? Schedules
+  ? [Schedule.TickOrderErrors<NoInfer<Schedules>>] extends [never]
+    ? Schedules
+    : Schedules & {
+        /** `Game.System.thisTick` reads whose writers do not all run earlier in this call. */
+        readonly __fixTickOrder__: Schedule.TickOrderErrors<NoInfer<Schedules>>
+      }
   : Schedules & {
       readonly __fixRuntimeRequirements__: RequirementErrorsOfSchedule<NoInfer<Schedules[number]>, Services, Resources, Machines>
     }
 
 type ValidateSchedule<
-  Schedule extends ExecutableScheduleDefinition<any, any, any, any, any>,
+  Schedule extends ExecutableScheduleDefinition<any, any, any, any, any, AnyScheduleOrder>,
   Services extends Record<string, unknown>,
   Resources extends object,
   Machines extends object
@@ -432,7 +445,13 @@ type RequirementErrorsOfInspector<
   ? RequirementErrorsFor<Needs, Spec["schema"], Services, Resources, Machines>
   : never
 
-type ValidateInspector<
+/**
+ * Resolves to `unknown` when the runtime provides every resource, service,
+ * and machine the inspector reads, otherwise to an object naming each
+ * missing or incompatible one. `runtime.inspect(...)` uses it; tools that
+ * run inspectors on a runtime they receive (devtools invariants) reuse it.
+ */
+export type ValidateInspector<
   Selected extends Inspector.Inspector.Any,
   Services extends Record<string, unknown>,
   Resources extends object,
@@ -451,6 +470,15 @@ export interface MissingRuntimeRequirement {
   readonly name: string
 }
 
+/**
+ * Returned by `tryTick` when a `Game.System.thisTick` read has a writer that
+ * runs after it in the schedule. Nothing ran.
+ */
+export interface TickOrderViolation {
+  readonly kind: "TickOrderViolation"
+  readonly issues: ReadonlyArray<Schedule.OrderIssue>
+}
+
 /** Explicit failure returned by the dynamic schedule execution path. */
 export interface MissingRuntimeRequirements {
   readonly kind: "MissingRuntimeRequirements"
@@ -584,20 +612,22 @@ export interface Runtime<
    * system's ECS writes are rolled back and earlier systems stay committed.
    */
   readonly tick: {
-    <const Schedules extends ReadonlyArray<ExecutableScheduleDefinition<S, any, Root, any, any>>>(
+    <const Schedules extends ReadonlyArray<ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>>>(
       ...schedules: ValidateScheduleArgs<Schedules, Services, Resources, Machines>
     ): Result.Result<void, Schedule.FailureOf<Schedules[number]>>
   }
   /**
-   * Runs a schedule whose exact requirements are not statically known, for
-   * example one loaded through a plugin boundary.
+   * Runs a schedule whose exact requirements are not statically known: for
+   * tools that hold schedules with erased types, such as devtools sessions.
+   * Games use `tick(...)`, which rejects missing requirements at compile time.
    *
    * Requirements are checked against current provisioning first and missing
-   * ones are returned as data.
+   * ones are returned as data, then `Game.System.thisTick` reads are checked
+   * against the schedule's order (`TickOrderViolation`).
    */
-  readonly tryTick: <const Selected extends ExecutableScheduleDefinition<S, any, any, any, any>>(
+  readonly tryTick: <const Selected extends ExecutableScheduleDefinition<S, any, any, any, any, AnyScheduleOrder>>(
     schedule: Selected
-  ) => Result.Result<void, MissingRuntimeRequirements | Schedule.FailureOf<Selected>>
+  ) => Result.Result<void, MissingRuntimeRequirements | TickOrderViolation | Schedule.FailureOf<Selected>>
   /**
    * Captures the world as plain data: entities with their ids, components,
    * relation edges, resources, and committed machine values.
@@ -678,7 +708,8 @@ const makeValidatedRuntime = <
   readonly resources: Partial<Record<string, unknown>>
   readonly machines: RuntimeMachines<any> | undefined
   readonly machineDefinitions: ReadonlyArray<Machine.StateMachine.Any>
-  readonly debug: boolean
+  readonly scopeDefinitions: ReadonlyArray<EntityScopeModule.EntityScope.Any>
+  readonly debug: Debug.Option | undefined
 }): Runtime<S, Services, Resources, Root, Machines> => {
   const world = makeWorld(options.schema, streamCapacity)
   const queries = makeQueryEngine(world)
@@ -723,12 +754,12 @@ const makeValidatedRuntime = <
   const pendingCommands: Array<Command.DeferredCommand<S>> = []
 
   /**
-   * Debug state. With `debug: true`, `pendingOrigins` names the system that
+   * Debug state. With `debug`, `pendingOrigins` names the system that
    * queued each pending command, in step with `pendingCommands`. Tracing is
    * on only while `observe` listeners are registered; untraced runs pay one
    * boolean check at each system, schedule, and marker boundary.
    */
-  const debugEnabled = options.debug
+  const debugEnabled = options.debug !== undefined
   const pendingOrigins: Array<string> = []
   const traceListeners = new Set<(event: Debug.TraceEvent) => void>()
   let tracing = false
@@ -740,7 +771,9 @@ const makeValidatedRuntime = <
   const scheduleNames = new Map<object, string>()
   const anonymousScheduleNames = new WeakMap<object, string>()
   let anonymousScheduleCount = 0
-  const now = (): number => performance.now()
+  // Only a debug runtime times anything; the clock is the one it was given.
+  const hostClock: HostClockModule.HostClock = options.debug?.hostClock ?? { now: () => 0 }
+  const now = (): number => hostClock.now()
   const emit = (event: Debug.TraceEvent): void => {
     for (const listener of traceListeners) listener(event)
   }
@@ -772,8 +805,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 = (
@@ -797,29 +870,148 @@ const makeValidatedRuntime = <
     ])
   }
 
+  /**
+   * With `debug`, the relations commands have tried to relate or
+   * reorder, with the systems that queued those commands, for the
+   * `relation-failure-never-read` lint. `commandOrigin` names the system whose
+   * command is being applied.
+   */
+  const relationMutations = new Map<string, Set<string>>()
+  let commandOrigin = "(unknown)"
+  /**
+   * With `debug`, what each system's applied commands did, as
+   * `kind:name` (`spawns:Enemy`, `despawns:Enemy` for every component the
+   * despawned entity had), and the systems that ran: for the
+   * `command-permission-unused` lint.
+   */
+  const commandUses = new Map<string, Set<string>>()
+  const ranSystems = new Set<string>()
+  const noteCommand = (kind: string, name: string): void => {
+    let uses = commandUses.get(commandOrigin)
+    if (uses === undefined) {
+      uses = new Set()
+      commandUses.set(commandOrigin, uses)
+    }
+    uses.add(`${kind}:${name}`)
+  }
+  const noteRelationMutation = (relation: Relation.Relation.Any): void => {
+    let systems = relationMutations.get(relation.name)
+    if (systems === undefined) {
+      systems = new Set()
+      relationMutations.set(relation.name, systems)
+    }
+    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 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) {
+        const record = world.records.get(id)
+        record?.values.forEach((value, ordinal) => {
+          if (value !== ABSENT) noteCommand("despawns", world.descriptorAt(ordinal).name)
+        })
+      }
       world.destroyEntity(id)
     },
     assignEntityScope(id, scope) {
       world.assignEntityScope(id, scope.key)
     },
     destroyEntityScope(scope) {
+      if (debugEnabled) noteCommand("despawnsScope", scope.name)
       world.destroyEntityScope(scope.key)
     },
-    removeComponent(id, descriptor) {
-      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)
+      }
     },
-    writeComponent(id, descriptor, value) {
-      world.writeComponent(id, descriptor, value)
+    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)
+      }
     },
     tryRelate(id, relation, target) {
+      if (debugEnabled) {
+        noteRelationMutation(relation)
+        noteCommand("relates", relation.name)
+      }
       const result = world.tryRelate(id, relation, target)
       if (!result.ok) {
         appendRelationFailure(relation, "relate", id, target, result.error)
@@ -827,9 +1019,14 @@ const makeValidatedRuntime = <
       return result
     },
     unrelate(id, relation) {
+      if (debugEnabled) noteCommand("relates", relation.name)
       world.unrelate(id, relation)
     },
     reorderChildren(id, relation, children) {
+      if (debugEnabled) {
+        noteRelationMutation(relation)
+        noteCommand("relates", relation.name)
+      }
       const result = world.reorderChildren(id, relation, children.map((child) => child))
       if (!result.ok) {
         const targetId = result.error._tag === "MissingChildEntity"
@@ -882,12 +1079,6 @@ const makeValidatedRuntime = <
 
   const makeLookup = (reader: ReaderState): LookupApi<S, Root> => {
     const lookup: LookupApi<S, Root> = {
-    get(target, query) {
-      return resolve(target, query, reader)
-    },
-    getHandle(handle, query) {
-      return resolve(handle, query, reader)
-    },
     related: relatedTarget,
     relatedSources(target, relation) {
       if (!world.records.has(target)) {
@@ -895,19 +1086,6 @@ const makeValidatedRuntime = <
       }
       return Result.success(world.relatedSourceIds(relation, target).map(entityId))
     },
-    childMatches(target, relation, query) {
-      if (!world.records.has(target)) {
-        return Result.failure(Relation.missingEntityError(target))
-      }
-      const matches: Array<QueryMatch<S, typeof query>> = []
-      for (const sourceId of world.relatedSourceIds(relation, target)) {
-        const resolved = resolve(sourceId, query, reader)
-        if (resolved.ok) {
-          matches.push(resolved.value)
-        }
-      }
-      return Result.success(matches)
-    },
     parent: relatedTarget,
     ancestors(target, relation) {
       if (!world.records.has(target)) {
@@ -946,20 +1124,6 @@ const makeValidatedRuntime = <
       }
       return Result.success(descendants)
     },
-    descendantMatches(target, relation, query, options) {
-      const descendants = lookup.descendants(target, relation, options)
-      if (!descendants.ok) {
-        return descendants
-      }
-      const matches: Array<QueryMatch<S, typeof query>> = []
-      for (const descendantId of descendants.value) {
-        const resolved = resolve(descendantId, query, reader)
-        if (resolved.ok) {
-          matches.push(resolved.value)
-        }
-      }
-      return Result.success(matches)
-    },
     root(target, relation) {
       if (!world.records.has(target)) {
         return Result.failure(Relation.missingEntityError(target))
@@ -976,13 +1140,32 @@ const makeValidatedRuntime = <
     return lookup
   }
 
-  const makeQueryHandle = <Q extends Query.Query.Any<Root>>(query: Q, reader: ReaderState): QueryHandle<S, Q> => {
+  const makeQueryHandle = <Q extends Query.Query.Any<Root>>(query: Q, reader: ReaderState, lookup: LookupApi<S, Root>): QueryHandle<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>> = []
+      for (const id of ids) {
+        const resolved = resolve(id, query, reader)
+        if (resolved.ok) matches.push(resolved.value)
+      }
+      return matches
+    }
     return {
       each,
       get(target) {
         return resolve(target, query, reader)
       },
+      getHandle(handle) {
+        return resolve(handle as Entity.Handle<Root, any>, query, reader)
+      },
+      children(target, relation) {
+        if (!world.records.has(target)) return Result.failure(Relation.missingEntityError(target))
+        return Result.success(matching(world.relatedSourceIds(relation, target).map(entityId)))
+      },
+      descendants(target, relation, options) {
+        const ids = lookup.descendants(target, relation, options)
+        return ids.ok ? Result.success(matching(ids.value)) : ids
+      },
       single() {
         const matches = each()
         if (matches.length === 0) {
@@ -1024,6 +1207,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)
@@ -1036,6 +1228,14 @@ const makeValidatedRuntime = <
 
   const commitSystemTransaction = (): void => {
     world.commitTransaction()
+    if (watchedResources.size > 0) {
+      for (const [key, before] of resourceOriginals) {
+        if (!watchedResources.has(key)) continue
+        if (before === absentValue || !sameValue(before, resources.get(key))) {
+          resourceChangedAt.set(key, world.currentTick())
+        }
+      }
+    }
     if (emittedEvents.size > 0) {
       const published = world.advanceTick()
       for (const [key, values] of emittedEvents) {
@@ -1078,6 +1278,17 @@ const makeValidatedRuntime = <
     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>>
@@ -1115,6 +1326,9 @@ const makeValidatedRuntime = <
     return {
       all() {
         return world.removedSince(ordinal, reader.since).map(entityId)
+      },
+      lagged() {
+        return world.removedLagged(ordinal, reader.since, reader.registeredAt)
       }
     }
   }
@@ -1122,6 +1336,9 @@ const makeValidatedRuntime = <
   const makeDespawnedReadView = (reader: ReaderState): DespawnedReadView<S, Root> => ({
     all() {
       return world.despawnedSince(reader.since).map(entityId)
+    },
+    lagged() {
+      return world.despawnedLagged(reader.since, reader.registeredAt)
     }
   })
 
@@ -1138,19 +1355,33 @@ 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)
+    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)
@@ -1199,16 +1430,19 @@ const makeValidatedRuntime = <
    * views the implementation is allowed to see. Views read live storage, so
    * one context is built per system and reused for every run.
    */
-  const makeContext = (system: SystemDefinition<any, any, any>, reader: ReaderState): SystemContext<any> => {
+  const makeContext = (system: SystemDefinition<any, any, any>, reader: ReaderState, queue: Command.CommandQueue<S, Root>): SystemContext<any> => {
     const spec = system.spec
+    const lookup = makeLookup(reader)
     return {
       local: (spec.local as (() => unknown) | undefined)?.(),
-      queries: mapRecord(spec.queries as Record<string, Query.Query.Any<Root>>, (query) => makeQueryHandle(query, reader)),
-      lookup: makeLookup(reader),
+      queries: mapRecord(spec.queries as Record<string, Query.Query.Any<Root>>, (query) => makeQueryHandle(query, reader, lookup)),
+      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)
@@ -1222,12 +1456,15 @@ const makeValidatedRuntime = <
       relationFailures: mapRecord(spec.relationFailures as Record<string, any>, (access) => makeRelationFailureReadView(access.relation, reader)),
       services: mapRecord(spec.services as Record<string, any>, (access) =>
         providedServices[access.descriptor.name as keyof Services]),
-      commands: Command.makeCommands<S, Root>(() => world.allocateEntity() as Entity.EntityId<S, Root>)
+      // The queue serves every declared permission set; the spec's types narrow it.
+      commands: queue as unknown
     } as SystemContext<any>
   }
 
   interface SystemSlot {
     readonly context: SystemContext<any>
+    /** The system's command queue (its context's `commands`, unchecked). */
+    readonly commands: Command.CommandQueue<S, Root>
     readonly reader: ReaderState
   }
 
@@ -1316,7 +1553,7 @@ const makeValidatedRuntime = <
       system: system.name,
       outcome,
       ...(outcome === "ok" ? {} : { error }),
-      ms: now() - started,
+      ms: HostClockModule.elapsed(started, now()),
       writes,
       resources: resourceWrites,
       events: emitted,
@@ -1383,7 +1620,8 @@ const makeValidatedRuntime = <
     let slot = slots.get(stateKey(system))
     if (!slot) {
       const reader: ReaderState = { since: 0, lastRun: 0, streamSince: 0, streamLastRun: 0, registeredAt: world.currentTick() }
-      slot = { context: makeContext(system, reader), reader }
+      const commands = Command.makeCommands<S, Root>(() => world.allocateEntity() as Entity.EntityId<S, Root>)
+      slot = { context: makeContext(system, reader, commands), commands, reader }
       slots.set(stateKey(system), slot)
       if (holdsStreams) registerStreamReader(system, slot.reader)
       const make = system.spec.local as (() => unknown) | undefined
@@ -1422,7 +1660,8 @@ const makeValidatedRuntime = <
         return succeeded
       }
     }
-    const { context, reader } = slotOf(system, true)
+    const { context, commands, reader } = slotOf(system, true)
+    if (debugEnabled) ranSystems.add(system.name)
     // Changes stamped after the previous completed run are visible to this run.
     reader.since = reader.lastRun
     reader.streamSince = reader.streamLastRun
@@ -1431,23 +1670,21 @@ const makeValidatedRuntime = <
     beginSystemTransaction()
     let outcome: Result.Result<unknown, unknown>
     try {
-      // A system that returns nothing cannot fail. Otherwise run its effect,
-      // equivalent to `Fx.runSync(Fx.provide(effect, services))` without the wrapper allocations.
-      const effect = system.run(context)
-      outcome = effect === undefined ? succeeded : effect.run(context.services)
+      // A system that returns nothing cannot fail; otherwise it returned a `Result`.
+      outcome = system.run(context) ?? succeeded
     } catch (defect) {
-      if (tracing) emit(traceSystem(system, reader, thisRun, started, "defect", defect, context.commands.flush()))
+      if (tracing) emit(traceSystem(system, reader, thisRun, started, "defect", defect, commands.flush()))
       rollbackSystemTransaction()
-      context.commands.flush()
+      commands.flush()
       throw defect
     }
     if (!outcome.ok) {
-      if (tracing) emit(traceSystem(system, reader, thisRun, started, "failed", outcome.error, context.commands.flush()))
+      if (tracing) emit(traceSystem(system, reader, thisRun, started, "failed", outcome.error, commands.flush()))
       rollbackSystemTransaction()
-      context.commands.flush()
+      commands.flush()
       return Result.failure({ kind: "SystemFailure", system: system.name, error: outcome.error })
     }
-    const queued = context.commands.flush()
+    const queued = commands.flush()
     const traced = tracing ? traceSystem(system, reader, thisRun, started, "ok", undefined, queued) : undefined
     commitSystemTransaction()
     // A failed run leaves `lastRun` unchanged, so the next run sees the same changes again.
@@ -1469,8 +1706,15 @@ const makeValidatedRuntime = <
     const origins = pendingOrigins.splice(0, pendingOrigins.length)
     world.advanceTick()
     if (!tracing) {
-      for (const command of commands) {
-        command.apply(commandWorld)
+      if (!debugEnabled) {
+        for (const command of commands) {
+          command.apply(commandWorld)
+        }
+        return
+      }
+      for (let index = 0; index < commands.length; index++) {
+        commandOrigin = origins[index] ?? "(unknown)"
+        commands[index]!.apply(commandWorld)
       }
       return
     }
@@ -1479,6 +1723,7 @@ const makeValidatedRuntime = <
       const command = commands[index]!
       const effects: Array<Debug.Effect> = []
       commandEffects = effects
+      commandOrigin = origins[index] ?? "(unknown)"
       try {
         command.apply(commandWorld)
       } finally {
@@ -1503,7 +1748,7 @@ const makeValidatedRuntime = <
     } finally {
       schedulePath.pop()
     }
-    emit({ type: "schedule.end", frame: frameCount, schedule: scheduleLabel, ok: result.ok, ms: now() - started })
+    emit({ type: "schedule.end", frame: frameCount, schedule: scheduleLabel, ok: result.ok, ms: HostClockModule.elapsed(started, now()) })
     return result
   }
 
@@ -1541,6 +1786,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.
@@ -1558,6 +1833,10 @@ const makeValidatedRuntime = <
 
     const schedules = bundle?.entries ?? []
     for (const [machineKey, pending] of scheduledTransitions) {
+      if (pendingMachines.get(machineKey) !== pending) {
+        // Discarded earlier in this marker: its parent left the state it exists in.
+        continue
+      }
       pendingMachines.delete(machineKey)
       const current = currentMachines.get(machineKey)
       if (current === undefined) {
@@ -1568,12 +1847,25 @@ const makeValidatedRuntime = <
         continue
       }
 
-      previousMachines.set(machineKey, current)
       const snapshot = {
         from: current as Machine.StateValue,
         to: pending.value as Machine.StateValue
       }
 
+      // 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.
+      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) {
@@ -1603,10 +1895,8 @@ const makeValidatedRuntime = <
         }
       }
 
-      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)
 
       for (const schedule of schedules) {
         const transition = schedule.transition
@@ -1618,6 +1908,82 @@ 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
+    }
+    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)
+      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, then runs their `onEnter` schedules and enters their own
+   * sub-states.
+   */
+  const enterSubStates = (parentKey: symbol, state: unknown, schedules: TransitionSchedules): Result.Result<void, SystemFailure> => {
+    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)
+      const snapshot = { from: undefined, to: value } as unknown as Machine.TransitionSnapshot
+      const result = runPhase(sub.key, "enter", value, snapshot, schedules)
+      if (!result.ok) {
+        if (tracing) traceTransition(sub.key, snapshot, "enterFailed")
+        return result
+      }
+      const nested = enterSubStates(sub.key, value, schedules)
+      if (!nested.ok) return nested
     }
     return succeeded
   }
@@ -1661,7 +2027,7 @@ const makeValidatedRuntime = <
    * Runs one schedule. A failing system stops the schedule; systems that
    * already succeeded stay committed, and their pending work stays pending.
    */
-  const runScheduleUnsafe = (schedule: ExecutableScheduleDefinition<S, any, any, any, any>): Result.Result<void, SystemFailure> => {
+  const runScheduleUnsafe = (schedule: ExecutableScheduleDefinition<S, any, any, any, any, AnyScheduleOrder>): Result.Result<void, SystemFailure> => {
     changedMachines = new Set()
     return tracing
       ? traceSchedule(scheduleName(schedule), () => runSteps(schedule.steps))
@@ -1670,6 +2036,13 @@ const makeValidatedRuntime = <
 
   const eventsByKey = new Set((Object.values(options.schema.events) as ReadonlyArray<Descriptor.Any>).map((descriptor) => descriptor.key))
   const externallyWrittenEvents = new Set<string>()
+  /** `debug.observeHost` listeners: ticks and sends, without tracing. Only a debug runtime registers any. */
+  const hostListeners = new Set<(event: Debug.HostEvent<S, Root>) => void>()
+  const emitHost = (event: Debug.HostEvent<S, Root>): void => {
+    for (const listener of hostListeners) listener(event)
+  }
+  /** Events declared as sent by the host (`debug.declareHostEvents`). */
+  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`)
@@ -1679,6 +2052,7 @@ const makeValidatedRuntime = <
     // Bound host traffic even when it sends repeatedly without ticking.
     events.trim(0)
     externallyWrittenEvents.add(descriptor.name)
+    if (hostListeners.size > 0) emitHost({ type: "send", event: descriptor.name, value })
     if (tracing) emit({ type: "runtime.sent", frame: frameCount, tick: published, event: descriptor.name, value })
   }
 
@@ -1691,21 +2065,91 @@ const makeValidatedRuntime = <
     relationFailures.trim(boundary)
   }
 
-  const tickUnsafe = (schedules: ReadonlyArray<ExecutableScheduleDefinition<S, any, any, any, any>>): Result.Result<void, SystemFailure> => {
+  /**
+   * With debug: the last failed tick result, until its `ok` is read. The
+   * result handed back is a copy whose `ok` getter marks it read.
+   */
+  let unread: { read: boolean; readonly event: Omit<Debug.FailureIgnoredEvent, "type" | "when"> } | undefined
+  const reportUnread = (when: Debug.FailureIgnoredEvent["when"]): void => {
+    const pending = unread
+    unread = undefined
+    if (pending === undefined || pending.read) return
+    const event: Debug.FailureIgnoredEvent = { type: "failure.ignored", ...pending.event, when }
+    emit(event)
+    emitHost(event)
+  }
+  const watchResult = <R extends Result.Result<void, unknown>>(
+    result: R,
+    schedules: ReadonlyArray<ExecutableScheduleDefinition<S, any, any, any, any, AnyScheduleOrder>>
+  ): R => {
+    if (!debugEnabled || result.ok) return result
+    const error = result.error
+    const system = typeof error === "object" && error !== null && (error as { readonly kind?: unknown }).kind === "SystemFailure"
+      ? (error as SystemFailure).system
+      : undefined
+    const names = schedules.flatMap((schedule) => schedule.steps.filter(Schedule.isSystemStep).map((step) => (step as SystemDefinition<any, any, any>).name))
+    const at = system === undefined ? -1 : names.indexOf(system)
+    const holder = system === undefined
+      ? schedules[0]
+      : schedules.find((schedule) => schedule.steps.some((step) => Schedule.isSystemStep(step) && (step as SystemDefinition<any, any, any>).name === system)) ?? schedules[0]
+    const entry = {
+      read: false,
+      event: {
+        frame: frameCount,
+        schedule: holder === undefined ? "(none)" : scheduleName(holder),
+        system,
+        error,
+        skipped: [...new Set(names.slice(at + 1))]
+      }
+    }
+    unread = entry
+    return {
+      get ok() {
+        entry.read = true
+        return false
+      },
+      error
+    } as unknown as R
+  }
+
+  const tickUnsafe = (schedules: ReadonlyArray<ExecutableScheduleDefinition<S, any, any, any, any, AnyScheduleOrder>>): Result.Result<void, SystemFailure> => {
     if (ticking) throw new Error("runtime.tick cannot run inside another tick")
+    if (debugEnabled) reportUnread("next-tick")
     ticking = true
     try {
       advanceFrame()
-      for (const schedule of schedules) {
-        const result = runScheduleUnsafe(schedule)
-        if (!result.ok) return result
-      }
-      return succeeded
+      return watchResult(observedTick(schedules, () => {
+        for (const schedule of schedules) {
+          const result = runScheduleUnsafe(schedule)
+          if (!result.ok) return result
+        }
+        return succeeded
+      }), schedules)
     } finally {
       ticking = false
     }
   }
 
+  /** Runs one tick's schedules, telling `observeHost` listeners when it starts and how it ends. */
+  const observedTick = (
+    schedules: ReadonlyArray<ExecutableScheduleDefinition<S, any, any, any, any, AnyScheduleOrder>>,
+    run: () => Result.Result<void, SystemFailure>
+  ): Result.Result<void, SystemFailure> => {
+    if (hostListeners.size === 0) return run()
+    emitHost({ type: "tick.start", schedules, frame: frameCount })
+    let result: Result.Result<void, SystemFailure>
+    try {
+      result = run()
+    } catch (defect) {
+      emitHost({ type: "tick.end", schedules, frame: frameCount, outcome: "defect", error: defect })
+      throw defect
+    }
+    emitHost(result.ok
+      ? { type: "tick.end", schedules, frame: frameCount, outcome: "ok" }
+      : { type: "tick.end", schedules, frame: frameCount, outcome: "failed", error: result.error })
+    return result
+  }
+
   const hasRequirement = (requirement: Requirement.RequirementValue): boolean => {
     switch (requirement.kind) {
       case "service":
@@ -1713,26 +2157,33 @@ 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)
     }
   }
 
-  const tryRunSchedule = <const Selected extends ExecutableScheduleDefinition<S, any, any, any, any>>(
+  const tryRunSchedule = <const Selected extends ExecutableScheduleDefinition<S, any, any, any, any, AnyScheduleOrder>>(
     schedule: Selected
-  ): Result.Result<void, MissingRuntimeRequirements | Schedule.FailureOf<Selected>> => {
+  ): Result.Result<void, MissingRuntimeRequirements | TickOrderViolation | Schedule.FailureOf<Selected>> => {
+    if (debugEnabled) reportUnread("next-tick")
     const missing = schedule.requirements
       .filter((requirement) => !hasRequirement(requirement))
       .map(({ kind, name }) => ({ kind, name }))
 
     if (missing.length > 0) {
-      return Result.failure({
-        kind: "MissingRuntimeRequirements",
+      return watchResult(Result.failure({
+        kind: "MissingRuntimeRequirements" as const,
         requirements: missing
-      })
+      }), [schedule])
+    }
+
+    const issues = OrderInternal.tickOrderIssues(schedule.steps)
+    if (issues.length > 0) {
+      return watchResult(Result.failure({ kind: "TickOrderViolation" as const, issues }), [schedule])
     }
 
     advanceFrame()
-    return runScheduleUnsafe(schedule) as Result.Result<void, Schedule.FailureOf<Selected>>
+    return watchResult(observedTick([schedule], () => runScheduleUnsafe(schedule)), [schedule]) as Result.Result<void, Schedule.FailureOf<Selected>>
   }
 
   /**
@@ -1823,6 +2274,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]> = []
@@ -1859,12 +2315,29 @@ 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>()
@@ -1897,8 +2370,12 @@ 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
@@ -2041,12 +2518,21 @@ const makeValidatedRuntime = <
       scheduleNames.clear()
       for (const [name, schedule] of Object.entries(named)) scheduleNames.set(schedule, name)
     },
+    declareHostEvents(declared) {
+      hostEvents = new Set(declared.map((descriptor) => descriptor.name))
+    },
     describe: () => DebugInternal.describe({
       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,
+      externallyWrittenEvents: new Set([...externallyWrittenEvents, ...hostEvents]),
+      relationMutations,
+      commandUses,
+      ranSystems,
+      requirementViolations: [...requirementViolations.values()],
       hasResource: (descriptor) => resources.has(descriptor.key),
       schedules: [...scheduleNames].map(([schedule, name]) => [name, schedule as ExecutableScheduleDefinition<S>] as const)
     }),
@@ -2063,6 +2549,13 @@ const makeValidatedRuntime = <
         }
       }
     },
+    observeHost(listener) {
+      hostListeners.add(listener)
+      return () => {
+        hostListeners.delete(listener)
+      }
+    },
+    checkIgnoredFailures: () => reportUnread("session-end"),
     streams,
     population: () => {
       const components: Record<string, number> = {}
@@ -2110,7 +2603,9 @@ export const make = <
   readonly resources?: Resources
   readonly machines?: ProvidedMachines
   readonly machineDefinitions?: ReadonlyArray<Machine.StateMachine.Any>
-  /** Attaches a `debug` handle to the runtime; see the `Debug` module. */
+  /** 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
 }): MakeRuntimeResult<S, Simplify<RuntimeServicesOf<ProvidedServices>>, Resources, Root, RuntimeMachinesOf<ProvidedMachines>, Enabled> => {
   const fallible = Object.entries(options.schema.resources).some(([key, descriptor]) =>
@@ -2128,7 +2623,8 @@ export const make = <
     resources: validated.value,
     machines: options.machines,
     machineDefinitions: options.machineDefinitions ?? [],
-    debug: options.debug === true
+    scopeDefinitions: options.scopeDefinitions ?? [],
+    debug: options.debug
   })
   return (fallible ? Result.success(runtime) : runtime) as never
 }