@its-not-rocket-science/ananke 0.1.0

package/dist/src/sim/hazard.js

@@ -0,0 +1,201 @@
+// src/sim/hazard.ts — Phase 60: Environmental Hazard Zones
+//
+// Persistent 2-D circular hazard zones that inflict per-second effects on entities
+// within their radius. Five hazard types cover the main environmental threats:
+//
+//   fire         — fatigue drain, thermal heating, surface damage
+//   radiation    — cumulative dose accumulation (see Phase 53 radiation_dose toxin)
+//   toxic_gas    — fatigue drain + disease exposure (marsh_fever by default)
+//   acid         — surface damage, minor fatigue
+//   extreme_cold — thermal cooling, fatigue from shivering
+//
+// Exposure model: linear falloff from full intensity at the hazard centre to zero
+// at the edge. Effects are per-second rates; the host multiplies by dt.
+//
+//   exposureQ = max(0, (radius − dist) × intensity / radius)   [0..intensity_Q]
+//
+// Temperature offsets (thermalDelta_Q) use the same Q-per-degree encoding as
+// Phase 29/51 (WEATHER_Q_PER_DEG_C ≈ 185; so 1 000 Q ≈ +5.4 °C, −2 000 Q ≈ −10.8 °C).
+//
+// Public API:
+//   computeDistToHazard(x_Sm, y_Sm, hazard)          → SCALE.m
+//   isInsideHazard(x_Sm, y_Sm, hazard)                → boolean
+//   computeHazardExposure(dist_Sm, hazard)             → Q [0..intensity_Q]
+//   deriveHazardEffect(hazard, exposureQ)              → HazardEffect (per-second rates)
+//   stepHazardZone(hazard, elapsedSeconds)             → mutates hazard.durationSeconds
+//   isHazardExpired(hazard)                            → boolean
+import { q, clampQ, to, SCALE } from "../units.js";
+/** All hazard type identifiers (useful for validation and iteration). */
+export const ALL_HAZARD_TYPES = [
+    "fire", "radiation", "toxic_gas", "acid", "extreme_cold",
+];
+const BASE_EFFECTS = {
+    fire: {
+        fatigueInc_Q: q(0.0333), // 3.33 % fatigue/s at full intensity → fully fatigued in 30 s
+        thermalDelta_Q: 1_000, // ≈ +5.4 °C ambient bias
+        radiationDose_Q: q(0),
+        surfaceDamageInc_Q: q(0.005), // 0.5 % surface damage/s
+    },
+    radiation: {
+        fatigueInc_Q: q(0),
+        thermalDelta_Q: 0,
+        radiationDose_Q: q(0.010), // 1 % cumulative dose/s at full exposure
+        surfaceDamageInc_Q: q(0),
+    },
+    toxic_gas: {
+        fatigueInc_Q: q(0.010), // 1 % fatigue/s
+        thermalDelta_Q: 0,
+        radiationDose_Q: q(0),
+        surfaceDamageInc_Q: q(0),
+        diseaseExposureId: "marsh_fever",
+    },
+    acid: {
+        fatigueInc_Q: q(0.005), // 0.5 % fatigue/s (chemical burns)
+        thermalDelta_Q: 0,
+        radiationDose_Q: q(0),
+        surfaceDamageInc_Q: q(0.015), // 1.5 % surface damage/s
+    },
+    extreme_cold: {
+        fatigueInc_Q: q(0.008), // 0.8 % fatigue/s (shivering)
+        thermalDelta_Q: -2_000, // ≈ −10.8 °C ambient bias
+        radiationDose_Q: q(0),
+        surfaceDamageInc_Q: q(0),
+    },
+};
+const ZERO_EFFECT = {
+    fatigueInc_Q: q(0),
+    thermalDelta_Q: 0,
+    radiationDose_Q: q(0),
+    surfaceDamageInc_Q: q(0),
+};
+// ── Sample hazard zones ───────────────────────────────────────────────────────
+/** A modest campfire — 3 m radius, 1-hour duration. */
+export const CAMPFIRE = {
+    id: "campfire",
+    type: "fire",
+    x_Sm: 0,
+    y_Sm: 0,
+    radius_Sm: to.m(3),
+    intensity_Q: q(0.60),
+    durationSeconds: 3_600,
+};
+/** A contaminated crater — 50 m radius, permanent. */
+export const RADIATION_ZONE = {
+    id: "radiation_zone",
+    type: "radiation",
+    x_Sm: 0,
+    y_Sm: 0,
+    radius_Sm: to.m(50),
+    intensity_Q: q(0.40),
+    durationSeconds: -1, // permanent
+};
+/** A drifting toxic-gas cloud — 20 m radius, 30-minute duration. */
+export const MUSTARD_GAS = {
+    id: "mustard_gas",
+    type: "toxic_gas",
+    x_Sm: 0,
+    y_Sm: 0,
+    radius_Sm: to.m(20),
+    intensity_Q: q(0.80),
+    durationSeconds: 1_800,
+};
+/** A corrosive acid pool — 2 m radius, 2-hour duration. */
+export const ACID_POOL = {
+    id: "acid_pool",
+    type: "acid",
+    x_Sm: 0,
+    y_Sm: 0,
+    radius_Sm: to.m(2),
+    intensity_Q: q(0.90),
+    durationSeconds: 7_200,
+};
+/** A severe cold zone — 100 m radius, 6-hour duration. */
+export const BLIZZARD_ZONE = {
+    id: "blizzard_zone",
+    type: "extreme_cold",
+    x_Sm: 0,
+    y_Sm: 0,
+    radius_Sm: to.m(100),
+    intensity_Q: q(0.70),
+    durationSeconds: 21_600,
+};
+/** All sample hazard zones. */
+export const ALL_SAMPLE_HAZARDS = [
+    CAMPFIRE, RADIATION_ZONE, MUSTARD_GAS, ACID_POOL, BLIZZARD_ZONE,
+];
+// ── Core computation ──────────────────────────────────────────────────────────
+/**
+ * Euclidean distance from a world position to the hazard centre [SCALE.m].
+ *
+ * Uses float sqrt for a one-time calculation; result is truncated to integer.
+ */
+export function computeDistToHazard(x_Sm, y_Sm, hazard) {
+    const dx = x_Sm - hazard.x_Sm;
+    const dy = y_Sm - hazard.y_Sm;
+    return Math.trunc(Math.sqrt(dx * dx + dy * dy));
+}
+/**
+ * True if the given position is within or on the hazard boundary.
+ *
+ * Uses integer squared-distance comparison to avoid float precision issues.
+ */
+export function isInsideHazard(x_Sm, y_Sm, hazard) {
+    const dx = x_Sm - hazard.x_Sm;
+    const dy = y_Sm - hazard.y_Sm;
+    return dx * dx + dy * dy <= hazard.radius_Sm * hazard.radius_Sm;
+}
+/**
+ * Compute the exposure intensity at a given distance from the hazard centre.
+ *
+ * Linear falloff:  `exposure = (radius − dist) × intensity / radius`
+ * Returns `q(0)` when `dist >= radius`.
+ *
+ * @param dist_Sm  Distance from hazard centre [SCALE.m].
+ */
+export function computeHazardExposure(dist_Sm, hazard) {
+    if (dist_Sm >= hazard.radius_Sm || hazard.intensity_Q <= 0)
+        return q(0);
+    return clampQ(Math.round((hazard.radius_Sm - dist_Sm) * hazard.intensity_Q / hazard.radius_Sm), q(0), SCALE.Q);
+}
+/**
+ * Derive per-second hazard effect rates from an exposure level.
+ *
+ * `exposureQ` is the output of `computeHazardExposure` — already in [0, intensity_Q].
+ * Each base rate is scaled linearly: `rate = base × exposureQ / SCALE.Q`.
+ *
+ * `thermalDelta_Q` uses the same scaling so the thermal offset fades toward the
+ * hazard boundary.
+ *
+ * Returns a zero-effect record when `exposureQ <= 0`.
+ */
+export function deriveHazardEffect(hazard, exposureQ) {
+    if (exposureQ <= 0)
+        return { ...ZERO_EFFECT };
+    const b = BASE_EFFECTS[hazard.type];
+    return {
+        fatigueInc_Q: clampQ(Math.round(b.fatigueInc_Q * exposureQ / SCALE.Q), 0, SCALE.Q),
+        thermalDelta_Q: Math.round(b.thermalDelta_Q * exposureQ / SCALE.Q),
+        radiationDose_Q: clampQ(Math.round(b.radiationDose_Q * exposureQ / SCALE.Q), 0, SCALE.Q),
+        surfaceDamageInc_Q: clampQ(Math.round(b.surfaceDamageInc_Q * exposureQ / SCALE.Q), 0, SCALE.Q),
+        ...(b.diseaseExposureId ? { diseaseExposureId: b.diseaseExposureId } : {}),
+    };
+}
+// ── Lifecycle ─────────────────────────────────────────────────────────────────
+/**
+ * Advance a hazard zone's lifetime by `elapsedSeconds`.
+ *
+ * Permanent hazards (`durationSeconds === -1`) are untouched.
+ * Mutates: `hazard.durationSeconds`.
+ */
+export function stepHazardZone(hazard, elapsedSeconds) {
+    if (hazard.durationSeconds < 0)
+        return;
+    hazard.durationSeconds = Math.max(0, hazard.durationSeconds - elapsedSeconds);
+}
+/**
+ * True when the hazard has run out of duration and should be removed from the world.
+ * Always false for permanent hazards.
+ */
+export function isHazardExpired(hazard) {
+    return hazard.durationSeconds >= 0 && hazard.durationSeconds === 0;
+}

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

