@its-not-rocket-science/ananke 0.1.28 → 0.1.29

package/CHANGELOG.md

@@ -6,6 +6,29 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.29] — 2026-03-26
+
+### Added
+
+- **Phase 84 · Siege Warfare** (`src/siege.ts`)
+  - `SiegePhase`: `"investment" | "active" | "resolved"`.
+  - `SiegeOutcome`: `"attacker_victory" | "defender_holds" | "surrender"`.
+  - `SiegeState { siegeId, attackerPolityId, defenderPolityId, phase, startTick, phaseDay, wallIntegrity_Q, supplyLevel_Q, defenderMorale_Q, siegeStrength_Q, outcome? }`.
+  - `SiegeAttrition { attackerLoss_Q, defenderLoss_Q }` — daily fractional losses per phase.
+  - `createSiege(attackerPolity, defenderPolity, tick?)` — seeds from `militaryStrength_Q` and `stabilityQ`.
+  - **Investment phase** (`INVESTMENT_DAYS = 14`): encirclement; no bombardment or starvation yet.
+  - **Active phase**: wall decay = `siegeStrength_Q × WALL_DECAY_BASE_Q / SCALE.Q` per day; supply drains at `SUPPLY_DRAIN_PER_DAY_Q = q(0.004)`; morale tracks combined wall/supply weakness.
+  - **Assault**: fires when `wallIntegrity_Q < ASSAULT_WALL_THRESHOLD_Q = q(0.30)`; resolved by `eventSeed` roll weighted by siege strength and defender morale deficit.
+  - **Surrender**: fires when `supplyLevel_Q ≤ SURRENDER_SUPPLY_THRESHOLD_Q = q(0.05)` and daily probabilistic roll succeeds based on morale deficit.
+  - `stepSiege(siege, worldSeed, tick, supplyPressureBonus_Q?, siegeStrengthMul_Q?)` — Phase-83 (severed trade) and Phase-78 (winter penalty) integration via optional parameters.
+  - `computeSiegeAttrition(siege)` → `SiegeAttrition` — daily losses by phase.
+  - `runSiegeToResolution(siege, worldSeed, startTick, maxDays?)` — convenience runner.
+  - All outcomes deterministic and idempotent via `eventSeed`.
+  - Added `./siege` subpath export to `package.json`.
+  - 38 new tests; 4,465 total. Coverage maintained above all thresholds.
+
+---
+
 ## [0.1.28] — 2026-03-26
 
 ### Added

package/dist/src/faith.d.ts

