R4: push enrichment — events carry a state delta, kill the last poll

Enrich the in-app live stream into a delta channel so the UI renders a move from the event without a follow-up game.state, and make the matchmaking poll a stream-down fallback.

- pkg/fbs: trailing fields on opponent_moved (move+game+bag_len), your_turn (move_count), match_found (state), game_over (game), notify (account/invitation/state), MoveResult (rack+bag_len); regenerate Go + TS.
- backend: notify owns the FB encoding (encode.go + payload.go input structs); game/lobby/social map their domain types in. emitMove builds the move delta; game.Service.InitialState feeds match_found/game_started the recipient's initial StateView; friends/invitations notify carry their account/invitation. The move-commit response (submit_play/pass/exchange/resign) returns the actor's refilled rack + bag size.
- gateway: MoveResult transcode carries rack+bag_len.
- ui: pure lib/gamedelta.ts reducer advances the per-game cache keyed on move_count (idempotent + gap-safe); app.svelte seeds the cache on match_found/game_started; Game.svelte applies the delta (commit/pass/exchange/resign drop their load()); NewGame polls only while app.streamAlive is false.
- docs: ARCHITECTURE §10, FUNCTIONAL(+ru), backend/gateway/ui READMEs; PRERELEASE R4 marked done + Refinements.

backend/internal/notify/events.go

@@ -6,6 +6,7 @@ import (
 	flatbuffers "github.com/google/flatbuffers/go"
 	"github.com/google/uuid"
 
+	"scrabble/backend/internal/engine"
 	fb "scrabble/pkg/fbs/scrabblefb"
 )
 
