Stage 8: UI social/account/history surfaces

Wire the deferred Stage 7 surfaces end-to-end (UI -> gateway transcode ->
backend REST -> existing domain services): friends (incl. one-time friend
codes), per-user blocks, friend-game invitations, profile editing + email
binding, the statistics screen, and the in-game history + GCG export.

Friends gain two add paths (interview decision, a deliberate plan change):
one-time 6-digit codes (friend_codes table, 12h TTL, single-use, rate-limited
redeem); and play-gated requests (shared game required) where an explicit
decline is permanent, an ignored request lapses after 30 days, and a code
bypasses a decline. Migration 00006 widens friendships_status_chk and adds
friend_codes.

Lobby notification badge is poll + push: a new generic `notify` event drives
it live; the client polls on open/focus. Language stays a single Settings
control that writes through to the durable account's preferred_language. GCG
export is finished-only (game.ErrGameActive) and shares/downloads the .gcg file.

Tests: backend unit + inttest (friend gate/decline/code, ListInvitations,
GetStats, GCG gate), gateway transcode round-trips + notify constructor, UI
vitest (codecs, win-rate, share choice) + Playwright social specs. Docs: PLAN
(Stage 8 done + refinements + TODO-5), ARCHITECTURE, FUNCTIONAL(+ru), UI_DESIGN,
TESTING, module READMEs.

backend/internal/social/friendcodes.go

