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

package/CHANGELOG.md

@@ -6,6 +6,53 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.41] — 2026-03-26
+
+### Added
+
+- **Phase 96 · Climate Events & Natural Disasters** (`src/climate.ts`)
+  - `ClimateEventType`: `"drought" | "flood" | "harsh_winter" | "earthquake" | "plague_season" | "locust_swarm"`.
+  - `ClimateEvent { eventId, type, severity_Q, durationDays }` — immutable descriptor.
+  - `ActiveClimateEvent { event, remainingDays, elapsedDays }` — mutable progress tracker stored externally by host.
+  - `ClimateEffects { deathPressure_Q, harvestYieldPenalty_Q, epidemicGrowthBonus_Q, infrastructureDamage_Q, unrestPressure_Q, marchPenalty_Q }` — advisory bundle passed to Phases 86–93.
+  - `BASE_EFFECTS: Record<ClimateEventType, ClimateEffects>` — full-severity baselines: locust_swarm has highest harvest penalty (q(0.80)), plague_season highest epidemic growth (q(0.40)), earthquake highest infrastructure damage (q(0.20)), harsh_winter highest march penalty (q(0.40)).
+  - `EVENT_DAILY_PROBABILITY_Q: Record<ClimateEventType, number>` — direct daily integer probabilities out of SCALE.Q=10000: harsh_winter 50, flood 40, drought 30, plague_season 20, locust_swarm 10, earthquake 5.
+  - `EVENT_DURATION_RANGE: Record<ClimateEventType, [number, number]>` — duration ranges in days: drought 60–180, plague_season 30–120, harsh_winter 30–90, flood 7–30, locust_swarm 7–21, earthquake 1–3.
+  - `createClimateEvent(eventId, type, severity_Q, durationDays)` — factory; clamps severity and enforces minimum duration of 1.
+  - `activateClimateEvent(event)` → `ActiveClimateEvent` with `remainingDays = durationDays`, `elapsedDays = 0`.
+  - `computeClimateEffects(active)` → `ClimateEffects`; each field = `round(base × severity / SCALE.Q)`; returns zero bundle when expired.
+  - `stepClimateEvent(active, elapsedDays)` — decrements `remainingDays` (floor 0), increments `elapsedDays`; returns `true` when event expires.
+  - `isClimateEventExpired(active)` → `remainingDays <= 0`.
+  - `generateClimateEvent(polityHash, worldSeed, tick)` → `ClimateEvent | undefined` — deterministic random generation via `eventSeed`; rolls each type independently; severity ∈ [q(0.20), q(0.90)]; duration interpolated within type range.
+  - `aggregateClimateEffects(actives)` → combined `ClimateEffects` — sums per-field across all active events and clamps to SCALE.Q; expired events contribute zero.
+  - Added `./climate` subpath export to `package.json`.
+  - 41 new tests; 5,022 total. Coverage: 100% statements/branches/functions/lines on `climate.ts`.
+
+---
+
+## [0.1.40] — 2026-03-26
+
+### Added
+
+- **Phase 95 · Natural Resources & Extraction** (`src/resources.ts`)
+  - `ResourceType`: `"iron" | "silver" | "timber" | "stone" | "horses"`.
+  - `ResourceDeposit { depositId, polityId, type, richness_Q, maxWorkers }` — immutable site descriptor.
+  - `ExtractionState { depositId, assignedWorkers, cumulativeYield_cu }` — mutable accumulator stored externally.
+  - `BASE_YIELD_PER_WORKER: Record<ResourceType, number>` — silver 8, horses 5, iron 3, timber/stone 2 cu/worker/day at base.
+  - `TECH_EXTRACTION_MUL: Record<number, Q>` — numeric TechEra keys; Prehistoric q(0.40) → DeepSpace q(4.00).
+  - `computeDailyYield(deposit, state, techEra)` → cu/day: `workers × baseRate × techMul × richnessMul`; `richnessMul ∈ [q(0.50), q(1.00)]`; 0 when exhausted or no workers.
+  - `assignWorkers(deposit, state, workers)` — clamps to `[0, deposit.maxWorkers]`.
+  - `depleteDeposit(deposit, yield_cu)` — reduces `richness_Q` by `DEPLETION_RATE_PER_1000_CU = q(0.005)` per 1000 cu extracted.
+  - `stepExtraction(deposit, state, polity, elapsedDays)` → `ExtractionStepResult`: adds yield to `polity.treasury_cu`; depletes richness; returns `{ yield_cu, richness_Q, exhausted }`.
+  - `computeTotalDailyResourceIncome(deposits, states, techEra)` → cu/day total across all deposits.
+  - Secondary bonus sets: `MILITARY_BONUS_RESOURCES` (iron, horses), `CONSTRUCTION_BONUS_RESOURCES` (timber, stone), `MOBILITY_BONUS_RESOURCES` (horses) — advisory flags for Phase-61/89/93.
+  - `hasMilitaryBonus / hasConstructionBonus / hasMobilityBonus` helpers.
+  - `estimateDaysToExhaustion(deposit, state, techEra)` → ceiling days; Infinity with no workers; 0 when already exhausted.
+  - Added `./resources` subpath export to `package.json`.
+  - 49 new tests; 4,981 total. Coverage maintained above all thresholds.
+
+---
+
 ## [0.1.39] — 2026-03-26
 
 ### Added

