feat(payments): chip wallet, store-compliance gate and benefit application

Stand up the internal chip/benefit mechanic behind the narrow payments interface:
context-aware balances and benefits, an atomic chip spend, admin grants as
zero-price value sales, the one-directional store-compliance gate (VK/TG same-
origin only, web draws direct→vk→tg, VK-iOS frozen, untrusted fail-closed), and
per-origin hint and no-ads application with term stacking. Reads are served from
an in-process, account-keyed write-through cache (mirroring the suspension gate),
so hot paths issue no query to the payments schema.

Flip the online-game hint wallet and the ad-banner suppression from the deprecated
accounts.hint_balance / paid_account columns to the payments benefit (a hint
balance no longer suppresses the banner — only a no-ads benefit does), and fold
chip segments and benefits by origin on account merge, inside the merge tx. Add
the GET/POST /api/v1/user/wallet edge chain (REST → Connect → FlatBuffers) plus
its codec unit test; no wallet UI yet.

Bring the frozen owner decisions log into the repo at
docs/PAYMENTS_DECISIONS_ru.md (it was untracked under .vscode) and reference it
from PLAN.md; record the read-cache design and the present-sources interface in
PLAN.md and docs/PAYMENTS.md (+ RU mirror).

ui/src/gen/fbs/scrabblefb.ts

@@ -81,5 +81,8 @@ export { TelegramLoginRequest } from './scrabblefb/telegram-login-request.js';
 export { TileRecord } from './scrabblefb/tile-record.js';
 export { UpdateProfileRequest } from './scrabblefb/update-profile-request.js';
 export { VKLoginRequest } from './scrabblefb/vklogin-request.js';
+export { Wallet } from './scrabblefb/wallet.js';
+export { WalletBuyRequest } from './scrabblefb/wallet-buy-request.js';
+export { WalletSegment } from './scrabblefb/wallet-segment.js';
 export { WordCheckResult } from './scrabblefb/word-check-result.js';
 export { YourTurnEvent } from './scrabblefb/your-turn-event.js';

ui/src/gen/fbs/scrabblefb/wallet-buy-request.ts

@@ -0,0 +1,48 @@
+// automatically generated by the FlatBuffers compiler, do not modify
+
+import * as flatbuffers from 'flatbuffers';
+
+export class WalletBuyRequest {
+  bb: flatbuffers.ByteBuffer|null = null;
+  bb_pos = 0;
+  __init(i:number, bb:flatbuffers.ByteBuffer):WalletBuyRequest {
+  this.bb_pos = i;
+  this.bb = bb;
+  return this;
+}
+
+static getRootAsWalletBuyRequest(bb:flatbuffers.ByteBuffer, obj?:WalletBuyRequest):WalletBuyRequest {
+  return (obj || new WalletBuyRequest()).__init(bb.readInt32(bb.position()) + bb.position(), bb);
+}
+
+static getSizePrefixedRootAsWalletBuyRequest(bb:flatbuffers.ByteBuffer, obj?:WalletBuyRequest):WalletBuyRequest {
+  bb.setPosition(bb.position() + flatbuffers.SIZE_PREFIX_LENGTH);
+  return (obj || new WalletBuyRequest()).__init(bb.readInt32(bb.position()) + bb.position(), bb);
+}
+
+productId():string|null
+productId(optionalEncoding:flatbuffers.Encoding):string|Uint8Array|null
+productId(optionalEncoding?:any):string|Uint8Array|null {
+  const offset = this.bb!.__offset(this.bb_pos, 4);
+  return offset ? this.bb!.__string(this.bb_pos + offset, optionalEncoding) : null;
+}
+
+static startWalletBuyRequest(builder:flatbuffers.Builder) {
+  builder.startObject(1);
+}
+
+static addProductId(builder:flatbuffers.Builder, productIdOffset:flatbuffers.Offset) {
+  builder.addFieldOffset(0, productIdOffset, 0);
+}
+
+static endWalletBuyRequest(builder:flatbuffers.Builder):flatbuffers.Offset {
+  const offset = builder.endObject();
+  return offset;
+}
+
+static createWalletBuyRequest(builder:flatbuffers.Builder, productIdOffset:flatbuffers.Offset):flatbuffers.Offset {
+  WalletBuyRequest.startWalletBuyRequest(builder);
+  WalletBuyRequest.addProductId(builder, productIdOffset);
+  return WalletBuyRequest.endWalletBuyRequest(builder);
+}
+}

