@its-not-rocket-science/ananke 0.1.0

package/dist/src/item-durability.d.ts

@@ -0,0 +1,69 @@
+import type { Q } from "./units.js";
+import type { ItemInstance } from "./inventory.js";
+/** Durability loss from parrying a heavy strike. */
+export declare const DURABILITY_LOSS_PARRY: Q;
+/** Durability loss from blocking with a weapon (scales with impact energy). */
+export declare const DURABILITY_LOSS_BLOCK_BASE: Q;
+/** Durability loss from armour absorbing damage (scales with absorbed energy). */
+export declare const DURABILITY_LOSS_ARMOUR_BASE: Q;
+/** Durability loss from normal weapon use (per strike). */
+export declare const DURABILITY_LOSS_STRIKE: Q;
+/** Threshold below which an item is considered "damaged" (visual/functional indicator). */
+export declare const DAMAGED_THRESHOLD_Q: Q;
+/** Threshold below which an item is "broken" (non-functional). */
+export declare const BROKEN_THRESHOLD_Q: Q;
+/** Check if item has durability tracking. */
+export declare function hasDurability(item: ItemInstance): boolean;
+/** Get current durability (returns 1.0 if item has no durability tracking). */
+export declare function getDurability(item: ItemInstance): Q;
+/** Check if item is damaged (below 50% durability). */
+export declare function isDamaged(item: ItemInstance): boolean;
+/** Check if item is broken (below 10% durability, non-functional). */
+export declare function isBroken(item: ItemInstance): boolean;
+/** Get durability-based effectiveness multiplier for weapons. */
+export declare function getWeaponEffectiveness(item: ItemInstance): Q;
+/** Get armour protection multiplier based on durability. */
+export declare function getArmourProtection(item: ItemInstance): Q;
+/** Apply durability loss to an item. */
+export declare function applyDurabilityLoss(item: ItemInstance, loss_Q: Q): void;
+/** Record wear from parrying an attack. */
+export declare function recordParryWear(item: ItemInstance, impactEnergy_J: number): void;
+/** Record wear from blocking with a weapon/shield. */
+export declare function recordBlockWear(item: ItemInstance, absorbedEnergy_J: number): void;
+/** Record wear from armour absorbing damage. */
+export declare function recordArmourWear(item: ItemInstance, absorbedEnergy_J: number): void;
+/** Record wear from normal weapon strike (hitting armour, flesh, etc.). */
+export declare function recordStrikeWear(item: ItemInstance, hitArmour: boolean): void;
+export interface RepairResult {
+    success: boolean;
+    durabilityRestored_Q: Q;
+    qualityLevel_Q: Q;
+    repairCost: RepairCost;
+    narrative: string;
+}
+export interface RepairCost {
+    /** Time required in seconds. */
+    time_s: number;
+    /** Material units consumed. */
+    materials: number;
+    /** Currency cost if using a repair service. */
+    currency?: number;
+}
+/** Calculate repair parameters based on crafter skill and item condition. */
+export declare function calculateRepairNeed(item: ItemInstance): {
+    missingDurability_Q: Q;
+    baseTime_s: number;
+    baseMaterials: number;
+};
+/**
+ * Resolve a repair attempt.
+ * @param item The item to repair
+ * @param crafterCognitionQ The crafter's cognition.logicalMath (for technical skill)
+ * @param toolQuality_Q Quality of tools being used (0-1)
+ * @param seed RNG seed for determinism
+ */
+export declare function resolveRepair(item: ItemInstance, crafterCognitionQ: Q, toolQuality_Q: Q, seed: number): RepairResult;
+/** Quick repair with no skill check (field repair). */
+export declare function fieldRepair(item: ItemInstance): RepairResult;
+/** Calculate item value based on durability and modifications. */
+export declare function calculateItemValue(baseValue: number, item: ItemInstance): number;

package/dist/src/item-durability.js

