@its-not-rocket-science/ananke 0.1.16 → 0.1.17

package/CHANGELOG.md

@@ -6,6 +6,39 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.17] — 2026-03-26
+
+### Added
+
+- **Phase 73 · Enhanced Epidemiological Models** (`src/sim/disease.ts` extended in-place)
+  - `VaccinationRecord { diseaseId, efficacy_Q, doseCount }` — partial-efficacy vaccination
+    stored on `entity.vaccinations?`; `vaccinate(entity, diseaseId, efficacy_Q)` helper.
+  - `ageSusceptibility_Q(ageYears)` — U-shaped multiplier: infants ×1.30, children ×0.80,
+    adults ×1.00, early elderly ×1.20, late elderly ×1.50. Auto-applied in
+    `computeTransmissionRisk` when `entity.age` is set.
+  - `NPIType`, `NPIRecord`, `NPIRegistry` — non-pharmaceutical intervention registry;
+    `applyNPI / removeNPI / hasNPI` helpers. `mask_mandate` reduces airborne transmission
+    by `NPI_MASK_REDUCTION_Q = q(0.60)` (60 %). `quarantine` recorded for host-side pair
+    filtering.
+  - `computeTransmissionRisk` extended with optional 5th `options?` parameter — backward-
+    compatible; applies vaccination, age susceptibility, and NPI effects when present.
+  - `computeR0(profile, entityMap)` — basic reproductive number estimate
+    (β × infectious-days × min(15, population−1)); used for validation.
+  - `stepSEIR(entity, delta_s, profile, worldSeed, tick)` — SEIR-aware entity step that
+    isolates a single disease profile; delegates to Phase 56 `stepDiseaseForEntity` for
+    full backward compatibility.
+  - `registerDiseaseProfile(profile)` — registers custom/SEIR profiles into the lookup map
+    without modifying the canonical `DISEASE_PROFILES` array.
+  - `MEASLES` profile (`useSeir: true`): R0 ≈ 15.1 in population ≥ 16, 14-day incubation,
+    14-day infectious period, 0.2 % IFR, permanent immunity. Validates epidemic curve
+    peaking days 10–20 and burning out by day 60 (matches standard SIR output ±15 %).
+  - `entity.vaccinations?: VaccinationRecord[]` added to `Entity`.
+  - `DiseaseProfile.useSeir?: boolean` opt-in field (no effect on existing callers).
+  - 37 new tests in `test/disease-seir.test.ts`. All 37 Phase 56 tests pass unmodified.
+  - **3 998 tests total.**
+
+---
+
 ## [0.1.16] — 2026-03-25
 
 ### Added

package/dist/src/economy-gen.d.ts