@@ -0,0 +1,58 @@
+import type { Q } from "../units.js";
+import { BodyRegion, BoneRegion, MajorOrgan } from "./body.js";
+import { BodySegment } from "./bodyplan.js";
+/** Minimum projectile velocity for temporary cavity effect (600 m/s in SCALE.mps). */
+export declare const HYDROSTATIC_THRESHOLD_mps: number;
+/** Minimum projectile velocity for cavitation bleed bonus (900 m/s in SCALE.mps). */
+export declare const CAVITATION_THRESHOLD_mps: number;
+/**
+ * Tissue compliance by region: lower = less elastic = more temporary cavity damage.
+ * Look up by region id; fall back to DEFAULT_COMPLIANCE for unknown regions.
+ *
+ * Reference values (lower bound = bone q(0.05), upper = elastic muscle q(0.60)):
+ *   bone/skull — q(0.05): extremely brittle; cavitation causes shattering
+ *   brain/liver/spleen — q(0.10): very inelastic fluid organs
+ *   lung — q(0.30): intermediate; partially elastic air-filled tissue
+ *   muscle/torso — q(0.60): moderately elastic
+ */
+export declare const TISSUE_COMPLIANCE: Record<BodyRegion | BodySegment["id"] | MajorOrgan | BoneRegion, Q>;
+export type TISSUE_COMPLIANCE_KEY = keyof typeof TISSUE_COMPLIANCE;
+/** Compliance used when a region is not in the table (muscle-level). */
+export declare const DEFAULT_COMPLIANCE: Q;
+/**
+ * Compute the temporary-cavity multiplier on internal-fraction damage.
+ *
+ * Returns a Q-scaled integer multiplier: `q(1.0)` = no extra damage, `q(3.0)` = maximum.
+ * Only activates when `v_impact > HYDROSTATIC_THRESHOLD_mps`.
+ *
+ * Formula (fixed-point):
+ *   v_ratio_Q = (v / 600)² × SCALE.Q
+ *   tissue_factor_Q = v_ratio_Q × (SCALE.Q − compliance_Q) / SCALE.Q
+ *   result = clamp(q(1.0) + tissue_factor_Q, q(1.0), q(3.0))
+ *
+ * Calibration:
+ *   9mm (370 m/s)    → q(1.0)  (below gate) ✓
+ *   5.56mm (960 m/s) → q(3.0)  for liver; q(2.0) for muscle ✓
+ *   subsonic .45 ACP (270 m/s) → q(1.0) ✓
+ *
+ * @param v_impact   Projectile velocity at impact point (SCALE.mps units).
+ * @param region     Hit region id.
+ */
+export declare function computeTemporaryCavityMul(v_impact: number, region: TISSUE_COMPLIANCE_KEY): Q;
+/**
+ * Apply cavitation-induced haemorrhage boost to a region's bleedingRate.
+ *
+ * Only active when:
+ *   - `v_impact > CAVITATION_THRESHOLD_mps` (900 m/s)
+ *   - `region` is fluid-saturated tissue (lung, liver, spleen, torso, legs)
+ *
+ * Formula:
+ *   cavMul = q(1.0) + (v − 900) / 300  [in Q-space]
+ *   newBleed = clamp(currentBleed × cavMul, 0, q(1.0))
+ *
+ * @param v_impact     Projectile velocity at impact (SCALE.mps units).
+ * @param currentBleed Existing bleedingRate after primary wound application (Q integer).
+ * @param region       Hit region id (bone and non-fluid regions return unchanged bleed).
+ * @returns            Updated bleedingRate (Q integer, clamped to q(1.0) max).
+ */
+export declare function computeCavitationBleed(v_impact: number, currentBleed: number, region: string): number;

