La demo final: arena, puzles y tu propio modelo desde el disco

/** The three things the screen can do: play the model, watch two stages play, solve puzzles. */
export type Mode = 'play' | 'arena' | 'puzzles';
export const MODES: readonly Mode[] = ['play', 'arena', 'puzzles'];

export interface Query {
  mock: boolean;
  stage: string;
  /** Encoder stage the evaluation bar would load; nothing is fetched until its own consent. */
  encoder: string;
  color: Color;
  mode: Mode;
  /** A position to start from (`?fen=`), when it parses; null otherwise. */
  fen: string | null;
  /** The second stage of the arena (`?vs=`), when it is a known stage. */
  vs: string | null;
}

export function parseQuery(
  search: string,
  fallback = defaultStageId(detectConditions()),
  encoderFallback = defaultEncoderId(detectConditions()),
): Query {
  const params = new URLSearchParams(search.startsWith('?') ? search.slice(1) : search);
  const requested = params.get('stage') ?? fallback;
  const stage = findStage(requested) ?? findStage(fallback);
  const mock = params.get('mock') === '1' || stage === undefined || stage.kind === 'mock';
  const encoder = findEncoderStage(params.get('encoder') ?? encoderFallback);
  const mode = params.get('mode');
  const vs = params.get('vs');
  return {
    mock,
    stage: mock ? 'mock' : (stage?.id ?? fallback),
    encoder: encoder?.id ?? encoderFallback,
    color: params.get('color') === 'b' ? 'b' : 'w',
    mode: mode !== null && (MODES as readonly string[]).includes(mode) ? (mode as Mode) : 'play',
    fen: validFen(params.get('fen')),
    vs: vs !== null && findStage(vs) ? vs : null,
  };
}

/** `fen` when chess.js accepts it as a position, else null. */
export function validFen(fen: string | null): string | null {
  if (!fen) return null;
  try {
    return new Chess(fen).fen();
  } catch {
    return null;
  }
}

/**
 * Arena: two stages play each other in the browser, and the difference is read off the games.
 *
 * The arithmetic is `rukh.eval.match` (M5) ported line for line: every opening is played twice
 * with the colours swapped, the score is A's points over both games, the Elo difference is
 * `400·log10(p / (1 - p))` and its interval comes from a bootstrap over the games. A match
 * measures a **difference** and nothing else: there is no third party here whose mood has to be
 * averaged (D-110), and the number is not a strength.
 *
 * Everything here is pure, so `tests/arena.test.ts` can pin the numbers against the Python
 * implementation without a model in sight.
 */

/** How many plies the random openings have; six, as `rukh eval match` does by default. */
export const OPENING_PLIES = 6;
/** A game that reaches this many plies without a result counts as a draw, and is marked cut. */
export const MAX_PLIES = 300;

/** A small, seeded PRNG so a run with the same seed plays the same openings. */
export function mulberry32(seed: number): () => number {
  let state = seed >>> 0;
  return () => {
    state = (state + 0x6d2b79f5) >>> 0;
    let t = state;
    t = Math.imul(t ^ (t >>> 15), t | 1);
    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
  };
}

/** A random legal opening of `plies` moves in UCI; retried when it ends the game early. */
export function randomOpening(random: () => number, plies = OPENING_PLIES): string[] {
  for (;;) {
    const chess = new Chess();
    const moves: string[] = [];
    for (let i = 0; i < plies; i += 1) {
      const legal = chess.moves({ verbose: true });
      if (legal.length === 0) break;
      const pick = legal[Math.floor(random() * legal.length)];
      chess.move(pick);
      moves.push(`${pick.from}${pick.to}${pick.promotion ?? ''}`);
    }
    if (moves.length === plies && !chess.isGameOver()) return moves;
  }
}

/** `pairs` openings, each to be played twice with the colours swapped. */
export function openingBook(pairs: number, seed: number, plies = OPENING_PLIES): string[][] {
  const random = mulberry32(seed);
  return Array.from({ length: pairs }, () => randomOpening(random, plies));
}

export interface ArenaGame {
  /** Index in the schedule: game `2k` has A as White on opening `k`, game `2k+1` swaps. */
  index: number;
  opening: string[];
  aWhite: boolean;
  /** A's points: 1, 0.5 or 0. */
  score: number;
  plies: number;
  /** True when the game hit `MAX_PLIES` and was scored as a draw. */
  cut: boolean;
}

