docs(UAT_PLAYBOOK): document canonical source-of-truth for UAT seed passwords (GRO-2000)

The 'Source of truth for UAT passwords' subsection under Pre-conditions records: - The seed-uat-passwords Secret in groombook-uat is the live source. - The Bitnami SealedSecret apps/overlays/uat/ss-seed-uat-passwords.yaml in groombook/infra is the single upstream source of truth. - A kubectl recipe to pull the current values for SUPER / GROOMER / TESTER / CUSTOMER at the start of every UAT run. - The 'captured env var from a previous rotation produces 401' failure mode that GRO-2000 hit, and the manual-reseed escape hatch if the login still 401s after pulling the live value. Refs: GRO-2000, GRO-1977 (idempotent re-hash), GRO-1999 (enum fix that allowed the seed Job to run cleanly again). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-01 15:30:34 +00:00
26 changed files with 1392 additions and 3433 deletions
@@ -33,11 +33,11 @@ jobs:
      - name: Typecheck
        run: |
-          pnpm run typecheck
+          pnpm --filter @groombook/api typecheck
          pnpm --filter @groombook/db typecheck
      - name: Lint
-        run: pnpm run lint
+        run: pnpm --filter @groombook/api lint
  test:
    name: Test
@@ -58,7 +58,7 @@ jobs:
        run: pnpm install --frozen-lockfile
      - name: Run tests
-        run: pnpm run test
+        run: pnpm --filter @groombook/api test
  docker:
    name: Build & Push Docker Images
@@ -156,32 +156,3 @@ jobs:
            ${{ github.ref == 'refs/heads/main' && 'git.farh.net/groombook/reset:latest' || '' }}
          cache-from: type=registry,ref=git.farh.net/groombook/cache:reset
          cache-to: type=registry,ref=git.farh.net/groombook/cache:reset,mode=max
      - name: Smoke test seed image (blackhole npmjs.org)
        run: |
          set -euo pipefail
          IMAGE="git.farh.net/groombook/seed:${{ steps.version.outputs.tag }}"
          docker pull "$IMAGE"
          # GRO-1985: pnpm must be a real binary, not a Corepack shim, and must
          # not try to reach registry.npmjs.org on invocation.
          docker run --rm \
            --add-host registry.npmjs.org:127.0.0.1 \
            --entrypoint="" \
            "$IMAGE" \
            sh -c 'set -e; test "$(which pnpm)" = "/usr/local/bin/pnpm"; pnpm --version'
          echo "seed image: pnpm resolves to /usr/local/bin/pnpm and runs offline ✓"
      - name: Smoke test reset image (blackhole npmjs.org)
        run: |
          set -euo pipefail
          IMAGE="git.farh.net/groombook/reset:${{ steps.version.outputs.tag }}"
          docker pull "$IMAGE"
          # GRO-1985: pnpm must be a real binary, not a Corepack shim, and must
          # not try to reach registry.npmjs.org on invocation. Validates the
          # hard requirement from the issue: reset runs offline.
          docker run --rm \
            --add-host registry.npmjs.org:127.0.0.1 \
            --entrypoint="" \
            "$IMAGE" \
            sh -c 'set -e; test "$(which pnpm)" = "/usr/local/bin/pnpm"; echo "HOME=$HOME"; pnpm --version'
          echo "reset image: pnpm resolves to /usr/local/bin/pnpm, HOME=/tmp, runs offline ✓"
@@ -3,12 +3,8 @@ FROM node:22-alpine AS base
 # invocations of `pnpm` work without DNS access to registry.npmjs.org.
 # The corepack shim delegates to corepack, which re-validates against
 # npmjs.org on first use — that fails in air-gapped UAT seed/migrate/reset
-# Jobs. GRO-1983 / GRO-1889 / GRO-1909 / GRO-1981 / GRO-1985.
+# Jobs. GRO-1983 / GRO-1889 / GRO-1909.
 RUN npm install -g pnpm@9.15.4
 # Belt-and-braces: disable Corepack's download fallback so that even if a
 # Corepack shim is somehow invoked at runtime, it will not try to fetch
 # pnpm from registry.npmjs.org. Belt for the real-binary trousers. GRO-1985.
 ENV COREPACK_ENABLE_DOWNLOAD_FALLBACK=0
 WORKDIR /app
 # Install deps
@@ -30,8 +26,6 @@ RUN pnpm --filter @groombook/types build && \
 # Runtime
 FROM node:22-alpine AS runner
 RUN npm install -g pnpm@9.15.4
 # Same defence-in-depth as base: no Corepack fallback. GRO-1985.
 ENV COREPACK_ENABLE_DOWNLOAD_FALLBACK=0
 WORKDIR /app
 ENV NODE_ENV=production
@@ -52,18 +46,12 @@ CMD ["node", "dist/index.js"]
 # Migrate stage — runs drizzle-kit migrate against the database
 FROM builder AS migrate
 # pnpm needs a writable HOME for any config/state it writes. With
 # readOnlyRootFilesystem: true and runAsUser: 1000, /home/node is read-only.
 # The job pods mount a writable emptyDir at /tmp; point HOME there. GRO-1985.
 ENV HOME=/tmp
 CMD ["pnpm", "--filter", "@groombook/db", "migrate"]
 # Seed stage — populates the database with test data
 FROM builder AS seed
 ENV HOME=/tmp
 CMD ["pnpm", "--filter", "@groombook/db", "seed"]
 # Reset stage — drops all tables, re-runs migrations, and re-seeds
 FROM builder AS reset
 ENV HOME=/tmp
 CMD ["pnpm", "--filter", "@groombook/db", "reset"]
