Merge branch 'main' into feat/typed-ai-chat

src/data/radioProxy.test.mjs

@@ -541,6 +541,191 @@ test('a mirror answering an invalid reason phrase rejects instead of crashing',
   await assert.rejects(Promise.race([fetchMirror(), crashed]), TypeError);
 });
 
+test('priority-country configuration is bounded, normalized and validated before requests', async () => {
+  const { parseRadioPriorityCountries } = await import('../../server/providers/radio/catalog.js');
+  assert.deepEqual(parseRadioPriorityCountries(' in, PL,in, '), ['IN', 'PL']);
+  assert.deepEqual(parseRadioPriorityCountries(''), []);
+  assert.deepEqual(parseRadioPriorityCountries('uk,GB,UK'), ['GB']);
+  assert.deepEqual(parseRadioPriorityCountries('US,CA,IN,PL,DE,FR,UK,GB,JP'), ['US', 'CA', 'IN', 'PL', 'DE', 'FR', 'GB', 'JP']);
+  for (const value of ['ZZ', 'India', 'IN&limit=9999', 'US,CA,IN,PL,DE,FR,GB,JP,AU']) {
+    assert.throws(() => createProxy({ priorityCountries: value }), /RADIO_PRIORITY_COUNTRIES/);
+  }
+});
+
+test('UK aliases query and report GB once and retain British stations', async () => {
+  const countryQueries = [];
+  const middleware = createProxy({
+    priorityCountries: 'UK,GB',
+    fetchImpl: async (url) => {
+      const parsed = new URL(url);
+      if (parsed.pathname === '/json/servers')
+        return responseJson([{ name: 'de1.api.radio-browser.info' }]);
+      const country = parsed.searchParams.get('countrycode');
+      if (country) {
+        countryQueries.push(country);
+        return responseJson([station({ country: 'United Kingdom', countrycode: 'GB' })]);
+      }
+      return responseJson(healthyRowsForQuery(url));
+    },
+  });
+  const response = await invoke(middleware, '/stations');
+  assert.equal(response.status, 200);
+  const body = JSON.parse(response.body);
+  assert.deepEqual(countryQueries, ['GB']);
+  assert.deepEqual(body.coverage.priorityCountries, [
+    { countryCode: 'GB', succeeded: true, stationCount: 1 },
+  ]);
+  assert.equal(body.stations.find((row) => row.id === UUID)?.countryCode, 'GB');
+});
+
+test('low-click country stations survive a full global catalog, with bounded cached queries and deduplication', async () => {
+  const calls = [];
+  let active = 0;
+  let peak = 0;
+  const middleware = createProxy({
+    priorityCountries: 'IN,PL',
+    fetchImpl: async (url) => {
+      const parsed = new URL(url);
+      calls.push(parsed);
+      if (parsed.pathname === '/json/servers') return responseJson([{ name: 'de1.api.radio-browser.info' }]);
+      if (parsed.pathname.startsWith('/json/url/')) return responseJson({ ok: true });
+      peak = Math.max(peak, ++active);
+      await new Promise((resolve) => setTimeout(resolve, 1));
+      active--;
+      const country = parsed.searchParams.get('countrycode');
+      if (country) {
+        assert.equal(parsed.searchParams.get('limit'), '200');
+        assert.equal(parsed.searchParams.get('is_https'), 'true');
+        const rows = catalogRows(country === 'IN' ? '10000000' : '20000000', 'community', 60)
+          .map((row) => ({ ...row, countrycode: country, clickcount: 0 }));
+        return responseJson([rows[0], ...rows]);
+      }
+      return responseJson(catalogRows('30000000', queryTag(url) || 'news', 900));
+    },
+  });
+  const responses = await Promise.all([invoke(middleware, '/stations'), invoke(middleware, '/stations')]);
+  const body = JSON.parse(responses[0].body);
+  assert.equal(body.degraded, false);
+  assert.equal(body.stations.length, 750);
+  assert.equal(new Set(body.stations.map((row) => row.id)).size, 750);
+  for (const country of ['IN', 'PL'])
+    assert.ok(body.stations.filter((row) => row.countryCode === country).length >= 40);
+  assert.ok(body.stations.some((row) => row.countryCode === 'US'));
+  assert.equal(calls.filter((url) => url.pathname.includes('/stations/')).length, 11);
+  assert.ok(peak <= 3);
+  const count = calls.length;
+  await invoke(middleware, '/stations');
+  assert.equal(calls.length, count, 'country queries share the 45-minute cache');
+  const id = body.stations.find((row) => row.countryCode === 'IN').id;
+  assert.equal((await invoke(middleware, `/click/${id}`, 'POST')).status, 204);
+});
+
+test('country failures never block cold or warm global catalog admission, even after seven days', async () => {
+  for (const coldFailure of [false, true]) {
+    let clock = 4_000_000;
+    let fail = coldFailure;
+    let calls = 0;
+    const middleware = createProxy({
+      priorityCountries: ['IN'], now: () => clock,
+      fetchImpl: async (url) => {
+        calls++;
+        if (String(url).includes('/json/servers')) return responseJson([{ name: 'de1.api.radio-browser.info' }]);
+        if (new URL(url).searchParams.has('countrycode')) {
+          if (fail) throw new Error('offline');
+          return responseJson([station({ countrycode: 'IN', country: 'India', tags: 'community' })]);
+        }
+        return responseJson(healthyRowsForQuery(url));
+      },
+    });
+    let generation = 0;
+    for (const elapsed of [0, 46 * 60 * 1000, 8 * 24 * 60 * 60 * 1000]) {
+      clock += elapsed;
+      if (elapsed) fail = true;
+      const response = await invoke(middleware, '/stations');
+      const body = JSON.parse(response.body);
+      assert.equal(response.status, 200);
+      assert.equal(body.stale, false);
+      assert.equal(body.degraded, false);
+      assert.ok(body.acceptedGeneration > generation);
+      generation = body.acceptedGeneration;
+      assert.equal(body.coverage.priorityCountries[0].succeeded, !fail);
+      assert.equal(body.coverage.priorityCountries[0].stationCount, fail ? 0 : 1);
+      const count = calls;
+      clock += 60_001;
+      assert.deepEqual(JSON.parse((await invoke(middleware, '/stations')).body), body);
+      assert.equal(calls, count, 'country failure does not shorten the healthy cache');
+    }
+  }
+});
+
+test('valid countries with no eligible stations are accepted and cached; malformed country responses stay isolated', async () => {
+  for (const mode of ['wrong', 'oversized', 'empty', 'ineligible', 'malformed']) {
+    let clock = 4_000_000;
+    let calls = 0;
+    const middleware = createProxy({
+      priorityCountries: ['IN'], now: () => clock,
+      fetchImpl: async (url) => {
+        calls++;
+        if (String(url).includes('/json/servers')) return responseJson([{ name: 'de1.api.radio-browser.info' }]);
+        if (new URL(url).searchParams.has('countrycode')) {
+          const rows = {
+            empty: [], wrong: [station()], malformed: [{ name: 'missing fields' }],
+            oversized: catalogRows('10000000', 'community', 201).map((row) => ({ ...row, countrycode: 'IN' })),
+            ineligible: [{ hls: 1 }, { codec: 'OGG' }, { codec: 'OPUS' }, { url_resolved: 'https://127.0.0.1/live.mp3' }]
+              .map((overrides) => station({ countrycode: 'IN', ...overrides })),
+          };
+          return responseJson(rows[mode]);
+        }
+        return responseJson(healthyRowsForQuery(url));
+      },
+    });
+    const response = await invoke(middleware, '/stations');
+    const body = JSON.parse(response.body);
+    assert.equal(response.status, 200, mode);
+    assert.equal(body.degraded, false, mode);
+    assert.ok(body.acceptedGeneration > 0, mode);
+    assert.equal(body.coverage.priorityCountries[0].stationCount, 0, mode);
+    assert.equal(body.coverage.priorityCountries[0].succeeded, !['oversized', 'malformed'].includes(mode), mode);
+    const count = calls;
+    clock += 44 * 60 * 1000;
+    assert.deepEqual(JSON.parse((await invoke(middleware, '/stations')).body), body);
+    assert.equal(calls, count, `${mode} country response preserves the 45-minute cache`);
+  }
+});
+
+for (const priorityCountries of ['', 'IN']) {
+  test(`cold failures coalesce, bound mirrors and back off with priority countries ${priorityCountries || 'unset'}`, async () => {
+    let clock = Date.UTC(2026, 0, 1);
+    let calls = 0;
+    let offline = true;
+    const middleware = createProxy({
+      priorityCountries, now: () => clock,
+      fetchImpl: async (url) => {
+        calls++;
+        if (String(url).includes('/json/servers')) return responseJson([{ name: 'de1.api.radio-browser.info' }]);
+        if (offline) throw new Error('offline');
+        if (new URL(url).searchParams.has('countrycode')) return responseJson([]);
+        return responseJson(healthyRowsForQuery(url));
+      },
+    });
+    const responses = await Promise.all([invoke(middleware, '/stations'), invoke(middleware, '/stations')]);
+    assert.ok(responses.every((response) => response.status === 503));
+    const initial = calls;
+    assert.equal(initial, 1 + (priorityCountries ? 10 : 9) * 3, 'one discovery and at most three mirrors per query');
+    offline = false;
+    clock += 59_999;
+    assert.equal((await invoke(middleware, '/stations')).status, 503);
+    assert.equal(calls, initial);
+    clock += 2;
+    const recovered = await invoke(middleware, '/stations');
+    assert.equal(recovered.status, 200);
+    assert.equal(JSON.parse(recovered.body).degraded, false);
+    assert.ok(calls > initial);
+    const afterRecovery = calls;
+    await invoke(middleware, '/stations');
+    assert.equal(calls, afterRecovery);
+  });
+}
 
 test('case expansion is capped after tag normalization in the portable and server station path', () => {
   const row = normalizeRadioBrowserStation(station({tags: 'İ'.repeat(80) + ', NEWS__RADIO ,news-radio'}));
@@ -599,3 +784,29 @@ test('server structural rejections reach the client diagnostic without discardin
     radioLayer.destroy();
   }
 });
