fix(booking): scheduling-timezone limit buckets, guarded + idempotent allocation, requested-path parity

__tests__/booking-algorithm/allocationAlgorithms.test.ts

@@ -4,7 +4,7 @@
  * Covers:
  * - manualAllocate (validation, business rules, error handling)
  * - autoAllocate (all strategies, preference filtering, error handling)
- * - preAllocate (validation, delegation)
+ * - allocateRequestedSlots (validation, delegation; formerly preAllocate)
  * - filterSlotsByPreferences (private, tested via autoAllocate)
  * - allocateConsultationSlots (session duration fix verification)
  * - allocateWebinarSlots (consecutive slot finding)
@@ -20,7 +20,7 @@
   type AllocationOptions,
 } from "@/app/dashboard/consultant/[consultantId]/(features)/shared/utils/allocationAlgorithms";
 import { AllocationService } from "@/app/dashboard/consultant/[consultantId]/(features)/shared/utils/allocationService";
 import {
   makeTimeSlot,
   makeConsecutiveTimeSlots,
   makeWeekOfAvailability,
@@ -398,8 +398,8 @@
 
       if (result.success) {
         // Should have distributed across weeks
         expect(result.selectedSlots.length).toBeGreaterThan(0);
         expect(result.strategy).toBe("optimal-distribution");
       }
     });
 
@@ -533,8 +533,8 @@
         // Morning preference should only include 9-12 slots
         result.selectedSlots.forEach((s) => {
           const hour = s.startTime.getHours();
           expect(hour).toBeGreaterThanOrEqual(9);
           expect(hour).toBeLessThan(12);
         });
       }
     });
@@ -606,11 +606,11 @@
   });
 });
 
-// ─── preAllocate ────────────────────────────────────────────────────────────
+// ─── allocateRequestedSlots ─────────────────────────────────────────────────
 
