@eigeninteractive/testkit 0.5.0 → 0.5.2

package/dist/contract-cli.d.ts

@@ -1 +1,2 @@
 #!/usr/bin/env node
+export {};

package/dist/contract-command.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Emits `game-contract.json` from an EigenInteractive package's conventional layout.
+ *
+ * This is the programmatic form of the `eigen-contract` executable. Most
+ * games should invoke the executable through their package script.
+ */
+export declare function emitConfiguredGameContract(root?: string): Promise<void>;
+/**
+ * Fails when the conventionally configured contract is absent or stale.
+ *
+ * Use this in CI through `eigen-contract --check`.
+ */
+export declare function checkConfiguredGameContract(root?: string): Promise<void>;

package/dist/game-contract.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 { type GameModule } from "@eigeninteractive/rules";
+/** Current format of the language-neutral contract consumed by EigenInteractive's Dart generator. */
+export declare 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;
+}
+/** Build a deterministic in-memory contract without touching the filesystem. */
+export declare function buildGameContract(options: BuildGameContractOptions): GameContract;
+/** Render one deterministic, newline-terminated contract document. */
+export declare function gameContractJson(options: BuildGameContractOptions): string;
+/** Emit one deterministic, newline-terminated `game-contract.json`. */
+export declare function emitGameContract(options: EmitGameContractOptions): void;
+/** Fail when an emitted contract is missing or differs from its inputs. */
+export declare function checkGameContract(options: EmitGameContractOptions): void;
+/** A useful default filename for scripts that accept an output directory. */
+export declare const gameContractFilename: (game: string) => string;

package/dist/index.d.ts

@@ -1,249 +1,11 @@
-import { GameModule, GameRules, JsonObject, TransitionCause, OutcomeEntry, GameAccess, Json } from '@eigeninteractive/rules';
-import { SeatView } from '@eigeninteractive/kernel';
-export { CommitInput, CommitPlan, DEADLINE_GRACE_MS, Effect, GameRow, Intent, ObservationFrame, RejectCode, Rejected, Seat, SeatView, StateRow, commit, deriveRng, isRejected, randomSeed } from '@eigeninteractive/kernel';
-
 /**
- * Emits `game-contract.json` from an EigenInteractive package's conventional layout.
+ * `@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.
  *
- * This is the programmatic form of the `eigen-contract` executable. Most
- * games should invoke the executable through their package script.
+ * @module @eigeninteractive/testkit
  */
