@lunora/scheduler 1.0.0-alpha.1 → 1.0.0-alpha.10

package/dist/index.d.mts

@@ -45,6 +45,15 @@ interface WorkflowReference<Params = Record<string, unknown>> {
 type CronTarget = FunctionReference | WorkflowReference;
 /** The arguments a cron's target accepts: a workflow's inferred `params`, else an open record (function args aren't inferred). */
 type CronTargetArgs<T extends CronTarget> = T extends WorkflowReference<infer Params> ? Params : Record<string, unknown>;
+/**
+* The arguments a one-shot schedule target ({@link Scheduler.runAfter} /
+* {@link Scheduler.runAt}) accepts. Unlike {@link CronTargetArgs} it preserves a
+* {@link FunctionReference}'s inferred `args` (via {@link ArgsOf}) as well as a
+* {@link WorkflowReference}'s inferred `params`, so scheduling a plain function
+* keeps its today's arg checking while scheduling a workflow/agent infers its
+* `params`.
+*/
+type ScheduleTargetArgs<T extends CronTarget> = T extends WorkflowReference<infer Params> ? Params : T extends FunctionReference ? ArgsOf<T> : Record<string, unknown>;
 /** Narrow a {@link CronTarget} to a {@link WorkflowReference} by its runtime brand. */
 declare const isWorkflowReference: (target: unknown) => target is WorkflowReference;
 /**
@@ -93,7 +102,12 @@ interface ScheduleRecord {
   */
   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
@@ -113,6 +127,14 @@ interface ScheduleRecord {
   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<{
@@ -122,19 +144,39 @@ interface Scheduler {
   get: (id: string) => Promise<ScheduleRecord | null>;
   /** All pending scheduled jobs (the DO's `/list` view). */
   list: () => Promise<ScheduleRecord[]>;
-  runAfter: <F extends FunctionReference>(delayMs: number, function_: F, args: ArgsOf<F>, options?: RunOptions) => Promise<{
+  /**
+  * Schedule `target` to run once, `delayMs` from now. `target` is a function
+  * {@link FunctionReference} (dispatched as a one-shot) or a durable
+  * {@link WorkflowReference} — the generated `workflows.&lt;name>` /
+  * `agents.&lt;name>` ref — which starts a fresh instance on fire (args become
+  * its `params`). {@link ScheduleTargetArgs} infers the accepted args from
+  * whichever target was passed.
+  */
+  runAfter: <T extends CronTarget>(delayMs: number, target: T, args: ScheduleTargetArgs<T>, options?: RunOptions) => Promise<{
     id: string;
     scheduledFor: number;
   }>;
-  runAt: <F extends FunctionReference>(date: Date | number, function_: F, args: ArgsOf<F>, options?: RunOptions) => Promise<{
+  /** Like {@link Scheduler.runAfter} but fires at an absolute `date`/timestamp. */
+  runAt: <T extends CronTarget>(date: Date | number, target: T, args: ScheduleTargetArgs<T>, options?: RunOptions) => Promise<{
     id: string;
     scheduledFor: number;
   }>;
 }
+/**
+* Cloudflare Durable Object data-residency jurisdiction. Widening union —
+* Cloudflare adds values over time.
+* @see https://developers.cloudflare.com/durable-objects/reference/data-location/
+*/
+type DurableObjectJurisdiction = "eu" | "fedramp" | "us";
 /** Subset of `DurableObjectNamespace` the package consumes. */
 interface DurableObjectNamespaceLike {
   get: (id: DurableObjectIdLike) => DurableObjectStubLike;
   idFromName: (name: string) => DurableObjectIdLike;
+  /**
+  * Derive a jurisdiction-restricted subnamespace. Optional because older
+  * workers-types releases (and test doubles) may not expose it.
+  */
+  jurisdiction?: (jurisdiction: DurableObjectJurisdiction) => DurableObjectNamespaceLike;
 }
 interface DurableObjectIdLike {
   toString: () => string;
@@ -145,6 +187,13 @@ interface DurableObjectStubLike {
 interface LunoraSchedulerOptions {
   /** Optional named instance — useful for tenant isolation. Default `default`. */
   instanceName?: string;
+  /**
+  * Pin the SchedulerDO (durable timers + cron state) to a Cloudflare
+  * data-residency jurisdiction. Pass the same value as the worker's
+  * `jurisdiction` so scheduled state co-resides with app data. Omit for the
+  * un-pinned global namespace.
+  */
+  jurisdiction?: DurableObjectJurisdiction;
   /** Binding to the `SchedulerDO` durable object namespace. */
   namespace: DurableObjectNamespaceLike;
   /**
@@ -599,6 +648,13 @@ declare class SchedulerDO {
   * compatibility shim, not the hot path.
   */
   private static releaseFirstSlot;
+  /**
+  * Normalize the mutually-exclusive dispatch target off an untrusted body: a
+  * one-shot function path (`functionPath`) or a durable workflow/agent
+  * instance (`workflow`, a `WORKFLOW_*`/`AGENT_*` binding). Returns `undefined`
+  * when neither is present so the caller can reject the schedule.
+  */
+  private static resolveScheduleTarget;
   protected readonly state: SchedulerDOState;
   protected readonly env: SchedulerEnv;
   constructor(state: SchedulerDOState, env: SchedulerEnv);
@@ -630,15 +686,17 @@ declare class SchedulerDO {
   *
   * 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.
+  * thrown storage op re-asserts the claim so 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.
+  * A throw reaching here always means the job was NOT dispatched:
+  * {@link drainRecord} swallows its own post-dispatch cleanup errors and
+  * returns instead of throwing once a kick succeeds, so every escaping throw
+  * comes from the pre-dispatch or failed-dispatch paths. We therefore always
+  * re-assert the time-index claim so a later alarm re-attempts it
+  * (at-least-once): the claim delete may have removed it and
+  * recordRetry()/requeuePooled() may not have re-armed it before throwing, and
+  * re-inserting the same key is idempotent, so a surviving claim is simply
+  * rewritten to its prior value.
   */
   private drainRecordGuarded;
   /**
@@ -648,16 +706,18 @@ declare class SchedulerDO {
   * 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.
+  * {@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). 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.
+  * 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;
   /**
@@ -665,6 +725,14 @@ declare class SchedulerDO {
   * 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;
   /**
@@ -782,4 +850,4 @@ declare const isValidCronExpression: (schedule: string) => boolean;
 * job (`cron job "send digest"`) vs. the bare trigger.
 */
 declare const assertValidCronExpression: (schedule: string, context?: string) => void;
-export { type ArgsOf, CRON_SCHEDULE_KINDS, type CronJob, type CronJobsBuilder, type CronScheduleKind, type CronTarget, type CronTriggerOptions, type CronTriggerSnippet, type DailySchedule, type DurableObjectIdLike, type DurableObjectNamespaceLike, type DurableObjectStubLike, type EnqueueOptions, type FunctionReference, type HttpDispatcherOptions, type IntervalSchedule, type LunoraSchedulerOptions, type MessageBatchLike, type MonthlySchedule, type QueueConsumerOptions, type QueueDispatch, type QueueEnqueueOptions, type QueueJob, type QueueLike, type QueueMessageLike, type QueueSendOptionsLike, type QueueSendRequestLike, type QueueWorkpool, type QueueWorkpoolOptions, type RetryPolicy, type RunOptions, type ScheduleRecord, type Scheduler, SchedulerDO, type SchedulerDOState, type SchedulerEnv, type SchedulerPoolStatus, type SchedulerStatus, type WeeklySchedule, type WorkflowReference, type Workpool, type WorkpoolOptions, assertValidCronExpression, compileCronSchedule, createCronTrigger, createQueueConsumer, createQueueWorkpool, createScheduler, createWorkpool, cronJobs, httpDispatcher, isValidCronExpression, isWorkflowReference };
+export { type ArgsOf, CRON_SCHEDULE_KINDS, type CronJob, type CronJobsBuilder, type CronScheduleKind, type CronTarget, type CronTriggerOptions, type CronTriggerSnippet, type DailySchedule, type DurableObjectIdLike, type DurableObjectJurisdiction, type DurableObjectNamespaceLike, type DurableObjectStubLike, type EnqueueOptions, type FunctionReference, type 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 };

package/dist/index.d.ts

@@ -45,6 +45,15 @@ interface WorkflowReference<Params = Record<string, unknown>> {
 type CronTarget = FunctionReference | WorkflowReference;
 /** The arguments a cron's target accepts: a workflow's inferred `params`, else an open record (function args aren't inferred). */
 type CronTargetArgs<T extends CronTarget> = T extends WorkflowReference<infer Params> ? Params : Record<string, unknown>;
+/**
+* The arguments a one-shot schedule target ({@link Scheduler.runAfter} /
+* {@link Scheduler.runAt}) accepts. Unlike {@link CronTargetArgs} it preserves a
+* {@link FunctionReference}'s inferred `args` (via {@link ArgsOf}) as well as a
+* {@link WorkflowReference}'s inferred `params`, so scheduling a plain function
+* keeps its today's arg checking while scheduling a workflow/agent infers its
+* `params`.
+*/
+type ScheduleTargetArgs<T extends CronTarget> = T extends WorkflowReference<infer Params> ? Params : T extends FunctionReference ? ArgsOf<T> : Record<string, unknown>;
 /** Narrow a {@link CronTarget} to a {@link WorkflowReference} by its runtime brand. */
 declare const isWorkflowReference: (target: unknown) => target is WorkflowReference;
 /**
@@ -93,7 +102,12 @@ interface ScheduleRecord {
   */
   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
@@ -113,6 +127,14 @@ interface ScheduleRecord {
   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<{
@@ -122,19 +144,39 @@ interface Scheduler {
   get: (id: string) => Promise<ScheduleRecord | null>;
   /** All pending scheduled jobs (the DO's `/list` view). */
   list: () => Promise<ScheduleRecord[]>;
-  runAfter: <F extends FunctionReference>(delayMs: number, function_: F, args: ArgsOf<F>, options?: RunOptions) => Promise<{
+  /**
+  * Schedule `target` to run once, `delayMs` from now. `target` is a function
+  * {@link FunctionReference} (dispatched as a one-shot) or a durable
+  * {@link WorkflowReference} — the generated `workflows.&lt;name>` /
+  * `agents.&lt;name>` ref — which starts a fresh instance on fire (args become
+  * its `params`). {@link ScheduleTargetArgs} infers the accepted args from
+  * whichever target was passed.
+  */
+  runAfter: <T extends CronTarget>(delayMs: number, target: T, args: ScheduleTargetArgs<T>, options?: RunOptions) => Promise<{
     id: string;
     scheduledFor: number;
   }>;
-  runAt: <F extends FunctionReference>(date: Date | number, function_: F, args: ArgsOf<F>, options?: RunOptions) => Promise<{
+  /** Like {@link Scheduler.runAfter} but fires at an absolute `date`/timestamp. */
+  runAt: <T extends CronTarget>(date: Date | number, target: T, args: ScheduleTargetArgs<T>, options?: RunOptions) => Promise<{
     id: string;
     scheduledFor: number;
   }>;
 }
+/**
+* Cloudflare Durable Object data-residency jurisdiction. Widening union —
+* Cloudflare adds values over time.
+* @see https://developers.cloudflare.com/durable-objects/reference/data-location/
+*/
+type DurableObjectJurisdiction = "eu" | "fedramp" | "us";
 /** Subset of `DurableObjectNamespace` the package consumes. */
 interface DurableObjectNamespaceLike {
   get: (id: DurableObjectIdLike) => DurableObjectStubLike;
   idFromName: (name: string) => DurableObjectIdLike;
+  /**
+  * Derive a jurisdiction-restricted subnamespace. Optional because older
+  * workers-types releases (and test doubles) may not expose it.
+  */
+  jurisdiction?: (jurisdiction: DurableObjectJurisdiction) => DurableObjectNamespaceLike;
 }
 interface DurableObjectIdLike {
   toString: () => string;
@@ -145,6 +187,13 @@ interface DurableObjectStubLike {
 interface LunoraSchedulerOptions {
   /** Optional named instance — useful for tenant isolation. Default `default`. */
   instanceName?: string;
+  /**
+  * Pin the SchedulerDO (durable timers + cron state) to a Cloudflare
+  * data-residency jurisdiction. Pass the same value as the worker's
+  * `jurisdiction` so scheduled state co-resides with app data. Omit for the
+  * un-pinned global namespace.
+  */
+  jurisdiction?: DurableObjectJurisdiction;
   /** Binding to the `SchedulerDO` durable object namespace. */
   namespace: DurableObjectNamespaceLike;
   /**
@@ -599,6 +648,13 @@ declare class SchedulerDO {
   * compatibility shim, not the hot path.
   */
   private static releaseFirstSlot;
+  /**
+  * Normalize the mutually-exclusive dispatch target off an untrusted body: a
+  * one-shot function path (`functionPath`) or a durable workflow/agent
+  * instance (`workflow`, a `WORKFLOW_*`/`AGENT_*` binding). Returns `undefined`
+  * when neither is present so the caller can reject the schedule.
+  */
+  private static resolveScheduleTarget;
   protected readonly state: SchedulerDOState;
   protected readonly env: SchedulerEnv;
   constructor(state: SchedulerDOState, env: SchedulerEnv);
@@ -630,15 +686,17 @@ declare class SchedulerDO {
   *
   * 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.
+  * thrown storage op re-asserts the claim so 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.
+  * A throw reaching here always means the job was NOT dispatched:
+  * {@link drainRecord} swallows its own post-dispatch cleanup errors and
+  * returns instead of throwing once a kick succeeds, so every escaping throw
+  * comes from the pre-dispatch or failed-dispatch paths. We therefore always
+  * re-assert the time-index claim so a later alarm re-attempts it
+  * (at-least-once): the claim delete may have removed it and
+  * recordRetry()/requeuePooled() may not have re-armed it before throwing, and
+  * re-inserting the same key is idempotent, so a surviving claim is simply
+  * rewritten to its prior value.
   */
   private drainRecordGuarded;
   /**
@@ -648,16 +706,18 @@ declare class SchedulerDO {
   * 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.
+  * {@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). 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.
+  * 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;
   /**
@@ -665,6 +725,14 @@ declare class SchedulerDO {
   * 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;
   /**
@@ -782,4 +850,4 @@ declare const isValidCronExpression: (schedule: string) => boolean;
 * job (`cron job "send digest"`) vs. the bare trigger.
 */
 declare const assertValidCronExpression: (schedule: string, context?: string) => void;
-export { type ArgsOf, CRON_SCHEDULE_KINDS, type CronJob, type CronJobsBuilder, type CronScheduleKind, type CronTarget, type CronTriggerOptions, type CronTriggerSnippet, type DailySchedule, type DurableObjectIdLike, type DurableObjectNamespaceLike, type DurableObjectStubLike, type EnqueueOptions, type FunctionReference, type HttpDispatcherOptions, type IntervalSchedule, type LunoraSchedulerOptions, type MessageBatchLike, type MonthlySchedule, type QueueConsumerOptions, type QueueDispatch, type QueueEnqueueOptions, type QueueJob, type QueueLike, type QueueMessageLike, type QueueSendOptionsLike, type QueueSendRequestLike, type QueueWorkpool, type QueueWorkpoolOptions, type RetryPolicy, type RunOptions, type ScheduleRecord, type Scheduler, SchedulerDO, type SchedulerDOState, type SchedulerEnv, type SchedulerPoolStatus, type SchedulerStatus, type WeeklySchedule, type WorkflowReference, type Workpool, type WorkpoolOptions, assertValidCronExpression, compileCronSchedule, createCronTrigger, createQueueConsumer, createQueueWorkpool, createScheduler, createWorkpool, cronJobs, httpDispatcher, isValidCronExpression, isWorkflowReference };
+export { type ArgsOf, CRON_SCHEDULE_KINDS, type CronJob, type CronJobsBuilder, type CronScheduleKind, type CronTarget, type CronTriggerOptions, type CronTriggerSnippet, type DailySchedule, type DurableObjectIdLike, type DurableObjectJurisdiction, type DurableObjectNamespaceLike, type DurableObjectStubLike, type EnqueueOptions, type FunctionReference, type 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 };

package/dist/index.mjs

@@ -1,8 +1,8 @@
-export { default as createScheduler } from './packem_shared/createScheduler-KCso4_at.mjs';
-export { default as createWorkpool } from './packem_shared/createWorkpool-D5cWPQmH.mjs';
-export { createCronTrigger } from './packem_shared/createCronTrigger-Cq9IBcWQ.mjs';
-export { CRON_SCHEDULE_KINDS, compileCronSchedule, cronJobs } from './packem_shared/compileCronSchedule-BaLlXJiN.mjs';
-export { createQueueConsumer, createQueueWorkpool, httpDispatcher } from './packem_shared/createQueueConsumer-DWahNPfz.mjs';
-export { SchedulerDO } from './packem_shared/SchedulerDO-BNzXNnS4.mjs';
+export { default as createScheduler } from './packem_shared/createScheduler-Df9JUjQb.mjs';
+export { default as createWorkpool } from './packem_shared/createWorkpool-Ce0kNM2p.mjs';
+export { createCronTrigger } from './packem_shared/createCronTrigger-Dh4VLxD9.mjs';
+export { CRON_SCHEDULE_KINDS, compileCronSchedule, cronJobs } from './packem_shared/CRON_SCHEDULE_KINDS-C2FflEnq.mjs';
+export { createQueueConsumer, createQueueWorkpool, httpDispatcher } from './packem_shared/createQueueConsumer-Cy-Mp-El.mjs';
+export { SchedulerDO } from './packem_shared/SchedulerDO-DeJHI379.mjs';
 export { isWorkflowReference } from './packem_shared/isWorkflowReference-C9mQkMXt.mjs';
-export { assertValidCronExpression, isValidCronExpression } from './packem_shared/assertValidCronExpression-BLfrDgmK.mjs';
+export { assertValidCronExpression, isValidCronExpression } from './packem_shared/assertValidCronExpression-B9m75qU0.mjs';

package/dist/packem_shared/{compileCronSchedule-BaLlXJiN.mjs → CRON_SCHEDULE_KINDS-C2FflEnq.mjs}

@@ -1,5 +1,6 @@
+import { LunoraError } from '@lunora/errors';
 import { isWorkflowReference } from './isWorkflowReference-C9mQkMXt.mjs';
-import { assertValidCronExpression } from './assertValidCronExpression-BLfrDgmK.mjs';
+import { assertValidCronExpression } from './assertValidCronExpression-B9m75qU0.mjs';
 
 const WEEKDAY_INDEX = {
   friday: 5,
@@ -12,24 +13,37 @@ const WEEKDAY_INDEX = {
 };
 const field = (value, label, min, max) => {
   if (!Number.isInteger(value) || value < min || value > max) {
-    throw new Error(`@lunora/scheduler: cronJobs ${label} must be an integer in [${min.toFixed(0)}, ${max.toFixed(0)}], got ${String(value)}`);
+    throw new LunoraError(
+      "INTERNAL",
+      `@lunora/scheduler: cronJobs ${label} must be an integer in [${min.toFixed(0)}, ${max.toFixed(0)}], got ${String(value)}`
+    );
   }
   return value.toFixed(0);
 };
+const stepField = (value, label, period) => {
+  const rendered = field(value, label, 1, period - 1);
+  if (period % value !== 0) {
+    throw new LunoraError(
+      "INTERNAL",
+      `@lunora/scheduler: ${label} must evenly divide ${period.toFixed(0)} for a fixed "every ${value.toFixed(0)}" interval — cron "*/${value.toFixed(0)}" means "at values divisible by ${value.toFixed(0)}", which wraps unevenly; pick a divisor of ${period.toFixed(0)}`
+    );
+  }
+  return rendered;
+};
 const compileInterval = (schedule) => {
   const units = ["seconds", "minutes", "hours"].filter((unit2) => schedule[unit2] !== void 0);
   if (units.length !== 1) {
-    throw new Error(`@lunora/scheduler: interval schedule must specify exactly one of { seconds, minutes, hours }`);
+    throw new LunoraError("INTERNAL", `@lunora/scheduler: interval schedule must specify exactly one of { seconds, minutes, hours }`);
   }
   const unit = units[0];
   const value = schedule[unit];
   if (unit === "seconds") {
-    return `*/${field(value, "interval.seconds", 1, 59)} * * * * *`;
+    return `*/${stepField(value, "interval.seconds", 60)} * * * * *`;
   }
   if (unit === "minutes") {
-    return `*/${field(value, "interval.minutes", 1, 59)} * * * *`;
+    return `*/${stepField(value, "interval.minutes", 60)} * * * *`;
   }
-  return `0 */${field(value, "interval.hours", 1, 23)} * * *`;
+  return `0 */${stepField(value, "interval.hours", 24)} * * *`;
 };
 const compileDaily = (schedule) => {
   const minute = field(schedule.minuteUTC, "daily.minuteUTC", 0, 59);
@@ -39,7 +53,7 @@ const compileDaily = (schedule) => {
 const compileWeekly = (schedule) => {
   const index = WEEKDAY_INDEX[schedule.dayOfWeek];
   if (index === void 0) {
-    throw new Error(`@lunora/scheduler: weekly schedule has invalid dayOfWeek "${schedule.dayOfWeek}"`);
+    throw new LunoraError("INTERNAL", `@lunora/scheduler: weekly schedule has invalid dayOfWeek "${schedule.dayOfWeek}"`);
   }
   const minute = field(schedule.minuteUTC, "weekly.minuteUTC", 0, 59);
   const hour = field(schedule.hourUTC, "weekly.hourUTC", 0, 23);
@@ -67,7 +81,7 @@ const compileCronSchedule = (kind, schedule) => {
       return compileWeekly(schedule);
     }
     default: {
-      throw new Error(`@lunora/scheduler: unknown cron schedule kind "${String(kind)}"`);
+      throw new LunoraError("INTERNAL", `@lunora/scheduler: unknown cron schedule kind "${String(kind)}"`);
     }
   }
 };
@@ -76,10 +90,10 @@ const cronJobs = () => {
   const seen = /* @__PURE__ */ new Set();
   const register = (name, cron, target, args) => {
     if (typeof name !== "string" || name.trim() === "") {
-      throw new Error(`@lunora/scheduler: cron job name must be a non-empty string`);
+      throw new LunoraError("INTERNAL", `@lunora/scheduler: cron job name must be a non-empty string`);
     }
     if (seen.has(name)) {
-      throw new Error(`@lunora/scheduler: duplicate cron job name "${name}" — names must be unique within one cronJobs()`);
+      throw new LunoraError("INTERNAL", `@lunora/scheduler: duplicate cron job name "${name}" — names must be unique within one cronJobs()`);
     }
     if (isWorkflowReference(target)) {
       assertValidCronExpression(cron, `cron expression for job "${name}"`);
@@ -88,7 +102,10 @@ const cronJobs = () => {
       return;
     }
     if (!target || typeof target.__lunoraRef !== "string") {
-      throw new Error(`@lunora/scheduler: cron job "${name}" requires a function reference (e.g. internal.email.digest) or a workflow reference`);
+      throw new LunoraError(
+        "INTERNAL",
+        `@lunora/scheduler: cron job "${name}" requires a function reference (e.g. internal.email.digest) or a workflow reference`
+      );
     }
     assertValidCronExpression(cron, `cron expression for job "${name}"`);
     seen.add(name);