// Bot and simulation types. Engine-agnostic: bots talk to the rules engine only // through EngineAdapter, so the same bots run against shared/game (see adapter.ts) // and against the toy engine used by the self-tests. Pure: no I/O. export type Seat = 0 | 1; export type Rng = () => number; export interface DeckSpec { id: string; /** Free-form tags for win-rate breakdowns: archetype, faction, keywords. */ tags: string[]; /** Whatever the engine needs to build the deck (card list, starter seed, ...). */ payload: unknown; } export interface MatchOutcome { winner: Seat | null; // null = draw reason?: string; } export interface EngineAdapter { name: string; /** Ruleset ids this adapter knows (e.g. "v1", "v1.1"). */ rulesets(): string[]; /** Decks available for matchmaking under a ruleset. */ decks(ruleset: string): DeckSpec[]; createMatch(ruleset: string, decks: [DeckSpec, DeckSpec], seed: number): S; /** Seat that must act now. */ toAct(state: S): Seat; legalActions(state: S, seat: Seat): A[]; /** Must not mutate `state`. */ applyAction(state: S, action: A): S; isOver(state: S): boolean; result(state: S): MatchOutcome; /** Turn counter (1-based, counts both players' turns). */ turn(state: S): number; /** Heuristic value of the state for `seat`, roughly in [-1, 1]. */ evaluate(state: S, seat: Seat): number; /** Card ids touched by an action (played, deployed...), for per-card stats. */ cardsOf(state: S, action: A): string[]; /** Short stable label for an action kind ("play", "pass", ...). */ actionKind(action: A): string; /** Optional card metadata (numeric stats, keywords, faction) for per-stat balance analysis. */ cardMeta?(cardId: string): Record | undefined; /** Printed power an action puts on the board (-1 for non-plays). Used by the naive maxpower bot. */ actionPower?(state: S, action: A): number; /** * Counterfactual keyword value for a finished match: for each (seat, keyword) on cards that seat played, * replay the same actions with that keyword removed from that seat's cards. `power` = own final total power * lost, `flip` = 1 if the result got worse for that seat (win->draw/loss, draw->loss), `cards` = cards played. */ keywordValues?(final: S, decks: [DeckSpec, DeckSpec]): { seat: Seat; keyword: string; power: number; flip: number; cards: number }[]; /** Seat with the first-player advantage (defaults to toAct at match start). */ firstSeat?(state: S): Seat; /** What `seat` may see (e.g. shared/game viewFor). Bots receive only this. Default: the state itself. */ observe?(state: S, seat: Seat): unknown; /** A full state consistent with an observation, hidden parts sampled with `rng` (determinization). */ assume?(observation: unknown, seat: Seat, rng: Rng): S; } /** A bot is a pure function of what its seat can see (EngineAdapter.observe). ui-b reuses it as the browser AI. */ export type BotFn = (observation: O, player: Seat, rng: Rng) => A; export interface MatchRecord { ruleset: string; seed: number; decks: [string, string]; deckTags: [string[], string[]]; bots: [string, string]; firstSeat: Seat; // seat that acted first winner: Seat | null; reason?: string; turns: number; actions: number; truncated: boolean; /** Eval for seat 0 at the start of each turn. */ evalTrace: number[]; /** Turn from which the eventual winner led on eval until the end (null for draws). */ decidedTurn: number | null; cardsPlayed: [string[], string[]]; keywordValues?: { seat: Seat; keyword: string; power: number; flip: number; cards: number }[]; actionKinds: Record; ms: number; }