@its-not-rocket-science/ananke 0.1.0

package/dist/src/chronicle.js

@@ -0,0 +1,232 @@
+// src/chronicle.ts — Phase 45: Emergent Story Generation — Chronicle System
+//
+// Transforms simulation events into coherent narratives through significance
+// scoring and narrative templates.
+// ── Significance Scoring ───────────────────────────────────────────────────────
+/** Base significance scores by event type. */
+export const SIGNIFICANCE_SCORES = {
+    entity_death: 80,
+    entity_birth: 30,
+    relationship_formed: 40,
+    relationship_broken: 50,
+    relationship_betrayal: 75,
+    quest_completed: 45,
+    quest_failed: 40,
+    quest_accepted: 20,
+    settlement_founded: 60,
+    settlement_upgraded: 50,
+    settlement_raided: 55,
+    settlement_destroyed: 90,
+    facility_completed: 35,
+    masterwork_crafted: 50,
+    first_contact: 70,
+    combat_victory: 25,
+    combat_defeat: 30,
+    rank_promotion: 35,
+    legendary_deed: 85,
+    tragic_event: 70,
+};
+/** Calculate significance score for an event. */
+export function calculateSignificance(eventType, context) {
+    let score = SIGNIFICANCE_SCORES[eventType] ?? 20;
+    if (context) {
+        if (context.actorWasFamous)
+            score += 15;
+        if (context.wasFirst)
+            score += 20;
+        if (context.involvedMultipleParties)
+            score += 10;
+        if (context.unexpectedOutcome)
+            score += 15;
+        if (context.lastingConsequences)
+            score += 10;
+    }
+    return Math.min(100, score);
+}
+/** Check if an event is significant enough to record. */
+export function isSignificant(eventType, threshold = 25, context) {
+    return calculateSignificance(eventType, context) >= threshold;
+}
+// ── Chronicle Management ───────────────────────────────────────────────────────
+/** Create a new chronicle. */
+export function createChronicle(chronicleId, scope, tick, ownerId) {
+    return {
+        chronicleId,
+        scope,
+        ownerId,
+        entries: [],
+        createdAtTick: tick,
+        lastEntryTick: tick,
+        detectedArcs: [],
+    };
+}
+/** Add an entry to a chronicle. */
+export function addChronicleEntry(chronicle, entry, seed) {
+    const fullEntry = {
+        ...entry,
+        entryId: generateEntryId(chronicle.chronicleId, chronicle.entries.length, seed ?? Date.now()),
+    };
+    chronicle.entries.push(fullEntry);
+    chronicle.lastEntryTick = entry.tick;
+    // Sort entries by tick
+    chronicle.entries.sort((a, b) => a.tick - b.tick);
+    return fullEntry;
+}
+function generateEntryId(chronicleId, index, seed) {
+    return `${chronicleId}_${seed}_${index}`;
+}
+/** Get entries above a significance threshold. */
+export function getSignificantEntries(chronicle, minSignificance = 50) {
+    return chronicle.entries.filter(e => e.significance >= minSignificance);
+}
+/** Get entries within a tick range. */
+export function getEntriesInRange(chronicle, startTick, endTick) {
+    return chronicle.entries.filter(e => e.tick >= startTick && e.tick <= endTick);
+}
+/** Get entries involving a specific entity. */
+export function getEntriesForEntity(chronicle, entityId) {
+    return chronicle.entries.filter(e => e.actors.includes(entityId));
+}
+/** Get entries of a specific type. */
+export function getEntriesByType(chronicle, eventType) {
+    return chronicle.entries.filter(e => e.eventType === eventType);
+}
+/** Create a new chronicle registry. */
+export function createChronicleRegistry(tick) {
+    return {
+        worldChronicle: createChronicle("world", "world", tick),
+        entityChronicles: new Map(),
+        factionChronicles: new Map(),
+        settlementChronicles: new Map(),
+    };
+}
+/** Record an event to appropriate chronicles. */
+export function recordEvent(registry, entry, options) {
+    // Always record to world chronicle if significant enough
+    if (entry.significance >= 30) {
+        addChronicleEntry(registry.worldChronicle, entry);
+    }
+    // Record to entity chronicles
+    if (options?.entityIds) {
+        for (const entityId of options.entityIds) {
+            let chronicle = registry.entityChronicles.get(entityId);
+            if (!chronicle) {
+                chronicle = createChronicle(`entity_${entityId}`, "entity", entry.tick, entityId);
+                registry.entityChronicles.set(entityId, chronicle);
+            }
+            addChronicleEntry(chronicle, entry);
+        }
+    }
+    // Record to faction chronicles
+    if (options?.factionIds) {
+        for (const factionId of options.factionIds) {
+            let chronicle = registry.factionChronicles.get(factionId);
+            if (!chronicle) {
+                chronicle = createChronicle(`faction_${factionId}`, "faction", entry.tick, factionId);
+                registry.factionChronicles.set(factionId, chronicle);
+            }
+            addChronicleEntry(chronicle, entry);
+        }
+    }
+    // Record to settlement chronicle
+    if (options?.settlementId) {
+        let chronicle = registry.settlementChronicles.get(options.settlementId);
+        if (!chronicle) {
+            chronicle = createChronicle(`settlement_${options.settlementId}`, "settlement", entry.tick, options.settlementId);
+            registry.settlementChronicles.set(options.settlementId, chronicle);
+        }
+        addChronicleEntry(chronicle, entry);
+    }
+}
+/** Summarize a chronicle at different granularities. */
+export function summarizeChronicle(chronicle, level = "chapter") {
+    let includedEntries;
+    let summaryText;
+    switch (level) {
+        case "full":
+            includedEntries = [...chronicle.entries];
+            summaryText = `Complete history: ${includedEntries.length} events recorded.`;
+            break;
+        case "chapter":
+            // Include only significant events and arc starts/ends
+            includedEntries = chronicle.entries.filter(e => e.significance >= 50 || chronicle.detectedArcs.some(a => a.entryIds.includes(e.entryId)));
+            summaryText = `Major events: ${includedEntries.length} significant moments across ${chronicle.detectedArcs.length} story arcs.`;
+            break;
+        case "synopsis":
+            // Just the highest significance events
+            includedEntries = getSignificantEntries(chronicle, 70);
+            summaryText = `Synopsis: ${includedEntries.length} pivotal events defined this ${chronicle.scope}.`;
+            break;
+    }
+    return {
+        level,
+        totalEntries: chronicle.entries.length,
+        includedEntries: includedEntries.length,
+        summaryText,
+        keyEvents: includedEntries,
+    };
+}
+// ── Serialization ─────────────────────────────────────────────────────────────
+/** Serialize chronicle to JSON-friendly format. */
+export function serializeChronicle(chronicle) {
+    return {
+        chronicleId: chronicle.chronicleId,
+        scope: chronicle.scope,
+        ownerId: chronicle.ownerId,
+        entries: chronicle.entries,
+        createdAtTick: chronicle.createdAtTick,
+        lastEntryTick: chronicle.lastEntryTick,
+        detectedArcs: chronicle.detectedArcs,
+    };
+}
+/** Deserialize chronicle. */
+export function deserializeChronicle(data) {
+    const d = data;
+    return {
+        chronicleId: d.chronicleId ?? "",
+        scope: d.scope ?? "world",
+        ownerId: d.ownerId,
+        entries: Array.isArray(d.entries) ? d.entries : [],
+        createdAtTick: d.createdAtTick ?? 0,
+        lastEntryTick: d.lastEntryTick ?? 0,
+        detectedArcs: Array.isArray(d.detectedArcs) ? d.detectedArcs : [],
+    };
+}
+/** Serialize chronicle registry. */
+export function serializeChronicleRegistry(registry) {
+    return {
+        worldChronicle: serializeChronicle(registry.worldChronicle),
+        entityChronicles: Array.from(registry.entityChronicles.entries()).map(([id, c]) => [id, serializeChronicle(c)]),
+        factionChronicles: Array.from(registry.factionChronicles.entries()).map(([id, c]) => [id, serializeChronicle(c)]),
+        settlementChronicles: Array.from(registry.settlementChronicles.entries()).map(([id, c]) => [id, serializeChronicle(c)]),
+    };
+}
+/** Deserialize chronicle registry. */
+export function deserializeChronicleRegistry(data) {
+    const d = data;
+    const registry = {
+        worldChronicle: createChronicle("world", "world", 0),
+        entityChronicles: new Map(),
+        factionChronicles: new Map(),
+        settlementChronicles: new Map(),
+    };
+    if (d.worldChronicle) {
+        registry.worldChronicle = deserializeChronicle(d.worldChronicle);
+    }
+    if (Array.isArray(d.entityChronicles)) {
+        for (const [id, c] of d.entityChronicles) {
+            registry.entityChronicles.set(id, deserializeChronicle(c));
+        }
+    }
+    if (Array.isArray(d.factionChronicles)) {
+        for (const [id, c] of d.factionChronicles) {
+            registry.factionChronicles.set(id, deserializeChronicle(c));
+        }
+    }
+    if (Array.isArray(d.settlementChronicles)) {
+        for (const [id, c] of d.settlementChronicles) {
+            registry.settlementChronicles.set(id, deserializeChronicle(c));
+        }
+    }
+    return registry;
+}

