@lunora/scheduler 1.0.0-alpha.7 → 1.0.0-alpha.71

package/dist/index.d.mts

@@ -1,82 +1,162 @@
+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`.
-*/
-interface FunctionReference {
+ * The generated function-reference type, shared by every package that needs to
+ * infer a call's args or return from `api.<file>.<fn>`.
+ *
+ * This lives in `shared/` rather than in one package because the consumers span
+ * a dependency boundary they must not cross: `@lunora/scheduler` and
+ * `@lunora/workflow` accept a reference in `runAfter`/`runAt`/`step.run*` but
+ * cannot depend on `@lunora/client`, which is a browser package. Each of them
+ * previously hand-copied this declaration, and both copies silently rotted when
+ * the phantom carrier was renamed — the conditional matched an OPTIONAL property
+ * that no longer existed, so `ArgsOf<F>` quietly resolved to `unknown` and every
+ * `step.run(ref, args)` in the repo lost its arg checking without a single error.
+ *
+ * `shared/` is the repo's answer to exactly that shape: bundler-inlined,
+ * zero-dependency source imported by relative path, so it creates no runtime
+ * edge between the packages that inline it. Being ONE declaration, there is
+ * nothing to keep in lockstep and no drift test to write.
+ */
+/** The registered function kinds a {@link FunctionReference} can describe. `stream` is a query that yields multiple frames over the WS. */
+type FunctionKind = "action" | "mutation" | "query" | "stream";
+/**
+ * Opaque reference to a registered function emitted by `@lunora/codegen`.
+ *
+ * At runtime it carries the `<file>:<function>` identifier in `__lunoraRef`.
+ * Generated declarations decorate this with phantom type parameters so callers
+ * can infer args / return values per call site.
+ */
+interface FunctionReference<Kind extends FunctionKind = FunctionKind, Args = unknown, Return = unknown> {
+  /**
+   * Phantom marker carrying the `Kind`/`Args`/`Return` type parameters for
+   * inference. Never present at runtime; declared as a covariant (output)
+   * position so a concrete reference stays assignable to a widened one.
+   */
+  readonly __lunoraPhantom?: {
+    args: Args;
+    kind: Kind;
+    returns: Return;
+  };
   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.
-*/
+}
+/** Extract the args type from a {@link FunctionReference}. */
+type ArgsOf<F> = F extends FunctionReference<infer _K, infer A, infer _R> ? A : never;
+/**
+ * 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). */
   readonly name?: string;
 }
+/**
+ * A function reference a scheduler or workpool may target.
+ *
+ * `stream` is excluded deliberately, and the exclusion is load-bearing rather
+ * than tidiness: a scheduled job is dispatched as an ordinary `/rpc` call, and
+ * the function runner cannot execute a stream function (see
+ * `create-worker.ts`'s registry note). Accepting one compiles a job that is
+ * guaranteed to fail when its alarm fires, long after the call site that
+ * scheduled it.
+ */
+type SchedulableReference<Args = unknown, Return = unknown> = FunctionReference<Exclude<FunctionKind, "stream">, Args, Return>;
 /** A cron job's target: either a one-shot function dispatch or a durable workflow start. */
-type CronTarget = FunctionReference | WorkflowReference;
+type CronTarget = SchedulableReference | 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 resolves a
+ * {@link FunctionReference}'s `args` through {@link ArgsOf} as well as a
+ * {@link WorkflowReference}'s `params`, so scheduling a generated function
+ * reference is arg-checked against that function's validator while scheduling a
+ * workflow/agent is checked against its `params`.
+ */
+type ScheduleTargetArgs<T extends CronTarget> = T extends WorkflowReference<infer Params> ? Params : T extends SchedulableReference ? 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;
-  /** Maximum number of dispatch attempts before dead-lettering. Default `5`. */
+  /**
+   * Maximum number of **retries** after the initial dispatch. Default `5`, so
+   * a job that keeps failing is dispatched 6 times in total before it is
+   * dead-lettered (the park happens once `attempts > maxAttempts`).
+   */
   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`.
