@volter/twin-googlemaps 0.1.0

package/dist/src/googlemaps-types.d.ts

@@ -0,0 +1,45 @@
+export type GoogleMapsRequest = {
+    method: string;
+    path: string;
+    body?: string;
+    root?: string;
+    readOnly?: boolean;
+    occurredAt?: string;
+    headers?: Record<string, string>;
+};
+export type GoogleMapsResponse = {
+    status: number;
+    body: unknown;
+};
+/** Web-service ("Maps") status enum shared across geocode/directions/etc. */
+export type MapsStatus = 'OK' | 'ZERO_RESULTS' | 'OVER_DAILY_LIMIT' | 'OVER_QUERY_LIMIT' | 'REQUEST_DENIED' | 'INVALID_REQUEST' | 'MAX_ELEMENTS_EXCEEDED' | 'MAX_WAYPOINTS_EXCEEDED' | 'MAX_ROUTE_LENGTH_EXCEEDED' | 'NOT_FOUND' | 'UNKNOWN_ERROR';
+export type LatLng = {
+    lat: number;
+    lng: number;
+};
+export type Viewport = {
+    northeast: LatLng;
+    southwest: LatLng;
+};
+export type AddressComponent = {
+    long_name: string;
+    short_name: string;
+    types: string[];
+};
+export type Geometry = {
+    location: LatLng;
+    location_type: 'ROOFTOP' | 'RANGE_INTERPOLATED' | 'GEOMETRIC_CENTER' | 'APPROXIMATE';
+    viewport: Viewport;
+    bounds?: Viewport;
+};
+export type GeocodeResult = {
+    address_components: AddressComponent[];
+    formatted_address: string;
+    geometry: Geometry;
+    place_id: string;
+    types: string[];
+    plus_code?: {
+        global_code: string;
+        compound_code: string;
+    };
+};

package/dist/src/googlemaps-types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/index.d.ts

@@ -0,0 +1,11 @@
+export { handleGoogleMapsTwinRequest } from './googlemaps-twin.js';
+export { createGoogleMapsTwinFetch, createGoogleMapsTwinServer, type GoogleMapsTwinFetchOptions } from './googlemaps-server.js';
+export { GOOGLEMAPS_API_BASE, googleMapsRequestForAction, liveGoogleMapsExecute, pullGoogleMapsGeocodes, pullGoogleMapsPlaces, pushGoogleMapsAction, syncGoogleMapsFromReal, } from './googlemaps-connector.js';
+export type { GoogleMapsExecute } from './googlemaps-connector.js';
+export { GOOGLEMAPS_BUDGET_CEILING, GOOGLEMAPS_BUDGET_MAX_RETRY_AFTER_S, GOOGLEMAPS_BUDGET_WINDOW_MS, GOOGLEMAPS_CALL_WEIGHTS, GOOGLEMAPS_RATE_BUDGET, GoogleMapsBudget, GoogleMapsBudgetError, googleMapsBudgetPath, googleMapsCallWeight, splitGoogleMapsPath, } from './googlemaps-budget.js';
+export type { GoogleMapsBudgetErrorKind, GoogleMapsBudgetOptions, GoogleMapsBudgetReservation, GoogleMapsBudgetSnapshot, } from './googlemaps-budget.js';
+export { allPlaces, deterministicDuration, deterministicElevation, deterministicLatLng, deterministicTimeZone, distanceText, durationText, encodePolyline, findPlaceById, findPlaceByLatLng, findPlaceByText, geocodeResultFromPlace, haversineMeters, isZeroResultsQuery, normalizeAddress, stableHash, synthGeocodeResult, viewportAround, } from './googlemaps-data.js';
+export type { CannedPlace } from './googlemaps-data.js';
+export type { AddressComponent, GeocodeResult, Geometry, GoogleMapsRequest, GoogleMapsResponse, LatLng, MapsStatus, Viewport, } from './googlemaps-types.js';
+import { type TwinPack } from '@volter/world-core';
+export declare const pack: TwinPack;

package/dist/src/index.js

