Stage 12: observability & performance (OTel/OTLP, domain metrics, guest GC)

- pkg/telemetry: shared OTel provider bootstrap (none/stdout/otlp + W3C
  propagators + Go runtime metrics); backend/internal/telemetry becomes a thin
  facade keeping its gin middleware.
- Telemetry parity: gateway and the Telegram connector gain telemetry runtimes
  and config (GATEWAY_/TELEGRAM_ SERVICE_NAME + OTEL_*); otelgrpc instruments the
  backend push server, the gateway's backend+connector clients and the connector
  server. Default exporter stays none (collector/dashboards are Stage 14).
- Operational metrics (variant attribute on game-scoped ones): game_replay_duration,
  game_move_validate_duration, games_started_total, games_abandoned_total,
  game_cache_active, chat_messages_total{kind}, gateway edge_request_duration.
  Wired via the SetMetrics setter pattern (default no-op meter).
- TODO-3: account.GuestReaper deletes guests with no game seat past
  BACKEND_GUEST_RETENTION (default 30d, swept every BACKEND_GUEST_REAP_INTERVAL).
- Tests: pkg/telemetry exporter selection; game/social/edge metric recording via
  a manual reader; config (otlp accepted, guest knobs); inttest guest reaper.
- Docs: PLAN.md re-scopes Stage 12 and adds Stage 13 (alphabet-on-wire) + Stage 14
  (CI/deploy) with the agreed dictionary-versioning resolution; ARCHITECTURE 11/13,
  TESTING, the three READMEs and FUNCTIONAL(+ru) updated.

docs/ARCHITECTURE.md

