fix(bikeshare): scope city failures to range and report partial outages

A failure now ends when its city leaves range or the camera rises above the
activation gate, so an empty map no longer reads LOAD FAILED. Late activation
and status rejections are ignored like late successes. Partial failure reads
DEGRADED, every in-range city failing over cached points reads STALE, and
freshness advances only on a refresh that succeeded. Behavioural tests drive
the real proximity, update and enable paths. Docs say no licence is published
for Toronto and list Social Bicycles and PBSC. The merge also restored the #61
GBFS v3 changelog entry that an earlier merge on main dropped.

src/layers/bikeshare/controls.js

@@ -56,7 +56,7 @@ export function createControls({ state: layerState, services, parts, source }) {
 
     /**
      * Return current layer statistics for the UI status display.
-     * @returns {{ count: number, lastUpdate: number|null, loading: boolean, loadingLabel?: string, error?: string }}
+     * @returns {{ count: number, lastUpdate: number|null, loading: boolean, loadingLabel?: string, error?: string, degraded?: boolean, stale?: boolean }}
      */
     getStats() {
       const stats = {
@@ -71,12 +71,19 @@ export function createControls({ state: layerState, services, parts, source }) {
             : 'scanning nearby systems...';
       }
       // A failed city is only the layer's failure when it left nothing on the
-      // map. While any city still renders, the layer is working and says so.
-      if (
-        layerState._failedCityIds.size > 0 &&
-        layerState._stationRenderMap.size === 0
-      ) {
-        stats.error = 'GBFS fetch error';
+      // map. While other cities still render, the partial failure reads
+      // DEGRADED; when every in-range city failed and only previously drawn
+      // points remain, they read STALE.
+      if (layerState._failedCityIds.size > 0) {
+        if (layerState._stationRenderMap.size === 0) {
+          stats.error = 'GBFS fetch error';
+        } else {
+          stats.degraded = true;
+          const allFailed = Array.from(layerState._activeCityIds).every(
+            (cityId) => layerState._failedCityIds.has(cityId),
+          );
+          if (allFailed) stats.stale = true;
+        }
       }
       return stats;
     },

src/layers/bikeshare/failureReporting.test.mjs

@@ -78,3 +78,299 @@ test('a recovered city clears its own failure', () => {
     'the failure outlived the city that caused it',
   );
 });
+
+// The cases above pin how getStats() reads failure state. The cases below
+// drive the real proximity check, status poll and lifecycle against a fake
+// GBFS source, so the failure state they read is the state the layer builds.
+
+import * as Cesium from 'cesium';
+import { CITY_BY_ID } from './registry.js';
+import { createIngestion } from './ingestion.js';
+import { createModel } from './model.js';
+import { createViewport } from './viewport.js';
+import { createRendering } from './rendering.js';
+import { createLifecycle } from './lifecycle.js';
+
+const TORONTO = 'toronto-bike-share';
+const BUFFALO = 'buffalo-reddy';
+// Within range of both Toronto and Buffalo.
+const BETWEEN = { lat: 43.25, lon: -79.1 };
+// Within range of Toronto only.
+const TORONTO_ONLY = { lat: 43.7, lon: -79.6 };
+// Within range of Buffalo only.
+const BUFFALO_ONLY = { lat: 42.5, lon: -78.0 };
+const LOW_M = 10_000;
+
+// disable() detaches a keydown listener; node has no document.
+globalThis.document ??= {
+  addEventListener() {},
+  removeEventListener() {},
+};
+
+/** A GBFS source whose per-city answers each test can change. */
+function makeSource() {
+  const cityOf = (url) => {
+    for (const [id, city] of CITY_BY_ID) {
+      if (url === city.stationInformationUrl) return { id, kind: 'info' };
+      if (url === city.stationStatusUrl) return { id, kind: 'status' };
+    }
+    throw new Error(`unexpected GBFS url ${url}`);
+  };
+  const source = {
+    dead: new Set(),
+    deadStatus: new Set(),
+    /** Optional per-call override: (cityId, kind) => Promise | undefined. */
+    hook: null,
+    async getStations(url, { signal } = {}) {
+      const { id, kind } = cityOf(url);
+      const hooked = source.hook?.(id, kind);
+      if (hooked) return hooked;
+      await new Promise((resolve) => setTimeout(resolve, 1));
+      signal?.throwIfAborted();
+      if (source.dead.has(id)) throw new Error('GBFS HTTP 404');
+      if (kind === 'status' && source.deadStatus.has(id))
+        throw new Error('GBFS HTTP 503');
+      const city = CITY_BY_ID.get(id);
+      if (kind === 'info') {
+        return {
+          data: {
+            stations: [
+              {
+                station_id: `${id}-1`,
+                name: `${id} dock`,
+                lat: city.centerLat,
+                lon: city.centerLon,
+                capacity: 10,
+              },
+            ],
+          },
+        };
+      }
+      return {
+        data: {
+          stations: [
+            {
+              station_id: `${id}-1`,
+              num_bikes_available: 3,
+              num_docks_available: 7,
+              is_installed: true,
+              is_renting: true,
+              is_returning: true,
+            },
+          ],
+        },
+      };
+    },
+  };
+  return source;
+}
+
+/** Assemble the layer from its real parts around a camera the test moves. */
+function makeLiveLayer() {
+  const source = makeSource();
+  const services = {
+    render: { governorRequestRender() {} },
+    overlays: {
+      setOverlayEntries() {},
+      setOverlaySourceVisible() {},
+      clearOverlaySource() {},
+    },
+    sprites: { registerSpriteCollection() {}, restoreSpriteOrder() {} },
+    picking: { registerPickOwner() {}, unregisterPickOwner() {} },
+  };
+  const state = createState({ services });
+  const parts = {};
+  const context = { state, services, parts, source };
+  parts.ingestion = createIngestion(context);
+  parts.model = createModel(context);
+  parts.viewport = createViewport(context);
+  parts.rendering = createRendering(context);
+  // Selection owns a DOM click handler; nothing here selects a station.
+  parts.selection = {
+    _installClickHandler() {},
+    _clearSelection() {},
+    _onKeyDown() {},
+  };
+  parts.queries = { collectDetectableStations: () => [] };
+  parts.lifecycle = createLifecycle(context);
+  const { methods: controls } = createControls(context);
+
+  const camera = { ...BETWEEN, height: LOW_M };
+  const viewer = {
+    camera: {
+      get positionCartographic() {
+        return Cesium.Cartographic.fromDegrees(
+          camera.lon,
+          camera.lat,
+          camera.height,
+        );
+      },
+      computeViewRectangle: () => undefined,
+      changed: { addEventListener() {}, removeEventListener() {} },
+    },
+    scene: { globe: {}, primitives: { add() {}, remove() {} } },
+  };
+  parts.lifecycle.methods.init(viewer);
+
+  return {
+    state,
+    source,
+    stats: () => controls.getStats(),
+    moveTo(place, height = LOW_M) {
+      Object.assign(camera, place, { height });
+      return parts.viewport.runProximityCheck();
+    },
+    async enable() {
+      parts.lifecycle.methods.enable(viewer);
+      await settle();
+    },
+    disable: () => parts.lifecycle.methods.disable(viewer),
+    poll: () => parts.ingestion.methods.update(),
+  };
+}
+
+/** Let fire-and-forget activation started by enable() finish. */
+async function settle() {
+  for (let i = 0; i < 5; i += 1)
+    await new Promise((resolve) => setTimeout(resolve, 2));
+}
+
+function deferred() {
+  let resolve, reject;
+  const promise = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+test('a city that fails beside one that renders reads DEGRADED, not healthy', async () => {
+  const layer = makeLiveLayer();
+  layer.source.dead.add(BUFFALO);
+  await layer.enable();
+
+  const stats = layer.stats();
+  assert.equal(stats.count, 1, 'Toronto should still draw');
+  assert.equal(stats.error, undefined);
+  assert.equal(stats.degraded, true, 'the Buffalo failure was hidden');
+  assert.equal(stats.stale, undefined);
+});
+
+test('a failed city that comes back clears its own failure', async () => {
+  const layer = makeLiveLayer();
+  layer.source.dead.add(BUFFALO);
+  await layer.enable();
+  assert.equal(layer.stats().degraded, true);
+
+  layer.source.dead.clear();
+  await layer.moveTo(BETWEEN);
+  const stats = layer.stats();
+  assert.equal(stats.count, 2);
+  assert.equal(stats.degraded, undefined);
+  assert.equal(stats.error, undefined);
+});
+
+test('a status poll that recovers clears the failure the last poll set', async () => {
+  const layer = makeLiveLayer();
+  await layer.moveTo(TORONTO_ONLY);
+  await layer.enable();
+  layer.source.deadStatus.add(TORONTO);
+  await layer.poll();
+  assert.equal(layer.stats().degraded, true);
+
+  layer.source.deadStatus.clear();
+  await layer.poll();
+  assert.equal(layer.stats().degraded, undefined);
+  assert.equal(layer.stats().stale, undefined);
+});
+
+test('a failure does not outlive its city leaving range', async () => {
+  const layer = makeLiveLayer();
+  layer.source.dead.add(BUFFALO);
+  await layer.enable();
+  await layer.moveTo(BUFFALO_ONLY);
+  assert.equal(layer.stats().error, 'GBFS fetch error');
+
+  // Low over the open Atlantic: nothing in range is empty, not broken.
+  await layer.moveTo({ lat: 30, lon: -40 });
+  const stats = layer.stats();
+  assert.equal(stats.count, 0);
+  assert.equal(stats.error, undefined, 'LOAD FAILED over empty ocean');
+  assert.equal(stats.degraded, undefined);
+});
+
+test('zooming out above the altitude gate drops a city failure', async () => {
+  const layer = makeLiveLayer();
+  layer.source.dead.add(BUFFALO);
+  await layer.enable();
+  await layer.moveTo(BUFFALO_ONLY);
+  assert.equal(layer.stats().error, 'GBFS fetch error');
+
+  await layer.moveTo(BUFFALO_ONLY, 200_000);
+  const stats = layer.stats();
+  assert.equal(stats.count, 0);
+  assert.equal(stats.error, undefined, 'LOAD FAILED above the gate');
+});
+
+test('a late rejection from before a disable/re-enable is ignored', async () => {
+  const layer = makeLiveLayer();
+  await layer.moveTo(BUFFALO_ONLY);
+  const first = deferred();
+  // The first info request hangs and ignores its abort signal.
+  layer.source.hook = (id, kind) => {
+    if (id !== BUFFALO || kind !== 'info') return undefined;
+    layer.source.hook = null;
+    return first.promise;
+  };
+  await layer.enable();
+  layer.disable();
+  await layer.enable();
+  assert.equal(layer.stats().count, 1, 're-enable should draw Buffalo');
+
+  first.reject(new Error('GBFS HTTP 500'));
+  await settle();
+  const stats = layer.stats();
+  assert.equal(stats.count, 1, 'a stale rejection tore down live points');
+  assert.equal(stats.error, undefined);
+  assert.equal(stats.degraded, undefined);
+});
+
+test('a late status poll rejection from before a disable/re-enable is ignored', async () => {
+  const layer = makeLiveLayer();
+  await layer.moveTo(TORONTO_ONLY);
+  await layer.enable();
+  const first = deferred();
+  layer.source.hook = (id, kind) => {
+    if (id !== TORONTO || kind !== 'status') return undefined;
+    layer.source.hook = null;
+    return first.promise;
+  };
+  const poll = layer.poll();
+  layer.disable();
+  await layer.enable();
+
+  first.reject(new Error('GBFS HTTP 500'));
+  await poll;
+  const stats = layer.stats();
+  assert.equal(stats.count, 1);
+  assert.equal(stats.degraded, undefined);
+  assert.equal(stats.error, undefined);
+});
+
+test('every status poll failing over cached points reads STALE, not fresh', async () => {
+  const layer = makeLiveLayer();
+  await layer.moveTo(TORONTO_ONLY);
+  await layer.enable();
+  const loadedAt = layer.stats().lastUpdate;
+  assert.ok(loadedAt, 'activation should record freshness');
+
+  layer.source.deadStatus.add(TORONTO);
+  await new Promise((resolve) => setTimeout(resolve, 5));
+  await layer.poll();
+  const stats = layer.stats();
+  assert.equal(stats.count, 1, 'the cached points stay drawn');
+  assert.equal(stats.error, undefined);
+  assert.equal(stats.degraded, true);
+  assert.equal(stats.stale, true);
+  assert.equal(stats.lastUpdate, loadedAt, 'a failed poll advanced freshness');
+});

src/layers/bikeshare/ingestion.js

@@ -171,20 +171,21 @@ export function createIngestion({
 
       const generation = layerState._proximityGeneration;
       const cityIds = Array.from(layerState._activeCityIds);
+      const isCurrent = (cityId) =>
+        layerState._enabled &&
+        layerState._activeCityIds.has(cityId) &&
+        generation === layerState._proximityGeneration;
+      let refreshed = false;
       await Promise.all(
         cityIds.map(async (cityId) => {
           try {
             const statusMap = await loadCityStationStatus(cityId, generation);
-            if (
-              !layerState._enabled ||
-              !layerState._activeCityIds.has(cityId) ||
-              generation !== layerState._proximityGeneration
-            )
-              return;
+            if (!isCurrent(cityId)) return;
             parts.rendering.applyStatusToPoints(cityId, statusMap);
             layerState._failedCityIds.delete(cityId);
+            refreshed = true;
           } catch (error) {
-            if (error?.name === 'AbortError') return;
+            if (error?.name === 'AbortError' || !isCurrent(cityId)) return;
             console.warn(
               `[Data:Bikeshare] ${cityId} status update error:`,
               error,
@@ -195,7 +196,9 @@ export function createIngestion({
       );
 
       layerState._count = layerState._stationRenderMap.size;
-      if (layerState._count > 0) layerState._lastUpdate = Date.now();
+      // Freshness advances only on a poll that actually refreshed a city.
+      if (refreshed && layerState._count > 0)
+        layerState._lastUpdate = Date.now();
     },
   };
 

src/layers/bikeshare/registry.test.mjs

@@ -23,7 +23,7 @@ test('every registered city is reachable through the GBFS proxy allowlist', () =
         `${city.id}: host ${url.hostname} is not allowlisted`,
       );
       assert.equal(
-        isAllowedGbfsPath(url.pathname),
+        isAllowedGbfsPath(url.pathname, url.hostname),
         true,
         `${city.id}: path ${url.pathname} is not allowlisted`,
       );

src/layers/bikeshare/state.js

@@ -104,8 +104,9 @@ export function createState({ services }) {
    *
    * Per city rather than one layer-wide flag: feeds are fetched independently,
    * so a retired operator must not mark a layer that other cities are still
-   * populating as failed. The layer reports failure only when these cost it
-   * everything it had to draw — see `getStats()` in controls.js.
+   * populating as failed. Entries are dropped when their city leaves range.
+   * The layer reports failure only when these cost it everything it had to
+   * draw, and degraded otherwise — see `getStats()` in controls.js.
    */
 
   layerState._failedCityIds = new Set();

src/layers/bikeshare/viewport.js

@@ -122,6 +122,9 @@ export function createViewport({ state: layerState, services, parts, source }) {
     const cityIds = Array.from(layerState._activeCityIds);
     for (const cityId of cityIds) deactivateCity(cityId);
     layerState._activeCityIds.clear();
+    // A failure belongs to a city in range; none are once everything is off.
+    layerState._failedCityIds.clear();
+    layerState._count = 0;
   }
 
   /**
@@ -171,6 +174,14 @@ export function createViewport({ state: layerState, services, parts, source }) {
       layerState._failedCityIds.delete(cityId);
     } catch (error) {
       if (error?.name === 'AbortError') return;
+      // A rejection from superseded work must not mark (or tear down) a city
+      // that a newer proximity check or re-enable now owns.
+      if (
+        !layerState._enabled ||
+        !layerState._activeCityIds.has(cityId) ||
+        generation !== layerState._proximityGeneration
+      )
+        return;
       console.warn(`[Data:Bikeshare] ${cityId} activate error:`, error);
       layerState._failedCityIds.add(cityId);
       deactivateCity(cityId);
@@ -208,6 +219,10 @@ export function createViewport({ state: layerState, services, parts, source }) {
         deactivateCity(cityId);
       }
     }
+    // A failure never outlives its city's range.
+    for (const cityId of layerState._failedCityIds) {
+      if (!nextActive.has(cityId)) layerState._failedCityIds.delete(cityId);
+    }
 
     layerState._activeCityIds = nextActive;
     if (layerState._activeCityIds.size === 0) {