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

package/dist/src/narrative-prose.js

@@ -0,0 +1,313 @@
+// src/narrative-prose.ts — Phase 74: Simulation Trace → Narrative Prose
+//
+// Cultural-tone rendering layer over Phase 45 ChronicleEntry events.
+// Extends `narrative-render.ts` with tone-varied templates driven by
+// `CultureProfile` (Phase 71) and `MythArchetype` (Phase 66).
+//
+// Design:
+//   - 6 prose tones: neutral | heroic | tragic | martial | spiritual | mercantile
+//   - Tone-varied sentence variants for all 19 ChronicleEventTypes
+//   - `deriveNarrativeTone(culture)` maps dominant cultural values → tone
+//   - `{name}` / `{target}` / `{variable}` substitution from entry.variables
+//     + entity name map (replaces numeric actor IDs with names)
+//   - `mythArchetypeFrame(archetype)` appends a myth-aware closing phrase
+//   - Fully deterministic — no Math.random()
+import { getDominantValues } from "./culture.js";
+// ── Tone → ValueId mapping ────────────────────────────────────────────────────
+/** Maps cultural value ids to the prose tone they imply. */
+const VALUE_TONE_MAP = {
+    martial_virtue: "martial",
+    spiritual_devotion: "spiritual",
+    commerce: "mercantile",
+    honour: "heroic",
+    fatalism: "tragic",
+    // honour + kin_loyalty lean heroic; others default to neutral
+};
+const TEMPLATES = {
+    entity_death: {
+        neutral: "{name} died{cause_str}{location_str}.",
+        heroic: "{name} fell in glorious battle, their deeds forever etched in memory.",
+        tragic: "The world grew darker as {name} breathed their last{cause_str}.",
+        martial: "{name} was cut down{cause_str} — a warrior's end.",
+        spiritual: "The gods finally claimed {name}{cause_str}, as had long been ordained.",
+        mercantile: "{name}'s final accounts were settled; the ledgers closed for the last time.",
+    },
+    entity_birth: {
+        neutral: "{entityName} was born{parents_str}{settlement_str}.",
+        heroic: "Into the world came {entityName}, destined for greatness{settlement_str}.",
+        tragic: "{entityName} entered a world that would not be kind to them{settlement_str}.",
+        spiritual: "The heavens marked the arrival of {entityName}{settlement_str}.",
+        mercantile: "A new soul joined the household{settlement_str}: {entityName}.",
+        martial: "{entityName} was born{settlement_str} — another sword arm for the generations.",
+    },
+    relationship_formed: {
+        neutral: "{actorA} and {actorB} formed a {bondType}{context_str}.",
+        heroic: "{actorA} and {actorB} swore a bond of {bondType} — an alliance the ages would remember.",
+        tragic: "{actorA} and {actorB} formed a {bondType}{context_str}, not knowing what lay ahead.",
+        martial: "{actorA} and {actorB} forged a pact of {bondType}{context_str}.",
+        spiritual: "Fate bound {actorA} and {actorB} together in {bondType}{context_str}.",
+        mercantile: "{actorA} and {actorB} entered a {bondType} arrangement{context_str}.",
+    },
+    relationship_broken: {
+        neutral: "{actorA} and {actorB}'s {bondType} ended{reason_str}.",
+        heroic: "The bond of {bondType} between {actorA} and {actorB} shattered{reason_str}.",
+        tragic: "What once bound {actorA} and {actorB} crumbled to dust{reason_str}.",
+        martial: "{actorA} and {actorB} severed their {bondType}{reason_str}.",
+        spiritual: "The ties between {actorA} and {actorB} were cut by forces beyond them{reason_str}.",
+        mercantile: "The {bondType} between {actorA} and {actorB} was dissolved{reason_str}.",
+    },
+    relationship_betrayal: {
+        neutral: "{betrayer} betrayed {victim}{context_str}, destroying their trust forever.",
+        heroic: "{betrayer} shamed themselves by betraying {victim}{context_str} — a dishonour never forgotten.",
+        tragic: "{betrayer} betrayed {victim}{context_str}, and so the tragedy unfolded as it had to.",
+        martial: "{betrayer} struck {victim} in the back{context_str}. Such treachery is not forgotten on the field.",
+        spiritual: "{betrayer}'s betrayal of {victim}{context_str} brought down divine displeasure upon them.",
+        mercantile: "{betrayer} broke faith with {victim}{context_str}, voiding every contract between them.",
+    },
+    quest_completed: {
+        neutral: "{actorName} completed the quest \"{questName}\"{reward_str}.",
+        heroic: "{actorName} returned triumphant from \"{questName}\"{reward_str}, glory well earned.",
+        tragic: "{actorName} completed \"{questName}\"{reward_str}, though the cost had been great.",
+        martial: "{actorName} accomplished \"{questName}\" through force and discipline{reward_str}.",
+        spiritual: "Providence guided {actorName} to complete \"{questName}\"{reward_str}.",
+        mercantile: "{actorName} fulfilled the terms of \"{questName}\"{reward_str}.",
+    },
+    quest_failed: {
+        neutral: "{actorName} failed the quest \"{questName}\"{reason_str}.",
+        heroic: "{actorName} fell short of completing \"{questName}\"{reason_str}, but the attempt was not without honour.",
+        tragic: "\"{questName}\" defeated {actorName}{reason_str} — some burdens are too great to bear.",
+        martial: "{actorName} was bested in \"{questName}\"{reason_str}.",
+        spiritual: "The gods turned their face from {actorName} in \"{questName}\"{reason_str}.",
+        mercantile: "{actorName} failed to deliver on \"{questName}\"{reason_str}.",
+    },
+    quest_accepted: {
+        neutral: "{actorName} accepted the quest \"{questName}\"{giver_str}.",
+        heroic: "{actorName} took up the challenge of \"{questName}\"{giver_str}, determined to prevail.",
+        tragic: "{actorName} accepted \"{questName}\"{giver_str}, setting foot on a road with no easy return.",
+        martial: "{actorName} took the mission \"{questName}\"{giver_str}.",
+        spiritual: "{actorName} heeded the call of \"{questName}\"{giver_str}.",
+        mercantile: "{actorName} contracted for \"{questName}\"{giver_str}.",
+    },
+    settlement_founded: {
+        neutral: "The settlement of {settlementName} was founded{founder_str}.",
+        heroic: "{founder} raised the banner over {settlementName} — a new stronghold in a dangerous land.",
+        tragic: "The settlement of {settlementName} was founded{founder_str}, its future unknown.",
+        martial: "{founder_str_cap} planted the flag at {settlementName} and began to fortify.",
+        spiritual: "The gods blessed the founding of {settlementName}{founder_str}.",
+        mercantile: "{settlementName} was established{founder_str} as a hub of exchange.",
+    },
+    settlement_upgraded: {
+        neutral: "{settlementName} grew from {oldTier} to {newTier}.",
+        heroic: "{settlementName} rose to become a mighty {newTier}, a symbol of what courage can build.",
+        tragic: "{settlementName} expanded to {newTier} — growth that would bring its own dangers.",
+        martial: "{settlementName} was fortified to {newTier} against all threats.",
+        spiritual: "The gods smiled on {settlementName} as it advanced to {newTier}.",
+        mercantile: "{settlementName} prospered, growing from {oldTier} to {newTier}.",
+    },
+    settlement_raided: {
+        neutral: "{settlementName} was raided by {raiders}{damage_str}.",
+        heroic: "{settlementName} withstood a raid by {raiders}, the defenders holding firm despite {damage_str}.",
+        tragic: "{raiders} descended on {settlementName}, leaving only ruin{damage_str}.",
+        martial: "{raiders} struck {settlementName}{damage_str} — a bold, brutal assault.",
+        spiritual: "Dark forces in the guise of {raiders} visited ruin upon {settlementName}{damage_str}.",
+        mercantile: "{raiders} raided {settlementName}, disrupting trade and costing heavily{damage_str}.",
+    },
+    settlement_destroyed: {
+        neutral: "{settlementName} fell to {destroyer}, ending its {age} history.",
+        heroic: "{settlementName} fell to {destroyer} after {age} — but its people's deeds will not be forgotten.",
+        tragic: "And so {settlementName} fell, its {age} of history extinguished by {destroyer}.",
+        martial: "{destroyer} razed {settlementName} after {age} — the victors' right of conquest.",
+        spiritual: "The gods withdrew their protection; {settlementName} fell to {destroyer} after {age}.",
+        mercantile: "{settlementName} ceased to exist after {age}, its markets silenced by {destroyer}.",
+    },
+    facility_completed: {
+        neutral: "A new {facilityType} was completed in {settlementName}.",
+        heroic: "The {facilityType} of {settlementName} stood complete — testament to collective will.",
+        martial: "The {facilityType} of {settlementName} was finished, strengthening the garrison.",
+        spiritual: "The sacred {facilityType} in {settlementName} was consecrated at last.",
+        mercantile: "The {facilityType} in {settlementName} opened for business.",
+        tragic: "The {facilityType} of {settlementName} was finally completed, though at great cost.",
+    },
+    masterwork_crafted: {
+        neutral: "{crafterName} forged {itemName}, a masterwork of exceptional quality.",
+        heroic: "{crafterName}'s {itemName} was a masterwork worthy of legend.",
+        tragic: "{crafterName} poured a lifetime's sorrow into {itemName} — the finest work they would ever do.",
+        martial: "{crafterName} hammered {itemName} into existence — a weapon that would turn battles.",
+        spiritual: "The gods guided {crafterName}'s hands as they crafted {itemName}.",
+        mercantile: "{crafterName}'s {itemName} commanded the highest price ever seen in the markets.",
+    },
+    first_contact: {
+        neutral: "{factionA} made first contact with {factionB}{location_str}.",
+        heroic: "{factionA} met {factionB} for the first time{location_str} — a meeting that would shape history.",
+        tragic: "{factionA} encountered {factionB}{location_str}; neither would be unchanged.",
+        martial: "{factionA} and {factionB} faced each other across the boundary{location_str}.",
+        spiritual: "Fate decreed that {factionA} and {factionB} would meet{location_str}.",
+        mercantile: "{factionA} opened relations with {factionB}{location_str}, eyeing mutual profit.",
+    },
+    combat_victory: {
+        neutral: "{victor} defeated {defeated}{method_str}.",
+        heroic: "{victor} stood triumphant over {defeated}{method_str} — glory well earned.",
+        tragic: "{victor} defeated {defeated}{method_str}, though victory came at a price.",
+        martial: "{victor} crushed {defeated}{method_str} through strength and discipline.",
+        spiritual: "Providence guided {victor}'s hand against {defeated}{method_str}.",
+        mercantile: "{victor} secured a decisive advantage over {defeated}{method_str}.",
+    },
+    combat_defeat: {
+        neutral: "{defeated} was overcome by {victor}{location_str}.",
+        heroic: "{defeated} fell before {victor}{location_str}, but fought with honour to the last.",
+        tragic: "{defeated} was overwhelmed by {victor}{location_str} — the outcome never in doubt.",
+        martial: "{victor} broke {defeated}{location_str} — outmatched from the first blow.",
+        spiritual: "The gods turned from {defeated} in {location_str}; {victor} prevailed.",
+        mercantile: "{defeated} lost ground to {victor}{location_str}, the balance of power shifting.",
+    },
+    rank_promotion: {
+        neutral: "{actorName} rose to the rank of {newRank}{faction_str}.",
+        heroic: "{actorName} was honoured with the rank of {newRank}{faction_str}, their deeds recognised at last.",
+        tragic: "{actorName} was elevated to {newRank}{faction_str} — responsibility they had never sought.",
+        martial: "{actorName} earned the rank of {newRank}{faction_str} through proven valour.",
+        spiritual: "The order elevated {actorName} to {newRank}{faction_str}, guided by higher purpose.",
+        mercantile: "{actorName} was promoted to {newRank}{faction_str}, gaining both status and obligation.",
+    },
+    legendary_deed: {
+        neutral: "{hero} performed a legendary deed: {deedDescription}",
+        heroic: "{hero} carved their name into history: {deedDescription}",
+        tragic: "{hero} achieved the impossible through {deedDescription} — at what cost, only time would tell.",
+        martial: "{hero} proved their supremacy: {deedDescription}",
+        spiritual: "The heavens bore witness as {hero} accomplished {deedDescription}",
+        mercantile: "{hero}'s deed — {deedDescription} — would be spoken of in every market for years.",
+    },
+    tragic_event: {
+        neutral: "Tragedy struck when {description}",
+        heroic: "Even heroes could not prevent the tragedy: {description}",
+        tragic: "As it was always destined to be: {description}",
+        martial: "The hard truth of war bore down: {description}",
+        spiritual: "The gods decreed it so: {description}",
+        mercantile: "No ledger could account for such loss: {description}",
+    },
+};
+// ── Myth archetype frames ─────────────────────────────────────────────────────
+/** Returns a closing phrase appropriate to the myth archetype. */
+export function mythArchetypeFrame(archetype) {
+    switch (archetype) {
+        case "hero": return "as heroes are destined to do";
+        case "monster": return "fulfilling the dark prophecy";
+        case "trickster": return "through cunning that none could have predicted";
+        case "great_plague": return "as the ancient sickness had foretold";
+        case "divine_wrath": return "by the judgment of wrathful gods";
+        case "golden_age": return "in an age that songs shall long remember";
+    }
+}
+// ── Tone derivation ───────────────────────────────────────────────────────────
+/**
+ * Derive the best matching `ProseTone` from a `CultureProfile`.
+ *
+ * Uses the top-ranked cultural value; falls back to `"neutral"` for values
+ * without a direct tone mapping (hospitality, hierarchy, innovation, etc.).
+ */
+export function deriveNarrativeTone(culture) {
+    const dominant = getDominantValues(culture, 1);
+    const topValue = dominant[0]?.id;
+    if (!topValue)
+        return "neutral";
+    return VALUE_TONE_MAP[topValue] ?? "neutral";
+}
+// ── Context builder ───────────────────────────────────────────────────────────
+/**
+ * Create a `NarrativeContext` for a rendering pass.
+ *
+ * @param entityNames  Map of entity id → display name (numeric ids are looked up here).
+ * @param culture      Optional culture profile — used to derive tone automatically.
+ * @param myth         Optional myth — used to append archetype-framing suffix.
+ */
+export function createNarrativeContext(entityNames, culture, myth) {
+    const tone = culture ? deriveNarrativeTone(culture) : "neutral";
+    const ctx = { entityNames, tone };
+    if (myth)
+        ctx.mythFrame = mythArchetypeFrame(myth.archetype);
+    return ctx;
+}
+// ── Template substitution ─────────────────────────────────────────────────────
+/**
+ * Replace `{varName}` placeholders in a template string.
+ *
+ * Resolution order:
+ *   1. `{name}`   → display name of `actors[0]` from `ctx.entityNames`
+ *   2. `{target}` → display name of `actors[1]` from `ctx.entityNames`
+ *   3. All keys in `entry.variables`
+ *   4. Computed helpers: `{cause_str}`, `{location_str}`, etc.
+ *   5. Any remaining `{varName}` → removed (empty string)
+ */
+function applyTemplate(template, entry, ctx) {
+    const vars = entry.variables;
+    const actors = entry.actors;
+    const names = ctx.entityNames;
+    const actorName = (id) => names.get(id) ?? `entity ${id}`;
+    const primaryName = actors[0] != null ? actorName(actors[0]) : (String(vars["actorName"] ?? "Unknown"));
+    const targetName = actors[1] != null ? actorName(actors[1]) : (String(vars["target"] ?? "Unknown"));
+    // Computed helper strings (empty when the variable is absent)
+    const helpers = {
+        cause_str: vars["cause"] ? ` from ${vars["cause"]}` : "",
+        location_str: vars["location"] ? ` in ${vars["location"]}` : "",
+        parents_str: vars["parents"] ? ` to ${vars["parents"]}` : "",
+        settlement_str: vars["settlement"] ? ` in ${vars["settlement"]}` : "",
+        context_str: vars["context"] ? ` after ${vars["context"]}` : "",
+        reason_str: vars["reason"] ? ` due to ${vars["reason"]}` : "",
+        reward_str: vars["reward"] ? ` and received ${vars["reward"]}` : "",
+        giver_str: vars["giver"] ? ` from ${vars["giver"]}` : "",
+        founder_str: vars["founder"] ? ` by ${vars["founder"]}` : "",
+        founder_str_cap: vars["founder"] ? String(vars["founder"]) : "Settlers",
+        damage_str: vars["damage"] ? `, suffering ${vars["damage"]}` : "",
+        method_str: vars["method"] ? ` by ${vars["method"]}` : "",
+        faction_str: vars["faction"] ? ` in the ${vars["faction"]}` : "",
+    };
+    let result = template;
+    // Named actor substitutions
+    result = result.replace(/\{name\}/g, primaryName);
+    result = result.replace(/\{target\}/g, targetName);
+    // Computed helpers
+    for (const [k, v] of Object.entries(helpers)) {
+        result = result.replace(new RegExp(`\\{${k}\\}`, "g"), v);
+    }
+    // Raw variables from entry
+    for (const [k, v] of Object.entries(vars)) {
+        result = result.replace(new RegExp(`\\{${k}\\}`, "g"), String(v));
+    }
+    // Remove any unresolved placeholders
+    result = result.replace(/\{[^}]+\}/g, "");
+    return result;
+}
+// ── Public render API ─────────────────────────────────────────────────────────
+/**
+ * Render a single `ChronicleEntry` with cultural-tone awareness.
+ *
+ * Selects the tone variant for `entry.eventType`; falls back to `"neutral"` if
+ * the requested tone has no specific variant.  Appends `ctx.mythFrame` if set.
+ *
+ * Does NOT mutate `entry.rendered` — call `entry.rendered = renderEntryWithTone(...)`
+ * manually if caching is desired.
+ */
+export function renderEntryWithTone(entry, ctx) {
+    const toneVariants = TEMPLATES[entry.eventType];
+    const template = toneVariants?.[ctx.tone] ?? toneVariants?.["neutral"] ?? "";
+    if (!template) {
+        return `[${entry.eventType}] (tick ${entry.tick})`;
+    }
+    let prose = applyTemplate(template, entry, ctx);
+    if (ctx.mythFrame) {
+        // Append myth frame, replacing terminal period if present
+        prose = prose.replace(/\.$/, "") + `, ${ctx.mythFrame}.`;
+    }
+    return prose;
+}
+/**
+ * Render all entries in a `Chronicle` above `minSignificance` (default 50),
+ * returned in chronological order.
+ *
+ * Uses `renderEntryWithTone` for each entry.
+ */
+export function renderChronicleWithTone(chronicle, ctx, minSignificance = 50) {
+    return chronicle.entries
+        .filter(e => e.significance >= minSignificance)
+        .sort((a, b) => a.tick - b.tick)
+        .map(e => renderEntryWithTone(e, ctx));
+}

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/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;