@@ -444,14 +444,27 @@ promotions) is future work and would deliver short markdown messages (text + lin
 ## 11. Observability
 
 - Structured logging with `go.uber.org/zap` (JSON). OpenTelemetry tracer and
-  meter providers are wired (Stage 1), env-gated by
-  `BACKEND_OTEL_{TRACES,METRICS}_EXPORTER` with a default of `none` (so no
-  collector is required locally or in CI); `stdout` is available for debugging
-  and the Postgres pool is instrumented with otelsql. OTLP export, a Prometheus
-  pull endpoint, and dashboards arrive with the first real workload.
+  meter providers are wired in **all three services** (backend, gateway, the
+  Telegram connector) through a shared `pkg/telemetry` bootstrap, env-gated per
+  service by `{BACKEND,GATEWAY,TELEGRAM}_OTEL_{TRACES,METRICS}_EXPORTER` with a
+  default of `none` (so no collector is required locally or in CI). `stdout` is
+  available for debugging; **`otlp`** (gRPC, endpoint from the standard
+  `OTEL_EXPORTER_OTLP_*` environment) exports to a collector. The Postgres pool is
+  instrumented with otelsql and `otelgrpc` traces the backend↔gateway push stream
+  and the gateway↔connector calls. The OTLP collector and Grafana dashboards are
+  stood up with the deploy (Stage 14).
 - Per-request server-side timing via gin middleware from day one (the access log
   carries method, route, status, latency and the active trace id). A
   client-measured RTT piggybacked on the next request is a later enhancement.
+- Domain/operational metrics (Stage 12), recorded through the meter and invisible
+  until an exporter is configured: histograms `game_replay_duration` (journal
+  rebuild on a cache miss) and `game_move_validate_duration`; counters
+  `games_started_total`, `games_abandoned_total` (a turn-timeout seat drop),
+  `chat_messages_total` (`kind` = message/nudge) and `robot_games_finished_total`;
+  an observable gauge `game_cache_active`; the gateway `edge_request_duration`
+  (the UI-perceived roundtrip, by `message_type`/`result`); and Go runtime/heap
+  metrics. Game-scoped metrics carry a `variant` attribute
+  (english/russian_scrabble/erudit).
 - Unauthenticated `GET /healthz` (liveness) and `GET /readyz` (readiness — the
   database answers a bounded ping and the session cache is warmed).
 - The backend serves a **second listener** — a gRPC server
@@ -486,15 +499,15 @@ a dedicated redeem sub-limit or a longer code is the hardening step if abuse app
 ## 13. Deployment (informational)
 
 Single public origin, path-routed: a mini-landing at the root, the **Telegram Mini
-App under `/telegram/`** (the gateway serves the static UI build; outside Telegram
-that path redirects to the root), the gateway public surface and the **admin console
+App under `/telegram/`** (the gateway serves the static UI build, wired in Stage 14;
+outside Telegram that path redirects to the root), the gateway public surface and the **admin console
 at `/_gm`** (backend-rendered, Basic-Auth at the gateway) share one host that
 terminates TLS. The **Telegram connector** runs as a separate
 container with **no public ingress** — it long-polls Telegram and egresses through a
 VPN sidecar, answering only internal gRPC. MVP runs one `gateway`, one `backend`, one
 Postgres, plus the connector. The connector's Docker/compose ships now
-(`platform/telegram/deploy`, mirroring `../15-puzzle`); the full multi-service deploy
-is Stage 12.
+(`platform/telegram/deploy`, mirroring `../15-puzzle`); the gateway's static UI serving
+and the full multi-service deploy land in Stage 14.
 
 ## 14. CI & branches
 

docs/FUNCTIONAL.md

@@ -29,7 +29,8 @@ session token; the backend resolves it to an internal `user_id`. A **Telegram Mi
 App** launch authenticates from the platform's signed `initData`, themes the UI to
 the Telegram colours, and — on first contact — seeds the new account's interface
 language from the Telegram client. Guests are session-only with restricted features
-(auto-match only; no friends, stats or history). While the app is open the client
+(auto-match only; no friends, stats or history); an abandoned guest that never
+joined a game and has been idle past the retention window is garbage-collected. While the app is open the client
 keeps a live stream and receives in-app updates in real time — the opponent's move,
 your turn, chat, nudges and a found match. When the app is **closed**, the chosen
 out-of-app events (your turn, nudge, a found match, an invitation or friend request)

docs/FUNCTIONAL_ru.md

@@ -30,7 +30,8 @@ session-токен; backend сопоставляет его с внутренн
 Mini App** авторизует по подписанным `initData` платформы, перекрашивает интерфейс
 в цвета Telegram и — при первом контакте — задаёт язык интерфейса нового аккаунта по
 языку Telegram-клиента. Гость — только сессия, с урезанными функциями (только
-авто-подбор; без друзей, статистики и истории). Пока приложение открыто, клиент
+авто-подбор; без друзей, статистики и истории); заброшенный гость, не вошедший ни
+в одну игру и простаивавший дольше окна удержания, удаляется сборщиком. Пока приложение открыто, клиент
 держит живой стрим и получает обновления в реальном времени — ход соперника, ваш ход,
 чат, nudge и найденный матч. Когда приложение **закрыто**, выбранные внеприложенческие
 события (ваш ход, nudge, найденный матч, приглашение или заявка в друзья) приходят

docs/TESTING.md

@@ -93,6 +93,16 @@ tests or touching CI.
   dictionary-change pipeline** (file → resolve with a disposition → pending change → mark
   applied), the admin **list/count** read queries, and the **/_gm console over HTTP**
   (pages render; a resolve POST needs a same-origin header).
+- **Observability & performance** *(Stage 12)* — `pkg/telemetry` unit-tests the exporter
+  selection (`none`/`stdout`/`otlp` build providers; OTLP constructs with no collector;
+  the nil-runtime fallback). The domain metrics are exercised through a manual
+  `sdkmetric` reader: `backend/internal/game` and `…/social` assert the counters and
+  histograms record with the right `variant`/`kind` attributes, and
+  `gateway/internal/connectsrv` asserts `edge_request_duration` by `message_type`/
+  `result`. Config tests cover the new telemetry env vars (backend/gateway/connector —
+  `otlp` now accepted, an unsupported exporter rejected) and the guest-reaper knobs.
+  Postgres-backed `inttest` drives the **guest reaper** end to end (an abandoned guest is
+  reaped; a too-young guest, a seated guest and a durable account are kept).
 
 ## Principles