fix(portwatch): rename date → date_ for IMF reserved-keyword sweep (koala73#3495)

IMF PortWatch ran a backend reserved-keyword rename on 2026-04-29
(date → date_, year → year_, month → month_, day → day_). Field aliases
stayed as the original names, but ArcGIS WHERE / outFields / orderByFields
/ outStatistics require the actual field name — alias ≠ queryable name.
Every per-country windowed query started failing with HTTP 400 "Cannot
perform query. Invalid query parameters." (00:04 UTC and 02:54 UTC runs
both 100% rejected, log lines 416-419 and 356-360 of the bundle output).

Diagnostic: error.details[] contains "'Invalid field: date' parameter is
invalid" — top-level message is generic, details has the real signal.
Confirmed via FeatureServer/0?f=json schema introspection.

Fix: rename all six in-code references (outFields, orderByFields, two
WHERE clauses, the per-row null-check on a.date_, and onStatisticField).
The `timestamp 'YYYY-MM-DD HH:MM:SS'` SQL literal still works on the new
esriFieldTypeDateOnly column, so the literal format is unchanged.

Hardening: add a first-batch circuit-breaker. When ≥80% of batch 1 is
rejected with the same "Invalid query parameters" error class, assume
global upstream regression and skip the remaining 14 batches — the
catch-path's extendExistingTtl preserves prior payloads. Cuts failure
cost from ~30s to ~2s and keeps Sentry signal-to-noise sane on the
next rename / policy change. The existing single-retry stays in place
for the original 3-of-N flake case (BRA/IDN/NGA, 2026-04-20).

Verified end-to-end against live ArcGIS:
  - patched WHERE returns features w/ attributes.date_ = "2026-03-30"
  - patched preflight returns max_date = "2026-04-24"

Test updates: two static-source assertions moved to date_; per-row
test-helper using r.date stays (it's an abstract aggregation test
unrelated to the ArcGIS shape).

Author: koala73

scripts/seed-portwatch-port-activity.mjs