-  */
+   * Job id to store the record under, instead of one the SchedulerDO mints.
+   *
+   * Exists for `@lunora/server`'s deferred-schedule facade: inside a mutation a
+   * `runAfter`/`runAt` is buffered until the transaction commits, but the
+   * handler is handed the id synchronously, so the id has to be decided before
+   * the call is made. Callers that are not deferring should leave it unset and
+   * take the minted id from the return value. Anything that is not a plain
+   * `[A-Za-z0-9_-]` id of at most 64 characters, or that LEADS with `-`, is
+   * REFUSED (`400 INVALID_SCHEDULE_ID`) rather than replaced: the id is handed
+   * to `WorkflowBinding.create({ id })` verbatim for a workflow target, and the
+   * engine's instance-id grammar (`^[a-zA-Z0-9_][a-zA-Z0-9-_]*$`) refuses that
+   * first character. Minting over it would mean two calls naming the same bad
+   * id ran the job twice instead of the second answering `409`.
+   *
+   * **Not an idempotency key.** An id that is already scheduled is REFUSED
+   * (`409 DUPLICATE_SCHEDULE_ID`), not replaced or de-duplicated: the time
+   * index is keyed by time as well as id, so an overwrite would fire the new
+   * job at the old job's instant and drop the slot it was actually scheduled
+   * for. Cancel the existing job first if you mean to reschedule it. The id
+   * is free again once the job has fired or been cancelled.
+   */
+  id?: string;
+  /**
+   * Cap for the {@link RunOptions.pool} this job joins, applied when the pool
+   * is first created and refreshed on every enqueue that carries one. Ignored
+   * without `pool`. A pool created by a `runAfter`/`runAt` that omits it caps
+   * at 1 — {@link Workpool} is the usual way to set it.
+   */
+  maxConcurrency?: number;
+  /**
+   * 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 +166,108 @@ 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<{
-    id: string;
-    scheduledFor: number;
-  }>;
-  runAt: <F extends FunctionReference>(date: Date | number, function_: F, args: ArgsOf<F>, options?: RunOptions) => Promise<{
-    id: string;
-    scheduledFor: number;
-  }>;
+  /**
+   * 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.
+   *
+   * **Resolves the job id, a bare string** — the same value `cancel`/`get`
+   * take, and the same value the `ctx.scheduler` surface promises. This object
+   * IS `ctx.scheduler` on the shard side (codegen installs it behind
+   * `SchedulerLike`, whose `runAfter`/`runAt` are declared `Promise<string>`),
+   * so resolving a `{ id, scheduledFor }` record here handed mutations an
+   * object where every other gate — `@lunora/server`'s `Scheduler`,
+   * `@lunora/shard-engine`'s `SchedulerLike`, `@lunora/runtime`'s httpAction
+   * ctx, and the docs — said string. Nothing caught it, because the install is
+   * a cast: apps wrote the object into a string column and `cancel(id)`
+   * answered `{ cancelled: false }` with no error anywhere.
+   *
+   * The fire instant is not lost: `runAt` was handed it, and a caller that
+   * needs it back reads `scheduledFor` off {@link Scheduler.get}.
+   */
+  runAfter: <T extends CronTarget>(delayMs: number, target: T, args: ScheduleTargetArgs<T>, options?: RunOptions) => Promise<string>;
+  /** Like {@link Scheduler.runAfter} but fires at an absolute `date`/timestamp. Resolves the job id. */
+  runAt: <T extends CronTarget>(date: Date | number, target: T, args: ScheduleTargetArgs<T>, options?: RunOptions) => Promise<string>;
 }
 /**
-* 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,19 +280,20 @@ 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.
-  */
-  originUrl: string;
+   * Binding to the `SchedulerDO` durable object namespace.
+   *
+   * The origin the DO dispatches back to is NOT passed here: it reads
+   * `env.LUNORA_ORIGIN_URL` off its own binding at fire time, because a
+   * caller-supplied dispatch target would be an SSRF vector.
+   */
+  namespace: DurableObjectNamespaceLike;
 }
 /** Per-enqueue options for a {@link Workpool}. Extends {@link RunOptions} minus the implicit `pool` (the pool sets that). */
 interface EnqueueOptions {
@@ -181,46 +305,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` / `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: <F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: EnqueueOptions) => Promise<{
+   * 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 SchedulableReference>(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<{
@@ -271,6 +395,13 @@ interface MessageBatchLike<Body = unknown> {
 }
 /** The wire payload Lunora puts on the queue: a function dispatch. */
 interface QueueJob {
+  /**
+   * The call's arguments in WIRE form (`shared/wire-codec`), so a `bigint`,
+   * `Date` or bytes survives the queue's own JSON serialisation. The producers
+   * encode; the shard's dispatch loop is the single decoder. A custom
+   * {@link QueueDispatch} must forward this untouched — decoding it here and
+   * letting the shard decode again flattens a `Date` to `{}`.
+   */
   args?: Record<string, unknown>;
   functionPath: string;
   /** Routing hint forwarded to the Worker so the call lands on the right shard. */
@@ -289,14 +420,14 @@ 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>;
+  enqueue: <F extends SchedulableReference>(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>;
@@ -304,8 +435,12 @@ interface QueueWorkpool {
     shardKey?: string;
   }>, options?: QueueSendOptionsLike) => Promise<void>;
 }
-/** Dispatches a single {@link QueueJob} — the consumer's per-message worker. */
-type QueueDispatch = (job: QueueJob) => Promise<void>;
+/**
+ * Dispatches a single {@link QueueJob} — the consumer's per-message worker.
+ * `messageId` is the queue message's native id, threaded through so the
+ * dispatcher can attribute a failure to the exact message that caused it.
+ */
+type QueueDispatch = (job: QueueJob, messageId?: string) => Promise<void>;
 /** Options for `createQueueConsumer`. */
 interface QueueConsumerOptions {
   /** How each job is executed; e.g. the `httpDispatcher`. */
@@ -319,43 +454,50 @@ interface HttpDispatcherOptions {
   fetchImpl?: typeof fetch;
   /** Origin where the Worker is mounted (the `/_lunora/scheduler/dispatch` endpoint). */
   originUrl: string;
+  /**
+   * Abort a job's dispatch after this many ms; the abort is retryable, so the
+   * consumer retries the message. Defaults to 5 minutes — raise it for a
+   * workpool running jobs that legitimately run longer, lower it to fail a
+   * stuck origin faster.
+   */
+  timeoutMs?: number;
 }
 /**
-* 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` /
+ * `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, 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,15 +519,25 @@ 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 {
+  /** 1–23, and must divide 24 (an interval repeats *within* a day). */
   hours?: number;
+  /** 1–59, and must divide 60. */
   minutes?: number;
+  /**
+   * Accepted by the type, **rejected at definition time**: Cloudflare Cron
+   * Triggers have a one-minute floor, so the 6-field expression this compiles
+   * to would survive codegen and land in the committed `wrangler.jsonc`, then
+   * fail at `wrangler deploy` naming neither the job nor the file. Declared so
+   * the rejection can name the job instead. Use `ctx.scheduler.runAfter`/
+   * `runAt` for sub-minute recurrence, or `{ minutes: 1 }`.
+   */
   seconds?: number;
 }
 /** Daily recurrence at a fixed UTC wall-clock time. */
@@ -395,6 +547,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 +571,156 @@ 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;
-/**
-* 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.
-*/
+ * 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.
+ */
 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 `{ minutes | hours }` — `{ seconds }` throws (Cron Triggers have a one-minute floor). 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}: dispatch each job to the Worker's
+ * `/_lunora/scheduler/dispatch` endpoint (the same path SchedulerDO dispatches
+ * through) via `@lunora/dispatch`'s `createDispatchRunner` — which bounds each
+ * job with {@link HttpDispatcherOptions.timeoutMs} (default
+ * {@link DEFAULT_JOB_TIMEOUT_MS}), so a hung origin no longer holds the whole
+ * `queue()` invocation open, and threads the queue message id through for
+ * failure attribution. Any dispatch failure throws so the consumer retries the
+ * message — including a 2xx carrying a non-empty non-JSON body, which is an
+ * intermediary's page rather than a function's return value and therefore no
+ * evidence the job ran. An empty 2xx is a normal success (a `void` function).
+ *
+ * `job.args` is forwarded VERBATIM: {@link encodeJobArgs} already put it in wire
+ * form at the producer, and the shard's dispatch loop is the single decoder.
+ * Encoding again here would leave the handler a tagged array.
+ */
 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.
-*/
+ * The id a new record is stored under: the caller's, or a freshly minted one when
+ * they did not name it.
+ *
+ * A caller id that is not a safe key segment is REFUSED, not replaced.
+ * `RunOptions.id` is not an idempotency key — an id already scheduled answers
+ * `409 DUPLICATE_SCHEDULE_ID` — so quietly swapping an invalid one for a random
+ * id made `runAt(ts, ref, args, { id: "-daily-2026-09-06" })` mint a fresh id on
+ * every call and run the job once per call, where naming it was the caller's way
+ * of saying "at most once".
+ *
+ * Minting swaps a leading `-` for `_` rather than re-rolling: 1 in 64 minted ids
+ * led with one and was refused by the workflow engine on dispatch. `_` is in the
+ * engine's leading class, the swap is a single pass, and 96 random bits stay 96
+ * random bits everywhere but that first character.
+ *
+ * Exported because two surfaces have to agree on it. The SchedulerDO applies it
+ * when the record is written (turning the refusal into a `400`);
+ * `@lunora/server`'s deferred-schedule facade applies it when the call is
+ * BUFFERED, because it answers the handler with the id synchronously — long
+ * before the DO sees the request. Restating the rule in the facade is how the two
+ * drift: an id the facade accepted and the DO replaced leaves the handler holding
+ * an id no job was ever stored under, so its later `cancel` silently misses.
+ * @param requested the caller's `RunOptions.id`, if any
+ * @throws LunoraError `INVALID_SCHEDULE_ID` when `requested` is supplied and is not a safe key segment
+ */
+declare const resolveScheduleId: (requested: unknown) => string;
+/**
+ * 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 +730,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,281 +739,524 @@ 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, which carries no dispatch target at all) to prevent SSRF.
+   */
   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.
-*/
+ * Retries allowed after the original attempt before {@link SchedulerDO.recordRetry}
+ * parks a record in the dead-letter (`dead:`) prefix. Overridable per job via
+ * {@link RetryPolicy.maxAttempts}. Exported so test doubles of the scheduler
+ * (`@lunora/testing`'s fake scheduler) model the same budget instead of
+ * duplicating the number.
+ */
+declare const MAX_RETRY_ATTEMPTS = 5;
+/**
+ * Backoff before the first retry, in milliseconds; doubles on each subsequent
+ * retry under the default `"exponential"` backoff (`baseMs * 2 ** (attempts - 1)`).
+ * Overridable per job via {@link RetryPolicy.baseMs}. Exported alongside
+ * {@link MAX_RETRY_ATTEMPTS} for the same reason.
+ */
+declare const RETRY_BASE_DELAY_MS = 3e4;
+/**
+ * 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;
+  /**
+   * Whether {@link SchedulerDO.reindexOrphanedRecords} has already run in THIS
+   * instance. Once is enough: an orphan can only be minted by an eviction, and
+   * an eviction ends the instance that minted it.
+   */
+  private reindexed;
   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.
-  */
+   * 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) so a schedule request can never name where the DO calls
+   * back — that would be SSRF. 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 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.
+   *
+   * With one exception, checked first: a record that already has a durable
+   * `dead:` row is TERMINAL, and re-claiming it would re-dispatch a job the
+   * dead-letter says is finished. See the comment on that branch.
+   */
   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 listPage}) 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).
