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

package/CHANGELOG.md

@@ -6,6 +6,23 @@ 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

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/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;

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/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@its-not-rocket-science/ananke",
-  "version": "0.1.52",
+  "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": {
@@ -174,6 +177,10 @@
     "./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": [
@@ -194,6 +201,7 @@
     "docs/wire-protocol.md",
     "schema/world.schema.json",
     "schema/replay.schema.json",
+    "schema/pack.schema.json",
     "CHANGELOG.md",
     "STABLE_API.md"
   ],
@@ -239,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 }
+      }
+    }
+  }
+}