Merge branch 'main' into fix/api-method-guard

server/providers/acartia.js

@@ -0,0 +1,181 @@
+import { normalizeAcartiaSightings } from '../../src/layers/wildlifeSightings/records.js';
+import { coalesceProxyRequest, readResponseJsonCapped } from './common/http.js';
+import { makeRateLimiter, clientKey } from './common/rate-limit.js';
+import { admitSameSiteKeyless } from './common/same-site.js';
+import { providerUserAgent } from './common/userAgent.js';
+
+const API_URL = 'https://acartia.io/api/v1/sightings/current';
+// All views share the provider's seven-day snapshot.
+const TTL_MS = 600_000;
+const STALE_MAX_MS = 24 * 60 * 60_000;
+const MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+const TIMEOUT_MS = 15_000;
+const COOLDOWN_MS = 60_000;
+const COOLDOWN_MIN_MS = 5000;
+const COOLDOWN_MAX_MS = 60 * 60_000;
+const FAILURE_COOLDOWN_MS = 15_000;
+
+/** Bound upstream Retry-After seconds or dates to five seconds–one hour. */
+export function acartiaRetryCooldownMs(raw, nowMs) {
+  const value = typeof raw === 'string' ? raw.trim() : '';
+  if (value) {
+    const seconds = /^\d+(?:\.\d+)?$/.test(value) ? Number(value) : NaN;
+    const deadline =
+      !Number.isFinite(seconds) && /[a-z]/i.test(value)
+        ? Date.parse(value)
+        : NaN;
+    const delay = Number.isFinite(seconds) ? seconds * 1000 : deadline - nowMs;
+    if (Number.isFinite(delay) && delay >= 0)
+      return Math.min(COOLDOWN_MAX_MS, Math.max(COOLDOWN_MIN_MS, delay));
+  }
+  return COOLDOWN_MS;
+}
+
+/** Salish Sea coverage. Precise coordinates and comments never enter cache. */
+export function acartiaProxy({
+  fetchImpl = (...args) => globalThis.fetch(...args),
+  now = () => Date.now(),
+  cache = new Map(),
+  warn = (...args) => console.warn(...args),
+} = {}) {
+  const inFlight = new Map();
+  const allow = makeRateLimiter({
+    windowMs: 60_000,
+    max: 60,
+    globalMax: 600,
+    now,
+  });
+  let cooldownUntil = 0;
+  let cooldownStatus = 429;
+  let warnedClamp = false;
+
+  const retrySeconds = () =>
+    Math.max(1, Math.ceil((cooldownUntil - now()) / 1000));
+  const unavailable = (status = 502) =>
+    Object.assign(new Error('acartia_unavailable'), {
+      status,
+      retryAfterS: retrySeconds(),
+    });
+
+  function coolDown(status, delay) {
+    const until = now() + delay;
+    if (until > cooldownUntil) {
+      cooldownUntil = until;
+      cooldownStatus = status;
+    } else if (status === 429 && now() < cooldownUntil) cooldownStatus = 429;
+  }
+
+  async function load() {
+    if (now() < cooldownUntil) throw unavailable(cooldownStatus);
+    const signal = AbortSignal.timeout(TIMEOUT_MS);
+    try {
+      const response = await fetchImpl(API_URL, {
+        signal,
+        redirect: 'error',
+        headers: {
+          Accept: 'application/json',
+          'User-Agent': providerUserAgent('wildlife-sightings'),
+        },
+      });
+      if (!response.ok) {
+        await response.body?.cancel().catch(() => {});
+        if (response.status === 429) {
+          const delay = acartiaRetryCooldownMs(
+            response.headers.get('retry-after'),
+            now(),
+          );
+          if (delay === COOLDOWN_MAX_MS && !warnedClamp) {
+            warnedClamp = true;
+            warn('[acartia-proxy] upstream cooldown capped at one hour');
+          }
+          coolDown(429, delay);
+          throw unavailable(429);
+        }
+        throw unavailable();
+      }
+      // This endpoint documents a JSON array, not a results/data envelope.
+      const payload = await readResponseJsonCapped(
+        response,
+        MAX_RESPONSE_BYTES,
+        signal,
+      );
+      const rows = normalizeAcartiaSightings(payload, now());
+      // Only a non-array is malformed. A quiet feed, or one whose rows all fall
+      // outside coverage or the species checks, is a valid empty snapshot.
+      if (!rows) throw new Error('invalid_snapshot');
+      return { fetchedAt: now(), rows };
+    } catch (error) {
+      if (error.status !== 429) coolDown(502, FAILURE_COOLDOWN_MS);
+      warn('[acartia-proxy] upstream refresh failed');
+      throw unavailable(error.status === 429 ? 429 : 502);
+    }
+  }
+
+  function age(entry) {
+    if (!entry) return Infinity;
+    const elapsed = now() - entry.savedAt;
+    return elapsed < 0 ? Infinity : elapsed;
+  }
+
+  async function acquire() {
+    const previous = cache.get('sightings');
+    if (age(previous) < TTL_MS) return { value: previous.value, stale: false };
+    if (age(previous) > STALE_MAX_MS) cache.delete('sightings');
+    try {
+      const { promise } = coalesceProxyRequest(
+        inFlight,
+        'sightings',
+        async () => {
+          const value = await load();
+          cache.set('sightings', { value, savedAt: now() });
+          return value;
+        },
+      );
+      return { value: await promise, stale: false };
+    } catch (error) {
+      if (age(previous) <= STALE_MAX_MS)
+        return { value: previous.value, stale: true };
+      throw error;
+    }
+  }
+
+  async function handler(req, res) {
+    const json = (status, value, { stale = false, retryAfterS } = {}) => {
+      if (res.destroyed) return;
+      res.writeHead(status, {
+        'Content-Type': 'application/json',
+        'Cache-Control': 'no-store',
+        ...(status === 405 ? { Allow: 'GET' } : {}),
+        ...(retryAfterS ? { 'Retry-After': String(retryAfterS) } : {}),
+        ...(stale ? { 'X-Data-Stale': 'true' } : {}),
+      });
+      res.end(JSON.stringify(value));
+    };
+    if (admitSameSiteKeyless(req, res)) return;
+    if (req.method !== 'GET') return json(405, { error: 'method_not_allowed' });
+    const pathname = (req.url || '/').split('?')[0];
+    if (pathname !== '/sightings') return json(404, { error: 'unknown_route' });
+    if (!allow(clientKey(req)))
+      return json(429, { error: 'rate_limited' }, { retryAfterS: 60 });
+    try {
+      const { value, stale } = await acquire();
+      return json(200, stale ? { ...value, stale: true } : value, { stale });
+    } catch (error) {
+      return json(
+        error.status === 429 ? 429 : 502,
+        { error: 'acartia_unavailable' },
+        { retryAfterS: error.retryAfterS },
+      );
+    }
+  }
+
+  return {
+    name: 'acartia',
+    configureServer({ middlewares }) {
+      middlewares.use('/api/acartia', handler);
+    },
+    configurePreviewServer({ middlewares }) {
+      middlewares.use('/api/acartia', handler);
+    },
+  };
+}

server/providers/acartia.test.mjs

@@ -0,0 +1,419 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { acartiaProxy, acartiaRetryCooldownMs } from './acartia.js';
+
+const NOW = Date.parse('2026-11-04T18:05:00Z');
+const sighting = (id = 'synthetic-1') => ({
+  entry_id: id,
+  latitude: 48.12345,
+  longitude: -123.12345,
+  created: '2026-11-04 17:00:00',
+  type: 'Orca',
+  no_sighted: '5',
+  photo_url: 'https://provider.example/photos/synthetic.jpg',
+  data_source_name: 'Synthetic Whale Network',
+  data_source_entity: 'Community reports',
+  trusted: true,
+  data_source_comments: '[email protected] +1-555-000-0000',
+});
+
+function install(options = {}, hook = 'configureServer') {
+  let handler;
+  const plugin = acartiaProxy({ now: () => NOW, warn() {}, ...options });
+  assert.equal(plugin.name, 'acartia');
+  assert.equal(typeof plugin.configureServer, 'function');
+  assert.equal(typeof plugin.configurePreviewServer, 'function');
+  plugin[hook]({
+    middlewares: {
+      use(mount, callback) {
+        assert.equal(mount, '/api/acartia');
+        handler = callback;
+      },
+    },
+  });
+  return async (
+    url = '/sightings',
+    { method = 'GET', peer = 'local', headers = {} } = {},
+  ) => {
+    const res = {
+      headers: {},
+      writeHead(status, headers) {
+        this.status = status;
+        this.headers = headers;
+      },
+      setHeader(key, value) {
+        this.headers[key] = value;
+      },
+      end(value) {
+        this.status ??= this.statusCode;
+        this.body = JSON.parse(value);
+      },
+    };
+    await handler(
+      { url, method, headers, socket: { remoteAddress: peer } },
+      res,
+    );
+    return res;
+  };
+}
+
+test('cache stores only supported marine mammals inside the coverage box', async () => {
+  const cache = new Map();
+  const request = install({
+    cache,
+    fetchImpl: async () =>
+      Response.json([
+        sighting('orca'),
+        { ...sighting('seal'), type: 'Harbor seal' },
+        { ...sighting('unknown'), type: 'Unknown' },
+        { ...sighting('fish'), type: 'Whale shark' },
+        { ...sighting('outside'), latitude: 37.8 },
+        { ...sighting('rounded-edge'), latitude: 45.49999 },
+      ]),
+  });
+  const result = await request();
+  assert.equal(result.status, 200);
+  for (const rows of [result.body.rows, cache.get('sightings').value.rows]) {
+    assert.deepEqual(
+      rows.map((row) => [row.stableId, row.cetacean]),
+      [
+        ['acartia:orca', true],
+        ['acartia:seal', false],
+      ],
+    );
+  }
+});
+
+for (const hook of ['configureServer', 'configurePreviewServer']) {
+  test(`${hook}: documented array is normalized and coarsened before caching`, async () => {
+    const cache = new Map();
+    let calls = 0;
+    const request = install(
+      {
+        cache,
+        fetchImpl: async (url, options) => {
+          calls += 1;
+          assert.equal(url, 'https://acartia.io/api/v1/sightings/current');
+          assert.equal(options.redirect, 'error');
+          assert.ok(options.signal instanceof AbortSignal);
+          assert.equal(options.headers.Accept, 'application/json');
+          assert.equal(
+            options.headers['User-Agent'],
+            'gods-eye-view-wildlife-sightings-proxy/1.0 (+https://github.com/bilawalsidhu/gods-eye-view)',
+          );
+          return Response.json([sighting()]);
+        },
+      },
+      hook,
+    );
+    assert.equal(calls, 0);
+    assert.equal(cache.size, 0);
+    const result = await request(
+      '/sightings?url=https://attacker.example&latitude=1',
+    );
+    assert.equal(result.status, 200);
+    assert.equal(result.headers['Cache-Control'], 'no-store');
+    assert.equal(result.body.fetchedAt, NOW);
+    assert.equal(result.body.rows[0].stableId, 'acartia:synthetic-1');
+    assert.equal(result.body.rows[0].lat, 48.12);
+    assert.equal(result.body.rows[0].lon, -123.12);
+    assert.equal(result.body.rows[0].provider.name, 'Synthetic Whale Network');
+    const retained = cache.get('sightings');
+    assert.equal(retained.value.rows[0].lat, 48.12);
+    assert.equal(retained.value.rows[0].lon, -123.12);
+    for (const value of [result.body, [...cache.values()]])
+      assert.doesNotMatch(
+        JSON.stringify(value),
+        /private-observer|555|data_source_comments|48\.12345|123\.12345/,
+      );
+    assert.equal(calls, 1);
+  });
+}
+
+test('gate, method and fixed route run before cache or upstream', async () => {
+  const cache = new Map();
+  let calls = 0;
+  const request = install({
+    cache,
+    fetchImpl: async () => {
+      calls += 1;
+      return Response.json([sighting()]);
+    },
+  });
+  for (let i = 0; i < 65; i += 1) {
+    assert.equal(
+      (
+        await request('/sightings', {
+          headers: {
+            host: 'localhost:5173',
+            origin: 'https://foreign.example',
+            'sec-fetch-site': 'cross-site',
+          },
+        })
+      ).status,
+      403,
+    );
+  }
+  const method = await request('/sightings', { method: 'POST' });
+  assert.equal(method.status, 405);
+  assert.equal(method.headers.Allow, 'GET');
+  for (const route of ['/', '/unknown', '/sightings/extra']) {
+    const result = await request(route);
+    assert.equal(result.status, 404);
+    assert.equal(result.body.error, 'unknown_route');
+  }
+  assert.equal(calls, 0);
+  assert.equal(cache.size, 0);
+  const sameOrigin = await request('/sightings', {
+    headers: {
+      host: 'gev.example',
+      origin: 'https://gev.example',
+      'sec-fetch-site': 'same-origin',
+      'x-forwarded-proto': 'https',
+      'x-forwarded-for': '203.0.113.9',
+    },
+  });
+  assert.equal(sameOrigin.status, 200);
+});
+
+test('request 61 is locally limited even with a fresh cache', async () => {
+  let calls = 0;
+  const request = install({
+    fetchImpl: async () => {
+      calls += 1;
+      return Response.json([sighting()]);
+    },
+  });
+  for (let i = 0; i < 60; i += 1) assert.equal((await request()).status, 200);
+  const limited = await request();
+  assert.equal(limited.status, 429);
+  assert.equal(limited.body.error, 'rate_limited');
+  assert.equal(limited.headers['Retry-After'], '60');
+  assert.equal(calls, 1);
+});
+
+test('one global snapshot single-flights and stays fresh for ten minutes', async () => {
+  let at = NOW;
+  let calls = 0;
+  let release;
+  const request = install({
+    now: () => at,
+    fetchImpl: async () => {
+      calls += 1;
+      if (calls === 1)
+        await new Promise((resolve) => {
+          release = resolve;
+        });
+      return Response.json([sighting()]);
+    },
+  });
+  const first = request();
+  const concurrent = request();
+  await new Promise(setImmediate);
+  assert.equal(calls, 1);
+  release();
+  assert.deepEqual((await first).body, (await concurrent).body);
+  at += 599_999;
+  await request();
+  assert.equal(calls, 1);
+  at += 1;
+  await request();
+  assert.equal(calls, 2);
+});
+
+test('a valid empty or fully filtered snapshot is a fresh success that clears old rows', async () => {
+  for (const quiet of [
+    [],
+    [null],
+    [{ ...sighting(), data_source_name: '' }],
+    [{ ...sighting(), latitude: 37.8 }],
+    [{ ...sighting(), type: 'Unknown' }],
+  ]) {
+    let at = NOW;
+    let calls = 0;
+    let empty = false;
+    const cache = new Map();
+    const request = install({
+      cache,
+      now: () => at,
+      fetchImpl: async () => {
+        calls += 1;
+        return Response.json(empty ? quiet : [sighting()]);
+      },
+    });
+    assert.equal((await request()).body.rows.length, 1);
+    empty = true;
+    at += 600_001;
+    const result = await request();
+    assert.equal(result.status, 200);
+    assert.deepEqual(result.body, { fetchedAt: at, rows: [] });
+    assert.equal(result.headers['X-Data-Stale'], undefined);
+    assert.equal(result.headers['Retry-After'], undefined);
+    assert.deepEqual(cache.get('sightings').value.rows, []);
+    // The quiet feed keeps the normal ten-minute cadence, not a failure retry.
+    at += 599_999;
+    assert.equal((await request()).status, 200);
+    assert.equal(calls, 2);
+    at += 1;
+    await request();
+    assert.equal(calls, 3);
+    const cold = install({ fetchImpl: async () => Response.json(quiet) });
+    const coldResult = await cold();
+    assert.equal(coldResult.status, 200);
+    assert.deepEqual(coldResult.body, { fetchedAt: NOW, rows: [] });
+  }
+});
+
+test('an invented wrapped snapshot never replaces the cache', async () => {
+  const bad = { results: [sighting()] };
+  let at = NOW;
+  let fail = false;
+  const cache = new Map();
+  const request = install({
+    cache,
+    now: () => at,
+    fetchImpl: async () => Response.json(fail ? bad : [sighting()]),
+  });
+  const fresh = await request();
+  const retained = cache.get('sightings');
+  fail = true;
+  at += 600_001;
+  const stale = await request();
+  assert.equal(stale.status, 200);
+  assert.equal(stale.headers['X-Data-Stale'], 'true');
+  assert.equal(stale.body.stale, true);
+  assert.equal(stale.body.fetchedAt, fresh.body.fetchedAt);
+  assert.equal(cache.get('sightings'), retained);
+  const coldCache = new Map();
+  const cold = install({
+    cache: coldCache,
+    fetchImpl: async () => Response.json(bad),
+  });
+  const result = await cold();
+  assert.equal(result.status, 502);
+  assert.equal(result.body.error, 'acartia_unavailable');
+  assert.equal(result.headers['Retry-After'], '15');
+  assert.equal(coldCache.size, 0);
+});
+
+test('failure serves stale for at most 24 hours and never reports a cold success', async () => {
+  let at = NOW;
+  let fail = false;
+  const request = install({
+    now: () => at,
+    fetchImpl: async () => {
+      if (fail) throw new Error('private upstream detail');
+      return Response.json([sighting()]);
+    },
+  });
+  const first = await request();
+  fail = true;
+  at += 23 * 60 * 60_000 + 59 * 60_000;
+  const stale = await request();
+  assert.equal(stale.status, 200);
+  assert.equal(stale.body.stale, true);
+  assert.equal(stale.body.fetchedAt, first.body.fetchedAt);
+  at += 2 * 60_000;
+  const expired = await request();
+  assert.equal(expired.status, 502);
+  assert.deepEqual(expired.body, { error: 'acartia_unavailable' });
+});
+
+test('upstream 429 honors Retry-After, caps it, and spends no requests while cooling down', async () => {
+  assert.equal(acartiaRetryCooldownMs('2', NOW), 5000);
+  assert.equal(acartiaRetryCooldownMs('999999', NOW), 3_600_000);
+  assert.equal(
+    acartiaRetryCooldownMs(new Date(NOW + 120_000).toUTCString(), NOW),
+    120_000,
+  );
+  assert.equal(acartiaRetryCooldownMs(null, NOW), 60_000);
+  let at = NOW;
+  let calls = 0;
+  const warnings = [];
+  const request = install({
+    now: () => at,
+    warn: (message) => warnings.push(message),
+    fetchImpl: async () => {
+      calls += 1;
+      return new Response('limit', {
+        status: 429,
+        headers: { 'Retry-After': '999999' },
+      });
+    },
+  });
+  const first = await request();
+  assert.equal(first.status, 429);
+  assert.equal(first.body.error, 'acartia_unavailable');
+  assert.equal(first.headers['Retry-After'], '3600');
+  at += 5000;
+  const cooling = await request();
+  assert.equal(cooling.headers['Retry-After'], '3595');
+  assert.equal(calls, 1);
+  assert.equal(
+    warnings.filter((message) => message.includes('capped')).length,
+    1,
+  );
+  at += 3_600_000;
+  await request();
+  assert.equal(calls, 2);
+  assert.equal(
+    warnings.filter((message) => message.includes('capped')).length,
+    1,
+  );
+});
+
+test('upstream 429 also serves a prior snapshot stale', async () => {
+  let at = NOW;
+  let fail = false;
+  let calls = 0;
+  const request = install({
+    now: () => at,
+    fetchImpl: async () => {
+      calls += 1;
+      return fail
+        ? new Response('limit', { status: 429 })
+        : Response.json([sighting()]);
+    },
+  });
+  const first = await request();
+  fail = true;
+  at += 600_001;
+  const stale = await request();
+  assert.equal(stale.status, 200);
+  assert.equal(stale.body.stale, true);
+  assert.equal(stale.body.fetchedAt, first.body.fetchedAt);
+  at += 1000;
+  assert.equal((await request()).body.stale, true);
+  assert.equal(calls, 2);
+});
+
+test('bad JSON, 5xx and capped bodies start a 15 second failure cooldown', async () => {
+  for (const bad of [
+    () => new Response('{malformed'),
+    () => new Response('private upstream message', { status: 503 }),
+    () =>
+      new Response('{}', {
+        headers: { 'Content-Length': String(2 * 1024 * 1024 + 1) },
+      }),
+  ]) {
+    let at = NOW;
+    let calls = 0;
+    const request = install({
+      now: () => at,
+      fetchImpl: async () => {
+        calls += 1;
+        return calls === 1 ? bad() : Response.json([sighting()]);
+      },
+    });
+    const first = await request();
+    assert.equal(first.status, 502);
+    assert.deepEqual(first.body, { error: 'acartia_unavailable' });
+    assert.equal(first.headers['Retry-After'], '15');
+    at += 14_999;
+    assert.equal((await request()).headers['Retry-After'], '1');
+    assert.equal(calls, 1);
+    at += 1;
+    assert.equal((await request()).status, 200);
+    assert.equal(calls, 2);
+  }
+});

