@irtio/cli 0.5.2 → 0.7.0

package/dist/simulate.d.ts

@@ -1,6 +1,46 @@
-import { RunEnd, SimulationReport, TickHealthReading } from '@irtio/bots';
+import { ScenarioDefinition, BotConditions, NetworkConditions, AssertionResult, RunEnd, SimulationReport, HitRow, TruthDiff, TickHealthReading } from '@irtio/bots';
 import { AnySchema } from '@irtio/schema';
 
+/**
+ * D41: loading a scenario file, and reading the recorded authoritative timeline back off the dev
+ * server.
+ *
+ * Loading follows `loadProjectSchema`'s pattern exactly: esbuild the user's TypeScript to ESM,
+ * dynamic-import it with a cache-busting query, and shape-check the export. `bundleRoom` is the
+ * wrong tool here for the same reason it is wrong for a schema module, only more so: it enforces
+ * the room sandbox's fixed import menu, and a scenario's whole point is that it imports
+ * `@irtio/bots`.
+ *
+ * Reading follows the tick counters' pattern exactly: the dev server's own inspector routes, on
+ * the socket's port. A deployed tenant has no authoritative tap, so it has no timeline either,
+ * and this module says so rather than inventing one from what a client received.
+ */
+
+/**
+ * A scenario that could not be loaded, or a timeline that could not be recorded. Both are "the
+ * run was not performed" rather than "the room failed": nothing was measured either way, and
+ * reporting a scenario as passing because its assertions never ran would be the worst outcome
+ * this command can produce.
+ */
+declare class ScenarioNotRunError extends Error {
+    readonly cause?: unknown | undefined;
+    readonly name = "ScenarioNotRunError";
+    constructor(message: string, cause?: unknown | undefined);
+}
+interface LoadScenarioOptions {
+    readonly cwd: string;
+    readonly outDir: string;
+    /** The scenario file, absolute or relative to `cwd`. */
+    readonly file: string;
+    /** Redirects `@irtio/*` for the bundle; the monorepo's own `src/` by default. */
+    readonly irtioPackages?: Record<string, string> | undefined;
+}
+/** Bundles the scenario module and returns its default export. */
+declare function loadScenario(options: LoadScenarioOptions): Promise<{
+    scenario: ScenarioDefinition;
+    file: string;
+}>;
+
 /**
  * `irtio simulate`: point N real clients at a running room, play it randomly for a few
  * seconds, and print a pass/fail line per built-in invariant.
@@ -19,16 +59,35 @@ interface SimulateArgs {
     bots: number;
     seconds: number;
     cheat: boolean;
+    /** D42: bots named by `--cheat-bot`. Empty means "whatever `cheat` says". */
+    cheatBots?: number[];
+    /** D42: `--conditions`, applied to every bot. */
+    conditions?: NetworkConditions;
+    /** D42: `--conditions-bot <index>:<json>`, overriding `conditions` for those indices. */
+    conditionsPerBot?: Record<number, NetworkConditions>;
+    /** D43: `--truth`, take a save at the end of the run and diff it against the clients. */
+    truth?: boolean;
     room?: string;
     url?: string;
     key?: string;
     trace?: string;
+    scenario?: string;
     mispredictionMax?: number;
     snapsMax?: number;
     correctionsMax?: number;
     overrunsMax?: number;
+    /** D65: give every bot a bandwidth ledger and print the run's breakdown. */
+    profile?: boolean;
+    /** D65: rows in that table. Implies `profile`. */
+    profileTop?: number;
+    /** Queue for rooms instead of building one. Needs `control`. */
+    queue?: string;
+    /** The control plane the queue lives on. `irtio dev` runs none. */
+    control?: string;
+    /** Group this many consecutive bots into one party each. */
+    party?: number;
 }
