@irtio/bots 0.5.2 → 0.6.0

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 import { PlainState, AnySchema, Delta, TypeDesc } from '@irtio/schema';
+import { TimelineDump } from '@irtio/runtime';
+export { TimelineDump, TimelineFrame } from '@irtio/runtime';
 import { Correction, Room, RelayRoom, Transport, JoinOptions } from '@irtio/client';
+import { ProfileSnapshot } from '@irtio/protocol';
 
 /**
  * The built-in invariants, and the pure checkers behind the two that need real protocol knowledge.
@@ -110,6 +113,342 @@ declare function snapshotVisibilityLeaks(ext: AnySchema, role: string, state: Pl
  */
 declare function frameVisibilityLeaks(ext: AnySchema, role: string, type: number, payload: Uint8Array, spatial?: SpatialVisibilityContext): string[];
 
+/**
+ * Seeded randomness and schema-driven value generation.
+ *
+ * Every bot gets its own generator seeded from `seed + index`, so a whole run replays exactly:
+ * a red simulation is worth nothing if the next run takes a different path.
+ *
+ * Value generation reads `@irtio/schema`'s `TypeDesc` directly rather than duplicating the type
+ * menu, so a new type kind is a compile error here instead of a silent gap.
+ */
+
+/** A seeded pseudo-random source behind `bot.random()`. */
+interface Rng {
+    /** Uniform in [0, 1). */
+    next(): number;
+    /** Uniform integer in [lo, hi] (inclusive). */
+    int(lo: number, hi: number): number;
+    /** Uniform in [lo, hi). */
+    float(lo: number, hi: number): number;
+    /** `true` with probability `p`. */
+    chance(p: number): boolean;
+    /** One element, or `undefined` for an empty array. */
+    pick<T>(items: readonly T[]): T | undefined;
+}
+/**
+ * mulberry32: 32 bits of state, good enough for behaviour scripts and — unlike `Math.random` —
+ * reproducible. Not cryptographic, and never used for anything that needs to be.
+ */
+declare function makeRng(seed: number): Rng;
+/** How a value is generated: a small walk (normal play) or a teleport (`--cheat`). */
+interface ValueContext {
+    /** Magnitude of one step for unbounded numeric fields. */
+    readonly step: number;
+    /** Produce values a server validator should reject. */
+    readonly cheat: boolean;
+    /**
+     * The value this field started at. Numeric walks are mean-reverting toward it, which keeps a
+     * long run inside whatever world bounds the room's validator enforces without the bot having to
+     * know them — the type system only declares a *representable* range, never a legal one.
+     */
+    readonly origin?: number | undefined;
+    /** Ids that a `ref` field may legally point at. */
+    readonly refIds?: readonly string[] | undefined;
+}
+/**
+ * The next value for a field that currently holds `current`. Always inside the type's declared
+ * range, so `track()` accepts it and the *server* — not the client — is the one that gets to say
+ * a value is illegal. In cheat mode the value is still type-valid and wildly out of play.
+ */
+declare function nextValue(rng: Rng, desc: TypeDesc, current: unknown, ctx: ValueContext): unknown;
+/** A fresh valid value for a field with no current value — RPC params, mostly. */
+declare function freshValue(rng: Rng, desc: TypeDesc, ctx: ValueContext): unknown;
+
+/**
+ * D42: injected network conditions, as a wrapper around the transport seam.
+ *
+ * `SpawnOptions.transport` exists so a test can get at the socket, and that is exactly the shape
+ * an adversarial run needs: a bot under conditions is still a real `@irtio/client` session
+ * speaking the real wire, it just gets its frames late, twice, out of order, or not at all. No
+ * protocol change, no frame change, and nothing below this file knows the difference.
+ *
+ * Three rules decide the design, and all three are load-bearing.
+ *
+ * 1. **Loss, duplication and reorder touch state frames only.** `@irtio/testing`'s in-process
+ *    harness restricts its loss die the same way, for the same reason: dropping a HELLO wedges
+ *    the join and dropping a REPLY wedges an RPC that has no retry, and a run that hangs on a
+ *    wedged join is a D36 regression, not an adversarial test. The peek is a read of the frame's
+ *    own type byte against `@irtio/protocol`'s `FrameType`, which is the envelope the protocol
+ *    already guarantees; nothing here decodes a payload.
+ * 2. **Delay is symmetric unless it is split.** `rttMs` is the round trip, so each direction
+ *    carries `rttMs / 2` plus a jitter draw. A stream is kept in order by a per-direction floor,
+ *    the way a real WebSocket is, and `reorder` is the only thing that lifts it.
+ * 3. **Reorder is bounded.** A reordered frame is held back by at most `reorderMs`, so frames
+ *    swap places with their neighbours rather than arriving at the end of the run. An unbounded
+ *    shuffle is indistinguishable from loss plus a very long tail, and it would make a run's
+ *    end time a function of the die.
+ *
+ * Determinism: every die is drawn from the rng handed in, which `spawnBots` seeds per bot index.
+ * The same seed injects the same delays, drops the same frames and duplicates the same ones. It
+ * does not make the *run* deterministic (real sockets and a real clock are still underneath), it
+ * makes the injection deterministic, which is the half this file owns.
+ */
+
+/** Default width of the reorder window when `reorder` is set and `reorderMs` is not. */
+declare const DEFAULT_REORDER_MS = 50;
+interface NetworkConditions {
+    /** Round-trip time in ms. Each direction carries half of it. */
+    readonly rttMs?: number;
+    /** Extra delay per frame, drawn uniformly from `[0, jitterMs)`. */
+    readonly jitterMs?: number;
+    /** Chance in `[0, 1]` that a state frame is dropped. Session and RPC frames are never dropped. */
+    readonly loss?: number;
+    /** Chance in `[0, 1]` that a state frame is delivered twice. */
+    readonly duplicate?: number;
+    /** Chance in `[0, 1]` that a state frame is held back past its neighbours. */
+    readonly reorder?: number;
+    /** How far a reordered frame may be held back, in ms. Default {@link DEFAULT_REORDER_MS}. */
+    readonly reorderMs?: number;
+}
+/** What the wrapper did, per bot. Reported so a run says what was injected, not what was asked for. */
+interface ConditionCounters {
+    /** Frames the loss die dropped, client to server. */
+    droppedOut: number;
+    /** Frames the loss die dropped, server to client. */
+    droppedIn: number;
+    duplicatedOut: number;
+    duplicatedIn: number;
+    reorderedOut: number;
+    reorderedIn: number;
+    /** Frames that were delayed at all (that is, every frame the wrapper saw and did not drop). */
+    delayed: number;
+}
+declare function newConditionCounters(): ConditionCounters;
+/**
+ * True when these conditions would change anything. `spawnBots` uses it to leave an unconditioned
+ * bot on the bare transport, so a plain run keeps exactly the timing it had before D42.
+ */
+declare function hasConditions(c: NetworkConditions | undefined): c is NetworkConditions;
+/** One line describing what was injected, for the report and for `bot.conditions`. */
+declare function describeConditions(c: NetworkConditions): string;
+/**
+ * The transport-seam shapes this file needs. Declared structurally rather than imported from
+ * `@irtio/client` so that `conditionedTransport` can be unit-tested against a fake transport with
+ * no socket anywhere near it.
+ */
+interface ConditionedSocket {
+    send(bytes: Uint8Array): void;
+    close(): void;
+    onopen: (() => void) | null;
+    onmessage: ((bytes: Uint8Array) => void) | null;
+    onclose: ((info?: {
+        code?: number;
+        reason?: string;
+    }) => void) | null;
+    onerror: ((error: unknown) => void) | null;
+}
+interface ConditionedTransport {
+    connect(url: string): ConditionedSocket;
+}
+/** Injectable timers, so a unit test can drive delivery without waiting on the real clock. */
+interface ConditionTimers {
+    now(): number;
+    setTimeout(fn: () => void, ms: number): () => void;
+}
+interface ConditionedTransportOptions {
+    readonly counters?: ConditionCounters;
+    readonly timers?: ConditionTimers;
+}
+/**
+ * Wraps `base` so every frame crossing this socket is subject to `conditions`.
+ *
+ * Outbound frames are delayed on their way into `base.send`; inbound frames are delayed on their
+ * way out of `base`'s `onmessage`. `onopen`, `onclose` and `onerror` pass through untouched: they
+ * are socket lifecycle, not frames, and delaying a close would only make a teardown slower to
+ * notice.
+ */
+declare function conditionedTransport(base: ConditionedTransport, conditions: NetworkConditions, rng: Rng, options?: ConditionedTransportOptions): ConditionedTransport;
+
+/**
+ * D42: hit registration.
+ *
+ * The sniper case from the v1 plan. A bot fires at a moving target; by the time the shot reaches
+ * the server the target has moved, and the report says by how much. Nothing here compensates for
+ * it, and that is the point: this is how a builder sees why lag compensation would matter, on
+ * their own room, before anyone ships one.
+ *
+ * ## What a shot is
+ *
+ * `bot.shot({ collection, target, aim })`. It is **bookkeeping, not a wire event**: the game's own
+ * RPC still does the shooting, and this call records that it happened, at whom, and where the
+ * shooter was aiming, in the shooter's own client-side view. No frame changes and no protocol
+ * changes, which is what keeps a hit-registration run a normal run of the same room.
+ *
+ * ## How a shot is correlated
+ *
+ * Three numbers, and the honesty of the third is the whole feature:
+ *
+ * - **`sentAt`** is the shooter's wall clock at the moment it fired.
+ * - **The server's receive tick** is estimated: the first recorded tick whose state settled at or
+ *   after `sentAt` plus the shot's uplink delay (`rttMs / 2` of whatever was injected into that
+ *   bot). It is an estimate, it is labelled one whenever conditions were injected, and it rests
+ *   on the recorder and the shooter sharing a clock — true under `irtio dev`, where the room runs
+ *   in a worker thread of the same process, and the reason this is a local-dev capability exactly
+ *   as the recorded timeline is.
+ * - **The miss distance** is the Euclidean distance between the aim and the target's
+ *   *authoritative* value at that tick, over the fields the aim names. The authoritative value is
+ *   read straight out of the recording, so a row can be checked against the timeline file by hand.
+ *
+ * A row whose target was not in the recording at that tick, or whose shot landed past the end of
+ * the recording, says so rather than reporting a distance of zero.
+ */
+
+/** One aim point: field name to value, over the target collection's numeric fields. */
+type AimPoint = Readonly<Record<string, number>>;
+interface ShotRequest {
+    /** The collection the target lives in. */
+    readonly collection: string;
+    /** The target entity's id. */
+    readonly target: string;
+    /** Where the shooter aimed, in its own client-side view. */
+    readonly aim: AimPoint;
+    /** Free-form label, carried through to the row. */
+    readonly label?: string;
+}
+/** A shot as recorded, before any correlation. */
+interface ShotRecord extends ShotRequest {
+    /** Which bot fired. */
+    readonly bot: number;
+    /** The shooter's wall clock when it fired. */
+    readonly sentAt: number;
+    /** The last server tick the shooter had seen when it fired, when the client exposes one. */
+    readonly clientTick: number | undefined;
+    /** The uplink delay injected into this bot, in ms: `rttMs / 2`. `0` with no conditions. */
+    readonly uplinkMs: number;
+}
+/** One correlated shot: what the shooter aimed at, and what the server actually held. */
+interface HitRow extends ShotRecord {
+    /** The server tick the shot is judged against, or `undefined` when none could be found. */
+    readonly serverTick: number | undefined;
+    /**
+     * `true` when `serverTick` was derived through an injected uplink delay rather than read off a
+     * frame the shot could only have landed in. The report prints the word.
+     */
+    readonly estimated: boolean;
+    /** The target's authoritative value at `serverTick`, over the fields the aim named. */
+    readonly authoritative: AimPoint | undefined;
+    /** Euclidean distance between `aim` and `authoritative`, or `undefined` when unknown. */
+    readonly missDistance: number | undefined;
+    /** Why a row has no distance, in one clause. Absent when it has one. */
+    readonly unresolved?: string;
+}
+/**
+ * Correlates every shot against the recording. Pure: same shots and same dump, same rows, which
+ * is what lets a scenario assert on them.
+ */
+declare function correlateShots(shots: readonly ShotRecord[], dump: TimelineDump): HitRow[];
+
+/**
+ * D43: the truth seam.
+ *
+ * The claim the scenario API's credibility rests on is "the wire matched authoritative state",
+ * and until this file existed nobody could check it: a room save was bytes only `RoomCore.restore`
+ * could read, and it read them by hydrating a live room. `decodeSave` in `@irtio/runtime` made the
+ * bytes readable; this file is what compares them against what the clients were told.
+ *
+ * ## What is compared
+ *
+ * Per bot, not globally. A client legitimately never received entities outside its area of
+ * interest or outside its role's visibility, so "the client holds the whole save" is not the
+ * question and answering it would fail every room with an AOI. The question is the other
+ * direction, and it has two halves:
+ *
+ * 1. **Every entity the client held is in the save**, with the same owner and the same field
+ *    values. A client holding something authority does not is the class of desync worth catching.
+ * 2. **Every value it held matches.** Field by field, on the fields the client actually has.
+ *
+ * Nothing is asserted about entities in the save that the client never received: that is
+ * visibility working, not a difference.
+ *
+ * ## What "clean" means, precisely
+ *
+ * Clean is: nothing the client held is absent from the save, and nothing it held disagrees with
+ * the save. It is not "the client saw everything". The report prints the sentence that way, and
+ * the docs do too, because the shorter version is the overclaim D43 exists to retire.
+ *
+ * ## The ordering that makes it meaningful
+ *
+ * The save is taken when the room is quiescent and the clients have had a settle window to
+ * receive the last flush. A room still changing after its save will differ from every client, and
+ * that difference is real: it is the run reporting that it compared two different instants. The
+ * negative fixture is built out of exactly that, which is the honest mechanism the plan asked for
+ * rather than a mutation invented for the test.
+ */
+
+/** One client's view, in the same shape `inspectState` and `decodeSave` produce. */
+type ClientStateView = Record<string, unknown>;
+/** One disagreement between a client's view and the decoded save. */
+interface TruthDifference {
+    readonly bot: number;
+    readonly collection: string;
+    /** The entity id, or `undefined` for a singleton collection. */
+    readonly id?: string;
+    /** The field, or `undefined` when the whole record is missing from the save. */
+    readonly field?: string;
+    /** What the client held. */
+    readonly client: unknown;
+    /** What the save held, or `undefined` when the save has nothing there. */
+    readonly save: unknown;
+    /** One sentence naming what went wrong, ready to print. */
+    readonly detail: string;
+}
+/** One bot's verdict. */
+interface TruthBotResult {
+    readonly bot: number;
+    /** Records the client held and the save agreed with. */
+    readonly compared: number;
+    readonly differences: readonly TruthDifference[];
+    readonly ok: boolean;
+}
+/** The whole diff. */
+interface TruthDiff {
+    readonly ok: boolean;
+    readonly bots: readonly TruthBotResult[];
+    /** Records compared across every bot. */
+    readonly compared: number;
+    readonly differences: readonly TruthDifference[];
+    /** The save's own tick, carried so the report can say what instant was compared. */
+    readonly saveTick: number;
+    /** The save blob's format version byte. */
+    readonly saveVersion: number;
+}
+/**
+ * Captures one bot's client-visible state, in `inspectState`'s shape.
+ *
+ * It reads the live `room.state` the client built from every frame it received, which is the only
+ * place "what this client was told" exists: the frame trace records headers, not payloads. No
+ * trace change and no payload retention are needed because of that.
+ *
+ * `schema` is the project schema as authored, which is what says which collections are entity
+ * tables and which are singletons.
+ */
+declare function captureClientState(schema: AnySchema, state: unknown): ClientStateView;
+/**
+ * Diffs each client's captured view against the decoded save, within that client's visibility.
+ *
+ * `saveState` is `decodeSave(bytes, schema).state`. Both sides are therefore `inspectState` shape
+ * and the comparison is like against like, which is the reason the decoder returns that shape
+ * rather than a `PlainState`.
+ */
+declare function diffAgainstSave(clients: readonly {
+    bot: number;
+    state: ClientStateView;
+}[], saveState: Record<string, unknown>, meta: {
+    saveTick: number;
+    saveVersion: number;
+}): TruthDiff;
+
 /**
  * The trace recorder: every frame in and out, per bot, with a timestamp and the decoded frame
  * type — the thing you actually read when a simulation goes red.
@@ -243,6 +582,16 @@ declare class BotObserver {
     readonly ring: TraceRing;
     readonly violations: Map<"schema-validity" | "visibility-leak" | "bandwidth" | "handler-error" | "correction-storm" | "misprediction" | "snaps" | "disconnects" | "tick-health", string[]>;
     readonly counts: Map<"schema-validity" | "visibility-leak" | "bandwidth" | "handler-error" | "correction-storm" | "misprediction" | "snaps" | "disconnects" | "tick-health", number>;
+    /**
+     * Bug #28: the decode extension, *mutable*. It starts as `options.ext` (the schema the run was
+     * spawned with) and is rebuilt in place when an inbound `SCHEMA` frame (13) lands — a D50
+     * additive `migrate` swaps the wire mid-session, the real client rebuilds its own decoders
+     * (`session.swapSchema`), and an observer still holding the v1 descriptor underruns on the v2
+     * resync WELCOME and fails `schema-validity` on a swap that was perfect.
+     */
+    private ext;
+    /** How many `SCHEMA` frames rebuilt {@link ext}. For tests and the trace, like the client's. */
+    schemaSwaps: number;
     id: string;
     role: string;
     roomId: string;
