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

package/CHANGELOG.md

@@ -6,6 +6,29 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.27] — 2026-03-26
+
+### Added
+
+- **Phase 82 · Espionage & Intelligence Networks** (`src/espionage.ts`)
+  - `OperationType`: `"intelligence_gather" | "treaty_sabotage" | "bond_subversion" | "treasury_theft" | "incite_migration"`.
+  - `AgentStatus`: `"active" | "compromised" | "captured"`.
+  - `SpyAgent { agentId, ownerPolityId, targetPolityId, operation, status, deployedTick, skill_Q }`.
+  - `EspionageRegistry { agents: Map<number, SpyAgent> }` — keyed by entity ID.
+  - `OperationResult { success, detected, effectDelta_Q }`.
+  - `OPERATION_BASE_SUCCESS_Q`: intelligence_gather q(0.70) → treasury_theft q(0.35).
+  - `OPERATION_DETECTION_RISK_Q`: treasury_theft q(0.40) → intelligence_gather q(0.10).
+  - `OPERATION_EFFECT_Q`: incite_migration q(0.15) → intelligence_gather q(0.00).
+  - `COVER_DECAY_PER_DAY = q(0.005)` — daily base cover-loss risk, mitigated by skill.
+  - `resolveOperation(agent, worldSeed, tick)` → `OperationResult` — deterministic via `eventSeed`; idempotent for same inputs; no-op for non-active agents.
+  - `stepAgentCover(agent, worldSeed, tick)` — daily cover check; may flip status to `"compromised"` or `"captured"` (50/50 split via secondary seed).
+  - `deployAgent`, `recallAgent`, `getAgentsByOwner`, `getAgentsByTarget`.
+  - `computeCounterIntelligence(registry, targetPolityId)` → Q — `compromised` agent count × `COUNTER_INTEL_PER_AGENT = q(0.05)`, clamped to SCALE.Q.
+  - Added `./espionage` subpath export to `package.json`.
+  - 34 new tests; 4,377 total. Coverage maintained above all thresholds.
+
+---
+
 ## [0.1.26] — 2026-03-26
 
 ### Added

package/dist/src/espionage.d.ts

