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

package/CHANGELOG.md

@@ -6,6 +6,64 @@ 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
+
+- **Phase 87 · Granary & Food Supply** (`src/granary.ts`)
+  - `GranaryState { polityId, grain_su }` — grain reserves in supply units (1 su = food for 1 person for 1 day); capacity derived dynamically from `polity.population × GRANARY_CAPACITY_DAYS = 730`.
+  - `createGranary(polity)` — initialises with one year of consumption.
+  - `computeCapacity(polity)` → integer; `computeFoodSupply_Q(polity, granary)` → Q [0, SCALE.Q] — feeds directly into Phase-86 `stepPolityPopulation(foodSupply_Q)`.
+  - **Harvest yield**: `HARVEST_BASE_SU_PER_CAPITA = 250` su/person/harvest; `HARVEST_YIELD_BASE_Q = q(0.70)` floor; `HARVEST_STABILITY_BONUS_Q = q(0.30)` max bonus from stability. `deriveHarvestYieldFactor(polity, season_Q?)` integrates Phase-78 seasonal multiplier.
+  - `computeHarvestYield(polity, yieldFactor_Q?)` → su; `triggerHarvest(polity, granary, yieldFactor_Q?)` → added su (clamped to capacity).
+  - `stepGranaryConsumption(polity, granary, elapsedDays)` → consumed su; drains `population × elapsedDays` su per step; floors at 0.
+  - `tradeFoodSupply(fromGranary, toGranary, toPolity, amount_su)` → transferred su; limited by source grain, destination capacity. Integrates with Phase-83 trade routes.
+  - `raidGranary(granary, raidFraction_Q?)` → plundered su; defaults to `RAID_FRACTION_Q = q(0.40)`. Integrates with Phase-84 siege attacker victory.
+  - Added `./granary` subpath export to `package.json`.
+  - 47 new tests; 4,608 total. Coverage maintained above all thresholds.
+
+---
+
 ## [0.1.31] — 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/granary.d.ts

