@homie-rocks/studio 0.46.5 → 0.47.0

package/CHANGELOG.md

@@ -17,6 +17,74 @@ 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.47.0] - 2026-10-13
+
+**Plugin 0.47.0** · Wrapped worlds and generated collision maps.
+
+Games can wrap across map edges and replace seeded tile levels during play, with the same collision geometry in server rules and prediction.
+
+### Added
+
+- Maps may opt into wrapping independently on x, y and z with `wrap: {x:true}`;
+  periods come from bounds. Bodies, sweeps, rays, overlaps, support, near/box queries,
+  area events, ranged effects, spatial delivery, rewind and view interpolation use
+  periodic geometry. Crossing an edge wraps rather than clamps. Sweeps/rays retain
+  their supplied direction and pay for each periodic image they visit.
+- Room handlers can call `world.map.replace(data)`. A replacement is validated,
+  indexed and activated atomically at the next tick, preserving bounds and wrapping.
+  Compact current/pending revisions are saved and sent once per collision revision;
+  local prediction replays the same compiled map by activation tick.
+- Maps accept row-major `tiles` with width, height, size, optional origin and solid
+  height. Nonzero cells compile to indexed horizontal runs. Rules and movement can
+  query `map.tile(x,y)`; views read `room.map.tiles`.
+- Named multi-source cardinal `tiles.flows` bake during map compilation. Rules and
+  movement use constant-work `map.distance(name,x,y)` and `map.flow(name,x,y)`.
+  The standalone rules runtime ships the nav package's new `Flow.js` baker, checked
+  against its source in the release gate. Generation, copying, indexing and baking
+  are charged to the rules handler; ordinary static-map budget charges are unchanged.
+- Seeded virtual-time release cases cover two-view seam crossing in 2D/3D and
+  generated-map collision, mid-round regeneration and restore, including 300 ms
+  delay and 12% loss. Geometry and navigation tests cover periodic casts,
+  multi-period movement, atomic failure and independently checked shortest paths.
+  Eight-player generation/restore replays also match every save and snapshot
+  across Node, Chrome and workerd for 240 seeded ticks.
+
+### Fixed
+
+- Handlers reached synchronously by `world.dispatch` now report their coverage to
+  the build checker, including failures, without opening a second handler budget.
+- The rewrite guide specifies named helper re-exports (`export *` is refused), and
+  the rules guide explains that mandatory spawn fields precede deferred `arrive`.
+
+This release covers wrapped worlds and generated levels. Arbitrary triangle-mesh
+collision, the measured Rapier-versus-kernel decision, first-class integration
+substeps, and the assisted rewrite command remain follow-up work.
+
+## [0.46.6] - 2026-10-11
+
+**Plugin 0.46.6** · Big rooms: what one room carries, measured. · [release-2026-10-11-studio-0.46.6](https://github.com/homie-rocks/homie/releases/tag/release-2026-10-11-studio-0.46.6)
+
+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/guides/game/REWRITE.md

@@ -17,7 +17,8 @@ Read RULES.md before starting.
    An old file named rules.ts may already export pure helpers that tests import.
    Preserve that public test API and every existing test file byte-for-byte,
    including imports. Re-export the old helpers from rules.ts if extracted into
-   another module; do not redirect tests to that module. Record test-file hashes
+   another module with named exports (`export { helper } from './helper'`);
+   `export *` is refused. Do not redirect tests to that module. Record test-file hashes
    before editing and compare them at the end. The filename alone does not
    mean it is a rules-plus-view game. If tests now load toolkit TypeScript under
    Node, use a narrowly scoped TypeScript loader and keep the normal test command

package/guides/game/RULES.md

@@ -1178,3 +1178,70 @@ still snap to authority. Opt in only after measuring stop/reversal and delayed
 collision behavior for the game's mover.
 
 For multi-cast movement or scratch trajectory checks, `ctx.world.sweep(body, delta, {ground:false})` (also captured-scene `sweep`) moves and returns the same collision but leaves `body.grounded` unchanged. Use it only when your mover computes support explicitly. Omitting the option retains the existing support query and grounding behavior. This avoids paying for identical support checks after horizontal and upward probes.
+
+
+## Wrapped worlds and generated levels (0.47.0)
+
+Declare wrapping in the map, independently per axis. The period is the bounds'
+extent; an omitted axis keeps its existing bounded behaviour:
+
+```json
+{"bounds":{"min":[0,0,0],"max":[25,25,10]},"wrap":{"x":true}}
+```
+
+Bodies and hit positions use canonical coordinates in `[min,max)`. Sweeps and rays
+follow the supplied displacement through periodic copies of the geometry; they can
+cross more than one period and pay for each visited image. Near/box queries, area
+events, effect ranges, spatial delivery, rewind and drawing interpolation use the
+short way around. Exactly half a period chooses the negative direction. A renderer
+can read `room.map.wrap.x` (the pair `[min,max]`) to draw copies at the viewport's
+edges. The server does not duplicate entities. In a maze with one tunnel, keep
+solid border cells on every other row; wrapping itself is per axis, not per row.
+
+For a generated maze, replace the room's current map in `room.start` or a room
+handler. Build its data using the rules' seeded random source, then publish once:
+
+```ts
+world.map.replace({
+  bounds: { min: [0, 0], max: [25, 25] },
+  wrap: { x: true },
+  tiles: { width: 25, height: 25, size: 1, data: cells,
+    flows: { exit: [312] } },
+  spots: { start: [[12.5, 19.5]] },
+});
+```
+
+`replace` preserves the original bounds and wrapping. It validates, bakes cardinal
+navigation fields and compiles the spatial index before publishing anything. A
+failed bake leaves the previous revision intact. The last successful replacement
+in a tick becomes current at the next tick; all bodies use the same revision.
+The compact map data and activation tick travel with collision revisions and saves,
+including both current and pending maps. Prediction replays against that tick's
+compiled geometry. Late knowledge is corrected by the normal reconciliation path.
+
+Tiles are row-major integers: zero is open, nonzero is solid. `at` defaults to
+`[0,0,0]`, `size` and `solidHeight` to 1. Horizontal runs become indexed boxes,
+including in 3D. On a wrapped axis the grid must span the full map. Authored boxes,
+round shapes, terrain and spots can be included in the same replacement. The view
+reads `room.map.tiles`; rules and movement read `world.map.tile(x,y)` and
+`ctx.map.tile(x,y)`. Cell coordinates are integers, not metres. Outside an unwrapped
+grid is solid. A custom tile mover may read these cells instead of using sweeps.
+
+`flows` names lists of open destination cell indices. `map.distance(name,x,y)` gives
+cardinal hops to the nearest destination, or -1 when unreachable/unknown;
+`map.flow(name,x,y)` gives the next unit direction, zero at a destination, or
+undefined when unreachable/unknown. Each lookup is constant work (4 or 8 budget
+units). Baking uses `@homie-rocks/nav`'s shared cardinal flow implementation;
+left/up/right/down resolves ties, including tunnels. Change destinations by
+publishing new flow declarations with the map. This is a bake, not an unmetered
+path search: budget for every field and regenerate only when its goals change.
+
+Room replacement charges copying, grid scanning, index construction and each flow
+bake to the calling handler. Snapshots charge for the compact data. Existing static
+maps need no replacement and retain their previous budget charges. A few thousand
+cells regenerated a few times a round belong in one map revision; live collider
+entities remain suitable for independently moving doors, cover and platforms.
+
+`spawn` exposes a new entity before its deferred `on.arrive` handler. Pass every
+field that must be valid immediately in the spawn data; use `arrive` for subsequent
+work, not for mandatory initialization.

package/guides/game/SKILL.md

@@ -75,6 +75,12 @@ Cloudflare or physical-phone capacity guarantees.
 
 ## Write and change rules plus view
 
+For wrapping worlds or generated levels, use the map's opt-in `wrap` and room-scoped
+`world.map.replace` APIs described in RULES.md's **Wrapped worlds and generated levels**.
+Prefer one indexed map revision for a generated maze; keep independently moving
+doors and platforms as live colliders. Generation and navigation baking spend the
+room handler's budget.
+
 **Read [RULES.md](RULES.md) before writing code.** All five starters use this contract.
 Work in few, large edits: read each source file once, decide its changes, then
 make every change it needs in ONE file_edit with an edits list. Build after each

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