@joystyk/testing 0.0.0-stage → 0.2.0

package/dist/simulation-conformance.js

@@ -0,0 +1,312 @@
+import { simulationReplay } from "./builders.js";
+import { deepEqual, deepFreeze, errorMessage, firstDifference, jsonProblem, jsonRoundTrip, show } from "./deep.js";
+import { replaySimulation as replaySimulation$1 } from "./replay.js";
+import { Recorder } from "./report.js";
+import { cloneRng, testRng, testSeed } from "./rng.js";
+import { formatIssues, validate } from "./schema.js";
+import { isJson } from "@joystyk/contracts";
+import { restoreRng } from "@joystyk/kit";
+import { replaySimulation } from "@joystyk/session";
+//#region src/simulation-conformance.ts
+/** The checks this suite runs, in report order. */
+var SIMULATION_CHECKS = [
+	{
+		id: "determinism",
+		title: "Determinism: the same seed and tick inputs give the same states and events"
+	},
+	{
+		id: "replay",
+		title: "Replay: the recorded tick log reproduces the final state"
+	},
+	{
+		id: "checkpoint",
+		title: "Checkpoints: saving, restoring and continuing equals running straight through"
+	},
+	{
+		id: "json",
+		title: "JSON safety of configs, states, inputs, events and outcomes"
+	},
+	{
+		id: "schemas",
+		title: "Schema agreement: every value passes the simulation's own schemas"
+	},
+	{
+		id: "purity",
+		title: "Step purity: the same state, inputs and generator give the same next state, without mutation"
+	},
+	{
+		id: "invariants",
+		title: "Invariants hold on every state the simulation reaches"
+	},
+	{
+		id: "outcome",
+		title: "Outcomes are valid and detected in time"
+	},
+	{
+		id: "budget",
+		title: "Step-time budget"
+	}
+];
+var now = () => globalThis.performance?.now() ?? 0;
+var outcomeProblem = (outcome) => {
+	if (![
+		"won",
+		"lost",
+		"draw",
+		"completed",
+		"abandoned"
+	].includes(outcome.result)) return `unknown result ${show(outcome.result)}`;
+	if (typeof outcome.summary !== "string") return "summary must be a string";
+	if (outcome.elapsedMs !== void 0 || outcome.undosUsed !== void 0 || outcome.assists !== void 0) return "simulations never set elapsedMs, undosUsed or assists; the scheduler adds them";
+	if (outcome.placements.length === 0) return "placements is empty; a solo game has one entry";
+	for (const p of outcome.placements) if (!Number.isInteger(p.place) || p.place < 1) return `seat ${p.seat} has place ${show(p.place)}; places start at 1`;
+	if (new Set(outcome.placements.map((p) => p.seat)).size !== outcome.placements.length) return "a seat is placed twice";
+	return null;
+};
+/**
+* Runs the Layer 3 conformance suite against `simulation` and returns a report. It never
+* throws for a failing check. Use `runSimulationConformance` to get one vitest case per check.
+*/
+var checkSimulation = async (simulation, options) => {
+	if (options.configs.length === 0) throw new TypeError("Simulation conformance needs at least one config.");
+	const rec = new Recorder(SIMULATION_CHECKS, options.maxFailuresPerCheck ?? 3);
+	const runs = options.runs ?? 4;
+	const ticks = options.ticks ?? 1e3;
+	const baseSeed = options.seed ?? "conformance";
+	const gameId = options.gameId ?? "test-game";
+	if (options.invariants === void 0) rec.skip("invariants", "no invariants hook given");
+	if (options.stepBudgetMs === void 0) rec.skip("budget", "no stepBudgetMs given");
+	const validations = [];
+	const checkSchema = (schema, value, what, fail) => {
+		rec.ran("schemas");
+		validations.push(validate(schema, value).then((result) => {
+			if (!result.ok) fail(`${what} fails its schema: ${formatIssues(result.issues)}; value ${show(value)}`);
+		}, (error) => fail(`${what}: the schema threw ${errorMessage(error)}`)));
+	};
+	let totalRuns = 0;
+	let totalTicks = 0;
+	let stepTime = 0;
+	let stepCount = 0;
+	for (const [configIndex, config] of options.configs.entries()) {
+		rec.ran("json");
+		if (!isJson(config)) rec.fail("json", {
+			message: `config ${configIndex} isn't JSON: ${jsonProblem(config)}`,
+			setup: configIndex
+		});
+		checkSchema(simulation.schemas.config, config, `config ${configIndex}`, (message) => rec.fail("schemas", {
+			message,
+			setup: configIndex
+		}));
+		for (let runIndex = 0; runIndex < runs; runIndex += 1) {
+			if (options.only !== void 0 && (options.only.setup !== configIndex || options.only.game !== runIndex)) continue;
+			totalRuns += 1;
+			const seed = `${baseSeed}/${configIndex}/${runIndex}`;
+			const seedState = testSeed(seed, "engine");
+			const driver = testRng(seed, "driver");
+			const log = [];
+			const states = [];
+			const rngs = [];
+			const results = [];
+			const replayUpTo = (endTick) => simulationReplay({
+				gameId,
+				rulesVersion: simulation.rulesVersion,
+				config,
+				seed: seedState,
+				inputs: log.filter((entry) => entry.tick < endTick),
+				endTick
+			});
+			const fail = (id, message, tick, input) => {
+				const failure = {
+					message,
+					setup: configIndex,
+					game: runIndex,
+					seed,
+					step: tick,
+					replay: replayUpTo(tick),
+					...input === void 0 ? {} : { input }
+				};
+				rec.fail(id, failure);
+			};
+			const rng = restoreRng(seedState);
+			let started;
+			try {
+				started = simulation.init(config, rng);
+			} catch (error) {
+				fail("purity", `init threw: ${errorMessage(error)}`, 0);
+				continue;
+			}
+			if (!started.ok) {
+				fail("outcome", `init rejected config ${configIndex}: ${show(started.error)}`, 0);
+				continue;
+			}
+			let state = deepFreeze(started.value);
+			let outcome = null;
+			let tick = 0;
+			const checkState = (value, at) => {
+				rec.ran("json");
+				if (!isJson(value)) fail("json", `the state isn't JSON: ${jsonProblem(value)}`, at);
+				checkSchema(simulation.schemas.state, value, "the state", (m) => fail("schemas", m, at));
+				if (options.invariants !== void 0) {
+					rec.ran("invariants");
+					try {
+						const result = options.invariants(value);
+						if (result === false || typeof result === "string") fail("invariants", `invariant violated: ${result === false ? "the invariant hook returned false" : result}`, at);
+					} catch (error) {
+						fail("invariants", `invariant violated: ${errorMessage(error)}`, at);
+					}
+				}
+			};
+			const findOutcome = (value, at) => {
+				const found = simulation.outcome(value);
+				if (found !== null) {
+					rec.ran("outcome");
+					if (!isJson(found)) fail("json", `the outcome isn't JSON: ${jsonProblem(found)}`, at);
+					const problem = outcomeProblem(found);
+					if (problem !== null) fail("outcome", `invalid outcome: ${problem}; outcome ${show(found)}`, at);
+				}
+				return found;
+			};
+			checkState(state, 0);
+			outcome = findOutcome(state, 0);
+			let broken = false;
+			for (; tick < ticks && outcome === null; tick += 1) {
+				states.push(state);
+				rngs.push(rng.save());
+				let inputs = [];
+				try {
+					inputs = deepFreeze([...options.inputs?.(state, tick, driver) ?? []]);
+				} catch (error) {
+					fail("purity", `the inputs generator threw: ${errorMessage(error)}`, tick);
+				}
+				for (const input of inputs) {
+					rec.ran("json");
+					if (!isJson(input)) fail("json", `an input isn't JSON: ${jsonProblem(input)}`, tick, input);
+					checkSchema(simulation.schemas.input, input, "an input", (m) => fail("schemas", m, tick, input));
+					log.push({
+						tick,
+						input
+					});
+				}
+				let trial = null;
+				const trialRng = cloneRng(rng);
+				try {
+					trial = simulation.step(state, inputs, trialRng);
+				} catch (error) {
+					const message = errorMessage(error);
+					fail("purity", /read[- ]only|not extensible|frozen|Cannot (assign|add|delete|define)/i.test(message) ? `step mutated its input (states and inputs are frozen): ${message}` : `step threw: ${message}`, tick);
+					broken = true;
+					break;
+				}
+				let result;
+				const t0 = now();
+				try {
+					result = deepFreeze(simulation.step(state, inputs, rng));
+				} catch (error) {
+					fail("purity", `step threw on a second call with the same arguments: ${errorMessage(error)}`, tick);
+					broken = true;
+					break;
+				}
+				stepTime += now() - t0;
+				stepCount += 1;
+				rec.ran("purity");
+				const diff = firstDifference(trial, result) ?? firstDifference(trialRng.save(), rng.save());
+				if (diff !== null) fail("purity", `step gave two different answers for the same state, inputs and generator: ${diff}`, tick);
+				rec.ran("json");
+				if (!isJson(result)) fail("json", `a step result isn't JSON: ${jsonProblem(result)}`, tick);
+				for (const event of result.events ?? []) checkSchema(simulation.schemas.event, event, "an event", (m) => fail("schemas", m, tick));
+				results.push(result);
+				state = result.state;
+				checkState(state, tick + 1);
+				outcome = findOutcome(state, tick + 1);
+			}
+			totalTicks += tick;
+			if (broken) continue;
+			states.push(state);
+			rngs.push(rng.save());
+			if (outcome === null && options.requireOutcome === true) {
+				rec.ran("outcome");
+				fail("outcome", `no outcome after ${ticks} ticks (raise ticks, or drop requireOutcome)`, tick);
+			}
+			const endTick = tick;
+			const final = state;
+			const inputsAt = (t) => log.filter((entry) => entry.tick === t).map((entry) => entry.input);
+			rec.ran("determinism");
+			try {
+				const again = restoreRng(seedState);
+				const init = simulation.init(config, again);
+				let current = init.ok ? init.value : null;
+				const initDiff = init.ok ? firstDifference(states[0], init.value) : "init rejected";
+				if (initDiff !== null) fail("determinism", `init gave a different state for the same seed: ${initDiff}`, 0);
+				for (let t = 0; t < endTick && current !== null && initDiff === null; t += 1) {
+					const result = simulation.step(current, inputsAt(t), again);
+					const d = firstDifference(results[t], result) ?? firstDifference(rngs[t + 1], again.save());
+					if (d !== null) {
+						fail("determinism", `a second run from the same seed diverged at tick ${t}: ${d}`, t);
+						break;
+					}
+					current = result.state;
+				}
+			} catch (error) {
+				fail("determinism", `a second run threw: ${errorMessage(error)}`, 0);
+			}
+			{
+				rec.ran("replay");
+				const replay = replayUpTo(endTick);
+				if (!isJson(replay)) fail("replay", "the replay isn't JSON", endTick);
+				else try {
+					const result = replaySimulation$1(simulation, jsonRoundTrip(replay));
+					if (!result.ok) fail("replay", `the replay doesn't start: ${show(result.error)}`, endTick);
+					else {
+						const d = firstDifference(final, result.value.state) ?? firstDifference(outcome, result.value.outcome);
+						if (d !== null) fail("replay", `the replay ends somewhere else: ${d}`, endTick);
+					}
+					const runner = replaySimulation(simulation, jsonRoundTrip(replay));
+					if (!runner.ok) fail("replay", `the session runner's replay doesn't start: ${show(runner.error)}`, endTick);
+					else {
+						const d = firstDifference(final, runner.value.state) ?? firstDifference(rngs[endTick], runner.value.rng);
+						if (d !== null) fail("replay", `the session runner's replay ends somewhere else: ${d}`, endTick);
+					}
+				} catch (error) {
+					fail("replay", `replaying threw: ${errorMessage(error)}`, endTick);
+				}
+			}
+			{
+				rec.ran("checkpoint");
+				const k = Math.min(options.checkpointAt ?? Math.floor(endTick / 2), endTick);
+				const checkpoint = {
+					state: states[k],
+					rng: rngs[k],
+					tick: k
+				};
+				if (!isJson(checkpoint)) fail("checkpoint", "the checkpoint isn't JSON", k);
+				else {
+					const restored = jsonRoundTrip(checkpoint);
+					const decoded = await validate(simulation.schemas.state, restored.state);
+					if (!decoded.ok) fail("checkpoint", `a checkpoint state fails schemas.state: ${formatIssues(decoded.issues)}`, k);
+					else if (!deepEqual(decoded.value, states[k])) fail("checkpoint", `schemas.state changed a valid checkpoint state: ${firstDifference(states[k], decoded.value)}`, k);
+					else try {
+						const resumed = restoreRng(restored.rng);
+						let current = decoded.value;
+						for (let t = k; t < endTick; t += 1) current = simulation.step(current, inputsAt(t), resumed).state;
+						const d = firstDifference(final, current);
+						if (d !== null) fail("checkpoint", `resuming from the checkpoint at tick ${k} ended differently: ${d}`, k);
+					} catch (error) {
+						fail("checkpoint", `resuming from a checkpoint threw: ${errorMessage(error)}`, k);
+					}
+				}
+			}
+		}
+	}
+	await Promise.all(validations);
+	if (options.stepBudgetMs !== void 0 && stepCount > 0) {
+		rec.ran("budget");
+		const mean = stepTime / stepCount;
+		if (mean > options.stepBudgetMs) rec.fail("budget", { message: `the mean step took ${mean.toFixed(3)} ms, over the ${options.stepBudgetMs} ms budget` });
+		else rec.note("budget", `mean step ${mean.toFixed(3)} ms`);
+	}
+	return rec.report(options.name ?? "simulation", totalRuns, totalTicks);
+};
+//#endregion
+export { SIMULATION_CHECKS, checkSimulation };
+
+//# sourceMappingURL=simulation-conformance.js.map

