@its-not-rocket-science/ananke 0.1.0

package/dist/src/sim/sensory.js

@@ -0,0 +1,109 @@
+/**
+ * Phase 4: Sensory environment model.
+ *
+ * Fixed-point only. No Math.random() — all randomness via eventSeed if needed.
+ * Light, smoke, and noise modifiers are Q values (SCALE.Q = full normal conditions).
+ */
+import { SCALE, q, mulDiv } from "../units.js";
+import { getSkill } from "./skills.js";
+// Default perception — used as init guard for entities without Phase 4 attributes.
+export const DEFAULT_PERCEPTION = {
+    visionRange_m: Math.trunc(200 * SCALE.m),
+    visionArcDeg: 120,
+    halfArcCosQ: Math.round(Math.cos((120 / 2) * (Math.PI / 180)) * SCALE.Q),
+    hearingRange_m: Math.trunc(50 * SCALE.m),
+    decisionLatency_s: Math.trunc(0.5 * SCALE.s),
+    attentionDepth: 4,
+    threatHorizon_m: Math.trunc(40 * SCALE.m),
+};
+export const DEFAULT_SENSORY_ENV = {
+    lightMul: q(1.0),
+    smokeMul: q(1.0),
+    noiseMul: q(1.0),
+};
+/**
+ * Compute detection quality of `subject` by `observer`.
+ *
+ * Returns a Q value:
+ *   q(1.0) = fully visible (within vision arc and range)
+ *   q(0.4) = heard only (within hearing range but not vision)
+ *   q(0)   = undetected
+ *
+ * Vision check: dot-product of facing direction vs observer→subject vector.
+ * Hearing: omnidirectional.
+ *
+ * Pure function — no side effects.
+ */
+export function canDetect(observer, subject, env, 
+/** Phase 11C: optional sensor boost from the observer's loadout. */
+sensorBoost) {
+    const perc = (observer.attributes).perception ?? DEFAULT_PERCEPTION;
+    // Phase 10C: blinded observer cannot see
+    const isBlind = (observer.condition).blindTicks > 0;
+    const dx = subject.position_m.x - observer.position_m.x;
+    const dy = subject.position_m.y - observer.position_m.y;
+    const dz = subject.position_m.z - observer.position_m.z;
+    // Squared distance (still in SCALE.m² fixed-point)
+    const dist2 = BigInt(dx) * BigInt(dx) + BigInt(dy) * BigInt(dy) + BigInt(dz) * BigInt(dz);
+    // ---- Vision ----
+    // Phase 10C: blinded observer has zero effective vision range
+    let effectiveVision = isBlind ? 0 : mulDiv(mulDiv(perc.visionRange_m, env.lightMul, SCALE.Q), env.smokeMul, SCALE.Q);
+    if (!isBlind && sensorBoost)
+        effectiveVision = mulDiv(effectiveVision, sensorBoost.visionRangeMul, SCALE.Q);
+    const visionR2 = BigInt(effectiveVision) * BigInt(effectiveVision);
+    if (dist2 <= visionR2) {
+        // Check if subject is within observer's facing arc.
+        // For 360° arc (visionArcDeg >= 360) skip the arc check.
+        if (perc.visionArcDeg >= 360)
+            return q(1.0);
+        // Dot product of normalized facing vs direction to subject.
+        // We compare in fixed-point Q units using the pre-computed halfArcCosQ.
+        const facing = observer.action.facingDirQ;
+        const dotQ = dotQ3(facing, dx, dy, dz, dist2);
+        if (dotQ >= perc.halfArcCosQ)
+            return q(1.0);
+    }
+    // ---- Hearing ----
+    // Phase 7: stealth.dispersionMul reduces subject's acoustic signature
+    // (multiplied into observer's effective hearing range for this subject)
+    const stealthSkill = getSkill(subject.skills, "stealth");
+    let effectiveHearing = mulDiv(mulDiv(perc.hearingRange_m, env.noiseMul, SCALE.Q), stealthSkill.dispersionMul, SCALE.Q);
+    if (sensorBoost)
+        effectiveHearing = mulDiv(effectiveHearing, sensorBoost.hearingRangeMul, SCALE.Q);
+    const hearingR2 = BigInt(effectiveHearing) * BigInt(effectiveHearing);
+    if (dist2 <= hearingR2)
+        return q(0.4);
+    return q(0);
+}
+/**
+ * Dot product of a normalized facing direction (Q components) against an unnormalized
+ * vector (dx, dy, dz) with squared magnitude dist2. Returns a Q value.
+ *
+ * facing is already in Q units (each component is Q scaled, magnitude ≈ SCALE.Q).
+ * dx/dy/dz are in SCALE.m units; we normalise them into Q using dist_m.
+ *
+ * Result in Q: positive = same direction, negative = opposite.
+ */
+function dotQ3(facing, dx, dy, dz, dist2) {
+    if (dist2 === 0n)
+        return q(0);
+    // Approximate dist_m via integer sqrt of dist2
+    let r = dist2;
+    let r1 = (r + 1n) >> 1n;
+    while (r1 < r) {
+        r = r1;
+        r1 = (r + dist2 / r) >> 1n;
+    }
+    const dist_m = Number(r);
+    if (dist_m === 0)
+        return q(0);
+    // Normalise dx/dy/dz into Q space
+    const ndx = mulDiv(dx, SCALE.Q, dist_m);
+    const ndy = mulDiv(dy, SCALE.Q, dist_m);
+    const ndz = mulDiv(dz, SCALE.Q, dist_m);
+    // Both facing and n* are in Q units; dot product → divide by SCALE.Q
+    const raw = mulDiv(facing.x, ndx, SCALE.Q)
+        + mulDiv(facing.y, ndy, SCALE.Q)
+        + mulDiv(facing.z, ndz, SCALE.Q);
+    return Math.max(-SCALE.Q, Math.min(SCALE.Q, raw));
+}

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

