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

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,11 +144,20 @@ 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;
   }>;
@@ -617,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);
@@ -648,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;
   /**
@@ -666,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;
   /**
@@ -683,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;
   /**

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,11 +144,20 @@ 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;
   }>;
@@ -617,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);
@@ -648,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;
   /**
@@ -666,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;
   /**
@@ -683,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;
   /**

package/dist/index.mjs

@@ -1,8 +1,8 @@
-export { default as createScheduler } from './packem_shared/createScheduler-CcD09oIm.mjs';
-export { default as createWorkpool } from './packem_shared/createWorkpool-C28trhTA.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-BMVeCHOu.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-DVeJrNbs.mjs';
+export { SchedulerDO } from './packem_shared/SchedulerDO-DeJHI379.mjs';
 export { isWorkflowReference } from './packem_shared/isWorkflowReference-C9mQkMXt.mjs';
 export { assertValidCronExpression, isValidCronExpression } from './packem_shared/assertValidCronExpression-B9m75qU0.mjs';

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

@@ -20,6 +20,16 @@ const field = (value, label, min, max) => {
   }
   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) {
@@ -28,12 +38,12 @@ const compileInterval = (schedule) => {
   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);

package/dist/packem_shared/{SchedulerDO-DVeJrNbs.mjs → SchedulerDO-DeJHI379.mjs}

@@ -7,7 +7,7 @@ const POOL_PREFIX = "pool:";
 const MAX_RETRY_ATTEMPTS = 5;
 const RETRY_BASE_DELAY_MS = 3e4;
 const POOL_BACKPRESSURE_DELAY_MS = 1e3;
-const MAX_SCHEDULED_FOR_MS = 864e13;
+const MAX_SCHEDULED_FOR_MS = 999999999999999;
 const TIME_PAD = 15;
 const padTime = (n) => String(n).padStart(TIME_PAD, "0");
 const generateId = () => {
@@ -102,6 +102,20 @@ class SchedulerDO {
     const next = pool.inFlightIds.slice(0, Math.max(0, pool.inFlightIds.length - 1));
     return { ...pool, inFlight: next.length, inFlightIds: next };
   }
+  /**
+   * 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.
+   */
+  static resolveScheduleTarget(body) {
+    const functionPath = typeof body?.functionPath === "string" && body.functionPath.length > 0 ? body.functionPath : void 0;
+    const workflow = typeof body?.workflow === "string" && body.workflow.length > 0 ? body.workflow : void 0;
+    if (functionPath === void 0 && workflow === void 0) {
+      return void 0;
+    }
+    return { functionPath, workflow };
+  }
   state;
   env;
   constructor(state, env) {
@@ -162,13 +176,14 @@ class SchedulerDO {
         const record = await this.state.storage.get(`${HEADER_PREFIX}${recordId}`);
         if (record) {
           due.push(record);
+        } else {
+          await this.state.storage.delete(indexKey);
         }
       }
     }