package/dist/simulation-conformance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"simulation-conformance.js","names":["replaySimulation","runnerReplaySimulation"],"sources":["../src/simulation-conformance.ts"],"sourcesContent":["// The Layer 3 conformance suite (game-contract.md, \"Conformance tests\", Layer 3). It runs\n// fixed-step simulations from fixed seeds with generated tick inputs and checks determinism,\n// replay, checkpoints, JSON safety, schemas, step purity, invariants and outcomes.\n\nimport {\n  isJson,\n  type FixedStepSimulation,\n  type Json,\n  type Outcome,\n  type Rng,\n  type RngState,\n  type StepResult,\n  type TickInput,\n  type Validator,\n} from '@joystyk/contracts';\nimport { restoreRng } from '@joystyk/kit';\nimport { replaySimulation as runnerReplaySimulation } from '@joystyk/session';\nimport { simulationReplay } from './builders.ts';\nimport { deepEqual, deepFreeze, errorMessage, firstDifference, jsonProblem, jsonRoundTrip, show } from './deep.ts';\nimport type { InvariantResult } from './engine-conformance.ts';\nimport { replaySimulation } from './replay.ts';\nimport { Recorder, type ConformanceReport, type Failure } from './report.ts';\nimport { cloneRng, testRng, testSeed } from './rng.ts';\nimport { formatIssues, validate } from './schema.ts';\n\n/** Options for `checkSimulation` and `runSimulationConformance`. */\nexport type SimulationConformanceOptions<State, Input, Config> = {\n  /** A name for reports and the vitest `describe` block. */\n  readonly name?: string;\n  /** The game id written into replays. Default \"test-game\". */\n  readonly gameId?: string;\n  /** The configs to start from; each runs `runs` times with different seeds. */\n  readonly configs: readonly Config[];\n  /** Runs per config. Default 4. */\n  readonly runs?: number;\n  /** Ticks per run (a run also stops at its outcome). Default 1000. */\n  readonly ticks?: number;\n  /** The base seed. Run `r` of config `c` uses the seed string `${seed}/${c}/${r}`. Default \"conformance\". */\n  readonly seed?: string;\n  /** Scripted inputs for a tick. Draw any randomness from `rng`. Default: no inputs. */\n  readonly inputs?: (state: State, tick: number, rng: Rng) => readonly Input[];\n  /** Called on every state the simulation reaches. */\n  readonly invariants?: (state: State) => InvariantResult;\n  /** Fail a run that has no outcome after `ticks` ticks. Default false. */\n  readonly requireOutcome?: boolean;\n  /** The tick of the checkpoint in the checkpoint-equivalence check. Default half the run. */\n  readonly checkpointAt?: number;\n  /** Fail when the mean step takes longer than this many milliseconds. Off by default. */\n  readonly stepBudgetMs?: number;\n  /** Run only one run, to reproduce a reported failure (`setup` is the config index). */\n  readonly only?: { readonly setup: number; readonly game: number };\n  /** Failures kept per check in the report. Default 3. */\n  readonly maxFailuresPerCheck?: number;\n};\n\n/** The checks this suite runs, in report order. */\nexport const SIMULATION_CHECKS = [\n  { id: 'determinism', title: 'Determinism: the same seed and tick inputs give the same states and events' },\n  { id: 'replay', title: 'Replay: the recorded tick log reproduces the final state' },\n  { id: 'checkpoint', title: 'Checkpoints: saving, restoring and continuing equals running straight through' },\n  { id: 'json', title: 'JSON safety of configs, states, inputs, events and outcomes' },\n  { id: 'schemas', title: \"Schema agreement: every value passes the simulation's own schemas\" },\n  {\n    id: 'purity',\n    title: 'Step purity: the same state, inputs and generator give the same next state, without mutation',\n  },\n  { id: 'invariants', title: 'Invariants hold on every state the simulation reaches' },\n  { id: 'outcome', title: 'Outcomes are valid and detected in time' },\n  { id: 'budget', title: 'Step-time budget' },\n] as const;\n\n/** The id of one simulation check. */\nexport type SimulationCheckId = (typeof SIMULATION_CHECKS)[number]['id'];\n\nconst now = (): number => (globalThis as { performance?: { now(): number } }).performance?.now() ?? 0;\n\nconst outcomeProblem = (outcome: Outcome): string | null => {\n  if (!['won', 'lost', 'draw', 'completed', 'abandoned'].includes(outcome.result))\n    return `unknown result ${show(outcome.result)}`;\n  if (typeof outcome.summary !== 'string') return 'summary must be a string';\n  if (outcome.elapsedMs !== undefined || outcome.undosUsed !== undefined || outcome.assists !== undefined) {\n    return 'simulations never set elapsedMs, undosUsed or assists; the scheduler adds them';\n  }\n  if (outcome.placements.length === 0) return 'placements is empty; a solo game has one entry';\n  for (const p of outcome.placements) {\n    if (!Number.isInteger(p.place) || p.place < 1)\n      return `seat ${p.seat} has place ${show(p.place)}; places start at 1`;\n  }\n  if (new Set(outcome.placements.map((p) => p.seat)).size !== outcome.placements.length)\n    return 'a seat is placed twice';\n  return null;\n};\n\n/**\n * Runs the Layer 3 conformance suite against `simulation` and returns a report. It never\n * throws for a failing check. Use `runSimulationConformance` to get one vitest case per check.\n */\nexport const checkSimulation = async <\n  State extends Json,\n  Input extends Json,\n  View,\n  Event extends Json,\n  Config extends Json,\n>(\n  simulation: FixedStepSimulation<State, Input, View, Event, Config>,\n  options: SimulationConformanceOptions<State, Input, Config>,\n): Promise<ConformanceReport> => {\n  if (options.configs.length === 0) throw new TypeError('Simulation conformance needs at least one config.');\n  const rec = new Recorder(SIMULATION_CHECKS, options.maxFailuresPerCheck ?? 3);\n  const runs = options.runs ?? 4;\n  const ticks = options.ticks ?? 1000;\n  const baseSeed = options.seed ?? 'conformance';\n  const gameId = options.gameId ?? 'test-game';\n  if (options.invariants === undefined) rec.skip('invariants', 'no invariants hook given');\n  if (options.stepBudgetMs === undefined) rec.skip('budget', 'no stepBudgetMs given');\n\n  const validations: Promise<void>[] = [];\n  const checkSchema = (\n    schema: Validator<unknown>,\n    value: unknown,\n    what: string,\n    fail: (message: string) => void,\n  ): void => {\n    rec.ran('schemas');\n    validations.push(\n      validate(schema, value).then(\n        (result) => {\n          if (!result.ok) fail(`${what} fails its schema: ${formatIssues(result.issues)}; value ${show(value)}`);\n        },\n        (error: unknown) => fail(`${what}: the schema threw ${errorMessage(error)}`),\n      ),\n    );\n  };\n\n  let totalRuns = 0;\n  let totalTicks = 0;\n  let stepTime = 0;\n  let stepCount = 0;\n\n  for (const [configIndex, config] of options.configs.entries()) {\n    rec.ran('json');\n    if (!isJson(config))\n      rec.fail('json', { message: `config ${configIndex} isn't JSON: ${jsonProblem(config)}`, setup: configIndex });\n    checkSchema(simulation.schemas.config, config, `config ${configIndex}`, (message) =>\n      rec.fail('schemas', { message, setup: configIndex }),\n    );\n\n    for (let runIndex = 0; runIndex < runs; runIndex += 1) {\n      if (options.only !== undefined && (options.only.setup !== configIndex || options.only.game !== runIndex))\n        continue;\n      totalRuns += 1;\n      const seed = `${baseSeed}/${configIndex}/${runIndex}`;\n      const seedState = testSeed(seed, 'engine');\n      const driver = testRng(seed, 'driver');\n      const log: TickInput<Input>[] = [];\n      const states: State[] = [];\n      const rngs: RngState[] = [];\n      const results: StepResult<State, Event>[] = [];\n\n      const replayUpTo = (endTick: number) =>\n        simulationReplay({\n          gameId,\n          rulesVersion: simulation.rulesVersion,\n          config,\n          seed: seedState,\n          inputs: log.filter((entry) => entry.tick < endTick),\n          endTick,\n        });\n      const fail = (id: SimulationCheckId, message: string, tick: number, input?: unknown): void => {\n        const failure: Failure = {\n          message,\n          setup: configIndex,\n          game: runIndex,\n          seed,\n          step: tick,\n          replay: replayUpTo(tick),\n          ...(input === undefined ? {} : { input }),\n        };\n        rec.fail(id, failure);\n      };\n\n      const rng = restoreRng(seedState);\n      let started: ReturnType<typeof simulation.init>;\n      try {\n        started = simulation.init(config, rng);\n      } catch (error) {\n        fail('purity', `init threw: ${errorMessage(error)}`, 0);\n        continue;\n      }\n      if (!started.ok) {\n        fail('outcome', `init rejected config ${configIndex}: ${show(started.error)}`, 0);\n        continue;\n      }\n      let state = deepFreeze(started.value);\n      let outcome: Outcome | null = null;\n      let tick = 0;\n\n      const checkState = (value: State, at: number): void => {\n        rec.ran('json');\n        if (!isJson(value)) fail('json', `the state isn't JSON: ${jsonProblem(value)}`, at);\n        checkSchema(simulation.schemas.state, value, 'the state', (m) => fail('schemas', m, at));\n        if (options.invariants !== undefined) {\n          rec.ran('invariants');\n          try {\n            const result = options.invariants(value);\n            if (result === false || typeof result === 'string') {\n              fail(\n                'invariants',\n                `invariant violated: ${result === false ? 'the invariant hook returned false' : result}`,\n                at,\n              );\n            }\n          } catch (error) {\n            fail('invariants', `invariant violated: ${errorMessage(error)}`, at);\n          }\n        }\n      };\n      const findOutcome = (value: State, at: number): Outcome | null => {\n        const found = simulation.outcome(value);\n        if (found !== null) {\n          rec.ran('outcome');\n          if (!isJson(found)) fail('json', `the outcome isn't JSON: ${jsonProblem(found)}`, at);\n          const problem = outcomeProblem(found);\n          if (problem !== null) fail('outcome', `invalid outcome: ${problem}; outcome ${show(found)}`, at);\n        }\n        return found;\n      };\n\n      checkState(state, 0);\n      outcome = findOutcome(state, 0);\n      let broken = false;\n      for (; tick < ticks && outcome === null; tick += 1) {\n        states.push(state);\n        rngs.push(rng.save());\n        let inputs: readonly Input[] = [];\n        try {\n          inputs = deepFreeze([...(options.inputs?.(state, tick, driver) ?? [])]);\n        } catch (error) {\n          fail('purity', `the inputs generator threw: ${errorMessage(error)}`, tick);\n        }\n        for (const input of inputs) {\n          rec.ran('json');\n          if (!isJson(input)) fail('json', `an input isn't JSON: ${jsonProblem(input)}`, tick, input);\n          checkSchema(simulation.schemas.input, input, 'an input', (m) => fail('schemas', m, tick, input));\n          log.push({ tick, input });\n        }\n\n        // Purity: a trial step on a copy of the generator, then the real one; they must agree.\n        let trial: StepResult<State, Event> | null = null;\n        const trialRng = cloneRng(rng);\n        try {\n          trial = simulation.step(state, inputs, trialRng);\n        } catch (error) {\n          const message = errorMessage(error);\n          const mutation = /read[- ]only|not extensible|frozen|Cannot (assign|add|delete|define)/i.test(message);\n          fail(\n            'purity',\n            mutation ? `step mutated its input (states and inputs are frozen): ${message}` : `step threw: ${message}`,\n            tick,\n          );\n          broken = true;\n          break;\n        }\n        let result: StepResult<State, Event>;\n        const t0 = now();\n        try {\n          result = deepFreeze(simulation.step(state, inputs, rng));\n        } catch (error) {\n          fail('purity', `step threw on a second call with the same arguments: ${errorMessage(error)}`, tick);\n          broken = true;\n          break;\n        }\n        stepTime += now() - t0;\n        stepCount += 1;\n        rec.ran('purity');\n        const diff = firstDifference(trial, result) ?? firstDifference(trialRng.save(), rng.save());\n        if (diff !== null)\n          fail('purity', `step gave two different answers for the same state, inputs and generator: ${diff}`, tick);\n\n        rec.ran('json');\n        if (!isJson(result)) fail('json', `a step result isn't JSON: ${jsonProblem(result)}`, tick);\n        for (const event of result.events ?? [])\n          checkSchema(simulation.schemas.event, event, 'an event', (m) => fail('schemas', m, tick));\n        results.push(result);\n        state = result.state;\n        checkState(state, tick + 1);\n        outcome = findOutcome(state, tick + 1);\n      }\n      totalTicks += tick;\n      if (broken) continue;\n      states.push(state);\n      rngs.push(rng.save());\n      if (outcome === null && options.requireOutcome === true) {\n        rec.ran('outcome');\n        fail('outcome', `no outcome after ${ticks} ticks (raise ticks, or drop requireOutcome)`, tick);\n      }\n      const endTick = tick;\n      const final = state;\n      const inputsAt = (t: number): Input[] => log.filter((entry) => entry.tick === t).map((entry) => entry.input);\n\n      // Determinism: a second run from the same seed with the recorded inputs.\n      {\n        rec.ran('determinism');\n        try {\n          const again = restoreRng(seedState);\n          const init = simulation.init(config, again);\n          let current = init.ok ? init.value : null;\n          const initDiff = init.ok ? firstDifference(states[0], init.value) : 'init rejected';\n          if (initDiff !== null) fail('determinism', `init gave a different state for the same seed: ${initDiff}`, 0);\n          for (let t = 0; t < endTick && current !== null && initDiff === null; t += 1) {\n            const result = simulation.step(current, inputsAt(t), again);\n            const d = firstDifference(results[t], result) ?? firstDifference(rngs[t + 1], again.save());\n            if (d !== null) {\n              fail('determinism', `a second run from the same seed diverged at tick ${t}: ${d}`, t);\n              break;\n            }\n            current = result.state;\n          }\n        } catch (error) {\n          fail('determinism', `a second run threw: ${errorMessage(error)}`, 0);\n        }\n      }\n\n      // Replay through the replay format, after a JSON round trip.\n      {\n        rec.ran('replay');\n        const replay = replayUpTo(endTick);\n        if (!isJson(replay)) fail('replay', \"the replay isn't JSON\", endTick);\n        else {\n          try {\n            const result = replaySimulation(simulation, jsonRoundTrip(replay));\n            if (!result.ok) fail('replay', `the replay doesn't start: ${show(result.error)}`, endTick);\n            else {\n              const d = firstDifference(final, result.value.state) ?? firstDifference(outcome, result.value.outcome);\n              if (d !== null) fail('replay', `the replay ends somewhere else: ${d}`, endTick);\n            }\n            // The session scheduler's own replay.\n            const runner = runnerReplaySimulation(simulation, jsonRoundTrip(replay));\n            if (!runner.ok) fail('replay', `the session runner's replay doesn't start: ${show(runner.error)}`, endTick);\n            else {\n              const d = firstDifference(final, runner.value.state) ?? firstDifference(rngs[endTick], runner.value.rng);\n              if (d !== null) fail('replay', `the session runner's replay ends somewhere else: ${d}`, endTick);\n            }\n          } catch (error) {\n            fail('replay', `replaying threw: ${errorMessage(error)}`, endTick);\n          }\n        }\n      }\n\n      // Checkpoint equivalence: save at a tick, restore after JSON, run the rest.\n      {\n        rec.ran('checkpoint');\n        const k = Math.min(options.checkpointAt ?? Math.floor(endTick / 2), endTick);\n        const checkpoint = { state: states[k], rng: rngs[k], tick: k };\n        if (!isJson(checkpoint)) fail('checkpoint', \"the checkpoint isn't JSON\", k);\n        else {\n          const restored = jsonRoundTrip(checkpoint);\n          const decoded = await validate(simulation.schemas.state, restored.state);\n          if (!decoded.ok)\n            fail('checkpoint', `a checkpoint state fails schemas.state: ${formatIssues(decoded.issues)}`, k);\n          else if (!deepEqual(decoded.value, states[k])) {\n            fail(\n              'checkpoint',\n              `schemas.state changed a valid checkpoint state: ${firstDifference(states[k], decoded.value)}`,\n              k,\n            );\n          } else {\n            try {\n              const resumed = restoreRng(restored.rng as RngState);\n              let current = decoded.value;\n              for (let t = k; t < endTick; t += 1) {\n                current = simulation.step(current, inputsAt(t), resumed).state;\n              }\n              const d = firstDifference(final, current);\n              if (d !== null)\n                fail('checkpoint', `resuming from the checkpoint at tick ${k} ended differently: ${d}`, k);\n            } catch (error) {\n              fail('checkpoint', `resuming from a checkpoint threw: ${errorMessage(error)}`, k);\n            }\n          }\n        }\n      }\n    }\n  }\n\n  await Promise.all(validations);\n  if (options.stepBudgetMs !== undefined && stepCount > 0) {\n    rec.ran('budget');\n    const mean = stepTime / stepCount;\n    if (mean > options.stepBudgetMs) {\n      rec.fail('budget', {\n        message: `the mean step took ${mean.toFixed(3)} ms, over the ${options.stepBudgetMs} ms budget`,\n      });\n    } else {\n      rec.note('budget', `mean step ${mean.toFixed(3)} ms`);\n    }\n  }\n  return rec.report(options.name ?? 'simulation', totalRuns, totalTicks);\n};\n"],"mappings":"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"}

