Stage 15: dual Telegram bots & language-gated variants

Service-agnostic refinement of the owner's idea: the sign-in service returns a
set of supported game languages with the user identity, and the lobby gates the
New Game variant choice by it (en -> English; ru -> Russian + Эрудит).

- Connector hosts two bots in one container (one per service language, each its
  own token + game channel; the same telegram_id spans both). ValidateInitData
  tries each token and returns the validating bot's service_language +
  supported_languages. Per-language config (TELEGRAM_BOT_TOKEN_EN/_RU, channels).
- supported_languages rides the Session (fbs, session-scoped, not persisted); the
  UI offers only the matching variants on New Game — gating only the START of a
  new game (auto-match + friend invite), not accept/open/play; backend does not
  enforce.
- service_language persisted (accounts.service_language, migration 00010, written
  every login, last-login-wins) and routes the user-facing Notify push back
  through the right bot (push-target coalesces with preferred_language).
- Admin SendToUser/SendToGameChannel gain an operator-chosen language selector in
  the console (unrelated to ValidateInitData).
- Non-Telegram logins carry the gateway default set
  (GATEWAY_DEFAULT_SUPPORTED_LANGUAGES, all variants).

Wire (committed regen): ValidateInitDataResponse +service_language
+supported_languages; Session +supported_languages; SendToUser/SendToGameChannel
+language. Docs (ARCHITECTURE/FUNCTIONAL/_ru/READMEs) + PLAN updated; stage marked done.

backend/README.md

@@ -80,8 +80,12 @@ the gateway fronts it with Basic-Auth and a same-origin guard protects its POSTs
 `resolved_at`/`applied_in_version` + the `status` CHECK) feeding a dictionary-change
 pipeline, dictionary **hot-reload** from `BACKEND_DICT_DIR/<version>/`
 (`engine.OpenWithVersions` / `Registry.LoadAvailable`), and operator **broadcasts** via a
-backend Telegram-connector client (`internal/connector`, `BACKEND_CONNECTOR_ADDR`). The
-shared wire contracts live in the sibling [`../pkg`](../pkg) module.
+backend Telegram-connector client (`internal/connector`, `BACKEND_CONNECTOR_ADDR`) — each
+broadcast picks the delivering bot by an operator-chosen language. **Stage 15** adds
+migration `00010` (`accounts.service_language`): the language tag of the bot a Telegram
+user last signed in through, written on every login and returned by
+`/internal/push-target` (falling back to `preferred_language`) so out-of-app push routes
+to the right bot. The shared wire contracts live in the sibling [`../pkg`](../pkg) module.
 
 Stage 11 adds **account linking & merge** (`/api/v1/user/link/*`). `internal/link`
 orchestrates it: an email confirm-code or a gateway-validated Telegram identity is

backend/internal/account/account.go

