@lunora/scheduler 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/index.d.ts

@@ -1,12 +1,13 @@
+import { SchedulerHost } from '@lunora/platform';
 /**
-* 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`.
-*/
+ * 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. */
@@ -16,26 +17,26 @@ 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.
-*/
+ * Typed reference to a Lunora durable workflow — either the generated
+ * `workflows.<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). */
+  /** The `WORKFLOW_*` binding name (present on a generated `workflows.<name>` ref). */
   readonly binding?: string;
   readonly isLunoraWorkflow: true;
   /** The workflow's export/stable name (present on a generated ref; a `defineWorkflow({ name })` override otherwise). */
@@ -45,23 +46,32 @@ interface WorkflowReference<Params = Record<string, unknown>> {
 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>;
+/**
+ * The arguments a one-shot schedule target ({@link Scheduler.runAfter} /
+ * {@link Scheduler.runAt}) accepts. Unlike {@link CronTargetArgs} it preserves a
+ * {@link FunctionReference}'s inferred `args` (via {@link ArgsOf}) as well as a
+ * {@link WorkflowReference}'s inferred `params`, so scheduling a plain function
+ * keeps its today's arg checking while scheduling a workflow/agent infers its
+ * `params`.
+ */
+type ScheduleTargetArgs<T extends CronTarget> = T extends WorkflowReference<infer Params> ? Params : T extends FunctionReference ? ArgsOf<T> : 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.
-*/
+ * 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 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;
@@ -72,11 +82,11 @@ interface RetryPolicy {
 }
 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`.