package/dist/src/sim/hydrostatic.js

@@ -0,0 +1,117 @@
+// src/sim/hydrostatic.ts — Phase 27: Hydrostatic Shock & Cavitation
+//
+// High-velocity projectiles (> 600 m/s) produce a temporary radial stretch wave
+// that amplifies internal damage in inelastic tissue. Above 900 m/s, momentary
+// vacuum cavitation further increases haemorrhage in fluid-saturated tissue.
+//
+// This module is pure computation — no entity mutation, no RNG.
+import { SCALE, q, clampQ, mulDiv } from "../units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Minimum projectile velocity for temporary cavity effect (600 m/s in SCALE.mps). */
+export const HYDROSTATIC_THRESHOLD_mps = Math.trunc(600 * SCALE.mps);
+/** Minimum projectile velocity for cavitation bleed bonus (900 m/s in SCALE.mps). */
+export const CAVITATION_THRESHOLD_mps = Math.trunc(900 * SCALE.mps);
+// ── Tissue compliance ─────────────────────────────────────────────────────────
+/**
+ * Tissue compliance by region: lower = less elastic = more temporary cavity damage.
+ * Look up by region id; fall back to DEFAULT_COMPLIANCE for unknown regions.
+ *
+ * Reference values (lower bound = bone q(0.05), upper = elastic muscle q(0.60)):
+ *   bone/skull — q(0.05): extremely brittle; cavitation causes shattering
+ *   brain/liver/spleen — q(0.10): very inelastic fluid organs
+ *   lung — q(0.30): intermediate; partially elastic air-filled tissue
+ *   muscle/torso — q(0.60): moderately elastic
+ */
+export const TISSUE_COMPLIANCE = {
+    // Organ segments (advanced body plans)
+    brain: q(0.10),
+    liver: q(0.10),
+    spleen: q(0.10),
+    lung: q(0.30),
+    // Humanoid string-literal regions
+    head: q(0.10), // brain-dominated
+    torso: q(0.40), // mixed thoracic/abdominal
+    leftArm: q(0.60),
+    rightArm: q(0.60),
+    leftLeg: q(0.60),
+    rightLeg: q(0.60),
+    // Bone segment ids
+    bone: q(0.05),
+    skull: q(0.05),
+    femur: q(0.05),
+    tibia: q(0.05),
+};
+/** Compliance used when a region is not in the table (muscle-level). */
+export const DEFAULT_COMPLIANCE = q(0.60);
+/**
+ * Region ids susceptible to cavitation bubble formation.
+ * Excludes bone (non-fluid) and brain (inelastic but not vascular enough for macroscopic bubbles).
+ */
+const CAVITATION_TISSUE = new Set([
+    "lung", "liver", "spleen",
+    "torso", "leftLeg", "rightLeg",
+]);
+// ── computeTemporaryCavityMul ─────────────────────────────────────────────────
+/**
+ * Compute the temporary-cavity multiplier on internal-fraction damage.
+ *
+ * Returns a Q-scaled integer multiplier: `q(1.0)` = no extra damage, `q(3.0)` = maximum.
+ * Only activates when `v_impact > HYDROSTATIC_THRESHOLD_mps`.
+ *
+ * Formula (fixed-point):
+ *   v_ratio_Q = (v / 600)² × SCALE.Q
+ *   tissue_factor_Q = v_ratio_Q × (SCALE.Q − compliance_Q) / SCALE.Q
+ *   result = clamp(q(1.0) + tissue_factor_Q, q(1.0), q(3.0))
+ *
+ * Calibration:
+ *   9mm (370 m/s)    → q(1.0)  (below gate) ✓
+ *   5.56mm (960 m/s) → q(3.0)  for liver; q(2.0) for muscle ✓
+ *   subsonic .45 ACP (270 m/s) → q(1.0) ✓
+ *
+ * @param v_impact   Projectile velocity at impact point (SCALE.mps units).
+ * @param region     Hit region id.
+ */
+export function computeTemporaryCavityMul(v_impact, region) {
+    if (v_impact <= HYDROSTATIC_THRESHOLD_mps)
+        return q(1.0);
+    const compliance_Q = TISSUE_COMPLIANCE[region] ?? DEFAULT_COMPLIANCE;
+    // (v / threshold)² in Q-units — BigInt prevents integer overflow
+    // Max practical v: ~2000 m/s = 2×10^7; v² = 4×10^14 → safe in BigInt
+    const vB = BigInt(v_impact);
+    const tB = BigInt(HYDROSTATIC_THRESHOLD_mps);
+    const v_ratio_Q = Number((vB * vB * BigInt(SCALE.Q)) / (tB * tB));
+    // tissue_factor_Q = v_ratio_Q × (1 − compliance) — both in Q-space
+    const tissue_factor_Q = mulDiv(v_ratio_Q, SCALE.Q - compliance_Q, SCALE.Q);
+    // result = q(1.0) + tissue_factor_Q, clamped to [q(1.0), q(3.0)]
+    return clampQ(SCALE.Q + tissue_factor_Q, SCALE.Q, 3 * SCALE.Q);
+}
+// ── computeCavitationBleed ────────────────────────────────────────────────────
+/**
+ * Apply cavitation-induced haemorrhage boost to a region's bleedingRate.
+ *
+ * Only active when:
+ *   - `v_impact > CAVITATION_THRESHOLD_mps` (900 m/s)
+ *   - `region` is fluid-saturated tissue (lung, liver, spleen, torso, legs)
+ *
+ * Formula:
+ *   cavMul = q(1.0) + (v − 900) / 300  [in Q-space]
+ *   newBleed = clamp(currentBleed × cavMul, 0, q(1.0))
+ *
+ * @param v_impact     Projectile velocity at impact (SCALE.mps units).
+ * @param currentBleed Existing bleedingRate after primary wound application (Q integer).
+ * @param region       Hit region id (bone and non-fluid regions return unchanged bleed).
+ * @returns            Updated bleedingRate (Q integer, clamped to q(1.0) max).
+ */
+export function computeCavitationBleed(v_impact, currentBleed, region) {
+    if (v_impact <= CAVITATION_THRESHOLD_mps)
+        return currentBleed;
+    if (!CAVITATION_TISSUE.has(region))
+        return currentBleed;
+    if (currentBleed <= 0)
+        return currentBleed;
+    const CAVITATION_RANGE_mps = Math.trunc(300 * SCALE.mps);
+    const v_excess = v_impact - CAVITATION_THRESHOLD_mps;
+    const bleedBonus_Q = mulDiv(v_excess, SCALE.Q, CAVITATION_RANGE_mps);
+    const cavMul_Q = SCALE.Q + bleedBonus_Q; // q(1.0) + proportional bonus
+    return Math.min(SCALE.Q, mulDiv(currentBleed, cavMul_Q, SCALE.Q));
+}

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

