@idosgames/mcp 0.1.2 → 0.1.4

package/registry/skills/idosgames-agent-debug-surface.json

@@ -0,0 +1,6 @@
+{
+  "name": "idosgames-agent-debug-surface",
+  "description": "Make a module observable and controllable by the AI Coder's agent through ctx.exposeToAgent — the ModuleAgentApi contract (state, actions, describeActions) that backs the GetGameState and GameAction tools. Read it BEFORE writing any module that renders into a canvas (three.js, Phaser, Pixi, raw WebGL/2d) — publishing the surface and avoiding Pointer Lock are part of building one. Also use it whenever a rendered game has to be debugged or verified in the live preview, when the agent reports \"the DOM shows nothing about this game\", or when a developer adds player/world state or agent-drivable actions to a module.",
+  "content": "---\nname: idosgames-agent-debug-surface\ndescription: >-\n  Make a module observable and controllable by the AI Coder's agent through ctx.exposeToAgent — the\n  ModuleAgentApi contract (state, actions, describeActions) that backs the GetGameState and\n  GameAction tools. Read it BEFORE writing any module that renders into a canvas (three.js, Phaser,\n  Pixi, raw WebGL/2d) — publishing the surface and avoiding Pointer Lock are part of building one.\n  Also use it whenever a rendered game has to be debugged or verified in the live preview, when the\n  agent reports \"the DOM shows nothing about this game\", or when a developer adds player/world\n  state or agent-drivable actions to a module.\n---\n\n# Making a module visible to the agent (`ctx.exposeToAgent`)\n\nThe agent inspects a running app by reading its DOM. A rendered game has no DOM to read — it is one\n`<canvas>` — so what the game _is doing_ is invisible unless the module says so itself.\n\n`ctx.exposeToAgent` closes that gap. The module publishes a small debug surface; the preview probe\npicks it up and the agent reaches it with two tools:\n\n- **GetGameState** — reads `state()` of every module that opted in, plus the list of its actions.\n- **GameAction** — calls one action and returns the state after it.\n\n## What the agent already sees without you\n\n`GetGameState` always returns an **automatic layer** first, measured by the preview probe with no\ncooperation from the game: which canvas and graphics context exist, fps, frames and draw calls,\na sparse grid of pixels read back from the frame, and the host's own state (login screen vs game).\n\nWhere the engine can be identified, its own numbers come too:\n\n| Engine   | How it is found                                                                 | What you get                                                                                                      |\n| -------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| three.js | `__THREE_DEVTOOLS__` — three announces itself                                   | renderer info (draw calls, triangles, textures), scene object/mesh/light counts, camera position + look direction |\n| PixiJS 8 | `__PIXI_APP_INIT__` / `__PIXI_RENDERER_INIT__` — Pixi announces itself          | stage display objects, hidden count, tree depth, ticker fps, renderer backend and resolution                      |\n| Phaser   | looked up in the page globals — Phaser has no such channel in its release build | scenes with active/visible flags, per-scene object counts, main camera scroll and zoom, loop fps                  |\n\n**Phaser needs one line from you.** Phaser assigns `window.PHASER_GAME` itself, but only in its\ndebug build — the release build shipped by npm has that branch stripped, so a Phaser game is\ninvisible to any observer until it hands itself over. Verified live: without the line the preview\nreports no engine at all; with it, scenes, object counts, camera and loop fps all come through.\n\n```ts\nthis.game = new Phaser.Game({/* … */});\n// Makes the game observable in the live preview, which reads this exact global.\n(globalThis as unknown as Record<string, unknown>).PHASER_GAME = this.game;\n```\n\nDelete it again in `destroy()` (`if (globals.PHASER_GAME === this.game) delete globals.PHASER_GAME`)\n— the Mode Router destroys a suspended mode, and a stale reference would show a game that no longer\nexists. `modules/idle-rpg` does exactly this; copy it.\n\nNote that the engine layer never replaces the surface below: it reports _scenes and objects_, never\n_what the game means_ — which hero is selected, what the score is, whose turn it is.\n\nThat layer answers \"does it render at all\" — a dead loop, a blank one-colour frame, a player stuck\non the login screen. It cannot answer anything about _gameplay_: where the player is, what the score\nis, why the character fell through the floor. That is what the surface below is for, and why a\ncanvas module is not finished without it.\n\nThe same goes for driving the game. `SendInput` dispatches synthetic keys/clicks and works for\ngames that read plain DOM events, but an engine that gates input on Pointer Lock ignores it —\nPointer Lock is unavailable inside the preview's cross-origin iframe. **Do not gate controls on\nPointer Lock**: support a soft-lock fallback (click the canvas to take control, Escape to release,\nclamp mouse deltas), or the preview is unplayable for the human too. Actions published here always\nwork, because they go through the module's own input path.\n\n## Adding the surface\n\n```ts\nsetup(ctx) {\n  const { scene, agent } = createMyGame();\n  ctx.registerScene(scene);\n  ctx.exposeToAgent(agent);\n}\n```\n\n```ts\nimport type { ModuleAgentApi } from \"@idosgames/module-sdk\";\n\nexport function createMyGameAgentApi(\n  getGame: () => Game | null,\n): ModuleAgentApi {\n  return {\n    state() {\n      const game = getGame();\n      if (!game) return { mounted: false };\n      return {\n        mounted: true,\n        playing: game.running, // на паузе персонаж не двигается — это не баг\n        player: { pos: game.player.pos, health: game.player.health },\n        world: { loadedChunks: game.world.chunks.size },\n      };\n    },\n    actions: {\n      move: async (args) => hold(dirKey(args?.dir), clampMs(args?.ms)),\n      jump: async () => hold(\"Space\", 120),\n    },\n    describeActions: {\n      move: \"Walk: { dir: forward|back|left|right, ms?: number }.\",\n      jump: \"Jump.\",\n    },\n  };\n}\n```\n\nPass a **getter**, not the game object: the scene creates the game in `mount()` and drops it in\n`destroy()`, while the surface is registered once in `setup()`.\n\n## Rules that matter\n\n1. **Actions go through the module's real input path** — intents, command queue, the same key set\n   the player's keyboard fills. A second movement implementation drifts from the real one, and then\n   the agent verifies a game nobody plays.\n2. **`state()` must be cheap, JSON-serializable and free of secrets.** It is called per request and\n   pasted verbatim into an LLM prompt.\n3. **Bound every action.** Clamp durations (a few seconds at most) so the agent cannot \"hold W\" for\n   a minute; reject unknown argument values with a clear error naming the valid ones.\n4. **Nothing destructive.** Deleting a save, spending real currency or resetting progress does not\n   belong here — this surface exists to observe and reproduce, not to administer.\n5. **`describeActions` is the only documentation the agent gets.** One line per action: what it does\n   and which arguments it takes, with units.\n6. **Include the \"am I even running\" flags** (`mounted`, `playing`). Most \"the character does not\n   move\" reports are a paused game, and without those flags the agent goes looking for a physics bug.\n\n## When the module's UI is DOM\n\nA module whose interface is React/DOM (panels, HUD, buttons) needs only a thin surface — the agent\nalready reads that tree and clicks it like a human. Expose what the canvas hides (scene state) and\nleave `actions` empty rather than mirroring buttons the agent can already press.\n\n## Verifying it works\n\nIn the preview, ask the agent something it can only answer by looking: \"where is the player right\nnow?\", \"walk forward for a second and tell me if the position changed\", \"jump and check that the\nplayer lands\". If `GetGameState` answers with the automatic layer but an empty `exposedByGame`, the\nsurface is not wired — check that `exposeToAgent` runs inside `setup()` and that the host is\n`@idosgames/app-shell` (the bridge publishes the registry).\n",
+  "references": []
+}

package/registry/skills/idosgames-getting-started.json

@@ -1,6 +1,6 @@
 {
   "name": "idosgames-getting-started",
   "description": "Start a new game or app on the iDosGames composable-module architecture: scaffold the host shell and plug in feature modules (board-game, idle-rpg, voxelcraft, …). Use this whenever a developer wants to CREATE an iDosGames project from scratch, add an iDosGames game module to a project, or asks how @idosgames/app-shell, @idosgames/module-sdk, the host shell, mountHost, or src/modules.ts fit together. Pairs with idosgames-module-contract (writing a module) and idosgames-compose-modules (merging several). If pulling modules over MCP, use the @idosgames/mcp tools get_host_scaffold / get_module / get_manifest.",
-  "content": "---\nname: idosgames-getting-started\ndescription: >-\n  Start a new game or app on the iDosGames composable-module architecture: scaffold the host shell\n  and plug in feature modules (board-game, idle-rpg, voxelcraft, …). Use this whenever\n  a developer wants to CREATE an iDosGames project from scratch, add an iDosGames game module to a\n  project, or asks how @idosgames/app-shell, @idosgames/module-sdk, the host shell, mountHost, or\n  src/modules.ts fit together. Pairs with idosgames-module-contract (writing a module) and\n  idosgames-compose-modules (merging several). If pulling modules over MCP, use the @idosgames/mcp\n  tools get_host_scaffold / get_module / get_manifest.\n---\n\n# Getting started (iDosGames composable modules)\n\nAn iDosGames project is **one host shell + N feature modules**. The host owns everything that exists\nonce — the SDK client, login, the React root, the screen, a module registry, and a Mode Router that\nswitches between modules. A module is a library (a game or app) that plugs into the host; it never\ncreates the client, logs in, or owns the root.\n\n## Runtime packages (npm)\n\n- `@idosgames/core` — the SDK client (`createIDosGamesClient`): auth, currency, store, characters,\n  blockchain, ~28 services. See the per-service skills (currency-system, store-system, …).\n- `@idosgames/module-sdk` — the module contract types (`Module`, `ModuleContext`, `EngineScene`,\n  `UiPanel`). See idosgames-module-contract.\n- `@idosgames/react` — shared React glue (`IDosGamesProvider`, `useIDosGamesClient`, `useUserState`,\n  `StatusProvider`, `createControllerContext`).\n- `@idosgames/app-shell` — the host runtime (`mountHost`, the Mode Router, the module registry).\n- `@idosgames/wallet` — optional wallet bridge (EVM/Solana) for on-chain deposits/withdrawals.\n\nInstall the exact versions from `get_manifest` (MCP) or the registry `index.json` `runtimePackages`.\n\n## Project shape\n\n```\nindex.html                 # mounts #app\nsrc/main.tsx               # creates ONE client and calls mountHost({container, client, modules})\nsrc/modules.ts             # the registry: export const modules: Module[] = [ … ]\nsrc/modules/{id}/          # each module's source (from get_module)\n```\n\n`src/main.tsx` (host-owned) is the only place that creates the client — but it does **not** sign in.\n`mountHost` owns sign-in: it replays a previous session (`autoLogin`) and renders the login screen\nwhen there is nothing to replay. Calling a `login*` method here skips that screen for good, taking\n\"switch account\" and wallet sign-in with it:\n\n```ts\nconst client = createIDosGamesClient({ titleID, buildKey, throttleMs: 0 });\n// Do NOT log in here — the host does it.\nmountHost({\n  container: app,\n  client,\n  modules, // from ./modules\n  renderLogin, // optional: your own screen; omitted = a plain guest-only default\n});\n```\n\nWhether a returning player is signed back in silently is the login screen's business, not the\nhost's: it calls `client.auth.setRememberSession(remember)` before a `login*` method. See the\nauthentication skill.\n\n`src/modules.ts` registers what the project composes:\n\n```ts\nimport type { Module } from \"@idosgames/module-sdk\";\nimport { boardGameModule } from \"./modules/board-game\";\nexport const modules: Module[] = [boardGameModule];\n```\n\n## Steps to scaffold\n\n1. **Host** — write the host scaffold to the project root (`get_host_scaffold`, or copy\n   `templates/host-starter`). Its `src/modules.ts` starts empty → the host shows a \"no modules\" state.\n2. **Bind the Title** — open `src/idos.title.ts` and set `IDOS_TITLE_ID` to the game's canonical\n   Title id (and `IDOS_BUILD_KEY` if the title enforces one). This file is the project's single\n   centralized identity — it is the highest-priority source and the only channel a packaged mobile\n   build, iframe embed, or shared link has. On platform-created projects the platform generates it;\n   on a manually scaffolded project **you fill it yourself**. Do NOT bind the title via `.env.local`\n   (`VITE_IDOS_TITLE_ID`) — that is a local-dev fallback for the raw template only, and it does not\n   travel with the code.\n3. **Pick modules** — `list_modules` / `search`, then `get_module {id}` for each. Write its files\n   into `src/modules/{id}/`.\n4. **Register** — for each module add `import { {camelCase(id)}Module } from \"./modules/{id}\"` and\n   push it into the `modules` array (e.g. `board-game` → `boardGameModule`).\n5. **Install deps** — the union of `runtimePackages` + each module's `dependencies`. Modules bring\n   their own engine (three, phaser); the host brings react/react-dom/app-shell.\n6. **Run** — the host renders a nav-bar when ≥2 modules register a route, and mode-switches between\n   them; a shared HUD panel (`activeOnly:false`) stays visible across all modes.\n\nTo combine multiple genres into one game, see **idosgames-compose-modules**. To write or edit a\nmodule, see **idosgames-module-contract**.\n\n## Two MCP surfaces: game CODE vs. a Title's live DATA\n\nThe platform exposes **two independent MCP servers** — don't confuse them:\n\n- **`@idosgames/mcp`** (this one) serves the **CODE registry**. Use it to WRITE a game's source:\n  `get_host_scaffold`, `list_modules` / `search` / `get_module`, `get_manifest`, `list_skills` /\n  `get_skill`. Transport: stdio (`npx -y @idosgames/mcp`). Its registry is bundled offline; to use the\n  hosted copy set `IDOSGAMES_REGISTRY_URL=https://cloud.idosgames.com/drive/registry/latest` — a **base**\n  the loader appends `/index.json`, `/modules/{id}.json`, etc. to (the base itself is not fetchable on\n  R2; open `.../latest/index.json` to browse the catalog). Read-only, no auth. It never reads or changes\n  a live Title's data.\n- **The Title-configuration MCP** (a separate backend server) owns a **live Title's DATA**. Use it to\n  read/write the Title's `TitlePublicConfiguration` (`get_<field>` / `save_<field>`, or the whole\n  model) and to generate assets (`generate_image` / `generate_audio` / `generate_text` /\n  `generate_three_d` / `generate_video`). Transport: HTTP JSON-RPC at\n  `POST https://site.idosgames.com/api/v2/mcp`, authenticated with an `X-MCP-API-Key` header (the\n  publisher issues the key per Title on platform.idosgames.com); every tool call takes a `title_id`\n  argument. Connect it as an HTTP MCP server — and keep the key out of committed config via env\n  expansion:\n\n  ```json\n  {\n    \"mcpServers\": {\n      \"idosgames-title\": {\n        \"type\": \"http\",\n        \"url\": \"https://site.idosgames.com/api/v2/mcp\",\n        \"headers\": { \"X-MCP-API-Key\": \"${IDOS_MCP_API_KEY}\" }\n      }\n    }\n  }\n  ```\n\n  Configuring a **fresh (empty) Title** so a game can actually run against it (currencies → game\n  loop → bots) is its own checklist: see **idosgames-title-bootstrap**.\n\nRule of thumb: **game CODE → `@idosgames/mcp`; a Title's live config DATA and generated ASSETS → the\nbackend `v2/mcp` server.** Scaffolding a project and configuring/populating the Title it runs as are\ntwo different jobs on two different servers — connect the one that matches the task (or both).\n",
+  "content": "---\nname: idosgames-getting-started\ndescription: >-\n  Start a new game or app on the iDosGames composable-module architecture: scaffold the host shell\n  and plug in feature modules (board-game, idle-rpg, voxelcraft, …). Use this whenever\n  a developer wants to CREATE an iDosGames project from scratch, add an iDosGames game module to a\n  project, or asks how @idosgames/app-shell, @idosgames/module-sdk, the host shell, mountHost, or\n  src/modules.ts fit together. Pairs with idosgames-module-contract (writing a module) and\n  idosgames-compose-modules (merging several). If pulling modules over MCP, use the @idosgames/mcp\n  tools get_host_scaffold / get_module / get_manifest.\n---\n\n# Getting started (iDosGames composable modules)\n\nAn iDosGames project is **one host shell + N feature modules**. The host owns everything that exists\nonce — the SDK client, login, the React root, the screen, a module registry, and a Mode Router that\nswitches between modules. A module is a library (a game or app) that plugs into the host; it never\ncreates the client, logs in, or owns the root.\n\n## Runtime packages (npm)\n\n- `@idosgames/core` — the SDK client (`createIDosGamesClient`): auth, currency, store, characters,\n  blockchain, ~28 services. See the per-service skills (currency-system, store-system, …).\n- `@idosgames/module-sdk` — the module contract types (`Module`, `ModuleContext`, `EngineScene`,\n  `UiPanel`). See idosgames-module-contract.\n- `@idosgames/react` — shared React glue (`IDosGamesProvider`, `useIDosGamesClient`, `useUserState`,\n  `StatusProvider`, `createControllerContext`).\n- `@idosgames/app-shell` — the host runtime (`mountHost`, the Mode Router, the module registry).\n- `@idosgames/wallet` — optional wallet bridge (EVM/Solana) for on-chain deposits/withdrawals.\n\nInstall the exact versions from `get_manifest` (MCP) or the registry `index.json` `runtimePackages`.\n\n## Project shape\n\n```\nindex.html                 # mounts #app\nsrc/main.tsx               # creates ONE client and calls mountHost({container, client, modules})\nsrc/modules.ts             # the registry: export const modules: Module[] = [ … ]\nsrc/modules/{id}/          # each module's source (from get_module)\n```\n\n`src/main.tsx` (host-owned) is the only place that creates the client — but it does **not** sign in.\n`mountHost` owns sign-in: it replays a previous session (`autoLogin`) and renders the login screen\nwhen there is nothing to replay. Calling a `login*` method here skips that screen for good, taking\n\"switch account\" and wallet sign-in with it:\n\n```ts\nconst client = createIDosGamesClient({ titleID, buildKey, throttleMs: 0 });\n// Do NOT log in here — the host does it.\nmountHost({\n  container: app,\n  client,\n  modules, // from ./modules\n  renderLogin, // optional: your own screen; omitted = a plain guest-only default\n});\n```\n\nWhether a returning player is signed back in silently is the login screen's business, not the\nhost's: it calls `client.auth.setRememberSession(remember)` before a `login*` method. See the\nauthentication skill.\n\n`src/modules.ts` registers what the project composes:\n\n```ts\nimport type { Module } from \"@idosgames/module-sdk\";\nimport { boardGameModule } from \"./modules/board-game\";\nexport const modules: Module[] = [boardGameModule];\n```\n\n## Steps to scaffold\n\n1. **Host** — write the host scaffold to the project root (`get_host_scaffold`, or copy\n   `templates/host-starter`). Its `src/modules.ts` starts empty → the host shows a \"no modules\" state.\n2. **Bind the Title** — open `src/idos.title.ts` and set `IDOS_TITLE_ID` to the game's canonical\n   Title id (and `IDOS_BUILD_KEY` if the title enforces one). This file is the project's single\n   centralized identity — it is the highest-priority source and the only channel a packaged mobile\n   build, iframe embed, or shared link has. On platform-created projects the platform generates it;\n   on a manually scaffolded project **you fill it yourself**. Do NOT bind the title via `.env.local`\n   (`VITE_IDOS_TITLE_ID`) — that is a local-dev fallback for the raw template only, and it does not\n   travel with the code.\n3. **Pick modules** — `list_modules` / `search`, then `get_module {id}` for each. Write its files\n   into `src/modules/{id}/`.\n4. **Register** — for each module add `import { {camelCase(id)}Module } from \"./modules/{id}\"` and\n   push it into the `modules` array (e.g. `board-game` → `boardGameModule`).\n5. **Install deps** — the union of `runtimePackages` + each module's `dependencies`. Modules bring\n   their own engine (three, phaser); the host brings react/react-dom/app-shell.\n6. **Run** — the host renders a nav-bar when ≥2 modules register a route, and mode-switches between\n   them; a shared HUD panel (`activeOnly:false`) stays visible across all modes.\n\nTo combine multiple genres into one game, see **idosgames-compose-modules**. To write or edit a\nmodule, see **idosgames-module-contract**.\n\n## Where state lives (decide this before writing the first save)\n\nThe project is client-side code in the player's browser. `localStorage`, module fields, and React\nstate are **not storage** — nothing there survives a device change, and nothing there is trusted.\n\n1. **A dedicated module owns it?** Use that module. Currencies, inventory, quests, characters,\n   leaderboards, store purchases each have a service that enforces the rules server-side.\n2. **Otherwise, per-player data → `client.userCustomData`** — buckets `Private`/`Public` are\n   client-writable (settings, cosmetics), `ReadOnly`/`Internal` are server-only. Anything a player\n   could cheat by editing goes in the server-only buckets. See **user-custom-data**.\n3. **Shared by all players → `client.titleCustomData`** (event state, global counters, server\n   thresholds, feature toggles). Read-only for clients. See **title-custom-data**.\n4. **Writing any of the server-only data, or any rule the player must not be able to fake** →\n   a CloudCode handler, called with `client.cloudCode.execute(...)`. See **cloud-code**.\n\n## Two MCP surfaces: game CODE vs. a Title's live DATA\n\nThe platform exposes **two independent MCP servers** — don't confuse them:\n\n- **`@idosgames/mcp`** (this one) serves the **CODE registry**. Use it to WRITE a game's source:\n  `get_host_scaffold`, `list_modules` / `search` / `get_module`, `get_manifest`, `list_skills` /\n  `get_skill`. Transport: stdio (`npx -y @idosgames/mcp`). Its registry is bundled offline; to use the\n  hosted copy set `IDOSGAMES_REGISTRY_URL=https://cloud.idosgames.com/drive/registry/latest` — a **base**\n  the loader appends `/index.json`, `/modules/{id}.json`, etc. to (the base itself is not fetchable on\n  R2; open `.../latest/index.json` to browse the catalog). Read-only, no auth. It never reads or changes\n  a live Title's data.\n- **The Title-configuration MCP** (a separate backend server) owns a **live Title's DATA**. Use it to\n  read/write the Title's `TitlePublicConfiguration` (`get_<field>` / `save_<field>`, or the whole\n  model) and to generate assets (`generate_image` / `generate_audio` / `generate_text` /\n  `generate_three_d` / `generate_video`). Transport: HTTP JSON-RPC at\n  `POST https://site.idosgames.com/api/v2/mcp`, authenticated with an `X-MCP-API-Key` header (the\n  publisher issues the key per Title on platform.idosgames.com); every tool call takes a `title_id`\n  argument. Connect it as an HTTP MCP server — and keep the key out of committed config via env\n  expansion:\n\n  ```json\n  {\n    \"mcpServers\": {\n      \"idosgames-title\": {\n        \"type\": \"http\",\n        \"url\": \"https://site.idosgames.com/api/v2/mcp\",\n        \"headers\": { \"X-MCP-API-Key\": \"${IDOS_MCP_API_KEY}\" }\n      }\n    }\n  }\n  ```\n\n  Configuring a **fresh (empty) Title** so a game can actually run against it (currencies → game\n  loop → bots) is its own checklist: see **idosgames-title-bootstrap**.\n\nRule of thumb: **game CODE → `@idosgames/mcp`; a Title's live config DATA and generated ASSETS → the\nbackend `v2/mcp` server.** Scaffolding a project and configuring/populating the Title it runs as are\ntwo different jobs on two different servers — connect the one that matches the task (or both).\n",
   "references": []
 }

package/registry/skills/idosgames-module-contract.json