package/dist/storage.d.ts

@@ -0,0 +1,29 @@
+import { type GameStorage, type Json } from '@joystyk/contracts';
+export type StorageOperation = 'get' | 'set' | 'delete';
+/** One call the fake storage received, in order. */
+export type StorageCall = {
+    readonly op: 'get';
+    readonly key: string;
+} | {
+    readonly op: 'set';
+    readonly key: string;
+    readonly value: Json;
+} | {
+    readonly op: 'delete';
+    readonly key: string;
+};
+/** `GameStorage` plus what a test needs to inspect and break it. */
+export interface FakeStorage extends GameStorage {
+    /** The stored values, decoded, keyed by storage key. */
+    entries(): Record<string, Json>;
+    /** Every call so far, in order (failed calls included). */
+    calls(): readonly StorageCall[];
+    /** Makes the next call of `op` reject with `error` (default: an Error naming the key). */
+    failNext(op: StorageOperation, error?: unknown): void;
+}
+/**
+ * An in-memory `GameStorage`. Values are stored as JSON text, as a real store serializes
+ * them, so reading returns a fresh copy and storing a value that isn't JSON (`undefined`,
+ * `NaN`, a `Date`, a class instance) rejects with a `TypeError` instead of passing silently.
+ */
+export declare const createFakeStorage: (initial?: Readonly<Record<string, Json>>) => FakeStorage;

