@its-not-rocket-science/ananke 0.1.17 → 0.1.23

package/dist/src/feudal.js

@@ -0,0 +1,161 @@
+// src/feudal.ts — Phase 79: Feudal Bonds & Vassal Tribute
+//
+// Tracks lord-vassal polity relationships including tribute, military levies,
+// bond strength, and revolt risk. Integrates with Phase 61 (Polity) for
+// treasury/military and Phase 75 (Renown) for oath-breaking infamy.
+//
+// Design:
+//   - Pure data layer — no Entity fields, no kernel changes.
+//   - `FeudalRegistry` is external to PolityRegistry; hosts maintain both.
+//   - Bond strength decays over time and recovers via positive events
+//     (kinship ties, shared victories, tribute payment).
+//   - `isRebellionRisk` provides a clear boolean hook for AI and event triggers.
+import { getRenownRecord } from "./renown.js";
+import { q, SCALE, clampQ, mulDiv } from "./units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Bond strength below this → `isRebellionRisk` returns true. */
+export const REBELLION_THRESHOLD = q(0.25);
+/** Daily strength decay for each loyalty type (per simulated day). */
+export const LOYALTY_DECAY_PER_DAY = {
+    kin_bound: q(0.001), // very slow — family ties are resilient
+    oath_sworn: q(0.002),
+    voluntary: q(0.003),
+    conquered: q(0.005), // fastest — resentment grows quickly
+};
+/** Base strength at bond creation per loyalty type. */
+export const LOYALTY_BASE_STRENGTH = {
+    kin_bound: q(0.90),
+    oath_sworn: q(0.70),
+    voluntary: q(0.65),
+    conquered: q(0.40),
+};
+/**
+ * Infamy added to the vassal's renown record when breaking an `oath_sworn` bond.
+ * `kin_bound` and `conquered` breaks carry no oath infamy.
+ */
+export const OATH_BREAK_INFAMY_Q = q(0.15);
+/** Tribute paid daily = `TRIBUTE_DAILY_FRAC` × annual rate × treasury_cu */
+export const TRIBUTE_DAYS_PER_YEAR = 365;
+// ── Factory ───────────────────────────────────────────────────────────────────
+export function createFeudalRegistry() {
+    return { bonds: new Map() };
+}
+// ── Bond key ──────────────────────────────────────────────────────────────────
+function bondKey(vassalId, liegeId) {
+    return `${vassalId}:${liegeId}`;
+}
+// ── Bond management ───────────────────────────────────────────────────────────
+/**
+ * Create a vassal bond and register it.
+ * If a bond between this pair already exists it is overwritten.
+ *
+ * @param tributeRate_Q  Annual tribute as fraction of vassal treasury (default q(0.10)).
+ * @param levyRate_Q     Fraction of military available as levy (default q(0.20)).
+ * @param tick           Current simulation tick.
+ */
+export function createVassalBond(registry, vassalPolityId, liegePolityId, loyaltyType, tributeRate_Q = q(0.10), levyRate_Q = q(0.20), tick = 0) {
+    const bond = {
+        vassalPolityId,
+        liegePolityId,
+        loyaltyType,
+        tributeRate_Q,
+        levyRate_Q,
+        strength_Q: LOYALTY_BASE_STRENGTH[loyaltyType],
+        establishedTick: tick,
+    };
+    registry.bonds.set(bondKey(vassalPolityId, liegePolityId), bond);
+    return bond;
+}
+/** Return the bond from `vassalId` to `liegeId`, or `undefined` if none. */
+export function getBond(registry, vassalId, liegeId) {
+    return registry.bonds.get(bondKey(vassalId, liegeId));
+}
+/** Return all active bonds where `liegeId` is the lord. */
+export function getVassals(registry, liegeId) {
+    return [...registry.bonds.values()].filter(b => b.liegePolityId === liegeId);
+}
+/** Return the bond where `vassalId` is the vassal, or `undefined`. */
+export function getLiege(registry, vassalId) {
+    return [...registry.bonds.values()].find(b => b.vassalPolityId === vassalId);
+}
+// ── Tribute computation ───────────────────────────────────────────────────────
+/**
+ * Compute the tribute owed for one simulated day.
+ * Scales linearly: `daily = floor(treasury_cu × tributeRate_Q / SCALE.Q / DAYS_PER_YEAR)`.
+ * Returns 0 if the vassal treasury is empty.
+ */
+export function computeDailyTribute(vassal, bond) {
+    if (vassal.treasury_cu <= 0)
+        return 0;
+    return Math.floor(vassal.treasury_cu * bond.tributeRate_Q / SCALE.Q / TRIBUTE_DAYS_PER_YEAR);
+}
+/**
+ * Apply one day of tribute: deduct from vassal treasury and add to liege treasury.
+ * Mutates both polity objects.
+ * No-op if computed tribute is 0.
+ */
+export function applyDailyTribute(vassal, liege, bond) {
+    const tribute = computeDailyTribute(vassal, bond);
+    if (tribute <= 0)
+        return 0;
+    vassal.treasury_cu = Math.max(0, vassal.treasury_cu - tribute);
+    liege.treasury_cu += tribute;
+    return tribute;
+}
+// ── Levy computation ──────────────────────────────────────────────────────────
+/**
+ * Compute the military strength available to the liege as a levy.
+ * = `vassal.militaryStrength_Q × levyRate_Q × bond.strength_Q`.
+ * A weakened bond reduces the effective levy.
+ */
+export function computeLevyStrength(vassal, bond) {
+    const raw = mulDiv(mulDiv(vassal.militaryStrength_Q, bond.levyRate_Q, SCALE.Q), bond.strength_Q, SCALE.Q);
+    return clampQ(raw, 0, SCALE.Q);
+}
+// ── Bond strength ─────────────────────────────────────────────────────────────
+/**
+ * Advance bond strength by one simulated day.
+ * Strength decays at `LOYALTY_DECAY_PER_DAY[loyaltyType]`.
+ * `boostDelta_Q` is an optional signed daily bonus (e.g., from kinship, shared victory,
+ * good governance). Positive = strengthen; negative = additional stress.
+ * Mutates `bond.strength_Q` directly.
+ */
+export function stepBondStrength(bond, boostDelta_Q = 0) {
+    const decay = LOYALTY_DECAY_PER_DAY[bond.loyaltyType];
+    bond.strength_Q = clampQ(bond.strength_Q - decay + boostDelta_Q, 0, SCALE.Q);
+}
+/**
+ * Strengthen a bond by a fixed delta (e.g., after a kinship event or tribute payment).
+ * Clamps to [0, SCALE.Q].
+ */
+export function reinforceBond(bond, deltaQ) {
+    bond.strength_Q = clampQ(bond.strength_Q + deltaQ, 0, SCALE.Q);
+}
+// ── Rebellion risk ────────────────────────────────────────────────────────────
+/** Return `true` if the bond is at rebellion risk (`strength_Q < REBELLION_THRESHOLD`). */
+export function isRebellionRisk(bond) {
+    return bond.strength_Q < REBELLION_THRESHOLD;
+}
+// ── Bond breaking ─────────────────────────────────────────────────────────────
+/**
+ * Break a vassal bond and remove it from the registry.
+ * For `oath_sworn` bonds, adds `OATH_BREAK_INFAMY_Q` to the vassal ruler's renown
+ * record if `vassalRulerId` and `renownRegistry` are provided.
+ *
+ * @returns `true` if a bond was found and removed; `false` otherwise.
+ */
+export function breakVassalBond(registry, vassalPolityId, liegePolityId, vassalRulerId, renownRegistry) {
+    const key = bondKey(vassalPolityId, liegePolityId);
+    const bond = registry.bonds.get(key);
+    if (!bond)
+        return false;
+    // Oath-breaking infamy
+    if (bond.loyaltyType === "oath_sworn" &&
+        vassalRulerId != null &&
+        renownRegistry != null) {
+        const record = getRenownRecord(renownRegistry, vassalRulerId);
+        record.infamy_Q = clampQ(record.infamy_Q + OATH_BREAK_INFAMY_Q, 0, SCALE.Q);
+    }
+    registry.bonds.delete(key);
+    return true;
+}

