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.

pkg/fbs/scrabble.fbs

@@ -159,10 +159,16 @@ table SubmitPlayRequest {
   tiles:[PlayTile];
 }
 
-// MoveResult is the outcome of a committed move: the move and the post-move game.
+// MoveResult is the outcome of a committed move: the move and the post-move game. rack and
+// bag_len carry the actor's own post-move private state — their refilled rack (alphabet indices,
+// Stage 13; a blank is the sentinel index 255) and the bag size after drawing — so the mover
+// renders the next state straight from this response without a follow-up game.state (R4; added
+// trailing — backward-compatible).
 table MoveResult {
   move:MoveRecord;
   game:GameView;
+  rack:[ubyte];
+  bag_len:int;
 }
 
 // StateRequest asks for the requesting player's view of a game. include_alphabet asks the
@@ -477,6 +483,8 @@ table GcgExport {
 // move kind ("play"/"pass"/"exchange"/...), last_word is the main word of a scoring play (empty
 // otherwise), and score_line is the recipient-first running score (e.g. "120:95:80"). They are
 // appended (FlatBuffers-optional), so an older reader that only needs game_id/deadline is unaffected.
+// move_count is the post-move count (matching the opponent_moved GameView): the client uses it to
+// tell whether its cached game already reflects the move, falling back to a refetch on a gap (R4).
 table YourTurnEvent {
   game_id:string;
   deadline_unix:long;
@@ -484,25 +492,35 @@ table YourTurnEvent {
   last_action:string;
   last_word:string;
   score_line:string;
+  move_count:int;
 }
 
 // GameOverEvent signals that a game the recipient is seated in has finished, driving the
 // out-of-app "game over" push (Stage 17). result is the outcome from the recipient's own
-// perspective ("won"/"lost"/"draw"); score_line is the recipient-first final score.
+// perspective ("won"/"lost"/"draw"); score_line is the recipient-first final score. game is the
+// final post-game summary (adjusted scores after rack penalties + the winner flag), so the client
+// settles the finished game from the event without a refetch (R4; added trailing).
 table GameOverEvent {
   game_id:string;
   result:string;
   score_line:string;
+  game:GameView;
 }
 
-// OpponentMovedEvent summarises a move another seat just committed; the client
-// refetches the full state.
+// OpponentMovedEvent carries a move another seat just committed as a delta the client applies to
+// its cached game without a refetch (R4): move is the decoded play/pass/exchange (the same record
+// game.history returns), game is the post-move summary (per-seat scores, to_move, move_count,
+// status) and bag_len is the bag size after the draw. The leading seat/action/score/total scalars
+// are the pre-R4 summary, now redundant with move/game and kept only for wire back-compat.
 table OpponentMovedEvent {
   game_id:string;
   seat:int;
   action:string;
   score:int;
   total:int;
+  move:MoveRecord;
+  game:GameView;
+  bag_len:int;
 }
 
 // NudgeEvent signals that a player nudged the recipient.
@@ -511,17 +529,27 @@ table NudgeEvent {
   from_user_id:string;
 }
 
-// MatchFoundEvent signals that an auto-match pairing (or robot substitution)
-// started a game the recipient is seated in.
+// MatchFoundEvent signals that an auto-match pairing (or robot substitution) started a game the
+// recipient is seated in. state is the recipient's full initial view of the new game (empty board,
+// dealt rack), so the client navigates straight in from the event with no follow-up fetch (R4;
+// added trailing — an older reader still reads just game_id).
 table MatchFoundEvent {
   game_id:string;
+  state:StateView;
 }
 
 // NotificationEvent is a lightweight "something changed, re-poll" signal that
 // drives the lobby badge (incoming friend requests, invitations). kind is a sub-
 // discriminator ("friend_request", "friend_added", "friend_declined", "invitation",
 // "game_started"); the client re-fetches its lobby counters (and, for a requester
-// watching a game, its friend state) on any of them.
+// watching a game, its friend state) on any of them. To let the client update its lobby without a
+// follow-up fetch (R4), each event also carries the payload its kind changed: account for the
+// friend_* kinds (the requester/friend), invitation for "invitation" (the new invitation) and
+// state for "game_started" (the started game's initial view, like match_found). Only the field
+// matching kind is set (all added trailing — backward-compatible).
 table NotificationEvent {
   kind:string;
+  account:AccountRef;
+  invitation:Invitation;
+  state:StateView;
 }

pkg/fbs/scrabblefb/GameOverEvent.go

@@ -65,8 +65,21 @@ func (rcv *GameOverEvent) ScoreLine() []byte {
 	return nil
 }
 
+func (rcv *GameOverEvent) Game(obj *GameView) *GameView {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(10))
+	if o != 0 {
+		x := rcv._tab.Indirect(o + rcv._tab.Pos)
+		if obj == nil {
+			obj = new(GameView)
+		}
+		obj.Init(rcv._tab.Bytes, x)
+		return obj
+	}
+	return nil
+}
+
 func GameOverEventStart(builder *flatbuffers.Builder) {
-	builder.StartObject(3)
+	builder.StartObject(4)
 }
 func GameOverEventAddGameId(builder *flatbuffers.Builder, gameId flatbuffers.UOffsetT) {
 	builder.PrependUOffsetTSlot(0, flatbuffers.UOffsetT(gameId), 0)
@@ -77,6 +90,9 @@ func GameOverEventAddResult(builder *flatbuffers.Builder, result flatbuffers.UOf
 func GameOverEventAddScoreLine(builder *flatbuffers.Builder, scoreLine flatbuffers.UOffsetT) {
 	builder.PrependUOffsetTSlot(2, flatbuffers.UOffsetT(scoreLine), 0)
 }
+func GameOverEventAddGame(builder *flatbuffers.Builder, game flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(3, flatbuffers.UOffsetT(game), 0)
+}
 func GameOverEventEnd(builder *flatbuffers.Builder) flatbuffers.UOffsetT {
 	return builder.EndObject()
 }

pkg/fbs/scrabblefb/MatchFoundEvent.go

@@ -49,12 +49,28 @@ func (rcv *MatchFoundEvent) GameId() []byte {
 	return nil
 }
 
+func (rcv *MatchFoundEvent) State(obj *StateView) *StateView {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(6))
+	if o != 0 {
+		x := rcv._tab.Indirect(o + rcv._tab.Pos)
+		if obj == nil {
+			obj = new(StateView)
+		}
+		obj.Init(rcv._tab.Bytes, x)
+		return obj
+	}
+	return nil
+}
+
 func MatchFoundEventStart(builder *flatbuffers.Builder) {
-	builder.StartObject(1)
+	builder.StartObject(2)
 }
 func MatchFoundEventAddGameId(builder *flatbuffers.Builder, gameId flatbuffers.UOffsetT) {
 	builder.PrependUOffsetTSlot(0, flatbuffers.UOffsetT(gameId), 0)
 }
+func MatchFoundEventAddState(builder *flatbuffers.Builder, state flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(1, flatbuffers.UOffsetT(state), 0)
+}
 func MatchFoundEventEnd(builder *flatbuffers.Builder) flatbuffers.UOffsetT {
 	return builder.EndObject()
 }

pkg/fbs/scrabblefb/MoveResult.go

@@ -67,8 +67,54 @@ func (rcv *MoveResult) Game(obj *GameView) *GameView {
 	return nil
 }
 
+func (rcv *MoveResult) Rack(j int) byte {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(8))
+	if o != 0 {
+		a := rcv._tab.Vector(o)
+		return rcv._tab.GetByte(a + flatbuffers.UOffsetT(j*1))
+	}
+	return 0
+}
+
+func (rcv *MoveResult) RackLength() int {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(8))
+	if o != 0 {
+		return rcv._tab.VectorLen(o)
+	}
+	return 0
+}
+
+func (rcv *MoveResult) RackBytes() []byte {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(8))
+	if o != 0 {
+		return rcv._tab.ByteVector(o + rcv._tab.Pos)
+	}
+	return nil
+}
+
+func (rcv *MoveResult) MutateRack(j int, n byte) bool {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(8))
+	if o != 0 {
+		a := rcv._tab.Vector(o)
+		return rcv._tab.MutateByte(a+flatbuffers.UOffsetT(j*1), n)
+	}
+	return false
+}
+
+func (rcv *MoveResult) BagLen() int32 {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(10))
+	if o != 0 {
+		return rcv._tab.GetInt32(o + rcv._tab.Pos)
+	}
+	return 0
+}
+
+func (rcv *MoveResult) MutateBagLen(n int32) bool {
+	return rcv._tab.MutateInt32Slot(10, n)
+}
+
 func MoveResultStart(builder *flatbuffers.Builder) {
-	builder.StartObject(2)
+	builder.StartObject(4)
 }
 func MoveResultAddMove(builder *flatbuffers.Builder, move flatbuffers.UOffsetT) {
 	builder.PrependUOffsetTSlot(0, flatbuffers.UOffsetT(move), 0)
@@ -76,6 +122,15 @@ func MoveResultAddMove(builder *flatbuffers.Builder, move flatbuffers.UOffsetT)
 func MoveResultAddGame(builder *flatbuffers.Builder, game flatbuffers.UOffsetT) {
 	builder.PrependUOffsetTSlot(1, flatbuffers.UOffsetT(game), 0)
 }
+func MoveResultAddRack(builder *flatbuffers.Builder, rack flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(2, flatbuffers.UOffsetT(rack), 0)
+}
+func MoveResultStartRackVector(builder *flatbuffers.Builder, numElems int) flatbuffers.UOffsetT {
+	return builder.StartVector(1, numElems, 1)
+}
+func MoveResultAddBagLen(builder *flatbuffers.Builder, bagLen int32) {
+	builder.PrependInt32Slot(3, bagLen, 0)
+}
 func MoveResultEnd(builder *flatbuffers.Builder) flatbuffers.UOffsetT {
 	return builder.EndObject()
 }

pkg/fbs/scrabblefb/NotificationEvent.go

@@ -49,12 +49,60 @@ func (rcv *NotificationEvent) Kind() []byte {
 	return nil
 }
 
+func (rcv *NotificationEvent) Account(obj *AccountRef) *AccountRef {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(6))
+	if o != 0 {
+		x := rcv._tab.Indirect(o + rcv._tab.Pos)
+		if obj == nil {
+			obj = new(AccountRef)
+		}
+		obj.Init(rcv._tab.Bytes, x)
+		return obj
+	}
+	return nil
+}
+
+func (rcv *NotificationEvent) Invitation(obj *Invitation) *Invitation {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(8))
+	if o != 0 {
+		x := rcv._tab.Indirect(o + rcv._tab.Pos)
+		if obj == nil {
+			obj = new(Invitation)
+		}
+		obj.Init(rcv._tab.Bytes, x)
+		return obj
+	}
+	return nil
+}
+
+func (rcv *NotificationEvent) State(obj *StateView) *StateView {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(10))
+	if o != 0 {
+		x := rcv._tab.Indirect(o + rcv._tab.Pos)
+		if obj == nil {
+			obj = new(StateView)
+		}
+		obj.Init(rcv._tab.Bytes, x)
+		return obj
+	}
+	return nil
+}
+
 func NotificationEventStart(builder *flatbuffers.Builder) {
-	builder.StartObject(1)
+	builder.StartObject(4)
 }
 func NotificationEventAddKind(builder *flatbuffers.Builder, kind flatbuffers.UOffsetT) {
 	builder.PrependUOffsetTSlot(0, flatbuffers.UOffsetT(kind), 0)
 }