package/dist/src/climate.d.ts

@@ -0,0 +1,108 @@
+import type { Q } from "./units.js";
+/** Classification of climate event. */
+export type ClimateEventType = "drought" | "flood" | "harsh_winter" | "earthquake" | "plague_season" | "locust_swarm";
+/** Immutable descriptor for a climate event. */
+export interface ClimateEvent {
+    eventId: string;
+    type: ClimateEventType;
+    /**
+     * Severity [0, SCALE.Q].  Scales all effect magnitudes.
+     * q(0.30) = minor; q(0.60) = severe; q(0.90) = catastrophic.
+     */
+    severity_Q: Q;
+    /**
+     * Total duration in simulated days.
+     * Remaining days tracked in `ActiveClimateEvent.remainingDays`.
+     */
+    durationDays: number;
+}
+/** Mutable tracking state for an ongoing climate event. */
+export interface ActiveClimateEvent {
+    event: ClimateEvent;
+    remainingDays: number;
+    /** Total days this event has been active on this polity. */
+    elapsedDays: number;
+}
+/**
+ * Advisory effect bundle derived from a climate event.
+ * Pass individual fields into the relevant downstream phase calls.
+ * All fields are [0, SCALE.Q] unless noted.
+ */
+export interface ClimateEffects {
+    /** Extra famine death pressure for Phase-86 `deathPressure_Q`. */
+    deathPressure_Q: Q;
+    /** Harvest yield penalty for Phase-87 `deriveHarvestYieldFactor`. */
+    harvestYieldPenalty_Q: Q;
+    /** Epidemic growth bonus for Phase-88 `stepEpidemic` health capacity. */
+    epidemicGrowthBonus_Q: Q;
+    /**
+     * Infrastructure damage fraction per day for Phase-89.
+     * Hosts subtract `investedCost × damage / SCALE.Q` from project progress.
+     */
+    infrastructureDamage_Q: Q;
+    /** Extra unrest pressure for Phase-90 `computeUnrestLevel`. */
+    unrestPressure_Q: Q;
+    /** March rate penalty for Phase-93 `stepCampaignMarch` road bonus reduction. */
+    marchPenalty_Q: Q;
+}
+/**
+ * Base effect magnitudes at full severity (q(1.0)) for each event type.
+ * Actual effects = base × severity_Q / SCALE.Q.
+ */
+export declare const BASE_EFFECTS: Record<ClimateEventType, ClimateEffects>;
+/**
+ * Typical duration ranges in days [min, max] for each event type.
+ * Used by `generateClimateEvent` to set `durationDays`.
+ */
+export declare const EVENT_DURATION_RANGE: Record<ClimateEventType, [number, number]>;
+/**
+ * Daily probability of each event type triggering [Q].
+ * Roll = `eventSeed(...) % SCALE.Q`; triggers when roll < dailyProb.
+ *
+ * These correspond to rough annual frequencies:
+ *   harsh_winter: q(0.005) ≈ 0.5%/day ≈ ~50% chance within a year
+ *   flood:        q(0.004) ≈ 0.4%/day ≈ ~40% within a year
+ *   drought:      q(0.003) ≈ 0.3%/day
+ *   plague_season:q(0.002) ≈ 0.2%/day
+ *   locust_swarm: q(0.001) ≈ 0.1%/day
+ *   earthquake:   q(0.0005)≈ 0.05%/day (rare)
+ */
+export declare const EVENT_DAILY_PROBABILITY_Q: Record<ClimateEventType, number>;
+/** Create a `ClimateEvent` with explicit parameters. */
+export declare function createClimateEvent(eventId: string, type: ClimateEventType, severity_Q: Q, durationDays: number): ClimateEvent;
+/** Start tracking an active climate event. */
+export declare function activateClimateEvent(event: ClimateEvent): ActiveClimateEvent;
+/**
+ * Compute the `ClimateEffects` bundle for a given event at its current severity.
+ *
+ * Each field = `round(BASE_EFFECTS[type][field] × severity_Q / SCALE.Q)`.
+ * Returns a zero bundle if `active.remainingDays <= 0`.
+ */
+export declare function computeClimateEffects(active: ActiveClimateEvent): ClimateEffects;
+/**
+ * Advance an active climate event by `elapsedDays`.
+ * Decrements `remainingDays` (floor at 0) and increments `elapsedDays`.
+ * Returns `true` if the event has expired this step.
+ */
+export declare function stepClimateEvent(active: ActiveClimateEvent, elapsedDays: number): boolean;
+/** Return true if the event has run its full duration. */
+export declare function isClimateEventExpired(active: ActiveClimateEvent): boolean;
+/**
+ * Attempt to generate a random climate event for a polity on the given tick.
+ *
+ * Each event type is rolled independently.  Returns the first event whose
+ * annual probability roll succeeds, or `undefined` if none trigger.
+ *
+ * Roll: `eventSeed(worldSeed, tick, polityHash, 0, typeSalt) % SCALE.Q`
+ * vs daily probability = `round(annualProb / 365)`.
+ *
+ * @param polityHash  `hashString(polity.id)` from Phase-61.
+ * @param worldSeed   World-level seed.
+ * @param tick        Current simulation tick (day).
+ */
+export declare function generateClimateEvent(polityHash: number, worldSeed: number, tick: number): ClimateEvent | undefined;
+/**
+ * Combine effects from multiple simultaneous active events (e.g. drought + locust).
+ * Each field is summed and clamped to SCALE.Q.
+ */
+export declare function aggregateClimateEffects(actives: ActiveClimateEvent[]): ClimateEffects;

