@homie-rocks/studio 0.46.0 → 0.46.2

package/CHANGELOG.md

@@ -17,6 +17,50 @@ 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.2] - 2026-10-11
+
+**Plugin 0.46.2** · Big rooms: the room runs the rules, its Gates do the rest.
+
+A room of hundreds has a new shape, a deploy the owner asked for is approved by the asking, and Homie paces no input of a server-hosted game.
+
+Measured on Cloudflare with a game where every player sees about 180 others: 300 players at 20 frames a second from a home connection; 600 at 20 frames a second measured from inside Cloudflare, marginal from one home connection carrying all 600; 1,000 are admitted and the room keeps its ticks, but delivery is not there yet. On the same game 0.45.0 delivered 13 frames a second at 300 and lost every player at 1,000.
+
+### Added
+
+- `room.rates` in game.json: a studio's own pace on what one player may send, in messages a second by kind (`{ "in": 60 }`). Leave it out and there is none.
+- `lib/crowd-probe/`: a Worker of its own that plays simulated players against a studio from inside Cloudflare, five a request, and `lib/crowd-cloud.mjs`, which adds the requests up into the report the home driver writes. A trial's tool: no studio's Worker imports it.
+- Each Gate measures the room's clock against its own, the room's ticks a second by its own clock, and the longest it went without a world. The room's own count of its ticks cannot see the room run late.
+- A big room's diagnostics come from an object that is neither the room nor a Gate with players. The room and each Gate post a second's facts to it (ticks a second, how long a player's input took to reach the rules, frames written to each player, how old the world was when a Gate sent it, how far behind players say they are), and `/_studio/api/room` answers from that copy with its age. Measuring a room costs it nothing, and a room too busy to answer still has its last word read.
+- A player's client says which tick it holds (`g` on its inputs and pings). A Gate that finds a player more than a second behind sends that player fewer, fresher frames, down to one a second, and restores the rate when they have caught up. Each frame is a change from the last one sent and carries the player's own body. A client that says nothing is sent every tick, as before.
+
+### Changed
+
+- In a room behind Gates the room object runs the rules and hands each Gate one world a tick. The Gate chooses what each of its players can see, encodes it and writes it. The room no longer selects, encodes or queues anything per player on its tick.
+- A Gate holds fifty players and Gates fill in order: the room tells the door which Gate has room, so fifty players in a 1,000-seat game are one Gate and a full room is twenty. A studio sets its room's size and nothing else. A room of 64 or fewer is still its Table alone.
+- The world crosses from the room to a Gate as one block of numbers, the same block for every Gate, plus whatever else about a body changed since that Gate last heard: about 33 KB a tick for 1,000 players where the JSON was 150 KB, and almost nothing for the Gate to parse.
+- A body that keeps its course is not sent again. A client built with 0.46.2 moves it along its last velocity, and a Gate sends it only when that has drifted past the game's `view.precisionM` (near bodies) or half the distance it covers between `view.farHz` refreshes (far ones). On the crowd-circuit game at 1,000 players a frame falls from 71 rows to 20, a player from 14.8 KB a second on the wire to 6.3, and a far body is drawn 3 cm from the truth on average where it was 35 cm. A game page built before 0.46.2 is sent every moving body, as before.
+- A Gate works out once for each world what does not depend on the player. Encoding a player's frame takes under a third of the time.
+- Each Gate has its own channel to the room. The relay between them (the Concentrator) is gone: it re-read and re-sent every world for eight Gates and was the first object to fall behind. A studio's `CONCENTRATOR` binding stays declared and unused, so an upgrade needs no migration.
+- A Gate sends the room what its players sent at once when the channel is quiet and never more than one frame in 50 ms, however many players it holds. Receipts ride that frame.
+- Far-view refreshes are spread across players, so a room's largest updates do not all leave on the same tick.
+- A deploy requested in the owner's prompt is approved for that task, including retries. Unrequested deployments remain held; explicit refusals revoke the task approval.
+- The crowd probe offers WebSocket compression, as every browser does, coasts, names the tick it holds, follows the room's word on how early its inputs arrive (as the toolkit's client does), and reports whether the server agreed to compress, what that saved, and the kilobytes a second a player cost.
+
+### Fixed
+
+- Homie no longer paces what a player sends a game whose rules run on the server. 0.45.3 dropped honest input at 60 a second when a slow network delivered a batch late. What players say to each other keeps its pace, and so does every room a player's own browser hosts.
+- A game with fields only their owner may see keeps each player's view in the room when the room is behind Gates. A Gate was handed the whole state.
+- Late callbacks that catch up at the requested tick rate no longer end a healthy room as an overrun; sustained slow ticks still stop.
+- Relay failures log their layer, close cause and queue counters. A link's receipt latency measures the link, not the cadence a receipt waited for. Frozen Cloudflare clocks are not reported as zero execution time.
+- Deployment summaries no longer assume Workers Free. A big room's estimate counts its Gates and its diagnostics object and says which request traffic it leaves out.
+
+### Upgrade notes
+
+- Rebuild and deploy a studio to get the new room shape; a game needs no change. A game page built before 0.46.2 still plays in a big room: it is sent every tick and every moving body, because it says neither which tick it holds nor that it coasts.
+- A room of 64 seats or fewer, and every room a player's browser hosts, is as it was: none of this is on its path. The one change that reaches a small server-hosted room is that Homie no longer paces what a player sends it.
+- To measure your own game on your own Cloudflare account: `lib/crowd-load.mjs` plays a crowd from your computer and `lib/crowd-probe/` from inside Cloudflare. `lib/crowd-probe/README.md` has the commands and how to delete the probe afterwards.
+- What four trials on Cloudflare measured, what is proven and what is not, is in `docs/crowd-transport-0462.md`.
+
 ## [0.46.0] - 2026-10-10
 
 **Plugin 0.46.0**