@@ -40,24 +40,6 @@ CUSTOMER=$(kubectl get secret seed-uat-passwords -n groombook-uat \
 **How to apply:** at the start of every UAT run that touches TC-API-1.4 / 1.5 / 1.6 / 1.7 / 3.18 / 3.21 / 3.23, refresh these four env vars from the cluster before issuing the sign-in request.
 ### rbac auto-provision for Better-Auth customers (GRO-2052)
 > Applies to TC-API-3.16 / 3.19a / 3.19b / 3.19c (customer-as-owner profile-summary paths) and any future case where the test user authenticates via Better-Auth email/password and the route relies on `resolveStaffMiddleware` to resolve a `staff` row.
 **Pre-condition (rbac auto-provision):** The test user must have a row in the Better-Auth `user` table (email/password sign-in creates this automatically — see TC-API-1.6 / 1.7). On first authenticated call, `resolveStaffMiddleware` (`./src/middleware/rbac.ts`) auto-provisions a `groomer` staff row keyed by `staff.user_id = user.id` (Better-Auth branch fires before the legacy OIDC `account` branch).
 **Verify the auto-provision fired** by querying the DB after the first authenticated call:
 ```sql
 SELECT user_id, role FROM staff WHERE user_id = '<test-user-id>';
 ```
 Expected: one row, `role = 'groomer'`. If zero rows return, the request hit the OIDC `account` branch and 403'd, or the user has no `user` row — fix the test sign-in path before re-running.
 **Why this matters:** without the auto-provision branch, Better-Auth email/password customers (e.g. `uat-customer@groombook.dev`) have no `account` row for the OIDC providers, so `resolveStaffMiddleware` falls through to `403 "Forbidden: no staff record found for authenticated user"` *before* `pets.ts` can run the owner-bypass added in GRO-2013. The owner-bypass code is unreachable unless the auto-provision has fired. A green TC-API-3.19a therefore implicitly proves the auto-provision worked; if 3.19a fails with the pre-fix 403, the auto-provision branch is missing from the deployed `./src` tree (see [GRO-2052](/GRO/issues/GRO-2052)).
 **How to apply:** for every run of TC-API-3.16 / 3.19a / 3.19b / 3.19c, sign in via TC-API-1.6 (email+password) first to guarantee the `user` row exists, then run the profile-summary call, then assert the `staff` row above before declaring pass.
 ## Test Cases
 ### 4.0 Health Check
@@ -120,24 +102,6 @@ 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 |
@@ -161,13 +125,6 @@ Geocoding turns a client's street address into `latitude`/`longitude` + `geocode
 | TC-API-3.17 | Get pet profile summary — groomer restricted | GET /api/pets/{id}/profile-summary as groomer with no pet linkage | 403 Forbidden |
 | TC-API-3.18 | Get pet profile summary — visitCount returns full count | GET /api/pets/{id}/profile-summary with 2+ completed appointments | visitCount >= 2 (not capped at 1) |
 | TC-API-3.19 | Get pet profile summary — upcomingAppointment excludes past | GET /api/pets/{id}/profile-summary with a past confirmed/scheduled appointment | upcomingAppointment is null (past appointments filtered by startTime >= now) |
 | TC-API-3.19a | Get pet profile summary — customer owner-bypass (GRO-2013) | Sign in as `uat-customer@groombook.dev`; `POST /api/portal/session-from-auth`; then `GET /api/pets/{ownPetId}/profile-summary` with header `X-Impersonation-Session-Id: {sessionId}` for either of the customer's seeded pets (`c0000001-0000-0000-0000-000000000002` UAT Pup Alpha, `c0000001-0000-0000-0000-000000000003` UAT Pup Beta) | 200 OK, aggregated profile returned (owner-bypass: customer with valid portal session for pet's clientId is allowed even though rbac.ts auto-provisions them as a `groomer` staff row with no appointment linkage) |
 | TC-API-3.19b | Get pet profile summary — customer cross-tenant blocked (GRO-2013) | Sign in as `uat-customer@groombook.dev`; reuse the customer's sessionId from TC-API-3.19a; `GET /api/pets/{otherClientPetId}/profile-summary` for a pet owned by a different client (`c0000002-...` or any non-customer pet) | 403 Forbidden (owner-bypass requires session.clientId === pet.clientId) |
 | TC-API-3.19c | Get pet profile summary — customer without portal session header | Same as TC-API-3.19a but omit the `X-Impersonation-Session-Id` header | 403 Forbidden (no owner-bypass without valid portal session) |
 | TC-API-3.19d | Get pet profile summary — owner-bypass writes audit row (GRO-2063) | Same setup as TC-API-3.19a (sign in as `uat-customer@groombook.dev`, establish a portal session for the customer's own clientId, call `GET /api/pets/{ownPetId}/profile-summary` with `X-Impersonation-Session-Id: {sessionId}` and a 200 OK response). Then call `GET /api/impersonation/sessions/{sessionId}/audit-log` and confirm there is exactly one entry with `action === "read_profile_summary"`, `pageVisited` matching the profile-summary path, and `metadata` containing `petId` and `actorStaffId` for the customer. Repeat TC-API-3.19b (cross-tenant attempt) and confirm NO new `read_profile_summary` row was written for the cross-tenant attempt. | 200 OK on the profile-summary call AND an audit log entry is present with the correct shape (defense-in-depth audit row; bypass attempts against other clients must NOT log) |
 | TC-API-3.29 | Get pet profile summary — unknown UUID returns 404 (GRO-2014) | GET /api/pets/00000000-0000-0000-0000-000000000001/profile-summary while authenticated (any role) | 404 Not Found with body `{"error":"Not found"}` (was empty-body 500 in GRO-2014) |
 | TC-API-3.30 | Get pet profile summary — malformed UUID returns 404 (GRO-2014) | GET /api/pets/not-a-uuid/profile-summary while authenticated | 404 Not Found with body `{"error":"Not found"}` (was empty-body 500 in GRO-2014 — Postgres uuid cast failure) |
 | TC-API-3.31 | Get pet profile summary — never empty-body 500 (GRO-2014) | GET /api/pets/{anyId}/profile-summary across the test sweep | No response has status 500 with an empty body. Any 500 must include a JSON body `{"error":"Internal Server Error"}` |
 #### Seed Data Verification (GRO-1898)
@@ -184,7 +141,6 @@ Geocoding turns a client's street address into `latitude`/`longitude` + `geocode
 | 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
@@ -211,33 +167,6 @@ Geocoding turns a client's street address into `latitude`/`longitude` + `geocode
 | TC-API-5.4 | Update service | PATCH /api/services/{id} with updated fields | 200 OK, service updated |
 | TC-API-5.5 | Delete service | DELETE /api/services/{id} | 200 OK, service deleted |
 #### 4.5.1 Seed/Reset idempotency (GRO-2064)
 Services seeding is now keyed on the deterministic `services.id` (not `name`) and
 the reset path now `TRUNCATE`s `services` alongside the other dynamic tables.
 This means:
 - Running the seed Job twice in a row (no reset in between) converges to the
  same catalogue — no `services_pkey` collision.
 - A `pnpm reset` followed by `pnpm seed` (or a CronJob reset fire) leaves the
  catalogue exactly matching `servicesDef` (10 rows, ids `b0000001-…-001` …
  `…-00a`), regardless of any stale rows that were present beforehand.
 - Mixed `seedKnownUsers` + full `seed()` invocations are safe — the
  `demoSvcs` subset (Bath & Brush, Full Groom Small/Medium, Nail Trim) is
  keyed on ids `…-001`, `…-002`, `…-003`, `…-005` and the upsert target
  is `services.id`, so the same-id / different-name collision that broke
  GRO-2033 (id `…-004` = "Nail Trim" vs servicesDef `…-004` =
  "Full Groom — Large") cannot recur.
 **UAT regression** (verify after a new image is rolled out):
 | # | Scenario | Steps | Expected |
 |---|----------|-------|----------|
 | TC-SEED-1 | Reset → seed converges | `kubectl -n groombook exec deploy/api -- pnpm reset && pnpm seed` | Seed completes 1/1, `services` count = 10, all ids match `servicesDef` |
 | TC-SEED-2 | Idempotent re-seed | Re-run `pnpm seed` without reset | Seed completes 1/1, no `services_pkey` errors, `services` count still 10 |
 | TC-SEED-3 | Catalogue matches servicesDef | `psql -c "SELECT id, name FROM services ORDER BY id"` | Rows `…-001`…`…-00a` with names "Bath & Brush"…"Sanitary Trim" exactly as in `servicesDef` |
 | TC-SEED-4 | Demo subset coexists | Run `seedKnownUsers` then full `seed` | No collision, demo subset (4 services) ends up with the same rows the full seed would write |
 ### 4.6 Staff Management
 | # | Scenario | Steps | Expected |
@@ -277,10 +206,6 @@ 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
@@ -12,8 +12,8 @@
    "test": "vitest run",
    "db:generate": "drizzle-kit generate",
    "db:migrate": "drizzle-kit migrate",
-    "db:seed": "pnpm --filter @groombook/db seed",
+    "db:seed": "tsx src/db/seed.ts",
-    "db:reset": "pnpm --filter @groombook/db reset",
+    "db:reset": "tsx src/db/reset.ts && drizzle-kit migrate && tsx src/db/seed.ts",
    "db:studio": "drizzle-kit studio"
  },
  "dependencies": {
@@ -44,7 +44,6 @@ interface MockState {
  groomingLogs: Record<string, unknown>[];
  staffMembers: Record<string, unknown>[];
  services: Record<string, unknown>[];
  impersonationSessions: Record<string, unknown>[];
 }
 let mock: MockState;
@@ -169,19 +168,6 @@ function resetMock() {
      { id: "service-1", name: "Full Groom", description: null, basePriceCents: 6000, durationMinutes: 120, active: true, createdAt: new Date(), updatedAt: new Date() },
      { id: "service-2", name: "Bath & Brush", description: null, basePriceCents: 4000, durationMinutes: 60, active: true, createdAt: new Date(), updatedAt: new Date() },
    ],
    impersonationSessions: [
      {
        id: "sess-owner",
        staffId: "staff-groomer-id",
        clientId: CLIENT_ID,
        reason: "sso-bridge",
        status: "active",
        startedAt: new Date("2024-11-01"),
        endedAt: null,
        expiresAt: new Date("2099-01-01T00:00:00Z"),
        createdAt: new Date("2024-11-01"),
      },
    ],
  };
 }
