feat(ads): server-driven ad-banner backend, wire & admin console (PR1)

Turn the gated-off mock banner into a real advertising subsystem (backend +
admin half; the UI rotation lands in PR2).

- internal/ads: campaigns (percent weight + validity window; a perpetual,
  undeletable default that fills the remainder up to 100%), 1..N bilingual
  messages (en+ru), global display timings; ActiveSet computes the
  window-filtered, default-remainder, GCD-reduced, language-resolved rotation
  feed. Smooth-weighted-round-robin math is unit-tested.
- migration 00006 (+ jetgen): ad_campaigns / ad_messages / ad_settings, seeded
  default campaign + house message + default timings.
- eligibility = !paid_account && hint_balance==0 && !no_banner role (new role;
  guests qualify). The resolved feed rides the profile.get response (no new RPC,
  works for guests, nothing distinct to filter); language by service_language.
- live update: a notify `banner` sub-kind (re-poll signal) published when an
  operator grants hints or grants/revokes no_banner, so the client shows/hides
  in place.
- admin console /_gm/banners (+ /_gm/banner-settings): campaign + message CRUD
  with reorder, default protection, clamped timings.
- wire: fbs BannerInfo/BannerCampaign on Profile; gateway transcode forwards it.
- docs: ARCHITECTURE §10, FUNCTIONAL (+ _ru), backend README, PRERELEASE tracker
  (incl. the deferred app.load aggregator note).

gateway/internal/transcode/encode.go

@@ -58,7 +58,8 @@ func encodeAck(ok bool) []byte {
 	return b.FinishedBytes()
 }
 