+func NotificationEventAddAccount(builder *flatbuffers.Builder, account flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(1, flatbuffers.UOffsetT(account), 0)
+}
+func NotificationEventAddInvitation(builder *flatbuffers.Builder, invitation flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(2, flatbuffers.UOffsetT(invitation), 0)
+}
+func NotificationEventAddState(builder *flatbuffers.Builder, state flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(3, flatbuffers.UOffsetT(state), 0)
+}
 func NotificationEventEnd(builder *flatbuffers.Builder) flatbuffers.UOffsetT {
 	return builder.EndObject()
 }

pkg/fbs/scrabblefb/OpponentMovedEvent.go

@@ -93,8 +93,46 @@ func (rcv *OpponentMovedEvent) MutateTotal(n int32) bool {
 	return rcv._tab.MutateInt32Slot(12, n)
 }
 
+func (rcv *OpponentMovedEvent) Move(obj *MoveRecord) *MoveRecord {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(14))
+	if o != 0 {
+		x := rcv._tab.Indirect(o + rcv._tab.Pos)
+		if obj == nil {
+			obj = new(MoveRecord)
+		}
+		obj.Init(rcv._tab.Bytes, x)
+		return obj
+	}
+	return nil
+}
+
+func (rcv *OpponentMovedEvent) Game(obj *GameView) *GameView {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(16))
+	if o != 0 {
+		x := rcv._tab.Indirect(o + rcv._tab.Pos)
+		if obj == nil {
+			obj = new(GameView)
+		}
+		obj.Init(rcv._tab.Bytes, x)
+		return obj
+	}
+	return nil
+}
+
+func (rcv *OpponentMovedEvent) BagLen() int32 {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(18))
+	if o != 0 {
+		return rcv._tab.GetInt32(o + rcv._tab.Pos)
+	}
+	return 0
+}
+
+func (rcv *OpponentMovedEvent) MutateBagLen(n int32) bool {
+	return rcv._tab.MutateInt32Slot(18, n)
+}
+
 func OpponentMovedEventStart(builder *flatbuffers.Builder) {
-	builder.StartObject(5)
+	builder.StartObject(8)
 }
 func OpponentMovedEventAddGameId(builder *flatbuffers.Builder, gameId flatbuffers.UOffsetT) {
 	builder.PrependUOffsetTSlot(0, flatbuffers.UOffsetT(gameId), 0)
@@ -111,6 +149,15 @@ func OpponentMovedEventAddScore(builder *flatbuffers.Builder, score int32) {
 func OpponentMovedEventAddTotal(builder *flatbuffers.Builder, total int32) {
 	builder.PrependInt32Slot(4, total, 0)
 }
+func OpponentMovedEventAddMove(builder *flatbuffers.Builder, move flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(5, flatbuffers.UOffsetT(move), 0)
+}
+func OpponentMovedEventAddGame(builder *flatbuffers.Builder, game flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(6, flatbuffers.UOffsetT(game), 0)
+}
+func OpponentMovedEventAddBagLen(builder *flatbuffers.Builder, bagLen int32) {
+	builder.PrependInt32Slot(7, bagLen, 0)
+}
 func OpponentMovedEventEnd(builder *flatbuffers.Builder) flatbuffers.UOffsetT {
 	return builder.EndObject()
 }

pkg/fbs/scrabblefb/YourTurnEvent.go

@@ -93,8 +93,20 @@ func (rcv *YourTurnEvent) ScoreLine() []byte {
 	return nil
 }
 
+func (rcv *YourTurnEvent) MoveCount() int32 {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(16))
+	if o != 0 {
+		return rcv._tab.GetInt32(o + rcv._tab.Pos)
+	}
+	return 0
+}
+
+func (rcv *YourTurnEvent) MutateMoveCount(n int32) bool {
+	return rcv._tab.MutateInt32Slot(16, n)
+}
+
 func YourTurnEventStart(builder *flatbuffers.Builder) {
-	builder.StartObject(6)
+	builder.StartObject(7)
 }
 func YourTurnEventAddGameId(builder *flatbuffers.Builder, gameId flatbuffers.UOffsetT) {
 	builder.PrependUOffsetTSlot(0, flatbuffers.UOffsetT(gameId), 0)
@@ -114,6 +126,9 @@ func YourTurnEventAddLastWord(builder *flatbuffers.Builder, lastWord flatbuffers
 func YourTurnEventAddScoreLine(builder *flatbuffers.Builder, scoreLine flatbuffers.UOffsetT) {
 	builder.PrependUOffsetTSlot(5, flatbuffers.UOffsetT(scoreLine), 0)
 }
+func YourTurnEventAddMoveCount(builder *flatbuffers.Builder, moveCount int32) {
+	builder.PrependInt32Slot(6, moveCount, 0)
+}
 func YourTurnEventEnd(builder *flatbuffers.Builder) flatbuffers.UOffsetT {
 	return builder.EndObject()
 }