@indiegems/gem-web-sdk 8.1.0 → 9.1.0

package/docs/room-shapes.md

@@ -1,12 +1,14 @@
-# Room shapes — the four things a game room is for
+# Room shapes — the three things a game room is for
 
-A game room is one mechanism with four useful shapes. The same browser surface (`gem.rooms` to get
-in, `gem.match.connect()` to reach the authority) and the same server entry point (`defineServer`)
-serve all four; what differs is the room template and what the hosting server chooses to do with
-its time.
+A game room is one mechanism with three useful shapes. The same browser surface (`gem.rooms` to
+get in, `gem.match.connect()` to reach the authority) and the same server entry point
+(`defineServer`) serve all three; what differs is the room template and what the hosting server
+chooses to do with its time.
 
-Only three of the four need a second player. The fourth is for a game that has no multiplayer at
-all and still needs something a browser cannot be trusted to do.
+A room is for players who share something live. A game with no real-time match that still needs
+something a browser cannot be trusted to do — a run verified, a score checked before it counts, a
+reward granted — does not need a room or a game server. That is a serverless function:
+[serverless-functions.md](serverless-functions.md).
 
 This page is the decision. [rooms-and-matches.md](rooms-and-matches.md) is the mechanism behind
 it — the room state machine, the event stream, room args, reconnection — and is what to read once
@@ -16,14 +18,12 @@ you know which shape you want.
 
 Answer in this order. The first yes wins.
 
-1. **Does the server need to run a match at all**, or only answer requests from clients who are
-   not playing each other? Only answer requests → **authoritative worker**.
-2. **Does one player decide when a round starts, and with what settings?** → **custom**.
-3. **Do players arrive and leave continuously, with the world outliving any one of them?** →
+1. **Does one player decide when a round starts, and with what settings?** → **custom**.
+2. **Do players arrive and leave continuously, with the world outliving any one of them?** →
    **hub**.
-4. Otherwise a lobby fills and plays one match → **match**.
+3. Otherwise a lobby fills and plays one match → **match**.
 
-## The four
+## The three
 
 ### Match
 
@@ -53,31 +53,6 @@ A hub is **served** or **unserved**, and `match_type` decides which:
 Reach for `none` when nothing needs simulating. A lobby that needs a member list and a settings
 object does not need a server, and a served hub costs one.
 
