@volter/twin-googlemaps 0.1.0

package/src/googlemaps-capabilities.ts

@@ -0,0 +1,766 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { projectResources } from '@volter/world-core';
+import { checkCapabilities, type CapabilityReport, type CapabilitySpec, verifyBoundary } from '@volter/world-tooling';
+import { pullGoogleMapsGeocodes,  } from './googlemaps-connector.ts';
+import { performPending } from './googlemaps-perform-harness.ts';
+import { handleGoogleMapsTwinRequest } from './googlemaps-twin.ts';
+
+type Body = Record<string, any>;
+type Step = { m: string; p: string; b?: unknown; readOnly?: boolean; headers?: Record<string, string> };
+
+async function withRoot(fn: (h: (step: Step) => Promise<{ status: number; body: unknown }>, root: string) => Promise<boolean>): Promise<boolean> {
+  const root = mkdtempSync(join(tmpdir(), 'googlemaps-cap-'));
+  const h = (step: Step) => handleGoogleMapsTwinRequest({
+    method: step.m,
+    path: step.p,
+    body: step.b === undefined ? undefined : JSON.stringify(step.b),
+    root,
+    readOnly: step.readOnly,
+    occurredAt: '1970-01-01T00:00:00.000Z',
+    ...(step.headers ? { headers: step.headers } : {}),
+  });
+  try {
+    return await verifyBoundary('googlemaps.withRoot', () => fn(h, root));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+const done = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier'], verify: CapabilitySpec['verify']): CapabilitySpec =>
+  ({ id, area, title, dimension, tier, expected: 'done', verify });
+const todo = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier']): CapabilitySpec =>
+  ({ id, area, title, dimension, tier, expected: 'todo' });
+
+export const GOOGLEMAPS_CAPABILITIES: CapabilitySpec[] = [
+  // ---- image bytes the twin does not serve yet ----
+  todo('googlemaps.staticmap.served_bytes', 'staticmap', 'Static Maps: serve deterministic placeholder image bytes at the /maps/api/staticmap URL (today only image metadata is returned)', 'api', 'common'),
+  todo('googlemaps.streetview.served_bytes', 'streetview', 'Street View: serve deterministic placeholder image bytes for a pano (today only metadata and a deterministic pano id are returned)', 'api', 'common'),
+  todo('googlemaps.places.photo_bytes', 'places', 'Place Photos: serve deterministic placeholder image bytes at the photo URL the twin returns (today the photo reference resolves to nothing)', 'api', 'common'),
+
+  // ---- Geocoding ----
+  done('googlemaps.geocode.ok', 'geocoding', 'Geocoding returns OK with a location for a known place', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/geocode/json?address=Los%20Angeles' });
+      const res = (r.body as Body).results?.[0];
+      return r.status === 200 && (r.body as Body).status === 'OK'
+        && res?.geometry?.location?.lat === 34.0522342 && res?.geometry?.location?.lng === -118.2436849
+        && res?.formatted_address === 'Los Angeles, CA, USA' && typeof res?.place_id === 'string';
+    })),
+  done('googlemaps.geocode.full_result_shape', 'geocoding', 'Geocoding result models the full real shape', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/geocode/json?address=1600%20Amphitheatre%20Pkwy%2C%20Mountain%20View' });
+      const res = (r.body as Body).results?.[0];
+      const comp = res?.address_components?.find((c: Body) => c.types?.includes('administrative_area_level_1'));
+      return r.status === 200
+        && Array.isArray(res?.address_components) && res.address_components.length > 0
+        && comp?.short_name === 'CA' && comp?.long_name === 'California'
+        && ['ROOFTOP', 'RANGE_INTERPOLATED', 'GEOMETRIC_CENTER', 'APPROXIMATE'].includes(res?.geometry?.location_type)
+        && typeof res?.geometry?.viewport?.northeast?.lat === 'number'
+        && Array.isArray(res?.types);
+    })),
+  done('googlemaps.geocode.zero_results', 'geocoding', 'Geocoding returns ZERO_RESULTS for an unmatched query', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/geocode/json?address=zzzznoresult-nowhere' });
+      return r.status === 200 && (r.body as Body).status === 'ZERO_RESULTS' && Array.isArray((r.body as Body).results) && (r.body as Body).results.length === 0;
+    })),
+  done('googlemaps.geocode.invalid_request', 'geocoding', 'Geocoding rejects a missing address with INVALID_REQUEST', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/geocode/json' });
+      return r.status === 200 && (r.body as Body).status === 'INVALID_REQUEST' && typeof (r.body as Body).error_message === 'string';
+    })),
+  done('googlemaps.geocode.by_place_id', 'geocoding', 'Geocoding by place_id resolves a known place', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/geocode/json?place_id=ChIJOwg_06VPwokRYv534QaPC8g' });
+      const res = (r.body as Body).results?.[0];
+      return (r.body as Body).status === 'OK' && res?.formatted_address === 'New York, NY, USA';
+    })),
+  done('googlemaps.geocode.place_id_not_found', 'geocoding', 'Geocoding by unknown place_id returns ZERO_RESULTS', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/geocode/json?place_id=ChIJ_does_not_exist' });
+      return (r.body as Body).status === 'ZERO_RESULTS';
+    })),
+  done('googlemaps.geocode.reverse', 'geocoding', 'Reverse geocoding resolves a lat/lng to an address', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/geocode/json?latlng=40.714224,-73.961452' });
+      const res = (r.body as Body).results?.[0];
+      return (r.body as Body).status === 'OK'
+        && res?.geometry?.location?.lat === 40.714224 && res?.geometry?.location?.lng === -73.961452
+        && res?.geometry?.location_type === 'APPROXIMATE' && typeof res?.formatted_address === 'string';
+    })),
+  done('googlemaps.geocode.reverse_invalid', 'geocoding', 'Reverse geocoding rejects an invalid latlng', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/geocode/json?latlng=not-a-coord' });
+      return (r.body as Body).status === 'INVALID_REQUEST';
+    })),
+  done('googlemaps.geocode.deterministic', 'geocoding', 'Geocoding is deterministic for arbitrary valid addresses', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const a = await h({ m: 'GET', p: '/maps/api/geocode/json?address=42%20Twin%20Street' });
+      const b = await h({ m: 'GET', p: '/maps/api/geocode/json?address=42%20Twin%20Street' });
+      const la = (a.body as Body).results?.[0]?.geometry?.location;
+      const lb = (b.body as Body).results?.[0]?.geometry?.location;
+      return (a.body as Body).status === 'OK' && la?.lat === lb?.lat && la?.lng === lb?.lng;
+    })),
+  done('googlemaps.geocode.stateful_override', 'geocoding', 'Geocoding reads connector-seeded override state', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const seeded = { address_components: [], formatted_address: 'Seeded HQ, Seedville', geometry: { location: { lat: 1.5, lng: 2.5 }, location_type: 'ROOFTOP', viewport: { northeast: { lat: 1.6, lng: 2.6 }, southwest: { lat: 1.4, lng: 2.4 } } }, place_id: 'ChIJseeded', types: ['premise'] };
+      await h({ m: 'POST', p: '/twin/geocode', b: { address: 'Seeded HQ', result: seeded } });
+      const r = await h({ m: 'GET', p: '/maps/api/geocode/json?address=Seeded%20HQ' });
+      const res = (r.body as Body).results?.[0];
+      return (r.body as Body).status === 'OK' && res?.formatted_address === 'Seeded HQ, Seedville' && res?.geometry?.location?.lat === 1.5;
+    })),
+
+  // ---- Distance Matrix ----
+  done('googlemaps.distancematrix.ok', 'distance_matrix', 'Distance Matrix returns OK rows with duration + distance', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/distancematrix/json?origins=34.05,-118.24&destinations=34.10,-118.30' });
+      const el = (r.body as Body).rows?.[0]?.elements?.[0];
+      return r.status === 200 && (r.body as Body).status === 'OK'
+        && el?.status === 'OK'
+        && typeof el?.duration?.value === 'number' && typeof el?.duration?.text === 'string'
+        && typeof el?.distance?.value === 'number' && typeof el?.distance?.text === 'string'
+        && Array.isArray((r.body as Body).origin_addresses) && Array.isArray((r.body as Body).destination_addresses);
+    })),
+  done('googlemaps.distancematrix.matrix', 'distance_matrix', 'Distance Matrix returns a full M×N matrix', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/distancematrix/json?origins=34.05,-118.24|40.71,-74.0&destinations=51.5,-0.12|35.68,139.65' });
+      const rows = (r.body as Body).rows;
+      return (r.body as Body).status === 'OK' && rows?.length === 2 && rows[0].elements.length === 2 && rows[1].elements.length === 2
+        && rows[0].elements[0].status === 'OK';
+    })),
+  done('googlemaps.distancematrix.element_not_found', 'distance_matrix', 'Distance Matrix marks an unresolvable element NOT_FOUND', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/distancematrix/json?origins=34.05,-118.24&destinations=nowhere-zero_results' });
+      return (r.body as Body).status === 'OK' && (r.body as Body).rows?.[0]?.elements?.[0]?.status === 'NOT_FOUND';
+    })),
+  done('googlemaps.distancematrix.invalid_request', 'distance_matrix', 'Distance Matrix rejects missing origins/destinations', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/distancematrix/json?origins=34.05,-118.24' });
+      return (r.body as Body).status === 'INVALID_REQUEST';
+    })),
+  done('googlemaps.distancematrix.units', 'distance_matrix', 'Distance Matrix honors metric vs imperial units', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const imp = await h({ m: 'GET', p: '/maps/api/distancematrix/json?origins=34.05,-118.24&destinations=34.50,-118.80' });
+      const met = await h({ m: 'GET', p: '/maps/api/distancematrix/json?origins=34.05,-118.24&destinations=34.50,-118.80&units=metric' });
+      const impText = (imp.body as Body).rows?.[0]?.elements?.[0]?.distance?.text as string;
+      const metText = (met.body as Body).rows?.[0]?.elements?.[0]?.distance?.text as string;
+      return /mi$/.test(impText) && /km$/.test(metText);
+    })),
+
+  // ---- Directions ----
+  done('googlemaps.directions.ok', 'directions', 'Directions returns OK with a route, legs and polyline', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/directions/json?origin=Los%20Angeles&destination=New%20York' });
+      const route = (r.body as Body).routes?.[0];
+      const leg = route?.legs?.[0];
+      return r.status === 200 && (r.body as Body).status === 'OK'
+        && typeof route?.overview_polyline?.points === 'string'
+        && typeof leg?.distance?.value === 'number' && typeof leg?.duration?.value === 'number'
+        && leg?.start_location && leg?.end_location && Array.isArray(leg?.steps) && leg.steps.length > 0;
+    })),
+  done('googlemaps.directions.geocoded_waypoints', 'directions', 'Directions includes geocoded_waypoints and bounds', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/directions/json?origin=London&destination=Tokyo' });
+      const wp = (r.body as Body).geocoded_waypoints;
+      const route = (r.body as Body).routes?.[0];
+      return (r.body as Body).status === 'OK' && Array.isArray(wp) && wp.length === 2 && wp[0].geocoder_status === 'OK'
+        && route?.bounds?.northeast && route?.copyrights && Array.isArray(route?.warnings);
+    })),
+  done('googlemaps.directions.zero_results', 'directions', 'Directions returns ZERO_RESULTS when no route exists', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/directions/json?origin=nowhere-zero_results&destination=London' });
+      return (r.body as Body).status === 'ZERO_RESULTS' && (r.body as Body).routes?.length === 0;
+    })),
+  done('googlemaps.directions.invalid_request', 'directions', 'Directions rejects a missing origin/destination', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/directions/json?origin=London' });
+      return (r.body as Body).status === 'INVALID_REQUEST';
+    })),
+
+  // ---- Places (legacy) ----
+  done('googlemaps.places.find_place', 'places', 'Find Place from Text returns a candidate', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/place/findplacefromtext/json?input=Tokyo&inputtype=textquery' });
+      const c = (r.body as Body).candidates?.[0];
+      return (r.body as Body).status === 'OK' && c?.place_id === 'ChIJ51cu8IcbXWARiRtXIothAS4' && c?.geometry?.location?.lat === 35.6761919;
+    })),
+  done('googlemaps.places.find_place_invalid', 'places', 'Find Place rejects a missing input', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/place/findplacefromtext/json?inputtype=textquery' });
+      return (r.body as Body).status === 'INVALID_REQUEST';
+    })),
+  done('googlemaps.places.text_search', 'places', 'Text Search returns results with rating', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/place/textsearch/json?query=London' });
+      const res = (r.body as Body).results?.[0];
+      return (r.body as Body).status === 'OK' && res?.place_id === 'ChIJdd4hrwug2EcRmSrV3Vo6llI' && typeof res?.rating === 'number';
+    })),
+  done('googlemaps.places.text_search_zero', 'places', 'Text Search returns ZERO_RESULTS for unmatched query', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/place/textsearch/json?query=zzzznoresult' });
+      return (r.body as Body).status === 'ZERO_RESULTS' && (r.body as Body).results?.length === 0;
+    })),
+  done('googlemaps.places.nearby_search', 'places', 'Nearby Search returns results near a location', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/place/nearbysearch/json?location=34.05,-118.24&radius=1500' });
+      const res = (r.body as Body).results?.[0];
+      return (r.body as Body).status === 'OK' && typeof res?.place_id === 'string' && typeof res?.vicinity === 'string';
+    })),
+  done('googlemaps.places.nearby_requires_radius', 'places', 'Nearby Search requires radius or rankby=distance', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const bad = await h({ m: 'GET', p: '/maps/api/place/nearbysearch/json?location=34.05,-118.24' });
+      const ok = await h({ m: 'GET', p: '/maps/api/place/nearbysearch/json?location=34.05,-118.24&rankby=distance' });
+      return (bad.body as Body).status === 'INVALID_REQUEST' && (ok.body as Body).status === 'OK';
+    })),
+  done('googlemaps.places.details', 'places', 'Place Details returns a place with components', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/place/details/json?place_id=ChIJj61dQgK6j4AR4GeTYWZsKWw' });
+      const res = (r.body as Body).result;
+      return (r.body as Body).status === 'OK' && res?.place_id === 'ChIJj61dQgK6j4AR4GeTYWZsKWw' && Array.isArray(res?.address_components) && typeof res?.url === 'string';
+    })),
+  done('googlemaps.places.details_not_found', 'places', 'Place Details returns NOT_FOUND for an unknown place', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/place/details/json?place_id=ChIJ_unknown' });
+      return (r.body as Body).status === 'NOT_FOUND';
+    })),
+  done('googlemaps.places.autocomplete', 'places', 'Autocomplete returns predictions for a prefix', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/place/autocomplete/json?input=Lon' });
+      const pred = (r.body as Body).predictions?.[0];
+      return (r.body as Body).status === 'OK' && typeof pred?.description === 'string' && typeof pred?.place_id === 'string'
+        && pred?.structured_formatting?.main_text === 'London';
+    })),
+  done('googlemaps.places.autocomplete_invalid', 'places', 'Autocomplete rejects a missing input', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/place/autocomplete/json' });
+      return (r.body as Body).status === 'INVALID_REQUEST';
+    })),
+  done('googlemaps.places.query_autocomplete', 'places', 'Query Autocomplete returns predictions', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/place/queryautocomplete/json?input=pizza' });
+      return (r.body as Body).status === 'OK' && typeof (r.body as Body).predictions?.[0]?.description === 'string';
+    })),
+
+  // ---- Places API (New) ----
+  done('googlemaps.places_new.text_search', 'places_new', 'Places API (New) searchText returns places', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/places:searchText', b: { textQuery: 'Tokyo' }, headers: { 'x-goog-api-key': 'k', 'x-goog-fieldmask': 'places.displayName,places.location' } });
+      const p = (r.body as Body).places?.[0];
+      return r.status === 200 && p?.displayName?.text === 'Tokyo' && p?.location?.latitude === 35.6761919 && p?.id === 'ChIJ51cu8IcbXWARiRtXIothAS4';
+    })),
+  done('googlemaps.places_new.text_search_validation', 'places_new', 'searchText rejects an empty textQuery with INVALID_ARGUMENT', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/places:searchText', b: {}, headers: { 'x-goog-api-key': 'k' } });
+      return r.status === 400 && (r.body as Body).error?.status === 'INVALID_ARGUMENT';
+    })),
+  done('googlemaps.places_new.text_search_zero', 'places_new', 'searchText returns an empty object for an unmatched query', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const zero = await h({ m: 'POST', p: '/v1/places:searchText', b: { textQuery: 'zzzznoresult' }, headers: { 'x-goog-api-key': 'k' } });
+      // a companion MATCHING query on the same handler must actually return place data —
+      // otherwise "places === undefined" for the zero-result query is indistinguishable from
+      // an always-empty saboteur response.
+      const found = await h({ m: 'POST', p: '/v1/places:searchText', b: { textQuery: 'coffee shop' }, headers: { 'x-goog-api-key': 'k' } });
+      const places = (found.body as Body).places as Body[] | undefined;
+      return zero.status === 200 && (zero.body as Body).places === undefined
+        && found.status === 200 && Array.isArray(places) && places.length > 0 && typeof places[0]?.id === 'string';
+    })),
+  done('googlemaps.places_new.nearby_search', 'places_new', 'Places API (New) searchNearby returns places', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/places:searchNearby', b: { locationRestriction: { circle: { center: { latitude: 34.05, longitude: -118.24 }, radius: 1000 } } }, headers: { 'x-goog-api-key': 'k' } });
+      return r.status === 200 && typeof (r.body as Body).places?.[0]?.id === 'string';
+    })),
+  done('googlemaps.places_new.nearby_validation', 'places_new', 'searchNearby rejects missing locationRestriction', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/places:searchNearby', b: {}, headers: { 'x-goog-api-key': 'k' } });
+      return r.status === 400 && (r.body as Body).error?.status === 'INVALID_ARGUMENT';
+    })),
+  done('googlemaps.places_new.details', 'places_new', 'Places API (New) GET place details', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/v1/places/ChIJOwg_06VPwokRYv534QaPC8g', headers: { 'x-goog-api-key': 'k', 'x-goog-fieldmask': 'displayName' } });
+      return r.status === 200 && (r.body as Body).id === 'ChIJOwg_06VPwokRYv534QaPC8g' && (r.body as Body).displayName?.text === 'New York' && (r.body as Body).name === 'places/ChIJOwg_06VPwokRYv534QaPC8g';
+    })),
+  done('googlemaps.places_new.details_not_found', 'places_new', 'Places API (New) details returns 404 for unknown place', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/v1/places/ChIJ_unknown', headers: { 'x-goog-api-key': 'k' } });
+      return r.status === 404 && (r.body as Body).error?.status === 'NOT_FOUND';
+    })),
+  done('googlemaps.places_new.autocomplete', 'places_new', 'Places API (New) autocomplete returns suggestions', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/places:autocomplete', b: { input: 'Lon' }, headers: { 'x-goog-api-key': 'k' } });
+      const s = (r.body as Body).suggestions?.[0]?.placePrediction;
+      return r.status === 200 && s?.placeId === 'ChIJdd4hrwug2EcRmSrV3Vo6llI' && s?.structuredFormat?.mainText?.text === 'London';
+    })),
+
+  // ---- Roads ----
+  done('googlemaps.roads.snap_to_roads', 'roads', 'Roads snapToRoads returns snapped points', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/v1/snapToRoads?path=34.05,-118.24|34.06,-118.25', headers: { 'x-goog-api-key': 'k' } });
+      const sp = (r.body as Body).snappedPoints;
+      return r.status === 200 && sp?.length === 2 && sp[0].location.latitude === 34.05 && sp[0].originalIndex === 0 && typeof sp[0].placeId === 'string';
+    })),
+  done('googlemaps.roads.snap_invalid', 'roads', 'Roads snapToRoads rejects a missing path with 400', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/v1/snapToRoads', headers: { 'x-goog-api-key': 'k' } });
+      return r.status === 400 && (r.body as Body).error?.status === 'INVALID_ARGUMENT';
+    })),
+  done('googlemaps.roads.nearest_roads', 'roads', 'Roads nearestRoads returns snapped points', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/v1/nearestRoads?points=60.17,24.94|60.17,24.95', headers: { 'x-goog-api-key': 'k' } });
+      return r.status === 200 && (r.body as Body).snappedPoints?.length === 2;
+    })),
+  done('googlemaps.roads.speed_limits', 'roads', 'Roads speedLimits returns speed limits', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/v1/speedLimits?path=34.05,-118.24', headers: { 'x-goog-api-key': 'k' } });
+      const sl = (r.body as Body).speedLimits?.[0];
+      return r.status === 200 && typeof sl?.speedLimit === 'number' && sl?.units === 'KPH' && typeof sl?.placeId === 'string';
+    })),
+
+  // ---- Time Zone / Elevation / Geolocation ----
+  done('googlemaps.timezone.ok', 'timezone', 'Time Zone returns a faithful tz envelope', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/timezone/json?location=34.05,-118.24&timestamp=1331161200' });
+      return r.status === 200 && (r.body as Body).status === 'OK'
+        && typeof (r.body as Body).timeZoneId === 'string' && typeof (r.body as Body).rawOffset === 'number'
+        && typeof (r.body as Body).timeZoneName === 'string';
+    })),
+  done('googlemaps.timezone.invalid', 'timezone', 'Time Zone rejects missing location/timestamp', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/timezone/json?location=34.05,-118.24' });
+      return (r.body as Body).status === 'INVALID_REQUEST';
+    })),
+  done('googlemaps.elevation.locations', 'elevation', 'Elevation returns elevation for locations', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/elevation/json?locations=39.73,-104.98|36.45,-116.86' });
+      const res = (r.body as Body).results;
+      return (r.body as Body).status === 'OK' && res?.length === 2 && typeof res[0].elevation === 'number' && typeof res[0].resolution === 'number';
+    })),
+  done('googlemaps.elevation.path_samples', 'elevation', 'Elevation path sampling honors `samples`', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const ok = await h({ m: 'GET', p: '/maps/api/elevation/json?path=36.578,-118.291|36.23,-116.83&samples=3' });
+      const bad = await h({ m: 'GET', p: '/maps/api/elevation/json?path=36.578,-118.291' });
+      return (ok.body as Body).status === 'OK' && (bad.body as Body).status === 'INVALID_REQUEST';
+    })),
+  done('googlemaps.elevation.invalid', 'elevation', 'Elevation rejects missing locations/path', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/elevation/json' });
+      return (r.body as Body).status === 'INVALID_REQUEST';
+    })),
+  done('googlemaps.geolocation.ok', 'geolocation', 'Geolocation returns a location + accuracy', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/maps/api/geolocation/json', b: { considerIp: true } });
+      return r.status === 200 && typeof (r.body as Body).location?.lat === 'number' && typeof (r.body as Body).accuracy === 'number';
+    })),
+  done('googlemaps.geolocation.deterministic', 'geolocation', 'Geolocation is deterministic for identical input', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const a = await h({ m: 'POST', p: '/maps/api/geolocation/json', b: { wifiAccessPoints: [{ macAddress: '00:11' }] } });
+      const b = await h({ m: 'POST', p: '/maps/api/geolocation/json', b: { wifiAccessPoints: [{ macAddress: '00:11' }] } });
+      // a DIFFERENT input must yield a DIFFERENT location — otherwise "same lat for same
+      // input" is trivially true of an always-undefined saboteur response too.
+      const c = await h({ m: 'POST', p: '/maps/api/geolocation/json', b: { wifiAccessPoints: [{ macAddress: 'ff:ee' }] } });
+      const latA = (a.body as Body).location?.lat;
+      return typeof latA === 'number' && typeof (a.body as Body).location?.lng === 'number' && typeof (a.body as Body).accuracy === 'number'
+        && latA === (b.body as Body).location?.lat
+        && latA !== (c.body as Body).location?.lat;
+    })),
+
+  // ---- Address Validation ----
+  done('googlemaps.address_validation.ok', 'address_validation', 'Address Validation returns a verdict + geocode', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1:validateAddress', b: { address: { addressLines: ['1600 Amphitheatre Pkwy, Mountain View'] } }, headers: { 'x-goog-api-key': 'k' } });
+      const result = (r.body as Body).result;
+      return r.status === 200 && result?.verdict?.addressComplete === true
+        && typeof result?.geocode?.location?.latitude === 'number' && typeof (r.body as Body).responseId === 'string';
+    })),
+  done('googlemaps.address_validation.unconfirmed', 'address_validation', 'Address Validation flags unconfirmed components', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1:validateAddress', b: { address: { addressLines: ['some unknown route 9999'] } }, headers: { 'x-goog-api-key': 'k' } });
+      return r.status === 200 && (r.body as Body).result?.verdict?.hasUnconfirmedComponents === true;
+    })),
+  done('googlemaps.address_validation.invalid', 'address_validation', 'Address Validation rejects empty addressLines', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1:validateAddress', b: { address: { addressLines: [] } }, headers: { 'x-goog-api-key': 'k' } });
+      return r.status === 400 && (r.body as Body).error?.status === 'INVALID_ARGUMENT';
+    })),
+
+  // ---- Static Maps / Street View ----
+  done('googlemaps.staticmap.metadata', 'staticmap', 'Static Maps returns image metadata for a valid request', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/staticmap?center=34.05,-118.24&zoom=12&size=600x400' });
+      return r.status === 200 && (r.body as Body).contentType === 'image/png' && (r.body as Body).size === '600x400';
+    })),
+  done('googlemaps.staticmap.invalid', 'staticmap', 'Static Maps rejects a missing size', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/staticmap?center=34.05,-118.24' });
+      return r.status === 400 && (r.body as Body).error?.status === 'INVALID_ARGUMENT';
+    })),
+  done('googlemaps.streetview.metadata_endpoint', 'streetview', 'Street View metadata returns OK with a pano id', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/streetview/metadata?location=34.05,-118.24' });
+      return r.status === 200 && (r.body as Body).status === 'OK' && typeof (r.body as Body).pano_id === 'string';
+    })),
+  done('googlemaps.streetview.metadata_zero', 'streetview', 'Street View metadata returns ZERO_RESULTS where no pano exists', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/streetview/metadata?location=zzzznoresult-nowhere' });
+      return (r.body as Body).status === 'ZERO_RESULTS';
+    })),
+  done('googlemaps.streetview.image_metadata', 'streetview', 'Street View image endpoint validates size', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const ok = await h({ m: 'GET', p: '/maps/api/streetview?location=34.05,-118.24&size=600x400' });
+      const bad = await h({ m: 'GET', p: '/maps/api/streetview?location=34.05,-118.24' });
+      return (ok.body as Body).contentType === 'image/jpeg' && bad.status === 400;
+    })),
+
+  // ---- Auth / errors / honesty ----
+  done('googlemaps.auth.request_denied', 'errors', 'Missing API key yields REQUEST_DENIED on a legacy service', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/geocode/json?address=Los%20Angeles', headers: {} });
+      return r.status === 200 && (r.body as Body).status === 'REQUEST_DENIED' && typeof (r.body as Body).error_message === 'string';
+    })),
+  done('googlemaps.auth.valid_key', 'errors', 'A valid key passes the gate', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/geocode/json?address=Los%20Angeles&key=AIzaTwinKey', headers: {} });
+      return r.status === 200 && (r.body as Body).status === 'OK';
+    })),
+  done('googlemaps.auth.over_query_limit', 'errors', 'Sentinel key yields OVER_QUERY_LIMIT', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/geocode/json?address=Los%20Angeles&key=over-query-limit', headers: {} });
+      return (r.body as Body).status === 'OVER_QUERY_LIMIT';
+    })),
+  done('googlemaps.auth.over_daily_limit', 'errors', 'Sentinel key yields OVER_DAILY_LIMIT', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/geocode/json?address=Los%20Angeles&key=over-daily-limit', headers: {} });
+      return (r.body as Body).status === 'OVER_DAILY_LIMIT';
+    })),
+  done('googlemaps.auth.v1_permission_denied', 'errors', 'Missing key yields a 403 PERMISSION_DENIED on a v1 service', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/places:searchText', b: { textQuery: 'Tokyo' }, headers: {} });
+      return r.status === 403 && (r.body as Body).error?.status === 'PERMISSION_DENIED';
+    })),
+  done('googlemaps.honesty.unmodeled_legacy', 'honesty', 'Unmodeled legacy op fails like the vendor (INVALID_REQUEST)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/unknown/json?key=k' });
+      return (r.body as Body).status === 'INVALID_REQUEST';
+    })),
+  done('googlemaps.honesty.unmodeled_v1', 'honesty', 'Unmodeled v1 op fails with a 404 NOT_FOUND', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/v1/unknownThing', headers: { 'x-goog-api-key': 'k' } });
+      return r.status === 404 && (r.body as Body).error?.status === 'NOT_FOUND';
+    })),
+  done('googlemaps.honesty.readonly_rejects_seed', 'honesty', 'readOnly forbids twin write endpoints (405)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/twin/geocode', b: { address: 'x', result: {} }, readOnly: true });
+      return r.status === 405;
+    })),
+  done('googlemaps.audit.request_logging', 'audit', 'Local audit log records requests; read-only is not logged', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      await h({ m: 'GET', p: '/maps/api/geocode/json?address=Los%20Angeles' });
+      await h({ m: 'GET', p: '/maps/api/directions/json?origin=London&destination=Tokyo' });
+      await h({ m: 'GET', p: '/maps/api/geocode/json?address=Los%20Angeles', readOnly: true });
+      const log = await h({ m: 'GET', p: '/twin/audit' });
+      const entries = (log.body as Body).entries as Body[] | undefined;
+      return entries?.length === 2 && entries.some((e) => e.api === 'geocode' && e.status === 'OK') && entries.some((e) => e.api === 'directions');
+    })),
+
+  // ---- Connector ----
+  done('googlemaps.connector.pull', 'connector', 'Connector pulls geocode overrides through an injected client idempotently', 'connector', 'common', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'googlemaps-conn-'));
+    try {
+      const execute = async () => ({ status: 200, data: { status: 'OK', results: [{ formatted_address: 'Pulled, Earth', geometry: { location: { lat: 9, lng: 9 } } }] } });
+      const n1 = await pullGoogleMapsGeocodes(execute, ['Pulled Place'], { root });
+      await pullGoogleMapsGeocodes(execute, ['Pulled Place'], { root });
+      const rows = projectResources('googlemaps', root).filter((r) => r.type === 'geocode');
+      return n1 === 1 && rows.length === 1 && (rows[0] as Body).result?.formatted_address === 'Pulled, Earth';
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }),
+  done('googlemaps.connector.push', 'connector', 'Connector pushes pending geocode seeds through an injected client idempotently', 'connector', 'common', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'googlemaps-conn-'));
+    try {
+      // A local seed creates a pending geocode.upsert action over a forked base.
+      const { applyTwinWrite } = await import('@volter/world-core');
+      await applyTwinWrite('googlemaps', {
+        operation: 'geocode.upsert',
+        subjectType: 'geocode',
+        subjectId: 'geocode_pushcap',
+        fields: { id: 'geocode_pushcap', normalized: 'push hq', address: 'Push HQ', result: { formatted_address: 'Push HQ' } },
+        occurredAt: '1970-01-01T00:00:00.000Z',
+        actor: { kind: 'system' },
+      }, root);
+      const { pendingActions } = await import('@volter/world-core');
+      const paths: string[] = [];
+      const first = await performPending(async (req) => { paths.push(req.path); return { status: 200, data: {} }; }, { root });
+      const second = await performPending(async () => ({ status: 200, data: {} }), { root });
+      return first === 1 && second === 0 && pendingActions('googlemaps', root).length === 0 && paths[0] === '/twin/geocode';
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }),
+
+  // ---- Geocoding niche ----
+  done('googlemaps.geocode.plus_codes', 'geocoding', 'Plus Codes (global_code / compound_code) in geocode results', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/geocode/json?address=Los%20Angeles' });
+      const pc = (r.body as Body).results?.[0]?.plus_code;
+      return (r.body as Body).status === 'OK'
+        && typeof pc?.global_code === 'string' && /\+/.test(pc.global_code) && pc.global_code.length >= 8
+        && typeof pc?.compound_code === 'string' && pc.compound_code.includes('Los Angeles');
+    })),
+  done('googlemaps.geocode.components_filter', 'geocoding', 'Geocoding components filter (country constraint → ZERO_RESULTS on mismatch)', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const ok = await h({ m: 'GET', p: '/maps/api/geocode/json?address=London&components=country:GB' });
+      const miss = await h({ m: 'GET', p: '/maps/api/geocode/json?address=London&components=country:JP' });
+      return (ok.body as Body).status === 'OK' && (ok.body as Body).results?.[0]?.place_id === 'ChIJdd4hrwug2EcRmSrV3Vo6llI'
+        && (miss.body as Body).status === 'ZERO_RESULTS' && (miss.body as Body).results?.length === 0;
+    })),
+  done('googlemaps.geocode.region_biasing', 'geocoding', 'Geocoding bounds biasing snaps a synthesized result into the requested viewport', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      // A non-canned address synthesizes a location; bounds must steer it into range.
+      const free = await h({ m: 'GET', p: '/maps/api/geocode/json?address=42%20Twin%20Street' });
+      const freeLoc = (free.body as Body).results?.[0]?.geometry?.location;
+      const biased = await h({ m: 'GET', p: '/maps/api/geocode/json?address=42%20Twin%20Street&region=us&bounds=40.0,-75.0|41.0,-73.0' });
+      const bLoc = (biased.body as Body).results?.[0]?.geometry?.location;
+      // Free location is somewhere on the globe; biased one is clamped into the box.
+      return (biased.body as Body).status === 'OK'
+        && bLoc?.lat >= 40.0 && bLoc?.lat <= 41.0 && bLoc?.lng >= -75.0 && bLoc?.lng <= -73.0
+        && !(freeLoc?.lat >= 40.0 && freeLoc?.lat <= 41.0 && freeLoc?.lng >= -75.0 && freeLoc?.lng <= -73.0);
+    })),
+  done('googlemaps.geocode.language', 'geocoding', 'Geocoding language parameter localizes formatted_address', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const en = await h({ m: 'GET', p: '/maps/api/geocode/json?address=Tokyo&language=en' });
+      const ja = await h({ m: 'GET', p: '/maps/api/geocode/json?address=Tokyo&language=ja' });
+      const enAddr = (en.body as Body).results?.[0]?.formatted_address;
+      const jaAddr = (ja.body as Body).results?.[0]?.formatted_address;
+      return enAddr === 'Tokyo, Japan' && jaAddr === '日本、東京都' && jaAddr !== enAddr
+        && (en.body as Body).results?.[0]?.place_id === (ja.body as Body).results?.[0]?.place_id;
+    })),
+
+  // ---- Directions ----
+  done('googlemaps.directions.waypoints', 'directions', 'Directions waypoints add legs; optimize:true reorders waypoint_order', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const plain = await h({ m: 'GET', p: '/maps/api/directions/json?origin=Los%20Angeles&destination=New%20York&waypoints=Tokyo|London' });
+      const pr = (plain.body as Body).routes?.[0];
+      const opt = await h({ m: 'GET', p: '/maps/api/directions/json?origin=Los%20Angeles&destination=New%20York&waypoints=optimize:true|Tokyo|London' });
+      const or = (opt.body as Body).routes?.[0];
+      return (plain.body as Body).status === 'OK' && pr?.legs?.length === 3 && JSON.stringify(pr.waypoint_order) === '[0,1]'
+        && or?.legs?.length === 3 && Array.isArray(or.waypoint_order) && or.waypoint_order.length === 2
+        && JSON.stringify(or.waypoint_order) !== '[0,1]';
+    })),
+  done('googlemaps.directions.alternatives', 'directions', 'Directions alternatives=true returns multiple distinct routes', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/directions/json?origin=Los%20Angeles&destination=New%20York&alternatives=true' });
+      const routes = (r.body as Body).routes;
+      return (r.body as Body).status === 'OK' && routes?.length === 2
+        && routes[1].legs[0].duration.value > routes[0].legs[0].duration.value;
+    })),
+  done('googlemaps.directions.travel_modes', 'directions', 'Directions walking/bicycling/transit modes scale duration + set travel_mode', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const drive = await h({ m: 'GET', p: '/maps/api/directions/json?origin=Los%20Angeles&destination=New%20York&mode=driving' });
+      const walk = await h({ m: 'GET', p: '/maps/api/directions/json?origin=Los%20Angeles&destination=New%20York&mode=walking' });
+      const dStep = (drive.body as Body).routes?.[0]?.legs?.[0]?.steps?.[0];
+      const wStep = (walk.body as Body).routes?.[0]?.legs?.[0]?.steps?.[0];
+      return dStep?.travel_mode === 'DRIVING' && wStep?.travel_mode === 'WALKING'
+        && wStep.duration.value > dStep.duration.value;
+    })),
+  done('googlemaps.directions.departure_traffic', 'directions', 'Directions departure_time adds duration_in_traffic to each leg', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/directions/json?origin=Los%20Angeles&destination=New%20York&departure_time=now' });
+      const leg = (r.body as Body).routes?.[0]?.legs?.[0];
+      return (r.body as Body).status === 'OK' && typeof leg?.duration_in_traffic?.value === 'number'
+        && leg.duration_in_traffic.value > leg.duration.value && typeof leg.duration_in_traffic.text === 'string';
+    })),
+  done('googlemaps.directions.avoid', 'directions', 'Directions avoid=tolls|highways records route warnings', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/directions/json?origin=Los%20Angeles&destination=New%20York&avoid=tolls|ferries' });
+      const w = (r.body as Body).routes?.[0]?.warnings;
+      return (r.body as Body).status === 'OK' && Array.isArray(w) && w.some((m: string) => /tolls/.test(m)) && w.some((m: string) => /ferries/.test(m));
+    })),
+  done('googlemaps.directions.transit_details', 'directions', 'Directions transit mode adds transit_details (line, stops)', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/directions/json?origin=London&destination=Tokyo&mode=transit' });
+      const td = (r.body as Body).routes?.[0]?.legs?.[0]?.steps?.[0]?.transit_details;
+      return (r.body as Body).status === 'OK' && td?.line?.vehicle?.type === 'HEAVY_RAIL'
+        && typeof td?.num_stops === 'number' && typeof td?.departure_stop?.name === 'string';
+    })),
+
+  // ---- Distance Matrix ----
+  done('googlemaps.distancematrix.travel_modes', 'distance_matrix', 'Distance Matrix travel modes + departure_time traffic', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const walk = await h({ m: 'GET', p: '/maps/api/distancematrix/json?origins=34.05,-118.24&destinations=34.50,-118.80&mode=walking' });
+      const drive = await h({ m: 'GET', p: '/maps/api/distancematrix/json?origins=34.05,-118.24&destinations=34.50,-118.80&mode=driving&departure_time=now' });
+      const wEl = (walk.body as Body).rows?.[0]?.elements?.[0];
+      const dEl = (drive.body as Body).rows?.[0]?.elements?.[0];
+      return wEl?.status === 'OK' && dEl?.status === 'OK'
+        && wEl.duration.value > dEl.duration.value
+        && typeof dEl.duration_in_traffic?.value === 'number' && dEl.duration_in_traffic.value > dEl.duration.value;
+    })),
+  done('googlemaps.distancematrix.max_elements', 'distance_matrix', 'Distance Matrix enforces MAX_ELEMENTS_EXCEEDED over 100 elements', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const origins = Array.from({ length: 11 }, (_v, i) => `34.${i},-118.2`).join('|');
+      const dests = Array.from({ length: 11 }, (_v, i) => `35.${i},-118.3`).join('|');
+      const r = await h({ m: 'GET', p: `/maps/api/distancematrix/json?origins=${origins}&destinations=${dests}` });
+      const ok = await h({ m: 'GET', p: '/maps/api/distancematrix/json?origins=34.05,-118.24&destinations=34.50,-118.80' });
+      return (r.body as Body).status === 'MAX_ELEMENTS_EXCEEDED' && (ok.body as Body).status === 'OK';
+    })),
+
+  // ---- Places (legacy) ----
+  done('googlemaps.places.photos', 'places', 'Place Details exposes photo_reference; Place Photo endpoint returns metadata', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const d = await h({ m: 'GET', p: '/maps/api/place/details/json?place_id=ChIJj61dQgK6j4AR4GeTYWZsKWw&fields=photos' });
+      const ref = (d.body as Body).result?.photos?.[0]?.photo_reference;
+      const photo = await h({ m: 'GET', p: `/maps/api/place/photo?maxwidth=400&photo_reference=${ref}` });
+      const bad = await h({ m: 'GET', p: '/maps/api/place/photo?photo_reference=x' });
+      return typeof ref === 'string' && (photo.body as Body).contentType === 'image/jpeg' && (photo.body as Body).photo_reference === ref
+        && (bad.body as Body).status === 'INVALID_REQUEST';
+    })),
+  done('googlemaps.places.pagination', 'places', 'Text/Nearby Search next_page_token paginates deterministically', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const p1 = await h({ m: 'GET', p: '/maps/api/place/textsearch/json?query=London' });
+      const tok = (p1.body as Body).next_page_token as string;
+      const p2 = await h({ m: 'GET', p: `/maps/api/place/textsearch/json?pagetoken=${encodeURIComponent(tok)}` });
+      return (p1.body as Body).status === 'OK' && (p1.body as Body).results?.length === 20 && typeof tok === 'string'
+        && (p2.body as Body).results?.length === 3
+        && (p1.body as Body).results[0].place_id !== (p2.body as Body).results[0].place_id;
+    })),
+  done('googlemaps.places.opening_hours', 'places', 'Place Details returns opening_hours / current_opening_hours', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/place/details/json?place_id=ChIJj61dQgK6j4AR4GeTYWZsKWw' });
+      const oh = (r.body as Body).result?.opening_hours;
+      return (r.body as Body).status === 'OK' && oh?.open_now === true
+        && Array.isArray(oh?.weekday_text) && oh.weekday_text.length === 7
+        && oh.periods?.[0]?.open?.time === '0900' && (r.body as Body).result?.current_opening_hours?.open_now === true;
+    })),
+  done('googlemaps.places.reviews', 'places', 'Place Details returns reviews + editorial_summary', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/place/details/json?place_id=ChIJj61dQgK6j4AR4GeTYWZsKWw' });
+      const rev = (r.body as Body).result?.reviews?.[0];
+      return (r.body as Body).status === 'OK' && typeof rev?.author_name === 'string' && typeof rev?.rating === 'number'
+        && typeof rev?.text === 'string' && typeof (r.body as Body).result?.editorial_summary?.overview === 'string';
+    })),
+  done('googlemaps.places.field_masks', 'places', 'Place Details `fields` masks the response to requested fields only', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/place/details/json?place_id=ChIJj61dQgK6j4AR4GeTYWZsKWw&fields=place_id,name' });
+      const res = (r.body as Body).result;
+      return (r.body as Body).status === 'OK' && res?.place_id === 'ChIJj61dQgK6j4AR4GeTYWZsKWw' && res?.name === 'Mountain View'
+        && res?.formatted_address === undefined && res?.reviews === undefined && Object.keys(res).length === 2;
+    })),
+
+  // ---- Places API (New) ----
+  done('googlemaps.places_new.field_mask_enforcement', 'places_new', 'X-Goog-FieldMask restricts searchText / details response fields', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const s = await h({ m: 'POST', p: '/v1/places:searchText', b: { textQuery: 'Tokyo' }, headers: { 'x-goog-api-key': 'k', 'x-goog-fieldmask': 'places.id,places.displayName' } });
+      const pl = (s.body as Body).places?.[0];
+      const d = await h({ m: 'GET', p: '/v1/places/ChIJOwg_06VPwokRYv534QaPC8g', headers: { 'x-goog-api-key': 'k', 'x-goog-fieldmask': 'id' } });
+      return pl?.id === 'ChIJ51cu8IcbXWARiRtXIothAS4' && pl?.displayName?.text === 'Tokyo' && pl?.location === undefined && pl?.types === undefined
+        && (d.body as Body).id === 'ChIJOwg_06VPwokRYv534QaPC8g' && (d.body as Body).displayName === undefined;
+    })),
+  done('googlemaps.places_new.photos', 'places_new', 'Places API (New) place exposes photos; media endpoint returns photoUri', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const d = await h({ m: 'GET', p: '/v1/places/ChIJOwg_06VPwokRYv534QaPC8g', headers: { 'x-goog-api-key': 'k', 'x-goog-fieldmask': 'photos' } });
+      const name = (d.body as Body).photos?.[0]?.name as string;
+      const ref = name.split('/').pop();
+      const media = await h({ m: 'GET', p: `/v1/places/ChIJOwg_06VPwokRYv534QaPC8g/photos/${ref}/media?maxWidthPx=400`, headers: { 'x-goog-api-key': 'k' } });
+      const bad = await h({ m: 'GET', p: `/v1/places/ChIJOwg_06VPwokRYv534QaPC8g/photos/${ref}/media`, headers: { 'x-goog-api-key': 'k' } });
+      return typeof name === 'string' && typeof (media.body as Body).photoUri === 'string' && (media.body as Body).contentType === 'image/jpeg'
+        && bad.status === 400 && (bad.body as Body).error?.status === 'INVALID_ARGUMENT';
+    })),
+  done('googlemaps.places_new.pagination', 'places_new', 'Places API (New) pageToken/pageSize pagination', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const p1 = await h({ m: 'POST', p: '/v1/places:searchText', b: { textQuery: 'London', pageSize: 10 }, headers: { 'x-goog-api-key': 'k' } });
+      const tok = (p1.body as Body).nextPageToken as string;
+      const p2 = await h({ m: 'POST', p: '/v1/places:searchText', b: { textQuery: 'London', pageToken: tok }, headers: { 'x-goog-api-key': 'k' } });
+      return (p1.body as Body).places?.length === 10 && typeof tok === 'string'
+        && Array.isArray((p2.body as Body).places) && (p2.body as Body).places.length > 0
+        && (p1.body as Body).places[0].id !== (p2.body as Body).places[0].id;
+    })),
+
+  // ---- Roads / TimeZone ----
+  done('googlemaps.roads.interpolate', 'roads', 'Roads snapToRoads interpolate=true densifies with index-less points', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const plain = await h({ m: 'GET', p: '/v1/snapToRoads?path=34.05,-118.24|34.06,-118.25', headers: { 'x-goog-api-key': 'k' } });
+      const inter = await h({ m: 'GET', p: '/v1/snapToRoads?interpolate=true&path=34.05,-118.24|34.06,-118.25', headers: { 'x-goog-api-key': 'k' } });
+      const ip = (inter.body as Body).snappedPoints;
+      return (plain.body as Body).snappedPoints?.length === 2 && ip?.length === 3
+        && ip[0].originalIndex === 0 && ip[1].originalIndex === undefined && ip[2].originalIndex === 1;
+    })),
+  done('googlemaps.timezone.dst', 'timezone', 'Time Zone computes a non-zero dstOffset for a summer timestamp in a DST zone', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      // Find a location whose deterministic zone observes DST, then probe summer vs winter.
+      for (const loc of ['34.05,-118.24', '40.71,-74.0', '51.5,-0.12', '48.0,2.0', '45.0,-100.0']) {
+        const summer = await h({ m: 'GET', p: `/maps/api/timezone/json?location=${loc}&timestamp=1656633600` }); // 2022-07-01
+        const winter = await h({ m: 'GET', p: `/maps/api/timezone/json?location=${loc}&timestamp=1640995200` }); // 2022-01-01
+        if ((summer.body as Body).dstOffset === 3600 && (winter.body as Body).dstOffset === 0
+          && (summer.body as Body).timeZoneName !== (winter.body as Body).timeZoneName) return true;
+      }
+      return false;
+    })),
+
+  // ---- Address Validation / Static Maps ----
+  done('googlemaps.address_validation.components', 'address_validation', 'Address Validation returns per-component confirmationLevel', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const ok = await h({ m: 'POST', p: '/v1:validateAddress', b: { address: { addressLines: ['1600 Amphitheatre Pkwy, Mountain View'] } }, headers: { 'x-goog-api-key': 'k' } });
+      const comp = (ok.body as Body).result?.address?.addressComponents?.[0];
+      const bad = await h({ m: 'POST', p: '/v1:validateAddress', b: { address: { addressLines: ['unknown route 9999'] } }, headers: { 'x-goog-api-key': 'k' } });
+      const badComp = (bad.body as Body).result?.address?.addressComponents?.[0];
+      return comp?.confirmationLevel === 'CONFIRMED' && typeof comp?.componentType === 'string'
+        && badComp?.confirmationLevel === 'UNCONFIRMED_BUT_PLAUSIBLE';
+    })),
+  done('googlemaps.address_validation.usps', 'address_validation', 'Address Validation populates USPS CASS metadata for US addresses only', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const us = await h({ m: 'POST', p: '/v1:validateAddress', b: { address: { addressLines: ['1600 Amphitheatre Pkwy, Mountain View'] } }, headers: { 'x-goog-api-key': 'k' } });
+      const nonUs = await h({ m: 'POST', p: '/v1:validateAddress', b: { address: { addressLines: ['London'] } }, headers: { 'x-goog-api-key': 'k' } });
+      return typeof (us.body as Body).result?.uspsData?.standardizedAddress?.zipCode === 'string'
+        && (us.body as Body).result?.uspsData?.dpvConfirmation === 'Y'
+        && (nonUs.body as Body).result?.uspsData === undefined;
+    })),
+  done('googlemaps.staticmap.styling', 'staticmap', 'Static Maps parses style/markers/path/maptype; rejects an invalid maptype', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/maps/api/staticmap?center=34.05,-118.24&zoom=12&size=600x400&maptype=satellite&markers=color:red|34.05,-118.24&style=feature:road|color:0x000000' });
+      const bad = await h({ m: 'GET', p: '/maps/api/staticmap?center=34.05,-118.24&size=600x400&maptype=bogus' });
+      return (r.body as Body).maptype === 'satellite' && (r.body as Body).markers?.length === 1 && (r.body as Body).style?.length === 1
+        && bad.status === 400 && (bad.body as Body).error?.status === 'INVALID_ARGUMENT';
+    })),
+
+  // ---- Routes API (New) ----
+  done('googlemaps.routes_api.compute_routes', 'routes_api', 'Routes API (New) computeRoutes returns routes with distance/duration/polyline', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({
+        m: 'POST', p: '/directions/v2:computeRoutes',
+        b: { origin: { location: { latLng: { latitude: 34.05, longitude: -118.24 } } }, destination: { location: { latLng: { latitude: 40.71, longitude: -74.0 } } }, travelMode: 'DRIVE', computeAlternativeRoutes: true },
+        headers: { 'x-goog-api-key': 'k', 'x-goog-fieldmask': 'routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline' },
+      });
+      const routes = (r.body as Body).routes;
+      const bad = await h({ m: 'POST', p: '/directions/v2:computeRoutes', b: { origin: { location: { latLng: { latitude: 34.05, longitude: -118.24 } } } }, headers: { 'x-goog-api-key': 'k' } });
+      return r.status === 200 && routes?.length === 2 && typeof routes[0].distanceMeters === 'number'
+        && /^\d+s$/.test(routes[0].duration) && typeof routes[0].polyline?.encodedPolyline === 'string'
+        && routes[0].legs === undefined // masked out
+        && bad.status === 400 && (bad.body as Body).error?.status === 'INVALID_ARGUMENT';
+    })),
+  done('googlemaps.routes_api.compute_route_matrix', 'routes_api', 'Routes API (New) computeRouteMatrix returns indexed elements with condition', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({
+        m: 'POST', p: '/distanceMatrix/v2:computeRouteMatrix',
+        b: {
+          origins: [{ waypoint: { location: { latLng: { latitude: 34.05, longitude: -118.24 } } } }, { waypoint: { location: { latLng: { latitude: 40.71, longitude: -74.0 } } } }],
+          destinations: [{ waypoint: { location: { latLng: { latitude: 51.5, longitude: -0.12 } } } }],
+          travelMode: 'DRIVE',
+        },
+        headers: { 'x-goog-api-key': 'k', 'x-goog-fieldmask': 'originIndex,destinationIndex,duration,distanceMeters,condition' },
+      });
+      const arr = r.body as Body[];
+      const bad = await h({ m: 'POST', p: '/distanceMatrix/v2:computeRouteMatrix', b: { origins: [] }, headers: { 'x-goog-api-key': 'k' } });
+      return r.status === 200 && Array.isArray(arr) && arr.length === 2
+        && arr[0]!.originIndex === 0 && arr[0]!.destinationIndex === 0 && arr[0]!.condition === 'ROUTE_EXISTS'
+        && typeof arr[0]!.distanceMeters === 'number' && /^\d+s$/.test(arr[0]!.duration)
+        && bad.status === 400 && (bad.body as Body).error?.status === 'INVALID_ARGUMENT';
+    })),
+
+  // ---- still genuinely-unbuilt (live denominator) ----
+  todo('googlemaps.places.session_tokens', 'places', 'Autocomplete sessiontoken billing semantics', 'api', 'niche'),
+  todo('googlemaps.geolocation.cell_wifi_trilateration', 'geolocation', 'Geolocation cell/wifi trilateration fidelity', 'api', 'niche'),
+];
+
+export async function googlemapsCapabilities(): Promise<CapabilityReport> {
+  return checkCapabilities('googlemaps', GOOGLEMAPS_CAPABILITIES);
+}