@joystyk/testing 0.0.0-stage → 0.2.0

package/dist/report.d.ts

@@ -0,0 +1,68 @@
+import type { Replay } from '@joystyk/contracts';
+/** One reproducible failure. */
+export type Failure = {
+    readonly message: string;
+    /** Which generated game failed: rerun just it with `only: { setup, game }`. */
+    readonly setup?: number;
+    readonly game?: number;
+    /** The game's seed string; the engine's generator is `testRng(seed, 'engine')`. */
+    readonly seed?: string;
+    /** The number of inputs applied before the failure (0: right after `init`). */
+    readonly step?: number;
+    /** The replay of the accepted inputs up to the failure; `replayEngine` reproduces it. */
+    readonly replay?: Replay;
+    /** The input being checked when the failure happened, if any. */
+    readonly input?: unknown;
+};
+export type CheckStatus = 'passed' | 'failed' | 'skipped';
+/** The result of one check across every generated game. */
+export type CheckResult = {
+    readonly id: string;
+    readonly title: string;
+    readonly status: CheckStatus;
+    /** Why the check was skipped, or a note on what it covered. */
+    readonly note?: string;
+    /** How many times the check ran (positions, transitions, games …). */
+    readonly runs: number;
+    /** The first few failures; `failureCount` has the total. */
+    readonly failures: readonly Failure[];
+    readonly failureCount: number;
+};
+/** Everything a suite found. */
+export type ConformanceReport = {
+    readonly subject: string;
+    readonly ok: boolean;
+    readonly checks: readonly CheckResult[];
+    /** Games generated and inputs applied, for a sense of coverage. */
+    readonly games: number;
+    readonly steps: number;
+};
+/** The failed checks' ids. */
+export declare const failedChecks: (report: ConformanceReport) => string[];
+/** One check by id; throws if the suite has no such check. */
+export declare const checkById: (report: ConformanceReport, id: string) => CheckResult;
+/** A failure as text a person can act on: what broke, the seed, and the input sequence. */
+export declare const formatFailure: (failure: Failure) => string;
+/** A check as text: its title, status and failures. */
+export declare const formatCheck: (check: CheckResult) => string;
+/** The whole report as text. */
+export declare const formatReport: (report: ConformanceReport) => string;
+/** Collects failures per check while a suite runs. */
+export declare class Recorder {
+    #private;
+    constructor(definitions: readonly {
+        readonly id: string;
+        readonly title: string;
+    }[], limit: number);
+    /** Counts one run of a check. */
+    ran(id: string, times?: number): void;
+    /** Records a failure of a check. */
+    fail(id: string, failure: Failure): void;
+    /** How many failures a check has so far. */
+    failures(id: string): number;
+    /** Marks a check as skipped, with the reason. */
+    skip(id: string, reason: string): void;
+    /** Adds a note to a check's result. */
+    note(id: string, note: string): void;
+    report(subject: string, games: number, steps: number): ConformanceReport;
+}

package/dist/report.js

