@its-not-rocket-science/ananke 0.1.0

package/dist/src/sim/weather.js

@@ -0,0 +1,105 @@
+// src/sim/weather.ts — Phase 51: Weather & Atmospheric Environment
+//
+// Pure computation module — no entity mutation.  Defines weather state types
+// and derives per-tick modifiers that the kernel applies to traction, sensory
+// environment, ambient temperature, and ranged-combat aim error.
+//
+// Data flow:
+//   KernelContext.weather (WeatherState) → deriveWeatherModifiers → WeatherModifiers
+//   WeatherModifiers → kernel stepWorld → tractionCoeff, sensoryEnv, thermalAmbient_Q
+//   WeatherState.wind + resolveShoot → computeWindAimError → extra gRadius_m
+import { SCALE, q, clampQ } from "../units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/**
+ * Approximate Q units per degree Celsius in the Phase-29 thermal encoding.
+ * (SCALE.Q / 54) where 54 = 64°C − 10°C temperature range).
+ */
+export const WEATHER_Q_PER_DEG_C = 185;
+/** Reference cone-weapon travel speed [SCALE.mps] for adjustConeRange. 20 m/s. */
+const CONE_REF_SPEED_mps = 2_000;
+// ── Precipitation lookup table ────────────────────────────────────────────────
+/** Physical parameters indexed by PrecipitationType. */
+const PRECIP_TABLE = {
+    none: { tractionMul: q(1.00), lightMul: q(1.00), precipVisionMul: q(1.00), thermalDegC: 0 },
+    rain: { tractionMul: q(0.85), lightMul: q(0.90), precipVisionMul: q(0.85), thermalDegC: 1 },
+    heavy_rain: { tractionMul: q(0.70), lightMul: q(0.70), precipVisionMul: q(0.60), thermalDegC: 2 },
+    snow: { tractionMul: q(0.60), lightMul: q(0.75), precipVisionMul: q(0.75), thermalDegC: 5 },
+    blizzard: { tractionMul: q(0.40), lightMul: q(0.30), precipVisionMul: q(0.30), thermalDegC: 12 },
+    hail: { tractionMul: q(0.75), lightMul: q(0.85), precipVisionMul: q(0.85), thermalDegC: 1 },
+};
+// ── deriveWeatherModifiers ─────────────────────────────────────────────────────
+/**
+ * Compute all derived modifiers for a WeatherState.
+ * Pure function — no side effects.
+ */
+export function deriveWeatherModifiers(weather) {
+    const pt = PRECIP_TABLE[weather.precipitation ?? "none"];
+    // Fog multiplier: q(0) fog = q(1.0) light; q(1.0) fog = q(0.10) minimum light.
+    const fogMul = weather.fogDensity_Q !== undefined
+        ? clampQ((SCALE.Q - weather.fogDensity_Q), q(0.10), SCALE.Q)
+        : SCALE.Q;
+    // Combined light reduction from precipitation and fog (multiplicative).
+    const lightMul_Q = clampQ(Math.trunc(pt.lightMul * fogMul / SCALE.Q), q(0.10), SCALE.Q);
+    return {
+        tractionMul_Q: pt.tractionMul,
+        lightMul_Q,
+        precipVisionMul_Q: pt.precipVisionMul,
+        thermalOffset_Q: pt.thermalDegC ? -(pt.thermalDegC * WEATHER_Q_PER_DEG_C) : 0,
+    };
+}
+// ── computeWindAimError ───────────────────────────────────────────────────────
+/**
+ * Additional aim grouping radius from wind drift [SCALE.m].
+ *
+ * Physics: drift = v_wind_perp × (range / v_proj)
+ *
+ * The perpendicular wind component is the 2D cross product of shot direction
+ * and wind direction.  Algebraic simplification yields:
+ *
+ *   drift_scaled_m = wind.speed_mps × |shot × wind| / (SCALE.m × v_proj_mps)
+ *
+ * where |shot × wind| is the cross-product magnitude in SCALE.m² units with
+ * shot direction of magnitude `dist_m` and wind direction of magnitude SCALE.m.
+ * The `dist_m` factors cancel, leaving a formula independent of scale choice.
+ *
+ * @param wind        Wind field (direction + speed).
+ * @param shotDx_m    Shot direction x [SCALE.m] (raw, not normalised).
+ * @param shotDy_m    Shot direction y [SCALE.m] (raw, not normalised).
+ * @param dist_m      Range to target [SCALE.m].
+ * @param v_proj_mps  Projectile speed [SCALE.mps].
+ * @returns Additional grouping radius [SCALE.m] (≥ 0).
+ */
+export function computeWindAimError(wind, shotDx_m, shotDy_m, dist_m, v_proj_mps) {
+    if (wind.speed_mps <= 0 || v_proj_mps <= 0 || dist_m <= 0)
+        return 0;
+    // 2D cross product magnitude: |shot × wind| in SCALE.m² units.
+    const crossRaw = Math.abs(shotDx_m * wind.dy_m - shotDy_m * wind.dx_m);
+    // drift_scaled_m = wind.speed_mps × crossRaw / (SCALE.m × v_proj_mps)
+    return Math.trunc(wind.speed_mps * crossRaw / (SCALE.m * v_proj_mps));
+}
+// ── adjustConeRange ───────────────────────────────────────────────────────────
+/**
+ * Adjust cone range for wind effects (breath weapons, gas clouds, flamethrowers).
+ *
+ * - Headwind (wind opposes cone direction) reduces range up to −20%.
+ * - Tailwind extends range up to +10%.
+ * - Crosswind (perpendicular) has no effect on range.
+ *
+ * @param wind      Wind field.
+ * @param coneDx_m  Cone facing direction x (SCALE.m unit vector).
+ * @param coneDy_m  Cone facing direction y (SCALE.m unit vector).
+ * @param range_m   Base cone range [SCALE.m].
+ * @returns Adjusted range [SCALE.m] (≥ 0).
+ */
+export function adjustConeRange(wind, coneDx_m, coneDy_m, range_m) {
+    if (wind.speed_mps <= 0 || range_m <= 0)
+        return range_m;
+    // Dot product of cone dir (SCALE.m unit vector) and wind dir (SCALE.m unit vector).
+    // Result is in SCALE.m²; divide by SCALE.m to get aligned component in SCALE.m.
+    const dot_m = Math.trunc((coneDx_m * wind.dx_m + coneDy_m * wind.dy_m) / SCALE.m);
+    // Effect = aligned_speed / CONE_REF_SPEED as a Q fraction, clamped to ±20% / +10%.
+    // At CONE_REF_SPEED full-headwind (dot = −SCALE.m): effect_Q = −q(0.20).
+    const effect_Q = clampQ(Math.trunc(wind.speed_mps * dot_m * 2_000 / (SCALE.m * CONE_REF_SPEED_mps)), -2_000, // max −20% headwind reduction
+    1_000);
+    return Math.max(0, range_m + Math.trunc(range_m * effect_Q / SCALE.Q));
+}

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

