@its-not-rocket-science/ananke 0.1.0

package/dist/src/faction.js

@@ -0,0 +1,237 @@
+// src/faction.ts — Phase 24: Faction & Reputation System
+//
+// Tracks faction membership, inter-faction standing, entity reputation, and
+// the witness system that propagates reputation deltas from combat events.
+//
+// No kernel import — pure data-management module.
+import { SCALE, q, clampQ } from "./units.js";
+import { TraceKinds } from "./sim/kinds.js";
+import { canDetect, DEFAULT_SENSORY_ENV } from "./sim/sensory.js";
+// ── Standing constants ────────────────────────────────────────────────────────
+export const STANDING_EXALTED = q(1.0); // Intra-faction default
+export const STANDING_ALLY = q(0.70); // Allied faction default
+export const STANDING_NEUTRAL = q(0.50); // Unknown faction default
+export const STANDING_RIVAL = q(0.20); // Rival faction default
+export const STANDING_KOS = q(0.0); // Kill on sight
+/** Standing below this → AI treats target as hostile. */
+export const STANDING_HOSTILE_THRESHOLD = q(0.30);
+/** Standing above this → AI will not initiate combat. */
+export const STANDING_FRIENDLY_THRESHOLD = q(0.70);
+/** Minimum detection quality for an entity to witness an event. */
+export const WITNESS_DETECTION_THRESHOLD = q(0.60);
+// ── Witness event delta magnitudes ────────────────────────────────────────────
+const DELTA_KILL = q(-0.15);
+const DELTA_ASSAULT = q(-0.05);
+const DELTA_AID = q(0.08);
+// ── Map-aware serialisation helpers ──────────────────────────────────────────
+const MAP_MARKER = "__ananke_map__";
+const SET_MARKER = "__ananke_set__";
+function replacer(_key, value) {
+    if (value instanceof Map) {
+        return { [MAP_MARKER]: true, entries: [...value.entries()] };
+    }
+    if (value instanceof Set) {
+        return { [SET_MARKER]: true, values: [...value.values()] };
+    }
+    return value;
+}
+function reviver(_key, value) {
+    if (value !== null && typeof value === "object") {
+        const v = value;
+        if (v[MAP_MARKER] === true) {
+            return new Map(v.entries);
+        }
+        if (v[SET_MARKER] === true) {
+            return new Set(v.values);
+        }
+    }
+    return value;
+}
+// ── Factory ───────────────────────────────────────────────────────────────────
+/**
+ * Create a FactionRegistry pre-populated with rival/ally default standings.
+ *
+ * Only direct relations need to be specified; symmetric standings are NOT
+ * applied automatically (enemy of A is not necessarily enemy of B).
+ */
+export function createFactionRegistry(factions) {
+    const factionMap = new Map(factions.map(f => [f.id, f]));
+    const globalStanding = new Map();
+    for (const f of factions) {
+        const row = new Map();
+        for (const rival of f.rivals)
+            row.set(rival, STANDING_RIVAL);
+        for (const ally of f.allies)
+            row.set(ally, STANDING_ALLY);
+        globalStanding.set(f.id, row);
+    }
+    return {
+        factions: factionMap,
+        globalStanding,
+        entityReputations: new Map(),
+    };
+}
+// ── Standing computation ──────────────────────────────────────────────────────
+/**
+ * Compute effective standing of entity `a` toward entity `b`.
+ *
+ * Priority (highest first):
+ * 1. Same faction → STANDING_EXALTED
+ * 2. Entity-level reputation (`registry.entityReputations.get(a.id)?.get(b.faction)`)
+ *    combined with faction default — max of the two is used.
+ * 3. Global faction-to-faction standing
+ * 4. Rival / ally default from faction definition
+ * 5. STANDING_NEUTRAL (q(0.50)) for all unknown combinations
+ */
+export function effectiveStanding(registry, a, b) {
+    const aFaction = a.faction;
+    const bFaction = b.faction;
+    // Same faction → exalted
+    if (aFaction && bFaction && aFaction === bFaction)
+        return STANDING_EXALTED;
+    // Entity-level reputation of a toward b's faction
+    const personalQ = bFaction
+        ? registry.entityReputations.get(a.id)?.get(bFaction)
+        : undefined;
+    // Faction-level standing of a's faction toward b's faction
+    let factionQ;
+    if (aFaction && bFaction) {
+        factionQ = registry.globalStanding.get(aFaction)?.get(bFaction);
+    }
+    // Combined: max of personal and faction (most favourable wins)
+    if (personalQ !== undefined && factionQ !== undefined) {
+        return Math.max(personalQ, factionQ);
+    }
+    if (personalQ !== undefined)
+        return personalQ;
+    if (factionQ !== undefined)
+        return factionQ;
+    return STANDING_NEUTRAL;
+}
+// ── Witness event application ─────────────────────────────────────────────────
+/**
+ * Apply a witness event: adjust the actor's standing within the specified faction.
+ *
+ * Deltas are clamped to [0, SCALE.Q].  A kill of a faction member reduces the
+ * actor's standing with that faction; aiding a member increases it.
+ */
+export function applyWitnessEvent(registry, event) {
+    let reps = registry.entityReputations.get(event.actorId);
+    if (!reps) {
+        reps = new Map();
+        registry.entityReputations.set(event.actorId, reps);
+    }
+    const current = reps.get(event.factionId) ?? STANDING_NEUTRAL;
+    reps.set(event.factionId, clampQ(current + event.delta, 0, SCALE.Q));
+}
+// ── Witness extraction ────────────────────────────────────────────────────────
+/**
+ * Scan a TraceEvent stream and produce WitnessEvents for reputation-relevant
+ * actions (kills, assaults, aid).
+ *
+ * Only events where at least one bystander entity (not the actor or target) can
+ * detect the actor (`detectionQ ≥ WITNESS_DETECTION_THRESHOLD`) are included.
+ *
+ * Deduplication: at most one event per (actorId, eventType) per tick.
+ *
+ * @param factions  Map of entityId → factionId for the current scenario.
+ */
+export function extractWitnessEvents(events, world, factions) {
+    // First pass: collect which entities die each tick
+    const deaths = new Set();
+    for (const ev of events) {
+        if (ev.kind === TraceKinds.Death) {
+            deaths.add(`${ev.entityId}:${ev.tick}`);
+        }
+    }
+    const results = [];
+    const seen = new Set(); // dedupKey = `${actorId}:${eventType}:${tick}`
+    for (const ev of events) {
+        let actorId;
+        let targetId;
+        let eventType;
+        let delta;
+        if (ev.kind === TraceKinds.Attack && !ev.blocked && !ev.parried && ev.energy_J > 0) {
+            actorId = ev.attackerId;
+            targetId = ev.targetId;
+            const isKill = deaths.has(`${ev.targetId}:${ev.tick}`);
+            eventType = isKill ? "kill" : "assault";
+            delta = isKill ? DELTA_KILL : DELTA_ASSAULT;
+        }
+        else if (ev.kind === TraceKinds.TreatmentApplied) {
+            actorId = ev.treaterId;
+            targetId = ev.targetId;
+            eventType = "aid";
+            delta = DELTA_AID;
+        }
+        if (actorId === undefined || targetId === undefined || !eventType || delta === undefined) {
+            continue;
+        }
+        const dedupKey = `${actorId}:${eventType}:${ev.tick}`;
+        if (seen.has(dedupKey))
+            continue;
+        // Faction that cares: the target's faction
+        const targetFactionId = factions.get(targetId);
+        if (!targetFactionId)
+            continue;
+        // Check for at least one bystander witness
+        const actor = world.entities.find(e => e.id === actorId);
+        if (!actor)
+            continue;
+        let hasWitness = false;
+        for (const witness of world.entities) {
+            if (witness.id === actorId || witness.id === targetId)
+                continue;
+            if (witness.injury.dead)
+                continue;
+            if (canDetect(witness, actor, DEFAULT_SENSORY_ENV) >= WITNESS_DETECTION_THRESHOLD) {
+                hasWitness = true;
+                break;
+            }
+        }
+        if (!hasWitness)
+            continue;
+        seen.add(dedupKey);
+        results.push({
+            actorId,
+            targetId,
+            eventType,
+            factionId: targetFactionId,
+            delta,
+            tick: ev.tick,
+        });
+    }
+    return results;
+}
+// ── Faction-level standing mutation ──────────────────────────────────────────
+/**
+ * Adjust the global faction-to-faction standing of `factionAId` toward
+ * `factionBId` by `delta`, clamped to [0, SCALE.Q].
+ *
+ * Used by the Polity diplomacy system (Phase 61) to apply `standingDelta`
+ * from `resolveDiplomacy`.  The relation is one-directional; call twice with
+ * swapped arguments for a symmetric update.
+ */
+export function applyFactionStanding(registry, factionAId, factionBId, delta) {
+    let row = registry.globalStanding.get(factionAId);
+    if (!row) {
+        row = new Map();
+        registry.globalStanding.set(factionAId, row);
+    }
+    const current = row.get(factionBId) ?? STANDING_NEUTRAL;
+    row.set(factionBId, clampQ(current + delta, 0, SCALE.Q));
+}
+// ── Serialisation ─────────────────────────────────────────────────────────────
+/**
+ * Serialise a FactionRegistry to a JSON string.
+ * Handles all nested Map and Set fields (rivals, allies, globalStanding, entityReputations).
+ */
+export function serialiseFactionRegistry(registry) {
+    return JSON.stringify(registry, replacer);
+}
+/**
+ * Deserialise a FactionRegistry from a JSON string produced by `serialiseFactionRegistry`.
+ */
+export function deserialiseFactionRegistry(json) {
+    return JSON.parse(json, reviver);
+}