package/dist/src/climate.js

@@ -0,0 +1,240 @@
+// src/climate.ts — Phase 96: Climate Events & Natural Disasters
+//
+// Multi-day climate events affect polity populations, granaries, infrastructure,
+// epidemic spread, and military campaigns.  This is distinct from Phase-51
+// (tactical weather): Phase 96 operates at the polity/campaign timescale —
+// weeks to seasons — rather than the second-to-second combat tick.
+//
+// Design:
+//   - Pure data layer — no Entity fields, no kernel changes.
+//   - `ClimateEvent` is an immutable descriptor; `ActiveClimateEvent` tracks progress.
+//   - `computeClimateEffects` returns an advisory `ClimateEffects` bundle;
+//     callers pass individual fields to Phase-86/87/88/89/90/93 as needed.
+//   - `generateClimateEvent` uses `eventSeed` for deterministic random occurrence.
+//   - Severity and duration determine effect magnitude; effects scale linearly with
+//     severity via mulDiv.
+//
+// Integration:
+//   Phase 86 (Demography):  deathPressure_Q elevated by drought/harsh_winter.
+//   Phase 87 (Granary):     harvestYieldPenalty_Q reduces harvest output.
+//   Phase 88 (Epidemic):    epidemicGrowthBonus_Q accelerates disease spread.
+//   Phase 89 (Infra):       infrastructureDamage_Q models flood/earthquake damage.
+//   Phase 90 (Unrest):      unrestPressure_Q adds to computeUnrestLevel factors.
+//   Phase 93 (Campaign):    marchPenalty_Q reduces daily march progress.
+import { eventSeed } from "./sim/seeds.js";
+import { q, SCALE, clampQ } from "./units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/**
+ * Base effect magnitudes at full severity (q(1.0)) for each event type.
+ * Actual effects = base × severity_Q / SCALE.Q.
+ */
+export const BASE_EFFECTS = {
+    drought: {
+        deathPressure_Q: q(0.10),
+        harvestYieldPenalty_Q: q(0.60), // major crop loss
+        epidemicGrowthBonus_Q: q(0.10),
+        infrastructureDamage_Q: 0,
+        unrestPressure_Q: q(0.15),
+        marchPenalty_Q: 0,
+    },
+    flood: {
+        deathPressure_Q: q(0.08),
+        harvestYieldPenalty_Q: q(0.40),
+        epidemicGrowthBonus_Q: q(0.20), // waterborne disease
+        infrastructureDamage_Q: q(0.05), // per day
+        unrestPressure_Q: q(0.10),
+        marchPenalty_Q: q(0.30), // mud impedes armies
+    },
+    harsh_winter: {
+        deathPressure_Q: q(0.08),
+        harvestYieldPenalty_Q: q(0.20),
+        epidemicGrowthBonus_Q: q(0.15), // respiratory illness
+        infrastructureDamage_Q: q(0.01),
+        unrestPressure_Q: q(0.08),
+        marchPenalty_Q: q(0.40), // historical winter campaign penalty
+    },
+    earthquake: {
+        deathPressure_Q: q(0.15), // immediate casualties
+        harvestYieldPenalty_Q: q(0.10),
+        epidemicGrowthBonus_Q: q(0.10),
+        infrastructureDamage_Q: q(0.20), // heavy structural damage
+        unrestPressure_Q: q(0.20),
+        marchPenalty_Q: q(0.10),
+    },
+    plague_season: {
+        deathPressure_Q: q(0.20), // epidemic peak
+        harvestYieldPenalty_Q: q(0.15), // insufficient labour
+        epidemicGrowthBonus_Q: q(0.40), // primary driver
+        infrastructureDamage_Q: 0,
+        unrestPressure_Q: q(0.18),
+        marchPenalty_Q: q(0.15), // sick soldiers
+    },
+    locust_swarm: {
+        deathPressure_Q: q(0.05),
+        harvestYieldPenalty_Q: q(0.80), // near-total crop destruction
+        epidemicGrowthBonus_Q: 0,
+        infrastructureDamage_Q: 0,
+        unrestPressure_Q: q(0.20),
+        marchPenalty_Q: 0,
+    },
+};
+/**
+ * Typical duration ranges in days [min, max] for each event type.
+ * Used by `generateClimateEvent` to set `durationDays`.
+ */
+export const EVENT_DURATION_RANGE = {
+    drought: [60, 180],
+    flood: [7, 30],
+    harsh_winter: [30, 90],
+    earthquake: [1, 3],
+    plague_season: [30, 120],
+    locust_swarm: [7, 21],
+};
+/**
+ * Daily probability of each event type triggering [Q].
+ * Roll = `eventSeed(...) % SCALE.Q`; triggers when roll < dailyProb.
+ *
+ * These correspond to rough annual frequencies:
+ *   harsh_winter: q(0.005) ≈ 0.5%/day ≈ ~50% chance within a year
+ *   flood:        q(0.004) ≈ 0.4%/day ≈ ~40% within a year
+ *   drought:      q(0.003) ≈ 0.3%/day
+ *   plague_season:q(0.002) ≈ 0.2%/day
+ *   locust_swarm: q(0.001) ≈ 0.1%/day
+ *   earthquake:   q(0.0005)≈ 0.05%/day (rare)
+ */
+export const EVENT_DAILY_PROBABILITY_Q = {
+    harsh_winter: 50, // 50/10000 = 0.5% per day
+    flood: 40,
+    drought: 30,
+    plague_season: 20,
+    locust_swarm: 10,
+    earthquake: 5,
+};
+// ── Factory ───────────────────────────────────────────────────────────────────
+/** Create a `ClimateEvent` with explicit parameters. */
+export function createClimateEvent(eventId, type, severity_Q, durationDays) {
+    return {
+        eventId,
+        type,
+        severity_Q: clampQ(severity_Q, 0, SCALE.Q),
+        durationDays: Math.max(1, durationDays),
+    };
+}
+/** Start tracking an active climate event. */
+export function activateClimateEvent(event) {
+    return { event, remainingDays: event.durationDays, elapsedDays: 0 };
+}
+// ── Effect computation ────────────────────────────────────────────────────────
+/**
+ * Compute the `ClimateEffects` bundle for a given event at its current severity.
+ *
+ * Each field = `round(BASE_EFFECTS[type][field] × severity_Q / SCALE.Q)`.
+ * Returns a zero bundle if `active.remainingDays <= 0`.
+ */
+export function computeClimateEffects(active) {
+    if (active.remainingDays <= 0) {
+        return zeroEffects();
+    }
+    const base = BASE_EFFECTS[active.event.type];
+    const sev = active.event.severity_Q;
+    return {
+        deathPressure_Q: scale(base.deathPressure_Q, sev),
+        harvestYieldPenalty_Q: scale(base.harvestYieldPenalty_Q, sev),
+        epidemicGrowthBonus_Q: scale(base.epidemicGrowthBonus_Q, sev),
+        infrastructureDamage_Q: scale(base.infrastructureDamage_Q, sev),
+        unrestPressure_Q: scale(base.unrestPressure_Q, sev),
+        marchPenalty_Q: scale(base.marchPenalty_Q, sev),
+    };
+}
+function scale(base, severity_Q) {
+    return clampQ(Math.round(base * severity_Q / SCALE.Q), 0, SCALE.Q);
+}
+function zeroEffects() {
+    return {
+        deathPressure_Q: 0,
+        harvestYieldPenalty_Q: 0,
+        epidemicGrowthBonus_Q: 0,
+        infrastructureDamage_Q: 0,
+        unrestPressure_Q: 0,
+        marchPenalty_Q: 0,
+    };
+}
+// ── Event step ────────────────────────────────────────────────────────────────
+/**
+ * Advance an active climate event by `elapsedDays`.
+ * Decrements `remainingDays` (floor at 0) and increments `elapsedDays`.
+ * Returns `true` if the event has expired this step.
+ */
+export function stepClimateEvent(active, elapsedDays) {
+    active.elapsedDays += elapsedDays;
+    active.remainingDays = Math.max(0, active.remainingDays - elapsedDays);
+    return active.remainingDays === 0;
+}
+/** Return true if the event has run its full duration. */
+export function isClimateEventExpired(active) {
+    return active.remainingDays <= 0;
+}
+// ── Random event generation ───────────────────────────────────────────────────
+/**
+ * Attempt to generate a random climate event for a polity on the given tick.
+ *
+ * Each event type is rolled independently.  Returns the first event whose
+ * annual probability roll succeeds, or `undefined` if none trigger.
+ *
+ * Roll: `eventSeed(worldSeed, tick, polityHash, 0, typeSalt) % SCALE.Q`
+ * vs daily probability = `round(annualProb / 365)`.
+ *
+ * @param polityHash  `hashString(polity.id)` from Phase-61.
+ * @param worldSeed   World-level seed.
+ * @param tick        Current simulation tick (day).
+ */
+export function generateClimateEvent(polityHash, worldSeed, tick) {
+    const types = [
+        "harsh_winter", "flood", "drought", "plague_season", "locust_swarm", "earthquake",
+    ];
+    for (let i = 0; i < types.length; i++) {
+        const type = types[i];
+        const dailyProb = EVENT_DAILY_PROBABILITY_Q[type];
+        const seed = eventSeed(worldSeed, tick, polityHash, 0, i + 1);
+        const roll = seed % SCALE.Q;
+        if (roll < dailyProb) {
+            // Determine severity: another seed roll, maps to q(0.20)–q(0.90)
+            const sevSeed = eventSeed(worldSeed, tick, polityHash, i + 1, 42);
+            const sevRoll = sevSeed % SCALE.Q;
+            const severity_Q = clampQ(q(0.20) + Math.round(sevRoll * q(0.70) / SCALE.Q), 0, SCALE.Q);
+            // Duration: interpolate within the type's range
+            const [minDays, maxDays] = EVENT_DURATION_RANGE[type];
+            const durSeed = eventSeed(worldSeed, tick, polityHash, i + 2, 7);
+            const durRange = maxDays - minDays;
+            const durationDays = minDays + (durSeed % (durRange + 1));
+            const eventId = `${type}_${tick}_${polityHash % 10000}`;
+            return createClimateEvent(eventId, type, severity_Q, durationDays);
+        }
+    }
+    return undefined;
+}
+// ── Aggregate helpers ─────────────────────────────────────────────────────────
+/**
+ * Combine effects from multiple simultaneous active events (e.g. drought + locust).
+ * Each field is summed and clamped to SCALE.Q.
+ */
+export function aggregateClimateEffects(actives) {
+    let death = 0, harvest = 0, epidemic = 0, infra = 0, unrest = 0, march = 0;
+    for (const active of actives) {
+        const fx = computeClimateEffects(active);
+        death += fx.deathPressure_Q;
+        harvest += fx.harvestYieldPenalty_Q;
+        epidemic += fx.epidemicGrowthBonus_Q;
+        infra += fx.infrastructureDamage_Q;
+        unrest += fx.unrestPressure_Q;
+        march += fx.marchPenalty_Q;
+    }
+    return {
+        deathPressure_Q: clampQ(death, 0, SCALE.Q),
+        harvestYieldPenalty_Q: clampQ(harvest, 0, SCALE.Q),
+        epidemicGrowthBonus_Q: clampQ(epidemic, 0, SCALE.Q),
+        infrastructureDamage_Q: clampQ(infra, 0, SCALE.Q),
+        unrestPressure_Q: clampQ(unrest, 0, SCALE.Q),
+        marchPenalty_Q: clampQ(march, 0, SCALE.Q),
+    };
+}