package/dist/src/collective-activities.d.ts

@@ -0,0 +1,154 @@
+import { type Q } from "./units.js";
+import type { Entity } from "./sim/entity.js";
+import type { Vec3 } from "./sim/vec3.js";
+/** Kind of collective engineering project. */
+export type CollectiveProjectKind = "field_fortification" | "siege_ramp" | "field_bridge" | "ritual_circle" | "trade_post";
+/** One contributor's recorded work on a collective project. */
+export interface CollectiveContributor {
+    entityId: number;
+    hoursWorked: number;
+    /** Effective competence at contribution time [Q]. */
+    competence_Q: Q;
+}
+/** A shared construction project that multiple entities contribute toward. */
+export interface CollectiveProject {
+    projectId: string;
+    kind: CollectiveProjectKind;
+    label: string;
+    /** Current completion [Q 0..completionThreshold_Q]. */
+    progress_Q: Q;
+    /** Q threshold at which project is considered complete (usually SCALE.Q). */
+    completionThreshold_Q: Q;
+    /** Person-hours at q(1.0) competence required to reach completionThreshold_Q. */
+    requiredWorkHours: number;
+    contributors: CollectiveContributor[];
+    /** Tick at which progress first reached completionThreshold_Q; undefined if incomplete. */
+    completedAtTick?: number | undefined;
+}
+/** Result returned by `stepRitual`. */
+export interface RitualResult {
+    /** Morale bonus applicable to all participants [Q 0..RITUAL_MAX_BONUS]. */
+    moraleBonus_Q: Q;
+    /** Fear threshold reduction for all participants [Q]. */
+    fearReduction_Q: Q;
+    /** Number of participants in this session. */
+    participantCount: number;
+}
+/** One waypoint in a caravan route. */
+export interface CaravanWaypoint {
+    /** Identifier for the location (settlement ID, etc.). */
+    positionId: string;
+    position_m: Vec3;
+    /** Planned rest time at this waypoint [hours]. */
+    restHours: number;
+}
+/** Logistics plan produced by `planCaravanRoute`. */
+export interface CaravanPlan {
+    /** Deterministic identifier derived from waypoint IDs. */
+    planId: string;
+    waypoints: CaravanWaypoint[];
+    /** Entity IDs of caravan participants. */
+    participantIds: number[];
+    /** Pure travel time excluding rest stops [seconds]. */
+    estimatedTravelSeconds: number;
+    /** Total journey time including rest stops [seconds]. */
+    estimatedTotalSeconds: number;
+    /** Food sufficiency for the journey [Q]: q(1.0) = fully provisioned. */
+    supplySufficiency_Q: Q;
+    /** Route quality from best navigator's logicalMathematical [Q]. */
+    routeQuality_Q: Q;
+    /** Trade bonus from best negotiator's interpersonal [Q]. */
+    negotiationBonus_Q: Q;
+}
+/**
+ * Seconds for a full-duration ritual to achieve maximum bonus.
+ * Shorter sessions scale linearly; longer sessions are capped at this duration.
+ */
+export declare const RITUAL_DURATION_s = 3600;
+/**
+ * Maximum morale bonus a ritual can produce [Q].
+ * Even a perfect ensemble cannot exceed this per session.
+ */
+export declare const RITUAL_MAX_BONUS: Q;
+/**
+ * Fraction of the morale bonus that converts to fear reduction [Q].
+ * fearReduction_Q = moraleBonus_Q × RITUAL_FEAR_REDUCTION_FRAC / SCALE.Q.
+ */
+export declare const RITUAL_FEAR_REDUCTION_FRAC: Q;
+/**
+ * Walking-pace caravan speed [SCALE.mps].
+ * 1.2 m/s = 12 000 SCALE.mps.
+ */
+export declare const CARAVAN_BASE_SPEED_Smps = 12000;
+/**
+ * Food rations required per person per day of caravan travel.
+ * Caller supplies all items in their food inventory; every item counts as one ration.
+ */
+export declare const CARAVAN_RATIONS_PER_PERSON_PER_DAY = 3;
+/**
+ * Default engineering competence for entities without a cognition profile.
+ * Represents an average untrained labourer.
+ */
+export declare const DEFAULT_ENGINEERING_COMPETENCE: Q;
+/**
+ * Derive an entity's engineering competence from their cognitive profile.
+ *
+ * Uses the average of logicalMathematical (planning) and bodilyKinesthetic
+ * (manual precision). Entities without a cognition profile return
+ * DEFAULT_ENGINEERING_COMPETENCE.
+ */
+export declare function deriveEngineeringCompetence(entity: Entity): Q;
+/**
+ * Create a new collective project with zero progress.
+ */
+export declare function createCollectiveProject(projectId: string, kind: CollectiveProjectKind, label: string, requiredWorkHours: number): CollectiveProject;
+/**
+ * Add a contribution to a collective project from one entity.
+ *
+ * Mutates `project.progress_Q` and appends to `project.contributors`.
+ * Progress delta = competence_Q × hoursWorked / requiredWorkHours (Q-scaled).
+ * Progress is clamped to [0, completionThreshold_Q].
+ *
+ * @param project      The shared project to advance.
+ * @param entity       The contributing entity.
+ * @param hoursWorked  Hours of work this entity is contributing (must be > 0).
+ * @param tick         Current world tick (used for completion timestamp).
+ * @returns            The actual progress delta applied (Q units).
+ */
+export declare function contributeToCollectiveProject(project: CollectiveProject, entity: Entity, hoursWorked: number, tick: number): Q;
+/**
+ * Return true if a project has reached its completion threshold.
+ */
+export declare function isProjectComplete(project: CollectiveProject): boolean;
+/**
+ * Compute the morale and fear-reduction effects of a communal ritual.
+ *
+ * Each participant contributes their average (intrapersonal + musical) / 2
+ * to a shared cognitive pool. The collective effect scales with sqrt(N)
+ * (diminishing returns for large groups). The time factor scales linearly
+ * from 0 at 0 s to 1 at RITUAL_DURATION_s; durations beyond that are capped.
+ *
+ * moraleBonus_Q is capped at RITUAL_MAX_BONUS regardless of group size.
+ * fearReduction_Q = moraleBonus_Q × RITUAL_FEAR_REDUCTION_FRAC / SCALE.Q.
+ *
+ * @param participants   All entities taking part (pass only alive entities).
+ * @param elapsedSeconds Duration of the ritual session in seconds.
+ * @returns RitualResult to apply to all participants.
+ */
+export declare function stepRitual(participants: Entity[], elapsedSeconds: number): RitualResult;
+/**
+ * Plan a trade caravan route, deriving logistics quality from participants'
+ * cognitive attributes and food sufficiency from the supplied inventory.
+ *
+ * Route quality (best logicalMathematical) shortens travel time:
+ *   speedFactor = q(0.80) + routeQuality_Q × q(0.20) / SCALE.Q  ∈ [q(0.80), q(1.00)]
+ *   adjustedTravelSeconds = baseSeconds × SCALE.Q / speedFactor
+ *
+ * Supply sufficiency = totalRations / (adjustedTravelDays × participants × RATIONS/DAY).
+ *
+ * @param waypoints     Ordered stops (position + rest hours).
+ * @param participants  Entities travelling with the caravan.
+ * @param inventory     Map<itemId, quantity> of food items available (all entries count).
+ * @returns             CaravanPlan with derived logistics values.
+ */
+export declare function planCaravanRoute(waypoints: CaravanWaypoint[], participants: Entity[], inventory: Map<string, number>): CaravanPlan;