@@ -0,0 +1,52 @@
+import type { Entity } from "./entity.js";
+import type { FieldEffect } from "./capability.js";
+import { SensoryEnvironment } from "./sensory.js";
+import { FactionRegistry } from "../faction.js";
+import { PartyRegistry } from "../party.js";
+import { RelationshipGraph } from "../relationships.js";
+/**
+ * Top-level simulation container.
+ *
+ * Fields are annotated with stability tiers identical to `Entity`:
+ * - **`@core`** — required by `stepWorld` every tick.
+ * - **`@subsystem(name)`** — optional state consumed only by a specific sub-module.
+ */
+export interface WorldState {
+    /** @core Current tick count; incremented by `stepWorld`. */
+    tick: number;
+    /** @core Deterministic RNG seed — same seed + same commands → identical output. */
+    seed: number;
+    /** @core All live and dead entities.  Do not splice manually; use `stepWorld`. */
+    entities: Entity[];
+    /**
+     * @subsystem(capability) Active suppression zones and field-effect modifiers
+     * (e.g., mana-null zones, buff auras).  Consumed by `src/sim/capability.ts`.
+     */
+    activeFieldEffects?: FieldEffect[];
+    /**
+     * @subsystem(sensory) Ambient lighting and visibility environment.
+     * Consumed by `src/sim/sensory.ts` when provided.  Prefixed `__` to discourage
+     * direct access — use the sensory API instead.
+     */
+    __sensoryEnv?: SensoryEnvironment;
+    /**
+     * @subsystem(faction) Global faction-standing registry.
+     * Consumed by `src/faction.ts` and AI targeting.
+     */
+    __factionRegistry?: FactionRegistry;
+    /**
+     * @subsystem(party) Global party registry.
+     * Consumed by `src/party.ts` for morale and formation bonuses.
+     */
+    __partyRegistry?: PartyRegistry;
+    /**
+     * @subsystem(relationships) Inter-entity relationship graph.
+     * Consumed by `src/relationships.ts`.
+     */
+    __relationshipGraph?: RelationshipGraph;
+    /**
+     * @subsystem(nutrition) Cross-tick nutrition accumulator.
+     * Consumed by the nutrition sub-step in `src/sim/kernel.ts`.
+     */
+    __nutritionAccum?: number;
+}