@@ -0,0 +1,65 @@
+export { handleGoogleMapsTwinRequest } from "./googlemaps-twin.js";
+export { createGoogleMapsTwinFetch, createGoogleMapsTwinServer } from "./googlemaps-server.js";
+export { GOOGLEMAPS_API_BASE, googleMapsRequestForAction, liveGoogleMapsExecute, pullGoogleMapsGeocodes, pullGoogleMapsPlaces, pushGoogleMapsAction, syncGoogleMapsFromReal, } from "./googlemaps-connector.js";
+// The client-side rate budget — the fail-closed backstop `liveGoogleMapsExecute` routes every live
+// request through. The mechanism is the kernel's (`@volter/world-core` → rateBudget.ts); these are this
+// vendor's numbers and the typed bindings around them.
+export { GOOGLEMAPS_BUDGET_CEILING, GOOGLEMAPS_BUDGET_MAX_RETRY_AFTER_S, GOOGLEMAPS_BUDGET_WINDOW_MS, GOOGLEMAPS_CALL_WEIGHTS, GOOGLEMAPS_RATE_BUDGET, GoogleMapsBudget, GoogleMapsBudgetError, googleMapsBudgetPath, googleMapsCallWeight, splitGoogleMapsPath, } from "./googlemaps-budget.js";
+export { allPlaces, deterministicDuration, deterministicElevation, deterministicLatLng, deterministicTimeZone, distanceText, durationText, encodePolyline, findPlaceById, findPlaceByLatLng, findPlaceByText, geocodeResultFromPlace, haversineMeters, isZeroResultsQuery, normalizeAddress, stableHash, synthGeocodeResult, viewportAround, } from "./googlemaps-data.js";
+import { registerPack } from '@volter/world-core';
+import { GOOGLEMAPS_RATE_BUDGET as RATE_BUDGET } from "./googlemaps-budget.js";
+import { performGoogleMapsAction, syncGoogleMapsFromRemote } from "./googlemaps-connector.js";
+export const pack = {
+    // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of the real
+    // state system. Moved 2026-09-08. The Google Maps APIs answer questions and accept no writes, so `perform`
+    // settles every entry with that reason and only `refresh` ever crosses.
+    protocol: '2',
+    refresh: { every: '1h', onDemand: { atMost: '60s' } }, // an address's geocode moves rarely; there are no webhooks
+    stateSystem: { perform: performGoogleMapsAction, refresh: syncGoogleMapsFromRemote },
+    // the round trip seeds one address's geocode — the twin's own door, because the vendor has no writable
+    // surface at all
+    roundTrip: { method: 'POST', path: '/twin/geocode?key=round-trip', body: { address: '1600 Amphitheatre Parkway, Mountain View, CA', result: { formatted_address: '1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA', geometry: { location: { lat: 37.4224, lng: -122.0842 } }, place_id: 'ChIJ_round_trip', types: ['street_address'] } } },
+    // a geocode stands alone — no subject here names another, so there is nothing for rule 5 to follow
+    references: [],
+    // The LEGACY endpoints this connector calls (Geocoding, Place Details) authenticate with `key=`
+    // in the QUERY STRING. Google's newer surfaces (Places API New, Address Validation) accept
+    // `X-Goog-Api-Key` instead — if this pack ever pulls through those, the strategy becomes a header
+    // and this line is where that is said (googlemaps-auth.ts documents both).
+    auth: { in: 'query', name: 'key' },
+    parityOrigin: 'http://twin',
+    // shapeParity is NOT held, for a structural reason rather than a divergence: the Geocoding API has no
+    // inventory to enumerate — you ask it about an address, and nothing lists what you have asked. A refresh
+    // into a fresh root therefore has nothing to ask about, so the gate's comparison has no ground here.
+    vendor: 'googlemaps',
+    // The SAME object googlemaps-budget.ts declares at module load — one source of truth, so
+    // registering the pack and importing the connector arm identical numbers.
+    rateBudget: RATE_BUDGET,
+    transport: 'rest',
+    archetype: 'crud',
+    bin: 'world-googlemaps',
+    // The subject types the twin SERVES over its own API — the R2 resource-level claim.
+    // `place` is deliberately NOT here: it is a connector-side projection that only
+    // `pullGoogleMapsPlaces` / `syncGoogleMapsFromReal` fold in from a real account through an
+    // injected client, and no route reads it back — Place Details answers from the canned
+    // corpus (`findPlaceById` over googlemaps-data.ts's PLACES), never from stored state.
+    // `geocode` stays because the twin both writes it (POST /twin/geocode) and serves it
+    // (the Geocoding route's stateful override); `audit` because GET /twin/audit reads it.
+    resources: ['geocode', 'audit'],
+    specSource: 'Google Maps Platform web-service APIs (Geocoding, Distance Matrix, Directions, Places + Places API New, Roads, Time Zone, Elevation, Geolocation, Address Validation, Static Maps, Street View Static) — deterministic canned data in faithful response shapes',
+    description: 'Google Maps Platform twin — deterministic, offline replicas of the Maps web-service APIs in vendor-faithful response shapes with the real status semantics + API-key gate.',
+    // Adoption + interception, moved off the central maps unchanged (descriptor-first back-migration, adding-a-twin.md §3,
+    // 2026-08-31): the official Node client, the `@googlemaps/` scope, the
+    // GOOGLEMAPS_* credential stem, and maps.googleapis.com — one of several *.googleapis.com
+    // hosts kept as separate vendors rather than one 'google' (see webrisk, gemini).
+    adoption: {
+        // Google's official Maps Platform Python client (googlemaps/google-maps-services-python).
+        pypi: ['googlemaps'],
+        sdks: ['@googlemaps/google-maps-services-js'],
+        scopes: ['@googlemaps/'],
+        envStems: ['GOOGLEMAPS'],
+    },
+    hosts: [{ host: 'maps.googleapis.com' }],
+    browserRouting: { apiPathPrefix: '/maps/api/', loaderHost: 'https://maps.googleapis.com' },
+};
+// registered at import: the kernel learns the pack's state system (protocol 2)
+registerPack(pack);

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@volter/twin-googlemaps",
+  "version": "0.1.0",
+  "description": "Local Google Maps Platform twin built on @volter/world-core.",
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/googlemaps"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/googlemaps#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-googlemaps": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@googlemaps/google-maps-services-js": "^3.4.0",
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createGoogleMapsTwinServer } from './googlemaps-server.ts';
+
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only');
+
+if (cmd === 'serve') {
+  const server = await createGoogleMapsTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
+  process.stdout.write(`googlemaps twin${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${server.port}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'conformance') {
+  const { checkGoogleMapsConformance } = await import('./googlemaps-conformance.ts');
+  const report = await checkGoogleMapsConformance({ ...(root ? { root } : {}) });
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+} else {
+  process.stdout.write('Usage: world-googlemaps serve|conformance [--port N] [--root DIR] [--read-only]\n');
+}

package/src/googlemaps-auth.ts

@@ -0,0 +1,52 @@
+import type { GoogleMapsResponse } from './googlemaps-types.ts';
+
+/**
+ * Google Maps Platform web services authenticate with an API key, passed either
+ * as the `key=` query parameter (legacy web-service APIs: Geocoding, Directions,
+ * Distance Matrix, Roads, Time Zone, Elevation, Geolocation, Static Maps, Street
+ * View) or as the `X-Goog-Api-Key` header (Places API New, Address Validation).
+ *
+ * Missing/invalid keys yield REQUEST_DENIED in the API's own status envelope
+ * (HTTP 200 with `status:"REQUEST_DENIED"` for legacy web services; a 403
+ * google.rpc.Status for the New/v1 APIs). A sentinel key lets verifies exercise
+ * OVER_QUERY_LIMIT / OVER_DAILY_LIMIT.
+ */
+
+export type MapsAuthResult =
+  | { ok: true; key: string }
+  | { ok: false; status: 'REQUEST_DENIED' | 'OVER_QUERY_LIMIT' | 'OVER_DAILY_LIMIT'; message: string };
+
+// Referenced so the GoogleMapsResponse type import stays meaningful for callers.
+export type _AuthResponse = GoogleMapsResponse;
+
+export function header(headers: Record<string, string> | undefined, name: string): string | undefined {
+  if (!headers) return undefined;
+  const lower = name.toLowerCase();
+  for (const [k, v] of Object.entries(headers)) if (k.toLowerCase() === lower) return v;
+  return undefined;
+}
+
+/** Extract the API key from `key=` query param or the `X-Goog-Api-Key` header. */
+export function extractKey(url: URL, headers: Record<string, string> | undefined): string | undefined {
+  return url.searchParams.get('key') ?? header(headers, 'x-goog-api-key') ?? undefined;
+}
+
+/**
+ * Validate the API key gate. When `headers` is entirely undefined (the in-process
+ * handler default used by most internal callers/tests) and no `key=` is present,
+ * auth is treated as pre-satisfied so offline flows keep working. When a key is
+ * supplied it is validated; the sentinel keys drive the quota error paths.
+ */
+export function authenticate(url: URL, headers: Record<string, string> | undefined): MapsAuthResult {
+  const key = extractKey(url, headers);
+  if (key === undefined) {
+    // Implicit auth: only when callers don't model headers at all.
+    if (headers === undefined) return { ok: true, key: 'twin-implicit' };
+    return { ok: false, status: 'REQUEST_DENIED', message: 'The provided API key is invalid or missing. Pass `key=` or the X-Goog-Api-Key header.' };
+  }
+  if (!key.trim()) return { ok: false, status: 'REQUEST_DENIED', message: 'The provided API key is empty.' };
+  if (key === 'over-query-limit') return { ok: false, status: 'OVER_QUERY_LIMIT', message: 'You have exceeded your rate-limit for this API.' };
+  if (key === 'over-daily-limit') return { ok: false, status: 'OVER_DAILY_LIMIT', message: 'You have exceeded your daily request quota for this API.' };
+  if (key === 'request-denied') return { ok: false, status: 'REQUEST_DENIED', message: 'This API key is not authorized to use this service or API.' };
+  return { ok: true, key };
+}

package/src/googlemaps-budget.ts

@@ -0,0 +1,168 @@
+// Google Maps Platform's CLIENT-SIDE RATE BUDGET — the pack's DECLARATION (the numbers) plus the
+// thin typed bindings `liveGoogleMapsExecute` uses. The MECHANISM — the durable token-keyed ledger,
+// the rolling window, reserve-under-lock, the `Retry-After`/429 cooldown, fail-CLOSED on a corrupt
+// ledger — lives ONCE in the vendor-agnostic kernel (`@volter/world-core` → `rateBudget.ts`). Read that
+// module's header for the full rationale AND for the honest list of what the guard does not
+// guarantee (an injected clock or ledger path still defeats it — it guards carelessness, not malice).
+//
+// ── WHY THIS EXISTS: THE MISSING CHOKE POINT ─────────────────────────────────────────────────
+// A ~4.5-day Figma token lockout (2026-07-25) came from a burst of raw vendor calls made OUTSIDE
+// any guarded client. The lesson generalized: a pack with no single construction site for its live
+// client is a pack that CANNOT be protected, because there is nowhere for a guard to sit.
+//
+// This connector took an INJECTED `GoogleMapsExecute` and nothing more. That is excellent for
+// testing — every verify runs offline against a fake — but it meant the pack itself never built a
+// network-calling execute, so a rate budget could only ever be something the CALLER opted into.
+// `liveGoogleMapsExecute` (in `googlemaps-connector.ts`) is the choke point that fixes that: the ONE
+// place in this pack that turns a credential into a function that really talks to
+// maps.googleapis.com, with this budget charged BEFORE every request goes out. The injected-function
+// contract is untouched — the factory is an ADDITION for production callers, not a replacement.
+//
+// ── HOW THE CEILING WAS CHOSEN ───────────────────────────────────────────────────────────────
+// Google DOES publish a scalar for the endpoint this connector leans on hardest: the Geocoding API
+// is documented as rate-limited to 3,000 QPM (queries per minute), counted as the sum of client-side
+// and server-side queries (developers.google.com/maps/documentation/geocoding/usage-and-billing). The
+// per-PROJECT scoping and the 'temporarily blocked' warning come from the Maps Platform FAQ's
+// usage-limits section, not from the Geocoding page — two sources, cited separately (§9, 2026-07-26). Exceeding a product's QPM returns an error, and REPEATEDLY exceeding it can
+// get access "temporarily blocked" — the lockout shape this guard exists to prevent.
+//
+// So: 300 weighted units per 60s, with a geocode priced at 1. That is 300 geocodes a minute — TEN
+// PERCENT of the documented limit — while a careless loop is refused after 300 rather than running
+// until Google blocks the project. The kernel independently caps any declaration at 1,000 units per
+// window and 20 units/second, so modeling the vendor's 3,000 QPM literally was never on the table;
+// 10% is a deliberate choice inside that cap, sized so the legitimate workload (a pull of a few
+// dozen addresses) fits many times over in one window.
+//
+// ── HOW THE WEIGHTS WERE CHOSEN (and what is a judgement call) ────────────────────────────────
+// Google counts REQUESTS, per API method per project, so weight 1 is the faithful price for a call
+// and the geocode endpoint — the one with a VERIFIED, generous 3,000 QPM figure — gets it.
+//
+// Everything else is priced at `defaultWeight` (2) or above, never below, because Google documents
+// that "the rate limit per minute is per API method per project" WITHOUT publishing the per-method
+// numbers for the Places surfaces. An endpoint whose limit we cannot read is an endpoint we must not
+// assume is generous.
+//
+// Place Details is priced at 4 — above default. That is a JUDGEMENT CALL, not a published cost: it
+// is the only endpoint in this connector whose response is unbounded in size (a full place record),
+// and Google publishes no per-minute figure for it. Unknown limit + heaviest response ⇒ dearest
+// price. No billing figure is cited here because none was verified.
+import {
+  declareRateBudget,
+  rateBudgetPath,
+  rateBudgetWeight,
+  RateBudget,
+  type RateBudgetDeclaration,
+  type RateBudgetOptions,
+  type RateBudgetReservation,
+  type RateBudgetSnapshot,
+} from '@volter/world-core';
+
+const VENDOR = 'googlemaps';
+
+/** Rolling window, in ms. Spend older than this is pruned. Matches Google's own per-MINUTE quotas. */
+export const GOOGLEMAPS_BUDGET_WINDOW_MS = 60_000;
+
+/**
+ * Weighted units allowed inside one window. 300 geocodes/60s = 10% of the documented 3,000 QPM.
+ */
+export const GOOGLEMAPS_BUDGET_CEILING = 300;
+
+/** Seconds. A `Retry-After` above this means the project is throttled hard — fail loudly. */
+export const GOOGLEMAPS_BUDGET_MAX_RETRY_AFTER_S = 300;
+
+/** Per-call cost, keyed by the `<METHOD> <path>` this connector is about to request. See the header. */
+export const GOOGLEMAPS_CALL_WEIGHTS = {
+  /** `GET /maps/api/geocode/json` — documented 3,000 QPM, the most generous figure Google publishes. */
+  geocode: 1,
+  /** `GET /maps/api/place/details/json` — unbounded response, NO published per-minute figure. */
+  placeDetails: 4,
+  /** Anything this pack has not classified. Priced like a read, never free. */
+  other: 2,
+} as const;
+
+/**
+ * THE PACK'S DECLARATION — pure data, the only Google-specific thing in the whole budget. Rules are
+ * ordered and first-match-wins, and they are keyed on `"<METHOD> <pathname>"` (not the bare path):
+ * Google's quotas are per API METHOD, and a write to a surface is not the same call as a read of it,
+ * so the method has to be part of what gets priced.
+ *
+ * Also exported as `pack.rateBudget` (see index.ts), so `registerPack` arms it too.
+ */
+export const GOOGLEMAPS_RATE_BUDGET: RateBudgetDeclaration = {
+  windowMs: GOOGLEMAPS_BUDGET_WINDOW_MS,
+  ceiling: GOOGLEMAPS_BUDGET_CEILING,
+  defaultWeight: GOOGLEMAPS_CALL_WEIGHTS.other,
+  maxRetryAfterSeconds: GOOGLEMAPS_BUDGET_MAX_RETRY_AFTER_S,
+  rules: [
+    { match: '^GET /maps/api/place/details', weight: GOOGLEMAPS_CALL_WEIGHTS.placeDetails },
+    { match: '^GET /maps/api/geocode/', weight: GOOGLEMAPS_CALL_WEIGHTS.geocode },
+  ],
+  reason:
+    'Google documents the Geocoding API as rate-limited to 3,000 QPM (queries per minute), counted as the ' +
+    'sum of client-side and server-side queries, and the Maps Platform FAQ warns that repeatedly exceeding ' +
+    'a product\'s QPM can get access temporarily blocked. 300 weighted units / 60s prices a geocode at 1, so the ceiling is ' +
+    '10% of that documented limit — many times a legitimate pull of a few dozen addresses, and a hard stop ' +
+    'for the careless loop that the ~4.5-day Figma lockout (2026-07-25) showed the cost of. Place Details ' +
+    'costs 4 because Google publishes NO per-minute figure for it and its response is the pack\'s largest — ' +
+    'a judgement call, not a published cost.',
+};
+
+// Declared at module load, so merely importing this module (which `googlemaps-connector.ts` does) is
+// enough to arm the real ceiling. A budget constructed BEFORE this runs falls back to the kernel's
+// DEFAULT_RATE_BUDGET, which is tighter in call count but prices every endpoint at 2 — cheaper than
+// the weight below for Place Details — so "the fallback is always safer" would be a false comfort.
+// `RateBudget` reads its policy live precisely so this declaration takes effect the moment it lands,
+// and constructing through the subclass below (which imports this module) makes the ordering a
+// non-issue in practice.
+declareRateBudget(VENDOR, GOOGLEMAPS_RATE_BUDGET);
+
+/** Split a connector path (which carries its own query string) into pathname + parsed query. */
+export function splitGoogleMapsPath(path: string): { pathname: string; query: Record<string, string> } {
+  const q = path.indexOf('?');
+  if (q < 0) return { pathname: path, query: {} };
+  const query: Record<string, string> = {};
+  for (const [k, v] of new URLSearchParams(path.slice(q + 1))) query[k] = v;
+  return { pathname: path.slice(0, q), query };
+}
+
+/**
+ * Price one call. Keyed off the request the connector is ABOUT to make, so an unclassified endpoint
+ * still costs `defaultWeight` — an unknown endpoint must never be free.
+ */
+export function googleMapsCallWeight(method: string, path: string): number {
+  const { pathname, query } = splitGoogleMapsPath(path);
+  return rateBudgetWeight(VENDOR, `${(method || 'GET').toUpperCase()} ${pathname}`, query);
+}
+
+/** Where Google Maps' ledger lives. API-key-keyed and cwd-independent by default (the quota is per
+ *  project/key, so a cwd-scoped ledger would hand the same key a fresh allowance in every checkout,
+ *  worktree and CI matrix leg); pass `root` to opt into world-scoped accounting instead. */
+export function googleMapsBudgetPath(opts: { root?: string; token?: string } | string = {}): string {
+  const o = typeof opts === 'string' ? { root: opts } : opts;
+  // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through (TypeScript's
+  // excess-property check only catches object literals) must not redirect this pack's ledger to
+  // another vendor's file.
+  return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+
+/** Construction options for Google Maps' budget. The vendor is fixed; everything else may only TIGHTEN. */
+export type GoogleMapsBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+
+/**
+ * Google Maps' budget — the shared kernel guard bound to this vendor's declaration. A real subclass,
+ * not an alias, so `budget instanceof GoogleMapsBudget` in `liveGoogleMapsExecute` still means "a
+ * budget that accounts against GOOGLEMAPS' ledger under GOOGLEMAPS' ceiling": another vendor's
+ * `RateBudget` (with its own, possibly larger, ceiling) is NOT assignable there.
+ */
+export class GoogleMapsBudget extends RateBudget {
+  constructor(opts: GoogleMapsBudgetOptions = {}) {
+    super({ ...opts, vendor: VENDOR });
+  }
+}
+
+/** The typed refusal. One error class shared with every other vendor's budget; `err.vendor` says
+ *  which one refused, and `err.kind` says why. */
+export { RateBudgetError as GoogleMapsBudgetError } from '@volter/world-core';
+export type { RateBudgetErrorKind as GoogleMapsBudgetErrorKind } from '@volter/world-core';
+export type GoogleMapsBudgetReservation = RateBudgetReservation;
+export type GoogleMapsBudgetSnapshot = RateBudgetSnapshot;