@@ -0,0 +1,70 @@
+import { type Q, type I32 } from "../units.js";
+export declare const SKILL_IDS: readonly ["meleeCombat", "meleeDefence", "grappling", "rangedCombat", "throwingWeapons", "shieldCraft", "medical", "athleticism", "tactics", "stealth"];
+export type SkillId = (typeof SKILL_IDS)[number];
+/**
+ * A SkillLevel is a set of physical outcome modifiers for one skill domain.
+ * All fields default to the neutral value (no effect on simulation output).
+ */
+export interface SkillLevel {
+    /**
+     * Timing offset (SCALE.s units). Negative = faster action or reaction.
+     *   meleeCombat: reduces attack recovery time (fewer ticks until next attack).
+     *   tactics:     reduces AI decision latency (faster plan revisions).
+     */
+    hitTimingOffset_s: I32;
+    /**
+     * Efficiency multiplier (Q). > q(1.0) = beneficial.
+     *   meleeCombat:     multiplied into strike impact energy.
+     *   meleeDefence:    multiplied into effective defence skill (parry / block quality).
+     *   grappling:       multiplied into grapple contest score (leverage bonus).
+     *   throwingWeapons: multiplied into thrown weapon launch energy.
+     *   shieldCraft:     multiplied into effective defence skill when blocking with a shield.
+     */
+    energyTransferMul: Q;
+    /**
+     * Dispersion multiplier (Q). < q(1.0) = tighter spread or smaller signature.
+     *   rangedCombat: multiplied into adjusted dispersion (more accurate fire).
+     *   stealth:      multiplied into the observer's effective hearing range for this
+     *                 entity (reduces acoustic signature — harder to detect by hearing).
+     */
+    dispersionMul: Q;
+    /**
+     * Treatment rate multiplier (Q). > q(1.0) = better self-care.
+     *   medical: divides the effective bleed-to-fluid-loss increment each tick
+     *            (passive wound management — slower fluid loss from bleeding).
+     */
+    treatmentRateMul: Q;
+    /**
+     * Fatigue rate multiplier (Q). < q(1.0) = less fatigue per tick.
+     *   athleticism: multiplied into the fatigue delta each energy tick.
+     */
+    fatigueRateMul: Q;
+}
+export type SkillMap = Map<SkillId, SkillLevel>;
+/** Returns a SkillLevel with all fields at the neutral (no-effect) value. */
+export declare function defaultSkillLevel(): SkillLevel;
+/**
+ * Build a SkillMap from a partial record.
+ * Any missing fields in each entry default to the neutral values.
+ */
+export declare function buildSkillMap(entries: Partial<Record<SkillId, Partial<SkillLevel>>>): SkillMap;
+/** Look up a skill level; returns neutral defaults when the map is absent or the skill is not set. */
+export declare function getSkill(skills: SkillMap | undefined, id: SkillId): SkillLevel;
+/**
+ * Combine two SkillLevels into one composite level.
+ *
+ * Use this in the host application to express synergy bonuses or to composite
+ * a base skill with a situational modifier before building the SkillMap.
+ * The engine itself has no concept of synergies — compositing happens outside.
+ *
+ * Combination rules:
+ *   hitTimingOffset_s  — additive    (both offsets reduce timing independently)
+ *   energyTransferMul  — qMul        (efficiency gains multiply)
+ *   dispersionMul      — qMul        (tighter spreads multiply)
+ *   treatmentRateMul   — qMul        (healing bonuses multiply)
+ *   fatigueRateMul     — qMul        (fatigue reductions multiply)
+ *
+ * Example: meleeCombat synergised with an athleticism bonus
+ *   buildSkillMap({ meleeCombat: combineSkillLevels(baseMelee, athleticismSynergyBonus) })
+ */
+export declare function combineSkillLevels(a: SkillLevel, b: SkillLevel): SkillLevel;

