---
title: "Algorithms & Scoring"
description: "Detailed documentation of World Monitor's scoring formulas, detection algorithms, and classification pipelines."
---

---

## Country & Regional Scoring

### Country Instability Index (CII)

Every Tier-1 country receives a live instability score (0-100). CII v8 tracks 31 Tier-1 countries with shared server/frontend `baselineRisk` and `eventMultiplier` coefficients plus signed 24-hour movement deltas: US, Russia, China, Ukraine, Iran, Israel, Taiwan, North Korea, Saudi Arabia, Turkey, Poland, Germany, France, UK, India, Pakistan, Syria, Yemen, Myanmar, Venezuela, Cuba, Mexico, Brazil, UAE, South Korea, Iraq, Afghanistan, Lebanon, Egypt, Japan, and Qatar. Countries outside the curated Tier-1 set use the default editorial coefficients when they are scored by supporting systems (`DEFAULT_CII_BASELINE_RISK = 15`, `DEFAULT_CII_EVENT_MULTIPLIER = 1.0`).

Authoritative CII scores come from the server-side `GET /api/intelligence/v1/get-risk-scores` RPC (`server/worldmonitor/intelligence/v1/get-risk-scores.ts`) and are served to the browser through the cached risk-score feed. The frontend `country-instability.ts` path shares the published `baselineRisk` / `eventMultiplier` coefficients and v3 conflict curve constants, but it is a fallback/local renderer path after cached backend scores, not the source of truth for published scores:

| Component            | Weight | Details |
| -------------------- | ------ | ------- |
| **Baseline risk**    | 40%    | Pre-configured per country reflecting structural fragility (0-50 scale) |
| **Event score**      | 60%    | Blend of Unrest (25%), Conflict (30%), Security (20%), Information (25%) |

**Unrest score** (0-100): Log2 dampening for high-volume low-multiplier countries (`multiplier &lt; 0.7`), linear otherwise. Base capped at 50, plus protest/riot fatality boost (up to 30), plus outage severity boost (TOTAL: 30pts, MAJOR: 15pts, PARTIAL: 5pts, capped at 50).

**Conflict score** (0-100): Weighted ACLED activity (battles x3, explosions x4, civilian violence x5, multiplied by `eventMultiplier`) is log-scaled with the v3 curve `min(70, log1p(rawActivity) / log1p(4000) * 70)` before additional boosts. Sqrt-scaled fatalities contribute up to 40, civilian targeting up to 10, Iran strike severity up to 50, and OREF alerts for Israel add 25 base + 5 per active alert up to 50 total. Rolling 24-hour OREF history contributes through the Israel blend boost described below.

**Security score** (0-100): Military flights (3pts each, capped at 50), military vessels (5pts each, capped at 30), aviation closures/delays (severity-weighted, capped at 40), and GPS/GNSS jamming (high: 5pts, medium: 2pts per hex, capped at 35). Foreign military presence is weighted ×2.

**Information score** (0-100): Country-attributed classified news pressure from top-story country attribution and threat summaries. Critical/high/medium headlines contribute with descending weights; info-level headlines do not move the score.

**Floors**: UCDP active war pins score at >= 70, UCDP minor conflict at >= 50. Travel advisory do-not-travel pins at >= 60, reconsider at >= 50. Advisory floors and boosts use the live advisory feed when available; otherwise the server may apply the embedded State Department fallback table. Each `CiiScore` exposes `advisoryLevel` plus `advisoryProvenance` (`live`, `fallback`, or `absent`) so clients can tell which path affected the score. UCDP floors read from the **latest** UCDP GED release (the seeder picks the newest version returning events, not the first to respond) and only count Tier-1 events within a **2-year recency window**; within that window, war means total deaths > 1000 or event count > 100, and minor conflict means event count > 10 below the war thresholds. Since UCDP GED is an annual, lagging dataset, recent conflict is driven by the real-time ACLED feed. The `riskScores` health/cache signal-density check counts three realtime families — conflict (ACLED **or** recent UCDP), news, and cyber — and reads `COVERAGE_PARTIAL` if any family has no Tier-1 signal (e.g. ACLED auth missing while UCDP is out of window).

**Boosts**: Advisory boost (+15 do-not-travel, +10 reconsider, +5 caution), OREF blend boost for Israel (+15 active alerts, +5/10 based on 24h history count), climate severity (up to +15), cyber threats (up to +12), wildfires (up to +8), displacement (up to +20), news urgency (up to +5), earthquakes (up to +25), sanctions (up to +14), and AIS disruptions (up to +10).

