theref-sdk 0.1.0

package/src/adapters/normalizer.ts

@@ -0,0 +1,252 @@
+import { AnyMove, NormalizedMove } from "../types";
+
+// ── Universal Move Normalizer ─────────────────────────────────────────────────
+//
+// Converts ANY input format into a human-readable string the AI judge can understand.
+// Handles: strings, numbers, objects, arrays, nested structures — everything.
+
+// ── Game-specific adapters ────────────────────────────────────────────────────
+
+/** Chess — handles algebraic, UCI, coordinate pairs, and move objects */
+function adaptChess(move: AnyMove): string | null {
+  if (typeof move === "string") {
+    // Already algebraic notation — passthrough
+    if (/^[a-h][1-8]$|^[NBRQK][a-h]?[1-8]?x?[a-h][1-8][+#]?$|^O-O(-O)?[+#]?$/.test(move)) {
+      return move;
+    }
+  }
+  if (typeof move === "object" && move !== null && !Array.isArray(move)) {
+    const m = move as Record<string, AnyMove>;
+    // { from: "e2", to: "e4" } or { from: "e2", to: "e4", promotion: "q" }
+    if (m.from && m.to) {
+      const promo = m.promotion ? `=${String(m.promotion).toUpperCase()}` : "";
+      const piece = m.piece ? `${String(m.piece).toUpperCase()} ` : "";
+      return `${piece}${m.from}${m.promotion ? "" : ""}${m.to}${promo}`.trim();
+    }
+    // { piece: "knight", from: "g1", to: "f3" }
+    if (m.piece && m.from && m.to) {
+      const pieceMap: Record<string, string> = {
+        knight: "N", bishop: "B", rook: "R", queen: "Q", king: "K", pawn: "",
+      };
+      const p = pieceMap[String(m.piece).toLowerCase()] ?? "";
+      return `${p}${m.to}`;
+    }
+    // UCI format { uci: "e2e4" }
+    if (m.uci && typeof m.uci === "string") {
+      return `${m.uci.slice(0, 2)}-${m.uci.slice(2, 4)}`;
+    }
+  }
+  // Coordinate array [fromFile, fromRank, toFile, toRank] e.g. [4,1,4,3]
+  if (Array.isArray(move) && move.length === 4 && move.every(n => typeof n === "number")) {
+    const files = "abcdefgh";
+    return `${files[move[0] as number]}${(move[1] as number) + 1}-${files[move[2] as number]}${(move[3] as number) + 1}`;
+  }
+  return null;
+}
+
+/** Rock Paper Scissors — normalizes any RPS variant */
+function adaptRPS(move: AnyMove): string | null {
+  const choices: Record<string, string> = {
+    rock: "Rock", paper: "Paper", scissors: "Scissors",
+    r: "Rock", p: "Paper", s: "Scissors",
+    "0": "Rock", "1": "Paper", "2": "Scissors",
+    stone: "Rock", shears: "Scissors",
+    lizard: "Lizard", spock: "Spock", // RPSLS variant
+  };
+  if (typeof move === "string") {
+    const normalized = choices[move.toLowerCase().trim()];
+    if (normalized) return normalized;
+  }
+  if (typeof move === "number") {
+    const normalized = choices[String(move)];
+    if (normalized) return normalized;
+  }
+  if (typeof move === "object" && !Array.isArray(move) && move !== null) {
+    const m = move as Record<string, AnyMove>;
+    const choice = m.choice ?? m.action ?? m.move ?? m.pick;
+    if (choice) return adaptRPS(choice);
+  }
+  return null;
+}
+
+/** Combat games — RPG attacks, fighting games, card games */
+function adaptCombat(move: AnyMove): string | null {
+  if (typeof move === "object" && !Array.isArray(move) && move !== null) {
+    const m = move as Record<string, AnyMove>;
+    const parts: string[] = [];
+
+    // Who is doing what
+    if (m.player || m.character || m.unit) {
+      parts.push(String(m.player ?? m.character ?? m.unit));
+    }
+
+    // Action
+    const action = m.action ?? m.move ?? m.skill ?? m.ability ?? m.attack ?? m.spell ?? m.card;
+    if (action) parts.push(`uses ${action}`);
+
+    // Target
+    const target = m.target ?? m.enemy ?? m.opponent;
+    if (target) parts.push(`on ${target}`);
+
+    // Modifiers
+    if (m.power !== undefined)    parts.push(`(power: ${m.power})`);
+    if (m.damage !== undefined)   parts.push(`(damage: ${m.damage})`);
+    if (m.mana_cost !== undefined) parts.push(`(mana: ${m.mana_cost})`);
+    if (m.combo)                  parts.push(`via combo: ${Array.isArray(m.combo) ? (m.combo as AnyMove[]).join("+") : m.combo}`);
+    if (m.type)                   parts.push(`[${m.type} type]`);
+    if (m.element)                parts.push(`[${m.element}]`);
+    if (m.special)                parts.push(`special: ${m.special}`);
+    if (m.position)               parts.push(`at ${JSON.stringify(m.position)}`);
+
+    if (parts.length > 0) return parts.join(" ");
+  }
+  return null;
+}
+
+/** Strategy/board game moves */
+function adaptStrategy(move: AnyMove): string | null {
+  if (typeof move === "object" && !Array.isArray(move) && move !== null) {
+    const m = move as Record<string, AnyMove>;
+    const parts: string[] = [];
+
+    const action = m.action ?? m.command ?? m.order;
+    if (action) parts.push(String(action));
+
+    const unit = m.unit ?? m.piece ?? m.troop ?? m.building;
+    if (unit) parts.push(String(unit));
+
+    if (m.from && m.to) {
+      parts.push(`from ${JSON.stringify(m.from)} to ${JSON.stringify(m.to)}`);
+    } else if (m.position ?? m.target ?? m.location) {
+      parts.push(`at ${JSON.stringify(m.position ?? m.target ?? m.location)}`);
+    }
+
+    if (m.attack) parts.push(`attacking with ${m.attack}`);
+    if (m.defend) parts.push(`defending with ${m.defend}`);
+    if (m.resource !== undefined) parts.push(`(cost: ${m.resource})`);
+
+    if (parts.length > 0) return parts.join(" ");
+  }
+  return null;
+}
+
+/** Trivia / Q&A — any answer format */
+function adaptTrivia(move: AnyMove): string | null {
+  if (typeof move === "object" && !Array.isArray(move) && move !== null) {
+    const m = move as Record<string, AnyMove>;
+    const answer = m.answer ?? m.response ?? m.text ?? m.value;
+    if (answer !== undefined) return String(answer);
+  }
+  return null;
+}
+
+/** Debate / argument */
+function adaptDebate(move: AnyMove): string | null {
+  if (typeof move === "object" && !Array.isArray(move) && move !== null) {
+    const m = move as Record<string, AnyMove>;
+    const parts: string[] = [];
+    if (m.position)  parts.push(`Position: ${m.position}`);
+    if (m.argument)  parts.push(`Argument: ${m.argument}`);
+    if (m.evidence)  parts.push(`Evidence: ${m.evidence}`);
+    if (m.rebuttal)  parts.push(`Rebuttal: ${m.rebuttal}`);
+    if (parts.length > 0) return parts.join(". ");
+  }
+  return null;
+}
+
+// ── Generic deep object flattener ─────────────────────────────────────────────
+
+function flattenObject(obj: Record<string, AnyMove>, prefix = ""): string {
+  return Object.entries(obj)
+    .map(([key, val]) => {
+      const label = prefix ? `${prefix}.${key}` : key;
+      if (val === null || val === undefined) return null;
+      if (typeof val === "object" && !Array.isArray(val)) {
+        return flattenObject(val as Record<string, AnyMove>, label);
+      }
+      if (Array.isArray(val)) {
+        return `${label}: [${(val as AnyMove[]).map(v => String(v)).join(", ")}]`;
+      }
+      return `${label}: ${val}`;
+    })
+    .filter(Boolean)
+    .join(", ");
+}
+
+// ── Main normalizer ───────────────────────────────────────────────────────────
+
+export function normalizeMove(move: AnyMove, gameHint?: string): NormalizedMove {
+  // 1. Already a string — use directly
+  if (typeof move === "string") {
+    return { raw: move, text: move.trim(), adapter: "passthrough" };
+  }
+
+  // 2. Number — convert to string
+  if (typeof move === "number") {
+    return { raw: move, text: String(move), adapter: "number" };
+  }
+
+  // 3. Boolean
+  if (typeof move === "boolean") {
+    return { raw: move, text: move ? "Yes" : "No", adapter: "boolean" };
+  }
+
+  // 4. Null/undefined
+  if (move === null || move === undefined) {
+    return { raw: move as AnyMove, text: "No move", adapter: "null" };
+  }
+
+  const hint = gameHint?.toLowerCase() ?? "";
+
+  // 5. Try game-specific adapters based on hint
+  if (hint.includes("chess")) {
+    const result = adaptChess(move);
+    if (result) return { raw: move, text: result, adapter: "chess" };
+  }
+  if (hint.includes("rock") || hint.includes("rps") || hint.includes("scissors")) {
+    const result = adaptRPS(move);
+    if (result) return { raw: move, text: result, adapter: "rps" };
+  }
+  if (hint.includes("trivia") || hint.includes("quiz") || hint.includes("question")) {
+    const result = adaptTrivia(move);
+    if (result) return { raw: move, text: result, adapter: "trivia" };
+  }
+  if (hint.includes("debate") || hint.includes("argument")) {
+    const result = adaptDebate(move);
+    if (result) return { raw: move, text: result, adapter: "debate" };
+  }
+
+  // 6. Auto-detect from structure — try all adapters
+  if (typeof move === "object") {
+    const chess = adaptChess(move);
+    if (chess) return { raw: move, text: chess, adapter: "chess" };
+
+    const rps = adaptRPS(move);
+    if (rps) return { raw: move, text: rps, adapter: "rps" };
+
+    const combat = adaptCombat(move);
+    if (combat) return { raw: move, text: combat, adapter: "combat" };
+
+    const strategy = adaptStrategy(move);
+    if (strategy) return { raw: move, text: strategy, adapter: "strategy" };
+
+    const trivia = adaptTrivia(move);
+    if (trivia) return { raw: move, text: trivia, adapter: "trivia" };
+
+    const debate = adaptDebate(move);
+    if (debate) return { raw: move, text: debate, adapter: "debate" };
+
+    // 7. Array — join elements
+    if (Array.isArray(move)) {
+      const text = (move as AnyMove[]).map(m => normalizeMove(m).text).join(", ");
+      return { raw: move, text, adapter: "array" };
+    }
+
+    // 8. Generic object — flatten to readable string
+    const flat = flattenObject(move as Record<string, AnyMove>);
+    return { raw: move, text: flat, adapter: "generic-object" };
+  }
+
+  // 9. Absolute fallback
+  return { raw: move, text: String(move), adapter: "fallback" };
+}

package/src/client/TheRefClient.ts

@@ -0,0 +1,444 @@
+import { createClient, createAccount, generatePrivateKey, chains } from "genlayer-js";
+import { TransactionStatus } from "genlayer-js/types";
+import {
+  TheRefConfig, NetworkConfig, GameState, GameStatus,
+  CreateGameOptions, JudgmentResult, RoundResult,
+  CreateTournamentOptions, Tournament, BracketMatch,
+  LeaderboardEntry, PlayerStats, PlayerType, AnyMove,
+} from "../types";
+import { resolveNetwork, gidToNum, DEFAULT_WS_URL } from "../utils/networks";
+import { normalizeMove } from "../adapters/normalizer";
+
+// ── Client ────────────────────────────────────────────────────────────────────
+
+export class TheRefClient {
+  private network:      NetworkConfig;
+  private glClient:     ReturnType<typeof createClient>;
+  private retries:      number;
+  private pollInterval: number;
+  private wsUrl:        string;
+
+  constructor(config: TheRefConfig) {
+    this.network      = resolveNetwork(config.network);
+    this.retries      = config.retries ?? 300;
+    this.pollInterval = config.pollInterval ?? 5000;
+    this.wsUrl        = config.wsUrl ?? DEFAULT_WS_URL;
+
+    // Select the correct built-in chain
+    const chain = this.network.chainId === 4221
+      ? chains.testnetBradbury
+      : chains.studionet;
+
+    // Build account — private key for agents, wallet address for browser
+    let account: any;
+    if (config.privateKey) {
+      account = createAccount(config.privateKey);
+    } else if (config.walletAddress) {
+      account = config.walletAddress; // SDK routes through window.ethereum
+    } else {
+      // Dev mode — generate ephemeral key
+      account = createAccount(generatePrivateKey());
+    }
+
+    this.glClient = createClient({
+      chain,
+      endpoint: this.network.rpc,
+      account,
+    });
+  }
+
+  // ── Internal helpers ────────────────────────────────────────────────────────
+
+  private async write(
+    address: string,
+    method:  string,
+    args:    any[],
+    value:   bigint = 0n,
+  ): Promise<{ payload: string; txHash: string }> {
+    const tx = await this.glClient.writeContract({
+      address:      address as `0x${string}`,
+      functionName: method,
+      args:         args as any,
+      value,
+    });
+
+    const receipt = await this.glClient.waitForTransactionReceipt({
+      hash:    tx as any,
+      status:  TransactionStatus.ACCEPTED,
+      retries: this.retries,
+    });
+
+    const leader  = (receipt as any)?.consensus_data?.leader_receipt?.[0];
+    const payload = String(
+      leader?.result?.payload?.readable ??
+      (receipt as any)?.data?.result ?? ""
+    ).replace(/^"|"$/g, "");
+
+    return { payload, txHash: String(tx) };
+  }
+
+  private async read(
+    address: string,
+    method:  string,
+    args:    any[] = [],
+  ): Promise<unknown> {
+    return this.glClient.readContract({
+      address:      address as `0x${string}`,
+      functionName: method,
+      args:         args as any,
+    });
+  }
+
+  private get CORE() { return this.network.addresses.CORE; }
+  private get LB()   { return this.network.addresses.LB;   }
+  private get TRN()  { return this.network.addresses.TRN;  }
+
+  private mapGameState(raw: any): GameState {
+    return {
+      gameId:        raw.game_id        ?? "",
+      gameName:      raw.game_name      ?? "",
+      status:        raw.status         ?? "waiting",
+      player1:       raw.player1        ?? "",
+      player2:       raw.player2        ?? "",
+      agent1:        raw.agent1         ?? "",
+      agent2:        raw.agent2         ?? "",
+      maxRounds:     Number(raw.max_rounds     ?? 0),
+      roundCount:    Number(raw.round_count    ?? 0),
+      judgedThrough: Number(raw.judged_through ?? 0),
+      rules:         raw.rules          ?? "",
+      winner:        raw.winner         ?? "",
+      score:         raw.score          ?? {},
+      playerTypes:   raw.player_types   ?? {},
+      caller:        raw.caller         ?? "",
+      rounds: (raw.rounds ?? []).map((r: any) => ({
+        roundNumber:   r.round_number,
+        movePlayer1:   r.move_player1   ?? "",
+        movePlayer2:   r.move_player2   ?? "",
+        result:        r.result         ?? "pending",
+        reasonType:    r.reason_type    ?? "normal",
+        invalidPlayer: r.invalid_player ?? "none",
+        reasoning:     r.reasoning      ?? "",
+        confidence:    Number(r.confidence ?? 0),
+        status:        r.status         ?? "pending",
+      })),
+    };
+  }
+
+  // ── Game API ────────────────────────────────────────────────────────────────
+
+  /**
+   * Create a new game. Returns the game ID.
+   */
+  async createGame(options: CreateGameOptions): Promise<string> {
+    const { payload } = await this.write(this.CORE, "start_game", [
+      options.name,
+      options.visibility ?? "public",
+      options.maxRounds  ?? 3,
+      options.rules      ?? "",
+      options.player1,
+      options.player2    ?? "",
+      options.agent1     ?? 0,
+      options.agent2     ?? 0,
+    ]);
+    return payload;
+  }
+
+  /**
+   * Submit a move for a player. Accepts ANY move format — string, object, array, etc.
+   * The SDK automatically normalizes it to a string the AI judge can understand.
+   */
+  async submitMove(
+    gameId:     string,
+    playerName: string,
+    move:       AnyMove,
+    gameHint?:  string,   // optional game name hint for better normalization
+  ): Promise<{ txHash: string; normalizedMove: string }> {
+    const normalized = normalizeMove(move, gameHint);
+    const { txHash } = await this.write(this.CORE, "submit_move", [
+      gidToNum(gameId),
+      playerName,
+      normalized.text,
+    ]);
+    return { txHash, normalizedMove: normalized.text };
+  }
+
+  /**
+   * Judge the game — triggers AI consensus on all pending rounds.
+   */
+  async judgeGame(gameId: string): Promise<JudgmentResult> {
+    const { payload, txHash } = await this.write(
+      this.CORE, "judge_game", [gidToNum(gameId)]
+    );
+    const state = await this.getGameState(gameId);
+    return {
+      winner:  state.winner,
+      isDraw:  state.status === "draw",
+      score:   state.score,
+      rounds:  state.rounds,
+      txHash,
+      payload,
+    };
+  }
+
+  /**
+   * End an open-ended game (max_rounds = 0). Only callable by the game creator.
+   */
+  async endGame(gameId: string): Promise<JudgmentResult> {
+    const { payload, txHash } = await this.write(
+      this.CORE, "end_game", [gidToNum(gameId)]
+    );
+    const state = await this.getGameState(gameId);
+    return {
+      winner:  state.winner,
+      isDraw:  state.status === "draw",
+      score:   state.score,
+      rounds:  state.rounds,
+      txHash,
+      payload,
+    };
+  }
+
+  /**
+   * Get the full game state.
+   */
+  async getGameState(gameId: string): Promise<GameState> {
+    const raw = await this.read(this.CORE, "get_game_state", [gameId]);
+    return this.mapGameState(raw);
+  }
+
+  /**
+   * Get all active games.
+   */
+  async getActiveGames(): Promise<GameState[]> {
+    const raw = await this.read(this.CORE, "get_active_games") as any[];
+    return (raw ?? []).map(this.mapGameState);
+  }
+
+  /**
+   * Get total number of games.
+   */
+  async getTotalGames(): Promise<number> {
+    const result = await this.read(this.CORE, "get_total_games");
+    return Number(result ?? 0);
+  }
+
+  // ── Polling helpers ─────────────────────────────────────────────────────────
+
+  /**
+   * Wait until both players have submitted their move for a given round.
+   * Polls every `pollInterval` ms.
+   */
+  async waitForBothMoves(gameId: string, roundNumber: number): Promise<RoundResult> {
+    while (true) {
+      const state = await this.getGameState(gameId);
+      const round = state.rounds.find(r => r.roundNumber === roundNumber);
+      if (round?.movePlayer1 && round?.movePlayer2) return round;
+      await this.sleep(this.pollInterval);
+    }
+  }
+
+  /**
+   * Wait until the opponent has submitted their move for a round.
+   * isPlayer1: true if you are player1, false if player2.
+   */
+  async waitForOpponentMove(
+    gameId:     string,
+    roundNumber: number,
+    isPlayer1:  boolean,
+  ): Promise<string> {
+    while (true) {
+      const state = await this.getGameState(gameId);
+      const round = state.rounds.find(r => r.roundNumber === roundNumber);
+      const opponentMove = isPlayer1 ? round?.movePlayer2 : round?.movePlayer1;
+      if (opponentMove) return opponentMove;
+      await this.sleep(this.pollInterval);
+    }
+  }
+
+  /**
+   * Wait until the game reaches a specific status.
+   */
+  async waitForStatus(gameId: string, status: GameStatus): Promise<GameState> {
+    while (true) {
+      const state = await this.getGameState(gameId);
+      if (state.status === status) return state;
+      if (state.status === "completed" || state.status === "draw") return state;
+      await this.sleep(this.pollInterval);
+    }
+  }
+
+  /**
+   * Play a full game automatically.
+   * moveFn is called for each round — return your move in any format.
+   */
+  async playGame(
+    gameId:     string,
+    playerName: string,
+    isPlayer1:  boolean,
+    moveFn:     (state: GameState, round: number) => Promise<AnyMove>,
+    gameHint?:  string,
+  ): Promise<JudgmentResult> {
+    let state = await this.getGameState(gameId);
+    const maxRounds = state.maxRounds || 999;
+
+    for (let round = 1; round <= maxRounds; round++) {
+      state = await this.getGameState(gameId);
+      if (state.status !== "active") break;
+
+      // Wait for opponent first if we're player2
+      if (!isPlayer1) {
+        await this.waitForOpponentMove(gameId, round, false);
+      }
+
+      // Generate and submit our move
+      state = await this.getGameState(gameId);
+      const move = await moveFn(state, round);
+      await this.submitMove(gameId, playerName, move, gameHint);
+
+      // Wait for opponent if we're player1
+      if (isPlayer1) {
+        await this.waitForOpponentMove(gameId, round, true);
+      }
+
+      // Check if max rounds reached
+      state = await this.getGameState(gameId);
+      if (state.roundCount >= maxRounds) break;
+    }
+
+    return this.judgeGame(gameId);
+  }
+
+  // ── Leaderboard API ─────────────────────────────────────────────────────────
+
+  async getLeaderboard(
+    gameName:   string,
+    playerType: PlayerType | "all" = "all",
+  ): Promise<LeaderboardEntry[]> {
+    const raw = await this.read(this.LB, "get_leaderboard", [gameName, playerType]) as any[];
+    return (raw ?? []).map(e => ({
+      player:     e.player     ?? "",
+      wins:       Number(e.wins   ?? 0),
+      losses:     Number(e.losses ?? 0),
+      draws:      Number(e.draws  ?? 0),
+      score:      Number(e.score  ?? 0),
+      playerType: (e.player_type ?? "human") as PlayerType,
+    }));
+  }
+
+  async getTopPlayers(gameName: string, n = 10): Promise<LeaderboardEntry[]> {
+    const raw = await this.read(this.LB, "get_top_players", [gameName, n]) as any[];
+    return (raw ?? []).map(e => ({
+      player:     e.player     ?? "",
+      wins:       Number(e.wins   ?? 0),
+      losses:     Number(e.losses ?? 0),
+      draws:      Number(e.draws  ?? 0),
+      score:      Number(e.score  ?? 0),
+      playerType: (e.player_type ?? "human") as PlayerType,
+    }));
+  }
+
+  async getPlayerStats(
+    gameName:   string,
+    playerName: string,
+    playerType: PlayerType | "all" = "all",
+  ): Promise<PlayerStats | null> {
+    try {
+      const raw = await this.read(this.LB, "get_player_stats", [gameName, playerName, playerType]) as any;
+      if (!raw) return null;
+      return {
+        player:     raw.player     ?? playerName,
+        wins:       Number(raw.wins   ?? 0),
+        losses:     Number(raw.losses ?? 0),
+        draws:      Number(raw.draws  ?? 0),
+        score:      Number(raw.score  ?? 0),
+        games:      Number(raw.games  ?? 0),
+        playerType: (raw.player_type ?? playerType) as PlayerType,
+      };
+    } catch { return null; }
+  }
+
+  // ── Tournament API ──────────────────────────────────────────────────────────
+
+  async createTournament(options: CreateTournamentOptions): Promise<string> {
+    const { payload } = await this.write(this.TRN, "create_tournament", [
+      options.name,
+      options.gameName,
+      options.format,
+      options.maxPlayers,
+      0,                          // entry fee — always free
+      options.prizeSplit ?? [70, 30],
+      options.rules      ?? "",
+      options.roundsPerMatch ?? 1,
+    ]);
+    return payload;
+  }
+
+  async joinTournament(
+    tid:        string,
+    playerName: string,
+    playerType: PlayerType = "human",
+  ): Promise<void> {
+    await this.write(this.TRN, "join_tournament", [tid, playerName, playerType]);
+  }
+
+  async startTournament(tid: string): Promise<void> {
+    await this.write(this.TRN, "start_tournament", [tid]);
+  }
+
+  async getTournament(tid: string): Promise<Tournament | null> {
+    try {
+      const raw = await this.read(this.TRN, "get_tournament", [tid]) as any;
+      if (!raw) return null;
+      return {
+        tid:        raw.tid        ?? tid,
+        name:       raw.name       ?? "",
+        gameName:   raw.game_name  ?? "",
+        format:     raw.format     ?? "",
+        maxPlayers: Number(raw.max_players ?? 0),
+        status:     raw.status     ?? "",
+        players:    raw.players    ?? [],
+        bracket:    (raw.bracket   ?? []).map((m: any) => ({
+          matchId: m.match_id,
+          round:   m.round,
+          player1: m.player1,
+          player2: m.player2,
+          gameId:  m.game_id,
+          winner:  m.winner,
+          status:  m.status,
+        })),
+        winner: raw.winner ?? "",
+      };
+    } catch { return null; }
+  }
+
+  async listTournaments(): Promise<Tournament[]> {
+    const raw = await this.read(this.TRN, "list_tournaments") as any[];
+    return (raw ?? []).map(t => ({
+      tid:        t.tid        ?? "",
+      name:       t.name       ?? "",
+      gameName:   t.game_name  ?? "",
+      format:     t.format     ?? "",
+      maxPlayers: Number(t.max_players ?? 0),
+      status:     t.status     ?? "",
+      players:    t.players    ?? [],
+      bracket:    [],
+      winner:     t.winner     ?? "",
+    }));
+  }
+
+  async recordMatchResult(tid: string, matchId: number, winner: string): Promise<void> {
+    await this.write(this.TRN, "record_match_result", [tid, matchId, winner]);
+  }
+
+  // ── Utils ───────────────────────────────────────────────────────────────────
+
+  /** Normalize any move to a string without submitting */
+  normalizeMove(move: AnyMove, gameHint?: string) {
+    return normalizeMove(move, gameHint);
+  }
+
+  /** Sleep helper */
+  private sleep(ms: number) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}