-declare function emitConfiguredGameContract(root?: string): Promise<void>;
-/**
- * Fails when the conventionally configured contract is absent or stale.
- *
- * Use this in CI through `eigen-contract --check`.
- */
-declare function checkConfiguredGameContract(root?: string): Promise<void>;
-
-/**
- * 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.
- */
-
-/** Current format of the language-neutral contract consumed by EigenInteractive's Dart generator. */
-declare const GAME_CONTRACT_FORMAT_VERSION = 1;
-/** One validated twin-fixture document embedded in a {@link GameContract}. */
-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`. */
-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. */
-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. */
-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. */
-interface EmitGameContractOptions extends BuildGameContractOptions {
-    /** Destination `game-contract.json` path. */
-    output: string | URL;
-}
-/** Build a deterministic in-memory contract without touching the filesystem. */
-declare function buildGameContract(options: BuildGameContractOptions): GameContract;
-/** Render one deterministic, newline-terminated contract document. */
-declare function gameContractJson(options: BuildGameContractOptions): string;
-/** Emit one deterministic, newline-terminated `game-contract.json`. */
-declare function emitGameContract(options: EmitGameContractOptions): void;
-/** Fail when an emitted contract is missing or differs from its inputs. */
-declare function checkGameContract(options: EmitGameContractOptions): void;
-/** A useful default filename for scripts that accept an output directory. */
-declare const gameContractFilename: (game: string) => string;
-
-/**
- * The kernel-scenario surface for game tests: how an implementor drives real
- * engine transitions over their rules unit (same-view pairs, timing/grace
- * behavior, lifecycle outcomes) without depending on the engine's internals.
- *
- * `@eigeninteractive/kernel` is an internal package: implementors ship `@eigeninteractive/rules` +
- * `@eigeninteractive/server` and dev-depend on `@eigeninteractive/testkit` alone. Everything a
- * game's test suite legitimately needs from the kernel is re-exported here,
- * so the kernel's own surface stays free to churn.
- */
-
-/** 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. */
-declare function projectView(rules: GameRules, args: {
-    state: JsonObject;
-    pending: number[];
-    /** The seat to project for, or null for a viewer. */
-    seat: number | null;
-    config: JsonObject;
-    cause?: TransitionCause;
-    participantCount?: number;
-    isReplay?: boolean;
-}): SeatView;
-
-/**
- * Twin-drift fixture runner: the TS half of the shared JSON fixtures that
- * keep a version unit's TS and Dart `GameRules` twins in sync. The JSON
- * fixture format is shared verbatim with the Dart runner
- * (`lib/testing/twin_fixtures.dart`): one file, two consumers.
- *
- * One fixture file per concern lives beside the version units at
- * `<fixturesRoot>/v<N>/*.json` and is consumed by BOTH sides: this module
- * runs each case against the TS unit (schemas + `applyAction` +
- * `computeObservation` + the two predicates), while the Dart runner runs the
- * same file against the Dart twin (generated payload parsing,
- * `isValidAction`, `previewAction`, predicate twins). A behavioral divergence
- * then fails one side's CI instead of degrading UX in production.
- *
- * ## Fixture file format
- *
- * ```jsonc
- * {
- *   "schemaVersion": 1,
- *   "cases": [
- *     {
- *       "kind": "action",
- *       "name": "seat 0 marks an empty cell",
- *       "config": {},
- *       "state": { ... },            // TS: applyAction input
- *       "obs": { ... },              // Dart-only; defaults to `state`
- *       "pending": [0],
- *       "playerIndex": 0,
- *       "participantCount": 2,       // optional, default 2
- *       "rngSeed": "any string",     // optional, default "twin-fixtures"
- *       "action": { ... },
- *       "expected": {
- *         "valid": true,             // false ⇒ TS IllegalMoveError,
- *                                    //         Dart isValidAction false
- *         "state": { ... },          // optional, TS envelope.state
- *         "pending": [1],            // optional, TS envelope.pendingPlayers
- *         "outcome": [ ... ],        // optional, TS envelope.outcome
- *                                    //   (null asserts the game is ongoing)
- *         "observation": { ... }     // optional, the actor's post-action
- *                                    //   view: TS computeObservation slice
- *                                    //   data; Dart previewAction (when the
- *                                    //   game implements optimism)
- *       }
- *     },
- *     { "kind": "playerLimits", "name": "...", "config": {},
- *       "expected": { "minPlayers": 2, "maxPlayers": 2 } },
- *     { "kind": "ratingPool",  "name": "...", "access": "public",
- *       "minPlayers": 2, "maxPlayers": 2, "config": {}, "expected": "blitz" },
- *     { "kind": "botSeatable", "name": "...", "gameConfig": {},
- *       "botConfig": {}, "expected": false }
- *   ]
- * }
- * ```
- *
- * The `state`/`obs` split exists for hidden-info games (a seat's observation
- * is not the state); perfect-info games omit `obs`. `expected.observation` is
- * the shared behavioral anchor: the TS side must project the post-action
- * state to it, and a Dart `previewAction` that returns non-null must predict
- * it, so the two sides are compared through one recorded value.
- *
- * Wire it up in a game-owned test file running under plain-Node vitest:
- *
- * ```ts
- * import { twinFixtureTests } from "@eigeninteractive/testkit";
- * import gameModule from "../src/module/index.js";
- *
- * twinFixtureTests(gameModule, new URL("../src/module/fixtures/", import.meta.url));
- * ```
- */
-
-/** One fixture file: cases targeting one `schemaVersion` unit. */
-interface TwinFixtureFile {
-    schemaVersion: number;
-    cases: TwinFixtureCase[];
-}
-/** A game-action case: exercises schemas, `applyAction`, and (through
- * `expected.observation`) `computeObservation` for the acting seat. */
-interface ActionCase {
-    kind: "action";
-    name: string;
-    config: JsonObject;
-    state: JsonObject;
-    /** Dart-side observation payload; unused here (defaults to `state`). */
-    obs?: JsonObject;
-    pending: number[];
-    playerIndex: number;
-    participantCount?: number;
-    rngSeed?: string;
-    action: JsonObject;
-    expected: {
-        valid: boolean;
-        state?: JsonObject;
-        pending?: number[];
-        outcome?: OutcomeEntry[] | null;
-        observation?: JsonObject;
-    };
-}
-/** A `ratingPool` predicate case. Omitted timing fields mean null. */
-interface RatingPoolCase {
-    kind: "ratingPool";
-    name: string;
-    access: GameAccess;
-    turnSeconds?: number | null;
-    budgetSeconds?: number | null;
-    incrementSeconds?: number | null;
-    minPlayers: number;
-    maxPlayers: number;
-    config: JsonObject;
-    expected: string | null;
-}
-/** A `playerLimits` case: the seats one config may be played with. */
-interface PlayerLimitsCase {
-    kind: "playerLimits";
-    name: string;
-    config: JsonObject;
-    expected: {
-        minPlayers: number;
-        maxPlayers: number;
-    };
-}
-/** A `botSeatable` predicate case. */
-interface BotSeatableCase {
-    kind: "botSeatable";
-    name: string;
-    gameConfig: JsonObject;
-    botConfig: JsonObject;
-    expected: boolean;
-}
-type TwinFixtureCase = ActionCase | PlayerLimitsCase | RatingPoolCase | BotSeatableCase;
-/** Validate one fixture file's parsed JSON, or throw naming the offending
- * file, case, and field. Exported so a repo can lint its fixtures without
- * running them. */
-declare function parseTwinFixtureFile(path: string, json: unknown): TwinFixtureFile;
-/** Run one fixture case against a rules unit, returning failure descriptions
- * (empty ⇒ the case passes). Pure; the file-reading test registrar is
- * {@link twinFixtureTests}. */
-declare function evaluateTwinCase(rules: GameRules, kase: TwinFixtureCase): string[];
-/** Register one vitest test per fixture case found under `fixturesRoot`
- * (layout: `<root>/v<N>/*.json`). Call at the top level of a test module
- * running in a Node environment. */
-declare function twinFixtureTests(gameModule: GameModule, fixturesRoot: string | URL): void;
-/** Structural JSON equality. Object keys with `undefined` values count as
- * absent (matching how schema libraries model optional fields); array order
- * matters. */
-declare function deepEquals(a: Json | undefined, b: Json | undefined): boolean;
-
-export { type ActionCase, type BotSeatableCase, type BuildGameContractOptions, type EmitGameContractOptions, GAME_CONTRACT_FORMAT_VERSION, type GameContract, type GameContractFixture, type GameContractVersion, type PlayerLimitsCase, type RatingPoolCase, type TwinFixtureCase, type TwinFixtureFile, buildGameContract, checkConfiguredGameContract, checkGameContract, deepEquals, emitConfiguredGameContract, emitGameContract, evaluateTwinCase, gameContractFilename, gameContractJson, parseTwinFixtureFile, projectView, twinFixtureTests };
+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/dist/inspect-cli.d.ts

