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

package/CHANGELOG.md

@@ -6,6 +6,51 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.26] — 2026-03-26
+
+### Added
+
+- **Phase 81 · Migration & Displacement** (`src/migration.ts`)
+  - `MigrationFlow { fromPolityId, toPolityId, population }` — a resolved daily population transfer.
+  - `MigrationContext { polityId, isAtWar?, lowestBondStr_Q? }` — optional per-polity war/feudal context passed by the host.
+  - `computePushPressure(polity, isAtWar?, lowestBondStr_Q?)` → Q — stability deficit + morale deficit + war bonus (`MIGRATION_WAR_PUSH_Q = q(0.20)`) + feudal-bond deficit below `MIGRATION_PUSH_FEUDAL_THRESHOLD = q(0.30)`.
+  - `computePullFactor(polity)` → Q — `stabilityQ × moraleQ / SCALE.Q`; both must be high to attract migrants.
+  - `computeMigrationFlow(from, to, push_Q, pull_Q)` → integer — 0 if push < `MIGRATION_PUSH_MIN_Q = q(0.05)` or pull = 0; floors to integer; max daily rate `MIGRATION_DAILY_RATE_Q = q(0.001)` (0.1% of population at full pressure).
+  - `resolveMigration(polities[], context?)` → `MigrationFlow[]` — collects all directed pair flows above threshold.
+  - `applyMigrationFlows(polityRegistry, flows)` — mutates `population` on sending and receiving polities; clamps to prevent negative populations.
+  - `estimateNetMigrationRate(polityId, flows, population)` → signed fraction — positive = net immigration, negative = net emigration.
+  - Integrates with Phase 61 (Polity), Phase 79 (Feudal bond strength), Phase 80 (Diplomacy) without direct imports — callers supply context.
+  - Added `./migration` subpath export to `package.json`.
+  - 41 new tests; 4,343 total. Coverage maintained above all thresholds.
+
+---
+
+## [0.1.25] — 2026-03-26
+
+### Added
+
+- **Phase 80 · Diplomacy & Treaties** (`src/diplomacy.ts`)
+  - `TreatyType`: `"non_aggression" | "trade_pact" | "peace" | "military_alliance" | "royal_marriage"`.
+  - `Treaty { treatyId, polityAId, polityBId, type, strength_Q, signedTick, expiryTick, tributeFromA_Q, tributeFromB_Q }` — bilateral agreement with optional tribute clause and finite or permanent duration.
+  - `TreatyRegistry { treaties: Map<string, Treaty> }` — keyed by canonical sorted pair + type; order-independent.
+  - `TREATY_BASE_STRENGTH`: military_alliance q(0.80) → trade_pact q(0.50).
+  - `TREATY_DECAY_PER_DAY`: military_alliance q(0.001)/day → non_aggression q(0.003)/day.
+  - `TREATY_BREAK_INFAMY`: military_alliance q(0.25) → trade_pact q(0.05) — Phase 75 integration.
+  - `TREATY_FRAGILE_THRESHOLD = q(0.20)` — `isTreatyFragile(treaty)` returns true below this.
+  - `signTreaty(registry, polityAId, polityBId, type, tick?, duration?, tributeFromA?, tributeFromB?)` — creates or replaces a treaty.
+  - `getTreaty(registry, polityAId, polityBId, type)` — symmetric lookup.
+  - `getActiveTreaties(registry, polityId)` — all treaties for a given polity.
+  - `isTreatyExpired(treaty, currentTick)` — true at/after `expiryTick`; permanent (`-1`) never expires.
+  - `stepTreatyStrength(treaty, boostDelta_Q?)` — daily decay with optional event boost.
+  - `reinforceTreaty(treaty, deltaQ)` — clamped reinforcement.
+  - `breakTreaty(registry, polityAId, polityBId, type, breakerRulerId?, renownRegistry?)` — removes treaty; adds `TREATY_BREAK_INFAMY[type]` infamy to breaker.
+  - `computeDiplomaticPrestige(registry, polityId)` → Q — sum of active treaty strengths, clamped to SCALE.Q.
+  - `areInAnyTreaty(registry, polityAId, polityBId)` → boolean.
+  - Added `./diplomacy` subpath export to `package.json`.
+  - 55 new tests; 4,302 total. Coverage maintained above all thresholds.
+
+---
+
 ## [0.1.24] — 2026-03-26
 
 ### Added