@@ -0,0 +1,104 @@
+//#region src/report.ts
+/** The failed checks' ids. */
+var failedChecks = (report) => report.checks.filter((c) => c.status === "failed").map((c) => c.id);
+/** One check by id; throws if the suite has no such check. */
+var checkById = (report, id) => {
+	const check = report.checks.find((c) => c.id === id);
+	if (check === void 0) throw new Error(`No check "${id}" in the report for ${report.subject}.`);
+	return check;
+};
+/** A failure as text a person can act on: what broke, the seed, and the input sequence. */
+var formatFailure = (failure) => {
+	const lines = [failure.message];
+	const where = [];
+	if (failure.setup !== void 0) where.push(`setup ${failure.setup}`);
+	if (failure.game !== void 0) where.push(`game ${failure.game}`);
+	if (failure.seed !== void 0) where.push(`seed "${failure.seed}"`);
+	if (failure.step !== void 0) where.push(`after ${failure.step} input${failure.step === 1 ? "" : "s"}`);
+	if (where.length > 0) lines.push(`  at: ${where.join(", ")}`);
+	if (failure.setup !== void 0 && failure.game !== void 0) lines.push(`  rerun only this game: add \`only: { setup: ${failure.setup}, game: ${failure.game} }\` to the options`);
+	if (failure.input !== void 0) lines.push(`  input: ${JSON.stringify(failure.input)}`);
+	if (failure.replay !== void 0) lines.push(`  replay: ${JSON.stringify(failure.replay)}`);
+	return lines.join("\n");
+};
+/** A check as text: its title, status and failures. */
+var formatCheck = (check) => {
+	const head = `[${check.id}] ${check.title}: ${check.status}${check.note === void 0 ? "" : ` (${check.note})`}`;
+	if (check.status !== "failed") return head;
+	const more = check.failureCount - check.failures.length;
+	return [
+		`${head}, ${check.failureCount} failure${check.failureCount === 1 ? "" : "s"}`,
+		...check.failures.map((f, i) => `\n#${i + 1} ${formatFailure(f)}`),
+		...more > 0 ? [`\n… and ${more} more`] : []
+	].join("\n");
+};
+/** The whole report as text. */
+var formatReport = (report) => [`${report.subject}: ${report.ok ? "conforms" : "FAILS"} (${report.games} games, ${report.steps} inputs)`, ...report.checks.map(formatCheck)].join("\n");
+/** Collects failures per check while a suite runs. */
+var Recorder = class {
+	#limit;
+	#checks = /* @__PURE__ */ new Map();
+	constructor(definitions, limit) {
+		this.#limit = limit;
+		for (const { id, title } of definitions) this.#checks.set(id, {
+			title,
+			runs: 0,
+			failures: [],
+			count: 0
+		});
+	}
+	#get(id) {
+		const check = this.#checks.get(id);
+		if (check === void 0) throw new Error(`Unknown check "${id}".`);
+		return check;
+	}
+	/** Counts one run of a check. */
+	ran(id, times = 1) {
+		this.#get(id).runs += times;
+	}
+	/** Records a failure of a check. */
+	fail(id, failure) {
+		const check = this.#get(id);
+		check.count += 1;
+		if (check.failures.length < this.#limit) check.failures.push(failure);
+	}
+	/** How many failures a check has so far. */
+	failures(id) {
+		return this.#get(id).count;
+	}
+	/** Marks a check as skipped, with the reason. */
+	skip(id, reason) {
+		this.#get(id).skip = reason;
+	}
+	/** Adds a note to a check's result. */
+	note(id, note) {
+		this.#get(id).note = note;
+	}
+	report(subject, games, steps) {
+		const checks = [...this.#checks].map(([id, c]) => {
+			const skip = c.skip ?? (c.runs === 0 ? "nothing to check in the generated games" : void 0);
+			const status = c.count > 0 ? "failed" : skip !== void 0 ? "skipped" : "passed";
+			const note = status === "skipped" ? skip : c.note;
+			return {
+				id,
+				title: c.title,
+				status,
+				...note === void 0 ? {} : { note },
+				runs: c.runs,
+				failures: c.failures,
+				failureCount: c.count
+			};
+		});
+		return {
+			subject,
+			ok: checks.every((c) => c.status !== "failed"),
+			checks,
+			games,
+			steps
+		};
+	}
+};
+//#endregion
+export { Recorder, checkById, failedChecks, formatCheck, formatFailure, formatReport };
+
+//# sourceMappingURL=report.js.map

