@lunora/scheduler 1.0.0-alpha.16 → 1.0.0-alpha.161

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/README.md +5 -5
  2. package/dist/index.d.mts +672 -117
  3. package/dist/index.d.ts +672 -117
  4. package/dist/index.mjs +1 -1
  5. package/dist/packem_shared/CRON_SCHEDULE_KINDS-v0tEYoxJ.mjs +1 -0
  6. package/dist/packem_shared/MAX_RETRY_ATTEMPTS-oLI_d_xX.mjs +1 -0
  7. package/dist/packem_shared/assertScheduleDelay-DiyM8a3y.mjs +1 -0
  8. package/dist/packem_shared/assertScheduleInstant-DlXlSbXn.mjs +1 -0
  9. package/dist/packem_shared/assertValidCronExpression-fiNfNiWf.mjs +1 -0
  10. package/dist/packem_shared/createCronTrigger-cg32QNgj.mjs +1 -0
  11. package/dist/packem_shared/createQueueConsumer-CYwmsmvq.mjs +4 -0
  12. package/dist/packem_shared/createScheduler-BhkNvLvi.mjs +1 -0
  13. package/dist/packem_shared/createSchedulerHost-CyQLO3fi.mjs +1 -0
  14. package/dist/packem_shared/createWorkpool-C9Qf2k6N.mjs +1 -0
  15. package/dist/packem_shared/do-client-XQayNStI.mjs +1 -0
  16. package/dist/packem_shared/resolve-schedule-id-B2ghxgFm.mjs +1 -0
  17. package/dist/packem_shared/resolveScheduleId-BEV7mby4.mjs +1 -0
  18. package/dist/packem_shared/validate-cron-full.d-Bemx45E8.d.mts +28 -0
  19. package/dist/packem_shared/validate-cron-full.d-Bemx45E8.d.ts +28 -0
  20. package/dist/validate-cron-full.d.mts +1 -0
  21. package/dist/validate-cron-full.d.ts +1 -0
  22. package/dist/validate-cron-full.mjs +1 -0
  23. package/package.json +9 -4
  24. package/dist/packem_shared/CRON_SCHEDULE_KINDS-DgupPI9t.mjs +0 -1
  25. package/dist/packem_shared/SchedulerDO-DGgeZ-uI.mjs +0 -1
  26. package/dist/packem_shared/assertValidCronExpression-DHvO7Vm9.mjs +0 -1
  27. package/dist/packem_shared/createCronTrigger-CyPdVKNF.mjs +0 -1
  28. package/dist/packem_shared/createQueueConsumer-B0qNXRUJ.mjs +0 -1
  29. package/dist/packem_shared/createScheduler-CsRAEtdb.mjs +0 -1
  30. package/dist/packem_shared/createSchedulerHost-C5XacwXv.mjs +0 -1
  31. package/dist/packem_shared/createWorkpool-DyVdhB6o.mjs +0 -1
  32. package/dist/packem_shared/do-client-BFps7NIj.mjs +0 -1
package/dist/index.d.ts CHANGED
@@ -1,25 +1,51 @@
1
1
  import { SchedulerHost } from '@lunora/platform';
2
+ export { a as assertValidCronExpression, i as isValidCronExpression, w as warnIfSecondsLeading } from "./packem_shared/validate-cron-full.d-Bemx45E8.js";
2
3
  /**
3
- * Opaque reference to a Lunora function. Mirrors the `FunctionReference` shape
4
- * emitted by `@lunora/codegen` (and consumed by `@lunora/client`). We avoid a
5
- * direct dependency to keep this package usable from the codegen pipeline
6
- * itself.
4
+ * The generated function-reference type, shared by every package that needs to
5
+ * infer a call's args or return from `api.<file>.<fn>`.
7
6
  *
8
- * The runtime identifier lives in `__lunoraRef` — this MUST stay in lockstep
9
- * with the codegen emit + `@lunora/client`'s `FunctionReference`.
7
+ * This lives in `shared/` rather than in one package because the consumers span
8
+ * a dependency boundary they must not cross: `@lunora/scheduler` and
9
+ * `@lunora/workflow` accept a reference in `runAfter`/`runAt`/`step.run*` but
10
+ * cannot depend on `@lunora/client`, which is a browser package. Each of them
11
+ * previously hand-copied this declaration, and both copies silently rotted when
12
+ * the phantom carrier was renamed — the conditional matched an OPTIONAL property
13
+ * that no longer existed, so `ArgsOf<F>` quietly resolved to `unknown` and every
14
+ * `step.run(ref, args)` in the repo lost its arg checking without a single error.
15
+ *
16
+ * `shared/` is the repo's answer to exactly that shape: bundler-inlined,
17
+ * zero-dependency source imported by relative path, so it creates no runtime
18
+ * edge between the packages that inline it. Being ONE declaration, there is
19
+ * nothing to keep in lockstep and no drift test to write.
10
20
  */
11
- interface FunctionReference {
21
+ /** The registered function kinds a {@link FunctionReference} can describe. `stream` is a query that yields multiple frames over the WS. */
22
+ type FunctionKind = "action" | "mutation" | "query" | "stream";
23
+ /**
24
+ * Opaque reference to a registered function emitted by `@lunora/codegen`.
25
+ *
26
+ * At runtime it carries the `<file>:<function>` identifier in `__lunoraRef`.
27
+ * Generated declarations decorate this with phantom type parameters so callers
28
+ * can infer args / return values per call site.
29
+ */
30
+ interface FunctionReference<Kind extends FunctionKind = FunctionKind, Args = unknown, Return = unknown> {
31
+ /**
32
+ * Phantom marker carrying the `Kind`/`Args`/`Return` type parameters for
33
+ * inference. Never present at runtime; declared as a covariant (output)
34
+ * position so a concrete reference stays assignable to a widened one.
35
+ */
36
+ readonly __lunoraPhantom?: {
37
+ args: Args;
38
+ kind: Kind;
39
+ returns: Return;
40
+ };
12
41
  readonly __lunoraRef: string;
13
- /** Marker phantom type — discriminates queries / mutations / actions. */
14
- readonly _kind?: "query" | "mutation" | "action";
15
42
  }
16
- type ArgsOf<F extends FunctionReference> = F extends {
17
- _args?: infer A;
18
- } ? A : Record<string, unknown>;
43
+ /** Extract the args type from a {@link FunctionReference}. */
44
+ type ArgsOf<F> = F extends FunctionReference<infer _K, infer A, infer _R> ? A : never;
19
45
  /**
20
46
  * Typed reference to a Lunora durable workflow — either the generated
21
- * `workflows.&lt;name>` reference object (`_generated/api.ts`, which carries the
22
- * `WORKFLOW_*` binding + export name) or, structurally, a `defineWorkflow()`
47
+ * `workflows.<name>` reference object (`_generated/api.ts`, which carries the
48
+ * workflow's class name + export name) or, structurally, a `defineWorkflow()`
23
49
  * result imported directly. Both are matched by the `isLunoraWorkflow` brand and
24
50
  * carry the workflow's `params` in the phantom `__params`, so a `cronJobs()`
25
51
  * registration infers them.
@@ -36,25 +62,36 @@ type ArgsOf<F extends FunctionReference> = F extends {
36
62
  interface WorkflowReference<Params = Record<string, unknown>> {
37
63
  /** Phantom carrier for the workflow's `params` type — drives `cronJobs()` arg inference. Never read at runtime. */
38
64
  readonly __params?: Params;
39
- /** The `WORKFLOW_*` binding name (present on a generated `workflows.&lt;name>` ref). */
40
- readonly binding?: string;
65
+ /** The workflow's export key — its generated class name, reached as `ctx.exports.<className>` (present on a generated ref). */
66
+ readonly className?: string;
41
67
  readonly isLunoraWorkflow: true;
42
68
  /** The workflow's export/stable name (present on a generated ref; a `defineWorkflow({ name })` override otherwise). */
43
69
  readonly name?: string;
44
70
  }
71
+ /**
72
+ * A function reference a scheduler or workpool may target.
73
+ *
74
+ * `stream` is excluded deliberately, and the exclusion is load-bearing rather
75
+ * than tidiness: a scheduled job is dispatched as an ordinary `/rpc` call, and
76
+ * the function runner cannot execute a stream function (see
77
+ * `create-worker.ts`'s registry note). Accepting one compiles a job that is
78
+ * guaranteed to fail when its alarm fires, long after the call site that
79
+ * scheduled it.
80
+ */
81
+ type SchedulableReference<Args = unknown, Return = unknown> = FunctionReference<Exclude<FunctionKind, "stream">, Args, Return>;
45
82
  /** A cron job's target: either a one-shot function dispatch or a durable workflow start. */
46
- type CronTarget = FunctionReference | WorkflowReference;
83
+ type CronTarget = SchedulableReference | WorkflowReference;
47
84
  /** The arguments a cron's target accepts: a workflow's inferred `params`, else an open record (function args aren't inferred). */
48
85
  type CronTargetArgs<T extends CronTarget> = T extends WorkflowReference<infer Params> ? Params : Record<string, unknown>;