-// encodeProfile builds a Profile payload.
+// encodeProfile builds a Profile payload, including the advertising-banner block
+// when the backend marked the viewer eligible.
 func encodeProfile(p backendclient.ProfileResp) []byte {
 	b := flatbuffers.NewBuilder(192)
 	uid := b.CreateString(p.UserID)
@@ -67,6 +68,12 @@ func encodeProfile(p backendclient.ProfileResp) []byte {
 	tz := b.CreateString(p.TimeZone)
 	awayStart := b.CreateString(p.AwayStart)
 	awayEnd := b.CreateString(p.AwayEnd)
+	// Build the banner table (and its children) before opening Profile: FlatBuffers
+	// forbids a nested table while another is under construction.
+	var banner flatbuffers.UOffsetT
+	if p.Banner != nil {
+		banner = encodeBanner(b, *p.Banner)
+	}
 	fb.ProfileStart(b)
 	fb.ProfileAddUserId(b, uid)
 	fb.ProfileAddDisplayName(b, name)
@@ -79,10 +86,51 @@ func encodeProfile(p backendclient.ProfileResp) []byte {
 	fb.ProfileAddAwayStart(b, awayStart)
 	fb.ProfileAddAwayEnd(b, awayEnd)
 	fb.ProfileAddNotificationsInAppOnly(b, p.NotificationsInAppOnly)
+	if p.Banner != nil {
+		fb.ProfileAddBanner(b, banner)
+	}
 	b.Finish(fb.ProfileEnd(b))
 	return b.FinishedBytes()
 }
 
+// encodeBanner builds a BannerInfo table from the resolved banner block and
+// returns its offset. It is bottom-up: each campaign's messages vector and table
+// are built first, then the campaigns vector, then the BannerInfo table. The
+// caller must invoke it with no table under construction.
+func encodeBanner(b *flatbuffers.Builder, banner backendclient.BannerResp) flatbuffers.UOffsetT {
+	campOffsets := make([]flatbuffers.UOffsetT, len(banner.Campaigns))
+	for i, c := range banner.Campaigns {
+		msgOffsets := make([]flatbuffers.UOffsetT, len(c.Messages))
+		for j, m := range c.Messages {
+			msgOffsets[j] = b.CreateString(m)
+		}
+		fb.BannerCampaignStartMessagesVector(b, len(msgOffsets))
+		for j := len(msgOffsets) - 1; j >= 0; j-- {
+			b.PrependUOffsetT(msgOffsets[j])
+		}
+		msgs := b.EndVector(len(msgOffsets))
+		fb.BannerCampaignStart(b)
+		fb.BannerCampaignAddWeight(b, int32(c.Weight))
+		fb.BannerCampaignAddMessages(b, msgs)
+		campOffsets[i] = fb.BannerCampaignEnd(b)
+	}
+	fb.BannerInfoStartCampaignsVector(b, len(campOffsets))
+	for i := len(campOffsets) - 1; i >= 0; i-- {
+		b.PrependUOffsetT(campOffsets[i])
+	}
+	camps := b.EndVector(len(campOffsets))
+	t := banner.Timings
+	fb.BannerInfoStart(b)
+	fb.BannerInfoAddCampaigns(b, camps)
+	fb.BannerInfoAddHoldMs(b, int32(t.HoldMs))
+	fb.BannerInfoAddEdgePauseMs(b, int32(t.EdgePauseMs))
+	fb.BannerInfoAddScrollPxPerSec(b, int32(t.ScrollPxPerSec))
+	fb.BannerInfoAddFadeOutMs(b, int32(t.FadeOutMs))
+	fb.BannerInfoAddGapMs(b, int32(t.GapMs))
+	fb.BannerInfoAddFadeInMs(b, int32(t.FadeInMs))
+	return fb.BannerInfoEnd(b)
+}
+
 // encodeBlockStatus builds a BlockStatus payload.
 func encodeBlockStatus(s backendclient.BlockStatusResp) []byte {
 	b := flatbuffers.NewBuilder(128)

gateway/internal/transcode/transcode_banner_test.go

@@ -0,0 +1,81 @@
+package transcode_test
+
+import (
+	"context"
+	"net/http"
+	"testing"
+
+	"scrabble/gateway/internal/transcode"
+	fb "scrabble/pkg/fbs/scrabblefb"
+)
+
+// TestProfileGetEncodesBanner verifies the gateway forwards the backend's banner
+// block verbatim into the Profile payload: the campaigns (weight + resolved
+// messages, in order) and the global display timings.
+func TestProfileGetEncodesBanner(t *testing.T) {
+	backend, cleanup := fakeBackend(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet || r.URL.Path != "/api/v1/user/profile" {
+			t.Errorf("unexpected %s %q", r.Method, r.URL.Path)
+		}
+		_, _ = w.Write([]byte(`{"user_id":"u-1","display_name":"Kaya","preferred_language":"en",` +
+			`"banner":{"campaigns":[` +
+			`{"weight":3,"messages":["promo-en"]},` +
+			`{"weight":7,"messages":["house-a","house-b"]}],` +
+			`"timings":{"hold_ms":60000,"edge_pause_ms":5000,"scroll_px_per_sec":40,` +
+			`"fade_out_ms":1000,"gap_ms":250,"fade_in_ms":1000}}}`))
+	})
+	defer cleanup()
+
+	reg := transcode.NewRegistry(backend, nil)
+	op, ok := reg.Lookup(transcode.MsgProfileGet)
+	if !ok {
+		t.Fatal("profile.get not registered")
+	}
+	payload, err := op.Handler(context.Background(), transcode.Request{UserID: "u-1"})
+	if err != nil {
+		t.Fatalf("handler: %v", err)
+	}
+
+	p := fb.GetRootAsProfile(payload, 0)
+	banner := p.Banner(nil)
+	if banner == nil {
+		t.Fatal("profile carries no banner block")
+	}
+	if got := banner.CampaignsLength(); got != 2 {
+		t.Fatalf("campaigns = %d, want 2", got)
+	}
+	var c fb.BannerCampaign
+	banner.Campaigns(&c, 0)
+	if c.Weight() != 3 || c.MessagesLength() != 1 || string(c.Messages(0)) != "promo-en" {
+		t.Errorf("campaign 0 = weight %d, %d msgs, msg0=%q", c.Weight(), c.MessagesLength(), c.Messages(0))
+	}
+	banner.Campaigns(&c, 1)
+	if c.Weight() != 7 || c.MessagesLength() != 2 || string(c.Messages(1)) != "house-b" {
+		t.Errorf("campaign 1 = weight %d, %d msgs, msg1=%q", c.Weight(), c.MessagesLength(), c.Messages(1))
+	}
+	if banner.HoldMs() != 60000 || banner.EdgePauseMs() != 5000 || banner.ScrollPxPerSec() != 40 {
+		t.Errorf("timings = hold %d edge %d scroll %d", banner.HoldMs(), banner.EdgePauseMs(), banner.ScrollPxPerSec())
+	}
+	if banner.FadeOutMs() != 1000 || banner.GapMs() != 250 || banner.FadeInMs() != 1000 {
+		t.Errorf("fade timings = out %d gap %d in %d", banner.FadeOutMs(), banner.GapMs(), banner.FadeInMs())
+	}
+}
+
+// TestProfileGetNoBanner verifies an ineligible viewer's profile carries no
+// banner block (the backend omits it).
+func TestProfileGetNoBanner(t *testing.T) {
+	backend, cleanup := fakeBackend(t, func(w http.ResponseWriter, r *http.Request) {
+		_, _ = w.Write([]byte(`{"user_id":"u-1","display_name":"Kaya","preferred_language":"en"}`))
+	})
+	defer cleanup()
+
+	reg := transcode.NewRegistry(backend, nil)
+	op, _ := reg.Lookup(transcode.MsgProfileGet)
+	payload, err := op.Handler(context.Background(), transcode.Request{UserID: "u-1"})
+	if err != nil {
+		t.Fatalf("handler: %v", err)
+	}
+	if p := fb.GetRootAsProfile(payload, 0); p.Banner(nil) != nil {
+		t.Error("ineligible profile unexpectedly carries a banner block")
+	}
+}