@@ -0,0 +1,123 @@
+import type { Q } from "./units.js";
+export type FaithId = string;
+/** Definition of a named faith. */
+export interface Faith {
+    faithId: FaithId;
+    name: string;
+    /**
+     * Proselytising energy [0, SCALE.Q].
+     * Higher fervor → faster conversion spread into other polities.
+     */
+    fervor_Q: Q;
+    /**
+     * Tolerance for other faiths [0, SCALE.Q].
+     * Low tolerance → higher heresy risk when minority faiths are present.
+     */
+    tolerance_Q: Q;
+    /**
+     * Exclusive faiths (monotheistic) compete: gaining adherents displaces
+     * other exclusive faiths proportionally.
+     * Syncretic faiths are additive — populations can hold multiple.
+     */
+    exclusive: boolean;
+}
+/** Presence of one faith within a polity. */
+export interface PolityFaith {
+    polityId: string;
+    faithId: FaithId;
+    /** Fraction of population following this faith [0, SCALE.Q]. */
+    adherents_Q: Q;
+}
+/** Central registry: faith definitions + per-polity adherent records. */
+export interface FaithRegistry {
+    /** All defined faiths keyed by faithId. */
+    faiths: Map<FaithId, Faith>;
+    /** polityId → array of PolityFaith (one entry per faith present). */
+    polityFaiths: Map<string, PolityFaith[]>;
+}
+/** High-fervor monotheistic faith. */
+export declare const SOLAR_CHURCH: Faith;
+/** Low-fervor animistic syncretic faith. */
+export declare const EARTH_SPIRITS: Faith;
+/** Moderate syncretic merchant cult. */
+export declare const MERCHANT_CULT: Faith;
+/**
+ * Base daily conversion delta at full missionary presence and full source fervor.
+ * Actual delta = `fervor_Q × missionaryPresence_Q × CONVERSION_BASE_RATE_Q / SCALE.Q²`.
+ */
+export declare const CONVERSION_BASE_RATE_Q: Q;
+/**
+ * Minority exclusive faith presence above this fraction → heresy risk fires.
+ * `computeHeresyRisk` returns non-zero only when a minority exclusive faith
+ * exceeds this threshold in a polity whose dominant faith has low tolerance.
+ */
+export declare const HERESY_THRESHOLD_Q: Q;
+/** Diplomatic bonus (Q offset) when two polities share the same dominant faith. */
+export declare const FAITH_DIPLOMATIC_BONUS_Q: Q;
+/** Diplomatic penalty when polities hold exclusive faiths that conflict. */
+export declare const FAITH_DIPLOMATIC_PENALTY_Q: Q;
+export declare function createFaithRegistry(): FaithRegistry;
+/** Register or replace a faith definition. */
+export declare function registerFaith(registry: FaithRegistry, faith: Faith): void;
+/** Return the faith definition, or `undefined` if unknown. */
+export declare function getFaith(registry: FaithRegistry, faithId: FaithId): Faith | undefined;
+/** Return all faith records for a polity (empty array if none). */
+export declare function getPolityFaiths(registry: FaithRegistry, polityId: string): PolityFaith[];
+/**
+ * Set the adherent fraction for a faith in a polity.
+ * Creates the record if it does not exist; updates it if it does.
+ * Clamps `adherents_Q` to [0, SCALE.Q].
+ * Does NOT normalise other faiths — call `normalisePolitFaiths` if needed.
+ */
+export declare function setPolityFaith(registry: FaithRegistry, polityId: string, faithId: FaithId, adherents_Q: Q): PolityFaith;
+/** Return the faith with the highest adherents in a polity, or `undefined`. */
+export declare function getDominantFaith(registry: FaithRegistry, polityId: string): PolityFaith | undefined;
+/** Return `true` if both polities share the same dominant faithId. */
+export declare function sharesDominantFaith(registry: FaithRegistry, polityAId: string, polityBId: string): boolean;
+/**
+ * Compute the daily conversion pressure exerted on a target polity by a
+ * source faith's missionaries.
+ *
+ * Formula:
+ *   pressure = fervor_Q × missionaryPresence_Q × CONVERSION_BASE_RATE_Q / SCALE.Q²
+ *
+ * Returns 0 if the faith is not registered.
+ *
+ * @param missionaryPresence_Q  Strength of missionary activity [0, SCALE.Q].
+ *                              Callers may derive this from Phase-82 agent presence
+ *                              or Phase-83 trade route volume.
+ */
+export declare function computeConversionPressure(faith: Faith, missionaryPresence_Q: Q): Q;
+/**
+ * Apply a conversion delta to a polity.
+ *
+ * **Exclusive faiths**: gaining `delta_Q` adherents displaces all other
+ * *exclusive* faiths proportionally, preserving their relative sizes.
+ * Non-exclusive faiths in the polity are unaffected.
+ *
+ * **Syncretic faiths**: delta is added directly; no displacement occurs.
+ *
+ * All adherent_Q values are clamped to [0, SCALE.Q] after adjustment.
+ */
+export declare function stepFaithConversion(registry: FaithRegistry, polityId: string, faithId: FaithId, delta_Q: Q): void;
+/**
+ * Compute the heresy risk in a polity [0, SCALE.Q].
+ *
+ * Risk is non-zero when:
+ * - The dominant faith is exclusive and has low tolerance.
+ * - A minority exclusive faith exceeds `HERESY_THRESHOLD_Q`.
+ *
+ * Formula: `(minorityPresence - HERESY_THRESHOLD) × (SCALE.Q - tolerance) / SCALE.Q`
+ * summed over all qualifying minority faiths.
+ */
+export declare function computeHeresyRisk(registry: FaithRegistry, polityId: string): Q;
+/**
+ * Compute a signed Q diplomatic modifier from faith compatibility.
+ *
+ * - Shared dominant faith → `+FAITH_DIPLOMATIC_BONUS_Q`.
+ * - Both polities have exclusive dominant faiths that differ → `−FAITH_DIPLOMATIC_PENALTY_Q`.
+ * - Otherwise (syncretic or no dominant faith) → `0`.
+ *
+ * Hosts add this to treaty strength or faction standing adjustments.
+ */
+export declare function computeFaithDiplomaticModifier(registry: FaithRegistry, polityAId: string, polityBId: string): number;

package/dist/src/faith.js

