@lunora/scheduler 0.0.0 → 1.0.0-alpha.2

package/dist/index.d.ts

@@ -0,0 +1,803 @@
+/**
+* Opaque reference to a Lunora function. Mirrors the `FunctionReference` shape
+* emitted by `@lunora/codegen` (and consumed by `@lunora/client`). We avoid a
+* direct dependency to keep this package usable from the codegen pipeline
+* itself.
+*
+* The runtime identifier lives in `__lunoraRef` — this MUST stay in lockstep
+* with the codegen emit + `@lunora/client`'s `FunctionReference`.
+*/
+interface FunctionReference {
+  readonly __lunoraRef: string;
+  /** Marker phantom type — discriminates queries / mutations / actions. */
+  readonly _kind?: "query" | "mutation" | "action";
+}
+type ArgsOf<F extends FunctionReference> = F extends {
+  _args?: infer A;
+} ? A : Record<string, unknown>;
+/**
+* Typed reference to a Lunora durable workflow — either the generated
+* `workflows.&lt;name>` reference object (`_generated/api.ts`, which carries the
+* `WORKFLOW_*` binding + export name) or, structurally, a `defineWorkflow()`
+* result imported directly. Both are matched by the `isLunoraWorkflow` brand and
+* carry the workflow's `params` in the phantom `__params`, so a `cronJobs()`
+* registration infers them.
+*
+* Declared structurally here so `@lunora/scheduler` can let a `cronJobs()`
+* builder target a workflow without depending on `@lunora/workflow` (and so the
+* generated `workflows.*` object needs no `@lunora/scheduler` import — it
+* matches structurally). A cron whose target is a {@link WorkflowReference}
+* starts a new workflow INSTANCE on each fire (the args become its `params`)
+* instead of dispatching a one-shot function. `@lunora/codegen` resolves the
+* concrete `lunora/workflows.ts` export statically; the runtime brand here is
+* the authoring-time guard.
+*/
+interface WorkflowReference<Params = Record<string, unknown>> {
+  /** Phantom carrier for the workflow's `params` type — drives `cronJobs()` arg inference. Never read at runtime. */
+  readonly __params?: Params;
+  /** The `WORKFLOW_*` binding name (present on a generated `workflows.&lt;name>` ref). */
+  readonly binding?: string;
+  readonly isLunoraWorkflow: true;
+  /** The workflow's export/stable name (present on a generated ref; a `defineWorkflow({ name })` override otherwise). */
+  readonly name?: string;
+}
+/** A cron job's target: either a one-shot function dispatch or a durable workflow start. */
+type CronTarget = FunctionReference | WorkflowReference;
+/** The arguments a cron's target accepts: a workflow's inferred `params`, else an open record (function args aren't inferred). */
+type CronTargetArgs<T extends CronTarget> = T extends WorkflowReference<infer Params> ? Params : Record<string, unknown>;
+/** Narrow a {@link CronTarget} to a {@link WorkflowReference} by its runtime brand. */
+declare const isWorkflowReference: (target: unknown) => target is WorkflowReference;
+/**
+* Per-job retry policy. Wired into the SchedulerDO's existing attempts/backoff
+* machinery. When omitted, the DO falls back to its built-in defaults
+* (`maxAttempts: 5`, `backoff: "exponential"`, `baseMs: 30_000`) so existing
+* `runAfter`/`runAt` callers keep today's behaviour unchanged.
+*
+* On exhaustion (attempts > `maxAttempts`) the record is parked under the
+* `dead:` dead-letter key for inspection — never silently dropped.
+*/
+interface RetryPolicy {
+  /**
+  * Backoff growth across attempts. `"exponential"` doubles the delay each
+  * attempt (`baseMs * 2 ** (attempt - 1)`); `"linear"` grows it linearly
+  * (`baseMs * attempt`). Default `"exponential"`.
+  */
+  backoff?: "exponential" | "linear";
+  /** Base delay in milliseconds for the first retry. Default `30_000`. */
+  baseMs?: number;
+  /** Maximum number of dispatch attempts before dead-lettering. Default `5`. */
+  maxAttempts?: number;
+  /** Optional ceiling clamping the computed backoff delay. */
+  maxMs?: number;
+}
+interface RunOptions {
+  /**
+  * Logical workpool this job belongs to. When set, the SchedulerDO gates the
+  * job behind the pool's `maxConcurrency` (see {@link WorkpoolOptions}).
+  * Usually populated by {@link Workpool.enqueue}; callers rarely set it on a
+  * bare `runAfter`/`runAt`.
+  */
+  pool?: string;
+  /** Per-job retry policy. Falls back to the DO's built-in defaults when omitted. */
+  retry?: RetryPolicy;
+  /** Routing hint — forwarded to the Worker so the call lands on the right shard. */
+  shardKey?: string;
+}
+interface ScheduleRecord {
+  args: Record<string, unknown>;
+  /**
+  * Number of dispatch attempts already made. Absent (treated as 0) until the
+  * first failure, after which `recordRetry()` persists it on both the
+  * `retry:` row and the `id:` header. Surfaced here so `/list` consumers and
+  * the studio see the field the storage layer actually writes.
+  */
+  attempts?: number;
+  enqueuedAt: number;
+  functionPath: string;
+  id: string;
+  /**
+  * Scheduler/workpool instance name the job was enqueued through. Echoed in
+  * the dispatch payload so the runtime can call back the SAME DO instance's
+  * `/complete` to release a pooled slot. Absent for the default instance.
+  */
+  instanceName?: string;
+  /**
+  * Logical workpool this job belongs to (set by {@link Workpool.enqueue}).
+  * When present, the SchedulerDO only dispatches the job while the pool's
+  * in-flight count is below its `maxConcurrency`; otherwise it stays queued
+  * and drains as slots free. Absent for plain `runAfter`/`runAt` jobs, which
+  * are never concurrency-gated.
+  */
+  pool?: string;
+  /** Per-job retry policy (see {@link RetryPolicy}); absent means DO defaults. */
+  retry?: RetryPolicy;
+  scheduledFor: number;
+  shardKey?: string;
+}
+interface Scheduler {
+  cancel: (id: string) => Promise<{
+    cancelled: boolean;
+  }>;
+  /** Resolve a single pending job by id, or `null` when absent (derived from {@link Scheduler.list}). */
+  get: (id: string) => Promise<ScheduleRecord | null>;
+  /** All pending scheduled jobs (the DO's `/list` view). */
+  list: () => Promise<ScheduleRecord[]>;
+  runAfter: <F extends FunctionReference>(delayMs: number, function_: F, args: ArgsOf<F>, options?: RunOptions) => Promise<{
+    id: string;
+    scheduledFor: number;
+  }>;
+  runAt: <F extends FunctionReference>(date: Date | number, function_: F, args: ArgsOf<F>, options?: RunOptions) => Promise<{
+    id: string;
+    scheduledFor: number;
+  }>;
+}
+/**
+* Cloudflare Durable Object data-residency jurisdiction. Widening union —
+* Cloudflare adds values over time.
+* @see https://developers.cloudflare.com/durable-objects/reference/data-location/
+*/
+type DurableObjectJurisdiction = "eu" | "fedramp" | "us";
+/** Subset of `DurableObjectNamespace` the package consumes. */
+interface DurableObjectNamespaceLike {
+  get: (id: DurableObjectIdLike) => DurableObjectStubLike;
+  idFromName: (name: string) => DurableObjectIdLike;
+  /**
+  * Derive a jurisdiction-restricted subnamespace. Optional because older
+  * workers-types releases (and test doubles) may not expose it.
+  */
+  jurisdiction?: (jurisdiction: DurableObjectJurisdiction) => DurableObjectNamespaceLike;
+}
+interface DurableObjectIdLike {
+  toString: () => string;
+}
+interface DurableObjectStubLike {
+  fetch: (input: Request | string, init?: RequestInit) => Promise<Response>;
+}
+interface LunoraSchedulerOptions {
+  /** Optional named instance — useful for tenant isolation. Default `default`. */
+  instanceName?: string;
+  /**
+  * Pin the SchedulerDO (durable timers + cron state) to a Cloudflare
+  * data-residency jurisdiction. Pass the same value as the worker's
+  * `jurisdiction` so scheduled state co-resides with app data. Omit for the
+  * un-pinned global namespace.
+  */
+  jurisdiction?: DurableObjectJurisdiction;
+  /** Binding to the `SchedulerDO` durable object namespace. */
+  namespace: DurableObjectNamespaceLike;
+  /**
+  * Origin where the Worker is mounted. SchedulerDO uses this base URL when
+  * dispatching scheduled functions back to the Worker on alarm fire.
+  */
+  originUrl: string;
+}
+/** Per-enqueue options for a {@link Workpool}. Extends {@link RunOptions} minus the implicit `pool` (the pool sets that). */
+interface EnqueueOptions {
+  /** Run the job no sooner than this delay (ms) from now. Default `0` (next drain). */
+  delayMs?: number;
+  /** Per-job retry policy. Falls back to the DO's built-in defaults when omitted. */
+  retry?: RetryPolicy;
+  /** Routing hint — forwarded to the Worker so the call lands on the right shard. */
+  shardKey?: string;
+}
+/**
+* Options for `createWorkpool`. Mirrors {@link LunoraSchedulerOptions}
+* (same `namespace` / `originUrl` / `instanceName`) plus the bounded-concurrency
+* controls. A workpool is a NAMED logical pool inside the existing SchedulerDO —
+* it needs no extra Durable Object or wrangler binding beyond the SchedulerDO
+* the scheduler already uses.
+*/
+interface WorkpoolOptions extends LunoraSchedulerOptions {
+  /**
+  * Maximum number of jobs from this pool that may be in flight at once.
+  * Excess enqueues are persisted and drain as slots free. Must be a positive
+  * integer.
+  */
+  maxConcurrency: number;
+  /**
+  * Pool name — the concurrency counter is keyed by this inside the
+  * SchedulerDO storage (`pool:&lt;name>`). Default `default`.
+  */
+  name?: string;
+}
+/**
+* Bounded-concurrency action queue (Lunora equivalent of `@convex-dev/workpool`).
+* Built on the existing SchedulerDO: `enqueue` schedules a job tagged with this
+* pool's name; the DO caps simultaneous dispatch at `maxConcurrency` and queues
+* the rest durably.
+*/
+interface Workpool {
+  /** Cancel a queued/in-flight pool job by id. */
+  cancel: (id: string) => Promise<{
+    cancelled: boolean;
+  }>;
+  /**
+  * Enqueue `function_(args)` into the pool. Resolves with the durable job id
+  * and the time it was scheduled for (it may not run immediately if the pool
+  * is at capacity).
+  */
+  enqueue: <F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: EnqueueOptions) => Promise<{
+    id: string;
+    scheduledFor: number;
+  }>;
+  /** The pool's name (the `pool:&lt;name>` storage key suffix). */
+  readonly name: string;
+  /** Inspect the pool's current state — `inFlight` slots used and the configured `maxConcurrency`. */
+  status: () => Promise<{
+    inFlight: number;
+    maxConcurrency: number;
+    queued: number;
+  }>;
+}
+/** Per-message options for {@link QueueLike.send} — the subset Lunora uses. */
+interface QueueSendOptionsLike {
+  /** Delay delivery to the consumer by this many seconds. */
+  delaySeconds?: number;
+}
+/** One message in a `sendBatch` call. */
+interface QueueSendRequestLike<Body = unknown> {
+  body: Body;
+  delaySeconds?: number;
+}
+/** Producer side of a Cloudflare Queue binding (the `env` queue binding). */
+interface QueueLike<Body = unknown> {
+  send: (body: Body, options?: QueueSendOptionsLike) => Promise<void>;
+  sendBatch: (messages: Iterable<QueueSendRequestLike<Body>>, options?: QueueSendOptionsLike) => Promise<void>;
+}
+/** One delivered Cloudflare Queue message (consumer side). */
+interface QueueMessageLike<Body = unknown> {
+  /** Marks the message delivered (won't be retried). */
+  ack: () => void;
+  /** 1-based count of delivery attempts so far. */
+  readonly attempts: number;
+  readonly body: Body;
+  readonly id: string;
+  /** Marks the message for retry on a later batch (→ dead-letter after `max_retries`). */
+  retry: (options?: {
+    delaySeconds?: number;
+  }) => void;
+  readonly timestamp: Date;
+}
+/** A batch of messages handed to a `queue()` consumer handler. */
+interface MessageBatchLike<Body = unknown> {
+  /** Mark every message delivered. */
+  ackAll: () => void;
+  readonly messages: ReadonlyArray<QueueMessageLike<Body>>;
+  readonly queue: string;
+  /** Mark every message for retry. */
+  retryAll: (options?: {
+    delaySeconds?: number;
+  }) => void;
+}
+/** The wire payload Lunora puts on the queue: a function dispatch. */
+interface QueueJob {
+  args?: Record<string, unknown>;
+  functionPath: string;
+  /** Routing hint forwarded to the Worker so the call lands on the right shard. */
+  shardKey?: string;
+}
+/** Per-enqueue options for a {@link QueueWorkpool}. */
+interface QueueEnqueueOptions {
+  /** Delay delivery by this many seconds (Queues-native). Default: immediate. */
+  delaySeconds?: number;
+  /** Routing hint — which shard the job should run against. */
+  shardKey?: string;
+}
+/** Options for `createQueueWorkpool`. */
+interface QueueWorkpoolOptions {
+  /** The Cloudflare Queue producer binding to enqueue onto. */
+  queue: QueueLike<QueueJob>;
+}
+/**
+* Queues-backed producer: enqueue function dispatches onto a Cloudflare Queue.
+* Concurrency, retries, and dead-lettering are configured on the queue consumer
+* in `wrangler.jsonc` (`max_concurrency` / `max_retries` / `dead_letter_queue`),
+* not here — that's the whole point of using Queues over the DO workpool.
+*/
+interface QueueWorkpool {
+  /** Enqueue a single `fn(args)` dispatch. */
+  enqueue: <F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: QueueEnqueueOptions) => Promise<void>;
+  /** Enqueue many dispatches in one `sendBatch`. Each job names its function `ref`. */
+  enqueueBatch: (jobs: ReadonlyArray<{
+    args?: Record<string, unknown>;
+    ref: FunctionReference;
+    shardKey?: string;
+  }>, options?: QueueSendOptionsLike) => Promise<void>;
+}
+/** Dispatches a single {@link QueueJob} — the consumer's per-message worker. */
+type QueueDispatch = (job: QueueJob) => Promise<void>;
+/** Options for `createQueueConsumer`. */
+interface QueueConsumerOptions {
+  /** How each job is executed; e.g. the `httpDispatcher`. */
+  dispatch: QueueDispatch;
+}
+/** Options for the `httpDispatcher` — the default HTTP dispatcher. */
+interface HttpDispatcherOptions {
+  /** Admin bearer token the dispatch endpoint accepts (`LUNORA_ADMIN_TOKEN`). */
+  adminToken: string;
+  /** Injectable fetch (tests); defaults to the global. */
+  fetchImpl?: typeof fetch;
+  /** Origin where the Worker is mounted (the `/_lunora/scheduler/dispatch` endpoint). */
+  originUrl: string;
+}
+/**
+* Client-side scheduler — forwards `runAfter` / `runAt` / `cancel` calls to a
+* `SchedulerDO` over HTTP. The DO owns the alarm and the storage; this is a
+* thin RPC wrapper.
+*/
+declare const createScheduler: (options: LunoraSchedulerOptions) => Scheduler;
+/**
+* Bounded-concurrency action queue — the Lunora equivalent of
+* `@convex-dev/workpool`. Mirrors `createScheduler`'s `namespace` /
+* `originUrl` / `instanceName` options and is built on the SAME `SchedulerDO`:
+* a workpool is just a NAMED logical pool inside that DO (concurrency counter
+* keyed by {@link WorkpoolOptions.name} under the `pool:&lt;name>` storage key).
+* It needs no extra Durable Object or wrangler binding beyond the SchedulerDO
+* the scheduler already uses.
+*
+* `enqueue` schedules a job tagged with this pool; the DO dispatches at most
+* `maxConcurrency` of the pool's jobs at once and queues the rest durably,
+* draining them as the runtime reports completions (`POST /complete`).
+*
+* ```ts
+* const pool = createWorkpool({ namespace: env.SCHEDULER, originUrl, maxConcurrency: 5 });
+* await pool.enqueue(internal.stripe.sync, { invoiceId }, { retry: { maxAttempts: 3 } });
+* ```
+*
+* Why not Cloudflare Queues? Queues natively cover concurrency-capped, retried,
+* dead-lettered, delayed dispatch (`max_concurrency`, `max_retries`,
+* `retry({ delaySeconds })`, `dead_letter_queue`), and are the right tool when
+* you just want to rate-limit fire-and-forget background work. This workpool
+* deliberately stays on `SchedulerDO` because it offers what a queue can't: a
+* hard concurrency cap (the DO is the single serialization point — no
+* cross-consumer overshoot), per-job cancellation, and per-job status
+* introspection, all keyed by a stable job id. Reach for Queues when you don't
+* need those; reach for this when you do. Either way, do NOT grow multi-step
+* orchestration on top of this — that's Cloudflare **Workflows** (`step.do` /
+* `step.sleep` / `step.waitForEvent`).
+*/
+declare const createWorkpool: (options: WorkpoolOptions) => Workpool;
+interface CronTriggerOptions {
+  /** Args passed to the function. */
+  args?: Record<string, unknown>;
+  /** The Lunora function to invoke on each trigger fire. */
+  fn: FunctionReference;
+  /** Standard cron expression, e.g. `"0 * * * *"`. */
+  schedule: string;
+}
+interface CronTriggerSnippet {
+  /** Paste these into `wrangler.jsonc` under `triggers.crons`. */
+  crons: string[];
+  /** Routes the Worker should mount to receive the trigger dispatch. */
+  dispatcher: {
+    args: Record<string, unknown>;
+    functionPath: string;
+  };
+  /** Human-readable wrangler.jsonc snippet developers can copy/paste. */
+  wranglerJsonc: string;
+}
+/**
+* Produces the wrangler.jsonc fragment + dispatcher metadata for a recurring
+* function. The actual cron handler is mounted by `@lunora/runtime` — we only
+* emit the configuration here.
+*/
+declare const createCronTrigger: (options: CronTriggerOptions) => CronTriggerSnippet;
+/** Sub-day recurrence. Exactly one unit must be provided. */
+interface IntervalSchedule {
+  hours?: number;
+  minutes?: number;
+  seconds?: number;
+}
+/** Daily recurrence at a fixed UTC wall-clock time. */
+interface DailySchedule {
+  /** 0–23. */
+  hourUTC: number;
+  /** 0–59. */
+  minuteUTC: number;
+}
+/** Weekly recurrence at a fixed UTC time on a given weekday. */
+interface WeeklySchedule extends DailySchedule {
+  /** Long weekday name, case-insensitive (e.g. `"monday"`). */
+  dayOfWeek: "friday" | "monday" | "saturday" | "sunday" | "thursday" | "tuesday" | "wednesday";
+}
+/** Monthly recurrence at a fixed UTC time on a given day-of-month. */
+interface MonthlySchedule extends DailySchedule {
+  /** 1–31. */
+  day: number;
+}
+/**
+* One registered cron job, normalized to a compiled cron expression. Shared
+* verbatim with `@lunora/codegen` (which lifts the same fields out of the AST)
+* and the runtime dispatcher — keep the shape stable across all three.
+*/
+interface CronJob {
+  /** Args forwarded to the function (or, for a workflow target, used as its `params`) on each fire. */
+  args: Record<string, unknown>;
+  /** Compiled standard cron expression, e.g. `"0 9 * * *"`. */
+  cron: string;
+  /**
+  * `__lunoraRef` of the target function. Present for a function target;
+  * absent when the job targets a workflow ({@link CronJob.workflow} instead).
+  */
+  functionPath?: string;
+  /** Human-readable identifier — must be unique within one `cronJobs()`. */
+  name: string;
+  /**
+  * Set when the job targets a durable workflow rather than a function: the
+  * workflow's stable name (`defineWorkflow({ name })`) when one was declared,
+  * otherwise `""`. `@lunora/codegen` statically resolves the concrete
+  * `lunora/workflows.ts` export + its `WORKFLOW_*` binding for the emitted
+  * dispatch map, so this authoring-time value is informational only.
+  */
+  workflow?: string;
+}
+/** The ergonomic builder methods, excluding the raw `.cron` escape hatch. */
+type CronScheduleKind = "daily" | "interval" | "monthly" | "weekly";
+/** The ergonomic schedule kinds as a runtime set (codegen reads this to detect cron builder methods). */
+declare const CRON_SCHEDULE_KINDS: ReadonlySet<CronScheduleKind>;
+/**
+* Compile one of the ergonomic schedule forms into a standard cron expression.
+* Exposed as a pure function so `@lunora/codegen` can reuse the exact same
+* compilation when it statically lifts a `crons.{kind}(...)` call out of the
+* AST — codegen imports this directly (no duplicated mirror).
+*/
+declare const compileCronSchedule: (kind: CronScheduleKind, schedule: DailySchedule | IntervalSchedule | MonthlySchedule | WeeklySchedule) => string;
+/**
+* Builder returned by {@link cronJobs}. Each method registers one recurring
+* job; the compiled expression is validated immediately so authoring mistakes
+* surface at definition time rather than at codegen.
+*/
+interface CronJobsBuilder {
+  /**
+  * Raw cron expression escape hatch (5- or 6-field, full cron-parser grammar).
+  * The target may be a function (`internal.file.fn`) or a durable workflow
+  * (`workflows.&lt;name>`); a workflow's `args` are inferred from its `params`.
+  */
+  cron: <T extends CronTarget>(name: string, cronExpr: string, target: T, args?: CronTargetArgs<T>) => CronJobsBuilder;
+  /** Daily at `hourUTC:minuteUTC` (UTC). The target may be a function or a durable workflow (`workflows.&lt;name>`). */
+  daily: <T extends CronTarget>(name: string, schedule: DailySchedule, target: T, args?: CronTargetArgs<T>) => CronJobsBuilder;
+  /** Every `{ seconds | minutes | hours }`. The target may be a function or a durable workflow (`workflows.&lt;name>`). */
+  interval: <T extends CronTarget>(name: string, schedule: IntervalSchedule, target: T, args?: CronTargetArgs<T>) => CronJobsBuilder;
+  /** Snapshot of the registered jobs, in declaration order. */
+  jobs: () => ReadonlyArray<CronJob>;
+  /** Monthly on `day` at `hourUTC:minuteUTC` (UTC). The target may be a function or a durable workflow (`workflows.&lt;name>`). */
+  monthly: <T extends CronTarget>(name: string, schedule: MonthlySchedule, target: T, args?: CronTargetArgs<T>) => CronJobsBuilder;
+  /** Weekly on `dayOfWeek` at `hourUTC:minuteUTC` (UTC). The target may be a function or a durable workflow (`workflows.&lt;name>`). */
+  weekly: <T extends CronTarget>(name: string, schedule: WeeklySchedule, target: T, args?: CronTargetArgs<T>) => CronJobsBuilder;
+}
+/**
+* Create a code-first cron registry. The returned builder is chainable;
+* codegen discovers a `lunora/crons.ts` default export by AST, not a runtime
+* brand.
+*/
+declare const cronJobs: () => CronJobsBuilder;
+/**
+* Build a Queues producer that enqueues Lunora function dispatches. Concurrency
+* and retry policy live on the consumer's `wrangler.jsonc` config, not here.
+*/
+declare const createQueueWorkpool: (options: QueueWorkpoolOptions) => QueueWorkpool;
+/**
+* Wrap a {@link QueueDispatch} into a Cloudflare `queue()` consumer handler.
+*
+* Each message is dispatched independently (concurrently across the batch). On
+* success the message is `ack()`-ed; on any failure — a thrown dispatcher or a
+* structurally-invalid body — it is `retry()`-ed, so Queues' own `max_retries`
+* + `dead_letter_queue` settings decide when to give up. Nothing is silently
+* dropped: a permanently-bad message rides retries into the dead-letter queue
+* where you can inspect it.
+*/
+declare const createQueueConsumer: (options: QueueConsumerOptions) => ((batch: MessageBatchLike) => Promise<void>);
+/**
+* Default {@link QueueDispatch}: POST each job to the Worker's
+* `/_lunora/scheduler/dispatch` endpoint (the same path SchedulerDO dispatches
+* through), authenticated with the admin bearer. A non-2xx response throws so
+* the consumer retries the message.
+*/
+declare const httpDispatcher: (options: HttpDispatcherOptions) => QueueDispatch;
+/**
+* Minimal projection of `DurableObjectState` for the SchedulerDO. Declared
+* structurally so unit tests can pass a fake state without booting the
+* workers runtime. The WebSocket methods are optional: they back the live
+* `/ws` subscription (push the job list on every change) and are absent in the
+* storage-only fakes, in which case the DO simply serves no live sockets.
+*/
+interface SchedulerDOState {
+  /** Accept a hibernatable server WebSocket (workers `state.acceptWebSocket`). */
+  acceptWebSocket?: (ws: WebSocket) => void;
+  /** Every accepted server WebSocket (workers `state.getWebSockets`). */
+  getWebSockets?: () => WebSocket[];
+  storage: {
+    delete: (key: string | string[]) => Promise<number | boolean>;
+    deleteAlarm: () => Promise<void> | void;
+    get: <T = unknown>(key: string) => Promise<T | undefined>;
+    getAlarm: () => Promise<number | null>;
+    list: <T = unknown>(options?: {
+      end?: string;
+      limit?: number;
+      prefix?: string;
+    }) => Promise<Map<string, T>>;
+    put: <T = unknown>(entries: Record<string, T> | string, value?: T) => Promise<void>;
+    setAlarm: (scheduledTime: number | Date) => Promise<void> | void;
+  };
+}
+interface SchedulerEnv {
+  [key: string]: unknown;
+  /**
+  * Fallback bearer token attached to the dispatch when
+  * {@link SchedulerEnv.LUNORA_SCHEDULER_SECRET} is not configured. Sent as
+  * `authorization: Bearer &lt;token>`.
+  */
+  LUNORA_ADMIN_TOKEN?: string;
+  /**
+  * Base URL where the Worker is mounted. SchedulerDO uses this at dispatch
+  * time to call back into the Worker. Read at fire time (NOT taken from the
+  * request body) to prevent SSRF via a forged `originUrl` field.
+  */
+  LUNORA_ORIGIN_URL?: string;
+  /**
+  * Shared secret used to HMAC-sign the dispatch body so the runtime receiver
+  * can authenticate the call (header `x-lunora-scheduler-signature`). Without
+  * it the dispatch is sent unsigned (optionally bearer-authenticated via
+  * {@link SchedulerEnv.LUNORA_ADMIN_TOKEN}).
+  */
+  LUNORA_SCHEDULER_SECRET?: string;
+}
+/**
+* One pool's live backlog, as surfaced by `GET /status`. `inFlight`/
+* `maxConcurrency` mirror the durable {@link PoolState} semaphore; `queued`
+* is the number of pending (not-yet-dispatched) jobs routed to this pool.
+*/
+interface SchedulerPoolStatus {
+  /** Jobs currently dispatched-but-not-yet-completed (the held slots). */
+  inFlight: number;
+  /** The pool's concurrency cap. */
+  maxConcurrency: number;
+  /** The logical workpool name (the `pool:&lt;name>` suffix). */
+  name: string;
+  /** Pending jobs routed to this pool but not yet dispatched. */
+  queued: number;
+}
+/**
+* App-level scheduler backlog, as returned by `GET /status`. `pools` carries
+* the per-pool breakdown; `backlog` and `inFlight` are the app-wide sums of
+* `queued` and `inFlight` across every pool — the SLO view's headline numbers.
+*/
+interface SchedulerStatus {
+  /** Sum of every pool's `queued` count — the total pending backlog. */
+  backlog: number;
+  /** Sum of every pool's `inFlight` count — the total held concurrency slots. */
+  inFlight: number;
+  /** Per-pool backlog breakdown, one entry per `pool:&lt;name>` record. */
+  pools: SchedulerPoolStatus[];
+}
+/**
+* Durable Object that stores pending scheduled invocations sorted by their
+* `scheduledFor` time and fires them via HTTP on alarm. Storage layout:
+* `id:&lt;id>` maps to {@link ScheduleRecord}; `t:&lt;paddedTime>:&lt;id>` maps to the
+* id (used as a sorted index).
+*
+* On every mutation the DO recomputes the earliest pending task and updates
+* the alarm via `state.storage.setAlarm(time)`.
+*/
+declare class SchedulerDO {
+  private static indexKey;
+  private static json;
+  private static error;
+  /**
+  * 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).
+  */
+  private static resolveRetry;
+  /** Clamp an untrusted `maxConcurrency` to a positive integer, else fall back. */
+  private static normalizeConcurrency;
+  /**
+  * 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.
+  */
+  private static normalizeRetry;
+  /**
+  * 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.
+  */
+  private static releaseSlot;
+  /**
+  * 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.
+  */
+  private static releaseFirstSlot;
+  protected readonly state: SchedulerDOState;
+  protected readonly env: SchedulerEnv;
+  constructor(state: SchedulerDOState, env: SchedulerEnv);
+  fetch(request: Request): Promise<Response>;
+  /** Called by the Workers runtime when the alarm previously set by `_rescheduleAlarm()` fires. */
+  alarm(): Promise<void>;
+  /**
+  * 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.
+  */
+  protected dispatch(record: ScheduleRecord): Promise<boolean>;
+  /**
+  * 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.
+  */
+  private drainRecordGuarded;
+  /**
+  * 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.
+  */
+  private drainRecord;
+  /**
+  * 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.
+  */
+  private reservePoolSlot;
+  /**
+  * 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.
+  */
+  private handleWebSocketUpgrade;
+  /**
+  * 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.
+  */
+  private broadcastChange;
+  /** The current pending job records (shared by `/list` and the live channel). */
+  private listRecords;
+  /**
+  * 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).
+  */
+  private signDispatch;
+  /**
+  * 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.
+  */
+  private recordRetry;
+  /** Read the durable `pool:&lt;name>` row, defaulting to a fresh `inFlight: 0` pool. */
+  private loadPool;
+  private savePool;
+  /**
+  * 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.
+  */
+  private requeuePooled;
+  /**
+  * 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.
+  */
+  private handleComplete;
+  /** `GET /pool?name=` — inspect a pool's slot usage + queued count. */
+  private handlePoolStatus;
+  /**
+  * `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.
+  */
+  private handleStatus;
+  private handleSchedule;
+  private handleCancel;
+  private handleList;
+  /**
+  * `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.
+  */
+  private handleDeadList;
+  /**
+  * `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 }`).
+  */
+  private handleDeadRetry;
+  /**
+  * `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.
+  */
+  private handleDeadCancel;
+  /**
+  * 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`).
+  */
+  private handleGet;
+  private removeRecord;
+  /**
+  * 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.
+  */
+  private armAlarmIfEarlier;
+  private rescheduleAlarm;
+}
+/** Standard cron expression (5- or 6-field) or a supported `@macro`, per `cron-parser`. */
+declare const isValidCronExpression: (schedule: string) => boolean;
+/**
+* Assert a raw cron expression is well-formed, throwing the same shaped error
+* both cron surfaces use. The `context` prefix lets callers name the offending
+* job (`cron job "send digest"`) vs. the bare trigger.
+*/
+declare const assertValidCronExpression: (schedule: string, context?: string) => void;
+export { type ArgsOf, CRON_SCHEDULE_KINDS, type CronJob, type CronJobsBuilder, type CronScheduleKind, type CronTarget, type CronTriggerOptions, type CronTriggerSnippet, type DailySchedule, type DurableObjectIdLike, type DurableObjectJurisdiction, type DurableObjectNamespaceLike, type DurableObjectStubLike, type EnqueueOptions, type FunctionReference, type HttpDispatcherOptions, type IntervalSchedule, type LunoraSchedulerOptions, type MessageBatchLike, type MonthlySchedule, type QueueConsumerOptions, type QueueDispatch, type QueueEnqueueOptions, type QueueJob, type QueueLike, type QueueMessageLike, type QueueSendOptionsLike, type QueueSendRequestLike, type QueueWorkpool, type QueueWorkpoolOptions, type RetryPolicy, type RunOptions, type ScheduleRecord, type Scheduler, SchedulerDO, type SchedulerDOState, type SchedulerEnv, type SchedulerPoolStatus, type SchedulerStatus, type WeeklySchedule, type WorkflowReference, type Workpool, type WorkpoolOptions, assertValidCronExpression, compileCronSchedule, createCronTrigger, createQueueConsumer, createQueueWorkpool, createScheduler, createWorkpool, cronJobs, httpDispatcher, isValidCronExpression, isWorkflowReference };