@its-not-rocket-science/ananke 0.1.32 → 0.1.35

package/CHANGELOG.md

@@ -6,6 +6,62 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.35] — 2026-03-26
+
+### Added
+
+- **Phase 90 · Civil Unrest & Rebellion** (`src/unrest.ts`)
+  - `UnrestFactors { faminePressure_Q?, epidemicPressure_Q?, heresyRisk_Q?, weakestBond_Q? }` — optional pressure inputs from Phases 85/87/88/79.
+  - `computeUnrestLevel(polity, factors?)` → Q: weighted composite of morale deficit (×q(0.30)), stability deficit (×q(0.25)), famine (×q(0.20)), epidemic (×q(0.10)), heresy (×q(0.10)), feudal bond deficit (×q(0.05)).
+  - `UNREST_ACTION_THRESHOLD_Q = q(0.30)` — excess above this drains morale/stability.
+  - `REBELLION_THRESHOLD_Q = q(0.65)` — above this `rebellionRisk` flag is set.
+  - `stepUnrest(polity, unrestLevel_Q, elapsedDays)` → `UnrestStepResult`: drains morale at `excess × UNREST_MORALE_DRAIN_Q = q(0.005)` per day, stability at `q(0.003)` per day; mutates polity in place; floor at 0.
+  - `resolveRebellion(polity, worldSeed, tick)` → `RebellionResult`: deterministic via `eventSeed`; outcomes `"quelled" | "uprising" | "civil_war"` weighted by polity `militaryStrength_Q` vs. unrest roll; each outcome applies morale/stability penalties and treasury raid (`REBELLION_TREASURY_RAID_Q = q(0.15)`; civil war = 2×).
+  - Added `./unrest` subpath export to `package.json`.
+  - 35 new tests; 4,722 total. Coverage maintained above all thresholds.
+
+---
+
+## [0.1.34] — 2026-03-26
+
+### Added
+
+- **Phase 89 · Infrastructure & Development** (`src/infrastructure.ts`)
+  - `InfraType`: `"road" | "wall" | "granary" | "marketplace" | "apothecary"`.
+  - `InfraProject { projectId, polityId, type, targetLevel, investedCost, totalCost, completedTick? }` — in-progress construction.
+  - `InfraStructure { structureId, polityId, type, level, builtTick }` — completed building; level [1, `MAX_INFRA_LEVEL = 5`].
+  - `INFRA_BASE_COST` — treasury cost per level per type (wall 20 k → granary 8 k per level).
+  - `INFRA_BONUS_PER_LEVEL_Q` — Q bonus per level (road q(0.05), wall q(0.08), granary q(0.10), marketplace q(0.02), apothecary q(0.06)).
+  - `createInfraProject`, `createInfraStructure` — factories; level clamped to [1, 5].
+  - `investInProject(polity, project, amount, tick)` — drains `polity.treasury_cu`, advances `investedCost`, stamps `completedTick` when fully funded; no-ops if complete or treasury insufficient.
+  - `isProjectComplete`, `completeProject` → `InfraStructure | undefined`.
+  - `computeInfraBonus(structures, type)` → Q: sums `BONUS_PER_LEVEL × level` across all matching structures; clamped to SCALE.Q.
+  - **Typed bonus helpers**: `computeRoadTradeBonus` (Phase-83 efficiency boost), `computeWallSiegeBonus` (Phase-84 attacker strength reduction), `computeGranaryCapacityBonus` (Phase-87 capacity multiplier), `computeApothecaryHealthBonus` (Phase-88 health capacity), `computeMarketplaceIncome` (daily treasury income = `floor(treasury × bonus / SCALE.Q)`).
+  - Max-level wall: −q(0.40) siege strength; max-level granary: +q(0.50) capacity.
+  - Added `./infrastructure` subpath export to `package.json`.
+  - 36 new tests; 4,687 total. Coverage maintained above all thresholds.
+
+---
+
+## [0.1.33] — 2026-03-26
+
+### Added
+
+- **Phase 88 · Epidemic Spread at Polity Scale** (`src/epidemic.ts`)
+  - `PolityEpidemicState { polityId, diseaseId, prevalence_Q }` — infected fraction of polity population [0, SCALE.Q]. Reuses Phase-56 `DiseaseProfile` for disease properties.
+  - `createEpidemicState(polityId, diseaseId, initialPrevalence_Q?)` — factory; default prevalence `q(0.01)`.
+  - `deriveHealthCapacity(polity)` → Q: tech-era health infrastructure (`HEALTH_CAPACITY_BY_ERA`: Stone q(0.05) → Modern q(0.99)).
+  - `computeEpidemicDeathPressure(state, profile)` → Q: annual death rate = `prevalence × mortalityRate / SCALE.Q`; feeds Phase-86 `deathPressure_Q` parameter.
+  - `stepEpidemic(state, profile, elapsedDays, healthCapacity_Q?)` — **discrete logistic model**: growth proportional to `prevalence × (SCALE.Q − prevalence) × GROWTH_RATE × transmissionRate`; recovery proportional to `prevalence × (RECOVERY_RATE + healthBonus)`; higher `healthCapacity_Q` accelerates recovery.
+  - `computeSpreadToPolity(sourceState, profile, contactIntensity_Q)` → Q: prevalence exported to a target polity; zero when source is contained.
+  - `spreadEpidemic(source, profile, targetPolityId, contactIntensity_Q, existingState?)` — creates or updates target epidemic state; returns `undefined` below `EPIDEMIC_CONTAINED_Q`.
+  - `computeEpidemicMigrationPush(state, profile)` → Q [0, `EPIDEMIC_MIGRATION_PUSH_MAX_Q = q(0.20)`]: flight pressure proportional to prevalence × severity; zero when `symptomSeverity_Q < EPIDEMIC_SEVERITY_THRESHOLD_Q = q(0.30)`. Integrates with Phase-81 push pressure.
+  - `EPIDEMIC_CONTAINED_Q = q(0.01)`, `EPIDEMIC_BASE_GROWTH_RATE_Q = q(0.05)`, `EPIDEMIC_BASE_RECOVERY_RATE_Q = q(0.02)`, `EPIDEMIC_HEALTH_RECOVERY_BONUS_Q = q(0.04)`.
+  - Added `./epidemic` subpath export to `package.json`.
+  - 43 new tests; 4,651 total. Coverage maintained above all thresholds.
+
+---
+
 ## [0.1.32] — 2026-03-26
 
 ### Added

