@eigeninteractive/testkit 0.6.1 → 0.8.0

package/README.md

@@ -14,6 +14,32 @@ import gameModule from "../../src/module/index.js";
 twinFixtureTests(gameModule, new URL("../../src/module/fixtures/", import.meta.url));
 ```
 
+A fixture case declares its `kind`:
+
+| kind | what it pins |
+|---|---|
+| `action` | `applyAction`, and the actor's post-action observation |
+| `initialState` | the opening envelope, drawn from the version-0 stream |
+| `lifecycle` | `applyLifecycle` for a timeout, a resign, or an account purge |
+| `transcript` | a whole match, replayed through the real kernel |
+| `rng` | recorded `deriveRng` draws, compared exactly |
+| `playerLimits`, `ratingPool`, `botSeatable` | the predicates |
+
+The format itself is documented at the top of `src/twin-fixtures.ts`, which is
+the normative description both runners follow.
+
+`rng` cases are generated rather than written, because their values are the
+kernel's own and the Dart port has to reproduce them bit for bit:
+
+```ts
+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 }),
+]);
+```
+
 `eigen-contract` imports the default `src/module/index.ts`, validates every
 `fixtures/v<N>/*.json` against the registered version, and emits
 `game-contract.json`. Use `eigen-contract --check` in CI.

package/dist/contract-cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as emitConfiguredGameContract, t as checkConfiguredGameContract } from "./contract-command-aCqO5CyJ.js";
+import { n as emitConfiguredGameContract, t as checkConfiguredGameContract } from "./contract-command-Dn5ANpqD.js";
 import { parseArgs } from "node:util";
 //#region src/contract-cli.ts
 try {

package/dist/{contract-command-aCqO5CyJ.js → contract-command-Dn5ANpqD.js}

@@ -3,6 +3,7 @@ import { basename, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { tsImport } from "tsx/esm/api";
 import { IllegalMoveError, assertPortableSchema } from "@eigeninteractive/rules";
+import { GameBugError, assertForfeitPending, commit, deriveRng, isRejected } from "@eigeninteractive/kernel";
 import Rand from "rand-seed";
 import { it } from "vitest";
 //#region src/twin-fixtures.ts
@@ -14,9 +15,9 @@ import { it } from "vitest";
 *
 * 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,
+* runs each case against the TS unit (schemas + the four hooks + the two
+* predicates, and whole matches through the real kernel), 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.
 *
@@ -55,7 +56,58 @@ import { it } from "vitest";
 *     { "kind": "ratingPool",  "name": "...", "access": "public",
 *       "minPlayers": 2, "maxPlayers": 2, "config": {}, "expected": "blitz" },
 *     { "kind": "botSeatable", "name": "...", "gameConfig": {},
-*       "botConfig": {}, "expected": false }
+*       "botConfig": {}, "expected": false },
+*     {
+*       "kind": "initialState",
+*       "name": "a fresh board seats both players",
+*       "config": { ... },
+*       "playerCount": 2,
+*       "rngSeed": "any string",     // optional, default "twin-fixtures"
+*       "expected": {                // the envelope block the action case
+*         "state": { ... },          //   records, minus `valid`
+*         "pending": [0, 1],
+*         "outcome": null
+*       }
+*     },
+*     {
+*       "kind": "lifecycle",
+*       "name": "a forfeit hands the match to the other seat",
+*       "config": { ... },
+*       "state": { ... },            // applyLifecycle input
+*       "pending": [0, 1],
+*       "type": "forfeit",           // timeout | forfeit | autoForfeit
+*       "playerIndex": 0,            // required for forfeit/autoForfeit,
+*                                    //   forbidden for timeout
+*       "participantCount": 2,       // optional, default 2
+*       "rngSeed": "any string",     // optional, default "twin-fixtures"
+*       "expected": { "state": { ... }, "pending": [], "outcome": [ ... ] }
+*     },
+*     {
+*       "kind": "transcript",
+*       "name": "a best-of-one match played to its finish",
+*       "config": { ... },
+*       "playerCount": 2,
+*       "seed": "the game's base rng seed",
+*       "transitions": [
+*         { "kind": "game", "playerIndex": 0, "data": { ... } },
+*         { "kind": "lifecycle", "type": "forfeit", "playerIndex": 1 }
+*       ],
+*       "expected": {
+*         "version": 3,              // the final committed state version
+*         "status": "finished",      // active | finished
+*         "state": { ... },          // optional, as above
+*         "pending": [],
+*         "outcome": [ ... ]
+*       }
+*     },
+*     {
+*       "kind": "rng",
+*       "name": "the stream initialState draws from",
+*       "seed": "twin-fixtures",
+*       "version": 0,
+*       "seat": 1,                   // optional; present ⇒ the bot stream
+*       "draws": [0.123, 0.456]      // 1..64 values, compared exactly
+*     }
 *   ]
 * }
 * ```
@@ -66,6 +118,34 @@ import { it } from "vitest";
 * state to it, and a Dart `previewAction` that returns non-null must predict
 * it, so the two sides are compared through one recorded value.
 *
+* ## What each kind records
+*
+* `action`, `playerLimits`, `ratingPool` and `botSeatable` pin one hook or
+* predicate. The four kinds below exist for offline play (architecture
+* decision 0012): a device runs the Dart twin through a Dart port of the
+* kernel, so the pieces the online client never had to reproduce — the
+* opening state, the lifecycle hooks, a whole match, and the random stream
+* itself — each need a recorded behavior of their own.
+*
+* - `initialState` runs `initialState` with `deriveRng(rngSeed, 0)`, the
+*   version-0 stream the engine's `start` commit derives, and checks the
+*   returned envelope exactly as the action case does.
+* - `lifecycle` runs `applyLifecycle` with the `data` payload the kernel
+*   builds (`{type:"timeout"}`, or `{type, playerIndex}`), then applies the
+*   kernel's forfeit guard: a forfeit must remove its own seat from pending.
+*   Like the action case, and unlike `initialState`, it draws from the raw
+*   `rngSeed` stream: a standalone hook case has no version to derive from.
+* - `transcript` replays an ordered match through the REAL kernel `commit()`,
+*   so every engine guard, the pending/version bookkeeping, and the
+*   per-transition `deriveRng(seed, version)` streams all participate. It is
+*   the case a Dart local kernel has to reproduce move for move, on the
+*   untimed table and with the human/bot roster {@link evaluateTranscript}
+*   documents.
+* - `rng` records raw `deriveRng` draws. Generated from the TypeScript kernel
+*   by {@link rngFixtureCase} / {@link writeRngFixture} and compared with
+*   `===`, no tolerance: the Dart port is required to be bit-identical, and a
+*   port that is merely close is a port that desynchronizes one draw later.
+*
 * Wire it up in a game-owned test file running under plain-Node vitest:
 *
 * ```ts
@@ -75,6 +155,20 @@ import { it } from "vitest";
 * twinFixtureTests(gameModule, new URL("../src/module/fixtures/", import.meta.url));
 * ```
 */
