@its-not-rocket-science/ananke 0.1.69 → 0.5.4

package/docs/integration-primer.md

@@ -7,7 +7,7 @@
 ## Purpose
 
 > **New to Ananke?** Start with [`docs/host-contract.md`](host-contract.md) — it covers the
-> complete stable integration surface with working code examples.  Return here for
+> current Tier 1 stable integration surface with working code examples. Return here for
 > architecture diagrams, type glossary, and integration gotchas.
 
 This document captures the technical insights, data‑flow diagrams, type glossaries, and gotchas discovered during the 2–4 week evaluation spike described in the ROADMAP’s **Deep Integration & Technical Onboarding** milestone. It is intended as an internal reference for engineers who will be integrating Ananke into a production game or simulation.
@@ -16,28 +16,29 @@ The spike consisted of three concrete experiments:
 
 1. **Tracing the data flow of a simple melee attack** — from `Command` input through the kernel to injury output (`tools/trace‑attack.ts`).
 2. **Building a minimal observer** that reads `WorldState` after each `stepWorld` call and prints entity positions, condition, and injury summaries (`tools/observer.ts`).
-3. **Experimenting with saving and loading a complete `WorldState`** to understand the serialisation format and any Map/BigInt round‑trip concerns (`tools/serialize.ts`).
+3. **Experimenting with saving and loading a full `WorldState` snapshot** to understand the serialisation format and any Map/BigInt round‑trip concerns (`tools/serialize.ts`).
 
 Each experiment is documented below, followed by a glossary of critical types and a list of integration gotchas.
 
 ## Choose your entry point
 
 Use the table below to find the right subpath export for your use case.
-The full module index with all 41 exports is in [`docs/module-index.md`](module-index.md).
+The full module index is in [`docs/module-index.md`](module-index.md).
 
 | I want to… | Start with | Then add |
 |---|---|---|
 | **Simulate a duel or battle** | `"@its-not-rocket-science/ananke"` (main) | `"…/combat"` for grapple, ranged, formation |
 | **Run a campaign / world simulation** | `"…"` + `"…/polity"` | `"…/campaign"` + whichever campaign extensions you need |
 | **Design a species or xenobiology** | `"…"` + `"…/species"` + `"…/anatomy"` | `"…/character"` for aging, sleep, disease |
-| **Drive a 3D renderer** | `"…"` (bridge exports are in main bundle) | See [`docs/bridge-contract.md`](bridge-contract.md) |
+| **Drive a 3D renderer** | `"…/host-loop"` for stable wire frames | Add `"…/tier2"` only if you need experimental bridge internals (`BridgeEngine`, mapping helpers) — see [`docs/bridge-contract.md`](bridge-contract.md) |
 | **Build a multiplayer host** | `"…"` (deterministic by design) | See [`docs/host-contract.md`](host-contract.md) for lockstep pattern |
+| **Run host session workflows** | `"…/session"` | See [`docs/session-api.md`](session-api.md) for the Tier 2 / experimental session facade |
 | **Add narrative / storytelling** | `"…/narrative"` + `"…/narrative-prose"` | `"…/renown"` for legend-building |
 | **Craft / economic simulation** | `"…/crafting"` + `"…/catalog"` | `"…/social"` for trade and faction effects |
 | **Grand strategy / 4X** | `"…/polity"` + `"…/campaign"` | Any combination of the 26 campaign extension modules |
 
-**Stability:** `"."` and `"./polity"` are **Tier 1 (Stable)** — no breaking changes without a major version bump.
-All other subpaths are **Tier 2 (Experimental)** — changelog documents any breaking changes.
+**Stability:** `"."` and `"./polity"` are **Tier 1 stable** — no breaking changes without a major version bump.
+All other subpaths are **Experimental** — changelog documents any breaking changes.
 See [`STABLE_API.md`](../STABLE_API.md) for the full tier table.
 
 ---
@@ -48,13 +49,19 @@ Ananke is a deterministic, lockstep‑friendly simulation kernel that models ent
 
 ### Core data structures
 
