@irtio/bots 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 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 { PredictionStatus, Correction, MatchTicket, Room, RelayRoom, Transport, JoinOptions } from '@irtio/client';
 import { ProfileSnapshot } from '@irtio/protocol';
 
 /**
@@ -17,7 +17,7 @@ import { ProfileSnapshot } from '@irtio/protocol';
  */
 
 /** 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
@@ -48,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
@@ -91,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;
 /**
@@ -287,21 +318,27 @@ declare function conditionedTransport(base: ConditionedTransport, conditions: Ne
  *
  * ## How a shot is correlated
  *
- * Three numbers, and the honesty of the third is the whole feature:
+ * 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.
  *
- * - **`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.
+ * - **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.
  *
- * 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.
+ * 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. */
@@ -315,6 +352,20 @@ interface ShotRequest {
     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 {
@@ -334,18 +385,27 @@ interface HitRow extends ShotRecord {
     /**
      * `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[];
 
@@ -511,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;
@@ -530,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
@@ -551,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
@@ -580,8 +691,8 @@ 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
@@ -609,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.
+     */
+    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.
      */
-    predictsBody: ((collection: string, id: string) => boolean) | undefined;
+    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;
@@ -625,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
@@ -659,6 +789,22 @@ 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
@@ -721,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. */
@@ -733,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. */
@@ -757,7 +970,13 @@ interface SimulationReport {
      * 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 {
@@ -772,12 +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`.
@@ -886,6 +1196,12 @@ interface SpawnOptionsBase {
     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.
@@ -908,6 +1224,15 @@ interface SpawnOptionsBase {
      * 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;
@@ -920,6 +1245,15 @@ 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 {
@@ -936,7 +1270,21 @@ interface BotConditions {
 }
 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. */
@@ -1185,4 +1533,4 @@ interface RelayEchoScriptOptions {
  */
 declare function relayEchoScript(options?: RelayEchoScriptOptions): BotScript<undefined>;
 
-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 };
+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 };