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

package/CHANGELOG.md

@@ -6,6 +6,39 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.52] — 2026-03-28
+
+### Added
+
+- **PA-3 — Stable Schema, Save & Wire Contract (complete):**
+  - `src/schema-migration.ts` (new): schema versioning and migration utilities — `SCHEMA_VERSION`, `stampSnapshot`, `validateSnapshot` (returns `ValidationError[]` with JSONPath paths), `migrateWorld` (chains registered migrations; legacy saves treated as version `"0.0"`), `registerMigration`, `detectVersion`, `isValidSnapshot`.
+  - `schema/world.schema.json` (new): JSON Schema 2020-12 for `WorldState` — documents `@core` fields (`tick`, `seed`, `entities` with per-entity validation), `@subsystem` fields, and Q-value semantics.
+  - `schema/replay.schema.json` (new): JSON Schema 2020-12 for `Replay` / `ReplayFrame` / `Command`.
+  - `docs/wire-protocol.md` (new): Q-value serialisation rules (store raw integers, never divide by `SCALE.Q`), binary diff format (ANKD magic, tag-value encoding), multiplayer lockstep message types (`cmd`/`ack`/`resync`/`hash_mismatch`), save-format recommendations, and full load-with-migration code sample.
+  - `"./schema"` subpath added to `package.json` exports.
+  - `schema/` directory and `docs/wire-protocol.md` added to `package.json` `"files"`.
+- 39 new tests (183 test files, 5,300 tests total). Build: clean.
+
+---
+
+## [0.1.51] — 2026-03-28
+
+### Added
+
+- **PA-2 — Modular Package Architecture (Phase 1 complete):**
+  - `packages/core/` — `@ananke/core` stub; re-exports the full main `"."` entry point (kernel, entity model, units, RNG, replay, bridge).
+  - `packages/combat/` — `@ananke/combat` stub; re-exports `"./combat"`, `"./anatomy"`, `"./competence"`, `"./wasm-kernel"`.
+  - `packages/campaign/` — `@ananke/campaign` stub; re-exports all 32 campaign-scale subpaths (polity, social, narrative, feudal, demography, economy, military…).
+  - `packages/content/` — `@ananke/content` stub; re-exports `"./species"`, `"./catalog"`, `"./character"`, `"./crafting"`.
+  - Each stub ships a pre-built `index.js` + `index.d.ts` (no separate compilation step); `@its-not-rocket-science/ananke` is a peer dependency.
+  - Root `package.json` gains `"workspaces": ["packages/*"]` for local linking.
+  - `docs/package-architecture.md` (new): canonical package boundary design — dependency graph, monolith subpath → package mapping table, full source-file → package mapping for Phase 2 migration, and a before/after import example.
+  - `docs/migration-monolith-to-modular.md` (new): step-by-step migration guide from the monolith to `@ananke/*` packages, with a complete old-import → new-package lookup table and Phase 2 expectations.
+  - `docs/package-architecture.md` and `docs/migration-monolith-to-modular.md` added to `package.json` `"files"` so they ship with the published package.
+- Build: clean. Tests: 5,261 passing. Coverage unchanged.
+
+---
+
 ## [0.1.50] — 2026-03-28
 
 ### Docs

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

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

package/dist/src/schema-migration.js

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

package/docs/migration-monolith-to-modular.md

