@k2b/cloud 0.41.0 → 0.42.0

package/src/services/geo/geoapify-route.ts

@@ -0,0 +1,93 @@
+import { z } from "zod";
+import type { GeoProvenance } from "../../contracts/geo";
+import type { GeoRouteLeg, GeoRouteOptions, GeoRouteResolvedStop } from "../../contracts/geo-route";
+import { GEO_MAX_ROUTE_RESPONSE_BYTES } from "./cache";
+import { GeoError, GeoProviderError } from "./errors";
+import { compactRouteLine } from "./route-geometry";
+
+const coordinate = z.tuple([z.number().min(-180).max(180), z.number().min(-90).max(90)]);
+const point = z.object({ lat: z.number().min(-90).max(90), lon: z.number().min(-180).max(180) });
+const resultSchema = z.object({
+  results: z
+    .array(
+      z.object({
+        units: z.literal("metric"),
+        distance_units: z.literal("meters"),
+        distance: z.number().nonnegative(),
+        time: z.number().nonnegative(),
+        waypoints: z
+          .array(z.object({ original_index: z.number().int().min(0).max(25), location: coordinate }))
+          .min(2)
+          .max(26),
+        legs: z
+          .array(
+            z.object({
+              distance: z.number().nonnegative(),
+              time: z.number().nonnegative(),
+            }),
+          )
+          .min(1)
+          .max(25),
+        // Even the shortest JSON coordinate pair takes at least 17 bytes. The response byte cap is authoritative.
+        geometry: z
+          .array(
+            z
+              .array(point)
+              .min(2)
+              .max(Math.floor(GEO_MAX_ROUTE_RESPONSE_BYTES / 17)),
+          )
+          .max(25),
+      }),
+    )
+    .max(1),
+});
+const pricedDistanceSchema = z.object({
+  results: z
+    .array(z.object({ units: z.literal("metric"), distance_units: z.literal("meters"), distance: z.number().nonnegative() }))
+    .length(1),
+});
+export const parseGeoapifyRoute = (
+  raw: unknown,
+  input: readonly GeoRouteResolvedStop[],
+  options: GeoRouteOptions,
+  optimize: boolean,
+  provenance: GeoProvenance,
+) => {
+  const priced = pricedDistanceSchema.safeParse(raw);
+  const actualDistance = priced.success ? priced.data.results[0]!.distance : undefined;
+  const failed = () =>
+    new GeoProviderError("GEO_PROVIDER_FAILED", actualDistance === undefined ? "unknown" : "known", false, actualDistance);
+  const parsed = resultSchema.safeParse(raw);
+  if (!parsed.success) throw failed();
+  const feature = parsed.data.results[0];
+  if (!feature) throw new GeoError("GEO_NO_ROUTE");
+  const p = feature,
+    indexes = p.waypoints.map((w) => w.original_index);
+  if (
+    p.legs.length !== input.length - 1 ||
+    indexes.length !== input.length ||
+    new Set(indexes).size !== input.length ||
+    indexes.some((i) => i >= input.length) ||
+    indexes[0] !== 0 ||
+    indexes.at(-1) !== input.length - 1 ||
+    (!optimize && indexes.some((value, i) => value !== i)) ||
+    feature.geometry.length !== p.legs.length ||
+    Math.abs(p.legs.reduce((sum, leg) => sum + leg.distance, 0) - p.distance) > 1 ||
+    Math.abs(p.legs.reduce((sum, leg) => sum + leg.time, 0) - p.time) > 1
+  )
+    throw failed();
+  const stops = indexes.map((i) => input[i]!);
+  const legs: GeoRouteLeg[] = p.legs.map((leg, i) => {
+    const line = feature.geometry[i]!;
+    return {
+      fromStopId: stops[i]!.id,
+      toStopId: stops[i + 1]!.id,
+      options,
+      distanceMeters: leg.distance,
+      durationSeconds: leg.time,
+      ...compactRouteLine(line),
+      provenance,
+    };
+  });
+  return { stops, legs, distanceMeters: p.distance };
+};

package/src/services/geo/geoapify.ts