package/dist/storage.js

@@ -0,0 +1,63 @@
+import { isJson } from "@joystyk/contracts";
+//#region src/storage.ts
+/**
+* An in-memory `GameStorage`. Values are stored as JSON text, as a real store serializes
+* them, so reading returns a fresh copy and storing a value that isn't JSON (`undefined`,
+* `NaN`, a `Date`, a class instance) rejects with a `TypeError` instead of passing silently.
+*/
+var createFakeStorage = (initial = {}) => {
+	const data = /* @__PURE__ */ new Map();
+	const log = [];
+	const failures = [];
+	const put = (key, value) => {
+		if (!isJson(value)) throw new TypeError(`Storage values must be JSON; "${key}" isn't.`);
+		data.set(key, JSON.stringify(value));
+	};
+	for (const [key, value] of Object.entries(initial)) put(key, value);
+	const takeFailure = (op, key) => {
+		const index = failures.findIndex((f) => f.op === op);
+		if (index === -1) return;
+		const [failure] = failures.splice(index, 1);
+		throw failure?.error ?? /* @__PURE__ */ new Error(`Fake storage: ${op} "${key}" failed.`);
+	};
+	return {
+		get: async (key) => {
+			log.push({
+				op: "get",
+				key
+			});
+			takeFailure("get", key);
+			const text = data.get(key);
+			return text === void 0 ? null : JSON.parse(text);
+		},
+		set: async (key, value) => {
+			log.push({
+				op: "set",
+				key,
+				value
+			});
+			takeFailure("set", key);
+			put(key, value);
+		},
+		delete: async (key) => {
+			log.push({
+				op: "delete",
+				key
+			});
+			takeFailure("delete", key);
+			data.delete(key);
+		},
+		entries: () => Object.fromEntries([...data].map(([key, text]) => [key, JSON.parse(text)])),
+		calls: () => log.slice(),
+		failNext: (op, error) => {
+			failures.push({
+				op,
+				error: error ?? /* @__PURE__ */ new Error(`Fake storage: injected ${op} failure.`)
+			});
+		}
+	};
+};
+//#endregion
+export { createFakeStorage };
+
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","names":[],"sources":["../src/storage.ts"],"sourcesContent":["// A fake storage port: the contract's `GameStorage`, in memory, with failure injection.\n\nimport { isJson, type GameStorage, type Json } from '@joystyk/contracts';\n\nexport type StorageOperation = 'get' | 'set' | 'delete';\n\n/** One call the fake storage received, in order. */\nexport type StorageCall =\n  | { readonly op: 'get'; readonly key: string }\n  | { readonly op: 'set'; readonly key: string; readonly value: Json }\n  | { readonly op: 'delete'; readonly key: string };\n\n/** `GameStorage` plus what a test needs to inspect and break it. */\nexport interface FakeStorage extends GameStorage {\n  /** The stored values, decoded, keyed by storage key. */\n  entries(): Record<string, Json>;\n  /** Every call so far, in order (failed calls included). */\n  calls(): readonly StorageCall[];\n  /** Makes the next call of `op` reject with `error` (default: an Error naming the key). */\n  failNext(op: StorageOperation, error?: unknown): void;\n}\n\n/**\n * An in-memory `GameStorage`. Values are stored as JSON text, as a real store serializes\n * them, so reading returns a fresh copy and storing a value that isn't JSON (`undefined`,\n * `NaN`, a `Date`, a class instance) rejects with a `TypeError` instead of passing silently.\n */\nexport const createFakeStorage = (initial: Readonly<Record<string, Json>> = {}): FakeStorage => {\n  const data = new Map<string, string>();\n  const log: StorageCall[] = [];\n  const failures: { op: StorageOperation; error: unknown }[] = [];\n\n  const put = (key: string, value: Json): void => {\n    if (!isJson(value)) throw new TypeError(`Storage values must be JSON; \"${key}\" isn't.`);\n    data.set(key, JSON.stringify(value));\n  };\n  for (const [key, value] of Object.entries(initial)) put(key, value);\n\n  const takeFailure = (op: StorageOperation, key: string): void => {\n    const index = failures.findIndex((f) => f.op === op);\n    if (index === -1) return;\n    const [failure] = failures.splice(index, 1);\n    throw failure?.error ?? new Error(`Fake storage: ${op} \"${key}\" failed.`);\n  };\n\n  return {\n    get: async (key) => {\n      log.push({ op: 'get', key });\n      takeFailure('get', key);\n      const text = data.get(key);\n      return text === undefined ? null : (JSON.parse(text) as Json);\n    },\n    set: async (key, value) => {\n      log.push({ op: 'set', key, value });\n      takeFailure('set', key);\n      put(key, value);\n    },\n    delete: async (key) => {\n      log.push({ op: 'delete', key });\n      takeFailure('delete', key);\n      data.delete(key);\n    },\n    entries: () => Object.fromEntries([...data].map(([key, text]) => [key, JSON.parse(text) as Json])),\n    calls: () => log.slice(),\n    failNext: (op, error) => {\n      failures.push({ op, error: error ?? new Error(`Fake storage: injected ${op} failure.`) });\n    },\n  };\n};\n"],"mappings":";;;;;;;AA2BA,IAAa,qBAAqB,UAA0C,CAAC,MAAmB;CAC9F,MAAM,uBAAO,IAAI,IAAoB;CACrC,MAAM,MAAqB,CAAC;CAC5B,MAAM,WAAuD,CAAC;CAE9D,MAAM,OAAO,KAAa,UAAsB;EAC9C,IAAI,CAAC,OAAO,KAAK,GAAG,MAAM,IAAI,UAAU,iCAAiC,IAAI,SAAS;EACtF,KAAK,IAAI,KAAK,KAAK,UAAU,KAAK,CAAC;CACrC;CACA,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,OAAO,GAAG,IAAI,KAAK,KAAK;CAElE,MAAM,eAAe,IAAsB,QAAsB;EAC/D,MAAM,QAAQ,SAAS,WAAW,MAAM,EAAE,OAAO,EAAE;EACnD,IAAI,UAAU,IAAI;EAClB,MAAM,CAAC,WAAW,SAAS,OAAO,OAAO,CAAC;EAC1C,MAAM,SAAS,yBAAS,IAAI,MAAM,iBAAiB,GAAG,IAAI,IAAI,UAAU;CAC1E;CAEA,OAAO;EACL,KAAK,OAAO,QAAQ;GAClB,IAAI,KAAK;IAAE,IAAI;IAAO;GAAI,CAAC;GAC3B,YAAY,OAAO,GAAG;GACtB,MAAM,OAAO,KAAK,IAAI,GAAG;GACzB,OAAO,SAAS,KAAA,IAAY,OAAQ,KAAK,MAAM,IAAI;EACrD;EACA,KAAK,OAAO,KAAK,UAAU;GACzB,IAAI,KAAK;IAAE,IAAI;IAAO;IAAK;GAAM,CAAC;GAClC,YAAY,OAAO,GAAG;GACtB,IAAI,KAAK,KAAK;EAChB;EACA,QAAQ,OAAO,QAAQ;GACrB,IAAI,KAAK;IAAE,IAAI;IAAU;GAAI,CAAC;GAC9B,YAAY,UAAU,GAAG;GACzB,KAAK,OAAO,GAAG;EACjB;EACA,eAAe,OAAO,YAAY,CAAC,GAAG,IAAI,CAAC,CAAC,KAAK,CAAC,KAAK,UAAU,CAAC,KAAK,KAAK,MAAM,IAAI,CAAS,CAAC,CAAC;EACjG,aAAa,IAAI,MAAM;EACvB,WAAW,IAAI,UAAU;GACvB,SAAS,KAAK;IAAE;IAAI,OAAO,yBAAS,IAAI,MAAM,0BAA0B,GAAG,UAAU;GAAE,CAAC;EAC1F;CACF;AACF"}

