fix(gateway): keep usage ranges on calendar days

vincentkoc · vincentkoc · commit 4a5b3fd4a4ac · 2026-07-05T20:58:20.000-07:00
diff --git a/src/gateway/server-methods/usage.cost-usage-cache.test.ts b/src/gateway/server-methods/usage.cost-usage-cache.test.ts
@@ -1,7 +1,7 @@
 // Regression: costUsageCache (usage.ts:65) has no production delete/prune/evict
 // path. The TTL at L310 is read-only — on a miss after expiry, set() overwrites
-// the same key but never removes stale keys. parseDateRange derives cacheKey
-// from getTodayStartMs so cacheKey rolls at every UTC 00:00, and additional
+// the same key but never removes stale keys. resolveDateRange derives cacheKey
+// from the current calendar day so cacheKey rolls at every UTC 00:00, and additional
 // axes (days, startDate, endDate, utcOffset) multiply cardinality.
 //
 // The same file has three sibling caches that implement MAX + FIFO eviction
diff --git a/src/gateway/server-methods/usage.test.ts b/src/gateway/server-methods/usage.test.ts
@@ -290,6 +290,21 @@ describe("gateway usage helpers", () => {
     });
   });
 
+  it("resolveDateRange keeps trailing gateway ranges on calendar days across DST", () => {
+    withTimeZone("America/New_York", () => {
+      vi.useFakeTimers();
+      vi.setSystemTime(new Date("2026-03-09T12:00:00.000Z"));
+      const range = expectDateRange(
+        testApi.resolveDateRange({
+          days: 2,
+          mode: "gateway",
+        }),
+      );
+      expect(range.startMs).toBe(new Date(2026, 2, 8).getTime());
+      expect(range.endMs).toBe(new Date(2026, 2, 10).getTime() - 1);
+    });
+  });
+
   it("resolveDateRange clamps days to at least 1 and defaults to 30 days", () => {
     vi.useFakeTimers();
     vi.setSystemTime(new Date("2026-02-05T12:34:56.000Z"));
diff --git a/src/gateway/server-methods/usage.ts b/src/gateway/server-methods/usage.ts
@@ -65,7 +65,6 @@ import type { GatewayRequestHandlers, RespondFn } from "./types.js";
 const COST_USAGE_CACHE_TTL_MS = 30_000;
 const COST_USAGE_CACHE_MAX = 256;
 const SESSIONS_USAGE_AGENT_LOAD_CONCURRENCY = 12;
-const DAY_MS = 24 * 60 * 60 * 1000;
 
 type DateRange = { startMs: number; endMs: number };
 // Keep validation and parsed timestamps in one result so handlers cannot forward
@@ -169,21 +168,28 @@ const parseDateParts = (raw: unknown): DateParts | undefined => {
   return { year, monthIndex, day };
 };
 
-const datePartsToEndMs = (parts: DateParts, interpretation: DateInterpretation): number => {
+const shiftDateParts = (parts: DateParts, days: number): DateParts => {
+  const shifted = new Date(Date.UTC(parts.year, parts.monthIndex, parts.day + days));
+  return {
+    year: shifted.getUTCFullYear(),
+    monthIndex: shifted.getUTCMonth(),
+    day: shifted.getUTCDate(),
+  };
+};
+
+const datePartsToStartMs = (parts: DateParts, interpretation: DateInterpretation): number => {
   const { year, monthIndex, day } = parts;
   if (interpretation.mode === "gateway") {
-    return new Date(year, monthIndex, day + 1).getTime() - 1;
+    return new Date(year, monthIndex, day).getTime();
   }
   if (interpretation.mode === "specific") {
-    return Date.UTC(year, monthIndex, day + 1) - interpretation.utcOffsetMinutes * 60 * 1000 - 1;
+    return Date.UTC(year, monthIndex, day) - interpretation.utcOffsetMinutes * 60 * 1000;
   }
-  return Date.UTC(year, monthIndex, day + 1) - 1;
+  return Date.UTC(year, monthIndex, day);
 };
 
-const parseDateEndToMs = (raw: unknown, interpretation: DateInterpretation): number | undefined => {
-  const parts = parseDateParts(raw);
-  return parts ? datePartsToEndMs(parts, interpretation) : undefined;
-};
+const datePartsToEndMs = (parts: DateParts, interpretation: DateInterpretation): number =>
+  datePartsToStartMs(shiftDateParts(parts, 1), interpretation) - 1;
 
 // usage.cost / sessions.usage accept optional startDate/endDate. parseDateParts returns
 // undefined for both absent and invalid input, so an explicitly supplied but unparseable
@@ -258,6 +264,25 @@ const resolveDayBucketUtcOffsetMinutes = (interpretation: DateInterpretation) =>
       ? interpretation.utcOffsetMinutes
       : 0;
 
+const getDateParts = (date: Date, interpretation: DateInterpretation): DateParts => {
+  if (interpretation.mode === "gateway") {
+    return { year: date.getFullYear(), monthIndex: date.getMonth(), day: date.getDate() };
+  }
+  if (interpretation.mode === "specific") {
+    const shifted = new Date(date.getTime() + interpretation.utcOffsetMinutes * 60 * 1000);
+    return {
+      year: shifted.getUTCFullYear(),
+      monthIndex: shifted.getUTCMonth(),
+      day: shifted.getUTCDate(),
+    };
+  }
+  return {
+    year: date.getUTCFullYear(),
+    monthIndex: date.getUTCMonth(),
+    day: date.getUTCDate(),
+  };
+};
+
 /**
  * Parse a date string (YYYY-MM-DD) to start-of-day timestamp based on interpretation mode.
  * Returns undefined if invalid.
@@ -270,53 +295,17 @@ const parseDateToMs = (
   if (!parts) {
     return undefined;
   }
-  const { year, monthIndex, day } = parts;
-  if (interpretation.mode === "gateway") {
-    const ms = new Date(year, monthIndex, day).getTime();
-    return Number.isNaN(ms) ? undefined : ms;
-  }
-  if (interpretation.mode === "specific") {
-    const ms = Date.UTC(year, monthIndex, day) - interpretation.utcOffsetMinutes * 60 * 1000;
-    return Number.isNaN(ms) ? undefined : ms;
-  }
-  const ms = Date.UTC(year, monthIndex, day);
-  return Number.isNaN(ms) ? undefined : ms;
-};
-
-const getTodayStartMs = (now: Date, interpretation: DateInterpretation): number => {
-  if (interpretation.mode === "gateway") {
-    return new Date(now.getFullYear(), now.getMonth(), now.getDate()).getTime();
-  }
-  if (interpretation.mode === "specific") {
-    const shifted = new Date(now.getTime() + interpretation.utcOffsetMinutes * 60 * 1000);
-    return (
-      Date.UTC(shifted.getUTCFullYear(), shifted.getUTCMonth(), shifted.getUTCDate()) -
-      interpretation.utcOffsetMinutes * 60 * 1000
-    );
-  }
-  return Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+  return datePartsToStartMs(parts, interpretation);
 };
 
 const formatDateLabel = (ms: number, interpretation: DateInterpretation): string => {
-  const date = new Date(ms);
-  if (interpretation.mode === "gateway") {
-    return formatDateParts(date.getFullYear(), date.getMonth(), date.getDate());
-  }
-  if (interpretation.mode === "specific") {
-    const shifted = new Date(ms + interpretation.utcOffsetMinutes * 60 * 1000);
-    return formatDateParts(shifted.getUTCFullYear(), shifted.getUTCMonth(), shifted.getUTCDate());
-  }
-  return formatDateParts(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate());
+  const parts = getDateParts(new Date(ms), interpretation);
+  return formatDateParts(parts.year, parts.monthIndex, parts.day);
 };
 
 const formatDateParts = (year: number, monthIndex: number, day: number): string =>
   `${year}-${String(monthIndex + 1).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
 
-const formatExplicitDateLabel = (raw: unknown): string | undefined => {
-  const parts = parseDateParts(raw);
-  return parts ? formatDateParts(parts.year, parts.monthIndex, parts.day) : undefined;
-};
-
 const parseDays = (raw: unknown): number | undefined => {
   if (typeof raw === "number" && Number.isFinite(raw)) {
     return Math.floor(raw);
@@ -349,6 +338,15 @@ const resolveRangeDays = (raw: unknown): number | "all" | undefined => {
   return undefined;
 };
 
+const resolveTrailingDays = (
+  endDateParts: DateParts,
+  days: number,
+  interpretation: DateInterpretation,
+): DateRange => ({
+  startMs: datePartsToStartMs(shiftDateParts(endDateParts, -(days - 1)), interpretation),
+  endMs: datePartsToEndMs(endDateParts, interpretation),
+});
+
 /**
  * Get date range from params (startDate/endDate or days).
  * Falls back to last 30 days if not provided.
@@ -371,45 +369,37 @@ const resolveDateRange = (params: {
 
   const now = new Date();
   const interpretation = resolveDateInterpretation(params);
-  const todayStartMs = getTodayStartMs(now, interpretation);
-  const todayEndMs = todayStartMs + DAY_MS - 1;
+  const todayDateParts = getDateParts(now, interpretation);
+  const todayEndMs = datePartsToEndMs(todayDateParts, interpretation);
 
-  const startMs = parseDateToMs(params.startDate, interpretation);
-  const endMs = parseDateToMs(params.endDate, interpretation);
+  const startDateParts = parseDateParts(params.startDate);
+  const endDateParts = parseDateParts(params.endDate);
 
-  if (startMs !== undefined && endMs !== undefined) {
-    if (startMs > endMs) {
+  if (startDateParts && endDateParts) {
+    const startMs = datePartsToStartMs(startDateParts, interpretation);
+    const endStartMs = datePartsToStartMs(endDateParts, interpretation);
+    if (startMs > endStartMs) {
       return { ok: false, error: "startDate must not be after endDate" };
     }
-    const endOfDayMs = parseDateEndToMs(params.endDate, interpretation);
-    if (endOfDayMs === undefined) {
-      return {
-        ok: false,
-        error: "invalid endDate: expected a valid YYYY-MM-DD calendar date",
-      };
-    }
-    return { ok: true, value: { startMs, endMs: endOfDayMs } };
+    return { ok: true, value: { startMs, endMs: datePartsToEndMs(endDateParts, interpretation) } };
   }
 
   const rangeDays = resolveRangeDays(params.range);
   if (rangeDays === "all") {
     return { ok: true, value: { startMs: 0, endMs: todayEndMs } };
   }
   if (rangeDays !== undefined) {
-    const start = todayStartMs - (rangeDays - 1) * DAY_MS;
-    return { ok: true, value: { startMs: start, endMs: todayEndMs } };
+    return { ok: true, value: resolveTrailingDays(todayDateParts, rangeDays, interpretation) };
   }
 
   const days = parseDays(params.days);
   if (days !== undefined) {
     const clampedDays = Math.max(1, days);
-    const start = todayStartMs - (clampedDays - 1) * DAY_MS;
-    return { ok: true, value: { startMs: start, endMs: todayEndMs } };
+    return { ok: true, value: resolveTrailingDays(todayDateParts, clampedDays, interpretation) };
   }
 
   // Default to last 30 days
-  const defaultStartMs = todayStartMs - 29 * DAY_MS;
-  return { ok: true, value: { startMs: defaultStartMs, endMs: todayEndMs } };
+  return { ok: true, value: resolveTrailingDays(todayDateParts, 30, interpretation) };
 };
 
 type DiscoveredSessionWithAgent = DiscoveredSession & { agentId: string };
@@ -945,7 +935,6 @@ export const testApi = {
   parseUtcOffsetToMinutes,
   resolveDateInterpretation,
   parseDateToMs,
-  getTodayStartMs,
   parseDays,
   resolveDateRange,
   discoverAllSessionsForUsage,
@@ -1503,19 +1492,10 @@ export const usageHandlers: GatewayRequestHandlers = {
       ...tail,
     };
 
-    const explicitStartDate = formatExplicitDateLabel(p.startDate);
-    const explicitEndDate = formatExplicitDateLabel(p.endDate);
-    let responseStartDate = formatDateLabel(startMs, dateInterpretation);
-    let responseEndDate = formatDateLabel(endMs, dateInterpretation);
-    if (explicitStartDate !== undefined && explicitEndDate !== undefined) {
-      responseStartDate = explicitStartDate;
-      responseEndDate = explicitEndDate;
-    }
-
     const result: SessionsUsageResult = {
       updatedAt: now,
-      startDate: responseStartDate,
-      endDate: responseEndDate,
+      startDate: formatDateLabel(startMs, dateInterpretation),
+      endDate: formatDateLabel(endMs, dateInterpretation),
       sessions,
       totals: aggregateTotals,
       aggregates,
