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

package/CHANGELOG.md

@@ -6,6 +6,38 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.54] — 2026-03-28
+
+### Added
+
+- **PA-5 — Campaign ↔ Tactical Terrain Bridge (complete):**
+  - `src/terrain-bridge.ts` (new): maps campaign hex tiles to tactical battlefield parameters consumable by `KernelContext`, and merges tactical battle results back into `CampaignState`.
+  - `extractTerrainParams(hexType)` → deterministic 10×8-cell (100 m × 80 m) battlefield with `TerrainGrid`, `ObstacleGrid`, `ElevationGrid`, `SlopeGrid`, and `CoverSegment[]` for all 8 hex types: `plains`, `forest`, `hills`, `marsh`, `urban`, `mountain`, `river_crossing`, `coastal`.
+  - `generateBattleSite(ctx)` → full `BattleTerrainParams` including `EntryVector[]` — attacker/defender spawn positions (y=5 m south, y=75 m north) with `facingY` direction.
+  - `mergeBattleOutcome(campaign, outcome)` → merges post-battle `WorldState` into `CampaignState`: removes `injury.dead` entities, copies post-battle `injury`/`condition` onto survivors, transfers looted weapons/items from captured entities to winner's inventory, advances `worldTime_s`, appends a log entry.
+  - Exports: `CampaignHexType`, `EntryVector`, `BattleTerrainParams`, `BattleSiteContext`, `BattleOutcome`; field constants `FIELD_WIDTH_Sm`, `FIELD_HEIGHT_Sm`, `CELL_SIZE_Sm`, `GRID_COLS`, `GRID_ROWS`.
+  - `"./terrain-bridge"` subpath export added to `package.json`.
+- 67 new tests (185 test files, 5,397 tests total). Coverage: 97.05% stmt, 87.88% branch, 95.75% func, 97.05% lines. Build: clean.
+
+---
+
+## [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/terrain-bridge.d.ts