package/dist/src/diplomacy.d.ts

@@ -0,0 +1,109 @@
+import type { RenownRegistry } from "./renown.js";
+import type { Q } from "./units.js";
+/** Category of diplomatic agreement. */
+export type TreatyType = "non_aggression" | "trade_pact" | "peace" | "military_alliance" | "royal_marriage";
+/**
+ * A bilateral diplomatic agreement between two polities.
+ * Stored in `TreatyRegistry`; keyed by canonical sorted pair + type.
+ */
+export interface Treaty {
+    /** Opaque unique id (host-assigned or from `treatyKey`). */
+    treatyId: string;
+    polityAId: string;
+    polityBId: string;
+    type: TreatyType;
+    /** Agreement health [0, SCALE.Q]. Below `TREATY_FRAGILE_THRESHOLD` → at risk. */
+    strength_Q: Q;
+    /** Simulation tick when signed. */
+    signedTick: number;
+    /**
+     * Tick when treaty expires. `-1` = permanent until broken.
+     * Hosts should call `isTreatyExpired` each tick and remove or renew.
+     */
+    expiryTick: number;
+    /**
+     * Annual tribute from polityA to polityB as a fraction of polityA treasury.
+     * `0` = no tribute clause. Range [0, SCALE.Q].
+     */
+    tributeFromA_Q: Q;
+    /**
+     * Annual tribute from polityB to polityA as a fraction of polityB treasury.
+     * `0` = no tribute clause. Range [0, SCALE.Q].
+     */
+    tributeFromB_Q: Q;
+}
+/** Registry of all active treaties. */
+export interface TreatyRegistry {
+    treaties: Map<string, Treaty>;
+}
+/** Treaty strength below this → `isTreatyFragile` returns true. */
+export declare const TREATY_FRAGILE_THRESHOLD: Q;
+/** Base strength at signing per treaty type. */
+export declare const TREATY_BASE_STRENGTH: Record<TreatyType, Q>;
+/** Daily strength decay per treaty type (per simulated day). */
+export declare const TREATY_DECAY_PER_DAY: Record<TreatyType, Q>;
+/**
+ * Infamy added to the breaker's renown record on treaty violation.
+ * Military alliances carry the gravest penalty; trade pacts the lightest.
+ */
+export declare const TREATY_BREAK_INFAMY: Record<TreatyType, Q>;
+export declare function createTreatyRegistry(): TreatyRegistry;
+/**
+ * Canonical treaty key — independent of argument order.
+ * Polity IDs are sorted lexicographically so `key(A,B,t) === key(B,A,t)`.
+ */
+export declare function treatyKey(polityAId: string, polityBId: string, type: TreatyType): string;
+/**
+ * Sign a new treaty between two polities and register it.
+ * If a treaty of the same type between the same pair already exists it is
+ * replaced (renewal).
+ *
+ * @param tick            Current simulation tick (day).
+ * @param durationTicks   How many ticks the treaty lasts; `-1` = permanent.
+ * @param tributeFromA_Q  Annual tribute fraction from A to B (default 0).
+ * @param tributeFromB_Q  Annual tribute fraction from B to A (default 0).
+ */
+export declare function signTreaty(registry: TreatyRegistry, polityAId: string, polityBId: string, type: TreatyType, tick?: number, durationTicks?: number, tributeFromA_Q?: Q, tributeFromB_Q?: Q): Treaty;
+/** Return the treaty between two polities of the given type, or `undefined`. */
+export declare function getTreaty(registry: TreatyRegistry, polityAId: string, polityBId: string, type: TreatyType): Treaty | undefined;
+/** Return all active treaties involving `polityId` (as either party). */
+export declare function getActiveTreaties(registry: TreatyRegistry, polityId: string): Treaty[];
+/**
+ * Return `true` if the treaty has expired at `currentTick`.
+ * Permanent treaties (`expiryTick === -1`) never expire.
+ */
+export declare function isTreatyExpired(treaty: Treaty, currentTick: number): boolean;
+/**
+ * Advance treaty strength by one simulated day.
+ * Decays at `TREATY_DECAY_PER_DAY[type]`; `boostDelta_Q` is an optional
+ * signed daily bonus (e.g., tribute paid, joint victory, diplomatic summit).
+ * Mutates `treaty.strength_Q`.
+ */
+export declare function stepTreatyStrength(treaty: Treaty, boostDelta_Q?: Q): void;
+/**
+ * Reinforce a treaty by a fixed delta (e.g., after a tribute payment, joint
+ * military victory, or diplomatic summit). Clamps to [0, SCALE.Q].
+ */
+export declare function reinforceTreaty(treaty: Treaty, deltaQ: Q): void;
+/** Return `true` if treaty strength is below `TREATY_FRAGILE_THRESHOLD`. */
+export declare function isTreatyFragile(treaty: Treaty): boolean;
+/**
+ * Break a treaty and remove it from the registry.
+ * Adds `TREATY_BREAK_INFAMY[type]` to `breakerRulerId`'s renown record
+ * if `breakerRulerId` and `renownRegistry` are provided.
+ *
+ * @returns `true` if a treaty was found and removed; `false` otherwise.
+ */
+export declare function breakTreaty(registry: TreatyRegistry, polityAId: string, polityBId: string, type: TreatyType, breakerRulerId?: number, renownRegistry?: RenownRegistry): boolean;
+/**
+ * Compute the diplomatic prestige of a polity as the sum of `strength_Q`
+ * of all its active treaties, normalised to [0, SCALE.Q].
+ *
+ * Hosts should pass only non-expired treaties; this function does no
+ * expiry filtering.
+ */
+export declare function computeDiplomaticPrestige(registry: TreatyRegistry, polityId: string): Q;
+/**
+ * Return `true` if the two polities have at least one active treaty of any type.
+ */
+export declare function areInAnyTreaty(registry: TreatyRegistry, polityAId: string, polityBId: string): boolean;

