@k2b/cloud 0.41.0 → 0.42.0

package/src/contracts/capabilities.ts

@@ -8,6 +8,7 @@ import {
 export * from "./capability-streams";
 
 import { z } from "zod";
+import type { RequestAuthority } from "../server/middleware/auth";
 import { CommandPathSchema } from "./commands";
 import type { AccessSubject, RequestActor, User } from "./shared";
 
@@ -177,6 +178,9 @@ export type CapabilityReach = (typeof CAPABILITY_REACHES)[number];
 export const CAPABILITY_ACTION_OUTCOMES = ["running", "done", "rejected", "not_run", "unknown"] as const;
 export type CapabilityActionOutcome = (typeof CAPABILITY_ACTION_OUTCOMES)[number];
 export const CAPABILITY_MAX_REVIEW_BYTES = 32 * 1024;
+/** Full review text and metadata, separate from the compact card and ordinary capability results. */
+export const CAPABILITY_MAX_REVIEW_CONTENT_BYTES = 16 * 1024 * 1024;
+export const CAPABILITY_MAX_REVIEW_RESPONSE_BYTES = CAPABILITY_MAX_REVIEW_CONTENT_BYTES + CAPABILITY_MAX_REVIEW_BYTES + 11;
 export const CapabilityActionPolicySchema = z.union([
   z.object({ silent: z.enum(CAPABILITY_REACHES), routines: z.literal(false).optional() }).strict(),
   z.object({ ask: z.enum(CAPABILITY_ASK_REASONS) }).strict(),
@@ -188,12 +192,12 @@ const reviewLine = (max: number, min = 1) =>
     .string()
     .min(min)
     .max(max)
-    .refine((text) => !/[\p{Cc}\p{Cf}\u2028\u2029]/u.test(text), "Contains unsafe characters");
+    .refine((text) => !/[\p{Cc}\p{Cf}\p{Cs}\u2028\u2029]/u.test(text), "Contains unsafe characters");
 const reviewBlock = (max: number) =>
   z
     .string()
     .max(max)
-    .refine((text) => !/[\p{Cc}\p{Cf}\u2028\u2029]/u.test(text.replace(/[\n\t]/g, "")), "Contains unsafe characters");
+    .refine((text) => !/[\p{Cc}\p{Cf}\p{Cs}\u2028\u2029]/u.test(text.replace(/[\n\t]/g, "")), "Contains unsafe characters");
 export const CapabilityPersonSchema = z
   .object({ name: reviewLine(200).optional(), address: reviewLine(320).optional(), userId: z.uuid().optional() })
   .strict()
@@ -432,60 +436,143 @@ export const CapabilityPreviewSchema = z.discriminatedUnion("kind", [
     .strict(),
 ]);
 export type CapabilityPreview = z.infer<typeof CapabilityPreviewSchema>;
-export const CapabilityActionCallReviewSchema = z
-  .object({
-    locale: z.string(),
-    sentence: z
-      .object({
-        action: reviewTemplate,
-        running: reviewTemplate,
-        done: reviewTemplate,
-        confirm: reviewTemplate,
-        decline: reviewTemplate,
-        rejected: reviewTemplate.optional(),
-        notRun: reviewTemplate.optional(),
-        short: reviewTemplate.refine((text) => text.length <= 60, "short exceeds 60 characters").optional(),
-      })
-      .strict(),
-    slots: reviewSlots.readonly(),
-    preview: CapabilityPreviewSchema.optional(),
-    consequences: z.array(CapabilityConsequenceSchema).max(6).optional(),
-    ask: z.enum(CAPABILITY_ASK_REASONS).optional(),
-    reach: z.enum(CAPABILITY_REACHES).optional(),
-    effects: z.number().int().min(1).max(1000).optional(),
-    check: z
-      .object({ query: CapabilityLocalIdSchema, input: z.record(z.string(), z.unknown()) })
-      .strict()
-      .optional(),
-    scope: z.string().min(1).max(200).optional(),
-    links: z.array(CapabilitySemanticLinkSchema).max(10).optional(),
-  })
-  .strict()
-  .superRefine((review, ctx) => {
-    for (const [form, text] of Object.entries(review.sentence)) {
-      if (text === undefined) continue;
-      const complete = form === "action" || form === "running" || form === "done";
-      for (const message of capabilitySentenceIssues(text, review.slots, complete, form === "action"))
-        ctx.addIssue({ code: "custom", path: ["sentence", form], message });
-      if ((form === "confirm" || form === "decline") && [...text.matchAll(/\{[a-z][A-Za-z0-9]{0,31}\}/g)].length > 1)
-        ctx.addIssue({ code: "custom", path: ["sentence", form], message: "Buttons name at most one slot" });
-    }
-  });
+/** Complete passive content; no attachment bytes, HTML, omitted entries, or silently shortened strings. */
+// Construct complete review validators in pure calls: unrelated browser consumers of resource refs do not need them.
+export const CapabilityReviewContentSchema = /* @__PURE__ */ (() => {
+  const fullReviewPerson = z
+    .object({
+      name: z.string().max(200).optional(),
+      address: z.string().max(320).optional(),
+      userId: z.uuid().optional(),
+    })
+    .strict()
+    .refine((person) => person.name !== undefined || person.address !== undefined, "A person needs a name or address");
+  return z
+    .discriminatedUnion("kind", [
+      z
+        .object({
+          kind: z.literal("message"),
+          baseRevision: z.number().int().nonnegative().optional(),
+          from: fullReviewPerson.optional(),
+          to: z.array(fullReviewPerson).max(600),
+          cc: z.array(fullReviewPerson).max(600).optional(),
+          bcc: z.array(fullReviewPerson).max(600).optional(),
+          subject: z.string().max(998),
+          body: z.string().max(CAPABILITY_MAX_REVIEW_CONTENT_BYTES),
+          format: z.literal("plain"),
+          attachments: z
+            .array(
+              z
+                .object({
+                  name: z.string().min(1).max(255),
+                  size: z.number().int().nonnegative().optional(),
+                  ref: CloudResourceRefSchema.optional(),
+                })
+                .strict(),
+            )
+            .max(202)
+            .optional(),
+          sendAt: reviewTime.optional(),
+          warnings: z.array(z.string().max(300)).max(6).optional(),
+        })
+        .strict(),
+      z
+        .object({
+          kind: z.literal("page"),
+          baseRevision: z.number().int().nonnegative().optional(),
+          title: z.string().max(200),
+          place: z.string().max(200).optional(),
+          body: z.string().max(CAPABILITY_MAX_REVIEW_CONTENT_BYTES),
+          format: z.literal("plain"),
+        })
+        .strict(),
+    ])
+    .superRefine((content, ctx) => {
+      if (content.kind === "message" && content.to.length + (content.cc?.length ?? 0) + (content.bcc?.length ?? 0) > 600)
+        ctx.addIssue({ code: "custom", message: "Full review content exceeds 600 recipients" });
+      if (new TextEncoder().encode(JSON.stringify(content)).byteLength > CAPABILITY_MAX_REVIEW_CONTENT_BYTES)
+        ctx.addIssue({ code: "custom", message: "Full review content exceeds 16 MiB" });
+    });
+})();
+export type CapabilityReviewContent = z.infer<typeof CapabilityReviewContentSchema>;
+/** Cloud supplies this after storing a review. It is a locator, never an authorization token. */
+export const CapabilityReviewContentRefSchema = /* @__PURE__ */ (() =>
+  z
+    .object({
+      href: z
+        .string()
+        .regex(
+          /^\/api\/approvals\/(?:[a-fA-F0-9-]{36}\/content|conversations\/[a-fA-F0-9-]{36}\/turns\/[a-fA-F0-9-]{36}\/reviews\/(?!\.{1,2}$)(?:[A-Za-z0-9_!~*'().-]|%[A-Fa-f0-9]{2})+)$/,
+        )
+        .max(2048),
+      digest: z.string().regex(/^[a-f0-9]{64}$/),
+    })
+    .strict())();
+export type CapabilityReviewContentRef = z.infer<typeof CapabilityReviewContentRefSchema>;
+export const CapabilityActionCallReviewSchema = /* @__PURE__ */ (() =>
+  z
+    .object({
+      locale: z.string(),
+      sentence: z
+        .object({
+          action: reviewTemplate,
+          running: reviewTemplate,
+          done: reviewTemplate,
+          confirm: reviewTemplate,
+          decline: reviewTemplate,
+          rejected: reviewTemplate.optional(),
+          notRun: reviewTemplate.optional(),
+          short: reviewTemplate.refine((text) => text.length <= 60, "short exceeds 60 characters").optional(),
+        })
+        .strict(),
+      slots: reviewSlots.readonly(),
+      preview: CapabilityPreviewSchema.optional(),
+      content: CapabilityReviewContentSchema.optional(),
+      consequences: z.array(CapabilityConsequenceSchema).max(6).optional(),
+      ask: z.enum(CAPABILITY_ASK_REASONS).optional(),
+      reach: z.enum(CAPABILITY_REACHES).optional(),
+      effects: z.number().int().min(1).max(1000).optional(),
+      check: z
+        .object({ query: CapabilityLocalIdSchema, input: z.record(z.string(), z.unknown()) })
+        .strict()
+        .optional(),
+      scope: z.string().min(1).max(200).optional(),
+      links: z.array(CapabilitySemanticLinkSchema).max(10).optional(),
+    })
+    .strict()
+    .superRefine((review, ctx) => {
+      for (const [form, text] of Object.entries(review.sentence)) {
+        if (text === undefined) continue;
+        const complete = form === "action" || form === "running" || form === "done";
+        for (const message of capabilitySentenceIssues(text, review.slots, complete, form === "action"))
+          ctx.addIssue({ code: "custom", path: ["sentence", form], message });
+        if ((form === "confirm" || form === "decline") && [...text.matchAll(/\{[a-z][A-Za-z0-9]{0,31}\}/g)].length > 1)
+          ctx.addIssue({ code: "custom", path: ["sentence", form], message: "Buttons name at most one slot" });
+      }
+    }))();
 export type CapabilityActionCallReview = z.infer<typeof CapabilityActionCallReviewSchema>;
 export type CapabilityActionReviewData = CapabilityActionCallReview | CapabilityActionReview;
-export const CapabilityActionReviewDataSchema = z
-  .unknown()
-  .transform((value, ctx) => {
-    const schema =
-      value !== null && typeof value === "object" && Object.hasOwn(value, "sentence")
-        ? CapabilityActionCallReviewSchema
-        : CapabilityActionReviewSchema;
-    const parsed = schema.safeParse(value);
-    if (parsed.success) return parsed.data;
-    for (const issue of parsed.error.issues) ctx.addIssue({ code: "custom", path: issue.path, message: issue.message });
-    return z.NEVER;
-  })
-  .pipe(z.union([CapabilityActionCallReviewSchema, CapabilityActionReviewSchema]));
+export const CapabilityActionReviewDataSchema = /* @__PURE__ */ (() =>
+  z
+    .unknown()
+    .transform((value, ctx) => {
+      const schema =
+        value !== null && typeof value === "object" && Object.hasOwn(value, "sentence")
+          ? CapabilityActionCallReviewSchema
+          : CapabilityActionReviewSchema;
+      const parsed = schema.safeParse(value);
+      if (parsed.success) return parsed.data;
+      for (const issue of parsed.error.issues) ctx.addIssue({ code: "custom", path: issue.path, message: issue.message });
+      return z.NEVER;
+    })
+    .pipe(z.union([CapabilityActionCallReviewSchema, CapabilityActionReviewSchema])))();
+/** Compact Cloud presentation. Providers return the strict review above, never a client-supplied content locator. */
+export const CapabilityActionReviewPresentationSchema = /* @__PURE__ */ (() =>
+  z.union([
+    CapabilityActionCallReviewSchema.safeExtend({ contentRef: CapabilityReviewContentRefSchema.optional() }),
+    CapabilityActionReviewSchema,
+  ]))();
+export type CapabilityActionReviewPresentation = z.infer<typeof CapabilityActionReviewPresentationSchema>;
 export const CapabilityActionReceiptSchema = z
   .object({ ...sentenceShape, preview: CapabilityPreviewSchema.optional() })
   .strict()
@@ -676,6 +763,12 @@ export const UniversalSearchDataSchema = z.array(CloudResourceViewSchema).max(10
 export type UniversalSearchData = z.infer<typeof UniversalSearchDataSchema>;
 
 export type CapabilityExecutionContext = {
+  /**
+   * Resolved request authority, supplied by the framework for execution, review
+   * and streams. Optional for existing in-process callers; authority-aware
+   * services fail closed when it is absent. Preserve its credential limits.
+   */
+  authority?: RequestAuthority;
   actor: RequestActor;
   accessSubject: AccessSubject;
   user: User | null;
@@ -695,6 +788,7 @@ export type CapabilityExecutionContext = {
   requestId: string;
   /** Cloud surface that invoked this capability. */
   origin: CapabilityOrigin;
+  /** Caller cancellation or shared dispatch deadline; forward it to expensive work. */
   signal: AbortSignal;
 };
 

package/src/contracts/geo-admin.ts

@@ -0,0 +1,127 @@
+import { z } from "zod";
+
+/** Geoapify plans in the order the administration offers them. */
+export const GEO_PLAN_IDS = ["free", "api10", "api25", "api50", "api100", "api250", "custom"] as const;
+export type GeoPlanId = (typeof GEO_PLAN_IDS)[number];
+
+/**
+ * Ledger function groups in display order. Every paid geo call reserves under one of these groups;
+ * the administration shows one share line per group.
+ */
+export const GEO_USAGE_GROUPS = ["tiles", "places", "route", "address"] as const;
+export type GeoUsageGroup = (typeof GEO_USAGE_GROUPS)[number];
+
+/** Largest credit value a geo budget setting accepts (stored as thousandths in a bigint ledger). */
+export const GEO_MAX_CREDITS = Math.floor(Number.MAX_SAFE_INTEGER / 1000);
+/** Largest custom request rate the token bucket accepts. */
+export const GEO_MAX_RPS = Math.floor(Number.MAX_SAFE_INTEGER / 9000);
+/** Upper bound of a pasted provider key; Geoapify keys are 32 characters. */
+export const GEO_MAX_KEY_LENGTH = 256;
+
+export type GeoAdminPerson = { id: string; name: string };
+
+export type GeoAdminKey = {
+  /** `unreadable`: a stored key exists but this installation cannot decrypt it; geo is off until it is replaced or removed. */
+  state: "none" | "set" | "unreadable";
+  setAt: string | null;
+  setBy: GeoAdminPerson | null;
+};
+
+export type GeoAdminBudget = {
+  plan: GeoPlanId;
+  customRps: number;
+  customDailyCredits: number;
+  monthlyCredits: number;
+  personDailyCredits: number;
+  /** Budget settings whose stored value cannot be read; saving the form replaces them. */
+  unreadable: Array<GeoBudgetField | "plan">;
+  changedAt: string | null;
+  changedBy: GeoAdminPerson | null;
+};
+
+export type GeoAdminStatus = {
+  key: GeoAdminKey;
+  budget: GeoAdminBudget;
+  plans: Record<Exclude<GeoPlanId, "custom">, { dailyCredits: number; rps: number }>;
+  /** `app.timezone`: dates on the page and the budget periods use it. */
+  timezone: string;
+};
+
+export type GeoAdminUsage = {
+  /** Credits. Values may carry fractions (a map tile costs 0.25). */
+  month: { period: string; used: number; limit: number; resetsAt: string };
+  /** Cloud-wide use today against the provider's daily allowance of the selected plan. */
+  today: { period: string; used: number; allowance: number; resetsAt: string };
+  shares: Array<{ group: GeoUsageGroup; credits: number }>;
+  /** Access subjects whose use today reached the per-person daily limit. */
+  peopleAtLimit: number;
+  timezone: string;
+};
+
+export const GeoKeyInputSchema = z.object({ apiKey: z.string().max(GEO_MAX_KEY_LENGTH * 4) }).strict();
+
+export const GeoBudgetInputSchema = z
+  .object({
+    plan: z.enum(GEO_PLAN_IDS),
+    customRps: z.unknown(),
+    customDailyCredits: z.unknown(),
+    monthlyCredits: z.unknown(),
+    personDailyCredits: z.unknown(),
+  })
+  .strict();
+export type GeoBudgetInput = z.infer<typeof GeoBudgetInputSchema>;
+export type GeoBudgetField = "customRps" | "customDailyCredits" | "monthlyCredits" | "personDailyCredits";
+
+/** Stable field error codes; the page renders their text. */
+export const GeoBudgetFieldErrorSchema = z.discriminatedUnion("code", [
+  z.object({ code: z.literal("not_whole_number") }),
+  z.object({ code: z.literal("too_small"), min: z.number() }),
+  z.object({ code: z.literal("too_large"), max: z.number() }),
+  z.object({ code: z.literal("above_monthly"), max: z.number() }),
+]);
+export type GeoBudgetFieldError = z.infer<typeof GeoBudgetFieldErrorSchema>;
+/** The 400 answer of a refused budget save. */
+export const GeoBudgetRefusalSchema = z.object({
+  code: z.literal("geo_budget_invalid"),
+  errors: z.partialRecord(z.enum(["customRps", "customDailyCredits", "monthlyCredits", "personDailyCredits"]), GeoBudgetFieldErrorSchema),
+});
+
+export type GeoKeyError =
+  | { code: "geo_key_missing" }
+  | { code: "geo_key_malformed" }
+  | { code: "geo_key_rejected" }
+  | { code: "geo_key_unverified" };
+
+/** Validate one budget number; `null` when it is acceptable. */
+const checkNumber = (value: unknown, min: number, max: number): GeoBudgetFieldError | null => {
+  if (typeof value !== "number" || !Number.isInteger(value)) return { code: "not_whole_number" };
+  if (value < min) return { code: "too_small", min };
+  if (value > max) return { code: "too_large", max };
+  return null;
+};
+
+/** Check the whole form before anything is written; the same rules as the settings registry plus the pair rule. */
+export const validateGeoBudget = (input: GeoBudgetInput) => {
+  const errors: Partial<Record<GeoBudgetField, GeoBudgetFieldError>> = {};
+  const fields: Array<[GeoBudgetField, number, number]> = [
+    ["monthlyCredits", 0, GEO_MAX_CREDITS],
+    ["personDailyCredits", 0, GEO_MAX_CREDITS],
+  ];
+  if (input.plan === "custom") fields.push(["customRps", 1, GEO_MAX_RPS], ["customDailyCredits", 1, GEO_MAX_CREDITS]);
+  for (const [field, min, max] of fields) {
+    const error = checkNumber(input[field], min, max);
+    if (error) errors[field] = error;
+  }
+  const month = input.monthlyCredits,
+    day = input.personDailyCredits;
+  if (!errors.monthlyCredits && !errors.personDailyCredits && typeof month === "number" && typeof day === "number" && day > month)
+    errors.personDailyCredits = { code: "above_monthly", max: month };
+  return errors;
+};
+
+/** Shape check before the provider sees a key: printable ASCII without spaces, as Geoapify issues them. */
+export const geoKeyProblem = (apiKey: string): "geo_key_missing" | "geo_key_malformed" | null => {
+  if (!apiKey) return "geo_key_missing";
+  if (apiKey.length > GEO_MAX_KEY_LENGTH || !/^[\x21-\x7e]+$/.test(apiKey)) return "geo_key_malformed";
+  return null;
+};

package/src/contracts/geo-map.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+
+export const GeoMapStyleInputSchema = z
+  .object({
+    theme: z.enum(["light", "dark"]).default("light").describe("Map appearance; labels use the request locale."),
+  })
+  .strict();
+export const GeoMapStyleDataSchema = z
+  .object({
+    styleUrl: z.string().startsWith("/api/geo/style?"),
+    attribution: z.array(z.object({ label: z.string(), href: z.url() }).strict()),
+  })
+  .strict();
+export const geoMapContract = { style: { id: "map.style", input: GeoMapStyleInputSchema, data: GeoMapStyleDataSchema } } as const;
+
+// This is a transport memory budget, not an asserted provider maximum. At Free's
+// 20 tile requests/s and 10 s deadline, buffered tile bodies occupy at most 200 MiB.
+export const GEO_MAX_TILE_BYTES = 1024 * 1024;
+export const GEO_MAP_MAX_ZOOM = 14;

package/src/contracts/geo-route.ts

@@ -0,0 +1,168 @@
+import { z } from "zod";
+import { GEO_MAX_POLYLINE_CHARS, GeoAddressSchema, GeoGeocodeInputSchema, GeoPointSchema, GeoProvenanceSchema } from "./geo";
+
+export const GEO_ROUTE_MAX_STOPS = 26;
+export const GeoRouteDistanceAllowanceSchema = z
+  .number()
+  .int()
+  .min(1)
+  .max(1_000_000_000)
+  .describe(
+    "Reference distance allowance in meters per leg; defaults to 500000. The whole chain reserves at this allowance. This is not a guaranteed provider bill ceiling. A larger actual route is charged and stops the chain.",
+  );
+const stopId = z.string().min(1).max(100).describe("Stable stop ID, unique within this route.");
+export const GeoRouteOptionsSchema = z
+  .object({
+    mode: z.enum(["car", "bike", "walk"]).optional().describe("Travel mode; defaults to car."),
+    avoid: z
+      .array(z.enum(["tolls", "ferries", "highways"]))
+      .max(3)
+      .optional()
+      .describe("Preferences, not prohibitions; tolls/highways require car. Each preference costs extra."),
+  })
+  .strict();
+export const GeoRouteStopSchema = z
+  .object({
+    id: stopId,
+    label: z.string().max(300).optional().describe("Optional display label."),
+    point: GeoPointSchema.optional().describe("Known coordinates; choose point or address."),
+    address: GeoGeocodeInputSchema.optional().describe("Address to resolve; choose address or point. Ambiguity returns candidates."),
+  })
+  .strict();
+export const GeoRouteResolvedStopSchema = z
+  .object({
+    id: stopId,
+    label: z.string().max(300).optional().describe("Optional display label."),
+    point: GeoPointSchema.describe("Resolved stop coordinates."),
+    address: GeoAddressSchema.optional().describe("Resolved address, when this stop was geocoded."),
+  })
+  .strict();
+export const GeoRouteLegOptionsSchema = z
+  .object({
+    fromStopId: stopId,
+    toStopId: stopId,
+    options: GeoRouteOptionsSchema.describe("Override only the supplied options for this adjacent pair."),
+  })
+  .strict();
+export const GeoRoutePlanSchema = z
+  .object({
+    distanceAllowanceMeters: GeoRouteDistanceAllowanceSchema.optional(),
+    stops: z.array(GeoRouteStopSchema).min(2).max(GEO_ROUTE_MAX_STOPS).describe("2–26 stops in travel order, with unique IDs."),
+    options: GeoRouteOptionsSchema.optional().describe("Default options for the route."),
+    legOptions: z
+      .array(GeoRouteLegOptionsSchema)
+      .max(25)
+      .optional()
+      .describe("Options for adjacent stop pairs; on move/optimization each override travels with its departure stop."),
+    optimize: z.boolean().optional().describe("Optimize intermediate stops; start and destination stay fixed."),
+  })
+  .strict();
+const geometry = z.string().min(2).max(GEO_MAX_POLYLINE_CHARS);
+export const GeoRouteLegSchema = z
+  .object({
+    fromStopId: stopId,
+    toStopId: stopId,
+    options: GeoRouteOptionsSchema.describe("Travel options; mode and avoid override only supplied fields."),
+    distanceMeters: z.number().nonnegative().describe("Travel distance in meters."),
+    durationSeconds: z.number().nonnegative().describe("Estimated travel duration in seconds, without live traffic."),
+    polyline6: geometry.describe("Encoded route geometry at precision six."),
+    simplificationToleranceMeters: z.number().nonnegative().describe("Conservative geometry simplification tolerance in meters."),
+    provenance: GeoProvenanceSchema.describe("Provider provenance and required attribution."),
+  })
+  .strict();
+export const GeoRouteSchema = z
+  .object({
+    distanceAllowanceMeters: GeoRouteDistanceAllowanceSchema,
+    stops: z.array(GeoRouteResolvedStopSchema).min(2).max(GEO_ROUTE_MAX_STOPS).describe("Resolved stops in current travel order."),
+    options: GeoRouteOptionsSchema.describe("Travel options; mode and avoid override only supplied fields."),
+    legs: z.array(GeoRouteLegSchema).min(1).max(25).describe("Independent stopover legs in travel order."),
+    distanceMeters: z.number().nonnegative().describe("Travel distance in meters."),
+    durationSeconds: z.number().nonnegative().describe("Estimated travel duration in seconds, without live traffic."),
+    polyline6: geometry.describe("Encoded route geometry at precision six."),
+    simplificationToleranceMeters: z.number().nonnegative().describe("Conservative geometry simplification tolerance in meters."),
+    inputHash: z
+      .string()
+      .regex(/^[a-f0-9]{64}$/)
+      .describe("SHA-256 fingerprint of the resolved route input; preserve when updating."),
+    provenance: GeoProvenanceSchema.describe("Provider provenance and required attribution."),
+  })
+  .strict()
+  .describe("Self-contained stateless route; preserve stops, legs, options and provenance when saving.");
+export const GeoRouteChangesSchema = z.discriminatedUnion("type", [
+  z
+    .object({
+      type: z.literal("insert").describe("Insert one stop."),
+      stop: GeoRouteStopSchema.describe("New stop to insert."),
+      afterStopId: stopId.optional().describe("Insert after this stop; omit to compare up to three best candidate gaps."),
+    })
+    .strict(),
+  z
+    .object({
+      type: z.literal("move").describe("Move an existing stop to a new index."),
+      stopId,
+      toIndex: z.number().int().min(0).max(25).describe("Zero-based destination index in the final stop order."),
+    })
+    .strict(),
+  z.object({ type: z.literal("optimize").describe("Optimize intermediate stop order while fixing start and destination.") }).strict(),
+  z
+    .object({
+      type: z.literal("options").describe("Change route defaults or one leg."),
+      options: GeoRouteOptionsSchema.describe("Travel options; mode and avoid override only supplied fields."),
+      leg: z
+        .object({ fromStopId: stopId, toStopId: stopId })
+        .strict()
+        .optional()
+        .describe("Change just this adjacent pair; omit to change route defaults and clear leg overrides."),
+    })
+    .strict(),
+]);
+export const GeoRouteCalculateInputSchema = z.object({ plan: GeoRoutePlanSchema.describe("Route stops and travel preferences.") }).strict();
+export const GeoRouteCalculateDataSchema = z.object({ route: GeoRouteSchema }).strict();
+export const GeoRouteUpdateInputSchema = z
+  .object({
+    route: GeoRouteSchema,
+    changes: GeoRouteChangesSchema.describe("One stateless route edit to preview."),
+    distanceAllowanceMeters: GeoRouteDistanceAllowanceSchema.optional(),
+  })
+  .strict();
+export const GeoRouteUpdateDataSchema = z
+  .object({
+    route: GeoRouteSchema,
+    before: z
+      .object({
+        stopIds: z.array(stopId).min(2).max(26),
+        distanceMeters: z.number().nonnegative().describe("Travel distance in meters."),
+        durationSeconds: z.number().nonnegative(),
+      })
+      .strict(),
+    after: z
+      .object({
+        stopIds: z.array(stopId).min(2).max(26),
+        distanceMeters: z.number().nonnegative().describe("Travel distance in meters."),
+        durationSeconds: z.number().nonnegative(),
+      })
+      .strict(),
+    delta: z.object({ distanceMeters: z.number(), durationSeconds: z.number() }).strict(),
+    insertion: z
+      .object({ afterStopId: stopId, candidateGaps: z.number().int().min(1).max(3), exhaustive: z.boolean() })
+      .strict()
+      .optional()
+      .describe("Best insertion is a three-gap heuristic when there are more than three gaps."),
+  })
+  .strict();
+export type GeoRouteOptions = z.infer<typeof GeoRouteOptionsSchema>;
+export type GeoRouteStop = z.infer<typeof GeoRouteStopSchema>;
+export type GeoRouteResolvedStop = z.infer<typeof GeoRouteResolvedStopSchema>;
+export type GeoRouteLegOptions = z.infer<typeof GeoRouteLegOptionsSchema>;
+export type GeoRoutePlan = z.infer<typeof GeoRoutePlanSchema>;
+export type GeoRouteLeg = z.infer<typeof GeoRouteLegSchema>;
+export type GeoRoute = z.infer<typeof GeoRouteSchema>;
+export type GeoRouteChanges = z.infer<typeof GeoRouteChangesSchema>;
+export type GeoRouteCalculateInput = z.infer<typeof GeoRouteCalculateInputSchema>;
+export type GeoRouteCalculateData = z.infer<typeof GeoRouteCalculateDataSchema>;
+export type GeoRouteUpdateInput = z.infer<typeof GeoRouteUpdateInputSchema>;
+export type GeoRouteUpdateData = z.infer<typeof GeoRouteUpdateDataSchema>;
+export const geoRouteContract = {
+  calculateRoute: { id: "route.calculate", input: GeoRouteCalculateInputSchema, data: GeoRouteCalculateDataSchema },
+  updateRoute: { id: "route.update", input: GeoRouteUpdateInputSchema, data: GeoRouteUpdateDataSchema },
+} as const;