@helipod/scheduler 0.1.0

package/dist/index.js

@@ -0,0 +1,775 @@
+// src/index.ts
+import { defineComponent } from "@helipod/component";
+
+// src/schema.ts
+import { defineSchema, defineTable, v } from "@helipod/values";
+var schedulerSchema = defineSchema({
+  jobs: defineTable({
+    fnPath: v.string(),
+    kind: v.union(v.literal("mutation"), v.literal("action")),
+    state: v.union(
+      v.literal("pending"),
+      v.literal("inProgress"),
+      v.literal("success"),
+      v.literal("failed"),
+      v.literal("canceled")
+    ),
+    nextTs: v.number(),
+    attempts: v.number(),
+    maxFailures: v.number(),
+    leaseHolder: v.optional(v.string()),
+    leaseExpiresAt: v.optional(v.number()),
+    idempotencyKey: v.optional(v.string()),
+    appVersion: v.optional(v.string()),
+    name: v.optional(v.string()),
+    hasArgs: v.boolean(),
+    onComplete: v.optional(v.string()),
+    parentId: v.optional(v.string()),
+    completedTs: v.optional(v.number()),
+    /** The most recent failure's `String(error)` — set on retry AND on dead-letter (Task 4). */
+    lastError: v.optional(v.string())
+  }).index("by_next_ts", ["state", "nextTs"]).index("by_completed_ts", ["completedTs"]).index("by_parent", ["parentId"]).index("by_idempotency", ["idempotencyKey"]),
+  job_args: defineTable({
+    jobId: v.string(),
+    args: v.any(),
+    context: v.optional(v.any())
+  }).index("by_job", ["jobId"]),
+  // Task 5: recurring/cron schedules. `cadenceJobId` points at the currently-pending `jobs` row
+  // for this cron's CADENCE job (the dual-job design's self-rescheduling half — see
+  // `_cronTick` in `./modules.ts`); the work job(s) it fires are ordinary `jobs` rows, tracked
+  // only via their deterministic `idempotencyKey` (`${name}:${fireTs}`), not by this pointer.
+  // `spec` is a JSON-serialized `CronSpec` (`./crons.ts`) — either `{kind:"interval",ms}` or
+  // `{kind:"cron",expr}`. `catchUp` was originally typed `boolean`; Task 5 widened it to the
+  // three-way policy `_cronTick` actually implements (`skip` | `fireOnce` | `fireAll`).
+  crons: defineTable({
+    name: v.string(),
+    spec: v.string(),
+    tz: v.string(),
+    catchUp: v.union(v.literal("skip"), v.literal("fireOnce"), v.literal("fireAll")),
+    lastScheduledTs: v.optional(v.number()),
+    workFnPath: v.string(),
+    workArgs: v.any(),
+    cadenceJobId: v.optional(v.string())
+  }).index("by_name", ["name"])
+});
+
+// src/facade.ts
+import "@helipod/executor";
+function getFunctionPath(ref) {
+  return typeof ref === "string" ? ref : ref.__path;
+}
+function currentAppVersion() {
+  return void 0;
+}
+function currentJobId() {
+  return void 0;
+}
+function compact(obj) {
+  const out = {};
+  for (const [k, v2] of Object.entries(obj)) if (v2 !== void 0) out[k] = v2;
+  return out;
+}
+async function enqueueInternal(db, now, tables, fnRef, args, opts, kindOf = () => "mutation") {
+  const fnPath = getFunctionPath(fnRef);
+  if (opts.idempotencyKey !== void 0) {
+    const existing = await db.query(tables.jobs, "by_idempotency").eq("idempotencyKey", opts.idempotencyKey).take(1).collect();
+    const found = existing[0];
+    if (found) return found._id;
+  }
+  const parentId = currentJobId();
+  let parentCanceled = false;
+  if (parentId !== void 0) {
+    const parent = await db.get(parentId);
+    parentCanceled = parent !== null && parent.state === "canceled";
+  }
+  const bornState = parentCanceled ? "canceled" : "pending";
+  const kind = kindOf(fnPath);
+  const nextTs = opts.runAt ?? (opts.runAfter !== void 0 ? now() + Math.max(0, opts.runAfter) : now());
+  const jobId = await db.insert(
+    tables.jobs,
+    compact({
+      fnPath,
+      kind,
+      state: bornState,
+      nextTs,
+      attempts: 0,
+      // Retry budget. Mutations are transactional (a failed one committed nothing), so retrying is
+      // always safe: default 4. Actions have arbitrary external side effects, so a CLEANLY-failed
+      // action (its own code threw after possibly running partway) must NOT be blindly re-run:
+      // default 1, i.e. dead-letter on the first failure (`_complete`'s `attempts >= maxFailures`
+      // check). An explicit `opts.retry` is the author's opt-in that the target is safe to re-run
+      // (e.g. `@helipod/workflow` threading a step's declared `maxAttempts` through here) and is
+      // honored as-is for both kinds.
+      maxFailures: opts.retry?.maxFailures ?? (kind === "action" ? 1 : 4),
+      leaseHolder: void 0,
+      leaseExpiresAt: void 0,
+      idempotencyKey: opts.idempotencyKey,
+      appVersion: currentAppVersion(),
+      name: opts.name,
+      hasArgs: true,
+      onComplete: opts.onComplete,
+      parentId,
+      completedTs: parentCanceled ? now() : void 0
+    })
+  );
+  await db.insert(tables.jobArgs, compact({ jobId, args, context: opts.context }));
+  return jobId;
+}
+var FACADE_TABLES = { jobs: "jobs", jobArgs: "job_args" };
+async function fireOnComplete(db, now, tables, jobId, onComplete, result) {
+  if (onComplete === void 0) return;
+  const argRows = await db.query(tables.jobArgs, "by_job").eq("jobId", jobId).take(1).collect();
+  const context = argRows[0]?.context;
+  await enqueueInternal(db, now, tables, onComplete, compact({ jobId, context, result }), { runAt: now() });
+}
+function schedulerContext(cctx) {
+  const db = cctx.db;
+  const now = () => cctx.now;
+  const kindOf = (fnPath) => cctx.functionKind?.(fnPath) === "action" ? "action" : "mutation";
+  return {
+    async runAfter(delayMs, fnRef, args) {
+      return enqueueInternal(db, now, FACADE_TABLES, fnRef, args, { runAt: now() + Math.max(0, delayMs) }, kindOf);
+    },
+    async runAt(ts, fnRef, args) {
+      return enqueueInternal(db, now, FACADE_TABLES, fnRef, args, { runAt: ts instanceof Date ? ts.getTime() : ts }, kindOf);
+    },
+    async cancel(id) {
+      const job = await db.get(id);
+      if (job !== null && job.state === "pending") {
+        await db.replace(id, { ...job, state: "canceled", completedTs: now() });
+        await fireOnComplete(db, now, FACADE_TABLES, id, job.onComplete, { kind: "canceled" });
+      }
+      const queue = [id];
+      const seen = /* @__PURE__ */ new Set([id]);
+      while (queue.length > 0) {
+        const parentId = queue.shift();
+        const children = await db.query("jobs", "by_parent").eq("parentId", parentId).collect();
+        for (const child of children) {
+          const childId = child._id;
+          if (seen.has(childId)) continue;
+          seen.add(childId);
+          if (child.state === "pending") {
+            await db.replace(childId, { ...child, state: "canceled", completedTs: now() });
+            await fireOnComplete(db, now, FACADE_TABLES, childId, child.onComplete, { kind: "canceled" });
+          }
+          queue.push(childId);
+        }
+      }
+    },
+    async enqueue(fnRef, args, opts) {
+      return enqueueInternal(db, now, FACADE_TABLES, fnRef, args, opts ?? {}, kindOf);
+    }
+  };
+}
+function schedulerActionContext(api) {
+  return {
+    async runAfter(delayMs, fnRef, args) {
+      return api.runMutation("scheduler:_enqueue", { fnPath: getFunctionPath(fnRef), args, runAtMs: Date.now() + delayMs });
+    },
+    async runAt(ts, fnRef, args) {
+      return api.runMutation("scheduler:_enqueue", {
+        fnPath: getFunctionPath(fnRef),
+        args,
+        runAtMs: ts instanceof Date ? ts.getTime() : ts
+      });
+    },
+    async cancel(id) {
+      await api.runMutation("scheduler:_cancel", { id });
+    }
+  };
+}
+
+// src/modules.ts
+import { query, mutation } from "@helipod/executor";
+
+// src/backoff.ts
+var DEFAULT_BACKOFF_OPTIONS = { initialBackoffMs: 250, base: 2 };
+function computeBackoff(attempts, rng = Math.random, o = DEFAULT_BACKOFF_OPTIONS) {
+  const raw = o.initialBackoffMs * o.base ** (attempts + 1);
+  return Math.round(raw * (0.5 + 0.5 * rng()));
+}
+
+// src/crons.ts
+import cronParser from "cron-parser";
+import "@helipod/executor";
+var { parseExpression } = cronParser;
+var DEFAULT_CATCH_UP = "skip";
+var DEFAULT_TZ = "UTC";
+var DAY_NUMBERS = {
+  sunday: 0,
+  monday: 1,
+  tuesday: 2,
+  wednesday: 3,
+  thursday: 4,
+  friday: 5,
+  saturday: 6
+};
+function cronJobs() {
+  const entries = /* @__PURE__ */ new Map();
+  function register(name, spec, tz, catchUp, fnRef, args) {
+    if (entries.has(name)) throw new Error(`cron "${name}" is already registered \u2014 cron identifiers must be unique`);
+    entries.set(name, {
+      name,
+      spec,
+      tz: tz ?? DEFAULT_TZ,
+      catchUp: catchUp ?? DEFAULT_CATCH_UP,
+      workFnPath: getFunctionPath(fnRef),
+      workArgs: args
+    });
+  }
+  return {
+    interval(name, period, fnRef, args, opts) {
+      const ms = (period.seconds ?? 0) * 1e3 + (period.minutes ?? 0) * 6e4 + (period.hours ?? 0) * 36e5;
+      if (ms <= 0) throw new Error(`cron "${name}": interval must resolve to a positive duration`);
+      register(name, { kind: "interval", ms }, opts?.tz, opts?.catchUp, fnRef, args);
+    },
+    cron(name, expr, fnRef, args, opts) {
+      register(name, { kind: "cron", expr }, opts?.tz, opts?.catchUp, fnRef, args);
+    },
+    daily(name, at, fnRef, args, opts) {
+      register(name, { kind: "cron", expr: `${at.minuteUTC} ${at.hourUTC} * * *` }, DEFAULT_TZ, opts?.catchUp, fnRef, args);
+    },
+    hourly(name, at, fnRef, args, opts) {
+      register(name, { kind: "cron", expr: `${at.minuteUTC} * * * *` }, DEFAULT_TZ, opts?.catchUp, fnRef, args);
+    },
+    weekly(name, at, fnRef, args, opts) {
+      register(name, { kind: "cron", expr: `${at.minuteUTC} ${at.hourUTC} * * ${DAY_NUMBERS[at.dayOfWeek]}` }, DEFAULT_TZ, opts?.catchUp, fnRef, args);
+    },
+    monthly(name, at, fnRef, args, opts) {
+      register(name, { kind: "cron", expr: `${at.minuteUTC} ${at.hourUTC} ${at.day} * *` }, DEFAULT_TZ, opts?.catchUp, fnRef, args);
+    },
+    __entries: () => [...entries.values()]
+  };
+}
+function computeNextRun(spec, tz, afterTs) {
+  if (spec.kind === "interval") return afterTs + spec.ms;
+  const interval = parseExpression(spec.expr, { currentDate: new Date(afterTs), tz });
+  return interval.next().toDate().getTime();
+}
+function computePrevRun(spec, tz, atOrBeforeTs) {
+  if (spec.kind === "interval") {
+    throw new Error(
+      "computePrevRun: interval specs are anchor-relative \u2014 compute their previous occurrence via arithmetic from the cron's own anchor instead of calling this"
+    );
+  }
+  const interval = parseExpression(spec.expr, { currentDate: new Date(atOrBeforeTs + 1), tz });
+  return interval.prev().toDate().getTime();
+}
+async function enqueueCadenceJob(db, now, tables, cronName, runAt) {
+  const jobId = await enqueueInternal(db, now, tables, "scheduler:_cronTick", { cronName }, { runAt, name: cronName });
+  const rows = await db.query(tables.jobArgs, "by_job").eq("jobId", jobId).take(1).collect();
+  const row = rows[0];
+  if (row !== void 0) {
+    await db.replace(row._id, { ...row, args: { cronName, jobId } });
+  }
+  return jobId;
+}
+async function reconcileCrons(ctx, registry) {
+  const db = ctx.db;
+  const now = ctx.now;
+  const nowFn = () => now;
+  const tables = { jobs: "jobs", jobArgs: "job_args" };
+  const desired = registry ? registry.__entries() : [];
+  const desiredByName = new Map(desired.map((e) => [e.name, e]));
+  const existingRows = await db.query("crons", "by_creation").collect();
+  const existingByName = new Map(existingRows.map((r) => [r.name, r]));
+  for (const row of existingRows) {
+    if (desiredByName.has(row.name)) continue;
+    const cadenceJobId = row.cadenceJobId;
+    if (cadenceJobId !== void 0) {
+      const job = await db.get(cadenceJobId);
+      if (job !== null && job.state === "pending") {
+        await db.replace(cadenceJobId, { ...job, state: "canceled", completedTs: now });
+      }
+    }
+    await db.delete(row._id);
+  }
+  for (const entry of desired) {
+    const specJson = JSON.stringify(entry.spec);
+    const existingRow = existingByName.get(entry.name);
+    if (existingRow === void 0) {
+      const cronId = await db.insert("crons", {
+        name: entry.name,
+        spec: specJson,
+        tz: entry.tz,
+        catchUp: entry.catchUp,
+        lastScheduledTs: now,
+        workFnPath: entry.workFnPath,
+        workArgs: entry.workArgs
+      });
+      const firstRun = computeNextRun(entry.spec, entry.tz, now);
+      const cadenceJobId2 = await enqueueCadenceJob(db, nowFn, tables, entry.name, firstRun);
+      await db.replace(cronId, {
+        name: entry.name,
+        spec: specJson,
+        tz: entry.tz,
+        catchUp: entry.catchUp,
+        lastScheduledTs: now,
+        workFnPath: entry.workFnPath,
+        workArgs: entry.workArgs,
+        cadenceJobId: cadenceJobId2
+      });
+      continue;
+    }
+    const specChanged = existingRow.spec !== specJson || existingRow.tz !== entry.tz || existingRow.workFnPath !== entry.workFnPath || JSON.stringify(existingRow.workArgs) !== JSON.stringify(entry.workArgs);
+    if (specChanged) {
+      const oldCadenceJobId = existingRow.cadenceJobId;
+      if (oldCadenceJobId !== void 0) {
+        const job = await db.get(oldCadenceJobId);
+        if (job !== null && job.state === "pending") {
+          await db.replace(oldCadenceJobId, { ...job, state: "canceled", completedTs: now });
+        }
+      }
+      const firstRun = computeNextRun(entry.spec, entry.tz, now);
+      const cadenceJobId2 = await enqueueCadenceJob(db, nowFn, tables, entry.name, firstRun);
+      await db.replace(existingRow._id, {
+        ...existingRow,
+        spec: specJson,
+        tz: entry.tz,
+        catchUp: entry.catchUp,
+        workFnPath: entry.workFnPath,
+        workArgs: entry.workArgs,
+        lastScheduledTs: now,
+        cadenceJobId: cadenceJobId2
+      });
+      continue;
+    }
+    if (existingRow.catchUp !== entry.catchUp) {
+      await db.replace(existingRow._id, { ...existingRow, catchUp: entry.catchUp });
+    }
+    const cadenceJobId = existingRow.cadenceJobId;
+    let hasLiveCadence = false;
+    if (cadenceJobId !== void 0) {
+      const job = await db.get(cadenceJobId);
+      hasLiveCadence = job !== null && (job.state === "pending" || job.state === "inProgress");
+    }
+    if (!hasLiveCadence) {
+      const anchor = existingRow.lastScheduledTs ?? now;
+      const nextRun = computeNextRun(entry.spec, entry.tz, anchor);
+      const newCadenceJobId = await enqueueCadenceJob(db, nowFn, tables, entry.name, nextRun);
+      await db.replace(existingRow._id, { ...existingRow, cadenceJobId: newCadenceJobId });
+    }
+  }
+}
+
+// src/modules.ts
+var BATCH_CAP = 64;
+var CATCHUP_CAP = 1e3;
+var LEASE_MS = 3e4;
+var SWEEP_MS = 3e4;
+function compact2(obj) {
+  const out = {};
+  for (const [k, v2] of Object.entries(obj)) if (v2 !== void 0) out[k] = v2;
+  return out;
+}
+var _peekDue = query(async (ctx) => {
+  const now = ctx.now();
+  const due = await ctx.db.query("scheduler/jobs", "by_next_ts").eq("state", "pending").lte("nextTs", now).order("asc").take(BATCH_CAP).collect();
+  const future = await ctx.db.query("scheduler/jobs", "by_next_ts").eq("state", "pending").gt("nextTs", now).order("asc").take(1).collect();
+  const next = future[0];
+  return {
+    due,
+    earliestFutureTs: next ? next.nextTs : null
+  };
+});
+var _claim = mutation(async (ctx, args) => {
+  const job = await ctx.db.get(args.jobId);
+  if (job === null || job.state !== "pending") return null;
+  const now = ctx.now();
+  await ctx.db.replace(args.jobId, {
+    ...job,
+    state: "inProgress",
+    leaseHolder: "driver",
+    leaseExpiresAt: now + LEASE_MS
+  });
+  const argRows = await ctx.db.query("scheduler/job_args", "by_job").eq("jobId", args.jobId).take(1).collect();
+  const argRow = argRows[0];
+  return {
+    jobId: args.jobId,
+    fnPath: job.fnPath,
+    kind: job.kind,
+    args: argRow?.args ?? null,
+    context: argRow?.context,
+    onComplete: job.onComplete
+  };
+});
+var _complete = mutation(async (ctx, args) => {
+  const job = await ctx.db.get(args.jobId);
+  if (job === null || job.state !== "inProgress") return null;
+  const now = ctx.now();
+  const nowFn = () => now;
+  if (args.result.kind === "success") {
+    await ctx.db.replace(
+      args.jobId,
+      compact2({
+        ...job,
+        state: "success",
+        completedTs: now,
+        leaseHolder: void 0,
+        leaseExpiresAt: void 0
+      })
+    );
+    await fireOnComplete(ctx.db, nowFn, CRON_TABLES, args.jobId, job.onComplete, {
+      kind: "success",
+      value: args.result.value
+    });
+    return null;
+  }
+  const attempts = job.attempts + 1;
+  const maxFailures = job.maxFailures;
+  const lastError = args.result.error;
+  const retryable = args.result.retryable ?? true;
+  if (attempts >= maxFailures || !retryable) {
+    await ctx.db.replace(
+      args.jobId,
+      compact2({
+        ...job,
+        state: "failed",
+        attempts,
+        completedTs: now,
+        lastError,
+        leaseHolder: void 0,
+        leaseExpiresAt: void 0
+      })
+    );
+    await fireOnComplete(ctx.db, nowFn, CRON_TABLES, args.jobId, job.onComplete, {
+      kind: "failed",
+      error: lastError
+    });
+    return null;
+  }
+  const nextTs = now + computeBackoff(attempts, ctx.random);
+  await ctx.db.replace(
+    args.jobId,
+    compact2({
+      ...job,
+      state: "pending",
+      attempts,
+      nextTs,
+      lastError,
+      leaseHolder: void 0,
+      leaseExpiresAt: void 0
+    })
+  );
+  return null;
+});
+var CRON_TABLES = { jobs: "scheduler/jobs", jobArgs: "scheduler/job_args" };
+var _enqueue = mutation(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  async (ctx, a) => ctx.scheduler.runAt(a.runAtMs, a.fnPath, a.args)
+);
+var _cancel = mutation(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  async (ctx, a) => {
+    await ctx.scheduler.cancel(a.id);
+    return null;
+  }
+);
+var _cronTick = mutation(async (ctx, args) => {
+  const rows = await ctx.db.query("scheduler/crons", "by_name").eq("name", args.cronName).take(1).collect();
+  const cron = rows[0];
+  if (cron === void 0) return null;
+  if (args.jobId !== void 0 && cron.cadenceJobId !== void 0 && cron.cadenceJobId !== args.jobId) {
+    return null;
+  }
+  const now = ctx.now();
+  const spec = JSON.parse(cron.spec);
+  const tz = cron.tz;
+  const catchUp = cron.catchUp;
+  const anchor = cron.lastScheduledTs ?? now;
+  const nowFn = () => ctx.now();
+  let toFire;
+  let next;
+  let newLastScheduledTs;
+  if (spec.kind === "interval") {
+    const period = spec.ms;
+    const elapsed = now - anchor;
+    const n = elapsed >= 0 ? Math.floor(elapsed / period) : 0;
+    if (n === 0) {
+      toFire = [];
+      next = anchor + period;
+      newLastScheduledTs = anchor;
+    } else if (n === 1) {
+      const only = anchor + period;
+      toFire = [only];
+      next = only + period;
+      newLastScheduledTs = only;
+    } else {
+      const lastOccurrence = anchor + n * period;
+      next = lastOccurrence + period;
+      newLastScheduledTs = lastOccurrence;
+      if (catchUp === "fireAll") {
+        const fireCount = Math.min(n, CATCHUP_CAP);
+        toFire = [];
+        for (let i = 0; i < fireCount; i++) toFire.push(anchor + (i + 1) * period);
+        if (n > CATCHUP_CAP) {
+          console.warn(
+            `[scheduler] cron "${cron.name}": fireAll backlog of ${n} occurrences exceeded CATCHUP_CAP (${CATCHUP_CAP}) \u2014 fired the oldest ${CATCHUP_CAP}, discarded the rest.`
+          );
+        }
+      } else if (catchUp === "fireOnce") {
+        toFire = [lastOccurrence];
+      } else {
+        toFire = [];
+      }
+    }
+  } else {
+    const firstAfterAnchor = computeNextRun(spec, tz, anchor);
+    if (firstAfterAnchor > now) {
+      toFire = [];
+      next = firstAfterAnchor;
+      newLastScheduledTs = anchor;
+    } else {
+      const secondAfterAnchor = computeNextRun(spec, tz, firstAfterAnchor);
+      if (secondAfterAnchor > now) {
+        toFire = [firstAfterAnchor];
+        next = secondAfterAnchor;
+        newLastScheduledTs = firstAfterAnchor;
+      } else {
+        next = computeNextRun(spec, tz, now);
+        const lastOccurrence = computePrevRun(spec, tz, now);
+        newLastScheduledTs = lastOccurrence;
+        if (catchUp === "fireAll") {
+          toFire = [];
+          let cursor = firstAfterAnchor;
+          let truncated = false;
+          while (cursor <= now) {
+            if (toFire.length >= CATCHUP_CAP) {
+              truncated = true;
+              break;
+            }
+            toFire.push(cursor);
+            cursor = computeNextRun(spec, tz, cursor);
+          }
+          if (truncated) {
+            console.warn(
+              `[scheduler] cron "${cron.name}": fireAll backlog exceeded CATCHUP_CAP (${CATCHUP_CAP}) \u2014 fired the oldest ${CATCHUP_CAP}, discarded the rest.`
+            );
+          }
+        } else if (catchUp === "fireOnce") {
+          toFire = [lastOccurrence];
+        } else {
+          toFire = [];
+          console.warn(
+            `[scheduler] cron "${cron.name}": skipped a downtime backlog (catchUp:"skip") \u2014 exact occurrence count not tracked for cron-expression specs.`
+          );
+        }
+      }
+    }
+  }
+  const schedulerFacade = ctx.scheduler;
+  for (const fireTs of toFire) {
+    await schedulerFacade.enqueue(cron.workFnPath, cron.workArgs, {
+      runAt: fireTs,
+      idempotencyKey: `${cron.name}:${fireTs}`,
+      name: cron.name
+    });
+  }
+  const cadenceJobId = await enqueueCadenceJob(ctx.db, nowFn, CRON_TABLES, cron.name, next);
+  await ctx.db.replace(
+    cron._id,
+    compact2({
+      ...cron,
+      lastScheduledTs: newLastScheduledTs,
+      cadenceJobId
+    })
+  );
+  return null;
+});
+var _reclaim = mutation(async (ctx) => {
+  const now = ctx.now();
+  const nowFn = () => now;
+  const expired = await ctx.db.query("scheduler/jobs", "by_next_ts").eq("state", "inProgress").where("lt", "leaseExpiresAt", now).take(BATCH_CAP).collect();
+  let reclaimed = 0;
+  for (const job of expired) {
+    const jobId = job._id;
+    const attempts = job.attempts + 1;
+    const lastError = "lease expired: driver did not complete the job before its lease deadline (infra kill)";
+    if (job.kind === "mutation" && attempts < job.maxFailures) {
+      await ctx.db.replace(
+        jobId,
+        compact2({
+          ...job,
+          state: "pending",
+          attempts,
+          nextTs: now,
+          // immediate — the delay was the crash, not the job's own backoff
+          lastError,
+          leaseHolder: void 0,
+          leaseExpiresAt: void 0
+        })
+      );
+    } else {
+      await ctx.db.replace(
+        jobId,
+        compact2({
+          ...job,
+          state: "failed",
+          attempts,
+          completedTs: now,
+          lastError,
+          leaseHolder: void 0,
+          leaseExpiresAt: void 0
+        })
+      );
+      await fireOnComplete(ctx.db, nowFn, CRON_TABLES, jobId, job.onComplete, {
+        kind: "failed",
+        error: lastError
+      });
+    }
+    reclaimed++;
+  }
+  return { reclaimed };
+});
+
+// src/driver.ts
+import { isHelipodError } from "@helipod/errors";
+function schedulerDriver() {
+  let ctx;
+  let running = false;
+  let pendingWake = false;
+  let timer = null;
+  let inFlight = null;
+  let sweepTimer = null;
+  let stopped = false;
+  function wake() {
+    if (stopped) return;
+    iterate().catch((e) => {
+      console.error("[scheduler] driver iteration failed:", e);
+    });
+  }
+  function iterate() {
+    if (running) {
+      pendingWake = true;
+      return inFlight ?? Promise.resolve();
+    }
+    running = true;
+    const pass = runPass().finally(() => {
+      running = false;
+      inFlight = null;
+      if (pendingWake) void wake();
+    });
+    inFlight = pass;
+    return pass;
+  }
+  async function runPass() {
+    let earliestFutureTs = null;
+    do {
+      pendingWake = false;
+      const peeked = await ctx.runFunction("scheduler:_peekDue", {});
+      earliestFutureTs = peeked.earliestFutureTs;
+      for (const job of peeked.due) {
+        const claimed = await ctx.runFunction("scheduler:_claim", { jobId: job._id });
+        if (claimed === null) continue;
+        let result;
+        try {
+          const value = await ctx.runFunction(claimed.fnPath, claimed.args);
+          result = { kind: "success", value: value === void 0 ? null : value };
+        } catch (e) {
+          result = { kind: "failed", error: String(e), retryable: isHelipodError(e) ? e.retryable : true };
+        }
+        await ctx.runFunction("scheduler:_complete", { jobId: job._id, result });
+      }
+    } while (pendingWake);
+    if (timer !== null) {
+      ctx.clearTimer(timer);
+      timer = null;
+    }
+    if (!stopped && earliestFutureTs != null) timer = ctx.setTimer(earliestFutureTs, wake);
+  }
+  async function sweepOnce() {
+    try {
+      await ctx.runFunction("scheduler:_reclaim", {});
+    } catch (e) {
+      console.error("[scheduler] lease-reclaim sweep failed:", e);
+    } finally {
+      armSweep();
+    }
+  }
+  function armSweep() {
+    if (stopped) return;
+    if (sweepTimer !== null) {
+      ctx.clearTimer(sweepTimer);
+      sweepTimer = null;
+    }
+    sweepTimer = ctx.setTimer(ctx.now() + ctx.backstopMs(SWEEP_MS), () => {
+      void sweepOnce();
+    });
+  }
+  let unsubscribeCommit = null;
+  return {
+    name: "scheduler",
+    start(c) {
+      ctx = c;
+      unsubscribeCommit = c.onCommit((inv) => {
+        if (inv.tables.some((t) => t.startsWith("scheduler/"))) wake();
+      });
+      wake();
+      armSweep();
+    },
+    stop() {
+      stopped = true;
+      unsubscribeCommit?.();
+      unsubscribeCommit = null;
+      if (timer !== null) {
+        ctx.clearTimer(timer);
+        timer = null;
+      }
+      if (sweepTimer !== null) {
+        ctx.clearTimer(sweepTimer);
+        sweepTimer = null;
+      }
+    },
+    // Test seam: drives a loop pass and awaits its actual completion (coalescing into an
+    // already-in-flight pass — e.g. one a same-turn reactive `onCommit` wake already started —
+    // rather than resolving early), and lets errors propagate to the caller (unlike `wake()`,
+    // used by the reactive/timer paths, which swallows+logs), so tests see real failures instead
+    // of them being silently logged.
+    __tick: () => iterate(),
+    // Test seam: the same fire-and-forget signal `onCommit`/timers send internally — see the
+    // interface doc above.
+    __wake: () => wake(),
+    // Test seam: runs the lease-reclaim sweep exactly once, without the real `SWEEP_MS` wait and
+    // without re-arming a live timer (unlike `armSweep`/`sweepOnce` above) — errors propagate
+    // (unlike the internal `sweepOnce`) so a test sees real `_reclaim` failures.
+    __sweep: () => ctx.runFunction("scheduler:_reclaim", {}).then(() => void 0)
+  };
+}
+
+// src/index.ts
+function defineScheduler(opts) {
+  return defineComponent({
+    name: "scheduler",
+    schema: schedulerSchema,
+    modules: { _peekDue, _claim, _complete, _reclaim, _cronTick, _enqueue, _cancel },
+    context: (cctx) => schedulerContext(cctx),
+    contextType: { import: "@helipod/scheduler", type: "SchedulerContext" },
+    serverExports: ["cronJobs"],
+    contextWrite: true,
+    driver: schedulerDriver(),
+    boot: (ctx) => reconcileCrons(ctx, opts?.crons),
+    // Action-mode `ctx.scheduler` (Convex parity: portable between a mutation and an action) —
+    // see `schedulerActionContext`'s doc comment in `./facade.ts`.
+    buildAction: (api) => schedulerActionContext(api)
+  });
+}
+export {
+  BATCH_CAP,
+  CATCHUP_CAP,
+  DEFAULT_BACKOFF_OPTIONS,
+  LEASE_MS,
+  SWEEP_MS,
+  computeBackoff,
+  computeNextRun,
+  computePrevRun,
+  cronJobs,
+  defineScheduler,
+  enqueueCadenceJob,
+  enqueueInternal,
+  fireOnComplete,
+  getFunctionPath,
+  schedulerActionContext,
+  schedulerDriver,
+  schedulerSchema
+};
+//# sourceMappingURL=index.js.map