+/** The stream a case draws from when it names no `rngSeed`. */
+const DEFAULT_RNG_SEED = "twin-fixtures";
+/** Every `kind` a fixture case may declare, in the order the error messages
+* and the evaluator switch list them. */
+const CASE_KINDS = [
+	"action",
+	"playerLimits",
+	"ratingPool",
+	"botSeatable",
+	"initialState",
+	"lifecycle",
+	"transcript",
+	"rng"
+];
 function describe(value) {
 	if (value === null) return "null";
 	if (Array.isArray(value)) return "an array";
@@ -103,24 +197,38 @@ function asNumberArray(where, v) {
 	if (!Array.isArray(v)) fail(where, "an array of numbers", v);
 	return v.map((n, i) => asNumber(`${where}[${i}]`, n));
 }
+/** A seat index, a seat count, or a state version: the fixture format has no
+* fractional or negative counts anywhere. */
+function asIndex(where, v) {
+	const n = asNumber(where, v);
+	if (!Number.isInteger(n) || n < 0) throw new Error(`${where}: expected a non-negative integer, got ${JSON.stringify(v)}`);
+	return n;
+}
 /** Applies `read` only when the key is present and non-null; absent and
 * explicit null both mean "not specified" for every optional fixture field. */
 function optional(where, v, read) {
 	return v === void 0 || v === null ? void 0 : read(where, v);
 }
+/** The `expected` block every hook-running case shares. */
+function parseExpectedEnvelope(where, raw) {
+	const expected = {
+		state: optional(`${where}.state`, raw.state, asObject),
+		pending: optional(`${where}.pending`, raw.pending, asNumberArray)
+	};
+	if ("outcome" in raw) {
+		const outcome = raw.outcome;
+		if (outcome !== null && !Array.isArray(outcome)) fail(`${where}.outcome`, "an array or null", outcome);
+		expected.outcome = outcome;
+	}
+	return expected;
+}
 function parseActionCase(where, raw) {
 	const expectedRaw = asObject(`${where}.expected`, raw.expected);
 	const expected = {
+		...parseExpectedEnvelope(`${where}.expected`, expectedRaw),
 		valid: asBoolean(`${where}.expected.valid`, expectedRaw.valid),
-		state: optional(`${where}.expected.state`, expectedRaw.state, asObject),
-		pending: optional(`${where}.expected.pending`, expectedRaw.pending, asNumberArray),
 		observation: optional(`${where}.expected.observation`, expectedRaw.observation, asObject)
 	};
-	if ("outcome" in expectedRaw) {
-		const outcome = expectedRaw.outcome;
-		if (outcome !== null && !Array.isArray(outcome)) fail(`${where}.expected.outcome`, "an array or null", outcome);
-		expected.outcome = outcome;
-	}
 	return {
 		kind: "action",
 		name: asString(`${where}.name`, raw.name),
@@ -172,6 +280,90 @@ function parseBotSeatableCase(where, raw) {
 		expected: asBoolean(`${where}.expected`, raw.expected)
 	};
 }
+function parseInitialStateCase(where, raw) {
+	return {
+		kind: "initialState",
+		name: asString(`${where}.name`, raw.name),
+		config: asObject(`${where}.config`, raw.config),
+		playerCount: asIndex(`${where}.playerCount`, raw.playerCount),
+		rngSeed: optional(`${where}.rngSeed`, raw.rngSeed, asString),
+		expected: parseExpectedEnvelope(`${where}.expected`, asObject(`${where}.expected`, raw.expected))
+	};
+}
+function parseLifecycleCase(where, raw) {
+	const type = asString(`${where}.type`, raw.type);
+	if (type !== "timeout" && type !== "forfeit" && type !== "autoForfeit") throw new Error(`${where}.type: expected one of timeout | forfeit | autoForfeit, got ${JSON.stringify(raw.type)}`);
+	const playerIndex = optional(`${where}.playerIndex`, raw.playerIndex, asIndex);
+	if (type === "timeout" && playerIndex !== void 0) throw new Error(`${where}.playerIndex: a timeout carries no seat (its victims are "pending"); remove it`);
+	if (type !== "timeout" && playerIndex === void 0) throw new Error(`${where}.playerIndex: a ${type} must name the forfeiting seat`);
+	return {
+		kind: "lifecycle",
+		name: asString(`${where}.name`, raw.name),
+		config: asObject(`${where}.config`, raw.config),
+		state: asObject(`${where}.state`, raw.state),
+		pending: asNumberArray(`${where}.pending`, raw.pending),
+		type,
+		playerIndex,
+		participantCount: optional(`${where}.participantCount`, raw.participantCount, asNumber),
+		rngSeed: optional(`${where}.rngSeed`, raw.rngSeed, asString),
+		expected: parseExpectedEnvelope(`${where}.expected`, asObject(`${where}.expected`, raw.expected))
+	};
+}
+function parseTranscriptTransition(where, raw) {
+	const obj = asObject(where, raw);
+	switch (obj.kind) {
+		case "game": return {
+			kind: "game",
+			playerIndex: asIndex(`${where}.playerIndex`, obj.playerIndex),
+			data: asObject(`${where}.data`, obj.data)
+		};
+		case "lifecycle": {
+			const type = asString(`${where}.type`, obj.type);
+			if (type !== "forfeit") throw new Error(`${where}.type: expected forfeit, got ${JSON.stringify(obj.type)}`);
+			return {
+				kind: "lifecycle",
+				type,
+				playerIndex: asIndex(`${where}.playerIndex`, obj.playerIndex)
+			};
+		}
+		default: throw new Error(`${where}.kind: expected one of game | lifecycle, got ${JSON.stringify(obj.kind)}`);
+	}
+}
+function parseTranscriptCase(where, raw) {
+	const expectedRaw = asObject(`${where}.expected`, raw.expected);
+	const status = asString(`${where}.expected.status`, expectedRaw.status);
+	if (status !== "active" && status !== "finished") throw new Error(`${where}.expected.status: expected one of active | finished, got ${JSON.stringify(expectedRaw.status)}`);
+	if (!Array.isArray(raw.transitions)) fail(`${where}.transitions`, "an array", raw.transitions);
+	return {
+		kind: "transcript",
+		name: asString(`${where}.name`, raw.name),
+		config: asObject(`${where}.config`, raw.config),
+		playerCount: asIndex(`${where}.playerCount`, raw.playerCount),
+		seed: asString(`${where}.seed`, raw.seed),
+		transitions: raw.transitions.map((transition, i) => parseTranscriptTransition(`${where}.transitions[${i}]`, transition)),
+		expected: {
+			...parseExpectedEnvelope(`${where}.expected`, expectedRaw),
+			version: asIndex(`${where}.expected.version`, expectedRaw.version),
+			status
+		}
+	};
+}
+/** The draw count one rng case may record. One is enough to catch a wrong
+* seeding; the cap keeps a fixture file a document rather than a data dump,
+* and a stream that agrees for 64 draws does not diverge at 65. */
+const RNG_DRAW_LIMIT = 64;
+function parseRngCase(where, raw) {
+	if (!Array.isArray(raw.draws)) fail(`${where}.draws`, "an array of numbers", raw.draws);
+	if (raw.draws.length === 0 || raw.draws.length > RNG_DRAW_LIMIT) throw new Error(`${where}.draws: expected between 1 and ${RNG_DRAW_LIMIT} draws, got ${raw.draws.length}`);
+	return {
+		kind: "rng",
+		name: asString(`${where}.name`, raw.name),
+		seed: asString(`${where}.seed`, raw.seed),
+		version: asIndex(`${where}.version`, raw.version),
+		seat: optional(`${where}.seat`, raw.seat, asIndex),
+		draws: asNumberArray(`${where}.draws`, raw.draws)
+	};
+}
 /** 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. */
@@ -190,21 +382,34 @@ function parseTwinFixtureFile(path, json) {
 				case "playerLimits": return parsePlayerLimitsCase(where, obj);
 				case "ratingPool": return parseRatingPoolCase(where, obj);
 				case "botSeatable": return parseBotSeatableCase(where, obj);
-				default: throw new Error(`${where}.kind: expected one of action | playerLimits | ratingPool | botSeatable, got ${JSON.stringify(obj.kind)}`);
+				case "initialState": return parseInitialStateCase(where, obj);
+				case "lifecycle": return parseLifecycleCase(where, obj);
+				case "transcript": return parseTranscriptCase(where, obj);
+				case "rng": return parseRngCase(where, obj);
+				default: throw new Error(`${where}.kind: expected one of ${CASE_KINDS.join(" | ")}, got ${JSON.stringify(obj.kind)}`);
 			}
 		})
 	};
 }
 /** Run one fixture case against a rules unit, returning failure descriptions
 * (empty ⇒ the case passes). Pure; the file-reading test registrar is
-* {@link twinFixtureTests}. */
-function evaluateTwinCase(rules, kase) {
+* {@link 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;
+* {@link twinFixtureTests} passes the fixture file's. */
+function evaluateTwinCase(rules, kase, schemaVersion = 1) {
 	switch (kase.kind) {
 		case "action": return evaluateAction(rules, kase);
 		case "playerLimits": return evaluatePlayerLimits(rules, kase);
 		case "ratingPool": return evaluateRatingPool(rules, kase);
 		case "botSeatable": return evaluateBotSeatable(rules, kase);
-		default: return [`unknown case kind "${kase.kind}", expected action | playerLimits | ratingPool | botSeatable`];
+		case "initialState": return evaluateInitialState(rules, kase);
+		case "lifecycle": return evaluateLifecycle(rules, kase, schemaVersion);
+		case "transcript": return evaluateTranscript(rules, kase, schemaVersion);
+		case "rng": return evaluateRng(kase);
+		default: return [`unknown case kind "${kase.kind}", expected ${CASE_KINDS.join(" | ")}`];
 	}
 }
 /** Register one vitest test per fixture case found under `fixturesRoot`
@@ -216,7 +421,7 @@ function twinFixtureTests(gameModule, fixturesRoot) {
 		const rules = gameModule.versions[fixture.schemaVersion];
 		for (const kase of fixture.cases) it(`twin v${fixture.schemaVersion}: ${kase.name}`, () => {
 			if (!rules) throw new Error(`gameModule ships no rules unit for schemaVersion ${fixture.schemaVersion} (fixture: ${filePath})`);
-			const failures = evaluateTwinCase(rules, kase);
+			const failures = evaluateTwinCase(rules, kase, fixture.schemaVersion);
 			if (failures.length) throw new Error(`\n${failures.join("\n")}`);
 		});
 	}
@@ -240,7 +445,7 @@ function evaluateAction(rules, kase) {
 		if (envelope) failures.push(envelope);
 		return failures;
 	}
-	checkEnvelope(rules, kase, envelope, failures);
+	checkEnvelope(rules, "applyAction", kase.expected, envelope, failures);
 	if (kase.expected.observation !== void 0) checkObservation(rules, kase, envelope, config, action, failures);
 	return failures;
 }
@@ -255,7 +460,7 @@ function applyFixtureAction(rules, kase, config, state, action) {
 			pending: kase.pending,
 			data: action,
 			playerIndex: kase.playerIndex,
-			rng: new Rand(kase.rngSeed ?? "twin-fixtures"),
+			rng: hookRng(kase.rngSeed),
 			config
 		});
 	} catch (error) {
@@ -264,9 +469,19 @@ function applyFixtureAction(rules, kase, config, state, action) {
 	}
 	return kase.expected.valid ? envelope : "applyAction accepted a move the fixture expects to be illegal";
 }
-function checkEnvelope(rules, kase, envelope, failures) {
-	if (validate(rules, "state", envelope.state) === void 0) failures.push("applyAction returned state that violates its own schema");
-	const expected = kase.expected;
+/** The stream a standalone hook case draws from. Seeded with the fixture's
+* `rngSeed` verbatim rather than through `deriveRng`, because a single hook
+* case stands outside any game: it has no committed version to derive a
+* stream from. The `initialState` case is the exception — a game's opening
+* transition is always version 0 — and a `transcript` case, which runs the
+* real kernel, gets the real per-version streams. */
+function hookRng(rngSeed) {
+	return new Rand(rngSeed ?? DEFAULT_RNG_SEED);
+}
+/** Compare a hook's envelope with what a case recorded, and re-validate the
+* state it returned exactly as the engine does before committing it. */
+function checkEnvelope(rules, hook, expected, envelope, failures) {
+	if (validate(rules, "state", envelope.state) === void 0) failures.push(`${hook} returned state that violates its own schema`);
 	if (expected.state !== void 0 && !deepEquals(envelope.state, expected.state)) failures.push(`envelope.state mismatch, got ${JSON.stringify(envelope.state)}`);
 	if (expected.pending !== void 0 && !deepEquals(envelope.pendingPlayers, expected.pending)) failures.push(`envelope.pendingPlayers mismatch, got ${JSON.stringify(envelope.pendingPlayers)}`);
 	if ("outcome" in expected && !deepEquals(envelope.outcome ?? null, expected.outcome ?? null)) failures.push(`envelope.outcome mismatch, got ${JSON.stringify(envelope.outcome ?? null)}`);
@@ -328,6 +543,227 @@ function evaluateBotSeatable(rules, kase) {
 	if (seatable !== kase.expected) failures.push(`botSeatable returned ${seatable}, fixture expects ${kase.expected}`);
 	return failures;
 }
+function evaluateInitialState(rules, kase) {
+	const failures = [];
+	const config = parseWith(rules, "config", kase.config, failures);
+	if (config === void 0) return failures;
+	let envelope;
+	try {
+		envelope = rules.initialState({
+			config,
+			rng: deriveRng(kase.rngSeed ?? DEFAULT_RNG_SEED, 0),
+			playerCount: kase.playerCount
+		});
+	} catch (error) {
+		failures.push(`initialState threw: ${error}`);
+		return failures;
+	}
+	checkEnvelope(rules, "initialState", kase.expected, envelope, failures);
+	return failures;
+}
+function evaluateLifecycle(rules, kase, schemaVersion) {
+	const failures = [];
+	const config = parseWith(rules, "config", kase.config, failures);
+	const state = parseWith(rules, "state", kase.state, failures);
+	if (config === void 0 || state === void 0) return failures;
+	const data = kase.type === "timeout" ? { type: "timeout" } : {
+		type: kase.type,
+		playerIndex: kase.playerIndex
+	};
+	let envelope;
+	try {
+		envelope = rules.applyLifecycle({
+			state,
+			pending: kase.pending,
+			type: kase.type,
+			data,
+			rng: hookRng(kase.rngSeed),
+			config
+		});
+	} catch (error) {
+		failures.push(`applyLifecycle threw: ${error}`);
+		return failures;
+	}
+	checkEnvelope(rules, "applyLifecycle", kase.expected, envelope, failures);
+	if (data.type !== "timeout") try {
+		assertForfeitPending(data.playerIndex, envelope, schemaVersion);
+	} catch (error) {
+		failures.push(`${error instanceof Error ? error.message : error}`);
+	}
+	return failures;
+}
+/**
+* Replay an ordered match through the real kernel.
+*
+* The table is the one a local (offline) game plays on, and the conventions
+* below are a contract with the Dart local kernel that replays the same file:
+*
+* - untimed and unrated (`turnSeconds`, `budgetSeconds`, `incrementSeconds`
+*   all null), so no deadline is ever armed and the clock is never read;
+* - a roster of `playerCount` identified seats: seat 0 is the human
+*   `user-0`, every other seat is the bot `bot-<seat>`;
+* - the match opens with a `start` intent carrying the case's `seed`, so
+*   every transition draws from `deriveRng(seed, version)`;
+* - each transition commits at `expectedVersion` = the current version (a
+*   device is the only actor, so it is never stale), with `actor` `"user"`
+*   for seat 0 and `"bot"` for the rest.
+*
+* A rejection or a broken invariant fails the case naming the transition that
+* produced it: an engine that refuses the transcript is as much a divergence
+* as a wrong final state.
+*/
+function evaluateTranscript(rules, kase, schemaVersion) {
+	const failures = [];
+	if (parseWith(rules, "config", kase.config, failures) === void 0) return failures;
+	const game = {
+		status: "ready",
+		schemaVersion,
+		config: kase.config,
+		turnSeconds: null,
+		budgetSeconds: null,
+		incrementSeconds: null,
+		rated: false,
+		ratingPool: null
+	};
+	const roster = Array.from({ length: kase.playerCount }, (_, seat) => seat === 0 ? {
+		playerIndex: 0,
+		userId: "user-0",
+		botId: null,
+		type: "human"
+	} : {
+		playerIndex: seat,
+		userId: null,
+		botId: `bot-${seat}`,
+		type: "bot"
+	});
+	let plan = runCommit({
+		game,
+		state: null,
+		roster,
+		intent: {
+			kind: "start",
+			seed: kase.seed
+		},
+		now: TRANSCRIPT_NOW,
+		rules
+	});
+	if (typeof plan === "string") return [`start: ${plan}`];
+	game.status = "active";
+	for (const [index, transition] of kase.transitions.entries()) {
+		const intent = transition.kind === "game" ? {
+			kind: "action",
+			seat: transition.playerIndex,
+			expectedVersion: plan.nextState.version,
+			data: transition.data,
+			actor: transition.playerIndex === 0 ? "user" : "bot"
+		} : {
+			kind: "lifecycle",
+			type: "forfeit",
+			seat: transition.playerIndex
+		};
+		const result = runCommit({
+			game,
+			state: plan.nextState,
+			roster,
+			intent,
+			now: TRANSCRIPT_NOW,
+			rules
+		});
+		if (typeof result === "string") return [`transitions[${index}] (${describeTransition(transition)}): ${result}`];
+		plan = result;
+		if (plan.outcomes !== null) game.status = "finished";
+	}
+	const status = plan.outcomes === null ? "active" : "finished";
+	if (plan.nextState.version !== kase.expected.version) failures.push(`the match committed as version ${plan.nextState.version}, fixture expects ${kase.expected.version}`);
+	if (status !== kase.expected.status) failures.push(`the match is ${status}, fixture expects ${kase.expected.status}`);
+	checkEnvelope(rules, "the final transition", kase.expected, {
+		state: plan.nextState.state,
+		pendingPlayers: plan.nextState.pending,
+		...plan.outcomes === null ? {} : { outcome: plan.outcomes }
+	}, failures);
+	return failures;
+}
+/** The commit instant every transcript transition carries. An untimed game
+* never reads it, and a fixed value keeps the case a pure function of the
+* transcript. */
+const TRANSCRIPT_NOW = 0;
+/** One kernel commit, with both failure species rendered as a string: a
+* rejection (a value) and a broken invariant (a throw) are equally a
+* transcript that does not replay. */
+function runCommit(input) {
+	let result;
+	try {
+		result = commit(input);
+	} catch (error) {
+		if (error instanceof GameBugError) return `the engine refused the hook result: ${error.message}`;
+		return `commit threw: ${error}`;
+	}
+	if (isRejected(result)) return `the engine rejected the intent (${result.code}): ${result.message}`;
+	return result;
+}
+function describeTransition(transition) {
+	return transition.kind === "game" ? `seat ${transition.playerIndex} plays ${JSON.stringify(transition.data)}` : `seat ${transition.playerIndex} forfeits`;
+}
+function evaluateRng(kase) {
+	const rng = rngStream(kase.seed, kase.version, kase.seat);
+	const failures = [];
+	for (const [index, expected] of kase.draws.entries()) {
+		const draw = rng.next();
+		if (draw !== expected) failures.push(`draw[${index}] is ${draw}, fixture records ${expected}`);
+	}
+	return failures;
+}
+/** The stream an {@link RngCase} describes: a transition's own stream, or,
+* when the case names a seat, the bot stream the Durable Object derives for
+* that seat before running its brain. */
+function rngStream(seed, version, seat) {
+	return seat === void 0 ? deriveRng(seed, version) : deriveRng(`${seed}:bot${seat}`, version);
+}
+/** Record one derived stream from the real kernel as a fixture case. */
+function rngFixtureCase(options) {
+	const { name, seed, version, seat, count } = options;
+	if (!Number.isInteger(count) || count < 1 || count > RNG_DRAW_LIMIT) throw new Error(`rngFixtureCase(${JSON.stringify(name)}): count must be an integer between 1 and ${RNG_DRAW_LIMIT}, got ${count}`);
+	const rng = rngStream(seed, version, seat);
+	return {
+		kind: "rng",
+		name,
+		seed,
+		version,
+		...seat === void 0 ? {} : { seat },
+		draws: Array.from({ length: count }, () => rng.next())
+	};
+}
+/**
+* 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.
+*
+* ```ts
+* 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 }),
+* ]);
+* ```
+*/
+function writeRngFixture(path, cases) {
+	const match = /(?:^|\/)v([1-9]\d*)\/[^/]+$/.exec(path.split("\\").join("/"));
+	if (match === null) throw new Error(`${path}: an rng fixture must be written into a v<N>/ directory, which names the schemaVersion it targets`);
+	const document = {
+		schemaVersion: Number(match[1]),
+		cases
+	};
+	parseTwinFixtureFile(path, document);
+	writeFileSync(path, `${JSON.stringify(document, null, 2)}\n`);
+}
 /** Run one of the unit's Standard Schemas synchronously, returning the parsed
 * value or undefined on failure (issues written to the second return slot). */
 function validate(rules, which, value, issues) {
@@ -537,6 +973,6 @@ async function checkConfiguredGameContract(root = process.cwd()) {
 	checkGameContract(await configuredGameContractOptions(root));
 }
 //#endregion
-export { checkGameContract as a, gameContractJson as c, parseTwinFixtureFile as d, twinFixtureTests as f, buildGameContract as i, deepEquals as l, emitConfiguredGameContract as n, emitGameContract as o, GAME_CONTRACT_FORMAT_VERSION as r, gameContractFilename as s, checkConfiguredGameContract as t, evaluateTwinCase as u };
+export { checkGameContract as a, gameContractJson as c, parseTwinFixtureFile as d, rngFixtureCase as f, buildGameContract as i, deepEquals as l, writeRngFixture as m, emitConfiguredGameContract as n, emitGameContract as o, twinFixtureTests as p, GAME_CONTRACT_FORMAT_VERSION as r, gameContractFilename as s, checkConfiguredGameContract as t, evaluateTwinCase as u };
 
-//# sourceMappingURL=contract-command-aCqO5CyJ.js.map
+//# sourceMappingURL=contract-command-Dn5ANpqD.js.map