@its-not-rocket-science/ananke 0.1.0

package/dist/src/sim/aging.js

@@ -0,0 +1,243 @@
+// src/sim/aging.ts — Phase 57: Aging & Lifespan
+//
+// Attribute curves parameterized by normalized age fraction (ageFrac = ageYears / lifespanYears).
+// Species-agnostic: a human at 25 years and an elf at 187 years both have ageFrac ≈ 0.31 and
+// receive the same multipliers — the underlying biology follows the same developmental arc.
+//
+// Seven multiplier dimensions, each modelled as a piecewise-linear Q curve:
+//   muscularStrength  — peakForce, peakPower, continuousPower (peaks ~0.28 ageFrac)
+//   reactionTime      — multiplier on reactionTime_s (>q(1.0) = slower; peaks ~0.28)
+//   motorControl      — controlQuality, stability, fineControl (peaks ~0.28)
+//   stature           — stature_m (stable adult, slight compression in ancient)
+//   cognitionFluid    — logical, spatial, kinesthetic, musical (peaks ~0.28)
+//   cognitionCrystal  — linguistic, interpersonal, intrapersonal (peaks ~0.58)
+//   distressTolerance — pain/fear tolerance; wisdom accumulates to middle age
+//
+// Public API:
+//   computeAgeFrac(ageYears, lifespanYears?)      → Q [0..SCALE.Q]
+//   getAgePhase(ageYears, lifespanYears?)          → AgePhase
+//   deriveAgeMultipliers(ageYears, lifespanYears?) → AgeMultipliers
+//   applyAgingToAttributes(base, ageYears, ...)    → IndividualAttributes (new object)
+//   stepAging(entity, elapsedSeconds)              → mutates entity.age
+import { q, clampQ, SCALE } from "../units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Seconds in one year (non-leap). */
+export const SECONDS_PER_YEAR = 365 * 86_400; // 31 536 000
+/** Default lifespan for entities without a species override [years]. */
+export const HUMAN_LIFESPAN_YEARS = 80;
+const MUSCULAR_STRENGTH_KNOTS = [
+    [q(0.00), q(0.05)], // birth
+    [q(0.15), q(0.55)], // child
+    [q(0.25), q(1.00)], // peak young adult
+    [q(0.45), q(0.95)], // maintained adult
+    [q(0.65), q(0.75)], // elder decline
+    [q(1.00), q(0.40)], // ancient
+];
+// reactionTime_Q > SCALE.Q means reaction is SLOWER than the archetype baseline.
+const REACTION_TIME_KNOTS = [
+    [q(0.00), 25_000], // infant (2.5× baseline — newborn has negligible voluntary motor)
+    [q(0.15), 12_000], // adolescent (1.2×)
+    [q(0.28), 10_000], // peak (1.0× = no change from archetype)
+    [q(0.50), 10_800], // slight adult slowdown (1.08×)
+    [q(0.70), 12_500], // elder (1.25×)
+    [q(1.00), 20_000], // ancient (2.0×)
+];
+const MOTOR_CONTROL_KNOTS = [
+    [q(0.00), q(0.30)], // infant
+    [q(0.15), q(0.80)], // adolescent
+    [q(0.28), q(1.00)], // peak
+    [q(0.60), q(0.95)], // adult maintained
+    [q(0.85), q(0.75)], // elder
+    [q(1.00), q(0.55)], // ancient
+];
+const STATURE_KNOTS = [
+    [q(0.00), q(0.30)], // infant
+    [q(0.20), q(0.95)], // adolescent growth
+    [q(0.25), q(1.00)], // peak adult height
+    [q(0.70), q(1.00)], // stable through adulthood
+    [q(0.90), q(0.97)], // slight compression in elder
+    [q(1.00), q(0.94)], // ancient
+];
+const COGNITION_FLUID_KNOTS = [
+    [q(0.00), q(0.10)], // infant
+    [q(0.20), q(0.90)], // adolescent rapid development
+    [q(0.28), q(1.00)], // peak young adult (~22 years for human)
+    [q(0.50), q(0.90)], // adult gradual decline
+    [q(0.70), q(0.70)], // elder
+    [q(1.00), q(0.35)], // ancient
+];
+const COGNITION_CRYSTAL_KNOTS = [
+    [q(0.00), q(0.10)], // infant
+    [q(0.25), q(0.75)], // young adult still accumulating wisdom
+    [q(0.55), q(1.00)], // peak middle age (~44 years for human)
+    [q(0.80), q(0.98)], // elder — wisdom mostly preserved
+    [q(1.00), q(0.78)], // ancient
+];
+const DISTRESS_TOLERANCE_KNOTS = [
+    [q(0.00), q(0.50)], // infant
+    [q(0.20), q(0.80)], // adolescent
+    [q(0.45), q(1.00)], // peaks middle age (hard-won tolerance)
+    [q(0.75), q(1.05)], // elder slightly above baseline (wisdom bonus)
+    [q(1.00), q(0.85)], // ancient — some decline
+];
+// ── Core computation ──────────────────────────────────────────────────────────
+/** Piecewise-linear interpolation between sorted knot pairs. */
+function interpKnots(x_Q, knots) {
+    if (x_Q <= knots[0][0])
+        return knots[0][1];
+    for (let i = 1; i < knots.length; i++) {
+        const [x0, y0] = knots[i - 1];
+        const [x1, y1] = knots[i];
+        if (x_Q <= x1) {
+            const span = x1 - x0;
+            if (span === 0)
+                return y0;
+            const t = Math.round((x_Q - x0) * SCALE.Q / span);
+            return (y0 + Math.round((y1 - y0) * t / SCALE.Q));
+        }
+    }
+    return knots[knots.length - 1][1];
+}
+/**
+ * Compute normalized age fraction [0..SCALE.Q] for a given age and lifespan.
+ *
+ * A 25-year-old human (lifespan 80) → q(0.3125).
+ * A 187-year-old elf (lifespan 600) → q(0.312) — effectively the same developmental stage.
+ *
+ * @param ageYears      Current age in years.
+ * @param lifespanYears Expected lifespan (default: HUMAN_LIFESPAN_YEARS).
+ */
+export function computeAgeFrac(ageYears, lifespanYears = HUMAN_LIFESPAN_YEARS) {
+    if (lifespanYears <= 0)
+        return q(0);
+    return clampQ(Math.round(ageYears * SCALE.Q / lifespanYears), q(0), SCALE.Q);
+}
+/**
+ * Classify the entity's life stage from their normalized age fraction.
+ *
+ * Boundaries (ageFrac):
+ *   infant 0–0.05 | child 0.05–0.15 | adolescent 0.15–0.22 |
+ *   young_adult 0.22–0.38 | adult 0.38–0.62 | elder 0.62–0.88 | ancient 0.88+
+ */
+export function getAgePhase(ageYears, lifespanYears = HUMAN_LIFESPAN_YEARS) {
+    const f = computeAgeFrac(ageYears, lifespanYears);
+    if (f < q(0.05))
+        return "infant";
+    if (f < q(0.15))
+        return "child";
+    if (f < q(0.22))
+        return "adolescent";
+    if (f < q(0.38))
+        return "young_adult";
+    if (f < q(0.62))
+        return "adult";
+    if (f < q(0.88))
+        return "elder";
+    return "ancient";
+}
+/**
+ * Derive age-based attribute multipliers from normalized age and lifespan.
+ *
+ * All returned Q values except `reactionTime_Q` are in [0, SCALE.Q].
+ * `reactionTime_Q` may exceed SCALE.Q (values > q(1.0) indicate slower reaction
+ * than the archetype baseline).
+ */
+export function deriveAgeMultipliers(ageYears, lifespanYears = HUMAN_LIFESPAN_YEARS) {
+    const f = computeAgeFrac(ageYears, lifespanYears);
+    return {
+        muscularStrength_Q: interpKnots(f, MUSCULAR_STRENGTH_KNOTS),
+        reactionTime_Q: interpKnots(f, REACTION_TIME_KNOTS),
+        motorControl_Q: interpKnots(f, MOTOR_CONTROL_KNOTS),
+        stature_Q: interpKnots(f, STATURE_KNOTS),
+        cognitionFluid_Q: interpKnots(f, COGNITION_FLUID_KNOTS),
+        cognitionCrystal_Q: interpKnots(f, COGNITION_CRYSTAL_KNOTS),
+        distressTolerance_Q: interpKnots(f, DISTRESS_TOLERANCE_KNOTS),
+    };
+}
+/**
+ * Apply age multipliers to a base attribute set, returning a new object.
+ *
+ * The input `base` is treated as the archetype peak (typically from `generateIndividual`).
+ * The caller is responsible for caching the base and recomputing aged attributes when
+ * age advances (e.g. once per in-game month for campaign simulation).
+ *
+ * Attributes affected:
+ *   - morphology.stature_m
+ *   - performance.peakForce_N, peakPower_W, continuousPower_W
+ *   - control.reactionTime_s, controlQuality, stability, fineControl
+ *   - resilience.distressTolerance
+ *   - cognition (if present): fluid dims + crystal dims scaled independently
+ *
+ * All Q outputs are clamped to [0, SCALE.Q]; reactionTime_s is clamped to ≥ 1.
+ *
+ * @param base          Archetype-peak attributes (unmodified).
+ * @param ageYears      Current age in years.
+ * @param lifespanYears Expected lifespan (default: HUMAN_LIFESPAN_YEARS).
+ */
+export function applyAgingToAttributes(base, ageYears, lifespanYears = HUMAN_LIFESPAN_YEARS) {
+    const m = deriveAgeMultipliers(ageYears, lifespanYears);
+    return {
+        ...base,
+        morphology: {
+            ...base.morphology,
+            stature_m: Math.max(1, Math.round(base.morphology.stature_m * m.stature_Q / SCALE.Q)),
+        },
+        performance: {
+            ...base.performance,
+            peakForce_N: Math.max(1, Math.round(base.performance.peakForce_N * m.muscularStrength_Q / SCALE.Q)),
+            peakPower_W: Math.max(1, Math.round(base.performance.peakPower_W * m.muscularStrength_Q / SCALE.Q)),
+            continuousPower_W: Math.max(1, Math.round(base.performance.continuousPower_W * m.muscularStrength_Q / SCALE.Q)),
+        },
+        control: {
+            ...base.control,
+            reactionTime_s: Math.max(1, Math.round(base.control.reactionTime_s * m.reactionTime_Q / SCALE.Q)),
+            controlQuality: clampQ(Math.round(base.control.controlQuality * m.motorControl_Q / SCALE.Q), q(0), SCALE.Q),
+            stability: clampQ(Math.round(base.control.stability * m.motorControl_Q / SCALE.Q), q(0), SCALE.Q),
+            fineControl: clampQ(Math.round(base.control.fineControl * m.motorControl_Q / SCALE.Q), q(0), SCALE.Q),
+        },
+        resilience: {
+            ...base.resilience,
+            distressTolerance: clampQ(Math.round(base.resilience.distressTolerance * m.distressTolerance_Q / SCALE.Q), q(0), SCALE.Q),
+        },
+        // exactOptionalPropertyTypes: spread present cognition, otherwise omit the key entirely.
+        ...(base.cognition
+            ? {
+                cognition: {
+                    ...base.cognition,
+                    // Fluid intelligence (peaks young, declines earlier)
+                    logicalMathematical: clampQ(Math.round(base.cognition.logicalMathematical * m.cognitionFluid_Q / SCALE.Q), q(0), SCALE.Q),
+                    spatial: clampQ(Math.round(base.cognition.spatial * m.cognitionFluid_Q / SCALE.Q), q(0), SCALE.Q),
+                    bodilyKinesthetic: clampQ(Math.round(base.cognition.bodilyKinesthetic * m.cognitionFluid_Q / SCALE.Q), q(0), SCALE.Q),
+                    musical: clampQ(Math.round(base.cognition.musical * m.cognitionFluid_Q / SCALE.Q), q(0), SCALE.Q),
+                    // Crystallized intelligence (peaks mid-life, persists through elder)
+                    linguistic: clampQ(Math.round(base.cognition.linguistic * m.cognitionCrystal_Q / SCALE.Q), q(0), SCALE.Q),
+                    interpersonal: clampQ(Math.round(base.cognition.interpersonal * m.cognitionCrystal_Q / SCALE.Q), q(0), SCALE.Q),
+                    intrapersonal: clampQ(Math.round(base.cognition.intrapersonal * m.cognitionCrystal_Q / SCALE.Q), q(0), SCALE.Q),
+                },
+            }
+            : {}),
+    };
+}
+/**
+ * Advance an entity's age by `elapsedSeconds`.
+ *
+ * Initializes `entity.age` if absent. Does NOT recompute attributes — the host
+ * should call `applyAgingToAttributes` when it needs current aged stats.
+ *
+ * Mutates: `entity.age`.
+ */
+export function stepAging(entity, elapsedSeconds) {
+    if (!entity.age) {
+        entity.age = { ageSeconds: 0 };
+    }
+    entity.age.ageSeconds += elapsedSeconds;
+}
+/**
+ * Convenience helper: return the current age in fractional years from entity.age.
+ * Returns 0 if `entity.age` is absent.
+ */
+export function entityAgeYears(entity) {
+    if (!entity.age)
+        return 0;
+    return entity.age.ageSeconds / SECONDS_PER_YEAR;
+}