package/dist/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","names":[],"sources":["../src/report.ts"],"sourcesContent":["// Conformance reports: what was checked, what failed, and how to reproduce each failure.\n\nimport type { Replay } from '@joystyk/contracts';\n\n/** One reproducible failure. */\nexport type Failure = {\n  readonly message: string;\n  /** Which generated game failed: rerun just it with `only: { setup, game }`. */\n  readonly setup?: number;\n  readonly game?: number;\n  /** The game's seed string; the engine's generator is `testRng(seed, 'engine')`. */\n  readonly seed?: string;\n  /** The number of inputs applied before the failure (0: right after `init`). */\n  readonly step?: number;\n  /** The replay of the accepted inputs up to the failure; `replayEngine` reproduces it. */\n  readonly replay?: Replay;\n  /** The input being checked when the failure happened, if any. */\n  readonly input?: unknown;\n};\n\nexport type CheckStatus = 'passed' | 'failed' | 'skipped';\n\n/** The result of one check across every generated game. */\nexport type CheckResult = {\n  readonly id: string;\n  readonly title: string;\n  readonly status: CheckStatus;\n  /** Why the check was skipped, or a note on what it covered. */\n  readonly note?: string;\n  /** How many times the check ran (positions, transitions, games …). */\n  readonly runs: number;\n  /** The first few failures; `failureCount` has the total. */\n  readonly failures: readonly Failure[];\n  readonly failureCount: number;\n};\n\n/** Everything a suite found. */\nexport type ConformanceReport = {\n  readonly subject: string;\n  readonly ok: boolean;\n  readonly checks: readonly CheckResult[];\n  /** Games generated and inputs applied, for a sense of coverage. */\n  readonly games: number;\n  readonly steps: number;\n};\n\n/** The failed checks' ids. */\nexport const failedChecks = (report: ConformanceReport): string[] =>\n  report.checks.filter((c) => c.status === 'failed').map((c) => c.id);\n\n/** One check by id; throws if the suite has no such check. */\nexport const checkById = (report: ConformanceReport, id: string): CheckResult => {\n  const check = report.checks.find((c) => c.id === id);\n  if (check === undefined) throw new Error(`No check \"${id}\" in the report for ${report.subject}.`);\n  return check;\n};\n\n/** A failure as text a person can act on: what broke, the seed, and the input sequence. */\nexport const formatFailure = (failure: Failure): string => {\n  const lines = [failure.message];\n  const where: string[] = [];\n  if (failure.setup !== undefined) where.push(`setup ${failure.setup}`);\n  if (failure.game !== undefined) where.push(`game ${failure.game}`);\n  if (failure.seed !== undefined) where.push(`seed \"${failure.seed}\"`);\n  if (failure.step !== undefined) where.push(`after ${failure.step} input${failure.step === 1 ? '' : 's'}`);\n  if (where.length > 0) lines.push(`  at: ${where.join(', ')}`);\n  if (failure.setup !== undefined && failure.game !== undefined) {\n    lines.push(\n      `  rerun only this game: add \\`only: { setup: ${failure.setup}, game: ${failure.game} }\\` to the options`,\n    );\n  }\n  if (failure.input !== undefined) lines.push(`  input: ${JSON.stringify(failure.input)}`);\n  if (failure.replay !== undefined) lines.push(`  replay: ${JSON.stringify(failure.replay)}`);\n  return lines.join('\\n');\n};\n\n/** A check as text: its title, status and failures. */\nexport const formatCheck = (check: CheckResult): string => {\n  const head = `[${check.id}] ${check.title}: ${check.status}${check.note === undefined ? '' : ` (${check.note})`}`;\n  if (check.status !== 'failed') return head;\n  const more = check.failureCount - check.failures.length;\n  return [\n    `${head}, ${check.failureCount} failure${check.failureCount === 1 ? '' : 's'}`,\n    ...check.failures.map((f, i) => `\\n#${i + 1} ${formatFailure(f)}`),\n    ...(more > 0 ? [`\\n… and ${more} more`] : []),\n  ].join('\\n');\n};\n\n/** The whole report as text. */\nexport const formatReport = (report: ConformanceReport): string =>\n  [\n    `${report.subject}: ${report.ok ? 'conforms' : 'FAILS'} (${report.games} games, ${report.steps} inputs)`,\n    ...report.checks.map(formatCheck),\n  ].join('\\n');\n\n/** Collects failures per check while a suite runs. */\nexport class Recorder {\n  readonly #limit: number;\n  readonly #checks = new Map<\n    string,\n    { title: string; runs: number; failures: Failure[]; count: number; skip?: string; note?: string }\n  >();\n\n  constructor(definitions: readonly { readonly id: string; readonly title: string }[], limit: number) {\n    this.#limit = limit;\n    for (const { id, title } of definitions) this.#checks.set(id, { title, runs: 0, failures: [], count: 0 });\n  }\n\n  #get(id: string) {\n    const check = this.#checks.get(id);\n    if (check === undefined) throw new Error(`Unknown check \"${id}\".`);\n    return check;\n  }\n\n  /** Counts one run of a check. */\n  ran(id: string, times = 1): void {\n    this.#get(id).runs += times;\n  }\n\n  /** Records a failure of a check. */\n  fail(id: string, failure: Failure): void {\n    const check = this.#get(id);\n    check.count += 1;\n    if (check.failures.length < this.#limit) check.failures.push(failure);\n  }\n\n  /** How many failures a check has so far. */\n  failures(id: string): number {\n    return this.#get(id).count;\n  }\n\n  /** Marks a check as skipped, with the reason. */\n  skip(id: string, reason: string): void {\n    this.#get(id).skip = reason;\n  }\n\n  /** Adds a note to a check's result. */\n  note(id: string, note: string): void {\n    this.#get(id).note = note;\n  }\n\n  report(subject: string, games: number, steps: number): ConformanceReport {\n    const checks: CheckResult[] = [...this.#checks].map(([id, c]) => {\n      const skip = c.skip ?? (c.runs === 0 ? 'nothing to check in the generated games' : undefined);\n      const status: CheckStatus = c.count > 0 ? 'failed' : skip !== undefined ? 'skipped' : 'passed';\n      const note = status === 'skipped' ? skip : c.note;\n      return {\n        id,\n        title: c.title,\n        status,\n        ...(note === undefined ? {} : { note }),\n        runs: c.runs,\n        failures: c.failures,\n        failureCount: c.count,\n      };\n    });\n    return { subject, ok: checks.every((c) => c.status !== 'failed'), checks, games, steps };\n  }\n}\n"],"mappings":"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"}