@@ -311,6 +660,14 @@ declare class BotObserver {
     /** Decodes the payload independently. Throws on a bad frame; the caller counts that. */
     private inspect;
     private onWelcome;
+    /**
+     * Bug #28: a `SCHEMA` frame (D50 additive migrate). Rebuild the decode extension from the
+     * descriptor the frame carries, exactly as the real client's `swapSchema` does, so the resync
+     * WELCOME about to arrive decodes under the schema it was encoded with. The old view and
+     * seen-ids are dropped — they were laid out by descriptors that no longer exist, and the resync
+     * WELCOME re-seeds both (`onWelcome`).
+     */
+    private onSchema;
     private onDelta;
     private onCorrect;
     /**
@@ -341,58 +698,6 @@ declare class BotObserver {
     private matchWrites;
 }
 
-/**
- * Seeded randomness and schema-driven value generation.
- *
- * Every bot gets its own generator seeded from `seed + index`, so a whole run replays exactly:
- * a red simulation is worth nothing if the next run takes a different path.
- *
- * Value generation reads `@irtio/schema`'s `TypeDesc` directly rather than duplicating the type
- * menu, so a new type kind is a compile error here instead of a silent gap.
- */
-
-/** A seeded pseudo-random source behind `bot.random()`. */
-interface Rng {
-    /** Uniform in [0, 1). */
-    next(): number;
-    /** Uniform integer in [lo, hi] (inclusive). */
-    int(lo: number, hi: number): number;
-    /** Uniform in [lo, hi). */
-    float(lo: number, hi: number): number;
-    /** `true` with probability `p`. */
-    chance(p: number): boolean;
-    /** One element, or `undefined` for an empty array. */
-    pick<T>(items: readonly T[]): T | undefined;
-}
-/**
- * mulberry32: 32 bits of state, good enough for behaviour scripts and — unlike `Math.random` —
- * reproducible. Not cryptographic, and never used for anything that needs to be.
- */
-declare function makeRng(seed: number): Rng;
-/** How a value is generated: a small walk (normal play) or a teleport (`--cheat`). */
-interface ValueContext {
-    /** Magnitude of one step for unbounded numeric fields. */
-    readonly step: number;
-    /** Produce values a server validator should reject. */
-    readonly cheat: boolean;
-    /**
-     * The value this field started at. Numeric walks are mean-reverting toward it, which keeps a
-     * long run inside whatever world bounds the room's validator enforces without the bot having to
-     * know them — the type system only declares a *representable* range, never a legal one.
-     */
-    readonly origin?: number | undefined;
-    /** Ids that a `ref` field may legally point at. */
-    readonly refIds?: readonly string[] | undefined;
-}
-/**
- * The next value for a field that currently holds `current`. Always inside the type's declared
- * range, so `track()` accepts it and the *server* — not the client — is the one that gets to say
- * a value is illegal. In cheat mode the value is still type-valid and wildly out of play.
- */
-declare function nextValue(rng: Rng, desc: TypeDesc, current: unknown, ctx: ValueContext): unknown;
-/** A fresh valid value for a field with no current value — RPC params, mostly. */
-declare function freshValue(rng: Rng, desc: TypeDesc, ctx: ValueContext): unknown;
-
 /**
  * The end-of-run summary: one line per invariant, one row per bot, and the handful of aggregate
  * numbers a load run cares about (frames/s, per-bot bandwidth, corrections, convergence lag).
@@ -446,6 +751,12 @@ interface SimulationReport {
     /** The headline number: median ms from one bot's write to another bot seeing it. */
     readonly convergenceLagMs: number | undefined;
     readonly tracePath: string | undefined;
+    /**
+     * D65: every bot's bandwidth ledger, merged, when the run asked for one. Cumulative for the
+     * whole run and for every bot together — a reader divides by `bots` and `durationMs` to get the
+     * per-bot rate the rest of this report prints. Absent when nobody profiled.
+     */
+    readonly profile?: ProfileSnapshot;
 }
 /** `undefined` when nothing converged during the run — an honest gap beats a fabricated zero. */
 declare function convergenceStats(lags: readonly number[]): ConvergenceStats | undefined;