@@ -56,6 +56,12 @@ type Account struct {
 	HintBalance         int
 	BlockChat           bool
 	BlockFriendRequests bool
+	// ServiceLanguage is the language tag (en/ru) of the bot the account last
+	// authenticated through (its last Telegram ValidateInitData); it routes the
+	// account's out-of-app push back through the right bot. Empty when the account
+	// has never signed in through a tagged bot. Distinct from PreferredLanguage (the
+	// interface language) and from a game's variant language.
+	ServiceLanguage string
 	// IsGuest marks an ephemeral guest account: a durable row with no identity,
 	// excluded from statistics, friends and history.
 	IsGuest bool
@@ -374,16 +380,41 @@ func (s *Store) SpendHint(ctx context.Context, id uuid.UUID) (bool, error) {
 	return n > 0, nil
 }
 
+// SetServiceLanguage records the service language (en/ru) of the bot a Telegram
+// user authenticated through. It is called on every Telegram login — new and
+// existing accounts — so it tracks the bot the user last came through (last-login-
+// wins), and the out-of-app push routes by it. It is a no-op for an empty language
+// (a non-Telegram login carries none) and does not bump updated_at (an infra
+// routing field, not a user profile edit).
+func (s *Store) SetServiceLanguage(ctx context.Context, id uuid.UUID, language string) error {
+	if language == "" {
+		return nil
+	}
+	stmt := table.Accounts.
+		UPDATE(table.Accounts.ServiceLanguage).
+		SET(postgres.String(language)).
+		WHERE(table.Accounts.AccountID.EQ(postgres.UUID(id)))
+	if _, err := stmt.ExecContext(ctx, s.db); err != nil {
+		return fmt.Errorf("account: set service language %s: %w", id, err)
+	}
+	return nil
+}
+
 // modelToAccount projects a generated model row into the public Account struct.
 func modelToAccount(row model.Accounts) Account {
 	var mergedInto uuid.UUID
 	if row.MergedInto != nil {
 		mergedInto = *row.MergedInto
 	}
+	var serviceLanguage string
+	if row.ServiceLanguage != nil {
+		serviceLanguage = *row.ServiceLanguage
+	}
 	return Account{
 		ID:                     row.AccountID,
 		DisplayName:            row.DisplayName,
 		PreferredLanguage:      row.PreferredLanguage,
+		ServiceLanguage:        serviceLanguage,
 		TimeZone:               row.TimeZone,
 		AwayStart:              row.AwayStart,
 		AwayEnd:                row.AwayEnd,

backend/internal/adminconsole/templates/pages/broadcast.gohtml

@@ -5,6 +5,7 @@
 {{if .ConnectorEnabled}}
 <form class="form col" method="post" action="/_gm/broadcast">
 <label>Message <textarea name="text" required></textarea></label>
+<label>Bot language <select name="language"><option value="en">en</option><option value="ru">ru</option></select></label>
 <div><button type="submit">Post to channel</button></div>
 </form>
 {{else}}<p class="note">connector not configured (set BACKEND_CONNECTOR_ADDR)</p>{{end}}

backend/internal/adminconsole/templates/pages/user_detail.gohtml

@@ -43,6 +43,7 @@
 {{if .ConnectorEnabled}}
 <form class="form col" method="post" action="/_gm/users/{{.ID}}/message">
 <label>Message <textarea name="text" required></textarea></label>
+<label>Bot language <select name="language"><option value="en">en</option><option value="ru">ru</option></select></label>
 <div><button type="submit">Send to user</button></div>
 </form>
 {{else}}<p class="note">connector not configured (set BACKEND_CONNECTOR_ADDR)</p>{{end}}

backend/internal/connector/client.go

@@ -1,8 +1,9 @@
 // Package connector is the backend's gRPC client for the Telegram platform
 // connector side-service. The admin console uses it to send operator broadcasts:
-// a direct message to one user, or a post to the connector's configured game
-// channel. The connector lives on the trusted internal network, so the
-// connection uses insecure (plaintext) transport credentials
+// a direct message to one user, or a post to a game channel. Each broadcast
+// selects the delivering bot by language (an operator choice, since the connector
+// hosts one bot per service language). The connector lives on the trusted internal
+// network, so the connection uses insecure (plaintext) transport credentials
 // (docs/ARCHITECTURE.md §12). It mirrors gateway/internal/connector, narrowed to
 // the two broadcast methods the admin surface needs.
 package connector
@@ -36,21 +37,22 @@ func New(addr string) (*Client, error) {
 func (c *Client) Close() error { return c.conn.Close() }
 
 // SendToUser sends an operator text message to one user, addressed by their
-// platform external_id. delivered reports whether the connector actually sent it
-// (false when the user has not started the bot).
-func (c *Client) SendToUser(ctx context.Context, externalID, text string) (bool, error) {
-	resp, err := c.c.SendToUser(ctx, &telegramv1.SendToUserRequest{ExternalId: externalID, Text: text})
+// platform external_id, through the bot for the given language. delivered reports
+// whether the connector actually sent it (false when the user has not started that
+// bot).
+func (c *Client) SendToUser(ctx context.Context, externalID, text, language string) (bool, error) {
+	resp, err := c.c.SendToUser(ctx, &telegramv1.SendToUserRequest{ExternalId: externalID, Text: text, Language: language})
 	if err != nil {
 		return false, err
 	}
 	return resp.GetDelivered(), nil
 }
 
-// SendToGameChannel posts an operator text message to the connector's configured
-// game channel. delivered reports whether the connector sent it (false when no
-// channel is configured).
-func (c *Client) SendToGameChannel(ctx context.Context, text string) (bool, error) {
-	resp, err := c.c.SendToGameChannel(ctx, &telegramv1.SendToGameChannelRequest{Text: text})
+// SendToGameChannel posts an operator text message to the game channel of the bot
+// for the given language. delivered reports whether the connector sent it (false
+// when that bot has no channel configured).
+func (c *Client) SendToGameChannel(ctx context.Context, text, language string) (bool, error) {
+	resp, err := c.c.SendToGameChannel(ctx, &telegramv1.SendToGameChannelRequest{Text: text, Language: language})
 	if err != nil {
 		return false, err
 	}

backend/internal/inttest/account_test.go

@@ -155,6 +155,46 @@ func TestProvisionTelegramUnknownLanguageDefaults(t *testing.T) {
 	}
 }
 
+// TestServiceLanguageRoundTrip checks SetServiceLanguage persists the push-routing
+// language (the bot a Telegram user last signed in through): a fresh account has
+// none, a set value reads back, a later login overwrites it (last-login-wins), and
+// an empty value is a no-op. The push-target route coalesces it with the preferred
+// language.
+func TestServiceLanguageRoundTrip(t *testing.T) {
+	ctx := context.Background()
+	store := account.NewStore(testDB)
+	acc, err := store.ProvisionTelegram(ctx, "tg-"+uuid.NewString(), "en", "", "Player")
+	if err != nil {
+		t.Fatalf("provision telegram: %v", err)
+	}
+	if acc.ServiceLanguage != "" {
+		t.Errorf("fresh ServiceLanguage = %q, want empty", acc.ServiceLanguage)
+	}
+
+	if err := store.SetServiceLanguage(ctx, acc.ID, "ru"); err != nil {
+		t.Fatalf("set service language: %v", err)
+	}
+	if got, err := store.GetByID(ctx, acc.ID); err != nil {
+		t.Fatalf("get by id: %v", err)
+	} else if got.ServiceLanguage != "ru" {
+		t.Errorf("ServiceLanguage = %q, want ru", got.ServiceLanguage)
+	}
+
+	// A later login through the other bot updates it; a subsequent empty value
+	// (a non-Telegram login) leaves it unchanged.
+	if err := store.SetServiceLanguage(ctx, acc.ID, "en"); err != nil {
+		t.Fatalf("update service language: %v", err)
+	}
+	if err := store.SetServiceLanguage(ctx, acc.ID, ""); err != nil {
+		t.Fatalf("noop service language: %v", err)
+	}
+	if got, err := store.GetByID(ctx, acc.ID); err != nil {
+		t.Fatalf("get by id: %v", err)
+	} else if got.ServiceLanguage != "en" {
+		t.Errorf("ServiceLanguage after update+noop = %q, want en", got.ServiceLanguage)
+	}
+}
+
 // TestIdentityExternalID covers the reverse identity lookup the push-target route
 // uses: it returns the external_id for the matching kind and ErrNotFound otherwise,
 // including for a guest that carries no identity.

backend/internal/postgres/jet/backend/model/accounts.go

@@ -29,4 +29,5 @@ type Accounts struct {
 	PaidAccount            bool
 	MergedInto             *uuid.UUID
 	MergedAt               *time.Time
+	ServiceLanguage        *string
 }

backend/internal/postgres/jet/backend/table/accounts.go

@@ -33,6 +33,7 @@ type accountsTable struct {
 	PaidAccount            postgres.ColumnBool
 	MergedInto             postgres.ColumnString
 	MergedAt               postgres.ColumnTimestampz
+	ServiceLanguage        postgres.ColumnString
 
 	AllColumns     postgres.ColumnList
 	MutableColumns postgres.ColumnList
@@ -90,8 +91,9 @@ func newAccountsTableImpl(schemaName, tableName, alias string) accountsTable {
 		PaidAccountColumn            = postgres.BoolColumn("paid_account")
 		MergedIntoColumn             = postgres.StringColumn("merged_into")
 		MergedAtColumn               = postgres.TimestampzColumn("merged_at")
-		allColumns                   = postgres.ColumnList{AccountIDColumn, DisplayNameColumn, PreferredLanguageColumn, TimeZoneColumn, BlockChatColumn, BlockFriendRequestsColumn, CreatedAtColumn, UpdatedAtColumn, AwayStartColumn, AwayEndColumn, HintBalanceColumn, IsGuestColumn, NotificationsInAppOnlyColumn, PaidAccountColumn, MergedIntoColumn, MergedAtColumn}
-		mutableColumns               = postgres.ColumnList{DisplayNameColumn, PreferredLanguageColumn, TimeZoneColumn, BlockChatColumn, BlockFriendRequestsColumn, CreatedAtColumn, UpdatedAtColumn, AwayStartColumn, AwayEndColumn, HintBalanceColumn, IsGuestColumn, NotificationsInAppOnlyColumn, PaidAccountColumn, MergedIntoColumn, MergedAtColumn}
+		ServiceLanguageColumn        = postgres.StringColumn("service_language")
+		allColumns                   = postgres.ColumnList{AccountIDColumn, DisplayNameColumn, PreferredLanguageColumn, TimeZoneColumn, BlockChatColumn, BlockFriendRequestsColumn, CreatedAtColumn, UpdatedAtColumn, AwayStartColumn, AwayEndColumn, HintBalanceColumn, IsGuestColumn, NotificationsInAppOnlyColumn, PaidAccountColumn, MergedIntoColumn, MergedAtColumn, ServiceLanguageColumn}
+		mutableColumns               = postgres.ColumnList{DisplayNameColumn, PreferredLanguageColumn, TimeZoneColumn, BlockChatColumn, BlockFriendRequestsColumn, CreatedAtColumn, UpdatedAtColumn, AwayStartColumn, AwayEndColumn, HintBalanceColumn, IsGuestColumn, NotificationsInAppOnlyColumn, PaidAccountColumn, MergedIntoColumn, MergedAtColumn, ServiceLanguageColumn}
 		defaultColumns               = postgres.ColumnList{DisplayNameColumn, PreferredLanguageColumn, TimeZoneColumn, BlockChatColumn, BlockFriendRequestsColumn, CreatedAtColumn, UpdatedAtColumn, AwayStartColumn, AwayEndColumn, HintBalanceColumn, IsGuestColumn, NotificationsInAppOnlyColumn, PaidAccountColumn}
 	)
 
@@ -115,6 +117,7 @@ func newAccountsTableImpl(schemaName, tableName, alias string) accountsTable {
 		PaidAccount:            PaidAccountColumn,
 		MergedInto:             MergedIntoColumn,
 		MergedAt:               MergedAtColumn,
+		ServiceLanguage:        ServiceLanguageColumn,
 
 		AllColumns:     allColumns,
 		MutableColumns: mutableColumns,

backend/internal/postgres/migrations/00010_service_language.sql

@@ -0,0 +1,21 @@
+-- +goose Up
+-- Stage 15 dual Telegram bots: service_language records the language tag of the bot
+-- a Telegram user last authenticated through (their last ValidateInitData). It is
+-- updated on every Telegram login — new and existing accounts — and routes the
+-- user's out-of-app push back through the right bot. It is distinct from
+-- preferred_language (the interface language) and from a game's variant language.
+-- Nullable: an account that has never signed in through a tagged bot (legacy,
+-- email-only or guest) has no value, and push routing falls back to
+-- preferred_language. Adds a column, so the generated jet code is regenerated
+-- (cmd/jetgen).
+SET search_path = backend, pg_catalog;
+
+ALTER TABLE accounts
+    ADD COLUMN service_language text
+        CHECK (service_language IN ('en', 'ru'));
+
+-- +goose Down
+SET search_path = backend, pg_catalog;
+
+ALTER TABLE accounts
+    DROP COLUMN service_language;

backend/internal/server/handlers_admin_console.go

@@ -146,6 +146,7 @@ func (s *Server) consoleUserMessage(c *gin.Context) {
 	}
 	back := "/_gm/users/" + id.String()
 	text := trimForm(c, "text")
+	language := trimForm(c, "language")
 	switch {
 	case text == "":
 		s.renderConsoleMessage(c, "Nothing sent", "the message was empty", back)
@@ -157,14 +158,14 @@ func (s *Server) consoleUserMessage(c *gin.Context) {
 			s.renderConsoleMessage(c, "No Telegram", "this account has no Telegram identity", back)
 			return
 		}
-		delivered, err := s.connector.SendToUser(ctx, ext, text)
+		delivered, err := s.connector.SendToUser(ctx, ext, text, language)
 		if err != nil {
 			s.consoleError(c, err)
 			return
 		}
 		body := "message delivered"
 		if !delivered {
-			body = "not delivered (the user may not have started the bot)"
+			body = "not delivered (the user may not have started that bot)"
 		}
 		s.renderConsoleMessage(c, "Sent", body, back)
 	}
@@ -340,20 +341,21 @@ func (s *Server) consoleBroadcast(c *gin.Context) {
 // consolePostBroadcast posts an operator message to the connector's game channel.
 func (s *Server) consolePostBroadcast(c *gin.Context) {
 	text := trimForm(c, "text")
+	language := trimForm(c, "language")
 	switch {
 	case text == "":
 		s.renderConsoleMessage(c, "Nothing sent", "the message was empty", "/_gm/broadcast")
 	case s.connector == nil:
 		s.renderConsoleMessage(c, "Not configured", "the connector is not configured (set BACKEND_CONNECTOR_ADDR)", "/_gm/broadcast")
 	default:
-		delivered, err := s.connector.SendToGameChannel(c.Request.Context(), text)
+		delivered, err := s.connector.SendToGameChannel(c.Request.Context(), text, language)
 		if err != nil {
 			s.consoleError(c, err)
 			return
 		}
 		body := "posted to the game channel"
 		if !delivered {
-			body = "not delivered (no game channel configured on the connector)"
+			body = "not delivered (that bot has no game channel configured)"
 		}
 		s.renderConsoleMessage(c, "Broadcast", body, "/_gm/broadcast")
 	}

backend/internal/server/handlers_auth.go

@@ -19,16 +19,20 @@ import (
 // telegramAuthRequest carries the identity the connector extracted from a
 // validated initData payload. Username, FirstName and LanguageCode seed a
 // brand-new account's display name and language (first contact only).
+// ServiceLanguage is the validating bot's language tag (en/ru); it is recorded on
+// every login (the bot the user last came through) and routes their out-of-app push.
 type telegramAuthRequest struct {
-	ExternalID   string `json:"external_id"`
-	Username     string `json:"username"`
-	FirstName    string `json:"first_name"`
-	LanguageCode string `json:"language_code"`
+	ExternalID      string `json:"external_id"`
+	Username        string `json:"username"`
+	FirstName       string `json:"first_name"`
+	LanguageCode    string `json:"language_code"`
+	ServiceLanguage string `json:"service_language"`
 }
 
 // handleTelegramAuth provisions (or finds) the account bound to a Telegram
 // identity and mints a session for it, seeding a new account's display name and
-// language from the supplied Telegram fields.
+// language from the supplied Telegram fields and recording the validating bot's
+// service language (updated every login) so out-of-app push routes to that bot.
 func (s *Server) handleTelegramAuth(c *gin.Context) {
 	var req telegramAuthRequest
 	if err := c.ShouldBindJSON(&req); err != nil || req.ExternalID == "" {
@@ -40,6 +44,10 @@ func (s *Server) handleTelegramAuth(c *gin.Context) {
 		s.abortErr(c, err)
 		return
 	}
+	if err := s.accounts.SetServiceLanguage(c.Request.Context(), acc.ID, req.ServiceLanguage); err != nil {
+		s.abortErr(c, err)
+		return
+	}
 	s.mintSession(c, acc)
 }
 
@@ -50,8 +58,10 @@ type pushTargetRequest struct {
 
 // pushTargetResponse carries what the gateway needs to route an out-of-app push:
 // the recipient's Telegram external_id (empty when they have no Telegram
-// identity, e.g. a guest or email-only account), the preferred language for the
-// message template, and whether they confined notifications to the in-app stream.
+// identity, e.g. a guest or email-only account), the language that both selects the
+// delivering bot and renders the message (the account's service language, the bot
+// it last signed in through, falling back to its preferred language), and whether
+// they confined notifications to the in-app stream.
 type pushTargetResponse struct {
 	ExternalID             string `json:"external_id"`
 	Language               string `json:"language"`
@@ -83,9 +93,15 @@ func (s *Server) handlePushTarget(c *gin.Context) {
 		s.abortErr(c, err)
 		return
 	}
+	// Route by the bot the user last signed in through; fall back to the interface
+	// language for an account that has never come through a tagged bot.
+	language := acc.ServiceLanguage
+	if language == "" {
+		language = acc.PreferredLanguage
+	}
 	c.JSON(http.StatusOK, pushTargetResponse{
 		ExternalID:             ext,
-		Language:               acc.PreferredLanguage,
+		Language:               language,
 		NotificationsInAppOnly: acc.NotificationsInAppOnly,
 	})
 }