@irtio/bots 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 irtio contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,469 @@
+import { AnySchema, Delta, PlainState, TypeDesc } from '@irtio/schema';
+import { Room, RelayRoom, Transport, JoinOptions } from '@irtio/client';
+
+/**
+ * The built-in invariants, and the pure checkers behind the two that need real protocol knowledge.
+ *
+ * `visibilityLeak` is the one worth the most: a role-scoped collection must never reach a client
+ * outside its roles, adds and removes included. The rule is `visibleNames` from `@irtio/runtime`
+ * — the *same* function the server encodes views with, imported rather than reimplemented, so the
+ * check cannot drift into agreeing with a bug.
+ *
+ * Everything here is a pure function of decoded frames: a unit test fabricates a `DELTA` and asks
+ * the checker, with no socket, no server and no bot anywhere in sight.
+ */
+
+/** The invariants every simulation checks, in report order. */
+declare const INVARIANT_NAMES: readonly ["schema-validity", "visibility-leak", "bandwidth", "handler-error", "correction-storm", "disconnects"];
+type InvariantName = (typeof INVARIANT_NAMES)[number];
+interface InvariantResult {
+    readonly name: InvariantName;
+    readonly ok: boolean;
+    readonly violations: number;
+    /** One line a human can act on: the threshold, the peak, the first offenders. */
+    readonly detail: string;
+}
+/** Thresholds the counting invariants compare against. */
+interface InvariantThresholds {
+    /** `bandwidth`: inbound bytes per second, per bot. */
+    readonly budgetBytesPerSec: number;
+    /** `correction-storm`: CORRECT frames per second, per bot — the cheater-mode signal. */
+    readonly correctionsPerSecMax: number;
+    /** `handler-error`: tolerated REPLY errors + non-fatal ERROR frames across the whole run. */
+    readonly handlerErrorsMax: number;
+}
+declare const DEFAULT_THRESHOLDS: InvariantThresholds;
+/**
+ * Collections a `DELTA` named that `role` is not allowed to see. An op count of zero is not a
+ * leak — an empty collection entry carries no information — but any add, update or remove is.
+ */
+declare function deltaVisibilityLeaks(ext: AnySchema, role: string, delta: Delta): string[];
+/**
+ * The same rule for a join snapshot. The wire format always has a slot for every collection —
+ * a hidden one is encoded empty — so the leak is *content*: an entity collection with records in
+ * it, or a singleton holding anything other than its zero record.
+ */
+declare function snapshotVisibilityLeaks(ext: AnySchema, role: string, state: PlainState): string[];
+/**
+ * The socket-free entry point for the frames that carry a delta (`DELTA`, `CORRECT`): hand it the
+ * frame type and its payload and it decodes and checks. Any other type returns `[]` — a join
+ * snapshot goes through `snapshotVisibilityLeaks` instead, because a `WELCOME` payload wraps one
+ * rather than being one. A payload that will not decode throws, and the caller counts that as a
+ * `schema-validity` violation rather than a visibility one.
+ */
+declare function frameVisibilityLeaks(ext: AnySchema, role: string, type: number, payload: Uint8Array): string[];
+
+/**
+ * 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.
+ *
+ * Bounded on purpose. A 20-bot 10 s run at 30 Hz is ~10 000 frames and a naive array of payloads
+ * would be tens of megabytes, so each bot gets a fixed-size ring of *headers only* (no payload
+ * bytes, just their length). `save()` dumps the merged ring as JSON.
+ */
+/** `'DELTA'`, `'WRITE'`, … or `'UNKNOWN(42)'` for a type this protocol version does not define. */
+declare function frameName(type: number): string;
+interface TraceEntry {
+    /** Milliseconds since the run started. */
+    readonly at: number;
+    readonly bot: number;
+    readonly dir: 'in' | 'out';
+    readonly type: number;
+    readonly frame: string;
+    readonly bytes: number;
+    /** Set when the frame is worth a word: a decode failure, an error code, an rpc name. */
+    readonly note?: string;
+}
+/** Fixed-capacity ring. Oldest entries are overwritten and counted in `dropped`. */
+declare class TraceRing {
+    readonly capacity: number;
+    private readonly items;
+    private next;
+    private count;
+    dropped: number;
+    constructor(capacity: number);
+    push(entry: TraceEntry): void;
+    /** Oldest first. */
+    entries(): TraceEntry[];
+}
+/** What `trace.save(path)` writes. */
+interface TraceDump {
+    /** `Date.now()` at the start of the run, so `entry.at` can be turned back into wall time. */
+    readonly startedAt: number;
+    readonly bots: number;
+    /** Frames the ring overwrote — a non-zero value means the trace is a tail, not the whole run. */
+    readonly dropped: number;
+    readonly entries: readonly TraceEntry[];
+}
+/** A read-only view over one or more rings. */
+interface Trace {
+    /** Merged, oldest first. */
+    entries(): TraceEntry[];
+    readonly dropped: number;
+    /** Writes `TraceDump` JSON. */
+    save(path: string): Promise<void>;
+}
+/** Builds a `Trace` over rings resolved lazily, so it keeps working as bots come and go. */
+declare function makeTrace(startedAt: number, rings: () => readonly TraceRing[]): Trace;
+
+/**
+ * One bot's continuous invariant checking, driven entirely by the client's `onFrame` seam.
+ *
+ * The observer never touches the room object: it decodes the wire a second time, independently of
+ * `@irtio/client`. That is the point — if the SDK's decoder and the server's encoder ever agree on
+ * something wrong, a checker built on `room.state` agrees with them and a checker built on the
+ * bytes does not.
+ */
+
+/** Per-bot counters the report prints verbatim. */
+interface BotStats {
+    readonly index: number;
+    /** The client id from `WELCOME` — `''` until the bot has joined. */
+    readonly id: string;
+    readonly role: string;
+    readonly framesIn: number;
+    readonly framesOut: number;
+    readonly bytesIn: number;
+    readonly bytesOut: number;
+    readonly corrections: number;
+    /** Outbound `CALL` frames: RPCs this bot asked the server for. */
+    readonly calls: number;
+    /** Error replies plus non-fatal `ERROR` frames. */
+    readonly errors: number;
+    readonly disconnects: number;
+    readonly peakBytesInPerSec: number;
+    readonly peakCorrectionsPerSec: number;
+}
+/**
+ * Shared across bots: the bridge that turns "bot A wrote x=7" plus "bot B was told x=7" into a
+ * convergence lag. Keyed by value, so a write the server clamps simply never matches and is
+ * evicted — under-sampling is fine, a wrong number is not.
+ */
+declare class WriteLog {
+    private readonly limit;
+    private readonly entries;
+    constructor(limit?: number);
+    record(key: string, at: number, bot: number): void;
+    /** The time *another* bot wrote this exact value, consuming the entry. */
+    match(key: string, bot: number): number | undefined;
+}
+interface ObserverOptions {
+    readonly index: number;
+    /** The runtime-extended schema the wire is encoded with (`withBuiltins`, or `relaySchema`). */
+    readonly ext: AnySchema;
+    /** `Date.now()` at the start of the run; every trace timestamp is relative to it. */
+    readonly startedAt: number;
+    readonly traceLimit: number;
+    readonly thresholds: InvariantThresholds;
+    readonly writeLog: WriteLog;
+    /** Convergence lag samples, shared across the run. */
+    readonly lags: number[];
+}
+declare class BotObserver {
+    private readonly options;
+    readonly ring: TraceRing;
+    readonly violations: Map<"schema-validity" | "visibility-leak" | "bandwidth" | "handler-error" | "correction-storm" | "disconnects", string[]>;
+    readonly counts: Map<"schema-validity" | "visibility-leak" | "bandwidth" | "handler-error" | "correction-storm" | "disconnects", number>;
+    id: string;
+    role: string;
+    roomId: string;
+    /** Set before `leave()`, so a deliberate teardown is not reported as a disconnect. */
+    stopping: boolean;
+    framesIn: number;
+    framesOut: number;
+    bytesIn: number;
+    bytesOut: number;
+    corrections: number;
+    calls: number;
+    errors: number;
+    disconnects: number;
+    peakBytesInPerSec: number;
+    peakCorrectionsPerSec: number;
+    private readonly bytesWindow;
+    private readonly correctWindow;
+    private readonly cooldown;
+    constructor(options: ObserverOptions);
+    get stats(): BotStats;
+    /** Counts a violation always; keeps an example, rate-limited per invariant when asked. */
+    private violate;
+    /** `room.on('status')`: transitions away from a healthy connection, ignored during teardown. */
+    onStatus(status: string): void;
+    /** The `onFrame` hook. `bytes` is the whole frame, envelope byte included. */
+    onFrame(dir: 'in' | 'out', type: number, bytes: Uint8Array): void;
+    /** Decodes the payload independently. Throws on a bad frame; the caller counts that. */
+    private inspect;
+    private onWelcome;
+    private onDelta;
+    private onCorrect;
+    private onError;
+    private onReply;
+    private eachScalar;
+    /** Our own `WRITE`: remember what we sent, so whoever sees it can date it. */
+    private recordWrites;
+    /** Somebody else's write arriving here: that round trip is the convergence lag. */
+    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).
+ *
+ * Assembly lives apart from the observers so a report can be built at any moment — `irtio
+ * simulate` builds one after the deadline, a test builds one mid-run to assert on it.
+ */
+
+/** Convergence lag, sampled from real writes crossing to another bot's view. */
+interface ConvergenceStats {
+    readonly samples: number;
+    readonly p50Ms: number;
+    readonly p95Ms: number;
+    readonly maxMs: number;
+}
+interface SimulationTotals {
+    readonly framesIn: number;
+    readonly framesOut: number;
+    readonly bytesIn: number;
+    readonly bytesOut: number;
+    readonly corrections: number;
+    readonly calls: number;
+    readonly errors: number;
+}
+interface SimulationReport {
+    /** True when every invariant passed. `irtio simulate` exits 1 when it is not. */
+    readonly ok: boolean;
+    readonly bots: number;
+    readonly roomId: string;
+    readonly durationMs: number;
+    readonly invariants: readonly InvariantResult[];
+    readonly perBot: readonly BotStats[];
+    readonly totals: SimulationTotals;
+    /** Frames per second across every bot, both directions. */
+    readonly framesPerSecond: number;
+    readonly bytesInPerSecondPerBot: number;
+    readonly bytesOutPerSecondPerBot: number;
+    readonly convergence: ConvergenceStats | undefined;
+    /** The headline number: median ms from one bot's write to another bot seeing it. */
+    readonly convergenceLagMs: number | undefined;
+    readonly tracePath: string | undefined;
+}
+/** `undefined` when nothing converged during the run — an honest gap beats a fabricated zero. */
+declare function convergenceStats(lags: readonly number[]): ConvergenceStats | undefined;
+interface BuildReportOptions {
+    readonly observers: readonly BotObserver[];
+    readonly roomId: string;
+    readonly durationMs: number;
+    readonly lags: readonly number[];
+    readonly thresholds?: InvariantThresholds;
+    readonly tracePath?: string | undefined;
+}
+/** Folds the observers into the report `irtio simulate` prints and tests assert on. */
+declare function buildReport(options: BuildReportOptions): SimulationReport;
+
+/**
+ * `spawnBots` — N real `@irtio/client` sessions in one Node process, each running a script, each
+ * watched by a `BotObserver`.
+ *
+ * "Real" is the whole point. A bot is not a mock: it speaks the same wire, through the same SDK,
+ * with the same write batching and the same reconnection logic a browser gets. The only seams the
+ * runtime uses are the ones `joinRoom` already offers for tests — `onFrame` for the trace,
+ * `transport` for the reconnection scenarios — so a bug a simulation finds is a bug a player hits.
+ *
+ * Bot 0 joins first and creates the room when no code was given; everyone else joins the code it
+ * came back with. Otherwise twenty bots would create twenty empty rooms and every invariant would
+ * pass while nothing was tested.
+ */
+
+/** Default seed: a run with no `seed` still replays, it just replays *this* sequence. */
+declare const DEFAULT_SEED = 96016;
+/** Trace ring size per bot. 20 bots × 4096 ≈ 80k headers, a few megabytes at worst. */
+declare const DEFAULT_TRACE_LIMIT = 4096;
+/** The room a bot holds: a full `Room` with a schema, or a schemaless `RelayRoom`. */
+type BotRoom<S> = S extends AnySchema ? Room<S> : RelayRoom;
+interface UntilOptions {
+    /** Named in the timeout message. */
+    readonly label?: string;
+    readonly timeoutMs?: number;
+    readonly everyMs?: number;
+}
+interface Bot<S = undefined> {
+    readonly index: number;
+    readonly room: BotRoom<S>;
+    /** The client id — `room.me`, repeated here because scripts reach for it constantly. */
+    readonly id: string;
+    readonly role: string;
+    /** Seeded per bot index: the same run replays the same way. */
+    random(): number;
+    /** The generator behind `random()`, for scripts that want integers and picks. */
+    readonly rng: Rng;
+    /** Sleeps, or returns immediately once the bot has been asked to stop. */
+    wait(ms: number): Promise<void>;
+    /** Polls (never a fixed sleep). Returns early if the bot is stopped. */
+    until(predicate: () => boolean | Promise<boolean>, options?: UntilOptions): Promise<void>;
+    /** Asks this bot's script to wind down. The socket closes when the runner stops. */
+    stop(): void;
+    readonly stopped: boolean;
+    /** This bot's slice of the trace. */
+    readonly trace: Trace;
+    readonly stats: BotStats;
+}
+type BotScript<S = undefined> = (bot: Bot<S>) => void | Promise<void>;
+interface SpawnOptionsBase {
+    /** Endpoint. Defaults to `@irtio/client`'s resolution (`ws://localhost:7070` in Node). */
+    readonly url?: string;
+    readonly key?: string;
+    /** Room code. Omitted: bot 0 creates one and the rest join it. */
+    readonly room?: string;
+    /** A string for every bot, or a function of the bot index (1 host + 8 controllers). */
+    readonly role?: string | ((index: number) => string);
+    readonly name?: string | ((index: number) => string);
+    /** `writeIntervalMs` on each client. */
+    readonly flushMs?: number;
+    /** Base seed; bot `i` uses `seed + i`. */
+    readonly seed?: number;
+    /** Frames kept per bot. */
+    readonly traceLimit?: number;
+    /** Stop every script after this long. Omitted: the scripts decide when they are done. */
+    readonly durationMs?: number;
+    /** `bandwidth` invariant budget, inbound bytes per second per bot. */
+    readonly budgetBytesPerSec?: number;
+    /** `correction-storm` threshold, CORRECTs per second per bot. */
+    readonly correctionsPerSecMax?: number;
+    /** `handler-error` tolerance for a run that expects some RPCs to be refused. */
+    readonly handlerErrorsMax?: number;
+    /** @internal Wrap `webSocketTransport` to get at the socket (the reconnection scenarios). */
+    readonly transport?: Transport;
+}
+interface SpawnOptions<S extends AnySchema> extends SpawnOptionsBase {
+    readonly schema: S;
+    readonly script?: BotScript<S>;
+    /** Implementations for server → client RPCs, shared by every bot. */
+    readonly rpc?: JoinOptions<S>['rpc'];
+}
+/** Schema-less relay: no schema, so `joinRelay` and a `RelayRoom`. */
+interface RelaySpawnOptions extends SpawnOptionsBase {
+    readonly schema?: undefined;
+    readonly script?: BotScript<undefined>;
+}
+interface BotRunner<S = undefined> extends Iterable<Bot<S>> {
+    readonly bots: readonly Bot<S>[];
+    readonly roomId: 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. */
+    readonly scriptErrors: readonly {
+        bot: number;
+        error: unknown;
+    }[];
+    /** Resolves when every script has finished; rejects with the first one that threw. */
+    done(): Promise<void>;
+    /** Stops the scripts, leaves every room, and returns the final report. */
+    stop(): Promise<SimulationReport>;
+    /** The report as of now — safe to call mid-run. */
+    report(): SimulationReport;
+}
+/** Spawns `n` real clients on one room, runs `script` on each, and watches every invariant. */
+declare function spawnBots<S extends AnySchema>(n: number, options: SpawnOptions<S>): Promise<BotRunner<S>>;
+declare function spawnBots(n: number, options?: RelaySpawnOptions): Promise<BotRunner<undefined>>;
+
+/**
+ * The generic behaviour script: play the room without knowing anything about it.
+ *
+ * Everything the script does is derived from the schema — which collections a client may own, what
+ * each field's declared type will accept, which RPCs take no answer. That is what makes `irtio
+ * simulate` work on a room it has never seen.
+ *
+ * Two deliberate choices are worth knowing about:
+ *
+ * - **Numeric writes are a mean-reverting walk, not a uniform draw over the type range.** A type
+ *   declares what is *representable*, never what is *legal*: `f32` says nothing about a 1000-unit
+ *   world or a 50-unit speed limit. A bot that teleported every tick would be corrected every tick
+ *   and the correction-storm invariant would be useless. Small steps around the spawn value keep a
+ *   well-behaved bot well-behaved on any room.
+ * - **`cheat: true` inverts exactly that.** It writes type-valid, play-illegal values — the far end
+ *   of an integer range, a five-order-of-magnitude jump on a float — which is what a modified
+ *   client does, and which every server validator should answer with a `CORRECT`.
+ */
+
+interface RandomScriptOptions {
+    /** Write values a validator should reject, and expect corrections back. */
+    readonly cheat?: 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. */
+    readonly step?: number;
+    /** Chance per step of calling a random void server RPC. Default 0.05. */
+    readonly rpcChance?: number;
+    /** Fields touched per owned instance per step. Default 2. */
+    readonly fieldsPerStep?: number;
+}
+/**
+ * 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.
+ */
+declare function randomScript<S extends AnySchema>(schema: S, options?: RandomScriptOptions): BotScript<S>;
+interface RelayEchoScriptOptions {
+    /** Milliseconds between broadcasts. Default 200. */
+    readonly everyMs?: number;
+    /** Bytes per message. Default 16. */
+    readonly bytes?: number;
+}
+/**
+ * The simplest behaviour: broadcast a small payload on a timer. A relay room has no state to
+ * write and no RPCs to call, so messages are the only thing a bot can do — and the only thing
+ * worth checking a relay tenant on.
+ */
+declare function relayEchoScript(options?: RelayEchoScriptOptions): BotScript<undefined>;
+
+export { type Bot, BotObserver, type BotRoom, type BotRunner, type BotScript, type BotStats, type BuildReportOptions, type ConvergenceStats, DEFAULT_SEED, DEFAULT_THRESHOLDS, DEFAULT_TRACE_LIMIT, INVARIANT_NAMES, type InvariantName, type InvariantResult, type InvariantThresholds, type ObserverOptions, type RandomScriptOptions, type RelayEchoScriptOptions, type RelaySpawnOptions, type Rng, type SimulationReport, type SimulationTotals, type SpawnOptions, 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 };

