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

package/CHANGELOG.md

@@ -6,6 +6,38 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.53] — 2026-03-28
+
+### Added
+
+- **PA-4 — Scenario & Content Pack System (complete):**
+  - `src/content-pack.ts` (new): runtime `.ananke-pack` loader — `validatePack`, `loadPack`, `getPackScenario`, `instantiatePackScenario`, `listLoadedPacks`, `getLoadedPack`, `clearPackRegistry`. `loadPack` registers weapons/armour/archetypes into the global catalog AND into the world-factory extension tables so they are immediately usable in `loadScenario` scenarios.
+  - `src/world-factory.ts`: added `registerWorldArchetype`, `registerWorldItem`, `clearWorldExtensions` extension hooks so content packs can make their items available to `createWorld` / `loadScenario` without a source build.
+  - `schema/pack.schema.json` (new): JSON Schema 2020-12 for pack manifests (weapons, armour, archetypes, scenarios sections; full per-field documentation).
+  - `tools/pack-cli.ts` (new): `ananke pack validate <file>`, `ananke pack bundle <dir>`, `ananke pack load <file>`. Registered as `bin.ananke` in `package.json` so `npx ananke pack validate` works after install.
+  - `examples/packs/weapons-medieval.json`: 5 medieval weapons + 3 armours.
+  - `examples/packs/species-humanoids.json`: 4 humanoid archetype variants.
+  - `examples/packs/scenarios-duel.json`: 3 duel scenarios, self-contained with own archetypes and weapons.
+  - `"./content-pack"` subpath, `schema/pack.schema.json`, and `bin.ananke` added to `package.json`.
+- 32 new tests (184 test files, 5,332 tests total). Build: clean.
+
+---
+
+## [0.1.52] — 2026-03-28
+
+### Added
+
+- **PA-3 — Stable Schema, Save & Wire Contract (complete):**
+  - `src/schema-migration.ts` (new): schema versioning and migration utilities — `SCHEMA_VERSION`, `stampSnapshot`, `validateSnapshot` (returns `ValidationError[]` with JSONPath paths), `migrateWorld` (chains registered migrations; legacy saves treated as version `"0.0"`), `registerMigration`, `detectVersion`, `isValidSnapshot`.
+  - `schema/world.schema.json` (new): JSON Schema 2020-12 for `WorldState` — documents `@core` fields (`tick`, `seed`, `entities` with per-entity validation), `@subsystem` fields, and Q-value semantics.
+  - `schema/replay.schema.json` (new): JSON Schema 2020-12 for `Replay` / `ReplayFrame` / `Command`.
+  - `docs/wire-protocol.md` (new): Q-value serialisation rules (store raw integers, never divide by `SCALE.Q`), binary diff format (ANKD magic, tag-value encoding), multiplayer lockstep message types (`cmd`/`ack`/`resync`/`hash_mismatch`), save-format recommendations, and full load-with-migration code sample.
+  - `"./schema"` subpath added to `package.json` exports.
+  - `schema/` directory and `docs/wire-protocol.md` added to `package.json` `"files"`.
+- 39 new tests (183 test files, 5,300 tests total). Build: clean.
+
+---
+
 ## [0.1.51] — 2026-03-28
 
 ### Added

package/dist/src/content-pack.d.ts

