@k2b/cloud 0.40.0 → 0.42.0

package/src/services/geo/polyline.ts

@@ -0,0 +1,184 @@
+import { GEO_MAX_POLYLINE_CHARS, type GeoPoint } from "../../contracts/geo";
+import { GeoError, limitExceeded } from "./errors";
+
+const R = 6_371_008.8;
+const rad = Math.PI / 180;
+const longitudeDelta = (delta: number) => ((delta + 540) % 360) - 180;
+export const geoDistance = (a: GeoPoint, b: GeoPoint) => {
+  const sinA = Math.sin(a.lat * rad),
+    cosA = Math.cos(a.lat * rad);
+  const sinB = Math.sin(b.lat * rad),
+    cosB = Math.cos(b.lat * rad);
+  const delta = longitudeDelta(b.lon - a.lon) * rad,
+    cosDelta = Math.cos(delta);
+  // atan2 retains the angular distance when haversine would round nearly opposite points to exactly π.
+  return R * Math.atan2(Math.hypot(cosB * Math.sin(delta), cosA * sinB - sinA * cosB * cosDelta), sinA * sinB + cosA * cosB * cosDelta);
+};
+export const decodePolyline6 = (encoded: string): GeoPoint[] => {
+  if (encoded.length > GEO_MAX_POLYLINE_CHARS) limitExceeded("along.polyline6", GEO_MAX_POLYLINE_CHARS, encoded.length);
+  let index = 0,
+    lat = 0,
+    lon = 0;
+  const points: GeoPoint[] = [];
+  const value = () => {
+    let result = 0,
+      factor = 1;
+    for (let count = 0; count < 6 && index < encoded.length; count++) {
+      const part = encoded.charCodeAt(index++) - 63;
+      if (part < 0 || part > 63) throw new GeoError("GEO_UNSUPPORTED_OPTION");
+      result += (part & 31) * factor;
+      if (part < 32) return result % 2 ? -(result + 1) / 2 : result / 2;
+      factor *= 32;
+    }
+    throw new GeoError("GEO_UNSUPPORTED_OPTION");
+  };
+  while (index < encoded.length) {
+    lat += value();
+    lon += value();
+    const point = { lat: lat / 1e6, lon: lon / 1e6 };
+    if (Math.abs(point.lat) > 90 || Math.abs(point.lon) > 180) throw new GeoError("GEO_UNSUPPORTED_OPTION");
+    points.push(point);
+  }
+  if (points.length < 2) throw new GeoError("GEO_UNSUPPORTED_OPTION");
+  return points;
+};
+const interpolate = (a: GeoPoint, b: GeoPoint, t: number): GeoPoint => {
+  const vector = (p: GeoPoint) => ({
+    x: Math.cos(p.lat * rad) * Math.cos(p.lon * rad),
+    y: Math.cos(p.lat * rad) * Math.sin(p.lon * rad),
+    z: Math.sin(p.lat * rad),
+  });
+  const from = vector(a),
+    to = vector(b);
+  const nx = from.y * to.z - from.z * to.y,
+    ny = from.z * to.x - from.x * to.z,
+    nz = from.x * to.y - from.y * to.x;
+  const normal = Math.hypot(nx, ny, nz),
+    dot = from.x * to.x + from.y * to.y + from.z * to.z;
+  // Exactly opposite endpoints do not define a unique arc; the route must include an intermediate point.
+  if (dot < 0 && normal <= 8 * Number.EPSILON) throw new GeoError("GEO_UNSUPPORTED_OPTION");
+  if (t === 0 || !normal) return a;
+  if (t === 1) return b;
+  const angle = Math.atan2(normal, dot) * t,
+    cos = Math.cos(angle),
+    sin = Math.sin(angle);
+  // Rotate from the first endpoint in its tangent direction, without subtracting opposing endpoint weights.
+  const x = from.x * cos + ((ny * from.z - nz * from.y) / normal) * sin,
+    y = from.y * cos + ((nz * from.x - nx * from.z) / normal) * sin,
+    z = from.z * cos + ((nx * from.y - ny * from.x) / normal) * sin;
+  return { lat: Math.atan2(z, Math.hypot(x, y)) / rad, lon: Math.atan2(y, x) / rad };
+};
+export const cutGeoWindow = (points: readonly GeoPoint[], fromMeters: number, toMeters: number): GeoPoint[] => {
+  const output: GeoPoint[] = [];
+  let at = 0;
+  for (let i = 1; i < points.length; i++) {
+    const a = points[i - 1]!,
+      b = points[i]!,
+      length = geoDistance(a, b),
+      end = at + length;
+    if (length && end > fromMeters && at < toMeters) {
+      if (!output.length) output.push(interpolate(a, b, Math.max(0, (fromMeters - at) / length)));
+      output.push(interpolate(a, b, Math.min(1, (toMeters - at) / length)));
+    }
+    at = end;
+    if (at >= toMeters) break;
+  }
+  if (output.length < 2) throw new GeoError("GEO_UNSUPPORTED_OPTION");
+  return output;
+};
+const segmentProjection = (a: GeoPoint, b: GeoPoint) => {
+  const length = geoDistance(a, b) / R;
+  const sinA = Math.sin(a.lat * rad),
+    cosA = Math.cos(a.lat * rad);
+  const deltaB = longitudeDelta(b.lon - a.lon) * rad;
+  const bearing = Math.atan2(
+    Math.sin(deltaB) * Math.cos(b.lat * rad),
+    cosA * Math.sin(b.lat * rad) - sinA * Math.cos(b.lat * rad) * Math.cos(deltaB),
+  );
+  const sinBearing = Math.sin(bearing),
+    cosBearing = Math.cos(bearing);
+  return (point: GeoPoint) => {
+    if (!length) return { t: 0, distance: geoDistance(point, a) };
+    const delta = longitudeDelta(point.lon - a.lon) * rad;
+    const sinPoint = Math.sin(point.lat * rad),
+      cosPoint = Math.cos(point.lat * rad),
+      cosDelta = Math.cos(delta);
+    const east = cosPoint * Math.sin(delta),
+      north = cosA * sinPoint - sinA * cosPoint * cosDelta;
+    // Great-circle along-track and cross-track angles, using one prepared bearing per segment.
+    const along = Math.atan2(east * sinBearing + north * cosBearing, sinA * sinPoint + cosA * cosPoint * cosDelta);
+    if (along < 0 || along > length) {
+      const from = geoDistance(point, a),
+        to = geoDistance(point, b);
+      return from <= to ? { t: 0, distance: from } : { t: 1, distance: to };
+    }
+    return { t: along / length, distance: R * Math.asin(Math.min(1, Math.abs(east * cosBearing - north * sinBearing))) };
+  };
+};
+export const locateOnGeoLine = (point: GeoPoint, line: readonly GeoPoint[]) => {
+  let at = 0,
+    atMeters = 0,
+    distanceToRouteMeters = Infinity;
+  for (let i = 1; i < line.length; i++) {
+    const a = line[i - 1]!,
+      b = line[i]!,
+      length = geoDistance(a, b),
+      match = segmentProjection(a, b)(point);
+    if (match.distance < distanceToRouteMeters) {
+      distanceToRouteMeters = match.distance;
+      atMeters = at + match.t * length;
+    }
+    at += length;
+  }
+  return { atMeters, distanceToRouteMeters };
+};
+/** Linear minimum-spacing pass before the more expensive Douglas–Peucker stage. */
+const reduceRadialDistance = (points: readonly GeoPoint[], tolerance: number): GeoPoint[] => {
+  const line = [points[0]!];
+  for (let i = 1; i < points.length - 1; i++) {
+    if (geoDistance(line.at(-1)!, points[i]!) > tolerance) line.push(points[i]!);
+  }
+  line.push(points.at(-1)!);
+  return line;
+};
+/** Iterative Douglas–Peucker: no recursion depth depends on untrusted line length. */
+const simplify = (points: readonly GeoPoint[], tolerance: number, pointLimit: number): GeoPoint[] => {
+  const keep = new Set([0, points.length - 1]);
+  const stack: Array<[number, number]> = [[0, points.length - 1]];
+  while (stack.length) {
+    const [start, end] = stack.pop()!;
+    let furthest = -1,
+      distance = tolerance;
+    const project = segmentProjection(points[start]!, points[end]!);
+    for (let i = start + 1; i < end; i++) {
+      const next = project(points[i]!).distance;
+      if (next > distance) {
+        distance = next;
+        furthest = i;
+      }
+    }
+    if (furthest >= 0) {
+      keep.add(furthest);
+      // This tolerance already cannot fit: stop work and try the next tolerance.
+      if (keep.size > pointLimit) return [...points];
+      stack.push([start, furthest], [furthest, end]);
+    }
+  }
+  return [...keep].sort((a, b) => a - b).map((index) => points[index]!);
+};
+export const simplifyGeoLine = (points: readonly GeoPoint[], minimumToleranceMeters = 0, pointLimit = 2000) => {
+  let toleranceMeters = minimumToleranceMeters,
+    reduced = [...points];
+  // Bound quadratic Douglas–Peucker work independently of the decoded input size.
+  while (reduced.length > pointLimit * 2) {
+    toleranceMeters = toleranceMeters ? toleranceMeters * 2 : 1;
+    reduced = reduceRadialDistance(points, toleranceMeters);
+  }
+  let line = minimumToleranceMeters ? simplify(reduced, toleranceMeters, pointLimit) : reduced;
+  while (line.length > pointLimit) {
+    toleranceMeters ||= 1;
+    line = simplify(reduced, toleranceMeters, pointLimit);
+    if (line.length > pointLimit) toleranceMeters *= 2;
+  }
+  return { line, toleranceMeters };
+};

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

