@its-not-rocket-science/ananke 0.1.11 → 0.1.13

package/CHANGELOG.md

@@ -10,6 +10,44 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ### Added
 
+- **Phase 70 · Stratified Political Simulation ("Vassal Web" Layer)** (`src/polity-vassals.ts`)
+  - `VassalNode` — intermediate layer between Entity and Polity with `territory_Q`,
+    `military_Q`, `treasury_cu`, and a `VassalLoyalty` block.
+  - Seven `LoyaltyType` variants with distinct `stepVassalLoyalty` dynamics:
+    `ideological` (slow, conviction-driven), `transactional` (treasury comparison),
+    `terrified` (instant collapse if liege appears weak), `honor_bound` (oath + grievance
+    spike), `opportunistic` (tracks liege/rival morale ratio), `kin_bound` (stable family
+    ties), `ideological_rival` (constant decay, cannot recover).
+  - `applyGrievanceEvent` — immutable grievance accumulation (host applies broken-promise,
+    tax-hike, kin-death events).
+  - `computeVassalContribution` — loyalty-scaled troop and treasury output; zero below
+    `CONTRIBUTION_FLOOR_Q` (q(0.20)), full above `CONTRIBUTION_FULL_Q` (q(0.50)).
+  - `computeEffectiveMilitary` — sums contributions for command-chain filtering before
+    passing force ratio to Phase 69 `resolveTacticalEngagement`.
+  - `detectRebellionRisk` — Q score (70% low-loyalty + 30% high-grievance) for AI queries.
+  - `resolveSuccessionCrisis` — deterministic heir-support rolls weighted by `military_Q`;
+    winners gain +q(0.05) loyalty, losers −q(0.08); `SuccessionResult` with `supportQ`
+    and per-vassal `loyaltyDeltas`.
+  - 40 tests in `test/polity-vassals.test.ts`; exported via `ananke/campaign` subpath.
+
+- **Option B · Tier 2 subpath exports** — eight new named import subpaths for all
+  Tier 2 module groupings; deep imports remain supported as a fallback:
+  - `ananke/character` → aging, sleep, disease, wound-aging, thermoregulation, nutrition,
+    medical, toxicology, progression
+  - `ananke/combat` → ranged, grapple, formation-combat, mount, hazard, morale, sensory,
+    sensory-extended, weather, terrain, skills, biome
+  - `ananke/campaign` → campaign, downtime, collective-activities, settlement,
+    settlement-services, inventory, item-durability, world-generation, inheritance,
+    economy, polity (campaign layer barrel)
+  - `ananke/social` → dialogue, faction, relationships, relationships-effects, party,
+    quest, quest-generators
+  - `ananke/narrative` → chronicle, story-arcs, narrative-render, legend, mythology,
+    narrative, narrative-stress, metrics, arena
+  - `ananke/anatomy` → existing `src/anatomy/index.ts` barrel
+  - `ananke/crafting` → existing `src/crafting/index.ts` barrel
+  - `ananke/competence` → existing `src/competence/index.ts` barrel
+  - `STABLE_API.md` updated to document preferred subpath import patterns.
+
 - **CE-16 · Modding Support** (`src/modding.ts`)
   - Layer 1 — `hashMod(json)`: deterministic FNV-1a fingerprint (8-char hex) for any
     parsed JSON mod file; canonical key-sorted serialisation ensures order-independence.

package/STABLE_API.md

@@ -185,21 +185,124 @@ version bump; renames require a major bump and migration guide.
 These exports are usable and tested but may change across minor versions.
 A `CHANGELOG.md` entry will document any breaking change.
 
+Tier 2 modules are accessible via **named subpath exports** (preferred) or deep imports:
+
+```typescript
+// Preferred — named subpath (stable grouping, no internal path coupling)
+import { stepAging, applyAgingToAttributes } from "@its-not-rocket-science/ananke/character";
+import { resolveRangedAttack, stepGrapple }  from "@its-not-rocket-science/ananke/combat";
+import { stepCampaignDay, createSettlement }  from "@its-not-rocket-science/ananke/campaign";
+import { dialogueProbability, effectiveStanding } from "@its-not-rocket-science/ananke/social";
+import { addChronicleEntry, detectStoryArcs } from "@its-not-rocket-science/ananke/narrative";
+import { compileAnatomyDefinition }           from "@its-not-rocket-science/ananke/anatomy";
+import { craftItem, getAvailableRecipes }     from "@its-not-rocket-science/ananke/crafting";
+import { resolveCompetence }                  from "@its-not-rocket-science/ananke/competence";
+
+// Deep import (fallback — internal paths may change)
+import { stepAging } from "@its-not-rocket-science/ananke/dist/src/sim/aging.js";
+```
+
+### AI command system
+
+| Module | Key exports |
+|--------|------------|
+| `src/sim/ai/system.ts` | `buildAICommands(world, ctx)` — build a `CommandMap` for all AI-controlled entities |
+
+### Character lifecycle
+
 | Module | Key exports |
 |--------|------------|
-| `src/mythology.ts` | `compressMythsFromHistory`, `stepMythologyYear`, `aggregateFactionMythEffect`, `scaledMythEffect` |
-| `src/narrative-stress.ts` | `runNarrativeStressTest`, `scoreNarrativePush` |
-| `src/campaign.ts` | `Campaign`, `stepCampaignDay`, `advanceCampaignClock`, `serializeCampaign`, `deserializeCampaign` |
-| `src/arena.ts` | Arena scenario DSL, `runArenaTrial`, `runArenaScenario` |
 | `src/sim/aging.ts` | `applyAgingToAttributes`, `stepAging`, `deriveAgeMultipliers`, `getAgePhase` |
 | `src/sim/sleep.ts` | `applySleepToAttributes`, `stepSleep`, `deriveSleepDeprivationMuls`, `circadianAlertness` |
 | `src/sim/disease.ts` | `exposeToDisease`, `stepDiseaseForEntity`, `spreadDisease`, `computeTransmissionRisk` |
