Merge pull request #1303 from quanticsoul4772/upstream/wind-stale

fix(tools): flag stale wind forecasts in get_wind

changelog.d/1303-wind-stale.md

@@ -0,0 +1,2 @@
+- `get_wind` flags stale forecasts (`stale`) when the wind proxy serves a
+  cached model run (quanticsoul4772, #1303).

docs/CURRENT-STATE.md

@@ -6016,7 +6016,7 @@ closed. Performance and live agency reliability require recorded validation.
 
 ## Wind forecast models
 
-Wind supports selectable GFS/IFS models with persisted model choice. Each fetch chooses the available cycle and forecast step nearest the current time; rows show both issue and valid UTC timestamps. Grid identities include model, cycle, forecast step and any requested scalar field. The six model/field cache slots each retain the last two issued grids for manifest/grid rollover, coalesce concurrent requests, retain last-good data on failures and retry no faster than once per minute. Model changes clear the old field immediately, cancel old acquisition and ignore superseded results.
+Wind supports selectable GFS/IFS models with persisted model choice. Each fetch chooses the available cycle and forecast step nearest the current time; rows show both issue and valid UTC timestamps. Grid identities include model, cycle, forecast step and any requested scalar field. The six model/field cache slots each retain the last two issued grids for manifest/grid rollover, coalesce concurrent requests, retain last-good data on failures and retry no faster than once per minute. Model changes clear the old field immediately, cancel old acquisition and ignore superseded results. Last-good data is marked stale; the wind row shows it, and `get_wind` returns `stale` and adds "(forecast may be stale)" to its summary.
 
 ### Local Weather review candidate
 

src/tools/queries/atmosphere.js

@@ -204,10 +204,14 @@ export const getWind = defineTool({
     const speed = windSpeed(vector.u, vector.v);
     const from = windFrom(vector.u, vector.v);
     const kph = speed * 3.6;
+    // When the model upstream fails, the proxy keeps serving the last run it
+    // has, however old, marked stale.
+    const stale = snapshot.stale === true;
     return {
       summary:
         `Wind at ${point.label}: ${kph.toFixed(0)} km/h` +
-        (from === 'Calm' ? ', calm.' : ` from the ${from}.`),
+        (from === 'Calm' ? ', calm' : ` from the ${from}`) +
+        (stale ? ' (forecast may be stale).' : '.'),
       data: {
         view: suggestView(services, {
           point,
@@ -224,6 +228,7 @@ export const getWind = defineTool({
         level: snapshot.level ?? '10 m above ground',
         model,
         cycle: snapshot.cycle ?? null,
+        stale,
       },
     };
   },

src/tools/queries/atmosphere.test.mjs

@@ -148,6 +148,34 @@ test('wind is sampled from the model grid at the location', async () => {
   const calm = await catalog.call('get_wind', { location: { lat: 0, lon: 0 } });
   assert.equal(calm.summary, 'Wind at 0.0000, 0.0000: 0 km/h, calm.');
   assert.equal(calm.data.calm, true);
+  assert.equal(calm.data.stale, false);
+  // The proxy's last run, served while the model upstream fails.
+  const cached = composeCatalog({
+    tools: coreTools,
+    services: {
+      wind: {
+        getSnapshot: async (options) => ({
+          ...(await wind.getSnapshot(options)),
+          stale: true,
+          reason: 'Wind upstream unavailable',
+        }),
+      },
+    },
+  });
+  const stale = await cached.call('get_wind', { location: { lat: 0, lon: 0 } });
+  assert.equal(
+    stale.summary,
+    'Wind at 0.0000, 0.0000: 0 km/h, calm (forecast may be stale).',
+  );
+  assert.equal(stale.data.stale, true);
+  u.fill(10);
+  const staleWest = await cached.call('get_wind', {
+    location: { lat: 30.27, lon: -97.74 },
+  });
+  assert.equal(
+    staleWest.summary,
+    'Wind at 30.2700, -97.7400: 36 km/h from the W (forecast may be stale).',
+  );
   const down = composeCatalog({
     tools: coreTools,
     services: { wind: { getSnapshot: async () => ({ unavailable: true }) } },