Stage 3: game domain (lifecycle, journal+cache, hint, word-check, GCG, stats)
internal/game drives the engine over a single match and owns everything the
engine does not: event-sourced persistence (a games row + an append-only decoded
move journal, with the live engine.Game kept warm in a cache and rebuilt by
replay on a miss), the play/pass/exchange/resign transitions with
validate-at-submit scoring, an unlimited score/legality preview, the hint
(per-game allowance + profile wallet), the word-check tool with complaint
capture, per-player game state, history and GCG export (Poslfit dialect), and a
background turn-timeout sweeper that auto-resigns overdue turns honouring each
player's daily away window. Like Stages 1-2 it is a service/store layer with no
HTTP; the gateway surface lands in Stage 6.
Engine: additive decoded domain API (Direction, SubmitPlay/SubmitExchange/
EvaluatePlay/HintView/Hand, MoveRecord.{Dir,MainRow,MainCol}, Registry.Lookup,
ParseVariant) so internal/game never imports scrabble-solver; and a Resign fix
so the resigner keeps their score yet never wins (the other player wins a
two-player game). Timeout reuses Resign.
Persistence: migration 00002 adds games, game_players, game_moves, complaints,
account_stats and extends accounts with away_start/away_end/hint_balance; go-jet
regenerated. account gained SpendHint. Config adds BACKEND_DICT_DIR (required),
BACKEND_DICT_VERSION, BACKEND_GAME_TIMEOUT_SWEEP_INTERVAL, BACKEND_GAME_CACHE_TTL;
main loads the registry at boot (hard dependency) and starts the sweeper.
Tests: engine resign + decoded-API tests; game unit tests (GCG, away-window
boundaries, hint budget, cache, keyed mutex, payload); inttest integration
(lifecycle, replay equivalence, timeout sweep with away grace, resign stats,
hint policy, word-check/complaint, per-game-lock). Docs (PLAN, ARCHITECTURE,
FUNCTIONAL +_ru, TESTING, README) updated.
This commit is contained in:
+76
-30
@@ -111,10 +111,12 @@ Key points:
|
||||
`Erudit()`). Эрудит's specifics (non-doubling centre, `ё` with no tiles, 3
|
||||
blanks, a 15-point bonus) live entirely in the solver ruleset, so the engine
|
||||
treats every variant uniformly.
|
||||
- **Dictionaries** are committed DAWGs loaded with `dawg.Load` from a directory
|
||||
(a parameter today; a configurable `BACKEND_DICT_DIR` is wired when the first
|
||||
consumer needs it). The `engine.Registry` holds them in memory addressed by
|
||||
`(variant, dict_version)`, tracking the latest version per variant.
|
||||
- **Dictionaries** are committed DAWGs loaded with `dawg.Load` from the
|
||||
directory `BACKEND_DICT_DIR`; `backend` loads the `engine.Registry` at startup
|
||||
as a hard dependency (like migrations), so a missing dictionary fails the boot.
|
||||
The registry holds dictionaries in memory addressed by `(variant,
|
||||
dict_version)`, tracking the latest version per variant, and answers the
|
||||
word-check tool through `Registry.Lookup`.
|
||||
- **Dictionary versioning — pin per game.** A game records the `dict_version` it
|
||||
started on and finishes on that version; new games use the latest. Multiple
|
||||
versions may be resident at once. An admin reload *(planned, Stage 9)*
|
||||
@@ -130,10 +132,18 @@ Key points:
|
||||
- **`engine.Game`** is the in-memory match state and the pure rules engine: it
|
||||
deals racks, applies legal plays / passes / exchanges / resignations, refills
|
||||
from the bag, keeps the scores and whose turn it is, and **detects the end of
|
||||
the game** — empty bag with an empty rack, six consecutive scoreless turns, or
|
||||
a resignation — applying the end-game rack-value adjustment. The 24-hour
|
||||
timeout / auto-resign, turn scheduling and persistence belong to the game
|
||||
domain *(Stage 3)*.
|
||||
the game** — empty bag with an empty rack, or six consecutive scoreless turns,
|
||||
applying the end-game rack-value adjustment, or a resignation. On a
|
||||
**resignation the resigner keeps their accumulated score (no rack adjustment)
|
||||
and never wins**: the win goes to the highest score among the remaining seats,
|
||||
unconditionally the other player in a two-player game. The engine exposes a
|
||||
decoded, solver-free API (`SubmitPlay`/`SubmitExchange`/`EvaluatePlay`/
|
||||
`HintView`/`Hand`) so `internal/game` drives it without importing the solver.
|
||||
- The **game domain** (`internal/game`) owns everything the engine does not —
|
||||
persistence, turn scheduling, the configurable turn timeout / auto-resign, the
|
||||
hint budget, word-check complaints, history and GCG — and is the engine's only
|
||||
consumer. Timeout auto-resign reuses `engine.Resign`, recording the move as a
|
||||
timeout, so it inherits the resignation win/loss.
|
||||
- History is dictionary-independent (§9.1): the engine emits decoded
|
||||
`MoveRecord`s and reconstructs the board from them with `engine.ReplayBoard`
|
||||
(alphabet only, no dictionary).
|
||||
@@ -143,13 +153,29 @@ Key points:
|
||||
- **Word legality: validate-at-submit.** An illegal play is rejected by
|
||||
`Solver.ValidatePlay`; there is no challenge phase.
|
||||
- **End of game**: the bag is empty **and** a player empties their rack, **or**
|
||||
**6 consecutive scoreless turns** (passes/exchanges). A move that is not made
|
||||
within the **24-hour** turn timeout becomes an automatic resignation.
|
||||
**6 consecutive scoreless turns** (passes/exchanges), **or** a resignation, or
|
||||
a missed turn. The **per-game turn timeout** is chosen at creation
|
||||
(5/10/15/30 min, 1/2/3/6/12/24 h; default 24 h); a turn not made within it
|
||||
becomes an automatic resignation, applied by a background sweeper. The sweeper
|
||||
honours each player's **away window** — a daily local-time sleep interval on the
|
||||
account (default 00:00–07:00, midnight-cross aware) — so a player is never
|
||||
timed out while asleep.
|
||||
- **Players**: auto-match is always 2 players; friend games are 2–4 players.
|
||||
`backend` owns turn order and the bag for any player count.
|
||||
- **Hint**: one per game; reveals the top-1 ranked move (`GenerateMoves[0]`).
|
||||
- **Word-check tool**: unlimited dictionary lookups; each result offers a
|
||||
**complaint** that lands in an admin review queue *(admin side planned)*.
|
||||
`backend` owns turn order and the bag for any player count. A resignation or
|
||||
timeout in a two-player game ends it with the other player winning; **richer
|
||||
multi-player drop-out (a leaver's seat skipped while the rest play on, with a
|
||||
per-game disposition of their tiles) is deferred to Stage 4**, when friend games
|
||||
are formed.
|
||||
- **Hint**: governed by two per-game settings — whether hints are allowed and the
|
||||
starting per-player allowance — plus a per-account hint **wallet**
|
||||
(`hint_balance`, spent after the allowance; top-ups are a later feature). A hint
|
||||
reveals the top-1 ranked move (`GenerateMoves[0]`). The lobby/tournament caller
|
||||
picks the per-game defaults (e.g. one in casual random games, none in
|
||||
tournaments).
|
||||
- **Word-check tool**: unlimited dictionary lookups against the game's pinned
|
||||
dictionary; each result offers a **complaint** (complainant, game, variant,
|
||||
dict_version, word, the disputed result, an optional note) that lands in an
|
||||
admin review queue *(admin side planned, Stage 9)*.
|
||||
|
||||
## 7. Robot opponent
|
||||
|
||||
@@ -191,26 +217,46 @@ within 10 seconds. Designed to be indistinguishable from a person.
|
||||
into `internal/postgres/jet` and committed, regenerated by `cmd/jetgen`).
|
||||
Migrations are embedded SQL applied with `pressly/goose/v3` at startup. Primary
|
||||
keys are application-generated **UUIDv7**.
|
||||
- Stage 1 tables: `accounts` (durable internal accounts), `identities`
|
||||
(platform/email identities, unique `(kind, external_id)`) and `sessions`
|
||||
(revoke-only opaque-token hashes).
|
||||
- **Active game state** is stored structurally with the `dict_version` pinned.
|
||||
- **Statistics** (computed on finish): wins, losses, max points in a game, max
|
||||
points for a single word.
|
||||
- Tables: `accounts` (durable internal accounts; Stage 3 added the away-window
|
||||
columns `away_start`/`away_end` and the hint wallet `hint_balance`),
|
||||
`identities` (platform/email identities, unique `(kind, external_id)`),
|
||||
`sessions` (revoke-only opaque-token hashes), and the Stage 3 game tables
|
||||
`games`, `game_players`, `game_moves` (the move journal), `complaints` and
|
||||
`account_stats`.
|
||||
- **Active games are event-sourced.** A game is a `games` row (pinned
|
||||
`variant`/`dict_version`, bag `seed`, the per-game settings, and a denormalised
|
||||
turn cursor) plus an append-only, decoded move journal (`game_moves`); the live
|
||||
position is an `engine.Game` held in an in-memory cache (≈24 h idle TTL) and
|
||||
rebuilt by replaying the journal on a miss, which the seeded bag makes exact.
|
||||
Each game is serialised by a per-game lock; a persistence failure evicts the
|
||||
live game so the next access rebuilds from the journal. `game_players` records
|
||||
each seat's account, running score, hints used and winner flag.
|
||||
- **Statistics** (`account_stats`, recomputed on each finish, durable accounts
|
||||
only — guests never appear): wins, losses, **draws**, max points in a game, and
|
||||
max points for a single **move** (which already folds in every word the move
|
||||
formed plus the all-tiles bonus). A tie increments draws only; a resignation or
|
||||
timeout is a loss for the acting player.
|
||||
|
||||
### 9.1 History invariant (must hold forever)
|
||||
|
||||
Archived games must replay **independently of any dictionary and of the
|
||||
solver's internal encoding** — at least visually. Therefore the move log
|
||||
persists only **decoded concrete values**: letters as text, coordinates, blank
|
||||
flag, action kind (play / pass / exchange / resign / timeout), acting player,
|
||||
per-move score and running total, timestamp. The board for visual replay is
|
||||
reconstructed by applying placements onto an empty grid; no dictionary is
|
||||
needed because moves were validated at play time and scores are stored.
|
||||
`variant` and `dict_version` are kept as **metadata only** (audit, complaint
|
||||
review), never as a replay dependency. **GCG export** is derived from the same
|
||||
rows and is likewise self-contained (we ship our own writer; the solver exposes
|
||||
no public GCG writer).
|
||||
solver's internal encoding** — at least visually. Therefore the move journal
|
||||
persists only **decoded concrete values**: action kind (play / pass / exchange /
|
||||
resign / timeout), acting player, per-move score and running total, timestamp,
|
||||
and — in a per-move JSON payload — the acting player's rack before the move (with
|
||||
`?` for a blank), and for a play its direction, main-word anchor, placed tiles
|
||||
(letter as text, coordinate, blank flag) and the words formed; for an exchange,
|
||||
the swapped tiles. This is exactly what is needed both to **replay the game
|
||||
through the engine** (a cache miss) and to render history or emit GCG **without a
|
||||
dictionary**: the board for visual replay is reconstructed by applying placements
|
||||
onto an empty grid, since moves were validated at play time and scores are
|
||||
stored. `variant` and `dict_version` are kept as **metadata only** (audit,
|
||||
complaint review), never as a replay dependency. **GCG export** is derived from
|
||||
the same rows and is likewise self-contained — we ship our own writer (the solver
|
||||
exposes none): the standard Poslfit dialect (UTF-8, `#player`/`#lexicon`
|
||||
pragmas, `8G`/`H8` coordinates, lower-case blanks, `.` pass-throughs, `-TILES`
|
||||
exchanges), plus `#note` lines for resignations and timeouts, which the standard
|
||||
does not cover.
|
||||
|
||||
## 10. Notifications
|
||||
|
||||
|
||||
Reference in New Issue
Block a user