@dudousxd/nestjs-durable-core 0.71.1 → 0.72.0

package/dist/index.js

@@ -250,6 +250,23 @@ var FatalError = class extends Error {
     this.code = code;
   }
 };
+var ConcurrencyLimitError = class extends Error {
+  static {
+    __name(this, "ConcurrencyLimitError");
+  }
+  workflow;
+  key;
+  limit;
+  active;
+  constructor(workflow, key, limit, active) {
+    super(`concurrency limit reached for key "${key}" (${active}/${limit} in flight); ${workflow} was not started \u2014 retry later`);
+    this.name = "ConcurrencyLimitError";
+    this.workflow = workflow;
+    this.key = key;
+    this.limit = limit;
+    this.active = active;
+  }
+};
 var SingletonQueueFullError = class extends Error {
   static {
     __name(this, "SingletonQueueFullError");
@@ -763,6 +780,58 @@ function instantCheckpoint(p) {
 }
 __name(instantCheckpoint, "instantCheckpoint");
 
+// src/concurrency.ts
+var DEFAULT_CONCURRENCY_STATUSES = [
+  "pending",
+  "running",
+  "suspended",
+  "cancelling",
+  "blocked"
+];
+function concurrencyTag(key) {
+  return `concurrency:${key}`;
+}
+__name(concurrencyTag, "concurrencyTag");
+async function resolveConcurrency(override, config, input) {
+  if (override) return override;
+  if (!config) return void 0;
+  const key = config.key(input);
+  if (key === void 0) return void 0;
+  const limit = typeof config.limit === "function" ? await config.limit(key) : config.limit;
+  return {
+    key,
+    limit,
+    countStatuses: config.countStatuses
+  };
+}
+__name(resolveConcurrency, "resolveConcurrency");
+async function countRuns(store, query) {
+  if (store.countRuns) return store.countRuns(query);
+  if (store.runFacets && !query.status && !query.statuses && query.origin === void 0) {
+    const cells = await store.runFacets(query);
+    return cells.reduce((sum, c) => sum + c.count, 0);
+  }
+  if (store.runFacets && query.statuses && !query.status && query.origin === void 0) {
+    const { statuses, ...rest } = query;
+    const cells = await store.runFacets(rest);
+    return cells.filter((c) => statuses.includes(c.status)).reduce((sum, c) => sum + c.count, 0);
+  }
+  return (await store.listRuns(query)).length;
+}
+__name(countRuns, "countRuns");
+async function assertConcurrency(store, workflow, quota) {
+  const active = quota.limit <= 0 ? 0 : await countRuns(store, {
+    tag: concurrencyTag(quota.key),
+    statuses: [
+      ...quota.countStatuses ?? DEFAULT_CONCURRENCY_STATUSES
+    ]
+  });
+  if (quota.limit <= 0 || active >= quota.limit) {
+    throw new ConcurrencyLimitError(workflow, quota.key, quota.limit, active);
+  }
+}
+__name(assertConcurrency, "assertConcurrency");
+
 // src/entities.ts
 var ENTITY_WORKFLOW = "__entity";
 var entityRunId = /* @__PURE__ */ __name((name, key) => `entity:${name}:${key}`, "entityRunId");
@@ -1595,6 +1664,19 @@ function planDispatch(requires, liveDescriptors, cp, token) {
 }
 __name(planDispatch, "planDispatch");
 
+// src/interfaces.ts
+var TERMINAL_RUN_STATUSES = [
+  "completed",
+  "failed",
+  "cancelled",
+  "dead"
+];
+function isNonEmptyRunScope(scope) {
+  if (!scope) return false;
+  return scope.workflow !== void 0 || scope.workflows !== void 0 || scope.tag !== void 0 || scope.tags !== void 0 || scope.namespace !== void 0 || scope.namespaces !== void 0 || scope.attributes !== void 0 && scope.attributes.length > 0;
+}
+__name(isNonEmptyRunScope, "isNonEmptyRunScope");
+
 // src/tenant-group.ts
 function tenantGroup(baseGroup, tenant) {
   return tenant !== void 0 && tenant !== "" && tenant !== "default" ? `${baseGroup}@${tenant}` : baseGroup;
@@ -1685,6 +1767,486 @@ function indexWaitersByRun(waiters) {
 }
 __name(indexWaitersByRun, "indexWaitersByRun");
 
+// src/scheduler.ts
+import { createRequire } from "node:module";
+
+// src/cron-compat.ts
+function isIndexable(value) {
+  return typeof value === "object" && value !== null || typeof value === "function";
+}
+__name(isIndexable, "isIndexable");
+function unwrapDefault(module_) {
+  if (!isIndexable(module_)) return module_;
+  if (Reflect.get(module_, "parseExpression") !== void 0) return module_;
+  if (Reflect.get(module_, "CronExpressionParser") !== void 0) return module_;
+  const inner = Reflect.get(module_, "default");
+  return inner === void 0 ? module_ : inner;
+}
+__name(unwrapDefault, "unwrapDefault");
+function v4Entry(module_) {
+  if (!isIndexable(module_)) return void 0;
+  const parse = Reflect.get(module_, "parseExpression");
+  if (typeof parse !== "function") return void 0;
+  return (expr, options) => parse.call(module_, expr, options);
+}
+__name(v4Entry, "v4Entry");
+function v5Entry(module_) {
+  if (!isIndexable(module_)) return void 0;
+  const parser = Reflect.get(module_, "CronExpressionParser");
+  if (!isIndexable(parser)) return void 0;
+  const parse = Reflect.get(parser, "parse");
+  if (typeof parse !== "function") return void 0;
+  return (expr, options) => parse.call(parser, expr, options);
+}
+__name(v5Entry, "v5Entry");
+function resolveCronParse(module_) {
+  const resolved = unwrapDefault(module_);
+  return v4Entry(resolved) ?? v5Entry(resolved);
+}
+__name(resolveCronParse, "resolveCronParse");
+
+// src/scheduler.ts
+var nodeRequire = createRequire(import.meta.url);
+var defaultSleep = /* @__PURE__ */ __name((ms) => new Promise((r) => setTimeout(r, ms)), "defaultSleep");
+function scheduledRunId(key, everyMs, nowMs) {
+  return `sched:${key}:${Math.floor(nowMs / everyMs)}`;
+}
+__name(scheduledRunId, "scheduledRunId");
+var cronParser;
+function loadCronParser() {
+  if (cronParser !== void 0) return cronParser;
+  try {
+    cronParser = nodeRequire("cron-parser");
+  } catch {
+    throw new Error('cron schedules need the optional peer dependency "cron-parser" \u2014 install it (e.g. `npm i cron-parser`).');
+  }
+  return cronParser;
+}
+__name(loadCronParser, "loadCronParser");
+function prevCronFireMs(expr, nowMs, timezone = "UTC") {
+  const parse = resolveCronParse(loadCronParser());
+  if (!parse) {
+    throw new Error(`the installed "cron-parser" exposes neither v4's parseExpression nor v5's CronExpressionParser.parse \u2014 the supported range is ^4.0.0 || ^5.0.0.`);
+  }
+  return parse(expr, {
+    currentDate: new Date(nowMs + 1),
+    tz: timezone
+  }).prev().toDate().getTime();
+}
+__name(prevCronFireMs, "prevCronFireMs");
+function nextCronFireMs(expr, afterMs, timezone = "UTC") {
+  const parse = resolveCronParse(loadCronParser());
+  if (!parse) {
+    throw new Error(`the installed "cron-parser" exposes neither v4's parseExpression nor v5's CronExpressionParser.parse \u2014 the supported range is ^4.0.0 || ^5.0.0.`);
+  }
+  return parse(expr, {
+    currentDate: new Date(afterMs),
+    tz: timezone
+  }).next().toDate().getTime();
+}
+__name(nextCronFireMs, "nextCronFireMs");
+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"`);
+}
+__name(scheduleRunIdAt, "scheduleRunIdAt");
+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) {
+    const prior = [];
+    let cursor = prevCronFireMs(s.cron, nowMs, s.timezone);
+    for (let i = 0; i < s.backfill.maxCatchup; i += 1) {
+      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;
+}
+__name(scheduleRunIdsAt, "scheduleRunIdsAt");
+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;
+    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;
+      }
+    }
+    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;
+}
+__name(runSchedules, "runSchedules");
+
+// src/schedules.ts
+var ScheduleAlreadyExistsError = class extends Error {
+  static {
+    __name(this, "ScheduleAlreadyExistsError");
+  }
+  scheduleId;
+  constructor(scheduleId) {
+    super(`schedule "${scheduleId}" already exists`), this.scheduleId = scheduleId;
+    this.name = "ScheduleAlreadyExistsError";
+  }
+};
+var ScheduleNotFoundError = class extends Error {
+  static {
+    __name(this, "ScheduleNotFoundError");
+  }
+  scheduleId;
+  constructor(scheduleId) {
+    super(`schedule "${scheduleId}" not found`), this.scheduleId = scheduleId;
+    this.name = "ScheduleNotFoundError";
+  }
+};
+var DEFAULT_NAMESPACE = "default";
+var ON_TIME_GRACE_MS = 6e4;
+var TICK_BATCH = 100;
+var ScheduleClient = class {
+  static {
+    __name(this, "ScheduleClient");
+  }
+  store;
+  host;
+  options;
+  constructor(store, host, options = {}) {
+    this.store = store;
+    this.host = host;
+    this.options = options;
+  }
+  now() {
+    return (this.options.clock ?? Date.now)();
+  }
+  /** Whether the store persists schedules (implements the schedule methods). */
+  get supported() {
+    const s = this.store;
+    return !!(s.saveSchedule && s.getSchedule && s.updateSchedule && s.deleteSchedule && s.listSchedules);
+  }
+  requireStore() {
+    if (!this.supported) {
+      throw new Error("persisted schedules need a store that implements saveSchedule/getSchedule/updateSchedule/deleteSchedule/listSchedules \u2014 every bundled store adapter does; this one does not");
+    }
+    const s = this.store;
+    return {
+      saveSchedule: /* @__PURE__ */ __name((r) => s.saveSchedule.call(s, r), "saveSchedule"),
+      getSchedule: /* @__PURE__ */ __name((id) => s.getSchedule.call(s, id), "getSchedule"),
+      updateSchedule: /* @__PURE__ */ __name((id, patch, expected) => s.updateSchedule.call(s, id, patch, expected), "updateSchedule"),
+      deleteSchedule: /* @__PURE__ */ __name((id) => s.deleteSchedule.call(s, id), "deleteSchedule"),
+      listSchedules: /* @__PURE__ */ __name((q) => s.listSchedules.call(s, q), "listSchedules")
+    };
+  }
+  /** Create a schedule. Throws {@link ScheduleAlreadyExistsError} if the id is taken. */
+  async create(opts) {
+    const store = this.requireStore();
+    if (await store.getSchedule(opts.id)) throw new ScheduleAlreadyExistsError(opts.id);
+    return this.write(opts, null);
+  }
+  /**
+  * Create the schedule, or replace the definition of an existing one (its history — last fire, last
+  * run, fire count — is kept). The next fire is recomputed from now under the new definition, so a
+  * window that already fired is never fired again by an upsert.
+  */
+  async upsert(opts) {
+    const store = this.requireStore();
+    return this.write(opts, await store.getSchedule(opts.id));
+  }
+  /** The schedule `id`, or null. */
+  async get(id) {
+    const record = await this.requireStore().getSchedule(id);
+    return record ? describe(record) : null;
+  }
+  /** Schedules matching `query`, soonest-due first. */
+  async list(query = {}) {
+    return (await this.requireStore().listSchedules(query)).map(describe);
+  }
+  /** Delete the schedule. Runs it already started are left alone. Returns whether it existed. */
+  delete(id) {
+    return this.requireStore().deleteSchedule(id);
+  }
+  /** Stop firing until {@link resume}. `note` records why (shown by `get`/`list`). */
+  async pause(id, note) {
+    const store = this.requireStore();
+    const record = await this.mustGet(id);
+    const spec = {
+      ...record.spec
+    };
+    if (note !== void 0) spec.note = note;
+    await store.updateSchedule(id, {
+      paused: true,
+      spec,
+      updatedAt: new Date(this.now())
+    });
+    return describe(await this.mustGet(id));
+  }
+  /**
+  * Fire again from the next window after now — the windows skipped while paused are NOT caught up.
+  */
+  async resume(id) {
+    const store = this.requireStore();
+    const record = await this.mustGet(id);
+    const spec = record.spec;
+    const window = nextWindowAfter(spec, this.now());
+    await store.updateSchedule(id, {
+      paused: false,
+      nextFireAt: window === null ? null : window + jitterFor(record.id, window, spec),
+      state: {
+        ...record.state,
+        window
+      },
+      updatedAt: new Date(this.now())
+    });
+    return describe(await this.mustGet(id));
+  }
+  /**
+  * Start one run of the schedule right now, outside its cadence (paused or not). The run id is
+  * `sched:<id>:manual:<nowMs>`; it doesn't move the schedule's next fire.
+  */
+  async trigger(id) {
+    const record = await this.mustGet(id);
+    const runId = `sched:${id}:manual:${this.now()}`;
+    return this.host.start(record.workflow, specOf(record).input, runId, startOptions(record));
+  }
+  /**
+  * Fire every due schedule (in this engine's namespace; all namespaces for an operator engine):
+  * start its window's run and advance it to the next window. Called by the NestJS timer poller on
+  * each tick when `persistedSchedules` is on; call it yourself from any other driver. Returns the
+  * run ids started (or re-found, for an idempotent re-fire).
+  */
+  async tick(nowMs = this.now()) {
+    const store = this.requireStore();
+    const started = [];
+    for (let round = 0; round < 50; round++) {
+      const due = await store.listSchedules({
+        dueBy: nowMs,
+        namespace: this.options.namespace,
+        limit: TICK_BATCH
+      });
+      for (const record of due) {
+        const runId = await this.fire(record, nowMs);
+        if (runId) started.push(runId);
+      }
+      if (due.length < TICK_BATCH) break;
+    }
+    return started;
+  }
+  /** Fire one due schedule and advance it. Returns the run id started, if any. */
+  async fire(record, nowMs) {
+    const store = this.requireStore();
+    const spec = specOf(record);
+    const state = record.state;
+    let latest;
+    let next;
+    try {
+      latest = latestWindowAtOrBefore(spec, nowMs);
+      next = nextWindowAfter(spec, latest);
+    } catch (error2) {
+      await store.updateSchedule(record.id, {
+        paused: true,
+        nextFireAt: null,
+        state: {
+          ...state,
+          lastError: `invalid schedule: ${errorMessage(error2)}`
+        },
+        updatedAt: new Date(nowMs)
+      }, record.nextFireAt);
+      return void 0;
+    }
+    const window = state.window ?? latest;
+    const jitter = spec.jitterMs ?? 0;
+    const onTime = nowMs - latest <= ON_TIME_GRACE_MS + jitter;
+    let runId;
+    let lastError;
+    let fired = false;
+    const skipMissed = spec.catchup === "skip" && !onTime;
+    const beforeWindow = latest < window;
+    if (!skipMissed && !beforeWindow && !await this.overlapping(spec, state)) {
+      runId = `sched:${record.id}:${latest}`;
+      try {
+        await this.host.start(record.workflow, spec.input, runId, startOptions(record));
+        fired = true;
+      } catch (error2) {
+        if (await this.host.getRun(runId)) fired = true;
+        else lastError = errorMessage(error2);
+      }
+    }
+    const nextState = {
+      ...state,
+      window: next,
+      ...fired ? {
+        lastFireAt: latest,
+        lastRunId: runId,
+        fires: (state.fires ?? 0) + 1
+      } : {},
+      lastError: fired ? void 0 : lastError ?? state.lastError
+    };
+    await store.updateSchedule(record.id, {
+      nextFireAt: next === null ? null : next + jitterFor(record.id, next, spec),
+      state: stripUndefined(nextState),
+      updatedAt: new Date(nowMs)
+    }, record.nextFireAt);
+    return fired ? runId : void 0;
+  }
+  /** `overlap: 'skip'` and the previous run of this schedule is still in flight. */
+  async overlapping(spec, state) {
+    if (spec.overlap !== "skip" || !state.lastRunId) return false;
+    const prev = await this.host.getRun(state.lastRunId);
+    return !!prev && !TERMINAL_RUN_STATUSES.includes(prev.status);
+  }
+  async mustGet(id) {
+    const record = await this.requireStore().getSchedule(id);
+    if (!record) throw new ScheduleNotFoundError(id);
+    return record;
+  }
+  async write(opts, existing) {
+    const store = this.requireStore();
+    const spec = toSpec(opts);
+    const now = this.now();
+    const paused = opts.paused ?? existing?.paused ?? false;
+    const window = nextWindowAfter(spec, now);
+    const record = {
+      id: opts.id,
+      namespace: opts.namespace ?? this.options.namespace ?? DEFAULT_NAMESPACE,
+      workflow: workflowName(opts.workflow),
+      paused,
+      nextFireAt: window === null ? null : window + jitterFor(opts.id, window, spec),
+      tags: opts.tags,
+      spec,
+      state: stripUndefined({
+        ...existing?.state ?? {},
+        window
+      }),
+      createdAt: existing?.createdAt ?? new Date(now),
+      updatedAt: new Date(now)
+    };
+    await store.saveSchedule(record);
+    return describe(record);
+  }
+};
+function toSpec(opts) {
+  if (opts.cron == null === (opts.every == null)) {
+    throw new Error(`schedule "${opts.id}" needs exactly one of "cron" or "every"`);
+  }
+  const everyMs = opts.every != null ? parseDuration(opts.every) : void 0;
+  if (everyMs !== void 0 && !(everyMs > 0)) {
+    throw new Error(`schedule "${opts.id}": "every" must be a positive duration`);
+  }
+  const jitterMs = opts.jitter != null ? parseDuration(opts.jitter) : void 0;
+  return stripUndefined({
+    v: 1,
+    input: opts.input,
+    cron: opts.cron,
+    everyMs,
+    timezone: opts.timezone,
+    jitterMs: jitterMs && jitterMs > 0 ? jitterMs : void 0,
+    overlap: opts.overlap ?? "allow",
+    catchup: opts.catchup ?? "latest",
+    note: opts.note,
+    searchAttributes: opts.searchAttributes,
+    priority: opts.priority,
+    concurrency: opts.concurrency
+  });
+}
+__name(toSpec, "toSpec");
+function specOf(record) {
+  return record.spec;
+}
+__name(specOf, "specOf");
+function latestWindowAtOrBefore(spec, atMs) {
+  if (spec.cron != null) return prevCronFireMs(spec.cron, atMs, spec.timezone);
+  const every = spec.everyMs;
+  return Math.floor(atMs / every) * every;
+}
+__name(latestWindowAtOrBefore, "latestWindowAtOrBefore");
+function nextWindowAfter(spec, afterMs) {
+  if (spec.cron != null) return nextCronFireMs(spec.cron, afterMs, spec.timezone);
+  const every = spec.everyMs;
+  return (Math.floor(afterMs / every) + 1) * every;
+}
+__name(nextWindowAfter, "nextWindowAfter");
+function jitterFor(id, window, spec) {
+  const max = spec.jitterMs ?? 0;
+  if (max <= 0) return 0;
+  let h = 2166136261;
+  for (const ch of `${id}@${window}`) {
+    h ^= ch.charCodeAt(0);
+    h = Math.imul(h, 16777619) >>> 0;
+  }
+  return h % max;
+}
+__name(jitterFor, "jitterFor");
+function startOptions(record) {
+  const spec = specOf(record);
+  return stripUndefined({
+    tags: [
+      ...record.tags ?? [],
+      `schedule:${record.id}`
+    ],
+    namespace: record.namespace,
+    searchAttributes: spec.searchAttributes,
+    priority: spec.priority,
+    concurrency: spec.concurrency
+  });
+}
+__name(startOptions, "startOptions");
+function describe(record) {
+  const spec = specOf(record);
+  const state = record.state;
+  return stripUndefined({
+    id: record.id,
+    workflow: record.workflow,
+    input: spec.input,
+    namespace: record.namespace,
+    cron: spec.cron,
+    everyMs: spec.everyMs,
+    timezone: spec.timezone,
+    jitterMs: spec.jitterMs,
+    overlap: spec.overlap ?? "allow",
+    catchup: spec.catchup ?? "latest",
+    paused: record.paused,
+    note: spec.note,
+    tags: record.tags,
+    searchAttributes: spec.searchAttributes,
+    priority: spec.priority,
+    concurrency: spec.concurrency,
+    nextFireAt: record.paused || record.nextFireAt == null ? null : new Date(record.nextFireAt),
+    lastFireAt: state.lastFireAt != null ? new Date(state.lastFireAt) : void 0,
+    lastRunId: state.lastRunId,
+    fires: state.fires ?? 0,
+    lastError: state.lastError,
+    createdAt: record.createdAt,
+    updatedAt: record.updatedAt
+  });
+}
+__name(describe, "describe");
+function stripUndefined(o) {
+  return Object.fromEntries(Object.entries(o).filter(([, v]) => v !== void 0));
+}
+__name(stripUndefined, "stripUndefined");
+function errorMessage(error2) {
+  return error2 instanceof Error ? error2.message : String(error2);
+}
+__name(errorMessage, "errorMessage");
+
 // src/singleton-gate.ts
 var SINGLETON_RETRY_MS = 1e3;
 var SINGLETON_RETRY_JITTER_MS = 250;