See [CII Risk Scoring Methodology](/methodology/cii-risk-scores) for the published per-country `baselineRisk` and `eventMultiplier` tables, the v8 formula, and the strategic-risk band derivation.

### Hotspot Escalation Scoring

Intelligence hotspots receive dynamic escalation scores blending four normalized signals (0–100):

- **News activity** (35%) — article count and severity in the hotspot's area
- **Country instability** (25%) — CII score of the host country
- **Geo-convergence alerts** (25%) — spatial binning detects 3+ event types (protests + military + earthquakes) co-occurring within 1° lat/lon cells
- **Military activity** (15%) — vessel clusters and flight density near the hotspot

The dynamic raw score is converted from 0-100 onto the hotspot's 1-5 escalation
scale, then blended as `staticBaseline × 0.30 + dynamicScore × 0.70`.
`staticBaseline` is the hotspot config's `escalationScore` (default `3`) and
the dynamic component is the weighted news/CII/geo/military signal. Signal
emissions cool down for 2 hours and fire on whole-band upward crossings at
`>=2/5`, rapid increases of at least `0.5`, or first entry into the critical
band at `>=4.5/5`.

### Geographic Convergence Detection

Events (protests, military flights, vessels, earthquakes) are binned into 1°×1° geographic cells within a 24-hour window. When 3+ distinct event types converge in one cell, a convergence alert fires. Scoring is based on type diversity (×25pts per unique type) plus event count bonuses (×2pts, capped at 25). Current emitted alerts are high or critical priority: 4 types or score ≥90 is critical; 3-type alerts below 90 are high. Alerts are reverse-geocoded to human-readable names using conflict zones, waterways, and hotspot databases.

### Strategic Risk Score Algorithm

The Strategic Risk panel prefers the cached server-published Strategic Risk headline from `GET /api/intelligence/v1/get-risk-scores`. In cached mode, the authoritative `StrategicRisk[0]` score is the server roll-up of the top-5 CII `combinedScore` values with weights `[1.00, 0.85, 0.70, 0.55, 0.40]`, scale factor `0.70`, floor `15`, and server severity bands High >= 70, Medium 40-69, Low < 40.

When cached server scores are unavailable, the browser renders a local fallback overview that synthesizes locally available module data into temporary panel context. This panel-local context is useful for continuity during cache misses, but it is not the published Strategic Risk contract.

**Browser/local fallback composite formula**:

```
compositeScore =
    convergenceScore × 0.30     // multi-type events co-located in same 1° cell
  + ciiRiskScore     × 0.50     // CII top-5 country weighted blend
  + infraScore       × 0.20     // infrastructure cascade incidents
  + theaterBoost     (0–25)     // military asset density + strike packaging
  + breakingBoost    (0–15)     // breaking news severity injection
  + sanctionsScore   (0–10)     // sanctions pressure and targeted-asset activity
  + radiationScore   (0–12)     // radiation-watch spikes and corroboration
```

**Sub-scores**:

- `convergenceScore` — `min(100, convergenceAlertCount × 25)`. Each geographic cell with 3+ distinct event types contributing 25 points
- `ciiRiskScore` — Local fallback only: top 5 locally available country scores, weighted `[0.40, 0.25, 0.20, 0.10, 0.05]`, with a bonus of `min(20, elevatedCount × 5)` for each country above CII 50
- `infraScore` — `min(100, cascadeAlertCount × 25)`. Each infrastructure cascade incident contributing 25 points
- `theaterBoost` — For each theater posture summary: `min(10, floor((aircraft + vessels) / 5))` + 5 if strike-capable (tanker + AWACS + fighters co-present). Summed across theaters, capped at 25. Halved when posture data is stale
- `breakingBoost` — Critical breaking news alerts add 15 points, high adds 8, capped at 15. Breaking alerts expire after 30 minutes
- `sanctionsScore` — Up to 10 points from new sanctions entries, largest-country entry volume, and sanctioned vessel/aircraft counts
- `radiationScore` — Up to 12 points from radiation-watch spikes, elevated readings, and corroborated observations, reduced by low-confidence or conflicting observations