@@ -0,0 +1,118 @@
+import type { Q } from "./units.js";
+import type { Polity } from "./polity.js";
+/**
+ * Grain reserves for one polity.
+ *
+ * Capacity is derived (not stored): `population × GRANARY_CAPACITY_DAYS`.
+ * Attach one `GranaryState` per polity; store externally (e.g., `Map<string, GranaryState>`).
+ */
+export interface GranaryState {
+    polityId: string;
+    /** Current grain reserves in supply units (1 su = food for 1 person for 1 day). */
+    grain_su: number;
+}
+/**
+ * Granary holds this many person-days of food at full capacity.
+ * Default: 730 (≈ 2 years of food per capita).
+ */
+export declare const GRANARY_CAPACITY_DAYS = 730;
+/**
+ * Each harvest at full yield contributes this many person-days per capita.
+ * With two harvests/year: 500 annual supply vs. 365 consumption → ~37% surplus headroom.
+ */
+export declare const HARVEST_BASE_SU_PER_CAPITA = 250;
+/**
+ * Minimum harvest yield at zero stability [0, SCALE.Q].
+ * Stability linearly scales yield from this floor to `SCALE.Q` (full yield).
+ */
+export declare const HARVEST_YIELD_BASE_Q: Q;
+/**
+ * Maximum additional yield from full stability [0, SCALE.Q].
+ * yieldFactor = HARVEST_YIELD_BASE_Q + mulDiv(HARVEST_STABILITY_BONUS_Q, stabilityQ, SCALE.Q).
+ */
+export declare const HARVEST_STABILITY_BONUS_Q: Q;
+/**
+ * Fraction of the granary that a successful siege raid removes.
+ * Callers may pass a different fraction to `raidGranary`.
+ */
+export declare const RAID_FRACTION_Q: Q;
+/**
+ * Create a new `GranaryState` for a polity.
+ * Initial reserves default to one year of consumption (stable starting point).
+ */
+export declare function createGranary(polity: Polity): GranaryState;
+/**
+ * Maximum grain the polity can store [supply units].
+ * Scales with current population — a growing polity can store more.
+ */
+export declare function computeCapacity(polity: Polity): number;
+/**
+ * Convert grain reserves to a [0, SCALE.Q] food supply fraction.
+ *
+ * This is the `foodSupply_Q` input for Phase-86 `stepPolityPopulation`:
+ *   - q(1.0) = full granary (no famine)
+ *   - below Phase-86 `FAMINE_THRESHOLD_Q = q(0.20)` → famine active
+ *
+ * Returns 0 when population is zero (prevents division by zero).
+ */
+export declare function computeFoodSupply_Q(polity: Polity, granary: GranaryState): Q;
+/**
+ * Derive the harvest yield factor [0, SCALE.Q] for a polity.
+ *
+ * Formula: `HARVEST_YIELD_BASE_Q + mulDiv(HARVEST_STABILITY_BONUS_Q, stabilityQ, SCALE.Q)`
+ * then optionally multiplied by a Phase-78 seasonal factor.
+ *
+ * @param season_Q  Seasonal multiplier [0, SCALE.Q] from Phase-78 Calendar.
+ *                  `q(1.0)` = summer peak; `q(0.50)` = winter harvest.
+ *                  Omit for an unseasoned annual harvest.
+ */
+export declare function deriveHarvestYieldFactor(polity: Polity, season_Q?: Q): Q;
+/**
+ * Compute the grain added by one harvest [supply units].
+ *
+ * `yield_su = round(population × HARVEST_BASE_SU_PER_CAPITA × yieldFactor_Q / SCALE.Q)`
+ *
+ * @param yieldFactor_Q  Override factor; defaults to `deriveHarvestYieldFactor(polity)`.
+ */
+export declare function computeHarvestYield(polity: Polity, yieldFactor_Q?: Q): number;
+/**
+ * Add one harvest to the granary.
+ *
+ * Grain is clamped to `computeCapacity(polity)` — surplus is lost (no overflow).
+ * Returns the amount actually added (may be less than yield if near capacity).
+ *
+ * Call at the end of each harvest season (biannual: spring + autumn).
+ */
+export declare function triggerHarvest(polity: Polity, granary: GranaryState, yieldFactor_Q?: Q): number;
+/**
+ * Drain daily grain consumption for `elapsedDays` days.
+ *
+ * Consumption = `polity.population × elapsedDays` supply units.
+ * Grain is clamped to 0 (no negative reserves).
+ *
+ * Returns the actual amount consumed (may be less than demand if reserves run low).
+ */
+export declare function stepGranaryConsumption(polity: Polity, granary: GranaryState, elapsedDays: number): number;
+/**
+ * Transfer grain from one polity's granary to another.
+ *
+ * Actual transfer is limited by:
+ * - Grain available in the source granary.
+ * - Remaining capacity in the destination granary.
+ *
+ * Returns the amount actually transferred.
+ * Integrate with Phase-83 trade routes: host calls this when resolving a food route.
+ */
+export declare function tradeFoodSupply(fromGranary: GranaryState, toGranary: GranaryState, toPolity: Polity, amount_su: number): number;
+/**
+ * Plunder a granary after a successful siege.
+ *
+ * Removes `raidFraction_Q` of current grain reserves.
+ * Returns the amount plundered.
+ *
+ * Integrates with Phase-84 siege: call on `outcome === "attacker_victory"`.
+ *
+ * @param raidFraction_Q  Fraction of reserves plundered [0, SCALE.Q].
+ *                        Defaults to `RAID_FRACTION_Q = q(0.40)`.
+ */
+export declare function raidGranary(granary: GranaryState, raidFraction_Q?: Q): number;

package/dist/src/granary.js