package/dist/src/epidemic.d.ts

@@ -0,0 +1,126 @@
+import type { Q } from "./units.js";
+import type { Polity } from "./polity.js";
+import type { DiseaseProfile } from "./sim/disease.js";
+/**
+ * Epidemic state for one disease in one polity.
+ * Attach one record per active disease; store externally (e.g. `Map<string, PolityEpidemicState[]>`).
+ */
+export interface PolityEpidemicState {
+    polityId: string;
+    diseaseId: string;
+    /** Infected fraction of population [0, SCALE.Q]. */
+    prevalence_Q: Q;
+}
+/** Outcome of a single `stepEpidemic` call. */
+export interface EpidemicStepResult {
+    /** New prevalence after the step. */
+    newPrevalence_Q: Q;
+    /** Signed change in prevalence. */
+    delta_Q: number;
+    /** Whether the epidemic is now contained (prevalence ≤ EPIDEMIC_CONTAINED_Q). */
+    contained: boolean;
+}
+/**
+ * Prevalence at or below this value is considered "contained" — epidemic
+ * no longer produces meaningful mortality or migration pressure.
+ */
+export declare const EPIDEMIC_CONTAINED_Q: Q;
+/**
+ * Base daily growth rate of prevalence per susceptible unit.
+ *
+ * Logistic growth: `growthDelta = prevalence × (SCALE.Q − prevalence) × GROWTH_RATE / SCALE.Q²`
+ * The actual rate is further scaled by `profile.baseTransmissionRate_Q`.
+ */
+export declare const EPIDEMIC_BASE_GROWTH_RATE_Q: Q;
+/**
+ * Base daily recovery rate (natural immunity + mortality removes infecteds).
+ * Scaled by `healthCapacity_Q`: better medicine → faster clearance.
+ */
+export declare const EPIDEMIC_BASE_RECOVERY_RATE_Q: Q;
+/**
+ * Maximum additional daily recovery from maximum `healthCapacity_Q`.
+ * At healthCapacity = SCALE.Q: recovery rate += this value.
+ */
+export declare const EPIDEMIC_HEALTH_RECOVERY_BONUS_Q: Q;
+/**
+ * Peak migration push pressure from a severe epidemic (at full prevalence).
+ * Integrates with Phase-81 `computePushPressure` as additive bonus.
+ */
+export declare const EPIDEMIC_MIGRATION_PUSH_MAX_Q: Q;
+/**
+ * Minimum symptom severity that generates significant migration push.
+ * Below this threshold `computeEpidemicMigrationPush` returns reduced pressure.
+ */
+export declare const EPIDEMIC_SEVERITY_THRESHOLD_Q: Q;
+/** Health-care capacity by tech era [0, SCALE.Q]. */
+export declare const HEALTH_CAPACITY_BY_ERA: Record<string, Q>;
+/** Create a new epidemic state for a polity. */
+export declare function createEpidemicState(polityId: string, diseaseId: string, initialPrevalence_Q?: Q): PolityEpidemicState;
+/**
+ * Derive health-care capacity [0, SCALE.Q] for a polity from its tech era.
+ *
+ * Hosts may blend this with morale or stability for a richer model.
+ */
+export declare function deriveHealthCapacity(polity: Polity): Q;
+/**
+ * Compute annual death pressure [Q = fraction/year] from an active epidemic.
+ *
+ * Formula: `prevalence_Q × mortalityRate_Q / SCALE.Q`
+ *
+ * Pass the result as `deathPressure_Q` to Phase-86 `stepPolityPopulation`.
+ */
+export declare function computeEpidemicDeathPressure(state: PolityEpidemicState, profile: DiseaseProfile): Q;
+/**
+ * Advance epidemic prevalence for `elapsedDays` days.
+ *
+ * **Logistic growth model** (daily, applied `elapsedDays` times via single formula):
+ *
+ * ```
+ * susceptible_Q  = SCALE.Q − prevalence_Q
+ * growthDelta_Q  = prevalence_Q × susceptible_Q × GROWTH_RATE × transmissionRate
+ *                  / SCALE.Q³
+ * recoveryDelta_Q = prevalence_Q × (RECOVERY_RATE + healthBonus) / SCALE.Q
+ * netDelta_Q     = (growthDelta − recoveryDelta) × elapsedDays
+ * ```
+ *
+ * Prevalence is clamped to [0, SCALE.Q].
+ *
+ * @param healthCapacity_Q  [0, SCALE.Q] tech-era / infrastructure health bonus.
+ *                          Derive via `deriveHealthCapacity(polity)`.
+ */
+export declare function stepEpidemic(state: PolityEpidemicState, profile: DiseaseProfile, elapsedDays: number, healthCapacity_Q?: Q): EpidemicStepResult;
+/**
+ * Compute the prevalence increase introduced into a target polity from a source.
+ *
+ * The `contactIntensity_Q` captures how connected the polities are:
+ * - Trade route efficiency or volume → high contact
+ * - Migration flow fraction → moderate contact
+ * - No trade/migration → zero
+ *
+ * Formula: `sourcePrevalence × contactIntensity × transmissionRate / SCALE.Q²`
+ *
+ * Returns 0 if the source epidemic is contained.
+ */
+export declare function computeSpreadToPolity(source: PolityEpidemicState, profile: DiseaseProfile, contactIntensity_Q: Q): Q;
+/**
+ * Introduce disease from a source polity into a target polity.
+ *
+ * Creates a new `PolityEpidemicState` for the target if the computed spread
+ * exceeds `EPIDEMIC_CONTAINED_Q`.  If the disease is already present in the
+ * target the existing state's prevalence is increased.
+ *
+ * Returns the state that was created or modified, or `undefined` if the
+ * spread was below the contained threshold.
+ */
+export declare function spreadEpidemic(sourceState: PolityEpidemicState, profile: DiseaseProfile, targetPolityId: string, contactIntensity_Q: Q, existingState?: PolityEpidemicState): PolityEpidemicState | undefined;
+/**
+ * Compute epidemic-driven migration push pressure [0, SCALE.Q].
+ *
+ * Pressure scales with both prevalence and symptom severity.
+ * Only fires when `profile.symptomSeverity_Q >= EPIDEMIC_SEVERITY_THRESHOLD_Q`.
+ *
+ * Formula: `prevalence × severity × MIGRATION_PUSH_MAX / SCALE.Q²`
+ *
+ * Add the result to Phase-81 `computePushPressure` output.
+ */
+export declare function computeEpidemicMigrationPush(state: PolityEpidemicState, profile: DiseaseProfile): Q;