server/providers/aircraft/opensky.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import { normalizeAdsbLolPointResponse } from '../../../src/data/adsbLolFallback.js';
+import { encodedBody, gzipBody } from '../common/compress.js';
 import {
   coalesceProxyRequest,
   readResponseJsonCapped,
@@ -18,6 +19,11 @@ let _openskyTokenExpiry = 0;
 let _openskyTokenPromise = null;
 /** @type {string|null} Cached upstream response body (JSON text). */
 let _openskyCacheBody = null;
+/**
+ * @type {Buffer|null} Gzip of `_openskyCacheBody`, written together with it.
+ * Null when the body is not worth compressing.
+ */
+let _openskyCacheGzip = null;
 /** @type {number} HTTP status of the cached response. */
 let _openskyCacheStatus = 0;
 /** @type {number} Epoch-ms when the response was cached. */
@@ -399,8 +405,12 @@ async function fetchAdsbLolPointFallback(req) {
           ADSBLOL_POINT_MAX_RESPONSE_BYTES,
         );
         const normalized = normalizeAdsbLolPointResponse(payload);
+        const body = JSON.stringify(normalized);
         const record = {
-          body: JSON.stringify(normalized),
+          body,
+          // Compressed once per entry; ADSBLOL_POINT_CACHE_MAX bounds the
+          // extra memory.
+          gzip: await gzipBody(body),
           cachedAt: Date.now(),
           count: normalized.states.length,
         };
@@ -429,6 +439,7 @@ async function fetchAdsbLolPointFallback(req) {
 async function serveAdsbLolPointFallback(req, res, requestedMode, reason) {
   const fallback = await fetchAdsbLolPointFallback(req);
   if (!fallback) return false;
+  const encoded = encodedBody(req, fallback.body, fallback.gzip);
   res.writeHead(200, {
     ...buildOpenSkyHeaders({
       cacheStatus: fallback.cacheStatus,
@@ -439,8 +450,9 @@ async function serveAdsbLolPointFallback(req, res, requestedMode, reason) {
     'X-Flight-Source': 'adsb.lol',
     'X-Flight-Coverage': `${ADSBLOL_POINT_RADIUS_NM}nm regional fallback`,
     'X-Flight-Count': String(fallback.count),
+    ...encoded.headers,
   });
-  res.end(fallback.body);
+  res.end(encoded.body);
   return true;
 }
 
@@ -526,9 +538,13 @@ export function openSkyProxy() {
             reason: 'cached',
           };
           const isStale = now - _openskyCacheTime >= _openskyTtlMs;
-          res.writeHead(
-            _openskyCacheStatus || 200,
-            buildOpenSkyHeaders({
+          const encoded = encodedBody(
+            req,
+            _openskyCacheBody,
+            _openskyCacheGzip,
+          );
+          res.writeHead(_openskyCacheStatus || 200, {
+            ...buildOpenSkyHeaders({
               cacheStatus: isStale ? 'STALE' : 'HIT',
               requestedMode: cachedMeta.requestedMode || requestedMode,
               usedMode: cachedMeta.usedMode || 'unknown',
@@ -544,8 +560,9 @@ export function openSkyProxy() {
                 ? (_openskyCooldownUntil - now) / 1000
                 : undefined,
             }),
-          );
-          res.end(_openskyCacheBody);
+            ...encoded.headers,
+          });
+          res.end(encoded.body);
           return;
         }
         // Cooling down with nothing cached (cold start into a rate limit):
@@ -640,7 +657,11 @@ export function openSkyProxy() {
             // Only cache successful responses — error responses (401/403/429/5xx)
             // should not be served from cache on subsequent requests
             if (upstream.ok) {
+              // Compress before writing either slot, so a request arriving
+              // mid-refresh still reads a body with its own frame.
+              const frame = await gzipBody(body);
               _openskyCacheBody = body;
+              _openskyCacheGzip = frame;
               _openskyCacheStatus = upstream.status;
               _openskyCacheTime = now;
               _openskyCacheSourceEpochMs = sourceEpochMs;
@@ -693,9 +714,13 @@ export function openSkyProxy() {
           // Serve the last-good body instead of the 429 when we have one —
           // the layer keeps rendering (STALE-cued) instead of dying.
           if (_openskyCacheBody && _openskyCacheStatus === 200) {
-            res.writeHead(
-              200,
-              buildOpenSkyHeaders({
+            const encoded = encodedBody(
+              req,
+              _openskyCacheBody,
+              _openskyCacheGzip,
+            );
+            res.writeHead(200, {
+              ...buildOpenSkyHeaders({
                 cacheStatus: 'STALE',
                 requestedMode,
                 usedMode,
@@ -703,8 +728,9 @@ export function openSkyProxy() {
                 staleSeconds: (now - _openskyCacheTime) / 1000,
                 retryAfterSeconds: cooldownMs / 1000,
               }),
-            );
-            res.end(_openskyCacheBody);
+              ...encoded.headers,
+            });
+            res.end(encoded.body);
             return;
           }
         }
@@ -746,16 +772,23 @@ export function openSkyProxy() {
           }
         }
 
-        res.writeHead(
-          upstream.status,
-          buildOpenSkyHeaders({
+        // The frame belongs to this body only if this body was cached. An
+        // uncached error must not borrow the previous snapshot's frame.
+        const encoded = encodedBody(
+          req,
+          body,
+          _openskyCacheBody === body ? _openskyCacheGzip : null,
+        );
+        res.writeHead(upstream.status, {
+          ...buildOpenSkyHeaders({
             cacheStatus: 'MISS',
             requestedMode,
             usedMode,
             reason,
           }),
-        );
-        res.end(body);
+          ...encoded.headers,
+        });
+        res.end(encoded.body);
       } catch (e) {
         console.error('[OpenSky Proxy]', e.message);
         if (_openskyCacheBody) {
@@ -766,17 +799,22 @@ export function openSkyProxy() {
             usedMode: 'unknown',
             reason: 'cached_stale',
           };
-          res.writeHead(
-            _openskyCacheStatus || 200,
-            buildOpenSkyHeaders({
+          const encoded = encodedBody(
+            req,
+            _openskyCacheBody,
+            _openskyCacheGzip,
+          );
+          res.writeHead(_openskyCacheStatus || 200, {
+            ...buildOpenSkyHeaders({
               cacheStatus: 'STALE',
               requestedMode:
                 cachedMeta.requestedMode || OPENSKY_AUTH_MODE_DEFAULT,
               usedMode: cachedMeta.usedMode || 'unknown',
               reason: cachedMeta.reason || 'cached_stale',
             }),
-          );
-          res.end(_openskyCacheBody);
+            ...encoded.headers,
+          });
+          res.end(encoded.body);
           return;
         }
         const requestedMode = normalizeOpenSkyAuthMode(

server/providers/cctv.js

@@ -1,4 +1,5 @@
 import { createCctvCatalog } from './cctv/catalog.js';
+import { quebec511VideoUrl, quebecBrowserVideoEnabled } from './cctv/quebec.js';
 import { normalizeFeedType, isVideoFeedType } from './cctv/normalize.js';
 import {
   buildSyntheticCctvSvg,
@@ -18,6 +19,8 @@ import { sanitizeCctvRangeHeader } from './cctv/range.js';
 import { admitSameSiteKeyless } from './common/same-site.js';
 import { PROXY_SIGNALS } from '../../src/localRequestGate.mjs';
 import { createHlsPuller } from './cctv/stream.js';
+import { isMlitRiverAdjustmentImage } from './cctv/worldCameras.js';
+import { ottawaAuthorizedFrameUrl } from './cctv/ottawa.js';
 import { googleServerApiKey } from './places/google-key.js';
 export { CCTV_FRAME_FETCH_TIMEOUT_MS, fetchCctvImageFromUpstream };
 /**
@@ -43,6 +46,120 @@ export function cctvProxy({ sourceRoot = process.cwd() } = {}) {
   const HEALTH_MAX_ENTRIES = CCTV_MAX_SOURCES_CEILING;
   /** Live HLS strategies (see ./cctv/stream.js). Shared across dev and preview. */
   const puller = createHlsPuller();
+  /**
+   * Bounded transient image reuse keeps cadence-limited providers (World
+   * stills, Ottawa's once-a-minute API) inside their refresh floor. The byte
+   * cap is the real bound; the entry cap only limits map overhead.
+   */
+  const WORLD_FRAME_CACHE_MAX_ENTRIES = 1024;
+  /** Retry a failed fetch sooner than a full refresh window, never under a minute. */
+  const THROTTLED_FRAME_FAILURE_BACKOFF_MS = 60 * 1000;
+  const WORLD_FRAME_CACHE_MAX_ENTRY_BYTES = 2 * 1024 * 1024;
+  const WORLD_FRAME_CACHE_MAX_BYTES = 32 * 1024 * 1024;
+  const worldFrameCache = new Map();
+  const worldFrameInflight = new Map();
+  const worldFrameNextAllowedAt = new Map();
+  let worldFrameCacheBytes = 0;
+
+  function getWorldFrameCache(cameraId) {
+    const entry = worldFrameCache.get(cameraId);
+    if (!entry) return null;
+    worldFrameCache.delete(cameraId);
+    worldFrameCache.set(cameraId, entry);
+    return entry;
+  }
+
+  function storeWorldFrame(cameraId, image) {
+    if (
+      !Buffer.isBuffer(image?.body) ||
+      image.body.length > WORLD_FRAME_CACHE_MAX_ENTRY_BYTES
+    )
+      return;
+    const previous = worldFrameCache.get(cameraId);
+    if (previous) worldFrameCacheBytes -= previous.body.length;
+    const entry = {
+      body: image.body,
+      contentType: image.contentType,
+      fetchedAt: Date.now(),
+    };
+    worldFrameCache.delete(cameraId);
+    worldFrameCache.set(cameraId, entry);
+    worldFrameCacheBytes += entry.body.length;
+    while (
+      worldFrameCache.size > WORLD_FRAME_CACHE_MAX_ENTRIES ||
+      worldFrameCacheBytes > WORLD_FRAME_CACHE_MAX_BYTES
+    ) {
+      const oldestId = worldFrameCache.keys().next().value;
+      const oldest = worldFrameCache.get(oldestId);
+      worldFrameCache.delete(oldestId);
+      worldFrameCacheBytes -= oldest.body.length;
+    }
+  }
+
+  function setNextAllowedAt(cameraId, at) {
+    worldFrameNextAllowedAt.delete(cameraId);
+    worldFrameNextAllowedAt.set(cameraId, at);
+    while (worldFrameNextAllowedAt.size > 4096) {
+      worldFrameNextAllowedAt.delete(
+        worldFrameNextAllowedAt.keys().next().value,
+      );
+    }
+  }
+
+  /**
+   * Fetch a frame from a provider with a per-camera refresh floor. Inside the
+   * floor the last frame is reused; with no frame to reuse the caller gets
+   * `{ throttled: true }` and serves a placeholder, so a cadence-limited camera
+   * never falls through to the key-bearing Street View fallback. A failed
+   * fetch backs off for a minute (capped at the floor) instead of a full
+   * window.
+   */
+  async function fetchThrottledFrame(source, cameraId, frameUrl) {
+    const cached = getWorldFrameCache(cameraId);
+    const rawRefreshMs = Number(source?.frameRefreshMs);
+    const refreshMs =
+      Number.isFinite(rawRefreshMs) && rawRefreshMs > 0
+        ? rawRefreshMs
+        : 5 * 60 * 1000;
+    const now = Date.now();
+    if (cached && now - cached.fetchedAt < refreshMs) {
+      return { ok: true, ...cached, cached: true };
+    }
+
+    const inflight = worldFrameInflight.get(cameraId);
+    if (inflight) return inflight;
+    const stale = cached
+      ? {
+          ok: true,
+          body: cached.body,
+          contentType: cached.contentType,
+          stale: true,
+        }
+      : null;
+    const nextAllowedAt = worldFrameNextAllowedAt.get(cameraId) || 0;
+    if (now < nextAllowedAt) return stale || { ok: false, throttled: true };
+    if (!frameUrl) return stale;
+    setNextAllowedAt(cameraId, now + refreshMs);
+    let request;
+    request = fetchCctvImageFromUpstream(frameUrl)
+      .then((image) => {
+        if (image?.ok) {
+          storeWorldFrame(cameraId, image);
+          return image;
+        }
+        setNextAllowedAt(
+          cameraId,
+          Date.now() + Math.min(refreshMs, THROTTLED_FRAME_FAILURE_BACKOFF_MS),
+        );
+        return stale || image;
+      })
+      .finally(() => {
+        if (worldFrameInflight.get(cameraId) === request)
+          worldFrameInflight.delete(cameraId);
+      });
+    worldFrameInflight.set(cameraId, request);
+    return request;
+  }
 
   /** Update the health entry for a camera, evicting the oldest entry if at capacity. */
   const setHealth = (cameraId, patch) => {
@@ -153,6 +270,7 @@ export function cctvProxy({ sourceRoot = process.cwd() } = {}) {
         );
 
         if (url.pathname === '/sources') {
+          const quebecVideo = quebecBrowserVideoEnabled();
           const body = {
             trimmedPacks: getCctvSources.trimmedPacks?.(sources) ?? [],
             sources: sources.map((source) => ({
@@ -164,6 +282,7 @@ export function cctvProxy({ sourceRoot = process.cwd() } = {}) {
               provider: source.provider,
               lat: source.lat,
               lon: source.lon,
+              frameRefreshMs: source.frameRefreshMs,
               headingDeg: source.headingDeg,
               headingConfidence: source.headingConfidence || '',
               pitchDeg: source.pitchDeg,
@@ -174,6 +293,13 @@ export function cctvProxy({ sourceRoot = process.cwd() } = {}) {
               feedType: normalizeFeedType(source.feedType),
               sourceKind:
                 source.sourceKind || (source.url ? 'configured' : 'fallback'),
+              sourceUrl: source.sourceUrl || '',
+              browserMediaUrl:
+                quebecVideo && source.sourceKind === 'quebec-511-browser'
+                  ? quebec511VideoUrl(source.id)
+                  : '',
+              accuracyM: source.accuracyM,
+              positionSource: source.positionSource || '',
               poseSource: source.poseSource,
               model: source.model || '',
               manufacturer: source.manufacturer || '',
@@ -526,15 +652,71 @@ export function cctvProxy({ sourceRoot = process.cwd() } = {}) {
             : '');
 
         const upstreamImage =
-          source?.sourceKind === 'txdot-its'
-            ? await fetchTxdotSnapshot(upstreamCandidate)
-            : await fetchCctvImageFromUpstream(upstreamCandidate);
+          source?.pack === 'world-cameras'
+            ? await fetchThrottledFrame(source, cameraId, upstreamCandidate)
+            : source?.sourceKind === 'ottawa-traffic'
+              ? await fetchThrottledFrame(
+                  source,
+                  cameraId,
+                  ottawaAuthorizedFrameUrl(upstreamCandidate),
+                )
+              : source?.sourceKind === 'txdot-its'
+                ? await fetchTxdotSnapshot(upstreamCandidate)
+                : await fetchCctvImageFromUpstream(upstreamCandidate, {
+                    allowMjpeg: source?.sourceKind === 'taiwan-highway-motc',
+                  });
+        if (
+          source?.sourceKind === 'mlit-river' &&
+          isMlitRiverAdjustmentImage(upstreamImage)
+        ) {
+          const svg = buildSyntheticCctvSvg({
+            cameraId,
+            label,
+            city,
+            status: 'CAMERA UNDER ADJUSTMENT',
+          });
+          setHealth(cameraId, {
+            status: 'degraded',
+            sourceKind: 'snapshot',
+            label: source.provider || 'MLIT river cameras',
+            message: 'Provider camera under adjustment',
+          });
+          res.writeHead(200, {
+            'Content-Type': 'image/svg+xml',
+            'Cache-Control': 'no-store',
+            'X-CCTV-Source': 'provider-maintenance',
+          });
+          res.end(svg);
+          return;
+        }
+        if (upstreamImage?.throttled) {
+          // Inside the provider's refresh floor with no frame to reuse: a
+          // placeholder, not Street View, and no health change.
+          res.writeHead(200, {
+            'Content-Type': 'image/svg+xml',
+            'Cache-Control': 'no-store',
+            'X-CCTV-Source': 'synthetic',
+          });
+          res.end(
+            buildSyntheticCctvSvg({
+              cameraId,
+              label,
+              city,
+              status: 'WAITING FOR NEXT FRAME',
+            }),
+          );
+          return;
+        }
         if (upstreamImage?.ok) {
           setHealth(cameraId, {
-            status: 'ok',
+            status: upstreamImage.stale ? 'degraded' : 'ok',
             sourceKind: 'snapshot',
             label: source?.provider || 'Configured source',
-            message: 'Upstream snapshot active',
+            message: upstreamImage.stale
+              ? 'Serving last snapshot; refresh failed'
+              : upstreamImage.cached
+                ? 'Cached snapshot active'
+                : 'Upstream snapshot active',
           });
           res.writeHead(200, {
             'Content-Type': upstreamImage.contentType,

server/providers/cctv/cap.js

@@ -1,5 +1,6 @@
 import {
   CCTV_MAX_SOURCES_CEILING,
+  CCTV_SHARED_SOURCE_SLOTS,
   DEFAULT_CCTV_MAX_SOURCES,
 } from './constants.js';
 
@@ -23,16 +24,27 @@ export function resolveCatalogCap(raw) {
  * exceed the catalog cap, the cap is filled ROUND-ROBIN — one camera from
  * each pack per turn, in each pack's own order — so a lowered
  * CCTV_MAX_SOURCES thins every region a little instead of deleting whichever
- * pack happened to be appended last. Duplicate ids resolve last-pack-wins so
+ * pack happened to be appended last. A pack with a `reservedCount` keeps up to
+ * that many rows only from the capacity ABOVE the shared floor, so a
+ * reservation adds room and never shrinks the other packs' round-robin
+ * share; at or below the floor reserved packs are ordinary lanes. Duplicate
+ * ids resolve last-pack-wins so
  * file/env overrides keep replacing live records; the record is then counted
  * against the pack that won it.
  *
  * @param {Array<{name:string, sources:Array<object>}>} packs - Normalized
  *   packs in merge order (earlier packs lose duplicate ids to later ones).
  * @param {number} maxCount - Catalog cap.
+ * @param {object} [options]
+ * @param {number} [options.sharedFloor=CCTV_SHARED_SOURCE_SLOTS] - Slots kept
+ *   for the round-robin before reservations apply.
  * @returns {{sources:Array<object>, packs:Array<{name:string, offered:number, kept:number}>}}
  */
-export function allocateSourceCap(packs, maxCount) {
+export function allocateSourceCap(
+  packs,
+  maxCount,
+  { sharedFloor = CCTV_SHARED_SOURCE_SLOTS } = {},
+) {
   const owner = new Map();
   for (const pack of packs) {
     for (const source of pack.sources) {
@@ -40,30 +52,53 @@ export function allocateSourceCap(packs, maxCount) {
       owner.set(source.id, { pack: pack.name, source });
     }
   }
-  const lanes = packs.map((pack) => ({
-    name: pack.name,
+  const lanes = packs.map((pack) => {
     // Only the record that WON its id (the last occurrence anywhere, so also
     // the last within this pack) takes a lane slot; earlier duplicates never
     // count against the cap.
-    queue: pack.sources.filter(
+    const queue = pack.sources.filter(
       (source) => source?.id && owner.get(source.id)?.source === source,
-    ),
-    next: 0,
-    kept: 0,
-  }));
+    );
+    return {
+      name: pack.name,
+      queue,
+      reserved: Math.max(
+        0,
+        Math.min(queue.length, Math.floor(Number(pack.reservedCount) || 0)),
+      ),
+      next: 0,
+      kept: 0,
+    };
+  });
   const total = lanes.reduce((sum, lane) => sum + lane.queue.length, 0);
   const limit = Math.min(total, Math.max(0, Math.floor(maxCount)));
 
   const sources = [];
+  const reservedSources = [];
   if (limit >= total) {
     for (const lane of lanes) {
       sources.push(...lane.queue);
       lane.kept = lane.queue.length;
     }
   } else {
-    while (sources.length < limit) {
+    // Reserved packs draw only on the capacity above the shared floor, then
+    // every lane (reserved ones included) shares the rest round-robin.
+    const reserveBudget = Math.max(0, limit - Math.max(0, sharedFloor));
+    while (reservedSources.length < reserveBudget) {
+      let tookReserved = false;
       for (const lane of lanes) {
-        if (sources.length >= limit) break;
+        if (reservedSources.length >= reserveBudget) break;
+        if (lane.kept >= lane.reserved) continue;
+        reservedSources.push(lane.queue[lane.next]);
+        lane.next += 1;
+        lane.kept += 1;
+        tookReserved = true;
+      }
+      if (!tookReserved) break;
+    }
+    while (sources.length + reservedSources.length < limit) {
+      for (const lane of lanes) {
+        if (sources.length + reservedSources.length >= limit) break;
         if (lane.next >= lane.queue.length) continue;
         sources.push(lane.queue[lane.next]);
         lane.next += 1;
@@ -72,7 +107,9 @@ export function allocateSourceCap(packs, maxCount) {
     }
   }
   return {
-    sources,
+    // Keep the shared round-robin sequence first so the default active camera
+    // remains in its established region; guaranteed regional rows follow it.
+    sources: [...sources, ...reservedSources],
     packs: lanes.map((lane) => ({
       name: lane.name,
       offered: lane.queue.length,

server/providers/cctv/catalog.js

@@ -1,11 +1,18 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { DEFAULT_CCTV_SOURCE_FILE, CCTV_SOURCE_CACHE_MS } from './constants.js';
+import {
+  DEFAULT_CCTV_SOURCE_FILE,
+  CCTV_SOURCE_CACHE_MS,
+  WORLD_CCTV_SOURCE_COUNT,
+} from './constants.js';
 import { allocateSourceCap, resolveCatalogCap } from './cap.js';
 import { loadGroundHeights, joinGroundHeights } from './groundHeights.js';
 import { cameraRegion, normalizeSourceItem } from './normalize.js';
 import { loadLithuaniaSources } from './lithuania.js';
+import { loadOttawaSourcesFromOpenData } from './ottawa.js';
+import { loadQuebecSources, QUEBEC_CAMERA_SOURCE_COUNT } from './quebec.js';
 import { loadTaiwanSources } from './taiwan.js';
+import { loadWorldCameraSources } from './worldCameras.js';
 import {
   loadAustinSourcesFromOpenData,
   loadCaltransSourcesFromOpenData,
@@ -20,6 +27,7 @@ import {
   loadNswSourcesFromOpenData,
   loadCalgarySourcesFromOpenData,
   loadCataloniaSourcesFromOpenData,
+  loadIcelandSourcesFromOpenData,
   loadHkSourcesFromOpenData,
   loadDelDOTSourcesFromOpenData,
   loadKingCountySourcesFromOpenData,
@@ -75,6 +83,11 @@ const LIVE_PACKS = [
     enabled: () => envEnabled('CCTV_DRIVEBC_ENABLED'),
     load: loadDriveBcSourcesFromOpenData,
   },
+  {
+    name: 'ottawa',
+    enabled: () => envEnabled('CCTV_OTTAWA_ENABLED'),
+    load: loadOttawaSourcesFromOpenData,
+  },
   {
     name: 'txdot',
     enabled: () => envEnabled('CCTV_TXDOT_ENABLED'),
@@ -110,6 +123,11 @@ const LIVE_PACKS = [
     enabled: () => envEnabled('CCTV_CATALONIA_ENABLED'),
     load: loadCataloniaSourcesFromOpenData,
   },
+  {
+    name: 'iceland',
+    enabled: () => envEnabled('CCTV_ICELAND_ENABLED'),
+    load: loadIcelandSourcesFromOpenData,
+  },
   {
     name: 'hk',
     enabled: () => envEnabled('CCTV_HK_ENABLED'),
@@ -172,6 +190,18 @@ const LIVE_PACKS = [
     enabled: () => envOptIn('CCTV_HOUSTON_ENABLED'),
     load: loadHoustonSourcesFromOpenData,
   },
+  {
+    name: 'quebec',
+    enabled: () => envEnabled('CCTV_QUEBEC_ENABLED'),
+    load: loadQuebecSources,
+    reservedCount: QUEBEC_CAMERA_SOURCE_COUNT,
+  },
+  {
+    name: 'world-cameras',
+    enabled: () => envEnabled('CCTV_WORLD_CAMERAS_ENABLED'),
+    load: loadWorldCameraSources,
+    reservedCount: WORLD_CCTV_SOURCE_COUNT,
+  },
   {
     name: 'a22',
     enabled: () => envEnabled('CCTV_A22_ENABLED'),
@@ -316,7 +346,7 @@ export function createCctvCatalog({ sourceRoot = process.cwd() } = {}) {
       : [];
     // Live packs first so file/env overrides win on duplicate IDs; each pack
     // keeps its own priority order and the catalog cap is shared fairly.
-    const normalizePack = (name, items) => ({
+    const normalizePack = (name, items, reservedCount = 0) => ({
       name,
       sources: items
         .filter((item) => item && typeof item === 'object')
@@ -326,6 +356,7 @@ export function createCctvCatalog({ sourceRoot = process.cwd() } = {}) {
         ? items.available
         : items.length,
       region: items.region ?? null,
+      reservedCount,
     });
     const packs = [
       ...LIVE_PACKS.map((pack, index) =>
@@ -334,6 +365,7 @@ export function createCctvCatalog({ sourceRoot = process.cwd() } = {}) {
           liveResults[index]?.status === 'fulfilled'
             ? liveResults[index].value
             : [],
+          pack.reservedCount,
         ),
       ),
       normalizePack('file', fromFile),

server/providers/cctv/constants.js

@@ -5,15 +5,18 @@ export const DEFAULT_AUSTIN_ROWS_URL =
 /** Default cap on Austin cameras after distance-based prioritization. */
 export const DEFAULT_AUSTIN_MAX_SOURCES = 250;
 /**
- * Catalog-wide safety ceiling on served cameras. Each pack already caps
- * itself (nearest-to-anchor first); this bound only matters when the packs
- * together exceed it, and it is then filled round-robin across packs (see
- * cap.js) so no region is silently dropped. The default per-pack caps
- * together can exceed it, so a default install may be thinned evenly here.
+ * Slots every pack shares round-robin before any reservation applies. A
+ * reserved pack (Québec, World) only takes capacity above this floor, so a
+ * cap at or below it thins every region evenly (see cap.js).
  */
-export const DEFAULT_CCTV_MAX_SOURCES = 4000;
+export const CCTV_SHARED_SOURCE_SLOTS = 4000;
+/**
+ * Catalog-wide default: the 4,000 shared slots plus room reserved for the
+ * 1,120 Québec and 2,230 World image locations.
+ */
+export const DEFAULT_CCTV_MAX_SOURCES = 7350;
 /** Hard upper bound for CCTV_MAX_SOURCES; also sizes the health map. */
-export const CCTV_MAX_SOURCES_CEILING = 5000;
+export const CCTV_MAX_SOURCES_CEILING = 8000;
 /** Reference point for Austin camera prioritization (Congress & 6th). */
 export const AUSTIN_DOWNTOWN = { lat: 30.2672, lon: -97.7431 };
 /** Caltrans CCTV: one JSON feed per district, identical schema statewide. */
@@ -197,6 +200,39 @@ export const DRIVEBC_ANCHORS = [
   { lat: 49.2827, lon: -123.1207 }, // Vancouver
   { lat: 48.4284, lon: -123.3656 }, // Victoria
 ];
+/** City of Ottawa traffic cameras: documented JSON list (keyless). */
+export const OTTAWA_CAMERAS_URL =
+  'https://traffic.ottawa.ca/map/service/camera';
+/**
+ * Keyless canonical frame URL for one camera number. The city's Traffic Camera
+ * Images API needs a certificate (OTTAWA_CAMERA_CERTIFICATE), which the frame
+ * proxy adds at request time so it never appears in a catalog response.
+ */
+export const OTTAWA_IMAGE_URL = (cameraNumber) =>
+  `https://traffic.ottawa.ca/opendata/camera?c=${encodeURIComponent(cameraNumber)}`;
+/** Pinned frame directory, for redirect containment in the media proxy. */
+export const OTTAWA_IMAGE_ORIGIN = 'https://traffic.ottawa.ca/opendata/';
+/** The API lets one certificate and user id fetch a camera once a minute. */
+export const OTTAWA_FRAME_REFRESH_MS = 60 * 1000;
+/** Alphanumeric user id this server sends with its certificate. */
+export const OTTAWA_API_USER_ID = 'gev';
+export const DEFAULT_OTTAWA_MAX_SOURCES = 250;
+/** Prioritization anchor: downtown Ottawa (Parliament Hill). */
+export const OTTAWA_ANCHORS = [{ lat: 45.4215, lon: -75.6972 }];
+/**
+ * Taiwan Highway Bureau MJPEG servers. Each camera is one root path segment,
+ * so the pin is the host root: a redirect must stay on the same server.
+ */
+export const TAIWAN_HIGHWAY_IMAGE_ORIGINS = Object.freeze(
+  [1, 2, 3, 4, 5, 6, 7, 8].map((n) => `https://cctv-ss0${n}.thb.gov.tw/`),
+);
+/** Direct still-image directories from the World cams add-on's eligible packs. */
+export const TRIPCHECK_IMAGE_ORIGIN =
+  'https://www.tripcheck.com/roadcams/cams/';
+export const MLIT_RIVER_IMAGE_ORIGIN = 'https://cam.river.go.jp/cam/now/';
+export const DEFAULT_WORLD_CCTV_SOURCE_FILE =
+  'config/cctv_sources.world-image-cameras.json';
+export const WORLD_CCTV_SOURCE_COUNT = 2230;
 /** Tallinn intersection cameras: curated catalog + public stills on ristmikud.tallinn.ee. */
 export const DEFAULT_TALLINN_SOURCE_FILE = 'config/cctv_sources.tallinn.json';
 export const DEFAULT_TALLINN_MAX_SOURCES = 255;
@@ -309,6 +345,37 @@ export const CATALONIA_ANCHORS = [
   { lat: 41.5636, lon: 2.0111 }, // Terrassa
 ];
 
+/**
+ * Icelandic Road and Coastal Administration (Vegagerðin, IRCA) road cameras:
+ * one keyless JSON list, one row per camera view (about 500 views at roughly
+ * 170 stations, verified 2026-11-06). Frames are stills on the IRCA host, each
+ * rewritten by the publisher every few minutes. Camera images are published
+ * under CC BY 4.0 (IRCA terms of use, "Open data" section).
+ */
+export const ICELAND_CAMERAS_URL =
+  'https://gagnaveita.vegagerdin.is/api/vefmyndavelar2014_1';
+/** The only directory Iceland camera frames may come from. */
+export const ICELAND_IMAGE_ORIGIN =
+  'https://www.vegagerdin.is/vgdata/vefmyndavelar/';
+/** Byte ceiling for the Iceland catalog read (~150 KB observed 2026-11-06). */
+export const ICELAND_MAX_CATALOG_BYTES = 2 * 1024 * 1024;
+/** Ground-elevation prior in metres: the feed carries none, and the country
+ * runs from sea level to highland passes. The client's ground snap corrects
+ * this on 3D-tile stacks. */
+export const ICELAND_GROUND_ELEVATION_M = 60;
+/** The feed lists about 500 views; the default keeps half so the shared
+ * catalog cap still leaves room for denser regions. */
+export const DEFAULT_ICELAND_MAX_SOURCES = 250;
+/** Prioritization anchors: Reykjavík and the regional centres, so a cap keeps
+ * every region's nearest cameras instead of only the capital's. */
+export const ICELAND_ANCHORS = [
+  { lat: 64.1466, lon: -21.9426 }, // Reykjavík
+  { lat: 65.6885, lon: -18.1262 }, // Akureyri
+  { lat: 65.2639, lon: -14.3948 }, // Egilsstaðir
+  { lat: 66.0749, lon: -23.1351 }, // Ísafjörður
+  { lat: 63.9331, lon: -20.9971 }, // Selfoss
+];
+
 /** Hong Kong Transport Department traffic snapshot cameras: keyless English
  * locations XML on DATA.GOV.HK; frames are stills on the TD CCTV host. */
 export const DEFAULT_HK_CAMERAS_URL =

server/providers/cctv/media.js

@@ -10,10 +10,15 @@ import {
   CCTV_MEDIA_MAX_BODY_BYTES,
   HK_IMAGE_ORIGIN,
   KING_COUNTY_IMAGE_ORIGIN,
+  MLIT_RIVER_IMAGE_ORIGIN,
+  TRIPCHECK_IMAGE_ORIGIN,
   NSW_IMAGE_ORIGIN,
   NSW_IMAGE_USER_AGENT,
+  OTTAWA_IMAGE_ORIGIN,
   TALLINN_IMAGE_ORIGIN,
   TARKTEE_IMAGE_ORIGIN,
+  ICELAND_IMAGE_ORIGIN,
+  TAIWAN_HIGHWAY_IMAGE_ORIGINS,
   TFL_IMAGE_ORIGIN,
   WARENDORF_IMAGE_ORIGINS,
   WSDOT_IMAGE_ORIGIN,
@@ -523,13 +528,18 @@ for (const prefix of [
   TFL_IMAGE_ORIGIN,
   TALLINN_IMAGE_ORIGIN,
   TARKTEE_IMAGE_ORIGIN,
+  ICELAND_IMAGE_ORIGIN,
   ...WARENDORF_IMAGE_ORIGINS,
   NSW_IMAGE_ORIGIN,
+  OTTAWA_IMAGE_ORIGIN,
   CALGARY_IMAGE_ORIGIN,
   HK_IMAGE_ORIGIN,
   KING_COUNTY_IMAGE_ORIGIN,
   WSDOT_IMAGE_ORIGIN,
   A22_IMAGE_ORIGIN,
+  TRIPCHECK_IMAGE_ORIGIN,
+  MLIT_RIVER_IMAGE_ORIGIN,
+  ...TAIWAN_HIGHWAY_IMAGE_ORIGINS,
 ]) {
   const host = new URL(prefix).hostname;
   CCTV_PINNED_PREFIXES_BY_HOST.set(host, [
@@ -621,6 +631,216 @@ export function cctvUpstreamUserAgent(url) {
   }
 }
 
+/** Largest single JPEG the MJPEG first-frame reader will buffer. */
+export const CCTV_MJPEG_FRAME_MAX_BYTES = 2 * 1024 * 1024;
+
+/**
+ * Read one bounded JPEG part from an open MJPEG response, then stop the stream.
+ *
+ * The first part may follow a CRLF preamble, and its delimiter may be written
+ * as `--<boundary>` or, when the declared boundary already starts with `--`,
+ * as the boundary itself. A part with Content-Length is read to that length;
+ * a part without one ends at the next delimiter, so a JPEG end marker inside
+ * the image (an EXIF thumbnail) never truncates it. Bytes are copied once
+ * into a preallocated buffer and every search resumes where it stopped, so a
+ * trickling upstream costs linear time.
+ */
+async function readFirstMjpegFrame(upstream, maxBytes) {
+  const mediaType = cctvLiveMediaType(
+    'mjpeg',
+    upstream.headers.get('content-type'),
+  );
+  const boundary = parseMediaType(mediaType)?.params.get('boundary') || '';
+  const frameMax = Math.min(maxBytes, CCTV_MJPEG_FRAME_MAX_BYTES);
+  if (
+    !boundary ||
+    !upstream.body ||
+    !Number.isSafeInteger(frameMax) ||
+    frameMax < 4
+  ) {
+    try {
+      await upstream.body?.cancel();
+    } catch {
+      /* no-op */
+    }
+    return null;
+  }
+
+  const delimiters = [Buffer.from('--' + boundary, 'latin1')];
+  if (boundary.startsWith('--') && boundary.length > 2)
+    delimiters.push(Buffer.from(boundary, 'latin1'));
+  const lineEnd = Buffer.from('\r\n', 'ascii');
+  const headerTerminator = Buffer.from('\r\n\r\n', 'ascii');
+  const jpegStart = Buffer.from([0xff, 0xd8]);
+  const jpegEnd = Buffer.from([0xff, 0xd9]);
+  const maxPreambleBytes = 64;
+  const maxHeaderBytes = 8 * 1024;
+  const maxBufferedBytes =
+    maxPreambleBytes +
+    delimiters[0].length +
+    lineEnd.length +
+    maxHeaderBytes +
+    headerTerminator.length +
+    frameMax +
+    lineEnd.length +
+    delimiters[0].length;
+  const buffer = Buffer.allocUnsafe(maxBufferedBytes);
+  let length = 0;
+  let reader;
+  let headerStart = -1;
+  let delimiter = null;
+  let headerScanFrom = 0;
+  let bodyStart = -1;
+  let declaredLength = null;
+  let boundaryScanFrom = -1;
+
+  /** Match the opening delimiter after an optional CRLF preamble. */
+  function findOpening() {
+    let at = 0;
+    while (at < length && (buffer[at] === 0x0d || buffer[at] === 0x0a)) at++;
+    if (at > maxPreambleBytes) return { failed: true };
+    for (const candidate of delimiters) {
+      const line = Buffer.concat([candidate, lineEnd]);
+      const need = at + line.length;
+      if (length < need) {
+        const seen = buffer.subarray(at, length);
+        if (line.subarray(0, seen.length).equals(seen))
+          return { pending: true };
+        continue;
+      }
+      if (buffer.subarray(at, need).equals(line))
+        return { start: need, delimiter: candidate };
+    }
+    return { failed: true };
+  }
+
+  /** Parse the part headers; false rejects the stream. */
+  function parseHeaders(headerEnd) {
+    const headerText = buffer
+      .subarray(headerStart, headerEnd)
+      .toString('latin1');
+    const headers = new Map();
+    for (const line of headerText.split('\r\n')) {
+      const colon = line.indexOf(':');
+      if (colon <= 0) return false;
+      const name = line.slice(0, colon).trim().toLowerCase();
+      if (!name || headers.has(name)) return false;
+      headers.set(name, line.slice(colon + 1).trim());
+    }
+    if (cctvRasterImageType(headers.get('content-type')) !== 'image/jpeg')
+      return false;
+    const declared = headers.get('content-length');
+    if (declared !== undefined) {
+      if (!/^\d+$/.test(declared)) return false;
+      declaredLength = Number(declared);
+      if (
+        !Number.isSafeInteger(declaredLength) ||
+        declaredLength < jpegStart.length + jpegEnd.length ||
+        declaredLength > frameMax
+      )
+        return false;
+    }
+    return true;
+  }
+
+  /** A complete JPEG body, or null. */
+  function asJpeg(frame) {
+    return frame.length >= jpegStart.length + jpegEnd.length &&
+      frame.subarray(0, jpegStart.length).equals(jpegStart) &&
+      frame.subarray(-jpegEnd.length).equals(jpegEnd)
+      ? Buffer.from(frame)
+      : null;
+  }
+
+  try {
+    reader = upstream.body.getReader();
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) return null;
+
+      const chunk = Buffer.from(value);
+      const room = maxBufferedBytes - length;
+      const included = Math.min(room, chunk.length);
+      chunk.copy(buffer, length, 0, included);
+      length += included;
+      const overflow = included < chunk.length;
+
+      if (headerStart < 0) {
+        const opening = findOpening();
+        if (opening.failed) return null;
+        if (opening.pending) {
+          if (overflow) return null;
+          continue;
+        }
+        headerStart = opening.start;
+        delimiter = opening.delimiter;
+        headerScanFrom = headerStart;
+      }
+
+      if (bodyStart < 0) {
+        const headerEnd = buffer
+          .subarray(0, length)
+          .indexOf(headerTerminator, headerScanFrom);
+        if (headerEnd < 0) {
+          if (length - headerStart > maxHeaderBytes || overflow) return null;
+          headerScanFrom = Math.max(
+            headerStart,
+            length - headerTerminator.length + 1,
+          );
+          continue;
+        }
+        if (headerEnd - headerStart > maxHeaderBytes) return null;
+        if (!parseHeaders(headerEnd)) return null;
+        bodyStart = headerEnd + headerTerminator.length;
+        boundaryScanFrom = bodyStart;
+      }
+
+      const available = length - bodyStart;
+      if (available >= jpegStart.length) {
+        if (
+          !buffer
+            .subarray(bodyStart, bodyStart + jpegStart.length)
+            .equals(jpegStart)
+        )
+          return null;
+      }
+      const nextDelimiter = Buffer.concat([lineEnd, delimiter]);
+      const nextPart = buffer
+        .subarray(0, length)
+        .indexOf(nextDelimiter, boundaryScanFrom);
+      if (declaredLength !== null) {
+        if (nextPart >= bodyStart && nextPart - bodyStart < declaredLength)
+          return null;
+        if (available >= declaredLength)
+          return asJpeg(buffer.subarray(bodyStart, bodyStart + declaredLength));
+      } else if (nextPart >= bodyStart) {
+        const frame = buffer.subarray(bodyStart, nextPart);
+        return frame.length > frameMax ? null : asJpeg(frame);
+      } else if (available > frameMax) {
+        return null;
+      }
+      if (nextPart < 0)
+        boundaryScanFrom = Math.max(
+          bodyStart,
+          length - nextDelimiter.length + 1,
+        );
+      if (overflow) return null;
+    }
+  } finally {
+    if (reader) {
+      try {
+        await reader.cancel();
+      } catch {
+        /* already closed or aborted */
+      }
+      try {
+        reader.releaseLock();
+      } catch {
+        /* already released */
+      }
+    }
+  }
+}
 /**
  * Fetch one upstream CCTV image within the frame-refresh budget.
  *
@@ -633,6 +853,10 @@ export function cctvUpstreamUserAgent(url) {
  * @param {typeof fetch} [options.fetchImpl=fetch] - Fetch implementation.
  * @param {number} [options.timeoutMs=CCTV_FRAME_FETCH_TIMEOUT_MS] - Abort timeout.
  * @param {number} [options.maxBytes=CCTV_FRAME_MAX_BODY_BYTES] - Snapshot byte cap.
+ * @param {boolean} [options.allowMjpeg=false] - Accept a multipart MJPEG
+ *   answer and keep its first JPEG. Only sources registered as MJPEG stills
+ *   (the Taiwan Highway Bureau feeds) set it; any other host answering
+ *   multipart falls through to the next fallback.
  * @returns {Promise<{ok:true,body:Buffer,contentType:string}|null>}
  */
 export async function fetchCctvImageFromUpstream(
@@ -641,6 +865,7 @@ export async function fetchCctvImageFromUpstream(
     fetchImpl = fetch,
     timeoutMs = CCTV_FRAME_FETCH_TIMEOUT_MS,
     maxBytes = CCTV_FRAME_MAX_BODY_BYTES,
+    allowMjpeg = false,
   } = {},
 ) {
   if (!url || !/^https?:\/\//i.test(url)) return null;
@@ -660,10 +885,7 @@ export async function fetchCctvImageFromUpstream(
       fetchImpl,
     );
     if (!upstream) return null;
-    const contentType = cctvRasterImageType(
-      upstream.headers.get('content-type'),
-    );
-    if (!upstream.ok || !contentType) {
+    if (!upstream.ok) {
       try {
         await upstream.body?.cancel();
       } catch {
@@ -671,9 +893,24 @@ export async function fetchCctvImageFromUpstream(
       }
       return null;
     }
-    const body = await readCappedResponseBytes(upstream, maxBytes);
+    const upstreamType = upstream.headers.get('content-type');
+    const contentType = cctvRasterImageType(upstreamType);
+    if (contentType) {
+      const body = await readCappedResponseBytes(upstream, maxBytes);
+      if (!body) return null;
+      return { ok: true, body, contentType };
+    }
+    if (!allowMjpeg || !cctvLiveMediaType('mjpeg', upstreamType)) {
+      try {
+        await upstream.body?.cancel();
+      } catch {
+        /* no-op */
+      }
+      return null;
+    }
+    const body = await readFirstMjpegFrame(upstream, maxBytes);
     if (!body) return null;
-    return { ok: true, body, contentType };
+    return { ok: true, body, contentType: 'image/jpeg' };
   } catch {
     return null;
   } finally {

server/providers/cctv/normalize.js

@@ -460,6 +460,17 @@ export function isLikelyCataloniaCoordinate(lat, lon) {
   );
 }
 
+/** Iceland bounding box (mainland and nearby islands, with a margin). */
+export function isLikelyIcelandCoordinate(lat, lon) {
+  return (
+    isPlausibleLatLon(lat, lon) &&
+    lat >= 63.0 &&
+    lat <= 66.7 &&
+    lon >= -25.0 &&
+    lon <= -13.0
+  );
+}
+
 /**
  * Decode numeric HTML character references, decimal ("&#237;") and hex
  * ("&#xED;") alike, the entity form the Catalonia feed uses for accented
@@ -639,6 +650,10 @@ export function normalizeSourceItem(item) {
     feedType: normalizeFeedType(item.feedType || item.type || ''),
     url: typeof item.url === 'string' ? item.url : '',
     snapshotUrl: typeof item.snapshotUrl === 'string' ? item.snapshotUrl : '',
+    frameRefreshMs: toFiniteNumber(item.frameRefreshMs),
+    sourceUrl: typeof item.sourceUrl === 'string' ? item.sourceUrl : '',
+    accuracyM: toFiniteNumber(item.accuracyM),
+    positionSource: String(item.positionSource || ''),
     license: String(item.license || item.licenseNote || ''),
     // Per-camera attribution for feeds a partner supplies inside a pack
     // (DriveBC: TransLink, city cameras). Shown beside the provider.

server/providers/cctv/ottawa.js

@@ -0,0 +1,185 @@
+import {
+  CCTV_SOURCE_FETCH_TIMEOUT_MS,
+  DEFAULT_OTTAWA_MAX_SOURCES,
+  OTTAWA_ANCHORS,
+  OTTAWA_API_USER_ID,
+  OTTAWA_CAMERAS_URL,
+  OTTAWA_FRAME_REFRESH_MS,
+  OTTAWA_IMAGE_ORIGIN,
+  OTTAWA_IMAGE_URL,
+} from './constants.js';
+import {
+  fallbackHeadingFromId,
+  pinnedCameraUrl,
+  prioritizeSources,
+  toFiniteNumber,
+} from './normalize.js';
+
+let ottawaCertificateMissingLogged = false;
+
+/** Test hook: let the next missing-certificate skip log again. */
+export function _resetOttawaCertificateWarningForTest() {
+  ottawaCertificateMissingLogged = false;
+}
+
+/** The operator's Traffic Camera Images API certificate, trimmed. */
+function ottawaCertificate(env = process.env) {
+  return String(env.OTTAWA_CAMERA_CERTIFICATE ?? '').trim();
+}
+
+/**
+ * Add the operator's certificate to a registered keyless Ottawa frame URL.
+ * Only a URL inside the pinned `/opendata/` directory with a numeric camera
+ * number is signed, so the certificate never goes to any other path or host.
+ *
+ * @param {string} url - Canonical frame URL from the catalog.
+ * @param {Record<string,string|undefined>} [env]
+ * @returns {string} The signed URL, or '' when there is no certificate or the
+ *   URL is not a registered Ottawa frame.
+ */
+export function ottawaAuthorizedFrameUrl(url, env = process.env) {
+  const certificate = ottawaCertificate(env);
+  const pinned = pinnedCameraUrl(url, OTTAWA_IMAGE_ORIGIN);
+  if (!certificate || !pinned) return '';
+  const parsed = new URL(pinned);
+  const cameraNumber = parsed.searchParams.get('c') || '';
+  if (parsed.pathname !== '/opendata/camera' || !/^\d+$/.test(cameraNumber))
+    return '';
+  const signed = new URL(OTTAWA_IMAGE_URL(cameraNumber));
+  signed.searchParams.set('certificate', certificate);
+  signed.searchParams.set('id', OTTAWA_API_USER_ID);
+  return signed.href;
+}
+
+/**
+ * City of Ottawa envelope: Kanata to Orléans, Barrhaven to the river, with
+ * slack for the MTO cameras on the 416/417 that the city feed also carries.
+ */
+const OTTAWA_BOUNDS = Object.freeze({
+  minLat: 45.1,
+  maxLat: 45.65,
+  minLon: -76.2,
+  maxLon: -75.1,
+});
+
+/** Whether a point is inside the city feed's service area. */
+function isOttawaCoordinate(lat, lon) {
+  return (
+    Number.isFinite(lat) &&
+    Number.isFinite(lon) &&
+    lat >= OTTAWA_BOUNDS.minLat &&
+    lat <= OTTAWA_BOUNDS.maxLat &&
+    lon >= OTTAWA_BOUNDS.minLon &&
+    lon <= OTTAWA_BOUNDS.maxLon
+  );
+}
+
+/**
+ * Load the City of Ottawa's traffic cameras.
+ *
+ * Camera images come from the city's Traffic Camera Images API, which needs a
+ * certificate from the city's registration form (OTTAWA_CAMERA_CERTIFICATE)
+ * and allows one fetch per camera per minute for a certificate and user id.
+ * Without a certificate the pack is skipped, with no request and one log line.
+ * The camera list is the documented `map/service/camera` JSON: a camera
+ * number, English and French names, coordinates and the owner (CITY or MTO).
+ * The feed carries no bearing, no elevation and no status field, so headings
+ * use the same deterministic low-confidence fallback as the other
+ * heading-less packs and the client's ground snap refines the elevation
+ * prior.
+ *
+ * @param {object} [_options]
+ * @param {Record<string,string|undefined>} [env]
+ * @returns {Promise<Array<object>>} Cameras nearest downtown first, or [] on
+ *   a missing certificate or any upstream or payload failure.
+ */
+export async function loadOttawaSourcesFromOpenData(
+  _options = {},
+  env = process.env,
+) {
+  if (!ottawaCertificate(env)) {
+    if (!ottawaCertificateMissingLogged) {
+      ottawaCertificateMissingLogged = true;
+      console.warn(
+        '[CCTV] Ottawa cameras skipped: the city camera image API needs a certificate (set OTTAWA_CAMERA_CERTIFICATE)',
+      );
+    }
+    return [];
+  }
+  try {
+    const resp = await fetch(OTTAWA_CAMERAS_URL, {
+      headers: { Accept: 'application/json' },
+      signal: AbortSignal.timeout(CCTV_SOURCE_FETCH_TIMEOUT_MS),
+    });
+    if (!resp.ok) {
+      console.warn('[CCTV] Ottawa camera download failed:', resp.status);
+      return [];
+    }
+    const payload = await resp.json();
+    const rows = Array.isArray(payload?.cameras) ? payload.cameras : null;
+    if (!rows) return [];
+
+    const cameras = [];
+    const seen = new Set();
+    for (const row of rows) {
+      const number = toFiniteNumber(row?.camera_number);
+      if (!Number.isSafeInteger(number) || number <= 0 || seen.has(number))
+        continue;
+      const lat = toFiniteNumber(row?.latitude);
+      const lon = toFiniteNumber(row?.longitude);
+      if (!isOttawaCoordinate(lat, lon)) continue;
+      seen.add(number);
+
+      const cameraId = `ottawa-${number}`;
+      const imageUrl = OTTAWA_IMAGE_URL(number);
+      // The docs name the field camera_owner; the live feed sends cameraOwner.
+      const owner = String(row?.camera_owner || row?.cameraOwner || '')
+        .trim()
+        .toUpperCase();
+      cameras.push({
+        id: cameraId,
+        name: String(row?.name || '').trim() || `Ottawa camera ${number}`,
+        city: 'Ottawa',
+        cityId: 'ottawa',
+        provider: 'City of Ottawa',
+        lat,
+        lon,
+        headingDeg: fallbackHeadingFromId(cameraId),
+        headingConfidence: 'low',
+        pitchDeg: -18,
+        fovDeg: 44,
+        rangeM: 145,
+        mountHeightM: 8,
+        groundElevationM: 0,
+        feedType: 'image',
+        url: imageUrl,
+        snapshotUrl: imageUrl,
+        frameRefreshMs: OTTAWA_FRAME_REFRESH_MS,
+        sourceKind: 'ottawa-traffic',
+        license: 'City of Ottawa Traffic Camera Images API (registered access)',
+        credit:
+          owner === 'MTO'
+            ? 'Ministry of Transportation of Ontario (MTO) camera'
+            : '',
+      });
+    }
+
+    const maxRaw = Number(
+      process.env.CCTV_OTTAWA_MAX_SOURCES || DEFAULT_OTTAWA_MAX_SOURCES,
+    );
+    const maxCount = Number.isFinite(maxRaw)
+      ? Math.max(8, Math.min(500, Math.floor(maxRaw)))
+      : DEFAULT_OTTAWA_MAX_SOURCES;
+    const prioritized = prioritizeSources(cameras, maxCount, OTTAWA_ANCHORS);
+    console.log(
+      `[CCTV] Loaded Ottawa camera sources: ${cameras.length} published (using nearest ${prioritized.length})`,
+    );
+    return prioritized;
+  } catch (error) {
+    console.warn(
+      '[CCTV] Ottawa camera download error:',
+      error?.message || error,
+    );
+    return [];
+  }
+}

server/providers/cctv/quebec.js

@@ -0,0 +1,138 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { cameraDisplayCode, fallbackHeadingFromId } from './normalize.js';
+
+const QUEBEC_CATALOG_PATH = 'public/quebec-cameras.json';
+export const QUEBEC_CAMERA_SOURCE_COUNT = 1120;
+
+/**
+ * Whether the operator opted in to the browser-direct Québec 511 video. Off by
+ * default: the camera locations are CC BY 4.0, but whether Québec 511's
+ * service terms allow another site to embed its clips is unconfirmed, so an
+ * unset flag lists the cameras with a link to the 511 viewer page only.
+ */
+export function quebecBrowserVideoEnabled(env = process.env) {
+  return String(env.CCTV_QUEBEC_VIDEO_ENABLED || '').trim() === '1';
+}
+
+/** Build the direct browser-only MP4 URL for one namespaced MTQ camera id. */
+export function quebec511VideoUrl(cameraId) {
+  const match = /^qc-511-(\d+)$/.exec(String(cameraId || ''));
+  return match
+    ? `https://www.quebec511.info/Carte/Fenetres/camera.ashx?id=${match[1]}&format=mp4`
+    : '';
+}
+
+function safeViewerUrl(value) {
+  try {
+    const url = new URL(String(value || ''));
+    return url.protocol === 'https:' && !url.username && !url.password
+      ? url.href
+      : '';
+  } catch {
+    return '';
+  }
+}
+
+function sourceId(camera) {
+  const id = String(camera?.id || '').trim();
+  if (camera?.kind === 'traffic' && /^\d+$/.test(id)) return `qc-511-${id}`;
+  if (camera?.kind === 'montreal' && /^mtl-\d+(?:-\d+)*$/.test(id))
+    return `qc-mtl-${id.slice(4)}`;
+  if (camera?.kind === 'webcam' && /^web-\d+$/.test(id))
+    return `qc-web-${id.slice(4)}`;
+  return '';
+}
+
+/**
+ * Read the checked-in, no-key Québec location catalog and adapt it to the
+ * regular CCTV source schema. MTQ video stays browser-only; other rows link to
+ * their operator page because this dataset has no direct image URL for them.
+ */
+export function loadQuebecSources({ sourceRoot = process.cwd() } = {}) {
+  const filename = path.resolve(sourceRoot, QUEBEC_CATALOG_PATH);
+  let cameras;
+  try {
+    const payload = JSON.parse(fs.readFileSync(filename, 'utf8'));
+    cameras = Array.isArray(payload?.cameras) ? payload.cameras : [];
+  } catch (error) {
+    console.warn('[CCTV] Québec camera catalog unavailable:', error?.message);
+    return [];
+  }
+
+  const sources = [];
+  const seen = new Set();
+  for (const camera of cameras) {
+    const id = sourceId(camera);
+    const lat = Number(camera.lat);
+    const lon = Number(camera.lon);
+    if (
+      !id ||
+      seen.has(id) ||
+      !Number.isFinite(lat) ||
+      !Number.isFinite(lon) ||
+      lat < 44.9 ||
+      lat > 62.6 ||
+      lon < -79.9 ||
+      lon > -57.1
+    )
+      continue;
+    seen.add(id);
+
+    const name = String(camera.nameEn || camera.name || id).trim();
+    const isTraffic = camera.kind === 'traffic';
+    const isMontreal = camera.kind === 'montreal';
+    const sourceKind = isTraffic
+      ? 'quebec-511-browser'
+      : isMontreal
+        ? 'quebec-montreal-osm'
+        : 'quebec-webcam-link';
+    const provider = isTraffic
+      ? 'Québec 511 / MTQ'
+      : isMontreal
+        ? 'Ville de Montréal / OpenStreetMap'
+        : String(camera.operator || 'Québec webcam');
+
+    sources.push({
+      id,
+      name: name.slice(0, 180),
+      city: String(camera.region || 'Québec'),
+      cityId: 'quebec',
+      provider,
+      lat,
+      lon,
+      headingDeg: fallbackHeadingFromId(id),
+      headingConfidence: 'low',
+      pitchDeg: -18,
+      fovDeg: 74,
+      rangeM: 400,
+      mountHeightM: 8,
+      groundElevationM: 0,
+      feedType: 'image',
+      // No frame URL is registered: the server never fetches 511 media. With
+      // CCTV_QUEBEC_VIDEO_ENABLED=1 the browser plays the 511 MP4 in the DOM
+      // overlay after a play click; otherwise the camera links to 511.
+      url: '',
+      snapshotUrl: '',
+      sourceKind,
+      sourceUrl: safeViewerUrl(camera.viewerUrl),
+      accuracyM: Number.isFinite(Number(camera.accuracyM))
+        ? Number(camera.accuracyM)
+        : null,
+      positionSource: String(camera.positionSource || ''),
+      license: isTraffic
+        ? 'Locations: Données Québec / MTQ, CC BY 4.0. Video: hosted by Québec 511 under its terms of use'
+        : isMontreal
+          ? 'OpenStreetMap contributors, ODbL 1.0'
+          : 'Operator terms apply; location provenance shown per camera',
+      credit: isTraffic
+        ? 'Locations: MTQ · CC BY 4.0 · Video: Québec 511'
+        : isMontreal
+          ? 'OpenStreetMap contributors · ODbL'
+          : provider,
+      code: cameraDisplayCode(name.toUpperCase()),
+    });
+  }
+
+  return sources;
+}

server/providers/cctv/sources.js

@@ -134,6 +134,12 @@ import {
   HOUSTON_MAX_CATALOG_BYTES,
   HOUSTON_GROUND_ELEVATION_M,
   HOUSTON_ANCHORS,
+  ICELAND_CAMERAS_URL,
+  ICELAND_IMAGE_ORIGIN,
+  ICELAND_MAX_CATALOG_BYTES,
+  ICELAND_GROUND_ELEVATION_M,
+  DEFAULT_ICELAND_MAX_SOURCES,
+  ICELAND_ANCHORS,
 } from './constants.js';
 import {
   toFiniteNumber,
@@ -152,6 +158,7 @@ import {
   isLikelyCalgaryCoordinate,
   isLikelyFloridaCoordinate,
   isLikelyCataloniaCoordinate,
+  isLikelyIcelandCoordinate,
   decodeNumericEntities,
   isLikelyNycCoordinate,
   isLikelyHoustonCoordinate,
@@ -2029,6 +2036,174 @@ export async function loadCataloniaSourcesFromOpenData() {
   }
 }
 
+/**
+ * Compass headings for Icelandic direction words, as they appear after "til"
+ * (genitive: "til vesturs"), "í" (accusative: "í vestur") or "séð" ("seen",
+ * as in "séð austur").
+ */
+const ICELAND_DIRECTION_HEADINGS = {
+  norður: 0,
+  norðaustur: 45,
+  austur: 90,
+  suðaustur: 135,
+  suður: 180,
+  suðvestur: 225,
+  vestur: 270,
+  norðvestur: 315,
+};
+const ICELAND_DIRECTION_WORD =
+  '(norðaustur|norðvestur|suðaustur|suðvestur|norður|suður|austur|vestur)s?';
+/** A facing, plus a second one joined by "og" ("til austurs og vesturs"). */
+const ICELAND_DIRECTION_RE = new RegExp(
+  `(?<![\\p{L}])(?:til|í|séð)\\s+${ICELAND_DIRECTION_WORD}` +
+    `(?:\\s+og\\s+(?:til\\s+|í\\s+)?${ICELAND_DIRECTION_WORD})?(?![\\p{L}])`,
+  'gu',
+);
+
+/**
+ * The compass heading an Icelandic view description states, or NaN. Only an
+ * explicit "til <átt>", "í <átt>" or "séð <átt>" counts: a bare place name or
+ * a road direction ("Miklabraut austur") is not a facing. A description naming
+ * two different directions ("til norðurs og til suðurs", "til austurs og
+ * vesturs") is ambiguous and yields NaN, and "niður á veg" (down onto the
+ * road) states none.
+ *
+ * @param {string} text - The feed's `Skyring` field.
+ * @returns {number} Heading in degrees [0..360), or NaN.
+ */
+export function icelandHeadingFromDescription(text) {
+  const headings = new Set();
+  for (const match of String(text || '')
+    .toLowerCase()
+    .matchAll(ICELAND_DIRECTION_RE)) {
+    for (const word of [match[1], match[2]]) {
+      if (word) headings.add(ICELAND_DIRECTION_HEADINGS[word]);
+    }
+  }
+  return headings.size === 1 ? headings.values().next().value : NaN;
+}
+
+/**
+ * One Vegagerðin camera row -> one catalog source, or null. A row is one camera
+ * view; a station (`Maelist_nr`) carries several. The id comes from the frame
+ * file name, which is unique per view in the live feed.
+ *
+ * @param {object} row - Element of the `vefmyndavelar2014_1` array.
+ * @returns {?object}
+ */
+export function icelandCameraToSource(row) {
+  const url = pinnedCameraUrl(row?.Slod, ICELAND_IMAGE_ORIGIN);
+  if (!url || !/\.jpe?g$/i.test(new URL(url).pathname)) return null;
+  // Numbers only: Number(null) and Number('') are 0.
+  const lat = typeof row.Breidd === 'number' ? row.Breidd : NaN;
+  const lon = typeof row.Lengd === 'number' ? row.Lengd : NaN;
+  if (!isLikelyIcelandCoordinate(lat, lon)) return null;
+  const stem = new URL(url).pathname
+    .slice(new URL(ICELAND_IMAGE_ORIGIN).pathname.length)
+    .replace(/\.jpe?g$/i, '')
+    .toLowerCase();
+  if (!/^[a-z0-9_-]+$/.test(stem)) return null;
+  const cameraId = `is-vegagerdin-${stem}`;
+  const description = String(row.Skyring || '')
+    .replace(/\s+/g, ' ')
+    // Letter lookarounds, not \b: \b is ASCII-only and would join "Þverá
+    // Árnessýslu" while missing "séð séð".
+    .replace(/(?<!\p{L})(\p{L}+) \1(?!\p{L})/giu, '$1')
+    .trim();
+  const station = String(row.Myndavel || '').trim();
+  const heading = icelandHeadingFromDescription(description);
+  const hasHeading = Number.isFinite(heading);
+  return {
+    id: cameraId,
+    name: description || station || `Vegagerðin ${row.Maelist_nr ?? stem}`,
+    city: 'Iceland',
+    cityId: 'iceland',
+    provider: 'Vegagerðin (IRCA)',
+    lat,
+    lon,
+    headingDeg: hasHeading ? heading : fallbackHeadingFromId(cameraId),
+    headingConfidence: hasHeading ? 'high' : 'low',
+    pitchDeg: hasHeading ? -24 : -18,
+    fovDeg: hasHeading ? 56 : 44,
+    rangeM: hasHeading ? 210 : 145,
+    mountHeightM: hasHeading ? 10 : 8,
+    groundElevationM: ICELAND_GROUND_ELEVATION_M,
+    feedType: 'image',
+    url,
+    snapshotUrl: url,
+    sourceKind: 'iceland-vegagerdin',
+    license:
+      'Icelandic Road and Coastal Administration (IRCA) — road camera images, CC BY 4.0',
+    code: cameraDisplayCode(station.toUpperCase() || description),
+  };
+}
+
+/**
+ * Fetch Icelandic road cameras (Vegagerðin / IRCA), keyless: one JSON list.
+ * Frames are stills on the IRCA host and the loader registers only links
+ * inside that host's camera directory (ICELAND_IMAGE_ORIGIN). The list decides
+ * ids, coordinates, labels and which frame path is proxied, so it is fetched
+ * over https, redirects are refused and the body read is capped at
+ * ICELAND_MAX_CATALOG_BYTES.
+ *
+ * @returns {Promise<Array<object>>} Normalized camera source objects.
+ */
+export async function loadIcelandSourcesFromOpenData() {
+  try {
+    const resp = await fetch(ICELAND_CAMERAS_URL, {
+      headers: {
+        Accept: 'application/json',
+        'User-Agent': 'gods-eye-view-cctv-proxy/1.0',
+      },
+      redirect: 'manual',
+      signal: AbortSignal.timeout(CCTV_SOURCE_FETCH_TIMEOUT_MS),
+    });
+    // A response this loader will not read still owns its transport until the
+    // body is released, so every rejection path cancels before returning.
+    const discard = async () => {
+      try {
+        await resp.body?.cancel();
+      } catch {
+        /* no-op */
+      }
+      return [];
+    };
+    if (resp.status >= 300 && resp.status < 400) {
+      console.warn(
+        '[CCTV] Iceland catalog redirected; redirects are not followed',
+      );
+      return discard();
+    }
+    if (!resp.ok) {
+      console.warn('[CCTV] Iceland camera download failed:', resp.status);
+      return discard();
+    }
+    const body = await readResponseJsonCapped(resp, ICELAND_MAX_CATALOG_BYTES);
+    const rows = Array.isArray(body) ? body : [];
+    const cameras = rows.map(icelandCameraToSource).filter(Boolean);
+    const unique = Array.from(
+      new Map(cameras.map((camera) => [camera.id, camera])).values(),
+    );
+    const maxRaw = Number(
+      process.env.CCTV_ICELAND_MAX_SOURCES || DEFAULT_ICELAND_MAX_SOURCES,
+    );
+    const maxCount = Number.isFinite(maxRaw)
+      ? Math.max(8, Math.min(600, Math.floor(maxRaw)))
+      : DEFAULT_ICELAND_MAX_SOURCES;
+    const prioritized = prioritizeSources(unique, maxCount, ICELAND_ANCHORS);
+    console.log(
+      `[CCTV] Loaded Iceland camera sources: ${unique.length} (using nearest ${prioritized.length})`,
+    );
+    return prioritized;
+  } catch (error) {
+    console.warn(
+      '[CCTV] Iceland camera download error:',
+      error?.message || error,
+    );
+    return [];
+  }
+}
+
 /**
  * Read one XML child tag's text from an `<image>` block.
  *

server/providers/cctv/stream.js

@@ -5,7 +5,9 @@ export const HLS_LIMITS = Object.freeze({
   sessions: 2,
   leasesPerSession: 8,
   playlistBytes: 256 * 1024,
-  segmentBytes: 4 * 1024 * 1024,
+  // High-resolution cameras can exceed 4 MiB in a single ten-second TS segment.
+  // Retained data still shares the independent 24 MiB session budget below.
+  segmentBytes: 8 * 1024 * 1024,
   sessionBytes: 24 * 1024 * 1024,
   segments: 12,
   pollMs: 2000,

server/providers/cctv/taiwan.js

@@ -1,4 +1,7 @@
-import { CCTV_SOURCE_FETCH_TIMEOUT_MS } from './constants.js';
+import {
+  CCTV_SOURCE_FETCH_TIMEOUT_MS,
+  TAIWAN_HIGHWAY_IMAGE_ORIGINS,
+} from './constants.js';
 import {
   cameraDisplayCode,
   fallbackHeadingFromId,
@@ -10,6 +13,8 @@ import { readResponseTextCapped } from '../common/http.js';
  * standard, published keyless and refreshed daily (~1,800 cameras). */
 export const TAIWAN_FREEWAY_CCTV_URL =
   'https://tisvcloud.freeway.gov.tw/history/motc20/CCTV.xml';
+export const TAIWAN_HIGHWAY_CCTV_URL =
+  'https://cctv-maintain.thb.gov.tw/opendataCCTVs.xml';
 /** The whole network is ~1.2 MB. */
 export const TAIWAN_MAX_CATALOG_BYTES = 6 * 1024 * 1024;
 const DEFAULT_TAIWAN_MAX_SOURCES = 600;
@@ -35,6 +40,9 @@ const STREAM_TO_FRAME = new Map([
 ]);
 
 const DIRECTIONS = { N: 'N', S: 'S', E: 'E', W: 'W' };
+const TAIWAN_HIGHWAY_CAMERA_HOSTS = new Set(
+  TAIWAN_HIGHWAY_IMAGE_ORIGINS.map((origin) => new URL(origin).hostname),
+);
 
 /** Prioritization anchors, north to south, so a cap keeps the whole island
  * rather than only greater Taipei. */
@@ -211,6 +219,74 @@ export function taiwanCameraToSource(row) {
   };
 }
 
+/**
+ * One Highway Bureau row -> a source whose first MJPEG frame is served as a
+ * snapshot by the existing camera-frame proxy.
+ *
+ * @param {object} row - Output of parseTaiwanCctvXml.
+ * @returns {?object}
+ */
+export function taiwanHighwayCameraToSource(row) {
+  if (!row || typeof row !== 'object') return null;
+  const { lat, lon } = row;
+  if (!isLikelyTaiwanCoordinate(lat, lon)) return null;
+
+  let url;
+  try {
+    url = new URL(String(row.streamUrl ?? ''));
+  } catch {
+    return null;
+  }
+  if (
+    url.protocol !== 'https:' ||
+    url.username ||
+    url.password ||
+    url.port ||
+    url.search ||
+    url.hash ||
+    !TAIWAN_HIGHWAY_CAMERA_HOSTS.has(url.hostname) ||
+    !/^\/[A-Za-z0-9._+~-]{1,100}$/.test(url.pathname) ||
+    url.pathname.includes('..')
+  )
+    return null;
+
+  const rawId = String(row.cctvId ?? '').trim();
+  if (!/^[A-Za-z0-9-]{1,80}$/.test(rawId)) return null;
+  const cameraId = 'tw-thb-' + rawId.toLowerCase();
+  const road = String(row.roadName ?? '').trim();
+  const direction = DIRECTIONS[String(row.direction ?? '').trim()] || '';
+  const mile = String(row.mile ?? '').trim();
+  const section = [row.sectionStart, row.sectionEnd]
+    .map((part) => String(part ?? '').trim())
+    .filter(Boolean)
+    .join('→');
+  const name =
+    (road || mile || section
+      ? [road, direction, mile, section].filter(Boolean).join(' ')
+      : '') || rawId;
+
+  return {
+    id: cameraId,
+    name: name.slice(0, 160),
+    city: 'Taiwan / 臺灣',
+    cityId: 'taiwan',
+    provider: 'Highway Bureau, MOTC',
+    lat,
+    lon,
+    headingDeg: fallbackHeadingFromId(cameraId),
+    headingConfidence: 'low',
+    pitchDeg: -18,
+    fovDeg: 44,
+    rangeM: 145,
+    mountHeightM: 8,
+    feedType: 'mjpeg',
+    url: url.href,
+    snapshotUrl: url.href,
+    sourceKind: 'taiwan-highway-motc',
+    license: 'Highway Bureau, MOTC open data',
+    code: cameraDisplayCode((road + ' ' + mile).trim().toUpperCase() || rawId),
+  };
+}
 let lastGood = null;
 let lastGoodAt = 0;
 let retryAfter = 0;
@@ -237,6 +313,49 @@ function taiwanSourceCap() {
     : DEFAULT_TAIWAN_MAX_SOURCES;
 }
 
+/** Fetch the public provincial-road CCTV table as a no-key fallback. */
+async function loadTaiwanHighwaySources() {
+  const signal = AbortSignal.timeout(CCTV_SOURCE_FETCH_TIMEOUT_MS);
+  const response = await fetch(TAIWAN_HIGHWAY_CCTV_URL, {
+    headers: { Accept: 'application/xml,text/xml' },
+    redirect: 'manual',
+    signal,
+  });
+  if (!response.ok) {
+    await response.body?.cancel().catch(() => {});
+    throw new Error(
+      response.status >= 300 && response.status < 400
+        ? 'Highway Bureau catalog redirected; redirects are not followed'
+        : 'Highway Bureau catalog HTTP ' + response.status,
+    );
+  }
+  const xml = await readResponseTextCapped(
+    response,
+    TAIWAN_MAX_CATALOG_BYTES,
+    signal,
+  );
+  const cameras = new Map();
+  for (const row of parseTaiwanCctvXml(xml)) {
+    const camera = taiwanHighwayCameraToSource(row);
+    if (camera && !cameras.has(camera.id)) cameras.set(camera.id, camera);
+  }
+  if (!cameras.size)
+    throw new Error('no usable Highway Bureau cameras in the table');
+  const sources = prioritizeSources(
+    [...cameras.values()],
+    taiwanSourceCap(),
+    ANCHORS,
+  );
+  console.log(
+    '[CCTV] Loaded Taiwan Highway Bureau fallback: ' +
+      cameras.size +
+      ' (using ' +
+      sources.length +
+      ')',
+  );
+  return sources;
+}
+
 /**
  * Fetch Taiwan Freeway Bureau cameras from the keyless MOTC 2.0 XML table.
  * One bounded request per shared catalog refresh. A failed download serves the
@@ -262,7 +381,7 @@ export async function loadTaiwanSources() {
       throw new Error(
         response.status >= 300 && response.status < 400
           ? 'catalog redirected; redirects are not followed'
-          : `HTTP ${response.status}`,
+          : 'HTTP ' + response.status,
       );
     }
     const xml = await readResponseTextCapped(
@@ -282,7 +401,11 @@ export async function loadTaiwanSources() {
       ANCHORS,
     );
     console.log(
-      `[CCTV] Loaded Taiwan camera sources: ${cameras.size} (using ${sources.length})`,
+      '[CCTV] Loaded Taiwan camera sources: ' +
+        cameras.size +
+        ' (using ' +
+        sources.length +
+        ')',
     );
     lastGood = sources;
     lastGoodAt = Date.now();
@@ -291,13 +414,37 @@ export async function loadTaiwanSources() {
   } catch (error) {
     retryAfter = Date.now() + TAIWAN_RETRY_AFTER_FAILURE_MS;
     const fallback = fallbackSources();
-    console.warn(
-      `[CCTV] Taiwan camera download failed (${error?.message || error}); ` +
-        (fallback.length
-          ? `serving the last good ${fallback.length} cameras`
-          : 'no Taiwan cameras') +
-        ', next attempt in 1 h',
-    );
-    return fallback;
+    if (fallback.length) {
+      console.warn(
+        '[CCTV] Taiwan Freeway camera download failed (' +
+          (error?.message || error) +
+          '); serving the last good ' +
+          fallback.length +
+          ' cameras, next attempt in 1 h',
+      );
+      return fallback;
+    }
+    try {
+      const sources = await loadTaiwanHighwaySources();
+      lastGood = sources;
+      lastGoodAt = Date.now();
+      console.warn(
+        '[CCTV] Taiwan Freeway camera download failed (' +
+          (error?.message || error) +
+          '); using ' +
+          sources.length +
+          ' Highway Bureau cameras as fallback, next attempt in 1 h',
+      );
+      return sources;
+    } catch (fallbackError) {
+      console.warn(
+        '[CCTV] Taiwan Freeway camera download failed (' +
+          (error?.message || error) +
+          '); Highway Bureau fallback failed (' +
+          (fallbackError?.message || fallbackError) +
+          '); no Taiwan cameras, next attempt in 1 h',
+      );
+      return [];
+    }
   }
 }

server/providers/cctv/worldCameras.js

@@ -0,0 +1,132 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  DEFAULT_WORLD_CCTV_SOURCE_FILE,
+  MLIT_RIVER_IMAGE_ORIGIN,
+  TRIPCHECK_IMAGE_ORIGIN,
+  WORLD_CCTV_SOURCE_COUNT,
+} from './constants.js';
+import { pinnedCameraUrl } from './normalize.js';
+
+const SOURCE_POLICIES = Object.freeze({
+  'tripcheck-odot': {
+    idPrefix: 'world-or-',
+    origin: TRIPCHECK_IMAGE_ORIGIN,
+    bounds: [41, 47, -125, -116],
+    filename: /^\/roadcams\/cams\/[^/]+\.jpe?g$/i,
+    frameRefreshMs: 5 * 60 * 1000,
+  },
+  'mlit-river': {
+    idPrefix: 'world-jp-river-',
+    origin: MLIT_RIVER_IMAGE_ORIGIN,
+    bounds: [24, 46, 122, 154],
+    filename: /^\/cam\/now\/\d+\.jpg$/i,
+    // The provider asks clients to avoid frequent repeated image collection.
+    frameRefreshMs: 10 * 60 * 1000,
+  },
+});
+
+// MLIT currently serves this fixed JPEG on cameras whose images are paused
+// for maintenance (verified against two Yamagata cameras on 2026-11-02).
+const MLIT_ADJUSTMENT_IMAGE_SHA256 =
+  'dbd2c3790eb75edf9ca44162f7979f2a3799090e23f2c5142f63211a035cb191';
+
+export function isMlitRiverAdjustmentImage(image) {
+  return (
+    image?.ok === true &&
+    Buffer.isBuffer(image.body) &&
+    createHash('sha256').update(image.body).digest('hex') ===
+      MLIT_ADJUSTMENT_IMAGE_SHA256
+  );
+}
+
+function safeFrameUrl(value, policy) {
+  const normalized = pinnedCameraUrl(value, policy.origin);
+  if (!normalized) return '';
+  const url = new URL(normalized);
+  return !url.search && !url.hash && policy.filename.test(url.pathname)
+    ? url.href
+    : '';
+}
+
+function inBounds(lat, lon, [minLat, maxLat, minLon, maxLon]) {
+  return (
+    Number.isFinite(lat) &&
+    Number.isFinite(lon) &&
+    lat >= minLat &&
+    lat <= maxLat &&
+    lon >= minLon &&
+    lon <= maxLon
+  );
+}
+
+/**
+ * Load only the new image-backed networks from the add-on export. Existing
+ * Canadian networks, Québec entries, JMA placeholder images, and NZTA's
+ * scraped Journey Planner rows are deliberately excluded. Vegagerðin (Iceland)
+ * rows are excluded too: the Iceland pack loads the full live list of those
+ * cameras, so a World copy would draw each one twice.
+ */
+export function loadWorldCameraSources({ sourceRoot = process.cwd() } = {}) {
+  const filename = path.resolve(sourceRoot, DEFAULT_WORLD_CCTV_SOURCE_FILE);
+  let rows;
+  try {
+    const payload = JSON.parse(fs.readFileSync(filename, 'utf8'));
+    rows = Array.isArray(payload) ? payload : [];
+  } catch (error) {
+    console.warn('[CCTV] World camera catalog unavailable:', error?.message);
+    return [];
+  }
+
+  const seen = new Set();
+  const sources = [];
+  for (const row of rows) {
+    const sourceKind = String(row?.sourceKind || '');
+    const policy = SOURCE_POLICIES[sourceKind];
+    if (!policy) continue;
+
+    const id = String(row.id || '').trim();
+    const lat = Number(row.lat);
+    const lon = Number(row.lon);
+    const url = safeFrameUrl(row.url || row.snapshotUrl, policy);
+    const snapshotUrl = safeFrameUrl(row.snapshotUrl || row.url, policy);
+    if (
+      !id.startsWith(policy.idPrefix) ||
+      seen.has(id) ||
+      !inBounds(lat, lon, policy.bounds) ||
+      !url ||
+      !snapshotUrl ||
+      url !== snapshotUrl
+    )
+      continue;
+    seen.add(id);
+    sources.push({
+      id,
+      name: String(row.name || id)
+        .trim()
+        .slice(0, 180),
+      city: String(row.city || row.country || 'World'),
+      cityId: String(row.cityId || ''),
+      provider: String(row.provider || 'World traffic camera'),
+      lat,
+      lon,
+      headingDeg: Number.isFinite(Number(row.headingDeg))
+        ? Number(row.headingDeg)
+        : undefined,
+      headingConfidence: String(row.headingConfidence || 'low'),
+      feedType: 'image',
+      sourceKind,
+      url,
+      snapshotUrl,
+      frameRefreshMs: policy.frameRefreshMs,
+      license: String(row.license || ''),
+      credit: String(row.credit || row.provider || ''),
+    });
+  }
+
+  console.log(
+    `[CCTV] Loaded World camera image sources: ${sources.length}/${WORLD_CCTV_SOURCE_COUNT}`,
+  );
+  return sources;
+}

server/providers/common/compress.js

@@ -0,0 +1,81 @@
+import { gzip } from 'node:zlib';
+import { promisify } from 'node:util';
+
+const gzipAsync = promisify(gzip);
+
+/**
+ * Opt-in gzip for text bodies a proxy already holds in memory.
+ *
+ * Not a middleware: `cctv/media.js` streams bodies and answers range requests,
+ * and several providers forward binary upstream types that gzip only grows.
+ * `encodedBody` returns the body with its headers so the two cannot disagree.
+ */
+
+/** Skip compression for bodies smaller than 1 KiB. */
+const MIN_COMPRESSED_BYTES = 1024;
+
+/**
+ * RFC 9110 section 12.4.2 `qvalue`. Matching the whole token keeps `q=1oops`
+ * and `q=2` unreadable instead of rounding them into acceptance.
+ */
+const QVALUE = /^(?:0(?:\.\d{0,3})?|1(?:\.0{0,3})?)$/;
+
+/**
+ * Whether `Accept-Encoding` offers gzip. Anything unreadable (no header, a bad
+ * q value, `x-gzip`) reads as no: every client can decode identity.
+ *
+ * @param {import('node:http').IncomingMessage} request
+ * @returns {boolean}
+ */
+export function acceptsGzip(request) {
+  const header = request?.headers?.['accept-encoding'];
+  if (typeof header !== 'string') return false;
+  return header.split(',').some((part) => {
+    const [token, ...parameters] = part.split(';');
+    if (token.trim().toLowerCase() !== 'gzip') return false;
+    const quality = parameters
+      .map((parameter) => parameter.trim().toLowerCase())
+      .find((parameter) => parameter.startsWith('q='));
+    if (quality === undefined) return true;
+    // `q=0` names gzip and refuses it.
+    const value = quality.slice(2);
+    return QVALUE.test(value) && Number(value) > 0;
+  });
+}
+
+/**
+ * Gzip a body once for a caller that caches it. Async, so the ~860 KB OpenSky
+ * snapshot does not block other requests while it compresses.
+ *
+ * Returns null, meaning "serve identity", when the body is under 1 KiB or gzip
+ * does not shrink it.
+ *
+ * @param {string|Buffer} body - the exact bytes the identity response sends.
+ * @returns {Promise<Buffer|null>}
+ */
+export async function gzipBody(body) {
+  const raw = Buffer.isBuffer(body) ? body : Buffer.from(body);
+  if (raw.byteLength < MIN_COMPRESSED_BYTES) return null;
+  const compressed = await gzipAsync(raw);
+  return compressed.byteLength < raw.byteLength ? compressed : null;
+}
+
+/**
+ * Pick the body and the headers that describe it. `Vary` is on both branches
+ * so a shared cache never serves one encoding to a client that asked for the
+ * other.
+ *
+ * @param {import('node:http').IncomingMessage} request
+ * @param {string|Buffer} identity - the uncompressed body.
+ * @param {Buffer|null} compressed - `gzipBody(identity)`, or null.
+ * @returns {{body: string|Buffer, headers: Record<string,string>}}
+ */
+export function encodedBody(request, identity, compressed) {
+  if (compressed && acceptsGzip(request)) {
+    return {
+      body: compressed,
+      headers: { 'Content-Encoding': 'gzip', Vary: 'Accept-Encoding' },
+    };
+  }
+  return { body: identity, headers: { Vary: 'Accept-Encoding' } };
+}

server/providers/common/userAgent.js

@@ -0,0 +1,4 @@
+/** Identify each provider while keeping the project contact URL consistent. */
+export function providerUserAgent(name) {
+  return `gods-eye-view-${name}-proxy/1.0 (+https://github.com/bilawalsidhu/gods-eye-view)`;
+}

server/providers/inaturalist/client.js

@@ -0,0 +1,370 @@
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { normalizeInatObservations } from '../../../src/layers/wildlifeSightings/records.js';
+import { readResponseJsonCapped } from '../common/http.js';
+import { clampInt } from '../common/query.js';
+import { providerUserAgent } from '../common/userAgent.js';
+import { projectInatGrid, validInatGridTile } from './grid.js';
+import { createInatQueue } from './queue.js';
+
+const DAILY_BUDGET = 8000;
+const DAY_MS = 24 * 60 * 60_000;
+// One page is capped independently of upstream Content-Length.
+const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+const TIMEOUT_MS = 20_000;
+const API_URL = 'https://api.inaturalist.org/v1';
+// Request only the fields used by the public observation projection.
+const OBSERVATIONS_URL = 'https://api.inaturalist.org/v2/observations';
+const OBSERVATION_FIELDS =
+  '(id:!t,uri:!t,location:!t,geojson:all,geoprivacy:!t,taxon_geoprivacy:!t,' +
+  'obscured:!t,quality_grade:!t,observed_on:!t,' +
+  'time_observed_at:!t,faves_count:!t,' +
+  'num_identification_agreements:!t,' +
+  'photos:(url:!t,attribution:!t,license_code:!t),' +
+  'taxon:(name:!t,preferred_common_name:!t,iconic_taxon_name:!t,' +
+  'threatened:!t))';
+const COOLDOWN_MS = 60_000;
+const FAILURE_COOLDOWN_MS = 15_000;
+
+/** Seconds and HTTP dates are accepted; a missing value earns one minute. */
+export function inatRetryCooldownMs(raw, nowMs) {
+  const value = typeof raw === 'string' ? raw.trim() : '';
+  if (value) {
+    const seconds = /^\d+(?:\.\d+)?$/.test(value) ? Number(value) : NaN;
+    const deadline =
+      !Number.isFinite(seconds) && /[a-z]/i.test(value)
+        ? Date.parse(value)
+        : NaN;
+    const delay = Number.isFinite(seconds) ? seconds * 1000 : deadline - nowMs;
+    if (Number.isFinite(delay) && delay >= 0) return delay;
+  }
+  return COOLDOWN_MS;
+}
+
+function upstreamError(code, status, retryAfterS, upstreamStatus) {
+  return Object.assign(new Error(code), {
+    code,
+    status,
+    retryAfterS,
+    upstreamStatus,
+  });
+}
+
+function observationFilters(params) {
+  const query = new URLSearchParams({
+    verifiable: 'true',
+    captive: 'false',
+    // d1 is an observation DATE, unlike creation-time created_d1.
+    d1: params.observedD1,
+  });
+  if (params.taxa !== 'whales') query.set('photos', 'true');
+  if (params.quality === 'research') query.set('quality_grade', 'research');
+  if (params.taxa === 'whales') query.set('taxon_id', '152871');
+  else if (['Aves', 'Mammalia', 'Insecta', 'Plantae'].includes(params.taxa))
+    query.set('iconic_taxa', params.taxa);
+  return query;
+}
+
+/**
+ * Shared iNaturalist governor. Only request counters are persisted; observation
+ * payloads are projected immediately and are never written to disk.
+ */
+export function createInatClient({
+  fetchImpl = (...args) => globalThis.fetch(...args),
+  now = () => Date.now(),
+  cacheDir = path.join(process.cwd(), '.gev-cache', 'inaturalist'),
+  warn = (...args) => console.warn(...args),
+  queueOptions,
+} = {}) {
+  const enqueue = createInatQueue(queueOptions);
+  let budget = null;
+  let budgetLoaded = false;
+  let budgetTail = Promise.resolve();
+  let cooldownUntil = 0;
+  // An unavailable UTFGrid tile must never place observation queries into a
+  // 502 cooldown. Only an upstream 429 is a provider-wide restriction.
+  const failures = new Map();
+
+  function dailyLimit() {
+    return clampInt(
+      process.env.INATURALIST_DAILY_BUDGET,
+      1,
+      Number.MAX_SAFE_INTEGER,
+      DAILY_BUDGET,
+    );
+  }
+
+  function day() {
+    return new Date(now()).toISOString().slice(0, 10);
+  }
+
+  function currentBudget() {
+    const date = day();
+    if (budget?.date !== date) budget = { date, count: 0 };
+    return budget;
+  }
+
+  async function readBudgetOnce() {
+    if (budgetLoaded) return;
+    budgetLoaded = true;
+    if (cacheDir === null) return;
+    try {
+      const value = JSON.parse(
+        await fs.readFile(path.join(cacheDir, 'budget.json'), 'utf8'),
+      );
+      if (
+        typeof value?.date === 'string' &&
+        /^\d{4}-\d{2}-\d{2}$/.test(value.date) &&
+        Number.isSafeInteger(value.count) &&
+        value.count >= 0
+      )
+        budget = { date: value.date, count: value.count };
+    } catch (error) {
+      if (error.code !== 'ENOENT')
+        warn('[inaturalist-proxy] budget read failed');
+    }
+  }
+
+  async function persistBudget(value) {
+    if (cacheDir === null) return;
+    const destination = path.join(cacheDir, 'budget.json');
+    const temporary = `${destination}.${randomUUID()}.tmp`;
+    try {
+      await fs.mkdir(cacheDir, { recursive: true });
+      await fs.writeFile(temporary, JSON.stringify(value), 'utf8');
+      await fs.rename(temporary, destination);
+    } catch {
+      await fs.rm(temporary, { force: true }).catch(() => {});
+      warn('[inaturalist-proxy] budget write failed');
+    }
+  }
+
+  function retrySeconds(until = cooldownUntil) {
+    return Math.max(0, Math.ceil((until - now()) / 1000));
+  }
+
+  function checkCooldown(resource) {
+    if (now() < cooldownUntil)
+      throw upstreamError('inaturalist_rate_limited', 429, retrySeconds(), 429);
+    const failure = failures.get(resource);
+    if (failure && now() < failure.until)
+      throw upstreamError(
+        'inaturalist_unavailable',
+        502,
+        retrySeconds(failure.until),
+        failure.status,
+      );
+    failures.delete(resource);
+  }
+
+  // Reserve and atomically persist one attempt before issuing it. A recovered
+  // tail prevents one disk/reservation failure from poisoning future calls.
+  function reserveAttempt(signal, resource) {
+    const result = budgetTail.then(async () => {
+      signal?.throwIfAborted();
+      checkCooldown(resource);
+      await readBudgetOnce();
+      signal?.throwIfAborted();
+      checkCooldown(resource);
+      const value = currentBudget();
+      if (value.count >= dailyLimit()) {
+        const retry = Math.max(
+          1,
+          Math.ceil((Date.parse(`${day()}T00:00:00Z`) + DAY_MS - now()) / 1000),
+        );
+        throw upstreamError('inaturalist_budget_exhausted', 503, retry);
+      }
+      value.count += 1;
+      await persistBudget({ ...value });
+    });
+    budgetTail = result.catch(() => {});
+    return result;
+  }
+
+  async function requestProjected(url, project, resource, { signal } = {}) {
+    signal?.throwIfAborted();
+    checkCooldown(resource);
+    return enqueue(() => dispatch(url, project, resource, signal), {
+      signal,
+      priority: resource === 'observations' ? 0 : 1,
+    });
+  }
+
+  async function dispatch(url, project, resource, signal) {
+    signal?.throwIfAborted();
+    await reserveAttempt(signal, resource);
+    signal?.throwIfAborted();
+    checkCooldown(resource);
+    const timeout = AbortSignal.timeout(TIMEOUT_MS);
+    const requestSignal = signal ? AbortSignal.any([signal, timeout]) : timeout;
+    let upstreamStatus;
+    let retryDelay = FAILURE_COOLDOWN_MS;
+    try {
+      const response = await fetchImpl(url, {
+        signal: requestSignal,
+        redirect: 'error',
+        headers: {
+          Accept: 'application/json',
+          'User-Agent': providerUserAgent('wildlife-sightings'),
+        },
+      });
+      upstreamStatus = response.status;
+      if (!response.ok) {
+        await response.body?.cancel().catch(() => {});
+        if (response.status === 429) {
+          const delay = inatRetryCooldownMs(
+            response.headers.get('retry-after'),
+            now(),
+          );
+          cooldownUntil = Math.max(cooldownUntil, now() + delay);
+          throw upstreamError(
+            'inaturalist_rate_limited',
+            429,
+            retrySeconds(),
+            429,
+          );
+        }
+        if (response.headers.has('retry-after'))
+          retryDelay = inatRetryCooldownMs(
+            response.headers.get('retry-after'),
+            now(),
+          );
+        throw upstreamError('inaturalist_unavailable', 502);
+      }
+      const payload = await readResponseJsonCapped(
+        response,
+        MAX_RESPONSE_BYTES,
+        requestSignal,
+      );
+      return project(payload);
+    } catch (error) {
+      // Log only safe diagnostic categories, never a URL, body, status text or
+      // exception message (each can contain request/private information).
+      const reason = signal?.aborted
+        ? 'abort'
+        : timeout.aborted || error.name === 'TimeoutError'
+          ? 'timeout'
+          : upstreamStatus && upstreamStatus >= 400
+            ? 'http'
+            : error.code === 'RESPONSE_TOO_LARGE'
+              ? 'response-too-large'
+              : upstreamStatus
+                ? 'invalid-payload'
+                : 'network';
+      warn(
+        `[inaturalist-proxy] upstream refresh failed resource=${resource} status=${upstreamStatus ?? 'none'} reason=${reason}`,
+      );
+      if (signal?.aborted) throw error;
+      // Network, abort, schema and size failures are not upstream cooldown
+      // signals. A later healthy request may recover immediately.
+      if (upstreamStatus >= 500)
+        failures.set(resource, {
+          until: now() + retryDelay,
+          status: upstreamStatus,
+        });
+      const failure = failures.get(resource);
+      throw upstreamError(
+        error.status === 429
+          ? 'inaturalist_rate_limited'
+          : 'inaturalist_unavailable',
+        error.status === 429 ? 429 : 502,
+        error.status === 429
+          ? retrySeconds()
+          : failure
+            ? retrySeconds(failure.until)
+            : undefined,
+        upstreamStatus === 429 || upstreamStatus >= 500
+          ? upstreamStatus
+          : undefined,
+      );
+    }
+  }
+
+  /** Request one bounded observation sample and project its public fields. */
+  async function getObservations(params, options = {}) {
+    const query = observationFilters(params);
+    // View samples stay stable in the route cache until their TTL expires.
+    query.set('order_by', params.scope === 'view' ? 'random' : 'observed_on');
+    if (params.scope !== 'view') query.set('order', 'desc');
+    query.set('per_page', '200');
+    query.set('fields', OBSERVATION_FIELDS);
+    if (params.scope === 'view') {
+      query.set('swlat', String(params.box.south));
+      query.set('swlng', String(params.box.west));
+      query.set('nelat', String(params.box.north));
+      query.set('nelng', String(params.box.east));
+    }
+    return requestProjected(
+      `${OBSERVATIONS_URL}?${query}`,
+      (payload) => {
+        if (
+          !Array.isArray(payload?.results) ||
+          !Number.isSafeInteger(payload.total_results) ||
+          payload.total_results < 0
+        )
+          throw upstreamError('inaturalist_unavailable', 502);
+        const rows = normalizeInatObservations(payload.results, {
+          nowMs: now(),
+          windowMs: (params.taxa === 'whales' ? 7 : 2) * DAY_MS,
+        });
+        // Empty views need total_results: 0. A wholly invalid page must not
+        // replace good data. Valid rows excluded by the finer rolling-time
+        // cutoff are a healthy empty result of the upstream DATE over-fetch.
+        if (
+          !rows ||
+          (!rows.length &&
+            (payload.results.length || payload.total_results) &&
+            !normalizeInatObservations(payload.results)?.length)
+        )
+          throw upstreamError('inaturalist_unavailable', 502);
+        return {
+          rows,
+          totalResults: payload.total_results,
+          ...(payload.total_results > payload.results.length
+            ? { partial: true, rawRowCount: payload.total_results }
+            : {}),
+        };
+      },
+      'observations',
+      options,
+    );
+  }
+
+  /** Decode one validated density tile without observation identifiers. */
+  async function getGrid(params, options = {}) {
+    if (!validInatGridTile(params)) throw new TypeError('Invalid grid tile');
+    const query = observationFilters(params);
+    return requestProjected(
+      `${API_URL}/grid/${params.z}/${params.x}/${params.y}.grid.json?${query}`,
+      (payload) => projectInatGrid(payload, params),
+      'grid',
+      options,
+    );
+  }
+
+  return {
+    getObservations,
+    getGrid,
+    /** Current provider-wide or resource-specific retry information. */
+    cooldownState(resource) {
+      if (now() < cooldownUntil)
+        return {
+          upstreamStatus: 429,
+          retryAfterS: retrySeconds(),
+        };
+      const failure = failures.get(resource);
+      if (failure && now() < failure.until)
+        return {
+          upstreamStatus: failure.status,
+          retryAfterS: retrySeconds(failure.until),
+        };
+      return undefined;
+    },
+    /** The current UTC day's reserved upstream attempts and configured limit. */
+    budgetState() {
+      const value = currentBudget();
+      return { ...value, budget: dailyLimit() };
+    },
+  };
+}

server/providers/inaturalist/client.test.mjs

@@ -0,0 +1,163 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createInatClient } from './client.js';
+import { syntheticGrid } from './grid.fixture.mjs';
+
+const NOW = Date.parse('2026-11-04T18:05:00Z');
+const observation = (id, time) => ({
+  id,
+  geojson: { coordinates: [-122.3, 47.6] },
+  quality_grade: 'research',
+  time_observed_at: time,
+  observed_on: time.slice(0, 10),
+  // Upload age does not determine whether an observation is recent.
+  created_at: '2026-11-04T18:00:00Z',
+  taxon: { name: 'Synthetic taxon', iconic_taxon_name: 'Aves' },
+});
+
+function clientFor(results) {
+  return createInatClient({
+    now: () => NOW,
+    cacheDir: null,
+    queueOptions: { intervalMs: 0 },
+    warn() {},
+    fetchImpl: async () =>
+      Response.json({ results, total_results: results.length }),
+  });
+}
+
+test('iNaturalist drops ancient and boundary-expired observations uploaded today', async () => {
+  const client = clientFor([
+    observation(1, '2010-11-04T18:00:00Z'),
+    observation(2, '2026-11-02T18:04:59Z'),
+    observation(3, '2026-11-02T18:05:00Z'),
+  ]);
+  const result = await client.getObservations({
+    scope: 'global',
+    taxa: 'all',
+    observedD1: '2026-11-02',
+  });
+  assert.deepEqual(
+    result.rows.map((row) => row.stableId),
+    ['inat:3'],
+  );
+});
+
+test('a valid date-filtered page can be empty after the exact recency cutoff', async () => {
+  const client = clientFor([observation(1, '2026-11-02T06:00:00Z')]);
+  const result = await client.getObservations({
+    scope: 'global',
+    taxa: 'all',
+    observedD1: '2026-11-02',
+  });
+  assert.deepEqual(result.rows, []);
+  assert.equal(result.totalResults, 1);
+});
+
+const params = {
+  scope: 'view',
+  box: { south: 47, west: -123, north: 48, east: -122 },
+  taxa: 'all',
+  observedD1: '2026-11-02',
+};
+
+test('observations and tiles share pacing, and observation priority wins a cold burst', async () => {
+  let at = 0;
+  const calls = [];
+  const client = createInatClient({
+    cacheDir: null,
+    now: () => NOW + at,
+    queueOptions: {
+      now: () => at,
+      wait: async (ms) => {
+        at += ms;
+      },
+    },
+    fetchImpl: async (url) => {
+      const isGrid = new URL(url).pathname.includes('/grid/');
+      calls.push([isGrid ? 'grid' : 'observations', at]);
+      return Response.json(
+        isGrid ? syntheticGrid() : { results: [], total_results: 0 },
+      );
+    },
+  });
+  const tiles = Array.from({ length: 3 }, (_, x) =>
+    client.getGrid({ ...params, z: 2, x, y: 1 }),
+  );
+  await Promise.all([...tiles, client.getObservations(params)]);
+  assert.deepEqual(calls, [
+    ['observations', 0],
+    ['grid', 0],
+    ['grid', 0],
+    ['grid', 0],
+  ]);
+  assert.equal(client.budgetState().count, 4);
+});
+
+test('upstream status and safe failure reasons are logged without upstream messages or URLs', async () => {
+  for (const [response, expected] of [
+    [
+      () =>
+        new Response('request-secret', {
+          status: 503,
+          statusText: 'request-secret',
+        }),
+      /status=503 reason=http/,
+    ],
+    [
+      () => Promise.reject(new DOMException('request-secret', 'TimeoutError')),
+      /status=none reason=timeout/,
+    ],
+    [
+      () => Response.json({ unexpected: 'request-secret' }),
+      /status=200 reason=invalid-payload/,
+    ],
+  ]) {
+    const warnings = [];
+    const client = createInatClient({
+      cacheDir: null,
+      now: () => NOW,
+      queueOptions: { intervalMs: 0 },
+      warn: (message) => warnings.push(message),
+      fetchImpl: response,
+    });
+    await assert.rejects(client.getObservations(params), { status: 502 });
+    assert.equal(warnings.length, 1);
+    assert.match(warnings[0], expected);
+    assert.doesNotMatch(warnings[0], /request-secret|https?:|swlat|d1=/);
+  }
+});
+
+test('a dispatched abort is diagnosed, spends only its attempt, and leaves the next request healthy', async () => {
+  const warnings = [];
+  const controller = new AbortController();
+  let started;
+  const didStart = new Promise((resolve) => {
+    started = resolve;
+  });
+  let calls = 0;
+  const client = createInatClient({
+    cacheDir: null,
+    now: () => NOW,
+    queueOptions: { intervalMs: 0 },
+    warn: (message) => warnings.push(message),
+    fetchImpl: async (url, { signal }) => {
+      calls += 1;
+      if (calls > 1) return Response.json({ results: [], total_results: 0 });
+      started();
+      return new Promise((resolve, reject) =>
+        signal.addEventListener('abort', () => reject(signal.reason), {
+          once: true,
+        }),
+      );
+    },
+  });
+  const pending = client.getObservations(params, { signal: controller.signal });
+  const failed = assert.rejects(pending, { name: 'AbortError' });
+  await didStart;
+  controller.abort();
+  await failed;
+  assert.match(warnings[0], /resource=observations status=none reason=abort/);
+  await client.getObservations(params);
+  assert.equal(calls, 2);
+});

server/providers/inaturalist/grid.fixture.mjs

@@ -0,0 +1,51 @@
+/** Build a synthetic UTFGrid with logical cell counts and repeated hit pixels. */
+export function syntheticGrid({
+  z = 2,
+  x = 1,
+  y = 1,
+  cells = [
+    { row: 1, column: 51, count: 6, iconic: 3 },
+    { row: 3, column: 49, count: 12, iconic: 47170 },
+  ],
+} = {}) {
+  const pixels = Array.from({ length: 64 }, () => Array(64).fill(' '));
+  const keys = [''];
+  const data = {};
+  cells.forEach((cell, index) => {
+    const key = String(900_000_000 + index);
+    keys.push(key);
+    const value = index + 1;
+    let code = value + 32;
+    if (code >= 34) code += 1;
+    if (code >= 92) code += 1;
+    const character = String.fromCharCode(code);
+    for (const [row, column] of [
+      [cell.row, cell.column],
+      [cell.row - 1, cell.column],
+      [cell.row + 1, cell.column],
+      [cell.row, cell.column - 1],
+      [cell.row, cell.column + 1],
+    ]) {
+      if (row >= 0 && row < 64 && column >= 0 && column < 64)
+        pixels[row][column] = character;
+    }
+    data[key] = {
+      captive: null,
+      cellCount: cell.count,
+      geoprivacy: null,
+      id: Number(key),
+      latitude:
+        (Math.atan(
+          Math.sinh(Math.PI * (1 - 2 * ((y + cell.row / 64) / 2 ** z))),
+        ) *
+          180) /
+        Math.PI,
+      longitude: ((x + cell.column / 64) / 2 ** z) * 360 - 180,
+      private_location: null,
+      quality_grade: 'needs_id',
+      'taxon.iconic_taxon_id': cell.iconic,
+      uuid: `00000000-0000-4000-8000-${String(index).padStart(12, '0')}`,
+    };
+  });
+  return { grid: pixels.map((row) => row.join('')), keys, data };
+}

server/providers/inaturalist/grid.js

@@ -0,0 +1,127 @@
+// iNaturalist's operational /v1/grid/{z}/{x}/{y}.grid.json endpoint is not
+// covered by its v1 Swagger contract. Validate the entire UTFGrid shape before
+// accepting any cell; callers preserve the last good sample on schema drift.
+import {
+  wildlifeGridCellId,
+  WILDLIFE_GRID_MAX_ZOOM,
+} from '../../../src/layers/wildlifeSightings/gridViewport.js';
+
+const INAT_GRID_SIZE = 64;
+export const INAT_GRID_DECODE_MEASURE = 'wildlife:server:tile-decode';
+const grades = new Set(['research', 'needs_id', 'casual']);
+const object = (value) =>
+  !!value && typeof value === 'object' && !Array.isArray(value);
+
+/** Accept only integer XYZ coordinates within the supported zoom range. */
+export function validInatGridTile({ z, x, y } = {}) {
+  return (
+    Number.isInteger(z) &&
+    z >= 0 &&
+    z <= WILDLIFE_GRID_MAX_ZOOM &&
+    Number.isInteger(x) &&
+    Number.isInteger(y) &&
+    x >= 0 &&
+    y >= 0 &&
+    x < 2 ** z &&
+    y < 2 ** z
+  );
+}
+
+/** Pure allow-list projection. A UTFGrid key is an observation identifier and
+ * its repeated pixels form a dilated hit area, not additional occupied cells.
+ * Neither those keys nor representative/private fields cross this boundary. */
+export function projectInatGrid(payload, tile) {
+  const start = `${INAT_GRID_DECODE_MEASURE}:start`;
+  const end = `${INAT_GRID_DECODE_MEASURE}:end`;
+  performance.mark(start);
+  try {
+    return decodeInatGrid(payload, tile);
+  } finally {
+    performance.mark(end);
+    // Keep the latest sample inspectable without retaining every tile forever.
+    // PerformanceObservers still receive each individual decode measurement.
+    performance.clearMeasures(INAT_GRID_DECODE_MEASURE);
+    performance.measure(INAT_GRID_DECODE_MEASURE, start, end);
+    performance.clearMarks(start);
+    performance.clearMarks(end);
+  }
+}
+
+function decodeInatGrid(payload, tile) {
+  const invalid = () => {
+    throw new TypeError('Invalid iNaturalist UTFGrid');
+  };
+  if (
+    !validInatGridTile(tile) ||
+    !object(payload) ||
+    !Array.isArray(payload.grid) ||
+    payload.grid.length !== INAT_GRID_SIZE ||
+    !payload.grid.every(
+      (row) => typeof row === 'string' && row.length === INAT_GRID_SIZE,
+    ) ||
+    !Array.isArray(payload.keys) ||
+    !payload.keys.length ||
+    payload.keys.length > INAT_GRID_SIZE ** 2 + 1 ||
+    payload.keys[0] !== '' ||
+    !payload.keys.every(
+      (key) => typeof key === 'string' && key.length <= 128,
+    ) ||
+    new Set(payload.keys).size !== payload.keys.length ||
+    !object(payload.data)
+  )
+    invalid();
+  const dataKeys = Object.keys(payload.data);
+  if (dataKeys.length !== payload.keys.length - 1) invalid();
+  for (const key of payload.keys.slice(1)) {
+    if (!key || !Object.hasOwn(payload.data, key)) invalid();
+    const value = payload.data[key];
+    if (
+      !object(value) ||
+      !Number.isSafeInteger(value.cellCount) ||
+      value.cellCount <= 0 ||
+      !Number.isFinite(value.latitude) ||
+      Math.abs(value.latitude) > 90 ||
+      !Number.isFinite(value.longitude) ||
+      Math.abs(value.longitude) > 180 ||
+      !grades.has(value.quality_grade) ||
+      !(
+        value['taxon.iconic_taxon_id'] === null ||
+        (Number.isSafeInteger(value['taxon.iconic_taxon_id']) &&
+          value['taxon.iconic_taxon_id'] > 0)
+      )
+    )
+      invalid();
+  }
+  const occupied = new Set();
+  for (const line of payload.grid) {
+    for (let column = 0; column < INAT_GRID_SIZE; column += 1) {
+      let code = line.charCodeAt(column);
+      if (code < 32 || code === 34 || code === 92) invalid();
+      if (code >= 93) code -= 1;
+      if (code >= 35) code -= 1;
+      const index = code - 32;
+      if (index < 0 || index >= payload.keys.length) invalid();
+      if (index) occupied.add(payload.keys[index]);
+    }
+  }
+  if (occupied.size !== dataKeys.length) invalid();
+  const cells = new Map();
+  for (const key of occupied) {
+    const value = payload.data[key];
+    const id = wildlifeGridCellId(value.latitude, value.longitude, tile.z);
+    const cell = {
+      id,
+      cellCount: value.cellCount,
+      lat: value.latitude,
+      lon: value.longitude,
+    };
+    // Two different representatives claiming one logical cell are a contract
+    // change; summing or choosing one silently would fabricate the count.
+    if (cells.has(id)) invalid();
+    cells.set(id, cell);
+  }
+  const rows = [...cells.values()];
+  const totalResults = rows.reduce((total, cell) => total + cell.cellCount, 0);
+  if (!Number.isSafeInteger(totalResults)) invalid();
+  return { cells: rows, totalResults };
+}

server/providers/inaturalist/grid.test.mjs

@@ -0,0 +1,374 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { projectInatGrid } from './grid.js';
+import { syntheticGrid } from './grid.fixture.mjs';
+import { installInatProxy, NOW } from './proxy.fixture.mjs';
+import { createInatClient } from './client.js';
+
+const tile = { z: 2, x: 1, y: 1 };
+const gridUrl = '/grid?z=2&x=1&y=1&taxa=Aves&quality=research';
+const install = (options, hook) => installInatProxy(gridUrl, options, hook);
+
+test('UTFGrid projection validates the full shape and counts each logical occupied cell once', () => {
+  const raw = syntheticGrid();
+  const projected = projectInatGrid(raw, tile);
+  assert.equal(raw.grid.length, 64);
+  assert.ok(raw.grid.every((row) => row.length === 64));
+  assert.equal(
+    raw.grid.join('').split('!').length - 1,
+    5,
+    'one key is repeated by its hit area',
+  );
+  assert.equal(projected.cells.length, 2);
+  assert.equal(projected.totalResults, 18);
+  assert.deepEqual(projected.cells[0], {
+    id: 'grid:2/1/1:1:51',
+    cellCount: 6,
+    lat: raw.data[raw.keys[1]].latitude,
+    lon: raw.data[raw.keys[1]].longitude,
+  });
+  for (const cell of projected.cells)
+    assert.deepEqual(Object.keys(cell).sort(), [
+      'cellCount',
+      'id',
+      'lat',
+      'lon',
+    ]);
+  for (const privateField of [
+    '900000000',
+    'uuid',
+    'geoprivacy',
+    'private_location',
+    'captive',
+    'quality_grade',
+  ])
+    assert.ok(!JSON.stringify(projected).includes(privateField));
+});
+
+test('legitimate blank grid and null/unknown iconic ids remain safe', () => {
+  assert.deepEqual(projectInatGrid(syntheticGrid({ cells: [] }), tile), {
+    cells: [],
+    totalResults: 0,
+  });
+  const raw = syntheticGrid({
+    cells: [{ row: 1, column: 1, count: 1, iconic: null }],
+  });
+  const projected = projectInatGrid(raw, tile);
+  assert.equal(projected.cells[0].cellCount, 1);
+  raw.data[raw.keys[1]]['taxon.iconic_taxon_id'] = 999999;
+  assert.deepEqual(projectInatGrid(raw, tile), projected);
+});
+
+test('schema drift anywhere fails closed, including unused, malformed and orphan cells', () => {
+  const changes = [
+    (raw) => {
+      raw.grid.pop();
+    },
+    (raw) => {
+      raw.grid[0] = '';
+    },
+    (raw) => {
+      raw.grid[0] = '~'.repeat(64);
+    },
+    (raw) => {
+      raw.keys[0] = 'not-empty';
+    },
+    (raw) => {
+      raw.keys.push(raw.keys[1]);
+    },
+    (raw) => {
+      delete raw.data[raw.keys[1]];
+    },
+    (raw) => {
+      raw.data.extra = {};
+    },
+    (raw) => {
+      raw.data[raw.keys[1]].cellCount = -1;
+    },
+    (raw) => {
+      raw.data[raw.keys[1]].latitude = '47';
+    },
+    (raw) => {
+      raw.data[raw.keys[1]].longitude = 181;
+    },
+    (raw) => {
+      raw.data[raw.keys[1]].quality_grade = 'new-grade';
+    },
+    (raw) => {
+      delete raw.data[raw.keys[1]]['taxon.iconic_taxon_id'];
+    },
+    (raw) => {
+      raw.data[raw.keys[1]]['taxon.iconic_taxon_id'] = 'Aves';
+    },
+    (raw) => {
+      raw.grid = Array(64).fill(' '.repeat(64));
+    },
+  ];
+  for (const change of changes) {
+    const raw = syntheticGrid();
+    change(raw);
+    assert.throws(
+      () => projectInatGrid(raw, tile),
+      /Invalid iNaturalist UTFGrid/,
+    );
+  }
+});
+
+for (const hook of ['configureServer', 'configurePreviewServer']) {
+  test(`${hook}: fixed grid URL shares filters, caps and allow-list cache`, async () => {
+    const calls = [];
+    const cache = new Map();
+    const request = install(
+      {
+        cache,
+        fetchImpl: async (url, options) => {
+          calls.push(new URL(url));
+          assert.equal(options.redirect, 'error');
+          assert.ok(options.signal instanceof AbortSignal);
+          assert.match(
+            options.headers['User-Agent'],
+            /^gods-eye-view-wildlife-sightings-proxy/,
+          );
+          return Response.json(syntheticGrid());
+        },
+      },
+      hook,
+    );
+    assert.equal(calls.length, 0);
+    const response = await request(
+      `${gridUrl}&url=https://attacker.test&per_page=999`,
+    );
+    assert.equal(response.status, 200);
+    assert.equal(response.body.cells.length, 2);
+    assert.equal(response.body.fetchedAt, NOW);
+    assert.equal(response.headers['Cache-Control'], 'no-store');
+    assert.equal(
+      calls[0].origin + calls[0].pathname,
+      'https://api.inaturalist.org/v1/grid/2/1/1.grid.json',
+    );
+    assert.deepEqual(Object.fromEntries(calls[0].searchParams), {
+      verifiable: 'true',
+      captive: 'false',
+      d1: '2026-11-02',
+      photos: 'true',
+      quality_grade: 'research',
+      iconic_taxa: 'Aves',
+    });
+    await request(gridUrl);
+    assert.equal(calls.length, 1, 'fresh stable tile/filter key is cached');
+    assert.ok(!JSON.stringify([...cache]).includes('private_location'));
+    assert.ok(!JSON.stringify([...cache]).includes('900000000'));
+    const whale = await request('/grid?z=2&x=1&y=1&taxa=whales&confirmed=true');
+    assert.equal(whale.status, 200);
+    assert.equal(calls[1].searchParams.get('taxon_id'), '152871');
+    assert.equal(calls[1].searchParams.get('d1'), '2026-10-28');
+    assert.equal(calls[1].searchParams.has('photos'), false);
+  });
+}
+
+test('grid admission rejects cross-site/method/path/tile before acquisition', async () => {
+  const request = install({
+    fetchImpl() {
+      assert.fail('invalid grid request acquired');
+    },
+  });
+  assert.equal(
+    (
+      await request(gridUrl, {
+        headers: {
+          host: 'localhost:5173',
+          origin: 'https://other.test',
+          'sec-fetch-site': 'cross-site',
+        },
+      })
+    ).status,
+    403,
+  );
+  assert.equal((await request('/grid', { method: 'POST' })).status, 405);
+  assert.equal((await request('/grid/extra')).status, 404);
+  for (const query of [
+    '',
+    'z=2&x=4&y=0',
+    'z=-1&x=0&y=0',
+    'z=23&x=0&y=0',
+    'z=2&x=1.5&y=0',
+    'z=2&x=&y=0',
+    'z=2&x=0&y=4',
+  ]) {
+    const result = await request(`/grid?${query}`);
+    assert.equal(result.status, 400, query);
+    assert.equal(result.body.error, 'invalid_tile');
+  }
+});
+
+test('grid refresh single-flight, stale fallback and hour-key expiry keep the original age', async () => {
+  let time = NOW;
+  let calls = 0;
+  let resolve;
+  let mode = 'pending';
+  const request = install({
+    now: () => time,
+    fetchImpl: async () => {
+      calls += 1;
+      if (mode === 'pending')
+        return new Promise((done) => {
+          resolve = done;
+        });
+      if (mode === 'bad') return Response.json({ grid: [] });
+      return Response.json(syntheticGrid());
+    },
+  });
+  const first = request();
+  const second = request();
+  for (let i = 0; i < 100 && !resolve; i += 1) await new Promise(setImmediate);
+  assert.equal(calls, 1);
+  resolve(Response.json(syntheticGrid()));
+  assert.equal((await first).status, 200);
+  assert.equal((await second).status, 200);
+  time += 900_001;
+  mode = 'bad';
+  const stale = await request();
+  assert.equal(stale.status, 200);
+  assert.equal(stale.body.stale, true);
+  assert.equal(stale.body.fetchedAt, NOW);
+  assert.equal(stale.headers['X-Data-Stale'], 'true');
+  time = NOW + 3_600_001;
+  const expired = await request();
+  assert.equal(expired.status, 502);
+  assert.equal(expired.body.error, 'inaturalist_unavailable');
+});
+
+test('grid and observations share the upstream cooldown and daily reservations', async () => {
+  let calls = 0;
+  const client = createInatClient({
+    now: () => NOW,
+    cacheDir: null,
+    queueOptions: { intervalMs: 0 },
+    warn() {},
+    fetchImpl: async () => {
+      calls += 1;
+      return new Response('', {
+        status: 429,
+        headers: { 'Retry-After': '120' },
+      });
+    },
+  });
+  await assert.rejects(
+    client.getGrid({ ...tile, taxa: 'all', observedD1: '2026-11-02' }),
+    (error) => error.status === 429 && error.retryAfterS === 120,
+  );
+  await assert.rejects(
+    client.getObservations({
+      scope: 'global',
+      taxa: 'all',
+      observedD1: '2026-11-02',
+    }),
+    (error) => error.status === 429,
+  );
+  assert.equal(calls, 1);
+  assert.equal(client.budgetState().count, 1);
+});
+
+test('grid body cap and upstream failures return fixed errors; only real 5xx cools down', async () => {
+  for (const [response, retryAfter] of [
+    [() => new Response('x'.repeat(8 * 1024 * 1024 + 1)), undefined],
+    [() => new Response('', { status: 503 }), '15'],
+  ]) {
+    const request = install({ fetchImpl: async () => response() });
+    const result = await request();
+    assert.equal(result.status, 502);
+    assert.deepEqual(result.body, { error: 'inaturalist_unavailable' });
+    assert.equal(result.headers['Retry-After'], retryAfter);
+  }
+});
+
+test('a failed tile preserves last good cells and cannot send unrelated observations into 502', async () => {
+  let at = NOW;
+  let failGrid = false;
+  const calls = [];
+  const warnings = [];
+  const request = install({
+    now: () => at,
+    warn: (message) => warnings.push(message),
+    fetchImpl: async (url) => {
+      const isGrid = new URL(url).pathname.includes('/grid/');
+      calls.push(isGrid ? 'grid' : 'observations');
+      if (isGrid && failGrid)
+        return new Response('private upstream text', {
+          status: 503,
+          headers: { 'Retry-After': '45' },
+        });
+      return Response.json(
+        isGrid ? syntheticGrid() : { results: [], total_results: 0 },
+      );
+    },
+  });
+  const first = await request();
+  at += 900_001;
+  failGrid = true;
+  const failed = await request();
+  assert.equal(failed.status, 200);
+  assert.equal(failed.headers['X-Data-Stale'], 'true');
+  assert.equal(failed.body.stale, true);
+  assert.equal(failed.body.fetchedAt, first.body.fetchedAt);
+  assert.deepEqual(failed.body.cells, first.body.cells);
+  assert.equal(
+    (await request('/observations?scope=global&taxa=whales')).status,
+    200,
+  );
+  assert.deepEqual(calls, ['grid', 'grid', 'observations']);
+  assert.match(warnings[0], /resource=grid status=503 reason=http/);
+  assert.doesNotMatch(warnings[0], /private upstream text/);
+  // The tile cooldown also preserves its data without another upstream try.
+  const cooling = await request();
+  assert.equal(cooling.body.stale, true);
+  assert.equal(cooling.headers['Retry-After'], '45');
+  assert.equal(cooling.headers['X-Upstream-Status'], '503');
+  assert.equal(calls.length, 3);
+  at += 45_000;
+  failGrid = false;
+  const refreshing = await request();
+  assert.equal(refreshing.body.stale, true);
+  await new Promise(setImmediate);
+  const recovered = await request();
+  assert.equal(recovered.status, 200);
+  assert.equal(recovered.body.stale, undefined);
+  assert.equal(
+    calls.length,
+    4,
+    'a failed queue task does not poison later tile work',
+  );
+});
+
+test('twelve queued tiles leave observation capacity and give the next dispatch to observations', async () => {
+  const calls = [];
+  let release;
+  const request = install({
+    fetchImpl: (url) => {
+      const path = new URL(url).pathname;
+      calls.push(path);
+      if (calls.length === 1)
+        return new Promise((resolve) => {
+          release = resolve;
+        });
+      return Response.json(
+        path.includes('/grid/')
+          ? syntheticGrid()
+          : { results: [], total_results: 0 },
+      );
+    },
+  });
+  const first = request('/grid?z=4&x=0&y=1');
+  for (let i = 0; i < 100 && !release; i += 1) await new Promise(setImmediate);
+  assert.ok(release);
+  const tiles = Array.from({ length: 11 }, (_, i) =>
+    request(`/grid?z=4&x=${i + 1}&y=1`),
+  );
+  const observation = request('/observations?scope=global');
+  const queuedTile = request('/grid?z=4&x=12&y=1');
+  release(Response.json(syntheticGrid()));
+  const results = await Promise.all([first, observation, ...tiles, queuedTile]);
+  assert.ok(results.every((result) => result.status === 200));
+  assert.equal(calls.length, 14);
+  assert.equal(calls[1], '/v2/observations');
+});

server/providers/inaturalist/observations.js

@@ -0,0 +1,343 @@
+import { createInatClient } from './client.js';
+import { coalesceProxyRequest } from '../common/http.js';
+import { admitSameSiteKeyless } from '../common/same-site.js';
+import { requiredFiniteQueryNumber } from '../common/query.js';
+import { snapWildlifeBox } from '../../../src/layers/wildlifeSightings/bounds.js';
+import { validInatGridTile } from './grid.js';
+
+// The upstream advertises five-minute freshness; global samples cost less often.
+const TTL_MS = 300_000;
+const GLOBAL_TTL_MS = 600_000;
+const INAT_GRID_CACHE_TTL_MS = 15 * 60_000;
+const STALE_MAX_MS = 3_600_000;
+const INAT_CACHE_MAX = 400;
+const HOUR_MS = 3_600_000;
+const TAXA = Object.freeze([
+  'all',
+  'Aves',
+  'Mammalia',
+  'Insecta',
+  'Plantae',
+  'whales',
+]);
+
+function requestParams(pathname, query, nowMs) {
+  const grid = pathname === '/grid';
+  const scope = grid ? 'grid' : (query.get('scope') ?? 'view');
+  if (!grid && scope !== 'view' && scope !== 'global')
+    return { error: 'invalid_scope' };
+  const quality =
+    query.get('quality') === 'research' ||
+    (grid && query.get('confirmed') === 'true')
+      ? 'research'
+      : 'all';
+  const taxa = TAXA.includes(query.get('taxa')) ? query.get('taxa') : 'all';
+  let box = null;
+  let tile;
+  if (grid) {
+    tile = Object.fromEntries(
+      ['z', 'x', 'y'].map((name) => [
+        name,
+        requiredFiniteQueryNumber(query, name),
+      ]),
+    );
+    if (!validInatGridTile(tile)) return { error: 'invalid_tile' };
+  } else if (scope === 'view') {
+    const south = requiredFiniteQueryNumber(query, 'south');
+    const west = requiredFiniteQueryNumber(query, 'west');
+    const north = requiredFiniteQueryNumber(query, 'north');
+    const east = requiredFiniteQueryNumber(query, 'east');
+    box = snapWildlifeBox({ south, west, north, east });
+    if (!box) return { error: 'invalid_bbox' };
+  }
+  const windowMs = (taxa === 'whales' ? 7 * 24 : 48) * HOUR_MS;
+  const windowKey = new Date(Math.floor((nowMs - windowMs) / HOUR_MS) * HOUR_MS)
+    .toISOString()
+    .replace('.000Z', 'Z');
+  const bounds = box ? `${box.south},${box.west},${box.north},${box.east}` : '';
+  const baseKey = grid
+    ? `grid:v1:${tile.z}/${tile.x}/${tile.y}:${quality}:${taxa}`
+    : `v1:${scope}:${bounds}:${quality}:${taxa}`;
+  return {
+    scope,
+    ...(grid
+      ? { ...tile, waitForFresh: query.get('refresh') === 'wait' }
+      : { box }),
+    quality,
+    taxa,
+    observedD1: windowKey.slice(0, 10),
+    baseKey,
+    key: `${baseKey}:${windowKey}`,
+  };
+}
+
+/** A shared-provider route for dev and preview; acquisition starts on demand. */
+export function inaturalistProxy({
+  fetchImpl = (...args) => globalThis.fetch(...args),
+  now = () => Date.now(),
+  cacheDir,
+  cache = new Map(),
+  warn = (...args) => console.warn(...args),
+  queueOptions,
+} = {}) {
+  const inFlight = new Map();
+  const consumers = new Map();
+  let client = null;
+
+  function age(entry) {
+    if (!entry) return Infinity;
+    const elapsed = now() - entry.savedAt;
+    return elapsed < 0 ? Infinity : elapsed;
+  }
+
+  function joinFlight(promise, group, signal) {
+    group.count += 1;
+    return new Promise((resolve, reject) => {
+      let released = false;
+      function release() {
+        if (released) return;
+        released = true;
+        signal?.removeEventListener('abort', abort);
+        group.count -= 1;
+        if (!group.count && !group.background && !group.settled) {
+          group.controller.abort();
+          // A fresh consumer must not join an abandoned queued generation.
+          if (inFlight.get(group.key) === promise) inFlight.delete(group.key);
+          if (consumers.get(group.key) === group) consumers.delete(group.key);
+        }
+      }
+      function abort() {
+        release();
+        reject(signal.reason);
+      }
+      signal?.addEventListener('abort', abort, { once: true });
+      if (signal?.aborted) abort();
+      promise.then(
+        (value) => {
+          release();
+          resolve(value);
+        },
+        (error) => {
+          release();
+          reject(error);
+        },
+      );
+    });
+  }
+
+  function refresh(params, background = false) {
+    // Global samples share pending refreshes across hourly window changes.
+    const flightKey = params.scope === 'global' ? params.baseKey : params.key;
+    let group = consumers.get(flightKey);
+    if (!group) {
+      group = {
+        key: flightKey,
+        controller: new AbortController(),
+        count: 0,
+        settled: false,
+        background,
+      };
+      consumers.set(flightKey, group);
+    }
+    group.background ||= background;
+    const { promise, shared } = coalesceProxyRequest(
+      inFlight,
+      flightKey,
+      async () => {
+        client ??= createInatClient({
+          fetchImpl,
+          now,
+          cacheDir,
+          warn,
+          queueOptions,
+        });
+        const options = { signal: group.controller.signal };
+        const result = await (params.scope === 'grid'
+          ? client.getGrid(params, options)
+          : client.getObservations(params, options));
+        const value = {
+          fetchedAt: now(),
+          ...(params.scope === 'grid'
+            ? {}
+            : { scope: params.scope, box: params.box }),
+          ...result,
+        };
+        cache.delete(params.key);
+        cache.set(params.key, {
+          value,
+          savedAt: now(),
+          baseKey: params.baseKey,
+        });
+        while (cache.size > INAT_CACHE_MAX)
+          cache.delete(cache.keys().next().value);
+        return value;
+      },
+    );
+    if (!shared) {
+      const settle = () => {
+        group.settled = true;
+        if (consumers.get(flightKey) === group) consumers.delete(flightKey);
+      };
+      void promise.then(settle, settle);
+    }
+    return { promise, group };
+  }
+
+  async function acquire(params, signal) {
+    signal?.throwIfAborted();
+    for (const [key, entry] of cache) {
+      if (age(entry) > STALE_MAX_MS) cache.delete(key);
+    }
+    const current = cache.get(params.key);
+    const ttl =
+      params.scope === 'grid'
+        ? INAT_GRID_CACHE_TTL_MS
+        : params.scope === 'global'
+          ? GLOBAL_TTL_MS
+          : TTL_MS;
+    if (current && age(current) < ttl) {
+      cache.delete(params.key);
+      cache.set(params.key, current);
+      return { value: current.value, stale: false };
+    }
+    // Window-hour rollover can reuse prior cells without claiming a new age.
+    let previous = current;
+    let previousKey = params.key;
+    if (!previous) {
+      for (const [key, entry] of cache) {
+        if (
+          entry.baseKey === params.baseKey &&
+          (!previous || entry.savedAt > previous.savedAt)
+        ) {
+          previous = entry;
+          previousKey = key;
+        }
+      }
+    }
+    if (params.scope === 'global' && age(previous) < GLOBAL_TTL_MS)
+      return { value: previous.value, stale: false };
+    if (
+      params.scope === 'grid' &&
+      !params.waitForFresh &&
+      age(previous) <= STALE_MAX_MS
+    ) {
+      cache.delete(previousKey);
+      cache.set(previousKey, previous);
+      // Retain one background consumer after this HTTP response closes. A stale
+      // tile is useful immediately; waiting for the token queue defeats SWR.
+      const cooling = client?.cooldownState('grid');
+      if (!cooling) {
+        const { promise } = refresh(params, true);
+        void promise.catch(() => {});
+      }
+      return {
+        value: previous.value,
+        stale: true,
+        ...cooling,
+      };
+    }
+    try {
+      const { promise, group } = refresh(params);
+      return { value: await joinFlight(promise, group, signal), stale: false };
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      if (age(previous) <= STALE_MAX_MS)
+        return {
+          value: previous.value,
+          stale: true,
+          retryAfterS: error.retryAfterS,
+          upstreamStatus: error.upstreamStatus,
+        };
+      throw error;
+    }
+  }
+
+  async function handler(req, res) {
+    const json = (
+      status,
+      value,
+      { stale = false, retryAfterS, upstreamStatus } = {},
+    ) => {
+      if (res.destroyed) return;
+      res.writeHead(status, {
+        'Content-Type': 'application/json',
+        'Cache-Control': 'no-store',
+        ...(status === 405 ? { Allow: 'GET' } : {}),
+        ...(Number.isFinite(retryAfterS)
+          ? { 'Retry-After': String(retryAfterS) }
+          : {}),
+        ...(upstreamStatus
+          ? { 'X-Upstream-Status': String(upstreamStatus) }
+          : {}),
+        ...(stale ? { 'X-Data-Stale': 'true' } : {}),
+      });
+      res.end(JSON.stringify(value));
+    };
+    if (admitSameSiteKeyless(req, res)) return;
+    if (req.method !== 'GET') return json(405, { error: 'method_not_allowed' });
+    const url = String(req.url || '/');
+    const queryAt = url.indexOf('?');
+    const pathname = queryAt < 0 ? url : url.slice(0, queryAt);
+    if (pathname !== '/observations' && pathname !== '/grid')
+      return json(404, { error: 'unknown_route' });
+    const params = requestParams(
+      pathname,
+      new URLSearchParams(queryAt < 0 ? '' : url.slice(queryAt + 1)),
+      now(),
+    );
+    if (params.error) return json(400, { error: params.error });
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    // IncomingMessage.close also fires after a complete request body. The
+    // response close identifies the abandoned browser fetch, while aborted
+    // covers a request cut short before it reached the response stage.
+    req.once?.('aborted', abort);
+    res.once?.('close', abort);
+    try {
+      const { value, stale, retryAfterS, upstreamStatus } = await acquire(
+        params,
+        controller.signal,
+      );
+      return json(200, stale ? { ...value, stale: true } : value, {
+        stale,
+        retryAfterS,
+        upstreamStatus,
+      });
+    } catch (error) {
+      if (controller.signal.aborted) return;
+      const status =
+        error.code === 'inaturalist_budget_exhausted'
+          ? 503
+          : error.status === 429
+            ? 429
+            : 502;
+      const code =
+        error.code === 'inaturalist_budget_exhausted'
+          ? error.code
+          : status === 429
+            ? 'inaturalist_rate_limited'
+            : 'inaturalist_unavailable';
+      return json(
+        status,
+        { error: code },
+        {
+          retryAfterS: error.retryAfterS,
+          upstreamStatus: error.upstreamStatus,
+        },
+      );
+    } finally {
+      req.removeListener?.('aborted', abort);
+      res.removeListener?.('close', abort);
+    }
+  }
+
+  return {
+    name: 'inaturalist',
+    configureServer({ middlewares }) {
+      middlewares.use('/api/inaturalist', handler);
+    },
+    configurePreviewServer({ middlewares }) {
+      middlewares.use('/api/inaturalist', handler);
+    },
+  };
+}

server/providers/inaturalist/observations.test.mjs

@@ -0,0 +1,893 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, readdir, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { installInatProxy, NOW } from './proxy.fixture.mjs';
+import { createInatClient, inatRetryCooldownMs } from './client.js';
+
+const observation = (id = 1) => ({
+  id,
+  uri: `https://www.inaturalist.org/observations/${id}`,
+  geojson: { coordinates: [-122.351, 47.613] },
+  time_observed_at: '2026-11-04T17:00:00Z',
+  observed_on: '2026-11-04',
+  created_at: '2026-11-04T17:01:00Z',
+  quality_grade: 'research',
+  license_code: 'cc-by',
+  positional_accuracy: 12,
+  faves_count: 2,
+  num_identification_agreements: 3,
+  taxon: {
+    name: 'Calypte anna',
+    preferred_common_name: "Anna's hummingbird",
+    iconic_taxon_name: 'Aves',
+  },
+  photos: [
+    {
+      url: 'https://inaturalist-open-data.s3.amazonaws.com/photos/123/square.jpeg',
+      license_code: 'cc-by',
+      attribution: 'Synthetic photographer, CC BY',
+    },
+  ],
+  user: { login: 'must-never-leave-server' },
+});
+const envelope = (rows = [observation()], total = rows.length) => ({
+  total_results: total,
+  page: 1,
+  per_page: 200,
+  results: rows,
+});
+const boxUrl = (index = 0, extra = '') =>
+  `/observations?south=47.51&west=${-122.49 + index * 0.2}&north=47.69&east=${-122.31 + index * 0.2}${extra}`;
+
+function install(options = {}, hook = 'configureServer') {
+  return installInatProxy(
+    boxUrl(),
+    {
+      // Serial dispatch makes queued cancellation and coalescing observable.
+      queueOptions: { intervalMs: 0, windowMs: 0, maxInFlight: 1 },
+      ...options,
+    },
+    hook,
+  );
+}
+
+async function until(check) {
+  for (let i = 0; i < 100; i += 1) {
+    if (check()) return;
+    await new Promise(setImmediate);
+  }
+  assert.fail('expected fake upstream calls were not dispatched');
+}
+
+for (const hook of ['configureServer', 'configurePreviewServer']) {
+  test(`${hook}: actual v2 envelope, fixed query, projection and privacy`, async () => {
+    const calls = [];
+    const cache = new Map();
+    const request = install(
+      {
+        cache,
+        fetchImpl: async (url, options) => {
+          calls.push(new URL(url));
+          assert.equal(options.redirect, 'error');
+          assert.ok(options.signal instanceof AbortSignal);
+          assert.equal(options.headers.Accept, 'application/json');
+          assert.equal(
+            options.headers['User-Agent'],
+            'gods-eye-view-wildlife-sightings-proxy/1.0 (+https://github.com/bilawalsidhu/gods-eye-view)',
+          );
+          return Response.json(envelope());
+        },
+      },
+      hook,
+    );
+    assert.equal(calls.length, 0, 'construction and mounting do not acquire');
+    const result = await request(
+      boxUrl(0, '&url=https://attacker.example&per_page=999'),
+    );
+    assert.equal(result.status, 200);
+    assert.equal(result.headers['Cache-Control'], 'no-store');
+    assert.equal(result.body.rows[0].stableId, 'inat:1');
+    assert.equal(result.body.fetchedAt, NOW);
+    assert.equal(result.body.scope, 'view');
+    assert.deepEqual(result.body.box, {
+      south: 47.5,
+      west: -122.5,
+      north: 47.7,
+      east: -122.3,
+    });
+    const query = calls[0].searchParams;
+    assert.equal(
+      calls[0].origin + calls[0].pathname,
+      'https://api.inaturalist.org/v2/observations',
+    );
+    // Only the projected fields are requested, never user or identification data.
+    assert.match(query.get('fields'), /^\(id:!t,uri:!t,.*photos:\(url:!t/);
+    assert.doesNotMatch(query.get('fields'), /user|identifications/);
+    assert.equal(query.get('swlat'), '47.5');
+    assert.equal(query.get('swlng'), '-122.5');
+    assert.equal(query.get('nelat'), '47.7');
+    assert.equal(query.get('nelng'), '-122.3');
+    assert.equal(query.get('d1'), '2026-11-02');
+    assert.equal(query.has('created_d1'), false);
+    assert.equal(query.get('per_page'), '200');
+    assert.equal(query.get('verifiable'), 'true');
+    assert.equal(query.get('photos'), 'true');
+    assert.equal(query.get('captive'), 'false');
+    assert.equal(query.get('order_by'), 'random');
+    assert.equal(query.has('order'), false);
+    assert.doesNotMatch(
+      JSON.stringify(result.body),
+      /must-never-leave-server|"user"/,
+    );
+    assert.doesNotMatch(
+      JSON.stringify([...cache.values()]),
+      /must-never-leave-server|"user"/,
+    );
+  });
+}
+
+test('gate, method, route and query validation run before quota, cache or upstream', async () => {
+  const cache = new Map();
+  let calls = 0;
+  const request = install({
+    cache,
+    fetchImpl: async () => {
+      calls += 1;
+      return Response.json(envelope());
+    },
+  });
+  for (let i = 0; i < 32; i += 1) {
+    const response = await request('/observations?scope=global', {
+      headers: {
+        host: 'localhost:5173',
+        origin: 'https://foreign.example',
+        'sec-fetch-site': 'cross-site',
+      },
+    });
+    assert.equal(response.status, 403);
+  }
+  const method = await request('/observations', { method: 'POST' });
+  assert.equal(method.status, 405);
+  assert.equal(method.headers.Allow, 'GET');
+  for (const route of ['/', '/unknown', '/observations/extra', '//[invalid'])
+    assert.equal((await request(route)).body.error, 'unknown_route');
+  assert.equal(
+    (await request('/observations?scope=planet')).body.error,
+    'invalid_scope',
+  );
+  for (const query of [
+    '',
+    'south=NaN&west=0&north=1&east=1',
+    'south=&west=0&north=1&east=1',
+    'south=0&west=0&north=0&east=1',
+    'south=0&west=1&north=1&east=0',
+    'south=-91&west=0&north=1&east=1',
+    'south=0&west=-181&north=1&east=1',
+    'south=0&west=0&north=41&east=1',
+    'south=0&west=0&north=1&east=41',
+  ]) {
+    const result = await request(`/observations?${query}`);
+    assert.equal(result.status, 400, query);
+    assert.equal(result.body.error, 'invalid_bbox', query);
+  }
+  assert.equal(cache.size, 0);
+  assert.equal(calls, 0);
+  const allowed = await request('/observations?scope=global', {
+    headers: {
+      host: 'gev.example',
+      origin: 'https://gev.example',
+      'sec-fetch-site': 'same-origin',
+      'x-forwarded-proto': 'https',
+      'x-forwarded-for': '203.0.113.9',
+    },
+  });
+  assert.equal(allowed.status, 200);
+});
+
+test('cached requests never exhaust a local request admission limiter', async () => {
+  let calls = 0;
+  const request = install({
+    fetchImpl: async () => {
+      calls += 1;
+      return Response.json(envelope());
+    },
+  });
+  for (let i = 0; i < 30; i += 1) assert.equal((await request()).status, 200);
+  const cached = await request();
+  assert.equal(cached.status, 200);
+  assert.equal(cached.headers['Retry-After'], undefined);
+  assert.equal(calls, 1);
+});
+
+test('proxy rejects oversized snapped spans before acquisition and preserves canonical client boxes', async () => {
+  const urls = [];
+  const request = install({
+    fetchImpl: async (url) => {
+      urls.push(new URL(url));
+      return Response.json(envelope());
+    },
+  });
+  for (const query of [
+    'south=10.2&west=0&north=50.1&east=1',
+    'south=0&west=10.2&north=1&east=50.1',
+  ]) {
+    const result = await request(`/observations?${query}`);
+    assert.equal(result.status, 400);
+    assert.equal(result.body.error, 'invalid_bbox');
+  }
+  assert.equal(urls.length, 0);
+  const canonical =
+    '/observations?south=47.4&west=-122.3&north=47.6&east=-122.1';
+  const first = await request(canonical);
+  assert.equal(first.status, 200);
+  assert.deepEqual(first.body.box, {
+    south: 47.4,
+    west: -122.3,
+    north: 47.6,
+    east: -122.1,
+  });
+  assert.equal(urls[0].searchParams.get('swlat'), '47.4');
+  assert.equal(urls[0].searchParams.get('swlng'), '-122.3');
+  const second = await request(canonical);
+  assert.deepEqual(second.body, first.body);
+  assert.equal(urls.length, 1, 'canonical boxes share their cache key');
+});
+
+test('view snapping, whales, research and global queries obey the requested policy', async () => {
+  const urls = [];
+  const request = install({
+    fetchImpl: async (url) => {
+      urls.push(new URL(url));
+      return Response.json(envelope());
+    },
+  });
+  await request(
+    '/observations?south=40.2&west=-123.7&north=46.1&east=-121.4&quality=research&taxa=Aves',
+  );
+  assert.equal(urls[0].searchParams.get('swlat'), '40');
+  assert.equal(urls[0].searchParams.get('nelat'), '47');
+  assert.equal(urls[0].searchParams.get('per_page'), '200');
+  assert.equal(urls[0].searchParams.get('quality_grade'), 'research');
+  assert.equal(urls[0].searchParams.get('iconic_taxa'), 'Aves');
+  await request(boxUrl(0, '&taxa=whales'));
+  const whales = urls[1].searchParams;
+  assert.equal(whales.get('taxon_id'), '152871');
+  assert.equal(whales.get('d1'), '2026-10-28');
+  assert.equal(whales.has('created_d1'), false);
+  assert.equal(whales.has('photos'), false);
+  assert.equal(whales.has('iconic_taxa'), false);
+  await request('/observations?scope=global&quality=typo&taxa=typo&south=bad');
+  const global = urls[2].searchParams;
+  for (const field of [
+    'swlat',
+    'swlng',
+    'nelat',
+    'nelng',
+    'quality_grade',
+    'iconic_taxa',
+  ])
+    assert.equal(global.has(field), false, field);
+  assert.equal(global.get('per_page'), '200');
+  assert.equal(global.get('d1'), '2026-11-02');
+  assert.equal(global.has('created_d1'), false);
+  assert.equal(global.get('order_by'), 'observed_on');
+  assert.equal(global.get('order'), 'desc');
+  await request('/observations?scope=global&taxa=whales');
+  const globalWhales = urls[3].searchParams;
+  assert.equal(globalWhales.get('d1'), '2026-10-28');
+  assert.equal(globalWhales.has('created_d1'), false);
+  assert.equal(globalWhales.get('order_by'), 'observed_on');
+  assert.equal(globalWhales.get('order'), 'desc');
+});
+
+test('fresh cache hits and global ten-minute TTL spend no upstream quota', async () => {
+  let at = NOW;
+  let calls = 0;
+  const request = install({
+    now: () => at,
+    fetchImpl: async () => {
+      calls += 1;
+      return Response.json(envelope());
+    },
+  });
+  const first = await request();
+  at += 299_999;
+  assert.deepEqual((await request()).body, first.body);
+  at += 1;
+  await request();
+  assert.equal(calls, 2);
+  await request('/observations?scope=global');
+  at += 599_999;
+  await request('/observations?scope=global');
+  assert.equal(calls, 3);
+  at += 1;
+  await request('/observations?scope=global');
+  assert.equal(calls, 4);
+});
+
+test('the same snapped view and window hour returns one cached random sample until expiry', async () => {
+  let at = NOW;
+  let draws = 0;
+  const cache = new Map();
+  const request = install({
+    cache,
+    now: () => at,
+    fetchImpl: async (url) => {
+      const query = new URL(url).searchParams;
+      assert.equal(query.get('order_by'), 'random');
+      assert.equal(query.get('per_page'), '200');
+      return Response.json(envelope([observation(++draws)]));
+    },
+  });
+  const first = await request();
+  for (const elapsed of [1, 1000, 60_000, 299_999]) {
+    at = NOW + elapsed;
+    const next = await request();
+    assert.deepEqual(next.body, first.body);
+  }
+  assert.equal(draws, 1);
+  assert.match(cache.keys().next().value, /2026-11-02T18:00:00Z$/);
+  at = NOW + 300_000;
+  const refresh = await request();
+  assert.equal(refresh.body.rows[0].stableId, 'inat:2');
+  assert.equal(draws, 2);
+});
+
+test('disconnected queued views are dropped while a remaining coalesced consumer keeps its request', async () => {
+  const calls = [];
+  const releases = [];
+  const cache = new Map();
+  const request = install({
+    cache,
+    fetchImpl: (url, { signal }) => {
+      calls.push({ url: new URL(url), signal });
+      return new Promise((resolve) => releases.push(resolve));
+    },
+  });
+  const first = request(boxUrl(0));
+  await until(() => releases.length === 1);
+  const superseded = new AbortController();
+  const oldView = request(boxUrl(1), { signal: superseded.signal });
+  const oneConsumer = new AbortController();
+  const one = request(boxUrl(2), { signal: oneConsumer.signal });
+  const other = request(boxUrl(2));
+  superseded.abort();
+  oneConsumer.abort();
+  await Promise.all([oldView, one]);
+  // Rejoining the abandoned key creates a healthy generation; the old
+  // coalescing promise must not later delete or cancel this replacement.
+  const replacement = request(boxUrl(1));
+  releases[0](Response.json(envelope()));
+  await until(() => releases.length === 2);
+  assert.equal(calls[1].url.searchParams.get('swlng'), '-122.1');
+  assert.equal(calls[1].signal.aborted, false);
+  releases[1](Response.json(envelope([observation(2)])));
+  await until(() => releases.length === 3);
+  assert.equal(calls[2].url.searchParams.get('swlng'), '-122.3');
+  releases[2](Response.json(envelope([observation(3)])));
+  const results = await Promise.all([first, other, replacement]);
+  assert.ok(results.every((result) => result.status === 200));
+  assert.equal(
+    calls.length,
+    3,
+    'the abandoned queued generation never dispatched',
+  );
+  assert.equal(cache.size, 3);
+  assert.equal(results[1].body.rows[0].stableId, 'inat:2');
+  assert.equal(results[2].body.rows[0].stableId, 'inat:3');
+});
+
+test('observation windows reject old sightings uploaded today and keep recent observations', async () => {
+  for (const [taxa, recentTime, expectedD1] of [
+    ['all', '2026-11-04T17:00:00Z', '2026-11-02'],
+    ['whales', '2026-10-30T17:00:00Z', '2026-10-28'],
+  ]) {
+    let upstreamQuery;
+    const request = install({
+      fetchImpl: async (url) => {
+        upstreamQuery = new URL(url).searchParams;
+        return Response.json(
+          envelope([
+            {
+              ...observation(80),
+              time_observed_at: '2010-06-01T12:00:00Z',
+              observed_on: '2010-06-01',
+            },
+            {
+              ...observation(81),
+              time_observed_at: recentTime,
+              observed_on: recentTime.slice(0, 10),
+            },
+          ]),
+        );
+      },
+    });
+    const result = await request(boxUrl(0, `&taxa=${taxa}`));
+    assert.equal(result.status, 200, taxa);
+    assert.equal(upstreamQuery.get('d1'), expectedD1);
+    assert.equal(upstreamQuery.has('created_d1'), false);
+    assert.equal(upstreamQuery.get('order_by'), 'random');
+    assert.deepEqual(
+      result.body.rows.map((row) => row.stableId),
+      ['inat:81'],
+    );
+  }
+});
+
+test('same-key requests single-flight and a seventeenth distinct in-flight key queues', async () => {
+  const releases = [];
+  const request = install({
+    fetchImpl: () => new Promise((resolve) => releases.push(resolve)),
+  });
+  const a = request();
+  const b = request();
+  await until(() => releases.length === 1);
+  releases.shift()(Response.json(envelope()));
+  assert.deepEqual((await a).body, (await b).body);
+  const pending = Array.from({ length: 16 }, (_, i) => request(boxUrl(i + 1)));
+  await until(() => releases.length === 1);
+  pending.push(request(boxUrl(18)));
+  for (let i = 0; i < 17; i += 1) {
+    await until(() => releases.length > i);
+    releases[i](Response.json(envelope()));
+  }
+  assert.ok((await Promise.all(pending)).every(({ status }) => status === 200));
+});
+
+test('a fresh global sample survives the hourly observation-window rollover without another fetch', async () => {
+  let at = Date.parse('2026-11-04T18:59:00Z');
+  let calls = 0;
+  const request = install({
+    now: () => at,
+    fetchImpl: async () => {
+      calls += 1;
+      return Response.json(envelope());
+    },
+  });
+  const first = await request('/observations?scope=global');
+  at += 60_000;
+  const nextHour = await request('/observations?scope=global');
+  assert.deepEqual(nextHour.body, first.body);
+  assert.equal(nextHour.body.stale, undefined);
+  assert.equal(calls, 1);
+  at += 9 * 60_000;
+  await request('/observations?scope=global');
+  assert.equal(calls, 2);
+});
+
+test('pending global refresh coalesces across the hourly observation-window rollover with a busy queue', async () => {
+  let at = Date.parse('2026-11-04T18:59:59Z');
+  const releases = [];
+  const cache = new Map();
+  const request = install({
+    cache,
+    now: () => at,
+    fetchImpl: (url) =>
+      new Promise((resolve) =>
+        releases.push({
+          resolve,
+          url: new URL(url),
+        }),
+      ),
+  });
+  const first = request(
+    '/observations?scope=global&quality=research&taxa=Aves',
+  );
+  const views = Array.from({ length: 15 }, (_, i) => request(boxUrl(i)));
+  await until(() => releases.length === 1);
+  assert.equal(releases[0].url.searchParams.get('d1'), '2026-11-02');
+  at = Date.parse('2026-11-04T19:00:01Z');
+  const nextHour = request(
+    '/observations?scope=global&quality=research&taxa=Aves',
+  );
+  await new Promise(setImmediate);
+  assert.equal(
+    releases.length,
+    1,
+    'the same global query joins the pending refresh',
+  );
+  const distinct = request(
+    '/observations?scope=global&quality=research&taxa=Mammalia',
+  );
+  for (let i = 0; i < 17; i += 1) {
+    await until(() => releases.length > i);
+    releases[i].resolve(Response.json(envelope()));
+  }
+  const [original, joined] = await Promise.all([first, nextHour]);
+  assert.equal(original.status, 200);
+  assert.equal((await distinct).status, 200);
+  assert.deepEqual(joined.body, original.body);
+  assert.ok((await Promise.all(views)).every(({ status }) => status === 200));
+  const globalEntries = [...cache.entries()].filter(
+    ([, entry]) => entry.value.scope === 'global',
+  );
+  assert.equal(globalEntries.length, 2);
+  assert.match(globalEntries[0][0], /2026-11-02T18:00:00Z$/);
+  assert.equal(
+    (await request('/observations?scope=global&quality=research&taxa=Aves'))
+      .status,
+    200,
+  );
+  assert.equal(
+    releases.length,
+    17,
+    'the accepted global answer keeps its ten-minute freshness',
+  );
+});
+
+test('view refreshes retain distinct hourly keys while a previous-hour request is pending', async () => {
+  let at = Date.parse('2026-11-04T18:59:59Z');
+  const releases = [];
+  const request = install({
+    now: () => at,
+    fetchImpl: () => new Promise((resolve) => releases.push(resolve)),
+  });
+  const first = request();
+  await until(() => releases.length === 1);
+  at = Date.parse('2026-11-04T19:00:01Z');
+  const nextHour = request();
+  await new Promise(setImmediate);
+  assert.equal(
+    releases.length,
+    1,
+    'the next view queues behind the current call',
+  );
+  releases[0](Response.json(envelope()));
+  await until(() => releases.length === 2);
+  releases[1](Response.json(envelope()));
+  assert.ok(
+    (await Promise.all([first, nextHour])).every(
+      ({ status }) => status === 200,
+    ),
+  );
+});
+
+test('upstream minute ceiling waits for request 61 across client addresses', async () => {
+  let at = NOW;
+  let calls = 0;
+  const request = install({
+    now: () => at,
+    queueOptions: {
+      now: () => at,
+      intervalMs: 0,
+      wait: async (ms) => {
+        at += ms;
+      },
+    },
+    fetchImpl: async () => {
+      calls += 1;
+      return Response.json(envelope());
+    },
+  });
+  for (let i = 0; i < 60; i += 1)
+    assert.equal(
+      (await request(boxUrl(i), { peer: `10.0.0.${i}` })).status,
+      200,
+    );
+  const queued = await request(boxUrl(60), { peer: '10.0.1.1' });
+  assert.equal(queued.status, 200);
+  assert.equal(queued.headers['Retry-After'], undefined);
+  assert.equal(at, NOW + 60_000);
+  assert.equal(calls, 61);
+});
+
+test('views refresh after many prior requests without fabricating an upstream limit', async () => {
+  let at = NOW;
+  let calls = 0;
+  const request = install({
+    now: () => at,
+    fetchImpl: async () => {
+      calls += 1;
+      return Response.json(envelope());
+    },
+  });
+  const first = await request();
+  at += 300_001;
+  for (let i = 1; i <= 60; i += 1)
+    await request(boxUrl(i), { peer: `10.0.0.${i}` });
+  const stale = await request();
+  assert.equal(stale.status, 200);
+  assert.equal(stale.body.stale, undefined);
+  assert.notEqual(stale.body.fetchedAt, first.body.fetchedAt);
+  assert.equal(calls, 62);
+});
+
+test('bounded samples preserve partial metadata, and well-formed empty views are valid', async () => {
+  let at = NOW;
+  let fail = false;
+  const request = install({
+    now: () => at,
+    fetchImpl: async () =>
+      fail
+        ? new Response('unavailable', { status: 503 })
+        : Response.json(envelope([observation()], 500)),
+  });
+  const first = await request();
+  assert.equal(first.body.partial, true);
+  assert.equal(first.body.rawRowCount, 500);
+  fail = true;
+  at += 59 * 60_000;
+  const stale = await request();
+  assert.equal(
+    stale.status,
+    200,
+    'hourly window changes still permit stale fallback',
+  );
+  assert.equal(stale.headers['X-Data-Stale'], 'true');
+  assert.equal(stale.body.stale, true);
+  assert.equal(stale.body.fetchedAt, first.body.fetchedAt);
+  assert.equal(stale.body.partial, true);
+  at += 2 * 60_000;
+  const expired = await request();
+  assert.equal(expired.status, 502);
+  assert.equal(expired.body.error, 'inaturalist_unavailable');
+  const empty = install({
+    fetchImpl: async () => Response.json(envelope([], 0)),
+  });
+  const result = await empty();
+  assert.equal(result.status, 200);
+  assert.deepEqual(result.body.rows, []);
+});
+
+test('bad envelopes, JSON and capped bodies fail closed without inventing a cooldown', async () => {
+  for (const bad of [
+    () => Response.json({ total_results: 1, results: {} }),
+    () => Response.json({ total_results: 1, observations: [observation()] }),
+    () => Response.json({ total_results: '1', results: [observation()] }),
+    () => Response.json(envelope([], 1)),
+    () => Response.json(envelope([{ ...observation(), id: null }], 1)),
+    () => new Response('{malformed'),
+    () =>
+      new Response('{}', {
+        headers: { 'Content-Length': String(8 * 1024 * 1024 + 1) },
+      }),
+  ]) {
+    let at = NOW;
+    let calls = 0;
+    const request = install({
+      now: () => at,
+      fetchImpl: async () => {
+        calls += 1;
+        return calls === 1 ? bad() : Response.json(envelope());
+      },
+    });
+    const first = await request();
+    assert.equal(first.status, 502);
+    assert.equal(first.body.error, 'inaturalist_unavailable');
+    assert.equal(first.headers['Retry-After'], undefined);
+    assert.equal((await request(boxUrl(1))).status, 200);
+    assert.equal(calls, 2);
+  }
+});
+
+test('a wholly invalid iNat page cannot replace a previously valid snapshot', async () => {
+  let at = NOW;
+  let fail = false;
+  const cache = new Map();
+  const request = install({
+    cache,
+    now: () => at,
+    fetchImpl: async () =>
+      Response.json(
+        fail
+          ? envelope([{ ...observation(), quality_grade: 'casual' }])
+          : envelope(),
+      ),
+  });
+  const first = await request();
+  const original = cache.values().next().value;
+  fail = true;
+  at += 300_001;
+  const stale = await request();
+  assert.equal(stale.status, 200);
+  assert.equal(stale.body.stale, true);
+  assert.equal(stale.body.fetchedAt, first.body.fetchedAt);
+  assert.equal(cache.values().next().value, original);
+});
+
+test('429 cooldown honors seconds, HTTP dates, and long upstream deadlines', async () => {
+  assert.equal(inatRetryCooldownMs(null, NOW), 60_000);
+  assert.equal(inatRetryCooldownMs('0', NOW), 0);
+  assert.equal(inatRetryCooldownMs('2', NOW), 2000);
+  assert.equal(inatRetryCooldownMs('999999', NOW), 999_999_000);
+  assert.equal(inatRetryCooldownMs('7200', NOW), 7_200_000);
+  assert.equal(
+    inatRetryCooldownMs(new Date(NOW + 7_200_000).toUTCString(), NOW),
+    7_200_000,
+  );
+  let at = NOW;
+  const releases = [];
+  const warnings = [];
+  const request = install({
+    now: () => at,
+    warn: (message) => warnings.push(message),
+    fetchImpl: () => new Promise((resolve) => releases.push(resolve)),
+  });
+  const first = request();
+  const later = request(boxUrl(1));
+  await until(() => releases.length === 1);
+  releases[0](
+    new Response('limit', {
+      status: 429,
+      headers: { 'Retry-After': '999999' },
+    }),
+  );
+  assert.equal((await first).headers['Retry-After'], '999999');
+  assert.equal((await later).headers['Retry-After'], '999999');
+  at += 1000;
+  assert.equal((await request(boxUrl(1))).headers['Retry-After'], '999998');
+  at += 5000;
+  const cooling = await request(boxUrl(2));
+  assert.equal(cooling.status, 429);
+  assert.equal(cooling.headers['Retry-After'], '999993');
+  assert.equal(
+    releases.length,
+    1,
+    'queued calls do not dispatch during cooldown',
+  );
+  assert.equal(
+    warnings.filter((message) => message.includes('capped')).length,
+    0,
+  );
+});
+
+for (const [upstreamStatus, expectedStatus, code, retryAfterS] of [
+  [429, 429, 'inaturalist_rate_limited', 120],
+  [503, 502, 'inaturalist_unavailable', 120],
+]) {
+  test(`concurrent reservations honor an immediate upstream ${upstreamStatus} before dispatch`, async () => {
+    let calls = 0;
+    const warnings = [];
+    const client = createInatClient({
+      now: () => 0,
+      cacheDir: null,
+      queueOptions: { intervalMs: 0 },
+      warn: (message) => warnings.push(message),
+      fetchImpl: async () => {
+        calls += 1;
+        return new Response('synthetic failure', {
+          status: upstreamStatus,
+          headers: { 'Retry-After': '120' },
+        });
+      },
+    });
+    const params = {
+      scope: 'global',
+      quality: 'all',
+      taxa: 'all',
+      observedD1: '1969-12-30',
+    };
+    const results = await Promise.allSettled(
+      Array.from({ length: 3 }, () => client.getObservations(params)),
+    );
+    assert.equal(
+      calls,
+      1,
+      'pending reservations must not dispatch during cooldown',
+    );
+    for (const result of results) {
+      assert.equal(result.status, 'rejected');
+      assert.equal(result.reason.status, expectedStatus);
+      assert.equal(result.reason.code, code);
+      assert.equal(result.reason.retryAfterS, retryAfterS);
+    }
+    assert.equal(
+      warnings.length,
+      1,
+      'only the dispatched refresh logs a failure',
+    );
+    await assert.rejects(client.getObservations(params), {
+      status: expectedStatus,
+      code,
+      retryAfterS,
+    });
+    assert.equal(calls, 1);
+  });
+}
+
+test('budget is read lazily, persisted as counters only, enforced across restart and UTC rollover', async (t) => {
+  const parent = await mkdtemp(path.join(os.tmpdir(), 'gev-inat-budget-'));
+  t.after(() => rm(parent, { recursive: true, force: true }));
+  const cacheDir = path.join(parent, 'not-created');
+  const before = process.env.INATURALIST_DAILY_BUDGET;
+  process.env.INATURALIST_DAILY_BUDGET = '2';
+  t.after(() =>
+    before === undefined
+      ? delete process.env.INATURALIST_DAILY_BUDGET
+      : (process.env.INATURALIST_DAILY_BUDGET = before),
+  );
+  let at = NOW;
+  let calls = 0;
+  const options = {
+    now: () => at,
+    cacheDir,
+    warn() {},
+    fetchImpl: async () => {
+      calls += 1;
+      return Response.json(envelope());
+    },
+  };
+  const client = createInatClient(options);
+  assert.deepEqual(
+    await readdir(parent),
+    [],
+    'construction performs no directory write',
+  );
+  const params = {
+    scope: 'global',
+    quality: 'all',
+    taxa: 'all',
+    observedD1: '2026-11-02',
+  };
+  await Promise.all([
+    client.getObservations(params),
+    client.getObservations(params),
+  ]);
+  assert.deepEqual(
+    JSON.parse(await readFile(path.join(cacheDir, 'budget.json'), 'utf8')),
+    { date: '2026-11-04', count: 2 },
+  );
+  assert.deepEqual(
+    await readdir(cacheDir),
+    ['budget.json'],
+    'atomic temporary files are retired',
+  );
+  const restarted = createInatClient(options);
+  await assert.rejects(restarted.getObservations(params), {
+    status: 503,
+    code: 'inaturalist_budget_exhausted',
+  });
+  assert.equal(calls, 2);
+  at = Date.parse('2026-11-05T00:00:00Z');
+  await restarted.getObservations(params);
+  assert.deepEqual(restarted.budgetState(), {
+    date: '2026-11-05',
+    count: 1,
+    budget: 2,
+  });
+  assert.deepEqual(
+    JSON.parse(await readFile(path.join(cacheDir, 'budget.json'), 'utf8')),
+    { date: '2026-11-05', count: 1 },
+  );
+  assert.equal(calls, 3);
+});
+
+test('memory cache is an LRU bounded to 400 projected entries', async () => {
+  let at = NOW;
+  const cache = new Map();
+  const request = install({
+    cache,
+    now: () => at,
+    fetchImpl: async () => Response.json(envelope()),
+  });
+  for (let i = 0; i < 400; i += 1) {
+    if (i && i % 20 === 0) at += 61_000;
+    await request(boxUrl(i), { peer: String(i) });
+  }
+  assert.equal(cache.size, 400);
+  const firstKey = cache.keys().next().value;
+  const secondKey = [...cache.keys()][1];
+  await request(boxUrl(0));
+  await request(boxUrl(400));
+  assert.equal(cache.size, 400);
+  assert.equal(cache.has(firstKey), true);
+  assert.equal(cache.has(secondKey), false);
+});
+
+test('aborted client calls spend no budget and never fetch', async () => {
+  const controller = new AbortController();
+  controller.abort();
+  const client = createInatClient({
+    now: () => NOW,
+    cacheDir: null,
+    queueOptions: { intervalMs: 0 },
+    fetchImpl: () => assert.fail('aborted call fetched'),
+  });
+  await assert.rejects(
+    client.getObservations({}, { signal: controller.signal }),
+    { name: 'AbortError' },
+  );
+  assert.equal(client.budgetState().count, 0);
+});

server/providers/inaturalist/proxy.fixture.mjs

@@ -0,0 +1,70 @@
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import { inaturalistProxy } from './observations.js';
+
+export const NOW = Date.parse('2026-11-04T18:05:00Z');
+
+/** Mount the proxy over synthetic HTTP objects, without opening a socket. */
+export function installInatProxy(
+  defaultUrl,
+  options = {},
+  hook = 'configureServer',
+) {
+  let handler;
+  const plugin = inaturalistProxy({
+    now: () => NOW,
+    cacheDir: null,
+    queueOptions: { intervalMs: 0, windowMs: 0 },
+    warn() {},
+    ...options,
+  });
+  assert.equal(plugin.name, 'inaturalist');
+  assert.equal(typeof plugin.configureServer, 'function');
+  assert.equal(typeof plugin.configurePreviewServer, 'function');
+  plugin[hook]({
+    middlewares: {
+      use(mount, callback) {
+        assert.equal(mount, '/api/inaturalist');
+        handler = callback;
+      },
+    },
+  });
+  return async (
+    url = defaultUrl,
+    { method = 'GET', peer = 'local', headers = {}, signal } = {},
+  ) => {
+    const res = Object.assign(new EventEmitter(), {
+      headers: {},
+      writeHead(status, headers) {
+        this.status = status;
+        Object.assign(this.headers, headers);
+      },
+      setHeader(key, value) {
+        this.headers[key] = value;
+      },
+      end(value) {
+        this.status ??= this.statusCode;
+        this.body = JSON.parse(value);
+      },
+    });
+    const abort = () => {
+      res.destroyed = true;
+      res.emit('close');
+    };
+    signal?.addEventListener('abort', abort, { once: true });
+    try {
+      await handler(
+        Object.assign(new EventEmitter(), {
+          url,
+          method,
+          headers,
+          socket: { remoteAddress: peer },
+        }),
+        res,
+      );
+    } finally {
+      signal?.removeEventListener('abort', abort);
+    }
+    return res;
+  };
+}

server/providers/inaturalist/queue.js

@@ -0,0 +1,109 @@
+import { setTimeout as delay } from 'node:timers/promises';
+
+// A four-request burst keeps a cold view responsive; thereafter every provider
+// call shares the same one-per-second token supply. The rolling minute ceiling
+// queues the few requests a token bucket alone could allow above 60/min.
+const INAT_INTERVAL_MS = 1000;
+const INAT_BURST = 4;
+const INAT_WINDOW_MS = 60_000;
+const INAT_MAX_PER_WINDOW = 60;
+const INAT_MAX_IN_FLIGHT = 4;
+
+/** Observation queries outrank tiles waiting for a token. Aborted consumers
+ * leave the queue before an attempt or daily-budget reservation is spent. */
+export function createInatQueue({
+  now = () => performance.now(),
+  wait = (ms) => delay(ms),
+  intervalMs = INAT_INTERVAL_MS,
+  burst = INAT_BURST,
+  windowMs = INAT_WINDOW_MS,
+  maxInFlight = INAT_MAX_IN_FLIGHT,
+} = {}) {
+  const pending = [];
+  const dispatchedAt = [];
+  let tokens = burst;
+  let refilledAt = null;
+  let running = false;
+  let inFlight = 0;
+  let slotFreed = null;
+
+  function refill() {
+    const at = now();
+    if (refilledAt !== null && intervalMs > 0)
+      tokens = Math.min(
+        burst,
+        tokens + Math.max(0, at - refilledAt) / intervalMs,
+      );
+    if (intervalMs <= 0) tokens = burst;
+    refilledAt = at;
+  }
+
+  function schedule() {
+    if (running) return;
+    running = true;
+    // A microtask also lets same-turn observation queries take priority.
+    void Promise.resolve().then(drain);
+  }
+
+  async function drain() {
+    try {
+      while (pending.length) {
+        if (inFlight >= maxInFlight) {
+          await new Promise((resolve) => (slotFreed = resolve));
+          continue;
+        }
+        refill();
+        const at = now();
+        while (dispatchedAt.length && dispatchedAt[0] <= at - windowMs)
+          dispatchedAt.shift();
+        const tokenWait = tokens < 1 ? (1 - tokens) * intervalMs : 0;
+        const windowWait =
+          windowMs > 0 && dispatchedAt.length >= INAT_MAX_PER_WINDOW
+            ? dispatchedAt[0] + windowMs - at
+            : 0;
+        if (tokenWait > 0 || windowWait > 0) {
+          await wait(Math.ceil(Math.max(tokenWait, windowWait)));
+          continue;
+        }
+        // Stable sorting preserves FIFO order within each priority.
+        pending.sort((a, b) => a.priority - b.priority);
+        const job = pending.shift();
+        job.signal?.removeEventListener('abort', job.abort);
+        if (job.signal?.aborted) {
+          job.reject(job.signal.reason);
+          continue;
+        }
+        tokens -= 1;
+        if (windowMs > 0) dispatchedAt.push(at);
+        inFlight += 1;
+        // A rejected task releases its slot without stopping the queue.
+        void new Promise((resolve) => resolve(job.task()))
+          .then(job.resolve, job.reject)
+          .finally(() => {
+            inFlight -= 1;
+            const wake = slotFreed;
+            slotFreed = null;
+            wake?.();
+          });
+      }
+    } finally {
+      running = false;
+    }
+  }
+
+  return function enqueue(task, { signal, priority = 1 } = {}) {
+    if (signal?.aborted) return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+      const job = { task, signal, priority, resolve, reject };
+      job.abort = () => {
+        const index = pending.indexOf(job);
+        if (index >= 0) pending.splice(index, 1);
+        signal.removeEventListener('abort', job.abort);
+        reject(signal.reason);
+      };
+      signal?.addEventListener('abort', job.abort, { once: true });
+      pending.push(job);
+      schedule();
+    });
+  };
+}

server/providers/inaturalist/queue.test.mjs

@@ -0,0 +1,111 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createInatQueue } from './queue.js';
+
+async function until(check) {
+  for (let i = 0; i < 100; i += 1) {
+    if (check()) return;
+    await new Promise(setImmediate);
+  }
+  assert.fail('queue did not reach its expected state');
+}
+
+test('shared governor paces a four-call burst within the rolling minute ceiling', async () => {
+  let at = 0;
+  const waits = [];
+  const queue = createInatQueue({
+    now: () => at,
+    wait: async (ms) => {
+      waits.push(ms);
+      at += ms;
+    },
+  });
+  const dispatched = [];
+  await Promise.all(
+    Array.from({ length: 65 }, () => queue(() => dispatched.push(at))),
+  );
+  assert.equal(dispatched.length, 65);
+  assert.deepEqual(dispatched.slice(0, 7), [0, 0, 0, 0, 1000, 2000, 3000]);
+  assert.deepEqual(waits.slice(0, 3), [1000, 1000, 1000]);
+  for (const time of dispatched)
+    assert.ok(
+      dispatched.filter((other) => other > time - 60_000 && other <= time)
+        .length <= 60,
+    );
+  assert.equal(dispatched[60], 60_000);
+});
+
+test('an observation arriving during the pacing wait overtakes queued tiles', async () => {
+  let at = 0;
+  const waits = [];
+  const queue = createInatQueue({
+    burst: 1,
+    now: () => at,
+    wait: (ms) => new Promise((resolve) => waits.push({ ms, resolve })),
+  });
+  const dispatched = [];
+  await queue(() => dispatched.push('first tile'));
+  const tile = queue(() => dispatched.push('waiting tile'));
+  await until(() => waits.length === 1);
+  const observation = queue(() => dispatched.push('observation'), {
+    priority: 0,
+  });
+  at += waits[0].ms;
+  waits[0].resolve();
+  await observation;
+  assert.deepEqual(dispatched, ['first tile', 'observation']);
+  await until(() => waits.length === 2);
+  at += waits[1].ms;
+  waits[1].resolve();
+  await tile;
+  assert.deepEqual(dispatched, ['first tile', 'observation', 'waiting tile']);
+});
+
+test('superseded tasks leave before dispatch, and a rejection cannot poison the tail', async () => {
+  const queue = createInatQueue({ intervalMs: 0 });
+  const dispatched = [];
+  let release;
+  const first = queue(
+    () =>
+      new Promise((resolve) => {
+        release = resolve;
+      }),
+  );
+  await until(() => release);
+  const controller = new AbortController();
+  const superseded = queue(() => assert.fail('superseded tile dispatched'), {
+    signal: controller.signal,
+  });
+  const dropped = assert.rejects(superseded, { name: 'AbortError' });
+  controller.abort();
+  await dropped;
+  const failed = queue(() => {
+    dispatched.push('failed');
+    throw new Error('synthetic');
+  });
+  const failure = assert.rejects(failed, /synthetic/);
+  const succeeding = queue(() => dispatched.push('recovered'));
+  release();
+  await Promise.all([first, failure, succeeding]);
+  assert.deepEqual(dispatched, ['failed', 'recovered']);
+});
+
+test('a slow call does not hold later calls; at most four run at once', async () => {
+  const queue = createInatQueue({ intervalMs: 0, windowMs: 0 });
+  const releases = [];
+  const started = [];
+  const slow = (id) => () =>
+    new Promise((resolve) => {
+      started.push(id);
+      releases.push(() => resolve(id));
+    });
+  const jobs = [1, 2, 3, 4, 5].map((id) => queue(slow(id)));
+  await until(() => started.length === 4);
+  assert.deepEqual(started, [1, 2, 3, 4], 'four start without waiting');
+  releases[1]();
+  assert.equal(await jobs[1], 2, 'a later call finishes before the first');
+  await until(() => started.length === 5);
+  assert.deepEqual(started, [1, 2, 3, 4, 5], 'a freed slot starts the next');
+  for (const release of releases) release();
+  assert.deepEqual(await Promise.all(jobs), [1, 2, 3, 4, 5]);
+});

server/providers/inaturalist/speed.test.mjs

@@ -0,0 +1,218 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createInatClient } from './client.js';
+import { installInatProxy, NOW } from './proxy.fixture.mjs';
+import { syntheticGrid } from './grid.fixture.mjs';
+import { INAT_GRID_DECODE_MEASURE } from './grid.js';
+
+const gridUrl = '/grid?z=2&x=1&y=1&taxa=Aves';
+const params = {
+  scope: 'global',
+  taxa: 'all',
+  observedD1: '2026-11-02',
+};
+const tick = () => new Promise(setImmediate);
+
+const install = (options, hook) => installInatProxy(gridUrl, options, hook);
+
+test('tile cache lasts fifteen minutes, then returns stale before revalidation finishes', async () => {
+  let at = NOW;
+  let calls = 0;
+  let release;
+  const request = install({
+    now: () => at,
+    fetchImpl: () => {
+      calls += 1;
+      return calls === 1
+        ? Response.json(syntheticGrid())
+        : new Promise((resolve) => {
+            release = resolve;
+          });
+    },
+  });
+  const first = await request();
+  at += 899_999;
+  const freshPromise = request();
+  await tick();
+  assert.equal(calls, 1, 'a fresh tile never spends another upstream attempt');
+  assert.deepEqual((await freshPromise).body, first.body);
+  at += 1;
+  const stalePromise = request();
+  let resolved = false;
+  void stalePromise.then(() => {
+    resolved = true;
+  });
+  await tick();
+  try {
+    assert.equal(
+      resolved,
+      true,
+      'stale cells publish while refresh is pending',
+    );
+    const stale = await stalePromise;
+    assert.equal(stale.body.stale, true);
+    assert.equal(stale.body.fetchedAt, NOW);
+    assert.deepEqual(stale.body.cells, first.body.cells);
+    await request();
+    assert.equal(calls, 2, 'all stale consumers share one background refresh');
+    const refreshPromise = request(`${gridUrl}&refresh=wait`);
+    let refreshed = false;
+    void refreshPromise.then(() => {
+      refreshed = true;
+    });
+    await tick();
+    assert.equal(
+      refreshed,
+      false,
+      'a background consumer can await the same refresh',
+    );
+    release(Response.json(syntheticGrid()));
+    const fresh = await refreshPromise;
+    assert.equal(fresh.body.stale, undefined);
+    assert.equal(fresh.body.fetchedAt, at);
+    assert.equal(
+      calls,
+      2,
+      'waiting for fresh cells never duplicates upstream work',
+    );
+    release = null;
+  } finally {
+    release?.(Response.json(syntheticGrid()));
+  }
+});
+
+test('more than sixteen queued views and thirty local requests never report local rate limiting', async () => {
+  let release;
+  let calls = 0;
+  const request = install({
+    fetchImpl: async () => {
+      calls += 1;
+      if (calls === 1)
+        await new Promise((resolve) => {
+          release = resolve;
+        });
+      return Response.json(syntheticGrid());
+    },
+  });
+  const pending = Array.from({ length: 40 }, (_, x) =>
+    request(`/grid?z=6&x=${x}&y=1`),
+  );
+  await tick();
+  release();
+  const results = await Promise.all(pending);
+  assert.ok(results.every((result) => result.status === 200));
+  assert.equal(calls, 40);
+});
+
+test('only real upstream 429 or 5xx failures start cooldown', async () => {
+  for (const bad of [
+    () => Promise.reject(new Error('network')),
+    () => Response.json({ malformed: true }),
+    () => new Response('', { status: 404 }),
+  ]) {
+    let calls = 0;
+    const client = createInatClient({
+      now: () => NOW,
+      cacheDir: null,
+      queueOptions: { intervalMs: 0, windowMs: 0 },
+      warn() {},
+      fetchImpl: () => {
+        calls += 1;
+        return calls === 1
+          ? bad()
+          : Response.json({ results: [], total_results: 0 });
+      },
+    });
+    await assert.rejects(client.getObservations(params), { status: 502 });
+    await client.getObservations(params);
+    assert.equal(
+      calls,
+      2,
+      'a non-cooldown failure must not hold the next attempt',
+    );
+  }
+});
+
+test('actual upstream cooldown is marked separately from a local budget stop', async () => {
+  for (const upstream of [429, 503]) {
+    let calls = 0;
+    const request = install({
+      fetchImpl: () => {
+        calls += 1;
+        return new Response('', {
+          status: upstream,
+          headers: { 'Retry-After': '120' },
+        });
+      },
+    });
+    const first = await request();
+    assert.equal(first.headers['X-Upstream-Status'], String(upstream));
+    assert.equal(first.headers['Retry-After'], '120');
+    await request();
+    assert.equal(calls, 1);
+  }
+});
+
+test('upstream Retry-After zero survives the HTTP response and permits an immediate next request', async () => {
+  for (const upstream of [429, 503]) {
+    let calls = 0;
+    const request = install({
+      fetchImpl: () => {
+        calls += 1;
+        return calls === 1
+          ? new Response('', {
+              status: upstream,
+              headers: { 'Retry-After': '0' },
+            })
+          : Response.json(syntheticGrid());
+      },
+    });
+    const first = await request();
+    assert.equal(first.headers['X-Upstream-Status'], String(upstream));
+    assert.equal(first.headers['Retry-After'], '0');
+    assert.equal((await request()).status, 200);
+    assert.equal(calls, 2);
+  }
+});
+
+test('a local daily budget stop has a distinct code and no upstream cooldown marker', async (t) => {
+  const before = process.env.INATURALIST_DAILY_BUDGET;
+  process.env.INATURALIST_DAILY_BUDGET = '1';
+  t.after(() => {
+    if (before === undefined) delete process.env.INATURALIST_DAILY_BUDGET;
+    else process.env.INATURALIST_DAILY_BUDGET = before;
+  });
+  let calls = 0;
+  const request = install({
+    fetchImpl: () => {
+      calls += 1;
+      return Response.json(syntheticGrid());
+    },
+  });
+  assert.equal((await request()).status, 200);
+  const stopped = await request('/grid?z=2&x=0&y=1');
+  assert.equal(stopped.status, 503);
+  assert.equal(stopped.body.error, 'inaturalist_budget_exhausted');
+  assert.equal(stopped.headers['X-Upstream-Status'], undefined);
+  assert.equal((await request()).status, 200, 'cached data remains available');
+  assert.equal(calls, 1);
+});
+
+test('cached tiles avoid UTFGrid decode and decode timing entries stay bounded', async () => {
+  const request = install({
+    fetchImpl: () => Response.json(syntheticGrid()),
+  });
+  await request();
+  const sample = performance.getEntriesByName(INAT_GRID_DECODE_MEASURE)[0];
+  assert.ok(sample.duration >= 0);
+  for (let i = 0; i < 10; i += 1) await request();
+  assert.equal(
+    performance.getEntriesByName(INAT_GRID_DECODE_MEASURE)[0],
+    sample,
+  );
+  for (let x = 0; x < 4; x += 1) await request(`/grid?z=3&x=${x}&y=1`);
+  assert.equal(
+    performance.getEntriesByName(INAT_GRID_DECODE_MEASURE).length,
+    1,
+  );
+});

server/providers/local.js

@@ -29,6 +29,8 @@ import { firePerimetersProxy } from './firePerimeters.js';
 import { gnssIntegrityProxy } from './gnssIntegrity.js';
 import { ghostMapsProxy } from './ghostMaps.js';
 import { droneAirspaceProxy } from './droneAirspace.js';
+import { inaturalistProxy } from './inaturalist/observations.js';
+import { acartiaProxy } from './acartia.js';
 import { cycloneProxy } from './cyclones.js';
 import { windProxy } from './wind.js';
 
@@ -81,6 +83,8 @@ function localProviderPlugins({
     gnssIntegrityProxy(),
     ghostMapsProxy(),
     droneAirspaceProxy(),
+    inaturalistProxy(),
+    acartiaProxy(),
     keySetupEndpoint(),
   ];
 }

server/providers/openai/chat.js

@@ -64,6 +64,30 @@ function validMessages(messages) {
   return !pending.length;
 }
 
+/**
+ * A tool schema without the `pattern`s Chat Completions refuses: it answers
+ * 400 for a whole request whose tool uses Unicode property classes (`\p{L}`),
+ * as `resolve_area`'s area ids do. Every argument is still checked against
+ * the action's own contract before the tool runs, so the model loses a hint,
+ * not a rule. Realtime voice accepts these patterns and keeps them.
+ */
+export function chatSchema(schema) {
+  if (Array.isArray(schema)) return schema.map(chatSchema);
+  if (!object(schema)) return schema;
+  return Object.fromEntries(
+    Object.entries(schema)
+      .filter(
+        ([key, value]) =>
+          !(
+            key === 'pattern' &&
+            typeof value === 'string' &&
+            /\\[pP]\{/.test(value)
+          ),
+      )
+      .map(([key, value]) => [key, chatSchema(value)]),
+  );
+}
+
 export function createOpenAiChatHandler({
   annotationGuidance,
   tools = GEV_REALTIME_TOOLS,
@@ -126,7 +150,12 @@ export function createOpenAiChatHandler({
           tools: offeredTools(tools, { overpass }).map(
             ({ name, description, parameters }) => ({
               type: 'function',
-              function: { name, description, parameters, strict: false },
+              function: {
+                name,
+                description,
+                parameters: chatSchema(parameters),
+                strict: false,
+              },
             }),
           ),
         },

server/providers/openai/toolDescriptions.js

@@ -135,7 +135,7 @@ export const ACTION_DESCRIPTIONS = {
   },
   control_cockpit: {
     description:
-      'Explicit Cockpit requests only: enter from a selected/tracked aircraft (establishes Contacts itself; no set_context_mode), exit, status, or next/previous. Explicit exit-and-show voice: voicePanel preview/settings (Voice Settings), no confirmation.',
+      'Explicit Cockpit requests only: enter from a selected/tracked aircraft (needs only its own Flights/Military layer on, not Contacts; opens Contacts itself, no set_context_mode), exit, status, or next/previous. Explicit exit-and-show voice: voicePanel preview/settings (Voice Settings), no confirmation.',
     $position: 1,
     parameters: {
       properties: {
@@ -523,7 +523,7 @@ export const ACTION_DESCRIPTIONS = {
       properties: {
         direction: {
           description:
-            'Required for pan/tilt/rotate; orbit/rotate_globe default right.',
+            'Pan/rotate/tilt steps; orbit/rotate_globe default right.',
           $position: 2,
         },
         mode: {
@@ -531,6 +531,10 @@ export const ACTION_DESCRIPTIONS = {
             'once = bounded eased nudge; continuous = until stop/manual input. rotate_globe defaults continuous; other motions default once.',
           $position: 2,
         },
+        pitchDeg: {
+          description: 'Absolute; -45 default, -89 top-down.',
+          $position: 1,
+        },
       },
     },
   },

server/providers/space/celestrak.js

@@ -1,6 +1,9 @@
 import path from 'node:path';
 import { promises as fsp } from 'node:fs';
-import { celestrakTleUrl } from '../../../src/data/spaceProviderRequests.js';
+import {
+  celestrakSatcatUrl,
+  celestrakTleUrl,
+} from '../../../src/data/spaceProviderRequests.js';
 import { providerCooldownMs } from './cooldown.js';
 import { admitSameSiteKeyless } from '../common/same-site.js';
 import { readResponseTextCapped } from '../common/http.js';
@@ -22,84 +25,131 @@ import { readResponseTextCapped } from '../common/http.js';
  * 6 h; on upstream failure the freshest stale copy is served (a stale TLE
  * beats an empty satellites layer). Pattern mirrors openSkyProxy's
  * cache+serve-stale. Adapted from skylight's TleStore (MIT).
+ *
+ * The same plugin serves CelesTrak SATCAT records for the satellites layer's
+ * groups at `/api/celestrak-satcat/<group>` (object type, operational status
+ * and owner, which file each object under a class). The catalog changes
+ * slowly, so SATCAT is cached for a day. CelesTrak throttles the client, not
+ * the endpoint, so a 403 or 429 holds both routes off; any other failure
+ * holds off only the route that failed, so a bad SATCAT answer never stops
+ * TLE refreshes.
  */
 export function celestrakProxy() {
   const TLE_TTL_MS = 6 * 3600_000;
+  const SATCAT_TTL_MS = 24 * 3600_000;
   const CACHE_DIR = path.join(process.cwd(), '.gev-cache');
-  const groups = new Set([
+  /** The satellites layer's core groups (src/layers/satellites/policy.js). */
+  const coreGroups = [
     'stations',
     'visual',
     'gps-ops',
     'glo-ops',
     'galileo',
     'geo',
-    'starlink',
-    // Space Missions (`getActiveTle`) reads the full active catalog.
-    'active',
-  ]);
-  let cooldownUntil = 0;
-  const mem = new Map(); // group -> { at: epochMs, body: string }
-  const inflight = new Map(); // group -> Promise<{at, body}|null>
-
-  const diskPath = (group) => path.join(CACHE_DIR, `celestrak-${group}.json`);
-
-  async function readDisk(group) {
-    try {
-      const parsed = JSON.parse(await fsp.readFile(diskPath(group), 'utf8'));
-      if (typeof parsed?.body === 'string' && Number.isFinite(parsed?.at))
-        return parsed;
-    } catch {
-      /* no disk cache yet */
-    }
-    return null;
-  }
-
-  async function writeDisk(group, entry) {
-    try {
-      await fsp.mkdir(CACHE_DIR, { recursive: true });
-      await fsp.writeFile(diskPath(group), JSON.stringify(entry), 'utf8');
-    } catch (err) {
-      console.warn('[celestrak-proxy] cache write failed');
-    }
-  }
+    'resource',
+    'weather',
+    'planet',
+    'sar',
+    'science',
+  ];
+  const feeds = [
+    {
+      route: '/api/celestrak',
+      ttlMs: TLE_TTL_MS,
+      cacheHeader: 'x-tle-cache',
+      cachedAtHeader: 'X-TLE-Cached-At',
+      diskName: (group) => `celestrak-${group}.json`,
+      upstreamUrl: celestrakTleUrl,
+      groups: new Set([
+        ...coreGroups,
+        'starlink',
+        // Space Missions (`getActiveTle`) reads the full active catalog.
+        'active',
+      ]),
+      // An upstream error page parses to zero TLEs — treat as failure, keep cache.
+      validate: (body) => /^1 /m.test(body),
+      invalid: 'no TLE lines in response',
+    },
+    {
+      route: '/api/celestrak-satcat',
+      ttlMs: SATCAT_TTL_MS,
+      cacheHeader: 'x-satcat-cache',
+      cachedAtHeader: 'X-SATCAT-Cached-At',
+      diskName: (group) => `celestrak-satcat-${group}.json`,
+      upstreamUrl: celestrakSatcatUrl,
+      groups: new Set(coreGroups),
+      // A real answer, even for an empty group, starts with the CSV header.
+      validate: (body) => /^OBJECT_NAME,/.test(body),
+      invalid: 'no SATCAT header in response',
+    },
+  ];
+  // CelesTrak throttling (403/429) is per client, so it holds every feed
+  // off; any other failure holds off only the feed that failed, so a bad
+  // SATCAT answer never blocks the TLEs the layer cannot do without.
+  let hostCooldownUntil = 0;
 
   /** The largest group (`active`) measures ~2.7 MB; this bounds a runaway body. */
   const CELESTRAK_MAX_RESPONSE_BYTES = 16 * 1024 * 1024;
 
-  async function fetchUpstream(group) {
-    const url = celestrakTleUrl(group);
-    const signal = AbortSignal.timeout(20000);
-    const res = await fetch(url.toString(), {
-      signal,
-      // CelesTrak 403s bulk groups (e.g. `active`) unless the request carries a
-      // descriptive User-Agent with a contact point.
-      headers: {
-        'User-Agent':
-          'gods-eye-view-celestrak-proxy/1.0 (+https://github.com/bilawalsidhu/gods-eye-view)',
-      },
-    });
-    if (!res.ok) {
-      // Group refreshes run in parallel: a later failure without Retry-After
-      // must never shorten a longer deadline an earlier one already set.
-      cooldownUntil = Math.max(
-        cooldownUntil,
-        Date.now() + providerCooldownMs(res),
-      );
-      void res.body?.cancel().catch(() => {});
-      throw new Error(`HTTP ${res.status}`);
-    }
-    const body = await readResponseTextCapped(
-      res,
-      CELESTRAK_MAX_RESPONSE_BYTES,
-      signal,
-    );
-    // An upstream error page parses to zero TLEs — treat as failure, keep cache.
-    if (!/^1 /m.test(body)) throw new Error('no TLE lines in response');
-    return { at: Date.now(), body };
-  }
+  function createFeedHandler(feed) {
+    let feedCooldownUntil = 0;
+    const cooldownUntil = () => Math.max(hostCooldownUntil, feedCooldownUntil);
+    const mem = new Map(); // group -> { at: epochMs, body: string }
+    const inflight = new Map(); // group -> Promise<{at, body}|null>
+    const diskPath = (group) => path.join(CACHE_DIR, feed.diskName(group));
 
-  const installMiddleware = (server) => {
-    server.middlewares.use('/api/celestrak', async (req, res) => {
+    async function readDisk(group) {
+      try {
+        const parsed = JSON.parse(await fsp.readFile(diskPath(group), 'utf8'));
+        if (typeof parsed?.body === 'string' && Number.isFinite(parsed?.at))
+          return parsed;
+      } catch {
+        /* no disk cache yet */
+      }
+      return null;
+    }
+
+    async function writeDisk(group, entry) {
+      try {
+        await fsp.mkdir(CACHE_DIR, { recursive: true });
+        await fsp.writeFile(diskPath(group), JSON.stringify(entry), 'utf8');
+      } catch (err) {
+        console.warn('[celestrak-proxy] cache write failed');
+      }
+    }
+
+    async function fetchUpstream(group) {
+      const url = feed.upstreamUrl(group);
+      const signal = AbortSignal.timeout(20000);
+      const res = await fetch(url.toString(), {
+        signal,
+        // CelesTrak 403s bulk groups (e.g. `active`) unless the request carries a
+        // descriptive User-Agent with a contact point.
+        headers: {
+          'User-Agent':
+            'gods-eye-view-celestrak-proxy/1.0 (+https://github.com/bilawalsidhu/gods-eye-view)',
+        },
+      });
+      if (!res.ok) {
+        // Group refreshes run in parallel: a later failure without Retry-After
+        // must never shorten a longer deadline an earlier one already set.
+        const until = Date.now() + providerCooldownMs(res);
+        if (res.status === 403 || res.status === 429)
+          hostCooldownUntil = Math.max(hostCooldownUntil, until);
+        else feedCooldownUntil = Math.max(feedCooldownUntil, until);
+        void res.body?.cancel().catch(() => {});
+        throw new Error(`HTTP ${res.status}`);
+      }
+      const body = await readResponseTextCapped(
+        res,
+        CELESTRAK_MAX_RESPONSE_BYTES,
+        signal,
+      );
+      if (!feed.validate(body)) throw new Error(feed.invalid);
+      return { at: Date.now(), body };
+    }
+
+    return async (req, res) => {
       const group = String(req.url || '')
         .replace(/^\//, '')
         .split('?')[0];
@@ -111,7 +161,7 @@ export function celestrakProxy() {
         res.end();
         return;
       }
-      if (!groups.has(group)) {
+      if (!feed.groups.has(group)) {
         res.writeHead(400, { 'Content-Type': 'text/plain' });
         res.end('invalid group');
         return;
@@ -123,15 +173,15 @@ export function celestrakProxy() {
         if (res.headersSent) return;
         res.writeHead(status, {
           'Content-Type': 'text/plain',
-          'x-tle-cache': cacheStatus,
+          [feed.cacheHeader]: cacheStatus,
           'Cache-Control': 'no-store',
           ...(entry
-            ? { 'X-TLE-Cached-At': new Date(entry.at).toISOString() }
+            ? { [feed.cachedAtHeader]: new Date(entry.at).toISOString() }
             : {}),
-          ...(cooldownUntil > 0 && Date.now() < cooldownUntil
+          ...(cooldownUntil() > 0 && Date.now() < cooldownUntil()
             ? {
                 'Retry-After': String(
-                  Math.ceil((cooldownUntil - Date.now()) / 1000),
+                  Math.ceil((cooldownUntil() - Date.now()) / 1000),
                 ),
               }
             : {}),
@@ -145,11 +195,11 @@ export function celestrakProxy() {
           entry = await readDisk(group);
           if (entry) mem.set(group, entry);
         }
-        if (entry && now - entry.at < TLE_TTL_MS) {
+        if (entry && now - entry.at < feed.ttlMs) {
           send(200, entry.body, 'HIT', entry);
           return;
         }
-        if (Date.now() < cooldownUntil) {
+        if (Date.now() < cooldownUntil()) {
           send(
             entry ? 200 : 502,
             entry?.body || 'celestrak upstream cooling down',
@@ -169,8 +219,8 @@ export function celestrakProxy() {
                 return fresh;
               })
               .catch((err) => {
-                if (Date.now() >= cooldownUntil)
-                  cooldownUntil = Date.now() + 60000;
+                if (Date.now() >= feedCooldownUntil)
+                  feedCooldownUntil = Date.now() + 60000;
                 console.warn(
                   '[celestrak-proxy] refresh failed — serving cache if any',
                 );
@@ -191,7 +241,13 @@ export function celestrakProxy() {
         console.error('[celestrak-proxy] request failed');
         send(500, 'celestrak proxy error', 'ERROR');
       }
-    });
+    };
+  }
+
+  const handlers = feeds.map((feed) => [feed.route, createFeedHandler(feed)]);
+  const installMiddleware = (server) => {
+    for (const [route, handler] of handlers)
+      server.middlewares.use(route, handler);
   };
   return {
     name: 'celestrak-proxy',