feat(schedule-engine): stop persisting per-tick schedule state

Each scheduled-task tick previously issued 3 Prisma UPDATEs against
TaskSchedule.lastRunTriggeredAt, TaskScheduleInstance.lastScheduledTimestamp,
and TaskScheduleInstance.nextScheduledTimestamp. All three were pure
denormalization — every value can be derived without persisting.

Engine
- Drop the three per-tick prisma.update calls.
- Refactor registerNextTaskScheduleInstance to take a fromTimestamp arg
  instead of reading instance.lastScheduledTimestamp from the DB.
- Add optional lastScheduleTime to the schedule worker payload so the
  previous fire time travels forward via Redis. payload.lastTimestamp
  is now sourced from the worker payload, not a DB column. First-ever
  fires still report undefined so customer "first-run" sentinel
  patterns keep working.
- For in-flight Redis jobs enqueued before this change (which lack
  lastScheduleTime), fall back to instance.lastScheduledTimestamp once.
  After those drain, the column is never read again.

Schema
- Mark the three columns @deprecated via triple-slash Prisma docstrings.
  No migration — columns remain in place so revert is code-only. They
  can be dropped in a follow-up once the rollout is stable.

Webapp
- ScheduleListPresenter derives the dashboard "Last run" cell from the
  cron expression's previous slot, gated on schedule.createdAt so
  brand-new schedules show "–". UI is best-effort; runs page is the
  source of truth.
- API responses (api.v1.schedules.*) already compute nextRun from cron;
  no public API change. lastTimestamp on the SDK payload retains
  Date | undefined semantics — no SDK change either.

Tests
- scheduleEngine integration test asserts first-fire lastTimestamp is
  undefined and the second fire carries the previous fire's timestamp
  exactly.
- scheduleRecovery tests no longer assert against the deprecated
  nextScheduledTimestamp column; presence of the worker job is the
  source of truth.

References
- New references/scheduled-tasks project with declarative schedules at
  multiple cadences plus three validators (first-fire-detector,
  interval-validator, upcoming-validator) that throw on FAIL — used
  for E2E-verifying the worker-payload flow.

Refs TRI-8891

Author: ericallam

.server-changes/stop-persisting-schedule-tick-state.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: improvement
+---
+
+Stop writing per-tick state (`lastScheduledTimestamp`, `nextScheduledTimestamp`, `lastRunTriggeredAt`) on `TaskSchedule` and `TaskScheduleInstance`. The schedule engine now carries the previous fire time forward via the worker queue payload, eliminating ~270K dead-tuple-driven autovacuums per year on these hot tables and the associated `IO:XactSync` mini-spikes on the writer. Customer-facing `payload.lastTimestamp` semantics are unchanged.

apps/webapp/app/presenters/v3/ScheduleListPresenter.server.ts

@@ -6,7 +6,10 @@ import { getLimit } from "~/services/platform.v3.server";
 import { findCurrentWorkerFromEnvironment } from "~/v3/models/workerDeployment.server";
 import { ServiceValidationError } from "~/v3/services/baseService.server";
 import { CheckScheduleService } from "~/v3/services/checkSchedule.server";
-import { calculateNextScheduledTimestampFromNow } from "~/v3/utils/calculateNextSchedule.server";
+import {
+  calculateNextScheduledTimestampFromNow,
+  previousScheduledTimestamp,
+} from "~/v3/utils/calculateNextSchedule.server";
 import { BasePresenter } from "./basePresenter.server";
 
 type ScheduleListOptions = {
@@ -193,7 +196,6 @@ export class ScheduleListPresenter extends BasePresenter {
           },
         },
         active: true,
