eliott/worldmonitor
1
0
Fork 0
mirror of https://github.com/koala73/worldmonitor.git synced 2026-04-25 17:14:57 +02:00
Code Issues Packages Projects Releases Wiki Activity

feat(variant): Energy Atlas — Release 1 Day 1 (variant scaffolding) (#3291)

Browse Source 
* feat(variant): add energy variant scaffolding for energy.worldmonitor.app

Release 1 Day 1 of the Energy Atlas plan — introduces src/config/variants/energy.ts
modeled on the commodity variant. No new panels or RPCs yet; the variant reuses
existing energy-related panels (energy-complex, oil-inventories, hormuz,
energy-crisis, fuel-prices, renewable-energy) + supply-chain/sanctions context.

Map layers enable pipelines, waterways, AIS, commodityPorts, minerals, climate,
outages, natural, weather. All geopolitical/military/tech/finance/happy variant
layers explicitly disabled per variant isolation conventions.

Next PRs on feat/energy-atlas-release-1 add:
- Pipeline & storage registries (curated critical assets, ~75 gas / ~75 oil / ~125 storage)
- Global fuel-shortage registry with automated evidence-threshold promotion
- Pipeline/storage disruption event log
- Country drill-down Energy section
- Atlas landing composition at variant root

* feat(variant): wire energy variant into runtime + atlas landing composition

Day 2 of the Energy Atlas Release 1 plan. The Day-1 commit added a canonical
variants/energy.ts but discovery during Day 2 showed the app's runtime variant
resolution lives in src/config/panels.ts (ENERGY_PANELS/ENERGY_MAP_LAYERS/etc.),
not in variants/*.ts (which are orphans). This commit does the real wiring.

Changes:
- src/config/panels.ts — ENERGY_PANELS, ENERGY_MAP_LAYERS, ENERGY_MOBILE_MAP_LAYERS;
  registered in ALL_PANELS, VARIANT_DEFAULTS, VARIANT_PANEL_OVERRIDES; wired into
  DEFAULT_MAP_LAYERS + MOBILE_DEFAULT_MAP_LAYERS ternaries. Panels at launch:
  map, live-news, insights, energy-complex, oil-inventories, hormuz, energy-crisis,
  fuel-prices, renewable-energy, commodities, energy (news), macro-signals,
  supply-chain, sanctions-pressure, gulf-economies, gcc-investments, climate,
  monitors, world-clock, latest-brief.
- src/config/variant.ts — recognize 'energy' as allowed SITE_VARIANT; resolve
  energy.worldmonitor.app subdomain to 'energy'; honor localStorage override.
- src/config/variant-meta.ts — SEO entry for energy.worldmonitor.app (title,
  description, keywords targeting 'oil pipeline tracker', 'gas storage map',
  'fuel shortage tracker', 'chokepoint monitor', etc.).
- src/app/panel-layout.ts — desktop variant switcher + mobile menu both list
  energy with ⚡ icon and t('header.energy') label.
- src/App.ts + src/app/data-loader.ts — energy variant enables trade-policy and
  supply-chain data loads (chokepoint exposure is a core Atlas surface).
- src/app/data-loader.ts — daily-brief newsCategories override for energy variant
  (energy, energy-markets, oil-gas-news, pipeline-news, lng-news).
- src/locales/en.json — 'header.energy' translation key.
- src/config/variants/energy.ts — add clarifying comment that real wiring lives
  in panels.ts (same orphan pattern as commodity.ts/finance.ts/etc.).

Atlas landing composition: the variant now renders its energy panel set with
energy-specific names (Energy Atlas Map, Energy Headlines, AI Energy Insights)
when SITE_VARIANT === 'energy'. Pipeline and commodity-port map layers enabled
so Week 2's pipeline registry + storage-facility registry drop in with layers
already toggled on.

Typecheck clean; 175 pre-push tests expected to remain green.

Subsequent PRs on feat/energy-atlas-release-1:
- Week 2: pipeline registry + storage facility registry (evidence-based)
- Week 3: fuel-shortage classifier + disruption log + country drill-down
- Week 4: automated revision log, SEO polish, launch

* feat(energy): chokepoint strip at top of atlas (7 chokepoints)

Day 3 of the Energy Atlas Release 1 plan. Adds ChokepointStripPanel — a
compact horizontal strip of chip-style cards, one per chokepoint, showing
name + status color + flow-as-%-of-baseline + active-warnings badge.
Ordered by volume: Hormuz, Malacca, Suez, Bab el-Mandeb, Turkish Straits,
Danish Straits, Panama.

GEF covers 5 chokepoints (Hormuz, Malacca, Suez, Bab el-Mandeb, Panama).
We cover 7 — adds Turkish Straits + Danish Straits. One of the surpass
vectors enumerated in §5.7 of the plan doc.

Data: reuses the existing fetchChokepointStatus() RPC backed by
supply_chain:chokepoints:v4 (Portwatch DWT + AIS calibration). No new
backend work; this is pure UI composition.

Changes:
- src/components/ChokepointStripPanel.ts — new Panel subclass with
  in-line CSS for the chip strip; falls back gracefully when a chokepoint
  is missing from the response or FlowEstimate is absent.
- src/components/index.ts — barrel export.
- src/app/panel-layout.ts — import + createPanel registration near
  existing energy panels.
- src/config/panels.ts — ENERGY_PANELS adds 'chokepoint-strip' at priority 1
  (renders near top of atlas). Also fixes two panel-ID mismatches caught
  while wiring: 'hormuz' → 'hormuz-tracker' and 'renewable-energy' →
  'renewable' (matches HormuzPanel.ts and RenewableEnergyPanel registration).

Typecheck clean. No new tests required — panel renders real data.

* feat(energy): attribution footer utility + methodology page stubs

Days 4 & 5 of the Energy Atlas Release 1 plan.

## Day 4 — Attribution footer (src/utils/attribution-footer.ts)

A reusable string-builder that stamps every energy-atlas number with its
provenance. Design intent per plan §5.6 (quantitative rigour moat):
"every flow number carries {value, baseline, n_vessels, methodology,
confidence}".

Input schema:
- sourceType: operator | regulator | ais | satellite | press | classifier | derived
- method: short free-text ("AIS-DWT calibrated", "GIE AGSI+ daily")
- sampleSize + sampleLabel: observation count and unit
- updatedAt: ISO8601 / Date / number — rendered as "Xm/h/d ago"
- confidence: 0..1 — bucketed to high/medium/low
- classifierVersion: surfaced when evidence-derived badges ship in Week 2+
- creditName / creditUrl: CC-BY / dataset credit (OWID, GEM pattern)

Every field also writes data-attributes (data-attr-source, data-attr-n,
data-attr-confidence, data-attr-classifier) so MCP / scraper / analyst
agents can extract the same provenance the reader sees. Agent-native by
default.

Applied to ChokepointStripPanel — the panel now shows its evidence
footer ("AIS calibration · Portwatch DWT + AIS · N AIS disruption
signals · updated Xh ago · EIA World Oil Transit Chokepoints").
Future pipeline / storage / shortage panels drop the same helper in
and hit the same rigour bar automatically.

7 unit tests (tests/attribution-footer.test.mts, node:test via tsx):
minimal footer, method + sample size + credit, "X ago" formatting,
confidence band mapping, full data-attribute emission, credit omission,
HTML escaping.

## Day 5 — Public methodology page stubs (docs/methodology/)

Four new MDX pages surfaced in docs/docs.json navigation under
"Intelligence & Analysis":

- chokepoints.mdx — 7 chokepoints, Portwatch+AIS calibration method,
  status badge derivation, known limits, revision-log link.
- pipelines.mdx — curated critical-asset scope, GEM CC-BY attribution,
  evidence-schema (NOT conclusion labels), freshness SLA, corrections.
- storage.mdx — curated ~125 facilities scope, "published not
  synthesized" fill % policy, country-aggregate fallback, attribution.
- shortages.mdx — automated tiered evidence threshold, LLM second-pass
  gating, auto-decay cadence, evidence-source transparency, break-glass
  override policy (admin-only, off critical path).

All four explicitly document WorldMonitor's automated-data-quality
posture: no human review queues, quality via classifier rigour +
evidence transparency + auto-decay + public revision log.

Typecheck clean. attribution-footer.test.mts passes all 7 tests.

* fix(variant): close three energy-variant isolation leaks from review

Addresses three High findings from PR review:

1. Map-layer isolation (src/config/map-layer-definitions.ts)
   - Add 'energy' to the MapVariant type union.
   - Add energy entry to VARIANT_LAYER_ORDER with the curated energy
     subset (pipelines, waterways, commodityPorts, commodityHubs, ais,
     tradeRoutes, minerals, sanctions, fires, climate, weather, outages,
     natural, resilienceScore, dayNight).
   Without this, getLayersForVariant() and sanitizeLayersForVariant()
   (called from DeckGLMap and App.ts) fell back to VARIANT_LAYER_ORDER.full,
   letting the full geopolitical palette (military, nuclear, iranAttacks,
   conflicts, hotspots, bases, protests, flights, ucdpEvents,
   displacement, gpsJamming, satellites, ciiChoropleth, cables,
   datacenters, economic, cyberThreats, spaceports, irradiators,
   radiationWatch) into the desktop map tray and saved/URL layer
   sanitization — breaking the PR's stated no-geopolitical-bleed goal
   and violating multi-variant-site-data-isolation.

2. News feeds (src/config/feeds.ts + src/app/data-loader.ts)
   - Add ENERGY_FEEDS with three keys matching ENERGY_PANELS: live-news
     (broad energy headlines from OilPrice, Rigzone, Reuters/Bloomberg/FT
     energy), energy (OPEC + crude + NatGas/LNG + pipelines/chokepoints
     + crisis/shortages + refineries), supply-chain (tanker/shipping,
     chokepoints, energy sanctions, ports/terminals).
   - Add SITE_VARIANT === 'energy' branch to the FEEDS variant selector.
   - Correct newsCategories override in data-loader.ts — my earlier
     speculative values ['energy','energy-markets','oil-gas-news',
     'pipeline-news','lng-news'] included keys that did not exist in
     any feed map. Replaced with real ENERGY_FEEDS keys ['live-news',
     'energy', 'supply-chain'].
   Without this, FEEDS resolved to FULL_FEEDS for the energy variant —
   live-news + daily-brief both ingested the world/geopolitical feed set.

3. Insights / AI brief framing (src/components/InsightsPanel.ts)
   - Add SITE_VARIANT === 'energy' branch to geoContext: dedicated energy
     prompt focused on physical supply (pipelines, chokepoints, storage,
     days-of-cover, refineries, LNG, sanctions, shortages) with
     evidence-grounded attribution, no bare conclusions.
   - Add '⚡ ENERGY BRIEF' heading branch in renderWorldBrief().
   Without this, the renamed 'AI Energy Insights' panel fell through
   to the empty default prompt and rendered 'WORLD BRIEF'.

Typecheck clean. attribution-footer tests still pass (no coupling changed).

* fix(variant): close energy-variant leak in SVG/mobile fallback map

Fifth High finding from PR review: src/components/Map.ts createLayerToggles()
(line 381-409) has no 'energy' branch in its variant ternary, so energy-variant
users whose MapContainer routes to the SVG/mobile fallback (no WebGL, mobile
with deviceMemory < 3, or DeckGL init throws) see the full geopolitical toggle
set — iranAttacks, conflicts, hotspots, bases, nuclear, irradiators, military,
protests, flights, gpsJamming, ciiChoropleth, cables, datacenters.

Clicking any toggle flips the layer via toggleLayer() which is variant-blind
(Map.ts:3383) — so users could enable military / nuclear layers on the energy
variant despite the rest of the isolation work in panels.ts,
map-layer-definitions.ts, feeds.ts, and InsightsPanel.ts.

Fix: add energyLayers array with the SVG-capable subset of ENERGY_MAP_LAYERS —
pipelines, waterways, ais, commodityHubs, minerals, sanctions, outages, natural,
weather, fires, economic. Intentionally omitted: commodityPorts, climate,
tradeRoutes, resilienceScore, dayNight — none of these have render handlers in
Map.ts's SVG path, so including them would create toggles that do nothing.
Extended the ternary with 'energy' → energyLayers between 'happy' and the
'full' fallback.

Note (preexisting, NOT fixed here): the same ternary has no 'commodity' branch
either, so commodity.worldmonitor.app also gets the full geopolitical toggle
set on the SVG fallback. Out of scope for this PR; flagged for a separate fix.

Defence-in-depth: sanitizeLayersForVariant() (now fixed in
map-layer-definitions.ts) strips saved-URL layers to the energy subset before
the SVG map sees them, so even if a user arrives with ?layers=military in the
URL, it's gone by the time initialState reaches MapComponent. The toggle-list
fix closes the UI-path leak; the sanitize fix closes the URL-path leak.

Typecheck clean.
This commit is contained in:
Elie Habib
2026-04-22 21:37:25 +04:00
committed by GitHub
parent 8172ea5660
commit a17a3383d9
21 changed files with 1104 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
docs/methodology/chokepoints.mdx Normal file
View File

@@ -0,0 +1,67 @@
---
title: "Chokepoint Methodology"
description: "How World Monitor calibrates live flow estimates for the seven global oil & gas shipping chokepoints (Hormuz, Malacca, Suez, Bab el-Mandeb, Turkish Straits, Danish Straits, Panama)."
---
## What we track
Seven oil & gas shipping chokepoints:
| Chokepoint | Baseline flow (mb/d) |
|-------------------|----------------------|
| Strait of Hormuz | 21.0 |
| Strait of Malacca | 17.2 |
| Suez Canal / SUMED| 7.6 |
| Bab el-Mandeb | 6.2 |
| Danish Straits | 3.0 |
| Turkish Straits | 2.9 |
| Panama Canal | 0.9 |
Baselines are EIA's 2023 World Oil Transit Chokepoints publication. Two chokepoints (Turkish + Danish Straits) are **not** covered by common competitor sites — they show up here.
## How live flow is derived
Not an editorial estimate. Every published flow number is calibrated from real observations on a 6-hour refresh:
1. **Portwatch DWT** — IMF / World Bank vessel-tracking aggregation produces per-chokepoint deadweight tonnage by vessel class.
2. **AIS-relay hazard matching** — our AIS ingestion (Railway relay) tags vessels within 500 km of a chokepoint with observed disruption signals (GPS jamming, AIS-off, anchorage clusters, Red/Orange GDACS alerts).
3. **Flow estimate** = current DWT ÷ 365-day baseline DWT, expressed as % of baseline.
4. **Confidence band** = function of vessel sample size and disruption-signal density.
Refresh cadence: `energy:chokepoint-flows:v1` (6h Railway cron) + `supply_chain:chokepoints:v4` warm-ping (30 min).
## Status badge derivation
Each chokepoint has a derived public badge: `normal | restricted | disrupted | closed`. The badge is a deterministic function of:
- Flow ratio (current mb/d ÷ baseline)
- Active AIS disruption count within 500 km
- War-risk tier (low / medium / high / extreme)
- Active navigational warnings (NGA)
We do not publish a bare conclusion label ("sanctions-blocked", "closed by Iran", etc.) without the underlying evidence fields visible alongside.
## Every public number carries its grounds
Every chokepoint card exposes its provenance via a standard attribution footer:
- Source type (`ais` for Portwatch + AIS, `regulator` for EIA baselines)
- Sample size (N AIS observations)
- Method (`AIS-DWT calibrated`)
- Confidence band (`high | medium | low`)
- Data freshness (`Xh ago`)
The footer is an `HTMLElement` with `data-attr-source`, `data-attr-n`, `data-attr-confidence` attributes so agents (MCP clients, scrapers, analyst tools) can extract the same provenance the eye can read.
## Known limits
- AIS signal drops over heavily-jammed regions (Bab el-Mandeb, Hormuz). Gaps are surfaced as reduced confidence, not synthesized away.
- Baselines are annual averages. Seasonal swings (e.g. Suez winter/summer) aren't modeled yet.
- No per-commodity breakdown (crude vs products vs LNG) at the strip level. Coming in a later release via the pipeline registry crosslink.
## Corrections
Every badge transition writes to the public revision log at
[`/corrections`](/corrections). If you spot a wrong number, open a GitHub issue
or email the address listed in the footer — we update on the next classifier
pass.

70
docs/methodology/pipelines.mdx Normal file
View File

@@ -0,0 +1,70 @@
---
title: "Pipeline Registry Methodology"
description: "How World Monitor curates and attributes status for the world's oil and gas pipelines shown on the Energy Atlas."
---
## Scope
Release 1 launches with a curated registry of critical oil & gas pipelines, not a claim of global completeness:
- ~75 critical gas pipelines (Nord Stream 1/2, TurkStream, Yamal, Brotherhood/Soyuz, Power of Siberia, Qatar–UAE Dolphin, Medgaz, Langeled, Europipe I/II, Franpipe, etc.)
- ~75 critical oil pipelines (Druzhba N/S, CPC, ESPO, BTC, Trans-Alaska, Habshan–Fujairah, Keystone, Kirkuk–Ceyhan, Baku–Supsa, etc.)
Curation bias is toward pipelines with active geopolitical exposure, not theoretical global completeness. Expansion is a post-launch decision.
## Data sources
- **[Global Energy Monitor](https://globalenergymonitor.org) — Oil & Gas Pipeline Tracker** (CC-BY 4.0). Primary source for geometry, capacity, operator, country list.
- **ENTSOG Transparency Platform** (public API) — EU gas pipeline nominations and sendout.
- **Operator technical documentation** — route schematics, capacity plates, force-majeure notices.
- **Regulator filings** — per-jurisdiction filings where applicable.
Every pipeline carries at least one primary source reference.
## Evidence schema (not conclusions)
We do not publish a bare `sanctions_blocked` or `political_cutoff` label. Public badges are derived server-side from an evidence bundle per pipeline:
```ts
{
physicalState: 'flowing' | 'reduced' | 'offline' | 'unknown',
physicalStateSource: 'ais-relay' | 'operator' | 'satellite' | 'press',
operatorStatement: { text, url, date } | null,
commercialState: 'under_contract' | 'expired' | 'suspended' | 'unknown',
sanctionRefs: [{ authority, listId, date, url }, ...],
lastEvidenceUpdate: ISO8601,
classifierVersion: 'vN',
classifierConfidence: 0..1
}
```
The visible `publicBadge` (`flowing | reduced | offline | disputed`) is a deterministic function with freshness weights. When a pipeline reopens or a sanctions list changes, the evidence fields update and the badge re-derives automatically. We ship the evidence; the badge is a convenience view of it.
## How public badges move
Any transition that flips a public status writes an append-only entry to the public revision log at [`/corrections`](/corrections). Each entry records:
- `{ assetId, fieldChanged, previousValue, newValue, trigger, sourcesUsed[], classifierVersion }`
No human review queue gates the transition — quality comes from the tiered evidence threshold + an LLM second-pass sanity check + auto-decay of stale evidence. The classifier's version string ships with every public badge so scientific reproducibility is possible.
## Freshness SLA
- Pipeline registry fields (geometry, operator, capacity): 35 days
- Pipeline public badge (derived state): 24 hours; auto-decay to `stale` at 48 h and excluded from "active disruptions" counts after 7 days
## Known limits
- Geometry is simplified (not engineering-grade routing). Do not use for field operations.
- Flow direction is advertised but not always calibrated to metered reality; relative state (flowing / reduced / offline) is more reliable than absolute mb/d.
- Sanction references are evidence, not legal interpretation. Every `sanctionRefs` entry cites the authority; the interpretation of whether a sanction "blocks" flow is made explicit in the evidence bundle, never implicit in a badge label.
## Attribution
Pipeline-registry data derived from [Global Energy Monitor](https://globalenergymonitor.org) (CC-BY 4.0), with additional operator and regulator material incorporated under fair-use for news reporting.
## Corrections
See the public revision log at [`/corrections`](/corrections). Spot a wrong
status? Open a GitHub issue or email the address in the atlas footer — we
update on the next classifier pass, typically within 6 hours.

85
docs/methodology/shortages.mdx Normal file
View File

@@ -0,0 +1,85 @@
---
title: "Fuel Shortage Alert Methodology"
description: "How World Monitor classifies and publishes fuel shortage alerts (jet, petrol, diesel, heating oil) using an automated evidence-threshold pipeline."
---
## What we track
Four product categories, two severity tiers, global coverage:
| Product | `watch` tier | `confirmed` tier |
|-----------|--------------|------------------|
| Jet fuel | ✓ | ✓ |
| Petrol | ✓ | ✓ |
| Diesel | ✓ | ✓ |
| Heating oil | ✓ | ✓ (winter only) |
Price spikes alone are not shortage signals. We key on physical supply constraints: flight cancellations, station closures, formal rationing, import cuts.
## Fully automated — no human review queue
WorldMonitor runs every classifier fully automated. Shortage tiers are no exception. Quality comes from **tiered evidence thresholds + an LLM second-pass sanity check + auto-decay of stale rows**, not from a human reviewer.
### Watch tier (automated)
One credible source:
- A regulator announcement (EPRA, NMDPRA, OGRA, CAA UK, DGCA), **or**
- An airline / airport operational bulletin, **or**
- A national wire story with ≥ 1 corroborating observation
### Confirmed tier (automated, stricter bar)
The `watch → confirmed` promotion requires:
- **Two distinct outlets + one regulator**, or
- **Three distinct outlets**, or
- **One regulator + a direct operational-impact signal** (flight cancellation in an airline feed, formal rationing announcement, station-closure list)
AND — the LLM second-pass must agree with the promotion. If the LLM disagrees, the row stays at `watch` until the threshold is exceeded with additional sources.
### Auto-decay
- `confirmed` without new corroborating signal in 7 days → auto-demotes to `watch`
- `watch` without new signal in 14 days → auto-removed
Stale shortages never persist silently. Every demotion writes to the public revision log.
## Evidence transparency
Every public shortage row exposes its `evidenceSources[]` inline — you can read the sources the classifier used. This is what makes WorldMonitor's shortage registry defensible without an editorial queue.
For any `confirmed` row, the panel surfaces:
- Outlet / regulator names
- Source dates
- Classifier version + confidence
Agents (MCP clients) receive the same structured evidence via `listActiveFuelShortages` (landing in Release 2).
## Root-cause attribution
Every shortage row carries a cause chain, not just a severity:
- `chokepoint` — physical supply constraint traced to a chokepoint status change
- `pipeline_disruption` — specific pipeline in the registry is offline
- `sanction` — new sanctions authority list triggered an import cut
- `upstream_refinery` — refinery turnaround or outage
- `logistics` — port / rail / truck bottleneck
- `policy` — deliberate government restriction
## Break-glass overrides
A `energy_asset_overrides` table exists for the rare case where a reader emails a demonstrably wrong classification. Overrides are admin-only writes and are NOT on the critical path — the default flow is fully automated. Every override writes to the revision log.
## Known limits
- Non-English regulator feeds surface with some lag; we're adding them incrementally.
- "Watch" tier in a politically-noisy country can churn — that's intentional; readers can filter to `confirmed` only if they want the stricter view.
- Heating-oil shortages are seasonal and under-reported in wire coverage; winter months have higher signal.
## Corrections
Public revision log at [`/corrections`](/corrections). Every tier change ships
with its trigger (`classifier` / `source` / `decay` / `override`) and the
sources used. Corrections land on the next classifier pass (max 6 hours).

52
docs/methodology/storage.mdx Normal file
View File

@@ -0,0 +1,52 @@
---
title: "Storage Facility Methodology"
description: "How World Monitor curates the world's critical oil & gas storage facilities: underground gas storage, LNG terminals, SPR caverns, and crude tank farms."
---
## Scope
Release 1 launches with ~125 curated critical storage facilities, not a global census. Curation bias: facilities that move markets, not every tank farm on earth.
- **Underground gas storage (UGS):** top European sites (Rehden, Bergermeer, Haidach, Chiren, etc.), US salt caverns.
- **Strategic Petroleum Reserve caverns:** US SPR (Bryan Mound, Big Hill, West Hackberry, Bayou Choctaw), plus major non-US stockholding facilities where published.
- **LNG import & export terminals:** Sabine Pass, Corpus Christi, Ras Laffan, Yamal LNG, Asian regas hubs.
- **Crude oil tank farms:** major trading hubs (Cushing OK, Rotterdam, Singapore, Fujairah) where operator data is public.
## Data sources
- **[Global Energy Monitor](https://globalenergymonitor.org) — Storage Tracker** (CC-BY 4.0) for facility identity, geometry, capacity.
- **GIE AGSI+ & ALSI** for EU gas / LNG fill % at facility granularity (where published).
- **EIA Form EIA-191** for US UGS.
- **EIA SPR weekly stock report** for US SPR-level inventory.
- **Operator dashboards** where the facility publishes real-time or near-real-time fill %.
## Fill % — published, not synthesized
If an operator publishes fill %, we show it. If they don't, we show `not disclosed`. **We never synthesize, interpolate, or country-share a missing fill.**
When fill data is unavailable at the facility level, the panel falls back to country-level aggregate (e.g. "DE gas storage: 62% overall; Rehden facility fill not disclosed") — both numbers labeled with their source.
## Freshness SLA
| Object | Target freshness | Stale policy |
|--------|------------------|--------------|
| Facility registry (identity, capacity, operator) | 35 days | Silent refresh |
| Fill % where published | 24 hours | Fall back to country aggregate if stale |
| Country aggregate (fallback) | 24 hours (gas) / weekly (oil SPR) | Show `stale` indicator if beyond SLA |
## Known limits
- Not every facility publishes fill %. We indicate "not disclosed" explicitly.
- Capacity figures are typically nameplate, not current maximum working capacity. Working capacity tends to be 75–85% of nameplate for gas UGS.
- No forecast of storage-days-to-empty here; that computation lands on the country energy drill-down once the disruption log ships in Week 3.
## Attribution
Storage-facility registry data derived from [Global Energy Monitor](https://globalenergymonitor.org) (CC-BY 4.0), GIE AGSI+/ALSI (registered API usage), and US EIA open data.
## Corrections
Public revision log at [`/corrections`](/corrections). If a facility you
operate is misrepresented, we treat corrections directly from the operator as
top-tier evidence — open a GitHub issue or email the address listed in the
atlas footer.