feat(abilities): add disasters & pandemics lever (v0.41.0, #63)
CI / build + unit + e2e (pull_request) Successful in 1m55s

Add the 9th modular LLM ability: a turn-transient `TurnResult.disasters`
lever letting the LLM declare natural/man-made disasters (earthquake /
flood / volcanic / wildfire / famine / plague / epidemic) on a nation or
a region, applying a DETERMINISTIC (type, severity) stat dip (no hidden
randomness). Like the hybrid layer it owns no GameState field, needs no
db.ts change, and leaves no durable list — an ongoing plague/epidemic is
simply re-declared each turn it persists.

- shared/protocol.ts: DisasterType / DisasterSeverity / DisasterEvent /
  DisastersOps, and `TurnResult.disasters` (between `ideology` and
  `markers`; required, default `{ events: [] }`).
- server/abilities/disasters.ts: the ability module (validate / apply /
  schemaLine / constraint / isMeaningful / inert stub / empty payload; no
  stateFields). `DISASTER_EFFECTS` is the deterministic (type, severity)
  dip table (population never touched). Target resolution mirrors hybrid
  (a region key hits its SOLE owner; 0/2+ owners dropped) but has NO
  `from` field, so there is no self-target drop. Dips clamp to 0-100,
  mirror to the target's regions (regionStats), and re-derive the target
  nation's stats (same 0-region / no-entry guards).
- Registered last in ABILITIES (after ideology). System-prompt goldens
  regenerated (one schema line + one constraint bullet each); the
  user.txt golden stays byte-identical (payload() is {}).
- New server/abilities/disasters.test.ts (33 tests); registry.test.ts
  updated to the 9-ability contract.
- Secondary cleanups from the v0.40 refactor: AGENTS.md (abilities/ in
  the Layout tree + a "how to add a new ability" bullet + a disasters
  bullet), delete the orphaned validateTakeovers JSDoc, fold both inline
  `as unknown` casts into the top-level ./abilities import, and de-dup
  `str` (now imported from ./abilities/shared).

Version bumped 0.40.0 -> 0.41.0.
This commit is contained in:
2026-10-16 09:15:55 +00:00
parent df52261835
commit c90e9ae753
14 changed files with 984 additions and 116 deletions
+70
View File
@@ -598,6 +598,58 @@ export function isNuclearCapable(nation: Nation, markers: readonly MapMarker[]):
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[];
}
/** The exact JSON object the world-simulator LLM must return for a turn. */
export interface TurnResult {
date: string;
@@ -749,6 +801,24 @@ export interface TurnResult {
* 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.27, #44) Map-marker ops this turn. `add` places new named markers
* (the engine positions each at its region's centroid + a small