@its-not-rocket-science/ananke 0.1.0

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

@@ -0,0 +1,150 @@
+import { type Q } from "../units.js";
+import type { Entity } from "./entity.js";
+/** Movement gait of the mounted pair. */
+export type MountGait = "walk" | "trot" | "gallop" | "charge";
+/** Species-level mount data record. */
+export interface MountProfile {
+    id: string;
+    name: string;
+    /** Body mass of the mount [SCALE.kg]. */
+    mass_kg: number;
+    /** Height of rider's seat above ground [SCALE.m]. */
+    riderHeightBonus_m: number;
+    /** Maximum load the mount can carry (rider + equipment) [SCALE.kg]. */
+    maxCarryCapacity_kg: number;
+    /** Walk speed [SCALE.mps]. */
+    walkSpeed_mps: number;
+    /** Trot speed [SCALE.mps]. */
+    trotSpeed_mps: number;
+    /** Gallop speed [SCALE.mps]. */
+    gallopSpeed_mps: number;
+    /** Charge speed — typically faster than gallop [SCALE.mps]. */
+    chargeSpeed_mps: number;
+    /** Mount postural stability [Q]. Partially inherited by rider. */
+    stability_Q: Q;
+    /**
+     * Fear threshold [Q].
+     * When mount shockQ exceeds this value, fear propagates to the rider and
+     * the mount risks bolting (forced dismount).
+     */
+    fearThreshold_Q: Q;
+}
+/** Kinetic energy delivered to a target in a charge attack. */
+export interface ChargeBonus {
+    /** Extra energy delivered to the target [J, SCALE.J = 1]. */
+    bonusEnergy_J: number;
+    /** Effective striking mass (the fraction of mount mass in the impact) [SCALE.kg]. */
+    strikeMass_kg: number;
+}
+/** Why a dismount was triggered. */
+export type DismountCause = "none" | "rider_shock" | "mount_dead" | "mount_bolt";
+/** Result of evaluating one mount/rider tick. */
+export interface MountStepResult {
+    /** True when the rider should be dismounted this tick. */
+    shouldDismount: boolean;
+    /** Reason for the dismount (or "none" if not dismounting). */
+    dismountCause: DismountCause;
+    /** Fall injury energy [J] — non-zero only when shouldDismount is true. */
+    fallEnergy_J: number;
+    /** Fear Q to add to the rider's condition from mount panic [Q]. */
+    fearPressure_Q: Q;
+}
+/**
+ * Per-entity mount/rider pair state, stored on `entity.mount`.
+ *
+ * On the rider entity: `mountId` is set, `riderId` is 0.
+ * On the mount entity: `riderId` is set, `mountId` is 0.
+ */
+export interface MountState {
+    /** Entity ID of the mount being ridden. 0 if this entity is not riding. */
+    mountId: number;
+    /** Entity ID of the rider being carried. 0 if this entity is not a mount. */
+    riderId: number;
+    /** Current movement gait. */
+    gait: MountGait;
+}
+/** Fraction of mount mass that contributes to charge strike energy [Q]. */
+export declare const CHARGE_MASS_FRAC: Q;
+/** Rider shock level above which a forced dismount occurs [Q]. */
+export declare const DISMOUNT_SHOCK_Q: Q;
+/** Aim / accuracy bonus per real metre of rider elevation [Q]. */
+export declare const HEIGHT_AIM_BONUS_PER_M: Q;
+/** Maximum rider height aim bonus (caps at 2.5 m for war elephant) [Q]. */
+export declare const HEIGHT_AIM_BONUS_MAX: Q;
+/** Fraction of mount stability that transfers to the rider [Q]. */
+export declare const RIDER_STABILITY_INHERIT: Q;
+/** Fraction of excess mount-shock (beyond fearThreshold) that propagates to rider [Q]. */
+export declare const MOUNT_FEAR_CONTAGION: Q;
+export declare const PONY: MountProfile;
+export declare const HORSE: MountProfile;
+export declare const WARHORSE: MountProfile;
+export declare const CAMEL: MountProfile;
+export declare const WAR_ELEPHANT: MountProfile;
+/** All mount profiles in one array. */
+export declare const ALL_MOUNTS: MountProfile[];
+/**
+ * Return the mount's speed in SCALE.mps for the given gait.
+ */
+export declare function getMountGaitSpeed(profile: MountProfile, gait: MountGait): number;
+/**
+ * Compute the bonus kinetic energy delivered to a target during a mounted charge.
+ *
+ * Only `CHARGE_MASS_FRAC` (8%) of the mount's mass participates in the impact;
+ * the remainder is absorbed through the mount's body.
+ *
+ * `bonusEnergy_J = ½ × strikeMass × v²`  (SI, result in joules)
+ *
+ * @param speed_Smps  Current charge speed [SCALE.mps].
+ */
+export declare function computeChargeBonus(profile: MountProfile, speed_Smps: number): ChargeBonus;
+/**
+ * Derive the aim/accuracy bonus a rider gains from elevation.
+ *
+ * `aimBonus_Q = (riderHeightBonus_m / SCALE.m) × HEIGHT_AIM_BONUS_PER_M`
+ * Capped at HEIGHT_AIM_BONUS_MAX = q(0.30).
+ */
+export declare function deriveRiderHeightBonus(profile: MountProfile): Q;
+/**
+ * Derive the stability bonus a rider inherits from a well-balanced mount.
+ *
+ * `stabilityBonus_Q = mount.stability_Q × RIDER_STABILITY_INHERIT / SCALE.Q`
+ * Capped at q(0.20).
+ */
+export declare function deriveRiderStabilityBonus(profile: MountProfile): Q;
+/**
+ * Compute the fall injury energy when a rider is dismounted from height.
+ *
+ * Models a free-fall from the rider's seat height:
+ *   fallEnergy_J = riderMass × g × height
+ *
+ * @param riderMass_Skg  Rider's mass [SCALE.kg].
+ */
+export declare function computeFallEnergy_J(profile: MountProfile, riderMass_Skg: number): number;
+/**
+ * Derive the fear pressure transmitted from a panicking mount to its rider.
+ *
+ * Returns q(0) when the mount's shockQ is at or below its fearThreshold.
+ * Above the threshold, 40% of the excess is propagated to the rider.
+ *
+ * @param mountShockQ       Current shock level of the mount [Q].
+ * @param fearThreshold_Q   Mount's panic threshold [Q].
+ */
+export declare function deriveMountFearPressure(mountShockQ: Q, fearThreshold_Q: Q): Q;
+/**
+ * Evaluate a single mounted-combat tick, returning dismount and fear outcomes.
+ *
+ * Does NOT mutate any entity — pure computation for the host to apply.
+ *
+ * Dismount priority: rider_shock > mount_dead > mount_bolt.
+ *
+ * @param riderShockQ   Rider's current shockQ [Q].
+ * @param mountShockQ   Mount's current shockQ [Q].
+ * @param mountDead     True if the mount has died this tick.
+ * @param profile       Mount species profile.
+ * @param riderMass_Skg Rider's mass [SCALE.kg] — used for fall energy.
+ */
+export declare function checkMountStep(riderShockQ: Q, mountShockQ: Q, mountDead: boolean, profile: MountProfile, riderMass_Skg?: number): MountStepResult;
+/** True if this entity is currently riding a mount. */
+export declare function entityIsMounted(entity: Entity): boolean;
+/** True if this entity is currently carrying a rider. */
+export declare function entityIsMount(entity: Entity): boolean;

