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).

pkg/fbs/scrabble.fbs

@@ -137,12 +137,39 @@ table Ack {
   ok:bool;
 }
 
+// --- advertising banner ---
+
+// BannerCampaign is one campaign in the rotation feed: a GCD-reduced show weight
+// (the client runs a smooth weighted round-robin over campaigns by this weight)
+// and its messages in display order, each already resolved to the viewer's bot
+// language (the stored en/ru pair is picked server-side).
+table BannerCampaign {
+  weight:int;
+  messages:[string];
+}
+
+// BannerInfo is the advertising-banner block of an eligible viewer's profile: the
+// campaigns to rotate and the global display timings the client rotator reads.
+// It is present (set on Profile.banner) only when the viewer is eligible to see a
+// banner; absent otherwise. The transition between messages is fade_out_ms, then
+// gap_ms, then fade_in_ms.
+table BannerInfo {
+  campaigns:[BannerCampaign];
+  hold_ms:int;
+  edge_pause_ms:int;
+  scroll_px_per_sec:int;
+  fade_out_ms:int;
+  gap_ms:int;
+  fade_in_ms:int;
+}
+
 // --- profile (authenticated) ---
 
 // Profile is the authenticated account's own profile view. away_start/away_end are
 // the "HH:MM" daily away-window bounds. notifications_in_app_only (default true)
-// suppresses out-of-app platform push, leaving only the in-app live stream (both
-// added trailing — backward-compatible).
+// suppresses out-of-app platform push, leaving only the in-app live stream. banner
+// carries the advertising-banner block for an eligible viewer, absent otherwise
+// (all added trailing — backward-compatible).
 table Profile {
   user_id:string;
   display_name:string;
@@ -155,6 +182,7 @@ table Profile {
   away_start:string;
   away_end:string;
   notifications_in_app_only:bool = true;
+  banner:BannerInfo;
 }
 
 // BlockStatus reports the caller's current manual block. The UI fetches it after any operation

pkg/fbs/scrabblefb/BannerCampaign.go

@@ -0,0 +1,87 @@
+// Code generated by the FlatBuffers compiler. DO NOT EDIT.
+
+package scrabblefb
+
+import (
+	flatbuffers "github.com/google/flatbuffers/go"
+)
+
+type BannerCampaign struct {
+	_tab flatbuffers.Table
+}
+
+func GetRootAsBannerCampaign(buf []byte, offset flatbuffers.UOffsetT) *BannerCampaign {
+	n := flatbuffers.GetUOffsetT(buf[offset:])
+	x := &BannerCampaign{}
+	x.Init(buf, n+offset)
+	return x
+}
+
+func FinishBannerCampaignBuffer(builder *flatbuffers.Builder, offset flatbuffers.UOffsetT) {
+	builder.Finish(offset)
+}
+
+func GetSizePrefixedRootAsBannerCampaign(buf []byte, offset flatbuffers.UOffsetT) *BannerCampaign {
+	n := flatbuffers.GetUOffsetT(buf[offset+flatbuffers.SizeUint32:])
+	x := &BannerCampaign{}
+	x.Init(buf, n+offset+flatbuffers.SizeUint32)
+	return x
+}
+
+func FinishSizePrefixedBannerCampaignBuffer(builder *flatbuffers.Builder, offset flatbuffers.UOffsetT) {
+	builder.FinishSizePrefixed(offset)
+}
+
+func (rcv *BannerCampaign) Init(buf []byte, i flatbuffers.UOffsetT) {
+	rcv._tab.Bytes = buf
+	rcv._tab.Pos = i
+}
+
+func (rcv *BannerCampaign) Table() flatbuffers.Table {
+	return rcv._tab
+}
+
+func (rcv *BannerCampaign) Weight() int32 {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(4))
+	if o != 0 {
+		return rcv._tab.GetInt32(o + rcv._tab.Pos)
+	}
+	return 0
+}
+
+func (rcv *BannerCampaign) MutateWeight(n int32) bool {
+	return rcv._tab.MutateInt32Slot(4, n)
+}
+
+func (rcv *BannerCampaign) Messages(j int) []byte {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(6))
+	if o != 0 {
+		a := rcv._tab.Vector(o)
+		return rcv._tab.ByteVector(a + flatbuffers.UOffsetT(j*4))
+	}
+	return nil
+}
+
+func (rcv *BannerCampaign) MessagesLength() int {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(6))
+	if o != 0 {
+		return rcv._tab.VectorLen(o)
+	}
+	return 0
+}
+
+func BannerCampaignStart(builder *flatbuffers.Builder) {
+	builder.StartObject(2)
+}
+func BannerCampaignAddWeight(builder *flatbuffers.Builder, weight int32) {
+	builder.PrependInt32Slot(0, weight, 0)
+}
+func BannerCampaignAddMessages(builder *flatbuffers.Builder, messages flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(1, flatbuffers.UOffsetT(messages), 0)
+}
+func BannerCampaignStartMessagesVector(builder *flatbuffers.Builder, numElems int) flatbuffers.UOffsetT {
+	return builder.StartVector(4, numElems, 4)
+}
+func BannerCampaignEnd(builder *flatbuffers.Builder) flatbuffers.UOffsetT {
+	return builder.EndObject()
+}