package/dist/src/epidemic.js

@@ -0,0 +1,193 @@
+// src/epidemic.ts — Phase 88: Epidemic Spread at Polity Scale
+//
+// Models disease prevalence in polity populations as a Q fraction of population
+// [0, SCALE.Q].  Uses Phase-56 DiseaseProfile for disease properties.
+// A discrete logistic model governs growth and recovery each step.
+//
+// Design:
+//   - Pure data layer — no Entity fields, no kernel changes.
+//   - `PolityEpidemicState` tracks prevalence per (polity, disease) pair.
+//   - `computeEpidemicDeathPressure` produces the `deathPressure_Q` annual rate
+//     consumed by Phase-86 `stepPolityPopulation`.
+//   - `spreadEpidemic` models contact-driven inter-polity transmission via
+//     Phase-83 trade route volume or Phase-81 migration flow intensity.
+//   - `computeEpidemicMigrationPush` adds flight pressure to Phase-81.
+//
+// Integration:
+//   Phase 56 (Disease):     reuses `DiseaseProfile` (transmissionRoute, mortalityRate_Q, etc.).
+//   Phase 61 (Polity):      techEra drives `deriveHealthCapacity`.
+//   Phase 81 (Migration):   `computeEpidemicMigrationPush` as additive push bonus.
+//   Phase 83 (Trade Routes): trade contact intensity drives inter-polity spread.
+//   Phase 86 (Demography):  `computeEpidemicDeathPressure` → `deathPressure_Q` param.
+import { q, SCALE, clampQ, mulDiv } from "./units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/**
+ * Prevalence at or below this value is considered "contained" — epidemic
+ * no longer produces meaningful mortality or migration pressure.
+ */
+export const EPIDEMIC_CONTAINED_Q = q(0.01);
+/**
+ * Base daily growth rate of prevalence per susceptible unit.
+ *
+ * Logistic growth: `growthDelta = prevalence × (SCALE.Q − prevalence) × GROWTH_RATE / SCALE.Q²`
+ * The actual rate is further scaled by `profile.baseTransmissionRate_Q`.
+ */
+export const EPIDEMIC_BASE_GROWTH_RATE_Q = q(0.05);
+/**
+ * Base daily recovery rate (natural immunity + mortality removes infecteds).
+ * Scaled by `healthCapacity_Q`: better medicine → faster clearance.
+ */
+export const EPIDEMIC_BASE_RECOVERY_RATE_Q = q(0.02);
+/**
+ * Maximum additional daily recovery from maximum `healthCapacity_Q`.
+ * At healthCapacity = SCALE.Q: recovery rate += this value.
+ */
+export const EPIDEMIC_HEALTH_RECOVERY_BONUS_Q = q(0.04);
+/**
+ * Peak migration push pressure from a severe epidemic (at full prevalence).
+ * Integrates with Phase-81 `computePushPressure` as additive bonus.
+ */
+export const EPIDEMIC_MIGRATION_PUSH_MAX_Q = q(0.20);
+/**
+ * Minimum symptom severity that generates significant migration push.
+ * Below this threshold `computeEpidemicMigrationPush` returns reduced pressure.
+ */
+export const EPIDEMIC_SEVERITY_THRESHOLD_Q = q(0.30);
+/** Health-care capacity by tech era [0, SCALE.Q]. */
+export const HEALTH_CAPACITY_BY_ERA = {
+    "Stone": q(0.05),
+    "Bronze": q(0.15),
+    "Iron": q(0.25),
+    "Medieval": q(0.40),
+    "Renaissance": q(0.60),
+    "Industrial": q(0.80),
+    "Modern": q(0.99),
+};
+// ── Factory ───────────────────────────────────────────────────────────────────
+/** Create a new epidemic state for a polity. */
+export function createEpidemicState(polityId, diseaseId, initialPrevalence_Q = q(0.01)) {
+    return {
+        polityId,
+        diseaseId,
+        prevalence_Q: clampQ(initialPrevalence_Q, 0, SCALE.Q),
+    };
+}
+// ── Health capacity ───────────────────────────────────────────────────────────
+/**
+ * Derive health-care capacity [0, SCALE.Q] for a polity from its tech era.
+ *
+ * Hosts may blend this with morale or stability for a richer model.
+ */
+export function deriveHealthCapacity(polity) {
+    return (HEALTH_CAPACITY_BY_ERA[polity.techEra] ?? q(0.05));
+}
+// ── Death pressure ────────────────────────────────────────────────────────────
+/**
+ * Compute annual death pressure [Q = fraction/year] from an active epidemic.
+ *
+ * Formula: `prevalence_Q × mortalityRate_Q / SCALE.Q`
+ *
+ * Pass the result as `deathPressure_Q` to Phase-86 `stepPolityPopulation`.
+ */
+export function computeEpidemicDeathPressure(state, profile) {
+    return clampQ(mulDiv(state.prevalence_Q, profile.mortalityRate_Q, SCALE.Q), 0, SCALE.Q);
+}
+// ── Epidemic step ─────────────────────────────────────────────────────────────
+/**
+ * Advance epidemic prevalence for `elapsedDays` days.
+ *
+ * **Logistic growth model** (daily, applied `elapsedDays` times via single formula):
+ *
+ * ```
+ * susceptible_Q  = SCALE.Q − prevalence_Q
+ * growthDelta_Q  = prevalence_Q × susceptible_Q × GROWTH_RATE × transmissionRate
+ *                  / SCALE.Q³
+ * recoveryDelta_Q = prevalence_Q × (RECOVERY_RATE + healthBonus) / SCALE.Q
+ * netDelta_Q     = (growthDelta − recoveryDelta) × elapsedDays
+ * ```
+ *
+ * Prevalence is clamped to [0, SCALE.Q].
+ *
+ * @param healthCapacity_Q  [0, SCALE.Q] tech-era / infrastructure health bonus.
+ *                          Derive via `deriveHealthCapacity(polity)`.
+ */
+export function stepEpidemic(state, profile, elapsedDays, healthCapacity_Q) {
+    const prev = state.prevalence_Q;
+    const susceptible = clampQ(SCALE.Q - prev, 0, SCALE.Q);
+    const healthBonus = healthCapacity_Q != null
+        ? mulDiv(EPIDEMIC_HEALTH_RECOVERY_BONUS_Q, healthCapacity_Q, SCALE.Q)
+        : 0;
+    const recoveryRate = EPIDEMIC_BASE_RECOVERY_RATE_Q + healthBonus;
+    // Growth: logistic — fast when few infected; slows as susceptibles run out
+    // growthDelta = prev × susceptible × BASE_GROWTH × transmissionRate / SCALE.Q³
+    const step1 = mulDiv(prev, susceptible, SCALE.Q); // prev × susc / SCALE.Q
+    const step2 = mulDiv(step1, EPIDEMIC_BASE_GROWTH_RATE_Q, SCALE.Q); // × GROWTH / SCALE.Q
+    const growthDaily = mulDiv(step2, profile.baseTransmissionRate_Q, SCALE.Q); // × transmRate / SCALE.Q
+    // Recovery: linear proportion of current prevalence
+    const recoveryDaily = mulDiv(prev, recoveryRate, SCALE.Q);
+    const netDaily = growthDaily - recoveryDaily;
+    const delta = Math.round(netDaily * elapsedDays);
+    const newPrev = clampQ(prev + delta, 0, SCALE.Q);
+    state.prevalence_Q = newPrev;
+    return {
+        newPrevalence_Q: newPrev,
+        delta_Q: delta,
+        contained: newPrev <= EPIDEMIC_CONTAINED_Q,
+    };
+}
+// ── Inter-polity spread ───────────────────────────────────────────────────────
+/**
+ * Compute the prevalence increase introduced into a target polity from a source.
+ *
+ * The `contactIntensity_Q` captures how connected the polities are:
+ * - Trade route efficiency or volume → high contact
+ * - Migration flow fraction → moderate contact
+ * - No trade/migration → zero
+ *
+ * Formula: `sourcePrevalence × contactIntensity × transmissionRate / SCALE.Q²`
+ *
+ * Returns 0 if the source epidemic is contained.
+ */
+export function computeSpreadToPolity(source, profile, contactIntensity_Q) {
+    if (source.prevalence_Q <= EPIDEMIC_CONTAINED_Q)
+        return 0;
+    const step1 = mulDiv(source.prevalence_Q, contactIntensity_Q, SCALE.Q);
+    return clampQ(mulDiv(step1, profile.baseTransmissionRate_Q, SCALE.Q), 0, SCALE.Q);
+}
+/**
+ * Introduce disease from a source polity into a target polity.
+ *
+ * Creates a new `PolityEpidemicState` for the target if the computed spread
+ * exceeds `EPIDEMIC_CONTAINED_Q`.  If the disease is already present in the
+ * target the existing state's prevalence is increased.
+ *
+ * Returns the state that was created or modified, or `undefined` if the
+ * spread was below the contained threshold.
+ */
+export function spreadEpidemic(sourceState, profile, targetPolityId, contactIntensity_Q, existingState) {
+    const added = computeSpreadToPolity(sourceState, profile, contactIntensity_Q);
+    if (added <= EPIDEMIC_CONTAINED_Q)
+        return undefined;
+    if (existingState) {
+        existingState.prevalence_Q = clampQ(existingState.prevalence_Q + added, 0, SCALE.Q);
+        return existingState;
+    }
+    return createEpidemicState(targetPolityId, profile.id, added);
+}
+// ── Migration push ────────────────────────────────────────────────────────────
+/**
+ * Compute epidemic-driven migration push pressure [0, SCALE.Q].
+ *
+ * Pressure scales with both prevalence and symptom severity.
+ * Only fires when `profile.symptomSeverity_Q >= EPIDEMIC_SEVERITY_THRESHOLD_Q`.
+ *
+ * Formula: `prevalence × severity × MIGRATION_PUSH_MAX / SCALE.Q²`
+ *
+ * Add the result to Phase-81 `computePushPressure` output.
+ */
+export function computeEpidemicMigrationPush(state, profile) {
+    if (profile.symptomSeverity_Q < EPIDEMIC_SEVERITY_THRESHOLD_Q)
+        return 0;
+    const step1 = mulDiv(state.prevalence_Q, profile.symptomSeverity_Q, SCALE.Q);
+    return clampQ(mulDiv(step1, EPIDEMIC_MIGRATION_PUSH_MAX_Q, SCALE.Q), 0, SCALE.Q);
+}

