CII Risk Scoring Methodology

v8 (2026-06-06). Fixed dead UCDP conflict-floor attribution. The server scorer read non-existent intensity_level / type_of_violence fields from the cached conflict:ucdp-events:v1 feed (whose rows actually carry violenceType / deathsBest / dateStart), so UCDP never applied its war (floor 70) / minor (floor 50) score floor and never counted toward /api/health.riskScores realtime signal coverage. UCDP is now classified per country over a 2-year trailing window (war when total deaths > 1000 or event count > 100; minor when event count > 10), matching the frontend deriveUcdpClassifications heuristic. The classifier is configured for that 2-year window, but the Redis writers currently fetch the newest six UCDP pages and retain at most 2,000 mapped events from a 365-day trailing slice. The relay /ucdp-events reader can fetch up to 12 pages, but it applies the same 365-day filter. Live scoring is therefore seed-input-bounded until UCDP retention is widened with production API-volume and Redis-payload safeguards. The health coverage metric’s conflict family is now satisfied by EITHER the ACLED API path OR UCDP, so a thin/empty ACLED window no longer flips health to COVERAGE_PARTIAL while UCDP is healthy. See Country Instability Index for the current ACLED-or-UCDP health coverage semantics. combinedScore values rise for active UCDP conflict countries (e.g. UA/PK/MX gain a war floor); the risk-score cache key family moved to risk:scores:sebuf:v8 and emitted methodology_version is now v8, so clients pinned on methodology_version should re-baseline.

