@its-not-rocket-science/ananke 0.1.0

package/dist/src/legend.js

@@ -0,0 +1,269 @@
+// src/legend.ts — Phase 50: Mythology & Legend
+//
+// Chronicle entries of sufficient significance crystallise into Legends —
+// persistent reputation objects that NPCs query when deciding how to treat
+// an entity.  Legends affect dialogue (persuasion / intimidation probability),
+// NPC fear, and ally morale.
+//
+// Data flow:
+//   Chronicle (Phase 45) → createLegendFromChronicle → Legend
+//   Legend + NPC → npcKnowsLegend (fame roll) → LegendEffect modifiers
+//   LegendEffect → applyLegendToDialogueContext → bonus Q values for dialogue.ts
+import { SCALE, q, clampQ, mulDiv } from "./units.js";
+import { eventSeed } from "./sim/seeds.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Minimum significance score for a chronicle entry to contribute to a legend. */
+export const LEGEND_MIN_SIGNIFICANCE = 60;
+/** Denominator for fame_Q computation: 7 entries at max significance → q(1.0). */
+const FAME_SIGNIFICANCE_DIVISOR = 700;
+/** Fame floor for "legendary" reputation — never decays below this. */
+const LEGENDARY_FAME_FLOOR = q(0.50);
+/** Fame below this threshold → reputation becomes "forgotten". */
+const FORGOTTEN_FAME_THRESHOLD = q(0.10);
+/** Fame decay per 1000 ticks (slow, long-term erosion). */
+const FAME_DECAY_PER_1000_TICKS = 5;
+// ── Tag derivation ────────────────────────────────────────────────────────────
+const EVENT_TAGS = {
+    legendary_deed: "legendary_deed",
+    combat_victory: "warrior",
+    masterwork_crafted: "craftsman",
+    settlement_founded: "builder",
+    settlement_upgraded: "builder",
+    first_contact: "explorer",
+    quest_completed: "quester",
+    entity_death: "slayer",
+    rank_promotion: "officer",
+};
+const ARC_TAGS = {
+    rise_of_hero: "hero",
+    tragic_fall: "fallen_hero",
+    rivalry: "rival",
+    legendary_craftsman: "master_craftsman",
+    notorious_villain: "villain",
+    unlikely_friendship: "friend",
+    betrayal_and_redemption: "redeemed",
+};
+/** Derive thematic tags from chronicle entries and arc types. */
+function deriveTagsFromEntries(entries, arcTypes) {
+    const seen = new Set();
+    for (const e of entries) {
+        const tag = EVENT_TAGS[e.eventType];
+        if (tag)
+            seen.add(tag);
+    }
+    for (const arc of arcTypes) {
+        const tag = ARC_TAGS[arc];
+        if (tag)
+            seen.add(tag);
+    }
+    return Array.from(seen);
+}
+// ── Reputation classification ──────────────────────────────────────────────────
+/** Classify reputation from entries, arcs, and computed fame. */
+function classifyReputation(entries, arcTypes, fame_Q) {
+    if (fame_Q < FORGOTTEN_FAME_THRESHOLD)
+        return "forgotten";
+    const positiveArcs = [
+        "rise_of_hero", "settlement_growth", "legendary_craftsman", "unlikely_friendship",
+        "betrayal_and_redemption",
+    ];
+    const negativeArcs = ["notorious_villain", "tragic_fall"];
+    const hasPositiveArc = arcTypes.some(a => positiveArcs.includes(a));
+    const hasNegativeArc = arcTypes.some(a => negativeArcs.includes(a));
+    const hasLegendaryDeed = entries.some(e => e.eventType === "legendary_deed");
+    // Legendary = both positive and negative arcs, or legendary deed + high fame
+    if ((hasPositiveArc && hasNegativeArc) || (hasLegendaryDeed && fame_Q >= q(0.60))) {
+        return "legendary";
+    }
+    if (hasNegativeArc)
+        return "notorious";
+    return "heroic";
+}
+// ── Fame computation ──────────────────────────────────────────────────────────
+/** Compute fame_Q from total significance of qualifying entries. */
+function computeFameQ(entries, minSignificance) {
+    const total = entries
+        .filter(e => e.significance >= minSignificance)
+        .reduce((sum, e) => sum + e.significance, 0);
+    return clampQ(Math.trunc(total * SCALE.Q / FAME_SIGNIFICANCE_DIVISOR), q(0), SCALE.Q);
+}
+// ── Legend creation ───────────────────────────────────────────────────────────
+/**
+ * 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 function createLegendFromChronicle(chronicle, subjectId, subjectName, minSignificance = LEGEND_MIN_SIGNIFICANCE) {
+    const qualifyingEntries = chronicle.entries.filter(e => e.significance >= minSignificance && e.actors.includes(subjectId));
+    if (qualifyingEntries.length === 0)
+        return undefined;
+    const fame_Q = computeFameQ(qualifyingEntries, minSignificance);
+    const arcTypes = chronicle.detectedArcs.flatMap(arc => arc.primaryActors.includes(subjectId) ? [arc.arcType] : []);
+    const tags = deriveTagsFromEntries(qualifyingEntries, arcTypes);
+    const reputation = classifyReputation(qualifyingEntries, arcTypes, fame_Q);
+    const createdAtTick = qualifyingEntries[qualifyingEntries.length - 1].tick;
+    const legendId = `legend_${subjectId}_${createdAtTick}`;
+    return {
+        legendId,
+        subjectId,
+        subjectName,
+        reputation,
+        fame_Q,
+        tags,
+        sourceEntryIds: qualifyingEntries.map(e => e.entryId),
+        sourceArcTypes: arcTypes,
+        createdAtTick,
+    };
+}
+// ── Registry ──────────────────────────────────────────────────────────────────
+/** Create a new empty legend registry. */
+export function createLegendRegistry() {
+    return { legends: new Map(), bySubject: new Map() };
+}
+/** Register a legend in the registry. Overwrites any existing legend with the same ID. */
+export function registerLegend(registry, legend) {
+    registry.legends.set(legend.legendId, legend);
+    let ids = registry.bySubject.get(legend.subjectId);
+    if (!ids) {
+        ids = new Set();
+        registry.bySubject.set(legend.subjectId, ids);
+    }
+    ids.add(legend.legendId);
+}
+/** Get all legends about a specific entity. */
+export function getLegendsBySubject(registry, subjectId) {
+    const ids = registry.bySubject.get(subjectId);
+    if (!ids)
+        return [];
+    return Array.from(ids)
+        .map(id => registry.legends.get(id))
+        .filter((l) => l !== undefined);
+}
+// ── Effects ───────────────────────────────────────────────────────────────────
+/** Derive NPC-behavior modifiers from a legend. */
+export function getLegendEffect(legend) {
+    const f = legend.fame_Q;
+    switch (legend.reputation) {
+        case "heroic":
+            return {
+                persuasionBonus_Q: mulDiv(f, q(0.20), SCALE.Q),
+                intimidationBonus_Q: q(0),
+                fearBonus_Q: q(0),
+                moraleBonus_Q: mulDiv(f, q(0.10), SCALE.Q),
+            };
+        case "notorious":
+            return {
+                persuasionBonus_Q: q(0),
+                intimidationBonus_Q: mulDiv(f, q(0.25), SCALE.Q),
+                fearBonus_Q: mulDiv(f, q(0.15), SCALE.Q),
+                moraleBonus_Q: q(0),
+            };
+        case "legendary":
+            return {
+                persuasionBonus_Q: mulDiv(f, q(0.25), SCALE.Q),
+                intimidationBonus_Q: mulDiv(f, q(0.20), SCALE.Q),
+                fearBonus_Q: mulDiv(f, q(0.10), SCALE.Q),
+                moraleBonus_Q: mulDiv(f, q(0.15), SCALE.Q),
+            };
+        case "forgotten":
+        default:
+            return {
+                persuasionBonus_Q: q(0),
+                intimidationBonus_Q: q(0),
+                fearBonus_Q: q(0),
+                moraleBonus_Q: q(0),
+            };
+    }
+}
+// ── NPC awareness ─────────────────────────────────────────────────────────────
+/**
+ * Determine whether an NPC "knows" a legend.
+ *
+ * Deterministic: same (legend, npcId, worldSeed, tick) → same result.
+ * Probability = `legend.fame_Q / SCALE.Q`.
+ */
+export function npcKnowsLegend(legend, npcId, worldSeed, tick) {
+    if (legend.fame_Q <= q(0))
+        return false;
+    if (legend.fame_Q >= SCALE.Q)
+        return true;
+    // Deterministic salt from legendId characters
+    const legendSalt = legend.legendId
+        .split("")
+        .reduce((acc, c) => (acc + c.charCodeAt(0)) & 0xFFFFFF, 0);
+    const seed = eventSeed(worldSeed, tick, npcId, 0, legendSalt);
+    return (seed % SCALE.Q) < legend.fame_Q;
+}
+// ── Dialogue integration ──────────────────────────────────────────────────────
+/**
+ * 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 function applyLegendToDialogueContext(initiatorId, targetId, registry, worldSeed, tick) {
+    let persuasionBonus = 0;
+    let intimidationBonus = 0;
+    let fearBonus = 0;
+    for (const legend of getLegendsBySubject(registry, initiatorId)) {
+        if (!npcKnowsLegend(legend, targetId, worldSeed, tick))
+            continue;
+        const effect = getLegendEffect(legend);
+        persuasionBonus += effect.persuasionBonus_Q;
+        intimidationBonus += effect.intimidationBonus_Q;
+        fearBonus += effect.fearBonus_Q;
+    }
+    return {
+        persuasionBonus_Q: clampQ(persuasionBonus, q(0), q(0.50)),
+        intimidationBonus_Q: clampQ(intimidationBonus, q(0), q(0.50)),
+        fearBonus_Q: clampQ(fearBonus, q(0), q(0.50)),
+    };
+}
+// ── Fame decay ────────────────────────────────────────────────────────────────
+/**
+ * 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 function stepLegendFame(registry, deltaTicks) {
+    if (deltaTicks <= 0)
+        return;
+    const decay = Math.trunc(deltaTicks * FAME_DECAY_PER_1000_TICKS / 1000);
+    if (decay <= 0)
+        return;
+    for (const legend of registry.legends.values()) {
+        const floor = legend.reputation === "legendary" ? LEGENDARY_FAME_FLOOR : q(0);
+        legend.fame_Q = clampQ((legend.fame_Q - decay), floor, SCALE.Q);
+        if (legend.fame_Q < FORGOTTEN_FAME_THRESHOLD && legend.reputation !== "legendary") {
+            legend.reputation = "forgotten";
+        }
+    }
+}
+// ── Serialization ─────────────────────────────────────────────────────────────
+/** Serialize legend registry to JSON-friendly object. */
+export function serializeLegendRegistry(registry) {
+    return {
+        legends: Array.from(registry.legends.entries()),
+    };
+}
+/** Deserialize legend registry. */
+export function deserializeLegendRegistry(data) {
+    const registry = createLegendRegistry();
+    const d = data;
+    if (Array.isArray(d.legends)) {
+        for (const [id, legend] of d.legends) {
+            registry.legends.set(id, legend);
+            let ids = registry.bySubject.get(legend.subjectId);
+            if (!ids) {
+                ids = new Set();
+                registry.bySubject.set(legend.subjectId, ids);
+            }
+            ids.add(id);
+        }
+    }
+    return registry;
+}

