@its-not-rocket-science/ananke 0.1.0

package/dist/src/competence/naturalist.js

@@ -0,0 +1,187 @@
+// src/competence/naturalist.ts — Phase 35: Naturalist Intelligence & Animal Handling
+//
+// Naturalist intelligence governs pattern recognition in living organisms:
+//   - Tracking: following quarry via environmental signs
+//   - Foraging: finding edible/medicinal plants, avoiding misidentification
+//   - Taming: building trust with animals across species boundaries
+//
+// No kernel import — pure resolution module.
+import { SCALE, q, clampQ, qMul, mulDiv } from "../units.js";
+import { makeRng } from "../rng.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Base track visibility range in metres at naturalist q(0.50), ideal conditions. */
+const BASE_TRACK_RANGE_m = 100;
+/** Age degradation: track freshness multiplier (seconds). */
+const AGE_MUL = {
+    ideal: { decayPerHour: 0.05, floor: q(0.80) },
+    rain: { decayPerHour: 0.25, floor: q(0.30) },
+    urban: { decayPerHour: 0.15, floor: q(0.40) },
+    deep_water: { decayPerHour: 0.50, floor: q(0.10) },
+    forest: { decayPerHour: 0.10, floor: q(0.50) }, // leaves/debris preserve tracks moderately
+};
+/** Species difficulty multiplier for tracking (default q(1.0)). */
+const SPECIES_TRACK_MUL = {
+    human: q(1.00),
+    elf: q(1.10),
+    dwarf: q(0.90),
+    halfling: q(0.85),
+    orc: q(1.05),
+    ogre: q(1.20),
+    goblin: q(0.80),
+    troll: q(1.30),
+    dragon: q(0.70), // rare, distinctive scent
+    wolf: q(1.15),
+    deer: q(1.10),
+    bear: q(1.25),
+};
+/** Species affinity bonus for tracking known species. */
+const SPECIES_AFFINITY_BONUS = q(0.15);
+/** Biome yield multipliers (base items per hour at naturalist q(0.50)). */
+const BIOME_YIELD_BASE = {
+    forest: 3.0,
+    plains: 2.0,
+    desert: 0.5,
+    swamp: 2.5,
+    mountain: 1.0,
+};
+/** Season multipliers affecting foraging yield. */
+const SEASON_MUL = {
+    spring: q(1.20),
+    summer: q(1.00),
+    autumn: q(0.90),
+    winter: q(0.40),
+};
+/** Threshold for reliable tracking confidence. */
+const TRACKING_CONFIDENCE_THRESHOLD = q(0.60);
+/** Trust threshold for fully tamed animal. */
+const FULLY_TAMED_THRESHOLD = q(0.90);
+// ── Helpers ───────────────────────────────────────────────────────────────────
+/**
+ * Get entity's species affinity list (for tracking/taming bonuses).
+ * Currently derived from species id in a simplified manner.
+ */
+function getSpeciesAffinity(entity) {
+    // Simplified: could be expanded with a proper affinity system
+    const baseAffinity = [];
+    // Add natural affinities based on archetype patterns
+    if (entity.attributes.cognition?.naturalist ?? 0 > q(0.60)) {
+        baseAffinity.push("wolf", "deer", "bear"); // high naturalist = forest affinity
+    }
+    return baseAffinity;
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Resolve a tracking attempt.
+ *
+ * Formula:
+ *   confidence_Q = naturalist × ageMul × terrainMul × speciesMul
+ *   If quarrySpecies in entity's speciesAffinity: +q(0.15)
+ *   trackRange_m = baseRange × confidence_Q (with floor at naturalist × 10m)
+ *
+ * @param entity - The tracker; uses `cognition.naturalist`.
+ * @param spec   - Tracking specification.
+ * @param _seed  - Reserved for future variance; currently unused.
+ */
+export function resolveTracking(entity, spec, _seed) {
+    const naturalist = (entity.attributes.cognition?.naturalist ?? q(0.50));
+    // Age multiplier: degrades over time, with terrain-specific floor
+    const hoursOld = spec.trackAge_s / 3600;
+    const ageConfig = AGE_MUL[spec.terrain];
+    const ageDegradation = Math.min(1.0, hoursOld * ageConfig.decayPerHour);
+    const ageMul = clampQ((q(1.0) - Math.trunc(ageDegradation * (q(1.0) - ageConfig.floor))), q(0.10), q(1.0));
+    // Species multiplier
+    const speciesMul = SPECIES_TRACK_MUL[spec.quarrySpecies] ?? q(1.0);
+    // Base confidence
+    let confidence_Q = qMul(qMul(naturalist, ageMul), speciesMul);
+    // Species affinity bonus
+    const affinity = getSpeciesAffinity(entity);
+    if (affinity.includes(spec.quarrySpecies)) {
+        confidence_Q = clampQ((confidence_Q + SPECIES_AFFINITY_BONUS), q(0), q(1.0));
+    }
+    // Track range scales with confidence and naturalist ability
+    // Floor ensures even low-confidence trackers can follow obvious trails
+    const rangeMul = Math.max(confidence_Q, mulDiv(naturalist, q(0.20), SCALE.Q));
+    const trackRange_m = Math.round(BASE_TRACK_RANGE_m * rangeMul / SCALE.Q);
+    return { confidence_Q, trackRange_m };
+}
+/**
+ * Resolve a foraging/herbalism attempt.
+ *
+ * Formula:
+ *   yield = baseYield × naturalist × seasonMul × searchHours
+ *   herbQuality_Q = clamp(naturalist × randomFactor, 0, 1)
+ *   P_misidentified = max(0, 0.30 − naturalist × 0.40)
+ *     (troll naturalist 0.50 → ~10%; elf naturalist 0.78 → ~0%)
+ *
+ * @param entity - The forager; uses `cognition.naturalist`.
+ * @param spec   - Foraging specification.
+ * @param seed   - Deterministic seed for quality variance.
+ */
+export function resolveForaging(entity, spec, seed) {
+    const naturalist = (entity.attributes.cognition?.naturalist ?? q(0.50));
+    // Base yield calculation
+    const baseYield = BIOME_YIELD_BASE[spec.biome];
+    const seasonQ = SEASON_MUL[spec.season];
+    // itemsFound = base × naturalist(normalized) × season × hours
+    const naturalistNorm = mulDiv(naturalist, q(1.0), SCALE.Q); // 0-1 range
+    const yieldFloat = baseYield * naturalistNorm * (seasonQ / SCALE.Q) * spec.searchHours;
+    const itemsFound = Math.max(0, Math.round(yieldFloat * 10) / 10); // 1 decimal place
+    // Herb quality: naturalist × RNG factor (roll in [0.70, 1.10] range)
+    const rng = makeRng(seed, SCALE.Q);
+    const q01Roll = rng.q01(); // [0, SCALE.Q-1]
+    const qualityRoll = clampQ((q(0.70) + mulDiv(q01Roll, q(0.40), SCALE.Q)), q(0.70), q(1.10));
+    const herbQuality_Q = clampQ(mulDiv(naturalist, qualityRoll, SCALE.Q), q(0), q(1.0));
+    // Misidentification probability: max(0, 0.30 − naturalist × 0.40)
+    // At naturalist 0.50 (q(0.50)=5000): 0.30 − 0.50 × 0.40 = 0.30 − 0.20 = 0.10 (10%)
+    // At naturalist 0.75: 0.30 − 0.30 = 0 (0%)
+    const naturalistFloat = naturalistNorm;
+    const pMisidentify = Math.max(0, 0.30 - naturalistFloat * 0.40);
+    const misidentifyRoll = (rng.q01() / SCALE.Q);
+    const misidentified = misidentifyRoll < pMisidentify;
+    return { itemsFound, herbQuality_Q, misidentified };
+}
+/**
+ * Resolve an animal taming attempt.
+ *
+ * Formula:
+ *   trust_Q = clamp(naturalist × interSpecies × effortFactor − animalFearQ × 0.50, 0, 1)
+ *   attacked = RNG < (animalFearQ − trust_Q) × 0.30  (high fear + low trust = danger)
+ *
+ * Full taming (trust_Q ≥ q(0.90)) makes the animal available as an ally.
+ *
+ * @param entity - The handler; uses `cognition.naturalist` and `cognition.interSpecies`.
+ * @param spec   - Taming specification.
+ * @param seed   - Deterministic seed for attack check.
+ */
+export function resolveTaming(entity, spec, seed) {
+    const naturalist = (entity.attributes.cognition?.naturalist ?? q(0.50));
+    const interSpecies = (entity.attributes.cognition?.interSpecies ?? q(0.35));
+    // Base trust from naturalist × interSpecies × effort
+    const baseTrust = qMul(qMul(naturalist, interSpecies), spec.effortFactor);
+    // Fear penalty: high fear reduces trust
+    const fearPenalty = mulDiv(spec.animalFearQ, q(0.50), SCALE.Q);
+    // Prior successes bonus: +5% per success, max +25%
+    const experienceBonus = Math.min(spec.priorSuccesses * q(0.05), q(0.25));
+    let trust_Q = clampQ((baseTrust - fearPenalty + experienceBonus), q(0), q(1.0));
+    // Attack check: high fear with low trust is dangerous
+    // P(attack) = max(0, (animalFearQ − trust_Q) × 0.30)
+    const fearFloat = mulDiv(spec.animalFearQ, q(1.0), SCALE.Q);
+    const trustFloat = mulDiv(trust_Q, q(1.0), SCALE.Q);
+    const pAttack = Math.max(0, (fearFloat - trustFloat) * 0.30);
+    const rng = makeRng(seed, SCALE.Q);
+    const attackRoll = rng.q01() / SCALE.Q;
+    const attacked = attackRoll < pAttack;
+    return { trust_Q, attacked };
+}
+/**
+ * Check if an animal is fully tamed (available as ally).
+ */
+export function isFullyTamed(trust_Q) {
+    return trust_Q >= FULLY_TAMED_THRESHOLD;
+}
+/**
+ * Check if tracking confidence is reliable.
+ */
+export function isTrackingReliable(confidence_Q) {
+    return confidence_Q >= TRACKING_CONFIDENCE_THRESHOLD;
+}

package/dist/src/competence/navigation.d.ts

@@ -0,0 +1,24 @@
+import type { Q } from "../units.js";
+import type { Entity } from "../sim/entity.js";
+export interface NavigationSpec {
+    /** Journey distance in metres (real number). */
+    distance_m: number;
+    terrain: "road" | "forest" | "mountain" | "urban" | "sea";
+    /** True = navigator has a map or chart of the area. */
+    hasMap: boolean;
+    visibility: "clear" | "fog" | "night";
+}
+export interface NavigationOutcome {
+    /** 1.0 = optimal route; lower = detours taken. Clamped to [q(0.50), q(1.0)]. */
+    routeEfficiency: Q;
+    /** Additional seconds lost to detours vs the optimal route. */
+    timeLost_s: number;
+}
+/**
+ * Resolve a navigation attempt.
+ *
+ * @param entity - The navigator; uses `cognition.spatial`.
+ * @param spec   - Navigation specification.
+ * @param seed   - Reserved for future variance; currently unused.
+ */
+export declare function resolveNavigation(entity: Entity, spec: NavigationSpec, _seed: number): NavigationOutcome;

package/dist/src/competence/navigation.js

@@ -0,0 +1,48 @@
+// src/competence/navigation.ts — Phase 34: Spatial Intelligence Non-Combat Applications
+//
+// Navigation and pathfinding model:
+//   routeEfficiency = clamp(spatial × terrainQ × mapBonus × visibilityQ, q(0.50), q(1.0))
+//   timeLost_s      = baseTime_s × (1 / routeEfficiency − 1)
+//     where baseTime_s = distance_m / BASE_TRAVEL_SPEED_mps
+//
+// No kernel import — pure resolution module.
+import { SCALE, q, clampQ, qMul, mulDiv } from "../units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+const TERRAIN_Q = {
+    road: q(1.00),
+    urban: q(0.95),
+    forest: q(0.85),
+    mountain: q(0.75),
+    sea: q(0.70),
+};
+const VIS_Q = {
+    clear: q(1.00),
+    fog: q(0.85),
+    night: q(0.75),
+};
+/** Default foot-travel speed [m/s] used to derive base journey time. */
+const BASE_TRAVEL_SPEED_mps = 1.4;
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Resolve a navigation attempt.
+ *
+ * @param entity - The navigator; uses `cognition.spatial`.
+ * @param spec   - Navigation specification.
+ * @param seed   - Reserved for future variance; currently unused.
+ */
+export function resolveNavigation(entity, spec, _seed) {
+    const spatial = (entity.attributes.cognition?.spatial ?? q(0.50));
+    const terrainQ = TERRAIN_Q[spec.terrain];
+    const visQ = VIS_Q[spec.visibility];
+    const mapBonus = spec.hasMap ? q(1.10) : q(0.90);
+    // Compose all modifiers: spatial × mapBonus × terrainQ × visibilityQ
+    const rawEfficiency = qMul(qMul(qMul(spatial, mapBonus), terrainQ), visQ);
+    const routeEfficiency = clampQ(rawEfficiency, q(0.50), q(1.0));
+    // timeLost = baseTravelTime × (1/efficiency − 1)
+    //          = baseTravelTime × (SCALE.Q − efficiency) / efficiency
+    const baseTime_s = spec.distance_m / BASE_TRAVEL_SPEED_mps;
+    const timeLost_s = spec.distance_m > 0
+        ? Math.round(baseTime_s * mulDiv(SCALE.Q - routeEfficiency, SCALE.Q, routeEfficiency) / SCALE.Q)
+        : 0;
+    return { routeEfficiency, timeLost_s };
+}