@@ -0,0 +1,133 @@
+import { type Q } from "./units.js";
+import type { Polity, PolityRegistry, PolityPair } from "./polity.js";
+import { TechEra } from "./sim/tech.js";
+/** Per-step fraction pulled back toward base price (8%). */
+export declare const MEAN_REVERSION_Q: number;
+/** Debt/treasury ratio above which a polity is in crisis (30%). */
+export declare const DEBT_CRISIS_RATIO_Q: number;
+/** Supply fraction added to market in an economic warfare dump (40%). */
+export declare const SUPPLY_DUMP_Q: number;
+/** Base trade income per shared location per commodity per step (cost-units). */
+export declare const TRADE_BASE_CU = 50;
+/** Fraction of treasury wagered per speculate() call (10%). */
+export declare const SPECULATE_WAGER_Q: number;
+/**
+ * Profit multiplier on a winning speculation — applied to the wager amount.
+ * q(1.0) means winner gains exactly the wager (net +wager).
+ * Combined with WIN_PROBABILITY_NUM/DEN = 45/100, EV = −10% per call.
+ */
+export declare const SPECULATE_WIN_MUL_Q: number;
+/** Numerator of win probability fraction (45%). */
+export declare const WIN_PROBABILITY_NUM = 45;
+export interface CommodityProfile {
+    readonly id: string;
+    readonly name: string;
+    /** Base price [0, SCALE.Q]. Long-run equilibrium the market reverts toward. */
+    readonly basePrice_Q: Q;
+    /** Maximum random price swing per step (±half this per step). */
+    readonly volatility_Q: Q;
+    /** Minimum tech era required for a polity to produce this commodity. */
+    readonly techMinEra: TechEra;
+}
+export interface PriceRecord {
+    /** Current market price [q(0.05), q(2.0)]. */
+    price_Q: Q;
+    /** Available supply [0, SCALE.Q]. */
+    supply_Q: Q;
+    /** Active demand [0, SCALE.Q]. */
+    demand_Q: Q;
+}
+export interface MarketState {
+    /** Current prices for each commodity. Keyed by CommodityProfile.id. */
+    prices: Map<string, PriceRecord>;
+    /** Outstanding debt per polity: polityId → cost-units owed. */
+    debt: Map<string, number>;
+}
+export interface MarketStepResult {
+    /** Trade income credited this step: polityId → cost-units. */
+    tradeIncome: Map<string, number>;
+    /** IDs of polities that are in (or entered) a debt crisis this step. */
+    crisisPolities: string[];
+}
+export interface EconomicWarfareResult {
+    /** Cost-units spent by the aggressor on the dump operation. */
+    aggressorCost_cu: number;
+    /** Price decrease applied to the targeted commodity [0, SCALE.Q]. */
+    priceDrop_Q: Q;
+}
+export declare const COMMODITIES: readonly CommodityProfile[];
+/** Returns commodity IDs a polity can produce given its tech era. */
+export declare function availableCommodities(techEra: TechEra): string[];
+/** Create a fresh MarketState with all commodities at base price, balanced supply/demand. */
+export declare function createMarket(): MarketState;
+/**
+ * Advance all commodity prices by one step.
+ *
+ * Each commodity's price changes by:
+ *   reversion  = MEAN_REVERSION_Q × (basePrice − current) / SCALE.Q
+ *   noise      = ±(volatility_Q / 2) via deterministic eventSeed
+ *   imbalance  = (demand_Q − supply_Q) × 5% / SCALE.Q   (supply/demand pressure)
+ *
+ * Result is clamped to [q(0.05), q(2.0)] to prevent collapse or runaway inflation.
+ */
+export declare function stepPrices(market: MarketState, worldSeed: number, tick: number): void;
+/**
+ * Resolve trade between all non-war polity pairs and credit treasury.
+ *
+ * For each non-war pair: the traded commodity set is the intersection of each
+ * polity's tech-era-gated catalogue.  Income per commodity =
+ *   `price_Q × TRADE_BASE_CU × sharedLocations × routeQuality_Q / SCALE.Q²`
+ *
+ * Both polities in a pair receive equal income.  Mutates `polity.treasury_cu`.
+ * Returns a map of total income credited this step per polity id.
+ */
+export declare function stepTrade(registry: PolityRegistry, pairs: PolityPair[], market: MarketState): Map<string, number>;
+/**
+ * Polity bets a fraction of treasury on a commodity price movement.
+ *
+ * Wager = `SPECULATE_WAGER_Q` (10%) of current treasury.
+ * Win probability = `WIN_PROBABILITY_NUM` / 100 (45%).  On win: treasury gains
+ * `wager × SPECULATE_WIN_MUL_Q / SCALE.Q`.  On loss: treasury loses the wager;
+ * if treasury is insufficient, the shortfall is added to `market.debt`.
+ *
+ * Expected value ≈ −10% per call (house-edge model for opaque markets).
+ * Returns the net treasury change (positive = profit, negative = loss or debt).
+ */
+export declare function speculate(polity: Polity, commodityId: string, worldSeed: number, tick: number): number;
+/**
+ * Returns true when the polity's debt exceeds the crisis threshold.
+ *
+ * Crisis triggers when:
+ * - `debt > treasury × DEBT_CRISIS_RATIO_Q / SCALE.Q`   (debt ratio exceeded), or
+ * - `treasury ≤ 0 AND debt > 0`                          (insolvency)
+ */
+export declare function checkDebtCrisis(polity: Polity, market: MarketState): boolean;
+/**
+ * Aggressor dumps supply of a commodity onto the market to depress its price.
+ *
+ * Supply increases by `SUPPLY_DUMP_Q`, capped at SCALE.Q.  Price drops
+ * proportionally to the supply increase × commodity volatility.
+ * Aggressor pays `TRADE_BASE_CU × SUPPLY_DUMP_Q / SCALE.Q × sharedLocations`
+ * cost-units (stockpile overhead).
+ *
+ * No-op if the commodity requires a higher tech era than the aggressor possesses,
+ * or if either polity is not in the registry.
+ */
+export declare function economicWarfare(aggressorId: string, targetId: string, commodityId: string, registry: PolityRegistry, market: MarketState, pairs: PolityPair[]): EconomicWarfareResult;
+/**
+ * Derive aggregate economic stress for a polity [0, SCALE.Q].
+ *
+ * Three components, equal weighting:
+ * 1. Debt ratio    — `clamp(debt / max(treasury, 1), 0, SCALE.Q)`
+ * 2. Price stress  — fraction of the polity's available commodities below 60% of base
+ * 3. War penalty   — q(0.20) per active war involving this polity, capped at q(0.60)
+ */
+export declare function deriveEconomicPressure(polity: Polity, market: MarketState, registry: PolityRegistry): Q;
+/**
+ * Full market step: advance prices, resolve trade, return income and crisis list.
+ *
+ * Call once per campaign day.  Mutates `market.prices`, polity `treasury_cu`
+ * values inside `registry`, and `market.debt` (via `checkDebtCrisis` reads only —
+ * debt is written by `speculate`, not by `stepMarket` directly).
+ */
+export declare function stepMarket(registry: PolityRegistry, pairs: PolityPair[], market: MarketState, worldSeed: number, tick: number): MarketStepResult;

package/dist/src/economy-gen.js