@@ -191,7 +177,6 @@ vi.mock("../db/index.js", () => {
  const groomingVisitLogs = new Proxy({ _name: "groomingVisitLogs" }, { get: (t, p) => p === "_name" ? "groomingVisitLogs" : {} });
  const staff = new Proxy({ _name: "staff" }, { get: (t, p) => p === "_name" ? "staff" : {} });
  const services = new Proxy({ _name: "services" }, { get: (t, p) => p === "_name" ? "services" : {} });
  const impersonationSessions = new Proxy({ _name: "impersonationSessions" }, { get: (t, p) => p === "_name" ? "impersonationSessions" : {} });
  // Tracks { [tableName]: { [alias]: SQLExpression } } for the current select() call
  let selectedColumns: Record<string, Record<string, unknown>> = {};
@@ -263,7 +248,6 @@ vi.mock("../db/index.js", () => {
            if (name === "groomingVisitLogs") return makeChainable(mock.groomingLogs);
            if (name === "staff") return makeChainable(mock.staffMembers);
            if (name === "services") return makeChainable(mock.services);
            if (name === "impersonationSessions") return makeChainable(mock.impersonationSessions);
            return makeChainable([]);
          },
        };
@@ -277,7 +261,6 @@ vi.mock("../db/index.js", () => {
    groomingVisitLogs,
    staff,
    services,
    impersonationSessions,
    and: vi.fn((a: unknown, b: unknown) => [a, b]),
    desc: vi.fn((c: unknown) => c),
    eq: vi.fn((_col: unknown, _val: unknown) => ({ col: _col, val: _val })),
@@ -417,101 +400,3 @@ describe("GET /:id/profile-summary — empty history", () => {
    expect(body.lastVisitDate).toBeNull();
  });
 });
 describe("GET /:id/profile-summary — owner-bypass via X-Impersonation-Session-Id (GRO-2013)", () => {
  beforeEach(resetMock);
  // Simulates the rbac.ts auto-provisioned "groomer" that a customer gets on first login:
  // role=groomer, no linkage to any appointment.
  const CUSTOMER_STAFF: StaffRow = {
    id: "staff-customer-id",
    oidcSub: null,
    userId: "user-customer-id",
    role: "groomer",
    isSuperUser: false,
    name: "UAT Customer",
    email: "uat-customer@groombook.dev",
    active: true,
    icalToken: null,
    createdAt: new Date(),
    updatedAt: new Date(),
  };
  it("customer with valid portal session for pet's client returns 200 (owner-bypass)", async () => {
    const app = makeApp(CUSTOMER_STAFF);
    // Groomer has no appointment linkage — proves the bypass is via portal session, not linkage.
    mock.appointments = [];
    const res = await app.request(`/pets/${PET_ID}/profile-summary`, {
      headers: { "X-Impersonation-Session-Id": "sess-owner" },
    });
    expect(res.status).toBe(200);
    const body = await res.json();
    expect(body.id).toBe(PET_ID);
    expect(body.name).toBe("Biscuit");
    expect(body.clientId).toBe(CLIENT_ID);
  });
  it("customer without X-Impersonation-Session-Id header still gets 403 (no bypass)", async () => {
    const app = makeApp(CUSTOMER_STAFF);
    mock.appointments = [];
    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
    expect(res.status).toBe(403);
  });
  it("customer with portal session for a DIFFERENT client gets 403 (cross-tenant blocked)", async () => {
    const app = makeApp(CUSTOMER_STAFF);
    mock.appointments = [];
    mock.impersonationSessions = [
      {
        id: "sess-other-client",
        staffId: "staff-customer-id",
        clientId: "00000000-0000-0000-0000-000000000099", // different from CLIENT_ID
        reason: "sso-bridge",
        status: "active",
        startedAt: new Date("2024-11-01"),
        endedAt: null,
        expiresAt: new Date("2099-01-01T00:00:00Z"),
        createdAt: new Date("2024-11-01"),
      },
    ];
    const res = await app.request(`/pets/${PET_ID}/profile-summary`, {
      headers: { "X-Impersonation-Session-Id": "sess-other-client" },
    });
    expect(res.status).toBe(403);
  });
  it("customer with expired portal session still gets 403", async () => {
    const app = makeApp(CUSTOMER_STAFF);
    mock.appointments = [];
    mock.impersonationSessions = [
      {
        id: "sess-expired",
        staffId: "staff-customer-id",
        clientId: CLIENT_ID,
        reason: "sso-bridge",
        status: "active",
        startedAt: new Date("2024-01-01"),
        endedAt: null,
        expiresAt: new Date("2024-02-01T00:00:00Z"), // expired long ago
        createdAt: new Date("2024-01-01"),
      },
    ];
    const res = await app.request(`/pets/${PET_ID}/profile-summary`, {
      headers: { "X-Impersonation-Session-Id": "sess-expired" },
    });
    expect(res.status).toBe(403);
  });
  it("manager does NOT need the impersonation header (existing role check still works)", async () => {
    const app = makeApp(MANAGER);
    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
    expect(res.status).toBe(200);
  });
  it("groomer with linkage to pet's client still works (regression — no regression from bypass)", async () => {
    const app = makeApp(GROOMER);
    // GROOMER fixture has appointments linked to staff-groomer-id in the mock state
    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
    expect(res.status).toBe(200);
  });
 });
@@ -1,7 +1,7 @@
 import { Hono } from "hono";
 import { zValidator } from "@hono/zod-validator";
 import { z } from "zod/v3";
-import { and, desc, eq, exists, getDb, gte, groomingVisitLogs, impersonationSessions, or, pets, appointments, staff, services, sql } from "../db/index.js";
+import { and, desc, eq, exists, getDb, gte, groomingVisitLogs, or, pets, appointments, staff, services, sql } from "../db/index.js";
 import type { AppEnv } from "../middleware/rbac.js";
 import {
  getPresignedUploadUrl,
@@ -307,38 +307,10 @@ async function groomerLinkageCheck(
  return !!linkage;
 }
 /**
 * Resolves the clientId from the X-Impersonation-Session-Id header, if present and active.
 * Used by staff routes to allow a customer (auto-provisioned as a `groomer` staff row
 * by rbac.ts) to access their own pet's data when they are the rightful owner.
 *
 * Returns null when the header is missing, the session is unknown/expired/ended, or the
 * session exists but has no clientId — callers should treat null as "no owner-bypass".
 */
 async function resolveImpersonationClientId(
  db: ReturnType<typeof getDb>,
  c: { req: { header: (name: string) => string | undefined } }
 ): Promise<string | null> {
  const sessionId = c.req.header("X-Impersonation-Session-Id");
  if (!sessionId) return null;
  const [session] = await db
    .select({ clientId: impersonationSessions.clientId, status: impersonationSessions.status, expiresAt: impersonationSessions.expiresAt })
    .from(impersonationSessions)
    .where(eq(impersonationSessions.id, sessionId))
    .limit(1);
  if (!session) return null;
  if (session.status !== "active") return null;
  if (session.expiresAt <= new Date()) return null;
  return session.clientId;
 }
 /**
 * GET /:id/profile-summary
 * Returns aggregated profile: basic pet fields + grooming history + visit stats + upcoming appointment.
 * Groomer RBAC: same visibility rules as GET /:id.
 * Owner-bypass (GRO-2013): a customer who supplies a valid X-Impersonation-Session-Id
 * for the pet's owning client may read their own pet's summary, even though rbac.ts
 * auto-provisions them as a `groomer` staff row with no appointment linkage.
 */
 petsRouter.get("/:id/profile-summary", async (c) => {
  const db = getDb();
@@ -349,15 +321,7 @@ petsRouter.get("/:id/profile-summary", async (c) => {
  const [row] = await db.select().from(pets).where(eq(pets.id, petId));
  if (!row) return c.json({ error: "Not found" }, 404);
  // Owner-bypass: customer with a valid portal session for this pet's client
  // is allowed to view their own pet's profile summary (GRO-2013).
  let isOwner = false;
  if (isGroomer) {
    const ownerClientId = await resolveImpersonationClientId(db, c);
    isOwner = !!ownerClientId && ownerClientId === row.clientId;
  }
  if (isGroomer && !isOwner) {
    const hasLinkage = await groomerLinkageCheck(db, row.clientId, staffRow);
    if (!hasLinkage) return c.json({ error: "Forbidden" }, 403);
  }
@@ -1,27 +0,0 @@
 -- Migration: 0039_extend_pet_profile_columns_idempotent.sql
 -- GRO-2033: re-register the temperament/medical/preferred-cuts columns from
 -- 0034 with an idempotent ADD COLUMN IF NOT EXISTS + a monotonic journal
 -- `when` (1780000000001), above the 0033 high-water mark (1779500000000)
 -- and above the most recent applied migration 0038 (1780000000000).
 --
 -- 0034_extend_pet_profile_columns.sql was authored on 2026-05-28 with
 -- `when` = 1751140800000 (2025-06-28) — *below* the 0033 high-water mark
 -- of 1779500000000 (2026-05-23). drizzle-orm@0.38.4
 -- (pg-core/dialect.js#migrate) only applies a migration when
 -- `migration.folderMillis > lastDbMigration.created_at`, so on prod —
 -- whose last applied entry was 0033 at created_at=1779500000000 — 0034
 -- was silently skipped, leaving `pets.temperament_score` (and friends)
 -- missing. The migrate Job still exits 0 ("migrations applied
 -- successfully!") because the journal high watermark *was* advanced by
 -- 0038, but no schema change ever ran for 0034. Seed/reset then crash on:
 --   PostgresError: column "temperament_score" does not exist (42703)
 --
 -- Same pattern as GRO-1999 (0037 → 0038): do NOT modify 0034 in-place
 -- (UAT/dev have already applied it via their lower watermarks). Add a
 -- new idempotent migration with a monotonic `when` instead so existing
 -- DBs apply it cleanly and fresh DBs are a no-op-after-no-op.
 ALTER TABLE "pets" ADD COLUMN IF NOT EXISTS "temperament_score" integer;
 ALTER TABLE "pets" ADD COLUMN IF NOT EXISTS "temperament_flags" jsonb DEFAULT '[]';
 ALTER TABLE "pets" ADD COLUMN IF NOT EXISTS "medical_alerts" jsonb DEFAULT '[]';
 ALTER TABLE "pets" ADD COLUMN IF NOT EXISTS "preferred_cuts" jsonb DEFAULT '[]';
@@ -1,26 +0,0 @@
 -- Migration: 0040_register_missing_coat_type_values.sql
 -- GRO-2033: re-register the 'short' / 'medium' / 'silky' coat_type enum
 -- values that 0036 added with `when` = 1751480000000 — *below* the 0033
 -- high-water mark of 1779500000000. drizzle-orm@0.38.4
 -- (pg-core/dialect.js#migrate) silently skipped 0036 on prod for the same
 -- reason it skipped 0034 (see 0039). 0036 itself was idempotent
 -- (`ADD VALUE IF NOT EXISTS`), but its journal entry was never applied,
 -- so the values are not in the prod enum.
 --
 -- Same pattern as GRO-1999 (0037 → 0038) and 0039: do NOT modify 0036 in
 -- place. Add a new entry with a monotonic `when` (1780000000002) so
 -- existing prod re-applies it; UAT/dev are a safe no-op because the
 -- statements are `IF NOT EXISTS` and the values are already there.
 --
 -- Postgres restriction: `ALTER TYPE ... ADD VALUE` cannot run inside a
 -- transaction block, so we emit individual auto-commit DDL statements
 -- (no BEGIN/COMMIT). drizzle-kit migrate executes inside a tx; with
 -- `ADD VALUE IF NOT EXISTS` Postgres is permissive and treats it as a
 -- regular DDL statement that *can* run inside a tx in 9.6+ when no new
 -- value is actually added. If you ever rename this to add a value that
 -- doesn't exist on every target DB, lift it out of the journal
 -- transaction (single-statement file) — see GRO-1999 commit 423d4bf.
 ALTER TYPE "coat_type" ADD VALUE IF NOT EXISTS 'short';
 ALTER TYPE "coat_type" ADD VALUE IF NOT EXISTS 'medium';
 ALTER TYPE "coat_type" ADD VALUE IF NOT EXISTS 'silky';
@@ -1,66 +0,0 @@
 -- 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");
@@ -267,27 +267,6 @@
      "when": 1780000000000,
      "tag": "0038_register_extra_large_pet_size_category",
      "breakpoints": true
    },
    {
      "idx": 39,
      "version": "7",
      "when": 1780000000001,
      "tag": "0039_extend_pet_profile_columns_idempotent",
      "breakpoints": true
    },
    {
      "idx": 40,
      "version": "7",
      "when": 1780000000002,
      "tag": "0040_register_missing_coat_type_values",
      "breakpoints": true
    },
    {
      "idx": 41,
      "version": "7",
      "when": 1780000000003,
      "tag": "0041_route_optimization",
      "breakpoints": true
    }
  ]
 }
@@ -78,9 +78,6 @@ 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,
@@ -1,7 +1,5 @@
 import {
  boolean,
  date,
  doublePrecision,
  index,
  integer,
  jsonb,
@@ -142,10 +140,6 @@ 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(),
  },
@@ -561,16 +555,6 @@ 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(),
 });
@@ -674,69 +658,3 @@ 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),
  ]
 );
@@ -401,9 +401,7 @@ const servicesDef = [
 *
 * In seedKnownUsers() this replaces the inline UAT-staff block.
 */
-async function seedUatStaffAccounts(
+async function seedUatStaffAccounts(db: ReturnType<typeof drizzle>) {
  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) {
@@ -670,132 +668,6 @@ async function seedUatStaffAccounts(
      console.log(`✓ Created UAT pet '${pet.name}' with extended fields`);
    }
  }
  // ── GRO-2100: deterministic uat-groomer ↔ pet linkage ───────────────────────
  // The UAT groomer (`uat-groomer@groombook.dev`, staffId 00000000-0000-0000-0000-000000000004)
  // needs at least one linked pet/appointment or GRO-1987 TC-UAT-2/3 cannot run
  // (the pet profile-summary endpoint returns 404 instead of 200/403).
  //
  // 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.
  //
  // 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;
 }
 /**
 * GRO-2100: create a deterministic completed appointment linking the UAT groomer
 * to "UAT Pup Alpha" (c0000001-0000-0000-0000-000000000002). "UAT Pup Beta"
 * (c0000001-0000-0000-0000-000000000003) is intentionally left UNLINKED so
 * GRO-1987 TC-UAT-3 can verify the 403 forbidden response.
 *
 * Idempotent: the deterministic appointment id (`a0000001-…-0001`) is the
 * upsert key, so re-running the seed on every reset-demo-data CronJob
 * (hourly per apps/overlays/uat/reset-cronjob.yaml) is safe.
 */
 async function seedUatGroomerLinkage(
  db: ReturnType<typeof drizzle>,
  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
    .select({ id: schema.staff.id })
    .from(schema.staff)
    .where(eq(schema.staff.email, uatGroomerEmail))
    .limit(1);
  if (!uatGroomerStaff) {
    return;
  }
  // Skip if this exact appointment already exists (idempotent on re-seed).
  const [existing] = await db
    .select({ id: schema.appointments.id })
    .from(schema.appointments)
    .where(eq(schema.appointments.id, APPT_ID))
    .limit(1);
  if (existing) {
    console.log(`✓ GRO-2100: uat-groomer linkage appointment already exists — skipping`);
    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).
  const BATH_AND_BRUSH_ID = "b0000001-0000-0000-0000-000000000001";
  const [bathService] = await db
    .select({ id: schema.services.id })
    .from(schema.services)
    .where(eq(schema.services.id, BATH_AND_BRUSH_ID))
    .limit(1);
  let serviceId: string;
  if (bathService) {
    serviceId = bathService.id;
  } else {
    const [fallback] = await db
      .select({ id: schema.services.id })
      .from(schema.services)
      .where(eq(schema.services.active, true))
      .limit(1);
    if (!fallback) {
      console.warn(`⚠ GRO-2100: no active services found — skipping uat-groomer linkage`);
      return;
    }
    serviceId = fallback.id;
  }
  // Schedule the completed appointment 7 days ago so the profile-summary's
  // "recentGroomingHistory" window (last 10) reliably includes it.
  const startTime = new Date();
  startTime.setDate(startTime.getDate() - 7);
  startTime.setHours(10, 0, 0, 0);
  const endTime = new Date(startTime.getTime() + 45 * 60 * 1000);
  await db.insert(schema.appointments).values({
    id: APPT_ID,
    clientId: customerClientId,
    petId: LINKED_PET_ID,
    serviceId,
    staffId: uatGroomerStaff.id,
    batherStaffId: null,
    status: "completed",
    startTime,
    endTime,
    notes: "GRO-2100: deterministic uat-groomer linkage for TC-UAT-2/3.",
    priceCents: null,
    confirmationStatus: "confirmed",
  });
  console.log(
    `✓ GRO-2100: linked uat-groomer (${uatGroomerStaff.id}) → UAT Pup Alpha (${LINKED_PET_ID}) via appointment ${APPT_ID}`,
  );
 }
 // ── Known-users-only seed (prod/demo) ───────────────────────────────────────
@@ -873,40 +745,27 @@ 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.
-  const uatCustomerClientId = await seedUatStaffAccounts(db);
+  await seedUatStaffAccounts(db);
-  // ── Services: idempotent upsert keyed on `id` ─────────────────────────────
+  // ── Services: idempotent upsert using name as unique key ─────────────────────
-  // GRO-2064: previously keyed on `services.name` while writing a
+  // UNIQUE constraint on services.name (migration 0020) must exist first.
-  // deterministic `id`. If a stale row existed with the same `id` but a
+  // Uses b0000001-... IDs to match main seed servicesDef for same-named services.
  // different `name`, PostgreSQL raised `services_pkey` (id collision)
  // before the name-targeted ON CONFLICT could fire. Switch the conflict
  // target to `services.id` so deterministic ids always win; pair with
  // `TRUNCATE services … CASCADE` above so each reset rebuilds the
  // catalogue from `servicesDef` cleanly. GRO-2033 close-out.
  // Id↔name map MUST stay in sync with `servicesDef` (the canonical source
  // of truth in the main `seed()` function).
  const demoSvcs = [
    { id: "b0000001-0000-0000-0000-000000000001", name: "Bath & Brush", description: "Full bath, blow-dry, brush out, and ear cleaning", basePriceCents: 4500, durationMinutes: 45 },
    { id: "b0000001-0000-0000-0000-000000000002", name: "Full Groom — Small", description: "Complete grooming for dogs under 25 lbs", basePriceCents: 6500, durationMinutes: 60 },
    { id: "b0000001-0000-0000-0000-000000000003", name: "Full Groom — Medium", description: "Complete grooming for dogs 25-50 lbs", basePriceCents: 8000, durationMinutes: 75 },
-    { id: "b0000001-0000-0000-0000-000000000005", name: "Nail Trim", description: "Nail clipping and filing", basePriceCents: 1500, durationMinutes: 15 },
+    { id: "b0000001-0000-0000-0000-000000000004", name: "Nail Trim", description: "Nail clipping and filing", basePriceCents: 1500, durationMinutes: 15 },
  ];
  for (const svc of demoSvcs) {
    await db.insert(schema.services)
      .values({ ...svc, active: true })
      .onConflictDoUpdate({
-        target: schema.services.id,
+        target: schema.services.name,
-        set: { name: svc.name, description: svc.description, basePriceCents: svc.basePriceCents, durationMinutes: svc.durationMinutes, active: true },
+        set: { description: svc.description, basePriceCents: svc.basePriceCents, durationMinutes: svc.durationMinutes, active: true },
      });
  }
  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()
@@ -976,63 +835,6 @@ 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) {
@@ -1050,22 +852,6 @@ 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 ──
@@ -1082,13 +868,7 @@ async function runSeedBody(
    ({ id: uuid(), name: `Bather ${i + 1}`, email: `bather${i + 1}@groombook.dev`, role: "groomer" as const, isSuperUser: false })
  );
-  // GRO-2064: also TRUNCATE `services` so each reset rebuilds the catalogue
+  await db.execute(sql`TRUNCATE impersonation_sessions, impersonation_audit_logs, appointments, invoices, invoice_line_items, invoice_tip_splits, grooming_visit_logs CASCADE`);
  // from `servicesDef` (deterministic IDs + UNIQUE(name)). Stale service rows
  // (e.g. a prior `seedKnownUsers` run that wrote a different `name` for the
  // same `id`) would otherwise cause the deterministic upsert to PK-collide
  // on `services.id` — see CTO review on infra PR #605 (rev #4230). TRUNCATE
  // CASCADE handles appointments/invoices FKs to services.id.
  await db.execute(sql`TRUNCATE services, impersonation_sessions, impersonation_audit_logs, appointments, invoices, invoice_line_items, invoice_tip_splits, grooming_visit_logs CASCADE`);
  const allStaff = [...managerStaff, ...receptionistStaff, ...groomers, ...bathers];
  for (const s of allStaff) {
@@ -1136,14 +916,12 @@ async function runSeedBody(
  // ── 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.
-  const uatCustomerClientId = await seedUatStaffAccounts(db);
+  await seedUatStaffAccounts(db);
  // ── Services ──
-  // GRO-2064: key the upsert on `services.id` (not `name`) so deterministic
+  // Upsert services using name as unique key. With deterministic IDs in
-  // ids always win, and rely on the TRUNCATE above to clear stale rows before
+  // servicesDef and TRUNCATE clearing downstream tables first, this is
-  // the catalogue is rebuilt. The previous name-targeted upsert failed with
+  // idempotent: first run inserts, subsequent runs update existing rows.
  // `services_pkey` when a prior run had left a row with the same id but a
  // different name (CTO review on infra PR #605, rev #4230).
  const serviceIds: string[] = [];
  for (const s of servicesDef) {
    serviceIds.push(s.id);
@@ -1157,18 +935,12 @@ async function runSeedBody(
        active: true,
      })
      .onConflictDoUpdate({
-        target: schema.services.id,
+        target: schema.services.name,
-        set: { name: s.name, description: s.desc, basePriceCents: s.price, durationMinutes: s.dur, active: true },
+        set: { description: s.desc, basePriceCents: s.price, durationMinutes: s.dur, active: true },
      });
  }
  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);
@@ -1687,6 +1459,8 @@ async function runSeedBody(
  }
  console.log(`✓ Created ${visitLogCount} grooming visit logs`);
  console.log("\nSeed complete!");
  await client.end();
 }
 seed().catch((err) => {
@@ -1,192 +0,0 @@
 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();
  });
 });
