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.
148 lines
6.9 KiB
Plaintext
148 lines
6.9 KiB
Plaintext
---
|
|
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.
|