-### Authoritative worker
-
-A room whose server **runs no match**. It accepts no player input, replicates no world state,
-simulates nothing. It answers requests from members who are not playing each other, and each
-member's session is unrelated to every other member's.
-
-This is how a browser game reaches an execution context a modified client cannot rewrite. Use it
-when something must be decided on your behalf rather than the player's, and the platform has no
-built-in rule for it:
-
-- Confirming an offline, single-player run really was finished, and to the score claimed.
-- Granting an award whose condition is game state — level reached, boss defeated, run completed
-  under a time — that only your game code can evaluate.
-- Checking a score before it counts.
-
-**A game with no multiplayer can need this shape.** The room is not a lobby; it is a way to get
-your own code running somewhere the player does not control.
-
-If a check out of the player's reach is all you want the room for, a serverless function is the
-smaller tool: no room, no seat and no connection, one call at a time. See
-[serverless-functions.md](serverless-functions.md).
-
-Two things decide whether you need it at all. See
-[what a worker owes you, and what it does not](#what-a-worker-owes-you-and-what-it-does-not).
-
 ### Custom
 
 A room one player owns, where a group gathers and plays round after round. The owner picks the
@@ -91,16 +66,16 @@ from a list hard-coded in your client — then the config can add a mode without
 
 ## The settings that produce each
 
-|                          | Match             | Hub                   | Worker      | Custom                |
-| ------------------------ | ----------------- | --------------------- | ----------- | --------------------- |
-| `match_type`             | `dedicated`/`p2p` | `dedicated` or `none` | `dedicated` | `dedicated`/`p2p`     |
-| `auto_start_host`        | `true`            | `true`                | `true`      | **`false`**           |
-| `min_players`            | the match size    | `1`                   | `1`         | `1`                   |
-| `allow_join_in_progress` | for backfill      | **`true`**            | **`true`**  | `false`               |
-| `show_in_browser`        | `false`           | `true`                | `false`     | when public           |
-| `transports`             | the ladder        | the ladder            | the ladder  | the ladder            |
-| How a player gets in     | `quickJoin`       | `quickJoin`           | `quickJoin` | `create`/`joinByCode` |
-| What starts the match    | `min_players`     | `min_players`         | first join  | the owner             |
+|                          | Match             | Hub                   | Custom                |
+| ------------------------ | ----------------- | --------------------- | --------------------- |
+| `match_type`             | `dedicated`/`p2p` | `dedicated` or `none` | `dedicated`/`p2p`     |
+| `auto_start_host`        | `true`            | `true`                | **`false`**           |
+| `min_players`            | the match size    | `1`                   | `1`                   |
+| `allow_join_in_progress` | for backfill      | **`true`**            | `false`               |
+| `show_in_browser`        | `false`           | `true`                | when public           |
+| `transports`             | the ladder        | the ladder            | the ladder            |
+| How a player gets in     | `quickJoin`       | `quickJoin`           | `create`/`joinByCode` |
+| What starts the match    | `min_players`     | `min_players`         | the owner             |
 
 Templates live in your game config under `game_room_templates`, and are uploaded and promoted per
 channel like the rest of it. `transports` is the same on every shape because it is orthogonal to
@@ -119,8 +94,7 @@ quietly becomes one world per player.
 
 ## What the platform decides for you
 
-Four limits bind every shape, and three of the four shapes exist partly to work around one of
-them.
+Four limits bind every shape.
 
 **Seats belong to the template, not to the room.** A create request carrying its own
 `max_players` is refused rather than having the field ignored. The template's count is not
@@ -130,7 +104,7 @@ from what one process can carry.
 
 **A match has a maximum duration.** `max_match_duration_seconds` defaults to 21600 — six hours —
 after which the platform ends the match the way any end happens: members get the ordinary
-`match_ended` push and the server is released. **Nothing here runs forever.** A hub or a worker is
+`match_ended` push and the server is released. **Nothing here runs forever.** A hub is
 recycled, not permanent, and has to be written that way: durable state belongs in player save
 data or your own store, written as it changes rather than at shutdown, and the client re-enters
 on the room's `matchEnded` event (reason `expired`, `roomReopened: true`) rather than treating it
@@ -150,37 +124,39 @@ server per player.
 behind a shared fence, so an `auto_start_host` template and a client that also calls start cannot
 race into two matches.
 
-## What a worker owes you, and what it does not
-
-The worker shape is the one most easily got wrong, in both directions.
-
-**It is not the answer to economy arithmetic.** Spending a currency and granting an item is a
-**recipe**, and a recipe is already evaluated on the platform's side where a modified client
-cannot change the arithmetic — no server of yours, no allocation, no seat. See
-[inventory-and-catalogs.md](inventory-and-catalogs.md). A worker room is for validating game state
-the platform knows nothing about. A worker that grants _after_ validating is doing both: decide
-here, then let the grant itself be a recipe or an order.
+## What a server in a room owes you
 
 **Its server must check its own roster.** A server bundle's credential is scoped to your game and
 channel, not to its match, and the room roster is not a boundary the platform enforces on it. A
 bundle can therefore act on any player of your game, including one who never joined its room.
-That is needed by an ordinary match server writing results — and it means a worker that skips its
-own membership check is an open grant endpoint wearing a room as decoration. Read the roster and
-check the requesting player against it before acting; not against an id the client sent.
-
-**A result against a daily's board is checked against the platform's copy, never the client's.**
-When your studio stores each period's content with the challenge, the worker reads it with
-`gem.challenges.list({ playerId })` — for the player who submitted, whose period is their own, for
-the current period and, with `periodsBack: 1`, the one before, so a run finished just before the
-rollover still verifies — and validates against the entry whose `periodLocalDate` (a cron
-challenge's `seed`) and `dataHash` match what the client submitted, never its `periodStartAt`. No
-match is a rejection. [daily-challenges.md](daily-challenges.md#verifying-a-result-against-the-content) has
+That is needed by an ordinary match server writing results — and it means a server that acts
+because a client asked it to must read the roster and check the requesting player against it
+first; not against an id the client sent.
+
+**It should hold no player state between joins.** Each join is a session, not an identity. A
+returning player may be in a completely different state than when they left, and the process may
+have served hundreds of others in between.
+
+## When you do not need a room
+
+A room, and the server behind it, is for a real-time match: the server is the authority, corrects
+what players do, and replicates the state of the game to everyone in it. Such a server can also
+verify results and grant progression and rewards for the match it ran.
+
+Everything else that must happen out of the player's reach is a **serverless function**:
+confirming a single-player run really was finished and to the score claimed, checking a score
+before it reaches a leaderboard, anti-cheat, updating progression, granting a reward whose
+condition only your game code can evaluate. A function needs no room, no seat and no connection,
+costs less and scales further. See [serverless-functions.md](serverless-functions.md).
+
+Two things are not a function's job either. Spending a currency and granting an item is a
+**recipe**, already evaluated on the platform's side where a modified client cannot change the
+arithmetic — see [inventory-and-catalogs.md](inventory-and-catalogs.md); a function that has
+decided a player earned something still makes the grant itself a recipe or an order. And a result
+against a daily's board is checked against the platform's copy of that period's content, never the
+client's — [daily-challenges.md](daily-challenges.md#verifying-a-result-against-the-content) has
 the recipe.
 
-**It should hold nothing between joins.** Each join is an unrelated session. A returning player
-may be in a completely different state than when they left, and the process may have served
-hundreds of others in between.
-
 ## Where to go next
 
 - [rooms-and-matches.md](rooms-and-matches.md) — the browser half in full: the room state
@@ -193,3 +169,5 @@ hundreds of others in between.
 - [p2p-and-parties.md](p2p-and-parties.md) — the shapes that run without a server of ours.
 - [inventory-and-catalogs.md](inventory-and-catalogs.md) — what a server calls once it has
   authority.
+- [serverless-functions.md](serverless-functions.md) — your own check out of the player's reach,
+  with no room and no game server.

package/docs/rooms-and-matches.md

@@ -6,9 +6,8 @@ carrying the engine's model should transfer with no friction, and where the web
 engine this document says why.
 
 > **Which SHAPE of room you want is decided first, on
-> [`room-shapes.md`](room-shapes.md)** — a match, a hub players drift through, a custom lobby one
-> player owns, or an authoritative worker whose server runs no match at all. This page is the
-> mechanism underneath all four.
+> [`room-shapes.md`](room-shapes.md)** — a match, a hub players drift through, or a custom lobby one
+> player owns. This page is the mechanism underneath all three.
 
 > **This page is the SDK's model. The platform's own rules are
 > [`platform-rules.md`](platform-rules.md)** — what gem-api enforces underneath, none of which is

package/docs/server-bundles.md

@@ -80,8 +80,8 @@ To check the download yourself: the package npm serves is, byte for byte, the fi
 also publishes on its download host, with the hash beside it:
 
 ```bash
-curl -fsSL -O https://downloads.gemarcade.com/sdk/v8.1.0/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v8.1.0/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v9.1.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v9.1.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

package/docs/serverless-functions.md

@@ -35,10 +35,11 @@ Two cases look like a function and are not:
   a dedicated server, and [server-bundles.md](server-bundles.md) is how you write one. A function
   holds nothing between calls.
 
-A function is also the smaller answer to a need [room-shapes.md](room-shapes.md#authoritative-worker)
-meets with an **authoritative worker** room. If you were going to allocate a worker room only to
-run your own check out of the player's reach, a function does the same job with no room, no seat
-and no connection to open, and each call is its own run.
+A function is the answer whenever your own check has to run out of the player's reach and no
+real-time match is running: verifying a run or a score, anti-cheat, updating progression, granting
+a reward. It needs no room, no seat and no connection to open, and each call is its own run. A game
+with no multiplayer does not need a game server for any of this.
+[room-shapes.md](room-shapes.md#when-you-do-not-need-a-room) draws the line from the other side.
 
 ⚠️ **A verdict you return to the browser is advice to the client you do not trust.** If your
 function decides a player earned something and returns `{ "ok": true }`, a modified client can skip
@@ -440,18 +441,22 @@ on every request your function makes.
 
 ### The limits on one call
 
-These are the platform's limits, the same for every game, and a game cannot raise its own.
-
-| Limit                                               | Value                                  |
-| --------------------------------------------------- | -------------------------------------- |
-| Wall clock                                          | 5 seconds                              |
-| CPU                                                 | 1 second of that 5                     |
-| Memory                                              | 64 MiB                                 |
-| `call-api`, `download-link` and `upload-link` calls | 32, all three together                 |
-| Input                                               | 256 KiB                                |
-| Output                                              | 1 MiB                                  |
-| Component size                                      | 32 MiB                                 |
-| Calls, per caller per minute                        | 30 for a player, 120 for a game server |
+These are the platform's limits, the same for every game, and a game cannot raise its own. If your
+game needs more memory, CPU, time or calls than they allow, ask for the limit to be raised: the
+platform raises a function's limits so the game can stay on a function. Reaching one is never a
+reason to move the work to a game server.
+
+| Limit                                                                          | Value                                  |
+| ------------------------------------------------------------------------------ | -------------------------------------- |
+| Wall clock                                                                     | 5 seconds                              |
+| CPU                                                                            | 1 second of that 5                     |
+| Memory                                                                         | 64 MiB                                 |
+| `call-api`, `download-link` and `upload-link` calls                            | 32, all three together                 |
+| A value handed to one `log`, `call-api`, `download-link` or `upload-link` call | 16 MiB                                 |
+| Input                                                                          | 256 KiB                                |
+| Output                                                                         | 1 MiB                                  |
+| Component size                                                                 | 32 MiB                                 |
+| Calls, per caller per minute                                                   | 30 for a player, 120 for a game server |
 
 **The per-minute budget belongs to the caller, not to your game.** A player who spends theirs is
 refused and nobody else is affected. Thirty a minute is also why a function call belongs at a
@@ -767,7 +772,9 @@ or `game_server`:
 - **A line your function logged**: its `level` and its `message`.
 - **The closing line**: `outcome` is `ok`, `error`, `timeout`, `cpu_exceeded` or `failed`, with the
   call's `wall_ms` and `cpu_ms`. On `error`, `message` is your `Err` text. On `failed`, `reason`
-  says what ended the call, and when your own code trapped, `message` is the trap's message.
+  says what ended the call, and when your own code trapped, `message` is the trap's message. When
+  `reason` is `output_too_large` or `argument_too_large`, `detail` names the limit the call
+  exceeded. The platform writes it and never copies your function's data into it.
 
 Newest first means a call's closing line comes before what it logged. **A call's logging is
 capped**: once it reaches its per-call log limit, that `log` call and every later one go
@@ -795,24 +802,27 @@ Every answer from a call that reached your function carries an invocation id: su
 refused before that point never became an invocation and carries none. `err.retryable` agrees with
 the last column: it is `true` exactly where this table says to retry.
 
-| What you get                                               | What happened                                                                                             | What to do                                                             |
-| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| `422 function_error`                                       | Your `handle` returned `Err`. The text is `err.functionMessage`                                           | Fix your code or the input. Return verdicts in `Ok`                    |
-| `422 function_failed`                                      | It did not finish. `err.failure` is `trap`, `memory_exceeded`, `cpu_budget_exceeded` or `host_call_limit` | A bug or a limit in the function. Reproduce with the same input        |
-| `504 function_timeout`                                     | It ran past the wall clock                                                                                | Do not retry: the same input takes as long again                       |
-| `404 function_not_published`                               | Nothing is promoted on the caller's channel                                                               | `gemctl function promote <version> --channel <channel>`                |
-| `413 function_input_too_large`                             | The input is over 256 KiB                                                                                 | Send a request, not a file                                             |
-| `429 rate_limited`                                         | This caller's per-minute budget is spent                                                                  | Wait `err.retryAfterSeconds`                                           |
-| `503 function_capacity_unavailable`                        | The platform was too busy to run it. Your function is not known to be broken                              | Retry after `err.retryAfterSeconds`                                    |
-| `503 function_host_unreachable`, `503 function_host_error` | The platform could not run it. Nothing about your function                                                | Retry shortly. Quote the invocation id if it persists                  |
-| `503 service_unavailable`                                  | The platform could not check the caller's budget, so it refused the call. The function did not run        | Retry shortly                                                          |
-| `503 functions_not_configured`                             | Functions are switched off on the backend you called                                                      | Do not retry. Nothing about your function or your game                 |
-| `403 forbidden`                                            | The call carried an account sign-in rather than a game-scoped or game-server token                        | Call from your game or its server, or through `gemctl function invoke` |
+| What you get                                               | What happened                                                                                                                                       | What to do                                                             |
+| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `422 function_error`                                       | Your `handle` returned `Err`. The text is `err.functionMessage`                                                                                     | Fix your code or the input. Return verdicts in `Ok`                    |
+| `422 function_failed`                                      | It did not finish. `err.failure` is `trap`, `memory_exceeded`, `cpu_budget_exceeded`, `host_call_limit`, `output_too_large` or `argument_too_large` | A bug or a limit in the function. Reproduce with the same input        |
+| `504 function_timeout`                                     | It ran past the wall clock                                                                                                                          | Do not retry: the same input takes as long again                       |
+| `404 function_not_published`                               | Nothing is promoted on the caller's channel                                                                                                         | `gemctl function promote <version> --channel <channel>`                |
+| `413 function_input_too_large`                             | The input is over 256 KiB                                                                                                                           | Send a request, not a file                                             |
+| `429 rate_limited`                                         | This caller's per-minute budget is spent                                                                                                            | Wait `err.retryAfterSeconds`                                           |
+| `503 function_capacity_unavailable`                        | The platform was too busy to run it. Your function is not known to be broken                                                                        | Retry after `err.retryAfterSeconds`                                    |
+| `503 function_host_unreachable`, `503 function_host_error` | The platform could not run it. Nothing about your function                                                                                          | Retry shortly. Quote the invocation id if it persists                  |
+| `503 service_unavailable`                                  | The platform could not check the caller's budget, so it refused the call. The function did not run                                                  | Retry shortly                                                          |
+| `503 functions_not_configured`                             | Functions are switched off on the backend you called                                                                                                | Do not retry. Nothing about your function or your game                 |
+| `403 forbidden`                                            | The call carried an account sign-in rather than a game-scoped or game-server token                                                                  | Call from your game or its server, or through `gemctl function invoke` |
 
 A `trap` is a panic, an `unreachable`, an out-of-bounds access or a stack overflow, and no stack
 trace comes back with it. On `dev`, the call's closing line in `gemctl function logs` carries the
-trap's message when your own code trapped (section 7). The other three reasons are the limits in
-section 2.
+trap's message when your own code trapped (section 7). The other five reasons are the limits in
+section 2. Two of them are about size: `output_too_large` is a result over the 1 MiB output cap,
+and `argument_too_large` is a value your function handed to `log`, `call-api`, `download-link` or
+`upload-link` that was over the 16 MiB one call accepts. On `dev`, the closing line of either
+carries `detail`, naming the limit the call exceeded.
 
 Publishing has its own refusals, and nothing is stored when one happens:
 

package/docs/what-a-game-must-do.md

@@ -53,8 +53,9 @@ No `baseUrl`. The Arcade names the backend on every token and the SDK routes the
 tokens only if its origin is allowed, and the pages that matter are always allowed without a word
 from you:
 
-- **the Gem Arcade website and app** — the SDK carries their origins as `ARCADE_EMBEDDERS`, on every
-  platform the app runs on;
+- **the platform's websites (Gem Arcade and Meme Games) and the Gem Arcade app** — the SDK carries
+  their origins as `ARCADE_EMBEDDERS`, on every platform the app runs on. Your game is listed on
+  one of the websites, but it accepts every origin in that list;
 - **a dev host on your own machine** — `gemctl serve` and the Gem Editor frame a locally-served game
   from a loopback origin whose port changes every run, and the SDK admits that shape by rule, only
   while your game itself is served from loopback. Once published, nothing about the rule applies.
@@ -527,7 +528,10 @@ credit for it until you say so.
   inventory and dialog operable on the standard gamepad mapping with the pointer unused, and a focus
   cue thicker than a hairline — a 1px outline disappears at ten feet. TV remotes arrive as
   **keyboard-class events** (arrows, Enter, Back), so a game that calls itself a keyboard game is a
-  D-pad game on a TV whether it planned to be or not.
+  D-pad game on a TV whether it planned to be or not. One control a gamepad cannot work: a
+  rewarded-ad button. Browsers do not count gamepad input as a press, so a rewarded ask made from
+  one is refused ([`rewarded-ads.md` §3](rewarded-ads.md#3-ask-from-the-press-then-re-read)). A
+  remote's keys do count. Keep the ordinary way on beside the button working.
 - **Title-safe layout.** HUD and critical UI inset at least ~5% of the frame — roughly 48–96px at
   1080p. `env(safe-area-inset-*)` resolves to **0 on every TV**: overscan is a hardware crop the
   browser cannot see, so no platform can hand you the number and your game must apply its own
@@ -1281,6 +1285,13 @@ rather than a failure; nothing rejects, so there is no error branch to write; an
 nothing, so a reward must never be handed out on the strength of it.
 [`cross-promotion.md`](cross-promotion.md) is the page.
 
+A button the player presses for a reward — a revive, an extra attempt — is the same call with
+`format: 'rewarded'`, made from that press itself. The button says it is an ad and names the
+reward, and the Arcade starts the ad as soon as the ask arrives. Your game config declares what
+each such button grants, the platform writes the reward into your game's inventory, and your game
+reads it there rather than from the answer.
+[`rewarded-ads.md`](rewarded-ads.md) is that page.
+
 ## An account upsell, if your game has something to offer one
 
 Not on the list above either. When a player reaches for something only an account gives them,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "8.1.0",
+  "version": "9.1.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",

package/schema/bridge.v1.json

@@ -3203,6 +3203,21 @@
         "",
         "  RENDER IT IN YOUR OWN CHROME. Labelled as a promotion, dismissible, and",
         "  focus-trapped over the paused game. Nothing in this message is rendered.",
+        "  For `rewarded`, the player pressed the game's button, and THAT PRESS IS",
+        "  THE OPT-IN: the game's label says it is an ad and names the reward, so",
+        "  start the ad without a prompt of your own. Label it as an ad for as long",
+        "  as it plays, and let the player close it; closing early is a skip and",
+        "  pays nothing. Where no ad could play and nothing was granted, say so",
+        "  briefly in your own chrome ('No ad available right now').",
+        "",
+        "  DO NOT RELY ON THE FRAME HAVING CHECKED FOR A PRESS. SDK releases after",
+        "  9.0.0 send a rewarded ask only while the frame holds user activation,",
+        "  where the browser reports it. Every SDK from 5.1.0 to 9.0.0 sends one",
+        "  with no such check, so a game pinned to one of those can ask from a",
+        "  timer and start an ad with no press, and a hostile frame posts on the",
+        "  port directly. Even the check cannot say which press caused an ask:",
+        "  activation belongs to the whole frame for a few seconds, so an ask from",
+        "  the game's jump button passes it too.",
         "",
         "  PAUSE WITH `gem.pause`. That message already means 'stop running and stop",
         "  making noise', which is exactly what is wanted while a panel is up. Do",
@@ -3224,10 +3239,14 @@
         "  generated validator checks type and length only - it may carry `../`,",
         "  NUL, newlines, RTL overrides and astral Unicode. The SDK will only SEND",
         "  `^[a-z0-9_-]{1,32}$`, which is the grammar the platform's own ad",
-        "  endpoint accepts - but that is the sender keeping a promise, not a",
-        "  guarantee you hold: a hostile frame posts on the port directly. It is",
-        "  matched against nothing, never interpolated into a path or a log line,",
-        "  and never shown to a player.",
+        "  endpoints accept - but that is the sender keeping a promise, not a",
+        "  guarantee you hold: a hostile frame posts on the port directly. For an",
+        "  interstitial it is matched against nothing. For `rewarded` it is the key",
+        "  of the reward the game's config declares, so check it against that",
+        "  grammar YOURSELF before forwarding it, in a request body, to the",
+        "  platform's rewarded offer. Never interpolate it into a path or an",
+        "  unchecked log line, never show it to a player, and NEVER SEND IT TO AN",
+        "  AD NETWORK: it stops at the platform, as every game-authored string does.",
         "",
         "  THE `perMinute` BELOW BOUNDS A BUGGY GAME, NOT A HOSTILE ONE. A hostile",
         "  game posts on the port it holds rather than calling the SDK, so a",
@@ -3243,12 +3262,12 @@
         "placement": {
           "kind": "string",
           "maxLength": 32,
-          "$comment": "The game's own name for the break it is at - 'level-complete', 'between-rounds'. UNTRUSTED TEXT, MATCHED AGAINST NOTHING BY TODAY'S PARENT: it does not look it up, does not vary its decision on it and does not render it. THE BOUND IS THE PLATFORM'S OWN, not a number chosen here: the ad endpoint behind the arcade accepts `^[a-z0-9_-]{1,32}$` and answers 400 otherwise, so 32 is what this carries and the SDK refuses the charset before sending. A real ad network keys its ad units BY placement - that is what the field is for - so the day one is swapped in the parent starts forwarding this string unchanged, and a game that shipped 'Boss Fight' or a 40-character name would have to be rebuilt. The grammar is narrow NOW, while nothing has shipped against it, so a game learns at development time instead. Codegen emits type and length only; the charset is the sender's to keep."
+          "$comment": "The game's own name for the break it is at - 'level-complete', 'classic_revive'. UNTRUSTED TEXT, never rendered. FOR AN INTERSTITIAL IT IS MATCHED AGAINST NOTHING: the parent does not look it up and does not vary its decision on it. FOR `rewarded` IT NAMES THE REWARD the game's config declares in `rewarded_placements`: the parent forwards it unchanged to the platform's rewarded offer, which matches it against that config, and a placement the config does not declare is answered `no_ad`. IT NEVER REACHES AN AD NETWORK, for either format, because a game-authored string that fits this grammar fits a dashless UUID too and would be an identifier channel to a third party. THE BOUND IS THE PLATFORM'S OWN, not a number chosen here: the platform's ad endpoints accept `^[a-z0-9_-]{1,32}$` and answer 400 otherwise, and config upload holds a declared placement to the same grammar, so 32 is what this carries and the SDK refuses the charset before sending. A game that shipped 'Boss Fight' or a 40-character name would have to be rebuilt to reach its reward, so the SDK refuses it at development time instead. Codegen emits type and length only; the charset is the sender's to keep."
         },
         "format": {
           "kind": "enum",
           "values": ["interstitial", "rewarded"],
-          "$comment": "A closed set, so a typo is refused at the boundary rather than left for the parent to interpret. `rewarded` IS IN THE GRAMMAR AND IS NOT SERVED: it is answered `no_ad` today, and a `shown` would grant nothing even when it is not - see gem.adResult's outcome. A game that grants a reward on an outcome has a reward any page that can post on this port can forge."
+          "$comment": "A closed set, so a typo is refused at the boundary rather than left for the parent to interpret. `rewarded` IS SERVED WHERE THE PARENT SERVES IT, and answered `no_ad` where it does not. Either way a `shown` grants nothing - see gem.adResult's outcome: the platform grants a rewarded placement's reward itself, into the game's own inventory, against its own record. A game that grants a reward on an outcome has a reward any page that can post on this port can forge."
         }
       },
       "rateLimit": {
@@ -3277,6 +3296,23 @@
         "  unavailable - the shell could not render at all just now. NOT a softer",
         "                no; a game reads it identically to `no_ad`.",
         "",
+        "AFTER A `rewarded` ASK the player pressed a button, so two of those",
+        "readings change. `shown` means the parent painted something for the ask",
+        "and it has closed - the ad, however it ended - and still grants nothing.",
+        "`no_ad` can arrive with the reward already granted - where no ad serves",
+        "and the game's config says to grant without one, for one - so a game",
+        "reads its own inventory, never the outcome, to learn whether a reward",
+        "landed. And where nothing new landed, a neutral 'no reward this time'",
+        "line from the game is right, because the player is waiting on their own",
+        "press; it must never guess a reason.",
+        "",
+        "THAT INVENTORY IS A SECOND CHANNEL, AND THE RULE BELOW DOES NOT CLOSE IT.",
+        "The rule closes the outcome. Whether a reward landed is visible to the",
+        "game by design, so which `no_ad` branches grant one is a disclosure the",
+        "platform decides where it makes the grant. A parent adds nothing to it:",
+        "it never grants, and it answers a rewarded ask exactly as below whatever",
+        "was granted.",
+        "",
         "THREE VALUES, AND THAT IS THE COMPLETE VOCABULARY. `no_ad` absorbs the",
         "feature being switched off, an empty catalogue once the running game is",
         "excluded, a frequency cap that has not expired, and a player whose",