package/dist/src/generate.d.ts

@@ -0,0 +1,35 @@
+import type { IndividualAttributes } from "./types.js";
+import type { Archetype } from "./archetypes.js";
+/**
+ * Signed bias applied to a character-generation axis, range [−1, 1].
+ *
+ * `+1` strongly skews toward the high end of the archetype's natural spread;
+ * `−1` toward the low end.  Values outside [−1, 1] are clamped internally.
+ * A biased character is still drawn from the population — just from a
+ * different part of the tail — so physical plausibility is preserved.
+ *
+ * Fields map to these generation axes:
+ *   `strength`   peakForce_N, peakPower_W, continuousPower_W, actuatorScale
+ *   `speed`      reactionTime_s  (positive bias → faster; i.e. lower time)
+ *   `resilience` distressTolerance, shockTolerance, concussionTolerance,
+ *                surface/bulk/structureIntegrity, recoveryRate
+ *                (positive bias also reduces fatigueRate)
+ *   `agility`    controlQuality, fineControl, stability
+ *   `size`       stature_m, mass_kg  (also influences reach)
+ *
+ * Note: per-individual cognitive variance (`intellect` bias) is reserved for
+ * a future phase once `Archetype.cognition` gains per-individual draws.
+ */
+export interface NarrativeBias {
+    /** Biases physical force and power output. */
+    strength?: number;
+    /** Biases reaction speed. Positive = faster (lower reactionTime_s). */
+    speed?: number;
+    /** Biases damage tolerance and recovery. Positive = tougher. */
+    resilience?: number;
+    /** Biases motor control precision and stability. */
+    agility?: number;
+    /** Biases body size (stature and mass). */
+    size?: number;
+}
+export declare function generateIndividual(seedU32: number, arch: Archetype, bias?: NarrativeBias): IndividualAttributes;