-  */
+  /**
+   * One bounded page of the rows under `prefix`, in key order, plus the
+   * `cursor` a caller resumes from (the last key of the page) when `truncated`.
+   * Lists `limit + 1` and slices back down so both facts are known without a
+   * second round-trip.
+   *
+   * Shared by `/list` (pending headers) and `/dead` (dead-letter records) so
+   * NEITHER can materialize an unbounded set into one JSON response: nothing
+   * prunes `dead:`, so a workpool with a broken origin parks thousands of rows
+   * and the studio's only view of them — and only way to requeue them — would
+   * fail exactly when it is needed.
+   */
+  private listPage;
+  /**
+   * Page through every row under `prefix` exactly once with bounded per-page
+   * memory (a `limit`+`startAfter` cursor loop), invoking `visit` for each.
+   * Unlike {@link listPage}, 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 forEachPage;
+  /**
+   * 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. */
+  /**
+   * Terminal park into the dead-letter (`dead:`) prefix, with `reason` naming
+   * why in the emitted warning. Shared by the two ways a retry ends for good:
+   * an exhausted attempt budget, and a backoff that ran past the largest
+   * schedulable time (see {@link isIndexableTime}).
+   */
+  private parkDead;
+  /** 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;
+  /**
+   * Persist (or refresh) a pool's concurrency cap, so the alarm-time gate has
+   * a durable `maxConcurrency` even after the enqueuing client is gone.
+   */
+  private persistPoolCap;
+  /**
+   * The `409` a caller-supplied id earns when something durable already holds
+   * it, or `undefined` when the id is free.
+   *
+   * A pending header is the obvious half: `put` on `id:<id>` overwrites, but
+   * the `t:` index is keyed by TIME as well as id, so the OLD entry survives.
+   * The drain then dispatches the NEW record at the OLD time and deletes the
+   * entry it should have fired at — the job runs early and never runs again.
+   * Refused rather than made a replace: `RunOptions.id` exists so a deferred
+   * schedule can name its own job, and silently retiming someone else's is the
+   * worse failure.
+   *
+   * The `dead:` row holds the id too, and for a worse reason. A dead record
+   * keeps NO `id:` header, so a pending-only check leaves the id apparently
+   * free — and a later `/dead/retry` writes the revived corpse straight over
+   * the new job's header and adds a SECOND time index under the same id. The
+   * new job is gone and the dead one fires in its place. Recovering a dead job
+   * is an operator action taken minutes or days after the schedule, so nothing
+   * at schedule time would ever have surfaced the collision.
+   */
+  private idConflict;
+  /**
+   * The id the record is stored under, or the `Response` refusing it.
+   *
+   * A caller id that is not a safe key segment is refused with a `400` rather
+   * than minted over: `RunOptions.id` is not an idempotency key, so swapping an
+   * invalid one for a random id made two calls naming it schedule two jobs
+   * where the second should have answered `409`.
+   *
+   * Only an id the CALLER chose can collide — a minted one is 96 random bits —
+   * so {@link idConflict} costs two `get`s on the deferred path and nothing on
+   * the ordinary one.
+   */
+  private resolveId;
   private handleSchedule;
   private handleCancel;
