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

package/CHANGELOG.md

@@ -6,6 +6,64 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [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
+
+- **Phase 91 · Technology Research** (`src/research.ts`)
+  - `ResearchState { polityId, progress }` — per-polity accumulator stored externally by the host.
+  - `RESEARCH_POINTS_REQUIRED: Record<number, number>` — numeric TechEra keys; Prehistoric 2 k → FarFuture 5 M; DeepSpace absent (no advancement).
+  - `computeDailyResearchPoints(polity, bonusPoints?)` → integer points/day: `baseUnits = max(1, floor(pop / RESEARCH_POP_DIVISOR=5000))`; `stabilityFactor ∈ [5000, 10000]`; `max(1, round(baseUnits × stabilityFactor / SCALE.Q)) + bonusPoints`.
+  - `stepResearch(polity, state, elapsedDays, bonusPoints?)` → `ResearchStepResult`: accumulates `daily × elapsedDays`; on threshold: increments `polity.techEra`, calls `deriveMilitaryStrength`, carries surplus; no-op at DeepSpace.
+  - `investInResearch(polity, state, amount)` — drains treasury at `RESEARCH_COST_PER_POINT = 10` cu/point; capped at available treasury; returns points added.
+  - `computeKnowledgeDiffusion(sourcePolity, targetPolity, contactIntensity_Q)` → bonus points/day: fires when `source.techEra > target.techEra`; `sourceDaily × eraDiff × KNOWLEDGE_DIFFUSION_RATE_Q(q(0.10)) × contactIntensity / SCALE.Q²`.
+  - `computeResearchProgress_Q(polity, state)` → Q [0, SCALE.Q]: fraction toward next era; SCALE.Q at DeepSpace.
+  - `estimateDaysToNextEra(polity, state, bonusPoints?)` → ceiling days; Infinity at DeepSpace or zero rate.
+  - Added `./research` subpath export to `package.json`.
+  - 57 new tests; 4,779 total. Coverage maintained above all thresholds.
+
+---
+
 ## [0.1.35] — 2026-03-26
 
 ### Added

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/research.d.ts

@@ -0,0 +1,103 @@
+import type { Q } from "./units.js";
+import type { Polity } from "./polity.js";
+/** Per-polity research progress. Store one externally per polity. */
+export interface ResearchState {
+    polityId: string;
+    /** Accumulated research points toward the next era. */
+    progress: number;
+}
+/** Result returned by `stepResearch`. */
+export interface ResearchStepResult {
+    /** Raw points added this step. */
+    pointsGained: number;
+    /** Whether the polity advanced to a new era this step. */
+    advanced: boolean;
+    /** New era if `advanced === true`, otherwise `undefined`. */
+    newEra?: number;
+}
+/**
+ * Population divisor for base daily research units.
+ * `baseUnits = floor(population / RESEARCH_POP_DIVISOR)` — minimum 1.
+ */
+export declare const RESEARCH_POP_DIVISOR = 5000;
+/**
+ * Research points required to advance FROM each TechEra to the next.
+ * Keyed by numeric TechEra value.  `Infinity` (absent) = max era, no advancement.
+ */
+export declare const RESEARCH_POINTS_REQUIRED: Record<number, number>;
+/**
+ * Treasury cost per research point when using `investInResearch`.
+ * 10 cost-units = 1 research point.
+ */
+export declare const RESEARCH_COST_PER_POINT = 10;
+/**
+ * Fraction of the source polity's daily research rate that diffuses to a
+ * less-advanced trade partner per era of difference.
+ */
+export declare const KNOWLEDGE_DIFFUSION_RATE_Q: Q;
+/** Create a fresh `ResearchState` with zero progress. */
+export declare function createResearchState(polityId: string): ResearchState;
+/**
+ * Points required to advance from the polity's current era.
+ * Returns `Infinity` at max era (no advancement possible).
+ */
+export declare function pointsRequiredForNextEra(polity: Polity): number;
+/**
+ * Compute the daily research rate for a polity [integer points/day].
+ *
+ * Formula:
+ *   baseUnits = max(1, floor(population / RESEARCH_POP_DIVISOR))
+ *   stabilityFactor = SCALE.Q/2 + mulDiv(SCALE.Q/2, stabilityQ, SCALE.Q)
+ *                   ∈ [q(0.50), q(1.00)] = [5000, 10000]
+ *   dailyPoints = max(1, round(baseUnits × stabilityFactor / SCALE.Q))
+ *
+ * @param bonusPoints  Additional flat bonus points per day (e.g., from
+ *                     knowledge diffusion or Phase-89 infrastructure).
+ */
+export declare function computeDailyResearchPoints(polity: Polity, bonusPoints?: number): number;
+/**
+ * Advance research for `elapsedDays` days.
+ *
+ * Adds `computeDailyResearchPoints(polity) × elapsedDays` to `state.progress`.
+ * When progress meets or exceeds `pointsRequiredForNextEra`:
+ * - Excess progress carries over.
+ * - `polity.techEra` is incremented.
+ * - `deriveMilitaryStrength` is refreshed.
+ *
+ * Only one era advancement occurs per call regardless of elapsed days.
+ * At DeepSpace (max era) the call is a no-op.
+ *
+ * @param bonusPoints  Flat daily bonus from knowledge diffusion or infrastructure.
+ */
+export declare function stepResearch(polity: Polity, state: ResearchState, elapsedDays: number, bonusPoints?: number): ResearchStepResult;
+/**
+ * Invest treasury into research, immediately adding points.
+ *
+ * Rate: `RESEARCH_COST_PER_POINT` cost-units = 1 point.
+ * Drains `min(amount, polity.treasury_cu)`.  No-ops if treasury is empty.
+ *
+ * Returns the actual number of research points added.
+ */
+export declare function investInResearch(polity: Polity, state: ResearchState, amount: number): number;
+/**
+ * Compute daily knowledge diffusion bonus that a source polity grants to a
+ * less-advanced target polity through trade or diplomatic contact.
+ *
+ * Diffusion fires only when `sourcePolity.techEra > targetPolity.techEra`.
+ *
+ * Formula: `round(sourceDaily × eraDiff × DIFFUSION_RATE × contactIntensity / SCALE.Q²)`
+ *
+ * @param contactIntensity_Q  Trade or diplomatic contact [0, SCALE.Q].
+ *                            Derive from Phase-83 route efficiency or Phase-80 treaty strength.
+ */
+export declare function computeKnowledgeDiffusion(sourcePolity: Polity, targetPolity: Polity, contactIntensity_Q: Q): number;
+/**
+ * Return current research progress as a Q fraction [0, SCALE.Q] toward the next era.
+ * Returns `SCALE.Q` at max era (DeepSpace).
+ */
+export declare function computeResearchProgress_Q(polity: Polity, state: ResearchState): Q;
+/**
+ * Estimate days until the next era advance at the current daily research rate.
+ * Returns `Infinity` at max era or when rate is zero.
+ */
+export declare function estimateDaysToNextEra(polity: Polity, state: ResearchState, bonusPoints?: number): number;

package/dist/src/research.js

@@ -0,0 +1,175 @@
+// src/research.ts — Phase 91: Technology Research
+//
+// Polities accumulate research points from their population and stability.
+// When accumulated points reach the era threshold the polity advances to the
+// next TechEra; treasury investment buys additional progress; contact with a
+// more advanced polity (via Phase-83 trade routes) grants knowledge diffusion.
+//
+// Design:
+//   - Pure data layer — no Entity fields, no kernel changes.
+//   - `ResearchState` is separate from Polity; host stores one per polity.
+//   - Uses numeric TechEra values (0–8) from Phase-11 tech.ts.
+//   - `stepResearch` mutates both `state.progress` and `polity.techEra`.
+//   - All arithmetic is integer fixed-point; no floating-point accumulation.
+//
+// Integration:
+//   Phase 11 (Tech):     TechEra numeric enum — advancement increments polity.techEra.
+//   Phase 61 (Polity):   population, stabilityQ, treasury_cu are read/mutated.
+//   Phase 83 (Trade):    contactIntensity_Q drives knowledge diffusion.
+//   Phase 89 (Infra):    hosts may add infrastructure bonuses to daily rate.
+import { q, SCALE, clampQ, mulDiv } from "./units.js";
+import { deriveMilitaryStrength } from "./polity.js";
+import { TechEra } from "./sim/tech.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/**
+ * Population divisor for base daily research units.
+ * `baseUnits = floor(population / RESEARCH_POP_DIVISOR)` — minimum 1.
+ */
+export const RESEARCH_POP_DIVISOR = 5_000;
+/**
+ * Research points required to advance FROM each TechEra to the next.
+ * Keyed by numeric TechEra value.  `Infinity` (absent) = max era, no advancement.
+ */
+export const RESEARCH_POINTS_REQUIRED = {
+    [TechEra.Prehistoric]: 2_000,
+    [TechEra.Ancient]: 8_000,
+    [TechEra.Medieval]: 30_000,
+    [TechEra.EarlyModern]: 80_000,
+    [TechEra.Industrial]: 200_000,
+    [TechEra.Modern]: 500_000,
+    [TechEra.NearFuture]: 1_500_000,
+    [TechEra.FarFuture]: 5_000_000,
+    // TechEra.DeepSpace (8): no entry → no advancement
+};
+/**
+ * Treasury cost per research point when using `investInResearch`.
+ * 10 cost-units = 1 research point.
+ */
+export const RESEARCH_COST_PER_POINT = 10;
+/**
+ * Fraction of the source polity's daily research rate that diffuses to a
+ * less-advanced trade partner per era of difference.
+ */
+export const KNOWLEDGE_DIFFUSION_RATE_Q = q(0.10);
+// ── Factory ───────────────────────────────────────────────────────────────────
+/** Create a fresh `ResearchState` with zero progress. */
+export function createResearchState(polityId) {
+    return { polityId, progress: 0 };
+}
+// ── Rate computation ──────────────────────────────────────────────────────────
+/**
+ * Points required to advance from the polity's current era.
+ * Returns `Infinity` at max era (no advancement possible).
+ */
+export function pointsRequiredForNextEra(polity) {
+    return RESEARCH_POINTS_REQUIRED[polity.techEra] ?? Infinity;
+}
+/**
+ * Compute the daily research rate for a polity [integer points/day].
+ *
+ * Formula:
+ *   baseUnits = max(1, floor(population / RESEARCH_POP_DIVISOR))
+ *   stabilityFactor = SCALE.Q/2 + mulDiv(SCALE.Q/2, stabilityQ, SCALE.Q)
+ *                   ∈ [q(0.50), q(1.00)] = [5000, 10000]
+ *   dailyPoints = max(1, round(baseUnits × stabilityFactor / SCALE.Q))
+ *
+ * @param bonusPoints  Additional flat bonus points per day (e.g., from
+ *                     knowledge diffusion or Phase-89 infrastructure).
+ */
+export function computeDailyResearchPoints(polity, bonusPoints = 0) {
+    const baseUnits = Math.max(1, Math.floor(polity.population / RESEARCH_POP_DIVISOR));
+    const stabilityFactor = SCALE.Q / 2 + mulDiv(SCALE.Q / 2, polity.stabilityQ, SCALE.Q);
+    const base = Math.max(1, Math.round(baseUnits * stabilityFactor / SCALE.Q));
+    return base + bonusPoints;
+}
+// ── Research step ─────────────────────────────────────────────────────────────
+/**
+ * Advance research for `elapsedDays` days.
+ *
+ * Adds `computeDailyResearchPoints(polity) × elapsedDays` to `state.progress`.
+ * When progress meets or exceeds `pointsRequiredForNextEra`:
+ * - Excess progress carries over.
+ * - `polity.techEra` is incremented.
+ * - `deriveMilitaryStrength` is refreshed.
+ *
+ * Only one era advancement occurs per call regardless of elapsed days.
+ * At DeepSpace (max era) the call is a no-op.
+ *
+ * @param bonusPoints  Flat daily bonus from knowledge diffusion or infrastructure.
+ */
+export function stepResearch(polity, state, elapsedDays, bonusPoints = 0) {
+    const daily = computeDailyResearchPoints(polity, bonusPoints);
+    const gained = daily * elapsedDays;
+    state.progress += gained;
+    const required = pointsRequiredForNextEra(polity);
+    const maxEra = TechEra.DeepSpace;
+    const canAdvance = polity.techEra < maxEra && isFinite(required) && state.progress >= required;
+    if (canAdvance) {
+        state.progress -= required; // carry over surplus
+        polity.techEra = (polity.techEra + 1);
+        deriveMilitaryStrength(polity);
+        return { pointsGained: gained, advanced: true, newEra: polity.techEra };
+    }
+    return { pointsGained: gained, advanced: false };
+}
+// ── Treasury investment ───────────────────────────────────────────────────────
+/**
+ * Invest treasury into research, immediately adding points.
+ *
+ * Rate: `RESEARCH_COST_PER_POINT` cost-units = 1 point.
+ * Drains `min(amount, polity.treasury_cu)`.  No-ops if treasury is empty.
+ *
+ * Returns the actual number of research points added.
+ */
+export function investInResearch(polity, state, amount) {
+    const actual = Math.min(amount, polity.treasury_cu);
+    const points = Math.floor(actual / RESEARCH_COST_PER_POINT);
+    polity.treasury_cu -= actual;
+    state.progress += points;
+    return points;
+}
+// ── Knowledge diffusion ───────────────────────────────────────────────────────
+/**
+ * Compute daily knowledge diffusion bonus that a source polity grants to a
+ * less-advanced target polity through trade or diplomatic contact.
+ *
+ * Diffusion fires only when `sourcePolity.techEra > targetPolity.techEra`.
+ *
+ * Formula: `round(sourceDaily × eraDiff × DIFFUSION_RATE × contactIntensity / SCALE.Q²)`
+ *
+ * @param contactIntensity_Q  Trade or diplomatic contact [0, SCALE.Q].
+ *                            Derive from Phase-83 route efficiency or Phase-80 treaty strength.
+ */
+export function computeKnowledgeDiffusion(sourcePolity, targetPolity, contactIntensity_Q) {
+    if (sourcePolity.techEra <= targetPolity.techEra)
+        return 0;
+    const eraDiff = sourcePolity.techEra - targetPolity.techEra;
+    const sourceRate = computeDailyResearchPoints(sourcePolity);
+    const step1 = mulDiv(sourceRate * eraDiff, KNOWLEDGE_DIFFUSION_RATE_Q, SCALE.Q);
+    return Math.max(0, Math.round(step1 * contactIntensity_Q / SCALE.Q));
+}
+// ── Progress reporting ────────────────────────────────────────────────────────
+/**
+ * Return current research progress as a Q fraction [0, SCALE.Q] toward the next era.
+ * Returns `SCALE.Q` at max era (DeepSpace).
+ */
+export function computeResearchProgress_Q(polity, state) {
+    const required = pointsRequiredForNextEra(polity);
+    if (!isFinite(required))
+        return SCALE.Q;
+    return clampQ(Math.round(state.progress * SCALE.Q / required), 0, SCALE.Q);
+}
+/**
+ * Estimate days until the next era advance at the current daily research rate.
+ * Returns `Infinity` at max era or when rate is zero.
+ */
+export function estimateDaysToNextEra(polity, state, bonusPoints = 0) {
+    const required = pointsRequiredForNextEra(polity);
+    if (!isFinite(required))
+        return Infinity;
+    const remaining = Math.max(0, required - state.progress);
+    const daily = computeDailyResearchPoints(polity, bonusPoints);
+    if (daily <= 0)
+        return Infinity;
+    return Math.ceil(remaining / daily);
+}

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.35",
+  "version": "0.1.38",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",
@@ -126,6 +126,18 @@
     "./unrest": {
       "import": "./dist/src/unrest.js",
       "types": "./dist/src/unrest.d.ts"
+    },
+    "./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"
     }
   },
   "files": [