@lunora/scheduler 0.0.0 → 1.0.0-alpha.1

package/dist/index.mjs

@@ -0,0 +1,8 @@
+export { default as createScheduler } from './packem_shared/createScheduler-KCso4_at.mjs';
+export { default as createWorkpool } from './packem_shared/createWorkpool-D5cWPQmH.mjs';
+export { createCronTrigger } from './packem_shared/createCronTrigger-Cq9IBcWQ.mjs';
+export { CRON_SCHEDULE_KINDS, compileCronSchedule, cronJobs } from './packem_shared/compileCronSchedule-BaLlXJiN.mjs';
+export { createQueueConsumer, createQueueWorkpool, httpDispatcher } from './packem_shared/createQueueConsumer-DWahNPfz.mjs';
+export { SchedulerDO } from './packem_shared/SchedulerDO-BNzXNnS4.mjs';
+export { isWorkflowReference } from './packem_shared/isWorkflowReference-C9mQkMXt.mjs';
+export { assertValidCronExpression, isValidCronExpression } from './packem_shared/assertValidCronExpression-BLfrDgmK.mjs';

package/dist/packem_shared/SchedulerDO-BNzXNnS4.mjs

@@ -0,0 +1,678 @@
+const HEADER_PREFIX = "id:";
+const RETRY_PREFIX = "retry:";
+const DEAD_PREFIX = "dead:";
+const POOL_PREFIX = "pool:";
+const MAX_RETRY_ATTEMPTS = 5;
+const RETRY_BASE_DELAY_MS = 3e4;
+const POOL_BACKPRESSURE_DELAY_MS = 1e3;
+const MAX_SCHEDULED_FOR_MS = 864e13;
+const TIME_PAD = 15;
+const padTime = (n) => String(n).padStart(TIME_PAD, "0");
+const generateId = () => {
+  const bytes = crypto.getRandomValues(new Uint8Array(12));
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCodePoint(byte);
+  }
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+};
+class SchedulerDO {
+  static indexKey(scheduledFor, id) {
+    return `t:${padTime(scheduledFor)}:${id}`;
+  }
+  static json(body, status = 200) {
+    return Response.json(body, { headers: { "content-type": "application/json" }, status });
+  }
+  static error(status, code, message) {
+    return SchedulerDO.json({ error: { code, message } }, status);
+  }
+  /**
+   * Resolve the effective retry parameters for a record: its per-job
+   * {@link RetryPolicy} merged over the DO's built-in defaults. Callers that
+   * never set `record.retry` get today's behaviour verbatim
+   * (`maxAttempts: 5`, exponential, `baseMs: 30_000`, no ceiling).
+   */
+  static resolveRetry(record) {
+    const policy = record.retry;
+    const maxAttempts = typeof policy?.maxAttempts === "number" && Number.isInteger(policy.maxAttempts) && policy.maxAttempts > 0 ? policy.maxAttempts : MAX_RETRY_ATTEMPTS;
+    const baseMs = typeof policy?.baseMs === "number" && Number.isFinite(policy.baseMs) && policy.baseMs >= 0 ? policy.baseMs : RETRY_BASE_DELAY_MS;
+    const backoff = policy?.backoff === "linear" ? "linear" : "exponential";
+    const maxMs = typeof policy?.maxMs === "number" && Number.isFinite(policy.maxMs) && policy.maxMs >= 0 ? policy.maxMs : void 0;
+    return { backoff, baseMs, maxAttempts, maxMs };
+  }
+  /** Clamp an untrusted `maxConcurrency` to a positive integer, else fall back. */
+  static normalizeConcurrency(value, fallback) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : fallback;
+  }
+  /**
+   * Sanitize an untrusted retry policy from the wire into a `RetryPolicy` (or
+   * `undefined` when nothing valid was provided). Keeps obviously-bad values
+   * out of storage so {@link SchedulerDO.resolveRetry} never has to re-guard.
+   * @returns The normalized policy, or `undefined` if no valid policy was found.
+   */
+  static normalizeRetry(value) {
+    if (typeof value !== "object" || value === null) {
+      return void 0;
+    }
+    const raw = value;
+    const policy = {};
+    if (typeof raw.maxAttempts === "number" && Number.isInteger(raw.maxAttempts) && raw.maxAttempts > 0) {
+      policy.maxAttempts = raw.maxAttempts;
+    }
+    if (typeof raw.baseMs === "number" && Number.isFinite(raw.baseMs) && raw.baseMs >= 0) {
+      policy.baseMs = raw.baseMs;
+    }
+    if (raw.backoff === "exponential" || raw.backoff === "linear") {
+      policy.backoff = raw.backoff;
+    }
+    if (typeof raw.maxMs === "number" && Number.isFinite(raw.maxMs) && raw.maxMs >= 0) {
+      policy.maxMs = raw.maxMs;
+    }
+    return Object.keys(policy).length === 0 ? void 0 : policy;
+  }
+  /**
+   * Idempotently release the slot held by `jobId`, returning the updated
+   * {@link PoolState} (pure — the caller persists it). A duplicate release for
+   * an id that no longer holds a slot is a no-op, so an at-least-once
+   * `/complete` (or a complete racing a failed-kick release) can never push
+   * `inFlight` below the true number of running jobs and oversubscribe the
+   * pool. Pools persisted before `inFlightIds` existed fall back to a clamped
+   * counter decrement.
+   */
+  static releaseSlot(pool, jobId) {
+    if (pool.inFlightIds === void 0) {
+      return { ...pool, inFlight: Math.max(0, pool.inFlight - 1) };
+    }
+    const next = pool.inFlightIds.filter((id) => id !== jobId);
+    return { ...pool, inFlight: next.length, inFlightIds: next };
+  }
+  /**
+   * Best-effort release with no job id (legacy `/complete` payloads). Drops one
+   * tracked id if the set exists, else clamps the counter. Less precise than
+   * {@link SchedulerDO.releaseSlot} — a duplicate id-less complete CAN
+   * over-release — but every current client sends the id, so this is the
+   * compatibility shim, not the hot path.
+   */
+  static releaseFirstSlot(pool) {
+    if (pool.inFlightIds === void 0) {
+      return { ...pool, inFlight: Math.max(0, pool.inFlight - 1) };
+    }
+    const next = pool.inFlightIds.slice(0, Math.max(0, pool.inFlightIds.length - 1));
+    return { ...pool, inFlight: next.length, inFlightIds: next };
+  }
+  state;
+  env;
+  constructor(state, env) {
+    this.state = state;
+    this.env = env;
+  }
+  async fetch(request) {
+    const url = new URL(request.url);
+    if (url.pathname === "/ws" && request.headers.get("Upgrade") === "websocket") {
+      return this.handleWebSocketUpgrade();
+    }
+    switch (`${request.method} ${url.pathname}`) {
+      case "GET /dead": {
+        return this.handleDeadList();
+      }
+      case "GET /get": {
+        return this.handleGet(url);
+      }
+      case "GET /list": {
+        return this.handleList();
+      }
+      case "GET /pool": {
+        return this.handlePoolStatus(url);
+      }
+      case "GET /status": {
+        return this.handleStatus();
+      }
+      case "POST /cancel": {
+        return this.handleCancel(request);
+      }
+      case "POST /complete": {
+        return this.handleComplete(request);
+      }
+      case "POST /dead/cancel": {
+        return this.handleDeadCancel(request);
+      }
+      case "POST /dead/retry": {
+        return this.handleDeadRetry(request);
+      }
+      case "POST /schedule": {
+        return this.handleSchedule(request);
+      }
+    }
+    return Response.json(
+      { error: { code: "NOT_FOUND" } },
+      {
+        headers: { "content-type": "application/json" },
+        status: 404
+      }
+    );
+  }
+  /** Called by the Workers runtime when the alarm previously set by `_rescheduleAlarm()` fires. */
+  async alarm() {
+    const now = Date.now();
+    const due = [];
+    const indexEntries = await this.state.storage.list({
+      end: `t:${padTime(now)}:~`,
+      limit: 100,
+      prefix: "t:"
+    });
+    for (const [indexKey, recordId] of indexEntries.entries()) {
+      const dueAt = Number.parseInt(indexKey.slice(2, indexKey.indexOf(":", 2)), 10);
+      if (Number.isFinite(dueAt) && dueAt <= now) {
+        const record = await this.state.storage.get(`${HEADER_PREFIX}${recordId}`);
+        if (record) {
+          due.push(record);
+        }
+      }
+    }
+    const pools = /* @__PURE__ */ new Map();
+    try {
+      for (const record of due) {
+        await this.drainRecordGuarded(record, pools);
+      }
+    } finally {
+      await this.rescheduleAlarm();
+    }
+    if (due.length > 0) {
+      await this.broadcastChange();
+    }
+  }
+  /**
+   * Internal dispatch hook; overridden in unit tests to capture the outgoing
+   * request. Returns `true` ONLY on an explicit 2xx response (`response.ok`).
+   * Anything else — a network failure, a 5xx, OR a non-2xx such as 404
+   * (receiver route not mounted) / 401 / 403 / 4xx — returns `false` and
+   * enters the retry pipeline via {@link recordRetry}. Treating 4xx as
+   * success used to permanently delete the job; since the receiver may simply
+   * be missing (404) or transiently failing, we retry rather than silently
+   * drop. After {@link MAX_RETRY_ATTEMPTS} the record is parked under a
+   * `dead:` key for inspection — never silently deleted.
+   *
+   * The dispatch target is taken from `env.LUNORA_ORIGIN_URL` (NOT from the
+   * stored record) to prevent SSRF via a forged `originUrl` on the schedule
+   * request. If that env var is missing at fire time (a deploy/binding
+   * regression — schedule time already enforced its presence) we return
+   * `false` so the record is retried rather than silently dropped.
+   */
+  async dispatch(record) {
+    const originUrl = typeof this.env.LUNORA_ORIGIN_URL === "string" && this.env.LUNORA_ORIGIN_URL.length > 0 ? this.env.LUNORA_ORIGIN_URL : void 0;
+    if (!originUrl) {
+      return false;
+    }
+    const body = JSON.stringify({
+      args: record.args,
+      functionPath: record.functionPath,
+      id: record.id,
+      // Echoed so the receiver can call back the SAME DO instance.
+      instanceName: record.instanceName,
+      // When the job belongs to a workpool, the receiver must report
+      // completion back to the SchedulerDO (`POST /complete { pool, id }`)
+      // so the pool's concurrency slot is released — see handleComplete().
+      pool: record.pool,
+      scheduledFor: record.scheduledFor,
+      shardKey: record.shardKey
+    });
+    try {
+      const headers = { "content-type": "application/json" };
+      const signature = await this.signDispatch(body);
+      if (signature !== void 0) {
+        headers["x-lunora-scheduler-signature"] = signature;
+      } else if (typeof this.env.LUNORA_ADMIN_TOKEN === "string" && this.env.LUNORA_ADMIN_TOKEN.length > 0) {
+        headers.authorization = `Bearer ${this.env.LUNORA_ADMIN_TOKEN}`;
+      }
+      const response = await fetch(`${originUrl}/_lunora/scheduler/dispatch`, {
+        body,
+        headers,
+        method: "POST"
+      });
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Claim + drain one due record with per-record fault isolation, so a storage
+   * throw can never abort the whole alarm pass (which would skip the remaining
+   * due records and the `rescheduleAlarm()` that re-arms the clock).
+   *
+   * Claims the job by deleting its time-index entry BEFORE dispatch (an alarm
+   * re-fire then won't pick it up again), runs {@link drainRecord}, and on a
+   * thrown storage op decides whether the job stays re-fireable.
+   *
+   * When the record was NOT successfully dispatched, re-assert the time-index
+   * claim so a later alarm re-attempts it (at-least-once): the claim delete may
+   * have removed it and recordRetry()/requeuePooled() may not have re-armed it
+   * before throwing, and re-inserting the same key is idempotent, so a
+   * surviving claim is simply rewritten to its prior value. When the record WAS
+   * dispatched (the throw came from post-dispatch cleanup), leave the index
+   * deleted so the already-kicked, idempotent job is not re-fired.
+   */
+  async drainRecordGuarded(record, pools) {
+    let dispatched = false;
+    try {
+      await this.state.storage.delete(SchedulerDO.indexKey(record.scheduledFor, record.id));
+      dispatched = await this.drainRecord(record, pools);
+    } catch {
+      if (!dispatched) {
+        try {
+          await this.state.storage.put(SchedulerDO.indexKey(record.scheduledFor, record.id), record.id);
+        } catch {
+        }
+      }
+    }
+  }
+  /**
+   * Process one due (already index-claimed) record within an alarm drain:
+   * apply the workpool concurrency gate, dispatch, and settle the result.
+   * A saturated pool re-arms the job (backpressure, no attempt charged); a
+   * free slot is reserved durably before dispatch and released immediately if
+   * the kick fails (success holds it until the runtime reports completion).
+   * Success clears the `id:`/`retry:` rows; failure routes to
+   * {@link recordRetry}. `pools` caches each pool's {@link PoolState} for the
+   * lifetime of the drain so the budget decrements without re-reading storage.
+   * @returns `true` only when the record was successfully dispatched (a 2xx
+   * kick). The caller ({@link drainRecordGuarded}) uses this in its per-record
+   * error guard: a record that returns `true` (or whose post-dispatch cleanup
+   * later throws) must NOT have its time-index claim restored, since re-firing
+   * an already-kicked job would break idempotency. A `false` return (pool
+   * backpressure or a failed dispatch) means the job is still re-fireable —
+   * either already re-armed here, or, if a throw escapes, re-claimed by the
+   * guard's catch.
+   */
+  async drainRecord(record, pools) {
+    const reserved = await this.reservePoolSlot(record, pools);
+    if (!reserved) {
+      return false;
+    }
+    const ok = await this.dispatch(record);
+    if (!ok && record.pool !== void 0) {
+      const pool = pools.get(record.pool);
+      if (pool !== void 0) {
+        const released = SchedulerDO.releaseSlot(pool, record.id);
+        pools.set(record.pool, released);
+        await this.savePool(record.pool, released);
+      }
+    }
+    if (ok) {
+      try {
+        await this.state.storage.delete([`${HEADER_PREFIX}${record.id}`, `${RETRY_PREFIX}${record.id}`]);
+      } catch {
+      }
+      return true;
+    }
+    await this.recordRetry(record);
+    return false;
+  }
+  /**
+   * Concurrency gate for a pooled record. Returns `false` (and re-arms the
+   * job via {@link requeuePooled}) when the pool is at `maxConcurrency`;
+   * otherwise reserves a slot durably and returns `true`. Non-pooled records
+   * always return `true` without touching any pool state.
+   */
+  async reservePoolSlot(record, pools) {
+    if (record.pool === void 0) {
+      return true;
+    }
+    const pool = pools.get(record.pool) ?? await this.loadPool(record.pool);
+    pools.set(record.pool, pool);
+    if (pool.inFlight >= pool.maxConcurrency) {
+      await this.requeuePooled(record);
+      return false;
+    }
+    const ids = pool.inFlightIds ?? [];
+    if (!ids.includes(record.id)) {
+      ids.push(record.id);
+    }
+    pool.inFlightIds = ids;
+    pool.inFlight = ids.length;
+    await this.savePool(record.pool, pool);
+    return true;
+  }
+  /**
+   * Accept a hibernatable live subscription to the job list. The scheduler has
+   * exactly one subscription shape (the whole list), so there's no per-socket
+   * registry or dependency tracking — every accepted socket gets the full list
+   * on connect and on every change. The worker is responsible for gating the
+   * upgrade behind the admin token before it reaches here.
+   */
+  async handleWebSocketUpgrade() {
+    if (this.state.acceptWebSocket === void 0) {
+      return SchedulerDO.error(501, "WS_UNSUPPORTED", "WebSocket subscriptions are not supported in this runtime");
+    }
+    const pair = new WebSocketPair();
+    const client = pair[0];
+    const server = pair[1];
+    this.state.acceptWebSocket(server);
+    server.send(JSON.stringify({ records: await this.listRecords(), type: "jobs" }));
+    return new Response(null, { status: 101, webSocket: client });
+  }
+  /**
+   * Re-list the jobs and push them to every connected subscriber. Called after
+   * any change (schedule / cancel / alarm-fire) so live studios reflect it
+   * immediately. A no-op when the runtime doesn't support hibernated sockets.
+   */
+  async broadcastChange() {
+    const sockets = this.state.getWebSockets?.();
+    if (sockets === void 0 || sockets.length === 0) {
+      return;
+    }
+    const message = JSON.stringify({ records: await this.listRecords(), type: "jobs" });
+    for (const socket of sockets) {
+      try {
+        socket.send(message);
+      } catch {
+      }
+    }
+  }
+  /** The current pending job records (shared by `/list` and the live channel). */
+  async listRecords() {
+    const entries = await this.state.storage.list({ prefix: HEADER_PREFIX });
+    return [...entries.values()];
+  }
+  /**
+   * HMAC-SHA-256 sign the dispatch body with `env.LUNORA_SCHEDULER_SECRET`,
+   * returning a base64url signature, or `undefined` when no secret is
+   * configured. Mirrors `@lunora/storage`'s signed-URL HMAC pattern (WebCrypto
+   * `crypto.subtle`, available in workerd).
+   */
+  async signDispatch(body) {
+    const secret = typeof this.env.LUNORA_SCHEDULER_SECRET === "string" ? this.env.LUNORA_SCHEDULER_SECRET : void 0;
+    if (!secret || secret.length === 0) {
+      return void 0;
+    }
+    const encoder = new TextEncoder();
+    const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { hash: "SHA-256", name: "HMAC" }, false, ["sign"]);
+    const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(body));
+    const bytes = new Uint8Array(signature);
+    let binary = "";
+    for (const byte of bytes) {
+      binary += String.fromCodePoint(byte);
+    }
+    return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+  }
+  /**
+   * Move a failed record into the retry pipeline with configurable backoff.
+   * The retry budget/backoff comes from the record's {@link RetryPolicy}
+   * (falling back to the DO defaults); on exhaustion the record is parked
+   * under a `dead:` key for manual inspection.
+   */
+  async recordRetry(record) {
+    const attempts = (record.attempts ?? 0) + 1;
+    const { backoff, baseMs, maxAttempts, maxMs } = SchedulerDO.resolveRetry(record);
+    if (attempts > maxAttempts) {
+      await this.state.storage.put(`${DEAD_PREFIX}${record.id}`, { ...record, attempts });
+      await this.state.storage.delete([`${RETRY_PREFIX}${record.id}`, `${HEADER_PREFIX}${record.id}`]);
+      return;
+    }
+    const rawDelay = backoff === "linear" ? baseMs * attempts : baseMs * 2 ** (attempts - 1);
+    const delayMs = maxMs === void 0 ? rawDelay : Math.min(rawDelay, maxMs);
+    const nextScheduledFor = Date.now() + delayMs;
+    const retryRecord = {
+      ...record,
+      attempts,
+      scheduledFor: nextScheduledFor
+    };
+    await this.state.storage.put(`${RETRY_PREFIX}${record.id}`, retryRecord);
+    await this.state.storage.put(`${HEADER_PREFIX}${record.id}`, retryRecord);
+    await this.state.storage.put(SchedulerDO.indexKey(nextScheduledFor, record.id), record.id);
+  }
+  /** Read the durable `pool:&lt;name>` row, defaulting to a fresh `inFlight: 0` pool. */
+  async loadPool(name, maxConcurrencyHint) {
+    const stored = await this.state.storage.get(`${POOL_PREFIX}${name}`);
+    if (stored !== void 0) {
+      if (Array.isArray(stored.inFlightIds)) {
+        return { inFlight: stored.inFlightIds.length, inFlightIds: [...stored.inFlightIds], maxConcurrency: stored.maxConcurrency };
+      }
+      return { inFlight: Math.max(0, stored.inFlight), maxConcurrency: stored.maxConcurrency };
+    }
+    return { inFlight: 0, inFlightIds: [], maxConcurrency: SchedulerDO.normalizeConcurrency(maxConcurrencyHint, 1) };
+  }
+  async savePool(name, pool) {
+    await this.state.storage.put(`${POOL_PREFIX}${name}`, pool);
+  }
+  /**
+   * Re-arm a pooled job that couldn't run because its pool was at capacity.
+   * No attempt is charged (this is backpressure, not a failure): the job is
+   * pushed `POOL_BACKPRESSURE_DELAY_MS` into the future so a later alarm
+   * drains it once a slot frees, keeping its `id:` header and retry policy.
+   */
+  async requeuePooled(record) {
+    const nextScheduledFor = Date.now() + POOL_BACKPRESSURE_DELAY_MS;
+    const requeued = { ...record, scheduledFor: nextScheduledFor };
+    await this.state.storage.put(`${HEADER_PREFIX}${record.id}`, requeued);
+    await this.state.storage.put(SchedulerDO.indexKey(nextScheduledFor, record.id), record.id);
+  }
+  /**
+   * Release a pool slot when the runtime reports an action finished. This is
+   * the durable-semaphore decrement: dispatch() only KICKS the action and
+   * holds the slot; the runtime calls back here (`POST /complete { id }`) once
+   * the action settles, freeing the slot for the next queued job. Idempotent
+   * and safe if the job/pool is already gone.
+   */
+  async handleComplete(request) {
+    const body = await request.json().catch(() => void 0);
+    const poolName = typeof body?.pool === "string" && body.pool.length > 0 ? body.pool : void 0;
+    const jobId = typeof body?.id === "string" && body.id.length > 0 ? body.id : void 0;
+    if (poolName === void 0) {
+      return SchedulerDO.error(400, "INVALID_INPUT", "pool is required");
+    }
+    const pool = await this.loadPool(poolName);
+    const next = jobId === void 0 ? SchedulerDO.releaseFirstSlot(pool) : SchedulerDO.releaseSlot(pool, jobId);
+    await this.savePool(poolName, next);
+    await this.armAlarmIfEarlier(Date.now());
+    return SchedulerDO.json({ inFlight: next.inFlight });
+  }
+  /** `GET /pool?name=` — inspect a pool's slot usage + queued count. */
+  async handlePoolStatus(url) {
+    const name = url.searchParams.get("name");
+    if (name === null || name.length === 0) {
+      return SchedulerDO.error(400, "INVALID_INPUT", "name is required");
+    }
+    const pool = await this.loadPool(name);
+    const headers = await this.state.storage.list({ prefix: HEADER_PREFIX });
+    let queued = 0;
+    for (const record of headers.values()) {
+      if (record.pool === name) {
+        queued += 1;
+      }
+    }
+    return SchedulerDO.json({ inFlight: pool.inFlight, maxConcurrency: pool.maxConcurrency, queued });
+  }
+  /**
+   * `GET /status` — the app-level backlog signal that powers the studio's
+   * SLO view. Enumerates every durable `pool:&lt;name>` row for its `inFlight`/
+   * `maxConcurrency` semaphore, counts the pending (not-yet-dispatched) jobs
+   * routed to each pool with the same single-pass scan {@link handlePoolStatus}
+   * uses, and rolls those up into app-wide `backlog` (sum of `queued`) and
+   * `inFlight` (sum of held slots) totals.
+   *
+   * Pools that have rows but no queued jobs still appear (with `queued: 0`) so
+   * a saturated-but-idle pool stays visible; a pool that only ever existed as
+   * queued jobs without a persisted row is unreachable here (the schedule path
+   * always writes a `pool:&lt;name>` row before the job's header), so a single
+   * scan over `pool:`/`id:` is sufficient.
+   */
+  async handleStatus() {
+    const poolRows = await this.state.storage.list({ prefix: POOL_PREFIX });
+    const headers = await this.state.storage.list({ prefix: HEADER_PREFIX });
+    const queuedByPool = /* @__PURE__ */ new Map();
+    for (const record of headers.values()) {
+      if (record.pool !== void 0) {
+        queuedByPool.set(record.pool, (queuedByPool.get(record.pool) ?? 0) + 1);
+      }
+    }
+    const pools = [];
+    let backlog = 0;
+    let inFlight = 0;
+    for (const [key, pool] of poolRows.entries()) {
+      const name = key.slice(POOL_PREFIX.length);
+      const slots = Math.max(0, pool.inFlight);
+      const queued = queuedByPool.get(name) ?? 0;
+      pools.push({ inFlight: slots, maxConcurrency: pool.maxConcurrency, name, queued });
+      backlog += queued;
+      inFlight += slots;
+    }
+    const status = { backlog, inFlight, pools };
+    return SchedulerDO.json(status);
+  }
+  async handleSchedule(request) {
+    const body = await request.json().catch(() => void 0);
+    if (!body || typeof body.functionPath !== "string") {
+      return SchedulerDO.error(400, "INVALID_INPUT", "functionPath is required");
+    }
+    if (typeof body.scheduledFor !== "number" || !Number.isInteger(body.scheduledFor) || body.scheduledFor <= 0 || body.scheduledFor > MAX_SCHEDULED_FOR_MS) {
+      return SchedulerDO.error(400, "INVALID_INPUT", "scheduledFor must be a positive integer epoch-millisecond number no greater than 8640000000000000");
+    }
+    if (typeof this.env.LUNORA_ORIGIN_URL !== "string" || this.env.LUNORA_ORIGIN_URL.length === 0) {
+      return SchedulerDO.error(500, "ORIGIN_NOT_CONFIGURED", "LUNORA_ORIGIN_URL env binding must be set on the SchedulerDO");
+    }
+    const pool = typeof body.pool === "string" && body.pool.length > 0 ? body.pool : void 0;
+    const instanceName = typeof body.instanceName === "string" && body.instanceName.length > 0 ? body.instanceName : void 0;
+    const retry = SchedulerDO.normalizeRetry(body.retry);
+    const id = generateId();
+    const record = {
+      // body is parsed from an untrusted request; args may be absent at runtime
+      // despite the type, so the ?? fallback is a real guard.
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- parsed wire data can omit args
+      args: body.args ?? {},
+      enqueuedAt: Date.now(),
+      functionPath: body.functionPath,
+      id,
+      ...instanceName === void 0 ? {} : { instanceName },
+      ...pool === void 0 ? {} : { pool },
+      ...retry === void 0 ? {} : { retry },
+      scheduledFor: body.scheduledFor,
+      shardKey: body.shardKey
+    };
+    if (pool !== void 0) {
+      const current = await this.loadPool(pool, body.maxConcurrency);
+      await this.savePool(pool, {
+        inFlight: current.inFlight,
+        // Preserve the in-flight id set so refreshing the cap on a new
+        // enqueue can't wipe the held-slot bookkeeping (which would let
+        // a later /complete over-release).
+        ...current.inFlightIds === void 0 ? {} : { inFlightIds: current.inFlightIds },
+        maxConcurrency: SchedulerDO.normalizeConcurrency(body.maxConcurrency, current.maxConcurrency)
+      });
+    }
+    await this.state.storage.put(`${HEADER_PREFIX}${id}`, record);
+    await this.state.storage.put(SchedulerDO.indexKey(record.scheduledFor, id), id);
+    await this.armAlarmIfEarlier(record.scheduledFor);
+    await this.broadcastChange();
+    return SchedulerDO.json({ id, scheduledFor: record.scheduledFor });
+  }
+  async handleCancel(request) {
+    const body = await request.json().catch(() => void 0);
+    if (!body?.id) {
+      return SchedulerDO.error(400, "INVALID_INPUT", "id is required");
+    }
+    const record = await this.state.storage.get(`${HEADER_PREFIX}${body.id}`);
+    if (!record) {
+      return SchedulerDO.json({ cancelled: false });
+    }
+    await this.removeRecord(record);
+    await this.rescheduleAlarm();
+    await this.broadcastChange();
+    return SchedulerDO.json({ cancelled: true });
+  }
+  async handleList() {
+    return SchedulerDO.json({ records: await this.listRecords() });
+  }
+  /**
+   * `GET /dead` — list the dead-letter records: jobs that exhausted their
+   * retry budget ({@link recordRetry}) and were parked under `dead:&lt;id>`
+   * instead of being silently dropped. These never appear in `/list` (their
+   * `id:` header is deleted on park), so this is the ONLY way the studio can
+   * surface — and recover — a permanently-failed job.
+   */
+  async handleDeadList() {
+    const entries = await this.state.storage.list({ prefix: DEAD_PREFIX });
+    return SchedulerDO.json({ records: [...entries.values()] });
+  }
+  /**
+   * `POST /dead/retry { id }` — resurrect a dead-letter record: reset its
+   * exhausted attempt count to 0 (a fresh retry budget), re-arm it for
+   * immediate dispatch via the standard time index, and drop the `dead:` row.
+   * The new `id:` header makes it visible to `/list` and the live `/ws`
+   * subscription again. A miss is a no-op (`{ retried: false }`).
+   */
+  async handleDeadRetry(request) {
+    const body = await request.json().catch(() => void 0);
+    if (typeof body?.id !== "string" || body.id.length === 0) {
+      return SchedulerDO.error(400, "INVALID_INPUT", "id is required");
+    }
+    const dead = await this.state.storage.get(`${DEAD_PREFIX}${body.id}`);
+    if (dead === void 0) {
+      return SchedulerDO.json({ retried: false });
+    }
+    const scheduledFor = Date.now();
+    const revived = { ...dead, attempts: 0, scheduledFor };
+    await this.state.storage.put(`${HEADER_PREFIX}${dead.id}`, revived);
+    await this.state.storage.put(SchedulerDO.indexKey(scheduledFor, dead.id), dead.id);
+    await this.state.storage.delete(`${DEAD_PREFIX}${dead.id}`);
+    await this.armAlarmIfEarlier(scheduledFor);
+    await this.broadcastChange();
+    return SchedulerDO.json({ id: dead.id, retried: true, scheduledFor });
+  }
+  /**
+   * `POST /dead/cancel { id }` — permanently drop a dead-letter record the
+   * operator has decided not to recover. Returns `{ removed }` (false when
+   * nothing matched). Idempotent: a repeated purge is a harmless no-op.
+   */
+  async handleDeadCancel(request) {
+    const body = await request.json().catch(() => void 0);
+    if (typeof body?.id !== "string" || body.id.length === 0) {
+      return SchedulerDO.error(400, "INVALID_INPUT", "id is required");
+    }
+    const removed = await this.state.storage.delete(`${DEAD_PREFIX}${body.id}`);
+    return SchedulerDO.json({ removed: Boolean(removed) });
+  }
+  /**
+   * Resolve a single pending job by id via a direct `id:&lt;id>` storage read —
+   * O(1), versus scanning the whole `/list` view. Responds `{ record }` on a
+   * hit and `{}` on a miss (an absent `record` field — JSON has no `undefined`
+   * — which the client reads back as `null`).
+   */
+  async handleGet(url) {
+    const id = url.searchParams.get("id");
+    if (id === null || id.length === 0) {
+      return SchedulerDO.error(400, "INVALID_INPUT", "id is required");
+    }
+    const record = await this.state.storage.get(`${HEADER_PREFIX}${id}`);
+    return SchedulerDO.json(record === void 0 ? {} : { record });
+  }
+  async removeRecord(record) {
+    await this.state.storage.delete([`${HEADER_PREFIX}${record.id}`, SchedulerDO.indexKey(record.scheduledFor, record.id), `${RETRY_PREFIX}${record.id}`]);
+  }
+  /**
+   * Arm the alarm for `scheduledFor` only if it is sooner than the currently
+   * set alarm (or none is set). Used on the schedule path: inserting a job
+   * can only ever pull the earliest-pending time *earlier*, never later, so a
+   * full `t:` rescan is unnecessary unless the new job is the new earliest.
+   */
+  async armAlarmIfEarlier(scheduledFor) {
+    const current = await this.state.storage.getAlarm();
+    if (current === null || scheduledFor < current) {
+      await this.state.storage.setAlarm(scheduledFor);
+    }
+  }
+  async rescheduleAlarm() {
+    const entries = await this.state.storage.list({ limit: 1, prefix: "t:" });
+    const first = entries.entries().next();
+    if (first.done) {
+      await this.state.storage.deleteAlarm();
+      return;
+    }
+    const [indexKey] = first.value;
+    const dueAt = Number.parseInt(indexKey.slice(2, indexKey.indexOf(":", 2)), 10);
+    if (Number.isFinite(dueAt)) {
+      await this.state.storage.setAlarm(dueAt);
+    }
+  }
+}
+
+export { SchedulerDO };