@@ -1,6 +1,6 @@
 {
   "name": "idosgames-module-contract",
   "description": "Write or modify an iDosGames feature module against the module contract in @idosgames/module-sdk: the Module manifest, ModuleContext, EngineScene (Three/Phaser/vanilla), UiPanel (React), route registration, and the shared controller-box bridge between an imperative scene and React panels. Use this whenever a developer authors a NEW module, edits an existing one (board-game, idle-rpg, voxelcraft), or asks about defineModule, registerScene/registerPanel/registerRoute, activate/suspend, SceneMountContext, or the {camelCase(id)}Module export convention.",
-  "content": "---\nname: idosgames-module-contract\ndescription: >-\n  Write or modify an iDosGames feature module against the module contract in @idosgames/module-sdk:\n  the Module manifest, ModuleContext, EngineScene (Three/Phaser/vanilla), UiPanel (React), route\n  registration, and the shared controller-box bridge between an imperative scene and React panels.\n  Use this whenever a developer authors a NEW module, edits an existing one (board-game, idle-rpg,\n  voxelcraft), or asks about defineModule, registerScene/registerPanel/registerRoute,\n  activate/suspend, SceneMountContext, or the {camelCase(id)}Module export convention.\n---\n\n# The module contract (@idosgames/module-sdk)\n\nA module is a manifest the host installs once. It exports `{camelCase(id)}Module` from its\n`index.ts` (e.g. `board-game` → `boardGameModule`, `idle-rpg` → `idleRpgModule`) — the host seeder\nderives the import name from the id, so this convention is required.\n\n```ts\nimport { defineModule } from \"@idosgames/module-sdk\";\n\nexport const boardGameModule = defineModule({\n  id: \"board-game\",\n  meta: { name: \"Board Game\", type: \"game\", genre: \"board\", engine: \"three\" }, // engine: three|phaser|dom\n  setup(ctx) {\n    // ctx.client (shared, authed) · ctx.events (cross-module bus) · ctx.surface\n    ctx.registerScene(createScene(box)); // rendered engine scene (optional)\n    ctx.registerPanel({ id: \"root\", slot: \"overlay\", component: RootPanel }); // React UI (optional)\n    ctx.registerRoute({ id: \"board-game\", label: \"Board\", icon: \"🎲\" }); // nav/mode entry\n  },\n});\n```\n\n`meta.type` is `game | app | ai-app`; `meta.engine` is `three | phaser | dom` (`dom` = no renderer —\na pure React/DOM app module). `setup` is called ONCE with `ctx: ModuleContext`.\n\n## EngineScene (the rendered part)\n\nA scene mounts into a bare `HTMLElement` (framework-free — this is why a vanilla Three game like\nvoxelcraft fits). The host's Mode Router drives it; only the active mode runs.\n\n```ts\nconst scene: EngineScene = {\n  surface: \"fullbleed-canvas\",\n  mount(ctx: SceneMountContext) {\n    controller = new Controller(ctx.host);\n    box.set(controller);\n  },\n  activate() {\n    controller?.setRunning(true);\n  }, // became the active mode → resume RAF\n  suspend() {\n    controller?.setRunning(false);\n  }, // hidden → stop RAF (invariant: only active ticks)\n  destroy() {\n    controller?.destroy();\n  }, // permanent teardown\n};\n```\n\n`mount` takes a context object (not a bare element) so it can grow — e.g. a host-shared renderer in\nthe composition era — without breaking the contract. A scene MUST stop its RAF on `suspend`.\n\n## UiPanel (the React part)\n\nPanels are React components the host renders inside its provider stack (client + status already\nprovided). Use `@idosgames/react` hooks (`useIDosGamesClient`, `useUserState`) — do NOT re-create\nproviders.\n\n- `slot`: `hud | sidebar | overlay | modal`.\n- `activeOnly` (default true): show only while this module's mode is active. Set `false` for shared\n  chrome that stays across every mode (e.g. a persistent HUD).\n\n## Bridging scene ↔ panel\n\nThe scene creates its controller at `mount` (needs the canvas), but panels render before that. Share\nit with a one-slot observable and read it with `useSyncExternalStore`:\n\n```ts\nexport function createControllerBox<T>() {\n  /* get/set/subscribe */\n}\n// panel: const controller = useSyncExternalStore(box.subscribe, box.get); if (!controller) return <Loading/>;\n```\n\nFor the module's controller React context use the shared factory instead of hand-writing it:\n\n```ts\nexport const [BoardControllerProvider, useBoardController] =\n  createControllerContext<BoardController>(\"BoardController\"); // from @idosgames/react\n```\n\n## Dependencies\n\nDeclare only the module's UNIQUE deps (e.g. `phaser` for idle-rpg, `three` for board/voxel) plus the\nshared baseline (react, @idosgames/*). The platform pins shared libs identically across modules; two\nmodules must not request different versions of one package (the build allowlist rejects it).\n\nStudy a real module via `get_module {id}` (MCP) before writing a new one.\n",
+  "content": "---\nname: idosgames-module-contract\ndescription: >-\n  Write or modify an iDosGames feature module against the module contract in @idosgames/module-sdk:\n  the Module manifest, ModuleContext, EngineScene (Three/Phaser/vanilla), UiPanel (React), route\n  registration, and the shared controller-box bridge between an imperative scene and React panels.\n  Use this whenever a developer authors a NEW module, edits an existing one (board-game, idle-rpg,\n  voxelcraft), or asks about defineModule, registerScene/registerPanel/registerRoute,\n  activate/suspend, SceneMountContext, or the {camelCase(id)}Module export convention.\n---\n\n# The module contract (@idosgames/module-sdk)\n\nA module is a manifest the host installs once. It exports `{camelCase(id)}Module` from its\n`index.ts` (e.g. `board-game` → `boardGameModule`, `idle-rpg` → `idleRpgModule`) — the host seeder\nderives the import name from the id, so this convention is required.\n\n```ts\nimport { defineModule } from \"@idosgames/module-sdk\";\n\nexport const boardGameModule = defineModule({\n  id: \"board-game\",\n  meta: { name: \"Board Game\", type: \"game\", genre: \"board\", engine: \"three\" }, // engine: three|phaser|dom\n  setup(ctx) {\n    // ctx.client (shared, authed) · ctx.events (cross-module bus) · ctx.surface\n    ctx.registerScene(createScene(box)); // rendered engine scene (optional)\n    ctx.registerPanel({ id: \"root\", slot: \"overlay\", component: RootPanel }); // React UI (optional)\n    ctx.registerRoute({ id: \"board-game\", label: \"Board\", icon: \"🎲\" }); // nav/mode entry\n  },\n});\n```\n\n`meta.type` is `game | app | ai-app`; `meta.engine` is `three | phaser | dom` (`dom` = no renderer —\na pure React/DOM app module). `setup` is called ONCE with `ctx: ModuleContext`.\n\n## EngineScene (the rendered part)\n\nA scene mounts into a bare `HTMLElement` (framework-free — this is why a vanilla Three game like\nvoxelcraft fits). The host's Mode Router drives it; only the active mode runs.\n\n```ts\nconst scene: EngineScene = {\n  surface: \"fullbleed-canvas\",\n  mount(ctx: SceneMountContext) {\n    controller = new Controller(ctx.host);\n    box.set(controller);\n  },\n  activate() {\n    controller?.setRunning(true);\n  }, // became the active mode → resume RAF\n  suspend() {\n    controller?.setRunning(false);\n  }, // hidden → stop RAF (invariant: only active ticks)\n  destroy() {\n    controller?.destroy();\n  }, // permanent teardown\n};\n```\n\n`mount` takes a context object (not a bare element) so it can grow — e.g. a host-shared renderer in\nthe composition era — without breaking the contract. A scene MUST stop its RAF on `suspend`.\n\nA module that registers a scene MUST also publish its debug surface — `ctx.exposeToAgent({ state,\nactions, describeActions })` — and must NOT gate controls on Pointer Lock (unavailable in the\npreview's cross-origin iframe). Nothing inside a `<canvas>` is observable from the DOM, so without\nthe surface neither the AI Coder nor a human reviewer can tell what the game is doing. See the\n`idosgames-agent-debug-surface` skill.\n\n## UiPanel (the React part)\n\nPanels are React components the host renders inside its provider stack (client + status already\nprovided). Use `@idosgames/react` hooks (`useIDosGamesClient`, `useUserState`) — do NOT re-create\nproviders.\n\n- `slot`: `hud | sidebar | overlay | modal`.\n- `activeOnly` (default true): show only while this module's mode is active. Set `false` for shared\n  chrome that stays across every mode (e.g. a persistent HUD).\n\n## Bridging scene ↔ panel\n\nThe scene creates its controller at `mount` (needs the canvas), but panels render before that. Share\nit with a one-slot observable and read it with `useSyncExternalStore`:\n\n```ts\nexport function createControllerBox<T>() {\n  /* get/set/subscribe */\n}\n// panel: const controller = useSyncExternalStore(box.subscribe, box.get); if (!controller) return <Loading/>;\n```\n\nFor the module's controller React context use the shared factory instead of hand-writing it:\n\n```ts\nexport const [BoardControllerProvider, useBoardController] =\n  createControllerContext<BoardController>(\"BoardController\"); // from @idosgames/react\n```\n\n## Dependencies\n\nDeclare only the module's UNIQUE deps (e.g. `phaser` for idle-rpg, `three` for board/voxel) plus the\nshared baseline (react, @idosgames/*). The platform pins shared libs identically across modules; two\nmodules must not request different versions of one package (the build allowlist rejects it).\n\nStudy a real module via `get_module {id}` (MCP) before writing a new one.\n",
   "references": []
 }

package/registry/skills/quest-system.json

