@its-not-rocket-science/ananke 0.1.0

package/dist/src/economy.js

@@ -0,0 +1,182 @@
+// src/economy.ts — Phase 25: Loot & Economy
+//
+// Item value, equipment degradation, drop resolution, and trade evaluation.
+// Composes with the equipment, medical, and arena systems without modifying them.
+//
+// No kernel import — pure data-management module.
+import { SCALE, q, clampQ, qMul } from "./units.js";
+import { eventSeed } from "./sim/seeds.js";
+import { makeRng } from "./rng.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Base wear increment at full intensity (q(1.0) per strike). */
+export const WEAR_BASE = q(0.001);
+/** Wear threshold at which a −5% effective-mass penalty begins. */
+export const WEAR_PENALTY_THRESHOLD = q(0.30);
+/** Wear threshold at which a 20% fumble chance triggers. */
+export const WEAR_FUMBLE_THRESHOLD = q(0.70);
+const FUMBLE_CHANCE_Q = q(0.20); // 20%
+const DEFAULT_SELL_FRACTION = 0.40; // weapons/armour
+const MEDICAL_SELL_FRACTION = 0.50;
+// ── computeItemValue ──────────────────────────────────────────────────────────
+/**
+ * Derive economic metadata for any item or medical resource.
+ *
+ * `wear_Q` is the caller's current wear value for the item.
+ *   - For melee weapons: use `weapon.wear_Q ?? q(0)`.
+ *   - For armour: derive via `armourConditionQ(resist_J, resistRemaining_J)`.
+ *   - Omit (defaults to `q(0)`) for consumables or new items.
+ *
+ * `condition_Q = q(1.0) − wear_Q`, clamped to [0, SCALE.Q].
+ */
+export function computeItemValue(item, wear_Q = q(0)) {
+    // MedicalResource: identified by `costUnits` presence
+    if ("costUnits" in item) {
+        const med = item;
+        return {
+            itemId: med.id,
+            baseValue: med.costUnits,
+            condition_Q: q(1.0), // consumables don't degrade
+            sellFraction: MEDICAL_SELL_FRACTION,
+        };
+    }
+    const it = item;
+    const condition_Q = clampQ(SCALE.Q - wear_Q, 0, SCALE.Q);
+    if (it.kind === "weapon") {
+        const w = it;
+        // ~10 cost units per kg, plus reach bonus
+        const massUnits = Math.floor((w.mass_kg / SCALE.kg) * 10);
+        const reachBonus = w.reach_m ? Math.floor((w.reach_m / SCALE.m) * 5) : 0;
+        return { itemId: w.id, baseValue: massUnits + reachBonus, condition_Q, sellFraction: DEFAULT_SELL_FRACTION };
+    }
+    if (it.kind === "armour") {
+        const a = it;
+        // ~0.4 cost units per joule of base resist
+        const base = Math.floor(a.resist_J * 0.4);
+        return { itemId: a.id, baseValue: base, condition_Q, sellFraction: DEFAULT_SELL_FRACTION };
+    }
+    if (it.kind === "ranged") {
+        const r = it;
+        const massUnits = Math.floor((r.mass_kg / SCALE.kg) * 10);
+        return { itemId: r.id, baseValue: massUnits + 5, condition_Q, sellFraction: DEFAULT_SELL_FRACTION };
+    }
+    // Shield / Gear / Exoskeleton / Sensor — fallback
+    return { itemId: it.id, baseValue: Math.floor(it.mass_kg / SCALE.kg * 8), condition_Q: q(1.0), sellFraction: DEFAULT_SELL_FRACTION };
+}
+/**
+ * Convert armour degradation state to a wear_Q fraction.
+ *
+ * ```
+ * wear = q(1.0) − resistRemaining_J / resist_J
+ * ```
+ * Used to derive `condition_Q` for ablative armour via `computeItemValue`.
+ */
+export function armourConditionQ(resist_J, resistRemaining_J) {
+    if (resist_J <= 0)
+        return q(1.0);
+    const fraction = Math.trunc((resistRemaining_J * SCALE.Q) / resist_J);
+    return clampQ(fraction, 0, SCALE.Q);
+}
+// ── applyWear ─────────────────────────────────────────────────────────────────
+/**
+ * Apply one strike's worth of use-wear to a melee weapon.
+ *
+ * @param weapon          - The weapon being used (reads `wear_Q` field if present).
+ * @param actionIntensity_Q - Strike intensity (q(0)..q(1.0)); higher = more wear.
+ *                           Use q(1.0) for strikes against hard targets (plate armour),
+ *                           lower values for soft/unarmoured opponents.
+ * @param seed            - Optional entropy seed for the deterministic fumble roll.
+ *                          Must be supplied when checking fumble; otherwise fumble = false.
+ *
+ * The returned `wear_Q` should be written back to `weapon.wear_Q` by the caller.
+ */
+export function applyWear(weapon, actionIntensity_Q, seed) {
+    const current = (weapon.wear_Q ?? q(0));
+    // Increment proportional to strike intensity (q(0.001) × intensity)
+    const increment = Math.max(1, Math.trunc(qMul(WEAR_BASE, actionIntensity_Q)));
+    const newWear = clampQ(current + increment, 0, SCALE.Q);
+    const broke = newWear >= SCALE.Q;
+    const penaltyActive = newWear >= WEAR_PENALTY_THRESHOLD;
+    let fumble = false;
+    if (!broke && newWear >= WEAR_FUMBLE_THRESHOLD && seed !== undefined) {
+        const rng = makeRng(eventSeed(seed, 0, 0, 0, 0xFADE1), SCALE.Q);
+        fumble = rng.q01() < FUMBLE_CHANCE_Q;
+    }
+    return { wear_Q: newWear, broke, fumble, penaltyActive };
+}
+// ── resolveDrops ──────────────────────────────────────────────────────────────
+/**
+ * Compute the list of item IDs dropped by an entity on death or incapacitation.
+ *
+ * Default behaviour:
+ *   - Dead entity → all equipped weapons, ranged weapons, and armour drop (guaranteed).
+ *   - Incapacitated but living → nothing drops (use `config.dropOnIncapacitated = true` to override).
+ *
+ * Additional items from `extra.guaranteed` always drop (when applicable).
+ * `extra.probabilistic` items are rolled deterministically from `seed`.
+ */
+export function resolveDrops(entity, seed, extra, config) {
+    const shouldDrop = entity.injury.dead || (config?.dropOnIncapacitated ?? false);
+    if (!shouldDrop)
+        return [];
+    const result = [];
+    // Guaranteed: all equipped weapons and armour
+    for (const item of entity.loadout.items) {
+        if (item.kind === "weapon" || item.kind === "armour" || item.kind === "ranged") {
+            result.push(item.id);
+        }
+    }
+    if (extra) {
+        for (const id of extra.guaranteed) {
+            result.push(id);
+        }
+        // Probabilistic roll — deterministic per item index
+        for (let i = 0; i < extra.probabilistic.length; i++) {
+            const entry = extra.probabilistic[i];
+            const rollSeed = eventSeed(seed, i, 0, 0, 0xD50A5);
+            const rng = makeRng(rollSeed, SCALE.Q);
+            if (rng.q01() < entry.chance_Q) {
+                result.push(entry.itemId);
+            }
+        }
+    }
+    return result;
+}
+// ── evaluateTradeOffer ────────────────────────────────────────────────────────
+/**
+ * Evaluate a trade offer from the accepting party's perspective.
+ *
+ * - `offer.give`:  items the proposing party puts on the table.
+ * - `offer.want`:  items the proposing party asks for in return.
+ * - `inventory`:   accepting party's current stock.
+ *
+ * `netValue` > 0 → advantageous for the accepting party (they receive more than they give).
+ * `feasible` — the accepting party has all `want` items in sufficient quantities.
+ */
+export function evaluateTradeOffer(offer, inventory) {
+    // Feasibility: does the accepting party have all wanted items?
+    let feasible = true;
+    for (const w of offer.want) {
+        const entry = inventory.get(w.itemId);
+        if (!entry || entry.count < w.count) {
+            feasible = false;
+            break;
+        }
+    }
+    // Net value for accepting party: receive give items, pay want items
+    let netValue = 0;
+    for (const g of offer.give)
+        netValue += g.count * g.unitValue;
+    for (const w of offer.want)
+        netValue -= w.count * w.unitValue;
+    return { netValue, feasible };
+}
+// ── totalInventoryValue ───────────────────────────────────────────────────────
+/**
+ * Sum the total value of all items in an inventory (count × unitValue for each entry).
+ */
+export function totalInventoryValue(inventory) {
+    let total = 0;
+    for (const [, entry] of inventory)
+        total += entry.count * entry.unitValue;
+    return total;
+}

