feat(#60): nuclear/WMD — capability flag + strikes (region → no-man's-land, nation collapse + war capitulation, MAD retaliation) (v0.37.0)

shared/protocol.ts

@@ -7,6 +7,7 @@ import type {
   EventType,
   GameState,
   IndustryProject,
+  MapMarker,
   MarkerType,
   Nation,
   NationStats,
@@ -433,6 +434,90 @@ export interface IndustryOps {
   projects: IndustryProject[];
 }
 
+/**
+ * (v0.37, #60) A single nuclear strike. `from` names the striking nation
+ * (id or name — it must be **nuclear-capable**, see `isNuclearCapable`);
+ * `target` names what is struck — either a **region key** (the region is
+ * devastated to no man's land and its former owner devastated) or a
+ * **nation** (id or name — the target's economy / military / stability are
+ * devastated; if the striker and the target are on opposite sides of an
+ * active war, that war ends in `capitulation`).
+ */
+export interface NuclearStrike {
+  /** The striking nation (id or name). Must be nuclear-capable. */
+  from: string;
+  /** The struck target: a region key, or a nation (id or name). */
+  target: string;
+}
+
+/**
+ * (v0.37, #60) The turn's NUCLEAR operations, nested under
+ * `TurnResult.nuclear`. `arm` names the nations (id or name) that declare a
+ * nuclear arsenal this turn (idempotent — arming an already-armed nation is a
+ * no-op; an unresolvable ref is dropped); `strikes` are the nuclear strikes
+ * fired this turn (at most one per turn in the prompt contract; each is
+ * validated independently — an invalid `from` or `target` is dropped, never
+ * thrown). A strike on a nuclear-capable target (or the owner of a struck
+ * region) triggers a smaller "MAD" retaliation on the striker. Required;
+ * default `{ arm: [], strikes: [] }`.
+ */
+export interface NuclearOps {
+  /** Nation refs (id or name) arming a nuclear arsenal this turn. */
+  arm: string[];
+  /** The nuclear strikes fired this turn. */
+  strikes: NuclearStrike[];
+}
+
+// --- Nuclear / WMD effect math (v0.37, #60) ----------------------------------
+//
+// A nuclear strike is a DETERMINISTIC, devastating stat collapse — there is no
+// hidden randomness (the LLM decides WHO strikes and WHAT is targeted; the
+// engine decides the size of the effect). The two magnitude tables below are
+// the single source of truth for the collapse: a full strike devastates a
+// nation (or the former owner of a devastated region) by `NUCLEAR_COLLAPSE`,
+// while a "MAD" retaliation (fired when a nuclear-capable nation is struck)
+// devastates the STRIKER by half that, `NUCLEAR_RETALIATION`. Both dip the
+// three war-relevant stats only (population is untouched); each value is the
+// signed per-turn delta the engine clamps against 0–100.
+
+/** The stats a nuclear strike collapses (population is never touched). */
+export type NuclearStatKey = 'economy' | 'military' | 'stability';
+
+/**
+ * (v0.37, #60) The deterministic stat collapse a FULL nuclear strike inflicts
+ * on its target (a struck nation, or the former owner of a devastated region):
+ * a heavy dip in economy / military / stability. Shared so the engine and the
+ * unit tests agree on the exact magnitudes.
+ */
+export const NUCLEAR_COLLAPSE: Record<NuclearStatKey, number> = {
+  economy: -40,
+  military: -50,
+  stability: -40,
+};
+
+/**
+ * (v0.37, #60) The deterministic stat collapse of a "MAD" RETALIATION — fired
+ * automatically when a nuclear-capable nation (or the owner of a devastated
+ * region) is struck — which hits the STRIKER at half the full collapse.
+ */
+export const NUCLEAR_RETALIATION: Record<NuclearStatKey, number> = {
+  economy: NUCLEAR_COLLAPSE.economy / 2,
+  military: NUCLEAR_COLLAPSE.military / 2,
+  stability: NUCLEAR_COLLAPSE.stability / 2,
+};
+
+/**
+ * (v0.37, #60) Whether a nation is **nuclear-capable** — i.e. able to fire a
+ * nuclear strike and subject to MAD retaliation: its `nuclear` flag is set, OR
+ * it owns a `rocket` marker (a launch site is an arsenal). A legacy nation
+ * without the flag is not nuclear unless it has a rocket marker. Pure +
+ * shared (used by the engine and the unit tests).
+ */
+export function isNuclearCapable(nation: Nation, markers: readonly MapMarker[]): boolean {
+  if (nation.nuclear === true) return true;
+  return markers.some((m) => m.ownerNationId === nation.id && m.type === 'rocket');
+}
+
 /** The exact JSON object the world-simulator LLM must return for a turn. */
 export interface TurnResult {
   date: string;
@@ -537,6 +622,21 @@ export interface TurnResult {
    * untouched. Required; default `{ projects: [] }`.
    */
   industry: IndustryOps;
+  /**
+   * (v0.37, #60) Nuclear / WMD ops — the LLM's nuclear lever. `arm` names
+   * the nations that declare a nuclear arsenal this turn (idempotent);
+   * `strikes` are the nuclear strikes fired this turn (at most one per turn
+   * in the prompt contract). A strike may target a **region** (devastated to
+   * no man's land, its former owner devastated) or a **nation** (its economy
+   * / military / stability devastated; a strike that lands on a nation
+   * warring with the striker ends that war in capitulation). A strike on a
+   * nuclear-capable target (or the owner of a struck region) triggers a
+   * smaller, automatic "MAD" retaliation on the striker. Only
+   * nuclear-capable nations (the `Nation.nuclear` flag set, or owning a
+   * `rocket` marker) may strike. Applied directly by `applyTurnResult`,
+   * never queued. Required; default `{ arm: [], strikes: [] }`.
+   */
+  nuclear: NuclearOps;
   /**
    * (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/types.ts

@@ -72,6 +72,14 @@ export interface Nation {
   stats: NationStats;
   territory: string[];
   relations: Record<string, RelationStatus>;
+  /**
+   * Whether the nation controls nuclear weapons (v0.37, #60). Optional — a
+   * legacy game loaded from SQLite has no flag, which means "not nuclear".
+   * A nation is *nuclear-capable* (for the `nuclear` lever and MAD
+   * retaliation) when this is `true` OR it owns a `rocket` marker (see
+   * `isNuclearCapable` in `protocol.ts`).
+   */
+  nuclear?: boolean;
 }
 
 /** Categories a narrative event can take. */