-describe("AllocationAlgorithms.preAllocate", () => {
+describe("AllocationAlgorithms.allocateRequestedSlots", () => {
   it("should reject when no requested slots provided", async () => {
-    const result = await AllocationAlgorithms.preAllocate({
+    const result = await AllocationAlgorithms.allocateRequestedSlots({
       eventType: "consultation",
       eventId: "event-1",
       durationInHours: 1,
@@ -620,7 +620,7 @@
   });
 
   it("should reject when requested slots is empty array", async () => {
-    const result = await AllocationAlgorithms.preAllocate({
+    const result = await AllocationAlgorithms.allocateRequestedSlots({
       eventType: "consultation",
       eventId: "event-1",
       durationInHours: 1,
@@ -631,7 +631,7 @@
 
   it("should reject wrong number of requested slots", async () => {
     const slots = makeFutureConsecutiveSlots("2025-06-01T09:00:00Z", 1);
-    const result = await AllocationAlgorithms.preAllocate({
+    const result = await AllocationAlgorithms.allocateRequestedSlots({
       eventType: "consultation",
       eventId: "event-1",
       durationInHours: 1,
@@ -643,7 +643,7 @@
 
   it("should succeed with correct number of slots", async () => {
     const slots = makeFutureConsecutiveSlots("2025-06-01T09:00:00Z", 2);
-    const result = await AllocationAlgorithms.preAllocate({
+    const result = await AllocationAlgorithms.allocateRequestedSlots({
       eventType: "consultation",
       eventId: "event-1",
       durationInHours: 1,
@@ -655,7 +655,11 @@
       "consultation",
       "event-1",
       slots,
-      { useRequestedSlots: true },
+      {
+        useRequestedSlots: true,
+        idempotencyKey: undefined,
+        initialAllocation: undefined,
+      },
     );
   });
 
@@ -666,7 +670,7 @@
     });
 
     const slots = makeFutureConsecutiveSlots("2025-06-01T09:00:00Z", 2);
-    const result = await AllocationAlgorithms.preAllocate({
+    const result = await AllocationAlgorithms.allocateRequestedSlots({
       eventType: "consultation",
       eventId: "event-1",
       durationInHours: 1,
@@ -680,7 +684,7 @@
     mockAllocateSlots.mockRejectedValue(new Error("Connection failed"));
 
     const slots = makeFutureConsecutiveSlots("2025-06-01T09:00:00Z", 2);
-    const result = await AllocationAlgorithms.preAllocate({
+    const result = await AllocationAlgorithms.allocateRequestedSlots({
       eventType: "consultation",
       eventId: "event-1",
       durationInHours: 1,

__tests__/booking-algorithm/calendarUtils.test.ts

@@ -40,7 +40,7 @@
   type Appointment,
 } from "@/app/dashboard/consultant/[consultantId]/(features)/shared/utils/calendarUtils";
 import { ScheduleType, DayOfWeek, AppointmentsType } from "@prisma/client";
 import {
   makeTimeSlot,
   makeConsecutiveTimeSlots,
   makeWeeklyAvailabilitySlot,
@@ -97,7 +97,7 @@
     const slots = mapWeeklySlots(data as any, new Date("2025-01-06"), "week");
     const mondaySlots = slots.filter((s) => s.startTime.getUTCDay() === 1);
     if (mondaySlots.length > 0) {
       expect(mondaySlots[0].startTime.getUTCHours()).toBe(14);
     }
   });
 
@@ -438,7 +438,8 @@
 
   it("startOfWeekSunday should return Sunday", () => {
     const result = startOfWeekSunday(new Date("2025-01-08")); // Wednesday
-    expect(result.getDay()).toBe(0);
+    // UTC weekday — this helper is UTC-based; local getDay() shifts by machine TZ
+    expect(result.getUTCDay()).toBe(0);
   });
 });
 

__tests__/booking-algorithm/idempotency-key.test.ts

@@ -0,0 +1,91 @@
+/**
+ * Idempotency-Key lifecycle for allocation attempts. A retry of the SAME
+ * payload must reuse the key (the server replays the original batch, #837);
+ * any change to mode, event, or slots must mint a fresh key.
+ */
+
+import "./setup";
+
+import {
+  computeAttemptFingerprint,
+  resolveAttemptKey,
+} from "@/app/dashboard/consultant/[consultantId]/(features)/shared/hooks/useSlotAllocation";
+// eslint-disable-next-line jest/no-mocks-import -- shared fixture builders, not module mocks (suite-wide pattern)
+import { makeConsecutiveTimeSlots } from "./__mocks__/booking.mockData";
+import type { TimeSlot } from "@/app/dashboard/consultant/[consultantId]/(features)/shared/utils/calendarUtils";
+
+const slots = makeConsecutiveTimeSlots(
+  "2026-08-03T09:00:00.000Z",
+  2,
+) as TimeSlot[];
+
+describe("computeAttemptFingerprint", () => {
+  it("is stable regardless of slot order", () => {
+    const reversed = [...slots].reverse();
+    expect(computeAttemptFingerprint("manual", "e1", slots)).toBe(
+      computeAttemptFingerprint("manual", "e1", reversed),
+    );
+  });
+
+  it("differs across modes, events, and slot sets", () => {
+    const fp = computeAttemptFingerprint("manual", "e1", slots);
+    expect(computeAttemptFingerprint("auto", "e1", slots)).not.toBe(fp);
+    expect(computeAttemptFingerprint("manual", "e2", slots)).not.toBe(fp);
+    expect(
+      computeAttemptFingerprint(
+        "manual",
+        "e1",
+        makeConsecutiveTimeSlots("2026-08-04T09:00:00.000Z", 2) as TimeSlot[],
+      ),
+    ).not.toBe(fp);
+  });
+});
+
+describe("resolveAttemptKey", () => {
+  it("reuses the key for an identical retry", () => {
+    const fp = computeAttemptFingerprint("manual", "e1", slots);
+    const first = resolveAttemptKey(null, fp);
+    const retry = resolveAttemptKey(first, fp);
+    expect(retry.key).toBe(first.key);
+  });
+
+  it("mints a new key when the payload changes", () => {
+    const first = resolveAttemptKey(
+      null,
+      computeAttemptFingerprint("manual", "e1", slots),
+    );
+    const changed = resolveAttemptKey(
+      first,
+      computeAttemptFingerprint("manual", "e1", [
+        ...slots,
+        ...(makeConsecutiveTimeSlots(
+          "2026-08-05T09:00:00.000Z",
+          2,
+        ) as TimeSlot[]),
+      ]),
+    );
+    expect(changed.key).not.toBe(first.key);
+  });
+
+  it("mints a new key when the mode changes", () => {
+    const manual = resolveAttemptKey(
+      null,
+      computeAttemptFingerprint("manual", "e1", slots),
+    );
+    const auto = resolveAttemptKey(
+      manual,
+      computeAttemptFingerprint("auto", "e1", []),
+    );
+    expect(auto.key).not.toBe(manual.key);
+  });
+
+  it("keys look like UUIDs", () => {
+    const attempt = resolveAttemptKey(
+      null,
+      computeAttemptFingerprint("auto", "e1", []),
+    );
+    expect(attempt.key).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+    );
+  });
+});