@adonis-agora/durable 0.1.0

package/dist/src/protocol.js

@@ -0,0 +1,47 @@
+import { createStepLogger } from './step-logger.js';
+/** Canonical step id — the stable identity of a step within a run, used for dedupe and
+ *  correlation. The format is part of the cross-language wire contract (Python builds the same). */
+export function stepId(runId, seq) {
+    return `${runId}:${seq}`;
+}
+/** Deterministic signal token a breakpoint suspends on — derived from its logical position. Shared
+ *  so `ctx.breakpoint` (which records it) and `engine.continue` (which signals it) agree. */
+export const breakpointToken = (runId, seq) => `bp:${runId}:${seq}`;
+/**
+ * Run `handler` for `task` and produce the wire-format {@link StepResult}. Pure (no transport,
+ * no I/O beyond the handler), so every transport — and any language port — can share the exact
+ * same completed / failed / no-handler contract instead of re-deriving it.
+ */
+export async function runStepHandler(task, handler) {
+    // Stamp the worker's pickup time so the engine can report queue-wait (startedAt − enqueuedAt).
+    // This is the one place every transport funnels through, so timing comes for free everywhere.
+    const base = { runId: task.runId, seq: task.seq, stepId: task.stepId, startedAt: Date.now() };
+    if (!handler) {
+        return {
+            ...base,
+            status: 'failed',
+            error: { message: `no handler for ${task.name}`, retryable: false },
+        };
+    }
+    const events = [];
+    const withEvents = (result) => events.length > 0 ? { ...result, events } : result;
+    try {
+        const output = await handler(task.input, createStepLogger(events, Date.now));
+        return withEvents({ ...base, status: 'completed', output });
+    }
+    catch (err) {
+        // Carry `code`/`retryable` off the thrown error if present, so the engine's durable retry can
+        // honour a worker's "don't retry this" verdict (e.g. a declined card).
+        const e = err;
+        return withEvents({
+            ...base,
+            status: 'failed',
+            error: {
+                message: err instanceof Error ? err.message : String(err),
+                ...(typeof e?.code === 'string' ? { code: e.code } : {}),
+                ...(typeof e?.retryable === 'boolean' ? { retryable: e.retryable } : {}),
+            },
+        });
+    }
+}
+//# sourceMappingURL=protocol.js.map

package/dist/src/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/protocol.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpD;oGACoG;AACpG,MAAM,UAAU,MAAM,CAAC,KAAa,EAAE,GAAW;IAC/C,OAAO,GAAG,KAAK,IAAI,GAAG,EAAE,CAAC;AAC3B,CAAC;AAED;6FAC6F;AAC7F,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,KAAa,EAAE,GAAW,EAAU,EAAE,CAAC,MAAM,KAAK,IAAI,GAAG,EAAE,CAAC;AAM5F;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAgB,EAChB,OAAgC;IAEhC,+FAA+F;IAC/F,8FAA8F;IAC9F,MAAM,IAAI,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;IAC9F,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO;YACL,GAAG,IAAI;YACP,MAAM,EAAE,QAAQ;YAChB,KAAK,EAAE,EAAE,OAAO,EAAE,kBAAkB,IAAI,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE;SACpE,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAgB,EAAE,CAAC;IAC/B,MAAM,UAAU,GAAG,CAAC,MAAkB,EAAc,EAAE,CACpD,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;IACrD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAC7E,OAAO,UAAU,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC,CAAC;IAC9D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,8FAA8F;QAC9F,uEAAuE;QACvE,MAAM,CAAC,GAAG,GAA+D,CAAC;QAC1E,OAAO,UAAU,CAAC;YAChB,GAAG,IAAI;YACP,MAAM,EAAE,QAAQ;YAChB,KAAK,EAAE;gBACL,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;gBACzD,GAAG,CAAC,OAAO,CAAC,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACxD,GAAG,CAAC,OAAO,CAAC,EAAE,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACzE;SACF,CAAC,CAAC;IACL,CAAC;AACH,CAAC"}

