Stage 6: gateway edge (Connect/FlatBuffers over h2c, platform/email/guest auth, sessions, rate-limit, admin passthrough, live push bridge)

New public ingress and the first network edge. Framework + a vertical slice of
operations end-to-end; remaining ops reuse the same transcode pattern in Stage 7.

Contracts (new module scrabble/pkg):
- push.proto (backend->gateway gRPC server-stream) + scrabble.fbs (FlatBuffers
  edge payloads), committed generated Go; buf/flatc Makefiles (dev-time codegen).

Backend:
- REST handlers on the /api/v1 groups: internal session endpoints
  (telegram/guest/email login -> mint, resolve, revoke) and the user slice
  (profile, submit_play, state, lobby enqueue/poll, chat).
- internal/notify in-process Publisher hub + internal/pushgrpc gRPC server
  (BACKEND_GRPC_ADDR) streaming your_turn/opponent_moved/chat/nudge/match_found;
  emission in game.commit, social, matchmaker.
- migration 00005 accounts.is_guest; guests are durable rows excluded from stats;
  ProvisionGuest; email-as-login (RequestLoginCode/LoginWithCode).

Gateway (new module scrabble/gateway):
- Connect Gateway service over h2c (Execute + Subscribe), FlatBuffers<->JSON
  transcode registry, Telegram initData HMAC validator (seam), session cache,
  token-bucket rate limiter (3 classes), push fan-out hub, backend REST + push
  gRPC client, admin Basic-Auth reverse proxy.