**Alert fusion**: Alerts from convergence detection, CII spikes (≥10-point change), infrastructure cascades, sanctions pressure, and radiation watch are merged when they occur within a 2-hour window and are within 200km or in the same country. Merged alerts carry the highest priority and combine summaries. Direct inserts pop the oldest alert after 50 entries; the Strategic Risk refresh path then sorts by newest timestamp and trims the recomputed queue to 100 entries after 24-hour pruning.

**Trend detection**: Delta ≥3 from previous composite = "escalating", ≤−3 = "de-escalating", otherwise "stable". A 15-minute learning period after panel initialization suppresses CII spike alerts to prevent false positives from initial data loading.

### Population Exposure Estimation

Active events (conflicts, earthquakes, floods, wildfires) are matched to the nearest centroid in the local 20-country priority population table and then estimated from `population / area` density. This is a coarse exposure approximation, not a live WorldPop lookup. Event-specific radii reflect typical impact footprints:

| Event Type      | Radius | Rationale                                |
| --------------- | ------ | ---------------------------------------- |
| **Conflicts**   | 50 km  | Direct combat zone + displacement buffer |
| **Earthquakes** | 100 km | Shaking intensity propagation            |
| **Floods**      | 100 km | Watershed and drainage basin extent      |
| **Wildfires**   | 30 km  | Smoke and evacuation perimeter           |

If an event falls outside the priority centroid table, the fallback density uses a synthetic `50,000,000 / 500,000 km2` country profile. The Population Exposure panel displays a summary header with total affected population and a per-event breakdown table.

---

## Military & Strategic

### Strategic Theater Posture Assessment

Nine operational theaters are continuously assessed for military posture escalation:

| Theater               | Key Trigger                                 |
| --------------------- | ------------------------------------------- |
| Iran / Persian Gulf   | Carrier groups, tanker activity, AWACS      |
| Taiwan Strait         | PLAAF sorties, USN carrier presence         |
| Baltic / Kaliningrad  | Russian Western Military District flights   |
| Korean Peninsula      | B-52/B-1 deployments, DPRK missile activity |
| Eastern Mediterranean | Multi-national naval exercises              |
| Horn of Africa        | Anti-piracy patrols, drone activity         |
| South China Sea       | Freedom of navigation operations            |
| Arctic                | Long-range aviation patrols                 |
| Black Sea             | ISR flights, naval movements                |

Posture levels escalate from NORMAL → ELEVATED → CRITICAL based on a composite of:

- **Aircraft count** in theater (both resident and transient)
- **Strike capability** — the presence of tankers + AWACS + fighters together indicates strike packaging, not routine training
- **Naval presence** — carrier groups and combatant formations
- **Country instability** — high CII scores for theater-adjacent countries amplify posture

Each theater is linked to 38+ military bases, enabling automatic correlation between observed flights and known operating locations.

### Military Surge & Foreign Presence Detection

The system monitors five operational theaters (Middle East, Eastern Europe, Western Europe, Western Pacific, Horn of Africa) with 38+ associated military bases. It classifies vessel clusters near hotspots by activity type:

- **Deployment** — carrier present with 5+ vessels
- **Exercise** — combatants present in formation
- **Transit** — vessels passing through

Foreign military presence is dual-credited: the operator's country is flagged for force projection, and the host location's country is flagged for foreign military threat. AIS gaps (dark ships) are flagged as potential signal discipline indicators.

### USNI Fleet Intelligence

The dashboard ingests weekly U.S. Naval Institute (USNI) fleet deployment reports and merges them with live AIS vessel tracking data. Each report is parsed for carrier strike groups, amphibious ready groups, and individual combatant deployments — extracting hull numbers, vessel names, operational regions, and mission notes.

The merge algorithm matches USNI entries against live AIS-tracked vessels by hull number and normalized name. Matched vessels receive enrichment: strike group assignment, deployment status (deployed / returning / in-port), and operational theater. Unmatched USNI entries (submarines, vessels running dark) generate synthetic positions based on the last known operational region, with coordinate scattering to prevent marker overlap.

This dual-source approach provides a more complete operational picture than either AIS or USNI alone — AIS reveals real-time positions but misses submarines and vessels with transponders off, while USNI captures the complete order of battle but with weekly lag.

### Aircraft Enrichment

Military flights detected via ADS-B transponder data are enriched through the Wingbits aviation intelligence API, which provides aircraft registration, manufacturer, model, owner, and operator details. Each flight receives a military confidence classification:

