Start here
When you click a pipeline or a storage facility on the map, this is the log of
what has happened to it — the sabotage, sanctions, maintenance windows,
storms, strikes, and contract milestones that took it offline or brought it back.
It exists because a status badge on its own is nearly useless. “Offline” means
one thing for a pipeline shut for scheduled maintenance and something completely
different for one shut by an explosion. The history is what supplies that
difference.
Each event answers four questions
- What happened, sorted into a fixed set of causes — sabotage, sanction,
maintenance, mechanical, weather, commercial, war.
- When it started, and whether it has ended. An open-ended event is still
running.
- How much capacity went offline, in the units that asset is measured in.
- Who says so — every event carries its sources.
Events also record a cause chain rather than a single label, because these
things are rarely simple: sanctions lead to a contract lapse, which leads to a
shutdown. Listing the chain keeps the sequence visible instead of collapsing it
into whichever cause is easiest to name.
This log is curated by hand, not detected automatically. It covers notable
events on the assets in the registry — it is not a complete record of everything
that has ever happened to world energy infrastructure. An automated
state-transition classifier was scoped but has not shipped. Absence from this log
is not evidence that nothing happened.
Scope
The disruption event log (energy:disruptions:v1) is a state-machine history of outages, sanctions, maintenance windows, weather events, and commercial milestones tied to the curated assets in energy:pipelines:gas:v1, energy:pipelines:oil:v1, and energy:storage-facilities:v1.
Release 1 ships a curated seed of notable historical and ongoing events (Nord Stream 1/2 sabotage, Druzhba sanctions, CPC force majeure, TurkStream maintenance, ESPO drone strikes, Arctic LNG 2 OFAC designation, etc.) tied to the assets that ship in the same registry. The log is curated-only today; an automated state-transition classifier was scoped but has not shipped.
Data shape
Each event is a row keyed on a stable id:
Every event must reference an asset that exists in the pipeline or storage registry at seed time — there is no free-floating event class.
What counts as a disruption
The event log covers state transitions, not daily throughput noise:
- Sabotage: explicit physical attacks (Nord Stream 2022, ESPO pumping stations 2025).
- Sanction: regulator listing or operator designation that forces a commercial halt (Arctic LNG 2 OFAC designation, Druzhba North policy halt).
- Maintenance: scheduled operator maintenance windows with published start/end.
- Mechanical: unscheduled failures, force majeure (CPC buoy damage).
- Weather: hurricane/storm-driven shutdowns (Sabine Pass Hurricane Beryl).
- Commercial: material commercial changes (Power of Siberia capacity ramp).
- War: war-driven operational changes (CPC, Yamal-Belarus).
Normal operational variation, routine nominations, and sub-daily flow shifts are not disruption events. They remain in the evidence bundle of the underlying asset, not in the event log.
How the log is kept fresh
- Curation: the event log is refreshed by
scripts/seed-energy-disruptions.mjs on a weekly cron, reading the hand-authored JSON in scripts/data/energy-disruptions.json. Rows are reviewed and added by editors as new state transitions surface in the evidence bundle of each asset. See /corrections for the planned audit-surface shape that will track future automated state-transition entries when/if an auto-classifier lands.
- Decay: ongoing events (where
endAt is null) whose lastEvidenceUpdate is older than 30 days drop to a “stale evidence” treatment in the panel drawer; they do not auto-resolve.
Evidence-source discipline
Every event carries at least one source with a publicly-verifiable URL. regulator and operator sources take precedence over press for classifier confidence weighting. The classifierConfidence field is a quality hint for downstream consumers; it does not gate display — all curated events are rendered.
Public API
ListEnergyDisruptions — GET /api/supply-chain/v1/list-energy-disruptions with optional assetId / assetType / ongoingOnly query facets. Returns events newest-first.- Free tier. Gateway cache tier:
medium.
- Panel drawers (
PipelineStatusPanel, StorageFacilityMapPanel) call this RPC lazily on drawer-open, scoped to the asset id.
Classifier version + auto-revision log
Every event is versioned with classifierVersion. When rules change (new cause enum, new event type, tightened confidence thresholds), the version is bumped and events re-derived. The prior classifier version remains readable via the classifierVersion field on the row — no silent rewrites.
Changes are planned to be auto-logged at /corrections with {field, previousValue, newValue, trigger, sourcesUsed, classifierVersion} per entry — the designed audit surface. The event log itself is forward-looking; the revision log will be the history of how the log has evolved once the classifier ships.
- Pipelines — the registry events tie back to.
- Storage — same for storage facilities.
- Shortages — complementary layer covering consumer-facing fuel shortages rather than upstream asset events.