package/dist/src/sim/skills.js

@@ -0,0 +1,69 @@
+// src/sim/skills.ts — Phase 7: Skill System
+//
+// Skills are learned technique modifiers separate from physical attributes.
+// They adjust physical outcomes rather than providing abstract point bonuses.
+// The engine consumes skill values; progression is managed by the host application.
+import { q } from "../units.js";
+export const SKILL_IDS = [
+    "meleeCombat",
+    "meleeDefence",
+    "grappling",
+    "rangedCombat",
+    "throwingWeapons",
+    "shieldCraft",
+    "medical",
+    "athleticism",
+    "tactics",
+    "stealth",
+];
+/** Returns a SkillLevel with all fields at the neutral (no-effect) value. */
+export function defaultSkillLevel() {
+    return {
+        hitTimingOffset_s: 0,
+        energyTransferMul: q(1.0),
+        dispersionMul: q(1.0),
+        treatmentRateMul: q(1.0),
+        fatigueRateMul: q(1.0),
+    };
+}
+/**
+ * Build a SkillMap from a partial record.
+ * Any missing fields in each entry default to the neutral values.
+ */
+export function buildSkillMap(entries) {
+    const m = new Map();
+    for (const [k, v] of Object.entries(entries)) {
+        m.set(k, { ...defaultSkillLevel(), ...v });
+    }
+    return m;
+}
+/** Look up a skill level; returns neutral defaults when the map is absent or the skill is not set. */
+export function getSkill(skills, id) {
+    return skills?.get(id) ?? defaultSkillLevel();
+}
+/**
+ * Combine two SkillLevels into one composite level.
+ *
+ * Use this in the host application to express synergy bonuses or to composite
+ * a base skill with a situational modifier before building the SkillMap.
+ * The engine itself has no concept of synergies — compositing happens outside.
+ *
+ * Combination rules:
+ *   hitTimingOffset_s  — additive    (both offsets reduce timing independently)
+ *   energyTransferMul  — qMul        (efficiency gains multiply)
+ *   dispersionMul      — qMul        (tighter spreads multiply)
+ *   treatmentRateMul   — qMul        (healing bonuses multiply)
+ *   fatigueRateMul     — qMul        (fatigue reductions multiply)
+ *
+ * Example: meleeCombat synergised with an athleticism bonus
+ *   buildSkillMap({ meleeCombat: combineSkillLevels(baseMelee, athleticismSynergyBonus) })
+ */
+export function combineSkillLevels(a, b) {
+    return {
+        hitTimingOffset_s: (a.hitTimingOffset_s + b.hitTimingOffset_s),
+        energyTransferMul: Math.trunc(a.energyTransferMul * b.energyTransferMul / 10_000),
+        dispersionMul: Math.trunc(a.dispersionMul * b.dispersionMul / 10_000),
+        treatmentRateMul: Math.trunc(a.treatmentRateMul * b.treatmentRateMul / 10_000),
+        fatigueRateMul: Math.trunc(a.fatigueRateMul * b.fatigueRateMul / 10_000),
+    };
+}

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