@@ -0,0 +1,221 @@
+// src/faith.ts — Phase 85: Religion & Faith Systems
+//
+// Models named faiths and their presence in polities. Faith presence is
+// expressed as a Q fraction of the polity population. Exclusive faiths
+// (monotheistic) compete with each other; syncretic faiths stack additively.
+//
+// Design:
+//   - Pure data layer — no Entity fields, no kernel changes.
+//   - `FaithRegistry` stores faith definitions and per-polity adherent fractions.
+//   - Conversion pressure integrates with Phase-81 (migration drives faith spread)
+//     and Phase-80 (shared faith boosts treaty strength) via caller-supplied context.
+//   - Heresy risk integrates with Phase-82 (espionage can incite religious unrest).
+import { q, SCALE, clampQ, mulDiv } from "./units.js";
+// ── Built-in sample faiths ─────────────────────────────────────────────────────
+/** High-fervor monotheistic faith. */
+export const SOLAR_CHURCH = {
+    faithId: "solar_church",
+    name: "The Solar Church",
+    fervor_Q: q(0.80),
+    tolerance_Q: q(0.20),
+    exclusive: true,
+};
+/** Low-fervor animistic syncretic faith. */
+export const EARTH_SPIRITS = {
+    faithId: "earth_spirits",
+    name: "Earth Spirits",
+    fervor_Q: q(0.30),
+    tolerance_Q: q(0.90),
+    exclusive: false,
+};
+/** Moderate syncretic merchant cult. */
+export const MERCHANT_CULT = {
+    faithId: "merchant_cult",
+    name: "Merchant Cult",
+    fervor_Q: q(0.50),
+    tolerance_Q: q(0.70),
+    exclusive: false,
+};
+// ── Constants ─────────────────────────────────────────────────────────────────
+/**
+ * Base daily conversion delta at full missionary presence and full source fervor.
+ * Actual delta = `fervor_Q × missionaryPresence_Q × CONVERSION_BASE_RATE_Q / SCALE.Q²`.
+ */
+export const CONVERSION_BASE_RATE_Q = q(0.002);
+/**
+ * Minority exclusive faith presence above this fraction → heresy risk fires.
+ * `computeHeresyRisk` returns non-zero only when a minority exclusive faith
+ * exceeds this threshold in a polity whose dominant faith has low tolerance.
+ */
+export const HERESY_THRESHOLD_Q = q(0.15);
+/** Diplomatic bonus (Q offset) when two polities share the same dominant faith. */
+export const FAITH_DIPLOMATIC_BONUS_Q = q(0.10);
+/** Diplomatic penalty when polities hold exclusive faiths that conflict. */
+export const FAITH_DIPLOMATIC_PENALTY_Q = q(0.10);
+// ── Factory ───────────────────────────────────────────────────────────────────
+export function createFaithRegistry() {
+    return { faiths: new Map(), polityFaiths: new Map() };
+}
+// ── Faith management ───────────────────────────────────────────────────────────
+/** Register or replace a faith definition. */
+export function registerFaith(registry, faith) {
+    registry.faiths.set(faith.faithId, faith);
+}
+/** Return the faith definition, or `undefined` if unknown. */
+export function getFaith(registry, faithId) {
+    return registry.faiths.get(faithId);
+}
+// ── Polity faith records ───────────────────────────────────────────────────────
+/** Return all faith records for a polity (empty array if none). */
+export function getPolityFaiths(registry, polityId) {
+    return registry.polityFaiths.get(polityId) ?? [];
+}
+/**
+ * Set the adherent fraction for a faith in a polity.
+ * Creates the record if it does not exist; updates it if it does.
+ * Clamps `adherents_Q` to [0, SCALE.Q].
+ * Does NOT normalise other faiths — call `normalisePolitFaiths` if needed.
+ */
+export function setPolityFaith(registry, polityId, faithId, adherents_Q) {
+    const clamped = clampQ(adherents_Q, 0, SCALE.Q);
+    let list = registry.polityFaiths.get(polityId);
+    if (!list) {
+        list = [];
+        registry.polityFaiths.set(polityId, list);
+    }
+    const existing = list.find(pf => pf.faithId === faithId);
+    if (existing) {
+        existing.adherents_Q = clamped;
+        return existing;
+    }
+    const pf = { polityId, faithId, adherents_Q: clamped };
+    list.push(pf);
+    return pf;
+}
+/** Return the faith with the highest adherents in a polity, or `undefined`. */
+export function getDominantFaith(registry, polityId) {
+    const list = getPolityFaiths(registry, polityId);
+    if (list.length === 0)
+        return undefined;
+    return list.reduce((best, pf) => pf.adherents_Q > best.adherents_Q ? pf : best);
+}
+/** Return `true` if both polities share the same dominant faithId. */
+export function sharesDominantFaith(registry, polityAId, polityBId) {
+    const a = getDominantFaith(registry, polityAId);
+    const b = getDominantFaith(registry, polityBId);
+    return a != null && b != null && a.faithId === b.faithId;
+}
+// ── Conversion mechanics ───────────────────────────────────────────────────────
+/**
+ * Compute the daily conversion pressure exerted on a target polity by a
+ * source faith's missionaries.
+ *
+ * Formula:
+ *   pressure = fervor_Q × missionaryPresence_Q × CONVERSION_BASE_RATE_Q / SCALE.Q²
+ *
+ * Returns 0 if the faith is not registered.
+ *
+ * @param missionaryPresence_Q  Strength of missionary activity [0, SCALE.Q].
+ *                              Callers may derive this from Phase-82 agent presence
+ *                              or Phase-83 trade route volume.
+ */
+export function computeConversionPressure(faith, missionaryPresence_Q) {
+    const step1 = mulDiv(faith.fervor_Q, missionaryPresence_Q, SCALE.Q);
+    return clampQ(mulDiv(step1, CONVERSION_BASE_RATE_Q, SCALE.Q), 0, SCALE.Q);
+}
+/**
+ * Apply a conversion delta to a polity.
+ *
+ * **Exclusive faiths**: gaining `delta_Q` adherents displaces all other
+ * *exclusive* faiths proportionally, preserving their relative sizes.
+ * Non-exclusive faiths in the polity are unaffected.
+ *
+ * **Syncretic faiths**: delta is added directly; no displacement occurs.
+ *
+ * All adherent_Q values are clamped to [0, SCALE.Q] after adjustment.
+ */
+export function stepFaithConversion(registry, polityId, faithId, delta_Q) {
+    if (delta_Q === 0)
+        return;
+    const faith = registry.faiths.get(faithId);
+    const list = getPolityFaiths(registry, polityId);
+    // Ensure target record exists
+    let target = list.find(pf => pf.faithId === faithId);
+    if (!target) {
+        target = { polityId, faithId, adherents_Q: 0 };
+        list.push(target);
+        if (!registry.polityFaiths.has(polityId))
+            registry.polityFaiths.set(polityId, list);
+    }
+    const newTarget = clampQ(target.adherents_Q + delta_Q, 0, SCALE.Q);
+    const actualDelta = newTarget - target.adherents_Q;
+    target.adherents_Q = newTarget;
+    // Displace other exclusive faiths proportionally
+    if (faith?.exclusive && actualDelta > 0) {
+        const others = list.filter(pf => pf.faithId !== faithId && registry.faiths.get(pf.faithId)?.exclusive);
+        const totalOther = others.reduce((s, pf) => s + pf.adherents_Q, 0);
+        if (totalOther > 0) {
+            for (const other of others) {
+                const displaced = mulDiv(actualDelta, other.adherents_Q, totalOther);
+                other.adherents_Q = clampQ(other.adherents_Q - displaced, 0, SCALE.Q);
+            }
+        }
+    }
+}
+// ── Heresy risk ────────────────────────────────────────────────────────────────
+/**
+ * Compute the heresy risk in a polity [0, SCALE.Q].
+ *
+ * Risk is non-zero when:
+ * - The dominant faith is exclusive and has low tolerance.
+ * - A minority exclusive faith exceeds `HERESY_THRESHOLD_Q`.
+ *
+ * Formula: `(minorityPresence - HERESY_THRESHOLD) × (SCALE.Q - tolerance) / SCALE.Q`
+ * summed over all qualifying minority faiths.
+ */
+export function computeHeresyRisk(registry, polityId) {
+    const list = getPolityFaiths(registry, polityId);
+    const dominant = getDominantFaith(registry, polityId);
+    if (!dominant)
+        return 0;
+    const domFaith = registry.faiths.get(dominant.faithId);
+    if (!domFaith?.exclusive)
+        return 0; // syncretic dominants don't declare heresy
+    let risk = 0;
+    for (const pf of list) {
+        if (pf.faithId === dominant.faithId)
+            continue;
+        const minFaith = registry.faiths.get(pf.faithId);
+        if (!minFaith?.exclusive)
+            continue; // syncretic minorities are tolerated
+        if (pf.adherents_Q <= HERESY_THRESHOLD_Q)
+            continue;
+        const excess = pf.adherents_Q - HERESY_THRESHOLD_Q;
+        const intolerance = SCALE.Q - domFaith.tolerance_Q;
+        risk += mulDiv(excess, intolerance, SCALE.Q);
+    }
+    return clampQ(risk, 0, SCALE.Q);
+}
+// ── Diplomatic faith modifier ──────────────────────────────────────────────────
+/**
+ * Compute a signed Q diplomatic modifier from faith compatibility.
+ *
+ * - Shared dominant faith → `+FAITH_DIPLOMATIC_BONUS_Q`.
+ * - Both polities have exclusive dominant faiths that differ → `−FAITH_DIPLOMATIC_PENALTY_Q`.
+ * - Otherwise (syncretic or no dominant faith) → `0`.
+ *
+ * Hosts add this to treaty strength or faction standing adjustments.
+ */
+export function computeFaithDiplomaticModifier(registry, polityAId, polityBId) {
+    const a = getDominantFaith(registry, polityAId);
+    const b = getDominantFaith(registry, polityBId);
+    if (!a || !b)
+        return 0;
+    if (a.faithId === b.faithId)
+        return FAITH_DIPLOMATIC_BONUS_Q;
+    const faithA = registry.faiths.get(a.faithId);
+    const faithB = registry.faiths.get(b.faithId);
+    if (faithA?.exclusive && faithB?.exclusive)
+        return -FAITH_DIPLOMATIC_PENALTY_Q;
+    return 0;
+}