package/dist/src/sim/world.js

@@ -0,0 +1 @@
+export {};

package/dist/src/sim/wound-aging.d.ts

@@ -0,0 +1,120 @@
+import { type Q } from "../units.js";
+import type { Entity } from "./entity.js";
+/**
+ * PTSD-like trauma state accumulating from severe shock events.
+ * Stored on `entity.traumaState`.
+ * Reduces effective fear threshold via `deriveFearThresholdMul`.
+ */
+export interface TraumaState {
+    /** Cumulative severity (Q 0..SCALE.Q). Grows with shock events; decays over time. */
+    severity_Q: Q;
+}
+/** Outcome summary returned by `stepWoundAging`. */
+export interface WoundAgingResult {
+    /** Region ids whose surface or internal damage improved (healed). */
+    healedRegions: string[];
+    /** Region ids whose damage worsened (infection progression). */
+    worsenedRegions: string[];
+    /** True if any region crossed the sepsis damage threshold this step. */
+    newSepsis: boolean;
+}
+/** Seconds per day — base unit for all per-day rates. */
+export declare const SECONDS_PER_DAY = 86400;
+/**
+ * Surface-damage healing rate [Q/day].
+ * At q(0.01)/day, a fully surface-damaged region takes ~100 days to heal.
+ */
+export declare const SURFACE_HEAL_Q_PER_DAY: Q;
+/**
+ * Internal-damage healing rate [Q/day].
+ * Half the surface rate — internal injuries heal more slowly.
+ */
+export declare const INTERNAL_HEAL_Q_PER_DAY: Q;
+/**
+ * Infection worsening rate [Q/day] applied to internalDamage while infected.
+ * 3× the internal heal rate — untreated infection outpaces natural recovery.
+ */
+export declare const INFECTION_WORSEN_Q_PER_DAY: Q;
+/**
+ * Internal-damage threshold (Q) above which an infected region is considered
+ * to pose a sepsis risk (systemically threatening).
+ */
+export declare const SEPSIS_THRESHOLD: Q;
+/**
+ * Chronic fatigue per-day rate [Q/day] applied when total permanent damage
+ * across all regions exceeds CHRONIC_FATIGUE_REGION_THRESHOLD.
+ */
+export declare const CHRONIC_FATIGUE_Q_PER_DAY: Q;
+/**
+ * Minimum total permanent damage (summed across all regions, relative to
+ * SCALE.Q × regionCount) to activate chronic fatigue.
+ * Approximately q(0.10) average per region.
+ */
+export declare const CHRONIC_FATIGUE_THRESHOLD: Q;
+/**
+ * Permanent-damage threshold (per region) above which a fractured region
+ * causes phantom pain during rest.
+ */
+export declare const PHANTOM_PAIN_THRESHOLD: Q;
+/**
+ * Phantom pain shock injection per day per qualifying fractured region [Q/day].
+ * Scaled by the region's (permanentDamage / SCALE.Q) ratio.
+ */
+export declare const PHANTOM_PAIN_Q_PER_DAY: Q;
+/**
+ * Trauma decay per day [Q/day] — natural recovery rate of traumaState.severity_Q.
+ * Slow: severe trauma takes months to fully resolve.
+ */
+export declare const TRAUMA_DECAY_Q_PER_DAY: Q;
+/**
+ * Minimum shock increment that registers as a traumatic event.
+ * Events below this threshold are too minor to compound PTSD-like symptoms.
+ */
+export declare const TRAUMA_TRIGGER_THRESHOLD: Q;
+/**
+ * Advance long-term wound state by `elapsedSeconds`.
+ *
+ * Intended for downtime / long-rest simulation (hours to weeks of elapsed time).
+ * At sub-minute resolution this function does nothing observable.
+ *
+ * Mutates:
+ *   entity.injury.byRegion  (surface/internal damage healed or worsened)
+ *   entity.injury.shock     (phantom pain)
+ *   entity.energy.fatigue   (chronic fatigue drain)
+ *   entity.traumaState      (natural severity decay)
+ *
+ * @param elapsedSeconds  Wall-clock seconds elapsed (use 86400 per game-day).
+ * @returns WoundAgingResult summary (healed, worsened, newSepsis).
+ */
+export declare function stepWoundAging(entity: Entity, elapsedSeconds: number): WoundAgingResult;
+/**
+ * Record a traumatic shock event, accumulating PTSD-like severity.
+ *
+ * Only events at or above TRAUMA_TRIGGER_THRESHOLD (q(0.20)) register.
+ * A q(1.0) shock event contributes q(0.30) to `traumaState.severity_Q`.
+ *
+ * Mutates: entity.traumaState (created if absent).
+ *
+ * @param shockIncrement_Q  The shock delta from the triggering event (Q).
+ */
+export declare function recordTraumaEvent(entity: Entity, shockIncrement_Q: Q): void;
+/**
+ * Derive the effective fear-threshold multiplier from accumulated trauma.
+ *
+ * Returns Q in [TRAUMA_FEAR_MUL_FLOOR, SCALE.Q]:
+ *   q(1.0) → no trauma — fear threshold unchanged.
+ *   q(0.50) → maximum trauma — entity triggers fear at half normal threshold.
+ *
+ * Usage (combat / morale layer):
+ *   `effectiveFearThreshold_Q = Math.round(baseFearThreshold_Q × mul / SCALE.Q)`
+ */
+export declare function deriveFearThresholdMul(entity: Entity): Q;
+/**
+ * Compute aggregate sepsis risk (Q 0..SCALE.Q) from all infected regions.
+ *
+ * Risk increases with both the number of infected regions and their
+ * internal damage level. Returns q(0) if no infected regions.
+ *
+ * Usage: AI / medical layer reads this to prioritise treatment.
+ */
+export declare function deriveSepsisRisk(entity: Entity): Q;