@@ -0,0 +1,145 @@
+import type { z } from "zod";
+import type { GeoFunction } from "../../contracts/geo";
+import type { createGeoBucket } from "./bucket";
+import { GEO_TIMEOUT_MS } from "./bucket";
+import type { createGeoCache } from "./cache";
+import { geoCacheKey } from "./cache";
+import { geoReferenceCost } from "./costs";
+import { GeoError, GeoProviderError, limitExceeded } from "./errors";
+import type { createGeoLedger } from "./ledger";
+import { geoRouteReferenceCost } from "./route-costs";
+import type { GeoContext } from "./service";
+import { type GeoConfig, geoPlan } from "./settings";
+
+export type GeoRouteChainDependencies = {
+  cache: ReturnType<typeof createGeoCache>;
+  bucket: ReturnType<typeof createGeoBucket>;
+  ledger: ReturnType<typeof createGeoLedger>;
+  now: () => Date;
+  recordTransition: (event: "monthly_budget_exhausted" | "provider_key_rejected", timezone: string, context: GeoContext) => Promise<void>;
+};
+export type GeoRouteCallPricing = { pairs: number; avoids: number; optimize: boolean; distanceAllowanceMeters: number };
+export const reserveRouteCall = (pricing: GeoRouteCallPricing) =>
+  geoRouteReferenceCost({ ...pricing, distanceMeters: pricing.pairs * pricing.distanceAllowanceMeters });
+export type GeoRouteChainCall = <V>(
+  fn: GeoFunction,
+  input: unknown,
+  schema: z.ZodType<V>,
+  request: (signal: AbortSignal) => Promise<V>,
+  pricing?: GeoRouteCallPricing,
+  distance?: (value: V) => number,
+) => Promise<V>;
+export const runGeoRouteChain = async <T>(
+  dependencies: GeoRouteChainDependencies,
+  context: GeoContext,
+  config: GeoConfig,
+  reserveCost: number,
+  work: (call: GeoRouteChainCall) => Promise<T>,
+): Promise<T> => {
+  const { ledger, bucket, cache, now } = dependencies;
+  if (!context.accessSubject) throw new GeoError("GEO_FORBIDDEN");
+  context.signal?.throwIfAborted();
+  const maximumCredits = Math.min(config.personDailyCredits, config.monthlyCredits);
+  if (reserveCost > maximumCredits * 1000) limitExceeded("reservationCredits", maximumCredits, reserveCost / 1000);
+  let reservation: Awaited<ReturnType<typeof ledger.reserve>>;
+  try {
+    // One atomic admission for all known geocodes and every possible paid routing step.
+    reservation = await ledger.reserve(context.accessSubject, config, reserveCost, "route", now());
+  } catch (error) {
+    if (error instanceof GeoError && error.code === "GEO_BUDGET_EXHAUSTED" && error.details.scope === "cloud")
+      await dependencies.recordTransition("monthly_budget_exhausted", config.timezone, context);
+    throw error;
+  }
+  let known = 0,
+    unknown = 0;
+  let result: T | undefined, failure: unknown;
+  try {
+    result = await work(async (fn, input, schema, request, pricing, distance) => {
+      context.signal?.throwIfAborted();
+      const key = geoCacheKey(fn, input, context.locale ?? "en");
+      const hit = await cache.get(key, schema);
+      if (hit !== null) {
+        // A cached response still must respect this call's reference allowance.
+        if (pricing && distance && distance(hit) > pricing.pairs * pricing.distanceAllowanceMeters)
+          throw new GeoError("GEO_COST_OVERRUN", {
+            distanceAllowanceMeters: pricing.distanceAllowanceMeters,
+            actualDistanceMeters: distance(hit),
+          });
+        return hit;
+      }
+      const allocated = pricing ? reserveRouteCall(pricing) : geoReferenceCost({ fn });
+      const debitKnown = (meters: number) => {
+        try {
+          const cost = pricing ? geoRouteReferenceCost({ ...pricing, distanceMeters: meters }) : allocated;
+          if (!Number.isSafeInteger(known + unknown + cost)) throw new Error("Unrepresentable reference cost");
+          known += cost;
+        } catch {
+          // A sent request never becomes free because the provider's distance cannot be priced safely.
+          unknown += allocated;
+          throw new GeoProviderError("GEO_PROVIDER_FAILED", "unknown");
+        }
+      };
+      const release = await bucket.acquire(fn, geoPlan(config).rps);
+      const deadline = AbortSignal.timeout(GEO_TIMEOUT_MS[fn]);
+      const signal = context.signal ? AbortSignal.any([context.signal, deadline]) : deadline;
+      try {
+        signal.throwIfAborted();
+        let response: unknown;
+        try {
+          response = await request(signal);
+        } catch (error) {
+          if (error instanceof GeoProviderError && error.charge === "none") {
+            /* provably not sent */
+          } else if (error instanceof GeoProviderError && error.charge === "unknown") unknown += allocated;
+          else if (error instanceof GeoError && !(error instanceof GeoProviderError)) debitKnown(0);
+          else if (error instanceof GeoProviderError) debitKnown(error.referenceDistanceMeters ?? 0);
+          else unknown += allocated;
+          if (error instanceof GeoProviderError && error.keyRejected)
+            await dependencies.recordTransition("provider_key_rejected", config.timezone, context);
+          throw error;
+        }
+        const parsed = schema.safeParse(response);
+        if (!parsed.success) {
+          unknown += allocated;
+          throw new GeoProviderError("GEO_PROVIDER_FAILED", "unknown");
+        }
+        const actualDistance = pricing && distance ? distance(parsed.data) : 0;
+        debitKnown(actualDistance);
+        if (signal.aborted) throw new GeoError("GEO_PROVIDER_FAILED");
+        // Retain valid paid results even on overrun, so an explicitly larger allowance can reuse them.
+        await cache.put(key, fn, parsed.data, false);
+        if (pricing && actualDistance > pricing.pairs * pricing.distanceAllowanceMeters)
+          throw new GeoError("GEO_COST_OVERRUN", {
+            distanceAllowanceMeters: pricing.distanceAllowanceMeters,
+            actualDistanceMeters: actualDistance,
+          });
+        return parsed.data;
+      } finally {
+        await release();
+      }
+    });
+  } catch (error) {
+    failure = error;
+  }
+  try {
+    await ledger.settle(reservation, known + unknown);
+  } catch {
+    // Keep the original admission debit, and make failed reconciliation visible without retaining a provider cause.
+    failure = new GeoError("GEO_PROVIDER_FAILED", {
+      adminHint:
+        "Geo accounting settlement failed; the final ledger debit is unconfirmed. Review the original reservation and reconcile accounting reference costs in Core geo usage before retrying.",
+      accounting: {
+        reservationCredits: reservation.cost / 1000,
+        knownReferenceCredits: known / 1000,
+        unknownReferenceCredits: unknown / 1000,
+      },
+    });
+    known = 0;
+    unknown = reservation.cost;
+  }
+  if (failure) {
+    const error = failure instanceof GeoError ? failure : new GeoError("GEO_PROVIDER_FAILED");
+    throw new GeoError(error.code, { ...error.details, costs: { settledCredits: known / 1000, unknownCredits: unknown / 1000 } });
+  }
+  return result!;
+};

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

