@indiegems/gem-web-sdk 7.5.0 → 7.7.0

package/docs/daily-challenges.md

@@ -64,8 +64,10 @@ reset_schedule: { type: daily, boundary: UTC, reset_time: '04:00' }
 
 - **`boundary`** — `local`, the default, is each player's own time zone. An IANA zone name such as
   `UTC` or `Asia/Tokyo` puts every player on that one calendar instead, so everybody's day turns
-  over at the same instant: what a daily leaderboard, or a server that works out "today" for
-  itself, needs.
+  over at the same instant: what a strictly fair daily leaderboard, or a server that works out
+  "today" for itself, needs. A daily leaderboard works on `local` too, with players on the same
+  date sharing a board — [section 10](#10-what-your-game-can-read-back) has the read, and
+  [leaderboards.md](leaderboards.md#one-day-many-time-zones) what the choice costs.
 - **`reset_time`** — the clock time, `HH:MM` in that zone, at which a period begins. The default is
   `00:00`; `'04:00'` lets a late-night player finish the day they started. Quote it: some YAML
   parsers read an unquoted `04:00` as a number.
@@ -563,6 +565,16 @@ server reads the same list for one player with `gem.challenges.list({ playerId }
 **How the player is doing in THIS period — yes**, through the ordinary progression read
 (section 3): `currentValue` and `isCompleted` are this period's, and reset with it.
 
+**How everybody did in THIS period — yes, if you declare a board for it.** A leaderboard can be
+scoped to this challenge's periods: today's standings, which start empty each day and close when
+the day does. Name the challenge on the board's run type and set `per_period` on the board; the
+board then takes this challenge's schedule, boundary and reset time, and
+`gem.leaderboards.get('daily')` answers for the player's current period. It needs no
+`platform_display` and no stored content. When your function or server records the run, send the
+`periodLocalDate` you read here as the run's `period_id`, so a run finished just before midnight
+counts for the day it was played. [A board for each day](leaderboards.md#a-board-for-each-day-period-boards)
+is the page.
+
 **Their per-period history and their streak — no.** There is no history read and no streak read in
 the SDK. The arcade is what displays those — the marker on your game's card, and the player's own
 progress, history and streak on platform surfaces. Your game does not have to render any of it.

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "7.5.0"
+  "@indiegems/gem-web-sdk": "7.7.0"
 }
 ```
 
@@ -157,11 +157,13 @@ your reports arrive with no picture. Two-dimensional canvas games need nothing h
 covers overriding the capture and attaching your own debug state, which is the part actually
 worth spending effort on.
 
-**There is no offline mode.** A game must be framed by an arcade page to reach the platform:
-unframed it still constructs and runs, but the bridge never connects and anything needing a
-token waits forever. To run framed without publishing, open your served build in the Gem
-Arcade app (step 6 below), or use the SDK repository's `examples/dev-harness/` — a local
-parent page that frames your dev server and completes a real handshake.
+**There is no offline mode.** A game must be framed by a page that speaks the bridge: opened
+at the top level, `createGem` throws `GemUnframedError`, which says how to run it. To run framed
+without publishing, use the Gem dev host, signed in to `gemctl`: `npm run dev` in a project the
+Gem tools scaffolded (`gemctl serve start . --dev`, your vite server with hot reload), or
+`gemctl serve start .` for a build. The Gem Editor's Play frames it too, and the SDK
+repository's `examples/dev-harness/` is a local parent page that frames your dev server. Never
+open the dev server's own address.
 
 ## 5. Tell the arcade when you are ready
 

package/docs/leaderboards.md

@@ -28,6 +28,10 @@ response, and their rank among everyone is not the rank most screens want anyway
 last runs"_. `get()` is for a standings screen. `friends()` is for a standings screen among people
 the player knows.
 
+**Want today's standings rather than all-time ones?** That is the same four reads over a board
+declared `per_period` — one board for each day of a daily challenge — and it has its own section:
+[A board for each day](#a-board-for-each-day-period-boards).
+
 `character()` is `mine()` for a character. **Read the leg your server WRITES.** Runs carry the
 entity that owns them, so if your server reports character-owned runs, `mine()` returns nothing and
 `character()` is the read you want — and vice versa. That mismatch is the commonest reason one of
@@ -226,6 +230,139 @@ is the second most likely reason a board looks empty.
 const theirs = await gem.leaderboards.character('time-trial', characterId);
 ```
 
+## A board for each day — period boards
+
+Everything above ranks **every run a board has ever been given**. A daily challenge wants something
+else: _today's_ standings, which start empty each day and close when the day does. Declare the board
+`per_period` and it exists once per period of a challenge — one board for each day of a daily
+challenge, each week of a weekly one, each month of a monthly one.
+
+You do not give the board a schedule. It takes the challenge's: the same days, the same reset
+time, the same time-zone rule. A board cannot drift from the challenge it belongs to, because it
+has no clock of its own.
+
+### Declare it
+
+Three pieces, and the middle one is the link. The run type names the **challenge** its runs belong
+to — the `id` of a progression in the same config with a `reset_schedule` — and the board asks to
+be split by that challenge's periods:
+
+```yaml
+progressions:
+  - id: 4f2a9c71-3e8b-4d15-9a62-7c0e5b1d8f43
+    slug: daily-puzzle
+    config:
+      completion_threshold: 1
+      reset_schedule: { type: daily }
+
+run_types:
+  - id: daily-run
+    int_value_1_name: moves
+    challenge: 4f2a9c71-3e8b-4d15-9a62-7c0e5b1d8f43
+
+leaderboards:
+  - id: daily
+    run_type: daily-run
+    order_by:
+      - column: int_value_1
+        direction: asc
+    per_period: true
+```
+
+- **If you already have a daily challenge, use its id.** The progression in
+  [daily-challenges.md](daily-challenges.md) is the same kind of thing; nothing new is needed.
+- **The challenge does not have to be shown on your game's card.** A progression with a
+  `reset_schedule` and nothing else is enough — no `platform_display`, no stored content.
+- **`daily`, `weekly`, `monthly` and a cron expression all work.** A progression with no
+  `reset_schedule`, or one that resets on an event, has no periods and is refused at upload.
+- **One set of runs can back two boards.** Leave `per_period` off a second board over the same run
+  type and it ranks every run: "today" and "all time" from the same reports.
+
+### Record a run
+
+Nothing changes in how a run is reported — your [serverless function](serverless-functions.md) or
+your dedicated server reports it, never the browser. What changes is that the platform files each
+run under a period:
+
+- **The platform decides the period, from when it receives the run and the player's own time
+  zone.** Not from the device clock, and not from the run's `occurred_at`.
+- **Name the period the run was played for.** Send `period_id` on the run, set to the challenge's
+  `periodLocalDate` from `gem.challenges.list()` as the player's game had it. A run that finishes
+  seconds before midnight and is checked seconds after still counts for the day it was played,
+  for **10 minutes** after that day ends. Leave it out and the run goes to whatever period it
+  arrives in — tomorrow's board, for that late run.
+- ⚠️ **A run for a period that is not open for the player is refused, and the whole batch with
+  it** — `409 run_period_closed`. That is a day that ended more than ten minutes ago, or one that
+  has not started for them. Do not retry it: tell the player the day has closed.
+- ⚠️ **Every run is a row.** A period board ranks every run it is given, so a player who plays
+  five times today holds five rows. For one row per player, have your function record one run per
+  player per period — `gem.leaderboards.mine('daily')` tells it whether today already has one.
+
+### Read it
+
+Every read answers for **one period**, and says which:
+
+```js
+const today = await gem.leaderboards.get('daily');
+const yesterday = await gem.leaderboards.get('daily', { periodsBack: 1 });
+
+heading(today.period.localDate, today.period.final ? 'Final' : 'So far');
+```
+
+| Option            | Reads                                                                             |
+| ----------------- | --------------------------------------------------------------------------------- |
+| _(none)_          | the player's current period                                                       |
+| `periodsBack: n`  | `n` periods before it — yesterday for a daily, last week for a weekly. 0 to 400   |
+| `period: id`      | exactly that period, from an earlier result's `period.id` — for a shared link or a history screen |
+
+`friends()`, `mine()` and `character()` take the same options. On `mine()` the runs, the personal
+best and the total are that one period's, so `personalBest` is "your best today" and an empty
+result each morning is the ordinary state.
+
+The result's `period` is absent on an ordinary board and carries, on a period board:
+
+| Field                | What it is                                                                      |
+| -------------------- | ------------------------------------------------------------------------------- |
+| `id`                 | the board's identity. Pass it back as `period` to read this same board again    |
+| `localDate`          | the date — the same value the challenge gives as `periodLocalDate`. Absent for a cron challenge |
+| `startAt`, `endsAt`  | the **player's own** day, in Unix seconds                                       |
+| `opensAt`, `closesAt` | when the board accepts runs from **anyone**, in Unix seconds                   |
+| `final`              | `true` once no run can still arrive                                             |
+
+⚠️ **Ask the platform which day it is; never work it out.** The player's day is a date on their
+own calendar, in the time zone the platform holds for them. A board id built from the device clock
+— `new Date().toISOString().slice(0, 10)` — names the wrong board for every player whose day is
+not the UTC day, and for the hours either side of midnight for everyone else. Read with no option
+for today, and take `period.id` from the result when you need to name it.
+
+### One day, many time zones
+
+On the default `local` boundary each player's day is their own: it begins at their midnight.
+**Players on the same date share one board, whatever their time zone** — the same board the
+challenge's seed gives them all. Three consequences follow, and each one surprises somebody:
+
+- **A day's board stays open about 50 hours.** It opens when the date begins in the earliest time
+  zone and closes when it ends in the latest. So the standings can change after _your_ day has
+  ended, and "you finished 3rd today" shown at the player's midnight can be wrong an hour later.
+  Say "so far" until `period.final` is `true`. Two or three days' boards are open at any moment.
+- **Players whose day starts later see the earlier results first.** The puzzle is the same for
+  everyone on the date, so a player in a later time zone can see scores — and may be handed
+  solutions — before they play. If your board has to be strictly fair, put the challenge on one
+  clock for everybody: `reset_schedule: { type: daily, boundary: UTC }`. Everyone's day then turns
+  over at the same instant, and the board is open for exactly that day.
+- **Rows carry no time.** `occurredAt` is `0` on a period board that follows each player's own time
+  zone: beside the board's date, a run's time would show where its player is. Render nothing for
+  `0`. Ranks are unaffected.
+
+**Changing time zone does not buy a longer day.** A player's first run on a date fixes when that
+date ends for them. Runs after that moment are refused for the date, even if the player has since
+moved to a time zone where it is still running.
+
+**From a serverless function or a dedicated server, name the player.** Their credential carries no
+player, so a period read is answered in UTC unless you pass
+`{ playerId }` — which is not that player's day on a `local` challenge. In the browser the read is
+always for the signed-in player and `playerId` is ignored.
+
 ## Where the rows come from
 
 Runs are reported **from the server side** — by a dedicated server during its match, or by your
@@ -262,6 +399,9 @@ a `code`, and testing `err.reason === 'bad_request'` never matches, because a 40
 | `reason: 'invalid'`, `code: 'invalid_bucket'`                                       | bucket values do not match the board's `bucket_by`                                                                                                                                                 | supply exactly the buckets the board declares                                                                                                                                                                                                                                                                                            |
 | `reason: 'not_found'`, `code: 'leaderboard_not_found'`, on `mine()` / `character()` | **also** the entity is not one you may read — an unknown character, one you do not own, one in another game, or a malformed id                                                                     | **the same code as the row above**, which is the point: the entity read answers ONE refusal for every reason that depends on the target, deliberately, because a distinguishable answer would tell a caller whether a given player plays this game. Check the entity id as well as the board id — nothing in the response separates them |
 | `reason: 'forbidden'`, on `mine()` / `character()` / `friends()`                    | the caller may not act for this entity at all, or (on `friends()`) carries no player identity at all — a game server token, say. Decided from the caller's own claims, not from what was asked for | this one is worth telling apart, and it is not about the target: it will not start working because the player played more. Treat it as a bug in how the call was made, not as an empty board. `get()` never answers this — the global board needs no viewer                                                                              |
+| `reason: 'invalid'`, `code: 'invalid_period'` | `periodsBack` or `period` asked of a board that is not `per_period`; or a `period` that is not one of the challenge's, or more than 400 periods back | a board that ranks every run has no periods to select: drop the option, or declare the board `per_period`. Otherwise take the id from an earlier result's `period.id` rather than building one |
+| `reason: 'invalid'`, `code: 'period_not_begun'` | the `period` asked for has not begun for this player, even if it has for players in time zones ahead of theirs | read with no option for the player's own current period |
+| `TypeError` (thrown, no request sent) | `periodsBack` out of 0–400, a `period` that is not a period id, or both passed at once | pass one of them, or neither |
 | `reason: 'invalid'`, `code: 'bad_request'`                                          | `limit` is not an integer in 1–100                                                                                                                                                                 | the SDK refuses this locally with a `TypeError` before any request, so seeing it from the server means something else built the URL                                                                                                                                                                                                      |
 | `TypeError` (thrown, no request sent)                                               | `limit` out of range, passed to `mine()` / `character()`                                                                                                                                           | pass an integer 1–100, or omit it for the default 25                                                                                                                                                                                                                                                                                     |
 

package/docs/manifest.json

@@ -13,8 +13,8 @@
     },
     {
       "file": "analytics.md",
-      "sha256": "4d6b9e5c2cbc47c527c0437329c7b3d7ebc61136a8c384f4e0a640f9fd4ed226",
-      "updated": "2026-10-02T01:09:38Z"
+      "sha256": "57fb07c3d649c2758a35660707d31b05164b363e9a425156978aed394d086339",
+      "updated": "2026-10-02T14:04:37Z"
     },
     {
       "file": "arcade-economy.md",
@@ -31,6 +31,11 @@
       "sha256": "cf54939a0fcee1f5a6e11b9de52b5ed498ec8c373683e92aa5bc6654b12eb0ab",
       "updated": "2026-10-01T03:49:20Z"
     },
+    {
+      "file": "changelog.md",
+      "sha256": "02083c9ed1d62baed5a297ca71b602608afa90320afb73a21ff03187da11346f",
+      "updated": "2026-10-02T04:41:46Z"
+    },
     {
       "file": "cross-promotion.md",
       "sha256": "3a8121a9c973e4a1bfed076a3226d139f8b4e38a173a06ea9f08000c72bca4b4",
@@ -38,8 +43,8 @@
     },
     {
       "file": "daily-challenges.md",
-      "sha256": "4820868e911cc518a5c37cbd8c31b36a8a2374e280be14f3a6dfa45985685372",
-      "updated": "2026-10-01T19:59:43Z"
+      "sha256": "7ba296ba3056407ca3c8c9757a3351f3a8062a943335ee52b4ee92e1b2721d3b",
+      "updated": "2026-10-02T18:52:17Z"
     },
     {
       "file": "dedicated-server-flow.md",
@@ -63,8 +68,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "678670383df1f4df16253616869d9c2d1aceaf3e2464f7499c6ff50cee70a82b",
-      "updated": "2026-10-02T01:21:17Z"
+      "sha256": "4a3c179022bbc7143b190a27a78c6fac8f7f92d8964b2dc6aec7342b052f40e1",
+      "updated": "2026-10-02T19:06:36Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -73,8 +78,8 @@
     },
     {
       "file": "leaderboards.md",
-      "sha256": "940be101a9a06a6ddad85a1afe18a23e9acca43772d158ff7be70ed0f2f6b28d",
-      "updated": "2026-09-28T19:46:26Z"
+      "sha256": "4f065b915604284ec810aa3c7bc046bfd99f343332a70b35921ecf061503f867",
+      "updated": "2026-10-02T18:52:17Z"
     },
     {
       "file": "match-session.md",
@@ -113,13 +118,18 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "abc87cf6bf86bd7c0538a983aa8681460f8c8d82fbee7bb78515ce5f97fb2e3f",
-      "updated": "2026-10-02T01:21:17Z"
+      "sha256": "7d48bdbc026a03c78d26c24bf217fab1aa8df9d358fbe54c64fa53f18aa0d77b",
+      "updated": "2026-10-02T19:06:36Z"
+    },
+    {
+      "file": "serverless-functions-js.md",
+      "sha256": "86b0f9f0b742a662ebb78b1538cbbc399309725faf22f46f613b63b5e0864082",
+      "updated": "2026-10-02T17:17:29Z"
     },
     {
       "file": "serverless-functions.md",
-      "sha256": "3b61ee955d3bc439c39a7cad9339f8ffe8c0fb584f0a25621b877e185160a45a",
-      "updated": "2026-10-01T18:13:51Z"
+      "sha256": "c830daf736713744909700bf93ff5ba139b8b5d8ad3c2b4e057ca813fc6179f7",
+      "updated": "2026-10-02T18:52:17Z"
     },
     {
       "file": "trading-and-gifting.md",
@@ -128,8 +138,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "25ea532aa4f0a2b2f3139fc52516bdc869e3ada921935337462b6655de2b0938",
-      "updated": "2026-10-02T01:09:38Z"
+      "sha256": "a0a2952a2b16b43b0af831ff58ad8fabe47b414f57fccd2cb2d866861a65465e",
+      "updated": "2026-10-02T14:04:37Z"
     }
   ]
 }

package/docs/server-bundles.md

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

package/docs/serverless-functions-js.md

@@ -0,0 +1,139 @@
+# Serverless functions in JavaScript
+
+<!-- gem-web: unpublished — the platform does not run JavaScript functions yet -->
+
+A serverless function can be written in JavaScript or TypeScript instead of Rust: the language your
+game is already written in, so the verification code in your browser game moves into a function
+with no change beyond bundling. You upload one bundled ES module, and the platform runs it on a
+JavaScript engine of its own.
+
+Everything [serverless-functions.md](serverless-functions.md) says about what a function is for,
+what it may change, its limits, channels, and calling it from your game holds here unchanged. This
+page covers only what is different: how you write one, how the SDK behaves inside it, and how
+publishing checks it.
+
+## 1. The contract
+
+The same as a component's: bytes in, bytes out, one fresh instance per call, nothing kept between
+calls. Your module exports **exactly one** of two functions, and which one decides how the bytes
+are read and written:
+
+| Export              | Input                                                 | Return                                                                                                    |
+| ------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `handle(input)`     | `Uint8Array`: the request body, byte for byte         | `Uint8Array`, `ArrayBuffer` or `string` (sent as UTF-8); anything else is an error                        |
+| `handleJson(input)` | the body parsed as JSON; an empty body is `undefined` | any JSON-serializable value, sent as its JSON text; `undefined` is sent as `null`; a `BigInt` is an error |
+
+Either may be `async`; the platform waits for the promise. Exporting neither, or both, is refused
+when you upload. A caller cannot tell which kind of function answered: `gem.functions.invoke`, the
+limits and the refusals in serverless-functions.md are identical for both.
+
+**A thrown exception is `Err`.** The call fails with `function_error`, and `err.functionMessage` is
+the exception's `name: message` (a thrown value that is not an `Error` is its `String()`). The
+message and the stack go to the platform's log for the invocation, never to the caller. A
+`handleJson` whose input is not JSON, or whose return value JSON cannot carry, fails the same way.
+
+**`console.*` reaches the invocation's log** at the matching level (`debug`, `info`, `warn`,
+`error`); `console.log` and every other method log at `info`. As with a component's `log`, nothing
+reads it back to you: the invocation id is what you quote about one call.
+
+## 2. Writing one
+
+```bash
+gemctl function init --lang js functions/score-check
+cd functions/score-check && npm install && npm run build
+gemctl function upload dist/function.js
+```
+
+**`init --lang js`** writes a `package.json` whose `build` script type-checks and then bundles to
+one ES module, a TypeScript starter handler and a `tsconfig.json`. gemctl runs neither step:
+`npm run build` is yours, the way `cargo build` is for a component.
+
+A handler looks like this:
+
+```ts
+import { createGem } from '@indiegems/gem-web-sdk/function';
+
+export async function handleJson(claim: { level: number }) {
+  const gem = createGem();
+  console.info(`level ${claim.level} claimed by ${gem.identity?.playerId ?? 'a game server'}`);
+  // Decide from what the player cannot forge, and make any write through `gem`
+  // here, before answering: the answer itself is only advice to the browser.
+  return { accepted: false };
+}
+```
+
+The package is the one your game already depends on, installed as
+[getting-started.md](getting-started.md) shows. What makes a check worth running is
+serverless-functions.md section 1, and it applies unchanged: a save or a setting the player's own
+browser can write is the player's claim, not evidence.
+
+**Imports.** The module may import the SDK and nothing else, under any of the three names a game
+already uses: `@indiegems/gem-web-sdk/function`, `@indiegems/gem-web-sdk/sdk`, or
+`@indiegems/gem-web-sdk/game`. Inside a function all three are the same module, the function
+entry, so shared code keeps its import. A name that module does not export, such as
+`defineServer`, fails every call with `function_error`. Everything else your code needs is bundled
+in, which is what the starter's build does. An `import()` at runtime is refused at upload.
+Top-level `await` is allowed and runs on every call.
+
+**What the engine gives you.** `Date`, `performance`, `Math.random`, `crypto.getRandomValues`,
+`crypto.randomUUID`, `TextEncoder`, `URL` and `fetch` all work. `fetch` reaches only the platform
+API, through the SDK, and the save links the platform hands you; any other URL is refused. A timer
+waits at most 10 ms: a function has no reason to sleep, and a long one would run out the wall
+clock.
+
+**The SDK version your function runs is the one the platform bundles**, not the one in your
+`package.json`; the starter pins the matching version. A method added in a newer SDK reaches a
+function when the platform's engine picks that version up.
+
+## 3. The SDK inside a function
+
+`createGem()` from `@indiegems/gem-web-sdk/function` is synchronous, `awaitBridge()` and
+`awaitIdentity()` resolve at once, and `gem.me` is the player who called. So a game's boot sequence
+runs unchanged, and the same `gem.me.saves.get`, `gem.leaderboards.get` and `gem.profiles.of` calls
+work, with the same types and the same errors. The function's game and channel come from the call;
+nothing you write names them. `gem.context` is who called, for which game and channel, and
+`gem.identity` is the same three fields a browser game reads from its own `gem.identity`.
+
+What a browser game has that is backed by the page or the arcade (ads, purchases, rooms, device
+settings, sharing) is not on `gem` inside a function. Four more differences, each following from
+how a function reaches the platform:
+
+- **`gem.me` is the invoker.** When a game server invoked the function there is no player, and
+  reading `gem.me` or `gem.transfers` throws saying so; `gem.identity` is `null`. Which writes a
+  player-invoked function may make is unchanged (serverless-functions.md section 2).
+- **No conditional requests, and no retries.** The platform call a function makes carries no
+  headers, so an `ifMatch` or `ifNoneMatch` cannot travel. A call carrying one is refused with
+  `TransportRefusal` naming the option, rather than sent as an overwrite that checks nothing.
+  Nothing is retried either: a retry is another platform call and a wait is your function's wall
+  clock, so your code decides.
+- **`gem.functions` is absent.** A function may not invoke a function.
+- **`gem.gameConfig` is absent.** The config document is not reachable from a function, so
+  `gem.me.currencies.get()` takes a currency id rather than a slug.
+
+`gem.friends.challenge()` answers `unavailable` without asking anything, because there is nobody in
+front of a screen to confirm it, and `gem.platform.earnAllowance.on()` never fires.
+
+⚠️ **Flush analytics before you return.** A page flushes on a timer and as it closes; a function
+ends the moment your handler settles, so `await gem.analytics.flush()` before you return, or the
+events may be lost.
+
+## 4. Check before you upload
+
+```bash
+gemctl function check dist/function.js
+```
+
+`check` runs the platform's publish-time validation for JavaScript on your machine, and an upload
+answers `400 source_invalid` with the same `details.reason`:
+
+| Reason             | What it usually is                                                        | What to change                                    |
+| ------------------ | ------------------------------------------------------------------------- | ------------------------------------------------- |
+| `not_a_module`     | A parse error, with its line and column, or a file that is not UTF-8      | Fix the syntax; bundle to ES2022                  |
+| `forbidden_import` | An `import` or `export … from` of anything but the SDK, or an `import()`  | Bundle the dependency in; drop the dynamic import |
+| `missing_handle`   | Neither `handle` nor `handleJson` is exported (`export *` does not count) | Export one of them from the module itself         |
+| `ambiguous_handle` | Both are exported                                                         | Keep one                                          |
+| `too_large`        | Over the size limit, the same one a component has                         | Bundle less; check what your build pulled in      |
+
+An upload also answers `source_invalid`, rather than `component_invalid`, for `not_uploaded`,
+`size_mismatch` and `sha256_mismatch`: upload again. Promoting, channels and invoking are the same
+as for a component (serverless-functions.md sections 4 to 7).

package/docs/serverless-functions.md

@@ -183,11 +183,15 @@ do not decide whether a reward was earned. So:
   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;
+- if you key the order that grants with a `nonce` instead, build the key from something the
+  platform decides: the date of the player's daily, or an id the platform issued, such as a match
+  it ran. That date is `period_local_date` on your
+  [daily challenge](daily-challenges.md#the-one-call-that-answers-both), read for the caller with
+  `GET /v1/challenges?player_id=<their id>` (`daily:2026-09-26`), and it is the player's own day
+  unless the challenge's `boundary` fixes a zone. The UTC date from `now-ms` names a UTC day,
+  which for a player off UTC is not the day their daily runs on. **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 day, not a week or a lifetime;
 - never pass the caller's request straight through to a progression write.
 
 ### What `call-api` can reach
@@ -386,6 +390,31 @@ The path's `{game_id}` is the game id from `get-context`, `entity_id` is the pla
 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 run for a daily board names its day.** When the run type belongs to a challenge — its config
+names one with `challenge`, which is what a
+[`per_period` board](leaderboards.md#a-board-for-each-day-period-boards) ranks — the platform
+files the run under one period of that challenge. It decides which from when the run arrives and
+the player's own time zone, never from `occurred_at`. Add `"period_id"` to the run, set to the
+`periodLocalDate` the player's game read from `gem.challenges.list()` and sent you with the result:
+
+```json
+{
+  "run_id": "5b0d3c1e-8f7a-4c2e-9d61-0a4b7e2f9c13",
+  "entity_type": "player",
+  "entity_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
+  "run_type": "daily-run",
+  "int_value_1": 14,
+  "period_id": "2026-10-02"
+}
+```
+
+A run that names the day it was played for still counts for that day when it arrives up to 10
+minutes after the day ended for the player. Without `period_id` the run goes to the period it
+arrives in. ⚠️ **`period_id` is a claim the platform checks, not a choice it obeys**: a client
+cannot use it to post to yesterday's board, or to a day that has not begun for the player. For a
+cron challenge the id is the period's start, as `2026-10-02T06:00:00Z`. Send no `period_id` for a
+run type that names no challenge; it is refused there.
+
 ⚠️ **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)
@@ -396,6 +425,7 @@ before you record it, or any player can put any score they like on your board.
 | `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                                      |
+| `409 run_period_closed`             | A run's challenge period is not open for its player: the day ended more than 10 minutes ago, or has not begun for them. Nothing was written, and `details` names the run by `index` and `run_id` | Do not retry that run. Tell the player the day has closed, and send the rest of the batch without it |
 | `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                                        |