@@ -1,313 +0,0 @@
 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],
    ]);
  });
 });
@@ -1,631 +0,0 @@
 /**
 * Pet Profile Summary Tests
 *
 * Covers GET /api/pets/:id/profile-summary in the deployed tree (root src/).
 *
 * Two suites share one mock harness:
 *
 *   1. GRO-2013 owner-bypass (the deployed-tree port of #135):
 *      A customer who is auto-provisioned as a `groomer` staff row by rbac.ts
 *      (with no appointment linkage) may still read their own pet's summary
 *      when they supply a valid X-Impersonation-Session-Id whose clientId
 *      matches the pet's clientId.
 *
 *   2. GRO-2014 error handling (deployed tree):
 *      - Empty-body 500 must never escape the route — the onError handler
 *        converts unhandled errors into a structured JSON 500.
 *      - Malformed UUIDs must return 404 (not 500 via a Postgres uuid cast).
 *      - Missing staff context must return 401 (not TypeError on staffRow.id).
 *      - Pet not found must return 404.
 *      - Groomer with no appointment linkage must return 403.
 *      - Manager and groomer with linkage must receive the summary body.
 *
 * Deployed tree handler: src/routes/pets.ts. The mock queries the
 * `appointments` table (the live schema) for visit history, not
 * `groomingVisitLogs`.
 */
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import { Hono } from "hono";
 import type { AppEnv, StaffRow } from "../middleware/rbac.js";
 // ─── Staff fixtures ──────────────────────────────────────────────────────────
 const MANAGER: StaffRow = {
  id: "staff-manager-id",
  oidcSub: "oidc-manager-sub",
  userId: null,
  role: "manager",
  isSuperUser: true,
  name: "Manager McManager",
  email: "manager@example.com",
  active: true,
  icalToken: null,
  createdAt: new Date(),
  updatedAt: new Date(),
 };
 const GROOMER: StaffRow = {
  ...MANAGER,
  id: "staff-groomer-id",
  oidcSub: "oidc-groomer-sub",
  role: "groomer",
  isSuperUser: false,
  name: "Groomer Gary",
  email: "groomer@example.com",
 };
 /**
 * Mirrors the auto-provisioned "groomer" staff row rbac.ts creates for an
 * OIDC user (e.g. uat-customer@groombook.dev) on first login: role=groomer,
 * no appointment linkage.
 */
 const CUSTOMER_STAFF: StaffRow = {
  ...MANAGER,
  id: "staff-customer-id",
  oidcSub: null,
  userId: "user-customer-id",
  role: "groomer",
  name: "UAT Customer",
  email: "uat-customer@groombook.dev",
 };
 // ─── Mutable mock state ─────────────────────────────────────────────────────
 const CLIENT_ID = "c0000001-0000-0000-0000-000000000001";
 const PET_ID = "c0000001-0000-0000-0000-000000000002";
 const OTHER_CLIENT_PET_ID = "c0000002-0000-0000-0000-000000000099";
 const UNKNOWN_PET_UUID = "00000000-0000-0000-0000-000000000001";
 const futureDate = () => new Date(Date.now() + 30 * 60_000);
 const pastDate = () => new Date(Date.now() - 5 * 60_000);
 function makePet(overrides: Record<string, unknown> = {}) {
  return {
    id: PET_ID,
    clientId: CLIENT_ID,
    name: "Biscuit",
    species: "dog",
    breed: "Golden Retriever",
    weightKg: "30.00",
    dateOfBirth: null,
    healthAlerts: null,
    groomingNotes: null,
    cutStyle: null,
    shampooPreference: null,
    specialCareNotes: null,
    customFields: {},
    petSizeCategory: "large",
    coatType: "double",
    photoKey: null,
    photoUploadedAt: null,
    createdAt: new Date("2024-01-01"),
    updatedAt: new Date("2024-01-01"),
    ...overrides,
  };
 }
 function makeAppointment(overrides: Record<string, unknown> = {}) {
  return {
    id: "appt-1",
    clientId: CLIENT_ID,
    petId: PET_ID,
    serviceId: "service-1",
    staffId: GROOMER.id,
    batherStaffId: null,
    status: "completed",
    startTime: new Date("2024-06-01T09:00:00Z"),
    endTime: new Date("2024-06-01T11:00:00Z"),
    notes: null,
    priceCents: 6000,
    seriesId: null,
    seriesIndex: null,
    groupId: null,
    confirmationStatus: "confirmed",
    confirmedAt: null,
    cancelledAt: null,
    confirmationToken: null,
    customerNotes: null,
    createdAt: new Date("2024-05-15"),
    updatedAt: new Date("2024-05-15"),
    ...overrides,
  };
 }
 function makeSession(overrides: Record<string, unknown> = {}) {
  return {
    id: "sess-owner",
    staffId: CUSTOMER_STAFF.id,
    clientId: CLIENT_ID,
    reason: "sso-bridge",
    status: "active",
    startedAt: new Date(),
    endedAt: null,
    expiresAt: futureDate(),
    createdAt: new Date(),
    ...overrides,
  };
 }
 // ─── DB mock state ──────────────────────────────────────────────────────────
 let petsTable: Record<string, unknown>[];
 let appointmentsTable: Record<string, unknown>[];
 let sessionsTable: Record<string, unknown>[];
 // selectQueue: queries resolve in FIFO order. Each .from(table) result
 // returns a chain that resolves to the next queued row set on a terminal
 // call (.where()/.orderBy()/.limit()).
 //
 // A queued entry of `{ table: "pets", rows: null, throw: "..." }` tells the
 // mock to throw instead of returning rows — used by the GRO-2014 "JSON
 // envelope on downstream error" test. Any other queued entry with `rows`
 // resolves to those rows. An entry with `rows: []` returns an empty array
 // (no rows, no throw).
 let selectQueue: Array<{
  table: string;
  rows: unknown[] | null;
  throw?: string;
 }> = [];
 // Captured `db.insert(table).values(vals)` calls. Mirrors the pattern from
 // src/__tests__/impersonation.test.ts so the GRO-2063 audit row assertions
 // can inspect what the route tried to write without needing a real DB.
 let insertCapture: Array<{ table: string; vals: Record<string, unknown> }> = [];
 function enqueue(table: string, rows: unknown[] = []) {
  selectQueue.push({ table, rows });
 }
 function enqueueThrow(table: string, message: string) {
  selectQueue.push({ table, rows: null, throw: message });
 }
 function resetMock() {
  petsTable = [makePet()];
  appointmentsTable = [makeAppointment()];
  sessionsTable = [makeSession()];
  selectQueue = [];
  insertCapture = [];
 }
 // ─── Module mocks ───────────────────────────────────────────────────────────
 vi.mock("@groombook/db", () => {
  function makeTable(name: string) {
    return new Proxy(
      { _name: name },
      {
        get(target, prop) {
          if (prop === "_name") return name;
          if (prop === "$inferSelect") return {};
          return { table: name, column: prop };
        },
      }
    );
  }
  function sqlMock(_strings: TemplateStringsArray, ..._params: unknown[]) {
    const queryString = _strings[0];
    return {
      queryChunks: [queryString],
      as: (alias: string) => ({
        queryChunks: [queryString],
        fieldAlias: alias,
        getSQL() { return this.queryChunks; },
      }),
    };
  }
  function takeQueuedRows(tableName: string): unknown[] {
    const next = selectQueue.shift();
    if (next && next.table === tableName) {
      if (next.throw) {
        throw new Error(next.throw);
      }
      return next.rows ?? [];
    }
    return [];
  }
  // Wrap a finalised result in a Proxy that exposes chainable methods
  // and the resolved rows. Each call to a chainable method (where/orderBy/
  // limit/...) returns the SAME rows so the route's natural await on the
  // chain resolves to the queued data.
  function wrapRows(rows: unknown[]): unknown {
    return new Proxy(rows, {
      get(target, prop: string | symbol) {
        if (prop === "where" || prop === "orderBy" || prop === "limit"
          || prop === "leftJoin" || prop === "innerJoin" || prop === "from") {
          return () => wrapRows(rows);
        }
        if (prop === "then") {
          return (onFulfilled?: (v: unknown) => unknown, onRejected?: (e: unknown) => unknown) =>
            Promise.resolve(rows).then(onFulfilled, onRejected);
        }
        if (prop === Symbol.iterator) {
          return function* () { for (const v of target) yield v; };
        }
        if (prop === Symbol.asyncIterator) {
          return async function* () { for (const v of target) yield v; };
        }
        // @ts-expect-error proxy access
        return target[prop];
      },
    });
  }
  return {
    getDb: () => ({
      select: (_cols?: Record<string, unknown>) => ({
        from: (table: { _name?: string }) => wrapRows(takeQueuedRows(table._name ?? "")),
      }),
      insert: (table: { _name?: string }) => ({
        values: (vals: Record<string, unknown>) => {
          insertCapture.push({ table: table._name ?? "unknown", vals });
          return { returning: () => [{}] };
        },
      }),
      update: () => ({ set: () => ({ where: () => ({ returning: () => [{}] }) }) }),
      delete: () => ({ where: () => ({ returning: () => [{}] }) }),
    }),
    pets: makeTable("pets"),
    appointments: makeTable("appointments"),
    staff: makeTable("staff"),
    services: makeTable("services"),
    impersonationSessions: makeTable("impersonationSessions"),
    impersonationAuditLogs: makeTable("impersonation_audit_logs"),
    and: vi.fn((..._args: unknown[]) => ({})),
    desc: vi.fn((c: unknown) => c),
    eq: vi.fn((_a: unknown, _b: unknown) => ({})),
    exists: vi.fn(() => true),
    or: vi.fn((..._args: unknown[]) => ({})),
    sql: sqlMock,
  };
 });
 vi.mock("../lib/s3.js", () => ({
  getPresignedUploadUrl: vi.fn(),
  getPresignedGetUrl: vi.fn(),
  deleteObject: vi.fn(),
 }));
 // ─── Import after mocks are set up ──────────────────────────────────────────
 const { petsRouter } = await import("../routes/pets.js");
 // ─── App builder ────────────────────────────────────────────────────────────
 function buildApp(staffRow: StaffRow | null) {
  const app = new Hono<AppEnv>();
  app.use("*", async (c, next) => {
    if (staffRow) {
      c.set("jwtPayload", { sub: staffRow.oidcSub ?? staffRow.userId ?? "" });
      c.set("staff", staffRow);
    }
    await next();
  });
  app.route("/pets", petsRouter);
  return app;
 }
 // ─── Reset before each test ─────────────────────────────────────────────────
 beforeEach(() => {
  resetMock();
  vi.clearAllMocks();
 });
 // ─── GRO-2014 error-handling suite ──────────────────────────────────────────
 describe("GET /:id/profile-summary — GRO-2014 error handling", () => {
  it("returns 404 (not 500) for a malformed UUID path param", async () => {
    const app = buildApp(MANAGER);
    const res = await app.request("/pets/not-a-uuid/profile-summary");
    expect(res.status).toBe(404);
    const body = (await res.json()) as { error: string };
    expect(body.error).toBe("Not found");
  });
  it("returns 401 when staff context is missing (defense in depth)", async () => {
    const app = buildApp(null);
    const res = await app.request(`/pets/${UNKNOWN_PET_UUID}/profile-summary`);
    expect(res.status).toBe(401);
    const body = (await res.json()) as { error: string };
    expect(body.error).toBe("Unauthorized");
  });
  it("returns 404 when authenticated and pet does not exist", async () => {
    enqueue("pets", []);
    const app = buildApp(MANAGER);
    const res = await app.request(`/pets/${UNKNOWN_PET_UUID}/profile-summary`);
    expect(res.status).toBe(404);
    const body = (await res.json()) as { error: string };
    expect(body.error).toBe("Not found");
  });
  it("returns 403 when groomer has no appointment linkage to the pet's client", async () => {
    enqueue("pets", petsTable);
    enqueue("appointments", []); // linkage check returns empty → 403
    const app = buildApp(GROOMER);
    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
    expect(res.status).toBe(403);
    const body = (await res.json()) as { error: string };
    expect(body.error).toBe("Forbidden");
  });
  it("returns 200 with summary for a manager (no groomer linkage check)", async () => {
    enqueue("pets", petsTable);
    enqueue("appointments", appointmentsTable); // history
    enqueue("appointments", [{ count: 1 }]);    // visit count
    enqueue("appointments", []);                // upcoming (none)
    const app = buildApp(MANAGER);
    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
    expect(res.status).toBe(200);
    const body = (await res.json()) as Record<string, unknown>;
    expect(body.id).toBe(PET_ID);
    expect(body.name).toBe("Biscuit");
    expect(body.visitCount).toBe(1);
    expect(body.upcomingAppointment).toBeNull();
    expect(body.recentGroomingHistory).toBeInstanceOf(Array);
  });
  it("returns 200 with summary for a groomer with appointment linkage", async () => {
    enqueue("pets", petsTable);
    enqueue("appointments", [{ id: "appt-1" }]); // linkage found
    enqueue("appointments", appointmentsTable);  // history
    enqueue("appointments", [{ count: 1 }]);     // visit count
    enqueue("appointments", []);                 // upcoming
    const app = buildApp(GROOMER);
    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
    expect(res.status).toBe(200);
    const body = (await res.json()) as Record<string, unknown>;
    expect(body.id).toBe(PET_ID);
  });
  it("returns a JSON envelope (not empty body) when a downstream query throws", async () => {
    enqueueThrow("pets", "simulated postgres uuid cast failure");
    const app = buildApp(MANAGER);
    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
    expect(res.status).toBe(500);
    const body = (await res.json()) as { error: string };
    expect(body.error).toBe("Internal Server Error");
  });
 });
 // ─── GRO-2013 owner-bypass suite ────────────────────────────────────────────
 describe("GET /:id/profile-summary — owner-bypass (GRO-2013)", () => {
  it("returns 404 when the pet does not exist", async () => {
    enqueue("pets", []);
    const app = buildApp(MANAGER);
    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
    expect(res.status).toBe(404);
  });
  it("returns 200 with aggregated profile for a manager", async () => {
    enqueue("pets", petsTable);
    enqueue("appointments", appointmentsTable);
    enqueue("appointments", [{ count: 1 }]);
    enqueue("appointments", []);
    const app = buildApp(MANAGER);
    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
    expect(res.status).toBe(200);
    const body = await res.json();
    expect(body.id).toBe(PET_ID);
    expect(body.name).toBe("Biscuit");
    expect(body.recentGroomingHistory).toBeInstanceOf(Array);
    expect(body.visitCount).toBe(1);
    expect(body.upcomingAppointment).toBeNull();
  });
  it("returns 200 for a groomer with appointment linkage to the pet's client", async () => {
    enqueue("pets", petsTable);
    enqueue("appointments", [{ id: "appt-1" }]); // linkage found
    enqueue("appointments", appointmentsTable);
    enqueue("appointments", [{ count: 1 }]);
    enqueue("appointments", []);
    const app = buildApp(GROOMER);
    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
    expect(res.status).toBe(200);
  });
  it("returns 403 for a groomer with no appointment linkage and no bypass header", async () => {
    enqueue("pets", petsTable);
    enqueue("appointments", []); // no linkage
    const app = buildApp(GROOMER);
    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
    expect(res.status).toBe(403);
  });
  it("customer-as-groomer with valid active session for pet's client returns 200", async () => {
    enqueue("pets", petsTable);
    enqueue("impersonationSessions", sessionsTable); // active session found
    enqueue("appointments", appointmentsTable);
    enqueue("appointments", [{ count: 1 }]);
    enqueue("appointments", []);
    const app = buildApp(CUSTOMER_STAFF);
    const res = await app.request(`/pets/${PET_ID}/profile-summary`, {
      headers: { "X-Impersonation-Session-Id": "sess-owner" },
    });
    expect(res.status).toBe(200);
    const body = await res.json();
    expect(body.id).toBe(PET_ID);
  });
  it("customer-as-groomer with no header still gets 403 (no bypass)", async () => {
    enqueue("pets", petsTable);
    const app = buildApp(CUSTOMER_STAFF);
    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
    expect(res.status).toBe(403);
  });
  it("customer-as-groomer with session for a DIFFERENT client gets 403 (cross-tenant blocked)", async () => {
    // Session exists but clientId !== pet.clientId → bypass does not apply
    // → falls through to groomer linkage check → no linkage → 403
    enqueue("pets", petsTable);
    enqueue("impersonationSessions", [
      makeSession({
        id: "sess-other-client",
        clientId: "c0000000-0000-0000-0000-000000000099", // different from CLIENT_ID
      }),
    ]);
    enqueue("appointments", []); // no linkage → 403
    const app = buildApp(CUSTOMER_STAFF);
    const res = await app.request(`/pets/${PET_ID}/profile-summary`, {
      headers: { "X-Impersonation-Session-Id": "sess-other-client" },
    });
    expect(res.status).toBe(403);
  });
  it("customer-as-groomer with expired session still gets 403", async () => {
    enqueue("pets", petsTable);
    enqueue("impersonationSessions", [
      makeSession({ id: "sess-expired", expiresAt: pastDate() }),
    ]);
    enqueue("appointments", []); // no linkage → 403
    const app = buildApp(CUSTOMER_STAFF);
    const res = await app.request(`/pets/${PET_ID}/profile-summary`, {
      headers: { "X-Impersonation-Session-Id": "sess-expired" },
    });
    expect(res.status).toBe(403);
  });
  it("customer-as-groomer with ended (status != active) session still gets 403", async () => {
    enqueue("pets", petsTable);
    enqueue("impersonationSessions", [
      makeSession({ id: "sess-ended", status: "ended" }),
    ]);
    enqueue("appointments", []); // no linkage → 403
    const app = buildApp(CUSTOMER_STAFF);
    const res = await app.request(`/pets/${PET_ID}/profile-summary`, {
      headers: { "X-Impersonation-Session-Id": "sess-ended" },
    });
    expect(res.status).toBe(403);
  });
  it("customer-as-groomer with unknown session id still gets 403", async () => {
    enqueue("pets", petsTable);
    enqueue("impersonationSessions", []); // session not found
    enqueue("appointments", []); // no linkage → 403
    const app = buildApp(CUSTOMER_STAFF);
    const res = await app.request(`/pets/${PET_ID}/profile-summary`, {
      headers: { "X-Impersonation-Session-Id": "sess-unknown" },
    });
    expect(res.status).toBe(403);
  });
  it("manager does NOT need the impersonation header (existing role check still works)", async () => {
    enqueue("pets", petsTable);
    enqueue("appointments", appointmentsTable);
    enqueue("appointments", [{ count: 1 }]);
    enqueue("appointments", []);
    const app = buildApp(MANAGER);
    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
    expect(res.status).toBe(200);
  });
  it("groomer with linkage to pet's client still works (regression — no regression from bypass)", async () => {
    enqueue("pets", petsTable);
    enqueue("appointments", [{ id: "appt-1" }]); // linkage found
    enqueue("appointments", appointmentsTable);
    enqueue("appointments", [{ count: 1 }]);
    enqueue("appointments", []);
    const app = buildApp(GROOMER);
    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
    expect(res.status).toBe(200);
  });
  it("owner-bypass: customer cannot view another client's pet (cross-tenant block)", async () => {
    // The customer has a valid session for CLIENT_ID, but the pet belongs
    // to a different client → isOwner=false → falls through to groomer
    // linkage check → 403.
    enqueue("pets", [
      makePet({ id: OTHER_CLIENT_PET_ID, clientId: "c0000002-0000-0000-0000-000000000002" }),
    ]);
    enqueue("impersonationSessions", sessionsTable); // valid session, but for CLIENT_ID
    enqueue("appointments", []); // no linkage → 403
    const app = buildApp(CUSTOMER_STAFF);
    const res = await app.request(`/pets/${OTHER_CLIENT_PET_ID}/profile-summary`, {
      headers: { "X-Impersonation-Session-Id": "sess-owner" },
    });
    expect(res.status).toBe(403);
  });
 });
 // ─── GRO-2063 owner-bypass audit write ──────────────────────────────────────
 describe("GET /:id/profile-summary — owner-bypass audit row (GRO-2063)", () => {
  it("writes exactly one audit row on the owner-bypass success path", async () => {
    enqueue("pets", petsTable);
    enqueue("impersonationSessions", sessionsTable); // valid active session for CLIENT_ID
    enqueue("appointments", appointmentsTable);
    enqueue("appointments", [{ count: 1 }]);
    enqueue("appointments", []);
    const app = buildApp(CUSTOMER_STAFF);
    const res = await app.request(`/pets/${PET_ID}/profile-summary`, {
      headers: { "X-Impersonation-Session-Id": "sess-owner" },
    });
    expect(res.status).toBe(200);
    const auditInserts = insertCapture.filter((c) => c.table === "impersonation_audit_logs");
    expect(auditInserts).toHaveLength(1);
    const vals = auditInserts[0]!.vals;
    expect(vals.action).toBe("read_profile_summary");
    expect(vals.sessionId).toBe("sess-owner");
    expect(vals.pageVisited).toBe(`/pets/${PET_ID}/profile-summary`);
    expect(vals.metadata).toEqual({
      petId: PET_ID,
      actorStaffId: CUSTOMER_STAFF.id,
    });
  });
  it("does NOT write an audit row on the normal groomer-linkage success path", async () => {
    // GROOMER is a "real" groomer with appointment linkage, NOT the
    // auto-provisioned customer-as-groomer. No impersonation header is
    // present, so the owner-bypass branch never executes.
    enqueue("pets", petsTable);
    enqueue("appointments", [{ id: "appt-1" }]); // linkage found
    enqueue("appointments", appointmentsTable);
    enqueue("appointments", [{ count: 1 }]);
    enqueue("appointments", []);
    const app = buildApp(GROOMER);
    const res = await app.request(`/pets/${PET_ID}/profile-summary`);
    expect(res.status).toBe(200);
    const auditInserts = insertCapture.filter((c) => c.table === "impersonation_audit_logs");
    expect(auditInserts).toHaveLength(0);
  });
  it("does NOT write an audit row when the owner-bypass attempt is denied (cross-tenant)", async () => {
    // Customer has a valid session but it points at a different client.
    // isOwner=false, falls through to groomer linkage check, returns 403.
    enqueue("pets", [
      makePet({ id: OTHER_CLIENT_PET_ID, clientId: "c0000002-0000-0000-0000-000000000002" }),
    ]);
    enqueue("impersonationSessions", sessionsTable); // session is for CLIENT_ID
    enqueue("appointments", []); // no linkage → 403
    const app = buildApp(CUSTOMER_STAFF);
    const res = await app.request(`/pets/${OTHER_CLIENT_PET_ID}/profile-summary`, {
      headers: { "X-Impersonation-Session-Id": "sess-owner" },
    });
    expect(res.status).toBe(403);
    const auditInserts = insertCapture.filter((c) => c.table === "impersonation_audit_logs");
    expect(auditInserts).toHaveLength(0);
  });
 });