@@ -17,8 +18,9 @@ import (
 // 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 {
+// turn" text. moveCount is the post-move count, which the client compares against its cached
+// game to detect a missed in-app move and fall back to a refetch (R4).
+func YourTurn(userID, gameID uuid.UUID, deadline time.Time, opponentName, lastAction, lastWord, scoreLine string, moveCount int) Intent {
 	b := flatbuffers.NewBuilder(128)
 	gid := b.CreateString(gameID.String())
 	name := b.CreateString(opponentName)
@@ -32,38 +34,51 @@ func YourTurn(userID, gameID uuid.UUID, deadline time.Time, opponentName, lastAc
 	fb.YourTurnEventAddLastAction(b, action)
 	fb.YourTurnEventAddLastWord(b, word)
 	fb.YourTurnEventAddScoreLine(b, score)
+	fb.YourTurnEventAddMoveCount(b, int32(moveCount))
 	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)
+// feed the out-of-app "game over" push (Stage 17). game is the final post-game summary (the
+// adjusted scores after rack penalties and the winner flag), so an in-app client settles the
+// finished game from the event without a refetch (R4).
+func GameOver(userID, gameID uuid.UUID, result, scoreLine string, game GameSummary) Intent {
+	b := flatbuffers.NewBuilder(512)
 	gid := b.CreateString(gameID.String())
 	res := b.CreateString(result)
 	score := b.CreateString(scoreLine)
+	gameOff := buildGameView(b, game)
 	fb.GameOverEventStart(b)
 	fb.GameOverEventAddGameId(b, gid)
 	fb.GameOverEventAddResult(b, res)
 	fb.GameOverEventAddScoreLine(b, score)
+	fb.GameOverEventAddGame(b, gameOff)
 	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 {
-	b := flatbuffers.NewBuilder(64)
+// OpponentMoved tells userID that move was just committed in game gameID, carrying it as a delta
+// the client applies to its cached game without a refetch (R4): move is the decoded play/pass/
+// exchange, game is the post-move summary (per-seat scores, to_move, move_count, status) and
+// bagLen is the bag size after the draw. The seat/action/score/total scalars repeat the move's
+// summary for pre-R4 wire back-compat.
+func OpponentMoved(userID, gameID uuid.UUID, move engine.MoveRecord, game GameSummary, bagLen int) Intent {
+	b := flatbuffers.NewBuilder(512)
 	gid := b.CreateString(gameID.String())
-	act := b.CreateString(action)
+	act := b.CreateString(move.Action.String())
+	moveOff := buildMoveRecord(b, move)
+	gameOff := buildGameView(b, game)
 	fb.OpponentMovedEventStart(b)
 	fb.OpponentMovedEventAddGameId(b, gid)
-	fb.OpponentMovedEventAddSeat(b, int32(seat))
+	fb.OpponentMovedEventAddSeat(b, int32(move.Player))
 	fb.OpponentMovedEventAddAction(b, act)
-	fb.OpponentMovedEventAddScore(b, int32(score))
-	fb.OpponentMovedEventAddTotal(b, int32(total))
+	fb.OpponentMovedEventAddScore(b, int32(move.Score))
+	fb.OpponentMovedEventAddTotal(b, int32(move.Total))
+	fb.OpponentMovedEventAddMove(b, moveOff)
+	fb.OpponentMovedEventAddGame(b, gameOff)
+	fb.OpponentMovedEventAddBagLen(b, int32(bagLen))
 	b.Finish(fb.OpponentMovedEventEnd(b))
 	return Intent{UserID: userID, Kind: KindOpponentMoved, Payload: b.FinishedBytes(), EventID: eventID()}
 }
@@ -99,21 +114,24 @@ func Nudge(userID, gameID, fromUserID uuid.UUID) Intent {
 	return Intent{UserID: userID, Kind: KindNudge, Payload: b.FinishedBytes(), EventID: eventID()}
 }
 
-// MatchFound tells userID that game gameID, which they are seated in, has
-// started (an auto-match pairing or a robot substitution).
-func MatchFound(userID, gameID uuid.UUID) Intent {
-	b := flatbuffers.NewBuilder(64)
+// MatchFound tells userID that game gameID, which they are seated in, has started (an auto-match
+// pairing or a robot substitution). state is the recipient's full initial view of the new game,
+// so the client navigates straight in from the event with no follow-up fetch (R4).
+func MatchFound(userID, gameID uuid.UUID, state PlayerState) Intent {
+	b := flatbuffers.NewBuilder(512)
 	gid := b.CreateString(gameID.String())
+	stateOff := buildStateView(b, state)
 	fb.MatchFoundEventStart(b)
 	fb.MatchFoundEventAddGameId(b, gid)
+	fb.MatchFoundEventAddState(b, stateOff)
 	b.Finish(fb.MatchFoundEventEnd(b))
 	return Intent{UserID: userID, Kind: KindMatchFound, Payload: b.FinishedBytes(), EventID: eventID()}
 }
 
-// Notification is a lightweight "re-poll" signal to userID that a friend request or
-// invitation changed. kind is a sub-discriminator (NotifyFriendRequest,
-// NotifyFriendAdded, NotifyFriendDeclined, NotifyInvitation, NotifyGameStarted) the
-// client may use to scope its refresh.
+// Notification is a lightweight "re-poll" signal to userID that something in their lobby
+// changed. kind is a sub-discriminator (NotifyFriendRequest, NotifyFriendAdded,
+// NotifyFriendDeclined, NotifyInvitation, NotifyGameStarted). It carries no payload; prefer the
+// enriched constructors below, which let the client update its lobby without a refetch (R4).
 func Notification(userID uuid.UUID, kind string) Intent {
 	b := flatbuffers.NewBuilder(32)
 	k := b.CreateString(kind)
@@ -123,6 +141,47 @@ func Notification(userID uuid.UUID, kind string) Intent {
 	return Intent{UserID: userID, Kind: KindNotification, Payload: b.FinishedBytes(), EventID: eventID()}
 }
 
+// NotificationAccount builds a lobby notification of one of the friend_* kinds carrying the
+// account it concerns (the requester, the new friend or the decliner), so the client updates its
+// requests/friends lists and the in-game "add friend" state without a refetch (R4).
+func NotificationAccount(userID uuid.UUID, kind string, acc AccountRef) Intent {
+	b := flatbuffers.NewBuilder(128)
+	k := b.CreateString(kind)
+	accOff := buildAccountRef(b, acc)
+	fb.NotificationEventStart(b)
+	fb.NotificationEventAddKind(b, k)
+	fb.NotificationEventAddAccount(b, accOff)
+	b.Finish(fb.NotificationEventEnd(b))
+	return Intent{UserID: userID, Kind: KindNotification, Payload: b.FinishedBytes(), EventID: eventID()}
+}
+
+// NotificationGameStarted builds the NotifyGameStarted notification carrying the recipient's
+// initial view of the just-started invited game, so the client seeds its game cache and the
+// lobby list without a refetch (R4).
+func NotificationGameStarted(userID uuid.UUID, state PlayerState) Intent {
+	b := flatbuffers.NewBuilder(512)
+	k := b.CreateString(NotifyGameStarted)
+	stateOff := buildStateView(b, state)
+	fb.NotificationEventStart(b)
+	fb.NotificationEventAddKind(b, k)
+	fb.NotificationEventAddState(b, stateOff)
+	b.Finish(fb.NotificationEventEnd(b))
+	return Intent{UserID: userID, Kind: KindNotification, Payload: b.FinishedBytes(), EventID: eventID()}
+}
+
+// NotificationInvitation builds the NotifyInvitation notification carrying the new invitation,
+// so the client adds it to its lobby invitations list without a refetch (R4).
+func NotificationInvitation(userID uuid.UUID, inv InvitationSummary) Intent {
+	b := flatbuffers.NewBuilder(512)
+	k := b.CreateString(NotifyInvitation)
+	invOff := buildInvitation(b, inv)
+	fb.NotificationEventStart(b)
+	fb.NotificationEventAddKind(b, k)
+	fb.NotificationEventAddInvitation(b, invOff)
+	b.Finish(fb.NotificationEventEnd(b))
+	return Intent{UserID: userID, Kind: KindNotification, Payload: b.FinishedBytes(), EventID: eventID()}
+}
+
 // eventID returns a best-effort correlation id for one emitted event.
 func eventID() string {
 	if id, err := uuid.NewV7(); err == nil {