package/dist/src/infrastructure.d.ts

@@ -0,0 +1,90 @@
+import type { Q } from "./units.js";
+import type { Polity } from "./polity.js";
+/** Available infrastructure types. */
+export type InfraType = "road" | "wall" | "granary" | "marketplace" | "apothecary";
+/** A completed infrastructure structure. */
+export interface InfraStructure {
+    structureId: string;
+    polityId: string;
+    type: InfraType;
+    /** Current upgrade level [1, MAX_INFRA_LEVEL]. */
+    level: number;
+    builtTick: number;
+}
+/** An in-progress construction project. */
+export interface InfraProject {
+    projectId: string;
+    polityId: string;
+    type: InfraType;
+    /** Target level upon completion. */
+    targetLevel: number;
+    /** Treasury already invested [cost units]. */
+    investedCost: number;
+    /** Total treasury cost required [cost units]. */
+    totalCost: number;
+    /** Tick on which construction completed, or `undefined` if still in progress. */
+    completedTick?: number;
+}
+/** Maximum upgrade level for any structure. */
+export declare const MAX_INFRA_LEVEL = 5;
+/**
+ * Base treasury cost per level for each structure type [cost units].
+ * Each level costs `BASE_COST × level` (level 1 = cheapest, level 5 = 5×).
+ */
+export declare const INFRA_BASE_COST: Record<InfraType, number>;
+/**
+ * Bonus Q per level for each infrastructure type.
+ * Total bonus = `BONUS_PER_LEVEL × level` (clamped by the calling function).
+ */
+export declare const INFRA_BONUS_PER_LEVEL_Q: Record<InfraType, Q>;
+/** Start a new construction project. Returns the project record (not yet complete). */
+export declare function createInfraProject(projectId: string, polityId: string, type: InfraType, targetLevel: number): InfraProject;
+/** Create a completed structure directly (e.g., at world initialisation). */
+export declare function createInfraStructure(structureId: string, polityId: string, type: InfraType, level: number, builtTick: number): InfraStructure;
+/**
+ * Invest treasury into a project.
+ *
+ * Drains `Math.min(investAmount, remainingCost)` from `polity.treasury_cu`.
+ * Sets `project.completedTick` when fully funded.
+ *
+ * Returns the amount actually invested this call.
+ */
+export declare function investInProject(polity: Polity, project: InfraProject, investAmount: number, currentTick: number): number;
+/** Return `true` if the project is fully funded and complete. */
+export declare function isProjectComplete(project: InfraProject): boolean;
+/**
+ * Convert a completed project into a permanent structure.
+ * Returns `undefined` if the project is not yet complete.
+ */
+export declare function completeProject(project: InfraProject, structureId: string): InfraStructure | undefined;
+/**
+ * Compute the total Q bonus from all structures of a given type at a polity.
+ * Sums `BONUS_PER_LEVEL × level` across all matching structures.
+ * Clamped to [0, SCALE.Q].
+ */
+export declare function computeInfraBonus(structures: InfraStructure[], type: InfraType): Q;
+/**
+ * Trade route efficiency bonus from roads [0, SCALE.Q].
+ * Add to route `efficiency_Q` when calling Phase-83 `computeDailyTradeIncome`.
+ */
+export declare function computeRoadTradeBonus(structures: InfraStructure[]): Q;
+/**
+ * Siege defence bonus from walls [0, SCALE.Q].
+ * Subtract from attacker's effective `siegeStrength_Q` in Phase-84.
+ */
+export declare function computeWallSiegeBonus(structures: InfraStructure[]): Q;
+/**
+ * Granary capacity multiplier bonus [0, SCALE.Q].
+ * Effective capacity = `baseCapacity × (SCALE.Q + bonus) / SCALE.Q`.
+ */
+export declare function computeGranaryCapacityBonus(structures: InfraStructure[]): Q;
+/**
+ * Daily treasury income from marketplaces [cost units].
+ * `income = treasury_cu × MARKETPLACE_BONUS / SCALE.Q`
+ */
+export declare function computeMarketplaceIncome(polity: Polity, structures: InfraStructure[]): number;
+/**
+ * Health capacity bonus from apothecaries [0, SCALE.Q].
+ * Add to `deriveHealthCapacity(polity)` result in Phase-88.
+ */
+export declare function computeApothecaryHealthBonus(structures: InfraStructure[]): Q;

