feat(#58): trade & embargoes — TurnResult.economy ops (trade/embargo, declare/lift) with a deterministic per-turn effect and war auto-suspension

server/engine.ts

@@ -4,6 +4,7 @@
 // and (4) builds the advisor brainstorm prompt. The network call itself lives in
 // llm.ts (injectable) and is invoked by runTurn.
 import type {
+  Embargo,
   EventOutcome,
   EventType,
   GameState,
@@ -15,6 +16,7 @@ import type {
   RegionStats,
   RoundItem,
   StatKey,
+  TradeAgreement,
   War,
 } from '../shared/types';
 import { EVENT_TYPES, RELATION_STATUSES } from '../shared/types';
@@ -31,6 +33,9 @@ import {
   markerId,
   MAX_MARKERS,
   nationForPrompt,
+  type EconomyEmbargoOp,
+  type EconomyOps,
+  type EconomyTradeOp,
   type HybridOp,
   type HybridOpType,
   type MarkerInfo,
@@ -163,7 +168,9 @@ export function playerFrontier(
  * (v0.21, #16 P2): the model may only move regions across a shared border, and
  * may verify borders with the tool before answering. The contract also
  * documents the `nationOps` proposal queue (v0.23, #16 P4a) — rename plus the
- * split/merge shapes applied on player confirm (v0.24, #16 P4b).
+ * split/merge shapes applied on player confirm (v0.24, #16 P4b), and the
+ * trade & embargo economy layer (v0.35.0, #58): bilateral trades and
+ * unilateral embargoes, each ended with a `lift: true` op.
  */
 export function buildSystemPrompt(preset: Preset, withNeighboursTool = false): string {
   const rules = preset.simulationRules
@@ -216,6 +223,7 @@ export function buildSystemPrompt(preset: Preset, withNeighboursTool = false): s
     '  "takeovers": [{"nationRef":"<nation id or name>","newRegimeName":"<name of the new regime>"}],',
     '  "wars": {"declare":[{"sides":["<nationId>","<nationId>"],"aims":["<short aim>"]}],"end":[{"id":"<war id>","outcome":"<armistice|capitulation>","terms":"<short terms>"}]},',
     '  "hybrid": {"ops":[{"type":"<spy|sabotage|assassinate|cyber|economic|information|proxy>","from":"<nation id or name>","target":"<nation id or name, or region key>","detail":"<short detail>","outcome":"<success|exposed>"}]},',
+    '  "economy": {"trade":[{"a":"<nationId>","b":"<nationId>","lift":<true|false>}],"embargo":[{"from":"<nationId>","target":"<nationId>","lift":<true|false>}]},',
     '  "markers": {"add":[{"type":"<city|factory|army|port|capital|fleet|rocket|gathering>","name":"<short name>","regionKey":"<region key>"}],"remove":["<marker id>"]}',
     '}',
     '',
@@ -236,6 +244,7 @@ export function buildSystemPrompt(preset: Preset, withNeighboursTool = false): s
     '- Takeover (automatic, NOT player-confirmed): add {"takeovers":[{"nationRef":"<nation id or name>","newRegimeName":"<name of the new regime>"}]} when a low-stability nation (e.g. stability < 30) hosting a "gathering" marker is overthrown in a coup or revolution. This renames the nation to the new regime (e.g. "France" → "Vichy Regime"). Also emit a narrative "event" (political or social, outcome "success") and a stability/economy shock via "stateChanges". A takeover is an automatic in-world regime change — use "nationOps" rename only for a diplomatic/political name change that the player must confirm.',
     '- Wars ("wars") are named conflicts, each with a stable id. To DECLARE one, add {"declare":[{"sides":["<id>","<id>"],"aims":[...]}]} with at least 2 distinct belligerents: while it is active the engine AUTOMATICALLY sets both directions of every warring pair\'s relation to "war" and drags in the mutual-defense allies of each belligerent, so do NOT also emit a "war" relation for those pairs (you can never "make peace" between them without ending the war). To END an active war, add {"end":[{"id":"<war id from the user message\'s "wars" field>","outcome":"<armistice|capitulation>"}]} — only active wars can be ended, and when one ends its belligerent pairs fall back to "hostile". Propose at most 1-2 declarations per turn and narrate each declaration and each ending in "events".',
     '- Covert / hybrid ops ("hybrid.ops") are non-kinetic operations — spies, sabotage, assassination attempts, cyberattacks, economic pressure, disinformation, and proxy support. Unlike territory they NEVER move borders: a successful op applies a small, deterministic effect (a small dip in the target\'s economy / stability / military for sabotage / assassinate / cyber / economic, or a relation nudge toward hostile for information / proxy), while an "exposed" op backfires (no effect, and the actor\'s relation with the target sours by one step toward hostile). "target" may be a nation id / name or a region key (a region key hits that region\'s sole owner). Keep each detail short, propose at most a few per turn, and narrate each op in "events".',
+    '- Economy ("economy") is the trade & embargo layer: a bilateral trade (trade: {"a":"..","b":".."}) gives BOTH parties a small, deterministic economy gain every turn, while a unilateral embargo (embargo: {"from":"..","target":".."}) lowers only the TARGET\'s economy every turn. Omit "lift" to declare / impose, and set "lift":true to end or lift an existing one (the user message\'s "trades"/"embargoes" fields list what is currently active). Propose at most 1-2 operations per turn and narrate each one in "events". Trades and embargoes between nations at war are suspended automatically by the engine.',
     '- Prefer 1-4 events per turn; keep each text 1-3 sentences.',
     '- Keep your internal reasoning brief (a few sentences) and go straight to the JSON result; do not over-deliberate or re-derive facts already present in the state.',
     '- Keep every stat value between 0 and 100.',
@@ -253,6 +262,9 @@ export function buildSystemPrompt(preset: Preset, withNeighboursTool = false): s
  * other consumer) can read the exact items. The framing instruction tells the
  * model to simulate the combined consequences of the whole batch (or to let the
  * world advance on its own when the batch is empty) and return one TurnResult.
+ * (v0.35.0, #58) It also carries the currently active `trades` / `embargoes`
+ * (omitted entirely when undefined, like the other optional fields) so the
+ * model can reference them — and `lift` them — in `TurnResult.economy`.
  */
 export function buildUserPrompt(
   state: GameState,
@@ -295,6 +307,20 @@ export function buildUserPrompt(
    * Omitted entirely when undefined.
    */
   relations?: Record<string, RelationStatus>,
+  /**
+   * (v0.35.0, #58) The currently active bilateral trade agreements (each a
+   * pair of nation ids). Emitted verbatim (even when empty) so the model
+   * knows which trades exist and can end one with `economy.trade` +
+   * `lift: true`. Omitted entirely when undefined.
+   */
+  trades?: TradeAgreement[],
+  /**
+   * (v0.35.0, #58) The currently active unilateral embargoes (each an
+   * `from` → `target` pair of nation ids). Emitted verbatim (even when
+   * empty) so the model knows which embargoes are in force and can lift one
+   * with `economy.embargo` + `lift: true`. Omitted entirely when undefined.
+   */
+  embargoes?: Embargo[],
 ): string {
   const player = state.nations[state.playerNationId];
   const playerName = player?.name ?? state.playerNationId;
@@ -409,6 +435,8 @@ export function buildUserPrompt(
   if (markers !== undefined) payload.markers = markers;
   if (wars !== undefined) payload.wars = wars;
   if (relations !== undefined) payload.relations = relations;
+  if (trades !== undefined) payload.trades = trades;
+  if (embargoes !== undefined) payload.embargoes = embargoes;
   return JSON.stringify(payload, null, 2);
 }
 
@@ -549,6 +577,7 @@ export function validateTurnResult(
     takeovers: [],
     wars: { declare: [], end: [] },
     hybrid: { ops: [] },
+    economy: { trade: [], embargo: [] },
     markers: { add: [], remove: [] },
   };
 
@@ -653,6 +682,12 @@ export function validateTurnResult(
   // exposed backfire.
   result.hybrid = { ops: validateHybridOps(o.hybrid) };
 
+  // (v0.35.0, #58) Trade & embargo ops: a no-`lift` op declares / imposes,
+  // `lift: true` ends / lifts. Refs stay raw here and are resolved at apply
+  // time against the real state (like wars / hybrid ops); unknown /
+  // ambiguous / self-pairing ops are dropped there, never thrown.
+  result.economy = validateEconomyOps(o.economy);
+
   // (v0.27, #44) Map-marker ops: new placements (validated here) and
   // removals by stable id. Applied by applyTurnResult after the territory
   // moves (a new marker's owner is the region's post-turn owner).
@@ -881,6 +916,52 @@ function validateHybridOpsList(raw: unknown[]): HybridOp[] {
   return out;
 }
 
+/**
+ * (v0.35.0, #58) Validate the raw `economy` object of a turn into a safe
+ * {@link EconomyOps}. Defensive like the rest of the parser — never throws.
+ * `trade`: each op needs non-empty `a` and `b` refs (a nation's id or unique
+ * name, capped at 200 chars) and a boolean `lift` (default false = declare);
+ * ops with a missing ref are dropped — ref resolution and the
+ * a≠b / from≠target checks happen at apply time against the real state
+ * (like wars / hybrid ops, whose raw refs are kept here). `embargo`: each op
+ * needs non-empty `from` and `target` refs and a boolean `lift` (default
+ * false = impose). A missing / malformed top-level object yields
+ * `{ trade: [], embargo: [] }`.
+ */
+export function validateEconomyOps(raw: unknown): EconomyOps {
+  const out: EconomyOps = { trade: [], embargo: [] };
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return out;
+  const o = raw as Record<string, unknown>;
+
+  if (Array.isArray(o.trade)) {
+    for (const e of o.trade) {
+      if (!e || typeof e !== 'object') continue;
+      const t = e as Record<string, unknown>;
+      const a = str(t.a, 200);
+      const b = str(t.b, 200);
+      if (!a || !b) continue;
+      const op: EconomyTradeOp = { a, b };
+      if (t.lift === true) op.lift = true;
+      out.trade.push(op);
+    }
+  }
+
+  if (Array.isArray(o.embargo)) {
+    for (const e of o.embargo) {
+      if (!e || typeof e !== 'object') continue;
+      const t = e as Record<string, unknown>;
+      const from = str(t.from, 200);
+      const target = str(t.target, 200);
+      if (!from || !target) continue;
+      const op: EconomyEmbargoOp = { from, target };
+      if (t.lift === true) op.lift = true;
+      out.embargo.push(op);
+    }
+  }
+
+  return out;
+}
+
 /**
  * (v0.33.0, #56) The UNORDERED pairs of belligerents of a set of ACTIVE
  * wars: a war with sides [a, b, c] contributes the pairs {a,b}, {a,c},
@@ -1165,6 +1246,128 @@ function applyHybridOp(
   else if (op.type === 'proxy') shiftRelationTowardHostile(next, from, target.nation.id, 'rival');
 }
 
+// --- Economy ops: trade + embargo (v0.35.0, #58) ------------------------------
+
+/**
+ * (v0.35.0, #58) The per-turn economic effect of the economy layer, applied
+ * EVERY committed turn (not just to this turn's declares): each active
+ * bilateral trade grants both parties a small, deterministic economy gain;
+ * each active embargo applies a small, deterministic economy dip to the
+ * target only. Clamped to 0–100. The effect lands on `stats.economy` AND on
+ * every region the nation owns (`regionStats`), mirroring the hybrid-op
+ * effect, and each affected nation's derived stats are re-derived afterwards
+ * (the same 0-region / no-entry guards as `applyHybridOp`). No-op when there
+ * are no active trades or embargoes. Never throws.
+ */
+const TRADE_ECONOMY_BONUS = 1;
+const EMBARGO_ECONOMY_PENALTY = 1;
+
+export function applyEconomyEffects(
+  next: GameState,
+  geoOf?: (key: string) => { area: number; population: number } | undefined,
+): void {
+  if (next.trades.length === 0 && next.embargoes.length === 0) return;
+
+  // nation id -> signed economy delta (trades add for both parties, embargoes
+  // subtract for the target; deltas accumulate for nations hit by several).
+  const delta = new Map<string, number>();
+  for (const t of next.trades) {
+    for (const id of [t.a, t.b]) {
+      delta.set(id, (delta.get(id) ?? 0) + TRADE_ECONOMY_BONUS);
+    }
+  }
+  for (const e of next.embargoes) {
+    delta.set(e.target, (delta.get(e.target) ?? 0) - EMBARGO_ECONOMY_PENALTY);
+  }
+
+  const affected = new Set<string>();
+  for (const [id, d] of delta) {
+    const n = next.nations[id];
+    if (!n) continue; // a nation removed this turn (a merge): the delta is dropped
+    const cur = clampStat(n.stats.economy + d);
+    if (cur === n.stats.economy) continue; // no change (already at the clamp)
+    n.stats.economy = cur;
+    for (const key of n.territory) {
+      const rs = next.regionStats[key];
+      if (rs) rs.economy = clampStat(rs.economy + d);
+    }
+    affected.add(id);
+  }
+
+  if (affected.size > 0) {
+    for (const id of affected) {
+      const n = next.nations[id];
+      if (n && n.territory.length > 0 && n.territory.some((k) => next.regionStats[k])) {
+        n.stats = deriveNationStats(n.territory, next.regionStats, geoOf);
+      }
+    }
+  }
+}
+
+/**
+ * (v0.35.0, #58) Apply the turn's economy ops to the active lists on
+ * `next`, RESOLVING the (possibly name-based) refs against the current
+ * state: a no-`lift` trade op declares the bilateral agreement (idempotent —
+ * an already-active pair is not duplicated; the pair is stored sorted, since
+ * a trade is symmetric); `lift: true` ends it (a no-op when absent). A no-
+ * `lift` embargo op imposes the unilateral embargo (idempotent — the ordered
+ * from→target pair is kept as-is); `lift: true` lifts it. An op whose refs
+ * don't resolve to distinct EXISTING nations is dropped (defensive — never
+ * throws). Mutates `next` in place.
+ */
+function applyEconomyOps(next: GameState, ops: EconomyOps): void {
+  const tradeKey = (a: string, b: string): string => (a < b ? `${a}\u0000${b}` : `${b}\u0000${a}`);
+  const embargoKey = (f: string, t: string): string => `${f}\u0000${t}`;
+
+  for (const op of ops.trade) {
+    const a = resolveNationRef(next, op.a);
+    const b = resolveNationRef(next, op.b);
+    if (!a || !b || a === b) continue; // unknown / ambiguous / self: drop
+    const key = tradeKey(a, b);
+    if (op.lift === true) {
+      next.trades = next.trades.filter((t) => tradeKey(t.a, t.b) !== key);
+    } else if (!next.trades.some((t) => tradeKey(t.a, t.b) === key)) {
+      // stored sorted (a < b): a trade is symmetric, so the agreement has a
+      // canonical shape no matter which way the LLM named the pair.
+      next.trades.push(a < b ? { a, b } : { a: b, b: a });
+    }
+  }
+
+  for (const op of ops.embargo) {
+    const from = resolveNationRef(next, op.from);
+    const target = resolveNationRef(next, op.target);
+    if (!from || !target || from === target) continue; // unknown / ambiguous / self: drop
+    const key = embargoKey(from, target);
+    if (op.lift === true) {
+      next.embargoes = next.embargoes.filter((e) => embargoKey(e.from, e.target) !== key);
+    } else if (!next.embargoes.some((e) => embargoKey(e.from, e.target) === key)) {
+      next.embargoes.push({ from, target });
+    }
+  }
+}
+
+/**
+ * (v0.35.0, #58) Auto-suspend the economy layer when war breaks out: any
+ * active trade or embargo whose two nations are on OPPOSITE sides of an
+ * active war (v0.33, #56) is removed — a war severs the economic link, so
+ * the suspended agreement stops producing its per-turn effect from now on.
+ * A trade/embargo between two non-belligerents, or between two nations on
+ * the SAME side, is untouched. Mutates `next` in place; idempotent. Must be
+ * called AFTER the war declare/end ops of the turn (so it sees the final
+ * `next.wars`). Never throws.
+ */
+function suspendEconomyOnWar(next: GameState): void {
+  if (next.trades.length === 0 && next.embargoes.length === 0) return;
+  const warring = activeWarPairs(next.wars);
+  const atWarNow = (x: string, y: string): boolean => {
+    if (x === y) return false;
+    const key = x < y ? `${x}\u0000${y}` : `${y}\u0000${x}`;
+    return warring.has(key);
+  };
+  next.trades = next.trades.filter((t) => !atWarNow(t.a, t.b));
+  next.embargoes = next.embargoes.filter((e) => !atWarNow(e.from, e.target));
+}
+
 /**
  * A turn is "meaningful" if it produced at least an event, a stat change, a
  * no-man's-land release (v0.22 #16 P3: a release is a real world change even
@@ -1190,6 +1393,10 @@ export function isMeaningful(result: TurnResult): boolean {
     // (v0.34.0, #57) a hybrid op (a successful one or an exposed backfire) is
     // a real world change (a stat dip or a soured relation).
     result.hybrid.ops.length > 0 ||
+    // (v0.35.0, #58) a trade declared/ended or an embargo imposed/lifted this
+    // turn is a real world change (the active economy lists moved).
+    result.economy.trade.length > 0 ||
+    result.economy.embargo.length > 0 ||
     // (v0.27, #44) a marker placed or removed this turn is a real world change.
     result.markers.add.length > 0 ||
     result.markers.remove.length > 0
@@ -1546,6 +1753,32 @@ export function applyTurnResult(
     applyHybridOp(next, op, geoOf, validKeys, regionNameOf, actingTurn);
   }
 
+  // --- Trade & embargo economy layer (v0.35.0, #58) ---
+  //
+  // Placed AFTER the wars block (so the auto-suspension sees the FINAL
+  // next.wars, including wars declared this turn) and before markers /
+  // nationOps (which never touch the economy lists). Order:
+  //   (1) APPLY OPS: the turn's declare/lift ops mutate the active
+  //       GameState.trades / GameState.embargoes lists (a declare is
+  //       idempotent; refs resolved against the current state, unknown /
+  //       ambiguous / self-pairing ops dropped).
+  //   (2) WAR AUTO-SUSPENSION: any active trade or embargo whose two
+  //       nations are on opposite sides of an active war is removed —
+  //       a war severs the economic link, so the suspended agreement
+  //       stops producing its per-turn effect from now on (this also
+  //       drops a trade declared this turn between two nations that just
+  //       went to war).
+  //   (3) PER-TURN EFFECT: the FULL active lists (not just this turn's
+  //       declares) each apply their deterministic effect this turn —
+  //       trade: both parties' economy up a little; embargo: the
+  //       target's economy down a little — clamped, mirrored to the
+  //       owning nations' regions, and re-derived like the hybrid dip.
+  // Additive only: declares add, lifts remove, and nothing else (not even
+  // a war) mutates the lists besides the suspension above.
+  applyEconomyOps(next, result.economy);
+  suspendEconomyOnWar(next);
+  applyEconomyEffects(next, geoOf);
+
   // --- Map markers (v0.27, #44) ---
   //
   // Markers are anchored to a region key and are processed against the FINAL
@@ -2058,6 +2291,10 @@ export async function runTurn(opts: {
     markers,
     wars,
     relations,
+    // (v0.35.0, #58) the active trade / embargo lists, so the model can
+    // reference — and `lift` — what is currently in force.
+    state.trades,
+    state.embargoes,
   );
   const nudge =
     'Your previous output was invalid. Respond with ONLY the JSON object described above for this batch — no prose, no fences.';
@@ -2113,6 +2350,7 @@ export async function runTurn(opts: {
       takeovers: [],
       wars: { declare: [], end: [] },
       hybrid: { ops: [] },
+      economy: { trade: [], embargo: [] },
       markers: { add: [], remove: [] },
     };
   }