package/dist/src/sim/wound-aging.js

@@ -0,0 +1,223 @@
+// src/sim/wound-aging.ts — Phase 54: Wound Aging & Long-Term Sequelae
+//
+// Extends Phase 21 (injury resolution) and Phase 9 (infection) with time-based
+// wound progression relevant to multi-day / multi-week campaign simulation.
+//
+// Four long-term processes:
+//   1. Healing    — uninfected regions slowly recover surface and internal damage
+//                   (clamped to permanentDamage floor; structural never recovers).
+//   2. Infection  — infected regions worsen; severe infection → sepsis flag.
+//   3. Chronic fatigue — sustained permanent damage creates a baseline fatigue drain.
+//   4. Phantom pain    — fractured regions with significant permanent damage inject
+//                        periodic shock increments during rest/downtime.
+//
+// Plus two PTSD-like trauma utilities:
+//   recordTraumaEvent(entity, shockQ)          — accumulate trauma severity
+//   deriveFearThresholdMul(entity) → Q         — fear multiplier from trauma
+//   deriveSepsisRisk(entity)       → Q         — aggregate infection severity
+//
+// Call stepWoundAging during downtime (long rests, between scenes) with the number
+// of real elapsed seconds. At 1 real second this does nothing useful; at 86 400 s
+// (one day) the full daily rates apply.
+import { q, clampQ, SCALE } from "../units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Seconds per day — base unit for all per-day rates. */
+export const SECONDS_PER_DAY = 86_400;
+/**
+ * Surface-damage healing rate [Q/day].
+ * At q(0.01)/day, a fully surface-damaged region takes ~100 days to heal.
+ */
+export const SURFACE_HEAL_Q_PER_DAY = q(0.01); // 100 Q/day
+/**
+ * Internal-damage healing rate [Q/day].
+ * Half the surface rate — internal injuries heal more slowly.
+ */
+export const INTERNAL_HEAL_Q_PER_DAY = q(0.005); // 50 Q/day
+/**
+ * Infection worsening rate [Q/day] applied to internalDamage while infected.
+ * 3× the internal heal rate — untreated infection outpaces natural recovery.
+ */
+export const INFECTION_WORSEN_Q_PER_DAY = q(0.015); // 150 Q/day
+/**
+ * Internal-damage threshold (Q) above which an infected region is considered
+ * to pose a sepsis risk (systemically threatening).
+ */
+export const SEPSIS_THRESHOLD = q(0.85);
+/**
+ * Chronic fatigue per-day rate [Q/day] applied when total permanent damage
+ * across all regions exceeds CHRONIC_FATIGUE_REGION_THRESHOLD.
+ */
+export const CHRONIC_FATIGUE_Q_PER_DAY = q(0.02); // 200 Q/day
+/**
+ * Minimum total permanent damage (summed across all regions, relative to
+ * SCALE.Q × regionCount) to activate chronic fatigue.
+ * Approximately q(0.10) average per region.
+ */
+export const CHRONIC_FATIGUE_THRESHOLD = q(0.10); // per-region average
+/**
+ * Permanent-damage threshold (per region) above which a fractured region
+ * causes phantom pain during rest.
+ */
+export const PHANTOM_PAIN_THRESHOLD = q(0.30);
+/**
+ * Phantom pain shock injection per day per qualifying fractured region [Q/day].
+ * Scaled by the region's (permanentDamage / SCALE.Q) ratio.
+ */
+export const PHANTOM_PAIN_Q_PER_DAY = q(0.02); // 200 Q/day at max permanent damage
+/**
+ * Trauma decay per day [Q/day] — natural recovery rate of traumaState.severity_Q.
+ * Slow: severe trauma takes months to fully resolve.
+ */
+export const TRAUMA_DECAY_Q_PER_DAY = q(0.002); // 20 Q/day
+/**
+ * Minimum shock increment that registers as a traumatic event.
+ * Events below this threshold are too minor to compound PTSD-like symptoms.
+ */
+export const TRAUMA_TRIGGER_THRESHOLD = q(0.20);
+/**
+ * Fraction of a shock increment that accumulates as trauma severity.
+ * q(0.30) → a q(1.0) shock event contributes q(0.30) to trauma severity.
+ */
+const TRAUMA_ACCUMULATION_RATE = q(0.30);
+/**
+ * Maximum fear-threshold reduction from trauma (q(0.50) → trauma halves
+ * the effective fear threshold, making entities fearful at lower stimuli).
+ */
+const TRAUMA_FEAR_MUL_FLOOR = q(0.50);
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Advance long-term wound state by `elapsedSeconds`.
+ *
+ * Intended for downtime / long-rest simulation (hours to weeks of elapsed time).
+ * At sub-minute resolution this function does nothing observable.
+ *
+ * Mutates:
+ *   entity.injury.byRegion  (surface/internal damage healed or worsened)
+ *   entity.injury.shock     (phantom pain)
+ *   entity.energy.fatigue   (chronic fatigue drain)
+ *   entity.traumaState      (natural severity decay)
+ *
+ * @param elapsedSeconds  Wall-clock seconds elapsed (use 86400 per game-day).
+ * @returns WoundAgingResult summary (healed, worsened, newSepsis).
+ */
+export function stepWoundAging(entity, elapsedSeconds) {
+    const days = elapsedSeconds / SECONDS_PER_DAY;
+    const result = {
+        healedRegions: [],
+        worsenedRegions: [],
+        newSepsis: false,
+    };
+    const regions = entity.injury.byRegion;
+    const regionEntries = Object.entries(regions);
+    let totalPermanent = 0;
+    let regionCount = 0;
+    for (const [regionId, reg] of regionEntries) {
+        regionCount++;
+        const prevSurface = reg.surfaceDamage;
+        const prevInternal = reg.internalDamage;
+        const perm = reg.permanentDamage;
+        totalPermanent += perm;
+        if (reg.infectedTick !== -1) {
+            // ── Infection worsening ────────────────────────────────────────────────
+            const worsenAmount = Math.round(INFECTION_WORSEN_Q_PER_DAY * days);
+            reg.internalDamage = clampQ((reg.internalDamage + worsenAmount), q(0), q(1.0));
+            if (reg.internalDamage > prevInternal) {
+                result.worsenedRegions.push(regionId);
+            }
+            // Sepsis: infected region has crossed the critical threshold
+            if (!result.newSepsis && reg.internalDamage >= SEPSIS_THRESHOLD && prevInternal < SEPSIS_THRESHOLD) {
+                result.newSepsis = true;
+            }
+        }
+        else {
+            // ── Healing ───────────────────────────────────────────────────────────
+            const surfaceHeal = Math.round(SURFACE_HEAL_Q_PER_DAY * days);
+            const internalHeal = Math.round(INTERNAL_HEAL_Q_PER_DAY * days);
+            reg.surfaceDamage = clampQ((reg.surfaceDamage - surfaceHeal), perm, q(1.0));
+            reg.internalDamage = clampQ((reg.internalDamage - internalHeal), perm, q(1.0));
+            if (reg.surfaceDamage < prevSurface || reg.internalDamage < prevInternal) {
+                result.healedRegions.push(regionId);
+            }
+        }
+        // ── Phantom pain ──────────────────────────────────────────────────────────
+        if (reg.fractured && reg.permanentDamage >= PHANTOM_PAIN_THRESHOLD) {
+            // Shock injection scaled by permanent damage fraction
+            const painQ = Math.round(PHANTOM_PAIN_Q_PER_DAY * days * reg.permanentDamage / SCALE.Q);
+            if (painQ > 0) {
+                entity.injury.shock = clampQ((entity.injury.shock + painQ), q(0), SCALE.Q);
+            }
+        }
+    }
+    // ── Chronic fatigue ────────────────────────────────────────────────────────
+    if (regionCount > 0) {
+        const avgPermanent = totalPermanent / regionCount;
+        if (avgPermanent >= CHRONIC_FATIGUE_THRESHOLD) {
+            const fatigueInc = Math.round(CHRONIC_FATIGUE_Q_PER_DAY * days * avgPermanent / SCALE.Q);
+            if (fatigueInc > 0) {
+                entity.energy.fatigue = clampQ((entity.energy.fatigue + fatigueInc), q(0), SCALE.Q);
+            }
+        }
+    }
+    // ── Trauma natural decay ───────────────────────────────────────────────────
+    if (entity.traumaState && entity.traumaState.severity_Q > 0) {
+        const decayAmount = Math.round(TRAUMA_DECAY_Q_PER_DAY * days);
+        entity.traumaState.severity_Q = clampQ((entity.traumaState.severity_Q - decayAmount), q(0), SCALE.Q);
+    }
+    return result;
+}
+// ── Trauma utilities ──────────────────────────────────────────────────────────
+/**
+ * Record a traumatic shock event, accumulating PTSD-like severity.
+ *
+ * Only events at or above TRAUMA_TRIGGER_THRESHOLD (q(0.20)) register.
+ * A q(1.0) shock event contributes q(0.30) to `traumaState.severity_Q`.
+ *
+ * Mutates: entity.traumaState (created if absent).
+ *
+ * @param shockIncrement_Q  The shock delta from the triggering event (Q).
+ */
+export function recordTraumaEvent(entity, shockIncrement_Q) {
+    if (shockIncrement_Q < TRAUMA_TRIGGER_THRESHOLD)
+        return;
+    if (!entity.traumaState) {
+        entity.traumaState = { severity_Q: q(0) };
+    }
+    const increment = Math.round(shockIncrement_Q * TRAUMA_ACCUMULATION_RATE / SCALE.Q);
+    entity.traumaState.severity_Q = clampQ((entity.traumaState.severity_Q + increment), q(0), SCALE.Q);
+}
+/**
+ * Derive the effective fear-threshold multiplier from accumulated trauma.
+ *
+ * Returns Q in [TRAUMA_FEAR_MUL_FLOOR, SCALE.Q]:
+ *   q(1.0) → no trauma — fear threshold unchanged.
+ *   q(0.50) → maximum trauma — entity triggers fear at half normal threshold.
+ *
+ * Usage (combat / morale layer):
+ *   `effectiveFearThreshold_Q = Math.round(baseFearThreshold_Q × mul / SCALE.Q)`
+ */
+export function deriveFearThresholdMul(entity) {
+    if (!entity.traumaState || entity.traumaState.severity_Q <= 0) {
+        return SCALE.Q;
+    }
+    // severity q(1.0) → reduction q(0.50); linear interpolation
+    const reduction = Math.round(entity.traumaState.severity_Q * (SCALE.Q - TRAUMA_FEAR_MUL_FLOOR) / SCALE.Q);
+    return clampQ((SCALE.Q - reduction), TRAUMA_FEAR_MUL_FLOOR, SCALE.Q);
+}
+/**
+ * Compute aggregate sepsis risk (Q 0..SCALE.Q) from all infected regions.
+ *
+ * Risk increases with both the number of infected regions and their
+ * internal damage level. Returns q(0) if no infected regions.
+ *
+ * Usage: AI / medical layer reads this to prioritise treatment.
+ */
+export function deriveSepsisRisk(entity) {
+    let totalRisk = 0;
+    for (const reg of Object.values(entity.injury.byRegion)) {
+        if (reg.infectedTick !== -1) {
+            // Risk contribution: internalDamage fraction of the infected region
+            totalRisk += reg.internalDamage;
+        }
+    }
+    return clampQ(totalRisk, q(0), SCALE.Q);
+}

