fix: change GAME_ROUNDS from strings to numbers

documentation/tickets/t00002.md

@@ -0,0 +1,149 @@
+# ADR: Change GAME_ROUNDS from strings to numbers
+
+## Status
+
+Accepted
+
+## Date
+
+2026-04-28
+
+## Context
+
+`GAME_ROUNDS` in `packages/shared/src/constants.ts` was typed as `["3", "10"] as const`, making `GameRounds` a string union (`"3" | "10"`). This meant `gameService.ts` had to cast the value with `Number(request.rounds)` deep in business logic — a type conversion happening far from the boundary where data enters the system. The type system was lying: `rounds` was described as a string everywhere but used as a number where it mattered.
+
+## Decision
+
+Change `GAME_ROUNDS` to `[3, 10] as const` and update the Zod schema to use `z.literal(GAME_ROUNDS)` instead of `z.enum(GAME_ROUNDS)`. The single source of truth remains `constants.ts` — adding a new round count (e.g. `20`) requires only editing that file.
+
+## Options considered
+
+### Option A — Numbers everywhere ✅
+
+Change `GAME_ROUNDS` to `[3, 10] as const`. Use `z.literal(GAME_ROUNDS)` in the schema. Update the frontend component state and `SettingGroup` props. Drop `Number()` cast in the service.
+
+Chosen because: JSON carries numbers natively, both ends of the wire are owned by this codebase, and type conversions belong at the boundary — not inside business logic.
+
+### Option B — Keep strings, accept the cast
+
+Leave `GAME_ROUNDS` as `["3", "10"]`. The `Number()` cast stays in `gameService.ts`.
+
+Rejected because: it pushes type conversion into business logic and makes the inferred `GameRequest` type misleading. The cast has to live somewhere — the schema boundary is the right place.
+
+### Option C — Coerce at the schema boundary
+
+Keep `GAME_ROUNDS` as numbers but use `z.coerce.number().pipe(z.literal(GAME_ROUNDS))` so the frontend can keep sending strings.
+
+Rejected because: coercion is for untrusted or uncontrolled inputs (form fields, query params, third-party clients). We control both ends of the wire. Coercing a self-inflicted type mismatch is treating a wound we gave ourselves.
+
+## Consequences
+
+- `GameRounds` is now `3 | 10` instead of `"3" | "10"`
+- `Number(request.rounds)` cast removed from `gameService.ts`
+- `SettingGroup` in `GameSetup.tsx` now accepts `string | number` options
+- `useState<string>` for rounds changed to `useState<number>`
+- Adding a new round count requires only editing `GAME_ROUNDS` in `constants.ts`
+- `z.enum` cannot be used for number literals — `z.literal` must be used instead (this is a Zod constraint, not a project convention)
+
+## Affected files
+
+- `packages/shared/src/constants.ts`
+- `packages/shared/src/schemas/game.ts`
+- `apps/api/src/services/gameService.ts`
+- `apps/api/src/services/gameService.test.ts`
+- `apps/api/src/controllers/gameController.test.ts`
+- `apps/web/src/components/game/GameSetup.tsx`
+
+## References
+
+- [Zod literals](https://zod.dev/?id=literals)
+
+---
+
+## Setup guide / implementation notes
+
+1. In `packages/shared/src/constants.ts`, change:
+
+   ```ts
+   export const GAME_ROUNDS = ["3", "10"] as const;
+   ```
+
+   to:
+
+   ```ts
+   export const GAME_ROUNDS = [3, 10] as const;
+   ```
+
+2. In `packages/shared/src/schemas/game.ts`, change:
+
+   ```ts
+   rounds: z.enum(GAME_ROUNDS),
+   ```
+
+   to:
+
+   ```ts
+   rounds: z.literal(GAME_ROUNDS),
+   ```
+
+3. In `apps/api/src/services/gameService.ts`, change:
+
+   ```ts
+   Number(request.rounds),
+   ```
+
+   to:
+
+   ```ts
+   request.rounds,
+   ```
+
+4. In `apps/api/src/services/gameService.test.ts`, change:
+
+   ```ts
+   rounds: "3",
+   ```
+
+   to:
+
+   ```ts
+   rounds: 3,
+   ```
+
+5. In `apps/api/src/controllers/gameController.test.ts`, change:
+
+   ```ts
+   rounds: "3",
+   ```
+
+   to:
+
+   ```ts
+   rounds: 3,
+   ```
+
+   Also add a pinning test before the refactor:
+
+   ```ts
+   it("returns 400 when rounds has an invalid value", async () => {
+     const res = await request(app)
+       .post("/api/v1/game/start")
+       .send({ ...validBody, rounds: "invalid" });
+     expect(res.status).toBe(400);
+     expect(res.body.success).toBe(false);
+   });
+   ```
+
+6. In `apps/web/src/components/game/GameSetup.tsx`:
+   - Update `SettingGroup` props to accept `string | number`:
+  
+     ```ts
+     type SettingGroupProps = {
+       options: readonly (string | number)[];
+       selected: string | number;
+       onSelect: (value: string | number) => void;
+     };
+     ```
+
+   - Update `LABELS` lookup to `LABELS[String(option)]`
+   - Change rounds state from `useState<string>` to `useState<number>`