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

server/regions.ts

@@ -17,6 +17,8 @@
 //     field (v0.21, #16 P2)
 //   - centroidOf(): a region key's precomputed anchor point ({ lat, lon, spread })
 //     — 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)
 //
 // Deliberately turf-free: it reads the JSON files with plain JSON.parse and
 // never imports @turf/@types/geojson (importing one pulls @types/geojson into
@@ -45,6 +47,8 @@ interface RegionData {
   adjacency: Record<string, string[]>;
   /** region key -> anchor point (from public/region-centroids.json). */
   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 }>;
 }
 
 let data: RegionData | null = null;
@@ -72,6 +76,7 @@ export function loadRegions(root: string): boolean {
   const geoFile = 'regions.geo.json';
   const adjacencyFile = 'region-adjacency.json';
   const centroidsFile = 'region-centroids.json';
+  const regionGeoFile = 'region-geo.json';
   const base = [
     path.join(root, 'public'), // dev: Vite serves public/ at /
     path.join(root, 'dist'), // prod: Vite copies public/* -> dist/ (== clientDir)
@@ -85,13 +90,13 @@ export function loadRegions(root: string): boolean {
   const geoPath = path.join(base, geoFile);
   try {
     const idToKey = JSON.parse(readFileSync(keyPath, 'utf8')) as Record<string, string>;
-    const geo = JSON.parse(readFileSync(geoPath, 'utf8')) as {
+    const geoJson = JSON.parse(readFileSync(geoPath, 'utf8')) as {
       features?: Array<{ id?: string | number; properties?: { name?: string; parent?: string } }>;
     };
     const keyToInfo: Record<string, RegionInfo> = {};
     const keysByCountry: Record<string, string[]> = {};
     const validKeys = new Set<string>();
-    for (const f of geo.features ?? []) {
+    for (const f of geoJson.features ?? []) {
       const id = f.id == null ? '' : String(f.id);
       const key = idToKey[id];
       if (!key) continue; // a geo feature with no manifest entry is skipped
@@ -147,7 +152,40 @@ export function loadRegions(root: string): boolean {
       }
     }
 
-    data = { idToKey, keyToInfo, keysByCountry, validKeys, adjacency, centroids };
+    // The region-geo manifest (v0.28, #46): area (km²) + population per region
+    // key — the weighting source for the per-region stats model. OPTIONAL like
+    // the others: a missing/broken file means "no geo data", and weighting
+    // degrades to uniform (every region weight 1) while everything else keeps
+    // working.
+    let geo: Record<string, { area: number; population: number }> = {};
+    const geoDataPath = path.join(base, regionGeoFile);
+    if (existsSync(geoDataPath)) {
+      try {
+        const raw = JSON.parse(readFileSync(geoDataPath, 'utf8')) as Record<
+          string,
+          { area?: unknown; population?: unknown }
+        >;
+        // Keep only well-formed entries; a corrupt file degrades to "none".
+        for (const [k, v] of Object.entries(raw)) {
+          if (
+            v &&
+            typeof v.area === 'number' &&
+            Number.isFinite(v.area) &&
+            v.area >= 0 &&
+            typeof v.population === 'number' &&
+            Number.isFinite(v.population) &&
+            v.population >= 0
+          ) {
+            geo[k] = { area: v.area, population: v.population };
+          }
+        }
+      } catch (err) {
+        console.error('[regions] failed to load region-geo.json, continuing without it', err);
+        geo = {};
+      }
+    }
+
+    data = { idToKey, keyToInfo, keysByCountry, validKeys, adjacency, centroids, geo };
     return validKeys.size > 0;
   } catch (err) {
     console.error('[regions] failed to load region data', err);
@@ -241,6 +279,16 @@ export function hasCentroids(): boolean {
   return data !== null && Object.keys(data.centroids).length > 0;
 }
 
+/**
+ * True when the region-geo manifest loaded with at least one entry (v0.28,
+ * #46). The server's jump route uses this to decide whether to hand the
+ * engine a geo resolver (which weights the per-region stats derivation by
+ * area×population) or fall back to a uniform (unweighted) median.
+ */
+export function hasGeo(): boolean {
+  return data !== null && Object.keys(data.geo).length > 0;
+}
+
 /**
  * The precomputed anchor point for a region key: the centroid of its
  * largest-area part, plus a `spread` (≈ 0.1 × that part's smallest bbox
@@ -252,6 +300,16 @@ export function centroidOf(key: string): { lat: number; lon: number; spread: num
   return data?.centroids[key];
 }
 
+/**
+ * The precomputed area (km²) + population for a region key (v0.28, #46) — the
+ * weighting source for the per-region stats model. `undefined` for an unknown
+ * key or when no geo data is loaded (the derivation then falls back to a
+ * uniform weight of 1 for that region).
+ */
+export function geoOf(key: string): { area: number; population: number } | undefined {
+  return data?.geo[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