package/dist/src/lod.d.ts

@@ -0,0 +1,9 @@
+import type { IndividualAttributes } from "./types.js";
+import { type Q } from "./units.js";
+export interface SquadAggregate {
+    count: number;
+    mean: IndividualAttributes;
+    cohesion: Q;
+    training: Q;
+}
+export declare function aggregateSquad(members: IndividualAttributes[]): SquadAggregate;

package/dist/src/lod.js

@@ -0,0 +1,84 @@
+import { q } from "./units.js";
+import { DEFAULT_PERCEPTION } from "./sim/sensory.js";
+export function aggregateSquad(members) {
+    const n = Math.max(1, members.length);
+    const sum = {
+        morphology: { stature_m: 0, mass_kg: 0, actuatorMass_kg: 0, actuatorScale: 0, structureScale: 0, reachScale: 0 },
+        performance: { peakForce_N: 0, peakPower_W: 0, continuousPower_W: 0, reserveEnergy_J: 0, conversionEfficiency: 0 },
+        control: { controlQuality: 0, reactionTime_s: 0, stability: 0, fineControl: 0 },
+        resilience: {
+            surfaceIntegrity: 0, bulkIntegrity: 0, structureIntegrity: 0,
+            distressTolerance: 0, shockTolerance: 0, concussionTolerance: 0,
+            heatTolerance: 0, coldTolerance: 0,
+            fatigueRate: 0, recoveryRate: 0,
+        },
+    };
+    for (const m of members) {
+        sum.morphology.stature_m += m.morphology.stature_m;
+        sum.morphology.mass_kg += m.morphology.mass_kg;
+        sum.morphology.actuatorMass_kg += m.morphology.actuatorMass_kg;
+        sum.morphology.actuatorScale += m.morphology.actuatorScale;
+        sum.morphology.structureScale += m.morphology.structureScale;
+        sum.morphology.reachScale += m.morphology.reachScale;
+        sum.performance.peakForce_N += m.performance.peakForce_N;
+        sum.performance.peakPower_W += m.performance.peakPower_W;
+        sum.performance.continuousPower_W += m.performance.continuousPower_W;
+        sum.performance.reserveEnergy_J += m.performance.reserveEnergy_J;
+        sum.performance.conversionEfficiency += m.performance.conversionEfficiency;
+        sum.control.controlQuality += m.control.controlQuality;
+        sum.control.reactionTime_s += m.control.reactionTime_s;
+        sum.control.stability += m.control.stability;
+        sum.control.fineControl += m.control.fineControl;
+        sum.resilience.surfaceIntegrity += m.resilience.surfaceIntegrity;
+        sum.resilience.bulkIntegrity += m.resilience.bulkIntegrity;
+        sum.resilience.structureIntegrity += m.resilience.structureIntegrity;
+        sum.resilience.distressTolerance += m.resilience.distressTolerance;
+        sum.resilience.shockTolerance += m.resilience.shockTolerance;
+        sum.resilience.concussionTolerance += m.resilience.concussionTolerance;
+        sum.resilience.heatTolerance += m.resilience.heatTolerance;
+        sum.resilience.coldTolerance += m.resilience.coldTolerance;
+        sum.resilience.fatigueRate += m.resilience.fatigueRate;
+        sum.resilience.recoveryRate += m.resilience.recoveryRate;
+    }
+    const div = (x) => Math.trunc(x / n);
+    const divQ = (x) => Math.trunc(x / n);
+    const mean = {
+        morphology: {
+            stature_m: div(sum.morphology.stature_m),
+            mass_kg: div(sum.morphology.mass_kg),
+            actuatorMass_kg: div(sum.morphology.actuatorMass_kg),
+            actuatorScale: divQ(sum.morphology.actuatorScale),
+            structureScale: divQ(sum.morphology.structureScale),
+            reachScale: divQ(sum.morphology.reachScale),
+        },
+        performance: {
+            peakForce_N: div(sum.performance.peakForce_N),
+            peakPower_W: div(sum.performance.peakPower_W),
+            continuousPower_W: div(sum.performance.continuousPower_W),
+            reserveEnergy_J: div(sum.performance.reserveEnergy_J),
+            conversionEfficiency: divQ(sum.performance.conversionEfficiency),
+        },
+        control: {
+            controlQuality: divQ(sum.control.controlQuality),
+            reactionTime_s: divQ(sum.control.reactionTime_s),
+            stability: divQ(sum.control.stability),
+            fineControl: div(sum.control.fineControl),
+        },
+        resilience: {
+            surfaceIntegrity: divQ(sum.resilience.surfaceIntegrity),
+            bulkIntegrity: divQ(sum.resilience.bulkIntegrity),
+            structureIntegrity: divQ(sum.resilience.structureIntegrity),
+            distressTolerance: divQ(sum.resilience.distressTolerance),
+            shockTolerance: divQ(sum.resilience.shockTolerance),
+            concussionTolerance: divQ(sum.resilience.concussionTolerance),
+            heatTolerance: divQ(sum.resilience.heatTolerance),
+            coldTolerance: divQ(sum.resilience.coldTolerance),
+            fatigueRate: divQ(sum.resilience.fatigueRate),
+            recoveryRate: div(sum.resilience.recoveryRate),
+        },
+        // Perception is a species characteristic, not averaged across individuals.
+        // Use DEFAULT_PERCEPTION as a neutral aggregate placeholder.
+        perception: DEFAULT_PERCEPTION,
+    };
+    return { count: n, mean, cohesion: q(0.75), training: q(0.65) };
+}

