@typeonce/ritmo 0.8.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: {
@@ -149,7 +150,7 @@ const collectConstructedRegistryValues = (registry, provided) => {
  *   resources: {
  *     score: 0
  *   }
- * })
+ * }).value
  * ```
  */
 /**
@@ -159,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);
@@ -171,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.
@@ -313,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) {
@@ -348,6 +375,41 @@ const makeValidatedRuntime = (options) => {
             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));
@@ -431,6 +493,9 @@ const makeValidatedRuntime = (options) => {
                 world.writeComponent(id, descriptor, value);
             }
         },
+        reportStaleTarget(command, id) {
+            reportStaleTarget(command, id);
+        },
         tryRelate(id, relation, target) {
             if (debugEnabled) {
                 noteRelationMutation(relation);
@@ -597,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);
@@ -622,11 +694,23 @@ 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());
                 }
             }
@@ -666,6 +750,59 @@ 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;
@@ -747,7 +884,24 @@ const makeValidatedRuntime = (options) => {
             });
         }
         journalMachine(stateMachine.key);
-        pendingMachines.set(stateMachine.key, { value, skipIfSame });
+        if (debugEnabled) {
+            const previous = pendingMachines.get(stateMachine.key);
+            // A set from a transition schedule waits for the next marker: it replaces nothing queued for this one.
+            if (previous?.by !== undefined && previous.by !== runningSystem && previous.value !== value && activeTransitions.size === 0) {
+                const key = `${stateMachine.name}/${previous.by}/${runningSystem}/${String(previous.value)}/${String(value)}`;
+                const seen = nextStateReplacements.get(key);
+                nextStateReplacements.set(key, {
+                    machine: stateMachine.name,
+                    replaced: { system: previous.by, value: previous.value },
+                    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) => ({
@@ -804,8 +958,12 @@ 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"
@@ -814,15 +972,15 @@ const makeValidatedRuntime = (options) => {
                     ? 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
@@ -985,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;
             }
@@ -1001,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;
@@ -1168,11 +1330,19 @@ 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) {
+            if (discardedPending.has(pending)) {
                 // Discarded earlier in this marker: its parent left the state it exists in.
                 continue;
             }
-            pendingMachines.delete(machineKey);
+            // A transition schedule earlier in this marker may have queued a newer
+            // value for this machine: that one waits for the next marker.
+            if (pendingMachines.get(machineKey) === pending)
+                pendingMachines.delete(machineKey);
+            /** Keeps this request queued after a failure, unless a newer one replaced it. */
+            const requeue = () => {
+                if (!pendingMachines.has(machineKey))
+                    pendingMachines.set(machineKey, pending);
+            };
             const current = currentMachines.get(machineKey);
             if (current === undefined) {
                 continue;
@@ -1189,48 +1359,46 @@ const makeValidatedRuntime = (options) => {
             // Sub-states that exist in the state being left exit first, deepest
             // first: their exit schedules run before the parent's, while they
             // still have their values, and they lose them at the parent's commit.
+            // The exit phase is one transaction: a failure undoes all of it, and
+            // the transition stays queued for a later attempt.
             const leaving = activeSubStatesIn(machineKey, snapshot.from);
-            for (const sub of leaving) {
-                const value = currentMachines.get(sub.key);
-                const result = runPhase(sub.key, "exit", value, { from: value, to: undefined }, schedules);
-                if (!result.ok) {
-                    pendingMachines.set(machineKey, pending);
-                    if (tracing)
-                        traceTransition(machineKey, snapshot, "failed");
-                    return result;
-                }
-            }
-            for (const schedule of schedules) {
-                const transition = schedule.transition;
-                if (transition.phase === "exit" && transition.machine.key === machineKey && transition.state === snapshot.from) {
-                    const result = runTransitionSchedule(schedule, snapshot);
-                    if (!result.ok) {
-                        // The transition did not happen; keep it queued for a later attempt.
-                        pendingMachines.set(machineKey, pending);
-                        if (tracing)
-                            traceTransition(machineKey, snapshot, "failed");
+            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;
             }
             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) {
@@ -1242,10 +1410,9 @@ 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;
+            const enteredSchedules = runSubStateEnters(entered, schedules);
+            if (!enteredSchedules.ok)
+                return enteredSchedules;
         }
         return succeeded;
     };
@@ -1260,6 +1427,9 @@ const makeValidatedRuntime = (options) => {
             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 {
@@ -1296,25 +1466,29 @@ const makeValidatedRuntime = (options) => {
     };
     /**
      * Gives the sub-states of `parentKey` that exist in `state` their entry
-     * value, then runs their `onEnter` schedules and enters their own
-     * sub-states.
+     * value, and theirs, parents first. Returns what it entered, in that order.
      */
-    const enterSubStates = (parentKey, state, schedules) => {
+    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(sub.key, "enter", value, snapshot, schedules);
+            const result = runPhase(key, "enter", value, snapshot, schedules);
             if (!result.ok) {
                 if (tracing)
-                    traceTransition(sub.key, snapshot, "enterFailed");
+                    traceTransition(key, snapshot, "enterFailed");
                 return result;
             }
-            const nested = enterSubStates(sub.key, value, schedules);
-            if (!nested.ok)
-                return nested;
         }
         return succeeded;
     };
@@ -1349,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.
@@ -1372,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`);
@@ -1446,6 +1626,7 @@ const makeValidatedRuntime = (options) => {
         if (debugEnabled)
             reportUnread("next-tick");
         ticking = true;
+        inTick = true;
         try {
             advanceFrame();
             return watchResult(observedTick(schedules, () => {
@@ -1459,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. */
@@ -1471,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 });
@@ -1506,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.
@@ -1535,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)) {
@@ -1555,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(),
@@ -1570,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 = [];
@@ -1669,6 +1867,8 @@ const makeValidatedRuntime = (options) => {
         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 });
@@ -1708,6 +1908,8 @@ const makeValidatedRuntime = (options) => {
         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 });
@@ -1856,6 +2058,9 @@ const makeValidatedRuntime = (options) => {
             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])
         }),
@@ -1895,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.
@@ -1909,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 });
@@ -1927,9 +2130,18 @@ export const make = (options) => {
         machines: options.machines,
         machineDefinitions: options.machineDefinitions ?? [],
         scopeDefinitions: options.scopeDefinitions ?? [],
-        debug: options.debug
+        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.
@@ -1940,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
@@ -1951,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;
@@ -1973,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;