@indiegems/gem-web-sdk 7.3.1 → 7.4.1

package/docs/inventory-and-catalogs.md

@@ -0,0 +1,1035 @@
+# Inventory and catalogs
+
+Games do not have to have an economy. A game with no currency, no items and nothing to buy is a
+complete game. Read this if yours has any of them — a coin count, a bag of items, a shop, a loot
+box, a battle pass.
+
+If it does, the platform holds it, the same way it holds a save. Balances and items live on the
+server and are reachable with the token your frame already holds, so they survive a device change
+and a browser wipe, and a modified client cannot invent them — with one large exception this
+document is careful to state, in [§14](#14-there-is-no-client-side-integrity-boundary).
+
+## 1. Two halves, and they happen at different times
+
+This is the thing to get straight first, because — as with save slots — only one half is code:
+
+|                                                                                     | Who                      | When                           |
+| ----------------------------------------------------------------------------------- | ------------------------ | ------------------------------ |
+| **Authoring definitions** — the currencies, items, shops and loot tables that exist | you, the developer       | once, in your game config      |
+| **Reading and changing what a player holds**                                        | your game's running code | every session, once per player |
+
+A currency, an item type, a shop, a loot table — these are **definitions**. You publish them in
+your game config, the same pipeline that ships save slots and room templates: versioned, no new
+build, rollback-able. What a specific player owns is an **instance** of a definition, and that is
+what your game reads and changes at runtime.
+
+Game code cannot create a definition, and this is the wall almost everyone hits first: a read or
+a grant that names an id you never published resolves to nothing, at the first call and every
+retry. So this document starts with the config, not the API.
+
+```bash
+gemctl config schema                                # the authoritative field list
+gemctl config upload --wait                         # registers a version; validation is ASYNC
+gemctl config promote <version> --channel <channel> # this is what makes it live
+```
+
+**Uploading is not shipping.** Until `gemctl config promote` puts the version on the channel your
+game runs, the definitions do not exist for that channel — see
+[`saving-player-progress.md`](saving-player-progress.md#1-declare-the-slot-in-your-game-config),
+which is the same rule with a save slot in place of a currency.
+
+## 2. Definition versus instance
+
+Hold the distinction, because the whole surface is built on it.
+
+- A **currency definition** is "coins exist, minimum 0, maximum a million." A player's **balance**
+  is an instance: "this player has 250 coins."
+- An **item definition** is "a healing potion, stackable to 99." An **item instance** is "this
+  player holds 3 of them," or, for a non-stacking item, "this specific sword, rolled with these
+  properties."
+- A **catalog** is a shop: a set of purchasable **recipes**. A player buying from it produces an
+  **order** — a record that the change happened.
+- A **loot table** is a weighted pool. A recipe that references it produces one **roll** per draw.
+
+You read definitions from the published config. You read instances from the player. They are
+different calls returning different shapes, and conflating them is how a bag renders raw ids
+because it never loaded the definitions that name them.
+
+## 3. The player, and their characters
+
+Everything a player owns is reached through `gem.me`, the signed-in player:
+
+```js
+await gem.me.currencies.get('coins');
+await gem.me.inventory.snapshot();
+```
+
+If your game gives a player several characters, each character carries the **same accessors**,
+scoped to that character:
+
+```js
+const hero = await gem.characters.get(characterId);
+await hero.currencies.get('coins'); // the hero's coins, not the account's
+```
+
+Code written against `gem.me` works unchanged against a character, because it is one interface on
+both. Characters are declared and managed exactly as
+[`saving-player-progress.md`](saving-player-progress.md) describes for saves; there is nothing
+economy-specific about them, and this section is all you need here.
+
+## 4. Reading the config, and the sync/async cliff
+
+Load the published config once, then read from it synchronously. The load is a round trip; the
+lookups are memory:
+
+```js
+const config = await gem.gameConfig.load(); // a round trip; do it once
+const potion = config.item('healing-potion'); // synchronous, from memory, by id or slug
+const coin = config.currency('coins'); // synchronous
+```
+
+Two things that will bite:
+
+- **`load()` resolving `null` is a real state, not an error** — twice over. A game with no config
+  at all resolves `null`, and so does a game whose config version has not finished building. A
+  game with no economy should not have to catch anything, so `null` is a value you handle, not an
+  exception you wrap.
+- **Do not remember the field names.** Read them from `gemctl config schema` and from what
+  `load()` returns, never from a list you typed once. A curated field list drifts silently: a
+  real one once read a `fungible` flag under an invented `is_fungible`, a `stack_size` under an
+  invented `max_stack_size`, and rendered an `icon_url` on the game's own config currencies that
+  has never existed on the wire (the PLATFORM currency catalogue does carry one — see
+  [brand-art.md](brand-art.md)). None of those raises. All of them just make a game quietly wrong. The schema is the
+  authority precisely because it cannot go stale against itself.
+
+## 5. Reading what a player holds
+
+One call returns everything the player owns — balances, items and progressions — in a single
+snapshot:
+
+```js
+const snap = await gem.me.inventory.snapshot();
+snap.currencies.data; // balances
+snap.items.data; // item instances
+snap.progressions.data; // progression state
+```
+
+The snapshot is **cached**. Repeat calls, and reads derived from it — `gem.me.currencies`,
+`gem.me.progressions`, item-instance lookups — serve from the one cached read rather than issuing
+a request each, so a HUD polling a balance does not re-download the whole bag. Any change the SDK
+makes drops the cache; [§6](#6-when-to-re-read) is about the changes it cannot see.
+
+Each of the three sections carries its **own cursor**, because any one of them can be large
+independently, and the snapshot carries an **`etag`** — the inventory's version — which
+[§11](#11-conditional-writes-and-why-most-writes-do-not-want-them) uses to make a write
+conditional.
+
+## 6. When to re-read
+
+**There is no push into a sandboxed frame.** A gift arriving from another player, a grant from
+your dedicated server, a change made on the player's other device — none of these produces an
+event in your game, because the frame has no socket to hear about them. A change your own game
+made through the SDK drops the cache; nothing else does.
+
+So the SDK's change event fires for your own writes and no others. Build on that and a port from
+a native engine — which _did_ push external changes — is wrong in exactly the places the engine
+was right.
+
+The remedy is not a poll. **Do not poll**: a fixed-period re-read is a per-session load on the
+backend that scales with your player count and buys staleness you could have designed around.
+Instead:
+
+- Re-read on screen-open. When the tab becomes visible, drop the cache and read again:
+
+  ```js
+  gem.me.inventory.refresh(); // drop what is cached
+  await gem.me.inventory.snapshot(); // re-fetch
+  ```
+
+  Add a little randomness to when you fire it so a whole cohort resuming at once does not hit the
+  backend in a spike.
+
+- Re-read after any action that could involve another player — a trade, a match result.
+- Treat the server's answer at the moment you _change_ something as the authority. A shop that
+  re-checks affordability when the player clicks Buy, and lets the purchase itself be the final
+  word, never needs the balance to be live between clicks.
+
+Design the UI so staleness is harmless, and you will not want a poll.
+
+## 7. Currencies
+
+A balance read is a lookup, not a list to iterate, because **a currency the player holds none of
+is absent, not present as zero**:
+
+```js
+const coins = await gem.me.currencies.get('coins');
+coins.total; // a number, or null when the player has no record of this currency
+```
+
+**`null` is not `0`.** Reach for `total ?? 0` and you have decided that "has never held any" and
+"holds none" are the same thing — and one of them may mean your game does not define that currency
+at all. If you want to show a missing balance as zero, do that where it renders, so the decision
+is visible.
+
+**Buckets** split a balance by how it was acquired — a daily allowance, a play-earned pool, a
+real-money pool. They are off by default and asked for per read:
+
+```js
+const c = await gem.me.currencies.get('coins', { buckets: true });
+c.buckets; // [{ bucket: 'earned', balance: 200 }, { bucket: 'purchased', balance: 50 }], or absent
+```
+
+They are off by default because they are a **disclosure**, not a cost: a bucket names whether
+value came from a real-money purchase versus play, so ask for them only on the screen that shows
+the split. An empty array means the currency is bucketed and this player has none; an absent field
+means you did not ask.
+
+## 8. Items
+
+An item definition is either **fungible** or not, and it changes what an instance is:
+
+- A **fungible** item stacks. A player's 3 potions are one instance with a quantity of 3.
+- A **non-fungible** item does not. Each is a distinct instance with its own id, and each may
+  carry its own rolled **properties** — the affixes a generated weapon draws from a pool.
+
+Read every instance of a definition without walking the whole bag:
+
+```js
+const swords = await gem.me.inventory.instances('iron-sword');
+```
+
+⚠️ **An item's `properties` and `customData` are untrusted, and rendering them wrong is a
+cross-player attack.** They are typed `unknown` **because the platform does not validate their
+contents** — every read of them is a parse, not a trusted object. And a transfer moves an instance
+between players, so one player's item text reaches another player's screen. Any string you pull
+from them is untrusted input: render it through `textContent` or your framework's escaping, and
+**never** through `innerHTML`, and **never** as an `img.src` or `a.href` — either of those is a
+`javascript:` / `data:` sink. The same caution applies to strings read from the config, which
+arrives over a signed URL with no integrity check on its body.
+
+### Reading a generated item's affixes and rarity
+
+When a recipe grants a **generated** item, the affixes the roll produced land in that instance's
+`properties`, keyed by the names your item definition's property schema declares. The SDK types
+`properties` as `unknown` on purpose — your config, not the SDK, decides those keys — so read a
+value out defensively rather than assuming a shape:
+
+```js
+const [blade] = await gem.me.inventory.instances('legendary-blade');
+const props = blade?.properties ?? {};
+const damage = typeof props.damage === 'number' ? props.damage : 0;
+```
+
+**Rarity is reported once, when the roll happens — it is not a field on the instance.** A loot
+open's result carries it (`result.lootResults[i].rarityTier`, from the same `executeRecipe` call
+that opened the box — see "Loot tables and odds" below), and the item instance itself has no
+rarity of its own. If you need the tier to persist on the item, have your config's generation
+write it as a property; it then reads back like any other affix above. Rendering any of these
+values still follows the untrusted-`properties` rule above.
+
+## 9. Catalogs and recipes
+
+A **catalog** is a shop; a **recipe** is one purchasable thing in it. A recipe declares its costs
+(what it consumes), its grants (what it gives), an optional cooldown, a use cap, availability
+windows, and optionally a loot table to roll. Its `recipe_type` is one of `purchase`, `exchange`,
+`claim`, `craft` or `loot_box`, and defaults to `purchase`; any other value — `standard`, for one —
+is refused at upload, naming the five. `gemctl config schema` is the authority if that list grows.
+There is no `consume` kind: a consume — spending an item the player holds, such as a revive token —
+is an `exchange` whose `costs` remove the item.
+
+Running a recipe is the one call that matters here:
+
+```js
+await gem.me.mutations.executeRecipe(catalogId, recipeId);
+```
+
+**A recipe is the only server-authoritative path in the economy.** When you execute one, the
+server charges its costs, checks its prerequisites, enforces its cooldown and rolls any loot
+table — none of which your client can forge. Everything else a shop shows — the price, whether
+the player can afford it, the cooldown, uses remaining, the base odds — is derivable on the client
+from the config and the snapshot you already loaded, with no per-item server call. [The
+tutorial](game-economy-tutorial.md) builds exactly that shop.
+
+Before you execute, you can ask whether a recipe can run, and that answer carries the cooldown so
+you do not need a second read for it:
+
+```js
+const av = await gem.me.mutations.recipeAvailability(catalogId, recipeId);
+av.canExecute; // boolean
+av.reasons; // why not, if not — the server's names: 'on_cooldown', 'insufficient_currency', …
+av.cooldownExpiresAt; // when the cooldown lifts, if it is on one
+```
+
+To read cooldowns for a whole shop at once, rather than one recipe at a time, there is a bulk
+usage read — one request covering every recipe the player has used:
+
+```js
+const usage = await gem.me.mutations.recipeUsageAll();
+usage.usages; // one entry per recipe, with isOnCooldown and cooldownExpiresAt
+usage.truncated; // true if the server had more than it returned — then a missing recipe is UNKNOWN, not idle
+```
+
+Prefer `recipeUsageAll` to render a shop's cooldowns without a call per row, and
+`recipeAvailability` to make the final check on the one recipe a player chose.
+
+### A locked recipe, and why it is locked
+
+A recipe's `prerequisites` — owning an item, completing a progression, reaching a progression value
+or a level — must all hold before it runs. A recipe whose prerequisites do not hold is **locked**,
+and unlike a cooldown or a price, neither waiting nor paying lifts it. `recipeAvailability` says
+whether it is locked and why, with the numbers to show:
+
+```js
+const av = await gem.me.mutations.recipeAvailability(catalogId, recipeId);
+if (av.locked) {
+  for (const lock of av.lockReasons) {
+    // { prerequisiteType: 'progression_level', referenceId, required: 10, current: 7 }
+    if (lock.prerequisiteType === 'progression_level') {
+      showLock(`Reach level ${lock.required} to unlock`); // you are level lock.current
+    }
+  }
+}
+```
+
+`required` and `current` are in the prerequisite's own unit: a quantity for `owns_item`, a value
+for `min_progression_value`, a level for `progression_level`, and `1`/`0` for
+`progression_complete`. `referenceId` is the item or progression, so look it up in your loaded
+config for its name. The prerequisites themselves are on each recipe in the config document, so a
+shop can show "Requires level 10" on every row without a call; `recipeAvailability` is what says
+whether _this_ player meets them.
+
+Render a locked row as locked — with what the player must do — rather than as a buy button that
+fails. The platform checks prerequisites **before it charges anything**: a recipe sold for a platform
+currency (§16) that the player is locked out of is refused with the code `recipe_locked`, and no
+currency moves.
+
+## 10. Orders — the record that something happened
+
+Every change to a player's holdings produces an **order**. Order history is read-only and answers
+"what happened," including the one question that matters after a write — "did it land":
+
+```js
+const result = await gem.me.mutations.executeRecipe(catalogId, recipeId);
+const order = await gem.me.orders.get(result.orderId); // did it land?
+await gem.me.orders.list(); // a page of recent orders
+```
+
+Two things about the history:
+
+- **The `source` of an order is not always your game.** The history holds every order for the
+  player in your game, including ones your game did not create — a reward, a system grant — so do
+  not assume every row is a purchase you made.
+- **It is not an accounting ledger.** It is a record of orders, not a running balance, and summing
+  it will not reconcile against a current total. Read a balance from the snapshot; read history to
+  see events.
+
+Creating an order directly — as opposed to through a recipe — is possible and is covered where it
+belongs, in the reference, because it is **not** how you build a shop. See
+[§14](#14-there-is-no-client-side-integrity-boundary) for why.
+
+When you do create one, `gem.me.mutations.create(operations)` records `source: 'play'` by default:
+that is the generic provenance for a game-authored mutation. Pass
+`{ source: 'game_consume' }` when the order specifically consumes game inventory. Both sources are
+accepted only in your token's game and channel, the currency, item or progression definition must
+still opt into browser writes with `client_writable`, and neither can reach platform inventory.
+They are not interchangeable, though: the platform also uses the source when deciding whether a
+character may be targeted and which configured inventory bucket receives a grant.
+
+## 11. Conditional writes, and why most writes do not want them
+
+You can make a write conditional on the inventory not having changed since you read it, by sending
+the snapshot's `etag`:
+
+```js
+const snap = await gem.me.inventory.snapshot();
+await gem.me.mutations.create(ops, { ifMatch: snap.etag });
+```
+
+A `precondition_failed` (HTTP 412) then means someone else wrote in between. The rule for a 412 is
+**re-read and re-decide — never resend the same body.**
+
+But **most game writes should not send `ifMatch`.** The common operations are deltas — spend this,
+grant that — and the server already bounds them, so they are safe under concurrency without a
+condition. Adding `ifMatch` converts harmless concurrency into 412s and forces a full re-read each
+time. It is genuinely wanted only for a value your client computed as an absolute that the server
+cannot re-derive, or a write that must not double-apply across two devices. It is a
+contention-dependent choice, not a default.
+
+**A 412 and a timeout are opposite cases, and a game that treats both as "retry" corrupts data.**
+A 412 proves the write did _not_ happen — re-decide freely. A timeout proves _nothing_: the write
+may have applied. Do not resend it; read the order back by id to find out what happened.
+
+## 12. Loot tables and odds
+
+A loot table is rolled **server-side only**. You never roll one on the client; you execute a
+recipe that references it, and the server draws from it with weights your client cannot influence.
+
+You can read a table's weights, to show a player their chances:
+
+```js
+const rates = await gem.gameConfig.dropRates('common-chest');
+rates.entries; // each with a weight and a server-computed drop rate
+```
+
+⚠️ **These are the table's odds, not this player's.** Three things move the real chance and none of
+them is in this response: a table may hold per-player pity state that no route exposes; entries can
+be gated on what the player already owns or has progressed past, so a table that cannot drop what
+you hold has different effective odds for everyone; and a mid-session config change is never seen,
+because the config does not re-poll — `gem.gameConfig.refresh()` is the only thing that re-fetches
+it. Show this number as a "base chance," or not as a number at
+all. The only authority on what a player actually receives is the result of executing the recipe.
+
+## 13. Progressions
+
+A **progression** is a track a player advances along — a battle pass, a level, a mastery. You read
+its state from the snapshot, and you advance and claim it through mutations:
+
+```js
+const levels = await gem.me.progressions.list();
+const one = await gem.me.progressions.get('season-1'); // null if the player has no record
+```
+
+A progression that grants rewards on a milestone is claimed like any other write, and the claim
+produces an order you can read back. As with currencies, `get` returns `null` for a player with no
+record of a progression, which is not the same as one they have started and sit at zero on.
+
+**A progression that repeats on a known period is read exactly like this one**, and `get` returns
+this period's value — it resets with the period, without your game doing anything. Adding
+`platform_display: challenge` on top is a feature of its own: the arcade displays it, counts a
+streak, and marks your game's card. It grants rewards and platform currency like any other
+progression. [daily-challenges.md](daily-challenges.md) is the whole of it. Read that before
+giving any progression a `daily`, `weekly` or `monthly` reset.
+
+There are four writes, and the choice between the first two is the one that matters:
+
+```js
+await gem.me.mutations.addProgression('season-xp', 250); // a counter: every match adds
+await gem.me.mutations.maxProgression('level-3-stars', 2); // a record: only a better run moves it
+await gem.me.mutations.claimProgression('season-xp'); // collect what milestones owe
+await gem.me.mutations.resetProgression('season-xp'); // back to the start; claimed rewards stay
+```
+
+`addProgression` is for things that accumulate — experience, kills, coins collected across a
+season. `maxProgression` is for things that are a _best_ — stars on a level, a high score, a
+furthest checkpoint. It raises the value if the new one is higher and does nothing otherwise, so
+replaying a level and doing worse leaves the record alone, and replaying it and doing the same
+records no change at all. Thresholds and rewards fire identically for both. Neither can lower a
+value; lowering is a server-only operation (`progression_set` on the generic order route), which is
+what keeps a milestone from being crossed twice by going back and forth over it.
+
+Whether a browser client may write a progression at all is the definition's `client_writable`
+flag in the game config, which defaults to off. A progression that feeds anything platform-wide —
+a `platform_grants` mapping onto a platform currency — must be written by your game's server or
+your serverless function, never by the browser; see §14.
+
+### Platform grants: awarding a platform-wide currency
+
+The arcade keeps currencies that span every game rather than belonging to yours. A game does not
+write them. A progression in the game's config can declare a _mapping_ — `platform_grants` in the
+gemctl `game-config` skill — and the platform makes the grant itself when that progression moves,
+bounded by the platform's ceilings: what one firing may pay, what one game may pay a player per
+window, and what all games together may pay a player per day.
+
+A platform currency is earned in one game and spent in another, including on items other games
+sell. What each one is for is [arcade-economy.md](arcade-economy.md); which ones your game may pay
+is `gemctl platform config`'s answer.
+
+**Which targets your config may name is the platform's decision and changes as the arcade grows**,
+so this page does not list them. Name one that is not permitted and the config upload is refused
+with an error that enumerates the ones that are.
+
+Gems can be your game's soft currency, awarded through a mapping. A game currency of your own suits
+what lives inside one play loop — coins picked up and spent within a run, energy, crafting
+materials: you control it completely, no other game can spend it, and none of the constraints below
+apply to it.
+
+What that means for game code:
+
+- The source progression is written by your **server** — through its game-server credential
+  against the progression `add` / `max` routes, never through `gem.me` in the browser — or by
+  your **serverless function**, through `call-api` against the same routes. A mapped progression
+  cannot be `client_writable`, cannot be the target of any operation in your config (a recipe, a
+  loot-table entry, another progression's reward), and a browser write to it is refused.
+- **A function pays only from a progression that opts in** with `function_may_grant: true`
+  (otherwise `suppressed`, `functions_not_opted_in`), and **a function a player called pays that
+  player only**: it may change only that player's own state (their inventory, progressions and
+  own characters), and any write to another player is refused with
+  `403 function_foreign_entity_write`. A function never pays a guest
+  (`function_invoker_is_guest`). One call pays
+  once: a second paying order in the same call is `suppressed` with
+  `function_invocation_already_granted`. Every receipt a function's order produces carries
+  `principal: "function"`.
+  [serverless-functions.md](serverless-functions.md#paying-the-player-who-called) is the whole of
+  it, including what the function must check before it pays.
+- A `progressionSet` never fires a mapping — it is a correction. Neither does a reward that
+  happens to add to the source.
+- **The channel does not change where a grant lands.** A mapping fires on `dev`, `test` and
+  `release` alike, into the player's real platform balance, against the real per-game cap — so
+  Gems paid while you test are real, and the allowance they spend is not given back.
+- The order your server gets back carries one `platform_grant` entry in `changes` per mapping:
+  `fired`, `clamped` (and which ceiling bit — the per-firing ceiling, the platform's per-game
+  ceiling or its daily maximum across all games, or the player's holdings cap), or `suppressed`
+  (and why). That entry is the receipt; the player's platform-scope order history does not list
+  these grants.
+- **A ceiling trims; it does not refuse**, for every platform currency. A firing that would cross
+  one is granted what is left of it, and 0 once it is spent — a player 50 short of the daily
+  maximum is paid 50 of a 200 firing. The receipt's `granted` is what landed, and a trim by the
+  per-game ceiling or the daily maximum names `platform_max_per_window`. The one exception is the
+  **holdings cap**, the most a player may hold: a grant that would cross it pays nothing, with
+  `clamped_by: holdings_cap`, so the receipt never reveals how much the player holds.
+- To **show** how much more a player can earn before a grant is trimmed, read it rather than
+  discovering it from a `clamped` receipt: see
+  [Showing how much more a player can earn](#showing-how-much-more-a-player-can-earn).
+- **The platform can switch your grants off**, globally, for one game, for one game and one
+  currency, or only for serverless functions (every game's, or one game's) — and when it has, the
+  receipt says so as a `suppressed` reason. If your mappings stop
+  firing, read the receipt before suspecting your config: that is the difference between "the
+  platform switched this off" and "your mapping is wrong", and it is the only place the two are
+  distinguishable. Existing balances are unaffected — a disable stops new grants and is never a
+  clawback.
+- **Granting a target is never permission to take it back.** No consume or set on a platform
+  currency reaches it from a game. A platform currency is spent by the _player_, through the
+  platform, and never by your game against their balance.
+- The count a player sees as "284 / 300" is what your game has granted them so far in the current
+  window, over the platform's per-game cap. **It counts what you awarded, not what they still
+  hold** — within a window it only rises, resetting or lowering the source progression never takes
+  it back, and a player spending a granted currency does not refill your game's allowance.
+
+### Achievements: the other kind of platform grant
+
+A `platform_grants` entry can also be an **achievement** — a platform-wide recognition with points,
+on the progression's completion or on one level of a track, that unlocks once per player when your
+server, or a serverless function that player called, moves the progression past it. Everything
+above about server-only writes applies — an achievement that awards points or rewards may not sit
+on a progression any operation in your config can raise, so a recipe priced in Gems can never sell
+one — and more: an achievement unlocks only on `release`, it never re-fires, and what it credits is
+fixed once released. Its points are never boosted. [achievements.md](achievements.md) is the whole of it.
+
+## 14. There is no client-side integrity boundary
+
+This is the exception the top of the document promised, and it is the most important paragraph
+here.
+
+> Within your own game's scope there is **no client-side integrity boundary**. Any balance, item
+> or progression a browser client can author, a modified browser client can author differently.
+> Recipes move the arithmetic to the server and are the only thing that does. Do not attach
+> anything of value — a leaderboard, a tournament, a payout, a cross-player market — to a number a
+> client authored.
+>
+> The platform holds itself to the same rule. Nothing a browser authors ever reaches platform
+> inventory: a `platform_grants` mapping fires only for a write your game's _server_ or your
+> _serverless function_ made, on a progression no client can reach, and the platform applies it
+> under its own authority. A game with neither a server nor a serverless function cannot award a
+> platform currency — that is the rule read strictly, not a gap. A function a player calls pays
+> only that player, and only from a progression that opts in
+> ([serverless-functions.md](serverless-functions.md#paying-the-player-who-called)).
+
+Your game can grant itself currency and items within its own scope, and there are legitimate uses
+for that — a single-player game rewarding a level, a prototype. But a grant your client authored is
+a grant a modified client can author differently, so it is never a basis for competition. When the
+value matters, run a **recipe**: the server does the arithmetic, and that is the only thing a
+modified client cannot rewrite. The SDK steering you toward recipes is ergonomics, not a fence —
+the game shares a page with the SDK and can reach any route directly — so the discipline has to be
+yours.
+
+## 15. Batch orders
+
+You can commit several orders together. One caution, because it is a data-loss trap:
+
+⚠️ **A batch is not safe to retry.** The idempotency guard the SDK applies per operation does not
+protect a whole batch the same way, so a batch that times out must not be resent — a resend can
+double-apply the entire batch. As with any write, a timeout is not a failure you retry; read back
+what happened. If a set of changes can be one order with more operations rather than several
+orders in a batch, prefer that.
+
+## 16. Selling for a platform currency
+
+Everything above is about currencies **your game defines** — you mint them, you price in them, and
+nobody else can touch them. The arcade also has currencies that span every game, and a game can both
+**award** one and **be paid in** one.
+
+That changes what a shop can be. A player earns in someone else's game and spends in yours.
+
+There are two such currencies, and they are not interchangeable: **Gems** (`GEMS`) buy progress and
+**Tickets** (`ARCADE_TICKETS`) buy cosmetics only. [arcade-economy.md](arcade-economy.md) says which
+to use for what.
+
+### Awarding one
+
+You do not write platform inventory, and you cannot. Instead a progression in your game config
+declares a _mapping_: when this progression moves, the platform grants the currency itself, under its
+own authority. That is config, not code — see the `platform_grants` section of the gemctl
+`game-config` skill, and note the two rules that catch people:
+
+- the source progression must be written by your **server** or your **serverless function**, never
+  the browser, and
+- it must not be the target of anything else in your config (a recipe, a loot-table entry, another
+  progression's reward).
+
+**Which currencies you may target, and which you may price in, are two different sets, and both are
+the platform's to change.** Ask rather than memorising either:
+
+```bash
+gemctl platform config
+```
+
+It answers both sites at once — everything under `platform_grants` may be a mapping's target,
+everything under `platform_prices` may carry a price, and a currency under neither cannot be used at
+all. The grant rows also carry the platform's ceilings, and a game does not declare its own; a
+`max_per_window` on a mapping is ignored, with a warning.
+
+
+A browser-only game cannot award a platform currency without a server **or a serverless function**.
+That is the price of the platform never trusting a client. A game with no dedicated server writes
+the source progression from a function the player calls, on a progression that opts in with
+`function_may_grant`, and the platform then pays that player only, in any listed platform currency
+— Gems (`GEMS`) and Tickets (`ARCADE_TICKETS`) alike
+([serverless-functions.md](serverless-functions.md#paying-the-player-who-called)).
+
+### Showing the reward land in the arcade's wallet
+
+**Platform-currency display belongs to the arcade** (the creator's ruling, 2026-09-24) — Gems and
+Tickets alike. The arcade draws the player's platform currencies in its own chrome while your game
+runs, and moves a total when the platform confirms a grant. Your game keeps no counter or balance
+of a platform currency of its own, draws no flight or celebration of its own, and shows no
+platform-currency amount at all when it is not connected to the arcade.
+
+What your game does is ask for the payout to start on **your** screen, from the currency's icon (or
+hero) beside the reward, so the currency flies from there into the wallet and the total bounces up
+as it lands. A Gems payout is cued from the gem:
+
+```js
+const { x, y, width, height } = rewardGem.getBoundingClientRect(); // the gem element's own box
+gem.cueReward({
+  currencySlug: 'GEMS',
+  expected: 15, // if you know it; drawn as provisional until the platform confirms
+  origin: { x: x + width / 2, y: y + height / 2 }, // CSS px of your own viewport
+});
+```
+
+`origin` is the **centre of the gem on screen** — measure the gem element itself, not the row or
+panel around it. A Tickets payout is the same call with `currencySlug: 'ARCADE_TICKETS'`, from the
+ticket: the slug decides which total the payout flies into. **If `cueReward` returns `false`, do
+nothing**: there is no fallback celebration.
+`false` means the arcade will not show it here — the bridge is not up, or the embedder has no wallet
+— and your game does not draw one of its own in its place.
+
+Call it when your server moves the mapped progression — just before or just after the write, it does
+not matter; the arcade reconciles. Three things to know:
+
+- **The arcade never takes your word for the amount.** What lands, and the player's new total, come
+  from the platform's own event, sent only after the grant committed. `expected` is drawn as
+  provisional; a cue the platform never confirms fades on its own.
+- **What lands can be less than you cued, and the arcade says why.** A ceiling trims a grant to what
+  is left of it, so at the platform's daily maximum the wallet moves by the part that fit, or not at
+  all once the player's day is spent. When the daily maximum is reached — by a trim, an exact fill
+  or a firing that paid nothing — the arcade shows the player "daily max" and when more of that
+  currency arrives, in its own chrome. That notice is the player's and never reaches your game, so
+  cue every payout the same way: do not predict the outcome of a grant. To show how much more your
+  game can still pay, read [the earn allowance](#showing-how-much-more-a-player-can-earn) — never to
+  decide whether to grant. A mapping the receipt reports `suppressed` produces no event, so its cue
+  fades and the wallet does not move. Do not read the wallet as confirmation of anything: your
+  server's order response is the receipt.
+- **This is presentation, not permission.** It grants nothing, spends nothing and reveals nothing,
+  and a reduced-motion player sees the total change without the flight.
+
+To draw the Gem on your own screen, use the platform's art, which ships in the package — the Gems
+**icon** beside an amount or price, the **hero** only on a reward presentation where the gem is the
+subject. [brand-art.md](brand-art.md) has both, how to draw them, and the rest of the rules.
+
+### Being paid in one
+
+Every game can choose between two purchase owners for the same published platform price:
+
+| Call | Who owns confirmation | Transport | Result |
+| --- | --- | --- | --- |
+| `gem.purchases.request(...)` | the platform | postMessage bridge; platform sheet always opens | `ok`, `declined`, or `unavailable` |
+| `gem.me.mutations.purchase(...)` | your game | direct authenticated SDK request; no bridge or platform sheet | an order-style result or a `GemApiError` |
+
+There is no approval step. Both paths are available to every game.
+
+#### Platform-owned purchase sheet
+
+Use the bridge path when you want the arcade to confirm and process the purchase:
+
+```js
+const config = await gem.gameConfig.load();
+const item = config.item('extra-life');
+
+const res = await gem.purchases.request({
+  kind: 'item', // or 'recipe'
+  targetId: item.id, // UUID, never the slug
+  currencySlug: 'GEMS',
+  quantity: 1,
+});
+
+if (res.outcome === 'ok' || res.outcome === 'unavailable') {
+  gem.me.inventory.refresh();
+  await gem.me.inventory.snapshot();
+}
+```
+
+The platform always opens its purchase sheet for this call. It re-fetches the target and price,
+submits the order with the player's account session, and verifies an `ok` before returning it to the
+game.
+
+- `declined` means the player cancelled or the platform refused, before anything was charged.
+  Return to the shop silently.
+- `unavailable` means no reliable answer arrived. Never retry automatically; re-read inventory
+  because the order may have completed.
+- `ok` means the grant was confirmed. Re-read inventory rather than granting anything locally.
+
+`declined` and `unavailable` also carry `res.reason`, which says why — `cancelled`,
+`insufficient_funds`, `recipe_locked`, `unknown_currency` and the rest of the list in
+[Why a purchase was refused](#why-a-purchase-was-refused). Branch on `outcome`; read `reason` to
+put the right state on the row or to find your own mistake. A reason your SDK version does not
+know arrives as `error`.
+
+The sheet opens only in answer to a player's click or key press, so call `request` from your Buy
+button's handler, never from a timer or on load: without one the answer is `declined` with reason
+`busy`, and nothing is shown. After a player cancels, the arcade answers further asks from your
+game `busy` for a short, growing interval — do not re-ask on `cancelled`.
+
+Hide this specific affordance when `gem.frame.parentSupports('purchases')` is false. That check does
+not apply to the direct SDK path.
+
+#### Game-owned direct purchase
+
+Use the direct path when your game provides its own purchase UI and does not want the platform sheet:
+
+```js
+const result = await gem.me.mutations.purchase({
+  kind: 'item', // or 'recipe'
+  targetId: item.id,
+  quantity: 1,
+  payment: {
+    kind: 'platform_currency',
+    currencySlug: 'GEMS',
+  },
+});
+
+console.log(result.orderId, result.purchaseId, result.status);
+```
+
+The game supplies the target and currency, never an amount. The SDK reads the current purchase
+catalog and active platform currencies, resolves the published price and config version, mints the
+idempotency nonce, and submits the order with the player's game token. gem-api checks the same
+published data again before debiting. A stale price is refused rather than charged at either value.
+
+The same method also replaces `executeRecipe()` for purchases paid by configured game-currency or
+item costs:
+
+```js
+const result = await gem.me.mutations.purchase({
+  kind: 'recipe',
+  catalogId,
+  targetId: recipeId,
+  payment: { kind: 'configured' },
+});
+```
+
+`executeRecipe(catalogId, recipeId)` remains as a compatibility wrapper around this configured
+payment form. Both forms are server-authoritative: a configured payment executes the recipe's costs
+and outputs; a platform-currency payment atomically debits the platform wallet and fulfills the item
+or recipe, reversing the debit if fulfillment fails.
+
+The direct path returns a discriminated result:
+
+- `payment: 'configured'` carries the recipe's `granted`, `consumed`, auto-claimed rewards and
+  loot rolls.
+- `payment: 'platform_currency'` carries `orderId`, `purchaseId`, `sourceOrderId`, `status`
+  and the total `price`.
+
+A refusal rejects, and **`err.code` says why** — in the same vocabulary as the sheet's `reason`:
+
+- Before sending anything, the SDK checks the target and currency against the catalog and the
+  player's platform currencies it just read, and throws a `PurchaseRefusal` (a `RangeError`) with
+  `code` `unknown_currency`, `not_purchasable`, `no_price_in_currency` or `quantity_invalid`. Its
+  message says what to fix: the currencies that are active, the config version it looked in, or
+  what the target _is_ priced in.
+- The platform's own refusals reject as `GemApiError`, whose `code` is the platform's —
+  `insufficient_funds` (with `reason: 'insufficient_funds'`), `price_mismatch`,
+  `config_version_stale`, `recipe_locked`, `recipe_on_cooldown`, `recipe_costs_unmet`, and so on.
+
+```js
+try {
+  await gem.me.mutations.purchase(request);
+} catch (err) {
+  switch (err.code) {
+    case 'insufficient_funds':
+      return showNotEnough(); // your shop's own words, never a top-up screen
+    case 'recipe_locked':
+      return showLock(); // read the lock from recipeAvailability()
+    case 'price_mismatch':
+    case 'config_version_stale':
+      return reloadShop(); // the catalog moved; nothing was charged
+    default:
+      console.error(err); // unknown_currency, no_price_in_currency, … are yours to fix
+      return showStoreUnavailable();
+  }
+}
+```
+
+Do not retry an unsafe write after a timeout; re-read inventory or use the returned order/purchase
+ids for support.
+
+**`targetId` is the UUID, never the slug.** `config.item(...)` accepts either because it is your
+local lookup. The purchase catalog is keyed by ids. Recipes also require `catalogId`.
+
+#### Why a purchase was refused
+
+One vocabulary covers both paths: the sheet's `res.reason` and the direct path's `err.code` are
+the same strings.
+
+| Code                                                                                                                 | What happened                                                                                           | What to do                                                                         |
+| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `unknown_currency`                                                                                                   | the slug is not an active platform currency                           | write `ARCADE_TICKETS` or `GEMS`; the direct path's message lists what is active    |
+| `currency_not_in_game_payable`                                                                                               | the currency exists but cannot pay for game items                                                       | price in a currency `gemctl platform config` lists under `platform_prices`          |
+| `not_purchasable`                                                                                                    | the target is not in the purchase catalog on this channel, or cannot be bought                          | send the id (not the slug); promote the config version that prices it              |
+| `no_price_in_currency`                                                                                               | the target has no price in that currency                                                                | ask in the currency it is priced in, or add the price                              |
+| `busy`                                                                                                               | a purchase is already in flight, a sheet is open, the arcade is backing off after a cancel, or no click | ask again only from a fresh player action                                          |
+| `cancelled`                                                                                                          | the player dismissed the sheet                                                                          | nothing — return to the shop                                                       |
+| `insufficient_funds`                                                                                                 | the player cannot afford it                                                                             | say so in your shop's words; never draw a top-up screen                            |
+| `price_mismatch`, `config_version_stale`                                                                             | the price or config changed since your catalog read; nothing was charged                                | re-read the catalog and re-render                                                  |
+| `platform_currency_unavailable`                                                                                      | the currency is not available to this purchase right now                                                | show the store as unavailable                                                      |
+| `not_available`                                                                                                      | the recipe is outside its availability window, or inactive; nothing was charged                         | hide or disable the row until its window opens                                     |
+| `recipe_locked`                                                                                                      | the recipe's prerequisites are not met; nothing was charged                                             | show the lock from `recipeAvailability().lockReasons`                              |
+| `recipe_on_cooldown`, `recipe_max_uses_exceeded`, `item_max_stack_exceeded`, `recipe_costs_unmet`, `quantity_invalid` | the recipe or item refused this purchase before any charge                                              | reflect it on the row; `recipeAvailability` has the detail                         |
+| `error`                                                                                                              | anything else, or no reliable answer                                                                    | one neutral "store unavailable"; after `unavailable`, re-read inventory            |
+
+Reasons are for your shop's state and your logs. Branch money on `outcome` and on a re-read of
+inventory, never on a reason, and do not retry because of one.
+
+⚠️ **Never draw a top-up or payment screen of your own** — no "get more Gems", no checkout, nothing
+that looks like the arcade's purchase sheet or wallet. A game screen shaped like platform payment
+chrome is an imitation of it. Your Buy button is yours; asking a player to add currency or pay is
+the arcade's alone.
+
+### Tickets buy cosmetics; Gems buy anything
+
+The arcade has two currencies a player spends: **Gems**, for progress, and **Tickets**
+(`ARCADE_TICKETS`), for cosmetics. The platform holds that line with two settings: each platform
+currency's **spend scope**, which the platform sets, and each of your items' **category**, which you
+set.
+
+- A currency whose spend scope is **`cosmetic_only`** may price cosmetics only. Tickets' is.
+- A currency whose spend scope is **`any`** may price anything. Gems' is.
+
+The platform owns each currency's scope and can change it, so do not hard-code which is which: a
+refusal always names the scope that applied.
+
+```yaml
+items:
+  - id: '…'
+    slug: dragon-skin
+    category: cosmetic # changes only how the player looks
+    platform_prices:
+      - currency: ARCADE_TICKETS
+        price: 120
+  - id: '…'
+    slug: extra-life
+    # category omitted: `progression`, the default
+    platform_prices:
+      - currency: GEMS
+        price: 25
+```
+
+- **`category`** is `cosmetic` — skins, outfits, visual effects, decorations, emotes, profile
+  cosmetics: anything that changes how the player looks and never what they can do — or
+  `progression`, anything that affects play. It defaults to `progression`, so an item is only ever a
+  cosmetic because you said so.
+- **A price in a `cosmetic_only` currency, such as Tickets, is accepted only on a cosmetic.** On an
+  item, that item must be `category: cosmetic` and a plain `item_type: item` — a `bundle` or
+  `loot_box` opens into things its own row does not describe, so it cannot be sold for Tickets.
+- **A recipe priced in a `cosmetic_only` currency must grant at least one cosmetic item and nothing
+  else.** It is refused if it grants any currency, moves any progression, grants a non-cosmetic item,
+  or rolls a loot table — a loot table is refused for now even when every entry is cosmetic. Taking
+  from the player as part of the recipe (`currency_consume`, `item_remove`) is fine.
+- **A currency whose scope is `any`, such as Gems, may price anything**, cosmetic or not.
+
+The upload refuses a config that breaks the rule. The refusal names the currency and its scope, and
+the offending item or operation, so you know what to change:
+
+```text
+catalogs[0].recipes[2] (skin-pack): priced in ARCADE_TICKETS, whose spend scope is `cosmetic_only`,
+but grants[1] (item_grant of 'xp-boost') grants an item whose category is `progression`. …
+```
+
+The same rule holds after you publish. If a currency's scope becomes `cosmetic_only` later, the
+purchase catalog stops listing that currency's price on anything the scope does not admit, and a
+purchase naming such a price is refused `not_purchasable` before anything is charged.
+
+The category is a declaration the platform takes at your word, and the release review checks it.
+Labelling something that affects play `cosmetic` so it can be sold for Tickets breaks platform policy.
+
+**To sell a cosmetic that needs game progress first, sell it through a recipe.** An item's own
+`platform_prices` cannot carry prerequisites; a recipe's can. Grant the cosmetic from a recipe that
+declares the prerequisite and carries the Tickets price:
+
+```yaml
+catalogs:
+  - id: '…'
+    slug: cosmetics
+    recipes:
+      - id: '…'
+        slug: buy-dragon-skin
+        prerequisites:
+          - prerequisite_type: progression_level
+            reference_id: '…' # your `mastery` progression
+            reference_value: 10
+        grants:
+          - type: item_grant
+            item_definition_slug: dragon-skin
+        platform_prices:
+          - currency: ARCADE_TICKETS
+            price: 120
+```
+
+A player below level 10 is refused `recipe_locked` before any Tickets are taken, and
+`recipeAvailability` tells your shop the recipe is locked and what it needs (§9) — so show the lock
+("Reach level 10 to unlock") instead of offering the purchase.
+
+### Reading the player's balance
+
+```js
+const currencies = await gem.platform.currencies.get();
+const gems = currencies.find((currency) => currency.slug === 'GEMS');
+buyButton.disabled = !gems || gems.balance < price; // can the player afford it?
+```
+
+**Read it to decide, never to display.** Platform-currency display belongs to the arcade: its
+wallet shows the player's Gems and Tickets totals while your game runs, and your game keeps no
+counter, balance or wallet total of either of its own ([brand-art.md](brand-art.md) §5). Use the
+balance to enable a purchase or to say "not enough Gems" — not to draw a number.
+
+Every game receives every active platform currency. Each row has `access: 'spend'`; the field stays
+in the response shape for existing consumers.
+
+- `currencyId` joins a balance to `platform_prices[].platform_currency_id`.
+- The balance is a snapshot. Re-read when the shop opens and after a purchase; do not poll.
+- This is a player-only read. A dedicated server token is refused.
+- The read itself never spends, grants or sets a balance.
+
+### Showing how much more a player can earn
+
+```js
+const allowances = await gem.platform.earnAllowance.get();
+const gems = allowances.find((a) => a.currencySlug === 'GEMS');
+// 0 or less once `resetsAt` has passed: the read is stale, so say nothing about when.
+const hours = gems?.resetsAt ? Math.ceil((gems.resetsAt - Date.now()) / 3_600_000) : 0;
+if (gems && gems.remaining > 0) {
+  hud.setText(`You can still earn ${gems.remaining} Gems` + (hours > 0 ? `, more in ${hours}h` : ''));
+} else if (gems?.resetsAt) {
+  // Spent for now: say when more arrives, never "0 left".
+  hud.setText(hours > 0 ? `More Gems in ${hours}h` : 'More Gems soon');
+}
+```
+
+One entry per earned platform currency (Gems and Tickets today), for **this game and this player**:
+how much more your game can still grant before the platform's ceilings trim the grant. It is the
+lower of what is left of your game's own cap and what is left of the player's daily maximum across
+all games, with the player's Boost applied — one figure, never a breakdown.
+
+| Field          | What it is                                                                                        |
+| -------------- | ------------------------------------------------------------------------------------------------- |
+| `currencySlug` | `GEMS`, `ARCADE_TICKETS`, … (`''` if the platform sent none)                                      |
+| `currencyId`   | The permanent id; joins to `gem.platform.currencies` and `platform_prices[].platform_currency_id` |
+| `limit`        | The binding ceiling: your game's own allowance, or the daily maximum across every game            |
+| `earned`       | How much of that ceiling has been paid, which may include other games' payouts                    |
+| `remaining`    | How much more can be paid now — the number to show                                                |
+| `period`       | `'day'` or `'window'` (a longer window)                                                           |
+| `periodDays`   | The window's length in days — a label; use `resetsAt` for _when_                                  |
+| `resetsAt`     | When more arrives, in epoch milliseconds — **absent** (never `0`) when no refill is scheduled     |
+
+**Only `remaining` and `resetsAt` are stable to display.** Do not build an `earned / limit` progress
+bar: the bar switches referent when the binding ceiling changes.
+
+A player whose Tickets are spent for today reads `remaining: 0` with a `resetsAt`: say when more
+arrives (from `resetsAt`), not "no Tickets". When the platform has paused a currency's grants for
+your game the entry reads `limit: 0, remaining: 0` with **no** `resetsAt`.
+
+**For a one-day allowance, `resetsAt` is the player's own next midnight — do not assume 00:00 UTC.**
+A longer window is a block of the player's own dates and refills at their local midnight too. Either
+way, render the `resetsAt` you are given rather than computing one. `resetsAt` can be later than the
+end of the reported period when both of the platform's ceilings are spent.
+
+**Display only. Never gate gameplay or a grant on it.**
+
+- ✅ `` hud.setText(`${gems.remaining} Gems left to earn today`) ``
+- ❌ `if (gems.remaining > 0) awardDailyBonus()`
+
+Grant anyway: the platform trims every grant to what is left, and the receipt is the authority on
+what landed. The figure can be stale the moment after you read it — another game may pay the player
+in between — and it is not a reservation. A player at their holdings cap can read a positive
+`remaining` while a grant pays 0.
+
+It is **not a counter** either: it states what your game can still pay, not what the player holds,
+so it never stands in for the arcade's wallet. Like every platform-currency amount, hide it when you
+are not connected to the arcade.
+
+**Staying current.** Read on your own schedule — on load, on a results screen, after your own grant.
+Some arcades also tell your game when the allowance may have changed — after your own grant, or a
+platform-wide change that moved your figure:
+
+```js
+let pending = false;
+const off = gem.platform.earnAllowance.on('changed', async () => {
+  if (pending) return;
+  pending = true;
+  try {
+    await refreshAllowance();
+  } finally {
+    pending = false;
+  }
+});
+```
+
+The listener receives no figures; call `get()` again. A burst of hints should produce one read. It
+is an upgrade, never a replacement for reading: an arcade may never send it, and nothing is fetched
+for you when it fires. Do not poll.
+
+**Errors.** `get()` rejects only when the platform could not be asked or refused the caller:
+`forbidden` (a context with no player, such as a game server), `not_found`, the retryable
+`unavailable` or `rate_limited`, or an `AuthError` when the play token cannot be renewed. **An outage
+rejects; it is never a zero** — a spent-looking allowance would be a wrong answer, so show nothing
+rather than "0 left".
+
+## What you cannot do here
+
+**You cannot submit an arbitrary platform debit, grant or amount.** A direct purchase names a
+published target and currency; the SDK and API resolve and verify the price. General platform-scope
+inventory writes remain unavailable. Your own currencies remain entirely yours.
+
+**You cannot read general platform inventory.** `gem.platform.currencies.get()` exposes active
+currency balances only, and `gem.platform.earnAllowance.get()` one consolidated figure per currency
+for this game. History, items, orders outside this game, other platform holdings, and a per-game
+breakdown of the player's earnings stay out of reach.
+
+**You cannot take back what you awarded.** Granting a platform currency is never permission to
+remove it. A player spends it through the platform, by choosing to.
+
+**You cannot sell for real money here.** A platform currency a player _earns_ is what this surface
+reaches. Charging actual money is a separate platform capability and is not something a game config
+grants itself.
+
+## Errors
+
+| What you get                                            | What happened                                                                                                                             | What to do                                                                                                                                                    |
+| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A read or grant resolves to nothing for an id           | The definition is not on this channel — uploaded but not promoted, or a channel mismatch between the running game and the promoted config | Promote the config version to the channel your game runs; see [`saving-player-progress.md`](saving-player-progress.md#1-declare-the-slot-in-your-game-config) |
+| `null` from `load()`                                    | This game has no config on this channel, or its version has not built yet                                                                 | A real state; render the no-economy path rather than catching an error                                                                                        |
+| `insufficient_funds` (HTTP 402) on a consume            | The player cannot afford it                                                                                                               | Re-read the balance and re-render; do not retry the same write                                                                                                |
+| `precondition_failed` (HTTP 412) on a conditional write | Someone else wrote since your read                                                                                                        | Re-read and re-decide — never resend the same body                                                                                                            |
+| A recipe reports it cannot run                          | A cooldown, a use cap, an unmet prerequisite, or an availability window                                                                   | Show the reason from `recipeAvailability`; the cooldown's end is on that same response                                                                        |
+| `recipe_locked` (HTTP 422) on a purchase                | The player does not meet the recipe's prerequisites; nothing was charged                                                                  | Show the lock from `recipeAvailability().lockReasons`; do not retry until it lifts                                                                            |
+| Any other purchase refusal, as `reason` or `err.code`   | The purchase was refused, and the code says why                                                                                           | See [Why a purchase was refused](#why-a-purchase-was-refused)                                                                                                 |
+| A write times out                                       | Unknown — it may have applied                                                                                                             | Do not resend; read the order back by id                                                                                                                      |
+
+## What to read next
+
+- [`arcade-economy.md`](arcade-economy.md) — Gems, Tickets and achievement points: which to use for
+  what, and the rules each carries.
+- [`achievements.md`](achievements.md) — platform achievements on your progressions' thresholds.
+- [`game-economy-tutorial.md`](game-economy-tutorial.md) — build a shop, step by step, the safe way.
+- [`trading-and-gifting.md`](trading-and-gifting.md) — move items and currency between players.
+- [`saving-player-progress.md`](saving-player-progress.md) — a save often holds an inventory; the two are neighbours.