package/dist/src/emotional-contagion.d.ts

@@ -0,0 +1,142 @@
+import { type Q } from "./units.js";
+import type { PolityRegistry, PolityPair } from "./polity.js";
+/** Whether the emotional wave helps or harms morale. */
+export type EmotionalValence = "fear" | "hope";
+/**
+ * Declarative profile for an emotional contagion event.
+ * Mirrors DiseaseProfile structure for API consistency.
+ */
+export interface EmotionalContagionProfile {
+    id: string;
+    name: string;
+    /** "fear" drains moraleQ; "hope" restores it. */
+    valence: EmotionalValence;
+    /**
+     * Daily transmission probability to each adjacent polity [0, SCALE.Q].
+     * Rolled against eventSeed; analogous to DiseaseProfile.baseTransmissionRate_Q.
+     */
+    baseTransmissionRate_Q: Q;
+    /**
+     * Fraction of wave intensity lost per day [0, SCALE.Q].
+     * At q(1.0) the wave expires in one tick.
+     */
+    decayRate_Q: Q;
+    /**
+     * Maximum moraleQ change applied to a polity per day [0, SCALE.Q].
+     * Scaled by the effective wave intensity × transmission success.
+     */
+    maxMoraleDelta_Q: Q;
+    /**
+     * Multiplier applied to initial wave intensity when a leader with high
+     * musical/performance intelligence triggers the event (Phase 39 hook).
+     * 0 = no amplification; q(1.0) = up to 2× base intensity.
+     */
+    leaderAmplification_Q: Q;
+}
+/**
+ * An active emotional event originating from one polity.
+ * Decays each day; removed when intensity_Q reaches 0.
+ */
+export interface EmotionalWave {
+    profileId: string;
+    /** The polity that originated the event (battle loss, speech, etc.). */
+    sourcePolityId: string;
+    /** Current intensity [0, SCALE.Q]. Decays by decayRate_Q each day. */
+    intensity_Q: Q;
+    /** Number of day-ticks this wave has been active. */
+    daysActive: number;
+}
+/** Per-polity morale delta produced by one batch of contagion spread. */
+export interface ContagionResult {
+    polityId: string;
+    moraleDelta_Q: Q;
+}
+/** Heavy defeat in the field triggers mass panic. Spreads fast, decays fast. */
+export declare const PROFILE_MILITARY_ROUT: EmotionalContagionProfile;
+/** Plague outbreak news spreads slowly but persists. */
+export declare const PROFILE_PLAGUE_PANIC: EmotionalContagionProfile;
+/** Victory news bolsters allied and neutral neighbours. */
+export declare const PROFILE_VICTORY_RALLY: EmotionalContagionProfile;
+/** A charismatic leader's speech rallies citizens directly. */
+export declare const PROFILE_CHARISMATIC_ADDRESS: EmotionalContagionProfile;
+/** All built-in profiles, indexed by id. */
+export declare const EMOTIONAL_PROFILES: ReadonlyArray<EmotionalContagionProfile>;
+/** Look up a profile by id. Returns undefined if unknown. */
+export declare function getEmotionalProfile(id: string): EmotionalContagionProfile | undefined;
+/**
+ * Create a new emotional wave at full intensity.
+ * Pass `leaderPerformance_Q` > 0 to amplify the initial intensity
+ * (effective only when the profile has leaderAmplification_Q > 0).
+ */
+export declare function createEmotionalWave(profile: EmotionalContagionProfile, sourcePolityId: string, leaderPerformance_Q?: Q): EmotionalWave;
+/** @internal Used by tests and convenience triggers. */
+export declare function _makeWave(profile: EmotionalContagionProfile, sourcePolityId: string, leaderPerformance_Q?: Q): EmotionalWave;
+/**
+ * Advance all active waves by one day: increment daysActive, apply decay.
+ * Returns the updated array with expired waves (intensity_Q === 0) removed.
+ *
+ * Does NOT modify the input array — returns a new array.
+ */
+export declare function stepEmotionalWaves(waves: ReadonlyArray<EmotionalWave>, profiles: ReadonlyArray<EmotionalContagionProfile>): EmotionalWave[];
+/**
+ * Compute the morale delta a source wave inflicts on one adjacent target polity.
+ *
+ * Returns 0 if:
+ * - The source polity is not in the registry
+ * - The deterministic roll misses (no transmission)
+ *
+ * The sign of the returned Q matches the transmission direction — callers
+ * should negate it for "fear" valence before applying to `moraleQ`.
+ * (Positive return always means "some effect occurred"; valence is handled
+ * by `applyEmotionalContagion`.)
+ */
+export declare function computeEmotionalSpread(sourcePolityId: string, targetPolityId: string, wave: EmotionalWave, profile: EmotionalContagionProfile, worldSeed: number, tick: number): Q;
+/**
+ * Apply all active emotional waves to the polity registry for one day-tick.
+ *
+ * For each wave, iterates all PolityPairs where the source polity appears.
+ * Calls `computeEmotionalSpread` for each neighbour polity.
+ * Applies the resulting morale delta (negative for fear, positive for hope)
+ * directly to `polity.moraleQ`, clamped to [0, SCALE.Q].
+ *
+ * Also applies the wave directly to the SOURCE polity at full intensity
+ * (the originating polity is always affected before it spreads outward).
+ *
+ * Returns a `ContagionResult[]` listing every polity that was affected.
+ * Polities with zero net delta are omitted.
+ */
+export declare function applyEmotionalContagion(registry: PolityRegistry, pairs: ReadonlyArray<PolityPair>, waves: ReadonlyArray<EmotionalWave>, profiles: ReadonlyArray<EmotionalContagionProfile>, worldSeed: number, tick: number): ContagionResult[];
+/**
+ * A polity's army has been routed.  Creates a MILITARY_ROUT fear wave at the
+ * source polity at full base intensity (no leader amplification for defeats).
+ */
+export declare function triggerMilitaryRout(sourcePolityId: string): EmotionalWave;
+/**
+ * Plague outbreak confirmed in a polity.  Creates a PLAGUE_PANIC fear wave.
+ */
+export declare function triggerPlaguePanic(sourcePolityId: string): EmotionalWave;
+/**
+ * A decisive military victory.  Creates a VICTORY_RALLY hope wave, optionally
+ * amplified by the commander's performance intelligence (Phase 39 hook).
+ *
+ * @param leaderPerformance_Q  Commander's musical/intrapersonal mean [0, SCALE.Q].
+ *                             Pass q(0) for a leaderless victory.
+ */
+export declare function triggerVictoryRally(sourcePolityId: string, leaderPerformance_Q?: Q): EmotionalWave;
+/**
+ * A charismatic leader addresses the populace.  Uses CHARISMATIC_ADDRESS profile;
+ * `leaderPerformance_Q` amplifies wave intensity (Phase 39 hook).
+ *
+ * @param leaderPerformance_Q  Leader's musical/intrapersonal mean [0, SCALE.Q].
+ */
+export declare function triggerLeaderAddress(sourcePolityId: string, leaderPerformance_Q: Q): EmotionalWave;
+/**
+ * Check whether a wave has fully decayed (intensity === 0).
+ */
+export declare function isWaveExpired(wave: EmotionalWave): boolean;
+/**
+ * Summarise the net emotional pressure across all active waves for a polity.
+ * Returns a signed Q: positive = net hope, negative = net fear.
+ * Useful for AI queries ("is this polity in panic?").
+ */
+export declare function netEmotionalPressure(polityId: string, waves: ReadonlyArray<EmotionalWave>, profiles: ReadonlyArray<EmotionalContagionProfile>): Q;