package/dist/vitest.d.ts

@@ -0,0 +1,32 @@
+import type { DiscreteEngine, FixedStepSimulation, Json } from '@joystyk/contracts';
+import { type EngineConformanceOptions } from './engine-conformance.js';
+import { type ConformanceReport } from './report.js';
+import { type SimulationConformanceOptions } from './simulation-conformance.js';
+/** Options the vitest wrappers add. */
+export type VitestOptions = {
+    /**
+     * Timeout for each case in milliseconds. The suite plays its games once, in the first case,
+     * so that case takes all the time: over a minute for the heaviest games on a loaded machine.
+     * Default 300 000.
+     */
+    readonly timeoutMs?: number;
+};
+/** Thrown by a failing conformance case; its message is the check's report. */
+export declare class ConformanceError extends Error {
+    readonly name = "ConformanceError";
+}
+/** Throws a `ConformanceError` with the whole report unless every check passed or was skipped. */
+export declare const expectConformance: (report: ConformanceReport) => void;
+/**
+ * Registers the Layer 2 conformance suite as vitest cases: a `describe` block with one `it`
+ * per check. The suite plays its games once, in whichever case runs first; a failing case
+ * prints the failures with their seeds and input sequences. Call it at the top level of a
+ * test file:
+ *
+ * ```ts
+ * runEngineConformance(engine, { configs: [{ heap: 10 }], seatCounts: [2], commands });
+ * ```
+ */
+export declare const runEngineConformance: <State extends Json, Command extends Json, View extends Json, Event extends Json, Config extends Json>(engine: DiscreteEngine<State, Command, View, Event, Config>, options: EngineConformanceOptions<State, Command, Config> & VitestOptions) => void;
+/** Registers the Layer 3 conformance suite as vitest cases, like `runEngineConformance`. */
+export declare const runSimulationConformance: <State extends Json, Input extends Json, View, Event extends Json, Config extends Json>(simulation: FixedStepSimulation<State, Input, View, Event, Config>, options: SimulationConformanceOptions<State, Input, Config> & VitestOptions) => void;

