@volter/twin-googlemaps 0.1.0

package/src/googlemaps-conformance.ts

@@ -0,0 +1,24 @@
+import { handleGoogleMapsTwinRequest } from './googlemaps-twin.ts';
+
+export type GoogleMapsConformanceReport = { ok: boolean; checksRun: number; failures: string[] };
+
+export async function checkGoogleMapsConformance(options: { root?: string } = {}): Promise<GoogleMapsConformanceReport> {
+  const failures: string[] = [];
+  let checksRun = 0;
+  const check = (name: string, ok: boolean) => { checksRun += 1; if (!ok) failures.push(name); };
+
+  const geo = await handleGoogleMapsTwinRequest({ method: 'GET', path: '/maps/api/geocode/json?address=Los%20Angeles', root: options.root });
+  check('geocode returns OK with a location', geo.status === 200
+    && (geo.body as any).status === 'OK'
+    && typeof (geo.body as any).results?.[0]?.geometry?.location?.lat === 'number');
+
+  const dm = await handleGoogleMapsTwinRequest({ method: 'GET', path: '/maps/api/distancematrix/json?origins=34.05,-118.24&destinations=40.71,-74.0', root: options.root });
+  check('distancematrix returns OK rows', dm.status === 200
+    && (dm.body as any).status === 'OK'
+    && (dm.body as any).rows?.[0]?.elements?.[0]?.status === 'OK');
+
+  const bad = await handleGoogleMapsTwinRequest({ method: 'GET', path: '/maps/api/geocode/json', root: options.root });
+  check('missing address rejects with INVALID_REQUEST', (bad.body as any).status === 'INVALID_REQUEST');
+
+  return { ok: failures.length === 0, checksRun, failures };
+}

package/src/googlemaps-connector.ts