package/dist/src/diplomacy.js

@@ -0,0 +1,167 @@
+// src/diplomacy.ts — Phase 80: Diplomacy & Treaties
+//
+// Formal agreements between polities. Each treaty has a type, strength,
+// optional expiry, and optional tribute clause. Strength decays over time
+// and recovers via upholding the terms. Breaking a treaty adds infamy to
+// the breaker's renown record (Phase 75).
+//
+// Design:
+//   - Pure data layer — no Entity fields, no kernel changes.
+//   - `TreatyRegistry` is external to PolityRegistry; hosts maintain both.
+//   - Treaty keys are canonical (sorted polity IDs) so order doesn't matter.
+//   - `isTreatyExpired` is a host responsibility: expired treaties should be
+//     removed or renewed each tick.
+import { getRenownRecord } from "./renown.js";
+import { q, SCALE, clampQ } from "./units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Treaty strength below this → `isTreatyFragile` returns true. */
+export const TREATY_FRAGILE_THRESHOLD = q(0.20);
+/** Base strength at signing per treaty type. */
+export const TREATY_BASE_STRENGTH = {
+    military_alliance: q(0.80),
+    royal_marriage: q(0.75),
+    peace: q(0.60),
+    non_aggression: q(0.55),
+    trade_pact: q(0.50),
+};
+/** Daily strength decay per treaty type (per simulated day). */
+export const TREATY_DECAY_PER_DAY = {
+    military_alliance: q(0.001), // very slow — costly to abandon
+    royal_marriage: q(0.001),
+    peace: q(0.002),
+    non_aggression: q(0.003),
+    trade_pact: q(0.002),
+};
+/**
+ * Infamy added to the breaker's renown record on treaty violation.
+ * Military alliances carry the gravest penalty; trade pacts the lightest.
+ */
+export const TREATY_BREAK_INFAMY = {
+    military_alliance: q(0.25),
+    royal_marriage: q(0.20),
+    peace: q(0.15),
+    non_aggression: q(0.10),
+    trade_pact: q(0.05),
+};
+// ── Factory ───────────────────────────────────────────────────────────────────
+export function createTreatyRegistry() {
+    return { treaties: new Map() };
+}
+// ── Key helpers ───────────────────────────────────────────────────────────────
+/**
+ * Canonical treaty key — independent of argument order.
+ * Polity IDs are sorted lexicographically so `key(A,B,t) === key(B,A,t)`.
+ */
+export function treatyKey(polityAId, polityBId, type) {
+    const [lo, hi] = polityAId < polityBId
+        ? [polityAId, polityBId]
+        : [polityBId, polityAId];
+    return `${lo}:${hi}:${type}`;
+}
+// ── Treaty management ─────────────────────────────────────────────────────────
+/**
+ * Sign a new treaty between two polities and register it.
+ * If a treaty of the same type between the same pair already exists it is
+ * replaced (renewal).
+ *
+ * @param tick            Current simulation tick (day).
+ * @param durationTicks   How many ticks the treaty lasts; `-1` = permanent.
+ * @param tributeFromA_Q  Annual tribute fraction from A to B (default 0).
+ * @param tributeFromB_Q  Annual tribute fraction from B to A (default 0).
+ */
+export function signTreaty(registry, polityAId, polityBId, type, tick = 0, durationTicks = -1, tributeFromA_Q = 0, tributeFromB_Q = 0) {
+    const key = treatyKey(polityAId, polityBId, type);
+    const treaty = {
+        treatyId: key,
+        polityAId,
+        polityBId,
+        type,
+        strength_Q: TREATY_BASE_STRENGTH[type],
+        signedTick: tick,
+        expiryTick: durationTicks < 0 ? -1 : tick + durationTicks,
+        tributeFromA_Q,
+        tributeFromB_Q,
+    };
+    registry.treaties.set(key, treaty);
+    return treaty;
+}
+/** Return the treaty between two polities of the given type, or `undefined`. */
+export function getTreaty(registry, polityAId, polityBId, type) {
+    return registry.treaties.get(treatyKey(polityAId, polityBId, type));
+}
+/** Return all active treaties involving `polityId` (as either party). */
+export function getActiveTreaties(registry, polityId) {
+    return [...registry.treaties.values()].filter(t => t.polityAId === polityId || t.polityBId === polityId);
+}
+// ── Expiry ────────────────────────────────────────────────────────────────────
+/**
+ * Return `true` if the treaty has expired at `currentTick`.
+ * Permanent treaties (`expiryTick === -1`) never expire.
+ */
+export function isTreatyExpired(treaty, currentTick) {
+    return treaty.expiryTick !== -1 && currentTick >= treaty.expiryTick;
+}
+// ── Strength dynamics ─────────────────────────────────────────────────────────
+/**
+ * Advance treaty strength by one simulated day.
+ * Decays at `TREATY_DECAY_PER_DAY[type]`; `boostDelta_Q` is an optional
+ * signed daily bonus (e.g., tribute paid, joint victory, diplomatic summit).
+ * Mutates `treaty.strength_Q`.
+ */
+export function stepTreatyStrength(treaty, boostDelta_Q = 0) {
+    const decay = TREATY_DECAY_PER_DAY[treaty.type];
+    treaty.strength_Q = clampQ(treaty.strength_Q - decay + boostDelta_Q, 0, SCALE.Q);
+}
+/**
+ * Reinforce a treaty by a fixed delta (e.g., after a tribute payment, joint
+ * military victory, or diplomatic summit). Clamps to [0, SCALE.Q].
+ */
+export function reinforceTreaty(treaty, deltaQ) {
+    treaty.strength_Q = clampQ(treaty.strength_Q + deltaQ, 0, SCALE.Q);
+}
+/** Return `true` if treaty strength is below `TREATY_FRAGILE_THRESHOLD`. */
+export function isTreatyFragile(treaty) {
+    return treaty.strength_Q < TREATY_FRAGILE_THRESHOLD;
+}
+// ── Treaty breaking ───────────────────────────────────────────────────────────
+/**
+ * Break a treaty and remove it from the registry.
+ * Adds `TREATY_BREAK_INFAMY[type]` to `breakerRulerId`'s renown record
+ * if `breakerRulerId` and `renownRegistry` are provided.
+ *
+ * @returns `true` if a treaty was found and removed; `false` otherwise.
+ */
+export function breakTreaty(registry, polityAId, polityBId, type, breakerRulerId, renownRegistry) {
+    const key = treatyKey(polityAId, polityBId, type);
+    const treaty = registry.treaties.get(key);
+    if (!treaty)
+        return false;
+    if (breakerRulerId != null && renownRegistry != null) {
+        const record = getRenownRecord(renownRegistry, breakerRulerId);
+        record.infamy_Q = clampQ(record.infamy_Q + TREATY_BREAK_INFAMY[type], 0, SCALE.Q);
+    }
+    registry.treaties.delete(key);
+    return true;
+}
+// ── Diplomatic prestige ───────────────────────────────────────────────────────
+/**
+ * Compute the diplomatic prestige of a polity as the sum of `strength_Q`
+ * of all its active treaties, normalised to [0, SCALE.Q].
+ *
+ * Hosts should pass only non-expired treaties; this function does no
+ * expiry filtering.
+ */
+export function computeDiplomaticPrestige(registry, polityId) {
+    const treaties = getActiveTreaties(registry, polityId);
+    if (treaties.length === 0)
+        return 0;
+    const total = treaties.reduce((sum, t) => sum + t.strength_Q, 0);
+    return clampQ(total, 0, SCALE.Q);
+}
+/**
+ * Return `true` if the two polities have at least one active treaty of any type.
+ */
+export function areInAnyTreaty(registry, polityAId, polityBId) {
+    return [...registry.treaties.values()].some(t => (t.polityAId === polityAId && t.polityBId === polityBId) ||
+        (t.polityAId === polityBId && t.polityBId === polityAId));
+}

