Intelligence products
WorldMonitor turns monitored signals into products that help a user understand what is happening, what may happen next, and where action may be needed. The product set moves from source-grounded briefs and country views to risk scores, forecasts, scenarios, resilience views, company monitoring, orbital imagery, and decision support.
Product model
Signal-to-decision chain
The intelligence product flow starts with monitored observations and ends with a decision aid. Product services select relevant signals, add cross-domain context, and present an output with evidence and uncertainty so a user can judge it. Country views apply the same pattern across separate sections, while analyst context combines several product families for a focused question.
This diagram shows how monitored observations move through shared context into present-state views, risk measures, future views, company views, orbital imagery, and decision support.
flowchart LR
A[Monitored observations] --> B[Signals and events]
B --> C[Classified events]
C --> D[Cross-domain context]
D --> E[Briefs and analysis]
D --> R[Country risk scores]
D --> T[Tension monitoring]
D --> O[Country coverage and observations]
D --> F[Forecasts]
D --> S[Scenarios]
D --> G[Resilience views]
D --> M[Company monitoring]
D --> I[Orbital imagery]
E --> Q[Decision support]
R --> Q
T --> Q
O --> Q
F --> Q
S --> Q
G --> Q
M --> Q
I --> Q
The products answer different questions rather than repeat the same view:
| Product family | Main question | Typical output |
|---|---|---|
| Briefs and analysis | What is happening and why does it matter? | A cited brief, situation view, research result, or daily editorial issue |
| Country coverage and observations | What recent events and source observations are visible for this country? | Headlines, incidents, signal observations, and source states |
| Country risk scores | Where is instability concentrated and how is it changing? | Scores, component signals, trends, and risk roll-ups |
| Tension monitoring | Which country pairs show notable pressure now? | Pair scores, movement, and bounded evidence |
| Forecasts | What is likely to happen next? | A probability, trend, time horizon, and supporting case |
| Scenarios | What could follow if a defined shock occurs? | An impact result for affected countries or sectors |
| Resilience views | How well can a country absorb and recover from pressure? | Scores, domains, coverage, confidence, and rankings |
| Company monitoring | What is changing around a named company? | Company context, signals, filings, and material events |
| Orbital imagery | What can imagery show about activity or change at a place? | Image evidence, pass windows, nearby event context, and geospatial views |
| Decision support | What should a user examine or consider next? | Market, country, company, or supply-chain implications |
References: src/…/InsightsPanel.ts• L223-258 src/…/CountryBriefController.ts• L14-66 proto/…/service.proto• L186-208 server/…/chat-analyst-context.ts• L986-1127 src/…/signal-aggregator.ts• L541-674
Product families
The product families form a reading path for a new engineer. Briefs explain the present state. Country coverage and observations show the source events behind it. Risk and tension views make pressure comparable. Forecasts and scenarios extend the view into possible futures. Resilience adds a longer-term capacity lens. Company monitoring, orbital imagery, and analyst outputs connect these views to named businesses, places, and decisions.
| Family | Child page |
|---|---|
| Brief generation, filtering, attribution, history, and analysis | Intelligence briefs and analysis |
| Company enrichment, signals, filings, and material events | Company monitoring intelligence |
| Forecast ingestion and evaluation, scenario processing, and resilience scoring | Forecasting, scenarios, and resilience |
| Travel-risk assessment and trip-focused decision support | Travel-risk assessment |
| Orbital imagery and place-focused image intelligence | Orbital imagery intelligence |
References: src/…/CountryBriefPanel.ts• L215-261 proto/…/service.proto• L15-42 proto/…/resilience.proto• L15-35 server/…/handler.ts• L38-74 docs/orbital-imagery-intelligence.md
Intelligence outputs
Briefs and analysis
Briefs turn selected signals into a short explanation of the current situation. World, country, and regional views can add source-linked news, risk, market, infrastructure, energy, and historical context. Country briefs publish supported claims in situation, implication, risk, outlook, and watch sections. Each claim must stay within its cited headline or data point, and the service keeps a fallback or unavailable state when the full analysis path cannot produce usable text.
The dashboard's Latest Brief surface presents a personalized daily editorial issue when it is ready. It can show a composing state while the issue is being prepared, or guide the user to sign in or use the required plan when access is not available. The issue is also delivered through the supported user channels, including email, Telegram, Slack, and the dashboard.
Analysis views connect signals across domains, compare the current situation with past events, or search durable intelligence history. Similar-event results provide precedents rather than predictions. Optional analysis frameworks change the structure of interpretation without changing the underlying signals.
See Intelligence briefs and analysis for generation, grounding, storage, and presentation flows.
References: server/…/get-country-intel-brief.ts• L74-93 server/…/get-country-intel-brief.ts• L181-256 server/…/get-country-intel-brief.ts• L481-643 server/…/get-similar-events.ts• L42-75 server/…/search-intel-history.ts• L38-78 src/…/country-intel.ts• L635-750 src/…/LatestBriefPanel.ts• L1-19 src/…/LatestBriefPanel.ts• L105-209
Country coverage and observations
Country coverage gives a country-focused view of recent headlines and incidents. It combines news with structured records such as protests, earthquakes, conflicts, military activity, and aviation disruption. It removes repeated reports and keeps source state beside the result, so a quiet period is distinct from a feed that failed or could not confirm its contents.
Country signal observations provide bounded access to selected source families for agents and other clients. Partial and unavailable states remain visible instead of becoming empty results.
References: server/…/_country-coverage-structured.ts• L39-55 server/…/_country-coverage-structured.ts• L133-205 server/…/get-country-signal-observations.ts• L16-72 src/…/country-intel.ts• L583-617
Country risk scores
Country risk scores provide a comparable view of instability across monitored countries. The Country Instability Index combines event pressure with security, information, climate, displacement, advisories, sanctions, disasters, military activity, and other monitored signals. It reports the score, component view, movement, trend, methodology version, and advisory source so a reader can see both the result and its basis.
The score can also support a strategic-risk roll-up based on the highest-risk countries. A trend is shown only when a valid earlier reading exists. A fresh response is preferred, while a failed refresh can return a stale snapshot or a low-information degraded result. Input health distinguishes missing, quiet, unavailable, and usable signal families, so missing inputs do not look like normal conditions.
References: server/…/classify-event.ts• L66-98 server/…/get-risk-scores.ts• L1271-1338 server/…/get-risk-scores.ts• L1691-1804 server/…/get-risk-scores.ts• L1875-1902 server/…/get-risk-scores.ts• L1918-1971 server/…/get-risk-scores.ts• L2281-2363 src/…/country-intel.ts• L483-489
Tension monitoring
The Pizzint status product provides a paired-country view of current tension. It combines a score and movement for configured pairs with notable evidence from channels such as strikes, airport status, military activity, and sanctions. Supporting evidence has its own freshness check, so a current score is not presented with stale observations.
References: server/…/get-pizzint-status.ts• L12-18 server/…/get-pizzint-status.ts• L21-83
Company monitoring
Company monitoring intelligence turns named-company context into a view of business exposure and change. It brings together company enrichment, company signals, filings, and material events so a user can connect a monitored development to a specific business.
See Company monitoring intelligence for the company-monitoring lifecycle and output details.
References: server/…/handler.ts• L18-24 server/…/handler.ts• L54-61
Forecasts and scenarios
Forecasts express possible future events as probabilities rather than facts. They can include a domain, region, time horizon, trend, signals, projected effects, alternative paths, and a rule for later resolution. Evaluation adds a track record while keeping unresolved, void, and audited outcomes distinct from verified accuracy.
Scenario workflows test a defined shock against supply-chain or market exposure. A request is accepted first, computed separately, and returned through a status query. The result reports whether its evidence is complete, partial, or unknown. Energy shock scenarios use measured crude imports and partner-level trade shares when available. They model bypass recovery for Saudi Arabia, the UAE, and Iraq rather than treating all Hormuz traffic as equally unrecoverable. A one-month ramp represents the early period before rerouting reaches its modeled level. Refinery output uses country-specific measured yields where available and a labeled global median for missing products. Product deficits use measured demand and trade data, with recent national demand data as a bounded fallback where the main source has no value. Missing origin or demand data is not replaced with a hidden fixed proxy. Shipping flow ratios remain context rather than a hidden change to scenario severity. Gas results are route sensitivities rather than country-specific shortage forecasts.
See Forecasting, scenarios, and resilience for forecast evaluation, scenario processing, and worker flows.
References: proto/…/forecast.proto• L7-18 src/…/ForecastPanel.ts• L332-585 proto/…/service.proto• L10-35 server/…/_hormuz-bypass.ts• L1-106 server/…/_shock-compute.ts• L101-177 server/…/_shock-compute.ts• L349-377 server/…/_shock-compute.ts• L535-570 server/…/compute-energy-shock.ts• L444-518 server/…/compute-energy-shock.ts• L566-697
Resilience views
Resilience views show how a country may absorb a shock and recover from it. The product combines several domains into an overall score and shows the domain view behind it. Coverage, freshness, confidence, and imputed data remain part of the result, so a score is read with its evidence limits.
See Forecasting, scenarios, and resilience for scoring, validation, ranking, and reporting workflows.
References: proto/…/resilience.proto• L17-38 src/…/ResilienceWidget.ts• L266-355 src/…/resilience-widget-utils.ts• L235-313 server/…/get-resilience-runtime-manifest.ts• L93-121
Travel-risk assessments
Travel-risk assessments turn monitored country conditions into trip-focused guidance. They connect current signals and country context to a travel decision, so the output supports questions about exposure, disruption, and precautions rather than only describing the general situation.
See Travel-risk assessment for the trip assessment workflow and its decision-support outputs.
References: docs/travel-risk-assessment.md
Orbital imagery intelligence
Orbital imagery intelligence adds image-based observations to the wider intelligence picture. It helps a user examine activity or change at a place and relate that visual evidence to monitored events and decision support.
The orbital watch view joins image evidence with time and place context. It can show confirmed acquisitions, likely or possible collection passes, the latest usable image, image history, daily mosaics, weather frames, and upcoming collection windows. Nearby events and live activity appear beside the imagery, while watched-site records add a place-specific view when one exists. Archive, freshness, processing, no-data, and partial-source states remain visible so the user can tell an absent image from an absent observation.
See Orbital imagery intelligence for the imagery workflow and its outputs.
References: src/…/OrbitalWatchPage.ts• L888-985 src/…/OrbitalWatchPage.ts• L988-1107 src/…/OrbitalWatchPage.ts• L1130-1177 src/…/OrbitalWatchPage.ts• L1180-1201 docs/orbital-imagery-intelligence.md
Decision-support outputs
Decision support combines a present-state explanation with a forward view or an impact lens. A country view can place a brief beside risk, signals, markets, infrastructure, energy, trade, and resilience context. Its energy view can show the mix, import dependence, storage, electricity, oil and gas measures, strategic reserves, and regional feed status. Energy values can come from data with different update times, while each unavailable or partial measure stays labeled. Port activity adds tanker movement and anomaly context when coverage is available. A decision brief can turn selected disruption or commodity-route assumptions into a conditional impact with evidence, assumptions, unknowns, and a next action.
The analyst context supports questions that need more than one product family. It can combine risk, forecasts, market implications, prediction markets, macro signals, headlines, and energy measures. Situation deduction can add matched prediction-market odds to a query and apply a caller-selected analysis framework for premium users. Market titles are treated as data, not instructions, before they enter the analysis context. The streamed analyst response checks stated prices against the live context. If an answer states a price that the context does not support, it adds a visible caveat instead of silently presenting the figure as current.
Country intelligence opens from the map or another client request. The country panel shows an early country view, then fills in signals, coverage, economics, infrastructure, and brief text. Request ownership and country identity checks prevent an older or invalid request from replacing the active view.
References: server/…/chat-analyst-context.ts• L986-1127 server/…/chat-analyst-grounding.ts• L97-132 server/…/chat-analyst-grounding.ts• L134-193 server/…/deduct-situation.ts• L50-88 server/…/deduct-situation.ts• L105-197 server/…/get-country-energy-profile.ts• L312-393 server/…/get-country-energy-profile.ts• L396-515 server/…/get-country-port-activity.ts• L73-126 server/…/compute-energy-shock.ts• L421-470 src/…/country-intel.ts• L421-507 src/…/country-intel.ts• L549-717
Product trust and delivery
Evidence and uncertainty
The products separate an observation from an interpretation. Briefs keep source links and validate claims. Event classification accepts only known threat levels and categories. Scores, markets, forecasts, tension evidence, resilience values, and country sections carry freshness, coverage, or grounding limits. Analyst context treats feed text as data rather than instructions, and price grounding marks unsupported streamed figures for the reader.
The signal layer also keeps different observations distinct before they reach product context. It normalizes events to countries, groups them by country and region, limits the retained window and total volume, and derives convergence from signal variety, count, and severity. This lets downstream analysis see cross-domain activity without treating every raw event as a separate high-level conclusion.
This trust model also affects empty and partial results. A healthy system with no matching signal is different from a missing source or a failed service. Product responses therefore use states such as degraded, stale, unavailable, pending, or low confidence instead of silently turning missing data into a quiet conclusion.
References: server/…/classify-event.ts• L44-64 server/…/classify-event.ts• L146-184 server/…/chat-analyst-grounding.ts• L88-119 server/…/chat-analyst-grounding.ts• L146-166 server/…/get-pizzint-status.ts• L21-83 server/…/get-risk-scores.ts• L1127-1199 server/…/get-country-energy-profile.ts• L403-429 server/…/compute-energy-shock.ts• L251-277 src/…/country-intel.ts• L759-799 src/…/signal-aggregator.ts• L103-140 src/…/signal-aggregator.ts• L534-619
Composite analysis inputs
Composite analysis turns several seeded or cached source payloads into a shared digest input. The adapters keep source absence as unavailable data, reject malformed coordinates and unsupported event locations, map source-specific severity to common levels, and preserve the distinction between a measured value and a missing one. This gives alert and decision products one stable input shape without hiding gaps in the source feeds.
References: shared/analysis-composite-adapters.ts• L41-71 shared/analysis-composite-adapters.ts• L73-163 shared/analysis-composite-adapters.ts• L165-250 shared/analysis-composite-adapters.ts• L252-272
Precomputed and on-demand work
The product set uses precomputed material for common views and on-demand work for questions that depend on the current user or a costly calculation. This keeps the dashboard fast while preserving deeper analysis when a user opens a view or asks a question.
Common briefs, forecasts, scores, and resilience data can come from shared snapshots. Historical searches, analyst questions, country coverage, signal observations, and decision calculations run when requested. Situation deduction uses a bounded request budget and caches successful context-specific results. Scenario and simulation work runs asynchronously, then returns a result through polling.
References: src/…/insights-loader.ts• L61-123 src/…/forecast.ts• L30-48 server/…/search-intel-history.ts• L24-73 server/…/deduct-situation.ts• L90-103 server/…/deduct-situation.ts• L123-190 server/…/get-scenario-status.ts• L62-97 src/…/country-intel.ts• L595-617
Access and product surfaces
Some intelligence products are public summaries. Deeper briefs, historical research, analyst conversations, scenarios, simulations, and resilience views use access rules enforced by the service layer. The daily Latest Brief is an account-linked, Pro-gated product that can be ready, composing, or unavailable without exposing another user's content. The same product can appear in a dashboard panel, a country view, a report, an API response, or an MCP response, so each surface must preserve the same meaning and access state.
References: src/…/LatestBriefPanel.ts• L105-209 src/…/LatestBriefPanel.ts• L224-345 src/…/LatestBriefPanel.ts• L393-445 src/…/ResilienceWidget.ts• L170-235 server/…/run-scenario.ts• L28-36 api/chat-analyst.ts• L129-172 src/…/country-intel.ts• L227-249
Change checklist
When these files or sections are changed, remember to consider these:
- When a monitored signal or snapshot shape changes, update selection, provenance, freshness, and degraded-state handling together.
- When signal types or convergence rules change, keep country normalization, regional membership, severity mapping, retention limits, AI context, and digest adapters aligned.
- When event classification labels change, keep the allowed levels, categories, severity mapping, cache namespace, and downstream risk interpretation aligned.
- When composite analysis inputs change, keep null propagation, source field mapping, coordinate validation, exposure grouping, and shared severity bands aligned.
- When a country brief grounding source changes, check source dates, cache sharing, evidence limits, citation validation, and fallback behavior together.
- When a country view changes, keep country identity, request ownership, section state, access gates, and exported decision content aligned.
- When analyst context changes, keep domain selection, headline scope, feed sanitization, active-source labels, and degraded state aligned.
- When analyst price grounding changes, keep currency matching, rounding tolerance, streamed completion handling, and visible caveat behavior aligned.
- When situation deduction changes, keep prediction-market selection, prompt-safe feed text, framework access, cache identity, timeout degradation, and quota release aligned.
- When country energy data changes, keep spine and fallback sources, regional feed status, per-series freshness, coverage flags, and cache-read failure behavior aligned.
- When country port activity changes, keep country allowlisting, current and servable age limits, stale labeling, and the bounded port list aligned.
- When an energy shock input changes, keep partner-level trade coverage, measured crude imports, bypass assumptions, ramp timing, refinery yield basis, product demand fallback, route factors, coverage labels, limitations, cache versions, and oil or gas mode behavior aligned.
- When forecast or scenario fields change, check the service contract, published data, worker result, coverage state, and reader together.
- When a resilience dimension or score formula changes, align score validity, confidence, ranking eligibility, and runtime metadata.
- When risk inputs or scoring weights change, align the formula version, methodology disclosure, input-health report, trend history, strategic roll-up, and stale fallback.
- When the daily brief's status or access rules change, keep account identity, entitlement state, signed-link delivery, composing refresh, and locked or unavailable states aligned.
- When orbital evidence or point context changes, keep pass tiers, archive results, image fallbacks, nearby event states, source credits, freshness labels, and watched-site records aligned.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A required source snapshot is missing or too old | A product can become unavailable or degraded, or show a score with weak confidence. | Validate freshness and carry explicit source state in the output. |
| A signal payload has an unknown country, invalid location, or unsupported shape | Events can be grouped under the wrong place or omitted from exposure and digest context. | Normalize country codes, validate coordinates, and reject unsupported records before grouping. |
| Signal volume exceeds the retained window or cap | Old or low-priority events can crowd out current activity and distort convergence. | Prune signals by age and retain only the newest bounded set. |
| A headline has an invalid or unsupported classification result | The event can disappear from the classification response or lose its intended risk priority. | Limit the input, validate the returned level and category, and return an undefined classification on failure. |
| A streamed analyst answer states a price absent from live context | A user may treat an old or invented price as current. | Compare prices by currency and tolerance, then append a visible unverified caveat before completion. |
| A country request has an invalid code or finishes after the user changes country | The wrong country can open or old data can replace the active view. | Canonicalize country codes and check request ownership before applying results. |
| A country coverage feed fails or has no usable items | A client can mistake a source failure for a quiet country. | Keep failed, unknown, empty, and usable states distinct. |
| A regional energy feed is malformed or outside its freshness window | A country energy view can present invalid or stale regional measures as current. | Validate feed records and periods, mark each feed state, and preserve partial coverage. |
| An energy profile cache read fails | A client can receive a successful-looking profile with false availability. | Return a service error and avoid publishing the profile as complete. |
| Port activity is not allowlisted or passes its serving age | A country view can expose an unsupported country or show a month-old movement window as current. | Apply the country allowlist and separate current, stale, and no-longer-servable payloads. |
| Situation deduction times out or its provider fails | A user receives no analysis after the request budget is spent. | Bound the reasoning call, cache successful context-specific results, and return an explicit error state. |
| Crude imports or partner-level origin shares are unavailable | An oil shock can look complete while its loss and product deficits are not measured. | Do not use a fixed proxy. Report unsupported or incomplete coverage with explicit limitations. |
| Bypass capacity or its date is changed without the loss and cover logic | The scenario can use one assumption for exposure and another for stock cover. | Keep exporter assumptions, ramp timing, cache inputs, limitations, and assessment text aligned. |
| Refinery yield or product demand data is missing or stale | Product deficits can look measured when they use a weak or mismatched basis. | Use a labeled fallback only where allowed and keep the source window and coverage in the result. |
| A gas shock result is read as a shortage forecast | A route sensitivity can be treated as measured country exposure. | Label the result as an assumed route sensitivity and show its data limits. |
| An asynchronous scenario is accepted but not complete | A user can read an accepted job as a finished impact result. | Return pending status and poll until completion or failure. |
| Forecast evidence is too small, stale, or under audit | The product can show a reliability number that the data cannot support. | Gate scorecards and keep unresolved or audited outcomes separate from verified grades. |
| A risk input read fails during score refresh | A partial recomputation can hide a source failure or replace a usable snapshot with bad data. | Reject the fresh build, keep the last good snapshot, and mark the response degraded and stale. |
| A risk score has no valid prior reading | The reader can mistake an unknown movement for a stable score. | Use an unspecified trend until a valid time-matched comparison exists. |
| A brief request crosses an account or entitlement change | One user's issue can be shown to another user, or a valid user can see a false upgrade prompt. | Bind the request to the current account, enforce access on the server, and check the result before display. |
| Brief composition has not finished or its service cannot be reached | The panel can imply that no brief exists or leave a user waiting without a clear state. | Show composing, sign-in, upgrade, desync, and service-error states separately. |
| An orbital archive, orbit catalog, or nearby-event source is stale or unavailable | A point view can look empty even though the source failed, or can present old evidence as current. | Mark source state and freshness separately, then preserve partial results and retry paths. |
| An image has no data at the point or is still processing | A missing crop can look like a failed acquisition or a confirmed absence of activity. | Use archive fallbacks and explicit no-data or processing states. |
Key files
| File | Why to read it |
|---|---|
| proto/…/service.proto | Defines the main intelligence service contract. |
| server/…/handler.ts | Shows the service surface for briefs, country observations, company monitoring, and decision support. |
| src/…/country-intel.ts | Shows how a country selection becomes a layered country intelligence view. |
| src/…/signal-aggregator.ts | Shows how current geographic signals become country clusters, regional convergence, and AI context. |
| shared/analysis-composite-adapters.ts | Shows how source payloads become common inputs for composite alert analysis. |
| server/…/classify-event.ts | Shows how monitored headlines receive bounded threat and category labels. |
| server/…/get-country-intel-brief.ts | Shows the country brief output and its evidence boundary. |
| src/…/LatestBriefPanel.ts | Shows the daily brief surface, its account and plan states, and its transition from composing to ready. |
| server/…/get-risk-scores.ts | Shows how monitored signals become country scores, trends, health states, and strategic risk. |
| server/…/chat-analyst-context.ts | Shows how cross-domain context is assembled for analyst questions. |
| server/…/chat-analyst-grounding.ts | Shows how streamed price claims are checked against live context. |
| server/…/deduct-situation.ts | Shows how on-demand situation analysis uses query context and prediction-market signals. |
| server/…/get-country-energy-profile.ts | Shows how country energy measures and regional feed states become decision context. |
| server/…/_regional-energy-feeds.ts | Defines regional energy feed validation, freshness, and availability states. |
| server/…/get-country-port-activity.ts | Shows how bounded port activity becomes country context with stale handling. |
| server/…/_hormuz-bypass.ts | Defines the dated bypass assumptions that limit modeled Hormuz oil loss. |
| server/…/_shock-compute.ts | Defines shared coverage, refinery, product-balance, stock-cover, and gas-sensitivity rules for shock scenarios. |
| server/…/compute-energy-shock.ts | Shows how trade, energy, storage, bypass, and chokepoint data shape an energy scenario. |
| src/…/OrbitalWatchPage.ts | Shows how a place-focused imagery view combines acquisitions, passes, archives, events, and source states. |
| proto/…/forecast.proto | Defines forecast claims, evidence, and resolution. |
| proto/…/service.proto | Defines the asynchronous scenario request and status flow. |
| proto/…/resilience.proto | Defines resilience domains, coverage, and ranking eligibility. |
| api/chat-analyst.ts | Shows the external streamed analyst surface. |
| docs/travel-risk-assessment.md | Explains the trip-focused assessment workflow and its output. |
| docs/orbital-imagery-intelligence.md | Explains the place-focused imagery workflow and its intelligence output. |