@@ -0,0 +1,107 @@
+import { type Q } from "../units.js";
+import type { IndividualAttributes } from "../types.js";
+import type { Entity } from "./entity.js";
+/** Current sleep phase. "awake" when the entity is not sleeping. */
+export type SleepPhase = "awake" | "light" | "deep" | "rem";
+/** Deprivation-driven attribute multipliers (all Q). */
+export interface SleepDeprivationMuls {
+    /** Fluid cognition multiplier: degrades fastest under sleep loss [Q]. */
+    cognitionFluid_Q: Q;
+    /** Reaction time multiplier: > q(1.0) = slower reaction [Q]. */
+    reactionTime_Q: Q;
+    /** Balance / postural stability multiplier [Q]. */
+    stability_Q: Q;
+    /** Distress tolerance multiplier: emotional dysregulation [Q]. */
+    distressTolerance_Q: Q;
+}
+/** Per-entity sleep state stored on `entity.sleep`. */
+export interface SleepState {
+    /** Current sleep phase ("awake" when not sleeping). */
+    phase: SleepPhase;
+    /** Seconds spent in the current phase. */
+    phaseSeconds: number;
+    /** Cumulative sleep deficit in seconds (capped at MAX_SLEEP_DEBT_S). */
+    sleepDebt_s: number;
+    /** Continuous seconds since last sleep bout. Resets to 0 on sleep onset. */
+    awakeSeconds: number;
+}
+/** Optimal sleep duration per 24-hour period [s]. */
+export declare const OPTIMAL_SLEEP_S: number;
+/** Optimal waking duration per 24-hour period [s]. */
+export declare const OPTIMAL_AWAKE_S: number;
+/** Continuous wake time above which cognitive/motor impairment begins [s]. */
+export declare const IMPAIR_THRESHOLD_S: number;
+/** Maximum sleep debt tracked (3 days of total sleep deprivation) [s]. */
+export declare const MAX_SLEEP_DEBT_S: number;
+/** Coefficient for cognition fluid degradation per unit impair fraction [numeric]. */
+export declare const COGNITION_FLUID_COEFF = 0.798;
+/** Coefficient for reaction time slowdown per unit impair fraction [numeric]. */
+export declare const REACTION_TIME_COEFF = 0.45;
+/** Coefficient for stability degradation per unit impair fraction [numeric]. */
+export declare const STABILITY_COEFF = 0.25;
+/** Coefficient for distress tolerance degradation per unit impair fraction [numeric]. */
+export declare const DISTRESS_TOLERANCE_COEFF = 0.35;
+/** Duration of the light-sleep (NREM-1/2) phase per cycle [s]. */
+export declare const LIGHT_PHASE_S: number;
+/** Duration of the deep-sleep (slow-wave) phase per cycle [s]. */
+export declare const DEEP_PHASE_S: number;
+/** Duration of the REM phase per cycle [s]. */
+export declare const REM_PHASE_S: number;
+/**
+ * Circadian alertness at a given time of day.
+ *
+ * @param hourOfDay  Float in [0, 24). Values outside this range are normalised.
+ * @returns Q in [q(0.30), q(1.0)]: q(1.0) at ~17:00, q(0.30) at ~03:00.
+ */
+export declare function circadianAlertness(hourOfDay: number): Q;
+/**
+ * Derive sleep-deprivation attribute multipliers from the entity's sleep state.
+ *
+ * Impairment is driven by the greater of:
+ *   - `awakeSeconds`  — continuous wake duration (resets on sleep)
+ *   - `sleepDebt_s`   — cumulative shortfall from prior nights
+ *
+ * Below IMPAIR_THRESHOLD_S (17 h) both drivers produce no impairment.
+ * Full impairment is reached at MAX_SLEEP_DEBT_S (72 h).
+ *
+ * Multiplier ranges at max deprivation:
+ *   cognitionFluid_Q:    q(1.0) → q(0.202)   (−79.8%)
+ *   reactionTime_Q:      q(1.0) → q(1.45)    (+45% slower)
+ *   stability_Q:         q(1.0) → q(0.75)    (−25%)
+ *   distressTolerance_Q: q(1.0) → q(0.65)    (−35%)
+ */
+export declare function deriveSleepDeprivationMuls(state: SleepState): SleepDeprivationMuls;
+/**
+ * Advance an entity's sleep state by `elapsedSeconds`.
+ *
+ * When `isSleeping = false` (awake):
+ *   - `awakeSeconds` accumulates.
+ *   - `sleepDebt_s` accrues at ½ s/s for each second spent beyond OPTIMAL_AWAKE_S.
+ *     (16 h waking × ½ = 8 h debt — exactly one night's repayment if sleep was ideal.)
+ *   - Phase stays or transitions to "awake".
+ *
+ * When `isSleeping = true`:
+ *   - On sleep onset (phase was "awake"): `awakeSeconds` resets to 0; phase enters "light".
+ *   - `sleepDebt_s` decrements 1:1 with elapsed sleep time (floored at 0).
+ *   - Phase cycles: light → deep → rem → light (90-minute NREM/REM cycle).
+ *
+ * Mutates: `entity.sleep`.
+ */
+export declare function stepSleep(entity: Entity, elapsedSeconds: number, isSleeping: boolean): void;
+/**
+ * Apply sleep-deprivation multipliers to a base attribute set, returning a new object.
+ *
+ * Attributes affected:
+ *   - control.reactionTime_s, stability
+ *   - resilience.distressTolerance
+ *   - cognition (if present): fluid dimensions (logical, spatial, kinesthetic, musical)
+ *
+ * Immutable — does not mutate `base`.
+ * Pattern matches `applyAgingToAttributes` (Phase 57).
+ */
+export declare function applySleepToAttributes(base: IndividualAttributes, state: SleepState): IndividualAttributes;
+/**
+ * Return the entity's accumulated sleep debt in hours.
+ * Returns 0 if `entity.sleep` is absent.
+ */
+export declare function entitySleepDebt_h(entity: Entity): number;