package/dist/src/resources.d.ts

@@ -0,0 +1,149 @@
+import type { Q } from "./units.js";
+import type { Polity } from "./polity.js";
+/** Classification of natural resource. */
+export type ResourceType = "iron" | "silver" | "timber" | "stone" | "horses";
+/** Immutable descriptor for a natural resource deposit. */
+export interface ResourceDeposit {
+    depositId: string;
+    polityId: string;
+    type: ResourceType;
+    /**
+     * Initial richness [0, SCALE.Q].  Declines with extraction via `depleteDeposit`.
+     * A richness of SCALE.Q represents an exceptionally rich find.
+     */
+    richness_Q: Q;
+    /**
+     * Maximum workers that can be productively assigned to this deposit.
+     * Additional workers beyond this are wasted.
+     */
+    maxWorkers: number;
+}
+/** Mutable extraction state — store one externally per deposit per polity. */
+export interface ExtractionState {
+    depositId: string;
+    /** Current worker count (may not exceed `deposit.maxWorkers`). */
+    assignedWorkers: number;
+    /** Cumulative cost-units yielded since deposit was first worked. */
+    cumulativeYield_cu: number;
+}
+/** Output of `stepExtraction`. */
+export interface ExtractionStepResult {
+    /** Cost-units added to polity treasury this step. */
+    yield_cu: number;
+    /** Current richness after any depletion [0, SCALE.Q]. */
+    richness_Q: Q;
+    /**
+     * Whether the deposit is now exhausted (`richness_Q <= DEPLETION_EXHAUSTED_Q`).
+     */
+    exhausted: boolean;
+}
+/**
+ * Base daily yield per worker [cost-units/worker/day] at full richness and
+ * base tech era (Ancient = 1, the reference point).
+ */
+export declare const BASE_YIELD_PER_WORKER: Record<ResourceType, number>;
+/**
+ * Tech era extraction efficiency multiplier [Q].
+ * Better tools, techniques, and logistics improve yield per worker.
+ */
+export declare const TECH_EXTRACTION_MUL: Record<number, Q>;
+/**
+ * Fraction of base yield that richness scales against [Q].
+ * At richness q(0.50), yield = base × (0.50 + 0.50×0.50) = base × 0.75
+ * — partial depletion still produces meaningful income.
+ */
+export declare const RICHNESS_FLOOR_Q: Q;
+/**
+ * Richness reduction per 1000 cost-units of cumulative yield.
+ * Controls the depletion rate.  Lower values mean longer-lived deposits.
+ */
+export declare const DEPLETION_RATE_PER_1000_CU: Q;
+/**
+ * Richness threshold below which the deposit is considered exhausted [Q].
+ * Extraction becomes uneconomical below this level.
+ */
+export declare const DEPLETION_EXHAUSTED_Q: Q;
+/**
+ * Maximum fraction of polity population that can be assigned as resource
+ * workers without impacting farming/tax base [Q].
+ * Hosts should warn if this is exceeded.
+ */
+export declare const WORKER_POP_FRACTION_Q: Q;
+/**
+ * Resource types that provide a military equipment bonus when worked.
+ * Hosts apply this to Phase-61 `deriveMilitaryStrength` or Phase-93 strength.
+ */
+export declare const MILITARY_BONUS_RESOURCES: ReadonlySet<ResourceType>;
+/**
+ * Resource types that provide a construction cost discount when worked.
+ * Hosts apply this to Phase-89 `investInProject` cost calculations.
+ */
+export declare const CONSTRUCTION_BONUS_RESOURCES: ReadonlySet<ResourceType>;
+/**
+ * Resource types that improve march rate when worked.
+ * Hosts add a road-equivalent bonus to Phase-93 `stepCampaignMarch`.
+ */
+export declare const MOBILITY_BONUS_RESOURCES: ReadonlySet<ResourceType>;
+/** Create a new `ResourceDeposit`. */
+export declare function createDeposit(depositId: string, polityId: string, type: ResourceType, richness_Q?: Q, maxWorkers?: number): ResourceDeposit;
+/** Create a fresh `ExtractionState` with no workers assigned. */
+export declare function createExtractionState(depositId: string): ExtractionState;
+/**
+ * Assign workers to a deposit.
+ * Clamps to `[0, deposit.maxWorkers]`.
+ * Returns the effective worker count after clamping.
+ */
+export declare function assignWorkers(deposit: ResourceDeposit, state: ExtractionState, workers: number): number;
+/**
+ * Compute the daily extraction yield [cost-units/day].
+ *
+ * Formula:
+ *   techMul       = TECH_EXTRACTION_MUL[techEra]  (default q(0.60))
+ *   richnessScale = RICHNESS_FLOOR_Q + mulDiv(SCALE.Q - RICHNESS_FLOOR_Q, richness_Q, SCALE.Q)
+ *                 ∈ [q(0.50), q(1.00)]
+ *   base          = workers × BASE_YIELD_PER_WORKER[type]
+ *   daily         = max(0, round(base × techMul / SCALE.Q × richnessScale / SCALE.Q))
+ *
+ * Returns 0 if the deposit is exhausted or no workers assigned.
+ */
+export declare function computeDailyYield(deposit: ResourceDeposit, state: ExtractionState, techEra: number): number;
+/**
+ * Reduce deposit richness based on cumulative yield extracted.
+ *
+ * `richnessDrain = round(yield_cu × DEPLETION_RATE_PER_1000_CU / 1000)`
+ *
+ * Mutates `deposit.richness_Q`.
+ */
+export declare function depleteDeposit(deposit: ResourceDeposit, yieldThisStep_cu: number): void;
+/**
+ * Advance extraction for `elapsedDays` days.
+ *
+ * 1. Computes `computeDailyYield × elapsedDays`.
+ * 2. Adds yield to `polity.treasury_cu` and `state.cumulativeYield_cu`.
+ * 3. Depletes deposit richness proportional to yield.
+ *
+ * Mutates `polity.treasury_cu`, `state.cumulativeYield_cu`, and `deposit.richness_Q`.
+ */
+export declare function stepExtraction(deposit: ResourceDeposit, state: ExtractionState, polity: Polity, elapsedDays: number): ExtractionStepResult;
+/**
+ * Estimate daily bonus income from resource extraction across multiple deposits.
+ * Useful for treasury planning alongside Phase-92 tax revenue.
+ */
+export declare function computeTotalDailyResourceIncome(deposits: ResourceDeposit[], states: Map<string, ExtractionState>, techEra: number): number;
+/**
+ * Return true if this resource type provides a military bonus.
+ */
+export declare function hasMilitaryBonus(type: ResourceType): boolean;
+/**
+ * Return true if this resource type provides a construction bonus.
+ */
+export declare function hasConstructionBonus(type: ResourceType): boolean;
+/**
+ * Return true if this resource type provides a mobility bonus.
+ */
+export declare function hasMobilityBonus(type: ResourceType): boolean;
+/**
+ * Estimate how many days until the deposit is exhausted at the current
+ * extraction rate.  Returns `Infinity` if no workers or already exhausted.
+ */
+export declare function estimateDaysToExhaustion(deposit: ResourceDeposit, state: ExtractionState, techEra: number): number;