package/dist/src/sim/ai/decide.d.ts

@@ -0,0 +1,10 @@
+import type { Entity } from "../entity.js";
+import type { WorldState } from "../world.js";
+import type { WorldIndex } from "../indexing.js";
+import type { SpatialIndex } from "../spatial.js";
+import type { Command } from "../commands.js";
+import { type I32 } from "../../units.js";
+import type { AIPolicy } from "./types.js";
+import { type SensoryEnvironment } from "../sensory.js";
+import { type ObstacleGrid } from "../terrain.js";
+export declare function decideCommandsForEntity(world: WorldState, index: WorldIndex, spatial: SpatialIndex, self: Entity, policy: AIPolicy, env?: SensoryEnvironment, obstacleGrid?: ObstacleGrid, cellSize_m?: I32): readonly Command[];

package/dist/src/sim/ai/decide.js

@@ -0,0 +1,267 @@
+import { q, clampQ, qMul, mulDiv, SCALE } from "../../units.js";
+import { pickTarget, updateFocus } from "./targeting.js";
+import { findWeapon } from "../../equipment.js";
+import { v3, normaliseDirCheapQ } from "../vec3.js";
+import { DEFAULT_PERCEPTION, DEFAULT_SENSORY_ENV } from "../sensory.js";
+import { isRouting, moraleThreshold } from "../morale.js";
+import { eventSeed } from "../seeds.js";
+import { coverFractionAtPosition, terrainKey } from "../terrain.js";
+import { getSkill } from "../skills.js";
+import { TICK_HZ } from "../tick.js";
+import { effectiveStanding, STANDING_FRIENDLY_THRESHOLD } from "../../faction.js";
+import { computeEffectiveRetreatRange, computeDefenceIntensityBoost, applyLoyaltyBias, applyOpportunismBias, computeEffectiveLoyalty, } from "./personality.js";
+export function decideCommandsForEntity(world, index, spatial, self, policy, env = DEFAULT_SENSORY_ENV, obstacleGrid, cellSize_m) {
+    if (self.injury.dead)
+        return [];
+    // Feature 4: surrendered entities are permanently passive
+    if ((self.condition).surrendered) {
+        return [
+            { kind: "defend", mode: "none", intensity: q(0) },
+            { kind: "setProne", prone: true },
+        ];
+    }
+    // tick down AI cooldowns
+    if (!self.ai)
+        self.ai = { focusTargetId: 0, retargetCooldownTicks: 0, decisionCooldownTicks: 0 };
+    if ((self.ai).decisionCooldownTicks === undefined)
+        (self.ai).decisionCooldownTicks = 0;
+    self.ai.retargetCooldownTicks = Math.max(0, self.ai.retargetCooldownTicks - 1);
+    self.ai.decisionCooldownTicks = Math.max(0, self.ai.decisionCooldownTicks - 1);
+    // Phase 4: decision latency — while cooling down, skip replanning and repeat current intent.
+    if (self.ai.decisionCooldownTicks > 0) {
+        // Emit the same defend and move as last tick (intent is already set from previous tick).
+        return [];
+    }
+    // Charge latency for next decision cycle
+    const perc = (self.attributes).perception ?? DEFAULT_PERCEPTION;
+    // Phase 7: tactics.hitTimingOffset_s reduces decision latency (max 50% reduction)
+    const tacticsSkill = getSkill(self.skills, "tactics");
+    const adjustedLatency_s = Math.max(Math.trunc(perc.decisionLatency_s / 2), perc.decisionLatency_s + tacticsSkill.hitTimingOffset_s);
+    // Phase 33: logicalMathematical reduces decision latency (faster tactical processing)
+    // Formula: mul = q(1.20) − logMath × q(0.40); human (0.60) → ×0.96; Vulcan (0.95) → ×0.82
+    const logMath = self.attributes.cognition?.logicalMathematical ?? 0;
+    const logLatencyMul = logMath
+        ? clampQ((q(1.20) - Math.trunc(mulDiv(q(0.40), logMath, SCALE.Q))), q(0.50), q(1.20))
+        : SCALE.Q;
+    const scaledLatency_s = logMath ? mulDiv(adjustedLatency_s, logLatencyMul, SCALE.Q) : adjustedLatency_s;
+    const latencyTicks = Math.max(1, Math.trunc((scaledLatency_s * TICK_HZ) / SCALE.s));
+    self.ai.decisionCooldownTicks = latencyTicks;
+    // Phase 5: morale states — routing flees; hesitant suppresses attacks
+    const fearQ = (self.condition).fearQ ?? q(0);
+    const distressTol = self.attributes.resilience.distressTolerance;
+    const fearResp = (self.attributes.resilience).fearResponse ?? "flight";
+    // Phase 47: personality-driven overrides
+    const personality = self.personality;
+    // Feature 6: berserk entities never route or hesitate
+    // Phase 47: high-aggression entities (> q(0.70)) also override hesitation
+    const isHesitant = fearResp !== "berserk" &&
+        !isRouting(fearQ, distressTol) &&
+        fearQ >= qMul(moraleThreshold(distressTol), q(0.70)) &&
+        (!personality || personality.aggression < q(0.70));
+    if (fearResp !== "berserk" && isRouting(fearQ, distressTol)) {
+        // Feature 6: freeze archetype routes by freezing instead of fleeing
+        if (fearResp === "freeze") {
+            return [];
+        }
+        // Feature 4: panic action variety — seeded surrender/freeze/flee roll
+        const panicSeed = eventSeed(world.seed, world.tick, self.id, 0, 0xFA115);
+        const surrenderChance = Math.trunc(qMul(q(0.10), (SCALE.Q - distressTol)));
+        const freezeChance = Math.trunc(qMul(q(0.15), (SCALE.Q - distressTol)));
+        const r = panicSeed % SCALE.Q;
+        if (r < surrenderChance) {
+            (self.condition).surrendered = true;
+            return [
+                { kind: "defend", mode: "none", intensity: q(0) },
+                { kind: "setProne", prone: true },
+            ];
+        }
+        if (r < surrenderChance + freezeChance) {
+            return [];
+        }
+        const nearestThreat = pickTarget(world, self, index, spatial, policy, env);
+        if (nearestThreat) {
+            const fdx = self.position_m.x - nearestThreat.position_m.x;
+            const fdy = self.position_m.y - nearestThreat.position_m.y;
+            return [
+                { kind: "defend", mode: "none", intensity: q(0) },
+                {
+                    kind: "move",
+                    dir: normaliseDirCheapQ(v3(fdx !== 0 || fdy !== 0 ? fdx : 1, fdy, 0)),
+                    intensity: q(1.0),
+                    mode: "sprint",
+                },
+            ];
+        }
+        return [{ kind: "defend", mode: "none", intensity: q(0) }];
+    }
+    // Phase 3 extension: suppression response — go prone when sustained under fire (low distressTol only)
+    const suppressedTicks = (self.condition).suppressedTicks ?? 0;
+    if (suppressedTicks >= 3 && distressTol < q(0.50)) {
+        const suppCmds = [{ kind: "defend", mode: "none", intensity: q(0) }];
+        if (!self.condition.prone) {
+            suppCmds.push({ kind: "setProne", prone: true });
+        }
+        return suppCmds;
+    }
+    let target = pickTarget(world, self, index, spatial, policy, env);
+    // Phase 47: personality-driven target bias (loyalty before opportunism)
+    const effectiveLoyalty = computeEffectiveLoyalty(self, world);
+    target = applyLoyaltyBias(self, world, target, effectiveLoyalty);
+    if (personality) {
+        target = applyOpportunismBias(self, world, target, personality.opportunism);
+    }
+    // Phase 24: faction standing — suppress attack on friendly entities.
+    // Self-defence override: if self has taken damage (shock > 0 or fluid loss > 0),
+    // faction check is bypassed (attacker is fought back regardless of standing).
+    if (target && self.faction) {
+        const factionRegistry = (world).__factionRegistry;
+        if (factionRegistry) {
+            const standing = effectiveStanding(factionRegistry, self, target);
+            const selfDefence = self.injury.shock > 0 || self.injury.fluidLoss > 0;
+            if (!selfDefence && standing >= STANDING_FRIENDLY_THRESHOLD) {
+                target = undefined;
+            }
+        }
+    }
+    updateFocus(self, target, policy);
+    // Default defend
+    let defendMode = "none";
+    let defendIntensity = q(0);
+    if (target) {
+        const dx = target.position_m.x - self.position_m.x;
+        const dy = target.position_m.y - self.position_m.y;
+        const d2 = BigInt(dx) * BigInt(dx) + BigInt(dy) * BigInt(dy);
+        const threatR = Math.max(1, policy.threatRange_m);
+        const threatD2 = BigInt(threatR) * BigInt(threatR);
+        if (d2 < threatD2) {
+            defendMode = pickDefenceModeDeterministic(policy);
+            // Phase 47: caution boosts/reduces defence intensity (±q(0.20) max at extremes)
+            defendIntensity = personality
+                ? computeDefenceIntensityBoost(policy.defendWhenThreatenedQ, personality.caution)
+                : clampQ(policy.defendWhenThreatenedQ, q(0), q(1.0));
+        }
+    }
+    const cmds = [];
+    cmds.push({ kind: "defend", mode: defendMode, intensity: defendIntensity });
+    if (!target) {
+        // still emit a “no move”
+        cmds.push({ kind: "move", dir: v3(0, 0, 0), intensity: q(0), mode: "walk" });
+        return cmds;
+    }
+    // movement: try to maintain desired range
+    const dx = target.position_m.x - self.position_m.x;
+    const dy = target.position_m.y - self.position_m.y;
+    const distApprox = approxDist(dx, dy);
+    const want = policy.desiredRange_m;
+    const engage = policy.engageRange_m;
+    // Move toward if too far, back off if too close
+    // Phase 47: aggression shifts the effective retreat range (aggressive → less retreat)
+    const effectiveRetreatRange = personality
+        ? computeEffectiveRetreatRange(policy.retreatRange_m, personality.aggression)
+        : policy.retreatRange_m;
+    let dirX = 0, dirY = 0;
+    if (distApprox > want) {
+        dirX = dx;
+        dirY = dy;
+    }
+    else if (distApprox < effectiveRetreatRange) {
+        dirX = -dx;
+        dirY = -dy;
+    }
+    let moveMode = distApprox > engage ? "sprint" : "run";
+    // Phase 6: cover-seeking — if exposed to enemies with no cover, move toward the best adjacent cell.
+    const aiCellSize = cellSize_m ?? Math.trunc(4 * SCALE.m);
+    const selfCoverQ = obstacleGrid
+        ? coverFractionAtPosition(obstacleGrid, aiCellSize, self.position_m.x, self.position_m.y)
+        : 0;
+    const coverThreshold = suppressedTicks > 0 ? q(0.50) : q(0.30);
+    if (selfCoverQ < coverThreshold && !isRouting(fearQ, distressTol)) {
+        const enemyCount = world.entities.filter(en => en.teamId !== self.teamId && !en.injury.dead &&
+            approxDist(en.position_m.x - self.position_m.x, en.position_m.y - self.position_m.y) < Math.trunc(30 * SCALE.m)).length;
+        if (enemyCount > 0) {
+            const coverDir = findBestCoverDir(self, obstacleGrid, aiCellSize);
+            if (coverDir) {
+                dirX = coverDir.x;
+                dirY = coverDir.y;
+                moveMode = "run";
+            }
+        }
+    }
+    if (dirX !== 0 || dirY !== 0) {
+        cmds.push({
+            kind: "move",
+            dir: normaliseDirCheapQ(v3(dirX, dirY, 0)),
+            intensity: q(1.0),
+            mode: moveMode,
+        });
+    }
+    else {
+        cmds.push({
+            kind: "move",
+            dir: v3(0, 0, 0),
+            intensity: q(0),
+            mode: "walk",
+        });
+    }
+    // attack when within engage range — hesitant or rallying entities hold back
+    const weapon = findWeapon(self.loadout, undefined);
+    const isRallying = ((self.condition).rallyCooldownTicks ?? 0) > 0;
+    if (weapon && !isHesitant && !isRallying) {
+        const reach = weapon.reach_m ?? Math.trunc(self.attributes.morphology.stature_m * 0.45);
+        if (distApprox <= reach + Math.trunc(0.25 * SCALE.m)) {
+            cmds.push({
+                kind: "attack",
+                targetId: target.id,
+                weaponId: weapon.id,
+                intensity: q(1.0),
+                mode: "strike",
+            });
+        }
+    }
+    return cmds;
+}
+function pickDefenceModeDeterministic(policy) {
+    // Deterministic selection (no RNG): allow dodge path.
+    // If dodge preference is strong, dodge. Else if parry preference strong, parry. Else block.
+    if (policy.dodgeBiasQ > policy.parryBiasQ && policy.dodgeBiasQ > q(0.50))
+        return "dodge";
+    if (policy.parryBiasQ > q(0.35))
+        return "parry";
+    return "block";
+}
+function approxDist(dx, dy) {
+    const adx = dx < 0 ? -dx : dx;
+    const ady = dy < 0 ? -dy : dy;
+    return adx > ady ? adx + (ady >> 1) : ady + (adx >> 1);
+}
+/**
+ * Scan the 8 adjacent cells and return a direction toward the one with the highest
+ * cover fraction that is better than the current cell (and not impassable).
+ * Returns undefined if already at the local cover maximum.
+ */
+function findBestCoverDir(self, grid, cellSize_m) {
+    if (!grid)
+        return undefined;
+    const cs = Math.max(1, cellSize_m);
+    const cx = Math.trunc(self.position_m.x / cs);
+    const cy = Math.trunc(self.position_m.y / cs);
+    const currentCover = grid.get(terrainKey(cx, cy)) ?? 0;
+    let bestCover = currentCover;
+    let bestDx = 0, bestDy = 0;
+    for (let ddx = -1; ddx <= 1; ddx++) {
+        for (let ddy = -1; ddy <= 1; ddy++) {
+            if (ddx === 0 && ddy === 0)
+                continue;
+            const frac = grid.get(terrainKey(cx + ddx, cy + ddy)) ?? 0;
+            // Prefer higher cover but skip impassable cells (q(1.0) = SCALE.Q)
+            if (frac > bestCover && frac < SCALE.Q) {
+                bestCover = frac;
+                bestDx = ddx;
+                bestDy = ddy;
+            }
+        }
+    }
+    if (bestDx === 0 && bestDy === 0)
+        return undefined;
+    return { x: bestDx, y: bestDy, z: 0 };
+}