package/dist/src/sim/sleep.js

@@ -0,0 +1,215 @@
+// src/sim/sleep.ts — Phase 58: Sleep & Circadian Rhythm
+//
+// Models circadian alertness, sleep-phase cycling, and attribute degradation from
+// sleep deprivation. Designed as a companion to Phase 57 (Aging & Lifespan):
+// same fixed-point arithmetic, same immutable apply… pattern.
+//
+// Two-factor impairment model:
+//   awakeSeconds — continuous wake duration since last sleep (primary driver)
+//   sleepDebt_s  — cumulative shortfall from prior nights (secondary; persists across sleep)
+//
+// Sleep phase cycle (90 min):  light (45 min) → deep (25 min) → rem (20 min) → light …
+//
+// Public API:
+//   circadianAlertness(hourOfDay)              → Q [0..SCALE.Q]
+//   deriveSleepDeprivationMuls(state)          → SleepDeprivationMuls
+//   stepSleep(entity, elapsedSeconds, sleeping) → mutates entity.sleep
+//   applySleepToAttributes(base, state)        → IndividualAttributes (new object)
+//   entitySleepDebt_h(entity)                  → number
+import { q, clampQ, SCALE } from "../units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Optimal sleep duration per 24-hour period [s]. */
+export const OPTIMAL_SLEEP_S = 8 * 3600; // 28 800
+/** Optimal waking duration per 24-hour period [s]. */
+export const OPTIMAL_AWAKE_S = 16 * 3600; // 57 600
+/** Continuous wake time above which cognitive/motor impairment begins [s]. */
+export const IMPAIR_THRESHOLD_S = 17 * 3600; // 61 200
+/** Maximum sleep debt tracked (3 days of total sleep deprivation) [s]. */
+export const MAX_SLEEP_DEBT_S = 72 * 3600; // 259 200
+/** Coefficient for cognition fluid degradation per unit impair fraction [numeric]. */
+export const COGNITION_FLUID_COEFF = 0.798;
+/** Coefficient for reaction time slowdown per unit impair fraction [numeric]. */
+export const REACTION_TIME_COEFF = 0.45;
+/** Coefficient for stability degradation per unit impair fraction [numeric]. */
+export const STABILITY_COEFF = 0.25;
+/** Coefficient for distress tolerance degradation per unit impair fraction [numeric]. */
+export const DISTRESS_TOLERANCE_COEFF = 0.35;
+/** Duration of the light-sleep (NREM-1/2) phase per cycle [s]. */
+export const LIGHT_PHASE_S = 45 * 60; // 2 700
+/** Duration of the deep-sleep (slow-wave) phase per cycle [s]. */
+export const DEEP_PHASE_S = 25 * 60; // 1 500
+/** Duration of the REM phase per cycle [s]. */
+export const REM_PHASE_S = 20 * 60; // 1 200
+// ── Circadian alertness ───────────────────────────────────────────────────────
+// Piecewise-linear hourly alertness table [hourOfDay → Q].
+// Peaks at ~17:00 (afternoon), nadir at ~03:00 (pre-dawn), secondary dip at 14:00.
+const CIRCADIAN_KNOTS = [
+    [0, q(0.45)],
+    [3, q(0.30)], // nadir ~03:00
+    [6, q(0.60)], // morning rise
+    [10, q(0.95)], // morning peak
+    [14, q(0.80)], // post-lunch dip
+    [17, q(1.00)], // afternoon peak
+    [21, q(0.70)], // evening decline
+    [24, q(0.45)], // back to midnight
+];
+/**
+ * Circadian alertness at a given time of day.
+ *
+ * @param hourOfDay  Float in [0, 24). Values outside this range are normalised.
+ * @returns Q in [q(0.30), q(1.0)]: q(1.0) at ~17:00, q(0.30) at ~03:00.
+ */
+export function circadianAlertness(hourOfDay) {
+    const h = ((hourOfDay % 24) + 24) % 24;
+    for (let i = 1; i < CIRCADIAN_KNOTS.length; i++) {
+        const [x0, y0] = CIRCADIAN_KNOTS[i - 1];
+        const [x1, y1] = CIRCADIAN_KNOTS[i];
+        if (h <= x1) {
+            const span = x1 - x0;
+            if (span === 0)
+                return y0;
+            const t = Math.round((h - x0) * SCALE.Q / span);
+            return (y0 + Math.round((y1 - y0) * t / SCALE.Q));
+        }
+    }
+    return CIRCADIAN_KNOTS[CIRCADIAN_KNOTS.length - 1][1];
+}
+// ── Sleep deprivation ─────────────────────────────────────────────────────────
+/**
+ * Derive sleep-deprivation attribute multipliers from the entity's sleep state.
+ *
+ * Impairment is driven by the greater of:
+ *   - `awakeSeconds`  — continuous wake duration (resets on sleep)
+ *   - `sleepDebt_s`   — cumulative shortfall from prior nights
+ *
+ * Below IMPAIR_THRESHOLD_S (17 h) both drivers produce no impairment.
+ * Full impairment is reached at MAX_SLEEP_DEBT_S (72 h).
+ *
+ * Multiplier ranges at max deprivation:
+ *   cognitionFluid_Q:    q(1.0) → q(0.202)   (−79.8%)
+ *   reactionTime_Q:      q(1.0) → q(1.45)    (+45% slower)
+ *   stability_Q:         q(1.0) → q(0.75)    (−25%)
+ *   distressTolerance_Q: q(1.0) → q(0.65)    (−35%)
+ */
+export function deriveSleepDeprivationMuls(state) {
+    const effectiveS = Math.max(state.awakeSeconds, state.sleepDebt_s);
+    const raw = Math.max(0, effectiveS - IMPAIR_THRESHOLD_S);
+    const range = MAX_SLEEP_DEBT_S - IMPAIR_THRESHOLD_S; // 198 000
+    const impairFrac_Q = clampQ(Math.round(raw * SCALE.Q / range), q(0), SCALE.Q);
+    const cognitionFluid_Q = clampQ((SCALE.Q - Math.round(impairFrac_Q * COGNITION_FLUID_COEFF)), q(0), SCALE.Q);
+    // > SCALE.Q means slower than baseline (mirrors aging reactionTime_Q convention)
+    const reactionTime_Q = (SCALE.Q + Math.round(impairFrac_Q * REACTION_TIME_COEFF));
+    const stability_Q = clampQ((SCALE.Q - Math.round(impairFrac_Q * STABILITY_COEFF)), q(0), SCALE.Q);
+    const distressTolerance_Q = clampQ((SCALE.Q - Math.round(impairFrac_Q * DISTRESS_TOLERANCE_COEFF)), q(0), SCALE.Q);
+    return { cognitionFluid_Q, reactionTime_Q, stability_Q, distressTolerance_Q };
+}
+// ── stepSleep ─────────────────────────────────────────────────────────────────
+/**
+ * Advance an entity's sleep state by `elapsedSeconds`.
+ *
+ * When `isSleeping = false` (awake):
+ *   - `awakeSeconds` accumulates.
+ *   - `sleepDebt_s` accrues at ½ s/s for each second spent beyond OPTIMAL_AWAKE_S.
+ *     (16 h waking × ½ = 8 h debt — exactly one night's repayment if sleep was ideal.)
+ *   - Phase stays or transitions to "awake".
+ *
+ * When `isSleeping = true`:
+ *   - On sleep onset (phase was "awake"): `awakeSeconds` resets to 0; phase enters "light".
+ *   - `sleepDebt_s` decrements 1:1 with elapsed sleep time (floored at 0).
+ *   - Phase cycles: light → deep → rem → light (90-minute NREM/REM cycle).
+ *
+ * Mutates: `entity.sleep`.
+ */
+export function stepSleep(entity, elapsedSeconds, isSleeping) {
+    if (!entity.sleep) {
+        entity.sleep = { phase: "awake", phaseSeconds: 0, sleepDebt_s: 0, awakeSeconds: 0 };
+    }
+    const s = entity.sleep;
+    if (!isSleeping) {
+        if (s.phase !== "awake") {
+            s.phase = "awake";
+            s.phaseSeconds = 0;
+        }
+        const prevAwake = s.awakeSeconds;
+        s.awakeSeconds += elapsedSeconds;
+        s.phaseSeconds += elapsedSeconds;
+        // Debt accrues only for time spent beyond the optimal waking window
+        const debtStart = Math.max(prevAwake, OPTIMAL_AWAKE_S);
+        const debtEnd = s.awakeSeconds;
+        if (debtEnd > debtStart) {
+            s.sleepDebt_s = Math.min(MAX_SLEEP_DEBT_S, s.sleepDebt_s + Math.round((debtEnd - debtStart) / 2));
+        }
+    }
+    else {
+        if (s.phase === "awake") {
+            // Sleep onset: enter light phase and reset continuous wake timer
+            s.phase = "light";
+            s.phaseSeconds = 0;
+            s.awakeSeconds = 0;
+        }
+        // Repay debt 1:1 (cannot go below 0)
+        s.sleepDebt_s = Math.max(0, s.sleepDebt_s - elapsedSeconds);
+        s.phaseSeconds += elapsedSeconds;
+        // Advance through NREM/REM cycle (phase is "light"|"deep"|"rem" at this point)
+        for (;;) {
+            const dur = s.phase === "light" ? LIGHT_PHASE_S
+                : s.phase === "deep" ? DEEP_PHASE_S
+                    : REM_PHASE_S;
+            if (s.phaseSeconds < dur)
+                break;
+            s.phaseSeconds -= dur;
+            s.phase = s.phase === "light" ? "deep"
+                : s.phase === "deep" ? "rem"
+                    : "light"; // rem → back to light
+        }
+    }
+}
+// ── applySleepToAttributes ────────────────────────────────────────────────────
+/**
+ * Apply sleep-deprivation multipliers to a base attribute set, returning a new object.
+ *
+ * Attributes affected:
+ *   - control.reactionTime_s, stability
+ *   - resilience.distressTolerance
+ *   - cognition (if present): fluid dimensions (logical, spatial, kinesthetic, musical)
+ *
+ * Immutable — does not mutate `base`.
+ * Pattern matches `applyAgingToAttributes` (Phase 57).
+ */
+export function applySleepToAttributes(base, state) {
+    const m = deriveSleepDeprivationMuls(state);
+    return {
+        ...base,
+        control: {
+            ...base.control,
+            reactionTime_s: Math.max(1, Math.round(base.control.reactionTime_s * m.reactionTime_Q / SCALE.Q)),
+            stability: clampQ(Math.round(base.control.stability * m.stability_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,
+                    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),
+                },
+            }
+            : {}),
+    };
+}
+// ── Entity convenience ────────────────────────────────────────────────────────
+/**
+ * Return the entity's accumulated sleep debt in hours.
+ * Returns 0 if `entity.sleep` is absent.
+ */
+export function entitySleepDebt_h(entity) {
+    if (!entity.sleep)
+        return 0;
+    return entity.sleep.sleepDebt_s / 3600;
+}

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

