@eigeninteractive/testkit 0.5.1 → 0.6.0

package/src/game-contract.ts

@@ -0,0 +1,205 @@
+/**
+ * Emit the language-neutral contract a game's Flutter repository consumes.
+ *
+ * The authoritative inputs live with the TypeScript rules: the four payload
+ * schemas and the shared behavioral fixtures. The output is one deterministic
+ * JSON file so it can be copied, attached to a release, or fetched by checksum
+ * without assuming any repository layout.
+ */
+
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, relative, resolve } from "node:path";
+import { assertPortableSchema, type GameModule, type StandardJSONSchemaV1 } from "@eigeninteractive/rules";
+import { parseTwinFixtureFile } from "./twin-fixtures.js";
+
+/** Current format of the language-neutral contract consumed by EigenInteractive's Dart generator. */
+export const GAME_CONTRACT_FORMAT_VERSION = 1;
+
+/** One validated twin-fixture document embedded in a {@link GameContract}. */
+export interface GameContractFixture {
+  /** POSIX-style path relative to the supplied fixtures root. */
+  path: string;
+  /** Validated fixture document, retained in its original JSON shape. */
+  document: unknown;
+}
+
+/** The four JSON Schemas emitted for one game `schemaVersion`. */
+export interface GameContractVersion {
+  schemas: {
+    state: Record<string, unknown>;
+    observation: Record<string, unknown>;
+    action: Record<string, unknown>;
+    config: Record<string, unknown>;
+  };
+}
+
+/** Language-neutral schemas and fixtures shared by a game's Worker and app. */
+export interface GameContract {
+  formatVersion: typeof GAME_CONTRACT_FORMAT_VERSION;
+  game: string;
+  versions: Record<string, GameContractVersion>;
+  fixtures: GameContractFixture[];
+}
+
+/** Inputs for building a {@link GameContract} without writing it. */
+export interface BuildGameContractOptions {
+  /** Stable display name used as the generated Dart type prefix. */
+  game: string;
+  /** Authoritative TypeScript rules registry. */
+  gameModule: GameModule;
+  /** Root containing `v<N>/*.json` twin fixtures. */
+  fixturesRoot?: string | URL;
+}
+
+/** Inputs for emitting or checking a {@link GameContract} file. */
+export interface EmitGameContractOptions extends BuildGameContractOptions {
+  /** Destination `game-contract.json` path. */
+  output: string | URL;
+}
+
+/**
+ * Sort object keys so the same schemas always emit the same bytes.
+ *
+ * Ordering is by UTF-16 code unit — plain `Array#sort` — which is what RFC 8785
+ * specifies and what `tool/check-contracts.mjs` uses to digest a manifest. It is
+ * *not* `localeCompare`: that collates case-insensitively, so a `$defs` entry
+ * named `Move` sorts before `additionalProperties` under one rule and after it
+ * under the other. Generated JSON Schema is full of capitalized `$defs` names, so
+ * the two orders genuinely disagree, and a digest computed over one would never
+ * match a document written by the other.
+ */
+function canonical(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([key, item]) => [key, canonical(item)]),
+    );
+  }
+  return value;
+}
+
+/**
+ * Emit one payload schema as portable draft-2020-12 JSON Schema.
+ *
+ * Always the **output** direction. Zod's input schema omits
+ * `additionalProperties: false` on objects, because on input a permissive object
+ * still strips unknown keys rather than rejecting them — but the contract is what
+ * the Dart side generates a validator from, and an open object there means the two
+ * halves disagree about an unknown key. Schemas are required to be transform-free
+ * (see `GameSchemas`), so the two directions describe the same values and the
+ * output one is simply the honest document.
+ *
+ * The result is then checked against the portable profile, because emission is
+ * where an unportable schema can still be fixed cheaply. Skipping this check is
+ * how the profile came to be violated in the first place.
+ */
+function jsonSchema(schema: StandardJSONSchemaV1, label: string): Record<string, unknown> {
+  const options = { target: "draft-2020-12" as const };
+  let emitted: unknown;
+  try {
+    emitted = canonical(schema["~standard"].jsonSchema.output(options));
+  } catch (error) {
+    throw new Error(`${label} cannot emit its type as draft-2020-12 JSON Schema`, { cause: error });
+  }
+  assertPortableSchema(emitted, label);
+  return emitted as Record<string, unknown>;
+}
+
+function fixtureFiles(root: string): string[] {
+  const found: string[] = [];
+  const visit = (directory: string): void => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const path = resolve(directory, entry.name);
+      if (entry.isDirectory()) visit(path);
+      else if (entry.isFile() && entry.name.endsWith(".json")) found.push(path);
+    }
+  };
+  visit(root);
+  return found.sort();
+}
+
+function fixtures(fixturesRoot: string | URL | undefined, versions: ReadonlySet<string>): GameContractFixture[] {
+  if (fixturesRoot === undefined) return [];
+  const root = fixturesRoot instanceof URL ? fixturesRoot.pathname : resolve(fixturesRoot);
+  return fixtureFiles(root).map((path) => {
+    const document = JSON.parse(readFileSync(path, "utf8")) as unknown;
+    const fixture = parseTwinFixtureFile(path, document);
+    const fixturePath = relative(root, path).split("\\").join("/");
+    const directory = fixturePath.split("/")[0];
+    const match = /^v([1-9]\d*)$/.exec(directory ?? "");
+    if (match === null) {
+      throw new Error(`${fixturePath}: fixtures must live under a v<N>/ directory`);
+    }
+    const pathVersion = Number(match[1]);
+    if (pathVersion !== fixture.schemaVersion) {
+      throw new Error(`${fixturePath}: directory v${pathVersion} disagrees with schemaVersion ${fixture.schemaVersion}`);
+    }
+    if (!versions.has(String(fixture.schemaVersion))) {
+      throw new Error(`${fixturePath}: gameModule ships no rules unit for schemaVersion ${fixture.schemaVersion}`);
+    }
+    return {
+      path: fixturePath,
+      document: canonical(document),
+    };
+  });
+}
+
+/** Build a deterministic in-memory contract without touching the filesystem. */
+export function buildGameContract(options: BuildGameContractOptions): GameContract {
+  const game = options.game.trim();
+  if (game.length === 0) throw new Error("game contract name must not be empty");
+
+  const versions = Object.fromEntries(
+    Object.entries(options.gameModule.versions)
+      .sort(([a], [b]) => Number(a) - Number(b))
+      .map(([version, rules]) => [
+        version,
+        {
+          schemas: {
+            state: jsonSchema(rules.schemas.state, `v${version} state`),
+            observation: jsonSchema(rules.schemas.observation, `v${version} observation`),
+            action: jsonSchema(rules.schemas.action, `v${version} action`),
+            config: jsonSchema(rules.schemas.config, `v${version} config`),
+          },
+        },
+      ]),
+  );
+
+  if (Object.keys(versions).length === 0) {
+    throw new Error("game contract must contain at least one schema version");
+  }
+
+  return {
+    formatVersion: GAME_CONTRACT_FORMAT_VERSION,
+    game,
+    versions,
+    fixtures: fixtures(options.fixturesRoot, new Set(Object.keys(versions))),
+  };
+}
+
+/** Render one deterministic, newline-terminated contract document. */
+export function gameContractJson(options: BuildGameContractOptions): string {
+  return `${JSON.stringify(buildGameContract(options), null, 2)}\n`;
+}
+
+/** Emit one deterministic, newline-terminated `game-contract.json`. */
+export function emitGameContract(options: EmitGameContractOptions): void {
+  const output = options.output instanceof URL ? options.output : resolve(options.output);
+  writeFileSync(output, gameContractJson(options));
+}
+
+/** Fail when an emitted contract is missing or differs from its inputs. */
+export function checkGameContract(options: EmitGameContractOptions): void {
+  const output = options.output instanceof URL ? options.output : resolve(options.output);
+  if (!existsSync(output) || readFileSync(output, "utf8") !== gameContractJson(options)) {
+    throw new Error(`${output.toString()} is stale; run eigen-contract`);
+  }
+}
+
+/** A useful default filename for scripts that accept an output directory. */
+export const gameContractFilename = (game: string): string =>
+  `${basename(game)
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9]+/g, "-")}-game-contract.json`;

