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

docs(energy): /corrections revision-log page (Week 4 launch requirement) (#3323)

Browse Source 
* 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.
This commit is contained in:
Elie Habib
2026-04-23 09:22:48 +04:00
committed by GitHub
parent 7f83e1e0c3
commit 99b536bfb4
7 changed files with 192 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

147
docs/corrections.mdx Normal file
View File

@@ -0,0 +1,147 @@
---
title: "Revision Log (Planned)"
description: "Specification for the public revision log that will surface every evidence change and public-badge transition across the Energy Atlas registries. The page documents the planned shape and status — the log itself is not yet live."
---
<Note>
**Status — v1 launch:** This page documents the planned
revision-log surface. **The public log itself is not yet live.**
What ships today on the Energy Atlas: the evidence bundles inside each
RPC response (`ListPipelines`, `ListStorageFacilities`,
`ListFuelShortages`, `ListEnergyDisruptions`), and the methodology pages
that describe how public badges are derived from those bundles. The
classifier that writes revision-log entries as a byproduct of normal
operation ships in a post-launch release. Until then:
`GetPipelineDetail.revisions` and `GetStorageFacilityDetail.revisions`
return empty arrays, and there is no automated correction-intake path.
This page exists so the data contract and submission policy are
documented **before** the surface goes live — not after.
</Note>
## What the revision log will be (when it ships)
WorldMonitor's Energy Atlas publishes evidence bundles — not opinions —
for pipelines, storage facilities, fuel shortages, and disruption
events. A deterministic, versioned classifier turns those bundles into
public badges (`flowing` / `reduced` / `offline` / `disputed` for
assets; `confirmed` / `watch` for shortages).
When the classifier goes live, every time it changes a public field —
because evidence updated, because staleness decayed a badge, because a
new classifier version re-derived an old asset, or because an
operator/regulator-submitted correction was applied — it will write an
append-only entry here.
This is the designed audit surface. The evidence registries themselves
are forward-looking snapshots; this log, once live, will be the history
of how each status arrived at where it is today.
## Planned data shape
Each entry is planned as a row with the following fields:
```ts
{
date: string, // ISO8601 — when the change was written
assetOrEventId: string, // matches an id in the pipeline / storage / shortage / disruption registry
fieldChanged: string, // e.g. 'publicBadge', 'physicalState', 'severity', 'evidence.sanctionRefs'
previousValue: unknown, // value before the change
newValue: unknown, // value after the change
trigger: 'classifier' | 'source' | 'decay' | 'override',
sourcesUsed: string[], // URLs cited by the classifier for this change
classifierVersion: string, // version that produced newValue (e.g. 'badge-deriver-v1')
}
```
The matching proto surface lives at
`GetPipelineDetail.revisions` and `GetStorageFacilityDetail.revisions`.
Both currently return empty arrays by design — the handlers document
"Revision log arrives in a post-launch release" in their code comments
rather than pretending the surface is live.
### Planned trigger vocabulary
- **`classifier`** — a routine classifier pass re-derives the field
from the current evidence bundle. Expected to be the most common
trigger once live.
- **`source`** — a new evidence source arrives (regulator filing,
operator press release, sanction list update) and the classifier
re-derives accordingly.
- **`decay`** — the evidence is older than the staleness window
(14 days for registry fields, 30 days for shortage evidence) and the
classifier demotes a non-positive badge to `disputed` or `watch`.
- **`override`** — a break-glass manual override is applied. Reserved
for demonstrably-wrong classifier outputs flagged by readers.
Overrides will carry the same `sourcesUsed` discipline as classifier
entries.
## What IS live today (v1 launch)
- **Evidence bundles on every asset.** Click any pipeline, storage
facility, or shortage pin on the [Energy Atlas](https://energy.worldmonitor.app)
and you see its full evidence bundle: physical state, commercial
state, operator statements (with URL and date), sanction references
(with authority + list ID + URL), classifier version and confidence,
and the timestamp of the most recent evidence update. This is the
primary audit surface today.
- **Public methodology pages.** The derivation rules, staleness
windows, and evidence-threshold specs are all publicly documented:
- [Pipeline Registry](/methodology/pipelines)
- [Storage Facilities](/methodology/storage)
- [Fuel Shortages](/methodology/shortages)
- [Disruption Event Log](/methodology/disruptions)
- [Chokepoints](/methodology/chokepoints)
- **Versioned classifier output.** Every RPC response carries a
`classifier_version` field. A reader can pin expectations to a
version today even though the revision-log history-of-versions
surface isn't yet published.
## What is NOT live today
- The revision-log entries themselves (this page will list real rows
once the classifier ships).
- An automated correction-intake pipeline. If you spot something
wrong, use the feedback channels at
[worldmonitor.app](https://worldmonitor.app) or open a GitHub issue
at the [public repository](https://github.com/koala73/worldmonitor/issues).
Corrections are not yet on the classifier's path — they're handled
manually today.
- The `override`-trigger entry writer. Same dependency: ships with the
classifier.
## Verifying a badge today (pre-classifier)
Until the revision log is live, the audit path for any status on the
Energy Atlas is:
1. Open the asset drawer (click the pipeline / storage dot / shortage
pin).
2. Read the evidence bundle — every source is linked with publication
date and authority (`regulator` / `operator` / `press` /
`satellite`).
3. Check the methodology page for the asset class — the derivation
rules are deterministic and versioned.
4. If all evidence is current and the public badge still looks wrong
after walking the rules, open an issue on the public repository
with the asset id, the current evidence bundle, and your reasoning.
The manual review path will seed `override` entries once the
revision log ships.
## Why document this surface before it ships
Two reasons to publish the spec before the writer lands:
1. **Contract stability.** The shape of `revisions` in
`GetPipelineDetail.revisions` / `GetStorageFacilityDetail.revisions`
is part of the RPC contract that agents and MCP clients consume.
Documenting it now means downstream consumers can code against the
stable shape before live data arrives.
2. **Policy signalling.** Evidence-first classification only works if
the audit trail is committed-to in public, not treated as an
internal implementation detail. Publishing the planned shape and
submission policy ahead of the writer is the commitment.
Neither reason justifies overstating the current state. When live
entries start appearing on this page, the `Status` callout at the top
will be replaced with a "last updated" timestamp and the "NOT live"
section will be removed.

2
docs/docs.json
View File

@@ -91,6 +91,8 @@
"methodology/pipelines",
"methodology/storage",
"methodology/shortages",
"methodology/disruptions",
"corrections",
"geographic-convergence",
"strategic-risk",
"algorithms"

10
docs/methodology/chokepoints.mdx
View File

@@ -61,7 +61,9 @@ The footer is an `HTMLElement` with `data-attr-source`, `data-attr-n`, `data-att
## 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.
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.

4
docs/methodology/disruptions.mdx
View File

@@ -57,7 +57,7 @@ Normal operational variation, routine nominations, and sub-daily flow shifts are
## 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.
- **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`](/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
@@ -74,7 +74,7 @@ Every event carries at least one source with a publicly-verifiable URL. `regulat
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 auto-logged at `/corrections` with `{field, previousValue, newValue, trigger, sourcesUsed, classifierVersion}` per entry. This is the real audit surface — the event log itself is forward-looking; the revision log is the history of how the log has evolved.
Changes are planned to be auto-logged at [`/corrections`](/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.
## Related methodology

12
docs/methodology/pipelines.mdx
View File

@@ -42,12 +42,14 @@ The visible `publicBadge` (`flowing | reduced | offline | disputed`) is a determ
## 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:
The designed audit surface is a public revision log that records every transition flipping a public status, as:
- `{ 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.
**Status (v1 launch):** the revision-log surface is not yet live — see [`/corrections`](/corrections) for the planned shape and current state. The classifier that writes entries ships post-launch. Today, the audit path is the evidence bundle embedded in each RPC response + the methodology on this page.
## Freshness SLA
- Pipeline registry fields (geometry, operator, capacity): 35 days
@@ -65,6 +67,8 @@ Pipeline-registry data derived from [Global Energy Monitor](https://globalenergy
## 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.
See [`/corrections`](/corrections) for the planned revision-log shape
and submission policy. Spot a wrong status? Open a GitHub issue at the
[public repository](https://github.com/koala73/worldmonitor/issues).
Corrections are handled manually today and will flow through the
automated `override`-trigger path once the classifier ships.

27
docs/methodology/shortages.mdx
View File

@@ -43,7 +43,7 @@ AND — the LLM second-pass must agree with the promotion. If the LLM disagrees,
- `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.
When the post-launch classifier ships, stale shortages will never persist silently — every demotion will write an entry to the planned public revision log. See [`/corrections`](/corrections) for the designed audit-surface shape and current status. Today the demotion thresholds above are the contract; the structured audit trail lands with the classifier.
## Evidence transparency
@@ -55,7 +55,7 @@ For any `confirmed` row, the panel surfaces:
- Source dates
- Classifier version + confidence
Agents (MCP clients) receive the same structured evidence via `listActiveFuelShortages` (landing in Release 2).
Agents (MCP clients) receive the same structured evidence via the `ListFuelShortages` RPC — every `FuelShortageEntry` in the response includes the full `evidence.evidenceSources[]` array, matching what the UI drawer renders.
## Root-cause attribution
@@ -68,9 +68,20 @@ Every shortage row carries a cause chain, not just a severity:
- `logistics` — port / rail / truck bottleneck
- `policy` — deliberate government restriction
## Break-glass overrides
## Break-glass overrides (planned)
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.
An `energy_asset_overrides` persistence layer is the designed break-glass
surface for the rare case where a reader flags a demonstrably wrong
classification. Writes would be admin-only and off the critical path —
the default flow stays fully automated, and every override would emit
an `override`-trigger entry to the revision log.
**Status (v1 launch):** the override persistence layer is not yet
implemented. Reader-flagged corrections are handled manually today via
[GitHub issues](https://github.com/koala73/worldmonitor/issues); they
flow through the automated override path once that layer ships
alongside the classifier. See [`/corrections`](/corrections) for the
planned shape of override entries.
## Known limits
@@ -80,6 +91,8 @@ A `energy_asset_overrides` table exists for the rare case where a reader emails
## 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).
See [`/corrections`](/corrections) for the planned revision-log shape
(every tier change will ship with its trigger — `classifier` / `source`
/ `decay` / `override` — and the sources used). The classifier that
writes entries ships post-launch; corrections are handled manually
today via [GitHub issues](https://github.com/koala73/worldmonitor/issues).

11
docs/methodology/storage.mdx
View File

@@ -46,7 +46,10 @@ Storage-facility registry data derived from [Global Energy Monitor](https://glob
## 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.
See [`/corrections`](/corrections) for the planned revision-log shape
and submission policy. If a facility you operate is misrepresented, we
treat corrections directly from the operator as top-tier evidence —
open a GitHub issue at the
[public repository](https://github.com/koala73/worldmonitor/issues).
Automated `override`-trigger entries ship with the post-launch
classifier; corrections are handled manually today.