@indiegems/gem-web-sdk 7.4.0 → 7.4.1

package/docs/p2p-and-parties.md

@@ -0,0 +1,783 @@
+# Peer-to-peer, and parties — the browser half
+
+Two surfaces that look unrelated and are not. Both run into the same wall: **the
+frame holds a game-scoped token and the page holds the player's account**, so
+anything reaching for an account-scoped route has to happen on the far side of
+the bridge. P2P hits it for signaling; parties hit it for everything. What
+follows is how each one gets across, and where the web genuinely cannot look
+like a native client.
+
+Companion to [`rooms-and-matches.md`](rooms-and-matches.md), which this
+builds on: rooms answer "which match", and this answers "how do I get onto it"
+for the protocol the other flow refuses.
+
+**You may not need to touch `gem.p2p` at all.** `gem.match.serve(yourServer)`
+runs the same `defineServer` bundle you publish for dedicated matches in the
+hosting player's browser, over the session this page describes, and
+`gem.match.connect()` gives every seat — the host included, through an
+in-process loopback — one `MatchConnection`. That is the whole of P2P for a
+game whose authority is its server bundle;
+[`server-bundles.md`](server-bundles.md#the-same-bundle-hosted-by-a-player)
+shows the two calls. `gem.p2p` stays public for raw channels, host-migration
+control and transport tuning, and that is what the rest of this page is about.
+
+---
+
+## 1. The surprise: almost all of P2P is already reachable
+
+The dedicated-server flow spent a long time looking blocked
+([`dedicated-server-flow.md`](dedicated-server-flow.md) §2), and only one
+of those blocks was real: the notification socket. P2P was expected to be worse,
+and it is not — it has that same one and nothing else. Every route below takes gem-api's
+`AuthenticatedGamePlayer` — the game-scoped play token the bridge already
+delivers — and the frame can call all of them today, unmodified:
+
+| Step                                         | Route                                                         |
+| -------------------------------------------- | ------------------------------------------------------------- |
+| Bind this browser's certificate to the match | `POST /v1/games/{game_id}/matches/{match_id}/join-credential` |
+| Lease a TURN relay                           | `POST /v1/games/{game_id}/matches/{match_id}/turn-lease`      |
+| Remove a peer (host only)                    | `POST /v1/games/{game_id}/matches/{match_id}/kick`            |
+| Leave                                        | `POST /v1/games/{game_id}/matches/{match_id}/leave`           |
+| Report connection telemetry                  | `POST /v1/games/{game_id}/telemetry/p2p`                      |
+| Verify a peer's credential                   | `GET /oauth2/jwks` (public)                                   |
+
+**One thing is not reachable, and it is the same one as before.** Signaling
+rides the notification WebSocket, `POST /v1/ws/ticket` accepts only player
+tokens, and the browser WebSocket API cannot set a bearer header — so there is
+no route around it. That is a platform decision, settled and not being
+revisited.
+
+So signaling is the only thing this SDK routes through the parent. Nothing else
+has to be, and nothing else is.
+
+### 1.1 What decides a match is peer-to-peer, and why no game gets one by default
+
+Reachability is not what stops a first P2P match happening. **The room's template
+decides the transport**, and nothing a game ships chooses this one until somebody
+authors it.
+
+`match_type` is a field on a room template. It takes `dedicated`, `p2p` or
+`none`, and it **defaults to `dedicated`**. A room created from a template gets
+that template's value; **a room created with no template at all is dedicated**.
+So are both templates the platform ships globally — `standard` is dedicated and
+`hub` starts no match — and those two are compiled in rather than stored, so no
+config upload changes them and there is no global `p2p` template to name.
+
+**A P2P match therefore needs a game-specific room template carrying
+`match_type: "p2p"`.** That is upstream of everything else in this document, and
+it fails two different ways depending on what the client asked for:
+
+- **The client names a slug the game's config does not carry** — room create is
+  refused for an unknown template slug, which reads like a client bug and is not
+  one.
+- **The client names no template at all** — it gets a room, it gets a match, and
+  it gets a **dedicated** one. There is no error anywhere; the first thing to
+  object is this SDK's own protocol check once the match reports ready. This is
+  the worse of the two, and it is the reason to name your template explicitly
+  rather than relying on a default.
+
+### 1.2 The template ships in your game config
+
+Room templates are authored in the game config you upload, under a
+**`game_room_templates`** key, and `match_type: "p2p"` is the field that matters
+here. Upload the config, assign that version to a channel, and rooms created on
+that channel can be built from it. The rest of the authoring surface — which
+fields are required, how a slug resolves, and the several ways a template can
+validate and still be unreachable — is
+[`platform-rules.md` §5](platform-rules.md#authoring-your-own); only the P2P
+half is repeated here.
+
+The published game-config JSON Schema declares the key, `match_type` enum and
+all, so a correct P2P config validates locally as well as on upload. Both
+schema endpoints are public, so if a validator you are running disagrees, fetch
+the schema yourself and check which copy it was holding.
+
+Two related facts, because both send people hunting for an endpoint that is not
+there:
+
+- **The platform's template routes are read-only.** Both the global list and
+  your game's resolved list answer `GET` and nothing else, so a template cannot
+  be poked in over the API. The config upload is the only route.
+- **You can check the result from inside the game.** `GET
+/v1/game-room-templates?channel=<channel>` answers with what a room can
+  actually be built from — your config's templates first, the globals behind
+  them — and it takes the game-scoped token the frame already holds. So a client
+  can confirm the template it is about to name exists, rather than discovering it
+  at room create.
+
+---
+
+## 2. Signaling goes both ways, and that is new
+
+`gem.roomEvent` is parent→frame, four event types, low rate, carrying no state.
+P2P signaling is the opposite on every axis: bidirectional, per-peer, and bursty
+— ICE candidate trickle arrives in clumps as the browser works through its
+interfaces.
+
+```
+        frame                    parent                     gem-api
+          │                        │                           │
+   gem.signal  ──────────────────▶ │  template + checks ─────▶ notification WS
+   (6 templates)                   │                           │
+          │  ◀────────────────  gem.signalEvent  ◀──────────  9 push types
+```
+
+### 2.1 The outbound direction is the whole risk of this work
+
+The socket belongs to the **player**, not to the game. It carries friend
+requests, party invites, transfer receipts and purchase completions. A frame able
+to ask the parent to put an arbitrary frame on it has escaped the sandbox — so
+`gem.signal` is deliberately **not** a message the parent forwards.
+
+It is a **request the parent fills in a template from**:
+
+- The frame names one of **six templates** (`join`, `offer`, `answer`, `ice`,
+  `migrationAck`, `hostUnreachable`) and supplies arguments. It never names a
+  socket message type.
+- The parent copies **only the fields that template declares**, by name, onto a
+  fresh object. Anything else is dropped rather than forwarded.
+- **`game_id` is the parent's**, taken from the token it issued. A frame that
+  could name one could ask the player's socket to join a match in another game.
+- **`match_id` must be one the parent has seen on this player's own socket.**
+  The socket delivers only this player's events, so a match id that arrived there
+  is one the player is genuinely party to. Without this the frame could name any
+  id and use the player's socket as a probe — and gem-api's refusals would be
+  spent out of the _player's_ rate budget, not the game's.
+
+That last point is what keeps this SDK's standing invariant true with a
+frame→parent message added: _no frame→parent field is a value the parent trusts
+or acts on beyond routing._
+
+### 2.2 Two limits, because the server's is not ours to spend
+
+gem-api rate-limits P2P signaling at **30 messages per second** and caps a client
+WebSocket frame at **16384 bytes**. Neither is a defence this side can lean on:
+exhausting a player's server-side budget is a denial of service against _them_,
+and a frame over the cap is not delivered slowly — it is not delivered, and the
+connection silently fails to form afterwards.
+
+So the parent enforces both itself:
+
+- **24 signals per second**, in its own one-second window, below the server's own
+  number. The bridge's limiter is per _minute_ by construction, so a frame with a
+  full bucket can burst a minute's worth inside one second and be entirely within
+  its rights.
+- **A 16384-byte cap on the serialized frame**, measured on the finished object
+  rather than guessed from the SDP's length. At the server's own figure rather
+  than below it — a frame this side refused that the socket would have accepted is
+  a connection that fails for no reason — so what it buys is a named refusal the
+  game can read in place of a socket that closes under it.
+
+### 2.3 What happens when the bridge is slower than the trickle
+
+Candidates arrive in bursts; the parent paces. Dropping the difference silently
+is the worst option available, because a lost candidate does not fail — it
+**degrades**. The connection falls back to relay, or does not form, and nothing
+says why.
+
+So candidates are **queued and paced** at ~20/second (under the parent's 24 and
+gem-api's 30), the queue is **bounded at 100** — deeper than that is buffering
+candidates the far side would refuse anyway — and an overflow is
+**reported** as a `candidatesDropped` event carrying the count. Offers, answers,
+joins, acks and reports are never queued: there is at most one of each in flight,
+they are what the connection waits on, and delaying them behind a hundred
+candidates is the slow version of dropping them.
+
+This is also why P2P **trickles** while the dedicated flow gathers to completion.
+It is not a stylistic difference, and it is not the frame size — 16 KB holds a
+complete gathered offer on either path. It is that this path sends the offer
+before gathering has finished and keeps finding candidates afterwards: a relay
+candidate once the TURN allocation completes, and an entirely new set after an ICE
+restart. One gathered exchange has nowhere to put those, which is why gem-api's
+P2P routes carry a candidate message and its dedicated route does not.
+
+### 2.4 The inbound relay carries state, unlike every other relay here
+
+`rooms-and-matches.md` §3 makes a point of the room relay being a _hint_:
+the frame re-reads the room over its own token, so a compromised parent can make
+it look and not believe. **`gem.signalEvent` cannot work that way** — there is no
+route by which a frame could re-read an SDP offer another player sent. The offer
+has to cross.
+
+What makes that acceptable is that nothing downstream believes it on the strength
+of having arrived. **Peer identity is bound to a DTLS certificate fingerprint the
+platform attests to the frame over the frame's own TLS connection to gem-api**
+(§3). A parent that rewrote an SDP would break the connection; it could not
+impersonate anyone. Everything else on that path — a candidate, an ICE ufrag — is
+harmless if forged, because a candidate that does not work simply does not work.
+
+One field is dropped at the parent and it is worth naming: **`jwks_url`**.
+gem-api sends it on `p2p_hello` so a host knows where to fetch the keys it
+verifies joiners against. A frame that took its key source from a relayed message
+would let whatever is embedding it choose the keys that decide whether a peer's
+claim to be player X is believed. The frame derives that URL from its own
+configured API root instead.
+
+---
+
+## 3. Peer identity: what a browser can honestly establish
+
+On a dedicated match the question does not arise for the client — the server
+verifies a platform-signed credential and the client verifies nothing. Here the
+other end is another player's browser, so **the peers authenticate each other**,
+and it is worth being exact about the two directions because they are not equally
+strong.
+
+### 3.1 Client verifying host — complete, and it needs no cryptography of ours
+
+`POST /matches/{id}/join-credential` answers with the current host's DTLS
+certificate fingerprint. That answer arrives over the **frame's own TLS
+connection to gem-api**, so it does not depend on the parent, on the signaling
+path, or on the host being honest.
+
+The client compares it against the `a=fingerprint:` line of the SDP answer
+**before applying the answer** — applying one is what starts the DTLS handshake,
+so a check afterwards is a check after the decision. A DTLS handshake only
+succeeds against the certificate the SDP named, so an impostor either fails the
+comparison or fails the handshake. This is the platform's standard pre-DTLS
+check, reproduced exactly.
+
+On a mismatch nothing is retried and — the part that matters — **the credential is
+never presented**.
+
+### 3.2 Host verifying client
+
+The joiner presents a platform-signed RS256 credential as the first message on
+the reliable channel, and the host verifies it: algorithm, `typ` (`p2p+jwt`, so a
+platform access token cannot be presented as one), issuer, audience, match, game,
+host epoch, expiry with five seconds of skew, `jti` replay, and the two
+fingerprint bindings. A browser can do all of that — WebCrypto verifies
+RSASSA-PKCS1-v1_5/SHA-256 natively.
+
+**When the host refuses a joiner, the host says why.** Only the host ran the check, so
+only the host's console can carry the reason: every refusal logs one `[gem]` line at warn
+level naming the joiner and what failed — the verifier's own sentence (`it names a
+different host epoch`, `it has already been used`, …), or that the credential was issued
+to a different player, that the player is on the kicked list, or that the platform's
+signing keys could not be fetched. The joiner is sent a code, and the `P2pError` its
+`connect()` rejects with carries it in `reason`, so a game can branch without matching on
+prose:
+
+| The host's reason | The joiner's `reason` | Worth a reconnect? |
+| --- | --- | --- |
+| The credential did not verify | `peer_unauthenticated` | No — the platform issued it, and the host disagrees with the platform |
+| The credential names a different player than the one who signalled | `not_expected_player` | No |
+| The player is on the host's kicked list for this epoch | `kicked` | No |
+| The host could not fetch the platform's keys | `keys_unavailable` | Yes — the host fetches again on the next joiner |
+
+A refusal never fails the host's own session: the one link is dropped, the line is logged,
+and hosting continues. `keys_unavailable` is additionally raised as the host session's
+`error` event, and a listen host forwards every session `error` to the same sink, because
+that one is host-wide — nobody can be admitted until the keys arrive.
+
+### 3.3 The certificate is per peer, not per connection
+
+gem-api stores **one host fingerprint per match epoch**, taken from the host's
+first SDP answer, and stamps it into every credential it issues. A host that let
+the browser mint a fresh certificate per `RTCPeerConnection` would answer its
+second joiner from a certificate the platform never saw, and that joiner's
+credential would name the first one — a peer failing authentication for a reason
+no log line would explain.
+
+So a peer generates **one** certificate (`RTCPeerConnection.generateCertificate`,
+ECDSA P-256) and passes it to every connection it makes.
+
+### 3.4 The admission handshake's version number is deliberately out of range
+
+The admission handshake follows an older native wire format byte for byte: join,
+admit, reject. Its `protocol_version` describes that format's **replication**
+wire — snapshot flags, entity transforms — which this SDK does not implement and
+which is explicitly out of scope.
+
+The value sent here sits **outside** the engine's ascending range, so an engine
+host refuses cleanly with `VERSION_MISMATCH` rather than admitting a browser peer
+and then waiting for packets that never come.
+
+That format is retired, so there are no peers left to mismatch against and this
+is now inert. **Do not "reclaim" the number**: the format is kept as-is
+because it is a working, reviewed handshake with a conservative default, and
+re-pointing `protocol_version` at something in-range buys nothing and reopens a
+settled question.
+
+### 3.5 What this does not do
+
+The engine's ICE-restart budgets, oscillation damping, per-peer packet rate
+limiting, DTLS rekey accounting and replication stack are all absent. They are
+netcode tuning around a transport rather than the transport, and a browser game
+gets a connection and three data channels from us — what it puts on them is its
+own.
+
+---
+
+## 4. TURN credentials reach the game, and cannot not
+
+The TURN lease route takes a game-scoped token, so the frame calls it directly —
+and it must, because the frame owns the peer connection and the credentials go
+into its ICE configuration. **On web the SDK shares a JavaScript realm with the
+game, so "the SDK holds it" and "the game holds it" are the same statement.**
+
+They are short-lived and match-scoped, which is why this is acceptable rather
+than alarming. But it is the second instance of the same fact, and it generalises:
+**anything that must not reach the game must not reach the frame.** That is the
+rule that put the notification socket on the parent, and it is the rule that keeps
+the party surface there too (§7).
+
+The lease is taken **before the first offer**, because ICE servers have to be in a
+peer connection's configuration when it is constructed. Leasing afterwards
+produces a connection that works whenever both peers are directly reachable —
+which passes every test on a LAN and fails for a large minority of real players.
+
+**Which cluster to lease from is normally nobody's decision to make here.** The
+parent measures the regions and hands the close ones across the bridge, and each
+peer leases from its own best one — a relay near that peer, whichever cluster
+the room is recorded in. See `dedicated-server-flow.md` §5 for how the measuring
+got onto the page and what never comes back off it.
+
+**The page's answer does not reach the match start.** When `connect` has to start
+the match, it names no cluster, so the room stays where it was made: naming one
+moves a room, and a host should not drag a room to their own region by
+connecting to it.
+
+Passing `clusterTargetId` explicitly still wins, for the lease and the start
+alike — which is a decision to move the room. When nothing resolves one the
+connection proceeds without a relay and says so loudly, because the failure it
+causes is the one that looks like success.
+
+**`null` names no cluster, exactly as omitting the option does.** A game picking
+its target out of a list writes `targets[0]?.id ?? null`, so that is the spelling
+ordinary code arrives with — and it defers to the parent's answer the same way an
+absent option does. What it must never do is reach the platform as a lease
+request for a cluster with no id: that costs the caller the no-relay warning and
+reports "the relay was refused" for a player whose actual problem is that nobody
+ever resolved a region for them.
+
+---
+
+## 5. Host migration is where a split match can happen
+
+On a dedicated match "the authority went away" means the match ended. Here it
+means the match continues under somebody else, and every peer has to agree who. A
+peer still talking to the old host is not a slow peer — it is a **second match**.
+
+```
+   idle ──migration(epoch+1)──▶ preparing     (this peer was elected)
+     ▲                          reconnecting  (somebody else was)
+     └──── completion broadcast, or admitted by the new host ────┘
+```
+
+Three rules carry the weight:
+
+**Tear down first, unconditionally.** An accepted migration closes every existing
+connection before anything is attempted. As a client there is exactly one and it
+points at a host that is gone; as the outgoing host they all point at players who
+are re-signaling elsewhere.
+
+**The epoch comparison is asymmetric, and should be.** Strictly greater is the
+migration. Equal is dropped **quietly** — gem-api broadcasts to every member
+including the elected host, so a second copy is an expected protocol artifact
+rather than an error, and reporting it would train a game to ignore a class that
+also contains real problems. Lower is refused **loudly**: it means reordering or
+replay, which nothing else in the flow would surface.
+
+**Acknowledging is not being acknowledged.** The elected host sends
+`p2p_migration_ack` and then stays in its active phase until the platform's
+_second_ broadcast at the same epoch says the migration completed. The platform
+holds the match in `migrating` until the ack arrives, refusing credentials to
+everyone meanwhile — so a lost ack is a match nobody can join and nothing is
+trying to fix, and the old host is already gone. A host that settled on its own
+send could not tell that apart from a healthy match. The active phase is bounded
+at 30 seconds and a stall is reported as `migration_failed`.
+
+A non-host that sees ICE fail reports the host unreachable **once per epoch**.
+That is a vote, not a verdict: gem-api migrates on a quorum of independent
+reporters and never on one, so it cannot unseat a host who is fine for everyone
+else.
+
+### 5.1 What `gem.match` does with a migration
+
+A `MatchConnection` to a hosting peer survives a migration as a **pause**: its
+channels re-resolve on `hostChanged`, so the game sees a gap rather than a new
+connection to build. What the room reports meanwhile is the ordinary session
+vocabulary — `matchSuspended` with cause `host_unreachable` when the host's
+link fails, `matchReconnected` with `attempt: 0` when the migration seated a
+new host and the link came back without a re-dial, and `matchEnded` with
+`host_left` or `migration_failed` when it did not. The screens for each are
+[match-session.md](match-session.md) §3 and §4; the listen host's own
+`end()` / `leave()` are §6 there. Two cases are not papered over, because both
+would be the second match above served authoritatively:
+
+- **The platform elects this player.** The connection closes with
+  `host_migrated_here`. Becoming the authority mid-match means running the
+  bundle — `gem.match.serve` — and a client pretending it still has a link to
+  somebody else would be a second match. Picking up serving mid-match is not
+  something the SDK does for you.
+- **This browser was the listen host, and the migration went elsewhere.** The
+  bundle `serve` started is **stopped**; the peers now answer to somebody else,
+  and a bundle kept running would be a second authority.
+
+**A migration is not the only way back.** When the host is fine and it is this
+peer's own network that moved — airplane mode, a handover from Wi-Fi to cellular
+— nothing is going to elect anybody, and the WebRTC connection underneath will
+never recover: its candidates name an address this device no longer has. The
+reconnect loop's attempt on a peer seat therefore **dials a second signaling
+session at the same host**, exactly as a dedicated seat dials a second link.
+
+Two things make that safe, and both are the reason it could not be done from a
+game's own code:
+
+- **The stale session is closed, not left.** `leave()` would tell gem-api this
+  player is out of the match, and the platform would be reconnecting somebody it
+  no longer has a seat for. `close()` tears down the links and the signaling and
+  says nothing.
+- **The second offer presents the first one's certificate.** The platform records
+  one DTLS fingerprint per player per match epoch, so a browser-minted
+  certificate on the second connection is refused a join credential — which is
+  why `gem.match.connect()` mints one for the seat and hands it to every dial.
+
+The host needs no new code: it answers a returning player as a new session,
+skipping only an offer whose signaling session id it has already answered, and
+gem-api mints a fresh one for the fresh join. A migration already in flight wins
+— that attempt waits, rather than tearing down the session the platform is
+moving.
+
+---
+
+## 6. The connect, as the boot line reports it
+
+`gem.boot` (see [`what-a-game-must-do.md`](what-a-game-must-do.md)) carries the
+platform's share of a slow boot as named marks, and a P2P session writes its own
+into the same line: the relay decision, the signaling join, the platform's hello,
+and then the steps of whichever side of the star this peer is on — a joiner's
+offer, credential, fingerprint check, channel and admission, or a host's
+`host listening` followed by the first joiner's arrival.
+
+**The names are not the dedicated flow's, deliberately.** That journey allocates
+and is welcomed by a server; this one discovers a peer, gathers candidates and
+connects directly, and the failures are different in kind. A shared vocabulary
+would make the two reports look comparable when the second one's steps do not
+exist on the first path at all.
+
+Two properties are worth keeping if this code moves:
+
+- **Marked where the step happens**, not where it is awaited. That is what makes
+  the order in the line the order of events, and what makes a missing mark
+  identify the stage that stopped — the diagnosis a support engineer performs on
+  a capture from a player they cannot reach.
+- **A session that never runs records nothing.** The whole argument for the
+  instrument is that it is free for games that do not use the feature.
+
+The connection that cannot form on a corporate or campus network — no direct
+path, and a relay that was never leased or could not help — presents as a line
+that reaches `host verified` and stops. Making that legible is what these marks
+are for; §4 covers what the relay does and does not fix.
+
+### 6.1 That failure is also reported, because nothing else can see it
+
+The boot line is for the one player holding it. The same failure is counted for
+the platform, once per connect attempt, as a `connection_failures_total` event
+on `POST /v1/games/{game_id}/telemetry/p2p` — and **the client is the only party
+that can send it**. gem-api relays signaling and is never on the media path, so
+ICE, DTLS and SCTP failures are invisible to it by construction: a player whose
+network blocks direct connections outright looks, from the platform's side,
+exactly like one who connected and said nothing.
+
+**Each report names its transport — `p2p`, `dedicated` or `unknown`.** That
+route is scoped by game rather than by match, so a dedicated-server client
+reaches it with the same play token, and without the label the two transports
+are one number with two opposite remedies behind it. The values are gem-api's
+and are not ours to extend: anything else is resolved to `unknown` rather than
+plotted, on this side and on the server's alike, so a label this SDK invented
+would be counted as nothing and reported to nobody. A sample that names none is
+stamped by the flow reporting it, which is the thing that knows.
+
+**What is deliberately not reported: anything the platform decided itself.** A
+migration it ran, a kick it issued, a match it ended, an exchange it refused —
+those are already counted where they happened, and re-reporting them would put
+noise in the one panel that exists to show what nothing else can see. Nor is a
+cancelled connect or a misconfigured game: a player who pressed Back is not a
+player whose network failed. The set of reported reasons is an inclusion list, so
+a failure reason added later is not silently swept in.
+
+**Why this is worth the code.** The only fix for players whose network blocks
+UDP outright is TURN relay over TCP/443, which the platform does not offer
+today. This is how that population gets counted, so the attribution matters and
+the volume does not.
+
+---
+
+## 7. Parties: the surface a game gets is one question
+
+**The platform gives a game no party surface at all.** No roster, no member list,
+no join code. What the room manager does is narrower and much better: a create,
+quick-join or join-by-code made **without** naming a party asynchronously resolves
+the local player's current party through the launcher backend and — _if and only
+if the local player is the party leader_ — attaches its id, so the server brings
+the whole party into the room atomically. A missing or failed lookup means "no
+party" and never errors.
+
+So the party reaches the game exactly one way: **as room members who are already
+there.** The game asks for a room; the party arrives in it.
+
+That maps onto web almost too neatly, because the split it assumes already
+exists. The launcher holds the account; here the parent page does.
+
+### 7.1 Two halves
+
+**Parent half — the real surface.** The page holds the account token, so it can do
+what the launcher does: read the current party, create one, join by code, invite,
+leave, kick, transfer leadership, and follow the party pushes on the socket it
+already holds. This is embedder-facing API, and it is where a party widget
+belongs — the party spans games and the frame does not.
+
+**Frame half — auto-attach, and nothing else.** One message out
+(`gem.partyRequest`), one back (`gem.partyResult`). The answer carries a party id
+**only when the local player leads one**, because that is the only case in which
+the frame has anything to do with it — gem-api requires the caller to be leader,
+so a non-leader that attached the id would be refused a room it could otherwise
+have had.
+
+Absence therefore means "no party, or you do not lead it" — **one state**, because
+the frame's behaviour is identical in both. Splitting them would hand a game the
+fact that this player is in somebody else's party, which is a social-graph fact no
+game asked for.
+
+Every failure is solo: no party, a parent that does not implement `parties`, a
+request that times out (two seconds, because this sits in front of a room call a
+player is waiting on). A room call broken by a feature the game never asked for is
+the one outcome that cannot be allowed.
+
+### 7.2 Why there is no game-facing roster
+
+This is the load-bearing exclusion, so here is the reasoning rather than the rule.
+
+A party record is **account-level and cross-game**. It carries which game the party
+is currently in, per-member suggestions of _other_ games to play, each member's
+proposed platform and engine version, the roster with display names, and a join
+code. Hand that to a game frame and the game learns who this player plays with,
+what else those people are playing, what platforms they are on, and a credential
+that lets anyone holding it join the party.
+
+That is the same concern the room's own member list raises, with the volume turned
+up: a room's members are people in _this_ room, in _this_ game, right now. A party
+is the player's social graph and their activity across the whole catalogue.
+
+### 7.3 What replaced the party id on a room member
+
+The room routes that name a party are on their **second version**, and that is the
+one this SDK calls. A v2 member row carries `group_id`; no party id appears
+anywhere in the response, at any level — not even the requester's own.
+
+`RoomMember.groupId` is that value, read off the wire. Two members sharing it
+arrived together; a member with no value arrived alone. It is opaque: draw a badge
+with it, group a roster by it, compare two members' values — but do not parse it,
+key anything off it, or keep it once the room is gone.
+
+The stability across rooms is precisely what was removed: the marker is scoped to
+one room, so the same party in two rooms carries two unrelated values. The useful
+half — _who is on a team already_ — is a property of the **room**, and this is the
+room exposing it.
+
+**This SDK derived that label itself until gem-api grew the v2 routes**, as `g1`,
+`g2`, … in first-seen order, out of the very field it was hiding. Two things
+changed when the derivation moved to the server, and both are strengthenings:
+
+- **The party id no longer enters the frame at all.** The old arrangement read it,
+  labelled it and dropped it — inside a JavaScript realm the game shares, which is
+  where a strip is worth the least. See `rooms-and-matches.md` §3.
+- **Every client in a room now agrees on the label.** First-seen order is a
+  function of when _this_ client started looking, so a player who joined after a
+  party left could number the remaining groups differently from one who was there
+  the whole time. The marker does not depend on who is asking or when they
+  arrived — and it survives a member leaving and rejoining, which the old label
+  did not.
+
+The field kept its name and its meaning; games see the same guarantee. What
+changed is the _shape_ of the value — no longer a short ordinal, now `g` followed
+by sixteen hex characters. A game that was displaying it raw was already showing
+the player something meaningless, and should map it to its own team names; nothing
+else needs to change.
+
+One caveat worth recording because it is invisible from here: the platform can
+relabel the groups in a room that is open at the time, so treat the value as
+stable for a room rather than permanent. Cosmetic, and it cannot be observed as a
+_loss_ of grouping — members of one party still share whatever the new value is.
+
+If a game-facing group is the wrong call entirely, the alternative is to drop the
+field; it should not be to pass the platform's id through.
+
+### 7.4 What a party MEMBER's game has to do, which is not what a solo game does
+
+Everything above is the leader's side. The half a game gets wrong is the other
+one, because nothing about it is visible from inside the member's frame.
+
+**The member is a room member before its game does anything.** The leader's one
+room call seated the whole party server-side. So the member's game boots into a
+world where it is already in a room, having made no room call — and if it does
+what a solo game does, it shows its own start menu and waits for a press.
+
+⚠️ **`seated` arrives in SDK 3.5.0, and an older build fails silently.** The
+listener registers happily and then never fires — no error, no warning — which
+reads exactly like the platform not sending the push, and sends the debugging
+somewhere there is nothing to find. Check what your game pins before you write
+the handler: it is the version of `@indiegems/gem-web-sdk` in `package.json` —
+or, in a project set up before 5.9.0, the version inside its download URL, which
+no dependency check reports as stale. Below 3.5.0, update the pin and reinstall
+first — `getting-started.md` §3 is the install.
+
+**Handle `seated`. That is the whole integration.**
+
+```js
+gem.rooms.on('seated', async (room) => {
+  if (room.roomType !== 'skirmish') return; // myRooms() also surfaces debris
+  await gem.rooms.join(room.id); // idempotent for a member
+  enterMatch();
+});
+```
+
+`seated` says this player holds a seat in a room this game never joined. It
+fires on the push gem-api sends when the party is seated, once when the game
+subscribes — which covers a seat that already existed while the game was still
+loading — and again whenever the tab comes back to the foreground. One handler
+covers all three, and a game that writes it has nothing else to do.
+
+⚠️ **A boot-time check alone is not enough, and this is the ordering that proves
+it.** Both players open the game and sit on their own start menus. *Then* the
+leader presses play. A `myRooms()` call at boot has long since run and found
+nothing; the seat appears afterwards, and without `seated` the member stays on
+the menu until they press the button themselves. Reproduced on prod 2026-08-29.
+
+`join()` on a room this player is already a member of is not a second join: the
+platform answers with the room. So is `quickJoin()` for the template the party
+is in. Either is safe, and a double fire — the push and the foreground check
+landing together, or the event arriving as the player presses your own button —
+costs one redundant request and never a second seat.
+
+The `roomType` filter matters: this player may also hold a room left behind by a
+page that closed without leaving, and that one is debris rather than an
+invitation.
+
+**What it costs when a game does not use it: nothing.** The watch behind the
+event — the push, the foreground check and a slow poll for the gap between them
+— is turned on by the subscription and by nothing else, so a game with no
+parties never makes a request for it. `createGem({ watchSeats: false })` turns it off for a game that subscribes and
+would rather ask on its own schedule; `rooms.reconcileSeats()` is then the
+manual check.
+
+**Quick-join also works, and is not the same thing.** Since 2026-08-29 the
+platform reads `party_id` off the membership row, so a member quick-joining for
+the template their party is in is handed that room rather than refused — the
+member's game is not broken if it does what a solo game does. What it costs is
+the point of having launched together: the player is sitting on a start menu
+they have to press, while the leader's match counts down. Adopting puts them in
+it. That is the whole difference, and it is a product difference rather than a
+correctness one.
+
+⚠️ **Before that date the same call answered 409 `already_in_matching_room`, with
+no way out.** A build shipped against an older platform — and any game reasoning
+about what a member's quick-join returns — should know the refusal existed: it
+was reported on prod on 2026-08-29 with a member pinned to the menu for a whole
+match. The recovery in `rooms-and-matches.md` §4.3b could not rescue it, for the
+reason the next paragraph gives, which is also why the fix had to be the
+server's: from inside the frame a party seat and a dead page's leftover are the
+same observation.
+
+**A member cannot leave, so do not offer them a button that says they can.** Only
+the party **leader** may take the group out of a room (`leave_as_group`); a
+member asking to leave alone is refused too, because a group that arrived
+together leaves together. Concretely, for a non-leader who has adopted the room:
+
+| The member's game calls | What comes back |
+| --- | --- |
+| `rooms.leave()` (group leave, the default) | **403** — leader-only |
+| `rooms.leave({ asGroup: false })` | **409** `party_member_cannot_leave_game_room` |
+| `rooms.leaveAll()` | the party room stays; `leaveAll()` is best-effort per room and swallows the refusal, so it returns without that id |
+
+So a "leave match" affordance on a member's screen is a button that cannot work.
+Leaving the party is the parent page's surface (§7.1), not the frame's — and it
+is where a member's exit belongs.
+
+**And it is why `rooms-and-matches.md` §4.3b's recovery never covered this.**
+That recovery clears a membership and retries once. A party seat is not clearable
+by the player holding it — the table above is the whole reason — so the clear
+frees nothing and the refusal it was recovering from is raised again. The
+platform answering a party member's quick-join with the room takes that path out
+of the ordinary case entirely. It is still reachable in an unusual one: a party
+seated in a room of **one** template while the member's game quick-joins for
+**another**. There the platform's own membership cap refuses, nothing can be
+cleared, and the SDK raises a refusal that names the party cause — because a game
+that just ran the documented recovery has every reason to think the room is gone.
+Adopting is the answer there too: the room to be in is the one the party is in.
+
+---
+
+## 8. Capabilities
+
+Two new tokens, both `implemented: true`, both gating in **both** directions:
+
+| Capability | Gates                                 | Advertised by a parent that…                                                                                  |
+| ---------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `p2p`      | `gem.signal`, `gem.signalEvent`       | holds the notification socket **and** enforces the outbound allowlist, the per-second budget and the size cap |
+| `parties`  | `gem.partyRequest`, `gem.partyResult` | can resolve the signed-in player's party                                                                      |
+
+`p2p` is the first gated **frame→parent** message type, which makes the parent's
+own receive-side capability check reachable for the first time. That check was
+written for a case that did not exist yet; it exists now.
+
+Advertising `p2p` without wiring `onSendSignal` is the one arrangement worse than
+not advertising it — the game believes it has signaling and every offer vanishes —
+so the parent answers that case with a named refusal rather than a silent drop.
+
+---
+
+## 9. Scope
+
+**In:** the P2P connection lifecycle end to end — signaling over the bridge, peer
+connections and data channels, trickled ICE, host migration with acknowledgement,
+peer authentication in both directions, leave and kick, the TURN lease, the
+reconnection story, and the telemetry the platform already accepts. Plus the
+parent-side party surface, the party pushes, and the frame's auto-attach. And
+the listen host: `gem.match.serve` running a `defineServer` bundle over this
+session, with two honest gaps — a P2P `kick` carries no reason, and
+`gem.log`/`gem.warn` go to the browser console.
+
+**Out:** replication, state sync, prediction, rollback, interest management. A
+browser game gets connections and data channels; what it sends over them is its
+own.
+
+**Out:** a game-facing party roster, and the party game-launch and room-proposal
+flows. Those are launcher and Arcade orchestration, not something a running game
+frame participates in.
+
+**Out:** voice over these peer connections. The platform has voice sessions, and
+the server side of a match allocates and tears them down — see
+[`server-bundles.md`](server-bundles.md). Those sessions are themselves WebRTC
+and the player's browser connects to one the platform runs. None of that travels
+over this transport, and signaling is not a route to adding it: SDP carrying an
+active audio or video section is refused in both directions.
+
+**Out:** mesh topology. gem-api assumes a star throughout — offers are refused
+from the host, answers are addressed by the host, migration elects one
+replacement — and the native client hardcodes a star topology.
+
+## 10. What the BRIDGE bundle gets from this: nothing
+
+⚠️ **This section is about `gem-web-sdk.bridge.js`, and that is not the bundle a
+game loads.** There are two IIFEs:
+
+|                                                                         | Carries                                                                                               |
+| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `gem-web-sdk.bridge.js` — **the bridge bundle**, this section's subject | the bridge and the generated protocol, and nothing else                                               |
+| `gem-web-sdk.min.js` — the classic script **older pages still load**    | the unified SDK: `createGem`, rooms, the dedicated flow, `defineServer`, `gem.match`, **all of this** |
+
+Rooms, the dedicated flow and everything here live in the game bundle and the ESM
+bundle — the bridge bundle carries none of it. It is built for its size budget and
+is not published.
+
+So the statement worth being exact about is about **artifacts**, not about how a
+game is delivered: **P2P is in the bundle a game imports —
+`@indiegems/gem-web-sdk/sdk` — and it is not in the bridge bundle.** An earlier
+version of this section phrased the distinction in terms of how a game loaded the
+SDK, which was true only of the bridge bundle and read as a denial to games that
+had `gem.p2p` in full. A game installs the package and imports it
+([getting-started](getting-started.md#3-add-the-sdk)); the distinction that
+survives is between the two IIFEs, and neither of them is what a game bundles.