feat(#46 PR 2): per-region stat lever (regionChanges) + region-stat hover

v0.29.0 — the LLM can now target individual regions' stats via
TurnResult.regionChanges (set/add per stat, clamped 0-100), applied
after nation-wide stateChanges and before the weighted-median
recompute. The map hover tooltip shows each region's own four stats.
The stub stays deterministic (regionChanges: []).

Fixes #46 (PR 2 of 2)

CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to **History** are listed here, newest first.
 
+## v0.29.0 — 2026-10-15 01:05
+- **#46 (PR 2 of 2): per-region stat lever — the LLM can now target individual regions' stats, and the map hover shows them.** The LLM gains a fine-grained `TurnResult.regionChanges` field (alongside the existing nation-wide `stateChanges`): each entry targets **one** region's own stats by its region key (preferred) or case-insensitive name. A `set` replaces the value; an `add` increments it (both clamped 0–100 at apply time). Region-level changes are applied **after** nation-wide `stateChanges` (so they override the nation-level value for that one region) and **before** the weighted-median recompute, which propagates every region's final value into its owning nation's derived `stats`. A region with no stats entry (unowned / no man's land) is a no-op. The map hover tooltip now shows each region's own four stats (military / economy / stability / population) alongside the region name and owner chip; the `NationPanel` keeps showing the nation-level derived aggregate. The stub stays fully deterministic (`regionChanges: []`) — e2e assertions are untouched.
+  - **Protocol (`shared/protocol.ts`).** New `RegionStatChange = { region: string; stat: StatKey; op: 'set'|'add'; value: number }`. `TurnResult.regionChanges: RegionStatChange[]` is **required** (default `[]`); sits right after `stateChanges`.
+  - **Engine (`server/engine.ts`).**
+    - `resolveRegionKey(ref, validKeys, nameOf)` — pure resolver: exact key first; then a case-insensitive unique-name match; ambiguous / unknown / empty → `null`.
+    - `validateRegionChanges(raw, regionKeyResolver?)` — validates and resolves each entry; drops unknown / ambiguous refs (never throws); clamps `set` values at validation; `add` values are clamped at apply time.
+    - `parseTurnResult` / `validateTurnResult` / `runTurn` all accept an **optional** `regionKeyResolver` (2nd arg / opts) threaded to `validateRegionChanges`; the generic "unclear" fallback carries `regionChanges: []`.
+    - `applyTurnResult` applies `regionChanges` after `stateChanges` and before the weighted-median recompute (the load-bearing order is: events → relations → territory → stateChanges → **regionChanges** → recompute → markers → nationOps).
+    - `isMeaningful` — a turn with only `regionChanges` is meaningful (survives the retry/nudge path).
+    - `buildSystemPrompt` — documents the `regionChanges` JSON field and a constraint bullet (target one region, use keys from the "regions" table, "playerRegionStats" lists the player's current per-region stats).
+    - `buildUserPrompt` — computes and emits `playerRegionStats` (the player's owned regions' current stats; bounded to the player's territory to keep the prompt small; `{}` when none).
+  - **Server route (`server/index.ts`).** The `/jump` route wires the `regionKeyResolver` (always on; degrades to key-only matching when the adjacency manifest is absent).
+  - **Stub (`server/stub.ts`).** `deterministicTurn` returns `regionChanges: []` — the per-region lever is covered by unit tests only, keeping the e2e assertions untouched.
+  - **Client (`src/components/WorldMap.tsx`).** The hover tooltip gains a `regionStats` prop and shows the region's own four stats (`Mil / Eco / Stab / Pop`); a region with no entry shows a `–` placeholder. The name and owner chip are kept; marker rendering and the click→dossier path are unchanged. `src/App.tsx` passes `game.regionStats ?? {}`.
+  - **Unit tests (`server/engine.test.ts`).** New suites: `resolveRegionKey` (key match, case-insensitive name match, unknown / ambiguous → null, key-over-name priority); `validateRegionChanges` (key / name resolution, unknown / invalid stat / non-numeric / invalid op dropped, `set` clamped, `add` not clamped at validation, non-array → [], no-resolver path); `applyTurnResult` with `regionChanges` (set changes only that region, add clamps 0/100, unowned no-op, applied after stateChanges, non-mutation); prompt contract (system prompt documents the field + constraint, user prompt emits bounded `playerRegionStats`); `isMeaningful` with `regionChanges`; stub returns `regionChanges: []`.
+
 ## v0.28.0 — 2026-10-15 00:12
 - **#46 (PR 1 of 2): per-region stats — a nation's four 0–100 stats become a *derived* aggregate.** Instead of storing `Nation.stats` as four independent per-nation numbers, they are now **derived** as the **area×population-weighted median** of the stats of the regions the nation owns. Each sub-region carries its own `RegionStats` in a new `GameState.regionStats: Record<regionKey, RegionStats>` table; a nation's displayed stats are the weighted median over its owned regions. This is the data foundation for the per-region LLM levers that land in **PR 2** — in this PR the LLM still only emits nation-level `stateChanges`, which are re-interpreted as applying to *all* of a nation's owned regions. A new `public/region-geo.json` manifest (area km² + population per region key) supplies the weighting. **Not deployed in this PR** — the production site updates when PR 2 ships (the change is additive and backward-compatible, so deferring the deploy is safe).
   - **Data build (`scripts/`, turf-`.mjs` only; never imported by `.ts`).**

package.json

@@ -1,6 +1,6 @@
 {
   "name": "history",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "private": true,
   "type": "module",
   "description": "AI-driven alternate-history simulator — the LLM is the world engine (Pax Historia style).",

server/engine.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest';
 import type { GameState, MarkerType, Nation, NationStats, Preset, RegionStats, RoundItem } from '../shared/types';
 import { makeEvent, markerId, MAX_MARKERS, seedRegionStats, type MarkerSpec, type NationOp, type TurnResult } from '../shared/protocol';
 import type { LlmClient, ToolDefinition, WireMessage } from './llm';
-import { makeStubLlmClient } from './stub';
+import { deterministicTurn, makeStubLlmClient } from './stub';
 import {
   applyNationOp,
   applyTurnResult,
@@ -20,9 +20,11 @@ import {
   rejectNationOp,
   removeRoundItem,
   resolveNationRef,
+  resolveRegionKey,
   runTurn,
   validateMarkerOps,
   validateNationOps,
+  validateRegionChanges,
   validateTurnResult,
 } from './engine';
 
@@ -548,6 +550,7 @@ describe('applyTurnResult (nation-op proposals, v0.23 #16 P4a)', () => {
       date: '1939-09-03',
       events: [{ nation: 'de', type: 'political', title: 'Reunification', text: 'The nation is renamed.', outcome: 'success' }],
       stateChanges: [],
+      regionChanges: [],
       relations: [],
       territoryChanges: [],
       unowned: [],
@@ -568,6 +571,7 @@ describe('applyTurnResult (nation-op proposals, v0.23 #16 P4a)', () => {
       date: '1939-09-03',
       events: [],
       stateChanges: [],
+      regionChanges: [],
       relations: [],
       territoryChanges: [],
       unowned: [],
@@ -586,6 +590,7 @@ describe('applyTurnResult (nation-op proposals, v0.23 #16 P4a)', () => {
       date: '1939-09-03',
       events: [],
       stateChanges: [],
+      regionChanges: [],
       relations: [],
       territoryChanges: [],
       unowned: [],
@@ -1042,6 +1047,7 @@ describe('applyTurnResult', () => {
       date: '1939-09-03',
       events: [{ nation: 'uk', type: 'military', title: 't', text: 'b', outcome: 'success' }],
       stateChanges: [{ nation: 'uk', stat: 'military', op: 'set', value: 99 }],
+      regionChanges: [],
       relations: [],
       territoryChanges: [],
       unowned: [],
@@ -1058,6 +1064,7 @@ describe('applyTurnResult', () => {
       date: '1939-09-03',
       events: [],
       stateChanges: [],
+      regionChanges: [],
       relations: [],
       territoryChanges: [],
       unowned: [],
@@ -1078,6 +1085,7 @@ describe('applyTurnResult', () => {
       date: '1939-09-03',
       events: [],
       stateChanges: [],
+      regionChanges: [],
       relations: [],
       // 'wales-bbbb' is a real key (owned by uk in the fixture); 'not-a-region-xyz'
       // is not a real key at all. Both are proposed as a gain by DE.
@@ -1102,6 +1110,7 @@ describe('applyTurnResult', () => {
       date: '1939-09-03',
       events: [],
       stateChanges: [],
+      regionChanges: [],
       relations: [],
       // 'wales-bbbb' has a sole previous owner (uk) -> it transfers; 'POL' is
       // owned by no one -> a re-claim (v0.22, #16 P3): DE gains it. It was never
@@ -1123,6 +1132,7 @@ describe('applyTurnResult (sole-ownership invariants, v0.21 #16 P2)', () => {
     date: '1939-09-03',
     events: [],
     stateChanges: [],
+    regionChanges: [],
     relations: [],
     unowned: [],
     nationOps: [], markers: { add: [], remove: [] },
@@ -1211,6 +1221,7 @@ describe('applyTurnResult (no man\'s land, v0.22 #16 P3)', () => {
     date: '1939-09-03',
     events: [],
     stateChanges: [],
+    regionChanges: [],
     relations: [],
     territoryChanges: [],
     unowned: [],
@@ -1329,7 +1340,7 @@ describe('applyTurnResult (no man\'s land, v0.22 #16 P3)', () => {
 
   it('a lone release is meaningful (it survives the retry/nudge path)', () => {
     expect(
-      isMeaningful({ date: 'x', events: [], stateChanges: [], relations: [], territoryChanges: [], unowned: ['GBR'], nationOps: [], markers: { add: [], remove: [] } }),
+      isMeaningful({ date: 'x', events: [], stateChanges: [], regionChanges: [], relations: [], territoryChanges: [], unowned: ['GBR'], nationOps: [], markers: { add: [], remove: [] } }),
     ).toBe(true);
   });
 
@@ -1636,9 +1647,9 @@ describe('buildSystemPrompt (tool mode, v0.21 #16 P2)', () => {
 
 describe('isMeaningful', () => {
   it('is true with an event, false when everything is empty', () => {
-    expect(isMeaningful({ date: 'x', events: [{ nation: 'uk', type: 'military', title: 't', text: 'b', outcome: 'neutral' }], stateChanges: [], relations: [], territoryChanges: [], unowned: [], nationOps: [], markers: { add: [], remove: [] } })).toBe(true);
-    expect(isMeaningful({ date: 'x', events: [], stateChanges: [{ nation: 'uk', stat: 'military', op: 'set', value: 5 }], relations: [], territoryChanges: [], unowned: [], nationOps: [], markers: { add: [], remove: [] } })).toBe(true);
-    expect(isMeaningful({ date: 'x', events: [], stateChanges: [], relations: [], territoryChanges: [], unowned: [], nationOps: [], markers: { add: [], remove: [] } })).toBe(false);
+    expect(isMeaningful({ date: 'x', events: [{ nation: 'uk', type: 'military', title: 't', text: 'b', outcome: 'neutral' }], stateChanges: [], regionChanges: [], relations: [], territoryChanges: [], unowned: [], nationOps: [], markers: { add: [], remove: [] } })).toBe(true);
+    expect(isMeaningful({ date: 'x', events: [], stateChanges: [{ nation: 'uk', stat: 'military', op: 'set', value: 5 }], regionChanges: [], relations: [], territoryChanges: [], unowned: [], nationOps: [], markers: { add: [], remove: [] } })).toBe(true);
+    expect(isMeaningful({ date: 'x', events: [], stateChanges: [], regionChanges: [], relations: [], territoryChanges: [], unowned: [], nationOps: [], markers: { add: [], remove: [] } })).toBe(false);
   });
 
   it('(v0.23 #16 P4a) a turn that only proposes a nation-op is meaningful (it survives the retry/nudge path)', () => {
@@ -1647,6 +1658,7 @@ describe('isMeaningful', () => {
         date: 'x',
         events: [],
         stateChanges: [],
+        regionChanges: [],
         relations: [],
         territoryChanges: [],
         unowned: [],
@@ -1661,6 +1673,7 @@ describe('isMeaningful', () => {
         date: 'x',
         events: [],
         stateChanges: [],
+        regionChanges: [],
         relations: [],
         territoryChanges: [],
         unowned: [],
@@ -1688,6 +1701,7 @@ describe('markers (point placement, v0.27 #44)', () => {
       date: '1939-09-03',
       events: [],
       stateChanges: [],
+      regionChanges: [],
       relations: [],
       territoryChanges: [],
       unowned: [],
@@ -1715,13 +1729,13 @@ describe('markers (point placement, v0.27 #44)', () => {
     state.nations.uk.territory = ['moselle-rygy'];
     const add = [mk('city', 'Strasbourg', 'moselle-rygy')];
     const first = applyTurnResult(state, {
-      date: '1939-09-03', events: [], stateChanges: [], relations: [], territoryChanges: [],
+      date: '1939-09-03', events: [], stateChanges: [], regionChanges: [], relations: [], territoryChanges: [],
       unowned: [], nationOps: [], markers: { add, remove: [] },
     }, undefined, centroidOf);
     expect(first.markers).toHaveLength(1);
     // a second turn proposes the exact same marker again
     const second = applyTurnResult(first, {
-      date: '1939-09-05', events: [], stateChanges: [], relations: [], territoryChanges: [],
+      date: '1939-09-05', events: [], stateChanges: [], regionChanges: [], relations: [], territoryChanges: [],
       unowned: [], nationOps: [], markers: { add, remove: [] },
     }, undefined, centroidOf);
     expect(second.markers).toHaveLength(1);
@@ -1739,6 +1753,7 @@ describe('markers (point placement, v0.27 #44)', () => {
       date: '1939-09-03',
       events: [],
       stateChanges: [],
+      regionChanges: [],
       relations: [],
       territoryChanges: [],
       unowned: [],
@@ -1780,6 +1795,7 @@ describe('markers (point placement, v0.27 #44)', () => {
       date: '1939-09-03',
       events: [],
       stateChanges: [],
+      regionChanges: [],
       relations: [],
       territoryChanges: [],
       unowned: [],
@@ -1808,7 +1824,7 @@ describe('markers (point placement, v0.27 #44)', () => {
       { id: idB, type: 'port', name: 'Dunkirk', regionKey: 'moselle-rygy', lat: 48, lon: 6, ownerNationId: 'uk', placedTurn: 1 },
     ];
     const next = applyTurnResult(state, {
-      date: '1939-09-03', events: [], stateChanges: [], relations: [], territoryChanges: [],
+      date: '1939-09-03', events: [], stateChanges: [], regionChanges: [], relations: [], territoryChanges: [],
       unowned: [], nationOps: [], markers: { add: [], remove: [idA, 'zzzz-not-there'] },
     }, undefined, centroidOf);
     expect(next.markers).toHaveLength(1);
@@ -1824,13 +1840,13 @@ describe('markers (point placement, v0.27 #44)', () => {
     ];
     // 1) uk releases the region → the marker becomes ownerless
     const released = applyTurnResult(state, {
-      date: '1939-09-03', events: [], stateChanges: [], relations: [], territoryChanges: [],
+      date: '1939-09-03', events: [], stateChanges: [], regionChanges: [], relations: [], territoryChanges: [],
       unowned: ['moselle-rygy'], nationOps: [], markers: { add: [], remove: [] },
     }, undefined, centroidOf);
     expect(released.markers[0].ownerNationId).toBeNull();
     // 2) de re-claims the region → the marker's owner follows to de
     const reclaimed = applyTurnResult(released, {
-      date: '1939-09-05', events: [], stateChanges: [], relations: [],
+      date: '1939-09-05', events: [], stateChanges: [], regionChanges: [], relations: [],
       territoryChanges: [{ nation: 'de', gain: ['moselle-rygy'], lose: [] }],
       unowned: [], nationOps: [], markers: { add: [], remove: [] },
     }, undefined, centroidOf);
@@ -1975,6 +1991,7 @@ function mkTurnResult(partial: Partial<TurnResult>): TurnResult {
     date: '1939-09-03',
     events: partial.events ?? [],
     stateChanges: partial.stateChanges ?? [],
+    regionChanges: partial.regionChanges ?? [],
     relations: partial.relations ?? [],
     territoryChanges: partial.territoryChanges ?? [],
     unowned: partial.unowned ?? [],
@@ -2120,3 +2137,336 @@ describe('applyTurnResult — per-region stats (v0.28, #46)', () => {
     expect(JSON.stringify(state.regionStats)).toBe(beforeRegions);
   });
 });
+
+// --- (v0.29, #46 PR 2) Per-region stat lever + region-stat hover ---
+
+describe('resolveRegionKey (v0.29, #46 PR 2)', () => {
+  const keys = new Set(['aabb-1111', 'bccc-2222', 'cddd-3333']);
+  const nameOf = (k: string) =>
+    k === 'aabb-1111' ? 'Alpha' : k === 'bccc-2222' ? 'Beta' : k === 'cddd-3333' ? 'Gamma' : undefined;
+
+  it('an exact key match returns the key', () => {
+    expect(resolveRegionKey('aabb-1111', keys, nameOf)).toBe('aabb-1111');
+  });
+
+  it('a case-insensitive name match returns the key', () => {
+    expect(resolveRegionKey('alpha', keys, nameOf)).toBe('aabb-1111');
+    expect(resolveRegionKey('ALPHA', keys, nameOf)).toBe('aabb-1111');
+    expect(resolveRegionKey('  gamma  ', keys, nameOf)).toBe('cddd-3333');
+  });
+
+  it('an unknown ref (not a key, no name match) returns null', () => {
+    expect(resolveRegionKey('not-a-key', keys, nameOf)).toBeNull();
+  });
+
+  it('an ambiguous name (two regions share it) returns null', () => {
+    const nameOf2 = (k: string) =>
+      k === 'aabb-1111' || k === 'bccc-2222' ? 'Twin' : undefined;
+    expect(resolveRegionKey('twin', keys, nameOf2)).toBeNull();
+  });
+
+  it('empty or whitespace ref returns null', () => {
+    expect(resolveRegionKey('', keys, nameOf)).toBeNull();
+    expect(resolveRegionKey('   ', keys, nameOf)).toBeNull();
+  });
+
+  it('a key that matches both a key and a different region\'s name prefers the key', () => {
+    // 'aabb-1111' is a valid key; nameOf maps 'bccc-2222' to 'Aabb-1111' (case-insensitive match)
+    const nameOf2 = (k: string) => (k === 'bccc-2222' ? 'Aabb-1111' : undefined);
+    expect(resolveRegionKey('aabb-1111', keys, nameOf2)).toBe('aabb-1111'); // key wins
+  });
+});
+
+describe('validateRegionChanges (v0.29, #46 PR 2)', () => {
+  const keys = new Set(['aabb-1111', 'bccc-2222']);
+  const nameOf = (k: string) =>
+    k === 'aabb-1111' ? 'Alpha' : k === 'bccc-2222' ? 'Beta' : undefined;
+  const resolver = (ref: string) => resolveRegionKey(ref, keys, nameOf);
+
+  it('a valid key ref is resolved and passed through', () => {
+    const out = validateRegionChanges(
+      [{ region: 'aabb-1111', stat: 'military', op: 'set', value: 50 }],
+      resolver,
+    );
+    expect(out).toEqual([{ region: 'aabb-1111', stat: 'military', op: 'set', value: 50 }]);
+  });
+
+  it('a case-insensitive name ref is resolved to the key', () => {
+    const out = validateRegionChanges(
+      [{ region: 'alpha', stat: 'economy', op: 'set', value: 30 }],
+      resolver,
+    );
+    expect(out).toEqual([{ region: 'aabb-1111', stat: 'economy', op: 'set', value: 30 }]);
+  });
+
+  it('an unknown ref (resolver returns null) is dropped', () => {
+    const out = validateRegionChanges(
+      [{ region: 'no-such-region', stat: 'military', op: 'set', value: 50 }],
+      resolver,
+    );
+    expect(out).toEqual([]);
+  });
+
+  it('an invalid stat is dropped', () => {
+    const out = validateRegionChanges(
+      [{ region: 'aabb-1111', stat: 'bogus', op: 'set', value: 50 }],
+      resolver,
+    );
+    expect(out).toEqual([]);
+  });
+
+  it('a non-numeric value is dropped', () => {
+    const out = validateRegionChanges(
+      [{ region: 'aabb-1111', stat: 'military', op: 'set', value: 'fifty' }],
+      resolver,
+    );
+    expect(out).toEqual([]);
+  });
+
+  it('a NaN value is dropped', () => {
+    const out = validateRegionChanges(
+      [{ region: 'aabb-1111', stat: 'military', op: 'set', value: NaN }],
+      resolver,
+    );
+    expect(out).toEqual([]);
+  });
+
+  it('an invalid op is dropped', () => {
+    const out = validateRegionChanges(
+      [{ region: 'aabb-1111', stat: 'military', op: 'multiply', value: 2 }],
+      resolver,
+    );
+    expect(out).toEqual([]);
+  });
+
+  it('a set value is clamped to 0-100 at validation', () => {
+    const out = validateRegionChanges(
+      [
+        { region: 'aabb-1111', stat: 'military', op: 'set', value: 150 },
+        { region: 'aabb-1111', stat: 'economy', op: 'set', value: -10 },
+      ],
+      resolver,
+    );
+    expect(out).toEqual([
+      { region: 'aabb-1111', stat: 'military', op: 'set', value: 100 },
+      { region: 'aabb-1111', stat: 'economy', op: 'set', value: 0 },
+    ]);
+  });
+
+  it('an add value is NOT clamped at validation (it is clamped at apply time)', () => {
+    const out = validateRegionChanges(
+      [{ region: 'aabb-1111', stat: 'military', op: 'add', value: 999 }],
+      resolver,
+    );
+    expect(out).toEqual([{ region: 'aabb-1111', stat: 'military', op: 'add', value: 999 }]);
+  });
+
+  it('non-array input returns []', () => {
+    expect(validateRegionChanges(null)).toEqual([]);
+    expect(validateRegionChanges('hello')).toEqual([]);
+    expect(validateRegionChanges(undefined)).toEqual([]);
+  });
+
+  it('non-object entries are skipped', () => {
+    const out = validateRegionChanges(
+      [null, 42, 'x', { region: 'aabb-1111', stat: 'military', op: 'set', value: 50 }],
+      resolver,
+    );
+    expect(out).toEqual([{ region: 'aabb-1111', stat: 'military', op: 'set', value: 50 }]);
+  });
+
+  it('without a resolver, the raw ref is kept (apply will no-op on a miss)', () => {
+    const out = validateRegionChanges(
+      [{ region: 'some-name', stat: 'military', op: 'set', value: 50 }],
+    );
+    expect(out).toEqual([{ region: 'some-name', stat: 'military', op: 'set', value: 50 }]);
+  });
+});
+
+describe('applyTurnResult — regionChanges (v0.29, #46 PR 2)', () => {
+  it('a set changes only that region\'s stats; the derived aggregate shifts', () => {
+    const state = mkTurnState(
+      { uk: mkNation('uk', NS(50, 50, 50, 50), ['a', 'b']) },
+      { a: RS(50, 50, 50, 50), b: RS(50, 50, 50, 50) },
+    );
+    const next = applyTurnResult(
+      state,
+      mkTurnResult({ regionChanges: [{ region: 'a', stat: 'military', op: 'set', value: 80 }] }),
+    );
+    // region a got the set; region b is untouched
+    expect(next.regionStats.a).toEqual(RS(80, 50, 50, 50));
+    expect(next.regionStats.b).toEqual(RS(50, 50, 50, 50));
+    // derived stats are the uniform median of a and b → military median(80,50)=50
+    expect(next.nations.uk.stats.military).toBe(50);
+  });
+
+  it('an add clamps to 0 and 100 at apply time', () => {
+    const state = mkTurnState(
+      { uk: mkNation('uk', NS(90, 50, 50, 50), ['a']) },
+      { a: RS(90, 50, 50, 50) },
+    );
+    const next = applyTurnResult(
+      state,
+      mkTurnResult({
+        regionChanges: [
+          { region: 'a', stat: 'military', op: 'add', value: 999 }, // 90+999 → clamps to 100
+          { region: 'a', stat: 'economy', op: 'add', value: -999 }, // 50-999 → clamps to 0
+        ],
+      }),
+    );
+    expect(next.regionStats.a.military).toBe(100);
+    expect(next.regionStats.a.economy).toBe(0);
+  });
+
+  it('a region with no stats entry (unowned / no man\'s land) is a no-op', () => {
+    const state = mkTurnState(
+      { uk: mkNation('uk', NS(50, 50, 50, 50), ['a']) },
+      { a: RS(50, 50, 50, 50) },
+      ['ghost'], // ghost is unowned, has no entry
+    );
+    const next = applyTurnResult(
+      state,
+      mkTurnResult({ regionChanges: [{ region: 'ghost', stat: 'military', op: 'set', value: 99 }] }),
+    );
+    // ghost has no entry → no-op; a is unchanged; ghost does NOT gain an entry
+    expect(next.regionStats.a).toEqual(RS(50, 50, 50, 50));
+    expect(next.regionStats).not.toHaveProperty('ghost');
+  });
+
+  it('regionChanges are applied AFTER stateChanges (region-level overrides nation-level)', () => {
+    const state = mkTurnState(
+      { uk: mkNation('uk', NS(50, 50, 50, 50), ['a']) },
+      { a: RS(50, 50, 50, 50) },
+    );
+    const next = applyTurnResult(
+      state,
+      mkTurnResult({
+        stateChanges: [{ nation: 'uk', stat: 'military', op: 'set', value: 70 }],
+        regionChanges: [{ region: 'a', stat: 'military', op: 'set', value: 90 }],
+      }),
+    );
+    // stateChanges set all of uk's regions to 70; then regionChanges overwrote a to 90
+    expect(next.regionStats.a.military).toBe(90);
+  });
+
+  it('a nation-level add and a region-level set compose correctly', () => {
+    const state = mkTurnState(
+      { uk: mkNation('uk', NS(50, 50, 50, 50), ['a', 'b']) },
+      { a: RS(50, 50, 50, 50), b: RS(50, 50, 50, 50) },
+    );
+    const next = applyTurnResult(
+      state,
+      mkTurnResult({
+        stateChanges: [{ nation: 'uk', stat: 'economy', op: 'add', value: 10 }],
+        regionChanges: [{ region: 'a', stat: 'economy', op: 'set', value: 99 }],
+      }),
+    );
+    // stateChanges: both regions +10 → a=60, b=60
+    // regionChanges: a set to 99 → a=99, b=60
+    expect(next.regionStats.a.economy).toBe(99);
+    expect(next.regionStats.b.economy).toBe(60);
+  });
+
+  it('the original state is never mutated', () => {
+    const state = mkTurnState(
+      { uk: mkNation('uk', NS(50, 50, 50, 50), ['a']) },
+      { a: RS(50, 50, 50, 50) },
+    );
+    const before = JSON.stringify(state);
+    applyTurnResult(
+      state,
+      mkTurnResult({ regionChanges: [{ region: 'a', stat: 'military', op: 'set', value: 99 }] }),
+    );
+    expect(JSON.stringify(state)).toBe(before);
+  });
+});
+
+describe('prompt contract — regionChanges (v0.29, #46 PR 2)', () => {
+  it('the system prompt documents the regionChanges JSON field', () => {
+    const p = buildSystemPrompt(preset);
+    expect(p).toMatch(/"regionChanges": \[\{"region":"<region key or name>"/);
+  });
+
+  it('the system prompt has the per-region stat change constraint bullet', () => {
+    const p = buildSystemPrompt(preset);
+    expect(p).toMatch(/Per-region stat changes \("regionChanges"\) target ONE region/);
+    expect(p).toMatch(/"playerRegionStats"/);
+  });
+
+  it('the user prompt emits playerRegionStats bounded to the player territory', () => {
+    const state = mkTurnState(
+      {
+        uk: mkNation('uk', NS(50, 50, 50, 50), ['a', 'b']),
+        de: mkNation('de', NS(90, 90, 90, 90), ['c']),
+      },
+      { a: RS(50, 50, 50, 50), b: RS(60, 60, 60, 60), c: RS(90, 90, 90, 90) },
+    );
+    const p = buildUserPrompt(state, []);
+    const payload = JSON.parse(p);
+    // only the player's regions are in playerRegionStats
+    expect(payload.playerRegionStats).toEqual({
+      a: RS(50, 50, 50, 50),
+      b: RS(60, 60, 60, 60),
+    });
+    // de's region c is NOT in playerRegionStats
+    expect(payload.playerRegionStats).not.toHaveProperty('c');
+  });
+
+  it('playerRegionStats is {} when the player has no regions with entries', () => {
+    const state = mkTurnState(
+      { uk: mkNation('uk', NS(50, 50, 50, 50), []) },
+      {},
+    );
+    const p = buildUserPrompt(state, []);
+    const payload = JSON.parse(p);
+    expect(payload.playerRegionStats).toEqual({});
+  });
+
+  it('playerRegionStats omits a player region that has no stats entry', () => {
+    const state = mkTurnState(
+      { uk: mkNation('uk', NS(50, 50, 50, 50), ['a', 'b']) },
+      { a: RS(50, 50, 50, 50) }, // b has no entry
+    );
+    const p = buildUserPrompt(state, []);
+    const payload = JSON.parse(p);
+    expect(payload.playerRegionStats).toEqual({ a: RS(50, 50, 50, 50) });
+    expect(payload.playerRegionStats).not.toHaveProperty('b');
+  });
+});
+
+describe('isMeaningful — regionChanges (v0.29, #46 PR 2)', () => {
+  it('a turn with only regionChanges is meaningful', () => {
+    const result = mkTurnResult({
+      regionChanges: [{ region: 'a', stat: 'military', op: 'set', value: 90 }],
+    });
+    expect(isMeaningful(result)).toBe(true);
+  });
+});
+
+describe('stub — regionChanges (v0.29, #46 PR 2)', () => {
+  it('the deterministic stub returns regionChanges: []', () => {
+    const payload = {
+      state: {
+        turn: 1,
+        date: '1939-09-01',
+        playerNationId: 'uk',
+        nations: {
+          uk: { stats: { military: 50, economy: 50, stability: 50, population: 50 }, territory: ['a'] },
+          de: { stats: { military: 60, economy: 60, stability: 60, population: 60 }, territory: ['b'] },
+        },
+      },
+      pending: [{ kind: 'action' as const, text: 'test' }],
+    };
+    const result = deterministicTurn(payload);
+    expect(result.regionChanges).toEqual([]);
+    // all other required fields are present
+    expect(result).toHaveProperty('date');
+    expect(result).toHaveProperty('events');
+    expect(result).toHaveProperty('stateChanges');
+    expect(result).toHaveProperty('relations');
+    expect(result).toHaveProperty('territoryChanges');
+    expect(result).toHaveProperty('unowned');
+    expect(result).toHaveProperty('nationOps');
+    expect(result).toHaveProperty('markers');
+  });
+});

server/engine.ts

@@ -12,6 +12,7 @@ import type {
   NationStats,
   Preset,
   RelationStatus,
+  RegionStats,
   RoundItem,
   StatKey,
 } from '../shared/types';
@@ -30,6 +31,7 @@ import {
   type MarkerInfo,
   type MarkerSpec,
   type NationOp,
+  type RegionStatChange,
   type TurnEventSpec,
   type TurnResult,
 } from '../shared/protocol';
@@ -187,6 +189,7 @@ export function buildSystemPrompt(preset: Preset, withNeighboursTool = false): s
     '    {"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>"],',
@@ -210,6 +213,7 @@ export function buildSystemPrompt(preset: Preset, withNeighboursTool = false): s
     '- 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.',
     ...territoryRules,
     '- If a field is not relevant this turn, set it to an empty array.',
   ].join('\n');
@@ -263,6 +267,19 @@ export function buildUserPrompt(
         )}. Simulate the combined consequences across all nations and advance the world by one period. Return a single TurnResult.`
       : 'The player takes no action this period; let the world advance on its own momentum. Return a single TurnResult.';
 
+  // (v0.29, #46 PR 2) The player's own regions' current per-region stats, so the
+  // model can reason about — and target via `regionChanges` — the player's
+  // individual regions. Bounded to the player's territory (not the whole
+  // world's 1,800 regions) to keep the prompt small. Always emitted: {} when
+  // the player has no region with a stats entry yet.
+  const playerRegionStats: Record<string, RegionStats> = {};
+  if (state.regionStats) {
+    for (const key of player?.territory ?? []) {
+      const rs = state.regionStats[key];
+      if (rs) playerRegionStats[key] = rs;
+    }
+  }
+
   const payload: Record<string, unknown> = {
     state: {
       turn: state.turn,
@@ -284,6 +301,7 @@ export function buildUserPrompt(
     playerActions,
     pending: items,
     roundInstruction,
+    playerRegionStats,
   };
   if (regionReference) payload.regions = regionReference;
   if (frontier !== undefined) payload.frontier = frontier;
@@ -328,8 +346,13 @@ function extractBalancedObject(text: string): string | null {
 /**
  * Parse raw LLM output into a validated TurnResult, or null if unusable. Strips
  * code fences, extracts the first balanced object, JSON.parse, then validates.
+ * (v0.29, #46 PR 2) The optional `regionKeyResolver` is threaded to
+ * `validateTurnResult` to resolve `regionChanges` refs to region keys.
  */
-export function parseTurnResult(raw: string): TurnResult | null {
+export function parseTurnResult(
+  raw: string,
+  regionKeyResolver?: (ref: string) => string | null,
+): TurnResult | null {
   const cleaned = stripFence(raw);
   const jsonText = extractBalancedObject(cleaned);
   if (!jsonText) return null;
@@ -339,7 +362,7 @@ export function parseTurnResult(raw: string): TurnResult | null {
   } catch {
     return null;
   }
-  return validateTurnResult(obj);
+  return validateTurnResult(obj, regionKeyResolver);
 }
 
 function str(s: unknown, max = 0): string | null {
@@ -400,14 +423,23 @@ export function validateNationOps(raw: unknown): NationOp[] {
  * Validate and normalize an arbitrary parsed object into a safe TurnResult.
  * Ignores unknown/invalid entries; clamps numeric stats to 0-100. Returns null
  * only when the input is not even a plain object.
+ *
+ * (v0.29, #46 PR 2) The optional `regionKeyResolver` resolves each
+ * `regionChanges` ref (key or name) to a concrete region key, dropping
+ * unknown/ambiguous refs; without it the refs are kept as-is (shape-only), so
+ * callers that build a TurnResult by hand (tests) need not supply it.
  */
-export function validateTurnResult(input: unknown): TurnResult | null {
+export function validateTurnResult(
+  input: unknown,
+  regionKeyResolver?: (ref: string) => string | null,
+): TurnResult | null {
   if (typeof input !== 'object' || input === null || Array.isArray(input)) return null;
   const o = input as Record<string, unknown>;
   const result: TurnResult = {
     date: typeof o.date === 'string' ? o.date : '',
     events: [],
     stateChanges: [],
+    regionChanges: [],
     relations: [],
     territoryChanges: [],
     unowned: [],
@@ -507,6 +539,12 @@ export function validateTurnResult(input: unknown): TurnResult | null {
   // moves (a new marker's owner is the region's post-turn owner).
   result.markers = validateMarkerOps(o.markers);
 
+  // (v0.29, #46 PR 2) Per-region stat changes: each targets a single region's
+  // stats (by key or name). Resolved to a key here when a resolver is
+  // supplied; applied by applyTurnResult after the nation-wide stateChanges
+  // and before the derived-stat recompute.
+  result.regionChanges = validateRegionChanges(o.regionChanges, regionKeyResolver);
+
   return result;
 }
 
@@ -547,6 +585,61 @@ export function validateMarkerOps(raw: unknown): { add: MarkerSpec[]; remove: st
   return out;
 }
 
+/**
+ * (v0.29, #46 PR 2) Validate the raw `regionChanges` array of a turn into a
+ * safe {@link RegionStatChange} list — the fine-grained, per-region stat lever
+ * that complements the nation-wide `stateChanges`. Defensive like the rest of
+ * the parser — never throws. Each entry needs a non-empty `region` (the
+ * region's stable key, preferred, or its human-readable name — capped at 120
+ * chars), a known stat, a finite numeric `value`, and an op of `set` or `add`.
+ *
+ * When `regionKeyResolver` is provided, each `region` ref is resolved to a
+ * concrete region key (key first, then a unique case-insensitive name match —
+ * see {@link resolveRegionKey}) and the resolved key is stored; a ref that
+ * resolves to `null` (unknown or ambiguous) is dropped, exactly like an
+ * unresolvable nation ref. When the resolver is absent (pure unit tests), the
+ * ref is kept as-is (shape-only validation) — a name that is not a key simply
+ * no-ops later in `applyTurnResult` (its `regionStats` lookup misses). `set`
+ * values are clamped to 0–100 here; `add` deltas are clamped against the
+ * current value at apply time (they may legitimately exceed 100 in the raw
+ * input, since they are added to an existing 0–100 value).
+ */
+export function validateRegionChanges(
+  raw: unknown,
+  regionKeyResolver?: (ref: string) => string | null,
+): RegionStatChange[] {
+  if (!Array.isArray(raw)) return [];
+  const out: RegionStatChange[] = [];
+  for (const e of raw) {
+    if (!e || typeof e !== 'object') continue;
+    const c = e as Record<string, unknown>;
+    const region = str(c.region, 120);
+    const stat = str(c.stat);
+    if (!region || !stat || !VALID_STATS.has(stat)) continue;
+    if (typeof c.value !== 'number' || !Number.isFinite(c.value)) continue;
+    if (c.op !== 'set' && c.op !== 'add') continue;
+    // Resolve the ref to a key when a resolver is available; drop it when the
+    // resolver says the ref is unknown or ambiguous (never throw). Without a
+    // resolver the ref is kept as-is (a name that is not a key no-ops later in
+    // applyTurnResult, whose regionStats lookup simply misses it).
+    let finalRegion: string;
+    if (regionKeyResolver) {
+      const resolved = regionKeyResolver(region);
+      if (resolved === null) continue; // unknown or ambiguous → drop
+      finalRegion = resolved;
+    } else {
+      finalRegion = region;
+    }
+    out.push({
+      region: finalRegion,
+      stat: stat as StatKey,
+      op: c.op,
+      value: c.op === 'set' ? clampStat(c.value) : c.value,
+    });
+  }
+  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
@@ -559,6 +652,8 @@ export function isMeaningful(result: TurnResult): boolean {
   return (
     result.events.length > 0 ||
     result.stateChanges.length > 0 ||
+    // (v0.29, #46 PR 2) a per-region stat change is a real world change.
+    result.regionChanges.length > 0 ||
     result.unowned.length > 0 ||
     result.nationOps.length > 0 ||
     // (v0.27, #44) a marker placed or removed this turn is a real world change.
@@ -761,6 +856,18 @@ export function applyTurnResult(
     }
     n.stats[c.stat] = c.op === 'set' ? clampStat(c.value) : clampStat(n.stats[c.stat] + c.value);
   }
+  // (v0.29, #46 PR 2) Fine-grained, per-region stat changes: each targets ONE
+  // region's own stats entry (by its resolved region key). Applied AFTER the
+  // nation-wide stateChanges (so a region-level change overrides the
+  // nation-level one for that single region) and BEFORE the weighted-median
+  // recompute below, which propagates every region's final value up into its
+  // owning nation's derived `stats`. A region with no stats entry (unowned /
+  // no man's land) is a no-op — there is nothing to change.
+  for (const c of result.regionChanges) {
+    const rs = next.regionStats[c.region];
+    if (!rs) continue; // no entry (unowned) → no-op
+    rs[c.stat] = c.op === 'set' ? clampStat(c.value) : clampStat(rs[c.stat] + c.value);
+  }
   for (const n of Object.values(next.nations)) {
     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
@@ -908,6 +1015,37 @@ export function resolveNationRef(state: GameState, ref: string): string | null {
   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
@@ -1177,8 +1315,18 @@ export async function runTurn(opts: {
    * still region-consistent, just unweighted.
    */
   geoOf?: (key: string) => { area: number; population: number } | undefined;
+  /**
+   * (v0.29, #46 PR 2) Region ref resolver: resolves a `regionChanges` entry's
+   * `region` (a region key, preferred, or a human-readable name) to a concrete
+   * region key, or `null` when the ref is unknown or ambiguous (two or more
+   * regions share the name) — the engine drops such entries. Present, the
+   * model may name a region by its name and it is resolved before apply;
+   * absent, refs are kept as-is (a name that is not a key simply no-ops in
+   * applyTurnResult's regionStats lookup).
+   */
+  regionKeyResolver?: (ref: string) => string | null;
 }): Promise<{ state: GameState; result: TurnResult }> {
-  const { llm, preset, state, items, regionReference, validRegionKeys, getNeighbours, centroidOf, geoOf } = opts;
+  const { llm, preset, state, items, regionReference, validRegionKeys, getNeighbours, centroidOf, geoOf, regionKeyResolver } = opts;
   const chatWithTools = llm.chatWithTools;
   const useTools = getNeighbours !== undefined && chatWithTools !== undefined;
   const system = buildSystemPrompt(preset, useTools);
@@ -1216,18 +1364,24 @@ export async function runTurn(opts: {
     return llm.chat(history as ChatMessage[], { temperature: 0.4, maxTokens: DEFAULT_MAX_TOKENS });
   };
 
-  let result = parseTurnResult(await call([
-    { role: 'system', content: system },
-    { role: 'user', content: user },
-  ]));
-
-  if (result === null || !isMeaningful(result)) {
-    result = parseTurnResult(await call([
+  let result = parseTurnResult(
+    await call([
       { role: 'system', content: system },
       { role: 'user', content: user },
-      { role: 'assistant', content: '' },
-      { role: 'user', content: nudge },
-    ]));
+    ]),
+    regionKeyResolver,
+  );
+
+  if (result === null || !isMeaningful(result)) {
+    result = parseTurnResult(
+      await call([
+        { role: 'system', content: system },
+        { role: 'user', content: user },
+        { role: 'assistant', content: '' },
+        { role: 'user', content: nudge },
+      ]),
+      regionKeyResolver,
+    );
   }
 
   if (result === null || !isMeaningful(result)) {
@@ -1235,6 +1389,7 @@ export async function runTurn(opts: {
       date: addDays(state.date, 2),
       events: [genericUnclearEvent(state)],
       stateChanges: [],
+      regionChanges: [],
       relations: [],
       territoryChanges: [],
       unowned: [],

server/index.ts

@@ -20,9 +20,9 @@ import type {
 import type { GameState } from '../shared/types';
 import { createLlmClient } from './llm';
 import { makeStubLlmClient } from './stub';
-import { askAdvisor, confirmNationOp, queueRoundItem, rejectNationOp, removeRoundItem, runTurn } from './engine';
+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, validKeys } from './regions';
+import { allTerritoryKeys, centroidOf, expandCountriesToKeys, geoOf, hasAdjacency, hasCentroids, hasGeo, loadRegions, neighboursOf, referenceForKeys, regionName, validKeys } from './regions';
 import { createPresetStore } from './presets';
 import { openDb, type Db } from './db';
 
@@ -307,6 +307,13 @@ app.post('/api/games/:id/jump', async (req, res) => {
       // owned region by area×population (without it the aggregate degrades to
       // an unweighted median — still region-consistent, just unweighted).
       geoOf: hasGeo() ? (key) => geoOf(key) : undefined,
+      // (v0.29, #46 PR 2) region ref resolver: lets the model name a
+      // regionChanges target by its human-readable name (resolved
+      // case-insensitively against the region-key manifest) or its key;
+      // unknown / ambiguous refs are dropped. Always on — the resolver is
+      // pure (validKeys + regionName) and degrades to a key-only match when
+      // the manifest is absent.
+      regionKeyResolver: (ref) => resolveRegionKey(ref, validKeys(), (k) => regionName(k)),
     });
     db.save(state);
     broadcast(id, 'turn', { state, result });

server/stub.ts

@@ -72,6 +72,11 @@ function truncate(s: string, n: number): string {
  * (v0.27, #44) The stub likewise NEVER places or removes a map marker (it
  * always returns `markers: { add: [], remove: [] }`) — the marker path is
  * covered by unit tests only, keeping the e2e assertions untouched.
+ *
+ * (v0.29, #46 PR 2) The stub likewise NEVER changes per-region stats (it
+ * always returns `regionChanges: []`) — the per-region lever is covered by
+ * unit tests only (see server/engine.test.ts), keeping the e2e assertions
+ * untouched.
  */
 export function deterministicTurn(p: StubPayload): TurnResult {
   const state = p.state;
@@ -133,6 +138,7 @@ export function deterministicTurn(p: StubPayload): TurnResult {
     date: addDays(state?.date ?? '1939-09-01', 2),
     events,
     stateChanges: [{ nation: pid, stat: 'military', op: 'set', value: mil }],
+    regionChanges: [], // the stub never changes per-region stats (see doc comment)
     relations: otherId ? [{ a: pid, b: otherId, set: 'ally' }] : [],
     territoryChanges,
     unowned: [], // the stub never creates no man's land (see doc comment)

shared/protocol.ts

@@ -20,6 +20,23 @@ export type StateChange =
   | { nation: string; stat: StatKey; op: 'set'; value: number }
   | { nation: string; stat: StatKey; op: 'add'; value: number };
 
+/**
+ * (v0.29, #46 PR 2) A numeric change to one of **one region's** 0–100 stats —
+ * the fine-grained, per-region lever that complements the nation-wide
+ * {@link StateChange}. `region` names the target by its **region key**
+ * (preferred) or its human-readable **name** (the engine resolves it
+ * case-insensitively, mirroring `resolveNationRef`); after validation it holds
+ * the resolved **region key**. `op` is `set` (replace the value) or `add`
+ * (delta, clamped to 0–100 by the engine).
+ */
+export type RegionStatChange = {
+  /** The target region's key (preferred) or name (resolved by the engine). */
+  region: string;
+  stat: StatKey;
+  op: 'set' | 'add';
+  value: number;
+};
+
 /** Set the bilateral relation between nations `a` and `b` to `set` (symmetric). */
 export interface RelationChange {
   a: string;
@@ -217,6 +234,17 @@ export interface TurnResult {
   date: string;
   events: TurnEventSpec[];
   stateChanges: StateChange[];
+  /**
+   * (v0.29, #46 PR 2) Fine-grained, **per-region** stat changes: each targets a
+   * single region's 0–100 stats (by region key or name) and complements the
+   * nation-wide `stateChanges` (which apply to *all* of a nation's regions).
+   * The engine resolves each `region` to a key (key first, then a
+   * case-insensitive unique name match) and applies it to
+   * `GameState.regionStats` only for regions that have an entry (owned); an
+   * unowned / no-man's-land region is a no-op. Empty on turns where the model
+   * changes no individual region. Required (default `[]`).
+   */
+  regionChanges: RegionStatChange[];
   relations: RelationChange[];
   territoryChanges: TerritoryChange[];
   /**

src/App.tsx

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

src/components/WorldMap.tsx

@@ -17,7 +17,7 @@ import {
   type RegionMap,
   type RegionOwner,
 } from '@shared/protocol';
-import { MARKER_TYPES, type MapMarker, type Nation } from '@shared/types';
+import { MARKER_TYPES, type MapMarker, type Nation, type RegionStats } from '@shared/types';
 import { cn } from '@/lib/utils';
 import { idToKey } from '@/lib/regions';
 
@@ -410,11 +410,29 @@ function hoverHtml(
   region?: RegionOwner,
   nation?: Nation,
   noMansLand = false,
+  regionKey?: string,
+  regionStats?: Record<string, RegionStats>,
 ): string {
   if (!region || !nation) {
     return `<div class="hm-popup"><div class="hm-popup-title">${esc(subRegionName || 'Unclaimed')}</div><div class="hm-popup-sub">${unownedTooltipLabel(noMansLand)}</div></div>`;
   }
-  const stats = [statRow('Mil', nation.stats.military), statRow('Eco', nation.stats.economy)].join('');
+  // (v0.29, #46 PR 2) The region's OWN per-region stats (not the nation's
+  // derived aggregate), looked up by region key. When the region has no stats
+  // entry (defensive — an owned region should always have one) every stat
+  // shows a placeholder dash. The dossier (NationPanel) still shows the
+  // nation's derived stats, so this tooltip is the one place a single region's
+  // numbers are visible on the map.
+  const rs = regionKey ? regionStats?.[regionKey] : undefined;
+  const row = (label: string, v?: number): string =>
+    rs == null
+      ? `<div class="hm-stat"><span class="hm-stat-k">${label}</span><span class="hm-stat-v">–</span></div>`
+      : statRow(label, v);
+  const stats = [
+    row('Mil', rs?.military),
+    row('Eco', rs?.economy),
+    row('Stab', rs?.stability),
+    row('Pop', rs?.population),
+  ].join('');
   return `<div class="hm-popup">
     <div class="hm-popup-title">${esc(subRegionName || region.owner)}</div>
     <div class="hm-popup-owner"><span class="hm-chip" style="background:${region.color}"></span>${esc(region.owner)}</div>
@@ -453,6 +471,14 @@ interface Props {
    * a top-most symbol layer (per-type glyph + name, per-type color).
    */
   markers?: MapMarker[];
+  /**
+   * (v0.29, #46 PR 2) The game's per-region stats (`GameState.regionStats`,
+   * keyed by region key). Used only by the hover tooltip to show a single
+   * region's own four 0–100 stats (a region with no entry shows placeholders).
+   * The dossier (NationPanel) is unaffected — it keeps the nation's derived
+   * stats.
+   */
+  regionStats?: Record<string, RegionStats>;
 }
 
 /**
@@ -509,6 +535,7 @@ export default function WorldMap({
   unowned,
   onFocusNation,
   markers,
+  regionStats,
 }: Props) {
   const containerRef = useRef<HTMLDivElement>(null);
   const mapRef = useRef<maplibregl.Map | null>(null);
@@ -524,6 +551,8 @@ export default function WorldMap({
   const unownedRef = useRef<Set<string>>(new Set(unowned ?? []));
   const onFocusNationRef = useRef(onFocusNation);
   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 ?? {});
   regionsRef.current = regions;
   nationsRef.current = nations;
   playerRef.current = playerNationId;
@@ -531,6 +560,7 @@ export default function WorldMap({
   unownedRef.current = new Set(unowned ?? []);
   onFocusNationRef.current = onFocusNation;
   markersRef.current = markers ?? [];
+  regionStatsRef.current = regionStats ?? {};
 
   // Diffing state for the transient territory-change flash (owned by this component
   // so a resync with identical data never re-flashes).
@@ -689,11 +719,11 @@ export default function WorldMap({
       // (v0.22, #16 P3) whether this region is no man's land (released
       // mid-game), so the ownerless tooltip can say so.
       const pKey = f.properties?.regionKey;
-      const noMansLand =
-        !region && typeof pKey === 'string' && pKey !== '' && unownedRef.current.has(pKey);
+      const keyStr = typeof pKey === 'string' && pKey !== '' ? pKey : undefined;
+      const noMansLand = !region && keyStr !== undefined && unownedRef.current.has(keyStr);
       hoverPopup
         .setLngLat(e.lngLat)
-        .setHTML(hoverHtml(p?.name ?? subId, region, nation, noMansLand))
+        .setHTML(hoverHtml(p?.name ?? subId, region, nation, noMansLand, keyStr, regionStatsRef.current))
         .addTo(map);
       map.getCanvas().style.cursor = 'pointer';
     };