ui/src/gen/fbs/scrabblefb/wallet-segment.ts

@@ -0,0 +1,68 @@
+// automatically generated by the FlatBuffers compiler, do not modify
+
+import * as flatbuffers from 'flatbuffers';
+
+export class WalletSegment {
+  bb: flatbuffers.ByteBuffer|null = null;
+  bb_pos = 0;
+  __init(i:number, bb:flatbuffers.ByteBuffer):WalletSegment {
+  this.bb_pos = i;
+  this.bb = bb;
+  return this;
+}
+
+static getRootAsWalletSegment(bb:flatbuffers.ByteBuffer, obj?:WalletSegment):WalletSegment {
+  return (obj || new WalletSegment()).__init(bb.readInt32(bb.position()) + bb.position(), bb);
+}
+
+static getSizePrefixedRootAsWalletSegment(bb:flatbuffers.ByteBuffer, obj?:WalletSegment):WalletSegment {
+  bb.setPosition(bb.position() + flatbuffers.SIZE_PREFIX_LENGTH);
+  return (obj || new WalletSegment()).__init(bb.readInt32(bb.position()) + bb.position(), bb);
+}
+
+source():string|null
+source(optionalEncoding:flatbuffers.Encoding):string|Uint8Array|null
+source(optionalEncoding?:any):string|Uint8Array|null {
+  const offset = this.bb!.__offset(this.bb_pos, 4);
+  return offset ? this.bb!.__string(this.bb_pos + offset, optionalEncoding) : null;
+}
+
+chips():number {
+  const offset = this.bb!.__offset(this.bb_pos, 6);
+  return offset ? this.bb!.readInt32(this.bb_pos + offset) : 0;
+}
+
+spendable():boolean {
+  const offset = this.bb!.__offset(this.bb_pos, 8);
+  return offset ? !!this.bb!.readInt8(this.bb_pos + offset) : false;
+}
+
+static startWalletSegment(builder:flatbuffers.Builder) {
+  builder.startObject(3);
+}
+
+static addSource(builder:flatbuffers.Builder, sourceOffset:flatbuffers.Offset) {
+  builder.addFieldOffset(0, sourceOffset, 0);
+}
+
+static addChips(builder:flatbuffers.Builder, chips:number) {
+  builder.addFieldInt32(1, chips, 0);
+}
+
+static addSpendable(builder:flatbuffers.Builder, spendable:boolean) {
+  builder.addFieldInt8(2, +spendable, +false);
+}
+
+static endWalletSegment(builder:flatbuffers.Builder):flatbuffers.Offset {
+  const offset = builder.endObject();
+  return offset;
+}
+
+static createWalletSegment(builder:flatbuffers.Builder, sourceOffset:flatbuffers.Offset, chips:number, spendable:boolean):flatbuffers.Offset {
+  WalletSegment.startWalletSegment(builder);
+  WalletSegment.addSource(builder, sourceOffset);
+  WalletSegment.addChips(builder, chips);
+  WalletSegment.addSpendable(builder, spendable);
+  return WalletSegment.endWalletSegment(builder);
+}
+}

ui/src/gen/fbs/scrabblefb/wallet.ts