pkg/fbs/scrabblefb/BannerInfo.go

@@ -0,0 +1,165 @@
+// Code generated by the FlatBuffers compiler. DO NOT EDIT.
+
+package scrabblefb
+
+import (
+	flatbuffers "github.com/google/flatbuffers/go"
+)
+
+type BannerInfo struct {
+	_tab flatbuffers.Table
+}
+
+func GetRootAsBannerInfo(buf []byte, offset flatbuffers.UOffsetT) *BannerInfo {
+	n := flatbuffers.GetUOffsetT(buf[offset:])
+	x := &BannerInfo{}
+	x.Init(buf, n+offset)
+	return x
+}
+
+func FinishBannerInfoBuffer(builder *flatbuffers.Builder, offset flatbuffers.UOffsetT) {
+	builder.Finish(offset)
+}
+
+func GetSizePrefixedRootAsBannerInfo(buf []byte, offset flatbuffers.UOffsetT) *BannerInfo {
+	n := flatbuffers.GetUOffsetT(buf[offset+flatbuffers.SizeUint32:])
+	x := &BannerInfo{}
+	x.Init(buf, n+offset+flatbuffers.SizeUint32)
+	return x
+}
+
+func FinishSizePrefixedBannerInfoBuffer(builder *flatbuffers.Builder, offset flatbuffers.UOffsetT) {
+	builder.FinishSizePrefixed(offset)
+}
+
+func (rcv *BannerInfo) Init(buf []byte, i flatbuffers.UOffsetT) {
+	rcv._tab.Bytes = buf
+	rcv._tab.Pos = i
+}
+
+func (rcv *BannerInfo) Table() flatbuffers.Table {
+	return rcv._tab
+}
+
+func (rcv *BannerInfo) Campaigns(obj *BannerCampaign, j int) bool {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(4))
+	if o != 0 {
+		x := rcv._tab.Vector(o)
+		x += flatbuffers.UOffsetT(j) * 4
+		x = rcv._tab.Indirect(x)
+		obj.Init(rcv._tab.Bytes, x)
+		return true
+	}
+	return false
+}
+
+func (rcv *BannerInfo) CampaignsLength() int {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(4))
+	if o != 0 {
+		return rcv._tab.VectorLen(o)
+	}
+	return 0
+}
+
+func (rcv *BannerInfo) HoldMs() int32 {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(6))
+	if o != 0 {
+		return rcv._tab.GetInt32(o + rcv._tab.Pos)
+	}
+	return 0
+}
+
+func (rcv *BannerInfo) MutateHoldMs(n int32) bool {
+	return rcv._tab.MutateInt32Slot(6, n)
+}
+
+func (rcv *BannerInfo) EdgePauseMs() int32 {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(8))
+	if o != 0 {
+		return rcv._tab.GetInt32(o + rcv._tab.Pos)
+	}
+	return 0
+}
+
+func (rcv *BannerInfo) MutateEdgePauseMs(n int32) bool {
+	return rcv._tab.MutateInt32Slot(8, n)
+}
+
+func (rcv *BannerInfo) ScrollPxPerSec() int32 {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(10))
+	if o != 0 {
+		return rcv._tab.GetInt32(o + rcv._tab.Pos)
+	}
+	return 0
+}
+
+func (rcv *BannerInfo) MutateScrollPxPerSec(n int32) bool {
+	return rcv._tab.MutateInt32Slot(10, n)
+}
+
+func (rcv *BannerInfo) FadeOutMs() int32 {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(12))
+	if o != 0 {
+		return rcv._tab.GetInt32(o + rcv._tab.Pos)
+	}
+	return 0
+}
+
+func (rcv *BannerInfo) MutateFadeOutMs(n int32) bool {
+	return rcv._tab.MutateInt32Slot(12, n)
+}
+
+func (rcv *BannerInfo) GapMs() int32 {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(14))
+	if o != 0 {
+		return rcv._tab.GetInt32(o + rcv._tab.Pos)
+	}
+	return 0
+}
+
+func (rcv *BannerInfo) MutateGapMs(n int32) bool {
+	return rcv._tab.MutateInt32Slot(14, n)
+}
+
+func (rcv *BannerInfo) FadeInMs() int32 {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(16))
+	if o != 0 {
+		return rcv._tab.GetInt32(o + rcv._tab.Pos)
+	}
+	return 0
+}
+
+func (rcv *BannerInfo) MutateFadeInMs(n int32) bool {
+	return rcv._tab.MutateInt32Slot(16, n)
+}
+
+func BannerInfoStart(builder *flatbuffers.Builder) {
+	builder.StartObject(7)
+}
+func BannerInfoAddCampaigns(builder *flatbuffers.Builder, campaigns flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(0, flatbuffers.UOffsetT(campaigns), 0)
+}
+func BannerInfoStartCampaignsVector(builder *flatbuffers.Builder, numElems int) flatbuffers.UOffsetT {
+	return builder.StartVector(4, numElems, 4)
+}
+func BannerInfoAddHoldMs(builder *flatbuffers.Builder, holdMs int32) {
+	builder.PrependInt32Slot(1, holdMs, 0)
+}
+func BannerInfoAddEdgePauseMs(builder *flatbuffers.Builder, edgePauseMs int32) {
+	builder.PrependInt32Slot(2, edgePauseMs, 0)
+}
+func BannerInfoAddScrollPxPerSec(builder *flatbuffers.Builder, scrollPxPerSec int32) {
+	builder.PrependInt32Slot(3, scrollPxPerSec, 0)
+}
+func BannerInfoAddFadeOutMs(builder *flatbuffers.Builder, fadeOutMs int32) {
+	builder.PrependInt32Slot(4, fadeOutMs, 0)
+}
+func BannerInfoAddGapMs(builder *flatbuffers.Builder, gapMs int32) {
+	builder.PrependInt32Slot(5, gapMs, 0)
+}
+func BannerInfoAddFadeInMs(builder *flatbuffers.Builder, fadeInMs int32) {
+	builder.PrependInt32Slot(6, fadeInMs, 0)
+}
+func BannerInfoEnd(builder *flatbuffers.Builder) flatbuffers.UOffsetT {
+	return builder.EndObject()
+}

