@irtio/bots 0.5.2 → 0.7.0

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 import { PlainState, AnySchema, Delta, TypeDesc } from '@irtio/schema';
-import { Correction, Room, RelayRoom, Transport, JoinOptions } from '@irtio/client';
+import { TimelineDump } from '@irtio/runtime';
+export { TimelineDump, TimelineFrame } from '@irtio/runtime';
+import { PredictionStatus, Correction, MatchTicket, 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.
@@ -14,7 +17,7 @@ import { Correction, Room, RelayRoom, Transport, JoinOptions } from '@irtio/clie
  */
 
 /** The invariants every simulation checks, in report order. */
-declare const INVARIANT_NAMES: readonly ["schema-validity", "visibility-leak", "bandwidth", "handler-error", "correction-storm", "misprediction", "snaps", "disconnects", "tick-health"];
+declare const INVARIANT_NAMES: readonly ["schema-validity", "visibility-leak", "bandwidth", "handler-error", "correction-storm", "misprediction", "snaps", "disconnects", "tick-health", "typed-message-drops", "party-integrity"];
 type InvariantName = (typeof INVARIANT_NAMES)[number];
 /**
  * D36: three states, not two. `unavailable` exists because the server's own tick counters cannot
@@ -45,6 +48,27 @@ interface TickHealthReading {
     /** Where the numbers came from, so a reader can go and check. */
     readonly source?: string;
 }
+/**
+ * M6 lane E (D73-c): what the queue answered, per bot, for the `party-integrity` invariant and the
+ * matchmaking report section. Absent ⇒ the run did not queue and the invariant is `unavailable`,
+ * which is D36's rule applied here: "nobody asked" and "nothing was wrong" stay different answers.
+ */
+interface MatchmakingReading {
+    readonly tickets: readonly {
+        readonly bot: number;
+        readonly room: string;
+        readonly queue: string;
+        /** Seats the queue says the room holds. `-1` seat means a backfill answer, not a position. */
+        readonly size: number;
+        readonly backfill: boolean;
+        readonly waitedMs: number;
+        readonly party?: number;
+    }[];
+    readonly failures: readonly {
+        readonly requested: number;
+        readonly code: string;
+    }[];
+}
 interface SpatialVisibilityContext {
     /**
      * The state the anchor and the judged positions are read from. Server truth when a test has it
@@ -88,6 +112,16 @@ interface InvariantThresholds {
      * paid for — and one `--overruns-max` away from being usable on a deliberately busy room.
      */
     readonly overrunsMax: number;
+    /**
+     * D70 `typed-message-drops`: typed peer messages a bot dropped across the run — an index its
+     * schema does not have, or a payload it could not decode.
+     *
+     * Zero by default, and strict on purpose. Every drop is a peer sending a shape this bot's
+     * schema does not describe, which in a simulation means the scenario and the room disagree.
+     * Before this the disagreement was invisible: the message simply never arrived, and the run
+     * went green.
+     */
+    readonly typedMessageDropsMax: number;
 }
 declare const DEFAULT_THRESHOLDS: InvariantThresholds;
 /**
@@ -110,6 +144,371 @@ 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
+ *
+ * Every row names one server tick — **the tick the shot was judged at** — and the miss distance is
+ * how far the aim was from where authority had the target at that tick. There are two ways to
+ * learn that tick, and the difference between them is why every row says which one it used.
+ *
+ * - **Exact (D72).** The game's own RPC tells the bot which tick it judged the shot at, and the
+ *   bot passes it to `bot.shot({ ..., serverTick })`. Nothing is inferred and no clock is compared
+ *   with any other clock. A room with no lag compensation reports the tick the `CALL` landed on, a
+ *   round trip after the shooter fired; a room that rewinds reports the tick its rewind answered
+ *   from, which is the tick the shooter was looking at. Moving that tick **is** lag compensation,
+ *   and the miss distance follows it.
+ * - **Estimated (D42, the fallback).** With no reported tick, the receive tick is 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 on
+ *   every row, 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 authoritative value is read straight out of the recording either way, 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;
+    /**
+     * D72: the server tick the room says it **judged this shot at**, when the game's own RPC
+     * reports one. Supplying it makes the row exact — no clock is compared with any other clock —
+     * and the report drops the word `(estimated)`.
+     *
+     * For a room with no lag compensation that is the tick the `CALL` was applied at, a round trip
+     * after the shooter fired. For a room that rewinds it is the tick the rewind answered from,
+     * which is the tick the shooter was looking at. That difference is the whole measurement: the
+     * miss distance is always "how far the aim was from where authority had the target **at the
+     * tick the shot was judged**", and lag compensation is what moves that tick.
+     */
+    readonly serverTick?: number | undefined;
+    /** D72: whether the room resolved this shot through `room.rewind`, when it says. */
+    readonly rewound?: boolean | undefined;
+}
+/** 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.
+     *
+     * D72: a shot whose room reported its own judging tick is never estimated, whatever the
+     * latency, because nothing was inferred from two clocks.
+     */
+    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;
+    /** D72: whether the room resolved this shot through `room.rewind`. `undefined` when it did not say. */
+    readonly rewound: boolean | 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.
+ *
+ * D72: a shot that carries `serverTick` is correlated to exactly that frame and is not estimated.
+ * A shot that does not falls back to the wall-clock path this started as, which is an estimate
+ * and says so on every row.
+ */
+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.
@@ -172,6 +571,16 @@ declare function makeTrace(startedAt: number, rings: () => readonly TraceRing[])
  * bytes does not.
  */
 
