@joystyk/testing 0.0.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# @joystyk/testing
+
+## 0.2.0
+
+### Minor Changes
+
+- bb095c7: Share canonical IPv4 and IPv6 /64 rate-limit keys across Node services. Keep room
+  initialization diagnostics on the server behind a client-safe reference, and expire old
+  message-rate strikes. Extend hidden-information conformance checks with transition-aware
+  perturbations so private events remain testable when recipients gain cards.
+
+### Patch Changes
+
+- Updated dependencies [bb095c7]
+- Updated dependencies [bb095c7]
+  - @joystyk/contracts@0.2.0
+  - @joystyk/session@0.2.0
+  - @joystyk/kit@0.2.0
+
+## 0.1.0
+
+### Minor Changes
+
+- Prepare the first compiled library release: ESM and API declarations for every public entry point, runtime assets, and checks against installed npm tarballs. Games and applications remain private.
+
+### Patch Changes
+
+- Updated dependencies
+  - @joystyk/contracts@0.1.0
+  - @joystyk/kit@0.1.0
+  - @joystyk/session@0.1.0

package/README.md

@@ -1,5 +1,192 @@
 # @joystyk/testing
 
-The first Joystyk library release is not yet available. This placeholder reserves the package name.
+Dev-time helpers that games and platform packages use from their own test files. The heart
+of the package is the pair of **conformance suites** that check the
+game contract (Joystyk host reference): a game opts in
+with one short test file, and the suite plays hundreds of seeded random games against its
+engine or simulation. Around them sit the fakes and builders that make other tests quick to
+write: a test RNG, a fake clock, a fake storage port, replay and undo helpers, and fixture
+builders.
 
