@its-not-rocket-science/ananke 0.1.0

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

@@ -0,0 +1,64 @@
+import { BodyRegion } from "./body";
+import { BodySegmentId } from "./bodyplan";
+/** Commands are player/AI intentions */
+export declare const CommandKinds: {
+    readonly Move: "move";
+    readonly Attack: "attack";
+    readonly AttackNearest: "attackNearest";
+    readonly Defend: "defend";
+    readonly Grapple: "grapple";
+    readonly BreakGrapple: "breakGrapple";
+    readonly BreakBind: "breakBind";
+    readonly Shoot: "shoot";
+    readonly Treat: "treat";
+    readonly SetProne: "setProne";
+    readonly Activate: "activate";
+};
+export type CommandKind = typeof CommandKinds[keyof typeof CommandKinds];
+/** Trace events are engine observations */
+export declare const TraceKinds: {
+    readonly TickStart: "tickStart";
+    readonly TickEnd: "tickEnd";
+    readonly Intent: "intent";
+    readonly Move: "move";
+    readonly Injury: "injury";
+    readonly Attack: "attack";
+    readonly AttackAttempt: "attackAttempt";
+    readonly Grapple: "grapple";
+    readonly KO: "ko";
+    readonly Death: "death";
+    readonly WeaponBind: "weaponBind";
+    readonly WeaponBindBreak: "weaponBindBreak";
+    readonly ProjectileHit: "projectileHit";
+    readonly MoraleRoute: "moraleRoute";
+    readonly MoraleRally: "moraleRally";
+    readonly Fracture: "fracture";
+    readonly TreatmentApplied: "treatmentApplied";
+    readonly BlastHit: "blastHit";
+    readonly CapabilityActivated: "capabilityActivated";
+    readonly CapabilitySuppressed: "capabilitySuppressed";
+    readonly CastInterrupted: "castInterrupted";
+};
+export type TraceKind = typeof TraceKinds[keyof typeof TraceKinds];
+export type AllKinds = CommandKind | TraceKind;
+export declare const MoveModes: {
+    readonly Walk: "walk";
+    readonly Run: "run";
+    readonly Sprint: "sprint";
+    readonly Crawl: "crawl";
+    readonly Hover: "hover";
+};
+export type MoveMode = typeof MoveModes[keyof typeof MoveModes];
+export declare const DefenceModes: {
+    readonly None: "none";
+    readonly Block: "block";
+    readonly Parry: "parry";
+    readonly Dodge: "dodge";
+};
+export type DefenceMode = typeof DefenceModes[keyof typeof DefenceModes];
+export declare const EngageModes: {
+    readonly None: "none";
+    readonly Strike: "strike";
+};
+export type EngageMode = typeof EngageModes[keyof typeof EngageModes];
+export type HitArea = BodyRegion | BodySegmentId;

package/dist/src/sim/kinds.js

@@ -0,0 +1,56 @@
+// src/sim/kinds.ts
+/** Commands are player/AI intentions */
+export const CommandKinds = {
+    Move: "move",
+    Attack: "attack",
+    AttackNearest: "attackNearest",
+    Defend: "defend",
+    Grapple: "grapple",
+    BreakGrapple: "breakGrapple",
+    BreakBind: "breakBind", // Phase 2C
+    Shoot: "shoot", // Phase 3
+    Treat: "treat", // Phase 9
+    SetProne: "setProne",
+    Activate: "activate", // Phase 12: use a capability source effect
+};
+/** Trace events are engine observations */
+export const TraceKinds = {
+    TickStart: "tickStart",
+    TickEnd: "tickEnd",
+    Intent: "intent",
+    Move: "move",
+    Injury: "injury",
+    Attack: "attack",
+    AttackAttempt: "attackAttempt",
+    Grapple: "grapple",
+    KO: "ko",
+    Death: "death",
+    WeaponBind: "weaponBind", // Phase 2C
+    WeaponBindBreak: "weaponBindBreak", // Phase 2C
+    ProjectileHit: "projectileHit", // Phase 3
+    MoraleRoute: "moraleRoute", // Phase 5
+    MoraleRally: "moraleRally", // Phase 18
+    Fracture: "fracture", // Phase 9
+    TreatmentApplied: "treatmentApplied", // Phase 9
+    BlastHit: "blastHit", // Phase 10
+    CapabilityActivated: "capabilityActivated", // Phase 12
+    CapabilitySuppressed: "capabilitySuppressed", // Phase 12
+    CastInterrupted: "castInterrupted", // Phase 12
+};
+export const MoveModes = {
+    Walk: "walk",
+    Run: "run",
+    Sprint: "sprint",
+    Crawl: "crawl",
+    Hover: "hover",
+};
+export const DefenceModes = {
+    None: "none",
+    Block: "block",
+    Parry: "parry",
+    Dodge: "dodge",
+};
+export const EngageModes = {
+    None: "none",
+    Strike: "strike",
+};

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

