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

package/CHANGELOG.md

@@ -6,6 +6,46 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@its-not-rocket-science/ananke",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",
@@ -114,6 +114,14 @@
     "./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"
     }
   },
   "files": [