@homie-rocks/studio 0.46.3 → 0.46.6

package/CHANGELOG.md

@@ -17,6 +17,76 @@ 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**
+
+A page left open across a deploy is brought up to date with its game, and a check never opens the live site
+unless it is asked to.
+
+### Added
+
+- `room.bots: { keep, names: [...] }`: a rules game names its own bots, by seat. The roster, the results and
+  `world.label` all use it. Opt-in: without `names` the toolkit's own list is used, as before.
+
+- A predictor can judge its own shot as the server will: `ctx.judgedTick(aimTick)` (the tick the server will
+  pose the others at for this seat; the snapshot's control row now carries the seat's own rewind allowance in a
+  game that declares `room.historySeconds`), `ctx.ray/rays(..., { atTick })` and `room.poseAt(id, tick)` (the pose
+  at a tick from the snapshots the browser holds), and `ctx.math` (the rules' own `math`).
+
+### Fixed
+
+Each of these changes what happened before; none needs a change to a game.
+
+- A play page open during a deploy kept hosting the newer game inside the older page: only the frame was loaded
+  again. When the newer game needed something the old page did not have (a player ticket, for a game that had
+  just started keeping results with `room.records`), the player saw an empty history and finished rounds were not
+  recorded until they reloaded the page themselves. The page now says what it was made for, the Worker answers
+  the frame with a stand-in when a page made now would differ, and the page does one full reload to the same room
+  and seat. A page from before this handshake is sent to a fresh page, by the one way it has, only when the game
+  cannot keep its results inside it. A deploy that changes only a game's code or art still reloads the frame alone.
+- A finished round that had no player to be written for was dropped without a word. The log now says
+  `record-unsaved`, and the player is told on their screen that the round was not saved and to reload.
+- The player's own body was drawn sinking for the whole tick it landed in, and standing only at the tick's end
+  (up to 33 ms late at 20 ticks a second). It is drawn down to the ground by the moment it met it.
+- `homie-studio check` with no `--url` opened the studio's **live** site, and with no game the first game by name:
+  `npm run check` could seat two check browsers in a live public room of a game nobody was working on. With no
+  `--url` a check now runs against this studio's own build: its running dev server, or one it starts on a free
+  port and stops afterwards. With no game it covers the games this checkout changed (against the default branch,
+  committed or not), else every game. The live site is checked only when asked: `--live`, or its address in
+  `--url`. `port check` and `perf` follow the same rule (the running dev server, `--url`, or `--live`).
+
+### Upgrade notes
+
+- Nothing to do. A script that relied on `homie-studio check` reaching the live site says `--live` now.
+- The first deploy of this version reloads open play pages whole, once (their pages are older than it).
+- Version 0.46.5 is provisional. No deploy or merge is part of this PR.
+
 ## [0.46.3] - 2026-10-11
 
 **Plugin 0.46.3**

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/bin/homie-studio.mjs

@@ -785,6 +785,8 @@ function print(result) {
         `Written: ${result.file}`);
       break;
     case 'check':
+      if (result.results) { for (const r of result.results) lines.push(`${r.game}: PASS at ${r.site}: room ${r.room}, round ${r.round?.n} (${r.round?.humans} humans, ${r.round?.bots} bots), connection ${r.uninterrupted === true ? 'uninterrupted' : r.uninterrupted === false ? 'INTERRUPTED' : 'unknown'}`); break; }
+      if (result.site) lines.push(`Checked ${result.local ? 'this studio\'s own build' : 'the site'} at ${result.site}.`);
       lines.push(`PASS: two fresh browsers in room ${result.room} finished round ${result.round.n} (${result.round.humans} humans, ${result.round.bots} bots) in ${Math.round(result.totalMs / 1000)} s.`,
         ...result.seats.map((s) => `  ${s.browser}: seat ${s.seat} (${s.role}), seated in ${(s.seatedMs / 1000).toFixed(1)} s`),
         ...(result.frames ?? []).map((f) => `  ${f.browser} drew ${f.fps ?? '?'} fps${f.renderer ? ` on ${f.renderer}` : ''}`),
@@ -933,8 +935,9 @@ async function main() {
   if (cmd === 'port' && sub === 'import') return importPort(root, positional[2], flags.get('id'), { name: flags.get('name'), mode: flags.get('mode') });
   if (cmd === 'port' && sub === 'check') {
     const game = positional[2] ?? listGames(root)[0]?.id;
-    const url = flags.get('url') ?? siteUrl(root);
-    if (!url) return { ok: false, command: 'port check', why: 'give --url (the local dev address or the live site)' };
+    // Never the live site unless asked (--live, or its address): this studio's running dev server, else say so.
+    const url = flags.get('url') ?? (flags.has('live') ? siteUrl(root) : (await import('../lib/dev.mjs')).runningDev(root)?.url);
+    if (!url) return { ok: false, command: 'port check', why: 'give --url (the local dev address), start npm run dev, or say --live for the live site' };
     return tracked(root, 'checks', (report) => portCheck({ url, game, root, only: flags.get('only') ?? null, shots: flags.get('shots') ? resolve(flags.get('shots')) : null, log, report }), 'port check');
   }
   if (cmd === 'app' && sub === 'role') {
@@ -955,8 +958,8 @@ async function main() {
   if (cmd === 'lab') return labCommand(root, sub);
   if (cmd === 'perf') {
     const game = sub ?? listGames(root)[0]?.id;
-    const url = flags.get('url') ?? siteUrl(root);
-    if (!url) return { ok: false, command: 'perf', why: 'give --url (the local dev address or the live site)' };
+    const url = flags.get('url') ?? (flags.has('live') ? siteUrl(root) : (await import('../lib/dev.mjs')).runningDev(root)?.url);
+    if (!url) return { ok: false, command: 'perf', why: 'give --url (the local dev address), start npm run dev, or say --live for the live site' };
     const devices = String(flags.get('device') ?? 'computer,phone').split(',').map((d) => d.trim()).filter(Boolean);
     const num = (k, d, lo, hi) => Math.max(lo, Math.min(hi, Number(flags.get(k) ?? d) || d));
     return perfRun({ root, url, game, devices, runs: num('runs', 1, 1, 50), seconds: num('seconds', 15, 3, 300), warm: num('warm', 3, 0, 60), profile: flags.has('profile'), out: flags.get('out') ? resolve(String(flags.get('out'))) : null, maxLoad: num('max-load', 0.8, 0.05, 50), cpu: num('cpu', 4, 1, 20), pair: flags.get('pair') ? String(flags.get('pair')) : null, log });
@@ -973,14 +976,30 @@ async function main() {
   if (cmd === 'dev' && flags.has('stop')) return stopDev(root);
   if (cmd === 'dev') return dev(root, { lan: flags.has('lan'), port: flags.get('port') ?? 8787, remoteAi: flags.has('remote-ai'), localAi: !flags.has('no-local-ai'), timestamps: flags.has('timestamps'), log });
   if (cmd === 'check') {
-    const game = positional[1] ?? listGames(root)[0]?.id;
-    const url = flags.get('url') ?? siteUrl(root);
-    if (!url) return { ok: false, command: 'check', why: 'give --url (the local dev address or the live site)' };
+    // lib/check-site.mjs: with no --url a check runs against this studio's own build, never the live site (--live asks
+    // for that); with no game it covers the games this checkout changed.
+    const { checkSite, gamesToCheck } = await import('../lib/check-site.mjs');
+    const { games, why } = gamesToCheck(root, positional[1]);
+    if (!games.length) return { ok: false, command: 'check', why: 'this studio has no game to check' };
     // A big binary committed under games/ fails the check before any browser starts: it belongs in R2, never in git.
     const { bigCommittedFiles } = await import('../lib/asset-check.mjs');
-    const big = bigCommittedFiles(root).filter((f) => f.path.startsWith(`games/${game}/`));
-    if (big.length) return { ok: false, command: 'check', why: `committed files over 5 MB under games/${game}: ${big.map((f) => `${f.path} (${(f.bytes / 1024 / 1024).toFixed(1)} MB)`).join(', ')}. Big media goes to the studio's R2 (homie-studio storage add, then media move); raw models stay in art/<slug>/raw/ (git-ignored); a shipped model is made phone-sized with homie-studio assets optimise. Take it out of git (git rm --cached), then check again.` };
-    return tracked(root, 'checks', (report) => check({ url, game, shots: flags.get('shots') ? resolve(flags.get('shots')) : null, log, report }), 'check');
+    for (const game of games) {
+      const big = bigCommittedFiles(root).filter((f) => f.path.startsWith(`games/${game}/`));
+      if (big.length) return { ok: false, command: 'check', why: `committed files over 5 MB under games/${game}: ${big.map((f) => `${f.path} (${(f.bytes / 1024 / 1024).toFixed(1)} MB)`).join(', ')}. Big media goes to the studio's R2 (homie-studio storage add, then media move); raw models stay in art/<slug>/raw/ (git-ignored); a shipped model is made phone-sized with homie-studio assets optimise. Take it out of git (git rm --cached <file>) and check again.` };
+    }
+    const site = await checkSite(root, { url: flags.get('url') ?? null, live: flags.has('live'), log });
+    if (!site.ok) return { ok: false, command: 'check', why: site.why };
+    try {
+      if (!positional[1]) log(`check: ${games.join(', ')} (${why}) at ${site.url}`);
+      const results = [];
+      for (const game of games) {
+        const shots = flags.get('shots') ? resolve(flags.get('shots'), ...(games.length > 1 ? [game] : [])) : null;
+        const r = await tracked(root, 'checks', (report) => check({ url: site.url, game, shots, log, report }), 'check');
+        results.push({ ...r, game, site: site.url, local: site.local });
+        if (!r.ok) break;
+      }
+      return results.length === 1 ? results[0] : { ok: results.every((r) => r.ok), command: 'check', site: site.url, local: site.local, why: results.find((r) => !r.ok)?.why, results };
+    } finally { await site.stop(); }
   }
   if (cmd === 'shoot') {
     const game = positional[1] ?? listGames(root)[0]?.id;

package/guides/game/RULES.md

@@ -1078,6 +1078,23 @@ leaves: take the marker down quietly. `ctx.ray/rays/rayAll` query what the
 player sees (`ctx.viewTick`); `ctx.preview` says the run is between ticks. A
 predictor runs often: keep it cheap, and keep per-entity state in `me`.
 
+To guess a shot the server will judge with rewind, ask for what the server
+will use (0.46.5). `ctx.judgedTick(aimTick)` is the tick it will pose the others
+at: the `aimTick` the input carries, held to how far back this seat may look
+right now (the server says so in every snapshot) and to this tick. Pass it on:
+`ctx.ray(from, dir, max, { atTick: ctx.judgedTick(input.aimTick), ...filters })`
+poses the other bodies as the server will, from the snapshots this browser
+holds (between two of them, or carried on from the newest along its velocity).
+Inside the allowance that is the drawn target; past the game's cap it is a newer
+pose, and the predictor then shows no hit where the server will see none.
+`room.poseAt(id, tick)` gives `{pos, vel, known}` for the game's own tests
+(`known: false` is a guess past the newest snapshot). `ctx.math` is the rules'
+own `math`, and the context is accepted by guarded rules code as a world is for
+what the two share (`tick`, `dt`, `math`, `ray`, `rays`, `rayAll`, and a scene's
+`ray`, `rayAll`, `sweep`, `support`), so an aiming helper written for the rules
+can be called with `ctx` instead of being restated in the view. It has no
+`near`, `inBox`, `send` or `emit`: a helper that needs those is the server's.
+
 A tick's prediction runs more than once (between ticks, again when the input
 changes, then the tick itself) and shows each thing once. Things are told apart
 by their name and `key`: give two effects of one name that mean different things
@@ -1087,6 +1104,12 @@ before using it in a `match` closure: `me` is reused. A valued pulse
 (`f.pulse()`) carries the tick it was predicted on, and the server acts on it in
 that tick, so a predicted swap is in the snapshot of the tick it was drawn for.
 
+### Naming the bots (0.46.5)
+
+`room.bots: { keep: 4, names: ['Vex', 'Moth', 'Kilo'] }` gives the game's bots its own names, by seat (the list
+wraps). The roster, the round's results and `world.label(id)` all say the same name, and a restore keeps it.
+Without `names` the toolkit's own list is used. A name is 1 to 24 characters on one line.
+
 ### Discrete actions with a value
 
 Use `select: f.pulse()` for a weapon slot or other byte-valued action. Call

package/guides/game/SKILL.md

@@ -304,6 +304,8 @@ npm run build                                          # fix every error it name
 npx --no-install homie-studio build --types            # the same, with the TypeScript checked first: run it before a deploy
 npm run dev                                            # in the background: http://127.0.0.1:8787/<id>/play
 npx --no-install homie-studio check <id> --url http://127.0.0.1:8787 --shots ./.checks
+# With no --url the check runs against this studio's own build (its running dev server, or one it starts and
+# stops); with no <id>, on the games this checkout changed. The live site only with --live or its address.
 npx --no-install homie-studio shoot <id> --preview     # pictures of the built game on a stepped clock, no site needed (a 3D game where there is no GPU)
 npx --no-install homie-studio preview <id>             # only that game's built files at an address (alone, offline): for a capture script
 ```

package/lib/check-site.mjs

@@ -0,0 +1,85 @@
+/**
+ * WHERE A CHECK RUNS, AND ON WHICH GAMES, WHEN NOBODY SAYS (0.46.5).
+ *
+ * A check puts real browsers in a real room. With no `--url` it used to open the studio's LIVE site, and with no game
+ * the first game by name: `npm run check` in a studio working on one game sat two check browsers in a live public
+ * room of another. A check is a gate on what is in this folder, so:
+ *
+ *   where   `--url <site>` as given; else this studio's own dev server: the one already running (lib/dev.mjs keeps
+ *           its record), or one started for the check on a free port and stopped when the check ends. The live site
+ *           only when asked by name: `--live`, or its address in `--url`.
+ *   which   the game named; else every game this checkout changed (files under games/<id>/ that differ from the
+ *           default branch, committed or not); else, when nothing changed or this is not a git checkout, every game.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import { once } from 'node:events';
+import { createServer } from 'node:net';
+import { fileURLToPath } from 'node:url';
+import { runningDev } from './dev.mjs';
+import { listGames, siteUrl } from './studio.mjs';
+
+const CLI = fileURLToPath(new URL('../bin/homie-studio.mjs', import.meta.url));
+
+async function freePort() {
+  const s = createServer(); s.listen(0, '127.0.0.1'); await once(s, 'listening');
+  const port = s.address().port; await new Promise((r) => s.close(r)); return port;
+}
+
+/**
+ * The site a check opens: { ok, url, local, live, started, stop() }. `stop` ends only a server this call started.
+ * `spawnFn` and `fetchFn` are for tests.
+ */
+export async function checkSite(root, { url = null, live = false, log = () => {}, spawnFn = spawn, fetchFn = globalThis.fetch, waitMs = 240_000 } = {}) {
+  const none = async () => {};
+  if (url) return { ok: true, url: String(url), local: /^https?:\/\/(?:127\.0\.0\.1|localhost|\[::1\])(?::|\/|$)/.test(String(url)), live: false, started: false, stop: none };
+  if (live) {
+    const site = siteUrl(root);
+    return site ? { ok: true, url: site, local: false, live: true, started: false, stop: none } : { ok: false, why: 'this studio has no live site yet (deploy it first), so there is nothing for --live to check' };
+  }
+  const running = runningDev(root);
+  if (running) return { ok: true, url: running.url, local: true, live: false, started: false, stop: none };
+  const port = await freePort(), origin = `http://127.0.0.1:${port}`;
+  log(`check: no --url, so this studio's own build is checked: starting its dev server on ${origin} (stopped when the check ends; --live checks the live site)`);
+  const child = spawnFn(process.execPath, [CLI, 'dev', '--port', String(port), '--no-local-ai'], { cwd: root, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+  let tail = '';
+  for (const stream of [child.stdout, child.stderr]) stream?.on('data', (chunk) => { tail = (tail + chunk).slice(-4000); });
+  const stop = async () => {
+    if (child.exitCode !== null || child.signalCode !== null) return;
+    const ended = once(child, 'exit');
+    try { process.kill(-child.pid, 'SIGTERM'); } catch { try { child.kill('SIGTERM'); } catch { /* gone */ } }
+    const force = setTimeout(() => { try { process.kill(-child.pid, 'SIGKILL'); } catch { /* gone */ } }, 8000);
+    try { await ended; } finally { clearTimeout(force); }
+  };
+  const deadline = Date.now() + waitMs;
+  while (Date.now() < deadline && child.exitCode === null && child.signalCode === null) {
+    const up = await fetchFn(`${origin}/games.json`, { signal: AbortSignal.timeout(1500) }).then((r) => r.ok).catch(() => false);
+    if (up) return { ok: true, url: origin, local: true, live: false, started: true, stop };
+    await new Promise((r) => setTimeout(r, 400));
+  }
+  await stop();
+  return { ok: false, why: `this studio's dev server did not start for the check${tail ? `:\n${tail.trim().split('\n').slice(-12).join('\n')}` : ''}\nStart it yourself (npm run dev) and give its address with --url, or fix the build.` };
+}
+
+/** The ids of the games this checkout changed against its default branch (committed or not), in the studio's order; [] when it cannot be told. */
+export function changedGames(root, { run = spawnSync } = {}) {
+  const git = (...args) => { const r = run('git', args, { cwd: root, encoding: 'utf8' }); return r.status === 0 ? String(r.stdout) : null; };
+  if (git('rev-parse', '--is-inside-work-tree') === null) return [];
+  const files = new Set((git('status', '--porcelain', '--', 'games') ?? '').split('\n').map((l) => l.slice(3).replace(/^"|"$/g, '').split(' -> ').pop()).filter(Boolean));
+  const head = (git('symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD') ?? '').trim();
+  for (const base of [head, 'origin/main', 'main', 'origin/master', 'master'].filter(Boolean)) {
+    const fork = (git('merge-base', 'HEAD', base) ?? '').trim();
+    if (!fork) continue;
+    for (const f of (git('diff', '--name-only', `${fork}..HEAD`, '--', 'games') ?? '').split('\n')) if (f) files.add(f);
+    break;
+  }
+  const touched = new Set([...files].map((f) => /^games\/([^/]+)\//.exec(f)?.[1]).filter(Boolean));
+  return listGames(root).map((g) => g.id).filter((id) => touched.has(id));
+}
+
+/** The games a check covers: the one named, else what changed, else all of them. */
+export function gamesToCheck(root, named, options) {
+  if (named) return { games: [named], why: 'named' };
+  const changed = changedGames(root, options);
+  if (changed.length) return { games: changed, why: 'changed in this checkout' };
+  return { games: listGames(root).map((g) => g.id), why: 'nothing changed against the default branch: every game' };
+}

package/lib/check.mjs

@@ -1,5 +1,6 @@
 /**
- * `homie-studio check <game> --url <site>` — the promise, measured: two fresh
+ * `homie-studio check [<game>] [--url <site> | --live]` — the promise, measured (where it runs and on which games
+ * when nobody says: lib/check-site.mjs; never the live site unless asked): two fresh
  * browsers (separate Chrome processes and profiles, one a computer and one a
  * phone) press Play, land in the SAME public room, play, and both see the round
  * finish. Exit 0 only when all of that happened. Uses this Mac's Chrome through

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 };
     },
   };