Stage 17 #4: enrich the out-of-app your-turn push + add game-over

The Telegram 'your turn' notification now names the opponent and recaps their last
move (voiced as the opponent: «{name}: my move — «WORD». Score 120:95» for a scoring
play; a short 'swapped / passed, your turn' otherwise), and a new game-over
notification reports the result + final score when a game ends by any path (closing
play, all-pass, resign, timeout). Scores are recipient-first (the reader's score
leads), 2-4 players (120:95:80).

- schema: YourTurnEvent gains opponent_name/last_action/last_word/score_line
  (appended, backward-compatible); new GameOverEvent{result, score_line}. Go + UI
  bindings regenerated (flatc 23.5.26 + pnpm codegen).
- backend: notify.YourTurn enriched + notify.GameOver; emitMove resolves the mover's
  name and emits per-recipient (your_turn to the next mover, game_over to every seat),
  with recipient-first score lines built in one place.
- gateway: game_over joins the out-of-app whitelist (routing.go).
- connector: render builds the enriched your_turn + game_over text per language (en/ru).
- tests: notify round-trip (enriched + game_over), emit (enriched fields + game_over to
  all seats / per-seat result), connector render (en/ru), routing; integration replay
  (play → your_turn with real name; resign → game_over) green.
- docs: ARCHITECTURE push catalog + out-of-app set, FUNCTIONAL (+ _ru), PLAN tracker.

backend/internal/game/emit_test.go

