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

package/CHANGELOG.md

@@ -6,6 +6,67 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [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
+
+- **Phase 93 · Military Campaigns & War Resolution** (`src/military-campaign.ts`)
+  - `CampaignState { campaignId, attackerPolityId, defenderPolityId, phase, startTick, daysElapsed, marchProgress_Q, attackerArmySize, attackerStrength_Q, defenderStrength_Q, outcome? }` — mutable live state stored externally per conflict.
+  - `CampaignPhase`: `"mobilization" | "march" | "battle" | "resolved"`.
+  - `BattleOutcome`: `"attacker_victory" | "defender_holds" | "stalemate"`.
+  - `computeArmySize(polity, mobilizationFrac_Q?)` — default q(0.05); clamped to `MAX_MOBILIZATION_Q = q(0.15)`.
+  - `computeBattleStrength(polity, armySize)` → Q: `militaryStrength_Q × armySize / REFERENCE_ARMY_SIZE × TECH_SOLDIER_MUL[techEra] × stabilityMul`; clamped to SCALE.Q.
+  - `mobilizeCampaign(campaign, attacker, mobilizationFrac_Q?)` — drains `MOBILIZATION_COST_PER_SOLDIER = 5` cu per soldier (capped at treasury); transitions to `"march"`.
+  - `prepareDefender(campaign, defender, wallBonus_Q?)` — sets defender strength; Phase-89 wall bonus increases effective defence.
+  - `stepCampaignMarch(campaign, attacker, elapsedDays, roadBonus_Q?)` — advances march at `BASE_MARCH_RATE_Q = q(0.05)` + road bonus; drains `CAMPAIGN_UPKEEP_PER_SOLDIER = 1` cu/soldier/day; triggers battle when progress reaches SCALE.Q.
+  - `resolveBattle(campaign, attacker, defender, worldSeed, tick)` → `BattleResult` — `eventSeed`-deterministic; outcome weighted by strength ratio; `VICTORY_TRIBUTE_Q = q(0.20)` of defender treasury on victory; reduces both sides' strength by casualty rates.
+  - `applyBattleConsequences(result, attacker, defender)` — applies morale/stability deltas; winner gains `VICTORY_MORALE_BONUS_Q = q(0.10)`; loser loses `DEFEAT_MORALE_HIT_Q = q(0.20)` + `DEFEAT_STABILITY_HIT_Q = q(0.15)`; both pay `COMBAT_STABILITY_DRAIN_Q = q(0.05)`.
+  - `computeWarUnrestPressure(campaign)` → Q: `WAR_UNREST_PRESSURE_Q = q(0.15)` during active campaign; 0 when resolved — feeds Phase-90 `computeUnrestLevel`.
+  - `computeDailyUpkeep(campaign)` → cu/day.
+  - Added `./military-campaign` subpath export to `package.json`.
+  - 56 new tests; 4,884 total. Coverage maintained above all thresholds.
+
+---
+
+## [0.1.37] — 2026-03-26
+
+### Added
+
+- **Phase 92 · Taxation & Treasury Revenue** (`src/taxation.ts`)
+  - `TaxPolicy { polityId, taxRate_Q, exemptFraction_Q? }` — per-polity config stored externally by the host.
+  - `TAX_REVENUE_PER_CAPITA_ANNUAL: Record<number, number>` — numeric TechEra keys; Prehistoric 0 → DeepSpace 20 k cu/person/year.
+  - `computeAnnualTaxRevenue(polity, policy)` → cu/year: `taxablePop × perCapita × taxRate × stabilityMul / SCALE.Q`; `stabilityMul ∈ [q(0.50), q(1.00)]` models collection efficiency; zero at Prehistoric era.
+  - `computeDailyTaxRevenue(polity, policy)` → cu/day: annual ÷ 365 with rounding.
+  - `computeTaxUnrestPressure(policy)` → Q [0, `MAX_TAX_UNREST_Q = q(0.30)`]: zero at/below `OPTIMAL_TAX_RATE_Q = q(0.15)`; linear ramp to max at `MAX_TAX_RATE_Q = q(0.50)`; passes directly into Phase-90 `computeUnrestLevel` as an additional factor.
+  - `stepTaxCollection(polity, policy, elapsedDays)` → `TaxCollectionResult`: adds `round(annual × days / 365)` to `polity.treasury_cu`; returns revenue and unrest pressure.
+  - `estimateDaysToTreasuryTarget(polity, policy, targetAmount)` → ceiling days; Infinity at zero daily rate.
+  - `computeRequiredTaxRate(polity, desiredAnnual)` → Q: reverse-solves for the rate needed to meet a target; clamped to MAX_TAX_RATE_Q.
+  - Added `./taxation` subpath export to `package.json`.
+  - 49 new tests; 4,828 total. Coverage maintained above all thresholds.
+
+---
+
 ## [0.1.36] — 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/military-campaign.d.ts

@@ -0,0 +1,210 @@
+import type { Q } from "./units.js";
+import type { Polity } from "./polity.js";
+/** Phase of a military campaign. */
+export type CampaignPhase = "mobilization" | "march" | "battle" | "resolved";
+/** How an open-field battle resolved. */
+export type BattleOutcome = "attacker_victory" | "defender_holds" | "stalemate";
+/** Live state of an ongoing or resolved campaign. */
+export interface CampaignState {
+    campaignId: string;
+    attackerPolityId: string;
+    defenderPolityId: string;
+    phase: CampaignPhase;
+    /** Day the campaign started. */
+    startTick: number;
+    /** Total days elapsed since campaign start. */
+    daysElapsed: number;
+    /**
+     * March progress toward the defender [0, SCALE.Q].
+     * Advances each day during `"march"` phase; battle triggers at SCALE.Q.
+     */
+    marchProgress_Q: Q;
+    /**
+     * Attacker army size at mobilization (integer soldiers).
+     * Does not change after mobilization; casualties reduce `attackerStrength_Q`.
+     */
+    attackerArmySize: number;
+    /** Attacker battle strength [0, SCALE.Q]; reduced by casualties. */
+    attackerStrength_Q: Q;
+    /** Defender battle strength [0, SCALE.Q]; reduced by casualties. */
+    defenderStrength_Q: Q;
+    /** Outcome when `phase === "resolved"`. */
+    outcome?: BattleOutcome;
+}
+/** Result of `mobilizeCampaign`. */
+export interface MobilizationResult {
+    /** Soldiers raised. */
+    armySize: number;
+    /** Cost-units drained from `polity.treasury_cu`. */
+    cost_cu: number;
+    /** Initial battle strength of the raised army [0, SCALE.Q]. */
+    armyStrength_Q: Q;
+}
+/** Result of `stepCampaignMarch`. */
+export interface MarchStepResult {
+    /** March progress added this step [Q]. */
+    progressAdded_Q: Q;
+    /** Cost-units drained from attacker treasury (daily upkeep). */
+    upkeep_cu: number;
+    /** Whether battle has been triggered this step. */
+    battleTriggered: boolean;
+}
+/** Result of `resolveBattle`. */
+export interface BattleResult {
+    outcome: BattleOutcome;
+    /** Fractional strength lost by attacker [0, SCALE.Q]. */
+    attackerCasualties_Q: Q;
+    /** Fractional strength lost by defender [0, SCALE.Q]. */
+    defenderCasualties_Q: Q;
+    /**
+     * Treasury tribute taken from defeated polity.
+     * Set only on `"attacker_victory"`.
+     */
+    tributeAmount?: number;
+}
+/**
+ * Default fraction of the population available as soldiers [Q].
+ * 5% mobilization is a sustainable wartime levy.
+ */
+export declare const MOBILIZATION_POP_FRACTION_Q: Q;
+/**
+ * Maximum fraction of population that can be mobilized [Q].
+ * Above this, domestic stability collapses.
+ */
+export declare const MAX_MOBILIZATION_Q: Q;
+/**
+ * Treasury cost per soldier for initial mobilization (equipment, muster pay).
+ * In cost-units per soldier.
+ */
+export declare const MOBILIZATION_COST_PER_SOLDIER = 5;
+/**
+ * Daily treasury upkeep per soldier [cost-units/soldier/day].
+ */
+export declare const CAMPAIGN_UPKEEP_PER_SOLDIER = 1;
+/**
+ * Base daily march progress [Q/day] at no road bonus.
+ * At this rate, full march (SCALE.Q) takes 20 days.
+ */
+export declare const BASE_MARCH_RATE_Q: Q;
+/**
+ * Fraction of the defeated polity's treasury taken as tribute on victory [Q].
+ */
+export declare const VICTORY_TRIBUTE_Q: Q;
+/**
+ * Per-soldier strength multiplier by tech era [Q/soldier].
+ * Higher eras have better weapons, tactics, and logistics.
+ */
+export declare const TECH_SOLDIER_MUL: Record<number, Q>;
+/**
+ * Reference army size used as denominator for strength scaling.
+ * An army of this size at q(1.0) military strength = battle strength q(1.0).
+ */
+export declare const REFERENCE_ARMY_SIZE = 10000;
+/**
+ * Unrest pressure on attacker polity during an active campaign [Q].
+ * Pass as extra unrest factor into Phase-90 `computeUnrestLevel`.
+ */
+export declare const WAR_UNREST_PRESSURE_Q: Q;
+/**
+ * Casualty rates per battle outcome.
+ * These are fractional strength losses applied to each side.
+ */
+export declare const ATTACKER_CASUALTY_ON_VICTORY_Q: Q;
+export declare const ATTACKER_CASUALTY_ON_DEFEAT_Q: Q;
+export declare const ATTACKER_CASUALTY_ON_STALEMATE_Q: Q;
+export declare const DEFENDER_CASUALTY_ON_VICTORY_Q: Q;
+export declare const DEFENDER_CASUALTY_ON_DEFEAT_Q: Q;
+export declare const DEFENDER_CASUALTY_ON_STALEMATE_Q: Q;
+/** Create a new campaign in `"mobilization"` phase. */
+export declare function createCampaign(campaignId: string, attackerPolityId: string, defenderPolityId: string, tick: number): CampaignState;
+/**
+ * Compute battle strength for a polity with a given army size [Q].
+ *
+ * Formula:
+ *   soldierMul    = TECH_SOLDIER_MUL[techEra]  (default q(0.80))
+ *   stabilityMul  = q(0.50) + mulDiv(q(0.50), stabilityQ, SCALE.Q)  ∈ [q(0.50), q(1.00)]
+ *   rawStrength   = round(militaryStrength_Q × armySize / REFERENCE_ARMY_SIZE)
+ *   adjusted      = round(rawStrength × soldierMul / SCALE.Q)
+ *   final         = clampQ(round(adjusted × stabilityMul / SCALE.Q), 0, SCALE.Q)
+ *
+ * @param armySize  Number of soldiers (capped at population for safety).
+ */
+export declare function computeBattleStrength(polity: Polity, armySize: number): Q;
+/**
+ * Compute army size for a given mobilization fraction [soldiers].
+ * Clamped to `[0, floor(population × MAX_MOBILIZATION_Q / SCALE.Q)]`.
+ */
+export declare function computeArmySize(polity: Polity, mobilizationFrac_Q?: Q): number;
+/**
+ * Raise an army and transition campaign to `"march"` phase.
+ *
+ * Drains `armySize × MOBILIZATION_COST_PER_SOLDIER` from `polity.treasury_cu`
+ * (capped at available treasury — a treasury-poor polity raises a smaller
+ * effective force than planned).
+ *
+ * Mutates `campaign` and `polity.treasury_cu`.
+ */
+export declare function mobilizeCampaign(campaign: CampaignState, attacker: Polity, mobilizationFrac_Q?: Q): MobilizationResult;
+/**
+ * Set the defender's battle strength.  Call before `stepCampaignMarch` starts.
+ *
+ * @param wallBonus_Q  Phase-89 wall infrastructure bonus [0, SCALE.Q].
+ *                     Increases defender effective strength by this fraction.
+ */
+export declare function prepareDefender(campaign: CampaignState, defender: Polity, wallBonus_Q?: Q): Q;
+/**
+ * Advance the campaign march for one tick.
+ *
+ * Daily march rate = `BASE_MARCH_RATE_Q + roadBonus_Q`.
+ * Daily upkeep    = `attackerArmySize × CAMPAIGN_UPKEEP_PER_SOLDIER`.
+ *
+ * When `marchProgress_Q` reaches SCALE.Q the phase transitions to `"battle"`.
+ *
+ * Mutates `campaign` and `attacker.treasury_cu`.
+ *
+ * @param roadBonus_Q  Phase-89 road infrastructure bonus [0, SCALE.Q].
+ */
+export declare function stepCampaignMarch(campaign: CampaignState, attacker: Polity, elapsedDays: number, roadBonus_Q?: Q): MarchStepResult;
+/**
+ * Resolve the field battle deterministically.
+ *
+ * Outcome probability is weighted by the strength ratio between attacker and
+ * defender, modified by a `eventSeed`-derived roll.
+ *
+ * Roll:
+ *   seed   = eventSeed(worldSeed, tick, hashString(attackerId), hashString(defenderId), 9301)
+ *   roll   = seed % SCALE.Q   ∈ [0, 9999]
+ *   threshold_victory  = round(attackerStr × q(0.80) / SCALE.Q)  — min roll to win
+ *   threshold_stalemate = threshold_victory + round(q(0.15) × SCALE.Q / SCALE.Q)
+ *
+ * This ensures that a stronger attacker has a proportionally higher chance
+ * of victory, while weaker attackers still occasionally succeed.
+ *
+ * Mutates `campaign.outcome`, `campaign.phase`, and `attacker.treasury_cu`/
+ * `defender.treasury_cu` (tribute on victory).
+ */
+export declare function resolveBattle(campaign: CampaignState, attacker: Polity, defender: Polity, worldSeed: number, tick: number): BattleResult;
+/**
+ * Apply morale and stability penalties to both sides after a resolved battle.
+ *
+ * - Loser: morale −`DEFEAT_MORALE_HIT_Q`, stability −`DEFEAT_STABILITY_HIT_Q`.
+ * - Winner: morale +`VICTORY_MORALE_BONUS_Q` (capped at SCALE.Q).
+ * - Both: stability drained by `COMBAT_STABILITY_DRAIN_Q` (war is always costly).
+ *
+ * Mutates `attacker` and `defender` in place.
+ */
+export declare const DEFEAT_MORALE_HIT_Q: Q;
+export declare const DEFEAT_STABILITY_HIT_Q: Q;
+export declare const VICTORY_MORALE_BONUS_Q: Q;
+export declare const COMBAT_STABILITY_DRAIN_Q: Q;
+export declare function applyBattleConsequences(result: BattleResult, attacker: Polity, defender: Polity): void;
+/**
+ * Compute daily treasury upkeep for an active campaign [cost-units/day].
+ */
+export declare function computeDailyUpkeep(campaign: CampaignState): number;
+/**
+ * Return the war unrest pressure on the attacker polity during an active campaign.
+ * Pass as an extra factor into Phase-90 `computeUnrestLevel`.
+ * Returns 0 when campaign is resolved.
+ */
+export declare function computeWarUnrestPressure(campaign: CampaignState): Q;

package/dist/src/military-campaign.js

@@ -0,0 +1,316 @@
+// src/military-campaign.ts — Phase 93: Military Campaigns & War Resolution
+//
+// Models field army mobilization, campaign march, and open-battle resolution
+// between polities.  Siege warfare against fortified positions is handled
+// separately by Phase-84 (src/siege.ts).
+//
+// Design:
+//   - Pure data layer — no Entity fields, no kernel changes.
+//   - `CampaignState` is the mutable live state; hosts store one per conflict.
+//   - All random outcomes use `eventSeed` for full determinism.
+//   - Battle strength derives from polity military strength × army size;
+//     tech era scales the per-soldier multiplier.
+//   - Phase-89 roads shorten march duration; Phase-89 walls add defender bonus.
+//   - Phase-90 unrest pressure increases during active campaigns.
+//   - Phase-92 treasury is drained daily by upkeep.
+//
+// Integration:
+//   Phase 11 (Tech):     techEra gates per-soldier strength multiplier.
+//   Phase 61 (Polity):   population, militaryStrength_Q, treasury_cu, stabilityQ mutated.
+//   Phase 89 (Infra):    road bonus (march speed), wall bonus (defender strength).
+//   Phase 90 (Unrest):   warUnrestPressure_Q as extra unrest factor.
+//   Phase 92 (Taxation): daily upkeep drains treasury alongside tax revenue.
+import { eventSeed, hashString } from "./sim/seeds.js";
+import { q, SCALE, clampQ, mulDiv } from "./units.js";
+import { TechEra } from "./sim/tech.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/**
+ * Default fraction of the population available as soldiers [Q].
+ * 5% mobilization is a sustainable wartime levy.
+ */
+export const MOBILIZATION_POP_FRACTION_Q = q(0.05);
+/**
+ * Maximum fraction of population that can be mobilized [Q].
+ * Above this, domestic stability collapses.
+ */
+export const MAX_MOBILIZATION_Q = q(0.15);
+/**
+ * Treasury cost per soldier for initial mobilization (equipment, muster pay).
+ * In cost-units per soldier.
+ */
+export const MOBILIZATION_COST_PER_SOLDIER = 5;
+/**
+ * Daily treasury upkeep per soldier [cost-units/soldier/day].
+ */
+export const CAMPAIGN_UPKEEP_PER_SOLDIER = 1;
+/**
+ * Base daily march progress [Q/day] at no road bonus.
+ * At this rate, full march (SCALE.Q) takes 20 days.
+ */
+export const BASE_MARCH_RATE_Q = q(0.05);
+/**
+ * Fraction of the defeated polity's treasury taken as tribute on victory [Q].
+ */
+export const VICTORY_TRIBUTE_Q = q(0.20);
+/**
+ * Per-soldier strength multiplier by tech era [Q/soldier].
+ * Higher eras have better weapons, tactics, and logistics.
+ */
+export const TECH_SOLDIER_MUL = {
+    [TechEra.Prehistoric]: q(0.50),
+    [TechEra.Ancient]: q(0.70),
+    [TechEra.Medieval]: q(0.80),
+    [TechEra.EarlyModern]: q(0.90),
+    [TechEra.Industrial]: q(1.00),
+    [TechEra.Modern]: q(1.00),
+    [TechEra.NearFuture]: q(1.00),
+    [TechEra.FarFuture]: q(1.00),
+    [TechEra.DeepSpace]: q(1.00),
+};
+/**
+ * Reference army size used as denominator for strength scaling.
+ * An army of this size at q(1.0) military strength = battle strength q(1.0).
+ */
+export const REFERENCE_ARMY_SIZE = 10_000;
+/**
+ * Unrest pressure on attacker polity during an active campaign [Q].
+ * Pass as extra unrest factor into Phase-90 `computeUnrestLevel`.
+ */
+export const WAR_UNREST_PRESSURE_Q = q(0.15);
+/**
+ * Casualty rates per battle outcome.
+ * These are fractional strength losses applied to each side.
+ */
+export const ATTACKER_CASUALTY_ON_VICTORY_Q = q(0.20);
+export const ATTACKER_CASUALTY_ON_DEFEAT_Q = q(0.40);
+export const ATTACKER_CASUALTY_ON_STALEMATE_Q = q(0.25);
+export const DEFENDER_CASUALTY_ON_VICTORY_Q = q(0.50);
+export const DEFENDER_CASUALTY_ON_DEFEAT_Q = q(0.15);
+export const DEFENDER_CASUALTY_ON_STALEMATE_Q = q(0.25);
+// ── Factory ───────────────────────────────────────────────────────────────────
+/** Create a new campaign in `"mobilization"` phase. */
+export function createCampaign(campaignId, attackerPolityId, defenderPolityId, tick) {
+    return {
+        campaignId,
+        attackerPolityId,
+        defenderPolityId,
+        phase: "mobilization",
+        startTick: tick,
+        daysElapsed: 0,
+        marchProgress_Q: 0,
+        attackerArmySize: 0,
+        attackerStrength_Q: 0,
+        defenderStrength_Q: 0,
+    };
+}
+// ── Army strength ─────────────────────────────────────────────────────────────
+/**
+ * Compute battle strength for a polity with a given army size [Q].
+ *
+ * Formula:
+ *   soldierMul    = TECH_SOLDIER_MUL[techEra]  (default q(0.80))
+ *   stabilityMul  = q(0.50) + mulDiv(q(0.50), stabilityQ, SCALE.Q)  ∈ [q(0.50), q(1.00)]
+ *   rawStrength   = round(militaryStrength_Q × armySize / REFERENCE_ARMY_SIZE)
+ *   adjusted      = round(rawStrength × soldierMul / SCALE.Q)
+ *   final         = clampQ(round(adjusted × stabilityMul / SCALE.Q), 0, SCALE.Q)
+ *
+ * @param armySize  Number of soldiers (capped at population for safety).
+ */
+export function computeBattleStrength(polity, armySize) {
+    const soldierMul = (TECH_SOLDIER_MUL[polity.techEra] ?? q(0.80));
+    const stabilityMul = SCALE.Q / 2 + mulDiv(SCALE.Q / 2, polity.stabilityQ, SCALE.Q);
+    const raw = Math.round(polity.militaryStrength_Q * armySize / REFERENCE_ARMY_SIZE);
+    const adjusted = Math.round(raw * soldierMul / SCALE.Q);
+    return clampQ(Math.round(adjusted * stabilityMul / SCALE.Q), 0, SCALE.Q);
+}
+/**
+ * Compute army size for a given mobilization fraction [soldiers].
+ * Clamped to `[0, floor(population × MAX_MOBILIZATION_Q / SCALE.Q)]`.
+ */
+export function computeArmySize(polity, mobilizationFrac_Q = MOBILIZATION_POP_FRACTION_Q) {
+    const frac = clampQ(mobilizationFrac_Q, 0, MAX_MOBILIZATION_Q);
+    return Math.floor(polity.population * frac / SCALE.Q);
+}
+// ── Mobilization ──────────────────────────────────────────────────────────────
+/**
+ * Raise an army and transition campaign to `"march"` phase.
+ *
+ * Drains `armySize × MOBILIZATION_COST_PER_SOLDIER` from `polity.treasury_cu`
+ * (capped at available treasury — a treasury-poor polity raises a smaller
+ * effective force than planned).
+ *
+ * Mutates `campaign` and `polity.treasury_cu`.
+ */
+export function mobilizeCampaign(campaign, attacker, mobilizationFrac_Q = MOBILIZATION_POP_FRACTION_Q) {
+    const armySize = computeArmySize(attacker, mobilizationFrac_Q);
+    const fullCost = armySize * MOBILIZATION_COST_PER_SOLDIER;
+    const cost_cu = Math.min(fullCost, attacker.treasury_cu);
+    attacker.treasury_cu -= cost_cu;
+    // Scale army size if treasury couldn't cover full cost
+    const fundedFrac = fullCost > 0 ? cost_cu / fullCost : 1;
+    const effectiveSize = Math.floor(armySize * fundedFrac);
+    const armyStrength_Q = computeBattleStrength(attacker, effectiveSize);
+    campaign.attackerArmySize = effectiveSize;
+    campaign.attackerStrength_Q = armyStrength_Q;
+    campaign.phase = "march";
+    return { armySize: effectiveSize, cost_cu, armyStrength_Q };
+}
+// ── Defender preparation ──────────────────────────────────────────────────────
+/**
+ * Set the defender's battle strength.  Call before `stepCampaignMarch` starts.
+ *
+ * @param wallBonus_Q  Phase-89 wall infrastructure bonus [0, SCALE.Q].
+ *                     Increases defender effective strength by this fraction.
+ */
+export function prepareDefender(campaign, defender, wallBonus_Q = 0) {
+    const armySize = computeArmySize(defender);
+    const baseStr = computeBattleStrength(defender, armySize);
+    const wallBoost = mulDiv(baseStr, wallBonus_Q, SCALE.Q);
+    const final = clampQ(baseStr + wallBoost, 0, SCALE.Q);
+    campaign.defenderStrength_Q = final;
+    return final;
+}
+// ── March ─────────────────────────────────────────────────────────────────────
+/**
+ * Advance the campaign march for one tick.
+ *
+ * Daily march rate = `BASE_MARCH_RATE_Q + roadBonus_Q`.
+ * Daily upkeep    = `attackerArmySize × CAMPAIGN_UPKEEP_PER_SOLDIER`.
+ *
+ * When `marchProgress_Q` reaches SCALE.Q the phase transitions to `"battle"`.
+ *
+ * Mutates `campaign` and `attacker.treasury_cu`.
+ *
+ * @param roadBonus_Q  Phase-89 road infrastructure bonus [0, SCALE.Q].
+ */
+export function stepCampaignMarch(campaign, attacker, elapsedDays, roadBonus_Q = 0) {
+    const dailyProgress = clampQ(BASE_MARCH_RATE_Q + roadBonus_Q, 0, SCALE.Q);
+    const added = clampQ(Math.min(dailyProgress * elapsedDays, SCALE.Q - campaign.marchProgress_Q), 0, SCALE.Q);
+    campaign.marchProgress_Q = clampQ(campaign.marchProgress_Q + added, 0, SCALE.Q);
+    campaign.daysElapsed += elapsedDays;
+    const upkeep_cu = Math.min(campaign.attackerArmySize * CAMPAIGN_UPKEEP_PER_SOLDIER * elapsedDays, attacker.treasury_cu);
+    attacker.treasury_cu -= upkeep_cu;
+    const battleTriggered = campaign.marchProgress_Q >= SCALE.Q;
+    if (battleTriggered && campaign.phase === "march") {
+        campaign.phase = "battle";
+    }
+    return { progressAdded_Q: added, upkeep_cu, battleTriggered };
+}
+// ── Battle resolution ─────────────────────────────────────────────────────────
+/**
+ * Resolve the field battle deterministically.
+ *
+ * Outcome probability is weighted by the strength ratio between attacker and
+ * defender, modified by a `eventSeed`-derived roll.
+ *
+ * Roll:
+ *   seed   = eventSeed(worldSeed, tick, hashString(attackerId), hashString(defenderId), 9301)
+ *   roll   = seed % SCALE.Q   ∈ [0, 9999]
+ *   threshold_victory  = round(attackerStr × q(0.80) / SCALE.Q)  — min roll to win
+ *   threshold_stalemate = threshold_victory + round(q(0.15) × SCALE.Q / SCALE.Q)
+ *
+ * This ensures that a stronger attacker has a proportionally higher chance
+ * of victory, while weaker attackers still occasionally succeed.
+ *
+ * Mutates `campaign.outcome`, `campaign.phase`, and `attacker.treasury_cu`/
+ * `defender.treasury_cu` (tribute on victory).
+ */
+export function resolveBattle(campaign, attacker, defender, worldSeed, tick) {
+    const seed = eventSeed(worldSeed, tick, hashString(attacker.id), hashString(defender.id), 9301);
+    const roll = seed % SCALE.Q;
+    // Compute victory threshold based on relative strength
+    const atkStr = campaign.attackerStrength_Q;
+    const defStr = campaign.defenderStrength_Q;
+    const totalStr = atkStr + defStr;
+    const atkFrac = totalStr > 0 ? Math.round(atkStr * SCALE.Q / totalStr) : SCALE.Q / 2;
+    // Thresholds:
+    // [0, victoryThreshold)  → attacker_victory
+    // [victoryThreshold, stalemateThreshold) → stalemate
+    // [stalemateThreshold, SCALE.Q) → defender_holds
+    const victoryThreshold = Math.round(atkFrac * 0.7);
+    const stalemateThreshold = Math.round(atkFrac * 0.9);
+    let outcome;
+    let attackerCas;
+    let defenderCas;
+    let tributeAmount;
+    if (roll < victoryThreshold) {
+        outcome = "attacker_victory";
+        attackerCas = ATTACKER_CASUALTY_ON_VICTORY_Q;
+        defenderCas = DEFENDER_CASUALTY_ON_VICTORY_Q;
+        tributeAmount = Math.floor(mulDiv(defender.treasury_cu, VICTORY_TRIBUTE_Q, SCALE.Q));
+        defender.treasury_cu -= tributeAmount;
+        attacker.treasury_cu += tributeAmount;
+    }
+    else if (roll < stalemateThreshold) {
+        outcome = "stalemate";
+        attackerCas = ATTACKER_CASUALTY_ON_STALEMATE_Q;
+        defenderCas = DEFENDER_CASUALTY_ON_STALEMATE_Q;
+    }
+    else {
+        outcome = "defender_holds";
+        attackerCas = ATTACKER_CASUALTY_ON_DEFEAT_Q;
+        defenderCas = DEFENDER_CASUALTY_ON_DEFEAT_Q;
+    }
+    // Apply strength reduction
+    campaign.attackerStrength_Q = clampQ(campaign.attackerStrength_Q - mulDiv(campaign.attackerStrength_Q, attackerCas, SCALE.Q), 0, SCALE.Q);
+    campaign.defenderStrength_Q = clampQ(campaign.defenderStrength_Q - mulDiv(campaign.defenderStrength_Q, defenderCas, SCALE.Q), 0, SCALE.Q);
+    campaign.outcome = outcome;
+    campaign.phase = "resolved";
+    return {
+        outcome,
+        attackerCasualties_Q: attackerCas,
+        defenderCasualties_Q: defenderCas,
+        ...(tributeAmount !== undefined ? { tributeAmount } : {}),
+    };
+}
+// ── Post-battle consequences ──────────────────────────────────────────────────
+/**
+ * Apply morale and stability penalties to both sides after a resolved battle.
+ *
+ * - Loser: morale −`DEFEAT_MORALE_HIT_Q`, stability −`DEFEAT_STABILITY_HIT_Q`.
+ * - Winner: morale +`VICTORY_MORALE_BONUS_Q` (capped at SCALE.Q).
+ * - Both: stability drained by `COMBAT_STABILITY_DRAIN_Q` (war is always costly).
+ *
+ * Mutates `attacker` and `defender` in place.
+ */
+export const DEFEAT_MORALE_HIT_Q = q(0.20);
+export const DEFEAT_STABILITY_HIT_Q = q(0.15);
+export const VICTORY_MORALE_BONUS_Q = q(0.10);
+export const COMBAT_STABILITY_DRAIN_Q = q(0.05);
+export function applyBattleConsequences(result, attacker, defender) {
+    // Both sides pay a stability toll for the war
+    attacker.stabilityQ = clampQ(attacker.stabilityQ - COMBAT_STABILITY_DRAIN_Q, 0, SCALE.Q);
+    defender.stabilityQ = clampQ(defender.stabilityQ - COMBAT_STABILITY_DRAIN_Q, 0, SCALE.Q);
+    if (result.outcome === "attacker_victory") {
+        attacker.moraleQ = clampQ(attacker.moraleQ + VICTORY_MORALE_BONUS_Q, 0, SCALE.Q);
+        defender.moraleQ = clampQ(defender.moraleQ - DEFEAT_MORALE_HIT_Q, 0, SCALE.Q);
+        defender.stabilityQ = clampQ(defender.stabilityQ - DEFEAT_STABILITY_HIT_Q, 0, SCALE.Q);
+    }
+    else if (result.outcome === "defender_holds") {
+        defender.moraleQ = clampQ(defender.moraleQ + VICTORY_MORALE_BONUS_Q, 0, SCALE.Q);
+        attacker.moraleQ = clampQ(attacker.moraleQ - DEFEAT_MORALE_HIT_Q, 0, SCALE.Q);
+        attacker.stabilityQ = clampQ(attacker.stabilityQ - DEFEAT_STABILITY_HIT_Q, 0, SCALE.Q);
+    }
+    else {
+        // Stalemate: minor morale drain on both
+        attacker.moraleQ = clampQ(attacker.moraleQ - mulDiv(DEFEAT_MORALE_HIT_Q, q(0.40), SCALE.Q), 0, SCALE.Q);
+        defender.moraleQ = clampQ(defender.moraleQ - mulDiv(DEFEAT_MORALE_HIT_Q, q(0.40), SCALE.Q), 0, SCALE.Q);
+    }
+}
+// ── Upkeep & attrition ────────────────────────────────────────────────────────
+/**
+ * Compute daily treasury upkeep for an active campaign [cost-units/day].
+ */
+export function computeDailyUpkeep(campaign) {
+    return campaign.attackerArmySize * CAMPAIGN_UPKEEP_PER_SOLDIER;
+}
+/**
+ * Return the war unrest pressure on the attacker polity during an active campaign.
+ * Pass as an extra factor into Phase-90 `computeUnrestLevel`.
+ * Returns 0 when campaign is resolved.
+ */
+export function computeWarUnrestPressure(campaign) {
+    if (campaign.phase === "resolved")
+        return 0;
+    return WAR_UNREST_PRESSURE_Q;
+}

package/dist/src/taxation.d.ts

@@ -0,0 +1,101 @@
+import type { Q } from "./units.js";
+import type { Polity } from "./polity.js";
+/** Per-polity tax configuration. Store one externally per polity. */
+export interface TaxPolicy {
+    polityId: string;
+    /**
+     * Fraction of the theoretical maximum revenue to collect [0, SCALE.Q].
+     * q(0.15) = standard rate; q(0.25) or above triggers unrest pressure.
+     */
+    taxRate_Q: Q;
+    /**
+     * Fraction of the population exempt from taxation (clergy, nobility, etc.)
+     * [0, SCALE.Q].  Reduces taxable base proportionally.  Defaults to 0.
+     */
+    exemptFraction_Q?: Q;
+}
+/** Result returned by `stepTaxCollection`. */
+export interface TaxCollectionResult {
+    /** Cost-units added to polity treasury this step. */
+    revenue_cu: number;
+    /** Unrest pressure generated by the current tax rate [0, SCALE.Q]. */
+    unrestPressure_Q: Q;
+}
+/**
+ * Annual tax revenue per capita at full (q(1.0)) tax rate, keyed by TechEra.
+ * Prehistoric has no monetary economy — yield is zero.
+ * Values are in cost-units per person per year.
+ */
+export declare const TAX_REVENUE_PER_CAPITA_ANNUAL: Record<number, number>;
+/**
+ * Tax rate below which no unrest pressure is generated [Q].
+ * Rates at or below this are considered politically acceptable.
+ */
+export declare const OPTIMAL_TAX_RATE_Q: Q;
+/**
+ * Tax rate above which unrest pressure reaches maximum [Q].
+ * Between OPTIMAL and MAX, pressure scales linearly.
+ */
+export declare const MAX_TAX_RATE_Q: Q;
+/**
+ * Maximum unrest pressure that taxation alone can generate [Q].
+ * Passed as an extra additive factor into Phase-90 `computeUnrestLevel`.
+ */
+export declare const MAX_TAX_UNREST_Q: Q;
+/** Create a default TaxPolicy with a standard rate and no exemptions. */
+export declare function createTaxPolicy(polityId: string, taxRate_Q?: Q): TaxPolicy;
+/**
+ * Compute annual tax revenue for a polity [cost-units/year].
+ *
+ * Formula:
+ *   taxablePopulation = population × (SCALE.Q − exemptFraction) / SCALE.Q
+ *   perCapita         = TAX_REVENUE_PER_CAPITA_ANNUAL[techEra]  (default 0)
+ *   stabilityMul      = SCALE.Q/2 + mulDiv(SCALE.Q/2, stabilityQ, SCALE.Q)
+ *                     ∈ [5000, 10000] = [q(0.50), q(1.00)]
+ *   gross             = taxablePopulation × perCapita × taxRate / SCALE.Q
+ *   annual            = round(gross × stabilityMul / SCALE.Q)
+ *
+ * Stability models collection efficiency: a fractured polity cannot collect
+ * the full assessed tax.  At zero stability, only half the theoretical
+ * revenue is gathered.
+ */
+export declare function computeAnnualTaxRevenue(polity: Polity, policy: TaxPolicy): number;
+/**
+ * Compute daily tax revenue [cost-units/day].
+ * Derived from `computeAnnualTaxRevenue` with day-fraction rounding.
+ */
+export declare function computeDailyTaxRevenue(polity: Polity, policy: TaxPolicy): number;
+/**
+ * Compute the unrest pressure generated by the current tax rate [Q].
+ *
+ * - At or below `OPTIMAL_TAX_RATE_Q`: pressure = 0.
+ * - Between OPTIMAL and MAX_TAX_RATE_Q: linear ramp 0 → MAX_TAX_UNREST_Q.
+ * - At or above MAX_TAX_RATE_Q: pressure = MAX_TAX_UNREST_Q.
+ *
+ * Pass the result as an extra additive unrest factor to Phase-90
+ * `computeUnrestLevel`.
+ */
+export declare function computeTaxUnrestPressure(policy: TaxPolicy): Q;
+/**
+ * Collect taxes for `elapsedDays` days and add to `polity.treasury_cu`.
+ *
+ * Mutates `polity.treasury_cu`.
+ *
+ * @returns Revenue added and the unrest pressure the current rate generates.
+ */
+export declare function stepTaxCollection(polity: Polity, policy: TaxPolicy, elapsedDays: number): TaxCollectionResult;
+/**
+ * Estimate how many days until the treasury reaches a target amount at the
+ * current daily tax revenue.  Returns `Infinity` if daily revenue is zero.
+ */
+export declare function estimateDaysToTreasuryTarget(polity: Polity, policy: TaxPolicy, targetAmount: number): number;
+/**
+ * Compute the effective tax rate needed to hit a desired annual revenue,
+ * clamped to [0, MAX_TAX_RATE_Q].
+ *
+ * Useful for host AI: "what rate do I need to fund X?"
+ *
+ * Returns MAX_TAX_RATE_Q if the desired revenue exceeds what full taxation
+ * can provide.
+ */
+export declare function computeRequiredTaxRate(polity: Polity, desiredAnnual: number): Q;

package/dist/src/taxation.js

@@ -0,0 +1,160 @@
+// src/taxation.ts — Phase 92: Taxation & Treasury Revenue
+//
+// Polities derive the bulk of their income from taxing population and trade.
+// This module models per-capita tax yields by tech era, stability-modulated
+// collection efficiency, and the unrest pressure that high rates generate.
+//
+// Design:
+//   - Pure data layer — no Entity fields, no kernel changes.
+//   - `TaxPolicy` is stored externally per polity by the host.
+//   - Uses numeric TechEra values (0–8) from Phase-11 tech.ts.
+//   - All arithmetic is integer fixed-point; no floating-point accumulation.
+//   - Trade-route income (Phase-83/89) is separate and additive.
+//
+// Integration:
+//   Phase 11 (Tech):    TechEra gates per-capita base yield.
+//   Phase 61 (Polity):  population, stabilityQ, treasury_cu are read/mutated.
+//   Phase 90 (Unrest):  computeTaxUnrestPressure returns a faminePressure_Q-style
+//                       value for use as an additional unrest factor.
+import { q, SCALE, clampQ, mulDiv } from "./units.js";
+import { TechEra } from "./sim/tech.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/**
+ * Annual tax revenue per capita at full (q(1.0)) tax rate, keyed by TechEra.
+ * Prehistoric has no monetary economy — yield is zero.
+ * Values are in cost-units per person per year.
+ */
+export const TAX_REVENUE_PER_CAPITA_ANNUAL = {
+    [TechEra.Prehistoric]: 0,
+    [TechEra.Ancient]: 2,
+    [TechEra.Medieval]: 5,
+    [TechEra.EarlyModern]: 15,
+    [TechEra.Industrial]: 50,
+    [TechEra.Modern]: 200,
+    [TechEra.NearFuture]: 1_000,
+    [TechEra.FarFuture]: 5_000,
+    [TechEra.DeepSpace]: 20_000,
+};
+/**
+ * Tax rate below which no unrest pressure is generated [Q].
+ * Rates at or below this are considered politically acceptable.
+ */
+export const OPTIMAL_TAX_RATE_Q = q(0.15);
+/**
+ * Tax rate above which unrest pressure reaches maximum [Q].
+ * Between OPTIMAL and MAX, pressure scales linearly.
+ */
+export const MAX_TAX_RATE_Q = q(0.50);
+/**
+ * Maximum unrest pressure that taxation alone can generate [Q].
+ * Passed as an extra additive factor into Phase-90 `computeUnrestLevel`.
+ */
+export const MAX_TAX_UNREST_Q = q(0.30);
+// ── Factory ───────────────────────────────────────────────────────────────────
+/** Create a default TaxPolicy with a standard rate and no exemptions. */
+export function createTaxPolicy(polityId, taxRate_Q = q(0.15)) {
+    return { polityId, taxRate_Q };
+}
+// ── Core computation ──────────────────────────────────────────────────────────
+/**
+ * Compute annual tax revenue for a polity [cost-units/year].
+ *
+ * Formula:
+ *   taxablePopulation = population × (SCALE.Q − exemptFraction) / SCALE.Q
+ *   perCapita         = TAX_REVENUE_PER_CAPITA_ANNUAL[techEra]  (default 0)
+ *   stabilityMul      = SCALE.Q/2 + mulDiv(SCALE.Q/2, stabilityQ, SCALE.Q)
+ *                     ∈ [5000, 10000] = [q(0.50), q(1.00)]
+ *   gross             = taxablePopulation × perCapita × taxRate / SCALE.Q
+ *   annual            = round(gross × stabilityMul / SCALE.Q)
+ *
+ * Stability models collection efficiency: a fractured polity cannot collect
+ * the full assessed tax.  At zero stability, only half the theoretical
+ * revenue is gathered.
+ */
+export function computeAnnualTaxRevenue(polity, policy) {
+    const perCapita = TAX_REVENUE_PER_CAPITA_ANNUAL[polity.techEra] ?? 0;
+    if (perCapita === 0)
+        return 0;
+    const exempt = policy.exemptFraction_Q ?? 0;
+    const taxablePop = Math.round(polity.population * (SCALE.Q - exempt) / SCALE.Q);
+    const gross = Math.round(taxablePop * perCapita * policy.taxRate_Q / SCALE.Q);
+    const stabilityMul = SCALE.Q / 2 + mulDiv(SCALE.Q / 2, polity.stabilityQ, SCALE.Q);
+    return Math.max(0, Math.round(gross * stabilityMul / SCALE.Q));
+}
+/**
+ * Compute daily tax revenue [cost-units/day].
+ * Derived from `computeAnnualTaxRevenue` with day-fraction rounding.
+ */
+export function computeDailyTaxRevenue(polity, policy) {
+    const annual = computeAnnualTaxRevenue(polity, policy);
+    return Math.max(0, Math.round(annual / 365));
+}
+/**
+ * Compute the unrest pressure generated by the current tax rate [Q].
+ *
+ * - At or below `OPTIMAL_TAX_RATE_Q`: pressure = 0.
+ * - Between OPTIMAL and MAX_TAX_RATE_Q: linear ramp 0 → MAX_TAX_UNREST_Q.
+ * - At or above MAX_TAX_RATE_Q: pressure = MAX_TAX_UNREST_Q.
+ *
+ * Pass the result as an extra additive unrest factor to Phase-90
+ * `computeUnrestLevel`.
+ */
+export function computeTaxUnrestPressure(policy) {
+    if (policy.taxRate_Q <= OPTIMAL_TAX_RATE_Q)
+        return 0;
+    const excess = policy.taxRate_Q - OPTIMAL_TAX_RATE_Q;
+    const range = MAX_TAX_RATE_Q - OPTIMAL_TAX_RATE_Q;
+    const frac = clampQ(Math.round(excess * SCALE.Q / range), 0, SCALE.Q);
+    return clampQ(Math.round(frac * MAX_TAX_UNREST_Q / SCALE.Q), 0, MAX_TAX_UNREST_Q);
+}
+// ── Treasury step ─────────────────────────────────────────────────────────────
+/**
+ * Collect taxes for `elapsedDays` days and add to `polity.treasury_cu`.
+ *
+ * Mutates `polity.treasury_cu`.
+ *
+ * @returns Revenue added and the unrest pressure the current rate generates.
+ */
+export function stepTaxCollection(polity, policy, elapsedDays) {
+    const annual = computeAnnualTaxRevenue(polity, policy);
+    const revenue_cu = Math.max(0, Math.round(annual * elapsedDays / 365));
+    polity.treasury_cu += revenue_cu;
+    const unrestPressure_Q = computeTaxUnrestPressure(policy);
+    return { revenue_cu, unrestPressure_Q };
+}
+// ── Reporting ─────────────────────────────────────────────────────────────────
+/**
+ * Estimate how many days until the treasury reaches a target amount at the
+ * current daily tax revenue.  Returns `Infinity` if daily revenue is zero.
+ */
+export function estimateDaysToTreasuryTarget(polity, policy, targetAmount) {
+    const daily = computeDailyTaxRevenue(polity, policy);
+    if (daily <= 0)
+        return Infinity;
+    const needed = Math.max(0, targetAmount - polity.treasury_cu);
+    if (needed === 0)
+        return 0;
+    return Math.ceil(needed / daily);
+}
+/**
+ * Compute the effective tax rate needed to hit a desired annual revenue,
+ * clamped to [0, MAX_TAX_RATE_Q].
+ *
+ * Useful for host AI: "what rate do I need to fund X?"
+ *
+ * Returns MAX_TAX_RATE_Q if the desired revenue exceeds what full taxation
+ * can provide.
+ */
+export function computeRequiredTaxRate(polity, desiredAnnual) {
+    const perCapita = TAX_REVENUE_PER_CAPITA_ANNUAL[polity.techEra] ?? 0;
+    if (perCapita === 0 || polity.population === 0)
+        return MAX_TAX_RATE_Q;
+    const stabilityMul = SCALE.Q / 2 + mulDiv(SCALE.Q / 2, polity.stabilityQ, SCALE.Q);
+    // reverse-solve: rate = desiredAnnual × SCALE.Q² / (population × perCapita × stabilityMul)
+    const numerator = desiredAnnual * SCALE.Q * SCALE.Q;
+    const denominator = polity.population * perCapita * stabilityMul;
+    if (denominator <= 0)
+        return MAX_TAX_RATE_Q;
+    const rate = Math.ceil(numerator / denominator);
+    return clampQ(rate, 0, MAX_TAX_RATE_Q);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@its-not-rocket-science/ananke",
-  "version": "0.1.36",
+  "version": "0.1.39",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",
@@ -130,6 +130,18 @@
     "./research": {
       "import": "./dist/src/research.js",
       "types": "./dist/src/research.d.ts"
+    },
+    "./taxation": {
+      "import": "./dist/src/taxation.js",
+      "types": "./dist/src/taxation.d.ts"
+    },
+    "./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"
     }
   },
   "files": [
@@ -150,7 +162,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",