feat(chat): unread read-receipts with lobby/game dot and history-open ack

Persist per-message read state as a chat_messages.unread_seats bitmask
(migration 00008): a text message seeds every recipient seat's bit, a nudge
only the awaited seat's. A seat's bit clears when the player opens the move
history or chat (POST /games/:id/chat/read, sent only when something is
unread), and a nudge additionally clears when its recipient answers by moving
(a wired game NudgeClearer, dependency-inverted so game keeps off social).

UI shows a per-viewer unread dot in the lobby (next to the opponent) and the
game score bar — the unread_chat game-view flag seeds it from authoritative
REST views, live chat/nudge events raise it. Opening the move history counts
as reading (even without entering chat): the 💬 fade-blinks twice and the
client acks. Admin Messages gains an unread-only filter, a read/unread column,
and a per-message card with the per-seat read breakdown. Observability:
chat_read_duration histogram + chat_unread_messages gauge + social tracing.

gateway/internal/backendclient/api.go

@@ -134,6 +134,7 @@ type GameResp struct {
 	EndReason            string     `json:"end_reason"`
 	LastActivityUnix     int64      `json:"last_activity_unix"`
 	Seats                []SeatResp `json:"seats"`
+	UnreadChat           bool       `json:"unread_chat"`
 }
 
 // MoveResultResp is the outcome of a committed move. Rack carries the actor's refilled rack as
@@ -468,6 +469,13 @@ func (c *Client) Nudge(ctx context.Context, userID, gameID string) (ChatResp, er
 	return out, err
 }
 
+// MarkChatRead acknowledges that the caller has read the game's chat (sent when they open
+// the move history or chat), so the backend clears their unread bits and records the
+// publish-to-read latency.
+func (c *Client) MarkChatRead(ctx context.Context, userID, gameID string) error {
+	return c.do(ctx, http.MethodPost, c.gamePath(gameID, "/chat/read"), userID, "", struct{}{}, nil)
+}
+
 // GamesList returns the caller's active and finished games.
 func (c *Client) GamesList(ctx context.Context, userID string) (GameListResp, error) {
 	var out GameListResp

gateway/internal/transcode/encode.go

@@ -438,6 +438,7 @@ func toWireGame(g backendclient.GameResp) wire.GameView {
 		EndReason:            g.EndReason,
 		Seats:                seats,
 		LastActivityUnix:     g.LastActivityUnix,
+		UnreadChat:           g.UnreadChat,
 	}
 }
 

gateway/internal/transcode/transcode.go

