@its-not-rocket-science/ananke 0.1.16 → 0.1.22

package/CHANGELOG.md

@@ -6,6 +6,151 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.22] — 2026-03-26
+
+### Added
+
+- **Phase 77 · Dynasty & Succession** (`src/succession.ts`)
+  - `SuccessionRuleType`: `"primogeniture" | "renown_based" | "election"`.
+  - `SuccessionCandidate { entityId, kinshipDegree, renown_Q, inheritedRenown_Q, claimStrength_Q }`.
+  - `SuccessionResult { heirId, candidates, rule, stabilityImpact_Q }` — signed Q stability delta.
+  - `findSuccessionCandidates(lineage, deceasedId, renownRegistry, maxDegree?)` — BFS over family graph (Phase 76), computes `renown_Q` and `inheritedRenown_Q` per candidate.
+  - `resolveSuccession(lineage, deceasedId, renownRegistry, rule, worldSeed, tick)` → `SuccessionResult`:
+    - **primogeniture**: first-born child (lowest entityId) gets SCALE.Q claim; others by distance.
+    - **renown_based**: claim = 70% own renown + 30% inherited renown.
+    - **election**: renown-weighted deterministic lottery via `eventSeed`.
+    - Stability: `+STABILITY_CLEAN_SUCCESSION_Q` for uncontested direct heir; `−STABILITY_DISTANT_HEIR_Q` per extra degree; `−STABILITY_CONTESTED_Q` when top-two gap < q(0.10); `−STABILITY_NO_HEIR_Q` if no candidates.
+  - `applySuccessionToPolity(polity, result)` — applies `stabilityImpact_Q` to `polity.stabilityQ` (clamped).
+  - Added `./succession` subpath export to `package.json`.
+  - 21 new tests; 4,142 total. Coverage maintained above all thresholds.
+
+---
+
+## [0.1.21] — 2026-03-26
+
+### Added
+
+- **Phase 76 · Kinship & Lineage** (`src/kinship.ts`)
+  - `LineageNode { entityId, parentIds, childIds, partnerIds }` — family links per entity.
+  - `LineageRegistry { nodes: Map<number, LineageNode> }` — flat registry, no Entity field changes.
+  - `createLineageRegistry()` / `getLineageNode(registry, entityId)` — factory and lazy-init accessor.
+  - `recordBirth(registry, childId, parentAId, parentBId?)` — links child to 1–2 parents; idempotent.
+  - `recordPartnership(registry, entityAId, entityBId)` — mutual partner link; idempotent.
+  - `getParents / getChildren / getSiblings` — direct family queries; siblings deduplicated.
+  - `findAncestors(registry, entityId, maxDepth?)` — BFS upward through parent links (default depth 4).
+  - `computeKinshipDegree(registry, entityA, entityB)` — BFS on undirected family graph (parents + children + partners); returns 0–4 or `null` beyond `MAX_KINSHIP_DEPTH = 4`.
+  - `isKin(registry, entityA, entityB, maxDegree?)` — convenience boolean.
+  - `getKinshipLabel(degree)` → `"self" | "immediate" | "close" | "extended" | "distant" | "unrelated"`.
+  - `computeInheritedRenown(lineage, entityId, renownRegistry, maxDepth?)` — sums ancestor `renown_Q` with geometric decay (`RENOWN_DEPTH_DECAY_Q = q(0.50)` per generation); clamped to SCALE.Q.
+  - Added `./kinship` subpath export to `package.json`.
+  - 42 new tests; 4,121 total. Coverage maintained above all thresholds.
+
+---
+
+## [0.1.20] — 2026-03-26
+
+### Added
+
+- **Phase 75 · Entity Renown & Legend Registry** (`src/renown.ts`)
+  - `RenownRecord { entityId, renown_Q, infamy_Q, entries: LegendEntry[] }` — per-entity reputation on two orthogonal axes.
+  - `LegendEntry { entryId, tick, eventType, significance }` — lightweight reference to a significant `ChronicleEntry`.
+  - `RenownRegistry { records: Map<number, RenownRecord> }` — flat registry, one record per entity.
+  - `createRenownRegistry()` / `getRenownRecord(registry, entityId)` — factory and lazy-init accessor.
+  - `updateRenownFromChronicle(registry, chronicle, entityId, minSignificance?)` — idempotent scan; renown events (legendary_deed, quest_completed, combat_victory, masterwork_crafted, rank_promotion, settlement_founded, first_contact) add to `renown_Q`; infamy events (relationship_betrayal, settlement_raided, settlement_destroyed, quest_failed) add to `infamy_Q`; both capped at SCALE.Q.
+  - `getRenownLabel(renown_Q)` → `"unknown" | "noted" | "known" | "renowned" | "legendary" | "mythic"` (6 tiers at q(0.10) boundaries).
+  - `getInfamyLabel(infamy_Q)` → `"innocent" | "suspect" | "notorious" | "infamous" | "reviled" | "condemned"`.
+  - `deriveFactionStandingAdjustment(renown_Q, infamy_Q, allianceBias)` — signed Q adjustment; heroic factions (bias=1.0) reward renown and punish infamy; criminal factions (bias=0.0) the reverse; clamped to [-SCALE.Q, SCALE.Q].
+  - `getTopLegendEntries(record, n)` — top N entries by significance (tick-descending tie-break).
+  - `renderLegendWithTone(record, entryMap, ctx, maxEntries?)` — renders top entries as prose via Phase 74's `renderEntryWithTone`.
+  - Added `./narrative-prose` and `./renown` subpath exports to `package.json`.
+  - 42 new tests; 4,079 total. Coverage maintained above all thresholds.
+
+---
+
+## [0.1.19] — 2026-03-26
+
+### Added
+
+- **Phase 74 · Simulation Trace → Narrative Prose** (`src/narrative-prose.ts`)
+  - 6 prose tones: `neutral | heroic | tragic | martial | spiritual | mercantile`
+  - Tone-varied templates for all 19 `ChronicleEventType` values.
+  - `deriveNarrativeTone(culture)` — maps dominant `CultureProfile` value → `ProseTone`
+    via `VALUE_TONE_MAP` (martial_virtue→martial, spiritual_devotion→spiritual,
+    commerce→mercantile, honour→heroic, fatalism→tragic; others fall back to neutral).
+  - `mythArchetypeFrame(archetype)` — returns a culturally-flavoured closing phrase for
+    each `MythArchetype` (hero, monster, trickster, great_plague, divine_wrath, golden_age).
+  - `createNarrativeContext(entityNames, culture?, myth?)` — bundles tone + name map + myth frame.
+  - `renderEntryWithTone(entry, ctx)` — picks the tone variant for each event, substitutes
+    `{name}`, `{target}`, computed helper strings (`{cause_str}`, `{location_str}`, etc.),
+    raw `entry.variables`, and appends the myth frame (replacing terminal period).
+  - `renderChronicleWithTone(chronicle, ctx, minSignificance?)` — filters by significance,
+    sorts chronologically, maps via `renderEntryWithTone`.
+  - **Success criterion met:** martial, spiritual, and mercantile tones produce clearly
+    distinguishable prose from the same chronicle events.
+  - 39 new tests; 4,037 total. Coverage: statements 96.81%, branches 86.87%, functions 94.80%.
+
+---
+
+## [0.1.18] — 2026-03-26
+
+### Added
+
+- **CE-18 · External Agent Interface** (`tools/agent-server.ts`)
+  - WebSocket server (default port 3001) implementing an agent observation/action loop
+    over the existing `stepWorld` kernel — no src/ changes, no new npm exports.
+  - **Protocol:**
+    - Client → `{ type: "step", commands?: AgentCommand[] }` or `{ type: "reset" }`
+    - Server → `{ type: "obs", tick, entities: ObservationSlice[], done, winner? }`
+    - On connect → `{ type: "init", config, obs }`
+  - **`ObservationSlice`** — safe subset: position, velocity, fatigue, shock/consciousness/dead,
+    detected nearby enemies (filtered via Phase 52 `canDetect`). No raw internals exposed.
+  - **`AgentCommand`** — validated high-level actions: `attack | move | dodge | flee | idle`.
+    Invalid team targeting silently dropped; `decideCommandsForEntity` fills in missing commands.
+  - Configurable scenario: `TEAM1_SIZE` / `TEAM2_SIZE` (1–4 each), `SEED`, `MAX_TICKS` via env vars.
+    Default: 1v1, Knight (longsword + mail) vs Brawler (club).
+  - Agent-driven stepping: server advances only when client sends `step` — agent controls tick rate.
+  - Determinism preserved: external commands injected via existing `CommandMap` before `stepWorld`.
+  - HTTP endpoints: `GET /config`, `GET /status`, `POST /reset`.
+  - Run: `npm run agent-server`
+  - **Success criterion met:** An external Python script using only `websockets` can drive a single
+    entity through a 1v1 fight, receiving `ObservationSlice` observations each tick and submitting
+    `attack` / `move` commands, without importing any Ananke TypeScript.
+
+---
+
+## [0.1.17] — 2026-03-26
+
+### Added
+
+- **Phase 73 · Enhanced Epidemiological Models** (`src/sim/disease.ts` extended in-place)
+  - `VaccinationRecord { diseaseId, efficacy_Q, doseCount }` — partial-efficacy vaccination
+    stored on `entity.vaccinations?`; `vaccinate(entity, diseaseId, efficacy_Q)` helper.
+  - `ageSusceptibility_Q(ageYears)` — U-shaped multiplier: infants ×1.30, children ×0.80,
+    adults ×1.00, early elderly ×1.20, late elderly ×1.50. Auto-applied in
+    `computeTransmissionRisk` when `entity.age` is set.
+  - `NPIType`, `NPIRecord`, `NPIRegistry` — non-pharmaceutical intervention registry;
+    `applyNPI / removeNPI / hasNPI` helpers. `mask_mandate` reduces airborne transmission
+    by `NPI_MASK_REDUCTION_Q = q(0.60)` (60 %). `quarantine` recorded for host-side pair
+    filtering.
+  - `computeTransmissionRisk` extended with optional 5th `options?` parameter — backward-
+    compatible; applies vaccination, age susceptibility, and NPI effects when present.
+  - `computeR0(profile, entityMap)` — basic reproductive number estimate
+    (β × infectious-days × min(15, population−1)); used for validation.
+  - `stepSEIR(entity, delta_s, profile, worldSeed, tick)` — SEIR-aware entity step that
+    isolates a single disease profile; delegates to Phase 56 `stepDiseaseForEntity` for
+    full backward compatibility.
+  - `registerDiseaseProfile(profile)` — registers custom/SEIR profiles into the lookup map
+    without modifying the canonical `DISEASE_PROFILES` array.
+  - `MEASLES` profile (`useSeir: true`): R0 ≈ 15.1 in population ≥ 16, 14-day incubation,
+    14-day infectious period, 0.2 % IFR, permanent immunity. Validates epidemic curve
+    peaking days 10–20 and burning out by day 60 (matches standard SIR output ±15 %).
+  - `entity.vaccinations?: VaccinationRecord[]` added to `Entity`.
+  - `DiseaseProfile.useSeir?: boolean` opt-in field (no effect on existing callers).
+  - 37 new tests in `test/disease-seir.test.ts`. All 37 Phase 56 tests pass unmodified.
+  - **3 998 tests total.**
+
+---
+
 ## [0.1.16] — 2026-03-25
 
 ### Added