@@ -1,11 +1,11 @@
 {
   "name": "quest-system",
   "description": "Build a quest / daily-task system in a game on the iDosGames TypeScript SDK (@idosgames/core) via client.quest (QuestService): load quest and cycle definitions, load the player's quest progress state, add progress toward a metric, claim a completed quest's reward, claim a points-track milestone reward, claim a group-completion (grand) reward, and refresh cycles (dailies/ weeklies) forward. Use this whenever the user is working in the iDosGames TS SDK or its game templates (board-game, idle-rpg) and wants daily/weekly quest screens, task lists, objective/progress trackers, battle-pass-style points tracks, milestone reward ladders, quest-group completion bonuses, or otherwise touches client.quest, QuestService, QuestDefinitions, UserQuestState, QuestPointsTrackView, or MilestoneDefinition — even if they don't name the module explicitly.",
-  "content": "---\nname: quest-system\ndescription: >-\n  Build a quest / daily-task system in a game on the iDosGames TypeScript SDK\n  (@idosgames/core) via client.quest (QuestService): load quest and cycle\n  definitions, load the player's quest progress state, add progress toward a\n  metric, claim a completed quest's reward, claim a points-track milestone\n  reward, claim a group-completion (grand) reward, and refresh cycles (dailies/\n  weeklies) forward. Use this whenever the user is working in the iDosGames TS\n  SDK or its game templates (board-game, idle-rpg) and wants daily/weekly quest\n  screens, task lists, objective/progress trackers, battle-pass-style points\n  tracks, milestone reward ladders, quest-group completion bonuses, or\n  otherwise touches client.quest, QuestService, QuestDefinitions,\n  UserQuestState, QuestPointsTrackView, or MilestoneDefinition — even if they\n  don't name the module explicitly.\n---\n\n# Quest system (iDosGames TS SDK)\n\nThe Quest module runs a title's task/quest board: dailies, weeklies, permanent\nquests, and one-off event quests, each made of objectives that accrue progress\ntoward a metric. Everything is **server-authoritative**: the backend tracks\nprogress, decides when a quest is `Completed`, and validates every claim. The\nclient asks the backend to report progress or claim a reward, and the SDK\nmirrors the confirmed result into a local cache your UI reads. You never\ncompute quest status yourself — you call a method, check the result, and\nrender from the cache.\n\nThis skill is for **using** the production `QuestService`, not for porting or\nextending it. If a call is rejected, that's the backend enforcing a rule\n(objective not met, already claimed, prerequisite quest incomplete) — surface\nthe error, don't try to reproduce the check client-side.\n\n## The two data shapes\n\nKeep these straight; every recipe below is just moving between them.\n\n1. **Definitions** (config, same for every player) — the title's catalog of\n   quest cycles (dailies/weeklies/permanent), the quests inside each cycle,\n   their objectives/rewards/prerequisites, and the cycle's milestone points\n   track and group-completion grand rewards. Fetched with\n   `getQuestDefinitions()`.\n2. **User quest state** (state, per player) — this player's live progress:\n   which cycle instances are active, each quest's `Status` and per-objective\n   `CurrentValue`, and the points-track balance/claimed-milestone ids for each\n   cycle. Fetched with `getUserQuestState()`.\n\nA quest lives either **inside a cycle** (`CycleID` set — dailies, weeklies,\nseasonal) or as a **permanent quest** (no `CycleID` — a one-time or\nalways-available quest, e.g. onboarding). Most methods take an optional/blank\n`CycleID` to address either; the cache keeps them in separate buckets\n(`Quest.Cycles[cycleID]` vs `Quest.PermanentQuests`).\n\nThree distinct reward mechanisms — don't conflate them:\n\n- **Quest reward** — the `Reward` on one `QuestDefinition`, claimed once that\n  quest's objectives are all met (`Status: \"Completed\"`), via\n  `claimQuestReward`. Moves the quest to `\"Claimed\"`.\n- **Milestone reward** — a rung on a cycle's **points track** (backend/config\n  comments call this \"Achievements\"): claiming a quest with `PointsReward > 0`\n  also grants that many points into a per-cycle point balance — a dedicated\n  `EventTokenType.Quest` token, tracked separately from any single quest's own\n  claim status — in the same atomic transaction as the quest claim. Each\n  `MilestoneDefinition` in `Cycle.Milestones` pays out once that balance's\n  lifetime total crosses its `RequiredProgress`. Claimed via\n  `claimMilestoneReward`. This is the battle-pass-style ladder — a player can\n  hit a milestone from points earned across many different quest claims, and\n  milestone eligibility never re-checks any individual quest's status.\n- **Group-completion reward** — a grand bonus in `Cycle.GroupCompletions` that\n  pays out once at least `RequiredCompletedQuests` quests sharing a `GroupID`\n  have reached `\"Completed\"` (not necessarily claimed). Claimed via\n  `claimGroupCompletionReward`.\n\nAll three can be in flight simultaneously for the same cycle — completing one\nquest can push its points into the milestone track, count toward its group's\ncompletion total, _and_ be individually claimable, all at once.\n\n**Progress** is reported with `addQuestProgress(metricID, progressValue)` — a\ngeneric counter keyed by `MetricID`, not by quest id. The backend fans one\nmetric update out to every objective across every active quest that listens to\nthat `MetricID` (per each objective's own `AggregationMethod`/filters), and\nreturns the list of quests/objectives that changed. You call this from your\ngame-loop code wherever the underlying action happens (e.g. \"enemy defeated\" →\n`addQuestProgress(\"EnemiesDefeated\", 1)`), not once per quest.\n\n**Cycles** (dailies/weeklies) roll forward on a schedule. `getUserQuestState`\ndefaults to auto-refreshing stale cycles for you (`autoRefreshCycles = true`);\ncall `refreshQuestCycles()` directly when you want to force-check for a new\ncycle boundary (e.g. app resumed from background) without re-fetching the\nwhole state.\n\nFor the full field-by-field shape of Definitions and state (objective sources,\nprerequisite modes, schedule/limit/gate blocks, the points-track/milestone\nplumbing), read [references/data-model.md](references/data-model.md). You do\n**not** need it to call the methods — only to drive richer UI off the config.\n\n## Setup\n\n```ts\nimport { createIDosGamesClient } from \"@idosgames/core\";\n\nconst client = createIDosGamesClient({ titleID: \"your-title-id\" });\nawait client.auth.loginWithDeviceID(); // or any auth.* method\n\nconst quest = client.quest; // the QuestService\n```\n\nEvery quest method requires an authenticated session. Without one they return\n`{ ok: false, reason: \"unauthorized\" }` — they do not throw. There is one\n`client` per player; don't share it across sessions.\n\n## Methods\n\nAll methods return `Promise<OperationResult<T>>`: a discriminated union that is\neither `{ ok: true, data }` or `{ ok: false, reason, error }`. Always branch on\n`result.ok` before touching `result.data`. `reason` is one of `\"client\"` (bad\nlocal args), `\"unauthorized\"`, `\"throttled\"` (fired the same endpoint again\ninside the throttle window), `\"connection\"` (transient, offer Retry),\n`\"validation\"` (response/schema drift), or `\"server\"` (backend rejected it —\n`error` carries the human-readable reason, e.g. \"Quest is not completed\",\n\"Already claimed\", \"Prerequisite quest not completed\").\n\n| Method                                                   | Purpose                                                              | `data` on success                                                          |\n| -------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------- |\n| `getQuestDefinitions()`                                  | Load the title's quest/cycle catalog (config).                       | `QuestDefinitions`                                                         |\n| `getUserQuestState(autoRefreshCycles?)`                  | Load this player's quest progress (state). Defaults to auto-refresh. | `GetUserQuestStateResponse` (`State`, `PointsTracks`)                      |\n| `refreshQuestCycles()`                                   | Force-check cycle boundaries and roll any stale cycle forward.       | `SuccessResponse`                                                          |\n| `addQuestProgress(metricID, progressValue)`              | Report progress on a metric; fans out to every listening objective.  | `AddQuestProgressResponse` (`Updates`)                                     |\n| `claimQuestReward(questID, cycleID?)`                    | Claim a single completed quest's reward.                             | `ClaimQuestRewardResponse` (`NewStatus`, `Resources`)                      |\n| `claimQuestRewardsBatch(quests)`                         | Claim several quests' rewards in one atomic call.                    | `BatchItemResult<ClaimQuestRewardResponse>[]`                              |\n| `claimMilestoneReward(cycleID, milestoneID)`             | Claim one points-track milestone reward for a cycle.                 | `ClaimMilestoneRewardResponse` (`PointsTotalEarned`, `Resources`)          |\n| `claimMilestoneRewardsBatch(milestones)`                 | Claim several milestone rewards in one atomic call.                  | `BatchItemResult<ClaimMilestoneRewardResponse>[]`                          |\n| `claimGroupCompletionReward(cycleID, groupCompletionID)` | Claim a cycle's group-completion grand reward.                       | `ClaimGroupCompletionRewardResponse` (`CompletedGroupQuests`, `Resources`) |\n\n`claimQuestReward` / `claimMilestoneReward` / `claimGroupCompletionReward` all\naccept a blank/absent `CycleID` to mean a permanent quest (quest claim only —\nmilestones and group-completions always belong to a cycle). Each mints its own\n`RelatedEntityID` internally for idempotency; you don't supply one.\n\n`claimQuestRewardsBatch(quests)` takes `QuestClaimRef[]` (`{ CycleID?,\nQuestID? }`, deduped by `CycleID`+`QuestID`); `claimMilestoneRewardsBatch(milestones)`\ntakes `MilestoneClaimRef[]` (`{ CycleID?, MilestoneID? }`, deduped by\n`CycleID`+`MilestoneID`).\n\nOn success, each method also **mirrors the confirmed change into the cache and\nemits an event** — you don't apply anything by hand. Granted resources\n(currencies, items) ride along in `data.Resources` (a `ResourceOperation`, see\n[ResourceModels](../../../packages/core/src/models/_shared/ResourceModels.ts))\nand are already applied to the cached balances, so read updated balances\nstraight from the cache.\n\n## Reading state and reacting to changes\n\nDrive the UI off the cache, not off one-off return values — that way every\nscreen stays consistent no matter which code path changed things.\n\n```ts\n// Quest progress (only present after getUserQuestState()):\nconst cycleA = client.data.user.state?.Quest?.Cycles?.[\"cycleA\"];\ncycleA?.Quests?.[\"q1\"]?.Status; // \"Active\" | \"Completed\" | \"Claimed\" | \"Expired\"\ncycleA?.Quests?.[\"q1\"]?.Objectives?.[\"obj1\"]?.CurrentValue;\ncycleA?.ClaimedGroupCompletionIDs; // string[]\n\nconst permanentQuest =\n  client.data.user.state?.Quest?.PermanentQuests?.[\"intro\"];\n\n// Points track (balance + claimed milestone ids), keyed by cycleID (or\n// \"cycleID:instanceKey\" for recurring cycles) — read with the helper so you\n// don't have to know the exact composite key:\nconst points = client.data.user.getQuestPointsProgress(\"cycleA\");\npoints?.Balance?.Current; // current points balance this cycle\npoints?.Balance?.TotalEarned;\npoints?.Milestone?.ClaimedIDs; // milestone ids already claimed\n\n// Definitions (cached after getQuestDefinitions()):\nimport type { QuestDefinitions } from \"@idosgames/core\";\nconst defs = client.data.config.getSection<QuestDefinitions>(\"Quest\");\n```\n\nSubscribe with `client.on(...)`; each returns an unsubscribe fn:\n\n- `quest:definitionsLoaded` → `QuestDefinitions`\n- `quest:userStateLoaded` → `UserQuestState`\n- `quest:cyclesRefreshed` → `void`\n- `quest:progressAdded` → `AddQuestProgressResponse`\n- `quest:rewardClaimed` → `ClaimQuestRewardResponse`\n- `quest:rewardsClaimedBatch` → `ClaimQuestRewardsBatchResponse`\n- `quest:milestoneClaimed` → `ClaimMilestoneRewardResponse`\n- `quest:milestonesClaimedBatch` → `ClaimMilestoneRewardsBatchResponse`\n- `quest:groupCompletionClaimed` → `ClaimGroupCompletionRewardResponse`\n\nThe coarse `user:questUpdated` (and `user:anyUpdated`) also fire on any quest\ncache write — handy for a \"re-render everything\" hook.\n\n```ts\nconst off = client.on(\"quest:progressAdded\", (r) => {\n  for (const u of r.Updates ?? []) {\n    console.log(`${u.QuestID} objective ${u.ObjectiveID} -> ${u.NewValue}`);\n  }\n});\n// later: off();\n```\n\n## Recipes\n\n### Load the board and render quest cards\n\n```ts\nawait client.quest.getQuestDefinitions();\nawait client.quest.getUserQuestState();\n\nconst defs = client.data.config.getSection<QuestDefinitions>(\"Quest\");\nconst cycles = client.data.user.state?.Quest?.Cycles ?? {};\n\nfor (const [cycleID, cycleDef] of Object.entries(defs?.Cycles ?? {})) {\n  const userCycle = cycles[cycleID];\n  for (const [questID, questDef] of Object.entries(defs?.Quests ?? {})) {\n    if (!questDef.CycleIDs?.includes(cycleID)) continue;\n    const progress = userCycle?.Quests?.[questID];\n    // progress?.Status drives the card state: not-started/Active/Completed/Claimed.\n    // questDef.Objectives + progress?.Objectives drives the progress bar(s).\n  }\n}\n```\n\nA quest's `CycleIDs` lists every cycle it can appear in; cross-reference\nagainst `defs.Cycles` to know which are currently relevant. A quest absent from\n`userCycle.Quests` simply hasn't accrued any progress yet — treat it as\n`\"Active\"` with zero progress, not as an error. The backend creates a quest's\nprogress record (and each objective's) lazily, the first time it accrues\nsomething — it never pre-populates the catalog with zeros.\n\n### Report progress, then claim\n\n```ts\n// Wherever the underlying game action happens:\nconst prog = await client.quest.addQuestProgress(\"EnemiesDefeated\", 1);\nif (!prog.ok) return showError(prog.error);\n\nfor (const u of prog.data.Updates ?? []) {\n  if (u.Status === \"Completed\") {\n    // Surface a \"claim\" button for u.QuestID / u.CycleID now.\n  }\n}\n```\n\n```ts\n// Later, when the player taps Claim:\nconst claim = await client.quest.claimQuestReward(\"q1\", \"cycleA\");\nif (!claim.ok) return showError(claim.error); // e.g. \"Quest is not completed\", \"Already claimed\"\n// cache now shows q1 as \"Claimed\"; balances already credited.\n```\n\nClaiming before every objective is met, or claiming twice, both fail with\n`reason: \"server\"` — the quest must be `\"Completed\"` and not already\n`\"Claimed\"`. There's no client-side shortcut to check this ahead of time beyond\nreading the cached `Status` you already have.\n\nOnly objectives configured with `Source: \"ClientApi\"` can be advanced this way;\nan unrecognized `MetricID` fails with `\"MetricID not allowed for ClientApi\"`.\nNever send an inflated `ProgressValue` \"to be safe\" — if a matching objective\ndeclares `MaxProgressPerCall`, the backend compares your raw value against it\nand **bans the account** on a violation (`\"User banned: Value exceeds\nMaxValuePerCall\"`); it does not just clamp and continue.\n\n### Claim a milestone once the points track crosses a rung\n\n```ts\nconst points = client.data.user.getQuestPointsProgress(\"cycleA\");\nconst claimedAlready = points?.Milestone?.ClaimedIDs?.includes(\"m1\") ?? false;\n\nif (\n  !claimedAlready &&\n  (points?.Balance?.Current ?? 0) >= /* milestone.RequiredProgress */ 100\n) {\n  const res = await client.quest.claimMilestoneReward(\"cycleA\", \"m1\");\n  if (!res.ok) return showError(res.error);\n  res.data.PointsTotalEarned; // lifetime points earned this cycle, for display\n}\n```\n\nMilestone eligibility is judged against the points token's **lifetime total**\n(`Balance.TotalEarned`, mirrored into `PointsCurrent`/`PointsTotalEarned` on\n`QuestPointsTrackView` — for this token they're always equal, since points are\nonly ever granted, never spent). Points land in that balance when a quest with\n`PointsReward > 0` is **claimed** (`claimQuestReward`/batch) — completing a\nquest alone does not add points, claiming it does, in the same atomic\ntransaction as the quest's own reward. So a player reaches milestone `m1` by\nclaiming enough individual quest rewards across the cycle — milestone claiming\nis independent of any _single_ quest's claim, but not of claiming in general.\n\n### Claim a group-completion grand reward\n\n```ts\nconst res = await client.quest.claimGroupCompletionReward(\n  \"cycleA\",\n  \"dailyGroupBonus\",\n);\nif (!res.ok) return showError(res.error); // e.g. \"not enough quests completed in group\"\nres.data.CompletedGroupQuests; // e.g. 3\nres.data.RequiredGroupQuests; // e.g. 3\n```\n\nEligibility counts quests in the group that reached `\"Completed\"` **or**\n`\"Claimed\"` — you don't need to claim every quest's own reward first, just\nfinish them. The required count is `RequiredCompletedQuests` if set, otherwise\n**every** quest currently in that group/cycle (0 means \"all\"). This is\nrecomputed live against the current catalog at claim time (not a snapshot from\nwhenever the player finished the quests), so a group whose quest list changed\nafter the player completed them can shift the totals. Once claimed, the id is\nrecorded in `cycle.ClaimedGroupCompletionIDs` — check that list to hide an\nalready-claimed banner.\n\n### Batch claim several quests/milestones at once\n\n```ts\nconst res = await client.quest.claimQuestRewardsBatch([\n  { CycleID: \"cycleA\", QuestID: \"q1\" },\n  { CycleID: \"cycleA\", QuestID: \"q2\" },\n  { QuestID: \"intro\" }, // permanent quest: CycleID omitted\n]);\nif (!res.ok) return showError(res.error);\nfor (const item of res.data) {\n  if (item.Success) applyOk(item.Id);\n  else showItemError(item.Id, item.Error); // this one was rejected\n}\n```\n\nBatch results are **partial-aware**: the outer `res.ok` tells you the call ran;\neach element's `Success`/`Error` tells you whether that item applied — one\nalready-claimed quest in the batch doesn't sink the others. `claimMilestoneRewardsBatch`\nworks the same way with `MilestoneClaimRef[]`.\n\n### Force a cycle refresh (e.g. on app resume)\n\n```ts\nconst res = await client.quest.refreshQuestCycles();\nif (res.ok) {\n  await client.quest.getUserQuestState(); // reload to pick up the new cycle instance\n}\n```\n\n`getUserQuestState()` already auto-refreshes cycles by default\n(`autoRefreshCycles: true`), so most apps never need to call this directly —\nreach for it when you want to roll cycles forward (e.g. after detecting a\nday/week boundary while the app was backgrounded) without waiting on a full\nstate reload, or want the two steps as separate UI beats (spinner → \"New\nquests!\" toast).\n\n## Gotchas\n\n- **Progress is reported by metric, not by quest.** `addQuestProgress` doesn't\n  target a quest id — it fans one `MetricID` update out to every objective\n  across every active quest (and cycle) that listens to it. Call it once per\n  underlying game action, not once per quest you think might care.\n- **Claiming has three independent tracks.** A quest's own `Reward`, its\n  cycle's points-track `Milestones`, and its group's `GroupCompletions` are\n  claimed through three different methods and three different cache locations\n  (`Quest.Cycles[...].Quests`, `EventToken.Quest`, `Quest.Cycles[...]\n.ClaimedGroupCompletionIDs`). Completing a quest can make all three\n  claimable at once — don't assume claiming one auto-claims the others.\n- **Milestone/points state lives in the event-token cache, not `Quest`.**\n  `client.data.user.state?.Quest` holds quest/objective progress; the points\n  balance and claimed-milestone ids live at\n  `client.data.user.state?.EventToken?.Quest`, keyed by `cycleID` or\n  `\"cycleID:instanceKey\"` for recurring cycles. Use the\n  `client.data.user.getQuestPointsProgress(cycleID)` helper instead of\n  indexing the bucket yourself — it normalizes the composite key for you.\n- **Guard against double-submit.** Each call mints a fresh idempotency key\n  (`RelatedEntityID`), so two separate calls are two real operations — a\n  double-clicked \"Claim\" can attempt to claim twice (the second simply fails\n  as already-claimed, but don't rely on that for UX). Disable the control\n  while a call is in flight. Firing the same endpoint again within the\n  throttle window (default 600 ms) is rejected with `reason: \"throttled\"`\n  rather than duplicated.\n- **`RequiredQuestIDs` can gate progress, not just claiming.** A quest's\n  `PrerequisiteMode` decides whether unmet prerequisites block progress from\n  accruing at all (`BlockProgressAndClaim`) or only block the final claim\n  (`BlockClaimOnly`) — check which mode a quest uses before assuming progress\n  bars will move.\n- **Batch charges/prereqs are evaluated per item, independently.** Unlike some\n  other modules' batch upgrades, quest/milestone batch claims aren't chained —\n  each item is judged against state at the start of the call, so claiming\n  `q1` and `q2` in the same batch where `q2` requires `q1` completed (not\n  claimed) still works, but don't expect claim-order effects within one batch\n  call.\n- **Cycles roll forward wholesale, not incrementally.** When a cycle's schedule\n  window rotates (e.g. midnight UTC for a daily), the server replaces that\n  cycle's entire `Quests` map and `ClaimedGroupCompletionIDs` with a fresh,\n  empty state — there is no partial carry-over of yesterday's progress. Always\n  call `getUserQuestState()` (or `refreshQuestCycles()` + a reload) after\n  detecting a boundary rather than trusting a stale cached cycle.\n- **Cache patches for an unknown cycle silently no-op.** `claimQuestReward` and\n  `claimGroupCompletionReward` only patch the local cache if that `CycleID`\n  already exists in `client.data.user.state.Quest.Cycles` — if you call them\n  for a cycle the client hasn't loaded yet (e.g. right after a cold start with\n  a stale cache), the call still succeeds server-side but the UI won't reflect\n  it until you `getUserQuestState()` again. Load state before wiring up claim\n  buttons.\n- **Render from the cache, handle the error from the result.** The happy path\n  updates the cache + emits an event; the failure path gives you `reason` +\n  `error`. Use `reason` to decide behavior (retry on `\"connection\"`, re-auth on\n  `\"unauthorized\"`, toast the `error` on `\"server\"`).\n\n## Full reference\n\n[references/data-model.md](references/data-model.md) — every config and state\nfield, the objective/prerequisite/schedule/limit/gate blocks, and how the\npoints-track and milestone plumbing ties into the shared event-token cache.\nRead it when building config-driven UI (objective progress bars, milestone\nladders, cycle countdowns) or when an error message points at a config rule you\nneed to understand.\n",
+  "content": "---\nname: quest-system\ndescription: >-\n  Build a quest / daily-task system in a game on the iDosGames TypeScript SDK\n  (@idosgames/core) via client.quest (QuestService): load quest and cycle\n  definitions, load the player's quest progress state, add progress toward a\n  metric, claim a completed quest's reward, claim a points-track milestone\n  reward, claim a group-completion (grand) reward, and refresh cycles (dailies/\n  weeklies) forward. Use this whenever the user is working in the iDosGames TS\n  SDK or its game templates (board-game, idle-rpg) and wants daily/weekly quest\n  screens, task lists, objective/progress trackers, battle-pass-style points\n  tracks, milestone reward ladders, quest-group completion bonuses, or\n  otherwise touches client.quest, QuestService, QuestDefinitions,\n  UserQuestState, QuestPointsTrackView, or MilestoneDefinition — even if they\n  don't name the module explicitly.\n---\n\n# Quest system (iDosGames TS SDK)\n\nThe Quest module runs a title's task/quest board: dailies, weeklies, permanent\nquests, and one-off event quests, each made of objectives that accrue progress\ntoward a metric. Everything is **server-authoritative**: the backend tracks\nprogress, decides when a quest is `Completed`, and validates every claim. The\nclient asks the backend to report progress or claim a reward, and the SDK\nmirrors the confirmed result into a local cache your UI reads. You never\ncompute quest status yourself — you call a method, check the result, and\nrender from the cache.\n\nThis skill is for **using** the production `QuestService`, not for porting or\nextending it. If a call is rejected, that's the backend enforcing a rule\n(objective not met, already claimed, prerequisite quest incomplete) — surface\nthe error, don't try to reproduce the check client-side.\n\n## The two data shapes\n\nKeep these straight; every recipe below is just moving between them.\n\n1. **Definitions** (config, same for every player) — the title's catalog of\n   quest cycles (dailies/weeklies/permanent), the quests inside each cycle,\n   their objectives/rewards/prerequisites, and the cycle's milestone points\n   track and group-completion grand rewards. Fetched with\n   `getQuestDefinitions()`.\n2. **User quest state** (state, per player) — this player's live progress:\n   which cycle instances are active, each quest's `Status` and per-objective\n   `CurrentValue`, and the points-track balance/claimed-milestone ids for each\n   cycle. Fetched with `getUserQuestState()`.\n\nA `QuestDefinition` carries **only `QuestID` at its root**; everything else is\nsplit into named blocks — `Identity` (name/description/icon), `Linking`\n(cycles, group label, prerequisites), `Availability` (window, gate, limits),\n`Objectives`, `Reward`. Same layout as `CharacterDefinition`, so read\n`questDef.Identity?.DisplayName`, not `questDef.DisplayName`.\n\nA quest lives either **inside a cycle** (`Linking.CycleIDs` non-empty —\ndailies, weeklies, seasonal) or as a **permanent quest** (empty `CycleIDs` — a\none-time or always-available quest, e.g. onboarding). Most methods take an\noptional/blank `CycleID` to address either; the cache keeps them in separate\nbuckets (`Quest.Cycles[cycleID]` vs `Quest.PermanentQuests`).\n\nBlocks can be **authored** through presets (`QuestDefinitions.Presets`, one\nbinding per block — every block except `Identity`, which is always written inline) so a 42-quest event isn't 42 copies of the same settings —\nbut the backend resolves that when it materializes the title config. What\n`getQuestDefinitions()` hands you is already assembled; a client never merges\nanything.\n\nThree distinct reward mechanisms — don't conflate them:\n\n- **Quest reward** — `Reward.Grant` on one `QuestDefinition`, claimed once that\n  quest's objectives are all met (`Status: \"Completed\"`), via\n  `claimQuestReward`. Moves the quest to `\"Claimed\"`.\n- **Chain phase** — a cycle whose `Schedule.Mode` is `\"Chained\"` plays its `Phases` one after\n  another and then repeats. Each phase is a separate window with its **own** points track and its\n  **own** claimed milestones, so a \"season\" of eight weeks is one cycle, not eight. Quests bind to\n  phases with `Linking.PhaseIDs`. The live phase arrives in `PointsTracks[cycleID].PhaseID`.\n- **Milestone reward** — a rung on a cycle's **points track** (backend/config\n  comments call this \"Achievements\"): claiming a quest with\n  `Reward.PointsReward > 0` also grants that many points into a per-cycle point balance — a dedicated\n  `EventTokenType.Quest` token, tracked separately from any single quest's own\n  claim status — in the same atomic transaction as the quest claim. Each\n  `MilestoneDefinition` in `Cycle.Milestones` pays out once that balance's\n  lifetime total crosses its `RequiredProgress`. Claimed via\n  `claimMilestoneReward`. This is the battle-pass-style ladder — a player can\n  hit a milestone from points earned across many different quest claims, and\n  milestone eligibility never re-checks any individual quest's status.\n- **Group-completion reward** — a grand bonus in `Cycle.GroupCompletions` that\n  pays out once at least `RequiredCompletedQuests` quests sharing a\n  `Linking.GroupID` have reached `\"Completed\"` (not necessarily claimed).\n  Claimed via `claimGroupCompletionReward`. A \"group\" is nothing but that\n  string label — there is no group entity to look up.\n\nAll three can be in flight simultaneously for the same cycle — completing one\nquest can push its points into the milestone track, count toward its group's\ncompletion total, _and_ be individually claimable, all at once.\n\n**Progress** is reported with `addQuestProgress(metricID, progressValue)` — a\ngeneric counter keyed by `MetricID`, not by quest id. The backend fans one\nmetric update out to every objective across every active quest that listens to\nthat `MetricID` (per each objective's own `AggregationMethod`/filters), and\nreturns the list of quests/objectives that changed. You call this from your\ngame-loop code wherever the underlying action happens (e.g. \"enemy defeated\" →\n`addQuestProgress(\"EnemiesDefeated\", 1)`), not once per quest.\n\n**Cycles** (dailies/weeklies) roll forward on a schedule. `getUserQuestState`\ndefaults to auto-refreshing stale cycles for you (`autoRefreshCycles = true`);\ncall `refreshQuestCycles()` directly when you want to force-check for a new\ncycle boundary (e.g. app resumed from background) without re-fetching the\nwhole state.\n\nFor the full field-by-field shape of Definitions and state (objective sources,\nprerequisite modes, schedule/limit/gate blocks, the points-track/milestone\nplumbing), read [references/data-model.md](references/data-model.md). You do\n**not** need it to call the methods — only to drive richer UI off the config.\n\n## Setup\n\n```ts\nimport { createIDosGamesClient } from \"@idosgames/core\";\n\nconst client = createIDosGamesClient({ titleID: \"your-title-id\" });\nawait client.auth.loginWithDeviceID(); // or any auth.* method\n\nconst quest = client.quest; // the QuestService\n```\n\nEvery quest method requires an authenticated session. Without one they return\n`{ ok: false, reason: \"unauthorized\" }` — they do not throw. There is one\n`client` per player; don't share it across sessions.\n\n## Methods\n\nAll methods return `Promise<OperationResult<T>>`: a discriminated union that is\neither `{ ok: true, data }` or `{ ok: false, reason, error }`. Always branch on\n`result.ok` before touching `result.data`. `reason` is one of `\"client\"` (bad\nlocal args), `\"unauthorized\"`, `\"throttled\"` (fired the same endpoint again\ninside the throttle window), `\"connection\"` (transient, offer Retry),\n`\"validation\"` (response/schema drift), or `\"server\"` (backend rejected it —\n`error` carries the human-readable reason, e.g. \"Quest is not completed\",\n\"Already claimed\", \"Prerequisite quest not completed\").\n\n| Method                                                   | Purpose                                                              | `data` on success                                                          |\n| -------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------- |\n| `getQuestDefinitions()`                                  | Load the title's quest/cycle catalog (config).                       | `QuestDefinitions`                                                         |\n| `getUserQuestState(autoRefreshCycles?)`                  | Load this player's quest progress (state). Defaults to auto-refresh. | `GetUserQuestStateResponse` (`State`, `PointsTracks`)                      |\n| `refreshQuestCycles()`                                   | Force-check cycle boundaries and roll any stale cycle forward.       | `SuccessResponse`                                                          |\n| `addQuestProgress(metricID, progressValue)`              | Report progress on a metric; fans out to every listening objective.  | `AddQuestProgressResponse` (`Updates`)                                     |\n| `claimQuestReward(questID, cycleID?)`                    | Claim a single completed quest's reward.                             | `ClaimQuestRewardResponse` (`NewStatus`, `Resources`)                      |\n| `claimQuestRewardsBatch(quests)`                         | Claim several quests' rewards in one atomic call.                    | `BatchItemResult<ClaimQuestRewardResponse>[]`                              |\n| `claimMilestoneReward(cycleID, milestoneID)`             | Claim one points-track milestone reward for a cycle.                 | `ClaimMilestoneRewardResponse` (`PointsTotalEarned`, `Resources`)          |\n| `claimMilestoneRewardsBatch(milestones)`                 | Claim several milestone rewards in one atomic call.                  | `BatchItemResult<ClaimMilestoneRewardResponse>[]`                          |\n| `claimGroupCompletionReward(cycleID, groupCompletionID)` | Claim a cycle's group-completion grand reward.                       | `ClaimGroupCompletionRewardResponse` (`CompletedGroupQuests`, `Resources`) |\n\n`claimQuestReward` / `claimMilestoneReward` / `claimGroupCompletionReward` all\naccept a blank/absent `CycleID` to mean a permanent quest (quest claim only —\nmilestones and group-completions always belong to a cycle). Each mints its own\n`RelatedEntityID` internally for idempotency; you don't supply one.\n\n`claimQuestRewardsBatch(quests)` takes `QuestClaimRef[]` (`{ CycleID?,\nQuestID? }`, deduped by `CycleID`+`QuestID`); `claimMilestoneRewardsBatch(milestones)`\ntakes `MilestoneClaimRef[]` (`{ CycleID?, MilestoneID? }`, deduped by\n`CycleID`+`MilestoneID`).\n\nOn success, each method also **mirrors the confirmed change into the cache and\nemits an event** — you don't apply anything by hand. Granted resources\n(currencies, items) ride along in `data.Resources` (a `ResourceOperation`, see\n[ResourceModels](../../../packages/core/src/models/_shared/ResourceModels.ts))\nand are already applied to the cached balances, so read updated balances\nstraight from the cache.\n\n## Reading state and reacting to changes\n\nDrive the UI off the cache, not off one-off return values — that way every\nscreen stays consistent no matter which code path changed things.\n\n```ts\n// Quest progress (only present after getUserQuestState()):\nconst cycleA = client.data.user.state?.Quest?.Cycles?.[\"cycleA\"];\ncycleA?.Quests?.[\"q1\"]?.Status; // \"Active\" | \"Completed\" | \"Claimed\" | \"Expired\"\ncycleA?.Quests?.[\"q1\"]?.Objectives?.[\"obj1\"]?.CurrentValue;\ncycleA?.ClaimedGroupCompletionIDs; // string[]\n\nconst permanentQuest =\n  client.data.user.state?.Quest?.PermanentQuests?.[\"intro\"];\n\n// Points track (balance + claimed milestone ids), keyed by cycleID (or\n// \"cycleID:instanceKey\" for recurring cycles) — read with the helper so you\n// don't have to know the exact composite key:\nconst points = client.data.user.getQuestPointsProgress(\"cycleA\");\npoints?.Balance?.Current; // current points balance this cycle\npoints?.Balance?.TotalEarned;\npoints?.Milestone?.ClaimedIDs; // milestone ids already claimed\n\n// Definitions (cached after getQuestDefinitions()):\nimport type { QuestDefinitions } from \"@idosgames/core\";\nconst defs = client.data.config.getSection<QuestDefinitions>(\"Quest\");\n```\n\nSubscribe with `client.on(...)`; each returns an unsubscribe fn:\n\n- `quest:definitionsLoaded` → `QuestDefinitions`\n- `quest:userStateLoaded` → `UserQuestState`\n- `quest:cyclesRefreshed` → `void`\n- `quest:progressAdded` → `AddQuestProgressResponse`\n- `quest:rewardClaimed` → `ClaimQuestRewardResponse`\n- `quest:rewardsClaimedBatch` → `ClaimQuestRewardsBatchResponse`\n- `quest:milestoneClaimed` → `ClaimMilestoneRewardResponse`\n- `quest:milestonesClaimedBatch` → `ClaimMilestoneRewardsBatchResponse`\n- `quest:groupCompletionClaimed` → `ClaimGroupCompletionRewardResponse`\n\nThe coarse `user:questUpdated` (and `user:anyUpdated`) also fire on any quest\ncache write — handy for a \"re-render everything\" hook.\n\n```ts\nconst off = client.on(\"quest:progressAdded\", (r) => {\n  for (const u of r.Updates ?? []) {\n    console.log(`${u.QuestID} objective ${u.ObjectiveID} -> ${u.NewValue}`);\n  }\n});\n// later: off();\n```\n\n## Recipes\n\n### Load the board and render quest cards\n\n```ts\nawait client.quest.getQuestDefinitions();\nawait client.quest.getUserQuestState();\n\nconst defs = client.data.config.getSection<QuestDefinitions>(\"Quest\");\nconst cycles = client.data.user.state?.Quest?.Cycles ?? {};\n\nfor (const [cycleID, cycleDef] of Object.entries(defs?.Cycles ?? {})) {\n  const userCycle = cycles[cycleID];\n  for (const [questID, questDef] of Object.entries(defs?.Quests ?? {})) {\n    if (!questDef.Linking?.CycleIDs?.includes(cycleID)) continue;\n    const progress = userCycle?.Quests?.[questID];\n    // progress?.Status drives the card state: not-started/Active/Completed/Claimed.\n    // questDef.Objectives + progress?.Objectives drives the progress bar(s).\n  }\n}\n```\n\nA quest's `Linking.CycleIDs` lists every cycle it can appear in;\ncross-reference against `defs.Cycles` to know which are currently relevant. A quest absent from\n`userCycle.Quests` simply hasn't accrued any progress yet — treat it as\n`\"Active\"` with zero progress, not as an error. The backend creates a quest's\nprogress record (and each objective's) lazily, the first time it accrues\nsomething — it never pre-populates the catalog with zeros.\n\n### Report progress, then claim\n\n```ts\n// Wherever the underlying game action happens:\nconst prog = await client.quest.addQuestProgress(\"EnemiesDefeated\", 1);\nif (!prog.ok) return showError(prog.error);\n\nfor (const u of prog.data.Updates ?? []) {\n  if (u.Status === \"Completed\") {\n    // Surface a \"claim\" button for u.QuestID / u.CycleID now.\n  }\n}\n```\n\n```ts\n// Later, when the player taps Claim:\nconst claim = await client.quest.claimQuestReward(\"q1\", \"cycleA\");\nif (!claim.ok) return showError(claim.error); // e.g. \"Quest is not completed\", \"Already claimed\"\n// cache now shows q1 as \"Claimed\"; balances already credited.\n```\n\nClaiming before every objective is met, or claiming twice, both fail with\n`reason: \"server\"` — the quest must be `\"Completed\"` and not already\n`\"Claimed\"`. There's no client-side shortcut to check this ahead of time beyond\nreading the cached `Status` you already have.\n\nOnly objectives configured with `Source: \"ClientApi\"` can be advanced this way;\nan unrecognized `MetricID` fails with `\"MetricID not allowed for ClientApi\"`.\nNever send an inflated `ProgressValue` \"to be safe\" — if a matching objective\ndeclares `MaxProgressPerCall`, the backend compares your raw value against it\nand **bans the account** on a violation (`\"User banned: Value exceeds\nMaxValuePerCall\"`); it does not just clamp and continue.\n\n### Objectives you must NOT report progress for\n\nObjectives with `Source: \"SystemEvent\"` are advanced by the backend itself from\ntheir `Triggers` list — board rolls, store purchases, marketplace settlements,\nclaiming another quest. There is no call to make: `addQuestProgress` rejects\nthem, and adding a client-side counter for them double-counts nothing but wastes\na request.\n\nWhen such an objective moves, the progress rides back on the envelope of\nwhatever call caused it (a roll, a purchase, a claim) as\n`QuestProgress: QuestProgressUpdate[]`. The client applies it to the cached user\nstate automatically, so quest UI just needs to re-read the cache — do not poll\n`getUserQuestState` for it.\n\n`Source: \"ServerApi\"` objectives are moved only by a CloudCode script calling\n`server.AddQuestProgress(metricID, value)`. Same rule: nothing for the game to\ncall.\n\n### Claim a milestone once the points track crosses a rung\n\n```ts\nconst points = client.data.user.getQuestPointsProgress(\"cycleA\");\nconst claimedAlready = points?.Milestone?.ClaimedIDs?.includes(\"m1\") ?? false;\n\nif (\n  !claimedAlready &&\n  (points?.Balance?.Current ?? 0) >= /* milestone.RequiredProgress */ 100\n) {\n  const res = await client.quest.claimMilestoneReward(\"cycleA\", \"m1\");\n  if (!res.ok) return showError(res.error);\n  res.data.PointsTotalEarned; // lifetime points earned this cycle, for display\n}\n```\n\nMilestone eligibility is judged against the points token's **lifetime total**\n(`Balance.TotalEarned`, mirrored into `PointsCurrent`/`PointsTotalEarned` on\n`QuestPointsTrackView` — for this token they're always equal, since points are\nonly ever granted, never spent). Points land in that balance when a quest with\n`Reward.PointsReward > 0` is **claimed** (`claimQuestReward`/batch) — completing a\nquest alone does not add points, claiming it does, in the same atomic\ntransaction as the quest's own reward. So a player reaches milestone `m1` by\nclaiming enough individual quest rewards across the cycle — milestone claiming\nis independent of any _single_ quest's claim, but not of claiming in general.\n\n### Claim a group-completion grand reward\n\n```ts\nconst res = await client.quest.claimGroupCompletionReward(\n  \"cycleA\",\n  \"dailyGroupBonus\",\n);\nif (!res.ok) return showError(res.error); // e.g. \"not enough quests completed in group\"\nres.data.CompletedGroupQuests; // e.g. 3\nres.data.RequiredGroupQuests; // e.g. 3\n```\n\nEligibility counts quests in the group that reached `\"Completed\"` **or**\n`\"Claimed\"` — you don't need to claim every quest's own reward first, just\nfinish them. The required count is `RequiredCompletedQuests` if set, otherwise\n**every** quest currently in that group/cycle (0 means \"all\"). This is\nrecomputed live against the current catalog at claim time (not a snapshot from\nwhenever the player finished the quests), so a group whose quest list changed\nafter the player completed them can shift the totals. Once claimed, the id is\nrecorded in `cycle.ClaimedGroupCompletionIDs` — check that list to hide an\nalready-claimed banner.\n\n### Batch claim several quests/milestones at once\n\n```ts\nconst res = await client.quest.claimQuestRewardsBatch([\n  { CycleID: \"cycleA\", QuestID: \"q1\" },\n  { CycleID: \"cycleA\", QuestID: \"q2\" },\n  { QuestID: \"intro\" }, // permanent quest: CycleID omitted\n]);\nif (!res.ok) return showError(res.error);\nfor (const item of res.data) {\n  if (item.Success) applyOk(item.Id);\n  else showItemError(item.Id, item.Error); // this one was rejected\n}\n```\n\nBatch results are **partial-aware**: the outer `res.ok` tells you the call ran;\neach element's `Success`/`Error` tells you whether that item applied — one\nalready-claimed quest in the batch doesn't sink the others. `claimMilestoneRewardsBatch`\nworks the same way with `MilestoneClaimRef[]`.\n\n### Force a cycle refresh (e.g. on app resume)\n\n```ts\nconst res = await client.quest.refreshQuestCycles();\nif (res.ok) {\n  await client.quest.getUserQuestState(); // reload to pick up the new cycle instance\n}\n```\n\n`getUserQuestState()` already auto-refreshes cycles by default\n(`autoRefreshCycles: true`), so most apps never need to call this directly —\nreach for it when you want to roll cycles forward (e.g. after detecting a\nday/week boundary while the app was backgrounded) without waiting on a full\nstate reload, or want the two steps as separate UI beats (spinner → \"New\nquests!\" toast).\n\n## Gotchas\n\n- **Config fields live in blocks, not on the quest root.** `QuestDefinition` has\n  only `QuestID` at the top level; the name is `Identity.DisplayName`, the\n  cycles are `Linking.CycleIDs`, the window is `Availability.Schedule`, the\n  payout is `Reward.Grant`, the points are `Reward.PointsReward`. Reading\n  `questDef.DisplayName` compiles (the schemas keep `.passthrough()`) and\n  silently yields `undefined`. Player **state** is unaffected — `UserQuestState`\n  was never blocked.\n- **Progress is reported by metric, not by quest.** `addQuestProgress` doesn't\n  target a quest id — it fans one `MetricID` update out to every objective\n  across every active quest (and cycle) that listens to it. Call it once per\n  underlying game action, not once per quest you think might care.\n- **Claiming has three independent tracks.** A quest's own `Reward`, its\n  cycle's points-track `Milestones`, and its group's `GroupCompletions` are\n  claimed through three different methods and three different cache locations\n  (`Quest.Cycles[...].Quests`, `EventToken.Quest`, `Quest.Cycles[...]\n.ClaimedGroupCompletionIDs`). Completing a quest can make all three\n  claimable at once — don't assume claiming one auto-claims the others.\n- **Milestone/points state lives in the event-token cache, not `Quest`.**\n  `client.data.user.state?.Quest` holds quest/objective progress; the points\n  balance and claimed-milestone ids live at\n  `client.data.user.state?.EventToken?.Quest`, keyed by `cycleID` or\n  `\"cycleID:instanceKey\"` for recurring cycles. Use the\n  `client.data.user.getQuestPointsProgress(cycleID)` helper instead of\n  indexing the bucket yourself — it normalizes the composite key for you.\n- **Guard against double-submit.** Each call mints a fresh idempotency key\n  (`RelatedEntityID`), so two separate calls are two real operations — a\n  double-clicked \"Claim\" can attempt to claim twice (the second simply fails\n  as already-claimed, but don't rely on that for UX). Disable the control\n  while a call is in flight. Firing the same endpoint again within the\n  throttle window (default 600 ms) is rejected with `reason: \"throttled\"`\n  rather than duplicated.\n- **`Linking.RequiredQuestIDs` can gate progress, not just claiming.** A quest's\n  `Linking.PrerequisiteMode` decides whether unmet prerequisites block progress from\n  accruing at all (`BlockProgressAndClaim`) or only block the final claim\n  (`BlockClaimOnly`) — check which mode a quest uses before assuming progress\n  bars will move.\n- **Batch charges/prereqs are evaluated per item, independently.** Unlike some\n  other modules' batch upgrades, quest/milestone batch claims aren't chained —\n  each item is judged against state at the start of the call, so claiming\n  `q1` and `q2` in the same batch where `q2` requires `q1` completed (not\n  claimed) still works, but don't expect claim-order effects within one batch\n  call.\n- **Cycles roll forward wholesale, not incrementally.** When a cycle's schedule\n  window rotates (e.g. midnight UTC for a daily), the server replaces that\n  cycle's entire `Quests` map and `ClaimedGroupCompletionIDs` with a fresh,\n  empty state — there is no partial carry-over of yesterday's progress. Always\n  call `getUserQuestState()` (or `refreshQuestCycles()` + a reload) after\n  detecting a boundary rather than trusting a stale cached cycle.\n- **Cache patches for an unknown cycle silently no-op.** `claimQuestReward` and\n  `claimGroupCompletionReward` only patch the local cache if that `CycleID`\n  already exists in `client.data.user.state.Quest.Cycles` — if you call them\n  for a cycle the client hasn't loaded yet (e.g. right after a cold start with\n  a stale cache), the call still succeeds server-side but the UI won't reflect\n  it until you `getUserQuestState()` again. Load state before wiring up claim\n  buttons.\n- **Render from the cache, handle the error from the result.** The happy path\n  updates the cache + emits an event; the failure path gives you `reason` +\n  `error`. Use `reason` to decide behavior (retry on `\"connection\"`, re-auth on\n  `\"unauthorized\"`, toast the `error` on `\"server\"`).\n\n## Full reference\n\n[references/data-model.md](references/data-model.md) — every config and state\nfield, the objective/prerequisite/schedule/limit/gate blocks, and how the\npoints-track and milestone plumbing ties into the shared event-token cache.\nRead it when building config-driven UI (objective progress bars, milestone\nladders, cycle countdowns) or when an error message points at a config rule you\nneed to understand.\n",
   "references": [
     {
       "path": "data-model.md",
-      "content": "# Quest data model — reference\n\nFull shape of the config (Definitions) and player state, the cycle/schedule\nresolution rules, the points-track (\"Achievements\") plumbing, group-completion\nmath, and the server-side limits/idempotency rules. All of these are **strictly\ntyped in the SDK** — `QuestDefinitions` and every nested block (`QuestDefinition`,\n`QuestCycleDefinition`, `QuestObjectiveDefinition`, `QuestGroupCompletionDefinition`,\nthe shared `ScheduleSpec`/`SegmentGate`/`LimitSpec`/`MilestoneDefinition`/\n`EventTokenDefinition` blocks, …) are exported from `@idosgames/core`, so\n`getQuestDefinitions()` and `getSection<QuestDefinitions>(\"Quest\")` give you\nconcrete types, not `unknown`. The schemas keep `.passthrough()`, so a field the\nbackend adds later still round-trips. Field names are PascalCase (straight from\nthe backend JSON).\n\nBackend source of truth for everything below:\n`IDosGamesSDK/API/Client/v2/Quest/Quest.cs`,\n`IDosGamesSDK/API/Client/v2/Quest/Models/QuestDefinitions.cs`,\n`IDosGamesSDK/API/Client/v2/Quest/Models/UserQuestState.cs`,\n`IDosGamesSDK/API/Core/Scheduling/Services/ScheduleResolver.cs`,\n`IDosGamesSDK/API/Core/Event/Services/EventTokenService.cs`.\n\n## Contents\n\n- [Player state](#player-state) — what `getUserQuestState()` returns\n- [Config: QuestDefinitions](#config-questdefinitions) — what `getQuestDefinitions()` returns\n- [QuestCycleDefinition](#questcycledefinition)\n- [QuestDefinition](#questdefinition)\n- [QuestObjectiveDefinition + progress aggregation](#questobjectivedefinition--progress-aggregation)\n- [Prerequisites (`RequiredQuestIDs`)](#prerequisites-requiredquestids)\n- [Cycle schedule resolution](#cycle-schedule-resolution)\n- [Per-quest schedule (\"staged unlock\" / Achievements)](#per-quest-schedule-staged-unlock--achievements)\n- [Points track (\"Achievements\") — the Quest event-token](#points-track-achievements--the-quest-event-token)\n- [Group-completion (grand reward) math](#group-completion-grand-reward-math)\n- [`AddQuestProgress` server-side rules](#addquestprogress-server-side-rules)\n- [Idempotency, atomicity, batch limits](#idempotency-atomicity-batch-limits)\n\n---\n\n## Player state\n\nReturned by `getUserQuestState()` as `{ State, PointsTracks }` and cached at\n`client.data.user.state?.Quest` (progress) + `client.data.user.state?.EventToken?.Quest`\n(points track — see below). Hand-written interfaces (not `z.infer`) because the\ncache-patch methods mutate these objects in place.\n\n```ts\ninterface UserQuestState {\n  Cycles?: Record<string, UserQuestCycleState>; // key = CycleID\n  PermanentQuests?: Record<string, UserQuestProgress>; // key = QuestID\n  LastUpdatedUtc?: string;\n}\n\ninterface UserQuestCycleState {\n  CycleID?: string;\n  CycleStartUtc?: string; // current window start, UTC\n  CycleEndUtc?: string; // current window end, UTC\n  Quests?: Record<string, UserQuestProgress>; // key = QuestID, THIS window only\n  ClaimedGroupCompletionIDs?: string[]; // CompletionIDs already claimed this window\n}\n\ninterface UserQuestProgress {\n  QuestID: string;\n  Status: \"Active\" | \"Completed\" | \"Claimed\" | \"Expired\";\n  ActivatedAtUtc?: string | null;\n  CompletedAtUtc?: string | null;\n  ClaimedAtUtc?: string | null;\n  Objectives?: Record<string, UserQuestObjectiveProgress>; // key = ObjectiveID\n}\n\ninterface UserQuestObjectiveProgress {\n  ObjectiveID: string;\n  CurrentValue: number;\n  Completed: boolean;\n  CompletedAtUtc?: string | null;\n}\n```\n\n**Lazy initialization** (`Quest.cs` `RefreshQuestCycles` / `CreateQuestProgressFromDefinition`):\na quest's `UserQuestProgress` (and each objective's `UserQuestObjectiveProgress`)\nis created only the first time progress is reported for it — the server does\n**not** pre-populate every configured quest/objective with zeros. A quest absent\nfrom `Cycles[cycleID].Quests` (or `PermanentQuests`) simply has zero progress on\nevery objective; render it as `\"Active\"`, not as an error or \"unknown\" state.\n`Expired` is only ever set for cyclic quests (never for permanent quests) and\nonly via the same lazy path — in practice you will see `Active` → `Completed` →\n`Claimed` for anything you've touched; a truly stale quest from a rolled-over\ncycle is simply absent (the whole cycle bucket gets replaced on rollover, see\nbelow), not flagged `Expired` in current code paths.\n\n---\n\n## Config: QuestDefinitions\n\nReturned by `getQuestDefinitions()`; cached via\n`client.data.config.getSection<QuestDefinitions>(\"Quest\")`.\n\n```ts\ninterface QuestDefinitions {\n  Cycles?: Record<string, QuestCycleDefinition>; // key = CycleID\n  Quests?: Record<string, QuestDefinition>; // key = QuestID\n}\n```\n\nA quest is **permanent** iff its `CycleIDs` is null/empty; otherwise it is\n**cyclic** and belongs to every cycle listed in `CycleIDs` (a quest can appear\nin more than one cycle definition, each with independent progress/claim state).\nCycle IDs and quest/objective IDs must all be Mongo-safe (no `.` or `$`) —\nthe server rejects unsafe keys outright (`\"Invalid CycleID (mongo-unsafe): …\"`,\n`\"QuestID is mongo-unsafe\"`, etc.); this only matters if you let players or\nremote config drive raw ids into these fields.\n\n---\n\n## QuestCycleDefinition\n\n`Quest.cs` / `QuestDefinitions.cs`. One recurring or one-off \"board\" (dailies,\nweeklies, a scheduled event window, …). Quests do **not** get listed here —\neach `QuestDefinition` points back at the cycle via `CycleIDs`.\n\n```ts\ninterface QuestCycleDefinition {\n  CycleID?: string;\n  DisplayName?: string;\n  Schedule?: ScheduleSpec; // cycle window/reset — see below\n  Milestones?: Record<string, MilestoneDefinition>; // points-track rungs, key = MilestoneID\n  Gate?: SegmentGate; // audience gate for the whole cycle; ANDed with each quest's own Gate\n  PointsToken?: EventTokenDefinition; // global caps/burn for the points track (see below)\n  GroupCompletions?: Record<string, QuestGroupCompletionDefinition>; // key = CompletionID\n}\n```\n\nBackend default when a cycle is authored without an explicit `Schedule`:\n`Mode: \"Cyclic\"`, `Cyclic: {}` (i.e. daily calendar reset) —\n`QuestCycleDefinition.Schedule` in `QuestDefinitions.cs`.\n\n---\n\n## QuestDefinition\n\n```ts\ninterface QuestDefinition {\n  QuestID?: string;\n  CycleIDs?: string[]; // null/empty => permanent; else cyclic, one entry per cycle it appears in\n  DisplayName?: string;\n  Description?: string;\n  SortOrder?: number; // lower = earlier in UI\n\n  RequiredQuestIDs?: string[]; // prerequisite QuestIDs — see below\n  PrerequisiteMode?: \"BlockProgressAndClaim\" | \"BlockClaimOnly\"; // default BlockProgressAndClaim\n\n  PointsReward?: number; // points into the cycle's points track on claim; ignored for permanent quests\n  Schedule?: ScheduleSpec; // per-quest unlock window; null = inherit the cycle's window (see below)\n  AccrueProgressWhenLocked?: boolean; // default false — see per-quest schedule section\n  Gate?: SegmentGate; // ANDed with the cycle's Gate\n  Limits?: LimitSpec; // per-quest per-source caps on POINTS grants only (not on objective progress)\n  GroupID?: string; // for UI grouping + QuestGroupCompletionDefinition.GroupID matching\n\n  Objectives?: Record<string, QuestObjectiveDefinition>; // key = ObjectiveID; ALL must complete\n  Reward?: ResourceGrant; // claimed via claimQuestReward\n}\n```\n\n`PrerequisiteMode` (`QuestDefinition.cs` comment, verbatim intent):\n\n| Mode                              | Effect on `RequiredQuestIDs`                                                                                                                            |\n| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `BlockProgressAndClaim` (default) | The quest does not start accruing progress at all until every listed prerequisite reaches `Completed`/`Claimed`; consequently it also can't be claimed. |\n| `BlockClaimOnly`                  | Progress accrues immediately; only the final reward claim is blocked until prerequisites are met.                                                       |\n\nA prerequisite is looked up \"where its own progress lives\": permanent →\n`PermanentQuests`; cyclic → the same `cycleID` if the prerequisite also belongs\nto it, otherwise the prerequisite's own first `CycleIDs` entry\n(`ArePrerequisitesMet`, `Quest.cs`). Empty/null `RequiredQuestIDs` = no gating.\n\n---\n\n## QuestObjectiveDefinition + progress aggregation\n\n```ts\ninterface QuestObjectiveDefinition {\n  ObjectiveID?: string;\n  Source?: \"ClientApi\" | \"ServerApi\" | \"SystemEvent\"; // who may report progress; default SystemEvent\n  MaxProgressPerCall?: number; // per-call delta cap (ClientApi abuse guard); 0/absent = no cap\n  MetricID?: string; // the metric key addQuestProgress reports against\n  TargetValue?: number; // default 1; required value to complete\n  AggregationMethod?: string; // \"Sum\" | \"Maximum\" | \"Minimum\" | \"Last\"; default \"Sum\"\n  Filters?: Record<string, string>; // optional metric refinement (not enforced client-side)\n}\n```\n\nOnly objectives with `Source: \"ClientApi\"` are reachable from `addQuestProgress`\n— `Source: \"ServerApi\"` / `\"SystemEvent\"` objectives are advanced by other\nbackend systems, never by the client, and a `MetricID` with no matching\n`ClientApi` objective anywhere in the catalog is rejected outright\n(`\"MetricID not allowed for ClientApi\"`).\n\nAggregation (`ApplyAggregation`, `Quest.cs`), given the objective's current\n`CurrentValue` and the incoming call value:\n\n| Method                   | New value                                                                                |\n| ------------------------ | ---------------------------------------------------------------------------------------- |\n| `Sum` (default)          | `current + incoming`, clamped to `long.MaxValue` on overflow; `incoming <= 0` is a no-op |\n| `Maximum`                | `max(current, incoming)`                                                                 |\n| `Minimum`                | `incoming` if `current == 0`, else `min(current, incoming)`                              |\n| `Last` (or unrecognized) | `incoming` (last-write-wins)                                                             |\n\nAfter aggregation, if `TargetValue > 0` the new value is clamped to\n`TargetValue` (progress bars never overshoot 100%); if `TargetValue <= 0` there\nis no cap. An objective is marked `Completed` once\n`(TargetValue <= 0 && newValue > 0) || newValue >= TargetValue`. A quest becomes\n`\"Completed\"` once **every** objective the player has a progress record for is\n`Completed` **and** every objective in the definition has a progress record —\ni.e. an objective with zero recorded progress blocks completion (it's absent\nfrom the player's `Objectives` map, so the `All(...)` check in\n`EnsureQuestObjectivesAndCompletion` fails for it).\n\n`MaxProgressPerCall` guards two different things depending on\n`AggregationMethod`:\n\n- If **any** matching `ClientApi` objective for the `MetricID` has\n  `MaxProgressPerCall > 0`, the server compares the **raw** `ProgressValue` you\n  sent against the (minimum across matches) cap **before** any clamping. If the\n  raw value exceeds it, the call is rejected **and the player is banned**\n  (`service.BanUser(...)`, fire-and-forget) with error `\"User banned: Value\nexceeds MaxValuePerCall\"`. This is a hard anti-abuse trip-wire, not a soft\n  clamp — never let client code send inflated values \"to be safe.\"\n- Only for objectives using `Sum` aggregation is the value additionally\n  clamped to `MaxProgressPerCall` before summing (defense in depth; irrelevant\n  once the ban-check above has already passed, since raw ⇐ cap by that point).\n\n---\n\n## Prerequisites (`RequiredQuestIDs`)\n\nSee the `PrerequisiteMode` table above. Enforcement points in `Quest.cs`:\n\n- **Progress accrual** (`AddQuestProgress` internal helper): for permanent\n  quests and for each cycle a cyclic quest belongs to, prerequisites are\n  checked (only in `BlockProgressAndClaim` mode) before the quest's\n  `UserQuestProgress` is even created/updated for that call.\n- **Claim** (`ClaimQuestReward` / batch): `ArePrerequisitesMet(...)` is checked\n  unconditionally (both modes gate the claim) — error\n  `\"Prerequisite quests are not completed\"`.\n\n---\n\n## Cycle schedule resolution\n\n`QuestCycleDefinition.Schedule` is a `ScheduleSpec` (`_shared/ScheduleModels.ts`\n/ `Core/Scheduling`), the same primitive every other module uses. For Quest,\n`RefreshQuestCycles` resolves it via `ScheduleResolver.ResolveActive(...)`\ninto a `[CycleStartUtc, CycleEndUtc)` window per the active `Mode`:\n\n- **`Cyclic`** (the practical default for dailies/weeklies): `Cyclic.Reset` picks\n  the calendar cadence — `Hourly`/`Daily`/`Weekly` (always **Monday** start)/`Monthly`\n  (always the **1st**)/`Yearly` are calendar-aligned in **UTC**, reset time is\n  **always 00:00:00 UTC** and is not configurable. `FixedInterval` instead repeats\n  every `Cyclic.IntervalSeconds` seconds from `Cyclic.AnchorUtc` (default anchor\n  `2026-01-01T00:00:00Z`, default interval 86400s if unset/≤0); an optional\n  `PauseBetweenCyclesSec` inserts a dead gap after each active window during\n  which `CanEarn` is `false` (`IsInPause = true`) but the window has still\n  technically \"ended\" — new progress does not accrue during the pause, though\n  already-completed quests remain claimable (claims are never earn-gated).\n- **`Scheduled`**: one fixed `[StartUtc, EndUtc]` window; `ClaimGraceHours`\n  extends claimability past `EndUtc` without extending earning (unless\n  `AllowEarningAfterEnd` is set).\n- **`AlwaysOn`**: always active, no end.\n- Any other/inactive resolution (e.g. `Triggered`, or `spec.IsActive === false`)\n  makes `ComputeCycleWindowUtc` **degrade to a plain UTC calendar day**\n  `[today 00:00, tomorrow 00:00)` as a fallback — don't configure `Triggered` on\n  a quest cycle expecting anything else.\n\n**Rollover behavior** (`RefreshQuestCycles`, called automatically by\n`getUserQuestState({autoRefreshCycles: true})` — the default — and before every\nmutating Quest action): when the resolved `[start, end)` no longer matches the\nstored `CycleStartUtc`/`CycleEndUtc`, the entire `UserQuestCycleState` for that\ncycle is **replaced with a brand-new, empty one** (`Quests: {}`,\n`ClaimedGroupCompletionIDs` reset) — there is no partial carry-over of\nin-progress quests into the new window. Cycles removed from config entirely are\ndeleted from the player's state on the next refresh. If the window has **not**\nrolled over, the refresh instead walks the player's **existing** quest progress\nrecords (only ones already started) and re-evaluates `Completed` status against\ncurrent config — it does not add new objectives to already-tracked quests.\n\n---\n\n## Per-quest schedule (\"staged unlock\" / Achievements)\n\n`QuestDefinition.Schedule` is an **independent, optional** `ScheduleSpec` layered\non top of the cycle's own schedule — this is how \"Day 2 unlocks 24h after Day 1\"\nor an \"Achievements\" track with a `ScheduleSpec`-driven unlock (rather than a\nliteral day-count) is built, with any number of stages at any interval, not just\nliteral days:\n\n- `Schedule` absent → the quest simply inherits its cycle's window; earning and\n  claiming follow the cycle's own `CanEarn`/`CanClaim`.\n- `Schedule` present → resolved via `ResolveQuestInstance`, which passes the\n  **cycle's** resolved instance as the `parent` for `Relative`-mode windows —\n  so a per-quest `Relative` schedule with `OffsetSecondsFromParentStart` is\n  \"N seconds after this cycle instance started,\" letting one `Cyclic` cycle\n  auto-repeat a whole staged sequence without hardcoded absolute dates.\n- `AccrueProgressWhenLocked` (default `false`) decides what happens **while**\n  the cycle's window is open but the quest's own window is not: `false` means a\n  locked stage accrues **zero** progress (a true lock — progress reported for\n  its metric while locked is simply dropped for that quest); `true` means\n  progress accrues the whole time the cycle is active, but the **reward claim**\n  is still gated on the quest's own `CanClaim` — so you can pre-accrue \"Day 3\"\n  progress while day 3 is still locked, and only the payout waits.\n\nEarning gate precedence for a cyclic quest, all of which must pass\n(`AddQuestProgress` internal helper): cycle `earningCycles` membership (cycle\nitself must be `CanEarn`, i.e. not `IsInPause`) → quest's own\n`IsQuestEarnable` (`AccrueProgressWhenLocked` bypasses this specific check) →\n`QuestGatesPass` (cycle `Gate` AND quest `Gate`) → prerequisites (only in\n`BlockProgressAndClaim` mode).\n\n---\n\n## Points track (\"Achievements\") — the Quest event-token\n\nThis is the mechanism the \"Achievements\" hint in the prompt refers to — it is\nreal and it is exactly the cycle's points track, not a separate module. Russian\ncomments in `Quest.cs` literally label it «Достижения» (Achievements).\n\n**How points get earned.** Each cyclic `QuestDefinition.PointsReward` (points,\nnot currency) is granted **only on claim** of that quest's own reward — via\n`ClaimQuestReward` / `ClaimQuestRewardsBatch`, in the **same atomic transaction**\nas the quest's `Reward` grant. It's `long`, defaults to `0`, and is ignored for\npermanent quests (`isPermanent` quests never touch the points track). A group\ncompletion (below) can **also** add points via its own `PointsReward`, on top of\nwhatever its member quests already contributed individually.\n\n**Where it's addressed.** The points track is backed by a standard\n`EventTokenType.Quest` event token (the same primitive TimedEvent/Leaderboard/\nCoopEvent/Season points tracks use), addressed at\n`EntityID = \"{cycleID}:{instanceKey}\"` where `instanceKey` comes from\n`ScheduleResolver`'s resolution of the **cycle's** schedule (`\"all\"` if the\ncycle has no resolvable instance). Because the instance key changes when the\ncycle's schedule rotates to a new window, **the points balance and claimed-milestone\nlist reset automatically on cycle rollover** — there is no explicit\n\"reset points\" step; it's a natural consequence of the address changing.\n\n**Where it lives in state.** `UserQuestState` does **not** carry the points\nbalance — it lives in `UserDataDocument.EventToken.Quest[entityID]`\n(`UserEventTokenProgress`: `Balance.Current`/`Balance.TotalEarned`,\n`Milestone.ClaimedIDs`). `GetUserQuestState` additionally projects a **read-only\nsnapshot** per cycle into `GetUserQuestStateResponse.PointsTracks[cycleID]`\n(`QuestPointsTrackView`) so the client doesn't have to know the composite key —\nthe TS SDK's `patchQuestPointsTracks` writes this into\n`client.data.user.state.EventToken.Quest[\"{cycleID}:{instanceKey}\"]` for you,\nand `client.data.user.getQuestPointsProgress(cycleID)` resolves the composite\nkey back out (`matchesBase`, `util/eventTokenIds.ts`) so you can look it up by\nplain `cycleID`.\n\n```ts\ninterface QuestPointsTrackView {\n  CycleID: string;\n  InstanceKey?: string | null;\n  CycleStartUtc?: string | null;\n  CycleEndUtc?: string | null; // source for a \"resets in\" timer\n  PointsTotalEarned?: number | null; // lifetime points earned this cycle instance\n  PointsCurrent?: number | null; // current balance (== TotalEarned; points are never spent)\n  ClaimedPointMilestoneIDs?: string[] | null;\n}\n```\n\n**Milestones** (`QuestCycleDefinition.Milestones`, keyed by `MilestoneID`) are\nthe shared Core `MilestoneDefinition` primitive\n(`RequiredProgress`, `Rewards`, `BonusRewards`, `SeasonTierRewards`,\n`SortOrder`, `IsFeatured`) — see `_shared/MilestoneModels.ts`. Eligibility is\njudged **only** against `Balance.TotalEarned` on the points token (never\n`Current`, though for Quest the two happen to always be equal since points are\nonly ever granted, never spent) — `EventTokenService.ComputeMilestoneClaim`:\nfails with `\"Not enough earned. Have: X, need: Y.\"` if under threshold, or\n`\"Milestone already claimed.\"` if `MilestoneID` is already in `ClaimedIDs`.\nClaiming pushes the id into `ClaimedIDs` via a Mongo `$push` guarded by a\n`$nin` filter (OCC — a concurrent duplicate claim loses the race cleanly). The\nmilestone's reward itself runs through the shared `MilestoneRewardResolver`\n(same resolver Leaderboard/TimedEvent/CommunityChest/Referral use), which\napplies the title's progression-multiplier overlay\n(`cfg.Reward.MilestoneRewardMultiplier`) if configured — so the actual payout\ncan exceed the base `Rewards` grant; read it from the response, don't assume\nface value.\n\n**Caps** on points grants (`BuildPointsGrantContext`): **global** caps come from\n`QuestCycleDefinition.PointsToken` (an `EventTokenDefinition` — `DailyEarnCap`,\n`MaxBalance`, `MaxPerGrant`); **per-quest-source** caps/cooldown come from\n`QuestDefinition.Limits` (a `LimitSpec`, mapped as `DailyWeightCap` →\nper-source daily cap, `DailyCap` → per-source daily trigger count,\n`CooldownSeconds` → per-source cooldown). Per-source limits only apply in the\n**single** `ClaimQuestReward` path — the batch claim path\n(`ClaimQuestRewardsBatch`) only enforces the cycle's **global** `PointsToken`\ncaps against the **summed** batch amount per address, since per-source limits\ndon't make sense once amounts from multiple quests are merged into one token\noperation. If a cap fully exhausts the grant, `EventTokenService.ComputeGrant`\ncan reduce the amount to `0`, which surfaces as a failed points portion inside\nthe resource operation — always read granted amounts from the response, never\nassume the full `PointsReward` landed.\n\n---\n\n## Group-completion (grand reward) math\n\n`QuestCycleDefinition.GroupCompletions[completionID]` (`QuestGroupCompletionDefinition`):\n\n```ts\ninterface QuestGroupCompletionDefinition {\n  CompletionID?: string;\n  GroupID?: string; // must match QuestDefinition.GroupID on member quests\n  RequiredCompletedQuests?: number; // 0 = \"ALL quests in this group, per current config\"\n  Gate?: SegmentGate; // ANDed with the cycle's Gate\n  Reward?: ResourceGrant;\n  PointsReward?: number; // additional points into the SAME cycle points track; 0 = none\n}\n```\n\n`ClaimGroupCompletionReward` computes eligibility **live**, at claim time, by\nscanning the **current** `QuestDefinitions.Quests` for every quest that (a)\nlists this `cycleID` in its `CycleIDs` and (b) has `GroupID` equal to the\ncompletion's `GroupID` — that's `totalGroupQuests`. Of those, it counts how many\nhave reached `Status === \"Completed\"` **or** `\"Claimed\"` in the player's current\ncycle state — that's `completedGroupQuests`. The required threshold is\n`RequiredCompletedQuests` if `> 0`, otherwise `totalGroupQuests` (i.e. every\ngroup quest currently in config). Failure modes:\n\n- `RequiredCompletedQuests` unset and the group is empty/misconfigured (no\n  quests currently reference that `GroupID` in that cycle) →\n  `\"No quests configured for this group\"` (required resolves to `0`, which is\n  rejected outright — you can never claim an empty group).\n- `completedGroupQuests < required` → `\"Not enough completed quests for this\ngroup\"`.\n- Already in `cycle.ClaimedGroupCompletionIDs` → `\"Group completion already\nclaimed\"` (checked in-memory before the DB round-trip, then re-enforced by an\n  `AnyEq`-negated Mongo filter for the actual OCC guard).\n- `completion.GroupID` blank/whitespace on the definition itself →\n  `\"Group completion has no GroupID\"` (a config error, not a player error).\n\nBecause the scan is **live against current config**, removing a quest from the\ngroup (or from the cycle) between when a player completed it and when they\nclaim the group reward can change `totalGroupQuests`/`completedGroupQuests` —\nthere's no snapshot of \"the group as it was.\" The response echoes\n`CompletedGroupQuests` and `RequiredGroupQuests` (the resolved threshold, not\nthe raw config field) so the client can show \"3 / 3\" without recomputing\nanything.\n\n---\n\n## `AddQuestProgress` server-side rules\n\nFull request-to-mutation path (`QuestV2.AddQuestProgress` public entry point +\nthe internal shared helper), summarized because several rules only make sense\ntogether:\n\n1. `MetricID` required; must match at least one `ClientApi`-sourced objective\n   in the **entire** quest catalog, or the call fails with `\"MetricID not\nallowed for ClientApi\"` before touching the database.\n2. `ProgressValue` (`long`) must be `>= 0`.\n3. If any matching objective declares `MaxProgressPerCall > 0`, the **raw**\n   value is checked against the smallest such cap across all matches; exceeding\n   it **bans the account** (see the objective section above) rather than\n   clamping — this is a hard security control, not UX guidance.\n4. The (possibly `Sum`-clamped) value then fans out to **every** quest/objective\n   pair across **every currently-earning cycle and every permanent quest**\n   whose objective's `Source === \"ClientApi\"` and `MetricID` matches — one\n   `addQuestProgress` call can move several quests (even across different\n   cycles) simultaneously if they all listen to the same metric.\n5. Each matched quest only advances if it isn't already `Completed`/`Claimed`\n   (`ApplyToQuestInstance` early-returns `false` otherwise) — so calling\n   `addQuestProgress` for an action a player keeps performing after a quest is\n   done is safe and a no-op for that quest.\n6. The response's `Updates[]` (`QuestProgressUpdate`) lists **only the\n   quest/objective pairs that actually changed** this call — an objective whose\n   `Sum` increment was clamped to `0` (already at `TargetValue`) or a locked\n   quest that accrued nothing produces no entry.\n7. This whole path calls `RefreshQuestCycles` first (unless the internal helper\n   is invoked with `ensureCyclesUpToDate: false`, which the public\n   `AddQuestProgress` action does to avoid double-refreshing) — so cycle\n   windows are always current before progress is evaluated.\n\n---\n\n## Idempotency, atomicity, batch limits\n\n- **Idempotency keys** (`ResourceService.ResolveRelatedEntityID`, stable ID\n  patterns from `Quest.cs`): single quest claim →\n  `\"{questID}\"` (permanent) or `\"{questID}_{cycleStartUtc:yyyyMMddHHmmss}\"`\n  (cyclic — so the **same** quest claimed again after the cycle rolls to a new\n  window is a distinct idempotency key, not a duplicate); milestone claim →\n  `\"{cycleID}_{milestoneID}_{instanceKey}\"`; group completion →\n  `\"{cycleID}_{completionID}_{cycleStartUtc:yyyyMMddHHmmss}\"`. You never\n  construct these yourself — the TS SDK mints its own client-side\n  `RelatedEntityID` (`quest_claim_…`, `milestone_claim_…`, `group_completion_…`,\n  each suffixed with a fresh UUID) purely for its own request-level tracking;\n  the **server-side** idempotency guarantee comes from the stable IDs above\n  plus the OCC filter on each claim, not from the client's `RelatedEntityID`.\n- **Atomicity.** Every claim path (`ClaimQuestReward`, `ClaimMilestoneReward`,\n  `ClaimGroupCompletionReward`, and both batch variants) runs the reward grant\n  and the state-mutating patches (status → `Claimed`, milestone `$push`, group\n  `$addToSet`) inside **one** `ResourceService.ApplyResourceOperationAtomicAsync`\n  call with an `extraFilter` re-asserting the pre-claim condition (e.g. quest\n  `Status == Completed`) — if the grant fails for any reason (insufficient\n  server-side room, a concurrent claim already flipped the filter condition,\n  etc.) the whole transaction rolls back; there is no partially-applied claim.\n- **Resources in batch responses.** For both `ClaimQuestRewardsBatch` and\n  `ClaimMilestoneRewardsBatch`, all included items' rewards are merged into a\n  **single** `ResourceBundle` (`BatchSupport.MergeBundles`) and charged/granted\n  in one call — the merged `ResourceOperation` is attached to only the **first\n  successful** `BatchItemResult.Data.Resources` in the returned array; every\n  other successful item's `Data.Resources` is an **empty** `ResourceOperation`\n  (`new ResourceOperation()`), not a duplicate of the shared one. Don't sum\n  resources across batch items — read them once from wherever they landed (the\n  TS SDK's `applyResourceOperation` is only ever called once, on the first\n  `Resources` it finds, matching this).\n- **Batch size.** `BatchSupport.MaxBatchSize = 50`. Both\n  `claimQuestRewardsBatch` and `claimMilestoneRewardsBatch` accumulate refs from\n  your array only up to 50 (after deduping by `CycleID+QuestID` /\n  `CycleID+MilestoneID`); anything past the 50th valid, deduped entry is\n  **silently dropped** — it never appears in the result array at all, so a\n  `results.length` shorter than your input isn't necessarily an error. Chunk\n  larger sets yourself.\n- **Batch validity filtering happens before charging.** Each item is\n  independently checked (mongo-safety, config existence, gates, schedule\n  window, prerequisites, current `Status`) and rejected into a preset\n  `BatchItemResult` **before** the shared resource operation runs; only\n  surviving items contribute to the merged grant and the combined Mongo filter\n  (`AND` of each item's own OCC filter). That combined filter means: if even\n  one surviving item's condition is no longer true by the time the transaction\n  actually commits (e.g. a race with another request), **the entire merged\n  operation fails** and every surviving item in that batch call reports the\n  same `apply.Error` — \"partial-aware\" describes the **pre-filtering** stage,\n  not protection against a mid-flight race on the shared charge.\n- **Rate limit / lock.** The whole `QuestV2` function uses\n  `RateLimitMilliseconds = 500` (per-IP endpoint throttle) and\n  `LockDurationMilliseconds = 10000` (per-user-action Mongo transaction lock)\n  inside `ClientRun.Execute` — both are backend-side controls independent of\n  the TS SDK's own 600ms client-side throttle guard.\n"
+      "content": "# Quest data model — reference\n\nFull shape of the config (Definitions) and player state, the cycle/schedule\nresolution rules, the points-track (\"Achievements\") plumbing, group-completion\nmath, and the server-side limits/idempotency rules. All of these are **strictly\ntyped in the SDK** — `QuestDefinitions` and every nested block (`QuestDefinition`\nand its `QuestIdentity`/`QuestLinking`/`QuestAvailability`/`QuestReward` blocks,\n`QuestCycleDefinition`, `QuestPhaseDefinition`, `QuestObjectiveDefinition`,\n`QuestGroupCompletionDefinition`, `QuestPresetRegistry`/`QuestPresetBindings`,\nthe shared `ScheduleSpec`/`SegmentGate`/`LimitSpec`/`MilestoneDefinition`/\n`EventTokenDefinition` blocks, …) are exported from `@idosgames/core`, so\n`getQuestDefinitions()` and `getSection<QuestDefinitions>(\"Quest\")` give you\nconcrete types, not `unknown`. The schemas keep `.passthrough()`, so a field the\nbackend adds later still round-trips. Field names are PascalCase (straight from\nthe backend JSON).\n\nBackend source of truth for everything below:\n`IDosGamesSDK/API/Client/v2/Quest/Quest.cs`,\n`IDosGamesSDK/API/Client/v2/Quest/Models/QuestDefinitions.cs`,\n`IDosGamesSDK/API/Client/v2/Quest/Models/UserQuestState.cs`,\n`IDosGamesSDK/API/Core/Scheduling/Services/ScheduleResolver.cs`,\n`IDosGamesSDK/API/Core/Event/Services/EventTokenService.cs`.\n\n## Contents\n\n- [Player state](#player-state) — what `getUserQuestState()` returns\n- [Config: QuestDefinitions](#config-questdefinitions) — what `getQuestDefinitions()` returns\n- [QuestCycleDefinition](#questcycledefinition)\n- [QuestDefinition](#questdefinition)\n- [Presets](#presets--authoring-n-days--m-tasks-without-nm-copies) — authoring N days × M tasks without N×M copies\n- [QuestObjectiveDefinition + progress aggregation](#questobjectivedefinition--progress-aggregation)\n- [Prerequisites (`RequiredQuestIDs`)](#prerequisites-requiredquestids)\n- [Cycle schedule resolution](#cycle-schedule-resolution)\n- [Per-quest schedule (\"staged unlock\" / Achievements)](#per-quest-schedule-staged-unlock--achievements)\n- [Points track (\"Achievements\") — the Quest event-token](#points-track-achievements--the-quest-event-token)\n- [Group-completion (grand reward) math](#group-completion-grand-reward-math)\n- [`AddQuestProgress` server-side rules](#addquestprogress-server-side-rules)\n- [Idempotency, atomicity, batch limits](#idempotency-atomicity-batch-limits)\n\n---\n\n## Player state\n\nReturned by `getUserQuestState()` as `{ State, PointsTracks }` and cached at\n`client.data.user.state?.Quest` (progress) + `client.data.user.state?.EventToken?.Quest`\n(points track — see below). Hand-written interfaces (not `z.infer`) because the\ncache-patch methods mutate these objects in place.\n\n```ts\ninterface UserQuestState {\n  Cycles?: Record<string, UserQuestCycleState>; // key = CycleID\n  PermanentQuests?: Record<string, UserQuestProgress>; // key = QuestID\n  LastUpdatedUtc?: string;\n}\n\ninterface UserQuestCycleState {\n  CycleID?: string;\n  CycleStartUtc?: string; // current window start, UTC\n  CycleEndUtc?: string; // current window end, UTC\n  Quests?: Record<string, UserQuestProgress>; // key = QuestID, THIS window only\n  ClaimedGroupCompletionIDs?: string[]; // CompletionIDs already claimed this window\n}\n\ninterface UserQuestProgress {\n  QuestID: string;\n  Status: \"Active\" | \"Completed\" | \"Claimed\" | \"Expired\";\n  ActivatedAtUtc?: string | null;\n  CompletedAtUtc?: string | null;\n  ClaimedAtUtc?: string | null;\n  Objectives?: Record<string, UserQuestObjectiveProgress>; // key = ObjectiveID\n}\n\ninterface UserQuestObjectiveProgress {\n  ObjectiveID: string;\n  CurrentValue: number;\n  Completed: boolean;\n  CompletedAtUtc?: string | null;\n}\n```\n\n**Lazy initialization** (`Quest.cs` `RefreshQuestCycles` / `CreateQuestProgressFromDefinition`):\na quest's `UserQuestProgress` (and each objective's `UserQuestObjectiveProgress`)\nis created only the first time progress is reported for it — the server does\n**not** pre-populate every configured quest/objective with zeros. A quest absent\nfrom `Cycles[cycleID].Quests` (or `PermanentQuests`) simply has zero progress on\nevery objective; render it as `\"Active\"`, not as an error or \"unknown\" state.\n`Expired` is only ever set for cyclic quests (never for permanent quests) and\nonly via the same lazy path — in practice you will see `Active` → `Completed` →\n`Claimed` for anything you've touched; a truly stale quest from a rolled-over\ncycle is simply absent (the whole cycle bucket gets replaced on rollover, see\nbelow), not flagged `Expired` in current code paths.\n\n---\n\n## Config: QuestDefinitions\n\nReturned by `getQuestDefinitions()`; cached via\n`client.data.config.getSection<QuestDefinitions>(\"Quest\")`.\n\n```ts\ninterface QuestDefinitions {\n  Cycles?: Record<string, QuestCycleDefinition>; // key = CycleID\n  Quests?: Record<string, QuestDefinition>; // key = QuestID\n  Presets?: QuestPresetRegistry; // reusable blocks, one registry per QuestDefinition block\n}\n```\n\n**Quests arrive already assembled.** The config is *authored* compactly — a field left unset on a\nquest comes from the preset bound to that block — but the backend resolves it once when it\nmaterializes the title config, so what `getQuestDefinitions()` returns already has every quest's\nblocks filled in. `Presets` rides along for editors; a game client never merges anything.\n\nAssembled is not the same as flattened: the **shape** stays blocked. A quest's name is at\n`Identity.DisplayName`, its cycles at `Linking.CycleIDs`, its window at `Availability.Schedule`,\nits payout at `Reward.Grant`.\n\nA quest is **permanent** iff its `Linking.CycleIDs` is null/empty; otherwise it is\n**cyclic** and belongs to every cycle listed there (a quest can appear\nin more than one cycle definition, each with independent progress/claim state).\nCycle IDs and quest/objective IDs must all be Mongo-safe (no `.` or `$`) —\nthe server rejects unsafe keys outright (`\"Invalid CycleID (mongo-unsafe): …\"`,\n`\"QuestID is mongo-unsafe\"`, etc.); this only matters if you let players or\nremote config drive raw ids into these fields.\n\n---\n\n## QuestCycleDefinition\n\n`Quest.cs` / `QuestDefinitions.cs`. One recurring or one-off \"board\" (dailies,\nweeklies, a scheduled event window, …). Quests do **not** get listed here —\neach `QuestDefinition` points back at the cycle via `Linking.CycleIDs`.\n\n```ts\ninterface QuestCycleDefinition {\n  CycleID?: string;\n  DisplayName?: string;\n  Schedule?: ScheduleSpec; // cycle window/reset — see below\n  Milestones?: Record<string, MilestoneDefinition>; // points-track rungs, key = MilestoneID\n  Phases?: Record<string, QuestPhaseDefinition>;    // chain phases, only for Schedule.Mode = \"Chained\"\n  Presets?: { Milestones?: PresetBinding };         // cycle-level preset wiring (Core/Presets)\n  AssetPaths?: Record<string, string>;\n  CustomParams?: Record<string, string>;\n  Gate?: SegmentGate; // audience gate for the whole cycle; ANDed with each quest's own Gate\n  PointsToken?: EventTokenDefinition; // global caps/burn for the points track (see below)\n  GroupCompletions?: Record<string, QuestGroupCompletionDefinition>; // key = CompletionID\n}\n```\n\nBackend default when a cycle is authored without an explicit `Schedule`:\n`Mode: \"Cyclic\"`, `Cyclic: {}` (i.e. daily calendar reset) —\n`QuestCycleDefinition.Schedule` in `QuestDefinitions.cs`.\n\n---\n\n## QuestDefinition\n\nOnly the ID lives at the root; everything else is a named block, exactly like\n`CharacterDefinition` (`Identity` / `Classification` / `Unlock` / `Stats` / …).\n\n```ts\ninterface QuestDefinition {\n  QuestID?: string;\n  Identity?: QuestIdentity;\n  Linking?: QuestLinking;\n  Availability?: QuestAvailability;\n  Objectives?: Record<string, QuestObjectiveDefinition>; // key = ObjectiveID; ALL must complete\n  Reward?: QuestReward;\n  Presets?: QuestPresetBindings; // one binding per block — see Presets\n}\n\n/** Display part — analogous to CharacterIdentity. */\ninterface QuestIdentity {\n  DisplayName?: string;\n  Description?: string;\n  SortOrder?: number; // lower = earlier in UI; default 0\n  AssetPaths?: Record<string, string>; // task icon and other client assets\n  CustomParams?: Record<string, string>; // passed to the client untouched\n}\n\n/** Links — analogous to CharacterClassification. */\ninterface QuestLinking {\n  CycleIDs?: string[]; // null/empty => permanent; else one entry per cycle it appears in\n  GroupID?: string;    // plain label: UI sections + QuestGroupCompletionDefinition matching\n  PhaseIDs?: string[]; // chain phases this quest lives in; empty = all\n  RequiredQuestIDs?: string[]; // prerequisite QuestIDs — see below\n  PrerequisiteMode?: \"BlockProgressAndClaim\" | \"BlockClaimOnly\"; // default BlockProgressAndClaim\n}\n\n/** Access rules — analogous to CharacterUnlock. */\ninterface QuestAvailability {\n  Schedule?: ScheduleSpec; // per-quest unlock window; unset = the cycle's window (see below)\n  AccrueProgressWhenLocked?: boolean; // default false — see per-quest schedule section\n  Gate?: SegmentGate; // ANDed with the cycle's Gate\n  Limits?: LimitSpec; // per-source caps on POINTS grants only (not on objective progress)\n}\n\n/** Claim payout: the grant plus points into the cycle track. */\ninterface QuestReward {\n  Grant?: ResourceGrant; // claimed via claimQuestReward\n  PointsReward?: number; // points into the cycle's track on claim; ignored for permanent quests\n}\n```\n\nThere is **no group entity.** `Linking.GroupID` is a plain string: it groups quests into UI\nsections and it is what `QuestGroupCompletionDefinition` matches on. Nothing has to declare it,\nand nothing inherits through it.\n\nIn the **stored** config every block, and every field inside it, is optional in the strong sense —\nabsent means \"take it from the preset bound to this block\" (see\n[Presets](#presets--authoring-n-days--m-tasks-without-nm-copies)). By the time this reaches a\nclient the backend has already assembled them.\n\n`PrerequisiteMode` (`QuestDefinitions.cs` comment, verbatim intent):\n\n| Mode                              | Effect on `RequiredQuestIDs`                                                                                                                            |\n| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `BlockProgressAndClaim` (default) | The quest does not start accruing progress at all until every listed prerequisite reaches `Completed`/`Claimed`; consequently it also can't be claimed. |\n| `BlockClaimOnly`                  | Progress accrues immediately; only the final reward claim is blocked until prerequisites are met.                                                       |\n\nA prerequisite is looked up \"where its own progress lives\": permanent →\n`PermanentQuests`; cyclic → the same `cycleID` if the prerequisite also belongs\nto it, otherwise the prerequisite's own first `Linking.CycleIDs` entry\n(`ArePrerequisitesMet`, `Quest.cs`). Empty/null `RequiredQuestIDs` = no gating.\n\n---\n\n## Chains — a cycle that runs phases one after another\n\nSet the cycle's `Schedule.Mode` to `\"Chained\"` and fill `Phases`. The chain starts at\n`Schedule.Chain.AnchorUtc`, plays its phases in `Order`, then repeats (`MaxCycles`, pauses).\n\n```ts\ninterface QuestPhaseDefinition {\n  PhaseID?: string;        // unique within the chain; referenced by QuestLinking.PhaseIDs\n  Order?: number;          // position within one full pass (0, 1, 2...)\n  DurationSec?: number;    // how long the phase stays open\n  ClaimGraceHours?: number;// extra claim window after it ends\n  DisplayName?: string;\n  AssetPaths?: Record<string, string>;\n  CustomParams?: Record<string, string>;\n  Gate?: SegmentGate;                                 // AND-ed with cycle gate and quest gate\n  Milestones?: Record<string, MilestoneDefinition>;   // null = the cycle's ladder is used\n  Presets?: { Milestones?: PresetBinding };\n  PointsToken?: EventTokenDefinition;                 // null = the cycle's token\n}\n```\n\nThree rules worth knowing before designing one:\n\n- **Every phase owns its progress.** The points-track address includes the instance key, and for\n  a phase that key is `chain:{cycleIndex}:{phaseID}`. So week 2 starts from zero points with its\n  own claimed-milestone list — it never inherits week 1. The cycle's quest state resets at a phase\n  boundary exactly like it resets at midnight for a `Daily` cycle.\n- **Unset phase content falls back to the cycle.** Eight identical weeks are eight phases with\n  only `Order`/`DurationSec` filled — not eight copies of the milestone ladder. The exception is an\n  *empty* (not absent) `Milestones` object: that explicitly means \"no milestones in this phase\".\n- **A `Chained` cycle with no phases never activates.** There is nothing to resolve, so the whole\n  cycle stays closed and its quests never progress.\n\nBind a quest to specific phases with `Linking.PhaseIDs` (empty = every phase). It gates\nboth progress and claiming — a week-2 quest cannot be claimed during week 1, in single and batch\nclaims alike. `PhaseIDs` is the direct way to say \"this quest belongs to week two\"; the quest's own\n`Availability.Schedule` with a `Relative` window stays for staged unlocking *within* one phase\n(\"Day N\").\n\n`GetUserQuestState` reports the live phase on each track: `PointsTracks[cycleID].PhaseID` and\n`.CycleIndex` (both absent/0 for a plain cycle) alongside `CycleStartUtc`/`CycleEndUtc` of that\nphase — enough to render \"Week 2 of 8\" and a countdown.\n\n### Milestone presets\n\n`QuestDefinitions.Presets.Milestones` is a registry of reusable `MilestoneSet`s keyed by PresetID —\nthe one preset block that belongs to cycles and phases rather than to quests. A cycle or a phase\nreferences one through `Presets.Milestones` (`PresetBinding`): the preset is the base, the inline\n`Milestones` dictionary overrides or adds by MilestoneID, and `Remove` drops keys. No PresetID ⇒\ninline only. An unknown PresetID silently falls back to inline — it never wipes the entity's own\nladder. Everything else about presets is in the next section.\n\n---\n\n## Presets — authoring N days × M tasks without N×M copies\n\nA seven-day event of six tasks a day is 42 quests that differ in three numbers. One mechanism\nexists so the config says that once instead of 42 times, and it is the **same one Character\nuses**: a registry of reusable blocks plus a binding per block. There is no second mechanism —\nno group entity, no chassis, no inheritance chain. It is **authoring-side only**: the backend\nresolves it at config load and everything downstream sees ordinary assembled quests.\n\n**The one rule:** *unset = take it from the preset, set = final.* A field that is absent takes its\nvalue from the preset bound to that block; a field that is present — **including `0`, `false` and\n`[]`** — wins and is never overwritten. That asymmetry is deliberate: \"this quest gives no points\"\n(`Reward.PointsReward: 0`) has to survive against a preset that grants 30.\n\n```ts\n/** Registry: one dictionary per block, each mirroring the same-named QuestDefinition block. */\ninterface QuestPresetRegistry {\n  Milestones?: Record<string, MilestoneSet>; // cycles and chain phases only\n  Linking?: Record<string, QuestLinking>;\n  Availability?: Record<string, QuestAvailability>;\n  Reward?: Record<string, QuestReward>;\n  Objectives?: Record<string, Record<string, QuestObjectiveDefinition>>; // inner key = ObjectiveID\n}\n\n/** Wiring: one binding per block, exactly like CharacterDefinition.Presets. */\ninterface QuestPresetBindings {\n  Milestones?: PresetBinding; // on a cycle / phase, not on a quest\n  Linking?: PresetBinding;\n  Availability?: PresetBinding;\n  Reward?: PresetBinding;\n  Objectives?: PresetBinding; // merges by ObjectiveID; `Remove` drops preset entries\n}\n```\n\n**Bindings are independent.** Take the schedule from one preset, the reward from another, and\nwrite the objectives inline — the blocks don't know about each other. Precedence inside one\nblock is just two layers:\n\n```\nquest's own field → the preset bound to that block → engine default\n```\n\n**`Identity` has no preset on purpose.** A quest's name and sort order are unique to it, and\n`Description` — the only field that is ever shared — is displayed by no client, so a registry for\nthis block added a binding to every quest and carried nothing. Write Identity inline.\n\nSingle-object blocks (`Linking` / `Availability` / `Reward`) merge **field by field**. `Objectives` merges **by ObjectiveID**, and inside a matched objective the same\nunset-takes-from-preset rule applies — that is the piece that pays for itself: the preset says\n*how* an objective advances, the quest restates only what differs.\n\n```jsonc\n// preset: how \"make N moves\" works — written once\n\"Presets\": { \"Objectives\": { \"moves\": {\n  \"task\": { \"Source\": \"SystemEvent\", \"TargetValue\": 15,\n            \"Triggers\": [{ \"SourceType\": \"BoardTileLanding\" }] } } } }\n\n// day 5's quest: name and target are all that is unique\n\"Quests\": { \"e7_d5_moves\": {\n  \"Identity\": { \"DisplayName\": \"Day 5. Make 35 moves\", \"SortOrder\": 501 },\n  \"Presets\": {\n    \"Linking\":      { \"PresetID\": \"e7\" },      // cycle + group label, shared by all 42\n    \"Availability\": { \"PresetID\": \"e7_d5\" },   // \"opens 4 days after the event starts\"\n    \"Reward\":       { \"PresetID\": \"e7_d5\" },   // day-5 payout, shared by that day's 6 tasks\n    \"Objectives\":   { \"PresetID\": \"moves\" }\n  },\n  \"Objectives\": { \"task\": { \"TargetValue\": 35 } }  // triggers survive — only the number changes\n}}\n```\n\nThree things that bite if you don't know them:\n\n- **The dictionary key is the ID.** A quest or objective written without `QuestID` /\n  `ObjectiveID` takes it from its key. In the compact form it is easy to omit, and an objective\n  with no ID used to be skipped silently — the quest looked configured and never moved.\n- **An unknown PresetID falls back to inline**, it never wipes the block. A typo therefore shows\n  up as a quest with a missing window or a missing reward, not as an error at load.\n- **`Remove` on `Presets.Objectives`** is the only way to take a preset objective away for a\n  single quest.\n\n---\n\n## QuestObjectiveDefinition + progress aggregation\n\n```ts\ninterface QuestObjectiveDefinition {\n  ObjectiveID?: string;\n  Source?: \"ClientApi\" | \"ServerApi\" | \"SystemEvent\"; // what advances it; default ClientApi\n  MaxProgressPerCall?: number; // ClientApi BAN threshold (not a clamp); 0/absent = no check\n  MetricID?: string; // ClientApi/ServerApi only: the metric key reported against\n  Triggers?: TriggerSource[]; // SystemEvent only: in-game events that advance it\n  TargetValue?: number; // default 1; required value to complete\n  AggregationMethod?: string; // \"Sum\" | \"Maximum\" | \"Minimum\" | \"Last\"; default \"Sum\"\n}\n```\n\n`Source` selects **which field is read** — they are mutually exclusive:\n\n| Source        | Advanced by                                     | Field read   |\n| ------------- | ----------------------------------------------- | ------------ |\n| `ClientApi`   | the game calling `addQuestProgress(MetricID, v)` | `MetricID`   |\n| `ServerApi`   | a CloudCode script calling `server.AddQuestProgress(MetricID, v)` | `MetricID` |\n| `SystemEvent` | the backend itself, on in-game events           | `Triggers`   |\n\n`addQuestProgress` reaches **only** `ClientApi` objectives; a `MetricID` with no\nmatching `ClientApi` objective anywhere in the catalog is rejected outright\n(`\"MetricID not allowed for ClientApi\"`).\n\n### `Triggers` — SystemEvent objectives\n\n`Triggers` is the shared `TriggerSource` used by `EventContent.TokenSources`\n(TimedEvent) and `LeaderboardDefinition.ScoreSources`: an event type plus\nfilters, with `BaseWeight` as the progress step per fire. The list is OR-ed\n(first match wins). Empty/absent ⇒ the objective never advances.\n\nThe backend emits these event types into quests — anything else in\n`EventTokenSourceType` never reaches a quest (use `ClientApi` for\nclient-observed actions like watching an ad):\n\n`BoardTileLanding`, `BoardPassStart`, `BoardAttack`, `BoardRaid`, `BoardBuild`,\n`BoardStageComplete`, `BoardSpecialComplete` (GameLoop) · `StorePurchase`\n(`Store.Purchase` / `PurchaseBatch`, multiplier = purchase count) ·\n`MarketplaceSell` / `MarketplaceBuy` (settlement, **acting player only**) ·\n`QuestComplete` (`ClaimQuestReward`, for meta-quests) · `DailyLogin` (first login of a UTC day —\ndeduped at login, so ten re-entries in one evening count as one day) · `CurrencySpent`\n(`ResourceService`, on the applied consume; multiplier = **amount spent**) · `LootboxOpened`\n(multiplier = boxes opened in the call) · `LeaderboardRankReward` (fired when a rank reward is\nactually claimed, not while the standing changes) · `IapPurchase` (`PurchaseV2`, after the receipt\nis verified and the goods granted; multiplier = units granted — **also fires on subscription\nauto-renewals** from the store callback, tagged `Renewal: \"true\"`) · `CryptoDeposit` / `CryptoWithdraw`\n(deposit credited / withdrawal **confirmed on chain** — not on the request, which may never land;\nmultiplier = 1 operation) · `CryptoSpent` (crypto consumed in-game; multiplier = amount) ·\n`CurrencyEarned` / `CryptoEarned` (`ResourceService`, on the applied **grant**, premium tiers\nincluded; multiplier = **amount granted**).\n\nTwo of these carry an *amount* in the multiplier rather than a count, which makes\n`ScaleWithRollMultiplier` the switch between two different goals:\n\n| Source | `true` | `false` |\n| ------ | ------ | ------- |\n| `CurrencySpent` | \"spend 100 coins\" | \"make 100 separate spends\" |\n| `CryptoSpent` | \"spend 100 tokens\" | \"make 100 separate spends\" |\n| `CurrencyEarned` | \"earn 1000 coins\" | \"receive coins 1000 times\" |\n| `CryptoEarned` | \"earn 100 tokens\" | \"receive tokens 100 times\" |\n| `LootboxOpened` | \"open 15 chests\" (one call of 15 counts fully) | \"open a chest 15 times\" |\n| `IapPurchase` | \"buy 5 units\" (a x5 pack counts fully) | \"make 5 separate purchases\" |\n\nSoft currency, crypto and real money are three **separate** sources on purpose: a goal like\n\"spend 100\" must not be closeable by coins one day and by tokens or dollars the next. If a title\nstores crypto in minimal (wei-like) units, set `ScaleWithRollMultiplier: false` on `CryptoSpent`\nand count operations — the amount would otherwise be astronomically large.\n\n`Params` filters the matcher actually checks: `StorePurchase` → `OfferID`;\n`QuestComplete` → `QuestID`, `CycleID`; `Marketplace*` → `CatalogID`, `ItemID`,\n`OfferType`; `CustomAction` → `ActionName`; `CurrencySpent` → `CurrencyID`;\n`LootboxOpened` → `LootboxID`; `IapPurchase` → `ProductID`, `Store`, `Renewal`\n(`\"true\"` = subscription auto-renewal, `\"false\"` = the player bought it by hand; omit to count\nboth — money was paid either way);\n`CryptoDeposit` / `CryptoWithdraw` → `CurrencyID`, `NetworkID`; `CryptoSpent` → `CurrencyID`;\n`CurrencyEarned` / `CryptoEarned` → `CurrencyID`, `Origin`\n(`\"Gameplay\"` = only what the game paid out, `\"RewardClaim\"` = only quest/milestone/rank/season/daily\npayouts, omit to count both — a goal like \"earn 1000 coins\" is otherwise partly closed by other\nquests' rewards);\n`LeaderboardRankReward` → `LeaderboardID`, `Rank`\n(exact match — \"first place\" is `Rank: \"1\"`; for \"top 3\" declare three sources or omit `Rank`).\nAny other key is stored but ignored.\n\nSet `ScaleWithRollMultiplier: false` on a quest trigger unless you *want* the\nboard's roll multiplier to inflate the step — otherwise \"win 3 raids\" closes on\na single x3 raid.\n\n`SystemEvent` progress is applied **after** the handler succeeds and returns on\nthat response's envelope as `QuestProgress: QuestProgressUpdate[]` (absent when\nnothing moved). The guarantee is at-most-once: the game action is already\ncommitted, so a failure here loses the event rather than rolling the action back.\n\nAggregation (`ApplyAggregation`, `Quest.cs`), given the objective's current\n`CurrentValue` and the incoming call value:\n\n| Method                   | New value                                                                                |\n| ------------------------ | ---------------------------------------------------------------------------------------- |\n| `Sum` (default)          | `current + incoming`, clamped to `long.MaxValue` on overflow; `incoming <= 0` is a no-op |\n| `Maximum`                | `max(current, incoming)`                                                                 |\n| `Minimum`                | `incoming` if `current == 0`, else `min(current, incoming)`                              |\n| `Last` (or unrecognized) | `incoming` (last-write-wins)                                                             |\n\nAfter aggregation, if `TargetValue > 0` the new value is clamped to\n`TargetValue` (progress bars never overshoot 100%); if `TargetValue <= 0` there\nis no cap. An objective is marked `Completed` once\n`(TargetValue <= 0 && newValue > 0) || newValue >= TargetValue`. A quest becomes\n`\"Completed\"` once **every** objective the player has a progress record for is\n`Completed` **and** every objective in the definition has a progress record —\ni.e. an objective with zero recorded progress blocks completion (it's absent\nfrom the player's `Objectives` map, so the `All(...)` check in\n`EnsureQuestObjectivesAndCompletion` fails for it).\n\n`MaxProgressPerCall` guards two different things depending on\n`AggregationMethod`:\n\n- If **any** matching `ClientApi` objective for the `MetricID` has\n  `MaxProgressPerCall > 0`, the server compares the **raw** `ProgressValue` you\n  sent against the (minimum across matches) cap **before** any clamping. If the\n  raw value exceeds it, the call is rejected **and the player is banned**\n  (`service.BanUser(...)`, fire-and-forget) with error `\"User banned: Value\nexceeds MaxValuePerCall\"`. This is a hard anti-abuse trip-wire, not a soft\n  clamp — never let client code send inflated values \"to be safe.\"\n- Only for objectives using `Sum` aggregation is the value additionally\n  clamped to `MaxProgressPerCall` before summing (defense in depth; irrelevant\n  once the ban-check above has already passed, since raw ⇐ cap by that point).\n\n---\n\n## Prerequisites (`RequiredQuestIDs`)\n\nSee the `PrerequisiteMode` table above. Enforcement points in `Quest.cs`:\n\n- **Progress accrual** (`AddQuestProgress` internal helper): for permanent\n  quests and for each cycle a cyclic quest belongs to, prerequisites are\n  checked (only in `BlockProgressAndClaim` mode) before the quest's\n  `UserQuestProgress` is even created/updated for that call.\n- **Claim** (`ClaimQuestReward` / batch): `ArePrerequisitesMet(...)` is checked\n  unconditionally (both modes gate the claim) — error\n  `\"Prerequisite quests are not completed\"`.\n\n---\n\n## Cycle schedule resolution\n\n`QuestCycleDefinition.Schedule` is a `ScheduleSpec` (`_shared/ScheduleModels.ts`\n/ `Core/Scheduling`), the same primitive every other module uses. For Quest,\n`RefreshQuestCycles` resolves it via `ScheduleResolver.ResolveActive(...)`\ninto a `[CycleStartUtc, CycleEndUtc)` window per the active `Mode`:\n\n- **`Cyclic`** (the practical default for dailies/weeklies): `Cyclic.Reset` picks\n  the calendar cadence — `Hourly`/`Daily`/`Weekly` (always **Monday** start)/`Monthly`\n  (always the **1st**)/`Yearly` are calendar-aligned in **UTC**, reset time is\n  **always 00:00:00 UTC** and is not configurable. `FixedInterval` instead repeats\n  every `Cyclic.IntervalSeconds` seconds from `Cyclic.AnchorUtc` (default anchor\n  `2026-01-01T00:00:00Z`, default interval 86400s if unset/≤0); an optional\n  `PauseBetweenCyclesSec` inserts a dead gap after each active window during\n  which `CanEarn` is `false` (`IsInPause = true`) but the window has still\n  technically \"ended\" — new progress does not accrue during the pause, though\n  already-completed quests remain claimable (claims are never earn-gated).\n- **`Scheduled`**: one fixed `[StartUtc, EndUtc]` window; `ClaimGraceHours`\n  extends claimability past `EndUtc` without extending earning (unless\n  `AllowEarningAfterEnd` is set).\n- **`AlwaysOn`**: always active, no end.\n- Any other/inactive resolution (e.g. `Triggered`, or `spec.IsActive === false`)\n  makes `ComputeCycleWindowUtc` **degrade to a plain UTC calendar day**\n  `[today 00:00, tomorrow 00:00)` as a fallback — don't configure `Triggered` on\n  a quest cycle expecting anything else.\n\n**Rollover behavior** (`RefreshQuestCycles`, called automatically by\n`getUserQuestState({autoRefreshCycles: true})` — the default — and before every\nmutating Quest action): when the resolved `[start, end)` no longer matches the\nstored `CycleStartUtc`/`CycleEndUtc`, the entire `UserQuestCycleState` for that\ncycle is **replaced with a brand-new, empty one** (`Quests: {}`,\n`ClaimedGroupCompletionIDs` reset) — there is no partial carry-over of\nin-progress quests into the new window. Cycles removed from config entirely are\ndeleted from the player's state on the next refresh. If the window has **not**\nrolled over, the refresh instead walks the player's **existing** quest progress\nrecords (only ones already started) and re-evaluates `Completed` status against\ncurrent config — it does not add new objectives to already-tracked quests.\n\n---\n\n## Per-quest schedule (\"staged unlock\" / Achievements)\n\n`QuestAvailability.Schedule` is an **independent, optional** `ScheduleSpec` layered\non top of the cycle's own schedule — this is how \"Day 2 unlocks 24h after Day 1\"\nor an \"Achievements\" track with a `ScheduleSpec`-driven unlock (rather than a\nliteral day-count) is built, with any number of stages at any interval, not just\nliteral days:\n\n- `Schedule` absent → the quest simply inherits its cycle's window; earning and\n  claiming follow the cycle's own `CanEarn`/`CanClaim`.\n- `Schedule` present → resolved via `ResolveQuestInstance`, which passes the\n  **cycle's** resolved instance as the `parent` for `Relative`-mode windows —\n  so a per-quest `Relative` schedule with `OffsetSecondsFromParentStart` is\n  \"N seconds after this cycle instance started,\" letting one `Cyclic` cycle\n  auto-repeat a whole staged sequence without hardcoded absolute dates.\n- `Availability.AccrueProgressWhenLocked` (default `false`) decides what happens **while**\n  the cycle's window is open but the quest's own window is not: `false` means a\n  locked stage accrues **zero** progress (a true lock — progress reported for\n  its metric while locked is simply dropped for that quest); `true` means\n  progress accrues the whole time the cycle is active, but the **reward claim**\n  is still gated on the quest's own `CanClaim` — so you can pre-accrue \"Day 3\"\n  progress while day 3 is still locked, and only the payout waits.\n\nEarning gate precedence for a cyclic quest, all of which must pass\n(`AddQuestProgress` internal helper): cycle `earningCycles` membership (cycle\nitself must be `CanEarn`, i.e. not `IsInPause`) → quest's own\n`IsQuestEarnable` (`AccrueProgressWhenLocked` bypasses this specific check) →\n`QuestGatesPass` (cycle `Gate` AND `Availability.Gate`) → prerequisites (only in\n`BlockProgressAndClaim` mode).\n\n---\n\n## Points track (\"Achievements\") — the Quest event-token\n\nThis is the mechanism the \"Achievements\" hint in the prompt refers to — it is\nreal and it is exactly the cycle's points track, not a separate module. Russian\ncomments in `Quest.cs` literally label it «Достижения» (Achievements).\n\n**How points get earned.** Each cyclic `QuestDefinition.Reward.PointsReward` (points,\nnot currency) is granted **only on claim** of that quest's own reward — via\n`ClaimQuestReward` / `ClaimQuestRewardsBatch`, in the **same atomic transaction**\nas the quest's `Reward` grant. It's `long`, defaults to `0`, and is ignored for\npermanent quests (`isPermanent` quests never touch the points track). A group\ncompletion (below) can **also** add points via its own `PointsReward`, on top of\nwhatever its member quests already contributed individually.\n\n**Where it's addressed.** The points track is backed by a standard\n`EventTokenType.Quest` event token (the same primitive TimedEvent/Leaderboard/\nCoopEvent/Season points tracks use), addressed at\n`EntityID = \"{cycleID}:{instanceKey}\"` where `instanceKey` comes from\n`ScheduleResolver`'s resolution of the **cycle's** schedule (`\"all\"` if the\ncycle has no resolvable instance). Because the instance key changes when the\ncycle's schedule rotates to a new window, **the points balance and claimed-milestone\nlist reset automatically on cycle rollover** — there is no explicit\n\"reset points\" step; it's a natural consequence of the address changing.\n\n**Where it lives in state.** `UserQuestState` does **not** carry the points\nbalance — it lives in `UserDataDocument.EventToken.Quest[entityID]`\n(`UserEventTokenProgress`: `Balance.Current`/`Balance.TotalEarned`,\n`Milestone.ClaimedIDs`). `GetUserQuestState` additionally projects a **read-only\nsnapshot** per cycle into `GetUserQuestStateResponse.PointsTracks[cycleID]`\n(`QuestPointsTrackView`) so the client doesn't have to know the composite key —\nthe TS SDK's `patchQuestPointsTracks` writes this into\n`client.data.user.state.EventToken.Quest[\"{cycleID}:{instanceKey}\"]` for you,\nand `client.data.user.getQuestPointsProgress(cycleID)` resolves the composite\nkey back out (`matchesBase`, `util/eventTokenIds.ts`) so you can look it up by\nplain `cycleID`.\n\n```ts\ninterface QuestPointsTrackView {\n  CycleID: string;\n  InstanceKey?: string | null;\n  CycleStartUtc?: string | null;\n  CycleEndUtc?: string | null; // source for a \"resets in\" timer\n  PointsTotalEarned?: number | null; // lifetime points earned this cycle instance\n  PointsCurrent?: number | null; // current balance (== TotalEarned; points are never spent)\n  ClaimedPointMilestoneIDs?: string[] | null;\n}\n```\n\n**Milestones** (`QuestCycleDefinition.Milestones`, keyed by `MilestoneID`) are\nthe shared Core `MilestoneDefinition` primitive\n(`RequiredProgress`, `Rewards`, `BonusRewards`, `SeasonTierRewards`,\n`SortOrder`, `IsFeatured`) — see `_shared/MilestoneModels.ts`. Eligibility is\njudged **only** against `Balance.TotalEarned` on the points token (never\n`Current`, though for Quest the two happen to always be equal since points are\nonly ever granted, never spent) — `EventTokenService.ComputeMilestoneClaim`:\nfails with `\"Not enough earned. Have: X, need: Y.\"` if under threshold, or\n`\"Milestone already claimed.\"` if `MilestoneID` is already in `ClaimedIDs`.\nClaiming pushes the id into `ClaimedIDs` via a Mongo `$push` guarded by a\n`$nin` filter (OCC — a concurrent duplicate claim loses the race cleanly). The\nmilestone's reward itself runs through the shared `MilestoneRewardResolver`\n(same resolver Leaderboard/TimedEvent/CommunityChest/Referral use), which\napplies the title's progression-multiplier overlay\n(`cfg.Reward.MilestoneRewardMultiplier`) if configured — so the actual payout\ncan exceed the base `Rewards` grant; read it from the response, don't assume\nface value.\n\n**Caps** on points grants (`BuildPointsGrantContext`): **global** caps come from\n`QuestCycleDefinition.PointsToken` (an `EventTokenDefinition` — `DailyEarnCap`,\n`MaxBalance`, `MaxPerGrant`); **per-quest-source** caps/cooldown come from\n`QuestAvailability.Limits` (a `LimitSpec`, mapped as `DailyWeightCap` →\nper-source daily cap, `DailyCap` → per-source daily trigger count,\n`CooldownSeconds` → per-source cooldown). Per-source limits only apply in the\n**single** `ClaimQuestReward` path — the batch claim path\n(`ClaimQuestRewardsBatch`) only enforces the cycle's **global** `PointsToken`\ncaps against the **summed** batch amount per address, since per-source limits\ndon't make sense once amounts from multiple quests are merged into one token\noperation. If a cap fully exhausts the grant, `EventTokenService.ComputeGrant`\ncan reduce the amount to `0`, which surfaces as a failed points portion inside\nthe resource operation — always read granted amounts from the response, never\nassume the full `PointsReward` landed.\n\n---\n\n## Group-completion (grand reward) math\n\n`QuestCycleDefinition.GroupCompletions[completionID]` (`QuestGroupCompletionDefinition`):\n\n```ts\ninterface QuestGroupCompletionDefinition {\n  CompletionID?: string;\n  GroupID?: string; // must match QuestLinking.GroupID on member quests\n  RequiredCompletedQuests?: number; // 0 = \"ALL quests in this group, per current config\"\n  Gate?: SegmentGate; // ANDed with the cycle's Gate\n  Reward?: ResourceGrant;\n  PointsReward?: number; // additional points into the SAME cycle points track; 0 = none\n}\n```\n\n`ClaimGroupCompletionReward` computes eligibility **live**, at claim time, by\nscanning the **current** `QuestDefinitions.Quests` for every quest that (a)\nlists this `cycleID` in its `Linking.CycleIDs` and (b) has `Linking.GroupID` equal to the\ncompletion's `GroupID` — that's `totalGroupQuests`. Of those, it counts how many\nhave reached `Status === \"Completed\"` **or** `\"Claimed\"` in the player's current\ncycle state — that's `completedGroupQuests`. The required threshold is\n`RequiredCompletedQuests` if `> 0`, otherwise `totalGroupQuests` (i.e. every\ngroup quest currently in config). Failure modes:\n\n- `RequiredCompletedQuests` unset and the group is empty/misconfigured (no\n  quests currently reference that `GroupID` in that cycle) →\n  `\"No quests configured for this group\"` (required resolves to `0`, which is\n  rejected outright — you can never claim an empty group).\n- `completedGroupQuests < required` → `\"Not enough completed quests for this\ngroup\"`.\n- Already in `cycle.ClaimedGroupCompletionIDs` → `\"Group completion already\nclaimed\"` (checked in-memory before the DB round-trip, then re-enforced by an\n  `AnyEq`-negated Mongo filter for the actual OCC guard).\n- `completion.GroupID` blank/whitespace on the definition itself →\n  `\"Group completion has no GroupID\"` (a config error, not a player error).\n\nBecause the scan is **live against current config**, removing a quest from the\ngroup (or from the cycle) between when a player completed it and when they\nclaim the group reward can change `totalGroupQuests`/`completedGroupQuests` —\nthere's no snapshot of \"the group as it was.\" The response echoes\n`CompletedGroupQuests` and `RequiredGroupQuests` (the resolved threshold, not\nthe raw config field) so the client can show \"3 / 3\" without recomputing\nanything.\n\n---\n\n## `AddQuestProgress` server-side rules\n\nFull request-to-mutation path (`QuestV2.AddQuestProgress` public entry point +\nthe internal shared helper), summarized because several rules only make sense\ntogether:\n\n1. `MetricID` required; must match at least one `ClientApi`-sourced objective\n   in the **entire** quest catalog, or the call fails with `\"MetricID not\nallowed for ClientApi\"` before touching the database.\n2. `ProgressValue` (`long`) must be `>= 0`.\n3. If any matching objective declares `MaxProgressPerCall > 0`, the **raw**\n   value is checked against the smallest such cap across all matches; exceeding\n   it **bans the account** (see the objective section above) rather than\n   clamping — this is a hard security control, not UX guidance.\n4. The (possibly `Sum`-clamped) value then fans out to **every** quest/objective\n   pair across **every currently-earning cycle and every permanent quest**\n   whose objective's `Source === \"ClientApi\"` and `MetricID` matches — one\n   `addQuestProgress` call can move several quests (even across different\n   cycles) simultaneously if they all listen to the same metric.\n5. Each matched quest only advances if it isn't already `Completed`/`Claimed`\n   (`ApplyToQuestInstance` early-returns `false` otherwise) — so calling\n   `addQuestProgress` for an action a player keeps performing after a quest is\n   done is safe and a no-op for that quest.\n6. The response's `Updates[]` (`QuestProgressUpdate`) lists **only the\n   quest/objective pairs that actually changed** this call — an objective whose\n   `Sum` increment was clamped to `0` (already at `TargetValue`) or a locked\n   quest that accrued nothing produces no entry.\n7. This whole path calls `RefreshQuestCycles` first (unless the internal helper\n   is invoked with `ensureCyclesUpToDate: false`, which the public\n   `AddQuestProgress` action does to avoid double-refreshing) — so cycle\n   windows are always current before progress is evaluated.\n\n---\n\n## Idempotency, atomicity, batch limits\n\n- **Idempotency keys** (`ResourceService.ResolveRelatedEntityID`, stable ID\n  patterns from `Quest.cs`): single quest claim →\n  `\"{questID}\"` (permanent) or `\"{questID}_{cycleStartUtc:yyyyMMddHHmmss}\"`\n  (cyclic — so the **same** quest claimed again after the cycle rolls to a new\n  window is a distinct idempotency key, not a duplicate); milestone claim →\n  `\"{cycleID}_{milestoneID}_{instanceKey}\"`; group completion →\n  `\"{cycleID}_{completionID}_{cycleStartUtc:yyyyMMddHHmmss}\"`. You never\n  construct these yourself — the TS SDK mints its own client-side\n  `RelatedEntityID` (`quest_claim_…`, `milestone_claim_…`, `group_completion_…`,\n  each suffixed with a fresh UUID) purely for its own request-level tracking;\n  the **server-side** idempotency guarantee comes from the stable IDs above\n  plus the OCC filter on each claim, not from the client's `RelatedEntityID`.\n- **Atomicity.** Every claim path (`ClaimQuestReward`, `ClaimMilestoneReward`,\n  `ClaimGroupCompletionReward`, and both batch variants) runs the reward grant\n  and the state-mutating patches (status → `Claimed`, milestone `$push`, group\n  `$addToSet`) inside **one** `ResourceService.ApplyResourceOperationAtomicAsync`\n  call with an `extraFilter` re-asserting the pre-claim condition (e.g. quest\n  `Status == Completed`) — if the grant fails for any reason (insufficient\n  server-side room, a concurrent claim already flipped the filter condition,\n  etc.) the whole transaction rolls back; there is no partially-applied claim.\n- **Resources in batch responses.** For both `ClaimQuestRewardsBatch` and\n  `ClaimMilestoneRewardsBatch`, all included items' rewards are merged into a\n  **single** `ResourceBundle` (`BatchSupport.MergeBundles`) and charged/granted\n  in one call — the merged `ResourceOperation` is attached to only the **first\n  successful** `BatchItemResult.Data.Resources` in the returned array; every\n  other successful item's `Data.Resources` is an **empty** `ResourceOperation`\n  (`new ResourceOperation()`), not a duplicate of the shared one. Don't sum\n  resources across batch items — read them once from wherever they landed (the\n  TS SDK's `applyResourceOperation` is only ever called once, on the first\n  `Resources` it finds, matching this).\n- **Batch size.** `BatchSupport.MaxBatchSize = 50`. Both\n  `claimQuestRewardsBatch` and `claimMilestoneRewardsBatch` accumulate refs from\n  your array only up to 50 (after deduping by `CycleID+QuestID` /\n  `CycleID+MilestoneID`); anything past the 50th valid, deduped entry is\n  **silently dropped** — it never appears in the result array at all, so a\n  `results.length` shorter than your input isn't necessarily an error. Chunk\n  larger sets yourself.\n- **Batch validity filtering happens before charging.** Each item is\n  independently checked (mongo-safety, config existence, gates, schedule\n  window, prerequisites, current `Status`) and rejected into a preset\n  `BatchItemResult` **before** the shared resource operation runs; only\n  surviving items contribute to the merged grant and the combined Mongo filter\n  (`AND` of each item's own OCC filter). That combined filter means: if even\n  one surviving item's condition is no longer true by the time the transaction\n  actually commits (e.g. a race with another request), **the entire merged\n  operation fails** and every surviving item in that batch call reports the\n  same `apply.Error` — \"partial-aware\" describes the **pre-filtering** stage,\n  not protection against a mid-flight race on the shared charge.\n- **Rate limit / lock.** The whole `QuestV2` function uses\n  `RateLimitMilliseconds = 500` (per-IP endpoint throttle) and\n  `LockDurationMilliseconds = 10000` (per-user-action Mongo transaction lock)\n  inside `ClientRun.Execute` — both are backend-side controls independent of\n  the TS SDK's own 600ms client-side throttle guard.\n"
     }
   ]
 }

