@typeonce/ritmo 0.6.0 → 0.8.0

package/dist/Runtime.js

@@ -55,17 +55,21 @@
  * @groupDescription Functions
  * Public runtime constructors and helpers for services, machines, and bootstrap input.
  */
+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";
 import * as Relation from "./Relation.js";
 import * as Result from "./Result.js";
 import * as Schedule from "./Schedule.js";
+import * as OrderInternal from "./internal/order.js";
 import * as EntityScopeModule from "./EntityScope.js";
 import * as Snapshot from "./Snapshot.js";
 /**
@@ -194,12 +198,12 @@ const makeValidatedRuntime = (options) => {
      */
     const pendingCommands = [];
     /**
-     * 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 = [];
     const traceListeners = new Set();
     let tracing = false;
@@ -211,7 +215,9 @@ const makeValidatedRuntime = (options) => {
     const scheduleNames = new Map();
     const anonymousScheduleNames = new WeakMap();
     let anonymousScheduleCount = 0;
-    const now = () => performance.now();
+    // Only a debug runtime times anything; the clock is the one it was given.
+    const hostClock = options.debug?.hostClock ?? { now: () => 0 };
+    const now = () => hostClock.now();
     const emit = (event) => {
         for (const listener of traceListeners)
             listener(event);
@@ -236,8 +242,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) {
@@ -247,29 +297,145 @@ const makeValidatedRuntime = (options) => {
             Relation.mutationFailure(relation, operation, world.entityIdOf(sourceId), world.entityIdOf(targetId), error)
         ]);
     };
+    /**
+     * 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();
+    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();
+    const ranSystems = new Set();
+    const noteCommand = (kind, name) => {
+        let uses = commandUses.get(commandOrigin);
+        if (uses === undefined) {
+            uses = new Set();
+            commandUses.set(commandOrigin, uses);
+        }
+        uses.add(`${kind}:${name}`);
+    };
+    const noteRelationMutation = (relation) => {
+        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();
+    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 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) {
+                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);
@@ -277,9 +443,15 @@ const makeValidatedRuntime = (options) => {
             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"
@@ -306,12 +478,6 @@ const makeValidatedRuntime = (options) => {
     };
     const makeLookup = (reader) => {
         const lookup = {
-            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)) {
@@ -319,19 +485,6 @@ const makeValidatedRuntime = (options) => {
                 }
                 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 = [];
-                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)) {
@@ -371,20 +524,6 @@ const makeValidatedRuntime = (options) => {
                 }
                 return Result.success(descendants);
             },
-            descendantMatches(target, relation, query, options) {
-                const descendants = lookup.descendants(target, relation, options);
-                if (!descendants.ok) {
-                    return descendants;
-                }
-                const matches = [];
-                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));
@@ -400,13 +539,34 @@ const makeValidatedRuntime = (options) => {
         };
         return lookup;
     };
-    const makeQueryHandle = (query, reader) => {
+    const makeQueryHandle = (query, reader, lookup) => {
         const each = () => queries.each(query, reader.since);
+        const matching = (ids) => {
+            const matches = [];
+            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, 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) {
@@ -444,6 +604,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);
@@ -454,6 +622,15 @@ const makeValidatedRuntime = (options) => {
     };
     const commitSystemTransaction = () => {
         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) {
@@ -490,6 +667,16 @@ const makeValidatedRuntime = (options) => {
         emittedEvents.clear();
     };
     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);
@@ -522,12 +709,18 @@ const makeValidatedRuntime = (options) => {
         return {
             all() {
                 return world.removedSince(ordinal, reader.since).map(entityId);
+            },
+            lagged() {
+                return world.removedLagged(ordinal, reader.since, reader.registeredAt);
             }
         };
     };
     const makeDespawnedReadView = (reader) => ({
         all() {
             return world.despawnedSince(reader.since).map(entityId);
+        },
+        lagged() {
+            return world.despawnedLagged(reader.since, reader.registeredAt);
         }
     });
     const makeRelationFailureReadView = (relation, reader) => ({
@@ -542,15 +735,28 @@ 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);
+        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);
@@ -595,15 +801,18 @@ const makeValidatedRuntime = (options) => {
      * 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, reader) => {
+    const makeContext = (system, reader, queue) => {
         const spec = system.spec;
+        const lookup = makeLookup(reader);
         return {
             local: spec.local?.(),
-            queries: mapRecord(spec.queries, (query) => makeQueryHandle(query, reader)),
-            lookup: makeLookup(reader),
+            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)
                 : makeEventWriteView(access.descriptor.key)),
@@ -615,7 +824,8 @@ const makeValidatedRuntime = (options) => {
             despawned: mapRecord(spec.despawned, () => makeDespawnedReadView(reader)),
             relationFailures: mapRecord(spec.relationFailures, (access) => makeRelationFailureReadView(access.relation, reader)),
             services: mapRecord(spec.services, (access) => providedServices[access.descriptor.name]),
-            commands: Command.makeCommands(() => world.allocateEntity())
+            // The queue serves every declared permission set; the spec's types narrow it.
+            commands: queue
         };
     };
     const slots = new WeakMap();
@@ -686,7 +896,7 @@ const makeValidatedRuntime = (options) => {
             system: system.name,
             outcome,
             ...(outcome === "ok" ? {} : { error }),
-            ms: now() - started,
+            ms: HostClockModule.elapsed(started, now()),
             writes,
             resources: resourceWrites,
             events: emitted,
@@ -748,7 +958,8 @@ const makeValidatedRuntime = (options) => {
         let slot = slots.get(stateKey(system));
         if (!slot) {
             const reader = { since: 0, lastRun: 0, streamSince: 0, streamLastRun: 0, registeredAt: world.currentTick() };
-            slot = { context: makeContext(system, reader), reader };
+            const commands = Command.makeCommands(() => world.allocateEntity());
+            slot = { context: makeContext(system, reader, commands), commands, reader };
             slots.set(stateKey(system), slot);
             if (holdsStreams)
                 registerStreamReader(system, slot.reader);
@@ -789,7 +1000,9 @@ const makeValidatedRuntime = (options) => {
                 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;
@@ -798,26 +1011,24 @@ const makeValidatedRuntime = (options) => {
         beginSystemTransaction();
         let outcome;
         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()));
+                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()));
+                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.
@@ -840,8 +1051,15 @@ const makeValidatedRuntime = (options) => {
         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;
         }
@@ -850,6 +1068,7 @@ const makeValidatedRuntime = (options) => {
             const command = commands[index];
             const effects = [];
             commandEffects = effects;
+            commandOrigin = origins[index] ?? "(unknown)";
             try {
                 command.apply(commandWorld);
             }
@@ -875,7 +1094,7 @@ const makeValidatedRuntime = (options) => {
         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;
     };
     const traceTransition = (machineKey, snapshot, outcome) => {
@@ -904,6 +1123,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.
@@ -916,6 +1168,10 @@ const makeValidatedRuntime = (options) => {
             - (machineDefinitionOrder.get(rightKey) ?? Number.MAX_SAFE_INTEGER));
         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) {
@@ -926,11 +1182,24 @@ const makeValidatedRuntime = (options) => {
                     traceTransition(machineKey, { from: current, to: current }, "unchanged");
                 continue;
             }
-            previousMachines.set(machineKey, current);
             const snapshot = {
                 from: current,
                 to: pending.value
             };
+            // 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 }, 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) {
@@ -959,11 +1228,9 @@ const makeValidatedRuntime = (options) => {
                     }
                 }
             }
-            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;
                 if (transition.phase === "enter" && transition.machine.key === machineKey && transition.state === snapshot.to) {
@@ -975,6 +1242,79 @@ const makeValidatedRuntime = (options) => {
                     }
                 }
             }
+            // 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, from, to) => {
+        const snapshot = { from, to };
+        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);
+    };
+    /** 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, then runs their `onEnter` schedules and enters their own
+     * sub-states.
+     */
+    const enterSubStates = (parentKey, state, schedules) => {
+        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 };
+            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;
     };