+
+
+test('country coverage retains valid rows and upstream rejection diagnostics in a cached healthy catalog', async () => {
+  let calls = 0;
+  const middleware = createProxy({
+    priorityCountries: 'IN',
+    fetchImpl: async (url) => {
+      calls++;
+      if (String(url).includes('/json/servers')) return responseJson([{ name: 'de1.api.radio-browser.info' }]);
+      if (new URL(url).searchParams.has('countrycode')) return responseJson([
+        station({ stationuuid: '60000000-0000-4000-8000-000000000001', countrycode: 'IN' }),
+        { name: 'missing required fields' },
+      ]);
+      return responseJson(healthyRowsForQuery(url));
+    },
+  });
+  const response = await invoke(middleware, '/stations');
+  const body = JSON.parse(response.body);
+  assert.equal(response.status, 200);
+  assert.equal(body.degraded, false);
+  assert.equal(body.rejectedStationCount, 1);
+  assert.deepEqual(body.coverage.priorityCountries, [{ countryCode: 'IN', succeeded: true, stationCount: 1 }]);
+  const count = calls;
+  assert.deepEqual(JSON.parse((await invoke(middleware, '/stations')).body), body);
+  assert.equal(calls, count);
+});

src/layers/military/ownership.test.mjs

@@ -28,6 +28,29 @@ function services() {
   };
 }
 
