@eigeninteractive/testkit

@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.

Interfaces

ActionCase

Defined in: server/packages/testkit/src/twin-fixtures.ts:177

A game-action case: exercises schemas, applyAction, and (through expected.observation) computeObservation for the acting seat.

Properties

action

action: JsonObject;

Defined in: server/packages/testkit/src/twin-fixtures.ts:188

config

config: JsonObject;

Defined in: server/packages/testkit/src/twin-fixtures.ts:180

expected

expected: ExpectedEnvelope & {
  observation?: JsonObject;
  valid: boolean;
};

Defined in: server/packages/testkit/src/twin-fixtures.ts:189

Type Declaration

observation?

optional observation?: JsonObject;

valid

valid: boolean;

kind

kind: "action";

Defined in: server/packages/testkit/src/twin-fixtures.ts:178

name

name: string;

Defined in: server/packages/testkit/src/twin-fixtures.ts:179

obs?

optional obs?: JsonObject;

Defined in: server/packages/testkit/src/twin-fixtures.ts:183

Dart-side observation payload; unused here (defaults to state).

participantCount?

optional participantCount?: number;

Defined in: server/packages/testkit/src/twin-fixtures.ts:186

pending

pending: number[];

Defined in: server/packages/testkit/src/twin-fixtures.ts:184

playerIndex

playerIndex: number;

Defined in: server/packages/testkit/src/twin-fixtures.ts:185

rngSeed?

optional rngSeed?: string;

Defined in: server/packages/testkit/src/twin-fixtures.ts:187

state

state: JsonObject;

Defined in: server/packages/testkit/src/twin-fixtures.ts:181

BotSeatableCase

Defined in: server/packages/testkit/src/twin-fixtures.ts:218

A botSeatable predicate case.

Properties

botConfig

botConfig: JsonObject;

Defined in: server/packages/testkit/src/twin-fixtures.ts:222

expected

expected: boolean;

Defined in: server/packages/testkit/src/twin-fixtures.ts:223

gameConfig

gameConfig: JsonObject;

Defined in: server/packages/testkit/src/twin-fixtures.ts:221

kind

kind: "botSeatable";

Defined in: server/packages/testkit/src/twin-fixtures.ts:219

name

name: string;

Defined in: server/packages/testkit/src/twin-fixtures.ts:220

BuildGameContractOptions

Defined in: server/packages/testkit/src/game-contract.ts:45

Inputs for building a GameContract without writing it.

Extended by

EmitGameContractOptions

Properties

fixturesRoot?

optional fixturesRoot?: string | URL;

Defined in: server/packages/testkit/src/game-contract.ts:51

