Bump to v0.21.0 (region transfers + getNeighbours tool, #16 P2)

AGENTS.md

@@ -28,12 +28,19 @@ renders territorial ownership; the whole thing persists to SQLite and streams ov
 - Backend: Node 22 + Express — one process serving the built client, `/api` (REST), and `/sse`
 - Persistence: `better-sqlite3` (one row per game, full `GameState` as JSON)
 - Map: MapLibre GL (`maplibre-gl`) — remote OpenFreeMap `dark` basemap + a **sub-national**
-  choropleth from `public/regions.geo.json` (2,597 sub-regions; feature `id` = `<ISO_A3>-<nn>`,
-  `properties.parent` = the country's ISO_A3). Ownership and the LLM stay at **country**
-  granularity, so a sub-region inherits its parent country's owner color (see #16).
+  choropleth from `public/regions.geo.json` (1,796 sub-regions; feature `id` = `<ISO_A3>-<nn>`,
+  `properties.parent` = the country's ISO_A3). Ownership is at **region-key** granularity
+  (v0.19, #16 P1): every sub-region is addressed by a stable key from
+  `public/region-keys.json`, `Nation.territory` holds those keys, and each sub-region is
+  colored by its own owner. Since v0.21 (#16 P2) the LLM moves *individual* sub-regions
+  across shared land borders (frontier-biased transfers, verified with the `getNeighbours`
+  function-calling tool) instead of whole countries.
 - The LLM client is a thin OpenAI chat-completions wrapper over native `fetch` with an
-  **injectable transport** (mirrors `mesh-bot/src/llm`). A deterministic **stub** transport
-  (`LLM_STUB=1`) is used by all tests/e2e.
+  **injectable transport** (mirrors `mesh-bot/src/llm`), with two entry points: plain
+  `chat()` and `chatWithTools()` — a bounded OpenAI function-calling loop (max 6 tool
+  rounds, then one forced no-tools request) sharing the same retry/backoff/
+  `reasoning_effort` machinery (see the LLM config note below). A deterministic **stub**
+  transport (`LLM_STUB=1`) is used by all tests/e2e.
 
 ## Layout
 
@@ -45,22 +52,29 @@ 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)
+├── vitest.config.ts        # unit tests (server/**/*.test.ts + scripts/**/*.test.ts; 105 tests)
 ├── playwright.config.ts    # deterministic e2e (webServer runs npm run dev, LLM_STUB=1)
 ├── index.html
 ├── presets/                # 5 scenario JSON files + index.json (manifest)
 ├── public/
 │   ├── countries.geo.json  # 177 countries, id=ISO_A3 (input to the region generator)
-│   └── regions.geo.json    # 2,597 sub-regions, id=<ISO_A3>-<nn>, parent=ISO_A3 (the choropleth)
+│   ├── regions.geo.json    # 1,796 sub-regions, id=<ISO_A3>-<nn>, parent=ISO_A3 (the choropleth)
+│   ├── region-keys.json    # feature id -> region key, 1,796 entries (the ownership/LLM address space, #16 P1)
+│   └── region-adjacency.json # region key -> bordering region keys, 1,796 entries (the getNeighbours data, #16 P2)
+├── scripts/                # the geo/manifest data pipeline — .mjs (turf allowed HERE only;
+│   │                       #   never imported by .ts): generate → coarsen → cleanup → smooth →
+│   │                       #   fill-gaps → build-region-keys → build-region-adjacency
+│   └── *.test.ts           # turf-free vitest tests pinning the dataset + both manifests
 ├── shared/                 # NO runtime deps — the single source of truth
 │   ├── types.ts            #   domain types (Nation, GameState, RoundItem, Preset, …)
 │   └── protocol.ts         #   LLM TurnResult schema + AddAction/AddDiplomacy/RemoveQueueItem/Jump request types + pure helpers
 ├── server/
-│   ├── index.ts            # Express: /api/* (action|diplomacy|queue/remove|jump|advisor|games|presets), /sse/:id; reads PORT/LLM_*/DATA_DIR
-│   ├── engine.ts           # pure: buildPrompt / parse+validate / applyTurnResult / runTurn / queueRoundItem / removeRoundItem / advisor
-│   ├── llm.ts              # LlmClient (injectable transport, retry+backoff, logging) + env config
-│   ├── stub.ts             # deterministic LLM transport (tests/e2e) + ADVISOR_MARKER
-│   ├── map.ts              # GameState → RegionMap (ISO_A3 → owner + stable color)
+│   ├── index.ts            # Express: /api/* (health|action|diplomacy|queue/remove|jump|advisor|games|map|presets), /sse/:id; reads PORT/LLM_*/DATA_DIR
+│   ├── engine.ts           # pure: prompts / parse+validate / applyTurnResult (sole-ownership) / runTurn (tool path + plain fallback) / getNeighbours tool + executor / playerFrontier / queue ops / advisor
+│   ├── llm.ts              # LlmClient: chat() + chatWithTools() (bounded function-calling loop), injectable transport, retry+backoff, logging + env config
+│   ├── regions.ts          # turf-free region-key data access: load manifest/geo/adjacency (public/ then dist/), country→keys expansion, reference table, neighboursOf/hasAdjacency
+│   ├── stub.ts             # deterministic LLM transport (tests/e2e): one frontier conquest per turn + ADVISOR_MARKER
+│   ├── map.ts              # GameState → RegionMap (region key → owner + stable color)
 │   ├── presets.ts          # load preset JSON files from disk
 │   ├── db.ts               # SQLite open/save/load
 │   └── *.test.ts           # unit tests (vitest)
@@ -91,10 +105,11 @@ history/
 | `npm run dev` | Express on :4321 (tsx watch) + Vite on :5173 (proxies `/api`,`/sse`) concurrently |
 | `npm run build` | `vite build` (client → `dist/`) then `tsup server/index.ts` → `server/dist/index.js` |
 | `npm start` | run the compiled server (`node server/dist/index.js`) on :4321 |
-| `npm test` | vitest unit tests in `server/` (39 tests) |
+| `npm test` | vitest unit tests (`server/` + `scripts/`; 105 tests) |
 | `npm run typecheck` | `tsc --noEmit` (strict) across src/server/shared/e2e/configs |
 | `npm run lint` | ESLint flat config |
 | `npm run e2e` | Playwright, fully deterministic (`LLM_STUB=1`); **runs in CI on every PR** (see below) |
+| `npm run build:region-keys` / `build:region-adjacency` | (re)generate the `public/region-keys.json` / `region-adjacency.json` manifests — deterministic + idempotent (byte-identical re-run) |
 | `docker compose up -d --build` | prod image on :4321, routed via Traefik at `history.dev.kkhost.pl` |
 
 **Local verification (before every PR):** `npm run typecheck` + `npm run lint` + `npm test` (unit) + `npm run build`. The full **e2e** suite (`npm run e2e`) is verified by **CI on every PR** (the Playwright config boots its own dev webServer with `LLM_STUB=1`) — locally you only need the four checks above; e2e is the CI source of truth.
@@ -143,29 +158,45 @@ history/
   (model down) surfaces as an HTTP 502 to the client (shown as a toast).
 - **Stable per-nation colors.** `shared.nationColor(id)` hashes a nation id → hue, shared by the
   server's `RegionMap` and any client coloring so the choropleth always agrees.
-- **Map click → dossier target (owner resolved from the RegionMap, via the parent country).**
+- **Region-level territory (v0.19/v0.21, #16 P1+P2).** Since v0.19 ownership lives at sub-region
+  granularity: `Nation.territory` holds **region keys** (`<name-slug>-<4char>`, e.g. `moselle-rygy`;
+  the manifest is `public/region-keys.json`), `server/regions.ts` expands each preset's country list
+  to all its sub-regions' keys at game creation, and `buildRegionMap` keys the choropleth `RegionMap`
+  by region key. Since v0.21 transfers are **frontier-biased**: `applyTurnResult` is snapshot-first
+  and enforces **sole ownership** (a key transfers only when exactly one nation claims it to gain,
+  it has exactly one current owner, and the owner is not the gainer — a double claim is rejected and
+  a lone `lose` is a no-op, so a key can never be orphaned or duplicated), and the LLM can call the
+  `getNeighbours` tool (`GET_NEIGHBOURS_TOOL` + `makeNeighboursExecutor` in `engine.ts`, data from
+  `public/region-adjacency.json` via `neighboursOf`) to verify land borders before proposing a
+  transfer; the user payload carries the player's `frontier` (the sorted other-nation keys bordering
+  the player's territory, via `playerFrontier`). The tool path degrades gracefully: without the
+  adjacency manifest (or with a client lacking `chatWithTools`), a turn runs the legacy plain
+  `chat()` path and the tool/frontier simply switch off.
+- **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
-  **parent country's** owning nation (`focusNation(ownerId)` in `GameScreen`, which also records
-  which region was clicked for a small dossier label); the manual "Inspect" selector and a map click
-  both set the same target and stay in sync (a manual pick clears the label). Ownership is resolved
-  from the authoritative `RegionMap` (keyed by the **parent country's** ISO_A3) via the feature's
-  `properties.parent`, using the shared `mapFeatureOwner()` helper (`regionId` still holds the
-  sub-region's own id, e.g. `FRA-03`). It must **never** be resolved from the feature's top-level
-  `id` (MapLibre repacks it into a numeric index — the "no owner" bug, #6) nor from the sub-region
-  `id` (not a `RegionMap` key). Sub-regions of a country with no `RegionMap` entry (unowned) leave
-  the current dossier target unchanged — never a broken dossier. The hover path (a non-closeable
-  tooltip showing the sub-region name + parent country + owner + key stats) uses the same resolution.
-  **PR 2 of #16:** the map renders `regions.geo.json` (sub-national) but ownership/territory and the
-  LLM stay at country level — a nation owns whole countries, so all its sub-regions share the country's
-  color, and a whole-country transfer flips all its sub-regions at once (PR 3 will make sub-regions
-  individually ownable).
+  owning nation (`focusNation(ownerId, {name})` in `App.tsx`, which also records which region was
+  clicked for a small dossier label); the manual "Inspect" selector and a map click both set the
+  same target and stay in sync (a manual pick clears the label). Ownership is resolved from the
+  authoritative `RegionMap` (keyed by **region key**) via the feature's stamped
+  `properties.regionKey`, using the shared `mapFeatureOwner()` helper (`shared/protocol.ts`) —
+  `WorldMap` stamps each rendered feature with its key from `region-keys.json` when it builds the
+  choropleth source. It must **never** be resolved from the feature's top-level `id` (MapLibre
+  repacks it into a numeric index — the "no owner" bug, #6) nor from the raw sub-region `id` (not a
+  `RegionMap` key). A sub-region whose key has no owner leaves the current dossier target
+  unchanged — never a broken dossier. The hover path (a non-closeable tooltip showing the region
+  name + owner chip + key stats) uses the same resolution. `properties.parent` is static
+  geographic-origin data — never use it for ownership or display.
 - **Deterministic stub.** `server/stub.ts` answers the model contract deterministically per
   queued round item: each `action` item → one military/success event, each `diplomacy` item → one
   diplomatic/partial event, an empty round → one political "The world moves on" event. The player
   nation's `military` is set to `(current + 5)` (clamped) once per committed turn (not per item),
   the player is allied with the first other nation (by key order in the `nations` record), and the
-  date advances 2 days. Unit + e2e assertions rely on these exact values, so keep the stub
-  deterministic.
+  date advances 2 days. Since v0.21 the stub also makes **one contiguous conquest per turn**: the
+  player gains `frontier[0]` (the first of the sorted `frontier` list from the prompt payload —
+  stable) and that region's owner loses it; an empty frontier (no controllable border, e.g. the UK
+  in `wwii-1939`) transfers nothing. The stub answers plain `content` (never tool calls), so it
+  naturally bypasses the tool loop in a single round. Unit + e2e assertions rely on these exact
+  values, so keep the stub deterministic.
 - **HUD layout.** The game screen is a full-viewport map (z-0) with `FloatingWindow` overlays. The
   top bar is **pinned** — a fixed, non-movable bar centered at the top a few px down (it re-centers
   on resize and always floats above the other windows). The **dossier / event-feed / action**
@@ -208,6 +239,12 @@ history/
 > ignoring `reasoning`. `chat()` retries transient failures (timeout/abort, 5xx, network
 > errors, null/empty `content`) up to 3 attempts with 2s→3s backoff and logs every call
 > (`[llm] chat ok` / `[llm] chat failed`). No auth header is sent — the endpoint requires no key.
+> The same machinery backs `chatWithTools()` (the function-calling loop used by turns when the
+> region-adjacency manifest is loaded): a `finish_reason: "tool_calls"` response is a *successful*
+> round (never a truncation error), each requested tool call is run through the injected executor,
+> the assistant tool-call message plus one `tool` result message per call are appended to the
+> history, and the loop re-sends until a final `content` — max `DEFAULT_MAX_TOOL_ROUNDS = 6`
+> tool rounds, after which one last *no-tools* request forces the answer.
 | `PORT` | `4321` | single server port |
 | `DATA_DIR` | `./data` | where `history.db` lives |
 | `CLIENT_DIST` | `./dist` | built client to serve (auto-found) |
@@ -247,6 +284,10 @@ history/
   caught.
 - **`better-sqlite3`** is the only native module; the Docker build relies on its prebuilt binary
   (works on `node:22-slim`/glibc). It's the sole `--external` in the tsup server bundle.
-- The `dist/` client is committed to the build output only; the `public/` geo files
-  (`regions.geo.json` — the choropleth — and `countries.geo.json`) are copied into `dist/` by Vite
-  at build time, so the prod image serves them from `dist/` (no separate copy).
+- The `dist/` client is committed to the build output only; the `public/` data files
+  (`regions.geo.json` — the choropleth — `region-keys.json` + `region-adjacency.json` — the
+  ownership/adjacency manifests — and `countries.geo.json`) are copied into `dist/` by Vite at
+  build time, so the prod image serves them from `dist/` (no separate copy). The server's region
+  loader (`server/regions.ts`) probes `public/` then `dist/` for the manifest pair, because the
+  Docker image keeps only `dist/` (the v0.20 fix — before it, region-level ownership silently
+  never activated in prod).