-Source: https://github.com/joystyk-games/game-libraries
+## npm package
+
+The first `0.1.0` release is being prepared; it has not been published. Once available:
+
+```sh
+npm install @joystyk/testing
+```
+
+Node consumers require Node 24.15 or later. Browser entry points require a modern
+browser and should be loaded in the browser. The root entry integrates with Vitest
+4.1.11; use it inside a Vitest test. Fixtures can also be imported separately.
+
+| Import | Format |
+| --- | --- |
+| `@joystyk/testing` | ES module and TypeScript declarations |
+| `@joystyk/testing/fixtures` | ES module and TypeScript declarations |
+
+Only the entries listed above are public API. Installed packages contain compiled ESM,
+type declarations and runtime assets. Repository-relative links describe the Joystyk
+workspace and are not needed to use the npm package.
+
+It depends on `@joystyk/contracts`, `@joystyk/kit` and `@joystyk/session` (whose runner
+replay it cross-checks against), and on `vitest` as a peer. Never import it from production
+code.
+
+## Conformance for a discrete engine
+
+```ts
+// games/nim/engine/conformance.test.ts
+import { runEngineConformance } from '@joystyk/testing';
+import { engine, migrations, perturbHidden } from './index.ts';
+
+runEngineConformance(engine, {
+  name: 'nim',
+  configs: [{ heap: 5 }, { heap: 21 }],
+  seatCounts: [2],
+  // Candidate commands for a seat: all legal moves, or a sample. Illegal ones are fine;
+  // the engine's answer decides. Without this the suite asks engine.ai for moves.
+  commands: (state, seat) => [1, 2, 3].map((count) => ({ type: 'take', count })),
+  perturbHidden,                        // games with hidden information; see below
+  invariants: (state) => state.heap >= 0 || 'the heap is negative',
+  saves: { version: 2, migrations, fixtures: [/* one stored state per shipped save version */] },
+});
+```
+
+`runEngineConformance` registers a `describe` block with one `it` per check, so a failure
+names the rule it broke. The games are played once, in the first case to run, and every
+case reads the shared report. A check that doesn't apply (no AI, no hidden information) is
+reported as skipped, with the reason.
+
+Each failure prints what broke, the game's seed, the number of inputs before it, the input
+being checked, and the replay of every accepted input so far:
+
+```text
+[no-leak] … : failed, 14 failures
+#1 viewFor(state, 0) changed when only hidden information changed: $.others[1][0].id: "q6y31" vs "brh76"
+  at: setup 0, game 3, seed "conformance/0/3", after 4 inputs
+  rerun only this game: add `only: { setup: 0, game: 3 }` to the options
+  replay: {"layer":2,"gameId":"test-game",…,"inputs":[…]}
+```
+
+Add the `only` option to replay just that game, or pass the printed replay to
+`replayEngine(engine, replay)` to reach the failing state in a debugger.
+
+### What it checks
+
+| Check | What fails it |
+| --- | --- |
+| `determinism` | The same seed and inputs give different states, beats, jobs, barriers, assistance, outcomes or random state; or `apply` answers the same arguments twice in two ways |
+| `replay` | The recorded log, after a JSON round trip, doesn't reproduce the final state, outcome and barriers, through this package's replay and through the session runner's |
+| `json` | A config, state, view, redacted event, command, job request, decision key or outcome isn't JSON (the message names the path, e.g. `-0 at $.lean`) |
+| `schemas` | A value fails the engine's own schema; or a command, state, config or job schema validates asynchronously, which runners can't wait for |
+| `no-leak` | `viewFor` or `decisionKey` changes when `perturbHidden` changes only what that viewer can't see, for every seat and the spectator; `eventFor` tells a viewer different things about two transitions that look identical to that viewer; or `perturbHidden` never changes anything |
+| `rejections` | `apply` throws, mutates its (frozen) input, or rejects without a JSON `GameError` |
+| `turns` | A command from a seat outside `pending()` (including seats that don't exist) is accepted; `pending()` lists unknown or repeated seats, or isn't empty after the outcome; a `timeout` or `seat` input (when `platformInputs` sends them) is refused while the game is in progress |
+| `resign` | A `resign` from any seat, in turn or out of turn, is refused while the game is in progress |
+| `invariants` | The `invariants` hook returns `false` or a message, or throws, on any state a game reaches |
+| `ai` | `ai.choose`, at any level and for any pending seat, throws or picks a command the engine rejects |
+| `saves` | A state saved at a random point doesn't survive JSON and `schemas.state` unchanged, or a game restored from it ends differently; a save fixture is missing for a shipped version, or doesn't migrate and validate |
+| `jobs` | A job outcome for an id never requested, already answered or superseded is accepted; an awaited job accepts a value but not a failure, or the reverse; a job id repeats; a job kind is undeclared or has no fake runner; a payload or the fake runner's value fails its schema |
+| `stale` | While a seat's `decisionKey` stays the same, the set of commands the engine accepts from it changes, so the room would let a stale command through |
+| `undo` | Undo by replay doesn't return to the state before the human's previous decision, steps back past an `undoBarrier`, or refuses although no barrier is in the way; or a barrier differs from the spec's `undoBarrier` rule |
+| `assist` | A transition's `assist` isn't `'hint'`, `'check'` or `'reveal'`, differs from the spec's `assist` rule, or isn't reproduced by replay |
+| `session-hooks` | A transition sets `startsClock` without the engine declaring `clockStart: 'transition'`, or sets it twice in one game; or `worthSaving` throws, mutates its state, answers something other than a boolean, or answers differently for the same state or its JSON copy. Skipped when the engine declares neither hook |
+| `outcome` | A game has no outcome after `maxSteps` inputs; nobody can move although the game isn't over; the outcome is malformed (every seat placed once, places from 1, no platform-written fields); a finished game accepts a command or a resignation |
+
+The suite deep-freezes every state and input it hands the engine, and restores the random
+state after every trial, as the session runner does. It tries each candidate input on a
+copy of the generator before committing one, so trials never change the game.
+
+### Options
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `setups` or `configs` × `seatCounts` | required | How games start: `{ config, seats }`, seats as a count or `SeatInfo`s |
+| `commands` | `engine.ai` | Candidate commands for a seat in a state |
+| `perturbHidden` | none (no-leak skipped) | `(state, viewer, rng) => state` changing only what `viewer` can't see |
+| `perturbTransition` | none | Optional `(state, viewer, rng, transition) => state` retry helper: preserve current knowledge, what the viewer learns in `transition.states`, and cards required by `transition.input`; vary everything still hidden |
+| `invariants` | none | `(state) => void \| boolean \| string` |
+| `games`, `maxSteps`, `seed` | 12, 400, `"conformance"` | Games per setup, inputs per game, base seed |
+| `requireOutcome` | true | Fail games that don't finish in `maxSteps` |
+| `platformInputs` | `{ resign: true }` | Also send `timeout` and `seat` inputs with `{ timeout: true, seatChanges: true }` |
+| `jobs`, `jobFailureRate` | none, 0.1 | Fake job runners by kind, `(payload, rng) => value`, and how often a job fails instead |
+| `undoBarrier`, `assist` | none | The spec's rules: which inputs are barriers, and which assistance each input is |
+| `saves` | round trip only | `{ version, firstVersion?, migrations, fixtures }` |
+| `only` | all games | `{ setup, game }`, to rerun one reported game |
+| `timeoutMs` | 300 000 | Per vitest case (`runEngineConformance` and `runSimulationConformance`) |
+
+`checkEngine(engine, options)` runs the same suite without vitest and returns a
+`ConformanceReport`; `formatReport` turns it into text and `expectConformance` throws unless
+it passed. Use it to assert on the report itself, as this package's own tests do.
+
+## Conformance for a fixed-step simulation
+
+```ts
+import { runSimulationConformance } from '@joystyk/testing';
+
+runSimulationConformance(simulation, {
+  configs: [{ length: 40, limit: 600 }],
+  ticks: 1000,
+  inputs: (state, tick, rng) => (rng.int(0, 5) === 0 ? [{ type: 'nudge', dir: 1 }] : []),
+  requireOutcome: true,
+  invariants: (state) => state.pos >= 0,
+});
+```
+
+| Check | What fails it |
+| --- | --- |
+| `determinism` | A second run with the same seed and tick inputs gives different results or random state |
+| `replay` | The tick log, after a JSON round trip, doesn't reproduce the final state and outcome, here or through the session scheduler's replay |
+| `checkpoint` | Saving at a tick, restoring through JSON and `schemas.state`, and running on gives a different end than running straight through |
+| `json`, `schemas` | A config, state, input, event or outcome isn't JSON or fails its schema |
+| `purity` | `step` throws, mutates its frozen input, or answers the same state, inputs and generator in two ways |
+| `invariants` | The hook fails on a state |
+| `outcome` | A malformed outcome, or none within `ticks` when `requireOutcome` is set |
+| `budget` | The mean step exceeds `stepBudgetMs` (off unless set; budgets belong on a reference machine) |
+
+## Helpers
+
+| Helper | Use |
+| --- | --- |
+| `testRng(...parts)`, `testSeed(...parts)`, `testSeeds(base, n)`, `cloneRng(rng)` | Seeded kit generators for tests, namespaced so they never equal a production seed |
+| `createFakeClock(start)` | `now`, `setTimer`, `setTimeout`, `advance`, `advanceTo`, `runAll`; the shape of the room server's `Clock` port |
+| `manualFrames()` | A fixed-step runner's `frames` port that runs only when the test says: `run(n)`, `advance(n)` and `until(condition, what)`, which counts game time in frames (testing under load (Joystyk host reference)) |
+| `waitUntil(condition, what)`, `pause(ms)`, `nextTask()`, `WAIT_BUDGET_MS` | Waits on a condition with a budget only a real failure exhausts, instead of a sleep |
+| `createFakeStorage(initial)` | The contract's `GameStorage` in memory, storing JSON text, with `entries`, `calls` and `failNext(op)` |
+| `runnerClock(fake)`, `createMemorySaveStore()` | The session runner's `Clock` on a fake clock, and a save slot in memory with `slot`, `writes` and `clears`, to play a game through `createLocalSession` |
+| `replayEngine`, `replaySimulation` | Replay a log and report each input's barrier, assistance and whether a human sent it |
+| `undoByReplay(engine, replay)` | Undo as the local runner does it: back to the start of the human's previous decision, refusing to cross a barrier, with the assistance record (`'undo'` included) |
+| `seats`, `commandInput`, `resignInput`, `timeoutInput`, `seatInput`, `jobResult`, `jobFailure` | Fixture builders for seats and inputs |
+| `engineReplay`, `simulationReplay`, `saveEnvelope`, `saveFixture` | Replays, saves and save fixtures with test defaults |
+| `guardSchema(guard)`, `anySchema()`, `validate(schema, value)` | Standard Schemas from type guards, and running any schema |
+| `firstDifference`, `deepEqual`, `deepFreeze`, `jsonRoundTrip` | What the suites use to compare and protect values |
+
+## Fixtures
+
+`@joystyk/testing/fixtures` holds small, correct games, each with conformance options that
+pass, for platform tests (runners, rooms, the two-client harness) that need a real engine:
+
+| Fixture | Layer | Exercises |
+| --- | --- | --- |
+| `nim` | 2 | Public state, runner-driven AI, saves with a migration chain |
+| `drawPlay` | 2 | Hidden hands and deck, opaque card ids, redacted events, two to four seats |
+| `sealedBids` | 2 | Simultaneous moves, a custom `decisionKey`, hidden choices |
+| `diceRace` | 2 | Jobs: requests, awaited ids and failures; solo and two seats |
+| `hintPuzzle` | 2 | Solo hidden information, undo barriers, `assist: 'hint'`, and both session hooks (`clockStart`, `worthSaving`) |
+| `drift` | 3 | A fixed-step simulation with seeded wind and scripted inputs |
+
+## Tests
+
+- `fixtures.test.ts` runs both suites through the vitest wrappers on every fixture, then
+  asserts from the reports that each fixture exercised the checks it was built for.
+- `broken.test.ts` runs the suites on deliberately broken fixtures (`broken.test-util.ts`),
+  one flaw each, and asserts that the right check fires: leaking ids, spectator views,
+  events and decision keys; non-deterministic, mutating and throwing engines; `undefined`
+  and `-0` in state; asynchronous and disagreeing schemas; wrong-turn acceptance; refused
+  and late resignations; endless and stuck games; illegal AI moves; frozen decision keys;
+  lost cards; missing barriers and wrong assistance; a clock started twice or undeclared,
+  and an impure or mutating `worthSaving`; job ids accepted, refused or reused;
+  missing and broken save fixtures; and the simulation equivalents. It also proves that a
+  reported seed and replay reproduce the failure.
+- `helpers.test.ts` covers the RNG, clock, storage, builders, deep helpers and undo.

package/dist/builders.d.ts

@@ -0,0 +1,59 @@
+import type { EngineInput, EngineReplay, Json, Replay, RngState, SaveEnvelope, SeatChange, SeatId, SeatInfo, SimulationReplay, TickInput, Validator } from '@joystyk/contracts';
+/**
+ * `count` human seats with ids 0 … count − 1 and stable names. Pass `ai` to make some seats
+ * AI seats: `seats(4, { ai: [1, 2, 3], aiLevel: 'easy' })`.
+ */
+export declare const seats: (count: number, options?: {
+    readonly ai?: readonly SeatId[];
+    readonly aiLevel?: string;
+}) => SeatInfo[];
+/** A `command` input. */
+export declare const commandInput: <C>(seat: SeatId, command: C) => EngineInput<C>;
+/** A `resign` input. */
+export declare const resignInput: <C = never>(seat: SeatId) => EngineInput<C>;
+/** A `timeout` input. */
+export declare const timeoutInput: <C = never>(seat: SeatId) => EngineInput<C>;
+/** A `seat` input. */
+export declare const seatInput: <C = never>(seat: SeatId, change: SeatChange) => EngineInput<C>;
+/** A `job` input carrying a successful outcome (without presentation, as the runner feeds it). */
+export declare const jobResult: <C = never>(jobId: string, value: Json) => EngineInput<C>;
+/** A `job` input carrying a failed outcome. */
+export declare const jobFailure: <C = never>(jobId: string, reason?: "timeout" | "failed") => EngineInput<C>;
+/**
+ * A Standard Schema from a type guard. Enough for fixtures and tests; real games use a schema
+ * library (Zod 4 by default, D-22).
+ */
+export declare const guardSchema: <T>(guard: (value: unknown) => value is T, message?: string) => Validator<T>;
+/** A Standard Schema that accepts anything as `T`. Use it only where the test isn't about schemas. */
+export declare const anySchema: <T>() => Validator<T>;
+/** A save fixture: the stored state of one shipped save version. */
+export type SaveFixture = {
+    /** A label for reports, e.g. "v1 mid-game". */
+    readonly name: string;
+    readonly saveVersion: number;
+    readonly state: Json;
+};
+/** A save fixture, for the `saves` option of the engine suite. */
+export declare const saveFixture: (name: string, saveVersion: number, state: Json) => SaveFixture;
+/** A save envelope with test defaults for everything but the state and the random state. */
+export declare const saveEnvelope: (fields: Pick<SaveEnvelope, "state" | "rng"> & Partial<SaveEnvelope>) => SaveEnvelope;
+/** A Layer 2 replay with test defaults. */
+export declare const engineReplay: <C extends Json = Json, Cfg extends Json = Json>(fields: {
+    readonly config: Cfg;
+    readonly seats: readonly SeatInfo[];
+    readonly seed: RngState;
+    readonly inputs: readonly EngineInput<C>[];
+    readonly gameId?: string;
+    readonly rulesVersion?: number;
+}) => EngineReplay<C, Cfg>;
+/** A Layer 3 replay with test defaults. */
+export declare const simulationReplay: <I extends Json = Json, Cfg extends Json = Json>(fields: {
+    readonly config: Cfg;
+    readonly seed: RngState;
+    readonly inputs: readonly TickInput<I>[];
+    readonly endTick: number;
+    readonly gameId?: string;
+    readonly rulesVersion?: number;
+}) => SimulationReplay<I, Cfg>;
+/** Narrows a replay by layer. */
+export declare const isEngineReplay: (replay: Replay) => replay is EngineReplay;

package/dist/builders.js

@@ -0,0 +1,129 @@
+//#region src/builders.ts
+var NAMES = [
+	"Ana",
+	"Ben",
+	"Cleo",
+	"Dev",
+	"Eli",
+	"Fay",
+	"Gus",
+	"Hana"
+];
+/**
+* `count` human seats with ids 0 … count − 1 and stable names. Pass `ai` to make some seats
+* AI seats: `seats(4, { ai: [1, 2, 3], aiLevel: 'easy' })`.
+*/
+var seats = (count, options = {}) => Array.from({ length: count }, (_, id) => {
+	const name = NAMES[id] ?? `Seat ${id + 1}`;
+	if (!(options.ai ?? []).includes(id)) return {
+		id,
+		name,
+		controller: "human"
+	};
+	return options.aiLevel === void 0 ? {
+		id,
+		name: `${name} (AI)`,
+		controller: "ai"
+	} : {
+		id,
+		name: `${name} (AI)`,
+		controller: "ai",
+		aiLevel: options.aiLevel
+	};
+});
+/** A `command` input. */
+var commandInput = (seat, command) => ({
+	kind: "command",
+	seat,
+	command
+});
+/** A `resign` input. */
+var resignInput = (seat) => ({
+	kind: "resign",
+	seat
+});
+/** A `timeout` input. */
+var timeoutInput = (seat) => ({
+	kind: "timeout",
+	seat
+});
+/** A `seat` input. */
+var seatInput = (seat, change) => ({
+	kind: "seat",
+	seat,
+	change
+});
+/** A `job` input carrying a successful outcome (without presentation, as the runner feeds it). */
+var jobResult = (jobId, value) => ({
+	kind: "job",
+	jobId,
+	outcome: {
+		ok: true,
+		value
+	}
+});
+/** A `job` input carrying a failed outcome. */
+var jobFailure = (jobId, reason = "failed") => ({
+	kind: "job",
+	jobId,
+	outcome: {
+		ok: false,
+		reason
+	}
+});
+/**
+* A Standard Schema from a type guard. Enough for fixtures and tests; real games use a schema
+* library (Zod 4 by default, D-22).
+*/
+var guardSchema = (guard, message = "Invalid value.") => ({ "~standard": {
+	version: 1,
+	vendor: "joystyk-testing",
+	validate: (value) => guard(value) ? { value } : { issues: [{ message }] }
+} });
+/** A Standard Schema that accepts anything as `T`. Use it only where the test isn't about schemas. */
+var anySchema = () => ({ "~standard": {
+	version: 1,
+	vendor: "joystyk-testing",
+	validate: (value) => ({ value })
+} });
+/** A save fixture, for the `saves` option of the engine suite. */
+var saveFixture = (name, saveVersion, state) => ({
+	name,
+	saveVersion,
+	state
+});
+/** A save envelope with test defaults for everything but the state and the random state. */
+var saveEnvelope = (fields) => ({
+	gameId: "test-game",
+	build: "0.0.0-test",
+	rulesVersion: 1,
+	saveVersion: 1,
+	seats: seats(2),
+	...fields
+});
+/** A Layer 2 replay with test defaults. */
+var engineReplay = (fields) => ({
+	layer: 2,
+	gameId: fields.gameId ?? "test-game",
+	rulesVersion: fields.rulesVersion ?? 1,
+	config: fields.config,
+	seats: fields.seats,
+	seed: fields.seed,
+	inputs: fields.inputs
+});
+/** A Layer 3 replay with test defaults. */
+var simulationReplay = (fields) => ({
+	layer: 3,
+	gameId: fields.gameId ?? "test-game",
+	rulesVersion: fields.rulesVersion ?? 1,
+	config: fields.config,
+	seed: fields.seed,
+	inputs: fields.inputs,
+	endTick: fields.endTick
+});
+/** Narrows a replay by layer. */
+var isEngineReplay = (replay) => replay.layer === 2;
+//#endregion
+export { anySchema, commandInput, engineReplay, guardSchema, isEngineReplay, jobFailure, jobResult, resignInput, saveEnvelope, saveFixture, seatInput, seats, simulationReplay, timeoutInput };
+
+//# sourceMappingURL=builders.js.map

package/dist/builders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.js","names":[],"sources":["../src/builders.ts"],"sourcesContent":["// Fixture builders: seats, inputs, schemas, saves and replays, without boilerplate.\n\nimport type {\n  EngineInput,\n  EngineReplay,\n  Json,\n  JobOutcome,\n  Replay,\n  RngState,\n  SaveEnvelope,\n  SeatChange,\n  SeatId,\n  SeatInfo,\n  SimulationReplay,\n  StandardSchemaV1,\n  TickInput,\n  Validator,\n} from '@joystyk/contracts';\n\nconst NAMES = ['Ana', 'Ben', 'Cleo', 'Dev', 'Eli', 'Fay', 'Gus', 'Hana'];\n\n/**\n * `count` human seats with ids 0 … count − 1 and stable names. Pass `ai` to make some seats\n * AI seats: `seats(4, { ai: [1, 2, 3], aiLevel: 'easy' })`.\n */\nexport const seats = (\n  count: number,\n  options: { readonly ai?: readonly SeatId[]; readonly aiLevel?: string } = {},\n): SeatInfo[] =>\n  Array.from({ length: count }, (_, id): SeatInfo => {\n    const name = NAMES[id] ?? `Seat ${id + 1}`;\n    if (!(options.ai ?? []).includes(id)) return { id, name, controller: 'human' };\n    return options.aiLevel === undefined\n      ? { id, name: `${name} (AI)`, controller: 'ai' }\n      : { id, name: `${name} (AI)`, controller: 'ai', aiLevel: options.aiLevel };\n  });\n\n/** A `command` input. */\nexport const commandInput = <C>(seat: SeatId, command: C): EngineInput<C> => ({ kind: 'command', seat, command });\n\n/** A `resign` input. */\nexport const resignInput = <C = never>(seat: SeatId): EngineInput<C> => ({ kind: 'resign', seat });\n\n/** A `timeout` input. */\nexport const timeoutInput = <C = never>(seat: SeatId): EngineInput<C> => ({ kind: 'timeout', seat });\n\n/** A `seat` input. */\nexport const seatInput = <C = never>(seat: SeatId, change: SeatChange): EngineInput<C> => ({\n  kind: 'seat',\n  seat,\n  change,\n});\n\n/** A `job` input carrying a successful outcome (without presentation, as the runner feeds it). */\nexport const jobResult = <C = never>(jobId: string, value: Json): EngineInput<C> => ({\n  kind: 'job',\n  jobId,\n  outcome: { ok: true, value },\n});\n\n/** A `job` input carrying a failed outcome. */\nexport const jobFailure = <C = never>(jobId: string, reason: 'timeout' | 'failed' = 'failed'): EngineInput<C> => ({\n  kind: 'job',\n  jobId,\n  outcome: { ok: false, reason } satisfies JobOutcome,\n});\n\n/**\n * A Standard Schema from a type guard. Enough for fixtures and tests; real games use a schema\n * library (Zod 4 by default, D-22).\n */\nexport const guardSchema = <T>(guard: (value: unknown) => value is T, message = 'Invalid value.'): Validator<T> => ({\n  '~standard': {\n    version: 1,\n    vendor: 'joystyk-testing',\n    validate: (value): StandardSchemaV1.Result<T> => (guard(value) ? { value } : { issues: [{ message }] }),\n  },\n});\n\n/** A Standard Schema that accepts anything as `T`. Use it only where the test isn't about schemas. */\nexport const anySchema = <T>(): Validator<T> => ({\n  '~standard': { version: 1, vendor: 'joystyk-testing', validate: (value) => ({ value: value as T }) },\n});\n\n/** A save fixture: the stored state of one shipped save version. */\nexport type SaveFixture = {\n  /** A label for reports, e.g. \"v1 mid-game\". */\n  readonly name: string;\n  readonly saveVersion: number;\n  readonly state: Json;\n};\n\n/** A save fixture, for the `saves` option of the engine suite. */\nexport const saveFixture = (name: string, saveVersion: number, state: Json): SaveFixture => ({\n  name,\n  saveVersion,\n  state,\n});\n\n/** A save envelope with test defaults for everything but the state and the random state. */\nexport const saveEnvelope = (fields: Pick<SaveEnvelope, 'state' | 'rng'> & Partial<SaveEnvelope>): SaveEnvelope => ({\n  gameId: 'test-game',\n  build: '0.0.0-test',\n  rulesVersion: 1,\n  saveVersion: 1,\n  seats: seats(2),\n  ...fields,\n});\n\n/** A Layer 2 replay with test defaults. */\nexport const engineReplay = <C extends Json = Json, Cfg extends Json = Json>(fields: {\n  readonly config: Cfg;\n  readonly seats: readonly SeatInfo[];\n  readonly seed: RngState;\n  readonly inputs: readonly EngineInput<C>[];\n  readonly gameId?: string;\n  readonly rulesVersion?: number;\n}): EngineReplay<C, Cfg> => ({\n  layer: 2,\n  gameId: fields.gameId ?? 'test-game',\n  rulesVersion: fields.rulesVersion ?? 1,\n  config: fields.config,\n  seats: fields.seats,\n  seed: fields.seed,\n  inputs: fields.inputs,\n});\n\n/** A Layer 3 replay with test defaults. */\nexport const simulationReplay = <I extends Json = Json, Cfg extends Json = Json>(fields: {\n  readonly config: Cfg;\n  readonly seed: RngState;\n  readonly inputs: readonly TickInput<I>[];\n  readonly endTick: number;\n  readonly gameId?: string;\n  readonly rulesVersion?: number;\n}): SimulationReplay<I, Cfg> => ({\n  layer: 3,\n  gameId: fields.gameId ?? 'test-game',\n  rulesVersion: fields.rulesVersion ?? 1,\n  config: fields.config,\n  seed: fields.seed,\n  inputs: fields.inputs,\n  endTick: fields.endTick,\n});\n\n/** Narrows a replay by layer. */\nexport const isEngineReplay = (replay: Replay): replay is EngineReplay => replay.layer === 2;\n"],"mappings":";AAmBA,IAAM,QAAQ;CAAC;CAAO;CAAO;CAAQ;CAAO;CAAO;CAAO;CAAO;AAAM;;;;;AAMvE,IAAa,SACX,OACA,UAA0E,CAAC,MAE3E,MAAM,KAAK,EAAE,QAAQ,MAAM,IAAI,GAAG,OAAiB;CACjD,MAAM,OAAO,MAAM,OAAO,QAAQ,KAAK;CACvC,IAAI,EAAE,QAAQ,MAAM,CAAC,EAAA,CAAG,SAAS,EAAE,GAAG,OAAO;EAAE;EAAI;EAAM,YAAY;CAAQ;CAC7E,OAAO,QAAQ,YAAY,KAAA,IACvB;EAAE;EAAI,MAAM,GAAG,KAAK;EAAQ,YAAY;CAAK,IAC7C;EAAE;EAAI,MAAM,GAAG,KAAK;EAAQ,YAAY;EAAM,SAAS,QAAQ;CAAQ;AAC7E,CAAC;;AAGH,IAAa,gBAAmB,MAAc,aAAgC;CAAE,MAAM;CAAW;CAAM;AAAQ;;AAG/G,IAAa,eAA0B,UAAkC;CAAE,MAAM;CAAU;AAAK;;AAGhG,IAAa,gBAA2B,UAAkC;CAAE,MAAM;CAAW;AAAK;;AAGlG,IAAa,aAAwB,MAAc,YAAwC;CACzF,MAAM;CACN;CACA;AACF;;AAGA,IAAa,aAAwB,OAAe,WAAiC;CACnF,MAAM;CACN;CACA,SAAS;EAAE,IAAI;EAAM;CAAM;AAC7B;;AAGA,IAAa,cAAyB,OAAe,SAA+B,cAA8B;CAChH,MAAM;CACN;CACA,SAAS;EAAE,IAAI;EAAO;CAAO;AAC/B;;;;;AAMA,IAAa,eAAkB,OAAuC,UAAU,sBAAoC,EAClH,aAAa;CACX,SAAS;CACT,QAAQ;CACR,WAAW,UAAuC,MAAM,KAAK,IAAI,EAAE,MAAM,IAAI,EAAE,QAAQ,CAAC,EAAE,QAAQ,CAAC,EAAE;AACvG,EACF;;AAGA,IAAa,mBAAoC,EAC/C,aAAa;CAAE,SAAS;CAAG,QAAQ;CAAmB,WAAW,WAAW,EAAS,MAAW;AAAG,EACrG;;AAWA,IAAa,eAAe,MAAc,aAAqB,WAA8B;CAC3F;CACA;CACA;AACF;;AAGA,IAAa,gBAAgB,YAAuF;CAClH,QAAQ;CACR,OAAO;CACP,cAAc;CACd,aAAa;CACb,OAAO,MAAM,CAAC;CACd,GAAG;AACL;;AAGA,IAAa,gBAAgE,YAOhD;CAC3B,OAAO;CACP,QAAQ,OAAO,UAAU;CACzB,cAAc,OAAO,gBAAgB;CACrC,QAAQ,OAAO;CACf,OAAO,OAAO;CACd,MAAM,OAAO;CACb,QAAQ,OAAO;AACjB;;AAGA,IAAa,oBAAoE,YAOhD;CAC/B,OAAO;CACP,QAAQ,OAAO,UAAU;CACzB,cAAc,OAAO,gBAAgB;CACrC,QAAQ,OAAO;CACf,MAAM,OAAO;CACb,QAAQ,OAAO;CACf,SAAS,OAAO;AAClB;;AAGA,IAAa,kBAAkB,WAA2C,OAAO,UAAU"}

package/dist/clock.d.ts

@@ -0,0 +1,30 @@
+/** A scheduled callback; cancelling it twice, or after it fired, is harmless. */
+export type TimerHandle = {
+    cancel(): void;
+};
+/**
+ * A manual clock with timers. It has the shape of the room server's `Clock` port
+ * (`now` and `setTimer`, room-server.md section 4.1) plus controls for tests.
+ */
+export interface FakeClock {
+    /** Current time in milliseconds. */
+    now(): number;
+    /** Calls `fire` once the clock reaches `at`. A time in the past fires on the next advance. */
+    setTimer(at: number, fire: () => void): TimerHandle;
+    /** Calls `fire` after `delayMs` more milliseconds. */
+    setTimeout(fire: () => void, delayMs: number): TimerHandle;
+    /**
+     * Moves time forward by `ms`, firing due timers in time order (ties in the order they were
+     * set). The clock reads each timer's own time while it fires, and timers set by a callback
+     * fire in the same call if they fall due. Returns how many fired.
+     */
+    advance(ms: number): number;
+    /** Like `advance`, to an absolute time. Moving backwards throws. */
+    advanceTo(time: number): number;
+    /** Advances to each pending timer in turn until none is left. Throws after `limit` firings. */
+    runAll(limit?: number): number;
+    /** How many timers are waiting. */
+    pendingTimers(): number;
+}
+/** A fake clock starting at `start` milliseconds (default 0). */
+export declare const createFakeClock: (start?: number) => FakeClock;

package/dist/clock.js

@@ -0,0 +1,58 @@
+//#region src/clock.ts
+/** A fake clock starting at `start` milliseconds (default 0). */
+var createFakeClock = (start = 0) => {
+	let time = start;
+	let order = 0;
+	let timers = [];
+	const setTimer = (at, fire) => {
+		if (!Number.isFinite(at)) throw new RangeError(`Timer time must be finite, got ${at}.`);
+		const timer = {
+			at,
+			order: order += 1,
+			fire,
+			cancelled: false
+		};
+		timers.push(timer);
+		return { cancel: () => {
+			timer.cancelled = true;
+		} };
+	};
+	const nextDue = (until) => {
+		timers = timers.filter((t) => !t.cancelled);
+		let best;
+		for (const t of timers) if (t.at <= until && (best === void 0 || t.at < best.at || t.at === best.at && t.order < best.order)) best = t;
+		return best;
+	};
+	const advanceTo = (target) => {
+		if (target < time) throw new RangeError(`The fake clock can't go back from ${time} to ${target}.`);
+		let fired = 0;
+		for (let timer = nextDue(target); timer !== void 0; timer = nextDue(target)) {
+			timer.cancelled = true;
+			time = Math.max(time, timer.at);
+			fired += 1;
+			timer.fire();
+		}
+		time = target;
+		return fired;
+	};
+	return {
+		now: () => time,
+		setTimer,
+		setTimeout: (fire, delayMs) => setTimer(time + delayMs, fire),
+		advance: (ms) => advanceTo(time + ms),
+		advanceTo,
+		runAll: (limit = 1e4) => {
+			let fired = 0;
+			for (let timer = nextDue(Infinity); timer !== void 0; timer = nextDue(Infinity)) {
+				if (fired >= limit) throw new Error(`runAll fired ${limit} timers and timers remain; a timer probably reschedules itself.`);
+				fired += advanceTo(Math.max(time, timer.at));
+			}
+			return fired;
+		},
+		pendingTimers: () => timers.filter((t) => !t.cancelled).length
+	};
+};
+//#endregion
+export { createFakeClock };
+
+//# sourceMappingURL=clock.js.map

package/dist/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","names":[],"sources":["../src/clock.ts"],"sourcesContent":["// A fake clock: time moves only when a test says so.\n\n/** A scheduled callback; cancelling it twice, or after it fired, is harmless. */\nexport type TimerHandle = { cancel(): void };\n\n/**\n * A manual clock with timers. It has the shape of the room server's `Clock` port\n * (`now` and `setTimer`, room-server.md section 4.1) plus controls for tests.\n */\nexport interface FakeClock {\n  /** Current time in milliseconds. */\n  now(): number;\n  /** Calls `fire` once the clock reaches `at`. A time in the past fires on the next advance. */\n  setTimer(at: number, fire: () => void): TimerHandle;\n  /** Calls `fire` after `delayMs` more milliseconds. */\n  setTimeout(fire: () => void, delayMs: number): TimerHandle;\n  /**\n   * Moves time forward by `ms`, firing due timers in time order (ties in the order they were\n   * set). The clock reads each timer's own time while it fires, and timers set by a callback\n   * fire in the same call if they fall due. Returns how many fired.\n   */\n  advance(ms: number): number;\n  /** Like `advance`, to an absolute time. Moving backwards throws. */\n  advanceTo(time: number): number;\n  /** Advances to each pending timer in turn until none is left. Throws after `limit` firings. */\n  runAll(limit?: number): number;\n  /** How many timers are waiting. */\n  pendingTimers(): number;\n}\n\ntype Timer = { readonly at: number; readonly order: number; readonly fire: () => void; cancelled: boolean };\n\n/** A fake clock starting at `start` milliseconds (default 0). */\nexport const createFakeClock = (start = 0): FakeClock => {\n  let time = start;\n  let order = 0;\n  let timers: Timer[] = [];\n\n  const setTimer = (at: number, fire: () => void): TimerHandle => {\n    if (!Number.isFinite(at)) throw new RangeError(`Timer time must be finite, got ${at}.`);\n    const timer: Timer = { at, order: (order += 1), fire, cancelled: false };\n    timers.push(timer);\n    return {\n      cancel: () => {\n        timer.cancelled = true;\n      },\n    };\n  };\n\n  const nextDue = (until: number): Timer | undefined => {\n    timers = timers.filter((t) => !t.cancelled);\n    let best: Timer | undefined;\n    for (const t of timers) {\n      if (t.at <= until && (best === undefined || t.at < best.at || (t.at === best.at && t.order < best.order)))\n        best = t;\n    }\n    return best;\n  };\n\n  const advanceTo = (target: number): number => {\n    if (target < time) throw new RangeError(`The fake clock can't go back from ${time} to ${target}.`);\n    let fired = 0;\n    for (let timer = nextDue(target); timer !== undefined; timer = nextDue(target)) {\n      timer.cancelled = true;\n      time = Math.max(time, timer.at);\n      fired += 1;\n      timer.fire();\n    }\n    time = target;\n    return fired;\n  };\n\n  return {\n    now: () => time,\n    setTimer,\n    setTimeout: (fire, delayMs) => setTimer(time + delayMs, fire),\n    advance: (ms) => advanceTo(time + ms),\n    advanceTo,\n    runAll: (limit = 10_000) => {\n      let fired = 0;\n      for (let timer = nextDue(Infinity); timer !== undefined; timer = nextDue(Infinity)) {\n        if (fired >= limit)\n          throw new Error(`runAll fired ${limit} timers and timers remain; a timer probably reschedules itself.`);\n        fired += advanceTo(Math.max(time, timer.at));\n      }\n      return fired;\n    },\n    pendingTimers: () => timers.filter((t) => !t.cancelled).length,\n  };\n};\n"],"mappings":";;AAiCA,IAAa,mBAAmB,QAAQ,MAAiB;CACvD,IAAI,OAAO;CACX,IAAI,QAAQ;CACZ,IAAI,SAAkB,CAAC;CAEvB,MAAM,YAAY,IAAY,SAAkC;EAC9D,IAAI,CAAC,OAAO,SAAS,EAAE,GAAG,MAAM,IAAI,WAAW,kCAAkC,GAAG,EAAE;EACtF,MAAM,QAAe;GAAE;GAAI,OAAQ,SAAS;GAAI;GAAM,WAAW;EAAM;EACvE,OAAO,KAAK,KAAK;EACjB,OAAO,EACL,cAAc;GACZ,MAAM,YAAY;EACpB,EACF;CACF;CAEA,MAAM,WAAW,UAAqC;EACpD,SAAS,OAAO,QAAQ,MAAM,CAAC,EAAE,SAAS;EAC1C,IAAI;EACJ,KAAK,MAAM,KAAK,QACd,IAAI,EAAE,MAAM,UAAU,SAAS,KAAA,KAAa,EAAE,KAAK,KAAK,MAAO,EAAE,OAAO,KAAK,MAAM,EAAE,QAAQ,KAAK,QAChG,OAAO;EAEX,OAAO;CACT;CAEA,MAAM,aAAa,WAA2B;EAC5C,IAAI,SAAS,MAAM,MAAM,IAAI,WAAW,qCAAqC,KAAK,MAAM,OAAO,EAAE;EACjG,IAAI,QAAQ;EACZ,KAAK,IAAI,QAAQ,QAAQ,MAAM,GAAG,UAAU,KAAA,GAAW,QAAQ,QAAQ,MAAM,GAAG;GAC9E,MAAM,YAAY;GAClB,OAAO,KAAK,IAAI,MAAM,MAAM,EAAE;GAC9B,SAAS;GACT,MAAM,KAAK;EACb;EACA,OAAO;EACP,OAAO;CACT;CAEA,OAAO;EACL,WAAW;EACX;EACA,aAAa,MAAM,YAAY,SAAS,OAAO,SAAS,IAAI;EAC5D,UAAU,OAAO,UAAU,OAAO,EAAE;EACpC;EACA,SAAS,QAAQ,QAAW;GAC1B,IAAI,QAAQ;GACZ,KAAK,IAAI,QAAQ,QAAQ,QAAQ,GAAG,UAAU,KAAA,GAAW,QAAQ,QAAQ,QAAQ,GAAG;IAClF,IAAI,SAAS,OACX,MAAM,IAAI,MAAM,gBAAgB,MAAM,gEAAgE;IACxG,SAAS,UAAU,KAAK,IAAI,MAAM,MAAM,EAAE,CAAC;GAC7C;GACA,OAAO;EACT;EACA,qBAAqB,OAAO,QAAQ,MAAM,CAAC,EAAE,SAAS,CAAC,CAAC;CAC1D;AACF"}

package/dist/deep.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The first place where `a` and `b` differ, as a readable path with both values, or null when
+ * they are structurally equal. Numbers compare with `Object.is`, so `0` and `-0` differ, and
+ * a missing key differs from a key holding `undefined`.
+ */
+export declare const firstDifference: (a: unknown, b: unknown, path?: string) => string | null;
+/** True when `a` and `b` are structurally equal (see `firstDifference`). */
+export declare const deepEqual: (a: unknown, b: unknown) => boolean;
+/**
+ * Freezes `value` and everything reachable from it, then returns it. The suites freeze every
+ * state, command and input they hand to an engine, so an engine that mutates its input
+ * throws instead of silently corrupting the game.
+ */
+export declare const deepFreeze: <T>(value: T) => T;
+/**
+ * Why `value` isn't JSON, with the path to the first offending part, or null when it is.
+ * The contract's `isJson` answers yes or no; failure messages need the where and why.
+ */
+export declare const jsonProblem: (value: unknown, path?: string, seen?: Set<object>) => string | null;
+/** A JSON round trip: what a value looks like after a socket, a save or a replay file. */
+export declare const jsonRoundTrip: <T>(value: T) => T;
+/** A short, single-line rendering of any value for failure messages. */
+export declare const show: (value: unknown) => string;
+/** The message of anything thrown. */
+export declare const errorMessage: (error: unknown) => string;