@its-not-rocket-science/ananke 0.1.68 → 0.5.1

package/docs/package-architecture.md

@@ -1,323 +1,116 @@
-# 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 architecture: shipped state, partial modularization, and target state
+
+This document reconciles three different things that are easy to blur together:
+
+1. What the repository and npm package ship **today**.
+2. What is **partially implemented** toward modular packages.
+3. What the **target architecture** is intended to be.
+
+---
+
+## Current state (shipped now)
+
+### What is published today
+
+The primary published package is still the monolith:
+
+- Package name: `@its-not-rocket-science/ananke`
+- Root entrypoint: `.` → `dist/src/index.js`
+- Many subpath exports (for example `./combat`, `./campaign`, `./species`, `./content`, etc.) from the same monolith build output.
+
+In other words: consumers can import many domain-specific entrypoints, but they are exported from one package build at the root.
+
+### Filesystem/layout reality
+
+- Main implementation is in `src/`.
+- Workspaces exist at `packages/*`.
+- `packages/core`, `packages/combat`, `packages/campaign`, and `packages/content` currently contain thin Phase 1 wrappers (`index.js` + `index.d.ts`) that re-export monolith entrypoints.
+- `packages/cli` exists, but it is private and points to root `dist/tools/*` binaries.
+
+### Current architecture diagram (monolith-first)
+
+```mermaid
+flowchart LR
+  App[Consumer app]
+  Mono[@its-not-rocket-science/ananke]
+  Dist[dist/src/*]
+  Src[src/* implementation]
+
+  App --> Mono
+  Mono --> Dist
+  Dist --> Src
+
+  subgraph Phase 1 workspace wrappers
+    Core[@ananke/core]
+    Combat[@ananke/combat]
+    Campaign[@ananke/campaign]
+    Content[@ananke/content]
+  end
+
+  Core -.re-exports.-> Mono
+  Combat -.re-exports.-> Mono
+  Campaign -.re-exports.-> Mono
+  Content -.re-exports.-> Mono
+```
+
+---
+
+## In progress (partially implemented)
+
+Modularization work is in progress and incomplete.
+
+### Already implemented
+
+- A modular ownership map and allowed dependency graph exist in `tools/package-boundaries.config.json`.
+- Boundary checking/report tooling exists (`tools/check-package-boundaries.ts`, `npm run check-boundaries*`).
+- Workspace package names and import surfaces for `@ananke/core`, `@ananke/combat`, `@ananke/campaign`, and `@ananke/content` are present.
+
+### Not complete yet
+
+- Boundary compliance is not yet achieved. The latest checked-in report (`docs/package-boundary-report.md`, generated 2026-04-09) still shows:
+  - hard violations,
+  - suspicious imports,
+  - and unmapped files.
+- Workspace packages are still wrappers; they do not yet own independent implementation/source trees.
+- Because wrappers re-export from the monolith, modular import paths do **not** yet imply full package isolation.
+
+---
+
+## Target state (planned)
+
+The target architecture is modular-first:
+
+- Each `@ananke/*` package owns its code, build output, and tests.
+- Cross-package imports follow the declared DAG (for example, `content -> core`, `combat -> core/content`, `campaign -> core/content`).
+- The monolith package remains as a compatibility/meta layer that re-exports modular packages for adopters who want one dependency.
+
+### Target architecture diagram (modular-first)
+
+```mermaid
+flowchart TD
+  Core[@ananke/core]
+  Content[@ananke/content]
+  Combat[@ananke/combat]
+  Campaign[@ananke/campaign]
+
+  Content --> Core
+  Combat --> Core
+  Combat --> Content
+  Campaign --> Core
+  Campaign --> Content
+
+  Meta[@its-not-rocket-science/ananke (compat/meta)]
+  Meta --> Core
+  Meta --> Content
+  Meta --> Combat
+  Meta --> Campaign
+```
+
+---
+
+## What this means for adopters today
+
+- You can safely use the monolith package now; it is the most direct reflection of shipped structure.
+- You can also use `@ananke/*` imports today, but treat them as import-path aliases/wrappers rather than fully independent packages.
+- Do not assume current modular imports provide maximum tree-shaking or strict package-boundary guarantees yet.
+- Migration to modular import paths can reduce future refactors, because those paths are intended to remain valid as ownership moves into `@ananke/*` packages.

