@indiegems/gem-web-sdk 7.3.1 → 7.4.1

package/docs/serverless-functions.md

@@ -0,0 +1,748 @@
+# Serverless functions
+
+A **function** is a small piece of your own code that the platform runs when your game calls it.
+Your game sends some bytes, the platform hands them to your function, and your function's answer
+comes back. It runs where the player cannot reach it, and nothing of yours has to be running for
+it to answer.
+
+Most games need none. A function earns its place when your game needs a decision that a player's
+browser cannot be trusted to make, and nothing the platform already does makes it for you. Read
+section 1 before you write one: two of the commonest reasons to reach for a function are better
+served by something else.
+
+## 1. Do you need one
+
+Everything in a player's browser belongs to the player. They can read your code, change it, and
+send the platform whatever they like. A function is somewhere your code runs that they cannot
+change: checking that a finished run was plausible, or granting a reward whose condition is game
+state only your code can judge.
+
+It is also how a game **with no dedicated server** pays a platform currency — Gems (`GEMS`) or
+Tickets (`ARCADE_TICKETS`) — or unlocks an achievement. A browser write
+never does either. A function a player calls may, for **that player only**, on a progression you
+opt in. Section 2's
+[Paying the player who called](#paying-the-player-who-called) is the whole of it. Opting in makes
+your function the part of your game that decides what the player earned, with nothing else
+checking it.
+
+Two cases look like a function and are not:
+
+- **Spending currency, granting an item, opening a loot box.** That arithmetic is a **recipe**, and
+  the platform already runs recipes where a modified client cannot change them. See
+  [inventory-and-catalogs.md](inventory-and-catalogs.md). A function that has decided a player
+  earned something still makes the grant itself an order or a recipe.
+- **A match with live state.** Players moving in a shared world, a simulation that ticks: that is
+  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 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
+the call and behave as though it got that answer. Whatever the function decides has to happen
+_inside_ the function: it writes the result through the platform API itself (`call-api`, section
+2), and the browser only learns what was done.
+
+⚠️ **The input is whatever the caller sent.** The platform vouches for one thing about a call: who
+made it. A score in the input is the player's claim. A function that reads a score from its input
+and writes it back has checked nothing. Check the claim against what the player cannot forge,
+such as the platform's own records (which `call-api` reads) and what your game's rules make
+possible.
+
+## 2. What a function is
+
+A function is one WebAssembly **component** per game per channel, built against the platform's
+`gem:functions` world. It exports exactly one function:
+
+```wit
+export handle: func(input: list<u8>) -> result<list<u8>, string>;
+```
+
+- `input` is the request body, byte for byte. What the bytes mean is up to your game and your
+  function. JSON is the usual choice, and section 6 explains why it is the easy one.
+- `Ok` bytes are the response body, byte for byte.
+- `Err` text is your own error message. The call fails, and the game reads the text as
+  `err.functionMessage` (section 6). Keep `Err` for input your function could not handle at all: a
+  verdict your game acts on, such as "too fast", is an answer, so it belongs in `Ok`.
+
+**Nothing survives between calls.** Each call gets a fresh instance, and the instance is thrown
+away when `handle` returns. A global you set is gone by the next call. State lives behind the
+platform API.
+
+The component imports one interface, `gem:functions/host`, and nothing else. That interface is
+everything a function can reach:
+
+| Host call       | What it gives you                                                                                                          |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `get-context`   | The game id, the channel, this call's invocation id, and **who called**: a player by id, or a game server by its server id |
+| `call-api`      | One request to the platform API, made **as your game's server**: a method, a `/v1/` path and a JSON body, and nothing else |
+| `download-link` | A save's contents, fetched from the download link the save's record carries                                                |
+| `upload-link`   | A save's new contents, sent to the upload link the platform issued for them                                                |
+| `log`           | A line kept on the platform under this call's invocation id, cut at 1 KiB                                                  |
+| `random-bytes`  | Randomness. The function has no other source                                                                               |
+| `now-ms`        | Unix time in milliseconds. The function has no other clock                                                                 |
+
+**`call-api` acts for your game, not for the player who called.** It carries your game's server
+authority whoever made the call. Take the player id from `get-context`, never from the input. The
+input is the caller's claim about who they are; `get-context` is the platform's answer. A route
+that refuses a game-server token refuses `call-api` too. When a **player** made the call, the
+platform also holds every write to that player: the next subsection.
+
+### What a function a player called may change
+
+**Only the calling player's own state.** A function a player called may change:
+
+- that player's inventory, currencies, items and progressions — dailies and challenges included;
+- that player's **own characters**;
+- that player's saves, settings and showcase values, their async-opponent records, the
+  leaderboard runs of that player and their characters, and the analytics events attributed to
+  them;
+- transfers **out of** that player's own inventory, to anyone the item's transfer policy allows.
+
+**Any write that targets another player, or another player's character, is refused with
+`403 function_foreign_entity_write`, and nothing is written.** It does not matter what the write
+is: an order, a progression `add`, `max`, `reset` or `claim`, a recipe, a save, a setting, a
+leaderboard run, a transfer out of someone else's inventory, a room kick or host transfer naming
+someone else. A batch of runs that names anyone else is refused whole, but an analytics batch
+rejects each event attributed to someone else with the same code and keeps the rest. Reads are not
+writes: the function may still read another player's state where your game server could, and
+simulating an order for them changes nothing.
+
+A transfer your function sends out of the caller's inventory is delivered like one the player sent
+themselves, except for one case: if receiving it would pay the recipient platform currency or an
+achievement (a pass item that opens a battle-pass track they are already past, say), it is not
+delivered by the function. It stays `pending` for the recipient to accept or reject.
+
+Anything that changes several players at once — settling a match, trading between two players,
+granting a whole room its rewards — is your **game server's** job, or the job of a function your
+server calls, which is not bound to a player.
+
+**`log` is not a debugger.** What it writes stays on the platform under the call's invocation id,
+and no command reads it back to you. The invocation id is what you quote when you ask the platform
+team about one call.
+
+**A function cannot call a function.** `call-api` to `/v1/functions/invoke` is refused with
+`function_cannot_invoke`.
+
+### Paying the player who called
+
+A progression in your game config can pay a platform currency (a `platform_grants` mapping) or
+carry an achievement: [inventory-and-catalogs.md](inventory-and-catalogs.md) §13 and
+[achievements.md](achievements.md). Your dedicated server's write fires them. A function's write
+fires them only when you opt in:
+
+- **Opt in per progression, with `function_may_grant: true`.** It is off by default. Without it, a
+  function's `progression_add` or `progression_max` still moves the value, but every grant and
+  achievement it would have fired reads `suppressed` with `functions_not_opted_in`. Turn it on only
+  for a progression whose function checks what it pays for, because turning it on makes that
+  check yours (see the ⚠️ below).
+- **A function a player called pays that player.** Its `call-api` writes the opted-in progression
+  for the player id `get-context` gave it, and the platform grants and unlocks as it does for your
+  server's write: currency on every channel, achievements on `release` only.
+- **It pays nobody else.** It cannot write another player at all
+  (`403 function_foreign_entity_write`, the previous subsection), so it cannot pay one, directly or
+  through anything your config writes on the order's behalf. A character never earns a platform
+  currency or an achievement, whoever writes it — your function may write the caller's own
+  characters, and their receipts read `suppressed` with `entity=character`. A transfer is the one
+  write that reaches someone else, and it grants them nothing either: one whose delivery would
+  grant the recipient platform currency or an achievement is neither delivered nor refused. The
+  request answers `200`, and the transfer stays `pending` for the recipient to accept or reject
+  (the previous subsection).
+- **Any currency the platform lists.** A function may pay every currency `gemctl platform config`
+  lists under `platform_grants` — Gems (`GEMS`) and Tickets (`ARCADE_TICKETS`) alike — so a daily
+  that pays Gems needs no dedicated server. (`function_gems_not_enabled` on an older receipt is from
+  before functions could pay Gems.)
+- **No guests.** A guest account's call grants and unlocks nothing (`function_invoker_is_guest`).
+- **An achievement unlocks once per player, ever**, whoever writes it.
+- **The receipt names the function.** Every `platform_grant` and `achievement_unlocked` entry your
+  function's orders produce carries `principal: "function"`, whatever its outcome.
+- **The platform's limits are the same as for a server.** What one firing may pay, what your game
+  may pay a player per window and what all games may pay a player per day all apply, and your game
+  declares none of them.
+- **The platform can switch a function's payouts off**, for every game or only yours, and leave
+  your dedicated server's payouts running. A grant then reads `suppressed` with the operator's
+  reason, and an unlock reads `suppressed` with `functions_disabled`. Read the receipt before
+  suspecting your config.
+- **A call from your dedicated server** is not bound to a player. The function acts for your game,
+  like the server that called it, and may write and pay whichever player it names, on a
+  progression that opts in.
+
+⚠️ **Opting in makes your function the only check on what the player earned.** A player can call
+it as often as their per-minute budget allows, with any input they like, and **every new call may
+grant again**. The platform's limits cap the damage per player per day. They
+do not decide whether a reward was earned. So:
+
+- treat the input as a claim, and check it against what the player cannot forge: the platform's
+  own records (read through `call-api`), elapsed time (`now-ms`) and what your game's rules make
+  possible;
+- let the progression make a reward grant once. An `on_complete` mapping on a progression with a
+  `daily` reset grants once per completion per day, the player's own unless its `boundary` fixes a
+  zone, and on one with no reset it grants once, ever.
+  `progression_max` grants only an improvement on a best. The platform keeps that state, and the
+  input cannot reset it;
+- if you key a paying order with a `nonce` instead, build the key from something the platform
+  decides: the UTC date from `now-ms` (`daily:2026-09-26`), or an id the platform issued, such as
+  a match it ran. **Never use an id from the call's input.** A run id your client made up is a new
+  id on every call, so it stops nothing. A nonce is also only remembered for 72 hours, so it
+  guards a period, not a lifetime;
+- never pass the caller's request straight through to a progression write.
+
+### What `call-api` can reach
+
+**A `call-api` request is a method, a `/v1/` path and a JSON body, and nothing else.** It reaches
+the platform API carrying your game's server credential. No header of yours goes with it, and
+nothing goes to any other address. So a route that needs a header from you is out of a function's
+reach, even where the route itself admits your game's server. A save's contents are the one thing
+a function sends or fetches anywhere else, and they have two host calls of their own:
+`download-link` and `upload-link`.
+
+That decides the three things a function is most often asked to do.
+
+**Saves: the record through `call-api`, the contents through the save links.** A save slot's
+`access_game_server_read` and `access_game_server_write`, both `true` by default, admit a function
+as they admit your dedicated server, with one limit on writes. A function a player called writes
+only that player's saves: starting, finishing or deleting anyone else's is refused with
+`403 function_foreign_entity_write`
+([What a function a player called may change](#what-a-function-a-player-called-may-change)). A
+function your server called keeps the slot's game-server access for every player of your game.
+
+The contents never travel on a `call-api` request. They move between your function and the
+platform's save storage over the same short-lived links a browser game's save uses, and
+`download-link` and `upload-link` are the calls that follow those links:
+
+| Step              | Request                                               | What it does                                                                                                                      |
+| ----------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| Read the record   | `GET /v1/saves/players/{player_id}/{key}`             | The save's `size_bytes`, its version (`etag`), its timestamps and `metadata`, and a `download_url`                                |
+| Read the contents | `download-link` with that `download_url`              | The save's bytes, as the answer's `body`                                                                                          |
+| Start a write     | `POST /v1/saves/players/{player_id}/{key}/upload-url` | Takes `size_bytes`, `content_type` and, if you like, `metadata`. Answers a `session_id`, an `upload_url` and the `upload_headers` |
+| Send the contents | `upload-link` with that `upload_url`                  | Sends the bytes, with the same content type and exactly the `upload_headers` it was given                                         |
+| Store them        | `POST /v1/saves/players/{player_id}/{key}/finalize`   | Takes `{ "session_id": ... }`, stores the save and answers its new record                                                         |
+| List              | `GET /v1/saves/players/{player_id}`                   | The player's saves your server may read: their records, with no download links                                                    |
+| Delete            | `DELETE /v1/saves/players/{player_id}/{key}`          | Deletes the save where the slot lets your server write                                                                            |
+
+- **Finish a write in the call that started it.** An upload a function starts lapses within a
+  minute, and until it does it counts as one of the five saves a player may have in flight.
+  `size_bytes` has to be exactly the number of bytes you send: `finalize` refuses any other with
+  `400 validation_error` and throws the bytes away.
+- **At most 8 MiB in one link call**, either way, so a larger save is out of a function's reach
+  whatever its slot allows. A link call also counts toward the call's 32 requests and its 5
+  seconds, as a `call-api` request does ([The limits on one call](#the-limits-on-one-call)).
+- **Only the platform's own save links.** A link call to any other address, or an upload to a
+  download link, is refused before anything is sent, and returns `Err`. A redirect is returned as
+  its status and never followed.
+- **What save storage answered is not an `Err`.** Every status comes back as an answer, with
+  `status` and `body`. A download's `body` is the save only when `status` is `200`, and an upload
+  succeeded when `status` is in the `2xx` range. Only `finalize` makes the save exist.
+
+A function writes a save like this. `contents` holds the bytes to store; the request bodies are
+built with `serde_json`, which you add to the crate:
+
+```rust
+use gem::functions::host::{self, ApiRequest, Caller, UploadRequest};
+
+let Caller::Player(player_id) = host::get_context().caller else {
+    return Err("expected a player's call".into());
+};
+let save = format!("/v1/saves/players/{player_id}/campaign");
+let json = |v: serde_json::Value| v.to_string().into_bytes();
+
+let started = host::call_api(&ApiRequest {
+    method: "POST".into(),
+    path: format!("{save}/upload-url"),
+    body: json(serde_json::json!({
+        "size_bytes": contents.len(),
+        "content_type": "application/octet-stream",
+        "metadata": { "level": 7 },
+    })),
+})?;
+if started.status != 200 {
+    return Err(format!("upload-url answered {}", started.status));
+}
+let grant: serde_json::Value = serde_json::from_slice(&started.body).map_err(|e| e.to_string())?;
+let headers = grant["upload_headers"]
+    .as_object()
+    .into_iter()
+    .flatten()
+    .map(|(name, value)| (name.clone(), value.as_str().unwrap_or_default().to_string()))
+    .collect();
+
+let sent = host::upload_link(&UploadRequest {
+    url: grant["upload_url"].as_str().unwrap_or_default().to_string(),
+    content_type: "application/octet-stream".into(),
+    headers,
+    body: contents,
+})?;
+if !(200..300).contains(&sent.status) {
+    return Err(format!("the upload answered {}", sent.status));
+}
+
+let stored = host::call_api(&ApiRequest {
+    method: "POST".into(),
+    path: format!("{save}/finalize"),
+    body: json(serde_json::json!({ "session_id": grant["session_id"] })),
+})?;
+if stored.status != 200 {
+    return Err(format!("finalize answered {}", stored.status));
+}
+```
+
+Reading one back is the record's `GET`, then `host::download_link(url)` with its `download_url`.
+
+The metadata is what makes the record worth reading on its own. Your game attaches it when it
+saves, such as `{ "level": 7 }`, and so can your function, so a function can check a claim in its
+input against it with one request and no download.
+
+⚠️ **A save is only as honest as whoever wrote it.** A player writes their own save unless the slot
+declares `access_self_write: false`, so on an ordinary slot its contents and its metadata are the
+player's word too, given earlier rather than in this call. A slot that declares it is one only
+your server and your function write, and the showcase example below declares one that way.
+
+**Showcase values: read and write.** A showcase slot, one declared with `visibility: friends` or
+`public`, holds a JSON value of at most 4096 bytes that travels on the request itself. That makes it
+the per-player value a function can both read and write: `GET`, `PUT` and `DELETE` on
+`/v1/showcase/players/{player_id}/{key}`, admitted by the slot's `access_game_server_read` and
+`access_game_server_write`. The same limit holds: a function a player called reads any player's
+value your server may read, but its `PUT` or `DELETE` for any other player is refused with
+`403 function_foreign_entity_write`. A function your server called may write any player's. It is
+not a private save. The slot's visibility shows the value to the player's friends or to every
+player of your game, and the last write wins, whoever made it.
+[Showcase slots](saving-player-progress.md#showcase-slots-a-little-progress-your-friends-can-read)
+covers declaring and reading one.
+
+**A value players cannot forge, written by a function.** A best time that friends can see and a
+player cannot write for themselves is a showcase slot only your game's server may write:
+
+```yaml
+save_schemas:
+  - key: best_time
+    visibility: friends
+    access_self_write: false
+    access_game_server_write: true
+```
+
+`access_game_server_write` is `true` already; writing it out says what the slot is for. The
+function checks the run, then writes the time for the player who called. The body is the showcase
+write's `{ "value": ... }`:
+
+```rust
+use gem::functions::host::{self, ApiRequest, Caller};
+
+// In `handle`, once the run has passed your checks. `finish_ms` is the time to show.
+let Caller::Player(player_id) = host::get_context().caller else {
+    return Err("expected a player's call".into());
+};
+let written = host::call_api(&ApiRequest {
+    method: "PUT".into(),
+    path: format!("/v1/showcase/players/{player_id}/best_time"),
+    body: serde_json::json!({ "value": { "ms": finish_ms } }).to_string().into_bytes(),
+})?;
+if written.status != 200 {
+    return Err(format!("best_time was not written: {}", written.status));
+}
+```
+
+**Leaderboard scores: `POST /v1/games/{game_id}/runs`.** This is how a function records a
+leaderboard result. It needs no match and no header. The runs go on the boards of the channel the
+function was called on, and no match is recorded against them. A function cannot use the route a
+dedicated server reports its match's runs on, because that route needs the match's allocation
+proof in a request header. This one takes the same body, checks each run the same way and refuses
+with the same codes. It accepts only a function's `call-api`: a dedicated server's own credential
+is refused there with `403 forbidden`.
+
+- **Whose runs.** A function a player called records runs only for that player and that player's
+  own characters. A batch that names anyone else is refused with
+  `403 function_foreign_entity_write`, and nothing in it is written. A function your server called
+  may record runs for any player or character of your game.
+- **How many.** Up to 500 runs in one request. Requests to this route share a budget of 60 a
+  minute across all the function calls one player makes, and another 60 across all the function
+  calls one game server makes.
+- **All or nothing.** If any run in the batch fails its checks, nothing is written, and the answer
+  names the first run that failed. A run is stored once per player or character and `run_id`, so a
+  batch sent again with the same ids records nothing twice, and the answer counts them in
+  `duplicates`.
+
+The body is a batch of runs. For the `race` run type that
+[leaderboards.md](leaderboards.md#1-declare-the-board-in-your-game-config) declares, whose
+`int_value_1_name` is `score`:
+
+```json
+{
+  "runs": [
+    {
+      "run_id": "5b0d3c1e-8f7a-4c2e-9d61-0a4b7e2f9c13",
+      "entity_type": "player",
+      "entity_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
+      "run_type": "race",
+      "int_value_1": 3100
+    }
+  ]
+}
+```
+
+The path's `{game_id}` is the game id from `get-context`, `entity_id` is the player id it gives
+you, and `run_id` is a UUID you choose. A run may also carry `occurred_at`, in Unix seconds, which
+defaults to now. A stored batch answers `200` with `{ "inserted": 1, "duplicates": 0 }`.
+
+⚠️ **A function that records the score its caller sent, unchecked, makes your board forgeable.**
+The platform trusts a function's runs as it trusts your dedicated server's, and it cannot tell a
+checked score from a forwarded one. Check the run against what the player cannot forge (section 1)
+before you record it, or any player can put any score they like on your board.
+
+| What you get                        | What happened                                                                           | What to do                                           |
+| ----------------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| `400 invalid_run`                   | A run failed its run type's checks. `details` names it by `index` and `run_id`          | Fix that run and send the batch again                |
+| `400 unknown_run_type`              | The run type is not in the active config of the channel the function was called on      | Publish the run type on that channel                 |
+| `400 too_many_runs`                 | More than 500 runs in one request                                                       | Split the batch                                      |
+| `403 function_foreign_entity_write` | A function a player called named another player, or a character not theirs              | Record runs only for the caller and their characters |
+| `429 rate_limited`                  | The budget of 60 requests a minute is spent. Nothing was written                        | Send more runs in each request, and fewer requests   |
+| `503 service_unavailable`           | The platform could not check the budget, so it refused the request. Nothing was written | Retry shortly                                        |
+
+[Where the rows come from](leaderboards.md#where-the-rows-come-from) is how runs reach a board
+from every side, and the rest of that page is how your game reads them back.
+
+⚠️ **A refused request is not an `Err`.** `call-api` returns `Err` only when the request was never
+answered: a request it will not send, such as a path outside `/v1/`, or no answer from the platform.
+A refusal comes back as an answer, with its status and the platform's error body, so check `status`
+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 |
+
+**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
+decision point, such as the end of a run or a claim, and never on a timer or once per frame.
+
+## 3. Writing one
+
+The reference toolchain is Rust. gemctl writes the starter crate and wraps what your build
+produces, and the build in between is yours:
+
+```bash
+gemctl function init functions/score-check
+rustup target add wasm32-unknown-unknown   # once per machine
+cargo build --release --target wasm32-unknown-unknown --manifest-path functions/score-check/Cargo.toml
+gemctl function package functions/score-check/target/wasm32-unknown-unknown/release/score_check.wasm
+```
+
+**`init`** writes three files into the directory: a `Cargo.toml`, a `lib.rs` whose `handle` echoes
+its input, and `wit/world.wit`, which is the platform's world and the one file you cannot write
+yourself. The package name comes from the directory unless you pass `--name`. It refuses to
+overwrite a file that is already there, naming every one, unless you pass `--force`. Run it inside
+your game's repository and it also adds the crate's `target/` to that repository's root ignore
+file (`.gitignore` for git).
+
+**gemctl never runs your build.** `cargo build` is yours, and `init` prints it for you rather than
+running it.
+
+**`package`** wraps the **core module** cargo wrote into a **component**, on your machine, with no
+second tool. It writes `score_check.component.wasm` beside the module (or wherever `--out` says),
+then runs the same check as `gemctl function check`, below. A refusal exits 1, and the component is
+written anyway so you can inspect it. It needs no sign-in and no network.
+
+What `init` writes for `handle`:
+
+```rust
+wit_bindgen::generate!({
+    path: "wit",
+    world: "function",
+});
+
+use gem::functions::host::{self, Caller, LogLevel};
+
+struct Function;
+
+impl Guest for Function {
+    fn handle(input: Vec<u8>) -> Result<Vec<u8>, String> {
+        let ctx = host::get_context();
+        let caller = match ctx.caller {
+            Caller::Player(id) => format!("player {id}"),
+            Caller::GameServer(Some(id)) => format!("game server {id}"),
+            Caller::GameServer(None) => "a game server".to_string(),
+        };
+        host::log(
+            LogLevel::Info,
+            &format!("invoked by {caller} with {} bytes", input.len()),
+        );
+
+        let mut output = format!("hello {caller}, from {} on {}: ", ctx.game_id, ctx.channel)
+            .into_bytes();
+        output.extend_from_slice(&input);
+        Ok(output)
+    }
+}
+
+export!(Function);
+```
+
+If you write the crate yourself, keep three settings the starter's `Cargo.toml` carries, because
+each one fails somewhere unhelpful when it is missing: `crate-type = ["cdylib"]` (without it there
+is no wasm module at all), an empty `[workspace]` table (without it a workspace the crate sits
+inside tries to build it for your machine), and a size-tuned release profile (`opt-level = "s"`,
+`lto`, `strip`).
+
+⚠️ **Do not build for `wasm32-wasip2`.** It is the target that makes a component in one step, so it
+is the one a Rust developer reaches for, and the platform refuses what it produces as
+`forbidden_import`: Rust's standard library links `wasi:*` imports into it whether or not your
+function uses them. A WASI adapter (`wasm-tools component new --adapt`) adds the same imports.
+Build for `wasm32-unknown-unknown` and wrap with no adapter, which is what `package` does.
+
+**Another toolchain.** `gemctl function init --wit-only <dir>` writes only `wit/world.wit`, for
+your toolchain's own bindings generator. Any language works if it produces a component that
+imports only `gem:functions/host` and exports `handle` with the signature above. Check a finished
+component with `gemctl function check`; wrap a core module that carries the world with
+`gemctl function package`.
+
+**What the world rules out.** A function has no filesystem, no network, no environment and no
+clock or randomness of its own: `now-ms` and `random-bytes` are the clock and the entropy, and
+`call-api` is the only way out, apart from `download-link` and `upload-link`, which move a save's
+contents to and from the platform's save storage and nowhere else. A crate that assumes a WASI or JavaScript host (`getrandom` without
+a custom backend, `std::time`, anything that reaches for files or sockets) either fails to build for
+`wasm32-unknown-unknown` or links an import the platform refuses.
+
+### Check before you upload
+
+```bash
+gemctl function check function.wasm
+```
+
+`check` runs the platform's own publish-time validation on your machine: the same rules, in the
+same order. It needs no sign-in, and nothing leaves the machine. A refusal names the reason the
+upload would give, says what to change, and exits 1:
+
+| Reason                   | What it usually is                                                 | What to change                                         |
+| ------------------------ | ------------------------------------------------------------------ | ------------------------------------------------------ |
+| `not_a_component`        | The core module cargo wrote, not yet wrapped                       | Run `gemctl function package` on it                    |
+| `forbidden_import`       | A `wasm32-wasip2` build, or a WASI adapter. The import is named    | Build for `wasm32-unknown-unknown`, no adapter         |
+| `missing_handle`         | No `handle` export: the bindings were not generated from the world | Generate them from `wit/world.wit`                     |
+| `wrong_handle_signature` | A `handle` written by hand                                         | Use the exact signature in section 2                   |
+| `too_large`              | Over the size limit                                                | Release profile with `opt-level = "s"`, `lto`, `strip` |
+
+The backend checks again when you upload, and its verdict is final.
+
+## 4. Publishing: upload, then promote
+
+Publishing is two steps, and only the second one changes what anybody calls. The commands act on
+the game your directory is bound to; [getting-started.md](getting-started.md) §1 and §2 cover
+signing in and binding one.
+
+```bash
+gemctl function upload --file function.wasm --version 1.0.0 --description "commit 3f2a9c1"
+gemctl function promote 1.0.0 --channel dev
+```
+
+**`upload` stores a version, and nobody calls it.** It runs `check` first and uploads nothing on a
+refusal; `--dry-run` runs the check and stops. Passing `--channel` promotes the version in the same
+step. Omit it while you iterate.
+
+**A version string is used once per game.** It is 1 to 64 letters, digits, `.`, `_` and `-`. To
+change what callers run, upload a new version and promote it. A deleted version keeps its name until
+the backend purges it.
+
+**`--description` is the only record of what a version was built from.** Nothing else on a version
+says which source produced it, so put the commit in it (500 characters at most).
+
+**`promote` points a channel at a version**, from the next call on. There is no cache to wait for.
+Publishing a function takes the same package permissions on your game that publishing a build does.
+
+⚠️ **`release` is every player, immediately.** `upload --channel release`, `promote --channel
+release` and `unassign --channel release` all refuse without `--yes`:
+
+```bash
+gemctl function promote 1.1.0 --channel release --yes
+```
+
+**Rolling back is promoting the previous version:**
+
+```bash
+gemctl function list                        # what each channel serves, who promoted it, and when
+gemctl function list --all                  # every upload, and which channel serves each
+gemctl function promote 1.0.0 --channel dev
+```
+
+`gemctl function view <version>` shows one version in detail, including its SHA-256, so you can
+compare it with a local build. `list --all --include-deleted` adds deleted versions that have not
+been purged yet.
+
+`gemctl function unassign --channel dev` clears a channel, so every call to it is refused
+`function_not_published`. **That is not a rollback**: to go back to an earlier version, promote it.
+`gemctl function delete <version> --yes` is refused while any channel serves the version, and
+gemctl cannot undo it.
+
+## 5. Channels
+
+Each channel (`dev`, `test` and `release`) serves at most one function version. A call never names
+its channel: the platform reads the channel, and the game, from the caller's token. Your game on
+`dev` calls `dev`'s function, and your released game calls `release`'s.
+
+| Channel   | Whose calls run it |
+| --------- | ------------------ |
+| `dev`     | your team          |
+| `test`    | your testers       |
+| `release` | **every player**   |
+
+⚠️ **A function version and a build version are promoted separately, and nothing ties one to the
+other.** Promote a function that expects a new input shape before the build that sends it, and
+every player on that channel sends the old shape to the new function. Promote the build first, and
+the new build calls the old function. A player who loaded your game before a promote is still
+running the build they loaded. So a function has to accept what the previous build sends for at
+least one release: put a version field in the input and branch on it.
+
+A dedicated server's token names the channel its match runs on, so your server calls the same
+channel's function as the players it serves.
+
+## 6. Calling it from your game
+
+`gem.functions.invoke(input)` calls the function promoted on your game's channel and resolves its
+answer. The call names no game and no channel: both come from the token your game already holds.
+
+```js
+import { GemFunctionError } from '@indiegems/gem-web-sdk/sdk';
+
+// `gem` is what createGem returned.
+const result = await gem.functions.invoke({ v: 2, runId, finishMs, moves });
+const { accepted, why } = result.json();
+```
+
+**What your function receives.** Pass a `Uint8Array`, an `ArrayBuffer` or another typed array and
+your function's `input` is those bytes, as they are. Pass anything else and it is sent as its JSON
+text, so parse `input` as JSON in `handle`. A string is a JSON value too: `'ping'` arrives as
+`"ping"`, quotes included. To send text as it is, encode it with `new TextEncoder().encode(text)`.
+A value JSON cannot carry, such as a `BigInt`, is refused before anything is sent.
+
+**What comes back** is a result holding your function's `Ok` bytes:
+
+- `result.json()` parses them as JSON, and throws if they are not JSON (an empty answer is not);
+- `result.text()` reads them as UTF-8, and throws if they are not UTF-8 rather than changing them;
+- `result.bytes` is the bytes themselves, for a function that answers in binary.
+
+**It sends the call once.** The SDK never repeats a function call for you, because your function
+may have granted or written something, and a retry you cannot see is how one grant becomes two.
+Whether repeating it could help is on the error. A repeated call may grant again, and what stops
+it is the progression's own state, or a key the platform decides (section 2).
+
+**A refused call throws `GemFunctionError`.** It is a `GemApiError`, so `err.code` is the
+platform's code from section 8, and the error adds what that code needs:
+
+- `err.functionMessage` is the text your `handle` returned in `Err`, on `function_error`. Your
+  function wrote it and it may repeat what the caller sent, so log it and never render it as markup;
+- `err.failure` says which limit or fault ended the call, on `function_failed`;
+- `err.retryable` is decided by the code. It is `false` for `function_timeout`, because the same
+  input runs out of time again, and for `functions_not_configured`, because functions are switched
+  off where you called. It is `true` for the refusals that mean the platform could not run the
+  call (too busy, unreachable, or rate-limiting the caller), and then `err.retryAfterSeconds` is the
+  wait the platform named, when it named one.
+
+```js
+try {
+  show((await gem.functions.invoke(claim)).json());
+} catch (err) {
+  if (!(err instanceof GemFunctionError)) throw err;
+  if (err.code === 'function_error') {
+    reportBug(err.functionMessage, err.invocationId); // your handle returned Err
+  } else if (err.retryable) {
+    retryLater(err.retryAfterSeconds ?? 5); // the function did not run
+  } else {
+    reportBug(err.code, err.invocationId); // repeating the same call gets the same answer
+  }
+}
+```
+
+⚠️ **A lost connection is `retryable` and tells you nothing about whether your function ran.** The
+call left, and no answer came back. If your function grants or writes, make it safe to call twice
+with the same input, for instance by keying what it writes on an id the caller sends.
+
+**The invocation id** is what the platform files one call under: `result.invocationId`, or
+`err.invocationId` on a call that reached your function. A server bundle always reads it. A game
+page cannot: the platform does not expose that response header to pages, so on a page both are
+`undefined`. To trace one call from a page, reproduce it with `gemctl function invoke` (section 7).
+
+**From your server bundle.** A dedicated server makes the same call, `gem.functions.invoke`, with
+its game-server token, so your function's `get-context` reports a game server rather than a player.
+A server gets 120 calls a minute because it calls for everyone in its match.
+[server-bundles.md](server-bundles.md) covers how a bundle calls the backend. A bundle that a
+player's browser is hosting holds that player's token instead, so its calls arrive as that player.
+
+## 7. Calling it from the terminal
+
+`gemctl function invoke` calls what a channel serves and reports what came back. It is how you
+test a function without a game, and how you see one call from outside it.
+
+```bash
+gemctl function invoke --data '{"v":2,"runId":"a1","finishMs":61234}'   # dev's function, as you
+gemctl function invoke --channel test --input request.json               # a file, byte for byte
+printf 'ping' | gemctl function invoke --input -                         # stdin
+gemctl function invoke --caller game-server --server-label probe         # as a game server would
+```
+
+It calls `dev` unless you pass `--channel`, and it calls **as you**, through a token scoped to this
+game and channel. `--caller game-server` calls as a game server instead, with the server id
+`--server-label` gives (`gemctl` by default). That token is issued only for `dev` and `test`, and
+only to an Owner, Admin or Contributor on the game. **A function that trusts a server more than a
+player has to be tested both ways.**
+
+It reports:
+
+- `result`: `returned`, `function_error`, `function_failed`, or the platform's code from section 8;
+- `output`: the function's bytes as text, or `output_base64` when they are not UTF-8;
+- `function_message`: your `Err` text, on a `function_error`;
+- `reason`: on a `function_failed`, which limit or fault ended the call;
+- `round_trip_ms`: measured by gemctl, from sending the call to the last byte back;
+- `invocation_id`: what the platform files the call under. **Keep it.** It is the only handle on
+  the platform's side of one call, including whatever the function passed to `log`.
+
+Anything but `returned` exits 1.
+
+⚠️ **`invoke` runs the function for real.** Whatever the function does through `call-api`, it
+does, on the channel you called. Stay on `dev` while you develop.
+
+If the call is refused before anything is invoked, the problem is your sign-in: `dev` needs you to
+be a developer on the game, `test` needs a grant on it, and `release` needs a game your account may
+play.
+
+## 8. When a call is refused
+
+Every answer from a call that reached your function carries an invocation id: success,
+`function_error`, `function_failed`, `function_timeout`, and the three `function_*` `503`s. A call
+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` |
+
+A `trap` is a panic, an `unreachable`, an out-of-bounds access or a stack overflow, and no stack
+trace comes back with it. The other three reasons are the limits in section 2.
+
+Publishing has its own refusals, and nothing is stored when one happens:
+
+| What you get                     | What happened                                                                                                                                        | What to do                                               |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| `400 component_invalid`          | The backend's check refused the component. `details.reason` is one of the five in section 3, or `sha256_mismatch`, `size_mismatch` or `not_uploaded` | The five: fix and rebuild. The other three: upload again |
+| `409 function_version_exists`    | That version string is taken, perhaps by a deleted version not yet purged                                                                            | Choose another version                                   |
+| `409 function_version_in_use`    | You tried to delete a version a channel still serves                                                                                                 | Promote another version there, or unassign it first      |
+| `404 function_version_not_found` | No such version, or it has been deleted                                                                                                              | `gemctl function list --all --include-deleted`           |