| Confidence    | Criteria                                                         |
| ------------- | ---------------------------------------------------------------- |
| **Confirmed** | Operator matches a known military branch or defense contractor  |
| **Likely**    | Aircraft type is exclusively military (tanker, AWACS, fighter)  |
| **Possible**  | Government-registered aircraft in a military operating area      |
| **Civilian**  | No military indicators detected                                 |

Enrichment queries are batched (up to 50 aircraft per request) and cached with a circuit breaker pattern to avoid hammering the upstream API during high-traffic periods. The enriched metadata feeds into the Theater Posture Assessment — a KC-135 tanker paired with F-15s and an E-3 AWACS indicates strike packaging, not routine training.

---

## Infrastructure

### Undersea Cable Health Monitoring

Beyond displaying static cable routes on the map, the system actively monitors cable health by cross-referencing two live data sources:

1. **NGA Navigational Warnings** — the U.S. National Geospatial-Intelligence Agency publishes maritime safety broadcasts that frequently mention cable repair operations. The system filters these warnings for cable-related keywords (`CABLE`, `CABLESHIP`, `SUBMARINE CABLE`, `FIBER OPTIC`, etc.) and extracts structured data: vessel names, DMS/decimal coordinates, advisory severity, and repair ETAs. Each warning is matched to the nearest cataloged undersea cable within a 5° geographic radius.

2. **AIS Cable Ship Tracking** — dedicated cable repair vessels (CS Reliance, Île de Bréhat, Cable Innovator, etc.) are identified by name pattern matching against AIS transponder data. Ship status is classified as `enroute` (transiting to repair site) or `on-station` (actively working) based on keyword analysis of the warning text.

Advisories are classified by severity: `fault` (cable break, cut, or damage — potential traffic rerouting) or `degraded` (repair work in progress with partial capacity). Impact descriptions are generated dynamically, linking the advisory to the specific cable and the countries it serves — enabling questions like "which cables serving South Asia are currently under repair?"

**Health scoring algorithm** — Each cable receives a status score computed from the strongest live signal after linear per-signal TTL decay:

```
recency_weight = clamp(1 - age_seconds / ttl_seconds, 0, 1)
effective      = severity * confidence * recency_weight
score          = round(max(effective) * 100) / 100
```

Signals are classified as `operator_fault`, `cable_advisory`, or `repair_activity`, each with its own severity, confidence, and TTL. A cable is marked `FAULT` when the top effective score is at least `0.80` and an operator-fault signal is present; `DEGRADED` when the top score is at least `0.50`, or at least `0.80` with repair activity; otherwise `OK`. Geographic matching uses cosine-latitude-corrected equirectangular distance to find the nearest cataloged cable within `555km` (about 5 degrees at the equator) of each NGA warning coordinate. Computed cable-health results are Redis-cached for `1800` seconds, and the NGA warning fetch is cached for `86400` seconds.

### Infrastructure Cascade Modeling

Beyond proximity correlation, the system models how disruptions propagate through interconnected infrastructure. A dependency graph connects undersea cables, pipelines, ports, chokepoints, and countries with weighted edges representing capacity dependencies:

```
Disruption Event → Affected Node → Cascade Propagation (BFS, depth ≤ 3)
                                          │
                    ┌─────────────────────┤
                    ▼                     ▼
            Direct Impact         Indirect Impact
         (e.g., cable cut)    (countries served by cable)
```

**Impact calculation**: `strength = edge_weight × disruption_level × (1 − redundancy)`

Strategic chokepoint modeling captures real-world dependencies:

- **Strait of Hormuz** — 80% of Japan's oil, 70% of South Korea's, 60% of India's, 40% of China's
- **Suez Canal** — EU-Asia trade routes (Germany, Italy, UK, China)
- **Malacca Strait** — 80% of China's oil transit

Ports are weighted by type: oil/LNG terminals (0.9 — critical), container ports (0.7), naval bases (0.4 — geopolitical but less economic). This enables questions like "if the Strait of Hormuz closes, which countries face energy shortages within 30 days?"

### Related Assets & Proximity Correlation

When a news event is geo-located, the system automatically identifies critical infrastructure within a 600km radius — pipelines, undersea cables, data centers, military bases, and nuclear facilities — ranked by distance. This enables instant geopolitical context: a cable cut near a strategic chokepoint, a protest near a nuclear facility, or troop movements near a data center cluster.

---

## News & Entity Analysis

### News Geo-Location