@@ -0,0 +1,281 @@
+import { z } from "zod";
+import { readBoundedJson } from "../../_internal/bounded-json";
+import {
+  GEO_CATEGORIES,
+  type GeoAddress,
+  type GeoAutocompleteInput,
+  type GeoFunction,
+  type GeoGeocodeInput,
+  type GeoPlace,
+  type GeoPlaceSearchInput,
+  type GeoPoint,
+  type GeoProvenance,
+  type GeoReverseInput,
+} from "../../contracts/geo";
+import type { GeoRouteOptions, GeoRouteResolvedStop } from "../../contracts/geo-route";
+import { EMPTY_NETWORK_ALLOWLIST } from "../../shared/network-address";
+import { createAllowedNetworkFetch } from "../allowed-network-fetch";
+import { GEO_TIMEOUT_MS } from "./bucket";
+import { GEO_MAX_JSON_BYTES, GEO_MAX_ROUTE_RESPONSE_BYTES } from "./cache";
+import { GeoProviderError } from "./errors";
+import { parseGeoapifyRoute } from "./geoapify-route";
+
+const GEOAPIFY_ORIGIN = "https://api-eu.geoapify.com";
+const guardedFetch = createAllowedNetworkFetch(EMPTY_NETWORK_ALLOWLIST);
+export type GeoFetch = (url: URL, init: RequestInit) => Promise<Response>;
+const text = z.string().max(300).optional();
+const rawProperties = z.object({
+  lat: z.number().min(-90).max(90),
+  lon: z.number().min(-180).max(180),
+  address_line1: text,
+  postcode: text,
+  city: text,
+  town: text,
+  village: text,
+  state: text,
+  region: text,
+  country_code: z.string().max(2).optional(),
+  formatted: z.string().max(600).optional(),
+  street: text,
+  housenumber: text,
+  name: text,
+  rank: z
+    .object({
+      confidence: z.number().min(0).max(1).optional(),
+      confidence_building_level: z.number().min(0).max(1).optional(),
+      match_type: z.string().optional(),
+    })
+    .optional(),
+  result_type: z.string().optional(),
+  place_id: z.string().min(1).max(2048).optional(),
+  categories: z.array(z.string().max(100)).max(20).optional(),
+  distance: z.number().nonnegative().optional(),
+  opening_hours: z.string().max(1000).optional(),
+  website: z.string().max(1000).optional(),
+  contact: z.object({ phone: text }).optional(),
+  datasource: z
+    .object({
+      raw: z.object({ opening_hours: z.string().max(1000).optional(), website: z.string().max(1000).optional(), phone: text }).optional(),
+    })
+    .optional(),
+});
+type RawProperties = z.infer<typeof rawProperties>;
+const collection = z.object({
+  type: z.literal("FeatureCollection"),
+  features: z
+    .array(
+      z.object({
+        type: z.literal("Feature"),
+        properties: rawProperties,
+        geometry: z.object({ type: z.string(), coordinates: z.unknown() }).nullable(),
+      }),
+    )
+    .max(20),
+});
+export const geoProvenance = (now: Date): GeoProvenance => ({
+  provider: "geoapify",
+  attribution: { text: "Geoapify · OpenStreetMap", links: ["https://geoapify.com", "https://www.openstreetmap.org/copyright"] },
+  computedAt: now.toISOString(),
+});
+const address = (p: RawProperties, provenance: GeoProvenance): GeoAddress => ({
+  line1: p.address_line1 ?? [p.street, p.housenumber].filter(Boolean).join(" "),
+  postalCode: p.postcode ?? "",
+  city: p.city ?? p.town ?? p.village ?? "",
+  stateRegion: p.state ?? p.region ?? "",
+  countryCode: p.country_code?.toUpperCase() ?? "",
+  point: { lat: p.lat, lon: p.lon },
+  formatted: p.formatted ?? p.address_line1 ?? "",
+  confidence: p.rank?.confidence ?? null,
+  provenance,
+});
+const areaFilter = (area: NonNullable<GeoAutocompleteInput["area"]>) =>
+  area.type === "bbox"
+    ? `rect:${area.west},${area.south},${area.east},${area.north}`
+    : `circle:${area.point.lon},${area.point.lat},${area.radiusMeters}`;
+/** Only these transport failures prove no HTTP request could have been delivered. Never retry resets, timeouts or aborts. */
+export const geoNeverSent = (error: unknown): boolean => {
+  const parsed = z.object({ code: z.string() }).safeParse(error);
+  return (
+    parsed.success &&
+    [
+      "ENOTFOUND",
+      "EAI_AGAIN",
+      "ECONNREFUSED",
+      "ERR_TLS_CERT_ALTNAME_INVALID",
+      "CERT_HAS_EXPIRED",
+      "DEPTH_ZERO_SELF_SIGNED_CERT",
+      "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+    ].includes(parsed.data.code)
+  );
+};
+export class GeoapifyAdapter {
+  constructor(private readonly options: { fetch?: GeoFetch; now?: () => Date } = {}) {}
+  private async requestJson(
+    fn: GeoFunction,
+    params: URLSearchParams,
+    key: string,
+    locale: string,
+    callerSignal?: AbortSignal,
+    body?: unknown,
+  ): Promise<unknown> {
+    const url = new URL(
+      fn === "route" ? "/v1/routing" : fn === "places" ? "/v2/places" : `/v1/geocode/${fn === "geocode" ? "search" : fn}`,
+      GEOAPIFY_ORIGIN,
+    );
+    const lang = new Intl.Locale(locale).language;
+    params.set("lang", lang);
+    params.set("format", fn === "route" ? "json" : "geojson");
+    // Places v2 has one GeoJSON representation and does not accept a format parameter.
+    if (fn === "places") params.delete("format");
+    url.search = params.toString();
+    const deadline = AbortSignal.timeout(GEO_TIMEOUT_MS[fn]);
+    const signal = callerSignal ? AbortSignal.any([callerSignal, deadline]) : deadline;
+    const init: RequestInit = {
+      method: body ? "POST" : "GET",
+      credentials: "omit",
+      redirect: "error",
+      signal,
+      headers: { "x-api-key": key, accept: "application/json", ...(body ? { "content-type": "application/json" } : {}) },
+      ...(body ? { body: JSON.stringify({ ...z.record(z.string(), z.unknown()).parse(body), lang }) } : {}),
+    };
+    for (let attempt = 0; attempt < 2; attempt++) {
+      if (signal.aborted) throw new GeoProviderError("GEO_PROVIDER_FAILED", "none");
+      let response: Response;
+      try {
+        response = await (this.options.fetch ?? guardedFetch)(url, init);
+      } catch (error) {
+        const neverSent = !signal.aborted && geoNeverSent(error);
+        if (neverSent && attempt === 0) continue;
+        throw new GeoProviderError("GEO_PROVIDER_FAILED", neverSent ? "none" : "unknown");
+      }
+      if (!response.ok) {
+        await response.body?.cancel().catch(() => {});
+        throw new GeoProviderError(
+          response.status === 429 ? "GEO_BUSY" : "GEO_PROVIDER_FAILED",
+          "known",
+          [401, 403].includes(response.status),
+        );
+      }
+      // Bound raw provider responses; routing geometry is compacted to the smaller public result budget.
+      const json = await readBoundedJson(response, fn === "route" ? GEO_MAX_ROUTE_RESPONSE_BYTES : GEO_MAX_JSON_BYTES);
+      if (signal.aborted) throw new GeoProviderError("GEO_PROVIDER_FAILED", "unknown");
+      if (!json.ok || JSON.stringify(json.data).includes(JSON.stringify(key).slice(1, -1)))
+        throw new GeoProviderError("GEO_PROVIDER_FAILED", fn === "route" ? "unknown" : "known");
+      return json.data;
+    }
+    throw new GeoProviderError("GEO_PROVIDER_FAILED", "none");
+  }
+  private async request(fn: GeoFunction, params: URLSearchParams, key: string, locale: string, signal?: AbortSignal, body?: unknown) {
+    const parsed = collection.safeParse(await this.requestJson(fn, params, key, locale, signal, body));
+    if (!parsed.success) throw new GeoProviderError("GEO_PROVIDER_FAILED", "known");
+    return parsed.data.features.map((feature) => feature.properties);
+  }
+  async route(
+    stops: readonly GeoRouteResolvedStop[],
+    options: GeoRouteOptions,
+    optimize: boolean,
+    key: string,
+    locale: string,
+    signal?: AbortSignal,
+  ) {
+    const params = new URLSearchParams({
+      waypoints: stops.map((stop) => `${stop.point.lat},${stop.point.lon}`).join("|"),
+      mode: options.mode === "bike" ? "bicycle" : options.mode === "walk" ? "walk" : "drive",
+      units: "metric",
+      traffic: "free_flow",
+      intermediate_waypoint_mode: "stopover",
+      optimize_stops: String(optimize),
+    });
+    if (options.avoid?.length) params.set("avoid", options.avoid.join("|"));
+    return parseGeoapifyRoute(await this.requestJson("route", params, key, locale, signal), stops, options, optimize, this.provenance());
+  }
+  private provenance() {
+    return geoProvenance((this.options.now ?? (() => new Date()))());
+  }
+  async autocomplete(input: GeoAutocompleteInput, key: string, locale: string, signal?: AbortSignal) {
+    const params = new URLSearchParams({ text: input.text, limit: String(input.limit ?? 5) });
+    if (input.type) params.set("type", input.type);
+    const filters = [
+      input.countryCode ? `countrycode:${input.countryCode.toLowerCase()}` : null,
+      input.area ? areaFilter(input.area) : null,
+    ].filter((v) => v !== null);
+    if (filters.length) params.set("filter", filters.join("|"));
+    if (input.bias) params.set("bias", `proximity:${input.bias.lon},${input.bias.lat}`);
+    const values = await this.request("autocomplete", params, key, locale, signal);
+    const provenance = this.provenance();
+    return { suggestions: values.slice(0, input.limit ?? 5).map((p) => address(p, provenance)), provenance };
+  }
+  async geocode(input: GeoGeocodeInput, key: string, locale: string, signal?: AbortSignal) {
+    const params = new URLSearchParams({ limit: "5" });
+    if (input.text) params.set("text", input.text);
+    if (input.fields)
+      for (const [field, name] of [
+        ["line1", "street"],
+        ["postalCode", "postcode"],
+        ["city", "city"],
+        ["stateRegion", "state"],
+        ["country", "country"],
+      ] as const) {
+        const value = input.fields[field];
+        if (value) params.set(name, value);
+      }
+    if (input.countryCode) params.set("filter", `countrycode:${input.countryCode.toLowerCase()}`);
+    const raw = await this.request("geocode", params, key, locale, signal);
+    const provenance = this.provenance();
+    // No unverified uniqueness claim: all candidates with confidence >= .5 are plausible.
+    const candidates = raw
+      .slice(0, 5)
+      .filter((p) => (p.rank?.confidence ?? 0) >= 0.5)
+      .map((p) => address(p, provenance));
+    return { candidates, provenance };
+  }
+  async reverse(input: GeoReverseInput, key: string, locale: string, signal?: AbortSignal) {
+    const raw = await this.request(
+      "reverse",
+      new URLSearchParams({ lat: String(input.point.lat), lon: String(input.point.lon), limit: "1" }),
+      key,
+      locale,
+      signal,
+    );
+    const provenance = this.provenance();
+    return { address: raw[0] ? address(raw[0], provenance) : null, provenance };
+  }
+  async places(input: GeoPlaceSearchInput, key: string, locale: string, signal?: AbortSignal, line?: readonly GeoPoint[]) {
+    const categories = input.categories.map((category) => GEO_CATEGORIES[category]);
+    const params = new URLSearchParams({ limit: String(input.limit ?? 20) });
+    let body: unknown;
+    if (input.along && line)
+      body = {
+        categories,
+        limit: input.limit ?? 20,
+        filter: {
+          type: "polyline",
+          geometry: { type: "LineString", coordinates: line.map((p) => [p.lon, p.lat]) },
+          buffer: input.along.bufferMeters ?? 1000,
+        },
+      };
+    else {
+      params.set("categories", categories.join(","));
+      if (input.near) params.set("bias", `proximity:${input.near.lon},${input.near.lat}`);
+      if (input.area) params.set("filter", areaFilter(input.area));
+    }
+    const raw = await this.request("places", params, key, locale, signal, body);
+    const provenance = this.provenance();
+    const places: GeoPlace[] = raw.slice(0, input.limit ?? 20).map((p) => {
+      if (!p.place_id) throw new GeoProviderError("GEO_PROVIDER_FAILED", "known");
+      return {
+        id: p.place_id,
+        name: p.name ?? p.address_line1 ?? "",
+        categories: p.categories ?? [],
+        point: { lat: p.lat, lon: p.lon },
+        address: address(p, provenance),
+        distanceMeters: p.distance,
+        openingHours: p.opening_hours ?? p.datasource?.raw?.opening_hours,
+        website: p.website ?? p.datasource?.raw?.website,
+        phone: p.contact?.phone ?? p.datasource?.raw?.phone,
+        provenance,
+      };
+    });
+    return { places, provenance };
+  }
+}

package/src/services/geo/ledger.ts

@@ -0,0 +1,122 @@
+import { type SQL, sql } from "bun";
+import type { AccessSubject, CapabilityExecutionContext } from "../../contracts";
+import { audit } from "../audit";
+import { GeoError } from "./errors";
+import type { GeoConfig } from "./settings";
+
+export type GeoBudgetConfig = Pick<GeoConfig, "timezone" | "monthlyCredits" | "personDailyCredits">;
+export type GeoPeriod = { period: string; resetsAt: string };
+export const geoPeriods = (now: Date, timezone: string): { person: GeoPeriod; cloud: GeoPeriod } => {
+  const format = new Intl.DateTimeFormat("en-CA", { timeZone: timezone, year: "numeric", month: "2-digit", day: "2-digit" });
+  const local = (at: number) => {
+    const parts = format.formatToParts(new Date(at));
+    return ["year", "month", "day"].map((type) => parts.find((p) => p.type === type)!.value).join("-");
+  };
+  const day = local(now.getTime());
+  const boundary = (width: number, length: number): string => {
+    const current = day.slice(0, length);
+    let low = now.getTime(),
+      high = low + width;
+    while (high - low > 1) {
+      const mid = Math.floor((low + high) / 2);
+      if (local(mid).slice(0, length) === current) low = mid;
+      else high = mid;
+    }
+    return new Date(high).toISOString();
+  };
+  return {
+    person: { period: day, resetsAt: boundary(2 * 86400_000, 10) },
+    cloud: { period: day.slice(0, 7), resetsAt: boundary(32 * 86400_000, 7) },
+  };
+};
+export const geoSubjectKey = (subject: AccessSubject) =>
+  subject.type === "user" ? `user:${subject.userId}` : `service_account:${subject.serviceAccountId}`;
+export type GeoReservation = {
+  cost: number;
+  group: string;
+  rows: Array<{ scope: "cloud" | "person"; subject: string; period: string; resetsAt: string; limit: number }>;
+};
+const rowsFor = (subject: AccessSubject, config: GeoBudgetConfig, now: Date) => {
+  const periods = geoPeriods(now, config.timezone);
+  return [
+    { scope: "cloud", subject: "*", ...periods.cloud, limit: config.monthlyCredits * 1000 },
+    { scope: "person", subject: geoSubjectKey(subject), ...periods.person, limit: config.personDailyCredits * 1000 },
+  ] satisfies GeoReservation["rows"];
+};
+export const createGeoLedger = (db: SQL = sql) => ({
+  async reserve(subject: AccessSubject, config: GeoBudgetConfig, cost: number, group: string, now: Date): Promise<GeoReservation> {
+    if (!Number.isSafeInteger(cost) || cost < 0) throw new Error("Invalid geo reservation");
+    const rows = rowsFor(subject, config, now);
+    await db.begin(async (tx) => {
+      // Fixed order across upserts, updates, shares and settlement: Cloud first, person second.
+      for (const row of rows)
+        await tx`INSERT INTO geo.usage(scope,subject,period) VALUES(${row.scope},${row.subject},${row.period}) ON CONFLICT DO NOTHING`;
+      for (const row of rows) {
+        const changed = await tx`UPDATE geo.usage SET used=used+${cost} WHERE scope=${row.scope} AND subject=${row.subject}
+          AND period=${row.period} AND used+${cost}<=${row.limit} RETURNING used`;
+        if (!changed.length) throw new GeoError("GEO_BUDGET_EXHAUSTED", { scope: row.scope, resetsAt: row.resetsAt });
+      }
+      for (const row of rows)
+        await tx`INSERT INTO geo.shares(scope,subject,period,function_group,used)
+        VALUES(${row.scope},${row.subject},${row.period},${group},${cost})
+        ON CONFLICT(scope,subject,period,function_group) DO UPDATE SET used=geo.shares.used+EXCLUDED.used`;
+    });
+    return { cost, group, rows };
+  },
+  async settle(reservation: GeoReservation, referenceCost: number) {
+    const refund = reservation.cost - referenceCost;
+    if (!Number.isSafeInteger(referenceCost) || referenceCost < 0 || !Number.isSafeInteger(refund))
+      throw new Error("Invalid geo settlement");
+    if (!refund) return;
+    // Negative refunds truthfully debit known routing overruns. Admission still uses the original
+    // bounded CAS transaction; future reservations see the overdrawn counters and are refused.
+    // Settle once per reservation, in the same fixed row order as admission.
+    await db.begin(async (tx) => {
+      for (const row of reservation.rows) {
+        await tx`UPDATE geo.usage SET used=used-${refund} WHERE scope=${row.scope} AND subject=${row.subject} AND period=${row.period}`;
+        await tx`UPDATE geo.shares SET used=used-${refund} WHERE scope=${row.scope} AND subject=${row.subject} AND period=${row.period} AND function_group=${reservation.group}`;
+      }
+    });
+  },
+  async availability(subject: AccessSubject, config: GeoBudgetConfig, now: Date) {
+    const balances = [];
+    for (const row of rowsFor(subject, config, now)) {
+      const [used] = await db<{ used: number }[]>`SELECT used::float8 AS used FROM geo.usage
+        WHERE scope=${row.scope} AND subject=${row.subject} AND period=${row.period}`;
+      balances.push({ exhausted: (used?.used ?? 0) >= row.limit, resetsAt: row.resetsAt });
+    }
+    return { cloud: balances[0]!, person: balances[1]! };
+  },
+  async recordTransition(
+    event: "provider_key_rejected" | "monthly_budget_exhausted",
+    timezone: string,
+    context: Pick<CapabilityExecutionContext, "actor"> & Partial<Pick<CapabilityExecutionContext, "requestId">>,
+    now: Date,
+  ) {
+    const period = geoPeriods(now, timezone).cloud.period;
+    await db.begin(async (tx) => {
+      const inserted =
+        await tx`INSERT INTO geo.audit_transitions(event,period) VALUES(${event},${period}) ON CONFLICT DO NOTHING RETURNING event`;
+      if (!inserted.length) return;
+      const actor =
+        context.actor.kind === "user"
+          ? {
+              userId: context.actor.user.id,
+              uid: context.actor.user.uid,
+              provider: context.actor.user.provider,
+              roles: context.actor.user.roles,
+            }
+          : { uid: `service-account:${context.actor.serviceAccount.id}`, provider: "service_account", roles: context.actor.scopes };
+      await audit.record(
+        {
+          action: `core.geo.${event}`,
+          outcome: event === "provider_key_rejected" ? "failed" : "denied",
+          actor,
+          requestId: context.requestId,
+          metadata: { period },
+        },
+        tx,
+      );
+    });
+  },
+});

package/src/services/geo/map.ts

@@ -0,0 +1,160 @@
+import { mapAttribution } from "@k2b/ui";
+import { GEO_MAP_MAX_ZOOM, GEO_MAX_TILE_BYTES, GeoMapStyleInputSchema } from "../../contracts/geo-map";
+import { EMPTY_NETWORK_ALLOWLIST } from "../../shared/network-address";
+import { createAllowedNetworkFetch } from "../allowed-network-fetch";
+import { createGeoBucket, GEO_TIMEOUT_MS } from "./bucket";
+import { GeoError, GeoProviderError } from "./errors";
+import { type GeoFetch, geoNeverSent } from "./geoapify";
+import { createGeoLedger } from "./ledger";
+import { type GeoContext, geoIdentity } from "./service";
+import { type GeoConfig, geoPlan, readGeoConfig } from "./settings";
+
+const guardedFetch = createAllowedNetworkFetch(EMPTY_NETWORK_ALLOWLIST);
+
+export const createGeoMapService = (
+  options: {
+    config?: () => Promise<GeoConfig>;
+    now?: () => Date;
+    fetch?: GeoFetch;
+    bucket?: ReturnType<typeof createGeoBucket>;
+    ledger?: ReturnType<typeof createGeoLedger>;
+  } = {},
+) => {
+  const config = options.config ?? readGeoConfig;
+  const now = options.now ?? (() => new Date());
+  const bucket = options.bucket ?? createGeoBucket();
+  const ledger = options.ledger ?? createGeoLedger();
+  const configured = async (context: GeoContext) => {
+    geoIdentity(context);
+    const settings = await config();
+    if (!settings.apiKey.trim()) throw new GeoError("GEO_NOT_CONFIGURED");
+    return settings;
+  };
+  return {
+    async style(input: { theme?: "light" | "dark" }, context: GeoContext) {
+      await configured(context);
+      const parsed = GeoMapStyleInputSchema.safeParse(input);
+      if (!parsed.success) throw new GeoError("GEO_UNSUPPORTED_OPTION");
+      const locale = new Intl.Locale(context.locale ?? "en").language;
+      return { styleUrl: `/api/geo/style?theme=${parsed.data.theme}&locale=${locale}`, attribution: [...mapAttribution] };
+    },
+    async tile(input: { z: number; x: number; y: number }, context: GeoContext): Promise<Uint8Array<ArrayBuffer>> {
+      const settings = await configured(context);
+      const identity = geoIdentity(context);
+      const { z, x, y } = input;
+      if (![z, x, y].every(Number.isInteger) || z < 0 || z > GEO_MAP_MAX_ZOOM || x < 0 || y < 0 || x >= 2 ** z || y >= 2 ** z)
+        throw new GeoError("GEO_UNSUPPORTED_OPTION");
+      const deadline = AbortSignal.timeout(GEO_TIMEOUT_MS.tiles);
+      const signal = context.signal ? AbortSignal.any([context.signal, deadline]) : deadline;
+      const release = await bucket.acquire("tiles", geoPlan(settings).rps * 4);
+      let reservation: Awaited<ReturnType<typeof ledger.reserve>> | undefined;
+      let charge: "none" | "known" | "unknown" = "none";
+      try {
+        signal.throwIfAborted();
+        reservation = await ledger.reserve(identity.accessSubject, settings, 250, "tiles", now());
+        const url = new URL(`/v1/tile/osm-bright/${z}/${x}/${y}.pbf`, "https://api-eu.geoapify.com");
+        let response: Response | undefined;
+        for (let attempt = 0; attempt < 2; attempt++) {
+          signal.throwIfAborted();
+          charge = "unknown";
+          try {
+            response = await (options.fetch ?? guardedFetch)(url, {
+              headers: { "x-api-key": settings.apiKey, accept: "application/x-protobuf" },
+              credentials: "omit",
+              redirect: "error",
+              signal,
+            });
+            break;
+          } catch (cause) {
+            if (!signal.aborted && geoNeverSent(cause)) {
+              charge = "none";
+              if (attempt === 0) continue;
+            }
+            throw new GeoProviderError("GEO_PROVIDER_FAILED", charge);
+          }
+        }
+        if (!response) throw new GeoProviderError("GEO_PROVIDER_FAILED", charge);
+        charge = "known";
+        if (!response.ok) {
+          void response.body?.cancel().catch(() => {});
+          throw new GeoProviderError(
+            response.status === 429 ? "GEO_BUSY" : "GEO_PROVIDER_FAILED",
+            charge,
+            [401, 403].includes(response.status),
+          );
+        }
+        const type = response.headers.get("content-type")?.split(";")[0]?.trim();
+        if (
+          !type ||
+          !["application/x-protobuf", "application/vnd.mapbox-vector-tile", "application/octet-stream"].includes(type) ||
+          Number(response.headers.get("content-length")) > GEO_MAX_TILE_BYTES
+        ) {
+          void response.body?.cancel().catch(() => {});
+          throw new GeoProviderError("GEO_PROVIDER_FAILED", charge);
+        }
+        const reader = response.body?.getReader();
+        if (!reader) throw new GeoProviderError("GEO_PROVIDER_FAILED", charge);
+        const abort = () => {
+          void reader.cancel().catch(() => {});
+        };
+        signal.addEventListener("abort", abort, { once: true });
+        const buffer = new Uint8Array(GEO_MAX_TILE_BYTES);
+        let size = 0;
+        try {
+          if (signal.aborted) abort();
+          while (true) {
+            const next = await reader.read();
+            if (next.done) break;
+            if (size + next.value.byteLength > GEO_MAX_TILE_BYTES) {
+              abort();
+              throw new GeoProviderError("GEO_PROVIDER_FAILED", charge);
+            }
+            buffer.set(next.value, size);
+            size += next.value.byteLength;
+          }
+          signal.throwIfAborted();
+        } finally {
+          signal.removeEventListener("abort", abort);
+          reader.releaseLock();
+        }
+        const bytes = buffer.subarray(0, size);
+        // Never forward an echoed credential, including one spanning streamed chunks.
+        if (Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).includes(Buffer.from(settings.apiKey)))
+          throw new GeoProviderError("GEO_PROVIDER_FAILED", charge);
+        return bytes;
+      } catch (cause) {
+        if (reservation && charge === "none") {
+          try {
+            await ledger.settle(reservation, 0);
+          } catch {
+            charge = "unknown";
+          }
+        }
+        if (reservation && charge !== "none" && (!(cause instanceof GeoError) || signal.aborted)) charge = "unknown";
+        const error = cause instanceof GeoError ? cause : new GeoError("GEO_PROVIDER_FAILED");
+        const transition =
+          cause instanceof GeoProviderError && cause.keyRejected
+            ? "provider_key_rejected"
+            : error.code === "GEO_BUDGET_EXHAUSTED" && error.details.scope === "cloud"
+              ? "monthly_budget_exhausted"
+              : null;
+        if (transition)
+          await ledger.recordTransition(transition, settings.timezone, { ...context, ...identity }, now()).catch(() => {
+            console.error("[geo] Map audit transition could not be recorded", { event: transition });
+          });
+        if (error.code === "GEO_PROVIDER_FAILED" || error.code === "GEO_BUSY")
+          throw new GeoError(error.code, {
+            ...error.details,
+            costs: {
+              settledCredits: reservation && charge === "known" ? 0.25 : 0,
+              unknownCredits: reservation && charge === "unknown" ? 0.25 : 0,
+            },
+          });
+        throw error;
+      } finally {
+        await release();
+      }
+    },
+  };
+};
+export const coreGeoMap = createGeoMapService();

