@dudousxd/nestjs-durable-core 0.71.0 → 0.72.0

package/dist/index.d.ts

@@ -935,10 +935,23 @@ interface StateStore {
      * first), cascading to their child rows exactly like {@link deleteRun}. Returns how many runs were
      * deleted — call again while it returns `limit` to drain a large backlog in bounded batches.
      *
+     * A policy with a {@link RetentionPolicy.scope} only ever selects (and counts, for `maxCount`) runs
+     * matching that scope.
+     *
      * Optional: only adapters that implement a bulk prune provide it; the retention poller no-ops with a
      * warning when the configured store omits it. See {@link RetentionPolicy} for the keep/prune rule.
      */
     pruneTerminalRuns?(policy: RetentionPolicy, nowMs: number, limit: number): Promise<number>;
+    /**
+     * Hard-delete a BATCH of runs and all of their rows in one go — exactly {@link deleteRun} applied to
+     * every id (checkpoints, signal waiters, attribute rows, then the runs), but as a handful of
+     * `IN (...)` statements in one transaction instead of four round-trips per run. Ids that don't exist
+     * are ignored. Like {@link deleteRun} it removes exactly the listed runs; the engine's
+     * `purgeRuns` walks the child edges first.
+     *
+     * Optional: a store that omits it still works — the engine falls back to one {@link deleteRun} per id.
+     */
+    deleteRuns?(runIds: string[]): Promise<void>;
     getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
     /**
      * Persist a checkpoint and advance the run atomically. Durable semantics depend on this
@@ -1031,7 +1044,30 @@ interface StateStore {
      * adapters implement it; `ctx.transaction` errors on a store without it.
      */
     transaction?<T>(work: (tx: StoreTransaction) => Promise<T>): Promise<T>;
+    /** Insert or fully replace the schedule `record.id`. */
+    saveSchedule?(record: ScheduleRecord): Promise<void>;
+    /** The schedule `id`, or null. */
+    getSchedule?(id: string): Promise<ScheduleRecord | null>;
+    /**
+     * Patch the schedule `id`. With `expectedNextFireAt`, a compare-and-set: the patch applies only if
+     * the stored `nextFireAt` still equals it (`null` matching `NULL`), which is how two schedulers racing
+     * on the same due schedule agree on who advanced it. Returns whether a row was updated.
+     */
+    updateSchedule?(id: string, patch: Partial<Omit<ScheduleRecord, 'id' | 'createdAt'>>, expectedNextFireAt?: number | null): Promise<boolean>;
+    /** Delete the schedule `id`. Returns whether it existed. Its past runs are left alone. */
+    deleteSchedule?(id: string): Promise<boolean>;
+    /** Schedules matching `query`, ordered by `nextFireAt` ascending (never-firing last), then `id`. */
+    listSchedules?(query: ScheduleQuery): Promise<ScheduleRecord[]>;
     listRuns(query: RunQuery): Promise<WorkflowRun[]>;
+    /**
+     * How many runs match `query` — a single `COUNT(*)` over the same predicates {@link listRuns}
+     * applies, without materializing a row. What the start-time concurrency quota asks on every start
+     * (`tag = concurrency:<key> AND status IN (...)`), so it must stay an aggregate, not a listing.
+     *
+     * Optional: a store that omits it still works — the engine falls back to summing {@link runFacets}
+     * cells, then to counting a {@link listRuns} result.
+     */
+    countRuns?(query: Omit<RunQuery, 'limit' | 'offset'>): Promise<number>;
     /**
      * Count the runs matching `query`, grouped by `(status, origin)` — the totals behind a console's
      * status and origin chips, in ONE aggregate instead of a full listing the caller counts in memory.
@@ -1080,6 +1116,44 @@ interface StateStore {
      */
     listCheckpointsByNamePrefix?(runId: string, prefixes: string[]): Promise<StepCheckpoint[]>;
 }