package/dist/src/siege.d.ts

@@ -0,0 +1,112 @@
+import type { Polity } from "./polity.js";
+import type { Q } from "./units.js";
+/**
+ * Phase of the siege.
+ *
+ * - `"investment"` — attacker encircles; supply lines not yet fully cut; no bombardment.
+ * - `"active"`     — bombardment + starvation running in parallel.
+ * - `"resolved"`   — siege ended; `outcome` is set.
+ */
+export type SiegePhase = "investment" | "active" | "resolved";
+/**
+ * How the siege ended.
+ *
+ * - `"attacker_victory"` — walls breached and assault succeeded.
+ * - `"defender_holds"`   — assault repelled; walls partially repaired.
+ * - `"surrender"`        — defender ran out of supply and capitulated.
+ */
+export type SiegeOutcome = "attacker_victory" | "defender_holds" | "surrender";
+/** Live state of an ongoing or resolved siege. */
+export interface SiegeState {
+    siegeId: string;
+    attackerPolityId: string;
+    defenderPolityId: string;
+    phase: SiegePhase;
+    /** Simulation tick (day) when the siege began. */
+    startTick: number;
+    /** Days elapsed in the current phase. */
+    phaseDay: number;
+    /** Defender fortification integrity [0, SCALE.Q]. Decays under bombardment. */
+    wallIntegrity_Q: Q;
+    /** Defender garrison supplies [0, SCALE.Q]. Drains each active day. */
+    supplyLevel_Q: Q;
+    /** Defender garrison morale [0, SCALE.Q]. Falls with supply and wall damage. */
+    defenderMorale_Q: Q;
+    /**
+     * Attacker siege capability [0, SCALE.Q].
+     * Derived from attacker `militaryStrength_Q`; governs wall-decay rate.
+     */
+    siegeStrength_Q: Q;
+    /** Set when `phase === "resolved"`. */
+    outcome?: SiegeOutcome;
+}
+/** Result of advancing the siege by one day. */
+export interface SiegeStepResult {
+    phaseChanged: boolean;
+    resolved: boolean;
+    outcome?: SiegeOutcome;
+}
+/** Daily attrition rates for both sides. */
+export interface SiegeAttrition {
+    /** Fraction of attacker force lost per day [0, SCALE.Q]. */
+    attackerLoss_Q: Q;
+    /** Fraction of defender force lost per day [0, SCALE.Q]. */
+    defenderLoss_Q: Q;
+}
+/** Days spent in the investment phase before active bombardment/starvation begins. */
+export declare const INVESTMENT_DAYS = 14;
+/**
+ * Base wall decay per active day at maximum siege strength.
+ * Actual decay = `siegeStrength_Q × WALL_DECAY_BASE_Q / SCALE.Q`.
+ */
+export declare const WALL_DECAY_BASE_Q: Q;
+/** Supply drain per active day (independent of attacker strength). */
+export declare const SUPPLY_DRAIN_PER_DAY_Q: Q;
+/** Rate at which defender morale decays relative to combined wall/supply weakness. */
+export declare const MORALE_DECAY_RATE_Q: Q;
+/** Wall integrity below this → assault is triggered and resolved. */
+export declare const ASSAULT_WALL_THRESHOLD_Q: Q;
+/**
+ * Base assault success probability at equal siege strength and full defender morale.
+ * Actual chance boosted by `(SCALE.Q - defenderMorale_Q) × 0.30`.
+ */
+export declare const ASSAULT_SUCCESS_BASE_Q: Q;
+/** Supply below this → daily surrender check fires. */
+export declare const SURRENDER_SUPPLY_THRESHOLD_Q: Q;
+/**
+ * Create a new siege. `attackerPolity.militaryStrength_Q` sets siege strength;
+ * `defenderPolity.stabilityQ` seeds defender morale.
+ */
+export declare function createSiege(attackerPolity: Polity, defenderPolity: Polity, tick?: number): SiegeState;
+/** Return `true` if the siege has ended. */
+export declare function isSiegeResolved(siege: SiegeState): boolean;
+/**
+ * Compute daily attrition fractions for both sides in the current phase.
+ * - Investment: minimal skirmishing losses.
+ * - Active: attacker takes defensive fire; defender takes bombardment damage.
+ * - Resolved: no attrition.
+ */
+export declare function computeSiegeAttrition(siege: SiegeState): SiegeAttrition;
+/**
+ * Advance the siege by one simulated day.
+ *
+ * **Investment phase**: counts down `INVESTMENT_DAYS` then transitions to active.
+ *
+ * **Active phase** (each day):
+ * 1. Decay `wallIntegrity_Q` by `siegeStrength_Q × WALL_DECAY_BASE_Q / SCALE.Q`.
+ * 2. Drain `supplyLevel_Q` by `SUPPLY_DRAIN_PER_DAY_Q` (+ optional `supplyPressureBonus_Q`).
+ * 3. Decay `defenderMorale_Q` proportionally to combined wall/supply weakness.
+ * 4. If `wallIntegrity_Q < ASSAULT_WALL_THRESHOLD_Q` → resolve assault via `eventSeed`.
+ * 5. Else if `supplyLevel_Q ≤ SURRENDER_SUPPLY_THRESHOLD_Q` → daily surrender roll.
+ *
+ * @param worldSeed            Global world seed for determinism.
+ * @param tick                 Current simulation tick.
+ * @param supplyPressureBonus_Q Extra daily supply drain (e.g., trade routes severed by Phase 83).
+ * @param siegeStrengthMul_Q   Multiplier on siege strength (e.g., winter penalty from Phase 78).
+ */
+export declare function stepSiege(siege: SiegeState, worldSeed: number, tick: number, supplyPressureBonus_Q?: Q, siegeStrengthMul_Q?: Q): SiegeStepResult;
+/**
+ * Run the siege forward until resolved or `maxDays` have elapsed.
+ * Returns the final step result. Useful for tests and quick simulations.
+ */
+export declare function runSiegeToResolution(siege: SiegeState, worldSeed: number, startTick: number, maxDays?: number): SiegeStepResult;

