@its-not-rocket-science/ananke 0.1.43 → 0.1.46

package/CHANGELOG.md

@@ -6,6 +6,82 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.46] — 2026-03-27
+
+### Added
+
+- **Phase 101 · Currency & Monetary Policy** (`src/monetary.ts`)
+  - `CoinagePolicy`: `"stable" | "slight_debasement" | "heavy_debasement" | "emergency_printing"`.
+  - `MonetaryState { polityId, coinPurity_Q, inflationLevel_Q, monetaryCrisis }` — per-polity mutable tracker stored externally.
+  - `coinPurity_Q` [0, SCALE.Q]: intrinsic metal content; trade partners check this. Starts at SCALE.Q.
+  - `inflationLevel_Q` [0, SCALE.Q]: accumulated price inflation; drives purchasing power loss and unrest. Starts at 0.
+  - `monetaryCrisis`: activates when `inflationLevel_Q >= MONETARY_CRISIS_THRESHOLD_Q = q(0.60)`.
+  - `POLICY_PURITY_DELTA_PER_DAY`: stable +3 (recovery) → emergency_printing −40/day.
+  - `POLICY_INFLATION_DELTA_PER_DAY`: stable −3 (deflation) → emergency_printing +50/day.
+  - `POLICY_DAILY_MINT_FRAC_Q`: stable 0 → emergency_printing 30/SCALE.Q (+110%/year).
+  - `computePurchasingPower_Q(state)` → `coinPurity × (1 − inflation) / SCALE.Q`; floor q(0.05).
+  - `computeMonetaryTradeMultiplier_Q(state)` → `[MONETARY_TRADE_FLOOR_Q, SCALE.Q]`; based on purity; feeds Phase-92.
+  - `computeMonetaryUnrest_Q(state)` → `[0, MONETARY_MAX_UNREST_Q=q(0.25)]`; linear on inflation; feeds Phase-90.
+  - `computeDebasementGain_cu(polity, policy, elapsedDays)` → advisory preview of mint gain.
+  - `stepMonetary(polity, state, policy, elapsedDays)` — mints extra treasury, updates purity/inflation, sets crisis flag.
+  - `isMonetaryCrisis(state)` / `isCoinageSound(state, threshold_Q?)` — predicates.
+  - Added `./monetary` subpath export to `package.json`.
+  - 45 new tests; 5,261 total. Coverage: 100% statements/branches/functions/lines on `monetary.ts`.
+
+---
+
+## [0.1.45] — 2026-03-27
+
+### Added
+
+- **Phase 100 · Wonders & Monuments** (`src/wonders.ts`)
+  - `WonderType`: `"great_pyramid" | "colosseum" | "grand_library" | "great_wall" | "grand_harbour" | "aqueduct_system" | "grand_temple"`.
+  - `WonderProject { projectId, polityId, type, progress_Q, investedCost_cu, startTick }` — in-progress construction.
+  - `Wonder { wonderId, polityId, type, completedAtTick, damaged }` — completed monument.
+  - `WonderEffects { stabilityBonus_Q, moraleBonus_Q, researchPointBonus, unrestReduction_Q, tradeIncomeBonus_Q, defenseBonus_Q, epidemicResistance_Q }` — advisory bundle.
+  - `WONDER_BASE_COST_CU`: grand_library 150k → great_pyramid 1,000k cu.
+  - `WONDER_TYPICAL_DAYS`: grand_library 180 → great_pyramid 3,650 days (10 years).
+  - `WONDER_BASE_EFFECTS`: distinct niches — great_wall highest defense (q(0.20)), grand_harbour highest trade (q(0.25)), aqueduct_system highest epidemic resistance (q(0.15)), colosseum highest unrest reduction (q(0.12)), grand_library +3 RP/day, great_pyramid highest stability (q(0.08)).
+  - `WONDER_DAMAGED_EFFECT_MUL = q(0.50)` — damaged wonders provide half effects.
+  - `WONDER_REPAIR_COST_FRAC = q(0.25)` — repair costs 25% of base construction cost.
+  - `createWonderProject(projectId, polityId, type, startTick)` — factory.
+  - `contributeToWonder(project, polity, contribution_cu)` — deducts treasury, advances progress_Q; capped by treasury and remaining cost; returns new progress.
+  - `isWonderProjectComplete(project)` → `progress_Q >= SCALE.Q`.
+  - `completeWonder(project, tick)` → `Wonder`.
+  - `damageWonder(wonder)` — set by Phase-96 earthquake or Phase-93 siege callers.
+  - `repairWonder(wonder, polity)` → `boolean` — spends repair cost; returns false if funds insufficient.
+  - `computeWonderEffects(wonder)` — full or half effects based on damage state.
+  - `aggregateWonderEffects(wonders)` — sums Q fields (clamped to SCALE.Q); sums researchPointBonus uncapped.
+  - `isWonderIntact(wonder)` / `computeRepairCost(type)` — helpers.
+  - Added `./wonders` subpath export to `package.json`.
+  - 43 new tests; 5,216 total. Coverage: 100% statements/branches/functions/lines on `wonders.ts`.
+
+---
+
+## [0.1.44] — 2026-03-27
+
+### Added
+
+- **Phase 99 · Mercenaries & Hired Forces** (`src/mercenaries.ts`)
+  - `MercenaryBand { bandId, name, size, quality_Q, dailyWagePerSoldier_cu }` — immutable descriptor.
+  - `MercenaryContract { contractId, polityId, bandId, daysActive, loyalty_Q, arrears_cu }` — mutable live state stored externally.
+  - `MercenaryStepResult { wagePaid_cu, arrearsAdded_cu, loyaltyDelta, deserted }` — step outcome.
+  - `DESERT_LOYALTY_THRESHOLD_Q = q(0.25)` — below this, desertion roll fires.
+  - `LOYALTY_DECAY_PER_DAY_UNPAID = 80` — loyalty drops 0.8%/day when wages owed.
+  - `LOYALTY_GROWTH_PER_DAY_PAID = 20` — loyalty grows 0.2%/day when fully paid.
+  - `MAX_MERC_STRENGTH_BONUS_Q = q(0.30)` — caps advisory strength contribution.
+  - `computeMercenaryWage(band, elapsedDays)` — `size × dailyWage × days`.
+  - `computeMercenaryStrengthContribution(band, contract)` → Q — `size × quality × loyalty / SCALE.Q²`; capped at q(0.30); add to Phase-93 battle strength.
+  - `stepMercenaryContract(contract, band, polity, elapsedDays, worldSeed, tick)` — pays wages from treasury, accrues arrears, grows/decays loyalty, rolls desertion via `eventSeed` (deterministic).
+  - `applyVictoryLoyaltyBonus(contract)` — q(0.10) boost after campaign victory.
+  - `hireMercenaries(contractId, polityId, band, initialLoyalty_Q?)` — factory; default loyalty q(0.70).
+  - `isMercenaryReliable(contract)` / `hasMercenaryArrears(contract)` — predicates.
+  - Three sample bands: `BAND_LIGHT_CAVALRY` (400 soldiers, q(0.65), 3 cu/day), `BAND_HEAVY_INFANTRY` (600, q(0.85), 5 cu/day), `BAND_SIEGE_ENGINEERS` (200, q(0.75), 8 cu/day).
+  - Added `./mercenaries` subpath export to `package.json`.
+  - 44 new tests; 5,173 total. Coverage: 100% statements/branches/functions/lines on `mercenaries.ts`.
+
+---
+
 ## [0.1.43] — 2026-03-26
 
 ### Added