package/dist/src/infrastructure.js

@@ -0,0 +1,147 @@
+// src/infrastructure.ts — Phase 89: Infrastructure & Development
+//
+// Models polity investment in permanent physical structures.  Each structure type
+// grants passive bonuses to existing systems (trade, siege, granary, treasury).
+// Construction consumes treasury and progresses over multiple ticks.
+//
+// Design:
+//   - Pure data layer — no Entity fields, no kernel changes.
+//   - `InfraProject` tracks in-progress construction; `InfraStructure` records
+//     completed buildings with an integer level (1–MAX_INFRA_LEVEL).
+//   - Bonus functions return Q modifiers; the host adds them to the relevant
+//     system calls (e.g., route efficiency, siege strength multiplier).
+//
+// Integration:
+//   Phase 61 (Polity):      treasury_cu is drained by construction costs.
+//   Phase 83 (Trade Routes): `computeRoadTradeBonus` → route efficiency boost.
+//   Phase 84 (Siege):        `computeWallSiegeBonus` → siege strength reduction for attacker.
+//   Phase 87 (Granary):      `computeGranaryCapacityBonus` → capacity multiplier.
+//   Phase 88 (Epidemic):     `computeApothecaryHealthBonus` → health capacity boost.
+import { q, SCALE, clampQ, mulDiv } from "./units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Maximum upgrade level for any structure. */
+export const MAX_INFRA_LEVEL = 5;
+/**
+ * Base treasury cost per level for each structure type [cost units].
+ * Each level costs `BASE_COST × level` (level 1 = cheapest, level 5 = 5×).
+ */
+export const INFRA_BASE_COST = {
+    road: 10_000,
+    wall: 20_000,
+    granary: 8_000,
+    marketplace: 15_000,
+    apothecary: 12_000,
+};
+/**
+ * Bonus Q per level for each infrastructure type.
+ * Total bonus = `BONUS_PER_LEVEL × level` (clamped by the calling function).
+ */
+export const INFRA_BONUS_PER_LEVEL_Q = {
+    road: q(0.05), // +5% trade route efficiency per level → +25% at max
+    wall: q(0.08), // +8% siege strength reduction per level → −40% at max
+    granary: q(0.10), // +10% granary capacity per level → +50% at max
+    marketplace: q(0.02), // +2% daily treasury income per level → +10% at max
+    apothecary: q(0.06), // +6% health capacity per level → +30% at max
+};
+// ── Factory ───────────────────────────────────────────────────────────────────
+/** Start a new construction project. Returns the project record (not yet complete). */
+export function createInfraProject(projectId, polityId, type, targetLevel) {
+    const level = Math.max(1, Math.min(targetLevel, MAX_INFRA_LEVEL));
+    const totalCost = INFRA_BASE_COST[type] * level;
+    return { projectId, polityId, type, targetLevel: level, investedCost: 0, totalCost };
+}
+/** Create a completed structure directly (e.g., at world initialisation). */
+export function createInfraStructure(structureId, polityId, type, level, builtTick) {
+    return {
+        structureId,
+        polityId,
+        type,
+        level: Math.max(1, Math.min(level, MAX_INFRA_LEVEL)),
+        builtTick,
+    };
+}
+// ── Construction ──────────────────────────────────────────────────────────────
+/**
+ * Invest treasury into a project.
+ *
+ * Drains `Math.min(investAmount, remainingCost)` from `polity.treasury_cu`.
+ * Sets `project.completedTick` when fully funded.
+ *
+ * Returns the amount actually invested this call.
+ */
+export function investInProject(polity, project, investAmount, currentTick) {
+    if (project.completedTick != null)
+        return 0; // already complete
+    const remaining = project.totalCost - project.investedCost;
+    const actual = Math.min(investAmount, remaining, polity.treasury_cu);
+    project.investedCost += actual;
+    polity.treasury_cu -= actual;
+    if (project.investedCost >= project.totalCost) {
+        project.completedTick = currentTick;
+    }
+    return actual;
+}
+/** Return `true` if the project is fully funded and complete. */
+export function isProjectComplete(project) {
+    return project.completedTick != null;
+}
+/**
+ * Convert a completed project into a permanent structure.
+ * Returns `undefined` if the project is not yet complete.
+ */
+export function completeProject(project, structureId) {
+    if (project.completedTick == null)
+        return undefined;
+    return createInfraStructure(structureId, project.polityId, project.type, project.targetLevel, project.completedTick);
+}
+// ── Bonus computations ────────────────────────────────────────────────────────
+/**
+ * Compute the total Q bonus from all structures of a given type at a polity.
+ * Sums `BONUS_PER_LEVEL × level` across all matching structures.
+ * Clamped to [0, SCALE.Q].
+ */
+export function computeInfraBonus(structures, type) {
+    let total = 0;
+    for (const s of structures) {
+        if (s.type === type) {
+            total += INFRA_BONUS_PER_LEVEL_Q[type] * s.level;
+        }
+    }
+    return clampQ(total, 0, SCALE.Q);
+}
+/**
+ * Trade route efficiency bonus from roads [0, SCALE.Q].
+ * Add to route `efficiency_Q` when calling Phase-83 `computeDailyTradeIncome`.
+ */
+export function computeRoadTradeBonus(structures) {
+    return computeInfraBonus(structures, "road");
+}
+/**
+ * Siege defence bonus from walls [0, SCALE.Q].
+ * Subtract from attacker's effective `siegeStrength_Q` in Phase-84.
+ */
+export function computeWallSiegeBonus(structures) {
+    return computeInfraBonus(structures, "wall");
+}
+/**
+ * Granary capacity multiplier bonus [0, SCALE.Q].
+ * Effective capacity = `baseCapacity × (SCALE.Q + bonus) / SCALE.Q`.
+ */
+export function computeGranaryCapacityBonus(structures) {
+    return computeInfraBonus(structures, "granary");
+}
+/**
+ * Daily treasury income from marketplaces [cost units].
+ * `income = treasury_cu × MARKETPLACE_BONUS / SCALE.Q`
+ */
+export function computeMarketplaceIncome(polity, structures) {
+    const bonus = computeInfraBonus(structures, "marketplace");
+    return Math.floor(mulDiv(polity.treasury_cu, bonus, SCALE.Q));
+}
+/**
+ * Health capacity bonus from apothecaries [0, SCALE.Q].
+ * Add to `deriveHealthCapacity(polity)` result in Phase-88.
+ */
+export function computeApothecaryHealthBonus(structures) {
+    return computeInfraBonus(structures, "apothecary");
+}

