@truelab/trueserver 0.0.4 → 0.1.0

package/CHANGELOG.md

@@ -6,6 +6,73 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.0] - Unreleased
+
+### Breaking
+
+- `/play` ответ **уплощён**: убрана обёртка `results`. Все поля теперь на верхнем уровне.
+- `/play` ответ: `results.cashWin` → `winCash`; `results.coins` → `winCoins`.
+- `/play` ответ: добавлено обязательное поле `hasMaxWin: boolean`. При достижении max-win обязательно `hasMaxWin: true` вместе с `finished: true`.
+- `/play` ответ: `results.choices?: integer[]` → `choices?: (number | string)[]` — тип элемента расширен до `number | string`.
+- `/play` ответ: добавлено поле `choice?: number | string` — эхо `choice` с continuation-шагов.
+- `/play` запрос: `choice` — тип `integer` → `number | string`.
+- `/config` ответ: удалено поле `gameTitle`.
+- `/config` ответ: `hasVariableLines` → `hasVariableLevels`.
+- `/config` ответ: добавлено обязательное поле `hasValidate: boolean`.
+- `/config` инварианты: при `hasMultiStake === true` обязательно `freeroundsAllowed === false` и `hasValidate === true`.
+- `TGameConfig` (`registerGameConfig`): удалено поле `gameTitle`; `hasVariableLines` → `hasVariableLevels`; `hasValidation` → `hasValidate` (обязательное при `hasMultiStake === true`).
+- `/validate` запрос: `demo` → `isDemo`; `metaPublic`/`metaPrivate` (строки) удалены — заменены на `meta: { public, private }` (объект); `currencyDecimals` и `stakes` стали обязательными.
+- `/validate` ответ: пустой `{}` → `{ valid: boolean, reason?: string }`. Хендлер игры теперь возвращает вердикт, а не пустой объект. `valid: false` — это `200` с отказом (раунд не открывается), не ошибка.
+- `StakeMode.parametric` — стало опциональным (отсутствие эквивалентно `false`).
+
+### Added
+
+- Money-хелперы: `Big`, `roundMoney`, `isExactDecimal` — экспортируются из `@truelab/trueserver`. Позволяют считать денежные значения в decimal-арифметике без подключения отдельной библиотеки.
+- Зависимость `big.js` добавлена в `dependencies` пакета (передаётся транзитивно потребителям).
+
+### Changed
+
+- Включает все изменения из 0.0.7 (multi-RTP режим: `rtpVersion` в `registerGameConfig` стал опциональным; сверка `rtpVersion` ответа с path-сегментом выполняется всегда).
+
+## [0.0.7] - 2026-06-06
+
+### Changed
+- `TGameConfig.rtpVersion` теперь **опциональное**. Поддержан режим «один инстанс — все RTP»: игра не регистрирует `rtpVersion`, а берёт его из сегмента `{rtpVersion}` пути на каждый запрос.
+- `config.route.validate.plugin`: сверка `rtpVersion` ответа с `gameConfig.rtpVersion` выполняется **только если** он задан (single-RTP). Сверка с path-сегментом `{rtpVersion}` выполняется всегда. См. [MIGRATION.md](MIGRATION.md).
+
+## [0.0.6] - 2026-06-03
+
+### Breaking
+- `/config` reply: добавлено обязательное поле `rtpVersion: string` (лейбл RTP-бакета, совпадает с сегментом `{rtpVersion}` пути). См. [MIGRATION.md](MIGRATION.md).
+- `TGameConfig.rtpVersion` — теперь обязательное поле для `registerGameConfig`.
+- `Stake.amount` — семантика изменилась: теперь это **полная сумма ставки**, уже умноженная на `StakeMode.bets` и `qty`. Формула: `amount = baseBetAmount × StakeMode.bets × (qty ?? 1)`. Не валидируется пакетом — обновлены только описания.
+
+### Added
+- `Stake.coinValue?: number` — опциональное поле для игр с coin-механикой (для рулеток и подобных — отсутствует).
+- `config.route.validate.plugin` сверяет `rtpVersion` в трёх источниках: `request.params.rtpVersion`, `payload.rtpVersion`, `gameConfig.rtpVersion`. Несовпадение → 500 с `code=1006`.
+
+## [0.0.5] - 2026-05-29
+
+### Breaking
+- Контракт API приведён к [GS Documentation 1.0.0](https://www.notion.so/truelab/GS-Documentation-36dd90f8c00680d485d4e4e3eba928f0). Полный список изменений и инструкция по переходу — в [MIGRATION.md](MIGRATION.md).
+- Гейм-плей роуты под версионным префиксом `/:rtpVersion` (`/config`, `/client`, `/play`, `/validate`, `/checksum`). `/healthcheck` остаётся без версии.
+- HTTP-методы: `GET /healthcheck`, `GET /:rtpVersion/config`, `GET /:rtpVersion/client`, `GET /:rtpVersion/checksum`. `/play` и `/validate` — `POST`.
+- Обёртка ошибок: `{ status: false, code, message }` (вместо `{ ok: false, message }`).
+- API-ключ проверяется на **всех** запросах (включая `GET`).
+- `/play`: переименование полей (`demo` → `isDemo`, `winCash` → `cashWin`, `winCoins` → `coins`); `meta` — единый объект `{ public, private }`; `gameResponse` и `rng` в новом формате; `finished/choices/meta` перенесены в `results`. Добавлено обязательное `stepIndex`.
+- `/config`: новая форма (`gameTitle`, `gameId`, `volatility: number`, `rtp: string`, `hasRestore`, `hasVariableLines`, `variableLevels: number[]`, `defaultLevel`). Удалены `category`, `hitrate`, `apiVersion`, `hasBuy`, `hasGamble`, `ECategory`, `EVolatility`.
+- `/healthcheck`: ответ упрощён до `{ ok, gameId, environment, uptime, timestamp }`. Поле `service` → `gameId`. Удалены `metrics`, `services`, `code`, `status`, `message`.
+- `/client`: убрано `ok`, добавлено опциональное поле `test` для cheat-tool.
+- Удалён плагин `metrics`.
+
+### Added
+- Новый эндпоинт `GET /:rtpVersion/checksum` для проверки целостности файлов.
+- Хелпер `EErrorCode` + типизированный `httpError(message, statusCode, code)`.
+- Инвариант `hasChoice ⇒ hasMeta` и `hasVariableLines ⇔ {variableLevels, defaultLevel}` проверяются в `registerGameConfig`.
+- Экспорт `MetaSchema` / `TMeta`.
+
+## [Unreleased archive]
+
 ### Added
 - NPM-пакет `@truelab/trueserver` (exports, dist, prepack, publishConfig)
 - Bitbucket Pipelines: test / build / publish

package/MIGRATION.md

@@ -0,0 +1,508 @@
+# Migration
+
+- [0.0.7 → 0.1.0](#migration-007--010) (последнее)
+- [0.0.6 → 0.0.7](#migration-006--007)
+- [0.0.5 → 0.0.6](#migration-005--006)
+- [0.0.4 → 0.0.5](#migration-004--005)
+
+---
+
+## Migration: 0.0.7 → 0.1.0
+
+Ломающий релиз. Приводит пакет в полное соответствие контракту Game Server API v1.0.0.
+
+> **TL;DR что менять в игре:**
+> 1. `/play` хендлер: убрать обёртку `results`, переименовать поля, добавить `hasMaxWin`.
+> 2. `/config` хендлер: убрать `gameTitle`, заменить `hasVariableLines` на `hasVariableLevels`, добавить `hasValidate`.
+> 3. `registerGameConfig`: убрать `gameTitle`, `hasVariableLines` → `hasVariableLevels`, `hasValidation` → `hasValidate`.
+> 4. `/validate` хендлер: обновить запрос и вернуть `{ valid: boolean, reason?: string }`.
+
+### 1. `/play` ответ — уплощение и переименования
+
+Обёртка `results` удалена. Все поля возвращаются на верхнем уровне.
+
+```diff
+ // handlers.register('play', async (request): Promise<TPlayReply> => {
+ return {
+     gameResponse: {},
+     rng: [],
+-    results: {
+-        coins: 250,
+-        cashWin: 2.5,
+-        finished: true,
+-    },
++    winCoins: 250,
++    winCash: 2.5,
++    finished: true,
++    hasMaxWin: false,
+ }
+```
+
+| Старое | Новое |
+|---|---|
+| `results.cashWin` | `winCash` |
+| `results.coins` | `winCoins` |
+| `results.finished` | `finished` |
+| `results.choices` | `choices` |
+| `results.meta` | `meta` |
+| — | `hasMaxWin` (обязательное) |
+| — | `choice` (эхо choice на continuation-шагах) |
+
+**`hasMaxWin`** — обязательное поле в каждом ответе. При достижении max-win: `hasMaxWin: true` + `finished: true` одновременно. Незавершённый раунд с `hasMaxWin: true` является ошибкой.
+
+### 2. `/play` запрос — тип `choice`
+
+`choice` расширен до `number | string` (раньше был только `integer`). Аналогично `choices` в ответе стал `(number | string)[]`.
+
+### 3. `/config` ответ
+
+```diff
+ {
+-    gameTitle: 'My Game',
+     gameId: 'my-game',
+     ...
+-    hasVariableLines: false,
++    hasVariableLevels: false,
+     coinRatio: 10,
+     ...
++    hasValidate: false,
+ }
+```
+
+| Старое | Новое |
+|---|---|
+| `gameTitle` | удалено |
+| `hasVariableLines` | `hasVariableLevels` |
+| — | `hasValidate` (обязательное) |
+
+**Новые инварианты** при `hasMultiStake === true`:
+- `freeroundsAllowed` должен быть `false`
+- `hasValidate` должен быть `true`
+
+### 4. `registerGameConfig`
+
+```diff
+ registerGameConfig({
+-    gameTitle: 'My Game',
+     gameId: 'my-game',
+     ...
+-    hasVariableLines: false,
++    hasVariableLevels: false,
+     coinRatio: 10,
+-    hasValidation: true,   // legacy
++    hasValidate: true,
+ })
+```
+
+| Старое | Новое |
+|---|---|
+| `gameTitle` | удалено |
+| `hasVariableLines` | `hasVariableLevels` |
+| `hasValidation` | `hasValidate` (обязательное при `hasMultiStake === true`) |
+
+### 5. `/validate` запрос и ответ
+
+**Запрос** — поля `metaPublic`/`metaPrivate` (строки) удалены, заменены на `meta: { public, private }` (объект); `demo` → `isDemo`; `currencyDecimals` и `stakes` стали обязательными.
+
+```diff
+-{
+-    demo: true,
+-    currencyDecimals: 2,
+-    stakes: [{ name: 'default', amount: 3 }],
+-    maxExposure: 100000,
+-    metaPublic: '{"someProgress": 15}',
+-    metaPrivate: '{"seed": "..."}',
+-}
++{
++    isDemo: true,
++    currencyDecimals: 2,
++    stakes: [{ name: 'default', amount: 3 }],
++    maxExposure: 100000,
++    meta: {
++        public: { someProgress: 15 },
++        private: { seed: '...' },
++    },
++}
+```
+
+**Ответ** — хендлер теперь возвращает вердикт, а не пустой объект:
+
+```diff
+-handlers.register('validate', async (): Promise<TValidateReply> => ({}))
++handlers.register('validate', async (request): Promise<TValidateReply> => {
++    // Validate stake set — e.g. check that max win cannot exceed maxExposure
++    const isValid = checkStakes(request.body.stakes, request.body.maxExposure)
++    if (!isValid) {
++        return { valid: false, reason: 'potential win exceeds maxExposure' }
++    }
++    return { valid: true }
++})
+```
+
+`valid: false` возвращается со статусом `200` — это деловой вердикт, не ошибка. RGS не откроет раунд при `valid: false`. Некорректный запрос (отсутствуют обязательные поля) — по-прежнему `400`.
+
+### 6. `StakeMode.parametric` — стало опциональным
+
+```diff
+-{ name: 'default', type: 'default', bets: 1, parametric: false }
++{ name: 'default', type: 'default', bets: 1 }
+```
+
+Отсутствие `parametric` эквивалентно `false`. Существующий код, передающий `parametric: false`, продолжает работать.
+
+### 7. Money-хелперы (новое)
+
+Пакет теперь экспортирует decimal-хелперы. Используйте их для вычисления `winCash`/`winCoins` вместо нативной float-арифметики:
+
+```typescript
+import { Big, roundMoney, isExactDecimal } from '@truelab/trueserver'
+
+const winCash = roundMoney(new Big(coins).times(coinValue), currencyDecimals)
+// winCash — точное decimal-число без float-дрейфа
+```
+
+### Чек-лист
+
+1. `npm install @truelab/trueserver@0.1.0`.
+2. `/play` хендлер: убрать `results`, переименовать `cashWin`→`winCash`, `coins`→`winCoins`, добавить `hasMaxWin`.
+3. `/config` хендлер: убрать `gameTitle`, `hasVariableLines`→`hasVariableLevels`, добавить `hasValidate`.
+4. `registerGameConfig`: убрать `gameTitle`, `hasVariableLines`→`hasVariableLevels`, `hasValidation`→`hasValidate`.
+5. `/validate` хендлер: обновить форму запроса (убрать `metaPublic`/`metaPrivate`, добавить `meta`; `demo`→`isDemo`); вернуть `{ valid: boolean, reason?: string }`.
+6. Проверить инварианты: если `hasMultiStake: true` — `freeroundsAllowed: false` и `hasValidate: true`.
+7. Обновить тесты: плоский ответ `/play`, новые поля, новый контракт `/validate`.
+8. Прогнать тесты.
+
+---
+
+## Migration: 0.0.6 → 0.0.7
+
+Не ломающее изменение. `rtpVersion` в `registerGameConfig` стал опциональным, чтобы один инстанс мог обслуживать все RTP-версии, выбирая их по сегменту `{rtpVersion}` пути.
+
+> **TL;DR:**
+> - Хотите как раньше (один инстанс = один RTP) — ничего менять не нужно, `rtpVersion` в `registerGameConfig` продолжает работать и сверяется.
+> - Хотите один инстанс на все RTP — **не передавайте** `rtpVersion` в `registerGameConfig`, а в reply `handlers.register('config', ...)` возвращайте `rtpVersion` из `request.params.rtpVersion`.
+
+### Режим «один инстанс — все RTP»
+
+```diff
+ registerGameConfig({
+     gameTitle: 'My Game',
+     gameId: 'my-game',
+-    rtpVersion: '96',
+     ...
+ })
+```
+
+```diff
+ handlers.register('config', async (request) => ({
+     ...
+-    rtpVersion: '96',
++    rtpVersion: request.params.rtpVersion,
+     ...
+ }))
+```
+
+Правила валидации `/config`:
+- `rtpVersion` ответа **всегда** сверяется с сегментом `{rtpVersion}` пути (несовпадение → `500` `code=1006`);
+- с `gameConfig.rtpVersion` — **только если** он задан (single-RTP режим).
+
+Все остальные RTP-зависимые поля (`rtp`, `volatility`, при необходимости `coinRatio`/`variableLevels`) тоже выбирайте по `request.params.rtpVersion`. Помните, что `coinRatio`/`variableLevels`/`defaultLevel` по-прежнему сверяются с `gameConfig`, поэтому при их различии между RTP single-config сверка не подойдёт.
+
+---
+
+## Migration: 0.0.5 → 0.0.6
+
+Документация GS Documentation обновлена после релиза 0.0.5. Изменения локальные, но breaking: новое обязательное поле в `/config` и опциональное в `Stake`.
+
+> **TL;DR что менять в игре:**
+> 1. В `registerGameConfig(...)` добавить `rtpVersion: '96'` (или ваш лейбл).
+> 2. В `handlers.register('config', ...)` добавить `rtpVersion` в reply (тот же, что в `gameConfig`, и совпадающий с path-сегментом).
+> 3. Опционально: добавить `coinValue` в `Stake` для игр с coin-механикой (запросы продолжают приниматься и без него).
+> 4. Перепроверить `Stake.amount`: теперь это **полная сумма** (включая `StakeMode.bets` и `qty`), а не «на одну ставку».
+
+### 1. `/config` reply → новое обязательное `rtpVersion`
+
+```diff
+ {
+     "gameTitle": "Book of Odin",
+     "gameId": "book-of-odin",
+     "volatility": 2.5,
+     "rtp": "96.17",
++    "rtpVersion": "96",
+     "hasMeta": true,
+     ...
+ }
+```
+
+`rtpVersion` — лейбл RTP-бакета (`"96"`, `"97"`, …). Он:
+- совпадает с сегментом `{rtpVersion}` пути, под которым смонтирован endpoint;
+- 1:1 с `rtp` (одной RTP-версии — один точный `rtp` и один `rtpVersion`);
+- сверяется с `gameConfig.rtpVersion` и с `request.params.rtpVersion`. Несовпадение → `500` с `code=1006`.
+
+### 2. `TGameConfig.rtpVersion`
+
+```diff
+ registerGameConfig({
+     gameTitle: 'My Game',
+     gameId: 'my-game',
++    rtpVersion: '96',
+     ...
+ })
+```
+
+`registerGameConfig` падает на старте, если `rtpVersion` пустой или не строка.
+
+### 3. `Stake.coinValue` (опционально)
+
+```diff
+ {
+     "name": "regular",
+     "amount": 1.0,
++    "coinValue": 0.1,
+     "level": 9
+ }
+```
+
+Игры без coin-механики (рулетки и т.п.) **не передают** это поле. Пакет не проверяет его наличие/отсутствие — формат остаётся на стороне игры.
+
+### 4. `Stake.amount` — новая семантика
+
+Ничего в схеме менять не нужно, но **читать значение** теперь надо по-другому:
+
+```
+amount = baseBetAmount × StakeMode.bets × (qty ?? 1)
+```
+
+`baseBetAmount` — стоимость одной базовой ставки в валюте (`coinValue × coinRatio` для fixed-line; `coinValue × level` для variable-line).
+
+`qty` **уже учтён** в `amount` — нельзя умножать ещё раз.
+
+### Чек-лист
+
+1. `npm install @truelab/trueserver@0.0.6`.
+2. Добавить `rtpVersion` в `registerGameConfig({...})`.
+3. Добавить `rtpVersion` в reply `handlers.register('config', ...)` — должен совпадать с тем, что в `gameConfig`, и с path-сегментом.
+4. Перепроверить расчёт `Stake.amount` в обработчике `/play`.
+5. Если используется coin-механика — добавить `coinValue` в формирование тестовых запросов / mocks.
+6. Прогнать тесты.
+
+---
+
+## Migration: 0.0.4 → 0.0.5
+
+Этот документ описывает все изменения контракта между 0.0.4 и 0.0.5.
+0.0.5 приводит пакет в соответствие со спецификацией [GS Documentation 1.0.0](https://www.notion.so/truelab/GS-Documentation-36dd90f8c00680d485d4e4e3eba928f0).
+
+Релиз помечен как **patch**, но **является ломающим**: меняются методы и пути роутов, формат ответов, имена и формы полей, удаляются enum'ы и флаги. Игры, использующие 0.0.4, не запустятся на 0.0.5 без правок.
+
+> **TL;DR что менять в игре:**
+> 1. `registerGameConfig(...)` — новые имена/набор полей.
+> 2. `handlers.register('config', ...)` — новый ответ.
+> 3. `handlers.register('play', ...)` — новый `request` и `reply`; в реквесте `request.params.rtpVersion` доступен.
+> 4. `handlers.register('client', ...)` — убрать `ok: true`, добавить `test` если нужен cheat-tool.
+> 5. Добавить `handlers.register('checksum', ...)`.
+> 6. Везде, где раньше возвращали ошибку — теперь формат `{ status, code, message }`.
+
+## 1. Маршруты и методы
+
+| Старое | Новое |
+|---|---|
+| `POST /healthcheck` | **`GET`** `/healthcheck` (без `:rtpVersion`) |
+| `POST /config` | **`GET`** `/:rtpVersion/config` |
+| `POST /client` | **`GET`** `/:rtpVersion/client` |
+| — | **`GET`** `/:rtpVersion/checksum` (новый) |
+| `POST /play` | `POST` `/:rtpVersion/play` |
+| `POST /validate` | `POST` `/:rtpVersion/validate` |
+
+- `{rtpVersion}` — путь-сегмент (`96`, `97`, `98` и т. п.). Игра получает его из `request.params.rtpVersion` (`TRtpParams` — см. `helpers/handlers.helper.ts`).
+- `ROUTE_PREFIX` оборачивает оба варианта. Например, `ROUTE_PREFIX=/api/v1` даёт `GET /api/v1/healthcheck` и `POST /api/v1/96/play`.
+
+## 2. Аутентификация
+
+API-ключ теперь проверяется на **всех** HTTP-методах (включая `GET`). Раньше — только на `POST`. Если у внешней инфраструктуры есть GET-пробы без заголовка `X-API-KEY`, их нужно обновить.
+
+## 3. Формат ошибок
+
+Старое:
+
+```json
+{ "ok": false, "message": "...", "custom": null }
+```
+
+Новое:
+
+```json
+{ "status": false, "code": 4001, "message": "..." }
+```
+
+`code` — целое число. Диапазоны:
+
+| Диапазон | Категория |
+|---|---|
+| `1xxx` | Валидация |
+| `2xxx` | Аутентификация |
+| `4xxx` | Бизнес-правила |
+| `9xxx` | Internal / unhandled |
+
+Константы — в `EErrorCode` (экспорт из корня пакета). Для собственных ошибок используйте `httpError(message, statusCode, code)`:
+
+```typescript
+import { EErrorCode, httpError } from '@truelab/trueserver'
+
+throw httpError('Unknown choice', 400, EErrorCode.BusinessChoiceUnknown)
+```
+
+## 4. `TGameConfig` (вход `registerGameConfig`)
+
+| Старое | Новое |
+|---|---|
+| `name` | `gameTitle` |
+| — | `gameId` (новое, общий ID для всех RTP) |
+| `hasMeta` | `hasMeta` |
+| `hasChoice` | `hasChoice` (теперь требует `hasMeta=true`) |
+| `hasBuy` | — (удалено) |
+| `hasGamble` | — (удалено) |
+| — | `hasRestore` (новое) |
+| `hasMultiStake` | `hasMultiStake` |
+| `hasValidation` | `hasValidation` (опциональное, оставлено для `/validate`) |
+| — | `hasVariableLines` (новое; раньше определялось по наличию `variableLevels`) |
+| `variableLevels: number` (целое) | `variableLevels: number[]` (массив доступных уровней) |
+| — | `defaultLevel: number` (обязателен при `hasVariableLines=true`) |
+| `coinRatio?` | `coinRatio` (required при `hasVariableLines=false`) |
+
+`registerGameConfig` теперь бросает при нарушении:
+- `hasChoice=true` без `hasMeta=true`;
+- `hasVariableLines=true` без непустого `variableLevels` или с `defaultLevel ∉ variableLevels`;
+- `hasVariableLines=false` без `coinRatio`.
+
+## 5. `/config` reply
+
+| Старое | Новое |
+|---|---|
+| `ok: true` | — (убрать, успех — plain JSON без обёртки) |
+| `name` | `gameTitle` |
+| — | `gameId` |
+| `category: ECategory` | — (удалено) |
+| `rtp: number` | `rtp: string` (десятичная строка, например `"96.17"`) |
+| `volatility: EVolatility` (enum-строка, опционально) | `volatility: number` из `{0.5, 1, 1.5, …, 5}` (обязательное) |
+| `hitrate?: number` | — (удалено) |
+| `apiVersion: number` | — (удалено) |
+| `hasBuy`, `hasGamble`, `hasValidation` | — (удалены из reply; `hasValidation` остался в `TGameConfig`) |
+| — | `hasRestore: boolean` |
+| — | `hasVariableLines: boolean` |
+| `variableLevels: number` | `variableLevels?: number[]` |
+| — | `defaultLevel?: number` |
+| `minWin?: number` | `minWin: number` (обязательное, множитель ставки) |
+| `maxWin: number` | `maxWin: number` (множитель ставки) |
+| `coinRatio?: number` | `coinRatio?: number` |
+| `stakeModes: StakeMode[]` | без изменений |
+
+Удалены enum'ы: `ECategory`, `EVolatility`.
+
+## 6. `/play` request
+
+| Старое | Новое |
+|---|---|
+| `demo: boolean` | `isDemo: boolean` |
+| `currencyDecimals?: number` | `currencyDecimals: integer` (обязательное) |
+| — | `stepIndex: integer` (новое; `0` для opening step, инкремент на каждое продолжение) |
+| `stakes?: Stake[]` | `stakes?: Stake[]` — только на opening step; уникальные `name` |
+| `choice?: integer` | `choice?: integer` — обязателен на continuation step при `hasChoice=true` |
+| `metaPrivate?: string`, `metaPublic?: string` | `meta?: { public, private }` — один объект |
+| `isGambleAllowed?: boolean` | — (удалено) |
+| `test?: string` | `test?: string` — игнорируется в production |
+
+## 7. `/play` reply
+
+| Старое | Новое |
+|---|---|
+| `ok: true` | — (убрать) |
+| `rng: string` (stringified JSON) | `rng: Array<{ value: number, ... }>` |
+| `finished: boolean` (top-level) | `results.finished: boolean` |
+| `results.response: string` (stringified JSON) | `gameResponse: object` (top-level) |
+| `results.winCash` | `results.cashWin` |
+| `results.winCoins?` | `results.coins?` |
+| `metaPrivate?`, `metaPublic?` (top-level, strings) | `results.meta?: { public, private }` |
+| `choices?: number[]` (top-level) | `results.choices?: integer[]` (non-empty, не `null`/`[]`) |
+| `analytics?` | — (удалено) |
+
+Контракт `choices`: должен присутствовать тогда и только тогда, когда `hasChoice=true` и `results.finished=false`.
+
+## 8. `/client` reply
+
+| Старое | Новое |
+|---|---|
+| `ok: true` | — (убрать) |
+| `data: object` | `data: object` |
+| — | `test?: object` (опциональное; RGS фильтрует для не-test-сессий) |
+
+## 9. `/healthcheck` reply
+
+| Старое | Новое |
+|---|---|
+| `code: 200` | — |
+| `status: true` | — |
+| `service: string` | `gameId: string` |
+| `environment` | `environment` |
+| `uptime: number` | `uptime: number` |
+| `message: 'OK'` | — |
+| `timestamp: integer` | `timestamp: integer` (ms) |
+| `metrics: {...}` | — (плагин `metrics` удалён) |
+| `services: { sentry }` | — |
+| — | `ok: true` (новое) |
+
+## 10. `/checksum` (новый эндпоинт)
+
+`GET /:rtpVersion/checksum`:
+
+```json
+{
+    "files": [
+        { "path": "src/math/probabilities.json", "hash": "9f86..." },
+        { "path": "src/math/paytable.json", "hash": "6c1b..." }
+    ]
+}
+```
+
+Алгоритм хэширования и набор файлов согласуются с RGS-командой при деплое.
+
+## 11. `/validate` (без изменений, но патч)
+
+`/validate` сохранён как был (вне новой спеки) для обратной совместимости. Изменилось только:
+- Reply теперь пустой объект `{}` (раньше `{ ok: true }`).
+- Endpoint, как и остальные версионированные, доступен под `/:rtpVersion/validate`.
+
+`hasValidation` остался во входе `registerGameConfig` как опциональный флаг. Если `false`, плагин валидации `/validate` отбивает запросы 400-кодом.
+
+## 12. Удалённые экспорты
+
+- `ECategory`, `EVolatility` — удалены полностью.
+- `TMetrics`, `MetricsSchema`, `metricsPlugin` — удалены.
+- `winCash`/`winCoins`/`metaPrivate`/`metaPublic` в `/play` — удалены (см. п. 7).
+- `apiVersion`, `hitrate`, `category`, `hasBuy`, `hasGamble` — удалены из `/config`.
+
+## 13. Что появилось
+
+- `EErrorCode`, `TErrorCode` — нумерация ошибок.
+- `MetaSchema`, `TMeta` — схема `{ public, private }`.
+- `ChecksumReplySchema`, `ChecksumRequestSchema`, `TChecksumReply`, `TChecksumRequest`.
+- `TRtpParams = { rtpVersion: string }` — тип path-параметра.
+- `FastifyError$Coded` — расширение `FastifyError` с полем `errorCode`.
+- `httpError(message, statusCode, code)` — третий параметр для машинного кода ошибки.
+
+## 14. Чек-лист обновления игры
+
+1. `npm install @truelab/trueserver@0.0.5`.
+2. Привести `registerGameConfig({...})` к новой форме (см. п. 4).
+3. Переписать `handlers.register('config', ...)` под новый reply (см. п. 5).
+4. Переписать `handlers.register('play', ...)` — request/reply (см. пп. 6, 7). `meta` теперь объект, а не два string'а.
+5. В `handlers.register('client', ...)` убрать `ok: true`. При необходимости добавить поле `test`.
+6. Зарегистрировать `handlers.register('checksum', ...)` (если интегрируется проверка целостности).
+7. Если был `handlers.register('validate', ...)` с `ok: true` — теперь возвращать `{}`.
+8. Сменить все собственные ошибки на формат `{ status, code, message }` или использовать `httpError(..., code)`.
+9. Обновить тесты: пути с `/:rtpVersion`, методы GET для `/config`/`/client`/`/checksum`, GET для `/healthcheck`, новые имена полей.
+10. Обновить URL-ы на стороне RGS-конфига для каждой игры.
+
+## Вопросы
+
+Регрессии и нерешённые ситуации — в Slack `#truelab-games-platform` или к командe RGS.