package/dist/index.js

@@ -0,0 +1,858 @@
+// src/invariants.ts
+import { FrameType } from "@irtio/protocol";
+import { visibleNames } from "@irtio/runtime";
+import {
+  decodeDelta,
+  defaultRecord
+} from "@irtio/schema";
+var INVARIANT_NAMES = [
+  "schema-validity",
+  "visibility-leak",
+  "bandwidth",
+  "handler-error",
+  "correction-storm",
+  "disconnects"
+];
+var DEFAULT_THRESHOLDS = {
+  budgetBytesPerSec: 128e3,
+  correctionsPerSecMax: 5,
+  handlerErrorsMax: 0
+};
+function deltaVisibilityLeaks(ext, role, delta) {
+  const allowed = visibleNames(ext, role);
+  const leaks = [];
+  for (const collection of delta.collections) {
+    if (allowed.has(collection.name)) continue;
+    if (collection.ops.length === 0) continue;
+    const ops = collection.ops.map((op) => op.op).join(",");
+    leaks.push(`delta@${delta.tick} carried ${collection.name} (${ops}) to role ${role || '""'}`);
+  }
+  return leaks;
+}
+function isDefaultRecord(desc, value) {
+  const zero = defaultRecord(desc);
+  for (const field of desc.fields) {
+    if (JSON.stringify(value[field.name]) !== JSON.stringify(zero[field.name])) return false;
+  }
+  return true;
+}
+function snapshotVisibilityLeaks(ext, role, state) {
+  const allowed = visibleNames(ext, role);
+  const leaks = [];
+  for (const desc of ext.collections) {
+    if (allowed.has(desc.name)) continue;
+    if (desc.kind === "entity") {
+      const size = state[desc.name]?.size ?? 0;
+      if (size > 0) leaks.push(`snapshot carried ${size} ${desc.name} to role ${role || '""'}`);
+      continue;
+    }
+    const value = state[desc.name];
+    if (value && !isDefaultRecord(desc, value)) {
+      leaks.push(`snapshot carried singleton ${desc.name} to role ${role || '""'}`);
+    }
+  }
+  return leaks;
+}
+function frameVisibilityLeaks(ext, role, type, payload) {
+  if (type !== FrameType.DELTA && type !== FrameType.CORRECT) return [];
+  return deltaVisibilityLeaks(ext, role, decodeDelta(ext, payload));
+}
+
+// src/observer.ts
+import {
+  FrameType as FrameType3,
+  decodeErrorPayload,
+  decodeFrame,
+  decodeReply,
+  decodeWelcome,
+  errorByCode
+} from "@irtio/protocol";
+import {
+  decodeDelta as decodeDelta2,
+  decodeSnapshot
+} from "@irtio/schema";
+
+// src/trace.ts
+import { writeFile } from "fs/promises";
+import { FrameType as FrameType2 } from "@irtio/protocol";
+var FRAME_NAMES = new Map(
+  Object.entries(FrameType2).map(([name, value]) => [value, name])
+);
+function frameName(type) {
+  return FRAME_NAMES.get(type) ?? `UNKNOWN(${type})`;
+}
+var TraceRing = class {
+  constructor(capacity) {
+    this.capacity = capacity;
+    this.items = new Array(Math.max(0, capacity));
+  }
+  capacity;
+  items;
+  next = 0;
+  count = 0;
+  dropped = 0;
+  push(entry) {
+    if (this.capacity <= 0) {
+      this.dropped++;
+      return;
+    }
+    if (this.count === this.capacity) this.dropped++;
+    this.items[this.next] = entry;
+    this.next = (this.next + 1) % this.capacity;
+    if (this.count < this.capacity) this.count++;
+  }
+  /** Oldest first. */
+  entries() {
+    const out = [];
+    const start = this.count === this.capacity ? this.next : 0;
+    for (let i = 0; i < this.count; i++) {
+      const entry = this.items[(start + i) % this.capacity];
+      if (entry) out.push(entry);
+    }
+    return out;
+  }
+};
+function makeTrace(startedAt, rings) {
+  const dump = () => {
+    const all = rings();
+    const entries = all.flatMap((ring) => ring.entries()).sort((a, b) => a.at - b.at);
+    return {
+      startedAt,
+      bots: all.length,
+      dropped: all.reduce((sum, ring) => sum + ring.dropped, 0),
+      entries
+    };
+  };
+  return {
+    entries: () => [...dump().entries],
+    get dropped() {
+      return rings().reduce((sum, ring) => sum + ring.dropped, 0);
+    },
+    async save(path) {
+      await writeFile(path, `${JSON.stringify(dump(), null, 2)}
+`, "utf8");
+    }
+  };
+}
+
+// src/observer.ts
+var WriteLog = class {
+  constructor(limit = 4096) {
+    this.limit = limit;
+  }
+  limit;
+  entries = /* @__PURE__ */ new Map();
+  record(key, at, bot) {
+    if (this.entries.size >= this.limit) {
+      const oldest = this.entries.keys().next();
+      if (!oldest.done) this.entries.delete(oldest.value);
+    }
+    this.entries.set(key, { at, bot });
+  }
+  /** The time *another* bot wrote this exact value, consuming the entry. */
+  match(key, bot) {
+    const found = this.entries.get(key);
+    if (!found || found.bot === bot) return void 0;
+    this.entries.delete(key);
+    return found.at;
+  }
+};
+function writeKey(collection, id, field, value) {
+  const kind = typeof value;
+  if (kind !== "number" && kind !== "string" && kind !== "boolean") return void 0;
+  return [collection, id, field, String(value)].join("\0");
+}
+var SecondWindow = class {
+  at = [];
+  amount = [];
+  sum = 0;
+  add(now, amount) {
+    this.at.push(now);
+    this.amount.push(amount);
+    this.sum += amount;
+    while (this.at.length > 0 && now - (this.at[0] ?? now) > 1e3) {
+      this.sum -= this.amount.shift() ?? 0;
+      this.at.shift();
+    }
+    return this.sum;
+  }
+};
+var DETAIL_LIMIT = 5;
+var VIOLATION_COOLDOWN_MS = 1e3;
+var BotObserver = class {
+  constructor(options) {
+    this.options = options;
+    this.ring = new TraceRing(options.traceLimit);
+  }
+  options;
+  ring;
+  violations = /* @__PURE__ */ new Map();
+  counts = /* @__PURE__ */ new Map();
+  id = "";
+  role = "";
+  roomId = "";
+  /** Set before `leave()`, so a deliberate teardown is not reported as a disconnect. */
+  stopping = false;
+  framesIn = 0;
+  framesOut = 0;
+  bytesIn = 0;
+  bytesOut = 0;
+  corrections = 0;
+  calls = 0;
+  errors = 0;
+  disconnects = 0;
+  peakBytesInPerSec = 0;
+  peakCorrectionsPerSec = 0;
+  bytesWindow = new SecondWindow();
+  correctWindow = new SecondWindow();
+  cooldown = /* @__PURE__ */ new Map();
+  get stats() {
+    return {
+      index: this.options.index,
+      id: this.id,
+      role: this.role,
+      framesIn: this.framesIn,
+      framesOut: this.framesOut,
+      bytesIn: this.bytesIn,
+      bytesOut: this.bytesOut,
+      corrections: this.corrections,
+      calls: this.calls,
+      errors: this.errors,
+      disconnects: this.disconnects,
+      peakBytesInPerSec: this.peakBytesInPerSec,
+      peakCorrectionsPerSec: this.peakCorrectionsPerSec
+    };
+  }
+  /** Counts a violation always; keeps an example, rate-limited per invariant when asked. */
+  violate(name, message, rateLimit = false) {
+    this.counts.set(name, (this.counts.get(name) ?? 0) + 1);
+    const now = Date.now();
+    if (rateLimit && now - (this.cooldown.get(name) ?? Number.NEGATIVE_INFINITY) < VIOLATION_COOLDOWN_MS) {
+      return;
+    }
+    this.cooldown.set(name, now);
+    const list = this.violations.get(name) ?? [];
+    if (list.length < DETAIL_LIMIT) list.push(`bot ${this.options.index}: ${message}`);
+    this.violations.set(name, list);
+  }
+  /** `room.on('status')`: transitions away from a healthy connection, ignored during teardown. */
+  onStatus(status) {
+    if (this.stopping) return;
+    if (status !== "reconnecting" && status !== "closed") return;
+    this.disconnects++;
+    this.violate("disconnects", `status became ${status}`);
+  }
+  /** The `onFrame` hook. `bytes` is the whole frame, envelope byte included. */
+  onFrame(dir, type, bytes) {
+    const now = Date.now();
+    let note;
+    if (dir === "in") {
+      this.framesIn++;
+      this.bytesIn += bytes.length;
+      const perSec = this.bytesWindow.add(now, bytes.length);
+      if (perSec > this.peakBytesInPerSec) this.peakBytesInPerSec = perSec;
+      if (perSec > this.options.thresholds.budgetBytesPerSec) {
+        this.violate(
+          "bandwidth",
+          `${perSec} B/s inbound over the ${this.options.thresholds.budgetBytesPerSec} B/s budget`,
+          true
+        );
+      }
+    } else {
+      this.framesOut++;
+      this.bytesOut += bytes.length;
+    }
+    try {
+      note = this.inspect(dir, type, bytes, now);
+    } catch (err) {
+      note = err instanceof Error ? err.message : String(err);
+      this.violate("schema-validity", `${frameName(type)} did not decode: ${note}`);
+    }
+    this.ring.push({
+      at: now - this.options.startedAt,
+      bot: this.options.index,
+      dir,
+      type,
+      frame: frameName(type),
+      bytes: bytes.length,
+      ...note !== void 0 ? { note } : {}
+    });
+  }
+  /** Decodes the payload independently. Throws on a bad frame; the caller counts that. */
+  inspect(dir, type, bytes, now) {
+    const payload = decodeFrame(bytes).payload;
+    if (dir === "out") {
+      if (type === FrameType3.CALL) this.calls++;
+      if (type === FrameType3.WRITE) this.recordWrites(decodeDelta2(this.options.ext, payload), now);
+      return void 0;
+    }
+    switch (type) {
+      case FrameType3.WELCOME:
+        return this.onWelcome(decodeWelcome(payload));
+      case FrameType3.DELTA:
+        return this.onDelta(decodeDelta2(this.options.ext, payload), now);
+      case FrameType3.CORRECT:
+        return this.onCorrect(decodeDelta2(this.options.ext, payload), now);
+      case FrameType3.ERROR:
+        return this.onError(payload);
+      case FrameType3.REPLY:
+        return this.onReply(payload);
+      default:
+        return void 0;
+    }
+  }
+  onWelcome(welcome) {
+    this.id = welcome.clientId;
+    this.role = welcome.role;
+    this.roomId = welcome.roomId;
+    const snapshot = decodeSnapshot(this.options.ext, welcome.snapshot);
+    for (const leak of snapshotVisibilityLeaks(this.options.ext, this.role, snapshot.state)) {
+      this.violate("visibility-leak", leak);
+    }
+    return `joined ${welcome.roomId} as ${welcome.clientId}/${welcome.role || "default"}`;
+  }
+  onDelta(delta, now) {
+    for (const leak of deltaVisibilityLeaks(this.options.ext, this.role, delta)) {
+      this.violate("visibility-leak", leak);
+    }
+    this.matchWrites(delta, now);
+    return void 0;
+  }
+  onCorrect(delta, now) {
+    this.corrections++;
+    for (const leak of deltaVisibilityLeaks(this.options.ext, this.role, delta)) {
+      this.violate("visibility-leak", leak);
+    }
+    const perSec = this.correctWindow.add(now, 1);
+    if (perSec > this.peakCorrectionsPerSec) this.peakCorrectionsPerSec = perSec;
+    if (perSec > this.options.thresholds.correctionsPerSecMax) {
+      this.violate(
+        "correction-storm",
+        `${perSec} corrections/s over the ${this.options.thresholds.correctionsPerSecMax}/s threshold`,
+        true
+      );
+    }
+    return `corrected ${delta.collections.map((c) => c.name).join(",")}`;
+  }
+  onError(payload) {
+    const error = decodeErrorPayload(payload);
+    let name;
+    try {
+      name = errorByCode(error.code).name;
+    } catch {
+      name = `code ${error.code}`;
+    }
+    if (!error.fatal) {
+      this.errors++;
+      this.violate("handler-error", `${name}: ${error.message}`);
+    }
+    return `${name}${error.fatal ? " (fatal)" : ""}`;
+  }
+  onReply(payload) {
+    const reply = decodeReply(payload);
+    if (reply.ok) return void 0;
+    this.errors++;
+    this.violate("handler-error", `reply #${reply.reqId} rejected: ${reply.error}`);
+    return `rejected: ${reply.error}`;
+  }
+  // -- convergence lag ------------------------------------------------------
+  eachScalar(delta, fn) {
+    for (const collection of delta.collections) {
+      for (const op of collection.ops) {
+        const values = op.op === "add" ? op.value : op.op === "update" ? op.patch : void 0;
+        if (!values) continue;
+        for (const [field, value] of Object.entries(values)) fn(collection.name, op, field, value);
+      }
+    }
+  }
+  /** Our own `WRITE`: remember what we sent, so whoever sees it can date it. */
+  recordWrites(delta, now) {
+    this.eachScalar(delta, (collection, op, field, value) => {
+      const key = writeKey(collection, op.id, field, value);
+      if (key) this.options.writeLog.record(key, now, this.options.index);
+    });
+  }
+  /** Somebody else's write arriving here: that round trip is the convergence lag. */
+  matchWrites(delta, now) {
+    this.eachScalar(delta, (collection, op, field, value) => {
+      const key = writeKey(collection, op.id, field, value);
+      if (!key) return;
+      const sentAt = this.options.writeLog.match(key, this.options.index);
+      if (sentAt !== void 0) this.options.lags.push(now - sentAt);
+    });
+  }
+};
+
+// src/random.ts
+var INT_RANGE = {
+  u8: [0, 255],
+  u16: [0, 65535],
+  u32: [0, 4294967295],
+  i32: [-2147483648, 2147483647]
+};
+function makeRng(seed) {
+  let state = seed >>> 0;
+  const next = () => {
+    state = state + 1831565813 >>> 0;
+    let t = state;
+    t = Math.imul(t ^ t >>> 15, t | 1);
+    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+  return {
+    next,
+    int: (lo, hi) => hi <= lo ? lo : lo + Math.floor(next() * (hi - lo + 1)),
+    float: (lo, hi) => lo + next() * (hi - lo),
+    chance: (p) => next() < p,
+    pick: (items) => items.length === 0 ? void 0 : items[Math.floor(next() * items.length)]
+  };
+}
+var MEAN_REVERSION = 0.05;
+var CHEAT_JUMP = 1e5;
+function walk(rng, current, ctx) {
+  if (ctx.cheat) return current + (rng.chance(0.5) ? CHEAT_JUMP : -CHEAT_JUMP);
+  const pull = ctx.origin === void 0 ? 0 : (ctx.origin - current) * MEAN_REVERSION;
+  return current + rng.float(-ctx.step, ctx.step) + pull;
+}
+function clampInt(v, lo, hi) {
+  return Math.min(hi, Math.max(lo, Math.round(v)));
+}
+var ALPHABET = "abcdefghijklmnopqrstuvwxyz";
+function token(rng, max) {
+  const n = Math.min(max, rng.int(1, 8));
+  let s = "";
+  for (let i = 0; i < n; i++) s += ALPHABET[rng.int(0, ALPHABET.length - 1)] ?? "x";
+  return s;
+}
+function nextValue(rng, desc, current, ctx) {
+  if (desc.opt && rng.chance(0.1)) return void 0;
+  switch (desc.kind) {
+    case "bool":
+      return typeof current === "boolean" ? !current : rng.chance(0.5);
+    case "u8":
+    case "u16":
+    case "u32":
+    case "i32": {
+      const [lo, hi] = INT_RANGE[desc.kind];
+      if (ctx.cheat) return rng.chance(0.5) ? lo : hi;
+      const base = typeof current === "number" ? current : 0;
+      return clampInt(walk(rng, base, ctx), lo, hi);
+    }
+    case "f32":
+    case "f64": {
+      const base = typeof current === "number" && Number.isFinite(current) ? current : 0;
+      return walk(rng, base, ctx);
+    }
+    case "str":
+      return desc.max === 0 ? "" : token(rng, desc.max);
+    case "enum":
+      return rng.pick(desc.values) ?? desc.values[0] ?? "";
+    case "ref":
+      return rng.pick(ctx.refIds ?? []) ?? "";
+    case "list": {
+      const n = Math.min(desc.max, rng.int(0, 3));
+      const out = [];
+      for (let i = 0; i < n; i++) out.push(nextValue(rng, desc.item, void 0, ctx));
+      return out;
+    }
+    case "struct": {
+      const out = {};
+      const from = typeof current === "object" && current !== null ? current : {};
+      for (const [name, field] of Object.entries(desc.fields)) {
+        out[name] = nextValue(rng, field, from[name], ctx);
+      }
+      return out;
+    }
+  }
+}
+function freshValue(rng, desc, ctx) {
+  return nextValue(rng, desc, void 0, { ...ctx, cheat: false, origin: void 0 });
+}
+
+// src/report.ts
+function percentile(sorted, p) {
+  if (sorted.length === 0) return 0;
+  const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil(p / 100 * sorted.length) - 1));
+  return sorted[index] ?? 0;
+}
+function convergenceStats(lags) {
+  if (lags.length === 0) return void 0;
+  const sorted = [...lags].sort((a, b) => a - b);
+  return {
+    samples: sorted.length,
+    p50Ms: percentile(sorted, 50),
+    p95Ms: percentile(sorted, 95),
+    maxMs: sorted[sorted.length - 1] ?? 0
+  };
+}
+function round(value, places = 1) {
+  const factor = 10 ** places;
+  return Math.round(value * factor) / factor;
+}
+function examples(observers, name) {
+  const lines = observers.flatMap((o) => o.violations.get(name) ?? []).slice(0, 5);
+  return lines.length === 0 ? "" : `; ${lines.join("; ")}`;
+}
+function total(observers, name) {
+  return observers.reduce((sum, o) => sum + (o.counts.get(name) ?? 0), 0);
+}
+function peak(observers, pick) {
+  return observers.reduce((max, o) => Math.max(max, pick(o)), 0);
+}
+function detailFor(name, observers, violations, thresholds) {
+  switch (name) {
+    case "schema-validity":
+      return violations === 0 ? "every snapshot and delta decoded" : `${violations} frame(s) failed to decode${examples(observers, name)}`;
+    case "visibility-leak":
+      return violations === 0 ? "no collection reached a role that cannot see it" : `${violations} leak(s)${examples(observers, name)}`;
+    case "bandwidth": {
+      const worst = peak(observers, (o) => o.peakBytesInPerSec);
+      return `peak ${worst} B/s in per bot, budget ${thresholds.budgetBytesPerSec} B/s${violations === 0 ? "" : examples(observers, name)}`;
+    }
+    case "handler-error": {
+      const errors = observers.reduce((sum, o) => sum + o.errors, 0);
+      return `${errors} error reply/frame(s), tolerated ${thresholds.handlerErrorsMax}${violations === 0 ? "" : examples(observers, name)}`;
+    }
+    case "correction-storm": {
+      const corrections = observers.reduce((sum, o) => sum + o.corrections, 0);
+      const worst = peak(observers, (o) => o.peakCorrectionsPerSec);
+      return `${corrections} correction(s), peak ${worst}/s per bot, threshold ${thresholds.correctionsPerSecMax}/s${violations === 0 ? "" : examples(observers, name)}`;
+    }
+    case "disconnects": {
+      const count = observers.reduce((sum, o) => sum + o.disconnects, 0);
+      return count === 0 ? "every bot stayed connected" : `${count} disconnect(s)${examples(observers, name)}`;
+    }
+  }
+}
+function buildReport(options) {
+  const { observers, roomId, lags } = options;
+  const thresholds = options.thresholds ?? DEFAULT_THRESHOLDS;
+  const durationMs = Math.max(1, options.durationMs);
+  const seconds = durationMs / 1e3;
+  const invariants = INVARIANT_NAMES.map((name) => {
+    const violations = total(observers, name);
+    const ok = name === "handler-error" ? violations <= thresholds.handlerErrorsMax : violations === 0;
+    return { name, ok, violations, detail: detailFor(name, observers, violations, thresholds) };
+  });
+  const perBot = observers.map((o) => o.stats);
+  const totals = {
+    framesIn: perBot.reduce((sum, b) => sum + b.framesIn, 0),
+    framesOut: perBot.reduce((sum, b) => sum + b.framesOut, 0),
+    bytesIn: perBot.reduce((sum, b) => sum + b.bytesIn, 0),
+    bytesOut: perBot.reduce((sum, b) => sum + b.bytesOut, 0),
+    corrections: perBot.reduce((sum, b) => sum + b.corrections, 0),
+    calls: perBot.reduce((sum, b) => sum + b.calls, 0),
+    errors: perBot.reduce((sum, b) => sum + b.errors, 0)
+  };
+  const bots = Math.max(1, perBot.length);
+  const convergence = convergenceStats(lags);
+  return {
+    ok: invariants.every((i) => i.ok),
+    bots: perBot.length,
+    roomId,
+    durationMs,
+    invariants,
+    perBot,
+    totals,
+    framesPerSecond: round((totals.framesIn + totals.framesOut) / seconds),
+    bytesInPerSecondPerBot: round(totals.bytesIn / seconds / bots),
+    bytesOutPerSecondPerBot: round(totals.bytesOut / seconds / bots),
+    convergence,
+    convergenceLagMs: convergence?.p50Ms,
+    tracePath: options.tracePath
+  };
+}
+
+// src/script.ts
+import { rpcTable } from "@irtio/protocol";
+function ownableCollections(schema) {
+  return schema.collections.filter(
+    (c) => c.kind === "entity" && !c.serverOwned
+  );
+}
+function voidServerRpcs(schema) {
+  return rpcTable(schema).filter((r) => r.direction === "server" && r.returns === void 0);
+}
+function asCollection(value) {
+  return value && typeof value.ownerOf === "function" ? value : void 0;
+}
+function randomScript(schema, options = {}) {
+  const cheat = options.cheat ?? false;
+  const stepMs = options.stepMs ?? 50;
+  const step = options.step ?? 8;
+  const rpcChance = options.rpcChance ?? 0.05;
+  const fieldsPerStep = options.fieldsPerStep ?? 2;
+  const collections = ownableCollections(schema);
+  const rpcs = voidServerRpcs(schema);
+  return async (bot) => {
+    const room = bot.room;
+    const origins = /* @__PURE__ */ new Map();
+    while (!bot.stopped) {
+      for (const desc of collections) {
+        const collection = asCollection(room.state[desc.name]);
+        if (!collection) continue;
+        for (const id of [...collection.ids()]) {
+          if (collection.ownerOf(id) !== room.me) continue;
+          const instance = collection.get(id);
+          if (!instance) continue;
+          writeFields(bot, desc, id, instance, origins);
+        }
+      }
+      if (rpcs.length > 0 && bot.rng.chance(rpcChance)) await callRandomRpc(bot, room.call, rpcs);
+      await bot.wait(stepMs);
+    }
+  };
+  function writeFields(bot, desc, id, instance, origins) {
+    const count = Math.min(fieldsPerStep, desc.fields.length);
+    for (let i = 0; i < count; i++) {
+      const field = bot.rng.pick(desc.fields);
+      if (!field) continue;
+      const current = instance[field.name];
+      const key = `${desc.name} ${id} ${field.name}`;
+      if (typeof current === "number" && !origins.has(key)) origins.set(key, current);
+      const value = nextValue(bot.rng, field.type, current, {
+        step,
+        cheat,
+        origin: origins.get(key)
+      });
+      instance[field.name] = value;
+    }
+  }
+  async function callRandomRpc(bot, call, table) {
+    const rpc = bot.rng.pick(table);
+    const fn = rpc ? call[rpc.name] : void 0;
+    if (!rpc || !fn) return;
+    const params = {};
+    for (const param of rpc.params) {
+      params[param.name] = freshValue(bot.rng, param.type, { step, cheat: false });
+    }
+    await fn(params).catch(() => void 0);
+  }
+}
+function relayEchoScript(options = {}) {
+  const everyMs = options.everyMs ?? 200;
+  const size = options.bytes ?? 16;
+  return async (bot) => {
+    while (!bot.stopped) {
+      const payload = new Uint8Array(size);
+      for (let i = 0; i < size; i++) payload[i] = bot.rng.int(0, 255);
+      payload[0] = bot.index & 255;
+      bot.room.message("all", payload);
+      await bot.wait(everyMs);
+    }
+  };
+}
+
+// src/spawn.ts
+import {
+  joinRelay,
+  joinRoom
+} from "@irtio/client";
+import { relaySchema, withBuiltins } from "@irtio/protocol";
+var DEFAULT_SEED = 96016;
+var DEFAULT_TRACE_LIMIT = 4096;
+function per(value, index) {
+  if (value === void 0) return void 0;
+  return typeof value === "function" ? value(index) : value;
+}
+var BotImpl = class {
+  constructor(index, room, observer, seed, startedAt) {
+    this.index = index;
+    this.room = room;
+    this.observer = observer;
+    this.startedAt = startedAt;
+    this.rng = makeRng(seed);
+  }
+  index;
+  room;
+  observer;
+  startedAt;
+  stopped = false;
+  rng;
+  stopListeners = /* @__PURE__ */ new Set();
+  get id() {
+    return this.observer.id;
+  }
+  get role() {
+    return this.observer.role;
+  }
+  random() {
+    return this.rng.next();
+  }
+  get trace() {
+    return makeTrace(this.startedAt, () => [this.observer.ring]);
+  }
+  get stats() {
+    return this.observer.stats;
+  }
+  stop() {
+    if (this.stopped) return;
+    this.stopped = true;
+    for (const listener of [...this.stopListeners]) listener();
+    this.stopListeners.clear();
+  }
+  onStop(listener) {
+    this.stopListeners.add(listener);
+    return () => {
+      this.stopListeners.delete(listener);
+    };
+  }
+  wait(ms) {
+    if (this.stopped) return Promise.resolve();
+    return new Promise((resolve) => {
+      const timer = setTimeout(finish, ms);
+      timer.unref?.();
+      const off = this.onStop(finish);
+      function finish() {
+        clearTimeout(timer);
+        off();
+        resolve();
+      }
+    });
+  }
+  async until(predicate, options = {}) {
+    const label = options.label ?? "a condition";
+    const everyMs = options.everyMs ?? 10;
+    const deadline = Date.now() + (options.timeoutMs ?? 1e4);
+    for (; ; ) {
+      if (this.stopped) return;
+      if (await predicate()) return;
+      if (Date.now() > deadline) {
+        throw new Error(`irtio bots: bot ${this.index} timed out waiting for ${label}`);
+      }
+      await this.wait(everyMs);
+    }
+  }
+};
+async function spawnBots(n, options = {}) {
+  if (!Number.isInteger(n) || n < 1) {
+    throw new Error(`irtio bots: spawnBots needs at least one bot, got ${String(n)}`);
+  }
+  const startedAt = Date.now();
+  const thresholds = {
+    budgetBytesPerSec: options.budgetBytesPerSec ?? DEFAULT_THRESHOLDS.budgetBytesPerSec,
+    correctionsPerSecMax: options.correctionsPerSecMax ?? DEFAULT_THRESHOLDS.correctionsPerSecMax,
+    handlerErrorsMax: options.handlerErrorsMax ?? DEFAULT_THRESHOLDS.handlerErrorsMax
+  };
+  const ext = options.schema ? withBuiltins(options.schema) : relaySchema;
+  const seed = options.seed ?? DEFAULT_SEED;
+  const traceLimit = options.traceLimit ?? DEFAULT_TRACE_LIMIT;
+  const writeLog = new WriteLog();
+  const lags = [];
+  const observers = [];
+  const bots = [];
+  async function joinOne(index, roomId2) {
+    const observer = new BotObserver({
+      index,
+      ext,
+      startedAt,
+      traceLimit,
+      thresholds,
+      writeLog,
+      lags
+    });
+    const role = per(options.role, index);
+    const name = per(options.name, index);
+    const common = {
+      room: roomId2,
+      ...options.url !== void 0 ? { url: options.url } : {},
+      ...options.key !== void 0 ? { key: options.key } : {},
+      ...role !== void 0 ? { role } : {},
+      ...name !== void 0 ? { name } : {},
+      ...options.transport !== void 0 ? { transport: options.transport } : {},
+      onFrame: (dir, type, bytes) => observer.onFrame(dir, type, bytes),
+      onStatus: (status) => observer.onStatus(status)
+    };
+    const room = options.schema ? await joinRoom(options.schema, {
+      ...common,
+      ...options.flushMs !== void 0 ? { writeIntervalMs: options.flushMs } : {},
+      ...options.rpc !== void 0 ? { rpc: options.rpc } : {}
+    }) : await joinRelay(common);
+    observers[index] = observer;
+    return new BotImpl(index, room, observer, seed + index, startedAt);
+  }
+  const first = await joinOne(0, options.room ?? "");
+  bots.push(first);
+  const roomId = first.room.id;
+  if (n > 1) {
+    const rest = await Promise.all(Array.from({ length: n - 1 }, (_, i) => joinOne(i + 1, roomId)));
+    bots.push(...rest);
+  }
+  const scriptErrors = [];
+  let firstError;
+  const script = options.script;
+  const scripts = bots.map(async (bot) => {
+    if (!script) {
+      await bot.until(() => bot.stopped, { label: "the run to end", timeoutMs: 24 * 36e5 });
+      return;
+    }
+    try {
+      await script(bot);
+    } catch (error) {
+      scriptErrors.push({ bot: bot.index, error });
+      firstError ??= error;
+    }
+  });
+  const finished = Promise.all(scripts).then(() => void 0);
+  let deadline;
+  if (options.durationMs !== void 0) {
+    deadline = setTimeout(() => {
+      for (const bot of bots) bot.stop();
+    }, options.durationMs);
+    deadline.unref?.();
+  }
+  let stoppedAt;
+  const rings = () => observers.map((o) => o.ring);
+  const runner = {
+    bots,
+    roomId,
+    trace: makeTrace(startedAt, rings),
+    scriptErrors,
+    [Symbol.iterator]: () => bots[Symbol.iterator](),
+    async done() {
+      await finished;
+      if (firstError !== void 0) throw firstError;
+    },
+    report() {
+      return buildReport({
+        observers,
+        roomId,
+        durationMs: (stoppedAt ?? Date.now()) - startedAt,
+        lags,
+        thresholds
+      });
+    },
+    async stop() {
+      if (deadline) clearTimeout(deadline);
+      for (const bot of bots) bot.stop();
+      await finished;
+      stoppedAt ??= Date.now();
+      for (const observer of observers) observer.stopping = true;
+      for (const bot of bots) bot.room.leave();
+      return this.report();
+    }
+  };
+  return runner;
+}
+export {
+  BotObserver,
+  DEFAULT_SEED,
+  DEFAULT_THRESHOLDS,
+  DEFAULT_TRACE_LIMIT,
+  INVARIANT_NAMES,
+  TraceRing,
+  WriteLog,
+  buildReport,
+  convergenceStats,
+  deltaVisibilityLeaks,
+  frameName,
+  frameVisibilityLeaks,
+  freshValue,
+  makeRng,
+  makeTrace,
+  nextValue,
+  randomScript,
+  relayEchoScript,
+  snapshotVisibilityLeaks,
+  spawnBots
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@irtio/bots",
+  "version": "0.1.0",
+  "description": "irtio bot runtime: N real clients, scripted behaviours, trace recorder, built-in invariants",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@irtio/client": "0.1.0",
+    "@irtio/protocol": "0.1.0",
+    "@irtio/schema": "0.1.0",
+    "@irtio/runtime": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}