@@ -0,0 +1,105 @@
+import type { WorldState } from "./sim/world.js";
+/** A single actionable validation failure from `validatePack`. */
+export interface PackValidationError {
+    /** JSONPath-style location, e.g. `"$.weapons[2].mass_kg"`. */
+    path: string;
+    /** Human-readable explanation of what is wrong. */
+    message: string;
+}
+/**
+ * The `.ananke-pack` manifest schema.
+ *
+ * All numeric fields in `weapons`, `armour`, and `archetypes` use real-world
+ * SI units (kg, m, J, s) and Q ratios in [0, 1].  See `docs/wire-protocol.md`
+ * for the full serialisation contract.
+ */
+export interface AnankePackManifest {
+    /** Optional link to `schema/pack.schema.json` for editor tooling. */
+    $schema?: string;
+    /** Unique pack name (kebab-case recommended), e.g. `"weapons-medieval"`. */
+    name: string;
+    /** Semantic version string, e.g. `"1.0.0"`. */
+    version: string;
+    /** Human-readable summary. */
+    description?: string;
+    /**
+     * Minimum Ananke version required, as a semver range string.
+     * Used for documentation only — not enforced at runtime in v0.1.
+     */
+    anankeVersion?: string;
+    /** Weapon definitions — each passed to `registerWeapon`. */
+    weapons?: unknown[];
+    /** Armour definitions — each passed to `registerArmour`. */
+    armour?: unknown[];
+    /** Archetype definitions — each passed to `registerArchetype`. */
+    archetypes?: unknown[];
+    /**
+     * Scenario definitions — stored in the pack registry and retrievable via
+     * `getPackScenario`.  NOT loaded into the catalog (scenarios have no global
+     * registry); instantiate on demand with `instantiatePackScenario`.
+     */
+    scenarios?: unknown[];
+}
+/** Result of a `loadPack` call. */
+export interface LoadPackResult {
+    /**
+     * Canonical pack identifier: `"${name}@${version}"`.
+     * Use this as the first argument to `getPackScenario`.
+     */
+    packId: string;
+    /**
+     * IDs of all catalog entries registered, prefixed by kind.
+     * e.g. `["weapon:medieval_longsword", "armour:medieval_gambeson"]`.
+     */
+    registeredIds: string[];
+    /** IDs of all scenarios stored in the pack registry. */
+    scenarioIds: string[];
+    /** 8-character hex fingerprint of the manifest (FNV-1a over canonical JSON). */
+    fingerprint: string;
+    /** Validation and registration errors.  Empty on full success. */
+    errors: PackValidationError[];
+}
+/**
+ * Validate a pack manifest for structural conformance without loading it.
+ *
+ * Checks required top-level fields, array element shapes, and runs
+ * `validateScenario` on each scenario entry.
+ *
+ * @returns Array of `PackValidationError`.  Empty means valid.
+ */
+export declare function validatePack(manifest: unknown): PackValidationError[];
+/**
+ * Validate and load a pack manifest into the active catalogues.
+ *
+ * - Weapons, armour, and archetypes are registered into the global catalog.
+ * - Scenarios are stored in the pack registry; retrieve with `getPackScenario`.
+ * - If `validatePack` reports errors the pack is NOT loaded and `errors` is
+ *   populated in the result.
+ * - Loading a pack with the same `name@version` id a second time is a no-op
+ *   (returns the original result with `errors` empty).
+ */
+export declare function loadPack(manifest: AnankePackManifest): LoadPackResult;
+/** Returns the pack registry entry for a previously-loaded pack, or `undefined`. */
+export declare function getLoadedPack(packId: string): LoadPackResult | undefined;
+/** Returns the `"name@version"` ids of all currently loaded packs. */
+export declare function listLoadedPacks(): string[];
+/**
+ * Returns the raw scenario JSON stored in a pack.
+ *
+ * @param packId    — `"name@version"` as returned by `loadPack`.
+ * @param scenarioId — the scenario's `id` field.
+ */
+export declare function getPackScenario(packId: string, scenarioId: string): unknown | undefined;
+/**
+ * Instantiate a packed scenario into a live `WorldState`.
+ *
+ * Equivalent to `loadScenario(getPackScenario(packId, scenarioId))`.
+ * Throws if the pack or scenario does not exist.
+ */
+export declare function instantiatePackScenario(packId: string, scenarioId: string): WorldState;
+/**
+ * Remove all entries from the pack registry.
+ * Does NOT un-register catalog entries — call `clearCatalog()` separately if needed.
+ * Primarily for testing.
+ */
+export declare function clearPackRegistry(): void;

package/dist/src/content-pack.js

