@its-not-rocket-science/ananke 0.1.0

package/dist/src/narrative-render.js

@@ -0,0 +1,194 @@
+// src/narrative-render.ts — Phase 45: Emergent Story Generation — Narrative Rendering
+//
+// Template-based prose generation for chronicle entries and story arcs.
+/** Static templates for each event type. */
+const EVENT_TEMPLATES = {
+    entity_death: (v) => `${v.actorName} died${v.cause ? ` from ${v.cause}` : ""}${v.location ? ` in ${v.location}` : ""}.`,
+    entity_birth: (v) => `${v.entityName} was born${v.parents ? ` to ${v.parents}` : ""}${v.settlement ? ` in ${v.settlement}` : ""}.`,
+    relationship_formed: (v) => `${v.actorA} and ${v.actorB} formed a ${v.bondType || "relationship"}${v.context ? ` after ${v.context}` : ""}.`,
+    relationship_broken: (v) => `${v.actorA} and ${v.actorB}'s ${v.bondType || "relationship"} ended${v.reason ? ` due to ${v.reason}` : ""}.`,
+    relationship_betrayal: (v) => `${v.betrayer} betrayed ${v.victim}${v.context ? ` during ${v.context}` : ""}, destroying their trust forever.`,
+    quest_completed: (v) => `${v.actorName} completed the quest "${v.questName}"${v.reward ? ` and received ${v.reward}` : ""}.`,
+    quest_failed: (v) => `${v.actorName} failed the quest "${v.questName}"${v.reason ? `: ${v.reason}` : ""}.`,
+    quest_accepted: (v) => `${v.actorName} accepted the quest "${v.questName}"${v.giver ? ` from ${v.giver}` : ""}.`,
+    settlement_founded: (v) => `The settlement of ${v.settlementName} was founded${v.founder ? ` by ${v.founder}` : ""}.`,
+    settlement_upgraded: (v) => `${v.settlementName} grew from ${v.oldTier} to ${v.newTier}.`,
+    settlement_raided: (v) => `${v.settlementName} was raided by ${v.raiders}${v.damage ? `, suffering ${v.damage}` : ""}.`,
+    settlement_destroyed: (v) => `${v.settlementName} fell to ${v.destroyer}, ending its ${v.age} history.`,
+    facility_completed: (v) => `A new ${v.facilityType} was completed in ${v.settlementName}.`,
+    masterwork_crafted: (v) => `${v.crafterName} forged ${v.itemName}, a masterwork of exceptional quality.`,
+    first_contact: (v) => `${v.factionA} made first contact with ${v.factionB}${v.location ? ` at ${v.location}` : ""}.`,
+    combat_victory: (v) => `${v.victor} defeated ${v.defeated}${v.method ? ` by ${v.method}` : ""}.`,
+    combat_defeat: (v) => `${v.defeated} was overcome by ${v.victor}${v.location ? ` in ${v.location}` : ""}.`,
+    rank_promotion: (v) => `${v.actorName} rose to the rank of ${v.newRank}${v.faction ? ` in ${v.faction}` : ""}.`,
+    legendary_deed: (v) => `${v.hero} performed a legendary deed: ${v.deedDescription}`,
+    tragic_event: (v) => `Tragedy struck when ${v.description}`,
+};
+// ── Arc Summary Templates ─────────────────────────────────────────────────────
+/** Generate a summary for a story arc. */
+export function renderArcSummary(arc) {
+    const typeSummaries = {
+        rise_of_hero: (a) => `The hero's journey of ${actorNames(a)} spans ${entryCount(a)} pivotal moments.`,
+        tragic_fall: (a) => `${actorNames(a)}'s descent from grace, marked by betrayal and loss.`,
+        rivalry: (a) => `An enduring rivalry between ${actorNames(a)} unfolding across ${entryCount(a)} confrontations.`,
+        great_migration: (a) => `A mass migration that reshaped the region.`,
+        settlement_growth: (a) => `The rise of a settlement from humble beginnings to prosperity.`,
+        fallen_settlement: (a) => `The tragic fall of a once-great settlement.`,
+        legendary_craftsman: (a) => `${actorNames(a)}'s masterworks will be remembered for generations.`,
+        notorious_villain: (a) => `The terrifying rise of ${actorNames(a)}.`,
+        unlikely_friendship: (a) => `An unexpected bond formed between ${actorNames(a)} against all odds.`,
+        betrayal_and_redemption: (a) => `A tale of treachery, guilt, and ultimately, redemption for ${actorNames(a)}.`,
+    };
+    const renderer = typeSummaries[arc.arcType];
+    return renderer ? renderer(arc) : arc.description;
+}
+function actorNames(arc) {
+    return arc.primaryActors.join(" and ");
+}
+function entryCount(arc) {
+    return arc.entryIds.length;
+}
+// ── Entry Rendering ───────────────────────────────────────────────────────────
+/** Render a chronicle entry to prose. */
+export function renderEntry(entry) {
+    // Return cached render if available
+    if (entry.rendered)
+        return entry.rendered;
+    const templateFn = EVENT_TEMPLATES[entry.eventType];
+    if (!templateFn) {
+        return `Event: ${entry.eventType} (tick ${entry.tick})`;
+    }
+    return templateFn(entry.variables);
+}
+/** Render an entry with full context. */
+export function renderEntryVerbose(entry) {
+    const base = renderEntry(entry);
+    const significance = ` [Significance: ${entry.significance}/100]`;
+    const actors = entry.actors.length > 0 ? ` (Actors: ${entry.actors.join(", ")})` : "";
+    const settlement = entry.settlementId ? ` @${entry.settlementId}` : "";
+    return `${base}${significance}${actors}${settlement}`;
+}
+/** Render multiple entries to a narrative. */
+export function renderChronicle(entries, options = {}) {
+    const { showSignificance = false, showActors = false, showSettlements = false, minSignificance = 0, format = "prose", } = options;
+    const filtered = entries.filter(e => e.significance >= minSignificance);
+    if (filtered.length === 0) {
+        return "No events recorded.";
+    }
+    switch (format) {
+        case "compact":
+            return filtered.map(e => `[Tick ${e.tick}] ${renderEntry(e)}`).join("\n");
+        case "chronological":
+            return filtered
+                .map(e => {
+                let line = `Turn ${e.tick}: ${renderEntry(e)}`;
+                if (showSignificance)
+                    line += ` [${e.significance}]`;
+                if (showActors && e.actors.length)
+                    line += ` {${e.actors.join(",")}}`;
+                if (showSettlements && e.settlementId)
+                    line += ` @${e.settlementId}`;
+                return line;
+            })
+                .join("\n");
+        case "prose":
+        default: {
+            const paragraphs = [];
+            let currentParagraph = "";
+            for (const entry of filtered) {
+                const sentence = renderEntry(entry);
+                // Start new paragraph on significant events
+                if (entry.significance >= 70 && currentParagraph) {
+                    paragraphs.push(currentParagraph.trim());
+                    currentParagraph = sentence + " ";
+                }
+                else {
+                    currentParagraph += sentence + " ";
+                }
+            }
+            if (currentParagraph) {
+                paragraphs.push(currentParagraph.trim());
+            }
+            return paragraphs.join("\n\n");
+        }
+    }
+}
+// ── Arc Rendering ─────────────────────────────────────────────────────────────
+/** Render a complete story arc with its entries. */
+export function renderArcNarrative(arc, entryMap) {
+    const lines = [];
+    // Header
+    lines.push(`═══ ${arc.arcType.toUpperCase().replace(/_/g, " ")} ═══`);
+    lines.push(`Significance: ${arc.significance}/100 | Duration: Tick ${arc.startTick} to ${arc.endTick ?? "ongoing"}`);
+    lines.push("");
+    // Arc summary
+    lines.push(renderArcSummary(arc));
+    lines.push("");
+    // Entries in arc
+    lines.push("Key Events:");
+    for (const entryId of arc.entryIds) {
+        const entry = entryMap.get(entryId);
+        if (entry) {
+            lines.push(`  [${entry.tick}] ${renderEntry(entry)}`);
+        }
+    }
+    return lines.join("\n");
+}
+/** Render all arcs in a chronicle. */
+export function renderAllArcs(arcs, entryMap) {
+    if (arcs.length === 0) {
+        return "No story arcs detected.";
+    }
+    return arcs
+        .sort((a, b) => b.significance - a.significance)
+        .map(arc => renderArcNarrative(arc, entryMap))
+        .join("\n\n");
+}
+// ── Custom Templates ──────────────────────────────────────────────────────────
+/** Register a custom template for an event type. */
+export function registerTemplate(eventType, templateFn) {
+    EVENT_TEMPLATES[eventType] = templateFn;
+}
+/** Register multiple templates at once. */
+export function registerTemplates(templates) {
+    for (const [eventType, fn] of Object.entries(templates)) {
+        if (fn) {
+            registerTemplate(eventType, fn);
+        }
+    }
+}
+/** Generate a complete narrative from a set of arcs and entries. */
+export function generateNarrative(arcs, entries) {
+    const sortedArcs = arcs.sort((a, b) => b.significance - a.significance);
+    const topArc = sortedArcs[0];
+    // Collect key figures from all arcs
+    const keyFigures = [...new Set(arcs.flatMap(a => a.primaryActors))];
+    // Title based on top arc
+    const title = topArc
+        ? `The ${topArc.arcType.replace(/_/g, " ").replace(/\b\w/g, c => c.toUpperCase())}`
+        : "Chronicle of Events";
+    // Summary paragraph
+    const summaryParts = [];
+    if (topArc) {
+        summaryParts.push(renderArcSummary(topArc));
+    }
+    if (sortedArcs.length > 1) {
+        summaryParts.push(`${sortedArcs.length - 1} other story arcs intertwine with this narrative.`);
+    }
+    const summary = summaryParts.join(" ") || "A series of unconnected events.";
+    // Build full text
+    const entryMap = new Map(entries.map(e => [e.entryId, e]));
+    const fullText = renderAllArcs(sortedArcs, entryMap);
+    // Drama estimate based on arc significance and variety
+    const significanceSum = arcs.reduce((sum, a) => sum + a.significance, 0);
+    const varietyBonus = Math.min(20, arcs.length * 5);
+    const estimatedDrama = Math.min(100, significanceSum / Math.max(1, arcs.length) + varietyBonus);
+    return {
+        title,
+        summary,
+        fullText,
+        keyFigures,
+        keyEvents: topArc?.entryIds ?? [],
+        estimatedDrama,
+    };
+}