package/dist/src/species.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Phase 31 — Species & Race System
+ *
+ * Data-driven species definitions that compose Archetype + BodyPlan + innate traits
+ * + capabilities + physiological overrides into a single declarative record.
+ *
+ * Covers:
+ *   Fantasy humanoids  — elf, dwarf, halfling, orc, ogre, goblin, troll (7)
+ *   Sci-fi humanoids   — Vulcan, Klingon, Romulan (3)
+ *   Mythological       — dragon, centaur, satyr (3)
+ *   Fictional          — Heechee (1)
+ */
+import type { Archetype } from "./archetypes.js";
+import type { IndividualAttributes } from "./types.js";
+import type { BodyPlan } from "./sim/bodyplan.js";
+import type { TraitId } from "./traits.js";
+import type { CapabilitySource } from "./sim/capability.js";
+import type { Weapon } from "./equipment.js";
+import type { SkillMap } from "./sim/skills.js";
+import { type Q } from "./units.js";
+/** Runtime metabolic overrides attached to Entity.physiology (Phase 31). */
+export interface SpeciesPhysiology {
+    /** True = ectotherm; stepCoreTemp is skipped entirely in the kernel. */
+    coldBlooded?: boolean;
+    /**
+     * Multiply the computed BMR before caloric drain.
+     * q(1.0) = normal; q(0.70) = slower starvation (e.g. meditative Vulcan);
+     * q(1.20) = high metabolism (e.g. aggressive Klingon).
+     */
+    bmrMultiplier?: Q;
+    /**
+     * Natural fur / scales / blubber insulation added to the armour insulation sum.
+     * Same unit as Armour.insulation_m2KW [m²K/W].
+     * Troll hide ≈ 0.08, Dragon scales ≈ 0.05.
+     */
+    naturalInsulation_m2KW?: number;
+}
+/**
+ * Everything `generateSpeciesIndividual` returns — the caller uses this to
+ * assemble a full Entity (set attributes, physiology, bodyPlan, apply traits,
+ * attach capabilities, add natural weapons to loadout).
+ */
+export interface SpeciesEntitySpec {
+    attributes: IndividualAttributes;
+    physiology?: SpeciesPhysiology;
+    bodyPlan?: BodyPlan;
+    innateTraits: TraitId[];
+    innateCapabilities: CapabilitySource[];
+    naturalWeapons: Weapon[];
+    skillAptitudes?: SkillMap;
+}
+/** Declarative species record. */
+export interface SpeciesDefinition {
+    id: string;
+    name: string;
+    description: string;
+    archetype: Archetype;
+    bodyPlan?: BodyPlan;
+    innateTraits?: TraitId[];
+    innateCapabilities?: CapabilitySource[];
+    naturalWeapons?: Weapon[];
+    physiology?: SpeciesPhysiology;
+    skillAptitudes?: SkillMap;
+    lore?: string;
+}
+/**
+ * Generate an individual from a species definition using a deterministic seed.
+ * Applies innate traits via `applyTraitsToAttributes` (which deep-copies attrs).
+ */
+export declare function generateSpeciesIndividual(species: SpeciesDefinition, seed: number): SpeciesEntitySpec;
+/** Elf — graceful, keen-sensed, sylvan endurance. */
+export declare const ELF_SPECIES: SpeciesDefinition;
+/** Dwarf — stocky, dense-boned, underground-adapted. */
+export declare const DWARF_SPECIES: SpeciesDefinition;
+/** Halfling — small, nimble, with surprising resilience. */
+export declare const HALFLING_SPECIES: SpeciesDefinition;
+/** Orc — powerful, pain-ignorant, high metabolic rate. */
+export declare const ORC_SPECIES: SpeciesDefinition;
+/** Ogre — massive, brutish, very slow decision-making. */
+export declare const OGRE_SPECIES: SpeciesDefinition;
+/** Goblin — small, cowardly, extremely fast reactions. */
+export declare const GOBLIN_SPECIES: SpeciesDefinition;
+/** Troll — massive regenerator, devastatingly vulnerable to fire. */
+export declare const TROLL_SPECIES: SpeciesDefinition;
+/** Vulcan — disciplined, strong, meditative metabolism; very low individual variance. */
+export declare const VULCAN_SPECIES: SpeciesDefinition;
+/** Klingon — aggressive warrior with redundant organs and thick cranial ridges. */
+export declare const KLINGON_SPECIES: SpeciesDefinition;
+/** Romulan — disciplined but more emotionally variable than Vulcans. */
+export declare const ROMULAN_SPECIES: SpeciesDefinition;
+/** Dragon — immense fire-breathing reptilian with scales and flight capability. */
+export declare const DRAGON_SPECIES: SpeciesDefinition;
+/** Centaur — horse body with human torso; CENTAUR_PLAN anatomy. */
+export declare const CENTAUR_SPECIES: SpeciesDefinition;
+/** Satyr — goat-human hybrid with natural horn and extraordinary balance. */
+export declare const SATYR_SPECIES: SpeciesDefinition;
+/**
+ * Heechee — Fred Pohl's Gateway aliens.
+ * Thin, soft-bodied, technologically advanced; fragile but extraordinarily precise.
+ */
+export declare const HEECHEE_SPECIES: SpeciesDefinition;
+export declare const FANTASY_HUMANOID_SPECIES: readonly SpeciesDefinition[];
+export declare const SCIFI_HUMANOID_SPECIES: readonly SpeciesDefinition[];
+export declare const MYTHOLOGICAL_SPECIES: readonly SpeciesDefinition[];
+export declare const FICTIONAL_SPECIES: readonly SpeciesDefinition[];
+export declare const ALL_SPECIES: readonly SpeciesDefinition[];