+| `src/sim/wound-aging.ts` | `stepWoundAging`, `recordTraumaEvent`, `deriveFearThresholdMul`, `deriveSepsisRisk` |
+| `src/sim/thermoregulation.ts` | `stepThermoregulation`, `deriveThermalComfort`, `computeMetabolicRate` |
+| `src/sim/nutrition.ts` | `stepNutrition`, `computeHungerEffect`, food catalogue constants |
+| `src/sim/medical.ts` | `resolveTreatment`, `computeTreatmentEffect`, medical tier definitions |
+| `src/sim/toxicology.ts` | `applyVenom`, `stepActiveVenoms`, `resolveIngestedToxin` |
+| `src/progression.ts` | `applyXP`, `applyTrainingDrift`, `computeMilestones` |
+
+### Combat extensions
+
+| Module | Key exports |
+|--------|------------|
 | `src/sim/mount.ts` | `checkMountStep`, `computeChargeBonus`, `deriveRiderHeightBonus` |
 | `src/sim/hazard.ts` | `deriveHazardEffect`, `computeHazardExposure`, `stepHazardZone` |
+| `src/sim/ranged.ts` | `resolveRangedAttack`, `computeRangedAccuracy`, `computeProjectileEnergy` |
+| `src/sim/grapple.ts` | `resolveGrappleContest`, `computeGrappleStrength`, `stepGrapple` |
+| `src/sim/formation.ts` | `FormationConfig`, `computeFormationBonus`, `resolveFormationStep` |
+| `src/sim/morale.ts` | `computeMoraleEffect`, `stepMorale`, `applyRoutEffect` |
+| `src/sim/sensory.ts` | `computeVisibility`, `computeHearingRange`, `stepSensoryState` |
+| `src/sim/sensory-extended.ts` | `computeEcholocationRange`, `computeOlfactionRange` — non-human senses |
+| `src/sim/weather.ts` | `WeatherState`, `stepWeather`, `computeWeatherEffect` |
+| `src/sim/terrain.ts` | `TerrainType`, `TERRAIN_PROFILES`, `computeTerrainTraction` |
+| `src/sim/skills.ts` | `SkillId`, `SkillLevel`, `SKILL_LEVEL_MULS`, `buildSkillMap`, `getSkillMul` |
+| `src/sim/biome.ts` | `BiomeType`, `BIOME_PROFILES`, `deriveBiomeEnvironment` |
+
+### Social and economic systems
+
+| Module | Key exports |
+|--------|------------|
 | `src/dialogue.ts` | `resolveIntimidation`, `resolvePersuasion`, `resolveDeception`, `resolveTradeNegotiation` |
 | `src/faction.ts` | `FactionRegistry`, `updateStanding`, `getFactionStanding` |
 | `src/economy.ts` | `computeItemValue`, `applyWear`, `resolveDrops`, `evaluateTradeOffer` |
-| `src/progression.ts` | `applyXP`, `applyTrainingDrift`, `computeMilestones` |
+| `src/relationships.ts` | `createRelationshipGraph`, `establishRelationship`, `recordEvent`, `getRelationshipAffinity` |
+| `src/relationships-effects.ts` | Relationship modifiers applied to dialogue, teaching, morale contexts |
+| `src/party.ts` | `createPartyRegistry`, `createParty`, `addPartyMember`, `setPartyStanding` |
+
+### Campaign and world management
+
+| Module | Key exports |
+|--------|------------|
+| `src/campaign.ts` | `Campaign`, `stepCampaignDay`, `advanceCampaignClock`, `serializeCampaign`, `deserializeCampaign` |
+| `src/downtime.ts` | `stepDowntime`, `TreatmentSchedule`, `EntityRecoveryReport` |
+| `src/collective-activities.ts` | `createCollectiveProject`, `contributeToCollectiveProject`, `stepRitual`, `planCaravanRoute` |
+| `src/inventory.ts` | `createInventory`, `addItemToInventory`, `consumeItemsByTemplateId`, `getEncumbrancePenalty` |
+| `src/item-durability.ts` | `stepWear`, `applyWearPenalty` |
+| `src/settlement.ts` | `createSettlement`, `upgradeSettlement`, `getServiceBonus` |
+| `src/settlement-services.ts` | Service definitions (forge, medical, market, barracks, temple) |
+| `src/inheritance.ts` | `transferEquipment`, `transferRelationships`, `transferInventory` — character death succession |
+| `src/world-generation.ts` | `generateWorld`, `deriveStartingRelationships`, `deriveStartingConflicts` |
+
+### Quest and narrative layer
+
+| Module | Key exports |
+|--------|------------|
+| `src/quest.ts` | `questFactory`, `updateQuestState`, `resolveObjective`, `Quest`, `QuestObjective` |
+| `src/quest-generators.ts` | `generateBountyQuest`, `generateEscortQuest`, `generateRetrievalQuest` |
+| `src/chronicle.ts` | `createChronicle`, `addChronicleEntry`, `getEntriesForEntity`, `ChronicleEntry` |
+| `src/story-arcs.ts` | `detectStoryArcs`, `updateDetectedArcs` — pattern detection across chronicle entries |
+| `src/narrative-render.ts` | `renderEntry`, `renderArcSummary` — template-based prose from chronicle entries |
+| `src/legend.ts` | `createLegendRegistry`, `createLegendFromChronicle`, `applyLegendToDialogueContext` |
+| `src/mythology.ts` | `compressMythsFromHistory`, `stepMythologyYear`, `aggregateFactionMythEffect`, `scaledMythEffect` |
+| `src/narrative.ts` | `narrateCombatTick`, `narrateInjury` — human-readable combat event strings |
+| `src/narrative-stress.ts` | `runNarrativeStressTest`, `scoreNarrativePush` |
+| `src/metrics.ts` | `extractCombatMetrics`, `summariseBattle` — analytics from trace events |
+| `src/arena.ts` | Arena scenario DSL, `runArenaTrial`, `runArenaScenario` |
+
+### Anatomy subsystem
+
+| Module | Key exports |
+|--------|------------|
+| `src/anatomy/index.ts` | Re-export barrel for the full anatomy API |
+| `src/anatomy/anatomy-contracts.ts` | `CompiledAnatomyModel`, `AnatomyContracts`, `AnatomyCapabilities` — core anatomy types |
+| `src/anatomy/anatomy-schema.ts` | `validateExtendedBodyPlan`, `ValidationResult` — validate JSON body plan definitions |
+| `src/anatomy/anatomy-compiler.ts` | `compileAnatomyDefinition`, `compileAnatomyDefinitionOrThrow` — compile a body plan to indexed model |
+| `src/anatomy/anatomy-helpers.ts` | `createAnatomyHelpers`, `summarizeFunctionalHealth`, `sampleProfile` — query compiled anatomy |
+
+### Competence framework
+
+| Module | Key exports |
+|--------|------------|
+| `src/competence/index.ts` | Re-export barrel for the full competence API |
+| `src/competence/framework.ts` | `resolveCompetence(entity, action, ctx)` — unified competence resolution dispatcher |
+| `src/competence/catalogue.ts` | `CompetenceDomain`, `CompetenceTask`, predefined task catalogue entries |
+
+### Crafting subsystem
+
+| Module | Key exports |
+|--------|------------|
+| `src/crafting/index.ts` | `craftItem`, `startManufacturing`, `advanceManufacturing`, `getAvailableRecipes` — main crafting API |
 
 ---
 
