@volter/twin-googlemaps 0.1.0

package/dist/src/googlemaps-capabilities.js

@@ -0,0 +1,648 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { projectResources } from '@volter/world-core';
+import { checkCapabilities, verifyBoundary } from '@volter/world-tooling';
+import { pullGoogleMapsGeocodes, } from "./googlemaps-connector.js";
+import { performPending } from "./googlemaps-perform-harness.js";
+import { handleGoogleMapsTwinRequest } from "./googlemaps-twin.js";
+async function withRoot(fn) {
+    const root = mkdtempSync(join(tmpdir(), 'googlemaps-cap-'));
+    const h = (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, area, title, dimension, tier, verify) => ({ id, area, title, dimension, tier, expected: 'done', verify });
+const todo = (id, area, title, dimension, tier) => ({ id, area, title, dimension, tier, expected: 'todo' });
+export const GOOGLEMAPS_CAPABILITIES = [
+    // ---- 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.results?.[0];
+        return r.status === 200 && r.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.results?.[0];
+        const comp = res?.address_components?.find((c) => 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.status === 'ZERO_RESULTS' && Array.isArray(r.body.results) && r.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.status === 'INVALID_REQUEST' && typeof r.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.results?.[0];
+        return r.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.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.results?.[0];
+        return r.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.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.results?.[0]?.geometry?.location;
+        const lb = b.body.results?.[0]?.geometry?.location;
+        return a.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.results?.[0];
+        return r.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.rows?.[0]?.elements?.[0];
+        return r.status === 200 && r.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.origin_addresses) && Array.isArray(r.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.rows;
+        return r.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.status === 'OK' && r.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.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.rows?.[0]?.elements?.[0]?.distance?.text;
+        const metText = met.body.rows?.[0]?.elements?.[0]?.distance?.text;
+        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.routes?.[0];
+        const leg = route?.legs?.[0];
+        return r.status === 200 && r.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.geocoded_waypoints;
+        const route = r.body.routes?.[0];
+        return r.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.status === 'ZERO_RESULTS' && r.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.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.candidates?.[0];
+        return r.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.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.results?.[0];
+        return r.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.status === 'ZERO_RESULTS' && r.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.results?.[0];
+        return r.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.status === 'INVALID_REQUEST' && ok.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.result;
+        return r.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.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.predictions?.[0];
+        return r.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.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.status === 'OK' && typeof r.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.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.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.places;
+        return zero.status === 200 && zero.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.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.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.id === 'ChIJOwg_06VPwokRYv534QaPC8g' && r.body.displayName?.text === 'New York' && r.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.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.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.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.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.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.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.status === 'OK'
+            && typeof r.body.timeZoneId === 'string' && typeof r.body.rawOffset === 'number'
+            && typeof r.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.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.results;
+        return r.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.status === 'OK' && bad.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.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.location?.lat === 'number' && typeof r.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.location?.lat;
+        return typeof latA === 'number' && typeof a.body.location?.lng === 'number' && typeof a.body.accuracy === 'number'
+            && latA === b.body.location?.lat
+            && latA !== c.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.result;
+        return r.status === 200 && result?.verdict?.addressComplete === true
+            && typeof result?.geocode?.location?.latitude === 'number' && typeof r.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.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.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.contentType === 'image/png' && r.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.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.status === 'OK' && typeof r.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.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.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.status === 'REQUEST_DENIED' && typeof r.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.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.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.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.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.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.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.entries;
+        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].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 = [];
+            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.results?.[0]?.plus_code;
+        return r.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.status === 'OK' && ok.body.results?.[0]?.place_id === 'ChIJdd4hrwug2EcRmSrV3Vo6llI'
+            && miss.body.status === 'ZERO_RESULTS' && miss.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.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.results?.[0]?.geometry?.location;
+        // Free location is somewhere on the globe; biased one is clamped into the box.
+        return biased.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.results?.[0]?.formatted_address;
+        const jaAddr = ja.body.results?.[0]?.formatted_address;
+        return enAddr === 'Tokyo, Japan' && jaAddr === '日本、東京都' && jaAddr !== enAddr
+            && en.body.results?.[0]?.place_id === ja.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.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.routes?.[0];
+        return plain.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.routes;
+        return r.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.routes?.[0]?.legs?.[0]?.steps?.[0];
+        const wStep = walk.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.routes?.[0]?.legs?.[0];
+        return r.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.routes?.[0]?.warnings;
+        return r.body.status === 'OK' && Array.isArray(w) && w.some((m) => /tolls/.test(m)) && w.some((m) => /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.routes?.[0]?.legs?.[0]?.steps?.[0]?.transit_details;
+        return r.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.rows?.[0]?.elements?.[0];
+        const dEl = drive.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.status === 'MAX_ELEMENTS_EXCEEDED' && ok.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.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.contentType === 'image/jpeg' && photo.body.photo_reference === ref
+            && bad.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.next_page_token;
+        const p2 = await h({ m: 'GET', p: `/maps/api/place/textsearch/json?pagetoken=${encodeURIComponent(tok)}` });
+        return p1.body.status === 'OK' && p1.body.results?.length === 20 && typeof tok === 'string'
+            && p2.body.results?.length === 3
+            && p1.body.results[0].place_id !== p2.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.result?.opening_hours;
+        return r.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.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.result?.reviews?.[0];
+        return r.body.status === 'OK' && typeof rev?.author_name === 'string' && typeof rev?.rating === 'number'
+            && typeof rev?.text === 'string' && typeof r.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.result;
+        return r.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.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.id === 'ChIJOwg_06VPwokRYv534QaPC8g' && d.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.photos?.[0]?.name;
+        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.photoUri === 'string' && media.body.contentType === 'image/jpeg'
+            && bad.status === 400 && bad.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.nextPageToken;
+        const p2 = await h({ m: 'POST', p: '/v1/places:searchText', b: { textQuery: 'London', pageToken: tok }, headers: { 'x-goog-api-key': 'k' } });
+        return p1.body.places?.length === 10 && typeof tok === 'string'
+            && Array.isArray(p2.body.places) && p2.body.places.length > 0
+            && p1.body.places[0].id !== p2.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.snappedPoints;
+        return plain.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.dstOffset === 3600 && winter.body.dstOffset === 0
+                && summer.body.timeZoneName !== winter.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.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.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.result?.uspsData?.standardizedAddress?.zipCode === 'string'
+            && us.body.result?.uspsData?.dpvConfirmation === 'Y'
+            && nonUs.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.maptype === 'satellite' && r.body.markers?.length === 1 && r.body.style?.length === 1
+            && bad.status === 400 && bad.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.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.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;
+        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.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() {
+    return checkCapabilities('googlemaps', GOOGLEMAPS_CAPABILITIES);
+}