v0.28.0 (#46): per-region stats — area×population-weighted-median Nation.stats (PR 1 of 2)

shared/types.ts

@@ -13,6 +13,19 @@ export interface NationStats {
   population: number;
 }
 
+/**
+ * (v0.28, #46) The 0–100 status indices of a **single region**. Per-region stats
+ * are the unit of record: a nation's aggregate {@link NationStats} is derived as
+ * the area×population-weighted median of the stats of the regions it owns (see
+ * `protocol.deriveNationStats`). Every value is clamped to 0–100 by the engine.
+ */
+export interface RegionStats {
+  military: number;
+  economy: number;
+  stability: number;
+  population: number;
+}
+
 export const STAT_KEYS = ['military', 'economy', 'stability', 'population'] as const;
 export type StatKey = (typeof STAT_KEYS)[number];
 
@@ -217,6 +230,19 @@ export interface GameState {
    * server/db.ts) — additive, no data wipe. Capped at protocol.MAX_MARKERS.
    */
   markers: MapMarker[];
+  /**
+   * (v0.28, #46) Per-region stats, keyed by **region key** (see
+   * `public/region-keys.json`): each owned region carries its own four 0–100
+   * stats, and a nation's aggregate `Nation.stats` is the area×population-
+   * weighted median of the regions it owns (see `protocol.deriveNationStats`).
+   * A region that ends a turn **unowned** (released to no man's land) has NO
+   * entry, and a preset-unassigned region (never owned) has none until first
+   * claimed (re-claiming re-inits it to the gainer's stats). Always present on a
+   * fresh game (every owned region seeded with its owner's initial stats); a
+   * legacy SQLite row without the field is migrated at load (see server/db.ts)
+   * — additive, no data wipe.
+   */
+  regionStats: Record<string, RegionStats>;
 }
 
 /**