@@ -94,6 +94,13 @@ async function fetchWithTimeout(url, { signal } = {}) {
 // also for the global WHERE after the PR #3225 rollout. A single retry with
 // a short back-off clears it in practice. No retry loop — one attempt
 // bounded. Does not retry any other error class.
+//
+// IMPORTANT: a 100%-batch-rejected version of this error is NOT a flake —
+// it's an upstream schema-rename (e.g. `date` → `date_` on 2026-04-29 via
+// IMF's reserved-keyword sweep, see fetchAll's first-batch circuit-breaker).
+// The single-retry assumption only holds for sporadic 3-of-N rejections;
+// the circuit-breaker handles the global-regression case to avoid burning
+// 30s of doomed work per cron tick.
 async function fetchWithRetryOnInvalidParams(url, { signal } = {}) {
   try {
     return await fetchWithTimeout(url, { signal });
@@ -156,9 +163,12 @@ async function paginateWindowInto(portAccumMap, iso3, where, windowKind, { signa
     if (signal?.aborted) throw signal.reason ?? new Error('aborted');
     const params = new URLSearchParams({
       where,
-      outFields: 'portid,portname,ISO3,date,portcalls_tanker,import_tanker,export_tanker',
+      // IMF PortWatch renamed `date` → `date_` on 2026-04-29 (reserved-keyword
+      // sweep, see ARCGIS_DATE_FIELD comment below). Field alias is still
+      // "date" but the queryable name is `date_` — alias ≠ name in ArcGIS.
+      outFields: 'portid,portname,ISO3,date_,portcalls_tanker,import_tanker,export_tanker',
       returnGeometry: 'false',
-      orderByFields: 'portid ASC,date ASC',
+      orderByFields: 'portid ASC,date_ ASC',
       resultRecordCount: String(PAGE_SIZE),
       resultOffset: String(offset),
       outSR: '4326',
@@ -168,7 +178,7 @@ async function paginateWindowInto(portAccumMap, iso3, where, windowKind, { signa
     const features = body.features ?? [];
     for (const f of features) {
       const a = f.attributes;
-      if (!a || a.portid == null || a.date == null) continue;
+      if (!a || a.portid == null || a.date_ == null) continue;
       const portId = String(a.portid);
       const calls = Number(a.portcalls_tanker ?? 0);
       const imports = Number(a.import_tanker ?? 0);
@@ -214,8 +224,8 @@ function parseMaxDateToAnchor(maxDateStr) {
 
 // Fetch ONE country's activity rows, streaming into per-port accumulators.
 // Splits into TWO parallel windowed queries:
-//   - Q1 (last30): WHERE ISO3='X' AND date > cutoff30
-//   - Q2 (prev30): WHERE ISO3='X' AND date > cutoff60 AND date <= cutoff30
+//   - Q1 (last30): WHERE ISO3='X' AND date_ > cutoff30
+//   - Q2 (prev30): WHERE ISO3='X' AND date_ > cutoff60 AND date_ <= cutoff30
 // Each returns ~half the rows a single 60-day query would. Heavy countries
 // (USA/CHN/etc.) drop from ~90s → ~30s because max(Q1,Q2) < Q1+Q2.
 //
@@ -238,18 +248,21 @@ async function fetchCountryAccum(iso3, { signal, anchorEpochMs } = {}) {
 
   const portAccumMap = new Map();
 
+  // ARCGIS_DATE_FIELD: queryable column is `date_`, not `date` — see comment
+  // on outFields above. The `timestamp 'YYYY-MM-DD HH:MM:SS'` literal still
+  // works on the new esriFieldTypeDateOnly column (verified 2026-04-29).
   await Promise.all([
     paginateWindowInto(
       portAccumMap,
       iso3,
-      `ISO3='${iso3}' AND date > ${epochToTimestamp(cutoff30)}`,
+      `ISO3='${iso3}' AND date_ > ${epochToTimestamp(cutoff30)}`,
       'last30',
       { signal },
     ),
     paginateWindowInto(
       portAccumMap,
       iso3,
-      `ISO3='${iso3}' AND date > ${epochToTimestamp(cutoff60)} AND date <= ${epochToTimestamp(cutoff30)}`,
+      `ISO3='${iso3}' AND date_ > ${epochToTimestamp(cutoff60)} AND date_ <= ${epochToTimestamp(cutoff30)}`,
       'prev30',
       { signal },
     ),
@@ -266,7 +279,10 @@ async function fetchCountryAccum(iso3, { signal, anchorEpochMs } = {}) {
 async function fetchMaxDate(iso3, { signal } = {}) {
   const outStats = JSON.stringify([{
     statisticType: 'max',
-    onStatisticField: 'date',
+    // See ARCGIS_DATE_FIELD comment in fetchCountryAccum: queryable name is
+    // `date_`, not `date`. outStatisticFieldName is the response key —
+    // unchanged on purpose so callers keep reading `attrs.max_date`.
+    onStatisticField: 'date_',
     outStatisticFieldName: 'max_date',
   }]);
   const params = new URLSearchParams({
@@ -521,6 +537,25 @@ export async function fetchAll(progress, { signal } = {}) {
       const elapsed = ((Date.now() - activityStart) / 1000).toFixed(1);
       console.log(`  [port-activity]   batch ${batchIdx}/${batches}: ${countryData.size} countries published, ${errors.length} errors (${elapsed}s)`);
     }
+
+    // Circuit-breaker: if batch 1 is ≥80% rejected with the SAME class of
+    // error, treat it as an upstream global regression (schema rename, policy
+    // change, dataset moved) — not a flake that more retries will clear.
+    // Skip the remaining batches and let the catch-path extendExistingTtl
+    // preserve prior payloads. Cuts failure cost ~30s → ~2s and keeps Sentry
+    // signal-to-noise sane during incidents like the 2026-04-29 IMF
+    // PortWatch `date` → `date_` rename.
+    if (batchIdx === 1 && batches > 1 && batch.length >= 5) {
+      const sameClassRate = errors.filter(e => /Invalid query parameters/i.test(e)).length / batch.length;
+      if (sameClassRate >= 0.8) {
+        console.error(
+          `  [port-activity] CIRCUIT-BREAKER: ${(sameClassRate * 100).toFixed(0)}% of batch 1 rejected with "Invalid query parameters" — ` +
+          `assuming upstream schema/policy regression. Skipping remaining ${batches - 1} batches; ` +
+          `catch-path will extend TTLs on prior payloads. First error: ${errors[0]}`,
+        );
+        break;
+      }
+    }
   }
 
   if (errors.length) {

tests/portwatch-port-activity-seed.test.mjs

@@ -51,9 +51,11 @@ describe('seed-portwatch-port-activity.mjs exports', () => {
     // H+F refactor: the WHERE clause is now built inline at the
     // paginateWindowInto call site (not as a `where:` param in a params
     // bag) because each window has a different date predicate.
-    assert.match(src, /`ISO3='\$\{iso3\}'\s+AND\s+date\s*>/);
+    // Field is `date_` post-2026-04-29 IMF reserved-keyword sweep (alias=date,
+    // queryable name=date_). See ARCGIS_DATE_FIELD comment in the seeder.
+    assert.match(src, /`ISO3='\$\{iso3\}'\s+AND\s+date_\s*>/);
     // Global where=date>X shape (PR #3225) must NOT be present.
-    assert.doesNotMatch(src, /where:\s*`date\s*>\s*\$\{epochToTimestamp\(since\)\}`/);
+    assert.doesNotMatch(src, /where:\s*`date_?\s*>\s*\$\{epochToTimestamp\(since\)\}`/);
   });
 
   it('EP4 refs query fetches all ports globally with where=1=1', () => {
@@ -129,7 +131,7 @@ describe('seed-portwatch-port-activity.mjs exports', () => {
   it('fetchMaxDate preflight uses outStatistics for cheap cache invalidation', () => {
     assert.match(src, /async function fetchMaxDate/);
     assert.match(src, /statisticType:\s*'max'/);
-    assert.match(src, /onStatisticField:\s*'date'/);
+    assert.match(src, /onStatisticField:\s*'date_'/);
   });
 
   it('fetchAll cache path: MGET preflight + maxDate check + reuse payload', () => {