package/dist/rng.d.ts

@@ -0,0 +1,18 @@
+import type { Rng, RngState } from '@joystyk/contracts';
+/**
+ * The seed state for a test. `testSeed('nim', 3)` hashes `"joystyk-test/nim/3"`. The same
+ * parts give the same state on every machine and in every run.
+ */
+export declare const testSeed: (...parts: readonly (string | number)[]) => RngState;
+/**
+ * A seeded generator for a test, from the kit's SFC32. Pass the same parts to get the same
+ * stream again, for example to reproduce a failure the suites report.
+ */
+export declare const testRng: (...parts: readonly (string | number)[]) => Rng;
+/** `count` distinct, reproducible seed states derived from `base`. */
+export declare const testSeeds: (base: string, count: number) => RngState[];
+/**
+ * An independent copy of `rng` at its current position. Drawing from the copy leaves `rng`
+ * untouched, which is how the suites try an input without consuming randomness.
+ */
+export declare const cloneRng: (rng: Rng) => Rng;

package/dist/rng.js

@@ -0,0 +1,25 @@
+import { restoreRng, seedState } from "@joystyk/kit";
+//#region src/rng.ts
+/** Every test seed is namespaced, so a test seed never equals a production deal or daily seed. */
+var PREFIX = "joystyk-test";
+/**
+* The seed state for a test. `testSeed('nim', 3)` hashes `"joystyk-test/nim/3"`. The same
+* parts give the same state on every machine and in every run.
+*/
+var testSeed = (...parts) => seedState([PREFIX, ...parts.map(String)].join("/"));
+/**
+* A seeded generator for a test, from the kit's SFC32. Pass the same parts to get the same
+* stream again, for example to reproduce a failure the suites report.
+*/
+var testRng = (...parts) => restoreRng(testSeed(...parts));
+/** `count` distinct, reproducible seed states derived from `base`. */
+var testSeeds = (base, count) => Array.from({ length: count }, (_, i) => testSeed(base, i));
+/**
+* An independent copy of `rng` at its current position. Drawing from the copy leaves `rng`
+* untouched, which is how the suites try an input without consuming randomness.
+*/
+var cloneRng = (rng) => restoreRng(rng.save());
+//#endregion
+export { cloneRng, testRng, testSeed, testSeeds };
+
+//# sourceMappingURL=rng.js.map