Root containing v<N>/*.json twin fixtures.

game

game: string;

Defined in: server/packages/testkit/src/game-contract.ts:47

Stable display name used as the generated Dart type prefix.

gameModule

gameModule: GameModule;

Defined in: server/packages/testkit/src/game-contract.ts:49

Authoritative TypeScript rules registry.

CommitInput

Defined in: server/packages/kernel/dist/index.d.ts:248

Properties

game

game: GameRow;

Defined in: server/packages/kernel/dist/index.d.ts:249

intent

intent: Intent;

Defined in: server/packages/kernel/dist/index.d.ts:254

now

now: number;

Defined in: server/packages/kernel/dist/index.d.ts:257

The commit instant (epoch ms), sampled once by the host and never read here.

roster

roster: Seat[];

Defined in: server/packages/kernel/dist/index.d.ts:253

rules

rules: GameRules;

Defined in: server/packages/kernel/dist/index.d.ts:260

The version unit for the game's schemaVersion, already resolved by the host from the GameModule.versions map.

staleViews?

optional staleViews?: {
  current: SeatView | null;
  expected: SeatView | null;
};

Defined in: server/packages/kernel/dist/index.d.ts:268

Same-view material for a stale game action: the acting seat's stored frames at expectedVersion and at the current version. Only consulted when intent.expectedVersion < state.version; if absent (or either frame is missing, e.g. compacted away), the stale action is rejected conservatively.

current

current: SeatView | null;

expected

expected: SeatView | null;

state

state: StateRow | null;

Defined in: server/packages/kernel/dist/index.d.ts:252

The latest transition, or null before v0 (only a start intent is meaningful then).

CommitPlan

Defined in: server/packages/kernel/dist/index.d.ts:314

Properties

action

action: TransitionAction | null;

Defined in: server/packages/kernel/dist/index.d.ts:317

effects

effects: Effect[];

Defined in: server/packages/kernel/dist/index.d.ts:328

frames

frames: ObservationFrame[];

Defined in: server/packages/kernel/dist/index.d.ts:320

Per-seat projected frames (identified seats only), persisted with the transition, fanned out over sockets. No raw state escapes the kernel.

nextState

nextState: StateRow;

Defined in: server/packages/kernel/dist/index.d.ts:316

The next transition row, already versioned (v+1, or 0 for start).

outcomes

outcomes: OutcomeEntry[] | null;

Defined in: server/packages/kernel/dist/index.d.ts:327

Per-seat results when this transition ends the game, else null.

Rating deltas are deliberately NOT here: they depend on global cross-game priors (D1-domain data the kernel must never need). The D1 applier computes them inside the rating CAS via computeRatings (ratings.ts) and the host delivers them as a follow-up versioned ratings transition.

EmitGameContractOptions

Defined in: server/packages/testkit/src/game-contract.ts:55

Inputs for emitting or checking a GameContract file.

Extends

BuildGameContractOptions

Properties

fixturesRoot?

optional fixturesRoot?: string | URL;

Defined in: server/packages/testkit/src/game-contract.ts:51

Root containing v<N>/*.json twin fixtures.

Inherited from

BuildGameContractOptions.fixturesRoot

game

game: string;

Defined in: server/packages/testkit/src/game-contract.ts:47

Stable display name used as the generated Dart type prefix.

Inherited from

BuildGameContractOptions.game

gameModule

gameModule: GameModule;

Defined in: server/packages/testkit/src/game-contract.ts:49

Authoritative TypeScript rules registry.

Inherited from

BuildGameContractOptions.gameModule

output

output: string | URL;

Defined in: server/packages/testkit/src/game-contract.ts:57

Destination game-contract.json path.

ExpectedEnvelope

Defined in: server/packages/testkit/src/twin-fixtures.ts:169

What a case may assert about the envelope a hook (or a whole transcript) produced. Every field is optional: a fixture pins what it means to pin. outcome is three-valued — absent leaves the outcome unchecked, null asserts the game is ongoing, a list asserts it ended exactly so.

Properties

outcome?

optional outcome?: OutcomeEntry[] | null;

Defined in: server/packages/testkit/src/twin-fixtures.ts:172

pending?

optional pending?: number[];

Defined in: server/packages/testkit/src/twin-fixtures.ts:171

state?

optional state?: JsonObject;

Defined in: server/packages/testkit/src/twin-fixtures.ts:170

GameContract

Defined in: server/packages/testkit/src/game-contract.ts:37

Language-neutral schemas and fixtures shared by a game's Worker and app.

Properties

fixtures

fixtures: GameContractFixture[];

Defined in: server/packages/testkit/src/game-contract.ts:41

formatVersion

formatVersion: 1;

Defined in: server/packages/testkit/src/game-contract.ts:38

game

game: string;

Defined in: server/packages/testkit/src/game-contract.ts:39

versions

versions: Record<string, GameContractVersion>;

Defined in: server/packages/testkit/src/game-contract.ts:40

GameContractFixture

Defined in: server/packages/testkit/src/game-contract.ts:19

One validated twin-fixture document embedded in a GameContract.

Properties

document

document: unknown;

Defined in: server/packages/testkit/src/game-contract.ts:23

Validated fixture document, retained in its original JSON shape.

path

path: string;

Defined in: server/packages/testkit/src/game-contract.ts:21

POSIX-style path relative to the supplied fixtures root.

GameContractVersion

Defined in: server/packages/testkit/src/game-contract.ts:27

The four JSON Schemas emitted for one game schemaVersion.

Properties

schemas

schemas: {
  action: Record<string, unknown>;
  config: Record<string, unknown>;
  observation: Record<string, unknown>;
  state: Record<string, unknown>;
};

Defined in: server/packages/testkit/src/game-contract.ts:28

action

action: Record<string, unknown>;

config

config: Record<string, unknown>;

observation

observation: Record<string, unknown>;

state

state: Record<string, unknown>;

GameRow

Defined in: server/packages/kernel/dist/index.d.ts:183

The game's standing configuration: the DO meta snapshot.

Properties

budgetSeconds

budgetSeconds: number | null;

Defined in: server/packages/kernel/dist/index.d.ts:190

config

config: JsonObject;

Defined in: server/packages/kernel/dist/index.d.ts:188

Stored creation config; parsed against the version unit's config schema before any hook sees it.

incrementSeconds

incrementSeconds: number | null;

Defined in: server/packages/kernel/dist/index.d.ts:191

rated

rated: boolean;

Defined in: server/packages/kernel/dist/index.d.ts:192

ratingPool

ratingPool: string | null;

Defined in: server/packages/kernel/dist/index.d.ts:193

schemaVersion

schemaVersion: number;

Defined in: server/packages/kernel/dist/index.d.ts:185

status

status: GameStatus;

Defined in: server/packages/kernel/dist/index.d.ts:184

turnSeconds

turnSeconds: number | null;

Defined in: server/packages/kernel/dist/index.d.ts:189

InitialStateCase

Defined in: server/packages/testkit/src/twin-fixtures.ts:228

The opening transition: what initialState returns for one config and seat count, drawing from the version-0 stream a start commit derives.

Properties

config

config: JsonObject;

Defined in: server/packages/testkit/src/twin-fixtures.ts:231

expected

expected: ExpectedEnvelope;

Defined in: server/packages/testkit/src/twin-fixtures.ts:234

kind

kind: "initialState";

Defined in: server/packages/testkit/src/twin-fixtures.ts:229

name

name: string;

Defined in: server/packages/testkit/src/twin-fixtures.ts:230

playerCount

playerCount: number;

Defined in: server/packages/testkit/src/twin-fixtures.ts:232

rngSeed?

optional rngSeed?: string;

Defined in: server/packages/testkit/src/twin-fixtures.ts:233

LifecycleCase

Defined in: server/packages/testkit/src/twin-fixtures.ts:239

An applyLifecycle case: one engine-driven transition (a turn that ran out, a resign, a purged account) resolved against a stated position.

Properties

config

config: JsonObject;

Defined in: server/packages/testkit/src/twin-fixtures.ts:242

expected

expected: ExpectedEnvelope;

Defined in: server/packages/testkit/src/twin-fixtures.ts:251

kind

kind: "lifecycle";

Defined in: server/packages/testkit/src/twin-fixtures.ts:240

name

name: string;

Defined in: server/packages/testkit/src/twin-fixtures.ts:241

participantCount?

optional participantCount?: number;

Defined in: server/packages/testkit/src/twin-fixtures.ts:249

pending

pending: number[];

Defined in: server/packages/testkit/src/twin-fixtures.ts:244

playerIndex?

optional playerIndex?: number;

Defined in: server/packages/testkit/src/twin-fixtures.ts:248

The forfeiting seat. Required for forfeit/autoForfeit; a timeout carries no seat (its victims are pending), so it must be omitted.

rngSeed?

optional rngSeed?: string;

Defined in: server/packages/testkit/src/twin-fixtures.ts:250

state

state: JsonObject;

Defined in: server/packages/testkit/src/twin-fixtures.ts:243

type

type: LifecycleType;

Defined in: server/packages/testkit/src/twin-fixtures.ts:245

ObservationFrame

Defined in: server/packages/kernel/dist/index.d.ts:103

One seat's projected frame, tagged with its seat. The host stamps version/timing when it persists and fans these out.

Properties

data

data: JsonObject;

Defined in: server/packages/kernel/dist/index.d.ts:105

pendingPlayers

pendingPlayers: number[];

Defined in: server/packages/kernel/dist/index.d.ts:106

playerIndex

playerIndex: number;

Defined in: server/packages/kernel/dist/index.d.ts:104

PlayerLimitsCase

Defined in: server/packages/testkit/src/twin-fixtures.ts:210

A playerLimits case: the seats one config may be played with.

Properties

config

config: JsonObject;

Defined in: server/packages/testkit/src/twin-fixtures.ts:213

expected

expected: {
  maxPlayers: number;
  minPlayers: number;
};

Defined in: server/packages/testkit/src/twin-fixtures.ts:214

maxPlayers

maxPlayers: number;

minPlayers

minPlayers: number;

kind

kind: "playerLimits";

Defined in: server/packages/testkit/src/twin-fixtures.ts:211

name

name: string;

Defined in: server/packages/testkit/src/twin-fixtures.ts:212

RatingPoolCase

Defined in: server/packages/testkit/src/twin-fixtures.ts:196

A ratingPool predicate case. Omitted timing fields mean null.

Properties

access

access: GameAccess;

Defined in: server/packages/testkit/src/twin-fixtures.ts:199

budgetSeconds?

optional budgetSeconds?: number | null;

Defined in: server/packages/testkit/src/twin-fixtures.ts:201

config

config: JsonObject;

Defined in: server/packages/testkit/src/twin-fixtures.ts:205

expected

expected: string | null;

Defined in: server/packages/testkit/src/twin-fixtures.ts:206

incrementSeconds?

optional incrementSeconds?: number | null;

Defined in: server/packages/testkit/src/twin-fixtures.ts:202

kind

kind: "ratingPool";

Defined in: server/packages/testkit/src/twin-fixtures.ts:197

maxPlayers

maxPlayers: number;

Defined in: server/packages/testkit/src/twin-fixtures.ts:204

minPlayers

minPlayers: number;

Defined in: server/packages/testkit/src/twin-fixtures.ts:203

name

name: string;

Defined in: server/packages/testkit/src/twin-fixtures.ts:198

turnSeconds?

optional turnSeconds?: number | null;

Defined in: server/packages/testkit/src/twin-fixtures.ts:200

Rejected

Defined in: server/packages/kernel/dist/index.d.ts:43

An intent the kernel refused. A value, not a throw: rejections are part of the normal protocol.

Properties

code

code: RejectCode;

Defined in: server/packages/kernel/dist/index.d.ts:45

message

message: string;

Defined in: server/packages/kernel/dist/index.d.ts:46

rejected

rejected: true;

Defined in: server/packages/kernel/dist/index.d.ts:44

RngCase

Defined in: server/packages/testkit/src/twin-fixtures.ts:277

Recorded draws from one derived RNG stream. Generated by rngFixtureCase, never hand-written: the values ARE the TypeScript kernel's, and the Dart port has to reproduce them bit for bit.

Properties

draws

draws: number[];

Defined in: server/packages/testkit/src/twin-fixtures.ts:285

kind

kind: "rng";

Defined in: server/packages/testkit/src/twin-fixtures.ts:278

name

name: string;

Defined in: server/packages/testkit/src/twin-fixtures.ts:279

seat?

optional seat?: number;

Defined in: server/packages/testkit/src/twin-fixtures.ts:284

Present ⇒ the bot stream for that seat, keyed "<seed>:bot<seat>".

seed

seed: string;

Defined in: server/packages/testkit/src/twin-fixtures.ts:280

version

version: number;

Defined in: server/packages/testkit/src/twin-fixtures.ts:282

The state version the stream belongs to (deriveRng's second arg).

RngFixtureCaseOptions

Defined in: server/packages/testkit/src/twin-fixtures.ts:980

What stream to record, and how much of it.

Properties

count

count: number;

Defined in: server/packages/testkit/src/twin-fixtures.ts:990

How many draws to record (1 to 64).

name

name: string;

Defined in: server/packages/testkit/src/twin-fixtures.ts:982

The case name, used as the test name on both sides.

seat?

optional seat?: number;

Defined in: server/packages/testkit/src/twin-fixtures.ts:988

Record the bot stream for this seat instead of the transition's own.

seed

seed: string;

Defined in: server/packages/testkit/src/twin-fixtures.ts:984

The game's base seed.

version

version: number;

Defined in: server/packages/testkit/src/twin-fixtures.ts:986

The state version whose stream to record.

Seat

Defined in: server/packages/kernel/dist/index.d.ts:197

One seat of the roster. Both ids null ⇒ the account was purged mid-game (the seat plays on as "Deleted User" for display, but can never act).

Properties

botId

botId: string | null;

Defined in: server/packages/kernel/dist/index.d.ts:200

playerIndex

playerIndex: number;

Defined in: server/packages/kernel/dist/index.d.ts:198

type

type: "bot" | "human";

Defined in: server/packages/kernel/dist/index.d.ts:201

userId

userId: string | null;

Defined in: server/packages/kernel/dist/index.d.ts:199

SeatView

Defined in: server/packages/kernel/dist/index.d.ts:85

A seat's stored projection at one version: what the same-view compare runs on (and what the DO persists per transition as frames[]).

Properties

data

data: JsonObject;

Defined in: server/packages/kernel/dist/index.d.ts:86

pendingPlayers

pendingPlayers: number[];

Defined in: server/packages/kernel/dist/index.d.ts:87

StateRow

Defined in: server/packages/kernel/dist/index.d.ts:205

The latest committed transition: state plus the engine-owned clocks. All instants are epoch milliseconds.

Properties

deadline

deadline: number | null;

Defined in: server/packages/kernel/dist/index.d.ts:212

The true turn deadline shown to clients; the alarm arms one millisecond after deadline + grace.

pending

pending: number[];

Defined in: server/packages/kernel/dist/index.d.ts:208

playerTimes

playerTimes: number[] | null;

Defined in: server/packages/kernel/dist/index.d.ts:214

Per-seat budget banks (ms), budget mode only.

rngSeed

rngSeed: string;

Defined in: server/packages/kernel/dist/index.d.ts:209

state

state: JsonObject;

Defined in: server/packages/kernel/dist/index.d.ts:207

turnStartedAt

turnStartedAt: number | null;

Defined in: server/packages/kernel/dist/index.d.ts:218

When the current turn is consuming a budget bank. Null for untimed, per-action, and hook-override turns. This is persisted so charging the turn that ends never depends on the next envelope.

version

version: number;

Defined in: server/packages/kernel/dist/index.d.ts:206

TranscriptCase

Defined in: server/packages/testkit/src/twin-fixtures.ts:260

A whole match, replayed through the real kernel from a stated base seed. The one case that pins the engine's bookkeeping — versions, pending hand-off, the per-transition RNG streams — rather than a single hook.

Properties

config

config: JsonObject;

Defined in: server/packages/testkit/src/twin-fixtures.ts:263

expected

expected: ExpectedEnvelope & {
  status: "active" | "finished";
  version: number;
};

Defined in: server/packages/testkit/src/twin-fixtures.ts:268

Type Declaration

status

status: "active" | "finished";

version

version: number;

kind

kind: "transcript";

Defined in: server/packages/testkit/src/twin-fixtures.ts:261

name

name: string;

Defined in: server/packages/testkit/src/twin-fixtures.ts:262

playerCount

playerCount: number;

Defined in: server/packages/testkit/src/twin-fixtures.ts:264

seed

seed: string;

Defined in: server/packages/testkit/src/twin-fixtures.ts:266

The game's base RNG seed: every transition's stream derives from it.

transitions

transitions: TranscriptTransition[];

Defined in: server/packages/testkit/src/twin-fixtures.ts:267

TwinFixtureFile

Defined in: server/packages/testkit/src/twin-fixtures.ts:160

One fixture file: cases targeting one schemaVersion unit.

Properties

cases

cases: TwinFixtureCase[];

Defined in: server/packages/testkit/src/twin-fixtures.ts:162

schemaVersion

schemaVersion: number;

Defined in: server/packages/testkit/src/twin-fixtures.ts:161

Type Aliases

Effect

type Effect =
  | {
  botId: string;
  kind: "wakeBot";
  seat: number;
}
  | {
  kind: "notifyTurn";
  seat: number;
  userId: string;
}
  | {
  kind: "notifyFinished";
  userIds: string[];
};

Defined in: server/packages/kernel/dist/index.d.ts:302

A push/wake the host should attempt post-commit (single attempt + error log, with no retry machinery in v1). The kernel names seats; the host resolves delivery (FCM targets, bot webhook vs local bot).

Intent

type Intent =
  | {
  kind: "start";
  seed: string;
}
  | {
  actor: "user" | "bot";
  data: unknown;
  expectedVersion: number;
  kind: "action";
  seat: number;
}
  | {
  kind: "lifecycle";
  type: "timeout";
}
  | {
  kind: "lifecycle";
  seat: number;
  type: "forfeit" | "autoForfeit";
};

Defined in: server/packages/kernel/dist/index.d.ts:222

What the host asks the kernel to do: the kernel-facing half of a Command (authorization already happened at the edge; dedupe at the DO).

Union Members

Type Literal

{
  kind: "start";
  seed: string;
}

kind

kind: "start";

seed

seed: string;

The game's base RNG seed, freshly generated by the host (randomSeed()); stored on v0 and copied to every later row.

Type Literal

{
  actor: "user" | "bot";
  data: unknown;
  expectedVersion: number;
  kind: "action";
  seat: number;
}

actor

actor: "user" | "bot";

data

data: unknown;

The raw move payload, parsed against the unit's action schema.

expectedVersion

expectedVersion: number;

The version the client computed the move against. Equal to the current version in the common case; a lower value is arbitrated by the same-view rule.

kind

kind: "action";

seat

seat: number;

Type Literal

{
  kind: "lifecycle";
  type: "timeout";
}

Type Literal

{
  kind: "lifecycle";
  seat: number;
  type: "forfeit" | "autoForfeit";
}

forfeit = a voluntary resign (a user action); autoForfeit = the engine-driven variant (account purge; identity-less system action).

RejectCode

type RejectCode =
  | "notActive"
  | "notReady"
  | "expired"
  | "notPending"
  | "stateUpdated"
  | "invalidPayload"
  | "illegalMove"
  | "abstain";

Defined in: server/packages/kernel/dist/index.d.ts:22

Why an intent was refused. Stable machine codes: the host's transport mapping and the client's retry policy key on these, so treat renames as breaking.

TranscriptTransition

type TranscriptTransition =
  | {
  data: JsonObject;
  kind: "game";
  playerIndex: number;
}
  | {
  kind: "lifecycle";
  playerIndex: number;
  type: "forfeit";
};

Defined in: server/packages/testkit/src/twin-fixtures.ts:255

One transition of a TranscriptCase: a seat's move, or a resign.

TwinFixtureCase

type TwinFixtureCase =
  | ActionCase
  | PlayerLimitsCase
  | RatingPoolCase
  | BotSeatableCase
  | InitialStateCase
  | LifecycleCase
  | TranscriptCase
  | RngCase;

Defined in: server/packages/testkit/src/twin-fixtures.ts:288

Variables

GAME_CONTRACT_FORMAT_VERSION

const GAME_CONTRACT_FORMAT_VERSION: 1 = 1;

Defined in: server/packages/testkit/src/game-contract.ts:16

Current format of the language-neutral contract consumed by EigenInteractive's Dart generator.

Functions

buildGameContract()

function buildGameContract(options): GameContract;

Defined in: server/packages/testkit/src/game-contract.ts:150

Build a deterministic in-memory contract without touching the filesystem.

Parameters

Parameter	Type
`options`	`BuildGameContractOptions`

Returns

GameContract

checkConfiguredGameContract()

function checkConfiguredGameContract(root?): Promise<void>;

Defined in: server/packages/testkit/src/contract-command.ts:76

Fails when the conventionally configured contract is absent or stale.

Use this in CI through eigen-contract --check.

Parameters

Parameter	Type
`root`	`any`

Returns

Promise<void>

checkGameContract()

function checkGameContract(options): void;

Defined in: server/packages/testkit/src/game-contract.ts:194

Fail when an emitted contract is missing or differs from its inputs.

Parameters

Parameter	Type
`options`	`EmitGameContractOptions`

Returns

void

commit()

function commit(input): CommitPlan | Rejected;

Defined in: server/packages/kernel/dist/index.d.ts:332

Parameters

Parameter	Type
`input`	`CommitInput`

Returns

CommitPlan | Rejected

deepEquals()

function deepEquals(a, b): boolean;

Defined in: server/packages/testkit/src/twin-fixtures.ts:1079

Structural JSON equality. Object keys with undefined values count as absent (matching how schema libraries model optional fields); array order matters.

Parameters

Parameter	Type
`a`	`Json` \| `undefined`
`b`	`Json` \| `undefined`

Returns

boolean

deriveRng()

function deriveRng(seed, version): Rng;

Defined in: server/packages/kernel/dist/index.d.ts:345

The deterministic RNG for one transition: rand-seed's sfc32 keyed by the game's base seed and the state version the envelope will commit as. The same (seed, version) always yields the same draw sequence, so a replay re-derives it, and every transition gets an independent stream, so hooks draw as many values as they need with no cross-invocation state. The derivation is fixed, so recorded games stay replayable.

Parameters

Parameter	Type
`seed`	`string`
`version`	`number`

Returns

Rng

emitConfiguredGameContract()

function emitConfiguredGameContract(root?): Promise<void>;

Defined in: server/packages/testkit/src/contract-command.ts:67

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.

Parameters

Parameter	Type
`root`	`any`

Returns

Promise<void>

emitGameContract()

function emitGameContract(options): void;

Defined in: server/packages/testkit/src/game-contract.ts:188

Emit one deterministic, newline-terminated game-contract.json.

Parameters

Parameter	Type
`options`	`EmitGameContractOptions`

Returns

void

evaluateTwinCase()

function evaluateTwinCase(
   rules,
   kase,
   schemaVersion?
): string[];

Defined in: server/packages/testkit/src/twin-fixtures.ts:596

Run one fixture case against a rules unit, returning failure descriptions (empty ⇒ the case passes). Pure; the file-reading test registrar is twinFixtureTests.

schemaVersion is the version the case targets. It never selects behavior — the caller already resolved rules from it — and only labels the engine guard messages a lifecycle or transcript case can provoke; twinFixtureTests passes the fixture file's.

Parameters

Parameter	Type	Default value
`rules`	`GameRules`	`undefined`
`kase`	`TwinFixtureCase`	`undefined`
`schemaVersion`	`number`	`1`

Returns

string[]

gameContractFilename()

function gameContractFilename(game): string;

Defined in: server/packages/testkit/src/game-contract.ts:202

A useful default filename for scripts that accept an output directory.

Parameters

Parameter	Type
`game`	`string`

Returns

string

gameContractJson()

function gameContractJson(options): string;

Defined in: server/packages/testkit/src/game-contract.ts:183

Render one deterministic, newline-terminated contract document.

Parameters

Parameter	Type
`options`	`BuildGameContractOptions`

Returns

string

isRejected()

function isRejected(result): result is Rejected;

Defined in: server/packages/kernel/dist/index.d.ts:331

Type guard: did commit() refuse the intent?

Parameters

Parameter	Type
`result`	`CommitPlan` \| `Rejected`

Returns

result is Rejected

parseTwinFixtureFile()

function parseTwinFixtureFile(path, json): TwinFixtureFile;

Defined in: server/packages/testkit/src/twin-fixtures.ts:554

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.

Parameters

Parameter	Type
`path`	`string`
`json`	`unknown`

Returns

TwinFixtureFile

projectView()

function projectView(rules, args): SeatView;

Defined in: server/packages/testkit/src/kernel-scenarios.ts:39

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.

Parameters

Parameter	Type	Description
`rules`	`GameRules`	-
`args`	{ `cause?`: `TransitionCause`; `config`: `JsonObject`; `isReplay?`: `boolean`; `participantCount?`: `number`; `pending`: `number`[]; `seat`: `number` \| `null`; `state`: `JsonObject`; }	-
`args.cause?`	`TransitionCause`	-
`args.config`	`JsonObject`	-
`args.isReplay?`	`boolean`	-
`args.participantCount?`	`number`	-
`args.pending`	`number`[]	-
`args.seat`	`number` \| `null`	The seat to project for, or null for a viewer.
`args.state`	`JsonObject`	-

Returns

SeatView

randomSeed()

function randomSeed(): string;

Defined in: server/packages/kernel/dist/index.d.ts:338

A fresh base seed for a new game: 128 random bits, hex-encoded. Stored on the game's v0 state row and copied onto every later row (server-only, never expose it: the whole randomness of the game is derivable from it).

Returns

string

rngFixtureCase()

function rngFixtureCase(options): RngCase;

Defined in: server/packages/testkit/src/twin-fixtures.ts:994

Record one derived stream from the real kernel as a fixture case.

Parameters

Parameter	Type
`options`	`RngFixtureCaseOptions`

Returns

RngCase

twinFixtureTests()

function twinFixtureTests(gameModule, fixturesRoot): void;

Defined in: server/packages/testkit/src/twin-fixtures.ts:622

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.

Parameters

Parameter	Type
`gameModule`	`GameModule`
`fixturesRoot`	`string` \| `URL`

Returns

void

writeRngFixture()

function writeRngFixture(path, cases): void;

Defined in: server/packages/testkit/src/twin-fixtures.ts:1031

Write a fixture file of generated rng cases.

The schemaVersion is read from the v<N>/ directory in path, the same rule eigen-contract enforces over every fixture file, so the two can never be written out of agreement. The document is validated before it is written: a generator that emits something the runners would refuse to load should fail at the generator.

The output is plain two-space JSON. Only the values mean anything to either runner, so a repo that formats JSON should run its formatter afterwards.

import { rngFixtureCase, writeRngFixture } from "@eigeninteractive/testkit";

writeRngFixture("src/module/fixtures/v1/rng.json", [
  rngFixtureCase({ name: "version 0", seed: "twin-fixtures", version: 0, count: 16 }),
  rngFixtureCase({ name: "seat 1's bot stream", seed: "twin-fixtures", version: 3, seat: 1, count: 16 }),
]);

Parameters

Parameter	Type
`path`	`string`
`cases`	`RngCase`[]

Returns

void

References

DEADLINE_GRACE_MS

Re-exports DEADLINE_GRACE_MS

Interfaces​

ActionCase​

Properties​

action​

config​

expected​

Type Declaration​

observation?​

valid​

kind​

name​

obs?​

participantCount?​

pending​

playerIndex​

rngSeed?​

state​

BotSeatableCase​

Properties​

botConfig​

expected​

gameConfig​

kind​

name​

BuildGameContractOptions​

Extended by​

Properties​

fixturesRoot?​

game​

gameModule​

CommitInput​

Properties​

game​

intent​

now​

roster​

rules​

staleViews?​

current​

expected​

state​

CommitPlan​

Properties​

action​

effects​

frames​

nextState​

outcomes​

EmitGameContractOptions​

Extends​

Properties​

fixturesRoot?​

Inherited from​

game​

Inherited from​

gameModule​

Inherited from​

output​

ExpectedEnvelope​

Properties​

outcome?​

pending?​

state?​

GameContract​

Properties​

fixtures​

formatVersion​

game​

versions​

GameContractFixture​

Properties​

document​

path​

GameContractVersion​

Properties​

schemas​

action​

config​

observation​

state​

Interfaces

ActionCase

Properties

action

config

expected

Type Declaration

observation?

valid

kind

name

obs?

participantCount?

pending

playerIndex

rngSeed?

state

BotSeatableCase

Properties

botConfig

expected

gameConfig

kind

name

BuildGameContractOptions

Extended by

Properties

fixturesRoot?

game

gameModule

CommitInput

Properties

game

intent

now

roster

rules

staleViews?

current

expected

state

CommitPlan

Properties

action

effects

frames

nextState

outcomes

EmitGameContractOptions

Extends

Properties

fixturesRoot?

Inherited from

game

Inherited from

gameModule

Inherited from

output

ExpectedEnvelope

Properties

outcome?

pending?

state?

GameContract

Properties

fixtures

formatVersion

game

versions

GameContractFixture

Properties

document

path

GameContractVersion

Properties

schemas

action

config

observation

state