package/dist/vitest.js

@@ -0,0 +1,45 @@
+import { checkById, formatCheck, formatReport } from "./report.js";
+import { ENGINE_CHECKS, checkEngine } from "./engine-conformance.js";
+import { SIMULATION_CHECKS, checkSimulation } from "./simulation-conformance.js";
+import { describe, it } from "vitest";
+//#region src/vitest.ts
+var CASE_TIMEOUT_MS = 3e5;
+/** Thrown by a failing conformance case; its message is the check's report. */
+var ConformanceError = class extends Error {
+	name = "ConformanceError";
+};
+/** Throws a `ConformanceError` with the whole report unless every check passed or was skipped. */
+var expectConformance = (report) => {
+	if (!report.ok) throw new ConformanceError(formatReport(report));
+};
+var register = (subject, checks, run, timeoutMs) => {
+	describe(`conformance: ${subject}`, () => {
+		let report;
+		for (const check of checks) it(`[${check.id}] ${check.title}`, async (context) => {
+			report ??= run();
+			const result = checkById(await report, check.id);
+			if (result.status === "skipped") {
+				context.skip(result.note);
+				return;
+			}
+			if (result.status === "failed") throw new ConformanceError(formatCheck(result));
+		}, timeoutMs);
+	});
+};
+/**
+* Registers the Layer 2 conformance suite as vitest cases: a `describe` block with one `it`
+* per check. The suite plays its games once, in whichever case runs first; a failing case
+* prints the failures with their seeds and input sequences. Call it at the top level of a
+* test file:
+*
+* ```ts
+* runEngineConformance(engine, { configs: [{ heap: 10 }], seatCounts: [2], commands });
+* ```
+*/
+var runEngineConformance = (engine, options) => register(options.name ?? "engine", ENGINE_CHECKS, () => checkEngine(engine, options), options.timeoutMs ?? CASE_TIMEOUT_MS);
+/** Registers the Layer 3 conformance suite as vitest cases, like `runEngineConformance`. */
+var runSimulationConformance = (simulation, options) => register(options.name ?? "simulation", SIMULATION_CHECKS, () => checkSimulation(simulation, options), options.timeoutMs ?? CASE_TIMEOUT_MS);
+//#endregion
+export { ConformanceError, expectConformance, runEngineConformance, runSimulationConformance };
+
+//# sourceMappingURL=vitest.js.map