-```typescript
+```typescript no-check-example
 interface WorldState {
   tick: number;
   seed: number;
   entities: Entity[];
   activeFieldEffects?: FieldEffect[];
-  __sensoryEnv?: any; // internal side‑channel
+  runtimeState?: {
+    sensoryEnv?: SensoryEnvironment;
+    factionRegistry?: FactionRegistry;
+    partyRegistry?: PartyRegistry;
+    relationshipGraph?: RelationshipGraph;
+    nutritionAccum?: number;
+  }; // explicit host/runtime subsystem state
 }
 
 interface Entity {
@@ -78,7 +85,7 @@ type CommandMap = Map<number, Command[]>;
 
 ### Kernel entry point
 
-```typescript
+```typescript no-check-example
 function stepWorld(
   world: WorldState,
   commands: CommandMap,
@@ -125,7 +132,7 @@ The observer (`tools/observer.ts`) demonstrates how to hook into the `stepWorld`
 
 ### Observer pattern
 
-```typescript
+```typescript no-check-example
 for (let tick = 0; tick < maxTicks; tick++) {
   // 1. Build indexes (required for AI decisions, but we hard‑code commands)
   const index   = buildWorldIndex(world);
@@ -161,7 +168,7 @@ The serialisation demo (`tools/serialize.ts`) shows how to round‑trip a `World
 
 Optional Map fields on `Entity` (`foodInventory`, `armourState`, `reputations`) must be explicitly converted to an array of entries for JSON serialisation:
 
-```typescript
+```typescript no-check-example
 function serializeEntity(e: Entity): unknown {
   const obj: any = { ...e };
   if (e.foodInventory instanceof Map) {
@@ -174,7 +181,7 @@ function serializeEntity(e: Entity): unknown {
 
 On deserialisation, reconstruct the Map from the array:
 
-```typescript
+```typescript no-check-example
 function deserializeEntity(e: any): Entity {
   const entity = { ...e } as Entity;
   if (Array.isArray(e.foodInventory)) {
@@ -189,24 +196,24 @@ function deserializeEntity(e: any): Entity {
 
 After deserialisation, the simulation can be continued from the saved state and will produce **identical results** to the original run, provided the same seed and commands are used. This is a direct consequence of the kernel’s pure‑deterministic design.
 
-> **Gotcha:** The `__sensoryEnv` and `activeFieldEffects` side‑channel fields are not required for basic combat simulation; they can be omitted during serialisation if not needed.
+> **Gotcha:** `runtimeState` and `activeFieldEffects` are optional host/runtime subsystem state; they can be omitted during serialisation for basic combat if unused.
 
 ---
 
 ## 5. Connecting to a Renderer (Bridge API)
 
-Milestone 3 delivers a complete bridge module (`src/bridge/`) that handles tick‑rate conversion, segment‑to‑bone mapping, and deterministic interpolation between simulation ticks. The bridge is a double‑buffered engine that ingests simulation snapshots at 20 Hz and provides smooth interpolated state at render frequency (60 Hz or higher).
+Milestone 3 delivers a Tier 1 stable bridge module (`src/bridge/`) that handles tick‑rate conversion, segment‑to‑bone mapping, and deterministic interpolation between simulation ticks. The bridge is a double‑buffered engine that ingests simulation snapshots at 20 Hz and provides smooth interpolated state at render frequency (60 Hz or higher).
 
 ### Key features
 
 - **Mapping system** – connect simulation segment IDs (`"leftArm"`, `"torso"`) to your skeleton’s bone names (`"arm_L"`, `"spine_02"`).
 - **Fixed‑point interpolation** – deterministic linear interpolation of positions, velocities, animation weights, pose modifiers, and condition.
 - **Extrapolation control** – optional velocity‑based prediction when render time runs ahead of simulation.
-- **Full API documentation** – see [`bridge‑api.md`](./bridge‑api.md) for detailed reference and examples.
+- **Full API documentation** – see [`bridge‑api.md`](./bridge-contract.md) for detailed reference and examples.
 
 ### Minimal setup example
 
-```typescript
+```typescript no-check-example
 import { BridgeEngine } from "ananke";
 import { extractRigSnapshots, extractMotionVectors, extractConditionSamples } from "ananke";
 
@@ -237,11 +244,11 @@ if (state) {
 
 ### Working demo
 
-Run `npm run run:bridge‑demo` to see a complete bridge workflow with humanoid and quadruped body plans, simulation loop, render‑loop simulation, and determinism verification.
+Run `npm run run:bridge-demo` to see an end-to-end bridge workflow with humanoid and quadruped body plans, simulation loop, render‑loop simulation, and determinism verification.
 
 ### Integration steps
 
-1. Read the [bridge API documentation](./bridge‑api.md) to understand mapping and interpolation details.
+1. Read the [bridge API documentation](./bridge-contract.md) to understand mapping and interpolation details.
 2. Author mappings for each body plan your game uses (humanoid, quadruped, avian, etc.).
 3. Integrate the bridge into your simulation and render threads as shown above.
 4. Use the `poseModifiers` array to drive vertex‑shader weights or morph targets for injury visualisation.
@@ -273,7 +280,7 @@ Run `npm run run:bridge‑demo` to see a complete bridge workflow with humanoid
 
 TypeScript’s `exactOptionalPropertyTypes` is enabled in the project. This means an optional property set to `undefined` is **not** the same as omitting the property. For example:
 
-```typescript
+```typescript no-check-example
 // ❌ Wrong – will cause type errors
 entity.cognition = undefined;
 
@@ -317,11 +324,11 @@ When mapping injury regions to a 3D skeleton, note that region IDs are **camelCa
 
 ## 8. Recommended Integration Steps
 
-1. **Start with the vertical slice** (`npm run run:vertical-slice`) to see a complete 1v1 duel.
+1. **Start with the vertical slice** (`npm run run:vertical-slice`) to see an end-to-end 1v1 duel.
 2. **Trace a single attack** (`npm run run:trace-attack`) to internalise the data flow.
 3. **Build an observer** that logs the state of your own entities each tick (copy `observer.ts`).
 4. **Implement save/load** using the serialisation pattern (`serialize.ts`).
-5. **Connect the 3D rig** using the bridge API (`npm run run:bridge‑demo`). See [Bridge API documentation](./bridge‑api.md).
+5. **Connect the 3D rig** using the bridge API (`npm run run:bridge-demo`). See [Bridge API documentation](./bridge-contract.md).
 6. **Profile performance** with many entities (100+) to ensure your bridge does not become a bottleneck.
 
 ---
@@ -332,4 +339,4 @@ The evaluation spike confirms that Ananke’s deterministic, physics‑first sim
 
 With this primer, a team can proceed to **Milestone 3 (Asset Pipeline & Renderer Bridge)** with a solid understanding of the kernel’s internals and the gotchas to avoid.
 
-*Generated by Claude Code during Integration Milestone 2, March 2026.*
+*Generated by Claude Code during Integration Milestone 2, March 2026.*

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

@@ -1,120 +1,102 @@
-# 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)
+# Migration guide: monolith to modular imports (state-aware)
+
+This guide separates what is available **today** from what is **planned** so adopters can migrate with accurate expectations.
+
+---
+
+## Current state (available now)
+
+- `@its-not-rocket-science/ananke` is the primary shipped package.
+- `@ananke/core`, `@ananke/combat`, `@ananke/campaign`, and `@ananke/content` are currently Phase 1 wrappers that re-export from the monolith.
+- Result: changing imports can improve API clarity, but does not yet create full package isolation or guaranteed bundle-size reductions.
+
+## In progress (partial implementation)
+
+- Package-boundary definitions and checks exist and are actively used.
+- Boundary cleanup and source ownership migration are still ongoing.
+- Until that migration is complete, modular packages should be treated as compatibility entrypoints, not fully separated codebases.
+
+## Target state (planned)
+
+- Each `@ananke/*` package will own implementation and build artifacts.
+- Dependency relationships between packages will match the declared modular DAG.
+- The monolith remains as a compatibility/meta package for teams that prefer one dependency.
+
+---
+
+## Should you migrate now?
+
+| Situation | Recommendation today |
+|---|---|
+| Existing project that already works on monolith imports | Staying on monolith is valid; no urgent change required. |
+| New project that wants explicit domain-oriented imports | Use `@ananke/*` imports, understanding they are wrappers in Phase 1. |
+| Team expecting immediate tree-shaking/size wins from modular packages | Wait for source-ownership migration milestones before expecting those gains. |
+
+---
+
+## Migration steps you can do today
+
+### 1) Install wrapper packages
+
+```bash
+# Example: combat-oriented app
+npm install @ananke/core @ananke/combat
+
+# Example: broader simulation app
+npm install @ananke/core @ananke/combat @ananke/campaign @ananke/content
+```
+
+These packages currently peer on `@its-not-rocket-science/ananke`.
+
+### 2) Update imports
+
+Use modular package names instead of monolith subpaths where practical.
+
+| Old import | Current modular 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/renown` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/kinship` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/succession` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/diplomacy` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/migration` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/trade-routes` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/military-campaign` | `@ananke/campaign` |
+| `@its-not-rocket-science/ananke/governance` | `@ananke/campaign` |
+
+> Note: for APIs not listed above, keep using monolith subpaths until corresponding modular wrapper/package coverage is explicitly documented.
+
+### 3) Verify build and tests
+
+```bash
+npm run build
+npm test
+```
+
+---
+
+## What this means for adopters today
+
+- Treat current migration as an import-surface alignment step.
+- Do not treat it as proof that implementation has already moved out of the monolith.
+- Adopting modular imports now can reduce future churn once target modular ownership lands.
+
+---
+
+## Related docs
+
+- [`docs/package-architecture.md`](package-architecture.md)
+- [`docs/module-index.md`](module-index.md)
+- [`STABLE_API.md`](../STABLE_API.md)