package/dist/src/monetary.d.ts

@@ -0,0 +1,104 @@
+import type { Q } from "./units.js";
+import type { Polity } from "./polity.js";
+/** Polity monetary policy tier. */
+export type CoinagePolicy = "stable" | "slight_debasement" | "heavy_debasement" | "emergency_printing";
+/**
+ * Per-polity monetary state.
+ * Store externally (e.g. `Map<string, MonetaryState>`); pass to step each tick.
+ */
+export interface MonetaryState {
+    polityId: string;
+    /**
+     * Intrinsic coin purity [0, SCALE.Q].
+     * Starts at SCALE.Q (pure silver/gold).  Debasement reduces it; stable
+     * policy restores it slowly.  Trade partners assess coins by purity.
+     */
+    coinPurity_Q: Q;
+    /**
+     * Accumulated price inflation [0, SCALE.Q].
+     * Starts at 0 (no inflation).  Rises with debasement; falls slowly under
+     * stable policy.  Drives purchasing power loss and unrest.
+     */
+    inflationLevel_Q: Q;
+    /**
+     * `true` when `inflationLevel_Q >= MONETARY_CRISIS_THRESHOLD_Q`.
+     * In crisis: purchasing power collapses; trade partners sharply discount coins.
+     */
+    monetaryCrisis: boolean;
+}
+/** Inflation level at which monetary crisis activates [Q]. */
+export declare const MONETARY_CRISIS_THRESHOLD_Q: Q;
+/**
+ * Maximum unrest pressure from inflation at full inflation level [Q].
+ * Scales linearly: 0 at no inflation, `MONETARY_MAX_UNREST_Q` at SCALE.Q.
+ */
+export declare const MONETARY_MAX_UNREST_Q: Q;
+/**
+ * Minimum trade acceptance multiplier even with near-zero coin purity [Q].
+ * Barter / commodity exchange prevents complete trade collapse.
+ */
+export declare const MONETARY_TRADE_FLOOR_Q: Q;
+/**
+ * Coin purity change per day by policy [out of SCALE.Q].
+ * Positive = recovery; negative = degradation.
+ */
+export declare const POLICY_PURITY_DELTA_PER_DAY: Record<CoinagePolicy, number>;
+/**
+ * Inflation change per day by policy [out of SCALE.Q].
+ * Positive = inflation rising; negative = inflation falling.
+ */
+export declare const POLICY_INFLATION_DELTA_PER_DAY: Record<CoinagePolicy, number>;
+/**
+ * Extra coins minted per day as a fraction of current treasury [out of SCALE.Q].
+ * `gain_cu = round(treasury_cu × mintFrac × elapsedDays / SCALE.Q)`
+ */
+export declare const POLICY_DAILY_MINT_FRAC_Q: Record<CoinagePolicy, number>;
+/** Create a fresh `MonetaryState` with full purity and zero inflation. */
+export declare function createMonetaryState(polityId: string): MonetaryState;
+/**
+ * Compute the effective purchasing power of treasury coins [0, SCALE.Q].
+ *
+ * `purchasingPower = coinPurity_Q × (SCALE.Q − inflationLevel_Q) / SCALE.Q`
+ *
+ * Use to scale the real value of treasury income, mercenary wages, and
+ * construction costs.  Returns q(0.05) minimum to avoid zero.
+ */
+export declare function computePurchasingPower_Q(state: MonetaryState): Q;
+/**
+ * Compute the trade acceptance multiplier [MONETARY_TRADE_FLOOR_Q, SCALE.Q].
+ *
+ * Foreign trade partners check coin purity:
+ * `multiplier = TRADE_FLOOR + mulDiv(SCALE.Q − TRADE_FLOOR, coinPurity_Q, SCALE.Q)`
+ *
+ * Pass as a multiplier on Phase-92 trade income.
+ */
+export declare function computeMonetaryTradeMultiplier_Q(state: MonetaryState): Q;
+/**
+ * Compute unrest pressure from inflation [0, MONETARY_MAX_UNREST_Q].
+ *
+ * `unrest = mulDiv(MONETARY_MAX_UNREST_Q, inflationLevel_Q, SCALE.Q)`
+ *
+ * Pass to Phase-90 `computeUnrestLevel`.
+ */
+export declare function computeMonetaryUnrest_Q(state: MonetaryState): Q;
+/**
+ * Compute the extra treasury that would be minted by a debasement step
+ * without mutating state.  Advisory / preview function.
+ */
+export declare function computeDebasementGain_cu(polity: Polity, policy: CoinagePolicy, elapsedDays: number): number;
+/**
+ * Advance monetary state by `elapsedDays` under the given policy.
+ *
+ * 1. Mints extra coins: `treasury += computeDebasementGain_cu(polity, policy, elapsedDays)`.
+ * 2. Updates `coinPurity_Q` by `POLICY_PURITY_DELTA_PER_DAY × elapsedDays`; clamped [0, SCALE.Q].
+ * 3. Updates `inflationLevel_Q` by `POLICY_INFLATION_DELTA_PER_DAY × elapsedDays`; clamped [0, SCALE.Q].
+ * 4. Sets `monetaryCrisis = inflationLevel_Q >= MONETARY_CRISIS_THRESHOLD_Q`.
+ *
+ * Mutates `polity.treasury_cu`, `state.coinPurity_Q`, `state.inflationLevel_Q`,
+ * and `state.monetaryCrisis`.
+ */
+export declare function stepMonetary(polity: Polity, state: MonetaryState, policy: CoinagePolicy, elapsedDays: number): void;
+/** Return `true` when the polity is in monetary crisis (high inflation). */
+export declare function isMonetaryCrisis(state: MonetaryState): boolean;
+/** Return `true` when coin purity is at or above the given threshold. */
+export declare function isCoinageSound(state: MonetaryState, threshold_Q?: Q): boolean;