A 217-hub strategic location database infers geography from headlines via keyword matching. Hubs span capitals, conflict zones, strategic chokepoints (Strait of Hormuz, Suez Canal, Malacca Strait), and international organizations. Confidence scoring is boosted for critical-tier hubs and active conflict zones, enabling map-driven news placement without requiring explicit location metadata from RSS feeds.

### Entity Index & Cross-Referencing

A structured entity registry catalogs countries, organizations, world leaders, and military entities with multiple lookup indices:

| Index Type        | Purpose               | Example                                         |
| ----------------- | --------------------- | ----------------------------------------------- |
| **ID index**      | Direct entity lookup  | `entity:us` → United States profile             |
| **Alias index**   | Name variant matching | "America", "USA", "United States" → same entity |
| **Keyword index** | Contextual detection  | "Pentagon", "White House" → United States       |
| **Sector index**  | Domain grouping       | "military", "energy", "tech"                    |
| **Type index**    | Category filtering    | "country", "organization", "leader"             |

Entity matching uses word-boundary regex to prevent false positives (e.g., "Iran" matching "Ukraine"). Confidence scores are tiered by match quality: exact name matches score 1.0, aliases 0.85–0.95, and keyword matches 0.7. When the same entity surfaces across multiple independent data sources (news, military tracking, protest feeds, market signals), the system identifies it as a focal point and escalates its prominence in the intelligence picture.

### Headline Scoring

The AI Insights panel ranks news clusters by geopolitical significance using `scoreImportance` in `scripts/_clustering.mjs`. Rather than displaying stories in chronological order, the algorithm combines upstream classifier scores, source quality, corroboration, keyword groups, recency, and demotion rules:

| Signal | Scoring rule |
| --- | --- |
| **Upstream classifier** | `upstreamImportanceScore * 2.2` when present |
| **Threat level** | LLM-sourced threats add critical `+220`, high `+150`, medium `+80`, low `+20`; non-LLM threat scores contribute 35% only when backed by upstream signal and not keyword-historical downgrade |
| **Source tier** | Tier 1 `+35`, Tier 2 `+20`, Tier 3 `+8` |
| **Source count** | `min(sourceCount, 6) * 12` |
| **Entity corroboration** | `+45` when the cluster has corroborated entities |
| **Keyword groups** | Violence `+50 + 12/match`; military `+40 + 10/match`; unrest `+35 + 9/match`; flashpoint `+30 + 8/match`; diplomacy `+35 + 9/match`; crisis `+15 + 5/match` |
| **Flashpoint interaction** | Violence, unrest, or diplomacy terms combined with flashpoint terms multiply the score by `1.25` |
| **Recency** | A 16-hour linear recency multiplier bottoms out at `0.5` |

**Source confirmation boost** — source count and entity corroboration reward multi-source reporting over single-source reporting.

**Demotion keywords** — corporate and financial noise reduces scores to 35% when no corroborated entity or strong non-keyword signal is present, preventing business news from crowding out geopolitical developments in the full/geopolitical variant.

**Theater posture integration** — when the Strategic Posture Assessment detects elevated military activity (e.g., unusual flight patterns in a theater), related news stories receive additional scoring boosts, surfacing contextually relevant reporting alongside the military signal.

The scored list feeds into the World Brief generation pipeline, where the top-ranked stories are selected for LLM summarization. Server-side insights (via `seed-insights.mjs`) pre-compute the scored digest and cache it as `news:insights:v1` for bootstrap hydration, so the panel renders instantly with pre-ranked stories on page load.

### Trending Keyword Spike Detection

Every RSS headline is tokenized into individual terms and tracked in per-term frequency maps. A 2-hour rolling window captures current activity while a 7-day baseline (refreshed hourly) establishes what "normal" looks like for each term. A spike fires when all conditions are met:

| Condition            | Threshold                                     |
| -------------------- | --------------------------------------------- |
| **Absolute count**   | > `minSpikeCount` (5 mentions)                |
| **Relative surge**   | > baseline × `spikeMultiplier` (3×)           |
| **Source diversity** | ≥ 2 unique RSS feed sources                   |
| **Cooldown**         | 30 minutes since last spike for the same term |

The tokenizer extracts CVE identifiers (`CVE-2024-xxxxx`), APT/FIN threat actor designators, and 16 tracked world-leader names, including multi-word names such as "Xi Jinping" and "Kim Jong Un" that would be lost by naive whitespace splitting. A configurable blocklist suppresses common noise terms.