@@ -207,16 +310,72 @@ A `CHANGELOG.md` entry will document any breaking change.
 
 These are implementation details.  Do not import them directly; they may change at any time.
 
+### Kernel internals
+
 | Module | Why internal |
 |--------|-------------|
 | `src/rng.ts` | `makeRng`, `eventSeed`, `hashString` — RNG contract is internal; seed structure may change |
+| `src/sim/seeds.ts` | Seed derivation utilities |
 | `src/sim/push.ts` | Pair-based resolution internals |
 | `src/sim/kernel.ts` (non-exported functions) | Step sub-phases, internal accumulators |
-| `src/sim/seeds.ts` | Seed derivation utilities |
-| `src/sim/ai/` | AI decision internals; host applications should use `buildAICommands()` via `src/sim/ai/system.ts` |
+| `src/sim/tick.ts` | Single-tick orchestration called by `stepWorld` |
+| `src/sim/action.ts` | Attack cooldown and swing-momentum state machine |
+| `src/sim/intent.ts` | Movement and defence intent processing |
+| `src/sim/combat.ts` | Hit resolution and skill-contest internals |
+| `src/sim/step/` | All sub-step modules (`push`, `energy`, `injury`, `movement`, etc.) |
+| `src/sim/context.ts` | `KernelContext` type definition (re-exported via `sim/world.ts`) |
+| `src/sim/events.ts` | Internal event emission — consumed by trace and bridge |
+| `src/sim/indexing.ts` | Spatial index internals used by `stepWorld` |
+| `src/sim/tuning.ts` | Physics constant tables — may be retuned in patch releases |
+| `src/sim/impairment.ts` | Functional damage accumulator — called by the kernel step |
+| `src/sim/occlusion.ts` | Internal visibility occlusion used by sensory |
+| `src/sim/systemic-toxicology.ts` | Multi-substance pharmacokinetics internals |
+| `src/sim/formation-unit.ts` | Squad-level unit structure used by `formation-combat.ts` |
+| `src/sim/commandBuilders.ts` | Low-level command construction helpers — prefer `noMove()` from `commands.ts` |
+| `src/sim/team.ts` | Team/side definitions used internally by AI and morale |
+| `src/derive.ts` | Movement-force and geometry derivations used by the kernel |
+| `src/lod.ts` | Level-of-detail helpers for large simulations |
+| `src/debug.ts` | Visual debug extraction (motion vectors, hit traces) |
+
+### AI decision internals
 
-> `buildAICommands()` from `src/sim/ai/system.ts` is Experimental (Tier 2).
-> The individual sub-modules (`decide.ts`, `perception.ts`, `targeting.ts`) are Tier 3.
+| Module | Why internal |
+|--------|-------------|
+| `src/sim/ai/decide.ts` | Decision-tree evaluation — called by `buildAICommands` |
+| `src/sim/ai/perception.ts` | AI sensory processing — called by `buildAICommands` |
+| `src/sim/ai/targeting.ts` | Target selection heuristics — called by `buildAICommands` |
+| `src/sim/ai/personality.ts` | Personality trait modifiers on AI decisions |
+| `src/sim/ai/types.ts` | AI policy and state types used only within `src/sim/ai/` |
+
+> Use `buildAICommands(world, ctx)` from `src/sim/ai/system.ts` (Tier 2) rather than importing AI sub-modules directly.
+
+### Competence domain resolvers
+
+These are called by `resolveCompetence()` and should not be imported directly.
+
+| Module | Domain |
+|--------|--------|
+| `src/competence/crafting.ts` | Crafting and tool use |
+| `src/competence/navigation.ts` | Wayfinding and cartography |
+| `src/competence/naturalist.ts` | Tracking, foraging, taming |
+| `src/competence/interspecies.ts` | Cross-species communication |
+| `src/competence/language.ts` | Linguistics and translation |
+| `src/competence/teaching.ts` | Knowledge transfer |
+| `src/competence/willpower.ts` | Endurance and mental fortitude |
+| `src/competence/engineering.ts` | Siege and structural engineering |
+| `src/competence/performance.ts` | Entertainment and oratory |
+| `src/competence/acoustic.ts` | Formation signalling (drums, horns) |
+
+### Crafting internals
+
+These are called by `craftItem()` / `startManufacturing()` and should not be imported directly.
+
+| Module | Role |
+|--------|------|
+| `src/crafting/materials.ts` | Material definitions and property calculations |
+| `src/crafting/recipes.ts` | Recipe validation and feasibility |
+| `src/crafting/manufacturing.ts` | Batch production mechanics |
+| `src/crafting/workshops.ts` | Workshop facility definitions and output bonuses |
 
 ---
 

package/dist/src/campaign-layer.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @module ananke/campaign
+ * @tier2 Experimental — breaking changes get a CHANGELOG entry.
+ *
+ * Campaign and world management: downtime activities, collective projects,
+ * settlements, inventory, item durability, world generation, inheritance,
+ * economy, and polity/socio-economic systems.
+ *
+ * Import via subpath:
+ *   import { stepDowntime, createSettlement } from "@its-not-rocket-science/ananke/campaign"
+ */
+export * from "./campaign.js";
+export * from "./downtime.js";
+export * from "./collective-activities.js";
+export * from "./settlement.js";
+export * from "./settlement-services.js";
+export * from "./inventory.js";
+export * from "./item-durability.js";
+export * from "./world-generation.js";
+export * from "./inheritance.js";
+export * from "./economy.js";
+export * from "./polity.js";
+export * from "./polity-vassals.js";