@@ -0,0 +1,8 @@
+import type { Vec3 } from "./vec3.js";
+import type { WorldState } from "./world.js";
+export interface SpatialIndex {
+    cell_m: number;
+    cells: Map<number, number[]>;
+}
+export declare function buildSpatialIndex(world: WorldState, cellSize_m: number): SpatialIndex;
+export declare function queryNearbyIds(index: SpatialIndex, pos: Vec3, radius_m: number, maxCount?: number): number[];

package/dist/src/sim/spatial.js

@@ -0,0 +1,59 @@
+function cellCoord(pos_m, cell_m) {
+    // floor division that behaves for negative coordinates too
+    const q = Math.trunc(pos_m / cell_m);
+    return pos_m < 0 && pos_m % cell_m !== 0 ? q - 1 : q;
+}
+function pack(cx, cy) {
+    // deterministic 32-bit packing (cx,cy limited by map bounds in practice)
+    // offset to avoid negative mixing issues
+    const ax = (cx & 0xffff) >>> 0;
+    const ay = (cy & 0xffff) >>> 0;
+    return ((ax << 16) | ay) >>> 0;
+}
+export function buildSpatialIndex(world, cellSize_m) {
+    const cell_m = Math.max(1, Math.trunc(cellSize_m)); // already in fixed-point metres
+    const cells = new Map();
+    for (const e of world.entities) {
+        if (e.injury.dead)
+            continue;
+        const cx = cellCoord(e.position_m.x, cell_m);
+        const cy = cellCoord(e.position_m.y, cell_m);
+        const key = pack(cx, cy);
+        let arr = cells.get(key);
+        if (!arr) {
+            arr = [];
+            cells.set(key, arr);
+        }
+        arr.push(e.id);
+    }
+    // deterministic: sort IDs inside each cell
+    for (const arr of cells.values())
+        arr.sort((a, b) => a - b);
+    return { cell_m, cells };
+}
+export function queryNearbyIds(index, pos, radius_m, maxCount) {
+    const cell_m = index.cell_m;
+    const r = Math.max(0, radius_m);
+    const cx0 = cellCoord(pos.x - r, cell_m);
+    const cx1 = cellCoord(pos.x + r, cell_m);
+    const cy0 = cellCoord(pos.y - r, cell_m);
+    const cy1 = cellCoord(pos.y + r, cell_m);
+    const out = [];
+    for (let cy = cy0; cy <= cy1; cy++) {
+        for (let cx = cx0; cx <= cx1; cx++) {
+            const key = pack(cx, cy);
+            const ids = index.cells.get(key);
+            if (!ids)
+                continue;
+            // already sorted
+            for (const id of ids) {
+                out.push(id);
+                if (maxCount !== undefined && out.length >= maxCount)
+                    break;
+            }
+        }
+    }
+    // deterministic overall order: sort once (cheap; neighbourhood small)
+    out.sort((a, b) => a - b);
+    return out;
+}

package/dist/src/sim/step/capability.d.ts

@@ -0,0 +1,8 @@
+import type { Entity } from "../entity.js";
+import type { WorldState } from "../world.js";
+import type { KernelContext } from "../context.js";
+/**
+ * Per-entity per-tick regen of all capability sources.
+ * Called after stepMovement so velocity is current.
+ */
+export declare function stepCapabilitySources(e: Entity, world: WorldState, ctx: KernelContext): void;