export interface ArenaSummary {
  games: number;
  /** A's points over all games, as a fraction. */
  score: number;
  wins: number;
  draws: number;
  losses: number;
  cut: number;
  /** A minus B in Elo, from the score; null until a game has been played. */
  elo: number | null;
  /** 95 % bootstrap interval of `elo`; null with fewer than two games. */
  low: number | null;
  high: number | null;
  /** True when the interval does not contain zero. */
  separated: boolean;
}

/** Elo difference that explains a score, clipped away from 0 and 1 as the harness does. */
export function eloDifference(score: number): number {
  const p = Math.min(Math.max(score, 0.001), 0.999);
  return 400 * Math.log10(p / (1 - p));
}

/**
 * Percentile bootstrap of the Elo difference over the games (`samples` resamples, seeded).
 * The same estimator as `rukh.eval.match.bootstrap_interval`: resample games with replacement,
 * recompute the score, convert.
 */
export function bootstrapElo(
  scores: readonly number[],
  samples = 500,
  seed = 0,
): { low: number; high: number } | null {
  if (scores.length < 2) return null;
  const random = mulberry32(seed);
  const draws: number[] = [];
  for (let s = 0; s < samples; s += 1) {
    let total = 0;
    for (let i = 0; i < scores.length; i += 1) {
      total += scores[Math.floor(random() * scores.length)];
    }
    draws.push(eloDifference(total / scores.length));
  }
  draws.sort((a, b) => a - b);
  const at = (q: number) => draws[Math.min(draws.length - 1, Math.floor(q * draws.length))];
  return { low: at(0.025), high: at(0.975) };
}

export function summarize(games: readonly ArenaGame[], seed = 0): ArenaSummary {
  const scores = games.map((game) => game.score);
  const points = scores.reduce((sum, value) => sum + value, 0);
  const score = games.length > 0 ? points / games.length : 0;
  const interval = bootstrapElo(scores, 500, seed);
  return {
    games: games.length,
    score,
    wins: scores.filter((value) => value === 1).length,
    draws: scores.filter((value) => value === 0.5).length,
    losses: scores.filter((value) => value === 0).length,
    cut: games.filter((game) => game.cut).length,
    elo: games.length > 0 ? eloDifference(score) : null,
    low: interval?.low ?? null,
    high: interval?.high ?? null,
    separated: interval !== null && (interval.low > 0 || interval.high < 0),
  };
}

/** The result of a finished game from A's point of view, given who had White. */
export function scoreFor(result: string | null, aWhite: boolean): number {
  if (result === '1-0') return aWhite ? 1 : 0;
  if (result === '0-1') return aWhite ? 0 : 1;
  return 0.5;
}

/** How many games the match needs to call an edge of `elo` points at 95 % (`labs/m5`). */
export function gamesNeeded(elo: number): number {
  const p = 1 / (1 + 10 ** (-Math.abs(elo) / 400));
  const z = 1.959963985;
  return Math.ceil((z * z * p * (1 - p)) / (p - 0.5) ** 2);
}

/**
 * Live puzzles: the harness's puzzle criterion (`rukh.eval.puzzles`), in the browser.
 *
 * A puzzle is attempted the way the table measured it (D-053): the model is prompted with the
 * **real game** that led to the position, with the players' own ratings in the header, and it
 * has to find the **whole** line, not the first move. `moves[0]` is the opponent's move that
 * sets the puzzle (Lichess's convention), then the sides alternate; the model answers the odd
 * indices and the opponent's replies are played from the solution.
 *
 * `public/puzzles.json` is written by `labs/m6/puzzles_export.py` in the ML repository from the
 * `test` split of `chorcat/rukh-puzzles-split`, fifty per band, seeded.
 */

export interface Puzzle {
  id: string;
  fen: string;
  moves: string[];
  rating: number;
  prefix: string[];
  whiteElo: number | null;
  blackElo: number | null;
}

export interface PuzzleSet {
  schema: string;
  source: string;
  seed: number;
  perBand: number;
  generated: string;
  bands: Record<string, Puzzle[]>;
}

export const BANDS = ['1000-1500', '1500-2000', '2000+'] as const;
export type Band = (typeof BANDS)[number];

export const PUZZLES_URL = '/puzzles.json';

export async function loadPuzzleSet(
  url = PUZZLES_URL,
  fetcher: typeof fetch = fetch,
): Promise<PuzzleSet> {
  const response = await fetcher(url);
  if (!response.ok) throw new Error(`puzzles: ${response.status} ${response.statusText}`);
  const data = (await response.json()) as PuzzleSet;
  if (data.schema !== 'rukh-puzzles/1') throw new Error(`puzzles: unknown schema ${data.schema}`);
  return data;
}