49
86
  /**
50
87
  * The arguments a one-shot schedule target ({@link Scheduler.runAfter} /
51
- * {@link Scheduler.runAt}) accepts. Unlike {@link CronTargetArgs} it preserves a
52
- * {@link FunctionReference}'s inferred `args` (via {@link ArgsOf}) as well as a
53
- * {@link WorkflowReference}'s inferred `params`, so scheduling a plain function
54
- * keeps its today's arg checking while scheduling a workflow/agent infers its
55
- * `params`.
88
+ * {@link Scheduler.runAt}) accepts. Unlike {@link CronTargetArgs} it resolves a
89
+ * {@link FunctionReference}'s `args` through {@link ArgsOf} as well as a
90
+ * {@link WorkflowReference}'s `params`, so scheduling a generated function
91
+ * reference is arg-checked against that function's validator while scheduling a
92
+ * workflow/agent is checked against its `params`.
56
93
  */
57
- type ScheduleTargetArgs<T extends CronTarget> = T extends WorkflowReference<infer Params> ? Params : T extends FunctionReference ? ArgsOf<T> : Record<string, unknown>;
94
+ type ScheduleTargetArgs<T extends CronTarget> = T extends WorkflowReference<infer Params> ? Params : T extends SchedulableReference ? ArgsOf<T> : Record<string, unknown>;
58
95
  /** Narrow a {@link CronTarget} to a {@link WorkflowReference} by its runtime brand. */
59
96
  declare const isWorkflowReference: (target: unknown) => target is WorkflowReference;
60
97
  /**
@@ -75,12 +112,46 @@ interface RetryPolicy {
75
112
  backoff?: "exponential" | "linear";
76
113
  /** Base delay in milliseconds for the first retry. Default `30_000`. */
77
114
  baseMs?: number;
78
- /** Maximum number of dispatch attempts before dead-lettering. Default `5`. */
115
+ /**
116
+ * Maximum number of **retries** after the initial dispatch. Default `5`, so
117
+ * a job that keeps failing is dispatched 6 times in total before it is
118
+ * dead-lettered (the park happens once `attempts > maxAttempts`).
119
+ */
79
120
  maxAttempts?: number;
80
121
  /** Optional ceiling clamping the computed backoff delay. */
81
122
  maxMs?: number;
82
123
  }
83
124
  interface RunOptions {
125
+ /**
126
+ * Job id to store the record under, instead of one the SchedulerDO mints.
127
+ *
128
+ * Exists for `@lunora/server`'s deferred-schedule facade: inside a mutation a
129
+ * `runAfter`/`runAt` is buffered until the transaction commits, but the
130
+ * handler is handed the id synchronously, so the id has to be decided before
131
+ * the call is made. Callers that are not deferring should leave it unset and
132
+ * take the minted id from the return value. Anything that is not a plain
133
+ * `[A-Za-z0-9_-]` id of at most 64 characters, or that LEADS with `-`, is
134
+ * REFUSED (`400 INVALID_SCHEDULE_ID`) rather than replaced: the id is handed
135
+ * to `WorkflowBinding.create({ id })` verbatim for a workflow target, and the
136
+ * engine's instance-id grammar (`^[a-zA-Z0-9_][a-zA-Z0-9-_]*$`) refuses that
137
+ * first character. Minting over it would mean two calls naming the same bad
138
+ * id ran the job twice instead of the second answering `409`.
139
+ *
140
+ * **Not an idempotency key.** An id that is already scheduled is REFUSED
141
+ * (`409 DUPLICATE_SCHEDULE_ID`), not replaced or de-duplicated: the time
142
+ * index is keyed by time as well as id, so an overwrite would fire the new
143
+ * job at the old job's instant and drop the slot it was actually scheduled
144
+ * for. Cancel the existing job first if you mean to reschedule it. The id
145
+ * is free again once the job has fired or been cancelled.
146
+ */
147
+ id?: string;
148
+ /**
149
+ * Cap for the {@link RunOptions.pool} this job joins, applied when the pool
150
+ * is first created and refreshed on every enqueue that carries one. Ignored
151
+ * without `pool`. A pool created by a `runAfter`/`runAt` that omits it caps
152
+ * at 1 — {@link Workpool} is the usual way to set it.
153
+ */
154
+ maxConcurrency?: number;
84
155
  /**
85
156
  * Logical workpool this job belongs to. When set, the SchedulerDO gates the
86
157
  * job behind the pool's `maxConcurrency` (see {@link WorkpoolOptions}).
@@ -129,7 +200,7 @@ interface ScheduleRecord {
129
200
  scheduledFor: number;
130
201
  shardKey?: string;
131
202
  /**
132
- * The `WORKFLOW_*`/`AGENT_*` binding name to start a fresh durable instance
203
+ * The workflow/agent export key (its generated class name) to start a fresh durable instance
133
204
  * of on fire (the {@link ScheduleRecord.args} become its `params`). Set
134
205
  * instead of {@link ScheduleRecord.functionPath} when the job targets a
135
206
  * workflow/agent {@link WorkflowReference}. The runtime — not the DO — owns
@@ -161,20 +232,28 @@ interface Scheduler {
161
232
  /**
162
233
  * Schedule `target` to run once, `delayMs` from now. `target` is a function
163
234
  * {@link FunctionReference} (dispatched as a one-shot) or a durable
164
- * {@link WorkflowReference} — the generated `workflows.&lt;name>` /
165
- * `agents.&lt;name>` ref — which starts a fresh instance on fire (args become
235
+ * {@link WorkflowReference} — the generated `workflows.<name>` /
236
+ * `agents.<name>` ref — which starts a fresh instance on fire (args become
166
237
  * its `params`). {@link ScheduleTargetArgs} infers the accepted args from
167
238
  * whichever target was passed.
239
+ *
240
+ * **Resolves the job id, a bare string** — the same value `cancel`/`get`
241
+ * take, and the same value the `ctx.scheduler` surface promises. This object
242
+ * IS `ctx.scheduler` on the shard side (codegen installs it behind
243
+ * `SchedulerLike`, whose `runAfter`/`runAt` are declared `Promise<string>`),
244
+ * so resolving a `{ id, scheduledFor }` record here handed mutations an
245
+ * object where every other gate — `@lunora/server`'s `Scheduler`,
246
+ * `@lunora/shard-engine`'s `SchedulerLike`, `@lunora/runtime`'s httpAction
247
+ * ctx, and the docs — said string. Nothing caught it, because the install is
248
+ * a cast: apps wrote the object into a string column and `cancel(id)`
249
+ * answered `{ cancelled: false }` with no error anywhere.
250
+ *
251
+ * The fire instant is not lost: `runAt` was handed it, and a caller that
252
+ * needs it back reads `scheduledFor` off {@link Scheduler.get}.
168
253
  */
169
- runAfter: <T extends CronTarget>(delayMs: number, target: T, args: ScheduleTargetArgs<T>, options?: RunOptions) => Promise<{
170
- id: string;
171
- scheduledFor: number;
172
- }>;
173
- /** Like {@link Scheduler.runAfter} but fires at an absolute `date`/timestamp. */
174
- runAt: <T extends CronTarget>(date: Date | number, target: T, args: ScheduleTargetArgs<T>, options?: RunOptions) => Promise<{
175
- id: string;
176
- scheduledFor: number;
177
- }>;
254
+ runAfter: <T extends CronTarget>(delayMs: number, target: T, args: ScheduleTargetArgs<T>, options?: RunOptions) => Promise<string>;
255
+ /** Like {@link Scheduler.runAfter} but fires at an absolute `date`/timestamp. Resolves the job id. */
256
+ runAt: <T extends CronTarget>(date: Date | number, target: T, args: ScheduleTargetArgs<T>, options?: RunOptions) => Promise<string>;
178
257
  }
179
258
  /**
180
259
  * Cloudflare Durable Object data-residency jurisdiction. Widening union —
@@ -208,13 +287,14 @@ interface LunoraSchedulerOptions {
208
287
  * un-pinned global namespace.
209
288
  */
210
289
  jurisdiction?: DurableObjectJurisdiction;
211
- /** Binding to the `SchedulerDO` durable object namespace. */
212
- namespace: DurableObjectNamespaceLike;
213
290
  /**
214
- * Origin where the Worker is mounted. SchedulerDO uses this base URL when
215
- * dispatching scheduled functions back to the Worker on alarm fire.
291
+ * Binding to the `SchedulerDO` durable object namespace.
292
+ *
293
+ * The origin the DO dispatches back to is NOT passed here: it reads
294
+ * `env.LUNORA_ORIGIN_URL` off its own binding at fire time, because a
295
+ * caller-supplied dispatch target would be an SSRF vector.
216
296
  */
217
- originUrl: string;
297
+ namespace: DurableObjectNamespaceLike;
218
298
  }
219
299
  /** Per-enqueue options for a {@link Workpool}. Extends {@link RunOptions} minus the implicit `pool` (the pool sets that). */
220
300
  interface EnqueueOptions {
@@ -227,7 +307,7 @@ interface EnqueueOptions {
227
307
  }
228
308
  /**
229
309
  * Options for `createWorkpool`. Mirrors {@link LunoraSchedulerOptions}
230
- * (same `namespace` / `originUrl` / `instanceName`) plus the bounded-concurrency
310
+ * (same `namespace` / `instanceName`) plus the bounded-concurrency
231
311
  * controls. A workpool is a NAMED logical pool inside the existing SchedulerDO —
232
312
  * it needs no extra Durable Object or wrangler binding beyond the SchedulerDO
233
313
  * the scheduler already uses.
@@ -241,7 +321,7 @@ interface WorkpoolOptions extends LunoraSchedulerOptions {
241
321
  maxConcurrency: number;
242
322
  /**
243
323
  * Pool name — the concurrency counter is keyed by this inside the
244
- * SchedulerDO storage (`pool:&lt;name>`). Default `default`.
324
+ * SchedulerDO storage (`pool:<name>`). Default `default`.
245
325
  */
246
326
  name?: string;
247
327
  }