@@ -0,0 +1,96 @@
+// automatically generated by the FlatBuffers compiler, do not modify
+
+import * as flatbuffers from 'flatbuffers';
+
+import { WalletSegment } from '../scrabblefb/wallet-segment.js';
+
+
+export class Wallet {
+  bb: flatbuffers.ByteBuffer|null = null;
+  bb_pos = 0;
+  __init(i:number, bb:flatbuffers.ByteBuffer):Wallet {
+  this.bb_pos = i;
+  this.bb = bb;
+  return this;
+}
+
+static getRootAsWallet(bb:flatbuffers.ByteBuffer, obj?:Wallet):Wallet {
+  return (obj || new Wallet()).__init(bb.readInt32(bb.position()) + bb.position(), bb);
+}
+
+static getSizePrefixedRootAsWallet(bb:flatbuffers.ByteBuffer, obj?:Wallet):Wallet {
+  bb.setPosition(bb.position() + flatbuffers.SIZE_PREFIX_LENGTH);
+  return (obj || new Wallet()).__init(bb.readInt32(bb.position()) + bb.position(), bb);
+}
+
+segments(index: number, obj?:WalletSegment):WalletSegment|null {
+  const offset = this.bb!.__offset(this.bb_pos, 4);
+  return offset ? (obj || new WalletSegment()).__init(this.bb!.__indirect(this.bb!.__vector(this.bb_pos + offset) + index * 4), this.bb!) : null;
+}
+
+segmentsLength():number {
+  const offset = this.bb!.__offset(this.bb_pos, 4);
+  return offset ? this.bb!.__vector_len(this.bb_pos + offset) : 0;
+}
+
+adsForever():boolean {
+  const offset = this.bb!.__offset(this.bb_pos, 6);
+  return offset ? !!this.bb!.readInt8(this.bb_pos + offset) : false;
+}
+
+adsPaidUntilMs():bigint {
+  const offset = this.bb!.__offset(this.bb_pos, 8);
+  return offset ? this.bb!.readInt64(this.bb_pos + offset) : BigInt('0');
+}
+
+hints():number {
+  const offset = this.bb!.__offset(this.bb_pos, 10);
+  return offset ? this.bb!.readInt32(this.bb_pos + offset) : 0;
+}
+
+static startWallet(builder:flatbuffers.Builder) {
+  builder.startObject(4);
+}
+
+static addSegments(builder:flatbuffers.Builder, segmentsOffset:flatbuffers.Offset) {
+  builder.addFieldOffset(0, segmentsOffset, 0);
+}
+
+static createSegmentsVector(builder:flatbuffers.Builder, data:flatbuffers.Offset[]):flatbuffers.Offset {
+  builder.startVector(4, data.length, 4);
+  for (let i = data.length - 1; i >= 0; i--) {
+    builder.addOffset(data[i]!);
+  }
+  return builder.endVector();
+}
+
+static startSegmentsVector(builder:flatbuffers.Builder, numElems:number) {
+  builder.startVector(4, numElems, 4);
+}
+
+static addAdsForever(builder:flatbuffers.Builder, adsForever:boolean) {
+  builder.addFieldInt8(1, +adsForever, +false);
+}
+
+static addAdsPaidUntilMs(builder:flatbuffers.Builder, adsPaidUntilMs:bigint) {
+  builder.addFieldInt64(2, adsPaidUntilMs, BigInt('0'));
+}
+
+static addHints(builder:flatbuffers.Builder, hints:number) {
+  builder.addFieldInt32(3, hints, 0);
+}
+
+static endWallet(builder:flatbuffers.Builder):flatbuffers.Offset {
+  const offset = builder.endObject();
+  return offset;
+}
+
+static createWallet(builder:flatbuffers.Builder, segmentsOffset:flatbuffers.Offset, adsForever:boolean, adsPaidUntilMs:bigint, hints:number):flatbuffers.Offset {
+  Wallet.startWallet(builder);
+  Wallet.addSegments(builder, segmentsOffset);
+  Wallet.addAdsForever(builder, adsForever);
+  Wallet.addAdsPaidUntilMs(builder, adsPaidUntilMs);
+  Wallet.addHints(builder, hints);
+  return Wallet.endWallet(builder);
+}
+}

ui/src/lib/codec.test.ts