@@ -461,6 +772,8 @@ interface BuildReportOptions {
      * reports `unavailable`, which is the honest answer for a caller that could not read it.
      */
     readonly tickHealth?: TickHealthReading | undefined;
+    /** D65: one ledger per bot, merged into `SimulationReport.profile`. */
+    readonly profiles?: readonly ProfileSnapshot[] | undefined;
 }
 /** Folds the observers into the report `irtio simulate` prints and tests assert on. */
 declare function buildReport(options: BuildReportOptions): SimulationReport;
@@ -526,6 +839,16 @@ interface Bot<S = undefined> {
     /** This bot's slice of the trace. */
     readonly trace: Trace;
     readonly stats: BotStats;
+    /** D42: the network conditions injected into this bot's socket, or `undefined` for a clean one. */
+    readonly conditions: NetworkConditions | undefined;
+    /**
+     * D42: records that this bot fired at something, for the hit-registration report.
+     *
+     * Bookkeeping only. It sends nothing and changes no frame: the game's own RPC still does the
+     * shooting, and this call sits beside it saying what was aimed at and when. The runner
+     * correlates it with the recorded authoritative timeline afterwards.
+     */
+    shot(request: ShotRequest): void;
 }
 type BotScript<S = undefined> = (bot: Bot<S>) => void | Promise<void>;
 interface SpawnOptionsBase {
@@ -553,6 +876,12 @@ interface SpawnOptionsBase {
     readonly handlerErrorsMax?: number;
     /** `misprediction` threshold: numeric units one correction may snap. Default: infinite. */
     readonly mispredictionMagnitudeMax?: number;
+    /**
+     * D65: give every bot a bandwidth ledger, merged into `SimulationReport.profile`. This is the
+     * view from the outside — what a real client's connection carries — as opposed to what the room
+     * believes it sent. Off by default.
+     */
+    readonly profile?: boolean;
     /** `snaps` tolerance: cap-exceeded reconciliations per bot. Default: infinite. */
     readonly snapsMax?: number;
     /** `tick-health` threshold: server tick overruns tolerated in the run window. Default 0. */
@@ -569,6 +898,16 @@ interface SpawnOptionsBase {
     readonly roomGoneGraceMs?: number;
     /** @internal Wrap `webSocketTransport` to get at the socket (the reconnection scenarios). */
     readonly transport?: Transport;
+    /**
+     * D42: network conditions injected into every bot's socket, or a function of the bot index for
+     * a split run (one lagged shooter against one clean target). A bot whose conditions are absent,
+     * or would change nothing, keeps the bare transport and the timing a plain run has.
+     *
+     * This is a *socket-level* model on a real wire, which is a different instrument from
+     * `@irtio/testing`'s `LatencySpec`: that one is an in-process harness on a fake clock, with no
+     * sockets at all. The vocabulary is deliberately the same and the two are not interchangeable.
+     */
+    readonly conditions?: NetworkConditions | ((index: number) => NetworkConditions | undefined);
 }
 interface SpawnOptions<S extends AnySchema> extends SpawnOptionsBase {
     readonly schema: S;
@@ -587,6 +926,14 @@ interface RelaySpawnOptions extends SpawnOptionsBase {
     readonly schema?: undefined;
     readonly script?: BotScript<undefined>;
 }
+/** D42: one bot's injected conditions, beside what the wrapper counted while injecting them. */
+interface BotConditions {
+    readonly bot: number;
+    /** What was asked for, or `undefined` when this bot ran on the bare transport. */
+    readonly conditions: NetworkConditions | undefined;
+    /** What the wrapper did. All zero when nothing was injected. */
+    readonly counters: ConditionCounters;
+}
 interface BotRunner<S = undefined> extends Iterable<Bot<S>> {
     readonly bots: readonly Bot<S>[];
     readonly roomId: string;
@@ -597,6 +944,10 @@ interface BotRunner<S = undefined> extends Iterable<Bot<S>> {
         bot: number;
         error: unknown;
     }[];
+    /** D42: every `bot.shot(...)`, in the order the bots recorded them. */
+    readonly shots: readonly ShotRecord[];
+    /** D42: what was injected per bot index, and what the wrapper actually did with it. */
+    readonly conditions: readonly BotConditions[];
     /**
      * D36: what ended the run, once something has. `scripts` (every script returned), `duration`
      * (the deadline fired) or `room-gone` (every bot was disconnected for longer than the grace).
@@ -630,6 +981,149 @@ declare class JoinTimeoutError extends Error {
 declare function spawnBots<S extends AnySchema>(n: number, options: SpawnOptions<S>): Promise<BotRunner<S>>;
 declare function spawnBots(n: number, options?: RelaySpawnOptions): Promise<BotRunner<undefined>>;
 
+/**
+ * D41: the read-only view a scenario's `assert` gets over the recorded authoritative timeline.
+ *
+ * The whole API is on this page on purpose. D41's constraint is that an agent can write a correct
+ * scenario from one docs page, and the fastest way to lose that is to grow matchers, query
+ * helpers and a second vocabulary for state a room author already has names for. So a moment is
+ * the room's own state, keyed by the collection names from the schema, and the only verbs are
+ * "read this tick", "find the first tick where", and "label this assertion".
+ *
+ * Reading is exact and never quietly empty. `at()` on a tick the recorder never held, or dropped,
+ * throws with the range that survived. A collection name the schema does not have throws with the
+ * names it does. Both of those would otherwise become an assertion that passes because it read
+ * nothing, which is worse than an assertion that fails.
+ */
+
+/** One entity's fields, or one singleton's fields, as recorded. */
+type TimelineRecord = Readonly<Record<string, unknown>>;
+/** One collection at one tick. Entity collections have entries; a singleton has `value`. */
+interface TimelineCollection {
+    /** The entity's fields, or `undefined` when no entity had that id at this tick. */
+    get(id: string): TimelineRecord | undefined;
+    has(id: string): boolean;
+    /** The ids present at this tick. */
+    ids(): readonly string[];
+    readonly size: number;
+    /** The client that owned this entity at this tick, if any. */
+    owner(id: string): string | undefined;
+    /** A singleton collection's fields. `undefined` for an entity collection. */
+    readonly value: TimelineRecord | undefined;
+}
+/**
+ * The room's authoritative state at one tick, keyed by the schema's own collection names.
+ *
+ * The schema is not known at compile time, so this is an index signature and a project with
+ * `noUncheckedIndexedAccess` types each collection as possibly undefined. At runtime it never is:
+ * a name your schema does have always resolves, and a name it does not have throws
+ * `UnknownCollectionError` rather than answering with a blank.
+ */
+interface TimelineState {
+    readonly [collection: string]: TimelineCollection;
+}
+interface TimelineMoment {
+    readonly tick: number;
+    readonly state: TimelineState;
+}
+/** One labelled assertion and how it went. This is what the report's scenario section lists. */
+interface AssertionResult {
+    readonly name: string;
+    readonly ok: boolean;
+    /** The last tick the assertion read, when it read one. */
+    readonly tick?: number;
+    /** On a pass, the ticks it read. On a failure, the thrown message. */
+    readonly detail: string;
+}
+interface Timeline {
+    readonly roomId: string;
+    /** Every recorded tick, oldest first. */
+    readonly ticks: readonly number[];
+    /** Ticks the recorder's caps evicted. Non-zero means this is a tail, not the whole run. */
+    readonly dropped: number;
+    /** The room's state at that tick. Throws when the tick was never recorded or was dropped. */
+    at(tick: number): TimelineState;
+    /** The first recorded tick where `match` holds, oldest first. */
+    find(match: (state: TimelineState, tick: number) => boolean): TimelineMoment | undefined;
+    /**
+     * Runs one labelled assertion. A throw inside it fails the scenario, and the report names the
+     * label, the tick the assertion last read, and the message you threw. The throw does not
+     * escape, so later checks still run and the report lists every verdict. A throw outside a
+     * `check` also fails the scenario; it just has no label to print.
+     */
+    check(name: string, assertion: () => void): void;
+    /** Every `check` that ran, in order. The runner reads this to build the report. */
+    readonly results: readonly AssertionResult[];
+}
+/** The scenario read a collection the schema does not have. Almost always a typo, never empty. */
+declare class UnknownCollectionError extends Error {
+    readonly name = "UnknownCollectionError";
+    constructor(collection: string, known: readonly string[]);
+}
+/** The scenario read a tick the recording does not hold. See `Timeline.dropped`. */
+declare class TickNotRecordedError extends Error {
+    readonly tick: number;
+    readonly name = "TickNotRecordedError";
+    constructor(tick: number, first: number | undefined, last: number | undefined, dropped: number);
+}
+/** Builds the read-only `Timeline` a scenario's `assert` is handed, over a recorder's dump. */
+declare function makeTimeline(dump: TimelineDump): Timeline;
+
+/**
+ * D41: `defineScenario`. A scenario is a TypeScript module next to the room file: how many bots,
+ * what they do, and what must be true of the recorded authoritative timeline afterwards.
+ *
+ * The type is small because the docs page has to be. `script` is the `BotScript` `@irtio/bots`
+ * already has, so there is no second bot vocabulary to learn, and `assert` is an ordinary
+ * function over the timeline, so there is no matcher library either. `defineScenario` itself only
+ * exists for the types: it returns its argument, and the CLI's loader shape-checks the export so a
+ * wrong one produces a sentence instead of a stack trace.
+ */
+
+/**
+ * D42/D43: what an adversarial scenario can read beyond the timeline. Both fields are empty or
+ * `undefined` unless the scenario asked for them, so a scenario that fires no shots and never
+ * sets `truth` reads and behaves exactly as it did in part 3.
+ */
+interface ScenarioEvidence {
+    /** One row per `bot.shot(...)`, correlated against the recording. Empty when nothing fired. */
+    readonly hits: readonly HitRow[];
+    /** The save-versus-clients diff, when `truth` asked for one and one could be taken. */
+    readonly truth: TruthDiff | undefined;
+}
+interface ScenarioDefinition<S extends AnySchema = AnySchema> {
+    /** How many bots to spawn. Bot 0 creates the room; the rest join it. */
+    readonly bots: number;
+    /** What each bot does. The same `bot` object `spawnBots` scripts get. */
+    readonly script: BotScript<S>;
+    /**
+     * What must be true afterwards. Assertions run against the recorded timeline, not a live room,
+     * so a scenario replays: same seed, same recording, same verdict. A throw fails the scenario.
+     */
+    readonly assert: (timeline: Timeline, evidence: ScenarioEvidence) => void | Promise<void>;
+    /** How long to run before the scripts are asked to stop. Default 10. */
+    readonly seconds?: number;
+    /** Base seed; bot `i` uses `seed + i`. Default 0x17710, the same as `irtio simulate`. */
+    readonly seed?: number;
+    /**
+     * D42: network conditions injected into every bot, or a function of the bot index. A scenario is
+     * where a per-bot split belongs, because a scenario is code already: one lagged shooter against
+     * one clean target is two lines here and a flag language on the CLI.
+     */
+    readonly conditions?: NetworkConditions | ((index: number) => NetworkConditions | undefined);
+    /** D42: which bots write values a validator should reject. `true` means all of them. */
+    readonly cheat?: boolean | ((index: number) => boolean);
+    /**
+     * D43: take a room save at the end of the run and diff it against what each client received,
+     * within that client's visibility. The verdict lands in `evidence.truth` and in the report.
+     */
+    readonly truth?: boolean;
+}
+/** Identity, typed. The export `irtio simulate --scenario` looks for. */
+declare function defineScenario<S extends AnySchema = AnySchema>(scenario: ScenarioDefinition<S>): ScenarioDefinition<S>;
+/** True when a loaded module's default export is shaped like a scenario. */
+declare function looksLikeScenario(value: unknown): value is ScenarioDefinition;
+
 /**
  * The generic behaviour script: play the room without knowing anything about it.
  *
@@ -650,8 +1144,14 @@ declare function spawnBots(n: number, options?: RelaySpawnOptions): Promise<BotR
  */
 
 interface RandomScriptOptions {
-    /** Write values a validator should reject, and expect corrections back. */
-    readonly cheat?: boolean;
+    /**
+     * Write values a validator should reject, and expect corrections back.
+     *
+     * D42: per bot as well as global. A function of the bot index makes one bot hostile while the
+     * rest play honestly, which is what an adversarial run against a real room usually looks like.
+     * `--cheat` on the CLI still means every bot cheats.
+     */
+    readonly cheat?: boolean | ((index: number) => boolean);
     /** Milliseconds between behaviour steps. Default 50 — one per client flush window. */
     readonly stepMs?: number;
     /** Magnitude of one numeric step for a well-behaved bot. Default 8. */
@@ -661,6 +1161,12 @@ interface RandomScriptOptions {
     /** Fields touched per owned instance per step. Default 2. */
     readonly fieldsPerStep?: number;
 }
+/**
+ * D42: `cheat` as a predicate over the bot index, whatever shape it was given in. Exported so the
+ * CLI and the report can say *which* bots cheated rather than only that some did, which is the
+ * difference between "the room accepted an illegal write" and a line an agent can act on.
+ */
+declare function cheatPredicate(cheat: boolean | ((index: number) => boolean) | undefined): (index: number) => boolean;
 /**
  * A behaviour script for any schema: random writes to the instances this bot owns, and the odd
  * void RPC with valid params. Runs until the bot is stopped.
@@ -679,4 +1185,4 @@ interface RelayEchoScriptOptions {
  */
 declare function relayEchoScript(options?: RelayEchoScriptOptions): BotScript<undefined>;
 
-export { type Bot, BotObserver, type BotRoom, type BotRunner, type BotScript, type BotStats, type BuildReportOptions, type ConvergenceStats, DEFAULT_JOIN_TIMEOUT_MS, DEFAULT_ROOM_GONE_GRACE_MS, DEFAULT_SEED, DEFAULT_THRESHOLDS, DEFAULT_TRACE_LIMIT, INVARIANT_NAMES, type InvariantName, type InvariantResult, type InvariantState, type InvariantThresholds, JoinTimeoutError, type ObserverOptions, type RandomScriptOptions, type RelayEchoScriptOptions, type RelaySpawnOptions, type Rng, type RunEnd, type SimulationReport, type SimulationTotals, type SpatialVisibilityContext, type SpawnOptions, type TickHealthReading, type Trace, type TraceDump, type TraceEntry, TraceRing, type UntilOptions, type ValueContext, WriteLog, buildReport, convergenceStats, deltaVisibilityLeaks, frameName, frameVisibilityLeaks, freshValue, makeRng, makeTrace, nextValue, randomScript, relayEchoScript, snapshotVisibilityLeaks, spawnBots };
+export { type AimPoint, type AssertionResult, type Bot, type BotConditions, BotObserver, type BotRoom, type BotRunner, type BotScript, type BotStats, type BuildReportOptions, type ClientStateView, type ConditionCounters, type ConditionTimers, type ConditionedSocket, type ConditionedTransport, type ConditionedTransportOptions, type ConvergenceStats, DEFAULT_JOIN_TIMEOUT_MS, DEFAULT_REORDER_MS, DEFAULT_ROOM_GONE_GRACE_MS, DEFAULT_SEED, DEFAULT_THRESHOLDS, DEFAULT_TRACE_LIMIT, type HitRow, INVARIANT_NAMES, type InvariantName, type InvariantResult, type InvariantState, type InvariantThresholds, JoinTimeoutError, type NetworkConditions, type ObserverOptions, type RandomScriptOptions, type RelayEchoScriptOptions, type RelaySpawnOptions, type Rng, type RunEnd, type ScenarioDefinition, type ScenarioEvidence, type ShotRecord, type ShotRequest, type SimulationReport, type SimulationTotals, type SpatialVisibilityContext, type SpawnOptions, type TickHealthReading, TickNotRecordedError, type Timeline, type TimelineCollection, type TimelineMoment, type TimelineRecord, type TimelineState, type Trace, type TraceDump, type TraceEntry, TraceRing, type TruthBotResult, type TruthDiff, type TruthDifference, UnknownCollectionError, type UntilOptions, type ValueContext, WriteLog, buildReport, captureClientState, cheatPredicate, conditionedTransport, convergenceStats, correlateShots, defineScenario, deltaVisibilityLeaks, describeConditions, diffAgainstSave, frameName, frameVisibilityLeaks, freshValue, hasConditions, looksLikeScenario, makeRng, makeTimeline, makeTrace, newConditionCounters, nextValue, randomScript, relayEchoScript, snapshotVisibilityLeaks, spawnBots };