package/dist/src/competence/performance.d.ts

@@ -0,0 +1,125 @@
+import type { Q } from "../units.js";
+import type { Entity } from "../sim/entity.js";
+import type { WillpowerState } from "./willpower.js";
+/** Performance type affecting the style of morale bonus. */
+export type PerformanceType = "march" | "rally" | "dirge" | "celebration" | "lament";
+/** Specification for a performance. */
+export interface PerformanceSpec {
+    /** Type of performance. */
+    performanceType: PerformanceType;
+    /** Duration in seconds. */
+    duration_s: number;
+    /** Number of allies in range (affects total willpower drain). */
+    audienceCount: number;
+    /** Base range of the performance in metres. */
+    range_m: number;
+}
+/** Outcome of a performance. */
+export interface PerformanceOutcome {
+    /** Fear decay bonus per tick (adds to normal fear decay). */
+    fearDecayBonus_Q: Q;
+    /** Cohesion bonus for the group (0–1). */
+    cohesionBonus_Q: Q;
+    /** Total willpower drained during performance. */
+    willpowerDrained_J: number;
+    /** Performance quality descriptor. */
+    descriptor: "exceptional" | "good" | "adequate" | "poor";
+    /** Whether performance was maintained for full duration. */
+    completed: boolean;
+}
+/** Active performance state for ongoing morale effects. */
+export interface ActivePerformance {
+    /** Performer entity ID. */
+    performerId: number;
+    /** Performance type. */
+    performanceType: PerformanceType;
+    /** Remaining duration in seconds. */
+    remaining_s: number;
+    /** Fear decay bonus per tick. */
+    fearDecayBonus_Q: Q;
+    /** Range in metres. */
+    range_m: number;
+}
+/**
+ * Resolve a musical performance.
+ *
+ * Performance generates sustained morale auras scaled by musical intelligence,
+ * draining willpower (Phase 38) from the performer.
+ *
+ * Formulas:
+ *   fearDecayBonus = musical × BASE_FEAR_DECAY_BONUS × typeMul
+ *   cohesionBonus = musical × BASE_COHESION_BONUS × typeMul
+ *   willpowerDrained = (BASE_DRAIN + audience × AUDIENCE_DRAIN) × duration × typeDrainMul
+ *
+ * Satyr bard (musical 0.95) → fearDecayBonus ≈ q(0.019), nearly matching a leader aura.
+ *
+ * @param performer - The entity performing; uses `cognition.musical`.
+ * @param spec - Performance specification.
+ * @returns Performance outcome with morale bonuses and willpower cost.
+ */
+export declare function resolvePerformance(performer: Entity, spec: PerformanceSpec): PerformanceOutcome;
+/**
+ * Step an active performance for one tick.
+ * Deducts willpower and returns whether performance can continue.
+ *
+ * @param performance - Active performance state (mutated).
+ * @param willpower - Performer's willpower state (mutated).
+ * @param delta_s - Time step in seconds.
+ * @returns True if performance can continue, false if willpower depleted.
+ */
+export declare function stepPerformance(performance: ActivePerformance, willpower: WillpowerState, delta_s: number): boolean;
+/**
+ * Calculate the effective range of a performance.
+ *
+ * @param performer - The performing entity.
+ * @param baseRange - Base range in metres.
+ * @returns Effective range in metres.
+ */
+export declare function calculatePerformanceRange(performer: Entity, baseRange?: number): number;
+/**
+ * Check if an entity is in range of a performance.
+ *
+ * @param performance - Active performance.
+ * @param performerPos - Performer's position.
+ * @param listenerPos - Potential listener's position.
+ * @returns True if listener is within performance range.
+ */
+export declare function isInPerformanceRange(performance: ActivePerformance, performerPos: {
+    x: number;
+    y: number;
+    z: number;
+}, listenerPos: {
+    x: number;
+    y: number;
+    z: number;
+}): boolean;
+/**
+ * Create an active performance state.
+ *
+ * @param performerId - Entity ID of the performer.
+ * @param performanceType - Type of performance.
+ * @param duration_s - Duration in seconds.
+ * @param performer - The performing entity (for musical bonus calculation).
+ * @returns Active performance state.
+ */
+export declare function createActivePerformance(performerId: number, performanceType: PerformanceType, duration_s: number, performer: Entity): ActivePerformance;
+/**
+ * Check if an entity can effectively perform.
+ * Requires minimum musical intelligence and available willpower.
+ *
+ * @param entity - The potential performer.
+ * @param willpower - The entity's willpower state.
+ * @param minMusical - Minimum musical intelligence required.
+ * @returns True if entity can perform.
+ */
+export declare function canPerform(entity: Entity, willpower: WillpowerState, minMusical?: Q): boolean;
+/**
+ * Estimate performance effectiveness without consuming resources.
+ *
+ * @param performer - The potential performer.
+ * @param performanceType - Type of performance.
+ * @param duration_s - Expected duration.
+ * @param audienceCount - Expected audience size.
+ * @returns Estimated outcome values.
+ */
+export declare function estimatePerformance(performer: Entity, performanceType: PerformanceType, duration_s: number, audienceCount: number): Omit<PerformanceOutcome, "completed">;