@@ -0,0 +1,120 @@
+# Migration Guide: Monolith to Modular Packages
+
+This guide covers how to migrate from `@its-not-rocket-science/ananke` to the
+focused `@ananke/*` packages.  Migration is optional — the monolith package is
+maintained indefinitely for backwards compatibility.
+
+---
+
+## Should you migrate?
+
+| Situation | Recommendation |
+|-----------|----------------|
+| Existing project, everything working | Stay on the monolith. No action required. |
+| New project, only needs combat | Start with `@ananke/combat` + `@ananke/core` |
+| New project, full simulation stack | Use the monolith; migrate to modular when convenient |
+| Bundle size is a concern (Phase 2+) | Migrate after Phase 2 (source migration) for real tree-shaking |
+
+---
+
+## Phase 1 Migration (stubs — available now)
+
+Phase 1 packages are thin wrappers that re-export from the monolith.  Bundle
+size is unchanged, but import paths are cleaner and signal which API tier you
+depend on.
+
+### Step 1 — Install the sub-package(s) you need
+
+```bash
+# Combat-only host
+npm install @ananke/core @ananke/combat
+
+# Full world simulation
+npm install @ananke/core @ananke/combat @ananke/campaign @ananke/content
+```
+
+The monolith is installed automatically as a peer dependency.
+
+### Step 2 — Update imports
+
+Replace monolith paths with the appropriate package name:
+
+| Old import | New import |
+|-----------|-----------|
+| `@its-not-rocket-science/ananke` | `@ananke/core` |
+| `@its-not-rocket-science/ananke/combat` | `@ananke/combat` |
+| `@its-not-rocket-science/ananke/anatomy` | `@ananke/combat` |
+| `@its-not-rocket-science/ananke/competence` | `@ananke/combat` |
+| `@its-not-rocket-science/ananke/wasm-kernel` | `@ananke/combat` |
+| `@its-not-rocket-science/ananke/species` | `@ananke/content` |
+| `@its-not-rocket-science/ananke/catalog` | `@ananke/content` |
+| `@its-not-rocket-science/ananke/character` | `@ananke/content` |
+| `@its-not-rocket-science/ananke/crafting` | `@ananke/content` |
+| `@its-not-rocket-science/ananke/campaign` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/polity` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/social` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/narrative` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/narrative-prose` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/renown` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/kinship` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/succession` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/calendar` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/feudal` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/diplomacy` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/migration` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/espionage` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/trade-routes` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/siege` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/faith` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/demography` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/granary` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/epidemic` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/infrastructure` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/unrest` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/research` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/taxation` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/military-campaign` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/governance` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/resources` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/climate` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/famine` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/containment` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/mercenaries` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/wonders` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/monetary` | `@ananke/campaign` |
+
+### Step 3 — Verify
+
+```bash
+npm run build   # or tsc --noEmit
+npm test
+```
+
+No other changes are needed.
+
+---
+
+## Phase 2 Migration (source migration — planned)
+
+When Phase 2 lands, `@ananke/combat` will no longer depend on the monolith.
+The import paths remain identical — only the transitive dependency graph changes.
+
+**No code changes required in your project for Phase 2.**
+
+Run `npm update` when the new versions are published; your bundler will
+automatically produce a smaller output.
+
+---
+
+## Staying on the monolith
+
+If you prefer to keep using `@its-not-rocket-science/ananke` directly, nothing
+changes.  The 41 subpath exports are stable and will not be removed.
+
+---
+
+## See also
+
+- [`docs/package-architecture.md`](package-architecture.md) — full design document and source file mapping
+- [`docs/module-index.md`](module-index.md) — all exports with stability tiers and use cases
+- [`STABLE_API.md`](../STABLE_API.md) — stable API surface (Tier 1)

package/docs/package-architecture.md

@@ -0,0 +1,323 @@
+# Ananke — Modular Package Architecture
+
+> **Status: Phase 1 complete** — Package stubs with re-exports are published.
+> Phase 2 (source migration) moves code into individual packages so combat has
+> no campaign dependency at the module level.
+
+---
+
+## Problem
+
+`@its-not-rocket-science/ananke` ships 41 subpath exports in a single package.
+A host that only needs tactical combat transitively depends on feudal succession,
+epidemic simulation, and monetary policy.  A renderer integration author has no
+clean way to depend only on the bridge layer.
+
+---
+
+## Package Overview
+
+| Package | Stability | Description | Key entry point(s) |
+|---------|-----------|-------------|-------------------|
+| `@ananke/core` | **Stable** | Kernel, entity model, fixed-point units, RNG, replay | `"@ananke/core"` |
+| `@ananke/combat` | Experimental | Combat resolution, anatomy, grapple, ranged, competence | `"@ananke/combat"` |
+| `@ananke/campaign` | Experimental | World simulation — polity, economy, social, demography | `"@ananke/campaign"` |
+| `@ananke/content` | Experimental | Species, equipment catalogue, archetypes, crafting | `"@ananke/content"` |
+| `@ananke/bridge` | Experimental | Renderer bridge, interpolation, animation hints *(Phase 2)* | `"@ananke/bridge"` |
+| `@its-not-rocket-science/ananke` | **Meta-package** | Re-exports all of the above for backwards compatibility | unchanged |
+
+> `@ananke/bridge` is not yet a standalone stub — bridge exports are part of
+> `@ananke/core` until Phase 2 adds a dedicated `"./bridge"` subpath to the
+> monolith.
+
+---
+
+## Package Dependency Graph
+
+```
+@ananke/core
+    │
+    ├── @ananke/combat      (peer: @ananke/core)
+    ├── @ananke/campaign    (peer: @ananke/core)
+    ├── @ananke/content     (peer: @ananke/core)
+    └── @ananke/bridge      (peer: @ananke/core)   [Phase 2]
+
+@its-not-rocket-science/ananke  (meta: re-exports all four)
+```
+
+---
+
+## Monolith Subpath → Package Mapping
+
+### @ananke/core
+
+| Monolith subpath | Notes |
+|-----------------|-------|
+| `"."` | Entire main export — kernel, entity, units, RNG, replay, bridge |
+
+### @ananke/combat
+
+| Monolith subpath | Notes |
+|-----------------|-------|
+| `"./combat"` | resolveHit, resolveBlock, CombatContext |
+| `"./anatomy"` | BodyPlan, AnatomyRegion, injury regions |
+| `"./competence"` | skill contest resolution, interspecies signalling |
+| `"./wasm-kernel"` | WASM-accelerated combat math |
+
+### @ananke/campaign
+
+| Monolith subpath | Notes |
+|-----------------|-------|
+| `"./campaign"` | Campaign layer, strategic tick |
+| `"./polity"` | Polity, stepPolityDay, tech diffusion |
+| `"./social"` | Social relationships, dialogue |
+| `"./narrative"` | Narrative event system |
+| `"./narrative-prose"` | Prose generation |
+| `"./renown"` | Fame and reputation |
+| `"./kinship"` | Family trees, genealogy |
+| `"./succession"` | Inheritance rules |
+| `"./calendar"` | In-world calendar and date tracking |
+| `"./feudal"` | Feudal hierarchy |
+| `"./diplomacy"` | Treaties and diplomatic acts |
+| `"./migration"` | Population movement |
+| `"./espionage"` | Espionage and spycraft |
+| `"./trade-routes"` | Trade route simulation |
+| `"./siege"` | Siege warfare mechanics |
+| `"./faith"` | Religion and doctrine |
+| `"./demography"` | Population simulation |
+| `"./granary"` | Food storage and distribution |
+| `"./epidemic"` | Disease spread |
+| `"./infrastructure"` | Buildings and construction |
+| `"./unrest"` | Civil unrest |
+| `"./research"` | Technology research |
+| `"./taxation"` | Tax collection |
+| `"./military-campaign"` | Military campaign mechanics |
+| `"./governance"` | Governance and edicts |
+| `"./resources"` | Resource management |
+| `"./climate"` | Climate and weather effects |
+| `"./famine"` | Famine simulation |
+| `"./containment"` | Disease containment |
+| `"./mercenaries"` | Mercenary companies |
+| `"./wonders"` | Wonders and monuments |
+| `"./monetary"` | Monetary policy and currency |
+
+### @ananke/content
+
+| Monolith subpath | Notes |
+|-----------------|-------|
+| `"./species"` | Species definitions, stat profiles |
+| `"./catalog"` | Equipment and item catalogue |
+| `"./character"` | Character generation and archetypes |
+| `"./crafting"` | Crafting recipes, workshops, manufacturing |
+
+---
+
+## Source File → Package Mapping (Phase 2 migration)
+
+### @ananke/core
+```
+src/units.ts
+src/rng.ts
+src/types.ts
+src/replay.ts
+src/sim/entity.ts
+src/sim/kernel.ts
+src/sim/seeds.ts
+src/sim/world.ts
+src/sim/kinds.ts
+src/sim/condition.ts
+src/sim/body.ts
+src/sim/bodyplan.ts
+src/sim/limb.ts
+src/sim/tick.ts
+src/sim/indexing.ts
+src/sim/events.ts
+src/sim/commands.ts
+src/sim/commandBuilders.ts
+src/sim/context.ts
+src/sim/intent.ts
+src/sim/vec3.ts
+src/sim/spatial.ts
+src/sim/skills.ts
+src/sim/traits.ts
+src/sim/terrain.ts
+src/sim/action.ts
+src/sim/step/           (all 10 step files)
+src/bridge/             (all 5 bridge files)
+src/presets.ts
+src/generate.ts
+src/derive.ts
+src/describe.ts
+src/traits.ts
+src/metrics.ts
+src/dist.ts
+src/wasm-kernel.ts
+```
+
+### @ananke/combat
+```
+src/sim/combat.ts
+src/sim/injury.ts
+src/sim/wound-aging.ts
+src/sim/medical.ts
+src/sim/morale.ts
+src/sim/grapple.ts
+src/sim/ranged.ts
+src/sim/stamina.ts      (if present)
+src/sim/impairment.ts
+src/sim/knockback.ts
+src/sim/cover.ts
+src/sim/cone.ts
+src/sim/formation.ts
+src/sim/formation-combat.ts
+src/sim/formation-unit.ts
+src/sim/frontage.ts
+src/sim/density.ts
+src/sim/occlusion.ts
+src/sim/ai/             (all 8 AI files)
+src/combat.ts
+src/equipment.ts
+src/weapons.ts
+src/anatomy/            (all 5 anatomy files)
+src/competence/         (all 13 competence files)
+src/arena.ts
+src/dialogue.ts
+src/party.ts
+src/faction.ts
+src/downtime.ts
+```
+
+### @ananke/campaign
+```
+src/campaign.ts
+src/campaign-layer.ts
+src/polity.ts
+src/polity-vassals.ts
+src/social.ts
+src/relationships.ts
+src/relationships-effects.ts
+src/emotional-contagion.ts
+src/narrative.ts
+src/narrative-layer.ts
+src/narrative-prose.ts
+src/narrative-render.ts
+src/narrative-stress.ts
+src/story-arcs.ts
+src/quest.ts
+src/quest-generators.ts
+src/chronicle.ts
+src/legend.ts
+src/mythology.ts
+src/renown.ts
+src/kinship.ts
+src/succession.ts
+src/calendar.ts
+src/feudal.ts
+src/diplomacy.ts
+src/migration.ts
+src/espionage.ts
+src/trade-routes.ts
+src/siege.ts
+src/faith.ts
+src/demography.ts
+src/granary.ts
+src/epidemic.ts
+src/infrastructure.ts
+src/unrest.ts
+src/research.ts
+src/taxation.ts
+src/military-campaign.ts
+src/governance.ts
+src/resources.ts
+src/climate.ts
+src/famine.ts
+src/containment.ts
+src/mercenaries.ts
+src/wonders.ts
+src/monetary.ts
+src/collective-activities.ts
+src/economy.ts
+src/economy-gen.ts
+src/tech-diffusion.ts
+src/culture.ts
+src/settlement.ts
+src/settlement-services.ts
+src/channels.ts
+src/inheritance.ts
+src/progression.ts
+src/sim/disease.ts
+src/sim/aging.ts
+src/sim/sleep.ts
+src/sim/mount.ts
+src/sim/hazard.ts
+src/sim/nutrition.ts
+src/sim/thermoregulation.ts
+src/sim/toxicology.ts
+src/sim/systemic-toxicology.ts
+src/sim/substance.ts
+src/sim/weather.ts
+src/sim/biome.ts
+src/sim/tech.ts
+```
+
+### @ananke/content
+```
+src/species.ts
+src/catalog.ts
+src/character.ts
+src/archetypes.ts
+src/crafting/           (all 5 crafting files)
+src/inventory.ts
+src/item-durability.ts
+src/snapshot.ts
+src/world-generation.ts
+src/world-factory.ts
+src/scenario.ts
+src/modding.ts
+src/lod.ts
+src/model3d.ts
+```
+
+---
+
+## Phase 2: Source Migration Plan
+
+1. **Create workspace package directories** with their own `tsconfig.build.json`.
+2. **Move source files** from `src/` into `packages/NAME/src/` following the table above.
+3. **Update internal imports** — use `@ananke/core` etc. instead of relative paths that cross
+   package boundaries.
+4. **Wire inter-package dependencies** — `@ananke/combat` lists `@ananke/core` as a dependency.
+5. **Update the monolith meta-package** (`@its-not-rocket-science/ananke`) to re-export from
+   the five sub-packages instead of from `src/`.
+6. **Verify** that all existing tests pass without modification (test paths remain unchanged).
+
+The most complex step is (3) — identifying which imports cross package boundaries.  A planned
+tool (`tools/check-package-boundaries.ts`) will analyse the import graph and report violations.
+
+---
+
+## What Changes for Package Consumers
+
+### Phase 1 (now — stubs)
+```typescript
+// Before (monolith)
+import { resolveHit } from "@its-not-rocket-science/ananke/combat";
+
+// After (modular stub — same bundle size, cleaner import path)
+import { resolveHit } from "@ananke/combat";
+```
+
+### Phase 2 (source migration — smaller bundles)
+```typescript
+// Same import — but now @ananke/combat has no campaign dependency
+import { resolveHit } from "@ananke/combat";
+```
+
+The import path is the same in Phase 1 and Phase 2; only the bundle contents change.
+
+---
+
+## Backwards Compatibility
+
+`@its-not-rocket-science/ananke` will remain published indefinitely as a meta-package.
+All 41 subpath exports will continue to work.  Existing hosts do not need to migrate.

package/docs/wire-protocol.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@its-not-rocket-science/ananke",
-  "version": "0.1.50",
+  "version": "0.1.52",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",
@@ -170,8 +170,15 @@
     "./monetary": {
       "import": "./dist/src/monetary.js",
       "types": "./dist/src/monetary.d.ts"
+    },
+    "./schema": {
+      "import": "./dist/src/schema-migration.js",
+      "types": "./dist/src/schema-migration.d.ts"
     }
   },
+  "workspaces": [
+    "packages/*"
+  ],
   "files": [
     "dist/src",
     "dist/as",
@@ -182,6 +189,11 @@
     "docs/performance.md",
     "docs/versioning.md",
     "docs/emergent-validation-report.md",
+    "docs/package-architecture.md",
+    "docs/migration-monolith-to-modular.md",
+    "docs/wire-protocol.md",
+    "schema/world.schema.json",
+    "schema/replay.schema.json",
     "CHANGELOG.md",
     "STABLE_API.md"
   ],

package/schema/replay.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://its-not-rocket-science.github.io/ananke/schema/replay.schema.json",
+  "title": "Replay",
+  "description": "Ananke deterministic replay — an initial WorldState plus a sequence of command frames. Replaying all frames against the initial state must reproduce the exact final state (same tick, same entity conditions, same RNG sequence).",
+  "type": "object",
+  "required": ["initialState", "frames"],
+  "properties": {
+    "_ananke_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+$",
+      "description": "Schema version stamped by stampSnapshot()."
+    },
+    "_schema": {
+      "type": "string",
+      "const": "replay",
+      "description": "Schema discrimination tag — always \"replay\" for Replay snapshots."
+    },
+    "initialState": {
+      "$ref": "world.schema.json",
+      "description": "The WorldState at tick 0 (or whatever tick the recording began). Must itself be a valid world snapshot."
+    },
+    "frames": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/ReplayFrame" },
+      "description": "Ordered sequence of command frames. Frame indices correspond to ticks relative to initialState.tick."
+    }
+  },
+  "unevaluatedProperties": true,
+  "$defs": {
+    "ReplayFrame": {
+      "title": "ReplayFrame",
+      "type": "object",
+      "required": ["tick", "commands"],
+      "properties": {
+        "tick": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Absolute simulation tick this frame was recorded at."
+        },
+        "commands": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/Command" },
+          "description": "Commands dispatched during this tick. May be empty."
+        }
+      }
+    },
+    "Command": {
+      "title": "Command",
+      "description": "A single world-mutating command dispatched to stepWorld(). Commands are discriminated by their `kind` field.",
+      "type": "object",
+      "required": ["kind"],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "description": "Command type identifier, e.g. \"attack\", \"move\", \"grapple\"."
+        },
+        "entityId": {
+          "type": "integer",
+          "description": "Issuing entity id (where applicable)."
+        },
+        "targetId": {
+          "type": "integer",
+          "description": "Target entity id (where applicable)."
+        }
+      },
+      "unevaluatedProperties": true
+    }
+  }
+}

package/schema/world.schema.json

@@ -0,0 +1,105 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://its-not-rocket-science.github.io/ananke/schema/world.schema.json",
+  "title": "WorldState",
+  "description": "Ananke world snapshot — the complete state required to resume or replay a simulation. See docs/wire-protocol.md for serialisation rules.",
+  "type": "object",
+  "required": ["tick", "seed", "entities"],
+  "properties": {
+    "_ananke_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+$",
+      "description": "Schema version stamped by stampSnapshot(), e.g. \"0.1\". Absent on legacy saves."
+    },
+    "_schema": {
+      "type": "string",
+      "const": "world",
+      "description": "Schema discrimination tag — always \"world\" for WorldState snapshots."
+    },
+    "tick": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "@core — Current simulation tick. Incremented by stepWorld() each call."
+    },
+    "seed": {
+      "type": "integer",
+      "description": "@core — Deterministic RNG seed. Same seed + same commands → identical output."
+    },
+    "entities": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/EntityCore" },
+      "description": "@core — All live and dead entities."
+    },
+    "activeFieldEffects": {
+      "type": "array",
+      "items": { "type": "object" },
+      "description": "@subsystem(capability) — Active suppression zones and field-effect modifiers."
+    },
+    "__sensoryEnv": {
+      "type": "object",
+      "description": "@subsystem(sensory) — Ambient lighting and visibility environment."
+    },
+    "__factionRegistry": {
+      "type": "object",
+      "description": "@subsystem(faction) — Global faction standing registry."
+    },
+    "__partyRegistry": {
+      "type": "object",
+      "description": "@subsystem(party) — Global party registry for morale and formation bonuses."
+    },
+    "__relationshipGraph": {
+      "type": "object",
+      "description": "@subsystem(relationships) — Inter-entity relationship graph."
+    },
+    "__nutritionAccum": {
+      "type": "number",
+      "description": "@subsystem(nutrition) — Cross-tick nutrition accumulator (scalar)."
+    }
+  },
+  "unevaluatedProperties": true,
+  "$defs": {
+    "EntityCore": {
+      "title": "Entity (@core fields)",
+      "description": "Core entity fields required by stepWorld() every tick. Subsystem and host-extension fields are permitted but not listed here — see src/sim/entity.ts.",
+      "type": "object",
+      "required": ["id", "teamId", "attributes", "energy", "loadout", "traits"],
+      "properties": {
+        "id": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Unique entity identifier (positive I32)."
+        },
+        "teamId": {
+          "type": "integer",
+          "description": "Team allegiance. Entities on the same teamId do not auto-target each other."
+        },
+        "attributes": {
+          "type": "object",
+          "description": "IndividualAttributes — physical and cognitive stats. All Q values are fixed-point integers scaled by SCALE.Q = 10 000."
+        },
+        "energy": {
+          "type": "object",
+          "description": "EnergyState — current stamina and metabolic state."
+        },
+        "loadout": {
+          "type": "object",
+          "description": "Loadout — equipped weapons and armour."
+        },
+        "traits": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Trait string identifiers, e.g. [\"leader\", \"berserker\"]."
+        },
+        "condition": {
+          "type": "object",
+          "description": "@subsystem(condition) — fear, morale, consciousness, surrender state."
+        },
+        "injury": {
+          "type": "object",
+          "description": "@subsystem(injury) — per-region damage fractions (all Q values)."
+        }
+      },
+      "unevaluatedProperties": true
+    }
+  }
+}