@@ -2753,6 +3315,12 @@ var WorkflowEngine = class {
   runDispatcher;
   /** Per-key serialization for singleton workflows (admission, back-pressure, notify-on-release). */
   singletons;
+  /**
+  * Persisted, runtime-managed schedules: create/upsert/pause/resume/delete/list/trigger them, and
+  * `tick()` fires the due ones (the NestJS timer poller does it when `persistedSchedules` is on).
+  * Needs a store that persists schedules — every bundled adapter does. See {@link ScheduleClient}.
+  */
+  schedules;
   /** Every registered workflow, keyed by `name@version` — so old versions stay runnable. */
   workflows = /* @__PURE__ */ new Map();
   /** The newest registered version per workflow name — used to `start` new runs. */
@@ -2837,6 +3405,13 @@ var WorkflowEngine = class {
       }, "dispatch"),
       configFor: /* @__PURE__ */ __name((run) => (this.workflows.get(versionKey(run.workflow, run.workflowVersion)) ?? this.latest.get(run.workflow))?.singleton, "configFor")
     });
+    this.schedules = new ScheduleClient(this.store, {
+      start: /* @__PURE__ */ __name((workflow, input, runId, opts) => this.start(workflow, input, runId, opts), "start"),
+      getRun: /* @__PURE__ */ __name((runId) => this.store.getRun(runId), "getRun")
+    }, {
+      namespace: this.namespace,
+      clock: this.clock
+    });
     this.pool.bind(
       async (result) => {
         const waiter = this.pending.get(result.stepId);
@@ -2972,6 +3547,7 @@ var WorkflowEngine = class {
       fn,
       tags: opts?.tags,
       singleton: opts?.singleton,
+      concurrency: opts?.concurrency,
       executionTimeoutMs: opts?.executionTimeout != null ? parseDuration(opts.executionTimeout) : void 0,
       validateInput: opts?.validateInput,
       searchAttributesSchema: opts?.searchAttributesSchema,
@@ -3034,6 +3610,7 @@ var WorkflowEngine = class {
       }, "fn"),
       tags: opts.tags,
       singleton: opts.singleton,
+      concurrency: opts.concurrency,
       executionTimeoutMs: opts.executionTimeout != null ? parseDuration(opts.executionTimeout) : void 0,
       validateInput: opts.validateInput,
       requires: opts.requires,
@@ -3205,12 +3782,17 @@ var WorkflowEngine = class {
         error: prior.error
       };
     }
+    const quota = await resolveConcurrency(opts?.concurrency, registered.concurrency, input);
+    if (quota) await assertConcurrency(this.store, name, quota);
     const now = /* @__PURE__ */ new Date();
     const stampedTags = [
       ...opts?.tags ?? [],
       ...registered.singleton ? [
         this.singletons.tag(registered.singleton, input)
       ] : [],
+      ...quota ? [
+        concurrencyTag(quota.key)
+      ] : [],
       ...registered.versionDeclared === false ? [
         VERSION_UNDECLARED_TAG
       ] : []
@@ -4248,6 +4830,123 @@ var WorkflowEngine = class {
     return deleted + 1;
   }
   /**
+  * Hard-delete EVERY run matching `scope` — plus, by default, each one's whole child subtree — in
+  * bounded batches. The "forget this tenant" / "drop this feature's history" operation: where
+  * {@link deleteRun} removes one tree you already know the id of, this drains everything a scope
+  * selects (`{ namespace: 'acme' }`, `{ tag: 'tenant:acme' }`, `{ workflows: [...] }`, attribute
+  * predicates …) through the store API, so no caller has to reach into the `durable_*` tables.
+  *
+  *  - **Live runs** (not yet terminal) are {@link cancel cancelled} first (plain cancel, no saga
+  *    undo), which tells any worker holding one to stop, and then deleted with the rest. Pass
+  *    `cancelLive: false` to leave live runs (and live descendants of finished ones) alone and
+  *    delete terminal history only.
+  *  - **Children** are found through the same parent→child edges as {@link getRunChildren} and deleted
+  *    with their root even when they don't match `scope` themselves (children inherit `namespace`,
+  *    but not `tags`). `children: false` deletes exactly the matching runs.
+  *  - **Batched**: `batchSize` runs (default 500) per round, each round one bulk
+  *    {@link StateStore.deleteRuns} (falling back to per-run {@link StateStore.deleteRun}).
+  *
+  * An EMPTY scope is rejected — it would delete every run in the store. Returns how many runs were
+  * deleted (children included).
+  */
+  async purgeRuns(scope, opts) {
+    if (!isNonEmptyRunScope(scope)) {
+      throw new Error("purgeRuns: refusing an empty scope (it would delete every run) \u2014 pass at least one predicate, e.g. { namespace }");
+    }
+    const batchSize = Math.max(1, opts?.batchSize ?? 500);
+    const cancelLive = opts?.cancelLive ?? true;
+    const withChildren = opts?.children ?? true;
+    const statuses = cancelLive ? void 0 : [
+      ...TERMINAL_RUN_STATUSES
+    ];
+    let deleted = 0;
+    let previous = "";
+    for (; ; ) {
+      const batch = await this.store.listRuns({
+        ...scope,
+        statuses,
+        limit: batchSize
+      });
+      if (batch.length === 0) break;
+      const fingerprint = batch.map((r) => r.id).join("\0");
+      if (fingerprint === previous) {
+        throw new Error("purgeRuns: the store returned the same runs after deleting them");
+      }
+      previous = fingerprint;
+      const known = new Map(batch.map((r) => [
+        r.id,
+        r.status
+      ]));
+      const ids = withChildren ? await this.collectSubtrees(batch.map((r) => r.id)) : batch.map((r) => r.id);
+      const doomed = [];
+      for (const id of ids) {
+        const status = known.has(id) ? known.get(id) : (await this.store.getRun(id))?.status;
+        if (status === void 0) continue;
+        if (!TERMINAL_RUN_STATUSES.includes(status)) {
+          if (!cancelLive) continue;
+          await this.cancel(id).catch(() => void 0);
+        }
+        doomed.push(id);
+      }
+      await this.deleteRunIds(doomed);
+      deleted += doomed.length;
+      if (batch.length < batchSize) break;
+    }
+    return deleted;
+  }
+  /**
+  * {@link purgeRuns} for one namespace — every run (and child) a tenant/partition owns. Children
+  * inherit their parent's namespace, so a namespace purge is complete by construction.
+  */
+  purgeNamespace(namespace, opts) {
+    return this.purgeRuns({
+      namespace
+    }, opts);
+  }
+  /** The given runs plus every descendant, children before parents. One waiter scan for the batch. */
+  async collectSubtrees(rootIds) {
+    const waitersByParent = /* @__PURE__ */ new Map();
+    for (const w of await this.store.listSignalWaiters("child:")) {
+      const list = waitersByParent.get(w.runId) ?? [];
+      list.push(w.token.slice("child:".length));
+      waitersByParent.set(w.runId, list);
+    }
+    const prefixes = [
+      "signal:child:",
+      "spawn:"
+    ];
+    const childrenOf = /* @__PURE__ */ __name(async (parent) => {
+      const ids = new Set(waitersByParent.get(parent) ?? []);
+      const cps = this.store.listCheckpointsByNamePrefix ? await this.store.listCheckpointsByNamePrefix(parent, prefixes) : (await this.store.listCheckpoints(parent)).filter((cp) => prefixes.some((p) => cp.name.startsWith(p)));
+      for (const cp of cps) {
+        if (cp.name.startsWith("signal:child:")) ids.add(cp.name.slice("signal:child:".length));
+        if (cp.name.startsWith("spawn:") && typeof cp.output === "string") ids.add(cp.output);
+      }
+      return [
+        ...ids
+      ];
+    }, "childrenOf");
+    const ordered = [];
+    const seen = /* @__PURE__ */ new Set();
+    const visit = /* @__PURE__ */ __name(async (id) => {
+      if (seen.has(id)) return;
+      seen.add(id);
+      for (const child of await childrenOf(id)) await visit(child);
+      ordered.push(id);
+    }, "visit");
+    for (const id of rootIds) await visit(id);
+    return ordered;
+  }
+  /** Bulk-delete through the store's `deleteRuns`, or one `deleteRun` per id when it has none. */
+  async deleteRunIds(ids) {
+    if (ids.length === 0) return;
+    if (this.store.deleteRuns) {
+      await this.store.deleteRuns(ids);
+      return;
+    }
+    for (const id of ids) await this.store.deleteRun(id);
+  }
+  /**
   * Cascade cancellation to a run's children — both awaited (`ctx.child`, found via its live
   * `child:<id>` waiter) and fire-and-forget (`ctx.startChild`, found via its `spawn:<id>`
   * checkpoint). Recursive, so a whole subtree is cancelled; the terminal guard in `cancel` stops it
@@ -6268,14 +6967,6 @@ var RemoteStepError = class extends Error {
   }
 };
 
-// src/interfaces.ts
-var TERMINAL_RUN_STATUSES = [
-  "completed",
-  "failed",
-  "cancelled",
-  "dead"
-];
-
 // src/run-facets.ts
 function facetOrigin(origin) {
   return origin?.trim() ? origin : null;
@@ -6307,7 +6998,8 @@ __name(mergeRunFacetRows, "mergeRunFacetRows");
 var RUN_VALUE_FACET_LIMIT = 100;
 var RUN_VALUE_FACET_SCAN = 5e3;
 var ENGINE_MINTED_TAG_PREFIXES = [
-  "singleton:"
+  "singleton:",
+  "concurrency:"
 ];
 function isEngineMintedTag(value) {
   return value !== null && ENGINE_MINTED_TAG_PREFIXES.some((prefix) => value.startsWith(prefix));
@@ -6412,9 +7104,42 @@ var CodecStateStore = class {
   * Bound the same conditional way as {@link runFacets} so absence is reported, not faked.
   */
   runValueFacets;
+  /** Forwarded verbatim (deletes touch no payload). Bound only when the inner store has it, so the
+  *  engine's per-run fallback still kicks in through the wrapper. */
+  deleteRuns;
+  /** Forwarded verbatim — retention selects by status/updatedAt/scope, never by payload. Bound only
+  *  when the inner store prunes, so the retention poller still sees (and warns about) its absence. */
+  pruneTerminalRuns;
+  /** Forwarded verbatim — a count reads no payload. Bound only when the inner store counts, so the
+  *  engine's facet/listing fallback still applies through the wrapper. */
+  countRuns;
+  /** Schedules persist their run `input` inside `spec` — encoded like any other payload. Bound only
+  *  when the inner store persists schedules, so `engine.schedules` reports absence faithfully. */
+  saveSchedule;
+  getSchedule;
+  updateSchedule;
+  deleteSchedule;
+  listSchedules;
   constructor(inner, codec) {
     this.inner = inner;
     this.codec = codec;
+    const deleteRuns = inner.deleteRuns;
+    if (deleteRuns) this.deleteRuns = (ids) => deleteRuns.call(inner, ids);
+    const prune = inner.pruneTerminalRuns;
+    if (prune) this.pruneTerminalRuns = (policy, now, limit) => prune.call(inner, policy, now, limit);
+    const count = inner.countRuns;
+    if (count) this.countRuns = (query) => count.call(inner, query);
+    const { saveSchedule, getSchedule, updateSchedule, deleteSchedule, listSchedules } = inner;
+    if (saveSchedule && getSchedule && updateSchedule && deleteSchedule && listSchedules) {
+      this.saveSchedule = (r) => saveSchedule.call(inner, this.encSchedule(r));
+      this.getSchedule = async (id) => this.decSchedule(await getSchedule.call(inner, id));
+      this.updateSchedule = (id, patch, expected) => updateSchedule.call(inner, id, patch.spec ? {
+        ...patch,
+        spec: this.encSpec(patch.spec)
+      } : patch, expected);
+      this.deleteSchedule = (id) => deleteSchedule.call(inner, id);
+      this.listSchedules = async (q) => (await listSchedules.call(inner, q)).map((r) => this.decSchedule(r));
+    }
     const facets = inner.runFacets;
     if (facets) this.runFacets = (query) => facets.call(inner, query);
     const valueFacets = inner.runValueFacets;
@@ -6456,6 +7181,28 @@ var CodecStateStore = class {
       output: this.dec(cp.output)
     };
   }
+  encSpec(spec) {
+    return "input" in spec ? {
+      ...spec,
+      input: this.enc(spec.input)
+    } : spec;
+  }
+  encSchedule(r) {
+    return {
+      ...r,
+      spec: this.encSpec(r.spec)
+    };
+  }
+  decSchedule(r) {
+    if (!r || !("input" in r.spec)) return r;
+    return {
+      ...r,
+      spec: {
+        ...r.spec,
+        input: this.dec(r.spec.input)
+      }
+    };
+  }
   ensureSchema() {
     return this.inner.ensureSchema?.() ?? Promise.resolve();
   }
@@ -6654,126 +7401,6 @@ function collectMetrics(engine) {
 }
 __name(collectMetrics, "collectMetrics");
 
-// src/scheduler.ts
-import { createRequire } from "node:module";
-
-// src/cron-compat.ts
-function isIndexable(value) {
-  return typeof value === "object" && value !== null || typeof value === "function";
-}
-__name(isIndexable, "isIndexable");
-function unwrapDefault(module_) {
-  if (!isIndexable(module_)) return module_;
-  if (Reflect.get(module_, "parseExpression") !== void 0) return module_;
-  if (Reflect.get(module_, "CronExpressionParser") !== void 0) return module_;
-  const inner = Reflect.get(module_, "default");
-  return inner === void 0 ? module_ : inner;
-}
-__name(unwrapDefault, "unwrapDefault");
-function v4Entry(module_) {
-  if (!isIndexable(module_)) return void 0;
-  const parse = Reflect.get(module_, "parseExpression");
-  if (typeof parse !== "function") return void 0;
-  return (expr, options) => parse.call(module_, expr, options);
-}
-__name(v4Entry, "v4Entry");
-function v5Entry(module_) {
-  if (!isIndexable(module_)) return void 0;
-  const parser = Reflect.get(module_, "CronExpressionParser");
-  if (!isIndexable(parser)) return void 0;
-  const parse = Reflect.get(parser, "parse");
-  if (typeof parse !== "function") return void 0;
-  return (expr, options) => parse.call(parser, expr, options);
-}
-__name(v5Entry, "v5Entry");
-function resolveCronParse(module_) {
-  const resolved = unwrapDefault(module_);
-  return v4Entry(resolved) ?? v5Entry(resolved);
-}
-__name(resolveCronParse, "resolveCronParse");
-
-// src/scheduler.ts
-var nodeRequire = createRequire(import.meta.url);
-var defaultSleep = /* @__PURE__ */ __name((ms) => new Promise((r) => setTimeout(r, ms)), "defaultSleep");
-function scheduledRunId(key, everyMs, nowMs) {
-  return `sched:${key}:${Math.floor(nowMs / everyMs)}`;
-}
-__name(scheduledRunId, "scheduledRunId");
-var cronParser;
-function loadCronParser() {
-  if (cronParser !== void 0) return cronParser;
-  try {
-    cronParser = nodeRequire("cron-parser");
-  } catch {
-    throw new Error('cron schedules need the optional peer dependency "cron-parser" \u2014 install it (e.g. `npm i cron-parser`).');
-  }
-  return cronParser;
-}
-__name(loadCronParser, "loadCronParser");
-function prevCronFireMs(expr, nowMs, timezone = "UTC") {
-  const parse = resolveCronParse(loadCronParser());
-  if (!parse) {
-    throw new Error(`the installed "cron-parser" exposes neither v4's parseExpression nor v5's CronExpressionParser.parse \u2014 the supported range is ^4.0.0 || ^5.0.0.`);
-  }
-  return parse(expr, {
-    currentDate: new Date(nowMs + 1),
-    tz: timezone
-  }).prev().toDate().getTime();
-}
-__name(prevCronFireMs, "prevCronFireMs");
-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"`);
-}
-__name(scheduleRunIdAt, "scheduleRunIdAt");
-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) {
-    const prior = [];
-    let cursor = prevCronFireMs(s.cron, nowMs, s.timezone);
-    for (let i = 0; i < s.backfill.maxCatchup; i += 1) {
-      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;
-}
-__name(scheduleRunIdsAt, "scheduleRunIdsAt");
-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;
-    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;
-      }
-    }
-    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;
-}
-__name(runSchedules, "runSchedules");
-
 // src/search-attributes.ts
 function compare(actual, filter) {
   if (filter.op === "in") return filter.values.some((v) => actual === v);
@@ -6981,6 +7608,38 @@ var InMemoryStateStore = class {
     }
     this.reindexAttributes(runId, void 0);
   }
