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.

backend/internal/config/config.go

@@ -8,6 +8,7 @@ import (
 	"strconv"
 	"time"
 
+	"scrabble/backend/internal/game"
 	"scrabble/backend/internal/postgres"
 	"scrabble/backend/internal/telemetry"
 )
@@ -22,6 +23,8 @@ type Config struct {
 	Postgres postgres.Config
 	// Telemetry configures the OpenTelemetry providers.
 	Telemetry telemetry.Config
+	// Game configures the game subsystem (dictionaries, sweeper, live-game cache).
+	Game game.Config
 }
 
 // Defaults applied when the corresponding environment variable is unset.
@@ -54,11 +57,22 @@ func Load() (Config, error) {
 	tel.TracesExporter = envOr("BACKEND_OTEL_TRACES_EXPORTER", tel.TracesExporter)
 	tel.MetricsExporter = envOr("BACKEND_OTEL_METRICS_EXPORTER", tel.MetricsExporter)
 
+	gm := game.DefaultConfig()
+	gm.DictDir = envOr("BACKEND_DICT_DIR", gm.DictDir)
+	gm.DictVersion = envOr("BACKEND_DICT_VERSION", gm.DictVersion)
+	if gm.TimeoutSweepInterval, err = envDuration("BACKEND_GAME_TIMEOUT_SWEEP_INTERVAL", gm.TimeoutSweepInterval); err != nil {
+		return Config{}, err
+	}
+	if gm.CacheTTL, err = envDuration("BACKEND_GAME_CACHE_TTL", gm.CacheTTL); err != nil {
+		return Config{}, err
+	}
+
 	c := Config{
 		HTTPAddr:  envOr("BACKEND_HTTP_ADDR", defaultHTTPAddr),
 		LogLevel:  envOr("BACKEND_LOG_LEVEL", defaultLogLevel),
 		Postgres:  pg,
 		Telemetry: tel,
+		Game:      gm,
 	}
 	if err := c.validate(); err != nil {
 		return Config{}, err
@@ -82,6 +96,9 @@ func (c Config) validate() error {
 	if err := c.Telemetry.Validate(); err != nil {
 		return fmt.Errorf("config: %w", err)
 	}
+	if err := c.Game.Validate(); err != nil {
+		return fmt.Errorf("config: %w (set BACKEND_DICT_DIR)", err)
+	}
 	return nil
 }
 

backend/internal/config/config_test.go

@@ -17,6 +17,10 @@ func TestLoadDefaults(t *testing.T) {
 	t.Setenv("BACKEND_HTTP_ADDR", "")
 	t.Setenv("BACKEND_LOG_LEVEL", "")
 	t.Setenv("BACKEND_POSTGRES_DSN", testDSN)
+	t.Setenv("BACKEND_DICT_DIR", "/dict")
+	t.Setenv("BACKEND_DICT_VERSION", "")
+	t.Setenv("BACKEND_GAME_TIMEOUT_SWEEP_INTERVAL", "")
+	t.Setenv("BACKEND_GAME_CACHE_TTL", "")
 
 	c, err := Load()
 	if err != nil {
@@ -40,6 +44,18 @@ func TestLoadDefaults(t *testing.T) {
 	if c.Telemetry.TracesExporter != telemetry.ExporterNone {
 		t.Errorf("Telemetry.TracesExporter = %q, want %q", c.Telemetry.TracesExporter, telemetry.ExporterNone)
 	}
+	if c.Game.DictDir != "/dict" {
+		t.Errorf("Game.DictDir = %q, want /dict", c.Game.DictDir)
+	}
+	if c.Game.DictVersion != "v1" {
+		t.Errorf("Game.DictVersion = %q, want v1", c.Game.DictVersion)
+	}
+	if c.Game.TimeoutSweepInterval != time.Minute {
+		t.Errorf("Game.TimeoutSweepInterval = %s, want 1m", c.Game.TimeoutSweepInterval)
+	}
+	if c.Game.CacheTTL != 24*time.Hour {
+		t.Errorf("Game.CacheTTL = %s, want 24h", c.Game.CacheTTL)
+	}
 }
 
 // TestLoadOverrides verifies that environment variables override the defaults.
@@ -51,6 +67,10 @@ func TestLoadOverrides(t *testing.T) {
 	t.Setenv("BACKEND_POSTGRES_OPERATION_TIMEOUT", "3s")
 	t.Setenv("BACKEND_SERVICE_NAME", "scrabble-test")
 	t.Setenv("BACKEND_OTEL_TRACES_EXPORTER", "stdout")
+	t.Setenv("BACKEND_DICT_DIR", "/srv/dict")
+	t.Setenv("BACKEND_DICT_VERSION", "2026-06")
+	t.Setenv("BACKEND_GAME_TIMEOUT_SWEEP_INTERVAL", "30s")
+	t.Setenv("BACKEND_GAME_CACHE_TTL", "1h")
 
 	c, err := Load()
 	if err != nil {
@@ -59,6 +79,15 @@ func TestLoadOverrides(t *testing.T) {
 	if c.HTTPAddr != "127.0.0.1:9090" {
 		t.Errorf("HTTPAddr = %q, want %q", c.HTTPAddr, "127.0.0.1:9090")
 	}
+	if c.Game.DictDir != "/srv/dict" || c.Game.DictVersion != "2026-06" {
+		t.Errorf("Game dict = %q/%q, want /srv/dict/2026-06", c.Game.DictDir, c.Game.DictVersion)
+	}
+	if c.Game.TimeoutSweepInterval != 30*time.Second {
+		t.Errorf("Game.TimeoutSweepInterval = %s, want 30s", c.Game.TimeoutSweepInterval)
+	}
+	if c.Game.CacheTTL != time.Hour {
+		t.Errorf("Game.CacheTTL = %s, want 1h", c.Game.CacheTTL)
+	}
 	if c.LogLevel != "debug" {
 		t.Errorf("LogLevel = %q", c.LogLevel)
 	}
@@ -93,6 +122,17 @@ func TestLoadRejectsInvalidLevel(t *testing.T) {
 	}
 }
 
+// TestLoadRejectsMissingDictDir verifies that an unset dictionary directory fails
+// validation (the game subsystem cannot load without it).
+func TestLoadRejectsMissingDictDir(t *testing.T) {
+	t.Setenv("BACKEND_POSTGRES_DSN", testDSN)
+	t.Setenv("BACKEND_LOG_LEVEL", "info")
+	t.Setenv("BACKEND_DICT_DIR", "")
+	if _, err := Load(); err == nil {
+		t.Fatal("Load: expected an error for a missing dictionary dir, got nil")
+	}
+}
+
 // TestLoadRejectsMalformedInt verifies that a non-numeric pool size is rejected.
 func TestLoadRejectsMalformedInt(t *testing.T) {
 	t.Setenv("BACKEND_POSTGRES_DSN", testDSN)