@@ -14,6 +14,8 @@ import {
   decodeMatchResult,
   decodeOutgoingList,
   decodeProfile,
+  decodeWallet,
+  encodeWalletBuy,
   decodeSession,
   decodeFeedbackState,
   decodeFeedbackUnread,
@@ -41,6 +43,35 @@ import {
 } from './codec';
 
 describe('codec', () => {
+  it('round-trips the wallet buy request and the wallet view', () => {
+    // buy request: product id survives the wire
+    const req = fb.WalletBuyRequest.getRootAsWalletBuyRequest(new ByteBuffer(encodeWalletBuy('prod-42')));
+    expect(req.productId()).toBe('prod-42');
+
+    // wallet response: build a Wallet payload and decode it, checking the segment vector,
+    // the spendable flag and the benefit fields (the long ms field decodes to a number).
+    const b = new Builder(128);
+    const src = b.createString('direct');
+    fb.WalletSegment.startWalletSegment(b);
+    fb.WalletSegment.addSource(b, src);
+    fb.WalletSegment.addChips(b, 120);
+    fb.WalletSegment.addSpendable(b, true);
+    const seg = fb.WalletSegment.endWalletSegment(b);
+    const segs = fb.Wallet.createSegmentsVector(b, [seg]);
+    fb.Wallet.startWallet(b);
+    fb.Wallet.addSegments(b, segs);
+    fb.Wallet.addAdsForever(b, false);
+    fb.Wallet.addAdsPaidUntilMs(b, BigInt(1_700_000_000_000));
+    fb.Wallet.addHints(b, 5);
+    b.finish(fb.Wallet.endWallet(b));
+
+    const w = decodeWallet(b.asUint8Array());
+    expect(w.segments).toEqual([{ source: 'direct', chips: 120, spendable: true }]);
+    expect(w.adsForever).toBe(false);
+    expect(w.adsPaidUntilMs).toBe(1_700_000_000_000);
+    expect(w.hints).toBe(5);
+  });
+
   it('round-trips the export-url request and response', () => {
     const req = fb.ExportUrlRequest.getRootAsExportUrlRequest(
       new ByteBuffer(

ui/src/lib/codec.ts

@@ -38,6 +38,8 @@ import type {
   MoveRecord,
   MoveResult,
   Profile,
+  Wallet,
+  WalletSegment,
   ProfileUpdate,
   PushEvent,
   Seat,
@@ -359,6 +361,33 @@ export function decodeSession(buf: Uint8Array): Session {
   return sessionFromTable(fb.Session.getRootAsSession(new ByteBuffer(buf)));
 }
 
+// encodeWalletBuy wraps the product id for a chip spend (POST /user/wallet/buy).
+export function encodeWalletBuy(productId: string): Uint8Array {
+  const b = new Builder(64);
+  const pid = b.createString(productId);
+  fb.WalletBuyRequest.startWalletBuyRequest(b);
+  fb.WalletBuyRequest.addProductId(b, pid);
+  return finish(b, fb.WalletBuyRequest.endWalletBuyRequest(b));
+}
+
+// decodeWallet reads the wallet payload: the context-visible chip segments and the
+// context-applicable benefits.
+export function decodeWallet(buf: Uint8Array): Wallet {
+  const w = fb.Wallet.getRootAsWallet(new ByteBuffer(buf));
+  const segments: WalletSegment[] = [];
+  for (let i = 0; i < w.segmentsLength(); i++) {
+    const seg = w.segments(i);
+    if (!seg) continue;
+    segments.push({ source: s(seg.source()), chips: seg.chips(), spendable: seg.spendable() });
+  }
+  return {
+    segments,
+    adsForever: w.adsForever(),
+    adsPaidUntilMs: Number(w.adsPaidUntilMs()),
+    hints: w.hints(),
+  };
+}
+
 export function decodeProfile(buf: Uint8Array): Profile {
   const p = fb.Profile.getRootAsProfile(new ByteBuffer(buf));
   return {

ui/src/lib/model.ts

@@ -152,6 +152,24 @@ export interface FeedbackState {
   reply: FeedbackReply | null;
 }
 
+/** One chip balance in the wallet: the funding source, the chip count, and whether it is
+ *  spendable in the current execution context (false for a frozen VK-iOS balance or untrusted). */
+export interface WalletSegment {
+  source: string;
+  chips: number;
+  spendable: boolean;
+}
+
+/** The user-facing wallet: the context-visible chip segments and the context-applicable
+ *  benefits (the no-ads term end as unix millis / forever flag, and the available hints). */
+export interface Wallet {
+  segments: WalletSegment[];
+  adsForever: boolean;
+  /** No-ads term end as unix milliseconds; 0 = no active term. */
+  adsPaidUntilMs: number;
+  hints: number;
+}
+
 export interface Profile {
   userId: string;
   displayName: string;