@homie-rocks/studio 0.46.5 → 0.46.6

package/CHANGELOG.md

@@ -17,6 +17,31 @@ To bring a studio up to date, tell Claude: "Upgrade my studio to the newest Homi
 `npx -y @homie-rocks/studio@latest upgrade`, which shows what's new since the version your studio pins (from this
 file) and what the upgrade would change, and changes nothing until you agree.
 
+## [0.46.6] - 2026-10-11
+
+**Plugin 0.46.6** · Big rooms: what one room carries, measured.
+
+What one room object carries on Cloudflare, measured in six trials and stated: with a light game at 20 ticks a second, 300 players with margin, 600 at the edge, 800 to 1,000 only by luck.
+
+### Changed
+
+- A big match room's once-a-second checkpoint no longer holds its frames. Cloudflare holds whatever an object sends after a storage write until the write is confirmed, so one or two worlds a second reached every Gate a tick late, at every size. The checkpoint is now written with `allowUnconfirmed`; a save an admission asks for is confirmed as before and replaces it. A lasting world's writes are unchanged. At 300 players the gap every Gate saw once a second is gone, and a Gate's round trip to the room fell from 40 ms to 18.
+- A big room costs less of its one thread than on 0.46.3 (a fifth less; a quarter less when inputs arrive late): it no longer builds the whole snapshot as text for nobody, does not encode an ASCII message to measure it, and reads the round trip it tells the rules, for a player behind a Gate, once a second from its ten-second window, not once an input.
+- A player is sent fewer frames only when behind and not catching up. A connection that stalls for a second and then delivers what it held catches up by itself; 0.46.2 slowed every player of a healthy room of 600 when their one home link hiccuped.
+- A Gate nobody is on gives its channel to the room back after ten seconds; the next player to arrive opens another. An open channel kept a big room and its Gates in memory after everybody had left.
+- Each Gate reports the share of worlds over 100, 200 and 400 ms old and the players more than a second behind, beside the worst of each second.
+
+### Added
+
+- Measuring a game's capacity on your own Cloudflare account (`lib/crowd-probe/README.md`): the in-Cloudflare probe offers compression as a browser does, reports every thirty seconds so a request cut short has still said what it saw, can play slow players among healthy ones (`--slow-every`), and times a fixed piece of work against your computer with the stopwatch outside Cloudflare (`--calibrate`). `lib/crowd-probe/run-trial.sh` runs a whole trial, each in-Cloudflare step three times, and writes one summary. The home driver can stop every Kth player's socket reading (`--slow-every`). Slow players' own figures are kept apart from everybody else's.
+
+### Upgrade notes
+
+- 1,000 players in one room is not promised; past what one room carries a world is split across rooms. Rooms of 64 seats or fewer and games a player's browser hosts are not on any of this path and behave as on 0.46.3.
+- **What one room carries** is in the README ("Room size and delivery") and, with the measurements and the ways past one room, in `docs/rooms-capacity-findings.md`. Homie still sets no limit on `players.max`: choose it with your own game's numbers.
+- Nothing an object measures about itself by its own clock is to be trusted on Cloudflare: a Worker's clock stands still while its code runs and reads a timer's due time when the timer fires. Each Gate's 20 ms lateness timer (added early in this release) read 0 in every step of every trial, fallen ones too. Read a Gate's round trip to the room and the share of worlds over 200 ms old.
+- `HOMIE_GATE_PLAYERS` on a studio's Worker sets the players a Gate holds, for a trial that is finding the right number. A studio does not set it.
+- The local crowd reproduction (eight workerd processes, two Chrome players and the load driver on one computer) is no longer a check. Run it by hand with `npm run test:crowd`; `docs/crowd-transport-0462.md` says what it can and cannot show.
 ## [0.46.5] - 2026-10-11
 
 **Plugin 0.46.5**

package/README.md

@@ -222,7 +222,18 @@ For example, a 300-player room can choose spatial delivery explicitly:
 The studio chooses the radius, precision and distant update rate for its game. The
 controlled body stays precise. Whole-room state remains the default. The build runs a
 local capacity trial; its numbers are not Cloudflare capacity guarantees. Test the actual
-mechanic at the chosen size. Rules builds derive their revision from rules and view;
+mechanic at the chosen size.
+
+**What one room carries.** A room's rules run in one object on one thread, whatever its
+`players.max`. Measured on Cloudflare in October 2026 with a light game at 20 ticks a
+second (every player in one dense arena, ten inputs a second each): 300 players with
+margin (clean in every run), 600 at the edge (four runs of six), and 800 to 1,000 only by
+luck (five runs of twenty-five). A game with heavier rules carries fewer. Homie sets no
+limit on `players.max`; it is the studio's to choose with its own game's numbers:
+`lib/crowd-probe/README.md` is how to measure them on your own Cloudflare account. Beyond
+what one room carries, a world is split across rooms (several rooms of a game today; one
+world of many areas is on the roadmap). `docs/rooms-capacity-findings.md` in the Homie
+repository has the measurements. Rules builds derive their revision from rules and view;
 do not manually bump `netplay.version`. Optional `netplay.params` still selects play-page
 query parameters passed to the view, beside `debug` and `q`.
 

package/lib/crowd-cloud.mjs

@@ -3,7 +3,8 @@
  * One crowd step played from inside Cloudflare, through the in-Cloudflare probe (lib/crowd-probe/README.md).
  *
  *   node lib/crowd-cloud.mjs --probe <probe address> --key <PROBE_KEY> --url <studio> --n 300
- *        [--seconds 150] [--room <name>] [--out <dir>] [--ramp-ms 50] [--game crowd-circuit]
+ *        [--seconds 150] [--room <name>] [--out <dir>] [--ramp-ms 50] [--game crowd-circuit] [--compress on] [--slow-every 10]
+ *   node lib/crowd-cloud.mjs --probe <probe address> --key <PROBE_KEY> --calibrate <file>
  *
  * It opens a request to the probe for every five players, holds them open for the step, and writes report.json in
  * the shape crowd-load.mjs writes (what applies: there is no browser and no home connection in this one).
