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

package/CHANGELOG.md

@@ -6,6 +6,57 @@ 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
+
+- **CE-5 · Persistent World Server** — campaign ↔ combat battle bridge:
+  - src/battle-bridge.ts: pure functions translating polity state to
+    BattleConfig and BattleOutcome back to PolityImpact[]. Covers
+    tech-era→loadout mapping, military-strength→team-size scaling,
+    deterministic battle seed, morale/stability/population impact.
+    27 tests in test/battle-bridge.test.ts.
+  - tools/persistent-world.ts: integrated server running polity tick +
+    synchronous tactical battles every 7 days per active war. Battle
+    outcomes mutate polity morale, stability, and population. Full
+    checkpoint/resume, WebSocket push, HTTP war/peace/save/reset/battles
+    endpoints. Run with: npm run persistent-world
+
+---
+
 ## [0.1.15] — 2026-03-25
 
 ### Added
@@ -33,8 +84,6 @@ Versioning follows [Semantic Versioning](https://semver.org/).
     accumulation parity with the TypeScript reference implementation.
   - Build scripts: `npm run build:wasm:all`, `npm run test:wasm`.
 
-## [Unreleased]
-
 ### Added
 
 - **Phase 71 · Cultural Generation & Evolution Framework** (`src/culture.ts`)

package/dist/src/battle-bridge.d.ts

@@ -0,0 +1,94 @@
+import { TechEra } from "./sim/tech.js";
+import type { Polity } from "./polity.js";
+/** Equipment loadout inferred from a polity's tech era. */
+export interface EraLoadout {
+    archetype: string;
+    weaponId: string;
+    armourId: string;
+}
+/** Configuration for a single tactical battle between two polities. */
+export interface BattleConfig {
+    /** Deterministic seed: combines world seed + day + polity ids. */
+    seed: number;
+    polityAId: string;
+    polityBId: string;
+    teamASize: number;
+    teamBSize: number;
+    loadoutA: EraLoadout;
+    loadoutB: EraLoadout;
+    /** Tick limit — battle is a draw if neither side wins by this tick. */
+    maxTicks: number;
+}
+/** Result reported by the caller after the battle completes. */
+export interface BattleOutcome {
+    /** 1 = team A won, 2 = team B won, 0 = draw (timeout or mutual annihilation). */
+    winner: 0 | 1 | 2;
+    ticksElapsed: number;
+    teamACasualties: number;
+    teamBCasualties: number;
+}
+/** Per-polity state changes to apply after a battle. */
+export interface PolityImpact {
+    polityId: string;
+    moraleDelta_Q: number;
+    stabilityDelta_Q: number;
+    populationLost: number;
+}
+/** Summary record written to the battle log. */
+export interface BattleRecord {
+    day: number;
+    polityAId: string;
+    polityBId: string;
+    winner: 0 | 1 | 2;
+    teamACasualties: number;
+    teamBCasualties: number;
+    ticksElapsed: number;
+}
+/** Minimum and maximum combatants per side. */
+export declare const MIN_TEAM_SIZE = 2;
+export declare const MAX_TEAM_SIZE = 16;
+/** Battle ends after this many ticks regardless of outcome (prevents infinite loops). */
+export declare const DEFAULT_MAX_TICKS = 6000;
+/** Morale bonus for winning a battle (Q units). */
+export declare const WIN_MORALE_BONUS: number;
+/** Morale penalty for losing a battle (Q units). */
+export declare const LOSS_MORALE_PENALTY: number;
+/** Stability penalty per 10% casualties above 20% casualty rate. */
+export declare const CASUALTY_STABILITY_RATE: number;
+/** Population lost per combatant casualty (polity headcount, not Q). */
+export declare const POP_PER_CASUALTY = 50;
+/**
+ * Returns the best available weapon and armour for a given tech era.
+ * Prehistoric → club + none; Ancient → knife + leather; Medieval+ → longsword + mail/plate.
+ */
+export declare function techEraToLoadout(era: TechEra): EraLoadout;
+/**
+ * Converts a polity's military strength (Q) to a team size.
+ * q(0) → MIN_TEAM_SIZE; q(1.0) → MAX_TEAM_SIZE.  Linear interpolation.
+ */
+export declare function militaryStrengthToTeamSize(militaryStrength_Q: number): number;
+/**
+ * Produces a deterministic battle seed from the world seed, day, and polity ids.
+ * Ensures each polity pair on each day gets a unique, reproducible seed.
+ */
+export declare function battleSeed(worldSeed: number, day: number, polityAId: string, polityBId: string): number;
+/**
+ * Builds a BattleConfig for a war between two polities.
+ * Team sizes scale with militaryStrength_Q; loadouts reflect each side's tech era.
+ */
+export declare function battleConfigFromPolities(polityA: Polity, polityB: Polity, worldSeed: number, day: number, maxTicks?: number): BattleConfig;
+/**
+ * Derives the per-polity state changes to apply after a battle.
+ *
+ * Win:  +WIN_MORALE_BONUS morale.
+ * Loss: −LOSS_MORALE_PENALTY morale.
+ * Draw: no morale change.
+ * Both sides: stability penalty proportional to casualties above 20%.
+ * Population: POP_PER_CASUALTY headcount lost per casualty.
+ */
+export declare function polityImpactFromBattle(outcome: BattleOutcome, config: BattleConfig): PolityImpact[];
+/**
+ * Apply a PolityImpact to a polity in-place.
+ * Clamps morale and stability to [0, SCALE.Q].
+ */
+export declare function applyPolityImpact(polity: Polity, impact: PolityImpact): void;

package/dist/src/battle-bridge.js

@@ -0,0 +1,126 @@
+// src/battle-bridge.ts — Campaign ↔ Combat bridge for the Persistent World Server.
+//
+// Pure functions that translate between polity-scale state and tactical combat
+// configuration, and back.  No I/O, no timers, no side effects.
+//
+// Flow:
+//   1. Polity layer detects a war (activeWars contains pair key).
+//   2. Caller invokes battleConfigFromPolities() to get a BattleConfig.
+//   3. Caller runs a tactical combat instance until one team is wiped out.
+//   4. Caller invokes polityImpactFromBattle() to get PolityImpact[] to apply.
+import { SCALE, q, clampQ } from "./units.js";
+import { TechEra } from "./sim/tech.js";
+// ── Constants ──────────────────────────────────────────────────────────────────
+/** Minimum and maximum combatants per side. */
+export const MIN_TEAM_SIZE = 2;
+export const MAX_TEAM_SIZE = 16;
+/** Battle ends after this many ticks regardless of outcome (prevents infinite loops). */
+export const DEFAULT_MAX_TICKS = 6000; // 5 min at 20 Hz
+/** Morale bonus for winning a battle (Q units). */
+export const WIN_MORALE_BONUS = q(0.08);
+/** Morale penalty for losing a battle (Q units). */
+export const LOSS_MORALE_PENALTY = q(0.12);
+/** Stability penalty per 10% casualties above 20% casualty rate. */
+export const CASUALTY_STABILITY_RATE = q(0.02);
+/** Population lost per combatant casualty (polity headcount, not Q). */
+export const POP_PER_CASUALTY = 50;
+// ── Era → Loadout mapping ──────────────────────────────────────────────────────
+/**
+ * Returns the best available weapon and armour for a given tech era.
+ * Prehistoric → club + none; Ancient → knife + leather; Medieval+ → longsword + mail/plate.
+ */
+export function techEraToLoadout(era) {
+    switch (era) {
+        case TechEra.Prehistoric:
+            return { archetype: "HUMAN_BASE", weaponId: "wpn_club", armourId: "arm_leather" };
+        case TechEra.Ancient:
+            return { archetype: "HUMAN_BASE", weaponId: "wpn_knife", armourId: "arm_leather" };
+        case TechEra.Medieval:
+            return { archetype: "HUMAN_BASE", weaponId: "wpn_longsword", armourId: "arm_mail" };
+        case TechEra.EarlyModern:
+            return { archetype: "HUMAN_BASE", weaponId: "wpn_longsword", armourId: "arm_plate" };
+        default:
+            return { archetype: "HUMAN_BASE", weaponId: "wpn_longsword", armourId: "arm_plate" };
+    }
+}
+// ── Military strength → team size ─────────────────────────────────────────────
+/**
+ * Converts a polity's military strength (Q) to a team size.
+ * q(0) → MIN_TEAM_SIZE; q(1.0) → MAX_TEAM_SIZE.  Linear interpolation.
+ */
+export function militaryStrengthToTeamSize(militaryStrength_Q) {
+    const frac = Math.max(0, Math.min(SCALE.Q, militaryStrength_Q)) / SCALE.Q;
+    const size = Math.round(MIN_TEAM_SIZE + frac * (MAX_TEAM_SIZE - MIN_TEAM_SIZE));
+    return Math.max(MIN_TEAM_SIZE, Math.min(MAX_TEAM_SIZE, size));
+}
+// ── Deterministic seed ─────────────────────────────────────────────────────────
+/**
+ * Produces a deterministic battle seed from the world seed, day, and polity ids.
+ * Ensures each polity pair on each day gets a unique, reproducible seed.
+ */
+export function battleSeed(worldSeed, day, polityAId, polityBId) {
+    const idSalt = [...(polityAId + polityBId)].reduce((acc, c) => acc + c.charCodeAt(0), 0);
+    return ((worldSeed * 1000003 + day * 6151 + idSalt) >>> 0);
+}
+// ── BattleConfig factory ───────────────────────────────────────────────────────
+/**
+ * Builds a BattleConfig for a war between two polities.
+ * Team sizes scale with militaryStrength_Q; loadouts reflect each side's tech era.
+ */
+export function battleConfigFromPolities(polityA, polityB, worldSeed, day, maxTicks = DEFAULT_MAX_TICKS) {
+    return {
+        seed: battleSeed(worldSeed, day, polityA.id, polityB.id),
+        polityAId: polityA.id,
+        polityBId: polityB.id,
+        teamASize: militaryStrengthToTeamSize(polityA.militaryStrength_Q),
+        teamBSize: militaryStrengthToTeamSize(polityB.militaryStrength_Q),
+        loadoutA: techEraToLoadout(polityA.techEra),
+        loadoutB: techEraToLoadout(polityB.techEra),
+        maxTicks,
+    };
+}
+// ── PolityImpact derivation ────────────────────────────────────────────────────
+/**
+ * Derives the per-polity state changes to apply after a battle.
+ *
+ * Win:  +WIN_MORALE_BONUS morale.
+ * Loss: −LOSS_MORALE_PENALTY morale.
+ * Draw: no morale change.
+ * Both sides: stability penalty proportional to casualties above 20%.
+ * Population: POP_PER_CASUALTY headcount lost per casualty.
+ */
+export function polityImpactFromBattle(outcome, config) {
+    const results = [];
+    const sides = [
+        { id: config.polityAId, casualties: outcome.teamACasualties, teamSize: config.teamASize, isWinner: outcome.winner === 1 },
+        { id: config.polityBId, casualties: outcome.teamBCasualties, teamSize: config.teamBSize, isWinner: outcome.winner === 2 },
+    ];
+    for (const side of sides) {
+        const isLoser = outcome.winner !== 0 && !side.isWinner;
+        const moraleDelta_Q = side.isWinner
+            ? WIN_MORALE_BONUS
+            : isLoser
+                ? -LOSS_MORALE_PENALTY
+                : 0;
+        // Stability penalty for casualty rates above 20%
+        const casualtyRate = side.teamSize > 0 ? side.casualties / side.teamSize : 0;
+        const excessCasualties = Math.max(0, casualtyRate - 0.20);
+        const stabilityDelta_Q = -Math.round(excessCasualties * 10 * CASUALTY_STABILITY_RATE);
+        results.push({
+            polityId: side.id,
+            moraleDelta_Q,
+            stabilityDelta_Q,
+            populationLost: side.casualties * POP_PER_CASUALTY,
+        });
+    }
+    return results;
+}
+/**
+ * Apply a PolityImpact to a polity in-place.
+ * Clamps morale and stability to [0, SCALE.Q].
+ */
+export function applyPolityImpact(polity, impact) {
+    polity.moraleQ = clampQ(polity.moraleQ + impact.moraleDelta_Q, 0, SCALE.Q);
+    polity.stabilityQ = clampQ(polity.stabilityQ + impact.stabilityDelta_Q, 0, SCALE.Q);
+    polity.population = Math.max(0, polity.population - impact.populationLost);
+}

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.15",
+  "version": "0.1.17",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",
@@ -116,8 +116,10 @@
     "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",
     "replication-server": "node dist/tools/replication-server.js",
     "benchmark-check": "node dist/tools/benchmark-check.js",
     "benchmark-check:strict": "node dist/tools/benchmark-check.js --threshold=0.10",