package/dist/src/campaign-layer.js

@@ -0,0 +1,23 @@
+/**
+ * @module ananke/campaign
+ * @tier2 Experimental — breaking changes get a CHANGELOG entry.
+ *
+ * Campaign and world management: downtime activities, collective projects,
+ * settlements, inventory, item durability, world generation, inheritance,
+ * economy, and polity/socio-economic systems.
+ *
+ * Import via subpath:
+ *   import { stepDowntime, createSettlement } from "@its-not-rocket-science/ananke/campaign"
+ */
+export * from "./campaign.js";
+export * from "./downtime.js";
+export * from "./collective-activities.js";
+export * from "./settlement.js";
+export * from "./settlement-services.js";
+export * from "./inventory.js";
+export * from "./item-durability.js";
+export * from "./world-generation.js";
+export * from "./inheritance.js";
+export * from "./economy.js";
+export * from "./polity.js";
+export * from "./polity-vassals.js";

package/dist/src/character.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @module ananke/character
+ * @tier2 Experimental — breaking changes get a CHANGELOG entry.
+ *
+ * Character lifecycle: aging, sleep, disease, wound healing, thermoregulation,
+ * nutrition, medical treatment, toxicology, and skill progression.
+ *
+ * Import via subpath:
+ *   import { stepAging, stepSleep } from "@its-not-rocket-science/ananke/character"
+ */
+export * from "./sim/aging.js";
+export * from "./sim/sleep.js";
+export * from "./sim/disease.js";
+export * from "./sim/wound-aging.js";
+export * from "./sim/thermoregulation.js";
+export * from "./sim/nutrition.js";
+export * from "./sim/medical.js";
+export * from "./sim/toxicology.js";
+export * from "./progression.js";

package/dist/src/character.js

@@ -0,0 +1,19 @@
+/**
+ * @module ananke/character
+ * @tier2 Experimental — breaking changes get a CHANGELOG entry.
+ *
+ * Character lifecycle: aging, sleep, disease, wound healing, thermoregulation,
+ * nutrition, medical treatment, toxicology, and skill progression.
+ *
+ * Import via subpath:
+ *   import { stepAging, stepSleep } from "@its-not-rocket-science/ananke/character"
+ */
+export * from "./sim/aging.js";
+export * from "./sim/sleep.js";
+export * from "./sim/disease.js";
+export * from "./sim/wound-aging.js";
+export * from "./sim/thermoregulation.js";
+export * from "./sim/nutrition.js";
+export * from "./sim/medical.js";
+export * from "./sim/toxicology.js";
+export * from "./progression.js";

package/dist/src/combat.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @module ananke/combat
+ * @tier2 Experimental — breaking changes get a CHANGELOG entry.
+ *
+ * Combat extensions: ranged weapons, grappling, formation tactics, mounted
+ * combat, environmental hazards, morale, sensory systems, weather, terrain,
+ * skills, and biome effects.
+ *
+ * Import via subpath:
+ *   import { resolveRangedAttack, stepGrapple } from "@its-not-rocket-science/ananke/combat"
+ */
+export * from "./sim/ranged.js";
+export * from "./sim/grapple.js";
+export * from "./sim/formation-combat.js";
+export * from "./sim/mount.js";
+export * from "./sim/hazard.js";
+export * from "./sim/morale.js";
+export * from "./sim/sensory.js";
+export * from "./sim/sensory-extended.js";
+export * from "./sim/weather.js";
+export * from "./sim/terrain.js";
+export * from "./sim/skills.js";
+export * from "./sim/biome.js";

package/dist/src/combat.js

@@ -0,0 +1,23 @@
+/**
+ * @module ananke/combat
+ * @tier2 Experimental — breaking changes get a CHANGELOG entry.
+ *
+ * Combat extensions: ranged weapons, grappling, formation tactics, mounted
+ * combat, environmental hazards, morale, sensory systems, weather, terrain,
+ * skills, and biome effects.
+ *
+ * Import via subpath:
+ *   import { resolveRangedAttack, stepGrapple } from "@its-not-rocket-science/ananke/combat"
+ */
+export * from "./sim/ranged.js";
+export * from "./sim/grapple.js";
+export * from "./sim/formation-combat.js";
+export * from "./sim/mount.js";
+export * from "./sim/hazard.js";
+export * from "./sim/morale.js";
+export * from "./sim/sensory.js";
+export * from "./sim/sensory-extended.js";
+export * from "./sim/weather.js";
+export * from "./sim/terrain.js";
+export * from "./sim/skills.js";
+export * from "./sim/biome.js";

package/dist/src/narrative-layer.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @module ananke/narrative
+ * @tier2 Experimental — breaking changes get a CHANGELOG entry.
+ *
+ * Narrative and chronicle systems: event chronicles, story arc detection,
+ * narrative rendering, legends, mythology, stress testing, combat metrics,
+ * and arena scenarios.
+ *
+ * Import via subpath:
+ *   import { addChronicleEntry, detectStoryArcs } from "@its-not-rocket-science/ananke/narrative"
+ */
+export * from "./chronicle.js";
+export * from "./story-arcs.js";
+export * from "./narrative-render.js";
+export * from "./legend.js";
+export * from "./mythology.js";
+export * from "./narrative.js";
+export * from "./narrative-stress.js";
+export * from "./metrics.js";
+export * from "./arena.js";

package/dist/src/narrative-layer.js

@@ -0,0 +1,20 @@
+/**
+ * @module ananke/narrative
+ * @tier2 Experimental — breaking changes get a CHANGELOG entry.
+ *
+ * Narrative and chronicle systems: event chronicles, story arc detection,
+ * narrative rendering, legends, mythology, stress testing, combat metrics,
+ * and arena scenarios.
+ *
+ * Import via subpath:
+ *   import { addChronicleEntry, detectStoryArcs } from "@its-not-rocket-science/ananke/narrative"
+ */
+export * from "./chronicle.js";
+export * from "./story-arcs.js";
+export * from "./narrative-render.js";
+export * from "./legend.js";
+export * from "./mythology.js";
+export * from "./narrative.js";
+export * from "./narrative-stress.js";
+export * from "./metrics.js";
+export * from "./arena.js";