package/dist/src/unrest.d.ts

@@ -0,0 +1,99 @@
+import type { Q } from "./units.js";
+import type { Polity } from "./polity.js";
+/**
+ * Pressure signals fed into `computeUnrestLevel`.
+ * All fields are Q fractions [0, SCALE.Q]; omit any that are not applicable.
+ */
+export interface UnrestFactors {
+    /** Phase-87 famine push pressure. */
+    faminePressure_Q?: Q;
+    /** Phase-88 epidemic flight pressure. */
+    epidemicPressure_Q?: Q;
+    /** Phase-85 heresy risk. */
+    heresyRisk_Q?: Q;
+    /**
+     * Weakest feudal bond strength [0, SCALE.Q] from Phase-79.
+     * Low value → high feudal unrest contribution.
+     */
+    weakestBond_Q?: Q;
+}
+/** Possible outcomes of a rebellion resolution. */
+export type RebellionOutcome = "quelled" | "uprising" | "civil_war";
+/** Result returned by `resolveRebellion`. */
+export interface RebellionResult {
+    outcome: RebellionOutcome;
+    /** Morale penalty applied to the polity (always ≤ 0). */
+    moraleHit_Q: number;
+    /** Stability penalty applied to the polity (always ≤ 0). */
+    stabilityHit_Q: number;
+    /** Treasury plundered by rebels [cost units]. */
+    treasuryLoss: number;
+}
+/** Outcome of `stepUnrest` — the changes applied this step. */
+export interface UnrestStepResult {
+    unrestLevel_Q: Q;
+    moraleDecay_Q: number;
+    stabilityDecay_Q: number;
+    /** Whether rebellion threshold was crossed (host should call resolveRebellion). */
+    rebellionRisk: boolean;
+}
+/** Weights applied to each pressure source in `computeUnrestLevel`. */
+export declare const UNREST_MORALE_WEIGHT_Q: Q;
+export declare const UNREST_STABILITY_WEIGHT_Q: Q;
+export declare const UNREST_FAMINE_WEIGHT_Q: Q;
+export declare const UNREST_EPIDEMIC_WEIGHT_Q: Q;
+export declare const UNREST_HERESY_WEIGHT_Q: Q;
+export declare const UNREST_FEUDAL_WEIGHT_Q: Q;
+/** Unrest above this threshold → morale and stability begin draining. */
+export declare const UNREST_ACTION_THRESHOLD_Q: Q;
+/** Unrest above this threshold → rebellion risk flag raised. */
+export declare const REBELLION_THRESHOLD_Q: Q;
+/** Maximum daily morale drain from sustained unrest [Q/day]. */
+export declare const UNREST_MORALE_DRAIN_Q: Q;
+/** Maximum daily stability drain from sustained unrest [Q/day]. */
+export declare const UNREST_STABILITY_DRAIN_Q: Q;
+/** Fraction of treasury rebels plunder during an uprising or civil war. */
+export declare const REBELLION_TREASURY_RAID_Q: Q;
+/**
+ * Compute the composite unrest level [0, SCALE.Q] for a polity.
+ *
+ * Unrest is the weighted sum of:
+ * - Low morale   (`(SCALE.Q - moraleQ)    × MORALE_WEIGHT`)
+ * - Low stability (`(SCALE.Q - stabilityQ) × STABILITY_WEIGHT`)
+ * - Famine pressure  × FAMINE_WEIGHT
+ * - Epidemic pressure × EPIDEMIC_WEIGHT
+ * - Heresy risk      × HERESY_WEIGHT
+ * - Feudal deficit   × FEUDAL_WEIGHT  (`SCALE.Q − weakestBond_Q`)
+ *
+ * All inputs are optional; omitted factors contribute zero.
+ */
+export declare function computeUnrestLevel(polity: Polity, factors?: UnrestFactors): Q;
+/**
+ * Apply unrest consequences to a polity for `elapsedDays` days.
+ *
+ * When `unrestLevel_Q > UNREST_ACTION_THRESHOLD_Q`:
+ * - Drains morale at rate `(unrest − threshold) × MORALE_DRAIN_Q / SCALE.Q` per day.
+ * - Drains stability at a lower rate.
+ *
+ * Mutates `polity.moraleQ` and `polity.stabilityQ` in place.
+ * Returns the step result for host inspection.
+ */
+export declare function stepUnrest(polity: Polity, unrestLevel_Q: Q, elapsedDays: number): UnrestStepResult;
+/**
+ * Resolve a rebellion event deterministically.
+ *
+ * Outcomes:
+ * - `"quelled"`:   rebels dispersed — morale/treasury hit only.
+ * - `"uprising"`:  significant unrest — larger morale/stability hit + treasury raid.
+ * - `"civil_war"`: polity fractures — severe penalties across all stats.
+ *
+ * Outcome probability is weighted by unrest level vs. military strength:
+ * - High military strength + moderate unrest → likely `"quelled"`
+ * - Low military + high unrest → risk of `"civil_war"`
+ *
+ * Mutates polity morale, stability, and treasury.
+ *
+ * @param worldSeed  World seed for deterministic resolution.
+ * @param tick       Current simulation tick.
+ */
+export declare function resolveRebellion(polity: Polity, worldSeed: number, tick: number): RebellionResult;