package/dist/src/collective-activities.js

@@ -0,0 +1,247 @@
+// src/collective-activities.ts — Phase 55: Collective Non-Combat Activities
+//
+// Three systems for formation/group-scale non-combat coordination:
+//
+//   1. Siege Engineering — field construction projects (fortifications, ramps, bridges)
+//      Progress = Σ(competence_Q × hoursWorked) / requiredWorkHours
+//      Competence derived from logicalMathematical + bodilyKinesthetic cognition.
+//
+//   2. Ritual & Ceremony — collective morale amplification via intrapersonal/musical pool
+//      moraleBonus_Q scales with average cognition and sqrt(N) for diminishing returns.
+//      Returns morale bonus and fear reduction applicable to all participants.
+//
+//   3. Trade Caravan Logistics — route planning with supply sufficiency and route quality
+//      routeQuality_Q from logicalMathematical (best navigator leads);
+//      negotiationBonus_Q from best interpersonal score;
+//      supplySufficiency_Q from inventory vs. estimated ration needs.
+import { q, clampQ, SCALE } from "./units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/**
+ * Seconds for a full-duration ritual to achieve maximum bonus.
+ * Shorter sessions scale linearly; longer sessions are capped at this duration.
+ */
+export const RITUAL_DURATION_s = 3_600; // 1 hour
+/**
+ * Maximum morale bonus a ritual can produce [Q].
+ * Even a perfect ensemble cannot exceed this per session.
+ */
+export const RITUAL_MAX_BONUS = q(0.30); // 3000
+/**
+ * Fraction of the morale bonus that converts to fear reduction [Q].
+ * fearReduction_Q = moraleBonus_Q × RITUAL_FEAR_REDUCTION_FRAC / SCALE.Q.
+ */
+export const RITUAL_FEAR_REDUCTION_FRAC = q(0.60); // 6000
+/**
+ * Walking-pace caravan speed [SCALE.mps].
+ * 1.2 m/s = 12 000 SCALE.mps.
+ */
+export const CARAVAN_BASE_SPEED_Smps = 12_000;
+/**
+ * Food rations required per person per day of caravan travel.
+ * Caller supplies all items in their food inventory; every item counts as one ration.
+ */
+export const CARAVAN_RATIONS_PER_PERSON_PER_DAY = 3;
+/**
+ * Default engineering competence for entities without a cognition profile.
+ * Represents an average untrained labourer.
+ */
+export const DEFAULT_ENGINEERING_COMPETENCE = q(0.50); // 5000
+// ── Siege Engineering ─────────────────────────────────────────────────────────
+/**
+ * Derive an entity's engineering competence from their cognitive profile.
+ *
+ * Uses the average of logicalMathematical (planning) and bodilyKinesthetic
+ * (manual precision). Entities without a cognition profile return
+ * DEFAULT_ENGINEERING_COMPETENCE.
+ */
+export function deriveEngineeringCompetence(entity) {
+    const cog = entity.attributes.cognition;
+    if (!cog)
+        return DEFAULT_ENGINEERING_COMPETENCE;
+    return Math.round((cog.logicalMathematical + cog.bodilyKinesthetic) / 2);
+}
+/**
+ * Create a new collective project with zero progress.
+ */
+export function createCollectiveProject(projectId, kind, label, requiredWorkHours) {
+    return {
+        projectId,
+        kind,
+        label,
+        progress_Q: q(0),
+        completionThreshold_Q: SCALE.Q,
+        requiredWorkHours,
+        contributors: [],
+        completedAtTick: undefined,
+    };
+}
+/**
+ * Add a contribution to a collective project from one entity.
+ *
+ * Mutates `project.progress_Q` and appends to `project.contributors`.
+ * Progress delta = competence_Q × hoursWorked / requiredWorkHours (Q-scaled).
+ * Progress is clamped to [0, completionThreshold_Q].
+ *
+ * @param project      The shared project to advance.
+ * @param entity       The contributing entity.
+ * @param hoursWorked  Hours of work this entity is contributing (must be > 0).
+ * @param tick         Current world tick (used for completion timestamp).
+ * @returns            The actual progress delta applied (Q units).
+ */
+export function contributeToCollectiveProject(project, entity, hoursWorked, tick) {
+    if (hoursWorked <= 0)
+        return q(0);
+    const competence_Q = deriveEngineeringCompetence(entity);
+    // delta = (competence_Q / SCALE.Q) × (hoursWorked / requiredWorkHours) × SCALE.Q
+    //       = competence_Q × hoursWorked / requiredWorkHours
+    const delta = Math.round(competence_Q * hoursWorked / project.requiredWorkHours);
+    const prevProgress = project.progress_Q;
+    project.progress_Q = clampQ((project.progress_Q + delta), q(0), project.completionThreshold_Q);
+    project.contributors.push({ entityId: entity.id, hoursWorked, competence_Q });
+    // Record completion tick the first time the threshold is crossed.
+    if (project.completedAtTick === undefined &&
+        project.progress_Q >= project.completionThreshold_Q &&
+        prevProgress < project.completionThreshold_Q) {
+        project.completedAtTick = tick;
+    }
+    return (project.progress_Q - prevProgress);
+}
+/**
+ * Return true if a project has reached its completion threshold.
+ */
+export function isProjectComplete(project) {
+    return project.progress_Q >= project.completionThreshold_Q;
+}
+// ── Ritual & Ceremony ─────────────────────────────────────────────────────────
+/**
+ * Compute the morale and fear-reduction effects of a communal ritual.
+ *
+ * Each participant contributes their average (intrapersonal + musical) / 2
+ * to a shared cognitive pool. The collective effect scales with sqrt(N)
+ * (diminishing returns for large groups). The time factor scales linearly
+ * from 0 at 0 s to 1 at RITUAL_DURATION_s; durations beyond that are capped.
+ *
+ * moraleBonus_Q is capped at RITUAL_MAX_BONUS regardless of group size.
+ * fearReduction_Q = moraleBonus_Q × RITUAL_FEAR_REDUCTION_FRAC / SCALE.Q.
+ *
+ * @param participants   All entities taking part (pass only alive entities).
+ * @param elapsedSeconds Duration of the ritual session in seconds.
+ * @returns RitualResult to apply to all participants.
+ */
+export function stepRitual(participants, elapsedSeconds) {
+    const n = participants.length;
+    if (n === 0) {
+        return { moraleBonus_Q: q(0), fearReduction_Q: q(0), participantCount: 0 };
+    }
+    // Pool each participant's ritual cognitive capacity.
+    let sumPool = 0;
+    for (const p of participants) {
+        const intrap = p.attributes.cognition?.intrapersonal ?? 0;
+        const musical = p.attributes.cognition?.musical ?? 0;
+        sumPool += Math.trunc((intrap + musical) / 2);
+    }
+    const avgPool = Math.trunc(sumPool / n);
+    // sqrt(N) collective scaling in fixed-point.
+    // sqrtN_Q = floor(sqrt(N) × SCALE.Q)  e.g. N=4 → sqrtN_Q = 20 000
+    const sqrtN_Q = Math.trunc(Math.sqrt(n) * SCALE.Q);
+    // Time factor [0..SCALE.Q]: fraction of full ritual duration completed.
+    const timeFrac = Math.min(SCALE.Q, Math.round(elapsedSeconds * SCALE.Q / RITUAL_DURATION_s));
+    // effectivePool = avgPool × sqrt(N)   [Q-scaled]
+    const effectivePool = Math.round(avgPool * sqrtN_Q / SCALE.Q);
+    // rawBonus = effectivePool × timeFrac / SCALE.Q
+    const rawBonus = Math.round(effectivePool * timeFrac / SCALE.Q);
+    const moraleBonus_Q = clampQ(rawBonus, q(0), RITUAL_MAX_BONUS);
+    const fearReduction_Q = clampQ(Math.round(moraleBonus_Q * RITUAL_FEAR_REDUCTION_FRAC / SCALE.Q), q(0), moraleBonus_Q);
+    return { moraleBonus_Q, fearReduction_Q, participantCount: n };
+}
+// ── Trade Caravan Logistics ────────────────────────────────────────────────────
+/** Compute total route distance (SCALE.m) from ordered waypoints. */
+function routeTotalDistance(waypoints) {
+    let total = 0;
+    for (let i = 1; i < waypoints.length; i++) {
+        const a = waypoints[i - 1].position_m;
+        const b = waypoints[i].position_m;
+        const dx = Number(a.x) - Number(b.x);
+        const dy = Number(a.y) - Number(b.y);
+        const dz = Number(a.z) - Number(b.z);
+        total += Math.trunc(Math.sqrt(dx * dx + dy * dy + dz * dz));
+    }
+    return total;
+}
+/**
+ * Plan a trade caravan route, deriving logistics quality from participants'
+ * cognitive attributes and food sufficiency from the supplied inventory.
+ *
+ * Route quality (best logicalMathematical) shortens travel time:
+ *   speedFactor = q(0.80) + routeQuality_Q × q(0.20) / SCALE.Q  ∈ [q(0.80), q(1.00)]
+ *   adjustedTravelSeconds = baseSeconds × SCALE.Q / speedFactor
+ *
+ * Supply sufficiency = totalRations / (adjustedTravelDays × participants × RATIONS/DAY).
+ *
+ * @param waypoints     Ordered stops (position + rest hours).
+ * @param participants  Entities travelling with the caravan.
+ * @param inventory     Map<itemId, quantity> of food items available (all entries count).
+ * @returns             CaravanPlan with derived logistics values.
+ */
+export function planCaravanRoute(waypoints, participants, inventory) {
+    const participantIds = participants.map(p => p.id);
+    // ── Route quality: best navigator's logicalMathematical leads the route ─────
+    let bestLogical = 0;
+    for (const p of participants) {
+        const lm = p.attributes.cognition?.logicalMathematical ?? 0;
+        if (lm > bestLogical)
+            bestLogical = lm;
+    }
+    const routeQuality_Q = participants.length > 0
+        ? clampQ(bestLogical, q(0), SCALE.Q)
+        : q(0);
+    // ── Negotiation bonus: best interpersonal score ───────────────────────────
+    let bestInterpersonal = 0;
+    for (const p of participants) {
+        const ip = p.attributes.cognition?.interpersonal ?? 0;
+        if (ip > bestInterpersonal)
+            bestInterpersonal = ip;
+    }
+    const negotiationBonus_Q = clampQ(bestInterpersonal, q(0), SCALE.Q);
+    // ── Distance and base travel time ─────────────────────────────────────────
+    const totalDistance_Sm = routeTotalDistance(waypoints);
+    const baseTravelSeconds = CARAVAN_BASE_SPEED_Smps > 0
+        ? Math.trunc(totalDistance_Sm / CARAVAN_BASE_SPEED_Smps)
+        : 0;
+    // speedFactor ∈ [q(0.80), q(1.00)]: higher quality → closer to q(1.00)
+    // At routeQuality_Q = 0      → speedFactor = q(0.80) → 25 % slower than optimal
+    // At routeQuality_Q = SCALE.Q → speedFactor = q(1.00) → full base speed
+    const speedFactor = (q(0.80) + Math.round(routeQuality_Q * q(0.20) / SCALE.Q));
+    const adjustedTravelSeconds = speedFactor > 0
+        ? Math.round(baseTravelSeconds * SCALE.Q / speedFactor)
+        : baseTravelSeconds;
+    // ── Rest stops ────────────────────────────────────────────────────────────
+    const totalRestSeconds = waypoints.reduce((sum, w) => sum + Math.round(w.restHours * 3600), 0);
+    const estimatedTotalSeconds = adjustedTravelSeconds + totalRestSeconds;
+    // ── Supply sufficiency ────────────────────────────────────────────────────
+    let totalRations = 0;
+    for (const qty of inventory.values()) {
+        totalRations += Math.max(0, qty);
+    }
+    const travelDays = adjustedTravelSeconds / 86_400;
+    const rationsNeeded = travelDays * participants.length * CARAVAN_RATIONS_PER_PERSON_PER_DAY;
+    let supplySufficiency_Q;
+    if (rationsNeeded <= 0) {
+        supplySufficiency_Q = SCALE.Q;
+    }
+    else {
+        supplySufficiency_Q = clampQ(Math.round(totalRations * SCALE.Q / rationsNeeded), q(0), SCALE.Q);
+    }
+    // ── Deterministic plan ID ─────────────────────────────────────────────────
+    const planId = `caravan_${waypoints.map(w => w.positionId).join("_")}`;
+    return {
+        planId,
+        waypoints,
+        participantIds,
+        estimatedTravelSeconds: adjustedTravelSeconds,
+        estimatedTotalSeconds,
+        supplySufficiency_Q,
+        routeQuality_Q,
+        negotiationBonus_Q,
+    };
+}