package/dist/src/economy-gen.d.ts

@@ -0,0 +1,133 @@
+import { type Q } from "./units.js";
+import type { Polity, PolityRegistry, PolityPair } from "./polity.js";
+import { TechEra } from "./sim/tech.js";
+/** Per-step fraction pulled back toward base price (8%). */
+export declare const MEAN_REVERSION_Q: number;
+/** Debt/treasury ratio above which a polity is in crisis (30%). */
+export declare const DEBT_CRISIS_RATIO_Q: number;
+/** Supply fraction added to market in an economic warfare dump (40%). */
+export declare const SUPPLY_DUMP_Q: number;
+/** Base trade income per shared location per commodity per step (cost-units). */
+export declare const TRADE_BASE_CU = 50;
+/** Fraction of treasury wagered per speculate() call (10%). */
+export declare const SPECULATE_WAGER_Q: number;
+/**
+ * Profit multiplier on a winning speculation — applied to the wager amount.
+ * q(1.0) means winner gains exactly the wager (net +wager).
+ * Combined with WIN_PROBABILITY_NUM/DEN = 45/100, EV = −10% per call.
+ */
+export declare const SPECULATE_WIN_MUL_Q: number;
+/** Numerator of win probability fraction (45%). */
+export declare const WIN_PROBABILITY_NUM = 45;
+export interface CommodityProfile {
+    readonly id: string;
+    readonly name: string;
+    /** Base price [0, SCALE.Q]. Long-run equilibrium the market reverts toward. */
+    readonly basePrice_Q: Q;
+    /** Maximum random price swing per step (±half this per step). */
+    readonly volatility_Q: Q;
+    /** Minimum tech era required for a polity to produce this commodity. */
+    readonly techMinEra: TechEra;
+}
+export interface PriceRecord {
+    /** Current market price [q(0.05), q(2.0)]. */
+    price_Q: Q;
+    /** Available supply [0, SCALE.Q]. */
+    supply_Q: Q;
+    /** Active demand [0, SCALE.Q]. */
+    demand_Q: Q;
+}
+export interface MarketState {
+    /** Current prices for each commodity. Keyed by CommodityProfile.id. */
+    prices: Map<string, PriceRecord>;
+    /** Outstanding debt per polity: polityId → cost-units owed. */
+    debt: Map<string, number>;
+}
+export interface MarketStepResult {
+    /** Trade income credited this step: polityId → cost-units. */
+    tradeIncome: Map<string, number>;
+    /** IDs of polities that are in (or entered) a debt crisis this step. */
+    crisisPolities: string[];
+}
+export interface EconomicWarfareResult {
+    /** Cost-units spent by the aggressor on the dump operation. */
+    aggressorCost_cu: number;
+    /** Price decrease applied to the targeted commodity [0, SCALE.Q]. */
+    priceDrop_Q: Q;
+}
+export declare const COMMODITIES: readonly CommodityProfile[];
+/** Returns commodity IDs a polity can produce given its tech era. */
+export declare function availableCommodities(techEra: TechEra): string[];
+/** Create a fresh MarketState with all commodities at base price, balanced supply/demand. */
+export declare function createMarket(): MarketState;
+/**
+ * Advance all commodity prices by one step.
+ *
+ * Each commodity's price changes by:
+ *   reversion  = MEAN_REVERSION_Q × (basePrice − current) / SCALE.Q
+ *   noise      = ±(volatility_Q / 2) via deterministic eventSeed
+ *   imbalance  = (demand_Q − supply_Q) × 5% / SCALE.Q   (supply/demand pressure)
+ *
+ * Result is clamped to [q(0.05), q(2.0)] to prevent collapse or runaway inflation.
+ */
+export declare function stepPrices(market: MarketState, worldSeed: number, tick: number): void;
+/**
+ * Resolve trade between all non-war polity pairs and credit treasury.
+ *
+ * For each non-war pair: the traded commodity set is the intersection of each
+ * polity's tech-era-gated catalogue.  Income per commodity =
+ *   `price_Q × TRADE_BASE_CU × sharedLocations × routeQuality_Q / SCALE.Q²`
+ *
+ * Both polities in a pair receive equal income.  Mutates `polity.treasury_cu`.
+ * Returns a map of total income credited this step per polity id.
+ */
+export declare function stepTrade(registry: PolityRegistry, pairs: PolityPair[], market: MarketState): Map<string, number>;
+/**
+ * Polity bets a fraction of treasury on a commodity price movement.
+ *
+ * Wager = `SPECULATE_WAGER_Q` (10%) of current treasury.
+ * Win probability = `WIN_PROBABILITY_NUM` / 100 (45%).  On win: treasury gains
+ * `wager × SPECULATE_WIN_MUL_Q / SCALE.Q`.  On loss: treasury loses the wager;
+ * if treasury is insufficient, the shortfall is added to `market.debt`.
+ *
+ * Expected value ≈ −10% per call (house-edge model for opaque markets).
+ * Returns the net treasury change (positive = profit, negative = loss or debt).
+ */
+export declare function speculate(polity: Polity, commodityId: string, worldSeed: number, tick: number): number;
+/**
+ * Returns true when the polity's debt exceeds the crisis threshold.
+ *
+ * Crisis triggers when:
+ * - `debt > treasury × DEBT_CRISIS_RATIO_Q / SCALE.Q`   (debt ratio exceeded), or
+ * - `treasury ≤ 0 AND debt > 0`                          (insolvency)
+ */
+export declare function checkDebtCrisis(polity: Polity, market: MarketState): boolean;
+/**
+ * Aggressor dumps supply of a commodity onto the market to depress its price.
+ *
+ * Supply increases by `SUPPLY_DUMP_Q`, capped at SCALE.Q.  Price drops
+ * proportionally to the supply increase × commodity volatility.
+ * Aggressor pays `TRADE_BASE_CU × SUPPLY_DUMP_Q / SCALE.Q × sharedLocations`
+ * cost-units (stockpile overhead).
+ *
+ * No-op if the commodity requires a higher tech era than the aggressor possesses,
+ * or if either polity is not in the registry.
+ */
+export declare function economicWarfare(aggressorId: string, targetId: string, commodityId: string, registry: PolityRegistry, market: MarketState, pairs: PolityPair[]): EconomicWarfareResult;
+/**
+ * Derive aggregate economic stress for a polity [0, SCALE.Q].
+ *
+ * Three components, equal weighting:
+ * 1. Debt ratio    — `clamp(debt / max(treasury, 1), 0, SCALE.Q)`
+ * 2. Price stress  — fraction of the polity's available commodities below 60% of base
+ * 3. War penalty   — q(0.20) per active war involving this polity, capped at q(0.60)
+ */
+export declare function deriveEconomicPressure(polity: Polity, market: MarketState, registry: PolityRegistry): Q;
+/**
+ * Full market step: advance prices, resolve trade, return income and crisis list.
+ *
+ * Call once per campaign day.  Mutates `market.prices`, polity `treasury_cu`
+ * values inside `registry`, and `market.debt` (via `checkDebtCrisis` reads only —
+ * debt is written by `speculate`, not by `stepMarket` directly).
+ */
+export declare function stepMarket(registry: PolityRegistry, pairs: PolityPair[], market: MarketState, worldSeed: number, tick: number): MarketStepResult;

