@its-not-rocket-science/ananke 0.1.44 → 0.1.47

package/dist/src/modding.js

@@ -8,13 +8,13 @@
  *   mod file.  The network replication layer (CE-11) compares fingerprints across clients
  *   to guarantee all participants use identical mod definitions.
  *
- * **Layer 2 — Post-tick behavior hooks**
+ * **Layer 2 — Post-tick behaviour hooks**
  *   `registerPostTickHook(id, fn)` registers an observer callback that the host fires
  *   after each `stepWorld` call via `runPostTickHooks(world)`.  Hooks are purely
  *   observational — they MUST NOT mutate `WorldState` during the call.  Because they run
  *   outside the kernel path they cannot break determinism.
  *
- * **Layer 3 — AI behavior node overrides**
+ * **Layer 3 — AI behaviour node overrides**
  *   `registerBehaviorNode(id, factory)` installs a named factory for custom
  *   `BehaviorNode` implementations.  `loadScenario` (CE-3) can reference them by id in
  *   scenario JSON.  AI overrides require explicit host opt-in.
@@ -117,7 +117,7 @@ const _behaviorNodes = new Map();
  * Register a named factory for a custom `BehaviorNode` implementation.
  *
  * The factory will be looked up by id when `loadScenario` (CE-3) encounters an
- * `"aiOverride"` reference in scenario JSON, or when a host builds a behavior
+ * `"aiOverride"` reference in scenario JSON, or when a host builds a behaviour
  * tree programmatically:
  *
  * ```typescript
@@ -129,7 +129,7 @@ const _behaviorNodes = new Map();
  * ```
  *
  * **Deterministic multiplayer**: AI overrides affect simulation output.  All
- * clients must register the same behavior nodes (verified via `computeModManifest`)
+ * clients must register the same behaviour nodes (verified via `computeModManifest`)
  * before joining a session.
  *
  * Re-registering an existing id overwrites the previous factory.
@@ -140,30 +140,30 @@ export function registerBehaviorNode(id, factory) {
     _behaviorNodes.set(id, factory);
 }
 /**
- * Remove a previously registered behavior node factory.
+ * Remove a previously registered behaviour node factory.
  * Returns `true` if the factory existed and was removed.
  */
 export function unregisterBehaviorNode(id) {
     return _behaviorNodes.delete(id);
 }
 /**
- * Look up a registered behavior node factory by id.
+ * Look up a registered behaviour node factory by id.
  * Returns `undefined` if not found.
  */
 export function getBehaviorNode(id) {
     return _behaviorNodes.get(id);
 }
-/** Return the ids of all registered behavior node factories in registration order. */
+/** Return the ids of all registered behaviour node factories in registration order. */
 export function listBehaviorNodes() {
     return [..._behaviorNodes.keys()];
 }