@@ -0,0 +1,261 @@
+// src/economy-gen.ts — Phase 72: Generative Economics
+//
+// Agent-based commodity markets for polity-scale simulation.
+// Extends Phase 61 (Polity) with price dynamics, debt cycles, and economic warfare.
+//
+// All values are fixed-point; no floating-point in the simulation path.
+// No Math.random() — determinism via eventSeed().
+import { q, SCALE, clampQ } from "./units.js";
+import { eventSeed, hashString } from "./sim/seeds.js";
+import { TechEra } from "./sim/tech.js";
+// ── Constants ──────────────────────────────────────────────────────────────────
+/** Per-step fraction pulled back toward base price (8%). */
+export const MEAN_REVERSION_Q = q(0.08);
+/** Debt/treasury ratio above which a polity is in crisis (30%). */
+export const DEBT_CRISIS_RATIO_Q = q(0.30);
+/** Supply fraction added to market in an economic warfare dump (40%). */
+export const SUPPLY_DUMP_Q = q(0.40);
+/** Base trade income per shared location per commodity per step (cost-units). */
+export const TRADE_BASE_CU = 50;
+/** Fraction of treasury wagered per speculate() call (10%). */
+export const SPECULATE_WAGER_Q = q(0.10);
+/**
+ * Profit multiplier on a winning speculation — applied to the wager amount.
+ * q(1.0) means winner gains exactly the wager (net +wager).
+ * Combined with WIN_PROBABILITY_NUM/DEN = 45/100, EV = −10% per call.
+ */
+export const SPECULATE_WIN_MUL_Q = q(1.0);
+/** Numerator of win probability fraction (45%). */
+export const WIN_PROBABILITY_NUM = 45;
+// ── Commodity catalogue ────────────────────────────────────────────────────────
+export const COMMODITIES = [
+    { id: "grain", name: "Grain", basePrice_Q: q(0.20), volatility_Q: q(0.12), techMinEra: TechEra.Prehistoric },
+    { id: "timber", name: "Timber", basePrice_Q: q(0.25), volatility_Q: q(0.08), techMinEra: TechEra.Prehistoric },
+    { id: "iron", name: "Iron", basePrice_Q: q(0.40), volatility_Q: q(0.15), techMinEra: TechEra.Ancient },
+    { id: "textile", name: "Textile", basePrice_Q: q(0.35), volatility_Q: q(0.10), techMinEra: TechEra.Ancient },
+    { id: "spice", name: "Spice", basePrice_Q: q(0.60), volatility_Q: q(0.25), techMinEra: TechEra.Ancient },
+    { id: "labour", name: "Labour", basePrice_Q: q(0.15), volatility_Q: q(0.05), techMinEra: TechEra.Prehistoric },
+    { id: "arcane", name: "Arcane Goods", basePrice_Q: q(0.80), volatility_Q: q(0.30), techMinEra: TechEra.Medieval },
+    { id: "manufactured", name: "Manufactured Goods", basePrice_Q: q(0.50), volatility_Q: q(0.18), techMinEra: TechEra.EarlyModern },
+];
+// ── Helpers ────────────────────────────────────────────────────────────────────
+/** Returns commodity IDs a polity can produce given its tech era. */
+export function availableCommodities(techEra) {
+    return COMMODITIES.filter(c => c.techMinEra <= techEra).map(c => c.id);
+}
+// ── Market creation ────────────────────────────────────────────────────────────
+/** Create a fresh MarketState with all commodities at base price, balanced supply/demand. */
+export function createMarket() {
+    const prices = new Map();
+    for (const c of COMMODITIES) {
+        prices.set(c.id, { price_Q: c.basePrice_Q, supply_Q: q(0.50), demand_Q: q(0.50) });
+    }
+    return { prices, debt: new Map() };
+}
+// ── Price dynamics ─────────────────────────────────────────────────────────────
+/**
+ * Advance all commodity prices by one step.
+ *
+ * Each commodity's price changes by:
+ *   reversion  = MEAN_REVERSION_Q × (basePrice − current) / SCALE.Q
+ *   noise      = ±(volatility_Q / 2) via deterministic eventSeed
+ *   imbalance  = (demand_Q − supply_Q) × 5% / SCALE.Q   (supply/demand pressure)
+ *
+ * Result is clamped to [q(0.05), q(2.0)] to prevent collapse or runaway inflation.
+ */
+export function stepPrices(market, worldSeed, tick) {
+    for (const c of COMMODITIES) {
+        const rec = market.prices.get(c.id);
+        // Mean reversion toward base price
+        const gap = c.basePrice_Q - rec.price_Q;
+        const reversion = Math.trunc(gap * MEAN_REVERSION_Q / SCALE.Q);
+        // Deterministic noise in [-volatility/2, +volatility/2)
+        const salt = hashString(c.id);
+        const raw = eventSeed(worldSeed, tick, 0, 0, salt);
+        const half = Math.trunc(c.volatility_Q / 2);
+        const noise = Math.trunc(raw % c.volatility_Q) - half;
+        // Supply/demand imbalance: excess demand = higher price, excess supply = lower
+        const imbalance = Math.trunc((rec.demand_Q - rec.supply_Q) * 5 / 100);
+        rec.price_Q = clampQ(rec.price_Q + reversion + noise + imbalance, q(0.05), q(2.0));
+    }
+}
+// ── Trade income ───────────────────────────────────────────────────────────────
+/**
+ * Resolve trade between all non-war polity pairs and credit treasury.
+ *
+ * For each non-war pair: the traded commodity set is the intersection of each
+ * polity's tech-era-gated catalogue.  Income per commodity =
+ *   `price_Q × TRADE_BASE_CU × sharedLocations × routeQuality_Q / SCALE.Q²`
+ *
+ * Both polities in a pair receive equal income.  Mutates `polity.treasury_cu`.
+ * Returns a map of total income credited this step per polity id.
+ */
+export function stepTrade(registry, pairs, market) {
+    const income = new Map();
+    for (const pair of pairs) {
+        const keyAB = `${pair.polityAId}:${pair.polityBId}`;
+        const keyBA = `${pair.polityBId}:${pair.polityAId}`;
+        if (registry.activeWars.has(keyAB) || registry.activeWars.has(keyBA))
+            continue;
+        const polityA = registry.polities.get(pair.polityAId);
+        const polityB = registry.polities.get(pair.polityBId);
+        if (!polityA || !polityB || pair.sharedLocations <= 0)
+            continue;
+        const aSet = new Set(availableCommodities(polityA.techEra));
+        const bSet = new Set(availableCommodities(polityB.techEra));
+        let pairIncome = 0;
+        for (const c of COMMODITIES) {
+            if (!aSet.has(c.id) || !bSet.has(c.id))
+                continue;
+            const rec = market.prices.get(c.id);
+            // price_Q × TRADE_BASE_CU / SCALE.Q → base income per location
+            const basePerLoc = Math.trunc(rec.price_Q * TRADE_BASE_CU / SCALE.Q);
+            pairIncome += Math.trunc(basePerLoc * pair.sharedLocations * pair.routeQuality_Q / SCALE.Q);
+        }
+        if (pairIncome > 0) {
+            polityA.treasury_cu += pairIncome;
+            polityB.treasury_cu += pairIncome;
+            income.set(pair.polityAId, (income.get(pair.polityAId) ?? 0) + pairIncome);
+            income.set(pair.polityBId, (income.get(pair.polityBId) ?? 0) + pairIncome);
+        }
+    }
+    return income;
+}
+// ── Speculation ────────────────────────────────────────────────────────────────
+/**
+ * Polity bets a fraction of treasury on a commodity price movement.
+ *
+ * Wager = `SPECULATE_WAGER_Q` (10%) of current treasury.
+ * Win probability = `WIN_PROBABILITY_NUM` / 100 (45%).  On win: treasury gains
+ * `wager × SPECULATE_WIN_MUL_Q / SCALE.Q`.  On loss: treasury loses the wager;
+ * if treasury is insufficient, the shortfall is added to `market.debt`.
+ *
+ * Expected value ≈ −10% per call (house-edge model for opaque markets).
+ * Returns the net treasury change (positive = profit, negative = loss or debt).
+ */
+export function speculate(polity, commodityId, worldSeed, tick) {
+    const wager = Math.trunc(polity.treasury_cu * SPECULATE_WAGER_Q / SCALE.Q);
+    if (wager <= 0)
+        return 0;
+    const salt = hashString("speculate_" + commodityId);
+    const roll = eventSeed(worldSeed, tick, hashString(polity.id), 0, salt) % SCALE.Q;
+    const threshold = Math.trunc(SCALE.Q * WIN_PROBABILITY_NUM / 100);
+    if (roll < threshold) {
+        const profit = Math.trunc(wager * SPECULATE_WIN_MUL_Q / SCALE.Q);
+        polity.treasury_cu += profit;
+        return profit;
+    }
+    else {
+        polity.treasury_cu -= wager; // always safe: wager = 10% of treasury ≤ treasury
+        return -wager;
+    }
+}
+// ── Debt crisis ────────────────────────────────────────────────────────────────
+/**
+ * Returns true when the polity's debt exceeds the crisis threshold.
+ *
+ * Crisis triggers when:
+ * - `debt > treasury × DEBT_CRISIS_RATIO_Q / SCALE.Q`   (debt ratio exceeded), or
+ * - `treasury ≤ 0 AND debt > 0`                          (insolvency)
+ */
+export function checkDebtCrisis(polity, market) {
+    const debt = market.debt.get(polity.id) ?? 0;
+    if (debt <= 0)
+        return false;
+    if (polity.treasury_cu <= 0)
+        return true;
+    const threshold = Math.trunc(polity.treasury_cu * DEBT_CRISIS_RATIO_Q / SCALE.Q);
+    return debt > threshold;
+}
+// ── Economic warfare ───────────────────────────────────────────────────────────
+/**
+ * Aggressor dumps supply of a commodity onto the market to depress its price.
+ *
+ * Supply increases by `SUPPLY_DUMP_Q`, capped at SCALE.Q.  Price drops
+ * proportionally to the supply increase × commodity volatility.
+ * Aggressor pays `TRADE_BASE_CU × SUPPLY_DUMP_Q / SCALE.Q × sharedLocations`
+ * cost-units (stockpile overhead).
+ *
+ * No-op if the commodity requires a higher tech era than the aggressor possesses,
+ * or if either polity is not in the registry.
+ */
+export function economicWarfare(aggressorId, targetId, commodityId, registry, market, pairs) {
+    const aggressor = registry.polities.get(aggressorId);
+    if (!aggressor || !registry.polities.has(targetId))
+        return { aggressorCost_cu: 0, priceDrop_Q: 0 };
+    const comm = COMMODITIES.find(c => c.id === commodityId);
+    if (!comm || comm.techMinEra > aggressor.techEra)
+        return { aggressorCost_cu: 0, priceDrop_Q: 0 };
+    const rec = market.prices.get(commodityId);
+    const prev = rec.supply_Q;
+    rec.supply_Q = clampQ(rec.supply_Q + SUPPLY_DUMP_Q, 0, SCALE.Q);
+    const supplyIncrease = rec.supply_Q - prev;
+    // Price drop proportional to the supply increase × volatility
+    const priceDrop_Q = Math.trunc(supplyIncrease * comm.volatility_Q / SCALE.Q);
+    rec.price_Q = clampQ(rec.price_Q - priceDrop_Q, q(0.05), q(2.0));
+    // Aggressor pays stockpile cost based on shared border with target
+    const sharedLocs = pairs.find(p => (p.polityAId === aggressorId && p.polityBId === targetId) ||
+        (p.polityAId === targetId && p.polityBId === aggressorId))?.sharedLocations ?? 1;
+    const aggressorCost_cu = Math.trunc(TRADE_BASE_CU * SUPPLY_DUMP_Q / SCALE.Q) * sharedLocs;
+    aggressor.treasury_cu = Math.max(0, aggressor.treasury_cu - aggressorCost_cu);
+    return { aggressorCost_cu, priceDrop_Q };
+}
+// ── Economic pressure ──────────────────────────────────────────────────────────
+/**
+ * Derive aggregate economic stress for a polity [0, SCALE.Q].
+ *
+ * Three components, equal weighting:
+ * 1. Debt ratio    — `clamp(debt / max(treasury, 1), 0, SCALE.Q)`
+ * 2. Price stress  — fraction of the polity's available commodities below 60% of base
+ * 3. War penalty   — q(0.20) per active war involving this polity, capped at q(0.60)
+ */
+export function deriveEconomicPressure(polity, market, registry) {
+    // 1. Debt ratio
+    const debt = market.debt.get(polity.id) ?? 0;
+    const debtRatio = debt > 0
+        ? clampQ(Math.trunc(debt * SCALE.Q / Math.max(polity.treasury_cu, 1)), 0, SCALE.Q)
+        : 0;
+    // 2. Price stress: fraction of available commodities trading below 60% of base
+    const avail = availableCommodities(polity.techEra);
+    let depressed = 0;
+    for (const id of avail) {
+        const rec = market.prices.get(id);
+        const comm = COMMODITIES.find(c => c.id === id);
+        if (!rec || !comm)
+            continue;
+        // 60% = 3/5 — integer arithmetic only
+        if (rec.price_Q < Math.trunc(comm.basePrice_Q * 3 / 5))
+            depressed++;
+    }
+    const priceStress = avail.length > 0
+        ? Math.trunc(depressed * SCALE.Q / avail.length)
+        : 0;
+    // 3. War penalty
+    let warCount = 0;
+    for (const key of registry.activeWars) {
+        const [a, b] = key.split(":");
+        if (a === polity.id || b === polity.id)
+            warCount++;
+    }
+    const warPenalty = clampQ(warCount * q(0.20), 0, q(0.60));
+    // Combined: equal thirds (integer division to keep fixed-point)
+    return clampQ((debtRatio + priceStress + warPenalty) / 3, 0, SCALE.Q);
+}
+// ── Composite step ─────────────────────────────────────────────────────────────
+/**
+ * Full market step: advance prices, resolve trade, return income and crisis list.
+ *
+ * Call once per campaign day.  Mutates `market.prices`, polity `treasury_cu`
+ * values inside `registry`, and `market.debt` (via `checkDebtCrisis` reads only —
+ * debt is written by `speculate`, not by `stepMarket` directly).
+ */
+export function stepMarket(registry, pairs, market, worldSeed, tick) {
+    stepPrices(market, worldSeed, tick);
+    const tradeIncome = stepTrade(registry, pairs, market);
+    const crisisPolities = [];
+    for (const polity of registry.polities.values()) {
+        if (checkDebtCrisis(polity, market))
+            crisisPolities.push(polity.id);
+    }
+    return { tradeIncome, crisisPolities };
+}

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

