@joystyk/testing 0.0.0-stage → 0.2.0

package/dist/fixtures/nim.d.ts

@@ -0,0 +1,34 @@
+import { type Migration, type SeatId } from '@joystyk/contracts';
+import type { EngineConformanceOptions } from '../engine-conformance.js';
+export type NimState = {
+    readonly heap: number;
+    readonly turn: SeatId;
+    readonly winner: SeatId | null;
+    readonly moves: number;
+};
+export type NimCommand = {
+    readonly type: 'take';
+    readonly count: number;
+};
+export type NimView = NimState;
+export type NimEvent = {
+    readonly type: 'took';
+    readonly seat: SeatId;
+    readonly count: number;
+} | {
+    readonly type: 'resigned';
+    readonly seat: SeatId;
+};
+export type NimConfig = {
+    readonly heap: number;
+};
+export declare const isNimState: (v: unknown) => v is NimState;
+/** The current save version of Nim's state. */
+export declare const NIM_SAVE_VERSION = 2;
+/** v1 → v2 added `moves`; a v1 save restarts the count at 0. */
+export declare const nimMigrations: readonly Migration[];
+/** Stored states for every shipped save version. */
+export declare const nimSaveFixtures: import("../builders.js").SaveFixture[];
+export declare const nim: import("@joystyk/contracts").DiscreteEngine<NimState, NimCommand, NimState, NimEvent, NimConfig>;
+/** Conformance options for the Nim fixture. */
+export declare const nimConformance: EngineConformanceOptions<NimState, NimCommand, NimConfig>;

package/dist/fixtures/nim.js

@@ -0,0 +1,141 @@
+import { guardSchema, saveFixture } from "../builders.js";
+import { isInt, isRecord, isSeat, isSeatOrNull } from "./guards.js";
+import { defineEngine, err, gameError, ok } from "@joystyk/contracts";
+//#region src/fixtures/nim.ts
+var isNimState = (v) => isRecord(v) && isInt(v["heap"], 0) && isSeat(v["turn"]) && v["turn"] < 2 && isSeatOrNull(v["winner"]) && isInt(v["moves"], 0);
+var isNimCommand = (v) => isRecord(v) && v["type"] === "take" && isInt(v["count"]);
+var isNimEvent = (v) => isRecord(v) && (v["type"] === "took" && isSeat(v["seat"]) && isInt(v["count"]) || v["type"] === "resigned" && isSeat(v["seat"]));
+var isNimConfig = (v) => isRecord(v) && isInt(v["heap"], 1, 1e3);
+/** The current save version of Nim's state. */
+var NIM_SAVE_VERSION = 2;
+/** v1 → v2 added `moves`; a v1 save restarts the count at 0. */
+var nimMigrations = [{
+	from: 1,
+	to: 2,
+	migrate: (old) => isRecord(old) ? ok({
+		...old,
+		moves: 0
+	}) : err(gameError("BadSave", "This saved game is damaged."))
+}];
+/** Stored states for every shipped save version. */
+var nimSaveFixtures = [saveFixture("v1 mid-game", 1, {
+	heap: 7,
+	turn: 1,
+	winner: null
+}), saveFixture("v2 finished", 2, {
+	heap: 0,
+	turn: 0,
+	winner: 1,
+	moves: 6
+})];
+var legalCounts = (heap) => [
+	1,
+	2,
+	3
+].filter((n) => n <= heap);
+var nim = defineEngine({
+	rulesVersion: 1,
+	schemas: {
+		config: guardSchema(isNimConfig, "Expected { heap }."),
+		command: guardSchema(isNimCommand, "Expected { type: \"take\", count }."),
+		state: guardSchema(isNimState, "Not a Nim state."),
+		view: guardSchema(isNimState, "Not a Nim view."),
+		event: guardSchema(isNimEvent, "Not a Nim event.")
+	},
+	init: (config, seats, rng) => seats.length === 2 ? ok({
+		heap: config.heap,
+		turn: rng.int(0, 2),
+		winner: null,
+		moves: 0
+	}) : err(gameError("Seats", "Nim needs two players.")),
+	apply: (state, input) => {
+		if (state.winner !== null) return err(gameError("GameOver", "The game is over."));
+		switch (input.kind) {
+			case "command": {
+				if (input.seat !== state.turn) return err(gameError("NotYourTurn", "It's not your turn."));
+				const { count } = input.command;
+				if (!legalCounts(state.heap).includes(count)) return err(gameError("IllegalMove", "Take one, two or three.", { count }));
+				const heap = state.heap - count;
+				const next = {
+					heap,
+					turn: 1 - state.turn,
+					winner: heap === 0 ? input.seat : null,
+					moves: state.moves + 1
+				};
+				return ok({
+					state: next,
+					beats: [{ event: {
+						type: "took",
+						seat: input.seat,
+						count
+					} }]
+				});
+			}
+			case "resign":
+				if (input.seat !== 0 && input.seat !== 1) return err(gameError("NoSuchSeat", "There is no such seat."));
+				return ok({
+					state: {
+						...state,
+						winner: 1 - input.seat
+					},
+					beats: [{ event: {
+						type: "resigned",
+						seat: input.seat
+					} }]
+				});
+			default: return err(gameError("Unsupported", "Nim has no clocks, seat changes or jobs."));
+		}
+	},
+	pending: (state) => state.winner === null ? [state.turn] : [],
+	viewFor: (state) => state,
+	eventFor: (event) => event,
+	outcome: (state) => state.winner === null ? null : {
+		result: "won",
+		placements: [{
+			seat: state.winner,
+			place: 1
+		}, {
+			seat: 1 - state.winner,
+			place: 2
+		}],
+		summary: `Seat ${state.winner + 1} wins.`,
+		stats: { moves: state.moves }
+	},
+	ai: {
+		levels: ["random", "perfect"],
+		choose: (view, _seat, level, rng) => {
+			const counts = legalCounts(view.heap);
+			const perfect = view.heap % 4;
+			return {
+				type: "take",
+				count: level === "perfect" && perfect > 0 ? perfect : counts[rng.int(0, counts.length)] ?? 1
+			};
+		}
+	}
+});
+/** Conformance options for the Nim fixture. */
+var nimConformance = {
+	name: "nim",
+	configs: [{ heap: 5 }, { heap: 21 }],
+	seatCounts: [2],
+	commands: () => [
+		0,
+		1,
+		2,
+		3,
+		4
+	].map((count) => ({
+		type: "take",
+		count
+	})),
+	invariants: (s) => s.heap < 0 ? "the heap is negative" : s.heap === 0 && s.winner === null ? "an empty heap without a winner" : true,
+	saves: {
+		version: 2,
+		migrations: nimMigrations,
+		fixtures: nimSaveFixtures
+	}
+};
+//#endregion
+export { NIM_SAVE_VERSION, isNimState, nim, nimConformance, nimMigrations, nimSaveFixtures };
+
+//# sourceMappingURL=nim.js.map

