@its-not-rocket-science/ananke 0.1.0

package/dist/src/sim/systemic-toxicology.d.ts

@@ -0,0 +1,109 @@
+import { type Q } from "../units.js";
+import type { Entity } from "./entity.js";
+export type ToxinCategory = "alcohol" | "sedative" | "alkaloid" | "heavy_metal" | "radiation";
+export interface IngestedToxinProfile {
+    id: string;
+    name: string;
+    category: ToxinCategory;
+    /** Seconds from ingestion to first symptomatic effect. */
+    onsetDelay_s: number;
+    /**
+     * Metabolic half-life [seconds].
+     * Per-second decay fraction ≈ ln(2) / halfLife_s.
+     * Effective decayQ = max(1, round(6931 / halfLife_s)) [Q units/s from SCALE.Q].
+     */
+    halfLife_s: number;
+    /** Per-second internal damage to torso (Q) while symptomatic. */
+    damageRate_Q?: Q;
+    /**
+     * Motor impairment at full concentration.
+     * Applied as per-second fatigue increase proportional to (SCALE.Q − motorMul_Q) × concentration.
+     * q(0.60) → 40% impairment; q(1.0) → no impairment.
+     */
+    motorMul_Q?: Q;
+    /**
+     * Cognitive impairment at full concentration.
+     * Applied as per-second consciousness erosion.
+     * q(0.50) → severe impairment; q(1.0) → no impairment.
+     */
+    cognitiveMul_Q?: Q;
+    /**
+     * Signed per-second fear delta [Q units] while symptomatic.
+     * Positive → fear increase (alkaloid panic); negative → fear decrease (alcohol disinhibition).
+     */
+    fearMod_perS?: number;
+    /** True = this toxin accumulates irreversibly in tissue (heavy metals, radiation). */
+    cumulative?: boolean;
+    /**
+     * Per-second irreversible dose accumulation while symptomatic [Q/s].
+     * Adds to CumulativeExposureRecord.totalDose_Q at rate: conc_Q × irreversibleRate_Q / SCALE.Q / s.
+     */
+    irreversibleRate_Q?: Q;
+    /** True = sustained use triggers a withdrawal state when concentration clears. */
+    addictive?: boolean;
+    /** Duration of withdrawal period [seconds] (default: halfLife_s × 2). */
+    withdrawalDuration_s?: number;
+}
+export interface ActiveIngestedToxin {
+    profile: IngestedToxinProfile;
+    /** Total seconds elapsed since ingestion. */
+    elapsedSeconds: number;
+    /**
+     * Current systemic concentration (Q 0..SCALE.Q).
+     * Initialized to SCALE.Q on ingestion; decays exponentially via halfLife_s.
+     */
+    concentration_Q: Q;
+    /**
+     * Seconds spent in the symptomatic phase (elapsed ≥ onsetDelay_s).
+     * Drives withdrawal eligibility for addictive toxins.
+     */
+    sustainedSeconds: number;
+}
+/** Irreversible lifetime dose accumulation for heavy metals and radiation. */
+export interface CumulativeExposureRecord {
+    toxinId: string;
+    /** Accumulated irreversible dose (Q 0..SCALE.Q). Increases with each symptomatic exposure. */
+    totalDose_Q: Q;
+}
+/** Active withdrawal state — temporary penalty period after an addictive toxin clears. */
+export interface WithdrawalState {
+    toxinId: string;
+    elapsedSeconds: number;
+    duration_s: number;
+    /** Q 0..SCALE.Q — scales all withdrawal symptom magnitudes. Higher = worse symptoms. */
+    severity_Q: Q;
+}
+export declare const INGESTED_TOXIN_PROFILES: readonly IngestedToxinProfile[];
+/** Look up an IngestedToxinProfile by id. Returns undefined if unknown. */
+export declare function getIngestedToxinProfile(id: string): IngestedToxinProfile | undefined;
+/**
+ * Add an ingested toxin to an entity.
+ *
+ * Initializes concentration at SCALE.Q (full dose). Multiple ingestions of the same
+ * toxin create separate entries — this models repeated ingestion (two cups of alcohol, etc.).
+ *
+ * @returns true if the toxin id is known; false otherwise.
+ */
+export declare function ingestToxin(entity: Entity, toxinId: string): boolean;
+/**
+ * Advance all active ingested toxins on an entity by `delta_s` seconds.
+ *
+ * Mutates:
+ *   entity.activeIngestedToxins (concentration decayed; expired entries removed)
+ *   entity.cumulativeExposure   (irreversible dose records updated for cumulative toxins)
+ *   entity.withdrawal           (new withdrawal states added; existing states advanced and expired)
+ *   entity.energy.fatigue       (motor-impairing toxins and withdrawal)
+ *   entity.injury.consciousness (cognitive-impairing toxins)
+ *   entity.injury (torso internalDamage or shock for toxins with damageRate_Q)
+ *   entity.condition.fearQ      (fearMod_perS and withdrawal)
+ */
+export declare function stepIngestedToxicology(entity: Entity, delta_s: number): void;
+/**
+ * Cumulative toxicity score (Q 0..SCALE.Q) from all irreversible dose records.
+ *
+ * Sums totalDose_Q across all CumulativeExposureRecord entries and clamps to SCALE.Q.
+ * Returns q(0) if no records exist.
+ *
+ * Usage: AI layer reads this to modulate attribute checks for chronically poisoned entities.
+ */
+export declare function deriveCumulativeToxicity(entity: Entity): Q;