-    const pools = /* @__PURE__ */ new Map();
     try {
       for (const record of due) {
-        await this.drainRecordGuarded(record, pools);
+        await this.drainRecordGuarded(record);
       }
     } finally {
       await this.rescheduleAlarm();
@@ -210,7 +225,12 @@ class SchedulerDO {
       // so the pool's concurrency slot is released — see handleComplete().
       pool: record.pool,
       scheduledFor: record.scheduledFor,
-      shardKey: record.shardKey
+      shardKey: record.shardKey,
+      // Present instead of `functionPath` for a workflow/agent target; the
+      // runtime starts a fresh instance of this binding. `undefined` when
+      // absent, so JSON.stringify drops it and the payload is unchanged for
+      // ordinary function dispatches.
+      workflow: record.workflow
     });
     try {
       const headers = { "content-type": "application/json" };
@@ -237,27 +257,26 @@ 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.
    */
-  async drainRecordGuarded(record, pools) {
-    let dispatched = false;
+  async drainRecordGuarded(record) {
     try {
       await this.state.storage.delete(SchedulerDO.indexKey(record.scheduledFor, record.id));
-      dispatched = await this.drainRecord(record, pools);
+      await this.drainRecord(record);
     } catch {
-      if (!dispatched) {
-        try {
-          await this.state.storage.put(SchedulerDO.indexKey(record.scheduledFor, record.id), record.id);
-        } catch {
-        }
+      try {
+        await this.state.storage.put(SchedulerDO.indexKey(record.scheduledFor, record.id), record.id);
+      } catch {
       }
     }
   }
@@ -268,30 +287,29 @@ 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).
    */
-  async drainRecord(record, pools) {
-    const reserved = await this.reservePoolSlot(record, pools);
+  async drainRecord(record) {
+    const reserved = await this.reservePoolSlot(record);
     if (!reserved) {
       return false;
     }
     const ok = await this.dispatch(record);
     if (!ok && record.pool !== void 0) {
-      const pool = pools.get(record.pool);
-      if (pool !== void 0) {
-        const released = SchedulerDO.releaseSlot(pool, record.id);
-        pools.set(record.pool, released);
-        await this.savePool(record.pool, released);
-      }
+      const pool = await this.loadPool(record.pool);
+      const released = SchedulerDO.releaseSlot(pool, record.id);
+      await this.savePool(record.pool, released);
     }
     if (ok) {
       try {
@@ -308,13 +326,20 @@ 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).
    */
-  async reservePoolSlot(record, pools) {
+  async reservePoolSlot(record) {
     if (record.pool === void 0) {
       return true;
     }
-    const pool = pools.get(record.pool) ?? await this.loadPool(record.pool);
-    pools.set(record.pool, pool);
+    const pool = await this.loadPool(record.pool);
     if (pool.inFlight >= pool.maxConcurrency) {
       await this.requeuePooled(record);
       return false;
@@ -402,7 +427,9 @@ class SchedulerDO {
     if (attempts > maxAttempts) {
       await this.state.storage.put(`${DEAD_PREFIX}${record.id}`, { ...record, attempts });
       await this.state.storage.delete([`${RETRY_PREFIX}${record.id}`, `${HEADER_PREFIX}${record.id}`]);
-      console.warn(`@lunora/scheduler: job "${record.id}" (${record.functionPath}) parked in dead-letter after ${String(attempts)} attempts`);
+      console.warn(
+        `@lunora/scheduler: job "${record.id}" (${record.functionPath ?? record.workflow ?? "unknown"}) parked in dead-letter after ${String(attempts)} attempts`
+      );
       return;
     }
     const rawDelay = backoff === "linear" ? baseMs * attempts : baseMs * 2 ** (attempts - 1);
@@ -518,11 +545,13 @@ class SchedulerDO {
   }
   async handleSchedule(request) {
     const body = await request.json().catch(() => void 0);
-    if (!body || typeof body.functionPath !== "string") {
-      return SchedulerDO.error(400, "INVALID_INPUT", "functionPath is required");
+    const target = SchedulerDO.resolveScheduleTarget(body);
+    if (!body || target === void 0) {
+      return SchedulerDO.error(400, "INVALID_INPUT", "functionPath or workflow is required");
     }
+    const { functionPath, workflow } = target;
     if (typeof body.scheduledFor !== "number" || !Number.isInteger(body.scheduledFor) || body.scheduledFor <= 0 || body.scheduledFor > MAX_SCHEDULED_FOR_MS) {
-      return SchedulerDO.error(400, "INVALID_INPUT", "scheduledFor must be a positive integer epoch-millisecond number no greater than 8640000000000000");
+      return SchedulerDO.error(400, "INVALID_INPUT", "scheduledFor must be a positive integer epoch-millisecond number no greater than 999999999999999");
     }
     if (typeof this.env.LUNORA_ORIGIN_URL !== "string" || this.env.LUNORA_ORIGIN_URL.length === 0) {
       return SchedulerDO.error(500, "ORIGIN_NOT_CONFIGURED", "LUNORA_ORIGIN_URL env binding must be set on the SchedulerDO");
@@ -537,13 +566,14 @@ class SchedulerDO {
       // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- parsed wire data can omit args
       args: body.args ?? {},
       enqueuedAt: Date.now(),
-      functionPath: body.functionPath,
       id,
+      ...functionPath === void 0 ? {} : { functionPath },
       ...instanceName === void 0 ? {} : { instanceName },
       ...pool === void 0 ? {} : { pool },
       ...retry === void 0 ? {} : { retry },
       scheduledFor: body.scheduledFor,
-      shardKey: body.shardKey
+      shardKey: body.shardKey,
+      ...workflow === void 0 ? {} : { workflow }
     };
     if (pool !== void 0) {
       const current = await this.loadPool(pool, body.maxConcurrency);

package/dist/packem_shared/createScheduler-Df9JUjQb.mjs

@@ -0,0 +1,52 @@
+import { LunoraError } from '@lunora/errors';
+import { c as callDO, g as getDO } from './do-client-CMJtLoHO.mjs';
+import { isWorkflowReference } from './isWorkflowReference-C9mQkMXt.mjs';
+
+const createScheduler = (options) => {
+  if (!options.namespace) {
+    throw new LunoraError("INTERNAL", "@lunora/scheduler: `namespace` (SchedulerDO binding) is required");
+  }
+  if (!options.originUrl) {
+    throw new LunoraError("INTERNAL", "@lunora/scheduler: `originUrl` is required so the DO can dispatch back to the Worker");
+  }
+  const runAt = async (date, target, args, options_ = {}) => {
+    const scheduledFor = date instanceof Date ? date.getTime() : date;
+    const base = {
+      args,
+      originUrl: options.originUrl,
+      pool: options_.pool,
+      retry: options_.retry,
+      scheduledFor,
+      shardKey: options_.shardKey
+    };
+    if (isWorkflowReference(target)) {
+      if (typeof target.binding !== "string" || target.binding.length === 0) {
+        throw new LunoraError(
+          "INTERNAL",
+          "@lunora/scheduler: workflow/agent schedule target is missing its `binding` — pass the generated `workflows.<name>` / `agents.<name>` reference"
+        );
+      }
+      return callDO(options, "/schedule", { ...base, workflow: target.binding });
+    }
+    const functionPath = typeof target === "string" ? target : target.__lunoraRef;
+    return callDO(options, "/schedule", { ...base, functionPath });
+  };
+  const runAfter = async (delayMs, target, args, options_ = {}) => {
+    if (!Number.isFinite(delayMs) || delayMs < 0) {
+      throw new LunoraError("INTERNAL", "@lunora/scheduler: `delayMs` must be a non-negative finite number");
+    }
+    return runAt(Date.now() + delayMs, target, args, options_);
+  };
+  const cancel = async (id) => callDO(options, "/cancel", { id });
+  const list = async () => {
+    const body = await getDO(options, "/list");
+    return Array.isArray(body.records) ? body.records : [];
+  };
+  const get = async (id) => {
+    const body = await getDO(options, `/get?id=${encodeURIComponent(id)}`);
+    return body.record ?? null;
+  };
+  return { cancel, get, list, runAfter, runAt };
+};
+
+export { createScheduler as default };

package/dist/packem_shared/{createWorkpool-C28trhTA.mjs → createWorkpool-Ce0kNM2p.mjs}

@@ -1,32 +1,6 @@
 import { LunoraError } from '@lunora/errors';
-import { a as applyJurisdiction } from './jurisdiction-CR2zC3Et.mjs';
+import { g as getDO, c as callDO } from './do-client-CMJtLoHO.mjs';
 
-const workpoolStub = (options) => {
-  const namespace = applyJurisdiction(options.namespace, options.jurisdiction);
-  return namespace.get(namespace.idFromName(options.instanceName ?? "default"));
-};
-const callDO = async (options, path, body) => {
-  const stub = workpoolStub(options);
-  const response = await stub.fetch(`https://scheduler.internal${path}`, {
-    body: JSON.stringify(body),
-    headers: { "content-type": "application/json" },
-    method: "POST"
-  });
-  if (!response.ok) {
-    const text = await response.text();
-    throw new LunoraError("INTERNAL", `@lunora/scheduler: SchedulerDO ${path} failed (${String(response.status)}): ${text}`);
-  }
-  return await response.json();
-};
-const getDO = async (options, path) => {
-  const stub = workpoolStub(options);
-  const response = await stub.fetch(`https://scheduler.internal${path}`, { method: "GET" });
-  if (!response.ok) {
-    const text = await response.text();
-    throw new LunoraError("INTERNAL", `@lunora/scheduler: SchedulerDO ${path} failed (${String(response.status)}): ${text}`);
-  }
-  return await response.json();
-};
 const createWorkpool = (options) => {
   if (!options.namespace) {
     throw new LunoraError("INTERNAL", "@lunora/scheduler: `namespace` (SchedulerDO binding) is required");

package/dist/packem_shared/do-client-CMJtLoHO.mjs

@@ -0,0 +1,42 @@
+import { LunoraError } from '@lunora/errors';
+
+const applyJurisdiction = (namespace, jurisdiction) => {
+  if (jurisdiction === void 0) {
+    return namespace;
+  }
+  if (typeof namespace.jurisdiction !== "function") {
+    throw new TypeError(
+      `@lunora/scheduler: Durable Object namespace does not support jurisdiction("${jurisdiction}") — update @cloudflare/workers-types or remove the jurisdiction option`
+    );
+  }
+  return namespace.jurisdiction(jurisdiction);
+};
+
+const schedulerStub = (options) => {
+  const namespace = applyJurisdiction(options.namespace, options.jurisdiction);
+  return namespace.get(namespace.idFromName(options.instanceName ?? "default"));
+};
+const callDO = async (options, path, body) => {
+  const stub = schedulerStub(options);
+  const response = await stub.fetch(`https://scheduler.internal${path}`, {
+    body: JSON.stringify(body),
+    headers: { "content-type": "application/json" },
+    method: "POST"
+  });
+  if (!response.ok) {
+    const text = await response.text();
+    throw new LunoraError("INTERNAL", `@lunora/scheduler: SchedulerDO ${path} failed (${String(response.status)}): ${text}`);
+  }
+  return await response.json();
+};
+const getDO = async (options, path) => {
+  const stub = schedulerStub(options);
+  const response = await stub.fetch(`https://scheduler.internal${path}`, { method: "GET" });
+  if (!response.ok) {
+    const text = await response.text();
+    throw new LunoraError("INTERNAL", `@lunora/scheduler: SchedulerDO ${path} failed (${String(response.status)}): ${text}`);
+  }
+  return await response.json();
+};
+
+export { callDO as c, getDO as g };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/scheduler",
-  "version": "1.0.0-alpha.7",
+  "version": "1.0.0-alpha.9",
   "description": "Scheduling for Lunora: runAfter / runAt and Cron Triggers via SchedulerDO",
   "keywords": [
     "cloudflare",
@@ -46,7 +46,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/errors": "1.0.0-alpha.3",
+    "@lunora/errors": "1.0.0-alpha.4",
     "cron-parser": "5.6.1"
   },
   "engines": {

package/dist/packem_shared/createScheduler-CcD09oIm.mjs

@@ -1,70 +0,0 @@
-import { LunoraError } from '@lunora/errors';
-import { a as applyJurisdiction } from './jurisdiction-CR2zC3Et.mjs';
-
-const schedulerStub = (options) => {
-  const namespace = applyJurisdiction(options.namespace, options.jurisdiction);
-  return namespace.get(namespace.idFromName(options.instanceName ?? "default"));
-};
-const callDO = async (options, path, body) => {
-  const stub = schedulerStub(options);
-  const response = await stub.fetch(`https://scheduler.internal${path}`, {
-    body: JSON.stringify(body),
-    headers: { "content-type": "application/json" },
-    method: "POST"
-  });
-  if (!response.ok) {
-    const text = await response.text();
-    throw new LunoraError("INTERNAL", `@lunora/scheduler: SchedulerDO ${path} failed (${String(response.status)}): ${text}`);
-  }
-  return await response.json();
-};
-const getDO = async (options, path) => {
-  const stub = schedulerStub(options);
-  const response = await stub.fetch(`https://scheduler.internal${path}`, { method: "GET" });
-  if (!response.ok) {
-    const text = await response.text();
-    throw new LunoraError("INTERNAL", `@lunora/scheduler: SchedulerDO ${path} failed (${String(response.status)}): ${text}`);
-  }
-  return await response.json();
-};
-const createScheduler = (options) => {
-  if (!options.namespace) {
-    throw new LunoraError("INTERNAL", "@lunora/scheduler: `namespace` (SchedulerDO binding) is required");
-  }
-  if (!options.originUrl) {
-    throw new LunoraError("INTERNAL", "@lunora/scheduler: `originUrl` is required so the DO can dispatch back to the Worker");
-  }
-  const runAt = async (date, function_, args, options_ = {}) => {
-    const scheduledFor = date instanceof Date ? date.getTime() : date;
-    return callDO(options, "/schedule", {
-      args,
-      functionPath: function_.__lunoraRef,
-      originUrl: options.originUrl,
-      // Optional workpool / retry-policy passthrough. Absent for ordinary
-      // `runAfter`/`runAt` calls, which keeps the wire payload (and the
-      // DO's behaviour) identical to before this feature.
-      pool: options_.pool,
-      retry: options_.retry,
-      scheduledFor,
-      shardKey: options_.shardKey
-    });
-  };
-  const runAfter = async (delayMs, function_, args, options_ = {}) => {
-    if (!Number.isFinite(delayMs) || delayMs < 0) {
-      throw new LunoraError("INTERNAL", "@lunora/scheduler: `delayMs` must be a non-negative finite number");
-    }
-    return runAt(Date.now() + delayMs, function_, args, options_);
-  };
-  const cancel = async (id) => callDO(options, "/cancel", { id });
-  const list = async () => {
-    const body = await getDO(options, "/list");
-    return Array.isArray(body.records) ? body.records : [];
-  };
-  const get = async (id) => {
-    const body = await getDO(options, `/get?id=${encodeURIComponent(id)}`);
-    return body.record ?? null;
-  };
-  return { cancel, get, list, runAfter, runAt };
-};
-
-export { createScheduler as default };

package/dist/packem_shared/jurisdiction-CR2zC3Et.mjs

@@ -1,13 +0,0 @@
-const applyJurisdiction = (namespace, jurisdiction) => {
-  if (jurisdiction === void 0) {
-    return namespace;
-  }
-  if (typeof namespace.jurisdiction !== "function") {
-    throw new TypeError(
-      `@lunora/scheduler: Durable Object namespace does not support jurisdiction("${jurisdiction}") — update @cloudflare/workers-types or remove the jurisdiction option`
-    );
-  }
-  return namespace.jurisdiction(jurisdiction);
-};
-
-export { applyJurisdiction as a };