-declare const USAGE = "usage: irtio simulate [options]\n\nDrives N real clients at a running room and checks the built-in invariants. Run it from a project\ndirectory so it can load irtio/schema.ts; without one it falls back to a relay run.\n\noptions:\n  --bots <n>                  how many clients to spawn (default 5)\n  --seconds <n>               how long to play for (default 10)\n  --room <code>               join this room instead of creating one\n  --url <ws://...>            where to connect (default ws://localhost:7070)\n  --key <projectKey>          the project key to present\n  --trace <path>              write the frame trace here\n  --cheat                     send illegal writes and expect corrections\n  --misprediction-max <units> fail if one correction snaps a prediction further than this\n  --snaps-max <n>             fail above this many cap-exceeded reconciliations\n  --corrections-max <perSec>  fail above this correction rate per bot\n  --overruns-max <n>          fail above this many server tick overruns in the run window\n                              (default 0; the count is read from the server, and the run says\n                              so when it could not be read)\n  -h, --help                  print this\n\nexit codes: 0 every invariant held, 1 something was measured and failed, 2 the run could not be\nperformed (nobody joined, or it passed its wall-clock ceiling).\n";
+declare const USAGE = "usage: irtio simulate [options]\n\nDrives N real clients at a running room and checks the built-in invariants. Run it from a project\ndirectory so it can load irtio/schema.ts; without one it falls back to a relay run.\n\noptions:\n  --bots <n>                  how many clients to spawn (default 5)\n  --seconds <n>               how long to play for (default 10)\n  --room <code>               join this room instead of creating one\n  --url <ws://...>            where to connect (default ws://localhost:7070)\n  --key <projectKey>          the project key to present\n  --trace <path>              write the frame trace here\n  --scenario <file>           run a scenario module and assert against the recorded timeline\n  --cheat                     send illegal writes and expect corrections, from every bot\n  --cheat-bot <index>         only this bot cheats (repeatable)\n  --conditions <json>         inject network conditions into every bot, e.g.\n                              '{\"rttMs\":200,\"jitterMs\":20,\"loss\":0.02}'. Keys: rttMs, jitterMs,\n                              loss, duplicate, reorder, reorderMs. Loss, duplicate and reorder\n                              touch state frames only, so a join always completes\n  --conditions-bot <i>:<json> conditions for one bot, overriding --conditions (repeatable)\n  --truth                     save the room at the end and diff it against what each client\n                              received, within that client's visibility\n  --misprediction-max <units> fail if one correction snaps a prediction further than this\n  --snaps-max <n>             fail above this many cap-exceeded reconciliations\n  --corrections-max <perSec>  fail above this correction rate per bot\n  --overruns-max <n>          fail above this many server tick overruns in the run window\n                              (default 0; the count is read from the server, and the run says\n                              so when it could not be read)\n  --queue <name>              queue for rooms through the matchmaker instead of creating one:\n                              every bot calls the real match API and joins the room its ticket\n                              names. Needs --control\n  --control <https://...>     the control plane the queue lives on. `irtio dev` runs none, so a\n                              queued run points at a real one (staging, or a test plane)\n  --party <n>                 group each n consecutive bots into one party, so they queue\n                              together and land in one room. Needs --queue\n  --profile                   print where the run's bytes went, by collection and field, as the\n                              bots saw them\n  --profile-top <n>           rows in that table (default 12; implies --profile)\n  -h, --help                  print this\n\nexit codes: 0 every invariant held, 1 something was measured and failed, 2 the run could not be\nperformed (nobody joined, or it passed its wall-clock ceiling).\n";
 /** Hand-rolled, like `parseDevArgs`: the CLI has no argument-parsing dependency. */
 declare function parseSimulateArgs(args: readonly string[]): SimulateArgs;
 interface LoadSchemaOptions {
@@ -47,6 +106,7 @@ declare function loadProjectSchema(options: LoadSchemaOptions): Promise<{
 } | undefined>;
 /** The shared world-builder's exports, as `joinRoom({ physics })` wants them. */
 interface LoadedWorld {
+    readonly engine: 'rapier3d';
     readonly gravity: {
         x: number;
         y: number;
@@ -58,12 +118,88 @@ interface LoadedWorld {
     readonly intents?: Record<string, (...args: never[]) => void> | undefined;
     readonly file: string;
 }
+/**
+ * D73-a: a matter2d world, as `joinRoom({ physics2d })` wants it.
+ *
+ * `bugs.md` #21 taught this loader to *recognise* a 2D world rather than refuse it, and stopped
+ * there, on a comment saying matter2d had no client prediction. That stopped being true when
+ * `joinRoom({ physics2d })` shipped (M5 part 4.5), so a 2D world is now loaded to be predicted
+ * with, exactly as the Rapier one is.
+ *
+ * The source is the shared world module, which exports `gravity` (2D) and whichever of `timestep`,
+ * `setup`, `bodies`, `intents` and `settle` it has — the same object a browser hands
+ * `joinRoom({ physics2d })`. The room's own `physics` declaration is deliberately **not** a
+ * source: it is the server's half, and the client half (`settle`, the per-step force over the
+ * bodies nobody steers, and the exact timestep) is written on the client. A world built from the
+ * room alone would leave every unsteered body hanging in the air locally and be corrected on
+ * every tick, which is a worse answer than not predicting.
+ */
+interface LoadedWorld2d {
+    readonly engine: 'matter2d';
+    readonly gravity: {
+        x: number;
+        y: number;
+    };
+    readonly timestep?: number | undefined;
+    readonly setup?: ((engine: unknown, matter: unknown) => void) | undefined;
+    readonly bodies?: Record<string, (...args: never[]) => unknown> | undefined;
+    readonly intents?: Record<string, (...args: never[]) => void> | undefined;
+    readonly settle?: Record<string, (...args: never[]) => void> | undefined;
+    /**
+     * The three tuning numbers `ClientPhysics2dOptions` takes, when the world module states them.
+     *
+     * `epsilon` is the one that matters and it is the one nobody expects: it is a distance in the
+     * world's own units, and its default (0.05) is sized for a metre-scale world. A matter.js world
+     * in pixels — matter's own convention, and what every matter.js tutorial writes — is two orders
+     * of magnitude coarser, so the default calls every ordinary contact resolution a misprediction.
+     * A world that states its scale here gets the same suppression a metre-scale world gets for free.
+     */
+    readonly epsilon?: number | undefined;
+    readonly maxPredictedBodies?: number | undefined;
+    readonly smoothingHalfLifeMs?: number | undefined;
+    readonly file: string;
+}
+/**
+ * A matter2d project this loader recognises and cannot predict from: run it, say why in one
+ * sentence, and never pretend to a predictor that does not exist.
+ *
+ * `bugs.md` #21 introduced this for every matter2d project, because there was no client
+ * prediction at all. D73-a narrows it to the two cases that are still true: a world module with
+ * no `bodies` (there is nothing to build), and an **inert** one — no `intents`, no `settle`, and
+ * zero gravity, so nothing in a local world built from it could ever move a body.
+ * `examples/matter-chase` is the second case by design: its room applies thrust by hand inside
+ * `tick()`, so there is no steering hook to share and its own client does not predict either.
+ */
+interface UnpredictedWorld {
+    readonly engine: 'matter2d';
+    /** One sentence, printed by the run, naming what would have to change. */
+    readonly why: string;
+    readonly file: string;
+}
+type LoadedAnyWorld = LoadedWorld | LoadedWorld2d | UnpredictedWorld;
+/** Narrows a loaded world to a matter2d one bots can predict with. */
+declare function is2dWorld(world: LoadedAnyWorld | undefined): world is LoadedWorld2d;
+declare function isUnpredictedWorld(world: LoadedAnyWorld | undefined): world is UnpredictedWorld;
+/**
+ * D73-a: does this project's room declare matter2d?
+ *
+ * The one question the room module is asked, and the reason it is asked at all: a matter2d project
+ * whose world module is not a client world — `games/dive`, whose engine gravity is zero and
+ * applied per body, so there is no `gravity` to export and its `physics2d` block is composed in
+ * `main.ts` — used to be refused at the door with "does not export a { x, y, z } gravity", which
+ * is why `irtio simulate` had never been run against dive at all. Recognising it here turns that
+ * refusal into a run with a sentence.
+ *
+ * `undefined` for every other answer: no room module, one that will not build or import, or one
+ * declaring another engine. None of those is an error here — the world module's own error is the
+ * right one to raise.
+ */
+declare function detectMatter2dRoom(options: LoadSchemaOptions): Promise<string | undefined>;
 /**
  * Bundles and imports the project's shared world-builder module, so the bots predict physics the
- * way a browser client would. The engine stays external — it must be the project's own copy,
- * resolved at import time, exactly as a room bundle resolves it.
+ * way a browser client would.
  */
-declare function loadProjectWorld(options: LoadSchemaOptions): Promise<LoadedWorld | undefined>;
+declare function loadProjectWorld(options: LoadSchemaOptions): Promise<LoadedAnyWorld | undefined>;
 /**
  * The build-twice determinism check: builds two worlds from the shared `setup` and compares
  * Rapier's own snapshots byte for byte. A builder that is not pure over synced inputs
@@ -72,6 +208,23 @@ declare function loadProjectWorld(options: LoadSchemaOptions): Promise<LoadedWor
  * description, or `undefined` when the worlds agree.
  */
 declare function checkWorldDeterminism(world: LoadedWorld): Promise<string | undefined>;
+/**
+ * D73-a: the matter2d determinism check.
+ *
+ * The Rapier check compares two `takeSnapshot()` byte strings, and matter.js has no snapshot at
+ * all (`packages/runtime/src/core/matter.ts`'s header says so), so this one is built the only way
+ * that is left: build the world twice through the engine the runtime loads, step both the same
+ * number of times with the same (empty) intent stream, and compare every body's pose and velocity
+ * through a canonical encoding. Two builds that disagree came from a builder that is not pure over
+ * synced inputs, which is the same fault the Rapier check catches and the same reason it matters —
+ * every "misprediction" it causes is blamed on netcode.
+ *
+ * Stepping, rather than comparing the two worlds as built, is what makes it catch randomness that
+ * is small at t=0: a crate spawned a thousandth of a unit off lands in a different place. The body
+ * factories are exercised too, against each collection's zero record, so a `Math.random()` in a
+ * factory is caught and not only one in `setup`.
+ */
+declare function checkWorld2dDeterminism(world: LoadedWorld2d, schema?: AnySchema): Promise<string | undefined>;
 /**
  * The dev server's JSON view, which is where a local run reads the server's own tick counters.
  * `irtio dev` serves it on the socket's own port; nothing else does, and that is deliberate — a
@@ -82,6 +235,41 @@ interface RoomTickCounters {
     readonly overruns?: number;
     readonly maxTickMs?: number;
 }
+/**
+ * `bugs.md` #16: which build of the room a run tested.
+ *
+ * A `simulate` report used to name the room code, the bot count and the URL, and nothing that
+ * identified the code under test. That is a false-green generator: edit `irtio/room.ts`, forget
+ * that an older `dev` is still holding the port, and the run measures the bundle you replaced.
+ * The information already existed on the inspector; nothing read it.
+ *
+ * Both fields matter and neither is redundant. The bundle hash catches an edit the server never
+ * picked up; the start time catches the case the hash cannot see, which is a *different process*
+ * that happens to be serving an identical bundle, and it is the field that tells a reader the
+ * server they thought they had restarted did not restart.
+ */
+interface BuildIdentity {
+    /** The bundle hash the server is serving, as `irtio dev` prints it at startup. */
+    readonly bundleHash?: string;
+    /** The schema hash behind that bundle, when the server knows one. */
+    readonly schemaHash?: string;
+    /** Epoch ms when the serving process booted. */
+    readonly startedAt?: number;
+    /** Where it was read from. */
+    readonly source?: string;
+    /** Why there is no identity, when there is none. Never both this and the fields above. */
+    readonly unavailable?: string;
+}
+/**
+ * Reads the serving build's identity off the dev inspector, or says why it could not.
+ *
+ * Deliberately shaped like `readTickCounters`: a deployed tenant does not serve `state.json`, so
+ * against staging this returns an `unavailable` sentence rather than a wrong answer. An unknown
+ * build is a fact worth printing, and printing nothing is what caused the bug.
+ */
+declare function readBuildIdentity(wsUrl: string): Promise<BuildIdentity>;
+/** The one line `bugs.md` #16 asked for, beside the URL in the report header. */
+declare function formatBuildIdentity(build: BuildIdentity): string;
 /**
  * Reads one room's tick counters off the dev server, or explains why it could not. Every failure
  * path returns a sentence rather than a zero: the `tick-health` invariant has an `unavailable`
@@ -126,6 +314,12 @@ interface RunSimulationOptions extends Partial<SimulateArgs> {
      * is a fatal run condition, not a clean end.
      */
     readonly ceilingMs?: number;
+    /**
+     * D73-c: how long a queued bot waits for its ticket. The control plane caps this at two minutes
+     * and applies its own default (30 s) when it is omitted; a run that wants to see a queue *not*
+     * fill needs a bound shorter than its own patience.
+     */
+    readonly matchTimeoutMs?: number;
     /** @internal Test seam, same as `startDev`'s. */
     readonly irtioPackages?: Record<string, string> | undefined;
 }
@@ -146,13 +340,67 @@ declare class RunNotPerformedError extends Error {
  * are the two fatal run conditions, and both still print the report and write the trace.
  */
 type SimulationEnd = RunEnd | 'ceiling';
+/** D42: the adversarial section. Present whenever anything was injected or anyone cheated. */
+interface AdversarialRun {
+    /** Per bot: what was injected and what the wrapper counted. */
+    readonly conditions: readonly BotConditions[];
+    /** Bot indices that cheated. */
+    readonly cheated: readonly number[];
+    /** Corrections drawn per cheating bot, in the same order as `cheated`. */
+    readonly correctionsPerCheater: readonly number[];
+}
+/** D41: what a scenario run adds to the report. Absent when no `--scenario` ran. */
+interface ScenarioRun {
+    readonly file: string;
+    /** Every assertion the scenario ran, in order. */
+    readonly assertions: readonly AssertionResult[];
+    readonly ok: boolean;
+    /** Recorded ticks the assertions could read. */
+    readonly ticks: number;
+    /** Ticks the recorder's caps evicted. Non-zero means the recording is a tail. */
+    readonly dropped: number;
+    /** Where the recording was written, so a failed run can be re-read without re-running it. */
+    readonly timelinePath: string;
+}
+/** D43: the truth-seam section, when a run asked for one. */
+interface TruthRun {
+    /** The diff, when a save was taken and decoded. */
+    readonly diff?: TruthDiff;
+    /** The save generation the diff read. */
+    readonly saveId?: string;
+    /**
+     * The decoded save's state, in `inspectState` shape. Carried because it is the only place a
+     * caller can read what the server actually held without starting a room, which is the whole
+     * point of the decoder, and because a test asserting "the illegal write was accepted" has to
+     * read authoritative state rather than infer it from a correction that did not arrive.
+     */
+    readonly saveState?: Record<string, unknown>;
+    /** Why there is no diff, when there is none. Never both this and `diff`. */
+    readonly error?: string;
+}
 interface SimulationRun {
     readonly report: SimulationReport;
     readonly tracePath: string;
+    /** `bugs.md` #16: which build of the room this run tested, or why that is not knowable. */
+    readonly build: BuildIdentity;
+    /** D41: the scenario section, when `--scenario` ran one. */
+    readonly scenario?: ScenarioRun;
+    /** D42: what was injected per bot, and which bots cheated. */
+    readonly adversarial?: AdversarialRun;
+    /** D42: one row per `bot.shot(...)`. Absent when nothing fired. */
+    readonly hits?: readonly HitRow[];
+    /** D43: the truth-seam verdict. Absent unless the run asked for it. */
+    readonly truth?: TruthRun;
     /** `false` when there was no schema module and the run fell back to a relay simulation. */
     readonly schema: boolean;
     /** `true` when the bots predicted physics from a shared world-builder module (D22 part 2). */
     readonly predicted: boolean;
+    /** D73-c: bots that never got a ticket. Empty on a run that did not queue. */
+    readonly matchFailures: readonly {
+        requested: number;
+        code: string;
+        message: string;
+    }[];
     /** Result of the build-twice world-builder check: the failure text, or `undefined` if it held
      *  (or did not apply). A failure also fails the run. */
     readonly worldError?: string;
@@ -169,4 +417,4 @@ interface SimulationRun {
 declare function runSimulation(options?: RunSimulationOptions): Promise<SimulationRun>;
 declare function simulate(args: readonly string[]): Promise<void>;
 
-export { type LoadSchemaOptions, RunNotPerformedError, type RunSimulationOptions, type SimulateArgs, type SimulationEnd, type SimulationRun, USAGE, ceilingFor, checkWorldDeterminism, loadProjectSchema, loadProjectWorld, parseSimulateArgs, readTickCounters, runSimulation, simulate, stateUrlFor, tickHealthFrom };
+export { type AdversarialRun, type BuildIdentity, type LoadSchemaOptions, type LoadedAnyWorld, type LoadedWorld2d, RunNotPerformedError, type RunSimulationOptions, ScenarioNotRunError, type ScenarioRun, type SimulateArgs, type SimulationEnd, type SimulationRun, type TruthRun, USAGE, type UnpredictedWorld, ceilingFor, checkWorld2dDeterminism, checkWorldDeterminism, detectMatter2dRoom, formatBuildIdentity, is2dWorld, isUnpredictedWorld, loadProjectSchema, loadProjectWorld, loadScenario, parseSimulateArgs, readBuildIdentity, readTickCounters, runSimulation, simulate, stateUrlFor, tickHealthFrom };