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

package/CHANGELOG.md

@@ -6,6 +6,45 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [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
+
+- **Phase 86 · Population Dynamics & Demographics** (`src/demography.ts`)
+  - Annual Q rates for birth and death (fraction of population per year) to preserve fixed-point precision.
+  - `BASELINE_BIRTH_RATE_ANNUAL_Q = q(0.035)` (≈ 3.5%/year); `BASELINE_DEATH_RATE_ANNUAL_Q = q(0.030)` (≈ 3.0%/year).
+  - `computeBirthRate(polity)` → Q: morale linearly scales rate between 50% and 150% of baseline.
+  - `computeDeathRate(polity, deathPressure_Q?, foodSupply_Q?)` → Q: baseline reduced by tech era (`TECH_ERA_DEATH_MUL`), plus instability bonus (up to `INSTABILITY_DEATH_ANNUAL_Q = q(0.015)`), optional external pressure, and famine bonus (`FAMINE_DEATH_ANNUAL_Q = q(0.030)`).
+  - `computeNetGrowthRate(polity, ...)` → signed number (may be negative).
+  - `stepPolityPopulation(polity, elapsedDays, deathPressure_Q?, foodSupply_Q?)` → `DemographicsStepResult`: mutates `polity.population`; formula `round(population × netAnnualRate_Q × days / (365 × SCALE.Q))`; clamps to ≥ 0.
+  - **Famine**: `FAMINE_THRESHOLD_Q = q(0.20)` — food below this activates extra mortality and migration push.
+  - `computeFamineMigrationPush(foodSupply_Q)` → Q [0, `FAMINE_MIGRATION_PUSH_Q = q(0.30)`]: linear from zero (at threshold) to peak (at food = 0); integrates with Phase-81 push pressure.
+  - `computeCarryingCapacity(polity)` — soft cap by tech era (Stone 50 k → Modern 200 M); `isOverCapacity(polity)`.
+  - `estimateAnnualBirths` / `estimateAnnualDeaths` — reporting utilities.
+  - Phase-56 (disease) and Phase-84 (siege) integrate via `deathPressure_Q`; Phase-81 (migration) integrates via `computeFamineMigrationPush`; Phase-78 (calendar) via caller-supplied seasonal multipliers.
+  - Added `./demography` subpath export to `package.json`.
+  - 51 new tests; 4,561 total. Coverage maintained above all thresholds.
+
+---
+
 ## [0.1.30] — 2026-03-26
 
 ### Added

package/dist/src/demography.d.ts

@@ -0,0 +1,122 @@
+import type { Q } from "./units.js";
+import type { Polity } from "./polity.js";
+/** Baseline annual birth rate [Q = fraction of population per year]. ≈ 3.5%/year. */
+export declare const BASELINE_BIRTH_RATE_ANNUAL_Q: Q;
+/** Baseline annual death rate [Q = fraction of population per year]. ≈ 3.0%/year. */
+export declare const BASELINE_DEATH_RATE_ANNUAL_Q: Q;
+/**
+ * Morale floor multiplier on birth rate.
+ *
+ * Birth rate factor = `BIRTH_RATE_MORALE_FLOOR_Q + moraleQ`, yielding:
+ *   moraleQ = 0        → factor = q(0.50) → birth rate × 0.50
+ *   moraleQ = SCALE.Q  → factor = q(1.50) → birth rate × 1.50
+ */
+export declare const BIRTH_RATE_MORALE_FLOOR_Q: Q;
+/**
+ * Additional annual death rate at zero stability.
+ * Linearly scaled by `(SCALE.Q − stabilityQ) / SCALE.Q`.
+ * Full bonus at stability = 0; zero at stability = SCALE.Q.
+ */
+export declare const INSTABILITY_DEATH_ANNUAL_Q: Q;
+/** Food supply fraction below which famine is active [0, SCALE.Q]. */
+export declare const FAMINE_THRESHOLD_Q: Q;
+/** Additional annual death rate during famine (+3%/year on top of baseline). */
+export declare const FAMINE_DEATH_ANNUAL_Q: Q;
+/**
+ * Peak famine-driven migration push pressure (at food = 0).
+ * Integrates with Phase-81 `computePushPressure` as an additive bonus.
+ */
+export declare const FAMINE_MIGRATION_PUSH_Q: Q;
+/**
+ * Tech-era multiplier applied to the baseline death rate.
+ * Better technology → lower mortality from disease and malnutrition.
+ * Expressed as a Q fraction of SCALE.Q.
+ */
+export declare const TECH_ERA_DEATH_MUL: Record<string, number>;
+/**
+ * Soft carrying capacity by tech era.
+ * `stepPolityPopulation` does not enforce it — host checks `isOverCapacity`
+ * and applies extra emigration pressure via Phase-81 if desired.
+ */
+export declare const CARRYING_CAPACITY_BY_ERA: Record<string, number>;
+/** Outcome of a single `stepPolityPopulation` call. */
+export interface DemographicsStepResult {
+    /** Signed population change (positive = growth, negative = decline). */
+    popDelta: number;
+    /** New population after applying delta (clamped to ≥ 0). */
+    newPopulation: number;
+    /** Effective annual birth rate used this step. */
+    effectiveBirthRate_Q: Q;
+    /** Effective annual death rate used this step (all pressures included). */
+    effectiveDeathRate_Q: Q;
+    /** Whether famine was active this step. */
+    famine: boolean;
+}
+/**
+ * Compute the effective annual birth rate for a polity [Q = fraction/year].
+ *
+ * Morale scales birth rate linearly between 50% and 150% of baseline:
+ *   moraleQ = 0        → BASELINE × 0.50  (≈ 1.75%/year)
+ *   moraleQ = SCALE.Q  → BASELINE × 1.50  (≈ 5.25%/year)
+ */
+export declare function computeBirthRate(polity: Polity): Q;
+/**
+ * Compute the effective annual death rate for a polity [Q = fraction/year].
+ *
+ * Factors (additive):
+ * 1. Baseline reduced by tech era (better medicine / nutrition).
+ * 2. Instability bonus: up to `INSTABILITY_DEATH_ANNUAL_Q` at stability = 0.
+ * 3. External death pressure (caller: Phase-56 epidemic or Phase-84 siege casualties).
+ * 4. Famine bonus: `FAMINE_DEATH_ANNUAL_Q` when `foodSupply_Q < FAMINE_THRESHOLD_Q`.
+ *
+ * @param deathPressure_Q  Annual mortality fraction from external cause.
+ * @param foodSupply_Q     Current food supply [0, SCALE.Q]; omit if unknown.
+ */
+export declare function computeDeathRate(polity: Polity, deathPressure_Q?: Q, foodSupply_Q?: Q): Q;
+/**
+ * Compute the net annual growth rate (birth rate − death rate).
+ * Negative values indicate population decline.
+ */
+export declare function computeNetGrowthRate(polity: Polity, deathPressure_Q?: Q, foodSupply_Q?: Q): number;
+/**
+ * Step polity population forward by `elapsedDays` simulated days.
+ *
+ * Mutates `polity.population` in place and returns step metadata.
+ *
+ * Delta formula (fixed-point, single rounding):
+ *   `popDelta = round(population × netAnnualRate_Q × elapsedDays / (365 × SCALE.Q))`
+ *
+ * @param elapsedDays     Number of simulated days to advance (typically 1–30).
+ * @param deathPressure_Q Annual mortality fraction from disease or siege casualties.
+ * @param foodSupply_Q    Food supply level [0, SCALE.Q]; famine fires below
+ *                        `FAMINE_THRESHOLD_Q`.
+ */
+export declare function stepPolityPopulation(polity: Polity, elapsedDays: number, deathPressure_Q?: Q, foodSupply_Q?: Q): DemographicsStepResult;
+/**
+ * Compute famine-driven migration push pressure [0, SCALE.Q].
+ *
+ * Zero at or above `FAMINE_THRESHOLD_Q`.  Scales linearly from zero (at the
+ * threshold) to `FAMINE_MIGRATION_PUSH_Q` (at food = 0).
+ *
+ * Add the result to Phase-81 `computePushPressure` output.
+ */
+export declare function computeFamineMigrationPush(foodSupply_Q: Q): Q;
+/**
+ * Soft carrying capacity for a polity based on tech era.
+ *
+ * `stepPolityPopulation` does not enforce this cap.  The host should call
+ * `isOverCapacity` after each step and pass additional emigration pressure
+ * to Phase-81 when it returns `true`.
+ */
+export declare function computeCarryingCapacity(polity: Polity): number;
+/** Return `true` if the polity's population exceeds its tech-era carrying capacity. */
+export declare function isOverCapacity(polity: Polity): boolean;
+/**
+ * Estimate annual births from a birth rate and population.
+ * Useful for host display and scenario planning.
+ */
+export declare function estimateAnnualBirths(population: number, birthRate_Q: Q): number;
+/**
+ * Estimate annual deaths from a death rate and population.
+ */
+export declare function estimateAnnualDeaths(population: number, deathRate_Q: Q): number;

package/dist/src/demography.js

@@ -0,0 +1,190 @@
+// src/demography.ts — Phase 86: Population Dynamics & Demographics
+//
+// Models natural population growth, mortality, and famine at polity level.
+// All rates are annual Q fractions (fraction of population per year) so that
+// SCALE.Q = 10000 gives sufficient precision (0.01%/year resolution).
+//
+// Step formula:
+//   popDelta = round(population × netAnnualRate_Q × elapsedDays / (365 × SCALE.Q))
+//
+// For small polities (< ~10 000) single-day steps yield zero delta;
+// call with 7- or 30-day intervals for visible change.
+//
+// Integration:
+//   - Phase 61 (Polity):   reads/mutates polity.population; uses morale/stability/techEra.
+//   - Phase 56 (Disease):  caller passes epidemic annual mortality as deathPressure_Q.
+//   - Phase 81 (Migration): computeFamineMigrationPush() is an additive push bonus.
+//   - Phase 78 (Calendar): caller may pass seasonal birth/death multipliers.
+import { q, SCALE, clampQ, mulDiv } from "./units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Baseline annual birth rate [Q = fraction of population per year]. ≈ 3.5%/year. */
+export const BASELINE_BIRTH_RATE_ANNUAL_Q = q(0.035);
+/** Baseline annual death rate [Q = fraction of population per year]. ≈ 3.0%/year. */
+export const BASELINE_DEATH_RATE_ANNUAL_Q = q(0.030);
+/**
+ * Morale floor multiplier on birth rate.
+ *
+ * Birth rate factor = `BIRTH_RATE_MORALE_FLOOR_Q + moraleQ`, yielding:
+ *   moraleQ = 0        → factor = q(0.50) → birth rate × 0.50
+ *   moraleQ = SCALE.Q  → factor = q(1.50) → birth rate × 1.50
+ */
+export const BIRTH_RATE_MORALE_FLOOR_Q = q(0.50);
+/**
+ * Additional annual death rate at zero stability.
+ * Linearly scaled by `(SCALE.Q − stabilityQ) / SCALE.Q`.
+ * Full bonus at stability = 0; zero at stability = SCALE.Q.
+ */
+export const INSTABILITY_DEATH_ANNUAL_Q = q(0.015);
+/** Food supply fraction below which famine is active [0, SCALE.Q]. */
+export const FAMINE_THRESHOLD_Q = q(0.20);
+/** Additional annual death rate during famine (+3%/year on top of baseline). */
+export const FAMINE_DEATH_ANNUAL_Q = q(0.030);
+/**
+ * Peak famine-driven migration push pressure (at food = 0).
+ * Integrates with Phase-81 `computePushPressure` as an additive bonus.
+ */
+export const FAMINE_MIGRATION_PUSH_Q = q(0.30);
+/**
+ * Tech-era multiplier applied to the baseline death rate.
+ * Better technology → lower mortality from disease and malnutrition.
+ * Expressed as a Q fraction of SCALE.Q.
+ */
+export const TECH_ERA_DEATH_MUL = {
+    "Stone": SCALE.Q, // no reduction
+    "Bronze": Math.round(SCALE.Q * 0.95), // −5%
+    "Iron": Math.round(SCALE.Q * 0.90), // −10%
+    "Medieval": Math.round(SCALE.Q * 0.85), // −15%
+    "Renaissance": Math.round(SCALE.Q * 0.80), // −20%
+    "Industrial": Math.round(SCALE.Q * 0.65), // −35%
+    "Modern": Math.round(SCALE.Q * 0.50), // −50%
+};
+/**
+ * Soft carrying capacity by tech era.
+ * `stepPolityPopulation` does not enforce it — host checks `isOverCapacity`
+ * and applies extra emigration pressure via Phase-81 if desired.
+ */
+export const CARRYING_CAPACITY_BY_ERA = {
+    "Stone": 50_000,
+    "Bronze": 200_000,
+    "Iron": 500_000,
+    "Medieval": 2_000_000,
+    "Renaissance": 5_000_000,
+    "Industrial": 20_000_000,
+    "Modern": 200_000_000,
+};
+// ── Rate computation ──────────────────────────────────────────────────────────
+/**
+ * Compute the effective annual birth rate for a polity [Q = fraction/year].
+ *
+ * Morale scales birth rate linearly between 50% and 150% of baseline:
+ *   moraleQ = 0        → BASELINE × 0.50  (≈ 1.75%/year)
+ *   moraleQ = SCALE.Q  → BASELINE × 1.50  (≈ 5.25%/year)
+ */
+export function computeBirthRate(polity) {
+    // factor ∈ [q(0.50), q(1.50)] = [5000, 15000]
+    const factor = BIRTH_RATE_MORALE_FLOOR_Q + polity.moraleQ;
+    return clampQ(mulDiv(BASELINE_BIRTH_RATE_ANNUAL_Q, factor, SCALE.Q), 0, SCALE.Q);
+}
+/**
+ * Compute the effective annual death rate for a polity [Q = fraction/year].
+ *
+ * Factors (additive):
+ * 1. Baseline reduced by tech era (better medicine / nutrition).
+ * 2. Instability bonus: up to `INSTABILITY_DEATH_ANNUAL_Q` at stability = 0.
+ * 3. External death pressure (caller: Phase-56 epidemic or Phase-84 siege casualties).
+ * 4. Famine bonus: `FAMINE_DEATH_ANNUAL_Q` when `foodSupply_Q < FAMINE_THRESHOLD_Q`.
+ *
+ * @param deathPressure_Q  Annual mortality fraction from external cause.
+ * @param foodSupply_Q     Current food supply [0, SCALE.Q]; omit if unknown.
+ */
+export function computeDeathRate(polity, deathPressure_Q, foodSupply_Q) {
+    const techMul = TECH_ERA_DEATH_MUL[polity.techEra] ?? SCALE.Q;
+    const techBase = mulDiv(BASELINE_DEATH_RATE_ANNUAL_Q, techMul, SCALE.Q);
+    const instFrac = SCALE.Q - polity.stabilityQ; // [0, SCALE.Q]
+    const instDeath = mulDiv(INSTABILITY_DEATH_ANNUAL_Q, instFrac, SCALE.Q);
+    const famine = foodSupply_Q != null && foodSupply_Q < FAMINE_THRESHOLD_Q;
+    const famineBonus = famine ? FAMINE_DEATH_ANNUAL_Q : 0;
+    const pressure = deathPressure_Q ?? 0;
+    return clampQ(techBase + instDeath + famineBonus + pressure, 0, SCALE.Q);
+}
+/**
+ * Compute the net annual growth rate (birth rate − death rate).
+ * Negative values indicate population decline.
+ */
+export function computeNetGrowthRate(polity, deathPressure_Q, foodSupply_Q) {
+    return computeBirthRate(polity) - computeDeathRate(polity, deathPressure_Q, foodSupply_Q);
+}
+// ── Population step ───────────────────────────────────────────────────────────
+/**
+ * Step polity population forward by `elapsedDays` simulated days.
+ *
+ * Mutates `polity.population` in place and returns step metadata.
+ *
+ * Delta formula (fixed-point, single rounding):
+ *   `popDelta = round(population × netAnnualRate_Q × elapsedDays / (365 × SCALE.Q))`
+ *
+ * @param elapsedDays     Number of simulated days to advance (typically 1–30).
+ * @param deathPressure_Q Annual mortality fraction from disease or siege casualties.
+ * @param foodSupply_Q    Food supply level [0, SCALE.Q]; famine fires below
+ *                        `FAMINE_THRESHOLD_Q`.
+ */
+export function stepPolityPopulation(polity, elapsedDays, deathPressure_Q, foodSupply_Q) {
+    const birthRate = computeBirthRate(polity);
+    const deathRate = computeDeathRate(polity, deathPressure_Q, foodSupply_Q);
+    const netRate = birthRate - deathRate;
+    const famine = foodSupply_Q != null && foodSupply_Q < FAMINE_THRESHOLD_Q;
+    const rawDelta = Math.round(polity.population * netRate * elapsedDays / (365 * SCALE.Q));
+    const newPop = Math.max(0, polity.population + rawDelta);
+    polity.population = newPop;
+    return {
+        popDelta: rawDelta,
+        newPopulation: newPop,
+        effectiveBirthRate_Q: birthRate,
+        effectiveDeathRate_Q: deathRate,
+        famine,
+    };
+}
+// ── Famine ────────────────────────────────────────────────────────────────────
+/**
+ * Compute famine-driven migration push pressure [0, SCALE.Q].
+ *
+ * Zero at or above `FAMINE_THRESHOLD_Q`.  Scales linearly from zero (at the
+ * threshold) to `FAMINE_MIGRATION_PUSH_Q` (at food = 0).
+ *
+ * Add the result to Phase-81 `computePushPressure` output.
+ */
+export function computeFamineMigrationPush(foodSupply_Q) {
+    if (foodSupply_Q >= FAMINE_THRESHOLD_Q)
+        return 0;
+    const deficit = FAMINE_THRESHOLD_Q - foodSupply_Q; // (0, FAMINE_THRESHOLD_Q]
+    return clampQ(mulDiv(FAMINE_MIGRATION_PUSH_Q, deficit, FAMINE_THRESHOLD_Q), 0, SCALE.Q);
+}
+// ── Carrying capacity ─────────────────────────────────────────────────────────
+/**
+ * Soft carrying capacity for a polity based on tech era.
+ *
+ * `stepPolityPopulation` does not enforce this cap.  The host should call
+ * `isOverCapacity` after each step and pass additional emigration pressure
+ * to Phase-81 when it returns `true`.
+ */
+export function computeCarryingCapacity(polity) {
+    return CARRYING_CAPACITY_BY_ERA[polity.techEra] ?? 50_000;
+}
+/** Return `true` if the polity's population exceeds its tech-era carrying capacity. */
+export function isOverCapacity(polity) {
+    return polity.population > computeCarryingCapacity(polity);
+}
+// ── Reporting utilities ───────────────────────────────────────────────────────
+/**
+ * Estimate annual births from a birth rate and population.
+ * Useful for host display and scenario planning.
+ */
+export function estimateAnnualBirths(population, birthRate_Q) {
+    return Math.round(population * birthRate_Q / SCALE.Q);
+}
+/**
+ * Estimate annual deaths from a death rate and population.
+ */
+export function estimateAnnualDeaths(population, deathRate_Q) {
+    return Math.round(population * deathRate_Q / 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/package.json

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