+  /**
+   * `GET /list[?cursor=]` — one bounded page of pending jobs. `truncated` says
+   * whether more rows follow and `cursor` is what a caller passes back to get
+   * them (`createScheduler.list()` walks every page; the studio shows one).
+   */
   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. Bounded and cursored
+   * like `/list`: nothing prunes `dead:`, so this set grows without limit.
+   */
   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;
+  /**
+   * Re-index every pending job whose time-index entry is gone.
+   *
+   * {@link SchedulerDO.drainRecordGuarded} claims a job by DELETING its `t:`
+   * entry, awaited (so durable) BEFORE {@link SchedulerDO.dispatch}'s outbound
+   * fetch. If the Durable Object is evicted or crashes during that fetch, the
+   * `id:` header (and any `retry:` row) survives with no `t:` entry — and
+   * nothing puts one back: {@link SchedulerDO.rescheduleAlarm} derives the
+   * clock from `t:` alone, and `alarm()`'s inline reconciliation only handles
+   * the INVERSE orphan (a `t:` entry whose header is gone). The job then sits
+   * in `/list` and `/status.backlog` forever, never fires, never reaches
+   * `/dead`. The at-least-once contract `drainRecordGuarded` documents covers
+   * a thrown storage op, not a lost instance.
+   *
+   * Re-firing is safe: the dispatch carries the record id, which the receiver
+   * spends as `x-lunora-mutation-id` for a function target and as the workflow
+   * INSTANCE id for a `workflow` target, so a job that DID reach the origin
+   * before the crash is not run twice either way.
+   *
+   * Two bounded walks (all `t:` values, then all `id:` headers) rather than a
+   * per-header `get`, so the cost is one pass over each prefix.
+   */
+  private reindexOrphanedRecords;
   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.