package/dist/src/monetary.js

@@ -0,0 +1,158 @@
+// src/monetary.ts — Phase 101: Currency & Monetary Policy
+//
+// Models coin purity, inflation, and monetary crises at polity scale.
+// Rulers can debase coinage (mint extra coins at lower purity) for short-term
+// treasury gain, but sustained debasement causes inflation, trade rejection,
+// and civil unrest.
+//
+// Design:
+//   - Pure data layer — no Entity fields, no kernel changes.
+//   - `MonetaryState` stores coin purity and inflation level separately:
+//       coinPurity_Q  — intrinsic metal content; affects trade acceptance.
+//       inflationLevel_Q — accumulated price inflation; affects purchasing power and unrest.
+//   - `stepMonetary` mints extra coins (treasury gain), degrades purity, and accrues
+//     inflation; stable policy slowly restores both.
+//   - All derived metrics (`purchasingPower_Q`, `tradeMultiplier_Q`, `unrestPressure_Q`)
+//     are advisory; callers pass them to Phases 90/92/93 as needed.
+//
+// Integration:
+//   Phase 90 (Unrest):      computeMonetaryUnrest_Q → unrestPressure_Q.
+//   Phase 92 (Taxation):    computePurchasingPower_Q → real value of tax revenue.
+//   Phase 93 (Campaign):    computeMonetaryTradeMultiplier_Q → tribute / supply costs.
+//   Phase 99 (Mercenaries): high inflation → real wage cost rises; host adjusts.
+//   Phase 100 (Wonders):    construction costs inflated; host scales contribution.
+import { q, SCALE, clampQ, mulDiv } from "./units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Inflation level at which monetary crisis activates [Q]. */
+export const MONETARY_CRISIS_THRESHOLD_Q = q(0.60);
+/**
+ * Maximum unrest pressure from inflation at full inflation level [Q].
+ * Scales linearly: 0 at no inflation, `MONETARY_MAX_UNREST_Q` at SCALE.Q.
+ */
+export const MONETARY_MAX_UNREST_Q = q(0.25);
+/**
+ * Minimum trade acceptance multiplier even with near-zero coin purity [Q].
+ * Barter / commodity exchange prevents complete trade collapse.
+ */
+export const MONETARY_TRADE_FLOOR_Q = q(0.40);
+/**
+ * Coin purity change per day by policy [out of SCALE.Q].
+ * Positive = recovery; negative = degradation.
+ */
+export const POLICY_PURITY_DELTA_PER_DAY = {
+    stable: +3,
+    slight_debasement: -5,
+    heavy_debasement: -18,
+    emergency_printing: -40,
+};
+/**
+ * Inflation change per day by policy [out of SCALE.Q].
+ * Positive = inflation rising; negative = inflation falling.
+ */
+export const POLICY_INFLATION_DELTA_PER_DAY = {
+    stable: -3,
+    slight_debasement: +6,
+    heavy_debasement: +20,
+    emergency_printing: +50,
+};
+/**
+ * Extra coins minted per day as a fraction of current treasury [out of SCALE.Q].
+ * `gain_cu = round(treasury_cu × mintFrac × elapsedDays / SCALE.Q)`
+ */
+export const POLICY_DAILY_MINT_FRAC_Q = {
+    stable: 0,
+    slight_debasement: 3, // +0.03%/day ≈ +11%/year
+    heavy_debasement: 10, // +0.10%/day ≈ +37%/year
+    emergency_printing: 30, // +0.30%/day ≈ +110%/year
+};
+// ── Factory ───────────────────────────────────────────────────────────────────
+/** Create a fresh `MonetaryState` with full purity and zero inflation. */
+export function createMonetaryState(polityId) {
+    return {
+        polityId,
+        coinPurity_Q: SCALE.Q,
+        inflationLevel_Q: 0,
+        monetaryCrisis: false,
+    };
+}
+// ── Advisory metrics ──────────────────────────────────────────────────────────
+/**
+ * Compute the effective purchasing power of treasury coins [0, SCALE.Q].
+ *
+ * `purchasingPower = coinPurity_Q × (SCALE.Q − inflationLevel_Q) / SCALE.Q`
+ *
+ * Use to scale the real value of treasury income, mercenary wages, and
+ * construction costs.  Returns q(0.05) minimum to avoid zero.
+ */
+export function computePurchasingPower_Q(state) {
+    const deflated = clampQ(SCALE.Q - state.inflationLevel_Q, 0, SCALE.Q);
+    const pp = mulDiv(state.coinPurity_Q, deflated, SCALE.Q);
+    return clampQ(pp, q(0.05), SCALE.Q);
+}
+/**
+ * Compute the trade acceptance multiplier [MONETARY_TRADE_FLOOR_Q, SCALE.Q].
+ *
+ * Foreign trade partners check coin purity:
+ * `multiplier = TRADE_FLOOR + mulDiv(SCALE.Q − TRADE_FLOOR, coinPurity_Q, SCALE.Q)`
+ *
+ * Pass as a multiplier on Phase-92 trade income.
+ */
+export function computeMonetaryTradeMultiplier_Q(state) {
+    const floor = MONETARY_TRADE_FLOOR_Q;
+    const range = SCALE.Q - floor;
+    return clampQ(floor + mulDiv(range, state.coinPurity_Q, SCALE.Q), floor, SCALE.Q);
+}
+/**
+ * Compute unrest pressure from inflation [0, MONETARY_MAX_UNREST_Q].
+ *
+ * `unrest = mulDiv(MONETARY_MAX_UNREST_Q, inflationLevel_Q, SCALE.Q)`
+ *
+ * Pass to Phase-90 `computeUnrestLevel`.
+ */
+export function computeMonetaryUnrest_Q(state) {
+    return clampQ(mulDiv(MONETARY_MAX_UNREST_Q, state.inflationLevel_Q, SCALE.Q), 0, MONETARY_MAX_UNREST_Q);
+}
+/**
+ * Compute the extra treasury that would be minted by a debasement step
+ * without mutating state.  Advisory / preview function.
+ */
+export function computeDebasementGain_cu(polity, policy, elapsedDays) {
+    const mintFrac = POLICY_DAILY_MINT_FRAC_Q[policy];
+    if (mintFrac === 0)
+        return 0;
+    return Math.round(polity.treasury_cu * mintFrac * elapsedDays / SCALE.Q);
+}
+// ── State step ────────────────────────────────────────────────────────────────
+/**
+ * Advance monetary state by `elapsedDays` under the given policy.
+ *
+ * 1. Mints extra coins: `treasury += computeDebasementGain_cu(polity, policy, elapsedDays)`.
+ * 2. Updates `coinPurity_Q` by `POLICY_PURITY_DELTA_PER_DAY × elapsedDays`; clamped [0, SCALE.Q].
+ * 3. Updates `inflationLevel_Q` by `POLICY_INFLATION_DELTA_PER_DAY × elapsedDays`; clamped [0, SCALE.Q].
+ * 4. Sets `monetaryCrisis = inflationLevel_Q >= MONETARY_CRISIS_THRESHOLD_Q`.
+ *
+ * Mutates `polity.treasury_cu`, `state.coinPurity_Q`, `state.inflationLevel_Q`,
+ * and `state.monetaryCrisis`.
+ */
+export function stepMonetary(polity, state, policy, elapsedDays) {
+    // Mint gain
+    const gain = computeDebasementGain_cu(polity, policy, elapsedDays);
+    polity.treasury_cu += gain;
+    // Purity update
+    const purityDelta = POLICY_PURITY_DELTA_PER_DAY[policy] * elapsedDays;
+    state.coinPurity_Q = clampQ(state.coinPurity_Q + purityDelta, 0, SCALE.Q);
+    // Inflation update
+    const inflDelta = POLICY_INFLATION_DELTA_PER_DAY[policy] * elapsedDays;
+    state.inflationLevel_Q = clampQ(state.inflationLevel_Q + inflDelta, 0, SCALE.Q);
+    // Crisis flag
+    state.monetaryCrisis = state.inflationLevel_Q >= MONETARY_CRISIS_THRESHOLD_Q;
+}
+// ── Helpers ───────────────────────────────────────────────────────────────────
+/** Return `true` when the polity is in monetary crisis (high inflation). */
+export function isMonetaryCrisis(state) {
+    return state.monetaryCrisis;
+}
+/** Return `true` when coin purity is at or above the given threshold. */
+export function isCoinageSound(state, threshold_Q = q(0.80)) {
+    return state.coinPurity_Q >= threshold_Q;
+}