+// The application's own scene services, as src/app/layers/militaryFlights.js
+// composes them; only the surface samplers and registry are stubbed.
+async function sceneServices() {
+  return {
+    picking: await import('../../data/pickRegistry.js'),
+    sprites: await import('../../data/spriteOrder.js'),
+    trails: await import('../../data/trailRenderer.js'),
+    aircraftPresentation: await import('../../data/tr3bRegistry.js'),
+    camera: await import('../../data/trackedCamera.js'),
+    labels: await import('../../data/detectionDraw.js'),
+    geoid: await import('../../data/geoid.js'),
+    focus: await import('../../data/focusDeemphasis.js'),
+    readout: await import('../../data/trackedReadout.js'),
+    context: await import('../../data/contextStore.js'),
+    render: await import('../../renderGovernor.js'),
+    recession: await import('../../data/aircraftRecession.js'),
+    groundFloor: await import('../../data/groundFloor.js'),
+    groundSnap: await import('../../data/groundSnap.js'),
+    meshFloor: { sampleMeshFloorCells: () => {} },
+    militaryRegistry: { registerMilitaryIcaos: () => {} },
+  };
+}
+
 test('military layer instances isolate policy and restoration state without requesting a source', async () => {
   let requests = 0;
   const source = {
@@ -122,26 +145,7 @@ test('a newly seen military contact appears at its delayed position, not ahead o
   // the next fleet tick jumped it back.
   const Cesium = await import('cesium');
   const { RENDER_DELAY_SEC } = await import('./policy.js');
-  // The application's own scene services, as src/app/layers/militaryFlights.js
-  // composes them; only the surface samplers and registry are stubbed.
-  const supplied = {
-    picking: await import('../../data/pickRegistry.js'),
-    sprites: await import('../../data/spriteOrder.js'),
-    trails: await import('../../data/trailRenderer.js'),
-    aircraftPresentation: await import('../../data/tr3bRegistry.js'),
-    camera: await import('../../data/trackedCamera.js'),
-    labels: await import('../../data/detectionDraw.js'),
-    geoid: await import('../../data/geoid.js'),
-    focus: await import('../../data/focusDeemphasis.js'),
-    readout: await import('../../data/trackedReadout.js'),
-    context: await import('../../data/contextStore.js'),
-    render: await import('../../renderGovernor.js'),
-    recession: await import('../../data/aircraftRecession.js'),
-    groundFloor: await import('../../data/groundFloor.js'),
-    groundSnap: await import('../../data/groundSnap.js'),
-    meshFloor: { sampleMeshFloorCells: () => {} },
-    militaryRegistry: { registerMilitaryIcaos: () => {} },
-  };
+  const supplied = await sceneServices();
   const fixLon = -97.6;
   const fixLat = 30.3;
   const speedMps = 200;
@@ -213,6 +217,55 @@ test('a newly seen military contact appears at its delayed position, not ahead o
   );
 });
 
+test('a vanished military contact fades while position-less rows keep theirs', async () => {
+  // About a third of a live adsb.lol /v2/mil fetch is contacts without a
+  // position. Those rows marked every snapshot partial, so an aircraft that
+  // left the feed stayed at full opacity for five minutes.
+  const Cesium = await import('cesium');
+  const { readsbSnapshot } = await import('../../sources/live/aircraft.js');
+  const nowMs = Date.now();
+  const row = (hex, lon) => ({
+    hex,
+    lat: 30.3,
+    lon,
+    alt_baro: 20_000,
+    gs: 300,
+    track: 90,
+    seen_pos: 1,
+  });
+  const polls = [
+    [row('ae0001', -97.6), row('ae0002', -96.6), row('ae0003', -95.6)],
+    [row('ae0001', -97.5), { hex: 'ae0003' }],
+  ];
+  // Every poll also lists a contact that never has a position.
+  for (const poll of polls) poll.push({ hex: 'ae0009', type: 'mode_s' });
+  const layer = createMilitaryFlightLayer({
+    services: await sceneServices(),
+    source: {
+      label: 'Fixture aircraft',
+      getSnapshot: async () =>
+        readsbSnapshot(
+          { ac: polls.shift() },
+          { observedAtMs: nowMs, now: nowMs },
+        ),
+    },
+  });
+  const viewer = { camera: { positionCartographic: null }, scene: {} };
+  layer.testing._setTrackedMilitaryRefreshStateForTest({
+    icao24: 'seed00',
+    entity: null,
+    meta: { rawLat: 0, rawLon: 0, onGround: false },
+    billboard: { show: false, position: Cesium.Cartesian3.fromDegrees(0, 0) },
+    billboardCollection: { show: true, add: (options) => ({ ...options }) },
+    viewer,
+    tracked: false,
+  });
+  await layer.update(viewer);
+  await layer.update(viewer);
+  assert.equal(layer.findByQuery('ae0002')?.stale, true, 'vanished: fading');
+  assert.equal(layer.findByQuery('ae0003')?.stale, false, 'still listed');
+});
+
 test('voice context reads a track that rounds to north as 0°, not 360°', () => {
   const stubs = services();
   stubs.aircraftPresentation = { tr3bTypeLabel: (id, type) => type };

src/layers/military/records.js

@@ -187,9 +187,12 @@ export class MilitaryFlightRecords {
       fixEpochMs: aircraft.positionTimeMs ?? observedAtMs,
     };
   }
-  absence(id, { complete, likelyLanded }) {
+  absence(id, { complete, retainIds, likelyLanded }) {
+    // Partial admissions and position-less rows do not prove absence, but
+    // retention remains bounded; a likely-landed position-less contact
+    // still takes the landed limit.
     if (
-      !complete &&
+      (!complete || (retainIds?.has(id) && !likelyLanded)) &&
       Date.now() - (this.data.get(id)?.observedReceiptMs ?? 0) < 300000
     )
       return 'retain';

src/layers/military/records.test.mjs

@@ -99,6 +99,30 @@ test('military records keep bounded partial retention and release metadata only
   );
 });
 
+test('complete military snapshots age out vanished aircraft and retain position-less ones unless landed', () => {
+  const records = store();
+  for (const id of ['aaa001', 'aaa002', 'aaa003'])
+    records.receive(observation({ id, reference: id }), context());
+  // aaa001 and aaa003 are still listed without a position; aaa002 vanished.
+  const absent = (id, likelyLanded = false) =>
+    records.absence(id, {
+      complete: true,
+      retainIds: new Set(['aaa001', 'aaa003']),
+      likelyLanded,
+    });
+  assert.deepEqual(
+    [absent('aaa002'), absent('aaa002'), absent('aaa002')],
+    ['stale', 'stale', 'remove'],
+  );
+  assert.equal(absent('aaa001'), 'retain');
+  assert.equal(records.missingPolls.has('aaa001'), false);
+  // A landed contact that lost its position takes the landed fast-cull.
+  assert.equal(absent('aaa003', true), 'remove');
+  // Position-less retention stays bounded like partial admission.
+  records.data.get('aaa001').observedReceiptMs = Date.now() - 300001;
+  assert.equal(absent('aaa001'), 'stale');
+});
+
 test('military emergency status follows the latest poll instead of sticking', () => {
   const records = store();
   const first = records.receive(

src/layers/military/snapshotRenderer.js

@@ -259,6 +259,7 @@ export function createMilitarySnapshotRenderer({
       if (currentIcaos.has(icao24)) continue;
       const absence = records.absence(icao24, {
         complete: snapshot.complete,
+        retainIds: snapshot.retainIds,
         likelyLanded: queries._likelyLanded(icao24),
       });
       if (absence === 'retain') continue;

src/localRequestGate.mjs

@@ -3,13 +3,16 @@
  *
  * The credential panel has its own stricter gate (`admitKeySetupRequest` in
  * keySetupCore.mjs): loopback socket + local Host + exact Origin + JSON
- * Content-Type. The four endpoints here — `/api/realtime/token` (mints an
- * OpenAI Realtime token = spends money), `/api/openai/hud-summary` (OpenAI
- * spend), `/api/google/nearby-places` (Google spend), and
- * `/api/realtime/debug-log` (appends to a local JSONL) — were previously
- * ungated, so a hostile web page open in the same browser could reach them
- * cross-site: a `fetch` carries a foreign `Origin`, and an `<img>`/navigation
- * carries NO `Origin` at all but does carry `Sec-Fetch-Site: cross-site`.
+ * Content-Type. The endpoints behind this gate — `/api/realtime/token` (mints
+ * an OpenAI Realtime token = spends money), `/api/openai/hud-summary` (OpenAI
+ * spend), `/api/google/nearby-places` (Google spend),
+ * `/api/realtime/debug-log` (appends to a local JSONL) and the quota-bearing
+ * routes SECURITY.md lists with them — were previously ungated, so a hostile
+ * web page open in the same browser could reach them cross-site: a `fetch`
+ * carries a foreign `Origin`, and an `<img>`/navigation carries NO `Origin`
+ * at all but does carry `Sec-Fetch-Site: cross-site`. The keyless map routes
+ * (`/api/terrain/heights`, `/api/overpass`) reuse this core through
+ * `admitSameSiteKeyless` with the forwarding-header refusal switched off.
  *
  * This module is the pure core that refuses those shapes while keeping the
  * documented `HOST=0.0.0.0` LAN opt-in and non-browser loopback tools (the two

src/sources/live/aircraft.js

@@ -40,9 +40,11 @@ export function normalizeOpenSkyAircraft(row) {
   };
 }
 
+const readsbId = (row) => cleanText(row?.hex).toLowerCase();
+
 /** Normalize readsb observations. The caller supplies the source snapshot epoch. */
 export function normalizeReadsbAircraft(row, snapshotTimeMs) {
-  const id = cleanText(row?.hex).toLowerCase();
+  const id = readsbId(row);
   const latitude = finite(row?.lat),
     longitude = finite(row?.lon);
   if (!id || !coordinates(latitude, longitude)) return null;
@@ -129,6 +131,14 @@ export function openSkySnapshot(
   };
 }
 
+/**
+ * readsb omits lat/lon for a contact heard without a current position. Both
+ * must be absent; a half or unreadable position still marks the row malformed.
+ */
+function readsbUnpositionedId(row) {
+  return row?.lat == null && row?.lon == null ? readsbId(row) : '';
+}
+
 export function readsbSnapshot(
   payload,
   {
@@ -143,6 +153,7 @@ export function readsbSnapshot(
     payload?.ac,
     (row) => normalizeReadsbAircraft(row, observedAtMs),
     'adsb.lol',
+    readsbUnpositionedId,
   );
   const ageMs = observedAtMs == null ? null : Math.max(0, now - observedAtMs);
   return {

src/sources/live/contract.test.mjs

@@ -102,13 +102,34 @@ test('position-less OpenSky rows are seen, not missing; malformed rows stay inco
   assert.throws(() => openSkySnapshot({ states: [unpositioned] }), {
     code: 'malformed',
   });
-  // Military readsb admission keeps its existing semantics.
-  const military = readsbSnapshot(
-    { ac: [{ hex: 'abc123', lat: 30, lon: -97 }, { hex: 'def456' }] },
-    { observedAtMs: null },
-  );
-  assert.equal(military.complete, false);
-  assert.equal(military.retainIds.size, 0);
+});
+
+test('position-less readsb rows are seen, not missing; malformed rows stay incomplete', () => {
+  // readsb omits lat/lon for a contact heard without a current position; a
+  // live adsb.lol /v2/mil fetch had 82 such rows of 239.
+  const positioned = { hex: 'ae638d', lat: 20.3, lon: -158.5, seen_pos: 0.2 };
+  const heard = { hex: 'ADFAC3', type: 'mode_s', rr_lat: 19.9, seen: 24.2 };
+  const lastPosition = {
+    hex: '3b752d',
+    lastPosition: { lat: 45.3, lon: 5.98, seen_pos: 61.56 },
+  };
+  const read = (ac) => readsbSnapshot({ ac }, { observedAtMs: null });
+  const snapshot = read([positioned, heard, lastPosition]);
+  assert.equal(snapshot.records.length, 1);
+  assert.equal(snapshot.complete, true);
+  assert.deepEqual([...snapshot.retainIds], ['adfac3', '3b752d']);
+  assert.equal(snapshot.rejectedCount, 2);
+  // No usable id, only half a position, an unreadable one, or no row at all.
+  for (const row of [
+    { ...heard, hex: ' ' },
+    { ...heard, lat: 30 },
+    { ...heard, lon: -97 },
+    { ...heard, lat: 'x', lon: 'y' },
+    null,
+  ])
+    assert.equal(read([positioned, heard, row]).complete, false);
+  // A feed with no positions at all still cannot prove absence.
+  assert.throws(() => read([heard]), { code: 'malformed' });
 });
 
 test('readsb units and position/contact ages are normalized once against the source epoch', () => {
@@ -346,7 +367,8 @@ test('classification identities include positionless aircraft without admitting
     snapshot.records.map((record) => record.id),
     ['def456'],
   );
-  assert.equal(snapshot.complete, false);
+  assert.equal(snapshot.complete, true);
+  assert.deepEqual([...snapshot.retainIds], ['abc123']);
 });
 
 test('identity lookup validates its response and honors body-parse cancellation', async () => {

src/tooling/trackArrivalObservation.mjs

@@ -1,11 +1,27 @@
-/** A reveal must beat the one-second idle rotation refresh, regardless of FPS. */
+/**
+ * Wall-clock budget for EACH observed frame, regardless of FPS. Both the settle
+ * frame (measured from the forced moveEnd) and the reveal frame (measured from
+ * the settle frame that hid the contact) must land inside it, so neither can be
+ * repaired by the one-second idle rotation refresh before it is read. The
+ * refresh clock starts at the fleet tick (preRender) of the frame the budget is
+ * measured from, so the budget must leave room for that frame's own render
+ * time: half the refresh interval tolerates frames up to ~500 ms, and a ~300 ms
+ * software-rendered frame (headless SwiftShader) fits with margin.
+ */
 export const ARRIVAL_OBSERVATION_MS = 500;
 
+/** A measured rotation error at or above this fails the arrival check. */
+export const ARRIVAL_MAX_ERROR_DEG = 10;
+
+/** Attempts allowed when every earlier one timed out without a wrong angle. */
+export const ARRIVAL_MAX_ATTEMPTS = 2;
+
 /**
  * Observe the first completed moveEnd frame and the first subsequent reveal.
- * The deadline starts when moveEnd is forced, before its rotation baseline, so
- * waiting for either frame cannot let the one-second idle refresh mask a bug.
- * `read` snapshots visibility and rotation error against the current position.
+ * The settle deadline starts when moveEnd is forced, before its rotation
+ * baseline; the reveal deadline restarts at the settle frame, which is where
+ * the contact is hidden. `read` snapshots visibility and rotation error
+ * against the current position.
  */
 export function observeArrivalRotation({
   scene,
@@ -18,6 +34,7 @@ export function observeArrivalRotation({
 }) {
   return new Promise((resolve, reject) => {
     const startedAt = now();
+    let phaseStartedAt = startedAt;
     let moveEnd = null;
     let moveEndMs = null;
     let revealFrames = 0;
@@ -34,24 +51,42 @@ export function observeArrivalRotation({
       cleanup();
       resolve(result);
     };
-    const expired = () => ({
+    // A timeout keeps every angle it measured: the settle angle before a
+    // reveal timeout, and the angle on a late frame itself (a late frame is
+    // read first; the idle refresh can only repair an angle, so a wrong one
+    // seen late was wrong on time too). `arrivalAngleViolated` then makes the
+    // timeout final instead of retryable.
+    const expired = (late = null) => ({
       error: `arrival ${moveEnd ? 'reveal' : 'moveEnd'} observation exceeded ${ARRIVAL_OBSERVATION_MS} ms`,
       elapsedMs: now() - startedAt,
       moveEndMs,
+      ...(moveEnd
+        ? { dMoveEnd: moveEnd.rotationError }
+        : late
+          ? { dMoveEnd: late.rotationError }
+          : {}),
+      ...(moveEnd && late?.shown ? { dReveal: late.rotationError } : {}),
       flipFrame: -1,
     });
+    const armDeadline = () => {
+      clearTimer(timer);
+      timer = setTimer(() => finish(expired()), ARRIVAL_OBSERVATION_MS);
+    };
     remove = scene.postRender.addEventListener(() => {
       if (done) return;
       try {
-        const elapsedMs = now() - startedAt;
-        if (elapsedMs >= ARRIVAL_OBSERVATION_MS) {
-          finish(expired());
+        const at = now();
+        const elapsedMs = at - startedAt;
+        const sample = read();
+        if (at - phaseStartedAt >= ARRIVAL_OBSERVATION_MS) {
+          finish(expired(sample));
           return;
         }
-        const sample = read();
         if (moveEnd === null) {
           moveEnd = sample;
           moveEndMs = elapsedMs;
+          phaseStartedAt = at;
+          armDeadline();
           startReveal();
         } else {
           revealFrames++;
@@ -76,7 +111,7 @@ export function observeArrivalRotation({
         reject(error);
       }
     });
-    timer = setTimer(() => finish(expired()), ARRIVAL_OBSERVATION_MS);
+    armDeadline();
     try {
       startMoveEnd();
       scene.requestRender();
@@ -87,14 +122,51 @@ export function observeArrivalRotation({
   });
 }
 
+/**
+ * Whether an observation measured a rotation error over the threshold on any
+ * frame it captured, including the settle frame of a reveal that then timed
+ * out. Such an observation is a demonstrated failure, never inconclusive.
+ */
+export function arrivalAngleViolated(observation) {
+  const limit = (ARRIVAL_MAX_ERROR_DEG * Math.PI) / 180;
+  return [observation?.dMoveEnd, observation?.dReveal].some(
+    (error) => Number.isFinite(error) && error >= limit,
+  );
+}
+
+/**
+ * Observe arrival rotation, retrying only an inconclusive timeout. A wall-clock
+ * timeout means the frame landed where the idle refresh could already have
+ * repaired it, so it earns another attempt; an observation that measured a
+ * wrong angle (or succeeded) is final, so a later clean attempt can never
+ * replace it. `prepare` runs before every attempt; the result carries
+ * `attempts`.
+ */
+export async function observeArrivalRotationWithRetry({
+  prepare = async () => {},
+  observe = observeArrivalRotation,
+  maxAttempts = ARRIVAL_MAX_ATTEMPTS,
+  ...options
+}) {
+  let observed;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    await prepare();
+    observed = { ...(await observe(options)), attempts: attempt };
+    if (!observed.error || arrivalAngleViolated(observed)) break;
+  }
+  return observed;
+}
+
 /** Test the captured frames without retrying a bad first observation. */
 export function arrivalRotationPassed(observation) {
   return (
     !!observation &&
     !observation.error &&
     observation.shown === true &&
-    observation.elapsedMs < ARRIVAL_OBSERVATION_MS &&
-    (observation.dMoveEnd * 180) / Math.PI < 10 &&
-    (observation.dReveal * 180) / Math.PI < 10
+    observation.moveEndMs < ARRIVAL_OBSERVATION_MS &&
+    observation.revealMs < ARRIVAL_OBSERVATION_MS &&
+    Number.isFinite(observation.dMoveEnd) &&
+    Number.isFinite(observation.dReveal) &&
+    !arrivalAngleViolated(observation)
   );
 }

src/tooling/trackArrivalObservation.test.mjs

@@ -1,19 +1,23 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import * as arrivalModule from './trackArrivalObservation.mjs';
 import {
   ARRIVAL_OBSERVATION_MS,
+  arrivalAngleViolated,
   arrivalRotationPassed,
   observeArrivalRotation,
+  observeArrivalRotationWithRetry,
 } from './trackArrivalObservation.mjs';
 
-function fixture() {
+function fixture(start = observeArrivalRotation) {
   let time = 0;
   let state = { shown: true, rotationError: 0 };
   const listeners = new Set();
   const timers = new Map();
   let renders = 0;
   let moveEnds = 0;
-  const observation = observeArrivalRotation({
+  const observation = start({
     scene: {
       postRender: {
         addEventListener(listener) {
@@ -110,7 +114,8 @@ test('no reveal fails at a deadline before the one-second idle catch-up', async
   assert.equal(ARRIVAL_OBSERVATION_MS, 500);
   f.frame(8, { shown: true, rotationError: 0 });
   f.frame(480);
-  f.expire(500);
+  // The reveal budget is measured from the 8 ms settle frame.
+  f.expire(508);
   const result = await f.observation;
   assert.match(result.error, /reveal.*500 ms/);
   assert.equal(arrivalRotationPassed(result), false);
@@ -123,20 +128,46 @@ test('no reveal fails at a deadline before the one-second idle catch-up', async
 test('a late visible frame fails even if the timeout callback is delayed', async () => {
   const f = fixture();
   f.frame(8, { shown: true, rotationError: 0 });
-  f.frame(501, { shown: true, rotationError: 0 });
+  f.frame(509, { shown: true, rotationError: 0 });
   const result = await f.observation;
   assert.match(result.error, /reveal.*500 ms/);
-  assert.equal(result.elapsedMs, 501);
+  assert.equal(result.elapsedMs, 509);
   assert.equal(arrivalRotationPassed(result), false);
 });
 
-test('the deadline includes moveEnd setup rather than restarting when hidden', async () => {
+test('a slow software renderer passes when each frame stays inside its own budget', async () => {
+  // Headless SwiftShader frames run ~300 ms: settle lands at 300 ms and the
+  // reveal at 600 ms from moveEnd. Both stay inside the 1 s idle refresh.
   const f = fixture();
-  f.frame(400, { shown: true, rotationError: 0 });
+  f.frame(300, { shown: true, rotationError: 0 });
+  f.expire(500); // the settle frame re-armed the deadline to 800 ms
   f.frame(600, { shown: true, rotationError: 0 });
   const result = await f.observation;
-  assert.equal(result.moveEndMs, 400);
+  assert.equal(result.moveEndMs, 300);
+  assert.equal(result.revealMs, 300);
   assert.equal(result.elapsedMs, 600);
+  assert.equal(result.flipFrame, 1);
+  assert.equal(arrivalRotationPassed(result), true);
+  assert.equal(f.resources.timers, 0);
+});
+
+test('a settle frame later than its budget fails as a moveEnd timeout', async () => {
+  const f = fixture();
+  f.frame(500, { shown: true, rotationError: 0 });
+  const result = await f.observation;
+  assert.match(result.error, /moveEnd.*500 ms/);
+  assert.equal(result.moveEndMs, null);
+  assert.equal(arrivalRotationPassed(result), false);
+});
+
+test('a reveal later than its own budget fails even after a fast settle frame', async () => {
+  const f = fixture();
+  f.frame(400, { shown: true, rotationError: 0 });
+  f.frame(901, { shown: true, rotationError: 0 });
+  const result = await f.observation;
+  assert.match(result.error, /reveal.*500 ms/);
+  assert.equal(result.moveEndMs, 400);
+  assert.equal(result.elapsedMs, 901);
   assert.equal(arrivalRotationPassed(result), false);
 });
 
@@ -149,3 +180,195 @@ test('missing moveEnd frames fail without waiting for a render callback', async
   assert.equal(f.resources.listeners, 0);
   assert.equal(f.resources.timers, 0);
 });
+
+// Let a retry's next attempt register its postRender listener.
+const settle = () => new Promise((resolve) => setImmediate(resolve));
+
+function retryFixture(extra = {}) {
+  const counts = { prepares: 0 };
+  const f = fixture((options) =>
+    observeArrivalRotationWithRetry({
+      ...options,
+      ...extra,
+      async prepare() {
+        counts.prepares++;
+      },
+    }),
+  );
+  f.counts = counts;
+  return f;
+}
+
+test('a wrong settle angle followed by a reveal timeout is final, not retried into a pass', async () => {
+  const f = retryFixture();
+  await settle();
+  // 0.5 rad ≈ 29°: a real threshold violation on the settle frame.
+  f.frame(8, { shown: true, rotationError: 0.5 });
+  f.expire(508); // the reveal never comes inside its budget
+  await settle();
+  // An otherwise clean second attempt, which must never be started.
+  f.frame(516, { shown: true, rotationError: 0 });
+  f.frame(524, { shown: true, rotationError: 0 });
+  const result = await f.observation;
+  assert.match(result.error, /reveal.*500 ms/);
+  assert.equal(result.dMoveEnd, 0.5, 'the measured settle angle is kept');
+  assert.equal(arrivalAngleViolated(result), true);
+  assert.equal(result.attempts, 1);
+  assert.equal(f.counts.prepares, 1);
+  assert.equal(f.resources.moveEnds, 1);
+  assert.equal(arrivalRotationPassed(result), false);
+  assert.equal(f.resources.listeners, 0);
+  assert.equal(f.resources.timers, 0);
+});
+
+test('an inconclusive reveal timeout after a correct settle earns one more attempt', async () => {
+  const f = retryFixture();
+  await settle();
+  f.frame(8, { shown: true, rotationError: 0 });
+  f.expire(508);
+  await settle();
+  f.frame(516, { shown: true, rotationError: 0 });
+  f.frame(596, { shown: true, rotationError: 0 });
+  const result = await f.observation;
+  assert.equal(result.attempts, 2);
+  assert.equal(f.counts.prepares, 2);
+  assert.equal(f.resources.moveEnds, 2);
+  assert.equal(arrivalRotationPassed(result), true);
+});
+
+test('timeouts stop after the attempt limit and still fail', async () => {
+  const f = retryFixture();
+  await settle();
+  f.expire(500);
+  await settle();
+  f.expire(1000);
+  const result = await f.observation;
+  assert.match(result.error, /moveEnd.*500 ms/);
+  assert.equal(result.attempts, 2);
+  assert.equal(arrivalRotationPassed(result), false);
+  assert.equal(f.resources.listeners, 0);
+  assert.equal(f.resources.timers, 0);
+});
+
+test('a missing or non-finite angle never passes', () => {
+  const clean = {
+    shown: true,
+    moveEndMs: 8,
+    revealMs: 80,
+    dMoveEnd: 0,
+    dReveal: 0,
+  };
+  assert.equal(arrivalRotationPassed(clean), true);
+  for (const field of ['dMoveEnd', 'dReveal']) {
+    assert.equal(arrivalRotationPassed({ ...clean, [field]: NaN }), false);
+    assert.equal(
+      arrivalRotationPassed({ ...clean, [field]: undefined }),
+      false,
+    );
+  }
+});
+
+test('a wrong angle on a late reveal frame is final, not retried into a pass', async () => {
+  const f = retryFixture();
+  await settle();
+  f.frame(100, { shown: true, rotationError: 0 });
+  // Shown at 600 ms (500 ms after settle) still wearing the tampered nose.
+  f.frame(600, { shown: true, rotationError: 1.5 });
+  await settle();
+  f.frame(608, { shown: true, rotationError: 0 });
+  f.frame(688, { shown: true, rotationError: 0 });
+  const result = await f.observation;
+  assert.match(result.error, /reveal.*500 ms/);
+  assert.equal(result.dReveal, 1.5);
+  assert.equal(result.attempts, 1);
+  assert.equal(f.resources.moveEnds, 1);
+  assert.equal(arrivalRotationPassed(result), false);
+});
+
+test('a wrong angle on a late settle frame is final, not retried into a pass', async () => {
+  const f = retryFixture();
+  await settle();
+  f.frame(926, { shown: true, rotationError: 1.5 });
+  await settle();
+  f.frame(934, { shown: true, rotationError: 0 });
+  f.frame(1014, { shown: true, rotationError: 0 });
+  const result = await f.observation;
+  assert.match(result.error, /moveEnd.*500 ms/);
+  assert.equal(result.dMoveEnd, 1.5);
+  assert.equal(result.attempts, 1);
+  assert.equal(arrivalRotationPassed(result), false);
+});
+
+test('a late hidden reveal frame records no angle and stays retryable', async () => {
+  const f = retryFixture();
+  await settle();
+  f.frame(8, { shown: true, rotationError: 0 });
+  // Still hidden, still tampered: not a measured reveal angle.
+  f.frame(600, { shown: false });
+  const first = f.observation;
+  await settle();
+  f.frame(608, { shown: true, rotationError: 0 });
+  f.frame(688, { shown: true, rotationError: 0 });
+  const result = await first;
+  assert.equal(result.attempts, 2);
+  assert.equal(result.dReveal, 0);
+  assert.equal(arrivalRotationPassed(result), true);
+});
+
+test('a late frame with correct angles stays an inconclusive, retryable timeout', async () => {
+  const f = retryFixture();
+  await settle();
+  f.frame(926, { shown: true, rotationError: 0 });
+  await settle();
+  f.frame(934, { shown: true, rotationError: 0 });
+  f.frame(1014, { shown: true, rotationError: 0 });
+  const result = await f.observation;
+  assert.equal(result.attempts, 2);
+  assert.equal(arrivalRotationPassed(result), true);
+});
+
+test('a wrong first reveal on time is final: no retry', async () => {
+  const f = retryFixture();
+  await settle();
+  f.frame(8, { shown: true, rotationError: 0 });
+  f.frame(88, { shown: true, rotationError: 1.5 });
+  const result = await f.observation;
+  assert.equal(result.error, undefined);
+  assert.equal(result.attempts, 1);
+  assert.equal(f.resources.moveEnds, 1);
+  assert.equal(arrivalRotationPassed(result), false);
+});
+
+test('maxAttempts bounds inconclusive retries', async () => {
+  const f = retryFixture({ maxAttempts: 3 });
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    await settle();
+    f.expire(attempt * 500);
+  }
+  const result = await f.observation;
+  assert.equal(result.attempts, 3);
+  assert.equal(f.counts.prepares, 3);
+  assert.equal(arrivalRotationPassed(result), false);
+});
+
+test('the 10° limit is inclusive', () => {
+  const limit = Math.PI / 18;
+  assert.equal(arrivalAngleViolated({ dMoveEnd: limit }), true);
+  assert.equal(arrivalAngleViolated({ dReveal: limit * 0.999 }), false);
+});
+
+test('every name the track harness imports from this module is exported', () => {
+  const harness = readFileSync(
+    new URL('../../scripts/track-regression.mjs', import.meta.url),
+    'utf8',
+  );
+  const names = [
+    ...harness.matchAll(
+      /(?:import|const)\s*\{([^}]+)\}\s*(?:from\s*|=\s*await import\()[^;]*trackArrivalObservation\.mjs/g,
+    ),
+  ].flatMap((match) => match[1].split(',').map((name) => name.trim()));
+  assert.ok(names.includes('arrivalRotationPassed'));
+  assert.ok(names.includes('observeArrivalRotationWithRetry'));
+  for (const name of names)
+    assert.equal(typeof arrivalModule[name], 'function', name);
+});