package/dist/rng.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rng.js","names":[],"sources":["../src/rng.ts"],"sourcesContent":["// Deterministic random sources for tests, built on the kit's seeded generator.\n\nimport type { Rng, RngState } from '@joystyk/contracts';\nimport { restoreRng, seedState } from '@joystyk/kit';\n\n/** Every test seed is namespaced, so a test seed never equals a production deal or daily seed. */\nconst PREFIX = 'joystyk-test';\n\n/**\n * The seed state for a test. `testSeed('nim', 3)` hashes `\"joystyk-test/nim/3\"`. The same\n * parts give the same state on every machine and in every run.\n */\nexport const testSeed = (...parts: readonly (string | number)[]): RngState =>\n  seedState([PREFIX, ...parts.map(String)].join('/'));\n\n/**\n * A seeded generator for a test, from the kit's SFC32. Pass the same parts to get the same\n * stream again, for example to reproduce a failure the suites report.\n */\nexport const testRng = (...parts: readonly (string | number)[]): Rng => restoreRng(testSeed(...parts));\n\n/** `count` distinct, reproducible seed states derived from `base`. */\nexport const testSeeds = (base: string, count: number): RngState[] =>\n  Array.from({ length: count }, (_, i) => testSeed(base, i));\n\n/**\n * An independent copy of `rng` at its current position. Drawing from the copy leaves `rng`\n * untouched, which is how the suites try an input without consuming randomness.\n */\nexport const cloneRng = (rng: Rng): Rng => restoreRng(rng.save());\n"],"mappings":";;;AAMA,IAAM,SAAS;;;;;AAMf,IAAa,YAAY,GAAG,UAC1B,UAAU,CAAC,QAAQ,GAAG,MAAM,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC;;;;;AAMpD,IAAa,WAAW,GAAG,UAA6C,WAAW,SAAS,GAAG,KAAK,CAAC;;AAGrG,IAAa,aAAa,MAAc,UACtC,MAAM,KAAK,EAAE,QAAQ,MAAM,IAAI,GAAG,MAAM,SAAS,MAAM,CAAC,CAAC;;;;;AAM3D,IAAa,YAAY,QAAkB,WAAW,IAAI,KAAK,CAAC"}

package/dist/schema.d.ts

@@ -0,0 +1,13 @@
+import type { StandardSchemaV1, Validator } from '@joystyk/contracts';
+/** The outcome of validating one value. */
+export type Validation<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly issues: readonly StandardSchemaV1.Issue[];
+};
+/** Validates `value` with a Standard Schema, sync or async. */
+export declare const validate: <T>(schema: Validator<T>, value: unknown) => Promise<Validation<T>>;
+/** Issues as one line: "message at path; message". */
+export declare const formatIssues: (issues: readonly StandardSchemaV1.Issue[]) => string;

package/dist/schema.js

@@ -0,0 +1,21 @@
+//#region src/schema.ts
+/** Validates `value` with a Standard Schema, sync or async. */
+var validate = async (schema, value) => {
+	const result = await schema["~standard"].validate(value);
+	return result.issues === void 0 ? {
+		ok: true,
+		value: result.value
+	} : {
+		ok: false,
+		issues: result.issues
+	};
+};
+/** Issues as one line: "message at path; message". */
+var formatIssues = (issues) => issues.slice(0, 3).map((issue) => {
+	const path = (issue.path ?? []).map((p) => String(typeof p === "object" ? p.key : p)).join(".");
+	return path === "" ? issue.message : `${issue.message} at ${path}`;
+}).join("; ") + (issues.length > 3 ? ` (+${issues.length - 3} more)` : "");
+//#endregion
+export { formatIssues, validate };
+
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","names":[],"sources":["../src/schema.ts"],"sourcesContent":["// Running Standard Schemas from tests.\n\nimport type { StandardSchemaV1, Validator } from '@joystyk/contracts';\n\n/** The outcome of validating one value. */\nexport type Validation<T> =\n  { readonly ok: true; readonly value: T } | { readonly ok: false; readonly issues: readonly StandardSchemaV1.Issue[] };\n\n/** Validates `value` with a Standard Schema, sync or async. */\nexport const validate = async <T>(schema: Validator<T>, value: unknown): Promise<Validation<T>> => {\n  const result = await schema['~standard'].validate(value);\n  return result.issues === undefined ? { ok: true, value: result.value } : { ok: false, issues: result.issues };\n};\n\n/** Issues as one line: \"message at path; message\". */\nexport const formatIssues = (issues: readonly StandardSchemaV1.Issue[]): string =>\n  issues\n    .slice(0, 3)\n    .map((issue) => {\n      const path = (issue.path ?? []).map((p) => String(typeof p === 'object' ? p.key : p)).join('.');\n      return path === '' ? issue.message : `${issue.message} at ${path}`;\n    })\n    .join('; ') + (issues.length > 3 ? ` (+${issues.length - 3} more)` : '');\n"],"mappings":";;AASA,IAAa,WAAW,OAAU,QAAsB,UAA2C;CACjG,MAAM,SAAS,MAAM,OAAO,YAAY,CAAC,SAAS,KAAK;CACvD,OAAO,OAAO,WAAW,KAAA,IAAY;EAAE,IAAI;EAAM,OAAO,OAAO;CAAM,IAAI;EAAE,IAAI;EAAO,QAAQ,OAAO;CAAO;AAC9G;;AAGA,IAAa,gBAAgB,WAC3B,OACG,MAAM,GAAG,CAAC,CAAC,CACX,KAAK,UAAU;CACd,MAAM,QAAQ,MAAM,QAAQ,CAAC,EAAA,CAAG,KAAK,MAAM,OAAO,OAAO,MAAM,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG;CAC9F,OAAO,SAAS,KAAK,MAAM,UAAU,GAAG,MAAM,QAAQ,MAAM;AAC9D,CAAC,CAAC,CACD,KAAK,IAAI,KAAK,OAAO,SAAS,IAAI,MAAM,OAAO,SAAS,EAAE,UAAU"}