package/dist/src/wonders.d.ts

@@ -0,0 +1,125 @@
+import type { Q } from "./units.js";
+import type { Polity } from "./polity.js";
+/** Classification of wonder. */
+export type WonderType = "great_pyramid" | "colosseum" | "grand_library" | "great_wall" | "grand_harbour" | "aqueduct_system" | "grand_temple";
+/** In-progress wonder construction. */
+export interface WonderProject {
+    projectId: string;
+    polityId: string;
+    type: WonderType;
+    /** Current build progress [0, SCALE.Q]. Complete at SCALE.Q. */
+    progress_Q: Q;
+    /** Cumulative treasury invested so far [cu]. */
+    investedCost_cu: number;
+    /** Tick at which construction started. */
+    startTick: number;
+}
+/** A completed wonder. */
+export interface Wonder {
+    wonderId: string;
+    polityId: string;
+    type: WonderType;
+    /** Tick at which construction finished. */
+    completedAtTick: number;
+    /**
+     * Whether this wonder has been damaged by an earthquake (Phase-96) or
+     * siege (Phase-93).  Damaged wonders provide `WONDER_DAMAGED_EFFECT_MUL`
+     * fraction of their normal effects until repaired.
+     */
+    damaged: boolean;
+}
+/**
+ * Advisory effect bundle from a wonder.
+ * Pass individual fields into the relevant downstream phase calls.
+ * All Q fields are [0, SCALE.Q]; `researchPointBonus` is raw points/day.
+ */
+export interface WonderEffects {
+    /** Add to `polity.stabilityQ`. */
+    stabilityBonus_Q: Q;
+    /** Add to `polity.moraleQ`. */
+    moraleBonus_Q: Q;
+    /** Additional research points per day. Pass to Phase-91. */
+    researchPointBonus: number;
+    /** Subtract from Phase-90 unrest level. */
+    unrestReduction_Q: Q;
+    /** Trade income multiplier bonus. Pass to Phase-92. */
+    tradeIncomeBonus_Q: Q;
+    /** Additive defender strength bonus. Pass to Phase-93. */
+    defenseBonus_Q: Q;
+    /** Add to `healthCapacity_Q` in Phase-88 `stepEpidemic`. */
+    epidemicResistance_Q: Q;
+}
+/**
+ * Total treasury cost to construct each wonder type [cu].
+ * Grand library is fastest; great pyramid is a generational project.
+ */
+export declare const WONDER_BASE_COST_CU: Record<WonderType, number>;
+/**
+ * Estimated build time in days at average investment rate.
+ * Informational only — actual duration depends on how fast the host invests.
+ */
+export declare const WONDER_TYPICAL_DAYS: Record<WonderType, number>;
+/**
+ * Full effects for each wonder type at q(1.0) effectiveness.
+ * Damaged wonders multiply each field by `WONDER_DAMAGED_EFFECT_MUL`.
+ */
+export declare const WONDER_BASE_EFFECTS: Record<WonderType, WonderEffects>;
+/**
+ * Effect multiplier for a damaged wonder [0, SCALE.Q].
+ * Damaged wonders still provide partial benefit; repair restores full effects.
+ */
+export declare const WONDER_DAMAGED_EFFECT_MUL: Q;
+/**
+ * Treasury cost to repair a damaged wonder, as a fraction of `WONDER_BASE_COST_CU`.
+ * Repair = `round(baseCost × WONDER_REPAIR_COST_FRAC / SCALE.Q)`.
+ */
+export declare const WONDER_REPAIR_COST_FRAC: Q;
+/** Create a new wonder construction project. */
+export declare function createWonderProject(projectId: string, polityId: string, type: WonderType, startTick: number): WonderProject;
+/**
+ * Invest treasury into a wonder project.
+ *
+ * Deducts up to `contribution_cu` from `polity.treasury_cu` (capped by available
+ * treasury and remaining cost), advances `progress_Q`, and returns the new progress.
+ *
+ * Does not auto-complete — call `isWonderProjectComplete` then `completeWonder`.
+ */
+export declare function contributeToWonder(project: WonderProject, polity: Polity, contribution_cu: number): Q;
+/** Return `true` when the project has reached full completion. */
+export declare function isWonderProjectComplete(project: WonderProject): boolean;
+/**
+ * Finalise a completed project into a standing `Wonder`.
+ *
+ * The caller is responsible for checking `isWonderProjectComplete` first.
+ */
+export declare function completeWonder(project: WonderProject, tick: number): Wonder;
+/**
+ * Mark a wonder as damaged (earthquake, siege).
+ * Damaged wonders yield `WONDER_DAMAGED_EFFECT_MUL` fraction of full effects.
+ */
+export declare function damageWonder(wonder: Wonder): void;
+/**
+ * Repair a damaged wonder, spending `WONDER_REPAIR_COST_FRAC` of base cost.
+ *
+ * Mutates `polity.treasury_cu` and clears `wonder.damaged`.
+ * Returns `true` if repaired; `false` if the polity lacked funds.
+ * No-op if wonder is not damaged.
+ */
+export declare function repairWonder(wonder: Wonder, polity: Polity): boolean;
+/**
+ * Compute the `WonderEffects` advisory bundle for a single wonder.
+ *
+ * Damaged wonders: each numeric field is scaled by `WONDER_DAMAGED_EFFECT_MUL / SCALE.Q`.
+ */
+export declare function computeWonderEffects(wonder: Wonder): WonderEffects;
+/**
+ * Aggregate effects from multiple wonders.
+ *
+ * Q fields are summed and clamped to SCALE.Q.
+ * `researchPointBonus` is summed without capping.
+ */
+export declare function aggregateWonderEffects(wonders: Wonder[]): WonderEffects;
+/** Return `true` when the wonder is standing and undamaged. */
+export declare function isWonderIntact(wonder: Wonder): boolean;
+/** Compute treasury cost to repair a damaged wonder [cu]. */
+export declare function computeRepairCost(type: WonderType): number;