@@ -0,0 +1,20 @@
+import type { Q } from "../units.js";
+import { type Entity } from "./entity.js";
+import type { SimulationTuning } from "./tuning.js";
+export interface FunctionalState {
+    mobilityMul: Q;
+    manipulationMul: Q;
+    coordinationMul: Q;
+    staminaMul: Q;
+    leftArmDisabled: boolean;
+    rightArmDisabled: boolean;
+    leftLegDisabled: boolean;
+    rightLegDisabled: boolean;
+    canStand: boolean;
+    canAct: boolean;
+    disabledFunctions: ReadonlySet<string>;
+}
+export declare function deriveFunctionalState(e: Entity, tuning?: SimulationTuning): FunctionalState;
+export declare function hasDisabledFunction(func: FunctionalState, functionId: string): boolean;
+export declare function hasAllDisabledFunctions(func: FunctionalState, ...functionIds: readonly string[]): boolean;
+export declare function hasAnyDisabledFunction(func: FunctionalState, ...functionIds: readonly string[]): boolean;

package/dist/src/sim/impairment.js

@@ -0,0 +1,162 @@
+import { q, clampQ, SCALE, qMul, mulDiv } from "../units.js";
+import { ensureAnatomyRuntime } from "./entity.js";
+import { TUNING } from "./tuning.js";
+const mean2 = (a, b) => Math.trunc((a + b) / 2);
+function applyImpairmentsClamped(base, minOut, maxOut, ...terms) {
+    let out = base;
+    for (const [value, weight] of terms)
+        out = (out - qMul(value, weight));
+    return clampQ(out, minOut, maxOut);
+}
+export function deriveFunctionalState(e, tuning = TUNING.tactical) {
+    const inj = e.injury;
+    const disabledFunctions = computeDisabledFunctions(e, tuning);
+    // Derive legacy booleans from the single source of truth.
+    const leftArmDisabled = disabledFunctions.has("leftManipulation");
+    const rightArmDisabled = disabledFunctions.has("rightManipulation");
+    const leftLegDisabled = disabledFunctions.has("leftLocomotion");
+    const rightLegDisabled = disabledFunctions.has("rightLocomotion");
+    let legStr;
+    let legInt;
+    let armStr;
+    let armInt;
+    let headInt;
+    let headStr;
+    let fractureLegQ = q(0);
+    let fractureArmQ = q(0);
+    const { helpers } = ensureAnatomyRuntime(e);
+    if (helpers?.functionalDamage) {
+        const summary = helpers.functionalDamage.summarize(inj);
+        legStr = summary.mobility.structural;
+        legInt = summary.mobility.internal;
+        armStr = summary.manipulation.structural;
+        armInt = summary.manipulation.internal;
+        headInt = summary.coordination.internal;
+        headStr = summary.coordination.structural;
+        fractureLegQ = summary.mobility.fracture;
+        fractureArmQ = summary.manipulation.fracture;
+    }
+    else {
+        // Backward compat: humanoid hardcoded regions
+        const leftArmStr = inj.byRegion.leftArm?.structuralDamage ?? q(0);
+        const rightArmStr = inj.byRegion.rightArm?.structuralDamage ?? q(0);
+        const leftLegStr = inj.byRegion.leftLeg?.structuralDamage ?? q(0);
+        const rightLegStr = inj.byRegion.rightLeg?.structuralDamage ?? q(0);
+        const leftLegIntVal = inj.byRegion.leftLeg?.internalDamage ?? q(0);
+        const rightLegIntVal = inj.byRegion.rightLeg?.internalDamage ?? q(0);
+        const leftArmIntVal = inj.byRegion.leftArm?.internalDamage ?? q(0);
+        const rightArmIntVal = inj.byRegion.rightArm?.internalDamage ?? q(0);
+        legStr = mean2(leftLegStr, rightLegStr);
+        legInt = mean2(leftLegIntVal, rightLegIntVal);
+        armStr = mean2(leftArmStr, rightArmStr);
+        armInt = mean2(leftArmIntVal, rightArmIntVal);
+        headInt = inj.byRegion.head?.internalDamage ?? q(0);
+        headStr = inj.byRegion.head?.structuralDamage ?? q(0);
+        const leftLegFrac = inj.byRegion.leftLeg?.fractured ?? false;
+        const rightLegFrac = inj.byRegion.rightLeg?.fractured ?? false;
+        const leftArmFrac = inj.byRegion.leftArm?.fractured ?? false;
+        const rightArmFrac = inj.byRegion.rightArm?.fractured ?? false;
+        fractureLegQ = Math.trunc(((leftLegFrac ? 1 : 0) + (rightLegFrac ? 1 : 0)) * SCALE.Q / 2);
+        fractureArmQ = Math.trunc(((leftArmFrac ? 1 : 0) + (rightArmFrac ? 1 : 0)) * SCALE.Q / 2);
+    }
+    const shock = inj.shock;
+    const fatigue = e.energy.fatigue;
+    const stun = e.condition.stunned;
+    const concLoss = (SCALE.Q - inj.consciousness);
+    const fluidLoss = inj.fluidLoss;
+    const pinnedQ = (e.condition?.pinned ?? false) ? SCALE.Q : 0;
+    const heldQ = (e.grapple?.heldByIds?.length ?? 0) > 0 ? SCALE.Q : 0;
+    const suppressedQ = (e.condition.suppressedTicks ?? 0) > 0 ? SCALE.Q : 0;
+    const fearQ = e.condition.fearQ ?? q(0);
+    const EXHAUSTION_THRESHOLD = q(0.15);
+    const baselineReserve = Math.max(1, e.attributes.performance.reserveEnergy_J);
+    const currentReserve = Math.max(0, e.energy.reserveEnergy_J);
+    const reserveRatioQ = clampQ(mulDiv(currentReserve, SCALE.Q, baselineReserve), q(0), q(1.0));
+    const exhaustionQ = reserveRatioQ >= EXHAUSTION_THRESHOLD
+        ? q(0)
+        : clampQ(mulDiv((EXHAUSTION_THRESHOLD - reserveRatioQ), SCALE.Q, EXHAUSTION_THRESHOLD), q(0), q(1.0));
+    const mobilityMul = applyImpairmentsClamped(q(1.0), q(0.05), q(1.0), [legStr, q(0.60)], [legInt, q(0.25)], [shock, q(0.15)], [fatigue, q(0.25)], [stun, q(0.35)], [concLoss, q(0.10)], [pinnedQ, q(0.80)], [heldQ, q(0.30)], [exhaustionQ, q(0.30)], [fractureLegQ, q(0.30)]);
+    const manipulationMul = applyImpairmentsClamped(q(1.0), q(0.05), q(1.0), [armStr, q(0.55)], [armInt, q(0.20)], [shock, q(0.10)], [fatigue, q(0.20)], [stun, q(0.25)], [concLoss, q(0.20)], [pinnedQ, q(0.60)], [heldQ, q(0.20)], [exhaustionQ, q(0.25)], [fearQ, q(0.15)], [fractureArmQ, q(0.25)]);
+    const coordinationMul = applyImpairmentsClamped(q(1.0), q(0.05), q(1.0), [headInt, q(0.45)], [headStr, q(0.15)], [shock, q(0.20)], [fatigue, q(0.20)], [stun, q(0.40)], [concLoss, q(0.35)], [exhaustionQ, q(0.20)], [suppressedQ, q(0.10)], [fearQ, q(0.15)]);
+    const staminaMul = applyImpairmentsClamped(q(1.0), q(0.00), q(1.0), [fatigue, q(0.65)], [shock, q(0.15)], [fluidLoss, q(0.35)], [exhaustionQ, q(0.50)]);
+    const canAct = inj.consciousness >= tuning.unconsciousThreshold && !inj.dead;
+    const legsOut = disabledFunctions.has("leftLocomotion") && disabledFunctions.has("rightLocomotion");
+    const canStand = canAct && !legsOut && mobilityMul >= tuning.standFailThreshold;
+    return {
+        mobilityMul,
+        manipulationMul,
+        coordinationMul,
+        staminaMul,
+        leftArmDisabled,
+        rightArmDisabled,
+        leftLegDisabled,
+        rightLegDisabled,
+        canStand,
+        canAct,
+        disabledFunctions,
+    };
+}
+export function hasDisabledFunction(func, functionId) {
+    return func.disabledFunctions.has(functionId);
+}
+export function hasAllDisabledFunctions(func, ...functionIds) {
+    return functionIds.every((id) => func.disabledFunctions.has(id));
+}
+export function hasAnyDisabledFunction(func, ...functionIds) {
+    return functionIds.some((id) => func.disabledFunctions.has(id));
+}
+function computeDisabledFunctions(e, tuning) {
+    const out = new Set();
+    const { helpers } = ensureAnatomyRuntime(e);
+    if (helpers?.functionalDamage) {
+        // General aggregate functions from anatomy model (no positional IDs here)
+        const fd = helpers.functionalDamage;
+        const candidates = [
+            "mobility", "locomotion", "manipulation", "coordination", "cognition",
+            "cns", "respiration", "circulation", "sensor", "vision", "balance",
+            "stancePosture",
+        ];
+        for (const id of candidates) {
+            if (fd.isFunctionDisabled(e.injury, id))
+                out.add(id);
+        }
+    }
+    // Positional left/right flags: always derived from body plan structure or hardcoded
+    // humanoid region names.  These are not indexed as anatomy-model function IDs.
+    addPositionalFlags(out, e, tuning);
+    return out;
+}
+/**
+ * Populates "leftManipulation", "rightManipulation", "leftLocomotion", "rightLocomotion"
+ * in `out` by inspecting injury thresholds on the primary body-plan segments.
+ *
+ * When a body plan is present the primary segment ordering is used ([0] = left, [1] = right).
+ * When absent the legacy humanoid region names ("leftArm", "rightArm", …) are used.
+ */
+function addPositionalFlags(out, e, tuning) {
+    const byRegion = e.injury.byRegion;
+    const plan = e.bodyPlan;
+    if (plan) {
+        const primaryManip = plan.segments.filter(s => s.manipulationRole === "primary");
+        const primaryLoco = plan.segments.filter(s => s.locomotionRole === "primary");
+        if ((byRegion[primaryManip[0]?.id ?? ""]?.structuralDamage ?? q(0)) >= tuning.armDisableThreshold)
+            out.add("leftManipulation");
+        if ((byRegion[primaryManip[1]?.id ?? ""]?.structuralDamage ?? q(0)) >= tuning.armDisableThreshold)
+            out.add("rightManipulation");
+        if ((byRegion[primaryLoco[0]?.id ?? ""]?.structuralDamage ?? q(0)) >= tuning.legDisableThreshold)
+            out.add("leftLocomotion");
+        if ((byRegion[primaryLoco[1]?.id ?? ""]?.structuralDamage ?? q(0)) >= tuning.legDisableThreshold)
+            out.add("rightLocomotion");
+    }
+    else {
+        // Humanoid fallback
+        if ((byRegion.leftArm?.structuralDamage ?? q(0)) >= tuning.armDisableThreshold)
+            out.add("leftManipulation");
+        if ((byRegion.rightArm?.structuralDamage ?? q(0)) >= tuning.armDisableThreshold)
+            out.add("rightManipulation");
+        if ((byRegion.leftLeg?.structuralDamage ?? q(0)) >= tuning.legDisableThreshold)
+            out.add("leftLocomotion");
+        if ((byRegion.rightLeg?.structuralDamage ?? q(0)) >= tuning.legDisableThreshold)
+            out.add("rightLocomotion");
+    }
+}

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