package/dist/src/narrative-stress.d.ts

@@ -0,0 +1,123 @@
+import type { WorldState } from "./sim/world.js";
+import type { CommandMap } from "./sim/commands.js";
+import type { KernelContext } from "./sim/context.js";
+import { type Q } from "./units.js";
+/**
+ * A function that returns the commands to issue on each tick.
+ * Receives the current WorldState so AI or scripted logic can react to it.
+ */
+export type CommandProvider = (world: WorldState) => CommandMap;
+/**
+ * A single expected story outcome that must become true within a tick window.
+ * A beat "passes" in a given run the first time its predicate returns true
+ * at any tick in [tickWindow[0], tickWindow[1]] (inclusive, post-step).
+ */
+export interface NarrativeBeat {
+    /** [firstTick, lastTick] inclusive range checked after each stepWorld call. */
+    tickWindow: [number, number];
+    /** Returns true when this beat's condition is satisfied. */
+    predicate: (world: WorldState) => boolean;
+    /** Human-readable label shown in reports. */
+    description: string;
+}
+/**
+ * A complete narrative scenario: world factory, command provider, and beats.
+ *
+ * Each trial overrides `world.seed` so the same setup runs deterministically
+ * across a range of seeds — no two trials share state.
+ */
+export interface NarrativeScenario {
+    name: string;
+    description?: string;
+    /** Returns a fresh WorldState.  `world.seed` is overridden per trial. */
+    setup: () => WorldState;
+    /** Supplies commands each tick (AI, scripted, or mixed). */
+    commands: CommandProvider;
+    /** All beats must pass for a run to count as a success. */
+    beats: NarrativeBeat[];
+    /** Maximum ticks per trial.  Default: 600 (30 s at 20 Hz). */
+    maxTicks?: number;
+}
+/** Per-beat aggregate across all trials. */
+export interface BeatResult {
+    description: string;
+    /** Fraction of runs where this beat was satisfied within its window. */
+    passRate: number;
+    /**
+     * Per-beat narrative push: `1 − passRate`.
+     * Identifies the bottleneck beat — the one that most resists the story.
+     */
+    beatPush: number;
+}
+/** Aggregate result of a full stress test run. */
+export interface StressTestResult {
+    scenarioName: string;
+    runsTotal: number;
+    /**
+     * Fraction of runs where ALL beats were satisfied.
+     * 1.0 = story happens every time; 0.0 = story never happens.
+     */
+    successRate: number;
+    /**
+     * Narrative push required to make the story happen: `1 − successRate`.
+     * 0.00 = no push needed (plausible);
+     * 1.00 = miracle required (extreme plot armour).
+     */
+    narrativePush: number;
+    /**
+     * Deus Ex score: `narrativePush × 10`, rounded to one decimal place.
+     * A 0–10 scale for quick human communication:
+     *   0.0–1.0 = plausible (no authorial help needed)
+     *   1.0–4.0 = light touch
+     *   4.0–7.0 = moderate intervention
+     *   7.0–9.0 = heavy plot armour
+     *   9.0–10.0 = miracle required
+     */
+    deusExScore: number;
+    /** Per-beat breakdown — identify which beat is the bottleneck. */
+    beatResults: BeatResult[];
+    /**
+     * Seeds that produced successful runs.
+     * Use these to replay and visually inspect a "canonical" version of the scene.
+     */
+    successSeeds: number[];
+}
+/** Consciousness threshold below which an entity is considered defeated. */
+export declare const DEFEATED_CONSCIOUSNESS: Q;
+/**
+ * Beat passes when entity `entityId` is dead or unconscious
+ * (consciousness ≤ DEFEATED_CONSCIOUSNESS).
+ */
+export declare function beatEntityDefeated(entityId: number): (world: WorldState) => boolean;
+/**
+ * Beat passes when entity `entityId` is alive and conscious
+ * (not dead, consciousness > DEFEATED_CONSCIOUSNESS).
+ */
+export declare function beatEntitySurvives(entityId: number): (world: WorldState) => boolean;
+/**
+ * Beat passes when ALL entities on `teamId` are defeated.
+ */
+export declare function beatTeamDefeated(teamId: number): (world: WorldState) => boolean;
+/**
+ * Beat passes when entity `entityId` shock exceeds `thresholdQ`.
+ * Useful for "hero takes a serious hit but survives" beats.
+ */
+export declare function beatEntityShockExceeds(entityId: number, thresholdQ: Q): (world: WorldState) => boolean;
+/**
+ * Beat passes when entity `entityId` fatigue exceeds `thresholdQ`.
+ */
+export declare function beatEntityFatigued(entityId: number, thresholdQ: Q): (world: WorldState) => boolean;
+/**
+ * Run `scenario` once per seed in `seeds`, checking each beat's predicate
+ * after every tick within its declared window.
+ *
+ * A run "succeeds" only when every beat passes at least once within its window.
+ * `successRate` is the fraction of successful runs; `narrativePush = 1 − successRate`.
+ */
+export declare function runNarrativeStressTest(scenario: NarrativeScenario, seeds: readonly number[], options?: {
+    ctx?: KernelContext;
+}): StressTestResult;
+/**
+ * Format a stress test result as a human-readable text report.
+ */
+export declare function formatStressTestReport(result: StressTestResult): string;

