@truelab/trueserver 0.0.3 → 0.0.6

package/CHANGELOG.md

@@ -6,6 +6,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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,303 @@
+# Migration
+
+- [0.0.5 → 0.0.6](#migration-005--006) (последнее)
+- [0.0.4 → 0.0.5](#migration-004--005)
+
+---
+
+## 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.

package/README.md

@@ -1,13 +1,13 @@
 # @truelab/trueserver
 
-Fastify-based server package for TrueLab games.
+Fastify-based server package for TrueLab games. Implements the **Game Server** contract described in [GS Documentation](https://www.notion.so/truelab/GS-Documentation-36dd90f8c00680d485d4e4e3eba928f0).
 
-The package provides ready-to-use HTTP routes, request/response validation, shared TypeBox schemas, API key checks, Sentry integration, and Swagger UI for local development. A game server only needs to register game metadata and route handlers.
+The package provides HTTP routes, TypeBox request/response schemas, API-key authentication, error envelope, Sentry integration and Swagger UI. A game team only needs to call `registerGameConfig`, register handlers and start the server.
 
 ## Requirements
 
-- Node.js 22.12+ (uses `require()` of an ESM-only `typebox` dependency)
-- npm package access for `@truelab/trueserver`
+- Node.js 22.12+
+- npm access to `@truelab/trueserver`
 
 ## Installation
 
@@ -17,18 +17,15 @@ npm install @truelab/trueserver
 
 ## Quick Start
 
-Register game config and handlers before building the Fastify app:
-
 ```typescript
 import {
     Application,
-    ECategory,
     EStakeType,
-    EVolatility,
     handlers,
     getenv,
     logger,
     registerGameConfig,
+    type TChecksumReply,
     type TClientReply,
     type TConfigReply,
     type TPlayReply,
@@ -44,57 +41,61 @@ const stakeModes = [{
 }]
 
 registerGameConfig({
-    name: 'My Game',
+    gameTitle: 'My Game',
+    gameId: 'my-game',
+    rtpVersion: '96',
     stakeModes,
-    hasBuy: false,
-    hasChoice: false,
-    hasGamble: false,
     hasMeta: false,
+    hasChoice: false,
+    hasRestore: false,
     hasMultiStake: false,
-    hasValidation: false,
+    hasVariableLines: false,
     coinRatio: 10,
 })
 
-handlers.register('client', async (): Promise<TClientReply> => ({
-    ok: true,
-    data: {},
-}))
-
 handlers.register('config', async (): Promise<TConfigReply> => ({
-    ok: true,
-    name: 'My Game',
-    category: ECategory.slots,
-    stakeModes,
-    rtp: 96,
-    hitrate: 25,
-    volatility: EVolatility.med,
+    gameTitle: 'My Game',
+    gameId: 'my-game',
+    volatility: 2.5,
+    rtp: '96.17',
+    rtpVersion: '96',
     hasMeta: false,
     hasChoice: false,
-    hasBuy: false,
+    hasRestore: false,
     hasMultiStake: false,
-    hasValidation: false,
-    hasGamble: false,
-    freeroundsAllowed: false,
+    hasVariableLines: false,
+    coinRatio: 10,
     minWin: 0.1,
     maxWin: 5000,
-    apiVersion: 0,
-    coinRatio: 10,
+    freeroundsAllowed: false,
+    stakeModes,
 }))
 
-handlers.register('play', async (): Promise<TPlayReply> => ({
-    ok: true,
-    rng: '[]',
-    finished: true,
-    results: {
-        response: '{}',
-        winCash: 0,
-    },
+handlers.register('client', async (): Promise<TClientReply> => ({
+    data: {},
 }))
 
-handlers.register('validate', async (): Promise<TValidateReply> => ({
-    ok: true,
+handlers.register('play', async (request): Promise<TPlayReply> => {
+    // request.params.rtpVersion is available for routing math by RTP
+    return {
+        gameResponse: {},
+        rng: [],
+        results: {
+            cashWin: 0,
+            finished: true,
+        },
+    }
+})
+
+handlers.register('checksum', async (): Promise<TChecksumReply> => ({
+    files: [
+        { path: 'src/math/spin.js', hash: '...' },
+    ],
 }))
 
+// Optional. `hasValidation` is a legacy flag — kept for backward compatibility.
+handlers.register('validate', async (): Promise<TValidateReply> => ({}))
+
 async function main() {
     const app = new Application()
     const server = await app.build()
@@ -111,63 +112,74 @@ main().catch((error) => {
 })
 ```
 
-`registerGameConfig` must be called before `app.build()`: validation plugins read this config while the server is being built.
+`registerGameConfig` must be called before `app.build()` — validation plugins read the config while the server is being built. The function throws if invariants are violated (e.g. `hasChoice=true` without `hasMeta=true`, or `hasVariableLines=true` without `variableLevels`/`defaultLevel`).
 
 ## Runtime API
 
-The server registers these routes:
+`{rtpVersion}` is a path segment (e.g. `96`, `97`, `98`) — RGS picks the correct RTP per call. Game Server receives it as `request.params.rtpVersion`.
 
 | Method | Path | Handler | Description |
 | ------ | ---- | ------- | ----------- |
-| `POST` | `/client` | `handlers.register('client', ...)` | Client settings payload |
-| `POST` | `/config` | `handlers.register('config', ...)` | Public game config |
-| `POST` | `/play` | `handlers.register('play', ...)` | Game round calculation |
-| `POST` | `/validate` | `handlers.register('validate', ...)` | Optional stake/meta validation |
-| `POST` | `/healthcheck` | built in | Service status and metrics |
+| `GET` | `/healthcheck` | built-in | Liveness/readiness probe |
+| `GET` | `/:rtpVersion/config` | `handlers.register('config', ...)` | Game config (RTP-specific) |
+| `GET` | `/:rtpVersion/client` | `handlers.register('client', ...)` | Client-side payload |
+| `GET` | `/:rtpVersion/checksum` | `handlers.register('checksum', ...)` | File hashes for integrity check |
+| `POST` | `/:rtpVersion/play` | `handlers.register('play', ...)` | One step of a round |
+| `POST` | `/:rtpVersion/validate` | `handlers.register('validate', ...)` | Legacy stake/meta pre-validation (off by default) |
 
-All `POST` routes require an API key header. By default the server expects `x-api-key: test`; configure it with `API_HEADER` and `API_KEY`.
+Every request must carry the API key header. By default it is `x-api-key: test`; override with `API_HEADER` and `API_KEY`.
 
-`ROUTE_PREFIX` is applied to all routes. For example, `ROUTE_PREFIX=/api/game` turns `/play` into `/api/game/play`.
+`ROUTE_PREFIX` is prepended to every route. For `ROUTE_PREFIX=/api/v1`, the play endpoint becomes `POST /api/v1/96/play`. `/healthcheck` is always mounted directly under the prefix (no `{rtpVersion}` segment).
 
-## Imports
+## Error envelope
 
-Use the root entry for runtime code, schemas, enums, helpers, and public types:
+Non-2xx responses follow:
+
+```json
+{
+    "status": false,
+    "code": 4001,
+    "message": "Invalid choice value"
+}
+```
+
+Recommended code ranges: `1xxx` validation, `2xxx` auth, `4xxx` business, `9xxx` internal. The `EErrorCode` enum exports the codes used by this package.
 
 ```typescript
-import {
-    Application,
-    EStakeType,
-    PlayRequestSchema,
-    handlers,
-    registerGameConfig,
-    type TPlayReply,
-} from '@truelab/trueserver'
+import { EErrorCode, httpError } from '@truelab/trueserver'
+
+throw httpError('Invalid choice value', 400, EErrorCode.BusinessChoiceUnknown)
 ```
 
-Test helpers are intentionally published through a separate entry:
+## Test utilities
 
 ```typescript
-import { testBuild } from '@truelab/trueserver/test-utils'
+import {
+    checkSchemaPropertyDescriptions,
+    testBuild,
+    testHeaders,
+    validator,
+} from '@truelab/trueserver/test-utils'
 ```
 
-Published code is compiled into `dist/`; package `exports` exposes only the public root entry and test utilities.
+`test-utils` uses Jest globals (`expect`), so consumers should keep `jest` and usually `@types/jest` in `devDependencies`.
 
-## Environment Variables
+## Environment variables
 
 | Variable | Default | Description |
 | -------- | ------- | ----------- |
-| `HOST` | `localhost` | Listen host used by the consuming game server |
-| `PORT` | `2980` | Listen port used by the consuming game server |
-| `ROUTE_PREFIX` | empty | Prefix for all autoloaded routes |
-| `API_HEADER` | `x-api-key` | Header name used by the API key plugin |
-| `API_KEY` | `test` | Expected API key for `POST` requests |
+| `HOST` | `localhost` | Listen host |
+| `PORT` | `2980` | Listen port |
+| `ROUTE_PREFIX` | empty | Prefix for all routes |
+| `API_HEADER` | `x-api-key` | Header name used by API-key plugin |
+| `API_KEY` | `test` | Expected API key value |
 | `LOG_LEVEL` | `error` | Pino log level |
-| `APP_ENV` | unset | `dev`, `release`, or `master`; controls Swagger and environment mapping |
+| `APP_ENV` | unset | `dev`, `release`, `master`; controls Swagger and environment mapping |
 | `SENTRY_DSN` | unset | Sentry DSN |
 | `SENTRY_RATE` | `0.01` | Sentry traces sample rate |
-| `GAME_ID` | `0001` | Sentry `game.id` tag |
+| `GAME_ID` | `0001` | Sentry `game.id` tag fallback |
 
-The environment helper imports `dotenv/config`, so `.env` is loaded when `@truelab/trueserver` is imported.
+The environment helper imports `dotenv/config`, so `.env` is loaded automatically.
 
 ## Swagger
 
@@ -175,45 +187,31 @@ Swagger UI is enabled only for `APP_ENV=dev`.
 
 - `GET /` redirects to `/docs`
 - `GET /docs` serves Swagger UI
-- `release` and `master` disable Swagger UI
 
-When `ROUTE_PREFIX` is set, it affects game routes, not the Swagger UI route.
+`release` and `master` disable Swagger UI.
 
 ## Advanced Validation
 
-The package validates both requests and successful replies with TypeBox schemas. It also performs game-specific checks based on `registerGameConfig`.
+The package validates both requests and replies via TypeBox schemas and runs game-specific checks based on `registerGameConfig`:
 
-- `/config` checks stake modes and requires exactly one of `coinRatio` or `variableLevels`.
-- `/play` checks stakes, choices, meta data, gamble flag, and reply consistency.
-- `/validate` is available only when `hasValidation` is `true`.
-- `test` data is rejected in production mapping (`APP_ENV=master` or unset).
+- `/config` checks stake modes, the `hasChoice ⇒ hasMeta` invariant and the `hasVariableLines ⇔ {variableLevels, defaultLevel}` pair.
+- `/play` checks stakes (uniqueness, qty, level in `variableLevels`, parametric/params), `stepIndex` consistency (opening vs continuation), `choice`/`meta` presence per flags, and reply shape (`finished`, `choices`, `meta`).
+- `/validate` is available only when `hasValidation=true`.
+- `test` field is rejected on production (`APP_ENV=master` or unset).
 
-For stepped games, set `hasChoice: true`; for games with meta state, set `hasMeta: true`; for line/table variants, use `variableLevels` instead of `coinRatio`.
-
-## Test Utilities
-
-Integration tests in consuming game servers can import Jest helpers from:
-
-```typescript
-import {
-    checkSchemaPropertyDescriptions,
-    testBuild,
-    testHeaders,
-    validator,
-} from '@truelab/trueserver/test-utils'
-```
+## Migration
 
-`test-utils` uses Jest globals (`expect`), so the consuming project should keep `jest` and usually `@types/jest` in `devDependencies`.
+This release is breaking. See [MIGRATION.md](MIGRATION.md) for a full mapping of old fields/paths to new ones.
 
 ## Package Development
 
 ```bash
-npm test        # run Jest tests
-npm run build   # compile TypeScript to dist/
-npm pack        # build and inspect the npm tarball
+npm test
+npm run build
+npm pack
 ```
 
-`bitbucket-pipelines.yml` runs tests and build on the default branch. The custom `publish` pipeline publishes to npm with `NPM_PUBLISH_TOKEN`.
+`bitbucket-pipelines.yml` runs tests and build on the default branch.
 
 ## License
 

package/dist/application.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"application.d.ts","sourceRoot":"","sources":["../application.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,cAAc,EAAkB,MAAM,0BAA0B,CAAA;AAGzE,MAAM,CAAC,OAAO,OAAO,WAAW;IAC5B,MAAM,EAAE,cAAc,CAAA;;IAchB,KAAK,IAAI,OAAO,CAAC,cAAc,CAAC;CAiBzC"}
+{"version":3,"file":"application.d.ts","sourceRoot":"","sources":["../application.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,cAAc,EAAkB,MAAM,0BAA0B,CAAA;AAGzE,MAAM,CAAC,OAAO,OAAO,WAAW;IAC5B,MAAM,EAAE,cAAc,CAAA;;IAchB,KAAK,IAAI,OAAO,CAAC,cAAc,CAAC;CAuBzC"}