package/dist/src/kinship.d.ts

@@ -0,0 +1,92 @@
+import type { RenownRegistry } from "./renown.js";
+import type { Q } from "./units.js";
+/** A single entity's family links within the lineage graph. */
+export interface LineageNode {
+    entityId: number;
+    /** 0, 1, or 2 biological parent IDs. */
+    parentIds: number[];
+    /** All children recorded via `recordBirth`. */
+    childIds: number[];
+    /** All recorded partners (may grow over time). */
+    partnerIds: number[];
+}
+/** Registry of all lineage nodes, keyed by entityId. */
+export interface LineageRegistry {
+    nodes: Map<number, LineageNode>;
+}
+/** Human-readable kinship label derived from `computeKinshipDegree`. */
+export type KinshipLabel = "self" | "immediate" | "close" | "extended" | "distant" | "unrelated";
+/** Maximum BFS depth for kinship searches; beyond this entities are "unrelated". */
+export declare const MAX_KINSHIP_DEPTH = 4;
+/**
+ * Depth-decay factor for inherited renown.
+ * Each generation reduces the renown contribution by this fraction:
+ *   depth 1 (parent) → q(0.50) × parent renown
+ *   depth 2 (grandparent) → q(0.25) × grandparent renown
+ */
+export declare const RENOWN_DEPTH_DECAY_Q: Q;
+export declare function createLineageRegistry(): LineageRegistry;
+/**
+ * Return the `LineageNode` for `entityId`, creating a root node (no parents,
+ * no children, no partners) if one does not yet exist.
+ */
+export declare function getLineageNode(registry: LineageRegistry, entityId: number): LineageNode;
+/**
+ * Register a birth: create a node for `childId` and link it to up to two parents.
+ * Parent nodes are created if they do not already exist.
+ * No-op if `childId` already has a node (idempotent).
+ */
+export declare function recordBirth(registry: LineageRegistry, childId: number, parentAId: number, parentBId?: number): void;
+/**
+ * Record a partnership between two entities.
+ * Partners are considered degree-1 kin (immediate).
+ * Idempotent: duplicate calls are safe.
+ */
+export declare function recordPartnership(registry: LineageRegistry, entityAId: number, entityBId: number): void;
+/** Return the parent IDs of `entityId` (0–2 elements). */
+export declare function getParents(registry: LineageRegistry, entityId: number): number[];
+/** Return the child IDs of `entityId`. */
+export declare function getChildren(registry: LineageRegistry, entityId: number): number[];
+/**
+ * Return the sibling IDs of `entityId` — entities that share at least one parent,
+ * excluding `entityId` itself.
+ */
+export declare function getSiblings(registry: LineageRegistry, entityId: number): number[];
+/**
+ * Return all ancestors of `entityId` within `maxDepth` generations.
+ * Uses BFS upward through parent links only.
+ */
+export declare function findAncestors(registry: LineageRegistry, entityId: number, maxDepth?: number): Set<number>;
+/**
+ * Compute the degree of kinship between two entities via BFS on the undirected
+ * family graph (parents, children, and partners are all degree-1 neighbours).
+ *
+ * Returns:
+ *   - `0` if `entityA === entityB`
+ *   - `1`–`MAX_KINSHIP_DEPTH` for kin within range
+ *   - `null` if no path exists within `MAX_KINSHIP_DEPTH`
+ */
+export declare function computeKinshipDegree(registry: LineageRegistry, entityA: number, entityB: number): number | null;
+/** Whether two entities are kin within `maxDegree` (default `MAX_KINSHIP_DEPTH`). */
+export declare function isKin(registry: LineageRegistry, entityA: number, entityB: number, maxDegree?: number): boolean;
+/**
+ * Map a numeric kinship degree (or `null`) to a `KinshipLabel`.
+ *
+ * @param degree  Result of `computeKinshipDegree`; pass `null` for unrelated.
+ */
+export declare function getKinshipLabel(degree: number | null): KinshipLabel;
+/**
+ * Compute the renown bonus an entity inherits from their ancestors.
+ *
+ * For each ancestor at depth d, contribution = `ancestor.renown_Q × decay^d`
+ * where `decay = RENOWN_DEPTH_DECAY_Q / SCALE.Q` (default 0.5 per generation).
+ * The sum is clamped to `[0, SCALE.Q]`.
+ *
+ * Entities with no renown records or no ancestors return 0.
+ *
+ * @param registry       Lineage registry.
+ * @param entityId       Entity whose ancestors are being summed.
+ * @param renownRegistry Phase 75 renown registry.
+ * @param maxDepth       How many generations to look back (default 3).
+ */
+export declare function computeInheritedRenown(lineage: LineageRegistry, entityId: number, renownRegistry: RenownRegistry, maxDepth?: number): Q;