@@ -0,0 +1,50 @@
+import type { Entity } from "./entity.js";
+/** Effective Δv at which a target begins to stumble (0.5 m/s in SCALE.mps units). */
+export declare const STAGGER_THRESHOLD_mps: number;
+/** Effective Δv at which a target is knocked prone (2.0 m/s in SCALE.mps units). */
+export declare const PRONE_THRESHOLD_mps: number;
+/** Ticks of reduced-action window while staggered. */
+export declare const STAGGER_TICKS = 3;
+export interface KnockbackResult {
+    /** Raw impulse in real Newton-seconds (diagnostic; not used in further simulation math). */
+    impulse_Ns: number;
+    /** Effective velocity delta in SCALE.mps units, after stability reduction. Applied to target. */
+    knockback_v: number;
+    /** True when effective_v ≥ STAGGER_THRESHOLD and entity is not knocked prone. */
+    staggered: boolean;
+    /** True when effective_v ≥ PRONE_THRESHOLD. Implies staggered. */
+    prone: boolean;
+}
+/**
+ * Derive knockback result from an impact.
+ *
+ * Physics derivation:
+ *   impulse = sqrt(2 × E × m_eff)         [N·s — same as p = m_eff × v_head]
+ *   raw_Δv  = impulse / m_target          [m/s]
+ *   effective_v = raw_Δv × (1 − stabilityQ)
+ *
+ * Calibration:
+ *   5.56 mm  (4 g, 1760 J, 75 kg target): Δv ≈ 0.05 m/s — negligible ✓
+ *   12-gauge slug (28 g, 2100 J, 75 kg):  Δv ≈ 0.25 m/s raw — stagger on low-stability target
+ *   Large creature kick (50 kg eff, 400 J, 75 kg): Δv ≈ 2.67 m/s raw — prone on low-stability
+ *
+ * @param energy_J    Impact energy (raw joules; SCALE.J = 1).
+ * @param massEff_kg  Effective striking mass in SCALE.kg units (wpn + body fraction, or projectile).
+ * @param target      Target entity (reads mass_kg and stabilityQ).
+ */
+export declare function computeKnockback(energy_J: number, massEff_kg: number, target: Entity): KnockbackResult;
+/**
+ * Apply knockback result to an entity.
+ *
+ * - Adds `result.knockback_v` to the entity's velocity in the hit direction.
+ * - Sets `condition.prone = true` when result.prone.
+ * - Sets `action.staggerTicks = STAGGER_TICKS` when result.staggered.
+ *
+ * @param entity  Target entity (mutated in-place).
+ * @param result  Result from `computeKnockback`.
+ * @param dir     Direction from attacker to target in SCALE.m coordinates (unnormalised).
+ */
+export declare function applyKnockback(entity: Entity, result: KnockbackResult, dir: {
+    dx: number;
+    dy: number;
+}): void;

package/dist/src/sim/knockback.js