/** UCI `e7e8q` as a `Move`. */
export function uciMove(uci: string): Move {
  return {
    from: uci.slice(0, 2),
    to: uci.slice(2, 4),
    promotion: (uci.slice(4, 5) || undefined) as Move['promotion'],
  };
}

/**
 * The game state the puzzle starts from: the real game replayed from the initial position, so
 * the prompt carries the prefix, and the board is the puzzle's FEN. Replaying the prefix must
 * land on that FEN (the first four fields); when it does not, the puzzle is malformed and is
 * skipped rather than attempted from a position the model never reached.
 */
export function puzzleStart(puzzle: Puzzle): GameState | null {
  const chess = new Chess();
  try {
    for (const uci of puzzle.prefix) chess.move(uciMove(uci));
  } catch {
    return null;
  }
  const reached = chess.fen().split(' ').slice(0, 4).join(' ');
  const expected = puzzle.fen.split(' ').slice(0, 4).join(' ');
  if (reached !== expected) return null;
  return {
    start: INITIAL_FEN,
    fen: chess.fen(),
    history: chess.history(),
    turn: chess.turn(),
    over: chess.isGameOver(),
    result: null,
  };
}

/** The moves the model has to find: the odd indices of the line. */
export function expectedMoves(puzzle: Puzzle): string[] {
  return puzzle.moves.filter((_, index) => index % 2 === 1);
}

export interface PuzzleAttempt {
  id: string;
  band: Band;
  rating: number;
  solved: boolean;
  /** Model moves that matched before the first miss. */
  correct: number;
  total: number;
  /** What the model proposed at the first miss (UCI), and what the line expected. */
  proposed: string | null;
  expected: string | null;
}

export interface BandProgress {
  band: Band;
  attempted: number;
  solved: number;
}

export function progressByBand(attempts: readonly PuzzleAttempt[]): BandProgress[] {
  return BANDS.map((band) => {
    const own = attempts.filter((attempt) => attempt.band === band);
    return { band, attempted: own.length, solved: own.filter((a) => a.solved).length };
  });
}

/** `12,3 %`-style rate, or an em dash before anything was attempted. */
export function rate(solved: number, attempted: number): string {
  if (attempted === 0) return '—';
  return `${((100 * solved) / attempted).toFixed(1).replace('.', ',')} %`;
}

/**
 * Playing against a model you trained yourself, from a file on your disk.
 *
 * The demo ships the models the course published, which is the wrong half of the point: somebody
 * who has just finished lab 5 of M2 has their own `artifacts/onnx/small/model-int8.onnx` and no
 * way to play it. This takes that file and makes a stage out of it.
 *
 * Nothing leaves the browser. The bytes go straight from the file picker to the worker as a
 * transferable, so there is no upload, no `fetch`, no Cache API entry and nothing to hit the
 * network with. That is also why the local stage is not remembered across reloads: a model the
 * page could restore by itself is a model a link could ask it to restore.
 *
 * What protects the reader from a bad file is the contract in `contract.ts`, which already
 * refuses a graph whose logits are not the tokenizer's 2030 moves wide. A `.onnx` that is not a
 * Rukh decoder fails there, by name, before it ever picks a move. The checks here are the cheap
 * ones that come first: shape of the name, and a ceiling on the size.
 */

  /**
   * True in the modes where nobody moves by hand (the arena, the puzzles): input is refused
   * without looking at whose turn it is, and the board says so with `data-locked`.
   */
  locked?: Signal<boolean>;

  // Keep the current ply visible once the list grows past its fixed height. Only the list
  // scrolls, never the page: `scrollIntoView` walks every scrollable ancestor, and on a
  // one-column layout that moved the document by hundreds of pixels *during* a touch, so the
  // click the browser synthesises after `touchend` landed on whatever had slid under the finger
  // (the mode switcher, once it existed). A page must not move because a move was played.
  useEffect(() => {
    const container = list.current;
    const current = container?.querySelector<HTMLElement>('.is-current');
    if (!container || !current) return;
    const box = container.getBoundingClientRect();
    const ply = current.getBoundingClientRect();
    if (ply.top < box.top) container.scrollTop += ply.top - box.top;
    else if (ply.bottom > box.bottom) container.scrollTop += ply.bottom - box.bottom;
  }, [history.length]);