@@ -40,6 +40,7 @@ const (
 	MsgGameHistory    = "game.history"
 	MsgChatList       = "chat.list"
 	MsgChatNudge      = "chat.nudge"
+	MsgChatRead       = "chat.read"
 	MsgDraftGet       = "draft.get"
 	MsgDraftSave      = "draft.save"
 	MsgGameHide       = "game.hide"
@@ -121,6 +122,7 @@ func NewRegistry(backend *backendclient.Client, tg TelegramValidator, defaultLan
 	r.ops[MsgGameHistory] = Op{Handler: historyHandler(backend), Auth: true}
 	r.ops[MsgChatList] = Op{Handler: chatListHandler(backend), Auth: true}
 	r.ops[MsgChatNudge] = Op{Handler: nudgeHandler(backend), Auth: true}
+	r.ops[MsgChatRead] = Op{Handler: markChatReadHandler(backend), Auth: true}
 	r.ops[MsgDraftGet] = Op{Handler: getDraftHandler(backend), Auth: true}
 	r.ops[MsgDraftSave] = Op{Handler: saveDraftHandler(backend), Auth: true}
 	r.ops[MsgGameHide] = Op{Handler: hideGameHandler(backend), Auth: true}
@@ -451,6 +453,18 @@ func nudgeHandler(backend *backendclient.Client) Handler {
 	}
 }
 
+// markChatReadHandler acknowledges the caller has read the game's chat. It reuses
+// GameActionRequest for the game id and echoes an Ack.
+func markChatReadHandler(backend *backendclient.Client) Handler {
+	return func(ctx context.Context, req Request) ([]byte, error) {
+		in := fb.GetRootAsGameActionRequest(req.Payload, 0)
+		if err := backend.MarkChatRead(ctx, req.UserID, string(in.GameId())); err != nil {
+			return nil, err
+		}
+		return encodeAck(true), nil
+	}
+}
+
 // getDraftHandler returns the player's saved composition. It reuses
 // GameActionRequest for the game id and wraps the backend's raw JSON in a DraftView.
 func getDraftHandler(backend *backendclient.Client) Handler {

gateway/internal/transcode/transcode_test.go

@@ -213,6 +213,39 @@ func TestHideGameForwardsToBackend(t *testing.T) {
 	}
 }
 
+// TestMarkChatReadForwardsToBackend checks chat.read reuses GameActionRequest, POSTs to the
+// game's /chat/read endpoint with the caller's id, and echoes an Ack.
+func TestMarkChatReadForwardsToBackend(t *testing.T) {
+	var hit bool
+	backend, cleanup := fakeBackend(t, func(w http.ResponseWriter, r *http.Request) {
+		hit = true
+		if r.Method != http.MethodPost || r.URL.Path != "/api/v1/user/games/g-1/chat/read" {
+			t.Errorf("unexpected %s %q", r.Method, r.URL.Path)
+		}
+		if got := r.Header.Get("X-User-ID"); got != "u-1" {
+			t.Errorf("X-User-ID = %q, want u-1", got)
+		}
+		_, _ = w.Write([]byte(`{"ok":true}`))
+	})
+	defer cleanup()
+
+	reg := transcode.NewRegistry(backend, nil)
+	op, ok := reg.Lookup(transcode.MsgChatRead)
+	if !ok {
+		t.Fatal("chat.read not registered")
+	}
+	payload, err := op.Handler(context.Background(), transcode.Request{UserID: "u-1", Payload: gameActionPayload("g-1")})
+	if err != nil {
+		t.Fatalf("handler: %v", err)
+	}
+	if !hit {
+		t.Error("backend not called")
+	}
+	if ack := fb.GetRootAsAck(payload, 0); !ack.Ok() {
+		t.Error("ack not ok")
+	}
+}
+
 func TestGamesListRoundTripDecodesSeatNames(t *testing.T) {
 	backend, cleanup := fakeBackend(t, func(w http.ResponseWriter, r *http.Request) {
 		if got := r.Header.Get("X-User-ID"); got != "u-9" {
@@ -221,7 +254,7 @@ func TestGamesListRoundTripDecodesSeatNames(t *testing.T) {
 		if r.URL.Path != "/api/v1/user/games" {
 			t.Errorf("unexpected path %q", r.URL.Path)
 		}
-		_, _ = w.Write([]byte(`{"games":[{"id":"g-1","variant":"scrabble_en","status":"active","players":2,"to_move":0,"last_activity_unix":1717000000,"seats":[{"seat":0,"account_id":"u-9","display_name":"You","score":10},{"seat":1,"account_id":"a-1","display_name":"Ann","score":7}]}],"at_game_limit":true}`))
+		_, _ = w.Write([]byte(`{"games":[{"id":"g-1","variant":"scrabble_en","status":"active","players":2,"to_move":0,"last_activity_unix":1717000000,"unread_chat":true,"seats":[{"seat":0,"account_id":"u-9","display_name":"You","score":10},{"seat":1,"account_id":"a-1","display_name":"Ann","score":7}]}],"at_game_limit":true}`))
 	})
 	defer cleanup()
 
@@ -243,6 +276,9 @@ func TestGamesListRoundTripDecodesSeatNames(t *testing.T) {
 	if g.LastActivityUnix() != 1717000000 {
 		t.Errorf("last activity = %d, want 1717000000", g.LastActivityUnix())
 	}
+	if !g.UnreadChat() {
+		t.Error("unread_chat = false, want true (the backend flagged unread for the viewer)")
+	}
 	var seat fb.SeatView
 	g.Seats(&seat, 1)
 	if string(seat.DisplayName()) != "Ann" {