@@ -0,0 +1,308 @@
+// src/item-durability.ts — Phase 43: Item Durability & Repair
+//
+// Wear tracking for weapons and armour, with repair mechanics integrated
+// with the competence system.
+import { q, clampQ, SCALE, mulDiv } from "./units.js";
+import { applyItemMod } from "./inventory.js";
+// ── Durability Constants ──────────────────────────────────────────────────────
+/** Durability loss from parrying a heavy strike. */
+export const DURABILITY_LOSS_PARRY = q(0.02);
+/** Durability loss from blocking with a weapon (scales with impact energy). */
+export const DURABILITY_LOSS_BLOCK_BASE = q(0.03);
+/** Durability loss from armour absorbing damage (scales with absorbed energy). */
+export const DURABILITY_LOSS_ARMOUR_BASE = q(0.04);
+/** Durability loss from normal weapon use (per strike). */
+export const DURABILITY_LOSS_STRIKE = q(0.005);
+/** Threshold below which an item is considered "damaged" (visual/functional indicator). */
+export const DAMAGED_THRESHOLD_Q = q(0.50);
+/** Threshold below which an item is "broken" (non-functional). */
+export const BROKEN_THRESHOLD_Q = q(0.10);
+// ── Durability Queries ─────────────────────────────────────────────────────────
+/** Check if item has durability tracking. */
+export function hasDurability(item) {
+    return item.durability_Q !== undefined;
+}
+/** Get current durability (returns 1.0 if item has no durability tracking). */
+export function getDurability(item) {
+    return item.durability_Q ?? SCALE.Q;
+}
+/** Check if item is damaged (below 50% durability). */
+export function isDamaged(item) {
+    if (!hasDurability(item))
+        return false;
+    return (item.durability_Q ?? SCALE.Q) < DAMAGED_THRESHOLD_Q;
+}
+/** Check if item is broken (below 10% durability, non-functional). */
+export function isBroken(item) {
+    if (!hasDurability(item))
+        return false;
+    return (item.durability_Q ?? SCALE.Q) < BROKEN_THRESHOLD_Q;
+}
+/** Get durability-based effectiveness multiplier for weapons. */
+export function getWeaponEffectiveness(item) {
+    if (!hasDurability(item))
+        return SCALE.Q;
+    const d = item.durability_Q ?? SCALE.Q;
+    // Broken weapons deal minimal damage (10%)
+    if (d < BROKEN_THRESHOLD_Q) {
+        return q(0.10);
+    }
+    // Damaged weapons deal reduced damage (50-100%)
+    if (d < DAMAGED_THRESHOLD_Q) {
+        // Linear interpolation from 50% at broken threshold to 100% at damaged threshold
+        const t = (d - BROKEN_THRESHOLD_Q) / (DAMAGED_THRESHOLD_Q - BROKEN_THRESHOLD_Q);
+        return Math.round(q(0.50) + t * q(0.50));
+    }
+    // Pristine to damaged: full effectiveness
+    return SCALE.Q;
+}
+/** Get armour protection multiplier based on durability. */
+export function getArmourProtection(item) {
+    if (!hasDurability(item))
+        return SCALE.Q;
+    const d = item.durability_Q ?? SCALE.Q;
+    // Broken armour provides no protection
+    if (d < BROKEN_THRESHOLD_Q) {
+        return q(0);
+    }
+    // Damaged armour provides partial protection
+    if (d < DAMAGED_THRESHOLD_Q) {
+        // Linear from 25% at broken to 100% at damaged threshold
+        const t = (d - BROKEN_THRESHOLD_Q) / (DAMAGED_THRESHOLD_Q - BROKEN_THRESHOLD_Q);
+        return Math.round(q(0.25) + t * q(0.75));
+    }
+    return SCALE.Q;
+}
+// ── Durability Modifications ───────────────────────────────────────────────────
+/** Apply durability loss to an item. */
+export function applyDurabilityLoss(item, loss_Q) {
+    if (!hasDurability(item))
+        return;
+    item.durability_Q = Math.max(0, (item.durability_Q ?? SCALE.Q) - loss_Q);
+    // Auto-apply "damaged" mod when crossing threshold
+    if (item.durability_Q < DAMAGED_THRESHOLD_Q && item.durability_Q >= BROKEN_THRESHOLD_Q) {
+        if (!item.modifications?.some((m) => m.type === "damaged")) {
+            applyItemMod(item, {
+                type: "damaged",
+                name: "Damaged",
+                statMultipliers: {
+                    damageMul: q(0.80),
+                    valueMul: q(0.50),
+                },
+            });
+        }
+    }
+}
+/** Record wear from parrying an attack. */
+export function recordParryWear(item, impactEnergy_J) {
+    if (!hasDurability(item))
+        return;
+    // Scale durability loss by impact energy (larger impacts = more wear)
+    // Base: ~100J impact causes base loss, scale linearly
+    const energyScale = Math.min(3.0, impactEnergy_J / 100);
+    const loss = Math.round(DURABILITY_LOSS_PARRY * energyScale);
+    applyDurabilityLoss(item, loss);
+}
+/** Record wear from blocking with a weapon/shield. */
+export function recordBlockWear(item, absorbedEnergy_J) {
+    if (!hasDurability(item))
+        return;
+    // Blocking causes more wear than parrying
+    const energyScale = Math.min(4.0, absorbedEnergy_J / 80);
+    const loss = Math.round(DURABILITY_LOSS_BLOCK_BASE * energyScale);
+    applyDurabilityLoss(item, loss);
+}
+/** Record wear from armour absorbing damage. */
+export function recordArmourWear(item, absorbedEnergy_J) {
+    if (!hasDurability(item))
+        return;
+    // Armour takes significant wear from absorption
+    const energyScale = Math.min(5.0, absorbedEnergy_J / 50);
+    const loss = Math.round(DURABILITY_LOSS_ARMOUR_BASE * energyScale);
+    applyDurabilityLoss(item, loss);
+}
+/** Record wear from normal weapon strike (hitting armour, flesh, etc.). */
+export function recordStrikeWear(item, hitArmour) {
+    if (!hasDurability(item))
+        return;
+    // Striking armour causes more wear than striking flesh
+    const multiplier = hitArmour ? 2.0 : 1.0;
+    const loss = Math.round(DURABILITY_LOSS_STRIKE * multiplier);
+    applyDurabilityLoss(item, loss);
+}
+/** Calculate repair parameters based on crafter skill and item condition. */
+export function calculateRepairNeed(item) {
+    if (!hasDurability(item)) {
+        return { missingDurability_Q: q(0), baseTime_s: 0, baseMaterials: 0 };
+    }
+    const current = item.durability_Q ?? SCALE.Q;
+    const missing = (SCALE.Q - current);
+    // Base repair time scales with damage severity
+    // Minor repair: 5 minutes, Major repair: 30 minutes, Restoration: 2 hours
+    let baseTime_s = 300; // 5 minutes
+    if (current < BROKEN_THRESHOLD_Q) {
+        baseTime_s = 7200; // 2 hours for broken items
+    }
+    else if (current < DAMAGED_THRESHOLD_Q) {
+        baseTime_s = 1800; // 30 minutes for damaged items
+    }
+    // Materials scale with missing durability
+    const baseMaterials = Math.ceil(missing / q(0.10));
+    return {
+        missingDurability_Q: missing,
+        baseTime_s,
+        baseMaterials,
+    };
+}
+/**
+ * Resolve a repair attempt.
+ * @param item The item to repair
+ * @param crafterCognitionQ The crafter's cognition.logicalMath (for technical skill)
+ * @param toolQuality_Q Quality of tools being used (0-1)
+ * @param seed RNG seed for determinism
+ */
+export function resolveRepair(item, crafterCognitionQ, toolQuality_Q, seed) {
+    if (!hasDurability(item)) {
+        return {
+            success: false,
+            durabilityRestored_Q: q(0),
+            qualityLevel_Q: q(0),
+            repairCost: { time_s: 0, materials: 0 },
+            narrative: "This item cannot be repaired.",
+        };
+    }
+    const need = calculateRepairNeed(item);
+    if (need.missingDurability_Q <= 0) {
+        return {
+            success: true,
+            durabilityRestored_Q: q(0),
+            qualityLevel_Q: SCALE.Q,
+            repairCost: { time_s: 0, materials: 0 },
+            narrative: "Item is already in perfect condition.",
+        };
+    }
+    // Quality of repair depends on skill and tools
+    // Base quality from skill (logicalMath represents technical competence)
+    const skillBonus = mulDiv(crafterCognitionQ, q(0.30), SCALE.Q);
+    const toolBonus = mulDiv(toolQuality_Q, q(0.20), SCALE.Q);
+    // Deterministic quality roll using seed
+    const qualityLevel_Q = clampQ((q(0.50) + skillBonus + toolBonus), q(0.30), SCALE.Q);
+    // Calculate actual durability restored
+    // Poor quality repairs restore less and may reduce max durability
+    const restoreRatio = 0.5 + (qualityLevel_Q / SCALE.Q) * 0.5;
+    const durabilityRestored_Q = Math.round(need.missingDurability_Q * restoreRatio);
+    // Calculate actual costs (better skill = more efficient)
+    const efficiencyMul = q(0.70) + mulDiv(crafterCognitionQ, q(0.30), SCALE.Q);
+    const time_s = Math.round(need.baseTime_s * (SCALE.Q / efficiencyMul));
+    const materials = Math.max(1, Math.round(need.baseMaterials * (SCALE.Q / efficiencyMul)));
+    // Apply repair
+    const newDurability = Math.min(SCALE.Q, (item.durability_Q ?? 0) + durabilityRestored_Q);
+    item.durability_Q = newDurability;
+    // Remove "damaged" mod if repaired above threshold
+    if (item.durability_Q >= DAMAGED_THRESHOLD_Q && item.modifications) {
+        const damagedIdx = item.modifications.findIndex((m) => m.type === "damaged");
+        if (damagedIdx >= 0) {
+            item.modifications.splice(damagedIdx, 1);
+        }
+    }
+    // Add "masterwork" mod for exceptional repairs
+    if (qualityLevel_Q > q(0.90) && !item.modifications?.some((m) => m.type === "masterwork")) {
+        applyItemMod(item, {
+            type: "masterwork",
+            name: "Masterwork",
+            statMultipliers: {
+                durabilityMul: q(1.10),
+                valueMul: q(1.25),
+            },
+        });
+    }
+    // Generate narrative
+    let narrative = "Repair completed.";
+    if (qualityLevel_Q > q(0.85)) {
+        narrative = "Excellent repair. The item looks as good as new.";
+    }
+    else if (qualityLevel_Q > q(0.60)) {
+        narrative = "Good repair. The item is serviceable again.";
+    }
+    else if (qualityLevel_Q > q(0.40)) {
+        narrative = "Basic repair. The item functions but shows wear.";
+    }
+    else {
+        narrative = "Poor repair. The item works but may not hold up long.";
+    }
+    return {
+        success: true,
+        durabilityRestored_Q,
+        qualityLevel_Q,
+        repairCost: { time_s, materials },
+        narrative,
+    };
+}
+/** Quick repair with no skill check (field repair). */
+export function fieldRepair(item) {
+    if (!hasDurability(item)) {
+        return {
+            success: false,
+            durabilityRestored_Q: q(0),
+            qualityLevel_Q: q(0),
+            repairCost: { time_s: 0, materials: 0 },
+            narrative: "Cannot field repair this item.",
+        };
+    }
+    const current = item.durability_Q ?? q(0);
+    const maxRestore = mulDiv(SCALE.Q - current, q(0.30), SCALE.Q); // Max 30% restore in field
+    if (maxRestore <= 0) {
+        return {
+            success: true,
+            durabilityRestored_Q: q(0),
+            qualityLevel_Q: SCALE.Q,
+            repairCost: { time_s: 0, materials: 0 },
+            narrative: "No repair needed.",
+        };
+    }
+    item.durability_Q = (current + maxRestore);
+    // Field repairs add temporary "damaged" mod to indicate suboptimal fix
+    if (!item.modifications?.some((m) => m.type === "damaged")) {
+        applyItemMod(item, {
+            type: "damaged",
+            name: "Field Repaired",
+            statMultipliers: {
+                valueMul: q(0.80),
+            },
+        });
+    }
+    return {
+        success: true,
+        durabilityRestored_Q: maxRestore,
+        qualityLevel_Q: q(0.40),
+        repairCost: { time_s: 300, materials: 1 }, // 5 minutes, minimal materials
+        narrative: "Field repair complete. Temporary fix, needs proper repair soon.",
+    };
+}
+// ── Value Calculation ─────────────────────────────────────────────────────────
+/** Calculate item value based on durability and modifications. */
+export function calculateItemValue(baseValue, item) {
+    let multiplier = 1.0;
+    // Durability factor
+    if (hasDurability(item)) {
+        const d = item.durability_Q ?? SCALE.Q;
+        if (d < BROKEN_THRESHOLD_Q) {
+            multiplier *= 0.1; // 10% for broken
+        }
+        else if (d < DAMAGED_THRESHOLD_Q) {
+            multiplier *= 0.5; // 50% for damaged
+        }
+        else {
+            multiplier *= d / SCALE.Q; // Linear for good condition
+        }
+    }
+    // Modification factors
+    if (item.modifications) {
+        for (const mod of item.modifications) {
+            if (mod.statMultipliers?.valueMul) {
+                multiplier *= mod.statMultipliers.valueMul / SCALE.Q;
+            }
+        }
+    }
+    return Math.round(baseValue * multiplier);
+}