package/dist/src/metrics.d.ts

@@ -0,0 +1,51 @@
+import type { TraceEvent, TraceSink } from "./sim/trace.js";
+/** Accumulated metrics derived from a sequence of trace events. */
+export interface CombatMetrics {
+    /** Total energy (J) delivered by each attacker entity (melee + ranged). */
+    damageDealt: Map<number, number>;
+    /** Number of successful hit events (melee Attack or ranged hit) per attacker. */
+    hitsLanded: Map<number, number>;
+    /** Number of times each entity was hit. */
+    hitsTaken: Map<number, number>;
+    /** First tick at which each entity received a KO event. */
+    tickOfKO: Map<number, number>;
+    /** First tick at which each entity died. */
+    tickOfDeath: Map<number, number>;
+    /**
+     * First tick at which each entity was incapacitated (KO or death, whichever came first).
+     * Entities that remained combat-capable throughout are absent from this map.
+     */
+    tickToIncapacitation: Map<number, number>;
+}
+/**
+ * Derive combat metrics from a flat array of trace events.
+ * Events from any number of ticks may be mixed; ordering is not required.
+ */
+export declare function collectMetrics(events: readonly TraceEvent[]): CombatMetrics;
+/**
+ * Fraction of `entityIds` that were never incapacitated (KO or death) in `events`.
+ * Returns 1.0 if `entityIds` is empty.
+ */
+export declare function survivalRate(events: readonly TraceEvent[], entityIds: readonly number[]): number;
+/**
+ * Mean tick-to-incapacitation across the given entities.
+ * Entities that were never incapacitated contribute `totalTicks` to the average
+ * (i.e. they survived the full duration).
+ *
+ * Returns `totalTicks` if no entity was incapacitated.
+ */
+export declare function meanTimeToIncapacitation(events: readonly TraceEvent[], entityIds: readonly number[], totalTicks: number): number;
+/**
+ * A TraceSink that accumulates all events into an array for later analysis.
+ *
+ * Usage:
+ *   const tracer = new CollectingTrace();
+ *   stepWorld(world, cmds, { ...ctx, trace: tracer });
+ *   const metrics = collectMetrics(tracer.events);
+ */
+export declare class CollectingTrace implements TraceSink {
+    readonly events: TraceEvent[];
+    onEvent(ev: TraceEvent): void;
+    /** Remove all accumulated events. */
+    clear(): void;
+}