@@ -0,0 +1,180 @@
+// src/granary.ts — Phase 87: Granary & Food Supply
+//
+// Tracks grain reserves per polity.  Grain is measured in "supply units" (su)
+// where 1 su feeds one person for one day.  The granary fills at each harvest
+// and drains with daily consumption; when reserves fall below a fraction of
+// capacity, Phase-86 famine mechanics activate.
+//
+// Design:
+//   - Pure data layer — no Entity fields, no kernel changes.
+//   - `GranaryState` stores only grain_su; capacity is derived from polity.population.
+//   - `computeFoodSupply_Q` produces the [0, SCALE.Q] value consumed by Phase-86
+//     `stepPolityPopulation(deathPressure_Q, foodSupply_Q)`.
+//   - Harvest yield is modulated by stability and an optional Phase-78 season multiplier.
+//   - `tradeFoodSupply` integrates with Phase-83 trade routes (caller-driven).
+//   - `raidGranary` integrates with Phase-84 siege warfare (plunder).
+//
+// Integration:
+//   Phase 61 (Polity):    population drives capacity and harvest yield.
+//   Phase 78 (Calendar):  season_Q passed to deriveHarvestYieldFactor.
+//   Phase 83 (Trade):     tradeFoodSupply called when host resolves a food route.
+//   Phase 84 (Siege):     raidGranary called on attacker victory.
+//   Phase 86 (Demography): computeFoodSupply_Q → foodSupply_Q parameter.
+import { q, SCALE, clampQ, mulDiv } from "./units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/**
+ * Granary holds this many person-days of food at full capacity.
+ * Default: 730 (≈ 2 years of food per capita).
+ */
+export const GRANARY_CAPACITY_DAYS = 730;
+/**
+ * Each harvest at full yield contributes this many person-days per capita.
+ * With two harvests/year: 500 annual supply vs. 365 consumption → ~37% surplus headroom.
+ */
+export const HARVEST_BASE_SU_PER_CAPITA = 250;
+/**
+ * Minimum harvest yield at zero stability [0, SCALE.Q].
+ * Stability linearly scales yield from this floor to `SCALE.Q` (full yield).
+ */
+export const HARVEST_YIELD_BASE_Q = q(0.70);
+/**
+ * Maximum additional yield from full stability [0, SCALE.Q].
+ * yieldFactor = HARVEST_YIELD_BASE_Q + mulDiv(HARVEST_STABILITY_BONUS_Q, stabilityQ, SCALE.Q).
+ */
+export const HARVEST_STABILITY_BONUS_Q = q(0.30);
+/**
+ * Fraction of the granary that a successful siege raid removes.
+ * Callers may pass a different fraction to `raidGranary`.
+ */
+export const RAID_FRACTION_Q = q(0.40);
+// ── Factory ───────────────────────────────────────────────────────────────────
+/**
+ * Create a new `GranaryState` for a polity.
+ * Initial reserves default to one year of consumption (stable starting point).
+ */
+export function createGranary(polity) {
+    return {
+        polityId: polity.id,
+        grain_su: polity.population * 365,
+    };
+}
+// ── Capacity & food supply ────────────────────────────────────────────────────
+/**
+ * Maximum grain the polity can store [supply units].
+ * Scales with current population — a growing polity can store more.
+ */
+export function computeCapacity(polity) {
+    return polity.population * GRANARY_CAPACITY_DAYS;
+}
+/**
+ * Convert grain reserves to a [0, SCALE.Q] food supply fraction.
+ *
+ * This is the `foodSupply_Q` input for Phase-86 `stepPolityPopulation`:
+ *   - q(1.0) = full granary (no famine)
+ *   - below Phase-86 `FAMINE_THRESHOLD_Q = q(0.20)` → famine active
+ *
+ * Returns 0 when population is zero (prevents division by zero).
+ */
+export function computeFoodSupply_Q(polity, granary) {
+    const cap = computeCapacity(polity);
+    if (cap <= 0)
+        return 0;
+    return clampQ(Math.round(granary.grain_su * SCALE.Q / cap), 0, SCALE.Q);
+}
+// ── Harvest ───────────────────────────────────────────────────────────────────
+/**
+ * Derive the harvest yield factor [0, SCALE.Q] for a polity.
+ *
+ * Formula: `HARVEST_YIELD_BASE_Q + mulDiv(HARVEST_STABILITY_BONUS_Q, stabilityQ, SCALE.Q)`
+ * then optionally multiplied by a Phase-78 seasonal factor.
+ *
+ * @param season_Q  Seasonal multiplier [0, SCALE.Q] from Phase-78 Calendar.
+ *                  `q(1.0)` = summer peak; `q(0.50)` = winter harvest.
+ *                  Omit for an unseasoned annual harvest.
+ */
+export function deriveHarvestYieldFactor(polity, season_Q) {
+    const stabilityBonus = mulDiv(HARVEST_STABILITY_BONUS_Q, polity.stabilityQ, SCALE.Q);
+    const baseFactor = clampQ(HARVEST_YIELD_BASE_Q + stabilityBonus, 0, SCALE.Q);
+    if (season_Q == null)
+        return baseFactor;
+    return clampQ(mulDiv(baseFactor, season_Q, SCALE.Q), 0, SCALE.Q);
+}
+/**
+ * Compute the grain added by one harvest [supply units].
+ *
+ * `yield_su = round(population × HARVEST_BASE_SU_PER_CAPITA × yieldFactor_Q / SCALE.Q)`
+ *
+ * @param yieldFactor_Q  Override factor; defaults to `deriveHarvestYieldFactor(polity)`.
+ */
+export function computeHarvestYield(polity, yieldFactor_Q) {
+    const factor = yieldFactor_Q ?? deriveHarvestYieldFactor(polity);
+    return Math.round(polity.population * HARVEST_BASE_SU_PER_CAPITA * factor / SCALE.Q);
+}
+/**
+ * Add one harvest to the granary.
+ *
+ * Grain is clamped to `computeCapacity(polity)` — surplus is lost (no overflow).
+ * Returns the amount actually added (may be less than yield if near capacity).
+ *
+ * Call at the end of each harvest season (biannual: spring + autumn).
+ */
+export function triggerHarvest(polity, granary, yieldFactor_Q) {
+    const cap = computeCapacity(polity);
+    const yield_ = computeHarvestYield(polity, yieldFactor_Q);
+    const added = Math.min(yield_, Math.max(0, cap - granary.grain_su));
+    granary.grain_su = Math.min(cap, granary.grain_su + yield_);
+    return added;
+}
+// ── Consumption ───────────────────────────────────────────────────────────────
+/**
+ * Drain daily grain consumption for `elapsedDays` days.
+ *
+ * Consumption = `polity.population × elapsedDays` supply units.
+ * Grain is clamped to 0 (no negative reserves).
+ *
+ * Returns the actual amount consumed (may be less than demand if reserves run low).
+ */
+export function stepGranaryConsumption(polity, granary, elapsedDays) {
+    const demand = polity.population * elapsedDays;
+    const consumed = Math.min(demand, granary.grain_su);
+    granary.grain_su = Math.max(0, granary.grain_su - demand);
+    return consumed;
+}
+// ── Trade food ────────────────────────────────────────────────────────────────
+/**
+ * Transfer grain from one polity's granary to another.
+ *
+ * Actual transfer is limited by:
+ * - Grain available in the source granary.
+ * - Remaining capacity in the destination granary.
+ *
+ * Returns the amount actually transferred.
+ * Integrate with Phase-83 trade routes: host calls this when resolving a food route.
+ */
+export function tradeFoodSupply(fromGranary, toGranary, toPolity, amount_su) {
+    const toCap = computeCapacity(toPolity);
+    const toSpace = Math.max(0, toCap - toGranary.grain_su);
+    const available = fromGranary.grain_su;
+    const transferred = Math.min(amount_su, available, toSpace);
+    fromGranary.grain_su -= transferred;
+    toGranary.grain_su += transferred;
+    return transferred;
+}
+// ── Siege raid ────────────────────────────────────────────────────────────────
+/**
+ * Plunder a granary after a successful siege.
+ *
+ * Removes `raidFraction_Q` of current grain reserves.
+ * Returns the amount plundered.
+ *
+ * Integrates with Phase-84 siege: call on `outcome === "attacker_victory"`.
+ *
+ * @param raidFraction_Q  Fraction of reserves plundered [0, SCALE.Q].
+ *                        Defaults to `RAID_FRACTION_Q = q(0.40)`.
+ */
+export function raidGranary(granary, raidFraction_Q) {
+    const fraction = raidFraction_Q ?? RAID_FRACTION_Q;
+    const plundered = Math.round(mulDiv(granary.grain_su, fraction, SCALE.Q));
+    granary.grain_su = Math.max(0, granary.grain_su - plundered);
+    return plundered;
+}

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.31",
+  "version": "0.1.34",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",
@@ -110,6 +110,18 @@
     "./demography": {
       "import": "./dist/src/demography.js",
       "types": "./dist/src/demography.d.ts"
+    },
+    "./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": [