@sentry/junior-scheduler 0.74.1 → 0.76.0

package/src/store.ts

@@ -1,11 +1,27 @@
 import {
-  agentPluginCredentialSubjectSchema,
+  pluginCredentialSubjectSchema,
   destinationSchema,
   isSlackDestination,
-  type AgentPluginReadState,
-  type AgentPluginState,
+  type PluginReadState,
+  type PluginState,
 } from "@sentry/junior-plugin-api";
+import {
+  and,
+  asc,
+  eq,
+  inArray,
+  isNotNull,
+  lte,
+  ne,
+  or,
+  sql,
+} from "drizzle-orm";
+import type { PgDatabase } from "drizzle-orm/pg-core";
+import type { PgQueryResultHKT } from "drizzle-orm/pg-core/session";
+import { z } from "zod";
 import { getNextRunAtMs } from "./cadence";
+import * as schedulerSqlSchema from "./db/schema";
+import { juniorSchedulerRuns, juniorSchedulerTasks } from "./db/schema";
 import type { ScheduledRun, ScheduledTask } from "./types";
 
 const SCHEDULER_KEY_PREFIX = "junior:scheduler";
@@ -15,6 +31,105 @@ const CLAIM_TTL_MS = 6 * 60 * 60 * 1000;
 const PENDING_CLAIM_STALE_MS = 60_000;
 const MISSED_RUN_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 const LOCK_TTL_MS = 10_000;
