@typeonce/ritmo-devtools 0.6.0 → 0.7.0

package/dist/ReplayNodeSink.d.ts

@@ -0,0 +1,11 @@
+import type * as Replay from "./Replay.ts";
+/** Where the last replay was written, and every path written so far. */
+export interface NodeSink extends Replay.Sink {
+    readonly written: ReadonlyArray<string>;
+}
+/** The file name of a replay: its save time, then its tick count. */
+export declare const fileName: (file: Replay.ReplayFile) => string;
+export declare const make: (options: {
+    readonly directory: string;
+}) => NodeSink;
+//# sourceMappingURL=ReplayNodeSink.d.ts.map

package/dist/ReplayNodeSink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReplayNodeSink.d.ts","sourceRoot":"","sources":["../src/ReplayNodeSink.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,KAAK,MAAM,MAAM,aAAa,CAAA;AAE1C,wEAAwE;AACxE,MAAM,WAAW,QAAS,SAAQ,MAAM,CAAC,IAAI;IAC3C,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CACxC;AAED,qEAAqE;AACrE,eAAO,MAAM,QAAQ,SAAU,MAAM,CAAC,UAAU,KAAG,MACqE,CAAA;AAExH,eAAO,MAAM,IAAI,YAAa;IAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,KAAG,QAW9D,CAAA"}

package/dist/ReplayNodeSink.js

@@ -0,0 +1,29 @@
+/**
+ * A `Replay.Sink` for Node: each saved replay becomes a JSON file in a
+ * directory. For headless runs (bots, scripts) that record replays.
+ *
+ * @module ReplayNodeSink
+ * @docGroup devtools
+ *
+ * @example
+ * ```ts
+ * const recorder = Replay.recorder(runtime, { ..., sink: ReplayNodeSink.make({ directory: ".replays" }) })
+ * ```
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/** The file name of a replay: its save time, then its tick count. */
+export const fileName = (file) => `${new Date(file.savedAt).toISOString().replaceAll(":", "-")}-tick-${file.ticks.at(-1)?.tick ?? file.start.tick}.json`;
+export const make = (options) => {
+    const written = [];
+    return {
+        written,
+        save: (file) => {
+            mkdirSync(options.directory, { recursive: true });
+            const path = join(options.directory, fileName(file));
+            writeFileSync(path, `${JSON.stringify(file)}\n`);
+            written.push(path);
+        }
+    };
+};
+//# sourceMappingURL=ReplayNodeSink.js.map

package/dist/ReplayNodeSink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReplayNodeSink.js","sourceRoot":"","sources":["../src/ReplayNodeSink.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAClD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAShC,qEAAqE;AACrE,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,IAAuB,EAAU,EAAE,CAC1D,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,SAAS,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,OAAO,CAAA;AAExH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,OAAuC,EAAY,EAAE;IACxE,MAAM,OAAO,GAAkB,EAAE,CAAA;IACjC,OAAO;QACL,OAAO;QACP,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE;YACb,SAAS,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;YACjD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAA;YACpD,aAAa,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YAChD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACpB,CAAC;KACF,CAAA;AACH,CAAC,CAAA"}

