feat: #66 contested regions / frontlines — 12th ability (v0.44.0)

A third region state (contested frontline): a region in no nation's territory and not in unowned, opened/resolved by the LLM, tied to an active war. Sole-ownership invariant preserved. Durable GameState.contested; contested-inert stub; map legend stays at 7.

AGENTS.md

@@ -56,7 +56,7 @@ history/
 ├── eslint.config.js        # flat config (ESLint 9)
 ├── tsconfig.json           # strict; aliases @/ → src/, @shared/ → shared/
 ├── vite.config.ts          # dev server + proxy /api,/sse → :4321; @ / @shared aliases
-├── vitest.config.ts        # unit tests (server/**/*.test.ts + scripts/**/*.test.ts; 225 tests)
+├── vitest.config.ts        # unit tests (server/**/*.test.ts + scripts/**/*.test.ts; 407 tests)
 ├── playwright.config.ts    # deterministic e2e (webServer runs npm run dev, LLM_STUB=1)
 ├── index.html
 ├── presets/                # 5 scenario JSON files + index.json (manifest)
@@ -67,11 +67,13 @@ history/
 │   ├── region-adjacency.json # region key -> bordering region keys, 1,800 entries (the getNeighbours data, #16 P2)
 │   ├── region-centroids.json # region key -> {lat,lon,spread} anchor for map markers, 1,800 entries (#44)
 │   ├── region-geo.json     # region key -> {area (km²), population}, 1,800 entries (the area×population weighting for per-region stats, #46)
+│   ├── region-resources.json # region key -> synthesized {oil, iron, food, industry} (each 0–1, 2dp), 1,800 entries (the resource profiles that scale industry boosts + feed the prompt aggregate, #59)
 │   └── ne-admin0-pop.json  # ISO_A3 -> admin-0 POP_EST, 249 codes (the committed population SOURCE for region-geo.json — a small derived table, the 13 MB Natural Earth source is NOT committed, #46)
 ├── scripts/                # the geo/manifest data pipeline — .mjs (turf allowed HERE only;
 │   │                       #   never imported by .ts): generate → coarsen → cleanup → smooth →
 │   │                       #   fill-gaps → split-arkhangel → split-arkhangel-band → build-region-keys
 │   │                       #   → build-region-adjacency → build-region-centroids → build-region-geo
+│   │                       #   → build-region-resources
 │   │                       #   (build-region-geo reads the COMMITTED ne-admin0-pop.json; that small
 │   │                       #   table is distilled once from the 13 MB Natural Earth admin-0 source by
 │   │                       #   extract-admin0-pop.mjs — the raw source is never committed, #46)
@@ -94,6 +96,16 @@ history/
 │   ├── map.ts              # GameState → RegionMap (region key → owner + stable color)
 │   ├── presets.ts          # load preset JSON files from disk
 │   ├── db.ts               # SQLite open/save/load (+ legacy regionStats migration on load, v0.28 #46)
+│   ├── abilities/          # the modular LLM-ability system (v0.40.0 #67) — one file per world lever
+│   │   ├── index.ts        #   the ABILITIES registry (list order = apply order) + the re-export surface
+│   │   ├── types.ts        #   the Ability contract + the AbilityField union
+│   │   ├── shared.ts       #   shared helpers (stat dips / re-derive / ref resolution, …)
+│   │   ├── apply-helpers.ts  #   shared apply-path helpers
+│   │   ├── <name>.ts       #   one module per ability: wars / takeovers / leaders / nuclear /
+│   │   │                   #     ideology / industry / economy / hybrid / disasters (v0.41.0 #63) /
+│   │   │                   #     migration (v0.42.0 #64)
+│   │   ├── *.test.ts       #   per-ability unit tests (registry.test.ts pins the 12-ability contract)
+│   │   └── goldens/        #   pinned prompt goldens (system-no-tool / system-tool / user)
 │   └── *.test.ts           # unit tests (vitest)
 └── src/
     ├── App.tsx             # screen router (home → pick → game) + manual hash router (#/game/<id>); owns game/regions/advisors/busy
@@ -131,6 +143,7 @@ history/
 | `npm run split:regions:band` | (re)apply the #41 Arctic-coast-band split (`RU-ARK` mainland's 28-part lat ≥ 68 band → `RU-PEO` + `RU-YAM`) — idempotent no-op once applied |
 | `npm run build:region-keys` / `build:region-adjacency` / `build:region-centroids` | (re)generate the `public/region-keys.json` / `region-adjacency.json` / `region-centroids.json` manifests — deterministic + idempotent (byte-identical re-run) |
 | `npm run build:region-geo` | (re)generate `public/region-geo.json` (region key → area km² + population) from `regions.geo.json` + `region-keys.json` + the committed `ne-admin0-pop.json` — deterministic + idempotent (byte-identical re-run; #46) |
+| `npm run build:region-resources` | (re)generate `public/region-resources.json` (region key → synthesized `{ oil, iron, food, industry }` 0–1 profile) from `region-keys.json` + `region-geo.json` (area factor) — deterministic + idempotent (byte-identical re-run; #59) |
 | `npm run extract:admin0-pop` | one-time distillation of the 13 MB Natural Earth admin-0 source → the committed `public/ne-admin0-pop.json` (ISO_A3 → `POP_EST`, 249 codes); the raw source is never committed (#46) |
 | `docker compose up -d --build` | prod image on :4321, routed via Traefik at `history.dev.kkhost.pl` |
 
@@ -327,6 +340,295 @@ history/
   `server/protocol.test.ts`, `server/db.test.ts`, `server/regions.test.ts`,
   `scripts/region-geo.test.ts`). **PR 1 of 2 — deliberately NOT deployed** (the user deploys
   when PR 2, the per-region LLM lever, ships).
+- **Wars — `GameState.wars`, a first-class conflict entity (v0.33, #56).**
+  Since v0.33 the `war` relation is no longer a bare boolean flag but a named `War` entity in
+  `GameState.wars` (required, `[]` at creation; a legacy SQLite row without the field loads as
+  `[]` — additive, never wipes). Each `War` has a stable id (`w1`, `w2`, …), a `sides` list
+  (≥2 distinct nation ids — any two distinct members are at war with each other), `declaredTurn`,
+  `declaredDate`, optional `aims`, a `status` (`active` / `armistice` / `capitulation`), and an
+  optional `front` (region keys). `TurnResult.wars = { declare: WarDeclareOp[]; end: WarEndOp[] }`
+  (both required, default `[]`): a **declare** creates a new active `War` (sides resolved via
+  `resolveNationRef` — id first, then case-insensitive unique name; a declare with <2 resolved
+  distinct sides is dropped); an **end** finds a war by id (unknown → no-op, never throw) and sets
+  its `status` to the outcome (`armistice` or `capitulation`). After declare/end,
+  `syncWarRelations(prev, next)` enforces the derived `war` relation: any two nations on opposite
+  sides of ≥1 **active** war get `war` in both directions (overriding lesser statuses — you
+  cannot "make peace" without ending the war); when a war ends, the pairs it caused that are not
+  covered by another active war fall back to `hostile`. A **bare** `war` relation with no matching
+  active war (legacy/back-compat) is never downgraded and never force-created. **Mutual-defense
+  drag-in**: when a war is declared, each belligerent's `ally`-relation partners are added to the
+  war's `sides` (one level, no cascade; deterministic — sides in declared order, allies in sorted
+  id order). The system prompt documents the field + declare/end ops (at most 1–2 declarations
+  per turn, each narrated in `events`); `buildUserPrompt` carries the current **active** wars
+  (as `WarInfo[]`: id + sides + aims) so the model can `end` by id. The **stub never declares or
+  ends** a war (`wars: { declare: [], end: [] }`) — e2e (CI, `LLM_STUB=1`) is unaffected and the
+  path is unit-tested only (`server/engine.test.ts`).
+- **Hybrid war — `TurnResult.hybrid`, a deterministic non-kinetic operations spectrum (v0.34, #57).**
+  `TurnResult.hybrid = { ops: HybridOp[] }` (required; default `{ ops: [] }`) adds a covert /
+  hybrid-warfare spectrum alongside the kinetic `regionChanges` lever: `HybridOp =
+  { type, from, target, detail?, outcome? }` with `type ∈ spy | sabotage | assassinate |
+  cyber | economic | information | proxy` and `outcome ∈ success | exposed` (the LLM
+  declares its *intended* outcome; the engine applies the deterministic effect).
+  `from`/`target` are refs resolved by the shared `resolveNationRef` (id first, then
+  case-insensitive unique name); a `target` that is not a resolvable nation is treated
+  as a region key — it hits that region's SOLE owner (a key with 0 or 2+ owners — or the
+  acting nation itself — is dropped, never thrown). Per type: `sabotage` dips `economy`
+  (−3), `economic` dips `economy` (−5), `cyber` dips `military` (−3), `assassinate` dips
+  `stability` (−5); `information` nudges the from↔target relation one step apart (capped
+  at `hostile`), `proxy` likewise but capped at `rival`; `spy` is informational only.
+  A region-target dip lands on the single `regionStats[regionKey]` entry (hybrid ops
+  never move territory — `regionChanges` is the only lever that does); a nation-target
+  dip lands on every region the nation owns; afterwards the target's derived `stats` is
+  re-derived (0-region / no-entry guards), so the effect persists and the sole-ownership
+  invariant is untouched. **Exposed** (`outcome: "exposed"`) is a backfire: the intended
+  effect is NOT applied; instead the from↔target relation moves one step *toward*
+  `hostile` (capped; `war` is never created or escalated by an exposed op) and a
+  diplomatic/failed event is auto-appended to the turn's `events`.
+  **Additive only — no `GameState.hybrid` field, no `db.ts` change** (the ops are
+  consumed inside `applyTurnResult` after territory + wars and before markers).
+  `isMeaningful` counts hybrid ops; the system prompt documents the field + per-type
+  effects (the "unclear" fallback and the stub both return `hybrid: { ops: [] }`), and the
+  user payload carries the player's `relations` map so the model can reason about the
+  relation caps. The **stub never** proposes a hybrid op, so e2e (CI, `LLM_STUB=1`) is
+  unaffected and the path is unit-tested only (`server/engine.test.ts`).
+- **Trade & embargo economy layer — `GameState.trades` / `GameState.embargoes`, `TurnResult.economy` (v0.35, #58).**
+  `TurnResult.economy = { trade: EconomyTradeOp[]; embargo: EconomyEmbargoOp[] }` (required;
+  default `{ trade: [], embargo: [] }`) is the model's lever for the economic layer: a
+  bilateral **trade** (`{ a, b, lift? }` — symmetric, stored **sorted** `a < b`) and a
+  unilateral **embargo** (`{ from, target, lift? }` — ordered). No `lift` declares/imposes,
+  `lift: true` ends/lifts (a no-op when absent). Refs are resolved at apply time by the
+  shared `resolveNationRef` (id first, then case-insensitive unique name); an unknown /
+  ambiguous / self-pairing op is dropped (never thrown). The lists live in `GameState`
+  (`trades`/`embargoes`, required, `[]` at creation; a legacy SQLite row without them loads
+  as `[]` — additive, never wiped, like `wars`/`markers`). **Deterministic, no hidden
+  randomness.** Every committed turn, in `applyTurnResult` (after hybrid, before markers):
+  (1) `applyEconomyOps` applies this turn's declares/lifts to the active lists (idempotent
+  declares — an already-active pair/ordered pair is not duplicated); (2)
+  `suspendEconomyOnWar` **auto-suspends** any trade or embargo whose two nations are on
+  opposite sides of an **active** `War` (#56) — a war severs the economic link, so the
+  suspended pair stops producing its effect (this also drops a trade declared this turn
+  between two nations that just went to war); (3) `applyEconomyEffects` applies the per-turn
+  effect to the **full** active lists: each active trade gives **both** parties a small,
+  deterministic `economy` gain (`TRADE_ECONOMY_BONUS`), each active embargo dips the
+  **target's** `economy` only (`EMBARGO_ECONOMY_PENALTY`) — clamped to 0–100, mirrored to
+  every region the nation owns (`regionStats`), and each affected nation's derived `stats`
+  re-derived afterwards (same 0-region / no-entry guards as the hybrid dip). Sole ownership
+  is untouched (the layer moves stats, never territory). `isMeaningful` counts non-empty
+  `economy.trade` / `economy.embargo`; the system prompt documents the field + constraints
+  (at most 1–2 ops per turn, narrated in `events`; warring pairs auto-suspended), and the
+  user payload carries the active `trades`/`embargoes` so the model can `lift` them. The
+  **stub never** declares or lifts a trade/embargo (`economy: { trade: [], embargo: [] }`),
+  so e2e (CI, `LLM_STUB=1`) is unaffected and the path is unit-tested only
+  (`server/engine.test.ts`).
+- **Resources & Industry — per-region resource profiles + the `industry` lever (v0.36, #59).**
+  Since v0.36 each of the 1,800 sub-regions carries a **synthesized 4-value resource profile**
+  (`{ oil, iron, food, industry }`, each 0–1, 2dp) from the committed `public/region-resources.json`
+  — built by the deterministic, idempotent `scripts/build-region-resources.mjs` (an FNV-1a hash of
+  `` `${key}\u0000${resource}` `` scaled by an area factor from `region-geo.json`, clamped to 1,
+  byte-identical re-run) and loaded by `server/regions.ts` via the same optional-manifest pattern as
+  the other manifests (`hasResources()` / `resourceOf()`, probe `public/` then `dist/`; a missing or
+  malformed file degrades — boosts use the unscaled base value and the aggregate is omitted from the
+  prompt, never a crash). `TurnResult.industry = { projects: IndustryProject[] }` (required, default
+  `{ projects: [] }`; `IndustryProject = { regionKey, type }`, `type ∈ INDUSTRY_TYPES =
+  oil | iron | food | industry`) declares a project on a region. `applyTurnResult` maintains
+  `GameState.industry` (required, `[]` at creation; a legacy SQLite row without the field loads as
+  `[]` — `db.ts`, additive, never wiped) as a **per-region SET**: a region key not in the valid-keys
+  manifest is dropped; a region that already hosts a project is untouched (the first declared type
+  wins — re-declaring is a no-op, the type is never replaced). Every committed turn,
+  `applyIndustryEffects` (placed after the economy block, before markers; the owner is resolved from
+  the FINAL post-claim ownership) grants each active project's region's **SOLE owner** a small,
+  deterministic economy boost — `INDUSTRY_ECONOMY_BONUS = 1` plus one extra point when the region's
+  `industry` resource value is ≥ 0.5 (without the manifest, just the base) — clamped to 0–100,
+  mirrored to every region the owner holds (`regionStats`), and each affected nation's derived `stats`
+  re-derived afterwards (same 0-region / no-entry guards as the economy/hybrid dips). A project on a
+  region with 0 or 2+ owners yields no boost but is **kept** in the list (never removed, never
+  thrown); sole ownership is untouched (the layer moves stats, never territory). `isMeaningful`
+  counts non-empty `industry.projects`; the system prompt documents the field + constraints (a region
+  holds at most one project — never re-declare on a region that already has one; at most 1–2 per
+  turn, each narrated in `events`), and the user payload carries the active projects (`industry`)
+  plus each nation's aggregate resource profile (`resources` — `deriveNationResources` in
+  `shared/protocol.ts`, the area×population-weighted **average** of the owned regions' profiles;
+  omitted entirely when the manifest is not loaded). The **stub never** declares a project
+  (`industry: { projects: [] }`) — e2e (CI, `LLM_STUB=1`) is unaffected and the path is unit-tested
+  only (`server/engine.test.ts`, `server/protocol.test.ts`, `server/regions.test.ts`,
+  `server/db.test.ts`, `scripts/build-region-resources.test.ts`).
+- **Modular LLM abilities — how to add a new one (v0.40.0, #67).**
+  Since v0.40.0 the per-feature LLM levers are a modular registry in `server/abilities/`: one
+  file per ability plus `types.ts` (the `Ability<K>` interface, the closed `AbilityField` union,
+  and the `AbilityCtx` / `UserPromptCtx` shapes), `shared.ts` (the dependency-free `str` /
+  `resolveNationRef` / `resolveRegionKey` / fresh-id primitives the abilities share), and
+  `index.ts` (the ordered `ABILITIES` array — its position is the canonical apply / prompt /
+  payload order). Each ability is a plain object implementing `Ability<K>`: `field` (its
+  `TurnResult` field name), `default()` (a FRESH no-op value), `validate(raw)` (defensive parse
+  into the field's exact shape — never throws), `apply(state, data, ctx)` (mutate the world in
+  place — never throws), `schemaLine()` (its system-prompt JSON line), `constraint()` (its HARD
+  CONSTRAINTS bullet), `isMeaningful(data)` (does a non-default value make the turn meaningful?),
+  `stateFields?` (the `GameState` fields it owns, for the `db.ts` legacy-row migration —
+  `undefined` for turn-transient abilities), `stub()` (the deterministic stub's value — every
+  ability returns `default()`, so e2e is never affected), and `payload(ctx)` (the user-payload
+  keys it contributes — `{}` for turn-transient ones). The engine consumes the registry
+  generically and is never edited to add an ability: `buildSystemPrompt` emits each
+  `schemaLine()` / `constraint()` in `ABILITIES` order (between the `nationOps` block/line and the
+  `markers` line / "- Prefer 1-4 events" bullet), `buildUserPrompt` merges each `payload()` at its
+  historical position, `validateTurnResult` fills each field via `a.validate()`, `isMeaningful`
+  ORs the per-ability predicates, `applyTurnResult` runs `a.apply` in `ABILITIES` order (after the
+  core effects, before markers), the stub fills each field via `a.stub()`, and the "unclear"
+  fallback uses `a.default()`. To add a new ability: (1) add the field's type to `TurnResult` in
+  `shared/protocol.ts` (a required field with a default) and the field name to the `AbilityField`
+  union in `types.ts`; (2) create `server/abilities/<name>.ts` exporting an `Ability<'<name'>`
+  const; (3) import it in `index.ts` and APPEND it to `ABILITIES` (append last — never reorder
+  existing entries; their order is pinned by the goldens and the stub's byte-identical output);
+  (4) re-export any new public names from `index.ts` and from `engine.ts`; (5) if it owns a durable
+  `GameState` field, add it to `shared/types.ts` + the `db.ts` legacy-row migration (additive,
+  never wiped) and declare it in `stateFields`; if it contributes to the user payload, return its
+  keys from `payload()` and extend `UserPromptCtx`; (6) write `server/abilities/<name>.test.ts`
+  (the stub never exercises a new ability, so its apply path is unit-tested only) and — if it
+  changes the system prompt — regenerate the goldens
+  (`REGEN_GOLDENS=1 npx vitest run server/abilities/registry.test.ts`); `user.txt` must stay
+  byte-identical unless the new ability contributes user-payload keys.
+- **Disasters & pandemics — natural / man-made catastrophes with a deterministic dip (v0.41.0, #63).**
+  `TurnResult.disasters = DisastersOps = { events: DisasterEvent[] }` (required, default
+  `{ events: [] }`); `DisasterEvent = { type, target, severity, detail? }` with `type ∈
+  DISASTER_TYPES = earthquake | flood | volcanic | wildfire | famine | plague | epidemic` and
+  `severity ∈ DISASTER_SEVERITIES = minor | moderate | severe`. Like the hybrid layer this is
+  **turn-transient**: it owns NO `GameState` field (no durable list, no `db.ts` change) — a
+  plague or epidemic that persists is simply re-declared each turn it continues. The DETERMINISTIC
+  `DISASTER_EFFECTS` table (`server/abilities/disasters.ts`) maps each `(type, severity)` to a
+  small set of signed stat deltas (a severe plague is the hardest hit; none of them touch
+  `population`, and none move borders — sole ownership is untouched). The `target` resolves like a
+  hybrid op — a nation ref via the shared `resolveNationRef` (id first, then a case-insensitive
+  unique name), else a region key that hits that region's SOLE owner (a key with 0 or 2+ owners, or
+  one absent from the valid-keys manifest, is dropped); there is no `from`/actor field — a
+  catastrophe is not an attack — so (unlike hybrid) a self-target drop does NOT apply.
+  `applyDisasterEvent` (run in the `ABILITIES` loop after territory / wars / economy, before
+  markers) dips the target nation's `stats` (clamped 0–100), mirrors the dip to its regions (the
+  single named region for a region target, else every region it owns — entries with no
+  `regionStats` are skipped), and re-derives the nation's aggregate stats (the same 0-region /
+  no-entry guards, so a 0-region nation keeps its directly-mutated value and the dip persists).
+  `payload()` is `{}` (turn-transient), so the user-prompt golden (`user.txt`) is unchanged; the
+  system prompt gains the field's schema line + constraint bullet (the system goldens were
+  re-baselined in v0.41.0). `isMeaningful` is `events.length > 0`. The stub never proposes a
+  disaster (`{ events: [] }`), so e2e (CI, `LLM_STUB=1`) is unaffected and the path is unit-tested
+  only (`server/abilities/disasters.test.ts`).
+- **Migration & refugees — population flows between nations with a deterministic dip (v0.42.0, #64).**
+  `TurnResult.migration = MigrationOps = { ops: MigrationOp[] }` (required, default
+  `{ ops: [] }`); `MigrationOp = { kind, from, to?, scale, detail? }` with `kind ∈
+  MIGRATION_KINDS = migration | refugees | diaspora | exodus` and `scale ∈
+  MIGRATION_SCALES = small | moderate | large` (`to` is required for every kind except
+  `exodus`, which has no destination). Like the hybrid / disasters layers this is
+  **turn-transient**: it owns NO `GameState` field (no durable list, no `db.ts` change) — a
+  flow that persists is simply re-declared each turn it continues. The DETERMINISTIC
+  `MIGRATION_SOURCE_EFFECTS` / `MIGRATION_DESTINATION_EFFECTS` tables
+  (`server/abilities/migration.ts`) map each `scale` to signed stat deltas (no hidden
+  randomness): the source LOSES population + economy (small −1/−1, moderate −2/−2,
+  large −4/−3) and the destination GAINS population + economy (small +1/+1, moderate
+  +2/+2, large +3/+3); a `large` influx additionally strains the destination's stability by
+  `LARGE_INFLUX_STABILITY_DIP = -2`. Neither side ever moves territory (sole ownership is
+  untouched) and none touch borders. Both `from` and `to` resolve by the shared
+  `resolveNationRef` (id first, then a case-insensitive unique name): an unknown / ambiguous
+  source, a missing / unknown / ambiguous destination, or a **self-flow** (`from` and `to`
+  the same nation) drops the WHOLE op (the source is untouched); `exodus` skips the
+  destination entirely. The from↔to relation then moves one step toward the positive end of
+  the ally/neutral/rival/hostile ladder via the self-contained `shiftRelationTowardPositive`
+  (the mirror of the hybrid layer's `shiftRelationTowardHostile`): capped at `ally` for
+  `refugees` (hosting refugees builds the strongest goodwill), `neutral` for `migration` /
+  `diaspora`, and not at all for `exodus`; a missing relation starts at `neutral` and a
+  `war` relation is NEVER touched (the nudge neither fabricates nor escalates a war).
+  `applyMigrationOp` (run in the `ABILITIES` loop after territory / wars / economy, before
+  markers) applies the source dip, then the destination dip (+ stability strain for `large`),
+  clamps both to 0–100, mirrors each to every region the nation owns (`regionStats`), and
+  re-derives each nation's aggregate `stats` (the same 0-region / no-entry guards, so a
+  0-region nation keeps its directly-mutated value and the effect persists). `payload()` is
+  `{}` (turn-transient), so the user-prompt golden (`user.txt`) is unchanged; the system
+  prompt gains the field's schema line + constraint bullet (the system goldens were
+  re-baselined in v0.42.0). `isMeaningful` is `ops.length > 0`. The stub never proposes a
+  migration (`{ ops: [] }`), so e2e (CI, `LLM_STUB=1`) is unaffected and the path is
+  unit-tested only (`server/abilities/migration.test.ts`). **Design note:** the Gitea #64
+  body sketched a simpler `flows: {type: 'refugees'|'settlers'}` shape with a settler
+  re-claim of no-man's-land; the implemented, approved design is this richer four-kind
+  nation-to-nation **stat** layer that deliberately never moves territory (a no-man's-land
+  re-claim stays the `regionChanges` lever's job).
+- **Sea control — sole control of a fixed set of 12 named sea zones with a deterministic per-turn bonus (v0.43.0, #65).**
+  `TurnResult.sea = SeaOps = { control: SeaControlOp[] }` (required, default `{ control: [] }`);
+  `SeaControlOp = { zone, by }` where `zone` is one of the 12 fixed sea-zone ids from
+  `SEA_ZONES` in `shared/protocol.ts` (`north-atlantic`, `south-atlantic`, `pacific`, `indian`,
+  `mediterranean`, `north-sea`, `baltic`, `arctic`, `black-sea`, `gulf-mexico`, `red-sea`,
+  `sargasso`) and `by` is a nation ref (id first, then a case-insensitive unique name, via the
+  shared `resolveNationRef`; unknown / ambiguous → dropped, never thrown). Like the wars and
+  industry layers this is **durable** (unlike the turn-transient hybrid / disasters / migration
+  layers): it owns the `GameState.seaZones` field (required, `[]` at creation; a legacy SQLite
+  row without the field loads as `[]` — via the generic `ABILITIES` `stateFields` loop in
+  `db.ts`, no `db.ts` code change needed). `applySeaControl` (run in the `ABILITIES` loop after
+  territory / wars / economy, before markers) upserts the turn's ops into `next.seaZones`:
+  per zone (in first-appearance order) a single surviving op sets or replaces the zone's
+  controller (replace in place — preserving position — or append); two or more surviving ops
+  on the same zone for different resolved nations make the zone **contested** — the higher
+  current `stats.military` wins (a tie goes to the earlier-listed op) — deterministic, no
+  hidden randomness. The layer **never touches `territory` / `unowned`** — it is fully parallel
+  to but independent of land. Every committed turn (including a turn with an empty `control`),
+  `applySeaZoneBonuses` grants each existing claim's controller `SEA_ZONE_BONUS = 1` military
+  + 1 economy (clamped to 0–100, mirrored to every region the nation owns, then the nation's
+  derived `stats` re-derived with the same 0-region / no-entry guards as the economy / migration
+  layers, so a 0-region nation keeps its directly-mutated value); a nation controlling several
+  zones stacks the bonus; a claim whose nation no longer exists (removed by a merge / split
+  this turn) is skipped — the claim is kept, never thrown. `isMeaningful` is
+  `control.length > 0`. The system prompt documents the field + constraints (at most 1–2 claims
+  per turn, each narrated in `events`); the user payload **always** carries the current
+  `seaZones` list (even when empty) — `payload()` → `{ seaZones: ctx.seaZones ?? [] }` — the
+  one ability whose `payload()` is not `{}` (the durable list, unlike the turn-transient
+  layers). The **stub never** proposes a sea op (`{ control: [] }`), so e2e (CI, `LLM_STUB=1`)
+  is unaffected and the path is unit-tested only (`server/abilities/sea.test.ts`).
+  **Design note:** the Gitea #65 body sketched a `naval` layer with a free-form `zones`
+  array; the implemented, approved design is this richer `sea` layer with a **fixed set of
+  12 named zones**, sole-control semantics, contest-by-higher-military, and a durable
+  `seaZones` list — a cleaner, more deterministic model that the LLM can reason about without
+  inventing zone names each turn.
+- **Contested regions / frontlines — a `TurnResult.contested` lever opening/resolving war frontlines: a THIRD region state in no nation's `territory` and not in `unowned` (v0.44.0, #66).**
+  `TurnResult.contested = ContestedOps = { open: ContestOp[]; resolve: string[] }` (required,
+  default `{ open: [], resolve: [] }`); `ContestOp = { regionKey, parties }` where `regionKey` is
+  a region key or resolvable name and `parties` are TWO OR MORE nation refs (ids or names, via
+  the shared `resolveNationRef`). Like the `sea` / `industry` layers this is **durable**: it owns
+  the `GameState.contested: ContestedRegion[]` field (`ContestedRegion = { regionKey, parties }`
+  — `parties` store the RESOLVED nation ids; required, `[]` at creation; a legacy SQLite row
+  without the field loads as `[]` — via the generic `ABILITIES` `stateFields` loop in `db.ts`,
+  no `db.ts` code change needed). `applyContested` (run LAST in the `ABILITIES` loop, after
+  territory / wars / economy / sea — it sees the final post-claim ownership) runs **RESOLVE
+  first, then OPEN**: a `resolve` removes a currently-contested key and **releases it to no
+  man's land** (into `unowned`, out of any territory, `regionStats` deleted) — UNLESS a
+  concurrent winning claim by one of the contesting **parties** already re-owned it this turn
+  (the only claim the territory step permits on a contested key), in which case it stays owned
+  and keeps (or re-inits) its `regionStats`; an `open` makes a region a frontline only when it
+  is **contestable** — a **sole owner** at war (a shared **active** `War`) with at least one
+  party, or a **no-man's-land** region (0 owners AND in `unowned`) whose two parties are at war
+  with each other — a 2+-owner key or an owner not at war with any party is **dropped**
+  (an armistice/ended war does not count); on a successful open the key is **stripped from its
+  owner's `territory` (or from `unowned`)**, its `regionStats` entry deleted, and a
+  `{ regionKey, parties }` entry added to `next.contested` (**unique by `regionKey`** — a
+  re-open replaces a kept entry), with the stripped owner's derived stats re-derived (same
+  0-region / no-entry guards). The **sacrosanct sole-ownership invariant is never broken**: a
+  contested key is in **no** territory (never two) and is **never** in `unowned` while
+  contested (the two states are mutually exclusive). The **territory step in `engine.ts` is
+  guarded**: a normal `gain` on a currently-contested key is **dropped** unless this same turn
+  resolves the contest AND the gainer is one of the contesting parties (a party re-claim) — a
+  still-contested key is never a valid normal-claim target. The **map (client-only, like
+  no-man's-land)**: `WorldMap` renders a contested key in the distinct visible
+  `CONTESTED_FILL` / `CONTESTED_STROKE` (orange "hot" frontline) with a `"Contested: A vs B"`
+  hover sub-line (names from `GameState.contested`; a removed party degrades to a dash) — the
+  contested check runs **first** (before unowned / owned); the server `RegionMap` stays
+  owned-vs-absent (it never knows about contested). **The map legend stays at 7 items** (it is
+  derived from the `RegionMap` owners only — a contested key is absent from the `RegionMap`, so
+  no new legend entry; e2e legend assertions are unaffected). `isMeaningful` is
+  `open.length > 0 || resolve.length > 0`; the system prompt documents the field + constraints
+  (at most 1–2 contested-region changes per turn, each narrated in `events`); the user payload
+  carries the current frontlines (region key + party **names**) **only when non-empty** —
+  `payload()` → `{}` on a fresh / no-frontline world (unlike `sea`, which always emits). The
+  **stub never** opens or resolves a frontline (`{ open: [], resolve: [] }`), so e2e (CI,
+  `LLM_STUB=1`) is unaffected and the path is unit-tested only
+  (`server/abilities/contested.test.ts`, 52 tests, each asserting the sole-ownership invariants).
+  **Design note (deviation from the issue body):** the Gitea #66 body sketched a **two-owner**
+  `disputed` / `fronts` design that "relaxes sole-ownership"; the implemented, approved design
+  is this **third region state** (a contested key in NO territory, sole-ownership preserved)
+  with `open` / `resolve` ops and a minimum of two contesting parties.
 - **Map click → dossier target (owner resolved from the RegionMap, by region key).**
   Clicking a sub-region does NOT open a popup — it switches the dossier to that sub-region's
   owning nation (`focusNation(ownerId, {name})` in `App.tsx`, which also records which region was

CHANGELOG.md

@@ -2,6 +2,211 @@
 
 All notable changes to **History** are listed here, newest first.
 
+## v0.44.0 — 2026-10-16 15:10
+- **#66: Contested regions / frontlines — a `TurnResult.contested` lever letting the LLM declare a region a **contested** war frontline (a **third region state**: in **no** nation's `territory` and **not** in `unowned` / no-man's-land) and resolve existing frontlines.** It lands as the **12th ability** of the v0.40.0 modular system, in a new `server/abilities/contested.ts` module, **registered last** in the `ABILITIES` registry (after `sea`). Like the `sea` and `industry` layers it is **durable**: `GameState.contested` persists across turns and in SQLite. It is a **pure territory-state** layer — the contested key simply *leaves* ownership (sole ownership is never broken: a key is in at most one `territory`), it is never placed into two territories, and it never touches borders directly.
+  - **Types (`shared/protocol.ts`).** New `ContestOp` (`{ regionKey; parties }` — `regionKey` is a region key or resolvable name, `parties` are two or more nation refs (ids or names)), `ContestedOps` (`{ open: ContestOp[]; resolve: string[] }`), and `ContestedRegion` (`{ regionKey; parties }` — `parties` store the **resolved** nation ids); `TurnResult.contested` is **required**, placed between `sea` and `markers`, default `{ open: [], resolve: [] }`. New `CONTESTED_FILL = '#f97316'` / `CONTESTED_STROKE` (the distinct visible frontline fill/stroke for the map — a reddish/orange "hot" frontline on the dark basemap, clearly distinct from a nation color and from the no-man's-land grey) and `contestedTooltipLabel(parties)` (a short `"Contested: A vs B"` hover sub-line; a missing party name degrades to a dash, never crashes). `ContestedRegion` is imported into `shared/types.ts`; `GameState.contested: ContestedRegion[]` is **required** (`[]` at creation; a legacy SQLite row without the field loads as `[]` — additive, never wiped, via the generic `ABILITIES` `stateFields` loop in `db.ts` — no `db.ts` code change needed).
+  - **Ability module (`server/abilities/contested.ts`).** `field: 'contested'`; `default()` / `stub()` → a **fresh** `{ open: [], resolve: [] }` each call; `validate` wraps the exported `validateContestedOps` (defensive, never throws — accepts the `{ open, resolve }` object; an `open` op needs a non-empty `regionKey` (trimmed, ≤120) and **two or more** non-empty `party` refs (each trimmed, ≤200), a `resolve` entry a non-empty key (trimmed, ≤120); missing / malformed → dropped; a missing / malformed top-level object yields `{ open: [], resolve: [] }`); `apply` runs the exported `applyContested`; `schemaLine()` / `constraint()` supply the prompt text; **`payload()` → `{ contested: [{ regionKey, parties: [NAMES] }] }`** (the current frontlines with party **names** resolved from the stored ids) **only when non-empty** — `{}` on a fresh / no-frontline world (like the turn-transient layers, unlike `sea` which always emits); `isMeaningful` = `open.length > 0 || resolve.length > 0`; **`stateFields: ['contested']`** (the durable `GameState` field, for the `db.ts` legacy-row migration).
+  - **Open semantics (`applyContested`, OPEN phase).** Each `open` op's `regionKey` resolves to a concrete key (exact key first, then a unique case-insensitive name via the region manifest — with no manifest loaded the raw string is accepted; a key absent from the loaded manifest is dropped). Its `parties` resolve via the shared `resolveNationRef` (id first, then a unique name; unresolvable / ambiguous refs dropped, order preserved, duplicates removed) — an op left with **fewer than two distinct resolved parties** is dropped. A region is **contestable** only when either (a) it has a **sole owner** that is at war (a shared **active** `War`) with at least one of the parties, or (b) it has **zero owners AND is in `unowned`** (no man's land) and **two of the parties are at war with each other**. A region with **two or more owners** (corrupt), or whose owner is **not at war with any party**, is never contestable (dropped — an ended / armistice war does not count). On a successful open the key is **removed from its sole owner's `territory`** (or from `unowned` for a no-man's-land region), its `regionStats` entry is **deleted**, and a `{ regionKey, parties: [ids] }` entry is added to `next.contested` (**unique by `regionKey`** — a re-open replaces any kept entry for the same key). The stripped owner's derived `stats` are **re-derived** (the same 0-region / no-entry guards as the other layers, so a 0-region owner keeps its directly-mutated value).
+  - **Resolve semantics (`applyContested`, RESOLVE phase — runs FIRST).** Each key in `resolve` that is currently in `next.contested` is removed and its region **released to no man's land** (out of any territory, into `unowned`, `regionStats` deleted) — **UNLESS a concurrent winning claim by one of the contesting parties** already re-owned it this turn (the only claim the territory step permits on a contested key), in which case it **stays owned** and its `regionStats` is **kept** (or **re-initialised** as a copy of the owner's stats if absent). A key that is not currently contested is ignored (no-op). A resolved key owned by a **non-party** (defensive) is released as above.
+  - **Territory-step guard (`engine.ts applyTurnResult`).** A **currently-contested** key (in `state.contested`) sits in no nation's territory, so a normal `gain` would otherwise be treated as a free re-claim. The claims step is guarded: a normal claim on a contested key proceeds **only** when this same turn `resolve`s the contest **AND** the gainer is one of the contesting **parties** (a party re-claim); otherwise the frontline **stays contested** for the contested layer (which runs later in the turn) to decide its fate. A still-contested key is therefore never a valid normal-claim target.
+  - **Map (client `WorldMap.tsx`).** The contested state is decided by the client from `GameState.contested` (like no-man's-land), **never by the `RegionMap`** (which stays owned-vs-absent). A contested key is rendered with the distinct `CONTESTED_FILL` / `CONTESTED_STROKE` and a `"Contested: A vs B"` hover sub-line; the contested check runs **first** (before unowned / owned) in the fill-resolution, and the hover handler resolves the party names from `GameState.contested`. **The map legend stays at 7 items** (it is derived from the `RegionMap` owners only — a contested key is absent from the `RegionMap`, so it adds no legend entry — e2e legend assertions unaffected). `App.tsx` passes `contested={game.contested ?? []}` to `<WorldMap>`.
+  - **Registry & prompt.** `contested` is added **last** in `ABILITIES` (existing order untouched — the 12th entry); the system prompt gains the `contested` schema line and its constraint bullet ("a contested region is in NO nation's territory (never two) and is never no man's land while contested; at most 1–2 contested-region changes per turn, each narrated in `events`"); the user prompt gains `"contested"` (region key + party **names**) **only when the list is non-empty** (the one durable ability whose `payload()` can be `{}`). The two committed system-prompt **goldens** (`system-no-tool.txt`, `system-tool.txt`) are regenerated (each gains exactly the new `contested` schema line after `sea` + constraint bullet before the "Prefer 1-4 events" bullet); the **`user.txt` golden gains a `"contested"` entry** (the sample `b-r1` frontline with party names) as a new key after `seaZones`.
+  - **Tests.** New `server/abilities/contested.test.ts` (**52 tests**): the `CONTESTED_FILL` / `CONTESTED_STROKE` / `contestedTooltipLabel` surface; `validateContestedOps` (shape / leniency / drops / field caps / malformed top-level); `applyContested` OPEN (sole-owner-at-war with owner-as-party / party-not-owner, owner-not-at-war drop, no-man's-land open + NML-with-warring-parties + not-in-unowned drop, corrupt 2-owner drop, armistice-not-a-war drop, distinct-party / unresolvable / ambiguous drops, region-name + party-name resolve, manifest-gated key drop, owner stats re-derive + 0-region guard, two-opens-on-same-key, multi-key open); RESOLVE (release-to-NML, party-re-claim keeps + re-inits stats, non-party-owner release, multi-frontline, non-contested no-op, empty no-op); ordering (re-open replaces, resolve-then-open from NML, still-contested not re-openable, combined apply); and the ability const contract (field, `stateFields`, fresh `default()`/`stub()`, `isMeaningful`, `payload()` id→name / missing-nation fallback / `{}` when empty, `validate` wrapping, `apply` ctx wiring). Every apply test asserts the **sole-ownership invariants** (no key in >1 territory; a contested key in no territory and not unowned; an unowned key in no territory and not contested). `registry.test.ts` is updated for the **12-ability** contract (order, distinct fields, `fullDefaultTurn()`, `meaningfulFor`, durable `stateFields`, composes 13 / `extended[12]`, re-export pin, user-golden 15th arg). New `db.test.ts` legacy-row test (a pre-v0.44 save without `contested` loads with `[]`).
+  - **Design note (deviation from the issue body).** The Gitea #66 body sketched a **two-owner** design (`disputed` regions with `fronts`, explicitly "relaxing sole-ownership"). The approved, implemented design is a **third region state**: a contested key is in **no** nation's `territory` and not in `unowned` (sole ownership is preserved — a key is never in two territories), with `open` / `resolve` ops and a **minimum of two contesting parties** tied to an active war. This keeps the engine's sacrosanct sole-ownership invariant intact while still modelling a war frontline.
+- **Guarantees.** No new runtime deps, `shared/` keeps zero runtime deps, no `@turf`/`@types/geojson` in any `.ts`. No engine randomness (the LLM declares; the engine applies fixed, deterministic rules). All existing unit tests green (additive); e2e (CI, `LLM_STUB=1`) unaffected (the stub is contested-inert — it never opens or resolves a frontline, and the map legend stays at 7).
+- **Version** bumped `0.43.0 → 0.44.0`.
+
+## v0.43.0 — 2026-10-16 12:09
+- **#65: Sea control — a `TurnResult.sea` lever letting the LLM declare sole control over a fixed set of 12 named sea zones (North Atlantic, South Atlantic, Pacific, Indian, Mediterranean, North Sea, Baltic, Arctic, Black Sea, Gulf of Mexico, Red Sea, Sargasso), with a deterministic per-turn +1 military / +1 economy bonus for the controlling nation.** It is a **durable** feature (unlike the turn-transient `hybrid` / `disasters` / `migration` layers): `GameState.seaZones` persists across turns and in SQLite, and the user payload **always** carries the current `seaZones` list (even when empty) so the model knows who controls what. It lands as the **11th ability** of the v0.40.0 modular system, in a new `server/abilities/sea.ts` module, **registered last** in the `ABILITIES` registry (after `migration`). Sea control is fully **parallel to but independent of land**: it never touches `territory` / `unowned`, and moving land never touches a sea zone.
+  - **Types (`shared/protocol.ts`).** New `SEA_ZONES` (a frozen array of 12 `{ id, name }` pairs), `SEA_ZONE_IDS` (a `ReadonlySet` of all 12 ids), `isSeaZoneId(id)` (type guard), `seaZoneName(id)` (human-readable name; unknown → raw), `SeaControlOp` (`{ zone; by }`), and `SeaOps` (`{ control: SeaControlOp[] }`); `TurnResult.sea` is **required**, placed between `migration` and `markers`, default `{ control: [] }`. New `SeaZoneClaim` (`{ zone; by }`) in `shared/types.ts`; `GameState.seaZones: SeaZoneClaim[]` is **required** (`[]` at creation; a legacy SQLite row without the field loads as `[]` — additive, never wiped, via the generic `ABILITIES` `stateFields` loop in `db.ts` — no `db.ts` code change needed).
+  - **Ability module (`server/abilities/sea.ts`).** `field: 'sea'`; `default()` / `stub()` → a **fresh** `{ control: [] }` each call; `validate` wraps the exported `validateSeaOps` (defensive, never throws — accepts the `{ control: [...] }` object or a bare array; each op needs a valid `zone` (one of the 12 `SEA_ZONE_IDS`) and a non-empty `by` (trimmed, ≤200) — anything else is dropped); `apply` runs `applySeaControl` then `applySeaZoneBonuses`; `schemaLine()` / `constraint()` supply the prompt text; **`payload()` → `{ seaZones: ctx.seaZones ?? [] }` — the one ability that always emits a user-payload key** (the durable list, even when empty — unlike the turn-transient layers whose `payload()` is `{}`); `isMeaningful` = `control.length > 0`; **`stateFields: ['seaZones']`** (the durable `GameState` field, for the `db.ts` legacy-row migration).
+  - **Contest semantics (`applySeaControl`).** Each op's `by` is resolved via the shared `resolveNationRef` (id first, then a case-insensitive unique name; unknown / ambiguous → dropped, never thrown). Per zone (in first-appearance order): a single surviving op **sets or replaces** the zone's controller in `GameState.seaZones` (replace in place — preserving the entry's position — or append a new one); two or more surviving ops on the same zone for **different** resolved nations make the zone **contested**: the higher current `stats.military` wins (a tie goes to the op listed earlier in the `control` array) — deterministic, no hidden randomness. The layer **never touches `territory` / `unowned`**.
+  - **Per-turn bonus (`applySeaZoneBonuses`).** Every committed turn — **including a turn with an empty `control`** — each existing claim's controller earns `SEA_ZONE_BONUS = 1` military + 1 economy (clamped to 0–100, mirrored to every region the nation owns, then the nation's derived `stats` re-derived with the same 0-region / no-entry guards as the economy / migration layers, so a 0-region nation keeps its directly-mutated value). A nation controlling several zones **stacks** the bonus (one per zone). A claim whose nation no longer exists (removed by a merge / split this turn) is **skipped** — the claim is kept, never thrown.
+  - **Registry & prompt.** `sea` is added **last** in `ABILITIES` (existing order untouched); the system prompt gains the `sea` schema line and its constraint bullet ("at most 1–2 claims per turn, each narrated in `events`"); the **user prompt gains `"seaZones": []` as a new last key** (the intentional deviation from the turn-transient layers — the durable list is always emitted). The two committed system-prompt **goldens** are regenerated (each gains exactly the new `sea` schema line + constraint bullet); the **`user.txt` golden gains `"seaZones": []`** as the last key (verified by diff).
+  - **Tests.** New `server/abilities/sea.test.ts` (**~40 tests**): the zone-id predicate sets; `validateSeaOps` (shape / leniency / drops / field caps); `applySeaControl` (set / replace-in-place / append / contest by military / tie-break / same-nation dedup / name-resolve / unresolvable drop / ambiguous drop / territory-untouched); `applySeaZoneBonuses` (+1/+1 / clamping / stacking / 0-region direct-dip / stale-controller skip / empty no-op / territory-untouched); and the ability const contract (field, `stateFields`, fresh `default()`/`stub()`, `isMeaningful`, `payload()` incl. `?? []`, `validate` wrapping, `apply` ctx wiring). `registry.test.ts` is updated for the **11-ability** contract (order, distinct fields, `fullDefaultTurn()`, `meaningfulFor`, durable fields, composes 12 / `extended[11]`, re-export pin, user-golden 14th arg). New `db.test.ts` legacy-row test (a pre-v0.43 save without `seaZones` loads with `[]`).
+  - **Design note (deviation from the issue body).** The Gitea #65 body sketched a `naval` layer with a free-form `zones` array; the approved design implemented here is the richer `sea` layer with a **fixed set of 12 named zones**, sole-control semantics, contest-by-higher-military, and a durable `seaZones` list — a cleaner, more deterministic model that the LLM can reason about without inventing zone names each turn.
+- **Guarantees.** No client (`src/`) changes, no new runtime deps, `shared/` keeps zero runtime deps, no `@turf`/`@types/geojson` in any `.ts`. All unit tests green (additive); e2e (CI, `LLM_STUB=1`) unaffected (the stub is sea-inert — it never proposes a sea op).
+- **Version** bumped `0.42.0 → 0.43.0`.
+
+## v0.42.0 — 2026-10-16 10:12
+- **#64: Migration & refugees — a `TurnResult.migration` lever letting the LLM declare population flows between nations (ordinary migration / refugee flows / a spreading diaspora / an exodus), with a deterministic per-`scale` effect: the source loses a little population and economy, the destination gains a little (a `large` influx also strains its stability), and the from↔to relation is nudged one step toward the positive end of the ladder.** It is a **turn-transient** feature, exactly like the v0.34 `hybrid` and v0.41 `disasters` layers: **no new `GameState` field, no `db.ts` change, no durable list** — the ops are consumed inside `applyTurnResult` and leave nothing behind. It lands as the **10th ability** of the v0.40.0 modular system, in a new `server/abilities/migration.ts` module, **registered last** in the `ABILITIES` registry (after `disasters`).
+  - **Types (`shared/protocol.ts`).** New `MigrationKind` (`'migration' | 'refugees' | 'diaspora' | 'exodus'`), `MigrationScale` (`'small' | 'moderate' | 'large'`), `MigrationOp` (`{ kind; from; to?; scale; detail? }` — `to` is required for every kind except `exodus`, which has no destination), and `MigrationOps` (`{ ops: MigrationOp[] }`); `TurnResult.migration` is **required**, placed between `disasters` and `markers`, default `{ ops: [] }`.
+  - **Ability module (`server/abilities/migration.ts`).** `field: 'migration'`; `default()` / `stub()` → a **fresh** `{ ops: [] }` each call; `validate` wraps the exported `validateMigrationOps` (defensive, never throws — accepts the `{ ops: [...] }` object or a bare array; each op needs a valid `kind`, a valid `scale`, a non-empty `from` (trimmed, ≤200), and — for every kind except `exodus` — a non-empty `to` (trimmed, ≤200); an optional `detail` (trimmed, ≤300, empty dropped) — anything else is dropped); `apply` runs `applyMigrationOp` per op; `schemaLine()` / `constraint()` supply the prompt text; `payload()` → `{}` (no user-payload keys — both refs resolve from the existing nation ref table); `isMeaningful` = `ops.length > 0`; **no** `stateFields` (turn-transient, no durable `GameState` field).
+  - **Deterministic effects (tables, no hidden randomness).** `MIGRATION_SOURCE_EFFECTS` per scale — the source LOSES: small `{population:-1, economy:-1}`, moderate `{population:-2, economy:-2}`, large `{population:-4, economy:-3}`. `MIGRATION_DESTINATION_EFFECTS` per scale — the destination GAINS: small `{population:+1, economy:+1}`, moderate `{population:+2, economy:+2}`, large `{population:+3, economy:+3}`. `LARGE_INFLUX_STABILITY_DIP = -2` — a `large` influx additionally strains the destination's stability by 2. All clamped to 0–100.
+  - **Apply semantics (`applyMigrationOp`).** Resolution is drop-first: `from` must resolve to a nation (id first, then a unique name; unknown / ambiguous → drop); for every kind except `exodus` the `to` must resolve to a nation **distinct from** `from` (missing / unknown / ambiguous / self-flow → the **whole op** is dropped, the source untouched). Only then is the source dip applied (all four kinds, including `exodus`); `exodus` then returns (no destination, no nudge). Otherwise the destination gain is applied (plus the `large` stability strain), and the from↔to relation is nudged by the self-contained `shiftRelationTowardPositive` — the mirror of the hybrid layer's `shiftRelationTowardHostile`, but toward `ally` (`POSITIVE_ORDER = ['ally','neutral','rival','hostile']`, cap `ally` for `refugees`, `neutral` for `migration` / `diaspora`, none for `exodus`; a missing relation starts at `neutral`; a `war` relation is **never** touched — the nudge neither fabricates nor escalates a war). Each affected nation's dip is clamped to 0–100, **mirrored to every region it owns** (`regionStats`), and its derived `stats` **re-derived** afterwards (the same 0-region / no-entry guards as hybrid / economy / disasters — a 0-region nation keeps its directly-mutated value and the effect persists). It **never moves territory** (sole ownership is untouched). The **stub never** proposes a migration (`{ ops: [] }`), so e2e (CI, `LLM_STUB=1`) is unaffected and the path is covered by unit tests only.
+  - **Registry & prompt.** `migration` is added **last** in `ABILITIES` (existing order untouched); the system prompt gains the `migration` schema line and its constraint bullet ("at most 1–2 per turn, each narrated in `events` as a `social` or `diplomatic` event"); the user prompt is unchanged (`payload()` is `{}`). The two committed system-prompt **goldens** (`system-no-tool.txt`, `system-tool.txt`) are regenerated (each gains exactly the new `migration` schema line + constraint bullet); the **`user.txt` golden stays byte-identical** (no new user-payload keys — verified by checksum).
+  - **Tests.** New `server/abilities/migration.test.ts` (**38 tests**): the kind/scale predicate sets; the three effect tables (exact keys / signs / monotonicity); `validateMigrationOps` (shape / leniency / drops / field caps); `shiftRelationTowardPositive` (one-step nudge, caps, war-untouched, missing→neutral, unknown no-op); `applyMigrationOp` (small / moderate / large source & destination dips, the `large` stability strain, name-based resolve, the relation nudge by kind, war-untouched, exodus-only-source, self-flow drop, unknown / ambiguous source & destination drop, 0-region direct-dip persistence, territory-untouched, clamping at 0 and 100); and the ability const contract (field, no `stateFields`, fresh `default()`/`stub()`, `isMeaningful`, `payload() {}`, `validate` wrapping, `apply` ctx wiring). `registry.test.ts` is updated for the **10-ability** contract (order, distinct fields, `fullDefaultTurn()`, `meaningfulFor`, re-export pin); the goldens are regenerated (verified idempotent).
+  - **Design note (interpretation of the issue body).** The Gitea #64 body sketched a simpler `flows: { type: 'refugees' | 'settlers' }` shape that included a settler **re-claim of no-man's-land**; the refined, approved design implemented here is the richer `migration.ops` union of **four nation-to-nation population-flow kinds** (migration / refugees / diaspora / exodus) — a purely **stat** layer that **never moves territory** (sole ownership stays untouched; a no-man's-land re-claim is deliberately out of scope, as territory movement remains the `regionChanges` lever's job).
+- **Guarantees.** No client (`src/`) changes, no new runtime deps, `shared/` keeps zero runtime deps, and no `@turf`/`@types/geojson` in any `.ts`. All unit tests green (additive); e2e (CI, `LLM_STUB=1`) unaffected (the stub is migration-inert).
+- **Version** bumped `0.41.0 → 0.42.0`.
+
+## v0.41.0 — 2026-10-16 09:07
+- **#63: Disasters & pandemics — a `TurnResult.disasters` lever letting the LLM declare natural/man-made disasters (earthquake / flood / volcanic / wildfire / famine / plague / epidemic) on a nation or a region, with a deterministic stat dip (stability / economy / military).** It is a **turn-transient** feature, exactly like the v0.34 `hybrid` layer: **no new `GameState` field, no `db.ts` change, no durable list** — the ops are consumed inside `applyTurnResult` and leave nothing behind. It lands as the **9th ability** of the v0.40.0 modular system, in a new `server/abilities/disasters.ts` module, **registered last** in the `ABILITIES` registry (after `ideology`, before the loop appends `markers` / `nationOps`).
+  - **Types (`shared/protocol.ts`).** New `DisasterType` (`'earthquake' | 'flood' | 'volcanic' | 'wildfire' | 'famine' | 'plague' | 'epidemic'`), `DisasterSeverity` (`'minor' | 'moderate' | 'severe'`), `DisasterEvent` (`{ type; target; severity; detail? }` — `target` is a nation ref **or** a region key), and `DisastersOps` (`{ events: DisasterEvent[] }`); `TurnResult.disasters` is **required**, placed between `ideology` and `markers`, default `{ events: [] }`.
+  - **Ability module (`server/abilities/disasters.ts`).** `field: 'disasters'`; `default()` / `stub()` → a **fresh** `{ events: [] }` each call; `validate` wraps the exported `validateDisasterEvents` (defensive, never throws — accepts the `{ events: [...] }` object or a bare array; each event needs a valid `type`, a valid `severity`, and a non-empty `target` (trimmed, ≤120) — anything else is dropped, with a per-turn cap); `apply` runs `applyDisasterEvent` per event; `schemaLine()` / `constraint()` supply the prompt text; `payload()` → `{}` (no user-payload keys — targets resolve from the existing ref table); `isMeaningful` = `events.length > 0`; **no** `stateFields` (turn-transient, no durable `GameState` field).
+  - **Deterministic effects (`DISASTER_EFFECTS`).** A pure `(type, severity) → stat-dip` table — **no hidden randomness**. `population` is never touched. Earthquake and famine dip **both** `stability` and `economy` (−2 / −4 / −7 for minor / moderate / severe); flood dips `economy` (−2 / −3 / −6) and `stability` (−1 / −2 / −4); volcanic dips `economy` (−2 / −4 / −7) and `stability` (−2 / −3 / −6); wildfire dips **only** `economy` (−2 / −4 / −7); plague dips `stability` (−3 / −5 / −9) and `military` (−2 / −3 / −6); epidemic dips `stability` (−2 / −4 / −7) and `military` (−1 / −2 / −4).
+  - **Apply semantics (`applyDisasterEvent`).** The `target` is resolved exactly like a hybrid op (`resolveHybridTarget`): a resolvable nation ref hits every region the nation owns; a region key hits its **sole** owner; a 0-owner or 2+-owner region key is **dropped** (never thrown). The one deliberate difference from hybrid: a disaster has **no `from` field**, so there is **no self-target drop** — a nation may suffer a disaster it itself declared. The dip is clamped to 0–100, **mirrored to every region the target owns** (`regionStats`), and the target's derived `stats` is **re-derived** afterwards (the same 0-region / no-entry guards as hybrid / economy / industry — a 0-region nation keeps its directly-mutated value). It never moves territory (sole ownership is untouched). The **stub never** declares a disaster (`{ events: [] }`), so e2e (CI, `LLM_STUB=1`) is unaffected and the path is covered by unit tests only.
+  - **Registry & prompt.** `disasters` is added last in `ABILITIES`; the system prompt gains the `disasters` schema line and its constraint bullet ("at most 1–2 per turn, each narrated in `events`"); the user prompt is unchanged (`payload()` is `{}`). The two committed system-prompt **goldens** (`system-no-tool.txt`, `system-tool.txt`) are regenerated (each gains exactly the new `disasters` schema line + constraint bullet); the **`user.txt` golden stays byte-identical** (no new user-payload keys — verified by checksum).
+  - **Tests.** New `server/abilities/disasters.test.ts` (**33 tests**): the type/severity predicate sets; `validateDisasterEvents` (shape / leniency / drops / cap); `applyDisasterEvent` exact dips (nation target, single-region target, region gated by `validKeys`, clamping at 0, 0-owner / 2+-owner region drops, unknown-key drop, unknown / ambiguous ref drops, case-insensitive name resolve, 0-region direct-dip persistence, missing-`regionStats`-entry skip); and the ability const contract (field, no `stateFields`, fresh `default()`/`stub()`, `isMeaningful`, `payload() {}`, `validate` wrapping, `apply` ctx wiring). `registry.test.ts` is updated for the **9-ability** contract (order, fields, `fullDefaultTurn()`, `meaningfulFor`, re-export pin); the goldens are regenerated (verified idempotent).
+- **Secondary cleanups from the v0.40.0 refactor (folded into this release):**
+  - **AGENTS.md** — `server/abilities/` is added to the Layout tree (the per-ability files, tests, and goldens); Conventions gains a "Modular LLM abilities — how to add a new one (v0.40.0, #67)" bullet and a "Disasters & pandemics (v0.41.0, #63)" bullet.
+  - The **orphaned `validateTakeovers` JSDoc** (left over after the v0.40 refactor removed the function body) is deleted.
+  - Both **inline `as unknown` double-casts** are folded into the single top-level `./abilities` import (`AbilityCtx` + `UserPromptCtx` types).
+  - **`str()` is de-duplicated** — imported from `./abilities/shared` instead of the local copy.
+- **Guarantees.** No client (`src/`) changes, no new runtime deps, `shared/` keeps zero runtime deps, and no `@turf`/`@types/geojson` in any `.ts`. All unit tests green (additive); e2e (CI, `LLM_STUB=1`) unaffected (the stub is disasters-inert).
+- **Version** bumped `0.40.0 → 0.41.0`.
+
+## v0.40.0 — 2026-10-16 07:14
+- **#67: Modular LLM-ability system — the 8 per-feature LLM abilities are extracted from `server/engine.ts` into an ordered `ABILITIES` registry (`server/abilities/`).** A pure, **behavior-preserving** refactor: each per-ability concern (validate / schema-line / constraint / payload / meaningfulness / apply / stub-default / durable-state-field) moves into one file per ability, assembled into a single ordered registry that the engine iterates uniformly. **Nothing observable changes** — the system prompt, user prompt, `applyTurnResult` world-state mutations, and the deterministic stub are all byte-for-byte identical to v0.39.0 (pinned by new golden fixtures + registry tests), and `server/engine.ts` re-exports every name its existing callers import, so `server/index.ts` and all tests work with zero edits.
+  - **New `server/abilities/` package.**
+    - `types.ts` — the `Ability<K extends AbilityField>` interface (a self-contained per-field module: `field`, `default()`, `validate()`, `apply()`, `schemaLine()`, `constraint()`, `isMeaningful()`, `stub()`, `payload()`, optional `stateFields`) plus the `AbilityField` union (the closed set of the 8 fields), `AbilityCtx`, and `UserPromptCtx` type surfaces.
+    - `shared.ts` — the cross-ability pure helpers (`resolveNationRef`, `resolveRegionKey`, `freshNationId`, `freshWarId`, `NEW_NATION_STATS`).
+    - `apply-helpers.ts` — the war-relation sync helpers (`activeWarPairs`, `atWar`, `syncWarRelations`).
+    - One file per ability — `takeovers.ts`, `wars.ts`, `hybrid.ts`, `economy.ts`, `industry.ts`, `nuclear.ts`, `leaders.ts`, `ideology.ts` — each owning its `Ability<K>` const (validator, applier, schema line, constraint bullet, meaningfulness predicate, inert stub default, user-payload keys, and — for wars / economy / industry — the `GameState` fields it owns).
+    - `index.ts` — assembles the ordered `ABILITIES` registry (`takeovers → wars → hybrid → economy → industry → nuclear → leaders → ideology`) and re-exports every public name the engine and its tests need.
+  - **Engine (`server/engine.ts`).** Every per-ability code path now iterates `ABILITIES` instead of hand-enumerating the eight fields: `buildSystemPrompt` (schema lines + constraint bullets), `buildUserPrompt` (payload keys at their exact historical positions), `validateTurnResult` (per-field validate), `applyTurnResult` (the ordered apply block), `isMeaningful`, and the `runTurn` "unclear" fallback. The ~1,249 lines of moved ability bodies are deleted; the 21 names its callers import are re-exported from `./abilities` (5 shared primitives + 16 ability-module exports).
+  - **Stub (`server/stub.ts`).** `deterministicTurn` fills the 8 ability fields from the registry (each contributes its inert default) between the core fields and `markers` — the JSON output stays byte-identical to v0.39.0 (verified against `origin/master`).
+  - **Persistence (`server/db.ts`).** The legacy-row migration for ability-owned `GameState` fields (wars / trades / embargoes / industry) iterates the registry's `stateFields` (only-if-undefined) instead of a hardcoded field list.
+  - **Tests.** New `server/abilities/registry.test.ts` (11 tests): the committed **golden prompts** (`server/abilities/goldens/` — system no-tool / system tool / user) are asserted **byte-identical** to the pre-refactor engine's output (a `REGEN_GOLDENS=1` mode regenerates them after an intentional prompt change — verified a no-op); the registry is the canonical 8-ability order with 8 distinct `TurnResult` fields; each `default()` equals the canonical `TurnResult` default and is a **fresh** value (never a shared reference); the default is never "meaningful" while a populated value is; the registry declares exactly the durable `GameState` fields; the registry composes (a hypothetical 9th ability appends cleanly to every uniform loop); and the engine still re-exports every name its callers import.
+  - **Guarantees.** No client (`src/`) changes, no new runtime deps, no `@turf`/`@types/geojson` in any `.ts`, and `shared/` keeps zero runtime deps. All 522 unit tests green; e2e (CI, `LLM_STUB=1`) unaffected.
+- **Version** bumped `0.39.0 → 0.40.0`.
+
+## v0.39.0 — 2026-10-15 20:51
+- **#62: Ideology / form of government — a per-nation `ideology` + a `TurnResult.ideology` lever (coups / revolutions / reforms / constitutional changes) with a deterministic −5 stability dip and political narration.** Each nation may carry a free-form `ideology` label — its form of government ("democracy", "fascism", "military junta", …). The model changes it each turn via `ideology.changes`; each change names a target nation (id or name) and the new government type. The engine sets the label and applies a **deterministic** stability dip (a regime shift always unsettles a nation) — **no hidden randomness**, **additive** (no `db.ts` change — `ideology` is an optional `Nation` field; a pre-v0.39 row loads with it absent, i.e. "no recorded government"). It is a third, independent axis next to `leader` (who is in charge) and the v0.32.0 takeover (which renames the nation): the id, name, territory, relations, and the leader all stay valid — only the form of government and stability move.
+  - **Types (`shared/types.ts`).** `Nation.ideology?: string` (optional; `undefined`/absent = no recorded government).
+  - **Protocol (`shared/protocol.ts`).** New `IdeologyChange` (`{ target; to }` — `target` is a nation ref, `to` is the new form of government), `IdeologyOps` (`{ changes: IdeologyChange[] }`); `TurnResult.ideology` is **required**, placed between `leaders` and `markers`, default `{ changes: [] }`. New exported **`IDEOLOGY_STABILITY_EFFECT = −5`** (the deterministic stability dip of a regime shift). `nationForPrompt` now includes the nation's `ideology` (omitted when absent via `JSON.stringify`), so `buildUserPrompt` carries each nation's current government with no separate wiring.
+  - **Engine (`server/engine.ts`).**
+    - `validateIdeologyOps(raw)` — new exported, defensive validator (never throws): accepts a `{ changes: [...] }` object or a bare array; each change needs a non-empty `target` (trimmed, ≤120) and a non-empty, non-whitespace `to` (trimmed, ≤120) — anything else is dropped. Refs stay raw (resolved at apply time, like wars / hybrid / nuclear / leader ops).
+    - `applyIdeologyChange(next, op, geoOf?, actingTurn?)` — new, mirrors `applyLeaderChange` (single-stat, nation-target). Resolves the target (unknown / ambiguous → dropped, never thrown). On a valid change it sets `n.ideology = to` and applies `IDEOLOGY_STABILITY_EFFECT` (−5) to `n.stats.stability` (clamped 0–100) mirrored to every region the nation owns (`regionStats`), then re-derives the nation's stats (the same 0-region / no-entry guards as hybrid / economy / industry / leaders, so a 0-region nation keeps its directly-mutated value). Re-setting the **same** label is idempotent for the `ideology` field but still narrated and still dips (the shift just happened). Finally it appends a **`political`** narration event (`"<nation>'s government shifted to <to>"`). The change never moves territory (sole ownership is untouched).
+    - `applyTurnResult` — the ideology block runs **after `leaders` and before `markers`** (order: events → relations → territory → stateChanges → recompute → takeovers → wars → hybrid → economy → industry → nuclear → leaders → **ideology** → markers → nationOps).
+    - `isMeaningful` — a non-empty `ideology.changes` makes a turn meaningful.
+    - `validateTurnResult` — initializes and validates `ideology` (default `{ changes: [] }`).
+    - `buildSystemPrompt` — documents the `ideology` field (free-form label, the −5 dip, the "at most 1–2 per turn, narrated" rule) and contrasts it with a takeover (which RENAMES the nation) and a leader change (who is in charge); similar forms of government are a **soft, prompt-level compatibility nudge only** (alike ideologies tend to ally/trade, opposed ones tend to clash) — there is no engine gate behind it.
+    - `runTurn` — the "unclear" fallback carries `ideology: { changes: [] }`.
+  - **Stub (`server/stub.ts`).** `deterministicTurn` always returns `ideology: { changes: [] }` and the `StubPayload` nations type gains an optional `ideology` — the stub **never** changes an ideology, so the e2e (CI, `LLM_STUB=1`) is unaffected and the path is covered by unit tests only.
+  - **Tests.** New unit tests in `engine.test.ts`: `validateIdeologyOps` (`{changes}` object, bare array, empty/whitespace `to` drop, missing/whitespace target drop, malformed top-level, mixed batch keeps only valid, trim + 120-cap); `isMeaningful` (an ideology change is meaningful, empty ideology is not); `applyTurnResult` (a valid change → field set + 50→45 + `political` event + region mirror, other nation untouched; re-setting the same label → one dip, one event; a multi-region nation → every region dipped and stats re-derived; a target resolved by name as well as id; a 0-region nation keeps its directly-dipped stat; a dip clamped at 0; an unknown target and an ambiguous (two-nation-same-name) target → dropped without throwing); `buildUserPrompt` (a set ideology is stamped in the prompt nations, an absent one is omitted). `protocol.test.ts`: the `IDEOLOGY_STABILITY_EFFECT` constant is −5 and `nationForPrompt` includes/omits the `ideology` key in the JSON. Two `db.test.ts` round-trips: a legacy row with no ideology loads with it absent, and a set ideology round-trips through save/load.
+- **Version** bumped `0.38.0 → 0.39.0`.
+
+## v0.38.0 — 2026-10-15 20:06
+- **#61: Named leaders — a per-nation `leader` + a `TurnResult.leaders` lever (assassination / death / appointment) with a deterministic stability effect and succession narration.** Each nation may carry a single named head of state (`Nation.leader`); the model changes it each turn via `leaders.changes`. The engine is **fully deterministic (no hidden randomness)** and **additive** (no `db.ts` change — `leader` is an optional `Nation` field; a pre-v0.38 row loads with it absent, i.e. "no leader").
+  - **Types (`shared/types.ts`).** `Nation.leader?: { name: string }` (optional; `undefined`/absent = the nation has no leader).
+  - **Protocol (`shared/protocol.ts`).** New `LeaderCause` (`'assassination' | 'death' | 'appointed'`), `LeaderChange` (`{ target; name; cause }` — `target` is a nation ref, `name` is the new leader's name), and `LeaderOps` (`{ changes: LeaderChange[] }`); `TurnResult.leaders` is **required**, placed between `nuclear` and `markers`, default `{ changes: [] }`. New exported **`LEADER_STABILITY_EFFECT = { assassination: −15, death: −3, appointed: 0 }`** (the deterministic stability dip by cause). `nationForPrompt` now includes the nation's `leader` (omitted when absent), so `buildUserPrompt` carries each nation's current leader with no separate wiring.
+  - **Engine (`server/engine.ts`).**
+    - `validateLeaderOps(raw)` — new exported, defensive validator (never throws): accepts a `{ changes: [...] }` object or a bare array; each change needs a non-empty `target` (≤120), a non-empty `name` (≤120), and a `cause` that is one of the three literals — anything else is dropped. Refs stay raw (resolved at apply time, like wars / hybrid / nuclear ops).
+    - `applyLeaderChange(next, op, geoOf?, actingTurn?)` — new, mirrors `applyHybridOp` (single-stat, nation-target). Resolves the target (unknown / ambiguous → dropped, never thrown). **GATE**: an `assassination`/`death` requires the target to already have a leader (a leaderless target is dropped); `appointed` is always valid (it creates the first leader). On a valid change it sets `n.leader = { name }` and applies `LEADER_STABILITY_EFFECT[cause]` to `n.stats.stability` (clamped 0–100) mirrored to every region the nation owns (`regionStats`), then re-derives the nation's stats (the same 0-region / no-entry guards as hybrid / economy / industry, so a 0-region nation keeps its directly-mutated value). Finally it appends a narration event: a dramatic **`military`** event for an assassination, a **`political`** succession event for a death or an appointment. The replacement never moves territory (sole ownership is untouched).
+    - `applyTurnResult` — the leader block runs **after `nuclear` and before `markers`** (order: events → relations → territory → stateChanges → recompute → takeovers → wars → hybrid → economy → industry → nuclear → **leaders** → markers → nationOps).
+    - `isMeaningful` — a non-empty `leaders.changes` makes a turn meaningful.
+    - `validateTurnResult` — initializes and validates `leaders` (default `{ changes: [] }`).
+    - `buildSystemPrompt` — documents the `leaders` field (the three causes, the stability effects, the leaderless-gate, the "at most 1–2 per turn, narrated" rule) and contrasts it with the lighter `hybrid.assassinate` op (a −5 dip, no leader replacement) in both tool and plain modes.
+    - `runTurn` — the "unclear" fallback carries `leaders: { changes: [] }`.
+  - **Stub (`server/stub.ts`).** `deterministicTurn` always returns `leaders: { changes: [] }` and the `StubPayload` nations type gains an optional `leader` — the stub **never** changes a leader, so the e2e (CI, `LLM_STUB=1`) is unaffected and the path is covered by unit tests only.
+  - **Tests.** New unit tests in `engine.test.ts`: `validateLeaderOps` (`{changes}` object, bare array, unknown-cause drop, missing target/name drop, malformed top-level, mixed batch keeps only valid); `isMeaningful` (a leader change is meaningful, empty leaders is not); `applyTurnResult` (assassination with a leader → replaced + −15 + `military` event; assassination / death on a leaderless nation → dropped, no stat change, no event; death → replaced + −3 + `political` succession event; appointment on a leader-having and on a leaderless nation → sets the leader, neutral (no dip); a multi-region nation → every region dipped and stats re-derived; an unknown target and an ambiguous (two-nation-same-name) target → dropped without throwing). Two `db.test.ts` round-trips: a legacy row with no leader loads with it absent, and a set leader round-trips through save/load.
+- **Version** bumped `0.37.0 → 0.38.0`.
+
+## v0.37.0 — 2026-10-15 19:15
+- **#60: Nuclear / WMD — a per-nation `nuclear` capability flag + a `TurnResult.nuclear` lever (`arm` + `strikes`) with deterministic strikes and MAD retaliation.** A nation is *nuclear-capable* when its `nuclear` flag is `true` **or** it currently owns a `rocket` marker (a launch site is an arsenal). The model can **arm** nations (grant the flag — idempotent; a newly-armed nation is capable the same turn, since `arm` is applied before `strikes`) and fire **strikes** (`{ from, target }`). The engine is **fully deterministic (no hidden randomness)** and **additive** (a `db.ts` change is not needed — `nuclear` is an optional `Nation` field; a pre-v0.37 row loads with the flag absent).
+  - **Capability (`shared/protocol.ts`).** `isNuclearCapable(nation, markers)` — exported pure helper: `nation.nuclear === true` **or** it owns a `rocket` marker (`marker.type === 'rocket' && marker.ownerNationId === nation.id`). Markers supply the *pre-turn* rocket set, so a rocket placed this turn makes the owner capable from the *next* turn.
+  - **Types (`shared/types.ts`).** `Nation.nuclear?: boolean` (optional; `undefined`/absent = not armed; default `false` behavior).
+  - **Protocol (`shared/protocol.ts`).** New `NuclearStrike` (`{ from; target }` — `from` is the striking nation, `target` is a nation ref or a region key) and `NuclearOps` (`{ arm: string[]; strikes: NuclearStrike[] }`); `TurnResult.nuclear` is **required**, placed between `industry` and `markers`, default `{ arm: [], strikes: [] }`. New exported `NuclearStatKey` (`'economy' | 'military' | 'stability'`) and the two deterministic collapse tables: **`NUCLEAR_COLLAPSE = { economy: −40, military: −50, stability: −40 }**` (a full strike's effect on the struck nation / region owner) and **`NUCLEAR_RETALIATION = { economy: −20, military: −25, stability: −20 }`**` (the half-strength MAD backfire).
+  - **Engine (`server/engine.ts`).**
+    - `validateNuclearOps(raw)` — new exported, defensive validator (never throws): a missing/malformed object yields `{ arm: [], strikes: [] }`; `arm` entries are non-empty strings (≤120 chars) deduped; a strike needs a non-empty `from` **and** `target` (≤120) and is **dropped when it targets itself** (same ref, case-insensitive) — a self-strike is a no-op, never thrown.
+    - `applyNuclearOps(next, ops, state, geoOf?, validKeys?, regionNameOf?, actingTurn?)` — new exported, the load-bearing nuclear block. **`arm` first** (idempotent; a resolve miss or a self-arm is a no-op), then **`strikes`** in order: resolve `from` (an unresolvable or non-capable striker is **dropped** — capability checked against the *pre-turn* marker set plus any flag granted this turn); a `target` that is a **nation** collapses it (the `NUCLEAR_COLLAPSE` deltas applied to its `stats` and every region it owns, each affected nation's derived stats re-derived, 0-region / no-entry guards as elsewhere), ends **every active war it fights** by **capitulation** (`endWarsBetween` captures the active pairs *before* ending so a war declared+ended the same turn is handled), and downgrades the now-inactive `war` relations to `hostile`; a `target` that is a **region key** releases it to no man's land (a key with 0 or 2+ owners, or one the striker itself owns, is **dropped**), deletes its `regionStats` entry, and collapses its **sole owner** the same way. **MAD**: if the struck nation (or the struck region's sole owner) is itself nuclear-capable, it retaliates against the striker for the half-strength `NUCLEAR_RETALIATION` (clamped, mirrored, re-derived) and the two nations' relations are forced to `hostile` (`forceHostile` — both directions, unless already `war`). Each strike and each retaliation appends a dramatic **`military`** event (`war` is not a valid `EventType`). Sole ownership is never broken by a strike (a region is released, not re-claimed) and the block never throws.
+    - `applyTurnResult` — the nuclear block runs **after `industry` and before `markers`** (order: events → relations → territory → stateChanges → recompute → wars → hybrid → economy → industry → **nuclear** → markers → nationOps); it passes the *original* (pre-turn) `state` for the capability marker set and the current `regionNameOf` for event text.
+    - `isMeaningful` — a non-empty `nuclear.arm` or `nuclear.strikes` makes a turn meaningful.
+    - `validateTurnResult` — initializes and validates `nuclear` (default `{ arm: [], strikes: [] }`).
+    - `buildSystemPrompt` — documents the `nuclear` field and a constraint bullet (the capability rule; `arm` is idempotent; a strike hits a nation or a region; the collapse + capitulation + MAD outcomes; at most one strike per turn, always narrated) in both tool and plain modes.
+    - `buildUserPrompt` — new optional `nuclear` param (`Record<string, boolean>`, the per-nation capability map); when provided, each `state.nations` entry in the payload is stamped with its `nuclear` capability; when undefined the key is omitted entirely (stub / no-capability prompt stays byte-identical). `runTurn` always supplies the map (computed from `isNuclearCapable` over `state.markers`).
+  - **Stub (`server/stub.ts`).** `deterministicTurn` always returns `nuclear: { arm: [], strikes: [] }` — the stub **never** arms a nation or fires a strike, so the e2e (CI, `LLM_STUB=1`) is unaffected and the nuclear path is covered by unit tests only.
+  - **Tests.** 29 new unit tests: `isNuclearCapable` (flag / own rocket / non-rocket / other's rocket / null owner); `validateNuclearOps` (well-formed, `arm` dedupe, missing `from`/`target`, self-target drop, malformed top-level); `applyTurnResult` nuclear (arm idempotency across turns, arm+strike same turn, region strike → release + stats deleted + owner collapse + no MAD + the single `military` event, nation strike + pre-existing war → capitulation + hostile, nation strike + same-turn declare → capitulation + hostile, MAD on a capable nation target, MAD on a capable region owner, rocket-marker-only capability, non-capable striker dropped, 2+-owner region dropped, 0-owner/unowned region dropped, self-target dropped, malformed strikes never throw); `isMeaningful` (arm / strike); `buildUserPrompt` (per-nation capability stamped when the map is given, omitted when undefined); and two `db.test.ts` round-trips (a legacy row with no flag loads with it absent; a set flag round-trips through save/load).
+- **Version** bumped `0.36.0 → 0.37.0`.
+
+## v0.36.0 — 2026-10-15 18:17
+- **#59: Resources & Industry — per-region synthesized resource profiles + a per-region industry-project lever with a deterministic per-turn economy boost.** Every prior lever moved borders, dipped stats one-shot, or proposed a player-confirmed change; this version adds a **resource abundance layer** (every sub-region gets a synthesized 4-value profile) and a **development lever**: the model can build industry projects (oil facilities, iron mines, food operations, factories) in individual regions, and every committed turn each active project pays its region's sole owner a small, deterministic economy gain scaled by the region's `industry` resource value. The engine is **fully deterministic (no hidden randomness)**: the resource profiles are a pure function of the region key (FNV-1a) scaled by an area factor, and the per-turn effect is a fixed, clamped, mirrored, re-derived stat adjustment.
+  - **Manifest (`public/region-resources.json`, new).** 1,800 entries — region key → `{ oil, iron, food, industry }` (each 0–1, 2dp) — built by the new turf-free, deterministic, **idempotent** `scripts/build-region-resources.mjs` (`npm run build:region-resources`): per resource, `(fnv1a32(`${key}\u0000${resource}`) & 0x3fff) / 0x4000` → [0,1), times an area factor `1 + 0.2·min(1, log10(1+area)/8)` (max ≈1.2) from `region-geo.json` (missing geo / zero area → pure hash), clamped to 1, keys sorted, byte-identical re-run. Pinned by `scripts/build-region-resources.test.ts` (key-set equality vs `region-keys.json`, sorted order, per-entry shape, spot-checked values, determinism via a re-run).
+  - **Types (`shared/types.ts`).** New `RegionResources` (`{ oil; iron; food; industry }`), `IndustryType` (`'oil' | 'iron' | 'food' | 'industry'`) + `INDUSTRY_TYPES` const, `IndustryProject` (`{ regionKey; type }`), and the required `GameState.industry: IndustryProject[]` field (placed after `embargoes`). `[]` on a fresh game; rows saved before v0.36 load with it defaulted to `[]` (additive, never wiped).
+  - **Protocol (`shared/protocol.ts`).** New `IndustryOps` (`{ projects: IndustryProject[] }`); `TurnResult.industry` is required, placed between `economy` and `markers`. New exported `deriveNationResources(regionKeys, resourceOf?, geoOf?)` — a nation's aggregate profile as the **area×population-weighted AVERAGE** (an average, not a median, is the meaningful aggregation for an abundance profile) of the resource profiles of its owned regions, same weight formula as `deriveNationStats`, 2dp-rounded, zero profile when no owned region has a profile.
+  - **Engine (`server/engine.ts`).**
+    - `isIndustryType(t)` — exported guard over the four types (mirrors `isHybridOpType`).
+    - `validateIndustryOps(raw)` — new exported, defensive validator (never throws): a missing/malformed object yields `{ projects: [] }`; each op needs a non-empty `regionKey` (≤120 chars) and a known `type`.
+    - `industryBoost(regionKey, resourceOf?)` — internal; `INDUSTRY_ECONOMY_BONUS = 1` plus one extra point when the region's `industry` value is ≥ 0.5 (without the manifest, just the base).
+    - `applyIndustryOps(next, ops, validKeys?)` — internal; applies the turn's projects to `GameState.industry` as a **per-region SET** — a key not in the valid-keys manifest is dropped; a region that already hosts a project is untouched (first type wins; re-declare is a no-op, the type is never replaced).
+    - `applyIndustryEffects(next, resourceOf?, geoOf?)` — new exported; the per-turn effect, applied **every committed turn** to the **full** active list: each project grants its region's **SOLE owner** (owner resolved from the FINAL post-claim ownership; 0 or 2+ owners → no boost, project **kept**, never thrown) a deterministic economy boost, clamped to 0–100, mirrored to every region the owner holds (`regionStats`), and each affected nation's derived `stats` re-derived afterwards (same 0-region / no-entry guards as the economy/hybrid dips). Sole ownership is untouched (the layer moves stats, never territory). No-op when there are no active projects; never throws.
+    - `applyTurnResult` — new `resourceOf` param (last) and **industry block** (after the economy block, before markers): `applyIndustryOps` → `applyIndustryEffects` (ops first, so a project declared this turn is paid this turn).
+    - `isMeaningful` — non-empty `industry.projects` makes a turn meaningful.
+    - `validateTurnResult` — initializes and validates `industry` (default `{ projects: [] }`).
+    - `buildSystemPrompt` — documents the `industry` field and a constraint bullet (a per-resource development lever; one project per region — never re-declare on a region that already has one; at most 1–2 per turn, each narrated in `events`) in both tool and plain modes.
+    - `buildUserPrompt` — new optional `nationResources` (each nation's aggregate profile) and `industryProjects` (the active projects) params — emitted as `resources` / `industry` in the payload, only when provided (so the stub / no-manifest prompt stays byte-identical).
+    - `runTurn` — new optional `resourceOf` (last); computes `nationResources` via `deriveNationResources` **only when** the resource manifest is loaded (otherwise omitted from the prompt); passes both new payload fields; the "unclear" fallback carries `industry: { projects: [] }`; `applyTurnResult` receives `resourceOf`.
+  - **Regions loader (`server/regions.ts`).** The optional-manifest pattern extended: `region-resources.json` is probed after `public/` then `dist/`; malformed entries (any of the four values not a finite number in [0,1]) are filtered out, a failure logs `[regions] failed to load region-resources.json, continuing without it` and the server keeps working without it; new `hasResources()` / `resourceOf(key)` accessors (mirror `hasGeo()` / `geoOf()`).
+  - **Server wiring (`server/index.ts`).** The jump route passes `resourceOf: hasResources() ? (key) => resourceOf(key) : undefined` into `runTurn` (like `geoOf`); fresh preset games are created with `industry: []` (dynamic games already via `shared/scenario.ts`).
+  - **Persistence (`server/db.ts`).** `load()` defaults `industry` to `[]` on rows saved before v0.36 (additive migration, alongside `unowned`/`pendingNationOps`/`markers`/`wars`/`trades`/`embargoes`) — legacy games are never wiped and never gain phantom projects.
+  - **Stub (`server/stub.ts`).** The deterministic stub returns `industry: { projects: [] }` — it **never** declares an industry project, so the e2e (CI, `LLM_STUB=1`) assertions are unaffected and the path is covered by unit tests only. `StubPayload` gains optional `resources` / `industry` fields (ignored).
+  - **Unit tests.** New: `scripts/build-region-resources.test.ts` (5 tests); `server/regions.test.ts` (resources load/spot-check/unknown-key, degradation, prod `dist/` layout, incl. a new "with the manifest" case); `server/protocol.test.ts` — `deriveNationResources` (7 tests: area×population weighting, unweighted degradation, profile-skipping, zero profile, single region, weight fallback, 2dp rounding); `server/db.test.ts` — legacy-row default; `server/engine.test.ts` — `validateIndustryOps` (shape/drops), `applyTurnResult` industry ops (declare, per-region SET / re-declare no-op, invalid-key drop, persistence across turns), `applyIndustryEffects` (sole-owner boost, ≥0.5 scaling, multi-project accumulation, ownerless/2+ owner kept-but-unpaid, no-op empty), `isMeaningful`, the system-prompt contract (both modes), the user-prompt payload (carried / omitted), and the `runTurn` defensive init; all pre-existing fixtures gained the new required fields (mechanical, deliberate updates).
+  - **Client.** No change — the industry layer is an engine/LLM concern; its effects surface through the existing stats and event feed.
+  - **AGENTS.md.** New convention entry documenting the resource manifest, the per-region SET semantics, the sole-owner per-turn boost, and the stub/test coverage; the `public/` layout, the scripts pipeline line, and the Commands table all gained `region-resources` / `build:region-resources`.
+
+## v0.35.0 — 2026-10-15 17:22
+- **#58: Trade & Embargoes — a bilateral trade + embargo economy layer with a deterministic per-turn effect and war auto-suspension.** Every prior turn lever moved borders, dipped stats one-shot, or proposed a player-confirmed change. This version adds `TurnResult.economy = { trade: EconomyTradeOp[]; embargo: EconomyEmbargoOp[] }` (required, default `{ trade: [], embargo: [] }`) so the model can declare/lift **bilateral trade agreements** and **unilateral embargoes**, which persist in `GameState` and apply a small, deterministic economic effect **every committed turn**. The engine is **fully deterministic (no hidden randomness)** and **additive** — declares add to the lists, lifts remove, and nothing else (not even a war, beyond the suspension below) mutates them.
+  - **Types (`shared/types.ts`).** New `TradeAgreement` (`{ a; b }` — a symmetric pair, stored sorted `a < b`) and `Embargo` (`{ from; target }` — an ordered unilateral pair) interfaces, plus the required `GameState.trades` and `GameState.embargoes` fields (placed after `wars`). Both are `[]` on a fresh game; rows saved before v0.35 load with them defaulted to `[]` (additive, never wiped).
+  - **Protocol (`shared/protocol.ts`).** New `EconomyTradeOp` (`{ a; b; lift? }`), `EconomyEmbargoOp` (`{ from; target; lift? }`), and `EconomyOps` (`{ trade; embargo }`) types. `TurnResult.economy` is required, placed between `hybrid` and `markers`; a no-`lift` op declares/imposes, `lift: true` ends/lifts.
+  - **Engine (`server/engine.ts`).**
+    - `validateEconomyOps(raw)` — new exported, defensive validator (never throws): a missing/malformed object yields `{ trade: [], embargo: [] }`; each op needs non-empty `a`/`b` (or `from`/`target`) refs (trimmed, ≤200 chars) and a boolean `lift` (default false). Raw refs are kept — resolution happens at apply time against the real state (like wars/hybrid ops).
+    - `applyEconomyOps(next, ops)` — internal; resolves each op's refs via `resolveNationRef` (id first, then unique case-insensitive name). An unresolvable / ambiguous / self-pairing op is dropped (never thrown). A no-`lift` trade **declares** the agreement idempotently (stored sorted, so `{a,b}` and `{b,a}` are the same pair); `lift: true` ends it (a no-op when absent). A no-`lift` embargo **imposes** the ordered from→target pair idempotently; `lift: true` lifts it.
+    - `suspendEconomyOnWar(next)` — internal; 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. Runs **after** the turn's war declare/end ops (so it sees the final `next.wars`, including a war declared this turn) and **before** the per-turn effect.
+    - `applyEconomyEffects(next, geoOf?)` — internal; the per-turn effect, applied **every committed turn** to the **full** active lists (not just this turn's declares): each active trade grants **both** parties a small, deterministic economy gain (`TRADE_ECONOMY_BONUS`); each active embargo applies a small, deterministic economy dip to the **target only** (`EMBARGO_ECONOMY_PENALTY`). Clamped to 0–100, mirrored to every region the nation owns (`regionStats`), and each affected nation's derived `stats` re-derived afterwards (same 0-region/no-entry guards as the hybrid dip). No-op when there are no active trades or embargoes; never throws.
+    - `applyTurnResult` — new **economy block** (after the hybrid block, before markers): `applyEconomyOps` → `suspendEconomyOnWar` → `applyEconomyEffects`, in that order (ops first, so a same-turn trade declared between two nations that just went to war is suspended; effects then run on the surviving full lists). Sole ownership is untouched (the economy layer moves stats, never territory).
+    - `isMeaningful` — a non-empty `economy.trade` or `economy.embargo` makes a turn meaningful.
+    - `validateTurnResult` — initializes and validates `economy` (default `{ trade: [], embargo: [] }`).
+    - `buildSystemPrompt` — documents the `economy` field and a constraint bullet (bilateral trade gains both parties; a unilateral embargo hits the target only; omit `lift` to declare/impose, `lift: true` to end/lift; at most 1–2 ops per turn, narrated in `events`; trades/embargoes between warring nations are auto-suspended) in both tool and plain modes.
+    - `buildUserPrompt` — new optional `trades` and `embargoes` params (the currently active agreements/embargoes) so the model knows what is active and can `lift` it; emitted only when provided.
+    - `runTurn` — passes `state.trades` and `state.embargoes` to `buildUserPrompt`; the "unclear" fallback carries `economy: { trade: [], embargo: [] }`.
+  - **Stub (`server/stub.ts`).** The deterministic stub returns `economy: { trade: [], embargo: [] }` — it **never** declares or lifts a trade or embargo, so the e2e (CI, `LLM_STUB=1`) assertions are unaffected and the path is covered by unit tests only (`server/engine.test.ts`).
+  - **Persistence (`server/db.ts`).** `load()` defaults `trades`/`embargoes` to `[]` on rows saved before v0.35 (additive migration, alongside `unowned`/`pendingNationOps`/`markers`/`wars`) — legacy games are never wiped and never gain phantom trades/embargoes.
+  - **Game creation (`server/index.ts`, `shared/scenario.ts`).** Fresh games (preset and dynamic) are created with `trades: []` and `embargoes: []`.
+
+## v0.34.0 — 2026-10-15 16:35
+- **#57: Espionage & Hybrid War — a non-kinetic operations spectrum with a deterministic per-type effect and an exposure backfire.** Every prior turn lever was kinetic (conquest, state-change, region-change, wars, takeovers) or a player-confirmed proposal (nation ops). This version adds `TurnResult.hybrid = { ops: HybridOp[] }` (required, default `{ ops: [] }`) so the model can run **covert, non-kinetic** operations: spies, sabotage, assassination attempts, cyberattacks, economic pressure, disinformation, and proxy support. Unlike territory these **never move borders** — they dip a target's stats or sour a relation. The engine is **fully deterministic (no hidden randomness)**: the LLM declares an intended `outcome` (`success` by default, or `exposed`); a successful op applies its small per-type effect, an `exposed` op **backfires** (no effect, the actor's relation with the target sours one step toward hostile, and an auto `diplomatic`/`failure` event is emitted).
+  - **Protocol (`shared/protocol.ts`).** New `HybridOpType` (the seven types) + `HYBRID_OP_TYPES` const, and the `HybridOp` interface (`{ type; from; target; detail?; outcome? }`). `from` is the acting nation (id or unique name — resolved at apply time); `target` is **either** a nation (id/name) **or** a region key (hits that region's sole owner). `TurnResult.hybrid = { ops: HybridOp[] }` is required, placed between `wars` and `markers`.
+  - **Engine (`server/engine.ts`).**
+    - `isHybridOpType(t)` — exported guard over the seven types.
+    - `validateHybridOps(raw)` — new exported, defensive validator (never throws): accepts the `{ ops: […] }` object **or** a bare array; each op needs a known `type`, a non-empty `from` (≤200) and non-empty `target` (≤200); `outcome:'exposed'` is kept (success/missing is omitted to keep the shape minimal); `detail` capped at 300.
+    - `HYBRID_STAT_EFFECT` — exported table of the deterministic per-type stat dip: `sabotage`→economy −3, `assassinate`→stability −5, `cyber`→military −3, `economic`→economy −5; `spy`/`information`/`proxy` have no stat effect.
+    - `shiftRelationTowardHostile(state, a, b, cap)` — exported; nudges the bilateral relation **one** rung up the hostile ladder (`ally→neutral→rival→hostile`), symmetrically, capped at `cap`; a missing relation starts at `neutral`; a `war` relation is never touched (a covert op neither fabricates nor downgrades a war). Used for the `information`/`proxy` nudge and the `exposed` backfire.
+    - `resolveHybridTarget(state, target, validKeys?)` — internal; resolves a target to the concrete nation it affects: a nation ref via `resolveNationRef`, else a region key's **sole** owner (0 or 2+ owners → not targetable); `validKeys` (when supplied) gates the region path.
+    - `applyHybridOp(next, op, geoOf?, validKeys?, regionNameOf?, actingTurn?)` — internal; resolves `from`/`target` (unknown/ambiguous actor, unresolvable target, and self-targets are dropped — never throw), then applies the per-type effect: an `exposed` op backfires (relation sours one step, cap hostile, auto `diplomatic`/`failure` event); a successful stat op dips the target's `regionStats` (the single named region for a region target, otherwise **every** region the target owns) and re-derives the target nation's aggregate stats (same 0-region/no-entry guards as the main recompute) so the effect persists; `information`/`proxy` nudge the relation (caps `hostile`/`rival`); `spy` is informational only.
+    - `applyTurnResult` — new **hybrid block** (after the wars block, before markers): applies each validated op against the post-wars state. Sole ownership is preserved (a hybrid op affects stats, never ownership).
+    - `isMeaningful` — a non-empty `hybrid.ops` makes a turn meaningful.
+    - `validateTurnResult` — initializes and validates `hybrid` (default `{ ops: [] }`).
+    - `buildSystemPrompt` — documents the `hybrid` field and a HARD CONSTRAINTS bullet (non-kinetic, never moves borders, the per-type effects, the `exposed` backfire, region-key targets hit the sole owner, at most a few per turn, narrate each in `events`) in both tool and plain modes.
+    - `buildUserPrompt` — new optional `relations` param (the player's `nationId → RelationStatus` map) so the model sees the ladder its ops nudge and the starting point before a backfire; emitted only when provided.
+    - `runTurn` — computes the player's `relations` from state and passes them as the last `buildUserPrompt` arg; the "unclear" fallback carries `hybrid: { ops: [] }`.
+  - **Additive only.** No `GameState` field, **no** DB migration, **no** `db.ts` change — `hybrid` lives entirely in the `TurnResult` and is consumed by `applyTurnResult`.
+  - **Stub (`server/stub.ts`).** `deterministicTurn` returns `hybrid: { ops: [] }` — the stub **never** runs a covert op (mirrors `nationOps: []`, `takeovers: []`, `wars`). `StubPayload` gains an optional `relations` field (ignored). E2E (CI, `LLM_STUB=1`) is fully unaffected; the path is unit-tested only.
+  - **Unit tests (`server/engine.test.ts`).** ~30 new tests: `isHybridOpType`; `validateHybridOps` (both raw shapes, trim/cap, exposed-vs-success, drop rules); `validateTurnResult` — hybrid; `isMeaningful` — hybrid; `shiftRelationTowardHostile` (ladder, caps, war-untouched, missing=neutral); `applyTurnResult` — hybrid (each stat type's dip, nation-vs-region target, the per-type relation nudge & caps, `exposed` backfire + auto event, exposed-on-war, drop rules for unknown actor / self-target / unknown region / double-owned region, the `validKeys` gate, borders-untouched invariant, `HYBRID_STAT_EFFECT` magnitudes); `buildSystemPrompt` — hybrid contract (both modes); `buildUserPrompt` — relations; stub — hybrid.
+  - **Client.** No change — hybrid ops are an engine/LLM concern; their effects surface through the existing stats, relations, and event feed.
+  - **AGENTS.md.** New convention entry documenting the `hybrid` field, the deterministic per-type effects, the `exposed` backfire, the region-vs-nation targeting, and the stub/test coverage.
+
+## v0.33.0 — 2026-10-15 15:45
+- **#56: War as a first-class state — the `war` relation becomes a named `War` entity.** The v0.22+ `war` relation was a bare boolean flag on the `Relation` type with no lifecycle, no identity, and no way to distinguish "at war since 1939" from "at war since 1941" or to narrate the end of a conflict. This version promotes it to a first-class `War` entity in `GameState.wars` with a stable id, sides, declaration date/turn, optional aims, a lifecycle status (`active` / `armistice` / `capitulation`), and an optional front (region keys). The LLM declares and ends wars via `TurnResult.wars = { declare, end }` (both required, default `[]`); the engine creates/updates the entity and **derives** the `war` relation from active wars (any two nations on opposite sides of ≥1 active war get `war` in both directions, overriding lesser statuses — you cannot "make peace" without ending the war). When a war ends, the pairs it caused that are not covered by another active war fall back to `hostile`. A **bare** `war` relation with no matching active war (legacy/back-compat) is never downgraded and never force-created. **Mutual-defense drag-in**: when a war is declared, each belligerent's `ally`-relation partners are added to the war's `sides` (one level, no cascade; deterministic — sides in declared order, allies in sorted id order), so the dragged-in ally becomes `war` with all belligerents including its former ally.
+  - **Types (`shared/types.ts`).** New `War` interface (`id`, `sides: string[]` ≥2 distinct, `declaredTurn: number`, `declaredDate?: string`, `aims?: string[]`, `status: 'active'|'armistice'|'capitulation'`, `front?: string[]`); `GameState.wars: War[]` (required, `[]` at creation; a legacy SQLite row without the field loads as `[]` — additive, never wipes).
+  - **Protocol (`shared/protocol.ts`).** New `WarDeclareOp` (`{ sides: string[]; aims?: string[] }`) and `WarEndOp` (`{ id: string; outcome: 'armistice'|'capitulation'; terms?: string }`); `TurnResult.wars = { declare: WarDeclareOp[]; end: WarEndOp[] }` (both required, default `[]`). New `WarInfo` interface (`{ id; sides; aims? }`) for the user-prompt payload.
+  - **Engine (`server/engine.ts`).**
+    - `validateWarOps(raw)` — new exported, defensive validator (never throws): non-object → empty; `declare` — sides trimmed/capped 200/deduped, ≥2; aims ≤5×200; `end` — id ≤200, outcome exactly `armistice`|`capitulation`, terms ≤400.
+    - `activeWarPairs(wars): Set<string>` — NUL-joined sorted pair keys for active-only wars.
+    - `atWar(wars, a, b)` — convenience check.
+    - `syncWarRelations(prev, next)` — exported; enforces the derived `war` relation (active pairs → `war` both directions; ended pairs not covered by another active war → `hostile`; bare `war` never downgraded, never force-created).
+    - `freshWarId(taken)` — first free of `w1`, `w2`, … (next to `freshNationId`).
+    - `applyTurnResult` — new **wars block** (after takeovers, before markers): declare → create `War` (sides resolved via `resolveNationRef`; <2 distinct → dropped); end → find by id (unknown → no-op); then `syncWarRelations(state, next)`.
+    - `isMeaningful` — a non-empty `declare` or `end` makes a turn meaningful.
+    - `buildSystemPrompt` — documents the `wars` field (declare/end, at most 1–2 per turn, each narrated in `events`; the `war` relation is derived — do not emit it directly for active-war pairs).
+    - `buildUserPrompt` — carries current **active** wars as `WarInfo[]` so the model can `end` by id.
+    - `runTurn` — computes active-only `wars` from `state.wars`, passes as last arg; the "unclear" fallback carries `wars: { declare: [], end: [] }`.
+  - **DB (`server/db.ts`).** `load` defaults `state.wars` to `[]` when absent (after the markers default, before `migrateRegionStats`).
+  - **Stub (`server/stub.ts`).** `deterministicTurn` returns `wars: { declare: [], end: [] }` — the stub never declares or ends a war (mirrors `nationOps: []`, `takeovers: []`). E2E (CI, `LLM_STUB=1`) is unaffected; the path is unit-tested only.
+  - **Unit tests (`server/engine.test.ts`).** ~30 new tests: `freshWarId`, `validateWarOps`, `validateTurnResult` (wars), `activeWarPairs` / `atWar`, `syncWarRelations`, `applyTurnResult` — wars (declare creates war + derives relations; end removes active status + un-derives relations; mutual-defense drag-in; unknown-id end no-op; duplicate declare skip; unresolvable-ref drop; bare-war back-compat; relations-override-forced-back; same-turn declare+end leaves prior relation untouched), `isMeaningful` — wars, `buildSystemPrompt` — wars contract, `buildUserPrompt` — wars, stub — wars.
+  - **Client.** No change — wars are an engine/LLM concern; the UI already renders the `war` relation from the `Relation` type (which the engine now keeps in sync).
+  - **AGENTS.md.** New convention entry documenting the `War` entity, the `syncWarRelations` algorithm, the mutual-defense drag-in, and the stub/test coverage.
+
 ## v0.32.0 — 2026-10-15 10:56
 - **#54: non-military takeovers become a visible regime change — a `Takeover` in the turn renames the nation.** The v0.30.0 stats work made stability a *soft* lever: the system prompt told the model that a low-stability nation (`stability < 30`) hosting a `gathering` marker "can suffer a non-military takeover — a coup, revolution or faction seizure of power", narrated with an event and a stat shock — but the model had no actual *field* to express the regime change itself, so the nation's name never changed and the takeover was invisible in the world. This version closes that gap with a new `TurnResult.takeovers` field: `Takeover = { nationRef, newRegimeName }`. Each entry is an **automatic, in-world** regime change applied directly by `applyTurnResult` (unlike `nationOps`, which are player-confirmed proposals) — the target nation's display `name` becomes `newRegimeName`, while its stable `id`, territory, relations (keyed by id), stats, and `playerNationId` are all preserved, so a player whose nation is overthrown keeps leading it under the new regime.
   - **Protocol (`shared/protocol.ts`).** New `Takeover` interface (`nationRef` + `newRegimeName`, both strings). `TurnResult.takeovers: Takeover[]` is **required** (default `[]`), placed between `nationOps` and `markers`.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "history",
-  "version": "0.32.0",
+  "version": "0.44.0",
   "private": true,
   "type": "module",
   "description": "AI-driven alternate-history simulator — the LLM is the world engine (Pax Historia style).",
@@ -20,6 +20,7 @@
     "build:region-adjacency": "node scripts/build-region-adjacency.mjs",
     "build:region-centroids": "node scripts/build-region-centroids.mjs",
     "build:region-geo": "node scripts/build-region-geo.mjs",
+    "build:region-resources": "node scripts/build-region-resources.mjs",
     "extract:admin0-pop": "node scripts/extract-admin0-pop.mjs",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",

scripts/build-region-resources.mjs

@@ -0,0 +1,149 @@
+/**
+ * scripts/build-region-resources.mjs — build the region **resources** manifest:
+ * `public/region-resources.json` = `{ "<regionKey>": { "oil": <0-1>, "iron": <0-1>, "food": <0-1>, "industry": <0-1> }, ... }`.
+ *
+ * Every sub-region (region key, see `public/region-keys.json`) gets a
+ * synthesized four-value resource profile. For each resource dimension a
+ * value in [0, 1] (2 decimal places) is derived from the FNV-1a 32-bit hash
+ * of the region key (salted per resource — the same tiny, stable, pure
+ * string hash the region keys themselves use), then scaled MODESTLY by the
+ * region's area (from the committed `public/region-geo.json`, when present):
+ * larger regions carry a slightly higher value (a log-scaled factor of at
+ * most ~1.2), so a big region reads as holding more of each resource. The
+ * geo file is OPTIONAL — without it (or for a zero-area region) the factor
+ * is exactly 1 and the profile is pure hash.
+ *
+ * This is the v0.36 (#59) "Resources & Industry" data source: the engine
+ * scales each region's per-turn industry boost by its `industry` value, and
+ * the LLM prompt carries each nation's aggregate profile (the
+ * area×population-weighted mean of the owned regions' profiles, see
+ * `deriveNationResources` in shared/protocol.ts). The profiles are
+ * synthesized (there is no real per-sub-region resource census) — they exist
+ * to give the model a stable, deterministic world fact to reason about.
+ *
+ * Output contract (asserted by scripts/build-region-resources.test.ts):
+ *   - one entry for **every** region key, keyed identically to
+ *     `public/region-keys.json` (same key set, 1,800 entries);
+ *   - each entry is `{ oil, iron, food, industry }`, every value a finite
+ *     number in [0, 1] with at most 2 decimal places;
+ *   - keys are in sorted (deterministic) order.
+ *
+ * Deterministic + idempotent: fixed inputs (the key manifest, and the
+ * committed geo file when present), pure string hashing, fixed 2-dp
+ * rounding, and stable sorted key order → a re-run rewrites a byte-identical
+ * file (the test re-runs this script and compares bytes).
+ *
+ * Usage: `node scripts/build-region-resources.mjs`  (or `npm run build:region-resources`).
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(here, '..');
+
+const round2 = (v) => Math.round(v * 100) / 100;
+
+/** FNV-1a 32-bit — the same tiny, stable, pure hash the region keys use. */
+function fnv1a32(str) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h >>> 0;
+}
+
+const RESOURCES = ['oil', 'iron', 'food', 'industry'];
+
+// --- load the inputs (plain parse) ------------------------------------------
+const keysPath = path.join(root, 'public', 'region-keys.json');
+const geoPath = path.join(root, 'public', 'region-geo.json');
+
+let idToKey;
+try {
+  idToKey = JSON.parse(readFileSync(keysPath, 'utf8'));
+} catch (err) {
+  console.error(`[build-region-resources] could not load ${keysPath}.`);
+  throw err;
+}
+
+// region-geo is OPTIONAL: a missing/broken file means "no area scaling"
+// (factor 1 for every region) — the profile is then pure hash.
+let areaByKey = {};
+try {
+  const parsed = JSON.parse(readFileSync(geoPath, 'utf8'));
+  for (const [k, v] of Object.entries(parsed)) {
+    if (v && typeof v.area === 'number' && Number.isFinite(v.area) && v.area >= 0) {
+      areaByKey[k] = v.area;
+    }
+  }
+} catch {
+  areaByKey = {};
+}
+
+/**
+ * The base value in [0, 1) for one (region key, resource): the low 14 bits of
+ * the salted FNV-1a hash, normalized. Stable across runs and platforms; a
+ * uniform-enough spread for a synthesized profile.
+ */
+const base = (key, resource) => (fnv1a32(`${key}\u0000${resource}`) & 0x3fff) / 0x4000;
+
+/**
+ * The area scaling factor: 1.0 for a region with no geo entry (or zero area),
+ * rising on a log scale (clamped) to at most ~1.2 for the largest regions —
+ * bigger regions hold proportionally more of each resource.
+ */
+const areaScale = (key) => {
+  const a = areaByKey[key];
+  if (!a || a <= 0) return 1;
+  // log10(1 + area) runs ~0.004 (tiny slivers) to ~5.5 (a 300k km² region);
+  // /8 + clamp keeps the factor in [1, 1.2].
+  const t = Math.min(1, Math.log10(1 + a) / 8);
+  return 1 + 0.2 * t;
+};
+
+// --- assemble the manifest (sorted keys) -------------------------------------
+const expectedKeys = Object.values(idToKey);
+const manifest = {};
+for (const k of [...expectedKeys].sort()) {
+  const scale = areaScale(k);
+  manifest[k] = {
+    oil: round2(Math.min(1, base(k, 'oil') * scale)),
+    iron: round2(Math.min(1, base(k, 'iron') * scale)),
+    food: round2(Math.min(1, base(k, 'food') * scale)),
+    industry: round2(Math.min(1, base(k, 'industry') * scale)),
+  };
+}
+
+// --- hard assertions (the test re-checks these against the committed file) ----
+if (Object.keys(manifest).length !== expectedKeys.length) {
+  throw new Error(
+    `expected ${expectedKeys.length} region-resources entries (one per region key), got ${Object.keys(manifest).length}`,
+  );
+}
+let scaled = 0;
+for (const [k, v] of Object.entries(manifest)) {
+  if (areaByKey[k]) scaled += 1;
+  for (const r of RESOURCES) {
+    const val = v[r];
+    if (typeof val !== 'number' || !Number.isFinite(val) || val < 0 || val > 1) {
+      throw new Error(`bad ${r} value for ${k}: ${JSON.stringify(val)}`);
+    }
+    if (Math.round(val * 100) / 100 !== val) {
+      throw new Error(`${r} over 2dp for ${k}: ${val}`);
+    }
+  }
+}
+
+// --- write idempotently (sorted keys, 2-space indent, trailing newline) ------
+writeFileSync(
+  path.join(root, 'public', 'region-resources.json'),
+  JSON.stringify(manifest, null, 2) + '\n',
+);
+
+// --- summary ------------------------------------------------------------------
+console.log(
+  `[build-region-resources] wrote public/region-resources.json — ${Object.keys(manifest).length} region keys` +
+    ` (${scaled} area-scaled, ${Object.keys(manifest).length - scaled} pure-hash)`,
+);

scripts/build-region-resources.test.ts

@@ -0,0 +1,106 @@
+/**
+ * scripts/build-region-resources.test.ts — validation for the committed
+ * `public/region-resources.json` (built by `scripts/build-region-resources.mjs`).
+ *
+ * The manifest maps each region key to a synthesized four-value resource
+ * profile `{ oil, iron, food, industry }` — each a finite number in [0, 1]
+ * (2 decimal places). It is the v0.36 (#59) "Resources & Industry" data
+ * source: the engine scales each region's per-turn industry boost by its
+ * `industry` value, and the LLM prompt carries each nation's aggregate
+ * profile (the area×population-weighted mean of the owned regions' profiles,
+ * `deriveNationResources` in shared/protocol.ts).
+ *
+ * Like the region-geo manifest, this is a load-bearing data artifact — the
+ * test pins its contract. It is dependency-free: it reads the JSON with plain
+ * `fs`/`JSON.parse` (no `@turf`/geojson types, which would pull `@types/geojson`
+ * into the tsc program and break `WorldMap.tsx` — see the v0.17 note). The
+ * determinism test re-runs the (turf-free) `.mjs` builder and compares bytes,
+ * matching that the builder is idempotent.
+ */
+import { readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(here, '..');
+
+function readJson(rel: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(path.join(root, rel), 'utf8'));
+}
+
+interface ResourceEntry {
+  oil: number;
+  iron: number;
+  food: number;
+  industry: number;
+}
+
+const RESOURCES = ['oil', 'iron', 'food', 'industry'] as const;
+
+// feature id -> region key
+const manifest = readJson('public/region-keys.json') as Record<string, string>;
+const resources = readJson('public/region-resources.json') as Record<string, ResourceEntry>;
+const keys = Object.values(manifest);
+
+describe('region-resources.json', () => {
+  it('has exactly one entry per region key (same key set as region-keys.json)', () => {
+    expect(new Set(Object.keys(resources))).toEqual(new Set(keys));
+    expect(Object.keys(resources)).toHaveLength(1800);
+  });
+
+  it('is keyed in sorted (deterministic) order', () => {
+    const ks = Object.keys(resources);
+    expect(ks).toEqual([...ks].sort());
+  });
+
+  it('every entry is a finite { oil, iron, food, industry } in [0,1] with ≤ 2 dp', () => {
+    for (const [k, v] of Object.entries(resources)) {
+      for (const r of RESOURCES) {
+        const val = v[r];
+        expect(typeof val, `non-number ${r} for ${k}`).toBe('number');
+        expect(Number.isFinite(val), `non-finite ${r} for ${k}`).toBe(true);
+        expect(val >= 0, `negative ${r} for ${k}: ${val}`).toBe(true);
+        expect(val <= 1, `${r} above 1 for ${k}: ${val}`).toBe(true);
+        expect(
+          Math.round(val * 100) / 100 === val,
+          `${r} over 2dp for ${k}: ${val}`,
+        ).toBe(true);
+      }
+    }
+  });
+
+  it('spot-checks well-known regions for exact profiles', () => {
+    const is = (k: string, oil: number, iron: number, food: number, industry: number) => {
+      const v = resources[k];
+      expect(v, `missing resources for ${k}`).toBeDefined();
+      expect(v!.oil, `oil for ${k}`).toBe(oil);
+      expect(v!.iron, `iron for ${k}`).toBe(iron);
+      expect(v!.food, `food for ${k}`).toBe(food);
+      expect(v!.industry, `industry for ${k}`).toBe(industry);
+    };
+    is('california-kikh', 0.31, 0.1, 0.82, 0.97); // US-CA
+    is('arkhangel-sk-lhbk', 0.49, 0.52, 0.98, 0.82); // RU-ARK mainland core
+    is('pechora-qwhs', 0.11, 0.16, 1, 0.04); // RU-PEO (Arctic-coast band, #41)
+    is('yamal-gosw', 0.64, 1, 1, 0.49); // RU-YAM (Arctic-coast band, #41)
+    is('new-earth-eikt', 0.6, 0.56, 0.91, 0.66); // RU-ARK-NE (island group, #31)
+    is('severnaya-zemlya-awqp', 0.1, 0.48, 1, 0.3); // RU-ARK-SZ (island group, #31)
+    is('ain-lqtt', 0.94, 0.92, 0.51, 0.4); // FR-01 (Ain)
+  });
+
+  it('is deterministic: re-running the builder rewrites a byte-identical file', () => {
+    const file = path.join(root, 'public', 'region-resources.json');
+    const before = readFileSync(file, 'utf8');
+    // The builder is cwd-independent (it resolves the repo root from its own
+    // location) and idempotent: same input files (region-keys.json + the
+    // committed region-geo.json when present) + pure string hashing + fixed
+    // 2-dp rounding + stable (sorted) key order → identical bytes.
+    execFileSync(process.execPath, [path.join(root, 'scripts', 'build-region-resources.mjs')], {
+      cwd: root,
+      stdio: 'pipe',
+    });
+    const after = readFileSync(file, 'utf8');
+    expect(after).toBe(before);
+  });
+});

server/abilities/apply-helpers.ts

@@ -0,0 +1,88 @@
+// Shared, cross-ability `apply` primitives (v0.40.0, #67): the war-derived
+// relation machinery that several abilities share. Two abilities (wars,
+// nuclear) mutate `GameState.wars` and both need the same "which pairs are at
+// war" primitive (`activeWarPairs` / `atWar`); the wars ability applies the
+// turn's declare/end ops and then runs the war → relation sync
+// (`syncWarRelations`), and the nuclear ability's `endWarsBetween` (which
+// lives in ./nuclear.ts) reuses `activeWarPairs` to downgrade the relations a
+// just-ended war no longer covers.
+//
+// The bodies here are moved VERBATIM from the pre-refactor engine.ts (v0.39.0)
+// — `engine.ts` re-exports all three so existing callers (server/index.ts, the
+// unit tests) keep importing them from the engine unchanged. All functions are
+// pure or mutate their `GameState` argument in place and never throw.
+
+import type { GameState, War } from '../../shared/types';
+
+/**
+ * (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},
+ * {b,c} (any two distinct belligerents of the same active war are at war —
+ * see the War type's semantics). Pure; exported for the unit tests.
+ */
+export function activeWarPairs(wars: War[]): Set<string> {
+  const pairs = new Set<string>();
+  const key = (a: string, b: string) => (a < b ? `${a}\u0000${b}` : `${b}\u0000${a}`);
+  for (const w of wars) {
+    if (w.status !== 'active') continue;
+    for (let i = 0; i < w.sides.length; i++) {
+      for (let j = i + 1; j < w.sides.length; j++) {
+        pairs.add(key(w.sides[i], w.sides[j]));
+      }
+    }
+  }
+  return pairs;
+}
+
+/** True when nations `a` and `b` are both belligerents of ≥1 active war. */
+export function atWar(wars: War[], a: string, b: string): boolean {
+  const key = a < b ? `${a}\u0000${b}` : `${b}\u0000${a}`;
+  return activeWarPairs(wars).has(key);
+}
+
+/**
+ * (v0.33.0, #56) Derive the `war` relation from the set of ACTIVE wars,
+ * MUTATING the (cloned) `next` state in place (the caller passes a clone —
+ * applyTurnResult does) and never touching `prev`. For every unordered pair
+ * of distinct existing nations:
+ *
+ *  - the pair is on the sides of ≥1 ACTIVE war in `next` → BOTH directions
+ *    of the pair's relation are set to `war` (the engine owns this relation
+ *    while the war is active — a manual `relations` entry to a lesser status
+ *    on a warring pair is overridden, so the two can never "make peace"
+ *    without the war being ended);
+ *  - the pair is NOT at war in `next` but WAS at war in `prev` (one of the
+ *    wars that tied them ended this turn) AND the current relation is
+ *    `war` → both directions become `hostile` (a war is the strongest
+ *    hostility — when it stops, the nations stay hostile, not suddenly
+ *    neutral);
+ *  - otherwise (not at war now, and the relation is not `war`, or the pair
+ *    was never tied by an active war) → untouched: the LLM owns
+ *    ally/neutral/rival/hostile freely, and a **bare** `war` relation that
+ *    no active war ever covered (a preset leftover) stays as-is — an
+ *    implicit, unnamed war, never force-created into a War entity and never
+ *    clobbered by the sync.
+ *
+ * Never throws.
+ */
+export function syncWarRelations(prev: GameState, next: GameState): void {
+  const prevAtWar = activeWarPairs(prev.wars ?? []);
+  const nextAtWar = activeWarPairs(next.wars ?? []);
+  const ids = Object.keys(next.nations);
+  for (let i = 0; i < ids.length; i++) {
+    for (let j = i + 1; j < ids.length; j++) {
+      const a = ids[i];
+      const b = ids[j];
+      const key = a < b ? `${a}\u0000${b}` : `${b}\u0000${a}`;
+      const na = next.nations[a];
+      const nb = next.nations[b];
+      if (nextAtWar.has(key)) {
+        na.relations[b] = 'war';
+        nb.relations[a] = 'war';
+      } else if (prevAtWar.has(key) && (na.relations[b] === 'war' || nb.relations[a] === 'war')) {
+        na.relations[b] = 'hostile';
+        nb.relations[a] = 'hostile';
+      }
+    }
+  }
+}

server/abilities/contested.ts

@@ -0,0 +1,301 @@
+// The CONTESTED (contested regions / frontlines) ability (v0.44.0, #66) as a
+// modular LLM-ability (v0.40.0, #67) — a THIRD region state, besides "owned by
+// one nation" and "no man's land": a war frontline that is in **no** nation's
+// `territory` and not in `unowned`, contested by two or more nations at war.
+//
+// Each turn the LLM may `open` a region as a contested frontline and/or
+// `resolve` an existing one. `open` requires the region to have a SOLE owner
+// that is at war with at least one of the parties, or to be no man's land (in
+// `unowned`) with two or more of the parties at war with each other; a region
+// with two or more owners, or whose owner is not at war with any party, cannot
+// be contested (dropped). On a successful open the key is removed from its
+// owner's `territory` (sole ownership is preserved — a contested key is in NO
+// territory) and from `unowned`, its `regionStats` entry is deleted, and a
+// `{ regionKey, parties }` entry (parties = resolved nation ids) is added to
+// `GameState.contested` (unique by `regionKey` — re-opening replaces it).
+// `resolve` removes the entry and releases the key to no man's land — UNLESS a
+// concurrent winning claim by one of the parties (allowed by the
+// territory-step guard in engine.ts) already re-owned it, in which case it
+// stays owned and its stats are kept.
+//
+// A still-contested key is NOT a valid normal-claim target: a plain `gain` on
+// it is dropped in the territory step (only a resolving party's claim
+// re-owns it). The layer NEVER moves a key into two territories (sole
+// ownership is sacrosanct), never touches borders directly (the key simply
+// leaves ownership), and is deterministic (no hidden randomness — the LLM
+// declares, the engine applies fixed rules).
+//
+// This is a DURABLE ability (unlike the turn-transient hybrid / disasters /
+// migration layers): it owns the `GameState.contested` field, and the user
+// payload carries the current contested list (only when non-empty).
+
+import { deriveNationStats } from '../../shared/protocol';
+import type { ContestedOps, ContestedRegion } from '../../shared/protocol';
+// The map-fill constants + tooltip label live in the shared protocol module
+// (like the sea-zone / no-man's-land constants); re-exported here so the
+// index / engine re-export surface is one consistent place.
+export {
+  CONTESTED_FILL,
+  CONTESTED_STROKE,
+  contestedTooltipLabel,
+} from '../../shared/protocol';
+import type { GameState } from '../../shared/types';
+import { atWar } from './apply-helpers';
+import { resolveNationRef, resolveRegionKey, str } from './shared';
+import type { Ability, AbilityCtx } from './types';
+
+/**
+ * (v0.44.0, #66) The SOLE owners of a region key in `next` (a key that is in no
+ * nation's `territory` yields `[]`; a corrupt 2+ owner key yields both). Pure.
+ */
+function currentOwners(next: GameState, key: string): string[] {
+  const owners: string[] = [];
+  for (const n of Object.values(next.nations)) {
+    if (n.territory.includes(key)) owners.push(n.id);
+  }
+  return owners;
+}
+
+/**
+ * (v0.44.0, #66) Resolve a region reference (a raw key or a human name) to a
+ * concrete region key: exact key first, then a unique case-insensitive name
+ * match. With no region-key manifest loaded (`validKeys` undefined) the raw
+ * string is accepted as the key (a name cannot be resolved without the
+ * manifest). Returns `null` when the reference is empty or unresolvable.
+ */
+function resolveKey(
+  ref: string,
+  validKeys?: ReadonlySet<string>,
+  nameOf?: (key: string) => string | undefined,
+): string | null {
+  const r = (ref ?? '').trim();
+  if (!r) return null;
+  if (!validKeys) return r; // no manifest: accept the raw key as-is
+  return resolveRegionKey(r, validKeys, nameOf ?? (() => undefined));
+}
+
+/**
+ * (v0.44.0, #66) Resolve a list of party references to distinct nation ids
+ * (id first, then a case-insensitive unique name), preserving first-appearance
+ * order. An unresolvable ref is dropped. Pure.
+ */
+function resolveParties(next: GameState, refs: string[]): string[] {
+  const out: string[] = [];
+  for (const ref of refs) {
+    const id = resolveNationRef(next, ref);
+    if (id && !out.includes(id)) out.push(id);
+  }
+  return out;
+}
+
+/**
+ * (v0.44.0, #66) Re-derive a nation's aggregate `stats` from its regions'
+ * per-region stats, with the same 0-region / no-entry guards as the engine's
+ * main recompute (a nation with no region, or none with a stats entry, keeps
+ * its directly-mutated `stats`). Used after a contested open strips a region
+ * from its owner. Never throws.
+ */
+function rederiveOwnerStats(
+  next: GameState,
+  ownerId: string,
+  geoOf?: (key: string) => { area: number; population: number } | undefined,
+): void {
+  const n = next.nations[ownerId];
+  if (!n) return;
+  if (n.territory.length > 0 && n.territory.some((k) => next.regionStats[k])) {
+    n.stats = deriveNationStats(n.territory, next.regionStats, geoOf);
+  }
+}
+
+/**
+ * (v0.44.0, #66) Validate the raw `contested` field of a turn into a safe
+ * {@link ContestedOps}. Defensive like the rest of the parser — never throws.
+ * `open`: each op needs a non-empty `regionKey` (capped at 120 chars) and
+ * TWO OR MORE non-empty `parties` refs (each capped at 200 chars); an op with
+ * a missing `regionKey` or fewer than two party refs is dropped. `resolve`:
+ * each entry is a non-empty region key (capped at 120 chars); empty / non-
+ * string entries are dropped. Both region keys and party refs are kept RAW
+ * here (like the hybrid / economy / industry refs) — whether a ref resolves to
+ * a real region / nation, and whether the war-linkage / ownership conditions
+ * hold, is checked at apply time (a ref that does not resolve, or a region that
+ * is not contestable, is dropped there). A missing / malformed top-level object
+ * yields `{ open: [], resolve: [] }`.
+ */
+export function validateContestedOps(raw: unknown): ContestedOps {
+  const out: ContestedOps = { open: [], resolve: [] };
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return out;
+  const o = raw as Record<string, unknown>;
+  if (Array.isArray(o.open)) {
+    for (const e of o.open) {
+      if (!e || typeof e !== 'object') continue;
+      const p = e as Record<string, unknown>;
+      const regionKey = str(p.regionKey, 120);
+      if (!regionKey) continue; // missing / empty region key: drop
+      if (!Array.isArray(p.parties)) continue; // missing / malformed parties: drop
+      const parties = p.parties
+        .map((x) => str(x, 200))
+        .filter((x): x is string => x !== null);
+      if (parties.length < 2) continue; // need at least two party refs
+      out.open.push({ regionKey, parties });
+    }
+  }
+  if (Array.isArray(o.resolve)) {
+    for (const e of o.resolve) {
+      const key = str(e, 120);
+      if (key) out.resolve.push(key);
+    }
+  }
+  return out;
+}
+
+/**
+ * (v0.44.0, #66) Apply the turn's contested-region ops to `next`, mutating in
+ * place and never throwing. Runs in the `ABILITIES` loop AFTER the territory
+ * step and the derived-stats recompute, and BEFORE markers / nationOps, so the
+ * owner / unowned / wars it inspects are all final for this turn.
+ *
+ *  (1) RESOLVE (first): each key in `resolve` that is currently contested is
+ *      removed from `next.contested` and released to no man's land (into
+ *      `unowned`, out of any territory, `regionStats` deleted) — UNLESS a
+ *      concurrent winning claim by one of the parties (the only claim the
+ *      territory step permits on a contested key) already re-owned it, in
+ *      which case it stays owned and keeps (or re-inits) its stats.
+ *  (2) OPEN: each op that resolves to a contestable region (a sole owner at
+ *      war with a party, or a no-man's-land region whose parties are at war
+ *      with each other) is moved out of ownership (the owner's territory /
+ *      `unowned`), its `regionStats` is deleted, and it is added to
+ *      `next.contested` (unique by `regionKey` — an open replaces a kept
+ *      entry for the same key). The stripped owner's derived stats are
+ *      re-derived.
+ *
+ * A contested key is never placed into two territories and is never left in
+ * `unowned` (the two states are mutually exclusive), so the sole-ownership
+ * invariant holds after every op.
+ */
+export function applyContested(next: GameState, ops: ContestedOps, ctx: AbilityCtx): void {
+  const validKeys = ctx.validRegionKeys;
+  const nameOf = ctx.regionNameOf;
+  const geoOf = ctx.geoOf;
+  const open = Array.isArray(ops?.open) ? ops.open : [];
+  const resolve = Array.isArray(ops?.resolve) ? ops.resolve : [];
+  const prevContested = Array.isArray(next.contested) ? next.contested : [];
+
+  // (1) RESOLVE first: rebuild the kept list, dropping resolved keys. A
+  // resolved key is released to no man's land unless a party re-owned it.
+  const resolveSet = new Set(resolve);
+  const kept: ContestedRegion[] = [];
+  for (const c of prevContested) {
+    if (!resolveSet.has(c.regionKey)) {
+      kept.push(c); // not resolved this turn: keep
+      continue;
+    }
+    const owners = currentOwners(next, c.regionKey);
+    if (owners.length === 1 && c.parties.includes(owners[0])) {
+      // A party re-owned it via a concurrent winning claim (the territory step
+      // allowed it): keep it owned, ensure it has stats (the claim re-inits an
+      // absent entry; the post-claim recompute already reflected the gain).
+      if (!next.regionStats[c.regionKey]) {
+        next.regionStats[c.regionKey] = { ...next.nations[owners[0]].stats };
+      }
+      continue; // stays owned — not re-added to `contested`
+    }
+    // Release to no man's land: out of any territory (defensive — a contested
+    // key is normally in none), into `unowned`, and its per-region stats leave.
+    for (const n of Object.values(next.nations)) {
+      const i = n.territory.indexOf(c.regionKey);
+      if (i !== -1) n.territory.splice(i, 1);
+    }
+    if (!next.unowned.includes(c.regionKey)) next.unowned.push(c.regionKey);
+    delete next.regionStats[c.regionKey];
+  }
+
+  // (2) OPEN: each op that resolves to a contestable region is moved out of
+  // ownership and added to the contested list (unique by region key).
+  const opened = new Map<string, string[]>(); // region key -> resolved party ids
+  for (const op of open) {
+    const key = resolveKey(op.regionKey, validKeys, nameOf);
+    if (!key) continue;
+    const parties = resolveParties(next, op.parties);
+    if (parties.length < 2) continue; // fewer than two distinct resolved parties
+
+    const owners = currentOwners(next, key);
+    let ok = false;
+    if (owners.length === 1) {
+      // Sole owner present: the owner must be at war with at least one party
+      // (the owner may itself be a party — atWar is false for a==b, so this
+      // checks the owner against the OTHER parties).
+      ok = parties.some((p) => atWar(next.wars, owners[0], p));
+    } else if (owners.length === 0 && next.unowned.includes(key)) {
+      // No owner + no man's land: two of the parties must be at war with
+      // each other.
+      for (let i = 0; i < parties.length && !ok; i++) {
+        for (let j = i + 1; j < parties.length; j++) {
+          if (atWar(next.wars, parties[i], parties[j])) {
+            ok = true;
+            break;
+          }
+        }
+      }
+    }
+    // Two or more owners (corrupt), an owner not at war with any party, or a
+    // not-in-unowned keyless region: never contestable (dropped).
+    if (!ok) continue;
+
+    if (owners.length === 1) {
+      const n = next.nations[owners[0]];
+      const i = n.territory.indexOf(key);
+      if (i !== -1) n.territory.splice(i, 1);
+      rederiveOwnerStats(next, owners[0], geoOf);
+    } else {
+      const i = next.unowned.indexOf(key);
+      if (i !== -1) next.unowned.splice(i, 1);
+    }
+    delete next.regionStats[key];
+    opened.set(key, parties);
+  }
+
+  // Rebuild `next.contested`: the kept (unresolved) entries plus the newly
+  // opened ones, unique by region key (an open replaces a kept entry for the
+  // same key; a resolve removed its key from `kept` above).
+  const final: ContestedRegion[] = [];
+  const seen = new Set<string>();
+  for (const c of kept) {
+    if (opened.has(c.regionKey)) continue; // replaced by a re-open this turn
+    if (seen.has(c.regionKey)) continue; // dedupe (should not happen, but safe)
+    seen.add(c.regionKey);
+    final.push(c);
+  }
+  for (const [key, parties] of opened) {
+    if (seen.has(key)) continue;
+    seen.add(key);
+    final.push({ regionKey: key, parties });
+  }
+  next.contested = final;
+}
+
+export const contested: Ability<'contested'> = {
+  field: 'contested',
+  default: () => ({ open: [], resolve: [] }),
+  validate: (raw) => validateContestedOps(raw),
+  apply: (state, data, ctx) => applyContested(state, data, ctx),
+  schemaLine: () =>
+    '  "contested": {"open":[{"regionKey":"<region key>","parties":["<nation 1>","<nation 2>"]}],"resolve":["<region key>"]},',
+  constraint: () =>
+    '- Contested regions ("contested") are WAR FRONTLINES: a region that no nation controls and that is not no man\'s land, contested by two or more nations at war. An "open" op ({"regionKey":"<key>","parties":["<a>","<b>"]}) makes a region a frontline — it leaves its owner\'s territory (or no-man\'s-land) and is contested: the region\'s sole owner must be at war with at least one of the parties, or (for a no-man\'s-land region) two of the parties must be at war with each other. A "resolve" op (["<key>"]) ends a frontline, releasing the region to no man\'s land — unless a party\'s concurrent claim re-owns it. A contested region is in NO nation\'s territory (never two) and is never no man\'s land while contested. The user message\'s "contested" field lists the current frontlines (region key + party names). Propose at most 1-2 contested-region changes per turn and narrate each one in "events" (a "military" event).',
+  isMeaningful: (data) => data.open.length > 0 || data.resolve.length > 0,
+  stateFields: ['contested'],
+  stub: () => ({ open: [], resolve: [] }),
+  // The user payload carries the current contested frontlines (region key +
+  // party NAMES, resolved from the stored ids) — but only when non-empty (a
+  // fresh / no-frontline world contributes nothing, like the turn-transient
+  // layers).
+  payload: (ctx) => {
+    if (!ctx.contested || ctx.contested.length === 0) return {};
+    return {
+      contested: ctx.contested.map((c) => ({
+        regionKey: c.regionKey,
+        parties: c.parties.map((id) => ctx.state.nations[id]?.name ?? id),
+      })),
+    };
+  },
+};

server/abilities/disasters.test.ts

@@ -0,0 +1,449 @@
+// Unit tests for the DISASTERS & PANDEMICS ability (v0.41.0, #63) — the
+// modular, turn-transient LLM-ability that applies a deterministic
+// (type, severity) stat dip to a nation or a single region. This is the
+// ability's own test file (the registry's cross-cutting guarantees — order,
+// distinct fields, the system/user goldens — are covered by
+// ./registry.test.ts). The stub never proposes a disaster, so the apply path
+// is exercised here, not by the e2e suite.
+
+import { describe, expect, it } from 'vitest';
+
+import type { AbilityCtx } from './types';
+import {
+  DISASTER_EFFECTS,
+  DISASTER_SEVERITIES,
+  DISASTER_TYPES,
+  applyDisasterEvent,
+  disasters,
+  isDisasterSeverity,
+  isDisasterType,
+  validateDisasterEvents,
+} from './disasters';
+
+import type { DisasterEvent, DisastersOps } from '../../shared/protocol';
+import type { GameState, Nation, NationStats, RegionStats } from '../../shared/types';
+
+// ---------------------------------------------------------------------------
+// Fixture helpers
+// ---------------------------------------------------------------------------
+
+/** Build a NationStats from the four canonical indices (military, economy, stability, population). */
+function NS(military: number, economy: number, stability: number, population: number): NationStats {
+  return { military, economy, stability, population };
+}
+
+/** Build a RegionStats from the four canonical indices. */
+function RS(military: number, economy: number, stability: number, population: number): RegionStats {
+  return { military, economy, stability, population };
+}
+
+/** A minimal nation: the given id/name/stats/region-key territory, neutral relations. */
+function mkNation(id: string, name: string, stats: NationStats, territory: string[]): Nation {
+  return { id, name, type: 'major', stats, territory, relations: {} };
+}
+
+/**
+ * A minimal GameState carrying the given nations (keyed by id) and per-region
+ * stats. Every other required field is at its fresh-game baseline, so a test
+ * can focus purely on the disaster dip.
+ */
+function mkState(
+  nations: Record<string, Nation>,
+  regionStats: Record<string, RegionStats>,
+): GameState {
+  return {
+    id: 'g1',
+    presetId: 'test',
+    presetTitle: 'Test',
+    playerNationId: Object.keys(nations)[0] ?? 'uk',
+    turn: 1,
+    date: '1939-09-01',
+    nations,
+    events: [],
+    pending: [],
+    version: 1,
+    unowned: [],
+    pendingNationOps: [],
+    markers: [],
+    regionStats,
+    wars: [],
+    trades: [],
+    embargoes: [],
+    industry: [],
+    // (v0.43.0, #65) no sea-zone control on a fresh state.
+    seaZones: [],
+    // (v0.44.0, #66) no contested regions on a fresh state.
+    contested: [],
+  };
+}
+
+/** A minimal AbilityCtx for the ability's `apply` (no manifests loaded). */
+function mkCtx(state: GameState, validRegionKeys?: ReadonlySet<string>): AbilityCtx {
+  return {
+    previous: state,
+    actingTurn: state.turn,
+    ...(validRegionKeys ? { validRegionKeys } : {}),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Type / severity constants + predicates
+// ---------------------------------------------------------------------------
+
+describe('DISASTER_TYPES / DISASTER_SEVERITIES', () => {
+  it('exposes exactly the seven types and three severities', () => {
+    expect([...DISASTER_TYPES]).toEqual([
+      'earthquake',
+      'flood',
+      'volcanic',
+      'wildfire',
+      'famine',
+      'plague',
+      'epidemic',
+    ]);
+    expect([...DISASTER_SEVERITIES]).toEqual(['minor', 'moderate', 'severe']);
+  });
+
+  it('every (type, severity) pair dips at least one stat, never population', () => {
+    for (const t of DISASTER_TYPES) {
+      for (const s of DISASTER_SEVERITIES) {
+        const dips = DISASTER_EFFECTS[t][s];
+        expect(dips).toBeDefined();
+        const keys = Object.keys(dips);
+        expect(keys.length).toBeGreaterThan(0);
+        expect(keys).not.toContain('population');
+        for (const k of keys) expect(dips[k as keyof typeof dips]).toBeLessThan(0);
+      }
+    }
+  });
+});
+
+describe('isDisasterType / isDisasterSeverity', () => {
+  it('accepts each known type and rejects unknown / non-strings', () => {
+    for (const t of DISASTER_TYPES) expect(isDisasterType(t)).toBe(true);
+    expect(isDisasterType('tsunami')).toBe(false);
+    expect(isDisasterType('Earthquake')).toBe(false); // case-sensitive
+    expect(isDisasterType('')).toBe(false);
+    expect(isDisasterType(42)).toBe(false);
+    expect(isDisasterType(null)).toBe(false);
+    expect(isDisasterType(undefined)).toBe(false);
+  });
+
+  it('accepts each known severity and rejects unknown / non-strings', () => {
+    for (const s of DISASTER_SEVERITIES) expect(isDisasterSeverity(s)).toBe(true);
+    expect(isDisasterSeverity('extreme')).toBe(false);
+    expect(isDisasterSeverity('Minor')).toBe(false); // case-sensitive
+    expect(isDisasterSeverity('')).toBe(false);
+    expect(isDisasterSeverity(3)).toBe(false);
+    expect(isDisasterSeverity(undefined)).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// validateDisasterEvents
+// ---------------------------------------------------------------------------
+
+describe('validateDisasterEvents', () => {
+  const valid: DisasterEvent = { type: 'earthquake', target: 'uk', severity: 'severe' };
+
+  it('accepts the { events: [...] } shape', () => {
+    expect(validateDisasterEvents({ events: [valid] })).toEqual([valid]);
+  });
+
+  it('accepts a bare array (lenient about the wrapper)', () => {
+    expect(validateDisasterEvents([valid])).toEqual([valid]);
+  });
+
+  it('drops an event with an unknown type, keeping the valid one', () => {
+    const out = validateDisasterEvents({
+      events: [
+        { type: 'tsunami', target: 'uk', severity: 'minor' },
+        valid,
+      ],
+    });
+    expect(out).toEqual([valid]);
+  });
+
+  it('drops an event with a missing type', () => {
+    const out = validateDisasterEvents({
+      events: [{ target: 'uk', severity: 'minor' }, valid],
+    });
+    expect(out).toEqual([valid]);
+  });
+
+  it('drops an event with an unknown severity, keeping the valid one', () => {
+    const out = validateDisasterEvents({
+      events: [
+        { type: 'plague', target: 'uk', severity: 'extreme' },
+        valid,
+      ],
+    });
+    expect(out).toEqual([valid]);
+  });
+
+  it('drops an event with a missing severity', () => {
+    const out = validateDisasterEvents({
+      events: [{ type: 'plague', target: 'uk' }, valid],
+    });
+    expect(out).toEqual([valid]);
+  });
+
+  it('drops an event with an empty / whitespace target', () => {
+    const out = validateDisasterEvents({
+      events: [
+        { type: 'plague', target: '   ', severity: 'minor' },
+        { type: 'plague', target: '', severity: 'minor' },
+        valid,
+      ],
+    });
+    expect(out).toEqual([valid]);
+  });
+
+  it('caps a non-empty detail at 300 chars and keeps a short one', () => {
+    const long = 'x'.repeat(500);
+    const out = validateDisasterEvents({
+      events: [
+        { type: 'plague', target: 'uk', severity: 'minor', detail: long },
+        { type: 'flood', target: 'de', severity: 'minor', detail: 'a short note' },
+      ],
+    });
+    expect(out).toEqual([
+      { type: 'plague', target: 'uk', severity: 'minor', detail: 'x'.repeat(300) },
+      { type: 'flood', target: 'de', severity: 'minor', detail: 'a short note' },
+    ]);
+  });
+
+  it('omits the detail key entirely when detail is empty / missing', () => {
+    const out = validateDisasterEvents({
+      events: [
+        { type: 'flood', target: 'uk', severity: 'minor', detail: '' },
+        { type: 'flood', target: 'de', severity: 'minor' },
+      ],
+    });
+    expect(out).toEqual([
+      { type: 'flood', target: 'uk', severity: 'minor' },
+      { type: 'flood', target: 'de', severity: 'minor' },
+    ]);
+    expect(out[0]).not.toHaveProperty('detail');
+  });
+
+  it('drops non-object event entries', () => {
+    const out = validateDisasterEvents({ events: ['not-an-object', 7, null, valid] });
+    expect(out).toEqual([valid]);
+  });
+
+  it('yields { events: [] } (here, []) for a missing / malformed top-level value', () => {
+    expect(validateDisasterEvents(undefined)).toEqual([]);
+    expect(validateDisasterEvents(null)).toEqual([]);
+    expect(validateDisasterEvents('nope')).toEqual([]);
+    expect(validateDisasterEvents(5)).toEqual([]);
+    expect(validateDisasterEvents({})).toEqual([]);
+    expect(validateDisasterEvents({ events: 'not-an-array' })).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// applyDisasterEvent — the deterministic dip
+// ---------------------------------------------------------------------------
+
+describe('applyDisasterEvent', () => {
+  it('a nation target: dips the nation AND every region it owns, then re-derives (identical values pass through)', () => {
+    // uk owns three identical regions; all stats identical → the re-derived
+    // aggregate equals the dipped values exactly.
+    const state = mkState(
+      { uk: mkNation('uk', 'UK', NS(50, 50, 50, 50), ['g1', 'g2', 'g3']) },
+      { g1: RS(50, 50, 50, 50), g2: RS(50, 50, 50, 50), g3: RS(50, 50, 50, 50) },
+    );
+    applyDisasterEvent(state, { type: 'earthquake', target: 'uk', severity: 'moderate' });
+    // earthquake moderate = stability -4, economy -4 (military / population untouched)
+    expect(state.nations.uk.stats).toEqual(NS(50, 46, 46, 50));
+    for (const k of ['g1', 'g2', 'g3']) expect(state.regionStats[k]).toEqual(RS(50, 46, 46, 50));
+  });
+
+  it('a region target: dips ONLY the named region (the sibling region is untouched)', () => {
+    // uk owns g1 and g2 (identical). Target the region key g1 → only g1 dips.
+    const state = mkState(
+      { uk: mkNation('uk', 'UK', NS(50, 50, 50, 50), ['g1', 'g2']) },
+      { g1: RS(50, 50, 50, 50), g2: RS(50, 50, 50, 50) },
+    );
+    applyDisasterEvent(state, { type: 'wildfire', target: 'g1', severity: 'severe' });
+    // wildfire severe = economy -7 only
+    expect(state.regionStats.g1).toEqual(RS(50, 43, 50, 50));
+    expect(state.regionStats.g2).toEqual(RS(50, 50, 50, 50)); // untouched
+    // re-derive (equal weights, min-biased median) → the nation takes the dipped value
+    expect(state.nations.uk.stats).toEqual(NS(50, 43, 50, 50));
+  });
+
+  it('a region target resolved by a validKeys-gated key hits its sole owner', () => {
+    const state = mkState(
+      { uk: mkNation('uk', 'UK', NS(50, 50, 50, 50), ['g1']) },
+      { g1: RS(50, 50, 50, 50) },
+    );
+    applyDisasterEvent(
+      state,
+      { type: 'famine', target: 'g1', severity: 'moderate' },
+      undefined,
+      new Set(['g1']),
+    );
+    // famine moderate = economy -4, stability -4
+    expect(state.regionStats.g1).toEqual(RS(50, 46, 46, 50));
+    expect(state.nations.uk.stats).toEqual(NS(50, 46, 46, 50));
+  });
+
+  it('clamps every dip at 0 (never negative)', () => {
+    // low stability + military; a severe plague (stability -9, military -6) floors both.
+    const state = mkState(
+      { uk: mkNation('uk', 'UK', NS(3, 50, 3, 50), ['g1']) },
+      { g1: RS(3, 50, 3, 50) },
+    );
+    applyDisasterEvent(state, { type: 'plague', target: 'uk', severity: 'severe' });
+    expect(state.nations.uk.stats).toEqual(NS(0, 50, 0, 50));
+    expect(state.regionStats.g1).toEqual(RS(0, 50, 0, 50));
+  });
+
+  it('a 0-owner region is untargetable (the event is dropped, nothing dips)', () => {
+    // 'x1' is owned by nobody; no validKeys supplied, so the owners check drops it.
+    const state = mkState(
+      { uk: mkNation('uk', 'UK', NS(50, 50, 50, 50), ['g1']) },
+      { g1: RS(50, 50, 50, 50) },
+    );
+    applyDisasterEvent(state, { type: 'plague', target: 'x1', severity: 'severe' });
+    expect(state.nations.uk.stats).toEqual(NS(50, 50, 50, 50)); // untouched
+    expect(state.regionStats.g1).toEqual(RS(50, 50, 50, 50));
+  });
+
+  it('a region with 2+ owners is untargetable (the event is dropped, neither dips)', () => {
+    // corrupt double-ownership of 'y1'
+    const state = mkState(
+      {
+        uk: mkNation('uk', 'UK', NS(50, 50, 50, 50), ['y1']),
+        de: mkNation('de', 'DE', NS(60, 60, 60, 60), ['y1']),
+      },
+      { y1: RS(50, 50, 50, 50) },
+    );
+    applyDisasterEvent(state, { type: 'plague', target: 'y1', severity: 'severe' });
+    expect(state.nations.uk.stats).toEqual(NS(50, 50, 50, 50)); // untouched
+    expect(state.nations.de.stats).toEqual(NS(60, 60, 60, 60)); // untouched
+  });
+
+  it('an unknown region key (gated by validKeys) is dropped', () => {
+    const state = mkState(
+      { uk: mkNation('uk', 'UK', NS(50, 50, 50, 50), ['g1']) },
+      { g1: RS(50, 50, 50, 50) },
+    );
+    // 'zzz' is not in the manifest → dropped before the owners check.
+    applyDisasterEvent(state, { type: 'plague', target: 'zzz', severity: 'severe' }, undefined, new Set(['g1']));
+    expect(state.nations.uk.stats).toEqual(NS(50, 50, 50, 50));
+  });
+
+  it('an unknown nation reference is dropped (no throw, no dip)', () => {
+    const state = mkState(
+      { uk: mkNation('uk', 'UK', NS(50, 50, 50, 50), ['g1']) },
+      { g1: RS(50, 50, 50, 50) },
+    );
+    applyDisasterEvent(state, { type: 'plague', target: 'ghost', severity: 'severe' });
+    expect(state.nations.uk.stats).toEqual(NS(50, 50, 50, 50));
+    expect(state.regionStats.g1).toEqual(RS(50, 50, 50, 50));
+  });
+
+  it('an ambiguous nation reference (two share the name) is dropped', () => {
+    const state = mkState(
+      {
+        a: mkNation('a', 'Same', NS(50, 50, 50, 50), ['g1']),
+        b: mkNation('b', 'Same', NS(70, 70, 70, 70), ['d1']),
+      },
+      { g1: RS(50, 50, 50, 50), d1: RS(70, 70, 70, 70) },
+    );
+    applyDisasterEvent(state, { type: 'plague', target: 'Same', severity: 'severe' });
+    expect(state.nations.a.stats).toEqual(NS(50, 50, 50, 50)); // untouched
+    expect(state.nations.b.stats).toEqual(NS(70, 70, 70, 70)); // untouched
+  });
+
+  it('resolves a nation by (case-insensitive) name, not just id', () => {
+    const state = mkState(
+      { uk: mkNation('uk', 'United Kingdom', NS(50, 50, 50, 50), ['g1']) },
+      { g1: RS(50, 50, 50, 50) },
+    );
+    applyDisasterEvent(state, { type: 'epidemic', target: 'united kingdom', severity: 'moderate' });
+    // epidemic moderate = stability -4, military -2
+    expect(state.nations.uk.stats).toEqual(NS(48, 50, 46, 50));
+    expect(state.regionStats.g1).toEqual(RS(48, 50, 46, 50));
+  });
+
+  it('a 0-region nation keeps its directly-dipped stats (no re-derive to zero)', () => {
+    const iso = mkNation('iso', 'Iso', NS(50, 50, 50, 50), []);
+    const state = mkState({ iso }, {});
+    applyDisasterEvent(state, { type: 'epidemic', target: 'iso', severity: 'moderate' });
+    // epidemic moderate = stability -4, military -2 — the direct dip persists
+    expect(state.nations.iso.stats).toEqual(NS(48, 50, 46, 50));
+    expect(state.regionStats).toEqual({});
+  });
+
+  it('a region with no regionStats entry is skipped (the nation still dips + re-derives from its other regions)', () => {
+    // uk owns g1 (has stats) and g2 (no entry). Target the nation → the dip
+    // mirrors to g1 only (g2 has no entry to dip); re-derive uses g1 alone.
+    const state = mkState(
+      { uk: mkNation('uk', 'UK', NS(50, 50, 50, 50), ['g1', 'g2']) },
+      { g1: RS(50, 50, 50, 50) },
+    );
+    applyDisasterEvent(state, { type: 'earthquake', target: 'uk', severity: 'moderate' });
+    expect(state.regionStats.g1).toEqual(RS(50, 46, 46, 50));
+    expect(state.regionStats).not.toHaveProperty('g2'); // never created
+    expect(state.nations.uk.stats).toEqual(NS(50, 46, 46, 50));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// The Ability object
+// ---------------------------------------------------------------------------
+
+describe('disasters (Ability)', () => {
+  it('owns the "disasters" field and declares NO durable state fields (turn-transient)', () => {
+    expect(disasters.field).toBe('disasters');
+    expect(disasters.stateFields).toBeUndefined();
+  });
+
+  it('default() and stub() are fresh, empty { events: [] } values', () => {
+    expect(disasters.default()).toEqual({ events: [] });
+    expect(disasters.stub()).toEqual({ events: [] });
+    // fresh on every call (never a shared mutable reference)
+    expect(disasters.default()).not.toBe(disasters.default());
+    expect(disasters.default().events).not.toBe(disasters.default().events);
+    expect(disasters.stub()).not.toBe(disasters.stub());
+  });
+
+  it('isMeaningful is true iff there is at least one event', () => {
+    expect(disasters.isMeaningful({ events: [] })).toBe(false);
+    expect(disasters.isMeaningful({ events: [{ type: 'plague', target: 'uk', severity: 'minor' }] })).toBe(
+      true,
+    );
+  });
+
+  it('payload() is always empty (the layer is turn-transient)', () => {
+    const state = mkState(
+      { uk: mkNation('uk', 'UK', NS(50, 50, 50, 50), ['g1']) },
+      { g1: RS(50, 50, 50, 50) },
+    );
+    expect(disasters.payload({ state })).toEqual({});
+  });
+
+  it('validate() wraps the low-level validator into the { events } field shape', () => {
+    const valid = { type: 'flood', target: 'uk', severity: 'minor' } as DisasterEvent;
+    expect(disasters.validate({ events: [valid] })).toEqual({ events: [valid] });
+    expect(disasters.validate(undefined)).toEqual({ events: [] });
+    expect(disasters.validate([valid])).toEqual({ events: [valid] }); // bare array leniency
+  });
+
+  it('apply() wires ctx.geoOf + ctx.validRegionKeys through to the dip', () => {
+    const state = mkState(
+      { uk: mkNation('uk', 'UK', NS(50, 50, 50, 50), ['g1']) },
+      { g1: RS(50, 50, 50, 50) },
+    );
+    const ctx = mkCtx(state, new Set(['g1']));
+    const data: DisastersOps = { events: [{ type: 'volcanic', target: 'g1', severity: 'moderate' }] };
+    disasters.apply(state, data, ctx);
+    // volcanic moderate = economy -4, stability -3
+    expect(state.regionStats.g1).toEqual(RS(50, 46, 47, 50));
+    expect(state.nations.uk.stats).toEqual(NS(50, 46, 47, 50));
+  });
+});

server/abilities/disasters.ts

@@ -0,0 +1,259 @@
+// The DISASTERS & PANDEMICS ability (v0.41.0, #63) as a modular LLM-ability
+// (v0.40.0, #67). Natural and man-made catastrophes — earthquakes, floods,
+// volcanic eruptions, wildfires, famines, plagues, and epidemics — hit a
+// nation or a single region each turn. Unlike most other abilities this one
+// is **turn-transient**: it owns NO `GameState` field (no durable list, no
+// `db.ts` change) — exactly like the hybrid layer. Each event carries a
+// `type` and a `severity`, and the engine applies a DETERMINISTIC stat dip
+// chosen from the `(type, severity)` lookup table below (no hidden
+// randomness — the LLM chooses the type and severity, the table decides the
+// magnitude). The dip lands on the target nation's `stats` (clamped 0–100)
+// AND on the target's regions (`regionStats` — the single named region when
+// the target was a region key, otherwise every region the target owns), and
+// the target's derived `stats` are re-derived afterwards (the same 0-region /
+// no-entry guards as hybrid / economy / industry, so a 0-region nation keeps
+// its directly-mutated value and the dip persists to the next turn). The
+// target is a nation (resolved by the shared `resolveNationRef`) or a region
+// key (which hits its SOLE owner); a key with 0 or 2+ owners is untargetable.
+// There is no acting-nation (`from`) field on a disaster — a catastrophe is
+// not an attack, so the hybrid's self-target drop does not apply. Malformed
+// events and unresolvable targets are dropped, never thrown.
+
+import { clampStat, deriveNationStats } from '../../shared/protocol';
+import type {
+  DisasterEvent,
+  DisasterSeverity,
+  DisasterType,
+} from '../../shared/protocol';
+import type { GameState, Nation, NationStats, StatKey } from '../../shared/types';
+import { resolveNationRef, str } from './shared';
+import type { Ability } from './types';
+
+/** The seven disaster types a turn can declare (v0.41.0, #63). */
+export const DISASTER_TYPES: readonly DisasterType[] = [
+  'earthquake',
+  'flood',
+  'volcanic',
+  'wildfire',
+  'famine',
+  'plague',
+  'epidemic',
+];
+
+/** The three severity levels a disaster event can carry (v0.41.0, #63). */
+export const DISASTER_SEVERITIES: readonly DisasterSeverity[] = ['minor', 'moderate', 'severe'];
+
+const VALID_DISASTER_TYPES = new Set<string>(DISASTER_TYPES);
+const VALID_SEVERITIES = new Set<string>(DISASTER_SEVERITIES);
+
+/** True when `t` is one of the seven known disaster types (v0.41.0, #63). */
+export function isDisasterType(t: unknown): t is DisasterType {
+  return typeof t === 'string' && VALID_DISASTER_TYPES.has(t);
+}
+
+/** True when `s` is one of the three known disaster severities (v0.41.0, #63). */
+export function isDisasterSeverity(s: unknown): s is DisasterSeverity {
+  return typeof s === 'string' && VALID_SEVERITIES.has(s);
+}
+
+/**
+ * (v0.41.0, #63) The DETERMINISTIC per-`(type, severity)` stat dip of a
+ * disaster event. Each pair maps to a small set of signed (negative) stat
+ * deltas: no hidden randomness — the LLM picks the type and severity, the
+ * table decides the magnitude. Population is never touched (a disaster hurts
+ * military / economy / stability, never the head-count). Every (type,
+ * severity) combination dips at least one stat (none is purely
+ * informational).
+ */
+export const DISASTER_EFFECTS: Record<DisasterType, Record<DisasterSeverity, Partial<Record<StatKey, number>>>> = {
+  earthquake: {
+    minor: { stability: -2, economy: -2 },
+    moderate: { stability: -4, economy: -4 },
+    severe: { stability: -7, economy: -7 },
+  },
+  flood: {
+    minor: { economy: -2, stability: -1 },
+    moderate: { economy: -3, stability: -2 },
+    severe: { economy: -6, stability: -4 },
+  },
+  volcanic: {
+    minor: { economy: -2, stability: -2 },
+    moderate: { economy: -4, stability: -3 },
+    severe: { economy: -7, stability: -6 },
+  },
+  wildfire: {
+    minor: { economy: -2 },
+    moderate: { economy: -4 },
+    severe: { economy: -7 },
+  },
+  famine: {
+    minor: { economy: -2, stability: -2 },
+    moderate: { economy: -4, stability: -4 },
+    severe: { economy: -7, stability: -7 },
+  },
+  plague: {
+    minor: { stability: -3, military: -2 },
+    moderate: { stability: -5, military: -3 },
+    severe: { stability: -9, military: -6 },
+  },
+  epidemic: {
+    minor: { stability: -2, military: -1 },
+    moderate: { stability: -4, military: -2 },
+    severe: { stability: -7, military: -4 },
+  },
+};
+
+/**
+ * (v0.41.0, #63) Validate the raw `disasters` field of a turn into a safe
+ * list of {@link DisasterEvent}s. Defensive like the rest of the parser — never throws.
+ * The raw value may be the object `{ events: [...] }` (the TurnResult shape)
+ * or a bare array (be lenient about either). Each event needs a known `type`
+ * (one of {@link DISASTER_TYPES}), a known `severity` (one of
+ * {@link DISASTER_SEVERITIES}), and a non-empty `target` (a nation id/name or
+ * a region key, capped at 200 chars); a non-empty `detail` is capped at 300
+ * chars. An event with an unknown / missing `type`, an unknown / missing
+ * `severity`, or an empty `target` is dropped. Resolution of `target` to a
+ * concrete nation (or a region's sole owner) happens at apply time
+ * (`applyDisasterEvent`), not here. A missing / malformed top-level value
+ * yields `{ events: [] }`.
+ */
+export function validateDisasterEvents(raw: unknown): DisasterEvent[] {
+  let list: unknown[] | null = null;
+  if (Array.isArray(raw)) {
+    list = raw;
+  } else if (raw && typeof raw === 'object') {
+    const inner = (raw as Record<string, unknown>).events;
+    if (Array.isArray(inner)) list = inner;
+  }
+  if (!list) return [];
+  const out: DisasterEvent[] = [];
+  for (const e of list) {
+    if (!e || typeof e !== 'object') continue;
+    const o = e as Record<string, unknown>;
+    if (!isDisasterType(o.type)) continue; // unknown / missing type: drop
+    if (!isDisasterSeverity(o.severity)) continue; // unknown / missing severity: drop
+    const target = str(o.target, 200);
+    if (!target) continue; // empty / missing target: drop
+    const detail = str(o.detail, 300);
+    out.push({
+      type: o.type,
+      target,
+      severity: o.severity,
+      ...(detail ? { detail } : {}),
+    });
+  }
+  return out;
+}
+
+/**
+ * (v0.41.0, #63) Resolve a disaster event's `target` (a nation id/name OR a
+ * region key) to the concrete nation it affects. A nation ref resolves via
+ * {@link resolveNationRef}; a region key resolves to its SOLE owner (a region
+ * with zero or 2+ owners can't be a valid target). Returns the affected
+ * nation plus the specific region key (when the target was a region) so the
+ * dip can land on just that region's entry. `validKeys` (when supplied)
+ * gates the region-key path; a ref that is neither a known nation nor a
+ * valid region key returns `null`. Pure; never throws.
+ *
+ * NOTE: there is no acting-nation (`from`) field on a disaster — a
+ * catastrophe is not an attack, so (unlike the hybrid layer) a self-target
+ * drop does NOT apply: an earthquake can hit the nation it is declared
+ * against.
+ */
+function resolveDisasterTarget(
+  state: GameState,
+  target: string,
+  validKeys?: ReadonlySet<string>,
+): { nation: Nation; regionKey?: string } | null {
+  const id = resolveNationRef(state, target);
+  if (id !== null) {
+    const n = state.nations[id];
+    return n ? { nation: n } : null;
+  }
+  const key = (target ?? '').trim();
+  if (!key) return null;
+  if (validKeys && !validKeys.has(key)) return null; // unknown region key
+  const owners = Object.values(state.nations).filter((n) => n.territory.includes(key));
+  if (owners.length !== 1) return null; // 0 or 2+ owners: not a targetable region
+  return { nation: owners[0], regionKey: key };
+}
+
+/** Apply each signed dip in `dips` to a stats record in place (clamped). */
+function applyDips(stats: NationStats, dips: Partial<Record<StatKey, number>>): void {
+  (Object.keys(dips) as StatKey[]).forEach((k) => {
+    const d = dips[k];
+    if (typeof d === 'number') stats[k] = clampStat(stats[k] + d);
+  });
+}
+
+/**
+ * (v0.41.0, #63) Apply ONE disaster event to the (cloned) `next` state,
+ * mutating it in place and never throwing. Resolution order:
+ *   1. `target` must resolve to a concrete nation (a nation ref, or a region
+ *      key's sole owner); an unresolvable target (unknown / ambiguous ref, a
+ *      region with 0 or 2+ owners, or an unknown region key) drops the event.
+ * Then the deterministic `(type, severity)` dip from {@link DISASTER_EFFECTS}
+ * is applied:
+ *   - the target nation's `stats` is dipped on each affected stat (clamped
+ *     0–100);
+ *   - the dip is mirrored to the target's regions — the single named region
+ *     when the target was a region key, otherwise every region the target
+ *     owns (regions with no `regionStats` entry are skipped);
+ *   - the target nation's derived `stats` are re-derived afterwards (the
+ *     same 0-region / no-entry guards as the main recompute, so a 0-region
+ *     nation keeps its directly-mutated value and a dip persists).
+ * A disaster never moves territory (sole ownership is untouched) and never
+ * touches `population`.
+ */
+export function applyDisasterEvent(
+  next: GameState,
+  ev: DisasterEvent,
+  geoOf?: (key: string) => { area: number; population: number } | undefined,
+  validKeys?: ReadonlySet<string>,
+): void {
+  const target = resolveDisasterTarget(next, ev.target, validKeys);
+  if (target === null) return; // unresolvable target: drop
+  const dips = DISASTER_EFFECTS[ev.type][ev.severity];
+  if (!dips) return; // defensive: unknown (type, severity) pair
+  applyDips(target.nation.stats, dips);
+  if (target.regionKey !== undefined) {
+    const rs = next.regionStats[target.regionKey];
+    if (rs) applyDips(rs, dips);
+  } else {
+    for (const key of target.nation.territory) {
+      const rs = next.regionStats[key];
+      if (!rs) continue; // a key with no entry is skipped
+      applyDips(rs, dips);
+    }
+  }
+  // Re-derive the target nation's aggregate stats so the dip persists (the
+  // main recompute ran earlier this turn; without this the dip would be
+  // washed out next turn). Same 0-region / no-entry guards as hybrid /
+  // economy: a nation with no region stats entry keeps its directly-mutated
+  // `stats`.
+  if (target.nation.territory.length > 0 && target.nation.territory.some((k) => next.regionStats[k])) {
+    target.nation.stats = deriveNationStats(target.nation.territory, next.regionStats, geoOf);
+  }
+}
+
+export const disasters: Ability<'disasters'> = {
+  field: 'disasters',
+  default: () => ({ events: [] }),
+  // The low-level validator returns a bare list; the field's shape is the
+  // `{ events }` object (mirrors the historical TurnResult shape).
+  validate: (raw) => ({ events: validateDisasterEvents(raw) }),
+  apply: (state, data, ctx) => {
+    for (const ev of data.events) {
+      applyDisasterEvent(state, ev, ctx.geoOf, ctx.validRegionKeys);
+    }
+  },
+  schemaLine: () =>
+    '  "disasters": {"events":[{"type":"<earthquake|flood|volcanic|wildfire|famine|plague|epidemic>","target":"<nation id or name, or region key>","severity":"<minor|moderate|severe>","detail":"<short detail>"}]},',
+  constraint: () =>
+    '- Disasters & pandemics ("disasters.events") are natural and man-made catastrophes — earthquakes, floods, volcanic eruptions, wildfires, famines, plagues, and epidemics — that hit a nation or a single region this turn. Each event names a "target" (a nation id / name, or a region key that hits that region\'s SOLE owner — a region with 0 or 2+ owners can\'t be hit) and a "severity" (minor / moderate / severe); the engine applies a small, DETERMINISTIC stat dip from the (type, severity) table (a severe plague is the hardest hit; none of them touch population, and none move borders — sole ownership is untouched). There is NO memory of past disasters (the layer is turn-transient): a plague or epidemic that persists is simply RE-DECLARED each turn it continues, with a fresh "severity". Propose at most 1-2 events per turn and narrate each one in "events" (a "disaster" event).',
+  isMeaningful: (data) => data.events.length > 0,
+  stub: () => ({ events: [] }),
+  // The layer is turn-transient — it contributes nothing to the user payload
+  // (no durable state to show the model), so the payload is always empty.
+  payload: () => ({}),
+};

server/abilities/economy.ts

@@ -0,0 +1,229 @@
+// The ECONOMY (trade & embargo) ability (v0.35.0, #58) as a modular
+// LLM-ability (v0.40.0, #67). A bilateral trade gives BOTH parties a small,
+// deterministic economy gain every committed turn; a unilateral embargo
+// lowers only the TARGET's economy every committed turn. Ops are idempotent
+// (a no-`lift` op declares / imposes; `lift: true` ends / lifts; refs
+// resolved against the real state at apply time — unknown / ambiguous /
+// self-pairing ops are dropped, never thrown). Every committed turn the FULL
+// active lists apply their effect (clamped, mirrored to each affected
+// nation's regions, re-derived), and any trade/embargo between nations on
+// opposite sides of an active war is auto-suspended (a war severs the
+// economic link). All bodies are moved VERBATIM from the pre-refactor
+// engine.ts.
+
+import { clampStat, deriveNationStats } from '../../shared/protocol';
+import type { GameState } from '../../shared/types';
+import type { EconomyEmbargoOp, EconomyOps, EconomyTradeOp } from '../../shared/protocol';
+import { resolveNationRef, str } from './shared';
+import { activeWarPairs } from './apply-helpers';
+import type { Ability } from './types';
+
+/**
+ * (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.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));
+}
+
+export const economy: Ability<'economy'> = {
+  field: 'economy',
+  default: () => ({ trade: [], embargo: [] }),
+  validate: (raw) => validateEconomyOps(raw),
+  apply: (state, data, ctx) => {
+    // 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(state, data);
+    suspendEconomyOnWar(state);
+    applyEconomyEffects(state, ctx.geoOf);
+  },
+  schemaLine: () =>
+    '  "economy": {"trade":[{"a":"<nationId>","b":"<nationId>","lift":<true|false>}],"embargo":[{"from":"<nationId>","target":"<nationId>","lift":<true|false>}]},',
+  constraint: () =>
+    '- 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.',
+  isMeaningful: (data) => data.trade.length > 0 || data.embargo.length > 0,
+  stateFields: ['trades', 'embargoes'],
+  stub: () => ({ trade: [], embargo: [] }),
+  payload: (ctx) => {
+    const out: Record<string, unknown> = {};
+    if (ctx.trades !== undefined) out.trades = ctx.trades;
+    if (ctx.embargoes !== undefined) out.embargoes = ctx.embargoes;
+    return out;
+  },
+};

server/abilities/goldens/system-no-tool.txt

@@ -0,0 +1,81 @@
+WORLD: World War II — 1939-09-01
+It is early September 1939. Germany has just invaded Poland, and Britain and France have declared war. Europe stands on the edge of the largest conflict the world has ever seen. The Axis powers — Germany, Italy, and Japan — are pressing their advantage across Europe and the Pacific, while the Allies — Britain, France, the Soviet Union, and a still-neutral but industrially immense United States — are marshalling their strength.
+
+The balance of power is delicate. Germany's army is the most battle-hardened force on the continent, but its resources are finite and its flanks exposed. Britain commands the seas but is an island nation. The Soviet Union has a vast army and deep territory but a fragile industrial base. The United States has unmatched economic power but is geographically isolated and politically divided over entry into the war.
+
+You are the head of one of these nations. Every decision you make — military, economic, or diplomatic — ripples across the world and reshapes the map, the alliances, and the fate of hundreds of millions.
+
+SIMULATION RULES
+- Serious, historically-plausible tone; write like a war correspondent and a policy analyst combined.
+- Prefer gradual change: 1-4 meaningful events per turn, never a single decisive world-ending event.
+- Respect existing borders unless a war is declared or a decisive military shift occurs.
+- No single nation may instantly dominate the world; power shifts are incremental.
+- Respect the player's chosen nation's resources, manpower, and geography.
+- Diplomacy can shift relations over time but rarely reverses a declared war in one turn.
+- Keep stat values (military, economy, stability, population) between 0 and 100.
+
+You are the world simulator. You advance the shared world state for ALL nations given the current state and the player's move.
+Respond with ONLY a valid JSON object of exactly this shape. No prose, no commentary, no markdown fences, no trailing commas:
+{
+  "date": "YYYY-MM-DD (a few days after the current date)",
+  "events": [
+    {"nation":"<nationId>","type":"<military|diplomatic|economic|political|social|disaster|scientific|cultural>","title":"short headline","text":"1-3 sentences of narrative","outcome":"<success|failure|partial|neutral>"}
+  ],
+  "stateChanges": [{"nation":"<nationId>","stat":"<military|economy|stability|population>","op":"<set|add>","value":<0-100>}],
+  "regionChanges": [{"region":"<region key or name>","stat":"<military|economy|stability|population>","op":"<set|add>","value":<0-100>}],
+  "relations": [{"a":"<nationId>","b":"<nationId>","set":"<ally|neutral|rival|hostile|war>"}],
+  "territoryChanges": [{"nation":"<nationId>","gain":["<region key>"],"lose":["<region key>"]}],
+  "unowned": ["<region key>"],
+  "nationOps": [
+    {"kind":"rename","nationRef":"<nation id or name>","to":"<new name>"},
+    {"kind":"split","nationRef":"<nation id or name>","parts":[{"name":"<new name>","territory":["<region key>"]}]}
+    {"kind":"merge","nationRefs":["<id>","<id>"],"survivingRef":"<id of the surviving nation>","into":"<new name>"}
+  ],
+  "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>}]},
+  "industry": {"projects":[{"regionKey":"<region key>","type":"<oil|iron|food|industry>"}]},
+  "nuclear": {"arm":["<nation id or name>"],"strikes":[{"from":"<nuclear-capable nation id or name>","target":"<nation id or name, or region key>"}]},
+  "leaders": {"changes":[{"target":"<nation id or name>","name":"<new leader name>","cause":"<assassination|death|appointed>"}]},
+  "ideology": {"changes":[{"target":"<nation id or name>","to":"<new form of government>"}]},
+  "disasters": {"events":[{"type":"<earthquake|flood|volcanic|wildfire|famine|plague|epidemic>","target":"<nation id or name, or region key>","severity":"<minor|moderate|severe>","detail":"<short detail>"}]},
+  "migration": {"ops":[{"kind":"<migration|refugees|diaspora|exodus>","from":"<nation id or name>","to":"<nation id or name>","scale":"<small|moderate|large>","detail":"<short detail>"}]},
+  "sea": {"control":[{"zone":"<seaZoneId>","by":"<nation id or name>"}]},
+  "contested": {"open":[{"regionKey":"<region key>","parties":["<nation 1>","<nation 2>"]}],"resolve":["<region key>"]},
+  "markers": {"add":[{"type":"<city|factory|army|port|capital|fleet|rocket|gathering>","name":"<short name>","regionKey":"<region key>"}],"remove":["<marker id>"]}
+}
+
+HOW THE FOUR 0-100 STATS DRIVE OUTCOMES (military / economy / stability / population)
+- MILITARY (the engine ENFORCES this rule, so weigh it before proposing a conquest): a nation can take a region by force only when its military is at least the defender's military minus 15 — equal, or within 15, is enough to win, but an attacker MORE than 15 below the defender is REPELLED and the region stays with its owner (a "repelled" event is recorded automatically; you cannot capture such a region that turn). Re-claiming an unowned (no man's land) region is never blocked this way.
+- STABILITY (you drive this, no hard gate): a nation whose stability is below 30 AND that has a "gathering" marker on one of its regions can suffer a NON-military takeover — a coup, revolution or faction seizure of power. Narrate it with a political or social event (outcome "success"), a "gathering" marker on the region, and stateChanges that shock its stability and economy downward.
+- ECONOMY (you drive this, no hard gate): economy drives long-term development — a strong economy lets a nation's other stats trend UP over time (small per-turn gains via stateChanges / regionChanges), while a weak economy lets them DECAY. Reflect that trend in the stat changes you make and narrate it.
+
+HARD CONSTRAINTS
+- Use only nation ids and region keys that exist in the provided state.
+- A region key identifies one sub-region; the "regions" table in the user message maps each key to "<region name> (<parent country ISO_A3>)". Use those keys in territoryChanges and unowned.
+- List in "unowned" only region keys that a nation currently owns, and narrate each release in "events".
+- Map markers ("markers") are named points on the map, anchored to a region key you own or that the narrative justifies: a capital (a nation's main seat of power — at most one per nation), major cities, factory complexes, army deployments, ports, fleet concentrations, rocket launch sites, or a gathering (a large political/social mass event that can enable a non-military takeover). Use only region keys from the "regions" table, keep each name under 40 characters, and place at most a handful of new markers per turn — only where the narrative justifies it. List a marker id from the user message's "markers" field in "remove" when it ceases to exist (a city razed, an army dispersed, a site destroyed).
+- Nation-management ops ("nationOps") are PROPOSALS: they only take effect if the player confirms them afterwards. Propose at most 1-2 per turn, only when the narrative justifies it, and narrate each one in "events".
+- Rename: add {"kind":"rename","nationRef":"<nation id or name>","to":"<new name>"} for a revolution, regime change or reunification that changes a nation's name.
+- Split: add {"kind":"split","nationRef":"<nation id or name>","parts":[{"name":"<new name>","territory":["<region key>"]}, ...]} when a state breaks up (dissolution, secession). Use at least 2 parts and assign each of the nation's region keys to at most one part — any key you leave unassigned goes to the first part.
+- Merge: add {"kind":"merge","nationRefs":["<id or name>","<id or name>"],"survivingRef":"<id or name of the surviving nation>","into":"<new name>"} when states reunify or one is absorbed. Use at least 2 input nations and "survivingRef" must name one of them — the survivor keeps its id and its stats.
+- 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.
+- Industry ("industry") is the per-resource development lever: each project is a building in one region you (or a nation) controls — {"regionKey":"<region key>","type":"<oil|iron|food|industry>"} (an oil facility, an iron mine, a food operation, or a factory). Every committed turn each active project gives its region's owner a small, deterministic economy gain, the bigger the region's industry profile (see the "resources" field). A region holds at most one project — do not re-declare one on a region that already has one (the user message's "industry" field lists what is already built). Propose at most 1-2 new projects per turn and narrate each one in "events".
+- Nuclear / WMD ("nuclear"): a nation is "nuclear-capable" when its "nuclear" flag is true or it currently owns a "rocket" marker. "arm" names (by id or name) nations to grant the "nuclear" flag — idempotent (already-armed nations are unchanged); a newly armed nation is capable this same turn. "strikes" is a list of "NuclearStrike" objects, each "{from, target}" — "from" is the striking nation (must be nuclear-capable and never itself) and "target" is either a nation (its nation collapses: economy -40, military -50, stability -40; every active war the target fights ends by capitulation and the "war" relations it caused downgrade to "hostile") or a region key (that region is released to no man's land, its regionStats entry deleted, and its sole owner collapses the same way — a region with 0 or 2+ owners, or one the striker itself owns, is dropped). If the struck nation (or the struck region's owner) is itself nuclear-capable, a "MAD" retaliation is applied: it strikes the striker back for half the collapse, and the two nations' relations are forced to "hostile". At most one strike per turn; always narrate a strike (and a retaliation, if any) in "events".
+- Leaders ("leaders") name each nation's current head of state and change it. Each change is {"target":"<nation id or name>","name":"<new leader name>","cause":"<assassination|death|appointed>"}: "assassination" kills the current leader (a dramatic, destabilizing blow — a −15 stability dip, a "military" event) and is only valid when the target already has a leader; "death" is a natural-causes succession (a quieter −3 dip, a "political" event), also only valid for a nation that has a leader; "appointed" sets (or creates) a leader and is always valid (a neutral 0 effect, a "political" event). Propose at most 1-2 changes per turn and narrate each one in "events". This is the HEAVY leader lever — use the lighter "hybrid" {"type":"assassinate"} op (a −5 stability dip, no leader replacement) for a mere hit on a leader or region without changing who is in charge. The user message's "nations" field lists each nation's current "leader" (omitted when a nation has none).
+- Ideology ("ideology") is each nation's form of government — a free-form label such as "democracy", "fascism", or "military junta" — that can shift through a coup, a revolution, a reform, or a constitutional change. Each change is {"target":"<nation id or name>","to":"<new form of government>"}: the engine sets the nation's ideology, applies a small, deterministic stability dip (−5 — a regime shift always unsettles a nation), and narrates it with a "political" event. It is a third axis, distinct from a takeover (which RENAMES the nation) and from a leader change (who is in charge): the nation keeps its id, name, territory, relations, and leader — only its form of government and its stability move. Similar forms of government are a SOFT, prompt-level compatibility nudge only (nations with alike ideologies tend to ally and trade; very opposed ones tend to clash) — there is no engine gate behind it. Propose at most 1-2 changes per turn and narrate each one in "events". The user message's "nations" field lists each nation's current "ideology" (omitted when a nation has none).
+- Disasters & pandemics ("disasters.events") are natural and man-made catastrophes — earthquakes, floods, volcanic eruptions, wildfires, famines, plagues, and epidemics — that hit a nation or a single region this turn. Each event names a "target" (a nation id / name, or a region key that hits that region's SOLE owner — a region with 0 or 2+ owners can't be hit) and a "severity" (minor / moderate / severe); the engine applies a small, DETERMINISTIC stat dip from the (type, severity) table (a severe plague is the hardest hit; none of them touch population, and none move borders — sole ownership is untouched). There is NO memory of past disasters (the layer is turn-transient): a plague or epidemic that persists is simply RE-DECLARED each turn it continues, with a fresh "severity". Propose at most 1-2 events per turn and narrate each one in "events" (a "disaster" event).
+- Migration & refugees ("migration.ops") are people moving between nations this turn: a "kind" ("migration", "refugees", "diaspora", or "exodus"), a "from" (the source nation — id or name), a "to" (the destination nation — required for every kind except "exodus", which has no destination), and a "scale" (small / moderate / large). The engine applies a DETERMINISTIC effect (no hidden randomness): the source LOSES a small amount of population and economy, the destination GAINS a small amount of population and economy (a "large" influx additionally strains the destination's stability by 2), and the from↔to relation moves one step toward the positive end of the ally/neutral/rival/hostile ladder — capped at "ally" for "refugees" (hosting refugees builds the strongest goodwill), capped at "neutral" for "migration"/"diaspora" (milder ties), and not at all for "exodus"; the nudge never creates or escalates a "war" (a warring pair is left untouched). The layer is turn-transient (no memory): a continuing flow is simply RE-DECLARED each turn it persists. It never moves borders — sole ownership is untouched. Propose at most 1-2 per turn and narrate each one in "events" (a "social" or "diplomatic" event).
+- Sea control ("sea") is the naval layer, fully parallel to but INDEPENDENT of land: each of the 12 fixed sea zones — "north-atlantic" (North Atlantic), "south-atlantic" (South Atlantic), "pacific" (Pacific Ocean), "indian" (Indian Ocean), "mediterranean" (Mediterranean Sea), "north-sea" (North Sea), "baltic" (Baltic Sea), "arctic" (Arctic Ocean), "black-sea" (Black Sea), "gulf-mexico" (Gulf of Mexico), "red-sea" (Red Sea), "sargasso" (Sargasso Sea) — is under the SOLE control of at most one nation. A control op ({"zone":"<id>","by":"<nation>"}) sets or replaces that zone's controller (the user message's "seaZones" field lists who controls what now); if two or more ops this turn claim the SAME zone for DIFFERENT nations, the zone is CONTESTED and the higher current "military" wins (a tie goes to the earlier-listed op). Every committed turn each zone's controller earns a small deterministic +1 military and +1 economy. Sea control NEVER moves land (no territory changes) — it is a parallel track. Propose at most 1-2 claims per turn and narrate each one in "events" (a "military" or "diplomatic" event).
+- Contested regions ("contested") are WAR FRONTLINES: a region that no nation controls and that is not no man's land, contested by two or more nations at war. An "open" op ({"regionKey":"<key>","parties":["<a>","<b>"]}) makes a region a frontline — it leaves its owner's territory (or no-man's-land) and is contested: the region's sole owner must be at war with at least one of the parties, or (for a no-man's-land region) two of the parties must be at war with each other. A "resolve" op (["<key>"]) ends a frontline, releasing the region to no man's land — unless a party's concurrent claim re-owns it. A contested region is in NO nation's territory (never two) and is never no man's land while contested. The user message's "contested" field lists the current frontlines (region key + party names). Propose at most 1-2 contested-region changes per turn and narrate each one in "events" (a "military" event).
+- 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.
+- Per-region stat changes ("regionChanges") target ONE region's stats directly, by its region key (preferred) or name, and make that region differ from the rest of its nation (a garrisoned border province, a bombed-out city, an industrial heartland). A nation-wide "stateChanges" entry applies to ALL of a nation's regions; a "regionChanges" entry overrides it for that one region. The user message's "playerRegionStats" lists the player's own regions' current stats; use region keys from the "regions" table.
+- Only change borders when war or a decisive political shift justifies it.
+- A region key has at most one owner at all times — never assign a key to two nations. After a war or cataclysm a region may be left unowned ("no man's land"): list its key in "unowned" and narrate the cause in "events"; it stays unowned (grey on the map) until a nation re-claims it with a "gain". The "unowned" field of the user message lists the regions currently in no man's land.
+- If a field is not relevant this turn, set it to an empty array.

server/abilities/goldens/system-tool.txt

@@ -0,0 +1,82 @@
+WORLD: World War II — 1939-09-01
+It is early September 1939. Germany has just invaded Poland, and Britain and France have declared war. Europe stands on the edge of the largest conflict the world has ever seen. The Axis powers — Germany, Italy, and Japan — are pressing their advantage across Europe and the Pacific, while the Allies — Britain, France, the Soviet Union, and a still-neutral but industrially immense United States — are marshalling their strength.
+
+The balance of power is delicate. Germany's army is the most battle-hardened force on the continent, but its resources are finite and its flanks exposed. Britain commands the seas but is an island nation. The Soviet Union has a vast army and deep territory but a fragile industrial base. The United States has unmatched economic power but is geographically isolated and politically divided over entry into the war.
+
+You are the head of one of these nations. Every decision you make — military, economic, or diplomatic — ripples across the world and reshapes the map, the alliances, and the fate of hundreds of millions.
+
+SIMULATION RULES
+- Serious, historically-plausible tone; write like a war correspondent and a policy analyst combined.
+- Prefer gradual change: 1-4 meaningful events per turn, never a single decisive world-ending event.
+- Respect existing borders unless a war is declared or a decisive military shift occurs.
+- No single nation may instantly dominate the world; power shifts are incremental.
+- Respect the player's chosen nation's resources, manpower, and geography.
+- Diplomacy can shift relations over time but rarely reverses a declared war in one turn.
+- Keep stat values (military, economy, stability, population) between 0 and 100.
+
+You are the world simulator. You advance the shared world state for ALL nations given the current state and the player's move.
+You have a getNeighbours tool: given region keys it returns the region keys that border them. You may call it (a few times) to verify land borders before deciding territory transfers. Once done, respond with ONLY a valid JSON object of exactly this shape. No prose, no commentary, no markdown fences, no trailing commas:
+{
+  "date": "YYYY-MM-DD (a few days after the current date)",
+  "events": [
+    {"nation":"<nationId>","type":"<military|diplomatic|economic|political|social|disaster|scientific|cultural>","title":"short headline","text":"1-3 sentences of narrative","outcome":"<success|failure|partial|neutral>"}
+  ],
+  "stateChanges": [{"nation":"<nationId>","stat":"<military|economy|stability|population>","op":"<set|add>","value":<0-100>}],
+  "regionChanges": [{"region":"<region key or name>","stat":"<military|economy|stability|population>","op":"<set|add>","value":<0-100>}],
+  "relations": [{"a":"<nationId>","b":"<nationId>","set":"<ally|neutral|rival|hostile|war>"}],
+  "territoryChanges": [{"nation":"<nationId>","gain":["<region key>"],"lose":["<region key>"]}],
+  "unowned": ["<region key>"],
+  "nationOps": [
+    {"kind":"rename","nationRef":"<nation id or name>","to":"<new name>"},
+    {"kind":"split","nationRef":"<nation id or name>","parts":[{"name":"<new name>","territory":["<region key>"]}]}
+    {"kind":"merge","nationRefs":["<id>","<id>"],"survivingRef":"<id of the surviving nation>","into":"<new name>"}
+  ],
+  "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>}]},
+  "industry": {"projects":[{"regionKey":"<region key>","type":"<oil|iron|food|industry>"}]},
+  "nuclear": {"arm":["<nation id or name>"],"strikes":[{"from":"<nuclear-capable nation id or name>","target":"<nation id or name, or region key>"}]},
+  "leaders": {"changes":[{"target":"<nation id or name>","name":"<new leader name>","cause":"<assassination|death|appointed>"}]},
+  "ideology": {"changes":[{"target":"<nation id or name>","to":"<new form of government>"}]},
+  "disasters": {"events":[{"type":"<earthquake|flood|volcanic|wildfire|famine|plague|epidemic>","target":"<nation id or name, or region key>","severity":"<minor|moderate|severe>","detail":"<short detail>"}]},
+  "migration": {"ops":[{"kind":"<migration|refugees|diaspora|exodus>","from":"<nation id or name>","to":"<nation id or name>","scale":"<small|moderate|large>","detail":"<short detail>"}]},
+  "sea": {"control":[{"zone":"<seaZoneId>","by":"<nation id or name>"}]},
+  "contested": {"open":[{"regionKey":"<region key>","parties":["<nation 1>","<nation 2>"]}],"resolve":["<region key>"]},
+  "markers": {"add":[{"type":"<city|factory|army|port|capital|fleet|rocket|gathering>","name":"<short name>","regionKey":"<region key>"}],"remove":["<marker id>"]}
+}
+
+HOW THE FOUR 0-100 STATS DRIVE OUTCOMES (military / economy / stability / population)
+- MILITARY (the engine ENFORCES this rule, so weigh it before proposing a conquest): a nation can take a region by force only when its military is at least the defender's military minus 15 — equal, or within 15, is enough to win, but an attacker MORE than 15 below the defender is REPELLED and the region stays with its owner (a "repelled" event is recorded automatically; you cannot capture such a region that turn). Re-claiming an unowned (no man's land) region is never blocked this way.
+- STABILITY (you drive this, no hard gate): a nation whose stability is below 30 AND that has a "gathering" marker on one of its regions can suffer a NON-military takeover — a coup, revolution or faction seizure of power. Narrate it with a political or social event (outcome "success"), a "gathering" marker on the region, and stateChanges that shock its stability and economy downward.
+- ECONOMY (you drive this, no hard gate): economy drives long-term development — a strong economy lets a nation's other stats trend UP over time (small per-turn gains via stateChanges / regionChanges), while a weak economy lets them DECAY. Reflect that trend in the stat changes you make and narrate it.
+
+HARD CONSTRAINTS
+- Use only nation ids and region keys that exist in the provided state.
+- A region key identifies one sub-region; the "regions" table in the user message maps each key to "<region name> (<parent country ISO_A3>)". Use those keys in territoryChanges and unowned.
+- List in "unowned" only region keys that a nation currently owns, and narrate each release in "events".
+- Map markers ("markers") are named points on the map, anchored to a region key you own or that the narrative justifies: a capital (a nation's main seat of power — at most one per nation), major cities, factory complexes, army deployments, ports, fleet concentrations, rocket launch sites, or a gathering (a large political/social mass event that can enable a non-military takeover). Use only region keys from the "regions" table, keep each name under 40 characters, and place at most a handful of new markers per turn — only where the narrative justifies it. List a marker id from the user message's "markers" field in "remove" when it ceases to exist (a city razed, an army dispersed, a site destroyed).
+- Nation-management ops ("nationOps") are PROPOSALS: they only take effect if the player confirms them afterwards. Propose at most 1-2 per turn, only when the narrative justifies it, and narrate each one in "events".
+- Rename: add {"kind":"rename","nationRef":"<nation id or name>","to":"<new name>"} for a revolution, regime change or reunification that changes a nation's name.
+- Split: add {"kind":"split","nationRef":"<nation id or name>","parts":[{"name":"<new name>","territory":["<region key>"]}, ...]} when a state breaks up (dissolution, secession). Use at least 2 parts and assign each of the nation's region keys to at most one part — any key you leave unassigned goes to the first part.
+- Merge: add {"kind":"merge","nationRefs":["<id or name>","<id or name>"],"survivingRef":"<id or name of the surviving nation>","into":"<new name>"} when states reunify or one is absorbed. Use at least 2 input nations and "survivingRef" must name one of them — the survivor keeps its id and its stats.
+- 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.
+- Industry ("industry") is the per-resource development lever: each project is a building in one region you (or a nation) controls — {"regionKey":"<region key>","type":"<oil|iron|food|industry>"} (an oil facility, an iron mine, a food operation, or a factory). Every committed turn each active project gives its region's owner a small, deterministic economy gain, the bigger the region's industry profile (see the "resources" field). A region holds at most one project — do not re-declare one on a region that already has one (the user message's "industry" field lists what is already built). Propose at most 1-2 new projects per turn and narrate each one in "events".
+- Nuclear / WMD ("nuclear"): a nation is "nuclear-capable" when its "nuclear" flag is true or it currently owns a "rocket" marker. "arm" names (by id or name) nations to grant the "nuclear" flag — idempotent (already-armed nations are unchanged); a newly armed nation is capable this same turn. "strikes" is a list of "NuclearStrike" objects, each "{from, target}" — "from" is the striking nation (must be nuclear-capable and never itself) and "target" is either a nation (its nation collapses: economy -40, military -50, stability -40; every active war the target fights ends by capitulation and the "war" relations it caused downgrade to "hostile") or a region key (that region is released to no man's land, its regionStats entry deleted, and its sole owner collapses the same way — a region with 0 or 2+ owners, or one the striker itself owns, is dropped). If the struck nation (or the struck region's owner) is itself nuclear-capable, a "MAD" retaliation is applied: it strikes the striker back for half the collapse, and the two nations' relations are forced to "hostile". At most one strike per turn; always narrate a strike (and a retaliation, if any) in "events".
+- Leaders ("leaders") name each nation's current head of state and change it. Each change is {"target":"<nation id or name>","name":"<new leader name>","cause":"<assassination|death|appointed>"}: "assassination" kills the current leader (a dramatic, destabilizing blow — a −15 stability dip, a "military" event) and is only valid when the target already has a leader; "death" is a natural-causes succession (a quieter −3 dip, a "political" event), also only valid for a nation that has a leader; "appointed" sets (or creates) a leader and is always valid (a neutral 0 effect, a "political" event). Propose at most 1-2 changes per turn and narrate each one in "events". This is the HEAVY leader lever — use the lighter "hybrid" {"type":"assassinate"} op (a −5 stability dip, no leader replacement) for a mere hit on a leader or region without changing who is in charge. The user message's "nations" field lists each nation's current "leader" (omitted when a nation has none).
+- Ideology ("ideology") is each nation's form of government — a free-form label such as "democracy", "fascism", or "military junta" — that can shift through a coup, a revolution, a reform, or a constitutional change. Each change is {"target":"<nation id or name>","to":"<new form of government>"}: the engine sets the nation's ideology, applies a small, deterministic stability dip (−5 — a regime shift always unsettles a nation), and narrates it with a "political" event. It is a third axis, distinct from a takeover (which RENAMES the nation) and from a leader change (who is in charge): the nation keeps its id, name, territory, relations, and leader — only its form of government and its stability move. Similar forms of government are a SOFT, prompt-level compatibility nudge only (nations with alike ideologies tend to ally and trade; very opposed ones tend to clash) — there is no engine gate behind it. Propose at most 1-2 changes per turn and narrate each one in "events". The user message's "nations" field lists each nation's current "ideology" (omitted when a nation has none).
+- Disasters & pandemics ("disasters.events") are natural and man-made catastrophes — earthquakes, floods, volcanic eruptions, wildfires, famines, plagues, and epidemics — that hit a nation or a single region this turn. Each event names a "target" (a nation id / name, or a region key that hits that region's SOLE owner — a region with 0 or 2+ owners can't be hit) and a "severity" (minor / moderate / severe); the engine applies a small, DETERMINISTIC stat dip from the (type, severity) table (a severe plague is the hardest hit; none of them touch population, and none move borders — sole ownership is untouched). There is NO memory of past disasters (the layer is turn-transient): a plague or epidemic that persists is simply RE-DECLARED each turn it continues, with a fresh "severity". Propose at most 1-2 events per turn and narrate each one in "events" (a "disaster" event).
+- Migration & refugees ("migration.ops") are people moving between nations this turn: a "kind" ("migration", "refugees", "diaspora", or "exodus"), a "from" (the source nation — id or name), a "to" (the destination nation — required for every kind except "exodus", which has no destination), and a "scale" (small / moderate / large). The engine applies a DETERMINISTIC effect (no hidden randomness): the source LOSES a small amount of population and economy, the destination GAINS a small amount of population and economy (a "large" influx additionally strains the destination's stability by 2), and the from↔to relation moves one step toward the positive end of the ally/neutral/rival/hostile ladder — capped at "ally" for "refugees" (hosting refugees builds the strongest goodwill), capped at "neutral" for "migration"/"diaspora" (milder ties), and not at all for "exodus"; the nudge never creates or escalates a "war" (a warring pair is left untouched). The layer is turn-transient (no memory): a continuing flow is simply RE-DECLARED each turn it persists. It never moves borders — sole ownership is untouched. Propose at most 1-2 per turn and narrate each one in "events" (a "social" or "diplomatic" event).
+- Sea control ("sea") is the naval layer, fully parallel to but INDEPENDENT of land: each of the 12 fixed sea zones — "north-atlantic" (North Atlantic), "south-atlantic" (South Atlantic), "pacific" (Pacific Ocean), "indian" (Indian Ocean), "mediterranean" (Mediterranean Sea), "north-sea" (North Sea), "baltic" (Baltic Sea), "arctic" (Arctic Ocean), "black-sea" (Black Sea), "gulf-mexico" (Gulf of Mexico), "red-sea" (Red Sea), "sargasso" (Sargasso Sea) — is under the SOLE control of at most one nation. A control op ({"zone":"<id>","by":"<nation>"}) sets or replaces that zone's controller (the user message's "seaZones" field lists who controls what now); if two or more ops this turn claim the SAME zone for DIFFERENT nations, the zone is CONTESTED and the higher current "military" wins (a tie goes to the earlier-listed op). Every committed turn each zone's controller earns a small deterministic +1 military and +1 economy. Sea control NEVER moves land (no territory changes) — it is a parallel track. Propose at most 1-2 claims per turn and narrate each one in "events" (a "military" or "diplomatic" event).
+- Contested regions ("contested") are WAR FRONTLINES: a region that no nation controls and that is not no man's land, contested by two or more nations at war. An "open" op ({"regionKey":"<key>","parties":["<a>","<b>"]}) makes a region a frontline — it leaves its owner's territory (or no-man's-land) and is contested: the region's sole owner must be at war with at least one of the parties, or (for a no-man's-land region) two of the parties must be at war with each other. A "resolve" op (["<key>"]) ends a frontline, releasing the region to no man's land — unless a party's concurrent claim re-owns it. A contested region is in NO nation's territory (never two) and is never no man's land while contested. The user message's "contested" field lists the current frontlines (region key + party names). Propose at most 1-2 contested-region changes per turn and narrate each one in "events" (a "military" event).
+- 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.
+- Per-region stat changes ("regionChanges") target ONE region's stats directly, by its region key (preferred) or name, and make that region differ from the rest of its nation (a garrisoned border province, a bombed-out city, an industrial heartland). A nation-wide "stateChanges" entry applies to ALL of a nation's regions; a "regionChanges" entry overrides it for that one region. The user message's "playerRegionStats" lists the player's own regions' current stats; use region keys from the "regions" table.
+- Territory changes must be contiguous: a nation may only GAIN region keys that share a land border with a region it already owns (verify with getNeighbours) and may only LOSE region keys it currently owns.
+- The "frontier" field of the user message lists region keys owned by other nations that border the player's territory — the natural targets of a player-led conquest this turn.
+- A region key has at most one owner at all times — never assign a key to two nations. After a war or cataclysm a region may be left unowned ("no man's land"): list its key in "unowned" and narrate the cause in "events"; it stays unowned (grey on the map) until a nation re-claims it with a "gain". The "unowned" field of the user message lists the regions currently in no man's land.
+- If a field is not relevant this turn, set it to an empty array.

server/abilities/goldens/user.txt

@@ -0,0 +1,219 @@
+{
+  "state": {
+    "turn": 4,
+    "date": "1940-02-14",
+    "playerNationId": "a1",
+    "nations": {
+      "a1": {
+        "id": "a1",
+        "name": "Alpha",
+        "type": "major",
+        "stats": {
+          "military": 60,
+          "economy": 55,
+          "stability": 70,
+          "population": 80
+        },
+        "territory": [
+          "a-r1",
+          "a-r2"
+        ],
+        "relations": {
+          "b2": "ally",
+          "c3": "rival"
+        },
+        "leader": {
+          "name": "Alpha Leader"
+        },
+        "ideology": "democracy",
+        "nuclear": true
+      },
+      "b2": {
+        "id": "b2",
+        "name": "Bravo",
+        "type": "major",
+        "stats": {
+          "military": 75,
+          "economy": 40,
+          "stability": 20,
+          "population": 30
+        },
+        "territory": [
+          "b-r1",
+          "b-r2"
+        ],
+        "relations": {
+          "a1": "ally"
+        },
+        "ideology": "fascism",
+        "nuclear": false
+      },
+      "c3": {
+        "id": "c3",
+        "name": "Charlie",
+        "type": "major",
+        "stats": {
+          "military": 30,
+          "economy": 35,
+          "stability": 80,
+          "population": 20
+        },
+        "territory": [
+          "c-r1"
+        ],
+        "relations": {
+          "a1": "rival"
+        },
+        "nuclear": false
+      }
+    },
+    "recentEvents": []
+  },
+  "playerActions": [
+    "Rearm the northern border",
+    {
+      "to": "b2",
+      "message": "We can still talk terms, no?"
+    }
+  ],
+  "pending": [
+    {
+      "kind": "action",
+      "text": "Rearm the northern border"
+    },
+    {
+      "kind": "diplomacy",
+      "to": "b2",
+      "text": "We can still talk terms, no?"
+    }
+  ],
+  "roundInstruction": "This period the player (Alpha) takes the following actions and sends the following diplomatic messages: [\"Rearm the northern border\",{\"to\":\"b2\",\"message\":\"We can still talk terms, no?\"}]. Simulate the combined consequences across all nations and advance the world by one period. Return a single TurnResult.",
+  "playerRegionStats": {
+    "a-r1": {
+      "military": 60,
+      "economy": 55,
+      "stability": 70,
+      "population": 80
+    },
+    "a-r2": {
+      "military": 58,
+      "economy": 53,
+      "stability": 72,
+      "population": 78
+    }
+  },
+  "regions": {
+    "a-r1": "Alpha North (US)",
+    "a-r2": "Alpha South (US)",
+    "b-r1": "Bravo Plain (RU)",
+    "b-r2": "Bravo Coast (RU)",
+    "c-r1": "Charlie Isle (FR)",
+    "x-unowned": "X Released (UN)"
+  },
+  "frontier": [
+    "b-r1"
+  ],
+  "frontierMilitary": [
+    "[Your military: 60] vs [Bravo: 75] — a direct invasion could succeed"
+  ],
+  "takeoverRisks": [
+    "Bravo (stability 20, a gathering is in progress)"
+  ],
+  "unowned": [
+    "x-unowned"
+  ],
+  "markers": [
+    {
+      "id": "mk0001",
+      "type": "gathering",
+      "name": "Bravo Rally",
+      "regionKey": "b-r1",
+      "owner": "b2"
+    },
+    {
+      "id": "mk0002",
+      "type": "rocket",
+      "name": "Charlie Silo",
+      "regionKey": "c-r1",
+      "owner": "c3"
+    },
+    {
+      "id": "mk0003",
+      "type": "capital",
+      "name": "Alpha Cap",
+      "regionKey": "a-r1",
+      "owner": "a1"
+    }
+  ],
+  "wars": [
+    {
+      "id": "w1",
+      "sides": [
+        "a1",
+        "b2"
+      ],
+      "aims": [
+        "control the border"
+      ]
+    },
+    {
+      "id": "w2",
+      "sides": [
+        "b2",
+        "c3"
+      ]
+    }
+  ],
+  "relations": {
+    "b2": "ally",
+    "c3": "rival"
+  },
+  "trades": [
+    {
+      "a": "a1",
+      "b": "c3"
+    }
+  ],
+  "embargoes": [
+    {
+      "from": "a1",
+      "target": "b2"
+    }
+  ],
+  "resources": {
+    "a1": {
+      "oil": 0.5,
+      "iron": 0.2,
+      "food": 0.3,
+      "industry": 0.8
+    },
+    "b2": {
+      "oil": 0.1,
+      "iron": 0.9,
+      "food": 0.1,
+      "industry": 0.2
+    },
+    "c3": {
+      "oil": 0.2,
+      "iron": 0.3,
+      "food": 0.7,
+      "industry": 0.4
+    }
+  },
+  "industry": [
+    {
+      "regionKey": "a-r1",
+      "type": "industry"
+    }
+  ],
+  "seaZones": [],
+  "contested": [
+    {
+      "regionKey": "b-r1",
+      "parties": [
+        "Alpha",
+        "Bravo"
+      ]
+    }
+  ]
+}

server/abilities/hybrid.ts

@@ -0,0 +1,291 @@
+// The HYBRID-WAR ability (v0.34.0, #57) as a modular LLM-ability (v0.40.0, #67).
+// Covert, non-kinetic operations: the seven op types each have a DETERMINISTIC
+// engine effect (no hidden randomness — the LLM declares the intended `outcome`
+// and the engine acts only on that):
+//
+//   spy         informational only — no stat, no relation (pure intel)
+//   sabotage    a small ECONOMY dip on the target
+//   assassinate a small STABILITY dip on the target (absent the named-leaders
+//               feature, #61, a leader's removal sours the polity)
+//   cyber       a small MILITARY dip on the target
+//   economic    a small ECONOMY dip on the target
+//   information a relation nudge toward hostile (cap hostile) — disinformation
+//   proxy       a light relation nudge toward hostile (cap rival) — proxy war
+//
+// A successful stat op dips the target's `regionStats` (the single named region
+// when the target was a region key, otherwise every region the target owns) and
+// re-derives the target nation's aggregate stats so the effect persists. A
+// successful information/proxy and any exposed op sour the actor's relation
+// with the target by one step on the hostile ladder. All bodies are moved
+// VERBATIM from the pre-refactor engine.ts.
+
+import { clampStat, deriveNationStats, HYBRID_OP_TYPES, makeEvent } from '../../shared/protocol';
+import type { GameState, Nation, RelationStatus, StatKey } from '../../shared/types';
+import type { HybridOp, HybridOpType } from '../../shared/protocol';
+import { resolveNationRef, str } from './shared';
+import type { Ability } from './types';
+
+const VALID_HYBRID_TYPES = new Set<string>(HYBRID_OP_TYPES);
+
+/** True when `t` is one of the seven known hybrid op types (v0.34.0, #57). */
+export function isHybridOpType(t: unknown): t is HybridOpType {
+  return typeof t === 'string' && VALID_HYBRID_TYPES.has(t);
+}
+
+/**
+ * (v0.34.0, #57) Validate the raw `hybrid` field of a turn into a safe
+ * `{ ops }` shape. Defensive like the rest of the parser — never throws. The
+ * raw value may be the object `{ ops: [...] }` (the TurnResult shape) or a bare
+ * array (be lenient about either). Each op needs a known `type` (one of
+ * {@link HYBRID_OP_TYPES}), a non-empty `from` (the acting nation, capped at
+ * 200 chars) and a non-empty `target` (a nation id/name or a region key, capped
+ * at 200 chars); an `outcome` of exactly `success` or `exposed` is kept (the
+ * default, `success`, is stored as absent to keep the shape minimal — the
+ * engine treats a missing outcome as success); a non-empty `detail` is capped
+ * at 300 chars. Resolution of `from` / `target` to concrete nation ids or
+ * region owners happens at apply time (`applyHybridOp`), not here.
+ */
+export function validateHybridOps(raw: unknown): HybridOp[] {
+  if (!Array.isArray(raw)) {
+    // Lenient: accept the `{ ops: [...] }` object shape (or a non-array → []).
+    if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+      const inner = (raw as Record<string, unknown>).ops;
+      if (!Array.isArray(inner)) return [];
+      return validateHybridOpsList(inner);
+    }
+    return [];
+  }
+  return validateHybridOpsList(raw);
+}
+
+function validateHybridOpsList(raw: unknown[]): HybridOp[] {
+  const out: HybridOp[] = [];
+  for (const e of raw) {
+    if (!e || typeof e !== 'object') continue;
+    const o = e as Record<string, unknown>;
+    if (!isHybridOpType(o.type)) continue;
+    const from = str(o.from, 200);
+    const target = str(o.target, 200);
+    if (!from || !target) continue;
+    const detail = str(o.detail, 300);
+    const exposed = o.outcome === 'exposed'; // 'success' / missing → success
+    out.push({
+      type: o.type,
+      from,
+      target,
+      ...(detail ? { detail } : {}),
+      ...(exposed ? { outcome: 'exposed' as const } : {}),
+    });
+  }
+  return out;
+}
+
+/** The deterministic per-type stat effect of a hybrid op (v0.34.0, #57). */
+export const HYBRID_STAT_EFFECT: Record<HybridOpType, { stat: StatKey; delta: number } | null> = {
+  spy: null, // informational only
+  sabotage: { stat: 'economy', delta: -3 },
+  assassinate: { stat: 'stability', delta: -5 },
+  cyber: { stat: 'military', delta: -3 },
+  economic: { stat: 'economy', delta: -5 },
+  information: null, // relation nudge only
+  proxy: null, // relation nudge only
+};
+
+/**
+ * The hostile-relations ladder, weakest to strongest (the `cap` in
+ * {@link shiftRelationTowardHostile} is a member of this array). A missing
+ * relation is treated as `neutral`; `war` is never touched (a war is its own
+ * entity — a covert op neither fabricates nor ends one).
+ */
+const HOSTILE_ORDER: RelationStatus[] = ['ally', 'neutral', 'rival', 'hostile'];
+
+/**
+ * (v0.34.0, #57) Nudge the bilateral relation between nations `a` and `b`
+ * ONE step toward hostile (on the {@link HOSTILE_ORDER} ladder), applied
+ * symmetrically to both directions, but never past the given `cap`. A missing
+ * relation starts at `neutral`; a `war` relation is never touched (a covert op
+ * neither fabricates nor downgrades a war). Used for the `information` /
+ * `proxy` nudge and the `exposed` backfire. Mutates `state` in place (the
+ * caller passes a clone — applyTurnResult does). Never throws.
+ */
+export function shiftRelationTowardHostile(
+  state: GameState,
+  a: string,
+  b: string,
+  cap: RelationStatus,
+): void {
+  const na = state.nations[a];
+  const nb = state.nations[b];
+  if (!na || !nb) return;
+  const capIdx = HOSTILE_ORDER.indexOf(cap);
+  if (capIdx === -1) return; // unknown cap: no-op (defensive)
+  const step = (cur: RelationStatus | undefined): RelationStatus | null => {
+    if (cur === 'war') return null; // never touch a war relation
+    const s = cur ?? 'neutral'; // a missing relation is neutral
+    const i = HOSTILE_ORDER.indexOf(s);
+    if (i === -1) return 'neutral'; // defensive: unknown status
+    if (i >= capIdx) return s; // at or past the cap: no change
+    return HOSTILE_ORDER[i + 1];
+  };
+  const stepA = step(na.relations[b]);
+  if (stepA !== null) na.relations[b] = stepA;
+  const stepB = step(nb.relations[a]);
+  if (stepB !== null) nb.relations[a] = stepB;
+}
+
+/**
+ * (v0.34.0, #57) The display name of a hybrid op's target for the auto
+ * backfire event: a nation target shows the nation's name; a region target
+ * shows the region's display name (or its raw key when no resolver is given).
+ */
+function hybridTargetDisplayName(
+  target: { nation: Nation; regionKey?: string },
+  regionNameOf?: (key: string) => string | undefined,
+): string {
+  if (target.regionKey !== undefined) return regionNameOf?.(target.regionKey) ?? target.regionKey;
+  return target.nation.name;
+}
+
+/**
+ * (v0.34.0, #57) Resolve a hybrid op's `target` (a nation id/name OR a region
+ * key) to the concrete nation it affects. A nation ref resolves via
+ * {@link resolveNationRef}; a region key resolves to its SOLE owner (a region
+ * with zero or 2+ owners can't be a valid target). Returns the affected nation
+ * plus the specific region key (when the target was a region) so a stat op can
+ * dip just that region. `validKeys` (when supplied) gates the region-key path;
+ * a ref that is neither a known nation nor a valid region key returns `null`.
+ * Pure; never throws.
+ */
+function resolveHybridTarget(
+  state: GameState,
+  target: string,
+  validKeys?: ReadonlySet<string>,
+): { nation: Nation; regionKey?: string } | null {
+  const id = resolveNationRef(state, target);
+  if (id !== null) {
+    const n = state.nations[id];
+    return n ? { nation: n } : null;
+  }
+  const key = (target ?? '').trim();
+  if (!key) return null;
+  if (validKeys && !validKeys.has(key)) return null; // unknown region key
+  const owners = Object.values(state.nations).filter((n) => n.territory.includes(key));
+  if (owners.length !== 1) return null; // 0 or 2+ owners: not a targetable region
+  return { nation: owners[0], regionKey: key };
+}
+
+/**
+ * (v0.34.0, #57) Apply ONE hybrid op to the (cloned) `next` state, mutating it
+ * in place and never throwing. Resolution order:
+ *   1. `from` must resolve to a nation (id first, then a unique name); an
+ *      unknown / ambiguous actor drops the op.
+ *   2. `target` must resolve to a concrete nation (a nation ref, or a region
+ *      key's sole owner); an unresolvable target drops the op.
+ *   3. A self-target (`from` and the target nation are the same) is dropped.
+ * Then, per type:
+ *   - an `exposed` op BACKFIRES: no intended effect, the actor's relation with
+ *     the target sours by one step (cap hostile), and an auto diplomatic/
+ *     failure event is emitted (the engine's own narrative, mirroring the
+ *     "repelled" auto-event).
+ *   - a successful stat op (sabotage / assassinate / cyber / economic) dips the
+ *     target's `regionStats` by its per-type delta — the single named region
+ *     when the target was a region key, otherwise every region the target
+ *     owns — then re-derives the target nation's aggregate stats (the same
+ *     0-region / no-entry guards as the main recompute), so the effect
+ *     persists to the next turn.
+ *   - a successful `information` / `proxy` sours the actor's relation with the
+ *     target by one step (information caps at hostile, proxy at rival).
+ *   - `spy` is informational only (no stat, no relation) — a no-op except for
+ *     whatever the LLM narrates in `events`.
+ */
+export function applyHybridOp(
+  next: GameState,
+  op: HybridOp,
+  geoOf?: (key: string) => { area: number; population: number } | undefined,
+  validKeys?: ReadonlySet<string>,
+  regionNameOf?: (key: string) => string | undefined,
+  actingTurn?: number,
+): void {
+  const turn = actingTurn ?? next.turn;
+  const from = resolveNationRef(next, op.from);
+  if (from === null) return; // unknown / ambiguous actor: drop
+  const target = resolveHybridTarget(next, op.target, validKeys);
+  if (target === null) return; // unresolvable target: drop
+  if (from === target.nation.id) return; // self-target: drop
+
+  if (op.outcome === 'exposed') {
+    // Backfire: no intended effect; the relation sours by one step (cap
+    // hostile) and an auto diplomatic/failure event is emitted.
+    shiftRelationTowardHostile(next, from, target.nation.id, 'hostile');
+    const actor = next.nations[from];
+    next.events.push(
+      makeEvent(
+        {
+          nation: from,
+          type: 'diplomatic',
+          title: 'Covert operation exposed',
+          text: `${actor?.name ?? from}'s ${op.type} operation against ${hybridTargetDisplayName(
+            target,
+            regionNameOf,
+          )} was exposed; relations sour in response.`,
+          outcome: 'failure',
+        },
+        turn,
+        next.date,
+      ),
+    );
+    return;
+  }
+
+  const eff = HYBRID_STAT_EFFECT[op.type];
+  if (eff) {
+    // A successful stat op: dip the target's region(s), then re-derive.
+    if (target.regionKey !== undefined) {
+      const rs = next.regionStats[target.regionKey];
+      if (rs) rs[eff.stat] = clampStat(rs[eff.stat] + eff.delta);
+    } else {
+      for (const key of target.nation.territory) {
+        const rs = next.regionStats[key];
+        if (!rs) continue;
+        rs[eff.stat] = clampStat(rs[eff.stat] + eff.delta);
+      }
+    }
+    // Re-derive the target nation's aggregate stats. The main recompute ran
+    // earlier this turn, so without this the dip would be washed out next
+    // turn. The same 0-region / no-entry guards as the main recompute apply.
+    if (target.nation.territory.length > 0) {
+      if (target.nation.territory.some((k) => next.regionStats[k])) {
+        target.nation.stats = deriveNationStats(
+          target.nation.territory,
+          next.regionStats,
+          geoOf,
+        );
+      }
+    }
+    return;
+  }
+
+  // information / proxy: a relation nudge (spy is a pure no-op here).
+  if (op.type === 'information') shiftRelationTowardHostile(next, from, target.nation.id, 'hostile');
+  else if (op.type === 'proxy') shiftRelationTowardHostile(next, from, target.nation.id, 'rival');
+}
+
+export const hybrid: Ability<'hybrid'> = {
+  field: 'hybrid',
+  default: () => ({ ops: [] }),
+  // The low-level validator returns a bare list; the field's shape is the
+  // `{ ops }` object (mirrors the historical `result.hybrid = { ops: ... }`).
+  validate: (raw) => ({ ops: validateHybridOps(raw) }),
+  apply: (state, data, ctx) => {
+    for (const op of data.ops) {
+      applyHybridOp(state, op, ctx.geoOf, ctx.validRegionKeys, ctx.regionNameOf, ctx.actingTurn);
+    }
+  },
+  schemaLine: () =>
+    '  "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>"}]},',
+  constraint: () =>
+    '- 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".',
+  isMeaningful: (data) => data.ops.length > 0,
+  stub: () => ({ ops: [] }),
+  payload: (ctx) => (ctx.relations !== undefined ? { relations: ctx.relations } : {}),
+};

server/abilities/ideology.ts

@@ -0,0 +1,123 @@
+// The IDEOLOGY ability (v0.39, #62) as a modular LLM-ability (v0.40.0, #67).
+// The model may change a nation's form of government (its `ideology` field) —
+// a free-form label such as "democracy", "fascism", or "military junta" — via
+// a coup, revolution, reform, or constitutional change. On a valid change the
+// target's `ideology` is set, a DETERMINISTIC stability dip
+// (`IDEOLOGY_STABILITY_EFFECT`, −5) is applied to its `stats.stability`
+// (clamped) and mirrored to every region the nation owns (`regionStats`), the
+// nation's derived stats are re-derived afterwards (the same 0-region /
+// no-entry guards), and a narration event is appended. The change never moves
+// territory (sole ownership is untouched). All bodies are moved VERBATIM from
+// the pre-refactor engine.ts.
+
+import { deriveNationStats, makeEvent } from '../../shared/protocol';
+import { clampStat, IDEOLOGY_STABILITY_EFFECT } from '../../shared/protocol';
+import type { GameState } from '../../shared/types';
+import type { IdeologyChange } from '../../shared/protocol';
+import { resolveNationRef, str } from './shared';
+import type { Ability } from './types';
+
+/**
+ * (v0.39, #62) Validate the raw `ideology` object of a turn into a safe
+ * `IdeologyChange[]`. Defensive like the rest of the parser — never throws.
+ * Accepts a `{ changes: [...] }` object or a bare array (lenient). Each
+ * change needs a non-empty `target` (a nation ref, capped at 120 chars) and
+ * a non-empty, non-whitespace `to` (the new form of government, capped at
+ * 120 chars). Refs stay raw here (resolved against the real state at apply
+ * time, like the wars / hybrid / nuclear / leader ops); an unresolvable
+ * target is dropped at apply time, never thrown.
+ */
+export function validateIdeologyOps(raw: unknown): IdeologyChange[] {
+  const out: IdeologyChange[] = [];
+  const list = Array.isArray(raw)
+    ? raw
+    : raw && typeof raw === 'object'
+      ? (raw as Record<string, unknown>).changes
+      : undefined;
+  if (!Array.isArray(list)) return out;
+  for (const e of list) {
+    if (!e || typeof e !== 'object') continue;
+    const s = e as Record<string, unknown>;
+    const target = str(s.target, 120);
+    const to = str(s.to, 120);
+    if (!target || !to) continue;
+    out.push({ target, to });
+  }
+  return out;
+}
+
+/**
+ * (v0.39, #62) Apply a single ideology change to `next` (in place). The
+ * target nation is resolved by the shared resolver (id first, then a
+ * case-insensitive unique name; an unknown or ambiguous ref is dropped,
+ * never thrown). On a valid change the target's `ideology` is set to the new
+ * government type (re-setting the same value is idempotent for the field but
+ * still narrated) and a DETERMINISTIC stability dip
+ * (`IDEOLOGY_STABILITY_EFFECT`, −5) is applied to its `stats.stability`
+ * (clamped 0–100) and mirrored to every region the nation owns
+ * (`regionStats`); the nation's derived stats are re-derived afterwards (the
+ * same 0-region / no-entry guards as the hybrid/economy/industry/leader
+ * effects, so a 0-region nation keeps its directly-mutated value). Finally a
+ * narration event is appended: a `political` event for the government shift.
+ * The change never moves territory (sole ownership is untouched).
+ */
+function applyIdeologyChange(
+  next: GameState,
+  op: IdeologyChange,
+  geoOf?: (key: string) => { area: number; population: number } | undefined,
+  actingTurn?: number,
+): void {
+  const turn = actingTurn ?? next.turn;
+  const id = resolveNationRef(next, op.target);
+  if (id === null) return; // unknown / ambiguous target: drop, never throw
+  const n = next.nations[id];
+
+  n.ideology = op.to;
+
+  const delta = IDEOLOGY_STABILITY_EFFECT;
+  if (delta !== 0) {
+    n.stats.stability = clampStat(n.stats.stability + delta);
+    for (const key of n.territory) {
+      const rs = next.regionStats[key];
+      if (!rs) continue;
+      rs.stability = clampStat(rs.stability + delta);
+    }
+    // Re-derive the nation's aggregate stats (the main recompute ran earlier
+    // this turn, so without this the dip would be washed out next turn).
+    if (n.territory.length > 0 && n.territory.some((k) => next.regionStats[k])) {
+      n.stats = deriveNationStats(n.territory, next.regionStats, geoOf);
+    }
+  }
+
+  next.events.push(
+    makeEvent(
+      {
+        nation: n.id,
+        type: 'political',
+        title: `${n.name}'s government shifted to ${op.to}`,
+        text: `${n.name} has changed its form of government to ${op.to}.`,
+        outcome: 'success',
+      },
+      turn,
+      next.date,
+    ),
+  );
+}
+
+export const ideology: Ability<'ideology'> = {
+  field: 'ideology',
+  default: () => ({ changes: [] }),
+  // The low-level validator returns a bare list; the field's shape is the
+  // `{ changes }` object (mirrors the historical `result.ideology = { changes: ... }`).
+  validate: (raw) => ({ changes: validateIdeologyOps(raw) }),
+  apply: (state, data, ctx) => {
+    for (const ch of data.changes) applyIdeologyChange(state, ch, ctx.geoOf, ctx.actingTurn);
+  },
+  schemaLine: () =>
+    '  "ideology": {"changes":[{"target":"<nation id or name>","to":"<new form of government>"}]},',
+  constraint: () =>
+    '- Ideology ("ideology") is each nation\'s form of government — a free-form label such as "democracy", "fascism", or "military junta" — that can shift through a coup, a revolution, a reform, or a constitutional change. Each change is {"target":"<nation id or name>","to":"<new form of government>"}: the engine sets the nation\'s ideology, applies a small, deterministic stability dip (−5 — a regime shift always unsettles a nation), and narrates it with a "political" event. It is a third axis, distinct from a takeover (which RENAMES the nation) and from a leader change (who is in charge): the nation keeps its id, name, territory, relations, and leader — only its form of government and its stability move. Similar forms of government are a SOFT, prompt-level compatibility nudge only (nations with alike ideologies tend to ally and trade; very opposed ones tend to clash) — there is no engine gate behind it. Propose at most 1-2 changes per turn and narrate each one in "events". The user message\'s "nations" field lists each nation\'s current "ideology" (omitted when a nation has none).',
+  isMeaningful: (data) => data.changes.length > 0,
+  stub: () => ({ changes: [] }),
+  payload: () => ({}),
+};

server/abilities/index.ts

@@ -0,0 +1,187 @@
+// The ordered LLM-ability registry.
+//
+// `ABILITIES` is the single source of truth for the 12 per-feature LLM abilities.
+// The engine iterates it in this order:
+//   takeovers → wars → hybrid → economy → industry → nuclear → leaders → ideology → disasters → migration → sea → contested
+// for (a) the system-prompt schema lines + constraint bullets, (b) the per-ability
+// validate calls inside validateTurnResult, (c) the payload fields in buildUserPrompt,
+// (d) the ordered apply block inside applyTurnResult, (e) the isMeaningful check,
+// (f) the runTurn unclear-fallback defaults, (g) the stub's deterministic fields, and
+// (h) the db.ts state-field migrations.
+//
+// Each ability file defines its own `Ability<K>` const (the schema line, constraint
+// bullet, validator, applier, meaningfulness predicate, stub default, and user-payload
+// field). This module assembles them into the ordered `ABILITIES` array and re-exports
+// every public name the engine (and its tests) need.
+
+import { takeovers } from './takeovers';
+import { wars } from './wars';
+import { hybrid } from './hybrid';
+import { economy } from './economy';
+import { industry } from './industry';
+import { nuclear } from './nuclear';
+import { leaders } from './leaders';
+import { ideology } from './ideology';
+import { disasters } from './disasters';
+import { migration } from './migration';
+import { sea } from './sea';
+import { contested } from './contested';
+import type { Ability, AbilityField } from './types';
+
+/**
+ * The 12 per-feature LLM abilities in their canonical apply order.
+ * The order matters: it determines the order of the schema lines in the
+ * system prompt, the order of the validate calls, the order of the apply
+ * steps, and the order of the payload fields in the user prompt. New
+ * abilities are APPENDED last — never reorder existing entries (their order
+ * is pinned by the goldens and the stub's byte-identical output).
+ */
+export const ABILITIES: readonly Ability<AbilityField>[] = [
+  takeovers,
+  wars,
+  hybrid,
+  economy,
+  industry,
+  nuclear,
+  leaders,
+  ideology,
+  disasters,
+  migration,
+  sea,
+  contested,
+];
+
+// ── type re-exports ────────────────────────────────────────────────────────────
+
+export type {
+  Ability,
+  AbilityCtx,
+  UserPromptCtx,
+  AbilityField,
+} from './types';
+
+// ── shared helpers ─────────────────────────────────────────────────────────────
+
+export {
+  resolveNationRef,
+  resolveRegionKey,
+  freshNationId,
+  freshWarId,
+  NEW_NATION_STATS,
+} from './shared';
+
+// ── war helpers ────────────────────────────────────────────────────────────────
+
+export {
+  activeWarPairs,
+  atWar,
+  syncWarRelations,
+} from './apply-helpers';
+
+// ── takeovers ──────────────────────────────────────────────────────────────────
+
+export {
+  validateTakeovers,
+  applyTakeover,
+} from './takeovers';
+
+// ── wars ───────────────────────────────────────────────────────────────────────
+
+export {
+  validateWarOps,
+  applyWars,
+} from './wars';
+
+// ── hybrid ─────────────────────────────────────────────────────────────────────
+
+export {
+  validateHybridOps,
+  isHybridOpType,
+  HYBRID_STAT_EFFECT,
+  shiftRelationTowardHostile,
+  applyHybridOp,
+} from './hybrid';
+
+// ── economy ────────────────────────────────────────────────────────────────────
+
+export {
+  validateEconomyOps,
+  applyEconomyEffects,
+} from './economy';
+
+// ── industry ───────────────────────────────────────────────────────────────────
+
+export {
+  validateIndustryOps,
+  isIndustryType,
+  applyIndustryEffects,
+} from './industry';
+
+// ── nuclear ────────────────────────────────────────────────────────────────────
+
+export {
+  validateNuclearOps,
+  applyNuclearOps,
+} from './nuclear';
+
+// ── leaders ────────────────────────────────────────────────────────────────────
+
+export {
+  validateLeaderOps,
+} from './leaders';
+
+// ── ideology ───────────────────────────────────────────────────────────────────
+
+export {
+  validateIdeologyOps,
+} from './ideology';
+
+// ── disasters ────────────────────────────────────────────────────────────────
+
+export {
+  validateDisasterEvents,
+  applyDisasterEvent,
+  isDisasterType,
+  isDisasterSeverity,
+  DISASTER_TYPES,
+  DISASTER_SEVERITIES,
+  DISASTER_EFFECTS,
+} from './disasters';
+
+// ── migration ────────────────────────────────────────────────────────────────
+
+export {
+  validateMigrationOps,
+  applyMigrationOp,
+  shiftRelationTowardPositive,
+  isMigrationKind,
+  isMigrationScale,
+  MIGRATION_KINDS,
+  MIGRATION_SCALES,
+  MIGRATION_SOURCE_EFFECTS,
+  MIGRATION_DESTINATION_EFFECTS,
+  LARGE_INFLUX_STABILITY_DIP,
+} from './migration';
+
+// ── sea ──────────────────────────────────────────────────────────────────────
+
+export {
+  validateSeaOps,
+  applySeaControl,
+  applySeaZoneBonuses,
+  SEA_ZONE_BONUS,
+  SEA_ZONES,
+  SEA_ZONE_IDS,
+  isSeaZoneId,
+  seaZoneName,
+} from './sea';
+
+// ── contested (frontlines) ───────────────────────────────────────────────────
+
+export {
+  validateContestedOps,
+  applyContested,
+  CONTESTED_FILL,
+  CONTESTED_STROKE,
+  contestedTooltipLabel,
+} from './contested';

server/abilities/industry.ts

@@ -0,0 +1,212 @@
+// The INDUSTRY ability (v0.36, #59) as a modular LLM-ability (v0.40.0, #67).
+// The per-region economy-boost lever: each project is a building in one
+// region (`{ regionKey, type }`, type one of oil / iron / food / industry).
+// `GameState.industry` is a PER-REGION SET — a region key that is not a valid
+// manifest key is dropped; a region that already hosts a project is untouched
+// (the first declared type wins — re-declaring is a no-op). Every committed
+// turn each active project grants its region's SOLE owner a small,
+// deterministic economy boost (`INDUSTRY_ECONOMY_BONUS`, plus one extra point
+// when the region's `industry` resource value is ≥ 0.5 — from the synthesized
+// resource manifest; without it just the base) — clamped to 0–100, mirrored
+// to every region the owner holds, and re-derived like the economy/hybrid
+// effects. A project on a region with 0 or 2+ owners yields no boost but is
+// kept. Sole ownership is untouched (the layer moves stats, never territory).
+// All bodies are moved VERBATIM from the pre-refactor engine.ts.
+
+import { clampStat, deriveNationStats } from '../../shared/protocol';
+import type { GameState, IndustryType, RegionResources } from '../../shared/types';
+import { INDUSTRY_TYPES } from '../../shared/types';
+import type { IndustryOps } from '../../shared/protocol';
+import { str } from './shared';
+import type { Ability } from './types';
+
+const VALID_INDUSTRY_TYPES = new Set<string>(INDUSTRY_TYPES);
+
+/** True when `t` is one of the four known industry project types (v0.36, #59). */
+export function isIndustryType(t: unknown): t is IndustryType {
+  return typeof t === 'string' && VALID_INDUSTRY_TYPES.has(t);
+}
+
+/**
+ * (v0.36, #59) Validate the raw `industry` object of a turn into a safe
+ * {@link IndustryOps}. Defensive like the rest of the parser — never throws.
+ * `projects`: each op needs a non-empty `regionKey` (capped at 120 chars) and a
+ * known project {@link IndustryType} (one of INDUSTRY_TYPES); ops with a
+ * missing/malformed field are dropped. The region key is kept raw here (like
+ * the hybrid / economy refs) — whether it is a *valid* region key, and whether
+ * its region ends the turn with a sole owner, is checked at apply time against
+ * the manifest and the final ownership (a project on a region with no sole
+ * owner yields no boost but is kept). A missing / malformed top-level object
+ * yields `{ projects: [] }`.
+ */
+export function validateIndustryOps(raw: unknown): IndustryOps {
+  const out: IndustryOps = { projects: [] };
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return out;
+  const o = raw as Record<string, unknown>;
+  if (Array.isArray(o.projects)) {
+    for (const e of o.projects) {
+      if (!e || typeof e !== 'object') continue;
+      const p = e as Record<string, unknown>;
+      const regionKey = str(p.regionKey, 120);
+      if (!regionKey || !isIndustryType(p.type)) continue;
+      out.projects.push({ regionKey, type: p.type });
+    }
+  }
+  return out;
+}
+
+/**
+ * (v0.36, #59) The BASE per-turn economy boost one industry project grants its
+ * region's sole owner. A project's actual boost is this base plus one extra
+ * point when the region's `industry` resource value is at least 0.5 (a region
+ * with a strong industry profile yields a bigger return). The base value is
+ * deliberately the same magnitude as {@link TRADE_ECONOMY_BONUS} /
+ * {@link EMBARGO_ECONOMY_PENALTY}.
+ */
+const INDUSTRY_ECONOMY_BONUS = 1;
+
+/**
+ * (v0.36, #59) The per-turn economy boost for ONE industry project sitting in
+ * `regionKey`: {@link INDUSTRY_ECONOMY_BONUS} plus one extra point when the
+ * region's `industry` resource value (from `resourceOf`) is at least 0.5.
+ * Without the resource manifest (or for a region with no profile) the boost is
+ * the base value. Pure + deterministic.
+ */
+function industryBoost(
+  regionKey: string,
+  resourceOf?: (key: string) => RegionResources | undefined,
+): number {
+  const r = resourceOf?.(regionKey);
+  return INDUSTRY_ECONOMY_BONUS + (r && r.industry >= 0.5 ? 1 : 0);
+}
+
+/**
+ * (v0.36, #59) Apply the turn's industry ops to `GameState.industry` as a
+ * PER-REGION SET: each op names a region key + a project type. A region key
+ * that is not a valid manifest key (`validKeys`, when supplied) is dropped; a
+ * region that already hosts a project is untouched (the first declared type
+ * wins — re-declaring on the same region is a no-op, the type is never
+ * replaced). Otherwise the project is appended. Mutates `next` in place.
+ * Nothing here throws.
+ */
+function applyIndustryOps(
+  next: GameState,
+  ops: IndustryOps,
+  validKeys?: ReadonlySet<string>,
+): void {
+  if (ops.projects.length === 0) return;
+  const has = (key: string) => next.industry.some((p) => p.regionKey === key);
+  for (const p of ops.projects) {
+    if (validKeys && !validKeys.has(p.regionKey)) continue; // unknown region key: drop
+    if (has(p.regionKey)) continue; // a region hosts at most one project
+    next.industry.push({ regionKey: p.regionKey, type: p.type });
+  }
+}
+
+/**
+ * (v0.36, #59) The per-turn economic effect of the industry layer, applied
+ * EVERY committed turn (not just to this turn's adds): each active project
+ * grants its region's SOLE owner a small, deterministic economy boost (see
+ * {@link industryBoost}) — clamped to 0–100, mirrored to every region the
+ * owner holds (`regionStats`), and each affected nation's derived stats are
+ * re-derived afterwards (the same 0-region / no-entry guards as
+ * `applyEconomyEffects`). A project whose region ends the turn with NO owner,
+ * or 2+ owners (released to no man's land / corrupt), yields no boost but is
+ * kept in the list. Sole ownership is untouched. No-op when there are no
+ * active projects. Never throws.
+ */
+export function applyIndustryEffects(
+  next: GameState,
+  resourceOf?: (key: string) => RegionResources | undefined,
+  geoOf?: (key: string) => { area: number; population: number } | undefined,
+): void {
+  if (next.industry.length === 0) return;
+
+  // Map each region key to its SOLE owner (a key with 0 or 2+ owners maps to
+  // nothing and yields no boost).
+  const ownerOf = new Map<string, string>();
+  {
+    const owners = new Map<string, string[]>();
+    for (const n of Object.values(next.nations)) {
+      for (const key of n.territory) {
+        const list = owners.get(key);
+        if (list) list.push(n.id);
+        else owners.set(key, [n.id]);
+      }
+    }
+    for (const [key, list] of owners) {
+      if (list.length === 1) ownerOf.set(key, list[0]);
+    }
+  }
+
+  // nation id -> accumulated economy boost (a nation owning several project
+  // regions gets each of their boosts).
+  const delta = new Map<string, number>();
+  for (const p of next.industry) {
+    const owner = ownerOf.get(p.regionKey);
+    if (!owner) continue; // 0 or 2+ owners: no boost (the project is kept)
+    const n = next.nations[owner];
+    if (!n) continue; // a nation removed this turn (a merge): the boost is dropped
+    delta.set(owner, (delta.get(owner) ?? 0) + industryBoost(p.regionKey, resourceOf));
+  }
+
+  const affected = new Set<string>();
+  for (const [id, d] of delta) {
+    const n = next.nations[id];
+    if (!n) continue;
+    n.stats.economy = clampStat(n.stats.economy + d);
+    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);
+      }
+    }
+  }
+}
+
+export const industry: Ability<'industry'> = {
+  field: 'industry',
+  default: () => ({ projects: [] }),
+  validate: (raw) => validateIndustryOps(raw),
+  apply: (state, data, ctx) => {
+    // Placed after the economy block (both move stats, and the industry boost
+    // should compose with the trade/embargo effects of the same turn) and
+    // before markers / nationOps. Order:
+    //   (1) APPLY OPS: this turn's `industry.projects` are added to
+    //       `GameState.industry` as a per-region SET — a region key that is not
+    //       a valid manifest key is dropped, and a region that already hosts a
+    //       project is untouched (the first declared type wins; re-declaring is
+    //       a no-op).
+    //   (2) PER-TURN EFFECT: the FULL active project list (not just this
+    //       turn's adds) each grants their region's SOLE owner a small,
+    //       deterministic economy boost scaled by the region's `industry`
+    //       resource value — clamped, mirrored to every region the owner holds,
+    //       and re-derived like the economy/hybrid effects. A project whose
+    //       region ends the turn with no owner (or 2+ owners) yields no boost
+    //       but is KEPT (the region may be re-claimed later). Sole ownership is
+    //       untouched (the layer moves stats, never territory).
+    applyIndustryOps(state, data, ctx.validRegionKeys);
+    applyIndustryEffects(state, ctx.resourceOf, ctx.geoOf);
+  },
+  schemaLine: () =>
+    '  "industry": {"projects":[{"regionKey":"<region key>","type":"<oil|iron|food|industry>"}]},',
+  constraint: () =>
+    '- Industry ("industry") is the per-resource development lever: each project is a building in one region you (or a nation) controls — {"regionKey":"<region key>","type":"<oil|iron|food|industry>"} (an oil facility, an iron mine, a food operation, or a factory). Every committed turn each active project gives its region\'s owner a small, deterministic economy gain, the bigger the region\'s industry profile (see the "resources" field). A region holds at most one project — do not re-declare one on a region that already has one (the user message\'s "industry" field lists what is already built). Propose at most 1-2 new projects per turn and narrate each one in "events".',
+  isMeaningful: (data) => data.projects.length > 0,
+  stateFields: ['industry'],
+  stub: () => ({ projects: [] }),
+  payload: (ctx) => {
+    const out: Record<string, unknown> = {};
+    if (ctx.nationResources !== undefined) out.resources = ctx.nationResources;
+    if (ctx.industryProjects !== undefined) out.industry = ctx.industryProjects;
+    return out;
+  },
+};

server/abilities/leaders.ts

@@ -0,0 +1,156 @@
+// The NAMED-LEADERS ability (v0.38, #61) as a modular LLM-ability (v0.40.0,
+// #67). The model may change a nation's head of state: an `assassination`
+// (a dramatic, destabilizing blow — a −15 stability dip, a "military" event,
+// only valid when the target already has a leader), a `death` (a natural-
+// causes succession — a quieter −3 dip, a "political" event, also only valid
+// for a nation that has a leader), or an `appointed` change (sets or creates
+// a leader and is always valid — a neutral 0 effect, a "political" event).
+// On a valid change the target's `leader` is set, the DETERMINISTIC stability
+// dip (`LEADER_STABILITY_EFFECT[cause]`) is applied to its `stats.stability`
+// (clamped) and mirrored to every region the nation owns (`regionStats`), the
+// nation's derived stats are re-derived afterwards (the same 0-region /
+// no-entry guards), and a narration event is appended. The replacement never
+// moves territory (sole ownership is untouched). All bodies are moved
+// VERBATIM from the pre-refactor engine.ts.
+
+import { deriveNationStats, makeEvent } from '../../shared/protocol';
+import { clampStat, LEADER_STABILITY_EFFECT } from '../../shared/protocol';
+import type { GameState } from '../../shared/types';
+import type { LeaderCause, LeaderChange } from '../../shared/protocol';
+import { resolveNationRef, str } from './shared';
+import type { Ability } from './types';
+
+/**
+ * (v0.38, #61) Validate the raw `leaders` object of a turn into a safe
+ * `LeaderChange[]`. Defensive like the rest of the parser — never throws.
+ * Accepts a `{ changes: [...] }` object or a bare array (lenient). Each change
+ * needs a non-empty `target` (a nation ref, capped at 120 chars), a non-empty
+ * `name` (the new leader's name, capped at 120 chars), and a `cause` that is
+ * one of the three known literals (assassination / death / appointed). Refs
+ * stay raw here (resolved against the real state at apply time, like the wars
+ * / hybrid / nuclear ops); a leaderless assassination/death is dropped at
+ * apply time, never thrown.
+ */
+export function validateLeaderOps(raw: unknown): LeaderChange[] {
+  const out: LeaderChange[] = [];
+  const list = Array.isArray(raw)
+    ? raw
+    : raw && typeof raw === 'object'
+      ? (raw as Record<string, unknown>).changes
+      : undefined;
+  if (!Array.isArray(list)) return out;
+  for (const e of list) {
+    if (!e || typeof e !== 'object') continue;
+    const s = e as Record<string, unknown>;
+    const target = str(s.target, 120);
+    const name = str(s.name, 120);
+    if (!target || !name) continue;
+    const cause = typeof s.cause === 'string' ? s.cause : '';
+    if (cause === 'assassination' || cause === 'death' || cause === 'appointed') {
+      out.push({ target, name, cause: cause as LeaderCause });
+    }
+  }
+  return out;
+}
+
+/**
+ * (v0.38, #61) Apply a single leader change to `next` (in place). The target
+ * nation is resolved by the shared resolver (id first, then a case-insensitive
+ * unique name; an unknown or ambiguous ref is dropped, never thrown). A GATE
+ * then applies: an `assassination` or `death` requires the target to already
+ * have a leader (a leaderless target is dropped); an `appointed` change is
+ * always valid (it creates the first leader). On a valid change the target's
+ * `leader` is set to the new name and a DETERMINISTIC stability dip
+ * (`LEADER_STABILITY_EFFECT[cause]`) is applied to its `stats.stability`
+ * (clamped 0–100) and mirrored to every region the nation owns
+ * (`regionStats`); the nation's derived stats are re-derived afterwards (the
+ * same 0-region / no-entry guards as the hybrid/economy/industry effects, so a
+ * 0-region nation keeps its directly-mutated value). Finally a narration event
+ * is appended: a dramatic `military` event for an assassination, a `political`
+ * succession event for a death or an appointment. The replacement never moves
+ * territory (sole ownership is untouched).
+ */
+function applyLeaderChange(
+  next: GameState,
+  op: LeaderChange,
+  geoOf?: (key: string) => { area: number; population: number } | undefined,
+  actingTurn?: number,
+): void {
+  const turn = actingTurn ?? next.turn;
+  const id = resolveNationRef(next, op.target);
+  if (id === null) return; // unknown / ambiguous target: drop, never throw
+  const n = next.nations[id];
+
+  // GATE: assassination / death require an existing leader; an appointment is
+  // always valid (it creates the first leader).
+  if (op.cause !== 'appointed' && !n.leader) return;
+
+  const prevName = n.leader?.name;
+  n.leader = { name: op.name };
+
+  const delta = LEADER_STABILITY_EFFECT[op.cause];
+  if (delta !== 0) {
+    n.stats.stability = clampStat(n.stats.stability + delta);
+    for (const key of n.territory) {
+      const rs = next.regionStats[key];
+      if (!rs) continue;
+      rs.stability = clampStat(rs.stability + delta);
+    }
+    // Re-derive the nation's aggregate stats (the main recompute ran earlier
+    // this turn, so without this the dip would be washed out next turn).
+    if (n.territory.length > 0 && n.territory.some((k) => next.regionStats[k])) {
+      n.stats = deriveNationStats(n.territory, next.regionStats, geoOf);
+    }
+  }
+
+  const title =
+    op.cause === 'assassination'
+      ? `${prevName ?? 'The leader'} of ${n.name} is assassinated`
+      : op.cause === 'death'
+        ? `${prevName ?? 'The leader'} of ${n.name} dies`
+        : `${n.name} appoints ${op.name}`;
+  const text =
+    op.cause === 'assassination'
+      ? `${n.name}'s leader ${prevName ?? ''} was assassinated; ${op.name} takes power amid turmoil.`
+      : op.cause === 'death'
+        ? `${n.name}'s leader ${prevName ?? ''} has died; ${op.name} succeeds to power.`
+        : `${n.name} has appointed ${op.name} as its new leader.`;
+  next.events.push(
+    makeEvent(
+      {
+        nation: n.id,
+        type: op.cause === 'assassination' ? 'military' : 'political',
+        title,
+        text,
+        outcome: 'success',
+      },
+      turn,
+      next.date,
+    ),
+  );
+}
+
+export const leaders: Ability<'leaders'> = {
+  field: 'leaders',
+  default: () => ({ changes: [] }),
+  // The low-level validator returns a bare list; the field's shape is the
+  // `{ changes }` object (mirrors the historical `result.leaders = { changes: ... }`).
+  validate: (raw) => ({ changes: validateLeaderOps(raw) }),
+  apply: (state, data, ctx) => {
+    // Placed after the nuclear block (both are the "heavier" levers) and
+    // before the markers block (markers recompute their owner from the FINAL
+    // post-claim ownership; leaders only touch stats, so ordering w.r.t.
+    // markers is immaterial, but keeping the levers grouped is clearer). Each
+    // change sets the target's leader, applies a deterministic stability dip
+    // by cause, and appends a narration event. A leaderless assassination/
+    // death is dropped.
+    for (const op of data.changes) applyLeaderChange(state, op, ctx.geoOf, ctx.actingTurn);
+  },
+  schemaLine: () =>
+    '  "leaders": {"changes":[{"target":"<nation id or name>","name":"<new leader name>","cause":"<assassination|death|appointed>"}]},',
+  constraint: () =>
+    '- Leaders ("leaders") name each nation\'s current head of state and change it. Each change is {"target":"<nation id or name>","name":"<new leader name>","cause":"<assassination|death|appointed>"}: "assassination" kills the current leader (a dramatic, destabilizing blow — a −15 stability dip, a "military" event) and is only valid when the target already has a leader; "death" is a natural-causes succession (a quieter −3 dip, a "political" event), also only valid for a nation that has a leader; "appointed" sets (or creates) a leader and is always valid (a neutral 0 effect, a "political" event). Propose at most 1-2 changes per turn and narrate each one in "events". This is the HEAVY leader lever — use the lighter "hybrid" {"type":"assassinate"} op (a −5 stability dip, no leader replacement) for a mere hit on a leader or region without changing who is in charge. The user message\'s "nations" field lists each nation\'s current "leader" (omitted when a nation has none).',
+  isMeaningful: (data) => data.changes.length > 0,
+  stub: () => ({ changes: [] }),
+  payload: () => ({}),
+};

server/abilities/migration.test.ts

@@ -0,0 +1,574 @@
+// Unit tests for the MIGRATION & REFUGEES ability (v0.42.0, #64) — the
+// modular, turn-transient LLM-ability that moves population between nations:
+// the source loses a small amount of population and economy, the destination
+// gains a small amount (a `large` influx also strains the destination's
+// stability), each side's aggregate stats are re-derived, and the from↔to
+// relation is nudged one step toward the positive end of the ladder (capped by
+// kind; a war is never touched). This is the ability's own test file (the
+// registry's cross-cutting guarantees — order, distinct fields, the
+// system/user goldens — are covered by ./registry.test.ts). The stub never
+// proposes a migration, so the apply path is exercised here, not by the e2e
+// suite.
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  LARGE_INFLUX_STABILITY_DIP,
+  MIGRATION_DESTINATION_EFFECTS,
+  MIGRATION_KINDS,
+  MIGRATION_SCALES,
+  MIGRATION_SOURCE_EFFECTS,
+  applyMigrationOp,
+  isMigrationKind,
+  isMigrationScale,
+  migration,
+  shiftRelationTowardPositive,
+  validateMigrationOps,
+} from './migration';
+
+import type { MigrationScale } from '../../shared/protocol';
+import type { GameState, Nation, NationStats, RelationStatus, RegionStats } from '../../shared/types';
+
+// ---------------------------------------------------------------------------
+// Fixture helpers
+// ---------------------------------------------------------------------------
+
+/** Build a NationStats from the four canonical indices (military, economy, stability, population). */
+function NS(military: number, economy: number, stability: number, population: number): NationStats {
+  return { military, economy, stability, population };
+}
+
+/** Build a RegionStats from the four canonical indices. */
+function RS(military: number, economy: number, stability: number, population: number): RegionStats {
+  return { military, economy, stability, population };
+}
+
+/** A minimal nation: the given id/name/stats/region-key territory, given relations. */
+function mkNation(
+  id: string,
+  name: string,
+  stats: NationStats,
+  territory: string[],
+  relations: Record<string, RelationStatus> = {},
+): Nation {
+  return { id, name, type: 'major', stats, territory, relations };
+}
+
+/**
+ * A minimal GameState carrying the given nations (keyed by id) and per-region
+ * stats. Every other required field is at its fresh-game baseline, so a test
+ * can focus purely on the migration effect.
+ */
+function mkState(
+  nations: Record<string, Nation>,
+  regionStats: Record<string, RegionStats>,
+): GameState {
+  return {
+    id: 'g1',
+    presetId: 'test',
+    presetTitle: 'Test',
+    playerNationId: Object.keys(nations)[0] ?? 'uk',
+    turn: 1,
+    date: '1939-09-01',
+    nations,
+    events: [],
+    pending: [],
+    version: 1,
+    unowned: [],
+    pendingNationOps: [],
+    markers: [],
+    regionStats,
+    wars: [],
+    trades: [],
+    embargoes: [],
+    industry: [],
+    // (v0.43.0, #65) no sea-zone control on a fresh state.
+    seaZones: [],
+    // (v0.44.0, #66) no contested regions on a fresh state.
+    contested: [],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Kind / scale constants + predicates
+// ---------------------------------------------------------------------------
+
+describe('MIGRATION_KINDS / MIGRATION_SCALES', () => {
+  it('exposes exactly the four kinds and three scales', () => {
+    expect([...MIGRATION_KINDS]).toEqual(['migration', 'refugees', 'diaspora', 'exodus']);
+    expect([...MIGRATION_SCALES]).toEqual(['small', 'moderate', 'large']);
+  });
+});
+
+describe('isMigrationKind / isMigrationScale', () => {
+  it('accepts each known kind and rejects unknown / non-strings', () => {
+    for (const k of MIGRATION_KINDS) expect(isMigrationKind(k)).toBe(true);
+    expect(isMigrationKind('immigration')).toBe(false);
+    expect(isMigrationKind(42)).toBe(false);
+    expect(isMigrationKind(undefined)).toBe(false);
+  });
+
+  it('accepts each known scale and rejects unknown / non-strings', () => {
+    for (const s of MIGRATION_SCALES) expect(isMigrationScale(s)).toBe(true);
+    expect(isMigrationScale('massive')).toBe(false);
+    expect(isMigrationScale(42)).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Effect tables
+// ---------------------------------------------------------------------------
+
+describe('MIGRATION_SOURCE_EFFECTS / MIGRATION_DESTINATION_EFFECTS', () => {
+  it('every source scale dips exactly population and economy (both negative)', () => {
+    for (const s of MIGRATION_SCALES) {
+      const dips = MIGRATION_SOURCE_EFFECTS[s];
+      expect(Object.keys(dips).sort()).toEqual(['economy', 'population']);
+      expect(dips.population).toBeLessThan(0);
+      expect(dips.economy).toBeLessThan(0);
+    }
+  });
+
+  it('every destination scale gains exactly population and economy (both positive)', () => {
+    for (const s of MIGRATION_SCALES) {
+      const gains = MIGRATION_DESTINATION_EFFECTS[s];
+      expect(Object.keys(gains).sort()).toEqual(['economy', 'population']);
+      expect(gains.population).toBeGreaterThan(0);
+      expect(gains.economy).toBeGreaterThan(0);
+    }
+  });
+
+  it('source loses and destination gains monotonically with scale', () => {
+    const [small, moderate, large] = MIGRATION_SCALES;
+    const srcPop = (s: MigrationScale) => MIGRATION_SOURCE_EFFECTS[s].population!;
+    const dstPop = (s: MigrationScale) => MIGRATION_DESTINATION_EFFECTS[s].population!;
+    // A larger scale means the source LOSES more: the (negative) dip grows more
+    // negative as the scale grows, i.e. small > moderate > large.
+    expect(srcPop(small)).toBeGreaterThan(srcPop(moderate));
+    expect(srcPop(moderate)).toBeGreaterThan(srcPop(large));
+    // A larger scale means the destination GAINS more: the (positive) gain
+    // grows larger as the scale grows, i.e. small < moderate < large.
+    expect(dstPop(small)).toBeLessThan(dstPop(moderate));
+    expect(dstPop(moderate)).toBeLessThan(dstPop(large));
+  });
+
+  it('the large-influx stability strain is a small negative dip', () => {
+    expect(LARGE_INFLUX_STABILITY_DIP).toBeLessThan(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// validateMigrationOps
+// ---------------------------------------------------------------------------
+
+describe('validateMigrationOps', () => {
+  it('accepts the { ops: [...] } object shape and a bare array', () => {
+    const op = { kind: 'migration', from: 'a', to: 'b', scale: 'small' };
+    expect(validateMigrationOps({ ops: [op] })).toEqual([op]);
+    expect(validateMigrationOps([op])).toEqual([op]);
+  });
+
+  it('drops an op with an unknown / missing kind', () => {
+    expect(validateMigrationOps([{ kind: 'tsunami', from: 'a', to: 'b', scale: 'small' }])).toEqual(
+      [],
+    );
+    expect(
+      validateMigrationOps([
+        { from: 'a', to: 'b', scale: 'small' },
+        { kind: 'migration', from: 'a', to: 'b', scale: 'small' },
+      ]),
+    ).toEqual([{ kind: 'migration', from: 'a', to: 'b', scale: 'small' }]);
+  });
+
+  it('drops an op with an unknown / missing scale', () => {
+    expect(validateMigrationOps([{ kind: 'migration', from: 'a', to: 'b', scale: 'massive' }])).toEqual(
+      [],
+    );
+    expect(validateMigrationOps([{ kind: 'migration', from: 'a', to: 'b' }])).toEqual([]);
+  });
+
+  it('drops an op with an empty / missing from (the source)', () => {
+    expect(validateMigrationOps([{ kind: 'migration', from: '', to: 'b', scale: 'small' }])).toEqual(
+      [],
+    );
+    expect(validateMigrationOps([{ kind: 'migration', to: 'b', scale: 'small' }])).toEqual([]);
+  });
+
+  it('requires a non-empty `to` for every kind except exodus', () => {
+    // non-exodus kind missing `to`: dropped
+    expect(validateMigrationOps([{ kind: 'migration', from: 'a', scale: 'small' }])).toEqual([]);
+    expect(validateMigrationOps([{ kind: 'refugees', from: 'a', scale: 'small' }])).toEqual([]);
+    // exodus without a `to`: kept (an exodus has no destination)
+    expect(validateMigrationOps([{ kind: 'exodus', from: 'a', scale: 'small' }])).toEqual([
+      { kind: 'exodus', from: 'a', scale: 'small' },
+    ]);
+  });
+
+  it('caps `from` / `to` at 200 chars and `detail` at 300, dropping empty detail', () => {
+    const longFrom = 'f'.repeat(500);
+    const longDetail = 'd'.repeat(500);
+    const out = validateMigrationOps([
+      { kind: 'migration', from: longFrom, to: 'b', scale: 'small', detail: longDetail },
+    ]);
+    expect(out).toHaveLength(1);
+    expect(out[0].from).toHaveLength(200);
+    expect(out[0].detail).toHaveLength(300);
+  });
+
+  it('a missing / malformed top-level value yields an empty list', () => {
+    expect(validateMigrationOps(undefined)).toEqual([]);
+    expect(validateMigrationOps(null)).toEqual([]);
+    expect(validateMigrationOps('nope')).toEqual([]);
+    expect(validateMigrationOps({ ops: 'nope' })).toEqual([]);
+    expect(validateMigrationOps([{ kind: 'migration' }])).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// shiftRelationTowardPositive
+// ---------------------------------------------------------------------------
+
+describe('shiftRelationTowardPositive', () => {
+  function pair(rel: Record<string, RelationStatus>): GameState {
+    return mkState(
+      {
+        a1: mkNation('a1', 'Alpha', NS(50, 50, 50, 50), ['a-r1'], rel),
+        b2: mkNation('b2', 'Bravo', NS(50, 50, 50, 50), ['b-r1'], rel),
+      },
+      { 'a-r1': RS(50, 50, 50, 50), 'b-r1': RS(50, 50, 50, 50) },
+    );
+  }
+
+  it('nudges a neutral pair one step toward positive, symmetrically', () => {
+    const s = pair({ b2: 'neutral', a1: 'neutral' });
+    shiftRelationTowardPositive(s, 'a1', 'b2', 'ally');
+    expect(s.nations.a1.relations.b2).toBe('ally');
+    expect(s.nations.b2.relations.a1).toBe('ally');
+  });
+
+  it('never moves past the cap (migration/diaspora cap at neutral)', () => {
+    // hostile → rival (one step toward positive, still below the neutral cap)
+    let s = pair({ b2: 'hostile', a1: 'hostile' });
+    shiftRelationTowardPositive(s, 'a1', 'b2', 'neutral');
+    expect(s.nations.a1.relations.b2).toBe('rival');
+    // rival → neutral (reaches the cap)
+    s = pair({ b2: 'rival', a1: 'rival' });
+    shiftRelationTowardPositive(s, 'a1', 'b2', 'neutral');
+    expect(s.nations.a1.relations.b2).toBe('neutral');
+    // neutral → stays neutral (at the cap)
+    s = pair({ b2: 'neutral', a1: 'neutral' });
+    shiftRelationTowardPositive(s, 'a1', 'b2', 'neutral');
+    expect(s.nations.a1.relations.b2).toBe('neutral');
+    // ally → stays ally (more positive than the cap)
+    s = pair({ b2: 'ally', a1: 'ally' });
+    shiftRelationTowardPositive(s, 'a1', 'b2', 'neutral');
+    expect(s.nations.a1.relations.b2).toBe('ally');
+  });
+
+  it('refugees can nudge all the way to ally (cap ally)', () => {
+    let s = pair({ b2: 'hostile', a1: 'hostile' });
+    shiftRelationTowardPositive(s, 'a1', 'b2', 'ally');
+    expect(s.nations.a1.relations.b2).toBe('rival');
+    s = pair({ b2: 'rival', a1: 'rival' });
+    shiftRelationTowardPositive(s, 'a1', 'b2', 'ally');
+    expect(s.nations.a1.relations.b2).toBe('neutral');
+    s = pair({ b2: 'neutral', a1: 'neutral' });
+    shiftRelationTowardPositive(s, 'a1', 'b2', 'ally');
+    expect(s.nations.a1.relations.b2).toBe('ally');
+    // already ally: no change
+    s = pair({ b2: 'ally', a1: 'ally' });
+    shiftRelationTowardPositive(s, 'a1', 'b2', 'ally');
+    expect(s.nations.a1.relations.b2).toBe('ally');
+  });
+
+  it('a missing relation starts at neutral and nudges toward the cap', () => {
+    const s = pair({});
+    shiftRelationTowardPositive(s, 'a1', 'b2', 'ally');
+    expect(s.nations.a1.relations.b2).toBe('ally');
+    expect(s.nations.b2.relations.a1).toBe('ally');
+  });
+
+  it('never touches a war relation', () => {
+    const s = pair({ b2: 'war', a1: 'war' });
+    shiftRelationTowardPositive(s, 'a1', 'b2', 'ally');
+    expect(s.nations.a1.relations.b2).toBe('war');
+    expect(s.nations.b2.relations.a1).toBe('war');
+  });
+
+  it('is a no-op for an unknown nation id or an unknown cap', () => {
+    const s = pair({ b2: 'hostile', a1: 'hostile' });
+    shiftRelationTowardPositive(s, 'a1', 'zzz', 'ally'); // zzz absent
+    expect(s.nations.a1.relations.b2).toBe('hostile');
+    shiftRelationTowardPositive(s, 'a1', 'b2', 'nope' as RelationStatus); // bad cap
+    expect(s.nations.a1.relations.b2).toBe('hostile');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// applyMigrationOp
+// ---------------------------------------------------------------------------
+
+describe('applyMigrationOp', () => {
+  it('a small migration: source loses pop+eco, destination gains pop+eco, relation unchanged (neutral→neutral)', () => {
+    const state = mkState(
+      {
+        a1: mkNation('a1', 'Alpha', NS(80, 70, 60, 50), ['a-r1']),
+        b2: mkNation('b2', 'Bravo', NS(40, 30, 50, 60), ['b-r1']),
+      },
+      { 'a-r1': RS(80, 70, 60, 50), 'b-r1': RS(40, 30, 50, 60) },
+    );
+    applyMigrationOp(state, { kind: 'migration', from: 'a1', to: 'b2', scale: 'small' });
+    // source: economy 70→69, population 50→49 (re-derived from its single region)
+    expect(state.nations.a1.stats).toEqual(NS(80, 69, 60, 49));
+    // destination: economy 30→31, population 60→61
+    expect(state.nations.b2.stats).toEqual(NS(40, 31, 50, 61));
+    // both regions mirrored
+    expect(state.regionStats['a-r1']).toEqual(RS(80, 69, 60, 49));
+    expect(state.regionStats['b-r1']).toEqual(RS(40, 31, 50, 61));
+    // a neutral pair is already at the neutral cap: no relation change
+    expect(state.nations.a1.relations.b2 ?? 'neutral').toBe('neutral');
+    expect(state.nations.b2.relations.a1 ?? 'neutral').toBe('neutral');
+  });
+
+  it('resolves `from` / `to` by name (not just id)', () => {
+    const state = mkState(
+      {
+        a1: mkNation('a1', 'Alpha', NS(80, 70, 60, 50), ['a-r1']),
+        b2: mkNation('b2', 'Bravo', NS(40, 30, 50, 60), ['b-r1']),
+      },
+      { 'a-r1': RS(80, 70, 60, 50), 'b-r1': RS(40, 30, 50, 60) },
+    );
+    applyMigrationOp(state, { kind: 'migration', from: 'Alpha', to: 'Bravo', scale: 'moderate' });
+    // moderate: source pop -2 / eco -2; destination pop +2 / eco +2
+    expect(state.nations.a1.stats).toEqual(NS(80, 68, 60, 48));
+    expect(state.nations.b2.stats).toEqual(NS(40, 32, 50, 62));
+  });
+
+  it('a large influx strains the destination stability by 2', () => {
+    const state = mkState(
+      {
+        a1: mkNation('a1', 'Alpha', NS(80, 70, 60, 50), ['a-r1']),
+        b2: mkNation('b2', 'Bravo', NS(40, 30, 50, 60), ['b-r1']),
+      },
+      { 'a-r1': RS(80, 70, 60, 50), 'b-r1': RS(40, 30, 50, 60) },
+    );
+    applyMigrationOp(state, { kind: 'refugees', from: 'a1', to: 'b2', scale: 'large' });
+    // destination: eco 30→33, pop 60→63, stability 50→48 (large influx strain)
+    expect(state.nations.b2.stats).toEqual(NS(40, 33, 48, 63));
+    expect(state.regionStats['b-r1']).toEqual(RS(40, 33, 48, 63));
+    // source: eco 70→67, pop 50→46
+    expect(state.nations.a1.stats).toEqual(NS(80, 67, 60, 46));
+  });
+
+  it('a refugees flow nudges the relation toward ally (cap ally); migration/diaspora stop at neutral', () => {
+    const mk = (rel: RelationStatus) =>
+      mkState(
+        {
+          a1: mkNation('a1', 'Alpha', NS(80, 70, 60, 50), ['a-r1'], { b2: rel }),
+          b2: mkNation('b2', 'Bravo', NS(40, 30, 50, 60), ['b-r1'], { a1: rel }),
+        },
+        { 'a-r1': RS(80, 70, 60, 50), 'b-r1': RS(40, 30, 50, 60) },
+      );
+    // refugees: hostile → rival
+    let s = mk('hostile');
+    applyMigrationOp(s, { kind: 'refugees', from: 'a1', to: 'b2', scale: 'small' });
+    expect(s.nations.a1.relations.b2).toBe('rival');
+    // migration: hostile → rival (capped at neutral, one step only)
+    s = mk('hostile');
+    applyMigrationOp(s, { kind: 'migration', from: 'a1', to: 'b2', scale: 'small' });
+    expect(s.nations.a1.relations.b2).toBe('rival');
+    // migration: rival → neutral (reaches cap)
+    s = mk('rival');
+    applyMigrationOp(s, { kind: 'diaspora', from: 'a1', to: 'b2', scale: 'small' });
+    expect(s.nations.a1.relations.b2).toBe('neutral');
+    // refugees: neutral → ally
+    s = mk('neutral');
+    applyMigrationOp(s, { kind: 'refugees', from: 'a1', to: 'b2', scale: 'small' });
+    expect(s.nations.a1.relations.b2).toBe('ally');
+  });
+
+  it('never nudges a warring pair (a war is left untouched)', () => {
+    const state = mkState(
+      {
+        a1: mkNation('a1', 'Alpha', NS(80, 70, 60, 50), ['a-r1'], { b2: 'war' }),
+        b2: mkNation('b2', 'Bravo', NS(40, 30, 50, 60), ['b-r1'], { a1: 'war' }),
+      },
+      { 'a-r1': RS(80, 70, 60, 50), 'b-r1': RS(40, 30, 50, 60) },
+    );
+    applyMigrationOp(state, { kind: 'refugees', from: 'a1', to: 'b2', scale: 'large' });
+    expect(state.nations.a1.relations.b2).toBe('war');
+    expect(state.nations.b2.relations.a1).toBe('war');
+    // the stat effects still apply (a war does not block population movement)
+    expect(state.nations.a1.stats).toEqual(NS(80, 67, 60, 46));
+    expect(state.nations.b2.stats).toEqual(NS(40, 33, 48, 63));
+  });
+
+  it('an exodus only affects the source: no destination, no relation nudge', () => {
+    const state = mkState(
+      {
+        a1: mkNation('a1', 'Alpha', NS(80, 70, 60, 50), ['a-r1'], { b2: 'rival' }),
+        b2: mkNation('b2', 'Bravo', NS(40, 30, 50, 60), ['b-r1'], { a1: 'rival' }),
+      },
+      { 'a-r1': RS(80, 70, 60, 50), 'b-r1': RS(40, 30, 50, 60) },
+    );
+    applyMigrationOp(state, { kind: 'exodus', from: 'a1', scale: 'small' });
+    // source dips
+    expect(state.nations.a1.stats).toEqual(NS(80, 69, 60, 49));
+    // destination untouched
+    expect(state.nations.b2.stats).toEqual(NS(40, 30, 50, 60));
+    expect(state.regionStats['b-r1']).toEqual(RS(40, 30, 50, 60));
+    // no relation nudge
+    expect(state.nations.a1.relations.b2).toBe('rival');
+  });
+
+  it('a self-flow (from === to) is dropped entirely', () => {
+    const state = mkState(
+      { a1: mkNation('a1', 'Alpha', NS(80, 70, 60, 50), ['a-r1']) },
+      { 'a-r1': RS(80, 70, 60, 50) },
+    );
+    applyMigrationOp(state, { kind: 'migration', from: 'a1', to: 'a1', scale: 'large' });
+    // no change at all
+    expect(state.nations.a1.stats).toEqual(NS(80, 70, 60, 50));
+    expect(state.regionStats['a-r1']).toEqual(RS(80, 70, 60, 50));
+  });
+
+  it('an unknown or ambiguous source / destination drops the op', () => {
+    const base = () =>
+      mkState(
+        {
+          a1: mkNation('a1', 'Alpha', NS(80, 70, 60, 50), ['a-r1']),
+          b2: mkNation('b2', 'Bravo', NS(40, 30, 50, 60), ['b-r1']),
+        },
+        { 'a-r1': RS(80, 70, 60, 50), 'b-r1': RS(40, 30, 50, 60) },
+      );
+    // unknown source
+    let s = base();
+    applyMigrationOp(s, { kind: 'migration', from: 'zzz', to: 'b2', scale: 'small' });
+    expect(s.nations.b2.stats).toEqual(NS(40, 30, 50, 60));
+    // unknown destination
+    s = base();
+    applyMigrationOp(s, { kind: 'migration', from: 'a1', to: 'zzz', scale: 'small' });
+    expect(s.nations.a1.stats).toEqual(NS(80, 70, 60, 50));
+    // ambiguous source (two nations share the name)
+    const amb = mkState(
+      {
+        a1: mkNation('a1', 'Twin', NS(80, 70, 60, 50), ['a-r1']),
+        a2: mkNation('a2', 'Twin', NS(20, 20, 20, 20), ['a-r2']),
+        b2: mkNation('b2', 'Bravo', NS(40, 30, 50, 60), ['b-r1']),
+      },
+      { 'a-r1': RS(80, 70, 60, 50), 'a-r2': RS(20, 20, 20, 20), 'b-r1': RS(40, 30, 50, 60) },
+    );
+    applyMigrationOp(amb, { kind: 'migration', from: 'Twin', to: 'Bravo', scale: 'small' });
+    expect(amb.nations.b2.stats).toEqual(NS(40, 30, 50, 60));
+  });
+
+  it('a 0-region nation keeps its directly-mutated stats (no re-derive)', () => {
+    const state = mkState(
+      {
+        // a1 owns no regions — its stats are maintained directly, not derived
+        a1: mkNation('a1', 'Alpha', NS(80, 70, 60, 50), []),
+        b2: mkNation('b2', 'Bravo', NS(40, 30, 50, 60), ['b-r1']),
+      },
+      { 'b-r1': RS(40, 30, 50, 60) },
+    );
+    applyMigrationOp(state, { kind: 'migration', from: 'a1', to: 'b2', scale: 'moderate' });
+    // source (0 regions) keeps the direct dip: eco 70→68, pop 50→48
+    expect(state.nations.a1.stats).toEqual(NS(80, 68, 60, 48));
+    // destination re-derived from its region
+    expect(state.nations.b2.stats).toEqual(NS(40, 32, 50, 62));
+  });
+
+  it('never moves territory (sole ownership untouched)', () => {
+    const state = mkState(
+      {
+        a1: mkNation('a1', 'Alpha', NS(80, 70, 60, 50), ['a-r1']),
+        b2: mkNation('b2', 'Bravo', NS(40, 30, 50, 60), ['b-r1']),
+      },
+      { 'a-r1': RS(80, 70, 60, 50), 'b-r1': RS(40, 30, 50, 60) },
+    );
+    applyMigrationOp(state, { kind: 'refugees', from: 'a1', to: 'b2', scale: 'large' });
+    expect(state.nations.a1.territory).toEqual(['a-r1']);
+    expect(state.nations.b2.territory).toEqual(['b-r1']);
+  });
+
+  it('clamps affected stats to 0 and 100 (a source at the floor, a destination at the ceiling)', () => {
+    const state = mkState(
+      {
+        // a1 at the population / economy floor
+        a1: mkNation('a1', 'Alpha', NS(5, 3, 50, 1), ['a-r1']),
+        // b2 near the ceiling: a large gain (+3) pushes it past 100
+        b2: mkNation('b2', 'Bravo', NS(90, 98, 50, 98), ['b-r1']),
+      },
+      { 'a-r1': RS(5, 3, 50, 1), 'b-r1': RS(90, 98, 50, 98) },
+    );
+    applyMigrationOp(state, { kind: 'migration', from: 'a1', to: 'b2', scale: 'large' });
+    // source clamps at 0 (pop 1-4→0, eco 3-3→0)
+    expect(state.nations.a1.stats.population).toBe(0);
+    expect(state.nations.a1.stats.economy).toBe(0);
+    // destination gains but clamps at 100 (pop 98+3→100, eco 98+3→100)
+    expect(state.nations.b2.stats.population).toBe(100);
+    expect(state.nations.b2.stats.economy).toBe(100);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// The Ability object contract
+// ---------------------------------------------------------------------------
+
+describe('migration ability', () => {
+  it('owns the "migration" field; default() is a fresh empty { ops: [] }', () => {
+    expect(migration.field).toBe('migration');
+    expect(migration.default()).toEqual({ ops: [] });
+    expect(migration.default()).not.toBe(migration.default());
+  });
+
+  it('default() is not meaningful; a populated value is', () => {
+    expect(migration.isMeaningful(migration.default())).toBe(false);
+    expect(
+      migration.isMeaningful({ ops: [{ kind: 'exodus', from: 'a1', scale: 'small' }] }),
+    ).toBe(true);
+  });
+
+  it('validate() wraps the bare-list validator into the { ops } shape', () => {
+    expect(
+      migration.validate([{ kind: 'migration', from: 'a1', to: 'b2', scale: 'small' }]),
+    ).toEqual({ ops: [{ kind: 'migration', from: 'a1', to: 'b2', scale: 'small' }] });
+    expect(migration.validate(undefined)).toEqual({ ops: [] });
+  });
+
+  it('the stub value equals default() (the stub never proposes a migration)', () => {
+    expect(migration.stub()).toEqual({ ops: [] });
+  });
+
+  it('payload() is always empty (turn-transient — no durable state to show)', () => {
+    expect(migration.payload({} as never)).toEqual({});
+  });
+
+  it('stateFields is undefined (the layer owns no durable GameState field)', () => {
+    expect(migration.stateFields).toBeUndefined();
+  });
+
+  it('apply() runs each validated op against the world (no throw on a bad ref)', () => {
+    const state = mkState(
+      {
+        a1: mkNation('a1', 'Alpha', NS(80, 70, 60, 50), ['a-r1']),
+        b2: mkNation('b2', 'Bravo', NS(40, 30, 50, 60), ['b-r1']),
+      },
+      { 'a-r1': RS(80, 70, 60, 50), 'b-r1': RS(40, 30, 50, 60) },
+    );
+    const ctx = { previous: state, actingTurn: state.turn };
+    migration.apply(
+      state,
+      {
+        ops: [
+          { kind: 'migration', from: 'a1', to: 'b2', scale: 'small' },
+          // an unknown source — must be dropped, not throw
+          { kind: 'refugees', from: 'ghost', to: 'b2', scale: 'small' },
+        ],
+      },
+      ctx,
+    );
+    expect(state.nations.a1.stats).toEqual(NS(80, 69, 60, 49));
+    expect(state.nations.b2.stats).toEqual(NS(40, 31, 50, 61));
+  });
+});

server/abilities/migration.ts

@@ -0,0 +1,325 @@
+// The MIGRATION & REFUGEES ability (v0.42.0, #64) as a modular LLM-ability
+// (v0.40.0, #67). People moving between nations each turn: ordinary migration,
+// refugee flows (fleeing a war or disaster), a spreading diaspora, and an
+// exodus (people leaving with no destination). Unlike most other abilities this
+// one is **turn-transient**: it owns NO `GameState` field (no durable list, no
+// `db.ts` change) — exactly like the hybrid and disasters layers. Each op
+// carries a `kind`, a source `from` (the nation people leave), a destination
+// `to` (required for every kind except `exodus`), and a `scale` (small /
+// moderate / large). The engine applies a DETERMINISTIC effect chosen from the
+// per-`scale` tables below (no hidden randomness — the LLM chooses the kind and
+// scale, the tables decide the magnitude): the source LOSES a small amount of
+// population and economy, the destination GAINS a small amount of population and
+// economy (a `large` influx additionally strains the destination's stability),
+// both clamped to 0–100, mirrored to each side's regions (`regionStats`), and
+// each side's derived `stats` re-derived afterwards (the same 0-region /
+// no-entry guards as hybrid / economy / disasters, so a 0-region nation keeps
+// its directly-mutated value and the effect persists to the next turn). The
+// from↔to relation then moves one step toward the positive end of the
+// ally/neutral/rival/hostile ladder (`shiftRelationTowardPositive`) — capped at
+// `ally` for `refugees` (hosting refugees builds the strongest goodwill),
+// `neutral` for `migration` / `diaspora` (milder ties), and not at all for
+// `exodus`; a `war` relation is never touched (the nudge neither fabricates nor
+// escalates a war). Both `from` and `to` are resolved by the shared
+// `resolveNationRef` (id first, then a case-insensitive unique name); an
+// unknown / ambiguous ref, a missing `to` (for a non-`exodus` kind), or a
+// self-flow (`from` and `to` the same nation) drops the whole op. It never
+// moves territory (sole ownership is untouched).
+
+import { clampStat, deriveNationStats } from '../../shared/protocol';
+import type { MigrationOp, MigrationScale, MigrationKind } from '../../shared/protocol';
+import type { GameState, Nation, RelationStatus, StatKey } from '../../shared/types';
+import { resolveNationRef, str } from './shared';
+import type { Ability } from './types';
+
+/** The four kinds of population flow a turn can declare (v0.42.0, #64). */
+export const MIGRATION_KINDS: readonly MigrationKind[] = [
+  'migration',
+  'refugees',
+  'diaspora',
+  'exodus',
+];
+
+/** The three flow sizes a migration op can carry (v0.42.0, #64). */
+export const MIGRATION_SCALES: readonly MigrationScale[] = ['small', 'moderate', 'large'];
+
+const VALID_KINDS = new Set<string>(MIGRATION_KINDS);
+const VALID_SCALES = new Set<string>(MIGRATION_SCALES);
+
+/** True when `k` is one of the four known migration kinds (v0.42.0, #64). */
+export function isMigrationKind(k: unknown): k is MigrationKind {
+  return typeof k === 'string' && VALID_KINDS.has(k);
+}
+
+/** True when `s` is one of the three known migration scales (v0.42.0, #64). */
+export function isMigrationScale(s: unknown): s is MigrationScale {
+  return typeof s === 'string' && VALID_SCALES.has(s);
+}
+
+/**
+ * (v0.42.0, #64) The DETERMINISTIC per-`scale` stat dip applied to the SOURCE
+ * nation of a migration flow (the nation people leave). Each scale maps to a
+ * small set of signed (negative) stat deltas: the source loses population and
+ * economy. No hidden randomness — the LLM picks the scale, the table decides
+ * the magnitude. Military and stability are untouched by the source dip.
+ */
+export const MIGRATION_SOURCE_EFFECTS: Record<MigrationScale, Partial<Record<StatKey, number>>> = {
+  small: { population: -1, economy: -1 },
+  moderate: { population: -2, economy: -2 },
+  large: { population: -4, economy: -3 },
+};
+
+/**
+ * (v0.42.0, #64) The DETERMINISTIC per-`scale` stat gain applied to the
+ * DESTINATION nation of a migration flow (the nation people arrive in). Each
+ * scale maps to a small set of signed (positive) stat deltas: the destination
+ * gains population and economy. No hidden randomness. Military and stability
+ * are untouched by the base gain (the `large`-scale stability strain is applied
+ * separately, see {@link LARGE_INFLUX_STABILITY_DIP}).
+ */
+export const MIGRATION_DESTINATION_EFFECTS: Record<MigrationScale, Partial<Record<StatKey, number>>> =
+  {
+    small: { population: 1, economy: 1 },
+    moderate: { population: 2, economy: 2 },
+    large: { population: 3, economy: 3 },
+  };
+
+/**
+ * (v0.42.0, #64) The extra STABILITY dip applied to the destination of a
+ * `large`-scale influx only — a big population surge strains a society even as
+ * it grows. Added on top of the base destination gain.
+ */
+export const LARGE_INFLUX_STABILITY_DIP = -2;
+
+/**
+ * The positive-relations ladder, strongest (most positive) to weakest
+ * (least positive) — the same four non-war statuses, in the order a relation
+ * moves when it is nudged TOWARD the positive end. A missing relation is
+ * treated as `neutral`; `war` is never touched (a war is its own entity — a
+ * population flow neither fabricates nor escalates one). The `cap` in
+ * {@link shiftRelationTowardPositive} is a member of this array.
+ */
+const POSITIVE_ORDER: RelationStatus[] = ['ally', 'neutral', 'rival', 'hostile'];
+
+/**
+ * (v0.42.0, #64) Nudge the bilateral relation between nations `a` and `b`
+ * ONE step toward the POSITIVE end (toward `ally`) of the
+ * {@link POSITIVE_ORDER} ladder, applied symmetrically to both directions, but
+ * never past the given `cap`. A missing relation starts at `neutral`; a `war`
+ * relation is never touched (a population flow neither fabricates nor
+ * escalates a war — a warring pair is left exactly as it is). Mutates `state`
+ * in place (the caller passes a clone — applyTurnResult does). Never throws.
+ *
+ * `cap` is the most-positive status the nudge may reach:
+ *   - `refugees`   → `ally`     (hosting refugees builds the strongest goodwill)
+ *   - `migration` / `diaspora` → `neutral`  (milder ties)
+ *   - `exodus`     → no nudge at all
+ */
+export function shiftRelationTowardPositive(
+  state: GameState,
+  a: string,
+  b: string,
+  cap: RelationStatus,
+): void {
+  const na = state.nations[a];
+  const nb = state.nations[b];
+  if (!na || !nb) return;
+  const capIdx = POSITIVE_ORDER.indexOf(cap);
+  if (capIdx === -1) return; // unknown cap: no-op (defensive)
+  const step = (cur: RelationStatus | undefined): RelationStatus | null => {
+    if (cur === 'war') return null; // never touch a war relation
+    const s = cur ?? 'neutral'; // a missing relation is neutral
+    const i = POSITIVE_ORDER.indexOf(s);
+    if (i === -1) return 'neutral'; // defensive: unknown status
+    if (i <= capIdx) return s; // already at or more positive than the cap: no change
+    return POSITIVE_ORDER[i - 1]; // one step toward the positive end
+  };
+  const stepA = step(na.relations[b]);
+  if (stepA !== null) na.relations[b] = stepA;
+  const stepB = step(nb.relations[a]);
+  if (stepB !== null) nb.relations[a] = stepB;
+}
+
+/**
+ * (v0.42.0, #64) Validate the raw `migration` field of a turn into a safe
+ * list of {@link MigrationOp}s. Defensive like the rest of the parser — never
+ * throws. The raw value may be the object `{ ops: [...] }` (the TurnResult
+ * shape) or a bare array (be lenient about either). Each op needs a known
+ * `kind` (one of {@link MIGRATION_KINDS}), a known `scale` (one of
+ * {@link MIGRATION_SCALES}), a non-empty `from` (the source nation, capped at
+ * 200 chars), and — for every kind except `exodus` — a non-empty `to`
+ * (the destination nation, capped at 200 chars); a non-empty `detail` is capped
+ * at 300 chars. An op with an unknown / missing `kind`, an unknown / missing
+ * `scale`, an empty `from`, or (for a non-`exodus` kind) an empty `to` is
+ * dropped. Resolution of `from` / `to` to concrete nation ids happens at apply
+ * time (`applyMigrationOp`), not here. A missing / malformed top-level value
+ * yields `{ ops: [] }`.
+ */
+export function validateMigrationOps(raw: unknown): MigrationOp[] {
+  let list: unknown[] | null = null;
+  if (Array.isArray(raw)) {
+    list = raw;
+  } else if (raw && typeof raw === 'object') {
+    const inner = (raw as Record<string, unknown>).ops;
+    if (Array.isArray(inner)) list = inner;
+  }
+  if (!list) return [];
+  const out: MigrationOp[] = [];
+  for (const e of list) {
+    if (!e || typeof e !== 'object') continue;
+    const o = e as Record<string, unknown>;
+    if (!isMigrationKind(o.kind)) continue; // unknown / missing kind: drop
+    if (!isMigrationScale(o.scale)) continue; // unknown / missing scale: drop
+    const from = str(o.from, 200);
+    if (!from) continue; // empty / missing source: drop
+    const detail = str(o.detail, 300);
+    if (o.kind === 'exodus') {
+      // an exodus has no destination — `to` is optional (and ignored)
+      out.push({
+        kind: o.kind,
+        from,
+        scale: o.scale,
+        ...(detail ? { detail } : {}),
+      });
+    } else {
+      const to = str(o.to, 200);
+      if (!to) continue; // non-exodus kind needs a destination: drop
+      out.push({
+        kind: o.kind,
+        from,
+        to,
+        scale: o.scale,
+        ...(detail ? { detail } : {}),
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * Apply a set of signed stat `dips` to a nation's `stats` AND to every region
+ * it owns that has a `regionStats` entry (clamped to 0–100), then re-derive
+ * the nation's aggregate `stats` as the area×population-weighted median of its
+ * regions — the same 0-region / no-entry guards as the hybrid / economy /
+ * disasters layers, so a 0-region nation keeps its directly-mutated value and
+ * the effect persists to the next turn. Mutates in place; never throws.
+ */
+function applyNationDips(
+  nation: Nation,
+  dips: Partial<Record<StatKey, number>>,
+  regionStats: GameState['regionStats'],
+  geoOf?: (key: string) => { area: number; population: number } | undefined,
+): void {
+  (Object.keys(dips) as StatKey[]).forEach((k) => {
+    const d = dips[k];
+    if (typeof d === 'number') nation.stats[k] = clampStat(nation.stats[k] + d);
+  });
+  for (const key of nation.territory) {
+    const rs = regionStats[key];
+    if (!rs) continue; // a key with no entry is skipped
+    (Object.keys(dips) as StatKey[]).forEach((k) => {
+      const d = dips[k];
+      if (typeof d === 'number') rs[k] = clampStat(rs[k] + d);
+    });
+  }
+  // Re-derive the nation's aggregate stats so the effect persists (the main
+  // recompute ran earlier this turn; without this the change would be washed
+  // out next turn). A nation with no regionStats entry keeps its
+  // directly-mutated `stats`.
+  if (nation.territory.length > 0 && nation.territory.some((k) => regionStats[k])) {
+    nation.stats = deriveNationStats(nation.territory, regionStats, geoOf);
+  }
+}
+
+/**
+ * (v0.42.0, #64) Apply ONE migration / refugee op to the (cloned) `next` state,
+ * mutating it in place and never throwing. Resolution order:
+ *   1. `from` must resolve to a nation (id first, then a unique name); an
+ *      unknown / ambiguous source drops the op.
+ *   2. For every kind except `exodus`, `to` must resolve to a nation distinct
+ *      from `from` (a missing / unknown / ambiguous destination, or a
+ *      self-flow, drops the op); `exodus` has no destination and skips this.
+ * Then the deterministic per-`scale` effects from
+ * {@link MIGRATION_SOURCE_EFFECTS} / {@link MIGRATION_DESTINATION_EFFECTS}
+ * are applied:
+ *   - the SOURCE nation loses population and economy (all four kinds,
+ *     including `exodus`) — for a non-`exodus` op this is applied only AFTER
+ *     the destination is validated, so a self-flow or a bad destination drops
+ *     the op entirely and never touches the source;
+ *   - for a non-`exodus` kind the DESTINATION gains population and economy,
+ *     and a `large` influx additionally strains its stability by
+ *     {@link LARGE_INFLUX_STABILITY_DIP};
+ *   - each affected nation's derived `stats` are re-derived afterwards (the
+ *     same 0-region / no-entry guards, so the effect persists);
+ *   - for a non-`exodus` kind the from↔to relation moves one step toward the
+ *     positive end of the ladder (cap `ally` for `refugees`, `neutral` for
+ *     `migration` / `diaspora`; a `war` relation is left untouched).
+ * The op never moves territory (sole ownership is untouched) and never creates
+ * or escalates a war.
+ */
+export function applyMigrationOp(
+  next: GameState,
+  op: MigrationOp,
+  geoOf?: (key: string) => { area: number; population: number } | undefined,
+): void {
+  const from = resolveNationRef(next, op.from);
+  if (from === null) return; // unknown / ambiguous source: drop
+  const source = next.nations[from];
+  if (!source) return; // defensive: resolved id has no nation record
+
+  if (op.kind === 'exodus') {
+    // An exodus has no destination: the source loses population and economy
+    // and that is all (no gain, no relation nudge).
+    applyNationDips(source, MIGRATION_SOURCE_EFFECTS[op.scale], next.regionStats, geoOf);
+    return;
+  }
+
+  // Non-exodus: resolve the destination FIRST and drop the WHOLE op (including
+  // the source dip) when it is missing / unknown / ambiguous or a self-flow —
+  // so a self-flow or a bad destination never touches the source.
+  const to = op.to;
+  if (!to) return; // defensive: a non-exodus op should always have a `to`
+  const destId = resolveNationRef(next, to);
+  if (destId === null || destId === from) return; // unknown / self destination: drop
+  const dest = next.nations[destId];
+  if (!dest) return; // defensive
+
+  // The source loses population and economy (every non-exodus kind reaches
+  // here; the exodus path already applied its source dip and returned).
+  applyNationDips(source, MIGRATION_SOURCE_EFFECTS[op.scale], next.regionStats, geoOf);
+
+  // The destination gains population and economy; a large influx also strains
+  // its stability.
+  const destDips: Partial<Record<StatKey, number>> = { ...MIGRATION_DESTINATION_EFFECTS[op.scale] };
+  if (op.scale === 'large') {
+    destDips.stability = (destDips.stability ?? 0) + LARGE_INFLUX_STABILITY_DIP;
+  }
+  applyNationDips(dest, destDips, next.regionStats, geoOf);
+
+  // The from↔to relation moves one step toward the positive end, capped by
+  // kind (a `war` relation is left untouched by shiftRelationTowardPositive).
+  const cap: RelationStatus = op.kind === 'refugees' ? 'ally' : 'neutral';
+  shiftRelationTowardPositive(next, from, destId, cap);
+}
+
+export const migration: Ability<'migration'> = {
+  field: 'migration',
+  default: () => ({ ops: [] }),
+  // The low-level validator returns a bare list; the field's shape is the
+  // `{ ops }` object (mirrors the historical TurnResult shape).
+  validate: (raw) => ({ ops: validateMigrationOps(raw) }),
+  apply: (state, data, ctx) => {
+    for (const op of data.ops) {
+      applyMigrationOp(state, op, ctx.geoOf);
+    }
+  },
+  schemaLine: () =>
+    '  "migration": {"ops":[{"kind":"<migration|refugees|diaspora|exodus>","from":"<nation id or name>","to":"<nation id or name>","scale":"<small|moderate|large>","detail":"<short detail>"}]},',
+  constraint: () =>
+    '- Migration & refugees ("migration.ops") are people moving between nations this turn: a "kind" ("migration", "refugees", "diaspora", or "exodus"), a "from" (the source nation — id or name), a "to" (the destination nation — required for every kind except "exodus", which has no destination), and a "scale" (small / moderate / large). The engine applies a DETERMINISTIC effect (no hidden randomness): the source LOSES a small amount of population and economy, the destination GAINS a small amount of population and economy (a "large" influx additionally strains the destination\'s stability by 2), and the from↔to relation moves one step toward the positive end of the ally/neutral/rival/hostile ladder — capped at "ally" for "refugees" (hosting refugees builds the strongest goodwill), capped at "neutral" for "migration"/"diaspora" (milder ties), and not at all for "exodus"; the nudge never creates or escalates a "war" (a warring pair is left untouched). The layer is turn-transient (no memory): a continuing flow is simply RE-DECLARED each turn it persists. It never moves borders — sole ownership is untouched. Propose at most 1-2 per turn and narrate each one in "events" (a "social" or "diplomatic" event).',
+  isMeaningful: (data) => data.ops.length > 0,
+  stub: () => ({ ops: [] }),
+  // The layer is turn-transient — it contributes nothing to the user payload
+  // (no durable state to show the model), so the payload is always empty.
+  payload: () => ({}),
+};

server/abilities/nuclear.ts

@@ -0,0 +1,336 @@
+// The NUCLEAR / WMD ability (v0.37, #60) as a modular LLM-ability (v0.40.0, #67).
+// The model may name nations to ARM with the nuclear flag (`nuclear.arm`) and
+// fire nuclear strikes (`nuclear.strikes`, from a capable nation at a nation or
+// a region). The deterministic effects (devastating the target, MAD retaliation,
+// ending the target's wars, forcing relations hostile, releasing struck regions
+// to no man's land) are all applied here. The apply bodies are moved VERBATIM
+// from the pre-refactor engine.ts; `NUCLEAR_COLLAPSE` / `NUCLEAR_RETALIATION` /
+// `isNuclearCapable` / `makeEvent` / `deriveNationStats` come from shared/protocol.
+
+import {
+  clampStat,
+  deriveNationStats,
+  isNuclearCapable,
+  makeEvent,
+  NUCLEAR_COLLAPSE,
+  NUCLEAR_RETALIATION,
+  type NuclearOps,
+  type NuclearStatKey,
+} from '../../shared/protocol';
+import type { GameState, Nation } from '../../shared/types';
+import { activeWarPairs } from './apply-helpers';
+import { resolveNationRef, resolveRegionKey, str } from './shared';
+import type { Ability } from './types';
+
+const NUCLEAR_STATS: NuclearStatKey[] = ['economy', 'military', 'stability'];
+
+/**
+ * (v0.37, #60) Validate the raw `nuclear` object of a turn into a safe
+ * {@link NuclearOps}. Defensive like the rest of the parser — never throws.
+ * `arm`: non-empty nation refs (capped at 120 chars), deduped; a ref is
+ * resolved (id or name) at APPLY time, so an unknown ref is dropped there, not
+ * here. `strikes`: each needs a non-empty `from` (the striking nation ref) and
+ * a non-empty `target` (a nation ref OR a region key), each capped at 120
+ * chars; a self-target (`from` and `target` the same ref) is dropped here. A
+ * missing / malformed top-level object yields `{ arm: [], strikes: [] }`.
+ */
+export function validateNuclearOps(raw: unknown): NuclearOps {
+  const out: NuclearOps = { arm: [], strikes: [] };
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return out;
+  const o = raw as Record<string, unknown>;
+  if (Array.isArray(o.arm)) {
+    for (const e of o.arm) {
+      const s = typeof e === 'string' ? e.trim() : '';
+      if (s && !out.arm.includes(s)) out.arm.push(s.slice(0, 120));
+    }
+  }
+  if (Array.isArray(o.strikes)) {
+    for (const e of o.strikes) {
+      if (!e || typeof e !== 'object') continue;
+      const s = e as Record<string, unknown>;
+      const from = str(s.from, 120);
+      const target = str(s.target, 120);
+      if (!from || !target) continue;
+      if (from.toLowerCase() === target.toLowerCase()) continue; // self-target: drop
+      out.strikes.push({ from, target });
+    }
+  }
+  return out;
+}
+
+/**
+ * Devastate a nation's stats by a delta profile (collapse / retaliation): each
+ * of the three nuclear stat keys is shifted by the given delta (clamped) on
+ * BOTH the nation and every region it owns. Never throws.
+ */
+function collapseNationStats(
+  next: GameState,
+  nationId: string,
+  collapse: Record<NuclearStatKey, number>,
+): void {
+  const n = next.nations[nationId];
+  if (!n) return;
+  for (const k of NUCLEAR_STATS) {
+    const d = collapse[k];
+    n.stats[k] = clampStat(n.stats[k] + d);
+    for (const key of n.territory) {
+      const rs = next.regionStats[key];
+      if (rs) rs[k] = clampStat(rs[k] + d);
+    }
+  }
+}
+
+/**
+ * Release a region key to no man's land, reusing the turn's release semantics:
+ * the key leaves its SOLE owner's territory, is marked in `GameState.unowned`,
+ * and its `regionStats` entry is deleted. A key with 0 or 2+ owners (or an
+ * already-unowned key) is left untouched. Never throws.
+ */
+function releaseRegionToNoMansLand(next: GameState, key: string): void {
+  if (next.unowned.includes(key)) return; // already no man's land
+  const owners = Object.values(next.nations).filter((n) => n.territory.includes(key));
+  if (owners.length !== 1) return; // 0 or 2+ owners: not releasable
+  next.nations[owners[0]!.id].territory = next.nations[owners[0]!.id].territory.filter(
+    (k) => k !== key,
+  );
+  next.unowned.push(key);
+  delete next.regionStats[key];
+}
+
+/**
+ * End every ACTIVE war whose sides include both `a` and `b` (a nuclear
+ * capitulation), then downgrade the `war` relation of every pair that is no
+ * longer covered by an active war back to `hostile` (the war → relation sync).
+ * Capturing the active pairs immediately BEFORE the end keeps this correct for
+ * a war declared and ended in the SAME turn (where the start-of-turn `prev`
+ * that `syncWarRelations` uses would not contain it). Never throws.
+ */
+function endWarsBetween(next: GameState, a: string, b: string): void {
+  const before = activeWarPairs(next.wars);
+  let ended = false;
+  for (const w of next.wars) {
+    if (w.status === 'active' && w.sides.includes(a) && w.sides.includes(b)) {
+      w.status = 'capitulation';
+      ended = true;
+    }
+  }
+  if (!ended) return;
+  const after = activeWarPairs(next.wars);
+  for (const key of before) {
+    if (after.has(key)) continue; // still covered by another active war
+    const [x, y] = key.split('\u0000');
+    const nx = next.nations[x];
+    const ny = next.nations[y];
+    if (!nx || !ny) continue;
+    if (nx.relations[y] === 'war' || ny.relations[x] === 'war') {
+      nx.relations[y] = 'hostile';
+      ny.relations[x] = 'hostile';
+    }
+  }
+}
+
+/**
+ * Force the relation between two nations to `hostile` in BOTH directions —
+ * the aftermath of a MAD exchange. A `war` relation is never downgraded (the
+ * war entity owns it while active — e.g. a region strike that devastates one
+ * warring side without ending the war). Never throws.
+ */
+function forceHostile(next: GameState, a: string, b: string): void {
+  const na = next.nations[a];
+  const nb = next.nations[b];
+  if (!na || !nb) return;
+  if (na.relations[b] !== 'war') na.relations[b] = 'hostile';
+  if (nb.relations[a] !== 'war') nb.relations[a] = 'hostile';
+}
+
+/**
+ * Apply a turn's nuclear ops to the (cloned) `next` state, mutating it in
+ * place and never throwing. See the section comment above for the full
+ * contract. `state` is the ORIGINAL (pre-turn) state — its `markers` supply the
+ * "owns a rocket" half of nuclear capability (a rocket marker placed this very
+ * turn makes its owner capable only from the next turn, while a nation that
+ * already owns one this turn is capable now).
+ */
+export function applyNuclearOps(
+  next: GameState,
+  ops: NuclearOps,
+  state: GameState,
+  geoOf?: (key: string) => { area: number; population: number } | undefined,
+  validKeys?: ReadonlySet<string>,
+  regionNameOf?: (key: string) => string | undefined,
+  actingTurn?: number,
+): void {
+  if (ops.arm.length === 0 && ops.strikes.length === 0) return;
+  const turn = actingTurn ?? next.turn;
+  const markers = state.markers ?? [];
+  const capable = (id: string): boolean => {
+    const n = next.nations[id];
+    return n ? isNuclearCapable(n, markers) : false;
+  };
+
+  // (1) ARM: set the nuclear flag (idempotent); unresolvable refs are dropped.
+  for (const ref of ops.arm) {
+    const id = resolveNationRef(next, ref);
+    if (id === null) continue;
+    const n = next.nations[id];
+    if (!n) continue;
+    n.nuclear = true;
+  }
+
+  const affected = new Set<string>();
+  const regionDisplay = (key: string): string => regionNameOf?.(key) ?? key;
+
+  // (2) STRIKES: each validated independently against the post-arm state.
+  for (const strike of ops.strikes) {
+    const fromId = resolveNationRef(next, strike.from);
+    if (fromId === null) continue; // unknown / ambiguous striker: drop
+    const from = next.nations[fromId];
+    if (!from) continue;
+    if (!capable(fromId)) continue; // a non-capable nation cannot strike
+    if (fromId === resolveNationRef(next, strike.target)) continue; // self: drop
+
+    // Resolve the target: a NATION (a ref resolving to a distinct nation) or a
+    // REGION (a region key / name with a sole owner that is not the striker).
+    let target:
+      | { kind: 'nation'; nation: Nation }
+      | { kind: 'region'; key: string; owner: Nation }
+      | null = null;
+    const tid = resolveNationRef(next, strike.target);
+    if (tid !== null) {
+      const tn = next.nations[tid];
+      if (tn) target = { kind: 'nation', nation: tn };
+    } else {
+      const rk = validKeys
+        ? resolveRegionKey(strike.target, validKeys, regionNameOf ?? (() => undefined))
+        : (strike.target.trim() || null);
+      if (rk !== null) {
+        const owners = Object.values(next.nations).filter((n) => n.territory.includes(rk));
+        if (owners.length === 1 && owners[0]!.id !== fromId) {
+          target = { kind: 'region', key: rk, owner: owners[0]! };
+        }
+        // a 0/2+-owner region, or a region the striker owns (self), is dropped
+      }
+    }
+    if (target === null) continue; // unresolvable target: drop
+
+    if (target.kind === 'nation') {
+      // Devastate the target nation.
+      collapseNationStats(next, target.nation.id, NUCLEAR_COLLAPSE);
+      affected.add(target.nation.id);
+      // A strike on a nation at war with the striker ends that war in
+      // capitulation (the relation then falls back to hostile).
+      endWarsBetween(next, fromId, target.nation.id);
+      // MAD: a nuclear-capable target strikes back at half strength and the
+      // two nations end the exchange at least hostile.
+      if (capable(target.nation.id)) {
+        collapseNationStats(next, fromId, NUCLEAR_RETALIATION);
+        affected.add(fromId);
+        forceHostile(next, fromId, target.nation.id);
+        next.events.push(
+          makeEvent(
+            {
+              nation: fromId,
+              type: 'military',
+              title: 'MAD retaliation',
+              text: `${target.nation.name} launches a retaliatory nuclear strike against ${from.name}; mutual assured destruction devastates ${from.name} in turn.`,
+              outcome: 'failure',
+            },
+            turn,
+            next.date,
+          ),
+        );
+      }
+      next.events.push(
+        makeEvent(
+          {
+            nation: fromId,
+            type: 'military',
+            title: `Nuclear strike on ${target.nation.name}`,
+            text: `${from.name} devastates ${target.nation.name} with a nuclear strike; the target's economy, military and stability collapse.`,
+            outcome: 'success',
+          },
+          turn,
+          next.date,
+        ),
+      );
+    } else {
+      // Devastate the region: release it to no man's land, then devastate its
+      // former owner.
+      const owner = target.owner;
+      releaseRegionToNoMansLand(next, target.key);
+      collapseNationStats(next, owner.id, NUCLEAR_COLLAPSE);
+      affected.add(owner.id);
+      // MAD: a nuclear-capable owner strikes back at half strength and the
+      // two nations end the exchange at least hostile.
+      if (capable(owner.id)) {
+        collapseNationStats(next, fromId, NUCLEAR_RETALIATION);
+        affected.add(fromId);
+        forceHostile(next, fromId, owner.id);
+        next.events.push(
+          makeEvent(
+            {
+              nation: fromId,
+              type: 'military',
+              title: 'MAD retaliation',
+              text: `${owner.name} launches a retaliatory nuclear strike against ${from.name} in response to the devastation of ${regionDisplay(
+                target.key,
+              )}; mutual assured destruction devastates ${from.name} in turn.`,
+              outcome: 'failure',
+            },
+            turn,
+            next.date,
+          ),
+        );
+      }
+      next.events.push(
+        makeEvent(
+          {
+            nation: fromId,
+            type: 'military',
+            title: `Nuclear strike on ${regionDisplay(target.key)}`,
+            text: `${from.name} obliterates ${regionDisplay(
+              target.key,
+            )} with a nuclear strike, reducing the region to no man's land and devastating its former owner, ${owner.name}.`,
+            outcome: 'success',
+          },
+          turn,
+          next.date,
+        ),
+      );
+    }
+  }
+
+  // (3) RE-DERIVE: every affected nation's aggregate stats (the same 0-region /
+  // no-entry guards as the main recompute), so the collapse persists.
+  for (const id of affected) {
+    const n = next.nations[id];
+    if (!n) continue;
+    if (n.territory.length === 0) continue; // 0-region guard: no regions to aggregate
+    if (!n.territory.some((k) => next.regionStats[k])) continue; // no entry: keep n.stats
+    n.stats = deriveNationStats(n.territory, next.regionStats, geoOf);
+  }
+}
+
+export const nuclear: Ability<'nuclear'> = {
+  field: 'nuclear',
+  default: () => ({ arm: [], strikes: [] }),
+  validate: (raw) => validateNuclearOps(raw),
+  apply: (state, data, ctx) => {
+    applyNuclearOps(
+      state,
+      data,
+      ctx.previous,
+      ctx.geoOf,
+      ctx.validRegionKeys,
+      ctx.regionNameOf,
+      ctx.actingTurn,
+    );
+  },
+  schemaLine: () =>
+    '  "nuclear": {"arm":["<nation id or name>"],"strikes":[{"from":"<nuclear-capable nation id or name>","target":"<nation id or name, or region key>"}]},',
+  constraint: () =>
+    '- Nuclear / WMD ("nuclear"): a nation is "nuclear-capable" when its "nuclear" flag is true or it currently owns a "rocket" marker. "arm" names (by id or name) nations to grant the "nuclear" flag — idempotent (already-armed nations are unchanged); a newly armed nation is capable this same turn. "strikes" is a list of "NuclearStrike" objects, each "{from, target}" — "from" is the striking nation (must be nuclear-capable and never itself) and "target" is either a nation (its nation collapses: economy -40, military -50, stability -40; every active war the target fights ends by capitulation and the "war" relations it caused downgrade to "hostile") or a region key (that region is released to no man\'s land, its regionStats entry deleted, and its sole owner collapses the same way — a region with 0 or 2+ owners, or one the striker itself owns, is dropped). If the struck nation (or the struck region\'s owner) is itself nuclear-capable, a "MAD" retaliation is applied: it strikes the striker back for half the collapse, and the two nations\' relations are forced to "hostile". At most one strike per turn; always narrate a strike (and a retaliation, if any) in "events".',
+  isMeaningful: (data) => data.arm.length > 0 || data.strikes.length > 0,
+  stub: () => ({ arm: [], strikes: [] }),
+  payload: () => ({}),
+};

server/abilities/registry.test.ts

@@ -0,0 +1,470 @@
+// The ordered LLM-ability registry: contract + golden-prompt tests (v0.40.0, #67).
+//
+// These tests pin the refactor's two load-bearing guarantees:
+//
+//   1. GOLDEN PROMPTS — the system prompt (both tool variants) and the user
+//      prompt the engine builds are BYTE-IDENTICAL to the committed golden
+//      fixtures in ./goldens/ (captured in P1 from the pre-refactor engine, and
+//      re-baselined when a feature INTENTIONALLY changes the prompt — e.g. the
+//      system goldens were regenerated in v0.41.0 when the disasters ability
+//      was added). Any transcription drift in an ability's schemaLine /
+//      constraint / payload is caught here. The USER prompt golden is unchanged
+//      by the disasters feature (its payload is always empty).
+//
+//   2. REGISTRY CONTRACT — the ABILITIES registry is the canonical ordered
+//      list of the 12 abilities; each ability's default() equals the canonical
+//      TurnResult default for its field, is a FRESH value (never a shared
+//      reference), its default is not "meaningful" while a populated value is,
+//      and the registry composes (a hypothetical extra ability can be appended
+//      and every uniform loop still runs).
+//
+// Regenerate the goldens after an INTENTIONAL prompt change with:
+//   REGEN_GOLDENS=1 npx vitest run server/abilities/registry.test.ts
+// (the goldens are then rewritten from the current engine output; review the
+// diff and commit). In a normal run (no env) the tests assert byte-equality.
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import {
+  activeWarPairs,
+  applyDisasterEvent,
+  applyIndustryEffects,
+  applyMigrationOp,
+  atWar,
+  buildSystemPrompt,
+  buildUserPrompt,
+  DISASTER_EFFECTS,
+  DISASTER_SEVERITIES,
+  DISASTER_TYPES,
+  freshNationId,
+  freshWarId,
+  HYBRID_STAT_EFFECT,
+  isDisasterSeverity,
+  isDisasterType,
+  isHybridOpType,
+  isIndustryType,
+  isMigrationKind,
+  isMigrationScale,
+  LARGE_INFLUX_STABILITY_DIP,
+  MIGRATION_DESTINATION_EFFECTS,
+  MIGRATION_KINDS,
+  MIGRATION_SCALES,
+  MIGRATION_SOURCE_EFFECTS,
+  NEW_NATION_STATS,
+  resolveNationRef,
+  resolveRegionKey,
+  shiftRelationTowardHostile,
+  shiftRelationTowardPositive,
+  syncWarRelations,
+  validateDisasterEvents,
+  validateEconomyOps,
+  validateHybridOps,
+  validateIdeologyOps,
+  validateIndustryOps,
+  validateLeaderOps,
+  validateMigrationOps,
+  validateNuclearOps,
+  validateTakeovers,
+  validateWarOps,
+  validateSeaOps,
+  applySeaControl,
+  applySeaZoneBonuses,
+  SEA_ZONE_BONUS,
+  SEA_ZONES,
+  SEA_ZONE_IDS,
+  isSeaZoneId,
+  seaZoneName,
+  // contested (v0.44.0, #66)
+  validateContestedOps,
+  applyContested,
+  CONTESTED_FILL,
+  CONTESTED_STROKE,
+  contestedTooltipLabel,
+} from '../engine';
+import { createPresetStore } from '../presets';
+import { ABILITIES } from './index';
+import type { Ability, AbilityField } from './types';
+import type {
+  Embargo,
+  GameState,
+  IndustryProject,
+  Nation,
+  NationStats,
+  RegionResources,
+  RelationStatus,
+  RoundItem,
+  SeaZoneClaim,
+  TradeAgreement,
+} from '../../shared/types';
+import type { ContestedRegion, MarkerInfo, TurnResult, WarInfo } from '../../shared/protocol';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const goldensDir = path.join(here, 'goldens');
+const REGEN = process.env.REGEN_GOLDENS === '1';
+
+// --- The preset the system-prompt goldens were captured with. ---
+const root = path.resolve(here, '..', '..');
+const store = createPresetStore(path.join(root, 'presets'));
+const preset = store.get('wwii-1939');
+if (!preset) throw new Error('wwii-1939 preset not found');
+
+// --- The small, fully-controlled deterministic state that exercises EVERY
+// --- optional branch of buildUserPrompt (re-embedded from the P1
+// --- golden-capture so the committed goldens can be regenerated). ---
+function nation(
+  id: string,
+  name: string,
+  stats: NationStats,
+  territory: string[],
+  extra: Partial<Nation> = {},
+): Nation {
+  return { id, name, type: 'major', stats, territory, relations: {}, ...extra };
+}
+
+const s = (m: number, e: number, st: number, p: number): NationStats => ({
+  military: m,
+  economy: e,
+  stability: st,
+  population: p,
+});
+
+const a1 = nation('a1', 'Alpha', s(60, 55, 70, 80), ['a-r1', 'a-r2'], {
+  nuclear: true,
+  leader: { name: 'Alpha Leader' },
+  ideology: 'democracy',
+  relations: { b2: 'ally', c3: 'rival' },
+});
+const b2 = nation('b2', 'Bravo', s(75, 40, 20, 30), ['b-r1', 'b-r2'], {
+  ideology: 'fascism',
+  relations: { a1: 'ally' },
+});
+const c3 = nation('c3', 'Charlie', s(30, 35, 80, 20), ['c-r1'], {
+  relations: { a1: 'rival' },
+});
+
+const state: GameState = {
+  id: 'golden-0000-0000-0000-0000-000000000000',
+  presetId: 'wwii-1939',
+  presetTitle: preset.title,
+  playerNationId: 'a1',
+  turn: 4,
+  date: '1940-02-14',
+  nations: { a1, b2, c3 },
+  events: [],
+  pending: [],
+  version: 9,
+  unowned: ['x-unowned'],
+  pendingNationOps: [],
+  markers: [],
+  regionStats: {
+    'a-r1': s(60, 55, 70, 80),
+    'a-r2': s(58, 53, 72, 78),
+    'b-r1': s(75, 40, 20, 30),
+    'b-r2': s(70, 42, 22, 28),
+    'c-r1': s(30, 35, 80, 20),
+  },
+  wars: [],
+  trades: [],
+  embargoes: [],
+  industry: [],
+  // (v0.43.0, #65) no sea-zone control on a fresh state.
+  seaZones: [],
+  // (v0.44.0, #66) no contested regions on a fresh state.
+  contested: [],
+};
+
+// --- buildUserPrompt arguments: every optional branch exercised. ---
+const items: RoundItem[] = [
+  { kind: 'action', text: 'Rearm the northern border' },
+  { kind: 'diplomacy', to: 'b2', text: 'We can still talk terms, no?' },
+];
+const regionReference: Record<string, string> = {
+  'a-r1': 'Alpha North (US)',
+  'a-r2': 'Alpha South (US)',
+  'b-r1': 'Bravo Plain (RU)',
+  'b-r2': 'Bravo Coast (RU)',
+  'c-r1': 'Charlie Isle (FR)',
+  'x-unowned': 'X Released (UN)',
+};
+const frontier: string[] = ['b-r1']; // owned by b2 (a non-player) → frontierMilitary
+const noMansLand: string[] = ['x-unowned'];
+const markers: MarkerInfo[] = [
+  { id: 'mk0001', type: 'gathering', name: 'Bravo Rally', regionKey: 'b-r1', owner: 'b2' },
+  { id: 'mk0002', type: 'rocket', name: 'Charlie Silo', regionKey: 'c-r1', owner: 'c3' },
+  { id: 'mk0003', type: 'capital', name: 'Alpha Cap', regionKey: 'a-r1', owner: 'a1' },
+];
+const wars: WarInfo[] = [
+  { id: 'w1', sides: ['a1', 'b2'], aims: ['control the border'] },
+  { id: 'w2', sides: ['b2', 'c3'] },
+];
+const relations: Record<string, RelationStatus> = { b2: 'ally', c3: 'rival' };
+const trades: TradeAgreement[] = [{ a: 'a1', b: 'c3' }];
+const embargoes: Embargo[] = [{ from: 'a1', target: 'b2' }];
+const nationResources: Record<string, RegionResources> = {
+  a1: { oil: 0.5, iron: 0.2, food: 0.3, industry: 0.8 },
+  b2: { oil: 0.1, iron: 0.9, food: 0.1, industry: 0.2 },
+  c3: { oil: 0.2, iron: 0.3, food: 0.7, industry: 0.4 },
+};
+const industryProjects: IndustryProject[] = [{ regionKey: 'a-r1', type: 'industry' }];
+const nuclear: Record<string, boolean> = { a1: true, b2: false, c3: false };
+const seaZones: SeaZoneClaim[] = [];
+// (v0.44.0, #66) a non-empty contested sample so the golden's user payload
+// includes the `contested` key (region key + party NAMES, resolved from the
+// state's nations). `b-r1` is owned by b2; the parties are a1 + b2.
+const contested: ContestedRegion[] = [{ regionKey: 'b-r1', parties: ['a1', 'b2'] }];
+
+/**
+ * Assert the current prompt output is byte-identical to the committed golden —
+ * or, under REGEN_GOLDENS=1, rewrite the golden from the current output (a
+ * manual regeneration step; the test then passes without asserting).
+ */
+function checkGolden(name: string, current: string): void {
+  const file = path.join(goldensDir, name);
+  if (REGEN) {
+    mkdirSync(goldensDir, { recursive: true });
+    writeFileSync(file, current, 'utf8');
+    return;
+  }
+  const expected = readFileSync(file, 'utf8');
+  expect(current, `golden ${name} mismatch`).toBe(expected);
+}
+
+/** The canonical (default / no-op) value of EVERY TurnResult field. */
+function fullDefaultTurn(): TurnResult {
+  return {
+    date: '1939-09-01',
+    events: [],
+    stateChanges: [],
+    regionChanges: [],
+    relations: [],
+    territoryChanges: [],
+    unowned: [],
+    nationOps: [],
+    takeovers: [],
+    wars: { declare: [], end: [] },
+    hybrid: { ops: [] },
+    economy: { trade: [], embargo: [] },
+    industry: { projects: [] },
+    nuclear: { arm: [], strikes: [] },
+    leaders: { changes: [] },
+    ideology: { changes: [] },
+    disasters: { events: [] },
+    migration: { ops: [] },
+    sea: { control: [] },
+    contested: { open: [], resolve: [] },
+    markers: { add: [], remove: [] },
+  };
+}
+
+/** A "meaningful" (non-default) value for each ability field. */
+function meaningfulFor(field: AbilityField): TurnResult[AbilityField] {
+  switch (field) {
+    case 'takeovers':
+      return [{ nationRef: 'a1', newRegimeName: 'Alpha Regime' }];
+    case 'wars':
+      return { declare: [{ sides: ['a1', 'b2'] }], end: [] };
+    case 'hybrid':
+      return { ops: [{ type: 'spy', from: 'a1', target: 'b2' }] };
+    case 'economy':
+      return { trade: [{ a: 'a1', b: 'c3' }], embargo: [] };
+    case 'industry':
+      return { projects: [{ regionKey: 'a-r1', type: 'oil' }] };
+    case 'nuclear':
+      return { arm: ['a1'], strikes: [] };
+    case 'leaders':
+      return { changes: [{ target: 'a1', name: 'New Alpha Leader', cause: 'appointed' }] };
+    case 'ideology':
+      return { changes: [{ target: 'a1', to: 'democracy' }] };
+    case 'disasters':
+      return { events: [{ type: 'earthquake', target: 'a1', severity: 'minor' }] };
+    case 'migration':
+      return { ops: [{ kind: 'migration', from: 'a1', to: 'b2', scale: 'small' }] };
+    case 'sea':
+      return { control: [{ zone: 'pacific', by: 'a1' }] };
+    case 'contested':
+      return { open: [{ regionKey: 'b-r1', parties: ['a1', 'b2'] }], resolve: [] };
+  }
+}
+
+describe('ABILITIES registry (v0.40.0, #67)', () => {
+  it('is the canonical 12-ability order (takeovers → contested)', () => {
+    expect(ABILITIES.map((a) => a.field)).toEqual([
+      'takeovers',
+      'wars',
+      'hybrid',
+      'economy',
+      'industry',
+      'nuclear',
+      'leaders',
+      'ideology',
+      'disasters',
+      'migration',
+      'sea',
+      'contested',
+    ]);
+  });
+
+  it('lists 12 distinct fields, each a key of TurnResult', () => {
+    const fields = ABILITIES.map((a) => a.field);
+    expect(fields).toHaveLength(12);
+    expect(new Set(fields).size).toBe(12);
+    const all = fullDefaultTurn();
+    for (const f of fields) expect(f in all).toBe(true);
+  });
+
+  it('system prompt (no tool) is byte-identical to the committed golden', () => {
+    checkGolden('system-no-tool.txt', buildSystemPrompt(preset, false));
+  });
+
+  it('system prompt (tool) is byte-identical to the committed golden', () => {
+    checkGolden('system-tool.txt', buildSystemPrompt(preset, true));
+  });
+
+  it('user prompt is byte-identical to the committed golden', () => {
+    checkGolden(
+      'user.txt',
+      buildUserPrompt(
+        state,
+        items,
+        regionReference,
+        frontier,
+        noMansLand,
+        markers,
+        wars,
+        relations,
+        trades,
+        embargoes,
+        nationResources,
+        industryProjects,
+        nuclear,
+        seaZones,
+        contested,
+      ),
+    );
+  });
+
+  it("each ability's default() equals the canonical TurnResult default for its field", () => {
+    const all = fullDefaultTurn();
+    for (const a of ABILITIES) {
+      expect(a.default(), `default() for ${a.field}`).toEqual(all[a.field]);
+    }
+  });
+
+  it('default() is a FRESH value on every call (never a shared reference)', () => {
+    for (const a of ABILITIES) {
+      expect(a.default(), `${a.field} default should be a fresh object`).not.toBe(a.default());
+    }
+  });
+
+  it('default() is never meaningful; a populated value always is', () => {
+    for (const a of ABILITIES) {
+      expect(a.isMeaningful(a.default()), `${a.field} default should not be meaningful`).toBe(false);
+      expect(a.isMeaningful(meaningfulFor(a.field)), `${a.field} populated should be meaningful`).toBe(
+        true,
+      );
+    }
+  });
+
+  it('declares exactly the durable GameState fields the db migration must default', () => {
+    const owned: string[] = [];
+    for (const a of ABILITIES) if (a.stateFields) owned.push(...a.stateFields);
+    expect([...owned].sort()).toEqual(['contested', 'embargoes', 'industry', 'seaZones', 'trades', 'wars']);
+  });
+
+  it('composes: a hypothetical extra ability can be appended and every uniform loop still runs', () => {
+    // The registry is a plain ordered array the engine iterates uniformly. A
+    // structural (field-name-agnostic) loop over the abilities — schema line,
+    // constraint bullet — must keep working when a 12th ability is appended.
+    // This documents the extension point without widening the closed
+    // AbilityField union.
+    interface Loopable {
+      field: string;
+      schemaLine(): string;
+      constraint(): string;
+    }
+    const dummy: Loopable = {
+      field: 'custom',
+      schemaLine: () => '  "custom": [],',
+      constraint: () => '- A custom ability.',
+    };
+    const extended: readonly (Ability<AbilityField> | Loopable)[] = [...ABILITIES, dummy];
+    expect(extended.map((a) => a.field)).toEqual([
+      ...ABILITIES.map((a) => a.field),
+      'custom',
+    ]);
+    // every uniform loop runs over all N abilities, the appended one included:
+    expect(extended.map((a) => a.schemaLine())).toHaveLength(13);
+    expect(extended.map((a) => a.constraint())).toHaveLength(13);
+    expect(extended[12].schemaLine()).toBe('  "custom": [],');
+  });
+
+  it('the engine still re-exports every name its callers import from it', () => {
+    // Backward compatibility: server/index.ts and engine.test.ts import these
+    // from the engine; the re-export block must keep them all exported (a
+    // missing re-export would also fail typecheck — this pins it at runtime).
+    const reexported: Record<string, unknown> = {
+      // shared primitives (./abilities/shared)
+      freshNationId,
+      freshWarId,
+      NEW_NATION_STATS,
+      resolveNationRef,
+      resolveRegionKey,
+      // ability modules (./abilities)
+      isHybridOpType,
+      isIndustryType,
+      activeWarPairs,
+      atWar,
+      syncWarRelations,
+      HYBRID_STAT_EFFECT,
+      shiftRelationTowardHostile,
+      validateEconomyOps,
+      validateHybridOps,
+      validateIdeologyOps,
+      validateIndustryOps,
+      validateLeaderOps,
+      validateNuclearOps,
+      validateTakeovers,
+      validateWarOps,
+      applyIndustryEffects,
+      // disasters (v0.41.0, #63)
+      validateDisasterEvents,
+      applyDisasterEvent,
+      isDisasterType,
+      isDisasterSeverity,
+      DISASTER_TYPES,
+      DISASTER_SEVERITIES,
+      DISASTER_EFFECTS,
+      // migration (v0.42.0, #64)
+      validateMigrationOps,
+      applyMigrationOp,
+      shiftRelationTowardPositive,
+      isMigrationKind,
+      isMigrationScale,
+      MIGRATION_KINDS,
+      MIGRATION_SCALES,
+      MIGRATION_SOURCE_EFFECTS,
+      MIGRATION_DESTINATION_EFFECTS,
+      LARGE_INFLUX_STABILITY_DIP,
+      // sea (v0.43.0, #65)
+      validateSeaOps,
+      applySeaControl,
+      applySeaZoneBonuses,
+      SEA_ZONE_BONUS,
+      SEA_ZONES,
+      SEA_ZONE_IDS,
+      isSeaZoneId,
+      seaZoneName,
+      // contested (v0.44.0, #66)
+      validateContestedOps,
+      applyContested,
+      CONTESTED_FILL,
+      CONTESTED_STROKE,
+      contestedTooltipLabel,
+    };
+    for (const [name, value] of Object.entries(reexported)) {
+      expect(value, `engine should re-export ${name}`).toBeDefined();
+    }
+  });
+});

server/abilities/sea.test.ts

@@ -0,0 +1,496 @@
+// Unit tests for the SEA (naval / sea control) ability (v0.43.0, #65) — the
+// modular, DURABLE LLM-ability that gives nations sole control over a fixed
+// set of 12 named sea zones: the zone is upserted in `GameState.seaZones`
+// (replace in place, contest by higher current military), and every committed
+// turn the controller earns a deterministic +1 military / +1 economy bonus
+// (clamped, mirrored to its regions, re-derived). The layer never touches
+// `territory` / `unowned` — it is fully parallel to but independent of land.
+// This is the ability's own test file (the registry's cross-cutting
+// guarantees — order, distinct fields, the system/user goldens — are covered
+// by ./registry.test.ts). The stub never proposes a sea op, so the apply path
+// is exercised here, not by the e2e suite.
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  SEA_ZONES,
+  SEA_ZONE_IDS,
+  applySeaControl,
+  applySeaZoneBonuses,
+  isSeaZoneId,
+  sea,
+  seaZoneName,
+  validateSeaOps,
+} from './sea';
+
+import type {
+  GameState,
+  Nation,
+  NationStats,
+  RegionStats,
+  SeaZoneClaim,
+} from '../../shared/types';
+
+// ---------------------------------------------------------------------------
+// Fixture helpers
+// ---------------------------------------------------------------------------
+
+/** Build a NationStats from the four canonical indices (military, economy, stability, population). */
+function NS(military: number, economy: number, stability: number, population: number): NationStats {
+  return { military, economy, stability, population };
+}
+
+/** Build a RegionStats from the four canonical indices. */
+function RS(military: number, economy: number, stability: number, population: number): RegionStats {
+  return { military, economy, stability, population };
+}
+
+/** A minimal nation: the given id/name/stats/region-key territory. */
+function mkNation(
+  id: string,
+  name: string,
+  stats: NationStats,
+  territory: string[],
+): Nation {
+  return { id, name, type: 'major', stats, territory, relations: {} };
+}
+
+/**
+ * A minimal GameState carrying the given nations (keyed by id), per-region
+ * stats, and an optional existing sea-zone list. Every other required field
+ * is at its fresh-game baseline.
+ */
+function mkState(
+  nations: Record<string, Nation>,
+  regionStats: Record<string, RegionStats>,
+  seaZones: SeaZoneClaim[] = [],
+): GameState {
+  return {
+    id: 'g1',
+    presetId: 'test',
+    presetTitle: 'Test',
+    playerNationId: Object.keys(nations)[0] ?? 'a1',
+    turn: 1,
+    date: '1939-09-01',
+    nations,
+    events: [],
+    pending: [],
+    version: 1,
+    unowned: [],
+    pendingNationOps: [],
+    markers: [],
+    regionStats,
+    wars: [],
+    trades: [],
+    embargoes: [],
+    industry: [],
+    seaZones,
+    // (v0.44.0, #66) no contested regions on a fresh state.
+    contested: [],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// SEA_ZONES / isSeaZoneId / seaZoneName
+// ---------------------------------------------------------------------------
+
+describe('SEA_ZONES / SEA_ZONE_IDS / isSeaZoneId / seaZoneName', () => {
+  it('exposes exactly the 12 fixed sea zones', () => {
+    expect(SEA_ZONES).toHaveLength(12);
+    const ids = SEA_ZONES.map((z) => z.id);
+    expect(ids).toEqual([
+      'north-atlantic',
+      'south-atlantic',
+      'pacific',
+      'indian',
+      'mediterranean',
+      'north-sea',
+      'baltic',
+      'arctic',
+      'black-sea',
+      'gulf-mexico',
+      'red-sea',
+      'sargasso',
+    ]);
+  });
+
+  it('SEA_ZONE_IDS is a ReadonlySet of all 12 ids', () => {
+    expect(SEA_ZONE_IDS).toBeInstanceOf(Set);
+    expect(SEA_ZONE_IDS.size).toBe(12);
+    for (const z of SEA_ZONES) expect(SEA_ZONE_IDS.has(z.id)).toBe(true);
+  });
+
+  it('isSeaZoneId accepts each known id and rejects unknown / non-strings', () => {
+    for (const z of SEA_ZONES) expect(isSeaZoneId(z.id)).toBe(true);
+    expect(isSeaZoneId('atlantic-ocean')).toBe(false);
+    expect(isSeaZoneId('')).toBe(false);
+  });
+
+  it('seaZoneName returns the human-readable name; an unknown id is returned raw', () => {
+    expect(seaZoneName('pacific')).toBe('Pacific Ocean');
+    expect(seaZoneName('mediterranean')).toBe('Mediterranean Sea');
+    expect(seaZoneName('nope')).toBe('nope');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// validateSeaOps
+// ---------------------------------------------------------------------------
+
+describe('validateSeaOps', () => {
+  it('accepts the { control: [...] } object shape and a bare array', () => {
+    const op = { zone: 'pacific', by: 'a1' };
+    expect(validateSeaOps({ control: [op] })).toEqual({ control: [op] });
+    expect(validateSeaOps([op])).toEqual({ control: [op] });
+  });
+
+  it('drops an op with an unknown / missing zone', () => {
+    expect(validateSeaOps([{ zone: 'nope', by: 'a1' }])).toEqual({ control: [] });
+    expect(validateSeaOps([{ by: 'a1' }])).toEqual({ control: [] });
+    expect(validateSeaOps([{ zone: '', by: 'a1' }])).toEqual({ control: [] });
+  });
+
+  it('drops an op with an empty / missing `by` (the controller)', () => {
+    expect(validateSeaOps([{ zone: 'pacific', by: '' }])).toEqual({ control: [] });
+    expect(validateSeaOps([{ zone: 'pacific' }])).toEqual({ control: [] });
+  });
+
+  it('drops a non-object entry', () => {
+    expect(validateSeaOps([42, 'nope', null, { zone: 'pacific', by: 'a1' }])).toEqual({
+      control: [{ zone: 'pacific', by: 'a1' }],
+    });
+  });
+
+  it('a missing / malformed top-level value yields { control: [] }', () => {
+    expect(validateSeaOps(undefined)).toEqual({ control: [] });
+    expect(validateSeaOps(null)).toEqual({ control: [] });
+    expect(validateSeaOps('nope')).toEqual({ control: [] });
+    expect(validateSeaOps({ control: 'nope' })).toEqual({ control: [] });
+  });
+
+  it('caps `zone` at 100 and `by` at 200 chars', () => {
+    const longBy = 'f'.repeat(500);
+    const out = validateSeaOps([{ zone: 'pacific', by: longBy }]);
+    expect(out.control).toHaveLength(1);
+    expect(out.control[0].by).toHaveLength(200);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// applySeaControl
+// ---------------------------------------------------------------------------
+
+describe('applySeaControl', () => {
+  it('a single op sets a new zone claim', () => {
+    const state = mkState(
+      { a1: mkNation('a1', 'Alpha', NS(80, 70, 60, 50), ['a-r1']) },
+      { 'a-r1': RS(80, 70, 60, 50) },
+    );
+    applySeaControl(state, [{ zone: 'pacific', by: 'a1' }]);
+    expect(state.seaZones).toEqual([{ zone: 'pacific', by: 'a1' }]);
+  });
+
+  it('replaces an existing claim in place (position preserved)', () => {
+    const state = mkState(
+      {
+        a1: mkNation('a1', 'Alpha', NS(80, 70, 60, 50), ['a-r1']),
+        b2: mkNation('b2', 'Bravo', NS(90, 40, 20, 30), ['b-r1']),
+      },
+      { 'a-r1': RS(80, 70, 60, 50), 'b-r1': RS(90, 40, 20, 30) },
+      [
+        { zone: 'pacific', by: 'a1' },
+        { zone: 'indian', by: 'b2' },
+      ],
+    );
+    // b2 now claims pacific — the pacific claim moves to b2 but stays at index 0
+    applySeaControl(state, [{ zone: 'pacific', by: 'b2' }]);
+    expect(state.seaZones).toEqual([
+      { zone: 'pacific', by: 'b2' },
+      { zone: 'indian', by: 'b2' },
+    ]);
+  });
+
+  it('appends a new zone after existing claims', () => {
+    const state = mkState(
+      { a1: mkNation('a1', 'Alpha', NS(80, 70, 60, 50), ['a-r1']) },
+      { 'a-r1': RS(80, 70, 60, 50) },
+      [{ zone: 'pacific', by: 'a1' }],
+    );
+    applySeaControl(state, [{ zone: 'arctic', by: 'a1' }]);
+    expect(state.seaZones).toEqual([
+      { zone: 'pacific', by: 'a1' },
+      { zone: 'arctic', by: 'a1' },
+    ]);
+  });
+
+  it('a contest: the higher current military wins', () => {
+    const state = mkState(
+      {
+        a1: mkNation('a1', 'Alpha', NS(80, 70, 60, 50), ['a-r1']),
+        b2: mkNation('b2', 'Bravo', NS(90, 40, 20, 30), ['b-r1']),
+      },
+      { 'a-r1': RS(80, 70, 60, 50), 'b-r1': RS(90, 40, 20, 30) },
+    );
+    // b2 has higher military (90 > 80) → b2 wins
+    applySeaControl(state, [
+      { zone: 'pacific', by: 'a1' },
+      { zone: 'pacific', by: 'b2' },
+    ]);
+    expect(state.seaZones).toEqual([{ zone: 'pacific', by: 'b2' }]);
+  });
+
+  it('a contest tie: the earlier-listed op wins', () => {
+    const state = mkState(
+      {
+        a1: mkNation('a1', 'Alpha', NS(50, 50, 50, 50), ['a-r1']),
+        b2: mkNation('b2', 'Bravo', NS(50, 50, 50, 50), ['b-r1']),
+      },
+      { 'a-r1': RS(50, 50, 50, 50), 'b-r1': RS(50, 50, 50, 50) },
+    );
+    // equal military (50 == 50) → a1 wins (listed first)
+    applySeaControl(state, [
+      { zone: 'pacific', by: 'a1' },
+      { zone: 'pacific', by: 'b2' },
+    ]);
+    expect(state.seaZones).toEqual([{ zone: 'pacific', by: 'a1' }]);
+  });
+
+  it('two ops for the same nation on the same zone: a single claim (no contest)', () => {
+    const state = mkState(
+      { a1: mkNation('a1', 'Alpha', NS(80, 70, 60, 50), ['a-r1']) },
+      { 'a-r1': RS(80, 70, 60, 50) },
+    );
+    applySeaControl(state, [
+      { zone: 'pacific', by: 'a1' },
+      { zone: 'pacific', by: 'a1' },
+    ]);
+    expect(state.seaZones).toEqual([{ zone: 'pacific', by: 'a1' }]);
+  });
+
+  it('resolves `by` by unique name (not just id)', () => {
+    const state = mkState(
+      { a1: mkNation('a1', 'Alpha', NS(80, 70, 60, 50), ['a-r1']) },
+      { 'a-r1': RS(80, 70, 60, 50) },
+    );
+    applySeaControl(state, [{ zone: 'pacific', by: 'Alpha' }]);
+    expect(state.seaZones).toEqual([{ zone: 'pacific', by: 'a1' }]);
+  });
+
+  it('an unresolvable `by` is dropped; if all ops on a zone drop, the zone is untouched', () => {
+    const state = mkState(
+      { a1: mkNation('a1', 'Alpha', NS(80, 70, 60, 50), ['a-r1']) },
+      { 'a-r1': RS(80, 70, 60, 50) },
+      [{ zone: 'pacific', by: 'a1' }],
+    );
+    // ghost does not exist → dropped; pacific stays as a1
+    applySeaControl(state, [{ zone: 'pacific', by: 'ghost' }]);
+    expect(state.seaZones).toEqual([{ zone: 'pacific', by: 'a1' }]);
+
+    // a NEW zone with only an unresolvable op → zone not added
+    applySeaControl(state, [{ zone: 'arctic', by: 'ghost' }]);
+    expect(state.seaZones).toEqual([{ zone: 'pacific', by: 'a1' }]);
+  });
+
+  it('an ambiguous name (two nations share it) drops the op', () => {
+    const state = mkState(
+      {
+        a1: mkNation('a1', 'Twin', NS(80, 70, 60, 50), ['a-r1']),
+        a2: mkNation('a2', 'Twin', NS(20, 20, 20, 20), ['a-r2']),
+      },
+      { 'a-r1': RS(80, 70, 60, 50), 'a-r2': RS(20, 20, 20, 20) },
+    );
+    applySeaControl(state, [{ zone: 'pacific', by: 'Twin' }]);
+    // ambiguous → dropped
+    expect(state.seaZones).toEqual([]);
+  });
+
+  it('never touches `territory` or `unowned`', () => {
+    const state = mkState(
+      {
+        a1: mkNation('a1', 'Alpha', NS(80, 70, 60, 50), ['a-r1']),
+        b2: mkNation('b2', 'Bravo', NS(90, 40, 20, 30), ['b-r1']),
+      },
+      { 'a-r1': RS(80, 70, 60, 50), 'b-r1': RS(90, 40, 20, 30) },
+    );
+    applySeaControl(state, [
+      { zone: 'pacific', by: 'a1' },
+      { zone: 'pacific', by: 'b2' },
+    ]);
+    expect(state.nations.a1.territory).toEqual(['a-r1']);
+    expect(state.nations.b2.territory).toEqual(['b-r1']);
+    expect(state.unowned).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// applySeaZoneBonuses
+// ---------------------------------------------------------------------------
+
+describe('applySeaZoneBonuses', () => {
+  it('a controller earns +1 military and +1 economy (clamped, mirrored, re-derived)', () => {
+    const state = mkState(
+      { a1: mkNation('a1', 'Alpha', NS(50, 50, 50, 50), ['a-r1']) },
+      { 'a-r1': RS(50, 50, 50, 50) },
+      [{ zone: 'pacific', by: 'a1' }],
+    );
+    applySeaZoneBonuses(state);
+    // +1 to both military and economy, mirrored to the region, re-derived
+    // (single region → re-derive gives back the region's value)
+    expect(state.nations.a1.stats).toEqual(NS(51, 51, 50, 50));
+    expect(state.regionStats['a-r1']).toEqual(RS(51, 51, 50, 50));
+  });
+
+  it('clamps to 0 and 100', () => {
+    // military at 99 → 100; economy at 1 → 2
+    const state = mkState(
+      { a1: mkNation('a1', 'Alpha', NS(99, 1, 50, 50), ['a-r1']) },
+      { 'a-r1': RS(99, 1, 50, 50) },
+      [{ zone: 'pacific', by: 'a1' }],
+    );
+    applySeaZoneBonuses(state);
+    expect(state.nations.a1.stats.military).toBe(100);
+    expect(state.nations.a1.stats.economy).toBe(2);
+  });
+
+  it('a nation controlling several zones stacks the bonus', () => {
+    const state = mkState(
+      { a1: mkNation('a1', 'Alpha', NS(50, 50, 50, 50), ['a-r1']) },
+      { 'a-r1': RS(50, 50, 50, 50) },
+      [
+        { zone: 'pacific', by: 'a1' },
+        { zone: 'indian', by: 'a1' },
+      ],
+    );
+    applySeaZoneBonuses(state);
+    // +2 to both (one per zone)
+    expect(state.nations.a1.stats).toEqual(NS(52, 52, 50, 50));
+  });
+
+  it('a 0-region nation keeps its directly-mutated stats (no re-derive)', () => {
+    const state = mkState(
+      { a1: mkNation('a1', 'Alpha', NS(50, 50, 50, 50), []) },
+      {},
+      [{ zone: 'pacific', by: 'a1' }],
+    );
+    applySeaZoneBonuses(state);
+    // direct mutation, no re-derive (no regions)
+    expect(state.nations.a1.stats).toEqual(NS(51, 51, 50, 50));
+  });
+
+  it('a stale controller (nation no longer in `nations`) is skipped; the claim is kept', () => {
+    // Build a state where the claim references a nation id that is not in `nations`
+    const state = mkState(
+      { a1: mkNation('a1', 'Alpha', NS(50, 50, 50, 50), ['a-r1']) },
+      { 'a-r1': RS(50, 50, 50, 50) },
+      [{ zone: 'pacific', by: 'ghost' }],
+    );
+    applySeaZoneBonuses(state);
+    // ghost is not in nations → skipped; a1 is unaffected
+    expect(state.nations.a1.stats).toEqual(NS(50, 50, 50, 50));
+    // the claim is kept (not removed)
+    expect(state.seaZones).toEqual([{ zone: 'pacific', by: 'ghost' }]);
+  });
+
+  it('an empty seaZones list is a no-op', () => {
+    const state = mkState(
+      { a1: mkNation('a1', 'Alpha', NS(50, 50, 50, 50), ['a-r1']) },
+      { 'a-r1': RS(50, 50, 50, 50) },
+      [],
+    );
+    applySeaZoneBonuses(state);
+    expect(state.nations.a1.stats).toEqual(NS(50, 50, 50, 50));
+  });
+
+  it('never touches `territory` or `unowned`', () => {
+    const state = mkState(
+      { a1: mkNation('a1', 'Alpha', NS(50, 50, 50, 50), ['a-r1']) },
+      { 'a-r1': RS(50, 50, 50, 50) },
+      [{ zone: 'pacific', by: 'a1' }],
+    );
+    applySeaZoneBonuses(state);
+    expect(state.nations.a1.territory).toEqual(['a-r1']);
+    expect(state.unowned).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// The Ability object contract
+// ---------------------------------------------------------------------------
+
+describe('sea ability', () => {
+  it('owns the "sea" field; default() is a fresh empty { control: [] }', () => {
+    expect(sea.field).toBe('sea');
+    expect(sea.default()).toEqual({ control: [] });
+    expect(sea.default()).not.toBe(sea.default());
+  });
+
+  it('default() is not meaningful; a populated value is', () => {
+    expect(sea.isMeaningful(sea.default())).toBe(false);
+    expect(sea.isMeaningful({ control: [{ zone: 'pacific', by: 'a1' }] })).toBe(true);
+  });
+
+  it('validate() wraps the validator into the SeaOps shape', () => {
+    expect(sea.validate([{ zone: 'pacific', by: 'a1' }])).toEqual({
+      control: [{ zone: 'pacific', by: 'a1' }],
+    });
+    expect(sea.validate(undefined)).toEqual({ control: [] });
+  });
+
+  it('the stub value equals default() (the stub never proposes a sea op)', () => {
+    expect(sea.stub()).toEqual({ control: [] });
+  });
+
+  it('stateFields is [seaZones] (the durable GameState field)', () => {
+    expect(sea.stateFields).toEqual(['seaZones']);
+  });
+
+  it('payload() emits seaZones (even when empty / undefined)', () => {
+    expect(sea.payload({ seaZones: [] } as never)).toEqual({ seaZones: [] });
+    expect(sea.payload({} as never)).toEqual({ seaZones: [] });
+    expect(sea.payload({ seaZones: [{ zone: 'pacific', by: 'a1' }] } as never)).toEqual({
+      seaZones: [{ zone: 'pacific', by: 'a1' }],
+    });
+  });
+
+  it('apply() runs the ops then the per-turn bonus (no throw on a bad ref)', () => {
+    const state = mkState(
+      {
+        a1: mkNation('a1', 'Alpha', NS(50, 50, 50, 50), ['a-r1']),
+        b2: mkNation('b2', 'Bravo', NS(80, 40, 20, 30), ['b-r1']),
+      },
+      { 'a-r1': RS(50, 50, 50, 50), 'b-r1': RS(80, 40, 20, 30) },
+    );
+    const ctx = { previous: state, actingTurn: state.turn };
+    sea.apply(
+      state,
+      {
+        control: [
+          { zone: 'pacific', by: 'a1' },
+          { zone: 'pacific', by: 'b2' },
+          // an unresolvable ref — must be dropped, not throw
+          { zone: 'arctic', by: 'ghost' },
+        ],
+      },
+      ctx,
+    );
+    // contest: b2 (military 80) beats a1 (military 50) → b2 controls pacific
+    expect(state.seaZones).toEqual([{ zone: 'pacific', by: 'b2' }]);
+    // b2 gets the +1/+1 bonus (it controls pacific)
+    expect(state.nations.b2.stats).toEqual(NS(81, 41, 20, 30));
+    // a1 is unaffected
+    expect(state.nations.a1.stats).toEqual(NS(50, 50, 50, 50));
+  });
+
+  it('apply() with an empty control still applies the per-turn bonus to existing claims', () => {
+    const state = mkState(
+      { a1: mkNation('a1', 'Alpha', NS(50, 50, 50, 50), ['a-r1']) },
+      { 'a-r1': RS(50, 50, 50, 50) },
+      [{ zone: 'pacific', by: 'a1' }],
+    );
+    const ctx = { previous: state, actingTurn: state.turn };
+    sea.apply(state, { control: [] }, ctx);
+    // no new claims, but the existing claim's controller earns the bonus
+    expect(state.seaZones).toEqual([{ zone: 'pacific', by: 'a1' }]);
+    expect(state.nations.a1.stats).toEqual(NS(51, 51, 50, 50));
+  });
+});

server/abilities/sea.ts

@@ -0,0 +1,210 @@
+// The SEA (naval / sea control) ability (v0.43.0, #65) as a modular
+// LLM-ability (v0.40.0, #67) — the naval layer, fully parallel to but
+// INDEPENDENT of land. The world has a fixed set of 12 named SEA ZONES
+// (`SEA_ZONES` in shared/protocol.ts); each is under the SOLE CONTROL of at
+// most one nation. Controlling a sea zone never moves land (`territory` /
+// `unowned` are untouched) and moving land never touches a sea zone.
+//
+// Each turn the LLM declares `sea.control` ops — one op names the zone and
+// the nation that (now) controls it. The engine resolves `by` (id first, then
+// a case-insensitive unique name, via the shared `resolveNationRef`) and
+// UPSERTS the zone's claim in `GameState.seaZones` (replace in place if the
+// zone is already claimed, append if new). If two or more ops this turn claim
+// the SAME zone for DIFFERENT resolved nations, the zone is CONTESTED: the
+// higher current `stats.military` wins (a tie goes to the op listed earlier in
+// the `control` array) — deterministic, no hidden randomness. An unresolvable
+// `by` is dropped (never thrown).
+//
+// Every committed turn — INCLUDING a turn with an empty `control` — each
+// existing claim's controller earns a small DETERMINISTIC bonus
+// (`SEA_ZONE_BONUS = 1` military + 1 economy, clamped to 0–100, mirrored to
+// the controller's regions and re-derived with the same 0-region / no-entry
+// guards as the economy / migration layers); a claim whose nation no longer
+// exists is skipped (the claim is kept, never thrown). The layer is DURABLE
+// (unlike the turn-transient hybrid / disasters / migration layers):
+// `GameState.seaZones` persists across turns and in SQLite, and the user
+// payload always carries the current `seaZones` list (even when empty).
+
+import {
+  clampStat,
+  deriveNationStats,
+  isSeaZoneId,
+} from '../../shared/protocol';
+export { SEA_ZONES, SEA_ZONE_IDS, isSeaZoneId, seaZoneName } from '../../shared/protocol';
+import type { SeaControlOp, SeaOps } from '../../shared/protocol';
+import type { GameState, Nation } from '../../shared/types';
+import { resolveNationRef, str } from './shared';
+import type { Ability } from './types';
+
+/**
+ * (v0.43.0, #65) The DETERMINISTIC per-turn bonus each sea-zone controller
+ * earns (applied to BOTH `military` and `economy`, clamped to 0–100, mirrored
+ * to the controller's regions, and re-derived with the same 0-region /
+ * no-entry guards as the economy / migration layers). No hidden randomness.
+ */
+export const SEA_ZONE_BONUS = 1;
+
+/**
+ * (v0.43.0, #65) Validate the raw `sea` field of a turn into a safe
+ * {@link SeaOps}. Defensive like the rest of the parser — never throws. The
+ * raw value may be the object `{ control: [...] }` (the TurnResult shape) or
+ * a bare array (be lenient about either). Each op needs a valid `zone` (one of
+ * {@link SEA_ZONES}) and a non-empty `by` (the controlling nation's id or
+ * unique name, capped at 200 chars). An op with an unknown / missing `zone` or
+ * an empty / missing `by` is dropped. Resolution of `by` to a concrete nation
+ * id happens at apply time (`applySeaControl`), not here. A missing /
+ * malformed top-level value yields `{ control: [] }`.
+ */
+export function validateSeaOps(raw: unknown): SeaOps {
+  const out: SeaOps = { control: [] };
+  let list: unknown[] | null = null;
+  if (Array.isArray(raw)) {
+    list = raw;
+  } else if (raw && typeof raw === 'object') {
+    const inner = (raw as Record<string, unknown>).control;
+    if (Array.isArray(inner)) list = inner;
+  }
+  if (!list) return out;
+  for (const e of list) {
+    if (!e || typeof e !== 'object') continue;
+    const o = e as Record<string, unknown>;
+    const zone = str(o.zone, 100);
+    if (!zone || !isSeaZoneId(zone)) continue; // unknown / missing zone: drop
+    const by = str(o.by, 200);
+    if (!by) continue; // empty / missing controller: drop
+    out.control.push({ zone, by });
+  }
+  return out;
+}
+
+/**
+ * (v0.43.0, #65) Upsert the turn's sea-control ops into `next.seaZones`,
+ * mutating in place and never throwing. Each op's `by` is resolved against the
+ * CURRENT state (id first, then a case-insensitive unique name) — an
+ * unresolvable ref is dropped. Per zone (in first-appearance order): a single
+ * surviving op SETS or REPLACES the zone's controller (replace the existing
+ * entry in place — preserving its position — or append a new one); two or
+ * more surviving ops on the same zone for DIFFERENT resolved nations make the
+ * zone CONTESTED — the higher current `stats.military` wins (a tie goes to the
+ * op listed earlier in the `control` array), and the winner becomes the
+ * controller. A zone whose ops all resolve to the same nation is simply (re-)
+ * set to that nation. Sea control never touches `territory` / `unowned`.
+ */
+export function applySeaControl(next: GameState, ops: SeaControlOp[]): void {
+  // Group the ops by zone, keeping the original (first-appearance) order of
+  // zones and each zone's ops (so the contest tie-break "earlier in the
+  // control array" is well-defined).
+  const byZone = new Map<string, { index: number; by: string }[]>();
+  ops.forEach((op, index) => {
+    const list = byZone.get(op.zone) ?? [];
+    list.push({ index, by: op.by });
+    byZone.set(op.zone, list);
+  });
+
+  for (const [zone, list] of byZone) {
+    // Resolve each op's `by`; an unresolvable ref is dropped (the zone is
+    // still decided by the ops that do resolve).
+    const resolved = list
+      .map(({ index, by }) => ({ index, id: resolveNationRef(next, by) }))
+      .filter((r): r is { index: number; id: string } => r.id !== null);
+    if (resolved.length === 0) continue; // nothing resolved: zone untouched
+
+    // Contest: the highest current `stats.military` wins; a strict `>` keeps
+    // the EARLIER-listed op on a tie (the list is in control-array order).
+    let winner = resolved[0];
+    for (const r of resolved) {
+      const mw = next.nations[winner.id]?.stats.military ?? 0;
+      const mr = next.nations[r.id]?.stats.military ?? 0;
+      if (mr > mw) winner = r;
+    }
+
+    const existing = next.seaZones.find((c) => c.zone === zone);
+    if (existing) {
+      existing.by = winner.id; // replace in place (position preserved)
+    } else {
+      next.seaZones.push({ zone, by: winner.id });
+    }
+  }
+}
+
+/**
+ * (v0.43.0, #65) The per-turn sea bonus, applied EVERY committed turn (not
+ * just to this turn's claims): each entry of `next.seaZones` grants its
+ * controller `SEA_ZONE_BONUS` military + `SEA_ZONE_BONUS` economy (clamped
+ * to 0–100, mirrored to every region the nation owns, then the nation's
+ * derived `stats` re-derived — the same 0-region / no-entry guards as the
+ * economy / migration layers, so a 0-region nation keeps its directly-mutated
+ * value). A nation controlling several zones stacks the bonus; a claim whose
+ * nation no longer exists (removed by a merge / split this turn) is skipped —
+ * the claim is kept, never thrown. Never throws.
+ */
+export function applySeaZoneBonuses(
+  next: GameState,
+  geoOf?: (key: string) => { area: number; population: number } | undefined,
+): void {
+  if (next.seaZones.length === 0) return;
+
+  // nation id -> {military, economy} delta (claims for the same nation stack).
+  const delta = new Map<string, { military: number; economy: number }>();
+  for (const c of next.seaZones) {
+    const d = delta.get(c.by) ?? { military: 0, economy: 0 };
+    d.military += SEA_ZONE_BONUS;
+    d.economy += SEA_ZONE_BONUS;
+    delta.set(c.by, d);
+  }
+
+  const applyNation = (n: Nation, d: { military: number; economy: number }): void => {
+    (['military', 'economy'] as const).forEach((k) => {
+      n.stats[k] = clampStat(n.stats[k] + d[k]);
+    });
+    for (const key of n.territory) {
+      const rs = next.regionStats[key];
+      if (!rs) continue; // a key with no entry is skipped
+      (['military', 'economy'] as const).forEach((k) => {
+        rs[k] = clampStat(rs[k] + d[k]);
+      });
+    }
+    // Re-derive the nation's aggregate stats so the effect persists (the main
+    // recompute ran earlier this turn; without this the change would be washed
+    // out next turn). A nation with no regionStats entry keeps its
+    // directly-mutated `stats`.
+    if (n.territory.length > 0 && n.territory.some((k) => next.regionStats[k])) {
+      n.stats = deriveNationStats(n.territory, next.regionStats, geoOf);
+    }
+  };
+
+  for (const [id, d] of delta) {
+    const n = next.nations[id];
+    if (!n) continue; // a nation removed this turn: the bonus is dropped (claim kept)
+    applyNation(n, d);
+  }
+}
+
+export const sea: Ability<'sea'> = {
+  field: 'sea',
+  default: () => ({ control: [] }),
+  validate: (raw) => validateSeaOps(raw),
+  apply: (state, data, ctx) => {
+    // (1) APPLY OPS: this turn's control ops upsert `GameState.seaZones`
+    //     (a single op sets/replaces the zone's controller; a same-zone
+    //     contest goes to the higher current `stats.military`, a tie to the
+    //     earlier-listed op).
+    // (2) PER-TURN BONUS: EVERY committed turn — including this one, and
+    //     including turns with an empty `control` — each existing claim's
+    //     controller earns the deterministic military/economy bonus, so a
+    //     zone that stays held keeps paying out.
+    applySeaControl(state, data.control);
+    applySeaZoneBonuses(state, ctx.geoOf);
+  },
+  schemaLine: () =>
+    '  "sea": {"control":[{"zone":"<seaZoneId>","by":"<nation id or name>"}]},',
+  constraint: () =>
+    '- Sea control ("sea") is the naval layer, fully parallel to but INDEPENDENT of land: each of the 12 fixed sea zones — "north-atlantic" (North Atlantic), "south-atlantic" (South Atlantic), "pacific" (Pacific Ocean), "indian" (Indian Ocean), "mediterranean" (Mediterranean Sea), "north-sea" (North Sea), "baltic" (Baltic Sea), "arctic" (Arctic Ocean), "black-sea" (Black Sea), "gulf-mexico" (Gulf of Mexico), "red-sea" (Red Sea), "sargasso" (Sargasso Sea) — is under the SOLE control of at most one nation. A control op ({"zone":"<id>","by":"<nation>"}) sets or replaces that zone\'s controller (the user message\'s "seaZones" field lists who controls what now); if two or more ops this turn claim the SAME zone for DIFFERENT nations, the zone is CONTESTED and the higher current "military" wins (a tie goes to the earlier-listed op). Every committed turn each zone\'s controller earns a small deterministic +1 military and +1 economy. Sea control NEVER moves land (no territory changes) — it is a parallel track. Propose at most 1-2 claims per turn and narrate each one in "events" (a "military" or "diplomatic" event).',
+  isMeaningful: (data) => data.control.length > 0,
+  stateFields: ['seaZones'],
+  stub: () => ({ control: [] }),
+  // Sea control is DURABLE (unlike the turn-transient hybrid / disasters /
+  // migration layers): the user payload ALWAYS carries the current `seaZones`
+  // list (even when empty) so the model knows who controls which zone.
+  payload: (ctx) => ({ seaZones: ctx.seaZones ?? [] }),
+};

server/abilities/shared.ts

@@ -0,0 +1,109 @@
+// Shared reference-resolution / id-generation primitives used across the
+// modular LLM abilities (and re-exported by the core engine). Living here —
+// and in `./types.ts` rather than in `engine.ts` — breaks the engine <->
+// ability import cycle: the ability modules import from here, `engine.ts`
+// imports + re-exports them for the existing callers (`server/index.ts`, the
+// unit tests), and no ability imports the engine. Pure and dependency-free.
+
+import type { GameState, NationStats } from '../../shared/types';
+
+/**
+ * Resolve a nation reference (the `nationRef` of a NationOp, or the `target` /
+ * `from` / `sides` of an ability op — the LLM may write either the nation's
+ * stable `id` or its human-readable `name`) to a concrete nation id: an exact
+ * id match wins, then a unique case-insensitive name match. Returns `null` when
+ * the reference is empty, unknown, or ambiguous (two or more nations share that
+ * name) — every caller treats `null` as "no-op" and nothing here ever throws.
+ */
+export function resolveNationRef(state: GameState, ref: string): string | null {
+  const r = (ref ?? '').trim();
+  if (!r) return null;
+  if (state.nations[r]) return r; // exact id first
+  const matches = Object.values(state.nations).filter(
+    (n) => n.name.trim().toLowerCase() === r.toLowerCase(),
+  );
+  return matches.length === 1 ? matches[0].id : null;
+}
+
+/**
+ * (v0.29, #46 PR 2) Resolve a **region** reference (a region op's `region` /
+ * `regionKey` — the LLM may write either the region's stable **key** or its
+ * human-readable **name**) to a concrete region key: an exact key match wins,
+ * then a unique case-insensitive name match (via `nameOf`). Returns `null` when
+ * the reference is empty, unknown, or ambiguous (two or more regions share that
+ * name) — every caller treats `null` as "drop this change" and nothing here
+ * ever throws. Mirrors {@link resolveNationRef}. `validKeys` is the set of all
+ * region keys and `nameOf` maps a key to its human name (both supplied by
+ * server/regions.ts).
+ */
+export function resolveRegionKey(
+  ref: string,
+  validKeys: ReadonlySet<string>,
+  nameOf: (key: string) => string | undefined,
+): string | null {
+  const r = (ref ?? '').trim();
+  if (!r) return null;
+  if (validKeys.has(r)) return r; // exact key first
+  const lower = r.toLowerCase();
+  let match: string | null = null;
+  for (const k of validKeys) {
+    const name = nameOf(k);
+    if (name && name.trim().toLowerCase() === lower) {
+      if (match !== null) return null; // ambiguous: two or more regions share the name
+      match = k;
+    }
+  }
+  return match;
+}
+
+/**
+ * Generate a fresh, unused nation id for a newly created nation (split parts,
+ * v0.24 #16 P4b): the first free of `n1`, `n2`, ... The caller adds each id it
+ * creates to `taken` as it goes, so ids stay unique within an op and are never
+ * reused from a removed nation.
+ */
+export function freshNationId(taken: ReadonlySet<string>): string {
+  for (let i = 1; ; i++) {
+    const id = `n${i}`;
+    if (!taken.has(id)) return id;
+  }
+}
+
+/**
+ * Generate a fresh, unused war id for a newly declared {@link War}
+ * (v0.33.0, #56): the first free of `w1`, `w2`, ... The caller adds each id it
+ * creates to `taken` as it goes, so ids stay unique within a turn and are never
+ * reused from an ended war.
+ */
+export function freshWarId(taken: ReadonlySet<string>): string {
+  for (let i = 1; ; i++) {
+    const id = `w${i}`;
+    if (!taken.has(id)) return id;
+  }
+}
+
+/**
+ * The baseline stats a freshly created nation starts with (split parts,
+ * v0.24 #16 P4b) — a neutral middle-of-the-scale profile, deliberately NOT a
+ * copy of the parent's stats (a small rump state is not the parent's military
+ * power).
+ */
+export const NEW_NATION_STATS: NationStats = {
+  military: 50,
+  economy: 50,
+  stability: 50,
+  population: 50,
+};
+
+/**
+ * Coerce an unknown LLM JSON value to a trimmed, non-empty string, or `null`
+ * when it is not a non-empty string. An optional `max` caps the length (used
+ * for the 200-char caps on nationOp fields). Shared by every defensive
+ * validator (engine + the ability modules). Never throws.
+ */
+export function str(s: unknown, max = 0): string | null {
+  if (typeof s !== 'string') return null;
+  const t = s.trim();
+  if (!t) return null;
+  return max ? t.slice(0, max) : t;
+}

server/abilities/takeovers.ts

@@ -0,0 +1,100 @@
+// The TAKEOVER ability (v0.32.0, #54) as a modular LLM-ability (v0.40.0, #67).
+// The model may overthrow a low-stability nation hosting a "gathering" marker
+// (a coup / revolution) — an AUTOMATIC, non-military regime change that RENAMES
+// the nation to its new regime (the stable id, territory, relations, stats and
+// playerNationId all survive). The validator and the apply body are moved
+// VERBATIM from the pre-refactor engine.ts; the user-payload `takeoverRisks`
+// hint (v0.30, #50 — the bounded soft-lever nudge listing the nations ripe for
+// a takeover) moves here too, since it is this ability's own prompt data.
+
+import type { GameState } from '../../shared/types';
+import type { Takeover } from '../../shared/protocol';
+import { resolveNationRef, str } from './shared';
+import type { Ability } from './types';
+
+/**
+ * (v0.32.0, #54) Validate the raw `takeovers` array of a turn into a safe
+ * {@link Takeover} list — the non-military regime-change lever (a coup or
+ * revolution that renames a nation to its new regime name). Defensive like
+ * the rest of the parser — never throws. Each entry needs a non-empty
+ * `nationRef` (the target nation's id or name — capped at 200 chars) and a
+ * non-empty `newRegimeName` (capped at 200 chars). Resolution of `nationRef`
+ * to a concrete nation id happens at apply time (`resolveNationRef`), not
+ * here. Entries with either field missing or whitespace-only are dropped.
+ */
+export function validateTakeovers(raw: unknown): Takeover[] {
+  if (!Array.isArray(raw)) return [];
+  const out: Takeover[] = [];
+  for (const e of raw) {
+    if (!e || typeof e !== 'object') continue;
+    const o = e as Record<string, unknown>;
+    const nationRef = str(o.nationRef, 200);
+    const newRegimeName = str(o.newRegimeName, 200);
+    if (nationRef && newRegimeName) out.push({ nationRef, newRegimeName });
+  }
+  return out;
+}
+
+/**
+ * (v0.32.0, #54) Apply a takeover to `next` (in place). For each takeover:
+ *   1. Resolve the target nation via `resolveNationRef` (id first, then
+ *      case-insensitive unique name). Skip (no-op) if `null` — an
+ *      unknown or ambiguous ref is silently dropped, never thrown.
+ *   2. Rename the resolved nation: set `n.name = newRegimeName`. Only
+ *      the display name changes — the stable id, territory, relations
+ *      (keyed by id), stats, and `playerNationId` (which references the
+ *      id, not the name) are all preserved. The player keeps leading an
+ *      overthrown nation under its new regime.
+ */
+export function applyTakeover(next: GameState, t: Takeover): void {
+  const id = resolveNationRef(next, t.nationRef);
+  if (id === null) return; // unknown / ambiguous ref: no-op
+  const n = next.nations[id];
+  if (!n) return; // defensive: id resolved but nation missing (corrupt state)
+  n.name = t.newRegimeName;
+}
+
+export const takeovers: Ability<'takeovers'> = {
+  field: 'takeovers',
+  default: () => [],
+  validate: (raw) => validateTakeovers(raw),
+  apply: (state, data) => {
+    // Applied after the per-region recompute (the rename doesn't depend on
+    // territory or stats, so it is order-independent with respect to those
+    // steps) and before the markers block (a marker's owner is a nation id,
+    // not a name, so the rename does not affect the owner recompute).
+    for (const t of data) applyTakeover(state, t);
+  },
+  schemaLine: () =>
+    '  "takeovers": [{"nationRef":"<nation id or name>","newRegimeName":"<name of the new regime>"}],',
+  constraint: () =>
+    '- 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.',
+  isMeaningful: (data) => data.length > 0,
+  stub: () => [],
+  payload: (ctx) => {
+    // (v0.30, #50) Bounded soft-lever hint: nations whose stability is below 30
+    // AND that currently have a "gathering" marker on one of their regions are
+    // the ones ripe for a NON-military takeover (a coup / revolution / faction
+    // seizure) — the model can act on them this turn. One line per matching
+    // nation, emitted only when there is at least one; the rest of the payload
+    // is left untouched. A soft nudge only — there is no hard gate behind it.
+    let takeoverRisks: string[] | undefined;
+    if (ctx.markers !== undefined && ctx.markers.length > 0) {
+      const risks = new Set<string>();
+      for (const m of ctx.markers) {
+        if (m.type !== 'gathering') continue;
+        const ownerId = m.owner;
+        if (!ownerId) continue;
+        const n = ctx.state.nations[ownerId];
+        if (n && n.stats.stability < 30) risks.add(n.id);
+      }
+      if (risks.size > 0) {
+        takeoverRisks = [...risks].map((id) => {
+          const n = ctx.state.nations[id];
+          return `${n?.name ?? id} (stability ${n?.stats.stability}, a gathering is in progress)`;
+        });
+      }
+    }
+    return takeoverRisks !== undefined ? { takeoverRisks } : {};
+  },
+};

server/abilities/types.ts

@@ -0,0 +1,181 @@
+// The shared type surface for the modular LLM-ability system (v0.40.0, #67).
+// Every ability is a plain object conforming to `Ability`, listed (in its
+// canonical apply / prompt / payload order) by `ABILITIES` in ./index.ts. This
+// file holds only the *types* the ability modules program against — the
+// concrete implementations live in the sibling one-file-per-ability modules.
+// No runtime deps here (type-only imports), so it stays pure like the rest of
+// the `server/abilities` package.
+
+import type {
+  Embargo,
+  GameState,
+  IndustryProject,
+  RegionResources,
+  RelationStatus,
+  SeaZoneClaim,
+  TradeAgreement,
+} from '../../shared/types';
+import type { ContestedRegion, MarkerInfo, TurnResult, WarInfo } from '../../shared/protocol';
+
+/**
+ * The 12 per-feature LLM abilities a turn can exercise, by the `TurnResult`
+ * field each one owns. This is the closed universe the ordered `ABILITIES`
+ * registry (./index.ts) is built from: a turn's world changes are exactly the
+ * core engine effects (events / stats / territory / no-man's-land / nation-ops
+ * / markers) plus, in order, these twelve abilities.
+ */
+export type AbilityField =
+  | 'takeovers'
+  | 'wars'
+  | 'hybrid'
+  | 'economy'
+  | 'industry'
+  | 'nuclear'
+  | 'leaders'
+  | 'ideology'
+  | 'disasters'
+  | 'migration'
+  | 'sea'
+  | 'contested';
+
+/**
+ * Everything a single ability's `apply` may need from the surrounding turn.
+ *
+ * `previous` is the world state BEFORE this turn: reference resolution and
+ * sole-ownership checks must see the state before this turn's own mutations, so
+ * abilities read `previous` (not the state they are mutating) to resolve refs.
+ * `actingTurn` is the turn number stamped onto anything the ability creates or
+ * ends. The region-manifest resolvers are each optional and are absent when
+ * their manifest is not loaded — an ability must degrade gracefully when one is
+ * missing (never throw).
+ */
+export interface AbilityCtx {
+  /** The world state before this turn (a read-only snapshot). */
+  readonly previous: GameState;
+  /** The turn number stamped onto anything this ability creates / ends. */
+  actingTurn: number;
+  /** All valid region keys (public/region-keys.json); undefined if not loaded. */
+  readonly validRegionKeys?: ReadonlySet<string>;
+  /** Region key -> human name; undefined if the key manifest is not loaded. */
+  readonly regionNameOf?: (key: string) => string | undefined;
+  /** Region key -> {area (km²), population}; undefined if not loaded (v0.28 #46). */
+  readonly geoOf?: (key: string) => { area: number; population: number } | undefined;
+  /** Region key -> synthesized resource profile; undefined if not loaded (v0.36 #59). */
+  readonly resourceOf?: (key: string) => RegionResources | undefined;
+  /**
+   * Region key -> centroid anchor {lat, lon, spread}; undefined if not loaded
+   * (v0.27 #44).
+   */
+  readonly centroidOf?: (key: string) => { lat: number; lon: number; spread: number } | undefined;
+  /**
+   * The `getNeighbours` tool executor (verify land borders). Available to an
+   * ability that needs it; none of the current nine use it (it drives the
+   * core territory/conquest logic), but the type is here so a future one can.
+   */
+  readonly getNeighbours?: (regionKeys: string[]) => string[];
+}
+
+/**
+ * The inputs the user-prompt builder hands to an ability's `payload` method —
+ * the optional buildUserPrompt parameters (the core-only ones — `items`,
+ * `regionReference`, `frontier`, `noMansLand`, `nuclear` — are consumed by the
+ * engine, not by an ability). Each ability reports only the payload keys it
+ * owns here; the engine merges them into the payload in the historical
+ * buildUserPrompt order (pinned by the user-prompt golden fixture).
+ */
+export interface UserPromptCtx {
+  readonly state: GameState;
+  readonly markers?: MarkerInfo[];
+  readonly wars?: WarInfo[];
+  readonly relations?: Record<string, RelationStatus>;
+  readonly trades?: TradeAgreement[];
+  readonly embargoes?: Embargo[];
+  readonly nationResources?: Record<string, RegionResources>;
+  readonly industryProjects?: IndustryProject[];
+  readonly seaZones?: SeaZoneClaim[];
+  readonly contested?: ContestedRegion[];
+}
+
+/**
+ * A single LLM ability — a feature the model can exercise via one named
+ * `TurnResult` field. Each ability is self-contained: it validates the raw
+ * JSON for its field, documents itself in the system prompt (a JSON schema line
+ * and a HARD CONSTRAINTS bullet), contributes its keys to the user payload,
+ * reports whether a non-default value makes the turn meaningful, declares the
+ * `GameState` fields it owns (for db migrations), and applies its field to the
+ * world. `K` pins the field so every value-bearing method operates on the
+ * field's exact `TurnResult[K]` type (no `any`).
+ */
+export interface Ability<K extends AbilityField = AbilityField> {
+  /** The `TurnResult` field this ability owns (its stable, unique name). */
+  readonly field: K;
+
+  /**
+   * The default (empty / no-op) value of this field — a FRESH value on every
+   * call (never a shared mutable reference). Used by the "unclear" fallback and
+   * the deterministic stub.
+   */
+  default(): TurnResult[K];
+
+  /**
+   * Parse and defensively validate the raw (unknown) JSON for this field into a
+   * clean `TurnResult[K]`. Never throws — a missing / malformed value yields
+   * `default()`. NOTE: the hybrid / leaders / ideology low-level validators
+   * return a bare inner list, so those abilities' `validate` wraps that list
+   * into the field's object shape (`{ ops }` / `{ changes }`).
+   */
+  validate(raw: unknown): TurnResult[K];
+
+  /**
+   * Apply this field's (validated) value to the world, MUTATING `state` in
+   * place. Never throws — any unresolvable reference or missing manifest
+   * degrades to a no-op. Abilities run in the fixed order of `ABILITIES`.
+   */
+  apply(state: GameState, data: TurnResult[K], ctx: AbilityCtx): void;
+
+  /**
+   * The JSON schema line for this field in the system prompt's JSON block
+   * (e.g. `'  "wars": {"declare":[…],"end":[…]},'`). Inserted by the engine,
+   * in `ABILITIES` order, between the `nationOps` block and the `markers` line.
+   */
+  schemaLine(): string;
+
+  /**
+   * The HARD CONSTRAINTS bullet documenting this ability (e.g.
+   * `'- Wars ("wars") are named conflicts, …'`). Inserted by the engine, in
+   * `ABILITIES` order, between the `nationOps` bullets and the
+   * "- Prefer 1-4 events" bullet.
+   */
+  constraint(): string;
+
+  /**
+   * Whether a non-default value of this field makes the turn "meaningful"
+   * (not an empty round). Mirrors the historical per-field predicate exactly.
+   */
+  isMeaningful(data: TurnResult[K]): boolean;
+
+  /**
+   * The `GameState` fields this ability owns and that must be defaulted on a
+   * legacy SQLite row (db.ts migration, only-if-undefined). `undefined` for
+   * abilities that add no durable state (takeovers, hybrid, nuclear, leaders,
+   * ideology, disasters).
+   */
+  readonly stateFields?: readonly string[];
+
+  /**
+   * The deterministic stub's value for this field. Every ability returns
+   * `default()` (the stub never exercises an ability, so e2e is unaffected) —
+   * kept as a zero-arg method so the stub stays a uniform registry loop (the
+   * stub has no real `GameState` / `AbilityCtx` to hand one; it needs none).
+   */
+  stub(): TurnResult[K];
+
+  /**
+   * The keys this ability contributes to the user prompt payload, each included
+   * only when it should be emitted (matching buildUserPrompt's "omit when
+   * undefined" behavior). The engine merges the returned entries into the
+   * payload at each key's exact historical position (pinned by the user-prompt
+   * golden).
+   */
+  payload(ctx: UserPromptCtx): Record<string, unknown>;
+}

server/abilities/wars.ts

@@ -0,0 +1,156 @@
+// The WARS ability (v0.33.0, #56) as a modular LLM-ability (v0.40.0, #67).
+// Wars are named first-class conflicts (`GameState.wars`), not just a `war`
+// relation: the model declares a war (≥2 belligerents, optional aims) or ends
+// one by id (armistice / capitulation). Declaring drags in each belligerent's
+// mutual-defense allies; the derived `war` relation is synced from the ACTIVE
+// wars by `syncWarRelations` (a war-ended pair falls back to `hostile`). The
+// validator and the apply body are moved VERBATIM from the pre-refactor
+// engine.ts.
+
+import type { GameState } from '../../shared/types';
+import type { TurnResult, WarDeclareOp, WarEndOp } from '../../shared/protocol';
+import { freshWarId, resolveNationRef } from './shared';
+import { syncWarRelations } from './apply-helpers';
+import type { Ability } from './types';
+
+/**
+ * (v0.33.0, #56) Validate the raw `wars` object of a turn into a safe
+ * `{ declare, end }` shape. Defensive like the rest of the parser — never
+ * throws. `declare`: each entry must be an object whose `sides` is an array
+ * of non-empty strings (trimmed, capped at 200 chars each, deduped) that
+ * yields at least TWO distinct sides — anything else (a one-sided or
+ * empty-sided "war") is dropped; `aims`, when an array, is kept only as
+ * non-empty strings (capped at 200 chars, at most 5). `end`: each entry must
+ * be an object with a non-empty `id` (capped at 200 chars) and an `outcome`
+ * of exactly `armistice` or `capitulation` (anything else is dropped);
+ * `terms`, when a non-empty string, is capped at 400 chars. A non-object
+ * input yields `{ declare: [], end: [] }`.
+ */
+export function validateWarOps(raw: unknown): { declare: WarDeclareOp[]; end: WarEndOp[] } {
+  const out: { declare: WarDeclareOp[]; end: WarEndOp[] } = { declare: [], end: [] };
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return out;
+  const o = raw as Record<string, unknown>;
+  if (Array.isArray(o.declare)) {
+    for (const e of o.declare) {
+      if (!e || typeof e !== 'object') continue;
+      const d = e as Record<string, unknown>;
+      const sides = (Array.isArray(d.sides) ? d.sides : [])
+        .map((s) => (typeof s === 'string' ? s.trim().slice(0, 200) : ''))
+        .filter((s) => s !== '')
+        // dedupe case-insensitively? No — sides are nation ids: keep exact
+        // strings, drop exact duplicates only (resolution is later).
+        .filter((s, i, arr) => arr.indexOf(s) === i);
+      if (sides.length < 2) continue; // a war needs at least two belligerents
+      const aims = Array.isArray(d.aims)
+        ? (d.aims as unknown[])
+            .map((a) => (typeof a === 'string' ? a.trim().slice(0, 200) : ''))
+            .filter((a) => a !== '')
+            .slice(0, 5)
+        : undefined;
+      out.declare.push({ sides, ...(aims && aims.length > 0 ? { aims } : {}) });
+    }
+  }
+  if (Array.isArray(o.end)) {
+    for (const e of o.end) {
+      if (!e || typeof e !== 'object') continue;
+      const w = e as Record<string, unknown>;
+      const id = typeof w.id === 'string' ? w.id.trim().slice(0, 200) : '';
+      if (!id) continue;
+      if (w.outcome !== 'armistice' && w.outcome !== 'capitulation') continue;
+      const terms = typeof w.terms === 'string' ? w.terms.trim().slice(0, 400) : '';
+      out.end.push({ id, outcome: w.outcome, ...(terms ? { terms } : {}) });
+    }
+  }
+  return out;
+}
+
+/**
+ * (v0.33.0, #56) Apply the turn's wars ops to the (cloned) `next` state,
+ * mutating it in place and never throwing. Two kinds of change, applied in
+ * this order against `next`:
+ *
+ *   (1) DECLARE: each validated declare is resolved to concrete nation ids
+ *       (`resolveNationRef`, so the LLM may use an id OR a unique name) and
+ *       becomes a new active War with a fresh id (`w1`, `w2`, ...), stamped
+ *       with the acting turn and the turn's new date. Mutually-defensive
+ *       allies of the belligerents are DRAGGED IN: any nation that is an
+ *       `ally` of a belligerent (per the current, post-relations relations)
+ *       and is not already a side joins the war's `sides`. A declare with
+ *       fewer than two DISTINCT resolved sides is dropped; a declare whose
+ *       sides are all already contained in an existing ACTIVE war is a
+ *       duplicate and is skipped (the existing war stands).
+ *   (2) END: each validated end targets a war BY ID and sets its status to
+ *       the outcome (`armistice` / `capitulation`). Only ACTIVE wars are
+ *       affected — an unknown id or an already-ended war is a no-op.
+ *       (A war may be declared and ended in the SAME turn: declare runs
+ *       first, so the just-declared id is a valid end target.)
+ *   (3) RELATION SYNC: `syncWarRelations(prev, next)` derives the `war`
+ *       relation from the ACTIVE wars — the load-bearing step that keeps
+ *       the relation table honest with the war entities. `prev` is the
+ *       state this turn started from (ctx.previous).
+ *
+ * Nothing here throws: every unresolvable / invalid op is dropped.
+ */
+export function applyWars(
+  next: GameState,
+  data: TurnResult['wars'],
+  prev: GameState,
+  actingTurn: number,
+): void {
+  const takenWarIds = new Set(next.wars.map((w) => w.id));
+  // (1) DECLARE
+  for (const d of data.declare) {
+    const resolved: string[] = [];
+    for (const ref of d.sides) {
+      const id = resolveNationRef(next, ref);
+      if (id !== null && !resolved.includes(id)) resolved.push(id);
+    }
+    if (resolved.length < 2) continue; // not enough distinct belligerents
+    // Duplicate: an active war already contains all of these sides.
+    const dup = next.wars.some(
+      (w) => w.status === 'active' && resolved.every((s) => w.sides.includes(s)),
+    );
+    if (dup) continue;
+    const sides = [...resolved];
+    // Mutual-defense drag-in: each belligerent's allies join the war.
+    for (const s of resolved) {
+      const rels = next.nations[s]?.relations ?? {};
+      for (const ally of Object.keys(rels).filter((x) => rels[x] === 'ally').sort()) {
+        if (!sides.includes(ally)) sides.push(ally);
+      }
+    }
+    const id = freshWarId(takenWarIds);
+    takenWarIds.add(id);
+    next.wars.push({
+      id,
+      sides,
+      declaredTurn: actingTurn,
+      declaredDate: next.date,
+      ...(d.aims && d.aims.length > 0 ? { aims: d.aims } : {}),
+      status: 'active',
+    });
+  }
+  // (2) END (by id; active only)
+  for (const e of data.end) {
+    const w = next.wars.find((w) => w.id === e.id && w.status === 'active');
+    if (!w) continue; // unknown id / already ended: no-op
+    w.status = e.outcome;
+  }
+  // (3) RELATION SYNC (prev = the state this turn started from)
+  syncWarRelations(prev, next);
+}
+
+export const wars: Ability<'wars'> = {
+  field: 'wars',
+  default: () => ({ declare: [], end: [] }),
+  validate: (raw) => validateWarOps(raw),
+  apply: (state, data, ctx) => applyWars(state, data, ctx.previous, ctx.actingTurn),
+  schemaLine: () =>
+    '  "wars": {"declare":[{"sides":["<nationId>","<nationId>"],"aims":["<short aim>"]}],"end":[{"id":"<war id>","outcome":"<armistice|capitulation>","terms":"<short terms>"}]},',
+  constraint: () =>
+    '- 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".',
+  isMeaningful: (data) => data.declare.length > 0 || data.end.length > 0,
+  stateFields: ['wars'],
+  stub: () => ({ declare: [], end: [] }),
+  payload: (ctx) => (ctx.wars !== undefined ? { wars: ctx.wars } : {}),
+};

server/db.test.ts

@@ -31,6 +31,17 @@ function makeState(id: string): GameState {
     regionStats: {
       GBR: { military: 80, economy: 70, stability: 60, population: 50 },
     },
+    // (v0.33.0, #56) no wars.
+    wars: [],
+    // (v0.35.0, #58) no active trades or embargoes.
+    trades: [],
+    embargoes: [],
+    // (v0.36.0, #59) no industry projects.
+    industry: [],
+    // (v0.43.0, #65) no sea-zone control on a fresh state.
+    seaZones: [],
+    // (v0.44.0, #66) no contested regions on a fresh state.
+    contested: [],
   };
 }
 
@@ -147,6 +158,118 @@ describe('openDb', () => {
     db.close();
   });
 
+  it('(v0.35.0 #58) a legacy row saved before the trades/embargoes fields existed loads with them defaulted to []', () => {
+    const db = openDb(':memory:');
+    const legacy = makeState('legacy');
+    delete (legacy as { trades?: unknown[] }).trades; // a pre-v0.35 save (fields absent)
+    delete (legacy as { embargoes?: unknown[] }).embargoes;
+    db.save(legacy);
+    const loaded = db.load('legacy');
+    expect(loaded).not.toBeNull();
+    expect(loaded!.trades).toEqual([]);
+    expect(loaded!.embargoes).toEqual([]);
+    db.close();
+  });
+
+  it('(v0.36.0 #59) a legacy row saved before the industry field existed loads with it defaulted to []', () => {
+    const db = openDb(':memory:');
+    const legacy = makeState('legacy');
+    delete (legacy as { industry?: unknown[] }).industry; // a pre-v0.36 save (field absent)
+    db.save(legacy);
+    const loaded = db.load('legacy');
+    expect(loaded).not.toBeNull();
+    expect(loaded!.industry).toEqual([]);
+    db.close();
+  });
+
+  it('(v0.37.0 #60) a legacy row saved before the nation nuclear flag existed loads with it absent (not capable)', () => {
+    const db = openDb(':memory:');
+    // makeState has no nation.nuclear field — a pre-v0.37 save. The flag is
+    // optional and not re-stamped by load, so an absent flag stays absent.
+    db.save(makeState('legacy'));
+    const loaded = db.load('legacy');
+    expect(loaded).not.toBeNull();
+    expect(loaded!.nations.uk.nuclear).toBeUndefined();
+    db.close();
+  });
+
+  it('(v0.37.0 #60) a set nation nuclear flag round-trips through save/load', () => {
+    const db = openDb(':memory:');
+    const s = makeState('nuc');
+    s.nations.uk.nuclear = true; // armed (e.g. by a turn's nuclear.arm op)
+    db.save(s);
+    const loaded = db.load('nuc');
+    expect(loaded).not.toBeNull();
+    expect(loaded!.nations.uk.nuclear).toBe(true);
+    db.close();
+  });
+
+  it('(v0.38.0 #61) a legacy row saved before the nation leader field existed loads with it absent (no leader)', () => {
+    const db = openDb(':memory:');
+    // makeState has no nation.leader field — a pre-v0.38 save. The field is
+    // optional and not re-stamped by load, so an absent leader stays absent.
+    db.save(makeState('legacy'));
+    const loaded = db.load('legacy');
+    expect(loaded).not.toBeNull();
+    expect(loaded!.nations.uk.leader).toBeUndefined();
+    db.close();
+  });
+
+  it('(v0.38.0 #61) a set nation leader round-trips through save/load', () => {
+    const db = openDb(':memory:');
+    const s = makeState('ldr');
+    s.nations.uk.leader = { name: 'Admiral Old' };
+    db.save(s);
+    const loaded = db.load('ldr');
+    expect(loaded).not.toBeNull();
+    expect(loaded!.nations.uk.leader).toEqual({ name: 'Admiral Old' });
+    db.close();
+  });
+
+  it('(v0.39.0 #62) a legacy row saved before the nation ideology field existed loads with it absent (no recorded government)', () => {
+    const db = openDb(':memory:');
+    // makeState has no nation.ideology field — a pre-v0.39 save. The field is
+    // optional and not re-stamped by load, so an absent ideology stays absent.
+    db.save(makeState('legacy'));
+    const loaded = db.load('legacy');
+    expect(loaded).not.toBeNull();
+    expect(loaded!.nations.uk.ideology).toBeUndefined();
+    db.close();
+  });
+
+  it('(v0.39.0 #62) a set nation ideology round-trips through save/load', () => {
+    const db = openDb(':memory:');
+    const s = makeState('ideo');
+    s.nations.uk.ideology = 'fascism';
+    db.save(s);
+    const loaded = db.load('ideo');
+    expect(loaded).not.toBeNull();
+    expect(loaded!.nations.uk.ideology).toBe('fascism');
+    db.close();
+  });
+
+  it('(v0.43.0 #65) a legacy row saved before the seaZones field existed loads with it defaulted to []', () => {
+    const db = openDb(':memory:');
+    const legacy = makeState('legacy');
+    delete (legacy as { seaZones?: unknown[] }).seaZones; // a pre-v0.43 save (field absent)
+    db.save(legacy);
+    const loaded = db.load('legacy');
+    expect(loaded).not.toBeNull();
+    expect(loaded!.seaZones).toEqual([]);
+    db.close();
+  });
+
+  it('(v0.44.0 #66) a legacy row saved before the contested field existed loads with it defaulted to []', () => {
+    const db = openDb(':memory:');
+    const legacy = makeState('legacy');
+    delete (legacy as { contested?: unknown[] }).contested; // a pre-v0.44 save (field absent)
+    db.save(legacy);
+    const loaded = db.load('legacy');
+    expect(loaded).not.toBeNull();
+    expect(loaded!.contested).toEqual([]);
+    db.close();
+  });
+
   it('delete removes a game by id and reports absence otherwise', () => {
     const db = openDb(':memory:');
     db.save(makeState('a'));

server/db.ts

@@ -4,6 +4,7 @@ import path from 'node:path';
 import Database from 'better-sqlite3';
 import { migrateRegionStats } from '../shared/protocol';
 import type { GameState } from '../shared/types';
+import { ABILITIES } from './abilities';
 
 export interface Db {
   save(state: GameState): void;
@@ -49,6 +50,20 @@ export function openDb(filePath: string): Db {
         if (state.pendingNationOps === undefined) state.pendingNationOps = [];
         // (v0.27, #44) Same for map markers: a legacy game has none placed.
         if (state.markers === undefined) state.markers = [];
+        // (v0.33.0 #56, v0.35.0 #58, v0.36 #59, v0.40.0 #67) Same for every
+        // ability-owned GameState field (wars / trades / embargoes / industry):
+        // a legacy game has none of them. The ABILITIES registry is the single
+        // source of truth for which fields the LLM abilities own — each is a
+        // list, so the default is `[]`, applied only-if-undefined so a saved
+        // value is never wiped. (Any pre-v0.33 `war` relation stays a
+        // bare/implicit relation — see syncWarRelations, which never
+        // force-creates a War entity.)
+        for (const a of ABILITIES) {
+          const fields = a.stateFields;
+          if (!fields) continue;
+          const row = state as unknown as Record<string, unknown>;
+          for (const f of fields) if (row[f] === undefined) row[f] = [];
+        }
         // (v0.28, #46) Rows saved before per-region stats existed are migrated
         // ONCE at load time (and never re-migrated afterwards — the field is
         // then present): each owned region is seeded with a copy of its owner's

server/engine.ts

@@ -4,38 +4,45 @@
 // 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,
+  IndustryProject,
   MapMarker,
   Nation,
-  NationStats,
   Preset,
   RelationStatus,
+  RegionResources,
   RegionStats,
   RoundItem,
+  SeaZoneClaim,
   StatKey,
+  TradeAgreement,
 } from '../shared/types';
 import { EVENT_TYPES, RELATION_STATUSES } from '../shared/types';
 import {
   addDays,
   canConquer,
   clampStat,
+  deriveNationResources,
   deriveNationStats,
   fnv1a32,
   isDateLike,
   isMarkerType,
+  isNuclearCapable,
   makeEvent,
   markerId,
   MAX_MARKERS,
   nationForPrompt,
+  type ContestedRegion,
   type MarkerInfo,
   type MarkerSpec,
   type NationOp,
   type RegionStatChange,
-  type Takeover,
   type TurnEventSpec,
   type TurnResult,
+  type WarInfo,
 } from '../shared/protocol';
 import {
   DEFAULT_MAX_TOKENS,
@@ -46,11 +53,73 @@ import {
   type WireMessage,
 } from './llm';
 import { ADVISOR_MARKER } from './stub';
+import {
+  freshNationId,
+  freshWarId,
+  NEW_NATION_STATS,
+  resolveNationRef,
+  resolveRegionKey,
+  str,
+} from './abilities/shared';
+import { ABILITIES, type AbilityCtx, type UserPromptCtx } from './abilities';
+// Re-exported so the existing callers (server/index.ts, the unit tests) keep
+// importing these shared primitives from the engine unchanged.
+export { freshNationId, freshWarId, NEW_NATION_STATS, resolveNationRef, resolveRegionKey };
 
 const VALID_EVENT_TYPES = new Set<string>(EVENT_TYPES);
 const VALID_RELATIONS = new Set<string>(RELATION_STATUSES);
 const VALID_OUTCOMES = new Set<string>(['success', 'failure', 'partial', 'neutral']);
 const VALID_STATS = new Set<string>(['military', 'economy', 'stability', 'population']);
+// (v0.40.0, #67) Re-exported from the ability modules so the existing callers
+// (server/index.ts, the unit tests) keep importing these names from the engine.
+export {
+  isHybridOpType,
+  isIndustryType,
+  activeWarPairs,
+  atWar,
+  syncWarRelations,
+  HYBRID_STAT_EFFECT,
+  shiftRelationTowardHostile,
+  validateEconomyOps,
+  validateHybridOps,
+  validateIdeologyOps,
+  validateIndustryOps,
+  validateLeaderOps,
+  validateNuclearOps,
+  validateTakeovers,
+  validateWarOps,
+  applyIndustryEffects,
+  validateDisasterEvents,
+  applyDisasterEvent,
+  isDisasterType,
+  isDisasterSeverity,
+  DISASTER_TYPES,
+  DISASTER_SEVERITIES,
+  DISASTER_EFFECTS,
+  validateMigrationOps,
+  applyMigrationOp,
+  shiftRelationTowardPositive,
+  isMigrationKind,
+  isMigrationScale,
+  MIGRATION_KINDS,
+  MIGRATION_SCALES,
+  MIGRATION_SOURCE_EFFECTS,
+  MIGRATION_DESTINATION_EFFECTS,
+  LARGE_INFLUX_STABILITY_DIP,
+  validateSeaOps,
+  applySeaControl,
+  applySeaZoneBonuses,
+  SEA_ZONE_BONUS,
+  SEA_ZONES,
+  SEA_ZONE_IDS,
+  isSeaZoneId,
+  seaZoneName,
+  validateContestedOps,
+  applyContested,
+  CONTESTED_FILL,
+  CONTESTED_STROKE,
+  contestedTooltipLabel,
+} from './abilities';
 
 // --- The LLM's getNeighbours tool (v0.21, #16 P2: contiguous region transfers) ---
 
@@ -150,7 +219,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
@@ -200,7 +271,7 @@ export function buildSystemPrompt(preset: Preset, withNeighboursTool = false): s
     '    {"kind":"split","nationRef":"<nation id or name>","parts":[{"name":"<new name>","territory":["<region key>"]}]}',
     '    {"kind":"merge","nationRefs":["<id>","<id>"],"survivingRef":"<id of the surviving nation>","into":"<new name>"}',
     '  ],',
-    '  "takeovers": [{"nationRef":"<nation id or name>","newRegimeName":"<name of the new regime>"}],',
+    ...ABILITIES.map((a) => a.schemaLine()),
     '  "markers": {"add":[{"type":"<city|factory|army|port|capital|fleet|rocket|gathering>","name":"<short name>","regionKey":"<region key>"}],"remove":["<marker id>"]}',
     '}',
     '',
@@ -218,7 +289,7 @@ export function buildSystemPrompt(preset: Preset, withNeighboursTool = false): s
     '- Rename: add {"kind":"rename","nationRef":"<nation id or name>","to":"<new name>"} for a revolution, regime change or reunification that changes a nation\'s name.',
     '- Split: add {"kind":"split","nationRef":"<nation id or name>","parts":[{"name":"<new name>","territory":["<region key>"]}, ...]} when a state breaks up (dissolution, secession). Use at least 2 parts and assign each of the nation\'s region keys to at most one part — any key you leave unassigned goes to the first part.',
     '- Merge: add {"kind":"merge","nationRefs":["<id or name>","<id or name>"],"survivingRef":"<id or name of the surviving nation>","into":"<new name>"} when states reunify or one is absorbed. Use at least 2 input nations and "survivingRef" must name one of them — the survivor keeps its id and its stats.',
-    '- 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.',
+    ...ABILITIES.map((a) => a.constraint()),
   '- 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.',
@@ -236,6 +307,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,
@@ -263,6 +337,76 @@ export function buildUserPrompt(
    * Omitted entirely when undefined.
    */
   markers?: MarkerInfo[],
+  /**
+   * (v0.33.0, #56) The game's currently ACTIVE wars, as the model sees them:
+   * stable id, sides and aims. Emitted verbatim (even when empty) so the
+   * model can reference a war's id in `TurnResult.wars.end` to end it.
+   * Omitted entirely when undefined.
+   */
+  wars?: WarInfo[],
+  /**
+   * (v0.34.0, #57) The player's current relations to every other nation
+   * (`nationId -> RelationStatus`). Emitted verbatim (even when empty) so the
+   * model sees the relation ladder it can nudge with `information` / `proxy`
+   * hybrid ops and knows the current state before an `exposed` backfire.
+   * 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[],
+  /**
+   * (v0.36, #59) Each nation's AGGREGATE resource profile (nation id -> the
+   * area×population-weighted mean of the resource profiles of the regions it
+   * owns, via `deriveNationResources`). Emitted verbatim (even when empty) so
+   * the model can reason about which nations are rich in which resource and
+   * where to build industry projects. Omitted entirely when undefined (no
+   * resource manifest loaded).
+   */
+  nationResources?: Record<string, RegionResources>,
+  /**
+   * (v0.36, #59) The game's currently ACTIVE industry projects (each a region
+   * key + project type). Emitted verbatim (even when empty) so the model knows
+   * which regions already host a project (and should not be re-declared) and
+   * can reference them. Omitted entirely when undefined.
+   */
+  industryProjects?: IndustryProject[],
+  /**
+   * (v0.37.0, #60) Each nation's nuclear capability (nation id -> boolean),
+   * computed by the caller via `isNuclearCapable` (the nation's `nuclear` flag
+   * OR a current `rocket` marker). When defined, each nation in the `state.
+   * nations` map is stamped with `nuclear: true|false` so the model knows who
+   * can arm/strike and who can MAD-retaliate. Omitted entirely (no `nuclear`
+   * key on any nation) when undefined.
+   */
+  nuclear?: Record<string, boolean>,
+  /**
+   * (v0.43.0, #65) The game's current sea-zone control (each a `{ zone, by }`
+   * pair of the fixed sea zones and their controlling nation id). Emitted
+   * verbatim (even when empty) so the model knows which of the 12 fixed sea
+   * zones each nation currently controls and can re-claim or contest them via
+   * `TurnResult.sea`. Omitted entirely when undefined.
+   */
+  seaZones?: SeaZoneClaim[],
+  /**
+   * (v0.44.0, #66) The game's current contested regions (each a `{ regionKey,
+   * parties }` pair — a war frontline in no nation's territory and not in
+   * `unowned`). Emitted verbatim (even when empty) so the model knows which
+   * regions are frontlines (and can `resolve` them or see their parties);
+   * omitted entirely when undefined.
+   */
+  contested?: ContestedRegion[],
 ): string {
   const player = state.nations[state.playerNationId];
   const playerName = player?.name ?? state.playerNationId;
@@ -328,31 +472,19 @@ export function buildUserPrompt(
   // seizure) — the model can act on them this turn. One line per matching
   // nation, emitted only when there is at least one; the rest of the payload
   // is left untouched. A soft nudge only — there is no hard gate behind it.
-  let takeoverRisks: string[] | undefined;
-  if (markers !== undefined && markers.length > 0) {
-    const risks = new Set<string>();
-    for (const m of markers) {
-      if (m.type !== 'gathering') continue;
-      const ownerId = m.owner;
-      if (!ownerId) continue;
-      const n = state.nations[ownerId];
-      if (n && n.stats.stability < 30) risks.add(n.id);
-    }
-    if (risks.size > 0) {
-      takeoverRisks = [...risks].map((id) => {
-        const n = state.nations[id];
-        return `${n?.name ?? id} (stability ${n?.stats.stability}, a gathering is in progress)`;
-      });
-    }
-  }
-
+  // (v0.40.0, #67) The ability-specific payload fields (takeoverRisks, wars,
+  // relations, trades, embargoes, resources, industry) are now computed by
+  // each Ability's payload() method and merged at their exact positions below.
   const payload: Record<string, unknown> = {
     state: {
       turn: state.turn,
       date: state.date,
       playerNationId: state.playerNationId,
       nations: Object.fromEntries(
-        Object.entries(state.nations).map(([id, n]) => [id, nationForPrompt(n)]),
+        Object.entries(state.nations).map(([id, n]) => [
+          id,
+          nuclear ? { ...nationForPrompt(n), nuclear: nuclear[id] ?? false } : nationForPrompt(n),
+        ]),
       ),
       recentEvents: state.events.slice(-5).map((e) => ({
         turn: e.turn,
@@ -372,9 +504,30 @@ export function buildUserPrompt(
   if (regionReference) payload.regions = regionReference;
   if (frontier !== undefined) payload.frontier = frontier;
   if (frontierMilitary !== undefined) payload.frontierMilitary = frontierMilitary;
-  if (takeoverRisks !== undefined) payload.takeoverRisks = takeoverRisks;
+  // (v0.40.0, #67) Build the UserPromptCtx once and merge each ability's
+  // payload() at its exact position (the key order is load-bearing for the
+  // golden test).
+  const upCtx: UserPromptCtx = {
+    state,
+    markers,
+    wars,
+    relations,
+    trades,
+    embargoes,
+    nationResources,
+    industryProjects,
+    seaZones,
+    contested,
+  };
+  Object.assign(payload, ABILITIES[0].payload(upCtx)); // takeovers → takeoverRisks
   if (noMansLand !== undefined) payload.unowned = noMansLand;
   if (markers !== undefined) payload.markers = markers;
+  Object.assign(payload, ABILITIES[1].payload(upCtx)); // wars → wars
+  Object.assign(payload, ABILITIES[2].payload(upCtx)); // hybrid → relations
+  Object.assign(payload, ABILITIES[3].payload(upCtx)); // economy → trades, embargoes
+  Object.assign(payload, ABILITIES[4].payload(upCtx)); // industry → resources, industry
+  Object.assign(payload, ABILITIES[10].payload(upCtx)); // sea → seaZones (always emitted)
+  Object.assign(payload, ABILITIES[11].payload(upCtx)); // contested → contested (only when non-empty)
   return JSON.stringify(payload, null, 2);
 }
 
@@ -433,13 +586,6 @@ export function parseTurnResult(
   return validateTurnResult(obj, regionKeyResolver);
 }
 
-function str(s: unknown, max = 0): string | null {
-  if (typeof s !== 'string') return null;
-  const t = s.trim();
-  if (!t) return null;
-  return max ? t.slice(0, max) : t;
-}
-
 /**
  * Validate a raw (LLM) `nationOps` array into safe {@link NationOp} values
  * (v0.23, #16 P4a). Defensive like the rest of the parser: entries with an
@@ -513,6 +659,17 @@ export function validateTurnResult(
     unowned: [],
     nationOps: [],
     takeovers: [],
+    wars: { declare: [], end: [] },
+    hybrid: { ops: [] },
+    economy: { trade: [], embargo: [] },
+    industry: { projects: [] },
+    nuclear: { arm: [], strikes: [] },
+    leaders: { changes: [] },
+    ideology: { changes: [] },
+    disasters: { events: [] },
+    migration: { ops: [] },
+    sea: { control: [] },
+    contested: { open: [], resolve: [] },
     markers: { add: [], remove: [] },
   };
 
@@ -603,9 +760,12 @@ export function validateTurnResult(
   // list for the player to confirm/reject.
   result.nationOps = validateNationOps(o.nationOps);
 
-  // (v0.32.0, #54) Non-military regime changes (takeovers) — applied directly
-  // by applyTurnResult (automatic, not player-confirmed).
-  result.takeovers = validateTakeovers(o.takeovers);
+  // The 11 per-feature LLM abilities (v0.40.0, #67): each one's validate call
+  // is owned by its Ability module in the ABILITIES registry. The field's raw
+  // value is passed through a.validate() which returns the validated field shape.
+  for (const a of ABILITIES) {
+    (result as unknown as Record<string, unknown>)[a.field] = a.validate((o as Record<string, unknown>)[a.field]);
+  }
 
   // (v0.27, #44) Map-marker ops: new placements (validated here) and
   // removals by stable id. Applied by applyTurnResult after the territory
@@ -713,37 +873,6 @@ export function validateRegionChanges(
   return out;
 }
 
-/**
- * (v0.32.0, #54) Validate the raw `takeovers` array of a turn into a safe
- * {@link Takeover} list — the non-military regime-change lever (a coup or
- * revolution that renames a nation to its new regime name). Defensive like
- * the rest of the parser — never throws. Each entry needs a non-empty
- * `nationRef` (the target nation's id or name — capped at 200 chars) and a
- * non-empty `newRegimeName` (capped at 200 chars). Resolution of `nationRef`
- * to a concrete nation id happens at apply time (`resolveNationRef`), not
- * here. Entries with either field missing or whitespace-only are dropped.
- */
-export function validateTakeovers(raw: unknown): Takeover[] {
-  if (!Array.isArray(raw)) return [];
-  const out: Takeover[] = [];
-  for (const e of raw) {
-    if (!e || typeof e !== 'object') continue;
-    const o = e as Record<string, unknown>;
-    const nationRef = str(o.nationRef, 200);
-    const newRegimeName = str(o.newRegimeName, 200);
-    if (nationRef && newRegimeName) out.push({ nationRef, newRegimeName });
-  }
-  return out;
-}
-
-/**
- * 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
- * when the model under-narrates it), or a nation-op proposal (v0.23 #16 P4a:
- * a proposal is a real pending-world change the player will resolve, so it
- * must survive the retry/nudge path instead of being replaced by the generic
- * "unclear" result).
- */
 export function isMeaningful(result: TurnResult): boolean {
   return (
     result.events.length > 0 ||
@@ -752,8 +881,10 @@ export function isMeaningful(result: TurnResult): boolean {
     result.regionChanges.length > 0 ||
     result.unowned.length > 0 ||
     result.nationOps.length > 0 ||
-    // (v0.32.0, #54) a takeover is a real world change (regime rename).
-    result.takeovers.length > 0 ||
+    // (v0.40.0, #67) any of the 9 per-feature abilities having a non-empty
+    // payload is a real world change (each Ability's isMeaningful predicate
+    // is the per-ability half of the old 18-sub-field check).
+    ABILITIES.some((a) => a.isMeaningful(result[a.field])) ||
     // (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
@@ -798,6 +929,13 @@ function genericUnclearEvent(state: GameState): TurnEventSpec {
  * (from the geo `properties.name`, via server/regions.ts) for the text of the
  * engine-emitted "invasion repelled" event; without it the event falls back to
  * the raw key. Pure either way.
+ *
+ * `resourceOf` (v0.36, #59) resolves a region key to its synthesized resource
+ * profile (`{ oil, iron, food, industry }`, from public/region-resources.json
+ * via server/regions.ts). It is used to scale each industry project's per-turn
+ * economy boost by the region's `industry` value (a region with a strong
+ * industry profile yields a bigger return). Without it the boost is the
+ * unscaled base value — the engine stays pure and deterministic either way.
  */
 export function applyTurnResult(
   state: GameState,
@@ -806,12 +944,22 @@ export function applyTurnResult(
   centroidOf?: (key: string) => { lat: number; lon: number; spread: number } | undefined,
   geoOf?: (key: string) => { area: number; population: number } | undefined,
   regionNameOf?: (key: string) => string | undefined,
+  resourceOf?: (key: string) => RegionResources | undefined,
 ): GameState {
   const next: GameState = JSON.parse(JSON.stringify(state));
   next.version = (state.version ?? 0) + 1; // every mutation is a new revision
   // (v0.28, #46) per-region stats table; a legacy/corrupt clone without the
   // field starts empty (the turn then re-inits claimed regions as it goes).
   next.regionStats = next.regionStats ?? {};
+  // (v0.36, #59) active industry projects; a legacy/corrupt clone without the
+  // field starts empty (the turn then only ever adds to it).
+  next.industry = next.industry ?? [];
+  // (v0.43.0, #65) sea-zone control; a legacy/corrupt clone without the field
+  // starts empty (the turn then upserts this turn's claims into it).
+  next.seaZones = next.seaZones ?? [];
+  // (v0.44.0, #66) contested regions (war frontlines); a legacy/corrupt clone
+  // without the field starts empty (the turn then opens/resolves contests).
+  next.contested = next.contested ?? [];
   const actingTurn = state.turn; // this action resolves the current turn
   next.turn = state.turn + 1; // then we advance to the next turn to play
   next.date = isDateLike(result.date) ? result.date : addDays(state.date, 2);
@@ -907,12 +1055,34 @@ export function applyTurnResult(
     }
     set.add(gainer);
   }
+  // (v0.44.0, #66) Contested-region guard for the claims step below: a region
+  // that is currently a war frontline (in `state.contested`) sits in no
+  // nation's territory, so a normal `gain` would otherwise treat it as a free
+  // re-claim. A contested key may only be claimed by a normal claim when this
+  // same turn resolves the contest AND the gainer is one of the contesting
+  // parties (a party re-claim); otherwise the frontline stays contested for
+  // the contested layer (later in the turn) to decide its fate.
+  const contestedBefore = new Set((state.contested ?? []).map((c) => c.regionKey));
+  const resolveThisTurn = new Set(result.contested.resolve);
+  const contestedParties = new Map(
+    (state.contested ?? []).map((c) => [c.regionKey, c.parties]),
+  );
   for (const [key, claiming] of claimants) {
     if (claiming.size !== 1) continue; // double claim: the key stays as it was
     const gainer = [...claiming][0];
     const owner = ownerOf.get(key); // undefined: no owner; '': 2+ owners (corrupt)
     if (owner === '') continue; // pre-existing double ownership: never touched
     if (owner !== undefined && owner === gainer) continue; // self-gain: no-op
+    // (v0.44.0, #66) a currently-contested frontline is not a normal claim
+    // target: a claim on it only proceeds when this turn resolves the contest
+    // and the gainer is one of the contesting parties (a party re-claim);
+    // otherwise the frontline stays contested for the contested layer below.
+    if (
+      contestedBefore.has(key) &&
+      (!resolveThisTurn.has(key) || !contestedParties.get(key)?.includes(gainer))
+    ) {
+      continue;
+    }
     // (v0.30, #50) MILITARY HARD GATE: a CONTESTED conquest (the key has a
     // different sole owner) only proceeds when the attacker's derived military
     // is not MORE than CONQUEST_MILITARY_MARGIN below the defender's. A
@@ -1006,28 +1176,22 @@ export function applyTurnResult(
     n.stats = deriveNationStats(n.territory, next.regionStats, geoOf);
   }
 
-  // --- Takeovers (v0.32.0, #54): non-military regime changes (coups /
-  //     revolutions) that rename a nation to its new regime. Applied AFTER the
-  //     per-region recompute (the rename doesn't depend on territory or stats,
-  //     so it is order-independent with respect to those steps) and BEFORE the
-  //     markers block (a marker's owner is a nation id, not a name, so the
-  //     rename does not affect the owner recompute).
-  //
-  //     For each takeover:
-  //       1. Resolve the target nation via `resolveNationRef` (id first, then
-  //          case-insensitive unique name). Skip (no-op) if `null` — an
-  //          unknown or ambiguous ref is silently dropped, never thrown.
-  //       2. Rename the resolved nation: set `n.name = newRegimeName`. Only
-  //          the display name changes — the stable id, territory, relations
-  //          (keyed by id), stats, and `playerNationId` (which references the
-  //          id, not the name) are all preserved. The player keeps leading an
-  //          overthrown nation under its new regime.
-  for (const t of result.takeovers) {
-    const id = resolveNationRef(next, t.nationRef);
-    if (id === null) continue; // unknown / ambiguous ref: no-op
-    const n = next.nations[id];
-    if (!n) continue; // defensive: id resolved but nation missing (corrupt state)
-    n.name = t.newRegimeName;
+  // (v0.40.0, #67) The 9 per-feature LLM abilities, applied in ABILITIES
+  // order (takeovers → wars → hybrid → economy → industry → nuclear →
+  // leaders → ideology → disasters). Each Ability's apply method handles its
+  // own field's validated data against the post-territory/post-recompute
+  // `next` state. The AbilityCtx carries the shared resolvers.
+  const abilityCtx: AbilityCtx = {
+    previous: state,
+    actingTurn,
+    validRegionKeys: validKeys,
+    regionNameOf,
+    geoOf,
+    resourceOf,
+    centroidOf,
+  };
+  for (const a of ABILITIES) {
+    a.apply(next, result[a.field], abilityCtx);
   }
 
   // --- Map markers (v0.27, #44) ---
@@ -1153,81 +1317,6 @@ function validPendingOpIndex(state: GameState, index: number): boolean {
   return Number.isInteger(index) && index >= 0 && index < len;
 }
 
-/**
- * Resolve a nation reference (the `nationRef` of a NationOp — the LLM may
- * write either the nation's stable `id` or its human-readable `name`) to a
- * concrete nation id: an exact id match wins, then a unique case-insensitive
- * name match. Returns `null` when the reference is empty, unknown, or
- * ambiguous (two or more nations share that name) — every caller treats
- * `null` as "no-op" and nothing here ever throws.
- */
-export function resolveNationRef(state: GameState, ref: string): string | null {
-  const r = (ref ?? '').trim();
-  if (!r) return null;
-  if (state.nations[r]) return r; // exact id first
-  const matches = Object.values(state.nations).filter(
-    (n) => n.name.trim().toLowerCase() === r.toLowerCase(),
-  );
-  return matches.length === 1 ? matches[0].id : null;
-}
-
-/**
- * (v0.29, #46 PR 2) Resolve a **region** reference (a `regionChanges` entry's
- * `region` — the LLM may write either the region's stable **key** or its
- * human-readable **name**) to a concrete region key: an exact key match wins,
- * then a unique case-insensitive name match (via `nameOf`). Returns `null`
- * when the reference is empty, unknown, or ambiguous (two or more regions
- * share that name) — every caller treats `null` as "drop this change" and
- * nothing here ever throws. Mirrors {@link resolveNationRef}. `validKeys` is
- * the set of all region keys and `nameOf` maps a key to its human name (both
- * supplied by server/regions.ts).
- */
-export function resolveRegionKey(
-  ref: string,
-  validKeys: ReadonlySet<string>,
-  nameOf: (key: string) => string | undefined,
-): string | null {
-  const r = (ref ?? '').trim();
-  if (!r) return null;
-  if (validKeys.has(r)) return r; // exact key first
-  const lower = r.toLowerCase();
-  let match: string | null = null;
-  for (const k of validKeys) {
-    const name = nameOf(k);
-    if (name && name.trim().toLowerCase() === lower) {
-      if (match !== null) return null; // ambiguous: two or more regions share the name
-      match = k;
-    }
-  }
-  return match;
-}
-
-/**
- * Generate a fresh, unused nation id for a newly created nation (split
- * parts, v0.24 #16 P4b): the first free of `n1`, `n2`, ... The caller adds
- * each id it creates to `taken` as it goes, so ids stay unique within an
- * op and are never reused from a removed nation.
- */
-export function freshNationId(taken: ReadonlySet<string>): string {
-  for (let i = 1; ; i++) {
-    const id = `n${i}`;
-    if (!taken.has(id)) return id;
-  }
-}
-
-/**
- * The baseline stats a freshly created nation starts with (split parts,
- * v0.24 #16 P4b) — a neutral middle-of-the-scale profile, deliberately NOT
- * a copy of the parent's stats (a small rump state is not the parent's
- * military power).
- */
-export const NEW_NATION_STATS: NationStats = {
-  military: 50,
-  economy: 50,
-  stability: 50,
-  population: 50,
-};
-
 /**
  * Defensive cleanup after nations are removed (merge, v0.24 #16 P4b): drop
  * the removed nations' ids from every remaining nation's `relations` map so
@@ -1488,8 +1577,17 @@ export async function runTurn(opts: {
    * it falls back to the raw region key. Pure either way.
    */
   regionNameOf?: (key: string) => string | undefined;
+  /**
+   * (v0.36, #59) Region-key -> synthesized resource profile resolver (from
+   * public/region-resources.json via server/regions.ts). Present, each
+   * industry project's per-turn economy boost is scaled by its region's
+   * `industry` value, and each nation's aggregate resource profile is carried
+   * in the user prompt; absent, industry boosts use the unscaled base value
+   * and the profile is omitted.
+   */
+  resourceOf?: (key: string) => RegionResources | undefined;
 }): Promise<{ state: GameState; result: TurnResult }> {
-  const { llm, preset, state, items, regionReference, validRegionKeys, getNeighbours, centroidOf, geoOf, regionKeyResolver, regionNameOf } = opts;
+  const { llm, preset, state, items, regionReference, validRegionKeys, getNeighbours, centroidOf, geoOf, regionKeyResolver, regionNameOf, resourceOf } = opts;
   const chatWithTools = llm.chatWithTools;
   const useTools = getNeighbours !== undefined && chatWithTools !== undefined;
   const system = buildSystemPrompt(preset, useTools);
@@ -1505,7 +1603,70 @@ export async function runTurn(opts: {
     regionKey: m.regionKey,
     owner: m.ownerNationId,
   }));
-  const user = buildUserPrompt(state, items, regionReference, frontier, state.unowned ?? [], markers);
+  // (v0.33.0, #56) the model always sees the currently ACTIVE wars (empty list
+  // on a fresh game) so it can reference a war's id in `wars.end` to end it;
+  // ended wars stay in GameState.wars as history but are not surfaced.
+  const wars = (state.wars ?? [])
+    .filter((w) => w.status === 'active')
+    .map((w) => ({
+      id: w.id,
+      sides: w.sides,
+      ...(w.aims && w.aims.length > 0 ? { aims: w.aims } : {}),
+    }));
+  // (v0.34.0, #57) the player's current relations to every other nation, so the
+  // model sees the ladder its `information` / `proxy` hybrid ops nudge (and the
+  // starting point before an `exposed` backfire). Always emitted ({} when the
+  // player has no relations yet).
+  const relations = state.nations[state.playerNationId]?.relations ?? {};
+  // (v0.36, #59) each nation's AGGREGATE resource profile (the area×population-
+  // weighted mean of the resource profiles of the regions it owns). Carried in
+  // the user prompt ONLY when the resource manifest is loaded (resourceOf
+  // present); otherwise omitted (undefined) so the prompt — and the stub —
+  // stay identical to the no-manifest case.
+  const nationResources =
+    resourceOf === undefined
+      ? undefined
+      : Object.fromEntries(
+          Object.values(state.nations).map((n) => [
+            n.id,
+            deriveNationResources(n.territory, resourceOf, geoOf),
+          ]),
+        );
+  // (v0.37.0, #60) each nation's nuclear capability (its `nuclear` flag OR a
+  // current `rocket` marker), so the model knows who can arm/strike and who
+  // can MAD-retaliate. Always emitted (computed from the PRE-turn markers).
+  const nuclearCapability = Object.fromEntries(
+    Object.values(state.nations).map((n) => [n.id, isNuclearCapable(n, state.markers ?? [])]),
+  );
+  const user = buildUserPrompt(
+    state,
+    items,
+    regionReference,
+    frontier,
+    state.unowned ?? [],
+    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,
+    // (v0.36, #59) the aggregate resource profiles (undefined without the
+    // manifest) + the active industry projects, so the model knows which
+    // regions already host a project and which nations are rich in which
+    // resource.
+    nationResources,
+    state.industry ?? [],
+    // (v0.37.0, #60) per-nation nuclear capability (flag or rocket marker).
+    nuclearCapability,
+    // (v0.43.0, #65) the current sea-zone control (always emitted — even when
+    // empty — so the model knows who controls which of the fixed sea zones).
+    state.seaZones ?? [],
+    // (v0.44.0, #66) the current contested regions (war frontlines) — emitted
+    // verbatim (even when empty) so the model knows which regions are
+    // frontlines and can resolve them.
+    state.contested ?? [],
+  );
   const nudge =
     'Your previous output was invalid. Respond with ONLY the JSON object described above for this batch — no prose, no fences.';
 
@@ -1548,7 +1709,7 @@ export async function runTurn(opts: {
   }
 
   if (result === null || !isMeaningful(result)) {
-    result = {
+    const fallback = {
       date: addDays(state.date, 2),
       events: [genericUnclearEvent(state)],
       stateChanges: [],
@@ -1557,13 +1718,17 @@ export async function runTurn(opts: {
       territoryChanges: [],
       unowned: [],
       nationOps: [],
-      takeovers: [],
       markers: { add: [], remove: [] },
-    };
+    } as unknown as Record<string, unknown>;
+    // (v0.40.0, #67) Each ability's default() provides its field's empty value.
+    for (const a of ABILITIES) {
+      fallback[a.field] = a.default();
+    }
+    result = fallback as unknown as TurnResult;
   }
 
   return {
-    state: applyTurnResult(state, result, validRegionKeys, centroidOf, geoOf, regionNameOf),
+    state: applyTurnResult(state, result, validRegionKeys, centroidOf, geoOf, regionNameOf, resourceOf),
     result,
   };
 }

server/index.ts

@@ -25,7 +25,7 @@ import { makeScenarioStubLlmClient } from './stubScenario';
 import { finalizeWorld, generateDraft } from './scenario';
 import { askAdvisor, confirmNationOp, queueRoundItem, rejectNationOp, removeRoundItem, resolveRegionKey, runTurn } from './engine';
 import { buildRegionMap } from './map';
-import { allTerritoryKeys, centroidOf, expandCountriesToKeys, geoOf, hasAdjacency, hasCentroids, hasGeo, loadRegions, neighboursOf, referenceForKeys, regionName, validCountryCodes, validKeys } from './regions';
+import { allTerritoryKeys, centroidOf, expandCountriesToKeys, geoOf, hasAdjacency, hasCentroids, hasGeo, hasResources, loadRegions, neighboursOf, referenceForKeys, regionName, resourceOf, validCountryCodes, validKeys } from './regions';
 import { createPresetStore } from './presets';
 import { createTemplateStore } from './templates';
 import { openDb, type Db } from './db';
@@ -178,6 +178,22 @@ app.post('/api/games', (req: Request, res) => {
     // real region keys — each region starts as a copy of its owner's initial
     // stats, so the derived aggregate equals the nation's stats on turn 1.
     regionStats: {},
+    // (v0.33.0, #56) No wars on a fresh game; the LLM declares them over time
+    // (any preset-level `war` relation stays a bare/implicit one, not an
+    // entity — see syncWarRelations).
+    wars: [],
+    // (v0.35.0, #58) No active trades or embargoes on a fresh game; the LLM
+    // declares (and lifts) them over time via TurnResult.economy.
+    trades: [],
+    embargoes: [],
+    // (v0.36.0, #59) No active industry projects on a fresh game; the LLM
+    // declares them over time via TurnResult.industry (one per region, a
+    // per-region SET).
+    industry: [],
+    // (v0.43.0, #65) no sea-zone control on a fresh state.
+    seaZones: [],
+    // (v0.44.0, #66) no contested regions on a fresh state.
+    contested: [],
   };
   // v0.19 (#16 P1): expand each nation's ISO_A3 country list to the region keys
   // of all its sub-regions, so ownership (and the choropleth) is at region
@@ -362,6 +378,12 @@ app.post('/api/games/:id/jump', async (req, res) => {
       // event (geo properties.name, else the raw key). Always on — the
       // resolver is pure and degrades to the key when the manifest is absent.
       regionNameOf: (k) => regionName(k),
+      // (v0.36.0, #59) when the region-resources manifest (the synthesized
+      // per-region resource profiles) loaded, hand the engine the resolver —
+      // the industry boost is then scaled by each region's `industry` value
+      // (without it boosts use the unscaled base value) and each nation's
+      // aggregate resource profile is carried in the user prompt.
+      resourceOf: hasResources() ? (key) => resourceOf(key) : undefined,
     });
     db.save(state);
     broadcast(id, 'turn', { state, result });

server/map.test.ts

@@ -52,6 +52,17 @@ const state: GameState = {
   markers: [],
   // (v0.28, #46) the map is ownership-only; the region-stats table is unused here.
   regionStats: {},
+  // (v0.33.0, #56) the map is ownership-only; wars are unused here.
+  wars: [],
+  // (v0.35.0, #58) the map is ownership-only; trades/embargoes are unused here.
+  trades: [],
+  embargoes: [],
+  // (v0.36.0, #59) the map is ownership-only; industry is unused here.
+  industry: [],
+  // (v0.43.0, #65) no sea-zone control on a fresh state.
+  seaZones: [],
+  // (v0.44.0, #66) no contested regions on a fresh state.
+  contested: [],
 };
 
 // The RegionMap built from the fixture: the authoritative region key → owner source.

server/protocol.test.ts

@@ -2,8 +2,11 @@ import { describe, expect, it } from 'vitest';
 import {
   canConquer,
   CONQUEST_MILITARY_MARGIN,
+  deriveNationResources,
   deriveNationStats,
+  IDEOLOGY_STABILITY_EFFECT,
   migrateRegionStats,
+  nationForPrompt,
   seedRegionStats,
   weightedMedian,
 } from '../shared/protocol';
@@ -41,6 +44,14 @@ function mkState(
     pendingNationOps: [],
     markers: [],
     regionStats: {} as GameState['regionStats'],
+    wars: [],
+    trades: [],
+    embargoes: [],
+    industry: [],
+    // (v0.43.0, #65) no sea-zone control on a fresh state.
+    seaZones: [],
+    // (v0.44.0, #66) no contested regions on a fresh state.
+    contested: [],
   };
   if (regionStats !== undefined) base.regionStats = regionStats as GameState['regionStats'];
   else delete (base as { regionStats?: unknown }).regionStats; // simulate a legacy row
@@ -136,6 +147,81 @@ describe('deriveNationStats', () => {
   });
 });
 
+// --- deriveNationResources ---------------------------------------------------
+
+describe('deriveNationResources (v0.36.0 #59)', () => {
+  const prof: Record<string, { oil: number; iron: number; food: number; industry: number }> = {
+    a: { oil: 0.2, iron: 0.2, food: 0.2, industry: 0.2 },
+    b: { oil: 0.8, iron: 0.8, food: 0.8, industry: 0.8 },
+  };
+  const geo: Record<string, { area: number; population: number }> = {
+    a: { area: 100, population: 1000 },
+    b: { area: 1000, population: 1000 },
+  };
+
+  it('weights by area×population: the larger region dominates the average', () => {
+    // a: weight 100×1000=100000, b: weight 1000×1000=1000000
+    // → (0.2×1e5 + 0.8×1e6)/1.1e6 = 82/110 = 0.7454… → 0.75 on every axis
+    expect(deriveNationResources(['a', 'b'], (k) => prof[k], (k) => geo[k])).toEqual({
+      oil: 0.75, iron: 0.75, food: 0.75, industry: 0.75,
+    });
+  });
+
+  it('degrades to a uniform (unweighted) average without geo: equal weights', () => {
+    // equal weights 1,1 → the true mean 0.5 on every axis
+    expect(deriveNationResources(['a', 'b'], (k) => prof[k])).toEqual({
+      oil: 0.5, iron: 0.5, food: 0.5, industry: 0.5,
+    });
+    // same when geoOf is provided but returns undefined for the keys (missing geo)
+    expect(deriveNationResources(['a', 'b'], (k) => prof[k], () => undefined)).toEqual({
+      oil: 0.5, iron: 0.5, food: 0.5, industry: 0.5,
+    });
+  });
+
+  it('skips a region key that has no resource-profile entry', () => {
+    // b has no profile → only a is counted → a's values
+    const out = deriveNationResources(['a', 'b'], (k) => (k === 'a' ? prof.a : undefined), (k) => geo[k]);
+    expect(out).toEqual(prof.a);
+  });
+
+  it('returns the zero profile when none of the owned regions has a profile', () => {
+    expect(deriveNationResources(['a', 'b'], () => undefined)).toEqual({
+      oil: 0, iron: 0, food: 0, industry: 0,
+    });
+  });
+
+  it('a single region yields exactly that region\'s profile', () => {
+    expect(deriveNationResources(['a'], (k) => prof[k], (k) => geo[k])).toEqual(prof.a);
+  });
+
+  it('treats zero/negative area or population as a fallback weight of 1', () => {
+    // a: area 0 → weight 1×1000=1000; b: full weight 1e6 → b dominates
+    const g: Record<string, { area: number; population: number }> = {
+      a: { area: 0, population: 1000 },
+      b: { area: 1000, population: 1000 },
+    };
+    expect(deriveNationResources(['a', 'b'], (k) => prof[k], (k) => g[k])).toEqual({
+      oil: 0.8, iron: 0.8, food: 0.8, industry: 0.8,
+    });
+  });
+
+  it('rounds each axis to 2 decimal places', () => {
+    // a=0.2 (w=1×1=1) + b=0.4 (w=2×1=2) → (0.2×1 + 0.4×2)/(1+2) = 1.0/3 = 0.3333… → 0.33
+    const g: Record<string, { area: number; population: number }> = {
+      a: { area: 1, population: 1 },
+      b: { area: 2, population: 1 },
+    };
+    const out = deriveNationResources(
+      ['a', 'b'],
+      (k) => k === 'a'
+        ? { oil: 0.2, iron: 0.2, food: 0.2, industry: 0.2 }
+        : { oil: 0.4, iron: 0.4, food: 0.4, industry: 0.4 },
+      (k) => g[k],
+    );
+    expect(out).toEqual({ oil: 0.33, iron: 0.33, food: 0.33, industry: 0.33 });
+  });
+});
+
 // --- seedRegionStats ---------------------------------------------------------
 
 describe('seedRegionStats', () => {
@@ -257,3 +343,30 @@ describe('canConquer', () => {
     expect(canConquer(49, 50, 0)).toBe(false); // one below → repel
   });
 });
+
+// --- IDEOLOGY_STABILITY_EFFECT (v0.39, #62) ----------------------------------
+
+describe('IDEOLOGY_STABILITY_EFFECT (v0.39.0 #62)', () => {
+  it('a regime shift is a deterministic −5 stability dip', () => {
+    expect(IDEOLOGY_STABILITY_EFFECT).toBe(-5);
+  });
+});
+
+// --- nationForPrompt — ideology (v0.39, #62) ---------------------------------
+
+describe('nationForPrompt — ideology (v0.39.0 #62)', () => {
+  it('stamps the ideology when a nation has one', () => {
+    const n = nation('uk', 'UK', S(50, 50, 50, 50), ['k1']);
+    n.ideology = 'fascism';
+    expect(nationForPrompt(n).ideology).toBe('fascism');
+    // and it survives JSON serialisation (the user prompt path)
+    expect(JSON.stringify(nationForPrompt(n))).toContain('"ideology":"fascism"');
+  });
+
+  it('omits the ideology from the JSON when a nation has none (undefined key dropped)', () => {
+    const n = nation('uk', 'UK', S(50, 50, 50, 50), ['k1']);
+    expect(n.ideology).toBeUndefined();
+    // JSON.stringify drops undefined-valued keys → no "ideology" in the prompt
+    expect(JSON.stringify(nationForPrompt(n))).not.toContain('ideology');
+  });
+});

server/regions.test.ts

@@ -12,11 +12,13 @@ import {
   hasCentroids,
   hasGeo,
   hasRegionData,
+  hasResources,
   loadRegions,
   neighboursOf,
   referenceForKeys,
   regionName,
   resetRegions,
+  resourceOf,
   validKeys,
 } from './regions';
 import type { GameState } from '../shared/types';
@@ -110,6 +112,16 @@ describe('regions (region-key loader, v0.19 #16 P1)', () => {
       markers: [],
       // (v0.28, #46) unused here (allTerritoryKeys is ownership-only).
       regionStats: {},
+      wars: [],
+      // (v0.35.0, #58) unused here (allTerritoryKeys is ownership-only).
+      trades: [],
+      embargoes: [],
+      // (v0.36.0, #59) unused here (allTerritoryKeys is ownership-only).
+      industry: [],
+      // (v0.43.0, #65) no sea-zone control on a fresh state.
+      seaZones: [],
+      // (v0.44.0, #66) no contested regions on a fresh state.
+      contested: [],
     };
     // 16 GBR sub-regions + 42 FRA sub-regions, no overlap between the two.
     expect(allTerritoryKeys(state).size).toBe(58);
@@ -168,6 +180,16 @@ describe('regions (region-key loader, v0.19 #16 P1)', () => {
     expect(geoOf('not-a-real-key-xyz')).toBeUndefined();
   });
 
+  it('(v0.36 #59) hasResources() is true and resourceOf resolves a real key to a 4-value profile', () => {
+    expect(hasResources()).toBe(true);
+    // exact spot-check values pinned from the committed manifest (Ain, FRA)
+    expect(resourceOf('ain-lqtt')).toEqual({ oil: 0.94, iron: 0.92, food: 0.51, industry: 0.4 });
+  });
+
+  it('(v0.36 #59) resourceOf returns undefined for an unknown key', () => {
+    expect(resourceOf('not-a-real-key-xyz')).toBeUndefined();
+  });
+
   describe('graceful degradation with no region data', () => {
     beforeEach(() => resetRegions());
 
@@ -187,6 +209,9 @@ describe('regions (region-key loader, v0.19 #16 P1)', () => {
       // and no region-geo: the per-region stats weighting degrades to uniform
       expect(hasGeo()).toBe(false);
       expect(geoOf('ain-lqtt')).toBeUndefined();
+      // and no region-resources: industry boosts use the unscaled base value
+      expect(hasResources()).toBe(false);
+      expect(resourceOf('ain-lqtt')).toBeUndefined();
     });
   });
 
@@ -244,6 +269,19 @@ describe('loadRegions resolves the manifest per environment (dev public/ vs prod
     // and no region-geo (not copied into this dist/) -> stats weighting is uniform
     expect(hasGeo()).toBe(false);
     expect(geoOf('ain-lqtt')).toBeUndefined();
+    // and no region-resources (not copied into this dist/) -> boosts unscaled
+    expect(hasResources()).toBe(false);
+    expect(resourceOf('ain-lqtt')).toBeUndefined();
+  });
+
+  it('(v0.36 #59) a dist/ WITH the region-resources manifest loads it (prod layout)', () => {
+    copyFileSync(
+      path.join(realRoot, 'public', 'region-resources.json'),
+      path.join(prodRoot, 'dist', 'region-resources.json'),
+    );
+    expect(loadRegions(prodRoot)).toBe(true);
+    expect(hasResources()).toBe(true);
+    expect(resourceOf('ain-lqtt')).toEqual({ oil: 0.94, iron: 0.92, food: 0.51, industry: 0.4 });
   });
 
   it('(v0.27 #44) a dist/ WITH the centroids manifest loads them (prod layout)', () => {

server/regions.ts

@@ -19,6 +19,9 @@
 //     — the data behind LLM-placed map markers (v0.27, #44)
 //   - geoOf(): a region key's area (km²) + population (from region-geo.json)
 //     — the weighting source for the per-region stats model (v0.28, #46)
+//   - resourceOf(): a region key's synthesized resource profile (from
+//     region-resources.json) — the data behind the LLM's industry lever
+//     (v0.36, #59)
 //
 // Deliberately turf-free: it reads the JSON files with plain JSON.parse and
 // never imports @turf/@types/geojson (importing one pulls @types/geojson into
@@ -26,7 +29,7 @@
 // Loaded once at boot; the accessors below are pure data reads thereafter.
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
-import type { GameState } from '../shared/types';
+import type { GameState, RegionResources } from '../shared/types';
 
 /** { name, parent } for one sub-region, where parent is the ISO_A3 country. */
 interface RegionInfo {
@@ -49,6 +52,8 @@ interface RegionData {
   centroids: Record<string, { lat: number; lon: number; spread: number }>;
   /** region key -> { area (km²), population } (from public/region-geo.json, v0.28 #46). */
   geo: Record<string, { area: number; population: number }>;
+  /** region key -> resource profile (from public/region-resources.json, v0.36 #59). */
+  resources: Record<string, RegionResources>;
 }
 
 let data: RegionData | null = null;
@@ -77,6 +82,7 @@ export function loadRegions(root: string): boolean {
   const adjacencyFile = 'region-adjacency.json';
   const centroidsFile = 'region-centroids.json';
   const regionGeoFile = 'region-geo.json';
+  const regionResourcesFile = 'region-resources.json';
   const base = [
     path.join(root, 'public'), // dev: Vite serves public/ at /
     path.join(root, 'dist'), // prod: Vite copies public/* -> dist/ (== clientDir)
@@ -185,7 +191,40 @@ export function loadRegions(root: string): boolean {
       }
     }
 
-    data = { idToKey, keyToInfo, keysByCountry, validKeys, adjacency, centroids, geo };
+    // The region-resources manifest (v0.36, #59): a synthesized four-value
+    // resource profile per region key — the data behind the LLM's industry
+    // lever. OPTIONAL like the others: a missing/broken file means "no
+    // resource data" — industry boosts degrade to the unscaled base value and
+    // the prompt omits the aggregate profile — while everything else keeps
+    // working.
+    let resources: Record<string, RegionResources> = {};
+    const resourcesPath = path.join(base, regionResourcesFile);
+    if (existsSync(resourcesPath)) {
+      try {
+        const raw = JSON.parse(readFileSync(resourcesPath, 'utf8')) as Record<
+          string,
+          { oil?: unknown; iron?: unknown; food?: unknown; industry?: unknown }
+        >;
+        // Keep only well-formed entries (all four values finite numbers in
+        // [0, 1]); a corrupt file degrades to "none".
+        for (const [k, v] of Object.entries(raw)) {
+          if (
+            v &&
+            typeof v.oil === 'number' && Number.isFinite(v.oil) && v.oil >= 0 && v.oil <= 1 &&
+            typeof v.iron === 'number' && Number.isFinite(v.iron) && v.iron >= 0 && v.iron <= 1 &&
+            typeof v.food === 'number' && Number.isFinite(v.food) && v.food >= 0 && v.food <= 1 &&
+            typeof v.industry === 'number' && Number.isFinite(v.industry) && v.industry >= 0 && v.industry <= 1
+          ) {
+            resources[k] = { oil: v.oil, iron: v.iron, food: v.food, industry: v.industry };
+          }
+        }
+      } catch (err) {
+        console.error('[regions] failed to load region-resources.json, continuing without it', err);
+        resources = {};
+      }
+    }
+
+    data = { idToKey, keyToInfo, keysByCountry, validKeys, adjacency, centroids, geo, resources };
     return validKeys.size > 0;
   } catch (err) {
     console.error('[regions] failed to load region data', err);
@@ -322,6 +361,29 @@ export function geoOf(key: string): { area: number; population: number } | undef
   return data?.geo[key];
 }
 
+/**
+ * True when the region-resources manifest loaded with at least one entry
+ * (v0.36, #59). The server's jump route uses this to decide whether to hand
+ * the engine a resource resolver (which lets a turn scale industry boosts by a
+ * region's `industry` value and carry each nation's aggregate resource profile
+ * in the LLM prompt) or skip both (industry boosts fall back to the unscaled
+ * base value).
+ */
+export function hasResources(): boolean {
+  return data !== null && Object.keys(data.resources).length > 0;
+}
+
+/**
+ * The synthesized resource profile for a region key (v0.36, #59): the
+ * four-value `{ oil, iron, food, industry }` from the committed
+ * `public/region-resources.json`. `undefined` for an unknown key or when no
+ * resource data is loaded (industry boosts then use the unscaled base value,
+ * and the aggregate profile is simply omitted from the prompt).
+ */
+export function resourceOf(key: string): RegionResources | undefined {
+  return data?.resources[key];
+}
+
 /**
  * The union of the region keys that share a land border with any of the given
  * keys — deduplicated, the queried keys themselves excluded, and sorted for

server/stub.ts

@@ -3,7 +3,8 @@
 // speaks the OpenAI chat-completions wire shape, so it plugs in as a Transport.
 import { createLlmClient, type ChatMessage, type Transport } from './llm';
 import { addDays, clampStat, type TerritoryChange, type TurnEventSpec, type TurnResult } from '../shared/protocol';
-import type { RoundItem } from '../shared/types';
+import type { RelationStatus, RoundItem } from '../shared/types';
+import { ABILITIES, type AbilityField } from './abilities';
 
 export const ADVISOR_MARKER = '<<ADVISOR>>';
 
@@ -13,7 +14,25 @@ export interface StubPayload {
     turn: number;
     date: string;
     playerNationId: string;
-    nations: Record<string, { stats: Record<string, number>; territory?: string[] }>;
+    // `nuclear` (v0.37.0, #60) is the per-nation nuclear capability stamped by
+    // the engine (its `nuclear` flag OR a `rocket` marker); the stub ignores
+    // it — it never arms or strikes (see deterministicTurn).
+    // `leader` (v0.38.0, #61) is the per-nation named leader stamped by the
+    // engine; the stub ignores it — it never changes a leader (see
+    // deterministicTurn).
+    // `ideology` (v0.39.0, #62) is the per-nation form of government stamped
+    // by the engine; the stub ignores it — it never changes an ideology (see
+    // deterministicTurn).
+    nations: Record<
+      string,
+      {
+        stats: Record<string, number>;
+        territory?: string[];
+        nuclear?: boolean;
+        leader?: { name: string };
+        ideology?: string;
+      }
+    >;
   };
   /** The raw pending round the engine emitted (one entry per queued item). */
   pending?: RoundItem[];
@@ -38,6 +57,64 @@ export interface StubPayload {
    * path is covered by unit tests against applyTurnResult, not by the stub.
    */
   markers?: Array<{ id: string; type: string; name: string; regionKey: string; owner: string | null }>;
+  /**
+   * (v0.33.0, #56) Currently ACTIVE wars (`{ id, sides, aims? }`), emitted by
+   * the engine's user prompt. The stub ignores this field — it never declares
+   * or ends a war (see deterministicTurn), so the war path is covered by unit
+   * tests against applyTurnResult, not by the stub.
+   */
+  wars?: Array<{ id: string; sides: string[]; aims?: string[] }>;
+  /**
+   * (v0.34.0, #57) The player's current relations to every other nation
+   * (`nationId -> RelationStatus`), emitted by the engine's user prompt. The
+   * stub ignores this field — it never runs a hybrid op (see
+   * deterministicTurn), so the hybrid path is covered by unit tests only.
+   */
+  relations?: Record<string, RelationStatus>;
+  /**
+   * (v0.35.0, #58) The currently active bilateral trade agreements
+   * (`{ a, b }` nation-id pairs), emitted by the engine's user prompt. The
+   * stub ignores this field — it never declares, lifts or suspends a trade
+   * (see deterministicTurn), so the trade path is covered by unit tests only.
+   */
+  trades?: Array<{ a: string; b: string }>;
+  /**
+   * (v0.35.0, #58) The currently active unilateral embargoes
+   * (`{ from, target }` nation-id pairs), emitted by the engine's user
+   * prompt. The stub ignores this field — it never imposes, lifts or
+   * suspends an embargo (see deterministicTurn), so the embargo path is
+   * covered by unit tests only.
+   */
+  embargoes?: Array<{ from: string; target: string }>;
+  /**
+   * (v0.36.0, #59) Each nation's aggregate resource profile
+   * (`{ oil, iron, food, industry }`), emitted by the engine's user prompt.
+   * The stub ignores this field — it never declares an industry project (see
+   * deterministicTurn), so the industry path is covered by unit tests only.
+   */
+  resources?: Record<string, { oil: number; iron: number; food: number; industry: number }>;
+  /**
+   * (v0.36.0, #59) The currently active industry projects
+   * (`{ regionKey, type }`), emitted by the engine's user prompt. The stub
+   * ignores this field — it never declares an industry project (see
+   * deterministicTurn), so the industry path is covered by unit tests only.
+   */
+  industry?: Array<{ regionKey: string; type: string }>;
+  /**
+   * (v0.43.0, #65) The currently active sea-zone control
+   * (`{ zone, by }` — fixed sea-zone id + controlling nation id), emitted by
+   * the engine's user prompt (always, even when empty). The stub ignores this
+   * field — it never claims, contests or re-claims a sea zone (see
+   * deterministicTurn), so the sea path is covered by unit tests only.
+   */
+  seaZones?: Array<{ zone: string; by: string }>;
+  /**
+   * (v0.44.0, #66) The currently contested regions (war frontlines,
+   * `{ regionKey, parties }`), emitted by the engine's user prompt. The stub
+   * ignores this field — it never opens or resolves a contest (see
+   * deterministicTurn), so the contested path is covered by unit tests only.
+   */
+  contested?: Array<{ regionKey: string; parties: string[] }>;
 }
 
 function truncate(s: string, n: number): string {
@@ -81,6 +158,53 @@ function truncate(s: string, n: number): string {
  * (v0.32.0, #54) The stub likewise NEVER performs a non-military takeover
  * (it always returns `takeovers: []`) — the regime-rename path is covered by
  * unit tests only, keeping the e2e assertions untouched.
+ *
+ * (v0.33.0, #56) The stub likewise NEVER declares or ends a war (it always
+ * returns `wars: { declare: [], end: [] }`) — the war path is covered by unit
+ * tests only, keeping the e2e assertions untouched.
+ *
+ * (v0.34.0, #57) The stub likewise NEVER runs a hybrid / covert op (it always
+ * returns `hybrid: { ops: [] }`) — the hybrid-war path is covered by unit
+ * tests only, keeping the e2e assertions untouched.
+ *
+ * (v0.35.0, #58) The stub likewise NEVER declares, lifts or suspends a trade
+ * or an embargo (it always returns `economy: { trade: [], embargo: [] }`) —
+ * the trade & embargo economy path is covered by unit tests only, keeping
+ * the e2e assertions untouched.
+ *
+ * (v0.36.0, #59) The stub likewise NEVER declares an industry project (it
+ * always returns `industry: { projects: [] }`) — the per-region industry
+ * path is covered by unit tests only, keeping the e2e assertions untouched.
+ *
+ * (v0.37.0, #60) The stub likewise NEVER arms a nation or fires a nuclear
+ * strike (it always returns `nuclear: { arm: [], strikes: [] }`) — the
+ * nuclear / WMD path is covered by unit tests only, keeping the e2e
+ * assertions untouched.
+ *
+ * (v0.38.0, #61) The stub likewise NEVER changes a leader (it always returns
+ * `leaders: { changes: [] }`) — the leader path is covered by unit tests
+ * only, keeping the e2e assertions untouched.
+ *
+ * (v0.39.0, #62) The stub likewise NEVER changes a nation's ideology (it
+ * always returns `ideology: { changes: [] }`) — the ideology path is covered
+ * by unit tests only, keeping the e2e assertions untouched.
+ *
+ * (v0.41.0, #63) The stub likewise NEVER declares a disaster or pandemic (it
+ * always returns `disasters: { events: [] }`) — the disasters path is covered
+ * by unit tests only, keeping the e2e assertions untouched.
+ *
+ * (v0.42.0, #64) The stub likewise NEVER declares a migration / refugee flow
+ * (it always returns `migration: { ops: [] }`) — the migration path is
+ * covered by unit tests only, keeping the e2e assertions untouched.
+ *
+ * (v0.43.0, #65) The stub likewise NEVER claims, contests or re-claims a sea
+ * zone (it always returns `sea: { control: [] }`) — the sea-control path is
+ * covered by unit tests only, keeping the e2e assertions untouched.
+ *
+ * (v0.44.0, #66) The stub likewise NEVER opens or resolves a contested region
+ * (a war frontline) — it always returns `contested: { open: [], resolve: [] }`
+ * — the contested path is covered by unit tests only, keeping the e2e
+ * assertions untouched.
  */
 export function deterministicTurn(p: StubPayload): TurnResult {
   const state = p.state;
@@ -138,7 +262,18 @@ export function deterministicTurn(p: StubPayload): TurnResult {
               },
         );
 
-  return {
+  // Core (non-ability) turn fields, in their historical position order.
+  const pre: Pick<
+    TurnResult,
+    | 'date'
+    | 'events'
+    | 'stateChanges'
+    | 'regionChanges'
+    | 'relations'
+    | 'territoryChanges'
+    | 'unowned'
+    | 'nationOps'
+  > = {
     date: addDays(state?.date ?? '1939-09-01', 2),
     events,
     stateChanges: [{ nation: pid, stat: 'military', op: 'set', value: mil }],
@@ -147,9 +282,25 @@ export function deterministicTurn(p: StubPayload): TurnResult {
     territoryChanges,
     unowned: [], // the stub never creates no man's land (see doc comment)
     nationOps: [], // the stub never proposes nation ops (see doc comment)
-    takeovers: [], // the stub never performs a takeover (see doc comment)
+  };
+
+  // The 12 ability fields, filled by the registry in its canonical order. The
+  // stub is ability-inert: every ability contributes its own no-op default
+  // (each ability's `stub()` — see the per-ability doc comments above), so the
+  // e2e assertions are unaffected. The insertion order here (ABILITIES) is the
+  // historical key order pinned by the stub's deterministic output
+  // (takeovers → wars → hybrid → economy → industry → nuclear → leaders →
+  // ideology → disasters → migration → sea → contested), which must stay
+  // byte-identical.
+  const abilities = {} as Record<AbilityField, unknown>;
+  for (const a of ABILITIES) abilities[a.field] = a.stub();
+
+  // The single field positioned after the abilities (markers last, as before).
+  const post: Pick<TurnResult, 'markers'> = {
     markers: { add: [], remove: [] }, // the stub never touches markers (see doc comment)
   };
+
+  return { ...pre, ...abilities, ...post } as TurnResult;
 }
 
 const CANNED_ADVISOR: string[] = [

shared/protocol.ts

@@ -6,10 +6,13 @@ import type {
   EventOutcome,
   EventType,
   GameState,
+  IndustryProject,
+  MapMarker,
   MarkerType,
   Nation,
   NationStats,
   RelationStatus,
+  RegionResources,
   RegionStats,
   StatKey,
 } from './types';
@@ -51,6 +54,50 @@ export interface TerritoryChange {
   lose: string[];
 }
 
+// --- Wars (v0.33.0, #56): first-class war entities --------------------------
+//
+// A war is an explicit world entity (see types.War), not just a boolean
+// relation: the LLM DECLARES one (it becomes an active War with an engine-
+// assigned stable id) and later ENDS one by id. The engine derives the
+// symmetric `war` relation from the set of ACTIVE wars on every turn (two
+// nations are in a `war` relation iff they are both belligerents of at least
+// one active war) and downgrades it to `hostile` when the war ends — so the
+// relation can never drift apart from the war state.
+
+/**
+ * (v0.33.0, #56) Declare a new war this turn. `sides` names every
+ * belligerent (≥2 distinct nation ids — each resolved by `resolveNationRef`,
+ * so a unique name also works); any two distinct sides end the turn in a
+ * `war` relation. `aims` are optional short war aims for the narrative. The
+ * engine assigns the stable id, the declared turn/date, drags in the
+ * mutual-defense allies of each belligerent, and drops the op when fewer than
+ * two sides resolve (never throws).
+ */
+export interface WarDeclareOp {
+  /** The belligerent nations (≥2 distinct ids or unique names). */
+  sides: string[];
+  /** Optional short war aims (narrative only). */
+  aims?: string[];
+}
+
+/**
+ * (v0.33.0, #56) End an existing ACTIVE war this turn, by its stable id
+ * (the model sees the current active wars in the user payload's `wars`
+ * field). `outcome` is `armistice` (a negotiated stop) or `capitulation`
+ * (one side surrenders); the war keeps its id/sides and stays in
+ * `GameState.wars` as history with that final status. `terms` are optional
+ * short peace terms (narrative only — the model narrates the details in
+ * `events`). An unknown id, or a war that is already ended, is a no-op
+ * (never throws).
+ */
+export interface WarEndOp {
+  /** The stable id of the active war to end (from the user payload). */
+  id: string;
+  outcome: 'armistice' | 'capitulation';
+  /** Optional short peace terms (narrative only). */
+  terms?: string;
+}
+
 // --- Nation-management ops (v0.23 P4a / v0.24 P4b, #16: the hybrid "LLM
 // proposes, player confirms" model) ------------------------------------------
 //
@@ -189,6 +236,19 @@ export interface MarkerInfo {
   owner: string | null;
 }
 
+/**
+ * (v0.33.0, #56) One ACTIVE war as the user prompt presents it to the model
+ * (the `wars` field): its stable `id` (the model echoes it in
+ * `TurnResult.wars.end` to end it), its belligerent `sides`, and optional
+ * short `aims`. Ended wars are NOT included — they stay in `GameState.wars`
+ * as history, but the model only needs to address the active ones.
+ */
+export interface WarInfo {
+  id: string;
+  sides: string[];
+  aims?: string[];
+}
+
 /**
  * The per-type presentation of a marker: its display label (tooltip /
  * dossier), its color, and its glyph character (a symbol-layer text label —
@@ -248,6 +308,528 @@ export function isMarkerType(t: unknown): t is MarkerType {
   return typeof t === 'string' && (MARKER_TYPES as string[]).includes(t);
 }
 
+// --- Hybrid war (v0.34.0, #57): non-kinetic operations ---------------------
+//
+// The LLM can run covert, non-kinetic operations each turn: spies, sabotage,
+// assassination attempts, cyberattacks, economic pressure, disinformation, and
+// proxy support. Unlike kinetic conquest (territory), these never move borders
+// — they dip a target's stats or sour a relation. The LLM declares an intended
+// outcome (`success` or `exposed`); the engine is fully deterministic (no
+// hidden randomness) and acts only on that declaration: a successful op applies
+// its small, per-type effect, and an "exposed" op backfires (no effect, the
+// actor's relation with the target sours by one step, and an auto
+// diplomatic/failure event is emitted).
+
+/** The seven covert operation types a hybrid op can be (v0.34.0, #57). */
+export type HybridOpType =
+  | 'spy'
+  | 'sabotage'
+  | 'assassinate'
+  | 'cyber'
+  | 'economic'
+  | 'information'
+  | 'proxy';
+
+/** All hybrid op types, in canonical order (the LLM contract + validator). */
+export const HYBRID_OP_TYPES: HybridOpType[] = [
+  'spy',
+  'sabotage',
+  'assassinate',
+  'cyber',
+  'economic',
+  'information',
+  'proxy',
+];
+
+/**
+ * (v0.34.0, #57) One covert (non-kinetic) operation the LLM may run in a turn
+ * (`TurnResult.hybrid.ops`). `from` is the acting nation (its id or a unique
+ * name — resolved by the engine's `resolveNationRef`). `target` is EITHER a
+ * nation (id or unique name) or a specific region key; a region target hits
+ * that region's sole owner (a region with zero or 2+ owners can't be
+ * targeted). `detail` is a short narrative (the LLM may also narrate the op in
+ * `events`). `outcome` is the LLM's *intended* result: `success` (the default)
+ * applies the op's deterministic effect, while `exposed` backfires it — the
+ * effect is NOT applied, the actor's relation with the target sours by one
+ * step, and an auto diplomatic/failure event is emitted.
+ */
+export interface HybridOp {
+  /** The operation type (see {@link HybridOpType}). */
+  type: HybridOpType;
+  /** The acting nation's id or current name (resolved by `resolveNationRef`). */
+  from: string;
+  /** The target: a nation's id/name, or a region key (hits that region's owner). */
+  target: string;
+  /** Short narrative detail (optional). */
+  detail?: string;
+  /** The LLM's intended result; `exposed` backfires the op. Defaults to success. */
+  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[];
+}
+
+/**
+ * (v0.36, #59) The turn's INDUSTRY operations, nested under
+ * `TurnResult.industry`. `projects` lists the industry projects the LLM builds
+ * this turn: each names a **region key** (the region must be valid, and — for
+ * the boost to take effect — will need a sole owner at apply time) and one of
+ * the four project {@link IndustryType}s. The engine applies each project to
+ * `GameState.industry` (a per-region SET — a region already hosting a project
+ * keeps the first one declared; a region key not in the valid manifest is
+ * dropped, never thrown). Required; default `{ projects: [] }`.
+ */
+export interface IndustryOps {
+  /** The industry projects built this turn (region key + type). */
+  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[];
+}
+
+// --- Named leaders (v0.38, #61) -----------------------------------------------
+//
+// Each nation may have a single named leader (`Nation.leader`). The LLM changes
+// it each turn via `TurnResult.leaders`. A change names a target nation (id or
+// name) and the outcome: an `assassination` (a leader killed — a dramatic,
+// destabilizing blow), a `death` (a leader dies of natural causes — a quieter
+// succession), or an `appointed` leader (a neutral succession / new head of
+// state). The engine sets the nation's leader to the new name and applies a
+// DETERMINISTIC stability dip (see `LEADER_STABILITY_EFFECT` below) — no hidden
+// randomness. A change whose target has no current leader may only *appoint*
+// one (an assassination/death of a leaderless nation is dropped, not thrown).
+
+/** How a nation's leader changed this turn (v0.38, #61). */
+export type LeaderCause = 'assassination' | 'death' | 'appointed';
+
+/** A single leader change: the target nation, the new leader's name, the cause. */
+export interface LeaderChange {
+  /** The target nation, by id or name (resolved by the shared resolver). */
+  target: string;
+  /** The new leader's name (the incoming / successor head of state). */
+  name: string;
+  /** What happened to the leader this turn. */
+  cause: LeaderCause;
+}
+
+/** The leader-ops block of a `TurnResult`. Required; default `{ changes: [] }`. */
+export interface LeaderOps {
+  changes: LeaderChange[];
+}
+
+/**
+ * The deterministic stability effect of each leader-cause (v0.38, #61).
+ * Assassination is the most destabilizing, a natural death a minor wobble, an
+ * appointment is neutral. Applied to the target's `stability` (clamped 0–100),
+ * mirrored to its `regionStats`, and its derived stats re-derived afterwards.
+ */
+export const LEADER_STABILITY_EFFECT: Record<LeaderCause, number> = {
+  assassination: -15,
+  death: -3,
+  appointed: 0,
+};
+
+// --- Ideology / form of government (v0.39, #62) ------------------------------
+//
+// Each nation may carry a free-form `ideology` label — its form of
+// government ("democracy", "fascism", "military junta", …). The LLM changes it
+// each turn via `TurnResult.ideology`: a change names a target nation (id or
+// name) and the new government type. The engine sets the nation's `ideology`
+// and applies a DETERMINISTIC stability dip (see `IDEOLOGY_STABILITY_EFFECT`
+// below) — a regime shift always unsettles a nation — no hidden randomness.
+// It is a third, independent axis next to `leader` (who is in charge) and the
+// v0.32.0 takeover (which renames the nation): the id, name, territory,
+// relations, and the leader all stay valid, only the form of government and
+// stability move.
+
+/** A single ideology change: the target nation and its new form of government. */
+export interface IdeologyChange {
+  /** The target nation, by id or name (resolved by the shared resolver). */
+  target: string;
+  /** The new form of government (a free-form label, e.g. "democracy"). */
+  to: string;
+}
+
+/** The ideology-ops block of a `TurnResult`. Required; default `{ changes: [] }`. */
+export interface IdeologyOps {
+  changes: IdeologyChange[];
+}
+
+/**
+ * The deterministic stability effect of an ideology change (v0.39, #62). A
+ * regime shift (a coup, a revolution, a reform, a constitutional change)
+ * unsettles the nation: a small −5 dip applied to the target's `stability`
+ * (clamped 0–100), mirrored to its `regionStats`, and its derived stats
+ * re-derived afterwards. Applied the same way a leader-cause effect is —
+ * re-setting the SAME ideology still dips (the shift just happened, even if
+ * the label does not change) but is idempotent for the `ideology` field
+ * itself.
+ */
+export const IDEOLOGY_STABILITY_EFFECT: number = -5;
+
+// --- 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');
+}
+
+// --- Disasters & pandemics (v0.41.0, #63) ------------------------------------
+//
+// Natural and man-made catastrophes — earthquakes, floods, volcanic eruptions,
+// wildfires, famines, plagues, and epidemics — hit a nation or a single region
+// each turn. Each event carries a `type` and a `severity`; the engine applies
+// a DETERMINISTIC stat dip chosen from the `(type, severity)` lookup table
+// `DISASTER_EFFECTS` (defined in `server/abilities/disasters.ts`) — no hidden
+// randomness: the LLM chooses the type and severity, the table decides the
+// magnitude. The dip is clamped to 0–100, mirrored to the target's regions
+// (`regionStats`), and the target's derived `stats` re-derived afterwards
+// (the same 0-region / no-entry guards as the hybrid / economy layers). It is
+// **turn-transient** like the hybrid layer: there is NO `GameState` field, no
+// durable list, and no `db.ts` change — an ongoing plague / epidemic is simply
+// re-declared each turn it persists. Disasters never move territory (sole
+// ownership is untouched) and never touch `population`.
+
+/** The kind of catastrophe a disaster event describes (v0.41.0, #63). */
+export type DisasterType =
+  | 'earthquake'
+  | 'flood'
+  | 'volcanic'
+  | 'wildfire'
+  | 'famine'
+  | 'plague'
+  | 'epidemic';
+
+/** The severity a disaster event carries (v0.41.0, #63). */
+export type DisasterSeverity = 'minor' | 'moderate' | 'severe';
+
+/**
+ * A single disaster event (v0.41.0, #63): the catastrophe `type`, its
+ * `target` (a nation id / name, or a region key that hits that region's sole
+ * owner — resolved at apply time), the `severity`, and an optional short
+ * `detail`. The deterministic stat dip is looked up from
+ * `DISASTER_EFFECTS[type][severity]`.
+ */
+export interface DisasterEvent {
+  /** The kind of catastrophe (one of {@link DisasterType}). */
+  type: DisasterType;
+  /** The affected nation (by id or name) or a region key (hits its sole owner). */
+  target: string;
+  /** How bad it was (one of {@link DisasterSeverity}). */
+  severity: DisasterSeverity;
+  /** Optional short annotation (≤300 chars). */
+  detail?: string;
+}
+
+/** The disasters block of a `TurnResult`. Required; default `{ events: [] }`. */
+export interface DisastersOps {
+  events: DisasterEvent[];
+}
+
+// --- Migration & refugees (v0.42.0, #64) --------------------------------------
+//
+// People moving between nations each turn: ordinary migration, refugee flows
+// (fleeing a war or disaster), a spreading diaspora, and an exodus (people
+// leaving with no destination). Each op names a `kind`, a source `from` (the
+// nation people leave), a destination `to` (required for every kind except
+// `exodus`), and a `scale` (small / moderate / large). The engine applies a
+// DETERMINISTIC effect chosen from the per-`scale` tables
+// `MIGRATION_SOURCE_EFFECTS` / `MIGRATION_DESTINATION_EFFECTS` (defined in
+// `server/abilities/migration.ts`) — no hidden randomness: the LLM chooses the
+// kind and scale, the tables decide the magnitude. The source LOSES a small
+// amount of population and economy, the destination GAINS a small amount of
+// population and economy (a `large` influx additionally strains the
+// destination's stability), both clamped to 0–100, mirrored to each side's
+// regions (`regionStats`), and each side's derived `stats` re-derived
+// afterwards (the same 0-region / no-entry guards as the hybrid / economy /
+// disasters layers). The from↔to relation moves one step toward the positive
+// end of the ally/neutral/rival/hostile ladder (`shiftRelationTowardPositive`)
+// — capped at `ally` for `refugees`, `neutral` for `migration` / `diaspora`,
+// and not at all for `exodus` — and a `war` relation is never touched. It is
+// **turn-transient** like the hybrid / disasters layers: there is NO `GameState`
+// field, no durable list, and no `db.ts` change — a continuing flow is simply
+// re-declared each turn it persists. It never moves territory (sole ownership
+// is untouched) and never creates or escalates a war.
+
+/** The kind of population flow a migration op describes (v0.42.0, #64). */
+export type MigrationKind = 'migration' | 'refugees' | 'diaspora' | 'exodus';
+
+/** The size of a migration flow (v0.42.0, #64). */
+export type MigrationScale = 'small' | 'moderate' | 'large';
+
+/**
+ * A single migration / refugee flow (v0.42.0, #64): the `kind`, the source
+ * `from` (a nation id / name — the nation people leave), the destination `to`
+ * (a nation id / name — required for every kind except `exodus`, which has no
+ * destination), the `scale`, and an optional short `detail`. The deterministic
+ * stat effects are looked up from `MIGRATION_SOURCE_EFFECTS` /
+ * `MIGRATION_DESTINATION_EFFECTS` by `scale`.
+ */
+export interface MigrationOp {
+  /** The kind of flow (one of {@link MigrationKind}). */
+  kind: MigrationKind;
+  /** The source nation (by id or name) people leave. */
+  from: string;
+  /** The destination nation (by id or name). Required for every kind except `exodus`. */
+  to?: string;
+  /** How many people moved (one of {@link MigrationScale}). */
+  scale: MigrationScale;
+  /** Optional short annotation (≤300 chars). */
+  detail?: string;
+}
+
+/** The migration block of a `TurnResult`. Required; default `{ ops: [] }`. */
+export interface MigrationOps {
+  ops: MigrationOp[];
+}
+
+// ---------------------------------------------------------------------------
+// (v0.43.0, #65) Sea zones & sea control — the naval layer, fully parallel to
+// but INDEPENDENT of land. The world has a fixed set of 12 named SEA ZONES
+// ({@link SEA_ZONES}); each is under the SOLE CONTROL of at most one nation.
+// Controlling a sea zone never moves land (`territory` / `unowned` are
+// untouched) and moving land never touches a sea zone. `SeaZoneClaim` (the
+// durable per-zone record, `{ zone, by }`) lives in `shared/types.ts` like
+// `Trade` / `Embargo` / `War` / `IndustryProject`; `GameState.seaZones` is a
+// list of them, unique per zone (`[]` at creation; a legacy SQLite row
+// without the field loads as `[]` — additive, never wiped). Each turn the LLM
+// declares `TurnResult.sea.control` ops — one op names the zone and the
+// nation that (now) controls it. The engine resolves `by` (id first, then a
+// case-insensitive unique name) and UPSERTS the zone's claim (replace in
+// place if the zone is already claimed, append if new). If two or more ops
+// this turn claim the SAME zone for DIFFERENT resolved nations, the zone is
+// CONTESTED: the higher current `stats.military` wins (a tie goes to the op
+// listed earlier in the `control` array) — deterministic, no hidden
+// randomness; an unresolvable `by` is dropped (never thrown). Every committed
+// turn — including a turn with an empty `control` — each existing claim's
+// controller earns a small DETERMINISTIC bonus (`SEA_ZONE_BONUS = 1` military
+// + 1 economy, clamped to 0–100, mirrored to the controller's regions and
+// re-derived with the same 0-region / no-entry guards as the economy /
+// migration layers); a claim whose nation no longer exists is skipped (the
+// claim is kept, never thrown). The layer is DURABLE (unlike the turn-
+// transient hybrid / disasters / migration layers): `GameState.seaZones`
+// persists across turns and in SQLite. The user payload carries the current
+// `seaZones` list so the model knows who controls which zone.
+
+/** The 12 named sea zones the world model knows (v0.43.0, #65). */
+export const SEA_ZONES = [
+  { id: 'north-atlantic', name: 'North Atlantic' },
+  { id: 'south-atlantic', name: 'South Atlantic' },
+  { id: 'pacific', name: 'Pacific Ocean' },
+  { id: 'indian', name: 'Indian Ocean' },
+  { id: 'mediterranean', name: 'Mediterranean Sea' },
+  { id: 'north-sea', name: 'North Sea' },
+  { id: 'baltic', name: 'Baltic Sea' },
+  { id: 'arctic', name: 'Arctic Ocean' },
+  { id: 'black-sea', name: 'Black Sea' },
+  { id: 'gulf-mexico', name: 'Gulf of Mexico' },
+  { id: 'red-sea', name: 'Red Sea' },
+  { id: 'sargasso', name: 'Sargasso Sea' },
+] as const;
+
+/** The set of valid sea-zone ids (v0.43.0, #65). */
+export const SEA_ZONE_IDS: ReadonlySet<string> = new Set(SEA_ZONES.map((z) => z.id));
+
+/** Whether `id` is one of the fixed sea-zone ids (v0.43.0, #65). */
+export function isSeaZoneId(id: string): boolean {
+  return SEA_ZONE_IDS.has(id);
+}
+
+/** The display name of a sea-zone id; an unknown id is returned as-is (v0.43.0, #65). */
+export function seaZoneName(id: string): string {
+  return SEA_ZONES.find((z) => z.id === id)?.name ?? id;
+}
+
+/**
+ * A single sea-control op (v0.43.0, #65): `zone` is one of the fixed
+ * {@link SEA_ZONES} ids and `by` is the nation that (now) controls it (by id
+ * or name). One op SETS or REPLACES the zone's controller; two or more ops on
+ * the same zone for different nations are CONTESTED — the higher current
+ * `stats.military` wins (a tie: the earlier-listed op).
+ */
+export interface SeaControlOp {
+  /** The sea zone (one of {@link SEA_ZONE_IDS}). */
+  zone: string;
+  /** The controlling nation (by id or name). */
+  by: string;
+}
+
+/** The sea-control block of a `TurnResult`. Required; default `{ control: [] }`. */
+export interface SeaOps {
+  control: SeaControlOp[];
+}
+
+/**
+ * (v0.44.0, #66) A single `open` op: make a region **contested** — a war
+ * frontline that is in **no** nation's `territory` and not in `unowned` (a
+ * third region state, besides "owned by one nation" and "no man's land").
+ * `regionKey` is the region key (or a resolvable region name); `parties` are
+ * two or more nation refs (ids or names), resolved via the shared
+ * `resolveNationRef` — the stored `ContestedRegion.parties` are the resolved
+ * nation ids.
+ */
+export interface ContestOp {
+  /** The region key to make contested (the model names it by key or name). */
+  regionKey: string;
+  /**
+   * The nations contesting the region — two or more refs (ids or names). At
+   * least two distinct, resolvable nations are required, and the region's
+   * sole owner (if any) must be at war with one of them (or, for a
+   * no-man's-land region, two of the parties must be at war with each other).
+   */
+  parties: string[];
+}
+
+/**
+ * The contested-region block of a `TurnResult`. Required; default
+ * `{ open: [], resolve: [] }`. `open` makes a region a contested frontline
+ * (it leaves its owner's `territory` and `unowned` — sole ownership is
+ * preserved); `resolve` ends a contest, releasing the region to no man's
+ * land — unless a concurrent winning claim by one of the parties re-owns it
+ * (re-initialising its `regionStats`).
+ */
+export interface ContestedOps {
+  /** Regions to make contested this turn. */
+  open: ContestOp[];
+  /** Region keys to resolve (release to no man's land) this turn. */
+  resolve: string[];
+}
+
+/**
+ * A contested region — a region key that is a war frontline: in **no**
+ * nation's `territory` and not in `unowned`, contested by `parties` (resolved
+ * nation ids, two or more). Stored in `GameState.contested` (unique by
+ * `regionKey`).
+ */
+export interface ContestedRegion {
+  regionKey: string;
+  parties: string[];
+}
+
 /** The exact JSON object the world-simulator LLM must return for a turn. */
 export interface TurnResult {
   date: string;
@@ -297,6 +879,179 @@ export interface TurnResult {
    * (default `[]`).
    */
   takeovers: Takeover[];
+  /**
+   * (v0.33.0, #56) First-class war ops this turn. `declare` starts new wars
+   * (≥2 distinct belligerents; the engine assigns the stable id / declared
+   * turn / date, drags in the mutual-defense allies of each belligerent, and
+   * derives the `war` relation between every pair of sides); `end` closes an
+   * existing ACTIVE war by id (`armistice` = a negotiated stop,
+   * `capitulation` = one side surrenders), which downgrades the relation the
+   * war had derived back to `hostile`. Both sub-fields are required and
+   * default `[]`; a turn with war activity is meaningful (it survives the
+   * retry/nudge path). The model sees the current active wars (id + sides +
+   * aims) in the user payload's `wars` field, so it can `end` by id.
+   */
+  wars: { declare: WarDeclareOp[]; end: WarEndOp[] };
+  /**
+   * (v0.34.0, #57) Covert, non-kinetic ("hybrid") operations this turn — spies,
+   * sabotage, assassination attempts, cyberattacks, economic pressure,
+   * disinformation, and proxy support. Unlike `nationOps` (player-confirmed
+   * proposals) these are applied directly by the turn, like territory / state
+   * changes: each op's deterministic per-type effect is applied by
+   * `applyTurnResult` (a small stat dip on the target's regions, or a
+   * relation nudge toward hostile for `information` / `proxy`); an `exposed`
+   * op backfires (no effect, the actor's relation with the target sours by
+   * one step, and an auto diplomatic/failure event is emitted). They never
+   * move borders — sole ownership is untouched. Required (default
+   * `{ 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.36, #59) Industry projects built this turn — the LLM's "industry"
+   * lever. `projects` lists `{ regionKey, type }` pairs: the model names a
+   * region it (believes it) controls and one of the four project types
+   * (`oil` / `iron` / `food` / `industry`). Applied directly by
+   * `applyTurnResult`: each project is added to `GameState.industry` (a
+   * per-region SET — re-declaring on a region that already has a project is a
+   * no-op), and on every committed turn each active project gives its region's
+   * SOLE owner a small, deterministic economy boost scaled by that region's
+   * `industry` resource value (a region with no owner, or 2+ owners, yields no
+   * boost but keeps its project). They never move borders — sole ownership is
+   * 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.38, #61) Leader changes this turn. Each change names a target nation
+   * (id or name) and sets its leader to the new name, applying a deterministic
+   * stability effect by cause: `assassination` (leader killed — a dramatic
+   * −15 to the target's stability, a `military` event), `death` (natural
+   * causes — a quieter −3 succession, a `political` event), or `appointed`
+   * (a neutral 0 succession, a `political` event). An assassination/death
+   * requires the target to already have a leader (a leaderless target is
+   * dropped, never thrown); an appointment is always valid (it creates the
+   * first leader). At most 1–2 per turn, each narrated in `events`. This is
+   * the *leader* lever — heavier and more destabilizing than the lighter
+   * `hybrid.assassinate` op (a −5 stability dip on a nation or region, with
+   * no leader replacement). Required; default `{ changes: [] }`.
+   */
+  leaders: LeaderOps;
+  /**
+   * (v0.39, #62) Ideology (form of government) changes this turn. Each
+   * change names a target nation (id or name) and its new form of
+   * government — a free-form label such as "democracy", "fascism", or
+   * "military junta". Applied directly by `applyTurnResult` (like leaders /
+   * hybrid / economy): the target's `ideology` is set to the new label, a
+   * small, deterministic stability dip (`IDEOLOGY_STABILITY_EFFECT`, −5) is
+   * applied (clamped, mirrored to the nation's regions, re-derived), and a
+   * `political` narration event is appended. Re-setting the same label is
+   * idempotent for the field (still narrated, still dips). Unknown /
+   * ambiguous targets and empty labels are dropped, never thrown; the
+   * change never moves territory (sole ownership is untouched). Distinct
+   * from a takeover (which renames the nation) and from a leader change
+   * (who is in charge). At most 1–2 per turn, each narrated in `events`.
+   * Required; default `{ changes: [] }`.
+   */
+  ideology: IdeologyOps;
+  /**
+   * (v0.41.0, #63) Disasters & pandemics that struck this turn — earthquakes,
+   * floods, volcanic eruptions, wildfires, famines, plagues, and epidemics,
+   * each hitting a **nation** (by id or name) or a single **region** (by key,
+   * which hits that region's SOLE owner — a key with 0 or 2+ owners can't be
+   * hit). Each event names a `type` (one of the seven `DisasterType`s) and a
+   * `severity` (minor / moderate / severe); the engine applies a small,
+   * DETERMINISTIC stat dip from the `(type, severity)` table
+   * (`DISASTER_EFFECTS`, in `server/abilities/disasters.ts`) — clamped to
+   * 0–100, mirrored to the target's regions, and the target's derived `stats`
+   * re-derived afterwards (no hidden randomness). They NEVER move borders
+   * (sole ownership is untouched) and never touch `population`, and the layer
+   * is turn-transient (no durable state): an ongoing plague / epidemic is
+   * simply re-declared each turn it persists. At most 1–2 events per turn,
+   * each narrated in `events` (a `disaster` event). Required; default
+   * `{ events: [] }`.
+   */
+  disasters: DisastersOps;
+  /**
+   * (v0.42.0, #64) Migration & refugee flows this turn — people moving between
+   * nations: ordinary `migration`, `refugees` fleeing a war or disaster, a
+   * spreading `diaspora`, and an `exodus` (people leaving with no destination).
+   * Each op names a `from` (the source nation, by id or name) and, for every
+   * kind except `exodus`, a `to` (the destination nation, by id or name), plus
+   * a `scale` (small / moderate / large). Applied directly by `applyTurnResult`
+   * (like the disasters / hybrid layers): the source LOSES a small amount of
+   * population and economy, the destination GAINS a small amount of population
+   * and economy (a `large` influx additionally strains the destination's
+   * stability by 2), both clamped to 0–100, mirrored to each side's regions,
+   * and each side's derived `stats` re-derived afterwards; the from↔to
+   * relation moves one step toward the positive end of the
+   * ally/neutral/rival/hostile ladder (capped at `ally` for `refugees`,
+   * `neutral` for `migration` / `diaspora`, not at all for `exodus`; a `war`
+   * relation is never touched). The layer is turn-transient (no `GameState`
+   * field, no `db.ts` change) — a continuing flow is simply re-declared each
+   * turn it persists. It never moves borders (sole ownership is untouched) and
+   * never creates or escalates a war. At most 1–2 per turn, each narrated in
+   * `events` (a `social` or `diplomatic` event). Required; default
+   * `{ ops: [] }`.
+   */
+  migration: MigrationOps;
+  /**
+   * (v0.43.0, #65) Sea-zone control ops this turn — the naval layer, fully
+   * parallel to but INDEPENDENT of land: each op names one of the 12 fixed
+   * sea zones (`SEA_ZONES`) and the nation that now controls it. The engine
+   * resolves `by` (id first, then a case-insensitive unique name) and
+   * upserts the zone's claim in `GameState.seaZones` (a single op sets or
+   * replaces the controller; two or more ops on the same zone for different
+   * nations are CONTESTED — the higher current `stats.military` wins, a tie
+   * goes to the op listed earlier in `control`; an unresolvable `by` is
+   * dropped, never thrown). Every committed turn, each existing claim's
+   * controller earns a small deterministic military/economy bonus
+   * (`SEA_ZONE_BONUS`). Sea control never moves land: `territory` and
+   * `unowned` are untouched. At most 1–2 per turn, each narrated in `events`
+   * (a `military` or `diplomatic` event). Required; default
+   * `{ control: [] }`.
+   */
+  sea: SeaOps;
+  /**
+   * (v0.44.0, #66) Contested regions / frontlines: `open` makes a region a
+   * contested war frontline (it leaves its owner's `territory` and `unowned`
+   * — a third region state in no territory and not no man's land — and is
+   * contested by two or more nations at war); `resolve` ends a contest,
+   * releasing the region to no man's land unless a concurrent winning claim
+   * by one of the parties re-owns it. A region with a sole owner not at war
+   * with any party, or two or more owners, cannot be contested. Sole
+   * ownership is never broken; a still-contested key is not a valid normal
+   * claim target. At most 1–2 per turn, each narrated in `events`. Required;
+   * default `{ open: [], resolve: [] }`.
+   */
+  contested: ContestedOps;
   /**
    * (v0.27, #44) Map-marker ops this turn. `add` places new named markers
    * (the engine positions each at its region's centroid + a small
@@ -538,6 +1293,27 @@ export const UNOWNED_STROKE = 'rgba(255,255,255,0.14)';
 /** The border of an owned region (brighter than unowned). */
 export const OWNED_STROKE = 'rgba(255,255,255,0.30)';
 
+/**
+ * The distinct, visible fill + stroke for a **contested** region (a war
+ * frontline — a key that is in no nation's `territory` and not in `unowned`).
+ * Reddish/orange to read as a "hot" frontline on the dark basemap — clearly
+ * distinct from a nation color and from the no-man's-land grey. The contested
+ * state is decided by the client (via `GameState.contested`), never by the
+ * `RegionMap` (which only knows owned vs absent).
+ */
+export const CONTESTED_FILL = '#f97316';
+export const CONTESTED_STROKE = 'rgba(255,237,213,0.55)';
+
+/**
+ * The hover-tooltip sub-line for a contested region: a short "Contested:
+ * A vs B" line naming the contesting parties. A missing party name (a nation
+ * removed by a merge/split) degrades to a dash, never crashes.
+ */
+export function contestedTooltipLabel(parties: string[]): string {
+  const names = parties.map((p) => p || '—');
+  return `Contested: ${names.join(' vs ')}`;
+}
+
 /** The hover-tooltip sub-line for a region with no owning nation. */
 export function unownedTooltipLabel(isNoMansLand: boolean): string {
   return isNoMansLand ? "No man's land" : 'No owner';
@@ -609,6 +1385,8 @@ export function nationForPrompt(n: Nation) {
     stats: n.stats,
     territory: n.territory,
     relations: n.relations,
+    leader: n.leader,
+    ideology: n.ideology,
   };
 }
 
@@ -745,3 +1523,49 @@ export function migrateRegionStats(
   }
   return next;
 }
+
+/**
+ * (v0.36, #59) Derive a nation's aggregate {@link RegionResources} from the
+ * resource profiles of the regions it owns: each of the four resource values is
+ * the **area×population-weighted AVERAGE** (an average — not a median — is the
+ * meaningful aggregation for an abundance profile) over the nation's owned
+ * region keys. A region's weight is the same
+ * `(area > 0 ? area : 1) × (population > 0 ? population : 1)` as
+ * {@link deriveNationStats} — both factors fall back to 1 when the region has
+ * no geo entry (`geoOf` returns `undefined` for it), so every region carries
+ * weight ≥ 1 and a missing geo degrades gracefully to a uniform (unweighted)
+ * average. A region key with no resource-profile entry (`resourceOf` returns
+ * `undefined` for it — the manifest is not loaded, or the key is absent) is
+ * skipped. Returns the zero profile when the nation owns no region with a
+ * profile. Pure + shared.
+ */
+export function deriveNationResources(
+  regionKeys: string[],
+  resourceOf?: (key: string) => RegionResources | undefined,
+  geoOf?: (key: string) => { area: number; population: number } | undefined,
+): RegionResources {
+  const zero: RegionResources = { oil: 0, iron: 0, food: 0, industry: 0 };
+  const sums: Record<keyof RegionResources, number> = { oil: 0, iron: 0, food: 0, industry: 0 };
+  let totalW = 0;
+  for (const key of regionKeys) {
+    const r = resourceOf?.(key);
+    if (!r) continue; // a key with no resource profile is skipped
+    const g = geoOf?.(key);
+    const a = g && g.area > 0 ? g.area : 1;
+    const p = g && g.population > 0 ? g.population : 1;
+    const w = a * p;
+    totalW += w;
+    sums.oil += r.oil * w;
+    sums.iron += r.iron * w;
+    sums.food += r.food * w;
+    sums.industry += r.industry * w;
+  }
+  if (totalW <= 0) return zero;
+  const round2 = (v: number) => Math.round(v * 100) / 100;
+  return {
+    oil: round2(sums.oil / totalW),
+    iron: round2(sums.iron / totalW),
+    food: round2(sums.food / totalW),
+    industry: round2(sums.industry / totalW),
+  };
+}

shared/scenario.ts

@@ -453,6 +453,18 @@ export function worldDraftToGameState(
     // Seed AFTER the territories hold real region keys: each owned region gets
     // a copy of its owner's stats, so the derived aggregate equals them.
     regionStats: seedRegionStats(nations),
+    // (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: [],
+    // (v0.36, #59) No industry projects on a fresh (dynamic) game.
+    industry: [],
+    // (v0.43.0, #65) no sea-zone control on a fresh state.
+    seaZones: [],
+    // (v0.44.0, #66) no contested regions on a fresh state.
+    contested: [],
   };
   return state;
 }

shared/types.ts

@@ -3,7 +3,7 @@
 // (The single `import type` below erases at compile time, so no runtime
 // dependency on protocol.ts is introduced — see the GameState.pendingNationOps
 // doc comment.)
-import type { NationOp } from './protocol';
+import type { NationOp, ContestedRegion } from './protocol';
 
 /** A nation's 0–100 status indices. Every value is clamped to 0–100 by the engine. */
 export interface NationStats {
@@ -26,6 +26,23 @@ export interface RegionStats {
   population: number;
 }
 
+/**
+ * (v0.36, #59) A region's synthesized four-value resource profile — each value
+ * a finite fraction in [0, 1]. Built once per region key by
+ * `scripts/build-region-resources.mjs` into the committed
+ * `public/region-resources.json` (the engine reads it via `regions.resourceOf`).
+ * The engine scales a region's per-turn industry boost by its `industry` value,
+ * and a nation's aggregate profile (the area×population-weighted mean of its
+ * owned regions' profiles, see `protocol.deriveNationResources`) is what the
+ * LLM prompt carries so the model can reason about where to build.
+ */
+export interface RegionResources {
+  oil: number;
+  iron: number;
+  food: number;
+  industry: number;
+}
+
 export const STAT_KEYS = ['military', 'economy', 'stability', 'population'] as const;
 export type StatKey = (typeof STAT_KEYS)[number];
 
@@ -55,6 +72,34 @@ 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;
+  /**
+   * The nation's current named leader (v0.38, #61). Optional — a legacy game
+   * (or a nation the LLM has never given a leader to) has none, which is the
+   * "no leader" baseline. The LLM changes it via `TurnResult.leaders`
+   * (assassination / death / appointment, see `LeaderChange` in `protocol.ts`);
+   * each change carries a deterministic stability effect + a narration event.
+   */
+  leader?: { name: string };
+  /**
+   * The nation's current form of government (v0.39, #62) — a free-form label
+   * such as `"democracy"`, `"fascism"` or `"military junta"`. Optional — a
+   * legacy game (or a nation the LLM has never given an ideology to) has none,
+   * which is the "no recorded government" baseline. The LLM changes it via
+   * `TurnResult.ideology` (coups / revolutions / reforms / constitutional
+   * changes, see `IdeologyChange` in `protocol.ts`); each change carries a
+   * deterministic stability dip + a political narration event. Distinct from
+   * the v0.32.0 takeover (which renames the nation) and from `leader` (who is
+   * in charge): only the form of government and stability move.
+   */
+  ideology?: string;
 }
 
 /** Categories a narrative event can take. */
@@ -143,6 +188,122 @@ 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;
+}
+
+// --- Resources & industry (v0.36, #59) ---------------------------------------
+//
+// The LLM can build per-region INDUSTRY PROJECTS (an oil facility, an iron
+// mine, a food operation, or a factory) on regions it controls; each active
+// project gives that region's sole owner a small, deterministic economy boost
+// every committed turn, scaled by the region's `industry` resource value from
+// the committed resource manifest. The active projects live in
+// `GameState.industry` — the LLM's "industry" lever.
+
+/** The four industry project types a region can host (v0.36, #59). */
+export type IndustryType = 'oil' | 'iron' | 'food' | 'industry';
+
+/** All industry project types, in canonical order (the LLM contract + validator). */
+export const INDUSTRY_TYPES: IndustryType[] = ['oil', 'iron', 'food', 'industry'];
+
+/**
+ * (v0.36, #59) One active industry project: a building of a given
+ * {@link IndustryType} in a specific region. The engine keys the per-turn
+ * economy boost by the region's SOLE owner (a region with no owner or 2+
+ * owners yields no boost) and scales it by the region's `industry` resource
+ * value. A region hosts at most ONE project — re-declaring on a region that
+ * already has one is a no-op (the first declared type wins).
+ */
+export interface IndustryProject {
+  /** The region key the project sits in (see `public/region-keys.json`). */
+  regionKey: string;
+  /** The kind of project built there (see {@link IndustryType}). */
+  type: IndustryType;
+}
+
+/**
+ * (v0.43.0, #65) One sea-zone claim: which nation controls one of the fixed
+ * sea zones (see `SEA_ZONES` in `shared/protocol.ts`). The world keeps at
+ * most ONE claim per zone — a new op on an already-claimed zone REPLACES the
+ * controller in place (the zone's entry is updated, never duplicated), and if
+ * a turn declares the same zone for two different resolved nations the higher
+ * current `stats.military` wins (a tie: the op listed earlier in the turn's
+ * `control` array). Sea control is fully parallel to but INDEPENDENT of land:
+ * it never touches `territory` / `unowned`.
+ */
+export interface SeaZoneClaim {
+  /** The sea zone (one of `SEA_ZONE_IDS`). */
+  zone: string;
+  /** The id of the nation that controls it (resolved, not a name). */
+  by: 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
+ * preset or a bare `relations` entry can carry without any structure behind
+ * it), a `War` is an explicit world entity the engine tracks: the LLM
+ * declares it (a turn's `wars.declare`), the engine assigns it a stable id
+ * (`w1`, `w2`, …), the turn and in-game date it was declared, and it stays in
+ * `GameState.wars` for the rest of the game as history after it ends.
+ *
+ * **Semantics of `sides`:** the flat list of every belligerent in the war
+ * (≥2 distinct nation ids). Any two distinct members of an active war's
+ * sides are at war with each other — the engine derives the symmetric `war`
+ * relation for every such pair on every turn (see the engine's
+ * `syncWarRelations`), and downgrades the relation to `hostile` when the war
+ * ends. A mutual-defense ally of a belligerent is dragged into the same list
+ * on declaration (the engine does this automatically).
+ */
+export interface War {
+  /** Stable id (`w1`, `w2`, …) assigned by the engine on declaration. */
+  id: string;
+  /** The belligerent nations (≥2 distinct ids; see the note above). */
+  sides: string[];
+  /** The turn number the war was declared on. */
+  declaredTurn: number;
+  /** The in-game date the war took effect on (`YYYY-MM-DD`). */
+  declaredDate?: string;
+  /** Optional short war aims the LLM names at declaration. */
+  aims?: string[];
+  /**
+   * Lifecycle: `active` until a turn ends the war, then the end outcome —
+   * `armistice` (a negotiated stop) or `capitulation` (one side surrenders) —
+   * or the generic `ended`. Ended wars stay in `GameState.wars` as history.
+   */
+  status: 'active' | 'armistice' | 'capitulation' | 'ended';
+  /** Optional region keys the war's front line runs through (reserved). */
+  front?: string[];
+}
+
 /** A narrative event the simulation emitted on some turn. */
 export interface EventEntry {
   id: string;
@@ -251,6 +412,80 @@ export interface GameState {
    * — additive, no data wipe.
    */
   regionStats: Record<string, RegionStats>;
+  /**
+   * (v0.33.0, #56) First-class war entities (see {@link War}): declared by a
+   * turn's `wars.declare` (the engine assigns the id, declared turn/date, and
+   * drags in mutual-defense allies) and closed by `wars.end` (armistice /
+   * capitulation). The engine DERIVES the `war` relation from the ACTIVE
+   * wars on every turn (two nations are in a `war` relation iff they are both
+   * belligerents of ≥1 active war), so the boolean relation and the war
+   * entities can never drift apart. A bare preset `war` relation with no
+   * active war behind it stays as-is (an implicit, unnamed war — never
+   * force-created into an entity). Always `[]` on a fresh game; rows saved
+   * before v0.33 load with this defaulted to `[]` (see server/db.ts) —
+   * 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[];
+  /**
+   * (v0.36, #59) Active industry projects (see {@link IndustryProject}): built
+   * by a turn's `industry.projects` ops (the LLM names a region key + a
+   * project type). Each region hosts at most one project — re-declaring on a
+   * region that already has one is a no-op. Every committed turn the engine
+   * gives each project's region's SOLE owner a small, deterministic economy
+   * boost scaled by that region's `industry` resource value. A project on a
+   * region that ends a turn with no owner (or 2+ owners) yields no boost but
+   * is NOT removed. Always `[]` on a fresh game; rows saved before v0.36 load
+   * with this defaulted to `[]` (see server/db.ts) — additive, no data wipe.
+   */
+  industry: IndustryProject[];
+  /**
+   * (v0.43.0, #65) Sea-zone control (see {@link SeaZoneClaim}): one entry per
+   * controlled sea zone — which of the 12 fixed zones (`SEA_ZONES`) each
+   * nation controls. At most ONE entry per zone (unique by `zone`); a turn's
+   * `sea.control` ops upsert entries (a re-claim by a different nation
+   * replaces the controller in place; a same-zone contest goes to the higher
+   * current `stats.military`, a tie to the earlier-listed op). Every
+   * committed turn each claim's controller earns a small deterministic
+   * military/economy bonus (`SEA_ZONE_BONUS`). Sea control never moves land
+   * (`territory` / `unowned` are untouched). Always `[]` on a fresh game;
+   * rows saved before v0.43 load with this defaulted to `[]` (see
+   * server/db.ts) — additive, no data wipe.
+   */
+  seaZones: SeaZoneClaim[];
+  /**
+   * (v0.44.0, #66) Contested regions / frontlines (see {@link ContestedRegion}):
+   * one entry per region key that is a war frontline — a key in **no** nation's
+   * `territory` and not in `unowned`, contested by two or more nations at war.
+   * A region becomes contested when a turn's `contested.open` succeeds (it
+   * leaves its owner's `territory` and `unowned` — sole ownership is preserved);
+   * it is resolved (released to no man's land, or re-claimed by a party) by a
+   * later `contested.resolve`. At most ONE entry per region key (unique by
+   * `regionKey`). Always `[]` on a fresh game; rows saved before v0.44 load
+   * with this defaulted to `[]` (see server/db.ts) — additive, no data wipe.
+   */
+  contested: ContestedRegion[];
 }
 
 /**

src/App.tsx

@@ -834,6 +834,7 @@ function GameScreen({
         unowned={game.unowned ?? []}
         markers={game.markers ?? []}
         regionStats={game.regionStats ?? {}}
+        contested={game.contested ?? []}
         onFocusNation={focusNation}
       />
 

src/components/WorldMap.tsx

@@ -9,11 +9,15 @@ import 'maplibre-gl/dist/maplibre-gl.css';
 import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?url';
 maplibregl.setWorkerUrl(workerUrl);
 import {
+  CONTESTED_FILL,
+  CONTESTED_STROKE,
+  contestedTooltipLabel,
   mapFeatureOwner,
   MARKER_TYPE_INFO,
   nationColor,
   regionFillStyle,
   unownedTooltipLabel,
+  type ContestedRegion,
   type RegionMap,
   type RegionOwner,
 } from '@shared/protocol';
@@ -146,6 +150,12 @@ function cameraForPreset(presetId: string): { center: [number, number]; zoom: nu
  * no man's land mid-game (`GameState.unowned`) — gets the distinct visible grey
  * (`NO_MANS_LAND_FILL`); every other ownerless region keeps the faint
  * preset-unassigned look. Both come from the shared `regionFillStyle` contract.
+ *
+ * (v0.44.0, #66) A **contested** region (a war frontline — `contestedSet`, from
+ * `GameState.contested`) takes precedence over both unowned looks: it is in no
+ * nation's territory and not no man's land, so it renders the distinct
+ * reddish/orange `CONTESTED_FILL` / `CONTESTED_STROKE`. The state is decided by
+ * the client, never by the RegionMap (which has no entry for a contested key).
  */
 function applyRegions(
   geo: FeatureCollection,
@@ -153,6 +163,7 @@ function applyRegions(
   playerNationId: string,
   idKey: Record<string, string>,
   unownedSet: ReadonlySet<string>,
+  contestedSet: ReadonlySet<string>,
 ): FeatureCollection {
   const out: FeatureCollection = JSON.parse(JSON.stringify(geo));
   for (const f of out.features) {
@@ -165,6 +176,18 @@ function applyRegions(
     // key the RegionMap by it — never the sub-region id or the repacked id.
     const key = idKey[subId] ?? '';
     f.properties.regionKey = key;
+    // (v0.44.0, #66) A contested frontline takes precedence over every other
+    // state (owned, unowned, no man's land): the key is in no nation's
+    // territory and not no man's land, so it renders the distinct contested
+    // fill/stroke (decided by the client from `GameState.contested`, never by
+    // the RegionMap, which has no entry for it).
+    if (key !== '' && contestedSet.has(key)) {
+      f.properties.fill = CONTESTED_FILL;
+      f.properties.stroke = CONTESTED_STROKE;
+      f.properties.owner = '';
+      f.properties.ownerId = '';
+      f.properties.isPlayer = 0;
+    } else {
       const r = key ? regions[key] : undefined;
       if (r) {
         const style = regionFillStyle(r, false);
@@ -184,6 +207,7 @@ function applyRegions(
         f.properties.isPlayer = 0;
       }
     }
+  }
   return out;
 }
 
@@ -412,8 +436,14 @@ function hoverHtml(
   noMansLand = false,
   regionKey?: string,
   regionStats?: Record<string, RegionStats>,
+  contestedParties?: string[],
 ): string {
   if (!region || !nation) {
+    // (v0.44.0, #66) A contested frontline (a region in no nation's territory
+    // and not no man's land) names its contesting parties in the sub-line.
+    if (contestedParties && contestedParties.length > 0) {
+      return `<div class="hm-popup"><div class="hm-popup-title">${esc(subRegionName || 'Contested')}</div><div class="hm-popup-sub">${contestedTooltipLabel(contestedParties)}</div></div>`;
+    }
     return `<div class="hm-popup"><div class="hm-popup-title">${esc(subRegionName || 'Unclaimed')}</div><div class="hm-popup-sub">${unownedTooltipLabel(noMansLand)}</div></div>`;
   }
   // (v0.29, #46 PR 2) The region's OWN per-region stats (not the nation's
@@ -479,6 +509,15 @@ interface Props {
    * stats.
    */
   regionStats?: Record<string, RegionStats>;
+  /**
+   * (v0.44.0, #66) The game's contested regions / war frontlines
+   * (`GameState.contested` — a region key + its contesting party ids). Such a
+   * region is in no nation's territory and not no man's land (a third region
+   * state): it renders the distinct reddish/orange `CONTESTED_FILL` and its
+   * hover tooltip names the parties. The map legend is unaffected (a
+   * contested key is absent from the RegionMap, so it adds no entry).
+   */
+  contested?: ContestedRegion[];
 }
 
 /**
@@ -536,6 +575,7 @@ export default function WorldMap({
   onFocusNation,
   markers,
   regionStats,
+  contested,
 }: Props) {
   const containerRef = useRef<HTMLDivElement>(null);
   const mapRef = useRef<maplibregl.Map | null>(null);
@@ -553,6 +593,10 @@ export default function WorldMap({
   const markersRef = useRef<MapMarker[]>(markers ?? []);
   // (v0.29, #46 PR 2) latest per-region stats, for the hover tooltip.
   const regionStatsRef = useRef<Record<string, RegionStats>>(regionStats ?? {});
+  // (v0.44.0, #66) latest contested regions, region key -> contesting party
+  // NAMES (the stored parties are resolved nation ids, resolved here so the
+  // hover tooltip can show "Contested: A vs B").
+  const contestedRef = useRef<Map<string, string[]>>(new Map());
   regionsRef.current = regions;
   nationsRef.current = nations;
   playerRef.current = playerNationId;
@@ -561,6 +605,11 @@ export default function WorldMap({
   onFocusNationRef.current = onFocusNation;
   markersRef.current = markers ?? [];
   regionStatsRef.current = regionStats ?? {};
+  {
+    const m = new Map<string, string[]>();
+    for (const c of contested ?? []) m.set(c.regionKey, c.parties.map((id) => nations[id]?.name ?? id));
+    contestedRef.current = m;
+  }
 
   // Diffing state for the transient territory-change flash (owned by this component
   // so a resync with identical data never re-flashes).
@@ -721,9 +770,12 @@ export default function WorldMap({
       const pKey = f.properties?.regionKey;
       const keyStr = typeof pKey === 'string' && pKey !== '' ? pKey : undefined;
       const noMansLand = !region && keyStr !== undefined && unownedRef.current.has(keyStr);
+      // (v0.44.0, #66) a contested frontline (in no territory, not no man's
+      // land) names its contesting parties in the tooltip sub-line.
+      const contestedParties = !region && keyStr !== undefined ? contestedRef.current.get(keyStr) : undefined;
       hoverPopup
         .setLngLat(e.lngLat)
-        .setHTML(hoverHtml(p?.name ?? subId, region, nation, noMansLand, keyStr, regionStatsRef.current))
+        .setHTML(hoverHtml(p?.name ?? subId, region, nation, noMansLand, keyStr, regionStatsRef.current, contestedParties))
         .addTo(map);
       map.getCanvas().style.cursor = 'pointer';
     };
@@ -799,7 +851,7 @@ export default function WorldMap({
       const idKey = idKeyRef.current;
       const src = map.getSource(REGIONS_SOURCE) as GeoSource | undefined;
       if (!geo || !idKey || !src) return;
-      src.setData(applyRegions(geo, regionsRef.current, playerRef.current, idKey, unownedRef.current));
+      src.setData(applyRegions(geo, regionsRef.current, playerRef.current, idKey, unownedRef.current, new Set(contestedRef.current.keys())));
     };
 
     // Stamp the current markers onto the marker source (v0.27, #44).
@@ -977,7 +1029,7 @@ export default function WorldMap({
 
     if (map && geo && idKey) {
       const src = map.getSource(REGIONS_SOURCE) as GeoSource | undefined;
-      if (src) void src.setData(applyRegions(geo, cur, playerNationId, idKey, unownedSet));
+      if (src) void src.setData(applyRegions(geo, cur, playerNationId, idKey, unownedSet, new Set(contestedRef.current.keys())));
     }
 
     if (wasPrimed && prev && idKey) {
@@ -989,7 +1041,9 @@ export default function WorldMap({
       // up as ownerId changes above, so they flash like any other transfer.
       if (changed.size > 0) flashApiRef.current?.([...changed]);
     }
-  }, [regions, playerNationId, unowned]);
+    // (v0.44.0, #66) re-paint when the contested set changes too — a contested
+    // key is absent from the RegionMap, so the diff alone wouldn't repaint it.
+  }, [regions, playerNationId, unowned, contested]);
 
   // (v0.27, #44) Repaint the marker symbol layer whenever the marker list
   // changes (a turn placed/removed markers) or the nations record changes