Stage 5: robot opponent (pool, seed-derived strategy, move driver, matchmaker substitution)

- internal/robot: durable kind='robot' account pool (migration 00004); every
  per-game and per-turn choice derived deterministically from the game seed
  (restart-stable FNV mix); a background move driver; margin targeting (band
  1-30, closest-to-band); right-skewed [2,90]min delays (median ~10m);
  opponent-anchored sleep with +/-3h drift; daytime nudge reply + proactive
  12h nudge; friend/chat blocked via profile toggles.
- engine.Candidates (decoded ranked plays); game.Candidates + RobotTurns;
  social.LastNudgeAt.
- matchmaker: 10s wait then robot substitution (reaper) + Poll delivery seam.
- config (BACKEND_ROBOT_DRIVE_INTERVAL, BACKEND_LOBBY_ROBOT_WAIT,
  BACKEND_LOBBY_REAPER_INTERVAL); main wiring + boot-time pool provisioning.
- metrics: robot account_stats (authoritative balance) + robot_games_finished_total
  OTel counter + per-finish log.
- docs: PLAN, ARCHITECTURE, FUNCTIONAL(+ru), TESTING, README; account.go comment.
- tests: robot strategy units, matchmaker reaper/Poll, engine.Candidates; inttest
  robot full-game / substitution / proactive-nudge.

backend/internal/lobby/config.go

@@ -0,0 +1,36 @@
+package lobby
+
+import (
+	"fmt"
+	"time"
+)
+
+// Config configures the matchmaking pool's robot substitution.
+type Config struct {
+	// RobotWait is how long an auto-match player waits for a human before a robot
+	// is substituted. Sourced from BACKEND_LOBBY_ROBOT_WAIT.
+	RobotWait time.Duration
+	// ReaperInterval is how often the substitution reaper scans for over-waited
+	// players. Sourced from BACKEND_LOBBY_REAPER_INTERVAL.
+	ReaperInterval time.Duration
+}
+
+// DefaultConfig returns the matchmaking defaults: a 10-second wait
+// (docs/ARCHITECTURE.md §7) scanned every second.
+func DefaultConfig() Config {
+	return Config{
+		RobotWait:      10 * time.Second,
+		ReaperInterval: time.Second,
+	}
+}
+
+// Validate reports whether the configuration is usable.
+func (c Config) Validate() error {
+	if c.RobotWait <= 0 {
+		return fmt.Errorf("lobby: robot wait must be positive, got %s", c.RobotWait)
+	}
+	if c.ReaperInterval <= 0 {
+		return fmt.Errorf("lobby: reaper interval must be positive, got %s", c.ReaperInterval)
+	}
+	return nil
+}

backend/internal/lobby/lobby.go

@@ -21,6 +21,13 @@ type GameCreator interface {
 	Create(ctx context.Context, params game.CreateParams) (game.Game, error)
 }
 
+// RobotProvider supplies a robot account to substitute for a missing human in
+// auto-match. robot.Service satisfies it; it returns an error when no robot is
+// available so the matchmaker can defer substitution.
+type RobotProvider interface {
+	Pick() (uuid.UUID, error)
+}
+
 // Blocker reports whether two accounts have a block between them (either
 // direction). social.Service satisfies it; the lobby uses it to refuse
 // invitations between blocked accounts.

backend/internal/lobby/matchmaker.go

@@ -7,34 +7,56 @@ import (
 	"time"
 
 	"github.com/google/uuid"
+	"go.uber.org/zap"
 
 	"scrabble/backend/internal/engine"
 	"scrabble/backend/internal/game"
 )
 
 // Matchmaker is the in-memory auto-match pool: a FIFO queue per variant that pairs
-// the next two humans into a two-player game. It holds no database state and is
-// lost on restart (players simply re-queue). It is safe for concurrent use.
+// the next two humans into a two-player game, or — when no human arrives within
+// the wait window — substitutes a robot. It holds no database state and is lost on
+// restart (players simply re-queue). It is safe for concurrent use.
 //
 // Auto-match is anonymous, so the pool does not consult per-user blocks (those