package/dist/vitest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest.js","names":[],"sources":["../src/vitest.ts"],"sourcesContent":["// The vitest face of the suites: one `it` per check, each failing with a reproducible report.\n\nimport type { DiscreteEngine, FixedStepSimulation, Json } from '@joystyk/contracts';\nimport { describe, it } from 'vitest';\nimport { checkEngine, ENGINE_CHECKS, type EngineConformanceOptions } from './engine-conformance.ts';\nimport { checkById, formatCheck, formatReport, type ConformanceReport } from './report.ts';\nimport { checkSimulation, SIMULATION_CHECKS, type SimulationConformanceOptions } from './simulation-conformance.ts';\n\n/** Options the vitest wrappers add. */\nexport type VitestOptions = {\n  /**\n   * Timeout for each case in milliseconds. The suite plays its games once, in the first case,\n   * so that case takes all the time: over a minute for the heaviest games on a loaded machine.\n   * Default 300 000.\n   */\n  readonly timeoutMs?: number;\n};\n\nconst CASE_TIMEOUT_MS = 300_000;\n\n/** Thrown by a failing conformance case; its message is the check's report. */\nexport class ConformanceError extends Error {\n  override readonly name = 'ConformanceError';\n}\n\n/** Throws a `ConformanceError` with the whole report unless every check passed or was skipped. */\nexport const expectConformance = (report: ConformanceReport): void => {\n  if (!report.ok) throw new ConformanceError(formatReport(report));\n};\n\nconst register = (\n  subject: string,\n  checks: readonly { readonly id: string; readonly title: string }[],\n  run: () => Promise<ConformanceReport>,\n  timeoutMs: number,\n): void => {\n  describe(`conformance: ${subject}`, () => {\n    let report: Promise<ConformanceReport> | undefined;\n    for (const check of checks) {\n      it(\n        `[${check.id}] ${check.title}`,\n        async (context) => {\n          report ??= run();\n          const result = checkById(await report, check.id);\n          if (result.status === 'skipped') {\n            context.skip(result.note);\n            return;\n          }\n          if (result.status === 'failed') throw new ConformanceError(formatCheck(result));\n        },\n        timeoutMs,\n      );\n    }\n  });\n};\n\n/**\n * Registers the Layer 2 conformance suite as vitest cases: a `describe` block with one `it`\n * per check. The suite plays its games once, in whichever case runs first; a failing case\n * prints the failures with their seeds and input sequences. Call it at the top level of a\n * test file:\n *\n * ```ts\n * runEngineConformance(engine, { configs: [{ heap: 10 }], seatCounts: [2], commands });\n * ```\n */\nexport const runEngineConformance = <\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  options: EngineConformanceOptions<State, Command, Config> & VitestOptions,\n): void =>\n  register(\n    options.name ?? 'engine',\n    ENGINE_CHECKS,\n    () => checkEngine(engine, options),\n    options.timeoutMs ?? CASE_TIMEOUT_MS,\n  );\n\n/** Registers the Layer 3 conformance suite as vitest cases, like `runEngineConformance`. */\nexport const runSimulationConformance = <\n  State extends Json,\n  Input extends Json,\n  View,\n  Event extends Json,\n  Config extends Json,\n>(\n  simulation: FixedStepSimulation<State, Input, View, Event, Config>,\n  options: SimulationConformanceOptions<State, Input, Config> & VitestOptions,\n): void =>\n  register(\n    options.name ?? 'simulation',\n    SIMULATION_CHECKS,\n    () => checkSimulation(simulation, options),\n    options.timeoutMs ?? CASE_TIMEOUT_MS,\n  );\n"],"mappings":";;;;;AAkBA,IAAM,kBAAkB;;AAGxB,IAAa,mBAAb,cAAsC,MAAM;CAC1C,OAAyB;AAC3B;;AAGA,IAAa,qBAAqB,WAAoC;CACpE,IAAI,CAAC,OAAO,IAAI,MAAM,IAAI,iBAAiB,aAAa,MAAM,CAAC;AACjE;AAEA,IAAM,YACJ,SACA,QACA,KACA,cACS;CACT,SAAS,gBAAgB,iBAAiB;EACxC,IAAI;EACJ,KAAK,MAAM,SAAS,QAClB,GACE,IAAI,MAAM,GAAG,IAAI,MAAM,SACvB,OAAO,YAAY;GACjB,WAAW,IAAI;GACf,MAAM,SAAS,UAAU,MAAM,QAAQ,MAAM,EAAE;GAC/C,IAAI,OAAO,WAAW,WAAW;IAC/B,QAAQ,KAAK,OAAO,IAAI;IACxB;GACF;GACA,IAAI,OAAO,WAAW,UAAU,MAAM,IAAI,iBAAiB,YAAY,MAAM,CAAC;EAChF,GACA,SACF;CAEJ,CAAC;AACH;;;;;;;;;;;AAYA,IAAa,wBAOX,QACA,YAEA,SACE,QAAQ,QAAQ,UAChB,qBACM,YAAY,QAAQ,OAAO,GACjC,QAAQ,aAAa,eACvB;;AAGF,IAAa,4BAOX,YACA,YAEA,SACE,QAAQ,QAAQ,cAChB,yBACM,gBAAgB,YAAY,OAAO,GACzC,QAAQ,aAAa,eACvB"}