package/dist/src/resources.js

@@ -0,0 +1,219 @@
+// src/resources.ts — Phase 95: Natural Resources & Extraction
+//
+// Polity economies are not purely population-driven.  Mines, forests, quarries,
+// and pastures provide resource income that is largely independent of population
+// size.  This module tracks resource deposits, worker assignment, daily yield,
+// and gradual depletion.
+//
+// Design:
+//   - Pure data layer — no Entity fields, no kernel changes.
+//   - `ResourceDeposit` is the immutable site descriptor; `ExtractionState` is
+//     the mutable accumulator stored externally by the host.
+//   - Yield scales with workers, tech era, and deposit richness.
+//   - Richness slowly declines with cumulative extraction (depletion model).
+//   - Resource income is expressed in treasury cost-units for uniform integration
+//     with Phase-92 taxation and Phase-89 infrastructure.
+//   - Secondary bonus flags (`militaryBonus`, `constructionBonus`, `mobilityBonus`)
+//     are advisory — the host applies them to Phase-61/89/93 calls.
+//
+// Integration:
+//   Phase 11 (Tech):    techEra multiplier improves extraction efficiency.
+//   Phase 61 (Polity):  treasury_cu receives daily yield; population caps workers.
+//   Phase 89 (Infra):   timber/stone → construction discount advisory flag.
+//   Phase 93 (Campaign): horses → march-rate advisory flag.
+//   Phase 92 (Taxation): resource income is additive to tax revenue.
+import { q, SCALE, clampQ, mulDiv } from "./units.js";
+import { TechEra } from "./sim/tech.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/**
+ * Base daily yield per worker [cost-units/worker/day] at full richness and
+ * base tech era (Ancient = 1, the reference point).
+ */
+export const BASE_YIELD_PER_WORKER = {
+    iron: 3, // ore smelting; military equipment
+    silver: 8, // coinage; highest raw value
+    timber: 2, // construction material
+    stone: 2, // construction material
+    horses: 5, // breeding; cavalry
+};
+/**
+ * Tech era extraction efficiency multiplier [Q].
+ * Better tools, techniques, and logistics improve yield per worker.
+ */
+export const TECH_EXTRACTION_MUL = {
+    [TechEra.Prehistoric]: q(0.40),
+    [TechEra.Ancient]: q(0.60),
+    [TechEra.Medieval]: q(0.80),
+    [TechEra.EarlyModern]: q(1.00),
+    [TechEra.Industrial]: q(1.50),
+    [TechEra.Modern]: q(2.00),
+    [TechEra.NearFuture]: q(2.50),
+    [TechEra.FarFuture]: q(3.00),
+    [TechEra.DeepSpace]: q(4.00),
+};
+/**
+ * Fraction of base yield that richness scales against [Q].
+ * At richness q(0.50), yield = base × (0.50 + 0.50×0.50) = base × 0.75
+ * — partial depletion still produces meaningful income.
+ */
+export const RICHNESS_FLOOR_Q = q(0.50);
+/**
+ * Richness reduction per 1000 cost-units of cumulative yield.
+ * Controls the depletion rate.  Lower values mean longer-lived deposits.
+ */
+export const DEPLETION_RATE_PER_1000_CU = q(0.005);
+/**
+ * Richness threshold below which the deposit is considered exhausted [Q].
+ * Extraction becomes uneconomical below this level.
+ */
+export const DEPLETION_EXHAUSTED_Q = q(0.05);
+/**
+ * Maximum fraction of polity population that can be assigned as resource
+ * workers without impacting farming/tax base [Q].
+ * Hosts should warn if this is exceeded.
+ */
+export const WORKER_POP_FRACTION_Q = q(0.10);
+// ── Secondary bonus flags ─────────────────────────────────────────────────────
+/**
+ * Resource types that provide a military equipment bonus when worked.
+ * Hosts apply this to Phase-61 `deriveMilitaryStrength` or Phase-93 strength.
+ */
+export const MILITARY_BONUS_RESOURCES = new Set(["iron", "horses"]);
+/**
+ * Resource types that provide a construction cost discount when worked.
+ * Hosts apply this to Phase-89 `investInProject` cost calculations.
+ */
+export const CONSTRUCTION_BONUS_RESOURCES = new Set(["timber", "stone"]);
+/**
+ * Resource types that improve march rate when worked.
+ * Hosts add a road-equivalent bonus to Phase-93 `stepCampaignMarch`.
+ */
+export const MOBILITY_BONUS_RESOURCES = new Set(["horses"]);
+// ── Factory ───────────────────────────────────────────────────────────────────
+/** Create a new `ResourceDeposit`. */
+export function createDeposit(depositId, polityId, type, richness_Q = q(0.80), maxWorkers = 500) {
+    return { depositId, polityId, type, richness_Q: clampQ(richness_Q, 0, SCALE.Q), maxWorkers };
+}
+/** Create a fresh `ExtractionState` with no workers assigned. */
+export function createExtractionState(depositId) {
+    return { depositId, assignedWorkers: 0, cumulativeYield_cu: 0 };
+}
+// ── Worker management ─────────────────────────────────────────────────────────
+/**
+ * Assign workers to a deposit.
+ * Clamps to `[0, deposit.maxWorkers]`.
+ * Returns the effective worker count after clamping.
+ */
+export function assignWorkers(deposit, state, workers) {
+    state.assignedWorkers = Math.max(0, Math.min(workers, deposit.maxWorkers));
+    return state.assignedWorkers;
+}
+// ── Yield computation ─────────────────────────────────────────────────────────
+/**
+ * Compute the daily extraction yield [cost-units/day].
+ *
+ * Formula:
+ *   techMul       = TECH_EXTRACTION_MUL[techEra]  (default q(0.60))
+ *   richnessScale = RICHNESS_FLOOR_Q + mulDiv(SCALE.Q - RICHNESS_FLOOR_Q, richness_Q, SCALE.Q)
+ *                 ∈ [q(0.50), q(1.00)]
+ *   base          = workers × BASE_YIELD_PER_WORKER[type]
+ *   daily         = max(0, round(base × techMul / SCALE.Q × richnessScale / SCALE.Q))
+ *
+ * Returns 0 if the deposit is exhausted or no workers assigned.
+ */
+export function computeDailyYield(deposit, state, techEra) {
+    if (deposit.richness_Q <= DEPLETION_EXHAUSTED_Q)
+        return 0;
+    if (state.assignedWorkers <= 0)
+        return 0;
+    const techMul = (TECH_EXTRACTION_MUL[techEra] ?? q(0.60));
+    const richnessMul = RICHNESS_FLOOR_Q + mulDiv(SCALE.Q - RICHNESS_FLOOR_Q, deposit.richness_Q, SCALE.Q);
+    const basePerWorker = BASE_YIELD_PER_WORKER[deposit.type] ?? 0;
+    const base = state.assignedWorkers * basePerWorker;
+    const withTech = Math.round(base * techMul / SCALE.Q);
+    return Math.max(0, Math.round(withTech * richnessMul / SCALE.Q));
+}
+// ── Depletion ─────────────────────────────────────────────────────────────────
+/**
+ * Reduce deposit richness based on cumulative yield extracted.
+ *
+ * `richnessDrain = round(yield_cu × DEPLETION_RATE_PER_1000_CU / 1000)`
+ *
+ * Mutates `deposit.richness_Q`.
+ */
+export function depleteDeposit(deposit, yieldThisStep_cu) {
+    if (yieldThisStep_cu <= 0)
+        return;
+    const drain = Math.round(yieldThisStep_cu * DEPLETION_RATE_PER_1000_CU / 1000);
+    deposit.richness_Q = clampQ(deposit.richness_Q - drain, 0, SCALE.Q);
+}
+// ── Extraction step ───────────────────────────────────────────────────────────
+/**
+ * Advance extraction for `elapsedDays` days.
+ *
+ * 1. Computes `computeDailyYield × elapsedDays`.
+ * 2. Adds yield to `polity.treasury_cu` and `state.cumulativeYield_cu`.
+ * 3. Depletes deposit richness proportional to yield.
+ *
+ * Mutates `polity.treasury_cu`, `state.cumulativeYield_cu`, and `deposit.richness_Q`.
+ */
+export function stepExtraction(deposit, state, polity, elapsedDays) {
+    const daily = computeDailyYield(deposit, state, polity.techEra);
+    const yield_cu = daily * elapsedDays;
+    polity.treasury_cu += yield_cu;
+    state.cumulativeYield_cu += yield_cu;
+    depleteDeposit(deposit, yield_cu);
+    const exhausted = deposit.richness_Q <= DEPLETION_EXHAUSTED_Q;
+    return { yield_cu, richness_Q: deposit.richness_Q, exhausted };
+}
+// ── Reporting ─────────────────────────────────────────────────────────────────
+/**
+ * Estimate daily bonus income from resource extraction across multiple deposits.
+ * Useful for treasury planning alongside Phase-92 tax revenue.
+ */
+export function computeTotalDailyResourceIncome(deposits, states, techEra) {
+    let total = 0;
+    for (const deposit of deposits) {
+        const state = states.get(deposit.depositId);
+        if (!state)
+            continue;
+        total += computeDailyYield(deposit, state, techEra);
+    }
+    return total;
+}
+/**
+ * Return true if this resource type provides a military bonus.
+ */
+export function hasMilitaryBonus(type) {
+    return MILITARY_BONUS_RESOURCES.has(type);
+}
+/**
+ * Return true if this resource type provides a construction bonus.
+ */
+export function hasConstructionBonus(type) {
+    return CONSTRUCTION_BONUS_RESOURCES.has(type);
+}
+/**
+ * Return true if this resource type provides a mobility bonus.
+ */
+export function hasMobilityBonus(type) {
+    return MOBILITY_BONUS_RESOURCES.has(type);
+}
+/**
+ * Estimate how many days until the deposit is exhausted at the current
+ * extraction rate.  Returns `Infinity` if no workers or already exhausted.
+ */
+export function estimateDaysToExhaustion(deposit, state, techEra) {
+    if (deposit.richness_Q <= DEPLETION_EXHAUSTED_Q)
+        return 0;
+    const daily = computeDailyYield(deposit, state, techEra);
+    if (daily <= 0)
+        return Infinity;
+    // richness that needs to be drained = richness_Q - DEPLETION_EXHAUSTED_Q
+    // drain per day = daily × DEPLETION_RATE_PER_1000_CU / 1000
+    const drainPerDay = daily * DEPLETION_RATE_PER_1000_CU / 1000;
+    if (drainPerDay <= 0)
+        return Infinity;
+    const remainingRichness = deposit.richness_Q - DEPLETION_EXHAUSTED_Q;
+    return Math.ceil(remainingRichness / drainPerDay);
+}

package/package.json

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