Stage 1: backend foundation (Postgres, sessions, accounts, OTel)

- internal/postgres: pgx-over-database/sql pool (otelsql), embedded goose
  migrations into schema 'backend', committed go-jet code + cmd/jetgen tool.
- internal/account: durable accounts + unified telegram/email identities
  (UUIDv7 keys), find-or-create provisioning with unique-conflict handling.
- internal/session: opaque 256-bit tokens stored as a SHA-256 hash, revoke-only
  (no TTL); write-through cache gating /readyz; store + service.
- internal/telemetry: OTel tracer/meter providers (none/stdout) + request-timing
  middleware; internal/config gains Postgres + OTel env loading.
- internal/server: /api/v1 {public,user,internal,admin} skeleton + X-User-ID
  middleware; /readyz checks DB ping + cache; main wires
  telemetry -> db+migrate -> warm cache -> server.
- Tests: unit + integration (build tag 'integration', testcontainers
  postgres:17) for migrations, accounts, sessions, readyz; new integration.yaml.
- Docs: ARCHITECTURE, TESTING, PLAN refinements, root + backend READMEs.

Session/account REST handlers deferred to Stage 6 (gateway); OTLP + dashboards
to Stage 11.

backend/internal/telemetry/telemetry.go

@@ -0,0 +1,204 @@
+// Package telemetry owns the OpenTelemetry runtime for the backend process.
+//
+// New constructs the configured tracer and meter providers, registers them as
+// the OpenTelemetry globals, and exposes Shutdown for orderly exit. The MVP
+// supports the `none` and `stdout` exporters; OTLP export and dashboards arrive
+// in a later stage. The per-request timing middleware lives in middleware.go and
+// uses the registered global tracer, so requests are timed and logged even when
+// the exporter is `none`.
+package telemetry
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/exporters/stdout/stdoutmetric"
+	"go.opentelemetry.io/otel/exporters/stdout/stdouttrace"
+	"go.opentelemetry.io/otel/metric"
+	"go.opentelemetry.io/otel/propagation"
+	sdkmetric "go.opentelemetry.io/otel/sdk/metric"
+	"go.opentelemetry.io/otel/sdk/resource"
+	sdktrace "go.opentelemetry.io/otel/sdk/trace"
+	"go.opentelemetry.io/otel/trace"
+	"go.uber.org/zap"
+)
+
+// Exporter selectors supported by the backend.
+const (
+	ExporterNone   = "none"
+	ExporterStdout = "stdout"
+)
+
+// DefaultServiceName labels traces and metrics when BACKEND_SERVICE_NAME is
+// unset.
+const DefaultServiceName = "scrabble-backend"
+
+// Config selects the telemetry providers' service name and exporters.
+type Config struct {
+	// ServiceName is reported as the OpenTelemetry service.name resource.
+	ServiceName string
+	// TracesExporter is one of ExporterNone or ExporterStdout.
+	TracesExporter string
+	// MetricsExporter is one of ExporterNone or ExporterStdout.
+	MetricsExporter string
+}
+
+// DefaultConfig returns the MVP telemetry configuration: named service, no
+// exporters (so no collector is required locally or in CI).
+func DefaultConfig() Config {
+	return Config{
+		ServiceName:     DefaultServiceName,
+		TracesExporter:  ExporterNone,
+		MetricsExporter: ExporterNone,
+	}
+}
+
+// Validate reports whether the configuration selects supported exporters.
+func (c Config) Validate() error {
+	if c.ServiceName == "" {
+		return errors.New("telemetry: ServiceName must not be empty")
+	}
+	if err := validateExporter("traces", c.TracesExporter); err != nil {
+		return err
+	}
+	return validateExporter("metrics", c.MetricsExporter)
+}
+
+func validateExporter(kind, value string) error {
+	switch value {
+	case ExporterNone, ExporterStdout:
+		return nil
+	default:
+		return fmt.Errorf("telemetry: unsupported %s exporter %q", kind, value)
+	}
+}
+
+// Runtime owns the shared OpenTelemetry providers.
+type Runtime struct {
+	tracerProvider *sdktrace.TracerProvider
+	meterProvider  *sdkmetric.MeterProvider
+}
+
+// New constructs the telemetry runtime, registers the global providers and the
+// W3C trace-context/baggage propagators, and returns the Runtime. Callers must
+// invoke Runtime.Shutdown during process exit.
+func New(ctx context.Context, cfg Config) (*Runtime, error) {
+	if err := cfg.Validate(); err != nil {
+		return nil, err
+	}
+
+	res, err := resource.New(ctx, resource.WithAttributes(
+		attribute.String("service.name", cfg.ServiceName),
+	))
+	if err != nil {
+		return nil, fmt.Errorf("telemetry: build resource: %w", err)
+	}
+
+	tracerProvider, err := newTracerProvider(cfg, res)
+	if err != nil {
+		return nil, fmt.Errorf("telemetry: build tracer provider: %w", err)
+	}
+	meterProvider, err := newMeterProvider(cfg, res)
+	if err != nil {
+		_ = tracerProvider.Shutdown(ctx)
+		return nil, fmt.Errorf("telemetry: build meter provider: %w", err)
+	}
+
+	otel.SetTracerProvider(tracerProvider)
+	otel.SetMeterProvider(meterProvider)
+	otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(
+		propagation.TraceContext{},
+		propagation.Baggage{},
+	))
+
+	return &Runtime{tracerProvider: tracerProvider, meterProvider: meterProvider}, nil
+}
+
+// TracerProvider returns the runtime tracer provider, or the global one when r
+// is not initialised.
+func (r *Runtime) TracerProvider() trace.TracerProvider {
+	if r == nil || r.tracerProvider == nil {
+		return otel.GetTracerProvider()
+	}
+	return r.tracerProvider
+}
+
+// MeterProvider returns the runtime meter provider, or the global one when r is
+// not initialised.
+func (r *Runtime) MeterProvider() metric.MeterProvider {
+	if r == nil || r.meterProvider == nil {
+		return otel.GetMeterProvider()
+	}
+	return r.meterProvider
+}
+
+// Shutdown flushes both providers within ctx.
+func (r *Runtime) Shutdown(ctx context.Context) error {
+	if r == nil {
+		return nil
+	}
+	var err error
+	if r.meterProvider != nil {
+		err = errors.Join(err, r.meterProvider.Shutdown(ctx))
+	}
+	if r.tracerProvider != nil {
+		err = errors.Join(err, r.tracerProvider.Shutdown(ctx))
+	}
+	return err
+}
+
+// TraceFieldsFromContext returns zap fields identifying the active span, or nil
+// when ctx carries no valid span context. Collocated here so callers do not
+// import the OpenTelemetry API directly.
+func TraceFieldsFromContext(ctx context.Context) []zap.Field {
+	if ctx == nil {
+		return nil
+	}
+	sc := trace.SpanContextFromContext(ctx)
+	if !sc.IsValid() {
+		return nil
+	}
+	return []zap.Field{
+		zap.String("otel_trace_id", sc.TraceID().String()),
+		zap.String("otel_span_id", sc.SpanID().String()),
+	}
+}
+
+func newTracerProvider(cfg Config, res *resource.Resource) (*sdktrace.TracerProvider, error) {
+	switch cfg.TracesExporter {
+	case ExporterNone:
+		return sdktrace.NewTracerProvider(sdktrace.WithResource(res)), nil
+	case ExporterStdout:
+		exporter, err := stdouttrace.New()
+		if err != nil {
+			return nil, fmt.Errorf("stdout trace exporter: %w", err)
+		}
+		return sdktrace.NewTracerProvider(
+			sdktrace.WithBatcher(exporter),
+			sdktrace.WithResource(res),
+		), nil
+	default:
+		return nil, fmt.Errorf("unsupported traces exporter %q", cfg.TracesExporter)
+	}
+}
+
+func newMeterProvider(cfg Config, res *resource.Resource) (*sdkmetric.MeterProvider, error) {
+	switch cfg.MetricsExporter {
+	case ExporterNone:
+		return sdkmetric.NewMeterProvider(sdkmetric.WithResource(res)), nil
+	case ExporterStdout:
+		exporter, err := stdoutmetric.New()
+		if err != nil {
+			return nil, fmt.Errorf("stdout metric exporter: %w", err)
+		}
+		return sdkmetric.NewMeterProvider(
+			sdkmetric.WithResource(res),
+			sdkmetric.WithReader(sdkmetric.NewPeriodicReader(exporter)),
+		), nil
+	default:
+		return nil, fmt.Errorf("unsupported metrics exporter %q", cfg.MetricsExporter)
+	}
+}