+/**
+ * A persisted schedule as the STORE sees it: a handful of queryable columns plus two JSON documents
+ * the store keeps verbatim (`spec`, `state`) and never interprets. The engine's schedule client owns
+ * their meaning (cron/interval math, overlap, catch-up) — so a store only has to persist rows and
+ * answer "which unpaused schedules are due by T".
+ */
+interface ScheduleRecord {
+    /** Caller-chosen, stable id (e.g. `digest:user-42`) — also part of every run id it starts. */
+    id: string;
+    /** Partition: the namespace its runs are stamped with, and which schedulers fire it. */
+    namespace: string;
+    /** Registered workflow name the schedule starts. */
+    workflow: string;
+    /** A paused schedule is never due. */
+    paused: boolean;
+    /** Epoch ms at which it is next due (jitter included), or null when it will never fire again. */
+    nextFireAt: number | null;
+    /** Labels to list/filter schedules by (also stamped onto the runs it starts). */
+    tags?: string[] | undefined;
+    /** The schedule's definition — opaque to the store. */
+    spec: Record<string, unknown>;
+    /** The schedule's bookkeeping (last fire, last run id, last error…) — opaque to the store. */
+    state: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** Filter for {@link StateStore.listSchedules}. Every predicate is ANDed; absent = unrestricted. */
+interface ScheduleQuery {
+    namespace?: string | undefined;
+    workflow?: string | undefined;
+    /** Only schedules carrying this tag. */
+    tag?: string | undefined;
+    paused?: boolean | undefined;
+    /** Only DUE schedules: unpaused, `nextFireAt <= dueBy`. */
+    dueBy?: number | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+}
 /** The terminal run statuses — a run in one of these is finished and will never change on its own.
  *  Only these are eligible for retention pruning (a {@link RetentionPolicy} targeting a non-terminal
  *  status would race the engine and delete live work). */
@@ -1100,7 +1174,27 @@ interface RetentionPolicy {
     statuses: RunStatus[];
     maxAge?: number | string;
     maxCount?: number;
+    /**
+     * Confine the policy to the runs matching these predicates (same semantics as the {@link RunQuery}
+     * fields of the same names) — e.g. `{ namespace: 'acme' }` for one tenant, `{ tags: ['chat'] }` for
+     * one kind of run, `{ workflows: ['report', 'report.branch'] }` for a workflow family. Absent = every
+     * run in `statuses`. `maxCount` is then counted WITHIN the scope ("keep acme's newest 100").
+     *
+     * A scope matches runs by their own row, so a child run is only covered if it matches too (children
+     * inherit their parent's `namespace`, but not its `tags`) — scope by `namespace` or by `workflows`
+     * when a whole run tree must age out together.
+     */
+    scope?: RunScope | undefined;
 }
+/**
+ * The run predicates a bulk operation (a scoped {@link RetentionPolicy}, `engine.purgeRuns`) is
+ * confined to — the identity axes of a {@link RunQuery}: which tenant (`namespace`), which kind of
+ * run (`workflow`/`tags`), which business entity (`attributes`). Status, origin and paging are left
+ * out on purpose: each bulk operation owns its own status rule.
+ */
+type RunScope = Pick<RunQuery, 'workflow' | 'workflows' | 'tag' | 'tags' | 'namespace' | 'namespaces' | 'attributes'>;
+/** True when `scope` sets at least one predicate — a bulk delete refuses an empty (match-all) scope. */
+declare function isNonEmptyRunScope(scope: RunScope | undefined): boolean;
 /** Typed, queryable per-run data — exact values for `eq`/`ne`, numbers/strings for range ops. */
 type SearchAttributes = Record<string, string | number | boolean>;
 /**
@@ -2280,6 +2374,41 @@ interface WorkflowCtx<A extends SearchAttributes = SearchAttributes> {
      */
     localStep<TOutput>(name: string, fn: (log: StepLogger) => Promise<TOutput>, options?: StepOptions): Promise<TOutput>;
 }