package/dist/src/narrative-stress.js

@@ -0,0 +1,183 @@
+// src/narrative-stress.ts — Phase 63: Narrative Stress Test
+//
+// Runs a scenario across many deterministic seeds and measures how probable
+// a sequence of expected story beats is.  The inverse of that probability is
+// the "narrative push" — the authorial effort required to make the story happen.
+//
+// Uses only existing infrastructure: stepWorld, makeRng/eventSeed, no new
+// simulation primitives required.
+import { stepWorld } from "./sim/kernel.js";
+import { q } from "./units.js";
+import { TUNING } from "./sim/tuning.js";
+import { TICK_HZ } from "./sim/tick.js";
+// ─── Constants ────────────────────────────────────────────────────────────────
+const DEFAULT_MAX_TICKS = 30 * TICK_HZ; // 30 s × 20 Hz = 600 ticks
+/** Consciousness threshold below which an entity is considered defeated. */
+export const DEFEATED_CONSCIOUSNESS = q(0.10);
+// ─── Beat predicate helpers ───────────────────────────────────────────────────
+/**
+ * Beat passes when entity `entityId` is dead or unconscious
+ * (consciousness ≤ DEFEATED_CONSCIOUSNESS).
+ */
+export function beatEntityDefeated(entityId) {
+    return (world) => {
+        const entity = world.entities.find(e => e.id === entityId);
+        if (!entity)
+            return false;
+        return entity.injury.dead || entity.injury.consciousness <= DEFEATED_CONSCIOUSNESS;
+    };
+}
+/**
+ * Beat passes when entity `entityId` is alive and conscious
+ * (not dead, consciousness > DEFEATED_CONSCIOUSNESS).
+ */
+export function beatEntitySurvives(entityId) {
+    return (world) => {
+        const entity = world.entities.find(e => e.id === entityId);
+        if (!entity)
+            return false;
+        return !entity.injury.dead && entity.injury.consciousness > DEFEATED_CONSCIOUSNESS;
+    };
+}
+/**
+ * Beat passes when ALL entities on `teamId` are defeated.
+ */
+export function beatTeamDefeated(teamId) {
+    return (world) => {
+        const team = world.entities.filter(e => e.teamId === teamId);
+        if (team.length === 0)
+            return false;
+        return team.every(e => e.injury.dead || e.injury.consciousness <= DEFEATED_CONSCIOUSNESS);
+    };
+}
+/**
+ * Beat passes when entity `entityId` shock exceeds `thresholdQ`.
+ * Useful for "hero takes a serious hit but survives" beats.
+ */
+export function beatEntityShockExceeds(entityId, thresholdQ) {
+    return (world) => {
+        const entity = world.entities.find(e => e.id === entityId);
+        if (!entity)
+            return false;
+        return entity.injury.shock > thresholdQ;
+    };
+}
+/**
+ * Beat passes when entity `entityId` fatigue exceeds `thresholdQ`.
+ */
+export function beatEntityFatigued(entityId, thresholdQ) {
+    return (world) => {
+        const entity = world.entities.find(e => e.id === entityId);
+        if (!entity)
+            return false;
+        return entity.energy.fatigue > thresholdQ;
+    };
+}
+// ─── Core runner ──────────────────────────────────────────────────────────────
+/**
+ * Run `scenario` once per seed in `seeds`, checking each beat's predicate
+ * after every tick within its declared window.
+ *
+ * A run "succeeds" only when every beat passes at least once within its window.
+ * `successRate` is the fraction of successful runs; `narrativePush = 1 − successRate`.
+ */
+export function runNarrativeStressTest(scenario, seeds, options) {
+    const maxTicks = scenario.maxTicks ?? DEFAULT_MAX_TICKS;
+    const ctx = {
+        tractionCoeff: q(1.0),
+        tuning: TUNING.tactical,
+        ...options?.ctx,
+    };
+    const nBeats = scenario.beats.length;
+    const beatPassCounts = new Array(nBeats).fill(0);
+    let successCount = 0;
+    const successSeeds = [];
+    for (const seed of seeds) {
+        const world = scenario.setup();
+        world.seed = seed;
+        const beatPassed = new Array(nBeats).fill(false);
+        let allPassed = false;
+        for (let t = 0; t < maxTicks; t++) {
+            const commands = scenario.commands(world);
+            stepWorld(world, commands, ctx);
+            const tick = world.tick;
+            for (let b = 0; b < nBeats; b++) {
+                if (beatPassed[b])
+                    continue;
+                const beat = scenario.beats[b];
+                if (tick >= beat.tickWindow[0] && tick <= beat.tickWindow[1]) {
+                    if (beat.predicate(world)) {
+                        beatPassed[b] = true;
+                    }
+                }
+            }
+            // Early exit: all beats have passed
+            allPassed = beatPassed.every(Boolean);
+            if (allPassed)
+                break;
+        }
+        for (let b = 0; b < nBeats; b++) {
+            if (beatPassed[b])
+                beatPassCounts[b]++;
+        }
+        if (allPassed) {
+            successCount++;
+            successSeeds.push(seed);
+        }
+    }
+    const runsTotal = seeds.length;
+    const successRate = runsTotal > 0 ? successCount / runsTotal : 0;
+    const narrativePush = runsTotal > 0
+        ? Math.round((1 - successRate) * 10000) / 10000
+        : 0;
+    const deusExScore = Math.round(narrativePush * 100) / 10; // 0–10, 1 d.p.
+    return {
+        scenarioName: scenario.name,
+        runsTotal,
+        successRate,
+        narrativePush,
+        deusExScore,
+        beatResults: scenario.beats.map((beat, b) => {
+            const passRate = runsTotal > 0 ? beatPassCounts[b] / runsTotal : 0;
+            return {
+                description: beat.description,
+                passRate,
+                beatPush: Math.round((1 - passRate) * 10000) / 10000,
+            };
+        }),
+        successSeeds,
+    };
+}
+// ─── Report formatter ─────────────────────────────────────────────────────────
+/**
+ * Format a stress test result as a human-readable text report.
+ */
+export function formatStressTestReport(result) {
+    const pct = (v) => `${(v * 100).toFixed(1)}%`;
+    const pushLabel = result.narrativePush < 0.10 ? "none — plausible" :
+        result.narrativePush < 0.40 ? "light" :
+            result.narrativePush < 0.70 ? "moderate" :
+                result.narrativePush < 0.90 ? "heavy" : "extreme — plot armour";
+    const lines = [
+        `Narrative Stress Test: ${result.scenarioName}`,
+        "─".repeat(52),
+        `Runs:            ${result.runsTotal}`,
+        `Success rate:    ${pct(result.successRate)}`,
+        `Narrative push:  ${result.narrativePush.toFixed(4)}  (${pushLabel})`,
+        `Deus Ex score:   ${result.deusExScore.toFixed(1)} / 10`,
+        "",
+        "Beat breakdown:",
+    ];
+    for (const b of result.beatResults) {
+        const icon = b.passRate >= 0.90 ? "✓" : b.passRate >= 0.50 ? "~" : "✗";
+        const pushStr = `[push ${b.beatPush.toFixed(2)}]`;
+        lines.push(`  ${icon} ${pct(b.passRate).padStart(6)}  ${pushStr}  ${b.description}`);
+    }
+    const shown = result.successSeeds.slice(0, 10);
+    if (shown.length > 0) {
+        const suffix = result.successSeeds.length > 10
+            ? ` … (${result.successSeeds.length} total)` : "";
+        lines.push("", `Success seeds: ${shown.join(", ")}${suffix}`);
+    }
+    return lines.join("\n");
+}

