@its-not-rocket-science/ananke 0.1.38 → 0.1.40

package/CHANGELOG.md

@@ -6,6 +6,50 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [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
+
+- **Phase 94 · Laws & Governance Codes** (`src/governance.ts`)
+  - `GovernanceType`: `"tribal" | "monarchy" | "oligarchy" | "republic" | "empire" | "theocracy"`.
+  - `GovernanceModifiers { taxEfficiencyMul_Q, mobilizationMax_Q, researchBonus, unrestMitigation_Q, stabilityIncrement_Q }` — aggregate modifier bundle applied to downstream phases.
+  - `GOVERNANCE_BASE: Record<GovernanceType, GovernanceModifiers>` — baseline modifiers per type; tribal maximises mobilisation (q(0.20)) but has lowest tax efficiency (q(0.60)); oligarchy and empire share highest tax efficiency (q(1.00)); theocracy has highest unrest mitigation (q(0.18)); republic has highest research bonus (+3).
+  - `LawCode { lawId, name, taxBonus_Q, researchBonus, mobilizationBonus_Q, unrestBonus_Q, stabilityCostPerDay_Q }` — discrete enacted policies.
+  - Five preset laws: `LAW_CONSCRIPTION` (+mobilisation, stability cost), `LAW_TAX_REFORM` (+tax), `LAW_SCHOLAR_PATRONAGE` (+5 research), `LAW_RULE_OF_LAW` (+tax +unrest mitigation), `LAW_MARTIAL_LAW` (+unrest mitigation, heavy stability drain).
+  - `GovernanceState { polityId, governanceType, activeLawIds, changeCooldown }`.
+  - `computeGovernanceModifiers(state, lawRegistry?)` — stacks law bonuses on governance baseline; clamps all outputs.
+  - `enactLaw(state, lawId)` / `repealLaw(state, lawId)` — add/remove laws; enforces `MAX_ACTIVE_LAWS = 5`.
+  - `changeGovernance(polity, state, newType)` — hits `polity.stabilityQ` by q(0.20); sets 365-day cooldown; no-op on same type or during cooldown.
+  - `stepGovernanceCooldown(state, elapsedDays)` — ticks down cooldown.
+  - `stepGovernanceStability(polity, state, elapsedDays, lawRegistry?)` — applies net `stabilityIncrement_Q` per day to `polity.stabilityQ`; no-op when law costs cancel the baseline.
+  - Added `./governance` subpath export to `package.json`.
+  - 48 new tests; 4,932 total. 100% statement/branch/function/line coverage. All thresholds met.
+
+---
+
 ## [0.1.38] — 2026-03-26
 
 ### Added

package/dist/src/governance.d.ts

@@ -0,0 +1,125 @@
+import type { Q } from "./units.js";
+import type { Polity } from "./polity.js";
+/** Governance form of a polity. */
+export type GovernanceType = "tribal" | "monarchy" | "oligarchy" | "republic" | "empire" | "theocracy";
+/**
+ * Modifier bundle derived from a polity's governance type and enacted laws.
+ * Each field is a Q multiplier or bonus that callers pass to downstream phases.
+ */
+export interface GovernanceModifiers {
+    /** Multiplier on Phase-92 annual tax revenue [Q]. */
+    taxEfficiencyMul_Q: Q;
+    /** Maximum mobilisation fraction override for Phase-93 [Q]. */
+    mobilizationMax_Q: Q;
+    /** Flat daily research point bonus for Phase-91 [integer]. */
+    researchBonus: number;
+    /**
+     * Passive unrest mitigation [Q].
+     * Subtract from raw unrest level before Phase-90 thresholds.
+     */
+    unrestMitigation_Q: Q;
+    /** Passive daily stability increment [Q/day × 100 to avoid sub-unit loss]. */
+    stabilityIncrement_Q: Q;
+}
+/** A discrete enacted law providing targeted modifiers. */
+export interface LawCode {
+    lawId: string;
+    name: string;
+    /** Additive bonus to `taxEfficiencyMul_Q` [Q]. */
+    taxBonus_Q: Q;
+    /** Additive bonus to `researchBonus` [integer]. */
+    researchBonus: number;
+    /** Additive bonus to `mobilizationMax_Q` [Q]. */
+    mobilizationBonus_Q: Q;
+    /** Additive bonus to `unrestMitigation_Q` [Q]. */
+    unrestBonus_Q: Q;
+    /** Stability cost per day while this law is active [Q]. */
+    stabilityCostPerDay_Q: Q;
+}
+/** Per-polity governance state. Store one externally per polity. */
+export interface GovernanceState {
+    polityId: string;
+    governanceType: GovernanceType;
+    /** IDs of currently enacted laws. Max `MAX_ACTIVE_LAWS`. */
+    activeLawIds: string[];
+    /**
+     * Cooldown days before governance type can be changed again.
+     * `stepGovernanceCooldown` decrements this.
+     */
+    changeCooldown: number;
+}
+/**
+ * Maximum number of laws that can be active simultaneously.
+ */
+export declare const MAX_ACTIVE_LAWS = 5;
+/**
+ * Stability penalty applied when changing governance type [Q].
+ * Represents the upheaval of political transition.
+ */
+export declare const GOVERNANCE_CHANGE_STABILITY_HIT_Q: Q;
+/**
+ * Cooldown days after a governance change before another is allowed.
+ */
+export declare const GOVERNANCE_CHANGE_COOLDOWN_DAYS = 365;
+/**
+ * Baseline governance modifiers for each type.
+ * Callers layer law-code bonuses on top.
+ */
+export declare const GOVERNANCE_BASE: Record<GovernanceType, GovernanceModifiers>;
+/** Conscription law: larger armies, minor stability cost. */
+export declare const LAW_CONSCRIPTION: LawCode;
+/** Tax reform: better tax efficiency, minor unrest from displacing old collectors. */
+export declare const LAW_TAX_REFORM: LawCode;
+/** Patronage of scholars: research bonus, expensive. */
+export declare const LAW_SCHOLAR_PATRONAGE: LawCode;
+/** Rule of law: stability bonus, research bonus, small unrest mitigation. */
+export declare const LAW_RULE_OF_LAW: LawCode;
+/** Martial law: strong unrest mitigation but heavy stability drain. */
+export declare const LAW_MARTIAL_LAW: LawCode;
+export declare const PRESET_LAW_CODES: LawCode[];
+/** Create a fresh `GovernanceState` with no laws and no cooldown. */
+export declare function createGovernanceState(polityId: string, governanceType?: GovernanceType): GovernanceState;
+/**
+ * Compute the aggregate `GovernanceModifiers` for the given state plus active laws.
+ *
+ * Each law's bonuses are added on top of the governance baseline.
+ * `taxEfficiencyMul_Q` is clamped to SCALE.Q; others to [0, SCALE.Q].
+ *
+ * @param lawRegistry  Map of lawId → LawCode.  Pass only enacted laws.
+ */
+export declare function computeGovernanceModifiers(state: GovernanceState, lawRegistry?: Map<string, LawCode>): GovernanceModifiers;
+/**
+ * Enact a new law.  Returns `false` if already enacted or at `MAX_ACTIVE_LAWS`.
+ */
+export declare function enactLaw(state: GovernanceState, lawId: string): boolean;
+/**
+ * Repeal an active law.  Returns `false` if the law was not active.
+ */
+export declare function repealLaw(state: GovernanceState, lawId: string): boolean;
+/**
+ * Change the governance type of a polity.
+ *
+ * Applies `GOVERNANCE_CHANGE_STABILITY_HIT_Q` to `polity.stabilityQ` and
+ * sets `state.changeCooldown = GOVERNANCE_CHANGE_COOLDOWN_DAYS`.
+ *
+ * Returns `false` (no-op) if:
+ * - `newType` is the same as current type.
+ * - `state.changeCooldown > 0` (still cooling down).
+ */
+export declare function changeGovernance(polity: Polity, state: GovernanceState, newType: GovernanceType): boolean;
+/**
+ * Tick down the governance change cooldown.
+ * Mutates `state.changeCooldown`; never goes below 0.
+ */
+export declare function stepGovernanceCooldown(state: GovernanceState, elapsedDays: number): void;
+/**
+ * Apply the governance passive stability increment per elapsed days.
+ *
+ * Uses `computeGovernanceModifiers` to get the net `stabilityIncrement_Q`,
+ * then adds `increment × elapsedDays` to `polity.stabilityQ`.
+ *
+ * No-op if net increment is 0 (law costs cancel the baseline bonus).
+ *
+ * @param lawRegistry  Active law registry.
+ */
+export declare function stepGovernanceStability(polity: Polity, state: GovernanceState, elapsedDays: number, lawRegistry?: Map<string, LawCode>): void;

package/dist/src/governance.js

@@ -0,0 +1,251 @@
+// src/governance.ts — Phase 94: Laws & Governance Codes
+//
+// The governance type of a polity shapes how effectively it taxes, mobilises
+// armies, maintains stability, and advances research.  Law codes are discrete
+// enacted policies that provide targeted bonuses and penalties on top of the
+// governance baseline.
+//
+// Design:
+//   - Pure data layer — no Entity fields, no kernel changes.
+//   - `GovernanceState` is stored externally per polity by the host.
+//   - `computeGovernanceModifiers` returns a single struct; callers apply each
+//     field to the appropriate Phase (92 tax, 91 research, 93 mobilisation, 90 unrest).
+//   - Governance changes trigger a stability hit and a cooldown before the
+//     next change is allowed.
+//   - All arithmetic is integer fixed-point; no floating-point accumulation.
+//
+// Integration:
+//   Phase 61 (Polity):   stabilityQ mutated on governance change.
+//   Phase 90 (Unrest):   unrestMitigation_Q reduces effective unrest.
+//   Phase 91 (Research): researchBonus added as flat bonus points/day.
+//   Phase 92 (Taxation): taxEfficiencyMul scales annual revenue.
+//   Phase 93 (Campaign): mobilizationMax_Q overrides default mobilisation cap.
+import { q, SCALE, clampQ } from "./units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/**
+ * Maximum number of laws that can be active simultaneously.
+ */
+export const MAX_ACTIVE_LAWS = 5;
+/**
+ * Stability penalty applied when changing governance type [Q].
+ * Represents the upheaval of political transition.
+ */
+export const GOVERNANCE_CHANGE_STABILITY_HIT_Q = q(0.20);
+/**
+ * Cooldown days after a governance change before another is allowed.
+ */
+export const GOVERNANCE_CHANGE_COOLDOWN_DAYS = 365;
+/**
+ * Baseline governance modifiers for each type.
+ * Callers layer law-code bonuses on top.
+ */
+export const GOVERNANCE_BASE = {
+    tribal: {
+        taxEfficiencyMul_Q: q(0.60),
+        mobilizationMax_Q: q(0.20), // can field a larger fraction but untrained
+        researchBonus: 0,
+        unrestMitigation_Q: q(0.05),
+        stabilityIncrement_Q: 0,
+    },
+    monarchy: {
+        taxEfficiencyMul_Q: q(0.80),
+        mobilizationMax_Q: q(0.12),
+        researchBonus: 1,
+        unrestMitigation_Q: q(0.08),
+        stabilityIncrement_Q: q(0.001),
+    },
+    oligarchy: {
+        taxEfficiencyMul_Q: q(1.00), // efficient tax extraction for the elite
+        mobilizationMax_Q: q(0.08), // mercenary-reliant, smaller citizen levy
+        researchBonus: 2,
+        unrestMitigation_Q: q(0.03),
+        stabilityIncrement_Q: 0,
+    },
+    republic: {
+        taxEfficiencyMul_Q: q(0.90),
+        mobilizationMax_Q: q(0.10),
+        researchBonus: 3,
+        unrestMitigation_Q: q(0.10),
+        stabilityIncrement_Q: q(0.002),
+    },
+    empire: {
+        taxEfficiencyMul_Q: q(1.00),
+        mobilizationMax_Q: q(0.15),
+        researchBonus: 2,
+        unrestMitigation_Q: q(0.12),
+        stabilityIncrement_Q: q(0.001),
+    },
+    theocracy: {
+        taxEfficiencyMul_Q: q(0.70), // tithes are less efficient than direct tax
+        mobilizationMax_Q: q(0.10),
+        researchBonus: 1,
+        unrestMitigation_Q: q(0.18), // religious legitimacy suppresses unrest
+        stabilityIncrement_Q: q(0.002),
+    },
+};
+// ── Preset law codes ──────────────────────────────────────────────────────────
+/** Conscription law: larger armies, minor stability cost. */
+export const LAW_CONSCRIPTION = {
+    lawId: "conscription",
+    name: "Conscription",
+    taxBonus_Q: 0,
+    researchBonus: 0,
+    mobilizationBonus_Q: q(0.03),
+    unrestBonus_Q: 0,
+    stabilityCostPerDay_Q: q(0.001),
+};
+/** Tax reform: better tax efficiency, minor unrest from displacing old collectors. */
+export const LAW_TAX_REFORM = {
+    lawId: "tax_reform",
+    name: "Tax Reform",
+    taxBonus_Q: q(0.10),
+    researchBonus: 0,
+    mobilizationBonus_Q: 0,
+    unrestBonus_Q: q(0.02),
+    stabilityCostPerDay_Q: 0,
+};
+/** Patronage of scholars: research bonus, expensive. */
+export const LAW_SCHOLAR_PATRONAGE = {
+    lawId: "scholar_patronage",
+    name: "Scholar Patronage",
+    taxBonus_Q: 0,
+    researchBonus: 5,
+    mobilizationBonus_Q: 0,
+    unrestBonus_Q: 0,
+    stabilityCostPerDay_Q: 0,
+};
+/** Rule of law: stability bonus, research bonus, small unrest mitigation. */
+export const LAW_RULE_OF_LAW = {
+    lawId: "rule_of_law",
+    name: "Rule of Law",
+    taxBonus_Q: q(0.05),
+    researchBonus: 1,
+    mobilizationBonus_Q: 0,
+    unrestBonus_Q: q(0.05),
+    stabilityCostPerDay_Q: 0,
+};
+/** Martial law: strong unrest mitigation but heavy stability drain. */
+export const LAW_MARTIAL_LAW = {
+    lawId: "martial_law",
+    name: "Martial Law",
+    taxBonus_Q: 0,
+    researchBonus: 0,
+    mobilizationBonus_Q: q(0.02),
+    unrestBonus_Q: q(0.12),
+    stabilityCostPerDay_Q: q(0.003),
+};
+export const PRESET_LAW_CODES = [
+    LAW_CONSCRIPTION,
+    LAW_TAX_REFORM,
+    LAW_SCHOLAR_PATRONAGE,
+    LAW_RULE_OF_LAW,
+    LAW_MARTIAL_LAW,
+];
+// ── Factory ───────────────────────────────────────────────────────────────────
+/** Create a fresh `GovernanceState` with no laws and no cooldown. */
+export function createGovernanceState(polityId, governanceType = "monarchy") {
+    return { polityId, governanceType, activeLawIds: [], changeCooldown: 0 };
+}
+// ── Modifier computation ──────────────────────────────────────────────────────
+/**
+ * Compute the aggregate `GovernanceModifiers` for the given state plus active laws.
+ *
+ * Each law's bonuses are added on top of the governance baseline.
+ * `taxEfficiencyMul_Q` is clamped to SCALE.Q; others to [0, SCALE.Q].
+ *
+ * @param lawRegistry  Map of lawId → LawCode.  Pass only enacted laws.
+ */
+export function computeGovernanceModifiers(state, lawRegistry = new Map()) {
+    const base = GOVERNANCE_BASE[state.governanceType];
+    let taxMul = base.taxEfficiencyMul_Q;
+    let mobilMax = base.mobilizationMax_Q;
+    let research = base.researchBonus;
+    let unrestMit = base.unrestMitigation_Q;
+    let stabilityInc = base.stabilityIncrement_Q;
+    for (const lawId of state.activeLawIds) {
+        const law = lawRegistry.get(lawId);
+        if (!law)
+            continue;
+        taxMul = clampQ(taxMul + law.taxBonus_Q, 0, SCALE.Q);
+        mobilMax = clampQ(mobilMax + law.mobilizationBonus_Q, 0, SCALE.Q);
+        research += law.researchBonus;
+        unrestMit = clampQ(unrestMit + law.unrestBonus_Q, 0, SCALE.Q);
+        // stability cost from active laws reduces the passive increment
+        stabilityInc = clampQ(stabilityInc - law.stabilityCostPerDay_Q, 0, SCALE.Q);
+    }
+    return {
+        taxEfficiencyMul_Q: taxMul,
+        mobilizationMax_Q: mobilMax,
+        researchBonus: Math.max(0, research),
+        unrestMitigation_Q: unrestMit,
+        stabilityIncrement_Q: stabilityInc,
+    };
+}
+// ── Law management ────────────────────────────────────────────────────────────
+/**
+ * Enact a new law.  Returns `false` if already enacted or at `MAX_ACTIVE_LAWS`.
+ */
+export function enactLaw(state, lawId) {
+    if (state.activeLawIds.includes(lawId))
+        return false;
+    if (state.activeLawIds.length >= MAX_ACTIVE_LAWS)
+        return false;
+    state.activeLawIds.push(lawId);
+    return true;
+}
+/**
+ * Repeal an active law.  Returns `false` if the law was not active.
+ */
+export function repealLaw(state, lawId) {
+    const idx = state.activeLawIds.indexOf(lawId);
+    if (idx === -1)
+        return false;
+    state.activeLawIds.splice(idx, 1);
+    return true;
+}
+// ── Governance change ─────────────────────────────────────────────────────────
+/**
+ * Change the governance type of a polity.
+ *
+ * Applies `GOVERNANCE_CHANGE_STABILITY_HIT_Q` to `polity.stabilityQ` and
+ * sets `state.changeCooldown = GOVERNANCE_CHANGE_COOLDOWN_DAYS`.
+ *
+ * Returns `false` (no-op) if:
+ * - `newType` is the same as current type.
+ * - `state.changeCooldown > 0` (still cooling down).
+ */
+export function changeGovernance(polity, state, newType) {
+    if (state.governanceType === newType)
+        return false;
+    if (state.changeCooldown > 0)
+        return false;
+    state.governanceType = newType;
+    state.changeCooldown = GOVERNANCE_CHANGE_COOLDOWN_DAYS;
+    polity.stabilityQ = clampQ(polity.stabilityQ - GOVERNANCE_CHANGE_STABILITY_HIT_Q, 0, SCALE.Q);
+    return true;
+}
+/**
+ * Tick down the governance change cooldown.
+ * Mutates `state.changeCooldown`; never goes below 0.
+ */
+export function stepGovernanceCooldown(state, elapsedDays) {
+    state.changeCooldown = Math.max(0, state.changeCooldown - elapsedDays);
+}
+// ── Passive stability tick ────────────────────────────────────────────────────
+/**
+ * Apply the governance passive stability increment per elapsed days.
+ *
+ * Uses `computeGovernanceModifiers` to get the net `stabilityIncrement_Q`,
+ * then adds `increment × elapsedDays` to `polity.stabilityQ`.
+ *
+ * No-op if net increment is 0 (law costs cancel the baseline bonus).
+ *
+ * @param lawRegistry  Active law registry.
+ */
+export function stepGovernanceStability(polity, state, elapsedDays, lawRegistry = new Map()) {
+    const mods = computeGovernanceModifiers(state, lawRegistry);
+    if (mods.stabilityIncrement_Q <= 0)
+        return;
+    const delta = Math.round(mods.stabilityIncrement_Q * elapsedDays);
+    polity.stabilityQ = clampQ(polity.stabilityQ + delta, 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.38",
+  "version": "0.1.40",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",
@@ -138,6 +138,14 @@
     "./military-campaign": {
       "import": "./dist/src/military-campaign.js",
       "types": "./dist/src/military-campaign.d.ts"
+    },
+    "./governance": {
+      "import": "./dist/src/governance.js",
+      "types": "./dist/src/governance.d.ts"
+    },
+    "./resources": {
+      "import": "./dist/src/resources.js",
+      "types": "./dist/src/resources.d.ts"
     }
   },
   "files": [
@@ -158,7 +166,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/its-not-rocket-science/ananke.git"
+    "url": "git+https://github.com/its-not-rocket-science/ananke.git"
   },
   "keywords": [
     "simulation",