package/dist/src/emotional-contagion.js

@@ -0,0 +1,274 @@
+// src/emotional-contagion.ts — Phase 65: Emotional Contagion at Polity Scale
+//
+// Fear and hope propagate between polities using the same transmission model
+// as Phase 56 disease spread, with `fear_Q` / `hope_Q` as the "pathogen".
+//
+// Design:
+//   1. EmotionalContagionProfile  — transmission rate, valence, decay, amplitude
+//   2. EmotionalWave              — active event (battle rout, rally speech) with
+//                                   decaying intensity; multiple waves can stack
+//   3. computeEmotionalSpread()   — risk Q between a source and adjacent polity
+//   4. applyEmotionalContagion()  — batch spread + morale delta application
+//   5. stepEmotionalWaves()       — daily decay; expired waves removed
+//   6. Convenience triggers       — triggerMilitaryRout, triggerVictoryRally,
+//                                   triggerLeaderAddress, triggerPlaguePanic
+//
+// The host calls applyEmotionalContagion once per polity day-tick (alongside
+// stepPolityDay and computePolityDiseaseSpread).  No Entity import — this
+// module operates purely at the Polity / PolityRegistry level.
+//
+// Four built-in profiles:
+//   military_rout       — fear; fast spread, fast decay
+//   plague_panic        — fear; moderate spread, slow decay
+//   victory_rally       — hope; moderate spread, medium decay
+//   charismatic_address — hope; leader-amplified, short-range, fast decay
+//
+// Phase 39 hook: leaderPerformance_Q amplifies the initial wave intensity
+// of a charismatic_address event via triggerLeaderAddress().
+import { q, clampQ, qMul, SCALE } from "./units.js";
+import { eventSeed, hashString } from "./sim/seeds.js";
+import { makeRng } from "./rng.js";
+// ── Built-in profiles ─────────────────────────────────────────────────────────
+/** Heavy defeat in the field triggers mass panic. Spreads fast, decays fast. */
+export const PROFILE_MILITARY_ROUT = {
+    id: "military_rout",
+    name: "Military Rout",
+    valence: "fear",
+    baseTransmissionRate_Q: q(0.60),
+    decayRate_Q: q(0.18), // ~5-day half-life
+    maxMoraleDelta_Q: q(0.08),
+    leaderAmplification_Q: q(0),
+};
+/** Plague outbreak news spreads slowly but persists. */
+export const PROFILE_PLAGUE_PANIC = {
+    id: "plague_panic",
+    name: "Plague Panic",
+    valence: "fear",
+    baseTransmissionRate_Q: q(0.40),
+    decayRate_Q: q(0.05), // ~20-day half-life
+    maxMoraleDelta_Q: q(0.05),
+    leaderAmplification_Q: q(0),
+};
+/** Victory news bolsters allied and neutral neighbours. */
+export const PROFILE_VICTORY_RALLY = {
+    id: "victory_rally",
+    name: "Victory Rally",
+    valence: "hope",
+    baseTransmissionRate_Q: q(0.45),
+    decayRate_Q: q(0.10), // ~10-day half-life
+    maxMoraleDelta_Q: q(0.04),
+    leaderAmplification_Q: q(0.50),
+};
+/** A charismatic leader's speech rallies citizens directly. */
+export const PROFILE_CHARISMATIC_ADDRESS = {
+    id: "charismatic_address",
+    name: "Charismatic Address",
+    valence: "hope",
+    baseTransmissionRate_Q: q(0.30),
+    decayRate_Q: q(0.25), // ~4-day half-life (fades quickly)
+    maxMoraleDelta_Q: q(0.10),
+    leaderAmplification_Q: q(1.00), // leader skill doubles wave impact
+};
+/** All built-in profiles, indexed by id. */
+export const EMOTIONAL_PROFILES = [
+    PROFILE_MILITARY_ROUT,
+    PROFILE_PLAGUE_PANIC,
+    PROFILE_VICTORY_RALLY,
+    PROFILE_CHARISMATIC_ADDRESS,
+];
+/** Look up a profile by id. Returns undefined if unknown. */
+export function getEmotionalProfile(id) {
+    return EMOTIONAL_PROFILES.find(p => p.id === id);
+}
+// ── Wave management ────────────────────────────────────────────────────────────
+/**
+ * Create a new emotional wave at full intensity.
+ * Pass `leaderPerformance_Q` > 0 to amplify the initial intensity
+ * (effective only when the profile has leaderAmplification_Q > 0).
+ */
+export function createEmotionalWave(profile, sourcePolityId, leaderPerformance_Q = q(0)) {
+    // amplification = base + leaderPerformance_Q × leaderAmplification_Q / SCALE.Q
+    // capped at SCALE.Q so intensity stays in [0, SCALE.Q]
+    const amplification = qMul(leaderPerformance_Q, profile.leaderAmplification_Q);
+    const intensity_Q = clampQ(SCALE.Q + amplification, 0, SCALE.Q * 2);
+    // clamp to SCALE.Q for the wave field
+    const clamped = clampQ(intensity_Q, 0, SCALE.Q);
+    return { profileId: sourcePolityId, sourcePolityId, intensity_Q: clamped, daysActive: 0 };
+}
+/** @internal Used by tests and convenience triggers. */
+export function _makeWave(profile, sourcePolityId, leaderPerformance_Q = q(0)) {
+    const amplification = qMul(leaderPerformance_Q, profile.leaderAmplification_Q);
+    const raw = SCALE.Q + amplification;
+    const intensity_Q = clampQ(raw, 0, SCALE.Q);
+    return {
+        profileId: profile.id,
+        sourcePolityId,
+        intensity_Q,
+        daysActive: 0,
+    };
+}
+/**
+ * Advance all active waves by one day: increment daysActive, apply decay.
+ * Returns the updated array with expired waves (intensity_Q === 0) removed.
+ *
+ * Does NOT modify the input array — returns a new array.
+ */
+export function stepEmotionalWaves(waves, profiles) {
+    const result = [];
+    for (const wave of waves) {
+        const profile = profiles.find(p => p.id === wave.profileId);
+        const decayRate = profile?.decayRate_Q ?? q(0.10);
+        const decayed = qMul(wave.intensity_Q, SCALE.Q - decayRate);
+        const newIntensity = clampQ(decayed, 0, SCALE.Q);
+        if (newIntensity > 0) {
+            result.push({ ...wave, intensity_Q: newIntensity, daysActive: wave.daysActive + 1 });
+        }
+    }
+    return result;
+}
+// ── Spread computation ─────────────────────────────────────────────────────────
+/**
+ * Compute the morale delta a source wave inflicts on one adjacent target polity.
+ *
+ * Returns 0 if:
+ * - The source polity is not in the registry
+ * - The deterministic roll misses (no transmission)
+ *
+ * The sign of the returned Q matches the transmission direction — callers
+ * should negate it for "fear" valence before applying to `moraleQ`.
+ * (Positive return always means "some effect occurred"; valence is handled
+ * by `applyEmotionalContagion`.)
+ */
+export function computeEmotionalSpread(sourcePolityId, targetPolityId, wave, profile, worldSeed, tick) {
+    if (sourcePolityId === targetPolityId)
+        return q(0);
+    // Transmission roll — identical salt scheme to Phase 56
+    const salt = hashString(profile.id);
+    const seed = eventSeed(worldSeed, tick, hashString(sourcePolityId), hashString(targetPolityId), salt);
+    const rng = makeRng(seed, SCALE.Q);
+    const roll = rng.q01();
+    // Effective rate: base × wave intensity
+    const effectiveRate = qMul(profile.baseTransmissionRate_Q, wave.intensity_Q);
+    if (roll > effectiveRate)
+        return q(0);
+    // Morale delta: maxDelta × (effectiveRate / SCALE.Q)
+    const delta = Math.round(profile.maxMoraleDelta_Q * effectiveRate / SCALE.Q);
+    return clampQ(delta, 0, profile.maxMoraleDelta_Q);
+}
+// ── Batch application ──────────────────────────────────────────────────────────
+/**
+ * Apply all active emotional waves to the polity registry for one day-tick.
+ *
+ * For each wave, iterates all PolityPairs where the source polity appears.
+ * Calls `computeEmotionalSpread` for each neighbour polity.
+ * Applies the resulting morale delta (negative for fear, positive for hope)
+ * directly to `polity.moraleQ`, clamped to [0, SCALE.Q].
+ *
+ * Also applies the wave directly to the SOURCE polity at full intensity
+ * (the originating polity is always affected before it spreads outward).
+ *
+ * Returns a `ContagionResult[]` listing every polity that was affected.
+ * Polities with zero net delta are omitted.
+ */
+export function applyEmotionalContagion(registry, pairs, waves, profiles, worldSeed, tick) {
+    if (waves.length === 0)
+        return [];
+    // Accumulate per-polity morale deltas (signed: positive = hope, negative = fear)
+    const deltas = new Map();
+    const applyDelta = (polityId, signed) => {
+        deltas.set(polityId, (deltas.get(polityId) ?? 0) + signed);
+    };
+    for (const wave of waves) {
+        const profile = profiles.find(p => p.id === wave.profileId);
+        if (!profile)
+            continue;
+        const sign = profile.valence === "fear" ? -1 : 1;
+        // Source polity always receives the full wave intensity as a direct morale hit
+        const sourceDelta = Math.round(profile.maxMoraleDelta_Q * wave.intensity_Q / SCALE.Q);
+        applyDelta(wave.sourcePolityId, sign * sourceDelta);
+        // Spread to adjacent polities via pairs
+        for (const pair of pairs) {
+            let targetId = null;
+            if (pair.polityAId === wave.sourcePolityId)
+                targetId = pair.polityBId;
+            else if (pair.polityBId === wave.sourcePolityId)
+                targetId = pair.polityAId;
+            if (!targetId)
+                continue;
+            const spread = computeEmotionalSpread(wave.sourcePolityId, targetId, wave, profile, worldSeed, tick);
+            if (spread > 0) {
+                applyDelta(targetId, sign * spread);
+            }
+        }
+    }
+    // Apply accumulated deltas to registry and build result list
+    const results = [];
+    for (const [polityId, delta] of deltas) {
+        if (delta === 0)
+            continue;
+        const polity = registry.polities.get(polityId);
+        if (!polity)
+            continue;
+        const newMorale = clampQ(polity.moraleQ + delta, 0, SCALE.Q);
+        polity.moraleQ = newMorale;
+        results.push({ polityId, moraleDelta_Q: delta });
+    }
+    return results;
+}
+// ── Convenience triggers ───────────────────────────────────────────────────────
+/**
+ * A polity's army has been routed.  Creates a MILITARY_ROUT fear wave at the
+ * source polity at full base intensity (no leader amplification for defeats).
+ */
+export function triggerMilitaryRout(sourcePolityId) {
+    return _makeWave(PROFILE_MILITARY_ROUT, sourcePolityId);
+}
+/**
+ * Plague outbreak confirmed in a polity.  Creates a PLAGUE_PANIC fear wave.
+ */
+export function triggerPlaguePanic(sourcePolityId) {
+    return _makeWave(PROFILE_PLAGUE_PANIC, sourcePolityId);
+}
+/**
+ * A decisive military victory.  Creates a VICTORY_RALLY hope wave, optionally
+ * amplified by the commander's performance intelligence (Phase 39 hook).
+ *
+ * @param leaderPerformance_Q  Commander's musical/intrapersonal mean [0, SCALE.Q].
+ *                             Pass q(0) for a leaderless victory.
+ */
+export function triggerVictoryRally(sourcePolityId, leaderPerformance_Q = q(0)) {
+    return _makeWave(PROFILE_VICTORY_RALLY, sourcePolityId, leaderPerformance_Q);
+}
+/**
+ * A charismatic leader addresses the populace.  Uses CHARISMATIC_ADDRESS profile;
+ * `leaderPerformance_Q` amplifies wave intensity (Phase 39 hook).
+ *
+ * @param leaderPerformance_Q  Leader's musical/intrapersonal mean [0, SCALE.Q].
+ */
+export function triggerLeaderAddress(sourcePolityId, leaderPerformance_Q) {
+    return _makeWave(PROFILE_CHARISMATIC_ADDRESS, sourcePolityId, leaderPerformance_Q);
+}
+/**
+ * Check whether a wave has fully decayed (intensity === 0).
+ */
+export function isWaveExpired(wave) {
+    return wave.intensity_Q <= 0;
+}
+/**
+ * Summarise the net emotional pressure across all active waves for a polity.
+ * Returns a signed Q: positive = net hope, negative = net fear.
+ * Useful for AI queries ("is this polity in panic?").
+ */
+export function netEmotionalPressure(polityId, waves, profiles) {
+    let total = 0;
+    for (const wave of waves) {
+        if (wave.sourcePolityId !== polityId)
+            continue;
+        const profile = profiles.find(p => p.id === wave.profileId);
+        if (!profile)
+            continue;
+        const signed = profile.valence === "fear" ? -wave.intensity_Q : wave.intensity_Q;
+        total += signed;
+    }
+    return clampQ(total, -SCALE.Q, SCALE.Q);
+}