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

package/CHANGELOG.md

@@ -6,6 +6,137 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.23] — 2026-03-26
+
+### Added
+
+- **Phase 78 · Seasonal Calendar & Agricultural Cycle** (`src/calendar.ts`)
+  - `CalendarState { year, dayOfYear }` — immutable; advanced via `stepCalendar(state, days)`.
+  - `computeSeason(dayOfYear)` → `"winter" | "spring" | "summer" | "autumn"` (91-day quarters).
+  - `computeHarvestPhase(dayOfYear)` → `"dormant" | "planting" | "growing" | "harvest"`.
+  - `isInHarvestWindow(dayOfYear)` — true for days 274–365 (Autumn).
+  - `SeasonalModifiers { thermalOffset, precipitationMul_Q, diseaseMul_Q, mobilityMul_Q, harvestYield_Q }`.
+  - `SEASONAL_MODIFIERS` table: winter (−10 °C, zero harvest, x1.20 disease, x0.70 mobility), spring (rain, x1.30 precip, planting), summer (+5 °C, optimal mobility), autumn (peak harvest q(1.0), x1.10 disease).
+  - `applySeasonalHarvest(polity, modifiers, baseDailyIncome)` → cost-unit gain for the day.
+  - `deriveSeasonalWeatherBias(season, intensity?)` → `Partial<WeatherState>` — advisory weather for Phase-18 hosts.
+  - `applySeasonalDiseaseMul(baseRate_Q, modifiers)` → scaled transmission rate for Phase-56/73 integration.
+  - Added `./calendar` subpath export to `package.json`.
+  - 47 new tests; 4,189 total. Coverage maintained above all thresholds.
+
+---
+
+## [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

package/dist/src/calendar.d.ts