@@ -1,267 +0,0 @@
 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");
    expect(persisted.photoKey).toBe("pets/rex.jpg");
    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);
  });
  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);
  });
 });
@@ -43,103 +43,42 @@ const GROOMER: StaffRow = {
 // ─── Mock DB ──────────────────────────────────────────────────────────────────
 // staffLookupResult drives every `from(staff)` query that doesn't go through
 // the dev-mode `.limit()` shortcut. Tests that want to simulate "no staff row"
 // leave it null.
 let staffLookupResult: StaffRow | null = null;
 // managerFallbackResult is only consumed by the dev-mode `from(staff).limit(1)`
 // path (looking up the first manager when AUTH_DISABLED=true and no header).
 let managerFallbackResult: StaffRow | null = MANAGER;
 // userLookupResult drives `from(user).limit(1)` for the Better-Auth user
 // auto-provision branch (GRO-2052). Tests that simulate "no Better-Auth user"
 // leave it null.
 type UserRow = { id: string; name: string | null; email: string | null };
 let userLookupResult: UserRow | null = null;
 // accountLookupResult drives `from(account).limit(1)` for the legacy OIDC
 // auto-provision branch. Null means "no OIDC account row".
 let accountLookupResult: { id: string } | null = null;
 // insertReturningResult drives `insert(staff).values(...).returning()` for
 // any auto-provision branch that actually creates a staff record. Null means
 // the INSERT returned no rows (simulating a DB failure).
 let insertReturningResult: StaffRow | null = null;
 vi.mock("@groombook/db", () => {
-  function tableMarker(name: string) {
+  const staff = new Proxy(
-    return new Proxy(
+    { _name: "staff" },
-      { _name: name },
+    {
-      {
+      get(target, prop) {
-        get(_target, prop) {
+        if (prop === "_name") return "staff";
-          if (prop === "_name") return name;
+        if (prop === "$inferSelect") return {};
-          if (prop === "$inferSelect") return {};
+        return { table: "staff", column: prop };
-          return { table: name, column: prop };
+      },
-        },
+    }
-      }
+  );
    );
  }
  const staff = tableMarker("staff");
  const user = tableMarker("user");
  const account = tableMarker("account");
  function lookupFor(tableName: string) {
    if (tableName === "user") return userLookupResult;
    if (tableName === "account") return accountLookupResult;
    return staffLookupResult;
  }
  return {
    getDb: () => ({
-      select: (_columns?: unknown) => ({
+      select: () => ({
-        from: (table: { _name?: string }) => {
+        from: () => ({
-          const name = table?._name ?? "staff";
+          where: () => ({
-          return {
+            limit: () => {
-            where: () => ({
+              // dev mode fallback to first manager
-              limit: () => {
+              return managerFallbackResult ? [managerFallbackResult] : [];
-                // The user / account auto-provision branches always call
+            },
-                // `.limit(1)`; route to the per-table lookup state.
+            [Symbol.iterator]: function* () {
-                if (name === "user")
+              if (staffLookupResult) yield staffLookupResult;
-                  return userLookupResult ? [userLookupResult] : [];
+            },
-                if (name === "account")
+            0: staffLookupResult,
-                  return accountLookupResult ? [accountLookupResult] : [];
+            length: staffLookupResult ? 1 : 0,
-                // dev-mode `from(staff).limit(1)` falls back to the first
+          }),
                // manager when AUTH_DISABLED is set with no header.
                return managerFallbackResult ? [managerFallbackResult] : [];
              },
              [Symbol.iterator]: function* () {
                const row = lookupFor(name);
                if (row) yield row;
              },
              0: lookupFor(name),
              length: lookupFor(name) ? 1 : 0,
            }),
          };
        },
      }),
      insert: (_table: unknown) => ({
        values: (_v: unknown) => ({
          returning: () =>
            insertReturningResult ? [insertReturningResult] : [],
        }),
      }),
      update: (_table: unknown) => ({
        set: (_v: unknown) => ({
          where: () => Promise.resolve(undefined),
        }),
      }),
    }),
    staff,
    user,
    account,
    eq: vi.fn((_col: unknown, _val: unknown) => ({ col: _col, val: _val })),
    and: vi.fn((..._clauses: unknown[]) => ({})),
    sql: Object.assign(
      vi.fn((..._tpl: unknown[]) => ({})),
      { raw: vi.fn(() => ({})) }
    ),
  };
 });
@@ -148,25 +87,16 @@ vi.mock("@groombook/db", () => {
 function resetMocks() {
  staffLookupResult = null;
  managerFallbackResult = MANAGER;
  userLookupResult = null;
  accountLookupResult = null;
  insertReturningResult = null;
 }
 /** Build a minimal Hono app with jwtPayload pre-set, then apply a middleware. */
 function buildApp(
  middleware: MiddlewareHandler<AppEnv>,
-  handler?: (c: Context<AppEnv>) => Response | Promise<Response>,
+  handler?: (c: Context<AppEnv>) => Response | Promise<Response>
  jwtOverride?: Partial<{ sub: string; email: string; name: string }>
 ) {
  const app = new Hono<AppEnv>();
  app.use("*", async (c, next) => {
-    const defaultSub = staffLookupResult?.userId ?? "unknown-sub";
+    c.set("jwtPayload", { sub: staffLookupResult?.userId ?? "unknown-sub" });
    c.set("jwtPayload", {
      sub: jwtOverride?.sub ?? defaultSub,
      ...(jwtOverride?.email !== undefined ? { email: jwtOverride.email } : {}),
      ...(jwtOverride?.name !== undefined ? { name: jwtOverride.name } : {}),
    });
    await next();
  });
  app.use("*", middleware);
@@ -274,125 +204,6 @@ describe("resolveStaffMiddleware", () => {
  });
 });
 // ─── Auto-provision branches (GRO-2052) ───────────────────────────────────────
 //
 // Each branch creates a staff row on first authenticated request when no row
 // exists yet. The Better-Auth branch (user table) is the primary path for
 // email/password customers; the OIDC branch (account table) is a fallback for
 // legacy authentik/google/github sessions.
 describe("resolveStaffMiddleware — auto-provision", () => {
  const PROVISIONED: StaffRow = {
    ...MANAGER,
    id: "staff-provisioned-id",
    oidcSub: null,
    userId: "ba-user-customer",
    role: "groomer",
    isSuperUser: false,
    name: "UAT Customer",
    email: "uat-customer@groombook.dev",
  };
  it("Better-Auth: creates a groomer staff row when user exists but no staff record (GRO-2052)", async () => {
    // No existing staff row, no OIDC account row, but a Better-Auth user row.
    staffLookupResult = null;
    userLookupResult = {
      id: "ba-user-customer",
      name: "UAT Customer",
      email: "uat-customer@groombook.dev",
    };
    accountLookupResult = null;
    insertReturningResult = PROVISIONED;
    let capturedStaff: StaffRow | null = null;
    const app = buildApp(
      resolveStaffMiddleware,
      (c) => {
        capturedStaff = c.get("staff");
        return c.json({ ok: true });
      },
      { sub: "ba-user-customer", email: "uat-customer@groombook.dev" }
    );
    const res = await app.request("/test");
    expect(res.status).toBe(200);
    expect(capturedStaff).not.toBeNull();
    expect(capturedStaff!.role).toBe("groomer");
    expect(capturedStaff!.userId).toBe("ba-user-customer");
  });
  it("Better-Auth: returns 500 if INSERT yields no row", async () => {
    staffLookupResult = null;
    userLookupResult = {
      id: "ba-user-customer",
      name: "UAT Customer",
      email: "uat-customer@groombook.dev",
    };
    insertReturningResult = null; // simulate INSERT … RETURNING returning []
    const app = buildApp(resolveStaffMiddleware, undefined, {
      sub: "ba-user-customer",
      email: "uat-customer@groombook.dev",
    });
    const res = await app.request("/test");
    expect(res.status).toBe(500);
    const body = await res.json();
    expect(body.error).toMatch(/auto-provision failed/i);
  });
  it("Better-Auth branch runs before OIDC branch (does not require jwt.email)", async () => {
    // A Better-Auth user row alone is sufficient: jwt.email is intentionally
    // absent. The pre-GRO-2052 code only auto-provisioned inside `if (jwt.email)`.
    staffLookupResult = null;
    userLookupResult = {
      id: "ba-user-customer",
      name: "UAT Customer",
      email: "uat-customer@groombook.dev",
    };
    insertReturningResult = PROVISIONED;
    const app = buildApp(resolveStaffMiddleware, undefined, {
      sub: "ba-user-customer",
    });
    const res = await app.request("/test");
    expect(res.status).toBe(200);
  });
  it("OIDC fallback: still provisions when user row is missing but account row exists", async () => {
    // No staff row, no Better-Auth user, but an OIDC account row.
    staffLookupResult = null;
    userLookupResult = null;
    accountLookupResult = { id: "oidc-account-id" };
    insertReturningResult = { ...PROVISIONED, userId: "oidc-sub" };
    const app = buildApp(resolveStaffMiddleware, undefined, {
      sub: "oidc-sub",
      email: "oidc-user@example.com",
    });
    const res = await app.request("/test");
    expect(res.status).toBe(200);
  });
  it("falls through to 403 when neither Better-Auth user nor OIDC account row exists", async () => {
    staffLookupResult = null;
    userLookupResult = null;
    accountLookupResult = null;
    const app = buildApp(resolveStaffMiddleware, undefined, {
      sub: "ghost-sub",
      email: "ghost@example.com",
    });
    const res = await app.request("/test");
    expect(res.status).toBe(403);
    const body = await res.json();
    expect(body.error).toMatch(/no staff record/i);
  });
 });
 // ─── requireRole tests ────────────────────────────────────────────────────────
 describe("requireRole", () => {
@@ -235,15 +235,6 @@ 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"],
@@ -1,5 +1,5 @@
 import type { MiddlewareHandler } from "hono";
-import { and, eq, getDb, sql, staff, account, user } from "@groombook/db";
+import { and, eq, getDb, sql, staff, account } from "@groombook/db";
 export type StaffRole = "groomer" | "receptionist" | "manager";
 export type StaffRow = typeof staff.$inferSelect;
@@ -111,49 +111,8 @@ export const resolveStaffMiddleware: MiddlewareHandler<AppEnv> = async (
    }
  }
  // Auto-provision for Better-Auth users (GRO-2052): the user signed in via
  // Better-Auth (email/password, magic link, etc.), so a row exists in `user`
  // for jwt.sub but no `account` provider row is required. Create a minimal
  // groomer staff record on first login. This is the primary auto-provision
  // path; the OIDC branch below remains as a fallback for legacy accounts
  // that exist in `account` but not in `user`.
  const [userRow] = await db
    .select({ id: user.id, name: user.name, email: user.email })
    .from(user)
    .where(eq(user.id, jwt.sub))
    .limit(1);
  if (userRow) {
    const emailPrefix = userRow.email ? userRow.email.split("@")[0] : "Unknown";
    const name = userRow.name?.trim() || jwt.name?.trim() || emailPrefix;
    const [newStaff] = await db
      .insert(staff)
      .values({
        userId: jwt.sub,
        email: userRow.email ?? jwt.email ?? "",
        name,
        role: "groomer",
        isSuperUser: false,
        active: true,
      } as Parameters<typeof db.insert>[0] extends { values: infer V } ? V : never)
      .returning()!;
    if (!newStaff) {
      return c.json({ error: "Forbidden: auto-provision failed" }, 500);
    }
    console.log(
      `[rbac] auto-provisioned staff record for Better-Auth user: ${jwt.sub} -> staff:${newStaff.id} (${name})`
    );
    c.set("staff", newStaff);
    await next();
    return;
  }
  // Auto-provision for OIDC users: check if jwt.sub has an OAuth/OIDC account
-  // (e.g. authentik). If so, create a groomer staff record on the fly. This
+  // (e.g. authentik). If so, create a groomer staff record on the fly.
  // is kept for backward compatibility with legacy OIDC sessions whose user
  // row may not yet exist in the Better-Auth `user` table.
  if (jwt.email) {
    const [oidcAccount] = await db
      .select({ id: account.id })
@@ -3,61 +3,9 @@ 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(),
@@ -143,59 +91,9 @@ 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(),
@@ -225,29 +123,13 @@ clientsRouter.patch(
    }
    delete setValues.smsOptOut;
-    // Auto-geocode on address change (GRO-2154). If the address was cleared,
+    const [row] = await db
    // 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 (!updated) return c.json({ error: "Not found" }, 404);
+    if (!row) return c.json({ error: "Not found" }, 404);
-
+    return c.json(row);
    if (addressProvided && trimmedAddress) {
      const { row: enriched, outcome } = await autoGeocodeClient(db, updated);
      return c.json({ ...enriched, geocoding: outcome });
    }
    return c.json(updated);
  }
 );
@@ -7,8 +7,6 @@ import {
  eq,
  exists,
  getDb,
  impersonationAuditLogs,
  impersonationSessions,
  or,
  pets,
  appointments,
@@ -25,23 +23,6 @@ import {
 export const petsRouter = new Hono<AppEnv>();
 // Convert Zod validation errors from 422 to 400 and ensure any thrown error
 // returns a structured JSON body rather than Hono's default empty-body 500.
 // GRO-2014: profile-summary previously bubbled unhandled errors and produced
 // an empty-body 500. Mirror the onError pattern already used in invoices.ts
 // and reports.ts so every error has a JSON envelope.
 petsRouter.onError((err, c) => {
  if (err instanceof z.ZodError) {
    return c.json({ error: "Validation failed", issues: err.issues }, 400);
  }
  console.error("[pets] unhandled error", err);
  return c.json({ error: "Internal Server Error" }, 500);
 });
 // UUID format used by all pet routes — guards path params against malformed
 // values before they hit Drizzle / Postgres uuid columns (which would throw).
 const uuidSchema = z.string().uuid();
 const createPetSchema = z.object({
  clientId: z.string().uuid(),
  name: z.string().min(1).max(200),
@@ -128,121 +109,18 @@ petsRouter.get("/:id", async (c) => {
  return c.json(row);
 });
 /**
 * Resolves the clientId from the X-Impersonation-Session-Id header, if present and active.
 * Used by staff routes to allow a customer (auto-provisioned as a `groomer` staff row
 * by rbac.ts) to access their own pet's data when they are the rightful owner.
 *
 * Returns null when the header is missing, the session is unknown/expired/ended, or the
 * session exists but has no clientId — callers should treat null as "no owner-bypass".
 */
 async function resolveImpersonationClientId(
  db: ReturnType<typeof getDb>,
  c: { req: { header: (name: string) => string | undefined } }
 ): Promise<string | null> {
  const sessionId = c.req.header("X-Impersonation-Session-Id");
  if (!sessionId) return null;
  const [session] = await db
    .select({
      clientId: impersonationSessions.clientId,
      status: impersonationSessions.status,
      expiresAt: impersonationSessions.expiresAt,
    })
    .from(impersonationSessions)
    .where(eq(impersonationSessions.id, sessionId))
    .limit(1);
  if (!session) return null;
  if (session.status !== "active") return null;
  if (session.expiresAt <= new Date()) return null;
  return session.clientId;
 }
 /**
 * Defense-in-depth audit write for the staff-side owner-bypass path in
 * GET /pets/:id/profile-summary. Mirrors the failure-isolation pattern in
 * src/middleware/portalAudit.ts: errors are logged but never thrown, so a
 * misbehaving audit insert cannot turn a working read into a 500.
 *
 * Called only when the owner-bypass actually fires (i.e. the requester is a
 * groomer-role staff row with no appointment linkage, but supplies a valid
 * X-Impersonation-Session-Id whose clientId matches the pet's owner). The
 * `petId` and `actorStaffId` are written inside `metadata` because the
 * impersonation_audit_logs schema has no first-class columns for them and
 * adding a migration is out of scope.
 */
 async function writeOwnerBypassAudit(
  db: ReturnType<typeof getDb>,
  args: {
    sessionId: string;
    petId: string;
    actorStaffId: string;
    pageVisited: string;
  }
 ): Promise<void> {
  try {
    await db.insert(impersonationAuditLogs).values({
      sessionId: args.sessionId,
      action: "read_profile_summary",
      pageVisited: args.pageVisited,
      metadata: { petId: args.petId, actorStaffId: args.actorStaffId },
    });
  } catch (err) {
    console.error("[pets] failed to write owner-bypass audit log:", err);
  }
 }
 petsRouter.get("/:id/profile-summary", async (c) => {
  const db = getDb();
  const petId = c.req.param("id");
  // GRO-2014: validate UUID format before hitting Postgres. Passing a non-UUID
  // string to a uuid column makes the driver throw, which previously surfaced
  // as an empty-body 500 to clients.
  const parsedId = uuidSchema.safeParse(petId);
  if (!parsedId.success) {
    return c.json({ error: "Not found" }, 404);
  }
  // Defense in depth: resolveStaffMiddleware should always populate `staff`
  // for protected routes (or short-circuit with 401/403 of its own). Guard
  // anyway so a misconfigured route mount can't trigger a TypeError on
  // staffRow.id when the linkage check runs.
  const staffRow = c.get("staff");
-  if (!staffRow) {
+  const isGroomer = staffRow?.role === "groomer";
    return c.json({ error: "Unauthorized" }, 401);
  }
  const isGroomer = staffRow.role === "groomer";
  // Fetch the pet
  const [pet] = await db.select().from(pets).where(eq(pets.id, petId));
  if (!pet) return c.json({ error: "Not found" }, 404);
  // Owner-bypass (GRO-2013): a customer who supplies a valid
  // X-Impersonation-Session-Id for the pet's owning client may read their
  // own pet's summary, even though rbac.ts auto-provisions them as a
  // `groomer` staff row with no appointment linkage.
  let isOwner = false;
  if (isGroomer) {
    const headerSessionId = c.req.header("X-Impersonation-Session-Id");
    const ownerClientId = await resolveImpersonationClientId(db, c);
    isOwner = !!ownerClientId && ownerClientId === pet.clientId;
    if (isOwner && headerSessionId) {
      // GRO-2063: defense-in-depth audit row. Only fires when the bypass
      // is actually granted; never on the normal groomer-linkage path,
      // 403/404/401, or when the header is absent. Failure is swallowed
      // (try/catch inside writeOwnerBypassAudit) so this can never turn a
      // working read into a 500.
      await writeOwnerBypassAudit(db, {
        sessionId: headerSessionId,
        petId: pet.id,
        actorStaffId: staffRow.id,
        pageVisited: c.req.path,
      });
    }
  }
  // Groomer RBAC: check appointment linkage to this pet's client
-  if (isGroomer && !isOwner) {
+  if (isGroomer) {
    const [linkage] = await db
      .select({ id: appointments.id })
      .from(appointments)
@@ -225,153 +225,9 @@ 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 => ({
+  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 })));
    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(),
  description: z.string(),
  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: z.string().nullable().optional(),
  // 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()).nullable().optional(),
  medicalAlerts: z.array(portalMedicalAlertSchema).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;
    if (body.photoUrl !== undefined) updateData.photoKey = body.photoUrl;
    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");
@@ -1,212 +0,0 @@
 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,
  };
 }
@@ -1,419 +0,0 @@
 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;
 }