package/dist/src/sim/mount.js

@@ -0,0 +1,225 @@
+// src/sim/mount.ts — Phase 59: Mounted Combat & Riding
+//
+// Physics-grounded model for rider/mount pairs.
+//
+// Charge attack: a fraction of the mount's kinetic energy is delivered to the target.
+//   bonusEnergy_J = ½ × (mass_kg × CHARGE_MASS_FRAC / SCALE.Q) × v²
+//
+// Height advantage: elevated rider gains an aim bonus proportional to mount height.
+//   aimBonus_Q = min(riderHeightBonus_m / SCALE.m × HEIGHT_AIM_BONUS_PER_M, HEIGHT_AIM_BONUS_MAX)
+//
+// Fear contagion: when mount shock exceeds its fearThreshold, excess shock propagates to rider.
+//
+// Forced dismount: triggered by rider over-shock, mount death, or mount bolting.
+//
+// Public API:
+//   getMountGaitSpeed(profile, gait)           → SCALE.mps
+//   computeChargeBonus(profile, speed_Smps)    → ChargeBonus
+//   deriveRiderHeightBonus(profile)            → Q
+//   deriveRiderStabilityBonus(profile)         → Q
+//   computeFallEnergy_J(profile, riderMass_Skg)→ number (joules)
+//   deriveMountFearPressure(mountShockQ, fearThreshold_Q) → Q
+//   checkMountStep(riderShockQ, mountShockQ, mountDead, profile) → MountStepResult
+//   entityIsMounted(entity)                    → boolean
+//   entityIsMount(entity)                      → boolean
+import { q, clampQ, to, SCALE } from "../units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Fraction of mount mass that contributes to charge strike energy [Q]. */
+export const CHARGE_MASS_FRAC = q(0.08);
+/** Rider shock level above which a forced dismount occurs [Q]. */
+export const DISMOUNT_SHOCK_Q = q(0.65);
+/** Aim / accuracy bonus per real metre of rider elevation [Q]. */
+export const HEIGHT_AIM_BONUS_PER_M = q(0.12);
+/** Maximum rider height aim bonus (caps at 2.5 m for war elephant) [Q]. */
+export const HEIGHT_AIM_BONUS_MAX = q(0.30);
+/** Fraction of mount stability that transfers to the rider [Q]. */
+export const RIDER_STABILITY_INHERIT = q(0.15);
+/** Fraction of excess mount-shock (beyond fearThreshold) that propagates to rider [Q]. */
+export const MOUNT_FEAR_CONTAGION = q(0.40);
+// ── Mount profiles ────────────────────────────────────────────────────────────
+export const PONY = {
+    id: "pony",
+    name: "Pony",
+    mass_kg: to.kg(250),
+    riderHeightBonus_m: to.m(0.90),
+    maxCarryCapacity_kg: to.kg(100),
+    walkSpeed_mps: to.mps(1.5),
+    trotSpeed_mps: to.mps(4.0),
+    gallopSpeed_mps: to.mps(10.0),
+    chargeSpeed_mps: to.mps(11.0),
+    stability_Q: q(0.82),
+    fearThreshold_Q: q(0.50),
+};
+export const HORSE = {
+    id: "horse",
+    name: "Horse",
+    mass_kg: to.kg(450),
+    riderHeightBonus_m: to.m(1.20),
+    maxCarryCapacity_kg: to.kg(130),
+    walkSpeed_mps: to.mps(1.6),
+    trotSpeed_mps: to.mps(4.5),
+    gallopSpeed_mps: to.mps(14.0),
+    chargeSpeed_mps: to.mps(16.0),
+    stability_Q: q(0.88),
+    fearThreshold_Q: q(0.58),
+};
+export const WARHORSE = {
+    id: "warhorse",
+    name: "Warhorse",
+    mass_kg: to.kg(550),
+    riderHeightBonus_m: to.m(1.30),
+    maxCarryCapacity_kg: to.kg(150),
+    walkSpeed_mps: to.mps(1.5),
+    trotSpeed_mps: to.mps(4.0),
+    gallopSpeed_mps: to.mps(13.0),
+    chargeSpeed_mps: to.mps(17.0),
+    stability_Q: q(0.92),
+    fearThreshold_Q: q(0.72), // battle-trained — much harder to panic
+};
+export const CAMEL = {
+    id: "camel",
+    name: "Camel",
+    mass_kg: to.kg(400),
+    riderHeightBonus_m: to.m(1.80),
+    maxCarryCapacity_kg: to.kg(160),
+    walkSpeed_mps: to.mps(1.5),
+    trotSpeed_mps: to.mps(3.5),
+    gallopSpeed_mps: to.mps(11.0),
+    chargeSpeed_mps: to.mps(12.0),
+    stability_Q: q(0.80),
+    fearThreshold_Q: q(0.52),
+};
+export const WAR_ELEPHANT = {
+    id: "war_elephant",
+    name: "War Elephant",
+    mass_kg: to.kg(3_000),
+    riderHeightBonus_m: to.m(2.50),
+    maxCarryCapacity_kg: to.kg(300),
+    walkSpeed_mps: to.mps(2.0),
+    trotSpeed_mps: to.mps(4.0),
+    gallopSpeed_mps: to.mps(7.0),
+    chargeSpeed_mps: to.mps(8.0),
+    stability_Q: q(0.92),
+    fearThreshold_Q: q(0.48), // prone to panic but devastating when controlled
+};
+/** All mount profiles in one array. */
+export const ALL_MOUNTS = [PONY, HORSE, WARHORSE, CAMEL, WAR_ELEPHANT];
+// ── Core computation ──────────────────────────────────────────────────────────
+/**
+ * Return the mount's speed in SCALE.mps for the given gait.
+ */
+export function getMountGaitSpeed(profile, gait) {
+    switch (gait) {
+        case "walk": return profile.walkSpeed_mps;
+        case "trot": return profile.trotSpeed_mps;
+        case "gallop": return profile.gallopSpeed_mps;
+        case "charge": return profile.chargeSpeed_mps;
+    }
+}
+/**
+ * Compute the bonus kinetic energy delivered to a target during a mounted charge.
+ *
+ * Only `CHARGE_MASS_FRAC` (8%) of the mount's mass participates in the impact;
+ * the remainder is absorbed through the mount's body.
+ *
+ * `bonusEnergy_J = ½ × strikeMass × v²`  (SI, result in joules)
+ *
+ * @param speed_Smps  Current charge speed [SCALE.mps].
+ */
+export function computeChargeBonus(profile, speed_Smps) {
+    if (speed_Smps <= 0)
+        return { bonusEnergy_J: 0, strikeMass_kg: 0 };
+    const strikeMass_kg = Math.round(profile.mass_kg * CHARGE_MASS_FRAC / SCALE.Q);
+    // ½ × (strikeMass_kg / SCALE.kg) × (speed_Smps / SCALE.mps)²  — result in J (SCALE.J = 1)
+    const bonusEnergy_J = Math.round(0.5 * strikeMass_kg * speed_Smps * speed_Smps / (SCALE.kg * SCALE.mps * SCALE.mps));
+    return { bonusEnergy_J, strikeMass_kg };
+}
+/**
+ * Derive the aim/accuracy bonus a rider gains from elevation.
+ *
+ * `aimBonus_Q = (riderHeightBonus_m / SCALE.m) × HEIGHT_AIM_BONUS_PER_M`
+ * Capped at HEIGHT_AIM_BONUS_MAX = q(0.30).
+ */
+export function deriveRiderHeightBonus(profile) {
+    const heightBonus_Q = Math.round(profile.riderHeightBonus_m * HEIGHT_AIM_BONUS_PER_M / SCALE.m);
+    return clampQ(heightBonus_Q, q(0), HEIGHT_AIM_BONUS_MAX);
+}
+/**
+ * Derive the stability bonus a rider inherits from a well-balanced mount.
+ *
+ * `stabilityBonus_Q = mount.stability_Q × RIDER_STABILITY_INHERIT / SCALE.Q`
+ * Capped at q(0.20).
+ */
+export function deriveRiderStabilityBonus(profile) {
+    return clampQ(Math.round(profile.stability_Q * RIDER_STABILITY_INHERIT / SCALE.Q), q(0), q(0.20));
+}
+/**
+ * Compute the fall injury energy when a rider is dismounted from height.
+ *
+ * Models a free-fall from the rider's seat height:
+ *   fallEnergy_J = riderMass × g × height
+ *
+ * @param riderMass_Skg  Rider's mass [SCALE.kg].
+ */
+export function computeFallEnergy_J(profile, riderMass_Skg) {
+    if (profile.riderHeightBonus_m <= 0)
+        return 0;
+    // E = m × g × h  (SI: kg × m/s² × m = J)
+    // m = riderMass_Skg / SCALE.kg
+    // g = 9.807 m/s²
+    // h = riderHeightBonus_m / SCALE.m
+    return Math.round(riderMass_Skg / SCALE.kg * 9.807 * profile.riderHeightBonus_m / SCALE.m);
+}
+/**
+ * Derive the fear pressure transmitted from a panicking mount to its rider.
+ *
+ * Returns q(0) when the mount's shockQ is at or below its fearThreshold.
+ * Above the threshold, 40% of the excess is propagated to the rider.
+ *
+ * @param mountShockQ       Current shock level of the mount [Q].
+ * @param fearThreshold_Q   Mount's panic threshold [Q].
+ */
+export function deriveMountFearPressure(mountShockQ, fearThreshold_Q) {
+    if (mountShockQ <= fearThreshold_Q)
+        return q(0);
+    const excess_Q = mountShockQ - fearThreshold_Q;
+    return clampQ(Math.round(excess_Q * MOUNT_FEAR_CONTAGION / SCALE.Q), q(0), SCALE.Q);
+}
+/**
+ * Evaluate a single mounted-combat tick, returning dismount and fear outcomes.
+ *
+ * Does NOT mutate any entity — pure computation for the host to apply.
+ *
+ * Dismount priority: rider_shock > mount_dead > mount_bolt.
+ *
+ * @param riderShockQ   Rider's current shockQ [Q].
+ * @param mountShockQ   Mount's current shockQ [Q].
+ * @param mountDead     True if the mount has died this tick.
+ * @param profile       Mount species profile.
+ * @param riderMass_Skg Rider's mass [SCALE.kg] — used for fall energy.
+ */
+export function checkMountStep(riderShockQ, mountShockQ, mountDead, profile, riderMass_Skg = to.kg(80)) {
+    const fearPressure_Q = deriveMountFearPressure(mountShockQ, profile.fearThreshold_Q);
+    // Evaluate dismount causes in priority order
+    let cause = "none";
+    if (riderShockQ > DISMOUNT_SHOCK_Q)
+        cause = "rider_shock";
+    else if (mountDead)
+        cause = "mount_dead";
+    else if (mountShockQ > profile.fearThreshold_Q)
+        cause = "mount_bolt";
+    const shouldDismount = cause !== "none";
+    const fallEnergy_J = shouldDismount
+        ? computeFallEnergy_J(profile, riderMass_Skg)
+        : 0;
+    return { shouldDismount, dismountCause: cause, fallEnergy_J, fearPressure_Q };
+}
+// ── Entity convenience ────────────────────────────────────────────────────────
+/** True if this entity is currently riding a mount. */
+export function entityIsMounted(entity) {
+    return (entity.mount?.mountId ?? 0) > 0;
+}
+/** True if this entity is currently carrying a rider. */
+export function entityIsMount(entity) {
+    return (entity.mount?.riderId ?? 0) > 0;
+}

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

