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

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/dist/src/succession.d.ts

@@ -0,0 +1,86 @@
+import type { LineageRegistry } from "./kinship.js";
+import type { RenownRegistry } from "./renown.js";
+import type { Polity } from "./polity.js";
+import type { Q } from "./units.js";
+/** How the succession contest is resolved. */
+export type SuccessionRuleType = "primogeniture" | "renown_based" | "election";
+export interface SuccessionRule {
+    type: SuccessionRuleType;
+    /**
+     * Maximum kinship degree to search for candidates (default `MAX_KINSHIP_DEPTH`).
+     * Closer kin are always preferred at equal claim strength.
+     */
+    maxDegree?: number;
+}
+/**
+ * A single candidate in a succession contest.
+ */
+export interface SuccessionCandidate {
+    entityId: number;
+    /** Degree of kinship to the deceased (1 = child/parent, 2 = grandchild, etc.). */
+    kinshipDegree: number;
+    /** Candidate's own renown from Phase 75. */
+    renown_Q: Q;
+    /**
+     * Ancestor-inherited renown bonus from Phase 76.
+     * Provides legitimacy even for candidates who have not yet distinguished themselves.
+     */
+    inheritedRenown_Q: Q;
+    /**
+     * Final composite claim strength [0, SCALE.Q].
+     * For primogeniture: 0 for all except first-born (which gets SCALE.Q).
+     * For renown_based / election: weighted combination of renown + inherited.
+     */
+    claimStrength_Q: Q;
+}
+/**
+ * Outcome of a succession resolution.
+ */
+export interface SuccessionResult {
+    /** Winning heir, or `null` if no eligible candidates were found. */
+    heirId: number | null;
+    /** All candidates evaluated, sorted by claimStrength_Q descending. */
+    candidates: SuccessionCandidate[];
+    rule: SuccessionRuleType;
+    /**
+     * Signed stability delta [−SCALE.Q, +SCALE.Q].
+     * Negative = destabilising (distant heir, no heir, contested succession).
+     * Positive = stabilising (clear close-kin heir).
+     */
+    stabilityImpact_Q: Q;
+}
+/** Weight of own renown vs. inherited renown when computing claim strength. */
+export declare const CLAIM_OWN_RENOWN_WEIGHT_Q: Q;
+export declare const CLAIM_INHERITED_RENOWN_WEIGHT_Q: Q;
+/** Stability penalty per extra degree of kinship beyond 1 (direct child/parent). */
+export declare const STABILITY_DISTANT_HEIR_Q: Q;
+/** Stability penalty when no heir is found. */
+export declare const STABILITY_NO_HEIR_Q: Q;
+/** Additional penalty when the top two candidates are within this band. */
+export declare const CONTESTED_THRESHOLD_Q: Q;
+export declare const STABILITY_CONTESTED_Q: Q;
+/** Stability bonus when a direct child inherits with no contest. */
+export declare const STABILITY_CLEAN_SUCCESSION_Q: Q;
+/**
+ * Find all kin of `deceasedId` up to `maxDegree` and compute their claim strength.
+ * Candidates are sorted by claimStrength_Q descending, then kinshipDegree ascending.
+ */
+export declare function findSuccessionCandidates(lineage: LineageRegistry, deceasedId: number, renownRegistry: RenownRegistry, maxDegree?: number): SuccessionCandidate[];
+/**
+ * Resolve succession after `deceasedId` dies.
+ *
+ * @param lineage         Kinship registry (Phase 76).
+ * @param deceasedId      The entity whose position must be inherited.
+ * @param renownRegistry  Renown registry (Phase 75).
+ * @param rule            Succession rule to apply.
+ * @param worldSeed       For deterministic election roll.
+ * @param tick            Current simulation tick.
+ */
+export declare function resolveSuccession(lineage: LineageRegistry, deceasedId: number, renownRegistry: RenownRegistry, rule: SuccessionRule, worldSeed: number, tick: number): SuccessionResult;
+/**
+ * Apply a succession result to a polity.
+ * Adjusts `stabilityQ` by `result.stabilityImpact_Q`.
+ * Does NOT change the ruler field (Polity has no rulerId); callers update faction
+ * leadership separately if needed.
+ */
+export declare function applySuccessionToPolity(polity: Polity, result: SuccessionResult): void;

package/dist/src/succession.js