@@ -0,0 +1,82 @@
+// src/sim/knockback.ts — Phase 26: Momentum Transfer & Knockback
+//
+// Impulse-momentum model for melee and ranged impacts.
+// Physics: impulse = sqrt(2 × E × m_eff); Δv = impulse / m_target
+// Stability modifier reduces effective knockback before threshold checks.
+//
+// Math.sqrt is used for impulse calculation — acceptable per project convention
+// (already used in kernel.ts for velocity magnitude computations).
+import { SCALE, qMul } from "../units.js";
+import { normaliseDirCheapQ } from "./vec3.js";
+import { mulDiv } from "../units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Effective Δv at which a target begins to stumble (0.5 m/s in SCALE.mps units). */
+export const STAGGER_THRESHOLD_mps = Math.trunc(0.5 * SCALE.mps); // 5 000
+/** Effective Δv at which a target is knocked prone (2.0 m/s in SCALE.mps units). */
+export const PRONE_THRESHOLD_mps = Math.trunc(2.0 * SCALE.mps); // 20 000
+/** Ticks of reduced-action window while staggered. */
+export const STAGGER_TICKS = 3;
+// ── computeKnockback ──────────────────────────────────────────────────────────
+/**
+ * Derive knockback result from an impact.
+ *
+ * Physics derivation:
+ *   impulse = sqrt(2 × E × m_eff)         [N·s — same as p = m_eff × v_head]
+ *   raw_Δv  = impulse / m_target          [m/s]
+ *   effective_v = raw_Δv × (1 − stabilityQ)
+ *
+ * Calibration:
+ *   5.56 mm  (4 g, 1760 J, 75 kg target): Δv ≈ 0.05 m/s — negligible ✓
+ *   12-gauge slug (28 g, 2100 J, 75 kg):  Δv ≈ 0.25 m/s raw — stagger on low-stability target
+ *   Large creature kick (50 kg eff, 400 J, 75 kg): Δv ≈ 2.67 m/s raw — prone on low-stability
+ *
+ * @param energy_J    Impact energy (raw joules; SCALE.J = 1).
+ * @param massEff_kg  Effective striking mass in SCALE.kg units (wpn + body fraction, or projectile).
+ * @param target      Target entity (reads mass_kg and stabilityQ).
+ */
+export function computeKnockback(energy_J, massEff_kg, target) {
+    const zero = { impulse_Ns: 0, knockback_v: 0, staggered: false, prone: false };
+    if (energy_J <= 0 || massEff_kg <= 0)
+        return zero;
+    // Convert to real units for physics calculation
+    const massEff_real = massEff_kg / SCALE.kg; // real kg
+    const massTarget_real = Math.max(0.001, target.attributes.morphology.mass_kg / SCALE.kg); // real kg
+    // impulse = sqrt(2 × E × m_eff)  [N·s]
+    const impulse_Ns = Math.sqrt(2 * energy_J * massEff_real);
+    // raw Δv in SCALE.mps units
+    const raw_v = Math.trunc((impulse_Ns / massTarget_real) * SCALE.mps);
+    // Stability modifier: higher stability → less effective knockback
+    const stabilityQ = target.attributes.control.stability;
+    const knockback_v = Math.trunc(qMul(raw_v, SCALE.Q - stabilityQ));
+    const prone = knockback_v >= PRONE_THRESHOLD_mps;
+    const staggered = !prone && knockback_v >= STAGGER_THRESHOLD_mps;
+    return { impulse_Ns, knockback_v, staggered, prone };
+}
+// ── applyKnockback ────────────────────────────────────────────────────────────
+/**
+ * Apply knockback result to an entity.
+ *
+ * - Adds `result.knockback_v` to the entity's velocity in the hit direction.
+ * - Sets `condition.prone = true` when result.prone.
+ * - Sets `action.staggerTicks = STAGGER_TICKS` when result.staggered.
+ *
+ * @param entity  Target entity (mutated in-place).
+ * @param result  Result from `computeKnockback`.
+ * @param dir     Direction from attacker to target in SCALE.m coordinates (unnormalised).
+ */
+export function applyKnockback(entity, result, dir) {
+    if (result.knockback_v === 0)
+        return;
+    if (dir.dx === 0 && dir.dy === 0)
+        return;
+    // Cheap Chebyshev normalisation — no float division in the hot path
+    const dirQ = normaliseDirCheapQ({ x: dir.dx, y: dir.dy, z: 0 });
+    entity.velocity_mps.x += mulDiv(result.knockback_v, dirQ.x, SCALE.Q);
+    entity.velocity_mps.y += mulDiv(result.knockback_v, dirQ.y, SCALE.Q);
+    if (result.prone) {
+        entity.condition.prone = true;
+    }
+    if (result.staggered) {
+        entity.action.staggerTicks = Math.max(entity.action.staggerTicks ?? 0, STAGGER_TICKS);
+    }
+}

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

