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

package/dist/src/renown.d.ts

@@ -0,0 +1,82 @@
+import type { ChronicleEntry, Chronicle, ChronicleEventType } from "./chronicle.js";
+import type { NarrativeContext } from "./narrative-prose.js";
+import type { Q } from "./units.js";
+/** Lightweight reference to a significant chronicle event in an entity's legend. */
+export interface LegendEntry {
+    /** Unique chronicle entry id (reference to original ChronicleEntry). */
+    entryId: string;
+    tick: number;
+    eventType: ChronicleEventType;
+    /** Original significance score 0–100 from ChronicleEntry. */
+    significance: number;
+}
+/** Accumulated reputation record for a single entity. */
+export interface RenownRecord {
+    entityId: number;
+    /** Fame from positive deeds, [0, SCALE.Q]. */
+    renown_Q: Q;
+    /** Infamy from negative deeds, [0, SCALE.Q]. */
+    infamy_Q: Q;
+    /** All legend entries attributed to this entity, in insertion order. */
+    entries: LegendEntry[];
+}
+/** Flat registry of RenownRecords, one per entity. */
+export interface RenownRegistry {
+    records: Map<number, RenownRecord>;
+}
+/** Human-readable fame tier, derived from `renown_Q`. */
+export type RenownLabel = "unknown" | "noted" | "known" | "renowned" | "legendary" | "mythic";
+/** Human-readable infamy tier, derived from `infamy_Q`. */
+export type InfamyLabel = "innocent" | "suspect" | "notorious" | "infamous" | "reviled" | "condemned";
+/**
+ * Per-event renown/infamy contribution rate.
+ * A maximum-significance (100) event contributes `RENOWN_SCALE_Q` to the score.
+ * Scales linearly with `entry.significance`: `delta = round(sig * RENOWN_SCALE_Q / 100)`.
+ */
+export declare const RENOWN_SCALE_Q: Q;
+export declare function createRenownRegistry(): RenownRegistry;
+/**
+ * Return the RenownRecord for `entityId`, creating a zero-initialised record
+ * if one does not yet exist.
+ */
+export declare function getRenownRecord(registry: RenownRegistry, entityId: number): RenownRecord;
+/**
+ * Scan `chronicle` for entries involving `entityId` and update the entity's
+ * RenownRecord accordingly.
+ *
+ * Idempotent: already-seen entryIds (tracked by `record.entries`) are skipped,
+ * so this can be called on every game tick without double-counting.
+ *
+ * @param minSignificance  Only entries at or above this score are considered (default 50).
+ */
+export declare function updateRenownFromChronicle(registry: RenownRegistry, chronicle: Chronicle, entityId: number, minSignificance?: number): void;
+/** Map `renown_Q` to a human-readable fame tier. */
+export declare function getRenownLabel(renown_Q: Q): RenownLabel;
+/** Map `infamy_Q` to a human-readable infamy tier. */
+export declare function getInfamyLabel(infamy_Q: Q): InfamyLabel;
+/**
+ * Compute a signed faction standing delta based on entity renown and infamy.
+ *
+ * `allianceBias` controls how the faction weighs the two axes:
+ *   - q(1.0) = fully heroic faction: rewards renown, punishes infamy
+ *   - q(0.0) = fully criminal faction: rewards infamy, punishes renown
+ *   - q(0.5) = neutral: both axes equally weighted, they cancel
+ *
+ * Result is clamped to [-SCALE.Q, SCALE.Q].  The caller is responsible for
+ * adding this delta to the current standing and re-clamping to [0, SCALE.Q].
+ */
+export declare function deriveFactionStandingAdjustment(renown_Q: Q, infamy_Q: Q, allianceBias?: Q): Q;
+/**
+ * Return up to `n` legend entries sorted by significance (descending).
+ * Ties are broken by tick (descending — more recent wins).
+ */
+export declare function getTopLegendEntries(record: RenownRecord, n: number): LegendEntry[];
+/**
+ * Render an entity's top legend entries as tone-aware prose strings.
+ *
+ * Requires `entryMap` — a Map of `entryId → ChronicleEntry` for full entry data.
+ * Missing entries fall back to a bracketed placeholder.
+ *
+ * @param maxEntries  Maximum number of entries to render (default 5).
+ */
+export declare function renderLegendWithTone(record: RenownRecord, entryMap: Map<string, ChronicleEntry>, ctx: NarrativeContext, maxEntries?: number): string[];