package/dist/src/generate.js

@@ -0,0 +1,166 @@
+/*
+Morphology scaling philosophy:
+
+We intentionally damp size → strength scaling.
+
+Real biology:
+- strength ∝ cross-section (~mass^(2/3))
+- mass ∝ volume
+- energy cost grows faster than usable force
+
+Gameplay:
+- prevents giants from dominating
+- keeps small entities viable
+- allows cross-species balance
+
+Therefore:
+Most morphology scaling uses PARTIAL influence
+(~20–35% of raw geometric scaling)
+*/
+import { makeRng } from "./rng.js";
+import { SCALE, clampQ, q, qMul, mulDiv } from "./units.js";
+import { triSym, biasedTriSym, mulFromVariation, skewUp } from "./dist.js";
+// Math.cos is allowed here: generation path, not simulation path.
+function halfArcCosQ(arcDeg) {
+    const halfRad = (arcDeg / 2) * (Math.PI / 180);
+    return Math.round(Math.cos(halfRad) * SCALE.Q);
+}
+function applyMultI32(base, multQ) {
+    return mulDiv(base, multQ, SCALE.Q);
+}
+function clampI32(x, lo, hi) {
+    return Math.max(lo, Math.min(hi, x));
+}
+function sqrtNear1Q(mult) {
+    return (mult + SCALE.Q) >>> 1;
+}
+export function generateIndividual(seedU32, arch, bias) {
+    const rng = makeRng(seedU32 >>> 0, SCALE.Q);
+    // Convenience: biasedTriSym(rng, 0) === triSym(rng), so unbiased calls
+    // are identical to the previous behaviour when bias is undefined.
+    const sz = bias?.size ?? 0;
+    const str = bias?.strength ?? 0;
+    const spd = bias?.speed ?? 0;
+    const res = bias?.resilience ?? 0;
+    const agi = bias?.agility ?? 0;
+    const statureMult = mulFromVariation(biasedTriSym(rng, sz), arch.statureVar);
+    const massMult = mulFromVariation(biasedTriSym(rng, sz), arch.massVar);
+    const reachMult = mulFromVariation(biasedTriSym(rng, sz), arch.reachVar);
+    const actuatorScaleBase = mulFromVariation(biasedTriSym(rng, str), arch.actuatorScaleVar);
+    // Combine stature + mass into a single “size composite”.
+    // We use sqrt scaling to avoid extreme linear growth:
+    //  - doubling mass should NOT double strength directly
+    //  - tall + heavy should scale sub-linearly
+    const sizeComposite = qMul(sqrtNear1Q(statureMult), sqrtNear1Q(massMult));
+    /*
+    Actuator scaling rule:
+    
+    We do NOT apply full sizeComposite directly to force/power.
+    Instead we apply only ~25% of size deviation from baseline.
+    
+    Why:
+    - Prevent giant entities becoming absurdly strong
+    - Prevent small entities becoming unusably weak
+    - Maintain cross-species balance
+    - Keep simulation numerically stable
+    
+    Formula:
+    effectiveScale = 1 + (sizeComposite - 1) * 1.34
+    
+    51% geometric scaling (damped).
+    */
+    const actuatorScale = clampQ(qMul(actuatorScaleBase, (SCALE.Q + mulDiv(sizeComposite - SCALE.Q, q(1.34), SCALE.Q))), q(0.6), // lower bound: still functional
+    q(1.8) // upper bound: avoid runaway strength
+    );
+    const structureScaleBase = mulFromVariation(biasedTriSym(rng, res), arch.structureScaleVar);
+    const structureScale = clampQ(qMul(structureScaleBase, (SCALE.Q + ((sizeComposite - SCALE.Q) >>> 3))), q(0.7), q(2.0));
+    const stature_m = applyMultI32(arch.stature_m, statureMult);
+    const mass_kg = applyMultI32(arch.mass_kg, massMult);
+    const actuatorFracVar = mulFromVariation(biasedTriSym(rng, str), arch.actuatorMassVar);
+    const actuatorFrac = clampQ(qMul(arch.actuatorMassFrac, actuatorFracVar), q(0.15), q(0.70));
+    const actuatorMass_kg_raw = mulDiv(mass_kg, actuatorFrac, SCALE.Q);
+    const actuatorMass_kg = clampI32(actuatorMass_kg_raw, mulDiv(mass_kg, q(0.15), SCALE.Q), mulDiv(mass_kg, q(0.70), SCALE.Q));
+    const forceRand = mulFromVariation(biasedTriSym(rng, str), arch.peakForceVar);
+    const forceCouple = clampQ(qMul(actuatorScale, (SCALE.Q + ((actuatorFrac - arch.actuatorMassFrac) >> 1))), q(0.6), q(2.2));
+    const peakForceMult = clampQ(qMul(forceRand, forceCouple), q(0.5), q(2.5));
+    const powerRand = mulFromVariation(biasedTriSym(rng, str), arch.peakPowerVar);
+    const powerMult = clampQ(skewUp(qMul(powerRand, actuatorScale), 1), q(0.5), q(3.0));
+    const contRand = mulFromVariation(biasedTriSym(rng, str), arch.continuousPowerVar);
+    const contMult = clampQ(qMul(contRand, sqrtNear1Q(actuatorFrac)), q(0.4), q(3.0));
+    const reserveRand = mulFromVariation(biasedTriSym(rng, res), arch.reserveEnergyVar);
+    const reserveMult = clampQ(qMul(reserveRand, sqrtNear1Q(actuatorFrac)), q(0.3), q(4.0));
+    const effMult = mulFromVariation(biasedTriSym(rng, str), arch.efficiencyVar);
+    const conversionEfficiency = clampQ(qMul(arch.conversionEfficiency, effMult), q(0.45), q(0.98));
+    const peakForce_N = applyMultI32(arch.peakForce_N, peakForceMult);
+    const peakPower_W = applyMultI32(arch.peakPower_W, powerMult);
+    const continuousPower_W = applyMultI32(arch.continuousPower_W, contMult);
+    const reserveEnergy_J = applyMultI32(arch.reserveEnergy_J, reserveMult);
+    const controlMult = mulFromVariation(biasedTriSym(rng, agi), arch.controlVar);
+    const controlQuality = clampQ(qMul(arch.controlQuality, controlMult), q(0.15), q(0.98));
+    // speed bias is negated: +speed → shorter (faster) reactionTime
+    const reactMult = mulFromVariation(biasedTriSym(rng, -spd), arch.reactionTimeVar);
+    const reactCouple = clampQ((SCALE.Q + ((SCALE.Q - controlQuality) >>> 2)), q(0.75), q(1.30));
+    const reactionTime_s = applyMultI32(arch.reactionTime_s, qMul(reactMult, reactCouple));
+    const stability = clampQ(qMul(arch.stability, mulFromVariation(biasedTriSym(rng, agi), arch.stabilityVar)), q(0.05), q(0.99));
+    const rawFineControl = clampQ(qMul(arch.fineControl, mulFromVariation(biasedTriSym(rng, agi), arch.fineControlVar)), q(0.05), q(0.99));
+    // Phase 33: bodilyKinesthetic sets a floor on fine motor precision
+    const bkFloor = arch.cognition ? qMul(arch.cognition.bodilyKinesthetic, q(0.80)) : q(0);
+    const fineControl = clampQ(Math.max(rawFineControl, bkFloor), q(0.05), q(0.99));
+    const surfaceIntegrity = clampQ(qMul(arch.surfaceIntegrity, mulFromVariation(biasedTriSym(rng, res), arch.surfaceVar)), q(0.4), q(3.0));
+    const bulkIntegrity = clampQ(qMul(arch.bulkIntegrity, mulFromVariation(biasedTriSym(rng, res), arch.bulkVar)), q(0.4), q(3.0));
+    const structureIntegrity = clampQ(qMul(arch.structureIntegrity, mulFromVariation(biasedTriSym(rng, res), arch.structVar)), q(0.4), q(3.0));
+    const distressTolerance = clampQ(qMul(arch.distressTolerance, mulFromVariation(biasedTriSym(rng, res), arch.distressVar)), q(0.01), q(0.98));
+    const shockTolerance = clampQ(qMul(arch.shockTolerance, mulFromVariation(biasedTriSym(rng, res), arch.shockVar)), q(0.01), q(0.98));
+    const concussionTolerance = clampQ(qMul(arch.concussionTolerance, mulFromVariation(biasedTriSym(rng, res), arch.concVar)), q(0.01), q(0.98));
+    const heatTolerance = clampQ(qMul(arch.heatTolerance, mulFromVariation(triSym(rng), arch.heatVar)), q(0.01), q(0.98));
+    const coldTolerance = clampQ(qMul(arch.coldTolerance, mulFromVariation(triSym(rng), arch.coldVar)), q(0.01), q(0.98));
+    // positive resilience bias → lower fatigue rate (better endurance), so bias is negated
+    const fatigueRate = clampQ(qMul(arch.fatigueRate, mulFromVariation(biasedTriSym(rng, -res), arch.fatigueVar)), q(0.4), q(2.5));
+    const recoveryRate = clampQ(qMul(arch.recoveryRate, mulFromVariation(biasedTriSym(rng, res), arch.recoveryVar)), q(0.4), q(2.5));
+    return {
+        morphology: {
+            stature_m,
+            mass_kg,
+            actuatorMass_kg,
+            actuatorScale,
+            structureScale,
+            reachScale: reachMult,
+        },
+        performance: {
+            peakForce_N,
+            peakPower_W,
+            continuousPower_W,
+            reserveEnergy_J,
+            conversionEfficiency,
+        },
+        control: {
+            controlQuality,
+            reactionTime_s,
+            stability,
+            fineControl,
+        },
+        resilience: {
+            surfaceIntegrity,
+            bulkIntegrity,
+            structureIntegrity,
+            distressTolerance,
+            shockTolerance,
+            concussionTolerance,
+            heatTolerance,
+            coldTolerance,
+            fatigueRate,
+            recoveryRate,
+        },
+        perception: {
+            visionRange_m: arch.visionRange_m,
+            visionArcDeg: arch.visionArcDeg,
+            halfArcCosQ: halfArcCosQ(arch.visionArcDeg),
+            hearingRange_m: arch.hearingRange_m,
+            decisionLatency_s: arch.decisionLatency_s,
+            attentionDepth: arch.attentionDepth,
+            threatHorizon_m: arch.threatHorizon_m,
+        },
+        // Phase 33: pass through species-typical cognition (no per-individual variance)
+        ...(arch.cognition ? { cognition: arch.cognition } : {}),
+    };
+}