package/dist/src/competence/performance.js

@@ -0,0 +1,210 @@
+// src/competence/performance.ts — Phase 39: Musical Performance as Morale Vector
+//
+// Performance generates sustained morale effects scaled by musical intelligence,
+// draining willpower (Phase 38) to maintain.
+//
+// No kernel import — pure resolution module.
+import { SCALE, q, clampQ } from "../units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Base fear decay bonus per tick at musical q(1.0). */
+const BASE_FEAR_DECAY_BONUS = q(0.020);
+/** Base cohesion bonus per performance. */
+const BASE_COHESION_BONUS = q(0.010);
+/** Willpower drain per second of performance (at base quality). */
+const BASE_WILLPOWER_DRAIN_PER_SECOND = 50; // 50 J/s
+/** Willpower drain per audience member per second. */
+const AUDIENCE_DRAIN_PER_SECOND = 10; // 10 J/s per ally
+/** Maximum effective range for performance effects. */
+const MAX_PERFORMANCE_RANGE_m = 100;
+/** Minimum range for any performance effect. */
+const MIN_PERFORMANCE_RANGE_m = 10;
+// Performance type multipliers
+const PERFORMANCE_TYPE_MULTIPLIERS = {
+    march: { fearMul: 0.5, cohesionMul: 1.5, drainMul: 0.8 },
+    rally: { fearMul: 1.5, cohesionMul: 1.0, drainMul: 1.2 },
+    dirge: { fearMul: 0.8, cohesionMul: 0.5, drainMul: 0.6 },
+    celebration: { fearMul: 1.0, cohesionMul: 1.5, drainMul: 1.0 },
+    lament: { fearMul: 1.2, cohesionMul: 0.3, drainMul: 0.7 },
+};
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Resolve a musical performance.
+ *
+ * Performance generates sustained morale auras scaled by musical intelligence,
+ * draining willpower (Phase 38) from the performer.
+ *
+ * Formulas:
+ *   fearDecayBonus = musical × BASE_FEAR_DECAY_BONUS × typeMul
+ *   cohesionBonus = musical × BASE_COHESION_BONUS × typeMul
+ *   willpowerDrained = (BASE_DRAIN + audience × AUDIENCE_DRAIN) × duration × typeDrainMul
+ *
+ * Satyr bard (musical 0.95) → fearDecayBonus ≈ q(0.019), nearly matching a leader aura.
+ *
+ * @param performer - The entity performing; uses `cognition.musical`.
+ * @param spec - Performance specification.
+ * @returns Performance outcome with morale bonuses and willpower cost.
+ */
+export function resolvePerformance(performer, spec) {
+    const musical = (performer.attributes.cognition?.musical ?? q(0.50));
+    const musicalNorm = musical / SCALE.Q;
+    // Type multipliers
+    const typeMuls = PERFORMANCE_TYPE_MULTIPLIERS[spec.performanceType];
+    // Calculate fear decay bonus
+    const rawFearBonus = musicalNorm * (BASE_FEAR_DECAY_BONUS / SCALE.Q) * typeMuls.fearMul;
+    const fearDecayBonus_Q = clampQ(Math.round(rawFearBonus * SCALE.Q), q(0), q(0.050));
+    // Calculate cohesion bonus
+    const rawCohesionBonus = musicalNorm * (BASE_COHESION_BONUS / SCALE.Q) * typeMuls.cohesionMul;
+    const cohesionBonus_Q = clampQ(Math.round(rawCohesionBonus * SCALE.Q), q(0), SCALE.Q);
+    // Calculate willpower drain
+    const baseDrain = BASE_WILLPOWER_DRAIN_PER_SECOND + spec.audienceCount * AUDIENCE_DRAIN_PER_SECOND;
+    const willpowerDrained_J = Math.round(baseDrain * spec.duration_s * typeMuls.drainMul);
+    // Determine descriptor based on musical skill
+    let descriptor;
+    if (musical >= q(0.85)) {
+        descriptor = "exceptional";
+    }
+    else if (musical >= q(0.65)) {
+        descriptor = "good";
+    }
+    else if (musical >= q(0.45)) {
+        descriptor = "adequate";
+    }
+    else {
+        descriptor = "poor";
+    }
+    return {
+        fearDecayBonus_Q,
+        cohesionBonus_Q,
+        willpowerDrained_J,
+        descriptor,
+        completed: true, // assumes full duration completed
+    };
+}
+/**
+ * Step an active performance for one tick.
+ * Deducts willpower and returns whether performance can continue.
+ *
+ * @param performance - Active performance state (mutated).
+ * @param willpower - Performer's willpower state (mutated).
+ * @param delta_s - Time step in seconds.
+ * @returns True if performance can continue, false if willpower depleted.
+ */
+export function stepPerformance(performance, willpower, delta_s) {
+    const typeMuls = PERFORMANCE_TYPE_MULTIPLIERS[performance.performanceType];
+    const drainRate = BASE_WILLPOWER_DRAIN_PER_SECOND * typeMuls.drainMul;
+    const drainAmount = Math.round(drainRate * delta_s);
+    if (willpower.current_J < drainAmount) {
+        // Insufficient willpower - performance stops
+        willpower.current_J = Math.max(0, willpower.current_J);
+        return false;
+    }
+    willpower.current_J -= drainAmount;
+    performance.remaining_s = Math.max(0, performance.remaining_s - delta_s);
+    return performance.remaining_s > 0;
+}
+/**
+ * Calculate the effective range of a performance.
+ *
+ * @param performer - The performing entity.
+ * @param baseRange - Base range in metres.
+ * @returns Effective range in metres.
+ */
+export function calculatePerformanceRange(performer, baseRange = 50) {
+    const musical = (performer.attributes.cognition?.musical ?? q(0.50));
+    const musicalNorm = musical / SCALE.Q;
+    // Musical skill increases effective range
+    const rangeMultiplier = 0.5 + musicalNorm; // 0.5 to 1.5x range
+    const effectiveRange = Math.round(baseRange * rangeMultiplier);
+    return clampQ(effectiveRange, MIN_PERFORMANCE_RANGE_m, MAX_PERFORMANCE_RANGE_m);
+}
+/**
+ * Check if an entity is in range of a performance.
+ *
+ * @param performance - Active performance.
+ * @param performerPos - Performer's position.
+ * @param listenerPos - Potential listener's position.
+ * @returns True if listener is within performance range.
+ */
+export function isInPerformanceRange(performance, performerPos, listenerPos) {
+    const dx = (performerPos.x - listenerPos.x) / SCALE.m;
+    const dy = (performerPos.y - listenerPos.y) / SCALE.m;
+    const dz = (performerPos.z - listenerPos.z) / SCALE.m;
+    const dist_m = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    return dist_m <= performance.range_m;
+}
+/**
+ * Create an active performance state.
+ *
+ * @param performerId - Entity ID of the performer.
+ * @param performanceType - Type of performance.
+ * @param duration_s - Duration in seconds.
+ * @param performer - The performing entity (for musical bonus calculation).
+ * @returns Active performance state.
+ */
+export function createActivePerformance(performerId, performanceType, duration_s, performer) {
+    const outcome = resolvePerformance(performer, {
+        performanceType,
+        duration_s,
+        audienceCount: 0, // Will be updated dynamically
+        range_m: calculatePerformanceRange(performer),
+    });
+    return {
+        performerId,
+        performanceType,
+        remaining_s: duration_s,
+        fearDecayBonus_Q: outcome.fearDecayBonus_Q,
+        range_m: calculatePerformanceRange(performer),
+    };
+}
+/**
+ * Check if an entity can effectively perform.
+ * Requires minimum musical intelligence and available willpower.
+ *
+ * @param entity - The potential performer.
+ * @param willpower - The entity's willpower state.
+ * @param minMusical - Minimum musical intelligence required.
+ * @returns True if entity can perform.
+ */
+export function canPerform(entity, willpower, minMusical = q(0.35)) {
+    const musical = (entity.attributes.cognition?.musical ?? q(0.50));
+    return musical >= minMusical && willpower.current_J > BASE_WILLPOWER_DRAIN_PER_SECOND * 10;
+}
+/**
+ * Estimate performance effectiveness without consuming resources.
+ *
+ * @param performer - The potential performer.
+ * @param performanceType - Type of performance.
+ * @param duration_s - Expected duration.
+ * @param audienceCount - Expected audience size.
+ * @returns Estimated outcome values.
+ */
+export function estimatePerformance(performer, performanceType, duration_s, audienceCount) {
+    const musical = (performer.attributes.cognition?.musical ?? q(0.50));
+    const musicalNorm = musical / SCALE.Q;
+    const typeMuls = PERFORMANCE_TYPE_MULTIPLIERS[performanceType];
+    const rawFearBonus = musicalNorm * (BASE_FEAR_DECAY_BONUS / SCALE.Q) * typeMuls.fearMul;
+    const fearDecayBonus_Q = clampQ(Math.round(rawFearBonus * SCALE.Q), q(0), q(0.050));
+    const rawCohesionBonus = musicalNorm * (BASE_COHESION_BONUS / SCALE.Q) * typeMuls.cohesionMul;
+    const cohesionBonus_Q = clampQ(Math.round(rawCohesionBonus * SCALE.Q), q(0), SCALE.Q);
+    const baseDrain = BASE_WILLPOWER_DRAIN_PER_SECOND + audienceCount * AUDIENCE_DRAIN_PER_SECOND;
+    const willpowerDrained_J = Math.round(baseDrain * duration_s * typeMuls.drainMul);
+    let descriptor;
+    if (musical >= q(0.85)) {
+        descriptor = "exceptional";
+    }
+    else if (musical >= q(0.65)) {
+        descriptor = "good";
+    }
+    else if (musical >= q(0.45)) {
+        descriptor = "adequate";
+    }
+    else {
+        descriptor = "poor";
+    }
+    return {
+        fearDecayBonus_Q,
+        cohesionBonus_Q,
+        willpowerDrained_J,
+        descriptor,
+    };
+}