package/dist/src/migration.d.ts

@@ -0,0 +1,107 @@
+import type { Polity } from "./polity.js";
+import type { PolityRegistry } from "./polity.js";
+import type { Q } from "./units.js";
+/** A resolved population transfer from one polity to another. */
+export interface MigrationFlow {
+    fromPolityId: string;
+    toPolityId: string;
+    /** Positive integer — number of people moving. */
+    population: number;
+}
+/**
+ * Stability below this contributes to push pressure.
+ * A polity at q(0.40) stability has zero stability push; below it, pressure rises.
+ */
+export declare const MIGRATION_PUSH_STABILITY_THRESHOLD: Q;
+/**
+ * Morale below this contributes to push pressure.
+ */
+export declare const MIGRATION_PUSH_MORALE_THRESHOLD: Q;
+/**
+ * Feudal bond strength below this contributes to push pressure.
+ * Vassals under an oppressive liege (weak bonds) bleed population.
+ */
+export declare const MIGRATION_PUSH_FEUDAL_THRESHOLD: Q;
+/**
+ * Flat push bonus added when the polity is in an active war.
+ * Represents war refugees and general insecurity.
+ */
+export declare const MIGRATION_WAR_PUSH_Q: Q;
+/**
+ * Fraction of the source polity's population that migrates per simulated day
+ * at full combined pressure and full destination pull.
+ * q(0.001) = 0.1 % per day maximum.
+ */
+export declare const MIGRATION_DAILY_RATE_Q: Q;
+/**
+ * Minimum push pressure required for migration to occur.
+ * Prevents trickle migration from perfectly stable polities.
+ */
+export declare const MIGRATION_PUSH_MIN_Q: Q;
+/**
+ * Compute the push pressure of a polity — how strongly it repels its own
+ * population. Returns a Q in [0, SCALE.Q].
+ *
+ * @param polity           Source polity.
+ * @param isAtWar          True if the polity has any active war (Phase 61).
+ * @param lowestBondStr_Q  Weakest feudal bond as vassal, or SCALE.Q if not a vassal (Phase 79).
+ */
+export declare function computePushPressure(polity: Polity, isAtWar?: boolean, lowestBondStr_Q?: Q): Q;
+/**
+ * Compute the pull factor of a polity — how attractive it is as a destination.
+ * Pull = `stabilityQ × moraleQ / SCALE.Q` — both must be high to attract migrants.
+ * Returns a Q in [0, SCALE.Q].
+ */
+export declare function computePullFactor(polity: Polity): Q;
+/**
+ * Compute the number of people that would migrate from `from` to `to` in one
+ * simulated day, given pre-computed push and pull values.
+ *
+ * Formula (integer arithmetic throughout):
+ *   combined_Q = push_Q × pull_Q / SCALE.Q
+ *   scaledPop  = population × combined_Q / SCALE.Q
+ *   flow       = floor(scaledPop × DAILY_RATE_Q / SCALE.Q)
+ *
+ * Returns 0 if push < `MIGRATION_PUSH_MIN_Q`, pull ≤ 0, or from.population ≤ 0.
+ */
+export declare function computeMigrationFlow(from: Polity, to: Polity, push_Q: Q, pull_Q: Q): number;
+/**
+ * Optional per-polity context for migration resolution.
+ * Callers supply war/feudal context without this module needing to import
+ * PolityRegistry or FeudalRegistry.
+ */
+export interface MigrationContext {
+    polityId: string;
+    isAtWar?: boolean;
+    lowestBondStr_Q?: Q;
+}
+/**
+ * Resolve all migration flows for one simulated day across the provided
+ * polities. Returns a flat list of `MigrationFlow` objects with `population > 0`.
+ *
+ * The caller should pass all polities that may send or receive migrants.
+ * Flows are not applied here — call `applyMigrationFlows` to mutate state.
+ *
+ * @param polities  Array of candidate polities.
+ * @param context   Optional per-polity war / feudal context keyed by polityId.
+ */
+export declare function resolveMigration(polities: Polity[], context?: Map<string, MigrationContext>): MigrationFlow[];
+/**
+ * Apply a list of migration flows to the polity registry.
+ * Mutates `population` on both sending and receiving polities.
+ * The actual population moved is clamped to the sender's current population
+ * to prevent negative populations.
+ *
+ * Unknown polity IDs in a flow are silently skipped.
+ */
+export declare function applyMigrationFlows(registry: PolityRegistry, flows: MigrationFlow[]): void;
+/**
+ * Compute the net annual population change due to migration for a polity,
+ * expressed as a fraction of its current population.
+ *
+ * Positive = net immigration (pull exceeds push).
+ * Negative = net emigration (push exceeds pull).
+ *
+ * Useful for AI and diplomatic decision-making.
+ */
+export declare function estimateNetMigrationRate(polityId: string, flows: MigrationFlow[], population: number): number;