package/dist/src/siege.js

@@ -0,0 +1,176 @@
+// src/siege.ts — Phase 84: Siege Warfare
+//
+// Models prolonged military operations against a fortified polity.
+// A siege progresses through two main phases — investment then active —
+// and resolves when walls are breached (assault) or supply is exhausted
+// (surrender). All random outcomes use eventSeed for determinism.
+//
+// Design:
+//   - Pure data layer — no Entity fields, no kernel changes.
+//   - `SiegeState` is mutable; `stepSiege` advances it one simulated day.
+//   - Wall decay scales with attacker siege strength (Phase-61 militaryStrength_Q).
+//   - Defender morale tracks supply level and wall integrity.
+//   - Integrates with Phase-83 (severing trade routes raises supply drain)
+//     and Phase-78 (winter reduces attacker siege strength) via caller-supplied deltas.
+import { eventSeed, hashString } from "./sim/seeds.js";
+import { q, SCALE, clampQ, mulDiv } from "./units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Days spent in the investment phase before active bombardment/starvation begins. */
+export const INVESTMENT_DAYS = 14;
+/**
+ * Base wall decay per active day at maximum siege strength.
+ * Actual decay = `siegeStrength_Q × WALL_DECAY_BASE_Q / SCALE.Q`.
+ */
+export const WALL_DECAY_BASE_Q = q(0.005);
+/** Supply drain per active day (independent of attacker strength). */
+export const SUPPLY_DRAIN_PER_DAY_Q = q(0.004);
+/** Rate at which defender morale decays relative to combined wall/supply weakness. */
+export const MORALE_DECAY_RATE_Q = q(0.002);
+/** Wall integrity below this → assault is triggered and resolved. */
+export const ASSAULT_WALL_THRESHOLD_Q = q(0.30);
+/**
+ * Base assault success probability at equal siege strength and full defender morale.
+ * Actual chance boosted by `(SCALE.Q - defenderMorale_Q) × 0.30`.
+ */
+export const ASSAULT_SUCCESS_BASE_Q = q(0.50);
+/** Supply below this → daily surrender check fires. */
+export const SURRENDER_SUPPLY_THRESHOLD_Q = q(0.05);
+// ── eventSeed salts ───────────────────────────────────────────────────────────
+const ASSAULT_SALT = 1111;
+const SURRENDER_SALT = 2222;
+// ── Factory ───────────────────────────────────────────────────────────────────
+/**
+ * Create a new siege. `attackerPolity.militaryStrength_Q` sets siege strength;
+ * `defenderPolity.stabilityQ` seeds defender morale.
+ */
+export function createSiege(attackerPolity, defenderPolity, tick = 0) {
+    return {
+        siegeId: `${attackerPolity.id}:${defenderPolity.id}:${tick}`,
+        attackerPolityId: attackerPolity.id,
+        defenderPolityId: defenderPolity.id,
+        phase: "investment",
+        startTick: tick,
+        phaseDay: 0,
+        wallIntegrity_Q: SCALE.Q,
+        supplyLevel_Q: SCALE.Q,
+        defenderMorale_Q: clampQ(defenderPolity.stabilityQ, 0, SCALE.Q),
+        siegeStrength_Q: clampQ(attackerPolity.militaryStrength_Q, 0, SCALE.Q),
+    };
+}
+// ── Query helpers ──────────────────────────────────────────────────────────────
+/** Return `true` if the siege has ended. */
+export function isSiegeResolved(siege) {
+    return siege.phase === "resolved";
+}
+/**
+ * Compute daily attrition fractions for both sides in the current phase.
+ * - Investment: minimal skirmishing losses.
+ * - Active: attacker takes defensive fire; defender takes bombardment damage.
+ * - Resolved: no attrition.
+ */
+export function computeSiegeAttrition(siege) {
+    if (siege.phase === "investment") {
+        return { attackerLoss_Q: q(0.001), defenderLoss_Q: q(0.001) };
+    }
+    if (siege.phase === "active") {
+        // Attacker losses grow as walls fall (defenders become desperate)
+        const attackerLoss = clampQ(mulDiv(SCALE.Q - siege.wallIntegrity_Q, q(0.003), SCALE.Q) + q(0.001), 0, SCALE.Q);
+        // Defender losses from bombardment scale with siege strength
+        const defenderLoss = clampQ(mulDiv(siege.siegeStrength_Q, q(0.002), SCALE.Q), 0, SCALE.Q);
+        return { attackerLoss_Q: attackerLoss, defenderLoss_Q: defenderLoss };
+    }
+    return { attackerLoss_Q: 0, defenderLoss_Q: 0 };
+}
+// ── Siege progression ──────────────────────────────────────────────────────────
+/**
+ * Advance the siege by one simulated day.
+ *
+ * **Investment phase**: counts down `INVESTMENT_DAYS` then transitions to active.
+ *
+ * **Active phase** (each day):
+ * 1. Decay `wallIntegrity_Q` by `siegeStrength_Q × WALL_DECAY_BASE_Q / SCALE.Q`.
+ * 2. Drain `supplyLevel_Q` by `SUPPLY_DRAIN_PER_DAY_Q` (+ optional `supplyPressureBonus_Q`).
+ * 3. Decay `defenderMorale_Q` proportionally to combined wall/supply weakness.
+ * 4. If `wallIntegrity_Q < ASSAULT_WALL_THRESHOLD_Q` → resolve assault via `eventSeed`.
+ * 5. Else if `supplyLevel_Q ≤ SURRENDER_SUPPLY_THRESHOLD_Q` → daily surrender roll.
+ *
+ * @param worldSeed            Global world seed for determinism.
+ * @param tick                 Current simulation tick.
+ * @param supplyPressureBonus_Q Extra daily supply drain (e.g., trade routes severed by Phase 83).
+ * @param siegeStrengthMul_Q   Multiplier on siege strength (e.g., winter penalty from Phase 78).
+ */
+export function stepSiege(siege, worldSeed, tick, supplyPressureBonus_Q = 0, siegeStrengthMul_Q = SCALE.Q) {
+    if (siege.phase === "resolved") {
+        return { phaseChanged: false, resolved: true, ...(siege.outcome != null ? { outcome: siege.outcome } : {}) };
+    }
+    // ── Investment phase ────────────────────────────────────────────────────────
+    if (siege.phase === "investment") {
+        siege.phaseDay++;
+        if (siege.phaseDay >= INVESTMENT_DAYS) {
+            siege.phase = "active";
+            siege.phaseDay = 0;
+            return { phaseChanged: true, resolved: false };
+        }
+        return { phaseChanged: false, resolved: false };
+    }
+    // ── Active phase ────────────────────────────────────────────────────────────
+    const effectiveSiegeStr = clampQ(mulDiv(siege.siegeStrength_Q, siegeStrengthMul_Q, SCALE.Q), 0, SCALE.Q);
+    // 1. Wall decay
+    const wallDecay = mulDiv(effectiveSiegeStr, WALL_DECAY_BASE_Q, SCALE.Q);
+    siege.wallIntegrity_Q = clampQ(siege.wallIntegrity_Q - wallDecay, 0, SCALE.Q);
+    // 2. Supply drain (base + bonus from severed trade routes etc.)
+    const totalDrain = clampQ(SUPPLY_DRAIN_PER_DAY_Q + supplyPressureBonus_Q, 0, SCALE.Q);
+    siege.supplyLevel_Q = clampQ(siege.supplyLevel_Q - totalDrain, 0, SCALE.Q);
+    // 3. Morale decay — weighted average of supply and wall weakness
+    const wallWeakness = SCALE.Q - siege.wallIntegrity_Q;
+    const supplyWeakness = SCALE.Q - siege.supplyLevel_Q;
+    const avgWeakness = Math.round((wallWeakness + supplyWeakness) / 2);
+    const moraleDecay = mulDiv(avgWeakness, MORALE_DECAY_RATE_Q, SCALE.Q);
+    siege.defenderMorale_Q = clampQ(siege.defenderMorale_Q - moraleDecay, 0, SCALE.Q);
+    siege.phaseDay++;
+    // 4. Assault trigger (walls breached)
+    if (siege.wallIntegrity_Q < ASSAULT_WALL_THRESHOLD_Q) {
+        const seed = eventSeed(worldSeed, tick, hashString(siege.attackerPolityId), hashString(siege.defenderPolityId), ASSAULT_SALT);
+        const roll = seed % SCALE.Q;
+        // Attacker advantage = base success + morale deficit bonus
+        const moraleDeficitBonus = mulDiv(SCALE.Q - siege.defenderMorale_Q, q(0.30), SCALE.Q);
+        const successThresh = clampQ(mulDiv(effectiveSiegeStr, ASSAULT_SUCCESS_BASE_Q, SCALE.Q) + moraleDeficitBonus, 0, SCALE.Q);
+        if (roll < successThresh) {
+            siege.outcome = "attacker_victory";
+        }
+        else {
+            // Defenders plug the breach
+            siege.wallIntegrity_Q = clampQ(siege.wallIntegrity_Q + q(0.15), 0, SCALE.Q);
+            siege.outcome = "defender_holds";
+        }
+        siege.phase = "resolved";
+        return { phaseChanged: true, resolved: true, outcome: siege.outcome };
+    }
+    // 5. Surrender check (supply exhausted)
+    if (siege.supplyLevel_Q <= SURRENDER_SUPPLY_THRESHOLD_Q) {
+        const seed = eventSeed(worldSeed, tick, hashString(siege.defenderPolityId), hashString(siege.attackerPolityId), SURRENDER_SALT);
+        const roll = seed % SCALE.Q;
+        // Surrender chance = morale deficit × 0.70
+        const surrenderChance = mulDiv(SCALE.Q - siege.defenderMorale_Q, q(0.70), SCALE.Q);
+        if (roll < surrenderChance) {
+            siege.phase = "resolved";
+            siege.outcome = "surrender";
+            return { phaseChanged: true, resolved: true, outcome: "surrender" };
+        }
+    }
+    return { phaseChanged: false, resolved: false };
+}
+// ── Convenience helpers ────────────────────────────────────────────────────────
+/**
+ * Run the siege forward until resolved or `maxDays` have elapsed.
+ * Returns the final step result. Useful for tests and quick simulations.
+ */
+export function runSiegeToResolution(siege, worldSeed, startTick, maxDays = 500) {
+    let result = { phaseChanged: false, resolved: false };
+    for (let d = 0; d < maxDays; d++) {
+        result = stepSiege(siege, worldSeed, startTick + d);
+        if (result.resolved)
+            break;
+    }
+    return result;
+}

package/package.json

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