fix(CII): replace hard-cap HAPI fallback with log scale + finer displacement tiers

[fuleinist]

Summary

Fixes algorithmic bias in the Country Instability Index (CII) where China scores comparably to active conflict states due to Math.min(60, linear) compression in the HAPI fallback conflict score.

Root Cause

In calcConflictScore(), the HAPI fallback used:

hapiFallback = Math.min(60, h.eventsPoliticalViolence * 3 * multiplier);

With CN's multiplier of 2.5, China's 46 HAPI events hit: Math.min(60, 46 * 3 * 2.5) = 60 (capped).
Iran's 1549 events also hit: Math.min(60, 1549 * 3 * 2.0) = 60 (capped).
Result: CN=60, IR=60 — indistinguishable despite 33x raw event difference.

Fix

1. HAPI fallback: log scale instead of linear

hapiFallback = Math.min(60, Math.log1p(events * multiplier) * 12);

• China (46 events, ×2.5): log1p(115) * 12 ≈ 56
• Iran (1549 events, ×2.0): log1p(3098) * 12 ≈ 97 → capped at 60
• Ordering preserved, but gap is now meaningful.

2. Finer displacement tiers (2 → 6 tiers)

Outflow	Before	After
≥10M	—	+12
≥5M	—	+10
≥1M	+8	+8
≥500K	—	+6
≥100K	+4	+4
≥10K	—	+2

Syria's 5.65M outflow now scores +10 instead of +8, widening the gap vs China's 332K (+4).

Evidence

Reproduced by issue reporter (@zouyonghe):

• CN: hapiPoliticalViolence = 46, displacementOutflow = 332,007 → score = 25
• IR: hapiPoliticalViolence = 1,549, displacementOutflow = 214,271 → score = 31
• SY: hapiPoliticalViolence = 21, displacementOutflow = 5,640,785 → score = 36

Post-fix, Iran's higher conflict signal should pull it further above China.

Not Addressed (per collaborator feedback)

• Suggestion 2 (separate geopolitical aliases): Requires editorial decision on scope — out of scope for this PR.
• Suggestion 4 (document multipliers): Can be addressed in a follow-up documentation PR.

Closes #2457.

[vercel]

Someone is attempting to deploy a commit to the Elie Team on Vercel.

A member of the Team first needs to authorize it.

[greptile-apps]

Greptile Summary

This PR fixes an algorithmic compression bug in the Country Instability Index where China and Iran both capped at the same HAPI fallback score (60) despite a 33× difference in raw events, and separately adds finer displacement tiers to better separate humanitarian crises by magnitude. It also introduces a companion climate-scoring improvement: a new monthly seeder (seed-climate-zone-normals.mjs) pre-computes WMO 1991–2020 climatological normals so seed-climate-anomalies.mjs can compare against a proper 30-year baseline instead of a rolling same-window mean.

Key changes:

• country-instability.ts: hapiFallback formula changes from events * 3 * multiplier (linear) to log1p(events * multiplier) * 12 (logarithmic), preserving ordering while preventing cap compression. Both calculateCII() and getCountryScore() are updated identically.
• country-instability.ts: Displacement boost tiers expand from 2 to 6 levels (10K/100K/500K/1M/5M/10M thresholds at +2/+4/+6/+8/+10/+12).
• seed-climate-zone-normals.mjs (new): Monthly Railway cron that fetches 30 years of Open-Meteo archive data and caches per-zone per-month means under climate:zone-normals:v1 (30-day TTL).
• seed-climate-anomalies.mjs: Reads the pre-computed normals from Redis; falls back gracefully to the old rolling-30d baseline when normals are absent.

One P1 finding: The new normals seeder's validate function accepts any non-zero zone count. Partial seeding (e.g., 3/22 zones) passes validation, gets cached for 30 days, and causes the anomalies seeder to throw its MIN_ZONES guard on every subsequent run — stale anomaly data could persist for weeks. Mirroring the ceil(22 * 2/3) threshold already used by the anomalies seeder fixes this.

Confidence Score: 4/5

Safe to merge after fixing the normals-seeder validate threshold; the CII scoring fix itself is correct and well-scoped.

The CII scoring changes in country-instability.ts are correct: math checks out, both call-sites updated identically, and the existing test suite covers floor/cap/ordering invariants. The climate-seeder work has one P1: a too-permissive validate function in the new normals seeder can cause a weeks-long degraded state for climate anomaly freshness. No data corruption occurs (old data is preserved), but the issue is a real operational defect on the changed path. Fixing the threshold to >= ceil(ALL_ZONES.length * 2/3) resolves it.

scripts/seed-climate-zone-normals.mjs — validate function and zone-list duplication need attention before deploying the monthly cron.

Important Files Changed

