@its-not-rocket-science/ananke 0.1.41 → 0.1.42

package/CHANGELOG.md

@@ -6,6 +6,34 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.42] — 2026-03-26
+
+### Added
+
+- **Phase 97 · Famine Relief & Rationing** (`src/famine.ts`)
+  - `FaminePhase`: `"none" | "shortage" | "famine" | "catastrophe"` — graduated severity above Phase-87 Granary's binary famine flag.
+  - `RationingPolicy`: `"none" | "tight" | "emergency" | "starvation_rations"` — active polity response.
+  - `FamineState { polityId, phase, daysInPhase, cumulativeSeverity_Q }` — per-polity mutable tracker stored externally.
+  - `FaminePressures { deathBonus_Q, migrationPush_Q, unrestPressure_Q }` — advisory bundle; callers pass fields into Phases 86/81/90.
+  - Phase thresholds: shortage < q(0.50), famine < q(0.20), catastrophe < q(0.05) of `computeFoodSupply_Q`.
+  - `FAMINE_PHASE_DEATH_Q`: +1%/year (shortage) → +3%/year (famine) → +7%/year (catastrophe); stacks with Phase-86 base famine death.
+  - `FAMINE_PHASE_MIGRATION_Q`: q(0.08) → q(0.25) → q(0.50) — feeds Phase-81.
+  - `RATIONING_REDUCTION_Q`: tight 20%, emergency 40%, starvation_rations 60% consumption cut.
+  - `RATIONING_UNREST_Q`: q(0.04) → q(0.12) → q(0.25) — rationing itself generates unrest.
+  - `SEVERITY_DELTA_PER_DAY`: none −5 (decay), shortage +2, famine +10, catastrophe +25 per day; `cumulativeSeverity_Q` models long-term famine damage.
+  - `createFamineState(polityId)` — factory.
+  - `computeFaminePhase(foodSupply_Q)` — classifies severity from granary output.
+  - `computeFaminePressures(state, policy?)` — combined famine + rationing advisory pressures.
+  - `stepFamine(state, foodSupply_Q, elapsedDays)` → `boolean` — advances state; returns `true` when phase changes.
+  - `computeRationedConsumption(polity, policy, elapsedDays)` — rationed su demand.
+  - `stepRationedGranary(polity, granary, policy, elapsedDays)` — replaces Phase-87 `stepGranaryConsumption` when rationing is active.
+  - `computeReliefImport(polity, granary, budget_cu, capacityCap_su)` — converts treasury into grain; mutates both in-place; capped by treasury, budget, and granary space.
+  - `isFamineActive(state)` / `isCatastrophicFamine(state)` — convenience predicates.
+  - Added `./famine` subpath export to `package.json`.
+  - 60 new tests; 5,082 total. Coverage: 100% statements/branches/functions/lines on `famine.ts`.
+
+---
+
 ## [0.1.41] — 2026-03-26
 
 ### Added

package/dist/src/famine.d.ts