package/dist/src/polity-vassals.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Phase 70 — Stratified Political Simulation ("Vassal Web" Layer)
+ *
+ * Introduces a `VassalNode` between the individual Entity and the Polity.
+ * Seven loyalty types with distinct step dynamics allow political crises
+ * (rebellions, succession disputes, noble defections) to emerge from
+ * simulation state rather than scripted events.
+ *
+ * No kernel import — pure data-management module, fixed-point arithmetic only.
+ */
+import type { Q } from "./units.js";
+import type { Polity } from "./polity.js";
+/**
+ * The basis of a vassal's loyalty to their liege.
+ *
+ * Determines how `stepVassalLoyalty` updates `loyaltyQ` each campaign tick
+ * and what events cause loyalty to spike or collapse.
+ */
+export type LoyaltyType = "ideological" | "transactional" | "terrified" | "honor_bound" | "opportunistic" | "kin_bound" | "ideological_rival";
+export interface VassalLoyalty {
+    type: LoyaltyType;
+    /** Current loyalty level [0, SCALE.Q].  q(0) = open rebellion; q(1) = unconditional. */
+    loyaltyQ: Q;
+    /**
+     * Accumulated grievances [0, SCALE.Q].
+     * Drains loyalty each tick; applied by `applyGrievanceEvent` or set directly by the host.
+     */
+    grievance_Q: Q;
+}
+export interface VassalNode {
+    /** Unique identifier, e.g. "house_harlow", "guild_weavers". */
+    id: string;
+    /** The liege polity this vassal owes service to. */
+    polityId: string;
+    /** Fractional share of polity territory controlled [0, SCALE.Q]. */
+    territory_Q: Q;
+    /**
+     * Fractional share of polity military strength contracted from this vassal
+     * when loyalty is full [0, SCALE.Q].
+     */
+    military_Q: Q;
+    /** Vassal's own treasury reserves in cost-units (independent of polity). */
+    treasury_cu: number;
+    loyalty: VassalLoyalty;
+}
+export interface VassalContribution {
+    /** Actual troop fraction provided this tick (after loyalty scaling). */
+    troops_Q: Q;
+    /** Actual treasury contribution in cost-units this tick (after loyalty scaling). */
+    treasury_cu: number;
+}
+export interface SuccessionResult {
+    /** The heir identifier that was evaluated. */
+    heirId: string;
+    /** True if the heir secured majority military support; false = contested succession. */
+    successful: boolean;
+    /** Weighted military support fraction for the heir [0, SCALE.Q]. */
+    supportQ: Q;
+    /**
+     * Loyalty delta for each vassal this tick (id → delta Q, can be negative).
+     * Supporters of the winning side gain loyalty; supporters of the losing side lose it.
+     */
+    loyaltyDeltas: Map<string, Q>;
+}
+/** Natural grievance decay per tick for most loyalty types. */
+export declare const GRIEVANCE_DECAY_Q: Q;
+/** Slower natural decay for honor_bound — oaths and grudges linger. */
+export declare const GRIEVANCE_DECAY_HONOR_Q: Q;
+/** Hard loyalty ceiling for terrified vassals (fear ≠ devotion). */
+export declare const TERRIFIED_MAX_LOYALTY_Q: Q;
+/** Loyalty target kin_bound vassals gravitate toward in the absence of grievance. */
+export declare const KIN_BOUND_BASE_Q: Q;
+/** Constant loyalty decay per tick for ideological_rival — undermining is ceaseless. */
+export declare const RIVAL_DECAY_Q: Q;
+/** Below this loyalty Q, contribution drops to zero (passive defiance). */
+export declare const CONTRIBUTION_FLOOR_Q: Q;
+/** At or above this loyalty Q, full contribution is provided. */
+export declare const CONTRIBUTION_FULL_Q: Q;
+/**
+ * Treasury difference (in cost-units) that shifts transactional loyalty by q(0.40).
+ * A liege with 50 000 cu more than the richest rival earns maximum loyalty advantage.
+ */
+export declare const TRANSACTIONAL_TREASURY_NORM = 50000;
+/** eventSeed salt for succession crisis rolls. */
+export declare const SUCCESSION_SALT: number;
+/**
+ * Apply a grievance event to a vassal and return the updated node.
+ * Typical events: broken promise, tax hike, kin killed in service, territory seized.
+ *
+ * @param delta_Q  Grievance increment [0, SCALE.Q]; positive = more aggrieved.
+ */
+export declare function applyGrievanceEvent(node: VassalNode, delta_Q: Q): VassalNode;
+/**
+ * Advance a vassal's loyalty state by one campaign tick.
+ *
+ * Loyalty dynamics are determined entirely by the vassal's `LoyaltyType`.
+ * Returns a new `VassalNode` — the input is never mutated.
+ *
+ * @param node      Current vassal state.
+ * @param liege     The liege polity.
+ * @param rivals    All other polities the vassal might consider as alternatives.
+ * @param worldSeed Deterministic RNG seed (unused directly — reserved for future variance).
+ * @param tick      Current campaign tick.
+ */
+export declare function stepVassalLoyalty(node: VassalNode, liege: Polity, rivals: readonly Polity[], _worldSeed: number, _tick: number): VassalNode;
+/**
+ * Compute the actual troop and treasury contribution a vassal provides this tick.
+ *
+ * - `loyaltyQ >= CONTRIBUTION_FULL_Q` (q(0.50)): full contracted contribution.
+ * - `loyaltyQ <= CONTRIBUTION_FLOOR_Q` (q(0.20)): zero (passive defiance).
+ * - Between floor and full: linear interpolation.
+ */
+export declare function computeVassalContribution(node: VassalNode): VassalContribution;
+/**
+ * Aggregate the effective military strength a polity can actually field,
+ * accounting for disloyal vassals.
+ *
+ * Pass this value as the force multiplier to `resolveTacticalEngagement` (Phase 69)
+ * instead of the polity's nominal `militaryStrength_Q`.
+ *
+ * ```typescript
+ * const effective = computeEffectiveMilitary(vassals);
+ * // scale polity's military by effective fraction
+ * const scaledForce = mulDiv(polity.militaryStrength_Q, effective, SCALE.Q);
+ * ```
+ */
+export declare function computeEffectiveMilitary(vassals: readonly VassalNode[]): Q;
+/**
+ * Compute the rebellion risk for a vassal [0, SCALE.Q].
+ *
+ * Risk = 70 % from low loyalty + 30 % from high grievance.
+ * Use as an AI query or host-side event trigger threshold.
+ */
+export declare function detectRebellionRisk(node: VassalNode): Q;
+/**
+ * Resolve a succession crisis: determine whether the intended heir secures
+ * enough vassal support to rule unchallenged.
+ *
+ * Each vassal "votes" based on their loyalty type, current loyalty level,
+ * and a deterministic roll from `eventSeed`.  The vote is weighted by
+ * `military_Q` so powerful nobles matter more.
+ *
+ * On success:  supporters gain +q(0.05) loyalty; opponents lose −q(0.08).
+ * On failure:  deltas are inverted (the pretender's faction benefits).
+ *
+ * @param polity    The polity undergoing succession.
+ * @param vassals   Current vassal roster.
+ * @param heirId    Identifier of the intended heir.
+ * @param worldSeed
+ * @param tick
+ */
+export declare function resolveSuccessionCrisis(polity: Polity, vassals: readonly VassalNode[], heirId: string, worldSeed: number, tick: number): SuccessionResult;