@@ -1 +1,16 @@
 #!/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.
+ */
+export {};

package/dist/kernel-scenarios.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The kernel-scenario surface for game tests: how an implementor drives real
+ * engine transitions over their rules unit (same-view pairs, timing/grace
+ * behavior, lifecycle outcomes) without depending on the engine's internals.
+ *
+ * `@eigeninteractive/kernel` is an internal package: implementors ship `@eigeninteractive/rules` +
+ * `@eigeninteractive/server` and dev-depend on `@eigeninteractive/testkit` alone. Everything a
+ * 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 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";
+/** 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: {
+    state: JsonObject;
+    pending: number[];
+    /** The seat to project for, or null for a viewer. */
+    seat: number | null;
+    config: JsonObject;
+    cause?: TransitionCause;
+    participantCount?: number;
+    isReplay?: boolean;
+}): SeatView;

package/dist/local-state.d.ts

@@ -1,5 +1,3 @@
-import { DatabaseSync } from 'node:sqlite';
-
 /**
  * Read a Worker's LOCAL `.wrangler` state directly: the D1 index and the
  * per-game Durable Object databases, opened as plain SQLite files.
@@ -34,9 +32,9 @@ import { DatabaseSync } from 'node:sqlite';
  *
  * @module @eigeninteractive/testkit/local-state
  */
