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

package/CHANGELOG.md

@@ -6,6 +6,46 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.24] — 2026-03-26
+
+### Added
+
+- **Phase 79 · Feudal Bonds & Vassal Tribute** (`src/feudal.ts`)
+  - `LoyaltyType`: `"kin_bound" | "oath_sworn" | "conquered" | "voluntary"` — governs base strength and daily decay rate.
+  - `VassalBond { vassalPolityId, liegePolityId, loyaltyType, tributeRate_Q, levyRate_Q, strength_Q, establishedTick }` — directed lord-vassal record.
+  - `FeudalRegistry { bonds: Map<string, VassalBond> }` keyed by `"vassalId:liegeId"`.
+  - `LOYALTY_BASE_STRENGTH`: kin_bound q(0.90) → oath_sworn q(0.70) → voluntary q(0.65) → conquered q(0.40).
+  - `LOYALTY_DECAY_PER_DAY`: kin_bound q(0.001)/day → conquered q(0.005)/day.
+  - `REBELLION_THRESHOLD = q(0.25)` — `isRebellionRisk(bond)` returns true below this.
+  - `computeDailyTribute` / `applyDailyTribute` — floor-based tribute scaled by `tributeRate_Q / SCALE.Q / 365`.
+  - `computeLevyStrength(vassal, bond)` — effective levy reduced proportionally by bond weakness (`strength_Q`).
+  - `stepBondStrength(bond, boostDelta_Q?)` — daily decay with optional event boost.
+  - `reinforceBond(bond, deltaQ)` — clamped-to-SCALE.Q reinforcement for kinship events and tribute.
+  - `breakVassalBond(registry, vassalId, liegeId, vassalRulerId?, renownRegistry?)` — removes bond; adds `OATH_BREAK_INFAMY_Q = q(0.15)` infamy to the vassal ruler for `oath_sworn` breaks (Phase 75 integration).
+  - Added `./feudal` subpath export to `package.json`.
+  - 58 new tests; 4,247 total. Coverage maintained above all thresholds.
+
+---
+
+## [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

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;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@its-not-rocket-science/ananke",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",
@@ -74,6 +74,14 @@
     "./succession": {
       "import": "./dist/src/succession.js",
       "types": "./dist/src/succession.d.ts"
+    },
+    "./calendar": {
+      "import": "./dist/src/calendar.js",
+      "types": "./dist/src/calendar.d.ts"
+    },
+    "./feudal": {
+      "import": "./dist/src/feudal.js",
+      "types": "./dist/src/feudal.d.ts"
     }
   },
   "files": [