@typeonce/ritmo 0.6.0 → 0.7.0

package/dist/Runtime.js

@@ -55,6 +55,7 @@
  * @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";
@@ -66,6 +67,7 @@ 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 +196,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 +213,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);
@@ -247,29 +251,81 @@ 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);
+    };
     /**
      * World adapter used by deferred commands.
      */
     const commandWorld = {
         spawnEntity(id, components) {
+            if (debugEnabled)
+                for (const [descriptor] of components)
+                    noteCommand("spawns", descriptor.name);
             world.spawnEntity(id, components);
         },
         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) {
+            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);
         },
         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 +333,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 +368,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 +375,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 +414,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 +429,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) {
@@ -522,12 +572,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) => ({
@@ -595,12 +651,13 @@ 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)),
@@ -615,7 +672,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 +744,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 +806,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 +848,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 +859,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 +899,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 +916,7 @@ const makeValidatedRuntime = (options) => {
             const command = commands[index];
             const effects = [];
             commandEffects = effects;
+            commandOrigin = origins[index] ?? "(unknown)";
             try {
                 command.apply(commandWorld);
             }
@@ -875,7 +942,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) => {
@@ -1023,6 +1090,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 +1108,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 +1122,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":
@@ -1073,17 +1217,23 @@ const makeValidatedRuntime = (options) => {
         }
     };
     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.
@@ -1389,12 +1539,18 @@ 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),
             providedServices: Object.keys(providedServices),
-            externallyWrittenEvents,
+            externallyWrittenEvents: new Set([...externallyWrittenEvents, ...hostEvents]),
+            relationMutations,
+            commandUses,
+            ranSystems,
             hasResource: (descriptor) => resources.has(descriptor.key),
             schedules: [...scheduleNames].map(([schedule, name]) => [name, schedule])
         }),
@@ -1411,6 +1567,13 @@ const makeValidatedRuntime = (options) => {
                 }
             };
         },
+        observeHost(listener) {
+            hostListeners.add(listener);
+            return () => {
+                hostListeners.delete(listener);
+            };
+        },
+        checkIgnoredFailures: () => reportUnread("session-end"),
         streams,
         population: () => {
             const components = {};
@@ -1458,7 +1621,7 @@ export const make = (options) => {
         resources: validated.value,
         machines: options.machines,
         machineDefinitions: options.machineDefinitions ?? [],
-        debug: options.debug === true
+        debug: options.debug
     });
     return (fallible ? Result.success(runtime) : runtime);
 };