@its-not-rocket-science/ananke 0.1.0

package/dist/src/relationships-effects.js

@@ -0,0 +1,219 @@
+// src/relationships-effects.ts — Phase 42: Relationship Effects Integration
+//
+// Integration of relationship graph with morale, teaching, and combat systems.
+import { q, SCALE } from "./units.js";
+import { getRelationship, recordRelationshipEvent, recordBetrayal, computeTeachingRelationshipMultiplier, } from "./relationships.js";
+/**
+ * Compute morale impacts for all observers of a combat event.
+ */
+export function computeCombatMoraleImpacts(graph, world, impact) {
+    const impacts = [];
+    // Get all potential observers (simplified: all entities in world)
+    // In practice, this would use spatial queries for entities within perception range
+    const observers = world.entities;
+    for (const observer of observers) {
+        if (observer.id === impact.attackerId || observer.id === impact.targetId)
+            continue;
+        // Check relationship with victim
+        const rVictim = getRelationship(graph, observer.id, impact.targetId);
+        if (rVictim && rVictim.affinity_Q > q(0.3)) {
+            // Friend was hit
+            const severity = impact.energy_J > 500 ? "friend_killed" : "friend_injured";
+            impacts.push({
+                observerId: observer.id,
+                targetId: impact.targetId,
+                event: severity,
+                delta_Q: Math.round(-rVictim.affinity_Q * (severity === "friend_killed" ? 0.5 : 0.2)),
+            });
+        }
+        // Check relationship with attacker
+        const rAttacker = getRelationship(graph, observer.id, impact.attackerId);
+        if (rAttacker && rAttacker.affinity_Q < -q(0.3)) {
+            // Enemy succeeded in hitting someone
+            impacts.push({
+                observerId: observer.id,
+                targetId: impact.attackerId,
+                event: "enemy_defeated",
+                delta_Q: Math.round(rAttacker.affinity_Q * 0.1), // Negative = bad for morale
+            });
+        }
+    }
+    return impacts;
+}
+/**
+ * Compute morale impact from betrayal detection.
+ */
+export function computeBetrayalMoraleImpacts(graph, world, attackerId, victimId, tick) {
+    const impacts = [];
+    // Record betrayal in relationship graph
+    const betrayalResult = recordBetrayal(graph, attackerId, victimId, tick);
+    if (!betrayalResult.isBetrayal)
+        return impacts;
+    // Find all witnesses who care about the victim
+    const witnesses = world.entities.filter((e) => e.id !== attackerId && e.id !== victimId);
+    for (const witness of witnesses) {
+        const r = getRelationship(graph, witness.id, victimId);
+        if (r && r.affinity_Q > q(0.2)) {
+            impacts.push({
+                observerId: witness.id,
+                targetId: victimId,
+                event: "betrayal",
+                delta_Q: betrayalResult.witnessMoralePenalty_Q,
+            });
+        }
+    }
+    return impacts;
+}
+// ── Teaching Integration ──────────────────────────────────────────────────────
+/**
+ * Compute total teaching effectiveness multiplier.
+ * Combines base skill with relationship factors.
+ */
+export function computeTeachingEffectiveness(graph, teacherId, learnerId, baseEffectiveness) {
+    const relationshipMul = computeTeachingRelationshipMultiplier(graph, teacherId, learnerId);
+    return baseEffectiveness * relationshipMul;
+}
+/**
+ * Compute combat decision factors based on relationship.
+ */
+export function getCombatDecisionFactors(graph, entityId, targetId) {
+    const r = getRelationship(graph, entityId, targetId);
+    if (!r) {
+        return {
+            willProtect: false,
+            willAvoidHarm: false,
+            aggressionModifier: 0,
+            coordinationBonus: 0,
+        };
+    }
+    const affinityNorm = r.affinity_Q / SCALE.Q; // -1 to 1
+    const trustNorm = r.trust_Q / SCALE.Q; // 0 to 1
+    return {
+        willProtect: r.affinity_Q > q(0.5) && r.trust_Q > q(0.3),
+        willAvoidHarm: r.affinity_Q > q(0.2),
+        aggressionModifier: -affinityNorm * 0.5, // Negative affinity = more aggressive
+        coordinationBonus: r.bond === "mentor" || r.bond === "student"
+            ? 0.2
+            : trustNorm * 0.1,
+    };
+}
+/**
+ * Determine if entity should switch targets to protect an ally.
+ */
+export function shouldProtectAlly(graph, protectorId, allyId, threatId) {
+    const rAlly = getRelationship(graph, protectorId, allyId);
+    const rThreat = getRelationship(graph, protectorId, threatId);
+    if (!rAlly)
+        return false;
+    // Will protect if ally is friend and threat is not a closer friend
+    const allyValue = rAlly.affinity_Q + rAlly.trust_Q;
+    const threatValue = rThreat
+        ? rThreat.affinity_Q + rThreat.trust_Q
+        : -SCALE.Q; // Unknown = neutral/negative
+    return allyValue > q(0.5) && allyValue > threatValue;
+}
+/**
+ * Compute what dialogue options are available.
+ */
+export function getDialogueAvailability(graph, speakerId, listenerId) {
+    const r = getRelationship(graph, speakerId, listenerId);
+    if (!r) {
+        return {
+            canAskFavors: false,
+            canNegotiate: true,
+            canIntimidate: false,
+            persuasionBonus: 0,
+        };
+    }
+    const affinityNorm = r.affinity_Q / SCALE.Q;
+    const trustNorm = r.trust_Q / SCALE.Q;
+    return {
+        canAskFavors: r.affinity_Q > q(0.4) && r.trust_Q > q(0.3),
+        canNegotiate: r.affinity_Q > -q(0.3), // Can negotiate unless enemies
+        canIntimidate: r.trust_Q < q(0.3) || r.affinity_Q < -q(0.2),
+        persuasionBonus: affinityNorm * 0.2 + trustNorm * 0.1,
+    };
+}
+// ── Event Recording ───────────────────────────────────────────────────────────
+/**
+ * Record events from combat resolution.
+ */
+export function recordCombatOutcome(graph, impact, outcome, tick) {
+    if (outcome === "hit") {
+        // If significant damage, record as negative event for relationship
+        if (impact.energy_J > 100) {
+            recordRelationshipEvent(graph, impact.attackerId, impact.targetId, {
+                tick,
+                type: "insult", // Attacking is insulting
+                magnitude_Q: Math.min(q(0.1), Math.round(impact.energy_J / 1000)),
+                description: `Attacked in combat (${outcome})`,
+            });
+        }
+    }
+}
+/**
+ * Record cooperation between entities.
+ */
+export function recordCooperation(graph, entityA, entityB, success, tick) {
+    recordRelationshipEvent(graph, entityA, entityB, {
+        tick,
+        type: "fought_alongside",
+        magnitude_Q: success ? q(0.15) : q(0.05),
+        description: success ? "Successful cooperation" : "Attempted cooperation",
+    });
+}
+/**
+ * Record that one entity saved another.
+ */
+export function recordRescue(graph, rescuerId, rescuedId, tick) {
+    recordRelationshipEvent(graph, rescuerId, rescuedId, {
+        tick,
+        type: "saved",
+        magnitude_Q: q(0.4),
+        description: "Saved from danger",
+    });
+}
+// ── Group Formation ────────────────────────────────────────────────────────────
+/** Find entities that form a cohesive group based on relationships. */
+export function findCohesiveGroup(graph, seedEntityId, minAffinity_Q = q(0.2)) {
+    const group = new Set([seedEntityId]);
+    const toCheck = [seedEntityId];
+    while (toCheck.length > 0) {
+        const current = toCheck.pop();
+        const relationships = Array.from(graph.relationships.values()).filter((r) => (r.entityA === current || r.entityB === current) && r.affinity_Q >= minAffinity_Q);
+        for (const r of relationships) {
+            const other = r.entityA === current ? r.entityB : r.entityA;
+            if (!group.has(other)) {
+                group.add(other);
+                toCheck.push(other);
+            }
+        }
+    }
+    return Array.from(group);
+}
+/**
+ * Check if a group of entities can work together effectively.
+ */
+export function computeGroupCohesion(graph, groupIds) {
+    if (groupIds.length < 2)
+        return { cohesion_Q: q(0.5), trust_Q: q(0.5) };
+    let totalAffinity = 0;
+    let totalTrust = 0;
+    let pairCount = 0;
+    for (let i = 0; i < groupIds.length; i++) {
+        for (let j = i + 1; j < groupIds.length; j++) {
+            const rel = getRelationship(graph, groupIds[i], groupIds[j]);
+            if (rel) {
+                totalAffinity += rel.affinity_Q;
+                totalTrust += rel.trust_Q;
+                pairCount++;
+            }
+        }
+    }
+    if (pairCount === 0)
+        return { cohesion_Q: q(0.5), trust_Q: q(0.5) };
+    return {
+        cohesion_Q: Math.round(totalAffinity / pairCount),
+        trust_Q: Math.round(totalTrust / pairCount),
+    };
+}

