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/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;