-
+import { DatabaseSync } from "node:sqlite";
 /** A local Durable Object database: one game's whole session. */
-interface LocalDurableObject {
+export interface LocalDurableObject {
     /** The Durable Object class, parsed from the directory Miniflare names
      * `<worker>-<ClassName>`. */
     className: string;
@@ -53,17 +51,17 @@ interface LocalDurableObject {
 /** What a bound parameter may be: SQLite's own value domain, spelled out here
  * rather than re-exported from `node:sqlite` so the public signature does not
  * depend on a built-in module's type names. */
-type LocalQueryParam = string | number | bigint | null | Uint8Array;
+export type LocalQueryParam = string | number | bigint | null | Uint8Array;
 /** A row of Miniflare's alarm table: the DO's armed alarm, which for a game is
  * its turn deadline plus grace. An absent row means no timer is armed, which is
  * correct for an untimed game and a bug for a timed one mid-turn. */
-interface LocalAlarm {
+export interface LocalAlarm {
     actorId: string;
     actorName: string | null;
     scheduledTime: number | null;
 }
 /** The engine's `games` row: the D1 index entry, a display mirror of the DO. */
-interface LocalGameRow {
+export interface LocalGameRow {
     id: string;
     createdBy: string | null;
     status: string;
@@ -89,7 +87,7 @@ interface LocalGameRow {
 }
 /** One seat, from either store. `username` is filled in from D1's `users` and
  * `bots` tables when the reader has an index to join against. */
-interface LocalSeat {
+export interface LocalSeat {
     playerIndex: number;
     userId: string | null;
     botId: string | null;
@@ -98,7 +96,7 @@ interface LocalSeat {
     displayName: string | null;
 }
 /** The DO's single `meta` row: the authoritative session header. */
-interface LocalGameMeta {
+export interface LocalGameMeta {
     gameId: string;
     status: string;
     access: string;
@@ -115,7 +113,7 @@ interface LocalGameMeta {
     rngSeed: string | null;
 }
 /** One committed transition, decoded. `action` is null at v0 (the start). */
-interface LocalTransition {
+export interface LocalTransition {
     version: number;
     state: unknown;
     action: {
@@ -137,7 +135,7 @@ interface LocalTransition {
 /** Why the game is where it is, and what would move it. Derived rather than
  * stored: this is the sentence a developer actually wants, and every input to
  * it is already on screen above it. */
-interface LocalGameDiagnosis {
+export interface LocalGameDiagnosis {
     /** One line naming the next expected event, or the reason there is none. */
     summary: string;
     /** Disagreements between the D1 mirror and the DO's own truth. A non-empty
@@ -145,7 +143,7 @@ interface LocalGameDiagnosis {
     mirrorDrift: string[];
 }
 /** Everything both stores know about one game. */
-interface LocalGameView {
+export interface LocalGameView {
     gameId: string;
     /** The D1 index row, or null when D1 has no such game: either the id came
      * from a DO name and the index was wiped, or the create write never landed. */
@@ -182,7 +180,7 @@ interface LocalGameView {
  * inside a game repository, including the app half of a two-package layout,
  * where the state lives a directory or two above the shell's cwd.
  */
-declare function findWranglerState(from?: string): string | null;
+export declare function findWranglerState(from?: string): string | null;
 /**
  * Open a SQLite file for reading only.
  *
@@ -196,7 +194,7 @@ declare function findWranglerState(from?: string): string | null;
  * because that fallback would otherwise CREATE a database rather than report a
  * missing one.
  */
-declare function openSqlite(file: string): DatabaseSync;
+export declare function openSqlite(file: string): DatabaseSync;
 /**
  * A Worker's local state, with its databases opened lazily and held open.
  *
@@ -204,7 +202,7 @@ declare function openSqlite(file: string): DatabaseSync;
  * {@link close} it. A single instance is the unit both the CLI and a test use,
  * so neither has to know which file backs which resource.
  */
-declare class LocalStore {
+export declare class LocalStore {
     #private;
     /** Absolute path to `.wrangler/state/v3`. */
     readonly root: string;
@@ -277,5 +275,3 @@ declare class LocalStore {
     /** Release every open handle. */
     close(): void;
 }
-
-export { type LocalAlarm, type LocalDurableObject, type LocalGameDiagnosis, type LocalGameMeta, type LocalGameRow, type LocalGameView, type LocalQueryParam, type LocalSeat, LocalStore, type LocalTransition, findWranglerState, openSqlite };

package/dist/twin-fixtures.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Twin-drift fixture runner: the TS half of the shared JSON fixtures that
+ * keep a version unit's TS and Dart `GameRules` twins in sync. The JSON
+ * fixture format is shared verbatim with the Dart runner
+ * (`lib/testing/twin_fixtures.dart`): one file, two consumers.
+ *
+ * One fixture file per concern lives beside the version units at
+ * `<fixturesRoot>/v<N>/*.json` and is consumed by BOTH sides: this module
+ * runs each case against the TS unit (schemas + `applyAction` +
+ * `computeObservation` + the two predicates), while the Dart runner runs the
+ * same file against the Dart twin (generated payload parsing,
+ * `isValidAction`, `previewAction`, predicate twins). A behavioral divergence
+ * then fails one side's CI instead of degrading UX in production.
+ *
+ * ## Fixture file format
+ *
+ * ```jsonc
+ * {
+ *   "schemaVersion": 1,
+ *   "cases": [
+ *     {
+ *       "kind": "action",
+ *       "name": "seat 0 marks an empty cell",
+ *       "config": {},
+ *       "state": { ... },            // TS: applyAction input
+ *       "obs": { ... },              // Dart-only; defaults to `state`
+ *       "pending": [0],
+ *       "playerIndex": 0,
+ *       "participantCount": 2,       // optional, default 2
+ *       "rngSeed": "any string",     // optional, default "twin-fixtures"
+ *       "action": { ... },
+ *       "expected": {
+ *         "valid": true,             // false ⇒ TS IllegalMoveError,
+ *                                    //         Dart isValidAction false
+ *         "state": { ... },          // optional, TS envelope.state
+ *         "pending": [1],            // optional, TS envelope.pendingPlayers
+ *         "outcome": [ ... ],        // optional, TS envelope.outcome
+ *                                    //   (null asserts the game is ongoing)
+ *         "observation": { ... }     // optional, the actor's post-action
+ *                                    //   view: TS computeObservation slice
+ *                                    //   data; Dart previewAction (when the
+ *                                    //   game implements optimism)
+ *       }
+ *     },
+ *     { "kind": "playerLimits", "name": "...", "config": {},
+ *       "expected": { "minPlayers": 2, "maxPlayers": 2 } },
+ *     { "kind": "ratingPool",  "name": "...", "access": "public",
+ *       "minPlayers": 2, "maxPlayers": 2, "config": {}, "expected": "blitz" },
+ *     { "kind": "botSeatable", "name": "...", "gameConfig": {},
+ *       "botConfig": {}, "expected": false }
+ *   ]
+ * }
+ * ```
+ *
+ * The `state`/`obs` split exists for hidden-info games (a seat's observation
+ * is not the state); perfect-info games omit `obs`. `expected.observation` is
+ * the shared behavioral anchor: the TS side must project the post-action
+ * state to it, and a Dart `previewAction` that returns non-null must predict
+ * it, so the two sides are compared through one recorded value.
+ *
+ * Wire it up in a game-owned test file running under plain-Node vitest:
+ *
+ * ```ts
+ * import { twinFixtureTests } from "@eigeninteractive/testkit";
+ * import gameModule from "../src/module/index.js";
+ *
+ * twinFixtureTests(gameModule, new URL("../src/module/fixtures/", import.meta.url));
+ * ```
+ */
+import { type GameAccess, type GameModule, type GameRules, type Json, type JsonObject, type OutcomeEntry } from "@eigeninteractive/rules";
+/** One fixture file: cases targeting one `schemaVersion` unit. */
+export interface TwinFixtureFile {
+    schemaVersion: number;
+    cases: TwinFixtureCase[];
+}
+/** A game-action case: exercises schemas, `applyAction`, and (through
+ * `expected.observation`) `computeObservation` for the acting seat. */
+export interface ActionCase {
+    kind: "action";
+    name: string;
+    config: JsonObject;
+    state: JsonObject;
+    /** Dart-side observation payload; unused here (defaults to `state`). */
+    obs?: JsonObject;
+    pending: number[];
+    playerIndex: number;
+    participantCount?: number;
+    rngSeed?: string;
+    action: JsonObject;
+    expected: {
+        valid: boolean;
+        state?: JsonObject;
+        pending?: number[];
+        outcome?: OutcomeEntry[] | null;
+        observation?: JsonObject;
+    };
+}
+/** A `ratingPool` predicate case. Omitted timing fields mean null. */
+export interface RatingPoolCase {
+    kind: "ratingPool";
+    name: string;
+    access: GameAccess;
+    turnSeconds?: number | null;
+    budgetSeconds?: number | null;
+    incrementSeconds?: number | null;
+    minPlayers: number;
+    maxPlayers: number;
+    config: JsonObject;
+    expected: string | null;
+}
+/** A `playerLimits` case: the seats one config may be played with. */
+export interface PlayerLimitsCase {
+    kind: "playerLimits";
+    name: string;
+    config: JsonObject;
+    expected: {
+        minPlayers: number;
+        maxPlayers: number;
+    };
+}
+/** A `botSeatable` predicate case. */
+export interface BotSeatableCase {
+    kind: "botSeatable";
+    name: string;
+    gameConfig: JsonObject;
+    botConfig: JsonObject;
+    expected: boolean;
+}
+export type TwinFixtureCase = ActionCase | PlayerLimitsCase | RatingPoolCase | BotSeatableCase;
+/** Validate one fixture file's parsed JSON, or throw naming the offending
+ * file, case, and field. Exported so a repo can lint its fixtures without
+ * running them. */
+export declare function parseTwinFixtureFile(path: string, json: unknown): TwinFixtureFile;
+/** Run one fixture case against a rules unit, returning failure descriptions
+ * (empty ⇒ the case passes). Pure; the file-reading test registrar is
+ * {@link twinFixtureTests}. */
+export declare function evaluateTwinCase(rules: GameRules, kase: TwinFixtureCase): string[];
+/** Register one vitest test per fixture case found under `fixturesRoot`
+ * (layout: `<root>/v<N>/*.json`). Call at the top level of a test module
+ * running in a Node environment. */
+export declare function twinFixtureTests(gameModule: GameModule, fixturesRoot: string | URL): void;
+/** Structural JSON equality. Object keys with `undefined` values count as
+ * absent (matching how schema libraries model optional fields); array order
+ * matters. */
+export declare function deepEquals(a: Json | undefined, b: Json | undefined): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eigeninteractive/testkit",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "license": "MIT",
   "description": "Test helpers for games built on the EigenInteractive engine: drive rules through the real kernel and run shared twin fixtures, with no Worker, database or network.",
   "main": "./dist/index.js",
@@ -35,17 +35,17 @@
   "type": "module",
   "dependencies": {
     "rand-seed": "^3.0.0",
-    "tsx": "^4.23.1",
-    "@eigeninteractive/kernel": "0.5.0"
+    "tsx": "^4.23.12",
+    "@eigeninteractive/kernel": "0.5.2"
   },
   "devDependencies": {
-    "@types/node": "^26.1.1",
+    "@types/node": "^26.2.0",
     "vitest": "^4.1.10",
-    "@eigeninteractive/rules": "0.5.0"
+    "@eigeninteractive/rules": "0.5.2"
   },
   "peerDependencies": {
     "vitest": "^4.1.0",
-    "@eigeninteractive/rules": "^0.5.0"
+    "@eigeninteractive/rules": "^0.5.2"
   },
   "homepage": "https://eigeninteractive.com",
   "repository": {
@@ -60,7 +60,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && tsc -p tsconfig.build.json",
     "dev": "tsup --watch",
     "test": "vitest run --passWithNoTests",
     "typecheck": "tsc --noEmit -p tsconfig.json"