package/dist/src/polity-vassals.js

@@ -0,0 +1,289 @@
+/**
+ * Phase 70 — Stratified Political Simulation ("Vassal Web" Layer)
+ *
+ * Introduces a `VassalNode` between the individual Entity and the Polity.
+ * Seven loyalty types with distinct step dynamics allow political crises
+ * (rebellions, succession disputes, noble defections) to emerge from
+ * simulation state rather than scripted events.
+ *
+ * No kernel import — pure data-management module, fixed-point arithmetic only.
+ */
+import { SCALE, q, clampQ, mulDiv } from "./units.js";
+import { eventSeed, hashString } from "./sim/seeds.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Natural grievance decay per tick for most loyalty types. */
+export const GRIEVANCE_DECAY_Q = q(0.010);
+/** Slower natural decay for honor_bound — oaths and grudges linger. */
+export const GRIEVANCE_DECAY_HONOR_Q = q(0.004);
+/** Hard loyalty ceiling for terrified vassals (fear ≠ devotion). */
+export const TERRIFIED_MAX_LOYALTY_Q = q(0.70);
+/** Loyalty target kin_bound vassals gravitate toward in the absence of grievance. */
+export const KIN_BOUND_BASE_Q = q(0.85);
+/** Constant loyalty decay per tick for ideological_rival — undermining is ceaseless. */
+export const RIVAL_DECAY_Q = q(0.005);
+/** Below this loyalty Q, contribution drops to zero (passive defiance). */
+export const CONTRIBUTION_FLOOR_Q = q(0.20);
+/** At or above this loyalty Q, full contribution is provided. */
+export const CONTRIBUTION_FULL_Q = q(0.50);
+/**
+ * Treasury difference (in cost-units) that shifts transactional loyalty by q(0.40).
+ * A liege with 50 000 cu more than the richest rival earns maximum loyalty advantage.
+ */
+export const TRANSACTIONAL_TREASURY_NORM = 50_000;
+/** eventSeed salt for succession crisis rolls. */
+export const SUCCESSION_SALT = 0x5ECC;
+// ── Grievance events ──────────────────────────────────────────────────────────
+/**
+ * Apply a grievance event to a vassal and return the updated node.
+ * Typical events: broken promise, tax hike, kin killed in service, territory seized.
+ *
+ * @param delta_Q  Grievance increment [0, SCALE.Q]; positive = more aggrieved.
+ */
+export function applyGrievanceEvent(node, delta_Q) {
+    return {
+        ...node,
+        loyalty: {
+            ...node.loyalty,
+            grievance_Q: clampQ(node.loyalty.grievance_Q + delta_Q, 0, SCALE.Q),
+        },
+    };
+}
+// ── Loyalty step ──────────────────────────────────────────────────────────────
+/**
+ * Advance a vassal's loyalty state by one campaign tick.
+ *
+ * Loyalty dynamics are determined entirely by the vassal's `LoyaltyType`.
+ * Returns a new `VassalNode` — the input is never mutated.
+ *
+ * @param node      Current vassal state.
+ * @param liege     The liege polity.
+ * @param rivals    All other polities the vassal might consider as alternatives.
+ * @param worldSeed Deterministic RNG seed (unused directly — reserved for future variance).
+ * @param tick      Current campaign tick.
+ */
+export function stepVassalLoyalty(node, liege, rivals, _worldSeed, _tick) {
+    const { loyalty } = node;
+    const { type, loyaltyQ, grievance_Q } = loyalty;
+    // ── Step 1: decay grievance naturally ─────────────────────────────────────
+    const decayRate = type === "honor_bound" ? GRIEVANCE_DECAY_HONOR_Q : GRIEVANCE_DECAY_Q;
+    const newGrievance = clampQ(grievance_Q - decayRate, 0, SCALE.Q);
+    // ── Step 2: compute loyalty delta by type ─────────────────────────────────
+    let deltaNum = 0;
+    switch (type) {
+        case "ideological": {
+            // Slow ideological drift: grievance has minimal effect; passive recovery when content.
+            if (newGrievance > q(0.30)) {
+                deltaNum = -mulDiv(newGrievance, q(0.08), SCALE.Q);
+            }
+            else {
+                // Gentle recovery toward conviction
+                deltaNum = loyaltyQ < SCALE.Q ? q(0.003) : 0;
+            }
+            break;
+        }
+        case "transactional": {
+            // Target loyalty tracks how much richer the liege is than the best-paying rival.
+            const maxRivalTreasury = rivals.reduce((best, r) => Math.max(best, r.treasury_cu), 0);
+            const diff = Math.max(-TRANSACTIONAL_TREASURY_NORM, Math.min(TRANSACTIONAL_TREASURY_NORM, liege.treasury_cu - maxRivalTreasury));
+            const targetQ = clampQ(q(0.50) + Math.round(diff * q(0.40) / TRANSACTIONAL_TREASURY_NORM), 0, SCALE.Q);
+            // Move 5 %/tick toward target; grievance also bleeds loyalty.
+            deltaNum = mulDiv(targetQ - loyaltyQ, q(0.05), SCALE.Q);
+            deltaNum -= mulDiv(newGrievance, q(0.20), SCALE.Q);
+            break;
+        }
+        case "terrified": {
+            // Instant collapse if the liege is no stronger than the vassal.
+            if (liege.militaryStrength_Q <= node.military_Q) {
+                return {
+                    ...node,
+                    loyalty: { type, loyaltyQ: q(0.0), grievance_Q: newGrievance },
+                };
+            }
+            // Slow recovery toward the terrified ceiling; grievance undermines it.
+            deltaNum = mulDiv(TERRIFIED_MAX_LOYALTY_Q - loyaltyQ, q(0.03), SCALE.Q);
+            deltaNum -= mulDiv(newGrievance, q(0.25), SCALE.Q);
+            break;
+        }
+        case "honor_bound": {
+            // Heavy grievance causes sharp loyalty drain; without it, loyalty recovers.
+            if (grievance_Q > q(0.40)) {
+                deltaNum = -mulDiv(grievance_Q, q(0.30), SCALE.Q);
+            }
+            else {
+                deltaNum = loyaltyQ < q(0.90) ? q(0.008) : 0;
+                deltaNum -= mulDiv(newGrievance, q(0.10), SCALE.Q);
+            }
+            break;
+        }
+        case "opportunistic": {
+            // Target loyalty = liege.moraleQ: stays loyal when the liege is thriving,
+            // drifts away when the liege looks weak compared to rivals.
+            // Rivals pull target down proportionally if any of them out-morale the liege.
+            let maxRivalMorale = 0;
+            for (const r of rivals)
+                if (r.moraleQ > maxRivalMorale)
+                    maxRivalMorale = r.moraleQ;
+            // If a rival outperforms the liege, drag the target below liege.moraleQ.
+            const relativeQ = maxRivalMorale > liege.moraleQ
+                ? clampQ(mulDiv(liege.moraleQ, SCALE.Q, maxRivalMorale), 0, SCALE.Q)
+                : liege.moraleQ;
+            deltaNum = mulDiv(relativeQ - loyaltyQ, q(0.08), SCALE.Q);
+            deltaNum -= mulDiv(newGrievance, q(0.15), SCALE.Q);
+            break;
+        }
+        case "kin_bound": {
+            // Very stable; slow recovery; grievance has half the normal weight.
+            deltaNum = loyaltyQ < KIN_BOUND_BASE_Q ? q(0.01) : 0;
+            deltaNum -= mulDiv(newGrievance, q(0.10), SCALE.Q);
+            break;
+        }
+        case "ideological_rival": {
+            // Constant, inexorable decay — no incentive can reverse it.
+            deltaNum = -RIVAL_DECAY_Q;
+            break;
+        }
+    }
+    const rawLoyalty = clampQ(loyaltyQ + deltaNum, 0, SCALE.Q);
+    const newLoyalty = type === "terrified"
+        ? clampQ(rawLoyalty, 0, TERRIFIED_MAX_LOYALTY_Q)
+        : rawLoyalty;
+    return {
+        ...node,
+        loyalty: { type, loyaltyQ: newLoyalty, grievance_Q: newGrievance },
+    };
+}
+// ── Contribution ──────────────────────────────────────────────────────────────
+/**
+ * Compute the actual troop and treasury contribution a vassal provides this tick.
+ *
+ * - `loyaltyQ >= CONTRIBUTION_FULL_Q` (q(0.50)): full contracted contribution.
+ * - `loyaltyQ <= CONTRIBUTION_FLOOR_Q` (q(0.20)): zero (passive defiance).
+ * - Between floor and full: linear interpolation.
+ */
+export function computeVassalContribution(node) {
+    const { loyaltyQ } = node.loyalty;
+    const range = CONTRIBUTION_FULL_Q - CONTRIBUTION_FLOOR_Q; // q(0.30)
+    let factor;
+    if (loyaltyQ >= CONTRIBUTION_FULL_Q) {
+        factor = SCALE.Q;
+    }
+    else if (loyaltyQ <= CONTRIBUTION_FLOOR_Q) {
+        factor = 0;
+    }
+    else {
+        factor = Math.round((loyaltyQ - CONTRIBUTION_FLOOR_Q) * SCALE.Q / range);
+    }
+    return {
+        troops_Q: mulDiv(node.military_Q, factor, SCALE.Q),
+        treasury_cu: Math.round(node.treasury_cu * factor / SCALE.Q),
+    };
+}
+/**
+ * Aggregate the effective military strength a polity can actually field,
+ * accounting for disloyal vassals.
+ *
+ * Pass this value as the force multiplier to `resolveTacticalEngagement` (Phase 69)
+ * instead of the polity's nominal `militaryStrength_Q`.
+ *
+ * ```typescript
+ * const effective = computeEffectiveMilitary(vassals);
+ * // scale polity's military by effective fraction
+ * const scaledForce = mulDiv(polity.militaryStrength_Q, effective, SCALE.Q);
+ * ```
+ */
+export function computeEffectiveMilitary(vassals) {
+    return clampQ(vassals.reduce((sum, v) => sum + computeVassalContribution(v).troops_Q, 0), 0, SCALE.Q);
+}
+// ── Rebellion risk ────────────────────────────────────────────────────────────
+/**
+ * Compute the rebellion risk for a vassal [0, SCALE.Q].
+ *
+ * Risk = 70 % from low loyalty + 30 % from high grievance.
+ * Use as an AI query or host-side event trigger threshold.
+ */
+export function detectRebellionRisk(node) {
+    const { loyaltyQ, grievance_Q } = node.loyalty;
+    const loyaltyContrib = mulDiv(SCALE.Q - loyaltyQ, q(0.70), SCALE.Q);
+    const grievanceContrib = mulDiv(grievance_Q, q(0.30), SCALE.Q);
+    return clampQ(loyaltyContrib + grievanceContrib, 0, SCALE.Q);
+}
+// ── Succession crisis ─────────────────────────────────────────────────────────
+/**
+ * Resolve a succession crisis: determine whether the intended heir secures
+ * enough vassal support to rule unchallenged.
+ *
+ * Each vassal "votes" based on their loyalty type, current loyalty level,
+ * and a deterministic roll from `eventSeed`.  The vote is weighted by
+ * `military_Q` so powerful nobles matter more.
+ *
+ * On success:  supporters gain +q(0.05) loyalty; opponents lose −q(0.08).
+ * On failure:  deltas are inverted (the pretender's faction benefits).
+ *
+ * @param polity    The polity undergoing succession.
+ * @param vassals   Current vassal roster.
+ * @param heirId    Identifier of the intended heir.
+ * @param worldSeed
+ * @param tick
+ */
+export function resolveSuccessionCrisis(polity, vassals, heirId, worldSeed, tick) {
+    const polityHash = hashString(polity.id);
+    const heirHash = hashString(heirId);
+    let supportMilitary = 0;
+    let totalMilitary = 0;
+    const supportsHeir = new Map();
+    for (const vassal of vassals) {
+        const vassalHash = hashString(vassal.id);
+        const seed = eventSeed(worldSeed, tick, vassalHash, heirHash, (polityHash + SUCCESSION_SALT) & 0x7fff);
+        const roll = seed % (SCALE.Q + 1); // 0 .. SCALE.Q
+        // Support threshold: vassal supports heir if roll < threshold
+        let threshold;
+        switch (vassal.loyalty.type) {
+            case "ideological":
+                // Ideologically committed to the current regime → likely backs the heir.
+                threshold = q(0.70);
+                break;
+            case "transactional":
+                // Support proportional to current loyalty (loyalty ≈ economic satisfaction).
+                threshold = vassal.loyalty.loyaltyQ;
+                break;
+            case "terrified":
+                // Terrified vassals back whoever they think will win; proxy: loyalty.
+                threshold = vassal.loyalty.loyaltyQ;
+                break;
+            case "honor_bound":
+                // Oath-bound: strong support unless grievance has eroded trust.
+                threshold = vassal.loyalty.grievance_Q > q(0.60) ? q(0.25) : q(0.80);
+                break;
+            case "opportunistic":
+                // Genuinely uncertain — 50/50 until the outcome is clear.
+                threshold = q(0.50);
+                break;
+            case "kin_bound":
+                // Family ties: strongly backs the heir.
+                threshold = clampQ(vassal.loyalty.loyaltyQ + q(0.10), 0, SCALE.Q);
+                break;
+            case "ideological_rival":
+                // Almost never supports the heir — opposition is their purpose.
+                threshold = q(0.10);
+                break;
+        }
+        const backs = roll < threshold;
+        supportsHeir.set(vassal.id, backs);
+        totalMilitary += vassal.military_Q;
+        if (backs)
+            supportMilitary += vassal.military_Q;
+    }
+    const supportQ = totalMilitary > 0
+        ? clampQ(Math.round(supportMilitary * SCALE.Q / totalMilitary), 0, SCALE.Q)
+        : q(0.0);
+    const successful = supportQ > q(0.50);
+    const loyaltyDeltas = new Map();
+    for (const vassal of vassals) {
+        const backed = supportsHeir.get(vassal.id) ?? false;
+        // Winners gain loyalty; losers lose it (winning/losing is relative to outcome).
+        const backedHeir = backed;
+        const onWinningSide = successful ? backedHeir : !backedHeir;
+        loyaltyDeltas.set(vassal.id, (onWinningSide ? q(0.05) : -q(0.08)));
+    }
+    return { heirId, successful, supportQ, loyaltyDeltas };
+}