@@ -0,0 +1,103 @@
+import type { Q } from "./units.js";
+/** What the spy is trying to achieve. */
+export type OperationType = "intelligence_gather" | "treaty_sabotage" | "bond_subversion" | "treasury_theft" | "incite_migration";
+/** Current cover status of the agent in the target polity. */
+export type AgentStatus = "active" | "compromised" | "captured";
+/**
+ * A spy deployed by one polity against another.
+ * Stored in `EspionageRegistry`, keyed by `agentId` (entity ID).
+ */
+export interface SpyAgent {
+    /** Entity ID of the spy character. */
+    agentId: number;
+    ownerPolityId: string;
+    targetPolityId: string;
+    operation: OperationType;
+    status: AgentStatus;
+    /** Simulation tick when the agent was deployed. */
+    deployedTick: number;
+    /**
+     * Agent skill [0, SCALE.Q].
+     * Higher skill → better success rate and lower detection risk.
+     */
+    skill_Q: Q;
+}
+/** Registry of all deployed spy agents. */
+export interface EspionageRegistry {
+    agents: Map<number, SpyAgent>;
+}
+/** Outcome of a single operation resolution. */
+export interface OperationResult {
+    success: boolean;
+    detected: boolean;
+    /**
+     * Magnitude of the effect in Q units.
+     * For `treasury_theft` this is a fraction of treasury; host scales to cu.
+     * For `intelligence_gather` this is always 0 (effect is information).
+     */
+    effectDelta_Q: Q;
+}
+/**
+ * Base success probability per operation at agent skill = SCALE.Q.
+ * Actual threshold = `skill_Q × BASE_SUCCESS_Q / SCALE.Q`.
+ */
+export declare const OPERATION_BASE_SUCCESS_Q: Record<OperationType, Q>;
+/**
+ * Detection probability on failure for each operation.
+ * High-impact operations (treasury_theft) are riskier.
+ */
+export declare const OPERATION_DETECTION_RISK_Q: Record<OperationType, Q>;
+/**
+ * Maximum effect delta per successful operation, scaled by `skill_Q`.
+ * `intelligence_gather` has no Q delta (information is the outcome).
+ */
+export declare const OPERATION_EFFECT_Q: Record<OperationType, Q>;
+/**
+ * Daily base probability that an active agent's cover is blown
+ * regardless of operations. Low but non-zero.
+ */
+export declare const COVER_DECAY_PER_DAY: Q;
+export declare function createEspionageRegistry(): EspionageRegistry;
+/**
+ * Deploy an agent and register them.
+ * If an agent with this ID is already registered they are replaced.
+ */
+export declare function deployAgent(registry: EspionageRegistry, agentId: number, ownerPolityId: string, targetPolityId: string, operation: OperationType, skill_Q: Q, tick?: number): SpyAgent;
+/** Recall (remove) an active agent. Returns `true` if found and removed. */
+export declare function recallAgent(registry: EspionageRegistry, agentId: number): boolean;
+/** Return all agents deployed by `ownerPolityId`. */
+export declare function getAgentsByOwner(registry: EspionageRegistry, ownerPolityId: string): SpyAgent[];
+/** Return all agents currently operating against `targetPolityId`. */
+export declare function getAgentsByTarget(registry: EspionageRegistry, targetPolityId: string): SpyAgent[];
+/**
+ * Resolve one tick of an operation. Idempotent for the same (worldSeed, tick).
+ *
+ * Success check:
+ *   successThreshold = skill_Q × BASE_SUCCESS_Q[op] / SCALE.Q
+ *   successRoll      = eventSeed(…, opSalt) % SCALE.Q
+ *   success          = successRoll < successThreshold
+ *
+ * Detection check (only on failure):
+ *   detectionRoll = eventSeed(…, opSalt+1) % SCALE.Q
+ *   detected      = detectionRoll < DETECTION_RISK_Q[op]
+ *
+ * Does NOT mutate `agent.status` — call `stepAgentCover` for passive detection.
+ */
+export declare function resolveOperation(agent: SpyAgent, worldSeed: number, tick: number): OperationResult;
+/**
+ * Run a daily cover check for an active agent.
+ * If the check fires, the agent transitions to "compromised" or "captured"
+ * (50/50 split via a secondary roll).
+ * Mutates `agent.status` directly.
+ * No-op if agent is already compromised or captured.
+ */
+export declare function stepAgentCover(agent: SpyAgent, worldSeed: number, tick: number): void;
+/**
+ * Compute the counterintelligence strength of a polity based on the number
+ * of known (compromised) agents inside its borders.
+ * Returns a Q modifier applied by hosts to reduce incoming operation success.
+ *
+ * `knownAgentCount × COUNTER_INTEL_PER_AGENT`, clamped to [0, SCALE.Q].
+ */
+export declare const COUNTER_INTEL_PER_AGENT: Q;
+export declare function computeCounterIntelligence(registry: EspionageRegistry, targetPolityId: string): Q;

package/dist/src/espionage.js