@@ -12,12 +13,44 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Tally } from './crowd-probe/client.mjs';
+import { referenceWork } from './crowd-probe/reference-work.mjs';
 
 const pick = (sorted, q) => (sorted.length ? sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * q))] : null);
 
 /** Every probe request's last line, added up into one report. */
-export function cloudReport({ origin, room, n, seconds, started, measureAt, endAt, finals, failures = [], toolkit = null }) {
-  const players = finals.flatMap((f) => f.players), tallies = { ack: new Tally(), gaps: new Tally(), loops: new Tally() };
+/**
+ * How fast Cloudflare runs the reference work against this computer. A Worker cannot time its own work, so the
+ * stopwatch is here: a request that does the work `rounds` times, less a request that does none, each the quickest
+ * of several (the least delayed by the connection), divided by the rounds. This process times the same call.
+ * `ratio` is Cloudflare's milliseconds over this computer's: what a millisecond of test/crowd-room-cost.mjs costs there.
+ */
+export async function calibrate({ probe, key, requests = 6, rounds = 10, fetchFn = fetch, now = () => performance.now() }) {
+  referenceWork(4);
+  const local = [];
+  for (let i = 0; i < 5; i += 1) { const at = now(); referenceWork(); local.push(Math.round((now() - at) * 100) / 100); }
+  const check = referenceWork(), mine = Math.min(...local);
+  const ask = async (n) => { const at = now(); const answer = await (await fetchFn(`${probe}/calibrate?rounds=${n}&i=${Math.round(at)}`, { headers: { 'x-probe-key': key }, signal: AbortSignal.timeout(120000) })).json(); return { ms: Math.round((now() - at) * 100) / 100, ...answer }; };
+  const empty = [], worked = [];
+  for (let i = 0; i < requests; i += 1) {
+    try { empty.push(await ask(0)); } catch { /* one reading fewer */ }
+    try { const answer = await ask(rounds); if (answer.ok && answer.rounds === rounds) worked.push(answer); } catch { /* one reading fewer */ }
+  }
+  const base = Math.min(...empty.map((e) => e.ms)), each = worked.map((w) => Math.round((w.ms - base) / rounds * 100) / 100).sort((a, b) => a - b);
+  const of = (ms) => (Number.isFinite(ms) && mine > 0 ? Math.round(ms / mine * 100) / 100 : null);
+  return { at: new Date().toISOString(), rounds, localMs: local, emptyRequestMs: empty.map((e) => e.ms), workedRequestMs: worked.map((w) => w.ms), colos: [...new Set(worked.map((w) => w.colo).filter(Boolean))],
+    // What the Worker's own clock said the same rounds took: next to the stopwatch's figure, what a clock inside is worth.
+    workerOwnClockMs: worked.map((w) => w.own),
+    cloudMsARound: { min: each[0] ?? null, median: pick(each, 0.5), max: each.at(-1) ?? null },
+    ratio: each.length && Number.isFinite(base) ? { min: of(each[0]), median: of(pick(each, 0.5)), max: of(each.at(-1)) } : null,
+    same: worked.every((w) => w.check === check) };
+}
+
+export function cloudReport({ origin, room, n, seconds, started, measureAt, endAt, finals, failures = [], toolkit = null, compress = false, lost = 0, roomHz = 20 }) {
+  // A probe's clock is a Worker's: it reads a timer's due time and runs slow when the Worker runs late, so a rate
+  // timed by it reads high (the fifth trial's rows of 25 to 32 "ticks a second" from a 20-tick room). Frames for
+  // each tick the room advanced need no clock: times the room's rate, that is frames a second. (Not for a slow
+  // player, whose ticks are the ones it has got to: its rate stays by the clock.)
+  const players = finals.flatMap((f) => f.players).map((p) => (Number.isFinite(p.framesPerTick) && !p.slow ? { ...p, clockDeliveredHz: p.deliveredHz, deliveredHz: p.framesPerTick * roomHz } : p)), tallies = { ack: new Tally(), gaps: new Tally(), loops: new Tally() };
   for (const f of finals) for (const key of Object.keys(tallies)) tallies[key].merge(f.tallies?.[key]);
   const of = (key) => players.map((p) => p[key]).filter(Number.isFinite).sort((a, b) => a - b);
   const range = (key) => { const a = of(key); return { count: a.length, min: a[0] ?? null, median: pick(a, 0.5), p50: pick(a, 0.5), max: a.at(-1) ?? null }; };
@@ -36,10 +69,25 @@ export function cloudReport({ origin, room, n, seconds, started, measureAt, endA
     inputAckMs: tallies.ack.json(), receiveGapMs: tallies.gaps.json(),
     // From the tick a player held when it stamped an input to the tick that input reached the rules.
     inputLoopMs: tallies.loops.json(),
-    tickHz: range('tickHz'), deliveredHz: range('deliveredHz'),
-    payload: { upBytes: sum('upBytes'), downBytes: sum('downBytes'), inputFrames: sum('inputs'), downFrames: sum('frames'), wireDownBytes: 0, compressedSockets: 0 },
-    // Sockets that never leave Cloudflare are not compressed and cross no home connection.
-    compression: { offered: false, sockets: 0, of: players.length, ratio: null },
+    // `tickHz` is by the probe's own clock (see above): above the room's rate, it says the probe ran late.
+    tickHz: range('tickHz'), tickHzClock: 'probe', deliveredHz: range('deliveredHz'), framesPerTick: range('framesPerTick'),
+    payload: { upBytes: sum('upBytes'), downBytes: sum('downBytes'), inputFrames: sum('inputs'), downFrames: sum('frames'), wireDownBytes: 0, compressedSockets: players.filter((p) => p.compressed).length },
+    // Sockets that never leave Cloudflare cross no home connection; with --compress on the studio's Gates compress
+    // for them as for a browser (the bytes saved cannot be seen from inside a Worker).
+    compression: { offered: Boolean(compress), sockets: players.filter((p) => p.compressed).length, of: players.length, ratio: null },
+    // Probe requests whose last word never came: their players were in the room, and are counted from each
+    // request's last thirty-second report where there was one.
+    lostReports: lost, partialReports: finals.filter((f) => f.t === 'partial').length,
+    // --slow-every K: every Kth player takes six frames a second. `healthy` is everybody else: what the slow
+    // ones cost them is the difference from the same step without any.
+    slowPlayers: players.filter((p) => p.slow).length,
+    healthy: (() => {
+      const a = players.filter((p) => !p.slow), list = (key) => a.map((p) => p[key]).filter(Number.isFinite).sort((x, y) => x - y);
+      const hz = list('deliveredHz'), gap = list('maxStateGapMs');
+      return { players: a.length, deliveredHz: { min: hz[0] ?? null, p05: pick(hz, 0.05), median: pick(hz, 0.5) }, maxStateGapMs: { median: pick(gap, 0.5), max: gap.at(-1) ?? null } };
+    })(),
+    slowInputAckMs: (() => { const t = new Tally(); for (const f of finals) t.merge(f.slowAck); return t.json(); })(),
+    slow: (() => { const a = players.filter((p) => p.slow), hz = a.map((p) => p.deliveredHz).filter(Number.isFinite).sort((x, y) => x - y); return a.length ? { players: a.length, deliveredHz: { min: hz[0] ?? null, median: pick(hz, 0.5), max: hz.at(-1) ?? null } } : null; })(),
     inputLead: { ticksMedian: pick(leads, 0.5), ticksMax: leads.at(-1) ?? null, lateShare: sum('reports') ? Math.round(sum('late') / sum('reports') * 1000) / 1000 : null },
     driver: { requests: finals.length, failedRequests: failures.length, workerLoopP99Ms: [], peakTimerLagMs: finals.map((f) => f.worstTimerLagMs) },
     errors: [...errors].map(([text, count]) => ({ text, count })),
@@ -50,9 +98,17 @@ export function cloudReport({ origin, room, n, seconds, started, measureAt, endA
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   const opts = {};
   for (let i = 2; i < process.argv.length; i += 2) { if (!process.argv[i].startsWith('--') || process.argv[i + 1] === undefined) throw Error('Use --key value'); opts[process.argv[i].slice(2)] = process.argv[i + 1]; }
-  const probe = String(opts.probe ?? '').replace(/\/$/, ''), key = opts.key, origin = new URL(opts.url).origin, n = Number(opts.n ?? 50), seconds = Number(opts.seconds ?? 150);
-  const rampMs = Number(opts['ramp-ms'] ?? 50), game = opts.game ?? 'crowd-circuit', room = opts.room ?? `cloud-${n}-${Date.now().toString(36)}`, out = resolve(opts.out ?? `reports/crowd-circuit/${room}`);
-  if (!probe || !key || !Number.isInteger(n) || n < 1 || n > 1000 || !(seconds >= 1 && seconds <= 600)) throw Error('--probe, --key, --url, --n 1..1000, --seconds 1..600');
+  const probe = String(opts.probe ?? '').replace(/\/$/, ''), key = opts.key, origin = opts.url ? new URL(opts.url).origin : null, n = Number(opts.n ?? 50), seconds = Number(opts.seconds ?? 150);
+  const compress = opts.compress === 'on', rampMs = Number(opts['ramp-ms'] ?? 50), game = opts.game ?? 'crowd-circuit', room = opts.room ?? `cloud-${n}-${Date.now().toString(36)}`, out = resolve(opts.out ?? `reports/crowd-circuit/${room}`);
+  if (opts.calibrate) {
+    // `--calibrate <file>`: only the reference work, here and in the probe; no players.
+    const result = await calibrate({ probe, key });
+    await writeFile(resolve(opts.calibrate), JSON.stringify(result, null, 2));
+    console.log(JSON.stringify({ phase: 'calibrated', localMs: Math.min(...result.localMs), cloudMsARound: result.cloudMsARound, ratio: result.ratio, workerOwnClockMs: result.workerOwnClockMs }));
+    process.exit(0);
+  }
+  const slowEvery = Math.max(0, Math.floor(Number(opts['slow-every'] ?? 0)) || 0);
+  if (!probe || !key || !origin || !Number.isInteger(n) || n < 1 || n > 1000 || !(seconds >= 1 && seconds <= 600)) throw Error('--probe, --key, --url, --n 1..1000, --seconds 1..600');
   await mkdir(out, { recursive: true });
   const hello = await fetch(`${probe}/hello`, { headers: { 'x-probe-key': key }, signal: AbortSignal.timeout(15000) });
   if (!hello.ok) throw Error(`The probe did not answer (${hello.status}): is it deployed, and is the key its PROBE_KEY?`);
@@ -62,26 +118,28 @@ if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.ur
   // (fifteen seconds after the last has joined) and when to stop.
   const started = Date.now(), joinAt = started + 5000, measureAt = joinAt + n * rampMs + 15000, endAt = measureAt + seconds * 1000;
   console.log(JSON.stringify({ phase: 'start', generator: 'cloudflare', origin, room, n, seconds, requests: Math.ceil(n / 5), toolkit }));
-  const finals = [], failures = []; let lastNote = 0; const progress = new Map();
+  const finals = [], failures = []; let lastNote = 0, lost = 0; const progress = new Map();
   await Promise.all(Array.from({ length: Math.ceil(n / 5) }, async (_, r) => {
-    const from = r * 5, count = Math.min(5, n - from);
+    const from = r * 5, count = Math.min(5, n - from); let partial = null;
+    // Not all at once: a thousand players are two hundred requests.
+    await new Promise((done) => setTimeout(done, r * 10));
     try {
-      const res = await fetch(`${probe}/play?origin=${encodeURIComponent(origin)}&game=${encodeURIComponent(game)}&room=${encodeURIComponent(room)}&from=${from}&count=${count}&joinAt=${joinAt}&rampMs=${rampMs}&measureAt=${measureAt}&endAt=${endAt}`, { headers: { 'x-probe-key': key }, signal: AbortSignal.timeout(endAt - Date.now() + 60000) });
+      const res = await fetch(`${probe}/play?origin=${encodeURIComponent(origin)}&game=${encodeURIComponent(game)}&room=${encodeURIComponent(room)}&from=${from}&count=${count}&joinAt=${joinAt}&rampMs=${rampMs}&measureAt=${measureAt}&endAt=${endAt}${compress ? '&compress=1' : ''}${slowEvery ? `&slowEvery=${slowEvery}` : ''}`, { headers: { 'x-probe-key': key }, signal: AbortSignal.timeout(endAt - Date.now() + 30000) });
       if (!res.ok || !res.body) throw Error(`probe HTTP ${res.status}`);
-      let text = '', final = null;
+      let text = '', final = null; partial = null;
       for await (const chunk of res.body.pipeThrough(new TextDecoderStream())) {
         text += chunk;
         for (let at = text.indexOf('\n'); at >= 0; at = text.indexOf('\n')) {
           const row = JSON.parse(text.slice(0, at)); text = text.slice(at + 1);
-          if (row.t === 'final') final = row; else if (row.t === 'failed') throw Error(row.error); else if (row.t === 'sample') progress.set(from, row);
+          if (row.t === 'final') final = row; else if (row.t === 'partial') partial = row; else if (row.t === 'failed') throw Error(row.error); else if (row.t === 'sample') progress.set(from, row);
         }
         if (Date.now() - lastNote > 10000) { lastNote = Date.now(); const rows = [...progress.values()]; console.log(JSON.stringify({ phase: rows.some((x) => x.measuring) ? 'steady' : 'ramp', joined: rows.reduce((a, x) => a + x.joined, 0), open: rows.reduce((a, x) => a + x.open, 0) })); }
       }
       if (!final) throw Error('the probe ended without its report');
       finals.push(final);
-    } catch (error) { failures.push(`probe request ${from}: ${String(error?.message ?? error).slice(0, 160)}`); }
+    } catch (error) { failures.push(`probe request ${from}: ${String(error?.message ?? error).slice(0, 160)}`); if (partial) finals.push(partial); else lost += 1; }
   }));
-  const report = cloudReport({ origin, room, n, seconds, started, measureAt, endAt, finals, failures, toolkit });
+  const report = cloudReport({ origin, room, n, seconds, started, measureAt, endAt, finals, failures, toolkit, compress, lost });
   await writeFile(`${out}/report.json`, JSON.stringify(report, null, 2));
   console.log(JSON.stringify({ phase: 'done', out: `${out}/report.json`, joined: report.joined, connectedAtEnd: report.connectedAtEnd, ack: report.inputAckMs, loop: report.inputLoopMs, deliveredHz: report.deliveredHz, lead: report.inputLead, failedRequests: failures.length }));
   if (!finals.length) process.exitCode = 1;

package/lib/crowd-diagnostics.mjs

@@ -58,6 +58,7 @@ const result = await withKey(
           transport: f?.transport,
           gates: f?.gates,
           durability: f?.durability,
+          save: f?.save,
           diagnostics: f?.diagnostics,
           error: r.error
         }) + '\n'

package/lib/crowd-load.mjs

@@ -31,7 +31,8 @@ for (const k of Object.keys(opts))
       'churn',
       'churn-at',
       'compress',
-      'strict-chrome'
+      'strict-chrome',
+      'slow-every'
     ].includes(k)
   )
     throw Error('Unknown option --' + k);
@@ -127,7 +128,8 @@ function makeWorker(index) {
       room,
       index,
       workers: workerCount,
-      compress: opts.compress !== 'off'
+      compress: opts.compress !== 'off',
+      slowEvery: Number(opts['slow-every'] ?? 0)
     }
   });
   let sequence = 0;