-        lastRunTriggeredAt: true,
         createdAt: true,
       },
       where: {
@@ -244,6 +246,16 @@ export class ScheduleListPresenter extends BasePresenter {
     });
 
     const schedules: ScheduleListItem[] = rawSchedules.map((schedule) => {
+      // Approximate "last run" from the cron's previous slot. If that slot
+      // predates the schedule itself, the schedule hasn't fired yet — show
+      // undefined rather than a misleading timestamp. UI is best-effort;
+      // accurate run history is on the schedule's runs page.
+      const cronPrev = previousScheduledTimestamp(
+        schedule.generatorExpression,
+        schedule.timezone
+      );
+      const lastRun = cronPrev.getTime() > schedule.createdAt.getTime() ? cronPrev : undefined;
+
       return {
         id: schedule.id,
         type: schedule.type,
@@ -256,7 +268,7 @@ export class ScheduleListPresenter extends BasePresenter {
         timezone: schedule.timezone,
         active: schedule.active,
         externalId: schedule.externalId,
-        lastRun: schedule.lastRunTriggeredAt ?? undefined,
+        lastRun,
         nextRun: calculateNextScheduledTimestampFromNow(
           schedule.generatorExpression,
           schedule.timezone

apps/webapp/app/v3/utils/calculateNextSchedule.server.ts

@@ -22,6 +22,20 @@ function calculateNextStep(schedule: string, timezone: string | null, currentDat
     .toDate();
 }
 
+export function previousScheduledTimestamp(
+  schedule: string,
+  timezone: string | null,
+  fromTimestamp: Date = new Date()
+) {
+  return parseExpression(schedule, {
+    currentDate: fromTimestamp,
+    utc: timezone === null,
+    tz: timezone ?? undefined,
+  })
+    .prev()
+    .toDate();
+}
+
 export function nextScheduledTimestamps(
   cron: string,
   timezone: string | null,

internal-packages/database/prisma/schema.prisma

@@ -2128,6 +2128,7 @@ model TaskSchedule {
   ///Instances of the schedule that are active
   instances TaskScheduleInstance[]
 
+  /// @deprecated stop writing 2026-04-30; reads moved out of code (UI now derives from cron's previous slot). Drop in follow-up.
   lastRunTriggeredAt DateTime?
 
   project   Project @relation(fields: [projectId], references: [id], onDelete: Cascade, onUpdate: Cascade)
@@ -2173,7 +2174,9 @@ model TaskScheduleInstance {
 
   active Boolean @default(true)
 
+  /// @deprecated stop writing 2026-04-30; engine derives from cron + exactScheduleTime. Drop in follow-up.
   lastScheduledTimestamp DateTime?
+  /// @deprecated stop writing 2026-04-30; engine derives from cron + now(). Drop in follow-up.
   nextScheduledTimestamp DateTime?
 
   //you can only have a schedule attached to each environment once

internal-packages/schedule-engine/src/engine/index.ts

@@ -171,13 +171,13 @@ export class ScheduleEngine {
           instance.taskSchedule.generatorExpression
         );
 
-        const lastScheduledTimestamp = instance.lastScheduledTimestamp ?? new Date();
-        span.setAttribute("last_scheduled_timestamp", lastScheduledTimestamp.toISOString());
+        const fromTimestamp = params.fromTimestamp ?? new Date();
+        span.setAttribute("from_timestamp", fromTimestamp.toISOString());
 
         const nextScheduledTimestamp = calculateNextScheduledTimestamp(
           instance.taskSchedule.generatorExpression,
           instance.taskSchedule.timezone,
-          lastScheduledTimestamp
+          fromTimestamp
         );
 
         span.setAttribute("next_scheduled_timestamp", nextScheduledTimestamp.toISOString());
@@ -194,17 +194,16 @@ export class ScheduleEngine {
           timezone: instance.taskSchedule.timezone,
         });
 
-        await this.prisma.taskScheduleInstance.update({
-          where: {
-            id: params.instanceId,
-          },
-          data: {
-            nextScheduledTimestamp,
-          },
-        });
-
-        // Enqueue the scheduled task
-        await this.enqueueScheduledTask(params.instanceId, nextScheduledTimestamp);
+        // Enqueue the scheduled task. Pass fromTimestamp through as the next
+        // job's lastScheduleTime so the dequeueing engine can populate
+        // payload.lastTimestamp without re-reading state from the DB. When
+        // fromTimestamp is undefined (first-ever registration / recovery),
+        // lastScheduleTime is also undefined → consumer reports undefined.
+        await this.enqueueScheduledTask(
+          params.instanceId,
+          nextScheduledTimestamp,
+          params.fromTimestamp
+        );
 
         // Record metrics
         this.scheduleRegistrationCounter.add(1, {
@@ -244,6 +243,7 @@ export class ScheduleEngine {
       instanceId: payload.instanceId,
       finalAttempt: false, // TODO: implement retry logic
       exactScheduleTime: payload.exactScheduleTime,
+      lastScheduleTime: payload.lastScheduleTime,
     });
   }
 
@@ -350,14 +350,6 @@ export class ScheduleEngine {
           skipReason = "schedule_inactive";
         }
 
-        if (!instance.nextScheduledTimestamp) {
-          this.logger.debug("No next scheduled timestamp", {
-            instanceId: params.instanceId,
-          });
-          shouldTrigger = false;
-          skipReason = "no_next_timestamp";
-        }
-
         // For development environments, check if there's an active session
         if (instance.environment.type === "DEVELOPMENT") {
           this.devEnvironmentCheckCounter.add(1, {
@@ -396,15 +388,26 @@ export class ScheduleEngine {
         }
 
         // Calculate the schedule timestamp that will be used (regardless of whether we trigger or not)
-        const scheduleTimestamp =
-          params.exactScheduleTime ?? instance.nextScheduledTimestamp ?? new Date();
+        const scheduleTimestamp = params.exactScheduleTime ?? new Date();
 
         if (shouldTrigger) {
+          // payload.lastTimestamp is the actual previous fire time. Sources, in
+          // order:
+          //   1. params.lastScheduleTime — populated by the engine when this
+          //      job was enqueued. Always present for jobs enqueued post-deploy.
+          //   2. instance.lastScheduledTimestamp — backward-compat fallback for
+          //      in-flight Redis jobs enqueued by older engines that didn't
+          //      include lastScheduleTime in the payload. Once those drain
+          //      this fallback never triggers and we can drop the column.
+          //   3. undefined — first-ever fire (no previous fire to point at).
+          const lastTimestamp =
+            params.lastScheduleTime ?? instance.lastScheduledTimestamp ?? undefined;
+
           const payload = {
             scheduleId: instance.taskSchedule.friendlyId,
             type: instance.taskSchedule.type as "DECLARATIVE" | "IMPERATIVE",
             timestamp: scheduleTimestamp,
-            lastTimestamp: instance.lastScheduledTimestamp ?? undefined,
+            lastTimestamp,
             externalId: instance.taskSchedule.externalId ?? undefined,
             timezone: instance.taskSchedule.timezone,
             upcoming: nextScheduledTimestamps(
@@ -428,7 +431,7 @@ export class ScheduleEngine {
             scheduleTimestamp: scheduleTimestamp.toISOString(),
             actualExecutionTime: actualExecutionTime.toISOString(),
             schedulingAccuracyMs,
-            lastTimestamp: instance.lastScheduledTimestamp?.toISOString(),
+            lastTimestamp: lastTimestamp?.toISOString(),
           });
 
           const triggerStartTime = Date.now();
@@ -473,16 +476,6 @@ export class ScheduleEngine {
             );
           } else if (result) {
             if (result.success) {
-              // Update the last run triggered timestamp
-              await this.prisma.taskSchedule.update({
-                where: {
-                  id: instance.taskSchedule.id,
-                },
-                data: {
-                  lastRunTriggeredAt: new Date(),
-                },
-              });
-
               this.logger.info("Successfully triggered scheduled task", {
                 instanceId: params.instanceId,
                 taskIdentifier: instance.taskSchedule.taskIdentifier,
@@ -542,20 +535,14 @@ export class ScheduleEngine {
           });
         }
 
-        // Always update the last scheduled timestamp and register next run
-        await this.prisma.taskScheduleInstance.update({
-          where: {
-            id: params.instanceId,
-          },
-          data: {
-            lastScheduledTimestamp: scheduleTimestamp,
-          },
-        });
-
-        // Register the next run
+        // Register the next run, calculating from the timestamp we just fired (or
+        // skipped) so we don't need to round-trip through DB state.
         // Rewritten try/catch to use tryCatch utility
         const [nextRunError] = await tryCatch(
-          this.registerNextTaskScheduleInstance({ instanceId: params.instanceId })
+          this.registerNextTaskScheduleInstance({
+            instanceId: params.instanceId,
+            fromTimestamp: scheduleTimestamp,
+          })
         );
         if (nextRunError) {
           this.logger.error("Failed to schedule next run after execution", {
@@ -610,10 +597,17 @@ export class ScheduleEngine {
   /**
    * Enqueues a scheduled task with distributed execution timing
    */
-  private async enqueueScheduledTask(instanceId: string, exactScheduleTime: Date) {
+  private async enqueueScheduledTask(
+    instanceId: string,
+    exactScheduleTime: Date,
+    lastScheduleTime?: Date
+  ) {
     return startSpan(this.tracer, "enqueueScheduledTask", async (span) => {
       span.setAttribute("instanceId", instanceId);
       span.setAttribute("exactScheduleTime", exactScheduleTime.toISOString());
+      if (lastScheduleTime) {
+        span.setAttribute("lastScheduleTime", lastScheduleTime.toISOString());
+      }
 
       const distributedExecutionTime = calculateDistributedExecutionTime(
         exactScheduleTime,
@@ -646,6 +640,7 @@ export class ScheduleEngine {
           payload: {
             instanceId,
             exactScheduleTime,
+            lastScheduleTime,
           },
           availableAt: distributedExecutionTime,
         });
@@ -698,8 +693,6 @@ export class ScheduleEngine {
             select: {
               id: true,
               environmentId: true,
-              lastScheduledTimestamp: true,
-              nextScheduledTimestamp: true,
             },
           },
         },
@@ -774,8 +767,6 @@ export class ScheduleEngine {
     instance: {
       id: string;
       environmentId: string;
-      lastScheduledTimestamp: Date | null;
-      nextScheduledTimestamp: Date | null;
     };
     schedule: { id: string; generatorExpression: string };
   }) {

internal-packages/schedule-engine/src/engine/types.ts

@@ -74,8 +74,10 @@ export interface TriggerScheduleParams {
   instanceId: string;
   finalAttempt: boolean;
   exactScheduleTime?: Date;
+  lastScheduleTime?: Date;
 }
 
 export interface RegisterScheduleInstanceParams {
   instanceId: string;
+  fromTimestamp?: Date;
 }

internal-packages/schedule-engine/src/engine/workerCatalog.ts

@@ -5,6 +5,11 @@ export const scheduleWorkerCatalog = {
     schema: z.object({
       instanceId: z.string(),
       exactScheduleTime: z.coerce.date(),
+      // Optional for backward compat with in-flight jobs enqueued by older
+      // engines. After deploy, every newly-enqueued job populates this with
+      // the just-fired schedule time so the next dequeue can report
+      // payload.lastTimestamp accurately without a DB round-trip.
+      lastScheduleTime: z.coerce.date().optional(),
     }),
     visibilityTimeoutMs: 60_000,
     retry: {