@@ -0,0 +1,166 @@
+// src/espionage.ts — Phase 82: Espionage & Intelligence Networks
+//
+// Covert operations between polities. Each deployed spy runs a specific
+// operation that resolves deterministically via eventSeed. Detection
+// risk rises with operation severity and falls with agent skill.
+//
+// Design:
+//   - Pure data layer — no Entity fields, no kernel changes.
+//   - `EspionageRegistry` tracks deployed agents by entity ID.
+//   - `resolveOperation` returns success/detection/effectDelta each time it
+//     is called — idempotent for the same (worldSeed, tick) inputs.
+//   - Callers apply `effectDelta_Q` to the relevant Phase-79/80 registry.
+//   - `stepAgentCover` is called once per simulated day and may flip an
+//     "active" agent to "compromised" or "captured".
+import { eventSeed, hashString } from "./sim/seeds.js";
+import { q, SCALE, clampQ, mulDiv } from "./units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/**
+ * Base success probability per operation at agent skill = SCALE.Q.
+ * Actual threshold = `skill_Q × BASE_SUCCESS_Q / SCALE.Q`.
+ */
+export const OPERATION_BASE_SUCCESS_Q = {
+    intelligence_gather: q(0.70),
+    treaty_sabotage: q(0.50),
+    bond_subversion: q(0.45),
+    treasury_theft: q(0.35),
+    incite_migration: q(0.55),
+};
+/**
+ * Detection probability on failure for each operation.
+ * High-impact operations (treasury_theft) are riskier.
+ */
+export const OPERATION_DETECTION_RISK_Q = {
+    intelligence_gather: q(0.10),
+    incite_migration: q(0.15),
+    treaty_sabotage: q(0.20),
+    bond_subversion: q(0.25),
+    treasury_theft: q(0.40),
+};
+/**
+ * Maximum effect delta per successful operation, scaled by `skill_Q`.
+ * `intelligence_gather` has no Q delta (information is the outcome).
+ */
+export const OPERATION_EFFECT_Q = {
+    intelligence_gather: q(0.00),
+    treaty_sabotage: q(0.10),
+    bond_subversion: q(0.08),
+    treasury_theft: q(0.05),
+    incite_migration: q(0.15),
+};
+/**
+ * Daily base probability that an active agent's cover is blown
+ * regardless of operations. Low but non-zero.
+ */
+export const COVER_DECAY_PER_DAY = q(0.005);
+// ── Salt constants (deterministic per operation type) ──────────────────────────
+const OP_SALT = {
+    intelligence_gather: 1001,
+    treaty_sabotage: 1002,
+    bond_subversion: 1003,
+    treasury_theft: 1004,
+    incite_migration: 1005,
+};
+const COVER_CHECK_SALT = 9901;
+// ── Factory ───────────────────────────────────────────────────────────────────
+export function createEspionageRegistry() {
+    return { agents: new Map() };
+}
+// ── Agent management ───────────────────────────────────────────────────────────
+/**
+ * Deploy an agent and register them.
+ * If an agent with this ID is already registered they are replaced.
+ */
+export function deployAgent(registry, agentId, ownerPolityId, targetPolityId, operation, skill_Q, tick = 0) {
+    const agent = {
+        agentId,
+        ownerPolityId,
+        targetPolityId,
+        operation,
+        status: "active",
+        deployedTick: tick,
+        skill_Q,
+    };
+    registry.agents.set(agentId, agent);
+    return agent;
+}
+/** Recall (remove) an active agent. Returns `true` if found and removed. */
+export function recallAgent(registry, agentId) {
+    return registry.agents.delete(agentId);
+}
+/** Return all agents deployed by `ownerPolityId`. */
+export function getAgentsByOwner(registry, ownerPolityId) {
+    return [...registry.agents.values()].filter(a => a.ownerPolityId === ownerPolityId);
+}
+/** Return all agents currently operating against `targetPolityId`. */
+export function getAgentsByTarget(registry, targetPolityId) {
+    return [...registry.agents.values()].filter(a => a.targetPolityId === targetPolityId);
+}
+// ── Operation resolution ───────────────────────────────────────────────────────
+/**
+ * Resolve one tick of an operation. Idempotent for the same (worldSeed, tick).
+ *
+ * Success check:
+ *   successThreshold = skill_Q × BASE_SUCCESS_Q[op] / SCALE.Q
+ *   successRoll      = eventSeed(…, opSalt) % SCALE.Q
+ *   success          = successRoll < successThreshold
+ *
+ * Detection check (only on failure):
+ *   detectionRoll = eventSeed(…, opSalt+1) % SCALE.Q
+ *   detected      = detectionRoll < DETECTION_RISK_Q[op]
+ *
+ * Does NOT mutate `agent.status` — call `stepAgentCover` for passive detection.
+ */
+export function resolveOperation(agent, worldSeed, tick) {
+    if (agent.status !== "active") {
+        return { success: false, detected: false, effectDelta_Q: 0 };
+    }
+    const targetHash = hashString(agent.targetPolityId);
+    const salt = OP_SALT[agent.operation];
+    const successSeed = eventSeed(worldSeed, tick, agent.agentId, targetHash, salt);
+    const successRoll = successSeed % SCALE.Q;
+    const successThresh = mulDiv(agent.skill_Q, OPERATION_BASE_SUCCESS_Q[agent.operation], SCALE.Q);
+    const success = successRoll < successThresh;
+    const detectSeed = eventSeed(worldSeed, tick, agent.agentId, targetHash, salt + 1);
+    const detectRoll = detectSeed % SCALE.Q;
+    const detected = !success && detectRoll < OPERATION_DETECTION_RISK_Q[agent.operation];
+    const effectDelta_Q = success
+        ? clampQ(mulDiv(agent.skill_Q, OPERATION_EFFECT_Q[agent.operation], SCALE.Q), 0, SCALE.Q)
+        : 0;
+    return { success, detected, effectDelta_Q };
+}
+/**
+ * Run a daily cover check for an active agent.
+ * If the check fires, the agent transitions to "compromised" or "captured"
+ * (50/50 split via a secondary roll).
+ * Mutates `agent.status` directly.
+ * No-op if agent is already compromised or captured.
+ */
+export function stepAgentCover(agent, worldSeed, tick) {
+    if (agent.status !== "active")
+        return;
+    const targetHash = hashString(agent.targetPolityId);
+    // Skill reduces detection: effective risk = COVER_DECAY × (1 - skill / SCALE.Q)
+    const skillMitigation = mulDiv(COVER_DECAY_PER_DAY, agent.skill_Q, SCALE.Q);
+    const effectiveRisk = Math.max(0, COVER_DECAY_PER_DAY - skillMitigation);
+    const coverSeed = eventSeed(worldSeed, tick, agent.agentId, targetHash, COVER_CHECK_SALT);
+    const coverRoll = coverSeed % SCALE.Q;
+    if (coverRoll < effectiveRisk) {
+        const captSeed = eventSeed(worldSeed, tick, agent.agentId, targetHash, COVER_CHECK_SALT + 1);
+        agent.status = (captSeed % 2 === 0) ? "captured" : "compromised";
+    }
+}
+// ── Counterintelligence ────────────────────────────────────────────────────────
+/**
+ * Compute the counterintelligence strength of a polity based on the number
+ * of known (compromised) agents inside its borders.
+ * Returns a Q modifier applied by hosts to reduce incoming operation success.
+ *
+ * `knownAgentCount × COUNTER_INTEL_PER_AGENT`, clamped to [0, SCALE.Q].
+ */
+export const COUNTER_INTEL_PER_AGENT = q(0.05);
+export function computeCounterIntelligence(registry, targetPolityId) {
+    const known = getAgentsByTarget(registry, targetPolityId)
+        .filter(a => a.status === "compromised").length;
+    return clampQ(known * COUNTER_INTEL_PER_AGENT, 0, SCALE.Q);
+}

