scrabble-game/PLAN.md

PLAN — monetization implementation

Technical, step-by-step implementation of the monetization domain. Business mechanics and the rationale for every rule live in docs/PAYMENTS.md (RU mirror docs/PAYMENTS_ru.md); the frozen owner agreements they both derive from (the D1–D41 decisions log) live in docs/PAYMENTS_DECISIONS_ru.md — the authority when a rule is disputed. This file is the how. Each stage is written to be self-sufficient: returning to it gives full context — goal, exact touch-points, tests, done-criteria, and current status — without re-deriving decisions.

How to use this file

• Stage granularity (E0–E9) is fixed. Do not split or merge stages. Plan each stage densely enough to execute whole.
• Never leak stage ids into the product. Code, comments, commit messages, PR titles/descriptions must read as finalized feature copy — never "E5", "stage 3", etc. Stage ids exist only in this file.
• Deviations are allowed when new unknowns surface, but the plan is then edited whole and in agreement (not piecemeal), keeping it coherent, and docs/PAYMENTS.md updated in step.
• Status marks: each stage header carries Status: TODO | WIP | DONE. When a stage lands, flip it to DONE and note the PR. The Progress table is the at-a-glance index.
• Per-change discipline (repo CLAUDE.md): update tests at the layers docs/TESTING.md calls out, bake doc updates into the same PR, run local full verification before pushing, feature branch → PR into development.

Progress

Stage	Title	Release	Status
E0	Payments data foundation	1	DONE
E1	Trusted platform signal	1	DONE
E2	Currency + benefit core	1	DONE
E3	Wallet UI	1	DONE
E4	Durability (PITR)	2	DONE
E5	Payment intake	2	DONE
E6	Ads	2	DONE
E7	Admin & reports	2	TODO
E8	Guest limits	—	TODO
E9	Tournament fee	future	TODO

Release 1 = full mechanics with no real money, exercised via admin_grant (E0→E1→E2→E3). Release 2 = money (E4→E5→E6→E7). E8 is standalone (game-behaviour change, can run in parallel). E9 is future.

---

Architecture baseline (applies to all stages)

Read once; individual stages assume it.

Schema & isolation

• The payments domain owns its own Postgres schema payments in the shared instance (scrabble DB). All payments tables are payments.*. backend schema is untouched except for the deprecation of two legacy columns (E2).
• DB role. A dedicated NOLOGIN role holds ALL privileges on payments.* and nothing on backend — grant-based confinement, asserted by a SET ROLE isolation test. The application still connects on its single (superuser) pool, so these grants are a stepping-stone to a real separate login/process, not the runtime wall. The runtime wall is code-level: only the internal/payments package imports the payments jet code and issues payments.* SQL (an import-boundary test enforces it); every other domain reaches payments through the narrow Go interface.
• No cross-schema link at all. There is no foreign key from payments.* to backend.accounts: account_id is a plain uuid, kept referentially honest in code and joined to the tombstoned account / retained_identities dossier by the stable id. This keeps the spend transaction (ledger INSERT + balance UPDATE + benefit UPDATE) fully within payments and the domain extractable into its own database later. Benefits move into payments (they no longer live on accounts — see E2); game code reads them through the payments Go interface, never via SQL.
• Money. Monetary amounts are a single bigint in the currency's minor units (RUB kopecks; Votes/Stars/chips are whole units, scale 1) carried in Go by the payments.Money value type — the sole constructor/formatter/arithmetic, so no float64 ever touches an amount and a whole-unit currency structurally cannot hold a fraction. chip_rate is not a table: a chip pack is a product, so its per-method rate is product_price.

Domain boundary

• New package backend/internal/payments/ — payments.go (types + Service), store.go (type Store struct{ db *sql.DB }, go-jet against internal/postgres/jet/ payments), following the ads domain shape (backend/internal/ads/{ads,service,store}.go).
• Wired in backend/cmd/backend/main.go run() (construct after account, before server.New), handed into server.Deps (server.go), routes registered in registerRoutes gated if s.payments != nil, admin section in registerConsole gated if s.payments != nil.
• Game/other domains depend on payments only through a narrow interface (e.g. AdFree(ctx, account, platform, present) bool, SpendHint(ctx, account, platform, present) error, Balances(ctx, account, platform, present) …), where present is the set of identity sources the account currently holds (vk→vk, telegram→telegram, email→direct; robot ignored), computed by the caller from account.Identities — payments carries no cross-schema identity knowledge, so unlink/re-link availability (D14) falls out live. Keep the surface small; this is the seam that lets payments become a separate process later without touching callers.
• Read model. Hot reads (AdFree/HintsAvailable/Balances and the gate) are served from an in-process, account-keyed, write-through cache inside the payments package (mirroring account/suspension.go), invalidated on every payments mutation (spend/grant/fund/refund/merge); the payments DB is touched only on a cache miss, so the steady-state hot path issues no query to the payments schema. The D39 materialized balances/benefits tables stay the in-transaction write target the cache fronts. Single-instance, matching the deployment (a multi-instance backend would need a shared cache).

Migrations & codegen

• Migrations: same goose dir backend/internal/postgres/migrations/, sequential 0000N_*.sql, -- +goose Up/Down, schema-qualified, expand-contract mandatory (image rollback must stay DB-safe). First payments migration does CREATE SCHEMA IF NOT EXISTS payments, creates the role, grants.
• jetgen (backend/cmd/jetgen/main.go) is currently hardwired to schema=backend. Extend it to also generate schema=payments into internal/postgres/jet/payments/ {model,table} (committed). Regenerate only after a payments migration; revert unrelated backend-schema churn (jetgen may reorder untouched tables — commit only intended diffs).
• Transactions: reuse the local withTx(ctx, db, fn) idiom. Balance/benefit mutations are guarded single-row atomic UPDATEs (mirror account.SpendHint); the ledger INSERT + materialized-cache UPDATE go in one withTx. Default Read-Committed is sufficient given the guarded updates + unique idempotency keys; do not reach for Serializable without a demonstrated need.