package/dist/ReplayVitePlugin.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A Vite plugin (Node side) that receives the replays `ReplayViteSink`
+ * posts from the page and writes them into the game's repository as
+ * `.replays/<time>.json`, logging the path, the tick count, and the reason.
+ * Development only: it does nothing in a build.
+ *
+ * Add `.replays/` to the game's `.gitignore`.
+ *
+ * @module ReplayVitePlugin
+ * @docGroup devtools
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import * as ReplayVitePlugin from "@typeonce/ritmo-devtools/ReplayVitePlugin"
+ * export default defineConfig({ plugins: [ReplayVitePlugin.plugin()] })
+ * ```
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+/** The part of Vite's dev server the plugin uses. */
+export interface DevServer {
+    readonly middlewares: {
+        readonly use: (path: string, handler: (request: IncomingMessage, response: ServerResponse, next: () => void) => void) => void;
+    };
+    readonly config: {
+        readonly root: string;
+        readonly logger: {
+            readonly info: (message: string) => void;
+        };
+    };
+}
+/** A Vite plugin object. */
+export interface Plugin {
+    readonly name: string;
+    readonly apply: "serve";
+    readonly configureServer: (server: DevServer) => void;
+}
+export declare const plugin: (options?: {
+    readonly directory?: string;
+}) => Plugin;
+//# sourceMappingURL=ReplayVitePlugin.d.ts.map

package/dist/ReplayVitePlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReplayVitePlugin.d.ts","sourceRoot":"","sources":["../src/ReplayVitePlugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAMhE,qDAAqD;AACrD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,IAAI,KAAK,IAAI,KAAK,IAAI,CAAA;KAC9H,CAAA;IACD,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE;YAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;SAAE,CAAA;KAAE,CAAA;CAC1G;AAED,4BAA4B;AAC5B,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,eAAe,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,CAAA;CACtD;AAED,eAAO,MAAM,MAAM,aAAa;IAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,KAAQ,MAkCrE,CAAA"}

package/dist/ReplayVitePlugin.js

@@ -0,0 +1,41 @@
+import * as Replay from "./Replay.js";
+import * as ReplayNodeSink from "./ReplayNodeSink.js";
+import { endpoint } from "./ReplayViteSink.js";
+export const plugin = (options = {}) => ({
+    name: "ritmo-replays",
+    apply: "serve",
+    configureServer: (server) => {
+        const sink = ReplayNodeSink.make({ directory: `${server.config.root}/${options.directory ?? ".replays"}` });
+        server.middlewares.use(endpoint, (request, response, next) => {
+            if (request.method !== "POST")
+                return next();
+            let body = "";
+            request.setEncoding("utf8");
+            request.on("data", (chunk) => {
+                body += chunk;
+            });
+            request.on("end", () => {
+                let data;
+                try {
+                    data = JSON.parse(body);
+                }
+                catch {
+                    data = undefined;
+                }
+                const parsed = Replay.parse(data);
+                if (!parsed.ok) {
+                    response.statusCode = 400;
+                    response.end(parsed.error._tag === "InvalidReplay" ? parsed.error.message : parsed.error._tag);
+                    return;
+                }
+                sink.save(parsed.value);
+                const path = sink.written.at(-1).slice(server.config.root.length + 1);
+                const ticks = parsed.value.ticks.length;
+                server.config.logger.info(`[ritmo] replay saved: ${path} (${ticks} ticks): ${parsed.value.reason}`);
+                response.statusCode = 201;
+                response.end(path);
+            });
+        });
+    }
+});
+//# sourceMappingURL=ReplayVitePlugin.js.map

package/dist/ReplayVitePlugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReplayVitePlugin.js","sourceRoot":"","sources":["../src/ReplayVitePlugin.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAA;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAiB9C,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,OAAO,GAAoC,EAAE,EAAU,EAAE,CAAC,CAAC;IAChF,IAAI,EAAE,eAAe;IACrB,KAAK,EAAE,OAAO;IACd,eAAe,EAAE,CAAC,MAAM,EAAE,EAAE;QAC1B,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,IAAI,OAAO,CAAC,SAAS,IAAI,UAAU,EAAE,EAAE,CAAC,CAAA;QAC3G,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE;YAC3D,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM;gBAAE,OAAO,IAAI,EAAE,CAAA;YAC5C,IAAI,IAAI,GAAG,EAAE,CAAA;YACb,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAA;YAC3B,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;gBACnC,IAAI,IAAI,KAAK,CAAA;YACf,CAAC,CAAC,CAAA;YACF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE;gBACrB,IAAI,IAAa,CAAA;gBACjB,IAAI,CAAC;oBACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;gBACzB,CAAC;gBAAC,MAAM,CAAC;oBACP,IAAI,GAAG,SAAS,CAAA;gBAClB,CAAC;gBACD,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;gBACjC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;oBACf,QAAQ,CAAC,UAAU,GAAG,GAAG,CAAA;oBACzB,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,KAAK,eAAe,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;oBAC9F,OAAM;gBACR,CAAC;gBACD,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;gBACvB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAE,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;gBACtE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAA;gBACvC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,yBAAyB,IAAI,KAAK,KAAK,YAAY,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAA;gBACnG,QAAQ,CAAC,UAAU,GAAG,GAAG,CAAA;gBACzB,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;YACpB,CAAC,CAAC,CAAA;QACJ,CAAC,CAAC,CAAA;IACJ,CAAC;CACF,CAAC,CAAA"}

package/dist/ReplayViteSink.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A `Replay.Sink` for a page served by Vite in development: each saved
+ * replay is posted to the dev server, where `ReplayVitePlugin` writes it
+ * into the game's repository (`.replays/`). The page's `fetch` is passed in.
+ *
+ * @module ReplayViteSink
+ * @docGroup devtools
+ *
+ * @example
+ * ```ts
+ * if (import.meta.env.DEV) {
+ *   const sink = ReplayViteSink.make({ fetch: (url, init) => fetch(url, init) })
+ * }
+ * ```
+ */
+import type * as Replay from "./Replay.ts";
+/** The dev server's endpoint for replays (what `ReplayVitePlugin` serves). */
+export declare const endpoint = "/__ritmo/replays";
+export interface Options {
+    /** The page's `fetch` (or any function with its shape for these two arguments). */
+    readonly fetch: (url: string, init: {
+        readonly method: "POST";
+        readonly headers: Readonly<Record<string, string>>;
+        readonly body: string;
+    }) => Promise<unknown>;
+    /** Called when a post fails (the dev server is down, the plugin is not installed). */
+    readonly onError?: (error: unknown) => void;
+}
+export declare const make: (options: Options) => Replay.Sink;
+//# sourceMappingURL=ReplayViteSink.d.ts.map

package/dist/ReplayViteSink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReplayViteSink.d.ts","sourceRoot":"","sources":["../src/ReplayViteSink.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,KAAK,MAAM,MAAM,aAAa,CAAA;AAE1C,8EAA8E;AAC9E,eAAO,MAAM,QAAQ,qBAAqB,CAAA;AAE1C,MAAM,WAAW,OAAO;IACtB,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAC/J,sFAAsF;IACtF,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CAC5C;AAED,eAAO,MAAM,IAAI,YAAa,OAAO,KAAG,MAAM,CAAC,IAK7C,CAAA"}

package/dist/ReplayViteSink.js

@@ -0,0 +1,9 @@
+/** The dev server's endpoint for replays (what `ReplayVitePlugin` serves). */
+export const endpoint = "/__ritmo/replays";
+export const make = (options) => ({
+    save: (file) => {
+        void options.fetch(endpoint, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(file) })
+            .catch((error) => options.onError?.(error));
+    }
+});
+//# sourceMappingURL=ReplayViteSink.js.map

package/dist/ReplayViteSink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReplayViteSink.js","sourceRoot":"","sources":["../src/ReplayViteSink.ts"],"names":[],"mappings":"AAiBA,8EAA8E;AAC9E,MAAM,CAAC,MAAM,QAAQ,GAAG,kBAAkB,CAAA;AAS1C,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,OAAgB,EAAe,EAAE,CAAC,CAAC;IACtD,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE;QACb,KAAK,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;aAC1H,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,CAAA;IACxD,CAAC;CACF,CAAC,CAAA"}

package/dist/Session.d.ts

@@ -1,5 +1,5 @@
 /**
- * A debug session around a runtime made with `debug: true`.
+ * A debug session around a runtime made with `debug: { hostClock }`.
  *
  * The session names the schedules it drives, keeps a bounded history of
  * trace events, and answers questions about it as text and data:
@@ -8,7 +8,8 @@
  *   at the first system failure, thrown defect, or violated invariant.
  * - `journal(filter)` lists what happened, one fact per line, filtered by
  *   frames, entity, component, resource, event, machine, system, or kind.
- * - `why(entity, component)` lists the latest changes to one component.
+ * - `why(entity, component)` lists the latest changes to one component, and
+ *   the systems whose declared `spawns` could have spawned the entity.
  * - `system(name)` shows one system's declared access and recent activity.
  * - `describe()`, `dump(filter)`, `streams()` render the core debug handle.
  * - `report()` summarizes per-system timing and warnings accumulated while
@@ -34,25 +35,44 @@
  * console.log(session.journal({ frames: [180, 185], entity: 1 }))
  * ```
  */
