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.

ui/src/gen/fbs/scrabblefb/session.ts

@@ -46,8 +46,20 @@ displayName(optionalEncoding?:any):string|Uint8Array|null {
   return offset ? this.bb!.__string(this.bb_pos + offset, optionalEncoding) : null;
 }
 
+supportedLanguages(index: number):string
+supportedLanguages(index: number,optionalEncoding:flatbuffers.Encoding):string|Uint8Array
+supportedLanguages(index: number,optionalEncoding?:any):string|Uint8Array|null {
+  const offset = this.bb!.__offset(this.bb_pos, 12);
+  return offset ? this.bb!.__string(this.bb!.__vector(this.bb_pos + offset) + index * 4, optionalEncoding) : null;
+}
+
+supportedLanguagesLength():number {
+  const offset = this.bb!.__offset(this.bb_pos, 12);
+  return offset ? this.bb!.__vector_len(this.bb_pos + offset) : 0;
+}
+
 static startSession(builder:flatbuffers.Builder) {
-  builder.startObject(4);
+  builder.startObject(5);
 }
 
 static addToken(builder:flatbuffers.Builder, tokenOffset:flatbuffers.Offset) {
@@ -66,17 +78,34 @@ static addDisplayName(builder:flatbuffers.Builder, displayNameOffset:flatbuffers
   builder.addFieldOffset(3, displayNameOffset, 0);
 }
 
+static addSupportedLanguages(builder:flatbuffers.Builder, supportedLanguagesOffset:flatbuffers.Offset) {
+  builder.addFieldOffset(4, supportedLanguagesOffset, 0);
+}
+
+static createSupportedLanguagesVector(builder:flatbuffers.Builder, data:flatbuffers.Offset[]):flatbuffers.Offset {
+  builder.startVector(4, data.length, 4);
+  for (let i = data.length - 1; i >= 0; i--) {
+    builder.addOffset(data[i]!);
+  }
+  return builder.endVector();
+}
+
+static startSupportedLanguagesVector(builder:flatbuffers.Builder, numElems:number) {
+  builder.startVector(4, numElems, 4);
+}
+
 static endSession(builder:flatbuffers.Builder):flatbuffers.Offset {
   const offset = builder.endObject();
   return offset;
 }
 
-static createSession(builder:flatbuffers.Builder, tokenOffset:flatbuffers.Offset, userIdOffset:flatbuffers.Offset, isGuest:boolean, displayNameOffset:flatbuffers.Offset):flatbuffers.Offset {
+static createSession(builder:flatbuffers.Builder, tokenOffset:flatbuffers.Offset, userIdOffset:flatbuffers.Offset, isGuest:boolean, displayNameOffset:flatbuffers.Offset, supportedLanguagesOffset:flatbuffers.Offset):flatbuffers.Offset {
   Session.startSession(builder);
   Session.addToken(builder, tokenOffset);
   Session.addUserId(builder, userIdOffset);
   Session.addIsGuest(builder, isGuest);
   Session.addDisplayName(builder, displayNameOffset);
+  Session.addSupportedLanguages(builder, supportedLanguagesOffset);
   return Session.endSession(builder);
 }
 }

ui/src/lib/codec.test.ts

@@ -47,17 +47,20 @@ describe('codec', () => {
     const token = b.createString('tok');
     const uid = b.createString('u1');
     const name = b.createString('Me');
+    const langs = fb.Session.createSupportedLanguagesVector(b, [b.createString('en'), b.createString('ru')]);
     fb.Session.startSession(b);
     fb.Session.addToken(b, token);
     fb.Session.addUserId(b, uid);
     fb.Session.addIsGuest(b, true);
     fb.Session.addDisplayName(b, name);
+    fb.Session.addSupportedLanguages(b, langs);
     b.finish(fb.Session.endSession(b));
     expect(decodeSession(b.asUint8Array())).toEqual({
       token: 'tok',
       userId: 'u1',
       isGuest: true,
       displayName: 'Me',
+      supportedLanguages: ['en', 'ru'],
     });
   });
 
@@ -181,7 +184,7 @@ describe('codec', () => {
     b.finish(fb.LinkResult.endLinkResult(b));
     const r = decodeLinkResult(b.asUint8Array());
     expect(r.status).toBe('merged');
-    expect(r.session).toEqual({ token: 'tok-9', userId: 'a-1', isGuest: false, displayName: 'Kaya' });
+    expect(r.session).toEqual({ token: 'tok-9', userId: 'a-1', isGuest: false, displayName: 'Kaya', supportedLanguages: [] });
   });
 
   it('decodes an Invitation with inviter and invitees', () => {

ui/src/lib/codec.ts

@@ -274,9 +274,22 @@ function decodeChatMsg(m: fb.ChatMessage): ChatMessage {
   };
 }
 
+// sessionFromTable projects a FlatBuffers Session table (a root or a nested one) to
+// the Session model, including the supported-languages set the UI gates variants by.
+function sessionFromTable(t: fb.Session): Session {
+  const supportedLanguages: string[] = [];
+  for (let i = 0; i < t.supportedLanguagesLength(); i++) supportedLanguages.push(s(t.supportedLanguages(i)));
+  return {
+    token: s(t.token()),
+    userId: s(t.userId()),
+    isGuest: t.isGuest(),
+    displayName: s(t.displayName()),
+    supportedLanguages,
+  };
+}
+
 export function decodeSession(buf: Uint8Array): Session {
-  const t = fb.Session.getRootAsSession(new ByteBuffer(buf));
-  return { token: s(t.token()), userId: s(t.userId()), isGuest: t.isGuest(), displayName: s(t.displayName()) };
+  return sessionFromTable(fb.Session.getRootAsSession(new ByteBuffer(buf)));
 }
 
 export function decodeProfile(buf: Uint8Array): Profile {
@@ -525,9 +538,7 @@ export function decodeLinkResult(buf: Uint8Array): LinkResult {
     secondaryDisplayName: s(r.secondaryDisplayName()),
     secondaryGames: r.secondaryGames(),
     secondaryFriends: r.secondaryFriends(),
-    session: sess
-      ? { token: s(sess.token()), userId: s(sess.userId()), isGuest: sess.isGuest(), displayName: s(sess.displayName()) }
-      : null,
+    session: sess ? sessionFromTable(sess) : null,
   };
 }
 

ui/src/lib/mock/data.ts

@@ -23,6 +23,8 @@ export const SESSION: Session = {
   userId: ME,
   isGuest: true,
   displayName: 'You',
+  // Both languages by default, so the mock-driven UI offers every variant.
+  supportedLanguages: ['en', 'ru'],
 };
 
 export const PROFILE: Profile = {

ui/src/lib/model.ts

@@ -186,6 +186,11 @@ export interface Session {
   userId: string;
   isGuest: boolean;
   displayName: string;
+  // supportedLanguages is the set of game languages the service the user signed in
+  // through offers (subset of {en, ru}, at least one). New Game offers only the
+  // variants these languages support (en -> English; ru -> Russian + Эрудит). Empty
+  // means ungated (all variants).
+  supportedLanguages: string[];
 }
 
 // LinkResult is the outcome of an account link/merge step (Stage 11). status is

ui/src/lib/variants.test.ts

@@ -0,0 +1,22 @@
+import { describe, it, expect } from 'vitest';
+
+import { ALL_VARIANTS, availableVariants } from './variants';
+
+describe('availableVariants', () => {
+  it('is ungated (all variants) for an empty or absent set', () => {
+    expect(availableVariants([])).toEqual(ALL_VARIANTS);
+    expect(availableVariants(undefined)).toEqual(ALL_VARIANTS);
+  });
+
+  it('offers only English for an en-only service', () => {
+    expect(availableVariants(['en']).map((v) => v.id)).toEqual(['english']);
+  });
+
+  it('offers Russian and Эрудит for a ru-only service', () => {
+    expect(availableVariants(['ru']).map((v) => v.id)).toEqual(['russian', 'erudit']);
+  });
+
+  it('offers every variant for a bilingual service', () => {
+    expect(availableVariants(['en', 'ru']).map((v) => v.id)).toEqual(['english', 'russian', 'erudit']);
+  });
+});

ui/src/lib/variants.ts

@@ -0,0 +1,32 @@
+// Game variants offered on New Game, and the Stage 15 gating of that choice by the
+// languages the sign-in service supports. Kept out of the .svelte screen so the
+// gating is unit-testable (the project's node-env Vitest layer).
+
+import type { MessageKey } from './i18n/index.svelte';
+import type { Variant } from './model';
+
+// VariantOption is a selectable game variant with its i18n label key.
+export interface VariantOption {
+  id: Variant;
+  label: MessageKey;
+}
+
+// ALL_VARIANTS lists every variant in display order.
+export const ALL_VARIANTS: VariantOption[] = [
+  { id: 'english', label: 'new.english' },
+  { id: 'russian', label: 'new.russian' },
+  { id: 'erudit', label: 'new.erudit' },
+];
+
+// VARIANT_LANGUAGE maps each variant to its game language. en -> English;
+// ru -> Russian + Эрудит.
+export const VARIANT_LANGUAGE: Record<Variant, 'en' | 'ru'> = { english: 'en', russian: 'ru', erudit: 'ru' };
+
+// availableVariants gates ALL_VARIANTS by the session's supported languages. An empty
+// or absent set is ungated (a web/legacy session without a declared set), returning
+// every variant.
+export function availableVariants(supportedLanguages: string[] | undefined): VariantOption[] {
+  const langs = supportedLanguages ?? [];
+  if (langs.length === 0) return ALL_VARIANTS;
+  return ALL_VARIANTS.filter((v) => langs.includes(VARIANT_LANGUAGE[v.id]));
+}

ui/src/screens/NewGame.svelte

@@ -6,12 +6,11 @@
   import { navigate } from '../lib/router.svelte';
   import { t, type MessageKey } from '../lib/i18n/index.svelte';
   import type { AccountRef, Variant } from '../lib/model';
+  import { availableVariants } from '../lib/variants';
 
-  const variants: { id: Variant; label: MessageKey }[] = [
-    { id: 'english', label: 'new.english' },
-    { id: 'russian', label: 'new.russian' },
-    { id: 'erudit', label: 'new.erudit' },
-  ];
+  // The offered variants are gated by the languages the sign-in service supports
+  // (Stage 15); the auto-match list and the friend-invite picker both use this.
+  const variants = $derived(availableVariants(app.session?.supportedLanguages));
   const timeouts = [
     { secs: 300, key: 'time.minutes' as MessageKey, n: 5 },
     { secs: 1800, key: 'time.minutes' as MessageKey, n: 30 },