@typeonce/ritmo-devtools 0.6.0 → 0.8.0

package/README.md

@@ -1,5 +1,22 @@
 # `@typeonce/ritmo-devtools`
 
+Migrating from bevy-ts? See the [package migration guide](https://github.com/typeonce-dev/ritmo/blob/main/MIGRATION.md).
+
+`Determinism.check` compares the same scripted simulation twice, including
+transient components that snapshots omit:
+
+```ts
+const result = Determinism.check(({ hostClock }) => makeSimulation(hostClock), {
+  schedule: "update", frames: 1800, hostClock: HostClock.test()
+})
+if (!result.ok) throw new Error(JSON.stringify(result))
+```
+
+The factory returns `{ runtime, schedules }`, with a fresh debug runtime on
+every call. A difference reports its frame, value path, and the first system
+or schedule marker found by a diagnostic rerun. This checks the supplied
+inputs on the current JavaScript engine.
+
 Debug sessions for `ritmo` runtimes: run schedules headless, keep a trace
 history, and ask what happened as text. Built for coding agents first; the
 same data will back human-facing tools.
@@ -9,18 +26,33 @@ pnpm add -D @typeonce/ritmo-devtools
 ```
 
 The package reads the core `Debug` handle, which exists only on runtimes made
-with `debug: true`. Production runtimes carry no handle and pay nothing.
+with `debug: { hostClock }`. Production runtimes carry no handle and pay
+nothing. The modules read no platform globals: give the runtime and the
+session the same `HostClock` (`HostClock.test()` headless, so every timing is
+0 and text output is identical across runs; `BrowserHostClock.make(window)`
+in the browser).
+
+A dev-only debug handle in a browser game:
+
+```ts
+const runtime = Game.Runtime.make({
+  services,
+  debug: import.meta.env.DEV ? { hostClock: BrowserHostClock.make(window) } : undefined
+})
+if (runtime.debug !== undefined) Monitor.attach({ debug: runtime.debug }, { schedules, host: window })
+```
 
 ## The debugging loop
 
 1. **Get a headless runtime.** Build the game's simulation schedules on a
-   runtime that needs no renderer, with `debug: true` and scripted input. The
+   runtime that needs no renderer, with `debug: { hostClock: HostClock.test() }`
+   and scripted input. The
    top-down example's [`simulation.ts`](../../examples/top-down/simulation.ts)
    is the reference; its [`debug.ts`](../../examples/top-down/debug.ts) is a
    script to copy.
 2. **Read the lints, then orient.** `session.describe()` starts with lints
-   (events nobody reads, next states no marker applies, ...); a warning there
-   is often the whole answer. Then it lists every schedule step, each
+   (events nobody reads, next states no marker applies, relations whose
+   failures nobody reads, ...); a warning there is often the whole answer. Then it lists every schedule step, each
    system's declared reads and writes, and who reads and writes each
    component, resource, and event. `run()` also prints the lint warning count.
    Info-level `read-before-write` lints list systems that run before the
@@ -28,12 +60,14 @@ with `debug: true`. Production runtimes carry no handle and pay nothing.
    value. That is often intended (input before movement), but it is a
    one-frame lag worth checking when a reaction looks late.
 3. **Reproduce.** Script the input with `Keyboard.scripted(bindings, timeline)`
-   (or replay a recorded browser session), add an `Invariant` that encodes the
-   bug, and `session.run("update", { frames: 600 })`. The run stops at the
+   (or replay a recorded browser session), add an invariant that encodes the
+   bug (`Invariant.fromInspector(Game.Inspector(...))`, returning a message
+   when violated), and `session.run("update", { frames: 600 })`. The run stops at the
    first frame the invariant fails, a system fails, or a system throws.
 4. **Explain.** `session.why(entity, Component)` and
    `session.whyResource(Resource)` show the latest changes and which system
-   made them. `session.journal({ frames: [from, to], entity })`
+   made them; `why` also names the systems whose declared `spawns` could
+   have spawned the entity. `session.journal({ frames: [from, to], entity })`
    shows everything that touched an entity around the failure.
    `session.report()` lists warnings the trace collected and the current
    entity counts per component. `run()` prints the warnings it raised.
@@ -55,21 +89,21 @@ const keyboard = Keyboard.scripted(bindings, [
   { frame: 30, release: ["left"] },
   { frame: 32, press: ["jump"], release: ["jump"] } // a tap within one frame
 ])
-const runtime = Game.Runtime.make({ services, resources, machines, debug: true })
-// Invariants read the world through a typed, read-only Inspector.
-const PlayerHealth = Game.Inspector("Debug/PlayerHealth", {
-  queries: { player: Game.Query({ selection: { health: Game.Query.read(Health) }, with: [Player] }) },
-  resources: { score: Game.System.readResource(Score) }
-}, ({ queries, resources }) => ({
-  health: queries.player.each().map((match) => match.data.health.get()),
-  score: resources.score.get()
+const hostClock = HostClock.test()           // every timing 0: identical text on every run
+const runtime = Game.Runtime.make({ services, resources, machines, debug: { hostClock } })
+// An invariant is a typed, read-only Inspector that returns a violation
+// message, or undefined while it holds. It declares its reads like a system:
+// Session.make rejects at compile time one that reads a resource, service,
+// or machine the runtime does not provide.
+const HealthNeverNegative = Invariant.fromInspector(Game.Inspector("health >= 0", {
+  queries: { player: Game.Query({ selection: { health: Game.Query.read(Health) }, with: [Player] }) }
+}, ({ queries }) => {
+  const health = queries.player.each().map((match) => match.data.health.get())
+  return health.some((value) => value < 0) ? `health ${health.join(", ")}` : undefined
 }))
-const HealthNeverNegative = Invariant.make("health >= 0", () => {
-  const { health } = runtime.inspect(PlayerHealth)
-  return health.some((value) => value < 0) ? `health ${health.join(", ")}` : undefined // message, or undefined when it holds
-})
 
 const session = Session.make(runtime, {
+  hostClock,                              // times run(); the runtime's clock
   schedules: { setup, update },           // names used by run() and in traces
   describe: { render },                   // described and linted, never run (needs a renderer)
   invariants: [HealthNeverNegative],      // checked after every frame of every run
@@ -80,7 +114,7 @@ session.run("setup")
 const run = session.run("update", { frames: 300, until: (frame) => frame === 120 })
 run.data.ok                               // true when completed or `until` returned true
 run.data.stop                             // { reason: "completed" | "until" | "failure" | "defect"
-                                          //   | "invariant" | "missingRequirements", frame, ... }
+                                          //   | "invariant" | "missingRequirements" | "tickOrder", frame, ... }
 
 session.describe()                        // schema, schedules, access, lints
 session.dump({ with: [Player], limit: 5 })// entities, resources, machines, pending commands
@@ -126,7 +160,7 @@ f186 update  -                   transition Game/Flow Playing -> Paused applied
 
 ## Live monitor (browser)
 
-`Monitor.attach(runtime, { schedules })` adds a panel to a running game for
+`Monitor.attach(runtime, { schedules, host: window })` adds a panel to a running game for
 people who want to see how it works without reading its code. Toggle it
 with the backslash key or the corner button. It observes the runtime only while it is
 open, so a closed monitor costs nothing.
@@ -134,6 +168,7 @@ open, so a closed monitor costs nothing.
 ```ts
 const monitor = Monitor.attach(runtime, {
   schedules: { fixedUpdate: step, frame },           // the schedule objects you tick
+  host: window,                                      // its document, timers, events, and clock
   pick: (event) => entityUnderPointer(event),        // optional: "Pick on screen"
   locate: (entity) => clientPositionOf(entity)       // optional: ring on the selected entity
 })
@@ -165,6 +200,7 @@ data without DOM, for a custom UI.
 | `discarded-messages` | A skipped system discarded messages published while it was skipped. |
 | `transition-failed` | An exit or transition schedule failed (queued again), or an enter schedule failed. |
 | `system-failed` | A system returned an expected failure or threw. |
+| `ignored-failure` | A `tick` / `tryTick` result failed and nobody read its `ok` before the next tick (or the session's `report()`): the failure went unnoticed and later systems did not run. `run` stops on it with `reason: "ignored-failure"`. |
 | `non-finite-value` | A system wrote NaN or an infinity into a component, resource, event, or spawned entity. The message names the entity and path; `why()` shows the history. |
 | `population-growing` | A component's count rose through every quarter of a run of 60+ frames: its lowest count in each quarter was higher than in the quarter before. Bursts that are cleaned up do not trigger it; entities that are never despawned do. `run()` returns the counts in `growing`. |
 
@@ -174,6 +210,54 @@ The trace shows what systems wrote, not what they read. When a system writes
 a wrong value from correct inputs, the journal narrows the bug to that
 system (it runs, in order, and writes this value) and the rest is its code.
 
+## Replays
+
+A replay is the last seconds of a play session as a file: a debug artifact
+to open headless, explain, and turn into a test, then delete.
+
+```ts
+// In the game's dev build: record the simulation schedule.
+const recorder = Replay.recorder(runtime, {
+  schedule: simulate, name: "simulate",
+  keep: 30, step: STEP,                      // seconds kept, the fixed step (Clock.hz)
+  sink: ReplayViteSink.make({ fetch: (url, init) => fetch(url, init) }),
+  hostClock: BrowserHostClock.make(window),  // for savedAt
+  saveOn: { failure: true, invariants: [DeadAreGone] } // saves by itself
+})
+Monitor.attach(runtime, { schedules, host: window, replay: recorder }) // adds "Save replay"
+
+// vite.config.ts: writes posted replays to .replays/<time>.json and logs them.
+plugins: [ReplayVitePlugin.plugin()]
+```
+
+- The recorded schedule's services must be `snapshot()` sources of plain
+  data (input) or plain data (rules); anything else is a compile error that
+  names the service. Time and randomness live in the world, so the file holds
+  everything the simulation read: periodic snapshots, each tick's source
+  values (as changes), and every `runtime.send`.
+- Sinks deliver files: `Replay.memorySink()` (tests), `ReplayNodeSink`
+  (files, for headless runs), `ReplayViteSink` + `ReplayVitePlugin` (dev
+  server). The generic modules call no platform API; wall time comes from
+  `hostClock`.
+
+```ts
+// In Node: make(playback) builds the game with the recorded input.
+const make = (playback: Replay.Playback) => {
+  const hostClock = HostClock.test()       // replay text is identical on every run
+  const runtime = makeRuntime({ input: playback.source(Input), debug: { hostClock } })
+  return { runtime, schedules: { simulate }, hostClock }
+}
+const file = Replay.parse(JSON.parse(readFileSync(".replays/....json", "utf8")))
+const replay = file.ok ? Replay.session(make, file.value) : file
+replay.value.play()                       // run the ticks; reports checkpoint divergence
+replay.value.session.why(12, Position)    // a normal Session over the replayed frames
+Replay.verify(make, file.value)           // replays twice: nondeterminism shows up
+Replay.extract(make, file.value, { from: 1400, to: 1412 }) // a small replay for a test
+```
+
+A replay recorded with another schema fails with "replay recorded with an
+older schema".
+
 ## Recording a browser session
 
 ```ts

package/dist/Determinism.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Runs the same headless simulation twice and reports its first differing
+ * value. Supply fresh runtimes and scripted input; services and host time
+ * are inputs, not world state. Transient components are included, so this
+ * works even when the schema cannot be snapshotted.
+ *
+ * A mismatch is rerun with tracing on the differing frame to name the first
+ * system or schedule marker after which the worlds differ. If that rerun
+ * does not reproduce it, `after` is undefined: the original mismatch still
+ * fails the check. This checks repeatability on the current JS engine, not
+ * equality between platforms or every possible input sequence.
+ *
+ * @example
+ * ```ts
+ * const result = Determinism.check(({ hostClock }) => makeSimulation(hostClock), {
+ *   schedule: "update", frames: 1800, hostClock: HostClock.test()
+ * })
+ * if (!result.ok) throw new Error(JSON.stringify(result))
+ * ```
+ * @module Determinism
+ * @docGroup devtools
+ */
+import type { HostClock } from "@typeonce/ritmo";
+import type { Schema } from "@typeonce/ritmo/Schema";
+import type { AnyScheduleOrder, ExecutableScheduleDefinition } from "@typeonce/ritmo/Schedule";
+import type { Target as SessionTarget } from "./Session.ts";
+/** A fresh debug runtime, already set up, and its runnable schedules. */
+export interface Target<S extends Schema.Any, Root, Names extends string> {
+    readonly runtime: Pick<SessionTarget<S, Root>, "debug" | "tryTick">;
+    readonly schedules: Readonly<Record<Names, ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>>>;
+}
+/** Inputs supplied to each build, including diagnostic reruns. */
+export interface Context {
+    readonly hostClock: HostClock.HostClock;
+}
+/** Selects one schedule and a finite, whole number of frames to compare. */
+export interface Options<Names extends string> extends Context {
+    readonly schedule: Names;
+    readonly frames: number;
+}
+/** A mismatch names the first value; execution errors remain explicit failures. */
+export type CheckResult = {
+    readonly ok: true;
+    readonly frames: number;
+} | {
+    readonly ok: false;
+    /** 0 means the initial worlds already differ. */
+    readonly frame: number;
+    readonly reason: "difference";
+    readonly difference: string;
+    readonly first: unknown;
+    readonly second: unknown;
+    readonly after: string | undefined;
+} | {
+    readonly ok: false;
+    readonly frame: number;
+    readonly reason: "invalid-options" | "shared-runtime" | "failure" | "defect";
+    readonly run: "first" | "second";
+    readonly error: unknown;
+};
+/**
+ * Checks a schedule with identical inputs on two independently built worlds.
+ * The factory must make a fresh runtime each time (also on diagnostic
+ * reruns); it must not read live keyboard, pointer, network, or wall time.
+ * Values are compared structurally, with Object.is for primitives (NaN
+ * equals NaN). Maps and sets include iteration order. Functions compare by
+ * identity; weak collections and promises fail explicitly as uninspectable.
+ */
+export declare const check: <S extends Schema.Any, Root, const Names extends string>(make: (context: Context) => Target<S, Root, Names>, options: Options<NoInfer<Names>>) => CheckResult;
+//# sourceMappingURL=Determinism.d.ts.map

package/dist/Determinism.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Determinism.d.ts","sourceRoot":"","sources":["../src/Determinism.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAS,SAAS,EAAE,MAAM,iBAAiB,CAAA;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAA;AAC9F,OAAO,KAAK,EAAE,MAAM,IAAI,aAAa,EAAE,MAAM,cAAc,CAAA;AAE3D,yEAAyE;AACzE,MAAM,WAAW,MAAM,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,SAAS,MAAM;IACtE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC,CAAA;IACnE,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,4BAA4B,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAA;CACpH;AAED,kEAAkE;AAClE,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,SAAS,CAAA;CACxC;AAED,4EAA4E;AAC5E,MAAM,WAAW,OAAO,CAAC,KAAK,SAAS,MAAM,CAAE,SAAQ,OAAO;IAC5D,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,mFAAmF;AACnF,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC9C;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAA;IAClB,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;CACnC,GACD;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAA;IAClB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,gBAAgB,GAAG,SAAS,GAAG,QAAQ,CAAA;IAC5E,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAAA;IAChC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CACxB,CAAA;AA0CL;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,GAAI,CAAC,SAAS,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,KAAK,SAAS,MAAM,QACpE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,WACzC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,KAC/B,WAyCF,CAAA"}

package/dist/Determinism.js

@@ -0,0 +1,137 @@
+// Copy values immediately: dump values may be mutable and shared with the
+// next tick. JSON would silently discard undefined, NaN, maps, and cycles.
+const capture = (value, seen = new Map()) => {
+    if (typeof value !== "object" || value === null)
+        return { kind: typeof value, value };
+    const previous = seen.get(value);
+    if (previous !== undefined)
+        return { kind: "reference", value: previous };
+    seen.set(value, seen.size);
+    if (value instanceof Date)
+        return { kind: "Date", value: value.getTime() };
+    if (value instanceof RegExp)
+        return { kind: "RegExp", value: `${value.source}/${value.flags}/${value.lastIndex}` };
+    if (value instanceof Map)
+        return { kind: "Map", entries: [...value].map(([key, entry], index) => [String(index), capture([key, entry], seen)]) };
+    if (value instanceof Set)
+        return { kind: "Set", entries: [...value].map((entry, index) => [String(index), capture(entry, seen)]) };
+    if (value instanceof ArrayBuffer)
+        return { kind: "ArrayBuffer", entries: [...new Uint8Array(value)].map((entry, index) => [String(index), capture(entry, seen)]) };
+    if (ArrayBuffer.isView(value))
+        return { kind: value.constructor.name, entries: [...new Uint8Array(value.buffer, value.byteOffset, value.byteLength)].map((entry, index) => [String(index), capture(entry, seen)]) };
+    if (value instanceof WeakMap || value instanceof WeakSet || value instanceof Promise) {
+        throw new Error(`Determinism cannot inspect ${value.constructor.name}; keep opaque host state in a service`);
+    }
+    return {
+        kind: Array.isArray(value) ? "Array" : Object.getPrototypeOf(value)?.constructor?.name ?? "Object",
+        entries: Reflect.ownKeys(value).map((key) => [String(key), capture(Reflect.get(value, key), seen)])
+    };
+};
+const difference = (first, second, path = "world") => {
+    if (first.kind !== second.kind || !Object.is(first.value, second.value))
+        return { path, first: first.value ?? first.kind, second: second.value ?? second.kind };
+    const a = first.entries ?? [];
+    const b = second.entries ?? [];
+    for (let index = 0; index < Math.max(a.length, b.length); index++) {
+        const left = a[index];
+        const right = b[index];
+        if (left === undefined || right === undefined || left[0] !== right[0])
+            return { path: `${path}.keys[${index}]`, first: left?.[0], second: right?.[0] };
+        const found = difference(left[1], right[1], `${path}[${JSON.stringify(left[0])}]`);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+};
+/**
+ * Checks a schedule with identical inputs on two independently built worlds.
+ * The factory must make a fresh runtime each time (also on diagnostic
+ * reruns); it must not read live keyboard, pointer, network, or wall time.
+ * Values are compared structurally, with Object.is for primitives (NaN
+ * equals NaN). Maps and sets include iteration order. Functions compare by
+ * identity; weak collections and promises fail explicitly as uninspectable.
+ */
+export const check = (make, options) => {
+    if (!Number.isSafeInteger(options.frames) || options.frames < 0) {
+        return { ok: false, frame: 0, reason: "invalid-options", run: "first", error: "frames must be a finite whole number, 0 or more" };
+    }
+    const context = { hostClock: options.hostClock };
+    let run = "first";
+    let frame = 0;
+    try {
+        const first = make(context);
+        run = "second";
+        const second = make(context);
+        if (first.runtime === second.runtime || first.runtime.debug === second.runtime.debug) {
+            return { ok: false, frame: 0, reason: "shared-runtime", run, error: "the factory must build a fresh runtime each time" };
+        }
+        const a = first.schedules[options.schedule];
+        const b = second.schedules[options.schedule];
+        if (a === undefined || b === undefined)
+            return { ok: false, frame: 0, reason: "invalid-options", run, error: `unknown schedule ${options.schedule}` };
+        for (; frame <= options.frames; frame++) {
+            if (frame > 0) {
+                run = "first";
+                const result = first.runtime.tryTick(a);
+                if (!result.ok)
+                    return { ok: false, frame, reason: "failure", run, error: result.error };
+            }
+            run = "first";
+            const left = capture(first.runtime.debug.dump());
+            if (frame > 0) {
+                run = "second";
+                const result = second.runtime.tryTick(b);
+                if (!result.ok)
+                    return { ok: false, frame, reason: "failure", run, error: result.error };
+            }
+            run = "second";
+            const found = difference(left, capture(second.runtime.debug.dump()));
+            if (found !== undefined) {
+                const after = frame === 0 ? undefined : locate(make, context, options.schedule, frame);
+                return { ok: false, frame, reason: "difference", difference: found.path, first: found.first, second: found.second, after };
+            }
+        }
+        return { ok: true, frames: options.frames };
+    }
+    catch (error) {
+        return { ok: false, frame, reason: "defect", run, error };
+    }
+};
+const locate = (make, context, schedule, frame) => {
+    const stops = [];
+    try {
+        const first = make(context);
+        const second = make(context);
+        const traces = [[], []];
+        for (let index = 1; index <= frame; index++) {
+            for (const [run, target] of [first, second].entries()) {
+                if (index === frame)
+                    stops.push(target.runtime.debug.observe((event) => {
+                        const after = event.type === "system" ? event.system : event.type === "deferred" ? "applyDeferred()" : event.type === "transition" ? "applyStateTransitions()" : undefined;
+                        if (after !== undefined)
+                            traces[run].push({ after, state: capture(target.runtime.debug.dump()) });
+                    }));
+                if (!target.runtime.tryTick(target.schedules[schedule]).ok)
+                    return undefined;
+            }
+        }
+        for (let index = 0; index < Math.max(traces[0].length, traces[1].length); index++) {
+            const a = traces[0][index];
+            const b = traces[1][index];
+            if (a === undefined || b === undefined || a.after !== b.after)
+                return a?.after ?? b?.after;
+            if (difference(a.state, b.state) !== undefined)
+                return a.after;
+        }
+        return undefined;
+    }
+    catch {
+        // Diagnostic replay must not replace the original mismatch with a new error.
+        return undefined;
+    }
+    finally {
+        for (const stop of stops)
+            stop();
+    }
+};
+//# sourceMappingURL=Determinism.js.map

package/dist/Determinism.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Determinism.js","sourceRoot":"","sources":["../src/Determinism.ts"],"names":[],"mappings":"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"}

package/dist/Format.d.ts

@@ -22,6 +22,8 @@ export interface ValueOptions {
  * and print as such.
  */
 export declare const value: (input: unknown, options?: ValueOptions) => string;
+/** One transition as `Machine from -> to`; a sub-state without a value prints `(inactive)`. */
+export declare const transition: (event: Pick<Debug.TransitionEvent, "machine" | "from" | "to">) => string;
 /** One system's placements and declared access, indented under its name. */
 export declare const system: (input: Debug.SystemDescription) => string;
 /** Lints first, so they are the first thing read. */
@@ -33,7 +35,12 @@ export declare const dump: (input: Debug.WorldDump, options?: ValueOptions) => s
 /** One line per stream, then one indented line per reader. */
 export declare const streams: (input: ReadonlyArray<Debug.StreamStatus>) => string;
 /** The kinds of journal lines, for filtering. */
-export type LineKind = "write" | "resource" | "event" | "nextState" | "command" | "effect" | "failure" | "missed" | "skip" | "transition" | "restore";
+export type LineKind = "write" | "resource" | "event" | "nextState" | "command" | "effect" | "failure" | "missed" | "skip" | "transition" | "restore" | "ignored";
+/**
+ * The text for a failed tick result nobody read: who failed, with what, how
+ * many later systems did not run, and when it was found unread.
+ */
+export declare const ignoredFailure: (event: Debug.FailureIgnoredEvent, options?: ValueOptions) => string;
 /**
  * Structural equality for plain data: primitives by `Object.is`, arrays and
  * plain objects by their entries. Other objects compare by reference.

package/dist/Format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Format.d.ts","sourceRoot":"","sources":["../src/Format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,KAAK,KAAK,MAAM,uBAAuB,CAAA;AAEnD,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,uEAAuE;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAQD;;;;GAIG;AACH,eAAO,MAAM,KAAK,UAAW,OAAO,YAAW,YAAY,KAAQ,MAuDlE,CAAA;AAID,4EAA4E;AAC5E,eAAO,MAAM,MAAM,UAAW,KAAK,CAAC,iBAAiB,KAAG,MAkCvD,CAAA;AAED,qDAAqD;AACrD,eAAO,MAAM,SAAS,UAAW,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,KAAG,KAAK,CAAC,MAAM,CAGxE,CAAA;AAED,qFAAqF;AACrF,eAAO,MAAM,WAAW,UAAW,KAAK,CAAC,WAAW,KAAG,MAwDtD,CAAA;AAED,2EAA2E;AAC3E,eAAO,MAAM,IAAI,UAAW,KAAK,CAAC,SAAS,YAAW,YAAY,KAAQ,MA6BzE,CAAA;AAED,8DAA8D;AAC9D,eAAO,MAAM,OAAO,UAAW,aAAa,CAAC,KAAK,CAAC,YAAY,CAAC,KAAG,MAUlE,CAAA;AAuBD,iDAAiD;AACjD,MAAM,MAAM,QAAQ,GAChB,OAAO,GACP,UAAU,GACV,OAAO,GACP,WAAW,GACX,SAAS,GACT,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,MAAM,GACN,YAAY,GACZ,SAAS,CAAA;AAEb;;;GAGG;AACH,eAAO,MAAM,SAAS,SAAU,OAAO,SAAS,OAAO,KAAG,OAezD,CAAA;AASD;;;GAGG;AACH,eAAO,MAAM,MAAM,WAAY,OAAO,SAAS,OAAO,YAAW,YAAY,KAAQ,MAoBpF,CAAA;AAED,6CAA6C;AAC7C,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CACvB;AAED;;;GAGG;AACH,eAAO,MAAM,KAAK,UAAW,KAAK,CAAC,UAAU,YAAW,YAAY,KAAQ,aAAa,CAAC,IAAI,CAiG7F,CAAA;AAED,4CAA4C;AAC5C,eAAO,MAAM,IAAI,UAAW,IAAI,KAAG,MACgK,CAAA"}
+{"version":3,"file":"Format.d.ts","sourceRoot":"","sources":["../src/Format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,KAAK,KAAK,MAAM,uBAAuB,CAAA;AAEnD,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,uEAAuE;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAQD;;;;GAIG;AACH,eAAO,MAAM,KAAK,UAAW,OAAO,YAAW,YAAY,KAAQ,MAuDlE,CAAA;AAID,+FAA+F;AAC/F,eAAO,MAAM,UAAU,UAAW,IAAI,CAAC,KAAK,CAAC,eAAe,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAAC,KAAG,MACwD,CAAA;AAEnJ,4EAA4E;AAC5E,eAAO,MAAM,MAAM,UAAW,KAAK,CAAC,iBAAiB,KAAG,MA8CvD,CAAA;AAED,qDAAqD;AACrD,eAAO,MAAM,SAAS,UAAW,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,KAAG,KAAK,CAAC,MAAM,CAGxE,CAAA;AAED,qFAAqF;AACrF,eAAO,MAAM,WAAW,UAAW,KAAK,CAAC,WAAW,KAAG,MAkEtD,CAAA;AAED,2EAA2E;AAC3E,eAAO,MAAM,IAAI,UAAW,KAAK,CAAC,SAAS,YAAW,YAAY,KAAQ,MA6BzE,CAAA;AAED,8DAA8D;AAC9D,eAAO,MAAM,OAAO,UAAW,aAAa,CAAC,KAAK,CAAC,YAAY,CAAC,KAAG,MAUlE,CAAA;AAyBD,iDAAiD;AACjD,MAAM,MAAM,QAAQ,GAChB,OAAO,GACP,UAAU,GACV,OAAO,GACP,WAAW,GACX,SAAS,GACT,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,MAAM,GACN,YAAY,GACZ,SAAS,GACT,SAAS,CAAA;AAEb;;;GAGG;AACH,eAAO,MAAM,cAAc,UAAW,KAAK,CAAC,mBAAmB,YAAW,YAAY,KAAQ,MAS7F,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,SAAS,SAAU,OAAO,SAAS,OAAO,KAAG,OAezD,CAAA;AASD;;;GAGG;AACH,eAAO,MAAM,MAAM,WAAY,OAAO,SAAS,OAAO,YAAW,YAAY,KAAQ,MAoBpF,CAAA;AAED,6CAA6C;AAC7C,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CACvB;AAED;;;GAGG;AACH,eAAO,MAAM,KAAK,UAAW,KAAK,CAAC,UAAU,YAAW,YAAY,KAAQ,aAAa,CAAC,IAAI,CAmG7F,CAAA;AAED,4CAA4C;AAC5C,eAAO,MAAM,IAAI,UAAW,IAAI,KAAG,MACgK,CAAA"}

package/dist/Format.js

@@ -76,6 +76,8 @@ export const value = (input, options = {}) => {
     return go(input, 0);
 };
 const list = (items) => items.length === 0 ? "-" : items.join(", ");
+/** One transition as `Machine from -> to`; a sub-state without a value prints `(inactive)`. */
+export const transition = (event) => `${event.machine} ${event.from === undefined ? "(inactive)" : String(event.from)} -> ${event.to === undefined ? "(inactive)" : String(event.to)}`;
 /** One system's placements and declared access, indented under its name. */
 export const system = (input) => {
     const lines = [`${input.name}  @ ${input.placements.join(", ")}`];
@@ -88,6 +90,10 @@ export const system = (input) => {
             query.without.length > 0 ? `without ${query.without.join(", ")}` : undefined,
             query.added.length > 0 ? `added ${query.added.join(", ")}` : undefined,
             query.changed.length > 0 ? `changed ${query.changed.join(", ")}` : undefined,
+            ...query.anyOf.map((members) => `any of (${[
+                ...members.added.map((name) => `added ${name}`),
+                ...members.changed.map((name) => `changed ${name}`)
+            ].join(", ")})`),
             query.relations.length > 0 ? query.relations.join(", ") : undefined
         ].filter((part) => part !== undefined);
         lines.push(`  query ${query.slot}: ${parts.join("; ")}`);
@@ -96,7 +102,8 @@ export const system = (input) => {
         if (items.length > 0)
             lines.push(`  ${label}: ${items.join(", ")}`);
     };
-    add("reads resources", input.resources.reads);
+    add("reads resources", input.resources.reads.filter((name) => !input.resources.changed.includes(name)));
+    add("reads resources when changed", input.resources.changed);
     add("writes resources", input.resources.writes);
     add("reads events", input.events.reads);
     add("emits events", input.events.writes);
@@ -109,6 +116,14 @@ export const system = (input) => {
         lines.push("  reads despawned");
     add("reads relation failures", input.relationFailures);
     add("services", input.services);
+    add("may spawn", input.commands.spawns);
+    add("may insert", input.commands.inserts);
+    add("may remove", input.commands.removes);
+    add("may despawn", input.commands.despawns);
+    add("may despawn scope", input.commands.despawnsScope);
+    add("may relate", input.commands.relates);
+    if (input.thisTick.length > 0)
+        add("needs this tick", input.thisTick);
     add("when", input.when);
     add("pauses when", input.pauseWhen);
     if (input.local)
@@ -124,8 +139,10 @@ export const lintLines = (lints) => [
 export const description = (input) => {
     const lines = [];
     lines.push("# Components");
-    for (const component of input.components)
-        lines.push(`${component.name} (${component.storage})`);
+    for (const component of input.components) {
+        const notes = [component.storage, ...(component.immutable ? ["immutable"] : []), ...(component.requires.length > 0 ? [`requires ${component.requires.join(", ")}`] : [])];
+        lines.push(`${component.name} (${notes.join(", ")})`);
+    }
     lines.push("", "# Resources");
     for (const resource of input.resources) {
         lines.push(`${resource.name} (${resource.storage}${resource.present ? "" : ", no value"})`);
@@ -146,7 +163,14 @@ export const description = (input) => {
     if (input.machines.length > 0) {
         lines.push("", "# Machines");
         for (const machine of input.machines) {
-            lines.push(`${machine.name} = ${machine.current === undefined ? "(not provided)" : String(machine.current)}  [${machine.states.join(" | ")}]`);
+            const current = !machine.provided ? "(not provided)" : machine.current === undefined ? "(inactive)" : String(machine.current);
+            lines.push(`${machine.name} = ${current}  [${machine.states.join(" | ")}]${machine.within === undefined ? "" : `  within ${machine.within}`}`);
+        }
+    }
+    if (input.scopes.length > 0) {
+        lines.push("", "# Scopes");
+        for (const scope of input.scopes) {
+            lines.push(`${scope.name}${scope.despawnOn.length > 0 ? ` (despawned on ${scope.despawnOn.join(", ")})` : ""}`);
         }
     }
     if (input.services.length > 0) {
@@ -246,8 +270,24 @@ const effect = (input, options) => {
             return `unrelate e${input.entity} ${input.relation}`;
         case "relationFailure":
             return `relation failure e${input.entity} ${input.relation}: ${input.error}`;
+        case "requirementViolated":
+            return `skipped ${input.command} e${input.entity}: ${input.component} requires ${input.missing}`;
     }
 };
+/**
+ * The text for a failed tick result nobody read: who failed, with what, how
+ * many later systems did not run, and when it was found unread.
+ */
+export const ignoredFailure = (event, options = {}) => {
+    const who = event.system === undefined ? `${event.schedule} did not run` : `${event.system} failed`;
+    // A system failure shows what the system returned; anything else (missing requirements) as it is.
+    const error = typeof event.error === "object" && event.error !== null && event.error.kind === "SystemFailure"
+        ? event.error.error
+        : event.error;
+    const later = `${event.skipped.length} later ${event.skipped.length === 1 ? "system" : "systems"} did not run`;
+    const found = event.when === "next-tick" ? "not read before the next tick" : "not read before the session ended";
+    return `tick failure ignored: ${who} with ${value(error, options)}; ${later} (${found})`;
+};
 /**
  * Structural equality for plain data: primitives by `Object.is`, arrays and
  * plain objects by their entries. Other objects compare by reference.
@@ -319,6 +359,8 @@ export const lines = (event, options = {}) => {
             return [];
         case "restore":
             return [{ kind: "restore", frame: event.frame, schedule: "", system: undefined, entity: undefined, subject: undefined, noop: false, text: `restore ${event.ok ? "applied" : "rejected"}` }];
+        case "failure.ignored":
+            return [{ kind: "ignored", frame: event.frame, schedule: event.schedule, system: event.system, entity: undefined, subject: undefined, noop: false, text: ignoredFailure(event, options) }];
         case "transition":
             return [{
                     kind: "transition",
@@ -328,7 +370,7 @@ export const lines = (event, options = {}) => {
                     entity: undefined,
                     subject: event.machine,
                     noop: event.outcome === "unchanged",
-                    text: `transition ${event.machine} ${String(event.from)} -> ${String(event.to)} ${event.outcome}`
+                    text: `transition ${transition(event)} ${event.outcome}`
                 }];
         case "system.skipped": {
             const discarded = event.discarded.map((entry) => `${entry.count} ${entry.stream}`);