feat(GRO-2155): route CRUD + optimization endpoint (Phase 2.1)

Adds the core route engine for Mobile Groomer Route Optimization:

- src/services/routeOptimization.ts — order a day's geocoded stops via
  Google Directions (optimizeWaypoints:true) when a Maps API key is
  configured, else an offline nearest-neighbor TSP heuristic over
  great-circle distance. Handles the >25-stop edge case by chunking into
  sub-routes (Directions waypoint cap) with a user warning, degrades to
  the heuristic if Google errors mid-run, and resolves the API key from
  businessSettings.googleMapsApiKey (decrypted) / GOOGLE_MAPS_API_KEY.
- src/routes/routes.ts — GET /api/routes/daily (fetch/create draft route
  + enriched stops) and POST /api/routes/optimize (generate/re-optimize,
  persist stopOrder + travelMinsFromPrev + travelDistanceKmFromPrev and
  route totals/optimizedAt in one transaction). Auth: manager (any) or
  groomer (own route only); receptionists denied. Un-geocoded
  appointments are skipped and surfaced.
- src/index.ts — mount /api/routes under requireRole("manager","groomer").
- Unit tests for haversine, leg estimation, nearest-neighbor ordering,
  the Google path (mocked fetch), chunking, and fallback.
- UAT_PLAYBOOK.md §4.16 — new Route Optimization test cases.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

.gitea/workflows/ci.yml

@@ -33,11 +33,11 @@ jobs:
 
       - name: Typecheck
         run: |
-          pnpm --filter @groombook/api typecheck
+          pnpm run typecheck
           pnpm --filter @groombook/db typecheck
 
       - name: Lint
-        run: pnpm --filter @groombook/api lint
+        run: pnpm run lint
 
   test:
     name: Test
@@ -58,7 +58,7 @@ jobs:
         run: pnpm install --frozen-lockfile
 
       - name: Run tests
-        run: pnpm --filter @groombook/api test
+        run: pnpm run test
 
   docker:
     name: Build & Push Docker Images

UAT_PLAYBOOK.md

@@ -120,6 +120,24 @@ Expected: one row, `role = 'groomer'`. If zero rows return, the request hit the
 | TC-API-2.5 | Disable client | PATCH /api/clients/{id} with status: "disabled" | 200 OK, client marked as disabled |
 | TC-API-2.6 | Delete client | DELETE /api/clients/{id}?confirm=true | 200 OK, client deleted (if no appointments) |
 
+#### Client Geocoding — Route Optimization (GRO-2154, Phase 1.3)
+
+Geocoding turns a client's street address into `latitude`/`longitude` + `geocodedAt`. Provider is driven by `businessSettings.routeOptimizationProvider` (default Nominatim/OpenStreetMap, 1 req/sec; optional Google fallback). All explicit geocode endpoints are **manager-only**.
+
+| # | Scenario | Steps | Expected |
+|---|----------|-------|----------|
+| TC-API-2.7 | Geocode single client (success) | As **manager**, `POST /api/clients/{id}/geocode` for a client with a valid, real address (e.g. a seed client) | 200 OK; body `{ status: "geocoded", latitude, longitude, geocodedAt, formattedAddress, provider }`. Subsequent `GET /api/clients/{id}` shows the same non-null `latitude`/`longitude`/`geocodedAt` persisted |
+| TC-API-2.8 | Geocode single client — no address | As manager, `POST /api/clients/{id}/geocode` for a client whose `address` is null/blank | 422; `{ status: "no_address", message: "...no address on file..." }` (clear, actionable) |
+| TC-API-2.9 | Geocode single client — unresolvable/ambiguous address | As manager, set a nonsense address (e.g. `"asdkjhqweoui 99999"`) then `POST /api/clients/{id}/geocode` | 422; `{ status: "unresolved", message: "Address could not be resolved..." }` so groomers/managers know to correct it |
+| TC-API-2.10 | Geocode single client — not found | As manager, `POST /api/clients/00000000-0000-0000-0000-000000000000/geocode` | 404 `{ error: "Not found" }` |
+| TC-API-2.11 | Geocode endpoint is manager-only | As **groomer** or **receptionist**, `POST /api/clients/{id}/geocode` | 403 Forbidden (role not permitted) |
+| TC-API-2.12 | Batch geocode un-geocoded clients | As manager, `POST /api/clients/geocode-batch?limit=10` on a DB with un-geocoded clients | 200 OK; body `{ provider, processed, geocoded, unresolved, errors, remaining, outcomes[] }`. `processed` ≤ 10; `remaining` reflects un-geocoded clients beyond this batch. Re-run while `remaining > 0` to finish (throttled to provider rate limit) |
+| TC-API-2.13 | Batch geocode — invalid limit | As manager, `POST /api/clients/geocode-batch?limit=0` (or non-numeric) | 400 `{ error: "limit must be a positive integer" }` |
+| TC-API-2.14 | Batch geocode — manager-only | As groomer/receptionist, `POST /api/clients/geocode-batch` | 403 Forbidden |
+| TC-API-2.15 | Auto-geocode on create | As manager/receptionist, `POST /api/clients` with a valid `address` | 201 Created; response includes a `geocoding` object (`status: "geocoded"` for a resolvable address) and the persisted client carries `latitude`/`longitude`/`geocodedAt`. Creating without an address succeeds with no `geocoding` field |
+| TC-API-2.16 | Auto-geocode on address update | As manager/receptionist, `PATCH /api/clients/{id}` changing `address` to a new valid value | 200 OK; response includes a `geocoding` object and refreshed coordinates. Patching unrelated fields (e.g. `name`) does NOT re-geocode (no `geocoding` field) |
+| TC-API-2.17 | Clearing address drops coordinates | As manager/receptionist, `PATCH /api/clients/{id}` with `address: ""` | 200 OK; `latitude`/`longitude`/`geocodedAt` reset to null (no stale pin) |
+
 ### 4.3 Pet Management
 
 | # | Scenario | Steps | Expected |
@@ -166,6 +184,7 @@ Expected: one row, `role = 'groomer'`. If zero rows return, the request hit the
 | TC-API-3.26 | Verify 25-35% medicalAlerts distribution | GET /api/pets (first 30 pets), count how many have non-empty medicalAlerts | Ratio is 25-35% (seed uses rand() < 0.3 for ~30% distribution) |
 | TC-API-3.27 | Verify coat_type enum has all seed values | After UAT seed completes, inspect the coat_type enum on the UAT DB — it must contain: short, medium, long, double, wire, silky, curly, hairless | UAT seed jobs (`reset-demo-data`, `seed-test-data`) complete 1/1 with no `enum_in` error; coat_type includes all 8 values used by seed.ts `coatTypePool` |
 | TC-API-3.28 | Verify pet_size_category enum has all seed values | After UAT seed completes, inspect the pet_size_category enum on the UAT DB — it must contain: small, medium, large, extra_large | UAT seed jobs (`reset-demo-data`, `seed-test-data`) complete 1/1 with no `enum_in` error; pet_size_category includes all 4 values used by seed.ts `petSizeCategoryPool` (regression for GRO-1999, mirrors TC-API-3.27) |
+| TC-API-3.29 | Verify `reset-demo-data` CronJob does not fail with FK 23503 on `invoice_tip_splits` (GRO-2123) | Trigger the CronJob manually: `kubectl create job --from=cronjob/reset-demo-data verify-gro2123 -n groombook-uat`. Wait for pod to terminate. Inspect logs: `kubectl logs -n groombook-uat -l job-name=verify-gro2123` | Pod reaches `Completed` state; logs show `✓ Acquired seed advisory lock` and `✓ Released seed advisory lock` from `seed.ts`; no `PostgresError: … violates foreign key constraint "invoice_tip_splits_invoice_id_invoices_id_fk"` (code 23503); final counts unchanged (500 clients, ~4000 invoices) |
 
 ### 4.4 Appointment Scheduling
 
@@ -258,6 +277,10 @@ This means:
 | TC-API-8.9 | SSO bridge — no Better Auth session | POST /api/portal/session-from-auth without Better Auth session cookie | 401 Unauthorized |
 | TC-API-8.10 | SSO bridge — no matching client | POST /api/portal/session-from-auth with valid Better Auth session for a user with no client record | 404 Not Found, error "No client record found for this user" |
 | TC-API-8.11 | SSO bridge — returned session works on portal routes | After TC-API-8.8, use returned sessionId as `X-Impersonation-Session-Id` header on GET /api/portal/me | 200 OK, client profile returned |
+| TC-API-8.12 | Portal GET pets returns extended fields (GRO-2187) | Establish a portal session (TC-API-8.8), then `GET /api/portal/pets` with `X-Impersonation-Session-Id` | 200 OK; each pet includes `coatType`, `petSizeCategory`, `healthAlerts`, `preferredCuts`, `medicalAlerts` (in addition to id/name/breed/weight/birthDate/photoUrl/notes) |
+| TC-API-8.13 | Portal pet update — owner success + persistence (GRO-2187, fixes [GRO-1480](/GRO/issues/GRO-1480) §5.23) | With a portal session for the pet's owner, `PATCH /api/portal/pets/{petId}` with body `{ "name": "...", "breed": "...", "weightKg": 18.25, "healthAlerts": "...", "coatType": "double", "petSizeCategory": "xlarge", "preferredCuts": ["teddy bear"], "medicalAlerts": [{"type":"allergy","description":"oatmeal","severity":"medium"}] }` | 200 OK; response reflects the update with `petSizeCategory: "extra_large"` (web `xlarge` → DB `extra_large`). A follow-up `GET /api/portal/pets` shows the persisted values |
+| TC-API-8.14 | Portal pet update — non-owner blocked (GRO-2187) | `PATCH /api/portal/pets/{petId}` for a pet owned by a different client, using another client's portal session | 403 Forbidden (or 404 if pet id is unknown); no mutation persisted |
+| TC-API-8.15 | Portal pet update — invalid enum rejected (GRO-2187) | `PATCH /api/portal/pets/{petId}` with `coatType: "fluffy"` or `petSizeCategory: "gigantic"` | 422 Unprocessable Entity; pet unchanged |
 
 ### 4.9 Waitlist
 
@@ -335,6 +358,24 @@ This means:
 | TC-API-15.6 | Reject missing required fields | POST /api/admin/buffer-rules with service only | 400 Bad Request, species and sizeCategory required |
 | TC-API-15.7 | Booking uses buffer | Book appointment for pet with sizeCategory; verify duration reflects buffer | 201 Created, appointment duration includes buffer time |
 
+### 4.16 Route Optimization — Route CRUD + Optimize (GRO-2155, Phase 2.1)
+
+A groomer's daily route is one row per `(staffId, routeDate)` in `groomer_routes`, with ordered `route_stops`. `POST /api/routes/optimize` pulls the day's non-cancelled appointments whose client is geocoded (GRO-2154), orders them (Google Directions `optimizeWaypoints` when a key is configured in `businessSettings.googleMapsApiKey`, else an offline nearest-neighbor heuristic), and persists `stopOrder`, `travelMinsFromPrev`, `travelDistanceKmFromPrev` plus route `totalTravelMins`/`totalDistanceKm`/`optimizedAt`. **Auth: manager (any groomer's route) or groomer (own route only); receptionists have no access.** Pre-condition: at least one geocoded client with appointments on the target date for the staff member (use §4.2 geocoding + a seed groomer).
+
+| # | Scenario | Steps | Expected |
+|---|----------|-------|----------|
+| TC-API-16.1 | Fetch daily route (auto-create draft) | As **manager**, `GET /api/routes/daily?staffId={groomerId}&date=YYYY-MM-DD` for a date with no existing route | 200 OK; body `{ route, stops }`. `route.status` is `"draft"`, `route.staffId`/`routeDate` match, `stops` is `[]`. Re-calling returns the same route row (no duplicate) |
+| TC-API-16.2 | Optimize a multi-stop day | As manager, with ≥2 geocoded appointments for the groomer on the date, `POST /api/routes/optimize` body `{ "staffId": "{groomerId}", "date": "YYYY-MM-DD" }` | 200 OK; `route.status: "optimized"`, `optimizedAt` set, `totalTravelMins`/`totalDistanceKm` populated. `stops` ordered by `stopOrder` (1..N); first stop has `travelMinsFromPrev: null`, the rest positive. `provider` is `"nearest_neighbor"` (no Google key in UAT). Each stop carries `bufferMins` (default 15) |
+| TC-API-16.3 | Re-optimize replaces prior order | As manager, run TC-API-16.2 twice | Second call returns 200; stops fully replaced (no duplicate `route_stops`, `stopOrder` still contiguous 1..N), `optimizedAt` refreshed |
+| TC-API-16.4 | Skips un-geocoded appointments | As manager, optimize a day where one appointment's client has no coordinates | 200 OK; that appointment is absent from `stops` and listed under `skipped[]` with `reason: "client address is not geocoded"`; a corresponding entry appears in `warnings[]` |
+| TC-API-16.5 | Empty / single-stop day | As manager, optimize a date with 0 (or 1) geocoded appointments | 200 OK; `route.status: "optimized"`, `totalTravelMins: 0`, `totalDistanceKm: "0.00"`. For 1 stop, `stops` has one entry with `travelMinsFromPrev: null` |
+| TC-API-16.6 | >25 stops chunked with warning | As manager, optimize a day with >25 geocoded appointments | 200 OK; `chunked: true`, `subRouteCount ≥ 2`, a `warnings[]` entry mentions sub-routes; all appointments appear exactly once with contiguous `stopOrder` |
+| TC-API-16.7 | Groomer reads own route | As **groomer**, `GET /api/routes/daily?date=YYYY-MM-DD` (omit staffId, or pass own id) | 200 OK; route resolves to the groomer's own `staffId` |
+| TC-API-16.8 | Groomer cannot access another's route | As groomer, `GET /api/routes/daily?staffId={otherGroomerId}&date=...` or `POST /api/routes/optimize` with another `staffId` | 403 Forbidden (`groomers may only access their own route`) |
+| TC-API-16.9 | Receptionist denied | As **receptionist**, `GET /api/routes/daily?...` or `POST /api/routes/optimize` | 403 Forbidden (role not permitted) |
+| TC-API-16.10 | Manager must supply staffId | As manager, `POST /api/routes/optimize` body `{ "date": "YYYY-MM-DD" }` (no staffId) | 400 `{ error: "staffId is required" }` |
+| TC-API-16.11 | Invalid date rejected | `GET /api/routes/daily?staffId=...&date=06-08-2026` (wrong format) | 400 validation error (`date must be YYYY-MM-DD`) |
+
 ## Pass/Fail Criteria
 
 **Pass:**

apps/api/package.json

@@ -12,8 +12,8 @@
     "test": "vitest run",
     "db:generate": "drizzle-kit generate",
     "db:migrate": "drizzle-kit migrate",
-    "db:seed": "tsx src/db/seed.ts",
-    "db:reset": "tsx src/db/reset.ts && drizzle-kit migrate && tsx src/db/seed.ts",
+    "db:seed": "pnpm --filter @groombook/db seed",
+    "db:reset": "pnpm --filter @groombook/db reset",
     "db:studio": "drizzle-kit studio"
   },
   "dependencies": {

packages/db/migrations/0041_route_optimization.sql

@@ -0,0 +1,66 @@
+-- Migration: 0041_route_optimization.sql
+-- Route optimization schema: geocoding columns on clients, groomerRoutes +
+-- routeStops tables, and route settings on business_settings.
+-- Written idempotently so it is safe to re-run.
+
+-- ─── Enums ────────────────────────────────────────────────────────────────────
+
+DO $$ BEGIN
+  CREATE TYPE "route_status" AS ENUM ('draft', 'optimized', 'in_progress', 'completed');
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
+
+-- ─── Clients: geocoding columns ───────────────────────────────────────────────
+
+ALTER TABLE "clients" ADD COLUMN IF NOT EXISTS "latitude" double precision;
+ALTER TABLE "clients" ADD COLUMN IF NOT EXISTS "longitude" double precision;
+ALTER TABLE "clients" ADD COLUMN IF NOT EXISTS "geocoded_at" timestamp;
+
+-- ─── Business settings: route optimization config ─────────────────────────────
+
+ALTER TABLE "business_settings"
+  ADD COLUMN IF NOT EXISTS "default_travel_buffer_mins" integer NOT NULL DEFAULT 15;
+ALTER TABLE "business_settings"
+  ADD COLUMN IF NOT EXISTS "route_optimization_provider" text DEFAULT 'nominatim';
+-- Encrypted at rest at the application layer (AES-256-GCM).
+ALTER TABLE "business_settings"
+  ADD COLUMN IF NOT EXISTS "google_maps_api_key" text;
+
+-- ─── Groomer routes table ─────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS "groomer_routes" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "staff_id" uuid NOT NULL REFERENCES "staff"("id") ON DELETE CASCADE,
+  "route_date" date NOT NULL,
+  "status" "route_status" NOT NULL DEFAULT 'draft',
+  "total_travel_mins" integer,
+  "total_distance_km" numeric(8, 2),
+  "optimized_at" timestamp,
+  "created_at" timestamp NOT NULL DEFAULT now(),
+  "updated_at" timestamp NOT NULL DEFAULT now(),
+  CONSTRAINT "uq_groomer_routes_staff_date" UNIQUE ("staff_id", "route_date")
+);
+
+CREATE INDEX IF NOT EXISTS "idx_groomer_routes_staff_id"
+  ON "groomer_routes"("staff_id");
+
+-- ─── Route stops table ────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS "route_stops" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "route_id" uuid NOT NULL REFERENCES "groomer_routes"("id") ON DELETE CASCADE,
+  "appointment_id" uuid NOT NULL REFERENCES "appointments"("id") ON DELETE CASCADE,
+  "stop_order" integer NOT NULL,
+  "latitude" double precision NOT NULL,
+  "longitude" double precision NOT NULL,
+  "travel_mins_from_prev" integer,
+  "travel_distance_km_from_prev" numeric(8, 2),
+  "buffer_mins" integer NOT NULL DEFAULT 15,
+  "created_at" timestamp NOT NULL DEFAULT now(),
+  "updated_at" timestamp NOT NULL DEFAULT now(),
+  CONSTRAINT "uq_route_stops_route_appointment" UNIQUE ("route_id", "appointment_id"),
+  CONSTRAINT "uq_route_stops_route_order" UNIQUE ("route_id", "stop_order")
+);
+
+CREATE INDEX IF NOT EXISTS "idx_route_stops_route_id"
+  ON "route_stops"("route_id");