@@ -0,0 +1,250 @@
+// Google Maps CONNECTOR — pull/push against an INJECTED `GoogleMapsExecute`, so every test and
+// every capability verify runs offline against a deterministic fake.
+//
+// `liveGoogleMapsExecute` below is the pack's ONE construction site for a real, network-calling
+// execute — the choke point the rate budget sits inside. Before it existed there was nowhere for a
+// guard to live: the pack only ever received an execute, so a budget could only be something the
+// caller remembered to opt into, and "the caller remembered" is exactly the assumption that cost a
+// ~4.5-day Figma token lockout (2026-07-25). See `googlemaps-budget.ts` for the numbers and the
+// documented limits behind them.
+//
+// The injected contract is UNCHANGED: everything below still takes a plain `GoogleMapsExecute`.
+import { observeResources, projectResources } from '@volter/world-core';
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { normalizeAddress, stableHash } from './googlemaps-data.ts';
+import type { GeocodeResult } from './googlemaps-types.ts';
+import { GoogleMapsBudget, GoogleMapsBudgetError, googleMapsCallWeight, type GoogleMapsBudgetOptions } from './googlemaps-budget.ts';
+
+export type GoogleMapsExecute = (req: { method: string; path: string; body?: unknown }) => Promise<{ status: number; data: unknown }>;
+
+const DEFAULT_OCCURRED_AT = '1970-01-01T00:00:00.000Z';
+
+/** The real Google Maps Platform web-service host. The ONLY place this pack names it as a target. */
+export const GOOGLEMAPS_API_BASE = 'https://maps.googleapis.com';
+
+/**
+ * THE CHOKE POINT — the one place this pack builds a `GoogleMapsExecute` that really reaches
+ * maps.googleapis.com, and therefore the one place the rate budget has to be enforced.
+ *
+ * Reads the API key from `GOOGLE_MAPS_API_KEY` (never a literal, never a credentials file) and sends
+ * it the way Google documents for each surface: as the `key=` query parameter on the legacy
+ * `/maps/api/...` web services, and as the `X-Goog-Api-Key` header otherwise (Places API New /
+ * Address Validation) — see `googlemaps-auth.ts`, which models the same two forms.
+ *
+ * EVERY request is guarded: the budget is charged BEFORE it goes out (`checkBudget`, which THROWS
+ * instead of returning once the ceiling or a persisted cooldown says stop) and the response is fed
+ * back (`recordCall`) so a `Retry-After` / 429 / rate-limit-exhaustion signal becomes a persisted
+ * cooldown that makes every later call fail fast WITHOUT touching Google. There is deliberately NO
+ * option to disable the guard.
+ *
+ * No vendor SDK is imported: real-transport `fetch` keeps `@googlemaps/google-maps-services-js` a
+ * dev-only dependency, which the architecture guardrail requires.
+ */
+export function liveGoogleMapsExecute(
+  opts: {
+    apiKey?: string;
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+    /** An existing budget to share across executes. Omit and one is constructed. Cannot be null. */
+    budget?: GoogleMapsBudget;
+    /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+    budgetOptions?: GoogleMapsBudgetOptions;
+  } = {},
+): GoogleMapsExecute {
+  const apiKey = opts.apiKey ?? process.env.GOOGLE_MAPS_API_KEY ?? '';
+  if (!apiKey) throw new Error('GOOGLE_MAPS_API_KEY is not set — the live Google Maps client needs an API key');
+  const baseUrl = opts.baseUrl ?? GOOGLEMAPS_API_BASE;
+  const doFetch = opts.fetchImpl ?? fetch;
+  // There is no value a caller can pass to end up with an unguarded execute. `null`/`undefined` (or
+  // omitting it) build the default budget; anything that is not a REAL `GoogleMapsBudget` is refused
+  // loudly rather than trusted — a duck-typed stand-in with a no-op `checkBudget` would otherwise be
+  // the one clean way around the guard.
+  if (opts.budget !== undefined && opts.budget !== null && !(opts.budget instanceof GoogleMapsBudget)) {
+    throw new Error('liveGoogleMapsExecute: `budget` must be a GoogleMapsBudget — refusing to build a live Google Maps client around an unverified rate guard');
+  }
+  // The default ledger is keyed by a hash of THIS key — Google's quotas are per project/key, so a
+  // cwd-scoped ledger would hand the same key a fresh allowance per checkout/worktree/CI leg.
+  const budget = opts.budget instanceof GoogleMapsBudget
+    ? opts.budget
+    : new GoogleMapsBudget({ token: apiKey, ...(opts.budgetOptions ?? {}) });
+  return async (req) => {
+    requireVendorPath(req.path);
+    const method = (req.method || 'GET').toUpperCase();
+    const weight = googleMapsCallWeight(method, req.path);
+    // THROWS instead of calling. Nothing below this line runs when the budget refuses.
+    const reservation = budget.checkBudget(weight);
+    const legacy = req.path.startsWith('/maps/api/');
+    const url = new URL(req.path, baseUrl);
+    if (legacy) url.searchParams.set('key', apiKey);
+    const res = await doFetch(url.toString(), {
+      method,
+      headers: {
+        Accept: 'application/json',
+        ...(legacy ? {} : { 'X-Goog-Api-Key': apiKey }),
+        ...(req.body === undefined ? {} : { 'Content-Type': 'application/json' }),
+      },
+      ...(req.body === undefined ? {} : { body: JSON.stringify(req.body) }),
+    });
+    const headers = lowerCasedHeaders(res.headers);
+    const text = await res.text();
+    let data: unknown = null;
+    try { data = text ? JSON.parse(text) : null; } catch { data = { raw: text }; }
+    // Settles the reservation and, on a back-off signal, arms the cooldown. May itself throw (a
+    // Retry-After beyond the cap is not something to sleep off) — the cooldown is persisted first
+    // either way, so the refusal survives the throw.
+    // recordCall may THROW after arming the cooldown (a back-off beyond the cap). On a refused
+    // call that louder refusal wins; an answer Google Maps ACCEPTED is kept, so a write that landed is
+    // never recorded as failed and performed again on retry.
+    try {
+      budget.recordCall(weight, headers, { status: res.status, reservation });
+    } catch (error) {
+      if (!(error instanceof GoogleMapsBudgetError) || !res.ok) throw error;
+    }
+    return { status: res.status, data };
+  };
+}
+
+/**
+ * Refuse a `path` that is not a same-origin ABSOLUTE PATH.
+ *
+ * `new URL(path, base)` treats `https://evil.test/x` AND the protocol-relative `//evil.test/x` as
+ * absolute and silently retargets the host — and this factory attaches the credential
+ * unconditionally, so a caller-supplied absolute path would exfiltrate it to an arbitrary server.
+ * Figma's guarded client sidesteps this by concatenating rather than resolving; this execute takes an
+ * arbitrary `{ path }` from its caller, so it validates instead. (§9 finding, 2026-07-26.)
+ *
+ * `/twin/...` is refused for a different reason: those are the twin's OWN seed routes
+ * (`*RequestForAction` builds them), which the real vendor has never heard of. Sending one live is a
+ * guaranteed 404 that still burns budget and puts the live credential on the wire for nothing.
+ */
+function requireVendorPath(path: string): void {
+  if (typeof path !== 'string' || !/^\/(?!\/)/.test(path)) {
+    throw new Error(`liveGoogleMapsExecute: path must be a same-origin absolute path beginning with a single "/" (got ${String(path)}) — refusing to let a caller-supplied absolute URL retarget the host with the credential attached`);
+  }
+  if (path === '/twin' || path.startsWith('/twin/')) {
+    throw new Error(`liveGoogleMapsExecute: refusing to send the twin-only path ${path} to real Google Maps — that route exists only in the local twin`);
+  }
+}
+
+/** Response headers as a plain lower-cased record — what the kernel's back-off reader expects. */
+function lowerCasedHeaders(h: Headers): Record<string, string> {
+  const out: Record<string, string> = {};
+  h.forEach((v: string, k: string) => { out[k.toLowerCase()] = v; });
+  return out;
+}
+
+/** Fetch + map geocode results into SyncResource[] (no fold) — shared by pull + syncFromReal. */
+async function collectGoogleMapsGeocodes(execute: GoogleMapsExecute, addresses: string[]): Promise<SyncResource[]> {
+  const resources: SyncResource[] = [];
+  for (const address of addresses) {
+    const res = await execute({ method: 'GET', path: `/maps/api/geocode/json?address=${encodeURIComponent(address)}` });
+    if (res.status < 200 || res.status >= 300) continue;
+    const data = res.data as { status?: string; results?: GeocodeResult[] };
+    if (data.status !== 'OK' || !data.results?.length) continue;
+    const norm = normalizeAddress(address);
+    const id = `geocode_${stableHash(norm)}`;
+    resources.push({ type: 'geocode', id, fields: { id, normalized: norm, address, result: data.results[0], source: 'connector' } });
+  }
+  return resources;
+}
+
+/** Fetch + map place details into SyncResource[] (no fold) — shared by pull + syncFromReal. */
+async function collectGoogleMapsPlaces(execute: GoogleMapsExecute, placeIds: string[]): Promise<SyncResource[]> {
+  const resources: SyncResource[] = [];
+  for (const placeId of placeIds) {
+    const res = await execute({ method: 'GET', path: `/maps/api/place/details/json?place_id=${encodeURIComponent(placeId)}` });
+    if (res.status < 200 || res.status >= 300) continue;
+    const data = res.data as { status?: string; result?: Record<string, unknown> };
+    if (data.status !== 'OK' || !data.result) continue;
+    resources.push({ type: 'place', id: `place_${placeId}`, fields: { id: `place_${placeId}`, placeId, ...data.result, source: 'connector' } });
+  }
+  return resources;
+}
+
+/**
+ * Pull geocode results for a set of addresses through an injected client (the
+ * real Maps Geocoding API in prod, a fake in tests) and fold each OK result into
+ * local state as a `geocode` override. Idempotent on the normalized address.
+ */
+export async function pullGoogleMapsGeocodes(execute: GoogleMapsExecute, addresses: string[], opts: { root?: string; occurredAt?: string } = {}): Promise<number> {
+  const resources = await collectGoogleMapsGeocodes(execute, addresses);
+  fold(resources, opts);
+  return resources.length;
+}
+
+/**
+ * Pull place details for a set of place ids, folding each into local state as a
+ * `place` resource snapshot. Idempotent on the place id.
+ */
+export async function pullGoogleMapsPlaces(execute: GoogleMapsExecute, placeIds: string[], opts: { root?: string; occurredAt?: string } = {}): Promise<number> {
+  const resources = await collectGoogleMapsPlaces(execute, placeIds);
+  fold(resources, opts);
+  return resources.length;
+}
+
+/**
+ * D7 consumer-facing pull entry point: pull from the real Maps API (geocodes for the given
+ * addresses + details for the given place ids) and fold into the twin in ONE shadow-diffed
+ * one observed batch, returning the standard `{ observed, deltasAppended }` result. The inputs ride on the
+ * options object (this is an input-driven stateless twin). Idempotent — a re-pull of identical
+ * state appends nothing (deltasAppended drops to 0).
+ */
+export async function syncGoogleMapsFromReal(
+  execute: GoogleMapsExecute,
+  opts: { addresses?: string[]; placeIds?: string[]; root?: string; occurredAt?: string } = {},
+): Promise<{ observed: number; deltasAppended: number }> {
+  const geocodes = await collectGoogleMapsGeocodes(execute, opts.addresses ?? []);
+  const places = await collectGoogleMapsPlaces(execute, opts.placeIds ?? []);
+  const resources = [...geocodes, ...places];
+  const result = fold(resources, opts);
+  return { observed: result.observed, deltasAppended: result.appended };
+}
+
+/** One fold onto the head: protocol 2's observe, one batch, one instant. */
+function fold(resources: SyncResource[], opts: { root?: string; occurredAt?: string }) {
+  const at = opts.occurredAt ?? DEFAULT_OCCURRED_AT;
+  return observeResources('googlemaps', resources.map((r) => ({ type: r.type, id: r.id, fields: r.fields })), {
+    ...(opts.root !== undefined ? { root: opts.root } : {}), at, batch: `obs:googlemaps:${at}`,
+  });
+}
+
+/** A pending `geocode.upsert` action is pushed as a twin-only seed POST. */
+export function googleMapsRequestForAction(action: TwinAction): { method: string; path: string; body?: unknown } | null {
+  if (action.operation !== 'geocode.upsert') return null;
+  const fields = action.fields as Record<string, unknown>;
+  return { method: 'POST', path: '/twin/geocode', body: { address: fields.address, result: fields.result } };
+}
+
+export async function pushGoogleMapsAction(action: TwinAction, execute: GoogleMapsExecute): Promise<boolean> {
+  const req = googleMapsRequestForAction(action);
+  if (!req) return false;
+  const result = await execute(req);
+  return result.status >= 200 && result.status < 300;
+}
+
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+/** The pack's executor over the kernel's. */
+export function googleMapsExecuteOver(execute: RemoteExecute): GoogleMapsExecute {
+  return async ({ method, path, body }) => {
+    const res = await execute({ method, path, headers: { accept: 'application/json', ...(body ? { 'content-type': 'application/json' } : {}) }, ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+    let data: unknown = {};
+    if (res.body) { try { data = JSON.parse(res.body); } catch { data = { error_message: res.body }; } }
+    return { status: res.status, data };
+  };
+}
+/** The refresh adapter: re-read every address the tree already holds a geocode for. The Geocoding API has no
+ *  inventory to list — what a world knows to ask about IS the addresses it has seen. */
+export async function syncGoogleMapsFromRemote(execute: RemoteExecute, opts: { root?: string; origin?: string; occurredAt?: string } = {}): Promise<{ observed: number; deltasAppended: number }> {
+  const addresses: string[] = [];
+  for (const r of projectResources('googlemaps', opts.root)) {
+    if (r.type !== 'geocode') continue;
+    const address = (r as Record<string, unknown>).address;
+    if (typeof address === 'string' && address) addresses.push(address);
+  }
+  return syncGoogleMapsFromReal(googleMapsExecuteOver(execute), { addresses, ...(opts.root !== undefined ? { root: opts.root } : {}), ...(opts.occurredAt !== undefined ? { occurredAt: opts.occurredAt } : {}) });
+}
+/** The perform adapter. The Google Maps APIs this twin serves are READ-ONLY: they answer questions about
+ *  the world and accept no writes, so no entry ever crosses — each settles with that reason. */
+export async function performGoogleMapsAction(_execute: RemoteExecute, action: TwinAction, _ctx: PerformContext): Promise<PushOutcome> {
+  return { externalId: action.subject.id, data: { performed: false, reason: `${action.operation ?? action.subject.type}: the Google Maps APIs answer questions and accept no writes — nothing to perform` } };
+}

package/src/googlemaps-data.ts

@@ -0,0 +1,399 @@
+import { createHash } from 'node:crypto';
+import type { AddressComponent, GeocodeResult, Geometry, LatLng } from './googlemaps-types.ts';
+
+/**
+ * Deterministic, NON-real geodata. A Google Maps twin cannot reproduce Google's
+ * real geospatial index, live traffic, or imagery; instead it returns faithful
+ * response SHAPES with stable, deterministic values. A given query always maps
+ * to the same canned result so verifies and tests are repeatable offline.
+ */
+
+/** Stable FNV-ish hash → hex, used to derive deterministic ids/coords. */
+export function stableHash(input: unknown): string {
+  const s = typeof input === 'string' ? input : JSON.stringify(input);
+  return createHash('sha256').update(s).digest('hex').slice(0, 16);
+}
+
+/** Normalize a free-text address for stable keying (lowercase, collapse ws). */
+export function normalizeAddress(address: string): string {
+  return address.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+
+/** Deterministic lat/lng in a plausible range derived from a seed string. */
+export function deterministicLatLng(seed: string): LatLng {
+  const h = stableHash(seed);
+  const a = parseInt(h.slice(0, 8), 16);
+  const b = parseInt(h.slice(8, 16), 16);
+  // lat in [-85, 85], lng in [-180, 180], rounded to 7 decimals like Google.
+  const lat = Math.round((((a % 17000000) / 100000) - 85) * 1e7) / 1e7;
+  const lng = Math.round((((b % 36000000) / 100000) - 180) * 1e7) / 1e7;
+  return { lat, lng };
+}
+
+export function viewportAround(loc: LatLng, delta = 0.01): Geometry['viewport'] {
+  return {
+    northeast: { lat: Math.round((loc.lat + delta) * 1e7) / 1e7, lng: Math.round((loc.lng + delta) * 1e7) / 1e7 },
+    southwest: { lat: Math.round((loc.lat - delta) * 1e7) / 1e7, lng: Math.round((loc.lng - delta) * 1e7) / 1e7 },
+  };
+}
+
+/** A small named place dataset (canned, not real index lookups). */
+export type CannedPlace = {
+  place_id: string;
+  formatted_address: string;
+  location: LatLng;
+  types: string[];
+  components: AddressComponent[];
+  name: string;
+};
+
+// Place ids use Google's `ChIJ`-prefixed opaque token shape. These are canned.
+const PLACES: CannedPlace[] = [
+  {
+    place_id: 'ChIJE9on3F3HwoAR9AhGJW_fL-I',
+    name: 'Los Angeles',
+    formatted_address: 'Los Angeles, CA, USA',
+    location: { lat: 34.0522342, lng: -118.2436849 },
+    types: ['locality', 'political'],
+    components: [
+      { long_name: 'Los Angeles', short_name: 'Los Angeles', types: ['locality', 'political'] },
+      { long_name: 'Los Angeles County', short_name: 'Los Angeles County', types: ['administrative_area_level_2', 'political'] },
+      { long_name: 'California', short_name: 'CA', types: ['administrative_area_level_1', 'political'] },
+      { long_name: 'United States', short_name: 'US', types: ['country', 'political'] },
+    ],
+  },
+  {
+    place_id: 'ChIJOwg_06VPwokRYv534QaPC8g',
+    name: 'New York',
+    formatted_address: 'New York, NY, USA',
+    location: { lat: 40.7127753, lng: -74.0059728 },
+    types: ['locality', 'political'],
+    components: [
+      { long_name: 'New York', short_name: 'New York', types: ['locality', 'political'] },
+      { long_name: 'New York', short_name: 'NY', types: ['administrative_area_level_1', 'political'] },
+      { long_name: 'United States', short_name: 'US', types: ['country', 'political'] },
+    ],
+  },
+  {
+    place_id: 'ChIJj61dQgK6j4AR4GeTYWZsKWw',
+    name: 'Mountain View',
+    formatted_address: '1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA',
+    location: { lat: 37.4220656, lng: -122.0840897 },
+    types: ['street_address'],
+    components: [
+      { long_name: '1600', short_name: '1600', types: ['street_number'] },
+      { long_name: 'Amphitheatre Parkway', short_name: 'Amphitheatre Pkwy', types: ['route'] },
+      { long_name: 'Mountain View', short_name: 'Mountain View', types: ['locality', 'political'] },
+      { long_name: 'California', short_name: 'CA', types: ['administrative_area_level_1', 'political'] },
+      { long_name: 'United States', short_name: 'US', types: ['country', 'political'] },
+      { long_name: '94043', short_name: '94043', types: ['postal_code'] },
+    ],
+  },
+  {
+    place_id: 'ChIJdd4hrwug2EcRmSrV3Vo6llI',
+    name: 'London',
+    formatted_address: 'London, UK',
+    location: { lat: 51.5072178, lng: -0.1275862 },
+    types: ['locality', 'political'],
+    components: [
+      { long_name: 'London', short_name: 'London', types: ['locality', 'political'] },
+      { long_name: 'United Kingdom', short_name: 'GB', types: ['country', 'political'] },
+    ],
+  },
+  {
+    place_id: 'ChIJ51cu8IcbXWARiRtXIothAS4',
+    name: 'Tokyo',
+    formatted_address: 'Tokyo, Japan',
+    location: { lat: 35.6761919, lng: 139.6503106 },
+    types: ['locality', 'political'],
+    components: [
+      { long_name: 'Tokyo', short_name: 'Tokyo', types: ['locality', 'political'] },
+      { long_name: 'Japan', short_name: 'JP', types: ['country', 'political'] },
+    ],
+  },
+];
+
+const ZERO_RESULTS_MARKERS = ['nowhere', 'zzzznoresult', 'zero_results', 'this-place-does-not-exist'];
+
+/** Returns true for a query the twin deliberately maps to ZERO_RESULTS. */
+export function isZeroResultsQuery(q: string): boolean {
+  const n = normalizeAddress(q);
+  return ZERO_RESULTS_MARKERS.some((m) => n.includes(m));
+}
+
+/** Find a canned place by fuzzy name/address substring match. */
+export function findPlaceByText(query: string): CannedPlace | null {
+  const n = normalizeAddress(query);
+  for (const p of PLACES) {
+    if (n.includes(normalizeAddress(p.name))) return p;
+    if (normalizeAddress(p.formatted_address).includes(n) && n.length >= 3) return p;
+  }
+  return null;
+}
+
+export function findPlaceById(placeId: string): CannedPlace | null {
+  return PLACES.find((p) => p.place_id === placeId) ?? null;
+}
+
+/** The country short_name (ccTLD-ish) for a canned place, for component filtering. */
+export function countryOf(p: CannedPlace): string | undefined {
+  return p.components.find((c) => c.types.includes('country'))?.short_name?.toLowerCase();
+}
+
+/** The locality long_name for a canned place (used in plus-code compound codes). */
+export function localityOf(p: CannedPlace): string {
+  return p.components.find((c) => c.types.includes('locality'))?.long_name
+    ?? p.components.find((c) => c.types.includes('administrative_area_level_1'))?.long_name
+    ?? p.name;
+}
+
+/** Nearest canned place to a lat/lng (for reverse geocoding). */
+export function findPlaceByLatLng(loc: LatLng): CannedPlace {
+  let best = PLACES[0]!;
+  let bestD = Number.POSITIVE_INFINITY;
+  for (const p of PLACES) {
+    const d = (p.location.lat - loc.lat) ** 2 + (p.location.lng - loc.lng) ** 2;
+    if (d < bestD) { bestD = d; best = p; }
+  }
+  return best;
+}
+
+export function allPlaces(): CannedPlace[] {
+  return PLACES;
+}
+
+/**
+ * Localized display names for canned places, keyed by language code. The Geocoding
+ * API returns localized `formatted_address` / component names per the `language`
+ * parameter; the twin models this faithfully for a small set of languages and
+ * falls back to the English name otherwise.
+ */
+const LOCALIZED_NAMES: Record<string, Record<string, string>> = {
+  'Tokyo, Japan': { ja: '日本、東京都', fr: 'Tokyo, Japon', es: 'Tokio, Japón', de: 'Tokio, Japan' },
+  'London, UK': { ja: 'イギリス ロンドン', fr: 'Londres, Royaume-Uni', es: 'Londres, Reino Unido', de: 'London, Vereinigtes Königreich' },
+  'Los Angeles, CA, USA': { ja: 'アメリカ合衆国 カリフォルニア州 ロサンゼルス', fr: 'Los Angeles, Californie, États-Unis', es: 'Los Ángeles, California, EE. UU.', de: 'Los Angeles, Kalifornien, USA' },
+  'New York, NY, USA': { ja: 'アメリカ合衆国 ニューヨーク州 ニューヨーク', fr: 'New York, État de New York, États-Unis', es: 'Nueva York, EE. UU.', de: 'New York, USA' },
+};
+
+/** Localize a formatted_address for a `language` code (no-op for English/unknown). */
+export function localizeFormattedAddress(formatted_address: string, language: string | null | undefined): string {
+  if (!language) return formatted_address;
+  const lang = language.toLowerCase().split('-')[0]!;
+  if (lang === 'en') return formatted_address;
+  return LOCALIZED_NAMES[formatted_address]?.[lang] ?? formatted_address;
+}
+
+/** Build a faithful GeocodeResult from a canned place. */
+export function geocodeResultFromPlace(p: CannedPlace, locationType: Geometry['location_type'] = 'ROOFTOP'): GeocodeResult {
+  return {
+    address_components: p.components,
+    formatted_address: p.formatted_address,
+    geometry: {
+      location: p.location,
+      location_type: locationType,
+      viewport: viewportAround(p.location),
+    },
+    place_id: p.place_id,
+    types: p.types,
+  };
+}
+
+/**
+ * Synthesize a deterministic GeocodeResult for an arbitrary (non-canned but
+ * valid) address so the twin never falsely 404s a well-formed query. Coordinates
+ * are derived from the address hash; shape is faithful.
+ */
+export function synthGeocodeResult(address: string): GeocodeResult {
+  const loc = deterministicLatLng(normalizeAddress(address));
+  const placeId = `ChIJ${stableHash(address)}twin`;
+  return {
+    address_components: [
+      { long_name: address, short_name: address, types: ['route'] },
+      { long_name: 'United States', short_name: 'US', types: ['country', 'political'] },
+    ],
+    formatted_address: address,
+    geometry: { location: loc, location_type: 'GEOMETRIC_CENTER', viewport: viewportAround(loc) },
+    place_id: placeId,
+    types: ['route'],
+  };
+}
+
+/** Great-circle distance (haversine) in meters between two points. */
+export function haversineMeters(a: LatLng, b: LatLng): number {
+  const R = 6371000;
+  const toRad = (d: number) => (d * Math.PI) / 180;
+  const dLat = toRad(b.lat - a.lat);
+  const dLng = toRad(b.lng - a.lng);
+  const lat1 = toRad(a.lat);
+  const lat2 = toRad(b.lat);
+  const h = Math.sin(dLat / 2) ** 2 + Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLng / 2) ** 2;
+  return Math.round(2 * R * Math.asin(Math.sqrt(h)));
+}
+
+/** Human "5.0 mi" / "1.2 km" text for a distance in meters (imperial default). */
+export function distanceText(meters: number, metric = false): string {
+  if (metric) {
+    const km = meters / 1000;
+    return km >= 1 ? `${km.toFixed(1)} km` : `${meters} m`;
+  }
+  const mi = meters / 1609.344;
+  return mi >= 0.1 ? `${mi.toFixed(1)} mi` : `${Math.round(meters * 3.28084)} ft`;
+}
+
+/** Human "15 mins" / "1 hour 5 mins" text for a duration in seconds. */
+export function durationText(seconds: number): string {
+  const mins = Math.round(seconds / 60);
+  if (mins < 60) return `${mins} min${mins === 1 ? '' : 's'}`;
+  const h = Math.floor(mins / 60);
+  const m = mins % 60;
+  return m === 0 ? `${h} hour${h === 1 ? '' : 's'}` : `${h} hour${h === 1 ? '' : 's'} ${m} min${m === 1 ? '' : 's'}`;
+}
+
+/** Deterministic driving duration (seconds) for a distance — ~40 km/h average. */
+export function deterministicDuration(meters: number): number {
+  return Math.max(60, Math.round((meters / 1000 / 40) * 3600));
+}
+
+/**
+ * A tiny polyline encoder (Google's Encoded Polyline Algorithm Format), used to
+ * produce a faithful `overview_polyline.points` for Directions responses.
+ */
+export function encodePolyline(points: LatLng[]): string {
+  let last = [0, 0];
+  let out = '';
+  const enc = (cur: number, prev: number): string => {
+    let v = Math.round(cur * 1e5) - Math.round(prev * 1e5);
+    v = v < 0 ? ~(v << 1) : v << 1;
+    let s = '';
+    while (v >= 0x20) {
+      s += String.fromCharCode((0x20 | (v & 0x1f)) + 63);
+      v >>= 5;
+    }
+    s += String.fromCharCode(v + 63);
+    return s;
+  };
+  for (const p of points) {
+    out += enc(p.lat, last[0]!);
+    out += enc(p.lng, last[1]!);
+    last = [p.lat, p.lng];
+  }
+  return out;
+}
+
+/** Deterministic elevation (meters) for a lat/lng. */
+export function deterministicElevation(loc: LatLng): number {
+  const h = parseInt(stableHash(`${loc.lat},${loc.lng}`).slice(0, 8), 16);
+  return Math.round(((h % 400000) / 100 - 100) * 1e2) / 1e2; // -100m .. 3900m
+}
+
+/**
+ * Deterministic IANA time zone id + offsets for a lat/lng. When a UTC `timestamp`
+ * (seconds) is supplied, northern-hemisphere DST is computed faithfully: zones
+ * that observe DST (US/UK) return a non-zero `dstOffset` for timestamps that fall
+ * between mid-March and early November; UTC/Japan never observe DST.
+ */
+export function deterministicTimeZone(loc: LatLng, timestamp?: number): { timeZoneId: string; timeZoneName: string; rawOffset: number; dstOffset: number } {
+  const zones = [
+    { timeZoneId: 'America/Los_Angeles', stdName: 'Pacific Standard Time', dstName: 'Pacific Daylight Time', rawOffset: -28800, observesDst: true },
+    { timeZoneId: 'America/New_York', stdName: 'Eastern Standard Time', dstName: 'Eastern Daylight Time', rawOffset: -18000, observesDst: true },
+    { timeZoneId: 'Europe/London', stdName: 'Greenwich Mean Time', dstName: 'British Summer Time', rawOffset: 0, observesDst: true },
+    { timeZoneId: 'Asia/Tokyo', stdName: 'Japan Standard Time', dstName: 'Japan Standard Time', rawOffset: 32400, observesDst: false },
+  ];
+  const idx = parseInt(stableHash(`${loc.lat},${loc.lng}`).slice(0, 4), 16) % zones.length;
+  const z = zones[idx]!;
+  let dstOffset = 0;
+  if (z.observesDst && timestamp !== undefined && Number.isFinite(timestamp)) {
+    const month = new Date(timestamp * 1000).getUTCMonth(); // 0..11
+    // Northern-hemisphere DST window: roughly mid-March (2) .. October (9).
+    if (month >= 2 && month <= 9) dstOffset = 3600;
+  }
+  return {
+    timeZoneId: z.timeZoneId,
+    timeZoneName: dstOffset > 0 ? z.dstName : z.stdName,
+    rawOffset: z.rawOffset,
+    dstOffset,
+  };
+}
+
+/**
+ * Open Location Code (Plus Code) encoder. Produces a faithful global_code (the
+ * 11th char is '+' after position 8) and a compound_code (global suffix + a
+ * locality reference). This is the real OLC algorithm over a deterministic grid.
+ */
+const OLC_ALPHABET = '23456789CFGHJMPQRVWX';
+export function encodePlusCode(loc: LatLng, codeLength = 10): string {
+  const lat = Math.min(Math.max(loc.lat, -90), 90) + 90;
+  const lng = ((loc.lng + 180) % 360 + 360) % 360;
+  let code = '';
+  // First 10 chars: 5 pairs, each a base-20 digit for lat then lng.
+  let latPrecision = 20;
+  let lngPrecision = 20;
+  for (let i = 0; i < 5; i++) {
+    const latDigit = Math.floor(lat / latPrecision) % 20;
+    const lngDigit = Math.floor(lng / lngPrecision) % 20;
+    code += OLC_ALPHABET[latDigit];
+    code += OLC_ALPHABET[lngDigit];
+    if (i === 3) code += '+';
+    latPrecision /= 20;
+    lngPrecision /= 20;
+  }
+  return code.slice(0, codeLength + 1);
+}
+
+export function plusCodeFor(loc: LatLng, localityName: string): { global_code: string; compound_code: string } {
+  const global_code = encodePlusCode(loc);
+  // compound_code drops the 4-char area prefix and appends a locality reference.
+  const compound_code = `${global_code.slice(4)} ${localityName}`;
+  return { global_code, compound_code };
+}
+
+/** Deterministic next_page_token <-> offset codec for Places pagination. */
+export function encodePageToken(query: string, offset: number): string {
+  return Buffer.from(`${normalizeAddress(query)}::${offset}`).toString('base64url');
+}
+export function decodePageToken(token: string): { query: string; offset: number } | null {
+  try {
+    const [query, offsetStr] = Buffer.from(token, 'base64url').toString('utf8').split('::');
+    const offset = Number(offsetStr);
+    if (query === undefined || !Number.isFinite(offset)) return null;
+    return { query, offset };
+  } catch {
+    return null;
+  }
+}
+
+/** A faithful opening_hours block (weekday_text + periods) for a place. */
+export function openingHoursFor(p: CannedPlace): Record<string, unknown> {
+  const days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+  const periods = days.map((_d, i) => ({
+    open: { day: i, time: '0900' },
+    close: { day: i, time: '1700' },
+  }));
+  return {
+    open_now: true,
+    periods,
+    weekday_text: days.map((d) => `${d}: 9:00 AM – 5:00 PM`),
+  };
+}
+
+/** A faithful, deterministic set of reviews for a place. */
+export function reviewsFor(p: CannedPlace): Record<string, unknown>[] {
+  return [
+    {
+      author_name: 'A. Traveler',
+      rating: 5,
+      relative_time_description: 'a month ago',
+      text: `Great experience at ${p.name}.`,
+      time: 1700000000,
+      language: 'en',
+    },
+    {
+      author_name: 'B. Local',
+      rating: 4,
+      relative_time_description: '2 months ago',
+      text: `Solid spot in ${p.name}.`,
+      time: 1697000000,
+      language: 'en',
+    },
+  ];
+}