+/**
+ * {@link WorkflowCtx} with ONE signature per method: the string-addressed forms of the four overloaded
+ * methods (`step`, `child`, `startChild`, `all`), everything else unchanged.
+ *
+ * For code that drives the ctx DYNAMICALLY — an interpreter that runs a user-defined graph and only
+ * ever knows workflow/step names as strings — and for test fakes. An overloaded method is awkward to
+ * satisfy structurally (a fake must implement every overload, and a hand-written narrow interface
+ * has to guess which overload TS will match), so depend on this instead:
+ *
+ * ```ts
+ * type InterpreterCtx = Pick<DynamicWorkflowCtx, 'runId' | 'localStep' | 'child' | 'all' | 'sleep'>;
+ * class Interpreter { constructor(private readonly ctx: InterpreterCtx) {} }
+ *
+ * async run(ctx: WorkflowCtx, input: Input) {
+ *   return new Interpreter(ctx).run(); // no cast — a WorkflowCtx IS a DynamicWorkflowCtx
+ * }
+ * ```
+ *
+ * Every `WorkflowCtx<A>` is assignable to `DynamicWorkflowCtx<A>` (guarded by
+ * `dynamic-workflow-ctx.type-test.ts`), and a `Pick` of it is a plain object literal in a test.
+ */
+interface DynamicWorkflowCtx<A extends SearchAttributes = SearchAttributes> extends Omit<WorkflowCtx<A>, 'step' | 'child' | 'startChild' | 'all'> {
+    /** {@link WorkflowCtx.step} by step name (a cross-runtime handler, or a `@Step` by its name). */
+    step<TOutput = unknown, TInput = unknown>(name: string, input: TInput, opts?: StepDispatchOpts & {
+        compensate?: string;
+    }): Promise<TOutput>;
+    /** {@link WorkflowCtx.child} by workflow name. */
+    child<TOutput = unknown>(workflow: string, input: unknown, options?: string | ChildCallOptions): Promise<TOutput>;
+    /** {@link WorkflowCtx.startChild} by workflow name. */
+    startChild(workflow: string, input: unknown, options?: string | ChildCallOptions): Promise<string>;
+    /** {@link WorkflowCtx.all} by workflow name. */
+    all<TOutput = unknown>(workflow: string, inputs: unknown[], opts?: {
+        mode?: 'waitAll' | 'failFast';
+    }): Promise<TOutput[]>;
+}
 /** Result of executing or resuming a workflow run. */
 interface RunResult {
     runId: string;
@@ -2490,6 +2619,60 @@ declare const CONTROL_FLOW_SIGNAL: unique symbol;
  */
 declare function isWorkflowControlFlowSignal(error: unknown): boolean;
 
+/**
+ * A start-time concurrency quota for ONE start: at most `limit` runs sharing `key` may be in flight
+ * (in `countStatuses`) at once; a start that would exceed it is rejected with
+ * {@link ConcurrencyLimitError} before any run is created.
+ *
+ * The key is global — not per workflow — so different workflows started with the same key share the
+ * quota (e.g. `tenant:acme` capping every kind of run a tenant can have executing). Passed per start
+ * as `StartOptions.concurrency`, or derived from the input by a workflow's {@link ConcurrencyConfig}.
+ */
+interface ConcurrencyQuota {
+    /** The quota bucket, e.g. `tenant:acme`. Stamped on the run as the tag `concurrency:<key>`. */
+    key: string;
+    /** Max runs of this key in flight at once. `limit <= 0` rejects every start. */
+    limit: number;
+    /**
+     * Which statuses occupy a slot. Default: every non-terminal status
+     * ({@link DEFAULT_CONCURRENCY_STATUSES}). Narrow it to e.g. `['pending', 'running']` so runs parked
+     * on a human (`suspended`) stop counting against the quota.
+     */
+    countStatuses?: RunStatus[] | undefined;
+}
+/**
+ * A workflow's standing concurrency quota, declared at registration (`register(..., { concurrency })`
+ * / `@Workflow({ concurrency })`): the key is derived from each start's input, and the limit may be a
+ * function of the key (per-tenant plans). A `StartOptions.concurrency` on one start overrides it.
+ */
+interface ConcurrencyConfig {
+    /** Derive the quota key from the input. Return `undefined` to leave this start unlimited. */
+    key: (input: unknown) => string | undefined;
+    /** Max in-flight runs per key — a number, or resolved per key (e.g. from the tenant's plan). */
+    limit: number | ((key: string) => number | Promise<number>);
+    /** Which statuses occupy a slot. See {@link ConcurrencyQuota.countStatuses}. */
+    countStatuses?: RunStatus[] | undefined;
+}
+/** Every non-terminal status: what "in flight" means when a quota doesn't narrow it. */
+declare const DEFAULT_CONCURRENCY_STATUSES: readonly RunStatus[];
+/** The tag a quota-bearing run carries, so its siblings can be counted by one tag+status query. */
+declare function concurrencyTag(key: string): string;
+/** Resolve the quota that applies to one start: the per-start override, else the workflow's config. */
+declare function resolveConcurrency(override: ConcurrencyQuota | undefined, config: ConcurrencyConfig | undefined, input: unknown): Promise<ConcurrencyQuota | undefined>;
+/** Count the runs matching `query` as cheaply as the store allows (count → facets → listing). */
+declare function countRuns(store: StateStore, query: Omit<RunQuery, 'limit' | 'offset'>): Promise<number>;
+/**
+ * Reject a start that would exceed `quota`: counts the in-flight runs carrying the quota's tag and
+ * throws {@link ConcurrencyLimitError} once they reach the limit.
+ *
+ * A SOFT cap under a race: the count and the run's creation are separate statements, so N starts
+ * racing on the last free slot can each see it free (the same guarantee a hand-rolled
+ * `SELECT count(*)` gate gives). It is exact whenever starts for a key are not simultaneous, and the
+ * overshoot is bounded by the number of truly concurrent starts. Use `singleton` when you need a
+ * strict, queueing per-key limit instead of a rejecting one.
+ */
+declare function assertConcurrency(store: StateStore, workflow: string, quota: ConcurrencyQuota): Promise<void>;
+
 /**
  * Back-compat alias of {@link WorkflowCtx}. `localStep` — the checkpointed in-process step primitive
  * used for saga compensation — is now part of the public {@link WorkflowCtx}, so this type adds
@@ -3010,6 +3193,173 @@ type RoutingResolution = RoutableResolution | BlockedResolution;
  */
 declare function resolveRouting(handler: CapabilityRequirement, workers: readonly (RawWorkerDescriptor | WorkerDescriptor)[]): RoutingResolution;
 
+/**
+ * A schedule definition — what `engine.schedules.create/upsert` take. Temporal-style: a persisted,
+ * runtime-managed recurring start of `workflow` with `input`, fired by every driving engine's timer
+ * poll (safe with many workers: each window's run id is deterministic, `start` is idempotent, and
+ * advancing the schedule is a compare-and-set).
+ */
+interface ScheduleOptions {
+    /** Stable id, unique per store (e.g. `digest:user-42`). Part of every run id it starts. */
+    id: string;
+    /** The workflow to start — a registered name or `@Workflow` class. */
+    workflow: WorkflowRef;
+    /** The input every run starts with. */
+    input?: unknown;
+    /** Cron expression (5 fields, or 6 with leading seconds). Needs the `cron-parser` peer. */
+    cron?: string | undefined;
+    /** Fixed interval (`'15m'`, or ms), windows aligned to the epoch. Exclusive with `cron`. */
+    every?: string | number | undefined;
+    /** IANA timezone the cron is evaluated in (e.g. `America/Sao_Paulo`). Default UTC. */
+    timezone?: string | undefined;
+    /**
+     * Delay each fire by up to this much (`'30s'` or ms) — a stable per-(schedule, window) offset, so
+     * thousands of schedules on the same cron don't all start in the same second.
+     */
+    jitter?: string | number | undefined;
+    /**
+     * The previous run of this schedule is still in flight when the next window comes due:
+     * `'allow'` (default) starts the new one anyway; `'skip'` skips that window.
+     */
+    overlap?: 'allow' | 'skip' | undefined;
+    /**
+     * Windows missed while nothing polled (all schedulers down): `'latest'` (default) fires the most
+     * recent missed window once; `'skip'` drops them and waits for the next window. Never more than one
+     * catch-up run per schedule.
+     */
+    catchup?: 'latest' | 'skip' | undefined;
+    /** Create paused (never due until `resume`). On `upsert`, omit to keep the current paused state. */
+    paused?: boolean | undefined;
+    /** Free-form note shown with the schedule (why it exists / why it's paused). */
+    note?: string | undefined;
+    /** Namespace of the schedule and of the runs it starts. Defaults to the engine's own namespace. */
+    namespace?: string | undefined;
+    /** Labels to find the schedule by — also stamped on every run it starts (plus `schedule:<id>`). */
+    tags?: string[] | undefined;
+    /** Search attributes stamped on every run it starts. */
+    searchAttributes?: SearchAttributes | undefined;
+    /** Dispatch priority for the runs it starts. */
+    priority?: number | undefined;
+    /**
+     * A start-time concurrency quota applied to every run it starts (see `StartOptions.concurrency`):
+     * a window whose start would exceed it is recorded as the schedule's `lastError` and skipped, and
+     * the schedule moves on to its next window.
+     */
+    concurrency?: ConcurrencyQuota | undefined;
+}
+/** A schedule as `engine.schedules.get/list` describe it. */
+interface ScheduleDescription {
+    id: string;
+    workflow: string;
+    input: unknown;
+    namespace: string;
+    cron?: string | undefined;
+    everyMs?: number | undefined;
+    timezone?: string | undefined;
+    jitterMs?: number | undefined;
+    overlap: 'allow' | 'skip';
+    catchup: 'latest' | 'skip';
+    paused: boolean;
+    note?: string | undefined;
+    tags?: string[] | undefined;
+    searchAttributes?: SearchAttributes | undefined;
+    priority?: number | undefined;
+    concurrency?: ConcurrencyQuota | undefined;
+    /** When it is next due (jitter included), or null if it never fires again / paused. */
+    nextFireAt: Date | null;
+    /** The last window it fired for, and the run that window started. */
+    lastFireAt?: Date | undefined;
+    lastRunId?: string | undefined;
+    /** How many windows it has fired (manual triggers excluded). */
+    fires: number;
+    /** The last start failure (e.g. a concurrency limit), cleared by the next successful start. */
+    lastError?: string | undefined;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** Filter for `engine.schedules.list`. */
+type ScheduleListQuery = Omit<ScheduleQuery, 'dueBy'>;
+/** Thrown by `engine.schedules.create` when the id is taken (use `upsert` to replace). */
+declare class ScheduleAlreadyExistsError extends Error {
+    readonly scheduleId: string;
+    constructor(scheduleId: string);
+}
+/** Thrown by `engine.schedules.*` on an id that doesn't exist. */
+declare class ScheduleNotFoundError extends Error {
+    readonly scheduleId: string;
+    constructor(scheduleId: string);
+}
+/** The engine surface the schedule client drives. */
+interface ScheduleHost {
+    start(workflow: string, input: unknown, runId: string, opts?: StartOptions): Promise<RunResult>;
+    getRun(runId: string): Promise<WorkflowRun | null>;
+}
+/** Engine-level knobs for the client. */
+interface ScheduleClientOptions {
+    /** The engine's namespace: the default for new schedules, and which ones `tick` fires. */
+    namespace?: string | undefined;
+    clock?: (() => number) | undefined;
+}
+/**
+ * Persisted, runtime-managed schedules — `engine.schedules`. Unlike the code-registered
+ * `schedules` module option, these live in the store: create/update/pause/delete them at runtime
+ * (one per user, per tenant, per automation…), and every driving engine's timer poll fires the due
+ * ones via {@link tick}.
+ *
+ * Multi-worker safety comes from two properties, not from a lock: a window's run id is deterministic
+ * (`sched:<id>:<windowMs>`), so racing starts of the same window collapse into one run; and a
+ * schedule is advanced with a compare-and-set on its `nextFireAt`, so exactly one poller moves it on.
+ * A crash between starting the run and advancing the schedule just re-fires the (idempotent) start.
+ */
+declare class ScheduleClient {
+    private readonly store;
+    private readonly host;
+    private readonly options;
+    constructor(store: StateStore, host: ScheduleHost, options?: ScheduleClientOptions);
+    private now;
+    /** Whether the store persists schedules (implements the schedule methods). */
+    get supported(): boolean;
+    private requireStore;
+    /** Create a schedule. Throws {@link ScheduleAlreadyExistsError} if the id is taken. */
+    create(opts: ScheduleOptions): Promise<ScheduleDescription>;
+    /**
+     * 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.
+     */
+    upsert(opts: ScheduleOptions): Promise<ScheduleDescription>;
+    /** The schedule `id`, or null. */
+    get(id: string): Promise<ScheduleDescription | null>;
+    /** Schedules matching `query`, soonest-due first. */
+    list(query?: ScheduleListQuery): Promise<ScheduleDescription[]>;
+    /** Delete the schedule. Runs it already started are left alone. Returns whether it existed. */
+    delete(id: string): Promise<boolean>;
+    /** Stop firing until {@link resume}. `note` records why (shown by `get`/`list`). */
+    pause(id: string, note?: string): Promise<ScheduleDescription>;
+    /**
+     * Fire again from the next window after now — the windows skipped while paused are NOT caught up.
+     */
+    resume(id: string): Promise<ScheduleDescription>;
+    /**
+     * 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.
+     */
+    trigger(id: string): Promise<RunResult>;
+    /**
+     * 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).
+     */
+    tick(nowMs?: number): Promise<string[]>;
+    /** Fire one due schedule and advance it. Returns the run id started, if any. */
+    private fire;
+    /** `overlap: 'skip'` and the previous run of this schedule is still in flight. */
+    private overlapping;
+    private mustGet;
+    private write;
+}
+
 type WorkflowFn = (ctx: InternalWorkflowCtx, input: unknown) => Promise<unknown>;
 /**
  * Options for {@link WorkflowEngine.start}.
@@ -3055,6 +3405,12 @@ interface StartOptions {
      * maps here), so one DB-less-tenant-facing engine can create runs across many namespaces.
      */
     namespace?: string | undefined;
+    /**
+     * A start-time concurrency quota for this start — at most `limit` runs sharing `key` in flight;
+     * over it, `start` throws {@link ConcurrencyLimitError} and creates nothing. Overrides the
+     * workflow's registered `concurrency`. See {@link ConcurrencyQuota}.
+     */
+    concurrency?: ConcurrencyQuota | undefined;
 }
 /**
  * Serialize runs of a workflow that share a key — a durable, FIFO mutex (e.g. one pipeline per base).
@@ -3305,6 +3661,12 @@ declare class WorkflowEngine {
     private readonly runDispatcher;
     /** Per-key serialization for singleton workflows (admission, back-pressure, notify-on-release). */
     private readonly 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}.
