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.

pkg/proto/push/v1/push.pb.go

@@ -0,0 +1,214 @@
+// Code generated by protoc-gen-go. DO NOT EDIT.
+// versions:
+// 	protoc-gen-go v1.36.11
+// 	protoc        (unknown)
+// source: push/v1/push.proto
+
+// Package scrabble.push.v1 is the backend -> gateway live-event control channel.
+// The gateway opens Subscribe once at startup and keeps the stream open; the
+// backend pushes one Event per notification intent. The payload is an opaque
+// FlatBuffers message (the scrabblefb.* tables) that the gateway forwards to the
+// client without re-interpreting it. The transport is plain gRPC server-stream
+// (ARCHITECTURE.md §2); the client edge is Connect-RPC (gateway/proto/edge).
+
+package pushv1
+
+import (
+	protoreflect "google.golang.org/protobuf/reflect/protoreflect"
+	protoimpl "google.golang.org/protobuf/runtime/protoimpl"
+	reflect "reflect"
+	sync "sync"
+	unsafe "unsafe"
+)
+
+const (
+	// Verify that this generated code is sufficiently up-to-date.
+	_ = protoimpl.EnforceVersion(20 - protoimpl.MinVersion)
+	// Verify that runtime/protoimpl is sufficiently up-to-date.
+	_ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
+)
+
+// SubscribeRequest opens a push subscription. gateway_id identifies the gateway
+// instance for logging; the MVP backend keeps no per-gateway state.
+type SubscribeRequest struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	GatewayId     string                 `protobuf:"bytes,1,opt,name=gateway_id,json=gatewayId,proto3" json:"gateway_id,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *SubscribeRequest) Reset() {
+	*x = SubscribeRequest{}
+	mi := &file_push_v1_push_proto_msgTypes[0]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *SubscribeRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*SubscribeRequest) ProtoMessage() {}
+
+func (x *SubscribeRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_push_v1_push_proto_msgTypes[0]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use SubscribeRequest.ProtoReflect.Descriptor instead.
+func (*SubscribeRequest) Descriptor() ([]byte, []int) {
+	return file_push_v1_push_proto_rawDescGZIP(), []int{0}
+}
+
+func (x *SubscribeRequest) GetGatewayId() string {
+	if x != nil {
+		return x.GatewayId
+	}
+	return ""
+}
+
+// Event is one live-event frame. kind is the notification catalog kind
+// (your_turn, opponent_moved, chat_message, nudge, match_found). payload is the
+// FlatBuffers-encoded body for that kind. event_id is a correlation id the
+// gateway carries through to the client envelope.
+type Event struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	UserId        string                 `protobuf:"bytes,1,opt,name=user_id,json=userId,proto3" json:"user_id,omitempty"`
+	Kind          string                 `protobuf:"bytes,2,opt,name=kind,proto3" json:"kind,omitempty"`
+	Payload       []byte                 `protobuf:"bytes,3,opt,name=payload,proto3" json:"payload,omitempty"`
+	EventId       string                 `protobuf:"bytes,4,opt,name=event_id,json=eventId,proto3" json:"event_id,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *Event) Reset() {
+	*x = Event{}
+	mi := &file_push_v1_push_proto_msgTypes[1]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *Event) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*Event) ProtoMessage() {}
+
+func (x *Event) ProtoReflect() protoreflect.Message {
+	mi := &file_push_v1_push_proto_msgTypes[1]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use Event.ProtoReflect.Descriptor instead.
+func (*Event) Descriptor() ([]byte, []int) {
+	return file_push_v1_push_proto_rawDescGZIP(), []int{1}
+}
+
+func (x *Event) GetUserId() string {
+	if x != nil {
+		return x.UserId
+	}
+	return ""
+}
+
+func (x *Event) GetKind() string {
+	if x != nil {
+		return x.Kind
+	}
+	return ""
+}
+
+func (x *Event) GetPayload() []byte {
+	if x != nil {
+		return x.Payload
+	}
+	return nil
+}
+
+func (x *Event) GetEventId() string {
+	if x != nil {
+		return x.EventId
+	}
+	return ""
+}
+
+var File_push_v1_push_proto protoreflect.FileDescriptor
+
+const file_push_v1_push_proto_rawDesc = "" +
+	"\n" +
+	"\x12push/v1/push.proto\x12\x10scrabble.push.v1\"1\n" +
+	"\x10SubscribeRequest\x12\x1d\n" +
+	"\n" +
+	"gateway_id\x18\x01 \x01(\tR\tgatewayId\"i\n" +
+	"\x05Event\x12\x17\n" +
+	"\auser_id\x18\x01 \x01(\tR\x06userId\x12\x12\n" +
+	"\x04kind\x18\x02 \x01(\tR\x04kind\x12\x18\n" +
+	"\apayload\x18\x03 \x01(\fR\apayload\x12\x19\n" +
+	"\bevent_id\x18\x04 \x01(\tR\aeventId2R\n" +
+	"\x04Push\x12J\n" +
+	"\tSubscribe\x12\".scrabble.push.v1.SubscribeRequest\x1a\x17.scrabble.push.v1.Event0\x01B#Z!scrabble/pkg/proto/push/v1;pushv1b\x06proto3"
+
+var (
+	file_push_v1_push_proto_rawDescOnce sync.Once
+	file_push_v1_push_proto_rawDescData []byte
+)
+
+func file_push_v1_push_proto_rawDescGZIP() []byte {
+	file_push_v1_push_proto_rawDescOnce.Do(func() {
+		file_push_v1_push_proto_rawDescData = protoimpl.X.CompressGZIP(unsafe.Slice(unsafe.StringData(file_push_v1_push_proto_rawDesc), len(file_push_v1_push_proto_rawDesc)))
+	})
+	return file_push_v1_push_proto_rawDescData
+}
+
+var file_push_v1_push_proto_msgTypes = make([]protoimpl.MessageInfo, 2)
+var file_push_v1_push_proto_goTypes = []any{
+	(*SubscribeRequest)(nil), // 0: scrabble.push.v1.SubscribeRequest
+	(*Event)(nil),            // 1: scrabble.push.v1.Event
+}
+var file_push_v1_push_proto_depIdxs = []int32{
+	0, // 0: scrabble.push.v1.Push.Subscribe:input_type -> scrabble.push.v1.SubscribeRequest
+	1, // 1: scrabble.push.v1.Push.Subscribe:output_type -> scrabble.push.v1.Event
+	1, // [1:2] is the sub-list for method output_type
+	0, // [0:1] is the sub-list for method input_type
+	0, // [0:0] is the sub-list for extension type_name
+	0, // [0:0] is the sub-list for extension extendee
+	0, // [0:0] is the sub-list for field type_name
+}
+
+func init() { file_push_v1_push_proto_init() }
+func file_push_v1_push_proto_init() {
+	if File_push_v1_push_proto != nil {
+		return
+	}
+	type x struct{}
+	out := protoimpl.TypeBuilder{
+		File: protoimpl.DescBuilder{
+			GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
+			RawDescriptor: unsafe.Slice(unsafe.StringData(file_push_v1_push_proto_rawDesc), len(file_push_v1_push_proto_rawDesc)),
+			NumEnums:      0,
+			NumMessages:   2,
+			NumExtensions: 0,
+			NumServices:   1,
+		},
+		GoTypes:           file_push_v1_push_proto_goTypes,
+		DependencyIndexes: file_push_v1_push_proto_depIdxs,
+		MessageInfos:      file_push_v1_push_proto_msgTypes,
+	}.Build()
+	File_push_v1_push_proto = out.File
+	file_push_v1_push_proto_goTypes = nil
+	file_push_v1_push_proto_depIdxs = nil
+}

pkg/proto/push/v1/push.proto

@@ -0,0 +1,36 @@
+syntax = "proto3";
+
+// Package scrabble.push.v1 is the backend -> gateway live-event control channel.
+// The gateway opens Subscribe once at startup and keeps the stream open; the
+// backend pushes one Event per notification intent. The payload is an opaque
+// FlatBuffers message (the scrabblefb.* tables) that the gateway forwards to the
+// client without re-interpreting it. The transport is plain gRPC server-stream
+// (ARCHITECTURE.md §2); the client edge is Connect-RPC (gateway/proto/edge).
+package scrabble.push.v1;
+
+option go_package = "scrabble/pkg/proto/push/v1;pushv1";
+
+// Push is the unidirectional live-event channel from backend to gateway.
+service Push {
+  // Subscribe opens the single backend -> gateway event stream. The backend
+  // sends every event for every user; the gateway fans them out to the active
+  // client subscriptions by user_id.
+  rpc Subscribe(SubscribeRequest) returns (stream Event);
+}
+
+// SubscribeRequest opens a push subscription. gateway_id identifies the gateway
+// instance for logging; the MVP backend keeps no per-gateway state.
+message SubscribeRequest {
+  string gateway_id = 1;
+}
+
+// Event is one live-event frame. kind is the notification catalog kind
+// (your_turn, opponent_moved, chat_message, nudge, match_found). payload is the
+// FlatBuffers-encoded body for that kind. event_id is a correlation id the
+// gateway carries through to the client envelope.
+message Event {
+  string user_id = 1;
+  string kind = 2;
+  bytes payload = 3;
+  string event_id = 4;
+}

pkg/proto/push/v1/push_grpc.pb.go

@@ -0,0 +1,141 @@
+// Code generated by protoc-gen-go-grpc. DO NOT EDIT.
+// versions:
+// - protoc-gen-go-grpc v1.5.1
+// - protoc             (unknown)
+// source: push/v1/push.proto
+
+// Package scrabble.push.v1 is the backend -> gateway live-event control channel.
+// The gateway opens Subscribe once at startup and keeps the stream open; the
+// backend pushes one Event per notification intent. The payload is an opaque
+// FlatBuffers message (the scrabblefb.* tables) that the gateway forwards to the
+// client without re-interpreting it. The transport is plain gRPC server-stream
+// (ARCHITECTURE.md §2); the client edge is Connect-RPC (gateway/proto/edge).
+
+package pushv1
+
+import (
+	context "context"
+	grpc "google.golang.org/grpc"
+	codes "google.golang.org/grpc/codes"
+	status "google.golang.org/grpc/status"
+)
+
+// This is a compile-time assertion to ensure that this generated file
+// is compatible with the grpc package it is being compiled against.
+// Requires gRPC-Go v1.64.0 or later.
+const _ = grpc.SupportPackageIsVersion9
+
+const (
+	Push_Subscribe_FullMethodName = "/scrabble.push.v1.Push/Subscribe"
+)
+
+// PushClient is the client API for Push service.
+//
+// For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream.
+//
+// Push is the unidirectional live-event channel from backend to gateway.
+type PushClient interface {
+	// Subscribe opens the single backend -> gateway event stream. The backend
+	// sends every event for every user; the gateway fans them out to the active
+	// client subscriptions by user_id.
+	Subscribe(ctx context.Context, in *SubscribeRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[Event], error)
+}
+
+type pushClient struct {
+	cc grpc.ClientConnInterface
+}
+
+func NewPushClient(cc grpc.ClientConnInterface) PushClient {
+	return &pushClient{cc}
+}
+
+func (c *pushClient) Subscribe(ctx context.Context, in *SubscribeRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[Event], error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	stream, err := c.cc.NewStream(ctx, &Push_ServiceDesc.Streams[0], Push_Subscribe_FullMethodName, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	x := &grpc.GenericClientStream[SubscribeRequest, Event]{ClientStream: stream}
+	if err := x.ClientStream.SendMsg(in); err != nil {
+		return nil, err
+	}
+	if err := x.ClientStream.CloseSend(); err != nil {
+		return nil, err
+	}
+	return x, nil
+}
+
+// This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
+type Push_SubscribeClient = grpc.ServerStreamingClient[Event]
+
+// PushServer is the server API for Push service.
+// All implementations must embed UnimplementedPushServer
+// for forward compatibility.
+//
+// Push is the unidirectional live-event channel from backend to gateway.
+type PushServer interface {
+	// Subscribe opens the single backend -> gateway event stream. The backend
+	// sends every event for every user; the gateway fans them out to the active
+	// client subscriptions by user_id.
+	Subscribe(*SubscribeRequest, grpc.ServerStreamingServer[Event]) error
+	mustEmbedUnimplementedPushServer()
+}
+
+// UnimplementedPushServer must be embedded to have
+// forward compatible implementations.
+//
+// NOTE: this should be embedded by value instead of pointer to avoid a nil
+// pointer dereference when methods are called.
+type UnimplementedPushServer struct{}
+
+func (UnimplementedPushServer) Subscribe(*SubscribeRequest, grpc.ServerStreamingServer[Event]) error {
+	return status.Errorf(codes.Unimplemented, "method Subscribe not implemented")
+}
+func (UnimplementedPushServer) mustEmbedUnimplementedPushServer() {}
+func (UnimplementedPushServer) testEmbeddedByValue()              {}
+
+// UnsafePushServer may be embedded to opt out of forward compatibility for this service.
+// Use of this interface is not recommended, as added methods to PushServer will
+// result in compilation errors.
+type UnsafePushServer interface {
+	mustEmbedUnimplementedPushServer()
+}
+
+func RegisterPushServer(s grpc.ServiceRegistrar, srv PushServer) {
+	// If the following call pancis, it indicates UnimplementedPushServer was
+	// embedded by pointer and is nil.  This will cause panics if an
+	// unimplemented method is ever invoked, so we test this at initialization
+	// time to prevent it from happening at runtime later due to I/O.
+	if t, ok := srv.(interface{ testEmbeddedByValue() }); ok {
+		t.testEmbeddedByValue()
+	}
+	s.RegisterService(&Push_ServiceDesc, srv)
+}
+
+func _Push_Subscribe_Handler(srv interface{}, stream grpc.ServerStream) error {
+	m := new(SubscribeRequest)
+	if err := stream.RecvMsg(m); err != nil {
+		return err
+	}
+	return srv.(PushServer).Subscribe(m, &grpc.GenericServerStream[SubscribeRequest, Event]{ServerStream: stream})
+}
+
+// This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.
+type Push_SubscribeServer = grpc.ServerStreamingServer[Event]
+
+// Push_ServiceDesc is the grpc.ServiceDesc for Push service.
+// It's only intended for direct use with grpc.RegisterService,
+// and not to be introspected or modified (even as a copy)
+var Push_ServiceDesc = grpc.ServiceDesc{
+	ServiceName: "scrabble.push.v1.Push",
+	HandlerType: (*PushServer)(nil),
+	Methods:     []grpc.MethodDesc{},
+	Streams: []grpc.StreamDesc{
+		{
+			StreamName:    "Subscribe",
+			Handler:       _Push_Subscribe_Handler,
+			ServerStreams: true,
+		},
+	},
+	Metadata: "push/v1/push.proto",
+}