package/dist/src/index.d.ts

@@ -0,0 +1,42 @@
+export * from "./units.js";
+export * from "./types.js";
+export * from "./archetypes.js";
+export * from "./generate.js";
+export * from "./equipment.js";
+export * from "./sim/vec3.js";
+export * from "./sim/condition.js";
+export * from "./sim/injury.js";
+export * from "./sim/entity.js";
+export * from "./sim/commands.js";
+export * from "./sim/kernel.js";
+export * from "./sim/body.js";
+export * from "./sim/world.js";
+export * from "./model3d.js";
+export * from "./replay.js";
+export * from "./bridge/index.js";
+export * from "./channels.js";
+export * from "./traits.js";
+export * from "./derive.js";
+export * from "./sim/intent.js";
+export * from "./sim/action.js";
+export * from "./sim/combat.js";
+export * from "./quest.js";
+export * from "./quest-generators.js";
+export * from "./relationships.js";
+export * from "./relationships-effects.js";
+export * from "./inventory.js";
+export * from "./item-durability.js";
+export * from "./settlement.js";
+export * from "./settlement-services.js";
+export * from "./chronicle.js";
+export * from "./story-arcs.js";
+export * from "./narrative-render.js";
+export * from "./world-generation.js";
+export * from "./sim/trace.js";
+export * from "./rng.js";
+export * from "./dist.js";
+export * from "./lod.js";
+export * from "./sim/impairment.js";
+export * from "./sim/indexing.js";
+export * from "./sim/tuning.js";
+export * from "./sim/testing.js";

