From 6d6ce364c684bffb01fb2af1ef18b4a29579d42a Mon Sep 17 00:00:00 2001
From: Mazeyar Moeini Feizabadi <mazeyar@halfpixel.ai>
Date: Fri, 16 Oct 2026 02:03:16 +0200
Subject: [PATCH] docs(cyclones): document the early-advisory window and pin
 its bounds

Maintainer follow-up for #741, no runtime change.

- CURRENT-STATE: advisory issue and position times up to and including
  90 minutes ahead of the server clock are accepted because NHC can release
  advisories before their nominal time; 90 minutes is the app's tolerance,
  not an NHC limit. Later, non-canonical and over-12-hour-old times still
  reject the snapshot.
- Tests: pin exact 90-minute acceptance and +1 ms rejection, and exact
  12-hour acceptance and +1 ms rejection, for issuance and lastUpdate
  independently; the early-publication test now asserts
  invalid_cyclone_data.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/CURRENT-STATE.md           |  7 ++++++-
 src/data/cyclonesProxy.test.mjs | 33 +++++++++++++++++++++++++++++++--
 2 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md
index e5b3d2ace..0af075a6d 100644
--- a/docs/CURRENT-STATE.md
+++ b/docs/CURRENT-STATE.md
@@ -339,7 +339,12 @@ Cyclones combine fixed NHC/CPHC status and summary GIS endpoints through a bound
 same-origin provider. The status endpoint lacks browser CORS; each installation
 fetches keyless public sources at runtime, with no centralized ingestion service.
 The five-minute snapshot covers Atlantic and eastern/central North Pacific only.
-Current positions, advisory issue time and position time stay distinct. Tracks,
+Current positions, advisory issue time and position time stay distinct. NHC may
+release an advisory before its nominal time (routinely up to about 30 minutes,
+rarely about an hour), so advisory issue and position times up to and including
+90 minutes ahead of the server clock are accepted; 90 minutes is this app's
+tolerance, not an NHC limit. Later, non-canonical, or more than 12-hour-old
+times still reject the status snapshot. Tracks,
 forecast lead-hour points and cones render only when all source parts match the
 status advisory; a newer status shows its position with geometry pending rather
 than relabeling older geometry. The cone represents forecast center uncertainty,
diff --git a/src/data/cyclonesProxy.test.mjs b/src/data/cyclonesProxy.test.mjs
index 31433b326..23e84826c 100644
--- a/src/data/cyclonesProxy.test.mjs
+++ b/src/data/cyclonesProxy.test.mjs
@@ -166,11 +166,40 @@ test('advisories published before their nominal time are accepted, far-future on
   // NHC wrote the 03:00Z advisory at 02:34Z.
   const early = Date.UTC(2026, 8, 16, 2, 34);
   assert.equal(parseCycloneStatus(status(), early)[0].issuedAt, TIME);
-  assert.throws(() =>
-    parseCycloneStatus(status(), Date.UTC(2026, 8, 16, 1, 25)),
+  assert.throws(
+    () => parseCycloneStatus(status(), Date.UTC(2026, 8, 16, 1, 25)),
+    /invalid_cyclone_data/,
   );
 });
 
+test('advisory and position times are bounded at 90 minutes ahead and 12 hours old', () => {
+  const MINUTE = 60_000;
+  const at = (offsetMs) => new Date(NOW + offsetMs).toISOString();
+  const fields = {
+    issuedAt: (value) =>
+      status({
+        forecastAdvisory: {
+          advNum: '010',
+          issuance: value,
+          url: 'https://www.nhc.noaa.gov/text/MIATCMEP5.shtml',
+        },
+      }),
+    positionAt: (value) => status({ lastUpdate: value }),
+  };
+  for (const [field, payload] of Object.entries(fields)) {
+    for (const offset of [90 * MINUTE, -12 * 60 * MINUTE]) {
+      const [storm] = parseCycloneStatus(payload(at(offset)), NOW);
+      assert.equal(storm[field], at(offset), `${field} ${offset}`);
+    }
+    for (const offset of [90 * MINUTE + 1, -12 * 60 * MINUTE - 1])
+      assert.throws(
+        () => parseCycloneStatus(payload(at(offset)), NOW),
+        /invalid_cyclone_data/,
+        `${field} ${offset}`,
+      );
+  }
+});
+
 test('coherent geometry is retained with holes/dateline while older advisory geometry is omitted', () => {
   const storms = parseCycloneStatus(status(), NOW);
   const parts = collections();