package/dist/src/relationships.d.ts

@@ -0,0 +1,104 @@
+import type { Q } from "./units.js";
+/** Types of events that can affect relationships. */
+export type RelationshipEventType = "met" | "fought_alongside" | "betrayed" | "saved" | "deceived" | "gift_given" | "insult" | "bonded" | "separated";
+/** A single event in the relationship history. */
+export interface RelationshipEvent {
+    tick: number;
+    type: RelationshipEventType;
+    magnitude_Q: Q;
+    description?: string;
+}
+/** The nature of the social bond between two entities. */
+export type SocialBond = "none" | "acquaintance" | "friend" | "close_friend" | "rival" | "enemy" | "mentor" | "student" | "family" | "romantic_partner";
+/** Relationship between two entities. */
+export interface Relationship {
+    entityA: number;
+    entityB: number;
+    /** Affinity: -1.0 (hatred) to +1.0 (love) */
+    affinity_Q: Q;
+    /** Trust: 0.0 (none) to 1.0 (absolute) */
+    trust_Q: Q;
+    /** Current social bond classification */
+    bond: SocialBond;
+    /** Chronicle of interactions */
+    history: RelationshipEvent[];
+    /** Tick when relationship was established */
+    establishedAtTick: number;
+    /** Last interaction tick */
+    lastInteractionTick: number;
+}
+/** Global relationship graph storage. */
+export interface RelationshipGraph {
+    relationships: Map<string, Relationship>;
+    /** Entity-specific indices for quick lookup */
+    entityIndex: Map<number, Set<string>>;
+}
+/** Create a new empty relationship graph. */
+export declare function createRelationshipGraph(): RelationshipGraph;
+/**
+ * Get relationship between two entities.
+ * Returns undefined if no relationship exists.
+ */
+export declare function getRelationship(graph: RelationshipGraph, entityA: number, entityB: number): Relationship | undefined;
+/**
+ * Check if two entities have an existing relationship.
+ */
+export declare function hasRelationship(graph: RelationshipGraph, entityA: number, entityB: number): boolean;
+/**
+ * Get all relationships for an entity.
+ */
+export declare function getEntityRelationshipsList(graph: RelationshipGraph, entityId: number): Relationship[];
+/**
+ * Get all entities related to a given entity.
+ */
+export declare function getRelatedEntities(graph: RelationshipGraph, entityId: number): number[];
+/**
+ * Establish a new relationship between two entities.
+ */
+export declare function establishRelationship(graph: RelationshipGraph, entityA: number, entityB: number, tick: number, initialAffinity_Q?: Q, initialTrust_Q?: Q): Relationship;
+/**
+ * Record a relationship event and update affinity/trust.
+ */
+export declare function recordRelationshipEvent(graph: RelationshipGraph, entityA: number, entityB: number, event: Omit<RelationshipEvent, "tick"> & {
+    tick: number;
+}): Relationship | undefined;
+/**
+ * Classify the social bond based on affinity, trust, and history.
+ */
+export declare function classifyBond(affinity_Q: Q, trust_Q: Q, history: RelationshipEvent[]): SocialBond;
+/**
+ * Apply time-based decay to relationships.
+ * Call periodically (e.g., daily or weekly in simulation time).
+ */
+export declare function decayRelationships(graph: RelationshipGraph, currentTick: number, decayRatePerTick?: number): void;
+/** Check if entity A would consider entity B a friend. */
+export declare function isFriend(graph: RelationshipGraph, entityA: number, entityB: number): boolean;
+/** Check if entity A would consider entity B an enemy. */
+export declare function isEnemy(graph: RelationshipGraph, entityA: number, entityB: number): boolean;
+/** Check if entity A trusts entity B enough for combat cooperation. */
+export declare function hasCombatTrust(graph: RelationshipGraph, entityA: number, entityB: number): boolean;
+/** Get the effective relationship modifier for morale effects. */
+export declare function getMoraleModifier(graph: RelationshipGraph, observer: number, target: number): Q;
+/** Result of betrayal check. */
+export interface BetrayalResult {
+    isBetrayal: boolean;
+    severity_Q: Q;
+    /** Morale penalty for witnesses who care about the victim */
+    witnessMoralePenalty_Q: Q;
+}
+/**
+ * Check if harming someone constitutes betrayal.
+ */
+export declare function checkBetrayal(graph: RelationshipGraph, attackerId: number, victimId: number): BetrayalResult;
+/**
+ * Record a betrayal event and update relationships.
+ */
+export declare function recordBetrayal(graph: RelationshipGraph, attackerId: number, victimId: number, tick: number): BetrayalResult;
+/**
+ * Compute teaching effectiveness multiplier based on relationship.
+ */
+export declare function computeTeachingRelationshipMultiplier(graph: RelationshipGraph, teacherId: number, learnerId: number): number;
+/** Serialize relationship graph to JSON-friendly format. */
+export declare function serializeRelationshipGraph(graph: RelationshipGraph): unknown;
+/** Deserialize relationship graph. */
+export declare function deserializeRelationshipGraph(data: unknown): RelationshipGraph;