Detected spikes are auto-summarized via Groq (rate-limited to 5 summaries/hour) and emitted as `keyword_spike` signals into the correlation engine, where they compound with other signal types for convergence detection. The term registry is capped at 10,000 entries with LRU eviction to bound memory usage. All thresholds (spike multiplier, min count, cooldown, blocked terms) are configurable via the Settings panel.

### Temporal Baseline Anomaly Detection

Rather than relying on static thresholds, the system learns what "normal" looks like and flags deviations. Each event type (military flights, naval vessels, protests, news velocity, AIS gaps, satellite fires) is tracked per region with separate baselines for each weekday and month — because military activity patterns differ on Tuesdays vs. weekends, and January vs. July.

The algorithm uses **Welford's online method** for numerically stable streaming computation of mean and variance, stored in Redis with a 90-day rolling window. When a new observation arrives, its z-score is computed against the learned baseline. Thresholds:

| Z-Score | Severity      | Example                            |
| ------- | ------------- | ---------------------------------- |
| ≥ 1.5   | Medium        | Slightly elevated protest activity |
| ≥ 2.0   | High          | Unusual naval presence             |
| ≥ 3.0   | Critical      | Military flights 3x above baseline |

A minimum of 10 historical samples is required before anomalies are reported, preventing false positives during the learning phase. Anomalies are ingested back into the signal aggregator, where they compound with other signals for convergence detection.

### Breaking News Alert Pipeline

The dashboard monitors five independent alert origins and fuses them into a unified breaking news stream with layered deduplication, cooldowns, and source quality gating:

| Origin               | Trigger                                                        | Example                                      |
| -------------------- | -------------------------------------------------------------- | -------------------------------------------- |
| **RSS alert**        | News item with `isAlert: true` and threat level critical/high  | Reuters flash: missile strike confirmed       |
| **Keyword spike**    | Trending keyword exceeds spike threshold                       | "nuclear" surges across 8+ feeds in 2 hours  |
| **Hotspot escalation** | Hotspot escalation score exceeds critical threshold          | Taiwan Strait tension crosses 80/100         |
| **Military surge**   | Theater posture assessment detects strike packaging            | Tanker + AWACS + fighters co-present in MENA |
| **OREF siren**       | Israel Home Front Command issues incoming rocket/missile alert | Rocket barrage detected in northern Israel   |

**Anti-noise safeguards**:

- **Per-event dedup** — each alert is keyed by a content hash; repeated alerts for the same event are suppressed for 30 minutes
- **Global cooldown** — after any alert fires, a 60-second global cooldown prevents rapid-fire notification bursts
- **Recency gate** — items older than 15 minutes at processing time are silently dropped, preventing stale events from generating alerts after a reconnection
- **Source tier gating** — Tier 3+ sources (niche outlets, aggregators) must have LLM-confirmed classification (`threat.source !== 'keyword'`) to fire an alert; Tier 1–2 sources bypass this gate
- **Story-phase gate** — sustained and fading RSS stories are suppressed; the banner is reserved for breaking/developing stories or items without story metadata
- **Importance floor** — RSS items with `importanceScore < 30` are too low-signal for the banner
- **Startup grace** — RSS alerts are suppressed for the first 10 seconds after app load so the initial feed fetch does not replay old articles as breaking news. OREF siren alerts are exempt
- **User sensitivity control** — configurable between `critical-only` (only critical severity fires) and `critical-and-high` (both critical and high severities)

When an alert passes all gates, the system dispatches a `wm:breaking-news` CustomEvent on `document`, which the Breaking News Banner consumes to display a persistent top-of-screen notification. Optional browser Notification API popups and an audio chime are available as user settings. Clicking the banner scrolls to the RSS panel that sourced the alert and applies a 1.5-second flash highlight animation.

---

## Cross-Stream Correlation

### Signal Aggregation

All real-time data sources feed into a central signal aggregator that builds a unified geospatial intelligence picture. Signals are clustered by country and region, with each signal carrying a severity (low/medium/high), geographic coordinates, and metadata. The aggregator:

1. **Clusters by country** — groups signals from diverse sources (flights, vessels, protests, fires, outages, `keyword_spike`) into per-country profiles
2. **Detects regional convergence** — identifies when multiple signal types spike in the same geographic corridor (e.g., military flights + protests + satellite fires in Eastern Mediterranean)
3. **Feeds downstream analysis** — the CII, hotspot escalation, focal point detection, and AI insights modules all consume the aggregated signal picture rather than raw data