package/dist/src/trade-routes.d.ts

@@ -0,0 +1,108 @@
+import type { Polity } from "./polity.js";
+import type { Q } from "./units.js";
+/**
+ * A bilateral trade route between two polities.
+ * Both parties earn income each day a route is active.
+ */
+export interface TradeRoute {
+    /** Canonical key (sorted polity IDs). */
+    routeId: string;
+    polityAId: string;
+    polityBId: string;
+    /**
+     * Annual trade value in cost-units at full efficiency.
+     * Each polity earns `floor(baseVolume_cu × efficiency / 365)` per day.
+     */
+    baseVolume_cu: number;
+    /**
+     * Current route health [0, SCALE.Q].
+     * Below `ROUTE_VIABLE_THRESHOLD` the route is considered inactive.
+     */
+    efficiency_Q: Q;
+    /** Simulation tick (day) when the route was established. */
+    establishedTick: number;
+}
+/** Registry of all active trade routes. */
+export interface TradeRegistry {
+    routes: Map<string, TradeRoute>;
+}
+/** Daily income produced for both polities from a single route resolution. */
+export interface TradeIncome {
+    incomeA_cu: number;
+    incomeB_cu: number;
+}
+/** Route efficiency below this → `isRouteViable` returns false. */
+export declare const ROUTE_VIABLE_THRESHOLD: Q;
+/** Daily efficiency decay (without maintenance). */
+export declare const ROUTE_DECAY_PER_DAY: Q;
+/** Multiplier applied to both parties' income when a trade pact is active. */
+export declare const TREATY_TRADE_BONUS_Q: Q;
+/** Days per year used in the daily trade fraction calculation. */
+export declare const TRADE_DAYS_PER_YEAR = 365;
+export declare function createTradeRegistry(): TradeRegistry;
+/**
+ * Canonical route key — independent of argument order.
+ * Polity IDs are sorted lexicographically so `key(A,B) === key(B,A)`.
+ */
+export declare function routeKey(polityAId: string, polityBId: string): string;
+/**
+ * Establish a new trade route (or replace an existing one).
+ *
+ * @param baseVolume_cu Annual trade value in cost-units at 100% efficiency.
+ * @param tick          Current simulation tick.
+ */
+export declare function establishRoute(registry: TradeRegistry, polityAId: string, polityBId: string, baseVolume_cu: number, tick?: number): TradeRoute;
+/** Return the route between two polities, or `undefined` if none. */
+export declare function getRoute(registry: TradeRegistry, polityAId: string, polityBId: string): TradeRoute | undefined;
+/** Return all routes involving `polityId` (as either party). */
+export declare function getRoutesForPolity(registry: TradeRegistry, polityId: string): TradeRoute[];
+/** Remove a route from the registry. Returns `true` if found and removed. */
+export declare function abandonRoute(registry: TradeRegistry, polityAId: string, polityBId: string): boolean;
+/** Return `true` if the route is efficient enough to trade. */
+export declare function isRouteViable(route: TradeRoute): boolean;
+/**
+ * Compute the daily trade income for both polities from one route.
+ *
+ * Formula:
+ *   base = floor(baseVolume_cu × efficiency_Q / SCALE.Q / TRADE_DAYS_PER_YEAR)
+ *   bonus multiplier = SCALE.Q + (hasTradePact ? TREATY_TRADE_BONUS_Q : 0)
+ *   seasonal multiplier = seasonalMul_Q (default SCALE.Q = no modification)
+ *   income = floor(base × bonusMul / SCALE.Q × seasonalMul / SCALE.Q)
+ *
+ * Returns `{ incomeA_cu: 0, incomeB_cu: 0 }` if the route is not viable.
+ *
+ * @param hasTradePact  True if a Phase-80 trade_pact treaty is active between the pair.
+ * @param seasonalMul_Q Phase-78 seasonal modifier (default SCALE.Q = no change).
+ */
+export declare function computeDailyTradeIncome(route: TradeRoute, hasTradePact?: boolean, seasonalMul_Q?: Q): TradeIncome;
+/**
+ * Apply one day of trade: add computed income to both polity treasuries.
+ * Mutates both polity objects.
+ * Returns the `TradeIncome` applied (both zero if route not viable).
+ */
+export declare function applyDailyTrade(polityA: Polity, polityB: Polity, route: TradeRoute, hasTradePact?: boolean, seasonalMul_Q?: Q): TradeIncome;
+/**
+ * Advance route efficiency by one simulated day.
+ * Decays at `ROUTE_DECAY_PER_DAY`; `boostDelta_Q` is an optional signed
+ * daily bonus (e.g., from road maintenance, diplomatic investment).
+ * Mutates `route.efficiency_Q`.
+ */
+export declare function stepRouteEfficiency(route: TradeRoute, boostDelta_Q?: Q): void;
+/**
+ * Reinforce a route (e.g., road investment, diplomatic summit).
+ * Clamps to [0, SCALE.Q].
+ */
+export declare function reinforceRoute(route: TradeRoute, deltaQ: Q): void;
+/**
+ * Disrupt a route by reducing efficiency by `disruption_Q`.
+ * Used by callers applying espionage results (Phase 82), war declarations,
+ * or hazard events.
+ * Clamps to 0.
+ */
+export declare function disruptRoute(route: TradeRoute, disruption_Q: Q): void;
+/**
+ * Compute the total annual trade volume flowing through all viable routes
+ * for a given polity (sum of `baseVolume_cu × efficiency_Q / SCALE.Q`).
+ * Useful for AI and diplomatic valuation.
+ */
+export declare function computeAnnualTradeVolume(registry: TradeRegistry, polityId: string): number;