package/dist/fixtures/nim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nim.js","names":[],"sources":["../../src/fixtures/nim.ts"],"sourcesContent":["// Nim: two players take one to three from a heap; whoever takes the last one wins. All state\n// is public. The fixture also has a save history (v1 lacked the move counter) and an AI.\n\nimport { defineEngine, err, gameError, ok, type Json, type Migration, type SeatId } from '@joystyk/contracts';\nimport { guardSchema, saveFixture } from '../builders.ts';\nimport type { EngineConformanceOptions } from '../engine-conformance.ts';\nimport { isInt, isRecord, isSeat, isSeatOrNull } from './guards.ts';\n\nexport type NimState = {\n  readonly heap: number;\n  readonly turn: SeatId;\n  readonly winner: SeatId | null;\n  readonly moves: number;\n};\nexport type NimCommand = { readonly type: 'take'; readonly count: number };\nexport type NimView = NimState;\nexport type NimEvent =\n  | { readonly type: 'took'; readonly seat: SeatId; readonly count: number }\n  | { readonly type: 'resigned'; readonly seat: SeatId };\nexport type NimConfig = { readonly heap: number };\n\nexport const isNimState = (v: unknown): v is NimState =>\n  isRecord(v) &&\n  isInt(v['heap'], 0) &&\n  isSeat(v['turn']) &&\n  v['turn'] < 2 &&\n  isSeatOrNull(v['winner']) &&\n  isInt(v['moves'], 0);\nconst isNimCommand = (v: unknown): v is NimCommand => isRecord(v) && v['type'] === 'take' && isInt(v['count']);\nconst isNimEvent = (v: unknown): v is NimEvent =>\n  isRecord(v) &&\n  ((v['type'] === 'took' && isSeat(v['seat']) && isInt(v['count'])) || (v['type'] === 'resigned' && isSeat(v['seat'])));\nconst isNimConfig = (v: unknown): v is NimConfig => isRecord(v) && isInt(v['heap'], 1, 1000);\n\n/** The current save version of Nim's state. */\nexport const NIM_SAVE_VERSION = 2;\n\n/** v1 → v2 added `moves`; a v1 save restarts the count at 0. */\nexport const nimMigrations: readonly Migration[] = [\n  {\n    from: 1,\n    to: 2,\n    migrate: (old: Json) =>\n      isRecord(old) ? ok({ ...old, moves: 0 }) : err(gameError('BadSave', 'This saved game is damaged.')),\n  },\n];\n\n/** Stored states for every shipped save version. */\nexport const nimSaveFixtures = [\n  saveFixture('v1 mid-game', 1, { heap: 7, turn: 1, winner: null }),\n  saveFixture('v2 finished', 2, { heap: 0, turn: 0, winner: 1, moves: 6 }),\n];\n\nconst legalCounts = (heap: number): number[] => [1, 2, 3].filter((n) => n <= heap);\n\nexport const nim = defineEngine<NimState, NimCommand, NimView, NimEvent, NimConfig>({\n  rulesVersion: 1,\n  schemas: {\n    config: guardSchema(isNimConfig, 'Expected { heap }.'),\n    command: guardSchema(isNimCommand, 'Expected { type: \"take\", count }.'),\n    state: guardSchema(isNimState, 'Not a Nim state.'),\n    view: guardSchema(isNimState, 'Not a Nim view.'),\n    event: guardSchema(isNimEvent, 'Not a Nim event.'),\n  },\n  init: (config: NimConfig, seats, rng) =>\n    seats.length === 2\n      ? ok({ heap: config.heap, turn: rng.int(0, 2), winner: null, moves: 0 })\n      : err(gameError('Seats', 'Nim needs two players.')),\n  apply: (state: NimState, input) => {\n    if (state.winner !== null) return err(gameError('GameOver', 'The game is over.'));\n    switch (input.kind) {\n      case 'command': {\n        if (input.seat !== state.turn) return err(gameError('NotYourTurn', \"It's not your turn.\"));\n        const { count } = input.command;\n        if (!legalCounts(state.heap).includes(count))\n          return err(gameError('IllegalMove', 'Take one, two or three.', { count }));\n        const heap = state.heap - count;\n        const next: NimState = {\n          heap,\n          turn: 1 - state.turn,\n          winner: heap === 0 ? input.seat : null,\n          moves: state.moves + 1,\n        };\n        return ok({ state: next, beats: [{ event: { type: 'took', seat: input.seat, count } }] });\n      }\n      case 'resign': {\n        if (input.seat !== 0 && input.seat !== 1) return err(gameError('NoSuchSeat', 'There is no such seat.'));\n        return ok({\n          state: { ...state, winner: 1 - input.seat },\n          beats: [{ event: { type: 'resigned', seat: input.seat } }],\n        });\n      }\n      default:\n        return err(gameError('Unsupported', 'Nim has no clocks, seat changes or jobs.'));\n    }\n  },\n  pending: (state) => (state.winner === null ? [state.turn] : []),\n  viewFor: (state) => state,\n  eventFor: (event) => event,\n  outcome: (state) =>\n    state.winner === null\n      ? null\n      : {\n          result: 'won',\n          placements: [\n            { seat: state.winner, place: 1 },\n            { seat: 1 - state.winner, place: 2 },\n          ],\n          summary: `Seat ${state.winner + 1} wins.`,\n          stats: { moves: state.moves },\n        },\n  ai: {\n    levels: ['random', 'perfect'],\n    choose: (view, _seat, level, rng) => {\n      const counts = legalCounts(view.heap);\n      const perfect = view.heap % 4;\n      const count = level === 'perfect' && perfect > 0 ? perfect : (counts[rng.int(0, counts.length)] ?? 1);\n      return { type: 'take', count };\n    },\n  },\n});\n\n/** Conformance options for the Nim fixture. */\nexport const nimConformance: EngineConformanceOptions<NimState, NimCommand, NimConfig> = {\n  name: 'nim',\n  configs: [{ heap: 5 }, { heap: 21 }],\n  seatCounts: [2],\n  commands: () => [0, 1, 2, 3, 4].map((count) => ({ type: 'take', count })),\n  invariants: (s) =>\n    s.heap < 0 ? 'the heap is negative' : s.heap === 0 && s.winner === null ? 'an empty heap without a winner' : true,\n  saves: { version: NIM_SAVE_VERSION, migrations: nimMigrations, fixtures: nimSaveFixtures },\n};\n"],"mappings":"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"}