+     */
+    readonly schedules: ScheduleClient;
     /** Every registered workflow, keyed by `name@version` — so old versions stay runnable. */
     private readonly workflows;
     /** The newest registered version per workflow name — used to `start` new runs. */
@@ -3380,6 +3742,8 @@ declare class WorkflowEngine {
     register(name: string, version: string, fn: WorkflowFn, opts?: {
         tags?: string[] | undefined;
         singleton?: SingletonConfig | undefined;
+        /** Start-time concurrency quota — see {@link ConcurrencyConfig}. */
+        concurrency?: ConcurrencyConfig | undefined;
         executionTimeout?: string | number | undefined;
         validateInput?: ((input: unknown) => void | Promise<void>) | undefined;
         /** Typed/validated `searchAttributes` shape — see `RegisteredWorkflow.searchAttributesSchema`. */
@@ -3426,6 +3790,7 @@ declare class WorkflowEngine {
         executor: WorkflowExecutor;
         tags?: string[];
         singleton?: SingletonConfig;
+        concurrency?: ConcurrencyConfig;
         executionTimeout?: string | number;
         validateInput?: (input: unknown) => void | Promise<void>;
         /** Capabilities a live worker must advertise to run this remote workflow's turns (handshake §7.5). */
@@ -3451,6 +3816,7 @@ declare class WorkflowEngine {
         version?: string;
         tags?: string[];
         singleton?: SingletonConfig;
+        concurrency?: ConcurrencyConfig;
         executionTimeout?: string | number;
         validateInput?: (input: unknown) => void | Promise<void>;
         /** Capabilities a live worker must advertise to run this workflow's turns (handshake §7.5). */
@@ -3878,6 +4244,43 @@ declare class WorkflowEngine {
      * its worker (its next checkpoint write fails). Returns the number of runs deleted (0 if absent).
      */
     deleteRun(runId: string): Promise<number>;
+    /**
+     * 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).
+     */
+    purgeRuns(scope: RunScope, opts?: {
+        batchSize?: number;
+        cancelLive?: boolean;
+        children?: boolean;
+    }): Promise<number>;
+    /**
+     * {@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: string, opts?: {
+        batchSize?: number;
+        cancelLive?: boolean;
+    }): Promise<number>;
+    /** The given runs plus every descendant, children before parents. One waiter scan for the batch. */
+    private collectSubtrees;
+    /** Bulk-delete through the store's `deleteRuns`, or one `deleteRun` per id when it has none. */
+    private deleteRunIds;
     /**
      * 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>`
@@ -4400,6 +4803,19 @@ declare class FatalError extends Error {
     readonly code?: string | undefined;
     constructor(message: string, code?: string);
 }
+/**
+ * Thrown by `start` when a run would exceed its concurrency quota: `active` runs sharing the quota
+ * `key` are already in flight (in the quota's counted statuses) and the `limit` is `limit`. Nothing
+ * was created — the start is rejected up front, so the caller can shed load or answer "try again in a
+ * moment" (e.g. map it to HTTP 429). See `StartOptions.concurrency` / `ConcurrencyConfig`.
+ */
+declare class ConcurrencyLimitError extends Error {
+    readonly workflow: string;
+    readonly key: string;
+    readonly limit: number;
+    readonly active: number;
+    constructor(workflow: string, key: string, limit: number, active: number);
+}
 /**
  * Thrown by `start` when a singleton workflow's wait queue is full: the count of in-flight + gated
  * runs sharing the key already equals `limit + maxQueueDepth`, so admitting another would let the
@@ -4660,7 +5076,7 @@ declare const RUN_VALUE_FACET_SCAN = 5000;
  * sets exactly that), so it stays offered — just after the tags a human wrote. `version:undeclared`
  * is engine-minted too but is a single fixed value, so it competes fairly and is not listed here.
  */
-declare const ENGINE_MINTED_TAG_PREFIXES: readonly ["singleton:"];
+declare const ENGINE_MINTED_TAG_PREFIXES: readonly ["singleton:", "concurrency:"];
 /** Is this a tag the engine mints one of per key? See {@link ENGINE_MINTED_TAG_PREFIXES}. */
 declare function isEngineMintedTag(value: string | null): boolean;
 /**
@@ -4863,6 +5279,22 @@ declare class CodecStateStore implements StateStore {
      * Bound the same conditional way as {@link runFacets} so absence is reported, not faked.
      */
     readonly runValueFacets?: (axis: RunValueAxis, query: RunFacetQuery, opts?: RunValueFacetOptions) => Promise<RunValueFacetRow[]>;
+    /** 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. */
+    readonly deleteRuns?: (runIds: string[]) => Promise<void>;
+    /** 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. */
+    readonly pruneTerminalRuns?: (policy: RetentionPolicy, nowMs: number, limit: number) => Promise<number>;
+    /** 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. */
+    readonly countRuns?: (query: Omit<RunQuery, 'limit' | 'offset'>) => Promise<number>;
+    /** 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. */
+    readonly saveSchedule?: (record: ScheduleRecord) => Promise<void>;
+    readonly getSchedule?: (id: string) => Promise<ScheduleRecord | null>;
+    readonly updateSchedule?: (id: string, patch: Partial<Omit<ScheduleRecord, 'id' | 'createdAt'>>, expectedNextFireAt?: number | null) => Promise<boolean>;
+    readonly deleteSchedule?: (id: string) => Promise<boolean>;
+    readonly listSchedules?: (query: ScheduleQuery) => Promise<ScheduleRecord[]>;
     constructor(inner: StateStore, codec: PayloadCodec);
     private enc;
     private dec;
@@ -4870,6 +5302,9 @@ declare class CodecStateStore implements StateStore {
     private decRun;
     private encCp;
     private decCp;
+    private encSpec;
+    private encSchedule;
+    private decSchedule;
     ensureSchema(): Promise<void>;
     createRun(run: WorkflowRun): Promise<void>;
     updateRun(runId: string, patch: Partial<WorkflowRun>): Promise<void>;
@@ -5039,6 +5474,12 @@ declare function scheduledRunId(key: string, everyMs: number, nowMs: number): st
  * interval resolves to the same fire time — and thus the same idempotent run id.
  */
 declare function prevCronFireMs(expr: string, nowMs: number, timezone?: string): number;
+/**
+ * Epoch ms of the first cron fire STRICTLY after `afterMs`, evaluated in `timezone` (default UTC) —
+ * the forward counterpart of {@link prevCronFireMs}, used by persisted schedules to compute when a
+ * schedule is next due.
+ */
+declare function nextCronFireMs(expr: string, afterMs: 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
@@ -5297,6 +5738,8 @@ declare class InMemoryStateStore implements StateStore {
     updateRun(runId: string, patch: Partial<WorkflowRun>): Promise<void>;
     getRun(runId: string): Promise<WorkflowRun | null>;
     deleteRun(runId: string): Promise<void>;
+    deleteRuns(runIds: string[]): Promise<void>;
+    pruneTerminalRuns(policy: RetentionPolicy, nowMs: number, limit: number): Promise<number>;
     getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
     saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
     listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
@@ -5343,11 +5786,18 @@ declare class InMemoryStateStore implements StateStore {
      *  {@link listRuns} (which then sorts + pages it) and {@link runFacets} (which groups it). */
     private matching;
     listRuns(query: RunQuery): Promise<WorkflowRun[]>;
+    countRuns(query: Omit<RunQuery, 'limit' | 'offset'>): Promise<number>;
     runFacets(query: RunFacetQuery): Promise<RunFacetRow[]>;
     /** Counted over the newest `scan` matching runs for EVERY axis, not just `tag`: this store holds
      *  its runs in a Map with no index to group by, so the bound that the SQL stores need only for tags
      *  is the honest one to apply here throughout. */
     runValueFacets(axis: RunValueAxis, query: RunFacetQuery, opts?: RunValueFacetOptions): Promise<RunValueFacetRow[]>;
+    private readonly schedules;
+    saveSchedule(record: ScheduleRecord): Promise<void>;
+    getSchedule(id: string): Promise<ScheduleRecord | null>;
+    updateSchedule(id: string, patch: Partial<Omit<ScheduleRecord, 'id' | 'createdAt'>>, expectedNextFireAt?: number | null): Promise<boolean>;
+    deleteSchedule(id: string): Promise<boolean>;
+    listSchedules(query: ScheduleQuery): Promise<ScheduleRecord[]>;
     listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
     getLatestCheckpointByName(runId: string, name: string): Promise<StepCheckpoint | undefined>;
     listCheckpointsByNamePrefix(runId: string, prefixes: string[]): Promise<StepCheckpoint[]>;
@@ -5379,4 +5829,4 @@ declare class InMemoryTransport implements Transport, ControlPlane {
     onControl(handler: (msg: ControlMessage) => void): void;
 }
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, CONTROL_FLOW_SIGNAL, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_PARTITION, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type Disagreement, type DispatchDiagnostics, type DispatchPlan, type DurableExecution, type DurableExecutionWrapper, type DurableTopology, type DurableWebhook, DurableWorkflow, ENGINE_MINTED_TAG_PREFIXES, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HeartbeatSighting, type HeartbeatStatus, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, LEGACY_V1_CAPABILITIES, LEGACY_V1_PROTOCOL, type MetricsCollector, type MetricsSnapshot, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NonDeterminismError, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, RUN_VALUE_FACET_LIMIT, RUN_VALUE_FACET_SCAN, type RawWorkerDescriptor, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RoutableDispatch, type RoutableResolution, type RoutingResolution, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunFacetQuery, type RunFacetRow, RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, type RunValueAxis, type RunValueFacetOptions, type RunValueFacetOrder, type RunValueFacetRow, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, type ScalarAttributeFilter, type ScheduledWorkflow, type SearchAttributes, type SearchAttributesSchema, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, StandardSchemaV1, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, VERSION_UNDECLARED_TAG, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerDescriptor, type WorkerHeartbeat, type WorkerLifecycle, type WorkerStatus, type WorkflowAnnouncement, WorkflowBlocked, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, type WorkflowDirectory, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRegistration, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, aggregateAnnouncements, announcementsOf, applyAttributeQuery, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, classifyWaiterToken, clearDurableExecutionWrappers, collectMetrics, controlPlaneDescriptor, coveredTokens, createStepLogger, currentStep, currentWorkflowCtx, debug, describeWorker, descriptorHash, error, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, facetOrigin, hasDurableExecutionWrappers, heartbeatStatus, indexWaitersByRun, info, isEngineMintedTag, isEventToken, isLegacyDescriptor, isWorkflowControlFlowSignal, log, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, parseDuration, partitionOfToken, planDispatch, prevCronFireMs, readSearchAttributes, requiredCapabilities, resolveRouting, resolveRunWaiting, runDurableExecution, runInStepLogger, runInWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, tenantGroup, useDurableExecution, warn, workflowName };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, CONTROL_FLOW_SIGNAL, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type ChildCallOptions, CodecStateStore, type ConcurrencyConfig, ConcurrencyLimitError, type ConcurrencyQuota, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_CONCURRENCY_STATUSES, DEFAULT_PARTITION, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type Disagreement, type DispatchDiagnostics, type DispatchPlan, type DurableExecution, type DurableExecutionWrapper, type DurableTopology, type DurableWebhook, DurableWorkflow, type DynamicWorkflowCtx, ENGINE_MINTED_TAG_PREFIXES, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HeartbeatSighting, type HeartbeatStatus, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, LEGACY_V1_CAPABILITIES, LEGACY_V1_PROTOCOL, type MetricsCollector, type MetricsSnapshot, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NonDeterminismError, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, RUN_VALUE_FACET_LIMIT, RUN_VALUE_FACET_SCAN, type RawWorkerDescriptor, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RoutableDispatch, type RoutableResolution, type RoutingResolution, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunFacetQuery, type RunFacetRow, RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunScope, type RunStatus, type RunValueAxis, type RunValueFacetOptions, type RunValueFacetOrder, type RunValueFacetRow, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, type ScalarAttributeFilter, ScheduleAlreadyExistsError, ScheduleClient, type ScheduleClientOptions, type ScheduleDescription, type ScheduleHost, type ScheduleListQuery, ScheduleNotFoundError, type ScheduleOptions, type ScheduleQuery, type ScheduleRecord, type ScheduledWorkflow, type SearchAttributes, type SearchAttributesSchema, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, StandardSchemaV1, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, VERSION_UNDECLARED_TAG, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerDescriptor, type WorkerHeartbeat, type WorkerLifecycle, type WorkerStatus, type WorkflowAnnouncement, WorkflowBlocked, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, type WorkflowDirectory, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRegistration, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, aggregateAnnouncements, announcementsOf, applyAttributeQuery, assertConcurrency, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, classifyWaiterToken, clearDurableExecutionWrappers, collectMetrics, concurrencyTag, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentWorkflowCtx, debug, describeWorker, descriptorHash, error, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, facetOrigin, hasDurableExecutionWrappers, heartbeatStatus, indexWaitersByRun, info, isEngineMintedTag, isEventToken, isLegacyDescriptor, isNonEmptyRunScope, isWorkflowControlFlowSignal, log, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, parseDuration, partitionOfToken, planDispatch, prevCronFireMs, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, runDurableExecution, runInStepLogger, runInWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, tenantGroup, useDurableExecution, warn, workflowName };