@typeonce/ritmo 0.7.0 → 0.9.0

package/dist/Runtime.js

@@ -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: {
@@ -59,8 +60,10 @@ import * as HostClockModule from "./HostClock.js";
 import * as Command from "./Command.js";
 import * as DescriptorModule from "./Descriptor.js";
 import * as Cells from "./internal/cells.js";
+import { sameValue } from "./internal/equal.js";
 import * as DebugInternal from "./internal/debug.js";
 import { makeQueryEngine } from "./internal/queries.js";
+import { requirementIndex } from "./internal/requirements.js";
 import * as Streams from "./internal/streams.js";
 import { ABSENT, makeWorld } from "./internal/world.js";
 import * as Query from "./Query.js";
@@ -147,7 +150,7 @@ const collectConstructedRegistryValues = (registry, provided) => {
  *   resources: {
  *     score: 0
  *   }
- * })
+ * }).value
  * ```
  */
 /**
@@ -157,6 +160,25 @@ const collectConstructedRegistryValues = (registry, provided) => {
  * `lagged() === true` (or a `missed` read in the debug trace).
  */
 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, saves) => {
+    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 = (options) => {
     const world = makeWorld(options.schema, streamCapacity);
     const queries = makeQueryEngine(world);
@@ -169,7 +191,10 @@ const makeValidatedRuntime = (options) => {
      * Machine-keyed committed, pending, and previous values.
      */
     const currentMachines = new Map();
+    /** Queued next values; with `debug`, `by` is the system that queued it, for the `next-state-replaced` lint. */
     const pendingMachines = new Map();
+    /** Requests dropped because their sub-state stopped existing: skipped by the marker that queued them. */
+    const discardedPending = new WeakSet();
     const previousMachines = new Map();
     /**
      * Machine keys changed by transitions applied during the current schedule run.
@@ -240,8 +265,52 @@ const makeValidatedRuntime = (options) => {
     const providedMachines = (options.machines ?? machines());
     const machineEntries = (options.machines ?? machines())[runtimeMachinesEntries];
     const machineDefinitionOrder = new Map(options.machineDefinitions.map((machine, index) => [machine.key, index]));
+    /** Machines the runtime was given an initial value for. */
+    const providedMachineKeys = new Set();
     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();
+    const subStateEntry = new Map();
+    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();
+    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 = (relation, operation, sourceId, targetId, error) => {
         if (tracing) {
@@ -267,6 +336,10 @@ const makeValidatedRuntime = (options) => {
      */
     const commandUses = new Map();
     const ranSystems = new Set();
+    /** 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();
     const noteCommand = (kind, name) => {
         let uses = commandUses.get(commandOrigin);
         if (uses === undefined) {
@@ -283,15 +356,92 @@ const makeValidatedRuntime = (options) => {
         }
         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();
+    const violateRequirement = (command, entity, [component, missing]) => {
+        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();
+    const watchStreamLoss = (view, system, stream, paused) => {
+        const key = `${system}/${stream}`;
+        const entry = () => {
+            let found = streamLosses.get(key);
+            if (found === undefined) {
+                found = { system, stream, lostRuns: 0, checksLagged: false, paused };
+                streamLosses.set(key, found);
+            }
+            return found;
+        };
+        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();
+    const reportStaleTarget = (command, entity) => {
+        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) => {
+        const record = world.records.get(id);
+        return (descriptor) => record !== undefined && world.has(record, world.ordinalOf(descriptor));
+    };
+    /** The first requirement `components` break, as `[requirer, missing]`. */
+    const missingIn = (components, alsoHeld) => {
+        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 = {
         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) {
@@ -311,15 +461,40 @@ const makeValidatedRuntime = (options) => {
                 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);
+            }
         },
-        writeComponent(id, descriptor, value) {
-            if (debugEnabled)
-                noteCommand("inserts", descriptor.name);
-            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);
+            }
+        },
+        reportStaleTarget(command, id) {
+            reportStaleTarget(command, id);
         },
         tryRelate(id, relation, target) {
             if (debugEnabled) {
@@ -487,6 +662,13 @@ const makeValidatedRuntime = (options) => {
     const resourceOriginals = new Map();
     const machineOriginals = new Map();
     const emittedEvents = new Map();
+    let phase;
+    /** Keeps a reader's position from before the phase, the first time the phase moves it. */
+    const journalReader = (reader) => {
+        if (phase !== undefined && !phase.readers.has(reader)) {
+            phase.readers.set(reader, [reader.since, reader.lastRun, reader.streamSince, reader.streamLastRun]);
+        }
+    };
     const journalStoreWrite = (store, originals) => (key, value) => {
         if (!originals.has(key)) {
             originals.set(key, store.has(key) ? store.get(key) : absentValue);
@@ -494,6 +676,14 @@ const makeValidatedRuntime = (options) => {
         store.set(key, value);
     };
     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();
+    const resourceChangedAt = new Map();
     const journalMachine = (key) => {
         if (!machineOriginals.has(key)) {
             machineOriginals.set(key, pendingMachines.get(key) ?? absentValue);
@@ -504,6 +694,27 @@ const makeValidatedRuntime = (options) => {
     };
     const commitSystemTransaction = () => {
         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) {
@@ -539,7 +750,70 @@ const makeValidatedRuntime = (options) => {
         machineOriginals.clear();
         emittedEvents.clear();
     };
+    /**
+     * Runs `run` as one phase: on failure, or a thrown defect, everything the
+     * systems in it committed is undone.
+     */
+    const runAsPhase = (run) => {
+        const opened = {
+            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;
+        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, store, write) => Cells.storeWrite(store, descriptor.key, write, DescriptorModule.constructorOf(descriptor));
+    const makeResourceChangedView = (descriptor, reader) => {
+        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 = (descriptorKey, reader) => ({
         all() {
             return events.since(descriptorKey, reader.streamSince);
@@ -598,15 +872,45 @@ const makeValidatedRuntime = (options) => {
         get: () => currentMachines.get(stateMachine.key),
         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 = (stateMachine, value, skipIfSame) => {
+        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
+            });
+        }
+        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 },
+                    by: { system: runningSystem, value: value },
+                    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);
+    };
     const makeNextMachineWriteView = (stateMachine) => ({
         getPending: () => pendingMachines.get(stateMachine.key)?.value,
         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);
@@ -654,23 +958,29 @@ const makeValidatedRuntime = (options) => {
     const makeContext = (system, reader, queue) => {
         const spec = system.spec;
         const lookup = makeLookup(reader);
+        const paused = spec.pauseWhen.length > 0;
+        /** On a debug runtime, records reads after a loss and calls of `lagged()`, for the `stream-loss-unread` lint. */
+        const watch = (view, stream) => debugEnabled ? watchStreamLoss(view, system.name, stream, paused) : view;
         return {
             local: spec.local?.(),
+            // A filtered query hands out the same object; its type hides the lookups.
             queries: mapRecord(spec.queries, (query) => makeQueryHandle(query, reader, lookup)),
             lookup,
             resources: mapRecord(spec.resources, (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, (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, (access) => makeMachineReadView(access.machine)),
             nextMachines: mapRecord(spec.nextMachines, (access) => makeNextMachineWriteView(access.machine)),
-            transitionEvents: mapRecord(spec.transitionEvents, (access) => makeTransitionEventReadView(access.machine, reader)),
+            transitionEvents: mapRecord(spec.transitionEvents, (access) => watch(makeTransitionEventReadView(access.machine, reader), `transition events ${access.machine.name}`)),
             transitions: mapRecord(spec.transitions, (access) => makeTransitionReadView(access.machine)),
-            removed: mapRecord(spec.removed, (access) => makeRemovedReadView(access.descriptor, reader)),
-            despawned: mapRecord(spec.despawned, () => makeDespawnedReadView(reader)),
-            relationFailures: mapRecord(spec.relationFailures, (access) => makeRelationFailureReadView(access.relation, reader)),
+            removed: mapRecord(spec.removed, (access) => watch(makeRemovedReadView(access.descriptor, reader), `removed ${access.descriptor.name}`)),
+            despawned: mapRecord(spec.despawned, () => watch(makeDespawnedReadView(reader), "despawned")),
+            relationFailures: mapRecord(spec.relationFailures, (access) => watch(makeRelationFailureReadView(access.relation, reader), `relation failures ${access.relation.name}`)),
             services: mapRecord(spec.services, (access) => providedServices[access.descriptor.name]),
             // The queue serves every declared permission set; the spec's types narrow it.
             commands: queue
@@ -833,6 +1143,7 @@ const makeValidatedRuntime = (options) => {
                 const skipped = slotOf(system, true);
                 if (tracing)
                     traceSkipped(system, condition, skipped.reader, false);
+                journalReader(skipped.reader);
                 skipped.reader.streamLastRun = world.currentTick();
                 return succeeded;
             }
@@ -849,8 +1160,11 @@ const makeValidatedRuntime = (options) => {
             }
         }
         const { context, commands, reader } = slotOf(system, true);
-        if (debugEnabled)
+        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;
@@ -971,6 +1285,39 @@ const makeValidatedRuntime = (options) => {
             activeTransitions.delete(schedule.transition.machine.key);
         }
     };
+    /**
+     * 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, snapshot) => {
+        const triggers = scopeTriggers.get(machineKey);
+        if (triggers === undefined)
+            return;
+        const applied = [];
+        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 = [];
+            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.
@@ -983,7 +1330,19 @@ const makeValidatedRuntime = (options) => {
             - (machineDefinitionOrder.get(rightKey) ?? Number.MAX_SAFE_INTEGER));
         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;
@@ -993,44 +1352,53 @@ const makeValidatedRuntime = (options) => {
                     traceTransition(machineKey, { from: current, to: current }, "unchanged");
                 continue;
             }
-            previousMachines.set(machineKey, current);
             const snapshot = {
                 from: current,
                 to: pending.value
             };
-            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");
+            // 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 }, 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;
                 if (transition.phase === "enter" && transition.machine.key === machineKey && transition.state === snapshot.to) {
@@ -1042,6 +1410,85 @@ const makeValidatedRuntime = (options) => {
                     }
                 }
             }
+            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, from, to) => {
+        const snapshot = { from, to };
+        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);
+    };
+    /** Runs every schedule of `phase` for `machineKey` in `state`, in bundle order. */
+    const runPhase = (machineKey, phase, state, snapshot, schedules) => {
+        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, state) => {
+        const result = [];
+        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, state) => {
+        const entered = [];
+        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, schedules) => {
+        for (const [key, value] of entered) {
+            const snapshot = { from: undefined, to: value };
+            const result = runPhase(key, "enter", value, snapshot, schedules);
+            if (!result.ok) {
+                if (tracing)
+                    traceTransition(key, snapshot, "enterFailed");
+                return result;
+            }
         }
         return succeeded;
     };
@@ -1076,8 +1523,14 @@ const makeValidatedRuntime = (options) => {
         }
         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
      * already succeeded stay committed, and their pending work stays pending.
@@ -1099,7 +1552,7 @@ const makeValidatedRuntime = (options) => {
     /** Events declared as sent by the host (`debug.declareHostEvents`). */
     let hostEvents = new Set();
     const send = (descriptor, value) => {
-        if (ticking)
+        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`);
@@ -1173,6 +1626,7 @@ const makeValidatedRuntime = (options) => {
         if (debugEnabled)
             reportUnread("next-tick");
         ticking = true;
+        inTick = true;
         try {
             advanceFrame();
             return watchResult(observedTick(schedules, () => {
@@ -1186,6 +1640,7 @@ const makeValidatedRuntime = (options) => {
         }
         finally {
             ticking = false;
+            inTick = false;
         }
     };
     /** Runs one tick's schedules, telling `observeHost` listeners when it starts and how it ends. */
@@ -1198,9 +1653,11 @@ const makeValidatedRuntime = (options) => {
             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 });
@@ -1213,7 +1670,8 @@ const makeValidatedRuntime = (options) => {
             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 = (schedule) => {
@@ -1232,8 +1690,16 @@ const makeValidatedRuntime = (options) => {
         if (issues.length > 0) {
             return watchResult(Result.failure({ kind: "TickOrderViolation", issues }), [schedule]);
         }
-        advanceFrame();
-        return watchResult(observedTick([schedule], () => runScheduleUnsafe(schedule)), [schedule]);
+        if (inTick)
+            throw new Error("runtime.tryTick cannot run inside another tick");
+        inTick = true;
+        try {
+            advanceFrame();
+            return watchResult(observedTick([schedule], () => runScheduleUnsafe(schedule)), [schedule]);
+        }
+        finally {
+            inTick = false;
+        }
     };
     /**
      * Evaluates a declared read-only projection without running a schedule.
@@ -1261,6 +1727,8 @@ const makeValidatedRuntime = (options) => {
     for (const provision of machineEntries)
         machinesByName.set(provision.machine.name, provision.machine);
     const snapshot = () => {
+        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 = {};
         for (const [name, descriptor] of resourcesByName) {
             if (!DescriptorModule.isTransient(descriptor) && resources.has(descriptor.key)) {
@@ -1281,6 +1749,7 @@ const makeValidatedRuntime = (options) => {
         }
         return {
             version: Snapshot.version,
+            gameVersion: options.saves?.latest ?? 0,
             nextEntity: world.nextEntityValue(),
             entities: world.exportEntities(DescriptorModule.isTransient),
             relations: world.exportRelations(),
@@ -1296,7 +1765,10 @@ const makeValidatedRuntime = (options) => {
         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();
         const entities = [];
@@ -1317,6 +1789,11 @@ const makeValidatedRuntime = (options) => {
                     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 = [];
@@ -1358,18 +1835,40 @@ const makeValidatedRuntime = (options) => {
                 }
             }
         }
-        const machineValues = [];
+        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();
         const memberships = [];
         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 });
@@ -1397,15 +1896,20 @@ const makeValidatedRuntime = (options) => {
         }
         for (const [id, key] of memberships)
             world.assignEntityScope(id, key);
-        for (const [key, value] of validatedResources)
+        for (const [key, value] of validatedResources) {
             resources.set(key, value);
-        for (const [key, value] of machineValues)
+            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.local = rebuiltLocals[index]; });
         return succeeded;
     };
     const tracedRestore = (data) => {
+        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 });
@@ -1546,11 +2050,17 @@ const makeValidatedRuntime = (options) => {
             schema: options.schema,
             machines: [...new Set(machinesByName.values())],
             currentMachine: (machine) => currentMachines.get(machine.key),
+            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])
         }),
@@ -1590,8 +2100,9 @@ const makeValidatedRuntime = (options) => {
  * 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.
@@ -1604,13 +2115,10 @@ const makeValidatedRuntime = (options) => {
  *   ),
  *   resources: { Score: 0 },
  *   machines: Game.Runtime.machines(Game.Runtime.machine(Flow, "Menu"))
- * })
+ * }).value
  * ```
  */
 export const make = (options) => {
-    const fallible = Object.entries(options.schema.resources).some(([key, descriptor]) => options.resources !== undefined
-        && options.resources[key] !== undefined
-        && DescriptorModule.hasConstructor(descriptor));
     const validated = collectConstructedRegistryValues(options.schema.resources, options.resources);
     if (!validated.ok) {
         return Result.failure({ resources: validated.error });
@@ -1621,9 +2129,19 @@ export const make = (options) => {
         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);
+    return Result.success(runtime);
+};
+const rejectRepeated = (names, kind) => {
+    const seen = new Set();
+    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);
+    }
 };
 /**
  * Builds the descriptor-backed runtime service environment.
@@ -1634,6 +2152,8 @@ export const make = (options) => {
  *
  * 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
@@ -1645,6 +2165,7 @@ export const make = (options) => {
  * ```
  */
 export const services = (...entries) => {
+    rejectRepeated(entries.map((entry) => entry.descriptor.name), "service");
     const provided = {};
     for (const { descriptor, implementation } of entries) {
         provided[descriptor.name] = implementation;
@@ -1667,9 +2188,12 @@ export const service = (descriptor, implementation) => ({
  * 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 = (...entries) => {
+    rejectRepeated(entries.map((entry) => entry.machine.name), "machine");
     const provided = {};
     for (const { machine, initial } of entries) {
         provided[machine.name] = initial;