package/dist/src/renown.js

@@ -0,0 +1,175 @@
+// src/renown.ts — Phase 75: Entity Renown & Legend Registry
+//
+// Tracks per-entity reputation derived from Chronicle events (Phase 45).
+// Provides renown/infamy scores, faction standing adjustments, and prose
+// legend rendering via the Phase 74 tone system.
+//
+// Design:
+//   - Additive, history-scoped: renown grows only from *new* chronicle entries.
+//   - Pure computation — no kernel changes, no new Entity fields.
+//   - Two orthogonal axes: renown (positive deeds) and infamy (negative deeds).
+//   - Faction standing adjustment: `deriveFactionStandingAdjustment` applies a
+//     signed bias so heroic factions reward renown and outlaw factions reward infamy.
+import { renderEntryWithTone } from "./narrative-prose.js";
+import { q, SCALE, clampQ } from "./units.js";
+// ── Event classification ───────────────────────────────────────────────────────
+/** Event types that add to `renown_Q` when the entity is the primary actor. */
+const RENOWN_EVENT_TYPES = new Set([
+    "legendary_deed",
+    "quest_completed",
+    "combat_victory",
+    "masterwork_crafted",
+    "rank_promotion",
+    "settlement_founded",
+    "first_contact",
+]);
+/** Event types that add to `infamy_Q` when the entity is the primary actor. */
+const INFAMY_EVENT_TYPES = new Set([
+    "relationship_betrayal",
+    "settlement_raided",
+    "settlement_destroyed",
+    "quest_failed",
+]);
+// ── Constants ─────────────────────────────────────────────────────────────────
+/**
+ * Per-event renown/infamy contribution rate.
+ * A maximum-significance (100) event contributes `RENOWN_SCALE_Q` to the score.
+ * Scales linearly with `entry.significance`: `delta = round(sig * RENOWN_SCALE_Q / 100)`.
+ */
+export const RENOWN_SCALE_Q = q(0.10);
+// ── Factory ───────────────────────────────────────────────────────────────────
+export function createRenownRegistry() {
+    return { records: new Map() };
+}
+// ── Record access ─────────────────────────────────────────────────────────────
+/**
+ * Return the RenownRecord for `entityId`, creating a zero-initialised record
+ * if one does not yet exist.
+ */
+export function getRenownRecord(registry, entityId) {
+    let record = registry.records.get(entityId);
+    if (!record) {
+        record = { entityId, renown_Q: 0, infamy_Q: 0, entries: [] };
+        registry.records.set(entityId, record);
+    }
+    return record;
+}
+// ── Chronicle integration ─────────────────────────────────────────────────────
+/**
+ * Scan `chronicle` for entries involving `entityId` and update the entity's
+ * RenownRecord accordingly.
+ *
+ * Idempotent: already-seen entryIds (tracked by `record.entries`) are skipped,
+ * so this can be called on every game tick without double-counting.
+ *
+ * @param minSignificance  Only entries at or above this score are considered (default 50).
+ */
+export function updateRenownFromChronicle(registry, chronicle, entityId, minSignificance = 50) {
+    const record = getRenownRecord(registry, entityId);
+    const known = new Set(record.entries.map(e => e.entryId));
+    for (const entry of chronicle.entries) {
+        if (entry.significance < minSignificance)
+            continue;
+        if (!entry.actors.includes(entityId))
+            continue;
+        if (known.has(entry.entryId))
+            continue;
+        // Record the entry
+        record.entries.push({
+            entryId: entry.entryId,
+            tick: entry.tick,
+            eventType: entry.eventType,
+            significance: entry.significance,
+        });
+        known.add(entry.entryId);
+        // Compute contribution: scale linearly with significance
+        const delta = Math.round(entry.significance * RENOWN_SCALE_Q / 100);
+        if (RENOWN_EVENT_TYPES.has(entry.eventType)) {
+            record.renown_Q = clampQ(record.renown_Q + delta, 0, SCALE.Q);
+        }
+        else if (INFAMY_EVENT_TYPES.has(entry.eventType)) {
+            record.infamy_Q = clampQ(record.infamy_Q + delta, 0, SCALE.Q);
+        }
+        // Neutral event types (births, settlements, rank promotions as target) count
+        // in `entries` but do not move either axis.
+    }
+}
+// ── Label functions ───────────────────────────────────────────────────────────
+/** Map `renown_Q` to a human-readable fame tier. */
+export function getRenownLabel(renown_Q) {
+    if (renown_Q >= q(0.90))
+        return "mythic";
+    if (renown_Q >= q(0.70))
+        return "legendary";
+    if (renown_Q >= q(0.50))
+        return "renowned";
+    if (renown_Q >= q(0.30))
+        return "known";
+    if (renown_Q >= q(0.10))
+        return "noted";
+    return "unknown";
+}
+/** Map `infamy_Q` to a human-readable infamy tier. */
+export function getInfamyLabel(infamy_Q) {
+    if (infamy_Q >= q(0.90))
+        return "condemned";
+    if (infamy_Q >= q(0.70))
+        return "reviled";
+    if (infamy_Q >= q(0.50))
+        return "infamous";
+    if (infamy_Q >= q(0.30))
+        return "notorious";
+    if (infamy_Q >= q(0.10))
+        return "suspect";
+    return "innocent";
+}
+// ── Faction standing adjustment ───────────────────────────────────────────────
+/**
+ * Compute a signed faction standing delta based on entity renown and infamy.
+ *
+ * `allianceBias` controls how the faction weighs the two axes:
+ *   - q(1.0) = fully heroic faction: rewards renown, punishes infamy
+ *   - q(0.0) = fully criminal faction: rewards infamy, punishes renown
+ *   - q(0.5) = neutral: both axes equally weighted, they cancel
+ *
+ * Result is clamped to [-SCALE.Q, SCALE.Q].  The caller is responsible for
+ * adding this delta to the current standing and re-clamping to [0, SCALE.Q].
+ */
+export function deriveFactionStandingAdjustment(renown_Q, infamy_Q, allianceBias = q(0.5)) {
+    // Heroic contribution: renown boosts, infamy hurts, scaled by allianceBias
+    const heroicBias = allianceBias;
+    const criminalBias = (SCALE.Q - allianceBias);
+    const renownBoost = Math.round(renown_Q * heroicBias / SCALE.Q);
+    const infamyBoost = Math.round(infamy_Q * criminalBias / SCALE.Q);
+    const renownPenalty = Math.round(renown_Q * criminalBias / SCALE.Q);
+    const infamyPenalty = Math.round(infamy_Q * heroicBias / SCALE.Q);
+    const net = (renownBoost + infamyBoost) - (renownPenalty + infamyPenalty);
+    return clampQ(net, -SCALE.Q, SCALE.Q);
+}
+// ── Legend entry queries ──────────────────────────────────────────────────────
+/**
+ * Return up to `n` legend entries sorted by significance (descending).
+ * Ties are broken by tick (descending — more recent wins).
+ */
+export function getTopLegendEntries(record, n) {
+    return [...record.entries]
+        .sort((a, b) => b.significance - a.significance || b.tick - a.tick)
+        .slice(0, n);
+}
+// ── Prose rendering ───────────────────────────────────────────────────────────
+/**
+ * Render an entity's top legend entries as tone-aware prose strings.
+ *
+ * Requires `entryMap` — a Map of `entryId → ChronicleEntry` for full entry data.
+ * Missing entries fall back to a bracketed placeholder.
+ *
+ * @param maxEntries  Maximum number of entries to render (default 5).
+ */
+export function renderLegendWithTone(record, entryMap, ctx, maxEntries = 5) {
+    return getTopLegendEntries(record, maxEntries).map(le => {
+        const entry = entryMap.get(le.entryId);
+        if (!entry)
+            return `[${le.eventType}] (tick ${le.tick})`;
+        return renderEntryWithTone(entry, ctx);
+    });
+}

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;