-  */
+   * 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;
@@ -86,65 +96,100 @@ interface RunOptions {
 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.
-  */
+   * 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;
+  /**
+   * The `ns:fn` path of the function to dispatch on fire. Absent when the job
+   * targets a durable workflow/agent instead — see {@link ScheduleRecord.workflow}.
+   * Exactly one of `functionPath` / `workflow` is set.
+   */
+  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.
-  */
+   * 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.
-  */
+   * 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;
+  /**
+   * The `WORKFLOW_*`/`AGENT_*` binding name to start a fresh durable instance
+   * of on fire (the {@link ScheduleRecord.args} become its `params`). Set
+   * instead of {@link ScheduleRecord.functionPath} when the job targets a
+   * workflow/agent {@link WorkflowReference}. The runtime — not the DO — owns
+   * the binding, so the dispatch payload carries this through to the Worker.
+   */
+  workflow?: string;
 }
 interface Scheduler {
   cancel: (id: string) => Promise<{
     cancelled: boolean;
   }>;
+  /**
+   * Jobs that exhausted their retry budget and were parked under `dead:`
+   * (the DO's `/dead` view). Deliberately absent from {@link Scheduler.list} —
+   * the park deletes the `id:` header — so this is the only view of a job
+   * that failed permanently rather than being silently dropped.
+   */
+  dead: () => Promise<ScheduleRecord[]>;
+  /**
+   * Resurrect a parked job with a fresh attempt budget (the DO's
+   * `POST /dead/retry`). `false` when the id is not parked; a racing double
+   * recover is a no-op rather than an error.
+   */
+  deadRetry: (id: string) => Promise<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<{
+  /**
+   * Schedule `target` to run once, `delayMs` from now. `target` is a function
+   * {@link FunctionReference} (dispatched as a one-shot) or a durable
+   * {@link WorkflowReference} — the generated `workflows.<name>` /
+   * `agents.<name>` ref — which starts a fresh instance on fire (args become
+   * its `params`). {@link ScheduleTargetArgs} infers the accepted args from
+   * whichever target was passed.
+   */
+  runAfter: <T extends CronTarget>(delayMs: number, target: T, args: ScheduleTargetArgs<T>, options?: RunOptions) => Promise<{
     id: string;
     scheduledFor: number;
   }>;
-  runAt: <F extends FunctionReference>(date: Date | number, function_: F, args: ArgsOf<F>, options?: RunOptions) => Promise<{
+  /** Like {@link Scheduler.runAfter} but fires at an absolute `date`/timestamp. */
+  runAt: <T extends CronTarget>(date: Date | number, target: T, args: ScheduleTargetArgs<T>, 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/
-*/
+ * 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.
-  */
+   * Derive a jurisdiction-restricted subnamespace. Optional because older
+   * workers-types releases (and test doubles) may not expose it.
+   */
   jurisdiction?: (jurisdiction: DurableObjectJurisdiction) => DurableObjectNamespaceLike;
 }
 interface DurableObjectIdLike {
@@ -157,18 +202,18 @@ 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.
-  */
+   * 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.
-  */
+   * 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). */
@@ -181,46 +226,46 @@ interface EnqueueOptions {
   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.
-*/
+ * 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.
-  */
+   * 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`.
-  */
+   * Pool name — the concurrency counter is keyed by this inside the
+   * SchedulerDO storage (`pool:<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.
-*/
+ * 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 `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). */
+  /** The pool's name (the `pool:<name>` storage key suffix). */
   readonly name: string;
   /** Inspect the pool's current state — `inFlight` slots used and the configured `maxConcurrency`. */
   status: () => Promise<{
@@ -289,11 +334,11 @@ interface QueueWorkpoolOptions {
   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.
-*/
+ * 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>;
@@ -321,41 +366,41 @@ interface HttpDispatcherOptions {
   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.
-*/
+ * 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`).
-*/
+ * 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:<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. */
@@ -377,10 +422,10 @@ interface CronTriggerSnippet {
   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.
-*/
+ * 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 {
@@ -395,6 +440,19 @@ interface DailySchedule {
   /** 0–59. */
   minuteUTC: number;
 }
+/**
+ * Hourly recurrence at a fixed minute past the hour.
+ *
+ * `crons.interval({ hours: 1 })` compiles to the same expression, but the
+ * asymmetry of having `daily`/`weekly`/`monthly` and no `hourly` is its own
+ * papercut — and unlike the interval form this one lets
+ * the caller place the job off the hour boundary, which is how you stop a
+ * dozen hourly jobs from stampeding at `:00`.
+ */
+interface HourlySchedule {
+  /** 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"`). */
@@ -406,106 +464,119 @@ interface MonthlySchedule extends DailySchedule {
   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.
-*/
+ * 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).
-  */
+   * `__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.
-  */
+   * 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";
+type CronScheduleKind = "daily" | "hourly" | "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;
+ * 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). `jobName` is
+ * optional (see {@link compileInterval}) so codegen's existing 2-arg call site
+ * keeps working unchanged.
+ */
+declare const compileCronSchedule: (kind: CronScheduleKind, schedule: DailySchedule | HourlySchedule | IntervalSchedule | MonthlySchedule | WeeklySchedule, jobName?: string) => 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.
-*/
+ * 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`.
-  */
+   * 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.<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 at `hourUTC:minuteUTC` (UTC). The target may be a function or a durable workflow (`workflows.<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>`). */
+  /** Hourly at `minuteUTC` past the hour. The target may be a function or a durable workflow (`workflows.<name>`). */
+  hourly: <T extends CronTarget>(name: string, schedule: HourlySchedule, target: T, args?: CronTargetArgs<T>) => CronJobsBuilder;
+  /** Every `{ seconds | minutes | hours }`. The target may be a function or a durable workflow (`workflows.<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 on `day` at `hourUTC:minuteUTC` (UTC). The target may be a function or a durable workflow (`workflows.<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 on `dayOfWeek` at `hourUTC:minuteUTC` (UTC). The target may be a function or a durable workflow (`workflows.<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.
-*/
+ * 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.
-*/
+ * 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.
-*/
+ * 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.
-*/
+ * 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.
-*/
+ * 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[];
+  /**
+   * Register a constant ping/pong auto-response so the runtime answers a
+   * known keepalive frame on a hibernated socket WITHOUT waking this DO (no
+   * billable request, no dispatch). Optional: absent in the unit harness and
+   * older runtimes, present on the real `DurableObjectState`. Mirrors
+   * `@lunora/do`'s `ShardDOState.setWebSocketAutoResponse` — see
+   * {@link SchedulerDO.armWebSocketKeepalive}.
+   */
+  setWebSocketAutoResponse?: (pair: WebSocketRequestResponsePair) => void;
   storage: {
     delete: (key: string | string[]) => Promise<number | boolean>;
     deleteAlarm: () => Promise<void> | void;
@@ -515,6 +586,7 @@ interface SchedulerDOState {
       end?: string;
       limit?: number;
       prefix?: string;
+      startAfter?: string;
     }) => Promise<Map<string, T>>;
     put: <T = unknown>(entries: Record<string, T> | string, value?: T) => Promise<void>;
     setAlarm: (scheduledTime: number | Date) => Promise<void> | void;
@@ -523,100 +595,107 @@ interface SchedulerDOState {
 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>`.
-  */
+   * Fallback bearer token attached to the dispatch when
+   * {@link SchedulerEnv.LUNORA_SCHEDULER_SECRET} is not configured. Sent as
+   * `authorization: Bearer <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.
-  */
+   * 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}).
-  */
+   * 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.
-*/
+ * 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). */
+  /** The logical workpool name (the `pool:<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.
-*/
+ * 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. */
+  /** Per-pool backlog breakdown, one entry per `pool:<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)`.
-*/
+ * Durable Object that stores pending scheduled invocations sorted by their
+ * `scheduledFor` time and fires them via HTTP on alarm. Storage layout:
+ * `id:<id>` maps to {@link ScheduleRecord}; `t:<paddedTime>:<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).
-  */
+   * 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.
-  */
+   * 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.
-  */
+   * 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.
-  */
+   * 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;
+  /**
+   * Normalize the mutually-exclusive dispatch target off an untrusted body: a
+   * one-shot function path (`functionPath`) or a durable workflow/agent
+   * instance (`workflow`, a `WORKFLOW_*`/`AGENT_*` binding). Returns `undefined`
+   * when neither is present so the caller can reject the schedule.
+   */
+  private static resolveScheduleTarget;
   protected readonly state: SchedulerDOState;
   protected readonly env: SchedulerEnv;
   constructor(state: SchedulerDOState, env: SchedulerEnv);
@@ -624,180 +703,267 @@ declare class SchedulerDO {
   /** 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.
-  */
+   * 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.
-  */
+   * Register the hibernation-safe ping/pong keepalive. The runtime answers a
+   * {@link WS_KEEPALIVE_PING} text frame with {@link WS_KEEPALIVE_PONG}
+   * WITHOUT waking this Durable Object, keeping an idle `/ws` subscription
+   * alive across hibernation with no billable wakeup and no dispatch. Without
+   * this, a client's heartbeat ping goes unanswered and its watchdog force-
+   * closes the socket every ~90s, defeating hibernation (each unanswered ping
+   * wakes the DO to reconnect) — mirrors `@lunora/do`'s
+   * `ShardDO.armWebSocketKeepalive`. The auto-response is per-instance, so
+   * this re-runs on every construction (including a post-hibernation wake).
+   * Guarded: the API and the `WebSocketRequestResponsePair` global are absent
+   * in the unit harness and on older runtimes, where it degrades to a no-op.
+   */
+  private armWebSocketKeepalive;
+  /**
+   * 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 re-asserts the claim so the job stays re-fireable.
+   *
+   * A throw reaching here always means the job was NOT dispatched:
+   * {@link drainRecord} swallows its own post-dispatch cleanup errors and
+   * returns instead of throwing once a kick succeeds, so every escaping throw
+   * comes from the pre-dispatch or failed-dispatch paths. We therefore always
+   * 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.
+   */
   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.
-  */
+   * 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}. Pool state is read FRESH from storage per record (see
+   * {@link reservePoolSlot}) and never held across the dispatch() await, so a
+   * concurrent /complete landing mid-dispatch can't be clobbered.
+   * Once a kick succeeds, post-dispatch cleanup (clearing the `id:`/`retry:`
+   * rows) is swallowed rather than allowed to throw, so a successful dispatch
+   * NEVER propagates an error to {@link drainRecordGuarded}: every throw that
+   * escapes comes from the pre-dispatch or failed-dispatch paths, where the job
+   * is still re-fireable and the guard safely re-claims the time index.
+   * @returns `true` only when the record was successfully dispatched (a 2xx
+   * kick); `false` on pool backpressure or a failed dispatch (the job is still
+   * re-fireable — already re-armed here). The value is informational (the guard
+   * branches on throw/no-throw, not on this boolean).
+   */
   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.
-  */
+   * 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.
+   *
+   * The pool row is read FRESH from storage on every call — never cached
+   * across the drain. Each reservation durably `savePool()`s before the next
+   * record runs, so a same-pass reservation is still visible to the next
+   * record's fresh read (the budget carries forward); and because dispatch()
+   * awaits an outbound fetch between records, a concurrent /complete that
+   * decrements the row mid-drain IS reflected here instead of being clobbered
+   * by a stale in-memory copy (which would leak a slot permanently).
+   */
   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.
-  */
+   * 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.
-  */
+   * Re-list the jobs (bounded — see {@link listRecords}) 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). */
+  /**
+   * The current pending job records (shared by `/list` and the live channel),
+   * bounded to `limit` (default {@link DEFAULT_LIST_LIMIT}) so a large backlog
+   * can't be JSON-serialized and fanned out to every socket in one shot. Lists
+   * `limit + 1` and slices back down so `truncated` reflects whether there was
+   * a next row, without a second round-trip.
+   */
   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).
-  */
+   * Page through every `id:` header exactly once with bounded per-page memory
+   * (a `limit`+`startAfter` cursor loop), invoking `visit` for each record.
+   * Unlike {@link listRecords}, which intentionally truncates for the studio's
+   * live view, `/status` and `/pool` need EXACT counts — this walks the full
+   * set, but never materializes more than one page at a time.
+   */
+  private countHeaders;
+  /**
+   * 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.
-  */
+   * 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. */
+  /** Read the durable `pool:<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.
-  */
+   * 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.
-  */
+   * 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.
-  */
+   * `GET /status` — the app-level backlog signal that powers the studio's
+   * SLO view. Enumerates every durable `pool:<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:<name>` row before the job's header), so a single
+   * scan over `pool:` plus a cursor loop over `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.
-  */
+   * `GET /dead` — list the dead-letter records: jobs that exhausted their
+   * retry budget ({@link recordRetry}) and were parked under `dead:<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 }`).
-  */
+   * `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.
-  */
+   * `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`).
-  */
+   * Resolve a single pending job by id via a direct `id:<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.
-  */
+   * 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;
 }
+/** What the Cloudflare scheduler host needs from the Worker's environment. */
+interface SchedulerHostOptions {
+  /**
+   * Named scheduler instance — one `SchedulerDO` per name, useful for tenant
+   * isolation. Defaults to `"default"`.
+   */
+  instanceName?: string;
+  /**
+   * Data-residency jurisdiction for the `SchedulerDO`. Pass the same value as
+   * the worker's own jurisdiction so scheduled state co-resides with app data.
+   */
+  jurisdiction?: "eu" | "fedramp" | "us";
+  /** The `SchedulerDO` namespace binding. */
+  namespace: Parameters<typeof createScheduler>[0]["namespace"];
+  /**
+   * Public origin the Worker is mounted at. `SchedulerDO` dispatches back to
+   * this base URL when an alarm fires, so a wrong value means jobs fire into
+   * nothing.
+   */
+  originUrl: string;
+}
+/**
+ * Build the Cloudflare {@link SchedulerHost}.
+ *
+ * The returned host has no `cron` member — see the module docstring.
+ */
+declare const createSchedulerHost: (options: SchedulerHostOptions) => SchedulerHost;
 /** 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.
-*/
+ * A 6-field (seconds-leading) cron expression is legal generic cron grammar
+ * but not a Cloudflare Cron Trigger — the platform only understands the
+ * 5-field, minute-granularity form and rejects the rest at `wrangler deploy`
+ * with a message naming neither the job nor the file. Warn here instead of
+ * staying silent, without throwing: unlike the ergonomic `.interval()` form,
+ * the raw `.cron()` escape hatch is meant to accept cron grammar this module
+ * doesn't otherwise second-guess.
+ *
+ * Exported (not module-private) because it is the ONE place this advisory is
+ * written: the runtime `cronJobs()` builder reaches it via
+ * {@link assertValidCronExpression}, and `@lunora/codegen`'s static
+ * `discover-crons.ts` calls it directly after its own `isValidCronExpression`
+ * check — so a hand-authored 6-field `.cron()` warns whether it's discovered
+ * from source at build time or registered at runtime, with one shared message.
+ */
+declare const warnIfSecondsLeading: (schedule: string, context: string) => void;
+/**
+ * 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. Well-formed but
+ * Cloudflare-incompatible (6-field) expressions pass but log a warning — see
+ * {@link warnIfSecondsLeading}.
+ */
 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 };
+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 HourlySchedule, 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 SchedulerHostOptions, type SchedulerPoolStatus, type SchedulerStatus, type WeeklySchedule, type WorkflowReference, type Workpool, type WorkpoolOptions, assertValidCronExpression, compileCronSchedule, createCronTrigger, createQueueConsumer, createQueueWorkpool, createScheduler, createSchedulerHost, createWorkpool, cronJobs, httpDispatcher, isValidCronExpression, isWorkflowReference, warnIfSecondsLeading };