+   *
+   * The origin the DO dispatches back to is not configured here — it reads
+   * `env.LUNORA_ORIGIN_URL` off its own binding at fire time, so a wrong value
+   * there (or none) is what makes jobs fire into nothing.
+   */
+  namespace: Parameters<typeof createScheduler>[0]["namespace"];
+}
+/**
+ * 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 };
+/**
+ * Reject a `delayMs` a scheduler cannot act on, before it reaches the
+ * SchedulerDO.
+ *
+ * A `NaN`/`Infinity` delay serializes to `null` through JSON and lands as a
+ * malformed `scheduledFor`; a negative one schedules into the past. Both are the
+ * caller's argument, so the answer has to name the argument — which is why the
+ * code is `INVALID_INPUT` (400) and not `INTERNAL`: `toErrorBody` replaces an
+ * internal-coded message with "Internal error", redacting the one sentence that
+ * says what to fix.
+ *
+ * Exported because four surfaces enforce it — `createScheduler().runAfter`,
+ * `createWorkpool().enqueue`, `@lunora/server`'s deferred-schedule facade (which
+ * must reject BEFORE the transaction commits, not at flush time) and
+ * `@lunora/testing`'s fake scheduler. They used to restate it and threw three
+ * different codes between them, so a test written against the harness caught one
+ * code while production threw another.
+ * @param delayMs the delay to validate
+ * @param surface what to name in the message — the call the delay was passed to (e.g. `"ctx.scheduler.runAfter"`)
+ * @param argument the caller's argument to name in the message; `runAt` converts its absolute `date` to a delay and passes that name through so the answer points at what was actually written
+ */
+declare const assertScheduleDelay: (delayMs: number, surface: string, argument?: string) => void;
+/**
+ * Reject a `runAt` instant a scheduler cannot act on — {@link assertScheduleDelay}'s
+ * bound, restated for the absolute form by converting the instant to the delay it
+ * implies.
+ *
+ * `runAfter` has refused a `NaN`/`Infinity` argument since the guard was written;
+ * `runAt` took the same value through a different door and let it reach the DO,
+ * where it serializes to `null` through JSON and lands as a `scheduledFor` no
+ * alarm can ever fire. `new Date("2026-13-01")`, `runAt(row.dueAt + delay)` on a
+ * row whose `dueAt` is absent — both arrive here as a number that is not one.
+ *
+ * An instant already in the PAST is not refused. It is an overdue job
+ * (`runAt(row.dueAt)` on a row that came due while the request was in flight),
+ * and `runAfter` itself reaches `runAt` a fraction of a millisecond after
+ * capturing its own clock reading — so a strict sign check would fail the
+ * documented `runAfter(0, …)` call at random. The delay is therefore clamped at
+ * zero while it is still a finite number, which leaves the half that matters:
+ * a value that is not a number at all.
+ * @param timestampMs the absolute instant (epoch ms) the caller passed
+ * @param nowMs the clock to measure it against — the wall clock in production, the harness's virtual clock in a test
+ * @param surface what to name in the message — the call the instant was passed to (e.g. `"ctx.scheduler.runAt"`)
+ */
+declare const assertScheduleInstant: (timestampMs: number, nowMs: number, surface: 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 FunctionKind, type FunctionReference, type HourlySchedule, type HttpDispatcherOptions, type IntervalSchedule, type LunoraSchedulerOptions, MAX_RETRY_ATTEMPTS, type MessageBatchLike, type MonthlySchedule, type QueueConsumerOptions, type QueueDispatch, type QueueEnqueueOptions, type QueueJob, type QueueLike, type QueueMessageLike, type QueueSendOptionsLike, type QueueSendRequestLike, type QueueWorkpool, type QueueWorkpoolOptions, RETRY_BASE_DELAY_MS, 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, assertScheduleDelay, assertScheduleInstant, assertValidCronExpression, compileCronSchedule, createCronTrigger, createQueueConsumer, createQueueWorkpool, createScheduler, createSchedulerHost, createWorkpool, cronJobs, httpDispatcher, isValidCronExpression, isWorkflowReference, resolveScheduleId, warnIfSecondsLeading };