@@ -0,0 +1,197 @@
+// src/succession.ts — Phase 77: Dynasty & Succession
+//
+// Resolves inheritance of political leadership when a ruler dies.
+// Integrates Phase 76 (Kinship) for candidate discovery and Phase 75 (Renown)
+// for claim-strength weighting. No kernel changes; no new Entity fields.
+//
+// Succession rules:
+//   primogeniture  — first-born child (lowest entityId as proxy for birth order)
+//   renown_based   — candidate with highest `claimStrength_Q` (renown + inherited)
+//   election       — renown-weighted deterministic selection via eventSeed
+//
+// Stability impact:
+//   Direct heir (degree 1) → ±0 base impact
+//   Distant heir (degree 2+) → stability penalty per extra degree
+//   No heir found → large stability hit
+//   Contested succession (top-2 candidates within q(0.10)) → additional penalty
+import { computeInheritedRenown, MAX_KINSHIP_DEPTH, } from "./kinship.js";
+import { getRenownRecord } from "./renown.js";
+import { eventSeed } from "./sim/seeds.js";
+import { q, SCALE, clampQ, mulDiv } from "./units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Weight of own renown vs. inherited renown when computing claim strength. */
+export const CLAIM_OWN_RENOWN_WEIGHT_Q = q(0.70);
+export const CLAIM_INHERITED_RENOWN_WEIGHT_Q = q(0.30);
+/** Stability penalty per extra degree of kinship beyond 1 (direct child/parent). */
+export const STABILITY_DISTANT_HEIR_Q = q(0.05);
+/** Stability penalty when no heir is found. */
+export const STABILITY_NO_HEIR_Q = q(0.20);
+/** Additional penalty when the top two candidates are within this band. */
+export const CONTESTED_THRESHOLD_Q = q(0.10);
+export const STABILITY_CONTESTED_Q = q(0.05);
+/** Stability bonus when a direct child inherits with no contest. */
+export const STABILITY_CLEAN_SUCCESSION_Q = q(0.03);
+// ── Candidate discovery ───────────────────────────────────────────────────────
+/**
+ * Find all kin of `deceasedId` up to `maxDegree` and compute their claim strength.
+ * Candidates are sorted by claimStrength_Q descending, then kinshipDegree ascending.
+ */
+export function findSuccessionCandidates(lineage, deceasedId, renownRegistry, maxDegree = MAX_KINSHIP_DEPTH) {
+    // BFS over the family graph to collect all kin within maxDegree
+    const visited = new Set([deceasedId]);
+    const queue = [];
+    // Seed with immediate family
+    const deceasedNode = lineage.nodes.get(deceasedId);
+    if (!deceasedNode)
+        return [];
+    const seeds = [
+        ...deceasedNode.childIds,
+        ...deceasedNode.parentIds,
+        ...deceasedNode.partnerIds,
+    ];
+    for (const id of seeds) {
+        if (!visited.has(id)) {
+            visited.add(id);
+            queue.push({ id, degree: 1 });
+        }
+    }
+    const candidates = [];
+    while (queue.length > 0) {
+        const item = queue.shift();
+        if (item.degree > maxDegree)
+            continue;
+        // Compute claim
+        const record = getRenownRecord(renownRegistry, item.id);
+        const renown_Q = record.renown_Q;
+        const inheritedRenown = computeInheritedRenown(lineage, item.id, renownRegistry, 3);
+        candidates.push({
+            entityId: item.id,
+            kinshipDegree: item.degree,
+            renown_Q,
+            inheritedRenown_Q: inheritedRenown,
+            claimStrength_Q: 0, // filled in per-rule below
+        });
+        // Expand neighbours
+        const node = lineage.nodes.get(item.id);
+        if (!node)
+            continue;
+        for (const nbr of [...node.childIds, ...node.parentIds, ...node.partnerIds]) {
+            if (!visited.has(nbr)) {
+                visited.add(nbr);
+                queue.push({ id: nbr, degree: item.degree + 1 });
+            }
+        }
+    }
+    return candidates;
+}
+// ── Claim strength computation ─────────────────────────────────────────────────
+/** Compute `claimStrength_Q` for a candidate under the given rule. */
+function computeClaimStrength(candidate, rule, firstBornId) {
+    switch (rule) {
+        case "primogeniture":
+            // First-born (lowest entityId among children at degree 1) gets full claim;
+            // all others get proportionally less based on distance
+            if (candidate.entityId === firstBornId)
+                return SCALE.Q;
+            // Other children score by closeness only
+            return clampQ(SCALE.Q - candidate.kinshipDegree * STABILITY_DISTANT_HEIR_Q, 0, SCALE.Q);
+        case "renown_based":
+        case "election": {
+            // Weighted combination of own renown and inherited renown
+            const ownPart = mulDiv(candidate.renown_Q, CLAIM_OWN_RENOWN_WEIGHT_Q, SCALE.Q);
+            const inhPart = mulDiv(candidate.inheritedRenown_Q, CLAIM_INHERITED_RENOWN_WEIGHT_Q, SCALE.Q);
+            return clampQ(ownPart + inhPart, 0, SCALE.Q);
+        }
+    }
+}
+// ── Succession resolution ─────────────────────────────────────────────────────
+/**
+ * Resolve succession after `deceasedId` dies.
+ *
+ * @param lineage         Kinship registry (Phase 76).
+ * @param deceasedId      The entity whose position must be inherited.
+ * @param renownRegistry  Renown registry (Phase 75).
+ * @param rule            Succession rule to apply.
+ * @param worldSeed       For deterministic election roll.
+ * @param tick            Current simulation tick.
+ */
+export function resolveSuccession(lineage, deceasedId, renownRegistry, rule, worldSeed, tick) {
+    const maxDegree = rule.maxDegree ?? MAX_KINSHIP_DEPTH;
+    const ruleType = rule.type;
+    // Find candidates
+    const raw = findSuccessionCandidates(lineage, deceasedId, renownRegistry, maxDegree);
+    if (raw.length === 0) {
+        return {
+            heirId: null,
+            candidates: [],
+            rule: ruleType,
+            stabilityImpact_Q: -STABILITY_NO_HEIR_Q,
+        };
+    }
+    // Identify first-born (lowest entityId among direct children)
+    const directChildren = raw.filter(c => c.kinshipDegree === 1 &&
+        lineage.nodes.get(deceasedId)?.childIds.includes(c.entityId));
+    const firstBornId = directChildren.length > 0
+        ? Math.min(...directChildren.map(c => c.entityId))
+        : null;
+    // Fill claim strength
+    for (const c of raw) {
+        c.claimStrength_Q = computeClaimStrength(c, ruleType, firstBornId);
+    }
+    // Sort: claim strength desc, then kinshipDegree asc (closer kin breaks ties)
+    raw.sort((a, b) => b.claimStrength_Q - a.claimStrength_Q || a.kinshipDegree - b.kinshipDegree);
+    // Select heir
+    let heirId;
+    if (ruleType === "election" && raw.length > 1) {
+        // Renown-weighted lottery: for each candidate, roll eventSeed and weight by claimStrength
+        const totalClaim = raw.reduce((s, c) => s + c.claimStrength_Q, 0);
+        const roll = eventSeed(worldSeed, tick, deceasedId, 0, 77) % Math.max(totalClaim, 1);
+        let cumulative = 0;
+        let elected = raw[0].entityId;
+        for (const c of raw) {
+            cumulative += c.claimStrength_Q;
+            if (roll < cumulative) {
+                elected = c.entityId;
+                break;
+            }
+        }
+        heirId = elected;
+    }
+    else {
+        heirId = raw[0].entityId;
+    }
+    const winner = raw.find(c => c.entityId === heirId);
+    // Compute stability impact
+    let stability = 0;
+    // Bonus for clean direct succession
+    if (winner.kinshipDegree === 1 && raw.length === 1) {
+        stability += STABILITY_CLEAN_SUCCESSION_Q;
+    }
+    // Penalty for distant heir
+    if (winner.kinshipDegree > 1) {
+        stability -= (winner.kinshipDegree - 1) * STABILITY_DISTANT_HEIR_Q;
+    }
+    // Penalty for contested succession
+    if (raw.length >= 2) {
+        const gap = raw[0].claimStrength_Q - raw[1].claimStrength_Q;
+        if (gap < CONTESTED_THRESHOLD_Q) {
+            stability -= STABILITY_CONTESTED_Q;
+        }
+    }
+    return {
+        heirId,
+        candidates: raw,
+        rule: ruleType,
+        stabilityImpact_Q: clampQ(stability, -SCALE.Q, SCALE.Q),
+    };
+}
+// ── Polity integration ────────────────────────────────────────────────────────
+/**
+ * Apply a succession result to a polity.
+ * Adjusts `stabilityQ` by `result.stabilityImpact_Q`.
+ * Does NOT change the ruler field (Polity has no rulerId); callers update faction
+ * leadership separately if needed.
+ */
+export function applySuccessionToPolity(polity, result) {
+    polity.stabilityQ = clampQ(polity.stabilityQ + result.stabilityImpact_Q, 0, SCALE.Q);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@its-not-rocket-science/ananke",
-  "version": "0.1.16",
+  "version": "0.1.22",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",
@@ -58,6 +58,22 @@
     "./wasm-kernel": {
       "import": "./dist/src/wasm-kernel.js",
       "types": "./dist/src/wasm-kernel.d.ts"
+    },
+    "./narrative-prose": {
+      "import": "./dist/src/narrative-prose.js",
+      "types": "./dist/src/narrative-prose.d.ts"
+    },
+    "./renown": {
+      "import": "./dist/src/renown.js",
+      "types": "./dist/src/renown.d.ts"
+    },
+    "./kinship": {
+      "import": "./dist/src/kinship.js",
+      "types": "./dist/src/kinship.d.ts"
+    },
+    "./succession": {
+      "import": "./dist/src/succession.js",
+      "types": "./dist/src/succession.d.ts"
     }
   },
   "files": [
@@ -116,10 +132,12 @@
     "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",
+    "agent-server": "node dist/tools/agent-server.js",
     "benchmark-check": "node dist/tools/benchmark-check.js",
     "benchmark-check:strict": "node dist/tools/benchmark-check.js --threshold=0.10",
     "benchmark-check:update": "node dist/tools/benchmark-check.js --update-baseline",