@volter/twin-openweather

A local OpenWeather twin — offline, deterministic replicas of the OpenWeather request→response APIs (api.openweathermap.org) in vendor-faithful response shapes, with the real appid= API-key gate and 401/404/429 error semantics. An unmodified HTTP client (or any OpenWeather SDK) pointed at it gets OpenWeather-correct responses.

world-openweather serve [--port N] [--root DIR] [--read-only]
world-openweather conformance [--root DIR]

Coverage

The capability manifest (src/openweather-capabilities.ts) is an honest partial denominator across all OpenWeather products. A core slice across the high-value products is done (each with a failable, deterministic verify asserting response values plus a negative 4xx path); the long tail (less-common products and parameter variants) is honest todo. Total surface is >= 50 entries; this is the live denominator, not a self-portrait — it reads LOW on purpose and grows as more products are modeled.

Deterministic canned weather, NOT real meteorology. A local twin cannot reproduce real weather-station observations, live satellite/radar feeds, or rendered map-tile pixels. It returns faithful response shapes with stable, deterministic VALUES derived from (lat, lon): a given coordinate always maps to the same canned weather. Latitude drives a plausible climate gradient; the condition, wind, humidity, pressure, etc. are hash-derived and repeatable offline.

Modeled (done):

• Auth gate. Every product gates on the appid= query parameter (or the X-Api-Key header). Missing/invalid key → HTTP 401 in OpenWeather's own { cod, message } envelope; sentinel keys (rate-limited/over-quota) → HTTP 429.
• Current Weather Data (/data/2.5/weather) — the FULL real shape (coord, weather[], base, main{temp,feels_like,temp_min,temp_max,pressure,humidity, sea_level,grnd_level}, visibility, wind{speed,deg,gust}, clouds{all}, dt, sys{type,id,country,sunrise,sunset}, timezone, id, name, cod:200). Honors units (Kelvin/Celsius/Fahrenheit), lang (localized description), and city resolution via q=. Matches the QA-stack main.temp contract exactly.
• 5 day / 3 hour Forecast (/data/2.5/forecast) — list[] of 40 3-hourly entries (main incl. temp_kf, weather, clouds, wind, pop, sys.pod, dt_txt), plus city{id,name,coord,country,population,timezone,sunrise,sunset}; honors cnt + units.
• One Call API 3.0 (/data/3.0/onecall) — current, minutely[61], hourly[48], daily[8] (with temp/feels_like sub-objects + moon phase + summary), and alerts[]; honors the exclude parameter; plus /onecall/timemachine (historical by dt), /onecall/day_summary (aggregated daily by date), and /onecall/overview (a deterministic weather_overview string).
• Geocoding (/geo/1.0/*) — direct (city → array, limit capped at 5, local_names), zip (postal code → single object, 404 on unknown), reverse (coordinate → nearest city array).
• Air Pollution (/data/2.5/air_pollution{,/forecast,/history}) — list[] of { dt, main:{ aqi:1-5 }, components:{ co,no,no2,o3,so2,pm2_5,pm10, nh3 } }; forecast = 96 hourly samples; history honors start/end.
• Weather Maps 1.0 & 2.0 — /map/{layer}/{z}/{x}/{y}.png (the five 1.0 layers: clouds/precipitation/pressure/wind/temp) and /maps/2.0/weather/{op}/{z}/{x}/{y} (op codes TA2/PR0/WND/CL/APM/...). Each validates the layer/op and returns tile metadata (404 on unknown layer/op); serving PNG bytes at those routes is a planned todo.
• Audit + state. A local audit log of requests (GET /twin/audit, read-only requests not logged); connector-seeded per-coordinate observation overrides served by Current Weather.
• Connector. Injected-client pull of current-weather observations (pullOpenWeatherObservations), idempotent on the coordinate key; the kernel adapter performOpenWeatherAction handles supported observation entries. This does not create a write API on the real weather service.

Not yet modeled (honest todo): mode=xml/html output; Current Weather by id/bounding-box/group/find; rain/snow precipitation volume fields; Hourly-4-day / Daily-16-day / Climatic-30-day forecasts; the AI Weather Assistant session API; geocoding state/country qualifiers; Weather Maps 2.0 full 14-layer set + palette/opacity params; Global Precipitation & Relief maps; the Solar Irradiance / Panel Energy APIs; Fire Weather Index API + Maps; Road Risk API; the History / Statistical / Accumulated / Bulk APIs; the Weather Stations API; deterministic PNG bytes served at the Weather Maps tile routes.

Architecture

State lives in the @volter/world-core event/action log (observation overrides + the audit log); there is no ad-hoc store. The serve path makes no real network calls; connector functions accept injected executors for real OpenWeather I/O and are not used by the local handler. This is an API-first vendor with no operator-facing dashboard, so the pack ships no UI mirror — coverage is API + connector. The fidelity test drives the twin over real-transport fetch (there is no canonical first-party OpenWeather SDK).