package/src/services/geo/migrate.ts

@@ -0,0 +1,25 @@
+import { type SQL, sql } from "bun";
+export const migrate = async (db: SQL = sql): Promise<void> => {
+  await db.begin(async (tx) => {
+    await tx`SELECT pg_advisory_xact_lock(hashtextextended('core.geo.migrations', 0))`;
+    await tx`CREATE SCHEMA IF NOT EXISTS geo`.simple();
+    await tx`CREATE TABLE IF NOT EXISTS geo.usage (
+      scope text NOT NULL CHECK (scope IN ('cloud', 'person')),
+      subject text NOT NULL,
+      period text NOT NULL,
+      used bigint NOT NULL DEFAULT 0 CHECK (used >= 0),
+      PRIMARY KEY (scope, subject, period)
+    )`.simple();
+    // The administration reads one local day across all people.
+    await tx`CREATE INDEX IF NOT EXISTS geo_usage_scope_period ON geo.usage (scope, period)`.simple();
+    await tx`CREATE TABLE IF NOT EXISTS geo.shares (
+      scope text NOT NULL, subject text NOT NULL, period text NOT NULL,
+      function_group text NOT NULL, used bigint NOT NULL DEFAULT 0 CHECK (used >= 0),
+      PRIMARY KEY (scope, subject, period, function_group),
+      FOREIGN KEY (scope, subject, period) REFERENCES geo.usage(scope, subject, period)
+    )`.simple();
+    await tx`CREATE TABLE IF NOT EXISTS geo.audit_transitions (
+      event text NOT NULL, period text NOT NULL, PRIMARY KEY (event, period)
+    )`.simple();
+  });
+};