package/dist/src/relationships.js

@@ -0,0 +1,347 @@
+// src/relationships.ts — Phase 42: Personal Relationship Graph
+//
+// Individual-to-individual relationships — the social fabric that makes RPGs feel alive.
+// Affects morale, teaching effectiveness, betrayal probability, and dialogue options.
+import { SCALE, q, clampQ } from "./units.js";
+/** Key for storing relationships (ordered pair). */
+function relationshipKey(entityA, entityB) {
+    // Always store with smaller ID first for consistency
+    return entityA < entityB ? `${entityA}:${entityB}` : `${entityB}:${entityA}`;
+}
+/** Create a new empty relationship graph. */
+export function createRelationshipGraph() {
+    return {
+        relationships: new Map(),
+        entityIndex: new Map(),
+    };
+}
+/** Get or create entity index entry. */
+function getEntityRelationships(graph, entityId) {
+    let set = graph.entityIndex.get(entityId);
+    if (!set) {
+        set = new Set();
+        graph.entityIndex.set(entityId, set);
+    }
+    return set;
+}
+/**
+ * Get relationship between two entities.
+ * Returns undefined if no relationship exists.
+ */
+export function getRelationship(graph, entityA, entityB) {
+    if (entityA === entityB)
+        return undefined;
+    const key = relationshipKey(entityA, entityB);
+    return graph.relationships.get(key);
+}
+/**
+ * Check if two entities have an existing relationship.
+ */
+export function hasRelationship(graph, entityA, entityB) {
+    return getRelationship(graph, entityA, entityB) !== undefined;
+}
+/**
+ * Get all relationships for an entity.
+ */
+export function getEntityRelationshipsList(graph, entityId) {
+    const keys = graph.entityIndex.get(entityId);
+    if (!keys)
+        return [];
+    return Array.from(keys)
+        .map((key) => graph.relationships.get(key))
+        .filter((r) => r !== undefined);
+}
+/**
+ * Get all entities related to a given entity.
+ */
+export function getRelatedEntities(graph, entityId) {
+    const relationships = getEntityRelationshipsList(graph, entityId);
+    return relationships.map((r) => (r.entityA === entityId ? r.entityB : r.entityA));
+}
+// ── Relationship Creation & Modification ──────────────────────────────────────
+/**
+ * Establish a new relationship between two entities.
+ */
+export function establishRelationship(graph, entityA, entityB, tick, initialAffinity_Q = q(0), initialTrust_Q = q(0.1)) {
+    if (entityA === entityB) {
+        throw new Error("Cannot establish relationship with self");
+    }
+    const key = relationshipKey(entityA, entityB);
+    // Check if relationship already exists
+    const existing = graph.relationships.get(key);
+    if (existing)
+        return existing;
+    const affinity_Q = clampQ(initialAffinity_Q, -SCALE.Q, SCALE.Q);
+    const trust_Q = clampQ(initialTrust_Q, q(0), SCALE.Q);
+    const relationship = {
+        entityA,
+        entityB,
+        affinity_Q,
+        trust_Q,
+        bond: classifyBond(affinity_Q, trust_Q, []),
+        history: [],
+        establishedAtTick: tick,
+        lastInteractionTick: tick,
+    };
+    graph.relationships.set(key, relationship);
+    getEntityRelationships(graph, entityA).add(key);
+    getEntityRelationships(graph, entityB).add(key);
+    return relationship;
+}
+/**
+ * Record a relationship event and update affinity/trust.
+ */
+export function recordRelationshipEvent(graph, entityA, entityB, event) {
+    if (entityA === entityB)
+        return undefined;
+    const key = relationshipKey(entityA, entityB);
+    let relationship = graph.relationships.get(key);
+    // Auto-establish relationship if it doesn't exist
+    if (!relationship) {
+        relationship = establishRelationship(graph, entityA, entityB, event.tick);
+    }
+    // Add event to history
+    const evt = {
+        tick: event.tick,
+        type: event.type,
+        magnitude_Q: event.magnitude_Q,
+    };
+    if (event.description !== undefined)
+        evt.description = event.description;
+    relationship.history.push(evt);
+    // Update affinity and trust based on event type
+    const { affinityDelta, trustDelta } = computeDeltasFromEvent(event.type, event.magnitude_Q);
+    relationship.affinity_Q = clampQ((relationship.affinity_Q + affinityDelta), -SCALE.Q, SCALE.Q);
+    relationship.trust_Q = clampQ((relationship.trust_Q + trustDelta), q(0), SCALE.Q);
+    relationship.lastInteractionTick = event.tick;
+    // Reclassify bond
+    relationship.bond = classifyBond(relationship.affinity_Q, relationship.trust_Q, relationship.history);
+    return relationship;
+}
+/**
+ * Compute affinity and trust deltas from event type.
+ */
+function computeDeltasFromEvent(type, magnitude_Q) {
+    // Scale: magnitude_Q (0-10000) * factor -> delta_Q
+    // Multipliers are scaled to produce meaningful changes (0.5-1.0 range possible)
+    const mul = (n) => Math.round(magnitude_Q * n);
+    switch (type) {
+        case "met":
+            return { affinityDelta: mul(0.1), trustDelta: mul(0.05) };
+        case "fought_alongside":
+            return { affinityDelta: mul(0.3), trustDelta: mul(0.6) };
+        case "saved":
+            return { affinityDelta: mul(0.8), trustDelta: mul(0.7) };
+        case "betrayed":
+            // Severe penalty - can swing positive to negative
+            return { affinityDelta: mul(-1.8), trustDelta: mul(-2.0) };
+        case "deceived":
+            return { affinityDelta: mul(-0.6), trustDelta: mul(-1.0) };
+        case "gift_given":
+            return { affinityDelta: mul(0.2), trustDelta: mul(0.1) };
+        case "insult":
+            return { affinityDelta: mul(-0.3), trustDelta: mul(-0.1) };
+        case "bonded":
+            return { affinityDelta: mul(0.6), trustDelta: mul(0.5) };
+        case "separated":
+            // Gradual decay - handled by decay function instead
+            return { affinityDelta: q(0), trustDelta: q(0) };
+        default:
+            return { affinityDelta: q(0), trustDelta: q(0) };
+    }
+}
+/**
+ * Classify the social bond based on affinity, trust, and history.
+ */
+export function classifyBond(affinity_Q, trust_Q, history) {
+    // Check for negative bonds first
+    if (affinity_Q < -q(0.6) && trust_Q < q(0.3))
+        return "enemy";
+    if (affinity_Q < -q(0.3) && affinity_Q >= -q(0.6))
+        return "rival";
+    // Check for special bonds in history
+    const hasMentorEvent = history.some((e) => e.type === "bonded" && e.magnitude_Q > q(0.7));
+    if (hasMentorEvent) {
+        return affinity_Q > q(0.5) ? "mentor" : "student";
+    }
+    // Check for romantic bond
+    const romanticEvent = history.some((e) => e.type === "bonded" && e.description?.includes("romantic"));
+    if (romanticEvent && affinity_Q > q(0.7) && trust_Q > q(0.6))
+        return "romantic_partner";
+    // Check for family
+    const familyEvent = history.some((e) => e.description?.includes("family"));
+    if (familyEvent)
+        return "family";
+    // Standard positive bonds
+    if (affinity_Q >= q(0.7) && trust_Q >= q(0.5))
+        return "close_friend";
+    if (affinity_Q >= q(0.3))
+        return "friend";
+    // Acquaintance covers neutral to slightly positive, and slightly negative
+    if (affinity_Q >= -q(0.3))
+        return "acquaintance";
+    return "none";
+}
+// ── Relationship Decay ────────────────────────────────────────────────────────
+/**
+ * Apply time-based decay to relationships.
+ * Call periodically (e.g., daily or weekly in simulation time).
+ */
+export function decayRelationships(graph, currentTick, decayRatePerTick = 0.0001) {
+    for (const relationship of graph.relationships.values()) {
+        const timeSinceInteraction = currentTick - relationship.lastInteractionTick;
+        if (timeSinceInteraction > 1000) {
+            // Start decay after 1000 ticks of no interaction
+            const decayAmount = Math.round(timeSinceInteraction * decayRatePerTick * SCALE.Q);
+            // Decay affinity toward neutral (0)
+            if (relationship.affinity_Q > 0) {
+                relationship.affinity_Q = Math.max(0, relationship.affinity_Q - decayAmount);
+            }
+            else if (relationship.affinity_Q < 0) {
+                relationship.affinity_Q = Math.min(0, relationship.affinity_Q + decayAmount);
+            }
+            // Decay trust slightly (people forget trust too)
+            relationship.trust_Q = Math.max(0, relationship.trust_Q - decayAmount / 2);
+            // Reclassify bond
+            relationship.bond = classifyBond(relationship.affinity_Q, relationship.trust_Q, relationship.history);
+        }
+    }
+}
+// ── Relationship Queries ──────────────────────────────────────────────────────
+/** Check if entity A would consider entity B a friend. */
+export function isFriend(graph, entityA, entityB) {
+    const r = getRelationship(graph, entityA, entityB);
+    if (!r)
+        return false;
+    return r.affinity_Q >= q(0.3) && ["acquaintance", "friend", "close_friend", "mentor", "student", "romantic_partner", "family"].includes(r.bond);
+}
+/** Check if entity A would consider entity B an enemy. */
+export function isEnemy(graph, entityA, entityB) {
+    const r = getRelationship(graph, entityA, entityB);
+    if (!r)
+        return false;
+    return r.affinity_Q < -q(0.3) || r.bond === "enemy" || r.bond === "rival";
+}
+/** Check if entity A trusts entity B enough for combat cooperation. */
+export function hasCombatTrust(graph, entityA, entityB) {
+    const r = getRelationship(graph, entityA, entityB);
+    if (!r)
+        return false;
+    return r.trust_Q >= q(0.4);
+}
+/** Get the effective relationship modifier for morale effects. */
+export function getMoraleModifier(graph, observer, target) {
+    const r = getRelationship(graph, observer, target);
+    if (!r)
+        return q(0);
+    // Positive affinity = morale boost when target succeeds
+    // Negative affinity = morale boost when target fails
+    return r.affinity_Q;
+}
+/**
+ * Check if harming someone constitutes betrayal.
+ */
+export function checkBetrayal(graph, attackerId, victimId) {
+    const r = getRelationship(graph, attackerId, victimId);
+    if (!r) {
+        return {
+            isBetrayal: false,
+            severity_Q: q(0),
+            witnessMoralePenalty_Q: q(0),
+        };
+    }
+    // Betrayal occurs when affinity is positive but attacker harms victim
+    const isBetrayal = r.affinity_Q > q(0.5);
+    if (!isBetrayal) {
+        return {
+            isBetrayal: false,
+            severity_Q: q(0),
+            witnessMoralePenalty_Q: q(0),
+        };
+    }
+    // Severity based on how positive the relationship was (0.6 to 1.0 range, as Q)
+    // Higher affinity = more severe betrayal = larger magnitude
+    const severity_Q = Math.round(SCALE.Q * 0.6 + r.affinity_Q * 0.4);
+    // Witnesses who cared about the victim take morale hit (0.3 to 0.7 range, as Q)
+    const witnessMoralePenalty_Q = Math.round(SCALE.Q * 0.3 + r.affinity_Q * 0.4);
+    return {
+        isBetrayal: true,
+        severity_Q,
+        witnessMoralePenalty_Q,
+    };
+}
+/**
+ * Record a betrayal event and update relationships.
+ */
+export function recordBetrayal(graph, attackerId, victimId, tick) {
+    const result = checkBetrayal(graph, attackerId, victimId);
+    if (result.isBetrayal) {
+        recordRelationshipEvent(graph, attackerId, victimId, {
+            tick,
+            type: "betrayed",
+            magnitude_Q: result.severity_Q,
+            description: "Betrayed during combat",
+        });
+        // Also damage attacker's reputation with victim's friends
+        const victimFriends = getEntityRelationshipsList(graph, victimId)
+            .filter((r) => r.affinity_Q > q(0.3) && r.entityA !== attackerId && r.entityB !== attackerId);
+        for (const friendRel of victimFriends) {
+            const friendId = friendRel.entityA === victimId ? friendRel.entityB : friendRel.entityA;
+            recordRelationshipEvent(graph, attackerId, friendId, {
+                tick,
+                type: "betrayed",
+                magnitude_Q: Math.round(result.severity_Q * 0.5),
+                description: `Betrayed ${victimId}`,
+            });
+        }
+    }
+    return result;
+}
+// ── Teaching Integration ──────────────────────────────────────────────────────
+/**
+ * Compute teaching effectiveness multiplier based on relationship.
+ */
+export function computeTeachingRelationshipMultiplier(graph, teacherId, learnerId) {
+    const r = getRelationship(graph, teacherId, learnerId);
+    if (!r)
+        return 1.0;
+    // Base multiplier from affinity
+    let multiplier = 1.0 + (r.affinity_Q / SCALE.Q) * 0.3;
+    // Bonus for mentor/student bond
+    if (r.bond === "mentor" || r.bond === "student") {
+        multiplier += 0.2;
+    }
+    // Trust affects how well learner accepts teaching
+    multiplier += (r.trust_Q / SCALE.Q) * 0.2;
+    return Math.max(0.5, Math.min(1.5, multiplier));
+}
+// ── Serialization ─────────────────────────────────────────────────────────────
+/** Serialize relationship graph to JSON-friendly format. */
+export function serializeRelationshipGraph(graph) {
+    return {
+        relationships: Array.from(graph.relationships.entries()),
+        entityIndex: Array.from(graph.entityIndex.entries()).map(([entityId, keys]) => [
+            entityId,
+            Array.from(keys),
+        ]),
+    };
+}
+/** Deserialize relationship graph. */
+export function deserializeRelationshipGraph(data) {
+    const graph = createRelationshipGraph();
+    if (typeof data !== "object" || data === null) {
+        return graph;
+    }
+    const d = data;
+    if (Array.isArray(d.relationships)) {
+        for (const [key, rel] of d.relationships) {
+            graph.relationships.set(key, rel);
+        }
+    }
+    if (Array.isArray(d.entityIndex)) {
+        for (const [entityId, keys] of d.entityIndex) {
+            graph.entityIndex.set(entityId, new Set(keys));
+        }
+    }
+    return graph;
+}