+  async deleteRuns(runIds) {
+    for (const runId of runIds) await this.deleteRun(runId);
+  }
+  async pruneTerminalRuns(policy, nowMs, limit) {
+    const statuses = policy.statuses.filter((s) => TERMINAL_RUN_STATUSES.includes(s));
+    if (statuses.length === 0 || limit <= 0) return 0;
+    if (policy.maxAge == null && policy.maxCount == null) return 0;
+    const inScope = this.matching({
+      ...policy.scope ?? {},
+      statuses
+    });
+    const ids = /* @__PURE__ */ new Set();
+    if (policy.maxAge != null) {
+      const cutoff = nowMs - parseDuration(policy.maxAge);
+      const expired = inScope.filter((r) => r.updatedAt.getTime() < cutoff).sort((a, b) => a.updatedAt.getTime() - b.updatedAt.getTime()).slice(0, limit);
+      for (const r of expired) ids.add(r.id);
+    }
+    if (policy.maxCount != null && ids.size < limit) {
+      const byRecency = [
+        ...inScope
+      ].sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime() || b.id.localeCompare(a.id));
+      for (const r of byRecency.slice(policy.maxCount)) {
+        if (ids.size >= limit) break;
+        ids.add(r.id);
+      }
+    }
+    const doomed = [
+      ...ids
+    ].slice(0, limit);
+    await this.deleteRuns(doomed);
+    return doomed.length;
+  }
   async getCheckpoint(runId, seq) {
     const cp = this.checkpoints.get(this.key(runId, seq));
     return cp ? {
@@ -7188,6 +7847,9 @@ var InMemoryStateStore = class {
       ...r
     }));
   }