@@ -0,0 +1,261 @@
+// src/content-pack.ts — PA-4: Scenario & Content Pack System
+//
+// Runtime loader for `.ananke-pack` JSON manifests.  A content pack can
+// add weapons, armour, archetypes, and scenarios to the active catalogues
+// without touching source code.
+//
+// Integration pattern:
+//   const manifest = JSON.parse(fs.readFileSync("weapons-medieval.json", "utf8"));
+//   const result   = loadPack(manifest);
+//   if (result.errors.length > 0) throw new Error(result.errors[0]!.message);
+//   // catalog now contains the new weapons
+import { registerWeapon, registerArmour, registerArchetype } from "./catalog.js";
+import { validateScenario, loadScenario } from "./scenario.js";
+import { hashMod } from "./modding.js";
+import { registerWorldArchetype, registerWorldItem } from "./world-factory.js";
+const _packs = new Map();
+// ── Validation ────────────────────────────────────────────────────────────────
+/**
+ * Validate a pack manifest for structural conformance without loading it.
+ *
+ * Checks required top-level fields, array element shapes, and runs
+ * `validateScenario` on each scenario entry.
+ *
+ * @returns Array of `PackValidationError`.  Empty means valid.
+ */
+export function validatePack(manifest) {
+    const errors = [];
+    if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest)) {
+        errors.push({ path: "$", message: "pack manifest must be a plain object" });
+        return errors;
+    }
+    const m = manifest;
+    // Required: name
+    if (typeof m["name"] !== "string" || m["name"].trim() === "") {
+        errors.push({ path: "$.name", message: "must be a non-empty string" });
+    }
+    // Required: version (semver-ish)
+    if (typeof m["version"] !== "string" ||
+        !/^\d+\.\d+(\.\d+)?$/.test(m["version"])) {
+        errors.push({ path: "$.version", message: 'must be a semver string like "1.0.0" or "1.0"' });
+    }
+    // Optional arrays — must be arrays if present
+    for (const key of ["weapons", "armour", "archetypes", "scenarios"]) {
+        if (m[key] !== undefined && !Array.isArray(m[key])) {
+            errors.push({ path: `$.${key}`, message: "must be an array if present" });
+        }
+    }
+    // Validate weapon entries
+    if (Array.isArray(m["weapons"])) {
+        for (let i = 0; i < m["weapons"].length; i++) {
+            const w = m["weapons"][i];
+            errors.push(...validateWeaponEntry(w, i));
+        }
+    }
+    // Validate armour entries
+    if (Array.isArray(m["armour"])) {
+        for (let i = 0; i < m["armour"].length; i++) {
+            const a = m["armour"][i];
+            errors.push(...validateArmourEntry(a, i));
+        }
+    }
+    // Validate archetype entries (minimal — full validation is in registerArchetype)
+    if (Array.isArray(m["archetypes"])) {
+        for (let i = 0; i < m["archetypes"].length; i++) {
+            const arch = m["archetypes"][i];
+            if (typeof arch !== "object" || arch === null) {
+                errors.push({ path: `$.archetypes[${i}]`, message: "must be an object" });
+                continue;
+            }
+            const o = arch;
+            if (typeof o["id"] !== "string" || o["id"].trim() === "") {
+                errors.push({ path: `$.archetypes[${i}].id`, message: "must be a non-empty string" });
+            }
+        }
+    }
+    // Validate scenario entries via existing validateScenario
+    if (Array.isArray(m["scenarios"])) {
+        for (let i = 0; i < m["scenarios"].length; i++) {
+            const scenErrors = validateScenario(m["scenarios"][i]);
+            for (const msg of scenErrors) {
+                errors.push({ path: `$.scenarios[${i}]`, message: msg });
+            }
+        }
+    }
+    return errors;
+}
+function validateWeaponEntry(w, i) {
+    const errors = [];
+    if (typeof w !== "object" || w === null) {
+        errors.push({ path: `$.weapons[${i}]`, message: "must be an object" });
+        return errors;
+    }
+    const o = w;
+    if (typeof o["id"] !== "string" || o["id"].trim() === "") {
+        errors.push({ path: `$.weapons[${i}].id`, message: "must be a non-empty string" });
+    }
+    if (typeof o["name"] !== "string") {
+        errors.push({ path: `$.weapons[${i}].name`, message: "must be a string" });
+    }
+    if (typeof o["mass_kg"] !== "number" || o["mass_kg"] <= 0) {
+        errors.push({ path: `$.weapons[${i}].mass_kg`, message: "must be a positive number (real-world kg)" });
+    }
+    if (typeof o["damage"] !== "object" || o["damage"] === null) {
+        errors.push({ path: `$.weapons[${i}].damage`, message: "must be an object" });
+    }
+    return errors;
+}
+function validateArmourEntry(a, i) {
+    const errors = [];
+    if (typeof a !== "object" || a === null) {
+        errors.push({ path: `$.armour[${i}]`, message: "must be an object" });
+        return errors;
+    }
+    const o = a;
+    if (typeof o["id"] !== "string" || o["id"].trim() === "") {
+        errors.push({ path: `$.armour[${i}].id`, message: "must be a non-empty string" });
+    }
+    if (typeof o["name"] !== "string") {
+        errors.push({ path: `$.armour[${i}].name`, message: "must be a string" });
+    }
+    if (typeof o["mass_kg"] !== "number" || o["mass_kg"] <= 0) {
+        errors.push({ path: `$.armour[${i}].mass_kg`, message: "must be a positive number (real-world kg)" });
+    }
+    if (typeof o["resist_J"] !== "number" || o["resist_J"] <= 0) {
+        errors.push({ path: `$.armour[${i}].resist_J`, message: "must be a positive number (real-world Joules)" });
+    }
+    return errors;
+}
+// ── Load ──────────────────────────────────────────────────────────────────────
+/**
+ * Validate and load a pack manifest into the active catalogues.
+ *
+ * - Weapons, armour, and archetypes are registered into the global catalog.
+ * - Scenarios are stored in the pack registry; retrieve with `getPackScenario`.
+ * - If `validatePack` reports errors the pack is NOT loaded and `errors` is
+ *   populated in the result.
+ * - Loading a pack with the same `name@version` id a second time is a no-op
+ *   (returns the original result with `errors` empty).
+ */
+export function loadPack(manifest) {
+    const packId = `${manifest.name}@${manifest.version}`;
+    // Already loaded — return stored summary
+    const existing = _packs.get(packId);
+    if (existing !== undefined) {
+        return {
+            packId,
+            registeredIds: existing.registeredIds,
+            scenarioIds: existing.scenarioIds,
+            fingerprint: existing.fingerprint,
+            errors: [],
+        };
+    }
+    // Validate first
+    const errors = validatePack(manifest);
+    if (errors.length > 0) {
+        return { packId, registeredIds: [], scenarioIds: [], fingerprint: "", errors };
+    }
+    const registeredIds = [];
+    const loadErrors = [];
+    // Register weapons — into both the catalog and the world-factory lookup table
+    for (const w of manifest.weapons ?? []) {
+        try {
+            const weapon = registerWeapon(w);
+            const id = weapon.id;
+            registerWorldItem(id, weapon);
+            registeredIds.push(`weapon:${id}`);
+        }
+        catch (e) {
+            loadErrors.push({ path: "$.weapons", message: String(e) });
+        }
+    }
+    // Register armour — into both the catalog and the world-factory lookup table
+    for (const a of manifest.armour ?? []) {
+        try {
+            const armour = registerArmour(a);
+            const id = armour.id;
+            registerWorldItem(id, armour);
+            registeredIds.push(`armour:${id}`);
+        }
+        catch (e) {
+            loadErrors.push({ path: "$.armour", message: String(e) });
+        }
+    }
+    // Register archetypes — into both the catalog and the world-factory lookup table
+    for (const arch of manifest.archetypes ?? []) {
+        try {
+            const archetype = registerArchetype(arch);
+            const id = arch["id"];
+            registerWorldArchetype(id, archetype);
+            registeredIds.push(`archetype:${id}`);
+        }
+        catch (e) {
+            loadErrors.push({ path: "$.archetypes", message: String(e) });
+        }
+    }
+    // Store scenarios (not in global catalog — retrieved on demand)
+    const scenarioMap = new Map();
+    const scenarioIds = [];
+    for (const scen of manifest.scenarios ?? []) {
+        const id = scen["id"];
+        scenarioMap.set(id, scen);
+        scenarioIds.push(id);
+    }
+    const fingerprint = hashMod(manifest);
+    _packs.set(packId, {
+        manifest,
+        registeredIds,
+        scenarioIds,
+        fingerprint,
+        scenarios: scenarioMap,
+    });
+    return { packId, registeredIds, scenarioIds, fingerprint, errors: loadErrors };
+}
+// ── Query API ─────────────────────────────────────────────────────────────────
+/** Returns the pack registry entry for a previously-loaded pack, or `undefined`. */
+export function getLoadedPack(packId) {
+    const e = _packs.get(packId);
+    if (e === undefined)
+        return undefined;
+    return {
+        packId,
+        registeredIds: e.registeredIds,
+        scenarioIds: e.scenarioIds,
+        fingerprint: e.fingerprint,
+        errors: [],
+    };
+}
+/** Returns the `"name@version"` ids of all currently loaded packs. */
+export function listLoadedPacks() {
+    return [..._packs.keys()];
+}
+/**
+ * Returns the raw scenario JSON stored in a pack.
+ *
+ * @param packId    — `"name@version"` as returned by `loadPack`.
+ * @param scenarioId — the scenario's `id` field.
+ */
+export function getPackScenario(packId, scenarioId) {
+    return _packs.get(packId)?.scenarios.get(scenarioId);
+}
+/**
+ * Instantiate a packed scenario into a live `WorldState`.
+ *
+ * Equivalent to `loadScenario(getPackScenario(packId, scenarioId))`.
+ * Throws if the pack or scenario does not exist.
+ */
+export function instantiatePackScenario(packId, scenarioId) {
+    const scen = getPackScenario(packId, scenarioId);
+    if (scen === undefined) {
+        throw new Error(`instantiatePackScenario: scenario "${scenarioId}" not found in pack "${packId}"`);
+    }
+    return loadScenario(scen);
+}
+/**
+ * Remove all entries from the pack registry.
+ * Does NOT un-register catalog entries — call `clearCatalog()` separately if needed.
+ * Primarily for testing.
+ */
+export function clearPackRegistry() {
+    _packs.clear();
+}