@@ -0,0 +1,9 @@
+/** Conservative Cloud reference pricing, in integer millicredits; not a provider invoice quote. */
+export type GeoRouteCost = { pairs: number; avoids: number; optimize: boolean; distanceMeters: number };
+export const geoRouteReferenceCost = ({ pairs, avoids, optimize, distanceMeters }: GeoRouteCost) => {
+  const intermediate = pairs - 1;
+  const matrix = optimize && intermediate >= 2 ? intermediate * Math.min(intermediate, 10) : 0;
+  const cost = (pairs + avoids + matrix) * Math.max(1, Math.ceil(distanceMeters / 500_000)) * 1000;
+  if (!Number.isSafeInteger(cost) || cost < 0) throw new Error("Invalid geo routing reference cost");
+  return cost;
+};

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

@@ -0,0 +1,39 @@
+import type { GeoPoint } from "../../contracts/geo";
+import { decodePolyline6, simplifyGeoLine } from "./polyline";
+
+export const encodePolyline6 = (points: readonly GeoPoint[]) => {
+  let lat = 0,
+    lon = 0,
+    output = "";
+  const encode = (value: number) => {
+    let n = value < 0 ? -value * 2 - 1 : value * 2;
+    while (n >= 32) {
+      output += String.fromCharCode((n % 32) + 95);
+      n = Math.floor(n / 32);
+    }
+    output += String.fromCharCode(n + 63);
+  };
+  for (const point of points) {
+    const nextLat = Math.round(point.lat * 1e6),
+      nextLon = Math.round(point.lon * 1e6);
+    encode(nextLat - lat);
+    encode(nextLon - lon);
+    lat = nextLat;
+    lon = nextLon;
+  }
+  return output;
+};
+export const compactRouteLine = (line: readonly GeoPoint[], tolerance = 0, pointLimit = 2000) => {
+  const simplified = simplifyGeoLine([...line], tolerance, pointLimit);
+  return { polyline6: encodePolyline6(simplified.line), simplificationToleranceMeters: 2 * simplified.toleranceMeters };
+};
+export const joinRouteLines = (lines: readonly string[]) => {
+  const points: GeoPoint[] = [];
+  for (const line of lines) {
+    const next = decodePolyline6(line);
+    const last = points.at(-1),
+      first = next[0]!;
+    points.push(...(last && last.lat === first.lat && last.lon === first.lon ? next.slice(1) : next));
+  }
+  return encodePolyline6(points);
+};

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