package/dist/fixtures/sealed-bids.d.ts

@@ -0,0 +1,46 @@
+import { type SeatId } from '@joystyk/contracts';
+import type { EngineConformanceOptions } from '../engine-conformance.js';
+export type SealedBidsState = {
+    readonly round: number;
+    readonly rounds: number;
+    /** This round's bids; null until the seat bids. Hidden from everyone else. */
+    readonly bids: readonly (number | null)[];
+    readonly scores: readonly number[];
+    /** Revealed bids of finished rounds. */
+    readonly history: readonly (readonly number[])[];
+    readonly resigned: SeatId | null;
+};
+export type SealedBidsCommand = {
+    readonly type: 'bid';
+    readonly amount: number;
+};
+export type SealedBidsEvent = {
+    readonly type: 'bid';
+    readonly seat: SeatId;
+    readonly amount: number | null;
+} | {
+    readonly type: 'revealed';
+    readonly bids: readonly number[];
+} | {
+    readonly type: 'resigned';
+    readonly seat: SeatId;
+};
+export type SealedBidsView = {
+    readonly round: number;
+    readonly rounds: number;
+    readonly myBid: number | null;
+    readonly submitted: readonly boolean[];
+    readonly scores: readonly number[];
+    readonly history: readonly (readonly number[])[];
+    readonly resigned: SeatId | null;
+};
+export type SealedBidsConfig = {
+    readonly rounds: number;
+};
+export declare const sealedBids: import("@joystyk/contracts").DiscreteEngine<SealedBidsState, SealedBidsCommand, SealedBidsView, SealedBidsEvent, SealedBidsConfig>;
+/** Re-draws every bid `viewer` can't see. */
+export declare const perturbSealedBids: (state: SealedBidsState, viewer: SeatId | null, rng: {
+    int(min: number, max: number): number;
+}) => SealedBidsState;
+/** Conformance options for the Sealed Bids fixture. */
+export declare const sealedBidsConformance: EngineConformanceOptions<SealedBidsState, SealedBidsCommand, SealedBidsConfig>;

package/dist/fixtures/sealed-bids.js

@@ -0,0 +1,141 @@
+import { guardSchema } from "../builders.js";
+import { isArrayOf, isInt, isRecord, isSeat, isSeatOrNull, rankPlaces } from "./guards.js";
+import { defineEngine, err, gameError, ok } from "@joystyk/contracts";
+//#region src/fixtures/sealed-bids.ts
+var isBid = (v) => isInt(v, 1, 3);
+var isScores = (v) => isArrayOf(v, (n) => isInt(n, 0));
+var isHistory = (v) => isArrayOf(v, (r) => isArrayOf(r, isBid));
+var isState = (v) => isRecord(v) && isInt(v["round"], 1) && isInt(v["rounds"], 1) && isArrayOf(v["bids"], (b) => b === null || isBid(b)) && isScores(v["scores"]) && isHistory(v["history"]) && isSeatOrNull(v["resigned"]);
+var isView = (v) => isRecord(v) && isInt(v["round"], 1) && isInt(v["rounds"], 1) && (v["myBid"] === null || isBid(v["myBid"])) && isArrayOf(v["submitted"], (b) => typeof b === "boolean") && isScores(v["scores"]) && isHistory(v["history"]) && isSeatOrNull(v["resigned"]);
+var isCommand = (v) => isRecord(v) && v["type"] === "bid" && isInt(v["amount"]);
+var isEvent = (v) => isRecord(v) && (v["type"] === "bid" && isSeat(v["seat"]) && (v["amount"] === null || isBid(v["amount"])) || v["type"] === "revealed" && isArrayOf(v["bids"], isBid) || v["type"] === "resigned" && isSeat(v["seat"]));
+var isConfig = (v) => isRecord(v) && isInt(v["rounds"], 1, 20);
+var over = (s) => s.resigned !== null || s.round > s.rounds;
+var sealedBids = defineEngine({
+	rulesVersion: 1,
+	schemas: {
+		config: guardSchema(isConfig, "Expected { rounds } from 1 to 20."),
+		command: guardSchema(isCommand, "Expected { type: \"bid\", amount }."),
+		state: guardSchema(isState, "Not a Sealed Bids state."),
+		view: guardSchema(isView, "Not a Sealed Bids view."),
+		event: guardSchema(isEvent, "Not a Sealed Bids event.")
+	},
+	init: (config, seats) => seats.length < 2 || seats.length > 4 ? err(gameError("Seats", "Sealed Bids needs two to four players.")) : ok({
+		round: 1,
+		rounds: config.rounds,
+		bids: seats.map(() => null),
+		scores: seats.map(() => 0),
+		history: [],
+		resigned: null
+	}),
+	apply: (state, input) => {
+		if (over(state)) return err(gameError("GameOver", "The game is over."));
+		if (input.kind === "resign") {
+			if (state.bids[input.seat] === void 0) return err(gameError("NoSuchSeat", "There is no such seat."));
+			return ok({
+				state: {
+					...state,
+					resigned: input.seat
+				},
+				beats: [{ event: {
+					type: "resigned",
+					seat: input.seat
+				} }]
+			});
+		}
+		if (input.kind !== "command") return err(gameError("Unsupported", "Sealed Bids has no clocks, seat changes or jobs."));
+		if (state.bids[input.seat] !== null) return err(gameError("NotYourTurn", "You have already bid this round."));
+		const { amount } = input.command;
+		if (!isBid(amount)) return err(gameError("IllegalBid", "Bid 1, 2 or 3."));
+		const bids = state.bids.map((b, s) => s === input.seat ? amount : b);
+		const placed = { event: {
+			type: "bid",
+			seat: input.seat,
+			amount
+		} };
+		if (bids.some((b) => b === null)) return ok({
+			state: {
+				...state,
+				bids
+			},
+			beats: [placed]
+		});
+		const revealed = bids;
+		const scores = state.scores.map((score, s) => {
+			const bid = revealed[s] ?? 0;
+			return revealed.filter((b) => b === bid).length === 1 ? score + bid : score;
+		});
+		const next = {
+			...state,
+			round: state.round + 1,
+			bids: bids.map(() => null),
+			scores,
+			history: [...state.history, revealed]
+		};
+		return ok({
+			state: next,
+			beats: [placed, { event: {
+				type: "revealed",
+				bids: revealed
+			} }]
+		});
+	},
+	pending: (state) => over(state) ? [] : state.bids.flatMap((b, s) => b === null ? [s] : []),
+	viewFor: (state, viewer) => ({
+		round: state.round,
+		rounds: state.rounds,
+		myBid: viewer === null ? null : state.bids[viewer] ?? null,
+		submitted: state.bids.map((b) => b !== null),
+		scores: state.scores,
+		history: state.history,
+		resigned: state.resigned
+	}),
+	eventFor: (event, viewer) => event.type === "bid" && event.seat !== viewer ? {
+		...event,
+		amount: null
+	} : event,
+	outcome: (state) => over(state) ? {
+		result: "won",
+		placements: rankPlaces(state.scores, state.resigned),
+		summary: state.resigned === null ? `After ${state.rounds} rounds.` : `Seat ${state.resigned + 1} resigned.`
+	} : null,
+	decisionKey: (state, seat) => ({
+		round: state.round,
+		myBid: state.bids[seat] ?? null,
+		scores: state.scores,
+		history: state.history,
+		resigned: state.resigned
+	})
+});
+/** Re-draws every bid `viewer` can't see. */
+var perturbSealedBids = (state, viewer, rng) => ({
+	...state,
+	bids: state.bids.map((b, s) => b === null || s === viewer ? b : rng.int(1, 4))
+});
+/** Conformance options for the Sealed Bids fixture. */
+var sealedBidsConformance = {
+	name: "sealed-bids",
+	configs: [{ rounds: 4 }],
+	seatCounts: [
+		2,
+		3,
+		4
+	],
+	games: 8,
+	commands: () => [
+		0,
+		1,
+		2,
+		3,
+		4
+	].map((amount) => ({
+		type: "bid",
+		amount
+	})),
+	perturbHidden: perturbSealedBids,
+	invariants: (s) => s.history.length === s.round - 1 ? true : "history and round disagree"
+};
+//#endregion
+export { perturbSealedBids, sealedBids, sealedBidsConformance };
+
+//# sourceMappingURL=sealed-bids.js.map

