Stage 11: account linking & merge (email + Telegram Login Widget) (#12)

backend/README.md

@@ -83,6 +83,18 @@ pipeline, dictionary **hot-reload** from `BACKEND_DICT_DIR/<version>/`
 backend Telegram-connector client (`internal/connector`, `BACKEND_CONNECTOR_ADDR`). 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
+attached to the current account, and when the identity already has its own account
+the two are merged in one transaction (`internal/accountmerge`) — stats and the hint
+wallet summed, `paid_account` ORed, identities/games/chat/complaints transferred,
+friends/blocks de-duplicated, the secondary kept as a `merged_into` tombstone (so a
+shared finished game's foreign keys hold); a shared **active** game blocks the merge.
+The current account is primary, except a guest initiator whose linked identity has a
+durable owner — then the durable account wins and a fresh session is minted for it.
+Migration `00009` adds `paid_account`/`merged_into`/`merged_at`. This supersedes the
+Stage 8 `email.bind.*` edge surface (the `RequestCode`/`ConfirmCode` primitives stay).
+
 ## Package layout
 
 ```
@@ -93,8 +105,10 @@ internal/telemetry/  # OpenTelemetry providers + per-request timing middleware
 internal/postgres/   # pgx-over-database/sql pool (otelsql), goose migrations
   migrations/        #   embedded *.sql (goose), schema `backend`
   jet/               #   generated go-jet models + table builders (committed)
-internal/account/    # durable accounts + platform/email identities (store)
-internal/session/    # opaque tokens, sessions store, write-through cache, service
+internal/account/    # durable accounts + platform/email identities (store) + email/identity link primitives
+internal/accountmerge/ # single-transaction merge of a secondary account into a primary (Stage 11)
+internal/link/       # link/merge orchestrator over account + accountmerge + session (Stage 11)
+internal/session/    # opaque tokens, sessions store, write-through cache, service (incl. RevokeAllForAccount)
 internal/server/     # gin engine, route groups, X-User-ID middleware, probes
 internal/engine/     # in-process scrabble-solver bridge: registry, bag, Game, replay
 internal/game/       # game domain: lifecycle, journal+cache, hint, word-check, GCG, sweeper