+import { HostClock } from "@typeonce/ritmo";
 import type * as Debug from "@typeonce/ritmo/Debug";
+import type * as Inspector from "@typeonce/ritmo/Inspector";
 import type * as Machine from "@typeonce/ritmo/Machine";
 import type * as Result from "@typeonce/ritmo/Result";
-import type { ExecutableScheduleDefinition } from "@typeonce/ritmo/Schedule";
+import type * as Runtime from "@typeonce/ritmo/Runtime";
+import type { AnyScheduleOrder, ExecutableScheduleDefinition } from "@typeonce/ritmo/Schedule";
 import type { Schema } from "@typeonce/ritmo/Schema";
 import * as Format from "./Format.ts";
 import type { Invariant } from "./Invariant.ts";
 import * as Rendered from "./Rendered.ts";
 /**
- * What a session needs from a runtime: its debug handle and the dynamic
- * `tryTick`, which reports missing requirements as data.
+ * What a session needs from a runtime: its debug handle, the dynamic
+ * `tryTick`, which reports missing requirements as data, `inspect` for
+ * invariants, and what it was provided with, which invariants are checked
+ * against.
  */
-export interface Target<S extends Schema.Any, Root> {
+export interface Target<S extends Schema.Any, Root, Services extends Record<string, unknown> = Record<string, unknown>, Resources extends object = object, Machines extends Record<string, unknown> = Record<string, unknown>> {
     readonly debug: Debug.Handle<S, Root>;
-    readonly tryTick: (schedule: ExecutableScheduleDefinition<S, any, any, any, any>) => Result.Result<void, unknown>;
+    readonly tryTick: (schedule: ExecutableScheduleDefinition<S, any, any, any, any, AnyScheduleOrder>) => Result.Result<void, unknown>;
+    readonly inspect: (inspector: never) => unknown;
+    readonly services: Services;
+    readonly resourceValues: Resources;
+    readonly machineValues: Machines;
 }
-export interface Options<S extends Schema.Any, Root, Names extends string> {
+type InvariantRequirementErrors<Invariants extends ReadonlyArray<Invariant<Invariant.CheckInspector>>, Services extends Record<string, unknown>, Resources extends object, Machines extends Record<string, unknown>> = Runtime.ValidateInspector<Invariants[number]["inspector"], Services, Resources, Machines> extends {
+    readonly __fixRuntimeRequirements__: infer Errors;
+} ? Errors : never;
+/**
+ * Rejects invariants whose inspectors read a resource, service, or machine
+ * the runtime does not provide, naming each one.
+ */
+export type ValidateInvariants<Invariants extends ReadonlyArray<Invariant<Invariant.CheckInspector>>, Services extends Record<string, unknown>, Resources extends object, Machines extends Record<string, unknown>> = [InvariantRequirementErrors<Invariants, Services, Resources, Machines>] extends [never] ? unknown : {
+    readonly __fixInvariantRequirements__: InvariantRequirementErrors<Invariants, Services, Resources, Machines>;
+};
+export interface Options<S extends Schema.Any, Root, Names extends string, Invariants extends ReadonlyArray<Invariant<Invariant.CheckInspector>> = readonly []> {
     /** The schedules `run` can drive, by name. Also names them in traces. */
-    readonly schedules: Readonly<Record<Names, ExecutableScheduleDefinition<S, any, Root, any, any>>>;
+    readonly schedules: Readonly<Record<Names, ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>>>;
     /**
      * More schedules to include in `describe()`, its lints, and the access
      * maps, without making them runnable: typically a render schedule that
@@ -60,11 +80,22 @@ export interface Options<S extends Schema.Any, Root, Names extends string> {
      * and components only those schedules read are reported as never read.
      * Their services show as not provided, which is not a lint.
      */
-    readonly describe?: Readonly<Record<string, ExecutableScheduleDefinition<S, any, Root, any, any>>>;
-    /** Checked after every frame of every run. */
-    readonly invariants?: ReadonlyArray<Invariant>;
+    readonly describe?: Readonly<Record<string, ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>>>;
+    /** Events the host publishes with `runtime.send`: written, for the lints (see `Debug.Handle.declareHostEvents`). */
+    readonly hostEvents?: ReadonlyArray<Schema.EventDescriptor<S>>;
+    /**
+     * Checked after every frame of every run, in order; the first violation
+     * stops the run. Built with `Invariant.fromInspector(Game.Inspector(...))`.
+     */
+    readonly invariants?: Invariants;
     /** Frames of trace history kept for `journal` and `why`. Defaults to 600. */
     readonly history?: number;
+    /**
+     * Times runs (`RunResult.ms`). `HostClock.test()` makes every timing 0,
+     * so text output is identical across runs (give the runtime's
+     * `debug: { hostClock }` a test clock too).
+     */
+    readonly hostClock: HostClock.HostClock;
     /** Value formatting for all text output. */
     readonly format?: Format.ValueOptions;
 }
@@ -89,6 +120,12 @@ export type Stop = {
     readonly reason: "missingRequirements";
     readonly frame: number;
     readonly requirements: unknown;
+}
+/** A `Game.System.thisTick` read whose writer runs after it, or that has none; nothing ran. */
+ | {
+    readonly reason: "tickOrder";
+    readonly frame: number;
+    readonly issues: ReadonlyArray<string>;
 } | {
     readonly reason: "defect";
     readonly frame: number;
@@ -98,6 +135,20 @@ export type Stop = {
     readonly frame: number;
     readonly invariant: string;
     readonly message: string;
+}
+/**
+ * A failed tick result nobody read (for example a setup tick the game ran
+ * before this run): `frame` is the failed tick's, `skipped` the systems
+ * that did not run then.
+ */
+ | {
+    readonly reason: "ignored-failure";
+    readonly frame: number;
+    readonly schedule: string;
+    readonly system: string | undefined;
+    readonly error: unknown;
+    readonly skipped: ReadonlyArray<string>;
+    readonly when: "next-tick" | "session-end";
 };
 export interface RunResult {
     readonly schedule: string;
@@ -163,7 +214,7 @@ export interface SystemStats {
     readonly maxMs: number;
 }
 export interface Warning {
-    readonly code: "missed-read" | "pending-commands" | "pending-next-state" | "transition-failed" | "discarded-messages" | "sent-event-unread" | "system-failed" | "non-finite-value" | "population-growing";
+    readonly code: "missed-read" | "pending-commands" | "pending-next-state" | "transition-failed" | "discarded-messages" | "sent-event-unread" | "system-failed" | "non-finite-value" | "population-growing" | "ignored-failure";
     readonly message: string;
     readonly count: number;
     readonly firstFrame: number;
@@ -208,5 +259,6 @@ export interface Session<S extends Schema.Any, Names extends string> {
     /** Stops tracing. Queries keep working on the history recorded so far. */
     readonly close: () => void;
 }
-export declare const make: <S extends Schema.Any, Root, const Names extends string>(runtime: Target<S, Root>, options: Options<S, Root, Names>) => Session<S, Names>;
+export declare const make: <S extends Schema.Any, Root, Services extends Record<string, unknown>, Resources extends object, Machines extends Record<string, unknown>, const Names extends string, const Invariants extends ReadonlyArray<Invariant<Inspector.InspectorDefinition<any, string | undefined, Root, any, any>>> = readonly []>(runtime: Target<S, Root, Services, Resources, Machines>, options: Options<S, Root, Names, Invariants> & ValidateInvariants<Invariants, Services, Resources, Machines>) => Session<S, Names>;
+export {};
 //# sourceMappingURL=Session.d.ts.map

package/dist/Session.d.ts.map

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

package/dist/Session.js

@@ -1,3 +1,41 @@
+/**
+ * A debug session around a runtime made with `debug: { hostClock }`.
+ *
+ * The session names the schedules it drives, keeps a bounded history of
+ * trace events, and answers questions about it as text and data:
+ *
+ * - `run(name, { frames, until })` ticks a schedule frame by frame and stops
+ *   at the first system failure, thrown defect, or violated invariant.
+ * - `journal(filter)` lists what happened, one fact per line, filtered by
+ *   frames, entity, component, resource, event, machine, system, or kind.
+ * - `why(entity, component)` lists the latest changes to one component, and
+ *   the systems whose declared `spawns` could have spawned the entity.
+ * - `system(name)` shows one system's declared access and recent activity.
+ * - `describe()`, `dump(filter)`, `streams()` render the core debug handle.
+ * - `report()` summarizes per-system timing and warnings accumulated while
+ *   tracing: missed reads, commands still pending at the end of a frame,
+ *   failed transitions, skipped systems that discarded messages, NaN or
+ *   infinite numbers written anywhere, and entity counts that keep growing
+ *   through a run.
+ *
+ * Everything returns a `Rendered` value that prints as text.
+ *
+ * @module Session
+ * @docGroup devtools
+ *
+ * @example
+ * ```ts
+ * const session = Session.make(runtime, {
+ *   schedules: { setup: setupSchedule, update: updateSchedule },
+ *   invariants: [PlayerInsideWorld]
+ * })
+ * session.run("setup")
+ * console.log(session.run("update", { frames: 300 }))
+ * console.log(session.why(1, Position))
+ * console.log(session.journal({ frames: [180, 185], entity: 1 }))
+ * ```
+ */
+import { HostClock } from "@typeonce/ritmo";
 import * as Format from "./Format.js";
 import * as Rendered from "./Rendered.js";
 import { nonFinitePath } from "./internal/values.js";
@@ -25,6 +63,7 @@ const growsSteadily = (samples) => {
 };
 const describeError = (error) => typeof error === "object" && error !== null ? error : {};
 export const make = (runtime, options) => {
+    const inspect = runtime.inspect;
     const debug = runtime.debug;
     const capacity = options.history ?? 600;
     const format = options.format ?? {};
@@ -35,6 +74,7 @@ export const make = (runtime, options) => {
             throw new Error(`Session: "${name}" is both a runnable and a described-only schedule`);
     }
     debug.nameSchedules({ ...described, ...schedules });
+    debug.declareHostEvents(options.hostEvents ?? []);
     const history = [];
     let current = { frame: debug.frame(), events: [] };
     history.push(current);
@@ -158,6 +198,10 @@ export const make = (runtime, options) => {
                     }
                 }
                 break;
+            case "failure.ignored":
+                ignored = event;
+                warn("ignored-failure", `ignored:${event.frame}`, Format.ignoredFailure(event, format), event.frame);
+                break;
             case "transition":
                 if (event.outcome !== "failed")
                     pendingStates.delete(event.machine);
@@ -167,6 +211,13 @@ export const make = (runtime, options) => {
                 break;
         }
     };
+    /** The last `failure.ignored` event seen, for `run` to stop on. */
+    let ignored;
+    const takeIgnored = () => {
+        const found = ignored;
+        ignored = undefined;
+        return found;
+    };
     const stopObserving = debug.observe(record);
     const historyRange = () => {
         const first = history.find((entry) => entry.events.length > 0);
@@ -175,7 +226,7 @@ export const make = (runtime, options) => {
     const run = (name, runOptions = {}) => {
         const schedule = schedules[name];
         const frames = runOptions.frames ?? 1;
-        const started = performance.now();
+        const started = options.hostClock.now();
         const warningsBefore = new Map([...warnings].map(([key, warning]) => [key, warning.count]));
         const initial = debug.population();
         const entityCounts = [];
@@ -189,6 +240,7 @@ export const make = (runtime, options) => {
         let first;
         let last;
         let stop = { reason: "completed" };
+        takeIgnored();
         for (let index = 0; index < frames; index++) {
             let result;
             try {
@@ -205,17 +257,25 @@ export const make = (runtime, options) => {
             first ??= frame;
             last = frame;
             sample();
+            const unread = takeIgnored();
+            if (unread !== undefined) {
+                const { type: _type, ...found } = unread;
+                stop = { reason: "ignored-failure", ...found };
+                break;
+            }
             if (!result.ok) {
                 const error = describeError(result.error);
                 stop = error.kind === "MissingRuntimeRequirements"
                     ? { reason: "missingRequirements", frame, requirements: error.requirements }
-                    : { reason: "failure", frame, system: typeof error.system === "string" ? error.system : "(unknown)", error: error.error };
+                    : error.kind === "TickOrderViolation"
+                        ? { reason: "tickOrder", frame, issues: (error.issues ?? []).map((issue) => issue.message) }
+                        : { reason: "failure", frame, system: typeof error.system === "string" ? error.system : "(unknown)", error: error.error };
                 break;
             }
             const violation = (options.invariants ?? []).reduce((found, invariant) => {
                 if (found)
                     return found;
-                const message = invariant.check();
+                const message = inspect(invariant.inspector);
                 return message === undefined ? undefined : { invariant: invariant.name, message };
             }, undefined);
             if (violation) {
@@ -254,7 +314,7 @@ export const make = (runtime, options) => {
             frames: first === undefined || last === undefined ? 0 : last - first + 1,
             range: first === undefined || last === undefined ? undefined : [first, last],
             stop,
-            ms: performance.now() - started,
+            ms: HostClock.elapsed(started, options.hostClock.now()),
             lintWarnings: lintWarnings.length,
             warnings: raised,
             entities: range(initial.entities, entityCounts),
@@ -319,11 +379,28 @@ export const make = (runtime, options) => {
             : component.name in currentValue.components
                 ? `e${entity} ${component.name} is now ${Format.value(currentValue.components[component.name], format)}`
                 : `e${entity} has no ${component.name} now`;
-        const header = lines.length === 0
+        const changes = lines.length === 0
             ? `${now}; no change to it in ${rangeText()}`
             : `${now}; last ${lines.length} changes (oldest first):`;
+        const spawners = spawnersOf(currentValue === undefined ? [component.name] : Object.keys(currentValue.components), component.name);
+        const header = `${changes}\n${spawners.length === 0
+            ? `no described system declares spawns of ${component.name}`
+            : `could have spawned it: ${spawners.join(", ")}`}`;
         return Rendered.make(lines, renderLines(header, lines));
     };
+    /**
+     * The described systems whose declared `spawns` include `component` and
+     * cover every component the entity has that no described system may
+     * insert (so it can only have come from the spawn).
+     */
+    const spawnersOf = (has, component) => {
+        const systems = debug.describe().systems;
+        const insertable = new Set(systems.flatMap((system) => system.commands.inserts));
+        const fromSpawn = has.filter((name) => !insertable.has(name));
+        return systems
+            .filter((system) => system.commands.spawns.includes(component) && fromSpawn.every((name) => system.commands.spawns.includes(name)))
+            .map((system) => system.name);
+    };
     const whyResource = (resource, whyOptions = {}) => {
         const lines = collectLines({ resource, kinds: ["resource"], limit: whyOptions.limit ?? 5 });
         const resources = debug.dump({ limit: 0 }).resources;
@@ -359,6 +436,8 @@ export const make = (runtime, options) => {
         return Rendered.make(data, lines.join("\n"));
     };
     const report = () => {
+        // The report is where a session ends: a failure still unread shows here.
+        debug.checkIgnoredFailures();
         const systems = [...stats.keys()].map((name) => statsFor(name)).sort((left, right) => right.totalMs - left.totalMs);
         const data = {
             frames: debug.frame(),
@@ -406,7 +485,10 @@ export const make = (runtime, options) => {
         },
         report,
         frame: () => debug.frame(),
-        close: stopObserving
+        close: () => {
+            debug.checkIgnoredFailures();
+            stopObserving();
+        }
     };
 };
 const renderRun = (result, format) => {
@@ -426,6 +508,10 @@ const renderRun = (result, format) => {
             return `${head}, DEFECT at f${stop.frame}: ${stop.error instanceof Error ? stop.error.stack ?? stop.error.message : Format.value(stop.error, format)}`;
         case "invariant":
             return `${head}, INVARIANT "${stop.invariant}" violated at f${stop.frame}: ${stop.message}`;
+        case "tickOrder":
+            return `${head}, NOT RUN after f${stop.frame}: ${stop.issues.join("; ")}`;
+        case "ignored-failure":
+            return `${head}, STOPPED: ${Format.ignoredFailure({ type: "failure.ignored", ...stop }, format)}, at f${stop.frame}`;
     }
 };
 //# sourceMappingURL=Session.js.map