mirror of
https://github.com/koala73/worldmonitor.git
synced 2026-04-25 17:14:57 +02:00
99b536bfb4
* docs(energy): /corrections revision-log page (Week 4 launch requirement)
All five methodology pages reference /corrections (the auto-revision-log
URL promised in the Global Energy Flow parity plan §20) but the page
didn't exist — clicks 404'd. This lands the page.
Content:
- Explains the revision-log shape: `{date, assetOrEventId, fieldChanged,
previousValue, newValue, trigger, sourcesUsed, classifierVersion}`.
- Defines the trigger vocabulary (classifier / source / decay / override)
so readers know what kind of change they're seeing.
- States the v1-launch truth honestly: the log is empty at launch and
fills as the post-launch classifier pass (in proactive-intelligence.mjs)
runs on its normal schedule. No fake entries, no placeholder rows.
- Documents the correction-submission path (operators / regulators /
researchers with public source URLs) and the contract that
corrections write `override`-trigger entries citing the submitted
source — not anonymous overrides.
- Cross-links all five methodology pages.
- Explains WHY we publish this: evidence-first classification only
works if the audit trail is public; otherwise "the classifier said
so" has no more authority than any other opaque pipeline.
Also fixes a navigation gap: docs/docs.json was missing both
methodology/disruptions (landed in PR #3294 but never registered in
nav) and the new corrections page. Both now appear in the "Intelligence
& Analysis" group alongside the other methodology pages.
No code changes. MDX lint + docs.json JSON validation pass.
* docs(energy): reframe /corrections as planned-surface spec (P1 review fix)
Greptile P1: the prior /corrections page made live-product claims
("writes an append-only entry here", "expect the first entries within
days", "email corrections@worldmonitor.app") that the code doesn't
back. The revision-log writer ships with the post-launch classifier;
the correction-intake pipeline does not yet exist; and the related
detail handlers still return empty `revisions` arrays with code
comments explicitly marking the surface as future work.
Fix: rewrite the page as a planned-surface specification with a
prominent Status callout. Changes:
- Page title: "Revision Log" → "Revision Log (Planned)"
- Prominent <Note> callout at the top states v1 launch truth: log is
not yet live, RPC `revisions` arrays are empty by design,
corrections are handled manually today.
- "Current state (v1 launch)" section removed; replaced with two
explicit sections: "What IS live today" (evidence bundles,
methodology, versioned classifier output) and "What is NOT live
today" (log entries, automated correction intake, override-writer).
- "Within days" timeline language removed — no false operational SLA.
- Email submission path removed (no automated intake exists). Points
readers to GitHub issues for manual review today.
- Preserves the planned data shape, trigger vocabulary, policy
commitment, and "why we publish this" framing — those are spec, not
claims.
Also softens /corrections references in the four methodology pages
(pipelines, storage, shortages, disruptions) so none of them claim
the revision log is live. Each now says "planned revision-log shape
and submission policy" and points manual corrections at GitHub issues.
MDX lint 122/122 clean. docs.json JSON validation clean. No code
changes; pure reframing to match reality.
* docs(shortages): fix P1 overclaim + wrong RPC name (round-2 review)
Two findings on the same file:
P1 — `energy_asset_overrides` table documented as existing. It doesn't.
The PR's corrections.mdx explicitly lists the override-writer as NOT
live in v1; this section contradicted that. Rewrote as "Break-glass
overrides (planned)" with a clear Status callout matching the pattern
established in docs/corrections.mdx and the other methodology pages.
Points readers at GitHub issues for manual corrections today.
P2 — Wrong RPC name: `listActiveFuelShortages` doesn't exist. The
shipped RPC (in proto/worldmonitor/supply_chain/v1/
list_fuel_shortages.proto + server/worldmonitor/supply-chain/v1/
list-fuel-shortages.ts) is `ListFuelShortages`. Replaced the name +
reframed the sentence to describe what the actual RPC already exposes
(every FuelShortageEntry includes evidence.evidenceSources[]) rather
than projecting a future surface.
Also swept the other methodology pages for the same class of bug:
- grep for _overrides: only the one line above
- grep for listActive/ getActive RPC names: none found
- verified all RPC mentions in docs/methodology + docs/corrections.mdx
match names actually in proto (ListPipelines, ListStorageFacilities,
ListFuelShortages, ListEnergyDisruptions, GetPipelineDetail,
GetStorageFacilityDetail, GetFuelShortageDetail)
MDX lint clean. No code changes.
* docs(methodology): round-3 sibling sweep for revision-log overclaims
Reviewer (Greptile) caught a third round of the same overclaim pattern
I've been trying to stamp out: docs/methodology/shortages.mdx line 46
said "Stale shortages never persist silently. Every demotion writes to
the public revision log." — contradicting the same PR's /corrections
page which explicitly frames the revision log as not-yet-live. Fixed
that one AND did the mechanical sibling sweep the review pattern
clearly called for.
Changes:
- `docs/methodology/shortages.mdx:46` — rewrote the auto-decay footer
to future tense: "When the post-launch classifier ships, stale
shortages will never persist silently — every demotion will write
an entry to the planned public revision log." Points readers at
/corrections for the designed shape. Notes that today the demotion
thresholds ARE the contract; the structured audit trail is what
lands with the classifier.
- `docs/methodology/chokepoints.mdx:64` — sibling sweep caught the
same bug class ("Every badge transition writes to the public
revision log"). Reworded to future tense and pointed manual
corrections at GitHub issues, matching the pattern already applied
to pipelines / storage / shortages in prior commits on this PR.
Final audit of remaining revision-log mentions across all 5
methodology pages + corrections.mdx — every one uses hedged tense now
("planned", "will", "when live", "designed", "not yet live", "once
the classifier ships"). The one remaining present-tense "emit" in
shortages.mdx:77 is inside the "(planned)" break-glass section with
its own Status callout, so it's correctly scoped.
Following the plan-doc-as-docs-source-overclaim skill's step-4
(sibling sweep) explicitly this time — which also retroactively
validates the skill extraction: three review rounds was the cost of
not running the sweep on round 1.
MDX lint clean. No code changes.
* docs(corrections): drop hardcoded launch date (Greptile P2)
Greptile inline P2 at docs/corrections.mdx:60: the phrase
"v1 launch (2026-04-23)" pins a specific calendar date that will read
inaccurately to visitors months later once entries start appearing.
Dropped the parenthetical date. "Status — v1 launch:" keeps the
scoping clear without tying it to a specific day. When live entries
start appearing on this page (or when the page is rewritten to show
real rows), a "last updated" marker will replace the status callout
entirely — no migration churn needed.
MDX lint 122/122 clean.
70 lines
3.3 KiB
Plaintext
70 lines
3.3 KiB
Plaintext
---
|
|
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
|
|
|
|
See [`/corrections`](/corrections) for the planned revision-log shape —
|
|
every badge transition will write an entry there once the classifier
|
|
ships. If you spot a wrong number today, open a GitHub issue at the
|
|
[public repository](https://github.com/koala73/worldmonitor/issues).
|
|
Corrections are handled manually in v1 and flow through the automated
|
|
`override`-trigger path once the classifier is live.
|