package/dist/src/kinship.js

@@ -0,0 +1,234 @@
+// src/kinship.ts — Phase 76: Kinship & Lineage
+//
+// Tracks parent-child-partner links for entities and provides ancestry queries,
+// degree-of-kinship computation, and inherited renown from the Phase 75 system.
+//
+// Design:
+//   - Separate from Entity — the lineage graph lives in a `LineageRegistry`,
+//     not in entity fields, so no kernel changes are required.
+//   - `computeKinshipDegree` uses BFS over the undirected family graph (parents,
+//     children, partners counted at degree 1).
+//   - `inheritedRenown` sums ancestor renown_Q with geometric depth-decay so that
+//     a mythic grandparent grants a modest but real reputation bonus.
+//   - Deterministic: no Math.random(); only pure data queries.
+import { q, SCALE, clampQ } from "./units.js";
+/** Maximum BFS depth for kinship searches; beyond this entities are "unrelated". */
+export const MAX_KINSHIP_DEPTH = 4;
+/**
+ * Depth-decay factor for inherited renown.
+ * Each generation reduces the renown contribution by this fraction:
+ *   depth 1 (parent) → q(0.50) × parent renown
+ *   depth 2 (grandparent) → q(0.25) × grandparent renown
+ */
+export const RENOWN_DEPTH_DECAY_Q = q(0.50);
+// ── Factory ───────────────────────────────────────────────────────────────────
+export function createLineageRegistry() {
+    return { nodes: new Map() };
+}
+// ── Node access ───────────────────────────────────────────────────────────────
+/**
+ * Return the `LineageNode` for `entityId`, creating a root node (no parents,
+ * no children, no partners) if one does not yet exist.
+ */
+export function getLineageNode(registry, entityId) {
+    let node = registry.nodes.get(entityId);
+    if (!node) {
+        node = { entityId, parentIds: [], childIds: [], partnerIds: [] };
+        registry.nodes.set(entityId, node);
+    }
+    return node;
+}
+// ── Mutation helpers ──────────────────────────────────────────────────────────
+/**
+ * Register a birth: create a node for `childId` and link it to up to two parents.
+ * Parent nodes are created if they do not already exist.
+ * No-op if `childId` already has a node (idempotent).
+ */
+export function recordBirth(registry, childId, parentAId, parentBId) {
+    // Ensure child node exists with the given parents
+    const existing = registry.nodes.get(childId);
+    if (!existing) {
+        const parentIds = parentBId != null
+            ? [parentAId, parentBId]
+            : [parentAId];
+        registry.nodes.set(childId, { entityId: childId, parentIds, childIds: [], partnerIds: [] });
+    }
+    // Ensure parent nodes exist and include childId
+    const nodeA = getLineageNode(registry, parentAId);
+    if (!nodeA.childIds.includes(childId))
+        nodeA.childIds.push(childId);
+    if (parentBId != null) {
+        const nodeB = getLineageNode(registry, parentBId);
+        if (!nodeB.childIds.includes(childId))
+            nodeB.childIds.push(childId);
+    }
+}
+/**
+ * Record a partnership between two entities.
+ * Partners are considered degree-1 kin (immediate).
+ * Idempotent: duplicate calls are safe.
+ */
+export function recordPartnership(registry, entityAId, entityBId) {
+    const nodeA = getLineageNode(registry, entityAId);
+    const nodeB = getLineageNode(registry, entityBId);
+    if (!nodeA.partnerIds.includes(entityBId))
+        nodeA.partnerIds.push(entityBId);
+    if (!nodeB.partnerIds.includes(entityAId))
+        nodeB.partnerIds.push(entityAId);
+}
+// ── Family queries ────────────────────────────────────────────────────────────
+/** Return the parent IDs of `entityId` (0–2 elements). */
+export function getParents(registry, entityId) {
+    return registry.nodes.get(entityId)?.parentIds ?? [];
+}
+/** Return the child IDs of `entityId`. */
+export function getChildren(registry, entityId) {
+    return registry.nodes.get(entityId)?.childIds ?? [];
+}
+/**
+ * Return the sibling IDs of `entityId` — entities that share at least one parent,
+ * excluding `entityId` itself.
+ */
+export function getSiblings(registry, entityId) {
+    const parents = getParents(registry, entityId);
+    const result = new Set();
+    for (const pid of parents) {
+        for (const sibId of getChildren(registry, pid)) {
+            if (sibId !== entityId)
+                result.add(sibId);
+        }
+    }
+    return [...result];
+}
+/**
+ * Return all ancestors of `entityId` within `maxDepth` generations.
+ * Uses BFS upward through parent links only.
+ */
+export function findAncestors(registry, entityId, maxDepth = MAX_KINSHIP_DEPTH) {
+    const ancestors = new Set();
+    const queue = [{ id: entityId, depth: 0 }];
+    while (queue.length > 0) {
+        const item = queue.shift();
+        if (item.depth >= maxDepth)
+            continue;
+        for (const pid of getParents(registry, item.id)) {
+            if (!ancestors.has(pid)) {
+                ancestors.add(pid);
+                queue.push({ id: pid, depth: item.depth + 1 });
+            }
+        }
+    }
+    return ancestors;
+}
+/**
+ * Compute the degree of kinship between two entities via BFS on the undirected
+ * family graph (parents, children, and partners are all degree-1 neighbours).
+ *
+ * Returns:
+ *   - `0` if `entityA === entityB`
+ *   - `1`–`MAX_KINSHIP_DEPTH` for kin within range
+ *   - `null` if no path exists within `MAX_KINSHIP_DEPTH`
+ */
+export function computeKinshipDegree(registry, entityA, entityB) {
+    if (entityA === entityB)
+        return 0;
+    const visited = new Set([entityA]);
+    const queue = [{ id: entityA, depth: 0 }];
+    while (queue.length > 0) {
+        const item = queue.shift();
+        if (item.depth >= MAX_KINSHIP_DEPTH)
+            continue;
+        const node = registry.nodes.get(item.id);
+        if (!node)
+            continue;
+        // BFS over parents + children + partners (undirected)
+        const neighbours = [
+            ...node.parentIds,
+            ...node.childIds,
+            ...node.partnerIds,
+        ];
+        for (const nbr of neighbours) {
+            if (nbr === entityB)
+                return item.depth + 1;
+            if (!visited.has(nbr)) {
+                visited.add(nbr);
+                queue.push({ id: nbr, depth: item.depth + 1 });
+            }
+        }
+    }
+    return null; // unrelated within MAX_KINSHIP_DEPTH
+}
+/** Whether two entities are kin within `maxDegree` (default `MAX_KINSHIP_DEPTH`). */
+export function isKin(registry, entityA, entityB, maxDegree = MAX_KINSHIP_DEPTH) {
+    const degree = computeKinshipDegree(registry, entityA, entityB);
+    return degree !== null && degree <= maxDegree;
+}
+// ── Label ─────────────────────────────────────────────────────────────────────
+/**
+ * Map a numeric kinship degree (or `null`) to a `KinshipLabel`.
+ *
+ * @param degree  Result of `computeKinshipDegree`; pass `null` for unrelated.
+ */
+export function getKinshipLabel(degree) {
+    if (degree === null)
+        return "unrelated";
+    if (degree === 0)
+        return "self";
+    if (degree === 1)
+        return "immediate";
+    if (degree === 2)
+        return "close";
+    if (degree === 3)
+        return "extended";
+    if (degree <= MAX_KINSHIP_DEPTH)
+        return "distant";
+    return "unrelated";
+}
+// ── Inherited renown ──────────────────────────────────────────────────────────
+/**
+ * Compute the renown bonus an entity inherits from their ancestors.
+ *
+ * For each ancestor at depth d, contribution = `ancestor.renown_Q × decay^d`
+ * where `decay = RENOWN_DEPTH_DECAY_Q / SCALE.Q` (default 0.5 per generation).
+ * The sum is clamped to `[0, SCALE.Q]`.
+ *
+ * Entities with no renown records or no ancestors return 0.
+ *
+ * @param registry       Lineage registry.
+ * @param entityId       Entity whose ancestors are being summed.
+ * @param renownRegistry Phase 75 renown registry.
+ * @param maxDepth       How many generations to look back (default 3).
+ */
+export function computeInheritedRenown(lineage, entityId, renownRegistry, maxDepth = 3) {
+    // BFS upward through parent links only (not children/partners)
+    let total = 0;
+    const visited = new Set([entityId]);
+    const queue = [];
+    for (const pid of getParents(lineage, entityId)) {
+        if (!visited.has(pid)) {
+            visited.add(pid);
+            queue.push({ id: pid, depth: 1 });
+        }
+    }
+    while (queue.length > 0) {
+        const item = queue.shift();
+        if (item.depth > maxDepth)
+            continue;
+        const record = renownRegistry.records.get(item.id);
+        if (record && record.renown_Q > 0) {
+            // decay^depth applied via repeated integer multiplication
+            let contribution = record.renown_Q;
+            for (let i = 0; i < item.depth; i++) {
+                contribution = Math.round(contribution * RENOWN_DEPTH_DECAY_Q / SCALE.Q);
+            }
+            total += contribution;
+        }
+        for (const pid of getParents(lineage, item.id)) {
+            if (!visited.has(pid)) {
+                visited.add(pid);
+                queue.push({ id: pid, depth: item.depth + 1 });
+            }
+        }
+    }
+    return clampQ(total, 0, SCALE.Q);
+}