pkg/fbs/scrabblefb/Profile.go

@@ -149,8 +149,21 @@ func (rcv *Profile) MutateNotificationsInAppOnly(n bool) bool {
 	return rcv._tab.MutateBoolSlot(24, n)
 }
 
+func (rcv *Profile) Banner(obj *BannerInfo) *BannerInfo {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(26))
+	if o != 0 {
+		x := rcv._tab.Indirect(o + rcv._tab.Pos)
+		if obj == nil {
+			obj = new(BannerInfo)
+		}
+		obj.Init(rcv._tab.Bytes, x)
+		return obj
+	}
+	return nil
+}
+
 func ProfileStart(builder *flatbuffers.Builder) {
-	builder.StartObject(11)
+	builder.StartObject(12)
 }
 func ProfileAddUserId(builder *flatbuffers.Builder, userId flatbuffers.UOffsetT) {
 	builder.PrependUOffsetTSlot(0, flatbuffers.UOffsetT(userId), 0)
@@ -185,6 +198,9 @@ func ProfileAddAwayEnd(builder *flatbuffers.Builder, awayEnd flatbuffers.UOffset
 func ProfileAddNotificationsInAppOnly(builder *flatbuffers.Builder, notificationsInAppOnly bool) {
 	builder.PrependBoolSlot(10, notificationsInAppOnly, true)
 }
+func ProfileAddBanner(builder *flatbuffers.Builder, banner flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(11, flatbuffers.UOffsetT(banner), 0)
+}
 func ProfileEnd(builder *flatbuffers.Builder) flatbuffers.UOffsetT {
 	return builder.EndObject()
 }