package/docs/plugins/README.md

@@ -0,0 +1,42 @@
+# Ananke Plugin SDK
+
+Ananke plugins are third-party extensions that register one or more runtime hooks (for example `beforeStep`, `afterStep`, `afterDamage`, or `matchEnd`) and run in a constrained runtime.
+
+> ⚠️ **Security caveat (public plugin loading):** `loadPlugin(...)` is not, by itself, a complete security boundary for hostile third-party code. If you load public/untrusted plugins, read `docs/plugins/security-model.md` and apply `docs/plugins/deployment-checklist.md` before production enablement.
+
+## Write your first plugin in 10 minutes
+
+1. Create a folder under `plugins/`.
+2. Add `plugin.json` using `schema/plugin.schema.json`.
+3. Add an `index.js` file exporting `setup(api)`.
+4. Return handlers keyed by hook name.
+5. Load with `loadPlugin(path)` and call hooks with `runHook(...)`.
+
+### `plugin.json`
+
+```json
+{
+  "id": "ananke-plugin-hello",
+  "version": "1.0.0",
+  "hooks": ["afterStep"],
+  "dependencies": {},
+  "permissions": ["read:worldState", "write:telemetry"]
+}
+```
+
+### `index.js`
+
+```js
+module.exports = {
+  setup(api) {
+    return {
+      afterStep(ctx) {
+        const world = api.readWorldState(ctx.worldState);
+        api.emitTelemetry("hello.entities", { count: world.entities.length });
+      },
+    };
+  },
+};
+```
+
+See `docs/plugins/hooks.md` for the hook contract, `docs/plugins/publishing.md` for registry publication, and `docs/plugins/security-model.md` for production threat modeling.

package/docs/plugins/hooks.md

@@ -0,0 +1,22 @@
+# Hook reference
+
+## Core lifecycle hooks
+
+- `beforeStep(context)` — called before simulation step execution.
+- `afterStep(context)` — called after a simulation step has completed.
+- `afterDamage(context)` — called after a damage event resolves.
+- `matchEnd(context)` — called once at end-of-match with summary fields.
+
+## Plugin runtime API
+
+- `hasPermission(permission)`
+- `readWorldState(value)`
+- `mutateWorld(worldState, mutator)` (requires `write:worldState`)
+- `emitTelemetry(metric, payload)` (requires `write:telemetry`)
+- `writeArtifact(path, contents)` (requires `write:artifacts`)
+
+## Permission examples
+
+- Read-only observer plugin: `permissions: ["read:worldState"]`
+- Analytics plugin with reports: `permissions: ["read:events", "write:artifacts"]`
+- Full gameplay mutator: `permissions: ["read:worldState", "write:worldState"]`

package/docs/plugins/publishing.md

@@ -0,0 +1,29 @@
+# Publishing plugins to `ananke-plugins`
+
+The plugin registry is a GitHub repository that exposes a JSON index consumed by `ananke install <plugin>`.
+
+> ⚠️ **Security caveat (public registry):** Registry publication increases exposure to untrusted plugin code paths. Production operators should treat all third-party plugins as untrusted by default and apply `docs/plugins/security-model.md` and `docs/plugins/deployment-checklist.md` before enabling plugins.
+
+## Registry structure
+
+- `index.json` at repo root
+- one directory per plugin containing `plugin.json` and `index.js`
+
+Example entry:
+
+```json
+{
+  "name": "ananke-plugin-logger",
+  "manifestUrl": "https://raw.githubusercontent.com/its-not-rocket-science/ananke-plugins/main/ananke-plugin-logger/plugin.json",
+  "moduleUrl": "https://raw.githubusercontent.com/its-not-rocket-science/ananke-plugins/main/ananke-plugin-logger/index.js"
+}
+```
+
+## CI validation workflow
+
+1. Install latest Ananke package.
+2. Validate each `plugin.json` against `schema/plugin.schema.json`.
+3. Load each plugin with `loadPlugin` smoke test.
+4. Run plugin-specific test suite.
+
+This keeps registry plugins compatible with the latest API.