@@ -0,0 +1,120 @@
+import type { Q } from "./units.js";
+import type { Polity } from "./polity.js";
+import type { GranaryState } from "./granary.js";
+/** Graduated severity of a food crisis. */
+export type FaminePhase = "none" | "shortage" | "famine" | "catastrophe";
+/** Polity policy for reducing per-capita food consumption below normal demand. */
+export type RationingPolicy = "none" | "tight" | "emergency" | "starvation_rations";
+/**
+ * Per-polity famine tracking state.
+ * Attach one to each polity; store externally (e.g. `Map<string, FamineState>`).
+ */
+export interface FamineState {
+    polityId: string;
+    phase: FaminePhase;
+    /** Days spent continuously in the current phase. Resets when phase changes. */
+    daysInPhase: number;
+    /**
+     * Long-term famine damage [0, SCALE.Q].
+     * Accrues during famine/catastrophe (depleted seed grain, dead workers, trauma).
+     * Decays slowly once food supply recovers to "none".
+     */
+    cumulativeSeverity_Q: Q;
+}
+/**
+ * Advisory pressure bundle for downstream phases.
+ * All fields [0, SCALE.Q] unless noted.
+ */
+export interface FaminePressures {
+    /** Additional annual death rate. Supplement Phase-86 `deathPressure_Q`. */
+    deathBonus_Q: Q;
+    /** Migration push. Pass to Phase-81 `computePushPressure`. */
+    migrationPush_Q: Q;
+    /** Combined famine + rationing unrest. Pass to Phase-90 `computeUnrestLevel`. */
+    unrestPressure_Q: Q;
+}
+/** `foodSupply_Q` below this → shortage phase. */
+export declare const SHORTAGE_THRESHOLD_Q: Q;
+/** `foodSupply_Q` below this → famine phase. */
+export declare const FAMINE_THRESHOLD_Q: Q;
+/** `foodSupply_Q` below this → catastrophe phase. */
+export declare const CATASTROPHE_THRESHOLD_Q: Q;
+/**
+ * Additional annual death rate by famine phase [Q].
+ * Phase-86 already applies `FAMINE_DEATH_ANNUAL_Q = q(0.030)` at famine threshold;
+ * these bonuses are additive on top for graduated severity.
+ */
+export declare const FAMINE_PHASE_DEATH_Q: Record<FaminePhase, Q>;
+/** Migration push pressure by famine phase [0, SCALE.Q]. */
+export declare const FAMINE_PHASE_MIGRATION_Q: Record<FaminePhase, Q>;
+/** Base unrest pressure by famine phase [0, SCALE.Q]. */
+export declare const FAMINE_PHASE_UNREST_Q: Record<FaminePhase, Q>;
+/**
+ * Consumption reduction fraction per rationing policy [0, SCALE.Q].
+ * Applied to `polity.population × elapsedDays` to give actual su demand.
+ */
+export declare const RATIONING_REDUCTION_Q: Record<RationingPolicy, Q>;
+/** Unrest pressure added by rationing policy itself [0, SCALE.Q]. */
+export declare const RATIONING_UNREST_Q: Record<RationingPolicy, Q>;
+/** Treasury cost in cu per supply unit of emergency food import (1 su = 1 person-day). */
+export declare const RELIEF_IMPORT_COST_CU_PER_SU = 2;
+/**
+ * Cumulative severity change per day by famine phase [out of SCALE.Q].
+ * Negative values → decay; positive values → accrual.
+ */
+export declare const SEVERITY_DELTA_PER_DAY: Record<FaminePhase, number>;
+/** Create a fresh `FamineState` for a polity (no active famine, zero severity). */
+export declare function createFamineState(polityId: string): FamineState;
+/**
+ * Classify the current famine phase from the granary food supply fraction.
+ *
+ * Obtain `foodSupply_Q` from Phase-87 `computeFoodSupply_Q(polity, granary)`.
+ */
+export declare function computeFaminePhase(foodSupply_Q: Q): FaminePhase;
+/**
+ * Compute the advisory pressure bundle for the current famine state and rationing policy.
+ *
+ * `unrestPressure_Q` sums famine unrest with rationing unrest, clamped to SCALE.Q.
+ */
+export declare function computeFaminePressures(state: FamineState, policy?: RationingPolicy): FaminePressures;
+/**
+ * Advance famine state by `elapsedDays`.
+ *
+ * - Reclassifies `phase` from the current `foodSupply_Q`.
+ * - Resets `daysInPhase` to 0 on phase change; otherwise increments.
+ * - Accrues or decays `cumulativeSeverity_Q` at `SEVERITY_DELTA_PER_DAY`.
+ *
+ * Returns `true` if the famine phase changed this step.
+ */
+export declare function stepFamine(state: FamineState, foodSupply_Q: Q, elapsedDays: number): boolean;
+/**
+ * Compute food demand in supply units after applying the rationing reduction.
+ *
+ * Normal demand = `polity.population × elapsedDays` su.
+ * `RATIONING_REDUCTION_Q[policy]` fraction is subtracted before multiplication.
+ */
+export declare function computeRationedConsumption(polity: Polity, policy: RationingPolicy, elapsedDays: number): number;
+/**
+ * Drain rationed consumption from a granary.
+ *
+ * Use in place of Phase-87 `stepGranaryConsumption` when a rationing policy is
+ * active.  Grain is clamped to 0; returns the actual supply units consumed.
+ */
+export declare function stepRationedGranary(polity: Polity, granary: GranaryState, policy: RationingPolicy, elapsedDays: number): number;
+/**
+ * Spend treasury to import emergency food.
+ *
+ * Converts up to `budget_cu` of `polity.treasury_cu` into grain at
+ * `RELIEF_IMPORT_COST_CU_PER_SU` cu/su, limited by remaining granary space.
+ *
+ * Mutates `polity.treasury_cu` and `granary.grain_su`.
+ * Returns the actual supply units added.
+ *
+ * @param budget_cu       Max treasury to spend (e.g. pass `polity.treasury_cu` for all-in).
+ * @param capacityCap_su  Max granary capacity; derive via Phase-87 `computeCapacity(polity)`.
+ */
+export declare function computeReliefImport(polity: Polity, granary: GranaryState, budget_cu: number, capacityCap_su: number): number;
+/** Return `true` when the polity is in any active famine phase. */
+export declare function isFamineActive(state: FamineState): boolean;
+/** Return `true` when the polity has reached the most severe famine phase. */
+export declare function isCatastrophicFamine(state: FamineState): boolean;