package/registry/skills/timed-event-system.json

@@ -5,7 +5,7 @@
   "references": [
     {
       "path": "data-model.md",
-      "content": "# Timed-event data model — reference\n\nFull shape of the config (Definitions) and player state, the composite\nevent-token key scheme, the milestone self-heal rule, grace-window math, and\nthe bonus-window model. All of these are **strictly typed in the SDK** —\n`TimedEventDefinitions` and every nested block (`TimedEventDefinition`,\n`ChainedEventDefinition`, `EventContent`, `BonusWindowConfig`,\n`ActiveEventInfo`, …) are exported from `@idosgames/core`, so\n`getDefinitions()` and `getSection<TimedEventDefinitions>(\"TimedEvent\")` give\nyou concrete types, not `unknown`. The schemas keep `.passthrough()`, so a\nfield the backend adds later still round-trips. Field names are PascalCase\n(straight from the backend JSON).\n\nEvery claim in this file traces to a specific backend source line — cited\ninline as `(file:line)` against the iDos_Games_Engine repo.\n\n## Contents\n\n- [Config: TimedEventDefinitions](#config-timedeventdefinitions)\n- [TimedEventDefinition (Scheduled vs Chained)](#timedeventdefinition-scheduled-vs-chained)\n- [EventContent](#eventcontent)\n- [Player state: UserEventTokenProgress](#player-state-usereventtokenprogress)\n- [ActiveEventInfo (getActiveEvents response)](#activeeventinfo-getactiveevents-response)\n- [The composite instance-key scheme](#the-composite-instance-key-scheme)\n- [Grace windows and claim-only instances](#grace-windows-and-claim-only-instances)\n- [Milestone claim rules and the self-heal on read](#milestone-claim-rules-and-the-self-heal-on-read)\n- [Bonus window (Coin-Master-style)](#bonus-window-coin-master-style)\n- [Token sources, matching, and grant math](#token-sources-matching-and-grant-math)\n- [Server-side limits, batching, and idempotency](#server-side-limits-batching-and-idempotency)\n\n---\n\n## Config: TimedEventDefinitions\n\nReturned by `getDefinitions()`; cached via\n`client.data.config.getSection<TimedEventDefinitions>(\"TimedEvent\")`.\n\n```ts\ninterface TimedEventDefinitions {\n  Definitions?: Record<string, TimedEventDefinition>; // key = TimedEventID\n  Settings?: LimitedTimeEventsGlobalSettings;\n}\n\ninterface LimitedTimeEventsGlobalSettings {\n  MaxConcurrentEvents?: number; // config-mistake guard; default 5\n}\n```\n\n(`IDosGamesSDK/API/Client/v2/TimedEvent/Models/TimedEventDefinitions.cs:27-58`)\n\n---\n\n## TimedEventDefinition (Scheduled vs Chained)\n\nOne dictionary holds both kinds; the mode lives in `Schedule.Mode`.\n\n```ts\ninterface TimedEventDefinition {\n  TimedEventID?: string;\n  DisplayName?: string;\n  Description?: string;\n  AssetPaths?: Record<string, string>;\n  Schedule?: ScheduleSpec; // Mode: \"Scheduled\" | \"Chained\"\n  Content?: EventContent; // used when Mode = Scheduled\n  Events?: ChainedEventDefinition[]; // used when Mode = Chained\n  Gate?: SegmentGate; // audience gate; null = everyone\n  CustomParams?: Record<string, string>;\n}\n```\n\n(`TimedEventDefinitions.cs:72-130`)\n\n- **Scheduled**: one fixed window (`Schedule.Scheduled: ScheduledWindow` —\n  `StartUtc`, `EndUtc`, `AllowEarningAfterEnd`, `ClaimGraceHours`). Content\n  lives directly on `Content`.\n- **Chained**: a repeating ordered list of phases (`Events`), timed by\n  `Schedule.Chain: ScheduleChain` (`AnchorUtc`, `MaxCycles`,\n  `PauseBetweenPhasesSec`, `PauseBetweenCyclesSec`). Each phase has its own\n  `Content`. After the last phase, the whole cycle restarts from phase 0\n  (unless `MaxCycles` caps the number of repeats).\n\n```ts\ninterface ChainedEventDefinition {\n  ChainedEventID?: string; // unique within the chain\n  Order?: number; // 0-based position; defines phase sequence\n  DurationSec?: number;\n  Content?: EventContent;\n  ClaimGraceHours?: number; // 0 = no claiming once this phase ends\n  CustomParams?: Record<string, string>;\n}\n```\n\n(`TimedEventDefinitions.cs:138-180`)\n\n`Gate` is the standard `SegmentGate` (Core/Segment) — `Segments`,\n`MinPremiumTier`, `RequiredPremiumIDs`, `MinLevel`/`MaxLevel`, `Countries`,\n`RegisteredWithinDays`, `ActiveWithinDays`, `Experiment`. A player failing the\ngate does not see the event in `getActiveEvents()` and cannot earn or spend\nits tokens — `GrantTokensInternal` re-checks the gate server-side even if a\nstale client tries to call it directly\n(`IDosGamesSDK/API/Client/v2/TimedEvent/TimedEvent.cs:325-329`).\n\n---\n\n## EventContent\n\nShared shape used by both a `Scheduled` event's `Content` and each\n`ChainedEventDefinition.Content`.\n\n```ts\ninterface EventContent {\n  DisplayName?: string;\n  Description?: string;\n  AssetPaths?: Record<string, string>;\n  Category?: string; // free-form UI grouping tag\n  Token?: EventTokenDefinition; // the event token's own config\n  TokenSources?: TriggerSource[]; // whitelist of what earns this token\n  ClaimMode?: \"Instant\" | \"AfterEventEnd\" | \"FeaturedAfterEnd\";\n  Milestones?: Record<string, MilestoneDefinition>; // key = MilestoneID\n  BonusWindow?: BonusWindowConfig; // null = disabled for this event\n}\n```\n\n(`TimedEventDefinitions.cs:192-280`, `Core/Milestone/Models/MilestoneClaimMode.cs:14-36`)\n\n`EventTokenDefinition` (`_shared/EventTokenDefinitionModels.ts`, port of\n`Core/Event/Models/EventTokenModels.cs:399-453`):\n\n```ts\ninterface EventTokenDefinition {\n  DisplayName?: string;\n  AssetPaths?: Record<string, string>;\n  MaxBalance?: number; // 0 = unlimited spendable balance cap\n  MaxPerGrant?: number; // per-grant clamp; default 1000 server-side\n  DailyEarnCap?: number; // 0 = unlimited daily earn total\n  BurnOnEventEnd?: boolean; // default true — balance zeroed at event end\n  BurnConversion?: EventTokenConversion; // optional leftover→currency conversion\n}\n```\n\n`MilestoneDefinition` is the shared Core/Milestone primitive (also used by\nLeaderboard/Quest/CommunityChest/DealOffer):\n\n```ts\ninterface MilestoneDefinition {\n  MilestoneID?: string;\n  DisplayName?: string;\n  AssetPaths?: Record<string, string>;\n  RequiredProgress?: number; // compared against Balance.TotalEarned\n  Rewards?: ResourceGrant; // base reward\n  BonusRewards?: ResourceGrant; // added/scaled in during an active bonus window\n  SeasonTierRewards?: SeasonTierRewardSet; // not used by TimedEvent\n  SortOrder?: number;\n  IsFeatured?: boolean; // gates FeaturedAfterEnd behavior\n}\n```\n\n(`Core/Milestone/Models/MilestoneDefinition.cs` via `_shared/MilestoneModels.ts:125-138`)\n\n`TriggerSource` (shared `_shared/ScheduleModels.ts:83-96`, port of\n`Core/Scheduling/Models/TriggerSource.cs`):\n\n```ts\ninterface TriggerSource {\n  SourceType?: string; // EventTokenSourceType, e.g. \"BoardTileLanding\"\n  BaseWeight?: number; // tokens granted per matching trigger\n  ScaleWithRollMultiplier?: boolean; // multiply BaseWeight by the caller's roll multiplier\n  TileTypeFilter?: string[]; // BoardTileLanding only; empty = any\n  TileIndexFilter?: number[]; // BoardTileLanding only; empty = any\n  ChanceOutcomeFilter?: string[]; // BoardTileLanding Chance tiles only; empty = any\n  OutcomeFilter?: string[]; // checked for every source type; empty = any\n  Params?: Record<string, string>; // CustomAction: ActionName; Marketplace*: CatalogID/ItemID/OfferType\n  Limits?: LimitSpec; // DailyCap / DailyWeightCap / CooldownSeconds\n}\n```\n\n---\n\n## Player state: UserEventTokenProgress\n\nReturned inside `getUserLteState()`'s `Tokens` map and inside each\n`ActiveEventInfo.Progress`.\n\n```ts\ninterface UserEventTokenProgress {\n  Balance?: {\n    Current: number; // spendable balance; rises on grant, falls on spend\n    TotalEarned: number; // lifetime earned in THIS instance; monotonic; milestone math uses this\n    TotalSpent: number; // lifetime spent in this instance; analytics only\n  };\n  Daily?: {\n    Date: string; // UTC date the counters below apply to; lazy-reset on next grant\n    TotalEarned: number;\n    EarnedBySource?: Record<string, number>; // vs TriggerSource.Limits.DailyWeightCap\n    TriggersBySource?: Record<string, number>; // vs TriggerSource.Limits.DailyCap\n    LastTriggerBySource?: Record<string, string>; // vs TriggerSource.Limits.CooldownSeconds; NOT reset daily\n  };\n  Meta?: {\n    JoinedAtUtc?: string; // first grant into this instance's bucket\n    LastEarnedAtUtc?: string;\n  };\n  Milestone?: {\n    ClaimedIDs?: string[];\n    UnlockedIDs?: string[]; // reached but not yet claimable under AfterEventEnd/FeaturedAfterEnd\n  };\n}\n```\n\n(`Core/Event/Models/EventTokenModels.cs:51-179`, mirrored in SDK\n`_shared/EventTokenState.ts:8-38`)\n\nImportant: **spending tokens never affects `TotalEarned`**\n(`EventTokenService.ComputeSpend`, `EventTokenService.cs:311-337` only\ntouches `Balance.Current`/`Balance.TotalSpent`), so a milestone earned and\nthen \"un-afforded\" by spending remains claimable/claimed — milestones track\nlifetime earning, not current balance.\n\n---\n\n## ActiveEventInfo (getActiveEvents response)\n\n```ts\ninterface ActiveEventInfo {\n  Type?: \"Scheduled\" | \"Chained\";\n  TimedEventID?: string;\n  CurrentChainedEventID?: string | null; // null for Scheduled\n  Content?: EventContent | null; // resolved content for the current/ended instance\n  Progress?: UserEventTokenProgress | null;\n  ComputedStartUtc?: string | null;\n  ComputedEndUtc?: string | null;\n  CanEarn?: boolean | null; // tokens can still be granted for this instance\n  CanClaim?: boolean | null; // still inside claim/grace window\n  NextMilestone?: MilestoneDefinition | null; // lowest RequiredProgress not yet in ClaimedIDs\n  BonusWindow?: BonusWindowState | null; // computed; null = no window / disabled\n  CurrentCycleIndex?: number | null; // Chained only\n  CurrentEventOrder?: number | null; // Chained only: 1-based position... (see note)\n  TotalEventsInChain?: number | null; // Chained only\n}\n```\n\n(`IDosGamesSDK/API/Client/v2/TimedEvent/Models/UserTimedEventState.cs:23-78`)\n\nNote: the backend populates `CurrentEventOrder` from\n`ChainedEventDefinition.Order`, which is documented as 0-based\n(`TimedEventDefinitions.cs:148-152`) — the SDK's own doc-comment calling it\n\"1-based\" is aspirational UI framing, not a code guarantee; treat it as \"the\nphase's configured `Order` value\" and don't assume it starts at 1.\n\n`getActiveEvents()` can return **more than one `ActiveEventInfo` for the same\n`Chained` `TimedEventID`** in a single response: the currently active phase,\nplus any phase(s) that already ended but are still inside their\n`ClaimGraceHours` window (`CanEarn: false`, `CanClaim: true`)\n(`TimedEvent.cs:149-169`, `EnumerateEndedInGraceChainInstances`,\n`TimedEvent.cs:801-836`). Disambiguate them by `CurrentCycleIndex` +\n`CurrentChainedEventID`.\n\n---\n\n## The composite instance-key scheme\n\nEvery event **instance** — not just every event — gets its own progress\nbucket, milestone-claimed list, and (for chains) bonus-window timeline. The\nbucket key (`EventTokenAddress.EntityID`, stored under\n`UserDataDocument.EventToken.TimedEvent[EntityID]`) is:\n\n```\nEntityID = \"{TimedEventID}:{InstanceKey}\"\n```\n\n(`TimedEvent.cs:1044-1057`, `BuildTokenAddress`)\n\nWhere `InstanceKey` depends on the resolved mode\n(`Core/Scheduling/Services/ScheduleInstanceKey.cs:14-23`):\n\n| Mode        | `InstanceKey` format           | Example         |\n| ----------- | ------------------------------ | --------------- |\n| `AlwaysOn`  | `\"all\"`                        | `all`           |\n| `Scheduled` | `\"s{yyyyMMddHHmm}\"` (StartUtc) | `s202607010000` |\n| `Chained`   | `\"{cycleIndex}:{phaseID}\"`     | `4:boss_phase`  |\n\nSo a `Scheduled` event's `EntityID` is effectively\n`\"summer_sale:s202607010000\"`, and a `Chained` event's is\n`\"raid_rotation:4:boss_phase\"`. This is why re-running the same\n`TimedEventID` (a new Scheduled window with a different `StartUtc`, or the\nnext chain cycle) starts every player at a fresh `Balance`/`Milestone`\nbucket — nothing carries over, by design.\n\nThe SDK's `UserTimedEventStateResponse.Tokens` map uses these same composite\nkeys. Cache helpers that need to find \"the bucket for this `LteID`, whatever\nits current instance suffix is\" use `matchesBase(key, lteID)`\n(`packages/core/src/util/eventTokenIds.ts:4-6`): a key belongs to a base id\nif it equals it exactly or starts with `\"{lteID}:\"`. `getUserLteState()` is a\nflat dump of every bucket the player has ever touched (including stale\nfinished instances) — don't assume one entry per `LteID`.\n\n---\n\n## Grace windows and claim-only instances\n\nOnce an instance's window ends, tokens can no longer be earned\n(`CanEarn` flips to `false`), but the milestone rewards already reached can\nstill be claimed until a grace deadline:\n\n```\nClaimDeadlineUtc = EndUtc + ClaimGraceHours\n```\n\n- `Scheduled`: `ClaimGraceHours` comes from `Schedule.Scheduled.ClaimGraceHours`\n  (`TimedEvent.cs:728`). `AllowEarningAfterEnd` (also on `ScheduledWindow`)\n  lets earning continue past `EndUtc` if set — independent of the grace\n  window, which only governs _claiming_.\n- `Chained`: `ClaimGraceHours` comes from the specific\n  `ChainedEventDefinition.ClaimGraceHours` (`TimedEvent.cs:718,773,826`) —\n  each phase can have its own grace period. `AllowEarningAfterEnd` is always\n  `false` for chain phases (`TimedEvent.cs:719`) — earning always stops the\n  instant the phase ends.\n- `now > ClaimDeadlineUtc` ⇒ the instance is gone entirely: `ResolveScheduled`\n  / `ScheduleResolver.ResolveChainInstance` return `null`\n  (`Core/Scheduling/Services/ScheduleResolver.cs:127-145,361-406`), and any\n  spend/grant/claim call against it fails with `\"Event not found or not\nactive.\"` / `\"...not in claim window.\"`.\n\n`EnumerateEndedInGraceChainInstances` walks backward through past chain\ncycles (hard-capped at 200 lookback instances,\n`ScheduleResolver.cs:414-484`) collecting every phase whose\n`now ∈ (EndUtc, EndUtc + ClaimGraceHours]`, **only for instances where the\nplayer has existing progress** (`TimedEvent.cs:156-159` — buckets with no\nprogress are skipped, so a phase the player never touched doesn't clutter\nthe active-events list). These are returned with `CanEarn: false,\nCanClaim: true` and must be addressed by their own `CycleIndex` +\n`ChainedEventID` when spending/claiming (`ResolveEventFromArgs`,\n`TimedEvent.cs:672-686`, only takes the explicit-instance path when **both**\n`CycleIndex` and `ChainedEventID` are supplied — omitting either resolves to\nwhatever instance is currently active instead).\n\n---\n\n## Milestone claim rules and the self-heal on read\n\n**Claim gate** (`ClaimMilestone`, `TimedEvent.cs:518-658`, and the batch\npaths mirror this via `CheckMilestoneClaimMode`, `TimedEvent.cs:1767-1775`):\n\n1. The resolved instance must have `CanClaim: true` (inside its window or\n   grace), else `\"Claim window has expired.\"`.\n2. The milestone id must exist in the resolved content's `Milestones`, else\n   `\"Milestone '<id>' not found.\"`.\n3. `Content.ClaimMode` gate:\n   - `Instant` — always allowed once reached.\n   - `AfterEventEnd` — rejected with `\"Milestone can only be claimed after\nevent ends.\"` until `now > EndUtc`.\n   - `FeaturedAfterEnd` — same rejection (`\"Featured milestone can only be\nclaimed after event ends.\"`) but **only** when `MilestoneDefinition.IsFeatured\n=== true`; non-featured milestones under this mode behave like `Instant`.\n4. `EventTokenService.ComputeMilestoneClaim` (`EventTokenService.cs:343-366`):\n   fails with `\"No progress for this event token.\"` if the bucket doesn't\n   exist at all, `\"Not enough earned. Have: {X}, need: {Y}.\"` if\n   `Balance.TotalEarned < RequiredProgress`, or `\"Milestone already\nclaimed.\"` if the id is already in `ClaimedIDs`.\n\n**Self-heal on `GetActiveEvents` read** (`SanitizeMilestoneState`,\n`TimedEvent.cs:1070-1131`, invoked from `BuildActiveEventInfo` at\n`TimedEvent.cs:1143` and staged as background `$pullAll` patches at\n`TimedEvent.cs:112-187`):\n\n- Trigger condition: for the **specific instance bucket being read**, any id\n  present in that bucket's `Milestone.ClaimedIDs` or `Milestone.UnlockedIDs`\n  whose corresponding `MilestoneDefinition.RequiredProgress` is **greater\n  than that same bucket's own `Balance.TotalEarned`** is stale. An id with no\n  matching entry in the resolved content's `Milestones` dictionary is also\n  stripped (nothing to verify it against). The check is\n  `totalEarned >= def.RequiredProgress` per id\n  (`TimedEvent.cs:1076-1080`, local function `Reached`).\n- Why it's safe: `TotalEarned` is monotonically non-decreasing\n  (`EventTokenService.ComputeGrant` only ever increments it,\n  `EventTokenService.cs:226,271,283`), so a milestone legitimately claimed\n  (earned had already reached the threshold _at claim time_) can never later\n  have `TotalEarned` fall back below `RequiredProgress`. The only ids this\n  can strip are ones inconsistent with their own bucket's recorded earnings\n  — e.g. leftover data from before per-instance keying was introduced, not\n  anything a normal claim flow can produce.\n- Effect: the returned `ActiveEventInfo.Progress.Milestone.ClaimedIDs`/\n  `UnlockedIDs` (and therefore `NextMilestone`, which is computed from the\n  sanitized `ClaimedIDs`) are already clean in the response you receive — you\n  never see the stale ids. Separately, the same removals are persisted to\n  the DB via `$pullAll` on `{entryPath}.Milestone.ClaimedIDs` /\n  `...UnlockedIDs` (`TimedEvent.cs:1114-1131`) so the fix is permanent; this\n  DB write is best-effort and wrapped in a swallowed try/catch\n  (`TimedEvent.cs:177-187`) — a failed cleanup simply retries on the next\n  `GetActiveEvents` call and never fails the read itself.\n- This only runs from `GetActiveEvents` (both the currently-active-instance\n  path and the ended-in-grace path) — `GetUserLteState` returns the raw\n  bucket as stored, unsanitized, which is one more reason to treat it as a\n  secondary/debug view rather than the milestone UI's source of truth.\n\n---\n\n## Bonus window (Coin-Master-style)\n\n`EventContent.BonusWindow` (nullable) describes a repeating sequence of\nphases layered on top of the event's own timeline, used to scale milestone\nrewards during \"boosted\" windows:\n\n```ts\ninterface BonusWindowConfig {\n  Schedule?: BonusWindowPhase[]; // ordered by Order; empty = disabled\n  RepeatCycle?: boolean; // true: restart from phase 0 after the last phase\n  MaxCycles?: number; // 0 = infinite (bounded only by the event's own end)\n}\n\ninterface BonusWindowPhase {\n  Order: number; // 0-based, unique within Schedule\n  Type: \"Cooldown\" | \"Bonus\" | \"MultipliedBonus\";\n  DurationSec: number; // must be > 0\n  BonusMultiplier?: number; // MultipliedBonus only; default 1.5\n}\n```\n\n(`TimedEventDefinitions.cs:315-395`)\n\nComputed per-request (never stored) by `BonusWindowHelpers.ComputePhase`\n(`IDosGamesSDK/API/Client/v2/TimedEvent/Services/BonusWindowHelpers.cs:29-75`),\nanchored at the **event/phase's own start time** — so the phase schedule is\nidentical for every player and simply depends on wall-clock time since that\nstart:\n\n```ts\ninterface BonusWindowState {\n  IsActive: boolean; // true only during Bonus/MultipliedBonus phases\n  CurrentPhaseEndUtc: string;\n  NextBonusStartUtc?: string; // null = no more bonus phases will occur\n  CurrentCycleIndex: number; // 0-based pass through the whole Schedule\n  CurrentPhaseIndex: number; // the active phase's Order\n  ActiveBonusMultiplier: number; // Bonus=1.0, MultipliedBonus=phase.BonusMultiplier, else 0\n}\n```\n\n`ComputePhase` returns `null` when: `BonusWindow` is `null`/has an empty\n`Schedule`, the event hasn't started yet, or all cycles are exhausted\n(`RepeatCycle=false` and the one pass already completed, or `MaxCycles`\nreached) — treat a `null` `ActiveEventInfo.BonusWindow` as \"no boosted\nrewards available,\" not an error.\n\nAt claim time, the server independently recomputes the same\n`BonusWindowState` for the resolved instance's own `StartUtc`\n(`TimedEvent.cs:602-617`) — it is never trusted from a prior client read —\nand if `IsActive`, merges `MilestoneDefinition.BonusRewards` into the base\n`Rewards` via `MilestoneRewardResolver`/`BonusWindowHelpers.MergeRewards`,\nscaling the bonus part by `ActiveBonusMultiplier` when the phase type is\n`MultipliedBonus` (`BonusWindowHelpers.cs:136-176`, entries rounded via\n`Math.Round`). You cannot predict the exact reward amount client-side when a\n`MultipliedBonus` phase is active mid-window — read it from the claim\nresponse's `Rewards`.\n\n---\n\n## Token sources, matching, and grant math\n\nA grant (`grantTokens`/`grantTokensBatch`, and internally for board/quest/\nstore/marketplace triggers) resolves as follows\n(`GrantTokensInternal`, `TimedEvent.cs:273-435`):\n\n1. Resolve the target instance (current active, unless a chain ref supplies\n   `CycleIndex`+`ChainedEventID`). Fails `\"Event not found or not active.\"`\n   if unresolved, `\"Earning is not allowed.\"` if `CanEarn` is false.\n2. `TriggerMatcher.FindMatch` walks `Content.TokenSources` in order and\n   returns the first `TriggerSource` whose `SourceType` matches and whose\n   filters all pass (AND-ed) — see `TriggerMatcher.cs:25-59` for the exact\n   per-`SourceType` filter rules (`BoardTileLanding` checks\n   `TileTypeFilter`/`TileIndexFilter`/`ChanceOutcomeFilter`; `CustomAction`\n   checks `Params[\"ActionName\"]`; `MarketplaceSell`/`MarketplaceBuy` check\n   `Params[\"CatalogID\"]`/`[\"ItemID\"]`/`[\"OfferType\"]`; `OutcomeFilter` is\n   checked for every source type). No match ⇒ `\"Source '<type>' is not\nallowed for this event.\"`.\n3. `baseAmount = amountOverride ?? source.BaseWeight`; must be `> 0` else\n   `\"Base amount must be > 0.\"`.\n4. `adjustedAmount = ModifierService.Apply(baseAmount, ctx).FinalValue` where\n   `ctx` only carries the roll multiplier, and only if\n   `source.ScaleWithRollMultiplier` is true (`TimedEvent.cs:350-353`).\n5. `EventTokenService.ComputeGrant` (`EventTokenService.cs:156-305`) applies,\n   **in order**: `DailyEarnCap` (global daily total) →\n   `DailyCapFromSource`/`source.Limits.DailyWeightCap` (per-source daily\n   amount) → `DailyTriggerCap`/`source.Limits.DailyCap` (per-source daily\n   trigger _count_) → `CooldownSeconds` (per-source, not reset daily) →\n   `MaxBalance` (spendable balance ceiling) — any of these can reject the\n   grant outright (`EventTokenGrantFailure` reason string). If accepted, the\n   amount is then **clamped** (not rejected) by `MaxPerGrant`, remaining\n   daily headroom, and remaining balance headroom, in that order\n   (`EventTokenService.cs:205-224`) — so a grant can silently apply for less\n   than requested near a cap, rather than failing.\n\n`BuildBoardTokenOperations`/`BuildMarketplaceTokenOperations`\n(`TimedEvent.cs:900-995`) are the server-internal helpers other modules\n(GameLoop, Marketplace) use to fan a single gameplay action out to every\nmatching active event — not something client code calls directly, but useful\ncontext for why a single board roll can grant several different event\ntokens at once.\n\n---\n\n## Server-side limits, batching, and idempotency\n\n- **Max batch size: 50** entries per call (`BatchSupport.MaxBatchSize`,\n  `IDosGamesSDK/API/Client/v2/_Shared/BatchSupport.cs:35`), enforced\n  identically for `ClaimMilestonesBatch`, `SpendTokensBatch`, and\n  `GrantTokensBatch` (`TimedEvent.cs:1200,1306,1475,1583`). Entries beyond 50\n  are silently dropped during normalization — they never appear in the\n  response at all, so chunk larger sets into multiple calls yourself.\n- **Dedup**: `ClaimMilestonesBatch` dedupes by `(instance key)|(MilestoneID)`\n  (`TimedEvent.cs:1195-1201`); `SpendTokensBatch` dedupes by instance key\n  (`TimedEvent.cs:1470-1477`); `GrantTokensBatch` dedupes by\n  `(instance key)|SourceType|Outcome` on input, **and separately rejects a\n  second grant to the same resolved token address** within one batch with\n  `\"Duplicate event instance in grant batch — send it as a separate\nrequest.\"` (`TimedEvent.cs:1634-1637`) because two grants to one address\n  in the same Mongo update would conflict.\n- **Atomicity**: each batch call resolves every entry, then applies **one**\n  atomic `ResourceService.ApplyResourceOperationAtomicAsync` for the whole\n  batch. For `SpendTokensBatch`/`GrantTokensBatch` this means the _entire_\n  batch's resource change succeeds or fails together — a single\n  insufficient-balance/over-cap item fails the whole apply and every\n  successfully-resolved item in that batch reports the same `Error`\n  (`TimedEvent.cs:1518-1552,1659-1695`). Items that failed to even _resolve_\n  (bad instance ref, unknown milestone, claim-mode gate) are filtered out\n  **before** the atomic apply and get their own independent preset error —\n  those don't block the rest of the batch.\n  `ClaimMilestonesBatch`/`ClaimAllMilestones` are slightly more granular:\n  milestones are grouped **per resolved token address** so multiple\n  milestones on the _same_ event instance share one `$push`, but the\n  token-threshold/already-claimed check\n  (`EventTokenService.ComputeMilestoneClaimBatch`) still runs per address\n  before the shared atomic apply, so a milestone that fails its own\n  threshold/already-claimed check is rejected independently of the others\n  (`TimedEvent.cs:1372-1413`).\n- **Idempotency (`reason` / `RelatedEntityID`)**: every mutating call passes\n  a `reason` string to `ApplyResourceOperationAtomicAsync` built from the\n  action, the resolved `Type`+`EntityID` (and `MilestoneID`/`sourceKey`\n  where relevant), and — for single-item calls — the caller's optional\n  `RelatedEntityID` folded in via `ResourceService.ResolveRelatedEntityID`\n  (e.g. `\"SpendTokens:spend_{Type}_{EntityID}_{RelatedEntityID}\"`,\n  `TimedEvent.cs:484-489,619-624,405-413`). Including `Type` guards against a\n  `Scheduled` and `Chained` event that happen to share an `LteID`; including\n  the instance-keyed `EntityID` guards against collisions across chain\n  instances or across unrelated events reusing the same `RelatedEntityID`\n  string (e.g. `\"roll_42\"`). Batch calls build one shared reason from all\n  included item keys (`BatchSupport.BuildBatchReason`) rather than one per\n  item.\n- **Where `Resources` live in batch responses**: for `SpendTokensBatch`\n  /`GrantTokensBatch`, the single merged `ResourceOperation` from the one\n  atomic apply is attached to the **first successfully-applied item only**\n  (`attached` flag, `TimedEvent.cs:1536-1552,1677-1693`) — every other\n  successful item in that batch gets an **empty** `ResourceOperation` in its\n  `Data.Resources`. The SDK's `spendTokensBatch`/`grantTokensBatch` already\n  account for this: they scan for the first item with a non-empty\n  `Resources` and apply that once to the cache\n  (`TimedEventService.ts:209-221,238-250`) — don't assume every batch item\n  carries its own independent `Resources`/`Rewards` payload; read cache\n  balances after the call instead of summing per-item deltas.\n- **Rate limit**: the v2 pipeline's per-IP endpoint limit for\n  `TimedEventV2` is 500 ms (`RateLimitMilliseconds`,\n  `TimedEvent.cs:18`); per-user/action transaction lock is 10 s\n  (`LockDurationMilliseconds`, `TimedEvent.cs:19`). The SDK's own client-side\n  throttle is a separate, smaller 600 ms guard per endpoint\n  (`packages/core/src/transport/throttle.ts:4`, `DEFAULT_THROTTLE_MS`).\n"
+      "content": "# Timed-event data model — reference\n\nFull shape of the config (Definitions) and player state, the composite\nevent-token key scheme, the milestone self-heal rule, grace-window math, and\nthe bonus-window model. All of these are **strictly typed in the SDK** —\n`TimedEventDefinitions` and every nested block (`TimedEventDefinition`,\n`ChainedEventDefinition`, `EventContent`, `BonusWindowConfig`,\n`ActiveEventInfo`, …) are exported from `@idosgames/core`, so\n`getDefinitions()` and `getSection<TimedEventDefinitions>(\"TimedEvent\")` give\nyou concrete types, not `unknown`. The schemas keep `.passthrough()`, so a\nfield the backend adds later still round-trips. Field names are PascalCase\n(straight from the backend JSON).\n\nEvery claim in this file traces to a specific backend source line — cited\ninline as `(file:line)` against the iDos_Games_Engine repo.\n\n## Contents\n\n- [Config: TimedEventDefinitions](#config-timedeventdefinitions)\n- [TimedEventDefinition (Scheduled vs Chained)](#timedeventdefinition-scheduled-vs-chained)\n- [EventContent](#eventcontent)\n- [Player state: UserEventTokenProgress](#player-state-usereventtokenprogress)\n- [ActiveEventInfo (getActiveEvents response)](#activeeventinfo-getactiveevents-response)\n- [The composite instance-key scheme](#the-composite-instance-key-scheme)\n- [Grace windows and claim-only instances](#grace-windows-and-claim-only-instances)\n- [Milestone claim rules and the self-heal on read](#milestone-claim-rules-and-the-self-heal-on-read)\n- [Bonus window (Coin-Master-style)](#bonus-window-coin-master-style)\n- [Token sources, matching, and grant math](#token-sources-matching-and-grant-math)\n- [Server-side limits, batching, and idempotency](#server-side-limits-batching-and-idempotency)\n\n---\n\n## Config: TimedEventDefinitions\n\nReturned by `getDefinitions()`; cached via\n`client.data.config.getSection<TimedEventDefinitions>(\"TimedEvent\")`.\n\n```ts\ninterface TimedEventDefinitions {\n  Definitions?: Record<string, TimedEventDefinition>; // key = TimedEventID\n  Settings?: LimitedTimeEventsGlobalSettings;\n}\n\ninterface LimitedTimeEventsGlobalSettings {\n  MaxConcurrentEvents?: number; // config-mistake guard; default 5\n}\n```\n\n(`IDosGamesSDK/API/Client/v2/TimedEvent/Models/TimedEventDefinitions.cs:27-58`)\n\n---\n\n## TimedEventDefinition (Scheduled vs Chained)\n\nOne dictionary holds both kinds; the mode lives in `Schedule.Mode`.\n\n```ts\ninterface TimedEventDefinition {\n  TimedEventID?: string;\n  DisplayName?: string;\n  Description?: string;\n  AssetPaths?: Record<string, string>;\n  Schedule?: ScheduleSpec; // Mode: \"Scheduled\" | \"Chained\"\n  Content?: EventContent; // used when Mode = Scheduled\n  Events?: ChainedEventDefinition[]; // used when Mode = Chained\n  Gate?: SegmentGate; // audience gate; null = everyone\n  CustomParams?: Record<string, string>;\n}\n```\n\n(`TimedEventDefinitions.cs:72-130`)\n\n- **Scheduled**: one fixed window (`Schedule.Scheduled: ScheduledWindow` —\n  `StartUtc`, `EndUtc`, `AllowEarningAfterEnd`, `ClaimGraceHours`). Content\n  lives directly on `Content`.\n- **Chained**: a repeating ordered list of phases (`Events`), timed by\n  `Schedule.Chain: ScheduleChain` (`AnchorUtc`, `MaxCycles`,\n  `PauseBetweenPhasesSec`, `PauseBetweenCyclesSec`). Each phase has its own\n  `Content`. After the last phase, the whole cycle restarts from phase 0\n  (unless `MaxCycles` caps the number of repeats).\n\n```ts\ninterface ChainedEventDefinition {\n  ChainedEventID?: string; // unique within the chain\n  Order?: number; // 0-based position; defines phase sequence\n  DurationSec?: number;\n  Content?: EventContent;\n  ClaimGraceHours?: number; // 0 = no claiming once this phase ends\n  CustomParams?: Record<string, string>;\n}\n```\n\n(`TimedEventDefinitions.cs:138-180`)\n\n`Gate` is the standard `SegmentGate` (Core/Segment) — `Segments`,\n`MinPremiumTier`, `RequiredPremiumIDs`, `MinLevel`/`MaxLevel`, `Countries`,\n`RegisteredWithinDays`, `ActiveWithinDays`, `Experiment`. A player failing the\ngate does not see the event in `getActiveEvents()` and cannot earn or spend\nits tokens — `GrantTokensInternal` re-checks the gate server-side even if a\nstale client tries to call it directly\n(`IDosGamesSDK/API/Client/v2/TimedEvent/TimedEvent.cs:325-329`).\n\n---\n\n## EventContent\n\nShared shape used by both a `Scheduled` event's `Content` and each\n`ChainedEventDefinition.Content`.\n\n```ts\ninterface EventContent {\n  DisplayName?: string;\n  Description?: string;\n  AssetPaths?: Record<string, string>;\n  Category?: string; // free-form UI grouping tag\n  Token?: EventTokenDefinition; // the event token's own config\n  TokenSources?: TriggerSource[]; // whitelist of what earns this token\n  ClaimMode?: \"Instant\" | \"AfterEventEnd\" | \"FeaturedAfterEnd\";\n  Milestones?: Record<string, MilestoneDefinition>; // key = MilestoneID\n  BonusWindow?: BonusWindowConfig; // null = disabled for this event\n}\n```\n\n(`TimedEventDefinitions.cs:192-280`, `Core/Milestone/Models/MilestoneClaimMode.cs:14-36`)\n\n`EventTokenDefinition` (`_shared/EventTokenDefinitionModels.ts`, port of\n`Core/Event/Models/EventTokenModels.cs:399-453`):\n\n```ts\ninterface EventTokenDefinition {\n  DisplayName?: string;\n  AssetPaths?: Record<string, string>;\n  MaxBalance?: number; // 0 = unlimited spendable balance cap\n  MaxPerGrant?: number; // per-grant clamp; default 1000 server-side\n  DailyEarnCap?: number; // 0 = unlimited daily earn total\n  BurnOnEventEnd?: boolean; // default true — balance zeroed at event end\n  BurnConversion?: EventTokenConversion; // optional leftover→currency conversion\n}\n```\n\n`MilestoneDefinition` is the shared Core/Milestone primitive (also used by\nLeaderboard/Quest/CommunityChest/DealOffer):\n\n```ts\ninterface MilestoneDefinition {\n  MilestoneID?: string;\n  DisplayName?: string;\n  AssetPaths?: Record<string, string>;\n  RequiredProgress?: number; // compared against Balance.TotalEarned\n  Rewards?: ResourceGrant; // base reward\n  BonusRewards?: ResourceGrant; // added/scaled in during an active bonus window\n  SeasonTierRewards?: SeasonTierRewardSet; // not used by TimedEvent\n  SortOrder?: number;\n  IsFeatured?: boolean; // gates FeaturedAfterEnd behavior\n}\n```\n\n(`Core/Milestone/Models/MilestoneDefinition.cs` via `_shared/MilestoneModels.ts:125-138`)\n\n`TriggerSource` (shared `_shared/ScheduleModels.ts:83-96`, port of\n`Core/Scheduling/Models/TriggerSource.cs`):\n\n```ts\ninterface TriggerSource {\n  SourceType?: string; // EventTokenSourceType, e.g. \"BoardTileLanding\"\n  BaseWeight?: number; // tokens granted per matching trigger\n  ScaleWithRollMultiplier?: boolean; // multiply BaseWeight by the caller's roll multiplier\n  TileTypeFilter?: string[]; // BoardTileLanding only; empty = any\n  TileIndexFilter?: number[]; // BoardTileLanding only; empty = any\n  ChanceOutcomeFilter?: string[]; // BoardTileLanding Chance tiles only; empty = any\n  OutcomeFilter?: string[]; // checked for every source type; empty = any\n  Params?: Record<string, string>; // CustomAction: ActionName; Marketplace*: CatalogID/ItemID/OfferType\n  Limits?: LimitSpec; // DailyCap / DailyWeightCap / CooldownSeconds\n}\n```\n\n---\n\n## Player state: UserEventTokenProgress\n\nReturned inside `getUserLteState()`'s `Tokens` map and inside each\n`ActiveEventInfo.Progress`.\n\n```ts\ninterface UserEventTokenProgress {\n  Balance?: {\n    Current: number; // spendable balance; rises on grant, falls on spend\n    TotalEarned: number; // lifetime earned in THIS instance; monotonic; milestone math uses this\n    TotalSpent: number; // lifetime spent in this instance; analytics only\n  };\n  Daily?: {\n    Date: string; // UTC date the counters below apply to; lazy-reset on next grant\n    TotalEarned: number;\n    EarnedBySource?: Record<string, number>; // vs TriggerSource.Limits.DailyWeightCap\n    TriggersBySource?: Record<string, number>; // vs TriggerSource.Limits.DailyCap\n    LastTriggerBySource?: Record<string, string>; // vs TriggerSource.Limits.CooldownSeconds; NOT reset daily\n  };\n  Meta?: {\n    JoinedAtUtc?: string; // first grant into this instance's bucket\n    LastEarnedAtUtc?: string;\n  };\n  Milestone?: {\n    ClaimedIDs?: string[];\n    UnlockedIDs?: string[]; // reached but not yet claimable under AfterEventEnd/FeaturedAfterEnd\n  };\n}\n```\n\n(`Core/Event/Models/EventTokenModels.cs:51-179`, mirrored in SDK\n`_shared/EventTokenState.ts:8-38`)\n\nImportant: **spending tokens never affects `TotalEarned`**\n(`EventTokenService.ComputeSpend`, `EventTokenService.cs:311-337` only\ntouches `Balance.Current`/`Balance.TotalSpent`), so a milestone earned and\nthen \"un-afforded\" by spending remains claimable/claimed — milestones track\nlifetime earning, not current balance.\n\n---\n\n## ActiveEventInfo (getActiveEvents response)\n\n```ts\ninterface ActiveEventInfo {\n  Type?: \"Scheduled\" | \"Chained\";\n  TimedEventID?: string;\n  CurrentChainedEventID?: string | null; // null for Scheduled\n  Content?: EventContent | null; // resolved content for the current/ended instance\n  Progress?: UserEventTokenProgress | null;\n  ComputedStartUtc?: string | null;\n  ComputedEndUtc?: string | null;\n  CanEarn?: boolean | null; // tokens can still be granted for this instance\n  CanClaim?: boolean | null; // still inside claim/grace window\n  NextMilestone?: MilestoneDefinition | null; // lowest RequiredProgress not yet in ClaimedIDs\n  BonusWindow?: BonusWindowState | null; // computed; null = no window / disabled\n  CurrentCycleIndex?: number | null; // Chained only\n  CurrentEventOrder?: number | null; // Chained only: 1-based position... (see note)\n  TotalEventsInChain?: number | null; // Chained only\n}\n```\n\n(`IDosGamesSDK/API/Client/v2/TimedEvent/Models/UserTimedEventState.cs:23-78`)\n\nNote: the backend populates `CurrentEventOrder` from\n`ChainedEventDefinition.Order`, which is documented as 0-based\n(`TimedEventDefinitions.cs:148-152`) — the SDK's own doc-comment calling it\n\"1-based\" is aspirational UI framing, not a code guarantee; treat it as \"the\nphase's configured `Order` value\" and don't assume it starts at 1.\n\n`getActiveEvents()` can return **more than one `ActiveEventInfo` for the same\n`Chained` `TimedEventID`** in a single response: the currently active phase,\nplus any phase(s) that already ended but are still inside their\n`ClaimGraceHours` window (`CanEarn: false`, `CanClaim: true`)\n(`TimedEvent.cs:149-169`, `EnumerateEndedInGraceChainInstances`,\n`TimedEvent.cs:801-836`). Disambiguate them by `CurrentCycleIndex` +\n`CurrentChainedEventID`.\n\n---\n\n## The composite instance-key scheme\n\nEvery event **instance** — not just every event — gets its own progress\nbucket, milestone-claimed list, and (for chains) bonus-window timeline. The\nbucket key (`EventTokenAddress.EntityID`, stored under\n`UserDataDocument.EventToken.TimedEvent[EntityID]`) is:\n\n```\nEntityID = \"{TimedEventID}:{InstanceKey}\"\n```\n\n(`TimedEvent.cs:1044-1057`, `BuildTokenAddress`)\n\nWhere `InstanceKey` depends on the resolved mode\n(`Core/Scheduling/Services/ScheduleInstanceKey.cs:14-23`):\n\n| Mode        | `InstanceKey` format           | Example         |\n| ----------- | ------------------------------ | --------------- |\n| `AlwaysOn`  | `\"all\"`                        | `all`           |\n| `Scheduled` | `\"s{yyyyMMddHHmm}\"` (StartUtc) | `s202607010000` |\n| `Chained`   | `\"{cycleIndex}:{phaseID}\"`     | `4:boss_phase`  |\n\nSo a `Scheduled` event's `EntityID` is effectively\n`\"summer_sale:s202607010000\"`, and a `Chained` event's is\n`\"raid_rotation:4:boss_phase\"`. This is why re-running the same\n`TimedEventID` (a new Scheduled window with a different `StartUtc`, or the\nnext chain cycle) starts every player at a fresh `Balance`/`Milestone`\nbucket — nothing carries over, by design.\n\n### Addressing an event from title config (short form)\n\nThe composite key above is a **runtime** address — the cycle index and the\nwindow start are unknowable when a reward is authored. So a reward written in\ntitle config (a Special-mode choice on the board, a store offer, a quest\npayout…) addresses the event by name instead:\n\n| `Address.EntityID` in config | Meaning                                                    |\n| ---------------------------- | ---------------------------------------------------------- |\n| `\"raid_rotation\"`            | whichever instance of that event is live at grant time      |\n| `\"raid_rotation:boss_phase\"` | that chain phase, current cycle — skipped when it isn't live |\n\nThe backend expands it right before the grant (`EventTokenAddressResolver`,\ncalled from `ResourceService`), stamping the instance suffix that is active at\nthat moment. A grant whose event is paused, off, or currently in another phase\nis dropped rather than written to a bucket nobody reads; a *consume* keeps the\nshort address so the price can never silently become free. Already-composite\naddresses pass through untouched, so this is safe to re-apply.\n\nThe SDK's `UserTimedEventStateResponse.Tokens` map uses these same composite\nkeys. Cache helpers that need to find \"the bucket for this `LteID`, whatever\nits current instance suffix is\" use `matchesBase(key, lteID)`\n(`packages/core/src/util/eventTokenIds.ts:4-6`): a key belongs to a base id\nif it equals it exactly or starts with `\"{lteID}:\"`. `getUserLteState()` is a\nflat dump of every bucket the player has ever touched (including stale\nfinished instances) — don't assume one entry per `LteID`.\n\n---\n\n## Grace windows and claim-only instances\n\nOnce an instance's window ends, tokens can no longer be earned\n(`CanEarn` flips to `false`), but the milestone rewards already reached can\nstill be claimed until a grace deadline:\n\n```\nClaimDeadlineUtc = EndUtc + ClaimGraceHours\n```\n\n- `Scheduled`: `ClaimGraceHours` comes from `Schedule.Scheduled.ClaimGraceHours`\n  (`TimedEvent.cs:728`). `AllowEarningAfterEnd` (also on `ScheduledWindow`)\n  lets earning continue past `EndUtc` if set — independent of the grace\n  window, which only governs _claiming_.\n- `Chained`: `ClaimGraceHours` comes from the specific\n  `ChainedEventDefinition.ClaimGraceHours` (`TimedEvent.cs:718,773,826`) —\n  each phase can have its own grace period. `AllowEarningAfterEnd` is always\n  `false` for chain phases (`TimedEvent.cs:719`) — earning always stops the\n  instant the phase ends.\n- `now > ClaimDeadlineUtc` ⇒ the instance is gone entirely: `ResolveScheduled`\n  / `ScheduleResolver.ResolveChainInstance` return `null`\n  (`Core/Scheduling/Services/ScheduleResolver.cs:127-145,361-406`), and any\n  spend/grant/claim call against it fails with `\"Event not found or not\nactive.\"` / `\"...not in claim window.\"`.\n\n`EnumerateEndedInGraceChainInstances` walks backward through past chain\ncycles (hard-capped at 200 lookback instances,\n`ScheduleResolver.cs:414-484`) collecting every phase whose\n`now ∈ (EndUtc, EndUtc + ClaimGraceHours]`, **only for instances where the\nplayer has existing progress** (`TimedEvent.cs:156-159` — buckets with no\nprogress are skipped, so a phase the player never touched doesn't clutter\nthe active-events list). These are returned with `CanEarn: false,\nCanClaim: true` and must be addressed by their own `CycleIndex` +\n`ChainedEventID` when spending/claiming (`ResolveEventFromArgs`,\n`TimedEvent.cs:672-686`, only takes the explicit-instance path when **both**\n`CycleIndex` and `ChainedEventID` are supplied — omitting either resolves to\nwhatever instance is currently active instead).\n\n---\n\n## Milestone claim rules and the self-heal on read\n\n**Claim gate** (`ClaimMilestone`, `TimedEvent.cs:518-658`, and the batch\npaths mirror this via `CheckMilestoneClaimMode`, `TimedEvent.cs:1767-1775`):\n\n1. The resolved instance must have `CanClaim: true` (inside its window or\n   grace), else `\"Claim window has expired.\"`.\n2. The milestone id must exist in the resolved content's `Milestones`, else\n   `\"Milestone '<id>' not found.\"`.\n3. `Content.ClaimMode` gate:\n   - `Instant` — always allowed once reached.\n   - `AfterEventEnd` — rejected with `\"Milestone can only be claimed after\nevent ends.\"` until `now > EndUtc`.\n   - `FeaturedAfterEnd` — same rejection (`\"Featured milestone can only be\nclaimed after event ends.\"`) but **only** when `MilestoneDefinition.IsFeatured\n=== true`; non-featured milestones under this mode behave like `Instant`.\n4. `EventTokenService.ComputeMilestoneClaim` (`EventTokenService.cs:343-366`):\n   fails with `\"No progress for this event token.\"` if the bucket doesn't\n   exist at all, `\"Not enough earned. Have: {X}, need: {Y}.\"` if\n   `Balance.TotalEarned < RequiredProgress`, or `\"Milestone already\nclaimed.\"` if the id is already in `ClaimedIDs`.\n\n**Self-heal on `GetActiveEvents` read** (`SanitizeMilestoneState`,\n`TimedEvent.cs:1070-1131`, invoked from `BuildActiveEventInfo` at\n`TimedEvent.cs:1143` and staged as background `$pullAll` patches at\n`TimedEvent.cs:112-187`):\n\n- Trigger condition: for the **specific instance bucket being read**, any id\n  present in that bucket's `Milestone.ClaimedIDs` or `Milestone.UnlockedIDs`\n  whose corresponding `MilestoneDefinition.RequiredProgress` is **greater\n  than that same bucket's own `Balance.TotalEarned`** is stale. An id with no\n  matching entry in the resolved content's `Milestones` dictionary is also\n  stripped (nothing to verify it against). The check is\n  `totalEarned >= def.RequiredProgress` per id\n  (`TimedEvent.cs:1076-1080`, local function `Reached`).\n- Why it's safe: `TotalEarned` is monotonically non-decreasing\n  (`EventTokenService.ComputeGrant` only ever increments it,\n  `EventTokenService.cs:226,271,283`), so a milestone legitimately claimed\n  (earned had already reached the threshold _at claim time_) can never later\n  have `TotalEarned` fall back below `RequiredProgress`. The only ids this\n  can strip are ones inconsistent with their own bucket's recorded earnings\n  — e.g. leftover data from before per-instance keying was introduced, not\n  anything a normal claim flow can produce.\n- Effect: the returned `ActiveEventInfo.Progress.Milestone.ClaimedIDs`/\n  `UnlockedIDs` (and therefore `NextMilestone`, which is computed from the\n  sanitized `ClaimedIDs`) are already clean in the response you receive — you\n  never see the stale ids. Separately, the same removals are persisted to\n  the DB via `$pullAll` on `{entryPath}.Milestone.ClaimedIDs` /\n  `...UnlockedIDs` (`TimedEvent.cs:1114-1131`) so the fix is permanent; this\n  DB write is best-effort and wrapped in a swallowed try/catch\n  (`TimedEvent.cs:177-187`) — a failed cleanup simply retries on the next\n  `GetActiveEvents` call and never fails the read itself.\n- This only runs from `GetActiveEvents` (both the currently-active-instance\n  path and the ended-in-grace path) — `GetUserLteState` returns the raw\n  bucket as stored, unsanitized, which is one more reason to treat it as a\n  secondary/debug view rather than the milestone UI's source of truth.\n\n---\n\n## Bonus window (Coin-Master-style)\n\n`EventContent.BonusWindow` (nullable) describes a repeating sequence of\nphases layered on top of the event's own timeline, used to scale milestone\nrewards during \"boosted\" windows:\n\n```ts\ninterface BonusWindowConfig {\n  Schedule?: BonusWindowPhase[]; // ordered by Order; empty = disabled\n  RepeatCycle?: boolean; // true: restart from phase 0 after the last phase\n  MaxCycles?: number; // 0 = infinite (bounded only by the event's own end)\n}\n\ninterface BonusWindowPhase {\n  Order: number; // 0-based, unique within Schedule\n  Type: \"Cooldown\" | \"Bonus\" | \"MultipliedBonus\";\n  DurationSec: number; // must be > 0\n  BonusMultiplier?: number; // MultipliedBonus only; default 1.5\n}\n```\n\n(`TimedEventDefinitions.cs:315-395`)\n\nComputed per-request (never stored) by `BonusWindowHelpers.ComputePhase`\n(`IDosGamesSDK/API/Client/v2/TimedEvent/Services/BonusWindowHelpers.cs:29-75`),\nanchored at the **event/phase's own start time** — so the phase schedule is\nidentical for every player and simply depends on wall-clock time since that\nstart:\n\n```ts\ninterface BonusWindowState {\n  IsActive: boolean; // true only during Bonus/MultipliedBonus phases\n  CurrentPhaseEndUtc: string;\n  NextBonusStartUtc?: string; // null = no more bonus phases will occur\n  CurrentCycleIndex: number; // 0-based pass through the whole Schedule\n  CurrentPhaseIndex: number; // the active phase's Order\n  ActiveBonusMultiplier: number; // Bonus=1.0, MultipliedBonus=phase.BonusMultiplier, else 0\n}\n```\n\n`ComputePhase` returns `null` when: `BonusWindow` is `null`/has an empty\n`Schedule`, the event hasn't started yet, or all cycles are exhausted\n(`RepeatCycle=false` and the one pass already completed, or `MaxCycles`\nreached) — treat a `null` `ActiveEventInfo.BonusWindow` as \"no boosted\nrewards available,\" not an error.\n\nAt claim time, the server independently recomputes the same\n`BonusWindowState` for the resolved instance's own `StartUtc`\n(`TimedEvent.cs:602-617`) — it is never trusted from a prior client read —\nand if `IsActive`, merges `MilestoneDefinition.BonusRewards` into the base\n`Rewards` via `MilestoneRewardResolver`/`BonusWindowHelpers.MergeRewards`,\nscaling the bonus part by `ActiveBonusMultiplier` when the phase type is\n`MultipliedBonus` (`BonusWindowHelpers.cs:136-176`, entries rounded via\n`Math.Round`). You cannot predict the exact reward amount client-side when a\n`MultipliedBonus` phase is active mid-window — read it from the claim\nresponse's `Rewards`.\n\n---\n\n## Token sources, matching, and grant math\n\nA grant (`grantTokens`/`grantTokensBatch`, and internally for board/quest/\nstore/marketplace triggers) resolves as follows\n(`GrantTokensInternal`, `TimedEvent.cs:273-435`):\n\n1. Resolve the target instance (current active, unless a chain ref supplies\n   `CycleIndex`+`ChainedEventID`). Fails `\"Event not found or not active.\"`\n   if unresolved, `\"Earning is not allowed.\"` if `CanEarn` is false.\n2. `TriggerMatcher.FindMatch` walks `Content.TokenSources` in order and\n   returns the first `TriggerSource` whose `SourceType` matches and whose\n   filters all pass (AND-ed) — see `TriggerMatcher.cs:25-59` for the exact\n   per-`SourceType` filter rules (`BoardTileLanding` checks\n   `TileTypeFilter`/`TileIndexFilter`/`ChanceOutcomeFilter`; `CustomAction`\n   checks `Params[\"ActionName\"]`; `MarketplaceSell`/`MarketplaceBuy` check\n   `Params[\"CatalogID\"]`/`[\"ItemID\"]`/`[\"OfferType\"]`; `OutcomeFilter` is\n   checked for every source type). No match ⇒ `\"Source '<type>' is not\nallowed for this event.\"`.\n3. `baseAmount = amountOverride ?? source.BaseWeight`; must be `> 0` else\n   `\"Base amount must be > 0.\"`.\n4. `adjustedAmount = ModifierService.Apply(baseAmount, ctx).FinalValue` where\n   `ctx` only carries the roll multiplier, and only if\n   `source.ScaleWithRollMultiplier` is true (`TimedEvent.cs:350-353`).\n5. `EventTokenService.ComputeGrant` (`EventTokenService.cs:156-305`) applies,\n   **in order**: `DailyEarnCap` (global daily total) →\n   `DailyCapFromSource`/`source.Limits.DailyWeightCap` (per-source daily\n   amount) → `DailyTriggerCap`/`source.Limits.DailyCap` (per-source daily\n   trigger _count_) → `CooldownSeconds` (per-source, not reset daily) →\n   `MaxBalance` (spendable balance ceiling) — any of these can reject the\n   grant outright (`EventTokenGrantFailure` reason string). If accepted, the\n   amount is then **clamped** (not rejected) by `MaxPerGrant`, remaining\n   daily headroom, and remaining balance headroom, in that order\n   (`EventTokenService.cs:205-224`) — so a grant can silently apply for less\n   than requested near a cap, rather than failing.\n\n`BuildBoardTokenOperations`/`BuildMarketplaceTokenOperations`\n(`TimedEvent.cs:900-995`) are the server-internal helpers other modules\n(GameLoop, Marketplace) use to fan a single gameplay action out to every\nmatching active event — not something client code calls directly, but useful\ncontext for why a single board roll can grant several different event\ntokens at once.\n\n---\n\n## Server-side limits, batching, and idempotency\n\n- **Max batch size: 50** entries per call (`BatchSupport.MaxBatchSize`,\n  `IDosGamesSDK/API/Client/v2/_Shared/BatchSupport.cs:35`), enforced\n  identically for `ClaimMilestonesBatch`, `SpendTokensBatch`, and\n  `GrantTokensBatch` (`TimedEvent.cs:1200,1306,1475,1583`). Entries beyond 50\n  are silently dropped during normalization — they never appear in the\n  response at all, so chunk larger sets into multiple calls yourself.\n- **Dedup**: `ClaimMilestonesBatch` dedupes by `(instance key)|(MilestoneID)`\n  (`TimedEvent.cs:1195-1201`); `SpendTokensBatch` dedupes by instance key\n  (`TimedEvent.cs:1470-1477`); `GrantTokensBatch` dedupes by\n  `(instance key)|SourceType|Outcome` on input, **and separately rejects a\n  second grant to the same resolved token address** within one batch with\n  `\"Duplicate event instance in grant batch — send it as a separate\nrequest.\"` (`TimedEvent.cs:1634-1637`) because two grants to one address\n  in the same Mongo update would conflict.\n- **Atomicity**: each batch call resolves every entry, then applies **one**\n  atomic `ResourceService.ApplyResourceOperationAtomicAsync` for the whole\n  batch. For `SpendTokensBatch`/`GrantTokensBatch` this means the _entire_\n  batch's resource change succeeds or fails together — a single\n  insufficient-balance/over-cap item fails the whole apply and every\n  successfully-resolved item in that batch reports the same `Error`\n  (`TimedEvent.cs:1518-1552,1659-1695`). Items that failed to even _resolve_\n  (bad instance ref, unknown milestone, claim-mode gate) are filtered out\n  **before** the atomic apply and get their own independent preset error —\n  those don't block the rest of the batch.\n  `ClaimMilestonesBatch`/`ClaimAllMilestones` are slightly more granular:\n  milestones are grouped **per resolved token address** so multiple\n  milestones on the _same_ event instance share one `$push`, but the\n  token-threshold/already-claimed check\n  (`EventTokenService.ComputeMilestoneClaimBatch`) still runs per address\n  before the shared atomic apply, so a milestone that fails its own\n  threshold/already-claimed check is rejected independently of the others\n  (`TimedEvent.cs:1372-1413`).\n- **Idempotency (`reason` / `RelatedEntityID`)**: every mutating call passes\n  a `reason` string to `ApplyResourceOperationAtomicAsync` built from the\n  action, the resolved `Type`+`EntityID` (and `MilestoneID`/`sourceKey`\n  where relevant), and — for single-item calls — the caller's optional\n  `RelatedEntityID` folded in via `ResourceService.ResolveRelatedEntityID`\n  (e.g. `\"SpendTokens:spend_{Type}_{EntityID}_{RelatedEntityID}\"`,\n  `TimedEvent.cs:484-489,619-624,405-413`). Including `Type` guards against a\n  `Scheduled` and `Chained` event that happen to share an `LteID`; including\n  the instance-keyed `EntityID` guards against collisions across chain\n  instances or across unrelated events reusing the same `RelatedEntityID`\n  string (e.g. `\"roll_42\"`). Batch calls build one shared reason from all\n  included item keys (`BatchSupport.BuildBatchReason`) rather than one per\n  item.\n- **Where `Resources` live in batch responses**: for `SpendTokensBatch`\n  /`GrantTokensBatch`, the single merged `ResourceOperation` from the one\n  atomic apply is attached to the **first successfully-applied item only**\n  (`attached` flag, `TimedEvent.cs:1536-1552,1677-1693`) — every other\n  successful item in that batch gets an **empty** `ResourceOperation` in its\n  `Data.Resources`. The SDK's `spendTokensBatch`/`grantTokensBatch` already\n  account for this: they scan for the first item with a non-empty\n  `Resources` and apply that once to the cache\n  (`TimedEventService.ts:209-221,238-250`) — don't assume every batch item\n  carries its own independent `Resources`/`Rewards` payload; read cache\n  balances after the call instead of summing per-item deltas.\n- **Rate limit**: the v2 pipeline's per-IP endpoint limit for\n  `TimedEventV2` is 500 ms (`RateLimitMilliseconds`,\n  `TimedEvent.cs:18`); per-user/action transaction lock is 10 s\n  (`LockDurationMilliseconds`, `TimedEvent.cs:19`). The SDK's own client-side\n  throttle is a separate, smaller 600 ms guard per endpoint\n  (`packages/core/src/transport/throttle.ts:4`, `DEFAULT_THROTTLE_MS`).\n"
     }
   ]
 }