package/dist/src/social.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @module ananke/social
+ * @tier2 Experimental — breaking changes get a CHANGELOG entry.
+ *
+ * Social systems: dialogue, factions, relationships, party management,
+ * quests, and quest generation.
+ *
+ * Import via subpath:
+ *   import { dialogueProbability, effectiveStanding } from "@its-not-rocket-science/ananke/social"
+ */
+export * from "./dialogue.js";
+export * from "./faction.js";
+export * from "./relationships.js";
+export * from "./relationships-effects.js";
+export * from "./party.js";
+export * from "./quest.js";
+export * from "./quest-generators.js";

package/dist/src/social.js

@@ -0,0 +1,17 @@
+/**
+ * @module ananke/social
+ * @tier2 Experimental — breaking changes get a CHANGELOG entry.
+ *
+ * Social systems: dialogue, factions, relationships, party management,
+ * quests, and quest generation.
+ *
+ * Import via subpath:
+ *   import { dialogueProbability, effectiveStanding } from "@its-not-rocket-science/ananke/social"
+ */
+export * from "./dialogue.js";
+export * from "./faction.js";
+export * from "./relationships.js";
+export * from "./relationships-effects.js";
+export * from "./party.js";
+export * from "./quest.js";
+export * from "./quest-generators.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@its-not-rocket-science/ananke",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",
@@ -22,6 +22,38 @@
     "./catalog": {
       "import": "./dist/src/catalog.js",
       "types": "./dist/src/catalog.d.ts"
+    },
+    "./character": {
+      "import": "./dist/src/character.js",
+      "types": "./dist/src/character.d.ts"
+    },
+    "./combat": {
+      "import": "./dist/src/combat.js",
+      "types": "./dist/src/combat.d.ts"
+    },
+    "./campaign": {
+      "import": "./dist/src/campaign-layer.js",
+      "types": "./dist/src/campaign-layer.d.ts"
+    },
+    "./social": {
+      "import": "./dist/src/social.js",
+      "types": "./dist/src/social.d.ts"
+    },
+    "./narrative": {
+      "import": "./dist/src/narrative-layer.js",
+      "types": "./dist/src/narrative-layer.d.ts"
+    },
+    "./anatomy": {
+      "import": "./dist/src/anatomy/index.js",
+      "types": "./dist/src/anatomy/index.d.ts"
+    },
+    "./crafting": {
+      "import": "./dist/src/crafting/index.js",
+      "types": "./dist/src/crafting/index.d.ts"
+    },
+    "./competence": {
+      "import": "./dist/src/competence/index.js",
+      "types": "./dist/src/competence/index.d.ts"
     }
   },
   "files": [