package/dist/src/metrics.js

@@ -0,0 +1,91 @@
+// src/metrics.ts — Phase 13: combat metrics and analytics
+import { TraceKinds } from "./sim/kinds.js";
+// ── Core analytics ────────────────────────────────────────────────────────────
+/**
+ * Derive combat metrics from a flat array of trace events.
+ * Events from any number of ticks may be mixed; ordering is not required.
+ */
+export function collectMetrics(events) {
+    const damageDealt = new Map();
+    const hitsLanded = new Map();
+    const hitsTaken = new Map();
+    const tickOfKO = new Map();
+    const tickOfDeath = new Map();
+    for (const ev of events) {
+        if (ev.kind === TraceKinds.Attack) {
+            damageDealt.set(ev.attackerId, (damageDealt.get(ev.attackerId) ?? 0) + ev.energy_J);
+            hitsLanded.set(ev.attackerId, (hitsLanded.get(ev.attackerId) ?? 0) + 1);
+            hitsTaken.set(ev.targetId, (hitsTaken.get(ev.targetId) ?? 0) + 1);
+        }
+        else if (ev.kind === TraceKinds.ProjectileHit && ev.hit) {
+            damageDealt.set(ev.shooterId, (damageDealt.get(ev.shooterId) ?? 0) + ev.energyAtImpact_J);
+            hitsLanded.set(ev.shooterId, (hitsLanded.get(ev.shooterId) ?? 0) + 1);
+            if (ev.targetId !== undefined) {
+                hitsTaken.set(ev.targetId, (hitsTaken.get(ev.targetId) ?? 0) + 1);
+            }
+        }
+        else if (ev.kind === TraceKinds.KO) {
+            if (!tickOfKO.has(ev.entityId))
+                tickOfKO.set(ev.entityId, ev.tick);
+        }
+        else if (ev.kind === TraceKinds.Death) {
+            if (!tickOfDeath.has(ev.entityId))
+                tickOfDeath.set(ev.entityId, ev.tick);
+        }
+    }
+    // tickToIncapacitation = min(tickOfKO, tickOfDeath) per entity
+    const tickToIncapacitation = new Map();
+    for (const [id, t] of tickOfKO)
+        tickToIncapacitation.set(id, t);
+    for (const [id, t] of tickOfDeath) {
+        const prev = tickToIncapacitation.get(id);
+        tickToIncapacitation.set(id, prev === undefined ? t : Math.min(prev, t));
+    }
+    return { damageDealt, hitsLanded, hitsTaken, tickOfKO, tickOfDeath, tickToIncapacitation };
+}
+/**
+ * Fraction of `entityIds` that were never incapacitated (KO or death) in `events`.
+ * Returns 1.0 if `entityIds` is empty.
+ */
+export function survivalRate(events, entityIds) {
+    if (entityIds.length === 0)
+        return 1.0;
+    const { tickToIncapacitation } = collectMetrics(events);
+    const incapCount = entityIds.filter(id => tickToIncapacitation.has(id)).length;
+    return (entityIds.length - incapCount) / entityIds.length;
+}
+/**
+ * Mean tick-to-incapacitation across the given entities.
+ * Entities that were never incapacitated contribute `totalTicks` to the average
+ * (i.e. they survived the full duration).
+ *
+ * Returns `totalTicks` if no entity was incapacitated.
+ */
+export function meanTimeToIncapacitation(events, entityIds, totalTicks) {
+    if (entityIds.length === 0)
+        return totalTicks;
+    const { tickToIncapacitation } = collectMetrics(events);
+    const total = entityIds.reduce((sum, id) => {
+        return sum + (tickToIncapacitation.get(id) ?? totalTicks);
+    }, 0);
+    return total / entityIds.length;
+}
+// ── CollectingTrace ───────────────────────────────────────────────────────────
+/**
+ * A TraceSink that accumulates all events into an array for later analysis.
+ *
+ * Usage:
+ *   const tracer = new CollectingTrace();
+ *   stepWorld(world, cmds, { ...ctx, trace: tracer });
+ *   const metrics = collectMetrics(tracer.events);
+ */
+export class CollectingTrace {
+    events = [];
+    onEvent(ev) {
+        this.events.push(ev);
+    }
+    /** Remove all accumulated events. */
+    clear() {
+        this.events.length = 0;
+    }
+}