package/dist/src/sim/ai/perception.d.ts

@@ -0,0 +1,12 @@
+import type { Entity } from "../entity.js";
+import type { WorldState } from "../world.js";
+import type { WorldIndex } from "../indexing.js";
+import type { SpatialIndex } from "../spatial.js";
+import { type SensoryEnvironment } from "../sensory.js";
+export interface LocalPerception {
+    enemies: Entity[];
+    allies: Entity[];
+}
+/** @deprecated Use LocalPerception */
+export type Perception = LocalPerception;
+export declare function perceiveLocal(world: WorldState | undefined, self: Entity, index: WorldIndex, spatial: SpatialIndex, radius_m: number, maxCount?: number, env?: SensoryEnvironment): LocalPerception;

package/dist/src/sim/ai/perception.js

@@ -0,0 +1,54 @@
+import { queryNearbyIds } from "../spatial.js";
+import { isEnemy, areEntitiesHostile } from "../team.js";
+import { q } from "../../units.js";
+import { canDetect, DEFAULT_PERCEPTION, DEFAULT_SENSORY_ENV } from "../sensory.js";
+import { findSensor } from "../../equipment.js";
+export function perceiveLocal(world, self, index, spatial, radius_m, maxCount = 24, env = DEFAULT_SENSORY_ENV) {
+    const perc = (self.attributes).perception ?? DEFAULT_PERCEPTION;
+    // Use the threat horizon as the spatial query radius if it is smaller than the requested radius.
+    const effectiveRadius = Math.min(radius_m, perc.threatHorizon_m);
+    const ids = queryNearbyIds(spatial, self.position_m, effectiveRadius);
+    ids.sort((a, b) => a - b);
+    const enemies = [];
+    const allies = [];
+    for (const id of ids) {
+        if (id === self.id)
+            continue;
+        const e = index.byId.get(id);
+        if (!e || e.injury.dead)
+            continue;
+        // Phase 4: filter by sensory detection
+        // Phase 11C: derive sensor boost from loadout
+        const sensor = findSensor(self.loadout);
+        const sensorBoost = sensor
+            ? { visionRangeMul: sensor.visionRangeMul, hearingRangeMul: sensor.hearingRangeMul }
+            : undefined;
+        const detQ = canDetect(self, e, env, sensorBoost);
+        if (detQ <= q(0))
+            continue;
+        const hostile = world ? areEntitiesHostile(self, e, world) : isEnemy(self, e);
+        if (hostile)
+            enemies.push(e);
+        else
+            allies.push(e);
+        if (enemies.length + allies.length >= maxCount)
+            break;
+    }
+    // deterministic order: distance² then id
+    const sortByDist = (a, b) => {
+        const dxA = a.position_m.x - self.position_m.x;
+        const dyA = a.position_m.y - self.position_m.y;
+        const d2A = BigInt(dxA) * BigInt(dxA) + BigInt(dyA) * BigInt(dyA);
+        const dxB = b.position_m.x - self.position_m.x;
+        const dyB = b.position_m.y - self.position_m.y;
+        const d2B = BigInt(dxB) * BigInt(dxB) + BigInt(dyB) * BigInt(dyB);
+        if (d2A < d2B)
+            return -1;
+        if (d2A > d2B)
+            return 1;
+        return a.id - b.id;
+    };
+    enemies.sort(sortByDist);
+    allies.sort(sortByDist);
+    return { enemies, allies };
+}