@@ -1023,6 +1363,14 @@ const makeValidatedRuntime = (options) => {
     };
     const eventsByKey = new Set(Object.values(options.schema.events).map((descriptor) => descriptor.key));
     const externallyWrittenEvents = new Set();
+    /** `debug.observeHost` listeners: ticks and sends, without tracing. Only a debug runtime registers any. */
+    const hostListeners = new Set();
+    const emitHost = (event) => {
+        for (const listener of hostListeners)
+            listener(event);
+    };
+    /** Events declared as sent by the host (`debug.declareHostEvents`). */
+    let hostEvents = new Set();
     const send = (descriptor, value) => {
         if (ticking)
             throw new Error(`runtime.send(${descriptor.name}) was called while a schedule is running: emit from a system instead`);
@@ -1033,6 +1381,8 @@ const makeValidatedRuntime = (options) => {
         // 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 });
     };
@@ -1045,23 +1395,90 @@ const makeValidatedRuntime = (options) => {
         transitionEvents.trim(boundary);
         relationFailures.trim(boundary);
     };
+    /**
+     * 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;
+    const reportUnread = (when) => {
+        const pending = unread;
+        unread = undefined;
+        if (pending === undefined || pending.read)
+            return;
+        const event = { type: "failure.ignored", ...pending.event, when };
+        emit(event);
+        emitHost(event);
+    };
+    const watchResult = (result, schedules) => {
+        if (!debugEnabled || result.ok)
+            return result;
+        const error = result.error;
+        const system = typeof error === "object" && error !== null && error.kind === "SystemFailure"
+            ? error.system
+            : undefined;
+        const names = schedules.flatMap((schedule) => schedule.steps.filter(Schedule.isSystemStep).map((step) => step.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.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
+        };
+    };
     const tickUnsafe = (schedules) => {
         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, run) => {
+        if (hostListeners.size === 0)
+            return run();
+        emitHost({ type: "tick.start", schedules, frame: frameCount });
+        let result;
+        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) => {
         switch (requirement.kind) {
             case "service":
@@ -1069,21 +1486,28 @@ 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) => {
+        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({
+            return watchResult(Result.failure({
                 kind: "MissingRuntimeRequirements",
                 requirements: missing
-            });
+            }), [schedule]);
+        }
+        const issues = OrderInternal.tickOrderIssues(schedule.steps);
+        if (issues.length > 0) {
+            return watchResult(Result.failure({ kind: "TickOrderViolation", issues }), [schedule]);
         }
         advanceFrame();
-        return runScheduleUnsafe(schedule);
+        return watchResult(observedTick([schedule], () => runScheduleUnsafe(schedule)), [schedule]);
     };
     /**
      * Evaluates a declared read-only projection without running a schedule.
@@ -1167,6 +1591,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 = [];
@@ -1208,14 +1637,34 @@ 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 = [];
@@ -1247,9 +1696,12 @@ 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]; });
@@ -1389,12 +1841,21 @@ const makeValidatedRuntime = (options) => {
             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),
+            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])
         }),
@@ -1411,6 +1872,13 @@ const makeValidatedRuntime = (options) => {
                 }
             };
         },
+        observeHost(listener) {
+            hostListeners.add(listener);
+            return () => {
+                hostListeners.delete(listener);
+            };
+        },
+        checkIgnoredFailures: () => reportUnread("session-end"),
         streams,
         population: () => {
             const components = {};
@@ -1458,7 +1926,8 @@ export const make = (options) => {
         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);
 };