@softure-ai/jobs 0.1.0 → 0.1.2

package/dist/worker/run-job-worker.js

@@ -1,6 +1,6 @@
-// The worker loop: claims due jobs of every queue it has a handler for, up to each queue's concurrency, runs them,
-// keeps their leases alive, prunes old jobs once an hour, and on abort stops claiming, waits the grace period and
-// releases what is still running.
+// The worker loop: enqueues the due runs of the schedules among its queues, claims due jobs of every queue it has a
+// handler for, up to each queue's concurrency, runs them, keeps their leases alive, prunes old jobs once an hour, and
+// on abort stops claiming, waits the grace period and releases what is still running.
 import { hostname } from "node:os";
 import { systemClock } from "@softure-ai/core";
 import { claimJobs, extendJobLease, releaseJob } from "../server/claim.js";
@@ -9,6 +9,7 @@ import { consoleJobsLogger } from "../server/logger.js";
 import { pruneJobs } from "../server/maintenance.js";
 import { getJobsOptions, getQueue } from "../server/options.js";
 import { runClaimedJob } from "../server/process.js";
+import { enqueueScheduledRun, getSchedule, getScheduleNames, getScheduleSlot } from "../server/schedules.js";
 const PRUNE_INTERVAL_MS = 60 * 60 * 1000;
 /** A lease is extended three times per lease period, so one slow write does not lose it. */
 const HEARTBEATS_PER_LEASE = 3;