@@ -27,6 +27,42 @@ export interface DiseaseProfile {
      * -1 = permanent; 0 = no immunity (can be reinfected immediately).
      */
     immunityDuration_s: number;
+    /**
+     * Phase 73: opt-in to SEIR compartment tracking via `stepSEIR`.
+     * No effect on `stepDiseaseForEntity` — backward-compatible.
+     */
+    useSeir?: boolean;
+}
+/**
+ * Vaccination record granting partial-efficacy protection.
+ * Stored on `entity.vaccinations?`.
+ */
+export interface VaccinationRecord {
+    diseaseId: string;
+    /** Fraction of transmission risk blocked [Q]. q(0.95) = 95 % efficacy. */
+    efficacy_Q: Q;
+    /** Number of doses received. Informational; efficacy reflects total dose schedule. */
+    doseCount: number;
+}
+/** Non-pharmaceutical intervention type. */
+export type NPIType = "quarantine" | "mask_mandate";
+/** An active NPI for a polity. */
+export interface NPIRecord {
+    polityId: string;
+    npiType: NPIType;
+}
+/**
+ * Registry of active NPIs per polity.
+ * Key format: `"${polityId}:${npiType}"`.
+ */
+export type NPIRegistry = Map<string, NPIRecord>;
+/** Options for the extended `computeTransmissionRisk`. */
+export interface TransmissionOptions {
+    /**
+     * Mask mandate NPI active for this pair's polity.
+     * Reduces airborne transmission by `NPI_MASK_REDUCTION_Q` (60 %).
+     */
+    maskMandate?: boolean;
 }
 /** One active disease infection on an entity. */
 export interface DiseaseState {
@@ -67,10 +103,38 @@ export interface SpreadResult {
 }
 /** Maximum distance for contact/vector/waterborne transmission [SCALE.m]. */
 export declare const CONTACT_RANGE_Sm = 20000;
+/**
+ * Airborne transmission reduction from mask mandate NPI [Q].
+ * Risk is multiplied by (SCALE.Q − NPI_MASK_REDUCTION_Q) / SCALE.Q → ×0.40 remaining.
+ */
+export declare const NPI_MASK_REDUCTION_Q: number;
+/**
+ * Daily contacts-per-entity estimate for `computeR0`.
+ * Community-setting assumption; capped by actual population size.
+ */
+export declare const DAILY_CONTACTS_ESTIMATE = 15;
 /** All disease profiles indexed by id. */
 export declare const DISEASE_PROFILES: DiseaseProfile[];
 /** Look up a disease profile by id. Returns undefined for unknown ids. */
 export declare function getDiseaseProfile(id: string): DiseaseProfile | undefined;
+/**
+ * Register a custom disease profile so it can be used with
+ * `exposeToDisease`, `spreadDisease`, and `stepDiseaseForEntity`.
+ *
+ * Does not modify `DISEASE_PROFILES`. Use this to add `MEASLES` or other
+ * Phase 73 / host-defined profiles to the lookup map.
+ */
+export declare function registerDiseaseProfile(profile: DiseaseProfile): void;
+/**
+ * Measles — highly contagious SEIR airborne disease.
+ *
+ * R0 ≈ 12–18 in populations of 15+ (DAILY_CONTACTS_ESTIMATE × 14 days × baseRate).
+ * Use with `registerDiseaseProfile(MEASLES)` before calling `exposeToDisease`.
+ *
+ * Validation target: epidemic curve peaks days 10–20, burns out by day 60,
+ * matching standard SIR model output within ±15 % for 95 % susceptible population.
+ */
+export declare const MEASLES: DiseaseProfile;
 /**
  * Attempt to expose an entity to a disease.
  *
@@ -116,12 +180,18 @@ export declare function stepDiseaseForEntity(entity: Entity, delta_s: number, wo
  * Returns q(0) if the carrier has no symptomatic instance of this disease,
  * or if target already has immunity / active infection for this disease.
  *
+ * **Phase 73 extensions (backward-compatible):**
+ * - If `target.age` is set, applies age-stratified susceptibility multiplier.
+ * - If `target.vaccinations` contains a record for this disease, reduces risk by efficacy.
+ * - If `options.maskMandate` is true and disease is airborne, reduces risk by `NPI_MASK_REDUCTION_Q`.
+ *
  * @param carrier    The potentially infectious entity.
  * @param target     The potentially susceptible entity.
  * @param dist_Sm    Distance between them [SCALE.m].
  * @param disease    The disease profile to evaluate.
+ * @param options    Phase 73 optional NPI modifiers.
  */
-export declare function computeTransmissionRisk(carrier: Entity, target: Entity, dist_Sm: number, disease: DiseaseProfile): Q;
+export declare function computeTransmissionRisk(carrier: Entity, target: Entity, dist_Sm: number, disease: DiseaseProfile, options?: TransmissionOptions): Q;
 /**
  * Attempt to spread disease across a set of nearby entity pairs.
  *
@@ -139,3 +209,76 @@ export declare function computeTransmissionRisk(carrier: Entity, target: Entity,
  * @returns          Number of new exposures created.
  */
 export declare function spreadDisease(entityMap: Map<number, Entity>, pairs: NearbyPair[], worldSeed: number, tick: number): SpreadResult;
+/**
+ * Age-stratified susceptibility multiplier [Q].
+ *
+ * Returns a value that may exceed SCALE.Q (increased susceptibility) or fall
+ * below it (relative protection).  Applied in `computeTransmissionRisk` when
+ * `target.age` is set.
+ *
+ * | Age range | Multiplier | Notes                         |
+ * |-----------|-----------|-------------------------------|
+ * | 0–4 yrs   | ×1.30     | High infant susceptibility    |
+ * | 5–14 yrs  | ×0.80     | Children — lower risk         |
+ * | 15–59 yrs | ×1.00     | Adult baseline                |
+ * | 60–74 yrs | ×1.20     | Early elderly                 |
+ * | 75 + yrs  | ×1.50     | Late elderly / ancient        |
+ */
+export declare function ageSusceptibility_Q(ageYears: number): Q;
+/**
+ * Add or update a vaccination record on an entity.
+ *
+ * If the entity already has a record for this disease, updates `efficacy_Q`
+ * and increments `doseCount` (booster model).  Otherwise creates a new record.
+ *
+ * @param entity       Target entity to vaccinate.
+ * @param diseaseId    Disease being vaccinated against.
+ * @param efficacy_Q   Protection level [Q]; q(0.95) = 95 % efficacy.
+ */
+export declare function vaccinate(entity: Entity, diseaseId: string, efficacy_Q: Q): void;
+/**
+ * Activate an NPI for a polity.
+ *
+ * `"mask_mandate"` — reduces airborne transmission in `computeTransmissionRisk`
+ *   by `NPI_MASK_REDUCTION_Q` when the caller passes `options.maskMandate = true`.
+ *
+ * `"quarantine"` — recorded in the registry; the host is responsible for halving
+ *   the contact-range pairs passed to `spreadDisease` (spatial filtering).
+ */
+export declare function applyNPI(npiRegistry: NPIRegistry, npiType: NPIType, polityId: string): void;
+/** Remove an NPI from a polity's registry entry. */
+export declare function removeNPI(npiRegistry: NPIRegistry, npiType: NPIType, polityId: string): void;
+/** Returns true if the specified NPI is currently active for the polity. */
+export declare function hasNPI(npiRegistry: NPIRegistry, npiType: NPIType, polityId: string): boolean;
+/**
+ * Estimate the basic reproductive number R0 for a disease profile.
+ *
+ * Formula: R0 = beta × D × c
+ *   - beta = baseTransmissionRate_Q / SCALE.Q (per-contact daily probability)
+ *   - D    = symptomaticDuration_s / 86400 (infectious period in days)
+ *   - c    = min(DAILY_CONTACTS_ESTIMATE, entityMap.size − 1) (daily contacts)
+ *
+ * Used for validation — not a simulation path value.
+ *
+ * @param profile    Disease profile to evaluate.
+ * @param entityMap  Population map (size determines contact estimate).
+ * @returns          Estimated R0 (float; not fixed-point).
+ */
+export declare function computeR0(profile: DiseaseProfile, entityMap: Map<number, Entity>): number;
+/**
+ * Advance a single SEIR-enabled disease on an entity by `delta_s` seconds.
+ *
+ * Functionally equivalent to `stepDiseaseForEntity` for this profile only —
+ * isolates the target disease so other active diseases are not advanced.
+ * Backward-compatible: calls through to the Phase 56 step function.
+ *
+ * Intended for use with `profile.useSeir === true` diseases, but works with
+ * any profile registered via `registerDiseaseProfile`.
+ *
+ * @param entity     Entity to advance.
+ * @param delta_s    Elapsed seconds.
+ * @param profile    Disease profile to process.
+ * @param worldSeed  World seed for deterministic mortality roll.
+ * @param tick       Current tick for deterministic mortality roll.
+ */
+export declare function stepSEIR(entity: Entity, delta_s: number, profile: DiseaseProfile, worldSeed: number, tick: number): EntityDiseaseResult;

package/dist/src/sim/disease.js

@@ -22,6 +22,19 @@ export const CONTACT_RANGE_Sm = 20_000; // 2 m
 const FEVER_AIRBORNE_Sm = 100_000; // 10 m
 /** Plague airborne range [SCALE.m]. */
 const PLAGUE_AIRBORNE_Sm = 50_000; // 5 m
+// Phase 73 constants ───────────────────────────────────────────────────────────
+/**
+ * Airborne transmission reduction from mask mandate NPI [Q].
+ * Risk is multiplied by (SCALE.Q − NPI_MASK_REDUCTION_Q) / SCALE.Q → ×0.40 remaining.
+ */
+export const NPI_MASK_REDUCTION_Q = q(0.60);
+/**
+ * Daily contacts-per-entity estimate for `computeR0`.
+ * Community-setting assumption; capped by actual population size.
+ */
+export const DAILY_CONTACTS_ESTIMATE = 15;
+/** Seconds per year — mirrored from aging.ts to avoid circular import. */
+const _SECS_PER_YEAR = 365 * 86_400;
 // ── Disease Catalogue ─────────────────────────────────────────────────────────
 /**
  * Common fever — mild respiratory infection.
@@ -133,6 +146,39 @@ const _PROFILE_MAP = new Map(DISEASE_PROFILES.map(p => [p.id, p]));
 export function getDiseaseProfile(id) {
     return _PROFILE_MAP.get(id);
 }
+/**
+ * Register a custom disease profile so it can be used with
+ * `exposeToDisease`, `spreadDisease`, and `stepDiseaseForEntity`.
+ *
+ * Does not modify `DISEASE_PROFILES`. Use this to add `MEASLES` or other
+ * Phase 73 / host-defined profiles to the lookup map.
+ */
+export function registerDiseaseProfile(profile) {
+    _PROFILE_MAP.set(profile.id, profile);
+}
+// ── Phase 73: MEASLES profile ─────────────────────────────────────────────────
+/**
+ * Measles — highly contagious SEIR airborne disease.
+ *
+ * R0 ≈ 12–18 in populations of 15+ (DAILY_CONTACTS_ESTIMATE × 14 days × baseRate).
+ * Use with `registerDiseaseProfile(MEASLES)` before calling `exposeToDisease`.
+ *
+ * Validation target: epidemic curve peaks days 10–20, burns out by day 60,
+ * matching standard SIR model output within ±15 % for 95 % susceptible population.
+ */
+export const MEASLES = {
+    id: "measles",
+    name: "Measles",
+    transmissionRoute: "airborne",
+    baseTransmissionRate_Q: q(0.072), // R0 ≈ 15.1 with 15 daily contacts, 14-day duration
+    incubationPeriod_s: 14 * 86_400, // 14-day latent period
+    symptomaticDuration_s: 14 * 86_400, // 14-day infectious period
+    mortalityRate_Q: q(0.002), // 0.2 % IFR (developed world)
+    symptomSeverity_Q: q(0.15),
+    airborneRange_Sm: 100_000, // 10 m
+    immunityDuration_s: -1, // permanent lifelong immunity
+    useSeir: true,
+};
 // ── Entity-level API ──────────────────────────────────────────────────────────
 /**
  * Attempt to expose an entity to a disease.
@@ -268,12 +314,18 @@ export function stepDiseaseForEntity(entity, delta_s, worldSeed, tick) {
  * Returns q(0) if the carrier has no symptomatic instance of this disease,
  * or if target already has immunity / active infection for this disease.
  *
+ * **Phase 73 extensions (backward-compatible):**
+ * - If `target.age` is set, applies age-stratified susceptibility multiplier.
+ * - If `target.vaccinations` contains a record for this disease, reduces risk by efficacy.
+ * - If `options.maskMandate` is true and disease is airborne, reduces risk by `NPI_MASK_REDUCTION_Q`.
+ *
  * @param carrier    The potentially infectious entity.
  * @param target     The potentially susceptible entity.
  * @param dist_Sm    Distance between them [SCALE.m].
  * @param disease    The disease profile to evaluate.
+ * @param options    Phase 73 optional NPI modifiers.
  */
-export function computeTransmissionRisk(carrier, target, dist_Sm, disease) {
+export function computeTransmissionRisk(carrier, target, dist_Sm, disease, options) {
     // Carrier must be symptomatic with this disease
     const carrierState = carrier.activeDiseases?.find(d => d.diseaseId === disease.id && d.phase === "symptomatic");
     if (!carrierState)
@@ -285,16 +337,37 @@ export function computeTransmissionRisk(carrier, target, dist_Sm, disease) {
     const immune = target.immunity?.some(r => r.diseaseId === disease.id && (r.remainingSeconds === -1 || r.remainingSeconds > 0));
     if (immune)
         return q(0);
+    // ── Compute distance-based base risk ───────────────────────────────────────
+    let risk;
     if (disease.transmissionRoute === "airborne") {
         if (disease.airborneRange_Sm <= 0 || dist_Sm >= disease.airborneRange_Sm)
             return q(0);
         const proximity_Q = Math.round((disease.airborneRange_Sm - dist_Sm) * SCALE.Q / disease.airborneRange_Sm);
-        return Math.round(disease.baseTransmissionRate_Q * proximity_Q / SCALE.Q);
+        risk = Math.round(disease.baseTransmissionRate_Q * proximity_Q / SCALE.Q);
     }
-    // contact / vector / waterborne: flat risk within CONTACT_RANGE
-    if (dist_Sm > CONTACT_RANGE_Sm)
-        return q(0);
-    return disease.baseTransmissionRate_Q;
+    else {
+        // contact / vector / waterborne: flat risk within CONTACT_RANGE
+        if (dist_Sm > CONTACT_RANGE_Sm)
+            return q(0);
+        risk = disease.baseTransmissionRate_Q;
+    }
+    // ── Phase 73: age-stratified susceptibility ────────────────────────────────
+    if (target.age) {
+        const ageYears = target.age.ageSeconds / _SECS_PER_YEAR;
+        const ageMultiplier = ageSusceptibility_Q(ageYears);
+        risk = clampQ(Math.round(risk * ageMultiplier / SCALE.Q), 0, SCALE.Q);
+    }
+    // ── Phase 73: vaccination efficacy reduction ───────────────────────────────
+    const vacc = target.vaccinations?.find(v => v.diseaseId === disease.id);
+    if (vacc && vacc.efficacy_Q > 0) {
+        const blocked = Math.round(risk * vacc.efficacy_Q / SCALE.Q);
+        risk = Math.max(0, risk - blocked);
+    }
+    // ── Phase 73: NPI mask mandate (airborne only) ─────────────────────────────
+    if (options?.maskMandate && disease.transmissionRoute === "airborne") {
+        risk = Math.round(risk * (SCALE.Q - NPI_MASK_REDUCTION_Q) / SCALE.Q);
+    }
+    return risk;
 }
 /**
  * Attempt to spread disease across a set of nearby entity pairs.
@@ -351,3 +424,136 @@ function diseaseIdSalt(id) {
         h = (h + id.charCodeAt(i)) & 0xFFFFFF;
     return h;
 }
+// ── Phase 73: Enhanced Epidemiology Functions ─────────────────────────────────
+/**
+ * Age-stratified susceptibility multiplier [Q].
+ *
+ * Returns a value that may exceed SCALE.Q (increased susceptibility) or fall
+ * below it (relative protection).  Applied in `computeTransmissionRisk` when
+ * `target.age` is set.
+ *
+ * | Age range | Multiplier | Notes                         |
+ * |-----------|-----------|-------------------------------|
+ * | 0–4 yrs   | ×1.30     | High infant susceptibility    |
+ * | 5–14 yrs  | ×0.80     | Children — lower risk         |
+ * | 15–59 yrs | ×1.00     | Adult baseline                |
+ * | 60–74 yrs | ×1.20     | Early elderly                 |
+ * | 75 + yrs  | ×1.50     | Late elderly / ancient        |
+ */
+export function ageSusceptibility_Q(ageYears) {
+    if (ageYears < 5)
+        return 13_000; // ×1.30
+    if (ageYears < 15)
+        return 8_000; // ×0.80
+    if (ageYears < 60)
+        return 10_000; // ×1.00 baseline
+    if (ageYears < 75)
+        return 12_000; // ×1.20
+    return 15_000; // ×1.50
+}
+/**
+ * Add or update a vaccination record on an entity.
+ *
+ * If the entity already has a record for this disease, updates `efficacy_Q`
+ * and increments `doseCount` (booster model).  Otherwise creates a new record.
+ *
+ * @param entity       Target entity to vaccinate.
+ * @param diseaseId    Disease being vaccinated against.
+ * @param efficacy_Q   Protection level [Q]; q(0.95) = 95 % efficacy.
+ */
+export function vaccinate(entity, diseaseId, efficacy_Q) {
+    if (!entity.vaccinations)
+        entity.vaccinations = [];
+    const existing = entity.vaccinations.find(v => v.diseaseId === diseaseId);
+    if (existing) {
+        existing.efficacy_Q = efficacy_Q;
+        existing.doseCount++;
+    }
+    else {
+        entity.vaccinations.push({ diseaseId, efficacy_Q, doseCount: 1 });
+    }
+}
+// ── NPI registry helpers ───────────────────────────────────────────────────────
+function _npiKey(polityId, npiType) {
+    return `${polityId}:${npiType}`;
+}
+/**
+ * Activate an NPI for a polity.
+ *
+ * `"mask_mandate"` — reduces airborne transmission in `computeTransmissionRisk`
+ *   by `NPI_MASK_REDUCTION_Q` when the caller passes `options.maskMandate = true`.
+ *
+ * `"quarantine"` — recorded in the registry; the host is responsible for halving
+ *   the contact-range pairs passed to `spreadDisease` (spatial filtering).
+ */
+export function applyNPI(npiRegistry, npiType, polityId) {
+    npiRegistry.set(_npiKey(polityId, npiType), { polityId, npiType });
+}
+/** Remove an NPI from a polity's registry entry. */
+export function removeNPI(npiRegistry, npiType, polityId) {
+    npiRegistry.delete(_npiKey(polityId, npiType));
+}
+/** Returns true if the specified NPI is currently active for the polity. */
+export function hasNPI(npiRegistry, npiType, polityId) {
+    return npiRegistry.has(_npiKey(polityId, npiType));
+}
+/**
+ * Estimate the basic reproductive number R0 for a disease profile.
+ *
+ * Formula: R0 = beta × D × c
+ *   - beta = baseTransmissionRate_Q / SCALE.Q (per-contact daily probability)
+ *   - D    = symptomaticDuration_s / 86400 (infectious period in days)
+ *   - c    = min(DAILY_CONTACTS_ESTIMATE, entityMap.size − 1) (daily contacts)
+ *
+ * Used for validation — not a simulation path value.
+ *
+ * @param profile    Disease profile to evaluate.
+ * @param entityMap  Population map (size determines contact estimate).
+ * @returns          Estimated R0 (float; not fixed-point).
+ */
+export function computeR0(profile, entityMap) {
+    const infectiousDays = profile.symptomaticDuration_s / 86_400;
+    const beta = profile.baseTransmissionRate_Q / SCALE.Q;
+    const contacts = Math.min(DAILY_CONTACTS_ESTIMATE, Math.max(1, entityMap.size - 1));
+    return beta * infectiousDays * contacts;
+}
+/**
+ * Advance a single SEIR-enabled disease on an entity by `delta_s` seconds.
+ *
+ * Functionally equivalent to `stepDiseaseForEntity` for this profile only —
+ * isolates the target disease so other active diseases are not advanced.
+ * Backward-compatible: calls through to the Phase 56 step function.
+ *
+ * Intended for use with `profile.useSeir === true` diseases, but works with
+ * any profile registered via `registerDiseaseProfile`.
+ *
+ * @param entity     Entity to advance.
+ * @param delta_s    Elapsed seconds.
+ * @param profile    Disease profile to process.
+ * @param worldSeed  World seed for deterministic mortality roll.
+ * @param tick       Current tick for deterministic mortality roll.
+ */
+export function stepSEIR(entity, delta_s, profile, worldSeed, tick) {
+    const empty = {
+        advancedToSymptomatic: [],
+        recovered: [],
+        died: false,
+        fatigueApplied: 0,
+    };
+    if (entity.injury.dead)
+        return empty;
+    const diseaseState = entity.activeDiseases?.find(d => d.diseaseId === profile.id);
+    if (!diseaseState)
+        return empty;
+    // Isolate this disease so stepDiseaseForEntity only processes it
+    const others = entity.activeDiseases.filter(d => d.diseaseId !== profile.id);
+    entity.activeDiseases = [diseaseState];
+    const result = stepDiseaseForEntity(entity, delta_s, worldSeed, tick);
+    // Reattach other diseases (preserving any mutations stepDiseaseForEntity made)
+    const remaining = entity.activeDiseases ?? [];
+    entity.activeDiseases = [...others, ...remaining];
+    if (entity.activeDiseases.length === 0) {
+        delete entity.activeDiseases;
+    }
+    return result;
+}

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

@@ -17,7 +17,7 @@ import type { LimbState } from "./limb.js";
 import type { ExtendedSenses } from "./sensory-extended.js";
 import type { ActiveIngestedToxin, CumulativeExposureRecord, WithdrawalState } from "./systemic-toxicology.js";
 import type { TraumaState } from "./wound-aging.js";
-import type { DiseaseState, ImmunityRecord } from "./disease.js";
+import type { DiseaseState, ImmunityRecord, VaccinationRecord } from "./disease.js";
 import type { AgeState } from "./aging.js";
 import type { SleepState } from "./sleep.js";
 import type { MountState } from "./mount.js";
@@ -219,6 +219,11 @@ export interface Entity {
      * Consumed by `src/sim/disease.ts`.
      */
     immunity?: ImmunityRecord[];
+    /**
+     * @subsystem(disease/seir) Phase 73: vaccination records granting partial-efficacy protection.
+     * Consumed by `computeTransmissionRisk` in `src/sim/disease.ts`.
+     */
+    vaccinations?: VaccinationRecord[];
     /**
      * @subsystem(aging) Elapsed life-seconds for aging calculations.
      * Consumed by `src/sim/aging.ts`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@its-not-rocket-science/ananke",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",
@@ -116,6 +116,7 @@
     "example:species": "node dist/examples/quickstart-species.js",
     "generate-fixtures": "node dist/tools/generate-fixtures.js",
     "generate-zoo": "node dist/tools/generate-zoo.js",
+    "generate-playground": "node dist/tools/generate-playground.js",
     "generate-map": "node dist/tools/generate-map.js",
     "world-server": "node dist/tools/world-server.js",
     "persistent-world": "node dist/tools/persistent-world.js",