@@ -1,6 +1,7 @@
 package game
 
 import (
+	"context"
 	"slices"
 	"testing"
 	"time"
@@ -9,6 +10,7 @@ import (
 
 	"scrabble/backend/internal/engine"
 	"scrabble/backend/internal/notify"
+	fb "scrabble/pkg/fbs/scrabblefb"
 )
 
 // recordingPublisher captures every published intent for assertions.
@@ -29,13 +31,17 @@ func TestEmitMoveNotifiesActor(t *testing.T) {
 		ToMove:        1,
 		TurnStartedAt: time.Now(),
 		TurnTimeout:   time.Hour,
-		Seats:         []Seat{{Seat: 0, AccountID: actor}, {Seat: 1, AccountID: opp}},
+		Seats:         []Seat{{Seat: 0, AccountID: actor, Score: 19}, {Seat: 1, AccountID: opp, Score: 13}},
 	}
-	svc.emitMove(g, engine.MoveRecord{Player: 0, Action: engine.ActionPlay, Score: 10, Total: 10})
+	svc.emitMove(context.Background(), g, engine.MoveRecord{Player: 0, Action: engine.ActionPlay, Words: []string{"HELLO"}, Score: 10, Total: 19})
 
 	kinds := map[uuid.UUID][]string{}
+	var yourTurn notify.Intent
 	for _, in := range pub.intents {
 		kinds[in.UserID] = append(kinds[in.UserID], in.Kind)
+		if in.UserID == opp && in.Kind == notify.KindYourTurn {
+			yourTurn = in
+		}
 	}
 	if !slices.Contains(kinds[actor], notify.KindOpponentMoved) {
 		t.Errorf("actor should get opponent_moved, got %v", kinds[actor])
@@ -49,4 +55,51 @@ func TestEmitMoveNotifiesActor(t *testing.T) {
 	if slices.Contains(kinds[actor], notify.KindYourTurn) {
 		t.Errorf("actor is not next to move, should not get your_turn")
 	}
+	// The your_turn push is enriched: the last move's action and word, and a recipient-first
+	// score line (the next mover, seat 1, first). The opponent name needs the account store and
+	// is left empty by this store-less unit (covered at the render layer).
+	yt := fb.GetRootAsYourTurnEvent(yourTurn.Payload, 0)
+	if got := string(yt.LastAction()); got != "play" {
+		t.Errorf("your_turn last_action = %q, want play", got)
+	}
+	if got := string(yt.LastWord()); got != "HELLO" {
+		t.Errorf("your_turn last_word = %q, want HELLO", got)
+	}
+	if got := string(yt.ScoreLine()); got != "13:19" { // seat 1 (recipient) first, then seat 0
+		t.Errorf("your_turn score_line = %q, want 13:19", got)
+	}
+}
+
+// TestEmitMoveAnnouncesGameOver checks the closing move sends a game_over push to every seat,
+// each with its own outcome and a recipient-first final score.
+func TestEmitMoveAnnouncesGameOver(t *testing.T) {
+	winner, loser := uuid.New(), uuid.New()
+	pub := &recordingPublisher{}
+	svc := &Service{pub: pub}
+	g := Game{
+		ID:        uuid.New(),
+		Status:    StatusFinished,
+		Players:   2,
+		EndReason: "out_of_tiles",
+		Seats:     []Seat{{Seat: 0, AccountID: winner, Score: 120, IsWinner: true}, {Seat: 1, AccountID: loser, Score: 95}},
+	}
+	svc.emitMove(context.Background(), g, engine.MoveRecord{Player: 0, Action: engine.ActionPlay, Total: 120})
+
+	over := map[uuid.UUID]notify.Intent{}
+	for _, in := range pub.intents {
+		if in.Kind == notify.KindGameOver {
+			over[in.UserID] = in
+		}
+	}
+	if len(over) != 2 {
+		t.Fatalf("game_over should reach both seats, got %d", len(over))
+	}
+	w := fb.GetRootAsGameOverEvent(over[winner].Payload, 0)
+	if string(w.Result()) != "won" || string(w.ScoreLine()) != "120:95" {
+		t.Errorf("winner game_over = %q / %q, want won / 120:95", w.Result(), w.ScoreLine())
+	}
+	l := fb.GetRootAsGameOverEvent(over[loser].Payload, 0)
+	if string(l.Result()) != "lost" || string(l.ScoreLine()) != "95:120" {
+		t.Errorf("loser game_over = %q / %q, want lost / 95:120", l.Result(), l.ScoreLine())
+	}
 }

backend/internal/game/service.go

@@ -7,6 +7,7 @@ import (
 	"errors"
 	"fmt"
 	"slices"
+	"strconv"
 	"strings"
 	"time"
 
@@ -350,7 +351,7 @@ func (svc *Service) commit(ctx context.Context, gameID uuid.UUID, g *engine.Game
 	if err != nil {
 		return Game{}, err
 	}
-	svc.emitMove(post, rec)
+	svc.emitMove(ctx, post, rec)
 	return post, nil
 }
 
@@ -361,20 +362,92 @@ func (svc *Service) commit(ctx context.Context, gameID uuid.UUID, g *engine.Game
 // out-of-app push), so the actor is not notified out of band about their own move.
 // Delivery is best-effort (notify.Publisher never blocks) and the gateway fans each
 // event out to all of the recipient's live streams.
-func (svc *Service) emitMove(post Game, rec engine.MoveRecord) {
-	intents := make([]notify.Intent, 0, len(post.Seats)+1)
+func (svc *Service) emitMove(ctx context.Context, post Game, rec engine.MoveRecord) {
+	intents := make([]notify.Intent, 0, 2*len(post.Seats))
 	for _, s := range post.Seats {
 		intents = append(intents, notify.OpponentMoved(s.AccountID, post.ID, rec.Player, rec.Action.String(), rec.Score, rec.Total))
 	}
-	if post.Status == StatusActive {
+	switch post.Status {
+	case StatusActive:
 		if next, ok := seatAccount(post.Seats, post.ToMove); ok {
 			deadline := post.TurnStartedAt.Add(post.TurnTimeout)
-			intents = append(intents, notify.YourTurn(next, post.ID, deadline))
+			action := rec.Action.String()
+			word := ""
+			if action == "play" && len(rec.Words) > 0 {
+				word = rec.Words[0]
+			}
+			opponent := svc.displayName(ctx, post.Seats, rec.Player)
+			intents = append(intents, notify.YourTurn(next, post.ID, deadline, opponent, action, word, scoreLine(post, post.ToMove)))
+		}
+	case StatusFinished:
+		// The game just ended (any path: a closing play, all-pass, resign or timeout). Tell every
+		// seat, each with their own perspective + recipient-first score, so an offline player gets
+		// an out-of-app "game over" push (online players take it from the in-app refresh).
+		for _, s := range post.Seats {
+			intents = append(intents, notify.GameOver(s.AccountID, post.ID, seatResult(post.Seats, s.Seat), scoreLine(post, s.Seat)))
 		}
 	}
 	svc.pub.Publish(intents...)
 }
 
+// displayName resolves the display name of the account at the given seat, or "" when the seat
+// is absent or the lookup fails (the enriched push then falls back to its plain text).
+func (svc *Service) displayName(ctx context.Context, seats []Seat, seat int) string {
+	if svc.accounts == nil {
+		return ""
+	}
+	id, ok := seatAccount(seats, seat)
+	if !ok {
+		return ""
+	}
+	acc, err := svc.accounts.GetByID(ctx, id)
+	if err != nil {
+		return ""
+	}
+	return acc.DisplayName
+}
+
+// scoreLine formats the running scores with recipientSeat's score first, then the remaining
+// seats in seat order, colon-joined (e.g. "120:95:80") — the recipient-first form used in the
+// out-of-app notifications.
+func scoreLine(g Game, recipientSeat int) string {
+	n := len(g.Seats)
+	bySeat := make([]int, n)
+	for _, s := range g.Seats {
+		if s.Seat >= 0 && s.Seat < n {
+			bySeat[s.Seat] = s.Score
+		}
+	}
+	parts := make([]string, 0, n)
+	if recipientSeat >= 0 && recipientSeat < n {
+		parts = append(parts, strconv.Itoa(bySeat[recipientSeat]))
+	}
+	for seat := 0; seat < n; seat++ {
+		if seat != recipientSeat {
+			parts = append(parts, strconv.Itoa(bySeat[seat]))
+		}
+	}
+	return strings.Join(parts, ":")
+}
+
+// seatResult reports the finished-game outcome from recipientSeat's perspective: "draw" when no
+// seat is flagged the winner, "won" when recipientSeat is, otherwise "lost".
+func seatResult(seats []Seat, recipientSeat int) string {
+	winner := false
+	for _, s := range seats {
+		if s.IsWinner {
+			winner = true
+			if s.Seat == recipientSeat {
+				return "won"
+			}
+		}
+	}
+	if !winner {
+		return "draw"
+	}
+	return "lost"
+}
+
 // seatAccount returns the account seated at the given seat index, or false when
 // no seat matches (the slice is not assumed to be ordered by seat).
 func seatAccount(seats []Seat, seat int) (uuid.UUID, bool) {

backend/internal/notify/events.go

@@ -13,18 +13,45 @@ import (
 // the payload with the shared scrabblefb schema. Keeping the encoding here lets
 // the game/social/lobby services emit events without importing the wire schema.
 
-// YourTurn announces to userID that it is their turn in game gameID, with the
-// turn's nominal deadline.
-func YourTurn(userID, gameID uuid.UUID, deadline time.Time) Intent {
-	b := flatbuffers.NewBuilder(64)
+// YourTurn announces to userID that it is their turn in game gameID, with the turn's nominal
+// deadline. opponentName, lastAction, lastWord and scoreLine enrich the out-of-app push (Stage
+// 17): the player who just moved, their move kind, the main word of a scoring play (empty
+// otherwise) and the recipient-first running score line. Empty strings render the plain "your
+// turn" text.
+func YourTurn(userID, gameID uuid.UUID, deadline time.Time, opponentName, lastAction, lastWord, scoreLine string) Intent {
+	b := flatbuffers.NewBuilder(128)
 	gid := b.CreateString(gameID.String())
+	name := b.CreateString(opponentName)
+	action := b.CreateString(lastAction)
+	word := b.CreateString(lastWord)
+	score := b.CreateString(scoreLine)
 	fb.YourTurnEventStart(b)
 	fb.YourTurnEventAddGameId(b, gid)
 	fb.YourTurnEventAddDeadlineUnix(b, deadline.Unix())
+	fb.YourTurnEventAddOpponentName(b, name)
+	fb.YourTurnEventAddLastAction(b, action)
+	fb.YourTurnEventAddLastWord(b, word)
+	fb.YourTurnEventAddScoreLine(b, score)
 	b.Finish(fb.YourTurnEventEnd(b))
 	return Intent{UserID: userID, Kind: KindYourTurn, Payload: b.FinishedBytes(), EventID: eventID()}
 }
 
+// GameOver announces to userID that game gameID finished. result is the outcome from userID's
+// own perspective ("won"/"lost"/"draw") and scoreLine is the recipient-first final score; both
+// feed the out-of-app "game over" push (Stage 17).
+func GameOver(userID, gameID uuid.UUID, result, scoreLine string) Intent {
+	b := flatbuffers.NewBuilder(64)
+	gid := b.CreateString(gameID.String())
+	res := b.CreateString(result)
+	score := b.CreateString(scoreLine)
+	fb.GameOverEventStart(b)
+	fb.GameOverEventAddGameId(b, gid)
+	fb.GameOverEventAddResult(b, res)
+	fb.GameOverEventAddScoreLine(b, score)
+	b.Finish(fb.GameOverEventEnd(b))
+	return Intent{UserID: userID, Kind: KindGameOver, Payload: b.FinishedBytes(), EventID: eventID()}
+}
+
 // OpponentMoved tells userID that seat just committed a move in game gameID,
 // summarising it (the client refetches the full state).
 func OpponentMoved(userID, gameID uuid.UUID, seat int, action string, score, total int) Intent {

backend/internal/notify/notify.go

@@ -27,6 +27,9 @@ const (
 	// KindNotification is a lightweight "re-poll your lobby counters" signal
 	// (incoming friend requests, invitations) that drives the lobby badge.
 	KindNotification = "notify"
+	// KindGameOver announces a finished game to each seated player, driving the
+	// out-of-app "game over" push (Stage 17).
+	KindGameOver = "game_over"
 )
 
 // Notification sub-kinds carried in a KindNotification event payload; the client

backend/internal/notify/notify_test.go

@@ -61,7 +61,7 @@ func TestNopPublisherDiscards(t *testing.T) {
 
 func TestYourTurnPayloadRoundTrips(t *testing.T) {
 	uid, gid := uuid.New(), uuid.New()
-	in := notify.YourTurn(uid, gid, time.Unix(1717000000, 0))
+	in := notify.YourTurn(uid, gid, time.Unix(1717000000, 0), "Ann", "play", "STOOL", "120:95")
 	if in.UserID != uid || in.Kind != notify.KindYourTurn || in.EventID == "" {
 		t.Fatalf("intent metadata wrong: %+v", in)
 	}
@@ -72,6 +72,23 @@ func TestYourTurnPayloadRoundTrips(t *testing.T) {
 	if got := ev.DeadlineUnix(); got != 1717000000 {
 		t.Fatalf("deadline = %d, want 1717000000", got)
 	}
+	if string(ev.OpponentName()) != "Ann" || string(ev.LastAction()) != "play" ||
+		string(ev.LastWord()) != "STOOL" || string(ev.ScoreLine()) != "120:95" {
+		t.Fatalf("enriched fields wrong: name=%q action=%q word=%q score=%q",
+			ev.OpponentName(), ev.LastAction(), ev.LastWord(), ev.ScoreLine())
+	}
+}
+
+func TestGameOverPayloadRoundTrips(t *testing.T) {
+	uid, gid := uuid.New(), uuid.New()
+	in := notify.GameOver(uid, gid, "won", "120:95:80")
+	if in.UserID != uid || in.Kind != notify.KindGameOver || in.EventID == "" {
+		t.Fatalf("intent metadata wrong: %+v", in)
+	}
+	ev := fb.GetRootAsGameOverEvent(in.Payload, 0)
+	if string(ev.GameId()) != gid.String() || string(ev.Result()) != "won" || string(ev.ScoreLine()) != "120:95:80" {
+		t.Fatalf("game_over fields wrong: game=%q result=%q score=%q", ev.GameId(), ev.Result(), ev.ScoreLine())
+	}
 }
 
 func TestOpponentMovedPayloadRoundTrips(t *testing.T) {