packages/db/migrations/meta/_journal.json

@@ -281,6 +281,13 @@
       "when": 1780000000002,
       "tag": "0040_register_missing_coat_type_values",
       "breakpoints": true
+    },
+    {
+      "idx": 41,
+      "version": "7",
+      "when": 1780000000003,
+      "tag": "0041_route_optimization",
+      "breakpoints": true
     }
   ]
-}
+}

packages/db/package.json

@@ -18,9 +18,10 @@
   "scripts": {
     "build": "tsc --project .",
     "generate": "drizzle-kit generate",
-    "migrate": "drizzle-kit migrate",
-    "seed": "tsx src/seed.ts",
-    "reset": "tsx src/reset.ts && drizzle-kit migrate && tsx src/seed.ts",
+    "wait-for-db": "node ./scripts/wait-for-db.mjs",
+    "migrate": "node ./scripts/wait-for-db.mjs && drizzle-kit migrate",
+    "seed": "node ./scripts/wait-for-db.mjs && tsx src/seed.ts",
+    "reset": "node ./scripts/wait-for-db.mjs && tsx src/reset.ts && drizzle-kit migrate && tsx src/seed.ts",
     "studio": "drizzle-kit studio",
     "typecheck": "tsc --noEmit"
   },

packages/db/scripts/wait-for-db.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+// wait-for-db.mjs
+//
+// GRO-2163: wait for / retry DNS resolution of the database hostname derived
+// from DATABASE_URL before invoking `drizzle-kit migrate`. The first attempt
+// of a fresh migrate-schema pod occasionally hits a transient CoreDNS miss
+// (EAI_AGAIN) on `groombook-postgres-rw.<ns>.svc`; with backoffLimit: 2 the
+// retry pod usually wins, but three unlucky attempts in a row trips
+// BackoffLimitExceeded. Resolving once here, with backoff, removes the dice
+// roll at the source so the first attempt reliably succeeds.
+//
+// Mirrors the belt-and-braces pattern used in GRO-1985 (no Corepack
+// download fallback): we don't try to outsmart CoreDNS, we just don't ask
+// drizzle-kit to do the very first DNS lookup of a freshly-scheduled pod.
+//
+// Configuration (env):
+//   WAIT_FOR_DB_MAX_ATTEMPTS  default 12  (~30s of total wait at default backoff)
+//   WAIT_FOR_DB_BASE_DELAY_MS default 500
+//   WAIT_FOR_DB_MAX_DELAY_MS  default 5000
+//   WAIT_FOR_DB_SKIP          default unset; set to "1" to skip (debug only)
+//
+// On success: exit 0. On exhaustion: exit 1 so the Job's backoff is
+// preserved (we don't want to silently mask a real outage by giving up
+// after 30s and letting drizzle-kit fail with a less-actionable error).
+
+import { setTimeout as delay } from "node:timers/promises";
+import dns from "node:dns/promises";
+
+const MAX_ATTEMPTS = Number(process.env.WAIT_FOR_DB_MAX_ATTEMPTS ?? 12);
+const BASE_DELAY_MS = Number(process.env.WAIT_FOR_DB_BASE_DELAY_MS ?? 500);
+const MAX_DELAY_MS = Number(process.env.WAIT_FOR_DB_MAX_DELAY_MS ?? 5000);
+
+function parseHost(databaseUrl) {
+  try {
+    return new URL(databaseUrl).hostname || null;
+  } catch {
+    return null;
+  }
+}
+
+async function resolveOnce(host) {
+  const start = Date.now();
+  const result = await dns.lookup(host);
+  return { address: result.address, ms: Date.now() - start };
+}
+
+async function main() {
+  if (process.env.WAIT_FOR_DB_SKIP === "1") {
+    console.log("[wait-for-db] WAIT_FOR_DB_SKIP=1, skipping");
+    return;
+  }
+  const databaseUrl = process.env.DATABASE_URL;
+  if (!databaseUrl) {
+    // Don't gate the migrate on a misconfigured env — let drizzle-kit fail
+    // loudly with its own clear error.
+    console.warn("[wait-for-db] DATABASE_URL not set; skipping");
+    return;
+  }
+  const host = parseHost(databaseUrl);
+  if (!host) {
+    console.warn(`[wait-for-db] could not parse hostname from DATABASE_URL; skipping`);
+    return;
+  }
+  console.log(
+    `[wait-for-db] host=${host} max_attempts=${MAX_ATTEMPTS} ` +
+      `base_delay_ms=${BASE_DELAY_MS} max_delay_ms=${MAX_DELAY_MS}`,
+  );
+
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    try {
+      const { address, ms } = await resolveOnce(host);
+      console.log(`[wait-for-db] ok attempt=${attempt} host=${host} -> ${address} (${ms}ms)`);
+      return;
+    } catch (err) {
+      const code = err?.code ?? "UNKNOWN";
+      const transient = code === "EAI_AGAIN" || code === "ENOTFOUND" || code === "EAI_NODATA";
+      if (!transient) {
+        // Hard error (e.g. invalid hostname): surface and let drizzle-kit fail
+        // with a real error rather than spinning.
+        console.error(`[wait-for-db] non-transient DNS error attempt=${attempt} code=${code}: ${err.message}`);
+        process.exit(1);
+      }
+      if (attempt === MAX_ATTEMPTS) {
+        console.error(
+          `[wait-for-db] exhausted attempts=${MAX_ATTEMPTS} host=${host} last_code=${code}; exiting 1`,
+        );
+        process.exit(1);
+      }
+      const backoff = Math.min(
+        MAX_DELAY_MS,
+        BASE_DELAY_MS * 2 ** (attempt - 1) + Math.floor(Math.random() * BASE_DELAY_MS),
+      );
+      console.log(
+        `[wait-for-db] transient attempt=${attempt} code=${code} retry_in_ms=${backoff}`,
+      );
+      await delay(backoff);
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error(`[wait-for-db] fatal: ${err?.message ?? err}`);
+  process.exit(1);
+});

packages/db/src/factories.ts

@@ -78,6 +78,9 @@ export function buildClient(overrides: Partial<ClientRow> = {}): ClientRow {
     stripeCustomerId: null,
     status: "active",
     disabledAt: null,
+    latitude: null,
+    longitude: null,
+    geocodedAt: null,
     createdAt: new Date("2025-01-01T00:00:00Z"),
     updatedAt: new Date("2025-01-01T00:00:00Z"),
     ...overrides,

packages/db/src/schema.ts

@@ -1,5 +1,7 @@
 import {
   boolean,
+  date,
+  doublePrecision,
   index,
   integer,
   jsonb,
@@ -140,6 +142,10 @@ export const clients = pgTable(
     stripeCustomerId: text("stripe_customer_id"),
     status: clientStatusEnum("status").notNull().default("active"),
     disabledAt: timestamp("disabled_at"),
+    // Geocoded coordinates for route optimization; null until geocoded.
+    latitude: doublePrecision("latitude"),
+    longitude: doublePrecision("longitude"),
+    geocodedAt: timestamp("geocoded_at"),
     createdAt: timestamp("created_at").notNull().defaultNow(),
     updatedAt: timestamp("updated_at").notNull().defaultNow(),
   },
@@ -555,6 +561,16 @@ export const businessSettings = pgTable("business_settings", {
   accentColor: text("accent_color").notNull().default("#8b7355"),
   messagingPhoneNumber: text("messaging_phone_number"),
   telnyxMessagingProfileId: text("telnyx_messaging_profile_id"),
+  // Route optimization settings.
+  defaultTravelBufferMins: integer("default_travel_buffer_mins")
+    .notNull()
+    .default(15),
+  routeOptimizationProvider: text("route_optimization_provider").default(
+    "nominatim"
+  ),
+  // Encrypted at rest at the application layer (AES-256-GCM), mirroring
+  // the handling of authProviderConfigs.clientSecret.
+  googleMapsApiKey: text("google_maps_api_key"),
   createdAt: timestamp("created_at").notNull().defaultNow(),
   updatedAt: timestamp("updated_at").notNull().defaultNow(),
 });
@@ -658,3 +674,69 @@ export const bufferRules = pgTable(
     index("idx_buffer_rules_service_id").on(t.serviceId),
   ]
 );
+
+// ─── Route Optimization ───────────────────────────────────────────────────────
+
+export const routeStatusEnum = pgEnum("route_status", [
+  "draft",
+  "optimized",
+  "in_progress",
+  "completed",
+]);
+
+// A groomer's optimized route for a single day. One row per (staff, date).
+export const groomerRoutes = pgTable(
+  "groomer_routes",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    staffId: uuid("staff_id")
+      .notNull()
+      .references(() => staff.id, { onDelete: "cascade" }),
+    routeDate: date("route_date", { mode: "string" }).notNull(),
+    status: routeStatusEnum("status").notNull().default("draft"),
+    // Populated once the route is optimized.
+    totalTravelMins: integer("total_travel_mins"),
+    totalDistanceKm: numeric("total_distance_km", { precision: 8, scale: 2 }),
+    optimizedAt: timestamp("optimized_at"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+  },
+  (t) => [
+    // One route per groomer per day.
+    unique("uq_groomer_routes_staff_date").on(t.staffId, t.routeDate),
+    index("idx_groomer_routes_staff_id").on(t.staffId),
+  ]
+);
+
+// An ordered stop within a groomer's route, tied to an appointment.
+export const routeStops = pgTable(
+  "route_stops",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    routeId: uuid("route_id")
+      .notNull()
+      .references(() => groomerRoutes.id, { onDelete: "cascade" }),
+    appointmentId: uuid("appointment_id")
+      .notNull()
+      .references(() => appointments.id, { onDelete: "cascade" }),
+    stopOrder: integer("stop_order").notNull(),
+    latitude: doublePrecision("latitude").notNull(),
+    longitude: doublePrecision("longitude").notNull(),
+    // Null for the first stop in the route.
+    travelMinsFromPrev: integer("travel_mins_from_prev"),
+    travelDistanceKmFromPrev: numeric("travel_distance_km_from_prev", {
+      precision: 8,
+      scale: 2,
+    }),
+    bufferMins: integer("buffer_mins").notNull().default(15),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+  },
+  (t) => [
+    // An appointment appears at most once per route.
+    unique("uq_route_stops_route_appointment").on(t.routeId, t.appointmentId),
+    // Stop order is unique within a route.
+    unique("uq_route_stops_route_order").on(t.routeId, t.stopOrder),
+    index("idx_route_stops_route_id").on(t.routeId),
+  ]
+);

packages/db/src/seed.ts