package/src/index.ts

@@ -0,0 +1,53 @@
+/**
+ * `@eigeninteractive/testkit`: drive a game's rules through the real kernel without a
+ * Worker, a database or a network. Build a table, submit actions as seats,
+ * assert on the resulting transitions and per-seat observations.
+ *
+ * @module @eigeninteractive/testkit
+ */
+
+export { checkConfiguredGameContract, emitConfiguredGameContract } from "./contract-command.js";
+export {
+  type BuildGameContractOptions,
+  buildGameContract,
+  checkGameContract,
+  type EmitGameContractOptions,
+  emitGameContract,
+  GAME_CONTRACT_FORMAT_VERSION,
+  type GameContract,
+  type GameContractFixture,
+  type GameContractVersion,
+  gameContractFilename,
+  gameContractJson,
+} from "./game-contract.js";
+export {
+  type CommitInput,
+  type CommitPlan,
+  commit,
+  DEADLINE_GRACE_MS,
+  deriveRng,
+  type Effect,
+  type GameRow,
+  type Intent,
+  isRejected,
+  type ObservationFrame,
+  projectView,
+  type RejectCode,
+  type Rejected,
+  randomSeed,
+  type Seat,
+  type SeatView,
+  type StateRow,
+} from "./kernel-scenarios.js";
+export {
+  type ActionCase,
+  type BotSeatableCase,
+  deepEquals,
+  evaluateTwinCase,
+  type PlayerLimitsCase,
+  parseTwinFixtureFile,
+  type RatingPoolCase,
+  type TwinFixtureCase,
+  type TwinFixtureFile,
+  twinFixtureTests,
+} from "./twin-fixtures.js";