@@ -0,0 +1,74 @@
+/**
+ * Phase 30 — Nutrition & Starvation
+ *
+ * Models long-term caloric balance, hunger states, and staged combat penalties
+ * from starvation. Complements the Phase 2B short-term stamina (reserveEnergy_J).
+ *
+ * BMR (Kleiber's law):  BMR_W ≈ 80 × (mass_kg / 75)^0.75
+ * AMR (active):         AMR_W = BMR + peakPower_W × activityFrac × 0.15
+ *
+ * Hunger state thresholds (caloric deficit relative to BMR):
+ *   sated   : deficit < 12 h × BMR
+ *   hungry  : 12 h × BMR ≤ deficit < 24 h × BMR
+ *   starving: 24 h × BMR ≤ deficit < 72 h × BMR  (+fat catabolism)
+ *   critical: deficit ≥ 72 h × BMR               (+muscle catabolism)
+ */
+import { type Q } from "../units.js";
+import type { Entity } from "./entity.js";
+import type { HungerState } from "./condition.js";
+export interface FoodItem {
+    id: string;
+    name: string;
+    /** Caloric energy in joules (e.g. 1 ration bar ≈ 2 MJ). */
+    energy_J: number;
+    /** Mass of the item in grams. */
+    massGrams: number;
+    /** Hydration provided in the same unit system as hydrationBalance_J. */
+    hydration_J?: number;
+}
+export declare const FOOD_ITEMS: readonly FoodItem[];
+/**
+ * Compute Basal Metabolic Rate in watts (integer) using Kleiber's law.
+ * mass_kg must be in SCALE.kg units (e.g. 75 000 for 75 kg).
+ */
+export declare function computeBMR(mass_kg: number): number;
+/**
+ * Advance an entity's nutritional state by `delta_s` seconds.
+ *
+ * Mutates:
+ *   condition.caloricBalance_J, condition.hydrationBalance_J, condition.hungerState
+ *   attributes.morphology.mass_kg        (during starving or critical)
+ *   attributes.performance.peakForce_N   (during critical only)
+ *
+ * `activity` is a Q value (0 = resting, q(1.0) = maximum).
+ */
+export declare function stepNutrition(entity: Entity, delta_s: number, activity: Q): void;
+/**
+ * Consume a food item from the entity's optional food inventory.
+ *
+ * Returns `false` if the food ID is unknown, or if the entity has a
+ * `foodInventory: Map<string, number>` that does not contain the item.
+ * When no inventory is present (undefined), consumption is unconditional.
+ *
+ * Side effects:
+ *   - caloricBalance_J   += food.energy_J
+ *   - hydrationBalance_J += food.hydration_J (if any)
+ *   - lastMealTick        = tick
+ *   - injury.fluidLoss   reduced by scale(hydration_J)  [for water_flask]
+ *   - hungerState         re-derived
+ */
+export declare function consumeFood(entity: Entity, foodId: string, tick: number): boolean;
+/**
+ * Derive performance modifiers from hunger state.
+ *
+ *   staminaMul : multiplier on effective stamina energy drain (Phase 2B)
+ *   forceMul   : multiplier on effective peakForce_N in combat resolution
+ *   latencyMul : multiplier on decision latency (Phase 4)
+ *   moraleDecay: additional fear per tick (Phase 5)
+ */
+export declare function deriveHungerModifiers(state: HungerState): {
+    staminaMul: Q;
+    forceMul: Q;
+    latencyMul: Q;
+    moraleDecay: Q;
+};