package/dist/waiting.d.ts

@@ -0,0 +1,58 @@
+import type { FrameScheduler } from '@joystyk/session';
+/**
+ * The default wall-clock budget for a wait: generous, but under the browser and e2e
+ * projects' 60-second test timeout, so a wait that fails names what never happened instead of
+ * ending in a bare timeout.
+ */
+export declare const WAIT_BUDGET_MS = 45000;
+/** Resolves after `ms` milliseconds: for yielding to the page, never for waiting on a result. */
+export declare const pause: (ms: number) => Promise<void>;
+/**
+ * Resolves on a fresh task, without the 4 ms clamp nested timers get, so the events,
+ * commands and due timers queued before it can run.
+ */
+export declare const nextTask: () => Promise<void>;
+export type WaitOptions = {
+    /** The wall-clock budget. Default `WAIT_BUDGET_MS`. */
+    readonly timeoutMs?: number;
+    /** How often to check. Default 10 ms. */
+    readonly intervalMs?: number;
+};
+/**
+ * Resolves once `condition` holds, checking every few milliseconds. Fails with "Timed out
+ * waiting for <what>" after the budget, which by default is most of the test's own timeout.
+ */
+export declare const waitUntil: (condition: () => boolean, what: string, options?: WaitOptions) => Promise<void>;
+export type FrameWaitOptions = {
+    /** The most frames that may run a callback before the wait fails: game time. Default 3600 (a minute at 60 Hz). */
+    readonly maxFrames?: number;
+    /** The wall-clock budget, for waits on the UI while the runner is paused. Default `WAIT_BUDGET_MS`. */
+    readonly timeoutMs?: number;
+};
+/** A frame scheduler that runs only when the test says so. */
+export interface ManualFrames {
+    /** Pass this as the runner's `frames` port. */
+    readonly port: FrameScheduler;
+    /**
+     * Runs `count` frames, each `frameMs` after the last, and returns how many of them had a
+     * callback waiting. A paused or finished runner requests none, so it returns 0.
+     */
+    run(count: number): number;
+    /** True when a callback waits for the next frame. */
+    pending(): boolean;
+    /**
+     * Runs `count` frames, yielding to the page between them as `until` does, so input that
+     * arrives meanwhile is handled. For checking that nothing happens over some game time.
+     * Returns how many frames had a callback waiting.
+     */
+    advance(count: number): Promise<number>;
+    /**
+     * Runs one frame at a time until `condition` holds, yielding to the page between frames
+     * so events, commands and timers run. Game time can't outrun the check, so a phase that
+     * lasts a few ticks is never skipped, and a busy machine only makes the wait take longer.
+     * Fails after `maxFrames` frames that ran a callback, or after the wall-clock budget.
+     */
+    until(condition: () => boolean, what: string, options?: FrameWaitOptions): Promise<void>;
+}
+/** A manual frame scheduler for a fixed-step runner, at `frameMs` per frame (default 60 Hz). */
+export declare const manualFrames: (frameMs?: number) => ManualFrames;