@@ -401,7 +401,9 @@ const servicesDef = [
  *
  * In seedKnownUsers() this replaces the inline UAT-staff block.
  */
-async function seedUatStaffAccounts(db: ReturnType<typeof drizzle>) {
+async function seedUatStaffAccounts(
+  db: ReturnType<typeof drizzle>,
+): Promise<string | null> {
   // ── Staff: UAT Super User (oidcSub from SEED_UAT_SUPER_OIDC_SUB env var) ──
   const uatSuperOidcSub = process.env.SEED_UAT_SUPER_OIDC_SUB;
   if (uatSuperOidcSub) {
@@ -677,7 +679,12 @@ async function seedUatStaffAccounts(db: ReturnType<typeof drizzle>) {
   // We deterministically link the UAT groomer to the UAT customer's first pet
   // ("UAT Pup Alpha") and leave the second pet ("UAT Pup Beta") UNLINKED so
   // TC-UAT-2 (200) and TC-UAT-3 (403) can both hardcode the stable petIds.
-  await seedUatGroomerLinkage(db, uatCustomerClientId);
+  //
+  // The linkage call itself is performed by the caller AFTER the `services`
+  // catalogue has been seeded (this helper runs before services exist,
+  // which previously caused the linkage to be silently skipped on every
+  // reset). GRO-2100 follow-up.
+  return uatCustomerClientId;
 }
 
 /**
@@ -692,12 +699,18 @@ async function seedUatStaffAccounts(db: ReturnType<typeof drizzle>) {
  */
 async function seedUatGroomerLinkage(
   db: ReturnType<typeof drizzle>,
-  customerClientId: string,
+  customerClientId: string | null,
 ): Promise<void> {
   const uatGroomerEmail = "uat-groomer@groombook.dev";
   const LINKED_PET_ID = "c0000001-0000-0000-0000-000000000002"; // UAT Pup Alpha
   const APPT_ID = "a0000001-0000-0000-0000-000000000001";
 
+  // Skip silently if the UAT Customer client wasn't created (non-UAT seed
+  // profile, e.g. seedKnownUsers() in an env without the UAT personas).
+  if (!customerClientId) {
+    return;
+  }
+
   // Only run if the UAT groomer staff record actually exists — dev/test seeds
   // that don't set SEED_UAT_STAFF_OIDC_SUB should not crash.
   const [uatGroomerStaff] = await db
@@ -720,6 +733,19 @@ async function seedUatGroomerLinkage(
     return;
   }
 
+  // Skip if the linked pet hasn't been seeded yet (defensive: caller should
+  // ensure pets exist; if the helper is re-ordered later we don't want to
+  // crash here).
+  const [linkedPet] = await db
+    .select({ id: schema.pets.id })
+    .from(schema.pets)
+    .where(eq(schema.pets.id, LINKED_PET_ID))
+    .limit(1);
+  if (!linkedPet) {
+    console.warn(`⚠ GRO-2100: UAT Pup Alpha (${LINKED_PET_ID}) not found — skipping uat-groomer linkage`);
+    return;
+  }
+
   // The "Bath & Brush" service id is stable across the reset; falls back to
   // any active service if it has not been seeded yet (e.g. seedKnownUsers
   // runs in isolation).
@@ -847,7 +873,7 @@ async function seedKnownUsers() {
   // ── UAT staff accounts + Better Auth credentials (shared impl) ──────────────
   // Extracted into seedUatStaffAccounts() so it runs in both seedKnownUsers()
   // and the full seed() UAT branch.
-  await seedUatStaffAccounts(db);
+  const uatCustomerClientId = await seedUatStaffAccounts(db);
 
   // ── Services: idempotent upsert keyed on `id` ─────────────────────────────
   // GRO-2064: previously keyed on `services.name` while writing a
@@ -875,6 +901,12 @@ async function seedKnownUsers() {
   }
   console.log(`✓ Seeded ${demoSvcs.length} services`);
 
+  // GRO-2100: deterministic uat-groomer ↔ UAT Pup Alpha linkage. Must run
+  // AFTER services are seeded (this helper looks up an active service id
+  // to attach to the appointment; on a fresh reset there are none yet at
+  // the time seedUatStaffAccounts() returns).
+  await seedUatGroomerLinkage(db, uatCustomerClientId);
+
   // ── Client: Demo Client ──
   const [existingClient] = await db
     .select()
@@ -944,6 +976,63 @@ async function seedKnownUsers() {
 
 // ── Main seed ────────────────────────────────────────────────────────────────
 
+// ── GRO-2123: serialize reset+seed with a Postgres advisory lock ────────
+// The reset-demo-data CronJob runs on an hourly schedule. With
+// concurrencyPolicy=Replace, a new pod can start while the previous one
+// is still mid-seed; the new pod's TRUNCATE then deletes rows the old pod
+// is still inserting, producing FK 23503 errors non-deterministically
+// (see GRO-2123: invoice_tip_splits → invoices).
+//
+// We hold a session-level advisory lock for the full duration of the
+// seed so that overlapping invocations block then proceed in order —
+// not skip. The key is a stable 32-bit constant so it can be referenced
+// from runbooks without ambiguity and binds to the single-argument
+// `pg_advisory_lock(int)` form, which postgres-js serializes as a plain
+// number (no bigint type plumbing required).
+const SEED_ADVISORY_LOCK_KEY = 0x47524f4f; // "GROO" in ASCII — arbitrary, stable
+
+/**
+ * Reserve a dedicated connection from `pool`, take the seed advisory lock
+ * on it, run `fn`, and release the lock + connection in a try/finally.
+ *
+ * CRITICAL: with postgres-js connection pooling, a session-level
+ * `pg_advisory_lock(KEY)` acquired on one pooled connection and released
+ * on a *different* one is a no-op (the lock is bound to the session /
+ * pg-backend that took it). We therefore reserve a dedicated connection
+ * for the lock and release it from the same reserved connection. The
+ * seed work itself still runs on the pooled connections.
+ */
+async function withSeedAdvisoryLock<T>(
+  pool: ReturnType<typeof postgres>,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const lockConnection = await pool.reserve();
+  let lockHeld = false;
+  try {
+    await lockConnection`SELECT pg_advisory_lock(${SEED_ADVISORY_LOCK_KEY})`;
+    lockHeld = true;
+    console.log(`✓ Acquired seed advisory lock (key=${SEED_ADVISORY_LOCK_KEY})`);
+    const result = await fn();
+    await lockConnection`SELECT pg_advisory_unlock(${SEED_ADVISORY_LOCK_KEY})`;
+    lockHeld = false;
+    console.log(`✓ Released seed advisory lock`);
+    return result;
+  } finally {
+    if (lockHeld) {
+      try {
+        await lockConnection`SELECT pg_advisory_unlock(${SEED_ADVISORY_LOCK_KEY})`;
+      } catch (err) {
+        console.error("Failed to release seed advisory lock during cleanup:", err);
+      }
+    }
+    try {
+      lockConnection.release();
+    } catch (err) {
+      console.error("Failed to release reserved lock connection:", err);
+    }
+  }
+}
+
 async function seed() {
   const url = process.env.DATABASE_URL;
   if (!url) {
@@ -961,6 +1050,22 @@ async function seed() {
   const client = postgres(url, { max: 5 });
   const db = drizzle(client, { schema });
 
+  // GRO-2123: hold the seed advisory lock for the full body of runSeedBody.
+  // See the withSeedAdvisoryLock comment for why a reserved connection is
+  // required (postgres-js pooling would silently drop the lock otherwise).
+  await withSeedAdvisoryLock(client, async () => {
+    return await runSeedBody(client, db, profile, cfg);
+  });
+
+  await client.end();
+}
+
+async function runSeedBody(
+  client: ReturnType<typeof postgres>,
+  db: ReturnType<typeof drizzle>,
+  profile: SeedProfile,
+  cfg: ProfileConfig,
+): Promise<void> {
   console.log(`Seeding Groom Book database (profile: ${profile})...\n`);
 
   // ── Staff ──
@@ -1031,7 +1136,7 @@ async function seed() {
   // ── UAT staff accounts + Better Auth credentials (shared impl) ──────────────
   // Seeds deterministic UAT staff with numeric OIDC subs and Better Auth credentials.
   // Must run AFTER random staff are created so upserts land correctly.
-  await seedUatStaffAccounts(db);
+  const uatCustomerClientId = await seedUatStaffAccounts(db);
 
   // ── Services ──
   // GRO-2064: key the upsert on `services.id` (not `name`) so deterministic
@@ -1058,6 +1163,12 @@ async function seed() {
   }
   console.log(`✓ Created ${servicesDef.length} services`);
 
+  // GRO-2100: deterministic uat-groomer ↔ UAT Pup Alpha linkage. Must run
+  // AFTER services are seeded (this helper looks up an active service id
+  // to attach to the appointment; on a fresh reset there are none yet at
+  // the time seedUatStaffAccounts() returns).
+  await seedUatGroomerLinkage(db, uatCustomerClientId);
+
   // ── Clients & Pets ──
   const now = new Date();
   const appointmentsBackDate = new Date(now);
@@ -1576,8 +1687,6 @@ async function seed() {
   }
   console.log(`✓ Created ${visitLogCount} grooming visit logs`);
   console.log("\nSeed complete!");
-
-  await client.end();
 }
 
 seed().catch((err) => {

src/__tests__/clientGeocoding.test.ts

@@ -0,0 +1,192 @@
+import { describe, it, expect, vi } from "vitest";
+import {
+  geocodeClient,
+  geocodeUngeocodedClients,
+  resolveClientGeocodingProvider,
+} from "../services/clientGeocoding.js";
+import {
+  NominatimGeocodingProvider,
+  type GeocodeResult,
+  type GeocodingProvider,
+} from "../services/geocoding.js";
+
+// ─── Fakes ──────────────────────────────────────────────────────────────────
+
+/** Fake provider with a scripted geocode behaviour and a call log. */
+function fakeProvider(
+  impl: (address: string) => Promise<GeocodeResult | null>
+): GeocodingProvider & { calls: string[] } {
+  const calls: string[] = [];
+  return {
+    name: "nominatim",
+    minRequestIntervalMs: 0,
+    calls,
+    geocode: (address: string) => {
+      calls.push(address);
+      return impl(address);
+    },
+  };
+}
+
+const okResult = (lat: number, lng: number): GeocodeResult => ({
+  latitude: lat,
+  longitude: lng,
+  formattedAddress: "1 Main St, Anytown",
+  provider: "nominatim",
+});
+
+/**
+ * Minimal db double recording update() set-values. `select()` chains return the
+ * preloaded `selectQueue` shift()ed per call so different statements get
+ * different rows (used by geocodeUngeocodedClients: count, then rows).
+ */
+function fakeDb(selectQueue: unknown[][]) {
+  const updates: Record<string, unknown>[] = [];
+  const queue = [...selectQueue];
+  const chain = () => {
+    const rows = queue.shift() ?? [];
+    const proxy: Record<string, unknown> = {};
+    for (const k of ["from", "where", "orderBy", "limit"]) {
+      proxy[k] = () => proxy;
+    }
+    // Make the chain awaitable / iterable as the resolved rows.
+    (proxy as { then: unknown }).then = (resolve: (v: unknown) => void) =>
+      resolve(rows);
+    (proxy as { [Symbol.iterator]: unknown })[Symbol.iterator] = () =>
+      (rows as unknown[])[Symbol.iterator]();
+    return proxy;
+  };
+  const db = {
+    select: () => chain(),
+    update: () => ({
+      set: (vals: Record<string, unknown>) => ({
+        where: () => {
+          updates.push(vals);
+          return { returning: async () => [] };
+        },
+      }),
+    }),
+    updates,
+  };
+  return db as unknown as Parameters<typeof geocodeClient>[0] & {
+    updates: Record<string, unknown>[];
+  };
+}
+
+const clientRow = (over: Record<string, unknown> = {}) =>
+  ({
+    id: "client-1",
+    name: "Alice",
+    email: "a@example.com",
+    address: "1 Main St",
+    latitude: null,
+    longitude: null,
+    geocodedAt: null,
+    ...over,
+  }) as unknown as Parameters<typeof geocodeClient>[1];
+
+// ─── geocodeClient ────────────────────────────────────────────────────────────
+
+describe("geocodeClient", () => {
+  it("persists coordinates and returns a geocoded outcome", async () => {
+    const db = fakeDb([]);
+    const provider = fakeProvider(async () => okResult(40.1, -74.2));
+    const outcome = await geocodeClient(db, clientRow(), provider);
+
+    expect(outcome.status).toBe("geocoded");
+    expect(outcome.latitude).toBe(40.1);
+    expect(outcome.longitude).toBe(-74.2);
+    expect(outcome.geocodedAt).toBeTruthy();
+    expect(db.updates).toHaveLength(1);
+    expect(db.updates[0]!.latitude).toBe(40.1);
+    expect(db.updates[0]!.longitude).toBe(-74.2);
+    expect(db.updates[0]!.geocodedAt).toBeInstanceOf(Date);
+  });
+
+  it("returns no_address and does not persist when address is blank", async () => {
+    const db = fakeDb([]);
+    const provider = fakeProvider(async () => okResult(0, 0));
+    const outcome = await geocodeClient(db, clientRow({ address: "   " }), provider);
+
+    expect(outcome.status).toBe("no_address");
+    expect(provider.calls).toHaveLength(0);
+    expect(db.updates).toHaveLength(0);
+  });
+
+  it("returns unresolved when the provider finds no match", async () => {
+    const db = fakeDb([]);
+    const provider = fakeProvider(async () => null);
+    const outcome = await geocodeClient(db, clientRow(), provider);
+
+    expect(outcome.status).toBe("unresolved");
+    expect(outcome.message).toMatch(/could not be resolved/i);
+    expect(db.updates).toHaveLength(0);
+  });
+
+  it("returns error (without throwing) when the provider fails", async () => {
+    const db = fakeDb([]);
+    const provider = fakeProvider(async () => {
+      throw new Error("quota exceeded");
+    });
+    const outcome = await geocodeClient(db, clientRow(), provider);
+
+    expect(outcome.status).toBe("error");
+    expect(outcome.message).toMatch(/quota exceeded/);
+    expect(db.updates).toHaveLength(0);
+  });
+});
+
+// ─── geocodeUngeocodedClients ─────────────────────────────────────────────────
+
+describe("geocodeUngeocodedClients", () => {
+  it("geocodes candidates, tallies outcomes, and reports remaining", async () => {
+    // First select() = count query, second select() = candidate rows.
+    const db = fakeDb([
+      [{ count: 5 }],
+      [
+        clientRow({ id: "c1", address: "1 Main St" }),
+        clientRow({ id: "c2", address: "2 Oak Ave" }),
+        clientRow({ id: "c3", address: "" }), // no_address
+      ],
+    ]);
+    const provider = fakeProvider(async (addr) =>
+      addr === "2 Oak Ave" ? null : okResult(1, 2)
+    );
+
+    const summary = await geocodeUngeocodedClients(db, 50, provider);
+
+    expect(summary.processed).toBe(3);
+    expect(summary.geocoded).toBe(1);
+    expect(summary.unresolved).toBe(1); // "2 Oak Ave"
+    expect(summary.remaining).toBe(2); // 5 total - 3 processed
+    expect(summary.provider).toBe("nominatim");
+    expect(db.updates).toHaveLength(1); // only the successful one persisted
+  });
+
+  it("clamps the limit to the 1..500 range", async () => {
+    const db = fakeDb([[{ count: 0 }], []]);
+    const provider = fakeProvider(async () => okResult(1, 2));
+    const summary = await geocodeUngeocodedClients(db, 0, provider);
+    expect(summary.processed).toBe(0);
+    expect(summary.remaining).toBe(0);
+  });
+});
+
+// ─── resolveClientGeocodingProvider ───────────────────────────────────────────
+
+describe("resolveClientGeocodingProvider", () => {
+  it("defaults to Nominatim when no settings row exists", async () => {
+    const db = fakeDb([[]]); // businessSettings select -> empty
+    const provider = await resolveClientGeocodingProvider(db);
+    expect(provider).toBeInstanceOf(NominatimGeocodingProvider);
+    expect(provider.name).toBe("nominatim");
+  });
+
+  it("defaults to Nominatim when provider is unset on settings", async () => {
+    const db = fakeDb([[{ routeOptimizationProvider: null, googleMapsApiKey: null }]]);
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const provider = await resolveClientGeocodingProvider(db);
+    expect(provider.name).toBe("nominatim");
+    warn.mockRestore();
+  });
+});

src/__tests__/geocoding.test.ts

@@ -0,0 +1,313 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import {
+  NominatimGeocodingProvider,
+  GoogleGeocodingProvider,
+  resolveGeocodingProvider,
+  geocodeBatch,
+  type FetchLike,
+} from "../services/geocoding.js";
+
+/** Builds a fake fetch returning a single JSON body, recording the called URLs. */
+function fakeFetch(
+  body: unknown,
+  init: { ok?: boolean; status?: number; statusText?: string } = {}
+): { fetchImpl: FetchLike; calls: string[] } {
+  const calls: string[] = [];
+  const fetchImpl: FetchLike = async (url) => {
+    calls.push(url);
+    return {
+      ok: init.ok ?? true,
+      status: init.status ?? 200,
+      statusText: init.statusText ?? "OK",
+      json: async () => body,
+    };
+  };
+  return { fetchImpl, calls };
+}
+
+/** Virtual clock whose `sleep` advances `now`, so throttle timing is deterministic. */
+function fakeClock() {
+  const state = { t: 0 };
+  const sleeps: number[] = [];
+  return {
+    now: () => state.t,
+    sleep: async (ms: number) => {
+      sleeps.push(ms);
+      state.t += ms;
+    },
+    sleeps,
+  };
+}
+
+const NOMINATIM_ROW = {
+  lat: "40.7128",
+  lon: "-74.0060",
+  display_name: "New York, NY, USA",
+};
+
+describe("NominatimGeocodingProvider", () => {
+  it("parses the top match into a GeocodeResult", async () => {
+    const { fetchImpl, calls } = fakeFetch([NOMINATIM_ROW]);
+    const provider = new NominatimGeocodingProvider({ fetchImpl });
+
+    const result = await provider.geocode("123 Main St");
+
+    expect(result).toEqual({
+      latitude: 40.7128,
+      longitude: -74.006,
+      formattedAddress: "New York, NY, USA",
+      provider: "nominatim",
+    });
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toContain("/search");
+    expect(calls[0]).toContain("q=123+Main+St");
+    expect(calls[0]).toContain("format=jsonv2");
+    expect(calls[0]).toContain("limit=1");
+  });
+
+  it("returns null for an empty result set", async () => {
+    const { fetchImpl } = fakeFetch([]);
+    const provider = new NominatimGeocodingProvider({ fetchImpl });
+    expect(await provider.geocode("nowhere at all")).toBeNull();
+  });
+
+  it("returns null for a blank address without calling fetch", async () => {
+    const { fetchImpl, calls } = fakeFetch([NOMINATIM_ROW]);
+    const provider = new NominatimGeocodingProvider({ fetchImpl });
+    expect(await provider.geocode("   ")).toBeNull();
+    expect(calls).toHaveLength(0);
+  });
+
+  it("throws on a non-OK HTTP response", async () => {
+    const { fetchImpl } = fakeFetch("rate limited", {
+      ok: false,
+      status: 429,
+      statusText: "Too Many Requests",
+    });
+    const provider = new NominatimGeocodingProvider({ fetchImpl });
+    await expect(provider.geocode("123 Main St")).rejects.toThrow(
+      /Nominatim geocoding failed: 429/
+    );
+  });
+
+  it("sends the configured User-Agent and honors a custom base URL", async () => {
+    const calls: Array<{ url: string; headers?: Record<string, string> }> = [];
+    const fetchImpl: FetchLike = async (url, opts) => {
+      calls.push({ url, headers: opts?.headers });
+      return { ok: true, status: 200, statusText: "OK", json: async () => [NOMINATIM_ROW] };
+    };
+    const provider = new NominatimGeocodingProvider({
+      fetchImpl,
+      baseUrl: "https://nominatim.example.com/",
+      userAgent: "TestAgent/9.9",
+    });
+
+    await provider.geocode("123 Main St");
+
+    expect(calls[0]!.url).toContain("https://nominatim.example.com/search");
+    expect(calls[0]!.headers?.["User-Agent"]).toBe("TestAgent/9.9");
+  });
+
+  it("throttles to ~1 req/sec across consecutive calls (first call not delayed)", async () => {
+    const clock = fakeClock();
+    const { fetchImpl } = fakeFetch([NOMINATIM_ROW]);
+    const provider = new NominatimGeocodingProvider({
+      fetchImpl,
+      minRequestIntervalMs: 1000,
+      now: clock.now,
+      sleep: clock.sleep,
+    });
+
+    await provider.geocode("a");
+    await provider.geocode("b");
+    await provider.geocode("c");
+
+    // First request immediate; each subsequent waits the full interval.
+    expect(clock.sleeps).toEqual([1000, 1000]);
+  });
+});
+
+describe("GoogleGeocodingProvider", () => {
+  const GOOGLE_OK = {
+    status: "OK",
+    results: [
+      {
+        formatted_address: "1600 Amphitheatre Pkwy, Mountain View, CA",
+        geometry: { location: { lat: 37.4224, lng: -122.0842 } },
+      },
+    ],
+  };
+
+  it("parses the first result into a GeocodeResult", async () => {
+    const { fetchImpl, calls } = fakeFetch(GOOGLE_OK);
+    const provider = new GoogleGeocodingProvider("test-key", { fetchImpl });
+
+    const result = await provider.geocode("1600 Amphitheatre Pkwy");
+
+    expect(result).toEqual({
+      latitude: 37.4224,
+      longitude: -122.0842,
+      formattedAddress: "1600 Amphitheatre Pkwy, Mountain View, CA",
+      provider: "google",
+    });
+    expect(calls[0]).toContain("key=test-key");
+    expect(calls[0]).toContain("address=1600+Amphitheatre+Pkwy");
+  });
+
+  it("returns null on ZERO_RESULTS", async () => {
+    const { fetchImpl } = fakeFetch({ status: "ZERO_RESULTS", results: [] });
+    const provider = new GoogleGeocodingProvider("test-key", { fetchImpl });
+    expect(await provider.geocode("nowhere")).toBeNull();
+  });
+
+  it("throws on an API error status with the error message", async () => {
+    const { fetchImpl } = fakeFetch({
+      status: "REQUEST_DENIED",
+      error_message: "The provided API key is invalid.",
+    });
+    const provider = new GoogleGeocodingProvider("bad-key", { fetchImpl });
+    await expect(provider.geocode("123 Main St")).rejects.toThrow(
+      /Google geocoding error: REQUEST_DENIED: The provided API key is invalid\./
+    );
+  });
+
+  it("returns null for a blank address without calling fetch", async () => {
+    const { fetchImpl, calls } = fakeFetch(GOOGLE_OK);
+    const provider = new GoogleGeocodingProvider("test-key", { fetchImpl });
+    expect(await provider.geocode("")).toBeNull();
+    expect(calls).toHaveLength(0);
+  });
+
+  it("rejects construction with an empty API key", () => {
+    expect(() => new GoogleGeocodingProvider("")).toThrow(/non-empty API key/);
+  });
+});
+
+describe("resolveGeocodingProvider", () => {
+  const originalEnv = process.env.GOOGLE_MAPS_API_KEY;
+  afterEach(() => {
+    if (originalEnv === undefined) delete process.env.GOOGLE_MAPS_API_KEY;
+    else process.env.GOOGLE_MAPS_API_KEY = originalEnv;
+  });
+
+  it("defaults to Nominatim when provider is unset", () => {
+    const provider = resolveGeocodingProvider(null);
+    expect(provider.name).toBe("nominatim");
+  });
+
+  it("returns Nominatim for an explicit nominatim setting", () => {
+    const provider = resolveGeocodingProvider({
+      routeOptimizationProvider: "nominatim",
+    });
+    expect(provider.name).toBe("nominatim");
+  });
+
+  it("returns Google and decrypts the stored key when provider is google", () => {
+    const decrypt = vi.fn().mockReturnValue("decrypted-google-key");
+    const provider = resolveGeocodingProvider(
+      { routeOptimizationProvider: "google", googleMapsApiKey: "enc:abc" },
+      { decrypt }
+    );
+    expect(provider.name).toBe("google");
+    expect(decrypt).toHaveBeenCalledWith("enc:abc");
+  });
+
+  it("falls back to Nominatim (with a warning) when google has no usable key", () => {
+    delete process.env.GOOGLE_MAPS_API_KEY;
+    const warn = vi.fn();
+    const provider = resolveGeocodingProvider(
+      { routeOptimizationProvider: "google", googleMapsApiKey: null },
+      { warn }
+    );
+    expect(provider.name).toBe("nominatim");
+    expect(warn).toHaveBeenCalledOnce();
+  });
+
+  it("falls back to Nominatim (with a warning) when decryption fails", () => {
+    const decrypt = vi.fn().mockImplementation(() => {
+      throw new Error("bad ciphertext");
+    });
+    const warn = vi.fn();
+    delete process.env.GOOGLE_MAPS_API_KEY;
+    const provider = resolveGeocodingProvider(
+      { routeOptimizationProvider: "google", googleMapsApiKey: "enc:corrupt" },
+      { decrypt, warn }
+    );
+    expect(provider.name).toBe("nominatim");
+    expect(warn).toHaveBeenCalled();
+  });
+
+  it("uses GOOGLE_MAPS_API_KEY env var as a fallback key source", () => {
+    process.env.GOOGLE_MAPS_API_KEY = "env-key";
+    const provider = resolveGeocodingProvider({
+      routeOptimizationProvider: "google",
+    });
+    expect(provider.name).toBe("google");
+  });
+});
+
+describe("geocodeBatch", () => {
+  it("geocodes items in order and preserves keys", async () => {
+    const { fetchImpl } = fakeFetch([NOMINATIM_ROW]);
+    const provider = new NominatimGeocodingProvider({
+      fetchImpl,
+      minRequestIntervalMs: 0,
+    });
+
+    const outcomes = await geocodeBatch(
+      [
+        { key: "c1", address: "123 Main St" },
+        { key: "c2", address: "456 Oak Ave" },
+      ],
+      provider
+    );
+
+    expect(outcomes.map((o) => o.key)).toEqual(["c1", "c2"]);
+    expect(outcomes[0]!.result?.latitude).toBe(40.7128);
+    expect(outcomes[1]!.error).toBeUndefined();
+  });
+
+  it("captures per-item errors and continues the batch", async () => {
+    let call = 0;
+    const fetchImpl: FetchLike = async () => {
+      call += 1;
+      if (call === 1) {
+        return { ok: false, status: 500, statusText: "Server Error", json: async () => "" };
+      }
+      return { ok: true, status: 200, statusText: "OK", json: async () => [NOMINATIM_ROW] };
+    };
+    const provider = new NominatimGeocodingProvider({ fetchImpl, minRequestIntervalMs: 0 });
+
+    const outcomes = await geocodeBatch(
+      [
+        { key: 1, address: "bad" },
+        { key: 2, address: "good" },
+      ],
+      provider
+    );
+
+    expect(outcomes[0]!.result).toBeNull();
+    expect(outcomes[0]!.error).toMatch(/500/);
+    expect(outcomes[1]!.result?.latitude).toBe(40.7128);
+  });
+
+  it("reports progress for each completed item", async () => {
+    const { fetchImpl } = fakeFetch([NOMINATIM_ROW]);
+    const provider = new NominatimGeocodingProvider({ fetchImpl, minRequestIntervalMs: 0 });
+    const progress: Array<[number, number]> = [];
+
+    await geocodeBatch(
+      [
+        { key: "a", address: "1 St" },
+        { key: "b", address: "2 St" },
+      ],
+      provider,
+      { onProgress: (completed, total) => progress.push([completed, total]) }
+    );
+
+    expect(progress).toEqual([
+      [1, 2],
+      [2, 2],
+    ]);
+  });
+});

src/__tests__/petProfileSummary.test.ts

@@ -131,20 +131,6 @@ function makeAppointment(overrides: Record<string, unknown> = {}) {
   };
 }
 
-function makeService(overrides: Record<string, unknown> = {}) {
-  return {
-    id: "service-1",
-    name: "Full Groom",
-    description: null,
-    basePriceCents: 6000,
-    durationMinutes: 120,
-    active: true,
-    createdAt: new Date(),
-    updatedAt: new Date(),
-    ...overrides,
-  };
-}
-
 function makeSession(overrides: Record<string, unknown> = {}) {
   return {
     id: "sess-owner",
@@ -164,7 +150,6 @@ function makeSession(overrides: Record<string, unknown> = {}) {
 
 let petsTable: Record<string, unknown>[];
 let appointmentsTable: Record<string, unknown>[];
-let servicesTable: Record<string, unknown>[];
 let sessionsTable: Record<string, unknown>[];
 
 // selectQueue: queries resolve in FIFO order. Each .from(table) result
@@ -198,7 +183,6 @@ function enqueueThrow(table: string, message: string) {
 function resetMock() {
   petsTable = [makePet()];
   appointmentsTable = [makeAppointment()];
-  servicesTable = [makeService()];
   sessionsTable = [makeSession()];
   selectQueue = [];
   insertCapture = [];

src/__tests__/portalPets.test.ts

@@ -0,0 +1,319 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { Hono } from "hono";
+
+const CLIENT_ID = "550e8400-e29b-41d4-a716-446655440001";
+const OTHER_CLIENT_ID = "550e8400-e29b-41d4-a716-446655440099";
+const PET_ID = "880e8400-e29b-41d4-a716-446655440004";
+const SESSION_ID = "770e8400-e29b-41d4-a716-446655440003";
+
+const futureDate = () => new Date(Date.now() + 30 * 60 * 1000);
+
+const ACTIVE_SESSION = {
+  id: SESSION_ID,
+  clientId: CLIENT_ID,
+  status: "active" as const,
+  expiresAt: futureDate(),
+  createdAt: new Date(),
+};
+
+// A persisted pet owned by CLIENT_ID. weightKg is a string because the column is
+// numeric (Drizzle serialises numeric to string).
+const PET = {
+  id: PET_ID,
+  clientId: CLIENT_ID,
+  name: "Rex",
+  species: "dog",
+  breed: "Labrador",
+  weightKg: "12.50",
+  dateOfBirth: null,
+  healthAlerts: null,
+  groomingNotes: null,
+  coatType: null,
+  petSizeCategory: null,
+  preferredCuts: [],
+  medicalAlerts: [],
+  photoKey: null,
+};
+
+let selectSessionRow: Record<string, unknown> | null = null;
+let selectPetRow: Record<string, unknown> | null = null;
+let updatedValues: Record<string, unknown>[] = [];
+
+function resetMock() {
+  selectSessionRow = null;
+  selectPetRow = null;
+  updatedValues = [];
+}
+
+vi.mock("@groombook/db", () => {
+  function makeChainable(data: unknown[]): unknown {
+    const arr = [...data];
+    const chain = new Proxy(arr, {
+      get(target, prop) {
+        if (prop === "where" || prop === "orderBy" || prop === "limit") {
+          return () => chain;
+        }
+        // @ts-expect-error proxy
+        return target[prop];
+      },
+    });
+    return chain;
+  }
+
+  function tableProxy(name: string) {
+    return new Proxy(
+      { _name: name },
+      { get: (t, p) => (p === "_name" ? name : { table: name, column: p }) }
+    );
+  }
+
+  const impersonationSessions = tableProxy("impersonationSessions");
+  const pets = tableProxy("pets");
+
+  return {
+    getDb: () => ({
+      select: () => ({
+        from: (table: { _name: string }) => {
+          if (table._name === "impersonationSessions") {
+            return makeChainable(selectSessionRow ? [selectSessionRow] : []);
+          }
+          if (table._name === "pets") {
+            return makeChainable(selectPetRow ? [selectPetRow] : []);
+          }
+          return makeChainable([]);
+        },
+      }),
+      update: () => ({
+        set: (vals: Record<string, unknown>) => ({
+          where: () => ({
+            returning: () => {
+              if (selectPetRow) {
+                updatedValues.push(vals);
+                return [{ ...selectPetRow, ...vals }];
+              }
+              return [];
+            },
+          }),
+        }),
+      }),
+      // portalAudit inserts an audit row after the handler; make it a no-op so
+      // the middleware does not log a swallowed error during tests.
+      insert: () => ({ values: () => ({ returning: () => [] }) }),
+    }),
+    impersonationSessions,
+    pets,
+    // Other tables imported by the portal router but unused in these tests.
+    appointments: tableProxy("appointments"),
+    waitlistEntries: tableProxy("waitlistEntries"),
+    clients: tableProxy("clients"),
+    services: tableProxy("services"),
+    staff: tableProxy("staff"),
+    invoices: tableProxy("invoices"),
+    invoiceLineItems: tableProxy("invoiceLineItems"),
+    impersonationAuditLogs: tableProxy("impersonationAuditLogs"),
+    eq: vi.fn(),
+    and: vi.fn(),
+    inArray: vi.fn(),
+  };
+});
+
+const { portalRouter } = await import("../routes/portal.js");
+
+const app = new Hono();
+app.route("/portal", portalRouter);
+
+function jsonPatch(path: string, body: unknown, headers?: Record<string, string>) {
+  return app.request(path, {
+    method: "PATCH",
+    headers: {
+      "Content-Type": "application/json",
+      ...headers,
+    },
+    body: JSON.stringify(body),
+  });
+}
+
+beforeEach(() => resetMock());
+
+describe("PATCH /portal/pets/:petId", () => {
+  it("updates an owned pet and persists the mapped columns (200)", async () => {
+    selectSessionRow = ACTIVE_SESSION;
+    selectPetRow = PET;
+
+    // Mirrors the groombook/web PetForm payload: it spreads the GET-shaped pet
+    // (weight, notes, birthDate, photoUrl) and adds the form's edited keys
+    // (weightKg, healthAlerts, coatType, …). "xlarge" must map to "extra_large".
+    const res = await jsonPatch(
+      `/portal/pets/${PET_ID}`,
+      {
+        id: PET_ID,
+        name: "Rex Updated",
+        breed: "Golden Retriever",
+        weight: "12.50",
+        weightKg: 18.25,
+        notes: "old grooming notes",
+        healthAlerts: "Allergic to oatmeal shampoo",
+        photoUrl: "pets/rex.jpg",
+        coatType: "double",
+        petSizeCategory: "xlarge",
+        preferredCuts: ["teddy bear", "puppy cut"],
+        medicalAlerts: [
+          { id: "a1", type: "allergy", description: "oatmeal", severity: "medium" },
+        ],
+      },
+      { "X-Impersonation-Session-Id": SESSION_ID }
+    );
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.name).toBe("Rex Updated");
+    expect(body.petSizeCategory).toBe("extra_large");
+    expect(body.coatType).toBe("double");
+
+    const persisted = updatedValues[0]!;
+    expect(persisted.name).toBe("Rex Updated");
+    expect(persisted.breed).toBe("Golden Retriever");
+    // weightKg (form key) wins over weight (GET key) and is stored as a string.
+    expect(persisted.weightKg).toBe("18.25");
+    expect(persisted.groomingNotes).toBe("old grooming notes");
+    expect(persisted.healthAlerts).toBe("Allergic to oatmeal shampoo");
+    // photoKey is NOT writable via portal PATCH (GRO-2187 S3 key-hijack fix):
+    // the web form round-trips the GET-shaped photoUrl, but the server must not
+    // persist it. Photo changes go through the key-validated upload flow.
+    expect(persisted.photoKey).toBeUndefined();
+    expect(persisted.coatType).toBe("double");
+    expect(persisted.petSizeCategory).toBe("extra_large");
+    expect(persisted.preferredCuts).toEqual(["teddy bear", "puppy cut"]);
+    expect(persisted.medicalAlerts).toEqual([
+      { id: "a1", type: "allergy", description: "oatmeal", severity: "medium" },
+    ]);
+    expect(persisted.updatedAt).toBeInstanceOf(Date);
+  });
+
+  // GRO-2187 security regression: a portal customer must not be able to set the
+  // S3 object key. photoKey is consumed server-side by getPresignedGetUrl /
+  // deleteObject; the upload path guards keys with a pets/{petId}/ prefix, and the
+  // portal PATCH must not offer a bypass. A foreign/arbitrary photoUrl is accepted
+  // (Zod strips the unknown key) but must leave photoKey untouched.
+  it("does not mutate photoKey when a foreign photoUrl is supplied (200)", async () => {
+    selectSessionRow = ACTIVE_SESSION;
+    const ownKey = `pets/${PET_ID}/original.jpg`;
+    selectPetRow = { ...PET, photoKey: ownKey };
+
+    const res = await jsonPatch(
+      `/portal/pets/${PET_ID}`,
+      {
+        name: "Rex",
+        // attacker-chosen key pointing at another tenant's object
+        photoUrl: "pets/00000000-0000-0000-0000-0000000000ff/victim-secret.jpg",
+      },
+      { "X-Impersonation-Session-Id": SESSION_ID }
+    );
+
+    expect(res.status).toBe(200);
+    const persisted = updatedValues[0]!;
+    // The attacker-supplied key never reaches the update payload.
+    expect(persisted.photoKey).toBeUndefined();
+    // And the stored key is unchanged from the pet's own value.
+    const body = await res.json();
+    expect(body.photoUrl).toBe(ownKey);
+  });
+
+  // The length/array caps live in the Zod schema, so violations are rejected by
+  // zValidator with 400 (in-handler enum checks are what return 422).
+  it("returns 400 when a medicalAlert description exceeds the length cap", async () => {
+    selectSessionRow = ACTIVE_SESSION;
+    selectPetRow = PET;
+
+    const res = await jsonPatch(
+      `/portal/pets/${PET_ID}`,
+      {
+        medicalAlerts: [
+          { type: "allergy", description: "x".repeat(2001), severity: "low" },
+        ],
+      },
+      { "X-Impersonation-Session-Id": SESSION_ID }
+    );
+
+    expect(res.status).toBe(400);
+    expect(updatedValues).toHaveLength(0);
+  });
+
+  it("falls back to the weight key when weightKg is absent", async () => {
+    selectSessionRow = ACTIVE_SESSION;
+    selectPetRow = PET;
+
+    const res = await jsonPatch(
+      `/portal/pets/${PET_ID}`,
+      { weight: "9.75" },
+      { "X-Impersonation-Session-Id": SESSION_ID }
+    );
+
+    expect(res.status).toBe(200);
+    expect(updatedValues[0]!.weightKg).toBe("9.75");
+  });
+
+  it("returns 403 when the pet belongs to a different client", async () => {
+    selectSessionRow = ACTIVE_SESSION;
+    selectPetRow = { ...PET, clientId: OTHER_CLIENT_ID };
+
+    const res = await jsonPatch(
+      `/portal/pets/${PET_ID}`,
+      { name: "Hacker" },
+      { "X-Impersonation-Session-Id": SESSION_ID }
+    );
+
+    expect(res.status).toBe(403);
+    expect(updatedValues).toHaveLength(0);
+  });
+
+  it("returns 404 when the pet does not exist", async () => {
+    selectSessionRow = ACTIVE_SESSION;
+    selectPetRow = null;
+
+    const res = await jsonPatch(
+      `/portal/pets/${PET_ID}`,
+      { name: "Ghost" },
+      { "X-Impersonation-Session-Id": SESSION_ID }
+    );
+
+    expect(res.status).toBe(404);
+  });
+
+  it("returns 422 for an invalid coatType", async () => {
+    selectSessionRow = ACTIVE_SESSION;
+    selectPetRow = PET;
+
+    const res = await jsonPatch(
+      `/portal/pets/${PET_ID}`,
+      { coatType: "fluffy" },
+      { "X-Impersonation-Session-Id": SESSION_ID }
+    );
+
+    expect(res.status).toBe(422);
+    expect(updatedValues).toHaveLength(0);
+  });
+
+  it("returns 422 for an invalid petSizeCategory", async () => {
+    selectSessionRow = ACTIVE_SESSION;
+    selectPetRow = PET;
+
+    const res = await jsonPatch(
+      `/portal/pets/${PET_ID}`,
+      { petSizeCategory: "gigantic" },
+      { "X-Impersonation-Session-Id": SESSION_ID }
+    );
+
+    expect(res.status).toBe(422);
+    expect(updatedValues).toHaveLength(0);
+  });
+
+  it("returns 401 without an impersonation session header", async () => {
+    selectSessionRow = ACTIVE_SESSION;
+    selectPetRow = PET;
+
+    const res = await jsonPatch(`/portal/pets/${PET_ID}`, { name: "NoAuth" });
+
+    expect(res.status).toBe(401);
+  });
+});

src/__tests__/routeOptimization.test.ts

@@ -0,0 +1,184 @@
+import { describe, it, expect } from "vitest";
+import {
+  haversineKm,
+  estimateLeg,
+  nearestNeighborOrder,
+  optimizeRoute,
+  MAX_STOPS_PER_ROUTE,
+  type RouteStopInput,
+} from "../services/routeOptimization.js";
+import type { FetchLike } from "../services/geocoding.js";
+
+/** Builds a fake fetch returning a single JSON body, recording called URLs. */
+function fakeFetch(
+  body: unknown,
+  init: { ok?: boolean; status?: number; statusText?: string } = {}
+): { fetchImpl: FetchLike; calls: string[] } {
+  const calls: string[] = [];
+  const fetchImpl: FetchLike = async (url) => {
+    calls.push(url);
+    return {
+      ok: init.ok ?? true,
+      status: init.status ?? 200,
+      statusText: init.statusText ?? "OK",
+      json: async () => body,
+    };
+  };
+  return { fetchImpl, calls };
+}
+
+function stop(appointmentId: string, lat: number, lng: number): RouteStopInput {
+  return { appointmentId, latitude: lat, longitude: lng };
+}
+
+describe("haversineKm", () => {
+  it("is zero for the same point", () => {
+    expect(haversineKm({ latitude: 40, longitude: -74 }, { latitude: 40, longitude: -74 })).toBe(0);
+  });
+
+  it("approximates 1 degree of latitude as ~111km", () => {
+    const d = haversineKm({ latitude: 0, longitude: 0 }, { latitude: 1, longitude: 0 });
+    expect(d).toBeGreaterThan(110);
+    expect(d).toBeLessThan(112);
+  });
+});
+
+describe("estimateLeg", () => {
+  it("applies the circuity factor and average speed", () => {
+    const a = { latitude: 0, longitude: 0 };
+    const b = { latitude: 0, longitude: 1 };
+    const { distanceKm, mins } = estimateLeg(a, b);
+    // ~111km straight * 1.3 circuity ≈ 144.6km; at 40km/h ≈ 217 min
+    expect(distanceKm).toBeGreaterThan(140);
+    expect(distanceKm).toBeLessThan(150);
+    expect(mins).toBeGreaterThan(200);
+    expect(mins).toBeLessThan(230);
+    expect(Number.isInteger(mins)).toBe(true);
+  });
+});
+
+describe("nearestNeighborOrder", () => {
+  it("returns trivial order for 0 or 1 points", () => {
+    expect(nearestNeighborOrder([])).toEqual([]);
+    expect(nearestNeighborOrder([{ latitude: 1, longitude: 1 }])).toEqual([0]);
+  });
+
+  it("greedily visits the nearest unvisited point", () => {
+    // Points on a line; scrambled input order.
+    const points = [
+      { latitude: 0, longitude: 0 }, // 0 (start)
+      { latitude: 0, longitude: 5 }, // 1 (far)
+      { latitude: 0, longitude: 1 }, // 2
+      { latitude: 0, longitude: 2 }, // 3
+    ];
+    expect(nearestNeighborOrder(points, 0)).toEqual([0, 2, 3, 1]);
+  });
+});
+
+describe("optimizeRoute — nearest-neighbor fallback (no API key)", () => {
+  it("returns an empty route for no stops", async () => {
+    const r = await optimizeRoute([]);
+    expect(r.stops).toHaveLength(0);
+    expect(r.totalTravelMins).toBe(0);
+    expect(r.totalDistanceKm).toBe(0);
+    expect(r.provider).toBe("nearest_neighbor");
+    expect(r.chunked).toBe(false);
+  });
+
+  it("handles a single stop with null travel-from-prev", async () => {
+    const r = await optimizeRoute([stop("a", 40, -74)]);
+    expect(r.stops).toHaveLength(1);
+    expect(r.stops[0]!.travelMinsFromPrev).toBeNull();
+    expect(r.stops[0]!.travelDistanceKmFromPrev).toBeNull();
+    expect(r.totalTravelMins).toBe(0);
+  });
+
+  it("orders multiple stops greedily and sums totals", async () => {
+    const stops = [
+      stop("start", 0, 0),
+      stop("far", 0, 5),
+      stop("near1", 0, 1),
+      stop("near2", 0, 2),
+    ];
+    const r = await optimizeRoute(stops);
+    expect(r.provider).toBe("nearest_neighbor");
+    expect(r.stops.map((s) => s.appointmentId)).toEqual([
+      "start",
+      "near1",
+      "near2",
+      "far",
+    ]);
+    // First stop has no inbound leg.
+    expect(r.stops[0]!.travelMinsFromPrev).toBeNull();
+    // Remaining stops have positive travel.
+    for (const s of r.stops.slice(1)) {
+      expect(s.travelMinsFromPrev!).toBeGreaterThan(0);
+      expect(s.travelDistanceKmFromPrev!).toBeGreaterThan(0);
+    }
+    const summed = r.stops.reduce((acc, s) => acc + (s.travelMinsFromPrev ?? 0), 0);
+    expect(r.totalTravelMins).toBe(summed);
+  });
+});
+
+describe("optimizeRoute — Google Directions path", () => {
+  it("uses optimized waypoint order and real leg metrics, dropping the return leg", async () => {
+    const stops = [stop("A", 0, 0), stop("B", 0, 1), stop("C", 0, 2)];
+    // waypoints = [B, C]; optimizer reorders them to [C, B] (waypoint_order [1,0]).
+    // legs: A->C, C->B, B->A(return). The return leg must be dropped.
+    const { fetchImpl, calls } = fakeFetch({
+      status: "OK",
+      routes: [
+        {
+          waypoint_order: [1, 0],
+          legs: [
+            { distance: { value: 2000 }, duration: { value: 600 } }, // A->C
+            { distance: { value: 1000 }, duration: { value: 300 } }, // C->B
+            { distance: { value: 3000 }, duration: { value: 900 } }, // B->A (return, dropped)
+          ],
+        },
+      ],
+    });
+
+    const r = await optimizeRoute(stops, { googleApiKey: "key", fetchImpl });
+    expect(r.provider).toBe("google");
+    expect(r.stops.map((s) => s.appointmentId)).toEqual(["A", "C", "B"]);
+    expect(r.stops[0]!.travelMinsFromPrev).toBeNull();
+    expect(r.stops[1]!.travelDistanceKmFromPrev).toBe(2); // 2000m -> 2km
+    expect(r.stops[1]!.travelMinsFromPrev).toBe(10); // 600s -> 10min
+    expect(r.stops[2]!.travelDistanceKmFromPrev).toBe(1); // 1000m
+    expect(r.stops[2]!.travelMinsFromPrev).toBe(5); // 300s
+    expect(r.totalDistanceKm).toBe(3);
+    expect(r.totalTravelMins).toBe(15);
+    expect(decodeURIComponent(calls[0]!)).toContain("optimize:true");
+  });
+
+  it("falls back to the heuristic when Google returns a non-OK status", async () => {
+    const stops = [stop("A", 0, 0), stop("B", 0, 1), stop("C", 0, 2)];
+    const { fetchImpl } = fakeFetch({ status: "REQUEST_DENIED", error_message: "bad key" });
+    const r = await optimizeRoute(stops, { googleApiKey: "key", fetchImpl });
+    // Provider label reflects the chosen strategy (google requested) but a
+    // warning records the degradation and stops are still ordered.
+    expect(r.stops).toHaveLength(3);
+    expect(r.warnings.some((w) => w.includes("offline heuristic"))).toBe(true);
+    expect(r.stops[0]!.travelMinsFromPrev).toBeNull();
+  });
+});
+
+describe("optimizeRoute — >25 stop chunking", () => {
+  it("splits into sub-routes with a warning and continuous stop ordering", async () => {
+    const stops: RouteStopInput[] = [];
+    for (let i = 0; i < MAX_STOPS_PER_ROUTE + 5; i++) {
+      stops.push(stop(`s${i}`, 0, i * 0.1));
+    }
+    const r = await optimizeRoute(stops);
+    expect(r.chunked).toBe(true);
+    expect(r.subRouteCount).toBe(2);
+    expect(r.warnings.some((w) => w.includes("sub-routes"))).toBe(true);
+    expect(r.stops).toHaveLength(MAX_STOPS_PER_ROUTE + 5);
+    // Only the very first stop of the whole route lacks an inbound leg.
+    expect(r.stops[0]!.travelMinsFromPrev).toBeNull();
+    expect(r.stops.slice(1).every((s) => s.travelMinsFromPrev !== null)).toBe(true);
+    // All appointment ids preserved exactly once.
+    expect(new Set(r.stops.map((s) => s.appointmentId)).size).toBe(stops.length);
+  });
+});

src/index.ts

@@ -20,6 +20,7 @@ import { settingsRouter } from "./routes/settings.js";
 import { authProviderRouter } from "./routes/authProvider.js";
 import { searchRouter } from "./routes/search.js";
 import { bufferRulesRouter } from "./routes/buffer-rules.js";
+import { routesRouter } from "./routes/routes.js";
 import { getObject } from "./lib/s3.js";
 import { calendarRouter } from "./routes/calendar.js";
 import { setupRouter } from "./routes/setup.js";
@@ -220,6 +221,10 @@ api.use("/reports/*", requireRole("manager"));
 api.use("/invoices/*", requireRole("manager", "groomer"));
 api.use("/impersonation/*", requireRole("manager"));
 
+// Route optimization: manager (any groomer's route) or groomer (own route only,
+// enforced in-handler). Receptionists have no access. (GRO-2155)
+api.use("/routes/*", requireRole("manager", "groomer"));
+
 // Manager + Receptionist only (groomers have no access): appointment-groups, grooming-logs, waitlist
 api.use("/appointment-groups/*", requireRole("manager", "receptionist"));
 api.use("/grooming-logs/*", requireRole("manager", "receptionist"));
@@ -235,6 +240,15 @@ api.on(
   requireRole("manager", "receptionist", "groomer")
 );
 
+// Route-optimization geocoding endpoints are manager-only (GRO-2154), stricter
+// than the general client write guard below. Registered FIRST so receptionists
+// are rejected here before the manager+receptionist guard can admit them.
+api.on(
+  ["POST"],
+  ["/clients/geocode-batch", "/clients/:clientId/geocode"],
+  requireRole("manager")
+);
+
 // Clients, appointments: all roles may read; only manager + receptionist may write
 api.on(
   ["POST", "PUT", "PATCH", "DELETE"],
@@ -274,6 +288,7 @@ api.route("/admin/auth-provider", authProviderRouter);
 api.route("/admin/seed", adminSeedRouter);
 api.route("/search", searchRouter);
 api.route("/buffer-rules", bufferRulesRouter);
+api.route("/routes", routesRouter);
 
 const port = Number(process.env.PORT ?? 3000);
 await initAuth();

src/routes/clients.ts

@@ -3,9 +3,61 @@ import { zValidator } from "@hono/zod-validator";
 import { z } from "zod/v3";
 import { and, eq, exists, getDb, or, clients, appointments } from "@groombook/db";
 import type { AppEnv } from "../middleware/rbac.js";
+import {
+  geocodeClient,
+  geocodeUngeocodedClients,
+  resolveClientGeocodingProvider,
+  type ClientGeocodeOutcome,
+} from "../services/clientGeocoding.js";
 
 export const clientsRouter = new Hono<AppEnv>();
 
+type ClientRow = typeof clients.$inferSelect;
+
+/**
+ * Best-effort auto-geocode of a freshly created/updated client (GRO-2154).
+ * Never throws: a flaky geocoding backend must not break client mutations.
+ * Returns the (possibly coordinate-enriched) row plus a structured outcome the
+ * caller surfaces under a `geocoding` field so ambiguous addresses are visible.
+ */
+async function autoGeocodeClient(
+  db: ReturnType<typeof getDb>,
+  row: ClientRow
+): Promise<{ row: ClientRow; outcome: ClientGeocodeOutcome }> {
+  try {
+    const provider = await resolveClientGeocodingProvider(db);
+    const outcome = await geocodeClient(db, row, provider);
+    const enriched =
+      outcome.status === "geocoded"
+        ? {
+            ...row,
+            latitude: outcome.latitude,
+            longitude: outcome.longitude,
+            geocodedAt: outcome.geocodedAt
+              ? new Date(outcome.geocodedAt)
+              : row.geocodedAt,
+          }
+        : row;
+    return { row: enriched, outcome };
+  } catch (err) {
+    return {
+      row,
+      outcome: {
+        clientId: row.id,
+        status: "error",
+        message: `Auto-geocode failed: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+        latitude: null,
+        longitude: null,
+        geocodedAt: null,
+        formattedAddress: null,
+        provider: null,
+      },
+    };
+  }
+}
+
 const createClientSchema = z.object({
   name: z.string().min(1).max(200),
   email: z.string().email(),
@@ -91,9 +143,59 @@ clientsRouter.post("/", zValidator("json", createClientSchema), async (c) => {
   const db = getDb();
   const body = c.req.valid("json");
   const [row] = await db.insert(clients).values(body).returning();
+  if (!row) return c.json({ error: "Failed to create client" }, 500);
+
+  // Auto-geocode on create when an address is supplied (GRO-2154). Best-effort:
+  // the client is created regardless; the `geocoding` field surfaces failures.
+  if (body.address && body.address.trim()) {
+    const { row: enriched, outcome } = await autoGeocodeClient(db, row);
+    return c.json({ ...enriched, geocoding: outcome }, 201);
+  }
   return c.json(row, 201);
 });
 
+// Geocode a single client's address and persist coordinates (manager-only;
+// enforced by the route guard in index.ts).
+clientsRouter.post("/:clientId/geocode", async (c) => {
+  const db = getDb();
+  const clientId = c.req.param("clientId");
+  const [client] = await db
+    .select()
+    .from(clients)
+    .where(eq(clients.id, clientId));
+  if (!client) return c.json({ error: "Not found" }, 404);
+
+  const provider = await resolveClientGeocodingProvider(db);
+  const outcome = await geocodeClient(db, client, provider);
+
+  // Map outcome to an HTTP status so the result is unambiguous to the caller:
+  //  geocoded -> 200, provider error -> 502, no_address/unresolved -> 422.
+  const status =
+    outcome.status === "geocoded"
+      ? 200
+      : outcome.status === "error"
+        ? 502
+        : 422;
+  return c.json(outcome, status);
+});
+
+// Batch-geocode un-geocoded clients with provider-rate-limited throttling
+// (manager-only). Processes up to ?limit clients (default 50, max 500) per call;
+// re-invoke while `remaining` > 0 to finish large datasets.
+clientsRouter.post("/geocode-batch", async (c) => {
+  const db = getDb();
+  const limitRaw = c.req.query("limit");
+  let limit = 50;
+  if (limitRaw !== undefined) {
+    limit = Number(limitRaw);
+    if (!Number.isFinite(limit) || limit <= 0) {
+      return c.json({ error: "limit must be a positive integer" }, 400);
+    }
+  }
+  const summary = await geocodeUngeocodedClients(db, limit);
+  return c.json(summary);
+});
+
 // Update a client (including status changes)
 const patchClientSchema = createClientSchema.partial().extend({
   status: z.enum(["active", "disabled"]).optional(),
@@ -123,13 +225,29 @@ clientsRouter.patch(
     }
     delete setValues.smsOptOut;
 
-    const [row] = await db
+    // Auto-geocode on address change (GRO-2154). If the address was cleared,
+    // drop any stale coordinates so a disabled/blank address never keeps a pin.
+    const addressProvided = Object.prototype.hasOwnProperty.call(body, "address");
+    const trimmedAddress =
+      typeof body.address === "string" ? body.address.trim() : undefined;
+    if (addressProvided && !trimmedAddress) {
+      setValues.latitude = null;
+      setValues.longitude = null;
+      setValues.geocodedAt = null;
+    }
+
+    const [updated] = await db
       .update(clients)
       .set(setValues)
       .where(eq(clients.id, c.req.param("id")))
       .returning();
-    if (!row) return c.json({ error: "Not found" }, 404);
-    return c.json(row);
+    if (!updated) return c.json({ error: "Not found" }, 404);
+
+    if (addressProvided && trimmedAddress) {
+      const { row: enriched, outcome } = await autoGeocodeClient(db, updated);
+      return c.json({ ...enriched, geocoding: outcome });
+    }
+    return c.json(updated);
   }
 );
 

src/routes/portal.ts

@@ -225,9 +225,158 @@ portalRouter.get("/pets", async (c) => {
   const clientId = c.get("portalClientId");
 
   const clientPets = await db.select().from(pets).where(eq(pets.clientId, clientId));
-  return c.json(clientPets.map(p => ({ id: p.id, name: p.name, breed: p.breed, weight: p.weightKg, birthDate: p.dateOfBirth, photoUrl: p.photoKey, notes: p.groomingNotes })));
+  return c.json(clientPets.map(p => ({
+    id: p.id,
+    name: p.name,
+    breed: p.breed,
+    weight: p.weightKg,
+    birthDate: p.dateOfBirth,
+    photoUrl: p.photoKey,
+    notes: p.groomingNotes,
+    coatType: p.coatType,
+    petSizeCategory: p.petSizeCategory,
+    healthAlerts: p.healthAlerts,
+    preferredCuts: p.preferredCuts,
+    medicalAlerts: p.medicalAlerts,
+  })));
 });
 
+// ─── Customer-facing pet update ───────────────────────────────────────────────
+//
+// The customer portal pet-profile form (groombook/web) saves edits via
+// PATCH /api/portal/pets/:petId. The web payload mixes the keys returned by
+// GET /portal/pets (weight, birthDate, photoUrl, notes) with the form's own
+// edited keys (weightKg, healthAlerts, coatType, …), so we accept both spellings
+// and map each to its `pets` column. Ownership is enforced exactly like the
+// appointment-notes handler: 404 if the pet does not exist, 403 if it belongs to
+// another client.
+
+// Allowed enum values mirror packages/db/src/schema.ts coatTypeEnum /
+// petSizeCategoryEnum. Kept as plain string lists so an invalid value can be
+// rejected with 422 in-handler (zValidator failures would surface as 400).
+const PORTAL_COAT_TYPES: readonly string[] = ["short", "medium", "long", "double", "wire", "silky", "curly", "hairless"];
+const PORTAL_PET_SIZES: readonly string[] = ["small", "medium", "large", "extra_large"];
+// The web size dropdown emits "xlarge"; the DB enum value is "extra_large".
+const PORTAL_PET_SIZE_ALIASES: Record<string, string> = { xlarge: "extra_large" };
+
+const portalMedicalAlertSchema = z.object({
+  id: z.string().optional(),
+  type: z.string().max(2000),
+  description: z.string().max(2000),
+  severity: z.enum(["low", "medium", "high"]),
+});
+
+const portalPetUpdateSchema = z.object({
+  name: z.string().min(1).max(200).optional(),
+  breed: z.string().max(200).nullable().optional(),
+  // weightKg is the form's edited key; weight is the GET-shaped key. Accept both.
+  weightKg: z.union([z.number(), z.string()]).nullable().optional(),
+  weight: z.union([z.number(), z.string()]).nullable().optional(),
+  birthDate: z.string().nullable().optional(),
+  notes: z.string().max(2000).nullable().optional(),
+  healthAlerts: z.string().max(2000).nullable().optional(),
+  // photoUrl/photoKey are intentionally NOT writable here: photoKey is a trusted
+  // S3 object key consumed server-side (getPresignedGetUrl / deleteObject), and the
+  // upload path (pets.ts) already enforces a pets/{petId}/ prefix guard against key
+  // hijacking. Photo changes go through the dedicated upload + /photo/confirm flow.
+  // The web form round-trips the GET-shaped photoUrl; Zod strips it as an unknown key.
+  // coatType / petSizeCategory validated in-handler so bad values return 422.
+  coatType: z.string().nullable().optional(),
+  petSizeCategory: z.string().nullable().optional(),
+  preferredCuts: z.array(z.string().max(2000)).max(50).nullable().optional(),
+  medicalAlerts: z.array(portalMedicalAlertSchema).max(50).nullable().optional(),
+});
+
+portalRouter.patch(
+  "/pets/:petId",
+  zValidator("json", portalPetUpdateSchema),
+  async (c) => {
+    const db = getDb();
+    const petId = c.req.param("petId");
+    const body = c.req.valid("json");
+    const clientId = c.get("portalClientId");
+
+    const [pet] = await db
+      .select()
+      .from(pets)
+      .where(eq(pets.id, petId))
+      .limit(1);
+
+    if (!pet) {
+      return c.json({ error: "Not found" }, 404);
+    }
+
+    if (pet.clientId !== clientId) {
+      return c.json({ error: "Forbidden" }, 403);
+    }
+
+    const updateData: Record<string, unknown> = { updatedAt: new Date() };
+
+    if (body.name !== undefined) updateData.name = body.name;
+    if (body.breed !== undefined) updateData.breed = body.breed;
+
+    if (body.weightKg !== undefined || body.weight !== undefined) {
+      const w = body.weightKg ?? body.weight;
+      updateData.weightKg = w === null || w === undefined ? null : String(w);
+    }
+
+    if (body.birthDate !== undefined) {
+      updateData.dateOfBirth = body.birthDate ? new Date(body.birthDate) : null;
+    }
+
+    if (body.notes !== undefined) updateData.groomingNotes = body.notes;
+    if (body.healthAlerts !== undefined) updateData.healthAlerts = body.healthAlerts;
+    // photoKey is intentionally not writable here — see portalPetUpdateSchema note.
+    // Photo changes go through the key-validated upload + /photo/confirm flow.
+
+    if (body.coatType !== undefined) {
+      if (body.coatType !== null && !PORTAL_COAT_TYPES.includes(body.coatType)) {
+        return c.json({ error: "Invalid coatType" }, 422);
+      }
+      updateData.coatType = body.coatType;
+    }
+
+    if (body.petSizeCategory !== undefined) {
+      let size: string | null = body.petSizeCategory;
+      if (size !== null) {
+        size = PORTAL_PET_SIZE_ALIASES[size] ?? size;
+        if (!PORTAL_PET_SIZES.includes(size)) {
+          return c.json({ error: "Invalid petSizeCategory" }, 422);
+        }
+      }
+      updateData.petSizeCategory = size;
+    }
+
+    if (body.preferredCuts !== undefined) updateData.preferredCuts = body.preferredCuts ?? [];
+    if (body.medicalAlerts !== undefined) updateData.medicalAlerts = body.medicalAlerts ?? [];
+
+    const [updated] = await db
+      .update(pets)
+      .set(updateData)
+      .where(eq(pets.id, petId))
+      .returning();
+
+    if (!updated) {
+      return c.json({ error: "Not found" }, 404);
+    }
+
+    return c.json({
+      id: updated.id,
+      name: updated.name,
+      breed: updated.breed,
+      weight: updated.weightKg,
+      birthDate: updated.dateOfBirth,
+      photoUrl: updated.photoKey,
+      notes: updated.groomingNotes,
+      coatType: updated.coatType,
+      petSizeCategory: updated.petSizeCategory,
+      healthAlerts: updated.healthAlerts,
+      preferredCuts: updated.preferredCuts,
+      medicalAlerts: updated.medicalAlerts,
+    });
+  }
+);
+
 portalRouter.get("/invoices", async (c) => {
   const db = getDb();
   const clientId = c.get("portalClientId");

src/routes/routes.ts

@@ -0,0 +1,284 @@
+import { Hono } from "hono";
+import { zValidator } from "@hono/zod-validator";
+import { z } from "zod/v3";
+import {
+  and,
+  asc,
+  eq,
+  gte,
+  lt,
+  ne,
+  getDb,
+  appointments,
+  businessSettings,
+  clients,
+  groomerRoutes,
+  routeStops,
+} from "@groombook/db";
+import type { AppEnv, StaffRow } from "../middleware/rbac.js";
+import {
+  optimizeRoute,
+  resolveRouteGoogleApiKey,
+  type RouteStopInput,
+} from "../services/routeOptimization.js";
+
+export const routesRouter = new Hono<AppEnv>();
+
+const dailyQuerySchema = z.object({
+  staffId: z.string().uuid().optional(),
+  date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "date must be YYYY-MM-DD"),
+});
+
+const optimizeBodySchema = z.object({
+  staffId: z.string().uuid().optional(),
+  date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "date must be YYYY-MM-DD"),
+});
+
+/**
+ * Resolves the target staffId for the request and enforces the groomer-own /
+ * manager authorization rule. Groomers may only act on their own route; if a
+ * groomer omits staffId it defaults to their own. Returns either the resolved
+ * id or an error tuple the caller turns into a JSON response.
+ */
+function resolveTargetStaffId(
+  staffRow: StaffRow | undefined,
+  requestedStaffId: string | undefined
+): { staffId: string } | { error: string; status: 400 | 403 } {
+  const isGroomer = staffRow?.role === "groomer";
+
+  if (isGroomer) {
+    if (requestedStaffId && requestedStaffId !== staffRow.id) {
+      return {
+        error: "Forbidden: groomers may only access their own route",
+        status: 403,
+      };
+    }
+    return { staffId: staffRow.id };
+  }
+
+  // Manager: staffId is required (no implicit self — managers plan others' days).
+  if (!requestedStaffId) {
+    return { error: "staffId is required", status: 400 };
+  }
+  return { staffId: requestedStaffId };
+}
+
+/** Day window [date 00:00:00Z, nextDay 00:00:00Z) for filtering appointments. */
+function dayBounds(date: string): { start: Date; end: Date } {
+  const start = new Date(`${date}T00:00:00.000Z`);
+  const end = new Date(start.getTime() + 24 * 60 * 60 * 1000);
+  return { start, end };
+}
+
+/** Loads a route's persisted stops, enriched with appointment + client detail. */
+async function loadRouteStops(db: ReturnType<typeof getDb>, routeId: string) {
+  return db
+    .select({
+      id: routeStops.id,
+      appointmentId: routeStops.appointmentId,
+      stopOrder: routeStops.stopOrder,
+      latitude: routeStops.latitude,
+      longitude: routeStops.longitude,
+      travelMinsFromPrev: routeStops.travelMinsFromPrev,
+      travelDistanceKmFromPrev: routeStops.travelDistanceKmFromPrev,
+      bufferMins: routeStops.bufferMins,
+      appointmentStartTime: appointments.startTime,
+      appointmentEndTime: appointments.endTime,
+      appointmentStatus: appointments.status,
+      clientId: clients.id,
+      clientName: clients.name,
+      clientAddress: clients.address,
+    })
+    .from(routeStops)
+    .innerJoin(appointments, eq(routeStops.appointmentId, appointments.id))
+    .innerJoin(clients, eq(appointments.clientId, clients.id))
+    .where(eq(routeStops.routeId, routeId))
+    .orderBy(asc(routeStops.stopOrder));
+}
+
+/**
+ * GET /api/routes/daily?staffId=&date=
+ * Fetches (creating a draft if absent) the daily route for a groomer, with all
+ * persisted stops. Auth: groomer (own) or manager.
+ */
+routesRouter.get("/daily", zValidator("query", dailyQuerySchema), async (c) => {
+  const db = getDb();
+  const { staffId: requestedStaffId, date } = c.req.valid("query");
+
+  const resolved = resolveTargetStaffId(c.get("staff"), requestedStaffId);
+  if ("error" in resolved) {
+    return c.json({ error: resolved.error }, resolved.status);
+  }
+  const staffId = resolved.staffId;
+
+  let [route] = await db
+    .select()
+    .from(groomerRoutes)
+    .where(
+      and(
+        eq(groomerRoutes.staffId, staffId),
+        eq(groomerRoutes.routeDate, date)
+      )
+    );
+
+  if (!route) {
+    // Create a draft route so the day is addressable before optimization.
+    [route] = await db
+      .insert(groomerRoutes)
+      .values({ staffId, routeDate: date, status: "draft" })
+      .returning();
+  }
+
+  const stops = await loadRouteStops(db, route!.id);
+  return c.json({ route, stops });
+});
+
+/**
+ * POST /api/routes/optimize  { staffId, date }
+ * Generates or re-optimizes the daily route: pulls the day's geocoded
+ * appointments, optimizes the visiting order (Google Directions when a key is
+ * configured, else nearest-neighbor), and persists the ordered stops + totals.
+ * Auth: groomer (own) or manager.
+ */
+routesRouter.post(
+  "/optimize",
+  zValidator("json", optimizeBodySchema),
+  async (c) => {
+    const db = getDb();
+    const { staffId: requestedStaffId, date } = c.req.valid("json");
+
+    const resolved = resolveTargetStaffId(c.get("staff"), requestedStaffId);
+    if ("error" in resolved) {
+      return c.json({ error: resolved.error }, resolved.status);
+    }
+    const staffId = resolved.staffId;
+    const { start, end } = dayBounds(date);
+
+    // Pull the day's non-cancelled appointments for this groomer, joined to the
+    // client coordinates. Ordered by start time so the earliest booking anchors
+    // the route.
+    const dayAppointments = await db
+      .select({
+        appointmentId: appointments.id,
+        startTime: appointments.startTime,
+        clientId: clients.id,
+        clientName: clients.name,
+        latitude: clients.latitude,
+        longitude: clients.longitude,
+      })
+      .from(appointments)
+      .innerJoin(clients, eq(appointments.clientId, clients.id))
+      .where(
+        and(
+          eq(appointments.staffId, staffId),
+          gte(appointments.startTime, start),
+          lt(appointments.startTime, end),
+          ne(appointments.status, "cancelled")
+        )
+      )
+      .orderBy(asc(appointments.startTime));
+
+    const stopInputs: RouteStopInput[] = [];
+    const skipped: Array<{ appointmentId: string; clientName: string; reason: string }> =
+      [];
+    for (const appt of dayAppointments) {
+      if (appt.latitude == null || appt.longitude == null) {
+        skipped.push({
+          appointmentId: appt.appointmentId,
+          clientName: appt.clientName,
+          reason: "client address is not geocoded",
+        });
+        continue;
+      }
+      stopInputs.push({
+        appointmentId: appt.appointmentId,
+        latitude: appt.latitude,
+        longitude: appt.longitude,
+      });
+    }
+
+    const [settings] = await db.select().from(businessSettings).limit(1);
+    const bufferMins = settings?.defaultTravelBufferMins ?? 15;
+
+    const googleApiKey = await resolveRouteGoogleApiKey(db);
+    const optimized = await optimizeRoute(stopInputs, { googleApiKey });
+
+    const warnings = [...optimized.warnings];
+    if (skipped.length > 0) {
+      warnings.push(
+        `${skipped.length} appointment(s) were skipped because the client address is not geocoded.`
+      );
+    }
+
+    const now = new Date();
+    const route = await db.transaction(async (tx) => {
+      // Upsert the route row for (staffId, date).
+      const [existing] = await tx
+        .select()
+        .from(groomerRoutes)
+        .where(
+          and(
+            eq(groomerRoutes.staffId, staffId),
+            eq(groomerRoutes.routeDate, date)
+          )
+        );
+
+      const [routeRow] = existing
+        ? await tx
+            .update(groomerRoutes)
+            .set({
+              status: "optimized",
+              totalTravelMins: optimized.totalTravelMins,
+              totalDistanceKm: optimized.totalDistanceKm.toFixed(2),
+              optimizedAt: now,
+              updatedAt: now,
+            })
+            .where(eq(groomerRoutes.id, existing.id))
+            .returning()
+        : await tx
+            .insert(groomerRoutes)
+            .values({
+              staffId,
+              routeDate: date,
+              status: "optimized",
+              totalTravelMins: optimized.totalTravelMins,
+              totalDistanceKm: optimized.totalDistanceKm.toFixed(2),
+              optimizedAt: now,
+            })
+            .returning();
+
+      // Replace stops: clear prior ordering, insert the freshly optimized one.
+      await tx.delete(routeStops).where(eq(routeStops.routeId, routeRow!.id));
+      if (optimized.stops.length > 0) {
+        await tx.insert(routeStops).values(
+          optimized.stops.map((s, i) => ({
+            routeId: routeRow!.id,
+            appointmentId: s.appointmentId,
+            stopOrder: i + 1,
+            latitude: s.latitude,
+            longitude: s.longitude,
+            travelMinsFromPrev: s.travelMinsFromPrev,
+            travelDistanceKmFromPrev:
+              s.travelDistanceKmFromPrev == null
+                ? null
+                : s.travelDistanceKmFromPrev.toFixed(2),
+            bufferMins,
+          }))
+        );
+      }
+
+      return routeRow!;
+    });
+
+    const stops = await loadRouteStops(db, route.id);
+    return c.json({
+      route,
+      stops,
+      provider: optimized.provider,
+      chunked: optimized.chunked,
+      subRouteCount: optimized.subRouteCount,
+      skipped,
+      warnings,
+    });
+  }
+);

src/services/clientGeocoding.ts

@@ -0,0 +1,212 @@
+import {
+  getDb,
+  businessSettings,
+  clients,
+  and,
+  eq,
+  isNull,
+  sql,
+} from "@groombook/db";
+import {
+  resolveGeocodingProvider,
+  type GeocodingProvider,
+  type GeocodeResult,
+} from "./geocoding.js";
+
+/**
+ * Client geocoding orchestration (GRO-2154, Phase 1.3 of Route Optimization).
+ *
+ * Bridges the provider-agnostic {@link GeocodingProvider} layer (GRO-2153) and
+ * the `clients` table: resolves the configured provider from `businessSettings`,
+ * geocodes a client's address, and persists `latitude`/`longitude`/`geocodedAt`.
+ *
+ * Outcomes are returned as structured {@link ClientGeocodeOutcome} values so that
+ * callers (the geocode endpoints and the auto-geocode create/update hook) can
+ * surface clear, actionable feedback — groomers need to know when an address is
+ * ambiguous or unresolvable, not just that "something failed".
+ */
+
+type Db = ReturnType<typeof getDb>;
+type ClientRow = typeof clients.$inferSelect;
+
+/** Status of a single client geocode attempt. */
+export type ClientGeocodeStatus =
+  /** Coordinates resolved and persisted. */
+  | "geocoded"
+  /** Client has no (non-blank) address on file — nothing to geocode. */
+  | "no_address"
+  /** Provider returned no match; the address is ambiguous or unrecognized. */
+  | "unresolved"
+  /** Provider call failed (transport, quota, bad key). Coordinates unchanged. */
+  | "error";
+
+/** Structured, UI-surfaceable result of geocoding one client. */
+export interface ClientGeocodeOutcome {
+  clientId: string;
+  status: ClientGeocodeStatus;
+  /** Human-readable explanation, safe to show to managers/groomers. */
+  message: string;
+  latitude: number | null;
+  longitude: number | null;
+  geocodedAt: string | null;
+  /** Provider-normalized address, when a match was found. */
+  formattedAddress: string | null;
+  /** Provider that produced (or attempted) this result. */
+  provider: string | null;
+}
+
+/**
+ * Builds the geocoding provider for the current business settings. A single
+ * provider instance should be reused across a batch so its internal rate limiter
+ * throttles the whole run (e.g. Nominatim's 1 req/sec policy).
+ */
+export async function resolveClientGeocodingProvider(
+  db: Db
+): Promise<GeocodingProvider> {
+  const [settings] = await db.select().from(businessSettings).limit(1);
+  return resolveGeocodingProvider(settings ?? null);
+}
+
+/**
+ * Geocodes a single client row through the given provider and persists the
+ * result on success. Never throws on provider failure — transport/quota errors
+ * are captured as an `"error"` outcome so callers (especially the create/update
+ * auto-geocode hook) are not broken by a flaky geocoding backend.
+ */
+export async function geocodeClient(
+  db: Db,
+  client: ClientRow,
+  provider: GeocodingProvider
+): Promise<ClientGeocodeOutcome> {
+  const base = {
+    clientId: client.id,
+    latitude: null as number | null,
+    longitude: null as number | null,
+    geocodedAt: null as string | null,
+    formattedAddress: null as string | null,
+    provider: provider.name as string | null,
+  };
+
+  const address = client.address?.trim();
+  if (!address) {
+    return {
+      ...base,
+      status: "no_address",
+      message: "Client has no address on file, so it cannot be geocoded.",
+    };
+  }
+
+  let result: GeocodeResult | null;
+  try {
+    result = await provider.geocode(address);
+  } catch (err) {
+    return {
+      ...base,
+      status: "error",
+      message: `Geocoding provider (${provider.name}) failed: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    };
+  }
+
+  if (!result) {
+    return {
+      ...base,
+      status: "unresolved",
+      message: `Address could not be resolved to a location: "${address}". Please verify or correct the address.`,
+    };
+  }
+
+  const geocodedAt = new Date();
+  await db
+    .update(clients)
+    .set({
+      latitude: result.latitude,
+      longitude: result.longitude,
+      geocodedAt,
+      updatedAt: geocodedAt,
+    })
+    .where(eq(clients.id, client.id));
+
+  return {
+    clientId: client.id,
+    status: "geocoded",
+    message: `Geocoded via ${result.provider} to ${result.latitude}, ${result.longitude}.`,
+    latitude: result.latitude,
+    longitude: result.longitude,
+    geocodedAt: geocodedAt.toISOString(),
+    formattedAddress: result.formattedAddress,
+    provider: result.provider,
+  };
+}
+
+/** Summary returned by {@link geocodeUngeocodedClients}. */
+export interface BatchGeocodeSummary {
+  provider: string;
+  /** Number of clients processed in this invocation. */
+  processed: number;
+  geocoded: number;
+  unresolved: number;
+  errors: number;
+  /** Un-geocoded clients with an address that were NOT processed (over `limit`). */
+  remaining: number;
+  /** Per-client outcomes for everything processed this invocation. */
+  outcomes: ClientGeocodeOutcome[];
+}
+
+/**
+ * Batch-geocodes clients that have an address but no `geocodedAt` yet, throttled
+ * by the active provider's rate limiter.
+ *
+ * Because Nominatim allows only ~1 req/sec, geocoding every un-geocoded client in
+ * a single HTTP request would risk timeouts on large datasets. Each invocation
+ * therefore processes at most `limit` clients (default 50, clamped 1..500) and
+ * reports `remaining`; managers re-run until `remaining` is 0.
+ */
+export async function geocodeUngeocodedClients(
+  db: Db,
+  limit = 50,
+  injectedProvider?: GeocodingProvider
+): Promise<BatchGeocodeSummary> {
+  const effectiveLimit = Math.min(Math.max(Math.trunc(limit) || 0, 1), 500);
+  const provider =
+    injectedProvider ?? (await resolveClientGeocodingProvider(db));
+
+  // Un-geocoded = geocodedAt IS NULL with a non-blank address.
+  const candidateFilter = and(
+    isNull(clients.geocodedAt),
+    sql`${clients.address} IS NOT NULL AND length(trim(${clients.address})) > 0`
+  );
+
+  const countRows = await db
+    .select({ count: sql<number>`count(*)::int` })
+    .from(clients)
+    .where(candidateFilter);
+  const totalRemaining = countRows[0]?.count ?? 0;
+
+  const rows = await db
+    .select()
+    .from(clients)
+    .where(candidateFilter)
+    .orderBy(clients.createdAt)
+    .limit(effectiveLimit);
+
+  const outcomes: ClientGeocodeOutcome[] = [];
+  for (const row of rows) {
+    outcomes.push(await geocodeClient(db, row, provider));
+  }
+
+  const geocoded = outcomes.filter((o) => o.status === "geocoded").length;
+  const unresolved = outcomes.filter((o) => o.status === "unresolved").length;
+  const errors = outcomes.filter((o) => o.status === "error").length;
+
+  return {
+    provider: provider.name,
+    processed: outcomes.length,
+    geocoded,
+    unresolved,
+    errors,
+    remaining: Math.max(totalRemaining - outcomes.length, 0),
+    outcomes,
+  };
+}

src/services/geocoding.ts

@@ -0,0 +1,419 @@
+import { decryptSecret } from "@groombook/db";
+
+/**
+ * Abstracted geocoding service layer (GRO-2153, Phase 1.2 of Route Optimization).
+ *
+ * Provides a provider-agnostic interface for turning a street address into
+ * latitude/longitude coordinates, with two concrete implementations:
+ *
+ *  - {@link NominatimGeocodingProvider} — OpenStreetMap Nominatim (default, free,
+ *    self-hostable). Enforces the public Nominatim usage policy of at most one
+ *    request per second.
+ *  - {@link GoogleGeocodingProvider} — Google Geocoding API (optional fallback,
+ *    requires an API key stored encrypted at rest in `businessSettings`).
+ *
+ * Provider selection is driven by `businessSettings.routeOptimizationProvider`
+ * via {@link resolveGeocodingProvider}. A {@link geocodeBatch} helper geocodes a
+ * list of addresses while respecting the active provider's rate limit.
+ */
+
+/** Identifier for a supported geocoding backend. Mirrors `route_optimization_provider`. */
+export type GeocodingProviderName = "nominatim" | "google";
+
+/** Successful geocoding result in WGS84 decimal degrees. */
+export interface GeocodeResult {
+  latitude: number;
+  longitude: number;
+  /** Provider-normalized display address, when available. */
+  formattedAddress: string | null;
+  /** Which provider produced this result. */
+  provider: GeocodingProviderName;
+}
+
+/** Abstract geocoding provider contract. */
+export interface GeocodingProvider {
+  /** Stable provider identifier. */
+  readonly name: GeocodingProviderName;
+  /**
+   * Minimum milliseconds to leave between consecutive requests. Used both by the
+   * provider's internal rate limiter and by {@link geocodeBatch} so callers do
+   * not need to know provider-specific limits.
+   */
+  readonly minRequestIntervalMs: number;
+  /**
+   * Geocode a single address.
+   * @returns the top match, or `null` when the address is blank or unresolvable.
+   * @throws on transport failures or provider-level errors (e.g. quota, bad key).
+   */
+  geocode(address: string): Promise<GeocodeResult | null>;
+}
+
+// --- Constants -------------------------------------------------------------
+
+/** Nominatim usage policy: at most 1 request per second. */
+const NOMINATIM_RATE_LIMIT_MS = 1000;
+const DEFAULT_NOMINATIM_BASE_URL = "https://nominatim.openstreetmap.org";
+/** Nominatim requires a descriptive User-Agent identifying the application. */
+const DEFAULT_NOMINATIM_USER_AGENT = "GroomBook/1.0 (+https://groombook.app route-optimization)";
+
+const GOOGLE_GEOCODE_BASE_URL = "https://maps.googleapis.com/maps/api/geocode/json";
+/**
+ * Google permits a high request rate; a small floor keeps batch traffic polite
+ * without throttling interactive single calls.
+ */
+const GOOGLE_RATE_LIMIT_MS = 20;
+
+// --- Injectable primitives (for testability) -------------------------------
+
+/** Minimal `fetch` shape this module depends on. Defaults to the global `fetch`. */
+export type FetchLike = (
+  input: string,
+  init?: { headers?: Record<string, string> }
+) => Promise<{
+  ok: boolean;
+  status: number;
+  statusText: string;
+  json(): Promise<unknown>;
+}>;
+
+type NowFn = () => number;
+type SleepFn = (ms: number) => Promise<void>;
+
+const defaultSleep: SleepFn = (ms) =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+const defaultFetch: FetchLike = (input, init) =>
+  (globalThis.fetch as unknown as FetchLike)(input, init);
+
+/**
+ * Serializes async tasks and guarantees at least `intervalMs` between the start
+ * of consecutive tasks. A failing task never wedges the queue.
+ */
+class RateLimiter {
+  // Negative infinity so the very first task never waits.
+  private last = Number.NEGATIVE_INFINITY;
+  private chain: Promise<unknown> = Promise.resolve();
+
+  constructor(
+    private readonly intervalMs: number,
+    private readonly now: NowFn = Date.now,
+    private readonly sleep: SleepFn = defaultSleep
+  ) {}
+
+  run<T>(task: () => Promise<T>): Promise<T> {
+    const result = this.chain.then(async () => {
+      if (this.intervalMs > 0) {
+        const elapsed = this.now() - this.last;
+        const wait = this.intervalMs - elapsed;
+        if (wait > 0) await this.sleep(wait);
+      }
+      this.last = this.now();
+      return task();
+    });
+    // Keep the queue alive regardless of whether this task resolves or rejects.
+    this.chain = result.then(
+      () => undefined,
+      () => undefined
+    );
+    return result;
+  }
+}
+
+function normalizeAddress(address: string): string {
+  return address.trim();
+}
+
+// --- Nominatim provider ----------------------------------------------------
+
+interface NominatimSearchRow {
+  lat?: string;
+  lon?: string;
+  display_name?: string;
+}
+
+export interface NominatimProviderOptions {
+  /** Override the Nominatim instance base URL (e.g. a self-hosted mirror). */
+  baseUrl?: string;
+  /** User-Agent header identifying this application, per Nominatim policy. */
+  userAgent?: string;
+  /** Minimum spacing between requests; defaults to the 1 req/sec policy. */
+  minRequestIntervalMs?: number;
+  fetchImpl?: FetchLike;
+  now?: NowFn;
+  sleep?: SleepFn;
+}
+
+export class NominatimGeocodingProvider implements GeocodingProvider {
+  readonly name = "nominatim" as const;
+  readonly minRequestIntervalMs: number;
+
+  private readonly baseUrl: string;
+  private readonly userAgent: string;
+  private readonly fetchImpl: FetchLike;
+  private readonly limiter: RateLimiter;
+
+  constructor(options: NominatimProviderOptions = {}) {
+    this.baseUrl = (options.baseUrl ?? DEFAULT_NOMINATIM_BASE_URL).replace(/\/+$/, "");
+    this.userAgent = options.userAgent ?? DEFAULT_NOMINATIM_USER_AGENT;
+    this.minRequestIntervalMs = options.minRequestIntervalMs ?? NOMINATIM_RATE_LIMIT_MS;
+    this.fetchImpl = options.fetchImpl ?? defaultFetch;
+    this.limiter = new RateLimiter(this.minRequestIntervalMs, options.now, options.sleep);
+  }
+
+  async geocode(address: string): Promise<GeocodeResult | null> {
+    const query = normalizeAddress(address);
+    if (!query) return null;
+
+    return this.limiter.run(async () => {
+      const url = new URL(`${this.baseUrl}/search`);
+      url.searchParams.set("q", query);
+      url.searchParams.set("format", "jsonv2");
+      url.searchParams.set("limit", "1");
+
+      const res = await this.fetchImpl(url.toString(), {
+        headers: { "User-Agent": this.userAgent },
+      });
+      if (!res.ok) {
+        throw new Error(
+          `Nominatim geocoding failed: ${res.status} ${res.statusText}`
+        );
+      }
+
+      const body = (await res.json()) as NominatimSearchRow[];
+      if (!Array.isArray(body) || body.length === 0) return null;
+
+      const top = body[0]!;
+      const latitude = Number(top.lat);
+      const longitude = Number(top.lon);
+      if (!Number.isFinite(latitude) || !Number.isFinite(longitude)) return null;
+
+      return {
+        latitude,
+        longitude,
+        formattedAddress: top.display_name ?? null,
+        provider: this.name,
+      };
+    });
+  }
+}
+
+// --- Google provider -------------------------------------------------------
+
+interface GoogleGeocodeResponse {
+  status: string;
+  error_message?: string;
+  results?: Array<{
+    formatted_address?: string;
+    geometry?: { location?: { lat?: number; lng?: number } };
+  }>;
+}
+
+export interface GoogleProviderOptions {
+  baseUrl?: string;
+  minRequestIntervalMs?: number;
+  fetchImpl?: FetchLike;
+  now?: NowFn;
+  sleep?: SleepFn;
+}
+
+export class GoogleGeocodingProvider implements GeocodingProvider {
+  readonly name = "google" as const;
+  readonly minRequestIntervalMs: number;
+
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+  private readonly fetchImpl: FetchLike;
+  private readonly limiter: RateLimiter;
+
+  constructor(apiKey: string, options: GoogleProviderOptions = {}) {
+    if (!apiKey) {
+      throw new Error("GoogleGeocodingProvider requires a non-empty API key");
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = options.baseUrl ?? GOOGLE_GEOCODE_BASE_URL;
+    this.minRequestIntervalMs = options.minRequestIntervalMs ?? GOOGLE_RATE_LIMIT_MS;
+    this.fetchImpl = options.fetchImpl ?? defaultFetch;
+    this.limiter = new RateLimiter(this.minRequestIntervalMs, options.now, options.sleep);
+  }
+
+  async geocode(address: string): Promise<GeocodeResult | null> {
+    const query = normalizeAddress(address);
+    if (!query) return null;
+
+    return this.limiter.run(async () => {
+      const url = new URL(this.baseUrl);
+      url.searchParams.set("address", query);
+      url.searchParams.set("key", this.apiKey);
+
+      const res = await this.fetchImpl(url.toString());
+      if (!res.ok) {
+        throw new Error(
+          `Google geocoding failed: ${res.status} ${res.statusText}`
+        );
+      }
+
+      const body = (await res.json()) as GoogleGeocodeResponse;
+      if (body.status === "ZERO_RESULTS") return null;
+      if (body.status !== "OK") {
+        const detail = body.error_message ? `: ${body.error_message}` : "";
+        throw new Error(`Google geocoding error: ${body.status}${detail}`);
+      }
+
+      const top = body.results?.[0];
+      const location = top?.geometry?.location;
+      const latitude = location?.lat;
+      const longitude = location?.lng;
+      if (
+        typeof latitude !== "number" ||
+        typeof longitude !== "number" ||
+        !Number.isFinite(latitude) ||
+        !Number.isFinite(longitude)
+      ) {
+        return null;
+      }
+
+      return {
+        latitude,
+        longitude,
+        formattedAddress: top?.formatted_address ?? null,
+        provider: this.name,
+      };
+    });
+  }
+}
+
+// --- Provider selection ----------------------------------------------------
+
+/** Subset of `businessSettings` relevant to geocoding provider selection. */
+export interface GeocodingSettings {
+  routeOptimizationProvider?: string | null;
+  /** Google API key, encrypted at rest (AES-256-GCM via `encryptSecret`). */
+  googleMapsApiKey?: string | null;
+}
+
+export interface ResolveProviderOptions {
+  /** Decryption function for the stored Google key. Defaults to `decryptSecret`. */
+  decrypt?: (ciphertext: string) => string;
+  /** Options forwarded to the constructed provider (base URL, fetch, timing). */
+  nominatim?: NominatimProviderOptions;
+  google?: GoogleProviderOptions;
+  /** Sink for non-fatal selection warnings. Defaults to `console.warn`. */
+  warn?: (message: string) => void;
+}
+
+/**
+ * Resolves the Google API key from settings (decrypting the at-rest value) or,
+ * as a development convenience, from the `GOOGLE_MAPS_API_KEY` env var.
+ * Returns `null` when no usable key is available.
+ */
+function resolveGoogleApiKey(
+  settings: GeocodingSettings,
+  decrypt: (ciphertext: string) => string,
+  warn: (message: string) => void
+): string | null {
+  const stored = settings.googleMapsApiKey?.trim();
+  if (stored) {
+    try {
+      const decrypted = decrypt(stored).trim();
+      if (decrypted) return decrypted;
+    } catch (err) {
+      warn(
+        `Failed to decrypt googleMapsApiKey; falling back to Nominatim: ${
+          err instanceof Error ? err.message : String(err)
+        }`
+      );
+      return null;
+    }
+  }
+  const fromEnv = process.env.GOOGLE_MAPS_API_KEY?.trim();
+  return fromEnv ? fromEnv : null;
+}
+
+/**
+ * Selects a geocoding provider based on `businessSettings.routeOptimizationProvider`.
+ *
+ * - `"google"` returns a {@link GoogleGeocodingProvider} when a usable key exists,
+ *   otherwise warns and falls back to Nominatim.
+ * - Any other value (including `null`/`undefined`) returns a
+ *   {@link NominatimGeocodingProvider}.
+ */
+export function resolveGeocodingProvider(
+  settings: GeocodingSettings | null | undefined,
+  options: ResolveProviderOptions = {}
+): GeocodingProvider {
+  const warn = options.warn ?? ((message: string) => console.warn(message));
+  const decrypt = options.decrypt ?? decryptSecret;
+  const requested = settings?.routeOptimizationProvider ?? "nominatim";
+
+  if (requested === "google") {
+    const apiKey = resolveGoogleApiKey(settings ?? {}, decrypt, warn);
+    if (apiKey) {
+      return new GoogleGeocodingProvider(apiKey, options.google);
+    }
+    warn(
+      "routeOptimizationProvider is 'google' but no usable API key was found; falling back to Nominatim"
+    );
+  }
+
+  return new NominatimGeocodingProvider(options.nominatim);
+}
+
+// --- Batch geocoding -------------------------------------------------------
+
+/** Input item for {@link geocodeBatch}: a caller-defined key and its address. */
+export interface BatchGeocodeItem<K> {
+  key: K;
+  address: string;
+}
+
+/** Per-item outcome from {@link geocodeBatch}. */
+export interface BatchGeocodeOutcome<K> {
+  key: K;
+  address: string;
+  /** Resolved coordinates, or `null` when unresolvable. */
+  result: GeocodeResult | null;
+  /** Present when the geocode call threw; the batch continues past errors. */
+  error?: string;
+}
+
+export interface GeocodeBatchOptions<K> {
+  /** Invoked after each item completes; useful for progress reporting. */
+  onProgress?: (
+    completed: number,
+    total: number,
+    outcome: BatchGeocodeOutcome<K>
+  ) => void;
+}
+
+/**
+ * Geocodes a list of addresses sequentially through the given provider. The
+ * provider's internal rate limiter enforces throttling (e.g. Nominatim's
+ * 1 req/sec), so addresses are processed one at a time and individual failures
+ * are captured per item rather than aborting the whole batch.
+ */
+export async function geocodeBatch<K>(
+  items: ReadonlyArray<BatchGeocodeItem<K>>,
+  provider: GeocodingProvider,
+  options: GeocodeBatchOptions<K> = {}
+): Promise<Array<BatchGeocodeOutcome<K>>> {
+  const outcomes: Array<BatchGeocodeOutcome<K>> = [];
+
+  for (const item of items) {
+    let outcome: BatchGeocodeOutcome<K>;
+    try {
+      const result = await provider.geocode(item.address);
+      outcome = { key: item.key, address: item.address, result };
+    } catch (err) {
+      outcome = {
+        key: item.key,
+        address: item.address,
+        result: null,
+        error: err instanceof Error ? err.message : String(err),
+      };
+    }
+    outcomes.push(outcome);
+    options.onProgress?.(outcomes.length, items.length, outcome);
+  }
+
+  return outcomes;
+}

src/services/routeOptimization.ts

@@ -0,0 +1,413 @@
+import { businessSettings, decryptSecret, type Db } from "@groombook/db";
+import type { FetchLike } from "./geocoding.js";
+
+/**
+ * Route optimization service (GRO-2155, Phase 2.1 of Route Optimization).
+ *
+ * Given a groomer's geocoded stops for a day, produces an optimized visiting
+ * order plus per-leg and total travel estimates. Two strategies:
+ *
+ * - {@link optimizeWithGoogle}: Google Maps Directions API with
+ *   `optimizeWaypoints: true` (real road durations/distances), used when a
+ *   Google Maps API key is configured.
+ * - {@link nearestNeighborOrder}: an offline nearest-neighbor TSP heuristic over
+ *   great-circle distance, used as the default free / no-API-key fallback.
+ *
+ * Both strategies share the same public {@link optimizeRoute} orchestrator,
+ * which also handles the >25-stop edge case by chunking into sub-routes (the
+ * Google Directions waypoint cap) and surfacing a warning.
+ */
+
+/** Google Directions allows origin + destination + up to 23 waypoints = 25
+ * points per request. We cap a sub-route at 25 stops and chunk beyond that. */
+export const MAX_STOPS_PER_ROUTE = 25;
+
+/** Average driving speed (km/h) used to convert distance into travel minutes in
+ * the offline heuristic. Tuned for mixed urban/suburban mobile-groomer routes. */
+export const AVG_SPEED_KMH = 40;
+
+/** Multiplier applied to great-circle distance to approximate real road
+ * distance in the offline heuristic (straight-line underestimates driving). */
+export const ROAD_CIRCUITY_FACTOR = 1.3;
+
+const EARTH_RADIUS_KM = 6371;
+
+/** A geocoded stop to be ordered. `appointmentId` ties it back to the schedule. */
+export interface RouteStopInput {
+  appointmentId: string;
+  latitude: number;
+  longitude: number;
+}
+
+/** A single stop in the optimized order, with travel from the previous stop. */
+export interface OptimizedStop {
+  appointmentId: string;
+  latitude: number;
+  longitude: number;
+  /** Null for the first stop of the whole route. */
+  travelMinsFromPrev: number | null;
+  /** Null for the first stop of the whole route. Kilometres, 2-dp. */
+  travelDistanceKmFromPrev: number | null;
+}
+
+export type RouteOptimizationProvider = "google" | "nearest_neighbor";
+
+export interface OptimizedRoute {
+  provider: RouteOptimizationProvider;
+  stops: OptimizedStop[];
+  totalTravelMins: number;
+  /** Kilometres, rounded to 2 decimal places. */
+  totalDistanceKm: number;
+  /** True when the route was split into multiple sub-routes (>25 stops). */
+  chunked: boolean;
+  subRouteCount: number;
+  /** Non-fatal advisories for the caller to surface to the user. */
+  warnings: string[];
+}
+
+export interface OptimizeRouteOptions {
+  /** Google Maps API key. When absent, the nearest-neighbor heuristic is used. */
+  googleApiKey?: string | null;
+  /** Injectable fetch for testing the Google path. Defaults to global fetch. */
+  fetchImpl?: FetchLike;
+}
+
+const defaultFetch: FetchLike = (input, init) =>
+  (globalThis.fetch as unknown as FetchLike)(input, init);
+
+// ─── Geometry helpers ───────────────────────────────────────────────────────
+
+function toRadians(deg: number): number {
+  return (deg * Math.PI) / 180;
+}
+
+/** Great-circle distance between two coordinates, in kilometres. */
+export function haversineKm(
+  a: { latitude: number; longitude: number },
+  b: { latitude: number; longitude: number }
+): number {
+  const dLat = toRadians(b.latitude - a.latitude);
+  const dLon = toRadians(b.longitude - a.longitude);
+  const lat1 = toRadians(a.latitude);
+  const lat2 = toRadians(b.latitude);
+  const h =
+    Math.sin(dLat / 2) ** 2 +
+    Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLon / 2) ** 2;
+  return 2 * EARTH_RADIUS_KM * Math.asin(Math.min(1, Math.sqrt(h)));
+}
+
+/** Round to 2 decimal places, returning a finite number. */
+function round2(n: number): number {
+  return Math.round(n * 100) / 100;
+}
+
+/**
+ * Estimate a road travel leg from the great-circle distance between two points.
+ * Applies a circuity factor for distance and a fixed average speed for time.
+ */
+export function estimateLeg(
+  a: { latitude: number; longitude: number },
+  b: { latitude: number; longitude: number }
+): { distanceKm: number; mins: number } {
+  const straight = haversineKm(a, b);
+  const distanceKm = straight * ROAD_CIRCUITY_FACTOR;
+  const mins = (distanceKm / AVG_SPEED_KMH) * 60;
+  return { distanceKm: round2(distanceKm), mins: Math.round(mins) };
+}
+
+// ─── Nearest-neighbor heuristic ─────────────────────────────────────────────
+
+/**
+ * Orders points greedily: start at `startIndex`, then repeatedly visit the
+ * nearest unvisited point (great-circle distance). Returns indices into the
+ * input array in visiting order. Deterministic ties broken by lowest index.
+ */
+export function nearestNeighborOrder(
+  points: Array<{ latitude: number; longitude: number }>,
+  startIndex = 0
+): number[] {
+  const n = points.length;
+  if (n <= 1) return points.map((_, i) => i);
+
+  const visited = new Array<boolean>(n).fill(false);
+  const order: number[] = [startIndex];
+  visited[startIndex] = true;
+  let current = startIndex;
+
+  for (let step = 1; step < n; step++) {
+    let best = -1;
+    let bestDist = Infinity;
+    for (let j = 0; j < n; j++) {
+      if (visited[j]) continue;
+      const d = haversineKm(points[current]!, points[j]!);
+      if (d < bestDist) {
+        bestDist = d;
+        best = j;
+      }
+    }
+    visited[best] = true;
+    order.push(best);
+    current = best;
+  }
+  return order;
+}
+
+/** Orders one chunk (<= MAX_STOPS_PER_ROUTE) via nearest-neighbor. */
+function optimizeChunkNearestNeighbor(
+  stops: RouteStopInput[]
+): RouteStopInput[] {
+  const order = nearestNeighborOrder(stops, 0);
+  return order.map((i) => stops[i]!);
+}
+
+// ─── Google Directions ──────────────────────────────────────────────────────
+
+const GOOGLE_DIRECTIONS_URL =
+  "https://maps.googleapis.com/maps/api/directions/json";
+
+interface GoogleDirectionsResponse {
+  status: string;
+  error_message?: string;
+  routes?: Array<{
+    waypoint_order?: number[];
+    legs?: Array<{
+      duration?: { value?: number };
+      distance?: { value?: number };
+    }>;
+  }>;
+}
+
+/**
+ * Orders one chunk via the Google Directions API with `optimizeWaypoints=true`.
+ *
+ * The first stop is fixed as both origin and destination (a closed tour); the
+ * remaining stops are passed as optimizable waypoints. We keep the optimized
+ * forward order and drop the final return-to-origin leg, yielding an open route
+ * whose per-leg durations/distances come from real road data.
+ */
+async function optimizeChunkGoogle(
+  stops: RouteStopInput[],
+  apiKey: string,
+  fetchImpl: FetchLike
+): Promise<{ stops: RouteStopInput[]; legsMeters: number[]; legsSeconds: number[] }> {
+  if (stops.length <= 1) {
+    return { stops: [...stops], legsMeters: [], legsSeconds: [] };
+  }
+
+  const origin = stops[0]!;
+  const waypoints = stops.slice(1);
+  const url = new URL(GOOGLE_DIRECTIONS_URL);
+  url.searchParams.set("origin", `${origin.latitude},${origin.longitude}`);
+  url.searchParams.set("destination", `${origin.latitude},${origin.longitude}`);
+  url.searchParams.set(
+    "waypoints",
+    "optimize:true|" +
+      waypoints.map((w) => `${w.latitude},${w.longitude}`).join("|")
+  );
+  url.searchParams.set("key", apiKey);
+
+  const res = await fetchImpl(url.toString());
+  if (!res.ok) {
+    throw new Error(
+      `Google Directions request failed: ${res.status} ${res.statusText}`
+    );
+  }
+  const body = (await res.json()) as GoogleDirectionsResponse;
+  if (body.status !== "OK" || !body.routes || body.routes.length === 0) {
+    throw new Error(
+      `Google Directions returned status ${body.status}${
+        body.error_message ? `: ${body.error_message}` : ""
+      }`
+    );
+  }
+
+  const route = body.routes[0]!;
+  const waypointOrder = route.waypoint_order ?? waypoints.map((_, i) => i);
+  const legs = route.legs ?? [];
+
+  // Ordered stops: origin first, then waypoints in the optimized order.
+  const orderedStops: RouteStopInput[] = [
+    origin,
+    ...waypointOrder.map((i) => waypoints[i]!),
+  ];
+
+  // legs[k] is the travel into orderedStops[k+1]. Drop the trailing return leg
+  // (orderedStops.length-1 legs describe the open route).
+  const legsMeters: number[] = [];
+  const legsSeconds: number[] = [];
+  for (let k = 0; k < orderedStops.length - 1; k++) {
+    const leg = legs[k];
+    legsMeters.push(leg?.distance?.value ?? 0);
+    legsSeconds.push(leg?.duration?.value ?? 0);
+  }
+
+  return { stops: orderedStops, legsMeters, legsSeconds };
+}
+
+// ─── Orchestration ──────────────────────────────────────────────────────────
+
+function chunk<T>(items: T[], size: number): T[][] {
+  const out: T[][] = [];
+  for (let i = 0; i < items.length; i += size) {
+    out.push(items.slice(i, i + size));
+  }
+  return out;
+}
+
+/**
+ * Optimizes a full day's stops into a single visiting order with travel
+ * metrics. Uses Google Directions when `googleApiKey` is provided, otherwise the
+ * offline nearest-neighbor heuristic. Routes longer than
+ * {@link MAX_STOPS_PER_ROUTE} stops are split into sub-routes and a warning is
+ * emitted; sub-routes are stitched end-to-end, with the boundary leg estimated
+ * from great-circle distance.
+ */
+export async function optimizeRoute(
+  inputStops: RouteStopInput[],
+  options: OptimizeRouteOptions = {}
+): Promise<OptimizedRoute> {
+  const fetchImpl = options.fetchImpl ?? defaultFetch;
+  const useGoogle = Boolean(options.googleApiKey);
+  const provider: RouteOptimizationProvider = useGoogle
+    ? "google"
+    : "nearest_neighbor";
+  const warnings: string[] = [];
+
+  if (inputStops.length === 0) {
+    return {
+      provider,
+      stops: [],
+      totalTravelMins: 0,
+      totalDistanceKm: 0,
+      chunked: false,
+      subRouteCount: 0,
+      warnings,
+    };
+  }
+
+  const chunks = chunk(inputStops, MAX_STOPS_PER_ROUTE);
+  const chunked = chunks.length > 1;
+  if (chunked) {
+    warnings.push(
+      `Route has ${inputStops.length} stops, exceeding the ${MAX_STOPS_PER_ROUTE}-stop optimization limit. Split into ${chunks.length} sub-routes; review the order at sub-route boundaries.`
+    );
+  }
+
+  const ordered: OptimizedStop[] = [];
+  let prev: RouteStopInput | null = null;
+
+  for (const group of chunks) {
+    let groupStops: RouteStopInput[];
+    let legDistanceKm: (i: number) => number;
+    let legMins: (i: number) => number;
+
+    if (useGoogle) {
+      try {
+        const result = await optimizeChunkGoogle(
+          group,
+          options.googleApiKey!,
+          fetchImpl
+        );
+        groupStops = result.stops;
+        legDistanceKm = (i) => round2(result.legsMeters[i]! / 1000);
+        legMins = (i) => Math.round(result.legsSeconds[i]! / 60);
+      } catch (err) {
+        // Google failed mid-optimization — degrade to the offline heuristic for
+        // this run rather than failing the whole request.
+        warnings.push(
+          `Google Directions unavailable; used offline heuristic: ${
+            err instanceof Error ? err.message : String(err)
+          }`
+        );
+        groupStops = optimizeChunkNearestNeighbor(group);
+        legDistanceKm = (i) => estimateLeg(groupStops[i]!, groupStops[i + 1]!).distanceKm;
+        legMins = (i) => estimateLeg(groupStops[i]!, groupStops[i + 1]!).mins;
+      }
+    } else {
+      groupStops = optimizeChunkNearestNeighbor(group);
+      legDistanceKm = (i) => estimateLeg(groupStops[i]!, groupStops[i + 1]!).distanceKm;
+      legMins = (i) => estimateLeg(groupStops[i]!, groupStops[i + 1]!).mins;
+    }
+
+    for (let i = 0; i < groupStops.length; i++) {
+      const stop = groupStops[i]!;
+      if (prev === null) {
+        // Very first stop of the whole route.
+        ordered.push({
+          appointmentId: stop.appointmentId,
+          latitude: stop.latitude,
+          longitude: stop.longitude,
+          travelMinsFromPrev: null,
+          travelDistanceKmFromPrev: null,
+        });
+      } else if (i === 0) {
+        // First stop of a non-initial chunk: estimate the boundary leg.
+        const est = estimateLeg(prev, stop);
+        ordered.push({
+          appointmentId: stop.appointmentId,
+          latitude: stop.latitude,
+          longitude: stop.longitude,
+          travelMinsFromPrev: est.mins,
+          travelDistanceKmFromPrev: est.distanceKm,
+        });
+      } else {
+        ordered.push({
+          appointmentId: stop.appointmentId,
+          latitude: stop.latitude,
+          longitude: stop.longitude,
+          travelMinsFromPrev: legMins(i - 1),
+          travelDistanceKmFromPrev: legDistanceKm(i - 1),
+        });
+      }
+      prev = stop;
+    }
+  }
+
+  const totalTravelMins = ordered.reduce(
+    (sum, s) => sum + (s.travelMinsFromPrev ?? 0),
+    0
+  );
+  const totalDistanceKm = round2(
+    ordered.reduce((sum, s) => sum + (s.travelDistanceKmFromPrev ?? 0), 0)
+  );
+
+  return {
+    provider,
+    stops: ordered,
+    totalTravelMins,
+    totalDistanceKm,
+    chunked,
+    subRouteCount: chunks.length,
+    warnings,
+  };
+}
+
+// ─── Google API key resolution ──────────────────────────────────────────────
+
+/**
+ * Resolves the Google Maps API key for route optimization from
+ * `businessSettings.googleMapsApiKey` (decrypted at rest) or, as a development
+ * convenience, the `GOOGLE_MAPS_API_KEY` env var. Returns `null` when no usable
+ * key exists, in which case callers fall back to the offline heuristic.
+ */
+export async function resolveRouteGoogleApiKey(
+  db: Db,
+  decrypt: (ciphertext: string) => string = decryptSecret
+): Promise<string | null> {
+  const [settings] = await db.select().from(businessSettings).limit(1);
+  const stored = settings?.googleMapsApiKey?.trim();
+  if (stored) {
+    try {
+      const decrypted = decrypt(stored).trim();
+      if (decrypted) return decrypted;
+    } catch (err) {
+      console.warn(
+        `Failed to decrypt googleMapsApiKey for route optimization; using offline heuristic: ${
+          err instanceof Error ? err.message : String(err)
+        }`
+      );
+    }
+  }
+  const fromEnv = process.env.GOOGLE_MAPS_API_KEY?.trim();
+  return fromEnv ? fromEnv : null;
+}