package/README.md

@@ -206,8 +206,9 @@ game its studio chooses to share, each with its own licence ("Game parts", below
 
 `players.max` in game.json is the room's chosen positive integer capacity; omitted means 8.
 There is no 32-player ceiling or default per-address admission limit. Public games use
-rules plus view with `room.host: "server"`. Gates carry the browser connections and
-concentrators combine Gate links for larger rooms. Server rules survive browser departures.
+rules plus view with `room.host: "server"`. Gates carry the browser connections, each on
+its own channel to the room: the room runs the rules and hands every Gate one world a tick;
+the Gate selects, encodes and paces each player's view. Server rules survive browser departures.
 New browser/offline games use the same rules contract. Existing netplay games and their
 port host helpers remain supported for upgrades, with their original 32-seat limit.
 For larger rooms, follow `guides/game/REWRITE.md`.

package/docs/rooms-milestone-2-notes.md

@@ -0,0 +1,345 @@
+# Rooms milestone 2: releasable slices
+
+The opening sections preserve the released slice-1 record. The 0.45.0 slice-2
+implementation, local measurements and remaining work follow below.
+
+0.44.0 is slice 1, **spatial state delivery**. It is useful independently in an
+existing server-hosted room: the studio chooses `room.view.radiusM` in game.json,
+and a player's view receives nearby entities and its own body. Unchanged state
+is compressed as deltas. No change to rules or movement is needed. `room.each`,
+`enter` and `leave` describe the visible set, so a view must dispose of departed
+meshes and recreate returning ones. Leaving view does not mean despawning.
+
+This first PR does not claim that the public join/build path admits hundreds.
+That path retains milestone 1's 32-seat restriction until slice 2 supplies Gates
+and removes it. The simulation and relay now handle a 300-seat test directly,
+without a simulation seat clamp or truncated rosters/control rows. This is the
+foundation for the next slice, not a substitute for its admission and transport
+proof. No deployment or merge was made.
+
+## What ships first
+
+- `room.view.radiusM`: a studio-selected radius in metres, including z in 3D.
+  Omitted or null means the whole room, with the existing small-room path and
+  no extra per-client encoding. Zero means only colocated entities. No default
+  radius, downstream budget, spend limit, or crowd admission policy is imposed.
+- The real relay filters both ongoing snapshots and join/rejoin welcome state.
+  A player with no body yet sees no entities. Watchers retain the whole-room
+  overview in this slice; following a camera does not restrict their feed.
+- Each connection retains one keyframe. Deltas carry changed entity components,
+  new entities and explicit removals, against that keyframe. They carry the
+  current round and only the receiving player's input acknowledgment/control row.
+- A keyframe at least once per simulation second, and a fresh one at every
+  connection or epoch change. Backpressure skips snapshots without advancing the
+  encoder. A missing intermediate delta cannot corrupt later updates. A lost
+  keyframe causes deltas to be ignored until the next keyframe, at most one
+  simulation second later. WebSocket itself is ordered and reliable.
+- Saving and host recovery still use complete authoritative state. Filtering
+  never changes simulation, collision, queries, scoreboards or shared state.
+- Seeded, virtual-time correctness in `npm test`; the long 300-client run is in
+  `test:rules:extended`. The pre-existing 12-scenario real-time traffic matrix and
+  27 handover repetitions move there too, with all assertions retained. The gate
+  keeps two actual-browser cases (tab hiding and socket closing); virtual time
+  covers the rate/seed/handover matrix. No wall-clock throughput threshold is a
+  release gate.
+
+Interest is a bandwidth feature, **not hidden information**. Shared state,
+effects, roster and watcher overview are still public. Private fields and tells
+arrive together in slice 3. Browser hosting continues to send complete state;
+requesting a radius there produces a build diagnostic. The existing starters
+need no contract rewrite for slice 1 and keep their whole-room views.
+
+## Design decisions and departures
+
+The roadmap's sections 5, 6, 7, 10 and 23 are the starting point. Milestone 1
+already separates the host, core, transport-free relay and view. We reuse those
+roles instead of first splitting Table into new abstractions or declaring empty
+Durable Object classes. Gate and concentrator classes arrive together in slice 2,
+when they can actually carry connections and their deploy can be tested.
+
+Interest/deltas precede Gates: doing this work in the existing relay gives a
+shippable feature and a measurable role to move. The codec is independent of
+Cloudflare and does not introduce a second runtime or contract profile. A small
+game continues to see the match contract without `uses` or `profile` boilerplate.
+
+Deltas name periodic keyframes rather than retaining an acknowledged history
+per player. One baseline bounds memory, intermediates may be skipped safely, and
+reconnect always starts fresh. This trades retransmitted changes and up to one
+simulation second of recovery after a lost keyframe for a much smaller protocol.
+It is not the roadmap's final bandwidth scheduler; near/far tiers, priorities,
+short IDs, watcher follow feeds and shared far encodings remain slice 3 work.
+
+The roadmap's default 96-metre visibility radius, default crowd cap from S6,
+per-client bandwidth budget and guest-address cap are not defaults we will
+adopt. They contradict the owner's no-imposed-limits rule. Studios may choose
+limits explicitly. Cloudflare limits and measured capacity are reported as
+information, never turned into a Homie admission ceiling.
+
+## Local proof
+
+The workload uses the checked and guarded rules loader, real host runtime and
+NetRoom relay, with 300 simulated WebSocket clients, one actual player body per
+seat, 20 Hz seeded inputs, a 20-by-15 grid at four-metre spacing and a chosen
+12-metre radius. Each player moves at up to 2 m/s and increments a field each
+tick. All 300 input acknowledgments, own bodies and roster entries are checked;
+there are no rules errors or cut ticks. The fixture explicitly chooses a
+5,000,000-unit tick budget; this is not a new default or a general game capacity
+claim. Warmup is 20 ticks. Clients keep one baseline and latest state, not a log
+of every received frame.
+
+Measurement includes input dispatch, rules, encoding, serialization and all 300
+clients parsing and decoding in the same Node process. Memory is peak sampled
+whole-process heap/RSS, including the harness and rules loader, not isolated
+server memory. Bytes count all downstream frames during the measurement window,
+including snapshot JSON and pings; WebSocket/TLS framing is not included. These
+are **local numbers, not Cloudflare measurements**, not Internet latency, and
+not a rendering or physical-phone capacity result.
+
+Measurement command:
+
+```sh
+node --input-type=module -e 'import {interestWorkload} from "./packages/studio/test/rules-interest-workload.mjs"; console.log(JSON.stringify(await interestWorkload({ticks:1200,measure:true}),null,2))'
+```
+
+Observed on macOS arm64, Node 22.23.3, 1,200 measured ticks (60 seconds of
+virtual play), plus 20 warmup ticks. Other local verification was running; CPU
+timings are observations, not a throughput guarantee.
+
+| Measurement | Local result |
+| --- | ---: |
+| Clients / tick rate | 300 / 20 Hz |
+| Peak visible bodies for one client | 33 |
+| Tick including relay and all client decoding, p50 / p95 / p99 | 14.88 / 21.04 / 25.41 ms |
+| Largest measured tick | 31.98 ms |
+| Downstream per player, mean / highest | 23,171 / 29,117 bytes/s |
+| Peak sampled whole-process heap / RSS | 133,426,952 / 238,764,032 bytes |
+
+This does **not** meet the roadmap's eventual 16 KB/s target. Tiers, priority and
+shared encodings in slice 3 have work to do; no target was weakened or represented
+as passed. All 300 clients are simulated, not 300 browser tabs or Cloudflare
+connections.
+
+## Release verification
+
+- Focused codec, relay and rules tests: 20 passed, no skips.
+- Real view client on virtual time: 189 passed, including the new spatial
+  delivery/lost-keyframe/reconnect case. Existing Chrome rendering smoke tests
+  run in the root gate; this slice adds no rendering-specific browser case.
+- Plugin: 123 passed, one optional live-URL fixture skipped.
+- Plugin validation, packed Desktop server and release preflight passed;
+  preflight lists studio 0.44.0 as the sole new npm version.
+- Template and history generation, changelog sync/check completed.
+- Root `npm test` runs with `CHROME_PATH` pointing to local Chrome. Final root
+  results and all six CI checks are tracked on [PR #83](https://github.com/homie-rocks/homie/pull/83).
+- A same-role reconnect now delivers its welcome snapshot to the rules view,
+  even though no role-change event fires. The regression blocks later periodic
+  keyframes and verifies that welcome-based deltas advance the view immediately.
+
+## Remaining slices, in order
+
+Each is a separate releasable commit series/PR after its predecessor is released.
+Slices 1 and 2 are implemented. Slice 1 shipped in 0.44.0; this PR prepares
+slice 2 as 0.45.0 on the released 0.44.1 base.
+
+1. **0.44.0 — spatial state delivery**, above. Proof: codec oracle, real views
+   on virtual time, loss/reconnect, and 300-client host/relay workload.
+2. **0.45.0 — Gates and bigger public rooms (implemented below).** Gate/concentrator classes together,
+   reuse the delivery role, batch input and preserve commands, authenticated binding-only admission,
+   resume/revocation, and automatic layout from `players.max`. Remove public seat
+   caps, make guest policy studio-selected, report tested size in build/deploy
+   plans. Prove 300 clients through the actual join path, Gate restart/resend,
+   20 Gates through concentrators, and small rooms without extra objects. Preserve
+   existing netplay builds, checks, deploys and host/port helpers at their original
+   32-seat limit. New games, starters and authoring guides use rules plus view,
+   including browser/offline mode.
+3. **Private and scheduled delivery.** Field `see`, reliable one-player `tell`,
+   optional studio-chosen downstream budget and priorities (near/far visual
+   scheduling shipped in slice 2),
+   watcher follow/region and overview feeds, crowd rendering guidance/helpers.
+   Update starters where these capabilities apply. Prove no owner/server field
+   reaches another player's bytes, tells survive reconnect once, boundary
+   enter/leave and fairness under a chosen budget; measure a dense crowd and
+   rendering in real browsers. A view leaving interest is not evidence of privacy.
+4. **Crowd policies and vehicles.** Studio-selected `crowd.cap` with queue/hold,
+   soft event work scheduling without dropping work, `uses`, solid bodies,
+   attach/control/detach and driver prediction. Prove cap absent means no imposed
+   cap; explicit queues/holds release correctly; four-person vehicle prediction,
+   seat contention, disconnect and restore. Ship one vehicle example and update
+   the skill in the same slice.
+5. **Large worlds' files.** Extend existing studio-owned R2 asset serving to game
+   files over 25 MiB and multipart upload; streamed map chunks, zones, compiled
+   triangle meshes and navigation. Reuse the existing upload/build machinery.
+   Prove large asset integrity, interrupted/resumed multipart upload and map
+   streaming with the same collision data on server and client.
+6. **Milestone proofs and authoring tools.** Single-machine swarm CLI, match kit,
+   cross-browser-engine movement hashing, S6 at 20/60 Hz and multiple regions,
+   S11 transport assessment, dense crowd tuning and remaining authoring trials.
+   Local correctness stays seeded/virtual; long runs stay extended. The roadmap's
+   300-bot, 30-minute Cloudflare exit test, Gate recovery latency, physical phone
+   rendering and actual billing need a separately authorized deployment/device
+   session. No local receipt here is represented as those results.
+
+## Slice 2 (0.45.0): public rooms in the hundreds
+
+Implemented:
+
+- `players.max` is the single build size, read by public admission, compilation
+  and deploy planning without the 32-seat clamp. Shared carrier addresses have
+  no automatic player ceiling.
+- Gate and Concentrator classes carry ordered, batched logical connections over
+  binding-only links. Public authentication remains in the Worker. Small rooms
+  embed the delivery role in the Table; larger layouts use one logical Gate per
+  64 seats and concentrators above eight Gates. These are routing partitions,
+  not admission limits. The template generates both bindings and migrations.
+- Link loss closes downstream sockets for normal token-based seat resumption.
+  Gates do not persist simulation or become a second authority. Gate passes are
+  internal binding requests, not independently client-supplied authorizations.
+- Ordered snapshot deltas, shared spatial indexing and cached wire rows reduce
+  repeated work. Optional `precisionM`, `nearM`, and `farHz` schedule remote
+  visual state; controlled bodies remain exact and independently recoverable in
+  every frame. A lost remote delta cannot stall the local body or collider
+  revisions. Snapshot exits remain immediate.
+- Revision 12 carries roster patches after a full welcome roster. A reconnect
+  storm previously repeated full rosters to every player. The patch baseline is
+  the last transmitted roster, separately from policy relabelling.
+
+A 300-player manifest (the game still needs appropriate arena,
+spawning, rule cost and rendering):
+
+```json
+{
+  "players": { "min": 1, "max": 300 },
+  "room": {
+    "host": "server",
+    "view": { "radiusM": 12, "precisionM": 0.01, "nearM": 4, "farHz": 5 }
+  }
+}
+```
+
+The visual settings are examples, not imposed defaults or information privacy.
+The workload explicitly chooses a 5,000,000-unit tick budget as in slice 1.
+
+### Local measurements
+
+All results below are **local**, not Cloudflare, billing, Internet latency or
+physical-phone results. Bytes exclude WebSocket/TLS framing. Heap/RSS include
+clients and the test harness in the same Node process. Other work on this
+machine affects CPU timing; bytes are deterministic for the virtual workload.
+
+| Workload | Players | Mean bytes/player/s | Tick p50 / p95 ms | Peak heap / RSS bytes |
+| --- | ---: | ---: | ---: | ---: |
+| Unmodified 0.44.0, 1,200 virtual ticks | 300 | 23,171 | 12.23 / 16.72 | 134,431,008 / 238,534,656 |
+| Final scheduled/delta delivery, 1,200 virtual ticks | 300 | 9,937 | 10.57 / 15.59 | 129,070,360 / 232,275,968 |
+| Final scheduled/delta delivery, 120 virtual ticks | 1,000 | 10,258 | 33.88 / 52.12 | 190,297,048 / 328,974,336 |
+| Gate links, 4 Chrome pages, reconnect churn and host restore, before roster patches | 300 | 88,444 | 15.79 / 73.47 | 142,211,400 / 375,734,272 |
+| Same mixed transport workload, with roster patches | 300 | 13,623 | 13.52 / 25.33 | 154,397,384 / 274,808,832 |
+
+Steady-state downstream falls about **57%** at 300. The two preliminary mixed
+runs include recovery traffic and measured a host wake (potentially several
+ticks); they are not directly comparable to the steady-state pair or the final
+single-tick measurements below. They did not declare rounds. The final harness
+declares a ten-minute round and verifies that failures preserve it.
+
+The mixed harness uses the real Gate/Concentrator classes, rules loader,
+host and NetRoom, external local WebSockets and four Chrome pages rendering
+received bodies, with in-memory links standing in for Durable Object bindings.
+Actual public Worker routing and workerd eviction are checked separately below.
+
+Commands:
+
+```sh
+node packages/studio/test/rules-crowd-local.mjs 300 60
+node packages/studio/test/rules-crowd-local.mjs 1000 60
+node --test packages/studio/test/rules-gates.test.mjs packages/studio/test/rules-interest.test.mjs
+```
+
+The sustained, real-time 300/1,000 mixed runs live in `test:rules:extended`,
+which runs files sequentially so load experiments do not compete with each other.
+Virtual-time tests cover batching/order, 1,000 logical admissions, link cleanup,
+spatial boundaries, quantisation, far scheduling and keyframe recovery.
+
+### Admission, compatibility and recovery proofs
+
+Existing browser-hosted netplay games retain the build and runtime path from
+0.44.1, including host helpers, HUD and port import. Their manifest precedence
+and 32-seat limit remain; larger requests print the limit and rewrite guide.
+The generated Worker supplies Gate/Concentrator exports for pre-Gate studio
+entries without rewriting custom Worker source. The release gate uses unchanged Ember Vale files from released 0.32.1, packs and
+installs the current package, builds it and runs the real two-browser check
+through a completed round. Starters/docs teach rules plus view only.
+Migrating the rules fixtures exposed missing TypeScript resolution for shared parts;
+the guarded checker now resolves those same declared parts as the bundler.
+
+The public Worker test verifies its actual authorization and capacity selection
+for 300 and 1,000 against Gate bindings, including a private-door refusal and
+ignoring caller-supplied capacity/hosting. Real local workerd tests additionally
+prove 20 Gate binding links through concentrators and a Gate abort, and the full
+public Worker → Gate → Table/SQLite route: 40 seats in a declared 300-player room,
+then Gate death and Table death, with every token resuming its original seat.
+The extended Workerd case also passed all **1,000 actual public admissions**
+across 16 Gates/two concentrators, then a Gate abort (59 returning clients) and
+a Table abort (all 1,000 returning clients), retaining every seat. That fixture
+runs at 1 Hz and is a storage/admission proof, not a 20 Hz capacity benchmark.
+These are functional proofs; the measured full crowds below use in-memory
+internal binding links as described above, not a Cloudflare deployment.
+
+Both declared-round mixed receipts now pass:
+
+| Local mixed run | Bytes/player/s, all measured traffic | Tick p50 / p95 / max ms | Peak Node heap / RSS bytes | Churn |
+| --- | ---: | ---: | ---: | ---: |
+| 300 players, 4 Chrome pages, 62.93 s | 10,463 | 10.21 / 31.54 / 142.32 | 206,609,760 / 313,114,624 | 15 |
+| 1,000 players, 4 Chrome pages, 101.02 s | 9,203 | 32.97 / 59.29 / 188.74 | 314,542,056 / 573,784,064 | 50 |
+
+Each run recovered all players after both failures within the same live round;
+simulated clients retained their seats, and all four real pages delivered live
+snapshot receipts after recovery. The final runs also verify each simulated and
+real client's own body after recovery. The 300 run's initial steady 20-second window
+was 9,274 bytes/player/s; the 1,000 run measured 7,931 over its first 20.19 seconds.
+Recovery-window averages include disconnected intervals,
+so the seeded virtual comparison above is the fair before/after bandwidth pair.
+Mixed tick timing is now one host tick through snapshot enqueue; earlier mixed
+numbers measured a host wake, potentially several ticks. Browser process memory
+is excluded from Node heap/RSS. The 300 run averaged 19.05 simulation ticks/s
+including failures; the 1,000 run averaged 16.27. CPU timings vary with other
+machine activity; 1,000 p95 exceeds a
+50-ms tick period, so this is not a claim of guaranteed 20 Hz on Cloudflare.
+
+The earlier failed 1,000 run is superseded. Fixes isolated a single failed
+client send from its entire Gate, compacted identical fanout rows on internal
+links, and made the restart harness reconstruct both saved relay seats and the
+host (as a Table restart does) instead of rejoining every old connection just
+before disconnecting it. Final root and six-check CI results are tracked in
+[PR #85](https://github.com/homie-rocks/homie/pull/85). No deployment or merge
+was performed.
+
+Competing full-suite and load runs triggered the real Workerd overrun guard
+and a mixed-run recovery timeout. They are failed stress attempts, not capacity
+receipts. The successful full Workerd rerun kept that guard enabled and ran
+without our other load runs. No Cloudflare CPU, memory or network guarantee is
+inferred from these local results.
+
+The scripted recovery checks include deliberate observation waits. All clients
+were back when checked at 20.08 s (Gate) / 20.74 s (rules) at 300, and
+20.10 s / 60.00 s at 1,000. These are upper bounds, not minimum recovery latency.
+The 1,000-client full restart is visibly expensive; faster crowd reconnection
+and deployed latency measurements remain work for the milestone proof slice.
+
+## Later step: retire browser-hosted netplay
+
+Retirement is not part of 0.45.0. Its preconditions are that every game in
+Homie's own three live studios has moved to server rules, and a release has
+already shipped a one-command assisted rewrite for other studios. Until both
+are met, existing games must continue to build, pass check, run and deploy,
+with the legacy release gate protecting that promise. New games remain rules
+games only.
+
+### Upgrade proof on the real studio copy
+
+Copied `/Users/ryan/Studios/homie-arcade` to
+`/tmp/homie-arcade-045-0Vaqlp/studio`, packed and installed 0.45.0 there.
+`npm run build` passed for all five existing netplay games.
+`npm run check -- --url http://127.0.0.1:8898` passed for its default game,
+2048 Race: desktop and phone finished round 1 in 123 seconds, with both
+connections uninterrupted. The original studio was not changed; nothing was
+deployed. The released 0.32.1 Ember Vale gate also passed with an older Worker
+entry: one host and one replica finished round 1 in 92 seconds.

package/guides/game/RULES.md

@@ -780,8 +780,17 @@ Rules, collision, saves and shared state stay authoritative and unchanged.
 Views must interpolate distant motion and dispose/recreate entities on view exit
 and entry. Omit the settings for full precision and the room's normal tick rate.
 
-A small room embeds delivery in its Table. Larger rooms open Gate connections;
-more than eight Gates use concentrators. The studio template supplies their exports, bindings and
+A small room embeds delivery in its Table. Larger rooms open Gate connections, one channel
+from each Gate to the room: the room runs the rules and hands each Gate one world a tick, and
+the Gate selects, encodes and paces each player's view. A player on a slow connection is sent
+fewer, fresher frames, never a growing backlog; draw from the newest snapshot and interpolate.
+A body that keeps its course is not sent every tick: the view library moves it along its last
+velocity, and it is sent again when that has drifted past `view.precisionM` (near bodies) or half
+the distance it covers between `view.farHz` refreshes (far ones). `precisionM` is what a crowd
+costs a player's connection: 0.01 is a centimetre; 0.05 sends about a sixth fewer bytes.
+Homie sets no pace on what a player sends a server-hosted game. To set your own, add
+`"rates": { "in": 60 }` to `room` in game.json: messages a second per player, by frame kind.
+The studio template supplies the Gate exports, bindings and
 migration; upgrade the template before deploying an existing studio. No infrastructure naming or studio admission ceiling is required.
 Read the local measurements and their limitations in
 `docs/rooms-milestone-2-notes.md` before making a capacity claim.

package/lib/build-identity.mjs

@@ -0,0 +1,43 @@
+/** Content identity of the runtime, independent of a studio's package pin or git commit. */
+import { createHash } from 'node:crypto';
+import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+const root = fileURLToPath(new URL('../', import.meta.url));
+export function runtimeIdentity() {
+  const hash = createHash('sha256');
+  function walk(dir) {
+    for (const entry of readdirSync(join(root, dir), {
+      withFileTypes: true
+    }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+      const path = dir + '/' + entry.name;
+      if (entry.isDirectory()) walk(path);
+      else if (/\.(mjs|ts|json)$/.test(path) && path !== 'worker/build-id.mjs')
+        hash
+          .update(path + '\0')
+          .update(readFileSync(join(root, path)))
+          .update('\0');
+    }
+  }
+  for (const dir of ['worker', 'rules', 'netplay']) walk(dir);
+  return {
+    version: JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+      .version,
+    sha256: hash.digest('hex')
+  };
+}
+export function stampRuntime(check = false) {
+  const text =
+      '// Generated by lib/build-identity.mjs; identifies the bundled runtime sources.\nexport const STUDIO_BUILD = Object.freeze(' +
+      JSON.stringify(runtimeIdentity()) +
+      ');\n',
+    path = join(root, 'worker/build-id.mjs');
+  if (check) {
+    if (readFileSync(path, 'utf8') !== text)
+      throw Error(
+        'Runtime identity is stale: node packages/studio/lib/build-identity.mjs --write'
+      );
+  } else writeFileSync(path, text);
+}
+if (process.argv[1] === fileURLToPath(import.meta.url))
+  stampRuntime(process.argv.includes('--check'));

package/lib/cloudflare.mjs

@@ -1,3 +1,4 @@
+import { roomLayout } from '../worker/gate.mjs';
 import {workerEntry} from './worker-build.mjs';
 import { seatCount } from '../worker/seats.mjs';
 import { refreshWorkerConfig } from './worker-config.mjs';
@@ -175,9 +176,12 @@ export async function zonePlan(root, opts = {}) {
  */
 export function hostedUse({ seats = 8, inputHz = 20 } = {}) {
   const requests = Math.round((seats * (inputHz * 3600 + 1800)) / 20);
-  const gbSeconds = 0.128 * 3600;
+  const layout = roomLayout(seats);
+  // A room behind Gates: the room, its Gates, and the object that keeps its diagnostics.
+  const objects = 1 + (layout.gates > 1 ? layout.gates + 1 : 0);
+  const gbSeconds = 0.128 * 3600 * objects;
   const pct = (n, of) => (n / of < 0.001 ? 'under 0.1%' : `${Math.round((n / of) * 1000) / 10}%`);
-  return { seats, requests, gbSeconds, rows: 12, share: { requests: pct(requests, 100_000), gbSeconds: pct(gbSeconds, 13_000), rows: pct(12, 100_000) } };
+  return { seats, requests, gbSeconds, objects, layout, requestBasis: 'player input and ping only; relay frames, receipts, HTTP, saves and Lobby are additional', rows: 12, share: { requests: pct(requests, 100_000), gbSeconds: pct(gbSeconds, 13_000), rows: pct(12, 100_000) } };
 }
 
 /** What `deploy` will create and what it costs, from studio.json alone. It calls nothing. */
@@ -197,18 +201,16 @@ export function deployPlan(root) {
   return {
     ok: true, command: 'deploy plan', studio: studio.name, account: cf.accountId ?? null,
     cloudflare: [
-      { kind: 'Worker', name: cf.worker, what: 'the studio\'s pages, each game\'s page and play shell, and /.well-known/homie-studio.json for the directory', state: mark(`worker:${cf.worker}`), plan: 'Workers Free' },
-      { kind: 'D1 database', name: cf.d1, what: 'the directory claim, every finished round, the studio\'s own stats (daily counters of visits, plays, rooms, rounds and songs, for the owner only; nothing about a visitor), and, for games that keep saves, player accounts (a passkey\'s public key, never a password) and their saves', state: mark(`d1:${cf.d1}`), plan: 'Workers Free (500 MB per database, 5 GB per account)' },
-      { kind: 'Durable Object', name: 'Table', what: hosted.length ? `one per public room: the netplay relay (seats, snapshots), and for ${hosted.map((h) => h.id).join(', ')} the game's own rules, which run here and nowhere else` : 'one per public room: the netplay relay (seats, host, snapshots); runs no game code', state: 'declared by the Worker', plan: 'Workers Free (SQLite-backed)' },
-      ...hosted.map((h) => ({ kind: 'Game rules', name: h.id, what: `the rules of ${h.name} run on Cloudflare, in each room's Table, not in a player's browser. An hour of play in one full room (${h.seats} players) uses about ${h.share.requests} of the free plan's 100,000 requests a day, ${h.share.gbSeconds} of its 13,000 GB-seconds of running time and ${h.share.rows} of its 100,000 rows written. A room with nobody in it uses nothing. Out of requests, every room of every game stops until 00:00 UTC; the Workers Paid plan removes the three allowances`, state: 'in the Worker', plan: 'Workers Free' })),
-      { kind: 'Durable Object', name: 'Lobby', what: 'one per game: puts strangers who press Play into the same room', state: 'declared by the Worker', plan: 'Workers Free (SQLite-backed)' },
+      { kind: 'Worker', name: cf.worker, what: 'the studio\'s pages, each game\'s page and play shell, and /.well-known/homie-studio.json for the directory', state: mark(`worker:${cf.worker}`) },
+      { kind: 'D1 database', name: cf.d1, what: 'the directory claim, every finished round, the studio\'s own stats (daily counters of visits, plays, rooms, rounds and songs, for the owner only; nothing about a visitor), and, for games that keep saves, player accounts (a passkey\'s public key, never a password) and their saves', state: mark(`d1:${cf.d1}`) },
+      { kind: 'Durable Object', name: 'Table', what: hosted.length ? `one per public room: the netplay relay (seats, snapshots), and for ${hosted.map((h) => h.id).join(', ')} the game's own rules, which run here and nowhere else` : 'one per public room: the netplay relay (seats, host, snapshots); runs no game code', state: 'declared by the Worker' },
+      ...hosted.map((h) => ({ kind: 'Game rules', name: h.id, what: `One full ${h.seats}-player room activates ${h.objects} objects (${h.layout.gates > 1 ? `${h.layout.gates} Gates, the room and its diagnostics` : 'the room'}): approximately ${h.gbSeconds} GB-seconds/hour before Lobby activity. Player input/ping alone contributes ${h.requests} request units/hour; relay frames and receipts, HTTP and storage are additional. Occupancy, batching and account usage determine the bill.`, state: 'in the Worker' })),
+      { kind: 'Durable Object', name: 'Lobby', what: 'one per game: puts strangers who press Play into the same room', state: 'declared by the Worker' },
       storage
         ? { kind: 'R2 bucket', name: storage, what: 'the studio\'s big media: songs and videos over the size studio.json media.r2Over names (1 MiB unless set) or that git leaves out, uploaded and checked by SHA-256 before the site stops carrying them, served at their same addresses', state: 'exists (this studio made it)', plan: 'R2 (payment method on the account; 10 GB-month free)' }
         : { kind: 'R2 bucket', name: null, what: 'none: a new studio needs no storage. `homie-studio storage add` adds it later, for large media only', state: 'not created', plan: null },
     ],
-    cost: storage
-      ? `Free on Cloudflare's Workers Free plan. ${R2_COST} Beyond the free tier Cloudflare bills the account directly.`
-      : 'Free: everything above is on Cloudflare\'s Workers Free plan, which needs no payment method. Its daily limits (100,000 Worker requests; D1 5 million rows read and 100,000 written) reset at 00:00 UTC; past them requests fail until the reset, nothing is charged.',
+    cost: 'Account subscription not queried. Cloudflare bills usage under the account’s current plan; estimates are not a billing quote.',
     login: 'One approval: `npx wrangler login` opens Cloudflare in the person\'s browser (a free account works; a new one verifies its email address first).',
     address: `https://${cf.worker}.<the account's workers.dev subdomain>.workers.dev`,
     directory: {
@@ -299,7 +301,7 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRo
     const account = who.accounts.find((a) => a.id === accountId)?.name ?? 'the signed-in account';
     announced.push(
       `First deploy of ${studio.name} to the Cloudflare account "${account}". It creates: the Worker ${cf.worker} (the site and its rooms), the D1 database ${cf.d1} (rounds, and the studio's own stats: counts for the owner, never a visitor's identity), and the Durable Objects Table and Lobby (SQLite-backed).`,
-      'Cost: free, on the Workers Free plan; no payment method, no R2 (storage for large media is `homie-studio storage add`, later, only if wanted).',
+      'Account subscription not queried; usage is billed under the account’s current Cloudflare plan.',
       `The directory (${homie || studio.homie?.directory || 'https://homie.rocks'}) will store the site's address and claim, the studio's name, and each game's name, blurb and Play link.`,
     );
     for (const line of announced) log(line);

package/lib/crowd-cloud.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * 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]
+ *
+ * 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).
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Tally } from './crowd-probe/client.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() };
+  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 }; };
+  const sum = (key) => players.reduce((a, p) => a + (p[key] ?? 0), 0), leads = of('lead');
+  const errors = new Map();
+  for (const p of players) { for (const text of p.errors ?? []) errors.set(text, (errors.get(text) ?? 0) + 1); if (p.closed && p.closed[1] !== 'probe step complete') { const text = `close: ${p.closed[0]} ${p.closed[1]}`; errors.set(text, (errors.get(text) ?? 0) + 1); } }
+  for (const text of failures) errors.set(text, (errors.get(text) ?? 0) + 1);
+  const joined = players.filter((p) => p.firstStateMs !== null).length, measured = Math.max(0, (endAt - measureAt) / 1000);
+  return {
+    generator: 'cloudflare', colos: [...new Set(finals.map((f) => f.colo).filter(Boolean))],
+    started: new Date(started).toISOString(), measurementStarted: new Date(measureAt).toISOString(), ended: new Date(endAt).toISOString(),
+    origin, room, n, total: n, simulated: n, chromePlayers: 0, toolkit, requestedSeconds: seconds, measuredSeconds: measured, stopReason: finals.length ? null : 'no probe answered',
+    joined, connectedAtEnd: players.filter((p) => p.firstStateMs !== null && (!p.closed || p.closed[1] === 'probe step complete')).length,
+    disconnects: players.filter((p) => p.closed && p.closed[1] !== 'probe step complete').length,
+    firstStateMs: (() => { const a = of('firstStateMs'); return { count: a.length, p50: pick(a, 0.5), p95: pick(a, 0.95), p99: pick(a, 0.99), max: a.at(-1) ?? null }; })(),
+    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 },
+    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 })),
+    players,
+  };
+}
+
+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');
+  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?`);
+  let toolkit = null;
+  try { toolkit = (await (await fetch(`${origin}/.well-known/homie-studio.json?probe=${Date.now()}`, { signal: AbortSignal.timeout(15000) })).json()).toolkit ?? null; } catch { /* reported as null */ }
+  // Every request is told the same moments: when its players join (one every ramp-ms), when to start measuring
+  // (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();
+  await Promise.all(Array.from({ length: Math.ceil(n / 5) }, async (_, r) => {
+    const from = r * 5, count = Math.min(5, n - from);
+    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) });
+      if (!res.ok || !res.body) throw Error(`probe HTTP ${res.status}`);
+      let text = '', final = 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 (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)}`); }
+  }));
+  const report = cloudReport({ origin, room, n, seconds, started, measureAt, endAt, finals, failures, toolkit });
+  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;
+}