package/dist/src/famine.js

@@ -0,0 +1,201 @@
+// src/famine.ts — Phase 97: Famine Relief & Rationing
+//
+// Graduated famine severity tracking, rationing policies, and emergency food
+// relief for polities.  Sits above Phase-87 (Granary) as the active response layer.
+//
+// Design:
+//   - Pure data layer — no Entity fields, no kernel changes.
+//   - `FamineState` tracks famine phase, days in phase, and cumulative severity.
+//     Store one per polity externally; pass to step functions each tick.
+//   - `computeFaminePressures` returns an advisory bundle; callers pass fields into
+//     Phase-86 (deathBonus), Phase-81 (migrationPush), and Phase-90 (unrest).
+//   - `stepRationedGranary` replaces Phase-87 `stepGranaryConsumption` when a
+//     rationing policy is active.
+//   - `computeReliefImport` converts `treasury_cu` to grain — treasury and granary
+//     are mutated in-place; caller supplies granary capacity.
+//
+// Integration:
+//   Phase 86 (Demography):  deathBonus_Q supplements Phase-86 FAMINE_DEATH_ANNUAL_Q.
+//   Phase 87 (Granary):     computeFoodSupply_Q → foodSupply_Q; stepRationedGranary.
+//   Phase 81 (Migration):   migrationPush_Q passed to computePushPressure.
+//   Phase 90 (Unrest):      unrestPressure_Q passed to computeUnrestLevel.
+//   Phase 96 (Climate):     harvestYieldPenalty worsens foodSupply_Q that drives here.
+import { q, SCALE, clampQ } from "./units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** `foodSupply_Q` below this → shortage phase. */
+export const SHORTAGE_THRESHOLD_Q = q(0.50);
+/** `foodSupply_Q` below this → famine phase. */
+export const FAMINE_THRESHOLD_Q = q(0.20);
+/** `foodSupply_Q` below this → catastrophe phase. */
+export const CATASTROPHE_THRESHOLD_Q = q(0.05);
+/**
+ * Additional annual death rate by famine phase [Q].
+ * Phase-86 already applies `FAMINE_DEATH_ANNUAL_Q = q(0.030)` at famine threshold;
+ * these bonuses are additive on top for graduated severity.
+ */
+export const FAMINE_PHASE_DEATH_Q = {
+    none: 0,
+    shortage: q(0.010), // +1%/year
+    famine: q(0.030), // +3%/year (stacks with Ph-86 +3%)
+    catastrophe: q(0.070), // +7%/year
+};
+/** Migration push pressure by famine phase [0, SCALE.Q]. */
+export const FAMINE_PHASE_MIGRATION_Q = {
+    none: 0,
+    shortage: q(0.08),
+    famine: q(0.25),
+    catastrophe: q(0.50),
+};
+/** Base unrest pressure by famine phase [0, SCALE.Q]. */
+export const FAMINE_PHASE_UNREST_Q = {
+    none: 0,
+    shortage: q(0.05),
+    famine: q(0.15),
+    catastrophe: q(0.30),
+};
+/**
+ * Consumption reduction fraction per rationing policy [0, SCALE.Q].
+ * Applied to `polity.population × elapsedDays` to give actual su demand.
+ */
+export const RATIONING_REDUCTION_Q = {
+    none: 0,
+    tight: q(0.20),
+    emergency: q(0.40),
+    starvation_rations: q(0.60),
+};
+/** Unrest pressure added by rationing policy itself [0, SCALE.Q]. */
+export const RATIONING_UNREST_Q = {
+    none: 0,
+    tight: q(0.04),
+    emergency: q(0.12),
+    starvation_rations: q(0.25),
+};
+/** Treasury cost in cu per supply unit of emergency food import (1 su = 1 person-day). */
+export const RELIEF_IMPORT_COST_CU_PER_SU = 2;
+/**
+ * Cumulative severity change per day by famine phase [out of SCALE.Q].
+ * Negative values → decay; positive values → accrual.
+ */
+export const SEVERITY_DELTA_PER_DAY = {
+    none: -5,
+    shortage: 2,
+    famine: 10,
+    catastrophe: 25,
+};
+// ── Factory ───────────────────────────────────────────────────────────────────
+/** Create a fresh `FamineState` for a polity (no active famine, zero severity). */
+export function createFamineState(polityId) {
+    return {
+        polityId,
+        phase: "none",
+        daysInPhase: 0,
+        cumulativeSeverity_Q: 0,
+    };
+}
+// ── Phase classification ───────────────────────────────────────────────────────
+/**
+ * Classify the current famine phase from the granary food supply fraction.
+ *
+ * Obtain `foodSupply_Q` from Phase-87 `computeFoodSupply_Q(polity, granary)`.
+ */
+export function computeFaminePhase(foodSupply_Q) {
+    if (foodSupply_Q < CATASTROPHE_THRESHOLD_Q)
+        return "catastrophe";
+    if (foodSupply_Q < FAMINE_THRESHOLD_Q)
+        return "famine";
+    if (foodSupply_Q < SHORTAGE_THRESHOLD_Q)
+        return "shortage";
+    return "none";
+}
+// ── Pressure computation ──────────────────────────────────────────────────────
+/**
+ * Compute the advisory pressure bundle for the current famine state and rationing policy.
+ *
+ * `unrestPressure_Q` sums famine unrest with rationing unrest, clamped to SCALE.Q.
+ */
+export function computeFaminePressures(state, policy = "none") {
+    const phase = state.phase;
+    const unrest = clampQ(FAMINE_PHASE_UNREST_Q[phase] + RATIONING_UNREST_Q[policy], 0, SCALE.Q);
+    return {
+        deathBonus_Q: FAMINE_PHASE_DEATH_Q[phase],
+        migrationPush_Q: FAMINE_PHASE_MIGRATION_Q[phase],
+        unrestPressure_Q: unrest,
+    };
+}
+// ── State step ────────────────────────────────────────────────────────────────
+/**
+ * Advance famine state by `elapsedDays`.
+ *
+ * - Reclassifies `phase` from the current `foodSupply_Q`.
+ * - Resets `daysInPhase` to 0 on phase change; otherwise increments.
+ * - Accrues or decays `cumulativeSeverity_Q` at `SEVERITY_DELTA_PER_DAY`.
+ *
+ * Returns `true` if the famine phase changed this step.
+ */
+export function stepFamine(state, foodSupply_Q, elapsedDays) {
+    const newPhase = computeFaminePhase(foodSupply_Q);
+    const phaseChanged = newPhase !== state.phase;
+    if (phaseChanged) {
+        state.phase = newPhase;
+        state.daysInPhase = 0;
+    }
+    state.daysInPhase += elapsedDays;
+    const delta = SEVERITY_DELTA_PER_DAY[state.phase] * elapsedDays;
+    state.cumulativeSeverity_Q = clampQ(state.cumulativeSeverity_Q + delta, 0, SCALE.Q);
+    return phaseChanged;
+}
+// ── Rationing ─────────────────────────────────────────────────────────────────
+/**
+ * Compute food demand in supply units after applying the rationing reduction.
+ *
+ * Normal demand = `polity.population × elapsedDays` su.
+ * `RATIONING_REDUCTION_Q[policy]` fraction is subtracted before multiplication.
+ */
+export function computeRationedConsumption(polity, policy, elapsedDays) {
+    const reduction = RATIONING_REDUCTION_Q[policy];
+    const factor = SCALE.Q - reduction;
+    const dailyDemand = Math.round(polity.population * factor / SCALE.Q);
+    return dailyDemand * elapsedDays;
+}
+/**
+ * Drain rationed consumption from a granary.
+ *
+ * Use in place of Phase-87 `stepGranaryConsumption` when a rationing policy is
+ * active.  Grain is clamped to 0; returns the actual supply units consumed.
+ */
+export function stepRationedGranary(polity, granary, policy, elapsedDays) {
+    const demand = computeRationedConsumption(polity, policy, elapsedDays);
+    const consumed = Math.min(demand, granary.grain_su);
+    granary.grain_su = Math.max(0, granary.grain_su - demand);
+    return consumed;
+}
+// ── Relief imports ─────────────────────────────────────────────────────────────
+/**
+ * Spend treasury to import emergency food.
+ *
+ * Converts up to `budget_cu` of `polity.treasury_cu` into grain at
+ * `RELIEF_IMPORT_COST_CU_PER_SU` cu/su, limited by remaining granary space.
+ *
+ * Mutates `polity.treasury_cu` and `granary.grain_su`.
+ * Returns the actual supply units added.
+ *
+ * @param budget_cu       Max treasury to spend (e.g. pass `polity.treasury_cu` for all-in).
+ * @param capacityCap_su  Max granary capacity; derive via Phase-87 `computeCapacity(polity)`.
+ */
+export function computeReliefImport(polity, granary, budget_cu, capacityCap_su) {
+    const affordable = Math.floor(Math.min(budget_cu, polity.treasury_cu) / RELIEF_IMPORT_COST_CU_PER_SU);
+    const space = Math.max(0, capacityCap_su - granary.grain_su);
+    const added = Math.min(affordable, space);
+    granary.grain_su += added;
+    polity.treasury_cu -= added * RELIEF_IMPORT_COST_CU_PER_SU;
+    return added;
+}
+// ── Helpers ───────────────────────────────────────────────────────────────────
+/** Return `true` when the polity is in any active famine phase. */
+export function isFamineActive(state) {
+    return state.phase !== "none";
+}
+/** Return `true` when the polity has reached the most severe famine phase. */
+export function isCatastrophicFamine(state) {
+    return state.phase === "catastrophe";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@its-not-rocket-science/ananke",
-  "version": "0.1.41",
+  "version": "0.1.42",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",
@@ -150,6 +150,10 @@
     "./climate": {
       "import": "./dist/src/climate.js",
       "types": "./dist/src/climate.d.ts"
+    },
+    "./famine": {
+      "import": "./dist/src/famine.js",
+      "types": "./dist/src/famine.d.ts"
     }
   },
   "files": [