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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/docs/migration-monolith-to-modular.md +120 -0
  3. package/docs/package-architecture.md +323 -0
  4. package/package.json +6 -1
package/CHANGELOG.md CHANGED
@@ -6,6 +6,24 @@ Versioning follows [Semantic Versioning](https://semver.org/).
6
6
 
7
7
  ---
8
8
 
9
+ ## [0.1.51] — 2026-03-28
10
+
11
+ ### Added
12
+
13
+ - **PA-2 — Modular Package Architecture (Phase 1 complete):**
14
+ - `packages/core/` — `@ananke/core` stub; re-exports the full main `"."` entry point (kernel, entity model, units, RNG, replay, bridge).
15
+ - `packages/combat/` — `@ananke/combat` stub; re-exports `"./combat"`, `"./anatomy"`, `"./competence"`, `"./wasm-kernel"`.
16
+ - `packages/campaign/` — `@ananke/campaign` stub; re-exports all 32 campaign-scale subpaths (polity, social, narrative, feudal, demography, economy, military…).
17
+ - `packages/content/` — `@ananke/content` stub; re-exports `"./species"`, `"./catalog"`, `"./character"`, `"./crafting"`.
18
+ - Each stub ships a pre-built `index.js` + `index.d.ts` (no separate compilation step); `@its-not-rocket-science/ananke` is a peer dependency.
19
+ - Root `package.json` gains `"workspaces": ["packages/*"]` for local linking.
20
+ - `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.
21
+ - `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.
22
+ - `docs/package-architecture.md` and `docs/migration-monolith-to-modular.md` added to `package.json` `"files"` so they ship with the published package.
23
+ - Build: clean. Tests: 5,261 passing. Coverage unchanged.
24
+
25
+ ---
26
+
9
27
  ## [0.1.50] — 2026-03-28
10
28
 
11
29
  ### Docs
package/docs/migration-monolith-to-modular.md ADDED
@@ -0,0 +1,120 @@
1
+ # Migration Guide: Monolith to Modular Packages
2
+
3
+ This guide covers how to migrate from `@its-not-rocket-science/ananke` to the
4
+ focused `@ananke/*` packages. Migration is optional — the monolith package is
5
+ maintained indefinitely for backwards compatibility.
6
+
7
+ ---
8
+
9
+ ## Should you migrate?
10
+
11
+ | Situation | Recommendation |
12
+ |-----------|----------------|
13
+ | Existing project, everything working | Stay on the monolith. No action required. |
14
+ | New project, only needs combat | Start with `@ananke/combat` + `@ananke/core` |
15
+ | New project, full simulation stack | Use the monolith; migrate to modular when convenient |
16
+ | Bundle size is a concern (Phase 2+) | Migrate after Phase 2 (source migration) for real tree-shaking |
17
+
18
+ ---
19
+
20
+ ## Phase 1 Migration (stubs — available now)
21
+
22
+ Phase 1 packages are thin wrappers that re-export from the monolith. Bundle
23
+ size is unchanged, but import paths are cleaner and signal which API tier you
24
+ depend on.
25
+
26
+ ### Step 1 — Install the sub-package(s) you need
27
+
28
+ ```bash
29
+ # Combat-only host
30
+ npm install @ananke/core @ananke/combat
31
+
32
+ # Full world simulation
33
+ npm install @ananke/core @ananke/combat @ananke/campaign @ananke/content
34
+ ```
35
+
36
+ The monolith is installed automatically as a peer dependency.
37
+
38
+ ### Step 2 — Update imports
39
+
40
+ Replace monolith paths with the appropriate package name:
41
+
42
+ | Old import | New import |
43
+ |-----------|-----------|
44
+ | `@its-not-rocket-science/ananke` | `@ananke/core` |
45
+ | `@its-not-rocket-science/ananke/combat` | `@ananke/combat` |
46
+ | `@its-not-rocket-science/ananke/anatomy` | `@ananke/combat` |
47
+ | `@its-not-rocket-science/ananke/competence` | `@ananke/combat` |
48
+ | `@its-not-rocket-science/ananke/wasm-kernel` | `@ananke/combat` |
49
+ | `@its-not-rocket-science/ananke/species` | `@ananke/content` |
50
+ | `@its-not-rocket-science/ananke/catalog` | `@ananke/content` |
51
+ | `@its-not-rocket-science/ananke/character` | `@ananke/content` |
52
+ | `@its-not-rocket-science/ananke/crafting` | `@ananke/content` |
53
+ | `@its-not-rocket-science/ananke/campaign` | `@ananke/campaign` |
54
+ | `@its-not-rocket-science/ananke/polity` | `@ananke/campaign` |
55
+ | `@its-not-rocket-science/ananke/social` | `@ananke/campaign` |
56
+ | `@its-not-rocket-science/ananke/narrative` | `@ananke/campaign` |
57
+ | `@its-not-rocket-science/ananke/narrative-prose` | `@ananke/campaign` |
58
+ | `@its-not-rocket-science/ananke/renown` | `@ananke/campaign` |
59
+ | `@its-not-rocket-science/ananke/kinship` | `@ananke/campaign` |
60
+ | `@its-not-rocket-science/ananke/succession` | `@ananke/campaign` |
61
+ | `@its-not-rocket-science/ananke/calendar` | `@ananke/campaign` |
62
+ | `@its-not-rocket-science/ananke/feudal` | `@ananke/campaign` |
63
+ | `@its-not-rocket-science/ananke/diplomacy` | `@ananke/campaign` |
64
+ | `@its-not-rocket-science/ananke/migration` | `@ananke/campaign` |
65
+ | `@its-not-rocket-science/ananke/espionage` | `@ananke/campaign` |
66
+ | `@its-not-rocket-science/ananke/trade-routes` | `@ananke/campaign` |
67
+ | `@its-not-rocket-science/ananke/siege` | `@ananke/campaign` |
68
+ | `@its-not-rocket-science/ananke/faith` | `@ananke/campaign` |
69
+ | `@its-not-rocket-science/ananke/demography` | `@ananke/campaign` |
70
+ | `@its-not-rocket-science/ananke/granary` | `@ananke/campaign` |
71
+ | `@its-not-rocket-science/ananke/epidemic` | `@ananke/campaign` |
72
+ | `@its-not-rocket-science/ananke/infrastructure` | `@ananke/campaign` |
73
+ | `@its-not-rocket-science/ananke/unrest` | `@ananke/campaign` |
74
+ | `@its-not-rocket-science/ananke/research` | `@ananke/campaign` |
75
+ | `@its-not-rocket-science/ananke/taxation` | `@ananke/campaign` |
76
+ | `@its-not-rocket-science/ananke/military-campaign` | `@ananke/campaign` |
77
+ | `@its-not-rocket-science/ananke/governance` | `@ananke/campaign` |
78
+ | `@its-not-rocket-science/ananke/resources` | `@ananke/campaign` |
79
+ | `@its-not-rocket-science/ananke/climate` | `@ananke/campaign` |
80
+ | `@its-not-rocket-science/ananke/famine` | `@ananke/campaign` |
81
+ | `@its-not-rocket-science/ananke/containment` | `@ananke/campaign` |
82
+ | `@its-not-rocket-science/ananke/mercenaries` | `@ananke/campaign` |
83
+ | `@its-not-rocket-science/ananke/wonders` | `@ananke/campaign` |
84
+ | `@its-not-rocket-science/ananke/monetary` | `@ananke/campaign` |
85
+
86
+ ### Step 3 — Verify
87
+
88
+ ```bash
89
+ npm run build # or tsc --noEmit
90
+ npm test
91
+ ```
92
+
93
+ No other changes are needed.
94
+
95
+ ---
96
+
97
+ ## Phase 2 Migration (source migration — planned)
98
+
99
+ When Phase 2 lands, `@ananke/combat` will no longer depend on the monolith.
100
+ The import paths remain identical — only the transitive dependency graph changes.
101
+
102
+ **No code changes required in your project for Phase 2.**
103
+
104
+ Run `npm update` when the new versions are published; your bundler will
105
+ automatically produce a smaller output.
106
+
107
+ ---
108
+
109
+ ## Staying on the monolith
110
+
111
+ If you prefer to keep using `@its-not-rocket-science/ananke` directly, nothing
112
+ changes. The 41 subpath exports are stable and will not be removed.
113
+
114
+ ---
115
+
116
+ ## See also
117
+
118
+ - [`docs/package-architecture.md`](package-architecture.md) — full design document and source file mapping
119
+ - [`docs/module-index.md`](module-index.md) — all exports with stability tiers and use cases
120
+ - [`STABLE_API.md`](../STABLE_API.md) — stable API surface (Tier 1)
package/docs/package-architecture.md ADDED
@@ -0,0 +1,323 @@
1
+ # Ananke — Modular Package Architecture
2
+
3
+ > **Status: Phase 1 complete** — Package stubs with re-exports are published.
4
+ > Phase 2 (source migration) moves code into individual packages so combat has
5
+ > no campaign dependency at the module level.
6
+
7
+ ---
8
+
9
+ ## Problem
10
+
11
+ `@its-not-rocket-science/ananke` ships 41 subpath exports in a single package.
12
+ A host that only needs tactical combat transitively depends on feudal succession,
13
+ epidemic simulation, and monetary policy. A renderer integration author has no
14
+ clean way to depend only on the bridge layer.
15
+
16
+ ---
17
+
18
+ ## Package Overview
19
+
20
+ | Package | Stability | Description | Key entry point(s) |
21
+ |---------|-----------|-------------|-------------------|
22
+ | `@ananke/core` | **Stable** | Kernel, entity model, fixed-point units, RNG, replay | `"@ananke/core"` |
23
+ | `@ananke/combat` | Experimental | Combat resolution, anatomy, grapple, ranged, competence | `"@ananke/combat"` |
24
+ | `@ananke/campaign` | Experimental | World simulation — polity, economy, social, demography | `"@ananke/campaign"` |
25
+ | `@ananke/content` | Experimental | Species, equipment catalogue, archetypes, crafting | `"@ananke/content"` |
26
+ | `@ananke/bridge` | Experimental | Renderer bridge, interpolation, animation hints *(Phase 2)* | `"@ananke/bridge"` |
27
+ | `@its-not-rocket-science/ananke` | **Meta-package** | Re-exports all of the above for backwards compatibility | unchanged |
28
+
29
+ > `@ananke/bridge` is not yet a standalone stub — bridge exports are part of
30
+ > `@ananke/core` until Phase 2 adds a dedicated `"./bridge"` subpath to the
31
+ > monolith.
32
+
33
+ ---
34
+
35
+ ## Package Dependency Graph
36
+
37
+ ```
38
+ @ananke/core
39
+ │
40
+ ├── @ananke/combat (peer: @ananke/core)
41
+ ├── @ananke/campaign (peer: @ananke/core)
42
+ ├── @ananke/content (peer: @ananke/core)
43
+ └── @ananke/bridge (peer: @ananke/core) [Phase 2]
44
+
45
+ @its-not-rocket-science/ananke (meta: re-exports all four)
46
+ ```
47
+
48
+ ---
49
+
50
+ ## Monolith Subpath → Package Mapping
51
+
52
+ ### @ananke/core
53
+
54
+ | Monolith subpath | Notes |
55
+ |-----------------|-------|
56
+ | `"."` | Entire main export — kernel, entity, units, RNG, replay, bridge |
57
+
58
+ ### @ananke/combat
59
+
60
+ | Monolith subpath | Notes |
61
+ |-----------------|-------|
62
+ | `"./combat"` | resolveHit, resolveBlock, CombatContext |
63
+ | `"./anatomy"` | BodyPlan, AnatomyRegion, injury regions |
64
+ | `"./competence"` | skill contest resolution, interspecies signalling |
65
+ | `"./wasm-kernel"` | WASM-accelerated combat math |
66
+
67
+ ### @ananke/campaign
68
+
69
+ | Monolith subpath | Notes |
70
+ |-----------------|-------|
71
+ | `"./campaign"` | Campaign layer, strategic tick |
72
+ | `"./polity"` | Polity, stepPolityDay, tech diffusion |
73
+ | `"./social"` | Social relationships, dialogue |
74
+ | `"./narrative"` | Narrative event system |
75
+ | `"./narrative-prose"` | Prose generation |
76
+ | `"./renown"` | Fame and reputation |
77
+ | `"./kinship"` | Family trees, genealogy |
78
+ | `"./succession"` | Inheritance rules |
79
+ | `"./calendar"` | In-world calendar and date tracking |
80
+ | `"./feudal"` | Feudal hierarchy |
81
+ | `"./diplomacy"` | Treaties and diplomatic acts |
82
+ | `"./migration"` | Population movement |
83
+ | `"./espionage"` | Espionage and spycraft |
84
+ | `"./trade-routes"` | Trade route simulation |
85
+ | `"./siege"` | Siege warfare mechanics |
86
+ | `"./faith"` | Religion and doctrine |
87
+ | `"./demography"` | Population simulation |
88
+ | `"./granary"` | Food storage and distribution |
89
+ | `"./epidemic"` | Disease spread |
90
+ | `"./infrastructure"` | Buildings and construction |
91
+ | `"./unrest"` | Civil unrest |
92
+ | `"./research"` | Technology research |
93
+ | `"./taxation"` | Tax collection |
94
+ | `"./military-campaign"` | Military campaign mechanics |
95
+ | `"./governance"` | Governance and edicts |
96
+ | `"./resources"` | Resource management |
97
+ | `"./climate"` | Climate and weather effects |
98
+ | `"./famine"` | Famine simulation |
99
+ | `"./containment"` | Disease containment |
100
+ | `"./mercenaries"` | Mercenary companies |
101
+ | `"./wonders"` | Wonders and monuments |
102
+ | `"./monetary"` | Monetary policy and currency |
103
+
104
+ ### @ananke/content
105
+
106
+ | Monolith subpath | Notes |
107
+ |-----------------|-------|
108
+ | `"./species"` | Species definitions, stat profiles |
109
+ | `"./catalog"` | Equipment and item catalogue |
110
+ | `"./character"` | Character generation and archetypes |
111
+ | `"./crafting"` | Crafting recipes, workshops, manufacturing |
112
+
113
+ ---
114
+
115
+ ## Source File → Package Mapping (Phase 2 migration)
116
+
117
+ ### @ananke/core
118
+ ```
119
+ src/units.ts
120
+ src/rng.ts
121
+ src/types.ts
122
+ src/replay.ts
123
+ src/sim/entity.ts
124
+ src/sim/kernel.ts
125
+ src/sim/seeds.ts
126
+ src/sim/world.ts
127
+ src/sim/kinds.ts
128
+ src/sim/condition.ts
129
+ src/sim/body.ts
130
+ src/sim/bodyplan.ts
131
+ src/sim/limb.ts
132
+ src/sim/tick.ts
133
+ src/sim/indexing.ts
134
+ src/sim/events.ts
135
+ src/sim/commands.ts
136
+ src/sim/commandBuilders.ts
137
+ src/sim/context.ts
138
+ src/sim/intent.ts
139
+ src/sim/vec3.ts
140
+ src/sim/spatial.ts
141
+ src/sim/skills.ts
142
+ src/sim/traits.ts
143
+ src/sim/terrain.ts
144
+ src/sim/action.ts
145
+ src/sim/step/ (all 10 step files)
146
+ src/bridge/ (all 5 bridge files)
147
+ src/presets.ts
148
+ src/generate.ts
149
+ src/derive.ts
150
+ src/describe.ts
151
+ src/traits.ts
152
+ src/metrics.ts
153
+ src/dist.ts
154
+ src/wasm-kernel.ts
155
+ ```
156
+
157
+ ### @ananke/combat
158
+ ```
159
+ src/sim/combat.ts
160
+ src/sim/injury.ts
161
+ src/sim/wound-aging.ts
162
+ src/sim/medical.ts
163
+ src/sim/morale.ts
164
+ src/sim/grapple.ts
165
+ src/sim/ranged.ts
166
+ src/sim/stamina.ts (if present)
167
+ src/sim/impairment.ts
168
+ src/sim/knockback.ts
169
+ src/sim/cover.ts
170
+ src/sim/cone.ts
171
+ src/sim/formation.ts
172
+ src/sim/formation-combat.ts
173
+ src/sim/formation-unit.ts
174
+ src/sim/frontage.ts
175
+ src/sim/density.ts
176
+ src/sim/occlusion.ts
177
+ src/sim/ai/ (all 8 AI files)
178
+ src/combat.ts
179
+ src/equipment.ts
180
+ src/weapons.ts
181
+ src/anatomy/ (all 5 anatomy files)
182
+ src/competence/ (all 13 competence files)
183
+ src/arena.ts
184
+ src/dialogue.ts
185
+ src/party.ts
186
+ src/faction.ts
187
+ src/downtime.ts
188
+ ```
189
+
190
+ ### @ananke/campaign
191
+ ```
192
+ src/campaign.ts
193
+ src/campaign-layer.ts
194
+ src/polity.ts
195
+ src/polity-vassals.ts
196
+ src/social.ts
197
+ src/relationships.ts
198
+ src/relationships-effects.ts
199
+ src/emotional-contagion.ts
200
+ src/narrative.ts
201
+ src/narrative-layer.ts
202
+ src/narrative-prose.ts
203
+ src/narrative-render.ts
204
+ src/narrative-stress.ts
205
+ src/story-arcs.ts
206
+ src/quest.ts
207
+ src/quest-generators.ts
208
+ src/chronicle.ts
209
+ src/legend.ts
210
+ src/mythology.ts
211
+ src/renown.ts
212
+ src/kinship.ts
213
+ src/succession.ts
214
+ src/calendar.ts
215
+ src/feudal.ts
216
+ src/diplomacy.ts
217
+ src/migration.ts
218
+ src/espionage.ts
219
+ src/trade-routes.ts
220
+ src/siege.ts
221
+ src/faith.ts
222
+ src/demography.ts
223
+ src/granary.ts
224
+ src/epidemic.ts
225
+ src/infrastructure.ts
226
+ src/unrest.ts
227
+ src/research.ts
228
+ src/taxation.ts
229
+ src/military-campaign.ts
230
+ src/governance.ts
231
+ src/resources.ts
232
+ src/climate.ts
233
+ src/famine.ts
234
+ src/containment.ts
235
+ src/mercenaries.ts
236
+ src/wonders.ts
237
+ src/monetary.ts
238
+ src/collective-activities.ts
239
+ src/economy.ts
240
+ src/economy-gen.ts
241
+ src/tech-diffusion.ts
242
+ src/culture.ts
243
+ src/settlement.ts
244
+ src/settlement-services.ts
245
+ src/channels.ts
246
+ src/inheritance.ts
247
+ src/progression.ts
248
+ src/sim/disease.ts
249
+ src/sim/aging.ts
250
+ src/sim/sleep.ts
251
+ src/sim/mount.ts
252
+ src/sim/hazard.ts
253
+ src/sim/nutrition.ts
254
+ src/sim/thermoregulation.ts
255
+ src/sim/toxicology.ts
256
+ src/sim/systemic-toxicology.ts
257
+ src/sim/substance.ts
258
+ src/sim/weather.ts
259
+ src/sim/biome.ts
260
+ src/sim/tech.ts
261
+ ```
262
+
263
+ ### @ananke/content
264
+ ```
265
+ src/species.ts
266
+ src/catalog.ts
267
+ src/character.ts
268
+ src/archetypes.ts
269
+ src/crafting/ (all 5 crafting files)
270
+ src/inventory.ts
271
+ src/item-durability.ts
272
+ src/snapshot.ts
273
+ src/world-generation.ts
274
+ src/world-factory.ts
275
+ src/scenario.ts
276
+ src/modding.ts
277
+ src/lod.ts
278
+ src/model3d.ts
279
+ ```
280
+
281
+ ---
282
+
283
+ ## Phase 2: Source Migration Plan
284
+
285
+ 1. **Create workspace package directories** with their own `tsconfig.build.json`.
286
+ 2. **Move source files** from `src/` into `packages/NAME/src/` following the table above.
287
+ 3. **Update internal imports** — use `@ananke/core` etc. instead of relative paths that cross
288
+ package boundaries.
289
+ 4. **Wire inter-package dependencies** — `@ananke/combat` lists `@ananke/core` as a dependency.
290
+ 5. **Update the monolith meta-package** (`@its-not-rocket-science/ananke`) to re-export from
291
+ the five sub-packages instead of from `src/`.
292
+ 6. **Verify** that all existing tests pass without modification (test paths remain unchanged).
293
+
294
+ The most complex step is (3) — identifying which imports cross package boundaries. A planned
295
+ tool (`tools/check-package-boundaries.ts`) will analyse the import graph and report violations.
296
+
297
+ ---
298
+
299
+ ## What Changes for Package Consumers
300
+
301
+ ### Phase 1 (now — stubs)
302
+ ```typescript
303
+ // Before (monolith)
304
+ import { resolveHit } from "@its-not-rocket-science/ananke/combat";
305
+
306
+ // After (modular stub — same bundle size, cleaner import path)
307
+ import { resolveHit } from "@ananke/combat";
308
+ ```
309
+
310
+ ### Phase 2 (source migration — smaller bundles)
311
+ ```typescript
312
+ // Same import — but now @ananke/combat has no campaign dependency
313
+ import { resolveHit } from "@ananke/combat";
314
+ ```
315
+
316
+ The import path is the same in Phase 1 and Phase 2; only the bundle contents change.
317
+
318
+ ---
319
+
320
+ ## Backwards Compatibility
321
+
322
+ `@its-not-rocket-science/ananke` will remain published indefinitely as a meta-package.
323
+ All 41 subpath exports will continue to work. Existing hosts do not need to migrate.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@its-not-rocket-science/ananke",
3
- "version": "0.1.50",
3
+ "version": "0.1.51",
4
4
  "type": "module",
5
5
  "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
6
6
  "license": "MIT",
@@ -172,6 +172,9 @@
172
172
  "types": "./dist/src/monetary.d.ts"
173
173
  }
174
174
  },
175
+ "workspaces": [
176
+ "packages/*"
177
+ ],
175
178
  "files": [
176
179
  "dist/src",
177
180
  "dist/as",
@@ -182,6 +185,8 @@
182
185
  "docs/performance.md",
183
186
  "docs/versioning.md",
184
187
  "docs/emergent-validation-report.md",
188
+ "docs/package-architecture.md",
189
+ "docs/migration-monolith-to-modular.md",
185
190
  "CHANGELOG.md",
186
191
  "STABLE_API.md"
187
192
  ],