+  async countRuns(query) {
+    return this.matching(query).length;
+  }
   async runFacets(query) {
     return mergeRunFacetRows(this.matching(query).map((run) => ({
       status: run.status,
@@ -7205,6 +7867,34 @@ var InMemoryStateStore = class {
     });
     return runValueFacetsFromRuns(runs, axis, opts);
   }
+  schedules = /* @__PURE__ */ new Map();
+  async saveSchedule(record) {
+    this.schedules.set(record.id, structuredClone(record));
+  }
+  async getSchedule(id) {
+    const record = this.schedules.get(id);
+    return record ? structuredClone(record) : null;
+  }
+  async updateSchedule(id, patch, expectedNextFireAt) {
+    const record = this.schedules.get(id);
+    if (!record) return false;
+    if (expectedNextFireAt !== void 0 && record.nextFireAt !== expectedNextFireAt) return false;
+    this.schedules.set(id, {
+      ...record,
+      ...structuredClone(patch)
+    });
+    return true;
+  }
+  async deleteSchedule(id) {
+    return this.schedules.delete(id);
+  }
+  async listSchedules(query) {
+    const rows = [
+      ...this.schedules.values()
+    ].filter((s) => query.namespace === void 0 || s.namespace === query.namespace).filter((s) => query.workflow === void 0 || s.workflow === query.workflow).filter((s) => query.tag === void 0 || (s.tags ?? []).includes(query.tag)).filter((s) => query.paused === void 0 || s.paused === query.paused).filter((s) => query.dueBy === void 0 || !s.paused && s.nextFireAt !== null && s.nextFireAt <= query.dueBy).sort((a, b) => (a.nextFireAt ?? Number.POSITIVE_INFINITY) - (b.nextFireAt ?? Number.POSITIVE_INFINITY) || a.id.localeCompare(b.id));
+    const offset = query.offset ?? 0;
+    return rows.slice(offset, query.limit != null ? offset + query.limit : void 0).map((s) => structuredClone(s));
+  }
   async listCheckpoints(runId) {
     const rows = [
       ...this.checkpoints.values()
@@ -7285,7 +7975,9 @@ export {
   CONTROL_FLOW_SIGNAL,
   CURRENT_PROTOCOL_VERSION,
   CodecStateStore,
+  ConcurrencyLimitError,
   ContinueAsNew,
+  DEFAULT_CONCURRENCY_STATUSES,
   DEFAULT_PARTITION,
   DURABLE_OPTIONS,
   DURABLE_OPTIONS_CANONICAL,
@@ -7315,6 +8007,9 @@ export {
   RunGateway,
   STATE_STORE,
   STATE_STORE_CANONICAL,
+  ScheduleAlreadyExistsError,
+  ScheduleClient,
+  ScheduleNotFoundError,
   SignalTimeoutError,
   SingletonQueueFullError,
   TERMINAL_RUN_STATUSES,
@@ -7328,6 +8023,7 @@ export {
   aggregateAnnouncements,
   announcementsOf,
   applyAttributeQuery,
+  assertConcurrency,
   attributeColumnFor,
   attributeOperand,
   attributePredicateOperands,
@@ -7340,7 +8036,9 @@ export {
   classifyWaiterToken,
   clearDurableExecutionWrappers,
   collectMetrics,
+  concurrencyTag,
   controlPlaneDescriptor,
+  countRuns,
   coveredTokens,
   createStepLogger,
   currentStep,
@@ -7362,6 +8060,7 @@ export {
   isEngineMintedTag,
   isEventToken,
   isLegacyDescriptor,
+  isNonEmptyRunScope,
   isWorkflowControlFlowSignal,
   log,
   matchesAttributes,
@@ -7369,6 +8068,7 @@ export {
   mergeRunValueFacetRows,
   missingCapabilities,
   negotiate,
+  nextCronFireMs,
   normalizeAttributeRows,
   normalizeDescriptor,
   observedAnnouncements,
@@ -7378,6 +8078,7 @@ export {
   prevCronFireMs,
   readSearchAttributes,
   requiredCapabilities,
+  resolveConcurrency,
   resolveRouting,
   resolveRunWaiting,
   runDurableExecution,