@diffenderfer-games/hub 2.0.0-next.4 → 2.0.0-next.6

package/src/turns-kit/check-rules.ts

@@ -0,0 +1,182 @@
+/**
+ * The rules conformance kit (docs/multiplayer.md "Turn games: testing"):
+ * `checkTurnRules(rules, options)` plays many seeded games through a rules
+ * module the way the hub does and throws on the first broken promise:
+ *
+ * - every game reaches an outcome within `maxMoves`, and `toAct` is never
+ *   empty before it;
+ * - the state survives a JSON round trip after every move, and the same seed
+ *   plays the same game (no `Math.random`, no hidden globals);
+ * - `autoMove` (when the rules have it) is always legal;
+ * - no seat's `view` or `eventView` shows another seat's secrets: markers
+ *   planted with `options.plant` never appear in anyone else's view;
+ * - stored fixtures from older versions `migrate` to a state that views;
+ * - views, events and moves stay within the hub's size caps.
+ *
+ * It needs no hub: run it in a game's own unit tests (vitest, node:test).
+ */
+import { createTurnRng, turnRngStateFromSeed, type TurnRng, type TurnRules } from '@diffenderfer-games/hub-contract';
+import { parseJsonText } from '../core/storage/json-guards';
+
+/** The hub's caps. */
+const STATE_MAX_BYTES = 64 * 1024;
+const MOVE_MAX_BYTES = 2 * 1024;
+
+/** How to check a rules module. */
+export interface TurnRulesCheckOptions<State, Move, Options = never> {
+  /** Seat counts to play (default: 2). */
+  readonly seats?: readonly number[];
+  /** Games per seat count (default: 25). */
+  readonly games?: number;
+  /** A game that runs longer than this many moves fails (default: 2000). */
+  readonly maxMoves?: number;
+  /** Options and mode to set games up with. */
+  readonly setupOptions?: Options;
+  readonly mode?: string | null;
+  /** A legal move for `seat` (default: the rules' own `autoMove`). At least one of the two is needed. */
+  readonly randomMove?: (state: State, seat: number, rng: TurnRng) => Move;
+  /**
+   * Put `marker` somewhere only `seat` may see (a card in their hand, their
+   * secret goal) and return the state; the kit then checks no other seat's
+   * view or events ever contain it. Leave it out for a game with no hidden
+   * information.
+   */
+  readonly plant?: (state: State, seat: number, marker: string) => State;
+  /** States saved by older rules versions, which `migrate` must bring up to date. */
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: states stored by older rules versions
+  readonly fixtures?: readonly { readonly version: number; readonly state: unknown }[];
+}
+
+/** What the kit played. */
+export interface TurnRulesReport {
+  readonly games: number;
+  readonly moves: number;
+  readonly longestGame: number;
+}
+
+/** The UTF-8 bytes of a JSON text. */
+function bytesOf(json: string): number {
+  return new TextEncoder().encode(json).length;
+}
+
+/** Throw a kit failure. */
+function fail(message: string): never {
+  throw new Error(`checkTurnRules: ${message}`);
+}
+
+/** A JSON copy (what the hub stores and reads back). */
+function roundTrip<T>(value: T): T {
+  const copy = parseJsonText(JSON.stringify(value));
+  if (copy === null && value !== null) {
+    fail('a state or move is not JSON');
+  }
+  return isGamesOwn(copy, value) ? copy : fail('a state or move is not JSON');
+}
+
+/** Always true: JSON a game's rules made is read back as the game's own type (the game vouches for it, as `toGameData` does). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the game's own JSON, round-tripped
+function isGamesOwn<T>(_value: unknown, _like: T): _value is T {
+  return true;
+}
+
+/** A move for `seat`: the check's own chooser, else the rules' autoMove. */
+function pickMove<State, Move, View, Event, Options>(rules: TurnRules<State, Move, View, Event, Options>, options: TurnRulesCheckOptions<State, Move, Options>, state: State, seat: number, rng: TurnRng): Move {
+  if (options.randomMove !== undefined) {
+    return options.randomMove(state, seat, rng);
+  }
+  if (rules.autoMove === undefined) {
+    return fail('the rules have no autoMove: pass options.randomMove');
+  }
+  return rules.autoMove(state, seat, rng);
+}
+
+/** Play one seeded game; answers its moves and a trace for the determinism check. */
+function playGame<State, Move, View, Event, Options>(
+  rules: TurnRules<State, Move, View, Event, Options>, seats: number, seed: number, options: TurnRulesCheckOptions<State, Move, Options>,
+): { moves: number; trace: string } {
+  const rng = createTurnRng(turnRngStateFromSeed(seed));
+  const marker = `MARKER-${String(seed)}-`;
+  let state = rules.setup({ seats, options: options.setupOptions ?? null, mode: options.mode ?? null, rng });
+  if (options.plant !== undefined) {
+    for (let seat = 0; seat < seats; seat++) {
+      state = options.plant(state, seat, `${marker}${String(seat)}`);
+    }
+  }
+  const maxMoves = options.maxMoves ?? 2000;
+  const trace: string[] = [];
+  const checkViews = (events: readonly Event[]): void => {
+    for (let viewer = 0; viewer < seats; viewer++) {
+      const seen = JSON.stringify(rules.view(state, viewer)) + JSON.stringify(events.map((event) => rules.eventView?.(event, viewer) ?? null));
+      for (let owner = 0; owner < seats; owner++) {
+        if (owner !== viewer && options.plant !== undefined && seen.includes(`${marker}${String(owner)}`)) {
+          fail(`seat ${String(viewer)} can see seat ${String(owner)}'s secret (seed ${String(seed)})`);
+        }
+      }
+    }
+    if (options.plant !== undefined && JSON.stringify(rules.view(state, null)).includes(marker)) {
+      fail(`the public view shows a seat's secret (seed ${String(seed)})`);
+    }
+  };
+  checkViews([]);
+  for (let moves = 0; moves < maxMoves; moves++) {
+    if (rules.outcome(state) !== null) {
+      return { moves, trace: trace.join('|') };
+    }
+    const toAct = rules.toAct(state);
+    const seat = toAct[0];
+    if (seat === undefined) {
+      fail(`toAct is empty but there is no outcome yet (seed ${String(seed)}, move ${String(moves)})`);
+    }
+    const move = pickMove(rules, options, state, seat, rng);
+    if (bytesOf(JSON.stringify(move)) > MOVE_MAX_BYTES) {
+      fail(`a move is over ${String(MOVE_MAX_BYTES)} bytes`);
+    }
+    const result = rules.apply(roundTrip(state), seat, roundTrip(move), rng);
+    if ('error' in result) {
+      fail(`${options.randomMove === undefined ? 'autoMove' : 'randomMove'} made an illegal move for seat ${String(seat)}: ${result.error} (seed ${String(seed)}, move ${String(moves)})`);
+    }
+    state = roundTrip(result.state);
+    if (bytesOf(JSON.stringify(state)) > STATE_MAX_BYTES) {
+      fail(`the state is over ${String(STATE_MAX_BYTES)} bytes`);
+    }
+    checkViews(result.events ?? []);
+    rules.progress(state, seat);
+    trace.push(JSON.stringify(move));
+  }
+  return fail(`a game did not end within ${String(maxMoves)} moves (seed ${String(seed)})`);
+}
+
+/** Check a rules module (see the file comment); throws on the first failure. */
+export function checkTurnRules<State, Move, View, Event, Options>(
+  rules: TurnRules<State, Move, View, Event, Options>, options: TurnRulesCheckOptions<State, Move, Options> = {},
+): TurnRulesReport {
+  if (!Number.isInteger(rules.version) || rules.version < 0) {
+    fail('rules.version must be a whole number');
+  }
+  let games = 0;
+  let moves = 0;
+  let longestGame = 0;
+  for (const seats of options.seats ?? [2]) {
+    for (let game = 0; game < (options.games ?? 25); game++) {
+      const seed = seats * 100_003 + game;
+      const played = playGame(rules, seats, seed, options);
+      if (playGame(rules, seats, seed, options).trace !== played.trace) {
+        fail(`the same seed played a different game (seed ${String(seed)}): use the rng you are given, never Math.random`);
+      }
+      games += 1;
+      moves += played.moves;
+      longestGame = Math.max(longestGame, played.moves);
+    }
+  }
+  for (const fixture of options.fixtures ?? []) {
+    if (fixture.version < rules.version) {
+      if (rules.migrate === undefined) {
+        fail(`a version ${String(fixture.version)} fixture needs rules.migrate`);
+      }
+      const migrated = rules.migrate(roundTrip(fixture.state), fixture.version);
+      rules.view(migrated, null);
+      rules.toAct(migrated);
+    }
+  }
+  return { games, moves, longestGame };
+}

package/src/turns.ts

@@ -0,0 +1,13 @@
+/**
+ * `@diffenderfer-games/hub/turns`: writing and testing an online turn
+ * game's rules module (docs/multiplayer.md "Turn games"). The types of the
+ * rules contract, `defineTurnRules` to type a rules object, the seeded RNG
+ * the hub hands the rules (to replay a game in tests), and the conformance
+ * kit, `checkTurnRules`, for the game's own CI. The page-side API is
+ * `hub.turns` on the main entry.
+ *
+ * @packageDocumentation
+ */
+export { createTurnRng, defineTurnRules, turnRngStateFromSeed } from '@diffenderfer-games/hub-contract';
+export type { TurnApplyResult, TurnOutcome, TurnProgress, TurnRng, TurnRngState, TurnRules, TurnSetupContext } from '@diffenderfer-games/hub-contract';
+export { checkTurnRules, type TurnRulesCheckOptions, type TurnRulesReport } from './turns-kit/check-rules';