package/dist/fixtures/sealed-bids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sealed-bids.js","names":[],"sources":["../../src/fixtures/sealed-bids.ts"],"sourcesContent":["// Sealed Bids: a simultaneous-move game for two to four players. Every round, all players\n// secretly bid 1, 2 or 3 at the same time. When the last bid arrives, the bids are revealed\n// and each unique bid scores its value. After the configured rounds the highest score wins.\n// It exercises several pending seats at once, hidden choices, redacted events and a\n// decisionKey that ignores who has already bid, so simultaneous bids are never stale.\n\nimport { defineEngine, err, gameError, ok, type SeatId } from '@joystyk/contracts';\nimport { guardSchema } from '../builders.ts';\nimport type { EngineConformanceOptions } from '../engine-conformance.ts';\nimport { isArrayOf, isInt, isRecord, isSeat, isSeatOrNull, rankPlaces } from './guards.ts';\n\nexport type SealedBidsState = {\n  readonly round: number;\n  readonly rounds: number;\n  /** This round's bids; null until the seat bids. Hidden from everyone else. */\n  readonly bids: readonly (number | null)[];\n  readonly scores: readonly number[];\n  /** Revealed bids of finished rounds. */\n  readonly history: readonly (readonly number[])[];\n  readonly resigned: SeatId | null;\n};\nexport type SealedBidsCommand = { readonly type: 'bid'; readonly amount: number };\nexport type SealedBidsEvent =\n  | { readonly type: 'bid'; readonly seat: SeatId; readonly amount: number | null }\n  | { readonly type: 'revealed'; readonly bids: readonly number[] }\n  | { readonly type: 'resigned'; readonly seat: SeatId };\nexport type SealedBidsView = {\n  readonly round: number;\n  readonly rounds: number;\n  readonly myBid: number | null;\n  readonly submitted: readonly boolean[];\n  readonly scores: readonly number[];\n  readonly history: readonly (readonly number[])[];\n  readonly resigned: SeatId | null;\n};\nexport type SealedBidsConfig = { readonly rounds: number };\n\nconst isBid = (v: unknown): v is number => isInt(v, 1, 3);\nconst isScores = (v: unknown): v is number[] => isArrayOf(v, (n): n is number => isInt(n, 0));\nconst isHistory = (v: unknown): v is number[][] => isArrayOf(v, (r): r is number[] => isArrayOf(r, isBid));\nconst isState = (v: unknown): v is SealedBidsState =>\n  isRecord(v) &&\n  isInt(v['round'], 1) &&\n  isInt(v['rounds'], 1) &&\n  isArrayOf(v['bids'], (b): b is number | null => b === null || isBid(b)) &&\n  isScores(v['scores']) &&\n  isHistory(v['history']) &&\n  isSeatOrNull(v['resigned']);\nconst isView = (v: unknown): v is SealedBidsView =>\n  isRecord(v) &&\n  isInt(v['round'], 1) &&\n  isInt(v['rounds'], 1) &&\n  (v['myBid'] === null || isBid(v['myBid'])) &&\n  isArrayOf(v['submitted'], (b): b is boolean => typeof b === 'boolean') &&\n  isScores(v['scores']) &&\n  isHistory(v['history']) &&\n  isSeatOrNull(v['resigned']);\nconst isCommand = (v: unknown): v is SealedBidsCommand => isRecord(v) && v['type'] === 'bid' && isInt(v['amount']);\nconst isEvent = (v: unknown): v is SealedBidsEvent =>\n  isRecord(v) &&\n  ((v['type'] === 'bid' && isSeat(v['seat']) && (v['amount'] === null || isBid(v['amount']))) ||\n    (v['type'] === 'revealed' && isArrayOf(v['bids'], isBid)) ||\n    (v['type'] === 'resigned' && isSeat(v['seat'])));\nconst isConfig = (v: unknown): v is SealedBidsConfig => isRecord(v) && isInt(v['rounds'], 1, 20);\n\nconst over = (s: SealedBidsState): boolean => s.resigned !== null || s.round > s.rounds;\n\nexport const sealedBids = defineEngine<\n  SealedBidsState,\n  SealedBidsCommand,\n  SealedBidsView,\n  SealedBidsEvent,\n  SealedBidsConfig\n>({\n  rulesVersion: 1,\n  schemas: {\n    config: guardSchema(isConfig, 'Expected { rounds } from 1 to 20.'),\n    command: guardSchema(isCommand, 'Expected { type: \"bid\", amount }.'),\n    state: guardSchema(isState, 'Not a Sealed Bids state.'),\n    view: guardSchema(isView, 'Not a Sealed Bids view.'),\n    event: guardSchema(isEvent, 'Not a Sealed Bids event.'),\n  },\n  init: (config: SealedBidsConfig, seats) =>\n    seats.length < 2 || seats.length > 4\n      ? err(gameError('Seats', 'Sealed Bids needs two to four players.'))\n      : ok({\n          round: 1,\n          rounds: config.rounds,\n          bids: seats.map(() => null),\n          scores: seats.map(() => 0),\n          history: [],\n          resigned: null,\n        }),\n  apply: (state: SealedBidsState, input) => {\n    if (over(state)) return err(gameError('GameOver', 'The game is over.'));\n    if (input.kind === 'resign') {\n      if (state.bids[input.seat] === undefined) return err(gameError('NoSuchSeat', 'There is no such seat.'));\n      return ok({\n        state: { ...state, resigned: input.seat },\n        beats: [{ event: { type: 'resigned', seat: input.seat } }],\n      });\n    }\n    if (input.kind !== 'command')\n      return err(gameError('Unsupported', 'Sealed Bids has no clocks, seat changes or jobs.'));\n    if (state.bids[input.seat] !== null) return err(gameError('NotYourTurn', 'You have already bid this round.'));\n    const { amount } = input.command;\n    if (!isBid(amount)) return err(gameError('IllegalBid', 'Bid 1, 2 or 3.'));\n    const bids = state.bids.map((b, s) => (s === input.seat ? amount : b));\n    const placed = { event: { type: 'bid', seat: input.seat, amount } } as const;\n    if (bids.some((b) => b === null)) return ok({ state: { ...state, bids }, beats: [placed] });\n    const revealed = bids as number[];\n    const scores = state.scores.map((score, s) => {\n      const bid = revealed[s] ?? 0;\n      return revealed.filter((b) => b === bid).length === 1 ? score + bid : score;\n    });\n    const next: SealedBidsState = {\n      ...state,\n      round: state.round + 1,\n      bids: bids.map(() => null),\n      scores,\n      history: [...state.history, revealed],\n    };\n    return ok({ state: next, beats: [placed, { event: { type: 'revealed', bids: revealed } }] });\n  },\n  pending: (state) => (over(state) ? [] : state.bids.flatMap((b, s) => (b === null ? [s] : []))),\n  viewFor: (state, viewer): SealedBidsView => ({\n    round: state.round,\n    rounds: state.rounds,\n    myBid: viewer === null ? null : (state.bids[viewer] ?? null),\n    submitted: state.bids.map((b) => b !== null),\n    scores: state.scores,\n    history: state.history,\n    resigned: state.resigned,\n  }),\n  eventFor: (event, viewer) => (event.type === 'bid' && event.seat !== viewer ? { ...event, amount: null } : event),\n  outcome: (state) =>\n    over(state)\n      ? {\n          result: 'won',\n          placements: rankPlaces(state.scores, state.resigned),\n          summary: state.resigned === null ? `After ${state.rounds} rounds.` : `Seat ${state.resigned + 1} resigned.`,\n        }\n      : null,\n  // Who has already bid doesn't change anyone else's decision.\n  decisionKey: (state, seat) => ({\n    round: state.round,\n    myBid: state.bids[seat] ?? null,\n    scores: state.scores,\n    history: state.history,\n    resigned: state.resigned,\n  }),\n});\n\n/** Re-draws every bid `viewer` can't see. */\nexport const perturbSealedBids = (\n  state: SealedBidsState,\n  viewer: SeatId | null,\n  rng: { int(min: number, max: number): number },\n): SealedBidsState => ({\n  ...state,\n  bids: state.bids.map((b, s) => (b === null || s === viewer ? b : rng.int(1, 4))),\n});\n\n/** Conformance options for the Sealed Bids fixture. */\nexport const sealedBidsConformance: EngineConformanceOptions<SealedBidsState, SealedBidsCommand, SealedBidsConfig> = {\n  name: 'sealed-bids',\n  configs: [{ rounds: 4 }],\n  seatCounts: [2, 3, 4],\n  games: 8,\n  commands: () => [0, 1, 2, 3, 4].map((amount) => ({ type: 'bid', amount })),\n  perturbHidden: perturbSealedBids,\n  invariants: (s) => (s.history.length === s.round - 1 ? true : 'history and round disagree'),\n};\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { checkEngine, ENGINE_CHECKS, type EngineCheckId, type EngineConformanceOptions, type EngineSetup, type HiddenTransition, type InvariantResult, type SaveOptions, } from './engine-conformance.js';
+export { checkSimulation, SIMULATION_CHECKS, type SimulationCheckId, type SimulationConformanceOptions, } from './simulation-conformance.js';
+export { ConformanceError, expectConformance, runEngineConformance, runSimulationConformance, type VitestOptions, } from './vitest.js';
+export { checkById, failedChecks, formatCheck, formatFailure, formatReport, type CheckResult, type CheckStatus, type ConformanceReport, type Failure, } from './report.js';
+export { replayEngine, replaySimulation, undoByReplay, type EngineReplayResult, type ReplayedInput, type SimulationReplayResult, type UndoResult, } from './replay.js';
+export { cloneRng, testRng, testSeed, testSeeds } from './rng.js';
+export { createFakeClock, type FakeClock, type TimerHandle } from './clock.js';
+export { manualFrames, nextTask, pause, WAIT_BUDGET_MS, waitUntil, type FrameWaitOptions, type ManualFrames, type WaitOptions, } from './waiting.js';
+export { createFakeStorage, type FakeStorage, type StorageCall, type StorageOperation } from './storage.js';
+export { createMemorySaveStore, runnerClock, type MemorySaveStore } from './session-ports.js';
+export { anySchema, commandInput, engineReplay, guardSchema, isEngineReplay, jobFailure, jobResult, resignInput, saveEnvelope, saveFixture, seatInput, seats, simulationReplay, timeoutInput, type SaveFixture, } from './builders.js';
+export { formatIssues, validate, type Validation } from './schema.js';
+export { deepEqual, deepFreeze, firstDifference, jsonRoundTrip } from './deep.js';