@@ -0,0 +1,118 @@
+import type { Polity } from "./polity.js";
+import type { WeatherState } from "./sim/weather.js";
+import type { Q } from "./units.js";
+export declare const DAYS_PER_YEAR = 365;
+export declare const SPRING_START_DAY = 92;
+export declare const SUMMER_START_DAY = 183;
+export declare const AUTUMN_START_DAY = 274;
+export declare const HARVEST_PLANTING_START = 92;
+export declare const HARVEST_PLANTING_END = 136;
+export declare const HARVEST_GROWING_START = 137;
+export declare const HARVEST_GROWING_END = 273;
+export declare const HARVEST_WINDOW_START = 274;
+export declare const HARVEST_WINDOW_END = 365;
+/**
+ * Approximate Q units per °C in Phase-29 thermal encoding.
+ * Matches `WEATHER_Q_PER_DEG_C` in `src/sim/weather.ts`.
+ */
+export declare const CALENDAR_Q_PER_DEG_C = 185;
+/** Macro-scale season driven by `computeSeason(dayOfYear)`. */
+export type Season = "winter" | "spring" | "summer" | "autumn";
+/** Agricultural phase for the current day. */
+export type HarvestPhase = "dormant" | "planting" | "growing" | "harvest";
+/**
+ * Persistent calendar state.  Advances via `stepCalendar(state, days)`.
+ * Year and dayOfYear are both 1-based.
+ */
+export interface CalendarState {
+    /** Simulated year number (starts at 1). */
+    year: number;
+    /** Day within the current year, 1–365. */
+    dayOfYear: number;
+}
+/**
+ * Seasonal multipliers and offsets for subsystem integration.
+ * All Q values follow the SCALE.Q convention (q(1.0) = no change).
+ */
+export interface SeasonalModifiers {
+    /**
+     * Additive thermal offset in Phase-29 Q units (1 °C ≈ CALENDAR_Q_PER_DEG_C).
+     * Negative = colder than baseline.
+     */
+    thermalOffset: number;
+    /**
+     * Multiplier on precipitation intensity and frequency [0, SCALE.Q].
+     * q(1.0) = average; q(1.30) = wet spring; q(0.70) = dry winter.
+     */
+    precipitationMul_Q: Q;
+    /**
+     * Multiplier on airborne disease transmission rate [0, SCALE.Q].
+     * q(1.0) = no change; q(1.20) = winter crowding boost.
+     */
+    diseaseMul_Q: Q;
+    /**
+     * Multiplier on overland travel speed [0, SCALE.Q].
+     * q(1.0) = normal; q(0.70) = winter snow or spring mud.
+     */
+    mobilityMul_Q: Q;
+    /**
+     * Harvest yield fraction for this season [0, SCALE.Q].
+     * q(0) = off-season (no harvest); q(1.0) = peak autumn harvest.
+     */
+    harvestYield_Q: Q;
+}
+export declare const SEASONAL_MODIFIERS: Record<Season, SeasonalModifiers>;
+/**
+ * Create a new `CalendarState` at the given year and day.
+ * Defaults to year 1, day 1 (first day of winter).
+ */
+export declare function createCalendar(startYear?: number, startDay?: number): CalendarState;
+/**
+ * Advance the calendar by `days` days (must be ≥ 0).
+ * Returns a new `CalendarState`; does NOT mutate the input.
+ */
+export declare function stepCalendar(state: CalendarState, days: number): CalendarState;
+/** Derive the current `Season` from `dayOfYear` (1–365). */
+export declare function computeSeason(dayOfYear: number): Season;
+/** Derive the current `HarvestPhase` from `dayOfYear`. */
+export declare function computeHarvestPhase(dayOfYear: number): HarvestPhase;
+/** Return `true` if the day falls within the autumn harvest window. */
+export declare function isInHarvestWindow(dayOfYear: number): boolean;
+/**
+ * Return the `SeasonalModifiers` for the given `dayOfYear`.
+ * Convenience wrapper over `SEASONAL_MODIFIERS[computeSeason(day)]`.
+ */
+export declare function getSeasonalModifiers(dayOfYear: number): SeasonalModifiers;
+/**
+ * Compute the treasury income for one simulated day, scaled by the seasonal
+ * harvest yield.
+ *
+ * @param polity           Current polity (provides treasury_cu as economic base).
+ * @param modifiers        Seasonal modifiers for this day.
+ * @param baseDailyIncome  Base income in cost-units per day (host-defined).
+ * @returns                Integer cost-unit gain for this day (≥ 0).
+ */
+export declare function applySeasonalHarvest(polity: Polity, modifiers: SeasonalModifiers, baseDailyIncome: number): number;
+/**
+ * Derive a suggested `WeatherState` biased toward the current season.
+ *
+ * The result is advisory — hosts can override or blend with their own weather
+ * system. Precipitation type:
+ *   - winter + heavy → "blizzard"; winter + light → "snow"
+ *   - spring/summer → "rain"; autumn → "rain" or dry depending on yield
+ *
+ * @param season     Current season.
+ * @param intensity  0–1 float: how extreme the seasonal weather should be.
+ *                   0 = clear; 1 = full seasonal character.
+ */
+export declare function deriveSeasonalWeatherBias(season: Season, intensity?: number): Partial<WeatherState>;
+/**
+ * Compute the effective disease transmission rate multiplier for a given
+ * base rate, applying the seasonal modifier.
+ *
+ * Result is clamped to [0, SCALE.Q × 2] (allows doubling but prevents runaway).
+ *
+ * @param baseRate_Q     Disease baseTransmissionRate_Q from DiseaseProfile.
+ * @param modifiers      Seasonal modifiers.
+ */
+export declare function applySeasonalDiseaseMul(baseRate_Q: Q, modifiers: SeasonalModifiers): Q;

package/dist/src/calendar.js