package/dist/src/narrative.d.ts

@@ -0,0 +1,44 @@
+import type { Q } from "./units.js";
+import type { WeaponDamageProfile } from "./equipment.js";
+import type { InjuryState } from "./sim/injury.js";
+import type { TraceEvent } from "./sim/trace.js";
+export interface NarrativeConfig {
+    /** How much detail to emit.
+     *  terse   — KO, Death, route/rally, fracture, blast, hits only
+     *  normal  — adds blocked/parried notes, misses, weapon bind, grapple start/break
+     *  verbose — adds grapple ticks, capability events, treatment events
+     */
+    verbosity: "terse" | "normal" | "verbose";
+    /** Display names keyed by entity id. Falls back to "combatant {id}".
+     *  Set an entity's name to "you" for second-person verb conjugation. */
+    nameMap?: Map<number, string>;
+    /** Damage profiles keyed by weapon id; enables verb selection for melee/ranged events. */
+    weaponProfiles?: Map<string, WeaponDamageProfile>;
+}
+/** Minimal entity summary needed for describeCombatOutcome. */
+export interface CombatantSummary {
+    id: number;
+    teamId: number;
+    injury: {
+        dead: boolean;
+        consciousness: Q;
+    };
+}
+/**
+ * Narrate a single trace event.
+ * Returns null for events that should be omitted at the current verbosity level.
+ */
+export declare function narrateEvent(ev: TraceEvent, cfg: NarrativeConfig): string | null;
+/**
+ * Convert a sequence of trace events into a list of narrative lines.
+ * Events that return null from narrateEvent are omitted.
+ */
+export declare function buildCombatLog(events: TraceEvent[], cfg: NarrativeConfig): string[];
+/**
+ * Summarise an entity's injury state as a short descriptive phrase.
+ */
+export declare function describeInjuries(injury: InjuryState): string;
+/**
+ * Produce a one-line outcome summary for a completed engagement.
+ */
+export declare function describeCombatOutcome(combatants: CombatantSummary[], tickCount?: number): string;