package/dist/src/index.js

@@ -0,0 +1,54 @@
+// ── Tier 1 — Stable host API ─────────────────────────────────────────────────
+// These exports form the public integration surface.  Breaking changes require
+// a major semver bump (x.0.0) and a migration guide in CHANGELOG.md.
+// Safe to import directly in host applications and typed as stable in STABLE_API.md.
+export * from "./units.js"; // q(), SCALE, qMul, mulDiv — fixed-point arithmetic
+export * from "./types.js"; // IndividualAttributes, core scalar types
+export * from "./archetypes.js"; // Archetype, BodyPlan, built-in species presets
+export * from "./generate.js"; // generateIndividual()
+export * from "./equipment.js"; // WEAPONS database, EquipmentCatalogue
+export * from "./sim/vec3.js"; // Vec3, lerpVec3, addVec3 — 3-D vector helpers
+export * from "./sim/condition.js"; // ConditionSnapshot, condition constants
+export * from "./sim/injury.js"; // InjuryRegion, BodyRegion, injury constants
+export * from "./sim/entity.js"; // Entity (stable fields: id, pos, mass_kg, attributes…)
+export * from "./sim/commands.js"; // CommandMap, EntityCommand, action verbs
+export * from "./sim/kernel.js"; // stepWorld(), applyImpactToInjury(), applyExplosion()
+export * from "./sim/body.js"; // BodyPlan, BodySegment, humanoid / quadruped plans
+export * from "./sim/world.js"; // WorldState, KernelContext, createWorld()
+export * from "./model3d.js"; // extractRigSnapshots(), deriveAnimationHints(), RigSnapshot, AnimationHints, GrapplePoseConstraint
+export * from "./replay.js"; // ReplayRecorder, replayTo(), serializeReplay(), deserializeReplay()
+export * from "./bridge/index.js"; // BridgeEngine, InterpolatedState, BridgeConfig — 3D renderer bridge
+// ── Tier 2 — Advanced / experimental API ─────────────────────────────────────
+// Tested and usable subsystems under active development.  May change between
+// minor versions (0.x.0); CHANGELOG.md will document any breaking change.
+// Reference STABLE_API.md §Tier 2 for the full export list per module.
+export * from "./channels.js"; // damage channel constants (BLUNT, SLASH, …)
+export * from "./traits.js"; // trait descriptors
+export * from "./derive.js"; // derived attribute helpers
+export * from "./sim/intent.js"; // IntentMap, buildIntent()
+export * from "./sim/action.js"; // ActionResult, resolveAction()
+export * from "./sim/combat.js"; // resolveHit(), resolveParry(), applyCombat()
+export * from "./quest.js"; // Quest, QuestObjective, questStep()
+export * from "./quest-generators.js"; // generateQuest(), generateQuestChain()
+export * from "./relationships.js"; // RelationshipMap, updateRelationship()
+export * from "./relationships-effects.js"; // applyRelationshipEffect()
+export * from "./inventory.js"; // Inventory, equipItem(), addItemToInventory()
+export * from "./item-durability.js"; // durability helpers, resolveRepair()
+export * from "./settlement.js"; // Settlement, stepSettlement()
+export * from "./settlement-services.js"; // service resolution helpers
+export * from "./chronicle.js"; // ChronicleEntry, addChronicleEntry()
+export * from "./story-arcs.js"; // StoryArc, detectArcs()
+export * from "./narrative-render.js"; // renderEntry(), renderChronicle(), generateNarrative()
+export * from "./world-generation.js"; // WorldTemplate, generateWorld()
+export * from "./sim/trace.js"; // SimTrace, traceStep() — debugging / profiling
+// ── Tier 3 — Internal / kernel API ───────────────────────────────────────────
+// Exported for power users and diagnostic tooling.  Not stability-guaranteed;
+// may change at any time without a changelog entry.  Prefer Tier 1/2 surfaces
+// in production host code.  See STABLE_API.md §Tier 3 for rationale.
+export * from "./rng.js"; // makeRng(), eventSeed() — RNG internals
+export * from "./dist.js"; // distribution primitives
+export * from "./lod.js"; // level-of-detail helpers
+export * from "./sim/impairment.js"; // low-level impairment accumulators
+export * from "./sim/indexing.js"; // SpatialIndex internals
+export * from "./sim/tuning.js"; // kernel tuning constants (may be adjusted)
+export * from "./sim/testing.js"; // mkHumanoidEntity() and other test helpers

