@irtio/cli 0.5.1 → 0.6.0

package/dist/simulate.d.ts

@@ -1,6 +1,46 @@
-import { SimulationReport } 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,14 +59,29 @@ 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;
 }
+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  --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 {
@@ -61,7 +116,14 @@ interface LoadedWorld {
  * 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.
  */
-declare function loadProjectWorld(options: LoadSchemaOptions): Promise<LoadedWorld | undefined>;
+/** `bugs.md` #21: a 2D world module, recognised rather than refused. There is nothing to predict
+ *  from it in this release, so the caller drops the predicted-world path and runs anyway. */
+interface UnpredictedWorld {
+    readonly unpredicted: 'matter2d';
+    readonly file: string;
+}
+declare function isUnpredictedWorld(world: LoadedWorld | UnpredictedWorld | undefined): world is UnpredictedWorld;
+declare function loadProjectWorld(options: LoadSchemaOptions): Promise<LoadedWorld | UnpredictedWorld | 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
@@ -70,6 +132,76 @@ declare function loadProjectWorld(options: LoadSchemaOptions): Promise<LoadedWor
  * description, or `undefined` when the worlds agree.
  */
 declare function checkWorldDeterminism(world: LoadedWorld): 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
+ * deployed tenant's counters belong to the control plane, not to whoever can reach the socket.
+ */
+declare function stateUrlFor(wsUrl: string): string | undefined;
+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`
+ * state precisely so that "the room dropped no ticks" and "nobody asked the room" stay different
+ * answers.
+ */
+declare function readTickCounters(wsUrl: string, roomId: string): Promise<{
+    counters?: RoomTickCounters;
+    unavailable?: string;
+    source?: string;
+}>;
+/**
+ * The run-window reading: overruns are a lifetime counter on the server, so the window is the
+ * difference between a baseline taken as the bots came up and a reading taken as they went down.
+ * `maxTickMs` has no windowed form (it is a running maximum) and is reported as what it is.
+ */
+declare function tickHealthFrom(before: {
+    counters?: RoomTickCounters;
+    unavailable?: string;
+    source?: string;
+}, after: {
+    counters?: RoomTickCounters;
+    unavailable?: string;
+    source?: string;
+}): TickHealthReading;
 interface RunSimulationOptions extends Partial<SimulateArgs> {
     /** Project root; defaults to `process.cwd()`. */
     readonly cwd?: string;
@@ -80,12 +212,86 @@ interface RunSimulationOptions extends Partial<SimulateArgs> {
      * hardware can burst past the cursor-tuned default without anything being wrong.
      */
     readonly correctionsPerSecMax?: number;
+    /** D36: initial-join bound, passed through to `spawnBots`. */
+    readonly joinTimeoutMs?: number;
+    /** D36: room-gone grace, passed through to `spawnBots`. */
+    readonly roomGoneGraceMs?: number;
+    /**
+     * D36: the hard wall-clock ceiling on the whole run. Default `seconds × 3 + 30 s`. Reaching it
+     * is a fatal run condition, not a clean end.
+     */
+    readonly ceilingMs?: number;
     /** @internal Test seam, same as `startDev`'s. */
     readonly irtioPackages?: Record<string, string> | undefined;
 }
+/** D36's wall-clock ceiling: generous enough that no healthy run meets it. */
+declare function ceilingFor(seconds: number): number;
+/**
+ * D36: the run could not be performed at all — nobody joined, so there is no report to print and
+ * nothing was measured. `irtio simulate` turns this into exit code 2, which is the whole point of
+ * having a third code: "clean" and "violation" are both claims about a room, and this is not one.
+ */
+declare class RunNotPerformedError extends Error {
+    readonly cause?: unknown | undefined;
+    readonly name = "RunNotPerformedError";
+    constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * D36: what ended the run. `scripts`/`duration` are the ordinary ends; `room-gone` and `ceiling`
+ * 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). */
@@ -93,6 +299,12 @@ interface SimulationRun {
     /** 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;
+    /** D36: what ended the run. */
+    readonly endedBy: SimulationEnd;
+    /** D36: the fatal run condition in one sentence, when one ended the run. */
+    readonly fatal?: string;
+    /** D36: `0` clean, `1` a violation was measured, `2` the run was not performed as asked. */
+    readonly exitCode: 0 | 1 | 2;
     /** Everything that was printed, in order — the same lines `log` received. */
     readonly output: readonly string[];
 }
@@ -100,4 +312,4 @@ interface SimulationRun {
 declare function runSimulation(options?: RunSimulationOptions): Promise<SimulationRun>;
 declare function simulate(args: readonly string[]): Promise<void>;
 
-export { type LoadSchemaOptions, type RunSimulationOptions, type SimulateArgs, type SimulationRun, checkWorldDeterminism, loadProjectSchema, loadProjectWorld, parseSimulateArgs, runSimulation, simulate };
+export { type AdversarialRun, type BuildIdentity, type LoadSchemaOptions, RunNotPerformedError, type RunSimulationOptions, ScenarioNotRunError, type ScenarioRun, type SimulateArgs, type SimulationEnd, type SimulationRun, type TruthRun, USAGE, type UnpredictedWorld, ceilingFor, checkWorldDeterminism, formatBuildIdentity, isUnpredictedWorld, loadProjectSchema, loadProjectWorld, loadScenario, parseSimulateArgs, readBuildIdentity, readTickCounters, runSimulation, simulate, stateUrlFor, tickHealthFrom };