@@ -0,0 +1,161 @@
+import { type I32 } from "./units.js";
+import { type TerrainGrid, type ObstacleGrid, type ElevationGrid, type SlopeGrid, type SurfaceType } from "./sim/terrain.js";
+import { type CoverSegment } from "./sim/cover.js";
+import type { CampaignState } from "./campaign.js";
+import type { WorldState } from "./sim/world.js";
+/** Battlefield width [SCALE.m]. 100 m. */
+export declare const FIELD_WIDTH_Sm: I32;
+/** Battlefield depth [SCALE.m]. 80 m. */
+export declare const FIELD_HEIGHT_Sm: I32;
+/** Terrain cell size [SCALE.m]. 10 m per cell → 10 × 8 grid. */
+export declare const CELL_SIZE_Sm: I32;
+/** Number of grid columns (field width / cell size). */
+export declare const GRID_COLS = 10;
+/** Number of grid rows (field height / cell size). */
+export declare const GRID_ROWS = 8;
+/** Attacker spawn y [SCALE.m] — 5 m from the south (y=0) edge. */
+export declare const ATTACKER_SPAWN_Y_Sm: I32;
+/** Defender spawn y [SCALE.m] — 5 m from the north edge. */
+export declare const DEFENDER_SPAWN_Y_Sm: I32;
+/**
+ * Campaign map tile type.
+ *
+ * Each hex type produces a distinct battlefield layout — surface type, cover
+ * density, elevation profile, and obstacle placement.
+ */
+export type CampaignHexType = "plains" | "forest" | "hills" | "marsh" | "urban" | "mountain" | "river_crossing" | "coastal";
+/**
+ * Initial spawn position and facing for one team entering the battlefield.
+ *
+ * Attackers (south-entry) have `facingY: 1` (moving toward increasing y).
+ * Defenders (north-entry) have `facingY: -1`.
+ */
+export interface EntryVector {
+    /** Team identifier matching `entity.teamId`. */
+    teamId: number;
+    /** Spawn x-coordinate [SCALE.m]. */
+    x_Sm: number;
+    /** Spawn y-coordinate [SCALE.m]. */
+    y_Sm: number;
+    /**
+     * Initial movement direction along the y-axis.
+     * `1`  = attacker advancing north.
+     * `-1` = defender holding or advancing south.
+     */
+    facingY: 1 | -1;
+}
+/**
+ * Complete tactical battlefield specification derived from a campaign hex encounter.
+ *
+ * ## Integration
+ * ```ts
+ * const site = generateBattleSite({ hexType: "forest", ... });
+ * const ctx: KernelContext = {
+ *   tractionCoeff: SURFACE_TRACTION[site.dominantSurface],
+ *   cellSize_m:    site.cellSize_Sm,
+ *   terrainGrid:   site.terrainGrid,
+ *   obstacleGrid:  site.obstacleGrid,
+ *   elevationGrid: site.elevationGrid,
+ *   slopeGrid:     site.slopeGrid,
+ * };
+ * // Position entities at site.entryVectors[n].x_Sm / y_Sm before first stepWorld.
+ * ```
+ */
+export interface BattleTerrainParams {
+    /** Total battlefield width [SCALE.m]. */
+    width_Sm: number;
+    /** Total battlefield depth [SCALE.m]. */
+    height_Sm: number;
+    /** Cell size used for terrain grid lookups [SCALE.m]. */
+    cellSize_Sm: number;
+    /** Per-cell surface type — pass to `KernelContext.terrainGrid`. */
+    terrainGrid: TerrainGrid;
+    /** Per-cell cover fraction — pass to `KernelContext.obstacleGrid`. */
+    obstacleGrid: ObstacleGrid;
+    /** Per-cell elevation above ground [SCALE.m] — pass to `KernelContext.elevationGrid`. */
+    elevationGrid: ElevationGrid;
+    /** Per-cell slope direction and grade — pass to `KernelContext.slopeGrid`. */
+    slopeGrid: SlopeGrid;
+    /** Structural cover segments to place in the world before battle begins. */
+    coverSegments: CoverSegment[];
+    /** Entry spawn positions for each team. */
+    entryVectors: EntryVector[];
+    /**
+     * Dominant surface type — use `SURFACE_TRACTION[dominantSurface]` as
+     * the default `KernelContext.tractionCoeff`.
+     */
+    dominantSurface: SurfaceType;
+}
+/**
+ * Context provided to `generateBattleSite`.
+ */
+export interface BattleSiteContext {
+    /** Campaign hex tile where the battle occurs. */
+    hexType: CampaignHexType;
+    /** Attacking team ids — they enter from the south (y ≈ 0). */
+    attackerTeamIds: number[];
+    /** Defending team ids — they enter from the north (y ≈ FIELD_HEIGHT). */
+    defenderTeamIds: number[];
+    /**
+     * World seed from the campaign — reserved for future micro-variance.
+     * Currently unused but forwarded for determinism documentation purposes.
+     */
+    seed?: number;
+}
+/**
+ * Outcome produced by the tactical simulation, passed to `mergeBattleOutcome`.
+ */
+export interface BattleOutcome {
+    /** Final `WorldState` after the tactical battle ends. */
+    worldState: WorldState;
+    /**
+     * Battle duration in simulated seconds, added to `CampaignState.worldTime_s`.
+     */
+    elapsedSeconds: number;
+    /**
+     * Entity ids of combatants incapacitated or captured on the losing side.
+     * Their weapons and armour will be transferred to the winning team's inventory.
+     */
+    capturedEntityIds?: number[];
+    /**
+     * Team id of the victorious side.  When `undefined` the battle is a draw and
+     * no equipment transfer occurs.
+     */
+    winnerTeamId?: number;
+}
+/**
+ * Build terrain, obstacle, elevation, and slope grids for a campaign hex type.
+ *
+ * Fully deterministic — produces the same output for the same `hexType` every
+ * call.  Does not include `entryVectors`; use `generateBattleSite` for a full
+ * site including team spawn positions.
+ *
+ * Grid layout: 10 columns × 8 rows, each cell 10 m (100 000 SCALE.m).
+ * Total field: 100 m wide × 80 m deep.
+ */
+export declare function extractTerrainParams(hexType: CampaignHexType): Omit<BattleTerrainParams, "entryVectors">;
+/**
+ * Generate a complete battle site for a campaign encounter.
+ *
+ * Calls `extractTerrainParams` and appends `EntryVector` entries for each
+ * attacking and defending team.
+ *
+ * Teams with more than three members reuse spawn positions (cyclic).
+ */
+export declare function generateBattleSite(ctx: BattleSiteContext): BattleTerrainParams;
+/**
+ * Merge a completed tactical battle back into campaign state.
+ *
+ * **What this does:**
+ * - Advances `campaign.worldTime_s` by `outcome.elapsedSeconds`.
+ * - Removes entities that died in battle (`injury.dead === true`) from the
+ *   campaign entity registry, location map, and inventory map.
+ * - Copies post-battle `injury` and `condition` state onto surviving campaign
+ *   entities so wounds persist between encounters.
+ * - Transfers weapons and armour from `capturedEntityIds` to the winning
+ *   team's first surviving entity inventory (item id → count).
+ * - Appends a human-readable battle summary to `campaign.log`.
+ *
+ * Mutates `campaign` in-place.
+ */
+export declare function mergeBattleOutcome(campaign: CampaignState, outcome: BattleOutcome): void;