-// govern friends, chat and invitations between known players). Robot substitution
-// for a missing human is added in a later stage.
+// govern friends, chat and invitations between known players).
+//
+// A player who is queued learns of a match — by a waiting human being paired, or
+// by robot substitution — through Poll, the interim delivery seam: production
+// delivery is a notification (session/in-app push and the platform side-service,
+// docs/ARCHITECTURE.md §10), wired with the gateway in a later stage.
 type Matchmaker struct {
-	games GameCreator
+	games     GameCreator
+	robots    RobotProvider
+	waitDelay time.Duration
+	clock     func() time.Time
+	log       *zap.Logger
 
-	mu     sync.Mutex
-	queues map[engine.Variant][]uuid.UUID
-	queued map[uuid.UUID]engine.Variant
-	rng    *rand.Rand
+	mu           sync.Mutex
+	queues       map[engine.Variant][]uuid.UUID
+	queued       map[uuid.UUID]engine.Variant
+	waitingSince map[uuid.UUID]time.Time
+	results      map[uuid.UUID]game.Game
+	rng          *rand.Rand
 }
 
-// NewMatchmaker constructs a Matchmaker that starts matched games through games.
-func NewMatchmaker(games GameCreator) *Matchmaker {
+// NewMatchmaker constructs a Matchmaker that starts matched games through games
+// and substitutes a robot from robots when a player waits longer than waitDelay.
+func NewMatchmaker(games GameCreator, robots RobotProvider, waitDelay time.Duration, log *zap.Logger) *Matchmaker {
+	if log == nil {
+		log = zap.NewNop()
+	}
 	return &Matchmaker{
-		games:  games,
-		queues: make(map[engine.Variant][]uuid.UUID),
-		queued: make(map[uuid.UUID]engine.Variant),
-		rng:    rand.New(rand.NewSource(time.Now().UnixNano())),
+		games:        games,
+		robots:       robots,
+		waitDelay:    waitDelay,
+		clock:        func() time.Time { return time.Now().UTC() },
+		log:          log,
+		queues:       make(map[engine.Variant][]uuid.UUID),
+		queued:       make(map[uuid.UUID]engine.Variant),
+		waitingSince: make(map[uuid.UUID]time.Time),
+		results:      make(map[uuid.UUID]game.Game),
+		rng:          rand.New(rand.NewSource(time.Now().UnixNano())),
 	}
 }
 
@@ -47,7 +69,8 @@ type EnqueueResult struct {
 
 // Enqueue joins accountID to the variant pool. If an opponent already waits, the
 // two are paired (seat order randomised for first-move fairness) and a game starts
-// immediately; otherwise the account waits. An account already waiting in any pool
+// immediately; otherwise the account waits, and a later pairing or robot
+// substitution is delivered through Poll. An account already waiting in any pool
 // gets ErrAlreadyQueued.
 func (m *Matchmaker) Enqueue(ctx context.Context, accountID uuid.UUID, variant engine.Variant) (EnqueueResult, error) {
 	m.mu.Lock()
@@ -59,31 +82,42 @@ func (m *Matchmaker) Enqueue(ctx context.Context, accountID uuid.UUID, variant e
 	if len(q) == 0 {
 		m.queues[variant] = append(q, accountID)
 		m.queued[accountID] = variant
+		m.waitingSince[accountID] = m.clock()
 		m.mu.Unlock()
 		return EnqueueResult{}, nil
 	}
 	opponent := q[0]
-	m.queues[variant] = q[1:]
-	delete(m.queued, opponent)
+	m.removeLocked(opponent, variant)
 	seats := []uuid.UUID{opponent, accountID}
 	if m.rng.Intn(2) == 0 {
 		seats[0], seats[1] = seats[1], seats[0]
 	}
 	m.mu.Unlock()
 
-	g, err := m.games.Create(ctx, game.CreateParams{
-		Variant:        variant,
-		Seats:          seats,
-		TurnTimeout:    game.DefaultTurnTimeout,
-		HintsAllowed:   autoMatchHintsAllowed,
-		HintsPerPlayer: autoMatchHintsPerPlayer,
-	})
+	g, err := m.games.Create(ctx, autoMatchParams(variant, seats))
 	if err != nil {
 		return EnqueueResult{}, err
 	}
+	// The opponent was waiting; record the game so they can collect it via Poll.
+	m.mu.Lock()
+	m.results[opponent] = g
+	m.mu.Unlock()
 	return EnqueueResult{Matched: true, Game: g}, nil
 }
 
+// Poll reports whether accountID has been matched since it queued, returning the
+// started game once (the result is drained on read). It reports Matched=false
+// while the account is still waiting or has no pending result.
+func (m *Matchmaker) Poll(_ context.Context, accountID uuid.UUID) (EnqueueResult, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if g, ok := m.results[accountID]; ok {
+		delete(m.results, accountID)
+		return EnqueueResult{Matched: true, Game: g}, nil
+	}
+	return EnqueueResult{}, nil
+}
+
 // Cancel removes accountID from whatever pool it waits in, reporting whether it
 // was queued.
 func (m *Matchmaker) Cancel(_ context.Context, accountID uuid.UUID) bool {
@@ -93,14 +127,7 @@ func (m *Matchmaker) Cancel(_ context.Context, accountID uuid.UUID) bool {
 	if !ok {
 		return false
 	}
-	delete(m.queued, accountID)
-	q := m.queues[variant]
-	for i, id := range q {
-		if id == accountID {
-			m.queues[variant] = append(q[:i], q[i+1:]...)
-			break
-		}
-	}
+	m.removeLocked(accountID, variant)
 	return true
 }
 
@@ -110,3 +137,91 @@ func (m *Matchmaker) QueueLen(variant engine.Variant) int {
 	defer m.mu.Unlock()
 	return len(m.queues[variant])
 }
+
+// RunReaper substitutes a robot for any player that has waited past waitDelay,
+// scanning every interval until ctx is cancelled. It is started once from main.
+func (m *Matchmaker) RunReaper(ctx context.Context, interval time.Duration) {
+	ticker := time.NewTicker(interval)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+			m.Reap(ctx, m.clock())
+		}
+	}
+}
+
+// Reap pairs every player that has waited past waitDelay with a freshly picked
+// robot and starts the game, recording it for the player's Poll. RunReaper calls
+// it on a timer; it takes now explicitly so tests and ops can drive a single pass
+// at a chosen instant. A waiter is only dequeued once a robot is secured, so a
+// momentarily empty pool just defers substitution to a later tick.
+func (m *Matchmaker) Reap(ctx context.Context, now time.Time) {
+	type sub struct {
+		human   uuid.UUID
+		variant engine.Variant
+		seats   []uuid.UUID
+	}
+	m.mu.Lock()
+	var due []uuid.UUID
+	for acc, since := range m.waitingSince {
+		if now.Sub(since) >= m.waitDelay {
+			due = append(due, acc)
+		}
+	}
+	var subs []sub
+	for _, acc := range due {
+		robotID, err := m.robots.Pick()
+		if err != nil {
+			m.log.Warn("robot substitution deferred", zap.Error(err))
+			continue
+		}
+		variant := m.queued[acc]
+		m.removeLocked(acc, variant)
+		seats := []uuid.UUID{acc, robotID}
+		if m.rng.Intn(2) == 0 {
+			seats[0], seats[1] = seats[1], seats[0]
+		}
+		subs = append(subs, sub{human: acc, variant: variant, seats: seats})
+	}
+	m.mu.Unlock()
+
+	for _, s := range subs {
+		g, err := m.games.Create(ctx, autoMatchParams(s.variant, s.seats))
+		if err != nil {
+			m.log.Warn("robot substitution failed", zap.String("human", s.human.String()), zap.Error(err))
+			continue
+		}
+		m.mu.Lock()
+		m.results[s.human] = g
+		m.mu.Unlock()
+	}
+}
+
+// removeLocked drops accountID from the queue, the queued index and the waiting
+// clock. The caller holds m.mu.
+func (m *Matchmaker) removeLocked(accountID uuid.UUID, variant engine.Variant) {
+	delete(m.queued, accountID)
+	delete(m.waitingSince, accountID)
+	q := m.queues[variant]
+	for i, id := range q {
+		if id == accountID {
+			m.queues[variant] = append(q[:i], q[i+1:]...)
+			break
+		}
+	}
+}
+
+// autoMatchParams builds the create parameters for a two-player auto-match with
+// the casual defaults.
+func autoMatchParams(variant engine.Variant, seats []uuid.UUID) game.CreateParams {
+	return game.CreateParams{
+		Variant:        variant,
+		Seats:          seats,
+		TurnTimeout:    game.DefaultTurnTimeout,
+		HintsAllowed:   autoMatchHintsAllowed,
+		HintsPerPlayer: autoMatchHintsPerPlayer,
+	}
+}

backend/internal/lobby/matchmaker_test.go

@@ -4,8 +4,10 @@ import (
 	"context"
 	"errors"
 	"testing"
+	"time"
 
 	"github.com/google/uuid"
+	"go.uber.org/zap"
 
 	"scrabble/backend/internal/engine"
 	"scrabble/backend/internal/game"
@@ -25,6 +27,28 @@ func (f *fakeCreator) Create(_ context.Context, p game.CreateParams) (game.Game,
 	return game.Game{ID: uuid.New(), Players: len(p.Seats)}, nil
 }
 
+// fakeRobots is a RobotProvider returning a fixed robot id, or an error to model
+// an empty pool.
+type fakeRobots struct {
+	id  uuid.UUID
+	err error
+}
+
+func (f *fakeRobots) Pick() (uuid.UUID, error) {
+	if f.err != nil {
+		return uuid.Nil, f.err
+	}
+	return f.id, nil
+}
+
+// testWaitDelay is long enough that the reaper never fires in the pairing tests
+// (which do not run it); the substitution tests drive reap directly.
+const testWaitDelay = 10 * time.Second
+
+func newTestMatchmaker(creator GameCreator, robotID uuid.UUID) *Matchmaker {
+	return NewMatchmaker(creator, &fakeRobots{id: robotID}, testWaitDelay, zap.NewNop())
+}
+
 func seatsContain(seats []uuid.UUID, want ...uuid.UUID) bool {
 	for _, w := range want {
 		found := false
@@ -43,7 +67,7 @@ func seatsContain(seats []uuid.UUID, want ...uuid.UUID) bool {
 
 func TestMatchmakerPairsTwoHumans(t *testing.T) {
 	creator := &fakeCreator{}
-	mm := NewMatchmaker(creator)
+	mm := newTestMatchmaker(creator, uuid.New())
 	ctx := context.Background()
 	a, b := uuid.New(), uuid.New()
 
@@ -78,10 +102,22 @@ func TestMatchmakerPairsTwoHumans(t *testing.T) {
 	if p.TurnTimeout != game.DefaultTurnTimeout || !p.HintsAllowed || p.HintsPerPlayer != autoMatchHintsPerPlayer {
 		t.Errorf("auto-match defaults not applied: %+v", p)
 	}
+
+	// The waiting opponent learns of the match through Poll, exactly once.
+	got, err := mm.Poll(ctx, a)
+	if err != nil {
+		t.Fatalf("poll a: %v", err)
+	}
+	if !got.Matched || got.Game.ID != r2.Game.ID {
+		t.Errorf("poll a = %+v, want the matched game %s", got, r2.Game.ID)
+	}
+	if again, _ := mm.Poll(ctx, a); again.Matched {
+		t.Error("poll result must drain after the first read")
+	}
 }
 
 func TestMatchmakerAlreadyQueued(t *testing.T) {
-	mm := NewMatchmaker(&fakeCreator{})
+	mm := newTestMatchmaker(&fakeCreator{}, uuid.New())
 	ctx := context.Background()
 	a := uuid.New()
 	if _, err := mm.Enqueue(ctx, a, engine.VariantEnglish); err != nil {
@@ -93,7 +129,7 @@ func TestMatchmakerAlreadyQueued(t *testing.T) {
 }
 
 func TestMatchmakerCancel(t *testing.T) {
-	mm := NewMatchmaker(&fakeCreator{})
+	mm := newTestMatchmaker(&fakeCreator{}, uuid.New())
 	ctx := context.Background()
 	a := uuid.New()
 	if _, err := mm.Enqueue(ctx, a, engine.VariantEnglish); err != nil {
@@ -112,7 +148,7 @@ func TestMatchmakerCancel(t *testing.T) {
 
 func TestMatchmakerVariantsAreSeparate(t *testing.T) {
 	creator := &fakeCreator{}
-	mm := NewMatchmaker(creator)
+	mm := newTestMatchmaker(creator, uuid.New())
 	ctx := context.Background()
 	if _, err := mm.Enqueue(ctx, uuid.New(), engine.VariantEnglish); err != nil {
 		t.Fatalf("enqueue en: %v", err)
@@ -130,7 +166,7 @@ func TestMatchmakerVariantsAreSeparate(t *testing.T) {
 
 func TestMatchmakerFIFO(t *testing.T) {
 	creator := &fakeCreator{}
-	mm := NewMatchmaker(creator)
+	mm := newTestMatchmaker(creator, uuid.New())
 	ctx := context.Background()
 	a, b, c := uuid.New(), uuid.New(), uuid.New()
 	for _, id := range []uuid.UUID{a, b, c} {
@@ -149,3 +185,75 @@ func TestMatchmakerFIFO(t *testing.T) {
 		t.Errorf("c should remain queued; len = %d", mm.QueueLen(engine.VariantEnglish))
 	}
 }
+
+func TestMatchmakerReaperSubstitutesRobot(t *testing.T) {
+	creator := &fakeCreator{}
+	robotID := uuid.New()
+	mm := newTestMatchmaker(creator, robotID)
+	base := time.Now()
+	mm.clock = func() time.Time { return base }
+	ctx := context.Background()
+	a := uuid.New()
+
+	if _, err := mm.Enqueue(ctx, a, engine.VariantEnglish); err != nil {
+		t.Fatalf("enqueue: %v", err)
+	}
+
+	mm.Reap(ctx, base.Add(5*time.Second)) // before the wait window
+	if len(creator.created) != 0 || mm.QueueLen(engine.VariantEnglish) != 1 {
+		t.Fatalf("must not substitute before the wait: created=%d queued=%d", len(creator.created), mm.QueueLen(engine.VariantEnglish))
+	}
+
+	mm.Reap(ctx, base.Add(testWaitDelay+time.Second)) // past the wait window
+	if len(creator.created) != 1 {
+		t.Fatalf("created %d games, want 1 after substitution", len(creator.created))
+	}
+	if !seatsContain(creator.created[0].Seats, a, robotID) {
+		t.Errorf("substituted game seats = %v, want human %s and robot %s", creator.created[0].Seats, a, robotID)
+	}
+	if mm.QueueLen(engine.VariantEnglish) != 0 {
+		t.Errorf("waiter should be dequeued after substitution")
+	}
+	got, err := mm.Poll(ctx, a)
+	if err != nil || !got.Matched {
+		t.Errorf("poll after substitution = %+v err=%v, want matched", got, err)
+	}
+}
+
+func TestMatchmakerReaperSkipsCancelled(t *testing.T) {
+	creator := &fakeCreator{}
+	mm := newTestMatchmaker(creator, uuid.New())
+	base := time.Now()
+	mm.clock = func() time.Time { return base }
+	ctx := context.Background()
+	a := uuid.New()
+
+	if _, err := mm.Enqueue(ctx, a, engine.VariantEnglish); err != nil {
+		t.Fatalf("enqueue: %v", err)
+	}
+	mm.Cancel(ctx, a)
+	mm.Reap(ctx, base.Add(testWaitDelay+time.Second))
+	if len(creator.created) != 0 {
+		t.Errorf("a cancelled waiter must not be substituted; created %d", len(creator.created))
+	}
+}
+
+func TestMatchmakerReaperDefersWithoutRobot(t *testing.T) {
+	creator := &fakeCreator{}
+	mm := NewMatchmaker(creator, &fakeRobots{err: errors.New("empty pool")}, testWaitDelay, zap.NewNop())
+	base := time.Now()
+	mm.clock = func() time.Time { return base }
+	ctx := context.Background()
+	a := uuid.New()
+
+	if _, err := mm.Enqueue(ctx, a, engine.VariantEnglish); err != nil {
+		t.Fatalf("enqueue: %v", err)
+	}
+	mm.Reap(ctx, base.Add(testWaitDelay+time.Second))
+	if len(creator.created) != 0 {
+		t.Errorf("no robot available: must not create a game; created %d", len(creator.created))
+	}
+	if mm.QueueLen(engine.VariantEnglish) != 1 {
+		t.Errorf("waiter must stay queued when substitution is deferred; len %d", mm.QueueLen(engine.VariantEnglish))
+	}
+}