@its-not-rocket-science/ananke 0.1.51 → 0.1.53

package/dist/src/world-factory.js

@@ -60,6 +60,33 @@ function buildItemMap() {
 }
 /** Map of item id → Item for weapons and armour usable with createWorld(). */
 export const ITEM_MAP = buildItemMap();
+// ── Content-pack extension registries ────────────────────────────────────────
+// Dynamic additions from loadPack(); checked after the static maps.
+const _archetypeExtensions = new Map();
+const _itemExtensions = new Map();
+/**
+ * Register an archetype so it is resolvable by `createWorld` and `loadScenario`.
+ * Called automatically by `loadPack` in `content-pack.ts`.
+ */
+export function registerWorldArchetype(id, archetype) {
+    _archetypeExtensions.set(id, archetype);
+}
+/**
+ * Register a weapon or armour so it is resolvable by `createWorld` and `loadScenario`.
+ * Called automatically by `loadPack` in `content-pack.ts`.
+ */
+export function registerWorldItem(id, item) {
+    _itemExtensions.set(id, item);
+}
+/**
+ * Remove all content-pack extensions from the world-factory lookup tables.
+ * Does NOT affect the static `ARCHETYPE_MAP` or `ITEM_MAP`.
+ * Call in test `afterEach` alongside `clearCatalog()` and `clearPackRegistry()`.
+ */
+export function clearWorldExtensions() {
+    _archetypeExtensions.clear();
+    _itemExtensions.clear();
+}
 // ── createWorld ───────────────────────────────────────────────────────────────
 /**
  * Build a deterministic WorldState from a declarative entity spec list.
@@ -72,21 +99,21 @@ export const ITEM_MAP = buildItemMap();
 export function createWorld(seed, entities) {
     const built = [];
     for (const spec of entities) {
-        // ── Archetype lookup ──────────────────────────────────────────────────────
-        const archetype = ARCHETYPE_MAP.get(spec.archetype);
+        // ── Archetype lookup (static map + content-pack extensions) ──────────────
+        const archetype = ARCHETYPE_MAP.get(spec.archetype) ?? _archetypeExtensions.get(spec.archetype);
         if (archetype === undefined) {
             throw new Error(`createWorld: unknown archetype "${spec.archetype}". ` +
                 `Valid keys: ${[...ARCHETYPE_MAP.keys()].join(", ")}`);
         }
-        // ── Weapon lookup ─────────────────────────────────────────────────────────
-        const weapon = ITEM_MAP.get(spec.weaponId);
+        // ── Weapon lookup (static map + content-pack extensions) ─────────────────
+        const weapon = ITEM_MAP.get(spec.weaponId) ?? _itemExtensions.get(spec.weaponId);
         if (weapon === undefined) {
             throw new Error(`createWorld: unknown weaponId "${spec.weaponId}"`);
         }
         // ── Optional armour lookup ────────────────────────────────────────────────
         let armour;
         if (spec.armourId !== undefined) {
-            armour = ITEM_MAP.get(spec.armourId);
+            armour = ITEM_MAP.get(spec.armourId) ?? _itemExtensions.get(spec.armourId);
             if (armour === undefined) {
                 throw new Error(`createWorld: unknown armourId "${spec.armourId}"`);
             }

package/dist/tools/pack-cli.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// tools/pack-cli.ts — PA-4: Ananke content pack CLI
+//
+// Usage (after npm run build):
+//   node dist/tools/pack-cli.js pack validate <file.json>
+//   node dist/tools/pack-cli.js pack bundle <directory>
+//
+// Or via the installed binary:
+//   npx ananke pack validate <file.json>
+//   npx ananke pack bundle <directory>
+import { readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve, extname, basename } from "node:path";
+import { validatePack, loadPack } from "../src/content-pack.js";
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function readJson(filePath) {
+    try {
+        return JSON.parse(readFileSync(filePath, "utf8"));
+    }
+    catch (e) {
+        console.error(`Error reading ${filePath}: ${String(e)}`);
+        process.exit(1);
+    }
+}
+function printErrors(errors) {
+    for (const err of errors) {
+        console.error(`  ${err.path}: ${err.message}`);
+    }
+}
+// ── Commands ──────────────────────────────────────────────────────────────────
+function cmdValidate(args) {
+    const filePath = args[0];
+    if (!filePath) {
+        console.error("Usage: ananke pack validate <file.json>");
+        process.exit(1);
+    }
+    const manifest = readJson(resolve(filePath));
+    const errors = validatePack(manifest);
+    if (errors.length === 0) {
+        const m = manifest;
+        console.log(`✓  ${m["name"] ?? "pack"}@${m["version"] ?? "?"} — valid`);
+        process.exit(0);
+    }
+    else {
+        console.error(`✗  ${errors.length} error(s) in ${filePath}:`);
+        printErrors(errors);
+        process.exit(1);
+    }
+}
+function cmdBundle(args) {
+    const dir = args[0];
+    const outFile = args[1] ?? "bundle.ananke-pack.json";
+    if (!dir) {
+        console.error("Usage: ananke pack bundle <directory> [output.json]");
+        process.exit(1);
+    }
+    const dirPath = resolve(dir);
+    let entries;
+    try {
+        entries = readdirSync(dirPath).filter(f => extname(f) === ".json");
+    }
+    catch (e) {
+        console.error(`Cannot read directory ${dirPath}: ${String(e)}`);
+        process.exit(1);
+    }
+    if (entries.length === 0) {
+        console.error(`No .json files found in ${dirPath}`);
+        process.exit(1);
+    }
+    const bundle = {
+        name: basename(dirPath),
+        version: "1.0.0",
+        description: `Bundled from ${entries.length} file(s) in ${dirPath}`,
+        weapons: [],
+        armour: [],
+        archetypes: [],
+        scenarios: [],
+    };
+    for (const entry of entries) {
+        const filePath = join(dirPath, entry);
+        if (!statSync(filePath).isFile())
+            continue;
+        const raw = readJson(filePath);
+        const partial = raw;
+        if (Array.isArray(partial.weapons))
+            bundle.weapons.push(...partial.weapons);
+        if (Array.isArray(partial.armour))
+            bundle.armour.push(...partial.armour);
+        if (Array.isArray(partial.archetypes))
+            bundle.archetypes.push(...partial.archetypes);
+        if (Array.isArray(partial.scenarios))
+            bundle.scenarios.push(...partial.scenarios);
+        // Use name/version from first file that has them
+        if (!bundle.name && typeof partial.name === "string")
+            bundle.name = partial.name;
+    }
+    // Pre-validate before writing
+    const errors = validatePack(bundle);
+    if (errors.length > 0) {
+        console.warn(`  ${errors.length} validation warning(s) in bundle:`);
+        printErrors(errors);
+    }
+    const json = JSON.stringify(bundle, null, 2);
+    writeFileSync(outFile, json, "utf8");
+    console.log(`✓  Bundle written to ${outFile}`);
+    console.log(`   weapons: ${bundle.weapons.length}, armour: ${bundle.armour.length}, archetypes: ${bundle.archetypes.length}, scenarios: ${bundle.scenarios.length}`);
+}
+function cmdLoad(args) {
+    const filePath = args[0];
+    if (!filePath) {
+        console.error("Usage: ananke pack load <file.json>");
+        process.exit(1);
+    }
+    const manifest = readJson(resolve(filePath));
+    const result = loadPack(manifest);
+    if (result.errors.length > 0) {
+        console.error(`✗  Load failed:`);
+        printErrors(result.errors);
+        process.exit(1);
+    }
+    console.log(`✓  ${result.packId} loaded`);
+    console.log(`   registered: ${result.registeredIds.join(", ") || "none"}`);
+    console.log(`   scenarios:  ${result.scenarioIds.join(", ") || "none"}`);
+    console.log(`   fingerprint: ${result.fingerprint}`);
+}
+// ── Entry point ───────────────────────────────────────────────────────────────
+function main() {
+    const argv = process.argv.slice(2);
+    if (argv[0] !== "pack") {
+        console.log("Ananke CLI");
+        console.log("");
+        console.log("Commands:");
+        console.log("  pack validate <file.json>           — validate a pack manifest");
+        console.log("  pack bundle <directory> [out.json]  — merge JSON files into one pack");
+        console.log("  pack load <file.json>               — load a pack and report registered ids");
+        process.exit(0);
+    }
+    const sub = argv[1];
+    const rest = argv.slice(2);
+    switch (sub) {
+        case "validate":
+            cmdValidate(rest);
+            break;
+        case "bundle":
+            cmdBundle(rest);
+            break;
+        case "load":
+            cmdLoad(rest);
+            break;
+        default:
+            console.error(`Unknown subcommand: pack ${sub ?? ""}`);
+            console.error("Available: validate, bundle, load");
+            process.exit(1);
+    }
+}
+main();

package/docs/wire-protocol.md

@@ -0,0 +1,209 @@
+# Ananke — Wire Protocol & Save Format
+
+This document specifies how Ananke state is serialised for persistence, replay, and
+network transport.  All formats are deterministic: the same simulation state always
+produces the same bytes.
+
+---
+
+## 1. Concepts
+
+| Term | Meaning |
+|------|---------|
+| **Snapshot** | A serialised `WorldState` — complete enough to resume simulation |
+| **Replay** | An initial snapshot + a sequence of command frames |
+| **Diff** | A compact binary diff between two consecutive snapshots (CE-9) |
+| **Wire message** | A single unit transmitted between host and client over the network |
+| **Q value** | A fixed-point integer scaled by `SCALE.Q = 10 000` (e.g. `q(0.75) = 7500`) |
+
+---
+
+## 2. JSON Snapshot Format
+
+JSON is the recommended format for long-term save files and editor tooling.
+
+### 2.1 Deterministic key ordering
+
+When computing hash-checks across clients, keys must appear in insertion order.
+The canonical TypeScript implementation (`JSON.stringify`) preserves insertion
+order for string keys.  Third-party deserializers must preserve or sort keys
+identically.
+
+### 2.2 Q values
+
+All `Q`-typed fields are serialised as plain integers.  Do **not** divide by
+`SCALE.Q` before saving — the raw integer is the canonical representation.
+
+```json
+{ "fearQ": 7500 }    // correct — q(0.75)
+{ "fearQ": 0.75 }    // WRONG — will cause precision loss and replay divergence
+```
+
+### 2.3 Maps
+
+JavaScript `Map` instances do not serialise to JSON automatically.  Ananke
+serialises `Map<K, V>` as an array of `[K, V]` pairs:
+
+```json
+{ "__nutritionAccum": 0 }
+```
+
+> Note: `__nutritionAccum` was simplified to a scalar in v0.1.  If a `Map`
+> field is added in a future version, its pairs will use the array format above.
+
+### 2.4 Version stamping
+
+Always call `stampSnapshot(world, "world")` before persisting.  This adds
+`_ananke_version` and `_schema` fields that enable forward migration:
+
+```typescript
+import { stampSnapshot } from "@its-not-rocket-science/ananke/schema";
+// or: import { stampSnapshot } from "@ananke/core";   (when published)
+
+const save = JSON.stringify(stampSnapshot(world, "world"), null, 2);
+```
+
+### 2.5 JSON Schema files
+
+Canonical schemas ship with the package:
+
+| File | Validates |
+|------|-----------|
+| `schema/world.schema.json` | `WorldState` snapshots |
+| `schema/replay.schema.json` | `Replay` objects |
+
+Use `validateSnapshot(raw)` from `@its-not-rocket-science/ananke/schema` to
+check conformance programmatically before calling `stepWorld`.
+
+---
+
+## 3. Binary Diff Format
+
+For tick-to-tick state synchronisation (multiplayer, streaming), use the binary
+diff format implemented in `src/snapshot.ts`.
+
+### 3.1 Encoding
+
+```
+[magic: "ANKD" (4 bytes)] [version: 1 (u8)] [payload: tag-value stream]
+```
+
+Tag values:
+
+| Tag | Byte | Encodes |
+|-----|------|---------|
+| NULL | 0x00 | `null` |
+| TRUE | 0x01 | `true` |
+| FALSE | 0x02 | `false` |
+| UINT8 | 0x10 | Unsigned integer 0–255 |
+| INT32 | 0x11 | Signed 32-bit integer (big-endian) |
+| FLOAT64 | 0x12 | IEEE 754 double (big-endian) — use only for non-Q floats |
+| STRING | 0x20 | Length-prefixed UTF-8 |
+| ARRAY | 0x30 | Length-prefixed sequence of tag-value items |
+| OBJECT | 0x40 | Length-prefixed sequence of (string key, tag-value) pairs |
+
+### 3.2 Usage
+
+```typescript
+import { diffWorldState, packDiff, unpackDiff, applyDiff } from "@its-not-rocket-science/ananke";
+
+// Sender
+const diff   = diffWorldState(prevState, nextState);
+const bytes  = packDiff(diff);
+socket.send(bytes);
+
+// Receiver
+const diff2  = unpackDiff(bytes);
+const state2 = applyDiff(prevState, diff2);
+```
+
+### 3.3 Determinism guarantee
+
+A diff produced from identical states must produce identical bytes.  Do not
+include wall-clock timestamps or random nonces in diff payloads.
+
+---
+
+## 4. Multiplayer Message Protocol
+
+For lockstep multiplayer, hosts exchange command frames rather than full state.
+
+### 4.1 Message types
+
+| `kind` | Direction | Payload |
+|--------|-----------|---------|
+| `"cmd"` | Client → Server | `{ tick, commands: Command[] }` |
+| `"ack"` | Server → Client | `{ tick, stateHash: number }` |
+| `"resync"` | Server → Client | `{ tick, snapshot: WorldState }` |
+| `"hash_mismatch"` | Server → Client | `{ tick, expected: number, got: number }` |
+
+### 4.2 State hash
+
+Use the built-in tick counter and entity count as a cheap hash for divergence
+detection:
+
+```typescript
+function stateHash(world: WorldState): number {
+  return world.tick * 0x10000 + (world.entities.length & 0xFFFF);
+}
+```
+
+A full structural hash is more robust but expensive; use it only on resync.
+
+### 4.3 Lockstep loop
+
+```
+┌──────────────────────────────────────────────────────────┐
+│ Client                       Server                      │
+│                                                          │
+│ collect commands ──── cmd ──► apply to authoritative     │
+│                               state                      │
+│                   ◄── ack ─── broadcast stateHash        │
+│ verify hash                                              │
+│ if mismatch ─── resync req ─► send full snapshot        │
+│                ◄── resync ──                             │
+│ restore snapshot                                         │
+└──────────────────────────────────────────────────────────┘
+```
+
+### 4.4 Transport encoding
+
+Use JSON for development and debugging.  For production, encode wire messages
+as CBOR (RFC 8949) or MessagePack for ~30% size reduction.  The message
+structure is identical; only the outer encoding changes.
+
+---
+
+## 5. Save File Recommendations
+
+| Scenario | Format | Compression |
+|----------|--------|-------------|
+| Development / debugging | JSON (pretty-printed) | none |
+| Production saves | JSON (compact) | gzip or zstd |
+| Network sync (full state) | JSON or CBOR | none (already compact) |
+| Network sync (incremental) | Binary diff (`packDiff`) | none |
+| Replay archives | JSON replay schema | zstd |
+
+---
+
+## 6. Migration
+
+Load a save and bring it to the current schema version before simulating:
+
+```typescript
+import {
+  migrateWorld, validateSnapshot, stampSnapshot,
+} from "@its-not-rocket-science/ananke/schema";
+
+function loadSave(json: string): WorldState {
+  const raw      = JSON.parse(json) as Record<string, unknown>;
+  const migrated = migrateWorld(raw);          // no-op until 0.2 is released
+  const errors   = validateSnapshot(migrated);
+  if (errors.length > 0) {
+    throw new Error(`Invalid save: ${errors.map(e => `${e.path}: ${e.message}`).join("; ")}`);
+  }
+  return migrated as WorldState;
+}
+```
+
+See `docs/migration-monolith-to-modular.md` for package-level migration guidance.

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@its-not-rocket-science/ananke",
-  "version": "0.1.51",
+  "version": "0.1.53",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",
+  "bin": {
+    "ananke": "./dist/tools/pack-cli.js"
+  },
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",
   "exports": {
@@ -170,6 +173,14 @@
     "./monetary": {
       "import": "./dist/src/monetary.js",
       "types": "./dist/src/monetary.d.ts"
+    },
+    "./schema": {
+      "import": "./dist/src/schema-migration.js",
+      "types": "./dist/src/schema-migration.d.ts"
+    },
+    "./content-pack": {
+      "import": "./dist/src/content-pack.js",
+      "types": "./dist/src/content-pack.d.ts"
     }
   },
   "workspaces": [
@@ -187,6 +198,10 @@
     "docs/emergent-validation-report.md",
     "docs/package-architecture.md",
     "docs/migration-monolith-to-modular.md",
+    "docs/wire-protocol.md",
+    "schema/world.schema.json",
+    "schema/replay.schema.json",
+    "schema/pack.schema.json",
     "CHANGELOG.md",
     "STABLE_API.md"
   ],
@@ -232,6 +247,7 @@
     "example:campaign": "node dist/examples/quickstart-campaign.js",
     "example:species": "node dist/examples/quickstart-species.js",
     "generate-module-index": "node dist/tools/generate-module-index.js",
+    "pack": "node dist/tools/pack-cli.js pack",
     "generate-fixtures": "node dist/tools/generate-fixtures.js",
     "generate-zoo": "node dist/tools/generate-zoo.js",
     "generate-playground": "node dist/tools/generate-playground.js",

package/schema/pack.schema.json

@@ -0,0 +1,138 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://its-not-rocket-science.github.io/ananke/schema/pack.schema.json",
+  "title": "AnankePackManifest",
+  "description": "Ananke content pack manifest — a runtime-loadable bundle of weapons, armour, archetypes, and scenarios. Load with loadPack() from @its-not-rocket-science/ananke/content-pack.",
+  "type": "object",
+  "required": ["name", "version"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Link to this schema for editor validation."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Unique pack identifier (kebab-case recommended), e.g. \"weapons-medieval\"."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+(\\.\\d+)?$",
+      "description": "Semantic version, e.g. \"1.0.0\". Used as part of the packId \"name@version\"."
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable summary of pack contents."
+    },
+    "anankeVersion": {
+      "type": "string",
+      "description": "Minimum Ananke version required (semver range), e.g. \">=0.1\"."
+    },
+    "weapons": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/WeaponEntry" },
+      "description": "Weapon definitions — each registered via registerWeapon()."
+    },
+    "armour": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/ArmourEntry" },
+      "description": "Armour definitions — each registered via registerArmour()."
+    },
+    "archetypes": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/ArchetypeEntry" },
+      "description": "Archetype definitions — each registered via registerArchetype()."
+    },
+    "scenarios": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/Scenario" },
+      "description": "Scenario definitions — stored in the pack registry; instantiate with instantiatePackScenario()."
+    }
+  },
+  "unevaluatedProperties": true,
+  "$defs": {
+    "WeaponDamageProfile": {
+      "type": "object",
+      "required": ["surfaceFrac", "internalFrac", "structuralFrac", "bleedFactor", "penetrationBias"],
+      "properties": {
+        "surfaceFrac":     { "type": "number", "minimum": 0, "maximum": 1, "description": "Surface damage fraction [0, 1]." },
+        "internalFrac":    { "type": "number", "minimum": 0, "maximum": 1, "description": "Internal damage fraction [0, 1]." },
+        "structuralFrac":  { "type": "number", "minimum": 0, "maximum": 1, "description": "Structural (bone) damage fraction [0, 1]." },
+        "bleedFactor":     { "type": "number", "minimum": 0, "maximum": 1, "description": "Bleed factor [0, 1]." },
+        "penetrationBias": { "type": "number", "minimum": 0, "maximum": 1, "description": "Armour penetration bias [0, 1]." }
+      }
+    },
+    "WeaponEntry": {
+      "type": "object",
+      "required": ["id", "name", "mass_kg", "damage"],
+      "properties": {
+        "id":                       { "type": "string", "minLength": 1 },
+        "name":                     { "type": "string" },
+        "mass_kg":                  { "type": "number", "exclusiveMinimum": 0, "description": "Real-world mass in kilograms." },
+        "bulk":                     { "type": "number", "minimum": 0, "maximum": 1, "description": "Handling difficulty factor [0, 1]." },
+        "reach_m":                  { "type": "number", "exclusiveMinimum": 0, "description": "Strike reach in metres." },
+        "readyTime_s":              { "type": "number", "exclusiveMinimum": 0, "description": "Wind-up time in seconds." },
+        "handedness":               { "type": "string", "enum": ["oneHand", "twoHand", "mounted", "natural"] },
+        "strikeEffectiveMassFrac":  { "type": "number", "minimum": 0, "maximum": 1 },
+        "strikeSpeedMul":           { "type": "number", "minimum": 0 },
+        "handlingMul":              { "type": "number", "minimum": 0 },
+        "damage":                   { "$ref": "#/$defs/WeaponDamageProfile" }
+      },
+      "unevaluatedProperties": true
+    },
+    "ArmourEntry": {
+      "type": "object",
+      "required": ["id", "name", "mass_kg", "resist_J", "protectedDamageMul", "coverageByRegion"],
+      "properties": {
+        "id":                  { "type": "string", "minLength": 1 },
+        "name":                { "type": "string" },
+        "mass_kg":             { "type": "number", "exclusiveMinimum": 0, "description": "Real-world mass in kilograms." },
+        "bulk":                { "type": "number", "minimum": 0, "maximum": 1 },
+        "resist_J":            { "type": "number", "exclusiveMinimum": 0, "description": "Energy absorption capacity in real-world Joules." },
+        "protectedDamageMul":  { "type": "number", "minimum": 0, "maximum": 1, "description": "Damage multiplier applied when armour absorbs a hit [0, 1]." },
+        "coverageByRegion":    { "type": "object", "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 }, "description": "Region name → coverage fraction [0, 1]." },
+        "protects":            { "type": "array", "items": { "type": "string" }, "description": "Damage channel names this armour blocks, e.g. [\"Kinetic\", \"Thermal\"]." },
+        "mobilityMul":         { "type": "number", "minimum": 0 },
+        "fatigueMul":          { "type": "number", "minimum": 0 },
+        "reflectivity":        { "type": "number", "minimum": 0, "maximum": 1 },
+        "ablative":            { "type": "boolean" },
+        "insulation_m2KW":     { "type": "number", "minimum": 0 }
+      },
+      "unevaluatedProperties": true
+    },
+    "ArchetypeEntry": {
+      "type": "object",
+      "required": ["id"],
+      "properties": {
+        "id":        { "type": "string", "minLength": 1, "description": "Unique catalog id for this archetype." },
+        "base":      { "type": "string", "description": "Built-in base to inherit from: HUMAN_BASE, KNIGHT_INFANTRY, AMATEUR_BOXER, PRO_BOXER, GRECO_WRESTLER, etc." },
+        "overrides": { "type": "object", "description": "Field → real-world SI value overrides, e.g. {\"mass_kg\": 80, \"height_m\": 1.85}." }
+      },
+      "unevaluatedProperties": true
+    },
+    "ScenarioEntity": {
+      "type": "object",
+      "required": ["id", "teamId", "archetype", "weapon"],
+      "properties": {
+        "id":        { "type": "integer", "minimum": 1 },
+        "teamId":    { "type": "integer" },
+        "archetype": { "type": "string", "description": "Catalog archetype id." },
+        "weapon":    { "type": "string", "description": "Catalog weapon id." },
+        "armour":    { "type": "string", "description": "Catalog armour id (optional)." },
+        "x_m":       { "type": "number" },
+        "y_m":       { "type": "number" }
+      }
+    },
+    "Scenario": {
+      "type": "object",
+      "required": ["id", "seed", "maxTicks", "entities"],
+      "properties": {
+        "id":           { "type": "string", "minLength": 1 },
+        "seed":         { "type": "integer" },
+        "maxTicks":     { "type": "integer", "minimum": 1 },
+        "tractionCoeff": { "type": "number", "minimum": 0, "maximum": 1 },
+        "entities":     { "type": "array", "items": { "$ref": "#/$defs/ScenarioEntity" }, "minItems": 1 }
+      }
+    }
+  }
+}