Scheduled tasks

A task is a cron trigger that enqueues jobs. It never does work itself.

As of 2026-08. Stable API — semver from here (Upgrading).

The canonical shape

// task (cron)
export const nightlyDigest = task({
  cron: '0 3 * * *',
  tz: 'UTC',
  // The occurrence, never the wall clock: a catch-up tick runs long after the instant it fires
  // for, and a payload read off `Date.now()` there is silently for the wrong day.
  enqueue: (occurrenceMs) => [[sendDigest, { occurrenceMs }]],
});

A task only enqueues

If it has a handler body, it is a job, not a task.

enqueue must be cheap and synchronous-shaped: build inputs, return the list. Fanning out per tenant is a job that enqueues children, not a loop with a DB read inside enqueue.

export const rotateApiKeys = task({
  cron: '15 2 * * 1',
  tz: 'Europe/Berlin',
  enqueue: () => [[fanOutKeyRotation, {}]],
});

The fluent surface

Every projection is a method on the task — nightlyDigest.enqueue(), never runTask(nightlyDigest) — and every declared field is lifted onto it. A task has no .def.

A task reaches its jobs only through its own entries, and those entries carry job handles, never job names. So the scheduler dispatches with <job>.idempotencyKeyFor(input) and <job>.retry.attempts read off the handle — a task never restates a job's retry policy and never resolves a job by string.

Manual enqueue() and a scheduled tick differ in exactly one place: the key. A tick's is occurrence-scoped, <task>:<occurrenceMs>:<the job's own key>, so two schedulers or a retried tick cannot double-fire that occurrence. enqueue() uses the job's plain key, because a manual run has no occurrence to scope to — and scoping it to whichever occurrence it happened to land in is the one thing that would make a backfill dedupe against a real tick.

Fields

Nothing else. There is no timeout, no retry, no concurrency on a task — those belong to the job it enqueues. No queue either: the queue is the job's, and a per-call override rides on the fire, as <task>.enqueue({ queue }).

tz is required for a reason

tz is checked against the runtime's own IANA database, not merely for non-emptiness As of 2026-08. The declaration asks Intl.DateTimeFormat to resolve the zone, and Intl carries the runtime's copy of the tz database — the only check that can tell America/Bogota from Bogota. So a non-empty string is not a timezone:

X_INVARIANT: task "nightlyDigest" has tz "Bogota", which is not a zone in the IANA tz database
fix: use the full zone id on task("nightlyDigest"), e.g. tz: 'America/Bogota' — list the valid
     ones with: bun -e "console.log(Intl.supportedValuesOf('timeZone').join('\n'))"

It fails at declaration, not at the first tick. The alternative is what an abbreviation used to do: resolve every occurrence in UTC and run the cron five hours off, silently, forever.

Store UTC, schedule against an explicit zone, format at the edge. See Timezones and dates.

The scheduler role

Fixed 1. Cron dispatch only.

That chain is the whole safety argument: at-least-once dispatch + required job idempotency = effectively-once work. A scheduler that guarantees exactly-once dispatch does not exist; one that guarantees never-silently-skipped does.

Role table and drain sequence: Deployment.

Introspection

$ x tasks list --json
{"ok":true,"command":"tasks","summary":"1 task(s)","findings":[],"data":[
  {"kind":"task","name":"nightlyDigest","cron":"0 3 * * *","tz":"UTC","catchUp":"skip",
   "maxCatchUp":10,"jobs":["sendDigest"],
   "nextMs":1786503600000,"next":"2026-08-12T03:00:00Z"}]}

next carries the task's own zone offset, never a machine-local one: the same 0 3 * * * in America/New_York reads 2026-03-06T03:00:00-05:00 before the spring-forward and 2026-03-09T03:00:00-04:00 after it.

Testing

Frozen clock. clock.advance drives cron — never sleep, never wall-clock.

test('nightlyDigest enqueues one digest job per day', async ({ seed, clock }) => {
  await seed('one-org');
  clock.advance('3d');
  const trace = await runJobs.drain();
  expect(trace.enqueued(sendDigest)).toHaveLength(3);
});

Runner: x test job (tasks are dispatch, jobs are the assertion surface). See Testing.

Errors

Full index: Error codes.

Rules

• A task never contains a handler body. If it does work, it is a job.
• tz is always explicit and always IANA.
• Every job a task enqueues must be idempotent — that is what makes leader handover safe.
• Never rely on a task firing at an exact instant. Rely on it firing.
• Never use a task as a poller for something an action could publish. Cron is a fallback, not an event bus.
• One task per schedule. Two schedules for one job is two tasks, not a conditional inside enqueue.