v8 amendment (2026-06-07). Source discovery and observability were clarified without changing scoring coefficients, CII formula version, or risk:scores:sebuf:v8 cache keys. The UCDP seeder now prefers the newest GED release that returns events instead of stopping at the first responding version (#4200), and the CII refresh path warns when ACLED returns zero events for both comparison windows so operators can distinguish a quiet feed from an auth/upstream gap.

v7 (2026-06-06). Score attribution changed for the second CII gap-closure batch. Coordinate attribution now handles three-way bbox overlaps before pairwise border rules, so Punggye-ri resolves to KP instead of CN and Lublin resolves to PL instead of UA; the seed mirror uses the same resolver. Targeted rectangular-bbox probes were added for Lhasa, Gaziantep, Kermanshah, Quetta, Islamabad, Dammam, Tabuk, Ruili, Belogorsk, north Hokkaido, and Amman. Climate anomaly boosts now cover the producer-emitted Europe, East Asia, and Latin America zones, restoring boost coverage for KP/KR/JP/PL/DE/FR/GB/VE, and unknown future zone names can fall back through anomaly coordinates when present. combinedScore values can shift where affected records were previously attributed to the wrong country or ignored. The risk-score cache key family moved to risk:scores:sebuf:v7; clients pinned on methodology_version should re-baseline. Remaining coordinate attribution is still a rectangular approximation, not full point-in-polygon border geometry.

v6 (2026-06-06). Score attribution changed for country text, coordinate, and climate anomaly inputs. Text attribution now recognizes north korean as KP and taiwanese as TW while still rejecting ambiguous bare korean. Coordinate attribution keeps the seed and server in parity for high-value overlap zones: Rio Grande US/MX border segments, the western Korean DMZ, RU/UA, IN/PK, CN/RU and RU/JP. Climate anomaly boosts now consume the zone names emitted by the climate producer (Ukraine, California, Amazon, Taiwan Strait, Caribbean, etc.) and map enum severities into the numeric boost scale. combinedScore values can shift where affected military, fire, GPS, earthquake, news, or climate records were previously attributed to the wrong country or ignored. The risk-score cache key family moved to risk:scores:sebuf:v6; clients pinned on methodology_version should re-baseline.

v5 (2026-06-06). dynamicScore is now a signed movement delta in the range -100..100, derived from a valid CII snapshot from approximately 24 hours earlier. Positive values mean the country score rose, negative values mean it fell, and 0 means stable or no valid prior snapshot. The server trend label uses a strict one-point deadband: whole-point score changes of +1 or -1 remain stable, while +2 and -2 are the first rising/falling labels. The browser fallback uses the same trend deadband. combinedScore coefficients are unchanged by this bump, but API clients that previously treated dynamicScore as a non-negative live score should re-baseline.

v4 (2026-06-06). Attribution and source-input semantics changed while keeping the published coefficient table intact. Country text attribution now uses normalized token exact-match / phrase matching instead of raw substring matches, coordinate attribution routes known bounding-box overlaps through explicit border heuristics, the earthquake seed uses the USGS 4.5-week (4.5_week) feed, and sanctions scoring reads the full country-count map from sanctions:country-counts:v1 instead of relying on the top-pressure display list. combinedScore values can shift where these sources previously misattributed or omitted country pressure; clients pinned on methodology_version should re-baseline.

v3 (2026-05-27). Conflict event activity now uses a log-scaled curve before the final component cap (cap = 70, pivot = 4000), replacing the earlier linear early cap that could compress moderate and extreme political-violence volumes into the same component value. The browser-side legacy CII path now uses the same displacement log-ramp as the server (100K ≈ +4, 500K ≈ +10, 1M ≈ +12, 5M ≈ +18, 10M+ = +20) instead of the old two-tier +4/+8 boost. Browser news-alert pressure is no longer multiplied by per-country eventMultiplier; it remains an Information component signal, not a country-tuned proxy for domestic instability. Clients pinned on methodology_version should re-baseline.

Implementation note (2026-05-27). baselineRisk and eventMultiplier now come from one shared coefficient table used by both the server and frontend. This resolves the 7-country drift tracked in #3789 by keeping the previously published server/API values for AF, EG, IQ, JP, KR, LB and QA. Frontend client-side CII rendering now uses those same values. Server/API values were unchanged by this refactor — the v3 bump above is from the calibration changes, not this source-of-truth move.

v2 (2026-05-22). The Security component is no longer GPS-jamming-only — it now scores military flights, military vessels and aviation disruptions alongside GPS jamming (issue #3738). The composite blend gains newsUrgencyBoost, earthquakeBoost, sanctionsBoost and an AIS-disruption boost, and cyberBoost/fireBoost are now severity-weighted rather than raw counts. combinedScore values shift accordingly — clients pinned on methodology_version should re-baseline.

Heads up — score contract changes. Any edit that changes server/API per-country baselines, event multipliers, strategic-risk roll-up coefficients, inline server formula literals, guarded top-level formula constants, or CII movement semantics MUST come with a bump of CII_FORMULA_VERSION in server/worldmonitor/intelligence/v1/_risk-config.ts, an update to this document in the same commit, and a public CHANGELOG entry. Source-of-truth refactors that preserve server/API scores do not bump the wire version. Tests in tests/cii-scoring.test.mts enforce that this document lists every country code in CURATED_COUNTRIES.

​

1. The four CII components

eventScore = U * 0.25 + C * 0.30 + S * 0.20 + I * 0.25

composite = baseline * 0.4
          + eventScore * 0.6
          + climateBoost      (≤ 15)
          + cyberBoost        (≤ 12, severity-weighted)
          + fireBoost         (≤  8, high-fire weighted)
          + advisoryBoost     (≤ 15)
          + orefBlendBoost    (IL only, ≤ 25)
          + displacementBoost (≤ 20)
          + newsUrgencyBoost  (≤  5)
          + earthquakeBoost   (≤ 25)
          + sanctionsBoost    (≤ 14)
          + aisBoost          (≤ 10, AIS disruptions)

• Unrest severity boost: high-severity ACLED unrest events (for example, riots) add min(20, highSeverityUnrest * 10 * eventMultiplier) inside the Unrest component.
• Conflict civilian boost: violence-against-civilians events add min(10, civilianViolence * 3) after the log-scaled conflict activity and fatality terms.
• Iran-region strike boost: geocoded Iran-event strikes, or title/location fallback matches from the same feed, add min(50, iranStrikes * 3 + highSeverityStrikes * 5) inside the Conflict component. High and critical severity strikes therefore count twice: once in the per-strike term and once in the high-severity term. This feed is a theatre-intensity input, not a full armed-conflict casualty source; ACLED and UCDP remain the general conflict anchors.
• Conflict OREF boost: for Israel only, active OREF rocket-alert pressure adds 25 + min(25, activeAlertCount * 5) inside the Conflict component, so the component-level OREF contribution is capped at +50. This is separate from the composite orefBlendBoost term listed above, which is also Israel only and capped at +25.
• Information severity handling: classified top stories use weights critical = 4, high = 2, medium/elevated = 1, moderate/low = 0.5, and info = 0. The per-country threat-summary feed uses critical = 4, high = 2, medium = 1, low = 0.5, and info = 0, with that threat-summary sub-score capped at 20; the combined Information component is capped at 100.

• UCDP floor: 70 if a UCDP war-level event is active, 50 if a minor conflict-level event is active, else 0.
• State Department advisory floor: 60 for “do not travel”, 50 for “reconsider travel”, else 0.

​

Advisory fallback table

​

Text attribution caveat

​

2. Per-country baselineRisk and eventMultiplier

​

Fairness rationale for curated parameters

• eventMultiplier is an observability and signal-confidence adjustment for verified event inputs. It should not be used to amplify generic news attention or geopolitical salience.
• Search aliases used for discovery can be broader than scoring keywords. Broad theater phrases such as strategic waterways or cross-border disputes should not by themselves be treated as domestic instability evidence for a country unless a scored event source also attributes the signal there.
• The Information component measures news pressure and classified headline salience. It is allowed to move the composite, but it is separated from the Conflict component wherever the available schema permits.
• Humanitarian displacement is intentionally log-ramped rather than two-tiered so six-figure displacement, million-person crises, and multi-million-person crises do not collapse into nearly identical boosts.

​

3. Strategic Risk roll-up

top5         = ciiScores.slice(0, STRATEGIC_RISK_TOP_N)            # N = 5
weights      = [1.00, 0.85, 0.70, 0.55, 0.40]                       # 1 - i * 0.15
weightedAvg  = Σ(score_i * weight_i) / Σ(weight_i)
overallScore = min(100, round(weightedAvg * 0.70 + 15))             # banded to [15, 85]

• STRATEGIC_RISK_POSITIONAL_DECAY = 0.15 — the most-affected country gets full weight; the next four positions decay to 0.85, 0.70, 0.55, and 0.40. The next 1-based position 6 (0-based index 5) would still carry 0.25, so the explicit top-5 window, not a zero-weight cutoff, bounds the roll-up.
• STRATEGIC_RISK_TOP_N = 5 — large enough to dilute single-country spikes, small enough that the score reflects the “very top” of the dashboard rather than a long tail.
• STRATEGIC_RISK_SCALE_FLOOR = 15 — the global picture is never “all clear”. A baseline of 15 keeps the dial visually meaningful when every Tier-1 country is calm.
• STRATEGIC_RISK_SCALE_FACTOR = 0.70 — combined with the floor, this compresses the weighted top-5 average from [0, 100] into [15, 85] before the final min(100). Prevents a single very-high country from saturating the global score.

• SEVERITY_LEVEL_HIGH if overallScore ≥ 70
• SEVERITY_LEVEL_MEDIUM if 40 ≤ overallScore < 70
• SEVERITY_LEVEL_LOW if overallScore < 40

​

4. What this score is and is not