package/dist/src/schema-migration.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Current schema major.minor version.
+ *
+ * Patch releases (0.1.x → 0.1.y) never change the schema.
+ * Minor releases (0.1.x → 0.2.0) may add optional fields (non-breaking).
+ * Major releases (0.x → 1.0.0) may alter required fields (breaking; migration required).
+ */
+export declare const SCHEMA_VERSION = "0.1";
+/** Schema discrimination tag added by `stampSnapshot`. */
+export type SchemaKind = "world" | "replay" | "campaign";
+/**
+ * Metadata fields stamped onto a persisted snapshot.
+ * Present on any object returned by `stampSnapshot`.
+ */
+export interface VersionedSnapshot {
+    /** Schema version at save time, e.g. `"0.1"`. */
+    _ananke_version: string;
+    /** Which schema this snapshot conforms to. */
+    _schema: SchemaKind;
+}
+/**
+ * A single actionable validation failure.
+ *
+ * `path` uses JSONPath dot-notation, e.g. `"$.entities[2].id"`.
+ */
+export interface ValidationError {
+    path: string;
+    message: string;
+}
+/**
+ * Add `_ananke_version` and `_schema` metadata to a snapshot before persisting.
+ *
+ * Does not mutate the original object.
+ *
+ * @example
+ * const save = JSON.stringify(stampSnapshot(world, "world"));
+ */
+export declare function stampSnapshot<T extends Record<string, unknown>>(snapshot: T, schema: SchemaKind): T & VersionedSnapshot;
+/**
+ * Check structural conformance of a deserialized world snapshot.
+ *
+ * Validates only the `@core` fields that `stepWorld` requires.  Subsystem
+ * fields are not validated — unknown extra fields are silently permitted
+ * (hosts may attach extension data).
+ *
+ * @returns An array of `ValidationError`.  An empty array means valid.
+ */
+export declare function validateSnapshot(snapshot: unknown): ValidationError[];
+type MigrationFn = (snapshot: Record<string, unknown>) => Record<string, unknown>;
+/**
+ * Register a migration function between two schema versions.
+ *
+ * Migrations are chained automatically when `migrateWorld` is called.
+ * For a simple non-breaking addition, the migration only needs to add
+ * default values for the new fields.
+ *
+ * @example
+ * registerMigration("0.1", "0.2", snap => ({
+ *   ...snap,
+ *   __newField: snap["__newField"] ?? 0,
+ * }));
+ */
+export declare function registerMigration(fromVersion: string, toVersion: string, fn: MigrationFn): void;
+/**
+ * Migrate a deserialized world snapshot to `toVersion` (default: current `SCHEMA_VERSION`).
+ *
+ * - If the snapshot already carries `_ananke_version === toVersion`, it is returned unchanged.
+ * - Legacy snapshots without `_ananke_version` are treated as version `"0.0"`.
+ * - Throws a descriptive error when no registered migration path exists.
+ *
+ * The snapshot is not mutated; a new object is returned.
+ *
+ * @example
+ * const raw   = JSON.parse(fs.readFileSync("save.json", "utf8"));
+ * const world = migrateWorld(raw) as WorldState;
+ */
+export declare function migrateWorld(snapshot: Record<string, unknown>, toVersion?: string): Record<string, unknown>;
+/**
+ * Read the `_ananke_version` stamp from a deserialized snapshot.
+ * Returns `undefined` for legacy snapshots saved before PA-3.
+ */
+export declare function detectVersion(snapshot: unknown): string | undefined;
+/**
+ * Returns `true` when the snapshot carries a valid version stamp and passes
+ * structural validation (no `ValidationError` entries).
+ *
+ * Convenience wrapper for `detectVersion` + `validateSnapshot`.
+ */
+export declare function isValidSnapshot(snapshot: unknown): boolean;
+export {};