package/dist/src/unrest.js

@@ -0,0 +1,147 @@
+// src/unrest.ts — Phase 90: Civil Unrest & Rebellion
+//
+// Aggregates pressure signals from existing systems into a composite unrest
+// level, drains polity morale and stability under sustained pressure, and
+// resolves rebellion events deterministically.
+//
+// Design:
+//   - Pure data layer — no Entity fields, no kernel changes.
+//   - `computeUnrestLevel` is a pure aggregator: callers pass pre-computed
+//     pressure values from Phase-85 (heresy), Phase-87 (famine), Phase-88
+//     (epidemic), Phase-79 (weakest feudal bond), etc.
+//   - `stepUnrest` mutates polity.moraleQ and polity.stabilityQ when unrest
+//     exceeds thresholds.
+//   - `resolveRebellion` uses eventSeed for full determinism and replay safety.
+//
+// Integration:
+//   Phase 61 (Polity):     mutates moraleQ / stabilityQ; reads militaryStrength_Q.
+//   Phase 79 (Feudal):     weakestBond_Q input.
+//   Phase 85 (Faith):      heresyRisk_Q input.
+//   Phase 87 (Granary):    faminePressure_Q input from computeFamineMigrationPush.
+//   Phase 88 (Epidemic):   epidemicPressure_Q input from computeEpidemicMigrationPush.
+import { q, SCALE, clampQ, mulDiv } from "./units.js";
+import { eventSeed, hashString } from "./sim/seeds.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Weights applied to each pressure source in `computeUnrestLevel`. */
+export const UNREST_MORALE_WEIGHT_Q = q(0.30);
+export const UNREST_STABILITY_WEIGHT_Q = q(0.25);
+export const UNREST_FAMINE_WEIGHT_Q = q(0.20);
+export const UNREST_EPIDEMIC_WEIGHT_Q = q(0.10);
+export const UNREST_HERESY_WEIGHT_Q = q(0.10);
+export const UNREST_FEUDAL_WEIGHT_Q = q(0.05);
+/** Unrest above this threshold → morale and stability begin draining. */
+export const UNREST_ACTION_THRESHOLD_Q = q(0.30);
+/** Unrest above this threshold → rebellion risk flag raised. */
+export const REBELLION_THRESHOLD_Q = q(0.65);
+/** Maximum daily morale drain from sustained unrest [Q/day]. */
+export const UNREST_MORALE_DRAIN_Q = q(0.005);
+/** Maximum daily stability drain from sustained unrest [Q/day]. */
+export const UNREST_STABILITY_DRAIN_Q = q(0.003);
+/** Fraction of treasury rebels plunder during an uprising or civil war. */
+export const REBELLION_TREASURY_RAID_Q = q(0.15);
+// ── Unrest computation ────────────────────────────────────────────────────────
+/**
+ * Compute the composite unrest level [0, SCALE.Q] for a polity.
+ *
+ * Unrest is the weighted sum of:
+ * - Low morale   (`(SCALE.Q - moraleQ)    × MORALE_WEIGHT`)
+ * - Low stability (`(SCALE.Q - stabilityQ) × STABILITY_WEIGHT`)
+ * - Famine pressure  × FAMINE_WEIGHT
+ * - Epidemic pressure × EPIDEMIC_WEIGHT
+ * - Heresy risk      × HERESY_WEIGHT
+ * - Feudal deficit   × FEUDAL_WEIGHT  (`SCALE.Q − weakestBond_Q`)
+ *
+ * All inputs are optional; omitted factors contribute zero.
+ */
+export function computeUnrestLevel(polity, factors = {}) {
+    const moraleContrib = mulDiv(SCALE.Q - polity.moraleQ, UNREST_MORALE_WEIGHT_Q, SCALE.Q);
+    const stabilityContrib = mulDiv(SCALE.Q - polity.stabilityQ, UNREST_STABILITY_WEIGHT_Q, SCALE.Q);
+    const famineContrib = mulDiv(factors.faminePressure_Q ?? 0, UNREST_FAMINE_WEIGHT_Q, SCALE.Q);
+    const epidemicContrib = mulDiv(factors.epidemicPressure_Q ?? 0, UNREST_EPIDEMIC_WEIGHT_Q, SCALE.Q);
+    const heresyContrib = mulDiv(factors.heresyRisk_Q ?? 0, UNREST_HERESY_WEIGHT_Q, SCALE.Q);
+    const feudalDeficit = factors.weakestBond_Q != null
+        ? clampQ(SCALE.Q - factors.weakestBond_Q, 0, SCALE.Q)
+        : 0;
+    const feudalContrib = mulDiv(feudalDeficit, UNREST_FEUDAL_WEIGHT_Q, SCALE.Q);
+    const total = moraleContrib + stabilityContrib + famineContrib +
+        epidemicContrib + heresyContrib + feudalContrib;
+    return clampQ(total, 0, SCALE.Q);
+}
+// ── Unrest step ───────────────────────────────────────────────────────────────
+/**
+ * Apply unrest consequences to a polity for `elapsedDays` days.
+ *
+ * When `unrestLevel_Q > UNREST_ACTION_THRESHOLD_Q`:
+ * - Drains morale at rate `(unrest − threshold) × MORALE_DRAIN_Q / SCALE.Q` per day.
+ * - Drains stability at a lower rate.
+ *
+ * Mutates `polity.moraleQ` and `polity.stabilityQ` in place.
+ * Returns the step result for host inspection.
+ */
+export function stepUnrest(polity, unrestLevel_Q, elapsedDays) {
+    const excess = clampQ(unrestLevel_Q - UNREST_ACTION_THRESHOLD_Q, 0, SCALE.Q);
+    const moraleDecayPerDay = mulDiv(excess, UNREST_MORALE_DRAIN_Q, SCALE.Q);
+    const stabilityDecayPerDay = mulDiv(excess, UNREST_STABILITY_DRAIN_Q, SCALE.Q);
+    const totalMoraleDecay = Math.round(moraleDecayPerDay * elapsedDays);
+    const totalStabilityDecay = Math.round(stabilityDecayPerDay * elapsedDays);
+    polity.moraleQ = clampQ(polity.moraleQ - totalMoraleDecay, 0, SCALE.Q);
+    polity.stabilityQ = clampQ(polity.stabilityQ - totalStabilityDecay, 0, SCALE.Q);
+    return {
+        unrestLevel_Q,
+        moraleDecay_Q: totalMoraleDecay,
+        stabilityDecay_Q: totalStabilityDecay,
+        rebellionRisk: unrestLevel_Q > REBELLION_THRESHOLD_Q,
+    };
+}
+// ── Rebellion resolution ──────────────────────────────────────────────────────
+/**
+ * Resolve a rebellion event deterministically.
+ *
+ * Outcomes:
+ * - `"quelled"`:   rebels dispersed — morale/treasury hit only.
+ * - `"uprising"`:  significant unrest — larger morale/stability hit + treasury raid.
+ * - `"civil_war"`: polity fractures — severe penalties across all stats.
+ *
+ * Outcome probability is weighted by unrest level vs. military strength:
+ * - High military strength + moderate unrest → likely `"quelled"`
+ * - Low military + high unrest → risk of `"civil_war"`
+ *
+ * Mutates polity morale, stability, and treasury.
+ *
+ * @param worldSeed  World seed for deterministic resolution.
+ * @param tick       Current simulation tick.
+ */
+export function resolveRebellion(polity, worldSeed, tick) {
+    const polityHash = hashString(polity.id);
+    const seed = eventSeed(worldSeed, tick, polityHash, 0, 9001); // salt: rebellion
+    const roll = seed % SCALE.Q; // [0, SCALE.Q)
+    // Suppression capacity = military strength
+    const suppressCap = polity.militaryStrength_Q;
+    // Civil war threshold = low suppression + any roll in top quarter
+    const civilWarThresh = clampQ(SCALE.Q - suppressCap, 0, SCALE.Q);
+    const uprisingThresh = Math.round(civilWarThresh * 0.6);
+    let outcome;
+    if (roll >= civilWarThresh) {
+        outcome = "quelled";
+    }
+    else if (roll >= uprisingThresh) {
+        outcome = "uprising";
+    }
+    else {
+        outcome = "civil_war";
+    }
+    const moraleHit = outcome === "quelled" ? -q(0.05)
+        : outcome === "uprising" ? -q(0.15)
+            : -q(0.30);
+    const stabilityHit = outcome === "quelled" ? -q(0.03)
+        : outcome === "uprising" ? -q(0.10)
+            : -q(0.25);
+    const treasuryRaid = outcome === "quelled"
+        ? 0
+        : Math.floor(mulDiv(polity.treasury_cu, REBELLION_TREASURY_RAID_Q, SCALE.Q)
+            * (outcome === "civil_war" ? 2 : 1));
+    polity.moraleQ = clampQ(polity.moraleQ + moraleHit, 0, SCALE.Q);
+    polity.stabilityQ = clampQ(polity.stabilityQ + stabilityHit, 0, SCALE.Q);
+    polity.treasury_cu = Math.max(0, polity.treasury_cu - treasuryRaid);
+    return { outcome, moraleHit_Q: moraleHit, stabilityHit_Q: stabilityHit, treasuryLoss: treasuryRaid };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@its-not-rocket-science/ananke",
-  "version": "0.1.32",
+  "version": "0.1.35",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",
@@ -114,6 +114,18 @@
     "./granary": {
       "import": "./dist/src/granary.js",
       "types": "./dist/src/granary.d.ts"
+    },
+    "./epidemic": {
+      "import": "./dist/src/epidemic.js",
+      "types": "./dist/src/epidemic.d.ts"
+    },
+    "./infrastructure": {
+      "import": "./dist/src/infrastructure.js",
+      "types": "./dist/src/infrastructure.d.ts"
+    },
+    "./unrest": {
+      "import": "./dist/src/unrest.js",
+      "types": "./dist/src/unrest.d.ts"
     }
   },
   "files": [