package/dist/src/queue.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Flow control for remote steps. A queue caps how much work `ctx.call(step, input, { queue })`
+ * admits at once — a concurrency limit and/or a fixed-window rate limit. When a call can't be
+ * admitted it doesn't dispatch: the run re-suspends with a near-future wake time, and the timer
+ * poller re-tries admission later — so flow control is durable (survives crashes) without holding
+ * the run in memory.
+ *
+ * Accounting is per engine instance (the DBOS `workerConcurrency` tier): correct for the common
+ * single-orchestrator deployment. Global, cross-instance limits would need a durable counter in the
+ * store — a deliberate follow-up, not built here.
+ *
+ * Beyond raw caps, the controller can admit contended slots by PRIORITY and by per-KEY FAIRNESS
+ * (round-robin), so a single noisy key/tenant can't monopolize the concurrency budget. This is the
+ * DISPATCH/admission layer — it never touches workflow replay (engine positional logic). Default
+ * behaviour is unchanged FIFO when neither priority nor fairness is configured/passed.
+ *
+ * Design (vs Temporal/Inngest/DBOS): Temporal task queues are FIFO with separate priority levels;
+ * Inngest concurrency keys + throttle give per-key fairness; DBOS queues are FIFO with a
+ * `workerConcurrency` cap. We fold both knobs into the same in-process admission gate: an optional
+ * per-call `priority` (higher first) and an optional queue-level `fairness: 'key'` (round-robin by
+ * the per-call `key`). Because blocked calls re-suspend durably and retry independently (there is no
+ * resident FIFO list to reorder), the controller remembers the set of WAITERS that asked-and-were-
+ * blocked, and on a later retry only admits the one that is rightful-next under the policy.
+ */
+export interface QueueConfig {
+    /** Queue name, referenced by `ctx.call(step, input, { queue: name })`. */
+    name: string;
+    /** Max steps in flight at once for this queue (this instance). Omit for unlimited. */
+    concurrency?: number;
+    /** Fixed-window rate limit: at most `limit` admissions per `periodMs`. Omit for unlimited. */
+    rateLimit?: {
+        limit: number;
+        periodMs: number;
+    };
+    /** Delay (ms) before a concurrency-blocked call re-checks for a free slot. Default 1000. */
+    retryMs?: number;
+    /**
+     * Fairness policy for a contended concurrency slot. `'key'` round-robins across distinct per-call
+     * keys (the least-recently-served key wins the next slot), so one key can't monopolize the budget.
+     * Omit (or `'fifo'`) for plain first-come ordering. Priority always wins over fairness; fairness
+     * only breaks ties within the same priority.
+     */
+    fairness?: 'fifo' | 'key';
+    /**
+     * Arrival-order tiebreak among otherwise-equal waiters (same priority, same fairness rank).
+     * `'fifo'` (default) admits the earliest arrival; `'lifo'` admits the most recent (a stack).
+     * Orthogonal to `priority` and `fairness` — those still win first; this only breaks their ties.
+     */
+    order?: 'fifo' | 'lifo';
+}
+/**
+ * Per-call admission hints. All optional — omitting them keeps the legacy FIFO behaviour.
+ * - `priority`: higher is admitted first (default 0).
+ * - `key`: the fairness bucket (e.g. a tenant id) for `fairness: 'key'`.
+ * - `waiterId`: a stable id for THIS call across its retries (the engine passes the stepId), so the
+ *   controller can track it as one waiter instead of counting each retry as a new contender.
+ */
+export interface AdmissionItem {
+    priority?: number | undefined;
+    key?: string | undefined;
+    waiterId?: string | undefined;
+}
+/** Admission decision: either admitted, or blocked until `retryAt` (epoch ms). */
+export type Admission = {
+    ok: true;
+} | {
+    ok: false;
+    retryAt: number;
+};
+/** In-process admission controller for one {@link QueueConfig}. */
+export declare class QueueController {
+    readonly config: QueueConfig;
+    private readonly clock;
+    private inFlight;
+    private windowStart;
+    private windowCount;
+    /** Registered waiters by id (only used when priority/fairness ordering is in play). */
+    private readonly waiters;
+    /** Monotonic counter stamping each newly-seen waiter for a stable FIFO tiebreak. */
+    private waiterSeq;
+    /** Per-key "last served" order for round-robin fairness — higher = more recently served. */
+    private readonly keyServed;
+    private servedTick;
+    constructor(config: QueueConfig, clock: () => number);
+    /** Whether this controller does any priority/fairness/arrival ordering (else a plain FIFO gate). */
+    private get ordered();
+    /**
+     * Try to admit one unit of work. On `ok`, the caller has taken a concurrency slot and must call
+     * {@link release} when the step settles. On block, `retryAt` is when admission may next succeed.
+     *
+     * `item` carries optional priority/fairness hints; omitting it is the legacy FIFO path. When
+     * ordering is configured (or a priority is given), a blocked call REGISTERS as a waiter and is only
+     * admitted on a later retry once it is the rightful next under (priority desc, fairness, FIFO).
+     */
+    tryAdmit(item?: AdmissionItem): Admission;
+    /** Release a concurrency slot taken by a successful {@link tryAdmit}. */
+    release(): void;
+    /** Track (or refresh) a blocked call as a waiter; its FIFO seq is stamped only on first sight. */
+    private register;
+    /**
+     * Is the calling item the best candidate among all registered waiters? Ordering, best first:
+     *   1. higher `priority`;
+     *   2. fairness: with `fairness: 'key'`, the least-recently-served key wins (round-robin);
+     *   3. earliest registration (FIFO) — stable tiebreak.
+     * A bare item (no waiterId) is compared on its hints directly.
+     */
+    private isNext;
+    /** Strict "a should be admitted before b" comparison under the active policy. */
+    private better;
+    /** Last-served tick for a key (0 = never served, so an unseen key is admitted before a busy one). */
+    private servedOf;
+}
+//# sourceMappingURL=queue.d.ts.map