@@ -30,6 +31,9 @@ export async function runJobWorker(options) {
     const running = new Map(queues.map((queue) => [queue, new Set()]));
     const wakeUp = createWakeUp();
     let lastPruneAt = Number.NEGATIVE_INFINITY;
+    // Per schedule, the latest period this worker already settled (enqueued, or found taken), so it writes once per period.
+    const settledSlots = new Map();
+    const scheduleNames = getScheduleNames(jobsOptions, queues);
     const idle = Object.keys(jobsOptions.queues).filter((queue) => !queues.includes(queue));
     if (idle.length > 0 && options.queues === undefined) {
         logger.warn("configured queues without a handler are not run by this worker", { queues: idle.join(", ") });
@@ -60,6 +64,20 @@ export async function runJobWorker(options) {
         return entry;
     };
     while (!options.signal.aborted) {
+        for (const name of scheduleNames) {
+            const slot = getScheduleSlot(getSchedule(jobsOptions, name), ctx.clock.now());
+            if ((settledSlots.get(name) ?? Number.NEGATIVE_INFINITY) >= slot.getTime())
+                continue;
+            try {
+                const isEnqueued = await enqueueScheduledRun(ctx, name, slot);
+                settledSlots.set(name, slot.getTime());
+                if (isEnqueued)
+                    logger.info("scheduled run enqueued", { queue: name, slot: slot.toISOString() });
+            }
+            catch (error) {
+                logger.error("could not enqueue a scheduled run; trying again next round", { queue: name, error });
+            }
+        }
         for (const queue of queues) {
             const slots = running.get(queue) ?? new Set();
             const free = getQueue(jobsOptions, queue).concurrency - slots.size;

package/dist/worker/run-job-worker.js.map

@@ -1 +1 @@
-{"version":3,"file":"run-job-worker.js","sourceRoot":"","sources":["../../src/worker/run-job-worker.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"run-job-worker.js","sourceRoot":"","sources":["../../src/worker/run-job-worker.ts"],"names":[],"mappings":"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"}

package/dist/zoned-time.d.ts

@@ -0,0 +1,19 @@
+/** A date and a time of day as a clock in some time zone shows them; `month` counts from 1. */
+export interface WallClock {
+    readonly year: number;
+    readonly month: number;
+    readonly day: number;
+    readonly hour: number;
+    readonly minute: number;
+}
+/** True when `timeZone` is an IANA zone the runtime knows, such as `Europe/Warsaw` or `UTC`. */
+export declare function isTimeZone(timeZone: string): boolean;
+/** The wall clock of `instant` in `timeZone`, to the minute. */
+export declare function getWallClock(instant: number, timeZone: string): WallClock;
+/**
+ * The instant a clock in `timeZone` shows `wallClock`. A time that occurs twice (the hour a DST change repeats) gives
+ * its first occurrence; a time that does not occur (the hour a DST change skips) gives the instant the same distance
+ * after the change, so 02:30 on a day that jumps from 02:00 to 03:00 gives 03:30.
+ */
+export declare function getZonedInstant(wallClock: WallClock, timeZone: string): number;
+//# sourceMappingURL=zoned-time.d.ts.map

package/dist/zoned-time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zoned-time.d.ts","sourceRoot":"","sources":["../src/zoned-time.ts"],"names":[],"mappings":"AAKA,+FAA+F;AAC/F,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,gGAAgG;AAChG,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAOpD;AAED,gEAAgE;AAChE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,CASzE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAO9E"}

package/dist/zoned-time.js

@@ -0,0 +1,61 @@
+// Wall-clock time in an IANA time zone, with the platform's Intl data and no date library.
+const HOUR_MS = 60 * 60 * 1000;
+const formatters = new Map();
+/** True when `timeZone` is an IANA zone the runtime knows, such as `Europe/Warsaw` or `UTC`. */
+export function isTimeZone(timeZone) {
+    try {
+        getFormatter(timeZone);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The wall clock of `instant` in `timeZone`, to the minute. */
+export function getWallClock(instant, timeZone) {
+    const parts = Object.fromEntries(getFormatter(timeZone).formatToParts(new Date(instant)).map((part) => [part.type, part.value]));
+    return {
+        year: Number(parts.year),
+        month: Number(parts.month),
+        day: Number(parts.day),
+        hour: Number(parts.hour),
+        minute: Number(parts.minute),
+    };
+}
+/**
+ * The instant a clock in `timeZone` shows `wallClock`. A time that occurs twice (the hour a DST change repeats) gives
+ * its first occurrence; a time that does not occur (the hour a DST change skips) gives the instant the same distance
+ * after the change, so 02:30 on a day that jumps from 02:00 to 03:00 gives 03:30.
+ */
+export function getZonedInstant(wallClock, timeZone) {
+    const asUtc = toUtcMs(wallClock);
+    // One DST change a day at most: the offsets half a day before and after cover both sides of it.
+    const offsetBefore = getOffsetMs(asUtc - 12 * HOUR_MS, timeZone);
+    const offsetAfter = getOffsetMs(asUtc + 12 * HOUR_MS, timeZone);
+    const matching = [asUtc - offsetBefore, asUtc - offsetAfter].filter((instant) => toUtcMs(getWallClock(instant, timeZone)) === asUtc);
+    return matching.length > 0 ? Math.min(...matching) : asUtc - offsetBefore;
+}
+function getOffsetMs(instant, timeZone) {
+    const minute = Math.floor(instant / 60_000) * 60_000;
+    return toUtcMs(getWallClock(minute, timeZone)) - minute;
+}
+function toUtcMs(wallClock) {
+    return Date.UTC(wallClock.year, wallClock.month - 1, wallClock.day, wallClock.hour, wallClock.minute);
+}
+function getFormatter(timeZone) {
+    let formatter = formatters.get(timeZone);
+    if (formatter === undefined) {
+        formatter = new Intl.DateTimeFormat("en-US", {
+            timeZone,
+            hourCycle: "h23",
+            year: "numeric",
+            month: "numeric",
+            day: "numeric",
+            hour: "numeric",
+            minute: "numeric",
+        });
+        formatters.set(timeZone, formatter);
+    }
+    return formatter;
+}
+//# sourceMappingURL=zoned-time.js.map

package/dist/zoned-time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zoned-time.js","sourceRoot":"","sources":["../src/zoned-time.ts"],"names":[],"mappings":"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"}

package/migrations/0002_create_schedules.sql

@@ -0,0 +1,12 @@
+-- Recurring schedules: per schedule the last period a worker enqueued a run for, and when a run last succeeded.
+-- Rollback: DROP TABLE jobs.schedules; then
+--   DELETE FROM softure.migrations WHERE module = 'jobs' AND version = 2;
+CREATE TABLE schedules (
+  -- The schedule's queue.
+  name text PRIMARY KEY CHECK (name ~ '^[a-z][a-z0-9_.-]{0,62}$'),
+  -- The start of the latest period a run was enqueued for; a worker takes a period only when it is later than this.
+  last_slot_at timestamptz NOT NULL,
+  last_succeeded_at timestamptz,
+  created_at timestamptz NOT NULL,
+  updated_at timestamptz NOT NULL
+);

package/module.json

@@ -1,9 +1,9 @@
 {
   "id": "jobs",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "dependsOn": {},
   "dbSchema": "jobs",
-  "tables": ["jobs"],
+  "tables": ["jobs", "schedules"],
   "env": [],
   "switches": [],
   "routes": {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softure-ai/jobs",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "SOFTURE AI jobs module: background jobs in Postgres. Enqueue inside the caller's transaction with an optional dedup key, claim with FOR UPDATE SKIP LOCKED under a lease, fenced completion, retry with exponential backoff and a terminal failed state, a worker process with graceful shutdown, and an in-process runner for tests.",
   "license": "MIT",
   "type": "module",

package/src/index.ts

@@ -15,10 +15,10 @@ export const MODULE_ID = "jobs";
 export const jobs = defineModule({
   manifest: {
     id: MODULE_ID,
-    version: "0.1.0",
+    version: "0.1.2",
     dependsOn: {},
     dbSchema: "jobs",
-    tables: ["jobs"],
+    tables: ["jobs", "schedules"],
     env: [],
     switches: [],
     routes: {},
@@ -40,6 +40,15 @@ export {
   type JobStatus,
 } from "./contract.js";
 export { jobsMessages, type JobsMessages } from "./messages/index.js";
-export { jobsOptionsSchema, type JobQueueOptions, type JobsOptions, type JobsOptionsInput } from "./options.js";
+export {
+  jobsOptionsSchema,
+  type JobQueueOptions,
+  type JobScheduleOptions,
+  type JobSchedulesInput,
+  type JobsOptions,
+  type JobsOptionsInput,
+  type LocalTimeScheduleOptions,
+  type PeriodScheduleOptions,
+} from "./options.js";
 export { defineJobHandler, failJob, retryJobLater, type JobHandler, type JobHandlerContext, type JobHandlers } from "./handlers.js";
-export { jobs as jobsTable } from "./schema.js";
+export { jobs as jobsTable, schedules as jobSchedulesTable } from "./schema.js";

package/src/options.ts

@@ -1,5 +1,6 @@
 // The options an app passes to `jobs({ ... })` in softure.config.ts, parsed at startup.
 import { z } from "zod";
+import { isTimeZone } from "./zoned-time.js";
 
 const QUEUE_NAME = /^[a-z][a-z0-9_.-]{0,62}$/;
 const QUEUE_NAME_HINT = "is not a queue name: lowercase letters, digits, _ . and -, starting with a letter";
@@ -7,15 +8,80 @@ const DAY_SECONDS = 24 * 60 * 60;
 
 const backoffSchema = z
   .strictObject({
-    /** Delay before the second attempt; each later one doubles it. */
-    baseSeconds: z.number().int().min(1).max(DAY_SECONDS).default(10),
-    /** The longest delay between two attempts. */
-    maxSeconds: z.number().int().min(1).max(7 * DAY_SECONDS).default(3600),
-  })
-  .refine((backoff) => backoff.maxSeconds >= backoff.baseSeconds, {
-    message: "maxSeconds must be at least baseSeconds",
-    path: ["maxSeconds"],
-  });
+      /** Delay before the second attempt; each later one doubles it. */
+      baseSeconds: z.number().int().min(1).max(DAY_SECONDS).default(10),
+      /** The longest delay between two attempts. */
+      maxSeconds: z.number().int().min(1).max(7 * DAY_SECONDS).default(3600),
+    })
+    .refine((backoff) => backoff.maxSeconds >= backoff.baseSeconds, {
+      message: "maxSeconds must be at least baseSeconds",
+      path: ["maxSeconds"],
+    });
+
+  const EVERY = /^([1-9][0-9]{0,4})(m|h|d)$/;
+  const UNIT_SECONDS = { m: 60, h: 60 * 60, d: DAY_SECONDS } as const;
+  const MAX_EVERY_SECONDS = 7 * DAY_SECONDS;
+  const EVERY_HINT = "must be a whole number of minutes, hours or days (e.g. 15m, 1h, 1d), from 1m to 7d";
+
+  /** Seconds of an `every` text such as `15m`, `1h` or `1d`; null when it is not one or is outside 1m to 7d. */
+  export function parseEverySeconds(every: string): number | null {
+    const match = EVERY.exec(every);
+    if (match === null) return null;
+    const seconds = Number(match[1]) * UNIT_SECONDS[match[2] as keyof typeof UNIT_SECONDS];
+    return seconds <= MAX_EVERY_SECONDS ? seconds : null;
+  }
+
+  const AT_TIME = /^([01][0-9]|2[0-3]):[0-5][0-9]$/;
+  const AT_HINT = "must be times of day as HH:MM (00:00 to 23:59), each once";
+  const MAX_AT_TIMES = 48;
+
+  const scheduleSchema = z
+    .strictObject({
+      /** How often the schedule runs: `15m`, `1h`, `1d`. Runs start on whole periods counted from 1970-01-01 00:00 UTC. */
+      every: z.string().refine((every) => parseEverySeconds(every) !== null, { message: EVERY_HINT }).optional(),
+      /** Instead of `every`: the local times of day the schedule runs at, `HH:MM`, in `timeZone`. */
+      at: z
+        .array(z.string().regex(AT_TIME, { message: AT_HINT }))
+        .min(1)
+        .max(MAX_AT_TIMES)
+        .refine((times) => new Set(times).size === times.length, { message: AT_HINT })
+        .optional(),
+      /** The IANA time zone of `at`, such as `Europe/Warsaw`; required with `at`. */
+      timeZone: z.string().refine(isTimeZone, { message: "is not a time zone the runtime knows (an IANA name such as Europe/Warsaw)" }).optional(),
+      /** The payload of every run; default `{}`. */
+      payload: z.record(z.string(), z.unknown()).default({}),
+    })
+    .superRefine((schedule, context) => {
+      if ((schedule.every === undefined) === (schedule.at === undefined)) {
+        context.addIssue({ code: "custom", path: ["every"], message: "set either every or at, not both" });
+      }
+      if (schedule.at !== undefined && schedule.timeZone === undefined) {
+        context.addIssue({ code: "custom", path: ["timeZone"], message: "is required with at" });
+      }
+      if (schedule.every !== undefined && schedule.timeZone !== undefined) {
+        context.addIssue({ code: "custom", path: ["timeZone"], message: "applies to at only; every runs in UTC" });
+      }
+    })
+    .transform((schedule): PeriodScheduleOptions | LocalTimeScheduleOptions => {
+      if (schedule.at !== undefined && schedule.timeZone !== undefined) {
+        return { at: [...schedule.at].sort(), timeZone: schedule.timeZone, payload: schedule.payload };
+      }
+      // The refinement above leaves every set whenever at is not.
+      return { every: schedule.every ?? "", payload: schedule.payload };
+    });
+
+/** A schedule that runs once per period, aligned to UTC. */
+export interface PeriodScheduleOptions {
+  readonly every: string;
+  readonly payload: Record<string, unknown>;
+}
+
+/** A schedule that runs at local times of day in a time zone; `at` is sorted. */
+export interface LocalTimeScheduleOptions {
+  readonly at: readonly string[];
+  readonly timeZone: string;
+  readonly payload: Record<string, unknown>;
+}
 
 const queueSchema = z.strictObject({
   /** Attempts before a job is `failed` for good; the first run counts. */
@@ -40,25 +106,42 @@ const retentionSchema = z.strictObject({
   cancelledDays: z.number().int().min(0).max(3650).default(7),
 });
 
-export const jobsOptionsSchema = z.strictObject({
-  /** The queues, by name. A job is enqueued to one of them and runs with its settings. */
-  queues: z.record(z.string(), queueSchema).superRefine((queues, context) => {
-    const names = Object.keys(queues);
-    if (names.length === 0) {
-      context.addIssue({ code: "custom", message: "must define at least one queue" });
-    }
-    for (const name of names.filter((candidate) => !QUEUE_NAME.test(candidate))) {
-      context.addIssue({ code: "custom", path: [name], message: QUEUE_NAME_HINT });
+export const jobsOptionsSchema = z
+  .strictObject({
+    /** The queues, by name. A job is enqueued to one of them and runs with its settings. */
+    queues: z.record(z.string(), queueSchema).default({}).superRefine(checkNames),
+    /**
+     * Recurring runs, by queue name: the worker enqueues one job per period (`every`) or per local time of day (`at`
+     * in `timeZone`) however many workers run. A schedule's queue takes the default queue settings unless `queues`
+     * names it.
+     */
+    schedules: z.record(z.string(), scheduleSchema).default({}).superRefine(checkNames),
+    /** How long an idle worker waits before it looks for due jobs again. */
+    pollIntervalMs: z.number().int().min(50).max(60_000).default(1000),
+    /** How long a stopping worker waits for running handlers before it releases their jobs. */
+    shutdownGraceMs: z.number().int().min(0).max(10 * 60_000).default(20_000),
+    /** How long finished jobs are kept; the worker prunes once an hour. */
+    retention: retentionSchema.default({ succeededDays: 7, failedDays: 30, cancelledDays: 7 }),
+  })
+  .superRefine((options, context) => {
+    if (Object.keys(options.queues).length === 0 && Object.keys(options.schedules).length === 0) {
+      context.addIssue({ code: "custom", path: ["queues"], message: "must define at least one queue or schedule" });
     }
-  }),
-  /** How long an idle worker waits before it looks for due jobs again. */
-  pollIntervalMs: z.number().int().min(50).max(60_000).default(1000),
-  /** How long a stopping worker waits for running handlers before it releases their jobs. */
-  shutdownGraceMs: z.number().int().min(0).max(10 * 60_000).default(20_000),
-  /** How long finished jobs are kept; the worker prunes once an hour. */
-  retention: retentionSchema.default({ succeededDays: 7, failedDays: 30, cancelledDays: 7 }),
-});
+  })
+  .transform((options) => {
+    const scheduledOnly = Object.keys(options.schedules).filter((name) => !Object.hasOwn(options.queues, name));
+    return { ...options, queues: { ...options.queues, ...Object.fromEntries(scheduledOnly.map((name) => [name, queueSchema.parse({})])) } };
+  });
+
+function checkNames(record: Record<string, unknown>, context: z.RefinementCtx): void {
+  for (const name of Object.keys(record).filter((candidate) => !QUEUE_NAME.test(candidate))) {
+    context.addIssue({ code: "custom", path: [name], message: QUEUE_NAME_HINT });
+  }
+}
 
 export type JobsOptionsInput = z.input<typeof jobsOptionsSchema>;
 export type JobsOptions = z.output<typeof jobsOptionsSchema>;
 export type JobQueueOptions = JobsOptions["queues"][string];
+export type JobScheduleOptions = JobsOptions["schedules"][string];
+/** Schedules as an app or a package writes them, e.g. a package's ready-made prune schedules. */
+export type JobSchedulesInput = NonNullable<JobsOptionsInput["schedules"]>;

package/src/schema.ts

@@ -1,4 +1,4 @@
-// Drizzle view of the module's table (migrations/0001_create_jobs.sql). The migration is the source of truth; this
+// Drizzle view of the module's tables (migrations/). The migrations are the source of truth; this
 // file only types the queries.
 import { bigint, integer, jsonb, pgSchema, text, timestamp, uuid } from "drizzle-orm/pg-core";
 
@@ -23,3 +23,11 @@ export const jobs = jobsSchema.table("jobs", {
 });
 
 export type JobRow = typeof jobs.$inferSelect;
+
+export const schedules = jobsSchema.table("schedules", {
+  name: text("name").primaryKey(),
+  lastSlotAt: timestamp("last_slot_at", { withTimezone: true }).notNull(),
+  lastSucceededAt: timestamp("last_succeeded_at", { withTimezone: true }),
+  createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).notNull(),
+});

package/src/server/claim.ts

@@ -6,6 +6,7 @@ import { jobs } from "../schema.js";
 import type { JobsContext } from "./context.js";
 import { toJob } from "./job-row.js";
 import { getJobsOptions, getQueue } from "./options.js";
+import { recordScheduleSuccess } from "./schedules.js";
 
 /** A job this worker holds: the job and the token its writes are fenced with. */
 export interface ClaimedJob {
@@ -87,7 +88,10 @@ export async function extendJobLease(ctx: JobsContext, claimed: ClaimedJob): Pro
   return rows.length > 0;
 }
 
-/** Records the end of an attempt. False when the job is no longer this claim's: nothing was written. */
+/**
+ * Records the end of an attempt; a success of a scheduled queue also updates its schedule, in the same transaction.
+ * False when the job is no longer this claim's: nothing was written.
+ */
 export async function completeJob(ctx: JobsContext, claimed: ClaimedJob, completion: Completion): Promise<boolean> {
   const now = ctx.clock.now();
   const unlocked = { lockedUntil: null, lockedBy: null, claimToken: null, updatedAt: now };
@@ -97,8 +101,12 @@ export async function completeJob(ctx: JobsContext, claimed: ClaimedJob, complet
       : completion.kind === "retry"
         ? { ...unlocked, status: "pending" as const, runAt: completion.runAt, lastError: completion.error }
         : { ...unlocked, status: "failed" as const, finishedAt: now, lastError: completion.error };
-  const rows = await ctx.db.update(jobs).set(set).where(isHeld(claimed)).returning();
-  return rows.length > 0;
+  return ctx.db.transaction(async (tx) => {
+    const rows = await tx.update(jobs).set(set).where(isHeld(claimed)).returning();
+    if (rows.length === 0) return false;
+    if (completion.kind === "succeeded") await recordScheduleSuccess({ ...ctx, db: tx }, claimed.job.queue);
+    return true;
+  });
 }
 
 /**

package/src/server/index.ts

@@ -16,4 +16,11 @@ export { consoleJobsLogger, type JobsLogFields, type JobsLogger } from "./logger
 export { getQueueStats, pruneJobs, type QueueStats } from "./maintenance.js";
 export { getJobsOptions } from "./options.js";
 export { runClaimedJob, type RunClaimedJobOptions } from "./process.js";
+export {
+  enqueueDueSchedules,
+  getScheduleSlot,
+  SCHEDULE_DEDUP_KEY,
+  type EnqueueDueSchedulesInput,
+  type ScheduleState,
+} from "./schedules.js";
 export { runDueJobs, type RunDueJobsOptions, type RunDueJobsReport } from "./run-due.js";

package/src/server/maintenance.ts

@@ -4,6 +4,7 @@ import { JOB_STATUSES, type JobStatus } from "../contract.js";
 import { jobs } from "../schema.js";
 import type { JobsContext } from "./context.js";
 import { getJobsOptions } from "./options.js";
+import { getScheduleStates, type ScheduleState } from "./schedules.js";
 
 const DAY_MS = 24 * 60 * 60 * 1000;
 /** Rows deleted per statement, so pruning a large backlog never holds one long lock. */
@@ -39,11 +40,13 @@ export interface QueueStats {
   readonly due: number;
   /** The `run_at` of the oldest due pending job, or null: how far behind the workers are. */
   readonly oldestDueAt: Date | null;
+  /** The queue's schedule, when `schedules` names it: when it last ran and whether it is late. */
+  readonly schedule: ScheduleState | null;
 }
 
 /**
- * Counts per queue: every configured queue, plus any queue that still has rows in the table. For a dashboard, an ops
- * script or a health check of the app's own (`ops({ checks })`).
+ * Counts per queue: every configured queue, plus any queue that still has rows in the table, with the state of its
+ * schedule. For a dashboard, an ops script or a health check of the app's own (`ops({ checks })`).
  */
 export async function getQueueStats(ctx: JobsContext): Promise<QueueStats[]> {
   const now = ctx.clock.now();
@@ -56,12 +59,13 @@ export async function getQueueStats(ctx: JobsContext): Promise<QueueStats[]> {
     .from(jobs)
     .where(and(eq(jobs.status, "pending"), sql`${jobs.runAt} <= ${now}`))
     .groupBy(jobs.queue);
+  const scheduleStates = await getScheduleStates(ctx);
 
   const names = new Set([...Object.keys(getJobsOptions(ctx.config).queues), ...counted.map((row) => row.queue)]);
   return [...names].map((queue) => {
     const counts = Object.fromEntries(JOB_STATUSES.map((status) => [status, 0])) as Record<JobStatus, number>;
     for (const row of counted.filter((candidate) => candidate.queue === queue)) counts[row.status] = row.count;
     const due = backlog.find((row) => row.queue === queue);
-    return { queue, counts, due: due?.due ?? 0, oldestDueAt: due?.oldestDueAt ?? null };
+    return { queue, counts, due: due?.due ?? 0, oldestDueAt: due?.oldestDueAt ?? null, schedule: scheduleStates.get(queue) ?? null };
   });
 }

package/src/server/run-due.ts

@@ -7,6 +7,7 @@ import { consoleJobsLogger, type JobsLogger } from "./logger.js";
 import { getJobsOptions } from "./options.js";
 import { runClaimedJob } from "./process.js";
 import { checkHandlers } from "./handler-check.js";
+import { enqueueDueSchedules } from "./schedules.js";
 
 const DEFAULT_MAX_JOBS = 1000;
 const NEVER_ABORTED = new AbortController().signal;
@@ -33,11 +34,12 @@ export interface RunDueJobsReport {
 }
 
 /**
- * Claims and runs due jobs until none is due (a retried job is due later, so it waits for the clock). Returns what
+ * Enqueues the due runs of the schedules among its queues, then claims and runs due jobs until none is due (a retried job is due later, so it waits for the clock). Returns what
  * happened. Throws on a handler for a queue the config does not define; database failures propagate.
  */
 export async function runDueJobs(ctx: JobsContext, options: RunDueJobsOptions): Promise<RunDueJobsReport> {
   const queues = checkHandlers(getJobsOptions(ctx.config), options.handlers, options.queues);
+  await enqueueDueSchedules(ctx, { queues });
   const report = { succeeded: 0, retried: 0, failed: 0, stale: 0 };
   const maxJobs = options.maxJobs ?? DEFAULT_MAX_JOBS;
   const runOptions = {