@@ -0,0 +1,48 @@
+/**
+ * Phase 32B — Multi-Limb Granularity
+ *
+ * Per-limb state for entities whose body plan has multiple manipulation segments
+ * (octopoids, arachnids, multi-armed creatures). Integrates with grapple resolution
+ * by reducing effective contest force when limbs are severed or fatigued.
+ *
+ * Backward-compatible: entities without a limbStates field behave identically to
+ * the existing single-pool grapple model.
+ */
+import { type Q, type I32 } from "../units.js";
+import type { BodyPlan } from "./bodyplan.js";
+import type { InjuryState } from "./injury.js";
+export interface LimbState {
+    /** Matches a BodySegment.id in the entity's body plan. */
+    segmentId: string;
+    /** Current grip quality on this limb (0 = no grip, q(1.0) = full grip). */
+    gripQ: Q;
+    /** Entity id currently held by this limb; 0 = limb is free. */
+    engagedWith: number;
+    /** Float fatigue accumulator [same unit as energy_J]. Sub-unit precision. */
+    fatigueJ: number;
+}
+/**
+ * Build initial LimbState[] from a BodyPlan.
+ * Only segments with `manipulationRole === "primary"` are included.
+ * Returns an empty array if no such segments exist.
+ */
+export declare function buildLimbStates(plan: BodyPlan): LimbState[];
+/**
+ * Compute the effective force multiplier given current limb states and injury.
+ *
+ * A limb is excluded when its body segment has structural damage at SCALE.Q
+ * (fully destroyed / severed). The result is:
+ *   (activeLimbs / totalLimbs) × averageGripQ
+ *
+ * Returns q(1.0) when limbStates is empty (degenerate case, caller should not
+ * invoke this function if limb count is zero).
+ */
+export declare function effectiveLimbForceMul(limbStates: LimbState[], injury: InjuryState): Q;
+/**
+ * Tick fatigue for engaged limbs. Each active engaged limb drains
+ * `peakForce_N / limbCount` energy per second (sub-unit float accumulator).
+ *
+ * The accumulated fatigueJ is informational for host use; it does not directly
+ * reduce gripQ here (that is a host-side policy decision, e.g. after a threshold).
+ */
+export declare function stepLimbFatigue(limbStates: LimbState[], peakForce_N: I32, delta_s: number): void;

package/dist/src/sim/limb.js

@@ -0,0 +1,78 @@
+/**
+ * Phase 32B — Multi-Limb Granularity
+ *
+ * Per-limb state for entities whose body plan has multiple manipulation segments
+ * (octopoids, arachnids, multi-armed creatures). Integrates with grapple resolution
+ * by reducing effective contest force when limbs are severed or fatigued.
+ *
+ * Backward-compatible: entities without a limbStates field behave identically to
+ * the existing single-pool grapple model.
+ */
+import { q, SCALE, clampQ, qMul, mulDiv } from "../units.js";
+// ── Limb initialisation ───────────────────────────────────────────────────────
+/**
+ * Build initial LimbState[] from a BodyPlan.
+ * Only segments with `manipulationRole === "primary"` are included.
+ * Returns an empty array if no such segments exist.
+ */
+export function buildLimbStates(plan) {
+    return plan.segments
+        .filter(s => s.manipulationRole === "primary")
+        .map(s => ({
+        segmentId: s.id,
+        gripQ: q(0),
+        engagedWith: 0,
+        fatigueJ: 0,
+    }));
+}
+// ── Force contribution ────────────────────────────────────────────────────────
+/**
+ * Compute the effective force multiplier given current limb states and injury.
+ *
+ * A limb is excluded when its body segment has structural damage at SCALE.Q
+ * (fully destroyed / severed). The result is:
+ *   (activeLimbs / totalLimbs) × averageGripQ
+ *
+ * Returns q(1.0) when limbStates is empty (degenerate case, caller should not
+ * invoke this function if limb count is zero).
+ */
+export function effectiveLimbForceMul(limbStates, injury) {
+    const total = limbStates.length;
+    if (total === 0)
+        return q(1.0);
+    let activeCount = 0;
+    let gripSum = 0;
+    for (const ls of limbStates) {
+        const region = injury.byRegion?.[ls.segmentId];
+        const structDmg = region?.structuralDamage ?? 0;
+        if (structDmg >= SCALE.Q)
+            continue; // severed / destroyed
+        activeCount++;
+        gripSum += ls.gripQ;
+    }
+    if (activeCount === 0)
+        return q(0);
+    const activeFrac = mulDiv(activeCount, SCALE.Q, total); // e.g. 6/8 = q(0.75)
+    const avgGrip = Math.trunc(gripSum / activeCount);
+    // If all grips are 0 (entity not currently grappling) return activeFrac directly
+    if (avgGrip === 0)
+        return activeFrac;
+    return clampQ(qMul(activeFrac, avgGrip), q(0), q(1.0));
+}
+// ── Fatigue accumulation ──────────────────────────────────────────────────────
+/**
+ * Tick fatigue for engaged limbs. Each active engaged limb drains
+ * `peakForce_N / limbCount` energy per second (sub-unit float accumulator).
+ *
+ * The accumulated fatigueJ is informational for host use; it does not directly
+ * reduce gripQ here (that is a host-side policy decision, e.g. after a threshold).
+ */
+export function stepLimbFatigue(limbStates, peakForce_N, delta_s) {
+    const activeEngaged = limbStates.filter(ls => ls.engagedWith !== 0);
+    if (activeEngaged.length === 0)
+        return;
+    const drainPerLimb = (peakForce_N / limbStates.length) * delta_s;
+    for (const ls of activeEngaged) {
+        ls.fatigueJ += drainPerLimb;
+    }
+}

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