package/dist/index.js

@@ -0,0 +1,14 @@
+import { anySchema, commandInput, engineReplay, guardSchema, isEngineReplay, jobFailure, jobResult, resignInput, saveEnvelope, saveFixture, seatInput, seats, simulationReplay, timeoutInput } from "./builders.js";
+import { createFakeClock } from "./clock.js";
+import { deepEqual, deepFreeze, firstDifference, jsonRoundTrip } from "./deep.js";
+import { replayEngine, replaySimulation, undoByReplay } from "./replay.js";
+import { checkById, failedChecks, formatCheck, formatFailure, formatReport } from "./report.js";
+import { cloneRng, testRng, testSeed, testSeeds } from "./rng.js";
+import { formatIssues, validate } from "./schema.js";
+import { ENGINE_CHECKS, checkEngine } from "./engine-conformance.js";
+import { SIMULATION_CHECKS, checkSimulation } from "./simulation-conformance.js";
+import { ConformanceError, expectConformance, runEngineConformance, runSimulationConformance } from "./vitest.js";
+import { WAIT_BUDGET_MS, manualFrames, nextTask, pause, waitUntil } from "./waiting.js";
+import { createFakeStorage } from "./storage.js";
+import { createMemorySaveStore, runnerClock } from "./session-ports.js";
+export { ConformanceError, ENGINE_CHECKS, SIMULATION_CHECKS, WAIT_BUDGET_MS, anySchema, checkById, checkEngine, checkSimulation, cloneRng, commandInput, createFakeClock, createFakeStorage, createMemorySaveStore, deepEqual, deepFreeze, engineReplay, expectConformance, failedChecks, firstDifference, formatCheck, formatFailure, formatIssues, formatReport, guardSchema, isEngineReplay, jobFailure, jobResult, jsonRoundTrip, manualFrames, nextTask, pause, replayEngine, replaySimulation, resignInput, runEngineConformance, runSimulationConformance, runnerClock, saveEnvelope, saveFixture, seatInput, seats, simulationReplay, testRng, testSeed, testSeeds, timeoutInput, undoByReplay, validate, waitUntil };