package/dist/src/sim/nutrition.js

@@ -0,0 +1,168 @@
+/**
+ * Phase 30 — Nutrition & Starvation
+ *
+ * Models long-term caloric balance, hunger states, and staged combat penalties
+ * from starvation. Complements the Phase 2B short-term stamina (reserveEnergy_J).
+ *
+ * BMR (Kleiber's law):  BMR_W ≈ 80 × (mass_kg / 75)^0.75
+ * AMR (active):         AMR_W = BMR + peakPower_W × activityFrac × 0.15
+ *
+ * Hunger state thresholds (caloric deficit relative to BMR):
+ *   sated   : deficit < 12 h × BMR
+ *   hungry  : 12 h × BMR ≤ deficit < 24 h × BMR
+ *   starving: 24 h × BMR ≤ deficit < 72 h × BMR  (+fat catabolism)
+ *   critical: deficit ≥ 72 h × BMR               (+muscle catabolism)
+ */
+import { q, SCALE, clampQ } from "../units.js";
+export const FOOD_ITEMS = [
+    { id: "ration_bar", name: "Ration bar", energy_J: 2_000_000, massGrams: 500 },
+    { id: "dried_meat", name: "Dried meat", energy_J: 1_500_000, massGrams: 300 },
+    { id: "hardtack", name: "Hardtack", energy_J: 800_000, massGrams: 200 },
+    { id: "fresh_bread", name: "Fresh bread", energy_J: 700_000, massGrams: 250 },
+    { id: "berry_handful", name: "Berries", energy_J: 150_000, massGrams: 50 },
+    { id: "water_flask", name: "Water flask", energy_J: 0, massGrams: 500, hydration_J: 500_000 },
+];
+const FOOD_BY_ID = new Map(FOOD_ITEMS.map(f => [f.id, f]));
+// ── Metabolic constants ───────────────────────────────────────────────────────
+/** Fluid loss rate: ~2.5 L/day, scaled as 1 mL = 1000 hydration_J → 29 J/s. */
+const FLUID_LOSS_RATE = 29; // hydration_J per second
+/**
+ * Fat catabolism during starvation: ~300 g/day in SCALE.kg units.
+ * SCALE.kg = 1000 so 300 g = 300 SCALE.kg units.
+ * 300 / 86400 ≈ 0.003472 SCALE.kg/s — accumulated as float.
+ */
+const FAT_CATAB_RATE = 300 / 86400; // SCALE.kg per second
+/**
+ * Muscle catabolism in critical starvation: 0.5 N/hour reduction in peakForce_N.
+ * 0.5 N × SCALE.N = 50 SCALE.N / 3600 s ≈ 0.01389 SCALE.N/s — accumulated as float.
+ */
+const MUSCLE_CATAB_RATE = 0.5 * SCALE.N / 3600; // SCALE.N per second
+/** Seconds of BMR-equivalent deficit to enter hungry state (12 h). */
+const HUNGRY_SECONDS = 12 * 3600; // 43 200
+/** Seconds of BMR-equivalent deficit to enter starving state (24 h). */
+const STARVING_SECONDS = 24 * 3600; // 86 400
+/** Seconds of BMR-equivalent deficit to enter critical state (72 h). */
+const CRITICAL_SECONDS = 72 * 3600; // 259 200
+// ── Pure helpers ──────────────────────────────────────────────────────────────
+/**
+ * Compute Basal Metabolic Rate in watts (integer) using Kleiber's law.
+ * mass_kg must be in SCALE.kg units (e.g. 75 000 for 75 kg).
+ */
+export function computeBMR(mass_kg) {
+    const massReal = mass_kg / SCALE.kg;
+    return Math.round(80 * Math.pow(massReal / 75, 0.75));
+}
+/** Derive hunger state from caloric balance and BMR. */
+function deriveHungerState(caloricBalance, bmr) {
+    const deficit = -caloricBalance; // positive when in deficit
+    if (deficit < HUNGRY_SECONDS * bmr)
+        return "sated";
+    if (deficit < STARVING_SECONDS * bmr)
+        return "hungry";
+    if (deficit < CRITICAL_SECONDS * bmr)
+        return "starving";
+    return "critical";
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Advance an entity's nutritional state by `delta_s` seconds.
+ *
+ * Mutates:
+ *   condition.caloricBalance_J, condition.hydrationBalance_J, condition.hungerState
+ *   attributes.morphology.mass_kg        (during starving or critical)
+ *   attributes.performance.peakForce_N   (during critical only)
+ *
+ * `activity` is a Q value (0 = resting, q(1.0) = maximum).
+ */
+export function stepNutrition(entity, delta_s, activity) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const cond = entity.condition;
+    const baseBMR = computeBMR(entity.attributes.morphology.mass_kg);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const bmrMul = entity.physiology?.bmrMultiplier ?? SCALE.Q;
+    const bmr = Math.round(baseBMR * bmrMul / SCALE.Q);
+    // Active metabolic rate: BMR + peakPower × activityFrac × 0.15
+    const actFrac = activity / SCALE.Q;
+    const amr = bmr + entity.attributes.performance.peakPower_W * actFrac * 0.15;
+    // Caloric and hydration drain
+    cond.caloricBalance_J = (cond.caloricBalance_J ?? 0) - amr * delta_s;
+    cond.hydrationBalance_J = (cond.hydrationBalance_J ?? 0) - FLUID_LOSS_RATE * delta_s;
+    // Derive and cache hunger state
+    const hungerState = deriveHungerState(cond.caloricBalance_J, bmr);
+    cond.hungerState = hungerState;
+    // Fat catabolism (starving and critical) — sub-unit float accumulation
+    if (hungerState === "starving" || hungerState === "critical") {
+        entity.attributes.morphology.mass_kg -= FAT_CATAB_RATE * delta_s;
+        if (entity.attributes.morphology.mass_kg < 0)
+            entity.attributes.morphology.mass_kg = 0;
+    }
+    // Muscle catabolism (critical only)
+    if (hungerState === "critical") {
+        entity.attributes.performance.peakForce_N -= MUSCLE_CATAB_RATE * delta_s;
+        if (entity.attributes.performance.peakForce_N < 0)
+            entity.attributes.performance.peakForce_N = 0;
+    }
+}
+/**
+ * Consume a food item from the entity's optional food inventory.
+ *
+ * Returns `false` if the food ID is unknown, or if the entity has a
+ * `foodInventory: Map<string, number>` that does not contain the item.
+ * When no inventory is present (undefined), consumption is unconditional.
+ *
+ * Side effects:
+ *   - caloricBalance_J   += food.energy_J
+ *   - hydrationBalance_J += food.hydration_J (if any)
+ *   - lastMealTick        = tick
+ *   - injury.fluidLoss   reduced by scale(hydration_J)  [for water_flask]
+ *   - hungerState         re-derived
+ */
+export function consumeFood(entity, foodId, tick) {
+    const food = FOOD_BY_ID.get(foodId);
+    if (!food)
+        return false; // unknown food item
+    // Inventory check (undefined = unlimited supply)
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const inventory = entity.foodInventory;
+    if (inventory !== undefined) {
+        const count = inventory.get(foodId) ?? 0;
+        if (count <= 0)
+            return false;
+        inventory.set(foodId, count - 1);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const cond = entity.condition;
+    cond.caloricBalance_J = (cond.caloricBalance_J ?? 0) + food.energy_J;
+    cond.hydrationBalance_J = (cond.hydrationBalance_J ?? 0) + (food.hydration_J ?? 0);
+    cond.lastMealTick = tick;
+    // Water flask: also reduces injury fluid loss
+    // Scale: 500 000 hydration_J → Math.trunc(500_000 / 500) = 1000 = q(0.10)
+    if (food.hydration_J) {
+        const fluidRestore = Math.trunc(food.hydration_J / 500);
+        entity.injury.fluidLoss = clampQ((entity.injury.fluidLoss - fluidRestore), q(0), q(1.0));
+    }
+    // Re-derive hunger state after eating
+    const bmr = computeBMR(entity.attributes.morphology.mass_kg);
+    cond.hungerState = deriveHungerState(cond.caloricBalance_J, bmr);
+    return true;
+}
+/**
+ * Derive performance modifiers from hunger state.
+ *
+ *   staminaMul : multiplier on effective stamina energy drain (Phase 2B)
+ *   forceMul   : multiplier on effective peakForce_N in combat resolution
+ *   latencyMul : multiplier on decision latency (Phase 4)
+ *   moraleDecay: additional fear per tick (Phase 5)
+ */
+export function deriveHungerModifiers(state) {
+    switch (state) {
+        case "sated":
+            return { staminaMul: q(1.0), forceMul: q(1.0), latencyMul: q(1.0), moraleDecay: q(0) };
+        case "hungry":
+            return { staminaMul: q(0.90), forceMul: q(1.0), latencyMul: q(1.0), moraleDecay: q(0) };
+        case "starving":
+            return { staminaMul: q(0.75), forceMul: q(0.90), latencyMul: q(1.0), moraleDecay: q(0.030) };
+        case "critical":
+            return { staminaMul: q(0.50), forceMul: q(0.80), latencyMul: q(1.50), moraleDecay: q(0.030) };
+    }
+}

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

@@ -0,0 +1,8 @@
+import type { Entity } from "./entity.js";
+import type { WorldIndex } from "./indexing.js";
+import type { SpatialIndex } from "./spatial.js";
+import type { WorldState } from "./world.js";
+export interface OcclusionQuery {
+    laneRadius_m: number;
+}
+export declare function isMeleeLaneOccludedByFriendly(world: WorldState | undefined, attacker: Entity, target: Entity, index: WorldIndex, spatial: SpatialIndex, q: OcclusionQuery): boolean;