package/dist/session-ports.d.ts

@@ -0,0 +1,16 @@
+import type { SaveEnvelope } from '@joystyk/contracts';
+import type { Clock, SaveStore } from '@joystyk/session';
+import type { FakeClock } from './clock.js';
+/** The runner's `Clock` port, driven by a fake clock: time moves only on `advance`. */
+export declare const runnerClock: (fake: FakeClock) => Clock;
+/** A runner `SaveStore` in memory, with what a test needs to inspect it. */
+export interface MemorySaveStore extends SaveStore {
+    /** What the slot holds: a JSON copy of the last write since the last `clear`, or null. */
+    slot(): SaveEnvelope | null;
+    /** How many writes landed. */
+    writes(): number;
+    /** How many times the runner cleared the slot. */
+    clears(): number;
+}
+/** An in-memory save slot, which the runner writes and clears as the launcher's does. */
+export declare const createMemorySaveStore: () => MemorySaveStore;

package/dist/session-ports.js

@@ -0,0 +1,32 @@
+//#region src/session-ports.ts
+/** The runner's `Clock` port, driven by a fake clock: time moves only on `advance`. */
+var runnerClock = (fake) => ({
+	now: () => fake.now(),
+	after: (ms, callback) => {
+		const timer = fake.setTimeout(callback, ms);
+		return () => timer.cancel();
+	}
+});
+/** An in-memory save slot, which the runner writes and clears as the launcher's does. */
+var createMemorySaveStore = () => {
+	let slot = null;
+	let writes = 0;
+	let clears = 0;
+	return {
+		write: async (save) => {
+			slot = JSON.parse(JSON.stringify(save));
+			writes += 1;
+		},
+		clear: async () => {
+			slot = null;
+			clears += 1;
+		},
+		slot: () => slot,
+		writes: () => writes,
+		clears: () => clears
+	};
+};
+//#endregion
+export { createMemorySaveStore, runnerClock };
+
+//# sourceMappingURL=session-ports.js.map

package/dist/session-ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-ports.js","names":[],"sources":["../src/session-ports.ts"],"sourcesContent":["// Fakes for the session runner's ports, so a game's tests can play it through\n// `createLocalSession` with time and saves under the test's control.\n\nimport type { SaveEnvelope } from '@joystyk/contracts';\nimport type { Clock, SaveStore } from '@joystyk/session';\nimport type { FakeClock } from './clock.ts';\n\n/** The runner's `Clock` port, driven by a fake clock: time moves only on `advance`. */\nexport const runnerClock = (fake: FakeClock): Clock => ({\n  now: () => fake.now(),\n  after: (ms, callback) => {\n    const timer = fake.setTimeout(callback, ms);\n    return () => timer.cancel();\n  },\n});\n\n/** A runner `SaveStore` in memory, with what a test needs to inspect it. */\nexport interface MemorySaveStore extends SaveStore {\n  /** What the slot holds: a JSON copy of the last write since the last `clear`, or null. */\n  slot(): SaveEnvelope | null;\n  /** How many writes landed. */\n  writes(): number;\n  /** How many times the runner cleared the slot. */\n  clears(): number;\n}\n\n/** An in-memory save slot, which the runner writes and clears as the launcher's does. */\nexport const createMemorySaveStore = (): MemorySaveStore => {\n  let slot: SaveEnvelope | null = null;\n  let writes = 0;\n  let clears = 0;\n  return {\n    write: async (save) => {\n      slot = JSON.parse(JSON.stringify(save)) as SaveEnvelope;\n      writes += 1;\n    },\n    clear: async () => {\n      slot = null;\n      clears += 1;\n    },\n    slot: () => slot,\n    writes: () => writes,\n    clears: () => clears,\n  };\n};\n"],"mappings":";;AAQA,IAAa,eAAe,UAA4B;CACtD,WAAW,KAAK,IAAI;CACpB,QAAQ,IAAI,aAAa;EACvB,MAAM,QAAQ,KAAK,WAAW,UAAU,EAAE;EAC1C,aAAa,MAAM,OAAO;CAC5B;AACF;;AAaA,IAAa,8BAA+C;CAC1D,IAAI,OAA4B;CAChC,IAAI,SAAS;CACb,IAAI,SAAS;CACb,OAAO;EACL,OAAO,OAAO,SAAS;GACrB,OAAO,KAAK,MAAM,KAAK,UAAU,IAAI,CAAC;GACtC,UAAU;EACZ;EACA,OAAO,YAAY;GACjB,OAAO;GACP,UAAU;EACZ;EACA,YAAY;EACZ,cAAc;EACd,cAAc;CAChB;AACF"}