@@ -0,0 +1,32 @@
+import { type Q } from "../units.js";
+import type { TechCapability } from "./tech.js";
+/**
+ * Capability tier of the equipment used during treatment.
+ * Passed on TreatCommand; the kernel scales effectiveness accordingly.
+ */
+export type MedicalTier = "none" | "bandage" | "surgicalKit" | "autodoc" | "nanomedicine";
+/** Ordinal rank used for minimum-tier comparisons. Higher = more capable. */
+export declare const TIER_RANK: Record<MedicalTier, number>;
+/**
+ * Effectiveness multiplier per tier.
+ * Applied as: reduction = BASE_RATE × TIER_MUL × (medSkill.treatmentRateMul / SCALE.Q)
+ */
+export declare const TIER_MUL: Record<MedicalTier, Q>;
+/**
+ * Available treatment actions.
+ *
+ * tourniquet       — zeroes bleedingRate in one region immediately; requires ≥ bandage tier
+ * bandage          — reduces bleedingRate per tick; requires ≥ bandage tier
+ * surgery          — reduces structuralDamage per tick; clears fracture when healed; requires ≥ surgicalKit
+ * fluidReplacement — restores fluidLoss per tick; requires ≥ autodoc
+ */
+export type MedicalAction = "tourniquet" | "bandage" | "surgery" | "fluidReplacement";
+/** Minimum tier required for each action. */
+export declare const ACTION_MIN_TIER: Record<MedicalAction, MedicalTier>;
+/**
+ * Phase 11: TechCapability that must be available in TechContext to use equipment at this tier.
+ * When ctx.techCtx is provided and the capability is absent, treatment is blocked.
+ *
+ * Tiers not listed here have no technology requirement (they work in any era).
+ */
+export declare const TIER_TECH_REQ: Partial<Record<MedicalTier, TechCapability>>;

package/dist/src/sim/medical.js

@@ -0,0 +1,33 @@
+// src/sim/medical.ts — Phase 9: medical treatment types; Phase 11: tech gating
+import { q } from "../units.js";
+/** Ordinal rank used for minimum-tier comparisons. Higher = more capable. */
+export const TIER_RANK = {
+    none: 0, bandage: 1, surgicalKit: 2, autodoc: 3, nanomedicine: 4,
+};
+/**
+ * Effectiveness multiplier per tier.
+ * Applied as: reduction = BASE_RATE × TIER_MUL × (medSkill.treatmentRateMul / SCALE.Q)
+ */
+export const TIER_MUL = {
+    none: q(0),
+    bandage: q(0.50),
+    surgicalKit: q(0.80),
+    autodoc: q(1.00),
+    nanomedicine: q(1.20),
+};
+/** Minimum tier required for each action. */
+export const ACTION_MIN_TIER = {
+    tourniquet: "bandage",
+    bandage: "bandage",
+    surgery: "surgicalKit",
+    fluidReplacement: "autodoc",
+};
+/**
+ * Phase 11: TechCapability that must be available in TechContext to use equipment at this tier.
+ * When ctx.techCtx is provided and the capability is absent, treatment is blocked.
+ *
+ * Tiers not listed here have no technology requirement (they work in any era).
+ */
+export const TIER_TECH_REQ = {
+    nanomedicine: "NanomedicalRepair",
+};

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