@@ -474,7 +476,7 @@ try {
   );
   loop.disable();
   const histograms = {};
-  for (const key of ['first', 'welcome', 'ack', 'gaps', 'loops']) {
+  for (const key of ['first', 'welcome', 'ack', 'slowAck', 'gaps', 'loops']) {
     const h = new Histogram();
     for (const f of finals) h.merge(f.histograms[key]);
     histograms[key] = h.json();
@@ -518,6 +520,8 @@ try {
     firstStateMs: histograms.first,
     welcomeMs: histograms.welcome,
     inputAckMs: histograms.ack,
+    // With --slow-every: the slow players' own acknowledgements, kept out of everybody else's.
+    slowInputAckMs: histograms.slowAck,
     receiveGapMs: histograms.gaps,
     inputLoopMs: histograms.loops,
     ackSkipped: sum('ackSkipped'),
@@ -541,6 +545,14 @@ try {
       wireDownBytes: sum('wireDownBytes'),
       compressedSockets: sum('compressed')
     },
+    // --slow-every K: every Kth simulated player reads for one second in five (so every Gate holds some). `healthy` is everybody else: what the
+    // slow ones cost them is the difference from a run without any.
+    slowPlayers: players.filter((p) => p.slow).length,
+    healthy: (() => {
+      const a = players.filter((p) => !p.slow && !p.retired), of = (key) => a.map((p) => p[key]).filter(Number.isFinite).sort((x, y) => x - y);
+      const hz = of('deliveredHz'), gap = of('maxStateGapMs');
+      return { players: a.length, deliveredHz: { min: hz[0] ?? null, median: hz[Math.floor(hz.length / 2)] ?? null }, maxStateGapMs: { median: gap[Math.floor(gap.length / 2)] ?? null, max: gap.at(-1) ?? null } };
+    })(),
     // Samples in which a Chrome player was not a connected replica of this room.
     chromeTrouble,
     // Whether the server agreed to permessage-deflate on these sockets, as a

package/lib/crowd-probe/README.md

@@ -48,6 +48,64 @@ node node_modules/@homie-rocks/studio/lib/crowd-cloud.mjs \
 It opens one request to the probe for every five players, each held open for the step, adds up what they
 measured, and writes `report.json` in the shape `crowd-load.mjs` writes, so `crowd-summary.mjs` reads both.
 
+## Slow players among them
+
+`--slow-every 10` makes every tenth player a slow one: it takes what it is sent at six frames a second, in order,
+as a connection that carries no more does, and says which tick it holds. The report then has `healthy` (everybody
+else) beside `slow`: what a slow player costs the players on the same Gate is the difference from the same step
+without any. A Worker cannot slow a socket's reads, so this is a slow player and not a slow socket; for a socket
+that stops reading, `crowd-load.mjs --slow-every 10` from a computer pauses every tenth player's socket for four
+seconds in five.
+
+## How fast Cloudflare runs, against your computer
+
+```sh
+node node_modules/@homie-rocks/studio/lib/crowd-cloud.mjs \
+  --probe https://homie-crowd-probe.<account>.workers.dev --key $KEY --calibrate reports/calibration.json
+```
+
+A Worker's clock stands still while its code runs, so nothing timed on a computer says by itself what the same
+work costs on Cloudflare, and a Worker cannot time it either. This runs one fixed piece of work
+(`reference-work.mjs`) in the probe, ten rounds a request, with the stopwatch on your computer (a request that
+does the work less one that does none, the quickest of several), and the same work on your computer, and writes
+the ratio. `crowd-summary.mjs` prints it under a run's tables.
+
+## A whole trial
+
+`run-trial.sh` in this folder runs a plan of steps against a deployed studio: each from your computer and from
+inside Cloudflare, the in-Cloudflare steps three times each, one with slow players, the room's own figures beside
+every step, the calibration before and after, and one `summary.md`. It deploys nothing.
+
+```sh
+cd <your studio>
+URL=https://<studio> WORKER=<its worker's name> PROBE_URL=https://homie-crowd-probe.<account>.workers.dev PROBE_KEY=$KEY \
+  bash node_modules/@homie-rocks/studio/lib/crowd-probe/run-trial.sh
+```
+
+`PLAN=$'300 cloud 3\n600 cloud 3'` chooses the steps ("players mode runs"; the modes are in the script).
+
+## What a room carries, and how to read a trial
+
+One room's rules run in one object on one thread. With the crowd-circuit fixture (light rules, 20 ticks a second)
+that was 300 players with margin on Cloudflare, 600 at the edge, and 800 to 1,000 only by luck: the same step gave
+10 frames a second or 20, minutes apart. A game with heavier rules carries fewer.
+
+- Run the size you want and twice that size, three times each, at a busy hour. A size is carried when every run
+  is clean and twice the size is not falling apart. One clean run proves nothing: at its edge a room is clean or
+  not by what else its machine is doing.
+- Read **a Gate's round trip to the room** ("Gate rtt"), **the share of worlds over 200 ms old** and **"server
+  late"** (inputs that reached the rules after their tick). They are measured from outside the room.
+- Do not read the room's word about itself. On Cloudflare a Worker's clock stands still while its code runs and
+  reads a timer's due time when the timer fires, so a room that is seconds behind counts no late ticks. For the
+  same reason a probe that runs late reports rates that read high; the report's delivered frames a second are
+  counted against the room's ticks, not a clock.
+- Cloudflare's count of the room's processor time is not in a `wrangler tail` (it reads under 1% for a room that
+  is out of time). It is in the GraphQL analytics API (`durableObjectsPeriodicGroups`), which needs an API token
+  that may read account analytics.
+- `node packages/studio/test/crowd-room-cost.mjs` in the Homie repository says what a tick of the room costs on a
+  computer, divided into rules, input and worlds. With the calibration above it compares one game with another;
+  it does not predict where a room falls.
+
 ## Remove
 
 ```sh

package/lib/crowd-probe/client.mjs

@@ -90,6 +90,9 @@ export function crowdClient({ index, game, send, tallies, period = 50, lead = 3
       const span = c.lastAt > c.firstAt ? c.lastAt - c.firstAt : 0;
       return { i: index, seat: c.seat, firstStateMs: c.first, welcomeMs: c.welcomed, closed: c.closed, lead: c.lead, frames: c.frames, maxStateGapMs: c.maxGap,
         tickHz: span ? (c.lastTick - c.firstTick) * 1000 / span : null, deliveredHz: span ? (c.frames - 1) * 1000 / span : null,
+        // Frames received for each tick the room advanced: 1 is every frame. It needs no clock, which matters where
+        // the caller's clock is a Worker's (it reads a timer's due time, and runs slow when the Worker runs late).
+        framesPerTick: c.lastTick > c.firstTick ? (c.frames - 1) / (c.lastTick - c.firstTick) : null,
         downBytes: c.down, upBytes: c.up, inputs: c.inputs, reports: c.reports, late: c.late, undecodable: c.undecodable, ownMissing: c.ownMissing, errors: c.errors.slice(0, 8), fresh: c.at ? true : false };
     },
   };

package/lib/crowd-probe/reference-work.mjs

@@ -0,0 +1,45 @@
+/**
+ * A fixed piece of work, the same everywhere it runs: what a room's thread spends its time on, in miniature (parsing
+ * players' small messages, building and reading plain objects, arithmetic on floats, writing a block of text).
+ *
+ * A Worker cannot time a piece of its own work (its clock stands still while its code runs, and reads a timer's due
+ * time when the timer fires), so nothing measured on a laptop says by itself what a room costs on Cloudflare. This
+ * runs on both: the probe does it inside Cloudflare while `crowd-cloud.mjs --calibrate` holds the stopwatch on the
+ * request, and the same call is timed on the computer that asked. The ratio turns `test/crowd-room-cost.mjs`'s
+ * milliseconds into Cloudflare's.
+ *
+ * It returns a number that depends on every step, so no engine may skip the work, and the same number everywhere.
+ */
+export function referenceWork(rounds = 40) {
+  let check = 0, seed = 20261011;
+  const random = () => { seed = (Math.imul(seed, 1664525) + 1013904223) >>> 0; return seed / 4294967296; };
+  for (let round = 0; round < rounds; round += 1) {
+    // A tick's inputs: five hundred small messages parsed, held to numbers, queued by seat.
+    const queues = new Map();
+    for (let i = 0; i < 500; i += 1) {
+      const text = JSON.stringify({ t: 'in', e: 3914181188, k: 3000 + round, s: [[0, i % 2 ? 127 : -127, Math.round(random() * 70 - 35)]], r: i & 7, g: 2997 + round });
+      const m = JSON.parse(text), seat = i * 2;
+      const entry = { at: m.k >>> 0, values: { ax: Math.max(-127, Math.min(127, m.s[0][1] | 0)), ay: Math.max(-127, Math.min(127, m.s[0][2] | 0)) } };
+      let q = queues.get(seat); if (!q) { q = []; queues.set(seat, q); }
+      q.push(entry); check = (check + entry.values.ax + entry.values.ay + text.length) | 0;
+    }
+    // A tick of a thousand bodies: frozen vectors made and read, a little float arithmetic each.
+    const bodies = [];
+    for (let i = 0; i < 1000; i += 1) {
+      const q = queues.get(i), held = q ? q[q.length - 1].values : { ax: 0, ay: 0 };
+      const vel = Object.freeze({ x: Math.fround(held.ax / 127 * 6), y: Math.fround(held.ay / 127 * 6), z: 0 });
+      const pos = Object.freeze({ x: Math.fround(random() * 16 - 8 + vel.x * 0.05), y: Math.fround(random() * 120 - 60 + vel.y * 0.05), z: 0 });
+      const speed = Math.hypot(vel.x, vel.y);
+      bodies.push([`r${i}`, 0, round & 0xffff, [pos.x, pos.y], [vel.x, vel.y], [speed > 0 ? vel.x / speed : 1, speed > 0 ? vel.y / speed : 0], 0, [round, pos.x > 0], [], i, 0]);
+      check = (check + Math.round(pos.x * 100) + Math.round(pos.y * 100)) | 0;
+    }
+    // The world as it leaves: a block of numbers, and the room's checkpoint as text.
+    const block = new Float32Array(bodies.length * 6);
+    for (const [i, b] of bodies.entries()) block.set([b[3][0], b[3][1], b[4][0], b[4][1], b[5][0], b[5][1]], i * 6);
+    const bytes = new Uint8Array(block.buffer); let sum = 0;
+    for (let i = 0; i < bytes.length; i += 97) sum += bytes[i];
+    const text = JSON.stringify(bodies);
+    check = (check + sum + text.length + JSON.parse(text).length) | 0;
+  }
+  return check;
+}

package/lib/crowd-probe/run-trial.sh

@@ -0,0 +1,207 @@
+#!/usr/bin/env bash
+# A crowd trial of one game of a deployed studio, on your own Cloudflare account: each step from your computer and
+# from inside Cloudflare, the in-Cloudflare steps three times each (one run does not tell a limit from luck), a
+# step with slow players among healthy ones, the room's own figures a second beside every step, how fast Cloudflare
+# ran a fixed piece of work against this computer, and one summary.md at the end.
+#
+# It deploys nothing and changes nothing in the studio. It writes under reports/<game>/trial/<stamp>/ in the
+# studio's folder, creates temporary office keys for the diagnostics and revokes them.
+#
+#   cd <your studio>                       # deployed, with this toolkit installed
+#   (cd node_modules/@homie-rocks/studio/lib/crowd-probe && KEY=$(openssl rand -hex 24) && npx wrangler deploy --var PROBE_KEY:$KEY)
+#   URL=https://<studio> WORKER=<its worker's name> PROBE_URL=https://homie-crowd-probe.<account>.workers.dev PROBE_KEY=$KEY \
+#     bash node_modules/@homie-rocks/studio/lib/crowd-probe/run-trial.sh
+#   npx wrangler delete --name homie-crowd-probe      # when the trial is over
+#
+# Without PROBE_URL only the steps from this computer run. The players steer as the crowd-circuit fixture does:
+# for another game, change the input lib/crowd-probe/client.mjs and lib/crowd-worker.mjs send.
+#
+#   GAME=crowd-circuit                     the game's id
+#   PLAN=$'300 home\n600 cloud 3'          a different plan: "players mode [runs]" a line (modes below)
+#   LABEL=evening                          a word added to the report folder's name
+#   SECONDS_PER_STEP=150                   steady measurement per step
+#   EXPECTED_RUNTIME_SHA=<sha256>          stop unless the installed and the deployed toolkit are this build
+#   CHROME_PATH=/path/to/chrome            for the two real Chrome players in a step from this computer
+#
+# Read docs/crowd-transport-0462.md first for what each column can and cannot say. In short: nothing an object
+# measures about itself by its own clock is to be trusted on Cloudflare; a Gate's round trip to the room, the share
+# of worlds over 200 ms old and the players' own loop are the figures that show a room out of time.
+set -euo pipefail
+[ -d node_modules/@homie-rocks/studio ] || { echo 'Run this in a studio folder with @homie-rocks/studio installed.'; exit 1; }
+: "${URL:?URL=https://<your studio>}"
+: "${WORKER:?WORKER=<the name of the studio Worker, as in wrangler.jsonc>}"
+GAME="${GAME:-crowd-circuit}"
+export WRANGLER_SEND_METRICS=false
+# The probe inflates every frame, as a browser does; give zlib's pool room.
+export UV_THREADPOOL_SIZE=16
+TOOLKIT="$PWD/node_modules/@homie-rocks/studio"
+SECONDS_PER_STEP="${SECONDS_PER_STEP:-150}"
+PROBE_URL="${PROBE_URL:-}"
+PROBE_KEY="${PROBE_KEY:-}"
+STAMP=$(date -u +%Y%m%dT%H%M%SZ)
+OUT="$PWD/reports/$GAME/trial/$STAMP${LABEL:+-$LABEL}"
+mkdir -p "$OUT"
+
+# 1. The deployed Worker is this toolkit, byte for byte.
+node --input-type=module - "$URL" "$TOOLKIT" "$OUT" <<'JS'
+import { pathToFileURL } from 'node:url';
+import { writeFile } from 'node:fs/promises';
+const [url, toolkit, out] = process.argv.slice(2);
+const { STUDIO_BUILD } = await import(pathToFileURL(`${toolkit}/worker/build-id.mjs`));
+const expected = process.env.EXPECTED_RUNTIME_SHA;
+if (expected && STUDIO_BUILD.sha256 !== expected) throw Error(`Installed toolkit's runtime is ${STUDIO_BUILD.sha256}, not this build's ${expected}: install that build first`);
+const response = await fetch(`${url}/.well-known/homie-studio.json?verify=${Date.now()}`);
+if (!response.ok) throw Error(`manifest HTTP ${response.status}`);
+const manifest = await response.json();
+await writeFile(`${out}/deployment.json`, JSON.stringify(manifest, null, 2));
+if (manifest.toolkit?.sha256 !== STUDIO_BUILD.sha256 || manifest.toolkit?.version !== STUDIO_BUILD.version)
+  throw Error(`Wrong deployed toolkit: expected ${JSON.stringify(STUDIO_BUILD)}, got ${JSON.stringify(manifest.toolkit)}`);
+console.log('Verified deployed runtime', STUDIO_BUILD);
+JS
+
+# What this connection carries: twelve parallel downloads from Cloudflare for eight seconds, to nowhere.
+probe_link() {
+  local file="$1" tmp start end bytes pids=""
+  tmp=$(mktemp -d)
+  start=$(node -e 'console.log(Date.now())')
+  for i in 1 2 3 4 5 6 7 8 9 10 11 12; do
+    curl -s -o /dev/null -H 'Referer: https://speed.cloudflare.com/' -A 'Mozilla/5.0' --max-time 8 \
+      -w '%{size_download}\n' 'https://speed.cloudflare.com/__down?bytes=100000000' > "$tmp/$i" 2>/dev/null &
+    pids="$pids $!"
+  done
+  wait $pids
+  end=$(node -e 'console.log(Date.now())')
+  bytes=$(cat "$tmp"/* 2>/dev/null | awk '{s+=$1} END {print s+0}')
+  rm -rf "$tmp"
+  node -e '
+    const [file, bytes, start, end] = process.argv.slice(1);
+    const seconds = (end - start) / 1000, down = bytes > 0 && seconds > 0 ? bytes / seconds / 1e6 : null;
+    require("fs").writeFileSync(file, JSON.stringify({ at: new Date().toISOString(), streams: 12, seconds, bytes: Number(bytes), downMBps: down }, null, 2));
+    console.log("Link before this step:", down === null ? "not measured" : down.toFixed(2) + " MB/s (" + (down * 8).toFixed(0) + " Mbit/s)");
+  ' "$file" "$bytes" "$start" "$end"
+}
+
+TAIL_PID=
+DIAG_PID=
+cleanup() {
+  if [ -n "$DIAG_PID" ]; then kill -TERM "$DIAG_PID" 2>/dev/null || true; wait "$DIAG_PID" 2>/dev/null || true; fi
+  if [ -n "$TAIL_PID" ]; then kill -TERM "$TAIL_PID" 2>/dev/null || true; wait "$TAIL_PID" 2>/dev/null || true; fi
+  # Whatever finished is summarised, even when a step failed.
+  node "$TOOLKIT/lib/crowd-summary.mjs" "$OUT" || true
+  printf 'All reports: %s\nSummary: %s\n' "$OUT" "$OUT/summary.md"
+}
+trap cleanup EXIT
+trap 'exit 130' INT TERM
+
+# The tail is sampled by Cloudflare under load and is not the record; diagnostics.jsonl is.
+# Only failures are kept, so the sample is not spent on healthy requests.
+./node_modules/.bin/wrangler tail "$WORKER" --format json --status error > "$OUT/worker-tail.jsonl" 2> "$OUT/worker-tail.stderr" &
+TAIL_PID=$!
+sleep 3
+kill -0 "$TAIL_PID" 2>/dev/null || { printf 'Worker tail did not start (the run continues without it): %s\n' "$OUT/worker-tail.stderr"; TAIL_PID=; }
+# One step: the diagnostics collector beside a driver. $1 the step's folder, $2 the room, the rest the driver's command.
+run_step() {
+  local STEP="$1" ROOM="$2"; shift 2
+  mkdir -p "$STEP"
+  # The collector keeps a failed poll as a row and carries on; it is stopped when the step ends.
+  node "$TOOLKIT/lib/crowd-diagnostics.mjs" --root "$PWD" --url "$URL" \
+    --game "$GAME" --room "$ROOM" --seconds $((SECONDS_PER_STEP + 600)) --out "$STEP/diagnostics.jsonl" \
+    > "$STEP/diagnostics.log" 2>&1 &
+  DIAG_PID=$!
+  local READY=0 WAIT
+  for WAIT in $(seq 1 60); do
+    if [ -s "$STEP/diagnostics.jsonl" ]; then READY=1; break; fi
+    kill -0 "$DIAG_PID" 2>/dev/null || break
+    sleep 1
+  done
+  if [ "$READY" -ne 1 ]; then printf 'Diagnostics did not start for %s; the step runs without them:\n' "$ROOM"; cat "$STEP/diagnostics.log" || true; fi
+  local STATUS=0
+  "$@" > "$STEP.log" 2>&1 || STATUS=$?
+  printf '%s\n' "$STATUS" > "$STEP/driver-exit-code.txt"
+  kill -TERM "$DIAG_PID" 2>/dev/null || true
+  local DIAG_STATUS=0
+  wait "$DIAG_PID" 2>/dev/null || DIAG_STATUS=$?
+  printf '%s\n' "$DIAG_STATUS" > "$STEP/diagnostics-exit-code.txt"
+  DIAG_PID=
+  local ROWS FAILED
+  ROWS=$(wc -l < "$STEP/diagnostics.jsonl" 2>/dev/null | tr -d ' ' || echo 0)
+  FAILED=$(grep -c '"ok":false' "$STEP/diagnostics.jsonl" 2>/dev/null || true)
+  printf '%s finished (driver exit %s; diagnostics %s rows, %s failed polls): %s\n' "$ROOM" "$STATUS" "$ROWS" "${FAILED:-0}" "$STEP/report.json"
+  if [ -n "$TAIL_PID" ] && ! kill -0 "$TAIL_PID" 2>/dev/null; then
+    printf 'Worker tail stopped; inspect %s\n' "$OUT/worker-tail.stderr"; TAIL_PID=
+  fi
+  # A Gate gives its channel to the room back ten seconds after its last player leaves: the next step starts clean.
+  sleep 15
+}
+
+if [ -n "$PROBE_URL" ]; then
+  HELLO=$(curl -fsS -H "x-probe-key: $PROBE_KEY" "$PROBE_URL/hello" || true)
+  case "$HELLO" in
+    *'"probe":2'*) ;;
+    '') printf 'The probe at %s did not answer with that key; running from this computer only.\n' "$PROBE_URL"; PROBE_URL= ;;
+    *) printf 'The probe at %s is an older one (%s): deploy it again from the installed toolkit (lib/crowd-probe): it has the slow players and the calibration.\n' "$PROBE_URL" "$HELLO"; exit 1 ;;
+  esac
+fi
+
+# How fast Cloudflare runs a fixed piece of work against this computer: $1 the file. Eight probe requests.
+calibrate() {
+  [ -n "$PROBE_URL" ] || return 0
+  node "$TOOLKIT/lib/crowd-cloud.mjs" --probe "$PROBE_URL" --key "$PROBE_KEY" --calibrate "$1" || true
+}
+uptime > "$OUT/load-average-start.txt" || true
+calibrate "$OUT/calibration-start.json"
+
+# The plan: one step a line, "players mode [repeat]". Modes:
+#   home           this computer, compression on (what one home connection carries)
+#   home-slow      the same with every tenth player's socket not read for four seconds in five (a real slow socket)
+#   home-plain     this computer, compression off
+#   cloud          inside Cloudflare, compression off
+#   cloud-deflate  inside Cloudflare, compression on
+#   cloud-slow, cloud-deflate-slow   the same with every tenth player slow (it takes six frames a second)
+# The cloud steps run three times each: one run of each was not enough to tell a limit from luck.
+# From home: sizes one connection carries with room to spare. A thousand players on one connection measure the connection.
+PLAN="${PLAN:-300 home
+300 home-slow
+600 home
+800 cloud 3
+800 cloud-deflate 3
+900 cloud 3
+900 cloud-deflate 3
+1000 cloud 3
+1000 cloud-deflate 3
+1000 cloud-slow
+1000 cloud-deflate-slow}"
+printf '%s\n' "$PLAN" | while read -r N MODE REPEAT; do
+  [ -n "$N" ] || continue
+  for RUN in $(seq 1 "${REPEAT:-1}"); do
+    SUFFIX=""; [ "$RUN" -gt 1 ] && SUFFIX="-r$RUN"
+    case "$MODE" in
+      home|home-plain|home-slow)
+        STEP="$OUT/n$N"; COMPRESS=on; EXTRA=()
+        if [ "$MODE" = home-plain ]; then STEP="$OUT/n$N-home-plain"; COMPRESS=off; fi
+        if [ "$MODE" = home-slow ]; then STEP="$OUT/n$N-home-slow"; EXTRA=(--slow-every 10); fi
+        STEP="$STEP$SUFFIX"
+        mkdir -p "$STEP"
+        uptime > "$STEP/load-average.txt" || true
+        probe_link "$STEP/link.json" || true
+        # A full room is 998 simulated and two Chrome players.
+        SIZE=(--n "$N")
+        if [ "$N" -ge 999 ]; then SIZE=(--total 1000); fi
+        ROOM="h$(printf '%s' "$MODE" | cut -c6-7)$N-$RUN-$STAMP"
+        run_step "$STEP" "$ROOM" node "$TOOLKIT/lib/crowd-load.mjs" --url "$URL" "${SIZE[@]}" \
+          --workers 4 --seconds "$SECONDS_PER_STEP" --ramp-ms 50 --rss-mb 3072 --compress "$COMPRESS" ${EXTRA[@]+"${EXTRA[@]}"} --room "$ROOM" --out "$STEP" < /dev/null
+        ;;
+      cloud|cloud-deflate|cloud-slow|cloud-deflate-slow)
+        if [ -z "$PROBE_URL" ]; then continue; fi
+        STEP="$OUT/n$N-$MODE$SUFFIX"; COMPRESS=off; EXTRA=(); TAG=c
+        case "$MODE" in cloud-deflate*) COMPRESS=on; TAG=cd ;; esac
+        case "$MODE" in *-slow) EXTRA=(--slow-every 10); TAG="${TAG}s" ;; esac
+        ROOM="$TAG$N-$RUN-$STAMP"
+        run_step "$STEP" "$ROOM" node "$TOOLKIT/lib/crowd-cloud.mjs" --probe "$PROBE_URL" --key "$PROBE_KEY" \
+          --url "$URL" --n "$N" --seconds "$SECONDS_PER_STEP" --ramp-ms 50 --compress "$COMPRESS" --game "$GAME" ${EXTRA[@]+"${EXTRA[@]}"} --room "$ROOM" --out "$STEP" < /dev/null
+        ;;
+    esac
+  done
+done
+calibrate "$OUT/calibration-end.json"
+uptime > "$OUT/load-average-end.txt" || true