+const SQL_INCOMPLETE_RUN_STATUSES = ["pending", "running"] as const;
+export type SchedulerDb = PgDatabase<
+  PgQueryResultHKT,
+  typeof schedulerSqlSchema
+>;
+const slackDestinationSchema = destinationSchema.refine(isSlackDestination);
+const taskPrincipalSchema = z
+  .object({
+    slackUserId: z.string(),
+    fullName: z.string().optional(),
+    userName: z.string().optional(),
+  })
+  .strict();
+const recurrenceSchema = z
+  .object({
+    dayOfMonth: z.number().optional(),
+    frequency: z.enum(["daily", "weekly", "monthly", "yearly"]),
+    interval: z.number(),
+    month: z.number().optional(),
+    startDate: z.string(),
+    time: z
+      .object({
+        hour: z.number(),
+        minute: z.number(),
+      })
+      .strict(),
+    weekdays: z.array(z.number()).optional(),
+  })
+  .strict();
+const taskScheduleSchema = z
+  .object({
+    description: z.string(),
+    kind: z.enum(["one_off", "recurring"]),
+    recurrence: recurrenceSchema.optional(),
+    timezone: z.string(),
+  })
+  .strict();
+const taskSpecSchema = z
+  .object({
+    text: z.string(),
+  })
+  .strict();
+const taskRecordSchema = z
+  .object({
+    id: z.string(),
+    conversationAccess: z
+      .object({
+        audience: z.enum(["direct", "group", "channel"]),
+        visibility: z.enum(["private", "public", "unknown"]),
+      })
+      .strict()
+      .optional(),
+    createdAtMs: z.number(),
+    createdBy: taskPrincipalSchema,
+    credentialSubject: pluginCredentialSubjectSchema.optional(),
+    destination: slackDestinationSchema,
+    executionActor: z
+      .object({
+        type: z.literal("system"),
+        id: z.string(),
+      })
+      .strict()
+      .optional(),
+    lastRunAtMs: z.number().optional(),
+    nextRunAtMs: z.number().optional(),
+    originalRequest: z.string().optional(),
+    runNowAtMs: z.number().optional(),
+    schedule: taskScheduleSchema,
+    status: z.enum(["active", "paused", "blocked", "deleted"]),
+    statusReason: z.string().optional(),
+    task: taskSpecSchema,
+    updatedAtMs: z.number(),
+    version: z.number().optional(),
+  })
+  .strict();
+const runRecordSchema = z
+  .object({
+    id: z.string(),
+    attempt: z.number(),
+    claimedAtMs: z.number(),
+    completedAtMs: z.number().optional(),
+    dispatchId: z.string().optional(),
+    errorMessage: z.string().optional(),
+    idempotencyKey: z.string().optional(),
+    resultMessageTs: z.string().optional(),
+    scheduledForMs: z.number(),
+    startedAtMs: z.number().optional(),
+    status: z.enum([
+      "pending",
+      "running",
+      "completed",
+      "failed",
+      "blocked",
+      "skipped",
+    ]),
+    taskId: z.string(),
+    taskVersion: z.number().optional(),
+  })
+  .strict();
 
 export interface SchedulerStore {
   claimDueRun(args: { nowMs: number }): Promise<ScheduledRun | undefined>;
@@ -107,7 +222,7 @@ function unique(values: string[]): string[] {
 }
 
 async function withLock<T>(
-  state: AgentPluginState,
+  state: PluginState,
   key: string,
   callback: () => Promise<T>,
 ): Promise<T> {
@@ -115,7 +230,7 @@ async function withLock<T>(
 }
 
 async function addToIndex(
-  state: AgentPluginState,
+  state: PluginState,
   key: string,
   taskId: string,
 ): Promise<void> {
@@ -128,7 +243,7 @@ async function addToIndex(
 }
 
 async function removeFromIndex(
-  state: AgentPluginState,
+  state: PluginState,
   key: string,
   taskId: string,
 ): Promise<void> {
@@ -151,7 +266,7 @@ async function removeFromIndex(
 }
 
 async function getIndex(
-  state: AgentPluginReadState,
+  state: PluginReadState,
   key: string,
 ): Promise<string[]> {
   const values = (await state.get<string[]>(key)) ?? [];
@@ -161,7 +276,7 @@ async function getIndex(
 }
 
 async function clearActiveRun(
-  state: AgentPluginState,
+  state: PluginState,
   taskId: string,
   runId: string,
 ): Promise<void> {
@@ -174,7 +289,7 @@ async function clearActiveRun(
 }
 
 async function clearStaleActiveRun(
-  state: AgentPluginState,
+  state: PluginState,
   taskId: string,
   nowMs: number,
 ): Promise<boolean> {
@@ -188,8 +303,7 @@ async function clearStaleActiveRun(
     return true;
   }
 
-  const activeRun =
-    (await state.get<ScheduledRun>(runKey(active.runId))) ?? undefined;
+  const activeRun = parseStoredRun(await state.get(runKey(active.runId)));
   if (!isStaleActiveRun(active, activeRun, nowMs)) {
     return false;
   }
@@ -276,16 +390,13 @@ function buildScheduledRun(args: {
   scheduledForMs: number;
   task: ScheduledTask;
 }): ScheduledRun {
-  const idempotencyKey = `${args.task.id}:${args.scheduledForMs}`;
   return {
     id: buildRunId(args.task.id, args.scheduledForMs),
     attempt: 1,
     claimedAtMs: args.claimedAtMs,
-    idempotencyKey,
     scheduledForMs: args.scheduledForMs,
     status: "pending",
     taskId: args.task.id,
-    taskVersion: args.task.version,
   };
 }
 
@@ -358,27 +469,55 @@ function canFinishRun(
   return run.status === "running" && run.startedAtMs === startedAtMs;
 }
 
+/** Decode retained scheduler task state, skipping invalid legacy records. */
 function parseStoredTask(value: unknown): ScheduledTask | undefined {
-  if (!value || typeof value !== "object") {
-    return undefined;
-  }
-  const record = value as Partial<ScheduledTask>;
-  const destination = destinationSchema.safeParse(record.destination);
-  if (!destination.success || !isSlackDestination(destination.data)) {
-    return undefined;
+  const parsed = taskRecordSchema.safeParse(parseJsonRecord(value));
+  return parsed.success ? stripLegacyTaskFields(parsed.data) : undefined;
+}
+
+/** Decode retained scheduler run state, skipping invalid legacy records. */
+function parseStoredRun(value: unknown): ScheduledRun | undefined {
+  const parsed = runRecordSchema.safeParse(parseJsonRecord(value));
+  return parsed.success ? stripLegacyRunFields(parsed.data) : undefined;
+}
+
+function stripLegacyTaskFields(
+  task: ScheduledTask & { version?: number },
+): ScheduledTask {
+  const { version: _version, ...current } = task;
+  return current;
+}
+
+function stripLegacyRunFields(
+  run: ScheduledRun & {
+    idempotencyKey?: string;
+    taskVersion?: number;
+  },
+): ScheduledRun {
+  const {
+    idempotencyKey: _idempotencyKey,
+    taskVersion: _taskVersion,
+    ...current
+  } = run;
+  return current;
+}
+
+function parseJsonRecord<T>(value: unknown): T | undefined {
+  if (typeof value === "string") {
+    try {
+      return JSON.parse(value) as T;
+    } catch {
+      return undefined;
+    }
   }
-  const credentialSubject =
-    record.credentialSubject === undefined
-      ? undefined
-      : agentPluginCredentialSubjectSchema.safeParse(record.credentialSubject);
-  if (credentialSubject && !credentialSubject.success) {
-    return undefined;
+  if (value && typeof value === "object") {
+    return value as T;
   }
-  return {
-    ...(record as ScheduledTask),
-    destination: destination.data,
-    ...(credentialSubject ? { credentialSubject: credentialSubject.data } : {}),
-  };
+  return undefined;
+}
+
+function present<T>(value: T | undefined): value is T {
+  return value !== undefined;
 }
 
 function requireStoredTask(task: ScheduledTask): ScheduledTask {
@@ -390,14 +529,14 @@ function requireStoredTask(task: ScheduledTask): ScheduledTask {
 }
 
 async function getTaskFromState(
-  state: AgentPluginReadState,
+  state: PluginReadState,
   taskId: string,
 ): Promise<ScheduledTask | undefined> {
   return parseStoredTask(await state.get(taskKey(taskId)));
 }
 
 async function listTasksFromState(
-  state: AgentPluginReadState,
+  state: PluginReadState,
   indexKey: string,
 ): Promise<ScheduledTask[]> {
   const ids = await getIndex(state, indexKey);
@@ -409,14 +548,14 @@ async function listTasksFromState(
 }
 
 async function getRunFromState(
-  state: AgentPluginReadState,
+  state: PluginReadState,
   runId: string,
 ): Promise<ScheduledRun | undefined> {
-  return (await state.get<ScheduledRun>(runKey(runId))) ?? undefined;
+  return parseStoredRun(await state.get(runKey(runId)));
 }
 
 async function listIncompleteRunsForTasksFromState(
-  state: AgentPluginReadState,
+  state: PluginReadState,
   tasks: ScheduledTask[],
 ): Promise<ScheduledRun[]> {
   const runs: ScheduledRun[] = [];
@@ -434,9 +573,9 @@ async function listIncompleteRunsForTasksFromState(
 }
 
 class PluginStateSchedulerOperationalStore implements SchedulerOperationalStore {
-  private readonly state: AgentPluginReadState;
+  private readonly state: PluginReadState;
 
-  constructor(state: AgentPluginReadState) {
+  constructor(state: PluginReadState) {
     this.state = state;
   }
 
@@ -452,9 +591,9 @@ class PluginStateSchedulerOperationalStore implements SchedulerOperationalStore
 }
 
 class PluginStateSchedulerStore implements SchedulerStore {
-  private readonly state: AgentPluginState;
+  private readonly state: PluginState;
 
-  constructor(state: AgentPluginState) {
+  constructor(state: PluginState) {
     this.state = state;
   }
 
@@ -648,7 +787,6 @@ class PluginStateSchedulerStore implements SchedulerStore {
           status: nextStatus,
           statusReason: nextStatus === "paused" ? errorMessage : undefined,
           updatedAtMs: args.nowMs,
-          version: current.version + 1,
         },
         current,
       );
@@ -834,7 +972,6 @@ class PluginStateSchedulerStore implements SchedulerStore {
             statusReason:
               args.status === "blocked" ? args.errorMessage : undefined,
             updatedAtMs: args.nowMs,
-            version: current.version + 1,
           },
           current,
         );
@@ -850,7 +987,6 @@ class PluginStateSchedulerStore implements SchedulerStore {
             ...current,
             lastRunAtMs: args.run.scheduledForMs,
             updatedAtMs: args.nowMs,
-            version: current.version + 1,
           },
           current,
         );
@@ -876,7 +1012,6 @@ class PluginStateSchedulerStore implements SchedulerStore {
           statusReason:
             args.status === "blocked" ? args.errorMessage : undefined,
           updatedAtMs: args.nowMs,
-          version: current.version + 1,
         },
         current,
       );
@@ -903,13 +1038,673 @@ class PluginStateSchedulerStore implements SchedulerStore {
 }
 
 /** Create a scheduler store backed by this plugin's durable state namespace. */
-export function createSchedulerStore(state: AgentPluginState): SchedulerStore {
+export function createSchedulerStore(state: PluginState): SchedulerStore {
   return new PluginStateSchedulerStore(state);
 }
 
 /** Create a read-only scheduler store for operational reporting. */
 export function createSchedulerOperationalStore(
-  state: AgentPluginReadState,
+  state: PluginReadState,
 ): SchedulerOperationalStore {
   return new PluginStateSchedulerOperationalStore(state);
 }
+
+type SchedulerTaskRow = {
+  record: unknown;
+};
+
+type SchedulerRunRow = {
+  record: unknown;
+};
+
+/** Decode scheduler SQL task records and reject rows unsafe for scan paths. */
+function parseSqlTaskRecord(value: unknown): ScheduledTask | undefined {
+  const parsed = taskRecordSchema.safeParse(parseJsonRecord(value));
+  return parsed.success ? stripLegacyTaskFields(parsed.data) : undefined;
+}
+
+function parseSqlTaskRow(row: SchedulerTaskRow): ScheduledTask | undefined {
+  return parseSqlTaskRecord(row.record);
+}
+
+/** Decode scheduler SQL run records and reject rows unsafe for scan paths. */
+function parseSqlRunRow(row: SchedulerRunRow): ScheduledRun | undefined {
+  const parsed = runRecordSchema.safeParse(parseJsonRecord(row.record));
+  return parsed.success ? stripLegacyRunFields(parsed.data) : undefined;
+}
+
+async function withSqlLock<T>(
+  db: SchedulerDb,
+  key: string,
+  callback: (db: SchedulerDb) => Promise<T>,
+): Promise<T> {
+  return await db.transaction(async (tx) => {
+    await tx.execute(sql`SELECT pg_advisory_xact_lock(hashtext(${key}))`);
+    return await callback(tx);
+  });
+}
+
+async function upsertSqlTask(
+  db: SchedulerDb,
+  task: ScheduledTask,
+): Promise<void> {
+  await db
+    .insert(juniorSchedulerTasks)
+    .values({
+      createdAtMs: task.createdAtMs,
+      id: task.id,
+      nextRunAtMs: task.nextRunAtMs,
+      record: task,
+      runNowAtMs: task.runNowAtMs,
+      status: task.status,
+      teamId: task.destination.teamId,
+    })
+    .onConflictDoUpdate({
+      target: juniorSchedulerTasks.id,
+      set: {
+        createdAtMs: sql`excluded.created_at_ms`,
+        nextRunAtMs: sql`excluded.next_run_at_ms`,
+        record: sql`excluded.record`,
+        runNowAtMs: sql`excluded.run_now_at_ms`,
+        status: sql`excluded.status`,
+        teamId: sql`excluded.team_id`,
+      },
+    });
+}
+
+async function upsertSqlRun(db: SchedulerDb, run: ScheduledRun): Promise<void> {
+  await db
+    .insert(juniorSchedulerRuns)
+    .values({
+      id: run.id,
+      record: run,
+      scheduledForMs: run.scheduledForMs,
+      status: run.status,
+      taskId: run.taskId,
+    })
+    .onConflictDoUpdate({
+      target: juniorSchedulerRuns.id,
+      set: {
+        record: sql`excluded.record`,
+        scheduledForMs: sql`excluded.scheduled_for_ms`,
+        status: sql`excluded.status`,
+        taskId: sql`excluded.task_id`,
+      },
+    });
+}
+
+async function getTaskFromSql(
+  db: SchedulerDb,
+  taskId: string,
+): Promise<ScheduledTask | undefined> {
+  const rows = await db
+    .select({ record: juniorSchedulerTasks.record })
+    .from(juniorSchedulerTasks)
+    .where(eq(juniorSchedulerTasks.id, taskId))
+    .limit(1);
+  return rows[0] ? parseSqlTaskRow(rows[0]) : undefined;
+}
+
+async function getRunFromSql(
+  db: SchedulerDb,
+  runId: string,
+): Promise<ScheduledRun | undefined> {
+  const rows = await db
+    .select({ record: juniorSchedulerRuns.record })
+    .from(juniorSchedulerRuns)
+    .where(eq(juniorSchedulerRuns.id, runId))
+    .limit(1);
+  return rows[0] ? parseSqlRunRow(rows[0]) : undefined;
+}
+
+async function listTasksFromSql(db: SchedulerDb): Promise<ScheduledTask[]> {
+  const rows = await db
+    .select({ record: juniorSchedulerTasks.record })
+    .from(juniorSchedulerTasks)
+    .where(ne(juniorSchedulerTasks.status, "deleted"))
+    .orderBy(
+      asc(juniorSchedulerTasks.createdAtMs),
+      asc(juniorSchedulerTasks.id),
+    );
+  return rows.map(parseSqlTaskRow).filter(present);
+}
+
+async function listTasksForTeamFromSql(
+  db: SchedulerDb,
+  teamId: string,
+): Promise<ScheduledTask[]> {
+  const rows = await db
+    .select({ record: juniorSchedulerTasks.record })
+    .from(juniorSchedulerTasks)
+    .where(
+      and(
+        eq(juniorSchedulerTasks.teamId, teamId),
+        ne(juniorSchedulerTasks.status, "deleted"),
+      ),
+    )
+    .orderBy(
+      asc(juniorSchedulerTasks.createdAtMs),
+      asc(juniorSchedulerTasks.id),
+    );
+  return rows.map(parseSqlTaskRow).filter(present);
+}
+
+async function listIncompleteRunsForTasksFromSql(
+  db: SchedulerDb,
+  tasks: ScheduledTask[],
+): Promise<ScheduledRun[]> {
+  if (tasks.length === 0) {
+    return [];
+  }
+  const rows = await db
+    .select({ record: juniorSchedulerRuns.record })
+    .from(juniorSchedulerRuns)
+    .where(
+      and(
+        inArray(
+          juniorSchedulerRuns.taskId,
+          tasks.map((task) => task.id),
+        ),
+        inArray(juniorSchedulerRuns.status, [...SQL_INCOMPLETE_RUN_STATUSES]),
+      ),
+    )
+    .orderBy(
+      asc(juniorSchedulerRuns.scheduledForMs),
+      asc(juniorSchedulerRuns.id),
+    );
+  return rows.map(parseSqlRunRow).filter(present);
+}
+
+class SqlSchedulerStore implements SchedulerStore, SchedulerOperationalStore {
+  constructor(private readonly db: SchedulerDb) {}
+
+  async saveTask(task: ScheduledTask): Promise<void> {
+    const next = requireStoredTask(task);
+    await withSqlLock(this.db, taskLockKey(task.id), async (db) => {
+      const current = await getTaskFromSql(db, task.id);
+      await this.saveTaskRecord(db, next, current);
+    });
+  }
+
+  private async saveTaskRecord(
+    db: SchedulerDb,
+    task: ScheduledTask,
+    current: ScheduledTask | undefined,
+  ): Promise<void> {
+    // Reactivation intentionally forgets the blocked slot so authorization or
+    // configuration fixes can dispatch the same scheduled occurrence again.
+    if (
+      current?.status === "blocked" &&
+      task.status === "active" &&
+      typeof task.nextRunAtMs === "number" &&
+      Number.isFinite(task.nextRunAtMs)
+    ) {
+      await db
+        .delete(juniorSchedulerRuns)
+        .where(
+          and(
+            eq(juniorSchedulerRuns.id, buildRunId(task.id, task.nextRunAtMs)),
+            eq(juniorSchedulerRuns.status, "blocked"),
+          ),
+        );
+    }
+    await upsertSqlTask(db, task);
+  }
+
+  async getTask(taskId: string): Promise<ScheduledTask | undefined> {
+    return await getTaskFromSql(this.db, taskId);
+  }
+
+  async listTasks(): Promise<ScheduledTask[]> {
+    return await listTasksFromSql(this.db);
+  }
+
+  async listTasksForTeam(teamId: string): Promise<ScheduledTask[]> {
+    return await listTasksForTeamFromSql(this.db, teamId);
+  }
+
+  async claimDueRun(args: {
+    nowMs: number;
+  }): Promise<ScheduledRun | undefined> {
+    return await withSqlLock(this.db, "junior:scheduler:claim", async (db) => {
+      const rows = await db
+        .select({ record: juniorSchedulerTasks.record })
+        .from(juniorSchedulerTasks)
+        .where(
+          and(
+            eq(juniorSchedulerTasks.status, "active"),
+            or(
+              and(
+                isNotNull(juniorSchedulerTasks.runNowAtMs),
+                lte(juniorSchedulerTasks.runNowAtMs, args.nowMs),
+              ),
+              and(
+                isNotNull(juniorSchedulerTasks.nextRunAtMs),
+                lte(juniorSchedulerTasks.nextRunAtMs, args.nowMs),
+              ),
+            ),
+          ),
+        )
+        .orderBy(
+          asc(juniorSchedulerTasks.createdAtMs),
+          asc(juniorSchedulerTasks.id),
+        );
+
+      for (const row of rows) {
+        const task = parseSqlTaskRow(row);
+        if (!task) {
+          continue;
+        }
+        const scheduledForMs = getDueRunAtMs(task, args.nowMs);
+        if (scheduledForMs === undefined) {
+          continue;
+        }
+        const runId = buildRunId(task.id, scheduledForMs);
+        const incompleteRuns = await listIncompleteRunsForTasksFromSql(db, [
+          task,
+        ]);
+        const incompleteRun = incompleteRuns.find((run) => run.id === runId);
+        const blockingRun = incompleteRuns.find(
+          (run) => run.id !== runId && !isStalePendingRun(run, args.nowMs),
+        );
+        if (blockingRun) {
+          continue;
+        }
+        if (incompleteRun) {
+          if (!isStalePendingRun(incompleteRun, args.nowMs)) {
+            continue;
+          }
+          const reclaimed = {
+            ...incompleteRun,
+            attempt: incompleteRun.attempt + 1,
+            claimedAtMs: args.nowMs,
+          };
+          await upsertSqlRun(db, reclaimed);
+          return reclaimed;
+        }
+        const existingRun = await getRunFromSql(db, runId);
+        if (existingRun) {
+          continue;
+        }
+
+        if (isMissedRunTooOld({ nowMs: args.nowMs, scheduledForMs })) {
+          await this.skipMissedRun(db, {
+            nowMs: args.nowMs,
+            scheduledForMs,
+            task,
+          });
+          continue;
+        }
+
+        const run = buildScheduledRun({
+          claimedAtMs: args.nowMs,
+          scheduledForMs,
+          task,
+        });
+        await upsertSqlRun(db, run);
+        return run;
+      }
+
+      return undefined;
+    });
+  }
+
+  private async skipMissedRun(
+    db: SchedulerDb,
+    args: {
+      nowMs: number;
+      scheduledForMs: number;
+      task: ScheduledTask;
+    },
+  ): Promise<void> {
+    const current = await getTaskFromSql(db, args.task.id);
+    if (
+      !current ||
+      current.status !== "active" ||
+      getDueRunAtMs(current, args.nowMs) !== args.scheduledForMs
+    ) {
+      return;
+    }
+
+    const duplicateOf = await this.findStaleRecoveryCanonicalTask(db, current);
+    const errorMessage = duplicateOf
+      ? `Duplicate stale scheduled task was skipped without dispatch. Canonical task: ${duplicateOf.id}.`
+      : "Scheduled occurrence was more than 24 hours late and was skipped without dispatch.";
+    await upsertSqlRun(
+      db,
+      buildSkippedScheduledRun({
+        completedAtMs: args.nowMs,
+        errorMessage,
+        scheduledForMs: args.scheduledForMs,
+        task: current,
+      }),
+    );
+
+    const isRunNow = current.runNowAtMs === args.scheduledForMs;
+    let nextRunAtMs: number | undefined;
+    if (!duplicateOf) {
+      nextRunAtMs =
+        isRunNow && current.nextRunAtMs !== args.scheduledForMs
+          ? current.nextRunAtMs
+          : current.schedule.kind === "recurring"
+            ? getNextRunAtMs(current, args.scheduledForMs, args.nowMs)
+            : undefined;
+    }
+    const nextStatus = nextRunAtMs ? "active" : "paused";
+
+    await this.saveTaskRecord(
+      db,
+      {
+        ...current,
+        nextRunAtMs,
+        runNowAtMs: isRunNow ? undefined : current.runNowAtMs,
+        status: nextStatus,
+        statusReason: nextStatus === "paused" ? errorMessage : undefined,
+        updatedAtMs: args.nowMs,
+      },
+      current,
+    );
+  }
+
+  private async findStaleRecoveryCanonicalTask(
+    db: SchedulerDb,
+    task: ScheduledTask,
+  ): Promise<ScheduledTask | undefined> {
+    const fingerprint = taskDedupeFingerprint(task);
+    const tasks = await listTasksForTeamFromSql(db, task.destination.teamId);
+    return tasks
+      .filter((candidate) => candidate.id !== task.id)
+      .filter(
+        (candidate) =>
+          candidate.status === "active" &&
+          isEarlierTask(candidate, task) &&
+          taskDedupeFingerprint(candidate) === fingerprint,
+      )
+      .sort((a, b) => a.createdAtMs - b.createdAtMs || a.id.localeCompare(b.id))
+      .at(0);
+  }
+
+  async getRun(runId: string): Promise<ScheduledRun | undefined> {
+    return await getRunFromSql(this.db, runId);
+  }
+
+  async listIncompleteRuns(): Promise<ScheduledRun[]> {
+    return await listIncompleteRunsForTasksFromSql(
+      this.db,
+      await this.listTasks(),
+    );
+  }
+
+  async listIncompleteRunsForTasks(
+    tasks: ScheduledTask[],
+  ): Promise<ScheduledRun[]> {
+    return await listIncompleteRunsForTasksFromSql(this.db, tasks);
+  }
+
+  async markRunDispatched(args: {
+    claimedAtMs: number;
+    dispatchId: string;
+    nowMs: number;
+    runId: string;
+  }): Promise<ScheduledRun | undefined> {
+    return await this.updateRun(args.runId, (run) =>
+      run.status === "pending" && run.claimedAtMs === args.claimedAtMs
+        ? {
+            ...run,
+            dispatchId: args.dispatchId,
+            startedAtMs: args.nowMs,
+            status: "running",
+          }
+        : undefined,
+    );
+  }
+
+  async markRunCompleted(args: {
+    completedAtMs: number;
+    resultMessageTs?: string;
+    runId: string;
+    startedAtMs: number;
+  }): Promise<ScheduledRun | undefined> {
+    const next = await this.updateRun(args.runId, (run) =>
+      canFinishRun(run, args.startedAtMs)
+        ? {
+            ...run,
+            completedAtMs: args.completedAtMs,
+            resultMessageTs: args.resultMessageTs,
+            status: "completed",
+          }
+        : undefined,
+    );
+    return next;
+  }
+
+  async markRunFailed(args: {
+    completedAtMs: number;
+    errorMessage: string;
+    startedAtMs?: number;
+    runId: string;
+  }): Promise<ScheduledRun | undefined> {
+    return await this.updateRun(args.runId, (run) =>
+      canFinishRun(run, args.startedAtMs)
+        ? {
+            ...run,
+            completedAtMs: args.completedAtMs,
+            errorMessage: args.errorMessage,
+            status: "failed",
+          }
+        : undefined,
+    );
+  }
+
+  async markRunSkipped(args: {
+    completedAtMs: number;
+    errorMessage: string;
+    runId: string;
+  }): Promise<ScheduledRun | undefined> {
+    return await this.updateRun(args.runId, (run) =>
+      run.status === "pending"
+        ? {
+            ...run,
+            completedAtMs: args.completedAtMs,
+            errorMessage: args.errorMessage,
+            status: "skipped",
+          }
+        : undefined,
+    );
+  }
+
+  async markRunBlocked(args: {
+    completedAtMs: number;
+    errorMessage: string;
+    runId: string;
+    startedAtMs?: number;
+  }): Promise<ScheduledRun | undefined> {
+    return await this.updateRun(args.runId, (run) =>
+      canFinishRun(run, args.startedAtMs)
+        ? {
+            ...run,
+            completedAtMs: args.completedAtMs,
+            errorMessage: args.errorMessage,
+            status: "blocked",
+          }
+        : undefined,
+    );
+  }
+
+  async updateTaskAfterRun(args: {
+    errorMessage?: string;
+    nowMs: number;
+    run: ScheduledRun;
+    status: "blocked" | "completed" | "failed";
+  }): Promise<void> {
+    await withSqlLock(this.db, taskLockKey(args.run.taskId), async (db) => {
+      const current = await getTaskFromSql(db, args.run.taskId);
+      if (!current || current.status === "deleted") {
+        return;
+      }
+
+      const isRunNow = current.runNowAtMs === args.run.scheduledForMs;
+      if (isRunNow) {
+        let nextRunAtMs = current.nextRunAtMs;
+        if (
+          args.status !== "blocked" &&
+          typeof current.nextRunAtMs === "number" &&
+          current.nextRunAtMs <= args.run.scheduledForMs
+        ) {
+          nextRunAtMs = getNextRunAtMs(
+            current,
+            current.nextRunAtMs,
+            args.nowMs,
+          );
+        }
+        await this.saveTaskRecord(
+          db,
+          {
+            ...current,
+            lastRunAtMs: args.run.scheduledForMs,
+            nextRunAtMs,
+            runNowAtMs: undefined,
+            status:
+              args.status === "blocked"
+                ? "blocked"
+                : nextRunAtMs
+                  ? current.status
+                  : "paused",
+            statusReason:
+              args.status === "blocked" ? args.errorMessage : undefined,
+            updatedAtMs: args.nowMs,
+          },
+          current,
+        );
+        return;
+      }
+
+      if (
+        current.status !== "active" ||
+        current.nextRunAtMs !== args.run.scheduledForMs
+      ) {
+        await this.saveTaskRecord(
+          db,
+          {
+            ...current,
+            lastRunAtMs: args.run.scheduledForMs,
+            updatedAtMs: args.nowMs,
+          },
+          current,
+        );
+        return;
+      }
+
+      const nextRunAtMs =
+        args.status === "blocked"
+          ? undefined
+          : getNextRunAtMs(current, args.run.scheduledForMs, args.nowMs);
+
+      await this.saveTaskRecord(
+        db,
+        {
+          ...current,
+          lastRunAtMs: args.run.scheduledForMs,
+          nextRunAtMs,
+          status:
+            args.status === "blocked"
+              ? "blocked"
+              : nextRunAtMs
+                ? "active"
+                : "paused",
+          statusReason:
+            args.status === "blocked" ? args.errorMessage : undefined,
+          updatedAtMs: args.nowMs,
+        },
+        current,
+      );
+    });
+  }
+
+  private async updateRun(
+    runId: string,
+    update: (run: ScheduledRun) => ScheduledRun | undefined,
+  ): Promise<ScheduledRun | undefined> {
+    return await withSqlLock(
+      this.db,
+      indexLockKey(runKey(runId)),
+      async (db) => {
+        const current = await getRunFromSql(db, runId);
+        if (!current) {
+          return undefined;
+        }
+        const next = update(current);
+        if (!next) {
+          return undefined;
+        }
+        await upsertSqlRun(db, next);
+        return next;
+      },
+    );
+  }
+}
+
+/** Create a scheduler store backed by the plugin SQL database. */
+export function createSchedulerSqlStore(db: SchedulerDb): SchedulerStore {
+  return new SqlSchedulerStore(db);
+}
+
+/** Create a read-only scheduler operational store backed by SQL. */
+export function createSchedulerOperationalSqlStore(
+  db: SchedulerDb,
+): SchedulerOperationalStore {
+  return new SqlSchedulerStore(db);
+}
+
+/** Copy retained scheduler plugin-state records into the scheduler SQL tables. */
+export async function migrateSchedulerStateToSql(args: {
+  db: SchedulerDb;
+  state: PluginState;
+}): Promise<{
+  existing: number;
+  migrated: number;
+  missing: number;
+  scanned: number;
+}> {
+  const store = createSchedulerSqlStore(args.db);
+  const ids = await getIndex(args.state, globalTaskIndexKey());
+  let existing = 0;
+  let migrated = 0;
+  let missing = 0;
+  const migratedTasks: ScheduledTask[] = [];
+
+  for (const id of ids) {
+    const task = await getTaskFromState(args.state, id);
+    if (!task) {
+      missing += 1;
+      continue;
+    }
+    migratedTasks.push(task);
+    if (await store.getTask(task.id)) {
+      existing += 1;
+      continue;
+    }
+    await store.saveTask(task);
+    migrated += 1;
+  }
+
+  const runs = await listIncompleteRunsForTasksFromState(
+    args.state,
+    migratedTasks,
+  );
+  for (const run of runs) {
+    if (await store.getRun(run.id)) {
+      existing += 1;
+      continue;
+    }
+    await upsertSqlRun(args.db, run);
+    migrated += 1;
+  }
+
+  return {
+    existing,
+    migrated,
+    missing,
+    scanned: ids.length + runs.length,
+  };
+}