package/dist/src/narrative-prose.d.ts

@@ -0,0 +1,58 @@
+import type { ChronicleEntry } from "./chronicle.js";
+import type { Chronicle } from "./chronicle.js";
+import type { CultureProfile } from "./culture.js";
+import type { MythArchetype, Myth } from "./mythology.js";
+/**
+ * Voice tone used when rendering chronicle entries.
+ * Derived from the dominant cultural values of the originating polity.
+ */
+export type ProseTone = "neutral" | "heroic" | "tragic" | "martial" | "spiritual" | "mercantile";
+/**
+ * Context bundle for a tone-aware rendering pass.
+ * Created by `createNarrativeContext` and passed to render functions.
+ */
+export interface NarrativeContext {
+    /** Map of entity id → display name. Missing ids fall back to "entity {id}". */
+    entityNames: Map<number, string>;
+    /** Prose tone for this rendering pass. */
+    tone: ProseTone;
+    /**
+     * Optional myth-archetype closing phrase appended to each rendered sentence.
+     * Produced by `mythArchetypeFrame(archetype)`.
+     */
+    mythFrame?: string;
+}
+/** Returns a closing phrase appropriate to the myth archetype. */
+export declare function mythArchetypeFrame(archetype: MythArchetype): string;
+/**
+ * Derive the best matching `ProseTone` from a `CultureProfile`.
+ *
+ * Uses the top-ranked cultural value; falls back to `"neutral"` for values
+ * without a direct tone mapping (hospitality, hierarchy, innovation, etc.).
+ */
+export declare function deriveNarrativeTone(culture: CultureProfile): ProseTone;
+/**
+ * Create a `NarrativeContext` for a rendering pass.
+ *
+ * @param entityNames  Map of entity id → display name (numeric ids are looked up here).
+ * @param culture      Optional culture profile — used to derive tone automatically.
+ * @param myth         Optional myth — used to append archetype-framing suffix.
+ */
+export declare function createNarrativeContext(entityNames: Map<number, string>, culture?: CultureProfile, myth?: Myth): NarrativeContext;
+/**
+ * Render a single `ChronicleEntry` with cultural-tone awareness.
+ *
+ * Selects the tone variant for `entry.eventType`; falls back to `"neutral"` if
+ * the requested tone has no specific variant.  Appends `ctx.mythFrame` if set.
+ *
+ * Does NOT mutate `entry.rendered` — call `entry.rendered = renderEntryWithTone(...)`
+ * manually if caching is desired.
+ */
+export declare function renderEntryWithTone(entry: ChronicleEntry, ctx: NarrativeContext): string;
+/**
+ * Render all entries in a `Chronicle` above `minSignificance` (default 50),
+ * returned in chronological order.
+ *
+ * Uses `renderEntryWithTone` for each entry.
+ */
+export declare function renderChronicleWithTone(chronicle: Chronicle, ctx: NarrativeContext, minSignificance?: number): string[];