fix(webapp): keep scheduled last run times accurate

Mono-RevId: b455565ff705ccad4d1bba3fe3e02b25fbcd063e

Author: carderne

.server-changes/schedule-last-run.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: fix
+---
+
+Keep scheduled task "Last run" times stable across unchanged deployments and align them with configured schedule windows.

apps/webapp/app/v3/scheduleTimings.server.ts

@@ -88,7 +88,10 @@ export function resolveScheduleTimings(
   { phaseSecret, includeLastRun, now = new Date() }: ResolveScheduleTimingsOptions
 ): ScheduleTiming[] {
   const nominalCache = new Map<string, Date[]>();
-  const previousCache = new Map<string, Date | undefined>();
+  const previousCache = new Map<
+    string,
+    { latestNominal: Date; previousNominal?: Date } | undefined
+  >();
 
   return inputs.map((input) => {
     const window: NormalizedScheduleWindow | undefined = resolveScheduleWindow({
@@ -134,51 +137,80 @@ export function resolveScheduleTimings(
     return {
       nextRun: nominalAt,
       nextRunEffectiveAt: effectiveAt,
-      lastRun: includeLastRun ? resolveLastRun(input, now, previousCache) : undefined,
+      lastRun: includeLastRun
+        ? resolveLastRun(input, now, nominalAt, phase, window, previousCache)
+        : undefined,
     };
   });
 }
 
 /**
- * Approximates "last run" from the cron's previous slot.
+ * Approximates "last run" from the most recent effective schedule time.
  *
- * Skips inactive schedules — the previous slot reflects what *would* have
- * fired. Skips slots that predate `updatedAt`: any config change (cron edited,
- * timezone changed, deactivate/reactivate) bumps `updatedAt`, and a slot from
- * before the most recent change didn't fire under the current configuration.
- *
- * `cron-parser` throws on malformed expressions, so this degrades to undefined
- * per row rather than failing the whole list. Best-effort by design; the runs
- * page is the source of truth.
+ * Skips inactive schedules and effective times that predate `updatedAt`. Best-effort by design;
+ * the runs page is the source of truth.
  */
 function resolveLastRun(
   input: ScheduleTimingInput,
   now: Date,
-  cache: Map<string, Date | undefined>
+  nextNominal: Date,
+  phase: number,
+  window: NormalizedScheduleWindow | undefined,
+  cache: Map<string, { latestNominal: Date; previousNominal?: Date } | undefined>
 ): Date | undefined {
   if (!input.active) {
     return undefined;
   }
 
   const key = cacheKey(input.cron, input.timezone);
+  let nominalTimes = cache.get(key);
 
-  let previous: Date | undefined;
-  if (cache.has(key)) {
-    previous = cache.get(key);
-  } else {
+  if (!cache.has(key)) {
     try {
-      previous = previousScheduledTimestamp(input.cron, input.timezone, now);
+      nominalTimes = {
+        latestNominal: previousScheduledTimestamp(
+          input.cron,
+          input.timezone,
+          new Date(now.getTime() + 1)
+        ),
+      };
     } catch {
-      previous = undefined;
+      nominalTimes = undefined;
     }
-    cache.set(key, previous);
+    cache.set(key, nominalTimes);
   }
 
-  if (!previous) {
+  if (!nominalTimes) {
     return undefined;
   }
 
-  return previous.getTime() > input.updatedAt.getTime() ? previous : undefined;
+  const latestEffective = calculateEffectiveScheduleTime({
+    nominalAt: nominalTimes.latestNominal,
+    nextNominalAt: nextNominal,
+    schedulePhase: phase,
+    window,
+    minimumWindowDurationSeconds: input.minimumWindowDurationSeconds,
+  }).effectiveAt;
+  if (latestEffective.getTime() <= now.getTime()) {
+    return latestEffective.getTime() > input.updatedAt.getTime() ? latestEffective : undefined;
+  }
+
+  if (!nominalTimes.previousNominal) {
+    nominalTimes.previousNominal = previousScheduledTimestamp(
+      input.cron,
+      input.timezone,
+      nominalTimes.latestNominal
+    );
+  }
+  const previousEffective = calculateEffectiveScheduleTime({
+    nominalAt: nominalTimes.previousNominal,
+    nextNominalAt: nominalTimes.latestNominal,
+    schedulePhase: phase,
+    window,
+    minimumWindowDurationSeconds: input.minimumWindowDurationSeconds,
+  }).effectiveAt;
+
+  return previousEffective.getTime() > input.updatedAt.getTime() ? previousEffective : undefined;
 }
 
 /**

apps/webapp/app/v3/services/createBackgroundWorker.server.test.ts

@@ -394,6 +394,7 @@ describe("syncDeclarativeSchedules registration", () => {
     async ({ prisma, redisOptions }) => {
       const { project, prodEnv } = await seedProjectWithEnvs(prisma);
       const schedule = await makeDeclarativeSchedule(prisma, project.id, [prodEnv.id]);
+      const updatedAt = schedule.updatedAt;
       await seedScheduledTask(prisma, project.id, prodEnv.id);
       const engine = createTestScheduleEngine(prisma, redisOptions);
 
@@ -412,6 +413,12 @@ describe("syncDeclarativeSchedules registration", () => {
 
         expect(before).toBeDefined();
         expect(await engine.getJob(jobId)).toEqual(before);
+        expect(
+          await prisma.taskSchedule.findUniqueOrThrow({
+            where: { id: schedule.id },
+            select: { updatedAt: true },
+          })
+        ).toEqual({ updatedAt });
       } finally {
         await engine.quit();
       }

apps/webapp/app/v3/services/createBackgroundWorker.server.ts

@@ -1399,6 +1399,7 @@ async function prepareDeclarativeSchedules(
       minimumWindowDurationSeconds: true,
       instances: {
         select: {
+          id: true,
           environmentId: true,
         },
       },
@@ -1537,21 +1538,29 @@ export async function syncDeclarativeSchedules(
         !scheduleWindowsEqual(previousWindow, nextWindow) ||
         // Clearing the minimum changes the effective range.
         existingSchedule.minimumWindowDurationSeconds !== minimumWindowDurationSeconds;
-      const schedule = await prisma.taskSchedule.update({
-        where: {
-          id: existingSchedule.id,
-        },
-        data: {
-          generatorExpression: task.schedule.cron,
-          generatorDescription: cronstrue.toString(task.schedule.cron),
-          timezone: task.schedule.timezone,
-          minimumWindowDurationSeconds,
-          ...normalizedWindow,
-        },
-        include: {
-          instances: true,
-        },
-      });
+      const persistedValuesChanged =
+        existingSchedule.generatorExpression !== task.schedule.cron ||
+        existingSchedule.timezone !== task.schedule.timezone ||
+        existingSchedule.windowDurationSeconds !== normalizedWindow.windowDurationSeconds ||
+        existingSchedule.windowPercentage !== normalizedWindow.windowPercentage ||
+        existingSchedule.minimumWindowDurationSeconds !== minimumWindowDurationSeconds;
+      const schedule = persistedValuesChanged
+        ? await prisma.taskSchedule.update({
+            where: {
+              id: existingSchedule.id,
+            },
+            data: {
+              generatorExpression: task.schedule.cron,
+              generatorDescription: cronstrue.toString(task.schedule.cron),
+              timezone: task.schedule.timezone,
+              minimumWindowDurationSeconds,
+              ...normalizedWindow,
+            },
+            include: {
+              instances: true,
+            },
+          })
+        : existingSchedule;
 
       missingSchedules.delete(existingSchedule.id);
       const instances = timingChanged

apps/webapp/test/scheduleTimings.test.ts

@@ -4,9 +4,9 @@ import {
   SCHEDULE_PHASE_DENOMINATOR,
   calculateEffectiveScheduleTime,
   calculateSchedulePhase,
+  resolveScheduleWindow,
 } from "@internal/schedule-engine";
 import { CronPattern } from "~/v3/schedules";
-import { type NormalizedScheduleWindow } from "@trigger.dev/core/v3";
 import { parseExpression } from "cron-parser";
 import { describe, expect, it } from "vitest";
 import {
@@ -77,24 +77,48 @@ function referenceResolve(
         deduplicationKey: input.deduplicationKey,
       });
 
-    const window: NormalizedScheduleWindow | undefined =
-      input.windowPercentage !== null
-        ? { type: "percentage", percentage: input.windowPercentage }
-        : input.windowDurationSeconds !== null
-          ? { type: "duration", durationSeconds: input.windowDurationSeconds }
-          : undefined;
+    const window = resolveScheduleWindow({
+      windowDurationSeconds: input.windowDurationSeconds,
+      windowPercentage: input.windowPercentage,
+      defaultWindowDurationSeconds: input.defaultWindowDurationSeconds,
+    }).window;
 
     const { effectiveAt } = calculateEffectiveScheduleTime({
       nominalAt: nominalTimes[0],
       nextNominalAt: nominalTimes[1],
       schedulePhase: phase,
       window,
+      minimumWindowDurationSeconds: input.minimumWindowDurationSeconds,
     });
 
     let lastRun: Date | undefined;
     if (includeLastRun && input.active) {
       try {
-        const previous = previousScheduledTimestamp(input.cron, input.timezone, now);
+        const latestNominal = previousScheduledTimestamp(
+          input.cron,
+          input.timezone,
+          new Date(now.getTime() + 1)
+        );
+        const previousNominal = previousScheduledTimestamp(
+          input.cron,
+          input.timezone,
+          latestNominal
+        );
+        const latestEffective = calculateEffectiveScheduleTime({
+          nominalAt: latestNominal,
+          nextNominalAt: nominalTimes[0],
+          schedulePhase: phase,
+          window,
+          minimumWindowDurationSeconds: input.minimumWindowDurationSeconds,
+        }).effectiveAt;
+        const previousEffective = calculateEffectiveScheduleTime({
+          nominalAt: previousNominal,
+          nextNominalAt: latestNominal,
+          schedulePhase: phase,
+          window,
+          minimumWindowDurationSeconds: input.minimumWindowDurationSeconds,
+        }).effectiveAt;
+        const previous = latestEffective <= now ? latestEffective : previousEffective;
         lastRun = previous.getTime() > input.updatedAt.getTime() ? previous : undefined;
       } catch {
         lastRun = undefined;
@@ -255,15 +279,24 @@ describe("resolveScheduleTimings", () => {
   });
 
   it("skips lastRun when the previous slot predates the last config change", () => {
-    const [stale] = resolveScheduleTimings([input({ cron: "0 0 * * *", updatedAt: now })], {
-      phaseSecret: PHASE_SECRET,
-      includeLastRun: true,
-      now,
-    });
+    const [stale] = resolveScheduleTimings(
+      [input({ cron: "0 0 * * *", schedulePhase: 0, updatedAt: now })],
+      {
+        phaseSecret: PHASE_SECRET,
+        includeLastRun: true,
+        now,
+      }
+    );
     expect(stale.lastRun).toBeUndefined();
 
     const [fresh] = resolveScheduleTimings(
-      [input({ cron: "0 0 * * *", updatedAt: new Date("2020-01-01T00:00:00.000Z") })],
+      [
+        input({
+          cron: "0 0 * * *",
+          schedulePhase: 0,
+          updatedAt: new Date("2020-01-01T00:00:00.000Z"),
+        }),
+      ],
       { phaseSecret: PHASE_SECRET, includeLastRun: true, now }
     );
     expect(fresh.lastRun).toEqual(new Date("2024-06-15T00:00:00.000Z"));
@@ -282,7 +315,7 @@ describe("resolveScheduleTimings", () => {
   });
 
   it("resolves lastRun for a valid expression", () => {
-    const [valid] = resolveScheduleTimings([input({ cron: "0 0 * * *" })], {
+    const [valid] = resolveScheduleTimings([input({ cron: "0 0 * * *", schedulePhase: 0 })], {
       phaseSecret: PHASE_SECRET,
       includeLastRun: true,
       now,
@@ -291,6 +324,56 @@ describe("resolveScheduleTimings", () => {
     expect(valid.lastRun).toEqual(new Date("2024-06-15T00:00:00.000Z"));
   });
 
+  it("resolves lastRun from the most recent effective window time", () => {
+    const [beforeCurrentWindow] = resolveScheduleTimings(
+      [
+        input({
+          cron: "0 * * * *",
+          schedulePhase: SCHEDULE_PHASE_DENOMINATOR / 2,
+          windowPercentage: 100,
+        }),
+      ],
+      {
+        phaseSecret: PHASE_SECRET,
+        includeLastRun: true,
+        now,
+      }
+    );
+    const [afterCurrentWindow] = resolveScheduleTimings(
+      [
+        input({
+          cron: "0 * * * *",
+          schedulePhase: SCHEDULE_PHASE_DENOMINATOR / 2,
+          windowPercentage: 100,
+        }),
+      ],
+      {
+        phaseSecret: PHASE_SECRET,
+        includeLastRun: true,
+        now: new Date("2024-06-15T09:40:00.000Z"),
+      }
+    );
+
+    expect(beforeCurrentWindow.lastRun).toEqual(new Date("2024-06-15T08:30:00.000Z"));
+    expect(afterCurrentWindow.lastRun).toEqual(new Date("2024-06-15T09:30:00.000Z"));
+  });
+
+  it("compares updatedAt with the effective window time", () => {
+    const [timing] = resolveScheduleTimings(
+      [
+        input({
+          cron: "0 * * * *",
+          schedulePhase: SCHEDULE_PHASE_DENOMINATOR / 2,
+          windowPercentage: 100,
+          updatedAt: new Date("2024-06-15T08:15:00.000Z"),
+        }),
+      ],
+      { phaseSecret: PHASE_SECRET, includeLastRun: true, now }
+    );
+
+    expect(timing.lastRun).toEqual(new Date("2024-06-15T08:30:00.000Z"));
+  });
+
   it("honours a caller-supplied schedulePhase over the derived one", () => {
     const rows = [input({ schedulePhase: 0, windowPercentage: 100, cron: "0 * * * *" })];