package/dist/src/legend.d.ts

@@ -0,0 +1,97 @@
+import type { Q } from "./units.js";
+import type { Chronicle, StoryArcType } from "./chronicle.js";
+/** How an entity is perceived in living memory. */
+export type LegendReputation = "legendary" | "heroic" | "notorious" | "forgotten";
+/** A legend crystallised from chronicle entries. */
+export interface Legend {
+    legendId: string;
+    /** Entity the legend is about. */
+    subjectId: number;
+    /** Display name frozen at legend creation. */
+    subjectName: string;
+    reputation: LegendReputation;
+    /**
+     * How widely known this legend is (0..1).
+     * q(1.0) = universally known; q(0.10) = forgotten by most.
+     * Decays over time via stepLegendFame.
+     */
+    fame_Q: Q;
+    /**
+     * Thematic tags derived from source events/arcs.
+     * Examples: "warrior", "craftsman", "hero", "villain", "legendary_deed".
+     */
+    tags: string[];
+    /** Chronicle entry IDs that built this legend. */
+    sourceEntryIds: string[];
+    /** Story arc types present in source chronicle. */
+    sourceArcTypes: StoryArcType[];
+    /** Tick when this legend was created. */
+    createdAtTick: number;
+    /** Optional lore text for display. */
+    lore?: string | undefined;
+}
+/** Modifiers that a legend applies to NPC interactions. */
+export interface LegendEffect {
+    /** Bonus to persuasion probability (heroic / legendary). */
+    persuasionBonus_Q: Q;
+    /** Bonus to intimidation probability (notorious / legendary). */
+    intimidationBonus_Q: Q;
+    /** Fear delta applied to NPCs who know a notorious / legendary figure. */
+    fearBonus_Q: Q;
+    /** Ally morale bonus from fighting alongside / for a legend (heroic / legendary). */
+    moraleBonus_Q: Q;
+}
+/** Registry of all legends in a world. */
+export interface LegendRegistry {
+    legends: Map<string, Legend>;
+    /** Index: subjectId → Set of legendIds */
+    bySubject: Map<number, Set<string>>;
+}
+/** Minimum significance score for a chronicle entry to contribute to a legend. */
+export declare const LEGEND_MIN_SIGNIFICANCE = 60;
+/**
+ * Promote chronicle entries above `minSignificance` into a Legend.
+ *
+ * Returns `undefined` if no qualifying entries exist.
+ * Considers only entries where `subjectId` appears in the actors array.
+ */
+export declare function createLegendFromChronicle(chronicle: Chronicle, subjectId: number, subjectName: string, minSignificance?: number): Legend | undefined;
+/** Create a new empty legend registry. */
+export declare function createLegendRegistry(): LegendRegistry;
+/** Register a legend in the registry. Overwrites any existing legend with the same ID. */
+export declare function registerLegend(registry: LegendRegistry, legend: Legend): void;
+/** Get all legends about a specific entity. */
+export declare function getLegendsBySubject(registry: LegendRegistry, subjectId: number): Legend[];
+/** Derive NPC-behavior modifiers from a legend. */
+export declare function getLegendEffect(legend: Legend): LegendEffect;
+/**
+ * Determine whether an NPC "knows" a legend.
+ *
+ * Deterministic: same (legend, npcId, worldSeed, tick) → same result.
+ * Probability = `legend.fame_Q / SCALE.Q`.
+ */
+export declare function npcKnowsLegend(legend: Legend, npcId: number, worldSeed: number, tick: number): boolean;
+/**
+ * Aggregate legend effects for initiatorId, filtered by what targetId (NPC) knows.
+ *
+ * Called before dialogue resolution to get bonus Q values that shift
+ * persuasion/intimidation/fear probabilities.
+ */
+export declare function applyLegendToDialogueContext(initiatorId: number, targetId: number, registry: LegendRegistry, worldSeed: number, tick: number): {
+    persuasionBonus_Q: Q;
+    intimidationBonus_Q: Q;
+    fearBonus_Q: Q;
+};
+/**
+ * Decay fame on all registered legends over `deltaTicks` time.
+ *
+ * - "legendary" reputation has a hard floor at q(0.50).
+ * - All other reputations decay freely.
+ * - Legends whose fame_Q falls below FORGOTTEN_FAME_THRESHOLD are reclassified as "forgotten".
+ * - fame_Q never goes below 0.
+ */
+export declare function stepLegendFame(registry: LegendRegistry, deltaTicks: number): void;
+/** Serialize legend registry to JSON-friendly object. */
+export declare function serializeLegendRegistry(registry: LegendRegistry): unknown;
+/** Deserialize legend registry. */
+export declare function deserializeLegendRegistry(data: unknown): LegendRegistry;