@indiegems/gem-web-sdk 7.4.0 → 7.4.1

package/docs/server-bundles.md

@@ -0,0 +1,1041 @@
+# Writing the server for a dedicated match
+
+What a game publishes as its dedicated server, and how a browser talks to it once the SDK has opened
+the channel. Everything here is game-facing: the lifecycle a server bundle implements, the surface it
+is handed, and the first message on the wire.
+
+The browser half — allocating the match, negotiating WebRTC, getting a channel — is
+[`dedicated-server-flow.md`](dedicated-server-flow.md), and the SDK does all of it for you. This
+document starts where that one ends.
+
+> **Where this text comes from.** The dedicated-server runtime is the platform's own, and it is not
+> something you can read — so the game-facing half of its contract is **copied** here rather than
+> linked, taken from that runtime's documentation and source on 2026-08-13. That sync covers the
+> `roomArgs` settings object (which replaced the removed `gameArgs`/`templateArgs` string channels),
+> game-server token delivery (`apiBaseUrl`/`serverToken`/`onServerToken`), the move from pushed room
+> data to [reads your server makes itself](#what-your-server-reads-at-startup), and the lifespan
+> contract — how long a match may run, and how long a server gets to wind down.
+>
+> Two copies can drift, and no automated check guards this one. **If this text and the runtime
+> disagree, the runtime is right** — report it, and this page is what gets corrected.
+
+## A bundle is required
+
+A game that has published no server package does not get a dedicated server. gem-api refuses the
+match at start — **409, `no_compatible_server`**, which the SDK raises as a `GemApiError` with
+`reason: 'conflict'` — upstream of any allocation, so no pod is ever started to fail later.
+
+This is the contract rather than a limitation. There is no default server behaviour to fall back on
+and no mode of the runtime that runs without game code: "connect players to each other and let them
+sort it out" is what [P2P](p2p-and-parties.md) is for, and it has different properties on purpose.
+
+A server package is a package like any other: upload a version under the `server` platform, then
+assign it to the channel the match will run on
+(`PUT /v1/games/{game_id}/packages/server/channels/{channel}`) — the same path and the same developer
+role as a client build. The runtime resolves whatever that channel points at, downloads it, and
+verifies it against the digest the download endpoint returns before running a byte of it.
+
+## What you publish
+
+**One JavaScript file.** Not an archive, not a directory, not a `package.json` — the runtime writes
+the download to a single path and imports it directly. Anything your server needs must be bundled
+into that file.
+
+|               |                                                                                                            |
+| ------------- | ---------------------------------------------------------------------------------------------------------- |
+| Module format | From the published file's extension: `.mjs` is ESM, `.cjs` is CommonJS, anything else is treated as `.js`  |
+| Runtime       | Node 22, on a distroless image — no shell, no package manager, no network fetch of dependencies at runtime |
+| Size ceiling  | 256 MB                                                                                                     |
+| Environment   | `PATH`, `NODE_ENV=production`, `HOME`, and nothing else                                                    |
+
+That environment is deliberate and it is worth knowing why, because it is the one thing that
+surprises people. Your bundle's process is started with an **explicit** environment rather than
+inheriting the one around it, so there is nothing to read out of `process.env` — no platform
+configuration, and none of yours either. Everything arrives on the object the runtime hands your
+`init` instead: the room's [settings object](#room-args), and — for calling gem-api — a **derived,
+game-scoped token** that [the SDK wires up for you](#calling-gem-api-from-the-bundle). No
+platform-wide credential ever enters your process; the derived token is the whole reason it does not
+have to.
+
+## Where the server half of the SDK comes from
+
+**From the package, not from a URL.** The unified CDN artifacts (`gem-web-sdk.min.js`,
+`gem-web-sdk.sdk.js`) do carry `defineServer` — that is what lets
+[a player's browser host the same bundle](#the-same-bundle-hosted-by-a-player) — but a dedicated
+bundle is compiled under Node, where imports resolve from the **package, installed from npm**:
+your bundler compiles `@indiegems/gem-web-sdk/sdk` into the one file you
+publish, and nothing is fetched where the server runs.
+
+**It is the same one dependency the browser half installs.** If you followed
+[the getting-started page](getting-started.md#3-add-the-sdk) it is already in your
+`package.json` and there is nothing to add here — one install, in `dependencies`, and the
+same `@indiegems/gem-web-sdk/sdk` import from every seat. That page owns the install and is
+the only place it is written out.
+
+**Publish your client build and your server bundle at versions on the same compatibility
+line.** The two halves of one game must agree about the wire, and nothing checks that for
+you.
+
+To check the download yourself: the package npm serves is, byte for byte, the file each release
+also publishes on its download host, with the hash beside it:
+
+```bash
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v7.4.1/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v7.4.1/gem-web-sdk.tgz.sri
+openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
+```
+
+The last line prints what the `.sri` file holds, without its `sha384-` prefix.
+
+**Know what that check does and does not prove.** The `.sri` is served from the same place as the
+package file, so it catches a corrupted, truncated or cached-wrong download — not a compromised origin,
+which would serve you a matching pair. It is a checksum. Do not compute your own hash from a copy
+you already downloaded either: that certifies whatever you downloaded, which is the thing the check
+exists to test. **The control that actually pins bytes for you is the lockfile**, and it does that
+without you doing anything.
+
+Neither npm nor the download host lets a published version be overwritten, so a version you pin
+keeps serving what you checked.
+
+**`dependencies` is the right home** — your bundler compiles the SDK into the file you upload, so
+an install that skips dev dependencies must still resolve it. **Pin one version** across the builds
+you publish.
+
+### The package ships minified, and your stack traces will show it
+
+The JavaScript in the package is compiled and minified, so frames that fall inside the SDK carry
+one- or two-letter names and a column offset on line 1 rather than a function name and a line:
+
+```
+    at Module.P (node_modules/@indiegems/gem-web-sdk/dist/gem-web-sdk.sdk.js:1:43903)
+```
+
+Your own frames are unaffected — they come from your bundle, not ours. Two things a crash usually
+turns on still work normally: every error the SDK raises itself carries its full written message,
+and the types you build against are complete.
+
+The case worth knowing is a `TypeError` whose text names one of our identifiers — `t is not a
+function` rather than `setup is not a function`. That is a mangled name, not a variable of yours.
+Read the message the SDK wrote and the frames in your own code; if neither explains it, quote the
+whole trace and the version you pinned when you ask us.
+
+### Building the one file
+
+Everything your server imports is compiled into the file, because the runtime image has no
+`node_modules` and fetches nothing. One command does it:
+
+```bash
+npx esbuild src/server/main.js --bundle --platform=node --format=esm \
+  --target=node22 --outfile=server-dist/my-game-server.mjs
+```
+
+- `--bundle` inlines the SDK and every other import.
+- **The output extension selects the module system** the runtime loads it under — `.mjs` is ESM,
+  `.cjs` is CommonJS, anything else is treated as `.js` — so `--format` must agree with the
+  extension you choose.
+- `--platform=node --target=node22` matches the runtime the platform runs.
+- Emit into a directory of its own: the upload below takes a **directory**, and its contents are
+  the package.
+
+### Publishing it
+
+```bash
+gemctl build upload --dir server-dist --platform server --version 0.4.7 \
+  --server-size small --server-protocol webrtc_dedicated
+```
+
+⚠️ **`--server-size` and `--server-protocol` decide whether the package can ever allocate, and both
+are immutable after upload.** Size is required and `small` is the only class a fleet is deployed
+for. A browser game must declare `webrtc_dedicated` — an undeclared protocol resolves to UDP at
+allocation, which a browser cannot reach — and neither value can be added to an already-published
+version: the failure surfaces at the players' first match, not at publish. The version you pass
+must land on the same compatibility line as the client build it serves
+([`platform-rules.md`](platform-rules.md#4-the-compatibility-line)).
+
+## The game half
+
+**Write your bundle with `defineServer`.** It is the shape this page uses throughout, the shape the
+published example uses, and the one to reach for unless you have a specific reason not to:
+
+```js
+import { defineServer } from '@indiegems/gem-web-sdk/sdk';
+
+export default defineServer((gem) => ({
+  init() {}, // once, before any player
+  join(playerId, meta) {}, // a verified player connected
+  leave(playerId, meta) {}, // their channel closed
+  message(playerId, data, isText, meta) {}, // data: string when isText, else Buffer
+  shutdown() {}, // the match is ending
+}));
+```
+
+Those five methods are the **platform's** contract rather than this SDK's: a bundle's default export
+is called **once** and returns an object with any of them. All are optional, and each may be `async`
+— the runtime awaits it before delivering the next event. `defineServer` returns exactly that object,
+so nothing described on this page is a wrapper's behaviour you would lose by assembling it yourself.
+
+What it saves you is the wiring every bundle otherwise repeats. One `gem` carries both halves of the
+job — the runtime surface your match runs on, and the gem-api surface your results go through — so
+the five methods share one scope, the runtime's `host` never has to be captured in a variable of your
+own, and a misspelled `mesage` is a build error rather than a handler that is silently never called.
+[What `gem` carries](#what-gem-carries) is the full list.
+
+**Assembling it by hand is still supported, and is the exception.** `createMatchServer(host)` builds
+the same `gem` from inside an `init` you wrote yourself, and `createGemServer(host)` builds only the
+gem-api half for a bundle that wants nothing else. Both are exported and neither is deprecated — they
+are there for the bundle that has a reason to own its own lifecycle object. If you do not have one,
+use `defineServer` and read the rest of this page as written.
+
+### The same bundle, hosted by a player
+
+The module you write on this page is not tied to the dedicated fleet. When a room template declares
+`match_type: "p2p"`, the platform allocates no pod — the room's host **player's browser** runs the
+match — and the SDK runs **this same bundle** there, over the P2P connections it opens for you.
+Nothing about the lifecycle changes: the same five methods, delivered one at a time in the same
+order, the same `gem` surface.
+
+Wire it from your browser code with two calls, and make them unconditionally — every player, every
+match:
+
+```js
+import server from './server-logic.js'; // the same default export you publish
+
+const hosting = await gem.match.serve(server); // runs it HERE only if this player must host
+const link = await gem.match.connect(); // the authority, whoever that turned out to be
+```
+
+`serve` answers which case happened — `dedicated` (the platform runs your published bundle), `peer`
+(another player's browser is hosting), or `listen` (your bundle is now running in this browser).
+`connect` resolves the same link shape in all three: the dedicated server's negotiated transport,
+the hosting peer's data channels, or — on the host itself — an in-process loopback to the bundle
+`serve` started. **Which case a match takes is a fact of your room template, not of your source**,
+so retuning a game between dedicated and player hosting is a config change.
+
+One fact does not fit in `onClose`: whether the link **dropped** or the **platform ended the
+match**. Since the SDK's 4.0.0 release (2026-09-10) a drop is the SDK's to recover — the
+connection goes `suspended`, the room raises `matchSuspended`, and the policy re-dials on its own —
+so `onClose` fires only when the match is over or the attempts ran out. Ask for the end on
+`connect`, on every seat, and key nothing on `onClose`:
+
+```js
+const link = await gem.match.connect({
+  onMatchEnded: (reason) => {
+    showMatchOver(reason); // the platform's reason: 'explicit', 'expired', 'stale_cleanup', …
+  },
+});
+link.onClose(() => releaseTheScreen()); // cleanup only; never "the match ended"
+```
+
+`onMatchEnded` is called once, with the platform's reason, immediately **before** the connection
+closes — the same contract as `gem.dedicatedServer.connect({ onMatchEnded })`. It is not called
+for your own `close()`. The room's `matchEnded` event carries the same fact with `roomReopened`
+beside it; the phases, the reason vocabulary and the reconnect policy are
+[match-session.md](match-session.md). On a dedicated connection `link.transport` also names which
+wire won the ladder (`webtransport`, `webrtc` or `websocket`); it is absent on `p2p` and
+`loopback`.
+
+**Ending a match from this seat.** The handle `serve` returned is the authority when `mode` is
+`listen`: `hosting.end()` ends the match for everyone — the platform first, then your bundle's
+`shutdown` with `match_ended` / `explicit` — and `hosting.leave()` hands the match to another host
+without ending it. Both are refused on any other `mode`.
+
+Three things are honestly different on a player-hosted match, and your bundle can read
+`gem.sizeClass` (`listen_host`) if it needs to know:
+
+- **The credential is the hosting player's own play token**, not a game-server token. The calls on
+  `gem.api` are the same calls; gem-api is the authority on what each credential may do, so an
+  operation the play token does not cover fails at the platform with the same errors your `catch`
+  already handles.
+- **`kick(playerId, reason)` drops the reason** — the P2P kick carries none. The kick itself works.
+- **`gem.log` / `gem.warn` reach the game's own log sink**, not the platform's match logs — there is
+  no platform process to own a log stream. That sink is the browser console unless `createGem` was
+  given a `log` of its own, and each line is prefixed `[gem host]`.
+
+The `meta` arguments are what a **newer** runner knows beyond the id and the bytes, and they are
+optional end to end — an older runner passes nothing, so default before use, the same rule as every
+other version-skew member on `host`:
+
+| Callback  | `meta` may carry                                                                                                                                                                                                         |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `join`    | `playerNumber` — the seat the runtime assigned; `transport` — which transport carried the player (`webrtc`, `webtransport`, `websocket`; on a listen host `loopback` for the hosting player and `webrtc_p2p` for a peer); `rejoin: true` when the platform has met this player in this match before — restore what you kept for them; `superseded: true` when their earlier connection was still attached as this one landed, so the `leave` you just heard (its `cause` is `superseded`) was the platform swapping links, not the player leaving. Both keys are absent, not `false`, otherwise, and both come from a dedicated runtime and a listen host alike |
+| `leave`   | `cause` — why the connection ended, as the runtime saw it; `superseded` means the same player is already back on a newer connection and the `join` that says so follows at once                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `message` | `reliable` / `ordered` — [the delivery class the sender asked for](#delivery-classes-the-flags-are-the-senders-request); `sessionId`; `playerNumber`                                                                     |
+
+A complete working example is [`examples/server-bundle/echo.mjs`](../examples/server-bundle/echo.mjs)
+— a chat relay in one file, exercising every lifecycle method, the startup reads and most of the
+runtime surface. This repo's suite drives it against the contract below, so it is a starting point
+rather than a sketch.
+
+### The host
+
+The runtime hands its surface over at `init` and nowhere else. `defineServer` takes it from there and
+gives you `gem`, which carries the table below with three changes and nothing else moved:
+
+- `matchId`, `gameId`, `channel` and `gameRoomId` are grouped as **`gem.identity`**;
+- `profile` answers `null` rather than `undefined`, and wraps the display name — [below](#what-gem-carries);
+- the three **token members are consumed by the SDK** rather than passed on, because
+  [wiring them into gem-api](#calling-gem-api-from-the-bundle) is the whole of what they are for.
+
+Everything else keeps its name, so `players()` in this table is `gem.players()` in your bundle and
+`send` is `gem.send`. A bundle assembling its own lifecycle captures the `host` argument that `init`
+is called with and reads the table unmodified. Neither spelling is valid before `init` has run.
+
+|                                                  |                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `matchId`                                        | The match this process is serving                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `gameId`                                         | Your game                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `channel`                                        | The release channel the match is running on — the same one whose `server` package supplied this bundle                                                                                                                                                                                                                                                                                                                                                            |
+| `gameRoomId`                                     | The game room backing this match — the id the [startup reads](#what-your-server-reads-at-startup) are about. `undefined` under an older runtime image, so default before use, the same way the token members are handled                                                                                                                                                                                                                                          |
+| `sizeClass`                                      | Which fleet size class this pod was allocated from                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `roomArgs`                                       | The room's **settings object** — typed values, not a string. [Below](#room-args). **Deprecated, still delivered:** the room-args read through the SDK is its replacement. Delivery is the runtime image's call, not this package's — [the deprecation policy](deprecation-policy.md#3-runtime-delivered-pushes-are-a-separate-question)                                                                                                                           |
+| `roster`                                         | The room's members **at allocation time**, as player ids — a snapshot the platform never revises, and it may be empty. **Deprecated, still delivered:** the room read returns the live membership, with display identities the snapshot never had. Delivery is the runtime image's call, not this package's — [the deprecation policy](deprecation-policy.md#3-runtime-delivered-pushes-are-a-separate-question)                                                  |
+| `players()`                                      | The player ids connected right now, as a fresh array. Runtime truth, and **not** deprecated — see [members versus players](#members-versus-players)                                                                                                                                                                                                                                                                                                               |
+| `profile(playerId)`                              | `{ displayName, displayTag, discriminator }`, resolved by the platform from the match roster; `undefined` while the fetch is pending, or when the player has no display name. **Deprecated, still delivered:** the room read carries display identity plus `role`, `is_ready` and `avatar_icon_id`. Delivery is the runtime image's call, not this package's — [the deprecation policy](deprecation-policy.md#3-runtime-delivered-pushes-are-a-separate-question) |
+| `playerNumber(playerId)`                         | The 1-based seat number the runtime assigned a connected player, or `undefined` — for an id it has not seated, and equally on an older runtime image that has no such member                                                                                                                                                                                                                                                                                      |
+| `send(playerId, data, options)`                  | To one player. `data` is a string (sent as text) or a `Uint8Array`/`Buffer` (sent binary). `options` is `{ reliable, ordered }`, both defaulting true — [the delivery class you ask for](#delivery-classes-the-flags-are-the-senders-request). An older runner ignores the extra argument harmlessly                                                                                                                                                              |
+| `broadcast(data, { except, reliable, ordered })` | To every connected player, optionally excluding one, with the same delivery options                                                                                                                                                                                                                                                                                                                                                                               |
+| `kick(playerId, reason)`                         | Disconnect a player                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `log(message)`                                   | An info line in the match's logs                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `warn(message)`                                  | A warning line                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `apiBaseUrl`                                     | The backend's API origin. [Below](#calling-gem-api-from-the-bundle)                                                                                                                                                                                                                                                                                                                                                                                               |
+| `serverToken()`                                  | The current game-server token, as `{ token, expiresAt }`. [Below](#calling-gem-api-from-the-bundle)                                                                                                                                                                                                                                                                                                                                                               |
+| `onServerToken(listener)`                        | Subscribe to token replacement; returns an unsubscribe function. [Below](#calling-gem-api-from-the-bundle)                                                                                                                                                                                                                                                                                                                                                        |
+
+**Use `log`/`warn`, not `console.log`.** The bundle's stdout is the protocol channel between it and
+the platform half of the runtime. A line written directly to it is not lost — it is reported as "the
+game runner wrote a non-protocol line" — but it arrives as a warning about your bundle rather than as
+the log you wanted.
+
+### Delivery classes: the flags are the sender's request
+
+A newer runtime serves a match over more than one transport — WebRTC, WebTransport, WebSocket — and
+the transports differ in what they _can_ deliver. The `reliable`/`ordered` options on `send` and
+`broadcast`, and the same fields on `message`'s `meta`, are how both halves talk about it, and one
+rule makes them safe to use unconditionally:
+
+**The flags name what the sender ASKED for, not what the network did.** A transport upgrades
+delivery when it has nothing weaker — a player connected over WebSocket receives an
+unreliable-flagged message reliably, because TCP has nothing else — and the flags still cross
+untouched, so the receiver always knows the ask. Both default true, which is the only reading every
+transport honours exactly.
+
+Use `{ reliable: false, ordered: false }` for state that is superseded by the next update anyway —
+position snapshots, effect triggers — and leave the defaults for anything a player would miss:
+
+```js
+message(playerId, data, isText, meta) {
+  // meta?.reliable === false means the SENDER marked this expendable.
+  gem.broadcast(data, { except: playerId, reliable: meta?.reliable !== false });
+}
+```
+
+An older runner ignores the options argument harmlessly and passes no `meta`, so a bundle written
+this way runs unchanged on both. Nothing about the envelope changes either: the join/welcome
+exchange below is identical on every transport, and everything after the welcome is still yours.
+
+### Room args
+
+`gem.roomArgs` is the room's **settings object**, and that object is the sole configuration
+channel. (Older revisions of this runtime carried two opaque strings, `gameArgs` and `templateArgs`;
+both were removed along with the platform's `game_args`/`template_args` — everything they carried
+now travels through the room's schema.) The push itself is **deprecated, still delivered**: today
+your server [reads the same object itself](#what-your-server-reads-at-startup) through the SDK, and
+the push survives as a compatibility fallback for bundles that have not moved yet. **How long it
+keeps arriving is not this package's to say** — the dedicated-server runtime image delivers it, so
+that answer is made where the image is built. [The deprecation
+policy](deprecation-policy.md#3-runtime-delivered-pushes-are-a-separate-question) carries both
+halves: the property on the type is package surface, and delivery is the image's.
+
+The shape is declared by you, up front: the game's published config declares a schema
+(`room_args_template`) on the room's template — each entry's type, allowed values, default, and
+whether you fixed the value or left it for the room's owner to choose — and the room's owner fills
+in what they were allowed to, through gem-api. The values are frozen at the moment the match
+starts, and every one of them was type- and range-checked against your schema before it could reach
+the pod.
+
+**It is an object, not a string.** Values arrive already typed as the schema declared them, so
+nothing on the path parses them and your bundle should not either:
+
+```js
+const settings = gem.roomArgs ?? {}; // owner's choices, bounded by your schema
+const rounds = settings.rounds ?? 3; // already a number
+```
+
+- **`undefined` is not `{}`.** `roomArgs` is `undefined` when the room's template declares no
+  schema, which is deliberately distinguishable from a schema whose entries are all unset. An older
+  runtime image, or an older room, also reads as `undefined` — default before use.
+- **It is frozen at match start.** Nothing changes it for a live match.
+- **It is not a secret channel.** Every room member can read every value, including the ones you
+  fixed. Nothing whose safety depends on players not knowing it belongs here — that is what a
+  server holding authority is for.
+- **The browser sees the same values**, so a dedicated bundle and a listen-host can read one
+  published shape. It reads them off the room itself — `room.roomArgs`, on the v2 room read —
+  not from `settings`, which is a different, unvalidated field and does not carry them;
+  `rooms-and-matches.md` §5a is the browser half. The trust differs — the bundle runs on the
+  platform, a P2P host is a player's machine — but the data does not.
+
+A bundle can also read the object from gem-api rather than wait for the push: the room read
+carries it and admits a game-server token, and `gem.room.args()` is that object read off your own
+room, with a 404 `room_args_not_defined` when the template declares no schema. One read at startup is authoritative
+for the whole match, because the object is write-locked while a match runs — [What your server
+reads at startup](#what-your-server-reads-at-startup) is the full contract.
+
+### Calling gem-api from the bundle
+
+The bundle gets a **game-server token** for its own gem-api calls, delivered and kept fresh by the
+platform half — so a server can hold real authority: write a save, grant an item, move a
+progression, end the match, all from code players cannot reach.
+
+Three members on `host` carry it:
+
+|                           |                                                                                                                                                                                                                                                                     |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `apiBaseUrl`              | The backend's API origin. `undefined` under an older runtime image; so is everything else here, so default before use                                                                                                                                               |
+| `serverToken()`           | `{ token, expiresAt }` (`expiresAt` in unix seconds), or `undefined`. Read it **per request**: the platform half replaces the token well before expiry, so the current value is always the right one and your bundle never refreshes, decodes or schedules anything |
+| `onServerToken(listener)` | Called with `{ token, expiresAt }` immediately if a token is already held, and again on every replacement. Returns an unsubscribe function. This is the hook an SDK token source wires itself to; a bundle reading `serverToken()` per request never needs it       |
+
+The first token is already on `host` when your `init(host)` runs; replacements arrive on the
+platform half's own schedule (the token lives 15 minutes and is re-delivered roughly two minutes
+before it would expire).
+
+**Use the SDK rather than hand-rolling fetch.** The same package that serves the browser ships a
+server entry, so both halves of your game share one set of wire types:
+
+```js
+import { defineServer } from '@indiegems/gem-web-sdk/sdk';
+
+export default defineServer((gem) => {
+  const saves = new Map();
+
+  return {
+    async leave(playerId) {
+      // Server-authoritative persistence: the player's client never sees a write path.
+      const state = saves.get(playerId);
+      if (!state) return;
+      const grant = await gem.api.requestSaveUploadUrl('players', playerId, 'match-state', {
+        size_bytes: state.byteLength,
+        content_type: 'application/octet-stream',
+      });
+
+      // SEND what `grant.upload_headers` NAMED, through a list of what you are
+      // willing to send. Storage requires these and the grant is the only thing
+      // that knows which — see below, including why this is a check and not a
+      // spread.
+      const headers = { 'content-type': 'application/octet-stream' };
+      for (const [name, value] of Object.entries(grant.upload_headers ?? {})) {
+        // By name AND by value: a header you did not expect does not go on a
+        // request to someone else's host, and neither does one whose value is
+        // not a string.
+        if (name.toLowerCase() !== 'x-ms-blob-type') continue;
+        if (typeof value !== 'string') continue;
+        headers['x-ms-blob-type'] = value;
+      }
+
+      // TRY THE UPLOAD TWICE. A keep-alive connection the other side closed
+      // while it sat idle fails with no status at all, and nothing underneath
+      // re-sends it. The same bytes to the same signed URL are the same blob,
+      // so repeating this hop is safe — a REFUSAL is not retried, only a
+      // connection that reached nothing.
+      let upload;
+      for (let attempt = 1; ; attempt++) {
+        try {
+          upload = await fetch(grant.upload_url, { method: 'PUT', headers, body: state });
+          break;
+        } catch (error) {
+          if (attempt === 2) throw error;
+        }
+      }
+      // CHECK IT. Finalizing an upload that answered 400 stores nothing and
+      // reports success, which is the failure this whole section is about.
+      if (!upload.ok) throw new Error(`save upload answered ${upload.status}`);
+
+      // Nothing is stored until this returns. An upload that is never finalized
+      // is staged and swept, and the player's save stays whatever it was.
+      await gem.api.finalizeSaveUpload('players', playerId, 'match-state', {
+        session_id: grant.session_id,
+      });
+    },
+    async shutdown() {
+      await gem.match.end(); // a server-authoritative match ends when the server says so
+    },
+  };
+});
+```
+
+**`grant.upload_headers` is not optional.** The upload goes to object storage, not to the
+platform, and what storage requires on that `PUT` is not the same everywhere — one storage backend
+refuses the write without `x-ms-blob-type: BlockBlob` and answers `400 MissingRequiredHeader`,
+another requires nothing and sends you an empty object. Which one your save reaches is not
+something a bundle can see, so hardcoding either is right only by luck and sending neither fails
+outright.
+
+Send what the grant names — and **only** what you are willing to send. Spreading the object
+wholesale puts whatever the platform names onto a request your server makes to a host it did not
+choose, which admits headers that change what the request _does_ rather than how it is framed. The
+browser half of the SDK refuses that for the same reason, and a server bundle runs with more
+authority than a browser, not less. There is no wrapper on the server side to do this for you, so
+this example is the whole of the guidance.
+
+It previously wrote that hop as `// ... PUT the payload to grant's signed URL ...` and left the
+headers to the reader, which is the omission worth naming: the browser SDK made the same one in
+code, and saves could not store a byte from a browser for three releases while its tests stayed
+green.
+
+A server bundle meets no browser preflight on this request, so the header is the only part of that
+history which reaches it.
+
+**Only the middle hop needs a retry you write.** The two `gem.api` calls go through the SDK's
+client, which already re-sends what is safe to re-send — and asking for an upload URL is safe,
+because it stores nothing and a second ask is a second URL. Finalizing is not, and the SDK does not
+retry it: that hop is where the save becomes the player's, so repeating one that may already have
+been applied is a decision for you rather than for the SDK. The `PUT` in between leaves the platform
+and inherits none of that, which is why the example above loops around it.
+
+A complete, runnable version of this — with the slot's access rules, the room template that makes a
+dedicated server exist at all, and a real match's logs — is
+[`examples/server-saves/`](../examples/server-saves/README.md) in the SDK repository. It refuses the
+upload outright where the snippet above merely skips an unexpected header, because a grant naming
+something else is a platform bug worth surfacing rather than working around.
+
+The setup function runs once, before the match starts, and the object it returns is your lifecycle —
+so a `const` declared there is state your five methods share. The gem-api half is built for you as
+the runtime hands the host over, which is also where a runtime image too old to deliver tokens is
+refused: at startup, and not on your first call.
+
+#### Typing your own helpers against gem-api's shapes — `3.0.0` moved this
+
+**If you only call `gem.api.*` and let TypeScript infer, nothing here affects you.** This is about
+writing a gem-api response type down by name.
+
+Until `3.0.0`, `@indiegems/gem-web-sdk/server` re-exported the whole generated client — 145
+declarations — from its top level. It no longer does. The entry now exports a named list: the server
+API itself, the errors, the token and transport types, and the types its own signatures expose.
+
+**It moved 95 types AND 50 functions.** If you imported an operation function —
+`getEntityInventory`, anything in the table below — directly from `@indiegems/gem-web-sdk/server`,
+that is a build break, not just a typing one. Everything is still published, one level down:
+
+| was                                                                         | now                                         |
+| --------------------------------------------------------------------------- | ------------------------------------------- |
+| `import type { ItemInstanceResponse } from '@indiegems/gem-web-sdk/server'` | `…from '@indiegems/gem-web-sdk/server/api'` |
+| `import { getEntitySave } from '@indiegems/gem-web-sdk/server'`             | `…from '@indiegems/gem-web-sdk/server/api'` |
+
+So the fix is an import line, not a port. The deep path exists precisely so that narrowing the top
+level takes nothing away — and a second import is the honest price for reaching generated internals,
+which change when gem-api's document changes rather than when this SDK decides something.
+
+⚠️ **`/server/api` is a subpath export**, so your `tsconfig.json` needs `"moduleResolution":
+`"bundler"`or`"node16"`. On the older `"node"`resolution it fails as`Cannot find module`, which
+reads as a missing package rather than a config setting.
+
+**Two types genuinely improved rather than moved.** `ClientOptions` — the options for the
+`GemClient` this entry exports as a constructible class — and `HostTokenSourceOptions` were never
+exported at all, under the wildcard or before it, so a bundle could call those and had no way to
+write down what they took. Both are exported now.
+
+**The break is confined to `/server`.** The major bump takes the whole package to `3.0.0` because
+that is what package-level semver means, but nothing changed for `@indiegems/gem-web-sdk` or
+`@indiegems/gem-web-sdk/game`.
+
+That wiring binds your `game_id` and `channel` on every request (from the allocation — your code
+never types either, in a path or a query) and maps failures into the SDK's closed error set
+(`GemApiError.reason`). The callable surface, `gem.api.*`, is **generated from gem-api's own OpenAPI
+document**, so the call shapes provably match the contract:
+
+| Area                      | Operations                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Saves                     | `listEntitySaves`, `getEntitySave`, `deleteEntitySave`, `requestSaveUploadUrl`, `finalizeSaveUpload`                                                                                                                                                                                                                                                                                                                                 |
+| Settings                  | `listEntityGameSettings`, `getEntityGameSetting`, `putEntityGameSetting`, `deleteEntityGameSetting`                                                                                                                                                                                                                                                                                                                                  |
+| Inventory                 | `getEntityInventory`, `getEntityCurrency`, `getEntityInventoryItem`, orders (`createEntityOrder`, `createEntityBatchOrder`, `simulateEntityOrder`, `listEntityOrders`, `getEntityOrder`), progressions (`listEntityProgressions`, `getEntityProgression`, `addEntityProgression`, `maxEntityProgression`, `resetEntityProgression`, `claimEntityProgressionRewards`), recipes (`executeEntityRecipe`, `getEntityRecipeUsage`, `getEntityRecipeAvailability`) |
+| Loot                      | `getDropRates`                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| Leaderboards              | `getLeaderboard` (the whole board — seed a match from current ranks), `getEntityLeaderboard` (one entity's own runs, best first, with its personal best — the read for deciding a reward from what the player actually did). Not `getFriendLeaderboard`: that view is per viewer, so a credential with no player identity is refused                                                                                                 |
+| Transfers                 | `listTransfers`, `initiateInventoryTransfer`, `getTransferDetails`, `acceptTransfer`, `cancelInventoryTransfer`, `rejectTransfer`                                                                                                                                                                                                                                                                                                    |
+| Platform-funded purchases | `getPurchaseCatalog` — the catalog read only. A **player client** may use `gem.me.mutations.purchase` for a direct platform-currency order because its token fixes the player, game and channel. A dedicated server token names no player and cannot start one; have the player's client initiate it. |
+| Game rooms                | `getGameRoomV2`, `updateGameRoomV2`, `getRoomArgs`, `putRoomArgs`, `listGameRooms`, `closeGameRoom`, `kickPlayer`, `transferHostV2` — the reads pre-bound to your own room as `gem.room.get()` / `gem.room.args()`. [Below](#what-your-server-reads-at-startup)                                                                                                                                                                      |
+| Game config               | `getChannelAssignment` — which config version your server's own channel is running, and a short-lived signed URL for that version's JSON. Pass `gem.identity.channel`: the read is fenced to your own game and channel |
+| Room templates            | `listResolvedTemplates`, `getResolvedTemplate`                                                                                                                                                                                                                                                                                                                                                                                       |
+| Events                    | `listEvents`, `getEvent` — reads only; creating and scheduling events is a developer surface                                                                                                                                                                                                                                                                                                                                         |
+| Showcase                  | `getPlayerGameProfile`, `getShowcaseValue`, `putShowcaseValue`, `deleteShowcaseValue` — a player's display values. A server reads a slot that declares `access_game_server_read` and writes or clears any player's value in one that declares `access_game_server_write`; a slot without the flag refuses it |
+| Voice                     | `createSession`, `deleteSession`, `adminAction`                                                                                                                                                                                                                                                                                                                                                                                      |
+| Analytics                 | `ingestAnalyticsEvents` — prefer `gem.analytics`, which queues, batches, attributes each event to a player and reports refusals; this is the bare request underneath it                                                                                                                                                                                                                                                              |
+| Functions                 | `invokeFunction` — prefer `gem.functions`, which sends your input, decodes the answer and reads your function's own error text; this is the bare request underneath it                                                                                                                                                                                                                                                               |
+| Challenges                | `listChallenges` — prefer `gem.challenges`, which requires the player whose period you mean, since a read that names nobody is answered in UTC, and reads each row defensively; this is the bare request underneath it                                                                                                                                                                                                               |
+
+Entity operations take `entity_type` (`'players'` or `'characters'`) and the target's id — the
+proxy path, a game-server acting **on** a player. Conditional reads return the SDK's
+`VersionedResponse` and writes take `ifMatch`, so the ETag concurrency model survives generation.
+
+**Which operations are here, and why not others.** gem-api declares a `game_server_token` security
+scheme on the routes that accept one, so this table is derived from its document rather than
+guessed. What it leaves out, it leaves out on purpose: calls the **runtime** owns (below), and the
+ones the local runner owns when you serve a match from your own machine; routes whose own
+description refuses a server's token, such as a player's purchase receipt and the run submission a
+serverless function makes outside any match; surfaces that belong to a person rather than to a
+running match — creating or activating an event needs an Owner or Admin, and a bundle has neither;
+and routes the platform has **superseded itself**, where
+an older room read and an older roster read are both replaced by the v2 room read above, and the
+older path spellings are kept beside them as deprecated aliases. That last group takes nothing
+away: every replacement is on the table.
+
+Voice is worth calling out: those three are declared for game-server tokens and **nothing else**,
+so allocating and tearing down a match's voice rooms is a bundle's job by design — `createSession`
+at match start, `deleteSession` at match end, `adminAction` for mute/move/disconnect.
+
+**What the token is, exactly.** A gem-api access token naming your game's server identity for this
+game + channel. It is **game-wide, not match-wide**: gem-api will act on any player of your game
+with it, not only the players on this match's roster. That breadth is intended rather than
+provisional, so build on it — the roster is a discipline you keep, not a fence the token enforces.
+Address players by the ids the runtime verified (`join()`, `gem.players()`).
+
+**What it is not.** A platform credential. Nothing platform-wide ever enters your process; the
+derived token is why it does not have to.
+
+Two more rules of the road:
+
+- **The runtime owns the match lifecycle calls it already makes.** Match heartbeats, allocation
+  readiness, signaling tickets and the match-roster read are the platform half's job; the SDK's
+  server surface deliberately does not expose them. You lose nothing by that: `gem.room.get()`
+  returns a strict superset of the roster — every member with display identity, plus `role`,
+  `is_ready` and `avatar_icon_id` the roster never carried. `gem.match.end()` is the one
+  lifecycle call that is yours — it is how a server-authoritative game finishes — and even there
+  the platform half sends the request, carrying the proof that this server is the one allocated
+  to the match. There is no raw end-match operation on `gem.api`, and on a platform image too old
+  to send the end for you, `gem.match.end()` throws rather than sending one without that proof.
+- **Never write to `process.stdout`.** It is the protocol pipe to the platform half. The SDK's
+  server entry never logs for this reason; your code uses `gem.log`/`gem.warn`.
+
+### What your server reads at startup
+
+Room data used to arrive only as a push: the platform half wrote `roomArgs`, `roster` and the
+profile cache into your process at match start, and what it did not push you could not know. That
+paradigm is being retired. Your server now holds a token that can **read its own room**, so the
+contract is pull-shaped: you fetch what you need, when you need it, and the pushes survive only as
+a compatibility fallback for bundles that have not moved.
+
+The lifecycle contract, in one table:
+
+| What                                              | Call                                                | When                                                                                            | Changes mid-match?                                                                                               | On failure                                                                                                                                                                                               |
+| ------------------------------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The room — status, membership, display identities | `gem.room.get()`                                    | In `init`, and again when [`join` delivers an id you do not recognise](#members-versus-players) | **Yes** — members join and leave, hosts transfer, and the platform never revises a push to tell you              | Retry and degrade — run the match with what you have. A room read failing is **never** a reason to abort a match                                                                                         |
+| Room args — the settings object                   | `gem.room.args()`, or `room_args` off the room read | Once, in `init`                                                                                 | **No** — the object is write-locked while a match runs, so the startup read is authoritative for the whole match | 404 `room_args_not_defined` is the **normal** answer for a template that declares no schema — distinct from an empty object, and not an error to retry. Anything else: retry, then fall back to defaults |
+| Who is connected to this process                  | `gem.players()`                                     | Whenever you need it — it is a local, current array                                             | Yes, and it is always current                                                                                    | It cannot fail; it is runtime state, not a network call                                                                                                                                                  |
+
+`gem.room` is the room reads pre-bound to your own room's id, which the runtime delivers as
+`gem.identity.gameRoomId`. Under an older runtime image that id is `undefined` and `gem.room` is
+absent — check before use — and the deprecated pushes are your fallback on a pod running one:
+
+```js
+import { defineServer } from '@indiegems/gem-web-sdk/sdk';
+
+export default defineServer((gem) => {
+  let seats = [];
+  let settings = {};
+
+  return {
+    async init() {
+      if (gem.room) {
+        const [room, args] = await Promise.all([
+          gem.room.get(), // members, status, display identities
+          gem.room.args().catch((error) => {
+            if (error.reason === 'not_found') return null; // template declares no schema — normal
+            throw error;
+          }),
+        ]);
+        if (room.modified) seats = room.body.members;
+        settings = args?.room_args ?? {};
+      } else {
+        // Older runtime image: no room id delivered. The deprecated pushes still work.
+        seats = gem.roster ?? [];
+        settings = gem.roomArgs ?? {};
+      }
+    },
+  };
+});
+```
+
+**That fallback is not on a package clock.** The pushes come from the dedicated-server runtime
+image, so how long a pod still delivers them is settled where that image is built rather than by
+this package's release numbers — [the deprecation
+policy](deprecation-policy.md#3-runtime-delivered-pushes-are-a-separate-question). Keep the
+`gem.room` check either way: it is what makes one bundle correct on both images.
+
+Three habits worth keeping:
+
+- **Revalidate rather than refetch.** The room read supports conditional requests: pass the last
+  read's `etag` as `ifNoneMatch` and an unchanged room answers without a body
+  (`{ modified: false }`), so polling or re-reading on events stays cheap.
+- **Re-read the room when a stranger joins.** A player who entered the room after the match started
+  holds a valid credential and arrives at your `join(playerId)` without warning — the case the
+  runtime's push model used to paper over. The room read is how you learn their name and seat.
+- **Writes are yours too, within bounds.** `gem.room` covers the reads; the write half is on
+  `gem.api` — `updateGameRoomV2` (which takes `room_args` in the body, refused with 409
+  `room_not_open` while a match runs), `kickPlayer`, `transferHostV2`, `closeGameRoom` — a
+  dedicated server holds host-level authority over its game's rooms on its channel.
+
+### Members versus players
+
+Two different questions, and the retirement of the roster push sharpens the distinction rather than
+blurring it:
+
+- **`gem.players()`** answers _who is connected to this process_ — peers whose join credential the
+  runtime verified. Runtime truth. It is local, always current, and **never deprecated**.
+- **The room's members** (`gem.room.get()`) answer _who holds a seat_ — membership as the
+  platform tracks it, with display identities, `role` and `is_ready`. API truth.
+
+The two sets overlap and neither contains the other: a member who lost their connection is a member
+and not a player, and — the one that surprises — **a backfill player is a member before they are a
+player**: they take the seat first and reach your `join` seconds later. Which is why an unknown id
+arriving at `join` means "re-read the room", never "reject".
+
+## What `gem` carries
+
+Everything above, on one object. Here it is doing the whole job at once:
+
+```js
+import { defineServer } from '@indiegems/gem-web-sdk/sdk';
+
+export default defineServer((gem) => ({
+  async init() {
+    gem.log(`match ${gem.identity.matchId} on ${gem.identity.channel}`);
+    // The startup reads. `gem.room` is absent under an older runtime image —
+    // see the section above for what to fall back to.
+    if (gem.room) seat((await gem.room.get()).body.members);
+  },
+  join(playerId) {
+    gem.send(playerId, JSON.stringify({ t: 'hello', you: playerId, players: gem.players() }));
+    gem.broadcast(JSON.stringify({ t: 'joined', playerId }), { except: playerId });
+  },
+  message(playerId, data, isText) {
+    gem.broadcast(data, { except: playerId });
+  },
+  async shutdown() {
+    await gem.match.end();
+  },
+}));
+```
+
+Two halves, one object. The **match surface** is [the host table](#the-host) — `players()`, `send`,
+`broadcast`, `kick`, `log`, `warn`, `sizeClass`, and the deprecated `roster`/`roomArgs` pushes — and
+the **gem-api surface** is the sections after it: `gem.api.*`, `gem.room`, `gem.client`, `gem.match`
+and `gem.identity`, plus `gem.functions`, which calls your game's serverless function as this server
+([serverless-functions.md](serverless-functions.md)), and `gem.challenges`, which reads one
+player's daily-challenge period, date and seed ([daily-challenges.md](daily-challenges.md)).
+
+`gem.room` is [the startup reads](#what-your-server-reads-at-startup), pre-bound to your own room,
+and it is where a bundle written today gets its membership and its settings object.
+
+`gem.roomArgs` is the runtime's push passed straight through, so [§ Room args](#room-args) above is
+the whole contract — including the part that bites: **`undefined` is not `{}`**, and the SDK defaults
+neither to the other. `const settings = gem.roomArgs ?? {}` in your own bundle is the place to make
+that choice. It is the fallback for a pod running an older image, not the path to write first.
+
+**It is not valid until `init`** — that is the one place the platform hands anything over — so reading
+`gem.identity.matchId` at the top of your module throws a message saying so rather than handing you
+`undefined`.
+
+Three things it adds over the surface the runtime hands across:
+
+- **`gem.profile(playerId)`** — the display identity the platform resolved for a verified player, or
+  `null`. `displayName` arrives wrapped rather than as a plain string, because it is player-authored
+  and your server is the one place in your game that relays a name **to every other player**;
+  `text.toPlain(name)` unwraps it where you have decided that is safe. `displayTag` — the
+  precomposed `Name#0001` — contains the name, so it is wrapped too; only `discriminator` is
+  platform-assigned and an ordinary string. Prefer relaying the player id and letting each client
+  render the name it already has.
+- **`gem.playerNumber(playerId)`** — the seat number the runtime assigned, or `undefined` for an id
+  it has not seated — and equally on an older runtime image, which a bundle need not tell apart.
+- **A `shutdown` you do not have to remember.** The SDK defines one whether or not you do, and
+  unsubscribes from the token there. Yours runs first, and it still runs if you only want
+  `gem.match.end()`.
+- **One import for both halves.** The same package, the same error types, the same vocabulary. A
+  `catch` in your bundle reads like a `catch` in your browser code.
+
+⚠️ **A runtime image that predates token delivery fails at `init`, whatever your bundle does with
+gem-api.** `defineServer` builds the gem-api half before your `init` runs, and that is where the
+"predates token delivery" error comes from — so a message-relay bundle that never calls gem-api will
+also refuse to start on an old image. Better at startup than at `shutdown`, when the result you meant
+to write is the thing that fails.
+
+That is the one behaviour the hand-assembled route buys you, and it is the reason it exists: a bundle
+that calls `createGemServer(host)` itself decides when — and whether — to build the gem-api half, so
+it can serve an old image with the deprecated pushes instead of refusing to start. Every fleet this
+SDK targets delivers tokens, so that is a fallback to reach for deliberately and not a default worth
+carrying.
+
+**It is still one file.** Your bundle is bundled — the SDK is a dependency of your build, not of the
+runtime, and nothing is installed where your server runs. The `/sdk` entry carries both halves and
+is safe to bundle for Node — nothing in it touches a browser global at module scope — so what you
+publish is your code plus whatever of the SDK it reached. No API origin is baked in either way;
+that arrives on `host.apiBaseUrl` at runtime. (`/server` remains as the server-only door for a
+bundle that wants nothing of the browser half in its graph.)
+
+### What is not on the server surface, and why
+
+`gem.p2p`, `gem.dedicatedServer`, `gem.me`, `gem.characters` and `gem.gameConfig` are browser-only.
+For the first four that is not a restriction on servers — every one of them is scoped by a
+**player** token, and your server is not a player. It has no player identity, and the routes behind
+those namespaces would refuse it.
+
+`gem.gameConfig` is the exception, in one direction only. The namespace is browser-only, but the
+platform read underneath it is not refused to a server: the channel assignment admits a game-server
+token, fenced to that token's own game and channel. Your bundle reaches it as
+`gem.api.getChannelAssignment(gem.identity.channel)`, and fetches the returned `config_url` itself.
+
+The short version: the browser half is what a player's **session** can do, and the server half is
+what a **match** can do. `gem.rooms.join()` has no meaning to a process that exists because a match
+was already allocated.
+
+**Rooms are the case where those two answers differ**, so they are worth stating separately rather
+than filed under "browser-only". `gem.rooms` — join, leave, ready up, quick-join — is a player
+acting on their own membership, and your server has none. Reading and administering the room your
+match is running in is a different question, and one your token does answer:
+`gem.room.get()`/`gem.room.args()` for the reads, and `gem.api.*` for the writes
+([above](#what-your-server-reads-at-startup)). So the boundary is not "rooms are a player thing";
+it is that a server has authority over rooms and no membership in one.
+
+### Two orderings that are easy to get backwards
+
+- The joining player is **already** in `players()` when `join` runs. A roll-call built there includes
+  them, which is usually what you want: it is also how a client learns the id the platform verified
+  for it.
+- The leaving player is **already** gone from `players()` when `leave` runs. A broadcast there needs
+  no exclusion.
+
+### Failure
+
+- **A method that throws does not take the match down.** The exception is logged and the runtime
+  keeps serving — a bundle that dies mid-match would fail an allocation that is otherwise healthy.
+- **Except in `init`.** A throw there fails startup and the allocation is reported failed, because a
+  server that never initialised has nothing to serve.
+- `init` has **60 seconds** to return. Load what you need and hand back; do not wait on a player.
+- `shutdown` has **ten minutes** when the match is over — your own end, or an expired idle window —
+  before the link closes and the process goes with it. Anything that must outlive the match, a
+  result to report or a save to write, happens there. The budget is long on purpose: what a bundle
+  does in `shutdown` is save what just happened, and a process killed part-way through that costs a
+  player progress with nothing left to reconstruct it from. It is still a deadline, so bound your
+  work rather than assuming the window is the whole story.
+- **A node drain is not bounded by that ten minutes.** When the pod is being taken away rather than
+  the match ending, the platform waits for your `shutdown` however long it takes — a match with
+  people in it plays out rather than dying because a node is draining. The only limit is the pod's
+  own two hours, after which everything in it is killed regardless. Both budgets, what sets them,
+  and the reason a bundle never sees the signal that starts the longer one, are
+  [below](#how-long-your-server-lives).
+
+## How long your server lives
+
+Two limits decide it, and every bundle meets both. The first bounds how long the match may run. The
+second bounds what you can still do once something has decided the match is ending.
+
+Your `shutdown(info)` is told which it is: `info.reason` is `match_ended` (with `info.endedReason`
+naming why, in the same vocabulary the client's `matchEnded` carries), `idle_timeout`, or
+`signal` — and it is absent on older platform images, so default before use. Call
+`gem.match.end()` from `shutdown` unless the reason is `signal`: on `match_ended` it is already
+over and on `idle_timeout` the platform ends it itself, so the call is harmless on both, and on
+`signal` the players are still in it. What the players see for each reason is
+[match-session.md](match-session.md) §3 and §6.
+
+### The match has a maximum duration, and you set it
+
+A dedicated match runs for at most `max_match_duration_seconds`, declared **per room template** in
+your published game config:
+
+|                                  |                                                             |
+| -------------------------------- | ----------------------------------------------------------- |
+| What you may declare             | **30 minutes** to **48 hours**                              |
+| A template that declares nothing | **6 hours**                                                 |
+| Applies to                       | `match_type: dedicated` — the only type that holds a server |
+
+**Omitting it is not "unbounded".** A template naming no limit gets six hours, and a value outside
+the range **fails the config upload**, naming the field and both bounds, rather than being quietly
+clamped to the nearer one. Declaring it on a `p2p` or `none` template is refused for the same reason:
+neither holds a server, so the number would do nothing.
+
+**The deadline is fixed when the match starts**, from the template as it stood at that moment.
+Promoting new config does not move a running match's deadline — only matches started afterwards get
+the new number.
+
+**Reaching it ends the match exactly as your own server ending it would**, along the same path
+`gem.match.end()` takes: the room's members get the `match_ended` push they already handle, the
+room reopens, and the server is released. The only difference is the reason recorded against the
+match, `expired` rather than an ordinary end.
+
+So it is a **backstop, not a schedule**, and a game that ends its own matches never reaches it. What
+it catches is the match nobody ended — most often a finished match whose last browser tab stayed
+open, which a server cannot tell apart from a player still thinking about their turn.
+
+### Winding down, and the ceiling on it
+
+Your server can be asked to stop **at any time**. Two different things ask, and they do not give you
+the same budget:
+
+| Why your server is stopping                                                           | How long `shutdown()` gets                           |
+| ------------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| The match is over — your own end, the duration limit above, or an expired idle window | **10 minutes**                                       |
+| The platform needs the machine your server is running on                              | **as long as you take**, to a ceiling of **2 hours** |
+
+**The first row is the one nearly every match meets, and ten minutes is long on purpose.** What a
+bundle does there is save what just happened — a result to report, progress to write — and a process
+killed part-way through that costs a player something nobody can reconstruct afterwards. It is still
+a deadline and it is enforced: past it the link closes and your process goes with it, so bound the
+work rather than treating the window as the whole story.
+
+The second row is the more generous of the two, and also on purpose. When the platform reclaims a
+machine, **a match with players still in it is not killed for it**: the runtime calls your
+`shutdown()` and then waits for you with no deadline of its own, so a match that is nearly over can
+finish, and one that is not can move its players somewhere else first.
+
+**What bounds that wait is the pod's termination grace period, and it is 2 hours.** Past it every
+container is killed outright. A bundle that has not returned from `shutdown()` by then loses whatever
+it was still doing — the save it had not written, the result it had not reported, the players it had
+not moved.
+
+⚠️ **The signal does not reach your code as a signal.** A reclaim arrives at the pod as `SIGTERM`,
+and what is signalled is the platform half, not you. Your bundle hears about it through `shutdown()`
+and through nothing else: a `process.on('SIGTERM', …)` handler in a bundle is not the hook, is not
+guaranteed to run, and must not be what your wind-down depends on.
+
+## What counts as a player
+
+**A peer that has presented a join credential the runtime verified.** Not a peer that completed ICE,
+DTLS and SCTP — that peer has proved it can reach the server and nothing else, so counting it would
+hold a pod open for an unauthenticated stranger.
+
+This is why `playerId` is trustworthy. It is always the subject of a credential the platform issued
+and the runtime verified, so a client cannot claim to be someone else. That is a property a host peer
+in a P2P star **cannot** offer, and it is the main reason to want a dedicated server at all: with
+authenticated identity on the server, authority over score, inventory and outcome can live somewhere
+the players do not control.
+
+A pod that has held zero verified players for its idle window reports unhealthy and is recycled. The
+window is generous relative to a join — the clock starts at allocation rather than at pod start, and
+a join credential's own lifetime is 60 seconds — so a slow legitimate join cannot trip it.
+
+### Membership is not a guest list
+
+**Admission is by credential, and that is the whole rule.** Anyone who reaches your bundle has
+presented a join credential the runtime verified against the platform's keys, and the platform issues
+one to **any member of the room**, including a player who joined after the match started. Your server
+is obliged to honour it.
+
+So no list — not the deprecated `gem.roster` snapshot, and not the membership a room read returned
+a moment ago — is the set of players you are allowed to serve. A bundle that checks arrivals against
+either and drops the ones it cannot find will reject real players. It will do it _after_ their
+connection is up, which is the reason this is worth a section: to the player it looks like your game
+dropping them, not like an admission decision anybody made, so it gets reported as a platform fault
+and chased in the wrong place.
+
+```js
+async join(playerId) {
+  // WRONG. No membership list can answer this: a player who joined the room
+  // after your last read holds a valid credential and is not on your copy.
+  if (!seats.has(playerId)) gem.kick(playerId, 'not invited');
+
+  // RIGHT. An unknown id means your copy of the room is stale — re-read it.
+  if (!seats.has(playerId)) await refreshSeats(); // gem.room.get()
+}
+```
+
+Membership answers the questions it actually describes — who holds a seat, what to call them, who
+is host, who is ready — and the room read keeps the answer current in a way the retired snapshot
+never could. **The live connection set is a different question**: `gem.players()` is the players
+connected right now, correct at every moment, including inside `join` where the arriving player is
+already in it. [Members versus players](#members-versus-players) is the full distinction.
+
+## The DataChannel wire format
+
+The SDK's flow ends at "the channel is open, here is your join credential". This is what goes on it.
+
+**Client → server, the first message, and nothing else is accepted before it:**
+
+```json
+{ "t": "join", "credential": "<join credential JWT>" }
+```
+
+**Server → client:**
+
+```json
+{ "t": "welcome", "player_id": "<uuid>", "match_id": "<uuid>" }
+{ "t": "rejected", "reason": "invalid_credential" }
+```
+
+The seven rejection reasons, and what to do about each:
+
+| `reason`                          | What happened                                                                                                | What the client should do                                                                                                                  |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `expected_join`                   | The first message was not a `join` frame — unparseable, or some other `t`                                    | Fix the client. Retrying sends the same thing                                                                                              |
+| `invalid_credential`              | The JWT failed verification: signature, `alg`, audience, issuer, or one of its bindings                      | Not retryable. A fresh credential fails the same way                                                                                       |
+| `credential_expired`              | The JWT verified, but its lifetime had run out — past the leeway allowed for clock skew                      | **Retryable.** Call `connect()` again: it fetches a fresh credential and renegotiates                                                      |
+| `credential_reused`               | The JWT verified, and had already been presented as many times as one credential is good for (ten)           | **Retryable with a NEW credential.** The SDK fetches one and presents it on the same transport before reporting this                       |
+| `credential_not_for_this_channel` | It verified, but its subject is not the player who offered this channel                                      | Not retryable. Somebody is presenting a credential on a channel negotiated in another player's name                                        |
+| `credential_timeout`              | 30 seconds passed on an open channel with no join                                                            | Retryable, but the fault is almost always a client that never sent                                                                         |
+| `join_rate_limited`               | The JWT verified, and this player has joined too often — the runtime admits 30 joins a minute, 10 in a burst | **Retryable, but slow down.** The SDK waits at least two seconds and presents the same transport again, three times, before reporting this |
+
+`credential_expired` is a reason of its own rather than a flavour of `invalid_credential`, because it is
+the only refusal here a client can act on. Folded into "invalid" it reads as a broken token, which
+sends the search to the signing key and the JWKS cache instead of to the clock.
+
+**A rejection is written before the transport is torn down**, with a short grace so it actually
+arrives. A channel that vanishes with no explanation is indistinguishable from a network fault, and
+sends debugging to the wrong place.
+
+**After `welcome`, every message on the channel is opaque to the platform** and belongs to your game.
+The JSON envelope above is the platform's; what you do afterwards — JSON, binary, a schema of your
+own — is entirely yours. Nothing above the transport inspects it, and nothing above the transport
+caps its size either, which is a reason for a server to bound what it will accept.
+
+## Presenting the credential, from the browser
+
+**The SDK does this for you.** `connect()` sends the join frame and resolves once the runtime has
+answered `welcome` — so a session it hands back is one the server has already accepted, not merely a
+transport that came up.
+
+```js
+const session = await gem.dedicatedServer.connect({ clusterTargetId });
+// The server verified this player. Nothing above is the game's to write.
+startPlaying(session.welcome.playerId);
+
+session.channel.onmessage = (event) => handleGameMessage(event.data);
+```
+
+A rejection fails the connect, tears the session down, and carries the reason: the seven above map
+onto `credential_expired`, `credential_reused`, `join_rate_limited` and `timeout` — all `retryable`,
+so calling `connect()` again is the right answer, and on the negotiated path the SDK has already
+refreshed the credential or waited out the rate limit once before it reports the first three — and
+`join_refused`, which is not, because retrying sends the same thing.
+
+**The gap this leaves, and how to close it.** A data channel with no listener drops what arrives;
+nothing buffers anywhere. Between the welcome and the line that attaches `onmessage` there is a
+window, and your bundle's `join` callback runs inside it — so an opening snapshot sent from there is
+the message most likely to be lost. Attaching in the continuation as above is normally fast enough.
+To remove the window entirely, hand the SDK the handler instead and it attaches before the join frame
+goes out:
+
+```js
+const session = await gem.dedicatedServer.connect({
+  clusterTargetId,
+  onMessage: handleGameMessage, // post-welcome frames only; the envelope is consumed
+});
+```
+
+Do not do both — two handlers see every message twice.
+
+**Doing it yourself.** `presentCredential: false` hands back the raw channel, `session.welcome` is
+null, and the exchange above is yours to write. Send it immediately: `session.credentialExpiresAt` is
+a Unix-milliseconds deadline and the credential's lifetime is 60 seconds from the moment the SDK asked
+for match status — most of which the handshake has already spent.
+
+```js
+const session = await gem.dedicatedServer.connect({ clusterTargetId, presentCredential: false });
+
+session.channel.onmessage = (event) => {
+  // Binary is yours alone — the platform's two replies are always text.
+  if (typeof event.data !== 'string') return handleBinary(event.data);
+
+  const frame = JSON.parse(event.data);
+  if (frame.t === 'welcome') startPlaying(frame.player_id);
+  else if (frame.t === 'rejected') giveUp(frame.reason);
+  else handleGameMessage(frame);
+};
+
+session.channel.send(JSON.stringify({ t: 'join', credential: session.joinCredential }));
+```