package/dist/src/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,WAAW;IAC1B,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8FAA8F;IAC9F,SAAS,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD,4FAA4F;IAC5F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAC1B;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAED,kFAAkF;AAClF,MAAM,MAAM,SAAS,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAUtE,mEAAmE;AACnE,qBAAa,eAAe;IAaxB,QAAQ,CAAC,MAAM,EAAE,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK;IAbxB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,WAAW,CAAK;IACxB,uFAAuF;IACvF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,oFAAoF;IACpF,OAAO,CAAC,SAAS,CAAK;IACtB,4FAA4F;IAC5F,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IACvD,OAAO,CAAC,UAAU,CAAK;gBAGZ,MAAM,EAAE,WAAW,EACX,KAAK,EAAE,MAAM,MAAM;IAGtC,oGAAoG;IACpG,OAAO,KAAK,OAAO,GAElB;IAED;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,SAAS;IA0CzC,yEAAyE;IACzE,OAAO,IAAI,IAAI;IAIf,kGAAkG;IAClG,OAAO,CAAC,QAAQ;IAchB;;;;;;OAMG;IACH,OAAO,CAAC,MAAM;IAWd,iFAAiF;IACjF,OAAO,CAAC,MAAM;IAUd,qGAAqG;IACrG,OAAO,CAAC,QAAQ;CAIjB"}

package/dist/src/queue.js

@@ -0,0 +1,128 @@
+/** In-process admission controller for one {@link QueueConfig}. */
+export class QueueController {
+    config;
+    clock;
+    inFlight = 0;
+    windowStart = 0;
+    windowCount = 0;
+    /** Registered waiters by id (only used when priority/fairness ordering is in play). */
+    waiters = new Map();
+    /** Monotonic counter stamping each newly-seen waiter for a stable FIFO tiebreak. */
+    waiterSeq = 0;
+    /** Per-key "last served" order for round-robin fairness — higher = more recently served. */
+    keyServed = new Map();
+    servedTick = 0;
+    constructor(config, clock) {
+        this.config = config;
+        this.clock = clock;
+    }
+    /** Whether this controller does any priority/fairness/arrival ordering (else a plain FIFO gate). */
+    get ordered() {
+        return this.config.fairness === 'key' || this.config.order === 'lifo';
+    }
+    /**
+     * Try to admit one unit of work. On `ok`, the caller has taken a concurrency slot and must call
+     * {@link release} when the step settles. On block, `retryAt` is when admission may next succeed.
+     *
+     * `item` carries optional priority/fairness hints; omitting it is the legacy FIFO path. When
+     * ordering is configured (or a priority is given), a blocked call REGISTERS as a waiter and is only
+     * admitted on a later retry once it is the rightful next under (priority desc, fairness, FIFO).
+     */
+    tryAdmit(item) {
+        const now = this.clock();
+        const rl = this.config.rateLimit;
+        // Rate limit is a hard global window — checked first and unaffected by priority/fairness.
+        if (rl) {
+            if (now - this.windowStart >= rl.periodMs) {
+                this.windowStart = now;
+                this.windowCount = 0;
+            }
+            if (this.windowCount >= rl.limit)
+                return { ok: false, retryAt: this.windowStart + rl.periodMs };
+        }
+        const usingOrder = this.ordered || item?.priority != null || item?.waiterId != null;
+        const waiterId = item?.waiterId;
+        // Concurrency gate.
+        const full = this.config.concurrency != null && this.inFlight >= this.config.concurrency;
+        if (full) {
+            // No slot at all → block (and register as a waiter so a later retry can be ordered).
+            if (usingOrder && waiterId != null)
+                this.register(waiterId, item);
+            return { ok: false, retryAt: now + (this.config.retryMs ?? 1000) };
+        }
+        // A slot is free. Without ordering, admit immediately (legacy FIFO). With ordering, only admit if
+        // THIS call is the rightful next among all registered waiters — otherwise keep it waiting so the
+        // freed slot can go to a higher-priority / under-served key on its retry.
+        if (usingOrder && this.waiters.size > 0) {
+            if (waiterId != null)
+                this.register(waiterId, item);
+            if (!this.isNext(waiterId, item)) {
+                return { ok: false, retryAt: now + (this.config.retryMs ?? 1000) };
+            }
+        }
+        // Admit: consume the slot, the rate-window tick, and clear this waiter.
+        if (rl)
+            this.windowCount += 1;
+        this.inFlight += 1;
+        if (waiterId != null)
+            this.waiters.delete(waiterId);
+        if (item?.key != null)
+            this.keyServed.set(item.key, ++this.servedTick);
+        return { ok: true };
+    }
+    /** Release a concurrency slot taken by a successful {@link tryAdmit}. */
+    release() {
+        if (this.inFlight > 0)
+            this.inFlight -= 1;
+    }
+    /** Track (or refresh) a blocked call as a waiter; its FIFO seq is stamped only on first sight. */
+    register(waiterId, item) {
+        const existing = this.waiters.get(waiterId);
+        if (existing) {
+            existing.priority = item?.priority ?? 0;
+            existing.key = item?.key;
+            return;
+        }
+        this.waiters.set(waiterId, {
+            priority: item?.priority ?? 0,
+            key: item?.key,
+            seq: this.waiterSeq++,
+        });
+    }
+    /**
+     * Is the calling item the best candidate among all registered waiters? Ordering, best first:
+     *   1. higher `priority`;
+     *   2. fairness: with `fairness: 'key'`, the least-recently-served key wins (round-robin);
+     *   3. earliest registration (FIFO) — stable tiebreak.
+     * A bare item (no waiterId) is compared on its hints directly.
+     */
+    isNext(waiterId, item) {
+        const self = (waiterId != null ? this.waiters.get(waiterId) : undefined) ??
+            { priority: item?.priority ?? 0, key: item?.key, seq: Number.POSITIVE_INFINITY };
+        let best = self;
+        for (const w of this.waiters.values()) {
+            if (this.better(w, best))
+                best = w;
+        }
+        return best === self;
+    }
+    /** Strict "a should be admitted before b" comparison under the active policy. */
+    better(a, b) {
+        if (a.priority !== b.priority)
+            return a.priority > b.priority;
+        if (this.config.fairness === 'key') {
+            const sa = this.servedOf(a.key);
+            const sb = this.servedOf(b.key);
+            if (sa !== sb)
+                return sa < sb; // least-recently-served key first
+        }
+        return this.config.order === 'lifo' ? a.seq > b.seq : a.seq < b.seq; // arrival tiebreak
+    }
+    /** Last-served tick for a key (0 = never served, so an unseen key is admitted before a busy one). */
+    servedOf(key) {
+        if (key == null)
+            return 0;
+        return this.keyServed.get(key) ?? 0;
+    }
+}
+//# sourceMappingURL=queue.js.map