@@ -261,11 +341,11 @@ interface Workpool {
261
341
  * and the time it was scheduled for (it may not run immediately if the pool
262
342
  * is at capacity).
263
343
  */
264
- enqueue: <F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: EnqueueOptions) => Promise<{
344
+ enqueue: <F extends SchedulableReference>(function_: F, args: ArgsOf<F>, options?: EnqueueOptions) => Promise<{
265
345
  id: string;
266
346
  scheduledFor: number;
267
347
  }>;
268
- /** The pool's name (the `pool:&lt;name>` storage key suffix). */
348
+ /** The pool's name (the `pool:<name>` storage key suffix). */
269
349
  readonly name: string;
270
350
  /** Inspect the pool's current state — `inFlight` slots used and the configured `maxConcurrency`. */
271
351
  status: () => Promise<{
@@ -316,6 +396,13 @@ interface MessageBatchLike<Body = unknown> {
316
396
  }
317
397
  /** The wire payload Lunora puts on the queue: a function dispatch. */
318
398
  interface QueueJob {
399
+ /**
400
+ * The call's arguments in WIRE form (`packages/wire/src/wire-codec`), so a `bigint`,
401
+ * `Date` or bytes survives the queue's own JSON serialisation. The producers
402
+ * encode; the shard's dispatch loop is the single decoder. A custom
403
+ * {@link QueueDispatch} must forward this untouched — decoding it here and
404
+ * letting the shard decode again flattens a `Date` to `{}`.
405
+ */
319
406
  args?: Record<string, unknown>;
320
407
  functionPath: string;
321
408
  /** Routing hint forwarded to the Worker so the call lands on the right shard. */
@@ -341,7 +428,7 @@ interface QueueWorkpoolOptions {
341
428
  */
342
429
  interface QueueWorkpool {
343
430
  /** Enqueue a single `fn(args)` dispatch. */
344
- enqueue: <F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: QueueEnqueueOptions) => Promise<void>;
431
+ enqueue: <F extends SchedulableReference>(function_: F, args: ArgsOf<F>, options?: QueueEnqueueOptions) => Promise<void>;
345
432
  /** Enqueue many dispatches in one `sendBatch`. Each job names its function `ref`. */
346
433
  enqueueBatch: (jobs: ReadonlyArray<{
347
434
  args?: Record<string, unknown>;
@@ -349,12 +436,40 @@ interface QueueWorkpool {
349
436
  shardKey?: string;
350
437
  }>, options?: QueueSendOptionsLike) => Promise<void>;
351
438
  }
352
- /** Dispatches a single {@link QueueJob} — the consumer's per-message worker. */
353
- type QueueDispatch = (job: QueueJob) => Promise<void>;
439
+ /**
440
+ * Dispatches a single {@link QueueJob} — the consumer's per-message worker.
441
+ * `messageId` is the queue message's native id, threaded through so the
442
+ * dispatcher can attribute a failure to the exact message that caused it.
443
+ */
444
+ type QueueDispatch = (job: QueueJob, messageId?: string) => Promise<void>;
354
445
  /** Options for `createQueueConsumer`. */
355
446
  interface QueueConsumerOptions {
356
447
  /** How each job is executed; e.g. the `httpDispatcher`. */
357
448
  dispatch: QueueDispatch;
449
+ /**
450
+ * The consumer's `max_retries` as deployed in `wrangler.jsonc`, which a
451
+ * consumer cannot read at runtime. Used only to recognise a message's last
452
+ * delivery, where a declined dispatch is re-enqueued through `requeue` (or
453
+ * logged as the drop or dead-letter it becomes without one). Defaults to
454
+ * Cloudflare's default of 3.
455
+ */
456
+ maxRetries?: number;
457
+ /**
458
+ * Re-enqueue a job whose dispatch is declined on its last delivery as a
459
+ * copy delayed past the in-flight claim, with a fresh retry budget, instead
460
+ * of letting it be dead-lettered or dropped while its call is still
461
+ * running. Without it that loss is only logged.
462
+ *
463
+ * `queue` is the producer binding of the queue this consumer reads (the
464
+ * one handed to `createQueueWorkpool`). `secret` keys the MAC the copy
465
+ * carries — pass the admin token (`LUNORA_ADMIN_TOKEN`). The copy
466
+ * dispatches under the replaced message's id so the shard serves the
467
+ * declined call's result, and without a valid MAC no body can claim an id.
468
+ */
469
+ requeue?: {
470
+ queue: QueueLike<QueueJob>;
471
+ secret: string;
472
+ };
358
473
  }
359
474
  /** Options for the `httpDispatcher` — the default HTTP dispatcher. */
360
475
  interface HttpDispatcherOptions {
@@ -364,6 +479,13 @@ interface HttpDispatcherOptions {
364
479
  fetchImpl?: typeof fetch;
365
480
  /** Origin where the Worker is mounted (the `/_lunora/scheduler/dispatch` endpoint). */
366
481
  originUrl: string;
482
+ /**
483
+ * Abort a job's dispatch after this many ms; the abort is retryable, so the
484
+ * consumer retries the message. Defaults to 5 minutes — raise it for a
485
+ * workpool running jobs that legitimately run longer, lower it to fail a
486
+ * stuck origin faster.
487
+ */
488
+ timeoutMs?: number;
367
489
  }
368
490
  /**
369
491
  * Client-side scheduler — forwards `runAfter` / `runAt` / `cancel` calls to a
@@ -374,9 +496,9 @@ declare const createScheduler: (options: LunoraSchedulerOptions) => Scheduler;
374
496
  /**
375
497
  * Bounded-concurrency action queue — the Lunora equivalent of
376
498
  * `@convex-dev/workpool`. Mirrors `createScheduler`'s `namespace` /
377
- * `originUrl` / `instanceName` options and is built on the SAME `SchedulerDO`:
499
+ * `instanceName` options and is built on the SAME `SchedulerDO`:
378
500
  * a workpool is just a NAMED logical pool inside that DO (concurrency counter
379
- * keyed by {@link WorkpoolOptions.name} under the `pool:&lt;name>` storage key).
501
+ * keyed by {@link WorkpoolOptions.name} under the `pool:<name>` storage key).
380
502
  * It needs no extra Durable Object or wrangler binding beyond the SchedulerDO
381
503
  * the scheduler already uses.
382
504
  *
@@ -384,8 +506,24 @@ declare const createScheduler: (options: LunoraSchedulerOptions) => Scheduler;
384
506
  * `maxConcurrency` of the pool's jobs at once and queues the rest durably,
385
507
  * draining them as the runtime reports completions (`POST /complete`).
386
508
  *
509
+ * The ceiling the platform adds: one alarm drain keeps at most SIX dispatches in
510
+ * flight, because a Durable Object may have only six connections simultaneously
511
+ * waiting for response headers. A `maxConcurrency` above six is therefore not
512
+ * wrong, just not reachable within a single drain — the surplus drains on the
513
+ * following alarms. The same invocation is bounded by the 15-minute alarm wall
514
+ * clock, which covers the WHOLE drain rather than one job; work that does not
515
+ * fit is deferred to the next alarm, never dropped.
516
+ *
517
+ * For jobs that are individually long — an LLM call, an export, a payment
518
+ * round-trip — prefer `createQueueWorkpool`: the dispatch this DO awaits
519
+ * only returns once the function has finished running, so a long job occupies
520
+ * one of those six slots and one slice of that 15-minute budget for its whole
521
+ * duration. A Queues consumer gets a fresh Worker invocation per batch, with its
522
+ * own connection budget and its own clock, and its `max_concurrency` is not
523
+ * capped at six. You give up the hard cap, per-job cancel, and per-job status.
524
+ *
387
525
  * ```ts
388
- * const pool = createWorkpool({ namespace: env.SCHEDULER, originUrl, maxConcurrency: 5 });
526
+ * const pool = createWorkpool({ namespace: env.SCHEDULER, maxConcurrency: 5 });
389
527
  * await pool.enqueue(internal.stripe.sync, { invoiceId }, { retry: { maxAttempts: 3 } });
390
528
  * ```
391
529
  *
@@ -429,8 +567,18 @@ interface CronTriggerSnippet {
429
567
  declare const createCronTrigger: (options: CronTriggerOptions) => CronTriggerSnippet;
430
568
  /** Sub-day recurrence. Exactly one unit must be provided. */
431
569
  interface IntervalSchedule {
570
+ /** 1–23, and must divide 24 (an interval repeats *within* a day). */
432
571
  hours?: number;
572
+ /** 1–59, and must divide 60. */
433
573
  minutes?: number;
574
+ /**
575
+ * Accepted by the type, **rejected at definition time**: Cloudflare Cron
576
+ * Triggers have a one-minute floor, so the 6-field expression this compiles
577
+ * to would survive codegen and land in the committed `wrangler.jsonc`, then
578
+ * fail at `wrangler deploy` naming neither the job nor the file. Declared so
579
+ * the rejection can name the job instead. Use `ctx.scheduler.runAfter`/
580
+ * `runAt` for sub-minute recurrence, or `{ minutes: 1 }`.
581
+ */
434
582
  seconds?: number;
435
583
  }
436
584
  /** Daily recurrence at a fixed UTC wall-clock time. */
@@ -484,7 +632,7 @@ interface CronJob {
484
632
  * Set when the job targets a durable workflow rather than a function: the
485
633
  * workflow's stable name (`defineWorkflow({ name })`) when one was declared,
486
634
  * otherwise `""`. `@lunora/codegen` statically resolves the concrete
487
- * `lunora/workflows.ts` export + its `WORKFLOW_*` binding for the emitted
635
+ * `lunora/workflows.ts` export + its class name for the emitted
488
636
  * dispatch map, so this authoring-time value is informational only.
489
637
  */
490
638
  workflow?: string;
@@ -497,9 +645,11 @@ declare const CRON_SCHEDULE_KINDS: ReadonlySet<CronScheduleKind>;
497
645
  * Compile one of the ergonomic schedule forms into a standard cron expression.
498
646
  * Exposed as a pure function so `@lunora/codegen` can reuse the exact same
499
647
  * compilation when it statically lifts a `crons.{kind}(...)` call out of the
500
- * AST — codegen imports this directly (no duplicated mirror).
648
+ * AST — codegen imports this directly (no duplicated mirror). `jobName` is
649
+ * optional (see {@link compileInterval}) so codegen's existing 2-arg call site
650
+ * keeps working unchanged.
501
651
  */
502
- declare const compileCronSchedule: (kind: CronScheduleKind, schedule: DailySchedule | HourlySchedule | IntervalSchedule | MonthlySchedule | WeeklySchedule) => string;
652
+ declare const compileCronSchedule: (kind: CronScheduleKind, schedule: DailySchedule | HourlySchedule | IntervalSchedule | MonthlySchedule | WeeklySchedule, jobName?: string) => string;
503
653
  /**
504
654
  * Builder returned by {@link cronJobs}. Each method registers one recurring
505
655
  * job; the compiled expression is validated immediately so authoring mistakes
@@ -507,22 +657,22 @@ declare const compileCronSchedule: (kind: CronScheduleKind, schedule: DailySched
507
657
  */
508
658
  interface CronJobsBuilder {
509
659
  /**
510
- * Raw cron expression escape hatch (5- or 6-field, full cron-parser grammar).
660
+ * Raw cron expression escape hatch (5- or 6-field, full `@visulima/cron-parser` Cloudflare grammar).
511
661
  * The target may be a function (`internal.file.fn`) or a durable workflow
512
- * (`workflows.&lt;name>`); a workflow's `args` are inferred from its `params`.
662
+ * (`workflows.<name>`); a workflow's `args` are inferred from its `params`.
513
663
  */
514
664
  cron: <T extends CronTarget>(name: string, cronExpr: string, target: T, args?: CronTargetArgs<T>) => CronJobsBuilder;
515
- /** Daily at `hourUTC:minuteUTC` (UTC). The target may be a function or a durable workflow (`workflows.&lt;name>`). */
665
+ /** Daily at `hourUTC:minuteUTC` (UTC). The target may be a function or a durable workflow (`workflows.<name>`). */
516
666
  daily: <T extends CronTarget>(name: string, schedule: DailySchedule, target: T, args?: CronTargetArgs<T>) => CronJobsBuilder;
517
- /** Hourly at `minuteUTC` past the hour. The target may be a function or a durable workflow (`workflows.&lt;name>`). */
667
+ /** Hourly at `minuteUTC` past the hour. The target may be a function or a durable workflow (`workflows.<name>`). */
518
668
  hourly: <T extends CronTarget>(name: string, schedule: HourlySchedule, target: T, args?: CronTargetArgs<T>) => CronJobsBuilder;
519
- /** Every `{ seconds | minutes | hours }`. The target may be a function or a durable workflow (`workflows.&lt;name>`). */
669
+ /** Every `{ minutes | hours }` — `{ seconds }` throws (Cron Triggers have a one-minute floor). The target may be a function or a durable workflow (`workflows.<name>`). */
520
670
  interval: <T extends CronTarget>(name: string, schedule: IntervalSchedule, target: T, args?: CronTargetArgs<T>) => CronJobsBuilder;
521
671
  /** Snapshot of the registered jobs, in declaration order. */
522
672
  jobs: () => ReadonlyArray<CronJob>;
523
- /** Monthly on `day` at `hourUTC:minuteUTC` (UTC). The target may be a function or a durable workflow (`workflows.&lt;name>`). */
673
+ /** Monthly on `day` at `hourUTC:minuteUTC` (UTC). The target may be a function or a durable workflow (`workflows.<name>`). */
524
674
  monthly: <T extends CronTarget>(name: string, schedule: MonthlySchedule, target: T, args?: CronTargetArgs<T>) => CronJobsBuilder;
525
- /** Weekly on `dayOfWeek` at `hourUTC:minuteUTC` (UTC). The target may be a function or a durable workflow (`workflows.&lt;name>`). */
675
+ /** Weekly on `dayOfWeek` at `hourUTC:minuteUTC` (UTC). The target may be a function or a durable workflow (`workflows.<name>`). */
526
676
  weekly: <T extends CronTarget>(name: string, schedule: WeeklySchedule, target: T, args?: CronTargetArgs<T>) => CronJobsBuilder;
527
677
  }
528
678
  /**
@@ -548,12 +698,49 @@ declare const createQueueWorkpool: (options: QueueWorkpoolOptions) => QueueWorkp
548
698
  */
549
699
  declare const createQueueConsumer: (options: QueueConsumerOptions) => ((batch: MessageBatchLike) => Promise<void>);
550
700
  /**
551
- * Default {@link QueueDispatch}: POST each job to the Worker's
701
+ * Default {@link QueueDispatch}: dispatch each job to the Worker's
552
702
  * `/_lunora/scheduler/dispatch` endpoint (the same path SchedulerDO dispatches
553
- * through), authenticated with the admin bearer. A non-2xx response throws so
554
- * the consumer retries the message.
703
+ * through) via `@lunora/dispatch`'s `createDispatchRunner` — which bounds each
704
+ * job with {@link HttpDispatcherOptions.timeoutMs} (default
705
+ * {@link DEFAULT_JOB_TIMEOUT_MS}), so a hung origin no longer holds the whole
706
+ * `queue()` invocation open, and threads the queue message id through for
707
+ * failure attribution. Any dispatch failure throws so the consumer retries the
708
+ * message — including a 2xx carrying a non-empty non-JSON body, which is an
709
+ * intermediary's page rather than a function's return value and therefore no
710
+ * evidence the job ran. An empty 2xx is a normal success (a `void` function).
711
+ *
712
+ * `job.args` is forwarded VERBATIM: {@link encodeJobArgs} already put it in wire
713
+ * form at the producer, and the shard's dispatch loop is the single decoder.
714
+ * Encoding again here would leave the handler a tagged array.
555
715
  */
556
716
  declare const httpDispatcher: (options: HttpDispatcherOptions) => QueueDispatch;
717
+ /**
718
+ * The id a new record is stored under: the caller's, or a freshly minted one when
719
+ * they did not name it.
720
+ *
721
+ * A caller id that is not a safe key segment is REFUSED, not replaced.
722
+ * `RunOptions.id` is not an idempotency key — an id already scheduled answers
723
+ * `409 DUPLICATE_SCHEDULE_ID` — so quietly swapping an invalid one for a random
724
+ * id made `runAt(ts, ref, args, { id: "-daily-2026-09-06" })` mint a fresh id on
725
+ * every call and run the job once per call, where naming it was the caller's way
726
+ * of saying "at most once".
727
+ *
728
+ * Minting swaps a leading `-` for `_` rather than re-rolling: 1 in 64 minted ids
729
+ * led with one and was refused by the workflow engine on dispatch. `_` is in the
730
+ * engine's leading class, the swap is a single pass, and 96 random bits stay 96
731
+ * random bits everywhere but that first character.
732
+ *
733
+ * Exported because two surfaces have to agree on it. The SchedulerDO applies it
734
+ * when the record is written (turning the refusal into a `400`);
735
+ * `@lunora/server`'s deferred-schedule facade applies it when the call is
736
+ * BUFFERED, because it answers the handler with the id synchronously — long
737
+ * before the DO sees the request. Restating the rule in the facade is how the two
738
+ * drift: an id the facade accepted and the DO replaced leaves the handler holding
739
+ * an id no job was ever stored under, so its later `cancel` silently misses.
740
+ * @param requested the caller's `RunOptions.id`, if any
741
+ * @throws LunoraError `INVALID_SCHEDULE_ID` when `requested` is supplied and is not a safe key segment
742
+ */
743
+ declare const resolveScheduleId: (requested: unknown) => string;
557
744
  /**
558
745
  * Minimal projection of `DurableObjectState` for the SchedulerDO. Declared
559
746
  * structurally so unit tests can pass a fake state without booting the
@@ -566,6 +753,15 @@ interface SchedulerDOState {
566
753
  acceptWebSocket?: (ws: WebSocket) => void;
567
754
  /** Every accepted server WebSocket (workers `state.getWebSockets`). */
568
755
  getWebSockets?: () => WebSocket[];
756
+ /**
757
+ * Register a constant ping/pong auto-response so the runtime answers a
758
+ * known keepalive frame on a hibernated socket WITHOUT waking this DO (no
759
+ * billable request, no dispatch). Optional: absent in the unit harness and
760
+ * older runtimes, present on the real `DurableObjectState`. Mirrors
761
+ * `@lunora/do`'s `ShardDOState.setWebSocketAutoResponse` — see
762
+ * {@link SchedulerDO.armWebSocketKeepalive}.
763
+ */
764
+ setWebSocketAutoResponse?: (pair: WebSocketRequestResponsePair) => void;
569
765
  storage: {
570
766
  delete: (key: string | string[]) => Promise<number | boolean>;
571
767
  deleteAlarm: () => Promise<void> | void;
@@ -575,6 +771,7 @@ interface SchedulerDOState {
575
771
  end?: string;
576
772
  limit?: number;
577
773
  prefix?: string;
774
+ startAfter?: string;
578
775
  }) => Promise<Map<string, T>>;
579
776
  put: <T = unknown>(entries: Record<string, T> | string, value?: T) => Promise<void>;
580
777
  setAlarm: (scheduledTime: number | Date) => Promise<void> | void;
@@ -585,13 +782,13 @@ interface SchedulerEnv {
585
782
  /**
586
783
  * Fallback bearer token attached to the dispatch when
587
784
  * {@link SchedulerEnv.LUNORA_SCHEDULER_SECRET} is not configured. Sent as
588
- * `authorization: Bearer &lt;token>`.
785
+ * `authorization: Bearer <token>`.
589
786
  */
590
787
  LUNORA_ADMIN_TOKEN?: string;
591
788
  /**
592
789
  * Base URL where the Worker is mounted. SchedulerDO uses this at dispatch
593
790
  * time to call back into the Worker. Read at fire time (NOT taken from the
594
- * request body) to prevent SSRF via a forged `originUrl` field.
791
+ * request body, which carries no dispatch target at all) to prevent SSRF.
595
792
  */
596
793
  LUNORA_ORIGIN_URL?: string;
597
794
  /**
@@ -602,6 +799,21 @@ interface SchedulerEnv {
602
799
  */
603
800
  LUNORA_SCHEDULER_SECRET?: string;
604
801
  }
802
+ /**
803
+ * Retries allowed after the original attempt before {@link SchedulerDO.recordRetry}
804
+ * parks a record in the dead-letter (`dead:`) prefix. Overridable per job via
805
+ * {@link RetryPolicy.maxAttempts}. Exported so test doubles of the scheduler
806
+ * (`@lunora/testing`'s fake scheduler) model the same budget instead of
807
+ * duplicating the number.
808
+ */
809
+ declare const MAX_RETRY_ATTEMPTS = 5;
810
+ /**
811
+ * Backoff before the first retry, in milliseconds; doubles on each subsequent
812
+ * retry under the default `"exponential"` backoff (`baseMs * 2 ** (attempts - 1)`).
813
+ * Overridable per job via {@link RetryPolicy.baseMs}. Exported alongside
814
+ * {@link MAX_RETRY_ATTEMPTS} for the same reason.
815
+ */
816
+ declare const RETRY_BASE_DELAY_MS = 3e4;
605
817
  /**
606
818
  * One pool's live backlog, as surfaced by `GET /status`. `inFlight`/
607
819
  * `maxConcurrency` mirror the durable {@link PoolState} semaphore; `queued`
@@ -612,7 +824,7 @@ interface SchedulerPoolStatus {
612
824
  inFlight: number;
613
825
  /** The pool's concurrency cap. */
614
826
  maxConcurrency: number;
615
- /** The logical workpool name (the `pool:&lt;name>` suffix). */
827
+ /** The logical workpool name (the `pool:<name>` suffix). */
616
828
  name: string;
617
829
  /** Pending jobs routed to this pool but not yet dispatched. */
618
830
  queued: number;
@@ -627,13 +839,13 @@ interface SchedulerStatus {
627
839
  backlog: number;
628
840
  /** Sum of every pool's `inFlight` count — the total held concurrency slots. */
629
841
  inFlight: number;
630
- /** Per-pool backlog breakdown, one entry per `pool:&lt;name>` record. */
842
+ /** Per-pool backlog breakdown, one entry per `pool:<name>` record. */
631
843
  pools: SchedulerPoolStatus[];
632
844
  }
633
845
  /**
634
846
  * Durable Object that stores pending scheduled invocations sorted by their
635
847
  * `scheduledFor` time and fires them via HTTP on alarm. Storage layout:
636
- * `id:&lt;id>` maps to {@link ScheduleRecord}; `t:&lt;paddedTime>:&lt;id>` maps to the
848
+ * `id:<id>` maps to {@link ScheduleRecord}; `t:<paddedTime>:<id>` maps to the
637
849
  * id (used as a sorted index).
638
850
  *
639
851
  * On every mutation the DO recomputes the earliest pending task and updates
@@ -641,6 +853,16 @@ interface SchedulerStatus {
641
853
  */
642
854
  declare class SchedulerDO {
643
855
  private static indexKey;
856
+ /** The record's `pq:` row key, or `undefined` for a job outside any pool. */
857
+ private static poolQueueKey;
858
+ /**
859
+ * The rows that make `record` a pending job — its header, plus its `pq:` row
860
+ * when pooled — ready to spread into one multi-key `put`, so the two can
861
+ * never disagree.
862
+ */
863
+ private static pendingRows;
864
+ /** The header key plus the `pq:` row key, to spread into the same multi-key `delete`. */
865
+ private static pendingKeys;
644
866
  private static json;
645
867
  private static error;
646
868
  /**
@@ -680,15 +902,66 @@ declare class SchedulerDO {
680
902
  /**
681
903
  * Normalize the mutually-exclusive dispatch target off an untrusted body: a
682
904
  * one-shot function path (`functionPath`) or a durable workflow/agent
683
- * instance (`workflow`, a `WORKFLOW_*`/`AGENT_*` binding). Returns `undefined`
905
+ * instance (`workflow`, a workflow/agent export key). Returns `undefined`
684
906
  * when neither is present so the caller can reject the schedule.
685
907
  */
686
908
  private static resolveScheduleTarget;
687
909
  protected readonly state: SchedulerDOState;
688
910
  protected readonly env: SchedulerEnv;
911
+ /**
912
+ * This instance's one run of {@link SchedulerDO.reindexOrphanedRecords},
913
+ * shared by every caller so none proceeds before it settles. Once is enough:
914
+ * an orphan can only be minted by an eviction, and an eviction ends the
915
+ * instance that minted it. A rejection is surfaced to the first caller only.
916
+ */
917
+ private recovery;
918
+ /** Whether {@link SchedulerDO.recovery} completed, so this instance may vouch for the store via {@link CLEAN_KEY}. */
919
+ private recovered;
920
+ /**
921
+ * Set when a swallowed storage failure may have left a header with no `t:`
922
+ * entry in THIS instance (see `drainRecordGuarded`). Sticky: the instance
923
+ * then never writes {@link CLEAN_KEY} back, so its successor runs the walk.
924
+ */
925
+ private dirty;
926
+ /**
927
+ * Tail of the serialized `pool:<name>` critical section — see
928
+ * the pool lock (`withPoolLock`). Per-instance, which is the right scope: the pool rows
929
+ * live in this Durable Object's own storage and only this instance writes
930
+ * them.
931
+ */
932
+ private poolLock;
933
+ /**
934
+ * Record id → the `t:` index key its in-flight claim currently holds, for
935
+ * every dispatch this instance has open. See `drainRecordGuarded()`.
936
+ *
937
+ * A lease moves a record's index entry without rewriting its `scheduledFor`,
938
+ * so while a claim is held the live key is NOT the one derivable from the
939
+ * record. Anything that has to remove such a record — `removeRecord()`, on
940
+ * the `/cancel` path — would otherwise delete a key that no longer exists
941
+ * and strand the real one.
942
+ *
943
+ * In-memory and per-instance on purpose: it answers "is THIS instance
944
+ * dispatching that record right now", which is exactly when the divergence
945
+ * can be observed by another request. A lease left behind by an instance that
946
+ * died has no live dispatch to protect and is reconciled from storage
947
+ * instead — `alarm()` drops it as a dangling entry once the header is gone.
948
+ */
949
+ private readonly activeLeases;
950
+ /**
951
+ * Ids `/cancel` removed while this instance held their dispatch lease.
952
+ *
953
+ * The attempt is already in flight when such a cancel lands, and whatever it
954
+ * settles to must not write the job back: `recordRetry()` and
955
+ * `requeuePooled()` re-create the `id:` header and a `t:` entry, so a
956
+ * failed attempt would resurrect a job `/cancel` answered `{ cancelled: true }`
957
+ * for, and it would fire again. Both check this set synchronously right
958
+ * before their single write, so no `/cancel` can land between the check and
959
+ * the write. Cleared with the lease in `drainRecordGuarded()`.
960
+ */
961
+ private readonly cancelledLeases;
689
962
  constructor(state: SchedulerDOState, env: SchedulerEnv);
690
963
  fetch(request: Request): Promise<Response>;
691
- /** Called by the Workers runtime when the alarm previously set by `_rescheduleAlarm()` fires. */
964
+ /** Called by the Workers runtime when the alarm previously set by `rescheduleAlarm()` fires. */
692
965
  alarm(): Promise<void>;
693
966
  /**
694
967
  * Internal dispatch hook; overridden in unit tests to capture the outgoing
@@ -701,31 +974,119 @@ declare class SchedulerDO {
701
974
  * drop. After {@link MAX_RETRY_ATTEMPTS} the record is parked under a
702
975
  * `dead:` key for inspection — never silently deleted.
703
976
  *
977
+ * One non-2xx is told apart: a `409` carrying `DISPATCH_IN_PROGRESS` returns
978
+ * `"in-progress"`. The shard is saying the first attempt of this very record
979
+ * is still running, so {@link recordRetry} re-arms it without charging an
980
+ * attempt — see there.
981
+ *
704
982
  * The dispatch target is taken from `env.LUNORA_ORIGIN_URL` (NOT from the
705
- * stored record) to prevent SSRF via a forged `originUrl` on the schedule
706
- * request. If that env var is missing at fire time (a deploy/binding
983
+ * stored record) so a schedule request can never name where the DO calls
984
+ * back — that would be SSRF. If that env var is missing at fire time (a deploy/binding
707
985
  * regression — schedule time already enforced its presence) we return
708
986
  * `false` so the record is retried rather than silently dropped.
709
987
  */
710
- protected dispatch(record: ScheduleRecord): Promise<boolean>;
988
+ protected dispatch(record: ScheduleRecord): Promise<boolean | "in-progress">;
989
+ /**
990
+ * Register the hibernation-safe ping/pong keepalive. The runtime answers a
991
+ * {@link WS_KEEPALIVE_PING} text frame with {@link WS_KEEPALIVE_PONG}
992
+ * WITHOUT waking this Durable Object, keeping an idle `/ws` subscription
993
+ * alive across hibernation with no billable wakeup and no dispatch. Without
994
+ * this, a client's heartbeat ping goes unanswered and its watchdog force-
995
+ * closes the socket every ~90s, defeating hibernation (each unanswered ping
996
+ * wakes the DO to reconnect) — mirrors `@lunora/do`'s
997
+ * `ShardDO.armWebSocketKeepalive`. The auto-response is per-instance, so
998
+ * this re-runs on every construction (including a post-hibernation wake).
999
+ * Guarded: the API and the `WebSocketRequestResponsePair` global are absent
1000
+ * in the unit harness and on older runtimes, where it degrades to a no-op.
1001
+ */
1002
+ private armWebSocketKeepalive;
1003
+ /**
1004
+ * Drain the due slice with up to {@link MAX_CONCURRENT_DISPATCHES} records in
1005
+ * flight at once, so a slow job delays only its own lane instead of every
1006
+ * other due job in the app (see the constant for why the drain used to
1007
+ * serialise whole jobs, not just their kicks).
1008
+ *
1009
+ * Lanes pull from the head of the slice, so records still ENTER dispatch in
1010
+ * the slice's order — the same `t:<paddedTime>:<id>` order the sequential
1011
+ * drain used. What is no longer implied is that they FINISH in that order,
1012
+ * which was never a guarantee worth relying on anyway: two jobs due at the
1013
+ * same instant already ran in storage-key (id) order rather than arrival
1014
+ * order, a saturated pooled job is pushed {@link POOL_BACKPRESSURE_DELAY_MS}
1015
+ * into the future ahead of its queue-mates, and a failed job re-enters at the
1016
+ * end of a backoff. Nothing in the public surface documents an ordering
1017
+ * guarantee; jobs that must be ordered must chain themselves.
1018
+ *
1019
+ * {@link drainRecordGuarded} swallows every throw, so no lane can reject and
1020
+ * abandon its siblings.
1021
+ */
1022
+ private drainDue;
1023
+ /**
1024
+ * Run `critical` with exclusive access to the `pool:<name>` rows.
1025
+ *
1026
+ * Every pool mutation is a read-modify-write (`loadPool` → mutate →
1027
+ * `savePool`), and the two halves are separated by an `await`. That was safe
1028
+ * while the drain ran one record at a time — the Durable Object input gate
1029
+ * keeps a foreign event (a concurrent `/complete`) out while a storage
1030
+ * operation is in flight, and nothing else in this instance could interleave.
1031
+ * Concurrent lanes break exactly that assumption: lane A and lane B can both
1032
+ * issue their `get` before either `put` lands, both observe `inFlight: 0`,
1033
+ * and the second `put` then erases the first lane's reservation — the pool
1034
+ * oversubscribes and one holder's id is lost, so its slot is never released.
1035
+ *
1036
+ * The lock is a promise chain rather than anything cleverer because the
1037
+ * critical section is two local storage ops with no I/O in it. It is held
1038
+ * across NO outbound fetch: `dispatch()` runs outside it, which is the whole
1039
+ * point of draining concurrently.
1040
+ *
1041
+ * The chain is rebuilt from a swallowed copy so one rejecting section can
1042
+ * never wedge every later one.
1043
+ */
1044
+ private withPoolLock;
711
1045
  /**
712
1046
  * Claim + drain one due record with per-record fault isolation, so a storage
713
1047
  * throw can never abort the whole alarm pass (which would skip the remaining
714
1048
  * due records and the `rescheduleAlarm()` that re-arms the clock).
715
1049
  *
716
- * Claims the job by deleting its time-index entry BEFORE dispatch (an alarm
717
- * re-fire then won't pick it up again), runs {@link drainRecord}, and on a
718
- * thrown storage op re-asserts the claim so the job stays re-fireable.
1050
+ * The claim is a LEASE, not a deletion. The record's `t:` entry is moved
1051
+ * from its due time to `now + DISPATCH_LEASE_MS` before
1052
+ * {@link SchedulerDO.dispatch} is called, so this alarm pass (and the next)
1053
+ * will not pick it up again, while the record is never left WITHOUT an index
1054
+ * entry. That distinction is the whole point: deleting the entry outright
1055
+ * made an instance evicted mid-dispatch leave an `id:` header with no index,
1056
+ * which {@link SchedulerDO.reindexOrphanedRecords} re-armed and the
1057
+ * successor fired AGAIN on sight — concurrently with an attempt that could
1058
+ * still be running at the origin. A leased record is not an orphan, so the
1059
+ * successor leaves it alone until the lease lapses; see
1060
+ * {@link DISPATCH_LEASE_MS} for why that horizon is fifteen minutes and what
1061
+ * it does and does not bound.
1062
+ *
1063
+ * The lease is released as soon as this instance knows the attempt settled —
1064
+ * dispatched, re-armed for retry, backpressured, or dead-lettered — so the
1065
+ * horizon only ever governs the one case nobody is left to report: a lost
1066
+ * instance.
719
1067
  *
720
1068
  * A throw reaching here always means the job was NOT dispatched:
721
1069
  * {@link drainRecord} swallows its own post-dispatch cleanup errors and
722
1070
  * returns instead of throwing once a kick succeeds, so every escaping throw
723
- * comes from the pre-dispatch or failed-dispatch paths. We therefore always
724
- * re-assert the time-index claim so a later alarm re-attempts it
725
- * (at-least-once): the claim delete may have removed it and
726
- * recordRetry()/requeuePooled() may not have re-armed it before throwing, and
727
- * re-inserting the same key is idempotent, so a surviving claim is simply
728
- * rewritten to its prior value.
1071
+ * comes from the pre-dispatch or failed-dispatch paths. Nothing is in flight,
1072
+ * so the lease is dropped and the due-time claim re-asserted — keeping the
1073
+ * job re-fireable on the very next alarm (at-least-once) rather than letting
1074
+ * a transient storage blip cost it a whole lease.
1075
+ *
1076
+ * With one exception, checked first: a record that already has a durable
1077
+ * `dead:` row is TERMINAL, and re-claiming it would re-dispatch a job the
1078
+ * dead-letter says is finished. See the comment on that branch.
1079
+ *
1080
+ * `claimKey` is the index key `alarm()` SELECTED this record under, passed
1081
+ * down rather than recomputed. That is load-bearing, not tidiness: a lease
1082
+ * moves the record's index entry and deliberately does NOT rewrite its
1083
+ * `scheduledFor` (that field is the job's real due time, which `/list`,
1084
+ * `/get`, `/dead` and the studio all show, and which `parkDead` preserves).
1085
+ * So from the moment a lease is taken the live key and the key derivable
1086
+ * from the record disagree — and a claim that recomputed it would delete a
1087
+ * key that no longer exists while adding a second one, leaving the record
1088
+ * indexed twice and dispatched twice. That is the same double-run the lease
1089
+ * exists to close, re-entering through the expiry path.
729
1090
  */
730
1091
  private drainRecordGuarded;
731
1092
  /**
@@ -756,12 +1117,15 @@ declare class SchedulerDO {
756
1117
  * always return `true` without touching any pool state.
757
1118
  *
758
1119
  * The pool row is read FRESH from storage on every call — never cached
759
- * across the drain. Each reservation durably `savePool()`s before the next
760
- * record runs, so a same-pass reservation is still visible to the next
761
- * record's fresh read (the budget carries forward); and because dispatch()
762
- * awaits an outbound fetch between records, a concurrent /complete that
763
- * decrements the row mid-drain IS reflected here instead of being clobbered
764
- * by a stale in-memory copy (which would leak a slot permanently).
1120
+ * across the drain — and the read-modify-write runs under
1121
+ * the pool lock (`withPoolLock`). Both halves are load-bearing. Freshness is what
1122
+ * keeps a concurrent `/complete` landing during a dispatch from being
1123
+ * clobbered by a stale in-memory copy (which would leak a slot permanently: a
1124
+ * POOL SLOT has no expiry, unlike the dispatch claim's). The lock is what
1125
+ * keeps two drain lanes from both reading the same pre-reservation row and
1126
+ * both believing a slot was free — without it the pool oversubscribes past
1127
+ * `maxConcurrency` and one holder's id is dropped from `inFlightIds`, so its
1128
+ * slot is never released.
765
1129
  */
766
1130
  private reservePoolSlot;
767
1131
  /**
@@ -773,13 +1137,33 @@ declare class SchedulerDO {
773
1137
  */
774
1138
  private handleWebSocketUpgrade;
775
1139
  /**
776
- * Re-list the jobs and push them to every connected subscriber. Called after
777
- * any change (schedule / cancel / alarm-fire) so live studios reflect it
778
- * immediately. A no-op when the runtime doesn't support hibernated sockets.
1140
+ * Re-list the jobs (bounded — see {@link listPage}) and push them to
1141
+ * every connected subscriber. Called after any change (schedule / cancel /
1142
+ * alarm-fire) so live studios reflect it immediately. A no-op when the
1143
+ * runtime doesn't support hibernated sockets.
779
1144
  */
780
1145
  private broadcastChange;
781
- /** The current pending job records (shared by `/list` and the live channel). */
782
- private listRecords;
1146
+ /**
1147
+ * One bounded page of the rows under `prefix`, in key order, plus the
1148
+ * `cursor` a caller resumes from (the last key of the page) when `truncated`.
1149
+ * Lists `limit + 1` and slices back down so both facts are known without a
1150
+ * second round-trip.
1151
+ *
1152
+ * Shared by `/list` (pending headers) and `/dead` (dead-letter records) so
1153
+ * NEITHER can materialize an unbounded set into one JSON response: nothing
1154
+ * prunes `dead:`, so a workpool with a broken origin parks thousands of rows
1155
+ * and the studio's only view of them — and only way to requeue them — would
1156
+ * fail exactly when it is needed.
1157
+ */
1158
+ private listPage;
1159
+ /**
1160
+ * Page through every row under `prefix` exactly once with bounded per-page
1161
+ * memory (a `limit`+`startAfter` cursor loop), invoking `visit` for each.
1162
+ * Unlike {@link listPage}, which intentionally truncates for the studio's
1163
+ * live view, `/status` and `/pool` need EXACT counts — this walks the full
1164
+ * set, but never materializes more than one page at a time.
1165
+ */
1166
+ private forEachPage;
783
1167
  /**
784
1168
  * HMAC-SHA-256 sign the dispatch body with `env.LUNORA_SCHEDULER_SECRET`,
785
1169
  * returning a base64url signature, or `undefined` when no secret is
@@ -792,9 +1176,31 @@ declare class SchedulerDO {
792
1176
  * The retry budget/backoff comes from the record's {@link RetryPolicy}
793
1177
  * (falling back to the DO defaults); on exhaustion the record is parked
794
1178
  * under a `dead:` key for manual inspection.
1179
+ *
1180
+ * **A `DISPATCH_IN_PROGRESS` decline (`inProgress`) is not charged.** It
1181
+ * means the record's first attempt is still running on the shard, not that
1182
+ * anything failed; charging it would spend the budget while that attempt is
1183
+ * doing the work, and if it then failed the job would dead-letter having
1184
+ * run once. It still re-arms at the backoff of the NEXT charged attempt, at
1185
+ * least {@link RETRY_BASE_DELAY_MS} apart — nothing else rate-limits an
1186
+ * uncharged retry, and polling a running attempt faster gains nothing.
1187
+ *
1188
+ * It is bounded, not forever, only because the shard's claim is: a claim
1189
+ * older than the shard's fifteen-minute ceiling is treated as stale and the
1190
+ * next delivery runs (and is charged as usual if it fails). A handler that
1191
+ * hangs therefore costs at most that long in declines before the ordinary
1192
+ * budget applies again. Without that ceiling, not charging would let one hung
1193
+ * handler keep its record retrying and never dead-letter.
795
1194
  */
796
1195
  private recordRetry;
797
- /** Read the durable `pool:&lt;name>` row, defaulting to a fresh `inFlight: 0` pool. */
1196
+ /**
1197
+ * Terminal park into the dead-letter (`dead:`) prefix, with `reason` naming
1198
+ * why in the emitted warning. Shared by the two ways a retry ends for good:
1199
+ * an exhausted attempt budget, and a backoff that ran past the largest
1200
+ * schedulable time (see {@link isIndexableTime}).
1201
+ */
1202
+ private parkDead;
1203
+ /** Read the durable `pool:<name>` row, defaulting to a fresh `inFlight: 0` pool. */
798
1204
  private loadPool;
799
1205
  private savePool;
800
1206
  /**
@@ -816,28 +1222,72 @@ declare class SchedulerDO {
816
1222
  private handlePoolStatus;
817
1223
  /**
818
1224
  * `GET /status` — the app-level backlog signal that powers the studio's
819
- * SLO view. Enumerates every durable `pool:&lt;name>` row for its `inFlight`/
1225
+ * SLO view. Enumerates every durable `pool:<name>` row for its `inFlight`/
820
1226
  * `maxConcurrency` semaphore, counts the pending (not-yet-dispatched) jobs
821
- * routed to each pool with the same single-pass scan {@link handlePoolStatus}
822
- * uses, and rolls those up into app-wide `backlog` (sum of `queued`) and
823
- * `inFlight` (sum of held slots) totals.
1227
+ * routed to each pool from its `pq:` rows, and rolls those up into app-wide
1228
+ * `backlog` (sum of `queued`) and `inFlight` (sum of held slots) totals.
824
1229
  *
825
1230
  * Pools that have rows but no queued jobs still appear (with `queued: 0`) so
826
1231
  * a saturated-but-idle pool stays visible; a pool that only ever existed as
827
1232
  * queued jobs without a persisted row is unreachable here (the schedule path
828
- * always writes a `pool:&lt;name>` row before the job's header), so a single
829
- * scan over `pool:`/`id:` is sufficient.
1233
+ * always writes a `pool:<name>` row before the job's header), so a single
1234
+ * scan over `pool:` plus a cursor loop over `pq:` is sufficient.
830
1235
  */
831
1236
  private handleStatus;
1237
+ /**
1238
+ * Persist (or refresh) a pool's concurrency cap, so the alarm-time gate has
1239
+ * a durable `maxConcurrency` even after the enqueuing client is gone.
1240
+ */
1241
+ private persistPoolCap;
1242
+ /**
1243
+ * The `409` a caller-supplied id earns when something durable already holds
1244
+ * it, or `undefined` when the id is free.
1245
+ *
1246
+ * A pending header is the obvious half: `put` on `id:<id>` overwrites, but
1247
+ * the `t:` index is keyed by TIME as well as id, so the OLD entry survives.
1248
+ * The drain then dispatches the NEW record at the OLD time and deletes the
1249
+ * entry it should have fired at — the job runs early and never runs again.
1250
+ * Refused rather than made a replace: `RunOptions.id` exists so a deferred
1251
+ * schedule can name its own job, and silently retiming someone else's is the
1252
+ * worse failure.
1253
+ *
1254
+ * The `dead:` row holds the id too, and for a worse reason. A dead record
1255
+ * keeps NO `id:` header, so a pending-only check leaves the id apparently
1256
+ * free — and a later `/dead/retry` writes the revived corpse straight over
1257
+ * the new job's header and adds a SECOND time index under the same id. The
1258
+ * new job is gone and the dead one fires in its place. Recovering a dead job
1259
+ * is an operator action taken minutes or days after the schedule, so nothing
1260
+ * at schedule time would ever have surfaced the collision.
1261
+ */
1262
+ private idConflict;
1263
+ /**
1264
+ * The id the record is stored under, or the `Response` refusing it.
1265
+ *
1266
+ * A caller id that is not a safe key segment is refused with a `400` rather
1267
+ * than minted over: `RunOptions.id` is not an idempotency key, so swapping an
1268
+ * invalid one for a random id made two calls naming it schedule two jobs
1269
+ * where the second should have answered `409`.
1270
+ *
1271
+ * Only an id the CALLER chose can collide — a minted one is 96 random bits —
1272
+ * so {@link idConflict} costs two `get`s on the deferred path and nothing on
1273
+ * the ordinary one.
1274
+ */
1275
+ private resolveId;
832
1276
  private handleSchedule;
833
1277
  private handleCancel;
1278
+ /**
1279
+ * `GET /list[?cursor=]` — one bounded page of pending jobs. `truncated` says
1280
+ * whether more rows follow and `cursor` is what a caller passes back to get
1281
+ * them (`createScheduler.list()` walks every page; the studio shows one).
1282
+ */
834
1283
  private handleList;
835
1284
  /**
836
1285
  * `GET /dead` — list the dead-letter records: jobs that exhausted their
837
- * retry budget ({@link recordRetry}) and were parked under `dead:&lt;id>`
1286
+ * retry budget ({@link recordRetry}) and were parked under `dead:<id>`
838
1287
  * instead of being silently dropped. These never appear in `/list` (their
839
1288
  * `id:` header is deleted on park), so this is the ONLY way the studio can
840
- * surface — and recover — a permanently-failed job.
1289
+ * surface — and recover — a permanently-failed job. Bounded and cursored
1290
+ * like `/list`: nothing prunes `dead:`, so this set grows without limit.
841
1291
  */
842
1292
  private handleDeadList;
843
1293
  /**
@@ -855,7 +1305,7 @@ declare class SchedulerDO {
855
1305
  */
856
1306
  private handleDeadCancel;
857
1307
  /**
858
- * Resolve a single pending job by id via a direct `id:&lt;id>` storage read —
1308
+ * Resolve a single pending job by id via a direct `id:<id>` storage read —
859
1309
  * O(1), versus scanning the whole `/list` view. Responds `{ record }` on a
860
1310
  * hit and `{}` on a miss (an absent `record` field — JSON has no `undefined`
861
1311
  * — which the client reads back as `null`).
@@ -869,6 +1319,74 @@ declare class SchedulerDO {
869
1319
  * full `t:` rescan is unnecessary unless the new job is the new earliest.
870
1320
  */
871
1321
  private armAlarmIfEarlier;
1322
+ /**
1323
+ * Re-index every pending job whose time-index entry is gone, and fire it now.
1324
+ *
1325
+ * A record with an `id:` header but no `t:` entry is invisible to every
1326
+ * clock in this class: {@link SchedulerDO.rescheduleAlarm} derives the alarm
1327
+ * from `t:` alone, and `alarm()`'s inline reconciliation only handles the
1328
+ * INVERSE orphan (a `t:` entry whose header is gone). Left alone such a job
1329
+ * sits in `/list` and `/status.backlog` forever — never fires, never reaches
1330
+ * `/dead`.
1331
+ *
1332
+ * **This is no longer how a lost dispatch looks.**
1333
+ * {@link SchedulerDO.drainRecordGuarded} used to claim a record by deleting
1334
+ * its `t:` entry outright, so an instance evicted mid-dispatch minted an
1335
+ * orphan on every claimed record and this method re-fired each of them ON
1336
+ * SIGHT — concurrently with attempts that could still have been running at
1337
+ * the origin. The claim is a lease now (see {@link DISPATCH_LEASE_MS}): a
1338
+ * claimed record keeps a `t:` entry at the lease horizon, so it is not an
1339
+ * orphan, is not recovered here, and is re-fired by the ordinary alarm drain
1340
+ * only once the lease lapses.
1341
+ *
1342
+ * What still reaches this method is the residue of a storage failure — a
1343
+ * claim released with no lease written, or a pre-lease record written by an
1344
+ * older build — where nothing was dispatched and firing immediately is
1345
+ * exactly right.
1346
+ *
1347
+ * The dispatch is deduplicated by the record id, which the receiver spends
1348
+ * as `x-lunora-mutation-id` for a function target and as the workflow
1349
+ * INSTANCE id for a `workflow` target. A mutation's dedup read runs inside
1350
+ * the shard's single-writer gate, so a mutation is exactly-once even under a
1351
+ * genuinely concurrent re-fire; a workflow re-attaches to the running
1352
+ * instance rather than starting a second one. An ACTION takes no gate —
1353
+ * gating one would let any caller freeze a whole shard for the length of an
1354
+ * action's outbound I/O — and its dedup row is written only after the
1355
+ * handler returns, so the cache alone could not tell "already ran" from
1356
+ * "still running". The shard closes that itself (#803): it claims the dedup
1357
+ * key before entering the handler and answers a second delivery of a live
1358
+ * key `409 DISPATCH_IN_PROGRESS`, which is a non-2xx, so the record is
1359
+ * re-armed rather than cleared.
1360
+ *
1361
+ * Bounded walks (all `t:` values, `pq:` rows, then all `id:` headers) rather
1362
+ * than a per-header `get`, so the cost is one pass over each prefix.
1363
+ *
1364
+ * **The walk runs only when {@link CLEAN_KEY} is absent.** It is O(every
1365
+ * pending job), and an instance is evicted between alarms spaced wider than the
1366
+ * idle timeout, so it must not run on every new instance. The key is sufficient because
1367
+ * every remaining way to mint an orphan sits inside an alarm drain: the
1368
+ * schedule, dead-retry, retry and requeue writes each put header and index in
1369
+ * ONE call, and cancel deletes them in one. `alarm()` deletes the key before
1370
+ * a non-empty drain and writes it back only after the drain settled with no
1371
+ * swallowed failure ({@link dirty}) in an instance whose own recovery
1372
+ * finished — so an instance that dies mid-drain, or swallowed a failed
1373
+ * index write, leaves the key absent and its successor walks. A store from
1374
+ * an older build has no key and is walked once. The no-clock check at the
1375
+ * end is cheap and runs on every new instance regardless.
1376
+ */
1377
+ private reindexOrphanedRecords;
1378
+ /** One run of {@link reindexOrphanedRecords}. */
1379
+ private recoverStore;
1380
+ /** The full orphan walk — see {@link reindexOrphanedRecords}. */
1381
+ private reindexWalk;
1382
+ /**
1383
+ * The time component of the earliest pending `t:` entry, or `undefined` when
1384
+ * there is no pending entry at all. Reads exactly one row — the index's
1385
+ * lexical order is its numeric order. A present-but-unreadable key yields
1386
+ * `NaN`, which callers must distinguish from "nothing pending": the two
1387
+ * answers mean opposite things for the alarm.
1388
+ */
1389
+ private earliestPendingTime;
872
1390
  private rescheduleAlarm;
873
1391
  }
874
1392
  /** What the Cloudflare scheduler host needs from the Worker's environment. */
@@ -883,14 +1401,14 @@ interface SchedulerHostOptions {
883
1401
  * the worker's own jurisdiction so scheduled state co-resides with app data.
884
1402
  */
885
1403
  jurisdiction?: "eu" | "fedramp" | "us";
886
- /** The `SchedulerDO` namespace binding. */
887
- namespace: Parameters<typeof createScheduler>[0]["namespace"];
888
1404
  /**
889
- * Public origin the Worker is mounted at. `SchedulerDO` dispatches back to
890
- * this base URL when an alarm fires, so a wrong value means jobs fire into
891
- * nothing.
1405
+ * The `SchedulerDO` namespace binding.
1406
+ *
1407
+ * The origin the DO dispatches back to is not configured here — it reads
1408
+ * `env.LUNORA_ORIGIN_URL` off its own binding at fire time, so a wrong value
1409
+ * there (or none) is what makes jobs fire into nothing.
892
1410
  */
893
- originUrl: string;
1411
+ namespace: Parameters<typeof createScheduler>[0]["namespace"];
894
1412
  }
895
1413
  /**
896
1414
  * Build the Cloudflare {@link SchedulerHost}.
@@ -898,12 +1416,49 @@ interface SchedulerHostOptions {
898
1416
  * The returned host has no `cron` member — see the module docstring.
899
1417
  */
900
1418
  declare const createSchedulerHost: (options: SchedulerHostOptions) => SchedulerHost;
901
- /** Standard cron expression (5- or 6-field) or a supported `@macro`, per `cron-parser`. */
902
- declare const isValidCronExpression: (schedule: string) => boolean;
903
1419
  /**
904
- * Assert a raw cron expression is well-formed, throwing the same shaped error
905
- * both cron surfaces use. The `context` prefix lets callers name the offending
906
- * job (`cron job "send digest"`) vs. the bare trigger.
1420
+ * Reject a `delayMs` a scheduler cannot act on, before it reaches the
1421
+ * SchedulerDO.
1422
+ *
1423
+ * A `NaN`/`Infinity` delay serializes to `null` through JSON and lands as a
1424
+ * malformed `scheduledFor`; a negative one schedules into the past. Both are the
1425
+ * caller's argument, so the answer has to name the argument — which is why the
1426
+ * code is `INVALID_INPUT` (400) and not `INTERNAL`: `toErrorBody` replaces an
1427
+ * internal-coded message with "Internal error", redacting the one sentence that
1428
+ * says what to fix.
1429
+ *
1430
+ * Exported because four surfaces enforce it — `createScheduler().runAfter`,
1431
+ * `createWorkpool().enqueue`, `@lunora/server`'s deferred-schedule facade (which
1432
+ * must reject BEFORE the transaction commits, not at flush time) and
1433
+ * `@lunora/testing`'s fake scheduler. They used to restate it and threw three
1434
+ * different codes between them, so a test written against the harness caught one
1435
+ * code while production threw another.
1436
+ * @param delayMs the delay to validate
1437
+ * @param surface what to name in the message — the call the delay was passed to (e.g. `"ctx.scheduler.runAfter"`)
1438
+ * @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
1439
+ */
1440
+ declare const assertScheduleDelay: (delayMs: number, surface: string, argument?: string) => void;
1441
+ /**
1442
+ * Reject a `runAt` instant a scheduler cannot act on — {@link assertScheduleDelay}'s
1443
+ * bound, restated for the absolute form by converting the instant to the delay it
1444
+ * implies.
1445
+ *
1446
+ * `runAfter` has refused a `NaN`/`Infinity` argument since the guard was written;
1447
+ * `runAt` took the same value through a different door and let it reach the DO,
1448
+ * where it serializes to `null` through JSON and lands as a `scheduledFor` no
1449
+ * alarm can ever fire. `new Date("2026-13-01")`, `runAt(row.dueAt + delay)` on a
1450
+ * row whose `dueAt` is absent — both arrive here as a number that is not one.
1451
+ *
1452
+ * An instant already in the PAST is not refused. It is an overdue job
1453
+ * (`runAt(row.dueAt)` on a row that came due while the request was in flight),
1454
+ * and `runAfter` itself reaches `runAt` a fraction of a millisecond after
1455
+ * capturing its own clock reading — so a strict sign check would fail the
1456
+ * documented `runAfter(0, …)` call at random. The delay is therefore clamped at
1457
+ * zero while it is still a finite number, which leaves the half that matters:
1458
+ * a value that is not a number at all.
1459
+ * @param timestampMs the absolute instant (epoch ms) the caller passed
1460
+ * @param nowMs the clock to measure it against — the wall clock in production, the harness's virtual clock in a test
1461
+ * @param surface what to name in the message — the call the instant was passed to (e.g. `"ctx.scheduler.runAt"`)
907
1462
  */
908
- declare const assertValidCronExpression: (schedule: string, context?: string) => void;
909
- 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 };
1463
+ declare const assertScheduleInstant: (timestampMs: number, nowMs: number, surface: string) => void;
1464
+ 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, compileCronSchedule, createCronTrigger, createQueueConsumer, createQueueWorkpool, createScheduler, createSchedulerHost, createWorkpool, cronJobs, httpDispatcher, isWorkflowReference, resolveScheduleId };