package/src/inspect-cli.ts

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+/**
+ * `eigen-inspect`: read a Worker's local `.wrangler` state from the terminal.
+ *
+ * Deliberately narrow. Wrangler already ships a first-party browser for local
+ * resources (press `e` in `wrangler dev`, or open `/cdn-cgi/explorer`), and
+ * generic table browsing is its job, not this tool's. What that view cannot do
+ * is answer a question in the engine's own terms, because a game's truth is
+ * split across two stores on purpose: the D1 index and the game's own Durable
+ * Object. This reads both, decodes the JSON columns, prints the transition log
+ * as a timeline, and says what the game is waiting for.
+ *
+ * It also runs with no dev server, no browser and no account, and emits
+ * `--json` for a script or an agent.
+ */
+
+import { parseArgs } from "node:util";
+import type { LocalGameRow, LocalGameView, LocalSeat } from "./local-state.js";
+import { LocalStore } from "./local-state.js";
+
+const HELP = `Usage: eigen-inspect <command> [options]
+
+Read the local .wrangler state of an EigenInteractive Worker: the D1 index and
+each game's own Durable Object database.
+
+Commands:
+  games                    The D1 index, newest first
+  game <id|code|prefix>    One game across both stores, with its timeline
+  do                       Every local Durable Object, mapped back to its game
+  players                  Local users and bots, by id
+  tables [--game <ref>]    Table names and row counts
+  sql <query> [--game <ref>]
+                           Run a read-only statement against D1 or one game's DO
+
+Options:
+  --dir <path>   Start the search for .wrangler/state here (default: cwd)
+  --status <s>   games: filter by status
+  --limit <n>    games: row cap (default 20)
+  --game <ref>   tables/sql: target one game's Durable Object instead of D1
+  --json         Emit JSON instead of a table
+  -h, --help     Show this help
+
+Every database is opened read-only, so this is safe to run while the Worker is
+running. Wrangler's own browser for the same files is \`e\` in \`wrangler dev\`.`;
+
+function relative(ms: number | null): string {
+  if (ms === null) return "never";
+  const delta = Date.now() - ms;
+  const future = delta < 0;
+  const seconds = Math.round(Math.abs(delta) / 1000);
+  const [value, unit] = seconds < 60 ? [seconds, "s"] : seconds < 3600 ? [Math.round(seconds / 60), "m"] : seconds < 86400 ? [Math.round(seconds / 3600), "h"] : [Math.round(seconds / 86400), "d"];
+  return future ? `in ${value}${unit}` : `${value}${unit} ago`;
+}
+
+/** Render rows as an aligned table. Values are stringified defensively because
+ * SQLite hands back whatever the column holds, including blobs and nulls. */
+function table(rows: Record<string, unknown>[]): string {
+  if (rows.length === 0) return "(no rows)";
+  const columns = [...new Set(rows.flatMap((row) => Object.keys(row)))];
+  const cell = (value: unknown): string => (value === null || value === undefined ? "" : typeof value === "object" ? JSON.stringify(value) : String(value));
+  const widths = columns.map((column) => Math.max(column.length, ...rows.map((row) => cell(row[column]).length)));
+  const line = (values: string[]): string =>
+    values
+      .map((value, i) => value.padEnd(widths[i]))
+      .join("  ")
+      .trimEnd();
+  return [line(columns), line(widths.map((w) => "-".repeat(w))), ...rows.map((row) => line(columns.map((column, i) => cell(row[column]).padEnd(widths[i]))))].join("\n");
+}
+
+function short(id: string | null, length = 8): string {
+  return id === null ? "" : id.length <= length ? id : `${id.slice(0, length)}…`;
+}
+
+function seatLabel(seat: LocalSeat): string {
+  const identity = seat.username ?? short(seat.userId ?? seat.botId);
+  return `${seat.playerIndex}:${identity || "(empty)"}${seat.type === "bot" ? " (bot)" : ""}`;
+}
+
+function timingLabel(row: { turnSeconds: number | null; budgetSeconds: number | null; incrementSeconds: number | null }): string {
+  if (row.turnSeconds !== null) return `${row.turnSeconds}s per turn`;
+  if (row.budgetSeconds !== null) return `${row.budgetSeconds}s budget${row.incrementSeconds === null ? "" : ` +${row.incrementSeconds}s`}`;
+  return "untimed";
+}
+
+function gamesTable(rows: LocalGameRow[]): Record<string, unknown>[] {
+  return rows.map((row) => ({
+    id: short(row.id, 8),
+    code: row.shortCode,
+    status: row.status,
+    access: row.access,
+    seats: `${row.minPlayers}-${row.maxPlayers}`,
+    rated: row.rated ? "yes" : "no",
+    timing: timingLabel(row),
+    pending: row.pendingPlayers === null ? "" : JSON.stringify(row.pendingPlayers),
+    updated: relative(row.updatedAt),
+  }));
+}
+
+/** The `game` report: the whole session in reading order, index first, then the
+ * authoritative session, then the log, then the one sentence that explains it. */
+function renderGame(view: LocalGameView): string {
+  const out: string[] = [];
+  const index = view.index;
+  out.push(`Game ${view.gameId}${index === null ? "" : `  ${index.shortCode}`}`);
+
+  if (index === null) {
+    out.push("", "D1 index      (no games row)");
+  } else {
+    out.push(
+      "",
+      `D1 index      status=${index.status}  access=${index.access}  rated=${index.rated ? "yes" : "no"}  schema=v${index.schemaVersion}`,
+      `              seats ${index.minPlayers}-${index.maxPlayers}  ${timingLabel(index)}  created ${relative(index.createdAt)}  updated ${relative(index.updatedAt)}`,
+      `config        ${JSON.stringify(index.config)}`,
+      `participants  ${view.indexSeats.length === 0 ? "(none)" : view.indexSeats.map(seatLabel).join("   ")}`,
+    );
+    if (index.finishedAt !== null) out.push(`finished      ${relative(index.finishedAt)}  outcomes ${JSON.stringify(index.outcomes)}`);
+  }
+
+  out.push("");
+  if (view.durableObject === null) {
+    out.push("Durable Object  (none: no command or socket has touched this game yet)");
+  } else {
+    out.push(`Durable Object  ${short(view.durableObject.id, 12)}  ${view.durableObject.file}`);
+    const meta = view.meta;
+    if (meta === null) {
+      out.push("DO meta       (no meta row: the object exists but never initialised)");
+    } else {
+      out.push(`DO meta       status=${meta.status}  seats ${meta.minPlayers}-${meta.maxPlayers}  createdBy=${short(meta.createdBy)}  rngSeed=${meta.rngSeed === null ? "(unset, so no start has committed)" : short(meta.rngSeed, 12)}`);
+    }
+    out.push(`roster        ${view.roster.length === 0 ? "(empty)" : view.roster.map(seatLabel).join("   ")}`);
+    out.push(`alarm         ${view.alarm === null || view.alarm.scheduledTime === null ? "none armed" : `${new Date(view.alarm.scheduledTime).toISOString()} (${relative(view.alarm.scheduledTime)})`}`);
+    if (view.outbox.length > 0) out.push(`outbox        ${view.outbox.length} UNAPPLIED finish row(s): ${view.outbox.map((row) => short(row.finishId)).join(", ")}`);
+  }
+
+  out.push("", "Timeline");
+  if (view.transitions.length === 0) {
+    out.push("  (no transitions: the game has not started, so there is no v0)");
+  } else {
+    for (const transition of view.transitions) {
+      const action = transition.action;
+      const cause = action === null ? "start" : `${action.kind}/${action.type}${action.playerIndex === null ? "" : ` seat ${action.playerIndex}`}`;
+      const payload = action === null || action.data === null || action.data === undefined ? "" : ` ${JSON.stringify(action.data)}`;
+      out.push(`  v${String(transition.version).padEnd(3)} ${cause}${payload}`);
+      out.push(`       state ${JSON.stringify(transition.state)}`);
+      out.push(`       pending ${JSON.stringify(transition.pending)}  deadline ${transition.deadline === null ? "none" : relative(transition.deadline)}  frames ${transition.frameSeats.length === 0 ? "(compacted)" : JSON.stringify(transition.frameSeats)}`);
+    }
+  }
+
+  out.push("", `Diagnosis     ${view.diagnosis.summary}`);
+  for (const drift of view.diagnosis.mirrorDrift) out.push(`Mirror drift  ${drift}`);
+  return out.join("\n");
+}
+
+function main(): void {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      dir: { type: "string" },
+      status: { type: "string" },
+      limit: { type: "string" },
+      game: { type: "string" },
+      json: { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+    },
+  });
+
+  const [command, ...rest] = positionals;
+  if (values.help === true || command === undefined) {
+    console.log(HELP);
+    return;
+  }
+
+  const emit = (value: unknown, text: () => string): void => {
+    console.log(values.json === true ? JSON.stringify(value, null, 2) : text());
+  };
+
+  const store = LocalStore.open(values.dir);
+  try {
+    switch (command) {
+      case "games": {
+        const rows = store.games({ status: values.status, limit: values.limit === undefined ? 20 : Number(values.limit) });
+        emit(rows, () => (rows.length === 0 ? "no games in the local D1 index" : table(gamesTable(rows))));
+        return;
+      }
+      case "game": {
+        const ref = rest[0];
+        if (ref === undefined) throw new Error("game needs an id, short code, or id prefix");
+        const view = store.game(ref);
+        if (view === null) throw new Error(`no game matching "${ref}" in the local D1 index or in any local Durable Object`);
+        emit(view, () => renderGame(view));
+        return;
+      }
+      case "do": {
+        // Paths print relative to the state root: the absolute prefix is the
+        // same on every row and pushes the useful columns off the terminal.
+        const objects = store.durableObjects().map((object) => ({ class: object.className, game: object.name ?? "(unnamed)", doId: short(object.id, 12), file: object.file.startsWith(store.root) ? object.file.slice(store.root.length + 1) : object.file }));
+        emit(objects, () => (objects.length === 0 ? "no local Durable Objects: nothing has created a game session yet" : table(objects)));
+        return;
+      }
+      case "players": {
+        const users = store.query("select id, username, display_name, is_anonymous, created_at from users order by created_at desc");
+        const bots = store.query("select id, username, display_name, type, schema_version from bots order by username");
+        emit({ users, bots }, () => `Users\n${table(users)}\n\nBots\n${table(bots)}`);
+        return;
+      }
+      case "tables": {
+        const rows = store.tables({ game: values.game });
+        emit(rows, () => table(rows));
+        return;
+      }
+      case "sql": {
+        const sql = rest.join(" ");
+        if (sql === "") throw new Error("sql needs a statement");
+        const rows = store.query(sql, { game: values.game });
+        emit(rows, () => table(rows));
+        return;
+      }
+      default:
+        throw new Error(`unknown command "${command}". Run eigen-inspect --help`);
+    }
+  } finally {
+    store.close();
+  }
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(`eigen-inspect: ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 1;
+}

package/{dist/kernel-scenarios.d.ts → src/kernel-scenarios.ts}

@@ -8,14 +8,37 @@
  * game's test suite legitimately needs from the kernel is re-exported here,
  * so the kernel's own surface stays free to churn.
  */
-import { type SeatView } from "@eigeninteractive/kernel";
+
+import { assertHookPayload, type SeatView } from "@eigeninteractive/kernel";
 import type { GameRules, JsonObject, TransitionCause } from "@eigeninteractive/rules";
-export type { CommitInput, CommitPlan, Effect, GameRow, Intent, ObservationFrame, RejectCode, Rejected, Seat, SeatView, StateRow, } from "@eigeninteractive/kernel";
-export { commit, DEADLINE_GRACE_MS, deriveRng, isRejected, randomSeed, } from "@eigeninteractive/kernel";
+
+export type {
+  CommitInput,
+  CommitPlan,
+  Effect,
+  GameRow,
+  Intent,
+  ObservationFrame,
+  RejectCode,
+  Rejected,
+  Seat,
+  SeatView,
+  StateRow,
+} from "@eigeninteractive/kernel";
+export {
+  commit,
+  DEADLINE_GRACE_MS,
+  deriveRng,
+  isRejected,
+  randomSeed,
+} from "@eigeninteractive/kernel";
+
 /** Project one seat's view of a state: the stored-frame shape the same-view
  * rule compares (`commit()`'s `staleViews` input). Convenience for scenario
  * tests that replay a simultaneous-move race. */
-export declare function projectView(rules: GameRules, args: {
+export function projectView(
+  rules: GameRules,
+  args: {
     state: JsonObject;
     pending: number[];
     /** The seat to project for, or null for a viewer. */
@@ -24,4 +47,17 @@ export declare function projectView(rules: GameRules, args: {
     cause?: TransitionCause;
     participantCount?: number;
     isReplay?: boolean;
-}): SeatView;
+  },
+): SeatView {
+  const slice = rules.computeObservation({
+    state: args.state,
+    pending: args.pending,
+    playerIndex: args.seat,
+    participantCount: args.participantCount ?? 2,
+    config: args.config,
+    cause: args.cause ?? null,
+    isReplay: args.isReplay ?? false,
+  });
+  assertHookPayload(rules.schemas.observation, slice.data, `computeObservation for ${args.seat === null ? "viewer" : `seat ${args.seat}`}`);
+  return { data: slice.data, pendingPlayers: slice.pendingPlayers };
+}