@@ -0,0 +1,209 @@
+package social
+
+import (
+	"context"
+	crand "crypto/rand"
+	"crypto/sha256"
+	"database/sql"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"math/big"
+	"time"
+
+	"github.com/go-jet/jet/v2/postgres"
+	"github.com/go-jet/jet/v2/qrm"
+	"github.com/google/uuid"
+
+	"scrabble/backend/internal/notify"
+	"scrabble/backend/internal/postgres/jet/backend/model"
+	"scrabble/backend/internal/postgres/jet/backend/table"
+)
+
+const (
+	// friendCodeTTL bounds how long an issued friend code stays redeemable.
+	friendCodeTTL = 12 * time.Hour
+	// friendCodeIssueRetries caps regeneration attempts when a freshly generated
+	// code collides (by hash) with another account's still-live code.
+	friendCodeIssueRetries = 5
+)
+
+// FriendCode is a freshly issued one-time add-a-friend code. The plaintext Code is
+// returned exactly once (only its hash is persisted); the issuer shares it out of
+// band and whoever redeems it becomes their friend immediately.
+type FriendCode struct {
+	Code      string
+	ExpiresAt time.Time
+}
+
+// IssueFriendCode issues a fresh one-time friend code for accountID, replacing the
+// account's prior live code (at most one is redeemable per issuer at a time). Only
+// the hash is stored; the returned plaintext is the only copy. A collision with
+// another account's live code triggers a regeneration so the redeem lookup stays
+// unambiguous.
+func (svc *Service) IssueFriendCode(ctx context.Context, accountID uuid.UUID) (FriendCode, error) {
+	expiresAt := svc.now().Add(friendCodeTTL)
+	for range friendCodeIssueRetries {
+		code, hash, err := generateFriendCode()
+		if err != nil {
+			return FriendCode{}, err
+		}
+		inserted, err := svc.store.replaceFriendCode(ctx, accountID, hash, expiresAt, svc.now())
+		if err != nil {
+			return FriendCode{}, err
+		}
+		if inserted {
+			return FriendCode{Code: code, ExpiresAt: expiresAt}, nil
+		}
+	}
+	return FriendCode{}, fmt.Errorf("social: could not issue a unique friend code after %d tries", friendCodeIssueRetries)
+}
+
+// RedeemFriendCode makes redeemerID a friend of the account that issued code,
+// consuming the code. It returns the issuer's account id on success, or
+// ErrFriendCodeInvalid (unknown/used/expired), ErrSelfRelation (own code), or
+// ErrRequestBlocked (a block stands between the pair). A redeem bypasses any prior
+// decline between the two: it clears the old row and writes a fresh friendship.
+func (svc *Service) RedeemFriendCode(ctx context.Context, redeemerID uuid.UUID, code string) (uuid.UUID, error) {
+	issuerID, codeID, err := svc.store.liveFriendCodeByHash(ctx, hashFriendCode(code), svc.now())
+	if err != nil {
+		return uuid.UUID{}, err
+	}
+	if issuerID == redeemerID {
+		return uuid.UUID{}, ErrSelfRelation
+	}
+	blocked, err := svc.store.isBlocked(ctx, redeemerID, issuerID)
+	if err != nil {
+		return uuid.UUID{}, err
+	}
+	if blocked {
+		return uuid.UUID{}, ErrRequestBlocked
+	}
+	if err := svc.store.redeemFriendCode(ctx, codeID, issuerID, redeemerID, svc.now()); err != nil {
+		return uuid.UUID{}, err
+	}
+	svc.pub.Publish(notify.Notification(issuerID, notify.NotifyFriendAdded))
+	return issuerID, nil
+}
+
+// replaceFriendCode clears accountID's prior live code and inserts a fresh one,
+// inside one transaction. It reports false (without inserting) when codeHash
+// collides with another still-live code, so the caller regenerates.
+func (s *Store) replaceFriendCode(ctx context.Context, accountID uuid.UUID, codeHash string, expiresAt, now time.Time) (bool, error) {
+	id, err := uuid.NewV7()
+	if err != nil {
+		return false, fmt.Errorf("social: new friend code id: %w", err)
+	}
+	inserted := false
+	err = withTx(ctx, s.db, func(tx *sql.Tx) error {
+		del := table.FriendCodes.DELETE().WHERE(
+			table.FriendCodes.AccountID.EQ(postgres.UUID(accountID)).
+				AND(table.FriendCodes.ConsumedAt.IS_NULL()),
+		)
+		if _, err := del.ExecContext(ctx, tx); err != nil {
+			return fmt.Errorf("clear prior friend codes: %w", err)
+		}
+		var live []model.FriendCodes
+		sel := postgres.SELECT(table.FriendCodes.CodeID).
+			FROM(table.FriendCodes).
+			WHERE(
+				table.FriendCodes.CodeHash.EQ(postgres.String(codeHash)).
+					AND(table.FriendCodes.ConsumedAt.IS_NULL()).
+					AND(table.FriendCodes.ExpiresAt.GT(postgres.TimestampzT(now))),
+			).LIMIT(1)
+		if err := sel.QueryContext(ctx, tx, &live); err != nil {
+			return fmt.Errorf("check friend code collision: %w", err)
+		}
+		if len(live) > 0 {
+			return nil // collision: leave inserted false so the caller retries
+		}
+		ins := table.FriendCodes.INSERT(
+			table.FriendCodes.CodeID, table.FriendCodes.AccountID, table.FriendCodes.CodeHash, table.FriendCodes.ExpiresAt,
+		).VALUES(id, accountID, codeHash, expiresAt)
+		if _, err := ins.ExecContext(ctx, tx); err != nil {
+			return fmt.Errorf("insert friend code: %w", err)
+		}
+		inserted = true
+		return nil
+	})
+	if err != nil {
+		return false, err
+	}
+	return inserted, nil
+}
+
+// liveFriendCodeByHash returns the issuer and code id of the live (unconsumed,
+// unexpired) code with codeHash, or ErrFriendCodeInvalid when none matches.
+func (s *Store) liveFriendCodeByHash(ctx context.Context, codeHash string, now time.Time) (issuerID, codeID uuid.UUID, err error) {
+	stmt := postgres.SELECT(table.FriendCodes.CodeID, table.FriendCodes.AccountID).
+		FROM(table.FriendCodes).
+		WHERE(
+			table.FriendCodes.CodeHash.EQ(postgres.String(codeHash)).
+				AND(table.FriendCodes.ConsumedAt.IS_NULL()).
+				AND(table.FriendCodes.ExpiresAt.GT(postgres.TimestampzT(now))),
+		).LIMIT(1)
+	var row model.FriendCodes
+	if err := stmt.QueryContext(ctx, s.db, &row); err != nil {
+		if errors.Is(err, qrm.ErrNoRows) {
+			return uuid.UUID{}, uuid.UUID{}, ErrFriendCodeInvalid
+		}
+		return uuid.UUID{}, uuid.UUID{}, fmt.Errorf("social: load friend code: %w", err)
+	}
+	return row.AccountID, row.CodeID, nil
+}
+
+// redeemFriendCode consumes the code and writes an accepted friendship between
+// issuer and redeemer, inside one transaction. It clears any prior pending/declined
+// row between the pair first, so a code overrides an earlier decline. A code already
+// consumed by a concurrent redeem yields ErrFriendCodeInvalid (rolling back).
+func (s *Store) redeemFriendCode(ctx context.Context, codeID, issuer, redeemer uuid.UUID, now time.Time) error {
+	return withTx(ctx, s.db, func(tx *sql.Tx) error {
+		upd := table.FriendCodes.
+			UPDATE(table.FriendCodes.ConsumedAt).
+			SET(postgres.TimestampzT(now)).
+			WHERE(
+				table.FriendCodes.CodeID.EQ(postgres.UUID(codeID)).
+					AND(table.FriendCodes.ConsumedAt.IS_NULL()),
+			)
+		res, err := upd.ExecContext(ctx, tx)
+		if err != nil {
+			return fmt.Errorf("consume friend code: %w", err)
+		}
+		n, err := res.RowsAffected()
+		if err != nil {
+			return fmt.Errorf("consume friend code rows: %w", err)
+		}
+		if n == 0 {
+			return ErrFriendCodeInvalid
+		}
+		del := table.Friendships.DELETE().WHERE(edgeEither(issuer, redeemer))
+		if _, err := del.ExecContext(ctx, tx); err != nil {
+			return fmt.Errorf("clear friendship before code accept: %w", err)
+		}
+		ins := table.Friendships.INSERT(
+			table.Friendships.RequesterID, table.Friendships.AddresseeID, table.Friendships.Status,
+			table.Friendships.CreatedAt, table.Friendships.RespondedAt,
+		).VALUES(issuer, redeemer, friendAccepted, now, now)
+		if _, err := ins.ExecContext(ctx, tx); err != nil {
+			return fmt.Errorf("insert friendship from code: %w", err)
+		}
+		return nil
+	})
+}
+
+// generateFriendCode returns a random 6-digit numeric code and its hex SHA-256 hash.
+func generateFriendCode() (code, hash string, err error) {
+	n, err := crand.Int(crand.Reader, big.NewInt(1_000_000))
+	if err != nil {
+		return "", "", fmt.Errorf("social: generate friend code: %w", err)
+	}
+	code = fmt.Sprintf("%06d", n.Int64())
+	return code, hashFriendCode(code), nil
+}
+
+// hashFriendCode returns the hex-encoded SHA-256 of a friend code; the plaintext is
+// never persisted, matching the session and email-code models.
+func hashFriendCode(code string) string {
+	sum := sha256.Sum256([]byte(code))
+	return hex.EncodeToString(sum[:])
+}