package/dist/src/inheritance.d.ts

@@ -0,0 +1,69 @@
+import type { Q } from "./units.js";
+import type { Entity } from "./sim/entity.js";
+import type { CampaignState } from "./campaign.js";
+import type { RelationshipGraph } from "./relationships.js";
+export interface InheritanceSpec {
+    deceasedId: number;
+    heirId: number;
+    /**
+     * Fraction of relationship trust / affinity that passes to the heir.
+     * q(1.0) = full copy; q(0.50) = half strength; q(0) = no inheritance.
+     * Default: q(0.50).
+     */
+    relationshipTransferRate_Q?: Q;
+}
+export interface InheritanceReport {
+    /** Number of loadout items moved from deceased to heir. */
+    itemsTransferred: number;
+    /** Number of new relationship entries created for the heir. */
+    relationshipsTransferred: number;
+    /** Inventory items (itemId → count) transferred from deceased to heir. */
+    inventoryTransferred: Map<string, number>;
+}
+/**
+ * Move all loadout items from deceased to heir.
+ * Heir's existing items are preserved (deceased's items are appended).
+ * Deceased's loadout is cleared.
+ *
+ * @returns Number of items transferred.
+ */
+export declare function transferEquipment(deceased: Entity, heir: Entity): number;
+/**
+ * Partially copy the deceased's relationships to the heir.
+ *
+ * For each relationship R(deceased, X):
+ *   heir's trust_Q    = R.trust_Q    × transferRate_Q
+ *   heir's affinity_Q = |R.affinity_Q| × transferRate_Q  (sign preserved)
+ *
+ * Existing heir–X relationships are not overwritten.
+ * The deceased's relationships are left in the graph unmodified.
+ *
+ * @returns Number of new heir relationships created.
+ */
+export declare function transferRelationships(graph: RelationshipGraph, deceasedId: number, heirId: number, transferRate_Q: Q): number;
+/**
+ * Transfer all campaign inventory items from deceased to heir.
+ * Stacks merge: heir's existing counts are summed with deceased's amounts.
+ * The deceased's campaign inventory entry is deleted after transfer.
+ *
+ * @returns Map of transferred items (itemId → count transferred).
+ */
+export declare function transferInventory(campaign: CampaignState, deceasedId: number, heirId: number): Map<string, number>;
+/**
+ * Apply the full inheritance process when a character dies and an heir takes over.
+ *
+ * Steps performed:
+ *  1. Transfers loadout equipment from deceased to heir entity.
+ *  2. Transfers campaign inventory (deceased → heir, with stack merging).
+ *  3. Partially transfers relationships (if `graph` is provided).
+ *  4. Moves the deceased's campaign location to the heir.
+ *  5. Registers the heir in the campaign; removes the deceased.
+ *  6. Logs the event to `campaign.log`.
+ *
+ * Both deceased (via `campaign.entities`) and heir (provided directly) must be
+ * supplied.  The deceased entity is updated in-place before being removed so
+ * that equipment is properly cleared.
+ *
+ * @returns InheritanceReport with counts of transferred items and relationships.
+ */
+export declare function applyInheritance(campaign: CampaignState, graph: RelationshipGraph | undefined, spec: InheritanceSpec, heir: Entity): InheritanceReport;