+/**
+ * M6 lane E (D73-b): what this client's local world holds for one instance right now.
+ *
+ * The three states `room.prediction` distinguishes since D71, in the one word each the observer
+ * needs. `predicted` is simulated locally; `proxied` is a kinematic collider at the drawn pose,
+ * which predicted bodies stand on and never moves on its own; `absent` is no body at all, which a
+ * predicted body falls straight through. A bot that joined without physics sees everything as
+ * `absent`, which is exactly what it had before this existed.
+ */
+type BodyKind = 'predicted' | 'proxied' | 'absent';
 /** Per-bot counters the report prints verbatim. */
 interface BotStats {
     readonly index: number;
@@ -191,6 +600,16 @@ interface BotStats {
      * the meaning: once the client re-steps predicted bodies, these become real mispredictions.
      */
     readonly syncCorrections: number;
+    /**
+     * M6 lane E (D73-b): corrections that touched only body fields of **proxied** instances.
+     *
+     * Reported, never thresholded. A proxy is moved to the pose the renderer draws, so a correction
+     * on one is the server disagreeing with what this client drew — the interpolation residual —
+     * rather than a prediction being wrong or a body arriving for the first time. Split out of
+     * `syncCorrections`, where these used to land: a run with no proxies counts exactly what it
+     * counted before.
+     */
+    readonly proxiedCorrections: number;
     /**
      * D22 part 2: predicted-body corrections whose values matched the local prediction within the
      * epsilon — authority confirming the prediction, not disagreeing with it. Counted apart so a
@@ -212,6 +631,37 @@ interface BotStats {
     readonly disconnects: number;
     readonly peakBytesInPerSec: number;
     readonly peakCorrectionsPerSec: number;
+    /** D70: peer messages this bot sent, raw and typed together. */
+    readonly messagesSent: number;
+    /** D70: peer messages this bot received and could read. */
+    readonly messagesReceived: number;
+    /** D70: typed peer messages this bot could not read — an unknown index, or a bad payload. */
+    readonly messagesDropped: number;
+    /**
+     * M6 lane E (D73-a): did this bot's client ever simulate a local world during the run?
+     *
+     * Latched from `room.prediction.active` as frames arrive, rather than read when the report is
+     * built, and both halves of that are load-bearing. The engine loads *off* the join path, so a
+     * read at join time says `false` on every run; and `stop()` leaves the room before it takes the
+     * report, and a room that has been left has freed its world, so a read at the end says `false`
+     * too. What a caller wants to know is whether prediction was live while the run happened.
+     *
+     * False on a bot that joined without `physics`/`physics2d`. The report prints it rather than
+     * assuming that a run which asked for prediction got it.
+     */
+    readonly predicting: boolean;
+    /**
+     * D73-b: the most kinematic proxies this bot's local world held at once
+     * (`room.prediction.stats.proxies`), sampled as frames arrived. Zero without prediction.
+     */
+    readonly proxies: number;
+    /**
+     * D73-b: the most instances this bot's local world had **no body at all** for at once
+     * (`room.prediction.stats.absent`). A predicted body passes straight through one of these, so a
+     * non-zero value on a collection anything stands on is a gameplay bug rather than a tradeoff —
+     * which is why it is reported beside the proxies rather than folded into them.
+     */
+    readonly absent: number;
 }
 /**
  * Shared across bots: the bridge that turns "bot A wrote x=7" plus "bot B was told x=7" into a
@@ -241,8 +691,18 @@ interface ObserverOptions {
 declare class BotObserver {
     private readonly options;
     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>;
+    readonly violations: Map<"schema-validity" | "visibility-leak" | "bandwidth" | "handler-error" | "correction-storm" | "misprediction" | "snaps" | "disconnects" | "tick-health" | "typed-message-drops" | "party-integrity", string[]>;
+    readonly counts: Map<"schema-validity" | "visibility-leak" | "bandwidth" | "handler-error" | "correction-storm" | "misprediction" | "snaps" | "disconnects" | "tick-health" | "typed-message-drops" | "party-integrity", 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;
@@ -260,14 +720,29 @@ declare class BotObserver {
     bytesOut: number;
     corrections: number;
     syncCorrections: number;
+    proxiedCorrections: number;
     suppressedCorrections: number;
     mispredictions: number;
     /**
-     * Does this bot's client currently predict `collection[id]` in a local world? Assigned by
-     * `spawnBots` once the room exists (`room.prediction`); prediction status is client-local, so
-     * it cannot be derived from the bytes the observer otherwise sticks to.
+     * M6 lane E (D73-b): what this bot's client's local world holds for `collection[id]` right now.
+     * Assigned by `spawnBots` once the room exists (`room.prediction`); the local world's shape is
+     * client-local, so it cannot be derived from the bytes the observer otherwise sticks to.
+     *
+     * Unset means "no local world at all", which answers `absent` for everything — the behaviour a
+     * bot without physics has always had.
      */
-    predictsBody: ((collection: string, id: string) => boolean) | undefined;
+    bodyKind: ((collection: string, id: string) => BodyKind) | undefined;
+    /**
+     * M6 lane E (D73-a): the client's own `room.prediction`, when this bot joined with `physics` or
+     * `physics2d`. Held rather than copied because `active` flips once the engine has loaded, which
+     * happens off the join path — a boolean read at join time would say `false` on every run.
+     */
+    prediction: PredictionStatus | undefined;
+    /** D73-a: latched true the first time {@link prediction} reported an active local world. */
+    predicted: boolean;
+    /** D73-b: the high-water marks of `prediction.stats.proxies` / `.absent` across the run. */
+    proxies: number;
+    absent: number;
     mispredictionMagnitude: number;
     mispredictionMax: number;
     snaps: number;
@@ -276,6 +751,10 @@ declare class BotObserver {
     disconnects: number;
     peakBytesInPerSec: number;
     peakCorrectionsPerSec: number;
+    /** D70: peer-message counters, filled by `inspect`'s MSG case in both directions. */
+    messagesSent: number;
+    messagesReceived: number;
+    messagesDropped: number;
     /**
      * Spatial-grid ops actually put to the AOI policy. Zero on a run whose room has no spatial
      * collection; zero on a run that *does* and would mean the invariant passed vacuously, which is
@@ -310,7 +789,31 @@ declare class BotObserver {
     onFrame(dir: 'in' | 'out', type: number, bytes: Uint8Array): void;
     /** Decodes the payload independently. Throws on a bad frame; the caller counts that. */
     private inspect;
+    /**
+     * D70: one peer message, in either direction, as a trace note.
+     *
+     * Before this, `MSG` fell through to `undefined` and a trace showed a frame with a byte count
+     * and nothing else — which was tolerable while every message was opaque bytes and is not now
+     * that some of them have declared shapes. A raw message notes its target; a typed one notes its
+     * name and its value when this bot holds the schema, and its index when it does not.
+     *
+     * A typed message this bot cannot read is counted as a **drop**, which is what the
+     * `typed-message-drops` invariant fails a run on. That is the whole point of the counter: a
+     * scenario sending a shape the schema does not describe used to be a message that silently
+     * never arrived.
+     */
+    private onMsg;
+    /** D70: one typed message this bot could not read — a counter and an invariant violation. */
+    private dropTyped;
     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 +844,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).
@@ -416,6 +867,9 @@ interface SimulationTotals {
     readonly corrections: number;
     /** D22: corrections carrying only simulated body state — the sync path, not a disagreement. */
     readonly syncCorrections: number;
+    /** D73-b: corrections carrying only body state of **proxied** instances — the interpolation
+     *  residual, not a misprediction. Reported, never thresholded. */
+    readonly proxiedCorrections: number;
     /** D22 part 2: predicted-body corrections matching the prediction within epsilon (quiet). */
     readonly suppressedCorrections: number;
     /** Correction ops seen via the rooms' `correct` events, across every bot. */
@@ -428,6 +882,70 @@ interface SimulationTotals {
     readonly snaps: number;
     readonly calls: number;
     readonly errors: number;
+    /** D70: peer messages sent across every bot, raw and typed together. */
+    readonly messagesSent: number;
+    /** D70: peer messages received and read across every bot. */
+    readonly messagesReceived: number;
+    /** D70: typed peer messages no bot could read. Any of these fails `typed-message-drops`. */
+    readonly messagesDropped: number;
+}
+/**
+ * M6 lane E (D73-b): what the bots' local worlds held, across the run. Absent when no bot
+ * predicted, so a run without physics prints exactly what it printed before.
+ *
+ * `proxies` and `absent` are the **peaks**, summed over the bots that predicted — the worst
+ * moment, not an average, because the number that matters is how much of the world a client was
+ * ever unable to simulate. There is deliberately no "predicted bodies" count: `PredictionStats`
+ * exposes none, and inventing one here would mean the observer enumerating the local world every
+ * frame to answer a question the client can answer itself.
+ */
+interface PredictionSummary {
+    /** Bots whose client held a live local world at some point in the run. */
+    readonly bots: number;
+    /** Peak kinematic proxies (D71), summed across those bots. */
+    readonly proxies: number;
+    /** Peak instances with no local body at all, summed across those bots. */
+    readonly absent: number;
+}
+/**
+ * M6 lane E (D73-c): what the queue did, for the report's matchmaking section.
+ *
+ * `waitP50Ms`/`waitP95Ms` are over the tickets that were answered; a timeout contributes to
+ * `timeouts` and not to the percentiles, because folding a deadline into a wait distribution turns
+ * "nobody came" into "everybody waited exactly the timeout", which reads as a slow queue rather
+ * than an empty one.
+ */
+interface MatchmakingSummary {
+    /** Tickets answered. */
+    readonly tickets: number;
+    /** Distinct rooms those tickets named. */
+    readonly rooms: number;
+    readonly waitP50Ms: number;
+    readonly waitP95Ms: number;
+    readonly waitMaxMs: number;
+    /** Tickets that came back `E_NO_MATCH` — the queue's own deadline. */
+    readonly timeouts: number;
+    /** Every other way a ticket failed, by code. */
+    readonly failures: readonly {
+        readonly requested: number;
+        readonly code: string;
+    }[];
+    /** Tickets answered with a seat in a room that was already running. */
+    readonly backfills: number;
+    /** Parties that landed whole, out of the parties that queued. */
+    readonly partiesIntact: number;
+    readonly parties: number;
+    /** Rooms holding more bots than their ticket said they seat. Any is a `party-integrity` fail. */
+    readonly overfullRooms: readonly {
+        readonly room: string;
+        readonly bots: number;
+        readonly size: number;
+    }[];
+    /** Parties whose members did not all land in one room. */
+    readonly splitParties: readonly {
+        readonly party: number;
+        readonly rooms: readonly string[];
+    }[];
 }
 interface SimulationReport {
     /** True when every invariant passed. `irtio simulate` exits 1 when it is not. */
@@ -446,7 +964,19 @@ 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;
+    /** D73-b: the local worlds the bots held. Absent when no bot predicted. */
+    readonly prediction?: PredictionSummary;
+    /** D73-c: what the queue did. Absent when the run did not queue. */
+    readonly matchmaking?: MatchmakingSummary;
 }
+/** D73-c: folds the queue's answers into the summary and the `party-integrity` verdict. */
+declare function matchmakingSummary(reading: MatchmakingReading): MatchmakingSummary;
 /** `undefined` when nothing converged during the run — an honest gap beats a fabricated zero. */
 declare function convergenceStats(lags: readonly number[]): ConvergenceStats | undefined;
 interface BuildReportOptions {
@@ -461,10 +991,103 @@ interface BuildReportOptions {
      * reports `unavailable`, which is the honest answer for a caller that could not read it.
      */
     readonly tickHealth?: TickHealthReading | undefined;
+    /** D73-c: what the queue answered per bot. Absent ⇒ `party-integrity` reports `unavailable`. */
+    readonly matchmaking?: MatchmakingReading | 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;
 
+/**
+ * M6 lane E (D73-c): bots that queue.
+ *
+ * `spawnBots` has always put every bot in one room by construction — bot 0 creates it and the rest
+ * join the code it came back with — which is right for a load run and means matchmaking, the front
+ * door every game will use, had never been driven by the harness that exists to drive things. This
+ * module is the other way in: each bot calls the real `findMatch` against a real control plane and
+ * joins whatever room its ticket names.
+ *
+ * Real, in the same sense the rest of `@irtio/bots` is real. `findMatch` is `@irtio/client`'s own
+ * function over its own HTTP, `createParty` mints a real code, and the room the ticket names is
+ * joined through the ordinary `joinRoom` — nothing here knows it was a matchmaker that filled the
+ * room, which is the property D52's whole design rests on. The one seam is `fetch`, injected so a
+ * unit test can answer tickets without a plane.
+ *
+ * Parties are a group of bot indices sharing a `party(index)` value. One member mints the code and
+ * every member sends it with its own call, exactly as two friends would: nobody sends anybody
+ * else's identity, because a device credential is a secret that never leaves the browser that
+ * minted it. A group of one queues alone rather than minting a party of one, which the queue would
+ * accept and which would prove nothing.
+ */
+
+/** How long a bot waits for a ticket when nothing says otherwise. Control caps this at two
+ *  minutes and applies its own default (30 s) when it is omitted; a run wants a bound it can
+ *  outlive rather than one it inherits. */
+declare const DEFAULT_MATCH_TIMEOUT_MS = 20000;
+interface BotMatchOptions {
+    /** The control plane origin. `irtio dev` runs none, so a queued run needs a real one. */
+    readonly controlUrl: string;
+    /** The project the queue belongs to — a project key, as `schema.project` carries it. */
+    readonly project: string;
+    /** Queue name. Omitted uses the project's `default` queue (a party of two). */
+    readonly queue?: string;
+    /**
+     * A platform identity assertion per bot, when the run has them.
+     *
+     * The queue's one-ticket-per-player rule keys on the account an identity belongs to; without
+     * one it keys on a fresh anonymous id per request, which is why twenty anonymous bots can queue
+     * at once and why a run that wants to prove the dedupe rule has to mint identities first.
+     */
+    readonly identity?: (index: number) => string | undefined;
+    /**
+     * Which party group this bot queues in, or `undefined` to queue alone. Bots answering the same
+     * value are one party and land in one room.
+     */
+    readonly party?: (index: number) => number | undefined;
+    readonly timeoutMs?: number;
+    /** @internal Test seam: the unit tests answer tickets without a control plane. */
+    readonly fetch?: typeof fetch;
+}
+/** One bot's answer from the queue. */
+interface BotTicket {
+    /** The bot this became, once the failures were dropped — see {@link BotMatchResult}. */
+    readonly bot: number;
+    /** Which of the `n` queue attempts this was. Equal to `bot` when nothing failed. */
+    readonly requested: number;
+    readonly ticket: MatchTicket;
+    /** Wall clock from the call to the answer. The number a "still looking…" screen would show. */
+    readonly waitedMs: number;
+    /** The party group this bot queued in, when it queued in one. */
+    readonly party?: number;
+}
+/** One bot that never got a ticket. A timeout is one of these, not a hang. */
+interface BotMatchFailure {
+    readonly requested: number;
+    readonly code: string;
+    readonly message: string;
+    readonly waitedMs: number;
+    readonly party?: number;
+}
+interface BotMatchResult {
+    /** Tickets in request order, renumbered densely so `bot` indexes the run that follows. */
+    readonly tickets: readonly BotTicket[];
+    readonly failures: readonly BotMatchFailure[];
+    /** The party code minted per group, for the groups that queued as parties. */
+    readonly parties: ReadonlyMap<number, string>;
+}
+/**
+ * Queues `n` bots and answers what the queue said, per bot.
+ *
+ * Nothing throws for one bot's failure: a queue that refused three of twenty is a measurement, and
+ * the caller decides what to do with it (`spawnBots` runs the ones that got in and fails the run).
+ * A party whose code could not be minted fails as a whole, because a party that has lost its code
+ * is a group of strangers and queueing them anyway would quietly test something else.
+ */
+declare function matchBots(n: number, options: BotMatchOptions): Promise<BotMatchResult>;
+/** Bot indices per room, in the order the tickets came back. */
+declare function roomsOf(tickets: readonly BotTicket[]): Map<string, number[]>;
+
 /**
  * `spawnBots` — N real `@irtio/client` sessions in one Node process, each running a script, each
  * watched by a `BotObserver`.
@@ -526,6 +1149,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,10 +1186,22 @@ 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. */
     readonly overrunsMax?: number;
+    /**
+     * D70 `typed-message-drops` threshold: typed peer messages a bot may fail to read across the
+     * run. Default 0 — a drop means a peer sent a shape this schema does not declare, which in a
+     * simulation is a scenario and a room disagreeing.
+     */
+    readonly typedMessageDropsMax?: number;
     /**
      * D36: how long one bot's initial join may take before `spawnBots` gives up on the whole run.
      * Default {@link DEFAULT_JOIN_TIMEOUT_MS}; `0` restores the old unbounded wait.
@@ -569,6 +1214,25 @@ 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);
+    /**
+     * M6 lane E (D73-c): queue for rooms instead of building one.
+     *
+     * With this set the one-room contract below does not apply: every bot calls the real
+     * `findMatch` against the control plane named here and joins whatever room its ticket names, so
+     * a run drives the front door a game actually has. Bots sharing a `party(index)` value queue as
+     * one party and land together. `room` is ignored — the queue decides.
+     */
+    readonly match?: BotMatchOptions;
 }
 interface SpawnOptions<S extends AnySchema> extends SpawnOptionsBase {
     readonly schema: S;
@@ -581,15 +1245,46 @@ interface SpawnOptions<S extends AnySchema> extends SpawnOptionsBase {
      * corrections classify as real mispredictions (in world units) instead of `syncCorrections`.
      */
     readonly physics?: JoinOptions<S>['physics'];
+    /**
+     * M6 lane E (D73-a): the matter2d twin of `physics`, passed to every bot's
+     * `joinRoom({ physics2d })`.
+     *
+     * The two are mutually exclusive for the same reason `joinRoom` makes them so — a room runs one
+     * engine and the client predicts with that one — and passing both throws with the sentence
+     * `joinRoom` uses, before any socket opens.
+     */
+    readonly physics2d?: JoinOptions<S>['physics2d'];
 }
 /** Schema-less relay: no schema, so `joinRelay` and a `RelayRoom`. */
 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>[];
+    /**
+     * The room this run is about. With `match`, several rooms exist and this is the first ticket's
+     * — the one a caller reading the server's own counters has to pick one of. `rooms` has them all.
+     */
     readonly roomId: string;
+    /** D73-c: the ticket each bot queued for, in bot order. Empty on a run that did not queue. */
+    readonly matches: readonly BotTicket[];
+    /** D73-c: bot indices by room. One entry on a run that did not queue. */
+    readonly rooms: ReadonlyMap<string, readonly number[]>;
+    /** D73-c: bots that never got a ticket, and what the queue said. Empty when nothing failed. */
+    readonly matchFailures: readonly {
+        requested: number;
+        code: string;
+        message: string;
+    }[];
     /** Every bot's frames, merged and time-ordered. `trace.save(path)` writes JSON. */
     readonly trace: Trace;
     /** Anything a script threw, in the order it happened. */
@@ -597,6 +1292,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 +1329,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 +1492,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 +1509,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 +1533,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 BodyKind, type Bot, type BotConditions, type BotMatchFailure, type BotMatchOptions, type BotMatchResult, BotObserver, type BotRoom, type BotRunner, type BotScript, type BotStats, type BotTicket, type BuildReportOptions, type ClientStateView, type ConditionCounters, type ConditionTimers, type ConditionedSocket, type ConditionedTransport, type ConditionedTransportOptions, type ConvergenceStats, DEFAULT_JOIN_TIMEOUT_MS, DEFAULT_MATCH_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 MatchmakingReading, type MatchmakingSummary, type NetworkConditions, type ObserverOptions, type PredictionSummary, 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, matchBots, matchmakingSummary, newConditionCounters, nextValue, randomScript, relayEchoScript, roomsOf, snapshotVisibilityLeaks, spawnBots };