package/dist/src/economy-gen.js

@@ -0,0 +1,261 @@
+// src/economy-gen.ts — Phase 72: Generative Economics
+//
+// Agent-based commodity markets for polity-scale simulation.
+// Extends Phase 61 (Polity) with price dynamics, debt cycles, and economic warfare.
+//
+// All values are fixed-point; no floating-point in the simulation path.
+// No Math.random() — determinism via eventSeed().
+import { q, SCALE, clampQ } from "./units.js";
+import { eventSeed, hashString } from "./sim/seeds.js";
+import { TechEra } from "./sim/tech.js";
+// ── Constants ──────────────────────────────────────────────────────────────────
+/** Per-step fraction pulled back toward base price (8%). */
+export const MEAN_REVERSION_Q = q(0.08);
+/** Debt/treasury ratio above which a polity is in crisis (30%). */
+export const DEBT_CRISIS_RATIO_Q = q(0.30);
+/** Supply fraction added to market in an economic warfare dump (40%). */
+export const SUPPLY_DUMP_Q = q(0.40);
+/** Base trade income per shared location per commodity per step (cost-units). */
+export const TRADE_BASE_CU = 50;
+/** Fraction of treasury wagered per speculate() call (10%). */
+export const SPECULATE_WAGER_Q = q(0.10);
+/**
+ * Profit multiplier on a winning speculation — applied to the wager amount.
+ * q(1.0) means winner gains exactly the wager (net +wager).
+ * Combined with WIN_PROBABILITY_NUM/DEN = 45/100, EV = −10% per call.
+ */
+export const SPECULATE_WIN_MUL_Q = q(1.0);
+/** Numerator of win probability fraction (45%). */
+export const WIN_PROBABILITY_NUM = 45;
+// ── Commodity catalogue ────────────────────────────────────────────────────────
+export const COMMODITIES = [
+    { id: "grain", name: "Grain", basePrice_Q: q(0.20), volatility_Q: q(0.12), techMinEra: TechEra.Prehistoric },
+    { id: "timber", name: "Timber", basePrice_Q: q(0.25), volatility_Q: q(0.08), techMinEra: TechEra.Prehistoric },
+    { id: "iron", name: "Iron", basePrice_Q: q(0.40), volatility_Q: q(0.15), techMinEra: TechEra.Ancient },
+    { id: "textile", name: "Textile", basePrice_Q: q(0.35), volatility_Q: q(0.10), techMinEra: TechEra.Ancient },
+    { id: "spice", name: "Spice", basePrice_Q: q(0.60), volatility_Q: q(0.25), techMinEra: TechEra.Ancient },
+    { id: "labour", name: "Labour", basePrice_Q: q(0.15), volatility_Q: q(0.05), techMinEra: TechEra.Prehistoric },
+    { id: "arcane", name: "Arcane Goods", basePrice_Q: q(0.80), volatility_Q: q(0.30), techMinEra: TechEra.Medieval },
+    { id: "manufactured", name: "Manufactured Goods", basePrice_Q: q(0.50), volatility_Q: q(0.18), techMinEra: TechEra.EarlyModern },
+];
+// ── Helpers ────────────────────────────────────────────────────────────────────
+/** Returns commodity IDs a polity can produce given its tech era. */
+export function availableCommodities(techEra) {
+    return COMMODITIES.filter(c => c.techMinEra <= techEra).map(c => c.id);
+}
+// ── Market creation ────────────────────────────────────────────────────────────
+/** Create a fresh MarketState with all commodities at base price, balanced supply/demand. */
+export function createMarket() {
+    const prices = new Map();
+    for (const c of COMMODITIES) {
+        prices.set(c.id, { price_Q: c.basePrice_Q, supply_Q: q(0.50), demand_Q: q(0.50) });
+    }
+    return { prices, debt: new Map() };
+}
+// ── Price dynamics ─────────────────────────────────────────────────────────────
+/**
+ * Advance all commodity prices by one step.
+ *
+ * Each commodity's price changes by:
+ *   reversion  = MEAN_REVERSION_Q × (basePrice − current) / SCALE.Q
+ *   noise      = ±(volatility_Q / 2) via deterministic eventSeed
+ *   imbalance  = (demand_Q − supply_Q) × 5% / SCALE.Q   (supply/demand pressure)
+ *
+ * Result is clamped to [q(0.05), q(2.0)] to prevent collapse or runaway inflation.
+ */
+export function stepPrices(market, worldSeed, tick) {
+    for (const c of COMMODITIES) {
+        const rec = market.prices.get(c.id);
+        // Mean reversion toward base price
+        const gap = c.basePrice_Q - rec.price_Q;
+        const reversion = Math.trunc(gap * MEAN_REVERSION_Q / SCALE.Q);
+        // Deterministic noise in [-volatility/2, +volatility/2)
+        const salt = hashString(c.id);
+        const raw = eventSeed(worldSeed, tick, 0, 0, salt);
+        const half = Math.trunc(c.volatility_Q / 2);
+        const noise = Math.trunc(raw % c.volatility_Q) - half;
+        // Supply/demand imbalance: excess demand = higher price, excess supply = lower
+        const imbalance = Math.trunc((rec.demand_Q - rec.supply_Q) * 5 / 100);
+        rec.price_Q = clampQ(rec.price_Q + reversion + noise + imbalance, q(0.05), q(2.0));
+    }
+}
+// ── Trade income ───────────────────────────────────────────────────────────────
+/**
+ * Resolve trade between all non-war polity pairs and credit treasury.
+ *
+ * For each non-war pair: the traded commodity set is the intersection of each
+ * polity's tech-era-gated catalogue.  Income per commodity =
+ *   `price_Q × TRADE_BASE_CU × sharedLocations × routeQuality_Q / SCALE.Q²`
+ *
+ * Both polities in a pair receive equal income.  Mutates `polity.treasury_cu`.
+ * Returns a map of total income credited this step per polity id.
+ */
+export function stepTrade(registry, pairs, market) {
+    const income = new Map();
+    for (const pair of pairs) {
+        const keyAB = `${pair.polityAId}:${pair.polityBId}`;
+        const keyBA = `${pair.polityBId}:${pair.polityAId}`;
+        if (registry.activeWars.has(keyAB) || registry.activeWars.has(keyBA))
+            continue;
+        const polityA = registry.polities.get(pair.polityAId);
+        const polityB = registry.polities.get(pair.polityBId);
+        if (!polityA || !polityB || pair.sharedLocations <= 0)
+            continue;
+        const aSet = new Set(availableCommodities(polityA.techEra));
+        const bSet = new Set(availableCommodities(polityB.techEra));
+        let pairIncome = 0;
+        for (const c of COMMODITIES) {
+            if (!aSet.has(c.id) || !bSet.has(c.id))
+                continue;
+            const rec = market.prices.get(c.id);
+            // price_Q × TRADE_BASE_CU / SCALE.Q → base income per location
+            const basePerLoc = Math.trunc(rec.price_Q * TRADE_BASE_CU / SCALE.Q);
+            pairIncome += Math.trunc(basePerLoc * pair.sharedLocations * pair.routeQuality_Q / SCALE.Q);
+        }
+        if (pairIncome > 0) {
+            polityA.treasury_cu += pairIncome;
+            polityB.treasury_cu += pairIncome;
+            income.set(pair.polityAId, (income.get(pair.polityAId) ?? 0) + pairIncome);
+            income.set(pair.polityBId, (income.get(pair.polityBId) ?? 0) + pairIncome);
+        }
+    }
+    return income;
+}
+// ── Speculation ────────────────────────────────────────────────────────────────
+/**
+ * Polity bets a fraction of treasury on a commodity price movement.
+ *
+ * Wager = `SPECULATE_WAGER_Q` (10%) of current treasury.
+ * Win probability = `WIN_PROBABILITY_NUM` / 100 (45%).  On win: treasury gains
+ * `wager × SPECULATE_WIN_MUL_Q / SCALE.Q`.  On loss: treasury loses the wager;
+ * if treasury is insufficient, the shortfall is added to `market.debt`.
+ *
+ * Expected value ≈ −10% per call (house-edge model for opaque markets).
+ * Returns the net treasury change (positive = profit, negative = loss or debt).
+ */
+export function speculate(polity, commodityId, worldSeed, tick) {
+    const wager = Math.trunc(polity.treasury_cu * SPECULATE_WAGER_Q / SCALE.Q);
+    if (wager <= 0)
+        return 0;
+    const salt = hashString("speculate_" + commodityId);
+    const roll = eventSeed(worldSeed, tick, hashString(polity.id), 0, salt) % SCALE.Q;
+    const threshold = Math.trunc(SCALE.Q * WIN_PROBABILITY_NUM / 100);
+    if (roll < threshold) {
+        const profit = Math.trunc(wager * SPECULATE_WIN_MUL_Q / SCALE.Q);
+        polity.treasury_cu += profit;
+        return profit;
+    }
+    else {
+        polity.treasury_cu -= wager; // always safe: wager = 10% of treasury ≤ treasury
+        return -wager;
+    }
+}
+// ── Debt crisis ────────────────────────────────────────────────────────────────
+/**
+ * Returns true when the polity's debt exceeds the crisis threshold.
+ *
+ * Crisis triggers when:
+ * - `debt > treasury × DEBT_CRISIS_RATIO_Q / SCALE.Q`   (debt ratio exceeded), or
+ * - `treasury ≤ 0 AND debt > 0`                          (insolvency)
+ */
+export function checkDebtCrisis(polity, market) {
+    const debt = market.debt.get(polity.id) ?? 0;
+    if (debt <= 0)
+        return false;
+    if (polity.treasury_cu <= 0)
+        return true;
+    const threshold = Math.trunc(polity.treasury_cu * DEBT_CRISIS_RATIO_Q / SCALE.Q);
+    return debt > threshold;
+}
+// ── Economic warfare ───────────────────────────────────────────────────────────
+/**
+ * Aggressor dumps supply of a commodity onto the market to depress its price.
+ *
+ * Supply increases by `SUPPLY_DUMP_Q`, capped at SCALE.Q.  Price drops
+ * proportionally to the supply increase × commodity volatility.
+ * Aggressor pays `TRADE_BASE_CU × SUPPLY_DUMP_Q / SCALE.Q × sharedLocations`
+ * cost-units (stockpile overhead).
+ *
+ * No-op if the commodity requires a higher tech era than the aggressor possesses,
+ * or if either polity is not in the registry.
+ */
+export function economicWarfare(aggressorId, targetId, commodityId, registry, market, pairs) {
+    const aggressor = registry.polities.get(aggressorId);
+    if (!aggressor || !registry.polities.has(targetId))
+        return { aggressorCost_cu: 0, priceDrop_Q: 0 };
+    const comm = COMMODITIES.find(c => c.id === commodityId);
+    if (!comm || comm.techMinEra > aggressor.techEra)
+        return { aggressorCost_cu: 0, priceDrop_Q: 0 };
+    const rec = market.prices.get(commodityId);
+    const prev = rec.supply_Q;
+    rec.supply_Q = clampQ(rec.supply_Q + SUPPLY_DUMP_Q, 0, SCALE.Q);
+    const supplyIncrease = rec.supply_Q - prev;
+    // Price drop proportional to the supply increase × volatility
+    const priceDrop_Q = Math.trunc(supplyIncrease * comm.volatility_Q / SCALE.Q);
+    rec.price_Q = clampQ(rec.price_Q - priceDrop_Q, q(0.05), q(2.0));
+    // Aggressor pays stockpile cost based on shared border with target
+    const sharedLocs = pairs.find(p => (p.polityAId === aggressorId && p.polityBId === targetId) ||
+        (p.polityAId === targetId && p.polityBId === aggressorId))?.sharedLocations ?? 1;
+    const aggressorCost_cu = Math.trunc(TRADE_BASE_CU * SUPPLY_DUMP_Q / SCALE.Q) * sharedLocs;
+    aggressor.treasury_cu = Math.max(0, aggressor.treasury_cu - aggressorCost_cu);
+    return { aggressorCost_cu, priceDrop_Q };
+}
+// ── Economic pressure ──────────────────────────────────────────────────────────
+/**
+ * Derive aggregate economic stress for a polity [0, SCALE.Q].
+ *
+ * Three components, equal weighting:
+ * 1. Debt ratio    — `clamp(debt / max(treasury, 1), 0, SCALE.Q)`
+ * 2. Price stress  — fraction of the polity's available commodities below 60% of base
+ * 3. War penalty   — q(0.20) per active war involving this polity, capped at q(0.60)
+ */
+export function deriveEconomicPressure(polity, market, registry) {
+    // 1. Debt ratio
+    const debt = market.debt.get(polity.id) ?? 0;
+    const debtRatio = debt > 0
+        ? clampQ(Math.trunc(debt * SCALE.Q / Math.max(polity.treasury_cu, 1)), 0, SCALE.Q)
+        : 0;
+    // 2. Price stress: fraction of available commodities trading below 60% of base
+    const avail = availableCommodities(polity.techEra);
+    let depressed = 0;
+    for (const id of avail) {
+        const rec = market.prices.get(id);
+        const comm = COMMODITIES.find(c => c.id === id);
+        if (!rec || !comm)
+            continue;
+        // 60% = 3/5 — integer arithmetic only
+        if (rec.price_Q < Math.trunc(comm.basePrice_Q * 3 / 5))
+            depressed++;
+    }
+    const priceStress = avail.length > 0
+        ? Math.trunc(depressed * SCALE.Q / avail.length)
+        : 0;
+    // 3. War penalty
+    let warCount = 0;
+    for (const key of registry.activeWars) {
+        const [a, b] = key.split(":");
+        if (a === polity.id || b === polity.id)
+            warCount++;
+    }
+    const warPenalty = clampQ(warCount * q(0.20), 0, q(0.60));
+    // Combined: equal thirds (integer division to keep fixed-point)
+    return clampQ((debtRatio + priceStress + warPenalty) / 3, 0, SCALE.Q);
+}
+// ── Composite step ─────────────────────────────────────────────────────────────
+/**
+ * Full market step: advance prices, resolve trade, return income and crisis list.
+ *
+ * Call once per campaign day.  Mutates `market.prices`, polity `treasury_cu`
+ * values inside `registry`, and `market.debt` (via `checkDebtCrisis` reads only —
+ * debt is written by `speculate`, not by `stepMarket` directly).
+ */
+export function stepMarket(registry, pairs, market, worldSeed, tick) {
+    stepPrices(market, worldSeed, tick);
+    const tradeIncome = stepTrade(registry, pairs, market);
+    const crisisPolities = [];
+    for (const polity of registry.polities.values()) {
+        if (checkDebtCrisis(polity, market))
+            crisisPolities.push(polity.id);
+    }
+    return { tradeIncome, crisisPolities };
+}

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;