package/dist/src/queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.js","sourceRoot":"","sources":["../../src/queue.ts"],"names":[],"mappings":"AAwEA,mEAAmE;AACnE,MAAM,OAAO,eAAe;IAaf;IACQ;IAbX,QAAQ,GAAG,CAAC,CAAC;IACb,WAAW,GAAG,CAAC,CAAC;IAChB,WAAW,GAAG,CAAC,CAAC;IACxB,uFAAuF;IACtE,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IACrD,oFAAoF;IAC5E,SAAS,GAAG,CAAC,CAAC;IACtB,4FAA4F;IAC3E,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC/C,UAAU,GAAG,CAAC,CAAC;IAEvB,YACW,MAAmB,EACX,KAAmB;QAD3B,WAAM,GAAN,MAAM,CAAa;QACX,UAAK,GAAL,KAAK,CAAc;IACnC,CAAC;IAEJ,oGAAoG;IACpG,IAAY,OAAO;QACjB,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,KAAK,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,KAAK,MAAM,CAAC;IACxE,CAAC;IAED;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAoB;QAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QACzB,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC;QACjC,0FAA0F;QAC1F,IAAI,EAAE,EAAE,CAAC;YACP,IAAI,GAAG,GAAG,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC;gBAC1C,IAAI,CAAC,WAAW,GAAG,GAAG,CAAC;gBACvB,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC;YACvB,CAAC;YACD,IAAI,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,KAAK;gBAC9B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,WAAW,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC;QAClE,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,IAAI,IAAI,EAAE,QAAQ,IAAI,IAAI,IAAI,IAAI,EAAE,QAAQ,IAAI,IAAI,CAAC;QACpF,MAAM,QAAQ,GAAG,IAAI,EAAE,QAAQ,CAAC;QAEhC,oBAAoB;QACpB,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,IAAI,IAAI,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC;QACzF,IAAI,IAAI,EAAE,CAAC;YACT,qFAAqF;YACrF,IAAI,UAAU,IAAI,QAAQ,IAAI,IAAI;gBAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YAClE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,EAAE,CAAC;QACrE,CAAC;QAED,kGAAkG;QAClG,iGAAiG;QACjG,0EAA0E;QAC1E,IAAI,UAAU,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;YACxC,IAAI,QAAQ,IAAI,IAAI;gBAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YACpD,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,CAAC;gBACjC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,EAAE,CAAC;YACrE,CAAC;QACH,CAAC;QAED,wEAAwE;QACxE,IAAI,EAAE;YAAE,IAAI,CAAC,WAAW,IAAI,CAAC,CAAC;QAC9B,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;QACnB,IAAI,QAAQ,IAAI,IAAI;YAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACpD,IAAI,IAAI,EAAE,GAAG,IAAI,IAAI;YAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;QACvE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACtB,CAAC;IAED,yEAAyE;IACzE,OAAO;QACL,IAAI,IAAI,CAAC,QAAQ,GAAG,CAAC;YAAE,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;IAC5C,CAAC;IAED,kGAAkG;IAC1F,QAAQ,CAAC,QAAgB,EAAE,IAAoB;QACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC5C,IAAI,QAAQ,EAAE,CAAC;YACb,QAAQ,CAAC,QAAQ,GAAG,IAAI,EAAE,QAAQ,IAAI,CAAC,CAAC;YACxC,QAAQ,CAAC,GAAG,GAAG,IAAI,EAAE,GAAG,CAAC;YACzB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE;YACzB,QAAQ,EAAE,IAAI,EAAE,QAAQ,IAAI,CAAC;YAC7B,GAAG,EAAE,IAAI,EAAE,GAAG;YACd,GAAG,EAAE,IAAI,CAAC,SAAS,EAAE;SACtB,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACK,MAAM,CAAC,QAA4B,EAAE,IAAoB;QAC/D,MAAM,IAAI,GACR,CAAC,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAC1D,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,iBAAiB,EAAa,CAAC;QAC/F,IAAI,IAAI,GAAG,IAAI,CAAC;QAChB,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;YACtC,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC;gBAAE,IAAI,GAAG,CAAC,CAAC;QACrC,CAAC;QACD,OAAO,IAAI,KAAK,IAAI,CAAC;IACvB,CAAC;IAED,iFAAiF;IACzE,MAAM,CAAC,CAAS,EAAE,CAAS;QACjC,IAAI,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ;YAAE,OAAO,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC;QAC9D,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,KAAK,KAAK,EAAE,CAAC;YACnC,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YAChC,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YAChC,IAAI,EAAE,KAAK,EAAE;gBAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,kCAAkC;QACnE,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,mBAAmB;IAC1F,CAAC;IAED,qGAAqG;IAC7F,QAAQ,CAAC,GAAY;QAC3B,IAAI,GAAG,IAAI,IAAI;YAAE,OAAO,CAAC,CAAC;QAC1B,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;CACF"}