@@ -0,0 +1,182 @@
+// src/calendar.ts — Phase 78: Seasonal Calendar & Agricultural Cycle
+//
+// A campaign-scale time layer. One `CalendarState` advances by simulated days
+// and drives seasonal modifiers for weather, disease, mobility, and harvest income.
+//
+// Design:
+//   - Pure computation — no Entity fields, no kernel changes.
+//   - Immutable step: `stepCalendar` returns a new `CalendarState`.
+//   - Year divided into 4 equal seasons of 91–92 days (Northern-hemisphere convention).
+//   - `SeasonalModifiers` are the canonical interface between the calendar and
+//     subsystem-specific application helpers.
+//   - `applySeasonalHarvest` integrates directly with Phase 61 `Polity`.
+//   - `deriveSeasonalWeatherBias` produces a suggested `WeatherState` for the host.
+import { q, SCALE, clampQ } from "./units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+export const DAYS_PER_YEAR = 365;
+// Season day boundaries (1-based, Northern hemisphere)
+// Winter: 1–91   (Dec 21 – Mar 20)
+// Spring: 92–182 (Mar 21 – Jun 20)
+// Summer: 183–273 (Jun 21 – Sep 21)
+// Autumn: 274–365 (Sep 22 – Dec 20)
+export const SPRING_START_DAY = 92;
+export const SUMMER_START_DAY = 183;
+export const AUTUMN_START_DAY = 274;
+// Harvest window within Autumn: full harvest days 274–365
+export const HARVEST_PLANTING_START = 92; // spring planting begins
+export const HARVEST_PLANTING_END = 136; // planting ends mid-spring
+export const HARVEST_GROWING_START = 137; // growing begins
+export const HARVEST_GROWING_END = 273; // growing ends (end of summer)
+export const HARVEST_WINDOW_START = 274; // harvest opens
+export const HARVEST_WINDOW_END = 365; // harvest closes
+/**
+ * Approximate Q units per °C in Phase-29 thermal encoding.
+ * Matches `WEATHER_Q_PER_DEG_C` in `src/sim/weather.ts`.
+ */
+export const CALENDAR_Q_PER_DEG_C = 185;
+// ── Season modifiers table ────────────────────────────────────────────────────
+export const SEASONAL_MODIFIERS = {
+    winter: {
+        thermalOffset: -CALENDAR_Q_PER_DEG_C * 10, // ~−10 °C
+        precipitationMul_Q: q(0.70), // drier (frozen precip, less liquid)
+        diseaseMul_Q: q(1.20), // crowding and cold stress boosts disease
+        mobilityMul_Q: q(0.70), // snow and ice hinder travel
+        harvestYield_Q: q(0.00), // dormant; no harvest
+    },
+    spring: {
+        thermalOffset: 0, // baseline temperature
+        precipitationMul_Q: q(1.30), // spring rains
+        diseaseMul_Q: q(0.80), // mild weather reduces transmission
+        mobilityMul_Q: q(0.80), // mud season slows travel
+        harvestYield_Q: q(0.10), // minor early crops (spring vegetables)
+    },
+    summer: {
+        thermalOffset: CALENDAR_Q_PER_DEG_C * 5, // ~+5 °C
+        precipitationMul_Q: q(1.00), // average precipitation
+        diseaseMul_Q: q(0.90), // better hygiene conditions
+        mobilityMul_Q: q(1.00), // optimal travel conditions
+        harvestYield_Q: q(0.30), // some summer crops (hay, early grain)
+    },
+    autumn: {
+        thermalOffset: -CALENDAR_Q_PER_DEG_C * 3, // ~−3 °C
+        precipitationMul_Q: q(1.00), // average
+        diseaseMul_Q: q(1.10), // early cold season uptick
+        mobilityMul_Q: q(0.90), // cooling, shorter days
+        harvestYield_Q: q(1.00), // peak harvest
+    },
+};
+// ── Factory ───────────────────────────────────────────────────────────────────
+/**
+ * Create a new `CalendarState` at the given year and day.
+ * Defaults to year 1, day 1 (first day of winter).
+ */
+export function createCalendar(startYear = 1, startDay = 1) {
+    return {
+        year: Math.max(1, startYear),
+        dayOfYear: Math.max(1, Math.min(DAYS_PER_YEAR, startDay)),
+    };
+}
+// ── Step ──────────────────────────────────────────────────────────────────────
+/**
+ * Advance the calendar by `days` days (must be ≥ 0).
+ * Returns a new `CalendarState`; does NOT mutate the input.
+ */
+export function stepCalendar(state, days) {
+    if (days <= 0)
+        return { ...state };
+    const total = state.dayOfYear - 1 + days;
+    const yearDelta = Math.trunc(total / DAYS_PER_YEAR);
+    const dayOfYear = (total % DAYS_PER_YEAR) + 1;
+    return {
+        year: state.year + yearDelta,
+        dayOfYear,
+    };
+}
+// ── Derived state ─────────────────────────────────────────────────────────────
+/** Derive the current `Season` from `dayOfYear` (1–365). */
+export function computeSeason(dayOfYear) {
+    if (dayOfYear >= AUTUMN_START_DAY)
+        return "autumn";
+    if (dayOfYear >= SUMMER_START_DAY)
+        return "summer";
+    if (dayOfYear >= SPRING_START_DAY)
+        return "spring";
+    return "winter";
+}
+/** Derive the current `HarvestPhase` from `dayOfYear`. */
+export function computeHarvestPhase(dayOfYear) {
+    if (dayOfYear >= HARVEST_WINDOW_START)
+        return "harvest";
+    if (dayOfYear >= HARVEST_GROWING_START)
+        return "growing";
+    if (dayOfYear >= HARVEST_PLANTING_START)
+        return "planting";
+    return "dormant";
+}
+/** Return `true` if the day falls within the autumn harvest window. */
+export function isInHarvestWindow(dayOfYear) {
+    return dayOfYear >= HARVEST_WINDOW_START && dayOfYear <= HARVEST_WINDOW_END;
+}
+/**
+ * Return the `SeasonalModifiers` for the given `dayOfYear`.
+ * Convenience wrapper over `SEASONAL_MODIFIERS[computeSeason(day)]`.
+ */
+export function getSeasonalModifiers(dayOfYear) {
+    return SEASONAL_MODIFIERS[computeSeason(dayOfYear)];
+}
+// ── Subsystem integration ─────────────────────────────────────────────────────
+/**
+ * Compute the treasury income for one simulated day, scaled by the seasonal
+ * harvest yield.
+ *
+ * @param polity           Current polity (provides treasury_cu as economic base).
+ * @param modifiers        Seasonal modifiers for this day.
+ * @param baseDailyIncome  Base income in cost-units per day (host-defined).
+ * @returns                Integer cost-unit gain for this day (≥ 0).
+ */
+export function applySeasonalHarvest(polity, modifiers, baseDailyIncome) {
+    if (baseDailyIncome <= 0)
+        return 0;
+    const raw = Math.round(baseDailyIncome * modifiers.harvestYield_Q / SCALE.Q);
+    return Math.max(0, raw);
+}
+/**
+ * Derive a suggested `WeatherState` biased toward the current season.
+ *
+ * The result is advisory — hosts can override or blend with their own weather
+ * system. Precipitation type:
+ *   - winter + heavy → "blizzard"; winter + light → "snow"
+ *   - spring/summer → "rain"; autumn → "rain" or dry depending on yield
+ *
+ * @param season     Current season.
+ * @param intensity  0–1 float: how extreme the seasonal weather should be.
+ *                   0 = clear; 1 = full seasonal character.
+ */
+export function deriveSeasonalWeatherBias(season, intensity = 0.5) {
+    if (intensity <= 0)
+        return {};
+    switch (season) {
+        case "winter":
+            return {
+                precipitation: intensity >= 0.7 ? "blizzard" : "snow",
+            };
+        case "spring":
+            return intensity >= 0.5 ? { precipitation: "rain" } : {};
+        case "summer":
+            return {}; // dry summer default
+        case "autumn":
+            return intensity >= 0.6 ? { precipitation: "rain" } : {};
+    }
+}
+/**
+ * Compute the effective disease transmission rate multiplier for a given
+ * base rate, applying the seasonal modifier.
+ *
+ * Result is clamped to [0, SCALE.Q × 2] (allows doubling but prevents runaway).
+ *
+ * @param baseRate_Q     Disease baseTransmissionRate_Q from DiseaseProfile.
+ * @param modifiers      Seasonal modifiers.
+ */
+export function applySeasonalDiseaseMul(baseRate_Q, modifiers) {
+    return clampQ(Math.round(baseRate_Q * modifiers.diseaseMul_Q / SCALE.Q), 0, SCALE.Q * 2);
+}

