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

shared/protocol.ts

@@ -363,6 +363,59 @@ export interface HybridOp {
   outcome?: 'success' | 'exposed';
 }
 
+// --- Trade & embargo ops (v0.35.0, #58) --------------------------------------
+
+/**
+ * (v0.35.0, #58) A bilateral TRADE op in `TurnResult.economy.trade`: `a` and
+ * `b` are the two parties (each a nation's id or unique name — resolved by
+ * the engine's `resolveNationRef`; a pair that resolves to the same nation,
+ * or contains an unknown/ambiguous ref, is dropped defensively). Without
+ * `lift` the op DECLARES the agreement (idempotent — an already-active
+ * agreement is not duplicated); `lift: true` ENDS it.
+ */
+export interface EconomyTradeOp {
+  /** First party's id or unique name. */
+  a: string;
+  /** Second party's id or unique name (distinct from `a` after resolution). */
+  b: string;
+  /** `true` → end this bilateral trade; default `false` = declare it. */
+  lift?: boolean;
+}
+
+/**
+ * (v0.35.0, #58) A unilateral EMBARGO op in `TurnResult.economy.embargo`:
+ * `from` blocks trade with `target` (each a nation's id or unique name —
+ * resolved by `resolveNationRef`; an unknown/ambiguous ref or
+ * `from === target` is dropped defensively). Without `lift` the op imposes
+ * the embargo (idempotent — an already-active one is not duplicated);
+ * `lift: true` LIFTS it.
+ */
+export interface EconomyEmbargoOp {
+  /** The imposing nation's id or unique name. */
+  from: string;
+  /** The embargoed nation's id or unique name (distinct from `from`). */
+  target: string;
+  /** `true` → lift this embargo; default `false` = impose it. */
+  lift?: boolean;
+}
+
+/**
+ * (v0.35.0, #58) The turn's trade-and-embargo operations, nested under
+ * `TurnResult.economy`. Both arrays are required and default to `[]`. The
+ * engine applies the ops to `GameState.trades` / `GameState.embargoes`
+ * (add = declare/impose, remove = lift) and, on every committed turn, applies
+ * the per-turn economic effect of the FULL active lists (trade: both
+ * parties' economy up a little; embargo: the target's economy down a
+ * little). Active trades/embargoes between nations on opposite sides of an
+ * active war (v0.33, #56) are suspended (removed) automatically.
+ */
+export interface EconomyOps {
+  /** Bilateral trades (declare or lift). */
+  trade: EconomyTradeOp[];
+  /** Unilateral embargoes (impose or lift). */
+  embargo: EconomyEmbargoOp[];
+}
+
 /** The exact JSON object the world-simulator LLM must return for a turn. */
 export interface TurnResult {
   date: string;
@@ -439,6 +492,20 @@ export interface TurnResult {
    * `{ ops: [] }`).
    */
   hybrid: { ops: HybridOp[] };
+  /**
+   * (v0.35.0, #58) Trade and embargo ops — the economy layer. `trade`
+   * declares (or, with `lift: true`, ends) bilateral trade agreements
+   * between two nations; `embargo` imposes (or, with `lift: true`, lifts)
+   * a unilateral embargo on a target. Both arrays are required and default
+   * to `[]`. Applied directly by `applyTurnResult` (add to / remove from
+   * `GameState.trades` / `GameState.embargoes`), and the per-turn economic
+   * effect of the FULL active lists is applied on every committed turn (a
+   * trade lifts both parties' economy a little; an embargo lowers the
+   * target's economy a little — clamped, deterministic). Active
+   * trades/embargoes between nations on opposite sides of an active war are
+   * suspended automatically.
+   */
+  economy: EconomyOps;
   /**
    * (v0.27, #44) Map-marker ops this turn. `add` places new named markers
    * (the engine positions each at its region's centroid + a small

shared/scenario.ts

@@ -456,6 +456,9 @@ export function worldDraftToGameState(
     // (v0.33.0, #56) No wars on a fresh (dynamic) game; any preset-level `war`
     // relation stays a bare/implicit one, not an entity (see syncWarRelations).
     wars: [],
+    // (v0.35.0, #58) No trades/embargoes on a fresh (dynamic) game.
+    trades: [],
+    embargoes: [],
   };
   return state;
 }

shared/types.ts

@@ -143,6 +143,37 @@ export interface MapMarker {
   placedTurn: number;
 }
 
+/**
+ * (v0.35.0, #58) An active BILATERAL TRADE agreement between two distinct
+ * nations. Declared by the LLM via `TurnResult.economy.trade` (a no-`lift`
+ * op) and ended by a `lift: true` op; while active it yields a small,
+ * deterministic economy gain to BOTH parties every committed turn. The
+ * engine suspends (removes) the trade automatically when the two parties end
+ * up on opposite sides of an active war (v0.33, #56).
+ */
+export interface TradeAgreement {
+  /** First party's nation id. */
+  a: string;
+  /** Second party's nation id (distinct from `a`; the pair is symmetric). */
+  b: string;
+}
+
+/**
+ * (v0.35.0, #58) An active UNILATERAL EMBARGO: `from` blocks trade with
+ * `target` (which must differ from `from`). Declared by the LLM via
+ * `TurnResult.economy.embargo` (a no-`lift` op) and lifted by a `lift: true`
+ * op; while active it applies a small, deterministic economy dip to the
+ * TARGET only, every committed turn. The engine suspends (removes) the
+ * embargo automatically when the two nations end up on opposite sides of an
+ * active war (v0.33, #56).
+ */
+export interface Embargo {
+  /** The imposing nation's id. */
+  from: string;
+  /** The embargoed nation's id (distinct from `from`). */
+  target: string;
+}
+
 /**
  * (v0.33.0, #56) A first-class **war** — a named, ongoing armed conflict
  * between two or more nations. Unlike the boolean `war` relation (which a
@@ -303,6 +334,28 @@ export interface GameState {
    * additive, no data wipe.
    */
   wars: War[];
+  /**
+   * (v0.35.0, #58) Active bilateral trade agreements (see {@link TradeAgreement}):
+   * declared/ended by a turn's `economy.trade` ops (a no-`lift` op declares,
+   * `lift: true` ends). Every committed turn the engine applies a small,
+   * deterministic economy gain to BOTH parties of each active agreement, and
+   * suspends (removes) any agreement whose two parties are on opposite sides
+   * of an active war (v0.33, #56). Always `[]` on a fresh game; rows saved
+   * before v0.35 load with this defaulted to `[]` (see server/db.ts) —
+   * additive, no data wipe.
+   */
+  trades: TradeAgreement[];
+  /**
+   * (v0.35.0, #58) Active unilateral embargoes (see {@link Embargo}):
+   * imposed/lifted by a turn's `economy.embargo` ops (a no-`lift` op imposes,
+   * `lift: true` lifts). Every committed turn the engine applies a small,
+   * deterministic economy dip to each embargo's TARGET only, and suspends
+   * (removes) any embargo whose two nations are on opposite sides of an
+   * active war (v0.33, #56). Always `[]` on a fresh game; rows saved before
+   * v0.35 load with this defaulted to `[]` (see server/db.ts) — additive,
+   * no data wipe.
+   */
+  embargoes: Embargo[];
 }
 
 /**