package/dist/src/competence/teaching.d.ts

@@ -0,0 +1,64 @@
+import type { Q } from "../units.js";
+import type { Entity } from "../sim/entity.js";
+import type { SkillId } from "../sim/skills.js";
+export interface TeachingSpec {
+    /** Skill domain being taught. */
+    domain: SkillId;
+    /** Hours of teaching session. */
+    hours: number;
+    /** Teacher's interpersonal skill quality (optional override). */
+    teacherInterpersonal_Q?: Q;
+    /** Learner's natural learning rate (optional override). */
+    learnerLearningRate_Q?: Q;
+}
+export interface TeachingOutcome {
+    /** XP gained by learner. */
+    xpGained: number;
+    /** Teacher fatigue in joules. */
+    teacherFatigueJ: number;
+    /** Teaching quality multiplier (0–1). */
+    teachingQuality_Q: Q;
+}
+/**
+ * Resolve a teaching session and compute XP gain.
+ *
+ * Formula:
+ *   xpGained = hours × BASE_XP_RATE × interpersonal(teacher) × learningRate(learner)
+ *   teacherFatigueJ = hours × BASE_FATIGUE_PER_HOUR × FATIGUE_MULTIPLIER
+ *
+ * @param teacher - The entity providing instruction.
+ * @param learner - The entity receiving instruction.
+ * @param spec - Teaching specification.
+ * @returns Teaching outcome with XP gained and teacher fatigue.
+ */
+export declare function resolveTeaching(teacher: Entity, learner: Entity, spec: TeachingSpec): TeachingOutcome;
+/**
+ * Compute maximum effective teaching hours based on teacher stamina.
+ */
+export declare function computeMaxTeachingHours(teacher: Entity, availableEnergyJ: number): number;
+/**
+ * Check if teacher is qualified to teach a skill.
+ * Teacher should have at least journeyman level (skill delta showing improvement).
+ */
+export declare function isQualifiedTeacher(teacher: Entity, domain: SkillId, minimumProficiency?: Q): boolean;
+/**
+ * Compute probability of detecting deception.
+ *
+ * Formula:
+ *   P_detect = clamp(
+ *     attentionDepth × 0.50 + interpersonal × 0.50 − plausibility,
+ *     0, 1)
+ *
+ * @param detector - The entity attempting to detect deception.
+ * @param plausibility_Q - Plausibility of the deception (0–1).
+ * @returns Detection probability (0–1).
+ */
+export declare function computeDeceptionDetectionProbability(detector: Entity, plausibility_Q: Q): Q;
+/**
+ * Resolve deception detection.
+ * @returns True if deception was detected.
+ */
+export declare function resolveDeceptionDetection(detector: Entity, plausibility_Q: Q, seed: number): {
+    detected: boolean;
+    confidence_Q: Q;
+};