@@ -0,0 +1,69 @@
+/**
+ * Phase 5 — Morale and Psychological State
+ *
+ * Pure fixed-point functions. No Math.random(), no Entity imports.
+ * All randomness via eventSeed + caller-supplied seed.
+ */
+import type { Q } from "../units.js";
+/** Fear added per tick of active suppression (incoming near-miss fire). */
+export declare const FEAR_PER_SUPPRESSION_TICK: Q;
+/** Fear added when a nearby ally is killed in the same tick. */
+export declare const FEAR_FOR_ALLY_DEATH: Q;
+/** Multiplier: fear added per tick = shock × this. */
+export declare const FEAR_INJURY_MUL: Q;
+/** Fear added per tick when enemies outnumber allies in awareness radius. */
+export declare const FEAR_OUTNUMBERED: Q;
+/** Fear added to a defender per surprise attack (attacker undetected). */
+export declare const FEAR_SURPRISE: Q;
+/** Fear added per tick when >50% of own team is already routing. */
+export declare const FEAR_ROUTING_CASCADE: Q;
+/** Additional fear decay per leader within AURA_RADIUS_m. */
+export declare const LEADER_AURA_FEAR_REDUCTION: Q;
+/** Additional fear decay per standard-bearer within AURA_RADIUS_m. */
+export declare const BANNER_AURA_FEAR_REDUCTION: Q;
+/** Radius within which leader/banner auras apply (SCALE.m units). */
+export declare const AURA_RADIUS_m: number;
+/** Ticks of attack suppression after recovering from routing. */
+export declare const RALLY_COOLDOWN_TICKS = 60;
+/** Base fear decay per tick, multiplied by distressTolerance. */
+export declare const BASE_DECAY: Q;
+/** Additional fear decay per nearby living ally (cohesion effect). */
+export declare const ALLY_COHESION: Q;
+/** Additional fear decay per ally in a tight formation (Phase 32E). */
+export declare const FORMATION_COHESION: Q;
+/**
+ * Fear decay rate per tick.
+ * Scales with distressTolerance (stoic entities recover faster)
+ * and with nearby living ally count (cohesion effect).
+ *
+ * Returns a Q value to subtract from fearQ each tick.
+ */
+export declare function fearDecayPerTick(distressTolerance: Q, nearbyAllyCount: number, formationAllyCount?: number): Q;
+/**
+ * Routing threshold — minimum fear to trigger retreat behaviour.
+ * Higher distressTolerance → bolder → threshold is higher.
+ *
+ * Range: q(0.50) at tolerance=0 → q(0.80) at tolerance=1.
+ */
+export declare function moraleThreshold(distressTolerance: Q): Q;
+/**
+ * Whether an entity is currently routing.
+ */
+export declare function isRouting(fearQ: Q, distressTolerance: Q): boolean;
+/**
+ * Effective pain level from shock (0..1), reduced by distress tolerance.
+ *
+ * painLevel = shock × (1 − distressTolerance)
+ *
+ * Returns a Q value representing probability that pain blocks voluntary action.
+ */
+export declare function painLevel(shock: Q, distressTolerance: Q): Q;
+/**
+ * Deterministic pain suppression check.
+ * Returns true if pain prevents the entity from initiating an attack this tick.
+ *
+ * @param seed      - Caller supplies eventSeed(..., 0xPA15); value drives the roll.
+ * @param shock     - Entity's current shock level.
+ * @param distressTolerance - Entity's pain tolerance.
+ */
+export declare function painBlocksAction(seed: number, shock: Q, distressTolerance: Q): boolean;

package/dist/src/sim/morale.js