package/dist/replay.d.ts

@@ -0,0 +1,58 @@
+import { type AssistKind, type DiscreteEngine, type EngineAssist, type EngineReplay, type FixedStepSimulation, type Json, type Outcome, type Result, type SimulationReplay } from '@joystyk/contracts';
+/** What one replayed input's transition flagged. */
+export type ReplayedInput = {
+    readonly barrier: boolean;
+    readonly assist: EngineAssist | null;
+    /** Whether the input was a command from a seat a human controlled at the time. */
+    readonly humanCommand: boolean;
+};
+/** The end of a Layer 2 replay. */
+export type EngineReplayResult<State> = {
+    readonly state: State;
+    readonly outcome: Outcome | null;
+    /** One entry per input, in order. */
+    readonly inputs: readonly ReplayedInput[];
+    /** One flag per input: whether its transition set `undoBarrier`. */
+    readonly barriers: readonly boolean[];
+};
+/**
+ * Replays a Layer 2 log: `init` with the seed, then every input in order with the same
+ * generator. Fails with `ReplayInitFailed` or `ReplayInputRejected` (detail: the input's
+ * index and the engine's error) when the log no longer applies, as it won't after a rules
+ * change. An engine that throws is a bug, so the exception propagates.
+ */
+export declare const replayEngine: <State extends Json, Command extends Json, View extends Json, Event extends Json, Config extends Json>(engine: DiscreteEngine<State, Command, View, Event, Config>, replay: EngineReplay<Command, Config>) => Result<EngineReplayResult<State>>;
+/** The result of one undo by replay. */
+export type UndoResult<State, Command extends Json, Config extends Json> = {
+    /** The replay without the undone inputs. */
+    readonly replay: EngineReplay<Command, Config>;
+    readonly state: State;
+    /** How many inputs were dropped: the human's command and everything after it. */
+    readonly dropped: number;
+    /**
+     * Every assistance kind used in the game before the undo, in `ASSIST_KINDS` order, `'undo'`
+     * included. The record only grows: undoing a hint doesn't remove `'hint'`.
+     */
+    readonly assists: readonly AssistKind[];
+};
+/**
+ * Undo by replay, as the local runner performs it (D-32): it returns to the start of the
+ * human seat's previous decision, dropping the latest command from a human-controlled seat
+ * and everything after it (the AI's replies, job outcomes), then replays the rest from the
+ * seed. It refuses with `NothingToUndo` when no human command is left and with
+ * `UndoBarrier` when any dropped input's transition set `undoBarrier`, so undo never steps
+ * back past a barrier nor past anything before it. Barrier and assistance flags come from
+ * replaying the log, never from a separate record. Undo policies and limits are the
+ * runner's business, not this helper's.
+ */
+export declare const undoByReplay: <State extends Json, Command extends Json, View extends Json, Event extends Json, Config extends Json>(engine: DiscreteEngine<State, Command, View, Event, Config>, replay: EngineReplay<Command, Config>) => Result<UndoResult<State, Command, Config>>;
+/** The end of a Layer 3 replay. */
+export type SimulationReplayResult<State> = {
+    readonly state: State;
+    readonly outcome: Outcome | null;
+};
+/**
+ * Replays a Layer 3 log: `init` with the seed, then `step` from tick 0 up to `endTick`
+ * (exclusive), giving each tick the inputs assigned to it in array order.
+ */
+export declare const replaySimulation: <State extends Json, Input extends Json, View, Event extends Json, Config extends Json>(simulation: FixedStepSimulation<State, Input, View, Event, Config>, replay: SimulationReplay<Input, Config>) => Result<SimulationReplayResult<State>>;

package/dist/replay.js