-/** Remove all behavior node factories (useful for testing and hot-reload scenarios). */
+/** Remove all behaviour node factories (useful for testing and hot-reload scenarios). */
 export function clearBehaviorNodes() {
     _behaviorNodes.clear();
 }
 /**
  * Compute a session manifest covering all active mods (CE-12 catalog entries,
- * post-tick hooks, and AI behavior node overrides).
+ * post-tick hooks, and AI behaviour node overrides).
  *
  * The `fingerprint` is a deterministic 8-char hex string suitable for
  * multiplayer session comparison.  Clients are considered mod-compatible iff
@@ -181,7 +181,7 @@ export function computeModManifest(catalogIds = []) {
     const fingerprint = fnv1a32(combined).toString(16).padStart(8, "0");
     return { dataIds, hookIds, behaviorIds, fingerprint };
 }
-/** Remove all hooks and behavior node factories. Does not affect the CE-12 catalog. */
+/** Remove all hooks and behaviour node factories. Does not affect the CE-12 catalog. */
 export function clearAllMods() {
     _hooks.clear();
     _behaviorNodes.clear();

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/narrative-render.js

@@ -31,9 +31,9 @@ export function renderArcSummary(arc) {
         rise_of_hero: (a) => `The hero's journey of ${actorNames(a)} spans ${entryCount(a)} pivotal moments.`,
         tragic_fall: (a) => `${actorNames(a)}'s descent from grace, marked by betrayal and loss.`,
         rivalry: (a) => `An enduring rivalry between ${actorNames(a)} unfolding across ${entryCount(a)} confrontations.`,
-        great_migration: (a) => `A mass migration that reshaped the region.`,
-        settlement_growth: (a) => `The rise of a settlement from humble beginnings to prosperity.`,
-        fallen_settlement: (a) => `The tragic fall of a once-great settlement.`,
+        great_migration: (_a) => `A mass migration that reshaped the region.`,
+        settlement_growth: (_a) => `The rise of a settlement from humble beginnings to prosperity.`,
+        fallen_settlement: (_a) => `The tragic fall of a once-great settlement.`,
         legendary_craftsman: (a) => `${actorNames(a)}'s masterworks will be remembered for generations.`,
         notorious_villain: (a) => `The terrifying rise of ${actorNames(a)}.`,
         unlikely_friendship: (a) => `An unexpected bond formed between ${actorNames(a)} against all odds.`,

package/dist/src/quest-generators.js

@@ -40,7 +40,7 @@ const DELIVERY_TEMPLATE = {
         currency: 50,
     },
     objectiveGenerators: [
-        (ctx) => ({
+        (_ctx) => ({
             objectiveId: "collect_package",
             description: "Collect the package from the quest giver",
             type: "collect_item",
@@ -129,7 +129,7 @@ const INVESTIGATION_TEMPLATE = {
             state: "available",
             hidden: false,
         }),
-        (ctx) => ({
+        (_ctx) => ({
             objectiveId: "report_findings",
             description: "Return and report your findings",
             type: "dialogue_choice",
@@ -185,7 +185,7 @@ const COLLECTION_TEMPLATE = {
         currency: 60,
     },
     objectiveGenerators: [
-        (ctx) => ({
+        (_ctx) => ({
             objectiveId: "collect_items",
             description: "Collect the requested items",
             type: "collect_item",
@@ -224,7 +224,7 @@ const WAIT_TEMPLATE = {
             state: "available",
             hidden: false,
         }),
-        (ctx) => ({
+        (_ctx) => ({
             objectiveId: "stand_watch",
             description: "Stand watch for the required duration",
             type: "wait_duration",

package/dist/src/settlement-services.js

@@ -88,12 +88,12 @@ export function generateSettlementNeeds(settlement) {
             suggestedReward: 200,
         });
     }
-    // Recent raid → defense need
+    // Recent raid → defence need
     if (settlement.safetyStatus.ticksSinceLastRaid < 100) {
         needs.push({
             type: "defense",
             priority: 8,
-            description: "Recent raid requires improved defenses",
+            description: "Recent raid requires improved defences",
             suggestedReward: 300,
         });
     }

package/dist/src/settlement.d.ts

@@ -135,7 +135,7 @@ export interface AvailableServices {
 export declare function getAvailableServices(settlement: Settlement): AvailableServices;
 /** Record a raid/siege on a settlement. */
 export declare function recordRaid(settlement: Settlement, attackerFactionId: number, casualties: number, tick: number): void;
-/** Update settlement defenses. */
+/** Update settlement defences. */
 export declare function updateDefenses(settlement: Settlement, hasDefenses: boolean): void;
 /** Serialize settlement to JSON-friendly format. */
 export declare function serializeSettlement(settlement: Settlement): unknown;

package/dist/src/settlement.js

@@ -351,7 +351,7 @@ function getMedicalCareLevel(level) {
         default: return "none";
     }
 }
-// ── Settlement Defense ─────────────────────────────────────────────────────────
+// ── Settlement Defence ─────────────────────────────────────────────────────────
 /** Record a raid/siege on a settlement. */
 export function recordRaid(settlement, attackerFactionId, casualties, tick) {
     settlement.safetyStatus.ticksSinceLastRaid = 0;
@@ -367,7 +367,7 @@ export function recordRaid(settlement, attackerFactionId, casualties, tick) {
         settlement.population = Math.max(0, settlement.population - casualties);
     }
 }
-/** Update settlement defenses. */
+/** Update settlement defences. */
 export function updateDefenses(settlement, hasDefenses) {
     settlement.safetyStatus.hasDefenses = hasDefenses;
 }

package/dist/src/sim/ai/behavior-trees.d.ts

@@ -1,5 +1,5 @@
 /**
- * CE-10 — Pre-built AI Behavior Tree Library
+ * CE-10 — Pre-built AI Behaviour Tree Library
  *
  * A thin, composable layer over the existing AI decision system.  Each
  * `BehaviorNode` receives the ticking entity, the current world state, and
@@ -31,7 +31,7 @@ import type { KernelContext } from "../context.js";
 import type { Command } from "../commands.js";
 import { type Q } from "../../units.js";
 /**
- * A single node in a behavior tree.
+ * A single node in a behaviour tree.
  *
  * `tick` is called once per AI frame (typically once per `stepWorld` tick).
  * Returns a `Command` if this node produces an action, or `null` if the node's

package/dist/src/sim/ai/behavior-trees.js

@@ -1,5 +1,5 @@
 /**
- * CE-10 — Pre-built AI Behavior Tree Library
+ * CE-10 — Pre-built AI Behaviour Tree Library
  *
  * A thin, composable layer over the existing AI decision system.  Each
  * `BehaviorNode` receives the ticking entity, the current world state, and
@@ -302,7 +302,7 @@ export function WithProbability(probability_Q, inner, salt = 0) {
         },
     };
 }
-// ── Pre-built behavior tree presets ──────────────────────────────────────────
+// ── Pre-built behaviour tree presets ─────────────────────────────────────────
 /**
  * Standard aggressive attacker: attack `targetId` at full intensity.
  * Falls back to retreat if badly shocked (shock ≥ q(0.70)).

package/dist/src/sim/bodyplan.d.ts

@@ -81,7 +81,7 @@ export interface BodySegment {
      */
     regeneratesViaMolting?: boolean;
     /**
-     * Intrinsic structural armor resist (joules) — energy absorbed by the shell
+     * Intrinsic structural armour resist (joules) — energy absorbed by the shell
      * before damage channels are allocated.  Distinct from worn equipment armour.
      * Absent or 0 = no intrinsic resistance.
      */

package/dist/src/sim/kernel.js

@@ -1368,7 +1368,7 @@ export function applyImpactToInjury(target, wpn, energy_J, region, armoured, tra
         }
     }
     const armourShift = armoured ? q(0.75) : q(1.0);
-    // Phase 8C: intrinsic exoskeleton armor — absorbed before damage channels are allocated
+    // Phase 8C: intrinsic exoskeleton armour — absorbed before damage channels are allocated
     if (seg?.intrinsicArmor_J !== undefined && seg.intrinsicArmor_J > 0) {
         energy_J = Math.max(0, energy_J - seg.intrinsicArmor_J);
         if (energy_J === 0)

package/dist/src/sim/step/morale.js

@@ -48,7 +48,7 @@ export function stepMoraleForEntity(world, e, index, spatial, aliveBeforeTick, t
     }
     let fearQ = e.condition.fearQ;
     const wasRouting = isRouting(fearQ, distressTol);
-    // 1. Suppression ticks add fear per tick — scaled by caliber multiplier (Feature 1)
+    // 1. Suppression ticks add fear per tick — scaled by calibre multiplier (Feature 1)
     if (e.condition.suppressedTicks > 0) {
         const supMul = e.condition.suppressionFearMul ?? SCALE.Q;
         fearQ = clampQ(fearQ + qMul(FEAR_PER_SUPPRESSION_TICK, supMul), 0, SCALE.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;