package/dist/src/model3d.d.ts

@@ -0,0 +1,138 @@
+import type { WorldState } from "./sim/world.js";
+import type { Entity } from "./sim/entity.js";
+import type { GrapplePosition } from "./sim/entity.js";
+import type { Q } from "./units.js";
+/** Per-segment mass and its fraction of total body mass. */
+export interface SegmentMass {
+    segmentId: string;
+    /** Fixed-point kg (SCALE.kg = 1000; 5 kg = 5000). */
+    mass_kg: number;
+    /** Fraction of total body mass (Q; q(1.0) = 100% of body mass). */
+    fractionQ: Q;
+}
+/**
+ * Mass distribution and estimated centre of gravity for an entity.
+ * CoG is in real metres above the entity's foot position (world y = 0).
+ */
+export interface MassDistribution {
+    /** Total body mass in fixed-point kg (SCALE.kg = 1000). */
+    totalMass_kg: number;
+    segments: SegmentMass[];
+    /**
+     * Estimated centre of gravity in real metres.
+     * y = height above feet; x = lateral offset (negative = anatomical left).
+     */
+    cogOffset_m: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Derive mass distribution and centre of gravity from entity body plan.
+ * Falls back to a single "body" segment at the geometric midpoint when no
+ * body plan is present.
+ */
+export declare function deriveMassDistribution(entity: Entity): MassDistribution;
+/**
+ * Simplified diagonal inertia tensor about the entity's principal axes
+ * (kg·m²). z offsets are assumed zero (planar estimation).
+ */
+export interface InertiaTensor {
+    /** About vertical (yaw) axis — governs turn rate. */
+    yaw_kgm2: number;
+    /** About lateral (pitch) axis — governs forward lean. */
+    pitch_kgm2: number;
+    /** About fore-aft (roll) axis — governs side lean. */
+    roll_kgm2: number;
+}
+/**
+ * Derive a simplified diagonal inertia tensor from entity body plan.
+ * Falls back to a solid-sphere approximation when no body plan is present.
+ */
+export declare function deriveInertiaTensor(entity: Entity): InertiaTensor;
+/**
+ * Animation blend weights and state flags derived from entity physical state.
+ * Locomotion weights (idle/walk/run/sprint/crawl) are mutually exclusive;
+ * exactly one is SCALE.Q when the entity is mobile.
+ * All Q values in [0, SCALE.Q].
+ */
+export interface AnimationHints {
+    /** Locomotion blend — mutually exclusive. */
+    idle: Q;
+    walk: Q;
+    run: Q;
+    sprint: Q;
+    crawl: Q;
+    /** Active defence blend weight (derived from intent.defence.intensity). */
+    guardingQ: Q;
+    /**
+     * Attack blend weight — nonzero while attack cooldown is active, indicating
+     * the entity is mid-swing or recovering from a strike.
+     */
+    attackingQ: Q;
+    /** Physiological condition overlays (direct pass-through from entity state). */
+    shockQ: Q;
+    fearQ: Q;
+    /** Positional state flags. */
+    prone: boolean;
+    unconscious: boolean;
+    dead: boolean;
+}
+/**
+ * Derive animation hints from entity intent, condition, and injury state.
+ */
+export declare function deriveAnimationHints(entity: Entity): AnimationHints;
+/**
+ * Per-region injury state as a deformation blend weight for the host rig.
+ * A host renderer maps each segmentId to a skeleton bone and drives blend
+ * shape or constraint weights from impairmentQ.
+ */
+export interface PoseModifier {
+    segmentId: string;
+    /** Overall deformation blend: max(structuralQ, surfaceQ). */
+    impairmentQ: Q;
+    structuralQ: Q;
+    surfaceQ: Q;
+}
+/**
+ * Derive per-region pose modifiers from entity injury state.
+ * Returns one entry per injury region (byRegion keys).
+ */
+export declare function derivePoseModifiers(entity: Entity): PoseModifier[];
+/**
+ * Grapple relationship for pose-constraint solving.
+ * A host renderer uses this to lock relative pose between grappling entities.
+ */
+export interface GrapplePoseConstraint {
+    isHolder: boolean;
+    holdingEntityId?: number;
+    isHeld: boolean;
+    heldByIds: number[];
+    position: GrapplePosition;
+    gripQ: Q;
+}
+/**
+ * Derive grapple pose constraint from entity grapple state.
+ */
+export declare function deriveGrappleConstraint(entity: Entity): GrapplePoseConstraint;
+/**
+ * Complete per-entity rig data for a single simulation tick.
+ * Aggregates all Phase 14 outputs for convenient host consumption.
+ * Call extractRigSnapshots once per tick after stepWorld.
+ */
+export interface RigSnapshot {
+    entityId: number;
+    teamId: number;
+    tick: number;
+    mass: MassDistribution;
+    inertia: InertiaTensor;
+    animation: AnimationHints;
+    pose: PoseModifier[];
+    grapple: GrapplePoseConstraint;
+}
+/**
+ * Extract a full rig snapshot for every entity in the world.
+ * Combine with extractMotionVectors and extractConditionSamples from
+ * src/debug.ts for a complete per-tick visualisation feed.
+ */
+export declare function extractRigSnapshots(world: WorldState): RigSnapshot[];