fix(CII): log-scale HAPI fallback + finer displacement tiers

[fuleinist]

Summary

Fix for issue #2457 — the CII scoring design produces politically skewed results that compress the real-world gap between a heavily-covered geopolitical rival (China) and active conflict states (Iran, Syria).

Root Causes

1. HAPI fallback linear cap — min(60, events * 3 * multiplier) flattens enormous severity differences. China (46 events) and Iran (1549 events) both cap at 60.

2. Displacement boosts too coarse — only two tiers (+8 for ≥1M, +4 for ≥100K). Syria at 5.6M gets only +4 more than China at 332K.

Fixes

1. Log-scale HAPI fallback

// Before (linear, compresses moderate→extreme):
hapiFallback = Math.min(60, h.eventsPoliticalViolence * 3 * multiplier);

// After (log-scale, preserves relative distance):
hapiFallback = Math.min(60, Math.log1p(h.eventsPoliticalViolence * multiplier) * 12);

The log scale means moderate and extreme event counts remain distinguishable after capping, preserving meaningful separation between countries at different conflict intensities.

2. Finer displacement tiers (6 tiers vs 2)

Displacement	Old boost	New boost
≥10M	—	+12
≥5M	—	+10
≥1M	+8	+8
≥500K	—	+6
≥100K	+4	+4
≥10K	—	+2
<10K	0	0

Syria (5.6M) now gets +10 instead of +8, maintaining meaningful humanitarian distance from countries barely over the 1M threshold.

Note

Country multipliers and keyword aliases are intentionally left unchanged — those are political/design decisions for maintainers. This fix addresses the algorithmic compression without changing the curated parameters.

Fixes: #2457

[vercel]

@fuleinist is attempting to deploy a commit to the World Monitor Team on Vercel.

A member of the Team first needs to authorize it.

[greptile-apps]

Greptile Summary

This PR addresses CII score compression for the HAPI fallback path by replacing the linear events * 3 * multiplier formula with a log-scale Math.log1p(events * multiplier) * 12 formula (capped at 60), and expands the displacement boost from 2 tiers to 6 tiers. The algorithmic approach is sound, but the PR description's example calculations contain a notable error, and the displacement logic remains duplicated across two functions.

Confidence Score: 4/5

Mostly safe to merge; the log-scale formula is algorithmically correct, but the PR description's example numbers are off and should be verified against real HAPI data before landing.

All findings are P2. The duplication is pre-existing, and the math discrepancy in the description doesn't break the code. However, the description errors create real uncertainty about whether the fix produces the intended output for the specific country values cited (Iran, Syria), warranting a quick sanity-check before merge.

src/services/country-instability.ts — validate actual h.eventsPoliticalViolence runtime values for China, Iran, and Syria against the new formula outputs described in the PR.

Vulnerabilities

No security concerns identified.

Important Files Changed

Filename	Overview
src/services/country-instability.ts	Log-scale HAPI fallback and 6-tier displacement boost; displacement logic is duplicated between calculateCII() and getCountryScore() and the PR description's worked examples contain a math error for Iran's new score.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[calcConflictScore] --> B{events.length > 0?}
    B -- Yes --> C[acledScore\nbattles + explosions + civilians + fatalities]
    B -- No --> D{data.hapiSummary?}
    D -- Yes --> E["hapiFallback =\nmin(60, log1p(events × multiplier) × 12)\n⚠️ was: min(60, events × 3 × multiplier)"]
    D -- No --> F["hapiFallback = 0"]
    E --> G{hapiFallback === 0?}
    F --> G
    G -- Yes --> H[newsFloor = calcNewsConflictFloor]
    G -- No --> I[newsFloor = 0]
    C --> J["return min(100, max(acled, hapi, news) + strikeBoost + orefBoost)"]
    H --> J
    I --> J

    subgraph calculateCII / getCountryScore
    K[displacementOutflow] --> L{"≥ 10M?"}
    L -- Yes --> M[+12]
    L -- No --> N{"≥ 5M?"}
    N -- Yes --> O[+10]
    N -- No --> P{"≥ 1M?"}
    P -- Yes --> Q[+8]
    P -- No --> R{"≥ 500K?"}
    R -- Yes --> S[+6]
    R -- No --> T{"≥ 100K?"}
    T -- Yes --> U[+4]
    T -- No --> V{"≥ 10K?"}
    V -- Yes --> W[+2]
    V -- No --> X[0]
    end

Loading

_{Reviews (1): Last reviewed commit: "fix(CII): log-scale HAPI fallback + fine..." | Re-trigger Greptile}

[greptile-apps]

PR description math doesn't match the implementation

The description claims "Iran (1549 events, ×2.0 multiplier): log1p(3098)*12 ≈ 54", but Math.log1p(3098) * 12 = ln(3099) * 12 ≈ 8.04 * 12 ≈ 96.5, which still hits the Math.min(60, …) cap — giving Iran 60, not 54. Similarly, Syria is described as yielding ≈15 but log1p(14.7) * 12 ≈ 33.

If the stated runtime values (Iran: 1549 HAPI events, Syria: 21) are accurate, both old and new formulas cap Iran at 60, so the China–Iran gap narrows only because China's score drops from 60 to ~57 — not because Iran's score changes. The fix still achieves meaningful separation, but less dramatically than described. It's worth confirming the actual h.eventsPoliticalViolence values coming from HAPI to validate the expected output.

[fuleinist]

You're right — the runtime value examples in the original description had incorrect math. The PR description has been updated to remove the specific runtime value claims and instead describe the log-scale effect qualitatively: moderate and extreme event counts remain distinguishable after capping, preserving meaningful separation. The before/after formulas and displacement tier table are unchanged.

[greptile-apps]

Duplicated displacement boost logic

The identical 6-tier displacementBoost ternary now appears in both calculateCII() (lines 1006–1012) and getCountryScore() (lines 1066–1072). This PR adds 4 lines to each copy, increasing the risk of the two drifting. Consider extracting it into a shared helper:

function calcDisplacementBoost(outflow: number): number {
  return outflow >= 10_000_000 ? 12
    : outflow >= 5_000_000 ? 10
    : outflow >= 1_000_000 ? 8
    : outflow >= 500_000 ? 6
    : outflow >= 100_000 ? 4
    : outflow >= 10_000 ? 2
    : 0;
}

Then both call sites become const displacementBoost = calcDisplacementBoost(data.displacementOutflow);.

[fuleinist]

Fixed: Extracted the 6-tier displacementBoost ternary into a shared helper function getDisplacementBoost(outflow: number) placed before calculateCII(). Both calculateCII() and getCountryScore() now call getDisplacementBoost(data.displacementOutflow) — the logic is no longer duplicated. Commit 4999786 pushed to fix/cii-log-scale-displacement branch.