@indiegems/gem-web-sdk 7.4.0 → 7.4.2

package/docs/dedicated-server-flow.md

@@ -0,0 +1,879 @@
+# Dedicated servers — the browser half
+
+How a browser game gets from "I am in a room" to "I have a reliable ordered channel to a dedicated
+server" — over WebRTC by default, or across the negotiated transport ladder (WebTransport, WebRTC,
+WebSocket) that [`connect({ transports })`](#choosing-a-transport) opts into. The platform half is
+gem-api's and has its own design; this describes only what runs inside the game frame, and it is
+deliberately narrow.
+
+**Most games do not call this flow directly.** `gem.match.connect()` resolves one `MatchConnection`
+to whichever authority the room template chose — this dedicated server, a hosting peer, or the
+host's own in-process bundle — and on a dedicated match it runs exactly the flow below, with the
+negotiated transport ladder as its default. `gem.dedicatedServer.connect()` stays public for a game
+that wants the options this page describes: `retry`, `onMessage`, the WebRTC-only session and the
+raw `channel`. [`server-bundles.md`](server-bundles.md#the-same-bundle-hosted-by-a-player) shows
+the two `gem.match` calls.
+
+## What this is and is not
+
+This is the transport half only: protocol refusal, offer, answer, channel. **Rooms, membership, the
+host, ready state and the match lifecycle are `rooms-and-matches.md`**, and this flow reads its
+match from the room rather than from an argument.
+
+It used to be otherwise. This flow was written around a room id it was handed and a `matchId` a game
+had to carry from the host to the other players itself, because rooms were assigned elsewhere. That
+was reversed on 2026-08-01 and the room now supplies both. `connect` takes neither id.
+
+## 1. How the request reaches gem-api
+
+Over the ordinary authenticated client. No new transport, no new token path.
+
+Allocation and connection details are two existing routes, and both take
+`AuthenticatedGamePlayer` — the game-scoped play token the bridge already delivers:
+
+| Step               | Route                                                                         |
+| ------------------ | ----------------------------------------------------------------------------- |
+| Allocate           | `POST /v1/games/{game_id}/game-rooms/{game_room_id}/start_match`              |
+| Connection details | `GET /v1/games/{game_id}/game-rooms/{game_room_id}/matches/{match_id}/status` |
+
+`game_id` comes from the token, never from the game — the same rule the HTTP transport already
+applies to its default query. **No new foundation was needed for this:** the backend client, the
+token source and the transport seam landed in earlier stages and this sits on top of them unmodified.
+
+Three things about those routes are not free, though, and none of them is the caller's to supply any
+more.
+
+**Match status requires version fields, but only once the match is ready.** `platform` and
+`game_version` are validated on the `ready` branch and nowhere else, and gem-api's shipped config
+sets `require_version_fields`. Omitting them therefore polls healthily through every `pending`
+response and fails at the exact moment the server comes up, with a 400 that reads like an SDK bug.
+They are sent on every one of these calls for that reason. They are the same values the room was
+joined with, which is what gates "everybody is on the same build" — and the SDK has an answer for all
+three without asking the game: it reports the platform and the engine version itself, and the game
+version comes from the arcade with the play token.
+
+**`platform` is `web`, and the SDK reports it — a game does not supply one.** It decides which
+package dimension the arcade checks this build against, and a browser game publishes its bundle in
+the `web` dimension and nothing else. Report anything else and the check is run against a dimension
+the game has never published into, where there is nothing to find and therefore nothing to refuse:
+blacklist, not-released and expiry all pass without looking at the build at all. That is not a
+weaker check, it is no check, and the way it fails is that nothing fails. A value passed here from
+an older build is replaced with `web`, with a console warning saying so.
+
+So every one of the platform's version controls reaches a web build, and **the version reported has to
+name a build you actually published**. The arcade looks it up in the web dimension on the channel
+being played: a number that matches no upload there is refused as `unknown_version`, one that was
+never promoted to that channel as `not_released`, one you blacklisted as `blacklisted`, and one that
+was replaced more than a day ago as `expired`. None of that is this SDK's machinery, but sending the
+right platform is what turns it on.
+
+**The game version is the arcade's answer, not the game's.** It arrives with the play token — the
+arcade chose which build to route this player to, so it is the only party that can be wrong about it
+by accident rather than by hand. `clientVersion.gameVersion` is deprecated and still read, which is
+the fallback under an arcade too old to send one; where both exist the arcade's wins.
+
+**The engine version is the SDK's too, and a game does not supply one either.** The room routes want
+a third field — `engine_version`, the version a native build was exported from — and a browser game
+is not an engine export, so it has none. It is not optional: `require_version_fields` covers all
+three, and sending two is a 400. So the SDK reports `0.1.0-beta` on the game's behalf, exported as
+`WEB_ENGINE_VERSION`, and the game supplies none of the three.
+
+That is not a formality, because the value decides which fleet the match can reach: it derives an
+engine _line_, and **the only web fleet line the platform runs is `0-beta`**. A game that had written
+`1.0.0`, the obvious thing to write, would land on line `1`, match no fleet, and be told there is no
+capacity — at the allocation, minutes after the create that actually decided it, naming a region
+rather than a version. A build that does know its own engine version may still pass one; it is held
+to a line a fleet runs and refused by name before anything is sent. How that line is derived, and why
+its refusal is the hardest one on this path to read, is
+[below](#two-version-lines-two-derivation-rules-and-a-refusal-that-names-neither).
+
+**Allocation is host-only.** `start_match` requires the caller to be the room's host and refuses
+everyone else with 403, before its idempotency fence — so in a four-player room, one player
+allocates and three do not. Polling needs only room membership.
+
+That used to force two entry points, and the second of them took a `matchId` nothing in the SDK could
+produce. It does not any more: **the room knows who the host is**, so `connect` allocates for that
+player and waits for the rest, and it learns the match id from the room. One method, called
+identically by every member. See `rooms-and-matches.md` §2.
+
+That answers the question the work started from. The offer takes a different route, and it is the
+subject of the next section.
+
+### Two version lines, two derivation rules, and a refusal that names neither
+
+Three version fields go up with a room, and **two of them derive a _line_** — a compatibility group
+— by **different rules**. This is the most expensive thing to get wrong on this path, because
+neither failure mentions a version.
+
+- **The engine line decides which fleet the match can be allocated from.** It comes from the engine
+  version, which the SDK supplies: the semver major plus any prerelease tag, build metadata dropped.
+  `0.1.0-beta` → `0-beta`.
+- **The game line decides which published server build serves the match.** It comes from the version
+  the build was published under, by a different rule: `0.{minor}` while you are on `0.x`, the bare major from
+  `1.0.0` on, and a prerelease is a line of its own. `0.4.7` → `0.4`.
+  [`platform-rules.md`](platform-rules.md#4-the-compatibility-line) has the full table.
+
+So your client build and your published server bundle have to land on the same **game** line — a
+`0.4.7` client against a `0.5.0` server build has no server, though the two numbers look adjacent.
+The engine line is not yours to choose at all.
+
+**The two failures look nothing alike, and the second is the trap.**
+
+| What is wrong                                     | What the host gets from `start_match`                                                                                                                                                                                                              |
+| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The room's game line has no playable server build | 409 `no_compatible_server`, with `details.reason`: `none_on_channel` (this channel has no servable server build at all), `none_in_line` (it has some, none on this line) or `expired` (this line's builds aged out of the channel's expiry window) |
+| The engine line matches no fleet                  | 503 `capacity_unavailable` — **the same refusal a genuinely full fleet gives**, because the allocator cannot tell the two apart                                                                                                                    |
+
+The second row is why this is worth a section. A capacity refusal carries a retry hint and reads as
+"try again shortly", so a game that supplied a plausible-looking engine version of its own would
+wait through it forever: no amount of capacity ever arrives for a line no fleet runs. **What
+separates the two is the message**, which names the engine and the line the allocator looked for. A
+503 that does not clear is worth reading before it is treated as a fleet problem.
+
+## 2. How the offer reaches the server
+
+**Through the parent page, over the player's notification WebSocket.** Not because that is convenient
+but because it is the only route: the frame cannot open that socket, and gem-api's dedicated signaling
+lives on it.
+
+### 2a. What gem-api implements
+
+The full path is shipped. The browser sends `webrtc_offer` on its notification socket; gem-api
+validates the SDP structurally, pins the session to its DTLS fingerprint, stores the offer under a
+session id, and delivers it to the dedicated server allocated to that match. The server answers on
+its own separate socket, and the answer comes back to the offering player as
+`webrtc_sdp_answer`. A refusal at any point comes back as `webrtc_error`.
+
+Three properties of that path shape this side:
+
+- **The offer is relayed verbatim and no candidate is ever read.** gem-api validates structure only.
+- **The gate is room membership, resolved from the ALLOCATION.** The message's `game_id` is a lookup
+  key that can only narrow, never select; the room comes from the allocation and the membership check
+  runs before the offer is stored or published. A frame naming a match it is not in is refused with
+  `not_match_member` and the offer reaches nobody.
+- **Silence is reported.** A publish that finds no subscriber answers `webrtc_no_server` rather than
+  leaving the offer to expire — which matters here, because the whole handshake has to fit inside a
+  sixty-second credential window.
+
+`ServerProtocol` also has its `webrtc_dedicated` value now, so a match can report the protocol step 3
+requires.
+
+### 2b. Why the frame cannot send it directly
+
+The platform design has the exchange riding the notification WebSocket on the reasoning that "the
+browser holds one anyway". **That is true of the Arcade page and false of the game frame**, and that
+difference is the whole of the argument.
+
+`POST /v1/ws/ticket` takes `AuthenticatedPlayer`, which rejects every game-scoped token by kind before
+it does anything else. The ticket exists because the browser WebSocket API cannot set handshake
+headers, so there is no bearer-header route around it either.
+
+A page that signs the player in holds both credentials and feels no friction — it can call room and
+match routes with a game token and `/v1/ws/ticket` with an account token, in the same file. A
+game inside the Arcade iframe has only the first, by design: handing the account token across the
+bridge is the exact thing the game-scoped token exists to prevent.
+
+`GET /v1/regions` has the same shape and the same consequence — see §5.
+
+### 2c. So the parent relays, under a template it owns
+
+Exactly as P2P signaling does, with a smaller message set and its own capability.
+
+| Direction      | Bridge message                      | Socket message      |
+| -------------- | ----------------------------------- | ------------------- |
+| Frame → parent | `gem.dedicatedOffer`                | `webrtc_offer`      |
+| Parent → frame | `gem.dedicatedEvent` (`answer`)     | `webrtc_sdp_answer` |
+| Parent → frame | `gem.dedicatedEvent` (`error`)      | `webrtc_error`      |
+| Parent → frame | `gem.dedicatedEvent` (`matchEnded`) | `match_ended`       |
+
+The frame names no socket message type and supplies no game id. It sends a match id, an SDP and an
+intent; the parent selects the message type, derives `game_id` from the token it issued, meters the
+write against the socket's per-second budget — one budget shared with P2P, because there is one
+socket — and refuses a frame the socket would not carry.
+
+**`dedicated` is its own capability rather than part of `p2p`.** A page may relay one transport and
+not the other; gem-api ships an independent kill switch for each on exactly that reasoning. One token
+covering both would make a partial parent indistinguishable from a complete one, and the game would
+find out by sending an offer nobody answers.
+
+**The match id is not pinned, and only on this message.** `gem.signal` refuses a match the parent has
+not seen on the socket, exempting the P2P join because a player who joins a room already in a match
+learns the id by reading the room rather than from a push. The dedicated offer is that same case with
+no join ahead of it — it is the first message on this path — so a pin would make "join a match already
+running" unconnectable outright. What stands in is gem-api's own membership check above, which is
+stronger here than on the P2P path because a refused offer reaches nobody at all.
+
+**The error push is load-bearing.** gem-api stamps no game id on `webrtc_error`, so the parent scopes
+it by match: an error crosses for a match the socket has mentioned or one this frame has legitimately
+asked about. Without that, every refusal on this path is dropped and reads as a server that never came
+up. The same rule fixes `p2p_error`, which has the same shape and was being dropped for the same
+reason.
+
+**The parent can refuse an offer itself, on the same push.** An `error` for an offer the parent did
+not put on the socket settles the exchange just as gem-api's does, and carries a code the parent
+wrote. A code beginning `embedder_` is always one of those, for an offer that never left the page.
+Where the parent's refusal means exactly what one of gem-api's codes means, it sends that code
+instead, so a code without the prefix does not prove the offer reached gem-api.
+`embedder_relay_unavailable` is a momentary socket outage: the offer passed every check the parent
+makes before a send and the socket was not open at that moment, so nothing needs fixing and a resend
+may succeed. `embedder_no_relay` is final: the parent advertised `dedicated` and has nothing wired to
+send an offer with. That will not change while the page is open, so a resend cannot help.
+
+**The match-ended push is what makes a client let go**, and it is a different socket type from the
+P2P one. gem-api sends `p2p_match_ended` when a peer-to-peer match ends and plain `match_ended` when
+a dedicated one does — the second to the room's members, from `match_end`, which is the route a game
+server calls when it is finished. This SDK listed only the first, so the second reached no allowlist
+and was dropped like any type it does not know, and a browser left open on a finished match never
+learned the match was over. See §7 for what that cost.
+
+## 3. What that means for the shape
+
+Signaling is a seam — an interface with one method — and the shipped implementation relays over the
+bridge.
+
+```ts
+interface SignalingChannel {
+  exchange(request: OfferRequest, signal?: AbortSignal): Promise<SignalingAnswer>;
+  close(): void;
+}
+```
+
+One complete offer in, one answer out. That is not a placeholder shape chosen to defer a decision: the
+platform design's non-trickle choice makes the exchange a single round trip, so an interface with a
+candidate stream in it would be modelling something the design deliberately does not do. It fits on
+the socket because gem-api's client frame ceiling was raised to 16 KB for it — a complete gathered
+offer plus its JSON envelope passes, which is what makes non-trickle possible at all.
+
+The seam remains a seam because the bridge is not the only arrangement worth supporting: a game
+embedded somewhere other than the Arcade, or a test that wants the sequence without a bridge, supplies
+its own. When nothing is wired — the parts assembled by hand — the fallback **throws
+immediately, naming what is missing**. Never a hanging promise and never a silent no-op: a game that
+calls this outside a relaying parent gets a sentence explaining why, not a spinner.
+
+The flow does not trust a supplied one to settle either. The exchange is bounded and abort-aware on
+this side, because "the seam honours its contract" is an assumption about code this repo does not
+own, and the cost of it being wrong is a promise that never settles.
+
+**The flow closes the channel it was given** — when the session ends, and on every failure, including
+the refusals that happen before the handshake begins. A narrower promise would orphan a channel on
+every attempt that refuses early: a match that never allocated, or one reporting a protocol this flow
+will not connect. It matters for the bridge implementation specifically, which shares one routing
+table across the document — which is why `connect` is handed a factory and closes what it built,
+rather than holding a channel that would take the table down with the first failed match.
+
+## 4. The connect sequence
+
+1. **Allocate — if this player is the host.** `start_match`, in the room's own cluster (§5). Returns a match id,
+   and `pending` for a dedicated allocation. Every other player skips this step without being told to:
+   the room answers "am I the host", so the call is the same one.
+
+   **This step can find no server and is retried.** A start that arrives when no server is available
+   is refused with 503 until the platform has another. `startMatch` absorbs that with a jittered
+   exponential backoff inside a **30-second** budget and reports each wait as `matchStartWaiting`, so
+   the game has something to render. Two refusals in a row move the start, once, to the next cluster
+   the player can play well in (§5). That budget is set by what a player will sit through rather than
+   by how long the platform may take, so it will miss some starts a longer one would have caught.
+   `rooms-and-matches.md` §4.4 has that reasoning, the other numbers, why retrying this route
+   cannot duplicate a match, and the refusals that are deliberately not retried — including a
+   peer-to-peer room, which fails at once rather than waiting for a server nothing is allocating.
+   **`connect()` therefore has two bounded waits in series** — this one for a match to exist, then
+   step 2's for it to come up — and `retry` and `timeoutMs` are the separate knobs on them.
+   `gem.match.connect()` has the same two waits but exposes only `timeoutMs`; the start budget stays
+   at its 30-second default there, and `gem.dedicatedServer.connect({ retry })` is how to change it.
+
+2. **Wait for the match.** The room reaches `in_game` carrying a match id, which is how a non-host
+   learns there is one at all, and the manager polls status to a terminal state. Bounded — a poll loop
+   with no ceiling is how a game hangs on a fleet that will never have capacity. `awaitMatchOutcome`
+   resolves carrying `ready` or `failed` rather than rejecting on `failed`, because a match that failed
+   to allocate is an outcome a caller can branch on; `rooms.awaitMatch` rejects, because a caller
+   asking for the match it is about to connect to has to be told it is not coming.
+3. **Refuse an unrecognised protocol, loudly.** Only `webrtc_dedicated` proceeds.
+4. **Offer.** A peer connection with **no ICE servers**, one reliable ordered data channel, and no
+   media. Gather to completion, send one offer, bounded.
+5. **Answer.** Check it, apply it, wait for the channel to open.
+6. **Present the join credential** as the first message on the channel, and wait for the runtime's
+   answer. The format belongs to the server runtime and is
+   [`server-bundles.md`](server-bundles.md): a `{"t":"join","credential":"<jwt>"}` frame, before
+   anything else, answered with `welcome` or `rejected`. `connect()` resolves once the server has
+   **accepted** this player, not merely once the transport is up.
+
+   This used to be the game's step, and the argument for that was that the flow attaches no message
+   handler so `channel.onmessage` stays the game's alone. What that produced in practice was every
+   game writing the same exchange, and the first one to ship on this platform discovering by hand
+   that a rejection carries a reason, that two of the five reasons are worth another attempt, and
+   that the wait belongs to the credential rather than to a constant. A game that gets any of it
+   wrong presents as a channel that opened and then went quiet — which reads as a platform fault and
+   gets chased in the wrong repository.
+
+   The handler is removed the instant the exchange settles, so `channel.onmessage` is still the
+   game's. `presentCredential: false` takes the raw channel back for a game that wants the exchange
+   itself; `session.welcome` is then null.
+
+   ⚠️ **The gap between the welcome and your handler.** A data channel with no listener drops what
+   arrives — nothing buffers, anywhere — and the server bundle's `join` callback runs at exactly that
+   moment, so its opening snapshot is the message most likely to be lost. Attaching in the
+   continuation right after `await connect()` is normally fast enough, and `connect({ onMessage })`
+   removes the gap entirely by attaching before the join frame goes out. Do not do both: two handlers
+   see every message twice. `gem.match.connect()` takes no `onMessage` option — attach
+   `connection.onMessage(...)` in the continuation immediately after the `await`.
+
+### Choosing a transport
+
+A match is served over up to three transports on one port — **WebTransport**, **WebRTC** and
+**WebSocket** — and **which of them, in what order, is a property of the room template, not of your
+game's source.** The template's `transports` list in your game config is the ladder:
+
+```yaml
+game_room_templates:
+  - slug: skirmish
+    match_type: dedicated
+    transports: [webtransport, webrtc, websocket] # most preferred first
+```
+
+Each entry is one of `webtransport`, `webrtc`, `websocket`; the config upload refuses anything else,
+an empty list, or a repeated entry. A template that names no list gets exactly that default order.
+A `match_type: p2p` template may name only `webrtc` — a browser hosts nothing else — and a
+`match_type: none` template may name none. Different templates in one game can carry different
+lists, so a LAN-party template can be WebSocket-only while the ranked one keeps the full ladder.
+
+The platform resolves the list onto every room read (`room.transports`, most preferred first), and
+hands the same list to whoever hosts the match: the dedicated-server runtime offers only the
+transports on it, and the SDK dials only those, in that order. **Your code names no transport:**
+
+```js
+const connection = await gem.match.connect();
+connection.onMessage((data, meta) => handle(data, meta));
+connection.send(update, { reliable: false, ordered: false });
+console.log(connection.transport); // the rung that won: 'webtransport' | 'webrtc' | 'websocket'
+```
+
+`gem.match.connect()` reads the room's list and negotiates across it. `gem.dedicatedServer.connect()`
+does the same when handed `transports: []`; without the option it takes the WebRTC-only path this
+document describes and resolves a `DedicatedServerSession` — which the SDK refuses as
+`misconfigured` if the template does not offer WebRTC, since that path has nothing else to dial.
+On the negotiated path `connect()` resolves a `MultiTransportSession` whose `link` speaks one
+shape (`send`/`onMessage`/`onClose`/`close`) whichever transport won; `session.transport` names
+the winner, and `session.channel`/`session.peerConnection` are populated only when it was WebRTC.
+
+A non-empty `transports` option on either call only **narrows** the template's ladder to the kinds
+named — its order is the template's, and it cannot add a transport the template left out. Most
+games have no reason to pass it.
+
+**The advertisement.** The runtime writes what it serves into the game room's settings under the
+reserved `gem_transports` key — whether WebTransport and WebSocket are up, their URLs, and the
+certificate hash a WebTransport client must pin — and it writes it **before** it reports the match
+ready.
+
+**Two WebTransport dials.** On platforms where the gameserver holds a DNS name and a CA-issued
+certificate, the advert's `webtransport` entry also carries `named_url`: the same listener, dialled
+by name with the browser's **ordinary certificate verification and no hashes**. The SDK prefers it
+when offered — it is the only WebTransport an engine without `serverCertificateHashes` (WebKit) can
+complete, and it works everywhere else too — and falls back to the pinned `url` if the named dial
+fails, so a stale DNS record costs an attempt, never the rung. A named dial refused because the
+browser's WebTransport has no datagram lane is the one exception: that is a fact about the browser,
+so the SDK skips the pinned dial and the rest of the rung for the page. Games never look at any of this;
+it is what `gem.match.connect()` does on your behalf. The ladder therefore reads the advert off a **fresh room fetch made after status reports
+`ready`**, where that ordering is guaranteed; the room snapshot the manager already holds arrives on
+a push that the status poll can beat, so it serves only as the fallback when the fetch fails.
+(`readTransportAdvert(room.settings, matchId)` is the reader, whichever copy it is handed.) A missing advert
+(an older runtime, or a game that overwrote the settings object wholesale) means exactly "WebRTC
+only", which is what every older runtime serves. The advert carries `match_id`, the match it was
+written for; one bound to a match other than the one being joined is ignored as if none were
+written, so an advert that outlives its match cannot redirect the next one's players. An advert
+without the field — all a runtime predating it can write — is ignored too: it cannot say which
+match it was written for, and the match it claims is the one thing the check needs.
+
+**The ladder.** Candidates are tried in the template's order, filtered first: WebTransport needs
+the advert and a browser that has the API; WebSocket needs the advert; WebRTC qualifies without an
+advert (an older runtime serves it) and with one unless the advert says `webrtc: false` — the
+runtime's word that the template left it out. A ladder that filters to nothing refuses as
+`misconfigured`, naming the template's list. A rung that fails
+with a _transport-shaped_ reason — `timeout`, `connection_failed`, `signaling_unavailable`,
+`signaling_failed` — falls through to the next, and so does a WebRTC rung the page refused with
+`embedder_no_relay`, because that refusal is about the page's relay, which only WebRTC uses;
+`credential_expired` and `credential_reused` fetch a fresh credential and retry the same rung once;
+`join_rate_limited` waits — at least two seconds, growing, with jitter, for three retries or about
+fifteen seconds in all — and retries the same rung, never the next one down, because a lower rung
+would spend another join from the budget that just refused one; anything else (`join_refused`,
+`match_ended`, `aborted`, …) aborts the whole negotiation, because it would fail identically on
+every transport. If every rung fails, the error names which transports were tried and carries the
+last rung's `reason` and `platformCode`, and so its `retryable`: `cause` holds each transport's own
+failure, in the order tried, so an earlier one that was worth retrying is still there to read.
+
+Why the order: WebTransport is preferred where it works — real datagrams, one QUIC handshake — but
+it shares WebRTC's UDP reachability, so it rescues nobody WebRTC strands. The transport that does
+is WebSocket: TCP, for [the networks that drop UDP outright](#which-players-can-reach-a-server-and-which-cannot).
+Every delivery on it is reliable and ordered, because TCP has nothing else.
+
+**The tagged wire (`wire: 2`).** On this path the join frame carries `"wire": 2`, which selects the
+tagged framing on every transport: binary messages lead with one flags byte naming what the sender
+_asked for_ (unreliable, unordered), text stays reliable ordered text. The flags cross even when
+the transport upgraded delivery — a WebSocket player receives an unreliable-flagged message
+reliably, and `meta` still says what was asked. On the WebRTC rung the SDK also opens a second
+`gem-uu` data channel (unordered, zero retransmits) so unreliable sends get real drop semantics.
+
+**The secure-context WebSocket caveat.** A `ws://` (TLS-less) listener cannot be dialled from a
+secure context — the browser refuses the mixed-content socket — so a TLS-less advert qualifies only
+where the page itself is not secure (local development, essentially). In the Arcade, WebSocket is
+only ever tried when the runtime advertises `tls: true`.
+
+**P2P is WebRTC, by construction.** A `webrtc_p2p` match never reaches this ladder: it is a
+different flow with its own connect (`p2p-and-parties.md`), and this one refuses the protocol at
+step 3 exactly as before. Its template's `transports` resolves to `['webrtc']` whatever it says —
+which is why the config upload refuses a `p2p` template that names anything else. A game does not have to pick between the two itself: `gem.match.connect()`
+reads the protocol and takes this ladder for a dedicated match or the P2P session for a
+`webrtc_p2p` one, and `gem.match.serve(bundle)` runs your published server bundle in the hosting
+browser when the template says P2P.
+
+### What one complete offer weighs
+
+Step 4 sends the offer whole, and gem-api refuses an SDP at **10240 bytes** — by closing the socket,
+not by answering, so an offer that is too big reads to the game as a connection that silently never
+establishes. The design rested on that never happening and nobody had measured it.
+
+Measured on 2026-08-02, by building the connection this flow builds — no ICE servers, one ordered
+data channel, no media — gathering to completion and weighing the result. Chromium 150, Firefox
+153.0.1, WebKitGTK 2.43.4 (Safari has no Linux build; the engine is the same one). Chromium 149 and
+Firefox 123 were measured alongside them and produced identical byte counts, which is a useful thing
+to know about a number this design leans on: two years of releases did not move it.
+
+| Machine                                  | Chromium           | Firefox  | WebKit   |
+| ---------------------------------------- | ------------------ | -------- | -------- |
+| This one — ethernet, a VPN adapter       | 587 B, 1 candidate | 716 B, 2 | 703 B, 2 |
+| Synthesised with **8** virtual adapters  | 716 B, 2           | 907 B, 4 | 913 B, 4 |
+| Synthesised with **64** virtual adapters | 716 B, 2           | 907 B, 4 | 914 B, 4 |
+
+**Sixty-four adapters cost nothing over eight, or over none.** The worst offer any engine produced was
+914 bytes, an **11x** margin against the ceiling, and every gather completed — in 35–278 ms, against
+the flow's three-second wait. Headroom that size is not a number to defend; it is a number that says
+the question is closed.
+
+It is closed for a structural reason rather than a lucky one. With no ICE servers there is nothing to
+reflect or relay off, so the list is local addresses only — and every engine gathers on the **default
+route alone**, ignoring every other adapter on the machine. The candidate list is a property of the
+page, not of the network it sits on.
+
+One thing widens it, in one engine: a Chromium frame **holding a camera or microphone permission** is
+offered every adapter there is. The list then grows linearly, at about 115 bytes a candidate, and
+crosses the ceiling at around **forty adapters**.
+
+| Adapters (Chromium, capture permission held) | 8      | 16     | 32     | **40**      | 48      | 64      |
+| -------------------------------------------- | ------ | ------ | ------ | ----------- | ------- | ------- |
+| Offer                                        | 2955 B | 4796 B | 8486 B | **10333 B** | 12172 B | 15884 B |
+| Candidates                                   | 22     | 38     | 70     | 86          | 102     | 134     |
+
+Firefox and WebKit stayed at 4 candidates through all of it, permission or no permission.
+
+Forty adapters is a container-heavy developer machine, not a player's. Two things have to be true at
+once for it to matter, and the second is not this repo's to decide: **the Arcade would have to
+delegate `microphone` or `camera` to the game iframe**, and the player would have to be on such a
+machine, in Chromium. Until the frame can hold a capture permission at all, the ceiling is
+unreachable from this flow.
+
+When it does happen the failure is at least named and local: the frame-side size check refuses it as
+`invalid_sdp` with the byte count, before anything is sent, rather than letting the socket close
+underneath the game. That is the whole reason those checks are mirrored client-side.
+
+Nothing here argues for moving a limit. Raising `max_sdp_size_bytes` would drag `MAX_FRAME_SIZE` with
+it (they are tied by a boot assertion), trickling would be a protocol change on both ends for a
+margin that is already 11x, and capping the candidate list would trade connectivity for bytes nobody
+needs back.
+
+### Why step 3 is a refusal and not a fallback
+
+`MatchStatusResponse` populates `host` and `port` for every dedicated match, including this one, where
+they are advisory and the authoritative address is the candidate inside the answer SDP. The platform
+design says plainly that "a client that does not recognise the protocol value will use them and fail".
+
+Refusing also catches the rarer case worth catching: a match reporting a protocol this flow does not
+recognise is one something upstream got wrong, and it is better for that to be loud at one end than
+invisible at both. A client that shrugged and dialled host/port would be the second of those.
+
+### Why the client refuses media in both directions
+
+The platform refuses signaling SDP that carries an active audio or video section, and that is a
+compliance control rather than hygiene: voice belongs to the platform's own voice sessions, which
+the server side of a match allocates and tears down ([`server-bundles.md`](server-bundles.md)), and
+signaling is not a route to adding it here. Those sessions are themselves WebRTC and the player's
+browser connects to one the platform runs; what this rule excludes is voice over the game's own peer
+connections, not voice in the browser. This flow builds its own offer and adds no track, so the
+rule is satisfied by construction — but the peer-connection factory is injectable, so a game _can_
+hand in a connection with a track already attached. Checking our own offer before sending it turns
+that into an immediate, explained refusal rather than a server rejection the game cannot interpret.
+
+The **answer** is checked too, and that half is not merely symmetry: an answer accepting an audio
+section establishes an inbound track in the browser, so checking only what we send would leave one of
+the two directions unguarded.
+
+### Why the credential is spent against a deadline
+
+The join credential from match status has a sixty-second TTL, and the whole remaining chain — offer,
+answer, ICE, DTLS, SCTP, present — has to fit inside it. Over an already-open socket it fits
+comfortably, but "comfortably" is not a guarantee, and a credential that expires mid-handshake fails at
+the server with an error that reads like a bug in the game. The deadline is anchored to the moment
+status was **asked for**, not the moment it answered — gem-api started the credential's clock a round
+trip earlier, and deriving it from the reply would put the deadline late, which is the unsafe
+direction. It then **caps every wait after that point**: the signaling exchange and the channel-open
+wait each end at whichever comes first, their own timeout or the credential. At the tie the credential
+is what gets named, because it is the bound a developer can do something about.
+
+Absence is absence: a match that issues no credential (a P2P one does not) reports none, rather than an
+empty string with a deadline of _now_ — which reads as a credential that expired the instant it
+arrived, and sends a developer looking for a clock problem.
+
+### Which players can reach a server, and which cannot
+
+This failure is **per player, not per game**. A permissive home network connects and an office
+network may not, so a playtest that succeeds proves nothing about the shapes it did not run on —
+and a per-player failure nobody expected gets reported as a flake.
+
+**NAT is not the failure shape here.** The server is a passive ICE agent sitting on a publicly
+routable address and port: it never initiates and never gathers, so the browser always sends the
+first connectivity check, the server answers the source address it observed, and neither side has to
+predict the other's mapped port. Every home router works, including the strictest filtering
+discipline — the one usually called "symmetric NAT" — and so do CGNAT and double NAT. A connectivity
+report that blames NAT type is pointing at the wrong thing.
+
+What breaks it is a network that will not carry the packets at all:
+
+| The player's network                                                        | Direct connection |
+| --------------------------------------------------------------------------- | ----------------- |
+| Any NAT, any filtering discipline, including "symmetric"; CGNAT; double NAT | works             |
+| Outbound UDP permitted to any destination port                              | works             |
+| **Outbound UDP permitted only to well-known ports** (443, 3478, 53)         | **fails**         |
+| **Outbound UDP blocked entirely**                                           | **fails**         |
+| **IPv6-only with no CLAT**                                                  | **fails**         |
+
+The third row is the one worth knowing about, because it is a common corporate and guest-wifi
+posture rather than an exotic one. A dedicated server's UDP port is assigned dynamically and is not a
+well-known one, so a firewall that permits UDP only to the ports it recognises blocks the game while
+leaving the videoconferencing products on 3478 working perfectly — which is exactly the shape that
+gets read as "your game is broken and everything else is fine". The last row fails because an ICE
+candidate is an IP literal: there is no name for DNS64 to synthesise from, so a NAT64-only network
+cannot reach it. Most IPv6-only mobile carriers deploy a CLAT and are unaffected.
+
+**There is no relay to fall back on.** A TURN lease is a peer-to-peer feature: a dedicated match is
+issued no relay, and the lease endpoint refuses one by name (`match_not_p2p`) if asked. So for the
+three failing rows there is nothing to try today, and a player on such a network cannot reach a
+dedicated match at all.
+
+### What the client sees when it does not connect, and why only the client can say
+
+**gem-api stops watching once it has answered the offer.** It is not on the media path and never
+reads a candidate address, so from the exchange onwards a connection that failed and one that
+succeeded silently are the same thing from where it stands. Everything below the signaling layer is
+visible only to the two endpoints.
+
+So the cause is told apart by **which stage the attempt reached**, and the failure this flow raises
+names it:
+
+| Where it stopped                                       | What happened                                                                                                                                                                                                                                                                                                                                     |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A **`platformCode`** without the `embedder_` prefix    | Refused by the platform, or by the page for the same reason. The code is one of gem-api's: `match_not_found`, `not_match_member`, `account_banned`, `age_restricted`, `invalid_sdp`, `rate_limited`, `service_unavailable`, `fingerprint_mismatch`, `webrtc_no_server` (the offer was stored and nobody was listening for it) or `internal_error` |
+| A **`platformCode`** beginning `embedder_`             | The offer never left the page embedding your game, which refused it. `embedder_relay_unavailable` is a momentary socket outage, and a resend may succeed. `embedder_no_relay` is final: the page has nothing wired to relay with, and a resend cannot help                                                                                        |
+| `timeout` waiting for an answer, and no `platformCode` | **Three causes, one silence.** The server heard the offer and either its answer was refused or it died — a refused answer is reported to the _server's_ socket, so the player is told nothing at all                                                                                                                                              |
+| `connection_failed` once the answer was applied        | **This is the ICE failure**, and the network table above is where it comes from                                                                                                                                                                                                                                                                   |
+| `join_refused` once the channel opened                 | The transport is fine; the runtime turned down the join credential                                                                                                                                                                                                                                                                                |
+| `signaling_unavailable`, with no offer ever sent       | No parent, or one that never offered to relay (it did not advertise `dedicated`). A property of where the game is embedded, not of the platform                                                                                                                                                                                                   |
+
+**`platformCode` is the discriminator worth keying on**, because its presence proves that whoever
+was carrying the offer answered it — whatever `reason` the code was mapped to. It is not proof that
+the offer reached gem-api: an `embedder_` code says it did not, and a code without the prefix cannot
+say it did, because the page sends one of gem-api's codes where its own refusal means exactly the
+same thing. The mapping is by whether another attempt could end differently: a malformed SDP arrives
+as `invalid_sdp`; the four refusals that are facts about the account or about this client's picture
+of the match arrive as `offer_refused`, and so does `embedder_no_relay`, which is a fact about the
+page — it has nothing wired to relay with, and will not while it is open; and everything else —
+including `webrtc_no_server` and `embedder_relay_unavailable` — arrives as `signaling_failed` and is
+marked retryable, because a runtime still pulling its image answers the next offer, and a socket that
+was down a moment ago may be open for the next one. On the negotiated path, `embedder_no_relay` costs
+only the WebRTC transport: the SDK carries on to one that does not need the page.
+
+**A single handler on "it failed" collapses the first four rows into one symptom**, and that is
+precisely the shape that gets reported to a platform team as a flake. Record the stage. The
+[boot line](what-a-game-must-do.md#boot-diagnostics-where-the-seconds-went) is the other half of the
+same job, because it survives in a console capture taken from a player nobody can reach.
+
+### What a failed connect tells the platform
+
+A connect that fails from step 4 onwards is counted once — bar the exclusions at the end of this
+section — as a `connection_failures_total` event on
+`POST /v1/games/{game_id}/telemetry/p2p` labelled `transport: dedicated`. The route is named for P2P
+and is not only P2P's: it is scoped by **game** rather than by match, so a dedicated client reaches it
+with the play token it already holds, and the label is what keeps the two transports apart once
+counted. Nothing is wired for this — the flow reads the game id from the room it was already given —
+because a reporter a caller can forget to pass is one that ends up with no callers.
+
+**The client is the only party that can send it.** gem-api answers the offer and then stops watching;
+it is not on the media path, so from the exchange onwards a connection that failed and one that
+succeeded silently are the same thing from where it stands. A flat zero on that series means nobody
+reported, not that nobody failed — which is precisely what it meant before this shipped.
+
+**What is deliberately not reported: anything the platform decided itself.** An allocation it watched
+fail, an offer it refused, a fleet it had no room in, a match it ended — those are counted where they
+happened, and saying them again here would be this client telling the allocator what the allocator
+just told it. Nor is a cancelled connect or a misconfigured game. The page's own final refusal,
+`embedder_no_relay`, is reported all the same: it arrives as `offer_refused`, but the platform never
+saw that offer.
+
+So step 4 is where counting _becomes possible_, not a rule that everything past it counts. The
+`match_ended` refusal of §7 is the case that shows the difference, and it is the one to keep in mind
+when reading the two sections together: it lands squarely inside the handshake, and it is still not
+reported — a match the platform ended is not a connection that failed, and the transport may have
+been perfectly healthy right up to the push that ended it. Counting it would fill the panel that
+exists to find players who could never connect with players whose match simply finished.
+The set of reported reasons is an inclusion list, so a failure reason added later is not silently
+swept in.
+
+## 5. Cluster target selection is the parent's, and the game names nothing
+
+A dedicated allocation requires a `cluster_target_id`, and until this section was rewritten the SDK
+made every caller supply one by hand on the reasoning that nothing reachable from the frame could
+rank regions. The second half of that was true. The first half assumed the frame had to be the one
+doing the ranking.
+
+**Two endpoints, and they are not alternatives.** `GET /v1/ping/targets` is the NATIVE path: the
+endpoint each target advertises is a UDP echo, which is precisely the measurement a browser cannot
+make, so nothing in that response ranks anything. It stays, and the SDK still exposes it as
+`dedicatedServer.listClusterTargets()` — enumeration, plus each target's coarse `pressure`, which
+gem-api asks clients not to branch on until the refresher that varies it lands.
+
+`GET /v1/regions` is the BROWSER path, published for exactly this purpose: per region, the cluster
+target id and a list of **STUN** endpoints. A Binding request needs no credentials, no lease and no
+match, so a browser can time them at startup and rank by round trip. It takes `AuthenticatedPlayer`,
+so the frame cannot call it — the same boundary that keeps the frame off the notification socket.
+
+### The parent measures; the acceptable clusters cross
+
+```
+   Arcade page                          game frame
+   ───────────                          ──────────
+   GET /v1/regions        (player token)
+   time STUN probes per region
+   keep the close ones ──▶ up to three ids, best first
+                      ──── gem.clusterTarget ────▶  held
+                                                    create()    ──▶ cluster_target_id  (the first)
+                                                    quickJoin() ──▶ cluster_target_ids (all of them)
+                                                    startMatch() ─▶ nothing: the room's own
+```
+
+This is what the native launcher already does for the engine, and putting it on the page rather than
+in the frame is a decision rather than a convenience:
+
+- **It happens once per player session.** Every game the page loads inherits the answer, across a
+  pack swap. In the frame it would be repeated per game and per reload, and each repeat is a fresh
+  round of UDP to every region.
+- **The vector never reaches game code.** A round-trip time to every region is coarse geolocation
+  plus a network fingerprint, and a game frame is third-party code. What crosses is the ids of the
+  clusters close enough to the fastest that the player would not notice the difference — at most
+  three, best first — and nothing else: no timings, no list of the regions that were not close, no
+  `probe_targets_fresh`. Three ids with no timings is continent-level information. The field list
+  and the bound are pinned by a test, because the freeze rule would otherwise permit a `latencyMs`
+  "just for telemetry".
+- **The token the page holds is the one the route wants.** No new credential, no new hole in the
+  frame sandbox.
+
+The publisher-side constraints exist for browser reasons and belong to whoever measures: **at most
+three STUN endpoints per region**, because Firefox degrades past two servers on a single
+`RTCPeerConnection` and the cap is there so a drained node does not blank a region rather than as an
+invitation to probe all three at once; and **IPv4 only**, because WebKit filters IPv6
+server-reflexive candidates without camera or microphone permission, so an IPv6 target would make
+Safari silently never answer and rank that region last on every Apple device.
+
+### A room carries its cluster
+
+**Where a match runs is decided when the room is made, not when the match starts.** `create()`
+names the best cluster, and the room keeps it. `quickJoin()` names every acceptable one: it joins
+only a room whose cluster is in the list — so the players it puts together can all reach that
+server well — and a room it has to make takes the first. `joinByCode()` and `join()` apply no such
+filter; friends play together wherever the host is.
+
+**`startMatch()` then names no cluster at all,** and the match starts where the room is. That is
+what stops a host who inherited a public room from dragging it to their own region by pressing
+Start. The one exception is a room that carries no cluster — made by an older client, or entered
+before the page answered — which has nothing to fall back on, so the SDK names this player's best
+one there.
+
+Nothing means the field is omitted, never sent empty. A sentinel would be refused as an unknown
+cluster instead: the same failure, reported as the caller's mistake.
+
+The frame waits up to two seconds for a first answer, and only when the parent advertised the
+`clusterTarget` capability. That covers the one race there is — a game that enters a room while the
+page is still measuring — and **the grace is spent once per session**, across the create, the
+quick-join and the start, so a parent that advertises and never sends does not put a stall in front
+of every button.
+
+**Passing `clusterTargetId` to `startMatch()` still wins, and it moves the room.** The match starts
+in the cluster you named and, once it has started, the room's later matches start there too. That is
+the override for a region picker. The SDK never second-guesses an id you named: neither recovery
+below runs on one.
+
+### When a cluster refuses
+
+The platform never moves a room on its own. When the cluster a room names stops being usable, the
+host does, and the SDK does it for you:
+
+| What gem-api answers | Where | What the SDK does |
+| --- | --- | --- |
+| `invalid_cluster_target` | `create()`, `quickJoin()` | Waits up to five seconds for the page to send a different list, and tries once more with it |
+| `invalid_cluster_target` | `startMatch()` — the platform does not run the room's cluster | Starts once in this player's best other cluster, naming it, which moves the room |
+| `capacity_unavailable` twice in a row | `startMatch()` | Moves to the next acceptable cluster, once, and keeps waiting there |
+
+**Each of them happens once.** A second refusal is the answer, and it reaches you as the error.
+
+**An automatic start has nobody to answer, so the host's SDK answers it.** When a room's template
+starts the match as it fills to `min_players` and the platform refuses that start, no call is waiting
+to be refused. The host's game gets `matchAutoStartFailed`, carrying the same error code a manual
+start would have had — and for `invalid_cluster_target` and `capacity_unavailable` the SDK then
+starts the match from the host's game itself, which runs the recoveries above. The event's `handled`
+is `true` when it does.
+
+That start is made **once per room until a match begins in it**, and never beside a start already in
+flight. A later refusal reaches the game with `handled: false`, and so does every other code, because
+those are about the build and the same start would meet them again. A game that wants to decide
+passes `createGem({ retryAutoStart: false })`; the event then always says `handled: false`, and
+starting the match yourself runs the same recoveries:
+
+```js
+gem.rooms.on('matchAutoStartFailed', () => gem.rooms.startMatch());
+```
+
+### The degraded cases, and where each one lands
+
+| What happened | What the SDK names | What the player gets |
+| --- | --- | --- |
+| Parent sent the acceptable clusters | the list on quick-join, the first on create | a room near them, with players near them |
+| Parent sent one id, as an older page does | that id, as a list of one | the same, pooled a little more narrowly |
+| Parent measured nothing and sent its `default_cluster_target_id` | that id | a room, not necessarily near |
+| Parent does not advertise `clusterTarget` | nothing | a room that carries no cluster — see below |
+| No clusters configured at all (`default_cluster_target_id` absent) | nothing | nothing to allocate in either way |
+
+The fourth row is the one to be precise about. **A room entered with no cluster pools only with other
+rooms that carry none**: quick-join matches it only for a request that names no cluster either. Its
+automatic start runs in the platform's configured default cluster. A manual dedicated start on it
+must name a cluster, and with nobody resolving one it is refused by name —
+`400 cluster_target_required`. That is the honest outcome rather than a gap. The last row is why: an
+absent `default_cluster_target_id` means no clusters are configured at all, which is local dev and
+integration tests, where no dedicated allocation could have succeeded whatever id was sent.
+
+## 6. P2P
+
+Its allocation already worked here — `start_match` is one route and the room reports whatever protocol
+comes back, so a P2P match allocates and reaches step 3 unmodified, where this flow refuses it.
+
+**One place the two allocations are now told apart, and it is step 1's retry.** A 503 means "no
+capacity" for a dedicated start and "this backend has no P2P" for a peer-to-peer one — so the wait
+above would be spent on a server nothing was ever going to allocate. The refusal's error code says
+which (`capacity_unavailable` against `p2p_unavailable`), and a peer-to-peer start is refused at
+once as `p2p_unavailable`; `rooms-and-matches.md` §4.4 has the mechanism. Nothing else in this flow
+branches on it.
+
+Its _connection_ is now built, and it is [`p2p-and-parties.md`](p2p-and-parties.md). It did not
+fall out of the same shape and it did not try to: a designated host peer rather than a server,
+trickled candidates rather than one gathered offer, a TURN lease, host migration and epochs. Sharing
+the offer/answer nouns is not sharing the flow, and the two `connect` methods are separate for the
+same reason the two refusals are. Separate underneath, and joined above: `gem.match.connect()` is
+the branch between them written once, in the SDK, so the hosting decision stays in
+`game_room_templates` rather than in every game's source.
+
+The one thing worth carrying between them: **the token boundary was never about either transport
+specifically.** Every other route on both paths takes a game-scoped token and is reachable from the
+frame today; only signaling needs the socket. So both carry it over the bridge, under a parent-owned
+template, and the two differ in the message set rather than in the mechanism — which is why the two
+relays share their readers, their socket limits and their per-second budget, and differ in their
+tables.
+
+## 7. Ending a match, and why the client has to let go
+
+**A browser that finishes a match and stays open holds the server it was playing on.**
+
+The obvious diagnosis is that the peers vanished silently and the server never noticed. That is
+wrong, and the correction is worth keeping because it is the reason this fix lives on the client. The
+runtime's departure detection works — measured directly against a real loopback DTLS/SCTP session with
+the client socket pulled out from under it, no close of any kind, departure fires at 30 seconds on the
+shipped configuration. What holds a pod is the opposite case: a tab left open on a **finished** match
+goes on answering ICE consent checks, so the transport is genuinely alive and the player is genuinely
+gone. To the server that is indistinguishable from someone sitting on their turn thinking.
+
+So the teardown is the client's, and the signal for it is the platform's:
+
+1. The game server calls `match_end` when its match is over.
+2. gem-api sends `match_ended` to the room's members on their notification sockets.
+3. The parent relays it as `gem.dedicatedEvent` (`matchEnded`), scoped by game id like any other
+   push on that socket.
+4. The flow closes the session holding that match — the data channel, **the peer connection**, and
+   the signaling seam. Closing the channel alone is not enough: the ICE agent outlives it and the
+   consent checks keep flowing.
+
+Four things follow from that shape and are worth saying out loud:
+
+- **It is not reported as a disconnect.** A drop moves the room's match to `suspended`, from which
+  the SDK's own reconnect policy (since 4.0.0, 2026-09-10) or a `reconnectToMatch()` brings it
+  back; a match that has _ended_ has nothing to reconnect to, so the policy reads the match before
+  its first attempt and raises `matchEnded` instead of chasing it. Only the game's own `close()`
+  shares that suppression, and for the same reason. The session's phases and the policy are
+  [match-session.md](match-session.md).
+- **A game that wants to know asks for `connect({ onMatchEnded })`, or listens for the room's
+  `matchEnded` event.** The callback is called once, with
+  gem-api's reason, immediately before the teardown — so the order observed is "the match ended",
+  then "the channel went away". Without it the only thing a game sees is `channel.onclose`, which is
+  also what a network drop looks like, and the two want opposite screens. The teardown happens either
+  way: this is how the game hears about it, not what makes it happen. `gem.match.connect({ onMatchEnded })`
+  is the same contract on every seat — dedicated, peer, and the host's own loopback.
+- **An offer in flight is refused rather than left to time out**, with `match_ended`. A server that
+  no longer exists will not answer, and the alternative is spending a whole exchange timeout inside a
+  sixty-second credential window to learn a fact the socket already delivered. That refusal is _not_
+  reported as a connection failure, even though it interrupts the handshake — see §4: the platform
+  ended the match, so it already knows.
+- **It only reaches as far as the push does.** A match whose server never calls `match_end` produces
+  no `match_ended`, and this SDK cannot invent one — the client has no way to distinguish "the match
+  is over" from "nobody has moved yet". That case is the server runtime's own liveness to answer, and
+  it is the platform's rather than this SDK's.
+
+**The platform's own answer to that last case is a maximum duration, and it arrives as the same
+push.** Every dedicated match has one — declared per room template in the game's config, between 30
+minutes and 48 hours, and six hours if the template declares nothing. Reaching it ends the match the
+way the game's own server ending it would, so what a client observes is an ordinary `match_ended`:
+the teardown above runs unmodified, `onMatchEnded` is called with the reason, and there is no new
+case for a game to handle. It bounds how long "nobody has moved yet" can go on rather than telling it
+apart from "the match is over" — which is why it is a limit on the match and not a liveness check on
+the client. The contract in full, including what the server itself is given to wind down in, is
+[`server-bundles.md`](server-bundles.md#how-long-your-server-lives).
+
+The peer-to-peer path already did all of this, from `p2p_match_ended`: `P2pSession` closes every link
+it holds, and every link's connection with it. Both paths are pinned by tests, because they now owe
+the same thing and a regression on either would be silent.
+
+## Developing against your own machine
+
+Inside a development tool that can host — it advertises the `localHost` capability, which no
+player-facing embedder carries — the platform can dispatch a dedicated match to a server running
+on the developer's own machine instead of allocating one from the fleet. **Your game's source does
+not participate.** Immediately before starting a match, the SDK asks the embedder for a server for
+the room; the tool spawns your game's own server bundle, registers it with the platform, and the
+match that follows is dispatched to it. A game published to players never runs inside such an
+embedder, so there is nothing to gate and nothing to remove before shipping.
+
+Three things are worth knowing while you develop this way:
+
+- **The ask happens before the match starts, and a refusal arrives as `startMatch()` rejecting —
+  never as a hang.** The two failure shapes are deliberately different. A platform refusal (you are
+  not signed in as a developer on this game, or the room is not on a development channel) is
+  terminal, and retrying sends the same request to the same refusal. A machine that merely could
+  not start the process is retryable, and your tool has the log. Silence is bounded too: an
+  embedder that never answers is given thirty seconds, then the rejection says so. However many
+  times a racing Start button asks, one server is started per room.
+
+- **The winning transport is usually WebSocket, so take the negotiated path.** A locally run server
+  typically offers no WebTransport certificate chain and no WebRTC signaling; the ladder works
+  exactly as [§4](#4-the-connect-sequence) describes and WebSocket wins. That is invisible to a
+  game on `gem.match.connect()` — `link.send`/`link.onMessage` speak one shape whichever rung won —
+  but code that reaches into WebRTC internals breaks here first: `session.channel` and
+  `session.peerConnection` exist **only when WebRTC won**, so a
+  `session.channel.readyState` read that works against the fleet throws on a locally served match.
+  Check `session.transport` before touching either, or better, never touch them.
+
+- **Everything downstream is the real flow.** The dispatch is the platform's own: the join
+  credential, the roster, run reporting and `match_ended` all arrive exactly as this document
+  describes, and your server bundle runs unmodified. What you test locally is what ships, minus
+  the datacentre.