@@ -0,0 +1,7 @@
+import type { WorldState } from "./world.js";
+import type { Entity } from "./entity.js";
+export interface WorldIndex {
+    byId: Map<number, Entity>;
+    entities: readonly Entity[];
+}
+export declare function buildWorldIndex(world: WorldState): WorldIndex;

package/dist/src/sim/indexing.js

@@ -0,0 +1,7 @@
+export function buildWorldIndex(world) {
+    const byId = new Map();
+    for (const e of world.entities) {
+        byId.set(e.id, e);
+    }
+    return { byId, entities: world.entities };
+}

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

@@ -0,0 +1,54 @@
+import type { Q } from "../units.js";
+/**
+ * Structural damage fraction at which a fracture is recorded.
+ * Once set, `fractured` persists until surgically cleared.
+ */
+export declare const FRACTURE_THRESHOLD: Q;
+export interface RegionInjury {
+    surfaceDamage: Q;
+    internalDamage: Q;
+    structuralDamage: Q;
+    bleedingRate: Q;
+    /** Structural damage has crossed FRACTURE_THRESHOLD; cleared only by surgery. */
+    fractured: boolean;
+    /**
+     * Tick at which infection began; -1 = no infection.
+     * Set when a region bleeds for INFECTION_ONSET_TICKS consecutively with
+     * sufficient internal damage.
+     */
+    infectedTick: number;
+    /** Consecutive ticks the region has been actively bleeding (used for infection timer). */
+    bleedDuration_ticks: number;
+    /**
+     * Irreversible damage floor.  Set when structuralDamage ≥ PERMANENT_THRESHOLD.
+     * Treatment cannot reduce structuralDamage below this value.
+     */
+    permanentDamage: Q;
+}
+export interface InjuryState {
+    /** Keyed by segment id (BodyRegion strings for humanoid, or custom ids for other body plans). */
+    byRegion: Record<string, RegionInjury>;
+    fluidLoss: Q;
+    shock: Q;
+    consciousness: Q;
+    dead: boolean;
+    /** Phase 8B forward compat: hemolymph loss for open-fluid exoskeleton segments (0..1). */
+    hemolymphLoss: Q;
+}
+export declare const defaultRegionInjury: () => RegionInjury;
+/**
+ * Create a default InjuryState for the given segment ids.
+ * When omitted, defaults to the standard humanoid six regions.
+ */
+export declare const defaultInjury: (segmentIds?: readonly string[]) => InjuryState;
+export type DamageType = 'surfaceDamage' | 'internalDamage' | 'structuralDamage' | 'bleedingRate';
+export declare function totalSurfaceDamage(i: InjuryState): Q;
+export declare function totalInternalDamage(i: InjuryState): Q;
+export declare function totalStructuralDamage(i: InjuryState): Q;
+export declare function totalBleedingRate(i: InjuryState): Q;
+/**
+ * Compute KO risk from CNS-critical region damage.
+ * For humanoid and any plan that uses "head"/"torso" segment ids.
+ * For other body plans, falls back gracefully to q(0) for absent segments.
+ */
+export declare function regionKOFactor(i: InjuryState): Q;