package/dist/src/terrain-bridge.js

@@ -0,0 +1,322 @@
+// src/terrain-bridge.ts — PA-5: Campaign ↔ Tactical Terrain Bridge
+//
+// Maps campaign hex tiles to tactical battlefield parameters consumable by
+// KernelContext, and merges tactical battle results back into CampaignState.
+//
+// Typical workflow:
+//   1. Army enters a forest hex on the campaign map.
+//   2. Call generateBattleSite({ hexType: "forest", ... }) → BattleTerrainParams.
+//   3. Build KernelContext from terrain params; run stepWorld until battle ends.
+//   4. Call mergeBattleOutcome(campaign, { worldState, elapsedSeconds }) to
+//      apply casualties, injuries, and looted equipment back to campaign.
+import { q } from "./units.js";
+import { buildTerrainGrid, buildObstacleGrid, buildElevationGrid, buildSlopeGrid, terrainKey, } from "./sim/terrain.js";
+import { createCoverSegment } from "./sim/cover.js";
+// ── Field constants ────────────────────────────────────────────────────────────
+/** Battlefield width [SCALE.m]. 100 m. */
+export const FIELD_WIDTH_Sm = 1_000_000;
+/** Battlefield depth [SCALE.m]. 80 m. */
+export const FIELD_HEIGHT_Sm = 800_000;
+/** Terrain cell size [SCALE.m]. 10 m per cell → 10 × 8 grid. */
+export const CELL_SIZE_Sm = 100_000;
+/** Number of grid columns (field width / cell size). */
+export const GRID_COLS = 10;
+/** Number of grid rows (field height / cell size). */
+export const GRID_ROWS = 8;
+/** Attacker spawn y [SCALE.m] — 5 m from the south (y=0) edge. */
+export const ATTACKER_SPAWN_Y_Sm = 50_000;
+/** Defender spawn y [SCALE.m] — 5 m from the north edge. */
+export const DEFENDER_SPAWN_Y_Sm = (FIELD_HEIGHT_Sm - 50_000);
+// ── extractTerrainParams ──────────────────────────────────────────────────────
+/**
+ * Build terrain, obstacle, elevation, and slope grids for a campaign hex type.
+ *
+ * Fully deterministic — produces the same output for the same `hexType` every
+ * call.  Does not include `entryVectors`; use `generateBattleSite` for a full
+ * site including team spawn positions.
+ *
+ * Grid layout: 10 columns × 8 rows, each cell 10 m (100 000 SCALE.m).
+ * Total field: 100 m wide × 80 m deep.
+ */
+export function extractTerrainParams(hexType) {
+    switch (hexType) {
+        case "plains": return _plains();
+        case "forest": return _forest();
+        case "hills": return _hills();
+        case "marsh": return _marsh();
+        case "urban": return _urban();
+        case "mountain": return _mountain();
+        case "river_crossing": return _riverCrossing();
+        case "coastal": return _coastal();
+    }
+}
+// ── generateBattleSite ────────────────────────────────────────────────────────
+/** Three evenly-spaced x spawn positions (15 m, 50 m, 85 m). */
+const SPAWN_X_Sm = [150_000, 500_000, 850_000];
+/**
+ * Generate a complete battle site for a campaign encounter.
+ *
+ * Calls `extractTerrainParams` and appends `EntryVector` entries for each
+ * attacking and defending team.
+ *
+ * Teams with more than three members reuse spawn positions (cyclic).
+ */
+export function generateBattleSite(ctx) {
+    const base = extractTerrainParams(ctx.hexType);
+    const entryVectors = [];
+    for (let i = 0; i < ctx.attackerTeamIds.length; i++) {
+        entryVectors.push({
+            teamId: ctx.attackerTeamIds[i],
+            x_Sm: SPAWN_X_Sm[i % SPAWN_X_Sm.length],
+            y_Sm: ATTACKER_SPAWN_Y_Sm,
+            facingY: 1,
+        });
+    }
+    for (let i = 0; i < ctx.defenderTeamIds.length; i++) {
+        entryVectors.push({
+            teamId: ctx.defenderTeamIds[i],
+            x_Sm: SPAWN_X_Sm[i % SPAWN_X_Sm.length],
+            y_Sm: DEFENDER_SPAWN_Y_Sm,
+            facingY: -1,
+        });
+    }
+    return { ...base, entryVectors };
+}
+// ── mergeBattleOutcome ────────────────────────────────────────────────────────
+/**
+ * Merge a completed tactical battle back into campaign state.
+ *
+ * **What this does:**
+ * - Advances `campaign.worldTime_s` by `outcome.elapsedSeconds`.
+ * - Removes entities that died in battle (`injury.dead === true`) from the
+ *   campaign entity registry, location map, and inventory map.
+ * - Copies post-battle `injury` and `condition` state onto surviving campaign
+ *   entities so wounds persist between encounters.
+ * - Transfers weapons and armour from `capturedEntityIds` to the winning
+ *   team's first surviving entity inventory (item id → count).
+ * - Appends a human-readable battle summary to `campaign.log`.
+ *
+ * Mutates `campaign` in-place.
+ */
+export function mergeBattleOutcome(campaign, outcome) {
+    campaign.worldTime_s += outcome.elapsedSeconds;
+    const { worldState, capturedEntityIds = [], winnerTeamId } = outcome;
+    let killed = 0;
+    let survived = 0;
+    for (const entity of worldState.entities) {
+        const campaignEntity = campaign.entities.get(entity.id);
+        if (campaignEntity === undefined)
+            continue; // not in this campaign
+        if (_isDead(entity)) {
+            campaign.entities.delete(entity.id);
+            campaign.entityLocations.delete(entity.id);
+            campaign.entityInventories.delete(entity.id);
+            killed++;
+        }
+        else {
+            // Carry forward post-battle wounds and psychological state
+            if (entity.injury !== undefined)
+                campaignEntity.injury = entity.injury;
+            if (entity.condition !== undefined)
+                campaignEntity.condition = entity.condition;
+            survived++;
+        }
+    }
+    // Equipment transfer: looted gear from captured/incapacitated enemies
+    if (winnerTeamId !== undefined && capturedEntityIds.length > 0) {
+        const winnerId = _firstAliveInTeam(worldState, winnerTeamId);
+        if (winnerId !== undefined) {
+            const winInv = campaign.entityInventories.get(winnerId) ?? new Map();
+            for (const capturedId of capturedEntityIds) {
+                // Carry items from campaign inventory
+                const inv = campaign.entityInventories.get(capturedId);
+                if (inv !== undefined) {
+                    for (const [itemId, count] of inv) {
+                        winInv.set(itemId, (winInv.get(itemId) ?? 0) + count);
+                    }
+                }
+                // Transfer equipped items (weapons, armour) by id
+                const capEntity = campaign.entities.get(capturedId);
+                if (capEntity !== undefined) {
+                    for (const item of capEntity.loadout.items) {
+                        winInv.set(item.id, (winInv.get(item.id) ?? 0) + 1);
+                    }
+                }
+            }
+            campaign.entityInventories.set(winnerId, winInv);
+        }
+    }
+    const outcome_note = winnerTeamId !== undefined
+        ? ` Team ${winnerTeamId} victorious.`
+        : " Draw.";
+    campaign.log.push({
+        worldTime_s: campaign.worldTime_s,
+        text: `Battle concluded (${survived} survived, ${killed} killed).${outcome_note}`,
+    });
+}
+// ── Internal helpers ──────────────────────────────────────────────────────────
+function _isDead(entity) {
+    return entity.injury?.dead === true;
+}
+function _firstAliveInTeam(world, teamId) {
+    for (const e of world.entities) {
+        if (e.teamId === teamId && !_isDead(e))
+            return e.id;
+    }
+    return undefined;
+}
+function _base() {
+    return {
+        width_Sm: FIELD_WIDTH_Sm,
+        height_Sm: FIELD_HEIGHT_Sm,
+        cellSize_Sm: CELL_SIZE_Sm,
+        terrainGrid: new Map(),
+        obstacleGrid: new Map(),
+        elevationGrid: new Map(),
+        slopeGrid: new Map(),
+        coverSegments: [],
+        dominantSurface: "normal",
+    };
+}
+function ck(col, row) {
+    return terrainKey(col, row);
+}
+/** Plains: open ground, two dirt berm defensive lines. */
+function _plains() {
+    const r = _base();
+    r.coverSegments.push(createCoverSegment("plains_berm_s", 200_000, 250_000, 600_000, 8_000, "dirt"), createCoverSegment("plains_berm_n", 200_000, 550_000, 600_000, 8_000, "dirt"));
+    return r;
+}
+/** Forest: muddy undergrowth, partial cover, two wood tree-lines flanking a central path. */
+function _forest() {
+    const r = _base();
+    r.dominantSurface = "mud";
+    const terrain = {};
+    const obstacles = {};
+    for (let col = 0; col < GRID_COLS; col++) {
+        for (let row = 0; row < GRID_ROWS; row++) {
+            const key = ck(col, row);
+            if (row !== 3 && row !== 4) { // rows 3-4 = natural path (no mud)
+                terrain[key] = "mud";
+                obstacles[key] = q(0.40); // dense undergrowth — 40% cover
+            }
+        }
+    }
+    r.terrainGrid = buildTerrainGrid(terrain);
+    r.obstacleGrid = buildObstacleGrid(obstacles);
+    // Tree-lines flanking the path (y = 25 m and y = 50 m)
+    r.coverSegments.push(createCoverSegment("forest_tree_s", 0, 250_000, 1_000_000, 12_000, "wood"), createCoverSegment("forest_tree_n", 0, 500_000, 1_000_000, 12_000, "wood"));
+    return r;
+}
+/** Hills: gradient elevation south-to-north, stone cover on the crest. */
+function _hills() {
+    const r = _base();
+    r.dominantSurface = "slope_up";
+    const terrain = {};
+    const elevation = {};
+    const slopes = {};
+    for (let col = 0; col < GRID_COLS; col++) {
+        for (let row = 0; row < GRID_ROWS; row++) {
+            const key = ck(col, row);
+            if (row < 4) {
+                // South half — uphill approach; elevation rises 5 m per row (0–15 m)
+                terrain[key] = "slope_up";
+                elevation[key] = (row * 50_000);
+                slopes[key] = { type: "uphill", grade: q(0.50) };
+            }
+            else {
+                // North half — downhill on far side of crest
+                terrain[key] = "slope_down";
+                elevation[key] = ((GRID_ROWS - 1 - row) * 50_000);
+                slopes[key] = { type: "downhill", grade: q(0.50) };
+            }
+        }
+    }
+    r.terrainGrid = buildTerrainGrid(terrain);
+    r.elevationGrid = buildElevationGrid(elevation);
+    r.slopeGrid = buildSlopeGrid(slopes);
+    // Stone wall along the ridgeline (y ≈ 40 m)
+    r.coverSegments.push(createCoverSegment("hills_ridgeline", 100_000, 400_000, 800_000, 10_000, "stone"));
+    return r;
+}
+/** Marsh: all-mud terrain, no cover — speed heavily penalised. */
+function _marsh() {
+    const r = _base();
+    r.dominantSurface = "mud";
+    const terrain = {};
+    for (let col = 0; col < GRID_COLS; col++) {
+        for (let row = 0; row < GRID_ROWS; row++) {
+            terrain[ck(col, row)] = "mud";
+        }
+    }
+    r.terrainGrid = buildTerrainGrid(terrain);
+    return r;
+}
+/** Urban: dense stone and wood cover forming a street grid; partial obstacle cells. */
+function _urban() {
+    const r = _base();
+    // Stone building walls — south block, mid block, north block
+    r.coverSegments.push(createCoverSegment("urban_s1", 0, 200_000, 350_000, 20_000, "stone"), createCoverSegment("urban_s2", 450_000, 200_000, 350_000, 20_000, "stone"), createCoverSegment("urban_s3", 200_000, 300_000, 200_000, 20_000, "stone"), createCoverSegment("urban_m1", 0, 400_000, 250_000, 20_000, "stone"), createCoverSegment("urban_m2", 350_000, 400_000, 300_000, 20_000, "stone"), createCoverSegment("urban_m3", 750_000, 400_000, 250_000, 20_000, "stone"), createCoverSegment("urban_n1", 100_000, 600_000, 350_000, 20_000, "stone"), createCoverSegment("urban_n2", 550_000, 600_000, 350_000, 20_000, "stone"), createCoverSegment("urban_barr1", 350_000, 350_000, 100_000, 10_000, "wood"), createCoverSegment("urban_barr2", 350_000, 500_000, 100_000, 10_000, "wood"));
+    // Partial obstacles in building interiors (~50% cover)
+    r.obstacleGrid = buildObstacleGrid({
+        [ck(1, 2)]: q(0.50),
+        [ck(5, 2)]: q(0.50),
+        [ck(2, 4)]: q(0.50),
+        [ck(7, 4)]: q(0.50),
+    });
+    return r;
+}
+/** Mountain: steep icy ascent, high elevation, rocky outcrops. */
+function _mountain() {
+    const r = _base();
+    r.dominantSurface = "slope_up";
+    const terrain = {};
+    const elevation = {};
+    const slopes = {};
+    for (let col = 0; col < GRID_COLS; col++) {
+        for (let row = 0; row < GRID_ROWS; row++) {
+            const key = ck(col, row);
+            elevation[key] = (row * 100_000); // 0–70 m rise
+            terrain[key] = row >= 4 ? "ice" : "slope_up";
+            slopes[key] = {
+                type: "uphill",
+                grade: (row >= 4 ? q(0.80) : q(0.60)),
+            };
+        }
+    }
+    r.terrainGrid = buildTerrainGrid(terrain);
+    r.elevationGrid = buildElevationGrid(elevation);
+    r.slopeGrid = buildSlopeGrid(slopes);
+    // Rocky outcrops for cover
+    r.coverSegments.push(createCoverSegment("mtn_rock1", 100_000, 200_000, 150_000, 15_000, "stone"), createCoverSegment("mtn_rock2", 600_000, 350_000, 200_000, 15_000, "stone"), createCoverSegment("mtn_rock3", 300_000, 500_000, 150_000, 15_000, "stone"));
+    return r;
+}
+/** River crossing: muddy ford in the center, sandbag cover on the defending bank. */
+function _riverCrossing() {
+    const r = _base();
+    r.dominantSurface = "mud";
+    // Mud band at rows 3-4 (30–50 m) — the ford
+    const terrain = {};
+    for (let col = 0; col < GRID_COLS; col++) {
+        terrain[ck(col, 3)] = "mud";
+        terrain[ck(col, 4)] = "mud";
+    }
+    r.terrainGrid = buildTerrainGrid(terrain);
+    // Sandbag defensive line on the far (north) bank
+    r.coverSegments.push(createCoverSegment("river_cover_w", 50_000, 500_000, 350_000, 12_000, "sandbag"), createCoverSegment("river_cover_e", 600_000, 500_000, 350_000, 12_000, "sandbag"));
+    return r;
+}
+/** Coastal: muddy beach approach (south 2 rows), dunes and rocky outcrops for cover. */
+function _coastal() {
+    const r = _base();
+    // Soft sand / surf zone — rows 0-1 (0–20 m from south)
+    const terrain = {};
+    for (let col = 0; col < GRID_COLS; col++) {
+        terrain[ck(col, 0)] = "mud";
+        terrain[ck(col, 1)] = "mud";
+    }
+    r.terrainGrid = buildTerrainGrid(terrain);
+    // Dunes and rocky coastal outcrops
+    r.coverSegments.push(createCoverSegment("coastal_dune1", 100_000, 150_000, 300_000, 8_000, "dirt"), createCoverSegment("coastal_dune2", 600_000, 150_000, 300_000, 8_000, "dirt"), createCoverSegment("coastal_rock1", 0, 350_000, 200_000, 12_000, "stone"), createCoverSegment("coastal_rock2", 800_000, 450_000, 200_000, 12_000, "stone"));
+    return r;
+}

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.54",
   "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,14 @@
     "./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"
+    },
+    "./terrain-bridge": {
+      "import": "./dist/src/terrain-bridge.js",
+      "types": "./dist/src/terrain-bridge.d.ts"
     }
   },
   "workspaces": [
@@ -194,6 +205,7 @@
     "docs/wire-protocol.md",
     "schema/world.schema.json",
     "schema/replay.schema.json",
+    "schema/pack.schema.json",
     "CHANGELOG.md",
     "STABLE_API.md"
   ],
@@ -239,6 +251,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 }
+      }
+    }
+  }
+}