package/dist/simulation-conformance.d.ts

@@ -0,0 +1,71 @@
+import { type FixedStepSimulation, type Json, type Rng } from '@joystyk/contracts';
+import type { InvariantResult } from './engine-conformance.js';
+import { type ConformanceReport } from './report.js';
+/** Options for `checkSimulation` and `runSimulationConformance`. */
+export type SimulationConformanceOptions<State, Input, Config> = {
+    /** A name for reports and the vitest `describe` block. */
+    readonly name?: string;
+    /** The game id written into replays. Default "test-game". */
+    readonly gameId?: string;
+    /** The configs to start from; each runs `runs` times with different seeds. */
+    readonly configs: readonly Config[];
+    /** Runs per config. Default 4. */
+    readonly runs?: number;
+    /** Ticks per run (a run also stops at its outcome). Default 1000. */
+    readonly ticks?: number;
+    /** The base seed. Run `r` of config `c` uses the seed string `${seed}/${c}/${r}`. Default "conformance". */
+    readonly seed?: string;
+    /** Scripted inputs for a tick. Draw any randomness from `rng`. Default: no inputs. */
+    readonly inputs?: (state: State, tick: number, rng: Rng) => readonly Input[];
+    /** Called on every state the simulation reaches. */
+    readonly invariants?: (state: State) => InvariantResult;
+    /** Fail a run that has no outcome after `ticks` ticks. Default false. */
+    readonly requireOutcome?: boolean;
+    /** The tick of the checkpoint in the checkpoint-equivalence check. Default half the run. */
+    readonly checkpointAt?: number;
+    /** Fail when the mean step takes longer than this many milliseconds. Off by default. */
+    readonly stepBudgetMs?: number;
+    /** Run only one run, to reproduce a reported failure (`setup` is the config index). */
+    readonly only?: {
+        readonly setup: number;
+        readonly game: number;
+    };
+    /** Failures kept per check in the report. Default 3. */
+    readonly maxFailuresPerCheck?: number;
+};
+/** The checks this suite runs, in report order. */
+export declare const SIMULATION_CHECKS: readonly [{
+    readonly id: "determinism";
+    readonly title: "Determinism: the same seed and tick inputs give the same states and events";
+}, {
+    readonly id: "replay";
+    readonly title: "Replay: the recorded tick log reproduces the final state";
+}, {
+    readonly id: "checkpoint";
+    readonly title: "Checkpoints: saving, restoring and continuing equals running straight through";
+}, {
+    readonly id: "json";
+    readonly title: "JSON safety of configs, states, inputs, events and outcomes";
+}, {
+    readonly id: "schemas";
+    readonly title: "Schema agreement: every value passes the simulation's own schemas";
+}, {
+    readonly id: "purity";
+    readonly title: "Step purity: the same state, inputs and generator give the same next state, without mutation";
+}, {
+    readonly id: "invariants";
+    readonly title: "Invariants hold on every state the simulation reaches";
+}, {
+    readonly id: "outcome";
+    readonly title: "Outcomes are valid and detected in time";
+}, {
+    readonly id: "budget";
+    readonly title: "Step-time budget";
+}];
+/** The id of one simulation check. */
+export type SimulationCheckId = (typeof SIMULATION_CHECKS)[number]['id'];
+/**
+ * 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.
+ */
+export declare const checkSimulation: <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>) => Promise<ConformanceReport>;