package/dist/src/migration.js

@@ -0,0 +1,165 @@
+// src/migration.ts — Phase 81: Migration & Displacement
+//
+// Population movement between polities driven by push factors (instability,
+// low morale, active war, feudal oppression) and pull factors (prosperity,
+// stability). Integrates with Phase 61 (Polity), Phase 79 (Feudal), and
+// Phase 80 (Diplomacy) without importing any of them directly — callers
+// pass pre-computed context values.
+//
+// Design:
+//   - Pure computation layer — no Entity fields, no kernel changes.
+//   - `computePushPressure` and `computePullFactor` are the two primitives.
+//   - `computeMigrationFlow` derives the daily migrant count for a directed pair.
+//   - `resolveMigration` collects all flows above the threshold.
+//   - `applyMigrationFlows` mutates Polity population fields.
+import { SCALE, q, clampQ, mulDiv } from "./units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/**
+ * Stability below this contributes to push pressure.
+ * A polity at q(0.40) stability has zero stability push; below it, pressure rises.
+ */
+export const MIGRATION_PUSH_STABILITY_THRESHOLD = q(0.40);
+/**
+ * Morale below this contributes to push pressure.
+ */
+export const MIGRATION_PUSH_MORALE_THRESHOLD = q(0.40);
+/**
+ * Feudal bond strength below this contributes to push pressure.
+ * Vassals under an oppressive liege (weak bonds) bleed population.
+ */
+export const MIGRATION_PUSH_FEUDAL_THRESHOLD = q(0.30);
+/**
+ * Flat push bonus added when the polity is in an active war.
+ * Represents war refugees and general insecurity.
+ */
+export const MIGRATION_WAR_PUSH_Q = q(0.20);
+/**
+ * Fraction of the source polity's population that migrates per simulated day
+ * at full combined pressure and full destination pull.
+ * q(0.001) = 0.1 % per day maximum.
+ */
+export const MIGRATION_DAILY_RATE_Q = q(0.001);
+/**
+ * Minimum push pressure required for migration to occur.
+ * Prevents trickle migration from perfectly stable polities.
+ */
+export const MIGRATION_PUSH_MIN_Q = q(0.05);
+// ── Core computation ───────────────────────────────────────────────────────────
+/**
+ * Compute the push pressure of a polity — how strongly it repels its own
+ * population. Returns a Q in [0, SCALE.Q].
+ *
+ * @param polity           Source polity.
+ * @param isAtWar          True if the polity has any active war (Phase 61).
+ * @param lowestBondStr_Q  Weakest feudal bond as vassal, or SCALE.Q if not a vassal (Phase 79).
+ */
+export function computePushPressure(polity, isAtWar = false, lowestBondStr_Q = SCALE.Q) {
+    const stabilityDeficit = Math.max(0, MIGRATION_PUSH_STABILITY_THRESHOLD - polity.stabilityQ);
+    const moraleDeficit = Math.max(0, MIGRATION_PUSH_MORALE_THRESHOLD - polity.moraleQ);
+    const warBonus = isAtWar ? MIGRATION_WAR_PUSH_Q : 0;
+    const feudalDeficit = Math.max(0, MIGRATION_PUSH_FEUDAL_THRESHOLD - lowestBondStr_Q);
+    return clampQ(stabilityDeficit + moraleDeficit + warBonus + feudalDeficit, 0, SCALE.Q);
+}
+/**
+ * Compute the pull factor of a polity — how attractive it is as a destination.
+ * Pull = `stabilityQ × moraleQ / SCALE.Q` — both must be high to attract migrants.
+ * Returns a Q in [0, SCALE.Q].
+ */
+export function computePullFactor(polity) {
+    return clampQ(mulDiv(polity.stabilityQ, polity.moraleQ, SCALE.Q), 0, SCALE.Q);
+}
+/**
+ * Compute the number of people that would migrate from `from` to `to` in one
+ * simulated day, given pre-computed push and pull values.
+ *
+ * Formula (integer arithmetic throughout):
+ *   combined_Q = push_Q × pull_Q / SCALE.Q
+ *   scaledPop  = population × combined_Q / SCALE.Q
+ *   flow       = floor(scaledPop × DAILY_RATE_Q / SCALE.Q)
+ *
+ * Returns 0 if push < `MIGRATION_PUSH_MIN_Q`, pull ≤ 0, or from.population ≤ 0.
+ */
+export function computeMigrationFlow(from, to, push_Q, pull_Q) {
+    if (push_Q < MIGRATION_PUSH_MIN_Q)
+        return 0;
+    if (pull_Q <= 0)
+        return 0;
+    if (from.population <= 0)
+        return 0;
+    if (from.id === to.id)
+        return 0;
+    const combined_Q = mulDiv(push_Q, pull_Q, SCALE.Q);
+    const scaledPop = mulDiv(from.population, combined_Q, SCALE.Q);
+    const flow = Math.floor(scaledPop * MIGRATION_DAILY_RATE_Q / SCALE.Q);
+    return flow;
+}
+/**
+ * Resolve all migration flows for one simulated day across the provided
+ * polities. Returns a flat list of `MigrationFlow` objects with `population > 0`.
+ *
+ * The caller should pass all polities that may send or receive migrants.
+ * Flows are not applied here — call `applyMigrationFlows` to mutate state.
+ *
+ * @param polities  Array of candidate polities.
+ * @param context   Optional per-polity war / feudal context keyed by polityId.
+ */
+export function resolveMigration(polities, context = new Map()) {
+    const flows = [];
+    for (const from of polities) {
+        const ctx = context.get(from.id);
+        const push_Q = computePushPressure(from, ctx?.isAtWar ?? false, ctx?.lowestBondStr_Q ?? SCALE.Q);
+        if (push_Q < MIGRATION_PUSH_MIN_Q)
+            continue;
+        for (const to of polities) {
+            if (to.id === from.id)
+                continue;
+            const pull_Q = computePullFactor(to);
+            const n = computeMigrationFlow(from, to, push_Q, pull_Q);
+            if (n > 0)
+                flows.push({ fromPolityId: from.id, toPolityId: to.id, population: n });
+        }
+    }
+    return flows;
+}
+/**
+ * Apply a list of migration flows to the polity registry.
+ * Mutates `population` on both sending and receiving polities.
+ * The actual population moved is clamped to the sender's current population
+ * to prevent negative populations.
+ *
+ * Unknown polity IDs in a flow are silently skipped.
+ */
+export function applyMigrationFlows(registry, flows) {
+    for (const flow of flows) {
+        const from = registry.polities.get(flow.fromPolityId);
+        const to = registry.polities.get(flow.toPolityId);
+        if (!from || !to)
+            continue;
+        const actual = Math.min(flow.population, from.population);
+        if (actual <= 0)
+            continue;
+        from.population -= actual;
+        to.population += actual;
+    }
+}
+/**
+ * Compute the net annual population change due to migration for a polity,
+ * expressed as a fraction of its current population.
+ *
+ * Positive = net immigration (pull exceeds push).
+ * Negative = net emigration (push exceeds pull).
+ *
+ * Useful for AI and diplomatic decision-making.
+ */
+export function estimateNetMigrationRate(polityId, flows, population) {
+    if (population <= 0)
+        return 0;
+    let net = 0;
+    for (const f of flows) {
+        if (f.fromPolityId === polityId)
+            net -= f.population;
+        if (f.toPolityId === polityId)
+            net += f.population;
+    }
+    return net / population;
+}

package/package.json

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