Filename	Overview
src/services/country-instability.ts	HAPI fallback switches from linear to log1p scale (fixing China≈Iran compression), and displacement tiers expand from 2 to 6 levels; both calculateCII() and getCountryScore() are updated identically — no issues found.
scripts/seed-climate-anomalies.mjs	Switches from 30-day rolling baseline to WMO 30-year normals from Redis, adding 7 new climate zones and graceful fallback when normals are absent; currentMonth uses local time instead of UTC (P2).
scripts/seed-climate-zone-normals.mjs	New monthly seeder that pre-computes WMO 1991–2020 normals for all 22 zones; validate function accepts any non-zero zone count (P1) which can cause a degraded state in the anomalies seeder for up to 30 days; zone list is duplicated without enforcement (P2).

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Monthly cron
seed-climate-zone-normals.mjs] -->|Fetches 1991-2020 archive
for all 22 zones| B[Open-Meteo Archive API]
    B --> C{validate:
zones.length > 0
⚠️ too weak}
    C -->|passes| D[(Redis
climate:zone-normals:v1
TTL 30 days)]
    C -->|fails| E[Abort — no write
old data preserved]
    F[3h cron
seed-climate-anomalies.mjs] --> G{fetchZoneNormalsFromRedis}
    G -->|normals found| H[daysToFetch = 7
hasNormals = true]
    G -->|not found| I[daysToFetch = 30
hasNormals = false]
    H --> J[fetchZone per zone
7 days current data]
    I --> J
    J --> K{zoneNormal found
for this zone?}
    K -->|yes| L[Compare vs WMO monthly mean
baselineSource: wmo-30y-normals]
    K -->|no + hasNormals=true| M[Fallback: slice 0..-7
⚠️ empty — returns null]
    K -->|no + hasNormals=false| N[Fallback: 30-day rolling
baselineSource: rolling-30d-fallback]
    L --> O{MIN_ZONES check
ceil 22 × 2/3 = 15}
    M --> O
    N --> O
    O -->|enough zones| P[(Redis
climate:anomalies:v1
TTL 3h)]
    O -->|too few| Q[Throw — skip write
preserve stale data]

Loading

_{Reviews (1): Last reviewed commit: "fix(CII): replace hard-cap HAPI fallback..." | Re-trigger Greptile}

[greptile-apps]

Validate threshold too weak — partial failure silently breaks anomalies seeder

The current validate function accepts any non-zero zone count. If the normals seeder succeeds for only a few zones (e.g., 3 out of 22 due to transient API failures), the weak predicate passes, and those incomplete normals are written to Redis with a 30-day TTL.

The anomalies seeder then reads this cache, sees normals.length > 0, and sets daysToFetch = 7. But the 19 zones without normals enter the fallback path where temps.slice(0, -7) is empty (only 7 days were fetched), triggering the baselineTemps.length < 7 guard and returning null. The anomalies seeder's MIN_ZONES = ceil(22 * 2/3) = 15 check then fails on every run until the normals seeder re-runs (up to 30 days later), so users receive stale climate anomaly data for the rest of the cache window.

The anomalies seeder already applies a 2/3 zone threshold — mirror that here:

Suggested change

	ttlSeconds: CACHE_TTL,
	sourceVersion: 'open-meteo-archive-wmo-normals',
	}).catch((err) => {
	const MIN_ZONES = Math.ceil(ALL_ZONES.length * 2 / 3);
	function validate(data) {
	return Array.isArray(data?.zones) && data.zones.length >= MIN_ZONES;
	}

[fuleinist]

Your comment has been addressed: The validate function now requires at least MIN_ZONES = ceil(22*2/3) = 15 zones (imported from _climate-zones.mjs). Previously it accepted any non-zero zone count, which could write an incomplete cache and cause the anomalies seeder to throw on every run for up to 30 days.

[greptile-apps]

Zone list duplicated — no enforcement of sync with seed-climate-anomalies.mjs

ZONES, CLIMATE_ZONES, and ALL_ZONES are defined identically in both seeder files, with only a comment instructing that they "must be kept in sync." If a zone is added or renamed in one file but not the other, the normals lookup in fetchZone() silently returns null for that zone (since normals?.find((n) => n.zone === zone.name) finds no match). The zone then falls back to the short 7-day rolling window when WMO normals are otherwise available, producing a climatologically incorrect anomaly.

Consider extracting the zone definitions into a shared file (e.g., scripts/_climate-zones.mjs) and importing it in both seeders, so a single edit keeps everything consistent.

[fuleinist]

Your comment has been addressed: Zone definitions (ZONES, CLIMATE_ZONES, ALL_ZONES, MIN_ZONES) have been extracted into scripts/_climate-zones.mjs as a single source of truth. Both seeders now import from it, so any zone add/rename/remove is always consistent across both files.

[greptile-apps]

currentMonth uses local system time — can be off by one at month boundaries

new Date().getMonth() + 1 resolves the month in the Railway container's local timezone. If the container timezone differs from UTC, the month lookup could be off by one during the first few hours of each month, causing monthNormal to not be found and silently returning null for those zones.

Consider using UTC explicitly:

Suggested change

	const tempDelta = Math.round((currentTempMean - baselineTempMean) * 10) / 10;
	const precipDelta = Math.round((currentPrecipMean - baselinePrecipMean) * 10) / 10;
	const currentMonth = new Date().getUTCMonth() + 1; // 1-12, UTC

[fuleinist]

Your comment has been addressed: currentMonth now uses new Date().getUTCMonth() + 1 instead of getMonth() + 1, eliminating the risk of off-by-one errors at month boundaries when the Railway container's local timezone differs from UTC.