package/dist/src/remote-step-factory.d.ts

@@ -0,0 +1,15 @@
+import type { z } from 'zod';
+import type { RemoteStepDef, StepOptions } from './interfaces.js';
+export interface RemoteStepConfig<TInput, TOutput> extends StepOptions {
+    name: string;
+    /** Worker group expected to handle this step. Defaults to the `name` prefix before the first dot. */
+    group?: string;
+    input: z.ZodType<TInput>;
+    output: z.ZodType<TOutput>;
+}
+/**
+ * Defines a typed handle to a step that runs on a remote worker. Call it from a workflow with
+ * `ctx.call(step, input)`; a worker registers a handler under the same `name`.
+ */
+export declare function remoteStep<TInput, TOutput>(config: RemoteStepConfig<TInput, TOutput>): RemoteStepDef<TInput, TOutput>;
+//# sourceMappingURL=remote-step-factory.d.ts.map

package/dist/src/remote-step-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-step-factory.d.ts","sourceRoot":"","sources":["../../src/remote-step-factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAElE,MAAM,WAAW,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAE,SAAQ,WAAW;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,qGAAqG;IACrG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,EACxC,MAAM,EAAE,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,GACxC,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,CAMhC"}

package/dist/src/remote-step-factory.js

@@ -0,0 +1,12 @@
+/**
+ * Defines a typed handle to a step that runs on a remote worker. Call it from a workflow with
+ * `ctx.call(step, input)`; a worker registers a handler under the same `name`.
+ */
+export function remoteStep(config) {
+    return {
+        ...config,
+        group: config.group ?? config.name.split('.')[0] ?? config.name,
+        __remote: true,
+    };
+}
+//# sourceMappingURL=remote-step-factory.js.map

package/dist/src/remote-step-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-step-factory.js","sourceRoot":"","sources":["../../src/remote-step-factory.ts"],"names":[],"mappings":"AAWA;;;GAGG;AACH,MAAM,UAAU,UAAU,CACxB,MAAyC;IAEzC,OAAO;QACL,GAAG,MAAM;QACT,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,IAAI;QAC/D,QAAQ,EAAE,IAAI;KACf,CAAC;AACJ,CAAC"}

package/dist/src/remote-workflow-executor.d.ts

@@ -0,0 +1,24 @@
+import type { HistoryEvent, Transport, WorkflowDecision, WorkflowExecutor, WorkflowRun } from './interfaces.js';
+/**
+ * A {@link WorkflowExecutor} backed by a {@link Transport}: it advances a remote workflow by
+ * dispatching a {@link WorkflowTask} over the broker and awaiting the matching {@link WorkflowDecision}
+ * (correlated by `taskId`). Pass one to `engine.registerRemote(name, version, { group, executor })` so
+ * a workflow authored in another SDK (e.g. the Python `durable-worker`) is driven over Redis/BullMQ.
+ *
+ * Recovery-safe: if the engine crashes awaiting a decision, the re-drive dispatches a fresh task with
+ * the same history — the worker's replay is deterministic, so it returns the same decision; a late
+ * decision for the old `taskId` simply finds no waiter and is dropped.
+ */
+export declare class RemoteWorkflowExecutor implements WorkflowExecutor {
+    private readonly transport;
+    private readonly group;
+    private readonly opts;
+    private readonly pending;
+    private subscribed;
+    constructor(transport: Transport, group: string, opts?: {
+        timeoutMs?: number;
+    });
+    private ensureSubscribed;
+    advance(run: WorkflowRun, history: HistoryEvent[]): Promise<WorkflowDecision>;
+}
+//# sourceMappingURL=remote-workflow-executor.d.ts.map

package/dist/src/remote-workflow-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-workflow-executor.d.ts","sourceRoot":"","sources":["../../src/remote-workflow-executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EAEZ,MAAM,iBAAiB,CAAC;AAIzB;;;;;;;;;GASG;AACH,qBAAa,sBAAuB,YAAW,gBAAgB;IAK3D,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI;IANvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2D;IACnF,OAAO,CAAC,UAAU,CAAS;gBAGR,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,MAAM,EACb,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO;IAGpD,OAAO,CAAC,gBAAgB;IAelB,OAAO,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;CA+BpF"}