package/dist/src/sim/systemic-toxicology.js

@@ -0,0 +1,263 @@
+// src/sim/systemic-toxicology.ts — Phase 53: Systemic Toxicology (Ingested / Cumulative)
+//
+// Extends Phase 32C (injection venom) and Phase 10 (pharmacokinetics) with:
+//   - Ingested toxins with long onset times (minutes) and metabolic half-lives (hours)
+//   - Cumulative exposure: heavy metals, radiation — irreversible dose accumulation
+//   - Withdrawal states after sustained addictive toxin use
+//
+// Follows the 1 Hz accumulator pattern; called from the kernel's __nutritionAccum gate.
+//
+// Data flow:
+//   ingestToxin(entity, id) → entity.activeIngestedToxins[]
+//   stepIngestedToxicology(entity, delta_s) → mutates condition/injury/energy; manages withdrawal
+//   deriveCumulativeToxicity(entity) → Q summary for AI / combat layer queries
+import { q, clampQ, SCALE } from "../units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** round(ln(2) × SCALE.Q) — numerator for per-second decay fraction. */
+const LN2_Q = 6931;
+/** Minimum sustained seconds before withdrawal becomes possible. */
+const WITHDRAWAL_MIN_SUSTAINED_s = 120;
+/**
+ * Fatigue increase per unit of motor impairment × concentration per second.
+ * Formula: fatigueInc = (SCALE.Q − motorMul_Q) × conc_Q / SCALE.Q × MOTOR_IMPAIRMENT_RATE / SCALE.Q
+ * At full impairment (motorMul = q(0)) and full conc (q(1.0)): adds MOTOR_IMPAIRMENT_RATE Q/s.
+ */
+const MOTOR_IMPAIRMENT_RATE = 50; // q(0.005)/s at maximum motor impairment + full concentration
+/** Consciousness erosion per unit of cognitive impairment × concentration per second. */
+const COGNITIVE_IMPAIRMENT_RATE = 30; // q(0.003)/s at maximum impairment + full concentration
+/** Fatigue added per Q of withdrawal severity per second. */
+const WITHDRAWAL_FATIGUE_RATE = 8; // q(0.0008)/s at severity q(1.0)
+/** Fear added per Q of withdrawal severity per second. */
+const WITHDRAWAL_FEAR_RATE = 5; // q(0.0005)/s at severity q(1.0)
+// ── Toxin catalogue ───────────────────────────────────────────────────────────
+export const INGESTED_TOXIN_PROFILES = [
+    {
+        id: "alcohol",
+        name: "Alcohol (ethanol)",
+        category: "alcohol",
+        onsetDelay_s: 900, // 15 min to first motor effect
+        halfLife_s: 3_600, // 1 h hepatic clearance (decayQ ≈ 2/s)
+        motorMul_Q: q(0.60), // 40% motor impairment at peak
+        fearMod_perS: -3, // slight disinhibition: −3 Q/s (≈ −q(0.0003)/s)
+        addictive: true,
+        withdrawalDuration_s: 7_200, // 2 h withdrawal
+    },
+    {
+        id: "sedative_plant",
+        name: "Sedative alkaloid (valerian, poppy)",
+        category: "sedative",
+        onsetDelay_s: 1_800, // 30 min
+        halfLife_s: 7_200, // 2 h clearance (decayQ ≈ 1/s)
+        cognitiveMul_Q: q(0.50), // severe consciousness erosion
+        addictive: true,
+        withdrawalDuration_s: 14_400, // 4 h withdrawal
+    },
+    {
+        id: "alkaloid_poison",
+        name: "Plant alkaloid toxin (nightshade, hemlock)",
+        category: "alkaloid",
+        onsetDelay_s: 1_200, // 20 min
+        halfLife_s: 1_800, // 30 min — clears relatively quickly
+        damageRate_Q: q(0.004), // internal damage per second
+        fearMod_perS: 8, // panic response: +8 Q/s (≈ +q(0.0008)/s)
+    },
+    {
+        id: "heavy_lead",
+        name: "Lead (plumbum) — chronic poisoning",
+        category: "heavy_metal",
+        onsetDelay_s: 3_600, // 1 h onset (slow GI absorption)
+        halfLife_s: 86_400, // nominal 24 h (fixed-point effective: decayQ = max(1, round(0.08)) = 1)
+        cognitiveMul_Q: q(0.70), // neurological impairment
+        damageRate_Q: q(0.001), // slow systemic damage
+        cumulative: true,
+        irreversibleRate_Q: q(0.005), // 50 Q/s accumulation at full concentration
+    },
+    {
+        id: "radiation_dose",
+        name: "Ionising radiation dose (acute)",
+        category: "radiation",
+        onsetDelay_s: 7_200, // 2 h (ARS latent period before symptoms manifest)
+        halfLife_s: 604_800, // nominal 7 days (effective decayQ = 1)
+        damageRate_Q: q(0.002),
+        motorMul_Q: q(0.80), // bone marrow suppression → fatigue
+        cumulative: true,
+        irreversibleRate_Q: q(0.001), // 10 Q/s — DNA damage accumulates slower than lead
+    },
+];
+const TOXIN_BY_ID = new Map(INGESTED_TOXIN_PROFILES.map(t => [t.id, t]));
+/** Look up an IngestedToxinProfile by id. Returns undefined if unknown. */
+export function getIngestedToxinProfile(id) {
+    return TOXIN_BY_ID.get(id);
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Add an ingested toxin to an entity.
+ *
+ * Initializes concentration at SCALE.Q (full dose). Multiple ingestions of the same
+ * toxin create separate entries — this models repeated ingestion (two cups of alcohol, etc.).
+ *
+ * @returns true if the toxin id is known; false otherwise.
+ */
+export function ingestToxin(entity, toxinId) {
+    const profile = TOXIN_BY_ID.get(toxinId);
+    if (!profile)
+        return false;
+    if (!entity.activeIngestedToxins)
+        entity.activeIngestedToxins = [];
+    entity.activeIngestedToxins.push({
+        profile,
+        elapsedSeconds: 0,
+        concentration_Q: SCALE.Q,
+        sustainedSeconds: 0,
+    });
+    return true;
+}
+/**
+ * Advance all active ingested toxins on an entity by `delta_s` seconds.
+ *
+ * Mutates:
+ *   entity.activeIngestedToxins (concentration decayed; expired entries removed)
+ *   entity.cumulativeExposure   (irreversible dose records updated for cumulative toxins)
+ *   entity.withdrawal           (new withdrawal states added; existing states advanced and expired)
+ *   entity.energy.fatigue       (motor-impairing toxins and withdrawal)
+ *   entity.injury.consciousness (cognitive-impairing toxins)
+ *   entity.injury (torso internalDamage or shock for toxins with damageRate_Q)
+ *   entity.condition.fearQ      (fearMod_perS and withdrawal)
+ */
+export function stepIngestedToxicology(entity, delta_s) {
+    const delta_int = Math.round(delta_s); // integer seconds for accumulation arithmetic
+    _stepActiveToxins(entity, delta_s, delta_int);
+    _stepWithdrawal(entity, delta_int);
+}
+function _stepActiveToxins(entity, delta_s, delta_int) {
+    const toxins = entity.activeIngestedToxins;
+    if (!toxins || toxins.length === 0)
+        return;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const cond = entity.condition;
+    const torsoRegion = entity.injury.byRegion?.["torso"];
+    const toRemove = [];
+    for (let i = 0; i < toxins.length; i++) {
+        const at = toxins[i];
+        at.elapsedSeconds += delta_s;
+        // Decay concentration: decayQ = max(1, round(ln(2) × SCALE.Q / halfLife_s))
+        // Minimum decrement of 1 per delta_int seconds ensures toxin always eventually clears.
+        // (Without this, integer truncation freezes decay for very small concentrations.)
+        const decayQ = Math.max(1, Math.round(LN2_Q / at.profile.halfLife_s));
+        const rawDecrement = Math.trunc(at.concentration_Q * decayQ / SCALE.Q);
+        const decrement = at.concentration_Q > 0 ? Math.max(delta_int, rawDecrement * delta_int) : 0;
+        at.concentration_Q = clampQ((at.concentration_Q - decrement), q(0), SCALE.Q);
+        if (at.elapsedSeconds < at.profile.onsetDelay_s)
+            continue; // pre-onset: no effect yet
+        // Symptomatic — apply effects
+        at.sustainedSeconds += delta_s;
+        const conc = at.concentration_Q;
+        const p = at.profile;
+        // Internal damage (alkaloids, heavy metals, radiation)
+        if (p.damageRate_Q) {
+            const dmgInc = Math.trunc(p.damageRate_Q * delta_int);
+            if (torsoRegion !== undefined) {
+                torsoRegion.internalDamage = clampQ((torsoRegion.internalDamage + dmgInc), q(0), q(1.0));
+            }
+            else {
+                entity.injury.shock = clampQ((entity.injury.shock + dmgInc), q(0), SCALE.Q);
+            }
+        }
+        // Motor impairment → fatigue accumulation
+        if (p.motorMul_Q !== undefined) {
+            const impairFrac = Math.trunc((SCALE.Q - p.motorMul_Q) * conc / SCALE.Q);
+            const fatigueInc = Math.trunc(impairFrac * MOTOR_IMPAIRMENT_RATE / SCALE.Q) * delta_int;
+            entity.energy.fatigue = clampQ((entity.energy.fatigue + fatigueInc), q(0), SCALE.Q);
+        }
+        // Cognitive impairment → consciousness erosion
+        if (p.cognitiveMul_Q !== undefined) {
+            const impairFrac = Math.trunc((SCALE.Q - p.cognitiveMul_Q) * conc / SCALE.Q);
+            const consciousLoss = Math.trunc(impairFrac * COGNITIVE_IMPAIRMENT_RATE / SCALE.Q) * delta_int;
+            entity.injury.consciousness = clampQ((entity.injury.consciousness - consciousLoss), q(0), SCALE.Q);
+        }
+        // Fear modifier (signed: negative for disinhibition, positive for panic)
+        if (p.fearMod_perS !== undefined && p.fearMod_perS !== 0) {
+            const fearDelta = Math.trunc(p.fearMod_perS * delta_int);
+            cond.fearQ = clampQ((cond.fearQ + fearDelta), q(0), SCALE.Q);
+        }
+        // Cumulative irreversible dose accumulation
+        if (p.cumulative && p.irreversibleRate_Q) {
+            const irrInc = Math.trunc(conc * p.irreversibleRate_Q / SCALE.Q) * delta_int;
+            if (irrInc > 0) {
+                _accumulateDose(entity, p.id, irrInc);
+            }
+        }
+        // Schedule for removal if concentration is negligible
+        if (at.concentration_Q < 1) {
+            // Trigger withdrawal if applicable
+            if (p.addictive && at.sustainedSeconds >= WITHDRAWAL_MIN_SUSTAINED_s) {
+                _triggerWithdrawal(entity, p, at.sustainedSeconds);
+            }
+            toRemove.push(i);
+        }
+    }
+    // Remove expired entries in reverse order to preserve indices
+    for (let k = toRemove.length - 1; k >= 0; k--) {
+        toxins.splice(toRemove[k], 1);
+    }
+}
+function _accumulateDose(entity, toxinId, amount) {
+    if (!entity.cumulativeExposure)
+        entity.cumulativeExposure = [];
+    let rec = entity.cumulativeExposure.find(r => r.toxinId === toxinId);
+    if (!rec) {
+        rec = { toxinId, totalDose_Q: q(0) };
+        entity.cumulativeExposure.push(rec);
+    }
+    rec.totalDose_Q = clampQ((rec.totalDose_Q + amount), q(0), SCALE.Q);
+}
+function _triggerWithdrawal(entity, profile, sustainedSeconds) {
+    const duration_s = profile.withdrawalDuration_s ?? profile.halfLife_s * 2;
+    // Severity: capped to SCALE.Q; scales with how long entity was symptomatic
+    const severity_Q = clampQ(Math.trunc(sustainedSeconds * SCALE.Q / duration_s), q(0.10), // minimum severity when withdrawal triggers
+    SCALE.Q);
+    if (!entity.withdrawal)
+        entity.withdrawal = [];
+    entity.withdrawal.push({
+        toxinId: profile.id,
+        elapsedSeconds: 0,
+        duration_s,
+        severity_Q,
+    });
+}
+function _stepWithdrawal(entity, delta_int) {
+    const states = entity.withdrawal;
+    if (!states || states.length === 0)
+        return;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const cond = entity.condition;
+    for (const ws of states) {
+        ws.elapsedSeconds += delta_int;
+        // Apply withdrawal symptoms scaled by severity
+        const fatiguePenalty = Math.trunc(ws.severity_Q * WITHDRAWAL_FATIGUE_RATE / SCALE.Q) * delta_int;
+        entity.energy.fatigue = clampQ((entity.energy.fatigue + fatiguePenalty), q(0), SCALE.Q);
+        const fearPenalty = Math.trunc(ws.severity_Q * WITHDRAWAL_FEAR_RATE / SCALE.Q) * delta_int;
+        cond.fearQ = clampQ((cond.fearQ + fearPenalty), q(0), SCALE.Q);
+    }
+    // Remove expired withdrawal states
+    entity.withdrawal = states.filter(ws => ws.elapsedSeconds < ws.duration_s);
+}
+// ── Query functions ───────────────────────────────────────────────────────────
+/**
+ * Cumulative toxicity score (Q 0..SCALE.Q) from all irreversible dose records.
+ *
+ * Sums totalDose_Q across all CumulativeExposureRecord entries and clamps to SCALE.Q.
+ * Returns q(0) if no records exist.
+ *
+ * Usage: AI layer reads this to modulate attribute checks for chronically poisoned entities.
+ */
+export function deriveCumulativeToxicity(entity) {
+    if (!entity.cumulativeExposure || entity.cumulativeExposure.length === 0) {
+        return q(0);
+    }
+    let total = 0;
+    for (const rec of entity.cumulativeExposure) {
+        total += rec.totalDose_Q;
+    }
+    return clampQ(total, q(0), SCALE.Q);
+}

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

@@ -0,0 +1,9 @@
+import type { Entity } from "./entity.js";
+import type { WorldState } from "./world.js";
+export declare function isEnemy(a: Entity, b: Entity): boolean;
+/**
+ * Phase 48: Determine if two entities are hostile, considering team, party, and faction relationships.
+ * Returns true if they should treat each other as enemies.
+ * Self-defence override: injured entities (shock > 0 or fluidLoss > 0) ignore friendly faction/party thresholds.
+ */
+export declare function areEntitiesHostile(a: Entity, b: Entity, world: WorldState): boolean;

package/dist/src/sim/team.js

@@ -0,0 +1,37 @@
+import { effectiveStanding, STANDING_HOSTILE_THRESHOLD, STANDING_FRIENDLY_THRESHOLD } from "../faction.js";
+import { areEntitiesHostileByParty, areEntitiesFriendlyByParty } from "../party.js";
+export function isEnemy(a, b) {
+    return a.teamId !== b.teamId;
+}
+/**
+ * Phase 48: Determine if two entities are hostile, considering team, party, and faction relationships.
+ * Returns true if they should treat each other as enemies.
+ * Self-defence override: injured entities (shock > 0 or fluidLoss > 0) ignore friendly faction/party thresholds.
+ */
+export function areEntitiesHostile(a, b, world) {
+    // same team → never hostile
+    if (a.teamId === b.teamId)
+        return false;
+    const isInjured = a.injury.shock > 0 || a.injury.fluidLoss > 0;
+    // party check
+    const partyRegistry = world.__partyRegistry;
+    if (partyRegistry) {
+        // if parties are friendly, not hostile (unless injured)
+        if (!isInjured && areEntitiesFriendlyByParty(partyRegistry, a, b))
+            return false;
+        // if parties are hostile, hostile
+        if (areEntitiesHostileByParty(partyRegistry, a, b))
+            return true;
+    }
+    // faction check
+    const factionRegistry = world.__factionRegistry;
+    if (factionRegistry && a.faction && b.faction) {
+        const standing = effectiveStanding(factionRegistry, a, b);
+        if (!isInjured && standing >= STANDING_FRIENDLY_THRESHOLD)
+            return false;
+        if (standing < STANDING_HOSTILE_THRESHOLD)
+            return true;
+    }
+    // default: different team → hostile
+    return true;
+}

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

@@ -0,0 +1,36 @@
+/**
+ * Phase 11 — Technology Spectrum
+ *
+ * TechContext gates which items and capabilities are available in a given scenario.
+ * Items declare their requirements via `requiredCapabilities`; validateLoadout()
+ * checks them against the active TechContext.
+ *
+ * Design: era provides a sensible default capability set, but any capability
+ * can be added or removed for bespoke scenarios (time-travel, magitech, etc.).
+ */
+/** Numeric era codes; higher = more advanced. */
+export declare const TechEra: {
+    readonly Prehistoric: 0;
+    readonly Ancient: 1;
+    readonly Medieval: 2;
+    readonly EarlyModern: 3;
+    readonly Industrial: 4;
+    readonly Modern: 5;
+    readonly NearFuture: 6;
+    readonly FarFuture: 7;
+    readonly DeepSpace: 8;
+};
+export type TechEra = typeof TechEra[keyof typeof TechEra];
+/**
+ * Discrete capabilities that items may require.
+ * A scenario can have any combination regardless of era.
+ */
+export type TechCapability = "MetallicArmour" | "FirearmsPropellant" | "ExplosiveMunitions" | "BallisticArmour" | "PoweredExoskeleton" | "EnergyWeapons" | "ReactivePlating" | "NanomedicalRepair" | "ArcaneMagic" | "DivineMagic" | "Psionics" | "Nanotech";
+export interface TechContext {
+    era: TechEra;
+    available: Set<TechCapability>;
+}
+/** Build a TechContext from a named era with its default capability set. */
+export declare function defaultTechContext(era: TechEra): TechContext;
+/** Return true if the given capability is available in this context. */
+export declare function isCapabilityAvailable(ctx: TechContext, cap: TechCapability): boolean;

package/dist/src/sim/tech.js

@@ -0,0 +1,46 @@
+/**
+ * Phase 11 — Technology Spectrum
+ *
+ * TechContext gates which items and capabilities are available in a given scenario.
+ * Items declare their requirements via `requiredCapabilities`; validateLoadout()
+ * checks them against the active TechContext.
+ *
+ * Design: era provides a sensible default capability set, but any capability
+ * can be added or removed for bespoke scenarios (time-travel, magitech, etc.).
+ */
+/** Numeric era codes; higher = more advanced. */
+export const TechEra = {
+    Prehistoric: 0,
+    Ancient: 1,
+    Medieval: 2,
+    EarlyModern: 3,
+    Industrial: 4,
+    Modern: 5,
+    NearFuture: 6,
+    FarFuture: 7,
+    DeepSpace: 8,
+};
+/**
+ * Default capability sets for each era.
+ * Capabilities are cumulative: each era includes all capabilities of previous eras.
+ */
+const ERA_DEFAULTS = [
+    /* Prehistoric */ [],
+    /* Ancient     */ ["MetallicArmour"],
+    /* Medieval    */ ["MetallicArmour"],
+    /* EarlyModern */ ["MetallicArmour", "FirearmsPropellant"],
+    /* Industrial  */ ["MetallicArmour", "FirearmsPropellant", "ExplosiveMunitions"],
+    /* Modern      */ ["MetallicArmour", "FirearmsPropellant", "ExplosiveMunitions", "BallisticArmour"],
+    /* NearFuture  */ ["MetallicArmour", "FirearmsPropellant", "ExplosiveMunitions", "BallisticArmour", "PoweredExoskeleton"],
+    /* FarFuture   */ ["MetallicArmour", "FirearmsPropellant", "ExplosiveMunitions", "BallisticArmour", "PoweredExoskeleton", "EnergyWeapons", "ReactivePlating"],
+    /* DeepSpace   */ ["MetallicArmour", "FirearmsPropellant", "ExplosiveMunitions", "BallisticArmour", "PoweredExoskeleton", "EnergyWeapons", "ReactivePlating", "NanomedicalRepair"],
+];
+/** Build a TechContext from a named era with its default capability set. */
+export function defaultTechContext(era) {
+    const caps = ERA_DEFAULTS[era] ?? [];
+    return { era, available: new Set(caps) };
+}
+/** Return true if the given capability is available in this context. */
+export function isCapabilityAvailable(ctx, cap) {
+    return ctx.available.has(cap);
+}

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

@@ -0,0 +1,121 @@
+import { type Q, type I32 } from "../units.js";
+/**
+ * Physical surface classification. Determines traction available to entities.
+ */
+export type SurfaceType = "normal" | "mud" | "ice" | "slope_up" | "slope_down";
+/**
+ * Traction coefficient (Q) per surface type.
+ *
+ * Normal ground ≈ 0.80 (existing KernelContext default).
+ * Mud roughly halves usable force; ice allows only ~0.25×.
+ */
+export declare const SURFACE_TRACTION: Record<SurfaceType, Q>;
+/**
+ * Terrain speed multiplier (Q) per surface type.
+ *
+ * Applied directly to maxSprintSpeed to capture effects that traction alone
+ * does not model (viscous drag in mud, slip uncertainty on ice, grade resistance).
+ *
+ * Normal = q(1.0) (no penalty).
+ */
+export declare const SURFACE_SPEED_MUL: Record<SurfaceType, Q>;
+/**
+ * Sparse terrain grid. Keys are cell-index strings "cx,cy".
+ * Cells absent from the map use whatever default the caller provides (usually "normal").
+ */
+export type TerrainGrid = Map<string, SurfaceType>;
+/**
+ * Encode integer cell coordinates as a lookup key.
+ */
+export declare function terrainKey(cellX: number, cellY: number): string;
+/**
+ * Decode a terrain key back into cell coordinates.
+ */
+export declare function parseTerrainKey(key: string): {
+    cellX: number;
+    cellY: number;
+};
+/**
+ * Look up the traction coefficient at a given world position.
+ *
+ * @param grid        Terrain grid (may be undefined or empty)
+ * @param cellSize_m  Cell size in SCALE.m units (e.g. 4*SCALE.m for 4 m cells)
+ * @param pos_x       Entity x position in SCALE.m units
+ * @param pos_y       Entity y position in SCALE.m units
+ * @param defaultTraction  Fallback traction when no grid cell is found
+ * @returns Traction coefficient Q
+ */
+export declare function tractionAtPosition(grid: TerrainGrid | undefined, cellSize_m: I32, pos_x: I32, pos_y: I32, defaultTraction: Q): Q;
+/**
+ * Look up the speed multiplier at a given world position.
+ *
+ * Returns q(1.0) when the position has no terrain entry (no penalty).
+ */
+export declare function speedMulAtPosition(grid: TerrainGrid | undefined, cellSize_m: I32, pos_x: I32, pos_y: I32): Q;
+/**
+ * Convenience: build a TerrainGrid from a flat record of "cx,cy" → SurfaceType.
+ */
+export declare function buildTerrainGrid(cells: Record<string, SurfaceType>): TerrainGrid;
+/**
+ * Sparse obstacle / cover grid.  Q value = cover fraction (0 = no cover, q(1.0) = impassable).
+ * Partial cover (e.g. q(0.50)) halves the effective target body-width used in hit determination,
+ * making the target harder to shoot.  Full hard cover (q(1.0)) blocks movement and direct fire.
+ */
+export type ObstacleGrid = Map<string, Q>;
+/**
+ * Look up cover fraction at a world position.
+ * Returns 0 (no cover) if the grid is absent or the cell has no entry.
+ */
+export declare function coverFractionAtPosition(grid: ObstacleGrid | undefined, cellSize_m: I32, pos_x: I32, pos_y: I32): Q;
+/**
+ * Convenience: build an ObstacleGrid from a record of "cx,cy" → cover fraction Q.
+ * Use q(1.0) for impassable walls; fractional values for partial cover.
+ */
+export declare function buildObstacleGrid(cells: Record<string, Q>): ObstacleGrid;
+/**
+ * Sparse elevation grid.  Values are heights in SCALE.m units above the ground plane
+ * (e.g. `to.m(2)` = 2 m high ground).  Height differentials are added to the vertical
+ * separation when computing 3D reach (melee) and projectile range (ranged).
+ */
+export type ElevationGrid = Map<string, I32>;
+/**
+ * Look up elevation (height in SCALE.m units) at a world position.
+ * Returns 0 (ground level) if the grid is absent or the cell has no entry.
+ */
+export declare function elevationAtPosition(grid: ElevationGrid | undefined, cellSize_m: I32, pos_x: I32, pos_y: I32): I32;
+/**
+ * Convenience: build an ElevationGrid from a record of "cx,cy" → height (SCALE.m units).
+ */
+export declare function buildElevationGrid(cells: Record<string, I32>): ElevationGrid;
+/**
+ * Slope descriptor per cell.
+ * `grade` is a Q fraction where q(0) = flat and q(1.0) = maximum steepness.
+ */
+export interface SlopeInfo {
+    type: "uphill" | "downhill";
+    grade: Q;
+}
+/** Sparse slope grid.  Keys are "cx,cy" cell-index strings. */
+export type SlopeGrid = Map<string, SlopeInfo>;
+/**
+ * Look up slope info at a world position.
+ * Returns undefined if the grid is absent or the cell has no entry.
+ */
+export declare function slopeAtPosition(grid: SlopeGrid | undefined, cellSize_m: I32, pos_x: I32, pos_y: I32): SlopeInfo | undefined;
+/** Convenience: build a SlopeGrid from a record of "cx,cy" → SlopeInfo. */
+export declare function buildSlopeGrid(cells: Record<string, SlopeInfo>): SlopeGrid;
+/**
+ * Dynamic hazard cell.
+ * `intensity` ∈ [0, q(1.0)] scales per-tick damage.
+ * `duration_ticks`: 0 = permanent; >0 is decremented each tick and the cell is
+ * removed when it reaches 0.
+ */
+export interface HazardCell {
+    type: "fire" | "radiation" | "poison_gas";
+    intensity: Q;
+    duration_ticks: number;
+}
+/** Sparse hazard grid.  Keys are "cx,cy" cell-index strings. */
+export type HazardGrid = Map<string, HazardCell>;
+/** Convenience: build a HazardGrid from a record of "cx,cy" → HazardCell. */
+export declare function buildHazardGrid(cells: Record<string, HazardCell>): HazardGrid;