@@ -0,0 +1,110 @@
+import { ASSIST_KINDS, err, gameError, ok } from "@joystyk/contracts";
+import { restoreRng } from "@joystyk/kit";
+//#region src/replay.ts
+var ENGINE_ASSISTS = [
+	"hint",
+	"check",
+	"reveal",
+	"shuffle"
+];
+var seatsAfter = (seats, input) => {
+	if (input.kind !== "seat" || input.change.type !== "controller") return seats;
+	const { change } = input;
+	return seats.map((seat) => seat.id !== input.seat ? seat : change.aiLevel === void 0 ? {
+		id: seat.id,
+		name: change.name,
+		controller: change.controller
+	} : {
+		id: seat.id,
+		name: change.name,
+		controller: change.controller,
+		aiLevel: change.aiLevel
+	});
+};
+/**
+* Replays a Layer 2 log: `init` with the seed, then every input in order with the same
+* generator. Fails with `ReplayInitFailed` or `ReplayInputRejected` (detail: the input's
+* index and the engine's error) when the log no longer applies, as it won't after a rules
+* change. An engine that throws is a bug, so the exception propagates.
+*/
+var replayEngine = (engine, replay) => {
+	const rng = restoreRng(replay.seed);
+	const started = engine.init(replay.config, replay.seats, rng);
+	if (!started.ok) return err(gameError("ReplayInitFailed", "The replay could not start.", { error: started.error }));
+	let state = started.value;
+	let seats = replay.seats;
+	const inputs = [];
+	for (const [index, input] of replay.inputs.entries()) {
+		const applied = engine.apply(state, input, rng);
+		if (!applied.ok) return err(gameError("ReplayInputRejected", "The replay no longer applies.", {
+			index,
+			error: applied.error
+		}));
+		const { assist } = applied.value;
+		inputs.push({
+			barrier: applied.value.undoBarrier === true,
+			assist: ENGINE_ASSISTS.includes(assist) ? assist : null,
+			humanCommand: input.kind === "command" && seats.find((s) => s.id === input.seat)?.controller === "human"
+		});
+		seats = seatsAfter(seats, input);
+		state = applied.value.state;
+	}
+	return ok({
+		state,
+		outcome: engine.outcome(state),
+		inputs,
+		barriers: inputs.map((i) => i.barrier)
+	});
+};
+/**
+* Undo by replay, as the local runner performs it (D-32): it returns to the start of the
+* human seat's previous decision, dropping the latest command from a human-controlled seat
+* and everything after it (the AI's replies, job outcomes), then replays the rest from the
+* seed. It refuses with `NothingToUndo` when no human command is left and with
+* `UndoBarrier` when any dropped input's transition set `undoBarrier`, so undo never steps
+* back past a barrier nor past anything before it. Barrier and assistance flags come from
+* replaying the log, never from a separate record. Undo policies and limits are the
+* runner's business, not this helper's.
+*/
+var undoByReplay = (engine, replay) => {
+	const full = replayEngine(engine, replay);
+	if (!full.ok) return full;
+	const cut = full.value.inputs.findLastIndex((input) => input.humanCommand);
+	if (cut < 0) return err(gameError("NothingToUndo", "There is nothing to undo."));
+	const barrier = full.value.inputs.findIndex((input, index) => index >= cut && input.barrier);
+	if (barrier >= 0) return err(gameError("UndoBarrier", "That move can't be undone.", { index: barrier }));
+	const shorter = {
+		...replay,
+		inputs: replay.inputs.slice(0, cut)
+	};
+	const previous = replayEngine(engine, shorter);
+	if (!previous.ok) return previous;
+	const used = /* @__PURE__ */ new Set(["undo", ...full.value.inputs.flatMap((input) => input.assist === null ? [] : [input.assist])]);
+	return ok({
+		replay: shorter,
+		state: previous.value.state,
+		dropped: replay.inputs.length - cut,
+		assists: ASSIST_KINDS.filter((kind) => used.has(kind))
+	});
+};
+/**
+* Replays a Layer 3 log: `init` with the seed, then `step` from tick 0 up to `endTick`
+* (exclusive), giving each tick the inputs assigned to it in array order.
+*/
+var replaySimulation = (simulation, replay) => {
+	const rng = restoreRng(replay.seed);
+	const started = simulation.init(replay.config, rng);
+	if (!started.ok) return err(gameError("ReplayInitFailed", "The replay could not start.", { error: started.error }));
+	const byTick = /* @__PURE__ */ new Map();
+	for (const { tick, input } of replay.inputs) byTick.set(tick, [...byTick.get(tick) ?? [], input]);
+	let state = started.value;
+	for (let tick = 0; tick < replay.endTick; tick += 1) state = simulation.step(state, byTick.get(tick) ?? [], rng).state;
+	return ok({
+		state,
+		outcome: simulation.outcome(state)
+	});
+};
+//#endregion
+export { replayEngine, replaySimulation, undoByReplay };
+
+//# sourceMappingURL=replay.js.map