@@ -0,0 +1,92 @@
+/**
+ * Phase 5 — Morale and Psychological State
+ *
+ * Pure fixed-point functions. No Math.random(), no Entity imports.
+ * All randomness via eventSeed + caller-supplied seed.
+ */
+import { SCALE, q, clampQ, qMul } from "../units.js";
+// ── Fear increment constants ──────────────────────────────────────────────────
+/** Fear added per tick of active suppression (incoming near-miss fire). */
+export const FEAR_PER_SUPPRESSION_TICK = q(0.020);
+/** Fear added when a nearby ally is killed in the same tick. */
+export const FEAR_FOR_ALLY_DEATH = q(0.150);
+/** Multiplier: fear added per tick = shock × this. */
+export const FEAR_INJURY_MUL = q(0.012);
+/** Fear added per tick when enemies outnumber allies in awareness radius. */
+export const FEAR_OUTNUMBERED = q(0.010);
+/** Fear added to a defender per surprise attack (attacker undetected). */
+export const FEAR_SURPRISE = q(0.080);
+/** Fear added per tick when >50% of own team is already routing. */
+export const FEAR_ROUTING_CASCADE = q(0.030);
+// ── Phase 5 extension constants ───────────────────────────────────────────────
+/** Additional fear decay per leader within AURA_RADIUS_m. */
+export const LEADER_AURA_FEAR_REDUCTION = q(0.015);
+/** Additional fear decay per standard-bearer within AURA_RADIUS_m. */
+export const BANNER_AURA_FEAR_REDUCTION = q(0.010);
+/** Radius within which leader/banner auras apply (SCALE.m units). */
+export const AURA_RADIUS_m = Math.trunc(20 * SCALE.m);
+/** Ticks of attack suppression after recovering from routing. */
+export const RALLY_COOLDOWN_TICKS = 60;
+// ── Fear decay constants ──────────────────────────────────────────────────────
+/** Base fear decay per tick, multiplied by distressTolerance. */
+export const BASE_DECAY = q(0.008);
+/** Additional fear decay per nearby living ally (cohesion effect). */
+export const ALLY_COHESION = q(0.002);
+/** Additional fear decay per ally in a tight formation (Phase 32E). */
+export const FORMATION_COHESION = q(0.003);
+// ── Pure functions ────────────────────────────────────────────────────────────
+/**
+ * Fear decay rate per tick.
+ * Scales with distressTolerance (stoic entities recover faster)
+ * and with nearby living ally count (cohesion effect).
+ *
+ * Returns a Q value to subtract from fearQ each tick.
+ */
+export function fearDecayPerTick(distressTolerance, nearbyAllyCount, formationAllyCount) {
+    const base = qMul(BASE_DECAY, distressTolerance);
+    const cohesion = Math.min(nearbyAllyCount * ALLY_COHESION, q(0.020)); // cap at q(0.020)
+    const formation = formationAllyCount
+        ? Math.min(formationAllyCount * FORMATION_COHESION, q(0.015)) // cap at q(0.015)
+        : 0;
+    return clampQ(base + cohesion + formation, 0, q(0.040));
+}
+/**
+ * Routing threshold — minimum fear to trigger retreat behaviour.
+ * Higher distressTolerance → bolder → threshold is higher.
+ *
+ * Range: q(0.50) at tolerance=0 → q(0.80) at tolerance=1.
+ */
+export function moraleThreshold(distressTolerance) {
+    return clampQ(q(0.50) + qMul(distressTolerance, q(0.30)), q(0.50), q(0.80));
+}
+/**
+ * Whether an entity is currently routing.
+ */
+export function isRouting(fearQ, distressTolerance) {
+    return fearQ >= moraleThreshold(distressTolerance);
+}
+/**
+ * Effective pain level from shock (0..1), reduced by distress tolerance.
+ *
+ * painLevel = shock × (1 − distressTolerance)
+ *
+ * Returns a Q value representing probability that pain blocks voluntary action.
+ */
+export function painLevel(shock, distressTolerance) {
+    // shock × (SCALE.Q - distressTolerance) / SCALE.Q
+    return clampQ(qMul(shock, (SCALE.Q - distressTolerance)), 0, SCALE.Q);
+}
+/**
+ * Deterministic pain suppression check.
+ * Returns true if pain prevents the entity from initiating an attack this tick.
+ *
+ * @param seed      - Caller supplies eventSeed(..., 0xPA15); value drives the roll.
+ * @param shock     - Entity's current shock level.
+ * @param distressTolerance - Entity's pain tolerance.
+ */
+export function painBlocksAction(seed, shock, distressTolerance) {
+    const pain = painLevel(shock, distressTolerance);
+    if (pain <= 0)
+        return false;
+    return (seed % SCALE.Q) < pain;
+}