go.work: use ./pkg, ./gateway + replace scrabble/pkg. CI: gateway/**, pkg/**
path filters; unit build/vet/test span all three modules. Docs (PLAN,
ARCHITECTURE, FUNCTIONAL+ru, TESTING, READMEs) updated; gateway/pkg unit tests +
guest/email-login integration tests.

gateway/internal/transcode/encode.go

@@ -0,0 +1,209 @@
+package transcode
+
+import (
+	flatbuffers "github.com/google/flatbuffers/go"
+
+	"scrabble/gateway/internal/backendclient"
+	fb "scrabble/pkg/fbs/scrabblefb"
+)
+
+// The encoders build the FlatBuffers response payloads from the backend's typed
+// responses. FlatBuffers is built bottom-up: every string and child vector is
+// created before the table that references it, and no two tables/vectors are
+// under construction at once.
+
+// encodeSession builds a Session payload.
+func encodeSession(s backendclient.SessionResp) []byte {
+	b := flatbuffers.NewBuilder(128)
+	token := b.CreateString(s.Token)
+	uid := b.CreateString(s.UserID)
+	name := b.CreateString(s.DisplayName)
+	fb.SessionStart(b)
+	fb.SessionAddToken(b, token)
+	fb.SessionAddUserId(b, uid)
+	fb.SessionAddIsGuest(b, s.IsGuest)
+	fb.SessionAddDisplayName(b, name)
+	b.Finish(fb.SessionEnd(b))
+	return b.FinishedBytes()
+}
+
+// encodeAck builds an Ack payload.
+func encodeAck(ok bool) []byte {
+	b := flatbuffers.NewBuilder(16)
+	fb.AckStart(b)
+	fb.AckAddOk(b, ok)
+	b.Finish(fb.AckEnd(b))
+	return b.FinishedBytes()
+}
+
+// encodeProfile builds a Profile payload.
+func encodeProfile(p backendclient.ProfileResp) []byte {
+	b := flatbuffers.NewBuilder(192)
+	uid := b.CreateString(p.UserID)
+	name := b.CreateString(p.DisplayName)
+	lang := b.CreateString(p.PreferredLanguage)
+	tz := b.CreateString(p.TimeZone)
+	fb.ProfileStart(b)
+	fb.ProfileAddUserId(b, uid)
+	fb.ProfileAddDisplayName(b, name)
+	fb.ProfileAddPreferredLanguage(b, lang)
+	fb.ProfileAddTimeZone(b, tz)
+	fb.ProfileAddHintBalance(b, int32(p.HintBalance))
+	fb.ProfileAddBlockChat(b, p.BlockChat)
+	fb.ProfileAddBlockFriendRequests(b, p.BlockFriendRequests)
+	fb.ProfileAddIsGuest(b, p.IsGuest)
+	b.Finish(fb.ProfileEnd(b))
+	return b.FinishedBytes()
+}
+
+// encodeMoveResult builds a MoveResult payload.
+func encodeMoveResult(r backendclient.MoveResultResp) []byte {
+	b := flatbuffers.NewBuilder(512)
+	move := buildMoveRecord(b, r.Move)
+	game := buildGameView(b, r.Game)
+	fb.MoveResultStart(b)
+	fb.MoveResultAddMove(b, move)
+	fb.MoveResultAddGame(b, game)
+	b.Finish(fb.MoveResultEnd(b))
+	return b.FinishedBytes()
+}
+
+// encodeState builds a StateView payload.
+func encodeState(s backendclient.StateResp) []byte {
+	b := flatbuffers.NewBuilder(512)
+	game := buildGameView(b, s.Game)
+	rack := buildStringVector(b, s.Rack, fb.StateViewStartRackVector)
+	fb.StateViewStart(b)
+	fb.StateViewAddGame(b, game)
+	fb.StateViewAddSeat(b, int32(s.Seat))
+	fb.StateViewAddRack(b, rack)
+	fb.StateViewAddBagLen(b, int32(s.BagLen))
+	fb.StateViewAddHintsRemaining(b, int32(s.HintsRemaining))
+	b.Finish(fb.StateViewEnd(b))
+	return b.FinishedBytes()
+}
+
+// encodeMatch builds a MatchResult payload.
+func encodeMatch(m backendclient.MatchResp) []byte {
+	b := flatbuffers.NewBuilder(512)
+	matched := m.Matched && m.Game != nil
+	var game flatbuffers.UOffsetT
+	if matched {
+		game = buildGameView(b, *m.Game)
+	}
+	fb.MatchResultStart(b)
+	fb.MatchResultAddMatched(b, matched)
+	if matched {
+		fb.MatchResultAddGame(b, game)
+	}
+	b.Finish(fb.MatchResultEnd(b))
+	return b.FinishedBytes()
+}
+
+// encodeChat builds a ChatMessage payload.
+func encodeChat(c backendclient.ChatResp) []byte {
+	b := flatbuffers.NewBuilder(192)
+	id := b.CreateString(c.ID)
+	gid := b.CreateString(c.GameID)
+	sid := b.CreateString(c.SenderID)
+	kind := b.CreateString(c.Kind)
+	body := b.CreateString(c.Body)
+	fb.ChatMessageStart(b)
+	fb.ChatMessageAddId(b, id)
+	fb.ChatMessageAddGameId(b, gid)
+	fb.ChatMessageAddSenderId(b, sid)
+	fb.ChatMessageAddKind(b, kind)
+	fb.ChatMessageAddBody(b, body)
+	fb.ChatMessageAddCreatedAtUnix(b, c.CreatedAtUnix)
+	b.Finish(fb.ChatMessageEnd(b))
+	return b.FinishedBytes()
+}
+
+// buildGameView builds a GameView table and returns its offset.
+func buildGameView(b *flatbuffers.Builder, g backendclient.GameResp) flatbuffers.UOffsetT {
+	seatOffs := make([]flatbuffers.UOffsetT, len(g.Seats))
+	for i, s := range g.Seats {
+		aid := b.CreateString(s.AccountID)
+		fb.SeatViewStart(b)
+		fb.SeatViewAddSeat(b, int32(s.Seat))
+		fb.SeatViewAddAccountId(b, aid)
+		fb.SeatViewAddScore(b, int32(s.Score))
+		fb.SeatViewAddHintsUsed(b, int32(s.HintsUsed))
+		fb.SeatViewAddIsWinner(b, s.IsWinner)
+		seatOffs[i] = fb.SeatViewEnd(b)
+	}
+	fb.GameViewStartSeatsVector(b, len(seatOffs))
+	for i := len(seatOffs) - 1; i >= 0; i-- {
+		b.PrependUOffsetT(seatOffs[i])
+	}
+	seats := b.EndVector(len(seatOffs))
+
+	id := b.CreateString(g.ID)
+	variant := b.CreateString(g.Variant)
+	dictVer := b.CreateString(g.DictVersion)
+	status := b.CreateString(g.Status)
+	endReason := b.CreateString(g.EndReason)
+
+	fb.GameViewStart(b)
+	fb.GameViewAddId(b, id)
+	fb.GameViewAddVariant(b, variant)
+	fb.GameViewAddDictVersion(b, dictVer)
+	fb.GameViewAddStatus(b, status)
+	fb.GameViewAddPlayers(b, int32(g.Players))
+	fb.GameViewAddToMove(b, int32(g.ToMove))
+	fb.GameViewAddTurnTimeoutSecs(b, int32(g.TurnTimeoutSecs))
+	fb.GameViewAddMoveCount(b, int32(g.MoveCount))
+	fb.GameViewAddEndReason(b, endReason)
+	fb.GameViewAddSeats(b, seats)
+	return fb.GameViewEnd(b)
+}
+
+// buildMoveRecord builds a MoveRecord table and returns its offset.
+func buildMoveRecord(b *flatbuffers.Builder, m backendclient.MoveRecordResp) flatbuffers.UOffsetT {
+	tileOffs := make([]flatbuffers.UOffsetT, len(m.Tiles))
+	for i, t := range m.Tiles {
+		letter := b.CreateString(t.Letter)
+		fb.TileRecordStart(b)
+		fb.TileRecordAddRow(b, int32(t.Row))
+		fb.TileRecordAddCol(b, int32(t.Col))
+		fb.TileRecordAddLetter(b, letter)
+		fb.TileRecordAddBlank(b, t.Blank)
+		tileOffs[i] = fb.TileRecordEnd(b)
+	}
+	fb.MoveRecordStartTilesVector(b, len(tileOffs))
+	for i := len(tileOffs) - 1; i >= 0; i-- {
+		b.PrependUOffsetT(tileOffs[i])
+	}
+	tiles := b.EndVector(len(tileOffs))
+
+	words := buildStringVector(b, m.Words, fb.MoveRecordStartWordsVector)
+
+	action := b.CreateString(m.Action)
+	dir := b.CreateString(m.Dir)
+	fb.MoveRecordStart(b)
+	fb.MoveRecordAddPlayer(b, int32(m.Player))
+	fb.MoveRecordAddAction(b, action)
+	fb.MoveRecordAddDir(b, dir)
+	fb.MoveRecordAddMainRow(b, int32(m.MainRow))
+	fb.MoveRecordAddMainCol(b, int32(m.MainCol))
+	fb.MoveRecordAddTiles(b, tiles)
+	fb.MoveRecordAddWords(b, words)
+	fb.MoveRecordAddCount(b, int32(m.Count))
+	fb.MoveRecordAddScore(b, int32(m.Score))
+	fb.MoveRecordAddTotal(b, int32(m.Total))
+	return fb.MoveRecordEnd(b)
+}
+
+// buildStringVector builds a vector of strings using the table-specific
+// StartXVector function and returns the vector offset.
+func buildStringVector(b *flatbuffers.Builder, items []string, start func(*flatbuffers.Builder, int) flatbuffers.UOffsetT) flatbuffers.UOffsetT {
+	offs := make([]flatbuffers.UOffsetT, len(items))
+	for i, s := range items {
+		offs[i] = b.CreateString(s)
+	}
+	start(b, len(offs))
+	for i := len(offs) - 1; i >= 0; i-- {
+		b.PrependUOffsetT(offs[i])
+	}
+	return b.EndVector(len(offs))
+}

gateway/internal/transcode/transcode.go

@@ -0,0 +1,221 @@
+// Package transcode is the gateway's FlatBuffers<->REST bridge. Each message type
+// maps to a handler that decodes the FlatBuffers request payload, calls the
+// backend over REST, and encodes the FlatBuffers response. The registry is the
+// authoritative message_type catalog; new operations are added here following the
+// same pattern (PLAN.md Stage 6 vertical slice).
+package transcode
+
+import (
+	"context"
+	"errors"
+
+	"scrabble/gateway/internal/auth"
+	"scrabble/gateway/internal/backendclient"
+	fb "scrabble/pkg/fbs/scrabblefb"
+)
+
+// Message types in the vertical slice.
+const (
+	MsgAuthTelegram   = "auth.telegram"
+	MsgAuthGuest      = "auth.guest"
+	MsgAuthEmailReq   = "auth.email.request"
+	MsgAuthEmailLogin = "auth.email.login"
+	MsgProfileGet     = "profile.get"
+	MsgGameSubmitPlay = "game.submit_play"
+	MsgGameState      = "game.state"
+	MsgLobbyEnqueue   = "lobby.enqueue"
+	MsgLobbyPoll      = "lobby.poll"
+	MsgChatPost       = "chat.post"
+)
+
+// Request is one decoded Execute call.
+type Request struct {
+	Payload  []byte
+	UserID   string // resolved account id; empty for auth (unauthenticated) ops
+	ClientIP string
+}
+
+// Handler runs one operation and returns the FlatBuffers response payload.
+type Handler func(ctx context.Context, req Request) ([]byte, error)
+
+// Op is a registered message type and its policy flags.
+type Op struct {
+	Handler Handler
+	// Auth marks an operation that requires a resolved session (X-User-ID).
+	Auth bool
+	// Email marks the costly email-code path that gets a stricter rate sub-limit.
+	Email bool
+}
+
+// Registry maps message types to their operations.
+type Registry struct {
+	ops map[string]Op
+}
+
+// NewRegistry builds the slice's message-type catalog over the backend client.
+// The Telegram auth op is registered only when a validator is supplied (a bot
+// token is configured); otherwise auth.telegram is simply unknown.
+func NewRegistry(backend *backendclient.Client, tg auth.TelegramValidator) *Registry {
+	r := &Registry{ops: make(map[string]Op)}
+	if tg != nil {
+		r.ops[MsgAuthTelegram] = Op{Handler: authTelegramHandler(backend, tg)}
+	}
+	r.ops[MsgAuthGuest] = Op{Handler: authGuestHandler(backend)}
+	r.ops[MsgAuthEmailReq] = Op{Handler: authEmailRequestHandler(backend), Email: true}
+	r.ops[MsgAuthEmailLogin] = Op{Handler: authEmailLoginHandler(backend), Email: true}
+	r.ops[MsgProfileGet] = Op{Handler: profileHandler(backend), Auth: true}
+	r.ops[MsgGameSubmitPlay] = Op{Handler: submitPlayHandler(backend), Auth: true}
+	r.ops[MsgGameState] = Op{Handler: gameStateHandler(backend), Auth: true}
+	r.ops[MsgLobbyEnqueue] = Op{Handler: enqueueHandler(backend), Auth: true}
+	r.ops[MsgLobbyPoll] = Op{Handler: pollHandler(backend), Auth: true}
+	r.ops[MsgChatPost] = Op{Handler: chatPostHandler(backend), Auth: true}
+	return r
+}
+
+// Lookup returns the operation for messageType, and whether it is registered.
+func (r *Registry) Lookup(messageType string) (Op, bool) {
+	op, ok := r.ops[messageType]
+	return op, ok
+}
+
+// DomainCode maps an error to a stable result code to surface in the Execute
+// envelope, reporting false for an unexpected error the caller should treat as a
+// transport-level internal failure.
+func DomainCode(err error) (string, bool) {
+	var apiErr *backendclient.APIError
+	if errors.As(err, &apiErr) {
+		return apiErr.Code, true
+	}
+	if errors.Is(err, auth.ErrInvalidInitData) {
+		return "invalid_init_data", true
+	}
+	return "", false
+}
+
+func authTelegramHandler(backend *backendclient.Client, tg auth.TelegramValidator) Handler {
+	return func(ctx context.Context, req Request) ([]byte, error) {
+		in := fb.GetRootAsTelegramLoginRequest(req.Payload, 0)
+		user, err := tg.Validate(string(in.InitData()))
+		if err != nil {
+			return nil, err
+		}
+		sess, err := backend.TelegramAuth(ctx, user.ID)
+		if err != nil {
+			return nil, err
+		}
+		return encodeSession(sess), nil
+	}
+}
+
+func authGuestHandler(backend *backendclient.Client) Handler {
+	return func(ctx context.Context, _ Request) ([]byte, error) {
+		sess, err := backend.GuestAuth(ctx)
+		if err != nil {
+			return nil, err
+		}
+		return encodeSession(sess), nil
+	}
+}
+
+func authEmailRequestHandler(backend *backendclient.Client) Handler {
+	return func(ctx context.Context, req Request) ([]byte, error) {
+		in := fb.GetRootAsEmailRequestRequest(req.Payload, 0)
+		if err := backend.EmailRequest(ctx, string(in.Email())); err != nil {
+			return nil, err
+		}
+		return encodeAck(true), nil
+	}
+}
+
+func authEmailLoginHandler(backend *backendclient.Client) Handler {
+	return func(ctx context.Context, req Request) ([]byte, error) {
+		in := fb.GetRootAsEmailLoginRequest(req.Payload, 0)
+		sess, err := backend.EmailLogin(ctx, string(in.Email()), string(in.Code()))
+		if err != nil {
+			return nil, err
+		}
+		return encodeSession(sess), nil
+	}
+}
+
+func profileHandler(backend *backendclient.Client) Handler {
+	return func(ctx context.Context, req Request) ([]byte, error) {
+		p, err := backend.Profile(ctx, req.UserID)
+		if err != nil {
+			return nil, err
+		}
+		return encodeProfile(p), nil
+	}
+}
+
+func submitPlayHandler(backend *backendclient.Client) Handler {
+	return func(ctx context.Context, req Request) ([]byte, error) {
+		in := fb.GetRootAsSubmitPlayRequest(req.Payload, 0)
+		res, err := backend.SubmitPlay(ctx, req.UserID, string(in.GameId()), string(in.Dir()), decodeTiles(in))
+		if err != nil {
+			return nil, err
+		}
+		return encodeMoveResult(res), nil
+	}
+}
+
+func gameStateHandler(backend *backendclient.Client) Handler {
+	return func(ctx context.Context, req Request) ([]byte, error) {
+		in := fb.GetRootAsStateRequest(req.Payload, 0)
+		st, err := backend.GameState(ctx, req.UserID, string(in.GameId()))
+		if err != nil {
+			return nil, err
+		}
+		return encodeState(st), nil
+	}
+}
+
+func enqueueHandler(backend *backendclient.Client) Handler {
+	return func(ctx context.Context, req Request) ([]byte, error) {
+		in := fb.GetRootAsEnqueueRequest(req.Payload, 0)
+		m, err := backend.Enqueue(ctx, req.UserID, string(in.Variant()))
+		if err != nil {
+			return nil, err
+		}
+		return encodeMatch(m), nil
+	}
+}
+
+func pollHandler(backend *backendclient.Client) Handler {
+	return func(ctx context.Context, req Request) ([]byte, error) {
+		m, err := backend.Poll(ctx, req.UserID)
+		if err != nil {
+			return nil, err
+		}
+		return encodeMatch(m), nil
+	}
+}
+
+func chatPostHandler(backend *backendclient.Client) Handler {
+	return func(ctx context.Context, req Request) ([]byte, error) {
+		in := fb.GetRootAsChatPostRequest(req.Payload, 0)
+		c, err := backend.ChatPost(ctx, req.UserID, string(in.GameId()), string(in.Body()), req.ClientIP)
+		if err != nil {
+			return nil, err
+		}
+		return encodeChat(c), nil
+	}
+}
+
+// decodeTiles reads the placed tiles from a SubmitPlayRequest.
+func decodeTiles(in *fb.SubmitPlayRequest) []backendclient.TileJSON {
+	n := in.TilesLength()
+	tiles := make([]backendclient.TileJSON, 0, n)
+	var t fb.TileRecord
+	for i := 0; i < n; i++ {
+		if in.Tiles(&t, i) {
+			tiles = append(tiles, backendclient.TileJSON{
+				Row:    int(t.Row()),
+				Col:    int(t.Col()),
+				Letter: string(t.Letter()),
+				Blank:  t.Blank(),
+			})
+		}
+	}
+	return tiles
+}

gateway/internal/transcode/transcode_test.go

@@ -0,0 +1,141 @@
+package transcode_test
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	flatbuffers "github.com/google/flatbuffers/go"
+
+	"scrabble/gateway/internal/backendclient"
+	"scrabble/gateway/internal/transcode"
+	fb "scrabble/pkg/fbs/scrabblefb"
+)
+
+// fakeBackend serves the subset of backend endpoints the slice handlers call.
+func fakeBackend(t *testing.T, h http.HandlerFunc) (*backendclient.Client, func()) {
+	t.Helper()
+	srv := httptest.NewServer(h)
+	c, err := backendclient.New(srv.URL, "localhost:9090", 2_000_000_000)
+	if err != nil {
+		t.Fatalf("backendclient: %v", err)
+	}
+	return c, func() {
+		_ = c.Close()
+		srv.Close()
+	}
+}
+
+func TestGuestAuthRoundTrip(t *testing.T) {
+	backend, cleanup := fakeBackend(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/api/v1/internal/sessions/guest" {
+			t.Errorf("unexpected path %q", r.URL.Path)
+		}
+		_, _ = w.Write([]byte(`{"token":"tok-1","user_id":"u-1","is_guest":true,"display_name":"Guest"}`))
+	})
+	defer cleanup()
+
+	reg := transcode.NewRegistry(backend, nil)
+	op, ok := reg.Lookup(transcode.MsgAuthGuest)
+	if !ok {
+		t.Fatal("auth.guest not registered")
+	}
+	payload, err := op.Handler(context.Background(), transcode.Request{})
+	if err != nil {
+		t.Fatalf("handler: %v", err)
+	}
+	sess := fb.GetRootAsSession(payload, 0)
+	if string(sess.Token()) != "tok-1" || string(sess.UserId()) != "u-1" || !sess.IsGuest() {
+		t.Fatalf("session decoded wrong: token=%q user=%q guest=%v", sess.Token(), sess.UserId(), sess.IsGuest())
+	}
+}
+
+func TestGameStateRoundTripForwardsUserID(t *testing.T) {
+	backend, cleanup := fakeBackend(t, func(w http.ResponseWriter, r *http.Request) {
+		if got := r.Header.Get("X-User-ID"); got != "u-7" {
+			t.Errorf("X-User-ID = %q, want u-7", got)
+		}
+		if r.URL.Path != "/api/v1/user/games/g-1/state" {
+			t.Errorf("unexpected path %q", r.URL.Path)
+		}
+		_, _ = w.Write([]byte(`{"game":{"id":"g-1","variant":"english","status":"active","players":2,"to_move":1,"seats":[{"seat":0,"account_id":"u-7","score":5}]},"seat":0,"rack":["A","B"],"bag_len":80,"hints_remaining":1}`))
+	})
+	defer cleanup()
+
+	reg := transcode.NewRegistry(backend, nil)
+	op, _ := reg.Lookup(transcode.MsgGameState)
+
+	b := flatbuffers.NewBuilder(32)
+	gid := b.CreateString("g-1")
+	fb.StateRequestStart(b)
+	fb.StateRequestAddGameId(b, gid)
+	b.Finish(fb.StateRequestEnd(b))
+
+	payload, err := op.Handler(context.Background(), transcode.Request{Payload: b.FinishedBytes(), UserID: "u-7"})
+	if err != nil {
+		t.Fatalf("handler: %v", err)
+	}
+	st := fb.GetRootAsStateView(payload, 0)
+	if st.BagLen() != 80 || st.RackLength() != 2 || st.HintsRemaining() != 1 {
+		t.Fatalf("state decoded wrong: bag=%d rack=%d hints=%d", st.BagLen(), st.RackLength(), st.HintsRemaining())
+	}
+	game := st.Game(nil)
+	if game == nil || string(game.Id()) != "g-1" || string(game.Variant()) != "english" || game.ToMove() != 1 {
+		t.Fatalf("nested game decoded wrong: %+v", game)
+	}
+}
+
+func TestEnqueueRoundTripEncodesMatch(t *testing.T) {
+	backend, cleanup := fakeBackend(t, func(w http.ResponseWriter, r *http.Request) {
+		_, _ = w.Write([]byte(`{"matched":true,"game":{"id":"g-9","variant":"english","status":"active","players":2,"to_move":0,"seats":[]}}`))
+	})
+	defer cleanup()
+
+	reg := transcode.NewRegistry(backend, nil)
+	op, _ := reg.Lookup(transcode.MsgLobbyEnqueue)
+
+	b := flatbuffers.NewBuilder(32)
+	v := b.CreateString("english")
+	fb.EnqueueRequestStart(b)
+	fb.EnqueueRequestAddVariant(b, v)
+	b.Finish(fb.EnqueueRequestEnd(b))
+
+	payload, err := op.Handler(context.Background(), transcode.Request{Payload: b.FinishedBytes(), UserID: "u-1"})
+	if err != nil {
+		t.Fatalf("handler: %v", err)
+	}
+	m := fb.GetRootAsMatchResult(payload, 0)
+	if !m.Matched() {
+		t.Fatal("match result should be matched")
+	}
+	if g := m.Game(nil); g == nil || string(g.Id()) != "g-9" {
+		t.Fatalf("match game decoded wrong: %+v", g)
+	}
+}
+
+func TestDomainErrorSurfacesBackendCode(t *testing.T) {
+	backend, cleanup := fakeBackend(t, func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusConflict)
+		_, _ = w.Write([]byte(`{"error":{"code":"not_your_turn","message":"nope"}}`))
+	})
+	defer cleanup()
+
+	reg := transcode.NewRegistry(backend, nil)
+	op, _ := reg.Lookup(transcode.MsgGameState)
+
+	b := flatbuffers.NewBuilder(32)
+	gid := b.CreateString("g-1")
+	fb.StateRequestStart(b)
+	fb.StateRequestAddGameId(b, gid)
+	b.Finish(fb.StateRequestEnd(b))
+
+	_, err := op.Handler(context.Background(), transcode.Request{Payload: b.FinishedBytes(), UserID: "u-1"})
+	if err == nil {
+		t.Fatal("expected backend error")
+	}
+	code, ok := transcode.DomainCode(err)
+	if !ok || code != "not_your_turn" {
+		t.Fatalf("DomainCode = (%q, %v), want (not_your_turn, true)", code, ok)
+	}
+}