package/dist/replay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.js","names":[],"sources":["../src/replay.ts"],"sourcesContent":["// Replay and undo by replay, as the platform performs them (game-contract.md, \"Replays\" and\n// \"Undo, barriers and assistance\"). The session package's runners do the same in production;\n// these versions also report what each input's transition flagged, which tests need.\n\nimport {\n  ASSIST_KINDS,\n  err,\n  gameError,\n  ok,\n  type AssistKind,\n  type DiscreteEngine,\n  type EngineAssist,\n  type EngineInput,\n  type EngineReplay,\n  type FixedStepSimulation,\n  type Json,\n  type Outcome,\n  type Result,\n  type SeatInfo,\n  type SimulationReplay,\n} from '@joystyk/contracts';\nimport { restoreRng } from '@joystyk/kit';\n\n/** What one replayed input's transition flagged. */\nexport type ReplayedInput = {\n  readonly barrier: boolean;\n  readonly assist: EngineAssist | null;\n  /** Whether the input was a command from a seat a human controlled at the time. */\n  readonly humanCommand: boolean;\n};\n\n/** The end of a Layer 2 replay. */\nexport type EngineReplayResult<State> = {\n  readonly state: State;\n  readonly outcome: Outcome | null;\n  /** One entry per input, in order. */\n  readonly inputs: readonly ReplayedInput[];\n  /** One flag per input: whether its transition set `undoBarrier`. */\n  readonly barriers: readonly boolean[];\n};\n\nconst ENGINE_ASSISTS: readonly unknown[] = ['hint', 'check', 'reveal', 'shuffle'];\n\nconst seatsAfter = (seats: readonly SeatInfo[], input: EngineInput<unknown>): readonly SeatInfo[] => {\n  if (input.kind !== 'seat' || input.change.type !== 'controller') return seats;\n  const { change } = input;\n  return seats.map((seat) =>\n    seat.id !== input.seat\n      ? seat\n      : change.aiLevel === undefined\n        ? { id: seat.id, name: change.name, controller: change.controller }\n        : { id: seat.id, name: change.name, controller: change.controller, aiLevel: change.aiLevel },\n  );\n};\n\n/**\n * Replays a Layer 2 log: `init` with the seed, then every input in order with the same\n * generator. Fails with `ReplayInitFailed` or `ReplayInputRejected` (detail: the input's\n * index and the engine's error) when the log no longer applies, as it won't after a rules\n * change. An engine that throws is a bug, so the exception propagates.\n */\nexport const replayEngine = <\n  State extends Json,\n  Command extends Json,\n  View extends Json,\n  Event extends Json,\n  Config extends Json,\n>(\n  engine: DiscreteEngine<State, Command, View, Event, Config>,\n  replay: EngineReplay<Command, Config>,\n): Result<EngineReplayResult<State>> => {\n  const rng = restoreRng(replay.seed);\n  const started = engine.init(replay.config, replay.seats, rng);\n  if (!started.ok) return err(gameError('ReplayInitFailed', 'The replay could not start.', { error: started.error }));\n  let state = started.value;\n  let seats = replay.seats;\n  const inputs: ReplayedInput[] = [];\n  for (const [index, input] of replay.inputs.entries()) {\n    const applied = engine.apply(state, input, rng);\n    if (!applied.ok) {\n      return err(gameError('ReplayInputRejected', 'The replay no longer applies.', { index, error: applied.error }));\n    }\n    const { assist } = applied.value;\n    inputs.push({\n      barrier: applied.value.undoBarrier === true,\n      assist: ENGINE_ASSISTS.includes(assist) ? (assist as EngineAssist) : null,\n      humanCommand: input.kind === 'command' && seats.find((s) => s.id === input.seat)?.controller === 'human',\n    });\n    seats = seatsAfter(seats, input);\n    state = applied.value.state;\n  }\n  return ok({ state, outcome: engine.outcome(state), inputs, barriers: inputs.map((i) => i.barrier) });\n};\n\n/** The result of one undo by replay. */\nexport type UndoResult<State, Command extends Json, Config extends Json> = {\n  /** The replay without the undone inputs. */\n  readonly replay: EngineReplay<Command, Config>;\n  readonly state: State;\n  /** How many inputs were dropped: the human's command and everything after it. */\n  readonly dropped: number;\n  /**\n   * Every assistance kind used in the game before the undo, in `ASSIST_KINDS` order, `'undo'`\n   * included. The record only grows: undoing a hint doesn't remove `'hint'`.\n   */\n  readonly assists: readonly AssistKind[];\n};\n\n/**\n * Undo by replay, as the local runner performs it (D-32): it returns to the start of the\n * human seat's previous decision, dropping the latest command from a human-controlled seat\n * and everything after it (the AI's replies, job outcomes), then replays the rest from the\n * seed. It refuses with `NothingToUndo` when no human command is left and with\n * `UndoBarrier` when any dropped input's transition set `undoBarrier`, so undo never steps\n * back past a barrier nor past anything before it. Barrier and assistance flags come from\n * replaying the log, never from a separate record. Undo policies and limits are the\n * runner's business, not this helper's.\n */\nexport const undoByReplay = <\n  State extends Json,\n  Command extends Json,\n  View extends Json,\n  Event extends Json,\n  Config extends Json,\n>(\n  engine: DiscreteEngine<State, Command, View, Event, Config>,\n  replay: EngineReplay<Command, Config>,\n): Result<UndoResult<State, Command, Config>> => {\n  const full = replayEngine(engine, replay);\n  if (!full.ok) return full;\n  const cut = full.value.inputs.findLastIndex((input) => input.humanCommand);\n  if (cut < 0) return err(gameError('NothingToUndo', 'There is nothing to undo.'));\n  const barrier = full.value.inputs.findIndex((input, index) => index >= cut && input.barrier);\n  if (barrier >= 0) return err(gameError('UndoBarrier', \"That move can't be undone.\", { index: barrier }));\n  const shorter: EngineReplay<Command, Config> = { ...replay, inputs: replay.inputs.slice(0, cut) };\n  const previous = replayEngine(engine, shorter);\n  if (!previous.ok) return previous;\n  const used = new Set<AssistKind>([\n    'undo',\n    ...full.value.inputs.flatMap((input) => (input.assist === null ? [] : [input.assist])),\n  ]);\n  return ok({\n    replay: shorter,\n    state: previous.value.state,\n    dropped: replay.inputs.length - cut,\n    assists: ASSIST_KINDS.filter((kind) => used.has(kind)),\n  });\n};\n\n/** The end of a Layer 3 replay. */\nexport type SimulationReplayResult<State> = {\n  readonly state: State;\n  readonly outcome: Outcome | null;\n};\n\n/**\n * Replays a Layer 3 log: `init` with the seed, then `step` from tick 0 up to `endTick`\n * (exclusive), giving each tick the inputs assigned to it in array order.\n */\nexport const replaySimulation = <State extends Json, Input extends Json, View, Event extends Json, Config extends Json>(\n  simulation: FixedStepSimulation<State, Input, View, Event, Config>,\n  replay: SimulationReplay<Input, Config>,\n): Result<SimulationReplayResult<State>> => {\n  const rng = restoreRng(replay.seed);\n  const started = simulation.init(replay.config, rng);\n  if (!started.ok) return err(gameError('ReplayInitFailed', 'The replay could not start.', { error: started.error }));\n  const byTick = new Map<number, Input[]>();\n  for (const { tick, input } of replay.inputs) byTick.set(tick, [...(byTick.get(tick) ?? []), input]);\n  let state = started.value;\n  for (let tick = 0; tick < replay.endTick; tick += 1) {\n    state = simulation.step(state, byTick.get(tick) ?? [], rng).state;\n  }\n  return ok({ state, outcome: simulation.outcome(state) });\n};\n"],"mappings":"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"}