@@ -0,0 +1,172 @@
+import { createHash } from "node:crypto";
+import type { GeoPoint } from "../../contracts/geo";
+import {
+  type GeoRoute,
+  type GeoRouteLeg,
+  type GeoRouteOptions,
+  type GeoRoutePlan,
+  type GeoRouteResolvedStop,
+  GeoRouteSchema,
+  type GeoRouteStop,
+} from "../../contracts/geo-route";
+import { GEO_MAX_JSON_BYTES, normalizeGeoInput } from "./cache";
+import { GeoError, limitExceeded } from "./errors";
+import { geoProvenance } from "./geoapify";
+import { decodePolyline6, geoDistance } from "./polyline";
+import { compactRouteLine, joinRouteLines } from "./route-geometry";
+
+export const routeOptions = (value: GeoRouteOptions = {}, base: GeoRouteOptions = {}): GeoRouteOptions => {
+  const mode = value.mode ?? base.mode ?? "car";
+  const avoid = [...new Set(value.avoid ?? base.avoid ?? [])].sort();
+  if (mode !== "car" && avoid.some((option) => option !== "ferries")) throw new GeoError("GEO_UNSUPPORTED_OPTION");
+  return { mode, avoid };
+};
+export const sameRouteOptions = (a: GeoRouteOptions, b: GeoRouteOptions) =>
+  JSON.stringify(routeOptions(a)) === JSON.stringify(routeOptions(b));
+export const validateRouteStops = (stops: readonly GeoRouteStop[]) => {
+  if (stops.length < 2 || stops.length > 26) limitExceeded("stops", stops.length < 2 ? 2 : 26, stops.length);
+  if (new Set(stops.map((stop) => stop.id)).size !== stops.length) throw new GeoError("GEO_UNSUPPORTED_OPTION");
+  for (const stop of stops) {
+    if (!!stop.point === !!stop.address) throw new GeoError("GEO_UNSUPPORTED_OPTION");
+    if (!stop.address) continue;
+    const address = stop.address;
+    if (address.text !== undefined && (!address.text.trim() || address.text.length > 300))
+      limitExceeded("address.text", 300, address.text.length);
+    for (const [key, field] of Object.entries(address.fields ?? {}))
+      if (field !== undefined && field.length > 200) limitExceeded(`address.fields.${key}`, 200, field.length);
+    if (
+      !!address.text?.trim() === !!Object.values(address.fields ?? {}).some((field) => field?.trim()) ||
+      (address.countryCode !== undefined && !/^[a-z]{2}$/i.test(address.countryCode))
+    )
+      throw new GeoError("GEO_UNSUPPORTED_OPTION");
+  }
+};
+export const validateRoutePlan = (plan: GeoRoutePlan) => {
+  validateRouteStops(plan.stops);
+  const defaults = routeOptions(plan.options);
+  const byDeparture = new Map<string, GeoRouteOptions>();
+  for (const entry of plan.legOptions ?? []) {
+    const index = plan.stops.findIndex((stop) => stop.id === entry.fromStopId);
+    if (index < 0 || plan.stops[index + 1]?.id !== entry.toStopId || byDeparture.has(entry.fromStopId))
+      throw new GeoError("GEO_UNSUPPORTED_OPTION");
+    byDeparture.set(entry.fromStopId, routeOptions(entry.options, defaults));
+  }
+  return { defaults, byDeparture };
+};
+export const walkDistance = (stops: readonly GeoRouteResolvedStop[], options: GeoRouteOptions) => {
+  if (options.mode !== "walk") return;
+  for (let i = 1; i < stops.length; i++) {
+    const distance = geoDistance(stops[i - 1]!.point, stops[i]!.point);
+    if (distance > 100_000) limitExceeded("walk.legMeters", 100_000, distance);
+  }
+};
+const routeHash = (stops: readonly GeoRouteResolvedStop[], options: GeoRouteOptions, legs: readonly GeoRouteLeg[]) =>
+  createHash("sha256")
+    .update(
+      JSON.stringify(
+        normalizeGeoInput(
+          {
+            stops,
+            options,
+            legOptions: legs.map((leg) => ({
+              fromStopId: leg.fromStopId,
+              toStopId: leg.toStopId,
+              options: leg.options,
+            })),
+          },
+          "route",
+        ),
+      ),
+    )
+    .digest("hex");
+export const assembleRoute = (
+  stops: GeoRouteResolvedStop[],
+  defaults: GeoRouteOptions,
+  originalLegs: GeoRouteLeg[],
+  now: Date,
+  distanceAllowanceMeters: number,
+): GeoRoute => {
+  let legs = originalLegs;
+  const build = (): GeoRoute => ({
+    stops,
+    options: defaults,
+    legs,
+    distanceAllowanceMeters,
+    distanceMeters: legs.reduce((sum, leg) => sum + leg.distanceMeters, 0),
+    durationSeconds: legs.reduce((sum, leg) => sum + leg.durationSeconds, 0),
+    polyline6: joinRouteLines(legs.map((leg) => leg.polyline6)),
+    simplificationToleranceMeters: Math.max(...legs.map((leg) => leg.simplificationToleranceMeters)),
+    inputHash: routeHash(stops, defaults, legs),
+    provenance: geoProvenance(now),
+  });
+  let route = build();
+  // Leave space for the capability envelope and update's before/after/delta metadata.
+  // Always simplify from the original geometry, so repeated iterations do not compound the stated tolerance.
+  const lines = originalLegs.map((leg) => decodePolyline6(leg.polyline6));
+  // Each polyline point uses at most 12 ASCII bytes, and appears in its leg and the whole route.
+  // Reserve the actual metadata size before dividing the available geometry budget across legs.
+  const metadataBytes = Buffer.byteLength(
+    JSON.stringify({ data: { route: { ...route, polyline6: "", legs: legs.map((leg) => ({ ...leg, polyline6: "" })) } } }),
+  );
+  const pointLimit = Math.max(
+    2,
+    Math.min(2000, Math.floor((GEO_MAX_JSON_BYTES - 8192 - metadataBytes) / (24 * legs.length)), Math.floor(102400 / (12 * legs.length))),
+  );
+  let tolerance = 1;
+  while (Buffer.byteLength(JSON.stringify({ data: { route } })) > GEO_MAX_JSON_BYTES - 8192 || route.polyline6.length > 102400) {
+    legs = originalLegs.map((leg, i) => {
+      const compacted = compactRouteLine(lines[i]!, tolerance, pointLimit);
+      return {
+        ...leg,
+        ...compacted,
+        simplificationToleranceMeters: leg.simplificationToleranceMeters + compacted.simplificationToleranceMeters,
+      };
+    });
+    route = build();
+    tolerance *= 2;
+    if (tolerance > 40_100_000) throw new GeoError("GEO_PROVIDER_FAILED");
+  }
+  return GeoRouteSchema.parse(route);
+};
+export const validateSavedRoute = (route: GeoRoute) => {
+  if (Buffer.byteLength(JSON.stringify(route)) > GEO_MAX_JSON_BYTES)
+    limitExceeded("route.bytes", GEO_MAX_JSON_BYTES, Buffer.byteLength(JSON.stringify(route)));
+  if (new Set(route.stops.map((stop) => stop.id)).size !== route.stops.length || route.legs.length !== route.stops.length - 1)
+    throw new GeoError("GEO_UNSUPPORTED_OPTION");
+  const validProvenance = (value: GeoRoute["provenance"]) =>
+    value.attribution.links[0] === "https://geoapify.com" && value.attribution.links[1] === "https://www.openstreetmap.org/copyright";
+  if (!validProvenance(route.provenance) || route.stops.some((stop) => stop.address && !validProvenance(stop.address.provenance)))
+    throw new GeoError("GEO_UNSUPPORTED_OPTION");
+  routeOptions(route.options);
+  for (const [i, leg] of route.legs.entries()) {
+    if (leg.fromStopId !== route.stops[i]!.id || leg.toStopId !== route.stops[i + 1]!.id) throw new GeoError("GEO_UNSUPPORTED_OPTION");
+    if (!validProvenance(leg.provenance)) throw new GeoError("GEO_UNSUPPORTED_OPTION");
+    routeOptions(leg.options);
+    decodePolyline6(leg.polyline6);
+  }
+  decodePolyline6(route.polyline6);
+  if (
+    Math.abs(route.distanceMeters - route.legs.reduce((sum, leg) => sum + leg.distanceMeters, 0)) > 1e-6 ||
+    Math.abs(route.durationSeconds - route.legs.reduce((sum, leg) => sum + leg.durationSeconds, 0)) > 1e-6 ||
+    route.polyline6 !== joinRouteLines(route.legs.map((leg) => leg.polyline6)) ||
+    route.inputHash !== routeHash(route.stops, route.options, route.legs)
+  )
+    throw new GeoError("GEO_UNSUPPORTED_OPTION");
+};
+export const routeSummary = (route: GeoRoute) => ({
+  stopIds: route.stops.map((stop) => stop.id),
+  distanceMeters: route.distanceMeters,
+  durationSeconds: route.durationSeconds,
+});
+export const insertionGaps = (route: GeoRoute, point: GeoPoint) =>
+  route.legs
+    .map((_, index) => ({
+      index,
+      detour:
+        geoDistance(route.stops[index]!.point, point) +
+        geoDistance(point, route.stops[index + 1]!.point) -
+        geoDistance(route.stops[index]!.point, route.stops[index + 1]!.point),
+    }))
+    .sort((a, b) => a.detour - b.detour || a.index - b.index)
+    .slice(0, 3)
+    .map((gap) => gap.index);