package/dist/src/sim/ai/personality.d.ts

@@ -0,0 +1,54 @@
+import type { Q } from "../../units.js";
+import type { Entity } from "../entity.js";
+import type { WorldState } from "../world.js";
+import type { IndividualAttributes, PersonalityTraits, PersonalityId } from "../../types.js";
+export type { PersonalityTraits, PersonalityId };
+/**
+ * Neutral personality: q(0.50) on all axes.
+ * Produces identical behaviour to an entity with no personality set.
+ */
+export declare const NEUTRAL_PERSONALITY: PersonalityTraits;
+/** Named predefined personalities. */
+export declare const PERSONALITIES: Record<PersonalityId, PersonalityTraits>;
+/**
+ * Derive a personality from existing cognitive and resilience attributes.
+ *
+ * Mapping rationale:
+ *   aggression  ← distressTolerance (pain tolerance → willing to keep fighting)
+ *   caution     ← intrapersonal     (self-awareness → more careful and defensive)
+ *   loyalty     ← interpersonal     (social empathy → protects allies)
+ *   opportunism ← logicalMathematical (planning → targets strategically)
+ */
+export declare function derivePersonalityFromCognition(attrs: IndividualAttributes): PersonalityTraits;
+/**
+ * Compute effective loyalty combining personality loyalty and companion loyalty to party leader.
+ * If entity belongs to a party and has a relationship with the leader, companion loyalty is used.
+ * Otherwise falls back to personality loyalty (or neutral q(0.50) if no personality).
+ */
+export declare function computeEffectiveLoyalty(self: Entity, world: WorldState): Q;
+/**
+ * Effective retreat range after aggression bias.
+ *
+ * aggression q(0.90) → range reduced by ~0.20m (fights more aggressively)
+ * aggression q(0.50) → unchanged
+ * aggression q(0.10) → range increased by ~0.20m (retreats sooner)
+ */
+export declare function computeEffectiveRetreatRange(baseRange_m: number, aggression: Q): number;
+/**
+ * Effective defence intensity after caution bias.
+ *
+ * caution q(0.90) → +q(0.20) max boost
+ * caution q(0.50) → unchanged
+ * caution q(0.10) → −q(0.20) max reduction
+ */
+export declare function computeDefenceIntensityBoost(baseIntensity: Q, caution: Q): Q;
+/**
+ * Loyalty override: if an ally is in distress and has an enemy nearby, switch target to
+ * that enemy.  Only triggers when loyalty > q(0.50); roll probability = loyaltyQ / SCALE.Q.
+ */
+export declare function applyLoyaltyBias(self: Entity, world: WorldState, currentTarget: Entity | undefined, loyaltyQ: Q): Entity | undefined;
+/**
+ * Opportunism override: if a significantly more-wounded enemy is present, switch target.
+ * Only triggers when opportunism > q(0.50); roll probability = opportunismQ / SCALE.Q.
+ */
+export declare function applyOpportunismBias(self: Entity, world: WorldState, currentTarget: Entity | undefined, opportunismQ: Q): Entity | undefined;