feat(server): initial implementation

This commit captures the full server code accumulated across
several development sessions. It includes the following layers,
applied in roughly this order during development:

1. Base infrastructure
   - cmd/poc-server HTTP+WebSocket server, /health, /stats
   - internal/transport wire types (Envelope + all message types)
   - internal/catalog, internal/realtime, internal/stats
   - internal/storage/postgres with migrations 001-004
   - .env, .env.example, docker-compose, Dockerfile, scripts/

2. Swagger documentation
   - go get github.com/swaggo/http-swagger
   - swag init produces docs/docs.go
   - /swagger/index.html UI, /swagger/doc.json spec
   - annotations on health/stats/ws and catalog handlers

3. Races API
   - internal/races/{store,service,keyset,types}.go
   - migration 005_races.sql: finished_races, race_plans, race_queue
   - GET /api/races with keyset pagination, status filter
   - GET /api/races/upcoming
   - POST /api/races/queue/join, GET, DELETE
   - POST/GET /api/races/plans, DELETE /{id}
   - lobby.RaceMeta simplification (no host_id/host_name)

4. Races seeder
   - internal/races/seed with deterministic generator
   - --seed-races / --reset CLI flags in main.go
   - 30 finished + 5 live + 5 plans + 4 queue entries

5. Drivers and clans
   - internal/drivers, internal/clans (CRUD, validation)
   - migration 008_drivers_clans.sql
   - /api/clans and /api/drivers endpoints
   - 3-letter uppercase nickname/tag validation
   - lobby.DriverMeta: Nickname, AvatarURL, ClanID, ClanTag

6. Podium
   - internal/transport.RacePodiumEntry
   - lobby.SetDriverProfile for in-memory metadata sync
   - migration 007_podium.sql (podium JSONB column)
   - seeder populates top-3 per finished race

7. Live races persistence
   - migration 009_live_persistence.sql: live_races,
     live_race_drivers, lobby_drivers
   - internal/races/live_store.go: LiveStore with write-side
     mirror for lobby.Service mutations
   - Service.collectLive and Upcoming read from Postgres
   - main.go RestoreFromDB rehydrates lobby on startup

8. Unify live + finished into one races table
   - migration 010_unify_races.sql: rename finished_races to
     races, expand status CHECK, merge live rows
   - PgStore now hosts both write paths; LiveStore is a
     thin facade implementing lobby.Persistence
   - seeder resetAll drops only finished/cancelled rows and
     race_plans / race_queue / lobby_drivers

Each layer is consistent on its own; cross-layer changes are
visible in the file history. A future refactor may split this
commit into the per-stage boundaries listed above.

server/internal/lobby/lobby_test.go

@@ -0,0 +1,120 @@
+package lobby
+
+import (
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestAddDriver(t *testing.T) {
+	s := NewService()
+	d, err := s.AddDriver("d1", "Alice", "RU")
+	if err != nil {
+		t.Fatalf("AddDriver: %v", err)
+	}
+	if d.Status != DriverStatusIdle {
+		t.Errorf("expected idle, got %s", d.Status)
+	}
+	if d.Name != "Alice" {
+		t.Errorf("name: got %s", d.Name)
+	}
+}
+
+func TestCreateRaceValidates(t *testing.T) {
+	s := NewService()
+	_, _ = s.AddDriver("d1", "Alice", "")
+	tests := []struct {
+		name string
+		opts CreateRaceOptions
+		want string // substring of error message or "" for OK
+	}{
+		{"empty name", CreateRaceOptions{Name: "", MaxCars: 2, Laps: 1}, "name required"},
+		{"max cars too low", CreateRaceOptions{Name: "r", MaxCars: 0, Laps: 1}, ""}, // defaults
+		{"max cars too high", CreateRaceOptions{Name: "r", MaxCars: 9, Laps: 1}, "max_cars must be"},
+		{"no laps and no time", CreateRaceOptions{Name: "r", MaxCars: 2}, "laps or time_limit_s"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := s.CreateRace(tt.opts)
+			if tt.want == "" && err != nil {
+				t.Fatalf("expected ok, got %v", err)
+			}
+			if tt.want != "" && err == nil {
+				t.Fatalf("expected error containing %q, got nil", tt.want)
+			}
+			if tt.want != "" && err != nil && !strings.Contains(err.Error(), tt.want) {
+				t.Fatalf("error %q does not contain %q", err.Error(), tt.want)
+			}
+		})
+	}
+}
+
+func TestCreateRaceEmpty(t *testing.T) {
+	s := NewService()
+	r, err := s.CreateRace(CreateRaceOptions{
+		Name:    "open",
+		TrackID: "default",
+		MaxCars: 4,
+		Laps:    5,
+	})
+	if err != nil {
+		t.Fatalf("CreateRace: %v", err)
+	}
+	if r.Status != RaceStatusLobby {
+		t.Errorf("status: got %s", r.Status)
+	}
+	if len(r.DriverIDs) != 0 {
+		t.Errorf("expected empty drivers, got %d", len(r.DriverIDs))
+	}
+	if r.TrackID != "default" {
+		t.Errorf("track: got %s", r.TrackID)
+	}
+}
+
+func TestQuickPlayJoinsFirstRace(t *testing.T) {
+	s := NewService()
+	_, _ = s.AddDriver("d1", "Alice", "")
+	_, _ = s.AddDriver("d2", "Bob", "")
+	r1, _ := s.QuickPlay("d1", 4)
+	r2, err := s.QuickPlay("d2", 4)
+	if err != nil {
+		t.Fatalf("QuickPlay d2: %v", err)
+	}
+	if r2.ID != r1.ID {
+		t.Errorf("expected to join %s, got %s", r1.ID, r2.ID)
+	}
+	if len(r2.DriverIDs) != 2 {
+		t.Errorf("expected 2 drivers, got %d", len(r2.DriverIDs))
+	}
+}
+
+func TestSubscribeReceivesSnapshot(t *testing.T) {
+	s := NewService()
+	ch, cancel := s.Subscribe()
+	defer cancel()
+	// Subscribe pushes initial snapshot.
+	select {
+	case ev := <-ch:
+		if ev.kind != "snapshot" {
+			t.Fatalf("first event: kind=%s", ev.kind)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("no initial snapshot")
+	}
+}
+
+func TestSubscribeReceivesRaceCreated(t *testing.T) {
+	s := NewService()
+	ch, cancel := s.Subscribe()
+	defer cancel()
+	<-ch // drain initial snapshot
+	_, _ = s.AddDriver("d1", "Alice", "")
+	select {
+	case ev := <-ch:
+		if ev.kind != "driver_joined" {
+			t.Fatalf("expected driver_joined, got %s", ev.kind)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("no event after AddDriver")
+	}
+}