package/dist/src/wonders.js

@@ -0,0 +1,264 @@
+// src/wonders.ts — Phase 100: Wonders & Monuments
+//
+// Unique prestige constructions that define great civilisations — pyramids,
+// colosseums, grand libraries, great walls, harbours, aqueducts, temples.
+// Unlike Phase-89 functional infrastructure (roads, markets, apothecaries),
+// wonders are one-of-a-kind, take years to complete, and give civilisation-
+// level bonuses to stability, morale, research, defence, trade, and health.
+//
+// Design:
+//   - Pure data layer — no Entity fields, no kernel changes.
+//   - `WonderProject` tracks construction progress; `Wonder` is the completed record.
+//   - Progress = investedCost_cu / WONDER_BASE_COST_CU; completion when progress_Q = SCALE.Q.
+//   - `WonderEffects` is an advisory bundle; callers pass fields into Phases 88–93.
+//   - Damaged wonders (Phase-96 earthquake / Phase-93 siege) provide half effects
+//     until repaired at half the base cost.
+//   - Only one wonder of each type per polity (enforced by naming convention;
+//     host is responsible for uniqueness).
+//
+// Integration:
+//   Phase 88 (Epidemic):      epidemicResistance_Q adds to healthCapacity_Q (aqueduct).
+//   Phase 90 (Unrest):        unrestReduction_Q reduces computeUnrestLevel (colosseum, temple).
+//   Phase 91 (Research):      researchPointBonus adds daily research points (library).
+//   Phase 92 (Taxation):      tradeIncomeBonus_Q scales trade income (harbour).
+//   Phase 93 (Military Camp): defenseBonus_Q adds to defender strength (great_wall).
+//   Phase 96 (Climate):       earthquake → caller calls damageWonder().
+import { q, SCALE, clampQ, mulDiv } from "./units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/**
+ * Total treasury cost to construct each wonder type [cu].
+ * Grand library is fastest; great pyramid is a generational project.
+ */
+export const WONDER_BASE_COST_CU = {
+    grand_library: 150_000,
+    aqueduct_system: 200_000,
+    grand_temple: 250_000,
+    grand_harbour: 300_000,
+    colosseum: 500_000,
+    great_wall: 600_000,
+    great_pyramid: 1_000_000,
+};
+/**
+ * Estimated build time in days at average investment rate.
+ * Informational only — actual duration depends on how fast the host invests.
+ */
+export const WONDER_TYPICAL_DAYS = {
+    grand_library: 180,
+    aqueduct_system: 365,
+    grand_temple: 365,
+    grand_harbour: 365,
+    colosseum: 730,
+    great_wall: 1095,
+    great_pyramid: 3650,
+};
+/**
+ * Full effects for each wonder type at q(1.0) effectiveness.
+ * Damaged wonders multiply each field by `WONDER_DAMAGED_EFFECT_MUL`.
+ */
+export const WONDER_BASE_EFFECTS = {
+    great_pyramid: {
+        stabilityBonus_Q: q(0.08), // generational prestige
+        moraleBonus_Q: q(0.05),
+        researchPointBonus: 0,
+        unrestReduction_Q: 0,
+        tradeIncomeBonus_Q: 0,
+        defenseBonus_Q: 0,
+        epidemicResistance_Q: 0,
+    },
+    colosseum: {
+        stabilityBonus_Q: q(0.03),
+        moraleBonus_Q: q(0.10), // entertainment
+        researchPointBonus: 0,
+        unrestReduction_Q: q(0.12), // bread and circuses
+        tradeIncomeBonus_Q: 0,
+        defenseBonus_Q: 0,
+        epidemicResistance_Q: 0,
+    },
+    grand_library: {
+        stabilityBonus_Q: q(0.03),
+        moraleBonus_Q: q(0.02),
+        researchPointBonus: 3, // +3 RP/day
+        unrestReduction_Q: 0,
+        tradeIncomeBonus_Q: 0,
+        defenseBonus_Q: 0,
+        epidemicResistance_Q: 0,
+    },
+    great_wall: {
+        stabilityBonus_Q: q(0.05),
+        moraleBonus_Q: 0,
+        researchPointBonus: 0,
+        unrestReduction_Q: 0,
+        tradeIncomeBonus_Q: 0,
+        defenseBonus_Q: q(0.20), // major defensive advantage
+        epidemicResistance_Q: 0,
+    },
+    grand_harbour: {
+        stabilityBonus_Q: 0,
+        moraleBonus_Q: q(0.03),
+        researchPointBonus: 0,
+        unrestReduction_Q: 0,
+        tradeIncomeBonus_Q: q(0.25), // major trade multiplier
+        defenseBonus_Q: 0,
+        epidemicResistance_Q: 0,
+    },
+    aqueduct_system: {
+        stabilityBonus_Q: q(0.02),
+        moraleBonus_Q: q(0.04), // quality of life
+        researchPointBonus: 0,
+        unrestReduction_Q: 0,
+        tradeIncomeBonus_Q: 0,
+        defenseBonus_Q: 0,
+        epidemicResistance_Q: q(0.15), // clean water reduces disease
+    },
+    grand_temple: {
+        stabilityBonus_Q: q(0.06), // divine legitimacy
+        moraleBonus_Q: q(0.08),
+        researchPointBonus: 0,
+        unrestReduction_Q: q(0.08),
+        tradeIncomeBonus_Q: 0,
+        defenseBonus_Q: 0,
+        epidemicResistance_Q: 0,
+    },
+};
+/**
+ * Effect multiplier for a damaged wonder [0, SCALE.Q].
+ * Damaged wonders still provide partial benefit; repair restores full effects.
+ */
+export const WONDER_DAMAGED_EFFECT_MUL = q(0.50);
+/**
+ * Treasury cost to repair a damaged wonder, as a fraction of `WONDER_BASE_COST_CU`.
+ * Repair = `round(baseCost × WONDER_REPAIR_COST_FRAC / SCALE.Q)`.
+ */
+export const WONDER_REPAIR_COST_FRAC = q(0.25);
+// ── Factory ───────────────────────────────────────────────────────────────────
+/** Create a new wonder construction project. */
+export function createWonderProject(projectId, polityId, type, startTick) {
+    return {
+        projectId,
+        polityId,
+        type,
+        progress_Q: 0,
+        investedCost_cu: 0,
+        startTick,
+    };
+}
+// ── Construction ──────────────────────────────────────────────────────────────
+/**
+ * Invest treasury into a wonder project.
+ *
+ * Deducts up to `contribution_cu` from `polity.treasury_cu` (capped by available
+ * treasury and remaining cost), advances `progress_Q`, and returns the new progress.
+ *
+ * Does not auto-complete — call `isWonderProjectComplete` then `completeWonder`.
+ */
+export function contributeToWonder(project, polity, contribution_cu) {
+    const totalCost = WONDER_BASE_COST_CU[project.type];
+    const remaining = Math.max(0, totalCost - project.investedCost_cu);
+    const actual = Math.min(contribution_cu, polity.treasury_cu, remaining);
+    polity.treasury_cu -= actual;
+    project.investedCost_cu += actual;
+    project.progress_Q = clampQ(Math.round(project.investedCost_cu * SCALE.Q / totalCost), 0, SCALE.Q);
+    return project.progress_Q;
+}
+/** Return `true` when the project has reached full completion. */
+export function isWonderProjectComplete(project) {
+    return project.progress_Q >= SCALE.Q;
+}
+/**
+ * Finalise a completed project into a standing `Wonder`.
+ *
+ * The caller is responsible for checking `isWonderProjectComplete` first.
+ */
+export function completeWonder(project, tick) {
+    return {
+        wonderId: project.projectId,
+        polityId: project.polityId,
+        type: project.type,
+        completedAtTick: tick,
+        damaged: false,
+    };
+}
+// ── Damage & repair ───────────────────────────────────────────────────────────
+/**
+ * Mark a wonder as damaged (earthquake, siege).
+ * Damaged wonders yield `WONDER_DAMAGED_EFFECT_MUL` fraction of full effects.
+ */
+export function damageWonder(wonder) {
+    wonder.damaged = true;
+}
+/**
+ * Repair a damaged wonder, spending `WONDER_REPAIR_COST_FRAC` of base cost.
+ *
+ * Mutates `polity.treasury_cu` and clears `wonder.damaged`.
+ * Returns `true` if repaired; `false` if the polity lacked funds.
+ * No-op if wonder is not damaged.
+ */
+export function repairWonder(wonder, polity) {
+    if (!wonder.damaged)
+        return true;
+    const baseCost = WONDER_BASE_COST_CU[wonder.type];
+    const repairCost = Math.round(mulDiv(baseCost, WONDER_REPAIR_COST_FRAC, SCALE.Q));
+    if (polity.treasury_cu < repairCost)
+        return false;
+    polity.treasury_cu -= repairCost;
+    wonder.damaged = false;
+    return true;
+}
+// ── Effect computation ────────────────────────────────────────────────────────
+/**
+ * Compute the `WonderEffects` advisory bundle for a single wonder.
+ *
+ * Damaged wonders: each numeric field is scaled by `WONDER_DAMAGED_EFFECT_MUL / SCALE.Q`.
+ */
+export function computeWonderEffects(wonder) {
+    const base = WONDER_BASE_EFFECTS[wonder.type];
+    if (!wonder.damaged)
+        return { ...base };
+    const m = WONDER_DAMAGED_EFFECT_MUL;
+    return {
+        stabilityBonus_Q: mulDiv(base.stabilityBonus_Q, m, SCALE.Q),
+        moraleBonus_Q: mulDiv(base.moraleBonus_Q, m, SCALE.Q),
+        researchPointBonus: Math.round(base.researchPointBonus * m / SCALE.Q),
+        unrestReduction_Q: mulDiv(base.unrestReduction_Q, m, SCALE.Q),
+        tradeIncomeBonus_Q: mulDiv(base.tradeIncomeBonus_Q, m, SCALE.Q),
+        defenseBonus_Q: mulDiv(base.defenseBonus_Q, m, SCALE.Q),
+        epidemicResistance_Q: mulDiv(base.epidemicResistance_Q, m, SCALE.Q),
+    };
+}
+/**
+ * Aggregate effects from multiple wonders.
+ *
+ * Q fields are summed and clamped to SCALE.Q.
+ * `researchPointBonus` is summed without capping.
+ */
+export function aggregateWonderEffects(wonders) {
+    let stab = 0, morale = 0, rp = 0, unrest = 0, trade = 0, def = 0, epi = 0;
+    for (const w of wonders) {
+        const fx = computeWonderEffects(w);
+        stab += fx.stabilityBonus_Q;
+        morale += fx.moraleBonus_Q;
+        rp += fx.researchPointBonus;
+        unrest += fx.unrestReduction_Q;
+        trade += fx.tradeIncomeBonus_Q;
+        def += fx.defenseBonus_Q;
+        epi += fx.epidemicResistance_Q;
+    }
+    return {
+        stabilityBonus_Q: clampQ(stab, 0, SCALE.Q),
+        moraleBonus_Q: clampQ(morale, 0, SCALE.Q),
+        researchPointBonus: rp,
+        unrestReduction_Q: clampQ(unrest, 0, SCALE.Q),
+        tradeIncomeBonus_Q: clampQ(trade, 0, SCALE.Q),
+        defenseBonus_Q: clampQ(def, 0, SCALE.Q),
+        epidemicResistance_Q: clampQ(epi, 0, SCALE.Q),
+    };
+}
+// ── Helpers ───────────────────────────────────────────────────────────────────
+/** Return `true` when the wonder is standing and undamaged. */
+export function isWonderIntact(wonder) {
+    return !wonder.damaged;
+}
+/** Compute treasury cost to repair a damaged wonder [cu]. */
+export function computeRepairCost(type) {
+    return Math.round(mulDiv(WONDER_BASE_COST_CU[type], WONDER_REPAIR_COST_FRAC, SCALE.Q));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@its-not-rocket-science/ananke",
-  "version": "0.1.43",
+  "version": "0.1.46",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",
@@ -158,6 +158,18 @@
     "./containment": {
       "import": "./dist/src/containment.js",
       "types": "./dist/src/containment.d.ts"
+    },
+    "./mercenaries": {
+      "import": "./dist/src/mercenaries.js",
+      "types": "./dist/src/mercenaries.d.ts"
+    },
+    "./wonders": {
+      "import": "./dist/src/wonders.js",
+      "types": "./dist/src/wonders.d.ts"
+    },
+    "./monetary": {
+      "import": "./dist/src/monetary.js",
+      "types": "./dist/src/monetary.d.ts"
     }
   },
   "files": [