### Cross-Stream Correlation Engine

Beyond aggregating signals by geography, the system detects meaningful correlations *across* data streams — identifying patterns that no single source would reveal. 14 signal types are continuously evaluated:

| Signal Type               | Detection Logic                                                                 | Why It Matters                                           |
| ------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `prediction_leads_news`   | Polymarket probability shifts >5% before matching news headlines appear        | Prediction markets as early-warning indicators           |
| `news_leads_markets`      | News velocity spike precedes equity/crypto price move by 15–60 min             | Informational advantage detection                        |
| `silent_divergence`       | Significant market movement with no corresponding news volume                   | Potential insider activity or unreported events           |
| `velocity_spike`          | News cluster sources-per-hour exceeds 6+ from Tier 1–2 outlets                | Breaking story detection                                 |
| `keyword_spike`           | Trending term exceeds 3× its 7-day baseline                                   | Emerging narrative detection                             |
| `convergence`             | 3+ signal types co-locate in same 1°×1° geographic cell                        | Multi-domain crisis indicator                            |
| `triangulation`           | Same entity appears across news + military tracking + market signals           | High-confidence focal point identification               |
| `flow_drop`               | ETF flow estimates reverse direction while price continues                     | Smart money divergence                                   |
| `flow_price_divergence`   | Commodity prices move opposite to shipping flow indicators                     | Supply chain disruption signal                           |
| `geo_convergence`         | Geographic convergence alert from the spatial binning system                   | Regional crisis acceleration                             |
| `explained_market_move`   | Market price change has a matching news cluster with causal keywords           | Attributable market reaction                             |
| `hotspot_escalation`      | Hotspot escalation score exceeds threshold                                     | Conflict zone intensification                            |
| `sector_cascade`          | Multiple companies in same sector move in same direction simultaneously        | Sector-wide event detection                              |
| `military_surge`          | Theater posture assessment detects unusual force concentration                 | Military escalation warning                              |

Each signal carries a severity (low/medium/high), geographic coordinates, a human-readable summary, and the raw data that triggered it. Signals are deduplicated per-type with configurable cooldown windows (30 minutes to 6 hours) to prevent alert fatigue. The correlation output feeds into the AI Insights panel, where the narrative synthesis engine weaves detected correlations into a structured intelligence brief.

The Escalation Monitor correlation adapter clusters by country over a 48-hour
window and emits cards at a composite threshold of `20`. Its current signal
weights are `conflict_event` 45%, `escalation_outage` 25%, and `news_severity`
30%. Conflict/protest severities map high/medium/low to `85/55/30`; internet
outages map total/major/partial to `90/70/40` and are only kept for countries
that also have a conflict event; qualifying news clusters must be medium or
higher, match escalation keywords, and map critical/high/medium threat levels
to `85/65/45`.

### PizzINT Activity Monitor & GDELT Tension Index

The dashboard integrates two complementary geopolitical pulse indicators:

**PizzINT DEFCON scoring** — monitors foot traffic patterns at key military, intelligence, and government locations worldwide via the PizzINT API. Aggregate activity levels across monitored sites are converted into a 5-level DEFCON-style readout:

| Adjusted Activity | DEFCON Level | Label             |
| ----------------- | ------------ | ----------------- |
| ≥ 85%             | 1            | Maximum Activity  |
| 70% – 84%         | 2            | High Activity     |
| 50% – 69%         | 3            | Elevated Activity |
| 25% – 49%         | 4            | Above Normal      |
| &lt; 25%             | 5            | Normal Activity   |

Activity spikes at individual locations boost the aggregate score (+10 per spike, capped at 100). Data freshness is tracked per-location — the system distinguishes between stale readings (location sensor lag) and genuine low activity. Per-location detail includes current popularity percentage, spike magnitude, and open/closed status.

**GDELT bilateral tension pairs** — six strategic country pairs (USA↔Russia, Russia↔Ukraine, USA↔China, China↔Taiwan, USA↔Iran, USA↔Venezuela) are tracked via GDELT's GPR (Goldstein Political Relations) batch API. Each pair shows a current tension score, a percentage change from the previous data point, and a trend direction (rising/stable/falling, with ±5% thresholds). Rising bilateral tension scores that coincide with military signal spikes in the same region feed into the focal point detection algorithm.
