@eigeninteractive/testkit 0.5.2 → 0.6.1

package/dist/contract-cli.d.ts

@@ -1,2 +1 @@
-#!/usr/bin/env node
-export {};
+export {}

package/dist/contract-cli.js

@@ -1,34 +1,33 @@
 #!/usr/bin/env node
-import {
-  checkConfiguredGameContract,
-  emitConfiguredGameContract
-} from "./chunk-BQIY636F.js";
-
-// src/contract-cli.ts
+import { n as emitConfiguredGameContract, t as checkConfiguredGameContract } from "./contract-command-aCqO5CyJ.js";
 import { parseArgs } from "node:util";
+//#region src/contract-cli.ts
 try {
-  const { values } = parseArgs({
-    strict: true,
-    options: {
-      check: { type: "boolean" },
-      help: { type: "boolean", short: "h" }
-    }
-  });
-  if (values.help) {
-    console.log(`Usage: eigen-contract [options]
+	const { values } = parseArgs({
+		strict: true,
+		options: {
+			check: { type: "boolean" },
+			help: {
+				type: "boolean",
+				short: "h"
+			}
+		}
+	});
+	if (values.help) console.log(`Usage: eigen-contract [options]
 
 Emit game-contract.json from the configured game module and fixtures.
 
 Options:
   --check      Fail when the committed contract is stale
   -h, --help   Show this help`);
-  } else {
-    if (values.check) await checkConfiguredGameContract();
-    else await emitConfiguredGameContract();
-  }
+	else if (values.check) await checkConfiguredGameContract();
+	else await emitConfiguredGameContract();
 } catch (error) {
-  const message = error instanceof Error ? error.message : String(error);
-  console.error(`eigen-contract: ${message}`);
-  process.exitCode = 1;
+	const message = error instanceof Error ? error.message : String(error);
+	console.error(`eigen-contract: ${message}`);
+	process.exitCode = 1;
 }
+//#endregion
+export {};
+
 //# sourceMappingURL=contract-cli.js.map

package/dist/contract-cli.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/contract-cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { parseArgs } from \"node:util\";\nimport { checkConfiguredGameContract, emitConfiguredGameContract } from \"./contract-command.js\";\n\ntry {\n  const { values } = parseArgs({\n    strict: true,\n    options: {\n      check: { type: \"boolean\" },\n      help: { type: \"boolean\", short: \"h\" },\n    },\n  });\n  if (values.help) {\n    console.log(`Usage: eigen-contract [options]\n\nEmit game-contract.json from the configured game module and fixtures.\n\nOptions:\n  --check      Fail when the committed contract is stale\n  -h, --help   Show this help`);\n  } else {\n    if (values.check) await checkConfiguredGameContract();\n    else await emitConfiguredGameContract();\n  }\n} catch (error) {\n  const message = error instanceof Error ? error.message : String(error);\n  console.error(`eigen-contract: ${message}`);\n  process.exitCode = 1;\n}\n"],"mappings":";;;;;;;AACA,SAAS,iBAAiB;AAG1B,IAAI;AACF,QAAM,EAAE,OAAO,IAAI,UAAU;AAAA,IAC3B,QAAQ;AAAA,IACR,SAAS;AAAA,MACP,OAAO,EAAE,MAAM,UAAU;AAAA,MACzB,MAAM,EAAE,MAAM,WAAW,OAAO,IAAI;AAAA,IACtC;AAAA,EACF,CAAC;AACD,MAAI,OAAO,MAAM;AACf,YAAQ,IAAI;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,8BAMc;AAAA,EAC5B,OAAO;AACL,QAAI,OAAO,MAAO,OAAM,4BAA4B;AAAA,QAC/C,OAAM,2BAA2B;AAAA,EACxC;AACF,SAAS,OAAO;AACd,QAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AACrE,UAAQ,MAAM,mBAAmB,OAAO,EAAE;AAC1C,UAAQ,WAAW;AACrB;","names":[]}
+{"version":3,"file":"contract-cli.js","names":[],"sources":["../src/contract-cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { parseArgs } from \"node:util\";\nimport { checkConfiguredGameContract, emitConfiguredGameContract } from \"./contract-command.js\";\n\ntry {\n  const { values } = parseArgs({\n    strict: true,\n    options: {\n      check: { type: \"boolean\" },\n      help: { type: \"boolean\", short: \"h\" },\n    },\n  });\n  if (values.help) {\n    console.log(`Usage: eigen-contract [options]\n\nEmit game-contract.json from the configured game module and fixtures.\n\nOptions:\n  --check      Fail when the committed contract is stale\n  -h, --help   Show this help`);\n  } else {\n    if (values.check) await checkConfiguredGameContract();\n    else await emitConfiguredGameContract();\n  }\n} catch (error) {\n  const message = error instanceof Error ? error.message : String(error);\n  console.error(`eigen-contract: ${message}`);\n  process.exitCode = 1;\n}\n"],"mappings":";;;;AAIA,IAAI;CACF,MAAM,EAAE,WAAW,UAAU;EAC3B,QAAQ;EACR,SAAS;GACP,OAAO,EAAE,MAAM,UAAU;GACzB,MAAM;IAAE,MAAM;IAAW,OAAO;GAAI;EACtC;CACF,CAAC;CACD,IAAI,OAAO,MACT,QAAQ,IAAI;;;;;;8BAMc;MAE1B,IAAI,OAAO,OAAO,MAAM,4BAA4B;MAC/C,MAAM,2BAA2B;AAE1C,SAAS,OAAO;CACd,MAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;CACrE,QAAQ,MAAM,mBAAmB,SAAS;CAC1C,QAAQ,WAAW;AACrB"}

package/dist/contract-command-aCqO5CyJ.js

@@ -0,0 +1,542 @@
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { basename, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { tsImport } from "tsx/esm/api";
+import { IllegalMoveError, assertPortableSchema } from "@eigeninteractive/rules";
+import Rand from "rand-seed";
+import { it } from "vitest";
+//#region src/twin-fixtures.ts
+/**
+* Twin-drift fixture runner: the TS half of the shared JSON fixtures that
+* keep a version unit's TS and Dart `GameRules` twins in sync. The JSON
+* fixture format is shared verbatim with the Dart runner
+* (`lib/testing/twin_fixtures.dart`): one file, two consumers.
+*
+* One fixture file per concern lives beside the version units at
+* `<fixturesRoot>/v<N>/*.json` and is consumed by BOTH sides: this module
+* runs each case against the TS unit (schemas + `applyAction` +
+* `computeObservation` + the two predicates), while the Dart runner runs the
+* same file against the Dart twin (generated payload parsing,
+* `isValidAction`, `previewAction`, predicate twins). A behavioral divergence
+* then fails one side's CI instead of degrading UX in production.
+*
+* ## Fixture file format
+*
+* ```jsonc
+* {
+*   "schemaVersion": 1,
+*   "cases": [
+*     {
+*       "kind": "action",
+*       "name": "seat 0 marks an empty cell",
+*       "config": {},
+*       "state": { ... },            // TS: applyAction input
+*       "obs": { ... },              // Dart-only; defaults to `state`
+*       "pending": [0],
+*       "playerIndex": 0,
+*       "participantCount": 2,       // optional, default 2
+*       "rngSeed": "any string",     // optional, default "twin-fixtures"
+*       "action": { ... },
+*       "expected": {
+*         "valid": true,             // false ⇒ TS IllegalMoveError,
+*                                    //         Dart isValidAction false
+*         "state": { ... },          // optional, TS envelope.state
+*         "pending": [1],            // optional, TS envelope.pendingPlayers
+*         "outcome": [ ... ],        // optional, TS envelope.outcome
+*                                    //   (null asserts the game is ongoing)
+*         "observation": { ... }     // optional, the actor's post-action
+*                                    //   view: TS computeObservation slice
+*                                    //   data; Dart previewAction (when the
+*                                    //   game implements optimism)
+*       }
+*     },
+*     { "kind": "playerLimits", "name": "...", "config": {},
+*       "expected": { "minPlayers": 2, "maxPlayers": 2 } },
+*     { "kind": "ratingPool",  "name": "...", "access": "public",
+*       "minPlayers": 2, "maxPlayers": 2, "config": {}, "expected": "blitz" },
+*     { "kind": "botSeatable", "name": "...", "gameConfig": {},
+*       "botConfig": {}, "expected": false }
+*   ]
+* }
+* ```
+*
+* The `state`/`obs` split exists for hidden-info games (a seat's observation
+* is not the state); perfect-info games omit `obs`. `expected.observation` is
+* the shared behavioral anchor: the TS side must project the post-action
+* state to it, and a Dart `previewAction` that returns non-null must predict
+* it, so the two sides are compared through one recorded value.
+*
+* Wire it up in a game-owned test file running under plain-Node vitest:
+*
+* ```ts
+* import { twinFixtureTests } from "@eigeninteractive/testkit";
+* import gameModule from "../src/module/index.js";
+*
+* twinFixtureTests(gameModule, new URL("../src/module/fixtures/", import.meta.url));
+* ```
+*/
+function describe(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "an array";
+	return typeof value;
+}
+function fail(where, expected, got) {
+	throw new Error(`${where}: expected ${expected}, got ${describe(got)}`);
+}
+function asObject(where, v) {
+	if (typeof v !== "object" || v === null || Array.isArray(v)) fail(where, "an object", v);
+	return v;
+}
+function asString(where, v) {
+	if (typeof v !== "string") fail(where, "a string", v);
+	return v;
+}
+function asNumber(where, v) {
+	if (typeof v !== "number" || !Number.isFinite(v)) fail(where, "a finite number", v);
+	return v;
+}
+function asBoolean(where, v) {
+	if (typeof v !== "boolean") fail(where, "a boolean", v);
+	return v;
+}
+function asNumberArray(where, v) {
+	if (!Array.isArray(v)) fail(where, "an array of numbers", v);
+	return v.map((n, i) => asNumber(`${where}[${i}]`, n));
+}
+/** Applies `read` only when the key is present and non-null; absent and
+* explicit null both mean "not specified" for every optional fixture field. */
+function optional(where, v, read) {
+	return v === void 0 || v === null ? void 0 : read(where, v);
+}
+function parseActionCase(where, raw) {
+	const expectedRaw = asObject(`${where}.expected`, raw.expected);
+	const expected = {
+		valid: asBoolean(`${where}.expected.valid`, expectedRaw.valid),
+		state: optional(`${where}.expected.state`, expectedRaw.state, asObject),
+		pending: optional(`${where}.expected.pending`, expectedRaw.pending, asNumberArray),
+		observation: optional(`${where}.expected.observation`, expectedRaw.observation, asObject)
+	};
+	if ("outcome" in expectedRaw) {
+		const outcome = expectedRaw.outcome;
+		if (outcome !== null && !Array.isArray(outcome)) fail(`${where}.expected.outcome`, "an array or null", outcome);
+		expected.outcome = outcome;
+	}
+	return {
+		kind: "action",
+		name: asString(`${where}.name`, raw.name),
+		config: asObject(`${where}.config`, raw.config),
+		state: asObject(`${where}.state`, raw.state),
+		obs: optional(`${where}.obs`, raw.obs, asObject),
+		pending: asNumberArray(`${where}.pending`, raw.pending),
+		playerIndex: asNumber(`${where}.playerIndex`, raw.playerIndex),
+		participantCount: optional(`${where}.participantCount`, raw.participantCount, asNumber),
+		rngSeed: optional(`${where}.rngSeed`, raw.rngSeed, asString),
+		action: asObject(`${where}.action`, raw.action),
+		expected
+	};
+}
+function parseRatingPoolCase(where, raw) {
+	const access = asString(`${where}.access`, raw.access);
+	if (access !== "public" && access !== "private" && access !== "friends") throw new Error(`${where}.access: expected one of public | private | friends, got ${JSON.stringify(access)}`);
+	return {
+		kind: "ratingPool",
+		name: asString(`${where}.name`, raw.name),
+		access,
+		turnSeconds: optional(`${where}.turnSeconds`, raw.turnSeconds, asNumber) ?? null,
+		budgetSeconds: optional(`${where}.budgetSeconds`, raw.budgetSeconds, asNumber) ?? null,
+		incrementSeconds: optional(`${where}.incrementSeconds`, raw.incrementSeconds, asNumber) ?? null,
+		minPlayers: asNumber(`${where}.minPlayers`, raw.minPlayers),
+		maxPlayers: asNumber(`${where}.maxPlayers`, raw.maxPlayers),
+		config: asObject(`${where}.config`, raw.config),
+		expected: raw.expected === null ? null : asString(`${where}.expected`, raw.expected)
+	};
+}
+function parsePlayerLimitsCase(where, raw) {
+	const expected = asObject(`${where}.expected`, raw.expected);
+	return {
+		kind: "playerLimits",
+		name: asString(`${where}.name`, raw.name),
+		config: asObject(`${where}.config`, raw.config),
+		expected: {
+			minPlayers: asNumber(`${where}.expected.minPlayers`, expected.minPlayers),
+			maxPlayers: asNumber(`${where}.expected.maxPlayers`, expected.maxPlayers)
+		}
+	};
+}
+function parseBotSeatableCase(where, raw) {
+	return {
+		kind: "botSeatable",
+		name: asString(`${where}.name`, raw.name),
+		gameConfig: asObject(`${where}.gameConfig`, raw.gameConfig),
+		botConfig: asObject(`${where}.botConfig`, raw.botConfig),
+		expected: asBoolean(`${where}.expected`, raw.expected)
+	};
+}
+/** Validate one fixture file's parsed JSON, or throw naming the offending
+* file, case, and field. Exported so a repo can lint its fixtures without
+* running them. */
+function parseTwinFixtureFile(path, json) {
+	const root = asObject(path, json);
+	const schemaVersion = asNumber(`${path}.schemaVersion`, root.schemaVersion);
+	if (!Array.isArray(root.cases)) fail(`${path}.cases`, "an array", root.cases);
+	return {
+		schemaVersion,
+		cases: root.cases.map((raw, i) => {
+			const indexed = `${path}.cases[${i}]`;
+			const obj = asObject(indexed, raw);
+			const where = typeof obj.name === "string" ? `${indexed} (${obj.name})` : indexed;
+			switch (obj.kind) {
+				case "action": return parseActionCase(where, obj);
+				case "playerLimits": return parsePlayerLimitsCase(where, obj);
+				case "ratingPool": return parseRatingPoolCase(where, obj);
+				case "botSeatable": return parseBotSeatableCase(where, obj);
+				default: throw new Error(`${where}.kind: expected one of action | playerLimits | ratingPool | botSeatable, got ${JSON.stringify(obj.kind)}`);
+			}
+		})
+	};
+}
+/** Run one fixture case against a rules unit, returning failure descriptions
+* (empty ⇒ the case passes). Pure; the file-reading test registrar is
+* {@link twinFixtureTests}. */
+function evaluateTwinCase(rules, kase) {
+	switch (kase.kind) {
+		case "action": return evaluateAction(rules, kase);
+		case "playerLimits": return evaluatePlayerLimits(rules, kase);
+		case "ratingPool": return evaluateRatingPool(rules, kase);
+		case "botSeatable": return evaluateBotSeatable(rules, kase);
+		default: return [`unknown case kind "${kase.kind}", expected action | playerLimits | ratingPool | botSeatable`];
+	}
+}
+/** Register one vitest test per fixture case found under `fixturesRoot`
+* (layout: `<root>/v<N>/*.json`). Call at the top level of a test module
+* running in a Node environment. */
+function twinFixtureTests(gameModule, fixturesRoot) {
+	for (const filePath of fixtureFiles$1(fixturesRoot)) {
+		const fixture = parseTwinFixtureFile(filePath, JSON.parse(readFileSync(filePath, "utf8")));
+		const rules = gameModule.versions[fixture.schemaVersion];
+		for (const kase of fixture.cases) it(`twin v${fixture.schemaVersion}: ${kase.name}`, () => {
+			if (!rules) throw new Error(`gameModule ships no rules unit for schemaVersion ${fixture.schemaVersion} (fixture: ${filePath})`);
+			const failures = evaluateTwinCase(rules, kase);
+			if (failures.length) throw new Error(`\n${failures.join("\n")}`);
+		});
+	}
+}
+function* fixtureFiles$1(root) {
+	const dirs = readdirSync(root, { withFileTypes: true }).filter((e) => e.isDirectory()).sort((a, b) => a.name.localeCompare(b.name));
+	for (const dir of dirs) {
+		const files = readdirSync(`${dir.parentPath}/${dir.name}`, { withFileTypes: true }).filter((e) => e.isFile() && e.name.endsWith(".json")).sort((a, b) => a.name.localeCompare(b.name));
+		for (const file of files) yield `${file.parentPath}/${file.name}`;
+	}
+}
+function evaluateAction(rules, kase) {
+	const failures = [];
+	const config = parseWith(rules, "config", kase.config, failures);
+	const state = parseWith(rules, "state", kase.state, failures);
+	const action = parseWith(rules, "action", kase.action, failures);
+	if (config === void 0 || state === void 0 || action === void 0) return failures;
+	if (!deepEquals(action, kase.action)) failures.push(`action schema does not preserve the fixture action, parsed to ${JSON.stringify(action)}`);
+	const envelope = applyFixtureAction(rules, kase, config, state, action);
+	if (typeof envelope === "string") {
+		if (envelope) failures.push(envelope);
+		return failures;
+	}
+	checkEnvelope(rules, kase, envelope, failures);
+	if (kase.expected.observation !== void 0) checkObservation(rules, kase, envelope, config, action, failures);
+	return failures;
+}
+/** Invoke `applyAction` and reconcile with `expected.valid`. Returns the
+* envelope on a valid accepted move, an error string on failure, or "" when
+* an expected-illegal move was correctly rejected (nothing left to check). */
+function applyFixtureAction(rules, kase, config, state, action) {
+	let envelope;
+	try {
+		envelope = rules.applyAction({
+			state,
+			pending: kase.pending,
+			data: action,
+			playerIndex: kase.playerIndex,
+			rng: new Rand(kase.rngSeed ?? "twin-fixtures"),
+			config
+		});
+	} catch (error) {
+		if (!(error instanceof IllegalMoveError)) return `applyAction threw a non-IllegalMoveError: ${error}`;
+		return kase.expected.valid ? `applyAction rejected a move the fixture expects to be valid: ${error.message}` : "";
+	}
+	return kase.expected.valid ? envelope : "applyAction accepted a move the fixture expects to be illegal";
+}
+function checkEnvelope(rules, kase, envelope, failures) {
+	if (validate(rules, "state", envelope.state) === void 0) failures.push("applyAction returned state that violates its own schema");
+	const expected = kase.expected;
+	if (expected.state !== void 0 && !deepEquals(envelope.state, expected.state)) failures.push(`envelope.state mismatch, got ${JSON.stringify(envelope.state)}`);
+	if (expected.pending !== void 0 && !deepEquals(envelope.pendingPlayers, expected.pending)) failures.push(`envelope.pendingPlayers mismatch, got ${JSON.stringify(envelope.pendingPlayers)}`);
+	if ("outcome" in expected && !deepEquals(envelope.outcome ?? null, expected.outcome ?? null)) failures.push(`envelope.outcome mismatch, got ${JSON.stringify(envelope.outcome ?? null)}`);
+}
+function checkObservation(rules, kase, envelope, config, action, failures) {
+	let slice;
+	try {
+		slice = rules.computeObservation({
+			state: envelope.state,
+			pending: envelope.pendingPlayers,
+			playerIndex: kase.playerIndex,
+			participantCount: kase.participantCount ?? 2,
+			config,
+			cause: {
+				kind: "game",
+				data: action,
+				playerIndex: kase.playerIndex
+			},
+			isReplay: false
+		});
+	} catch (error) {
+		failures.push(`computeObservation threw: ${error}`);
+		return;
+	}
+	if (!deepEquals(slice.data, kase.expected.observation)) failures.push(`actor's observation mismatch, got ${JSON.stringify(slice.data)}`);
+}
+function evaluateRatingPool(rules, kase) {
+	const failures = [];
+	const config = parseWith(rules, "config", kase.config, failures);
+	if (config === void 0) return failures;
+	const pool = rules.ratingPool({
+		access: kase.access,
+		turnSeconds: kase.turnSeconds ?? null,
+		budgetSeconds: kase.budgetSeconds ?? null,
+		incrementSeconds: kase.incrementSeconds ?? null,
+		minPlayers: kase.minPlayers,
+		maxPlayers: kase.maxPlayers,
+		config
+	});
+	if (pool !== kase.expected) failures.push(`ratingPool returned ${JSON.stringify(pool)}, fixture expects ${JSON.stringify(kase.expected)}`);
+	return failures;
+}
+function evaluatePlayerLimits(rules, kase) {
+	const failures = [];
+	const config = parseWith(rules, "config", kase.config, failures);
+	if (config === void 0) return failures;
+	const limits = rules.playerLimits({ config });
+	if (limits.minPlayers !== kase.expected.minPlayers || limits.maxPlayers !== kase.expected.maxPlayers) failures.push(`playerLimits returned ${limits.minPlayers}-${limits.maxPlayers}, fixture expects ${kase.expected.minPlayers}-${kase.expected.maxPlayers}`);
+	return failures;
+}
+function evaluateBotSeatable(rules, kase) {
+	const failures = [];
+	const gameConfig = parseWith(rules, "config", kase.gameConfig, failures);
+	if (gameConfig === void 0) return failures;
+	const seatable = rules.botSeatable({
+		gameConfig,
+		botConfig: kase.botConfig
+	});
+	if (seatable !== kase.expected) failures.push(`botSeatable returned ${seatable}, fixture expects ${kase.expected}`);
+	return failures;
+}
+/** Run one of the unit's Standard Schemas synchronously, returning the parsed
+* value or undefined on failure (issues written to the second return slot). */
+function validate(rules, which, value, issues) {
+	const result = rules.schemas[which]["~standard"].validate(value);
+	if (result instanceof Promise) {
+		issues?.push(`${which} schema validated asynchronously; must be sync`);
+		return;
+	}
+	if (result.issues) {
+		issues?.push(result.issues.map((i) => {
+			const path = i.path?.map((p) => typeof p === "object" ? String(p.key) : String(p)).join(".");
+			return path ? `${path}: ${i.message}` : i.message;
+		}).join("; "));
+		return;
+	}
+	return result.value;
+}
+/** Parse a fixture payload through one of the unit's schemas, recording a
+* failure (and returning undefined) when it does not conform. */
+function parseWith(rules, which, value, failures) {
+	const issues = [];
+	const parsed = validate(rules, which, value, issues);
+	if (parsed === void 0) failures.push(`fixture ${which} fails the TS ${which} schema: ${issues.join("; ")}`);
+	return parsed;
+}
+/** Structural JSON equality. Object keys with `undefined` values count as
+* absent (matching how schema libraries model optional fields); array order
+* matters. */
+function deepEquals(a, b) {
+	if (a === void 0 || a === null) return b === void 0 || b === null;
+	if (b === void 0 || b === null) return false;
+	if (Array.isArray(a) || Array.isArray(b)) {
+		if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+		return a.every((item, i) => deepEquals(item, b[i]));
+	}
+	if (typeof a === "object" || typeof b === "object") {
+		if (typeof a !== "object" || typeof b !== "object") return false;
+		return [.../* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)])].every((k) => deepEquals(a[k], b[k]));
+	}
+	return a === b;
+}
+//#endregion
+//#region src/game-contract.ts
+/**
+* Emit the language-neutral contract a game's Flutter repository consumes.
+*
+* The authoritative inputs live with the TypeScript rules: the four payload
+* schemas and the shared behavioral fixtures. The output is one deterministic
+* JSON file so it can be copied, attached to a release, or fetched by checksum
+* without assuming any repository layout.
+*/
+/** Current format of the language-neutral contract consumed by EigenInteractive's Dart generator. */
+const GAME_CONTRACT_FORMAT_VERSION = 1;
+/**
+* Sort object keys so the same schemas always emit the same bytes.
+*
+* Ordering is by UTF-16 code unit — plain `Array#sort` — which is what RFC 8785
+* specifies and what `tool/check-contracts.mjs` uses to digest a manifest. It is
+* *not* `localeCompare`: that collates case-insensitively, so a `$defs` entry
+* named `Move` sorts before `additionalProperties` under one rule and after it
+* under the other. Generated JSON Schema is full of capitalized `$defs` names, so
+* the two orders genuinely disagree, and a digest computed over one would never
+* match a document written by the other.
+*/
+function canonical(value) {
+	if (Array.isArray(value)) return value.map(canonical);
+	if (value !== null && typeof value === "object") return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, item]) => [key, canonical(item)]));
+	return value;
+}
+/**
+* Emit one payload schema as portable draft-2020-12 JSON Schema.
+*
+* Always the **output** direction. Zod's input schema omits
+* `additionalProperties: false` on objects, because on input a permissive object
+* still strips unknown keys rather than rejecting them — but the contract is what
+* the Dart side generates a validator from, and an open object there means the two
+* halves disagree about an unknown key. Schemas are required to be transform-free
+* (see `GameSchemas`), so the two directions describe the same values and the
+* output one is simply the honest document.
+*
+* The result is then checked against the portable profile, because emission is
+* where an unportable schema can still be fixed cheaply. Skipping this check is
+* how the profile came to be violated in the first place.
+*/
+function jsonSchema(schema, label) {
+	const options = { target: "draft-2020-12" };
+	let emitted;
+	try {
+		emitted = canonical(schema["~standard"].jsonSchema.output(options));
+	} catch (error) {
+		throw new Error(`${label} cannot emit its type as draft-2020-12 JSON Schema`, { cause: error });
+	}
+	assertPortableSchema(emitted, label);
+	return emitted;
+}
+function fixtureFiles(root) {
+	const found = [];
+	const visit = (directory) => {
+		for (const entry of readdirSync(directory, { withFileTypes: true })) {
+			const path = resolve(directory, entry.name);
+			if (entry.isDirectory()) visit(path);
+			else if (entry.isFile() && entry.name.endsWith(".json")) found.push(path);
+		}
+	};
+	visit(root);
+	return found.sort();
+}
+function fixtures(fixturesRoot, versions) {
+	if (fixturesRoot === void 0) return [];
+	const root = fixturesRoot instanceof URL ? fixturesRoot.pathname : resolve(fixturesRoot);
+	return fixtureFiles(root).map((path) => {
+		const document = JSON.parse(readFileSync(path, "utf8"));
+		const fixture = parseTwinFixtureFile(path, document);
+		const fixturePath = relative(root, path).split("\\").join("/");
+		const directory = fixturePath.split("/")[0];
+		const match = /^v([1-9]\d*)$/.exec(directory ?? "");
+		if (match === null) throw new Error(`${fixturePath}: fixtures must live under a v<N>/ directory`);
+		const pathVersion = Number(match[1]);
+		if (pathVersion !== fixture.schemaVersion) throw new Error(`${fixturePath}: directory v${pathVersion} disagrees with schemaVersion ${fixture.schemaVersion}`);
+		if (!versions.has(String(fixture.schemaVersion))) throw new Error(`${fixturePath}: gameModule ships no rules unit for schemaVersion ${fixture.schemaVersion}`);
+		return {
+			path: fixturePath,
+			document: canonical(document)
+		};
+	});
+}
+/** Build a deterministic in-memory contract without touching the filesystem. */
+function buildGameContract(options) {
+	const game = options.game.trim();
+	if (game.length === 0) throw new Error("game contract name must not be empty");
+	const versions = Object.fromEntries(Object.entries(options.gameModule.versions).sort(([a], [b]) => Number(a) - Number(b)).map(([version, rules]) => [version, { schemas: {
+		state: jsonSchema(rules.schemas.state, `v${version} state`),
+		observation: jsonSchema(rules.schemas.observation, `v${version} observation`),
+		action: jsonSchema(rules.schemas.action, `v${version} action`),
+		config: jsonSchema(rules.schemas.config, `v${version} config`)
+	} }]));
+	if (Object.keys(versions).length === 0) throw new Error("game contract must contain at least one schema version");
+	return {
+		formatVersion: 1,
+		game,
+		versions,
+		fixtures: fixtures(options.fixturesRoot, new Set(Object.keys(versions)))
+	};
+}
+/** Render one deterministic, newline-terminated contract document. */
+function gameContractJson(options) {
+	return `${JSON.stringify(buildGameContract(options), null, 2)}\n`;
+}
+/** Emit one deterministic, newline-terminated `game-contract.json`. */
+function emitGameContract(options) {
+	const output = options.output instanceof URL ? options.output : resolve(options.output);
+	writeFileSync(output, gameContractJson(options));
+}
+/** Fail when an emitted contract is missing or differs from its inputs. */
+function checkGameContract(options) {
+	const output = options.output instanceof URL ? options.output : resolve(options.output);
+	if (!existsSync(output) || readFileSync(output, "utf8") !== gameContractJson(options)) throw new Error(`${output.toString()} is stale; run eigen-contract`);
+}
+/** A useful default filename for scripts that accept an output directory. */
+const gameContractFilename = (game) => `${basename(game).toLowerCase().replaceAll(/[^a-z0-9]+/g, "-")}-game-contract.json`;
+//#endregion
+//#region src/contract-command.ts
+function configuredString(value, fallback, field) {
+	if (value === void 0) return fallback;
+	if (typeof value !== "string" || value.trim().length === 0) throw new Error(`package.json eigen.${field} must be a non-empty string`);
+	return value;
+}
+const isGameModule = (value) => value !== null && typeof value === "object" && "versions" in value && value.versions !== null && typeof value.versions === "object";
+/**
+* Emit a contract from the conventional game package layout.
+*
+* The package default-exports its GameModule from `src/module/index.ts` and
+* declares `{ "eigen": { "game": "…" } }` in package.json. Paths can be
+* overridden under the same `eigen` object.
+*/
+async function configuredGameContractOptions(root) {
+	const config = JSON.parse(readFileSync(resolve(root, "package.json"), "utf8")).eigen ?? {};
+	const game = configuredString(config.game, "", "game");
+	if (game.length === 0) throw new Error("package.json must declare an EigenInteractive game name, e.g. \"eigen\": { \"game\": \"Chess\" }");
+	const modulePath = configuredString(config.module, "src/module/index.ts", "module");
+	const fixturesPath = configuredString(config.fixtures, "src/module/fixtures", "fixtures");
+	const contractPath = configuredString(config.contract, "game-contract.json", "contract");
+	const imported = await tsImport(pathToFileURL(resolve(root, modulePath)).href, import.meta.url);
+	if (!isGameModule(imported.default)) throw new Error(`${modulePath} must default-export an EigenInteractive GameModule`);
+	return {
+		game,
+		gameModule: imported.default,
+		fixturesRoot: resolve(root, fixturesPath),
+		output: resolve(root, contractPath)
+	};
+}
+/**
+* Emits `game-contract.json` from an EigenInteractive package's conventional layout.
+*
+* This is the programmatic form of the `eigen-contract` executable. Most
+* games should invoke the executable through their package script.
+*/
+async function emitConfiguredGameContract(root = process.cwd()) {
+	emitGameContract(await configuredGameContractOptions(root));
+}
+/**
+* Fails when the conventionally configured contract is absent or stale.
+*
+* Use this in CI through `eigen-contract --check`.
+*/
+async function checkConfiguredGameContract(root = process.cwd()) {
+	checkGameContract(await configuredGameContractOptions(root));
+}
+//#endregion
+export { checkGameContract as a, gameContractJson as c, parseTwinFixtureFile as d, twinFixtureTests as f, buildGameContract as i, deepEquals as l, emitConfiguredGameContract as n, emitGameContract as o, GAME_CONTRACT_FORMAT_VERSION as r, gameContractFilename as s, checkConfiguredGameContract as t, evaluateTwinCase as u };
+
+//# sourceMappingURL=contract-command-aCqO5CyJ.js.map