package/dist/src/feudal.d.ts

@@ -0,0 +1,99 @@
+import type { Polity } from "./polity.js";
+import type { RenownRegistry } from "./renown.js";
+import type { Q } from "./units.js";
+/** How the vassal bond was established — affects base strength and decay rate. */
+export type LoyaltyType = "kin_bound" | "oath_sworn" | "conquered" | "voluntary";
+/**
+ * A directional bond from a vassal polity to a liege polity.
+ * Stored once per directed pair (vassal → liege).
+ */
+export interface VassalBond {
+    vassalPolityId: string;
+    liegePolityId: string;
+    loyaltyType: LoyaltyType;
+    /** Fraction of vassal `treasury_cu` paid as annual tribute [0, SCALE.Q]. */
+    tributeRate_Q: Q;
+    /** Fraction of vassal `militaryStrength_Q` available to liege as levy [0, SCALE.Q]. */
+    levyRate_Q: Q;
+    /**
+     * Bond strength [0, SCALE.Q].
+     * Below `REBELLION_THRESHOLD` the vassal is at risk of revolt.
+     */
+    strength_Q: Q;
+    /** Tick when the bond was created (for age-based decay calculations). */
+    establishedTick: number;
+}
+/** Registry of all vassal bonds, keyed by `"vassalId:liegeId"`. */
+export interface FeudalRegistry {
+    bonds: Map<string, VassalBond>;
+}
+/** Bond strength below this → `isRebellionRisk` returns true. */
+export declare const REBELLION_THRESHOLD: Q;
+/** Daily strength decay for each loyalty type (per simulated day). */
+export declare const LOYALTY_DECAY_PER_DAY: Record<LoyaltyType, Q>;
+/** Base strength at bond creation per loyalty type. */
+export declare const LOYALTY_BASE_STRENGTH: Record<LoyaltyType, Q>;
+/**
+ * Infamy added to the vassal's renown record when breaking an `oath_sworn` bond.
+ * `kin_bound` and `conquered` breaks carry no oath infamy.
+ */
+export declare const OATH_BREAK_INFAMY_Q: Q;
+/** Tribute paid daily = `TRIBUTE_DAILY_FRAC` × annual rate × treasury_cu */
+export declare const TRIBUTE_DAYS_PER_YEAR = 365;
+export declare function createFeudalRegistry(): FeudalRegistry;
+/**
+ * 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 declare function createVassalBond(registry: FeudalRegistry, vassalPolityId: string, liegePolityId: string, loyaltyType: LoyaltyType, tributeRate_Q?: Q, levyRate_Q?: Q, tick?: number): VassalBond;
+/** Return the bond from `vassalId` to `liegeId`, or `undefined` if none. */
+export declare function getBond(registry: FeudalRegistry, vassalId: string, liegeId: string): VassalBond | undefined;
+/** Return all active bonds where `liegeId` is the lord. */
+export declare function getVassals(registry: FeudalRegistry, liegeId: string): VassalBond[];
+/** Return the bond where `vassalId` is the vassal, or `undefined`. */
+export declare function getLiege(registry: FeudalRegistry, vassalId: string): VassalBond | undefined;
+/**
+ * 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 declare function computeDailyTribute(vassal: Polity, bond: VassalBond): number;
+/**
+ * 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 declare function applyDailyTribute(vassal: Polity, liege: Polity, bond: VassalBond): number;
+/**
+ * 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 declare function computeLevyStrength(vassal: Polity, bond: VassalBond): Q;
+/**
+ * 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 declare function stepBondStrength(bond: VassalBond, boostDelta_Q?: Q): void;
+/**
+ * Strengthen a bond by a fixed delta (e.g., after a kinship event or tribute payment).
+ * Clamps to [0, SCALE.Q].
+ */
+export declare function reinforceBond(bond: VassalBond, deltaQ: Q): void;
+/** Return `true` if the bond is at rebellion risk (`strength_Q < REBELLION_THRESHOLD`). */
+export declare function isRebellionRisk(bond: VassalBond): boolean;
+/**
+ * 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 declare function breakVassalBond(registry: FeudalRegistry, vassalPolityId: string, liegePolityId: string, vassalRulerId?: number, renownRegistry?: RenownRegistry): boolean;