package/dist/src/schema-migration.js

@@ -0,0 +1,162 @@
+// src/schema-migration.ts — PA-3: Stable Schema, Save & Wire Contract
+//
+// Provides schema versioning, structural validation, and migration utilities
+// for WorldState snapshots, Campaign saves, and Replay files.
+//
+// Usage pattern:
+//   const raw = JSON.parse(saveFile);
+//   const migrated = migrateWorld(raw);
+//   const errors = validateSnapshot(migrated);
+//   if (errors.length === 0) stepWorld(migrated as WorldState, commands);
+// ── Version ───────────────────────────────────────────────────────────────────
+/**
+ * Current schema major.minor version.
+ *
+ * Patch releases (0.1.x → 0.1.y) never change the schema.
+ * Minor releases (0.1.x → 0.2.0) may add optional fields (non-breaking).
+ * Major releases (0.x → 1.0.0) may alter required fields (breaking; migration required).
+ */
+export const SCHEMA_VERSION = "0.1";
+// ── Stamp ─────────────────────────────────────────────────────────────────────
+/**
+ * Add `_ananke_version` and `_schema` metadata to a snapshot before persisting.
+ *
+ * Does not mutate the original object.
+ *
+ * @example
+ * const save = JSON.stringify(stampSnapshot(world, "world"));
+ */
+export function stampSnapshot(snapshot, schema) {
+    return {
+        ...snapshot,
+        _ananke_version: SCHEMA_VERSION,
+        _schema: schema,
+    };
+}
+// ── Validate ──────────────────────────────────────────────────────────────────
+/**
+ * Check structural conformance of a deserialized world snapshot.
+ *
+ * Validates only the `@core` fields that `stepWorld` requires.  Subsystem
+ * fields are not validated — unknown extra fields are silently permitted
+ * (hosts may attach extension data).
+ *
+ * @returns An array of `ValidationError`.  An empty array means valid.
+ */
+export function validateSnapshot(snapshot) {
+    const errors = [];
+    if (typeof snapshot !== "object" || snapshot === null || Array.isArray(snapshot)) {
+        errors.push({ path: "$", message: "must be a plain object" });
+        return errors;
+    }
+    const s = snapshot;
+    // tick
+    if (typeof s["tick"] !== "number" || !Number.isInteger(s["tick"]) || s["tick"] < 0) {
+        errors.push({ path: "$.tick", message: "must be a non-negative integer" });
+    }
+    // seed
+    if (typeof s["seed"] !== "number" || !Number.isInteger(s["seed"])) {
+        errors.push({ path: "$.seed", message: "must be an integer" });
+    }
+    // entities
+    if (!Array.isArray(s["entities"])) {
+        errors.push({ path: "$.entities", message: "must be an array" });
+    }
+    else {
+        for (let i = 0; i < s["entities"].length; i++) {
+            const e = s["entities"][i];
+            if (typeof e !== "object" || e === null || Array.isArray(e)) {
+                errors.push({ path: `$.entities[${i}]`, message: "must be a plain object" });
+                continue;
+            }
+            const ent = e;
+            if (typeof ent["id"] !== "number" || !Number.isInteger(ent["id"]) || ent["id"] < 0) {
+                errors.push({ path: `$.entities[${i}].id`, message: "must be a non-negative integer" });
+            }
+            if (typeof ent["teamId"] !== "number" || !Number.isInteger(ent["teamId"])) {
+                errors.push({ path: `$.entities[${i}].teamId`, message: "must be an integer" });
+            }
+            if (typeof ent["attributes"] !== "object" || ent["attributes"] === null) {
+                errors.push({ path: `$.entities[${i}].attributes`, message: "must be an object" });
+            }
+            if (typeof ent["energy"] !== "object" || ent["energy"] === null) {
+                errors.push({ path: `$.entities[${i}].energy`, message: "must be an object" });
+            }
+            if (typeof ent["loadout"] !== "object" || ent["loadout"] === null) {
+                errors.push({ path: `$.entities[${i}].loadout`, message: "must be an object" });
+            }
+            if (!Array.isArray(ent["traits"])) {
+                errors.push({ path: `$.entities[${i}].traits`, message: "must be an array" });
+            }
+        }
+    }
+    return errors;
+}
+/** Internal registry: `"from->to"` → migration function. */
+const MIGRATIONS = new Map();
+/**
+ * Register a migration function between two schema versions.
+ *
+ * Migrations are chained automatically when `migrateWorld` is called.
+ * For a simple non-breaking addition, the migration only needs to add
+ * default values for the new fields.
+ *
+ * @example
+ * registerMigration("0.1", "0.2", snap => ({
+ *   ...snap,
+ *   __newField: snap["__newField"] ?? 0,
+ * }));
+ */
+export function registerMigration(fromVersion, toVersion, fn) {
+    MIGRATIONS.set(`${fromVersion}->${toVersion}`, fn);
+}
+/**
+ * Migrate a deserialized world snapshot to `toVersion` (default: current `SCHEMA_VERSION`).
+ *
+ * - If the snapshot already carries `_ananke_version === toVersion`, it is returned unchanged.
+ * - Legacy snapshots without `_ananke_version` are treated as version `"0.0"`.
+ * - Throws a descriptive error when no registered migration path exists.
+ *
+ * The snapshot is not mutated; a new object is returned.
+ *
+ * @example
+ * const raw   = JSON.parse(fs.readFileSync("save.json", "utf8"));
+ * const world = migrateWorld(raw) as WorldState;
+ */
+export function migrateWorld(snapshot, toVersion = SCHEMA_VERSION) {
+    const fromVersion = typeof snapshot["_ananke_version"] === "string"
+        ? snapshot["_ananke_version"]
+        : "0.0";
+    if (fromVersion === toVersion)
+        return snapshot;
+    const key = `${fromVersion}->${toVersion}`;
+    const fn = MIGRATIONS.get(key);
+    if (fn === undefined) {
+        const known = [...MIGRATIONS.keys()];
+        throw new Error(`No migration from schema ${fromVersion} to ${toVersion}.` +
+            (known.length > 0 ? ` Registered paths: ${known.join(", ")}` : " No migrations registered."));
+    }
+    return fn(snapshot);
+}
+// ── Utilities ─────────────────────────────────────────────────────────────────
+/**
+ * Read the `_ananke_version` stamp from a deserialized snapshot.
+ * Returns `undefined` for legacy snapshots saved before PA-3.
+ */
+export function detectVersion(snapshot) {
+    if (typeof snapshot !== "object" || snapshot === null)
+        return undefined;
+    const v = snapshot["_ananke_version"];
+    return typeof v === "string" ? v : undefined;
+}
+/**
+ * Returns `true` when the snapshot carries a valid version stamp and passes
+ * structural validation (no `ValidationError` entries).
+ *
+ * Convenience wrapper for `detectVersion` + `validateSnapshot`.
+ */
+export function isValidSnapshot(snapshot) {
+    if (detectVersion(snapshot) === undefined)
+        return false;
+    return validateSnapshot(snapshot).length === 0;
+}

package/dist/src/world-factory.d.ts

@@ -12,6 +12,22 @@ import type { WorldState } from "./sim/world.js";
 export declare const ARCHETYPE_MAP: ReadonlyMap<string, Archetype>;
 /** Map of item id → Item for weapons and armour usable with createWorld(). */
 export declare const ITEM_MAP: ReadonlyMap<string, Item>;
+/**
+ * Register an archetype so it is resolvable by `createWorld` and `loadScenario`.
+ * Called automatically by `loadPack` in `content-pack.ts`.
+ */
+export declare function registerWorldArchetype(id: string, archetype: Archetype): void;
+/**
+ * Register a weapon or armour so it is resolvable by `createWorld` and `loadScenario`.
+ * Called automatically by `loadPack` in `content-pack.ts`.
+ */
+export declare function registerWorldItem(id: string, item: Item): void;
+/**
+ * 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 declare function clearWorldExtensions(): void;
 export interface EntitySpec {
     id: number;
     teamId: number;