package/dist/src/remote-workflow-executor.js

@@ -0,0 +1,70 @@
+let taskCounter = 0;
+/**
+ * A {@link WorkflowExecutor} backed by a {@link Transport}: it advances a remote workflow by
+ * dispatching a {@link WorkflowTask} over the broker and awaiting the matching {@link WorkflowDecision}
+ * (correlated by `taskId`). Pass one to `engine.registerRemote(name, version, { group, executor })` so
+ * a workflow authored in another SDK (e.g. the Python `durable-worker`) is driven over Redis/BullMQ.
+ *
+ * Recovery-safe: if the engine crashes awaiting a decision, the re-drive dispatches a fresh task with
+ * the same history — the worker's replay is deterministic, so it returns the same decision; a late
+ * decision for the old `taskId` simply finds no waiter and is dropped.
+ */
+export class RemoteWorkflowExecutor {
+    transport;
+    group;
+    opts;
+    pending = new Map();
+    subscribed = false;
+    constructor(transport, group, opts = {}) {
+        this.transport = transport;
+        this.group = group;
+        this.opts = opts;
+    }
+    ensureSubscribed() {
+        if (this.subscribed)
+            return;
+        if (!this.transport.onDecision) {
+            throw new Error('transport does not support workflow decisions (onDecision)');
+        }
+        this.subscribed = true;
+        this.transport.onDecision(async (decision) => {
+            const resolve = this.pending.get(decision.taskId);
+            if (resolve) {
+                this.pending.delete(decision.taskId);
+                resolve(decision);
+            }
+        });
+    }
+    async advance(run, history) {
+        if (!this.transport.dispatchWorkflowTask) {
+            throw new Error('transport does not support workflow tasks (dispatchWorkflowTask)');
+        }
+        this.ensureSubscribed();
+        taskCounter += 1;
+        const taskId = `${run.id}:wf:${taskCounter}`;
+        const task = {
+            taskId,
+            runId: run.id,
+            workflow: run.workflow,
+            workflowVersion: run.workflowVersion,
+            input: run.input,
+            history,
+            group: this.group,
+            priority: run.priority,
+            attempt: 1,
+        };
+        const decision = new Promise((resolve, reject) => {
+            this.pending.set(taskId, resolve);
+            if (this.opts.timeoutMs) {
+                const timer = setTimeout(() => {
+                    this.pending.delete(taskId);
+                    reject(new Error(`workflow task ${taskId} timed out after ${this.opts.timeoutMs}ms`));
+                }, this.opts.timeoutMs);
+                timer.unref?.();
+            }
+        });
+        await this.transport.dispatchWorkflowTask(task);
+        return decision;
+    }
+}
+//# sourceMappingURL=remote-workflow-executor.js.map

package/dist/src/remote-workflow-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-workflow-executor.js","sourceRoot":"","sources":["../../src/remote-workflow-executor.ts"],"names":[],"mappings":"AASA,IAAI,WAAW,GAAG,CAAC,CAAC;AAEpB;;;;;;;;;GASG;AACH,MAAM,OAAO,sBAAsB;IAKd;IACA;IACA;IANF,OAAO,GAAG,IAAI,GAAG,EAAgD,CAAC;IAC3E,UAAU,GAAG,KAAK,CAAC;IAE3B,YACmB,SAAoB,EACpB,KAAa,EACb,OAA+B,EAAE;QAFjC,cAAS,GAAT,SAAS,CAAW;QACpB,UAAK,GAAL,KAAK,CAAQ;QACb,SAAI,GAAJ,IAAI,CAA6B;IACjD,CAAC;IAEI,gBAAgB;QACtB,IAAI,IAAI,CAAC,UAAU;YAAE,OAAO;QAC5B,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;QAChF,CAAC;QACD,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACvB,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE;YAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAClD,IAAI,OAAO,EAAE,CAAC;gBACZ,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;gBACrC,OAAO,CAAC,QAAQ,CAAC,CAAC;YACpB,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,GAAgB,EAAE,OAAuB;QACrD,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,oBAAoB,EAAE,CAAC;YACzC,MAAM,IAAI,KAAK,CAAC,kEAAkE,CAAC,CAAC;QACtF,CAAC;QACD,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACxB,WAAW,IAAI,CAAC,CAAC;QACjB,MAAM,MAAM,GAAG,GAAG,GAAG,CAAC,EAAE,OAAO,WAAW,EAAE,CAAC;QAC7C,MAAM,IAAI,GAAiB;YACzB,MAAM;YACN,KAAK,EAAE,GAAG,CAAC,EAAE;YACb,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,eAAe,EAAE,GAAG,CAAC,eAAe;YACpC,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,OAAO;YACP,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,OAAO,EAAE,CAAC;SACX,CAAC;QACF,MAAM,QAAQ,GAAG,IAAI,OAAO,CAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACjE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAClC,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;gBACxB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;oBAC5B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;oBAC5B,MAAM,CAAC,IAAI,KAAK,CAAC,iBAAiB,MAAM,oBAAoB,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC;gBACxF,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;gBACvB,KAAgC,CAAC,KAAK,EAAE,EAAE,CAAC;YAC9C,CAAC;QACH,CAAC,CAAC,CAAC;QACH,MAAM,IAAI,CAAC,SAAS,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC;QAChD,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF"}