package/dist/src/trade-routes.js

@@ -0,0 +1,146 @@
+// src/trade-routes.ts — Phase 83: Trade Routes & Inter-Polity Commerce
+//
+// World-scale bilateral trade routes between polities. Each route has an
+// annual base volume (cost-units), a current efficiency score, and optional
+// treaty / seasonal multipliers supplied by the host.
+//
+// Design:
+//   - Pure data layer — no Entity fields, no kernel changes.
+//   - Route keys are canonical (sorted polity IDs) — symmetric lookup.
+//   - Trade is mutually beneficial: both polities earn income each day.
+//   - `disruptRoute` integrates with Phase 82 (espionage) and Phase 61 (war).
+//   - `TREATY_TRADE_BONUS_Q` rewards Phase-80 trade pacts without a direct import.
+import { q, SCALE, clampQ } from "./units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Route efficiency below this → `isRouteViable` returns false. */
+export const ROUTE_VIABLE_THRESHOLD = q(0.10);
+/** Daily efficiency decay (without maintenance). */
+export const ROUTE_DECAY_PER_DAY = q(0.001);
+/** Multiplier applied to both parties' income when a trade pact is active. */
+export const TREATY_TRADE_BONUS_Q = q(0.20);
+/** Days per year used in the daily trade fraction calculation. */
+export const TRADE_DAYS_PER_YEAR = 365;
+// ── Factory ───────────────────────────────────────────────────────────────────
+export function createTradeRegistry() {
+    return { routes: new Map() };
+}
+// ── Key helper ─────────────────────────────────────────────────────────────────
+/**
+ * Canonical route key — independent of argument order.
+ * Polity IDs are sorted lexicographically so `key(A,B) === key(B,A)`.
+ */
+export function routeKey(polityAId, polityBId) {
+    const [lo, hi] = polityAId < polityBId
+        ? [polityAId, polityBId]
+        : [polityBId, polityAId];
+    return `${lo}:${hi}`;
+}
+// ── Route management ───────────────────────────────────────────────────────────
+/**
+ * Establish a new trade route (or replace an existing one).
+ *
+ * @param baseVolume_cu Annual trade value in cost-units at 100% efficiency.
+ * @param tick          Current simulation tick.
+ */
+export function establishRoute(registry, polityAId, polityBId, baseVolume_cu, tick = 0) {
+    const key = routeKey(polityAId, polityBId);
+    const route = {
+        routeId: key,
+        polityAId,
+        polityBId,
+        baseVolume_cu,
+        efficiency_Q: SCALE.Q,
+        establishedTick: tick,
+    };
+    registry.routes.set(key, route);
+    return route;
+}
+/** Return the route between two polities, or `undefined` if none. */
+export function getRoute(registry, polityAId, polityBId) {
+    return registry.routes.get(routeKey(polityAId, polityBId));
+}
+/** Return all routes involving `polityId` (as either party). */
+export function getRoutesForPolity(registry, polityId) {
+    return [...registry.routes.values()].filter(r => r.polityAId === polityId || r.polityBId === polityId);
+}
+/** Remove a route from the registry. Returns `true` if found and removed. */
+export function abandonRoute(registry, polityAId, polityBId) {
+    return registry.routes.delete(routeKey(polityAId, polityBId));
+}
+// ── Viability ──────────────────────────────────────────────────────────────────
+/** Return `true` if the route is efficient enough to trade. */
+export function isRouteViable(route) {
+    return route.efficiency_Q >= ROUTE_VIABLE_THRESHOLD;
+}
+// ── Income computation ─────────────────────────────────────────────────────────
+/**
+ * Compute the daily trade income for both polities from one route.
+ *
+ * Formula:
+ *   base = floor(baseVolume_cu × efficiency_Q / SCALE.Q / TRADE_DAYS_PER_YEAR)
+ *   bonus multiplier = SCALE.Q + (hasTradePact ? TREATY_TRADE_BONUS_Q : 0)
+ *   seasonal multiplier = seasonalMul_Q (default SCALE.Q = no modification)
+ *   income = floor(base × bonusMul / SCALE.Q × seasonalMul / SCALE.Q)
+ *
+ * Returns `{ incomeA_cu: 0, incomeB_cu: 0 }` if the route is not viable.
+ *
+ * @param hasTradePact  True if a Phase-80 trade_pact treaty is active between the pair.
+ * @param seasonalMul_Q Phase-78 seasonal modifier (default SCALE.Q = no change).
+ */
+export function computeDailyTradeIncome(route, hasTradePact = false, seasonalMul_Q = SCALE.Q) {
+    if (!isRouteViable(route))
+        return { incomeA_cu: 0, incomeB_cu: 0 };
+    const effBase = Math.floor(route.baseVolume_cu * route.efficiency_Q / SCALE.Q / TRADE_DAYS_PER_YEAR);
+    const bonusMul = SCALE.Q + (hasTradePact ? TREATY_TRADE_BONUS_Q : 0);
+    const withBonus = Math.floor(effBase * bonusMul / SCALE.Q);
+    const income = Math.floor(withBonus * seasonalMul_Q / SCALE.Q);
+    return { incomeA_cu: income, incomeB_cu: income };
+}
+/**
+ * Apply one day of trade: add computed income to both polity treasuries.
+ * Mutates both polity objects.
+ * Returns the `TradeIncome` applied (both zero if route not viable).
+ */
+export function applyDailyTrade(polityA, polityB, route, hasTradePact = false, seasonalMul_Q = SCALE.Q) {
+    const income = computeDailyTradeIncome(route, hasTradePact, seasonalMul_Q);
+    polityA.treasury_cu += income.incomeA_cu;
+    polityB.treasury_cu += income.incomeB_cu;
+    return income;
+}
+// ── Efficiency dynamics ────────────────────────────────────────────────────────
+/**
+ * Advance route efficiency by one simulated day.
+ * Decays at `ROUTE_DECAY_PER_DAY`; `boostDelta_Q` is an optional signed
+ * daily bonus (e.g., from road maintenance, diplomatic investment).
+ * Mutates `route.efficiency_Q`.
+ */
+export function stepRouteEfficiency(route, boostDelta_Q = 0) {
+    route.efficiency_Q = clampQ(route.efficiency_Q - ROUTE_DECAY_PER_DAY + boostDelta_Q, 0, SCALE.Q);
+}
+/**
+ * Reinforce a route (e.g., road investment, diplomatic summit).
+ * Clamps to [0, SCALE.Q].
+ */
+export function reinforceRoute(route, deltaQ) {
+    route.efficiency_Q = clampQ(route.efficiency_Q + deltaQ, 0, SCALE.Q);
+}
+/**
+ * Disrupt a route by reducing efficiency by `disruption_Q`.
+ * Used by callers applying espionage results (Phase 82), war declarations,
+ * or hazard events.
+ * Clamps to 0.
+ */
+export function disruptRoute(route, disruption_Q) {
+    route.efficiency_Q = clampQ(route.efficiency_Q - disruption_Q, 0, SCALE.Q);
+}
+// ── Network summary ────────────────────────────────────────────────────────────
+/**
+ * Compute the total annual trade volume flowing through all viable routes
+ * for a given polity (sum of `baseVolume_cu × efficiency_Q / SCALE.Q`).
+ * Useful for AI and diplomatic valuation.
+ */
+export function computeAnnualTradeVolume(registry, polityId) {
+    return getRoutesForPolity(registry, polityId)
+        .filter(isRouteViable)
+        .reduce((sum, r) => sum + Math.floor(r.baseVolume_cu * r.efficiency_Q / SCALE.Q), 0);
+}

package/package.json

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