Transport

• client ↔ gateway: Connect-RPC + FlatBuffers (h2c). gateway ↔ backend: REST/JSON + X-User-ID via gateway/internal/backendclient. Any user-facing payments call needs the full chain: backend REST handler (u := s.user group) → backendclient method → Connect-RPC method + transcode (gateway/internal/transcode/) → FlatBuffers schema (pkg/fbs/…, regen with make -C pkg fbs + pnpm -C ui codegen).
• Provider webhooks (Robokassa/VK) do NOT use the Connect path — model on the existing public HMAC-signed route s.public.GET("/dl/:id/:kind", …) (handlers.go): a public route with signature verification, proxied by the gateway/Caddy @gateway matcher (deploy/caddy/Caddyfile — a new edge route MUST be added there or it falls to the landing catch-all).

Testing layers (docs/TESTING.md)

• unit (Go _test.go, TS vitest): gate-by-context, no-ads stacking, priority draw, rate math, idempotency keys, catalog snapshotting. UI logic must be extracted out of .svelte into ui/src/lib/* to be unit-testable.
• integration (backend/internal/inttest/, //go:build integration, Postgres-backed): atomic chip↔benefit spend, callback idempotency, order-flow, TG outbox delivery, merge/ unlink of segments.
• UI (Playwright mock e2e, Chromium+WebKit): Wallet screen, warnings, guest-hidden, GP stub. Mock e2e bypasses codec — wire bugs need codec unit tests.
• Local full verification before push: integration (-tags=integration + DAWG sibling + Ryuk-off), UI check/test/build, codegen (make -C pkg proto fbs, pnpm -C ui codegen).

---

E0 — Payments data foundation

Status: DONE · Release 1 · depends on: none · mechanics: PAYMENTS §14, §7, §11.

Goal. Stand up the payments schema, its confinement role, the jetgen target, the domain package skeleton and all core tables — nothing wired to real money yet. This is the substrate every later stage builds on.

Migration 00010_payments_foundation.sql (payments schema).

• CREATE SCHEMA payments; an idempotent DO $$ block creates a NOLOGIN payments role; GRANT USAGE + GRANT ALL ON ALL TABLES (+ ALTER DEFAULT PRIVILEGES … GRANT ALL) confine it to payments.* with nothing on backend. No REFERENCES grant (there is no cross-schema FK).
• payments.ledger — append-only. ledger_id (uuid PK, app-generated v7), account_id (plain uuid, no FK), kind (fund|spend|admin_grant|refund), source/origin (nullable, vk|telegram|direct), chips_delta (signed int, 0 for a grant), product_id (nullable FK→product), order_id (nullable FK→orders), provider + provider_payment_id (nullable), snapshot (jsonb, written from E2), created_at. Immutability is a BEFORE UPDATE OR DELETE trigger (a superuser bypasses a privilege REVOKE). Unique partial index on (provider, provider_payment_id) WHERE provider_payment_id IS NOT NULL — the idempotency key.
• payments.balances — (account_id, source) PK, chips int CHECK (>=0), updated_at. Created lazily on first fund (up to three rows/account, absent = zero).
• payments.benefits — (account_id, origin) PK, ads_paid_until timestamptz null, ads_forever bool, hints int CHECK (>=0), updated_at. Created lazily.
• payments.catalog_atom — atom_type PK (chips|hints|noads_days|tournament); the four atoms are seeded here (the tournament atom is provisioned for E9).
• payments.product (product_id PK, title, active bool soft-delete, timestamps); payments.product_item ((product_id, atom_type) PK → quantity); payments.product_price ((product_id, COALESCE(method,''), currency) unique → amount bigint minor units): a chip pack carries a money price per method (vk|telegram|direct), a value carries one currency='CHIP', method=NULL row. currency ∈ {RUB, VOTE, XTR, CHIP}; amount CHECK (>=0).
• payments.config — a single typed row (only_row bool PK CHECK): rewarded_payout_chips, cooldown_global_seconds (300), cooldown_vs_ai_seconds (1800), cooldown_hint_seconds (60), order_ttl_seconds (1800). No chip_rate table — the pack rate is product_price.
• payments.orders — order_id (uuid PK), account_id, platform, product_id (FK), expected_amount bigint + currency, origin, status (pending|paid|expired), provider, provider_payment_id (nullable), timestamps. Index (status, created_at) for the pending sweep.
• payments.payment_events — event_id (uuid PK), account_id, order_id (nullable FK), type (succeeded|failed|refunded), payload jsonb, created_at, dispatched_at (nullable, partial index for the dispatch queue).
• Full -- +goose Down (DROP SCHEMA CASCADE + DROP OWNED BY + DROP ROLE); expand-contract, proven reversible by an integration test.

Backend.

• backend/internal/payments/{payments,service,store}.go — the Money value type + Currency (bigint minor units, exact, no float); Store{db *sql.DB} with a Ping health read via jet; Service over the store. (withTx arrives with E2's first transaction.)
• cmd/jetgen generates the payments schema into internal/postgres/jet/payments/ (a second GenerateDB call); committed. Constructed in cmd/backend/main.go and passed to server.Deps (Payments) with a boot-time reachability check; its routes are registered from E2.

Legacy deprecation (expand phase only). A -- header note marks accounts.hint_balance and accounts.paid_account deprecated; they are not dropped (the DROP is the contract phase after E2 flips reads and after Release 2). Reads still use the old columns until E2.

Tests.

• integration (inttest): schema + role + seeds present; SET ROLE payments cannot read backend.accounts (grant confinement); ledger rejects UPDATE/DELETE (trigger); idempotency partial index holds (NULL-keyed rows repeat); balance/benefit/amount/enum CHECKs bite; migration applies forward and backward on a throwaway PG.
• unit: Money — exact round-trip, per-currency scale, no-float parse rejecting a fraction for a whole-unit currency, arithmetic, formatting. Import-boundary test: only internal/payments imports the payments jet code.

Done-criteria (met). Migrations apply forward+backward on a throwaway PG 17; go build ./backend/... + go vet + gofmt -l . clean; committed jet/payments/; all tests green; no behaviour change for users.

Notes. jetgen regenerates the whole backend schema; its committed jet had drifted from the migrations (robot_blocks, robot_friend_requests, the feedback_messages app_version / browser_tz columns, and UseSchema gaps), so this change also regenerates and commits jet/backend to bring it back in sync (additive only — all suites stay green). The payments role creation is idempotent (DO $$ / IF NOT EXISTS) for fresh volumes.

---

E1 — Trusted platform signal

Status: DONE · Release 1 · depends on: none (parallel to E0) · mechanics: PAYMENTS §8.

Goal. Make the server know the execution platform from a trusted, unforgeable source, carried on the session. This is the foundation the gate (E2) stands on; without it the gate is meaningless. Signal plumbing only — no user-visible change.

Model. platform = {kind: vk|telegram|direct, subtype: ios|android|web} is a property of the session, captured at creation. kind is always trusted — the gateway derives it from the validated establish path (VK launch / TG initData / a web-native session), never a client field. subtype is cryptographically trusted only for VK (it rides inside the signed vk_platform launch param); for telegram and direct it is client-reported best-effort, and the gate never relies on it (only the VK-iOS-frozen case is compliance-critical, and VK subtype is trusted). VK/TG re-mint a session on every cold start, so their platform is re-captured each launch; web/direct/email reuse the stored token, so their platform is captured once at creation (direct needs no signature).

Validation stays at the gateway. Both wrapper verifiers already live there and the backend cannot import either (separate modules under internal/, and the VK app secret is gateway-only): VK launch params via the in-process gateway/internal/vkauth.Verify (HMAC-SHA256 over the signed vk_* params under GATEWAY_VK_APP_SECRET, extended here to expose the signed vk_platform → a trusted Subtype()), TG initData via the validator RPC. The gateway hands the derived platform to the backend at establish; the backend persists it and returns it on resolve.

Backend.

• backend.sessions gains nullable platform_kind + platform_subtype columns (migration 00011, CHECK-constrained, jet regenerated). A session.Platform value type + session.Create captures it; Session carries it through the store and the warm cache.
• handleResolveSession → resolveResponse (dto.go) returns the platform; the establish handlers set kind from their own endpoint (/sessions/telegram|vk|guest|email/*) and subtype from the request (VK: gateway-extracted from the signed params; TG/direct: the client best-effort field, defaulting web). The account-merge session mint (link.merge) inherits the caller's platform from the request context.
• Middleware (middleware.go) parses the gateway-injected X-Platform into the request context on the s.user group; platform(c) exposes it. Absent ⇒ untrusted (fail-closed).

Gateway.

• backendclient.WithPlatform(ctx, "<kind>/<subtype>") + do/getRaw inject X-Platform on every authenticated backend call; connectsrv.Execute enriches the request context from the resolved session's platform (carried through the gateway session cache + ResolveSession). Never from a client request body.

Client (ui/). platformSubtype() (ui/src/lib/platform.ts) supplies a best-effort device subtype on the auth.telegram / auth.guest / auth.email.login requests (new FBS subtype field): Telegram's WebApp.platform inside a Mini App, else the Capacitor/web channel. VK sends nothing (the gateway derives the trusted subtype from the signed launch params).

Tests.

• unit (Go): vkauth exposes the signed vk_platform and maps iPhone/iPad → ios (the frozen case); the X-Platform middleware round-trips + reports untrusted when absent; the backend client injects X-Platform from the context and omits it when untrusted.
• integration: a session carries its platform through create + a cold-cache (DB) resolve for each kind; an unattributed session is untrusted; the CHECK constraints bite; migration 00011 applies forward and backward on a throwaway PG.
• UI: subtype normalization (vitest) + the new subtype field on the wire (codec unit test).

Done-criteria (met). A VK/TG session resolves to a trusted {kind, subtype}; a forged body cannot change kind (nor the VK subtype); direct sessions resolve to direct; the untrusted path is reachable and observable via platform(c). No user-visible change; all layers green.

Notes/risks. High blast-radius (auth/session table + broad gateway header threading): additive migration, no mixed-in refactors, X-Platform inert until E2 consumes it. Sessions minted before E1 carry no platform → untrusted (view-only) until re-login; VK/TG self-heal on the next cold-start re-mint, direct/email do not (accepted: Release 1 has no money, sessions cycle by Release 2). TG/direct subtype is not cryptographically trusted — E2 must keep the gate on kind

• the trusted VK subtype only.

---

E2 — Currency + benefit core

Status: DONE · Release 1 · depends on: E0, E1 · mechanics: PAYMENTS §2–§6, §11.

Goal. The full internal money mechanic, exercisable end-to-end without real money via admin_grant: chip balances, spend→benefit atomically, the compliance gate by context, benefit application (no-ads stacking, hints per-origin), the legacy migration, and the SpendHint rewrite. This is the heart.

Payments service (Go). Every read/gate method also takes present (the account's live identity sources, see Domain boundary) and is served from the read cache.

• Balances(ctx, account, platform, present) → per-segment {source, chips, spendable} for the context (VK→vk spendable, direct/tg hidden; TG→tg; direct→direct+vk+tg by priority; VK-iOS→vk shown as a frozen number, none spendable; untrusted→view-only, none spendable).
• Spend(ctx, account, platform, present, productID) → gate-checked purchase of a value (CHIP price, method=NULL; never a chip pack) with chips: resolve spendable segments by context, draw by priority direct→vk→tg, write a spend ledger row (+ a catalog snapshot of atoms+price) + decrement balance + apply benefit (extend ads_paid_until[origin] from max(now,end) / set ads_forever / add hints) in one tx, stamping origin = platform context. Refuse if untrusted (fail-closed) or funds insufficient.
• Grant(ctx, account, origin, atoms) → a 0-price sale of a value: an admin_grant ledger row (chips_delta=0, + snapshot), same benefit application; concrete values only, never chips (no chips move — it neither requires nor touches a balance). Origin chosen by the admin. In E2 this is the Go service method only, exercised by tests; the admin grant UI
  • catalog editor are E7.
• AdFree(ctx, account, platform, present) / HintsAvailable(…) / SpendHint(…) → apply the one-directional origin rule: in context P, usable origins = {P} plus, when P is web/native, {vk,tg} (relaxation outward); in VK only vk; in TG only tg. Hint consumption draws by the same priority direct→vk→tg.
• Merge / Unlink hooks: extend accountmerge to merge segments and benefits by origin (same-origin add — chips sum, terms extend per origin; different origins coexist) in the caller's tx (MergeTx), and make both segment and benefit availability follow identity presence — unlink sleeps the balance and the benefit, re-link wakes them (D14), resolved live from present. Warn-before-unlink surfaces the balance via the interface; the warning UI itself is not E2.

Backend wiring & migration.

• Deprecate-and-flip accounts.hint_balance / accounts.paid_account: E0 added the tables; here, move reads/writes to payments.benefits. SpendHint (game/service.go ~:1147) and ads.Eligible (ads/ads.go :107) call the payments interface instead of the account columns. Legacy values were never set in prod → zero them; the DROP is the contract phase (guarded, after Release 2 — keep columns until then for rollback safety).
• vs_ai hints stay free/unlimited (unchanged 30-min gate); only online-game hint spend routes through the segmented, context-aware path.

API (user-facing, Connect chain). Read-only wallet view + spend: GET /api/v1/user/wallet (balances+benefits for the context), POST /api/v1/user/wallet/ buy (spend chips on a product). Add the backend handlers (u := s.user), backendclient methods, Connect methods + transcode + FBS. Admin grant is internal/admin (E7 UI).

Tests.

• unit (Go): gate-by-context matrix (every row of PAYMENTS §4, incl. VK-iOS frozen + untrusted); priority draw; no-ads stacking (+= from max(now,end)) + forever override; per-origin hint applicability + direct→vk→tg draw; merge/unlink segment+benefit math; catalog snapshotting; read-cache invalidation on each mutation.
• integration: atomic spend (ledger+balance+benefit in one tx; failure rolls all back); admin_grant credits values not chips; legacy migration zeroes and flips reads; merge/ unlink over Postgres.
• UI: none new (E3 builds the screen); wallet DTO covered by codec unit tests.

Done-criteria. admin_grant applies no-ads/hints directly (a 0-price sale of a value — no chips involved); the player chip-spend path (Spend) is proven by unit/integration tests (balance seeded in-test, since a legitimate chip source arrives only with Release 2); the gate blocks cross-context spend and cross-origin application; the ads gate reads the new benefit; SpendHint uses segments; the hot read paths hit the read cache, not the payments schema; all layers green; compliance regression (a direct benefit never activates inside VK/TG) is a named test.

Notes/risks. This is the high-blast-radius core (money semantics + a live path SpendHint/ads.Eligible). Minimize surface, keep the interface narrow, no mixed-in refactors. The legacy flip is expand-contract: reads move first, DROP much later.

---

E3 — Wallet UI

Status: DONE · Release 1 · depends on: E2 · mechanics: PAYMENTS §1, §7, §6, §13, §4.

Goal. The user-facing "Кошелёк" (Wallet) section: balances + active benefits + the catalog storefront, honouring guest-hidden, GP-stub, and the web-spend warning.

Backend + wire (catalog read — new). E2 shipped wallet.get / wallet.buy (segments + benefits + a chip spend) but no way to list the catalog; the storefront needs one, so E3 adds a read path following the E2 shape:

• payments.Service.Catalog(ctx, cxt) + store.loadCatalog (internal/payments/{catalog, store_catalog}.go) read every active product with atoms and prices and project them to the context (projectCatalog, pure + unit-tested): a value (no chips atom) carries its CHIP price and shows everywhere; a chip pack (chips atom) carries the money price for the context method (cxt.Kind: vk→VOTE, telegram→XTR, direct→RUB) and shows only where that method is priced. Read uncached (the catalog is small and rarely edited — unlike the per-account balances/benefits the read cache fronts).
• REST GET /api/v1/user/wallet/catalog (handleWalletCatalog, gated by walletGate) → catalogDTO; gateway op wallet.catalog (transcode.go + encodeCatalog), backendclient. Catalog; FBS Catalog/CatalogProduct/CatalogAtom (pkg/fbs/scrabble.fbs), client decodeCatalog.

UI (ui/).

• New 'wallet' tab in ui/src/screens/SettingsHub.svelte — SettingsTab union, tab button between Friends and About (guest-hidden like Friends, offline-disabled like Profile/Friends), body branch, 'wallet' route in ui/src/lib/routeparse.ts + ui/src/App.svelte.
• Wallet.svelte screen: context-available chip balances + active benefits (no-ads until date / forever, hints count). No history feed (PAYMENTS §11 — noise). Storefront: values priced in chips (buyable with wallet.buy), chip packs priced per method.
• Guest: section hidden entirely (durable-only).
• GP build: the chip-pack purchases are hidden behind a RuStore stub; spending earned chips on values still works (PAYMENTS §13). Detected by a build-time flag VITE_GP_BUILD (ui/src/lib/distribution.ts), forcible under the mock e2e with ?gp.
• Web-spend warning: before a value spend that would draw vk/tg chips in a direct context, an own Modal (not showPopup) warns the benefit will be web/native-only. The context is inferred client-side (executionContext — VK/Telegram/direct); the server enforces the real gate on wallet.buy (fail-closed), so no wallet-DTO change was needed.
• Logic extracted to ui/src/lib/{wallet,distribution}.ts (unit-testable); .svelte stays thin.

Pack purchase is display-only in E3. Buying a chip pack needs the money order flow, which is E5; here a pack card shows its price with a disabled "Soon" action. E5 replaces that with the launch/order CTA. Value spends are wired now (E2 wallet.buy), though a Release-1 durable account has 0 chips until funding exists (E5/E6), so a real value spend returns insufficient-funds until then.

Tests.

• unit (Go): projectCatalog context matrix (value everywhere; pack per context method; misconfig omitted). unit (vitest): money/price formatting, spendable-segment selection, warning trigger, the GP flag; decodeCatalog codec round-trip (mock e2e bypasses the codec).
• integration (inttest): /wallet/catalog returns active products with the context-correct price over Postgres; soft-deleted excluded.
• UI (Playwright mock, Chromium+WebKit): Wallet renders between Friends/About; guest hides it (?guest seam); GP stub (?gp); warning modal on a vk-drawing web spend, no warning on a direct-covered spend. Mock overlay stays instant under MODE==='mock' (or it intercepts taps).

Done-criteria (met). Balances/benefits/storefront render per context; guest/GP/warning paths verified by unit + integration + mock e2e on both engines. A populated contour review depends on later stages (no products until the E7 catalog editor, no chip funding until E5/E6, no grant UI until E7): on the contour E3 shows the correct empty wallet/storefront states; the populated UI is proven by the mock e2e. (This replaces the earlier "demonstrable end-to-end via admin_grant" line — the grant UI is E7.)

Notes/risks. No global .btn/.ghost in ui/ — styled per-component with scoped CSS + tokens (mirror NewGame .invite). Product titles are single-language catalog data (E0 product.title), shown verbatim; currency/chip words are i18n, counts follow the app's label+number convention (no noun agreement). Svelte whitespace/$state naming gotchas apply.

---

E4 — Durability (PITR)

Status: DONE — armed + restore-drilled on prod (v1.13.0, 2026-07-09). · Release 2 · depends on: E0 (schema exists) · mechanics: PAYMENTS §14 (D4).

Goal. Continuous WAL archiving with point-in-time recovery, armed before the first real money is accepted (E5 prod). Protects both money and game data.

Locked decisions (this stage).

• Tool: pgBackRest. Destination: Selectel S3 object storage (encrypted AES-256-CBC, path-style addressing), prod main host only — the test contour never archives. (D4 left the tool + destination open; resolved here. Warm replica stays deferred, per D4.)
• Retention 30 days, daily full base backup (a systemd timer) + continuous WAL (archive_command, a 5-minute forced switch bounds the recovery point). Assessment (owner-reviewed prod gate): measured prod WAL ~0.77 MB/day, DB ~9.6 MB → archive < 1 ₽/month on Selectel S3, negligible perf impact. Recorded in deploy/README.md.
• Archiving ships gated OFF (PGBACKREST_ARCHIVE_MODE on the DB, pitr_enabled for the timer — both default off), so the merged/redeployed artifact is inert until armed and an un-armed prod deploy cannot pile WAL onto the disk.

Work (landed in the artifacts PR into development).

• pgBackRest in the DB image (deploy/postgres/Dockerfile); postgres becomes a built + pushed image (prod overlay image: + prod-deploy.yaml build/push list).
• Repository config + archive_mode via PGBACKREST_* env on the prod-overlay postgres service; secrets/vars rendered by deploy/write-prod-env.sh from the PROD_PGBACKREST_* Gitea set; parity added to prod-rollback.yaml (a rollback must not disarm archiving).
• Daily base-backup systemd timer (Ansible main role, gated by pitr_enabled).
• Two Grafana alerts on the exporter's pg_stat_archiver metrics (failing / stalled), absent/NaN-safe on the contour.
• Belt-and-braces pg_dump fixed to dump the whole DB (deploy/prod-deploy.sh was -n backend, silently excluding payments); manual-restore runbook updated.
• Full PITR runbook + arming sequence + recorded assessment in deploy/README.md.

Prod arming (completed 2026-07-09 with the v1.13.0 release). Owner created the Selectel S3 bucket (erudite, ru-6) + the PROD_PGBACKREST_* secrets/variables (incl. ARCHIVE_MODE=on); promoted development → master → prod-deploy (archive_mode on behind the maintenance window), then stanza-create + first base backup (31.9 MB cluster → 3.7 MB in the repo) + check, the Ansible -e pitr_enabled=true timer, and a restore drill on an isolated one-shot target (data intact, then wiped). Exact steps: deploy/README.md (point-in-time recovery — arming).

Tests. Restore drill on an isolated one-shot instance (base + WAL → target timestamp), recorded in deploy/README.md. No app-level tests. Local verification: docker compose config valid + the custom PG image builds (archiving inert on the contour).

Done-criteria (met). WAL archiving live on prod PG (v1.13.0); a restore verified on an isolated one-shot target; cost + perf assessment reviewed; runbook current in deploy/README.md.

Notes/risks. The repository cipher passphrase is unrecoverable if lost — stored apart from the S3 keys. Manual/timer pgBackRest runs use docker exec -u postgres … --pg1-user=scrabble (docker exec is root; the DB superuser role is scrabble, not postgres) — the systemd timer

• the runbook carry this. Enabling archive_mode restarts postgres (rode the prod-deploy maintenance window). Migrations stay expand-contract so image rollback remains DB-safe with PITR.

---

E5 — Payment intake

Status: DONE · Release 2 · depends on: E0, E1, E2, E4 · mechanics: PAYMENTS §9, §12.

Delivery & baked decisions. Shipped as a linear PR stack (owner's choice), Robokassa first. Resolved: match the order by a Robokassa Shp_order custom parameter, not the numeric InvId (an order id is a uuid); idempotency key = the order id (provider_payment_id = order_id); the НПД receipt is formed shop-side in the Robokassa cabinet, so no Receipt parameter is sent; a chargeback never drives the balance negative (D27 stands, balances_chips_chk kept), so E5 is schema-free (no migration, no contour wipe). Delivered on feature/payment-intake-robokassa: the offer page (/offer/), the order/fund engine (idempotent, honours an expired order), the internal/robokassa adapter, the POST /wallet/order + internal Result-callback handlers (a D36 confirmed-email gate on direct), the pending reaper, the wallet.order edge wire + the public /pay/* routes, the Wallet purchase CTA, the contour deploy env (IsTest forced), and the payment_events dispatcher — an in-app wallet-refresh push (KindNotification "payment") with a self-closing provider-return page (the payment opens in a separate window) and a return-focus refetch fallback. The VK Votes rail is delivered too: the client opens VKWebAppShowOrderBox({item: order_id}); a two-phase signed server callback (get_item → the pack title + vote price; a chargeable order_status_change → the same Fund with source=vk, idempotent on VK's own order id) is verified at the gateway with the app protected key (GATEWAY_VK_APP_SECRET, already deployed) and proxied to the backend intake. The Telegram Stars rail is delivered on feature/payment-intake-tg-stars: only the bot reaches Telegram, so the invoice is minted by the bot — on the wallet.order path the gateway sends a new CreateInvoice command over the reverse bot-link and the bot returns the createInvoiceLink (XTR) in its Ack, handed to the client's WebApp.openInvoice. The bot answers pre_checkout_query via a new bot→gateway ValidatePreCheckout unary (backed by the backend: the order must exist, be still creditable and not already paid — the reusable-invoice double-pay guard — with a matching amount); the decline reason is localised to the order account's language. A completed successful_payment is persisted to a pure-Go SQLite outbox (modernc.org/sqlite) then forwarded by a new bot→gateway ForwardPayment unary into the same Fund (source=telegram, idempotent on telegram_payment_charge_id, honours an expired order), re-driven at startup and every 30 s. The rail is wired by TELEGRAM_STARS_OUTBOX_DIR (defaults to the bot /data volume) but stays inert until a chip pack carries an XTR price, so seeding a Stars price in the admin is the go-live. Finally refunds are delivered on feature/payment-intake-refunds: a single Refund engine (internal/payments) reverses a paid order best-effort, exactly once — idempotent on (provider, provider_refund_id), revoking the funded chips floored at 0 (never negative, D27), and recording the unrecoverable remainder (chips already spent) as a per-account loss + abuse flag in the new additive payments.account_risk table (read by the E7 report). The refund ledger row's chip delta is what was actually reclaimed (the ledger stays reconcilable); the full reversal rides in its snapshot; the order stays paid. No rail pushes an unsolicited refund — all are admin-triggered (E7): Robokassa refund API / cabinet (auto-polling deferred — a worker not worth it at low chargeback volume), VK via support, Telegram refundStarPayment. failed events are not wired (no rail signals a hard post-charge server decline). The migration is additive (a new table only), so E5 stays rollback-safe / no contour wipe. That closes E5. Deferred to a later stage: hiding the ad banner on a no-ads purchase (a spend-path NotifyBanner, with the owner's agreement).

Goal. Accept real money on all three rails into the payments domain: order-flow, verified provider callbacks, idempotency, the TG bot SQLite outbox, the event dispatcher, receipts, and refunds.

Order-flow & intake (single writer).

• POST /api/v1/user/wallet/order → create order(pending) (account/platform/product/ expected amount/origin), return the provider-specific launch payload with order_id threaded in (Robokassa InvId / TG invoice_payload / VK item). The storefront's chip-pack card wires its purchase CTA to this here, replacing the disabled "Soon" placeholder E3 left (ui/src/screens/Wallet.svelte).
• Robokassa + VK public webhooks: new edge routes (add to deploy/caddy/Caddyfile @gateway matcher — or they fall to the landing catch-all), signature/HMAC verified, proxied into a payments intake handler. Match by order_id, verify amount, credit (ledger fund + balance UPDATE in one tx), mark order paid, emit payment_event. Idempotent by (provider, provider_payment_id).
• Pending sweep: background reaper expires pending orders after the configured timeout (~30 min). Expiry is cosmetic — a later valid callback still credits (revive/honour).

TG bot outbox (platform/telegram/).

• The bot receives successful_payment (and pre_checkout_query) via Bot API. A SQLite store on the bot's disk (internal/outbox): on receipt, persist → forward over the reverse mTLS bot-link to the gateway (a ForwardPayment unary; the bot cannot dial the backend directly) → the gateway proxies to the backend payments-intake REST → on a durable response, mark forwarded. Re-drive undelivered on startup and on a 30 s tick. Backend intake dedups by telegram_payment_charge_id.
• Invoice creation (Stars) is minted by the bot (createInvoiceLink, XTR) on the gateway's CreateInvoice bot-link command, returned to the Mini App as the openInvoice link.

Events & notifications.

• payment_events dispatcher: succeeded/failed/refunded → live gRPC stream if the user is connected, else botlink push / email relay (existing). "failed" = an active provider decline (not an abandoned pending) surfaced to the user; "succeeded" hook (email/bot message).

Receipts (§12). Robokassa self-employed НПД receipt on payment (provider config); VK handles Votes tax itself; TG Stars — no receipt.

Refunds (§9). ToS non-refundable. All refunds are admin-triggered (E7): no rail pushes an unsolicited refund — Robokassa refund API / cabinet (auto-polling deferred as a low-value worker), VK via support, Telegram refundStarPayment. One Refund engine reverses a paid order best-effort, exactly once (idempotent on (provider, provider_refund_id)): revoke floored at 0 (never negative), unrecoverable remainder → per-account loss + abuse flag (payments.account_risk), a refund ledger row (chip delta = revoked, full reversal in the snapshot). failed events are not wired (no rail signals a hard post-charge server decline). Ledger export-ready (reconciliation not built).

Tests.

• unit: signature/HMAC verifiers per rail; order-id matching; idempotency-key dedup.
• integration: full order→callback→credit per rail; duplicate callback credits once; expired order still honoured on late callback; TG outbox store→forward→ack→cleanup + restart re-drive; refund revoke best-effort/never-negative.
• UI: purchase flow reaches the provider launch (mock); success/failure surfaced.

Done-criteria. A real (sandbox) payment on each rail credits chips exactly once; a replayed callback does not double-credit; the TG outbox survives a bot restart mid-flight; failed/succeeded events reach the user; refund path exercised. PITR (E4) armed and the cost/perf assessment reviewed before this goes to prod.

Notes/risks. Manual docker run -p boot tests fail from the shell — verify the runnable artifact via the testcontainers integration suite. Distroless services run UID 65532; bind-mounted secrets must be 0644. Edge routes silently fall through if not added to the Caddyfile — add a CI probe. The prod rolling deploy skips caddy on config-only changes — force-recreate when the Caddyfile changes.

---

E6 — Ads

Status: DONE · Release 2 · depends on: E2 (chips), E5 (rewarded credits via intake) · mechanics: PAYMENTS §10.

Delivery & baked decisions. Shipped as a linear PR stack (owner's choice): rewarded first, then interstitial. Baked: the interstitial cooldowns already exist in payments.config (E0) and the per-origin banner suppression is already done (E2 AdFree), so E6 is the two ad DISPLAY paths + the rewarded credit. VK reality (checked live in the VK docs via Playwright): VK Mini App ads (VKWebAppShowNativeAds, both reward and interstitial) expose only a client-side data.result boolean — no server verify, no signature. So D29 is amended: rewarded is client-attested, guarded by a server daily + hourly cap (config reward_daily_cap / reward_hourly_cap, default 50 / 10) that is both anti-abuse and an economic conversion lever (limits free chips so players buy); the cooldown state for the interstitial is client-mirrored (owner's pick). Delivered on feature/ads-rewarded (the rewarded slice): the ads-network abstraction (ui/src/lib/ads.ts, VK impl) + the VK bridge (vkRewardedReady / vkShowRewarded), the backend CreditReward (VK-only, order-less, idempotent on a client nonce, floored by the caps, payout from config rewarded_payout_chips default 0 = off), the wallet.reward edge op returning the updated wallet (with reward_chips gating the "watch for chips" CTA), and a contour test stub (VITE_ADS_STUB → a toast instead of a real ad; prod always real). A temporary diagnostic confirmed on the contour that VK returns only {result:true} (no token/signature) — client-attested is final, no hardening possible; the diagnostic is removed. The slice also corrects the VK-iOS freeze to purchase-only (rewarded on VK-iOS earns chips, which the old blanket "spend freeze" then blocked from spending — Apple forbids only buying in-app values, not spending or earning them; vkFrozen() now gates only CreateOrder, not spendableSources, so VK-wallet chips spend on VK-iOS). Delivered on feature/ads-interstitial (the interstitial + D31 slice): the post-move fullscreen interstitial as a client-mirrored gate — the backend adsFor puts the config cooldowns + a suppressed flag (the no-ads / no_banner gate, same as the banner) on the profile (Profile.ads), and ui/src/lib/ads.ts maybeShowInterstitial self-gates on the last-shown time per kind in localStorage, showing a VK interstitial (vkShowInterstitial) after a confirmed play or a hint only (never a pass / exchange / resign), VK-only, offline banner-only, with the same VITE_ADS_STUB toast on the contour. The slice also lands D31 step 1 (contract-code): the domain no longer reads or writes the deprecated accounts.hint_balance / paid_account columns — the Account fields, the dead account.SpendHint, account.GrantHints and the admin grant-hints action are removed, and the in-game hint display now comes wholly from the payments benefit (HintsAvailable). The columns stay (no migration → image rollback is DB-safe); a later contract-PR does the DROP once E6 is stable on prod.

Goal. VK video ads: the post-move interstitial (frequency-gated) and the rewarded video (credits chips via server verify), plus extending the existing banner suppression to per-origin.

Work.

• Provider abstraction: a small ads-network interface (VK impl now) so a future network for other platforms slots in without rework. VK integration via ui/src/lib/vk.ts.
• Rewarded: voluntary view → the network's server verify callback → payments intake credits chips to the vk segment (client not believed, like a payment). On-launch anti-fraud = provider verify only (no own daily cap; abstraction allows later).
• Interstitial (post-move fullscreen), configurable server values (from payments config): global per-user cooldown across all games (default 5 min); vs_ai 30 min; a hint application triggers a post-move interstitial independently with its own 1-min cooldown; offline banner-only; respect VK's own frequency caps. Cooldown state is client-mirrored (the chosen option): the server sends the cooldowns + suppressed on the profile and the client self-gates on a per-kind last-shown time in localStorage — no per-move round-trip.
• Banner suppression: extend ads.Eligible (backend/internal/ads/ads.go :107) to gate on the origin benefit applicable in the current context (E2 interface) instead of the single legacy flag. No-ads suppresses banner + interstitial; rewarded never suppressed.

Tests.

• unit: cooldown logic (global 5m / vs_ai 30m / hint-trigger 1m independence); rewarded credit path; banner eligibility per context.
• integration: rewarded verify → credit exactly once (idempotent like a payment).
• UI: interstitial shows/respects cooldown (mock); rewarded button; no-ads hides banner + interstitial; rewarded still available under no-ads.

Done-criteria. VK rewarded credits chips once per verified view; interstitial respects all cooldowns incl. the hint trigger; no-ads suppresses banner+interstitial but not rewarded; offline shows banner only.

Notes/risks. Crypto-payout networks stay rejected. Rewarded-without-payout is pointless — only enable where the network pays (VK). Keep the interstitial frequency as server config so it tunes without a store release.

---

E7 — Admin & reports

Status: TODO · Release 2 · depends on: E2 (ledger/grant), E5 (payments/refunds) · mechanics: PAYMENTS §11.

Goal. The admin console financial surface: per-user report, admin grant UI, manual refund UI, ledger export.

Work (/_gm, backend/internal/server/handlers_admin_console.go + adminconsole/).

• Per-user financial panel on the existing user card (consoleUserDetail :343, UserDetailView): segment balances, payments, spends, grants, refunds, full history — read from the append-only ledger + materialized cache.
• Admin grant action (mirror the existing POST /_gm/users/:id/grant-hints): grant concrete values (no-ads days / hints), origin picker, never chips; writes an admin_grant ledger row (E2 Grant).
• Manual refund action: admin-initiated refund of a specific order (ties to the refund path); records a refund ledger row; best-effort benefit revoke.
• Ledger export: CSV/JSON export of the ledger for tax reporting + future Robokassa reconciliation (export-ready schema; reconciliation itself not built).
• Auth unchanged: gateway Basic-Auth in front of /_gm + backend same-origin CSRF on POSTs.

Tests.

• unit: report view assembly; grant refuses chips; export shape.
• integration: grant/refund write correct ledger rows; report reflects balances+history.

Done-criteria. An operator can see a user's full financial picture, grant concrete values (origin-picked, never chips), issue a manual refund, and export the ledger.

Notes/risks. /_gm per-user detail already surfaces PaidAccount/HintBalance — replace those with the segmented view as the legacy columns retire.

---

E8 — Guest limits

Status: TODO · standalone (game-behaviour change; can run in parallel) · depends on: none · mechanics: PAYMENTS §6.

Goal. A registration funnel: cap what a guest can do, enforced server-side (today the gating is UI-only).

Finding (verified). The friend/invitation paths do not check is_guest on the server — only the UI hides them: social/friends.go:50 SendFriendRequest, robotfriends.go:41 RequestInGame, friendcodes.go:67 RedeemFriendCode, lobby/invitations.go:208 CreateInvitation. A guest with a valid X-User-ID can call them in the UI's stead.

Work.

• Server guest gate on friend-request / redeem-code / invitation-create: refuse when the caller is_guest (add an ErrGuestForbidden-style guard, as feedback already has).
• Active-game limits for guests: at most 1 random-opponent game + 1 vs_ai concurrently (enforce on game/invitation creation in lobby/game; today no such limit exists).
• Keep the existing UI gating; this adds the server as the source of truth.

Tests.

• integration: guest is refused friend/redeem/invitation server-side; guest blocked from a 2nd random / 2nd vs_ai; durable account unaffected.
• UI: guest sees the funnel (existing hides + any new messaging).

Done-criteria. Guests are server-limited to 1 random + 1 vs_ai and cannot friend/invite; durable accounts unchanged; regression that this does not break existing durable flows.

Notes/risks. This changes existing game behaviour — its own tests, its own PR, no mixed-in payments changes. Decide whether a guest may finish an already-started game (limit on creation, not mid-game) at implementation and record it here.

---

E9 — Tournament fee (future)

Status: TODO · future · depends on: E0 (atom provisioned), tournament feature · mechanics: PAYMENTS §5, §7.

Goal. Charge a chip entry fee for tournaments. The tournament atom + a catalog product are provisioned in E0/E7; the spend mechanic reuses E2 (Spend). The actual tournament feature and its coupling to entry are out of scope until the tournament feature exists.

Done-criteria. Deferred — revisit when tournaments are built.

---

Verification & CI (all stages)

• Per-stage tests at the layers above; compliance-gate regression is mandatory (a direct benefit must never activate inside VK/TG) and runs from E2 onward.
• Local full verification before every push: go build/vet ./backend/... && gofmt -l ., integration (-tags=integration + DAWG sibling + Ryuk-off), pnpm -C ui check/test:unit/ build, Playwright mock e2e, codegen (make -C pkg proto fbs, pnpm -C ui codegen).
• Contour: each PR into development auto-deploys the test contour; owner does visual sign- off there (not local). Keep a multi-PR batch a linear stack (one shared contour, last-deploy-wins).
• Prod (Release 2): expand-contract migrations only (image rollback DB-safe); PITR armed + the E4 cost/perf assessment reviewed before the first money; new edge routes added to the Caddyfile with a CI probe; caddy force-recreated on config-only changes.
• Release framing: shipped docs/code/commits/PRs carry no stage ids — finalize copy for the release, not the plan.