package/dist/src/scheduler.d.ts

@@ -0,0 +1,67 @@
+import type { WorkflowEngine } from './engine.js';
+export interface ScheduledWorkflow {
+    /** Stable key identifying this schedule — part of the deterministic run id. */
+    key: string;
+    workflow: string;
+    input?: unknown;
+    /** Start one run every `everyMs`. Mutually exclusive with `cron`. */
+    everyMs?: number;
+    /**
+     * A cron expression (5 fields `m h dom mon dow`, or 6 with leading seconds) evaluated in
+     * {@link ScheduledWorkflow.timezone}. Mutually exclusive with `everyMs`. Needs the optional peer
+     * dependency `cron-parser`.
+     */
+    cron?: string;
+    /** IANA timezone the `cron` fires in (e.g. `America/Sao_Paulo`). Defaults to UTC. */
+    timezone?: string;
+    /** Temporarily stop firing this schedule (kept registered). Defaults to false. */
+    paused?: boolean;
+    /**
+     * What to do when the previous window's run hasn't finished yet (fixed-interval schedules only):
+     * `'allow'` (default) starts the new window anyway; `'skip'` skips it while the prior run is still
+     * `running`/`suspended`, so a slow run can't pile up overlapping executions.
+     */
+    overlap?: 'allow' | 'skip';
+    /**
+     * Randomly delay the dispatch by up to this many ms BEFORE firing, to spread load when many
+     * instances tick on the same boundary (avoids a thundering herd). Opt-in; absent = fire immediately.
+     *
+     * This is dispatch-path jitter only — it does NOT affect the run id (still the time bucket), so
+     * idempotency is unchanged: two instances jittering the same window still start it exactly once.
+     * (The engine forbids `Math.random` inside workflow code; the scheduler dispatch path is not
+     * workflow code, so jitter here is fine.)
+     */
+    jitter?: number;
+    /**
+     * Enqueue windows that were missed while the scheduler was down, instead of silently skipping
+     * them. Opt-in; absent = only the current window fires. `maxCatchup` bounds how many PRIOR windows
+     * are backfilled (a long outage can't flood the system). Backfilled runs use each missed window's
+     * deterministic bucket run id, so `engine.start` idempotency skips any that already ran.
+     */
+    backfill?: {
+        maxCatchup: number;
+    };
+}
+/** Injectable dispatch-path effects (kept out of the deterministic run-id logic). Defaults to real
+ *  `Math.random` + `setTimeout`; overridden in tests so jitter is deterministic and instant. */
+export interface RunSchedulesOptions {
+    random?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/** Deterministic run id for a fixed-interval schedule's current time window. */
+export declare function scheduledRunId(key: string, everyMs: number, nowMs: number): string;
+/**
+ * Epoch ms of the most recent cron fire at or before `nowMs`, evaluated in `timezone` (default UTC).
+ * This is the deterministic "bucket" a cron run is keyed on, so polling repeatedly within an
+ * interval resolves to the same fire time — and thus the same idempotent run id.
+ */
+export declare function prevCronFireMs(expr: string, nowMs: number, timezone?: string): number;
+/**
+ * Start each schedule's current-window run. The run id is the time bucket (a fixed-interval index,
+ * or the cron fire time) and `engine.start` is idempotent, so firing this on an interval — or
+ * racing two instances on the same tick — starts **each window exactly once**. Wire it to a
+ * `setInterval`, the durable timer poller, or `@nestjs/schedule`. Returns the run ids for the
+ * current windows.
+ */
+export declare function runSchedules(engine: Pick<WorkflowEngine, 'start' | 'getRun'>, schedules: readonly ScheduledWorkflow[], nowMs: number, opts?: RunSchedulesOptions): Promise<string[]>;
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/src/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/scheduler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAQlD,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC3B;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CACnC;AAED;gGACgG;AAChG,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAID,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAElF;AAiBD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,SAAQ,GAAG,MAAM,CAKpF;AAwCD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,GAAG,QAAQ,CAAC,EAChD,SAAS,EAAE,SAAS,iBAAiB,EAAE,EACvC,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,mBAAmB,GACzB,OAAO,CAAC,MAAM,EAAE,CAAC,CAwBnB"}

package/dist/src/scheduler.js

@@ -0,0 +1,111 @@
+import { createRequire } from 'node:module';
+// Resolve the optional `cron-parser` peer dependency in a way that works in BOTH the ESM and CJS
+// builds of this package (dual publish). `createRequire(import.meta.url)` gives a real `require` in
+// ESM output; in the CJS build, tsup's banner shims `import.meta.url` to the file URL, so the same
+// call resolves there too. This keeps the load synchronous (no async leak into the scheduler API).
+const nodeRequire = createRequire(import.meta.url);
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Deterministic run id for a fixed-interval schedule's current time window. */
+export function scheduledRunId(key, everyMs, nowMs) {
+    return `sched:${key}:${Math.floor(nowMs / everyMs)}`;
+}
+let cronParser;
+function loadCronParser() {
+    if (cronParser)
+        return cronParser;
+    try {
+        // Lazy + optional: core stays dependency-free; only users who schedule by cron need this.
+        cronParser = nodeRequire('cron-parser');
+    }
+    catch {
+        throw new Error('cron schedules need the optional peer dependency "cron-parser" — install it (e.g. `npm i cron-parser`).');
+    }
+    return cronParser;
+}
+/**
+ * Epoch ms of the most recent cron fire at or before `nowMs`, evaluated in `timezone` (default UTC).
+ * This is the deterministic "bucket" a cron run is keyed on, so polling repeatedly within an
+ * interval resolves to the same fire time — and thus the same idempotent run id.
+ */
+export function prevCronFireMs(expr, nowMs, timezone = 'UTC') {
+    const parser = loadCronParser();
+    // `+1` makes a fire landing exactly on `nowMs` count as "at or before now", not the prior one.
+    const it = parser.parseExpression(expr, { currentDate: new Date(nowMs + 1), tz: timezone });
+    return it.prev().toDate().getTime();
+}
+/** The deterministic, idempotent run id for a schedule at `nowMs` — its current fire window. */
+function scheduleRunIdAt(s, nowMs) {
+    if (s.cron != null)
+        return `sched:${s.key}:${prevCronFireMs(s.cron, nowMs, s.timezone)}`;
+    if (s.everyMs != null)
+        return scheduledRunId(s.key, s.everyMs, nowMs);
+    throw new Error(`schedule "${s.key}" needs either "everyMs" or "cron"`);
+}
+/**
+ * The run ids this schedule should fire at `nowMs`: the current window, plus — when `backfill` is set
+ * — up to `maxCatchup` prior windows that may have been missed. Oldest-first, so a backfill catches
+ * up in chronological order. Ids are the same deterministic buckets `scheduleRunIdAt` produces, so
+ * `engine.start` idempotency drops any window that already ran.
+ */
+function scheduleRunIdsAt(s, nowMs) {
+    const current = scheduleRunIdAt(s, nowMs);
+    if (!s.backfill || s.backfill.maxCatchup <= 0)
+        return [current];
+    const ids = [];
+    if (s.everyMs != null) {
+        const bucket = Math.floor(nowMs / s.everyMs);
+        const oldest = Math.max(0, bucket - s.backfill.maxCatchup);
+        for (let b = oldest; b < bucket; b += 1)
+            ids.push(`sched:${s.key}:${b}`);
+    }
+    else if (s.cron != null) {
+        // Walk back through prior cron fire times (most-recent missed first), then reverse to oldest-first.
+        const prior = [];
+        let cursor = prevCronFireMs(s.cron, nowMs, s.timezone);
+        for (let i = 0; i < s.backfill.maxCatchup; i += 1) {
+            // `cursor` (exclusive) → the fire strictly before it.
+            const before = prevCronFireMs(s.cron, cursor - 1, s.timezone);
+            prior.push(`sched:${s.key}:${before}`);
+            cursor = before;
+        }
+        ids.push(...prior.reverse());
+    }
+    ids.push(current);
+    return ids;
+}
+/**
+ * Start each schedule's current-window run. The run id is the time bucket (a fixed-interval index,
+ * or the cron fire time) and `engine.start` is idempotent, so firing this on an interval — or
+ * racing two instances on the same tick — starts **each window exactly once**. Wire it to a
+ * `setInterval`, the durable timer poller, or `@nestjs/schedule`. Returns the run ids for the
+ * current windows.
+ */
+export async function runSchedules(engine, schedules, nowMs, opts) {
+    const random = opts?.random ?? Math.random;
+    const sleep = opts?.sleep ?? defaultSleep;
+    const ids = [];
+    for (const s of schedules) {
+        if (s.paused)
+            continue;
+        // overlap:'skip' (fixed-interval): don't start this window while the previous window's run is
+        // still in-flight, so a slow run can't pile up. Interval-only — cron windows aren't adjacent ids.
+        if (s.overlap === 'skip' && s.everyMs) {
+            const prevBucket = Math.floor(nowMs / s.everyMs) - 1;
+            if (prevBucket >= 0) {
+                const prev = await engine.getRun(`sched:${s.key}:${prevBucket}`);
+                if (prev && (prev.status === 'running' || prev.status === 'suspended'))
+                    continue;
+            }
+        }
+        // Dispatch-path jitter (not workflow code): spread same-boundary ticks across instances. Applied
+        // once per schedule, before firing — the run ids below are unaffected, so idempotency holds.
+        if (s.jitter && s.jitter > 0)
+            await sleep(Math.floor(random() * s.jitter));
+        for (const runId of scheduleRunIdsAt(s, nowMs)) {
+            await engine.start(s.workflow, s.input, runId);
+            ids.push(runId);
+        }
+    }
+    return ids;
+}
+//# sourceMappingURL=scheduler.js.map