@dudousxd/nestjs-durable-core 0.101.0 → 0.102.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -266,6 +266,41 @@ interface WorkflowRegistration {
266
266
  * nothing.
267
267
  */
268
268
  subscribes?: string[];
269
+ /**
270
+ * The `@Workflow` options a control plane applies to this workflow when it serves it by convention
271
+ * (it knows a tenant's workflow by name alone). Only the data options travel: the ones that are
272
+ * functions of the input (a singleton or concurrency `key`, an input schema, `validateInput`) are
273
+ * evaluated by the starting app and carried on its start-run (see `StartRunMessage.singleton`).
274
+ * Absent = not stated, which applies nothing (the behaviour before this field).
275
+ */
276
+ options?: AnnouncedWorkflowOptions;
277
+ /**
278
+ * The workflow this workflow's dead-lettered runs are routed to: an inline `@DeadLetter()` handler
279
+ * (`<name>.dlq`, served by the same worker), a `deadLetterWorkflow` reference, or the app's
280
+ * module-level default. A control plane serving the workflow by convention starts it, in the dead
281
+ * run's namespace, when no dead-letter route of its own applies. Absent = not stated.
282
+ */
283
+ deadLetter?: string;
284
+ }
285
+ /**
286
+ * The JSON-safe `@Workflow` options a worker announces for a workflow (see
287
+ * {@link WorkflowRegistration.options}). Every field is optional and means "not stated" when absent.
288
+ */
289
+ interface AnnouncedWorkflowOptions {
290
+ /** Static tags stamped on every run, merged with the start's own tags. */
291
+ tags?: string[];
292
+ /** Max wall-clock lifetime of a run, in ms (`@Workflow({ executionTimeout })`). */
293
+ executionTimeoutMs?: number;
294
+ /**
295
+ * The workflow is a singleton (`@Workflow({ singleton })`): its runs that share a key are admitted
296
+ * at most `limit` (default 1) at a time. The key is a function of the input, so the starter computes
297
+ * it and the run carries it as its `singleton:<key>` tag; this states the limit the control plane
298
+ * admits against on every turn.
299
+ */
300
+ singleton?: {
301
+ limit?: number;
302
+ maxQueueDepth?: number;
303
+ };
269
304
  }
270
305
  /**
271
306
  * One recurring start a tenant app declares (its `schedules` module option), as its worker
@@ -291,6 +326,16 @@ interface AnnouncedSchedule {
291
326
  overlap?: 'allow' | 'skip';
292
327
  /** Delay each fire by a stable offset of up to this many ms. */
293
328
  jitterMs?: number;
329
+ /**
330
+ * The workflow's `@Workflow({ singleton })` key, evaluated by the app against this schedule's
331
+ * `input` (a key is a function of the input, which the control plane cannot run). Its fires are
332
+ * serialized with the app's other runs of that key. Absent = not a singleton.
333
+ */
334
+ singleton?: {
335
+ key: string;
336
+ limit?: number;
337
+ maxQueueDepth?: number;
338
+ };
294
339
  }
295
340
  /**
296
341
  * The schedules a tenant worker announces, and the wire tenant they belong to: the partition, or
@@ -964,69 +1009,6 @@ declare function fanPageBounds(query: FanPageQuery): {
964
1009
  limit: number;
965
1010
  };
966
1011
 
967
- /**
968
- * One end of a `ctx.waitForRun` wait, as a run detail lists it: the run waited for (`waitsFor`) or
969
- * the waiting run (`awaitedBy`), the waiting run's `seq` of the call, and the other run's status and
970
- * namespace when it was read.
971
- */
972
- interface RunWaitLink {
973
- runId: string;
974
- seq: number;
975
- status?: RunStatus | undefined;
976
- namespace?: string | undefined;
977
- }
978
- /**
979
- * Where a settled run's lifecycle event stands for one subscriber:
980
- * - `started`: its run exists (`runId`, a `durable:triggered:<subscriber>` tag);
981
- * - `owed`: still pending (a `durable:lifecycle:owed:<subscriber>` tag);
982
- * - `coalesced`: routed into a debounce/batch accumulator (a `durable:coalesced:<subscriber>` tag,
983
- * or the caller's `coalesced` map; `runId` is the accumulator's, when it can be derived);
984
- * - `failed`: its start failed (a `durable:trigger_failed:<subscriber>` tag): its `where` threw, its
985
- * input was rejected, its start threw, or the sweep dropped it as orphaned. A republish retries it;
986
- * - `not-started`: no run and nothing owed: its `where` declined the event, or it subscribed after
987
- * the run settled.
988
- */
989
- type LifecycleDeliveryState = 'started' | 'owed' | 'coalesced' | 'failed' | 'not-started';
990
- /** One subscriber of a settled run's lifecycle event, as the run detail lists it. */
991
- interface LifecycleDelivery {
992
- subscriber: string;
993
- state: LifecycleDeliveryState;
994
- /** The subscriber's run when `started`; the accumulator run when `coalesced` and derivable. */
995
- runId?: string | undefined;
996
- /** The status of a `started` subscriber's run, when it was read. */
997
- status?: RunStatus | undefined;
998
- /** The namespace of a `started` subscriber's run, when it was read. */
999
- namespace?: string | undefined;
1000
- /** When an `owed` subscriber became owed: the settled run's last update (epoch ms). */
1001
- owedSince?: number | undefined;
1002
- /**
1003
- * When the lifecycle sweep drops an `owed` subscriber that no live instance registers or
1004
- * announces for the run's namespace (epoch ms; see {@link LIFECYCLE_ORPHAN_MS}). Absent while one
1005
- * does.
1006
- */
1007
- orphanAt?: number | undefined;
1008
- /**
1009
- * Why a `failed` subscriber did not start, when the caller knows it (the run's tags record only
1010
- * that it failed; the `run.trigger_failed` event carries the message). {@link lifecycleDeliveriesOf}
1011
- * leaves it unset.
1012
- */
1013
- error?: string | undefined;
1014
- }
1015
- /**
1016
- * The {@link LifecycleDelivery} of each subscriber of a settled run, sorted by subscriber: the
1017
- * union of `subscribers` (the ones the run's event goes to now) and the owed, triggered, coalesced
1018
- * and trigger-failed tags. `live` names the subscribers a live instance registers or announces; an owed subscriber
1019
- * outside it gets `orphanAt`. `coalesced` maps each subscriber that coalesces its events to its
1020
- * accumulator run id (undefined when it cannot be derived). Empty for a run that has not settled.
1021
- */
1022
- declare function lifecycleDeliveriesOf(run: Pick<WorkflowRun, 'id' | 'status' | 'tags' | 'updatedAt'>, opts: {
1023
- subscribers: readonly string[];
1024
- live: ReadonlySet<string>;
1025
- coalesced?: ReadonlyMap<string, string | undefined> | undefined;
1026
- }): LifecycleDelivery[];
1027
- /** The trace id of a W3C `traceparent` (`00-<trace id>-<span id>-<flags>`), or undefined. */
1028
- declare function traceIdOfTraceparent(traceparent: string | undefined): string | undefined;
1029
-
1030
1012
  /**
1031
1013
  * One loaded copy of this package: its version and the real path of its package root. Two copies are
1032
1014
  * the same when their roots are, so the `src` and `dist` builds of one checkout, the ESM and CJS
@@ -1868,502 +1850,778 @@ declare function codeAndDetails(err: unknown): {
1868
1850
  details?: unknown;
1869
1851
  };
1870
1852
 
1871
- /** Default idle threshold for a stranded run: 15 minutes. */
1872
- declare const DEFAULT_STALLED_AFTER_MS: number;
1873
- /** The oldest unresolved remote step of a run — the lost-dispatch signature when it is old. */
1874
- interface StalePendingStep {
1875
- seq: number;
1876
- name: string;
1877
- /** How many times this step has been (re-)dispatched. A lost dispatch typically sits at 1. */
1878
- attempts: number;
1879
- /** Milliseconds since the step was enqueued to the transport. */
1880
- ageMs: number;
1881
- /**
1882
- * The step's lease (`wakeAt`, epoch ms) when it has one: a step with a `timeoutMs`, a heartbeat
1883
- * renewing it, or `remoteRedispatchMs`. `null` when nothing is leasing the step.
1884
- */
1885
- leaseUntil: number | null;
1886
- }
1887
- /** What an `engine.onStalled` listener (and {@link findStalledRuns}) receives: a stranded run and why. */
1888
- interface StalledRunInfo {
1889
- run: WorkflowRun;
1890
- /** Milliseconds since the run's last activity (`updatedAt`). */
1891
- ageMs: number;
1892
- /** Suspended with NO wake timer — nothing will re-drive it (the `reconcileMs: 0` hazard). */
1893
- wakeForever: boolean;
1894
- /** The oldest pending remote step with no live lease, when that is the stranding signature. */
1895
- stalePending: StalePendingStep | null;
1896
- }
1897
- /** Options for {@link findStalledRuns}. */
1898
- interface FindStalledRunsOptions {
1899
- /** Idle threshold in ms. Default {@link DEFAULT_STALLED_AFTER_MS}. */
1900
- thresholdMs?: number | undefined;
1901
- /** Max candidate runs inspected (newest first). Default 1000. */
1902
- scan?: number | undefined;
1903
- /** Evaluate as of this time (epoch ms). Default `Date.now()`. */
1904
- now?: number | undefined;
1905
- /** Only runs in this namespace. Omit for every namespace. */
1906
- namespace?: string | undefined;
1907
- }
1908
- /**
1909
- * The stranded runs in a store right now — the query behind `engine.sweepStalled`/`onStalled`,
1910
- * `engine.listStalledRuns` and the CLI's `durable inspect --stale`. Works on a bare store, so an
1911
- * ops script or a CLI can run it without an engine.
1912
- *
1913
- * A `running`/`suspended` run qualifies when it has been untouched for `thresholdMs` AND either:
1914
- *
1915
- * - it is suspended with NO wake timer (`wakeForever`): nothing will ever re-drive it; or
1916
- * - its oldest pending REMOTE step is older than the threshold and has no lease in the future
1917
- * (`stalePending`): the dispatch was most likely lost.
1918
- *
1919
- * Healthy long work is excluded: a long `ctx.sleep` has a future `wakeAt` and no pending step, and a
1920
- * remote step with a `timeoutMs`, a heartbeat or `remoteRedispatchMs` carries a future lease. Issues
1921
- * one `listCheckpoints` per idle candidate, bounded by `scan`: an operator read, not a hot path.
1922
- */
1923
- declare function findStalledRuns(store: Pick<StateStore, 'listRuns' | 'listCheckpoints'>, options?: FindStalledRunsOptions): Promise<StalledRunInfo[]>;
1924
-
1925
1853
  /**
1926
- * Layered tenant auth for the store-less cluster. On a tenant worker the `tenant` on a
1927
- * {@link import('./interfaces').RunRequest} / {@link import('./interfaces').StartRunMessage} is only
1928
- * a CLAIM: without a signed proof, any broker client can act as any tenant. This module is the
1929
- * default defense in depth on top of prefix/network isolation: a symmetric HMAC token the tenant
1930
- * worker presents IN the existing `tenant` wire field, which the operator's {@link TenantVerifier}
1931
- * checks and DERIVES the real tenant from, never trusting the body.
1932
- *
1933
- * Wire-compatible with Agora (`@adonis-agora/durable`) byte for byte: the token is
1934
- * `<claim>.<base64url(HMAC-SHA256(secret, claim))>`, where `claim` is the tenant name, optionally
1935
- * followed by `.exp<epochMs>`. It fits the `tenant: string` field with NO envelope change, so an
1936
- * operator that does not verify simply treats the whole string as the tenant name (and finds no
1937
- * runs, a safe failure), while an operator configured with {@link hmacTenantVerifier} verifies the
1938
- * signature and scopes to the embedded tenant. Agora and Aviary tokens are interchangeable.
1939
- *
1940
- * HMAC (shared secret) is the zero-infra default; a deployment that prefers asymmetric or issued
1941
- * tokens supplies its own {@link TenantVerifier} instead.
1854
+ * A schedule definition — what `engine.schedules.create/upsert` take. Temporal-style: a persisted,
1855
+ * runtime-managed recurring start of `workflow` with `input`, fired by every driving engine's timer
1856
+ * poll (safe with many workers: each window's run id is deterministic, `start` is idempotent, and
1857
+ * advancing the schedule is a compare-and-set).
1942
1858
  */
1943
- /** The identity a {@link TenantVerifier} derives from a tenant's signed claim. */
1944
- interface VerifiedTenant {
1945
- /** The tenant the token authenticates as. The responder trusts THIS, never the request body. */
1946
- tenant: string;
1859
+ interface ScheduleOptions {
1860
+ /** Stable id, unique per store (e.g. `digest:user-42`). Part of every run id it starts. */
1861
+ id: string;
1862
+ /** The workflow to start — a registered name or `@Workflow` class. */
1863
+ workflow: WorkflowRef;
1864
+ /** The input every run starts with. */
1865
+ input?: unknown;
1866
+ /** Cron expression (5 fields, or 6 with leading seconds). Needs the `cron-parser` peer. */
1867
+ cron?: string | undefined;
1868
+ /** Fixed interval (`'15m'`, or ms), windows aligned to the epoch. Exclusive with `cron`. */
1869
+ every?: string | number | undefined;
1947
1870
  /**
1948
- * Capabilities the token grants, if the issuer scopes them. `tenancy:*` or `tenancy:<id>` lets the
1949
- * process claim that customer tenant for the runs it starts (see `StartRunMessage.tenantId`). The
1950
- * run-request responder does not enforce them: a verified tenant can call every verb, scoped to
1951
- * its own namespace.
1871
+ * An RFC 5545 recurrence rule (`'FREQ=WEEKLY;BYDAY=MO;BYHOUR=8'`, optionally with a
1872
+ * `DTSTART:…` line), evaluated in `timezone`. Exactly one of `cron`, `every` and `rrule`. See
1873
+ * {@link parseRRule} for the supported parts. No peer needed.
1952
1874
  */
1953
- capabilities?: string[] | undefined;
1954
- }
1955
- /**
1956
- * Verifies a tenant's signed claim on the **operator** side, returning the {@link VerifiedTenant} it
1957
- * authenticates as, or `null` (or throwing) to reject a tampered/invalid/absent token. The signed
1958
- * token travels in the wire `tenant` field, so the responder passes that value as both `token` and
1959
- * the advisory `tenant`.
1960
- */
1961
- type TenantVerifier = (input: {
1962
- /** The signed token presented on the request. */
1963
- token?: string | undefined;
1964
- /** The tenant the request *claims* to be. Advisory only: the verifier derives the real one. */
1965
- tenant?: string | undefined;
1966
- }) => VerifiedTenant | null | Promise<VerifiedTenant | null>;
1967
- /**
1968
- * Where the tenant side gets the token it presents: a static string, or a function called before
1969
- * every request (so a short-lived token from {@link signTenantToken} with `ttlMs` can be re-minted
1970
- * or fetched from a secret store without restarting the worker).
1971
- */
1972
- type TenantTokenSource = string | (() => string | Promise<string>);
1973
- /**
1974
- * Mint the signed token a tenant worker presents:
1975
- * `` `${tenant}.${base64url(HMAC-SHA256(secret, tenant))}` ``. The worker carries only the token
1976
- * (never the secret); the operator verifies it with the SAME `secret` via {@link hmacTenantVerifier}.
1977
- */
1978
- declare function signTenantToken(tenant: string, secret: string, opts?: {
1875
+ rrule?: string | undefined;
1876
+ /** IANA timezone the cron / rrule is evaluated in (e.g. `America/Sao_Paulo`). Default UTC. */
1877
+ timezone?: string | undefined;
1979
1878
  /**
1980
- * Optional lifetime: the claim gains a `.exp<epochMs>` suffix, signed together with the tenant,
1981
- * and {@link hmacTenantVerifier} rejects the token once that instant passes. Without it the
1982
- * token never expires. Expiring and non-expiring tokens verify side by side. Tenant names
1983
- * ending in `.exp<digits>` are reserved by this scheme.
1879
+ * Delay each fire by up to this much (`'30s'` or ms) — a stable per-(schedule, window) offset, so
1880
+ * thousands of schedules on the same cron don't all start in the same second.
1984
1881
  */
1985
- ttlMs?: number;
1986
- /** Injectable clock for tests. */
1987
- now?: number;
1988
- }): string;
1989
- /**
1990
- * Build the operator-side {@link TenantVerifier} for {@link signTenantToken} tokens under `secret`.
1991
- * It recomputes the HMAC over the embedded claim and compares it in constant time, so a tampered
1992
- * tenant, a forged/absent signature, a token signed with another secret, or an expired token all
1993
- * return `null`. The tenant is DERIVED from the token's own claim.
1994
- *
1995
- * A LIST of secrets makes rotation a two-step deploy: verify with `[next, current]` everywhere first,
1996
- * then re-mint tenant tokens with `next` at leisure. `capabilities`, if given, is a static grant
1997
- * stamped onto every {@link VerifiedTenant} this verifier authenticates (informational: the
1998
- * responder does not enforce it yet, see {@link VerifiedTenant.capabilities}).
1999
- */
2000
- declare function hmacTenantVerifier(secret: string | string[], capabilities?: string[]): TenantVerifier;
2001
- /**
2002
- * Verify a wire message's `tenant`: with a verifier, the {@link VerifiedTenant} it derives (`null` on
2003
- * reject); without one, the wire value trusted verbatim, with no capabilities.
2004
- */
2005
- declare function verifyWireTenant(wireTenant: string, verifyTenant: TenantVerifier | undefined): Promise<VerifiedTenant | null>;
2006
- /**
2007
- * Whether a verified tenant process may claim the customer `tenantId` for a run it starts: its
2008
- * `capabilities` hold `tenancy:*` (any customer) or `tenancy:<tenantId>`. An unverified process (no
2009
- * verifier) holds none, so it never may.
2010
- */
2011
- declare function grantsClientTenant(verified: VerifiedTenant | null, tenantId: string): boolean;
2012
- /**
2013
- * Resolve the tenant a wire message is ALLOWED to act as. With a verifier, the wire `tenant` is the
2014
- * signed token: it is verified and the real tenant derived from it (`null` on reject). Without one,
2015
- * the wire value is trusted verbatim (prefix/network isolation only, today's behaviour).
2016
- */
2017
- declare function resolveWireTenant(wireTenant: string, verifyTenant: TenantVerifier | undefined): Promise<string | null>;
2018
- /** Resolve a {@link TenantTokenSource} to the token string to put on the wire. */
2019
- declare function resolveTenantToken(source: TenantTokenSource): Promise<string>;
2020
-
2021
- type WorkflowFn = (ctx: WorkflowCtx, input: unknown) => Promise<unknown>;
2022
- /**
2023
- * Options for {@link WorkflowEngine.start}.
2024
- *
2025
- * Note the absence of `origin`: {@link WorkflowRun.origin} says which PACKAGE declared the workflow,
2026
- * which is a property of the registered code, not of whoever started it. It is taken from the
2027
- * registration and nothing here can override it — otherwise one caller could label its runs as
2028
- * another lib's, and an origin filter would quietly lie.
2029
- */
2030
- interface StartOptions {
1882
+ jitter?: string | number | undefined;
2031
1883
  /**
2032
- * Start THIS registered version instead of the newest one. Omit (the default) and the run starts on
2033
- * the newest registered version, exactly as it always has — this option only ever narrows.
2034
- *
2035
- * Resolved against the by-name@version registry, so it pins anything explicitly registered:
2036
- * {@link WorkflowEngine.register}, {@link WorkflowEngine.registerRemote}, {@link WorkflowEngine.remote}.
2037
- * A version that is NOT registered throws before a run row is created and NEVER falls back to
2038
- * `latest` — a silent fallback is the exact failure this option exists to prevent (a caller that
2039
- * asked for `name@3` and got `name@4` has no way to tell, and its run is already going).
2040
- *
2041
- * NOT available on a child inheriting its remote ancestor's routing (see `findInheritedRegistration`),
2042
- * which INVENTS the version it stamps (the ancestor's). Convention routing to a live worker group of
2043
- * the same name (`resolveRemoteByConvention`) honours a pin only when the live workers on that group
2044
- * themselves DECLARE the pinned version (their announced registrations); a fleet that declares
2045
- * another version, or none, is no evidence, and the pinned start throws rather than pretending. To
2046
- * pin a cross-SDK workflow whose workers declare nothing, register it for real —
2047
- * `engine.remote('name', { version: '2', group })` — which puts `name@2` in the registry.
2048
- *
2049
- * A tenant's start ({@link StartRunMessage.version}) does not throw: with no live worker declaring
2050
- * the version yet, the run waits `blocked` (`no_live_worker`) until one does.
2051
- */
2052
- version?: string | undefined;
2053
- /** Run-scoped tags, merged with the workflow's static `@Workflow({ tags })` onto the run. */
2054
- tags?: string[] | undefined;
2055
- /** Typed, queryable run data stamped on the run (e.g. `{ amount: 200, tier: 'pro' }`). */
2056
- searchAttributes?: SearchAttributes | undefined;
2057
- /**
2058
- * Dispatch priority for a remote run — stamped on the run and carried onto every {@link WorkflowTask}
2059
- * the engine dispatches to advance it. Higher wins; absent = unprioritised. See {@link WorkflowRun.priority}.
1884
+ * The previous run of this schedule is still in flight when the next window comes due:
1885
+ * `'allow'` (default) starts the new one anyway; `'skip'` skips that window.
2060
1886
  */
2061
- priority?: number | undefined;
1887
+ overlap?: 'allow' | 'skip' | undefined;
2062
1888
  /**
2063
- * Override the namespace stamped on the run. Defaults to the engine's own `namespace`. Set by the
2064
- * control plane when it starts a run on behalf of a tenant (a {@link StartRunMessage}'s `tenant`
2065
- * maps here), so one DB-less-tenant-facing engine can create runs across many namespaces.
1889
+ * Windows missed while nothing polled (all schedulers down): `'latest'` (default) fires the most
1890
+ * recent missed window once; `'skip'` drops them and waits for the next window. Never more than one
1891
+ * catch-up run per schedule.
2066
1892
  */
1893
+ catchup?: 'latest' | 'skip' | undefined;
1894
+ /** Create paused (never due until `resume`). On `upsert`, omit to keep the current paused state. */
1895
+ paused?: boolean | undefined;
1896
+ /** Free-form note shown with the schedule (why it exists / why it's paused). */
1897
+ note?: string | undefined;
1898
+ /** Namespace of the schedule and of the runs it starts. Defaults to the engine's own namespace. */
2067
1899
  namespace?: string | undefined;
1900
+ /** Labels to find the schedule by — also stamped on every run it starts (plus `schedule:<id>`). */
1901
+ tags?: string[] | undefined;
1902
+ /** Search attributes stamped on every run it starts. */
1903
+ searchAttributes?: SearchAttributes | undefined;
1904
+ /** Dispatch priority for the runs it starts. */
1905
+ priority?: number | undefined;
2068
1906
  /**
2069
- * A start-time concurrency quota for this start — at most `limit` runs sharing `key` in flight;
2070
- * over it, `start` throws {@link ConcurrencyLimitError} and creates nothing. Overrides the
2071
- * workflow's registered `concurrency`. See {@link ConcurrencyQuota}.
1907
+ * A start-time concurrency quota applied to every run it starts (see `StartOptions.concurrency`):
1908
+ * a window whose start would exceed it is recorded as the schedule's `lastError` and skipped, and
1909
+ * the schedule moves on to its next window.
2072
1910
  */
2073
1911
  concurrency?: ConcurrencyQuota | undefined;
2074
1912
  /**
2075
- * Delayed start: don't execute before this time (epoch ms, or a `Date`), compared against the
2076
- * engine's clock. The run is created `suspended` with its `wakeAt` set to it, which is the same
2077
- * durable timer a `ctx.sleep` parks on: nothing is held in memory, it survives restarts, and the
2078
- * timer poller (`resumeDueTimers`) starts it once due, on any instance. A time that is not in the
2079
- * future starts the run at once, as if it were omitted.
2080
- *
2081
- * A delayed run reads `suspended` until it fires (so `start` returns `suspended`, and `waitForRun`
2082
- * settles on that right away), and skips the `run.started` event's `pending → running` hop. It
2083
- * counts as in flight for singleton back-pressure and concurrency quotas while it waits.
2084
- */
2085
- startAt?: number | Date | undefined;
2086
- /**
2087
- * The customer this run belongs to (see {@link WorkflowRun.tenantId}). An explicit value always
2088
- * wins; `null` starts it with no tenant. Omit it and the run takes the context tenant when tenancy
2089
- * is on, else none.
1913
+ * The customer the schedule belongs to; every run it starts inherits it. An explicit value wins
1914
+ * (`null` = none); omit it and the schedule takes the context tenant when tenancy is on. On
1915
+ * `upsert`, omit to keep the schedule's current tenant.
2090
1916
  */
2091
1917
  tenantId?: string | null | undefined;
2092
- /** The kind of {@link tenantId} (`organization`, `user`, …). Only read with an explicit `tenantId`. */
1918
+ /** The kind of {@link tenantId}. Only read with an explicit `tenantId`. */
2093
1919
  tenantKind?: string | undefined;
2094
1920
  }
2095
- /**
2096
- * Serialize runs of a workflow that share a key — a durable, FIFO mutex (e.g. one pipeline per base).
2097
- * Excess runs are admitted in creation order, `limit` at a time; the rest wait (suspended) and retry
2098
- * admission on a timer until a slot frees. The store atomically reserves durable slots before
2099
- * ordering unadmitted waiters by `(createdAt, id)`, so later starts cannot displace a holder.
2100
- */
2101
- interface SingletonConfig {
2102
- /** Derive the serialization key from the workflow input. */
2103
- key: (input: unknown) => string;
2104
- /** Max concurrent runs sharing the key. Default 1 (a mutex). */
2105
- limit?: number;
1921
+ /** A schedule as `engine.schedules.get/list` describe it. */
1922
+ interface ScheduleDescription {
1923
+ id: string;
1924
+ workflow: string;
1925
+ input: unknown;
1926
+ namespace: string;
1927
+ cron?: string | undefined;
1928
+ everyMs?: number | undefined;
1929
+ rrule?: string | undefined;
1930
+ timezone?: string | undefined;
1931
+ jitterMs?: number | undefined;
1932
+ overlap: 'allow' | 'skip';
1933
+ catchup: 'latest' | 'skip';
1934
+ paused: boolean;
1935
+ note?: string | undefined;
1936
+ tags?: string[] | undefined;
1937
+ searchAttributes?: SearchAttributes | undefined;
1938
+ priority?: number | undefined;
1939
+ concurrency?: ConcurrencyQuota | undefined;
1940
+ /** When it is next due (jitter included), or null if it never fires again / paused. */
1941
+ nextFireAt: Date | null;
1942
+ /** The last window it fired for, and the run that window started. */
1943
+ lastFireAt?: Date | undefined;
1944
+ lastRunId?: string | undefined;
1945
+ /** How many windows it has fired (manual triggers excluded). */
1946
+ fires: number;
1947
+ /** The last start failure (e.g. a concurrency limit), cleared by the next successful start. */
1948
+ lastError?: string | undefined;
1949
+ /** The customer the schedule and its runs belong to, when it has one. */
1950
+ tenantId?: string | undefined;
1951
+ tenantKind?: string | undefined;
2106
1952
  /**
2107
- * Max GATED (waiting-for-admission) runs allowed to queue behind the `limit` in-flight ones. When
2108
- * set, `start` rejects with {@link SingletonQueueFullError} once in-flight + gated reaches
2109
- * `limit + maxQueueDepth` — back-pressure against an unbounded same-key backlog. Omit for the
2110
- * default unbounded queue. Counts pending/running/suspended/blocked/cancelling runs sharing the key.
1953
+ * Set on a schedule a tenant app ANNOUNCED (its `schedules` module option) and the control plane
1954
+ * adopted: the key the app declares it under. Its `namespace` is the app (partition).
2111
1955
  */
2112
- maxQueueDepth?: number;
1956
+ announcedKey?: string | undefined;
1957
+ /** An announced schedule that no live worker of its app announces any more: since when. */
1958
+ unannouncedSince?: Date | undefined;
1959
+ /** When the control plane paused it for staying unannounced past the grace period. */
1960
+ withdrawnAt?: Date | undefined;
1961
+ createdAt: Date;
1962
+ updatedAt: Date;
1963
+ }
1964
+ /** The tag on every schedule adopted from a tenant's announcement (and on the runs it starts). */
1965
+ declare const ANNOUNCED_SCHEDULE_TAG = "schedule:announced";
1966
+ /** The control plane's schedule id for the schedule `key` announced by the app on `namespace`. */
1967
+ declare function announcedScheduleId(namespace: string, key: string): string;
1968
+ /** Filter for `engine.schedules.list`. */
1969
+ type ScheduleListQuery = Omit<ScheduleQuery, 'dueBy'>;
1970
+ /** Thrown by `engine.schedules.create` when the id is taken (use `upsert` to replace). */
1971
+ declare class ScheduleAlreadyExistsError extends Error {
1972
+ readonly scheduleId: string;
1973
+ constructor(scheduleId: string);
1974
+ }
1975
+ /** Thrown by `engine.schedules.*` on an id that doesn't exist. */
1976
+ declare class ScheduleNotFoundError extends Error {
1977
+ readonly scheduleId: string;
1978
+ constructor(scheduleId: string);
1979
+ }
1980
+ /** What {@link ScheduleClient.syncAnnounced} did to a namespace's adopted schedules. */
1981
+ interface AnnouncedScheduleSync {
1982
+ /** Created, or re-applied because the announced definition changed. */
1983
+ adopted: string[];
1984
+ /** Announced again after missing (and resumed, when it had been withdrawn). */
1985
+ restored: string[];
1986
+ /** Missing from the announcement for the first time: the grace period starts. */
1987
+ missing: string[];
1988
+ /** Paused because it stayed unannounced past the grace period. */
1989
+ withdrawn: string[];
1990
+ /** Announced, but the definition does not evaluate (bad cron, both or neither cadence). */
1991
+ invalid: {
1992
+ key: string;
1993
+ error: string;
1994
+ }[];
1995
+ }
1996
+ /** The engine surface the schedule client drives. */
1997
+ interface ScheduleHost {
1998
+ start(workflow: string, input: unknown, runId: string, opts?: StartOptions): Promise<RunResult>;
1999
+ /**
2000
+ * The tenant start path, used to fire an announced schedule: a workflow no live worker serves yet
2001
+ * is parked `blocked` (`no_live_worker`) until one is, instead of throwing. Absent = `start`.
2002
+ */
2003
+ startParked?(workflow: string, input: unknown, runId: string, opts?: StartOptions, singleton?: StartRunSingleton): Promise<RunResult>;
2004
+ getRun(runId: string): Promise<WorkflowRun | null>;
2005
+ /** True once the engine has begun shutting down; `tick` fires nothing more after that. */
2006
+ isDraining?(): boolean;
2007
+ /** The context tenant to stamp on a schedule created now (tenancy on), else undefined. */
2008
+ tenant?(): RunTenant | undefined;
2009
+ /** The tenancy matching filter for an app-facing call made now. Absent = sees everything. */
2010
+ tenantFilter?(): TenantFilter;
2011
+ }
2012
+ /** Engine-level knobs for the client. */
2013
+ interface ScheduleClientOptions {
2014
+ /** The engine's namespace: the default for new schedules, and which ones `tick` fires. */
2015
+ namespace?: string | undefined;
2016
+ clock?: (() => number) | undefined;
2113
2017
  }
2114
2018
  /**
2115
- * Stamped on a run whose workflow version NOBODY declared: a remote resolved by convention, served
2116
- * by a worker that announces no version for it (an SDK too old to publish a descriptor, or a body
2117
- * whose author simply never stated one).
2118
- *
2119
- * ## Why a run has to carry this
2120
- *
2121
- * Such a run's `workflowVersion` is `'1'`, the engine's convention default. That value is a routing
2122
- * placeholder, not an observation — and read back later it is indistinguishable from a worker that
2123
- * genuinely declared version `'1'`. Any check comparing an authored pin against it therefore passes
2124
- * whenever the pin is `'1'` and fails whenever it is not, regardless of what the callee actually is.
2125
- * A check that cannot fail is worse than no check, because it reads as a guarantee.
2126
- *
2127
- * The tag is the difference, carried ON the run so a retrospective check needs no second read: a
2128
- * caller that pinned a version can see that the version it is comparing against was never stated,
2129
- * and say so, instead of reporting a match it did not really make. It is deliberately a tag rather
2130
- * than a new column — every store already persists and queries tags, so this needs no migration and
2131
- * shows up in run listings and dashboards for free. Follows the `singleton:<key>` precedent for an
2132
- * engine-stamped reserved tag.
2019
+ * Persisted, runtime-managed schedules — `engine.schedules`. Unlike the code-registered
2020
+ * `schedules` module option, these live in the store: create/update/pause/delete them at runtime
2021
+ * (one per user, per tenant, per automation…), and every driving engine's timer poll fires the due
2022
+ * ones via {@link tick}.
2133
2023
  *
2134
- * A run whose callee DOES declare a version never carries it; that run's version is the declared one
2135
- * and a pin against it is genuinely checked.
2136
- */
2137
- declare const VERSION_UNDECLARED_TAG = "version:undeclared";
2138
- /**
2139
- * The `error.code` of a run a tenant started while no live worker served it yet (see
2140
- * `WorkflowEngine.startForTenant`). The run is parked `blocked` and the blocked-recovery poll starts
2141
- * it as soon as a worker on its group (declaring its pinned version, when it has one) is live. It is
2142
- * never dead-lettered for waiting: a start is a request queued for its consumer, however late that
2143
- * consumer boots. Cancel it to drop it.
2144
- */
2145
- declare const NO_LIVE_WORKER = "no_live_worker";
2146
- /**
2147
- * How long an adopted tenant schedule may go unannounced by every live worker of its app before the
2148
- * control plane pauses it (see `WorkflowEngine.syncAnnouncedSchedules`). Long enough to ride out a
2149
- * rolling deploy; a schedule is never deleted for missing.
2024
+ * Multi-worker safety comes from two properties, not from a lock: a window's run id is deterministic
2025
+ * (`sched:<id>:<windowMs>`), so racing starts of the same window collapse into one run; and a
2026
+ * schedule is advanced with a compare-and-set on its `nextFireAt`, so exactly one poller moves it on.
2027
+ * A crash between starting the run and advancing the schedule just re-fires the (idempotent) start.
2150
2028
  */
2151
- declare const DEFAULT_ANNOUNCED_SCHEDULE_GRACE_MS: number;
2152
- interface WorkflowEngineDeps {
2153
- store: StateStore;
2154
- /** A single task transport. Shorthand for a one-entry `transports` pool (id `default`). */
2155
- transport?: Transport | undefined;
2029
+ declare class ScheduleClient {
2030
+ private readonly store;
2031
+ private readonly host;
2032
+ private readonly options;
2033
+ constructor(store: StateStore, host: ScheduleHost, options?: ScheduleClientOptions);
2034
+ private now;
2035
+ /** Whether the store persists schedules (implements the schedule methods). */
2036
+ get supported(): boolean;
2037
+ private requireStore;
2038
+ private filter;
2039
+ /** The schedule `id` if it exists and the caller may see it (tenancy), else null. */
2040
+ private visible;
2041
+ /** Create a schedule. Throws {@link ScheduleAlreadyExistsError} if the id is taken. */
2042
+ create(opts: ScheduleOptions): Promise<ScheduleDescription>;
2156
2043
  /**
2157
- * An ordered pool of named transports. The engine dispatches on the first and fails over to the
2158
- * next on a dispatch error; a step pins one via `ctx.step(step, input, { transport: id })`. Use
2159
- * this instead of `transport` for failover / multi-broker setups.
2044
+ * Create the schedule, or replace the definition of an existing one (its history — last fire, last
2045
+ * run, fire count — is kept). The next fire is recomputed from now under the new definition, so a
2046
+ * window that already fired is never fired again by an upsert.
2160
2047
  */
2161
- transports?: NamedTransport[] | undefined;
2162
- /**
2163
- * Cross-instance broadcast pub/sub for lifecycle events + cancellation (see {@link ControlPlane}).
2164
- * Separate from the task `transport`; omit for a single-instance / local-only setup. A transport
2165
- * that can also broadcast may be passed here as well.
2166
- */
2167
- controlPlane?: ControlPlane | undefined;
2168
- /** Epoch-ms clock; injectable for tests. Defaults to `Date.now`. */
2169
- clock?: (() => number) | undefined;
2048
+ upsert(opts: ScheduleOptions): Promise<ScheduleDescription>;
2049
+ /** The schedule `id`, or null (also null for another tenant's schedule). */
2050
+ get(id: string): Promise<ScheduleDescription | null>;
2051
+ /** Schedules matching `query` (and visible to the caller's tenant), soonest-due first. */
2052
+ list(query?: ScheduleListQuery): Promise<ScheduleDescription[]>;
2053
+ /** Delete the schedule. Runs it already started are left alone. Returns whether it existed. */
2054
+ delete(id: string): Promise<boolean>;
2055
+ /** Stop firing until {@link resume}. `note` records why (shown by `get`/`list`). */
2056
+ pause(id: string, note?: string): Promise<ScheduleDescription>;
2170
2057
  /**
2171
- * Flow-control admission backend for `ctx.step(step, input, { queue })`. Defaults to an in-process
2172
- * {@link InMemoryAdmissionBackend} (per-instance caps). Inject a store/Redis-backed backend to make
2173
- * concurrency / rate-limit / ordering GLOBAL across engine replicas.
2058
+ * Fire again from the next window after now — the windows skipped while paused are NOT caught up.
2174
2059
  */
2175
- admission?: AdmissionBackend | undefined;
2176
- /** Unique id for this engine instance, used for recovery leases. Defaults to a random id. */
2177
- instanceId?: string | undefined;
2060
+ resume(id: string): Promise<ScheduleDescription>;
2178
2061
  /**
2179
- * Worker-pool partition for this engine. Stamped on every run it creates; the poll paths
2180
- * (`runPending`/`recoverIncomplete`/`resumeDueTimers`/`sweepTimeouts`) only act on runs in this
2181
- * namespace. Set distinct values to safely share ONE state store across non-interchangeable pools
2182
- * (e.g. local dev vs a cluster). **Omit it to make this engine an OPERATOR** — an unset namespace
2183
- * drives/recovers/resumes runs of EVERY namespace (the poll filters no-op, the resume/decision
2184
- * guards fall through) and leaves the transport on its bare prefix. This is the hosted control
2185
- * plane: "ver tudo = ausência de namespace".
2062
+ * Start one run of the schedule right now, outside its cadence (paused or not). The run id is
2063
+ * `sched:<id>:manual:<nowMs>`; it doesn't move the schedule's next fire.
2186
2064
  */
2187
- namespace?: string | undefined;
2065
+ trigger(id: string): Promise<RunResult>;
2188
2066
  /**
2189
- * Verifies the signed tenant token a store-less tenant worker presents in the `tenant` field of a
2190
- * {@link StartRunMessage}, and DERIVES the run's namespace from it (see `hmacTenantVerifier`).
2191
- * A message whose token is rejected (or whose verifier throws) is dropped without creating a run.
2192
- * Absent: the wire `tenant` is trusted verbatim, as before.
2067
+ * Start one run of `record`: through the tenant start path for an announced schedule (its run waits
2068
+ * `blocked` for a live worker of its app instead of failing), else a plain `start`.
2193
2069
  */
2194
- verifyTenant?: TenantVerifier | undefined;
2195
- /** Recovery lease duration in ms — how long this instance owns a run it picked up. Default 30s. */
2196
- leaseMs?: number | undefined;
2070
+ private startFor;
2197
2071
  /**
2198
- * Cap how many times crash-recovery may pick up the same still-`running` run before giving up and
2199
- * moving it to the `dead` dead-letter state (a poison pill that crashes the process every boot).
2200
- * Omit for unlimited (the default — recovery always retries).
2072
+ * Fire every due schedule (in this engine's namespace; all namespaces for an operator engine; only
2073
+ * those carrying `opts.tag` when given):
2074
+ * start its window's run and advance it to the next window. Called by the NestJS timer poller on
2075
+ * each tick when `persistedSchedules` is on; call it yourself from any other driver. Returns the
2076
+ * run ids started (or re-found, for an idempotent re-fire).
2201
2077
  */
2202
- maxRecoveryAttempts?: number | undefined;
2078
+ tick(nowMs?: number, opts?: {
2079
+ tag?: string;
2080
+ }): Promise<string[]>;
2203
2081
  /**
2204
- * How long (ms) a run may stay due while NO instance can resume it because its workflow version is
2205
- * not registered anywhere, before it is moved to `dead` (code `workflow_not_registered`). A rolling
2206
- * deploy skips such a run on purpose (skew protection): the pod still on the prior version picks it
2207
- * up within seconds. A run that stays unresumable far past that — its workflow was renamed or
2208
- * deleted — would otherwise be retried and logged on every tick forever. The clock starts when the
2209
- * run became due (its `wakeAt` for a parked run, its last update otherwise), so a long sleep is not
2210
- * counted. Default 24h; `0` disables (skip forever). A non-finite or negative value falls back to
2211
- * the default.
2082
+ * When {@link tick} next has a schedule to fire, if one is due by `byMs`: the earliest `nextFireAt`
2083
+ * of the unpaused schedules (of this engine's namespace, carrying `opts.tag` when given) due by
2084
+ * then, else `undefined`. One indexed
2085
+ * read (the due-schedule scan `tick` makes, with a later bound and a limit of one). A store that
2086
+ * does not persist schedules has none.
2212
2087
  */
2213
- unregisteredWorkflowGraceMs?: number | undefined;
2088
+ nextFireAt(byMs: number, opts?: {
2089
+ tag?: string;
2090
+ }): Promise<number | undefined>;
2091
+ /** Fire one due schedule and advance it. Returns the run id started, if any. */
2092
+ private fire;
2214
2093
  /**
2215
- * Opt-in liveness deadline (ms) for a remote workflow `advance`. If the worker neither returns a
2216
- * decision NOR sends a run-scoped {@link Heartbeat} within this window, the engine presumes it dead:
2217
- * it rejects the advance with {@link RemoteWorkflowTimeout}, releases the lease, and lets recovery
2218
- * re-drive (replaying completed steps from history). Each beat REARMS the window, so a worker still
2219
- * legitimately replaying a long turn (it keeps beating) is never re-driven — closing the duplicate-
2220
- * side-effect hazard a fixed {@link RemoteWorkflowExecutor} `timeoutMs` cannot avoid. Omit (default)
2221
- * for the prior unbounded await — byte-identical behavior when unset. If a `RemoteWorkflowExecutor` is
2222
- * ALSO constructed with its own `timeoutMs`, the shorter of the two deadlines wins; prefer setting only
2223
- * one (this rearmed window for heartbeat-aware workers, or the fixed `timeoutMs` otherwise).
2224
- *
2225
- * A turn DISPATCHED over a broker (a tenant's or another SDK's worker) is never left without a
2226
- * deadline: unset, its window is {@link reconcileMs} (5 min by default), so a run whose worker died
2227
- * holding the turn is re-driven instead of waiting forever. `reconcileMs: 0` with this unset keeps
2228
- * the old unbounded wait.
2094
+ * An announced schedule whose previous run is still parked waiting for a live worker of its app
2095
+ * (the app is down): this window is folded into that run instead of parking one more. However long
2096
+ * the app is down, it finds at most one run per schedule waiting when it comes back, the same
2097
+ * bound `catchup: 'latest'` puts on windows missed while no scheduler polled.
2229
2098
  */
2230
- remoteAdvanceSilenceMs?: number | undefined;
2099
+ private waitingForWorker;
2231
2100
  /**
2232
- * Fallback re-drive window (ms) for a run that SUSPENDS with no natural timer — i.e. it's waiting on
2233
- * an EVENT to wake it (a child's completion, a signal, a remote step with no `timeoutMs`) rather than
2234
- * a `ctx.sleep`. Those events re-drive the run directly; but if the wake is LOST (the delivering pod
2235
- * crashed / rolled mid-handoff), the run would otherwise sit `suspended` forever with `wakeAt: null` —
2236
- * invisible to both the timer poller (no `wakeAt`) and crash-recovery (no lease). This stamps a
2237
- * fallback `wakeAt` so {@link resumeDueTimers} re-drives it after the window; the re-drive is an
2238
- * idempotent replay (a still-pending dependency re-suspends via the checkpoint guard, a settled one
2239
- * advances), so it's a safe self-heal, not a retry that can double-dispatch. The primary event path
2240
- * still wins first for a healthy run (it re-drives long before this fires), so this only ever fires
2241
- * for a genuinely-orphaned run. Default 5min; set `0` to disable (the prior wake-forever behavior).
2101
+ * Reconcile the schedules adopted from one app (`namespace`) with what its LIVE workers announce
2102
+ * now (`items`, one per key; the caller resolved disagreeing workers). The rule:
2103
+ * - an announced key with no schedule yet is created (id {@link announcedScheduleId}, tagged
2104
+ * {@link ANNOUNCED_SCHEDULE_TAG}, `catchup: 'latest'`); one whose definition changed is
2105
+ * re-applied like `upsert` (its history kept, its next fire recomputed from now). An equal
2106
+ * definition writes nothing, so any number of replicas announcing the same set is a no-op;
2107
+ * - a pause or resume made from the console survives: a re-applied definition keeps the current
2108
+ * paused state, unless the app's own declared `paused` changed;
2109
+ * - an adopted schedule the app no longer announces is marked missing, and paused ("withdrawn")
2110
+ * once it has stayed missing for `graceMs`. It is never deleted: its history stays, and an app
2111
+ * that announces it again (a rollback) gets it back, resumed unless an operator had paused it.
2242
2112
  *
2243
- * Also the default re-drive window of a workflow turn dispatched to a remote worker when
2244
- * {@link remoteAdvanceSilenceMs} is unset (see there).
2113
+ * Call it only for an app that has at least one live worker stating its schedules: with none (the
2114
+ * app is down, or runs an SDK that does not announce schedules), nothing is withdrawn, and its
2115
+ * schedules keep firing into runs that wait for a worker.
2245
2116
  */
2246
- reconcileMs?: number | undefined;
2117
+ syncAnnounced(namespace: string, items: readonly AnnouncedSchedule[], opts: {
2118
+ nowMs?: number;
2119
+ graceMs: number;
2120
+ }): Promise<AnnouncedScheduleSync>;
2121
+ /** `overlap: 'skip'` and the previous run of this schedule is still in flight. */
2122
+ private overlapping;
2123
+ private mustGet;
2124
+ /** Explicit `opts.tenantId` → the existing schedule's tenant (upsert) → the context tenant → none. */
2125
+ private scheduleTenant;
2126
+ private write;
2127
+ }
2128
+
2129
+ /** Default idle threshold for a stranded run: 15 minutes. */
2130
+ declare const DEFAULT_STALLED_AFTER_MS: number;
2131
+ /** The oldest unresolved remote step of a run — the lost-dispatch signature when it is old. */
2132
+ interface StalePendingStep {
2133
+ seq: number;
2134
+ name: string;
2135
+ /** How many times this step has been (re-)dispatched. A lost dispatch typically sits at 1. */
2136
+ attempts: number;
2137
+ /** Milliseconds since the step was enqueued to the transport. */
2138
+ ageMs: number;
2247
2139
  /**
2248
- * How long an in-flight run must sit untouched, with the stranded signature (a wake-forever
2249
- * suspension, or an old pending remote step with no live lease), before the
2250
- * {@link WorkflowEngine.onStalled} listeners are notified. Default 900 000 (15 min); floored at
2251
- * 60 000. The sweep ({@link WorkflowEngine.sweepStalled}) only does work when a listener is
2252
- * registered.
2140
+ * The step's lease (`wakeAt`, epoch ms) when it has one: a step with a `timeoutMs`, a heartbeat
2141
+ * renewing it, or `remoteRedispatchMs`. `null` when nothing is leasing the step.
2253
2142
  */
2254
- stalledAfterMs?: number | undefined;
2143
+ leaseUntil: number | null;
2144
+ }
2145
+ /** What an `engine.onStalled` listener (and {@link findStalledRuns}) receives: a stranded run and why. */
2146
+ interface StalledRunInfo {
2147
+ run: WorkflowRun;
2148
+ /** Milliseconds since the run's last activity (`updatedAt`). */
2149
+ ageMs: number;
2150
+ /** Suspended with NO wake timer — nothing will re-drive it (the `reconcileMs: 0` hazard). */
2151
+ wakeForever: boolean;
2152
+ /** The oldest pending remote step with no live lease, when that is the stranding signature. */
2153
+ stalePending: StalePendingStep | null;
2154
+ }
2155
+ /** Options for {@link findStalledRuns}. */
2156
+ interface FindStalledRunsOptions {
2157
+ /** Idle threshold in ms. Default {@link DEFAULT_STALLED_AFTER_MS}. */
2158
+ thresholdMs?: number | undefined;
2159
+ /** Max candidate runs inspected (newest first). Default 1000. */
2160
+ scan?: number | undefined;
2161
+ /** Evaluate as of this time (epoch ms). Default `Date.now()`. */
2162
+ now?: number | undefined;
2163
+ /** Only runs in this namespace. Omit for every namespace. */
2164
+ namespace?: string | undefined;
2165
+ }
2166
+ /**
2167
+ * The stranded runs in a store right now — the query behind `engine.sweepStalled`/`onStalled`,
2168
+ * `engine.listStalledRuns` and the CLI's `durable inspect --stale`. Works on a bare store, so an
2169
+ * ops script or a CLI can run it without an engine.
2170
+ *
2171
+ * A `running`/`suspended` run qualifies when it has been untouched for `thresholdMs` AND either:
2172
+ *
2173
+ * - it is suspended with NO wake timer (`wakeForever`): nothing will ever re-drive it; or
2174
+ * - its oldest pending REMOTE step is older than the threshold and has no lease in the future
2175
+ * (`stalePending`): the dispatch was most likely lost.
2176
+ *
2177
+ * Healthy long work is excluded: a long `ctx.sleep` has a future `wakeAt` and no pending step, and a
2178
+ * remote step with a `timeoutMs`, a heartbeat or `remoteRedispatchMs` carries a future lease. Issues
2179
+ * one `listCheckpoints` per idle candidate, bounded by `scan`: an operator read, not a hot path.
2180
+ */
2181
+ declare function findStalledRuns(store: Pick<StateStore, 'listRuns' | 'listCheckpoints'>, options?: FindStalledRunsOptions): Promise<StalledRunInfo[]>;
2182
+
2183
+ /**
2184
+ * Layered tenant auth for the store-less cluster. On a tenant worker the `tenant` on a
2185
+ * {@link import('./interfaces').RunRequest} / {@link import('./interfaces').StartRunMessage} is only
2186
+ * a CLAIM: without a signed proof, any broker client can act as any tenant. This module is the
2187
+ * default defense in depth on top of prefix/network isolation: a symmetric HMAC token the tenant
2188
+ * worker presents IN the existing `tenant` wire field, which the operator's {@link TenantVerifier}
2189
+ * checks and DERIVES the real tenant from, never trusting the body.
2190
+ *
2191
+ * Wire-compatible with Agora (`@adonis-agora/durable`) byte for byte: the token is
2192
+ * `<claim>.<base64url(HMAC-SHA256(secret, claim))>`, where `claim` is the tenant name, optionally
2193
+ * followed by `.exp<epochMs>`. It fits the `tenant: string` field with NO envelope change, so an
2194
+ * operator that does not verify simply treats the whole string as the tenant name (and finds no
2195
+ * runs, a safe failure), while an operator configured with {@link hmacTenantVerifier} verifies the
2196
+ * signature and scopes to the embedded tenant. Agora and Aviary tokens are interchangeable.
2197
+ *
2198
+ * HMAC (shared secret) is the zero-infra default; a deployment that prefers asymmetric or issued
2199
+ * tokens supplies its own {@link TenantVerifier} instead.
2200
+ */
2201
+ /** The identity a {@link TenantVerifier} derives from a tenant's signed claim. */
2202
+ interface VerifiedTenant {
2203
+ /** The tenant the token authenticates as. The responder trusts THIS, never the request body. */
2204
+ tenant: string;
2255
2205
  /**
2256
- * The most due timers one {@link WorkflowEngine.resumeDueTimers} pass loads and drives, most
2257
- * overdue first. Every driving instance runs that pass each tick, so a wave of thousands of due
2258
- * runs (a recovery after an outage, a fan's children waking together) is worked through in
2259
- * batches instead of every instance loading and walking all of it. Default 500.
2206
+ * Capabilities the token grants, if the issuer scopes them. `tenancy:*` or `tenancy:<id>` lets the
2207
+ * process claim that customer tenant for the runs it starts (see `StartRunMessage.tenantId`). The
2208
+ * run-request responder does not enforce them: a verified tenant can call every verb, scoped to
2209
+ * its own namespace.
2260
2210
  */
2261
- timerBatchSize?: number | undefined;
2211
+ capabilities?: string[] | undefined;
2212
+ }
2213
+ /**
2214
+ * Verifies a tenant's signed claim on the **operator** side, returning the {@link VerifiedTenant} it
2215
+ * authenticates as, or `null` (or throwing) to reject a tampered/invalid/absent token. The signed
2216
+ * token travels in the wire `tenant` field, so the responder passes that value as both `token` and
2217
+ * the advisory `tenant`.
2218
+ */
2219
+ type TenantVerifier = (input: {
2220
+ /** The signed token presented on the request. */
2221
+ token?: string | undefined;
2222
+ /** The tenant the request *claims* to be. Advisory only: the verifier derives the real one. */
2223
+ tenant?: string | undefined;
2224
+ }) => VerifiedTenant | null | Promise<VerifiedTenant | null>;
2225
+ /**
2226
+ * Where the tenant side gets the token it presents: a static string, or a function called before
2227
+ * every request (so a short-lived token from {@link signTenantToken} with `ttlMs` can be re-minted
2228
+ * or fetched from a secret store without restarting the worker).
2229
+ */
2230
+ type TenantTokenSource = string | (() => string | Promise<string>);
2231
+ /**
2232
+ * Mint the signed token a tenant worker presents:
2233
+ * `` `${tenant}.${base64url(HMAC-SHA256(secret, tenant))}` ``. The worker carries only the token
2234
+ * (never the secret); the operator verifies it with the SAME `secret` via {@link hmacTenantVerifier}.
2235
+ */
2236
+ declare function signTenantToken(tenant: string, secret: string, opts?: {
2262
2237
  /**
2263
- * Retention for a BUFFERED event that no `waitForEvent` ever claims (see
2264
- * {@link WorkflowEngine.publishEvent}'s buffering — a publish matching no live waiter keeps ONE
2265
- * copy around for a later matching wait). Default `undefined`: keep it until consumed, same as
2266
- * {@link StateStore.bufferSignal}'s buffered signals — no silent expiry. Set a duration (ms) to
2267
- * have the {@link resumeDueTimers} reconcile pass prune rows past `publishedAt + eventBufferTtlMs`
2268
- * as it encounters them. Scoped to event NAMES the current reconcile tick's registered waiters
2269
- * reference (the sweep has no reason to otherwise enumerate every buffered name) — a name with a
2270
- * stale buffered event but zero waiters ever registered against it is not visited by this pass; that
2271
- * is an accepted gap given `listBufferedEvents` is name-scoped by design (see interfaces.ts), not a
2272
- * bug to route around here.
2238
+ * Optional lifetime: the claim gains a `.exp<epochMs>` suffix, signed together with the tenant,
2239
+ * and {@link hmacTenantVerifier} rejects the token once that instant passes. Without it the
2240
+ * token never expires. Expiring and non-expiring tokens verify side by side. Tenant names
2241
+ * ending in `.exp<digits>` are reserved by this scheme.
2273
2242
  */
2274
- eventBufferTtlMs?: number | undefined;
2243
+ ttlMs?: number;
2244
+ /** Injectable clock for tests. */
2245
+ now?: number;
2246
+ }): string;
2247
+ /**
2248
+ * Build the operator-side {@link TenantVerifier} for {@link signTenantToken} tokens under `secret`.
2249
+ * It recomputes the HMAC over the embedded claim and compares it in constant time, so a tampered
2250
+ * tenant, a forged/absent signature, a token signed with another secret, or an expired token all
2251
+ * return `null`. The tenant is DERIVED from the token's own claim.
2252
+ *
2253
+ * A LIST of secrets makes rotation a two-step deploy: verify with `[next, current]` everywhere first,
2254
+ * then re-mint tenant tokens with `next` at leisure. `capabilities`, if given, is a static grant
2255
+ * stamped onto every {@link VerifiedTenant} this verifier authenticates (informational: the
2256
+ * responder does not enforce it yet, see {@link VerifiedTenant.capabilities}).
2257
+ */
2258
+ declare function hmacTenantVerifier(secret: string | string[], capabilities?: string[]): TenantVerifier;
2259
+ /**
2260
+ * Verify a wire message's `tenant`: with a verifier, the {@link VerifiedTenant} it derives (`null` on
2261
+ * reject); without one, the wire value trusted verbatim, with no capabilities.
2262
+ */
2263
+ declare function verifyWireTenant(wireTenant: string, verifyTenant: TenantVerifier | undefined): Promise<VerifiedTenant | null>;
2264
+ /**
2265
+ * Whether a verified tenant process may claim the customer `tenantId` for a run it starts: its
2266
+ * `capabilities` hold `tenancy:*` (any customer) or `tenancy:<tenantId>`. An unverified process (no
2267
+ * verifier) holds none, so it never may.
2268
+ */
2269
+ declare function grantsClientTenant(verified: VerifiedTenant | null, tenantId: string): boolean;
2270
+ /**
2271
+ * Resolve the tenant a wire message is ALLOWED to act as. With a verifier, the wire `tenant` is the
2272
+ * signed token: it is verified and the real tenant derived from it (`null` on reject). Without one,
2273
+ * the wire value is trusted verbatim (prefix/network isolation only, today's behaviour).
2274
+ */
2275
+ declare function resolveWireTenant(wireTenant: string, verifyTenant: TenantVerifier | undefined): Promise<string | null>;
2276
+ /** Resolve a {@link TenantTokenSource} to the token string to put on the wire. */
2277
+ declare function resolveTenantToken(source: TenantTokenSource): Promise<string>;
2278
+
2279
+ type WorkflowFn = (ctx: WorkflowCtx, input: unknown) => Promise<unknown>;
2280
+ /**
2281
+ * Options for {@link WorkflowEngine.start}.
2282
+ *
2283
+ * Note the absence of `origin`: {@link WorkflowRun.origin} says which PACKAGE declared the workflow,
2284
+ * which is a property of the registered code, not of whoever started it. It is taken from the
2285
+ * registration and nothing here can override it — otherwise one caller could label its runs as
2286
+ * another lib's, and an origin filter would quietly lie.
2287
+ */
2288
+ interface StartOptions {
2275
2289
  /**
2276
- * How long `signal(token, payload, { id })` remembers an `id` (ms, or a duration like `'7d'`): a
2277
- * re-send with the same token and id within it is dropped. Records past it are ignored, and
2278
- * {@link WorkflowEngine.sweepExpiredSignalIds} deletes them. Keep it longer than any sender's
2279
- * redelivery window. Default 7 days; a call can pass its own `idTtl`.
2290
+ * Start THIS registered version instead of the newest one. Omit (the default) and the run starts on
2291
+ * the newest registered version, exactly as it always has — this option only ever narrows.
2292
+ *
2293
+ * Resolved against the by-name@version registry, so it pins anything explicitly registered:
2294
+ * {@link WorkflowEngine.register}, {@link WorkflowEngine.registerRemote}, {@link WorkflowEngine.remote}.
2295
+ * A version that is NOT registered throws before a run row is created and NEVER falls back to
2296
+ * `latest` — a silent fallback is the exact failure this option exists to prevent (a caller that
2297
+ * asked for `name@3` and got `name@4` has no way to tell, and its run is already going).
2298
+ *
2299
+ * NOT available on a child inheriting its remote ancestor's routing (see `findInheritedRegistration`),
2300
+ * which INVENTS the version it stamps (the ancestor's). Convention routing to a live worker group of
2301
+ * the same name (`resolveRemoteByConvention`) honours a pin only when the live workers on that group
2302
+ * themselves DECLARE the pinned version (their announced registrations); a fleet that declares
2303
+ * another version, or none, is no evidence, and the pinned start throws rather than pretending. To
2304
+ * pin a cross-SDK workflow whose workers declare nothing, register it for real —
2305
+ * `engine.remote('name', { version: '2', group })` — which puts `name@2` in the registry.
2306
+ *
2307
+ * A tenant's start ({@link StartRunMessage.version}) does not throw: with no live worker declaring
2308
+ * the version yet, the run waits `blocked` (`no_live_worker`) until one does.
2280
2309
  */
2281
- signalIdTtl?: string | number | undefined;
2310
+ version?: string | undefined;
2311
+ /** Run-scoped tags, merged with the workflow's static `@Workflow({ tags })` onto the run. */
2312
+ tags?: string[] | undefined;
2313
+ /** Typed, queryable run data stamped on the run (e.g. `{ amount: 200, tier: 'pro' }`). */
2314
+ searchAttributes?: SearchAttributes | undefined;
2282
2315
  /**
2283
- * Opt-in self-heal window (ms) for a remote step with NO `timeoutMs` whose dispatched job was LOST —
2284
- * the worker crashed mid-step leaving no result, or the transport dropped the job (a Redis
2285
- * flush/eviction, or BullMQ moving a stalled job to `failed` and removing it). The `pending`
2286
- * checkpoint then has no result to resume on, and — BY DESIGN (see {@link reconcileMs}) — the
2287
- * reconcile re-drive re-suspends a still-pending step rather than re-dispatching, so a slow-but-live
2288
- * worker is never double-run. That safety means a genuinely-lost dispatch would otherwise hang
2289
- * forever. When set, a reconcile re-drive that finds a remote step still `pending` PAST this window
2290
- * re-dispatches it (bumping `attempts`, bounded by {@link remoteRedispatchMax}). Off by default:
2291
- * re-dispatch can double-run a step whose original job is merely slow, so the window MUST exceed the
2292
- * longest such step and the step MUST be idempotent. Prefer a per-step `timeoutMs` (tighter,
2293
- * heartbeat-aware) where you can; this is the store-driven net for no-timeout steps that must
2294
- * survive a lost dispatch. {@link WorkflowEngine.redispatchPending} is the manual counterpart.
2316
+ * Dispatch priority for a remote run — stamped on the run and carried onto every {@link WorkflowTask}
2317
+ * the engine dispatches to advance it. Higher wins; absent = unprioritised. See {@link WorkflowRun.priority}.
2295
2318
  */
2296
- remoteRedispatchMs?: number | undefined;
2319
+ priority?: number | undefined;
2297
2320
  /**
2298
- * Max times {@link remoteRedispatchMs} re-dispatches one lost remote step before giving up and
2299
- * failing it as a {@link RemoteStepError} (`code: 'remote_step_lost'`), so the run fails / dead-letters
2300
- * instead of re-dispatching forever. Default 10. Ignored when `remoteRedispatchMs` is unset.
2321
+ * Override the namespace stamped on the run. Defaults to the engine's own `namespace`. Set by the
2322
+ * control plane when it starts a run on behalf of a tenant (a {@link StartRunMessage}'s `tenant`
2323
+ * maps here), so one DB-less-tenant-facing engine can create runs across many namespaces.
2301
2324
  */
2302
- remoteRedispatchMax?: number | undefined;
2325
+ namespace?: string | undefined;
2303
2326
  /**
2304
- * How long (ms) a run parked `blocked` (no capability-capable + protocol-compatible live worker,
2305
- * handshake design §7.5) waits before the blocked-recovery poll re-drives it to re-check the live
2306
- * fleet. Default 5000. The run proceeds the moment a capable+compatible worker appears; until then it
2307
- * re-parks with a fresh `wakeAt` each poll. Only relevant once a step/workflow declares `requires`
2308
- * AND descriptors are published (a legacy fleet never parks blocked).
2327
+ * A start-time concurrency quota for this start — at most `limit` runs sharing `key` in flight;
2328
+ * over it, `start` throws {@link ConcurrencyLimitError} and creates nothing. Overrides the
2329
+ * workflow's registered `concurrency`. See {@link ConcurrencyQuota}.
2309
2330
  */
2310
- blockedPollMs?: number | undefined;
2331
+ concurrency?: ConcurrencyQuota | undefined;
2311
2332
  /**
2312
- * How long (ms) the routing guard reuses the worker descriptors it read for a queue token before
2313
- * reading them again. Every dispatch consults them, and on BullMQ each read is a `SCAN` of the
2314
- * Redis keyspace; workers rewrite their descriptor every 10 s with a 35 s TTL, so a couple of
2315
- * seconds of reuse changes nothing the guard can observe. Concurrent reads of one token share a
2316
- * single request. Default 2000; `0` reads on every dispatch.
2333
+ * Delayed start: don't execute before this time (epoch ms, or a `Date`), compared against the
2334
+ * engine's clock. The run is created `suspended` with its `wakeAt` set to it, which is the same
2335
+ * durable timer a `ctx.sleep` parks on: nothing is held in memory, it survives restarts, and the
2336
+ * timer poller (`resumeDueTimers`) starts it once due, on any instance. A time that is not in the
2337
+ * future starts the run at once, as if it were omitted.
2338
+ *
2339
+ * A delayed run reads `suspended` until it fires (so `start` returns `suspended`, and `waitForRun`
2340
+ * settles on that right away), and skips the `run.started` event's `pending → running` hop. It
2341
+ * counts as in flight for singleton back-pressure and concurrency quotas while it waits.
2317
2342
  */
2318
- workerDescriptorCacheMs?: number | undefined;
2343
+ startAt?: number | Date | undefined;
2319
2344
  /**
2320
- * Build the public callback URL for a `ctx.webhook()` token (e.g.
2321
- * ``(t) => `https://api.example.com/durable/webhooks/${t}` ``). Populates
2322
- * {@link DurableWebhook.url}. Omit if you build URLs yourself from the token.
2345
+ * The customer this run belongs to (see {@link WorkflowRun.tenantId}). An explicit value always
2346
+ * wins; `null` starts it with no tenant. Omit it and the run takes the context tenant when tenancy
2347
+ * is on, else none.
2323
2348
  */
2324
- webhookUrl?: ((token: string) => string) | undefined;
2349
+ tenantId?: string | null | undefined;
2350
+ /** The kind of {@link tenantId} (`organization`, `user`, …). Only read with an explicit `tenantId`. */
2351
+ tenantKind?: string | undefined;
2352
+ }
2353
+ /**
2354
+ * Serialize runs of a workflow that share a key — a durable, FIFO mutex (e.g. one pipeline per base).
2355
+ * Excess runs are admitted in creation order, `limit` at a time; the rest wait (suspended) and retry
2356
+ * admission on a timer until a slot frees. The store atomically reserves durable slots before
2357
+ * ordering unadmitted waiters by `(createdAt, id)`, so later starts cannot displace a holder.
2358
+ */
2359
+ interface SingletonConfig {
2360
+ /** Derive the serialization key from the workflow input. */
2361
+ key: (input: unknown) => string;
2362
+ /** Max concurrent runs sharing the key. Default 1 (a mutex). */
2363
+ limit?: number;
2325
2364
  /**
2326
- * Provide the current W3C `traceparent` to stamp on each dispatched {@link RemoteTask}, so a
2327
- * worker (including the Python SDK) continues the distributed trace. Keep core OTel-free: supply
2328
- * `otelTraceparent` from `@dudousxd/nestjs-durable-otel`, or your own context reader. Omit to send none.
2365
+ * Max GATED (waiting-for-admission) runs allowed to queue behind the `limit` in-flight ones. When
2366
+ * set, `start` rejects with {@link SingletonQueueFullError} once in-flight + gated reaches
2367
+ * `limit + maxQueueDepth` — back-pressure against an unbounded same-key backlog. Omit for the
2368
+ * default unbounded queue. Counts pending/running/suspended/blocked/cancelling runs sharing the key.
2329
2369
  */
2330
- traceparent?: (() => string | undefined) | undefined;
2370
+ maxQueueDepth?: number;
2371
+ }
2372
+ /**
2373
+ * Stamped on a run whose workflow version NOBODY declared: a remote resolved by convention, served
2374
+ * by a worker that announces no version for it (an SDK too old to publish a descriptor, or a body
2375
+ * whose author simply never stated one).
2376
+ *
2377
+ * ## Why a run has to carry this
2378
+ *
2379
+ * Such a run's `workflowVersion` is `'1'`, the engine's convention default. That value is a routing
2380
+ * placeholder, not an observation — and read back later it is indistinguishable from a worker that
2381
+ * genuinely declared version `'1'`. Any check comparing an authored pin against it therefore passes
2382
+ * whenever the pin is `'1'` and fails whenever it is not, regardless of what the callee actually is.
2383
+ * A check that cannot fail is worse than no check, because it reads as a guarantee.
2384
+ *
2385
+ * The tag is the difference, carried ON the run so a retrospective check needs no second read: a
2386
+ * caller that pinned a version can see that the version it is comparing against was never stated,
2387
+ * and say so, instead of reporting a match it did not really make. It is deliberately a tag rather
2388
+ * than a new column — every store already persists and queries tags, so this needs no migration and
2389
+ * shows up in run listings and dashboards for free. Follows the `singleton:<key>` precedent for an
2390
+ * engine-stamped reserved tag.
2391
+ *
2392
+ * A run whose callee DOES declare a version never carries it; that run's version is the declared one
2393
+ * and a pin against it is genuinely checked.
2394
+ */
2395
+ declare const VERSION_UNDECLARED_TAG = "version:undeclared";
2396
+ /**
2397
+ * The `error.code` of a run a tenant started while no live worker served it yet (see
2398
+ * `WorkflowEngine.startForTenant`). The run is parked `blocked` and the blocked-recovery poll starts
2399
+ * it as soon as a worker on its group (declaring its pinned version, when it has one) is live. It is
2400
+ * never dead-lettered for waiting: a start is a request queued for its consumer, however late that
2401
+ * consumer boots. Cancel it to drop it.
2402
+ */
2403
+ declare const NO_LIVE_WORKER = "no_live_worker";
2404
+ /**
2405
+ * How long an adopted tenant schedule may go unannounced by every live worker of its app before the
2406
+ * control plane pauses it (see `WorkflowEngine.syncAnnouncedSchedules`). Long enough to ride out a
2407
+ * rolling deploy; a schedule is never deleted for missing.
2408
+ */
2409
+ declare const DEFAULT_ANNOUNCED_SCHEDULE_GRACE_MS: number;
2410
+ interface WorkflowEngineDeps {
2411
+ store: StateStore;
2412
+ /** A single task transport. Shorthand for a one-entry `transports` pool (id `default`). */
2413
+ transport?: Transport | undefined;
2331
2414
  /**
2332
- * Provide an opaque context carrier (tenant / user / correlation ids) to attach to each dispatched
2333
- * {@link RemoteTask} as its `context`, so a worker (including the Python SDK) re-exposes it to the
2334
- * step handler — cross-process propagation alongside the {@link traceparent}. Keep core dependency-free:
2335
- * supply this from `@dudousxd/nestjs-context` or your own request-scoped reader. The engine never
2336
- * inspects the returned object's shape. Omit to send none.
2337
- *
2338
- * Re-evaluated at each (re)dispatch — including a retry or a resume that the engine drives AFTER a
2339
- * crash/scale-down, which runs OUTSIDE the originating request scope. On such a path this provider
2340
- * may return empty or stale values (the request-scoped tenant/user is gone). Treat the carrier as
2341
- * best-effort correlation/propagation metadata only — do NOT treat it as an authorization boundary.
2415
+ * An ordered pool of named transports. The engine dispatches on the first and fails over to the
2416
+ * next on a dispatch error; a step pins one via `ctx.step(step, input, { transport: id })`. Use
2417
+ * this instead of `transport` for failover / multi-broker setups.
2342
2418
  */
2343
- context?: (() => Record<string, unknown> | undefined) | undefined;
2419
+ transports?: NamedTransport[] | undefined;
2344
2420
  /**
2345
- * Re-hydrate the originating context around a LOCAL step body, so a `@Step` reader sees the
2346
- * tenant / user / correlation ids that were live when the run was started — even on a path the
2347
- * engine drives outside the originating request scope (a resume after crash/scale-down, a timer).
2348
- * Given the carrier produced by {@link context} (may be empty/undefined) and the step body `fn`, it
2349
- * runs `fn` with that context ambiently established (e.g. inside `@dudousxd/nestjs-context`'s ALS)
2350
- * and returns its result. Keep core dependency-free: supply this from the nestjs wiring (which owns
2351
- * nestjs-context) or your own ALS bridge. The handler signature is unchanged — re-hydration is
2352
- * ambient. Default: passthrough (`(_, fn) => fn()`), so behavior is byte-identical when unset.
2421
+ * Cross-instance broadcast pub/sub for lifecycle events + cancellation (see {@link ControlPlane}).
2422
+ * Separate from the task `transport`; omit for a single-instance / local-only setup. A transport
2423
+ * that can also broadcast may be passed here as well.
2353
2424
  */
2354
- rehydrate?: (<T>(carrier: Record<string, unknown> | undefined, fn: () => T) => T) | undefined;
2425
+ controlPlane?: ControlPlane | undefined;
2426
+ /** Epoch-ms clock; injectable for tests. Defaults to `Date.now`. */
2427
+ clock?: (() => number) | undefined;
2355
2428
  /**
2356
- * Tenancy (the customer a run belongs to): how to read the context tenant at `start`, the matching
2357
- * filter for app-facing reads and control calls, and how to restore a run's tenant around each of
2358
- * its turns. Supplied by the NestJS module from `@dudousxd/nestjs-context`. Unset = tenancy off:
2359
- * runs carry only an explicit `StartOptions.tenantId` and no read is filtered.
2429
+ * Flow-control admission backend for `ctx.step(step, input, { queue })`. Defaults to an in-process
2430
+ * {@link InMemoryAdmissionBackend} (per-instance caps). Inject a store/Redis-backed backend to make
2431
+ * concurrency / rate-limit / ordering GLOBAL across engine replicas.
2360
2432
  */
2361
- tenancy?: EngineTenancy | undefined;
2433
+ admission?: AdmissionBackend | undefined;
2434
+ /** Unique id for this engine instance, used for recovery leases. Defaults to a random id. */
2435
+ instanceId?: string | undefined;
2362
2436
  /**
2363
- * Attempts for each saga compensation when the run fails (a transient undo — e.g. a refund API
2364
- * hiccup — gets another try). Default 1 (no retry). Compensations must be idempotent.
2437
+ * Worker-pool partition for this engine. Stamped on every run it creates; the poll paths
2438
+ * (`runPending`/`recoverIncomplete`/`resumeDueTimers`/`sweepTimeouts`) only act on runs in this
2439
+ * namespace. Set distinct values to safely share ONE state store across non-interchangeable pools
2440
+ * (e.g. local dev vs a cluster). **Omit it to make this engine an OPERATOR** — an unset namespace
2441
+ * drives/recovers/resumes runs of EVERY namespace (the poll filters no-op, the resume/decision
2442
+ * guards fall through) and leaves the transport on its bare prefix. This is the hosted control
2443
+ * plane: "ver tudo = ausência de namespace".
2365
2444
  */
2366
- compensationRetries?: number | undefined;
2445
+ namespace?: string | undefined;
2446
+ /**
2447
+ * Verifies the signed tenant token a store-less tenant worker presents in the `tenant` field of a
2448
+ * {@link StartRunMessage}, and DERIVES the run's namespace from it (see `hmacTenantVerifier`).
2449
+ * A message whose token is rejected (or whose verifier throws) is dropped without creating a run.
2450
+ * Absent: the wire `tenant` is trusted verbatim, as before.
2451
+ */
2452
+ verifyTenant?: TenantVerifier | undefined;
2453
+ /** Recovery lease duration in ms — how long this instance owns a run it picked up. Default 30s. */
2454
+ leaseMs?: number | undefined;
2455
+ /**
2456
+ * Cap how many times crash-recovery may pick up the same still-`running` run before giving up and
2457
+ * moving it to the `dead` dead-letter state (a poison pill that crashes the process every boot).
2458
+ * Omit for unlimited (the default — recovery always retries).
2459
+ */
2460
+ maxRecoveryAttempts?: number | undefined;
2461
+ /**
2462
+ * How long (ms) a run may stay due while NO instance can resume it because its workflow version is
2463
+ * not registered anywhere, before it is moved to `dead` (code `workflow_not_registered`). A rolling
2464
+ * deploy skips such a run on purpose (skew protection): the pod still on the prior version picks it
2465
+ * up within seconds. A run that stays unresumable far past that — its workflow was renamed or
2466
+ * deleted — would otherwise be retried and logged on every tick forever. The clock starts when the
2467
+ * run became due (its `wakeAt` for a parked run, its last update otherwise), so a long sleep is not
2468
+ * counted. Default 24h; `0` disables (skip forever). A non-finite or negative value falls back to
2469
+ * the default.
2470
+ */
2471
+ unregisteredWorkflowGraceMs?: number | undefined;
2472
+ /**
2473
+ * Opt-in liveness deadline (ms) for a remote workflow `advance`. If the worker neither returns a
2474
+ * decision NOR sends a run-scoped {@link Heartbeat} within this window, the engine presumes it dead:
2475
+ * it rejects the advance with {@link RemoteWorkflowTimeout}, releases the lease, and lets recovery
2476
+ * re-drive (replaying completed steps from history). Each beat REARMS the window, so a worker still
2477
+ * legitimately replaying a long turn (it keeps beating) is never re-driven — closing the duplicate-
2478
+ * side-effect hazard a fixed {@link RemoteWorkflowExecutor} `timeoutMs` cannot avoid. Omit (default)
2479
+ * for the prior unbounded await — byte-identical behavior when unset. If a `RemoteWorkflowExecutor` is
2480
+ * ALSO constructed with its own `timeoutMs`, the shorter of the two deadlines wins; prefer setting only
2481
+ * one (this rearmed window for heartbeat-aware workers, or the fixed `timeoutMs` otherwise).
2482
+ *
2483
+ * A turn DISPATCHED over a broker (a tenant's or another SDK's worker) is never left without a
2484
+ * deadline: unset, its window is {@link reconcileMs} (5 min by default), so a run whose worker died
2485
+ * holding the turn is re-driven instead of waiting forever. `reconcileMs: 0` with this unset keeps
2486
+ * the old unbounded wait.
2487
+ */
2488
+ remoteAdvanceSilenceMs?: number | undefined;
2489
+ /**
2490
+ * Fallback re-drive window (ms) for a run that SUSPENDS with no natural timer — i.e. it's waiting on
2491
+ * an EVENT to wake it (a child's completion, a signal, a remote step with no `timeoutMs`) rather than
2492
+ * a `ctx.sleep`. Those events re-drive the run directly; but if the wake is LOST (the delivering pod
2493
+ * crashed / rolled mid-handoff), the run would otherwise sit `suspended` forever with `wakeAt: null` —
2494
+ * invisible to both the timer poller (no `wakeAt`) and crash-recovery (no lease). This stamps a
2495
+ * fallback `wakeAt` so {@link resumeDueTimers} re-drives it after the window; the re-drive is an
2496
+ * idempotent replay (a still-pending dependency re-suspends via the checkpoint guard, a settled one
2497
+ * advances), so it's a safe self-heal, not a retry that can double-dispatch. The primary event path
2498
+ * still wins first for a healthy run (it re-drives long before this fires), so this only ever fires
2499
+ * for a genuinely-orphaned run. Default 5min; set `0` to disable (the prior wake-forever behavior).
2500
+ *
2501
+ * Also the default re-drive window of a workflow turn dispatched to a remote worker when
2502
+ * {@link remoteAdvanceSilenceMs} is unset (see there).
2503
+ */
2504
+ reconcileMs?: number | undefined;
2505
+ /**
2506
+ * How long an in-flight run must sit untouched, with the stranded signature (a wake-forever
2507
+ * suspension, or an old pending remote step with no live lease), before the
2508
+ * {@link WorkflowEngine.onStalled} listeners are notified. Default 900 000 (15 min); floored at
2509
+ * 60 000. The sweep ({@link WorkflowEngine.sweepStalled}) only does work when a listener is
2510
+ * registered.
2511
+ */
2512
+ stalledAfterMs?: number | undefined;
2513
+ /**
2514
+ * The most due timers one {@link WorkflowEngine.resumeDueTimers} pass loads and drives, most
2515
+ * overdue first. Every driving instance runs that pass each tick, so a wave of thousands of due
2516
+ * runs (a recovery after an outage, a fan's children waking together) is worked through in
2517
+ * batches instead of every instance loading and walking all of it. Default 500.
2518
+ */
2519
+ timerBatchSize?: number | undefined;
2520
+ /**
2521
+ * Retention for a BUFFERED event that no `waitForEvent` ever claims (see
2522
+ * {@link WorkflowEngine.publishEvent}'s buffering — a publish matching no live waiter keeps ONE
2523
+ * copy around for a later matching wait). Default `undefined`: keep it until consumed, same as
2524
+ * {@link StateStore.bufferSignal}'s buffered signals — no silent expiry. Set a duration (ms) to
2525
+ * have the {@link resumeDueTimers} reconcile pass prune rows past `publishedAt + eventBufferTtlMs`
2526
+ * as it encounters them. Scoped to event NAMES the current reconcile tick's registered waiters
2527
+ * reference (the sweep has no reason to otherwise enumerate every buffered name) — a name with a
2528
+ * stale buffered event but zero waiters ever registered against it is not visited by this pass; that
2529
+ * is an accepted gap given `listBufferedEvents` is name-scoped by design (see interfaces.ts), not a
2530
+ * bug to route around here.
2531
+ */
2532
+ eventBufferTtlMs?: number | undefined;
2533
+ /**
2534
+ * How long `signal(token, payload, { id })` remembers an `id` (ms, or a duration like `'7d'`): a
2535
+ * re-send with the same token and id within it is dropped. Records past it are ignored, and
2536
+ * {@link WorkflowEngine.sweepExpiredSignalIds} deletes them. Keep it longer than any sender's
2537
+ * redelivery window. Default 7 days; a call can pass its own `idTtl`.
2538
+ */
2539
+ signalIdTtl?: string | number | undefined;
2540
+ /**
2541
+ * Opt-in self-heal window (ms) for a remote step with NO `timeoutMs` whose dispatched job was LOST —
2542
+ * the worker crashed mid-step leaving no result, or the transport dropped the job (a Redis
2543
+ * flush/eviction, or BullMQ moving a stalled job to `failed` and removing it). The `pending`
2544
+ * checkpoint then has no result to resume on, and — BY DESIGN (see {@link reconcileMs}) — the
2545
+ * reconcile re-drive re-suspends a still-pending step rather than re-dispatching, so a slow-but-live
2546
+ * worker is never double-run. That safety means a genuinely-lost dispatch would otherwise hang
2547
+ * forever. When set, a reconcile re-drive that finds a remote step still `pending` PAST this window
2548
+ * re-dispatches it (bumping `attempts`, bounded by {@link remoteRedispatchMax}). Off by default:
2549
+ * re-dispatch can double-run a step whose original job is merely slow, so the window MUST exceed the
2550
+ * longest such step and the step MUST be idempotent. Prefer a per-step `timeoutMs` (tighter,
2551
+ * heartbeat-aware) where you can; this is the store-driven net for no-timeout steps that must
2552
+ * survive a lost dispatch. {@link WorkflowEngine.redispatchPending} is the manual counterpart.
2553
+ */
2554
+ remoteRedispatchMs?: number | undefined;
2555
+ /**
2556
+ * Max times {@link remoteRedispatchMs} re-dispatches one lost remote step before giving up and
2557
+ * failing it as a {@link RemoteStepError} (`code: 'remote_step_lost'`), so the run fails / dead-letters
2558
+ * instead of re-dispatching forever. Default 10. Ignored when `remoteRedispatchMs` is unset.
2559
+ */
2560
+ remoteRedispatchMax?: number | undefined;
2561
+ /**
2562
+ * How long (ms) a run parked `blocked` (no capability-capable + protocol-compatible live worker,
2563
+ * handshake design §7.5) waits before the blocked-recovery poll re-drives it to re-check the live
2564
+ * fleet. Default 5000. The run proceeds the moment a capable+compatible worker appears; until then it
2565
+ * re-parks with a fresh `wakeAt` each poll. Only relevant once a step/workflow declares `requires`
2566
+ * AND descriptors are published (a legacy fleet never parks blocked).
2567
+ */
2568
+ blockedPollMs?: number | undefined;
2569
+ /**
2570
+ * How long (ms) the routing guard reuses the worker descriptors it read for a queue token before
2571
+ * reading them again. Every dispatch consults them, and on BullMQ each read is a `SCAN` of the
2572
+ * Redis keyspace; workers rewrite their descriptor every 10 s with a 35 s TTL, so a couple of
2573
+ * seconds of reuse changes nothing the guard can observe. Concurrent reads of one token share a
2574
+ * single request. Default 2000; `0` reads on every dispatch.
2575
+ */
2576
+ workerDescriptorCacheMs?: number | undefined;
2577
+ /**
2578
+ * Build the public callback URL for a `ctx.webhook()` token (e.g.
2579
+ * ``(t) => `https://api.example.com/durable/webhooks/${t}` ``). Populates
2580
+ * {@link DurableWebhook.url}. Omit if you build URLs yourself from the token.
2581
+ */
2582
+ webhookUrl?: ((token: string) => string) | undefined;
2583
+ /**
2584
+ * Provide the current W3C `traceparent` to stamp on each dispatched {@link RemoteTask}, so a
2585
+ * worker (including the Python SDK) continues the distributed trace. Keep core OTel-free: supply
2586
+ * `otelTraceparent` from `@dudousxd/nestjs-durable-otel`, or your own context reader. Omit to send none.
2587
+ */
2588
+ traceparent?: (() => string | undefined) | undefined;
2589
+ /**
2590
+ * Provide an opaque context carrier (tenant / user / correlation ids) to attach to each dispatched
2591
+ * {@link RemoteTask} as its `context`, so a worker (including the Python SDK) re-exposes it to the
2592
+ * step handler — cross-process propagation alongside the {@link traceparent}. Keep core dependency-free:
2593
+ * supply this from `@dudousxd/nestjs-context` or your own request-scoped reader. The engine never
2594
+ * inspects the returned object's shape. Omit to send none.
2595
+ *
2596
+ * Re-evaluated at each (re)dispatch — including a retry or a resume that the engine drives AFTER a
2597
+ * crash/scale-down, which runs OUTSIDE the originating request scope. On such a path this provider
2598
+ * may return empty or stale values (the request-scoped tenant/user is gone). Treat the carrier as
2599
+ * best-effort correlation/propagation metadata only — do NOT treat it as an authorization boundary.
2600
+ */
2601
+ context?: (() => Record<string, unknown> | undefined) | undefined;
2602
+ /**
2603
+ * Re-hydrate the originating context around a LOCAL step body, so a `@Step` reader sees the
2604
+ * tenant / user / correlation ids that were live when the run was started — even on a path the
2605
+ * engine drives outside the originating request scope (a resume after crash/scale-down, a timer).
2606
+ * Given the carrier produced by {@link context} (may be empty/undefined) and the step body `fn`, it
2607
+ * runs `fn` with that context ambiently established (e.g. inside `@dudousxd/nestjs-context`'s ALS)
2608
+ * and returns its result. Keep core dependency-free: supply this from the nestjs wiring (which owns
2609
+ * nestjs-context) or your own ALS bridge. The handler signature is unchanged — re-hydration is
2610
+ * ambient. Default: passthrough (`(_, fn) => fn()`), so behavior is byte-identical when unset.
2611
+ */
2612
+ rehydrate?: (<T>(carrier: Record<string, unknown> | undefined, fn: () => T) => T) | undefined;
2613
+ /**
2614
+ * Tenancy (the customer a run belongs to): how to read the context tenant at `start`, the matching
2615
+ * filter for app-facing reads and control calls, and how to restore a run's tenant around each of
2616
+ * its turns. Supplied by the NestJS module from `@dudousxd/nestjs-context`. Unset = tenancy off:
2617
+ * runs carry only an explicit `StartOptions.tenantId` and no read is filtered.
2618
+ */
2619
+ tenancy?: EngineTenancy | undefined;
2620
+ /**
2621
+ * Attempts for each saga compensation when the run fails (a transient undo — e.g. a refund API
2622
+ * hiccup — gets another try). Default 1 (no retry). Compensations must be idempotent.
2623
+ */
2624
+ compensationRetries?: number | undefined;
2367
2625
  /**
2368
2626
  * Persist a `running` checkpoint when a local step's body begins, so an in-flight step shows up
2369
2627
  * in the dashboard (and a fresh page load / REST query) the moment it starts — not only once it
@@ -2977,6 +3235,20 @@ declare class WorkflowEngine {
2977
3235
  */
2978
3236
  listStalledRuns(options?: ListStalledRunsOptions): Promise<StalledRunInfo[]>;
2979
3237
  private notifyDead;
3238
+ /**
3239
+ * The dead-letter workflow the live workers serving `run`'s workflow announce (a tenant's inline
3240
+ * `@DeadLetter()` handler, its `deadLetterWorkflow`, or its module-level default), or `undefined`
3241
+ * when the workflow is registered on this engine (its own routing applies), they announce none, or
3242
+ * they cannot be read. A dead-letter listener with a catch-all default (`DurableModule`'s
3243
+ * `deadLetterWorkflow`) checks it first, so the app's own route wins over the default.
3244
+ */
3245
+ announcedDeadLetter(run: WorkflowRun): Promise<string | undefined>;
3246
+ /**
3247
+ * Start the announced dead-letter workflow of a dead run (see {@link announcedDeadLetter}) in the
3248
+ * run's namespace, as `dlq:<runId>` with the `DeadLetter` payload, through the tenant start path:
3249
+ * with no live worker of the app it waits `blocked` instead of being lost. Idempotent by run id.
3250
+ */
3251
+ private routeAnnouncedDeadLetter;
2980
3252
  /**
2981
3253
  * Emit a locally-produced lifecycle event: deliver to subscribers AND broadcast it on the control
2982
3254
  * plane so other instances (e.g. a dashboard pod) can live-tail this run. A `run.completed` or
@@ -3337,6 +3609,32 @@ declare class WorkflowEngine {
3337
3609
  * redelivery is a no-op once the run exists (idempotent by run id).
3338
3610
  */
3339
3611
  startForTenant(message: StartRunMessage, namespace: string, tenant: Pick<StartOptions, 'tenantId' | 'tenantKind'>): Promise<RunResult>;
3612
+ /**
3613
+ * The control plane's half of a tenant's `signalWithStart` (a `signalWithStart` run request):
3614
+ * start `start` like {@link startForTenant} unless its run exists, then signal `signal.token`.
3615
+ * Authorization is the caller's (the run-request responder): the run must belong to `namespace`,
3616
+ * and so must a run already waiting on the token. Delivered at once to a waiting run; with none
3617
+ * waiting yet it is buffered only when the token contains the run id (a run-scoped token), so a
3618
+ * tenant can never plant a payload for a wait another namespace opens later. `signalled: false`
3619
+ * when it was neither delivered nor buffered.
3620
+ */
3621
+ signalWithStartForTenant(start: StartRunMessage & {
3622
+ runId: string;
3623
+ }, namespace: string, tenant: Pick<StartOptions, 'tenantId' | 'tenantKind'>, signal: {
3624
+ token: string;
3625
+ payload?: unknown;
3626
+ }): Promise<{
3627
+ runId: string;
3628
+ signalled: boolean;
3629
+ }>;
3630
+ /**
3631
+ * The control plane's half of a tenant's `publishEvent` (a `publishEvent` run request): resume the
3632
+ * runs of `namespace` waiting on event `name` whose match the payload satisfies. Starting the
3633
+ * tenant's own subscribers is the tenant's (it holds their `where` and `input`); nothing is
3634
+ * buffered, since a buffered event could reach another namespace's later wait. Returns how many
3635
+ * runs it resumed.
3636
+ */
3637
+ publishEventForTenant(name: string, payload: unknown, namespace: string): Promise<number>;
3340
3638
  /** A tenant start {@link startForTenant} could not admit, kept as a `failed` run with the reason. */
3341
3639
  private recordRejectedStart;
3342
3640
  /**
@@ -3505,6 +3803,15 @@ declare class WorkflowEngine {
3505
3803
  * liveness changes between calls, exactly as {@link synthesizeRemoteChild} does.
3506
3804
  */
3507
3805
  private resolveRemoteByConvention;
3806
+ /**
3807
+ * The registration the live workers of `group` announce for `workflow` (at `version`, when one of
3808
+ * them states it): where they disagree (a rolling deploy), the one from the worker that started
3809
+ * last, as for announced schedules. `undefined` when none announces it, `null` when the read
3810
+ * failed (what the workers state is then unknown, not "nothing"). Reads
3811
+ * through the descriptor cache ({@link workerDescriptorCacheMs}), so a turn costs no extra round
3812
+ * trip in steady state.
3813
+ */
3814
+ private announcedRegistration;
3508
3815
  /**
3509
3816
  * The version the LIVE fleet declares for `workflow` on `group`, or `undefined` when it declares
3510
3817
  * none — which is a fact about the fleet, not a failure to read it.
@@ -3614,6 +3921,24 @@ declare class WorkflowEngine {
3614
3921
  * child: one unreachable child must not abort the sweep and leave every LATER timed-out run alive.
3615
3922
  */
3616
3923
  sweepTimeouts(now?: number): Promise<void>;
3924
+ /**
3925
+ * The singleton limit last resolved for a workflow served by convention, by `<namespace>\0<name>`
3926
+ * (see {@link resolveRemoteByConvention}): what the singleton gate's release wake-up reads, since
3927
+ * it cannot wait on the fleet. One entry per convention singleton the fleet serves.
3928
+ */
3929
+ private readonly conventionSingletonLimits;
3930
+ /** The last read of the announced execution timeouts (see {@link announcedTimeouts}). */
3931
+ private announcedTimeoutsRead;
3932
+ /**
3933
+ * The `executionTimeoutMs` live workers announce (`@Workflow({ executionTimeout })` on a tenant),
3934
+ * per workflow and namespace, for workflows this engine does not register (a registration here
3935
+ * applies its own). Where workers disagree, the one that started last wins. Read at most once per
3936
+ * {@link ANNOUNCED_TIMEOUTS_TTL_MS}; empty without a transport that reads the fleet, or when the
3937
+ * read fails.
3938
+ */
3939
+ private announcedTimeouts;
3940
+ /** Cancel (`execution_timeout`) the in-flight runs of `workflow` in `namespace` created before `deadline`. */
3941
+ private cancelTimedOut;
3617
3942
  /**
3618
3943
  * Resume every run left incomplete by a crash or deploy. Called on boot. Completed steps
3619
3944
  * replay from their checkpoints, so only the work that had not finished runs again.
@@ -4812,399 +5137,186 @@ declare class WorkflowEngine {
4812
5137
  * dispatch, the opt-in self-heal re-dispatch (see `remoteRedispatchMs`), and the explicit
4813
5138
  * {@link redispatchPending}. Carries the current trace/context so a re-dispatch is traceable. */
4814
5139
  private dispatchRemoteTask;
4815
- /**
4816
- * Run `work` after every earlier `work` for the same run on this instance has settled. A result
4817
- * resumes its run inline, and `execute` lets this instance into a lease it already holds — so two
4818
- * results of one run handled at once here would run two turns of it concurrently. Results of
4819
- * different runs still go in parallel, which is what a results consumer with concurrency > 1 is for.
4820
- */
4821
- private serializedPerRun;
4822
- /**
4823
- * Complete a durable remote step from its worker result — runs on whichever instance receives the
4824
- * result (the dispatching one may be gone), so the run is crash/scale-safe. Resolves whether the
4825
- * run should now be resumed: not for a duplicate or late delivery (the checkpoint isn't `pending`),
4826
- * a run already finished, or a step fan whose barrier is still closed.
4827
- *
4828
- * Results of one run are settled in batches: the first starts a batch, and the ones that arrive
4829
- * while it is being written form the next. Under load a wide fan's results are written by one
4830
- * {@link StateStore.saveCheckpointsIfPending} call per batch, and the fan's barrier is asked only
4831
- * by a batch with no more of the fan's results queued behind it. A result resolves only once its
4832
- * own write has committed, so the transport acknowledges nothing that is not durable yet. How
4833
- * large a batch gets is bounded by how many results the transport hands over at once.
4834
- */
4835
- private completeRemoteResult;
4836
- /** Settle `queue` (a run's queued results) batch by batch until it is empty, then retire it. */
4837
- private drainResultQueue;
4838
- /**
4839
- * Settle a batch of one run's step results. At most one of them resolves `true` (resume the run):
4840
- * that resume replays every write of the batch, so a second would only replay it again. A result
4841
- * whose read or write failed resolves its error, and the transport redelivers just that one.
4842
- *
4843
- * `queuedIn(from, to)` says whether a result for a seq in that range is already waiting for this
4844
- * run's next batch on this instance. A fan with one waiting is not asked its barrier: that result
4845
- * asks it once its own batch is written (as a settle, or as a redelivery of a settled step), so
4846
- * under a backlog the barrier is read once per drained queue rather than once per batch.
4847
- */
4848
- private completeRemoteResults;
4849
- /**
4850
- * {@link completeRemoteResults} on a store with {@link StateStore.settleResultsIfPending}: the
4851
- * results settle their `pending` rows and read them back in one call, instead of a read of the rows
4852
- * followed by the write. Only an entry that wrote nothing (a redelivery, or a step gone) is read
4853
- * afterwards. A settled `completed` row is also handed to the run's parked body, if this instance
4854
- * holds one, so its next turn does not read it again.
4855
- */
4856
- private settleResultsReturning;
4857
- /**
4858
- * The outcomes for a batch of redelivered results (their steps already settled): one of them
4859
- * resumes the run if it is `suspended` and, for a step of a fan, the fan's barrier is open. A
4860
- * resume of a run that had in fact moved on replays to its current wait and re-parks.
4861
- */
4862
- private resumeForRedelivered;
4863
- /**
4864
- * The join barrier of a step fan: a result for one of its steps resumes the parent only once no
4865
- * step of the fan is still `pending` (a settled wave), or on a failure (failFast surfaces it, and a
4866
- * retry needs the parent to schedule it). Without it every result would replay the whole parent,
4867
- * which makes a fan of N steps cost O(N²) checkpoint reads. `barriers` holds the answer per fan
4868
- * for the rest of a batch. A barrier that cannot be read counts as open: a spare resume replays and
4869
- * re-suspends, a lost one strands the run. A fan with a result waiting in `queuedIn` is left to
4870
- * that result (see {@link completeRemoteResults}).
4871
- */
4872
- private stepFanStillRunning;
4873
- /** Whether any step of a step fan's seq range is still `pending`. */
4874
- private stepFanHasPending;
4875
- /**
4876
- * Apply a remote workflow-turn {@link WorkflowDecision} durably — runs on WHATEVER instance receives
4877
- * it over the broker (the dispatching one may be gone, or a point-to-point broker handed it to a
4878
- * non-dispatcher). The durable, multi-instance-safe twin of {@link completeRemoteResult} for the
4879
- * workflow TURN: look the run up by `decision.runId`, verify the decision matches the run's
4880
- * CURRENTLY-awaited turn (`awaitingDecisionTaskId`) — so a stale / duplicate / foreign / re-driven
4881
- * decision is dropped (applied AT MOST ONCE) — lease it, clear the marker, and apply the decision.
4882
- */
4883
- private completeRemoteDecision;
4884
- /** Earliest clock time a suspended turn's deadline is worth LOOKING at again (`runId` → clock ms) —
4885
- * the read throttle for {@link rearmDecisionDeadline}, the run-scoped sibling of
4886
- * {@link stepLeaseRearms}. */
4887
- private readonly decisionDeadlineRearms;
4888
- /**
4889
- * A run-scoped heartbeat for a run suspended awaiting a workflow-turn decision (the dispatch path):
4890
- * push its durable re-drive deadline (`wakeAt`) forward so a still-working worker's turn is not
4891
- * re-dispatched. The durable counterpart of an inline turn's in-memory `heartbeatResets` rearm.
4892
- *
4893
- * THROTTLED exactly as {@link rearmStepLease} is, and for the same reason: a long workflow turn's
4894
- * worker beats every couple of seconds, and each beat otherwise cost a `getRun` + `updateRun`.
4895
- * The window here is `remoteAdvanceSilenceMs`, and a renewal buys at most one of them — so it is
4896
- * only worth a write once the window is half spent, which leaves a full half-window of headroom
4897
- * before the timer poller would re-drive the turn. The in-memory mark is a pure optimisation: a
4898
- * cold (or different) instance re-derives the same answer from the run's own `wakeAt`.
4899
- */
4900
- private rearmDecisionDeadline;
4901
- /**
4902
- * A slot freed on `queue` (a fleet-wide signal): resume this instance's runs blocked on it so they
4903
- * re-contend now instead of at their retry tick. Snapshot-and-clear — a run still blocked after the
4904
- * retry re-registers itself, and one that's gone (cancelled/admitted) is dropped. Best-effort.
4905
- */
4906
- private wakeQueueWaiters;
4907
- /** Release the flow-control slot a dispatched step held (if any), by its stepId. */
4908
- private releaseQueueSlot;
4909
- /** In-memory await path for a remote step with a liveness `timeoutMs` (re-dispatch on timeout). */
4910
- private callRemoteInMemory;
4911
- /**
4912
- * Await `resultPromise`, but reject with `onTimeout()` if neither it settles nor a heartbeat for `id`
4913
- * arrives within `timeoutMs`. Each heartbeat (delivered via `transport.onHeartbeat`, looked up in
4914
- * `heartbeatResets` by `id`) REARMS the window, so a worker that keeps beating stays alive past
4915
- * `timeoutMs`. Shared by the remote-STEP liveness (keyed by stepId) and the remote-WORKFLOW advance
4916
- * liveness (keyed by runId); the caller supplies the timeout error and any extra cleanup via `onTimeout`.
4917
- */
4918
- private awaitWithLivenessDeadline;
4919
- /** Remote-STEP liveness: await a worker result, timing out (with the step's pending-map cleanup) to
4920
- * `RemoteStepTimeout` if it neither lands nor beats within `timeoutMs`. See {@link awaitWithLivenessDeadline}. */
4921
- private awaitWithHeartbeat;
4922
- }
4923
- /** Raised inside the workflow when a remote worker reports a step failure. */
4924
- declare class RemoteStepError extends Error {
4925
- readonly stepError?: StepError | undefined;
4926
- constructor(stepError?: StepError);
4927
- }
4928
- /** Checkpoint names that record a parent→child edge: an awaited child, a folded group of them, a spawn. */
4929
- declare const CHILD_EDGE_PREFIXES: string[];
4930
- /** The child run ids a parent's {@link CHILD_EDGE_PREFIXES} checkpoints point at (others are skipped). */
4931
- declare function childIdsOf(checkpoints: StepCheckpoint[]): string[];
4932
-
4933
- /**
4934
- * A schedule definition — what `engine.schedules.create/upsert` take. Temporal-style: a persisted,
4935
- * runtime-managed recurring start of `workflow` with `input`, fired by every driving engine's timer
4936
- * poll (safe with many workers: each window's run id is deterministic, `start` is idempotent, and
4937
- * advancing the schedule is a compare-and-set).
4938
- */
4939
- interface ScheduleOptions {
4940
- /** Stable id, unique per store (e.g. `digest:user-42`). Part of every run id it starts. */
4941
- id: string;
4942
- /** The workflow to start — a registered name or `@Workflow` class. */
4943
- workflow: WorkflowRef;
4944
- /** The input every run starts with. */
4945
- input?: unknown;
4946
- /** Cron expression (5 fields, or 6 with leading seconds). Needs the `cron-parser` peer. */
4947
- cron?: string | undefined;
4948
- /** Fixed interval (`'15m'`, or ms), windows aligned to the epoch. Exclusive with `cron`. */
4949
- every?: string | number | undefined;
4950
- /**
4951
- * An RFC 5545 recurrence rule (`'FREQ=WEEKLY;BYDAY=MO;BYHOUR=8'`, optionally with a
4952
- * `DTSTART:…` line), evaluated in `timezone`. Exactly one of `cron`, `every` and `rrule`. See
4953
- * {@link parseRRule} for the supported parts. No peer needed.
4954
- */
4955
- rrule?: string | undefined;
4956
- /** IANA timezone the cron / rrule is evaluated in (e.g. `America/Sao_Paulo`). Default UTC. */
4957
- timezone?: string | undefined;
4958
- /**
4959
- * Delay each fire by up to this much (`'30s'` or ms) — a stable per-(schedule, window) offset, so
4960
- * thousands of schedules on the same cron don't all start in the same second.
4961
- */
4962
- jitter?: string | number | undefined;
4963
- /**
4964
- * The previous run of this schedule is still in flight when the next window comes due:
4965
- * `'allow'` (default) starts the new one anyway; `'skip'` skips that window.
4966
- */
4967
- overlap?: 'allow' | 'skip' | undefined;
4968
- /**
4969
- * Windows missed while nothing polled (all schedulers down): `'latest'` (default) fires the most
4970
- * recent missed window once; `'skip'` drops them and waits for the next window. Never more than one
4971
- * catch-up run per schedule.
4972
- */
4973
- catchup?: 'latest' | 'skip' | undefined;
4974
- /** Create paused (never due until `resume`). On `upsert`, omit to keep the current paused state. */
4975
- paused?: boolean | undefined;
4976
- /** Free-form note shown with the schedule (why it exists / why it's paused). */
4977
- note?: string | undefined;
4978
- /** Namespace of the schedule and of the runs it starts. Defaults to the engine's own namespace. */
4979
- namespace?: string | undefined;
4980
- /** Labels to find the schedule by — also stamped on every run it starts (plus `schedule:<id>`). */
4981
- tags?: string[] | undefined;
4982
- /** Search attributes stamped on every run it starts. */
4983
- searchAttributes?: SearchAttributes | undefined;
4984
- /** Dispatch priority for the runs it starts. */
4985
- priority?: number | undefined;
4986
- /**
4987
- * A start-time concurrency quota applied to every run it starts (see `StartOptions.concurrency`):
4988
- * a window whose start would exceed it is recorded as the schedule's `lastError` and skipped, and
4989
- * the schedule moves on to its next window.
4990
- */
4991
- concurrency?: ConcurrencyQuota | undefined;
4992
- /**
4993
- * The customer the schedule belongs to; every run it starts inherits it. An explicit value wins
4994
- * (`null` = none); omit it and the schedule takes the context tenant when tenancy is on. On
4995
- * `upsert`, omit to keep the schedule's current tenant.
4996
- */
4997
- tenantId?: string | null | undefined;
4998
- /** The kind of {@link tenantId}. Only read with an explicit `tenantId`. */
4999
- tenantKind?: string | undefined;
5000
- }
5001
- /** A schedule as `engine.schedules.get/list` describe it. */
5002
- interface ScheduleDescription {
5003
- id: string;
5004
- workflow: string;
5005
- input: unknown;
5006
- namespace: string;
5007
- cron?: string | undefined;
5008
- everyMs?: number | undefined;
5009
- rrule?: string | undefined;
5010
- timezone?: string | undefined;
5011
- jitterMs?: number | undefined;
5012
- overlap: 'allow' | 'skip';
5013
- catchup: 'latest' | 'skip';
5014
- paused: boolean;
5015
- note?: string | undefined;
5016
- tags?: string[] | undefined;
5017
- searchAttributes?: SearchAttributes | undefined;
5018
- priority?: number | undefined;
5019
- concurrency?: ConcurrencyQuota | undefined;
5020
- /** When it is next due (jitter included), or null if it never fires again / paused. */
5021
- nextFireAt: Date | null;
5022
- /** The last window it fired for, and the run that window started. */
5023
- lastFireAt?: Date | undefined;
5024
- lastRunId?: string | undefined;
5025
- /** How many windows it has fired (manual triggers excluded). */
5026
- fires: number;
5027
- /** The last start failure (e.g. a concurrency limit), cleared by the next successful start. */
5028
- lastError?: string | undefined;
5029
- /** The customer the schedule and its runs belong to, when it has one. */
5030
- tenantId?: string | undefined;
5031
- tenantKind?: string | undefined;
5032
- /**
5033
- * Set on a schedule a tenant app ANNOUNCED (its `schedules` module option) and the control plane
5034
- * adopted: the key the app declares it under. Its `namespace` is the app (partition).
5035
- */
5036
- announcedKey?: string | undefined;
5037
- /** An announced schedule that no live worker of its app announces any more: since when. */
5038
- unannouncedSince?: Date | undefined;
5039
- /** When the control plane paused it for staying unannounced past the grace period. */
5040
- withdrawnAt?: Date | undefined;
5041
- createdAt: Date;
5042
- updatedAt: Date;
5043
- }
5044
- /** The tag on every schedule adopted from a tenant's announcement (and on the runs it starts). */
5045
- declare const ANNOUNCED_SCHEDULE_TAG = "schedule:announced";
5046
- /** The control plane's schedule id for the schedule `key` announced by the app on `namespace`. */
5047
- declare function announcedScheduleId(namespace: string, key: string): string;
5048
- /** Filter for `engine.schedules.list`. */
5049
- type ScheduleListQuery = Omit<ScheduleQuery, 'dueBy'>;
5050
- /** Thrown by `engine.schedules.create` when the id is taken (use `upsert` to replace). */
5051
- declare class ScheduleAlreadyExistsError extends Error {
5052
- readonly scheduleId: string;
5053
- constructor(scheduleId: string);
5054
- }
5055
- /** Thrown by `engine.schedules.*` on an id that doesn't exist. */
5056
- declare class ScheduleNotFoundError extends Error {
5057
- readonly scheduleId: string;
5058
- constructor(scheduleId: string);
5059
- }
5060
- /** What {@link ScheduleClient.syncAnnounced} did to a namespace's adopted schedules. */
5061
- interface AnnouncedScheduleSync {
5062
- /** Created, or re-applied because the announced definition changed. */
5063
- adopted: string[];
5064
- /** Announced again after missing (and resumed, when it had been withdrawn). */
5065
- restored: string[];
5066
- /** Missing from the announcement for the first time: the grace period starts. */
5067
- missing: string[];
5068
- /** Paused because it stayed unannounced past the grace period. */
5069
- withdrawn: string[];
5070
- /** Announced, but the definition does not evaluate (bad cron, both or neither cadence). */
5071
- invalid: {
5072
- key: string;
5073
- error: string;
5074
- }[];
5075
- }
5076
- /** The engine surface the schedule client drives. */
5077
- interface ScheduleHost {
5078
- start(workflow: string, input: unknown, runId: string, opts?: StartOptions): Promise<RunResult>;
5079
- /**
5080
- * The tenant start path, used to fire an announced schedule: a workflow no live worker serves yet
5081
- * is parked `blocked` (`no_live_worker`) until one is, instead of throwing. Absent = `start`.
5082
- */
5083
- startParked?(workflow: string, input: unknown, runId: string, opts?: StartOptions): Promise<RunResult>;
5084
- getRun(runId: string): Promise<WorkflowRun | null>;
5085
- /** True once the engine has begun shutting down; `tick` fires nothing more after that. */
5086
- isDraining?(): boolean;
5087
- /** The context tenant to stamp on a schedule created now (tenancy on), else undefined. */
5088
- tenant?(): RunTenant | undefined;
5089
- /** The tenancy matching filter for an app-facing call made now. Absent = sees everything. */
5090
- tenantFilter?(): TenantFilter;
5091
- }
5092
- /** Engine-level knobs for the client. */
5093
- interface ScheduleClientOptions {
5094
- /** The engine's namespace: the default for new schedules, and which ones `tick` fires. */
5095
- namespace?: string | undefined;
5096
- clock?: (() => number) | undefined;
5097
- }
5098
- /**
5099
- * Persisted, runtime-managed schedules — `engine.schedules`. Unlike the code-registered
5100
- * `schedules` module option, these live in the store: create/update/pause/delete them at runtime
5101
- * (one per user, per tenant, per automation…), and every driving engine's timer poll fires the due
5102
- * ones via {@link tick}.
5103
- *
5104
- * Multi-worker safety comes from two properties, not from a lock: a window's run id is deterministic
5105
- * (`sched:<id>:<windowMs>`), so racing starts of the same window collapse into one run; and a
5106
- * schedule is advanced with a compare-and-set on its `nextFireAt`, so exactly one poller moves it on.
5107
- * A crash between starting the run and advancing the schedule just re-fires the (idempotent) start.
5108
- */
5109
- declare class ScheduleClient {
5110
- private readonly store;
5111
- private readonly host;
5112
- private readonly options;
5113
- constructor(store: StateStore, host: ScheduleHost, options?: ScheduleClientOptions);
5114
- private now;
5115
- /** Whether the store persists schedules (implements the schedule methods). */
5116
- get supported(): boolean;
5117
- private requireStore;
5118
- private filter;
5119
- /** The schedule `id` if it exists and the caller may see it (tenancy), else null. */
5120
- private visible;
5121
- /** Create a schedule. Throws {@link ScheduleAlreadyExistsError} if the id is taken. */
5122
- create(opts: ScheduleOptions): Promise<ScheduleDescription>;
5123
- /**
5124
- * Create the schedule, or replace the definition of an existing one (its history — last fire, last
5125
- * run, fire count — is kept). The next fire is recomputed from now under the new definition, so a
5126
- * window that already fired is never fired again by an upsert.
5140
+ /**
5141
+ * Run `work` after every earlier `work` for the same run on this instance has settled. A result
5142
+ * resumes its run inline, and `execute` lets this instance into a lease it already holds — so two
5143
+ * results of one run handled at once here would run two turns of it concurrently. Results of
5144
+ * different runs still go in parallel, which is what a results consumer with concurrency > 1 is for.
5127
5145
  */
5128
- upsert(opts: ScheduleOptions): Promise<ScheduleDescription>;
5129
- /** The schedule `id`, or null (also null for another tenant's schedule). */
5130
- get(id: string): Promise<ScheduleDescription | null>;
5131
- /** Schedules matching `query` (and visible to the caller's tenant), soonest-due first. */
5132
- list(query?: ScheduleListQuery): Promise<ScheduleDescription[]>;
5133
- /** Delete the schedule. Runs it already started are left alone. Returns whether it existed. */
5134
- delete(id: string): Promise<boolean>;
5135
- /** Stop firing until {@link resume}. `note` records why (shown by `get`/`list`). */
5136
- pause(id: string, note?: string): Promise<ScheduleDescription>;
5146
+ private serializedPerRun;
5137
5147
  /**
5138
- * Fire again from the next window after now — the windows skipped while paused are NOT caught up.
5148
+ * Complete a durable remote step from its worker result — runs on whichever instance receives the
5149
+ * result (the dispatching one may be gone), so the run is crash/scale-safe. Resolves whether the
5150
+ * run should now be resumed: not for a duplicate or late delivery (the checkpoint isn't `pending`),
5151
+ * a run already finished, or a step fan whose barrier is still closed.
5152
+ *
5153
+ * Results of one run are settled in batches: the first starts a batch, and the ones that arrive
5154
+ * while it is being written form the next. Under load a wide fan's results are written by one
5155
+ * {@link StateStore.saveCheckpointsIfPending} call per batch, and the fan's barrier is asked only
5156
+ * by a batch with no more of the fan's results queued behind it. A result resolves only once its
5157
+ * own write has committed, so the transport acknowledges nothing that is not durable yet. How
5158
+ * large a batch gets is bounded by how many results the transport hands over at once.
5139
5159
  */
5140
- resume(id: string): Promise<ScheduleDescription>;
5160
+ private completeRemoteResult;
5161
+ /** Settle `queue` (a run's queued results) batch by batch until it is empty, then retire it. */
5162
+ private drainResultQueue;
5141
5163
  /**
5142
- * Start one run of the schedule right now, outside its cadence (paused or not). The run id is
5143
- * `sched:<id>:manual:<nowMs>`; it doesn't move the schedule's next fire.
5164
+ * Settle a batch of one run's step results. At most one of them resolves `true` (resume the run):
5165
+ * that resume replays every write of the batch, so a second would only replay it again. A result
5166
+ * whose read or write failed resolves its error, and the transport redelivers just that one.
5167
+ *
5168
+ * `queuedIn(from, to)` says whether a result for a seq in that range is already waiting for this
5169
+ * run's next batch on this instance. A fan with one waiting is not asked its barrier: that result
5170
+ * asks it once its own batch is written (as a settle, or as a redelivery of a settled step), so
5171
+ * under a backlog the barrier is read once per drained queue rather than once per batch.
5144
5172
  */
5145
- trigger(id: string): Promise<RunResult>;
5173
+ private completeRemoteResults;
5146
5174
  /**
5147
- * Start one run of `record`: through the tenant start path for an announced schedule (its run waits
5148
- * `blocked` for a live worker of its app instead of failing), else a plain `start`.
5175
+ * {@link completeRemoteResults} on a store with {@link StateStore.settleResultsIfPending}: the
5176
+ * results settle their `pending` rows and read them back in one call, instead of a read of the rows
5177
+ * followed by the write. Only an entry that wrote nothing (a redelivery, or a step gone) is read
5178
+ * afterwards. A settled `completed` row is also handed to the run's parked body, if this instance
5179
+ * holds one, so its next turn does not read it again.
5149
5180
  */
5150
- private startFor;
5181
+ private settleResultsReturning;
5151
5182
  /**
5152
- * Fire every due schedule (in this engine's namespace; all namespaces for an operator engine; only
5153
- * those carrying `opts.tag` when given):
5154
- * start its window's run and advance it to the next window. Called by the NestJS timer poller on
5155
- * each tick when `persistedSchedules` is on; call it yourself from any other driver. Returns the
5156
- * run ids started (or re-found, for an idempotent re-fire).
5183
+ * The outcomes for a batch of redelivered results (their steps already settled): one of them
5184
+ * resumes the run if it is `suspended` and, for a step of a fan, the fan's barrier is open. A
5185
+ * resume of a run that had in fact moved on replays to its current wait and re-parks.
5157
5186
  */
5158
- tick(nowMs?: number, opts?: {
5159
- tag?: string;
5160
- }): Promise<string[]>;
5187
+ private resumeForRedelivered;
5161
5188
  /**
5162
- * When {@link tick} next has a schedule to fire, if one is due by `byMs`: the earliest `nextFireAt`
5163
- * of the unpaused schedules (of this engine's namespace, carrying `opts.tag` when given) due by
5164
- * then, else `undefined`. One indexed
5165
- * read (the due-schedule scan `tick` makes, with a later bound and a limit of one). A store that
5166
- * does not persist schedules has none.
5189
+ * The join barrier of a step fan: a result for one of its steps resumes the parent only once no
5190
+ * step of the fan is still `pending` (a settled wave), or on a failure (failFast surfaces it, and a
5191
+ * retry needs the parent to schedule it). Without it every result would replay the whole parent,
5192
+ * which makes a fan of N steps cost O(N²) checkpoint reads. `barriers` holds the answer per fan
5193
+ * for the rest of a batch. A barrier that cannot be read counts as open: a spare resume replays and
5194
+ * re-suspends, a lost one strands the run. A fan with a result waiting in `queuedIn` is left to
5195
+ * that result (see {@link completeRemoteResults}).
5167
5196
  */
5168
- nextFireAt(byMs: number, opts?: {
5169
- tag?: string;
5170
- }): Promise<number | undefined>;
5171
- /** Fire one due schedule and advance it. Returns the run id started, if any. */
5172
- private fire;
5197
+ private stepFanStillRunning;
5198
+ /** Whether any step of a step fan's seq range is still `pending`. */
5199
+ private stepFanHasPending;
5173
5200
  /**
5174
- * An announced schedule whose previous run is still parked waiting for a live worker of its app
5175
- * (the app is down): this window is folded into that run instead of parking one more. However long
5176
- * the app is down, it finds at most one run per schedule waiting when it comes back, the same
5177
- * bound `catchup: 'latest'` puts on windows missed while no scheduler polled.
5201
+ * Apply a remote workflow-turn {@link WorkflowDecision} durably — runs on WHATEVER instance receives
5202
+ * it over the broker (the dispatching one may be gone, or a point-to-point broker handed it to a
5203
+ * non-dispatcher). The durable, multi-instance-safe twin of {@link completeRemoteResult} for the
5204
+ * workflow TURN: look the run up by `decision.runId`, verify the decision matches the run's
5205
+ * CURRENTLY-awaited turn (`awaitingDecisionTaskId`) — so a stale / duplicate / foreign / re-driven
5206
+ * decision is dropped (applied AT MOST ONCE) — lease it, clear the marker, and apply the decision.
5178
5207
  */
5179
- private waitingForWorker;
5208
+ private completeRemoteDecision;
5209
+ /** Earliest clock time a suspended turn's deadline is worth LOOKING at again (`runId` → clock ms) —
5210
+ * the read throttle for {@link rearmDecisionDeadline}, the run-scoped sibling of
5211
+ * {@link stepLeaseRearms}. */
5212
+ private readonly decisionDeadlineRearms;
5180
5213
  /**
5181
- * Reconcile the schedules adopted from one app (`namespace`) with what its LIVE workers announce
5182
- * now (`items`, one per key; the caller resolved disagreeing workers). The rule:
5183
- * - an announced key with no schedule yet is created (id {@link announcedScheduleId}, tagged
5184
- * {@link ANNOUNCED_SCHEDULE_TAG}, `catchup: 'latest'`); one whose definition changed is
5185
- * re-applied like `upsert` (its history kept, its next fire recomputed from now). An equal
5186
- * definition writes nothing, so any number of replicas announcing the same set is a no-op;
5187
- * - a pause or resume made from the console survives: a re-applied definition keeps the current
5188
- * paused state, unless the app's own declared `paused` changed;
5189
- * - an adopted schedule the app no longer announces is marked missing, and paused ("withdrawn")
5190
- * once it has stayed missing for `graceMs`. It is never deleted: its history stays, and an app
5191
- * that announces it again (a rollback) gets it back, resumed unless an operator had paused it.
5214
+ * A run-scoped heartbeat for a run suspended awaiting a workflow-turn decision (the dispatch path):
5215
+ * push its durable re-drive deadline (`wakeAt`) forward so a still-working worker's turn is not
5216
+ * re-dispatched. The durable counterpart of an inline turn's in-memory `heartbeatResets` rearm.
5192
5217
  *
5193
- * Call it only for an app that has at least one live worker stating its schedules: with none (the
5194
- * app is down, or runs an SDK that does not announce schedules), nothing is withdrawn, and its
5195
- * schedules keep firing into runs that wait for a worker.
5218
+ * THROTTLED exactly as {@link rearmStepLease} is, and for the same reason: a long workflow turn's
5219
+ * worker beats every couple of seconds, and each beat otherwise cost a `getRun` + `updateRun`.
5220
+ * The window here is `remoteAdvanceSilenceMs`, and a renewal buys at most one of them — so it is
5221
+ * only worth a write once the window is half spent, which leaves a full half-window of headroom
5222
+ * before the timer poller would re-drive the turn. The in-memory mark is a pure optimisation: a
5223
+ * cold (or different) instance re-derives the same answer from the run's own `wakeAt`.
5196
5224
  */
5197
- syncAnnounced(namespace: string, items: readonly AnnouncedSchedule[], opts: {
5198
- nowMs?: number;
5199
- graceMs: number;
5200
- }): Promise<AnnouncedScheduleSync>;
5201
- /** `overlap: 'skip'` and the previous run of this schedule is still in flight. */
5202
- private overlapping;
5203
- private mustGet;
5204
- /** Explicit `opts.tenantId` → the existing schedule's tenant (upsert) → the context tenant → none. */
5205
- private scheduleTenant;
5206
- private write;
5225
+ private rearmDecisionDeadline;
5226
+ /**
5227
+ * A slot freed on `queue` (a fleet-wide signal): resume this instance's runs blocked on it so they
5228
+ * re-contend now instead of at their retry tick. Snapshot-and-clear — a run still blocked after the
5229
+ * retry re-registers itself, and one that's gone (cancelled/admitted) is dropped. Best-effort.
5230
+ */
5231
+ private wakeQueueWaiters;
5232
+ /** Release the flow-control slot a dispatched step held (if any), by its stepId. */
5233
+ private releaseQueueSlot;
5234
+ /** In-memory await path for a remote step with a liveness `timeoutMs` (re-dispatch on timeout). */
5235
+ private callRemoteInMemory;
5236
+ /**
5237
+ * Await `resultPromise`, but reject with `onTimeout()` if neither it settles nor a heartbeat for `id`
5238
+ * arrives within `timeoutMs`. Each heartbeat (delivered via `transport.onHeartbeat`, looked up in
5239
+ * `heartbeatResets` by `id`) REARMS the window, so a worker that keeps beating stays alive past
5240
+ * `timeoutMs`. Shared by the remote-STEP liveness (keyed by stepId) and the remote-WORKFLOW advance
5241
+ * liveness (keyed by runId); the caller supplies the timeout error and any extra cleanup via `onTimeout`.
5242
+ */
5243
+ private awaitWithLivenessDeadline;
5244
+ /** Remote-STEP liveness: await a worker result, timing out (with the step's pending-map cleanup) to
5245
+ * `RemoteStepTimeout` if it neither lands nor beats within `timeoutMs`. See {@link awaitWithLivenessDeadline}. */
5246
+ private awaitWithHeartbeat;
5247
+ }
5248
+ /** Raised inside the workflow when a remote worker reports a step failure. */
5249
+ declare class RemoteStepError extends Error {
5250
+ readonly stepError?: StepError | undefined;
5251
+ constructor(stepError?: StepError);
5252
+ }
5253
+ /** Checkpoint names that record a parent→child edge: an awaited child, a folded group of them, a spawn. */
5254
+ declare const CHILD_EDGE_PREFIXES: string[];
5255
+ /** The child run ids a parent's {@link CHILD_EDGE_PREFIXES} checkpoints point at (others are skipped). */
5256
+ declare function childIdsOf(checkpoints: StepCheckpoint[]): string[];
5257
+
5258
+ /**
5259
+ * One end of a `ctx.waitForRun` wait, as a run detail lists it: the run waited for (`waitsFor`) or
5260
+ * the waiting run (`awaitedBy`), the waiting run's `seq` of the call, and the other run's status and
5261
+ * namespace when it was read.
5262
+ */
5263
+ interface RunWaitLink {
5264
+ runId: string;
5265
+ seq: number;
5266
+ status?: RunStatus | undefined;
5267
+ namespace?: string | undefined;
5268
+ }
5269
+ /**
5270
+ * Where a settled run's lifecycle event stands for one subscriber:
5271
+ * - `started`: its run exists (`runId`, a `durable:triggered:<subscriber>` tag);
5272
+ * - `owed`: still pending (a `durable:lifecycle:owed:<subscriber>` tag);
5273
+ * - `coalesced`: routed into a debounce/batch accumulator (a `durable:coalesced:<subscriber>` tag,
5274
+ * or the caller's `coalesced` map; `runId` is the accumulator's, when it can be derived);
5275
+ * - `failed`: its start failed (a `durable:trigger_failed:<subscriber>` tag): its `where` threw, its
5276
+ * input was rejected, its start threw, or the sweep dropped it as orphaned. A republish retries it;
5277
+ * - `not-started`: no run and nothing owed: its `where` declined the event, or it subscribed after
5278
+ * the run settled.
5279
+ */
5280
+ type LifecycleDeliveryState = 'started' | 'owed' | 'coalesced' | 'failed' | 'not-started';
5281
+ /** One subscriber of a settled run's lifecycle event, as the run detail lists it. */
5282
+ interface LifecycleDelivery {
5283
+ subscriber: string;
5284
+ state: LifecycleDeliveryState;
5285
+ /** The subscriber's run when `started`; the accumulator run when `coalesced` and derivable. */
5286
+ runId?: string | undefined;
5287
+ /** The status of a `started` subscriber's run, when it was read. */
5288
+ status?: RunStatus | undefined;
5289
+ /** The namespace of a `started` subscriber's run, when it was read. */
5290
+ namespace?: string | undefined;
5291
+ /** When an `owed` subscriber became owed: the settled run's last update (epoch ms). */
5292
+ owedSince?: number | undefined;
5293
+ /**
5294
+ * When the lifecycle sweep drops an `owed` subscriber that no live instance registers or
5295
+ * announces for the run's namespace (epoch ms; see {@link LIFECYCLE_ORPHAN_MS}). Absent while one
5296
+ * does.
5297
+ */
5298
+ orphanAt?: number | undefined;
5299
+ /**
5300
+ * Why a `failed` subscriber did not start, when the caller knows it (the run's tags record only
5301
+ * that it failed; the `run.trigger_failed` event carries the message). {@link lifecycleDeliveriesOf}
5302
+ * leaves it unset.
5303
+ */
5304
+ error?: string | undefined;
5207
5305
  }
5306
+ /**
5307
+ * The {@link LifecycleDelivery} of each subscriber of a settled run, sorted by subscriber: the
5308
+ * union of `subscribers` (the ones the run's event goes to now) and the owed, triggered, coalesced
5309
+ * and trigger-failed tags. `live` names the subscribers a live instance registers or announces; an owed subscriber
5310
+ * outside it gets `orphanAt`. `coalesced` maps each subscriber that coalesces its events to its
5311
+ * accumulator run id (undefined when it cannot be derived). Empty for a run that has not settled.
5312
+ */
5313
+ declare function lifecycleDeliveriesOf(run: Pick<WorkflowRun, 'id' | 'status' | 'tags' | 'updatedAt'>, opts: {
5314
+ subscribers: readonly string[];
5315
+ live: ReadonlySet<string>;
5316
+ coalesced?: ReadonlyMap<string, string | undefined> | undefined;
5317
+ }): LifecycleDelivery[];
5318
+ /** The trace id of a W3C `traceparent` (`00-<trace id>-<span id>-<flags>`), or undefined. */
5319
+ declare function traceIdOfTraceparent(traceparent: string | undefined): string | undefined;
5208
5320
 
5209
5321
  /** A run as returned by the gateway's list — the durable run plus an optional {@link RunWaiting}
5210
5322
  * descriptor the control plane resolves (what a suspended run is parked on), so the dashboard can
@@ -5475,9 +5587,29 @@ declare abstract class RunGateway {
5475
5587
  * Deliver `payload` to the run waiting on `token` (`WorkflowEngine.signal`). Null when no run waits
5476
5588
  * on it. Optional, like {@link listSchedules}.
5477
5589
  */
5478
- signal?(token: string, payload: unknown): Promise<RunResult | null>;
5590
+ signal?(token: string, payload: unknown, opts?: SignalOptions): Promise<RunResult | null>;
5479
5591
  /** The id of the run waiting on signal `token`, or null when none waits on it yet. Optional. */
5480
5592
  signalWaiter?(token: string): Promise<string | null>;
5593
+ /**
5594
+ * A tenant's `signalWithStart` (`WorkflowEngine.signalWithStartForTenant`): start `start` in
5595
+ * `namespace` unless its run exists, then signal it. Optional, like {@link listSchedules}.
5596
+ */
5597
+ signalWithStartForTenant?(start: StartRunMessage & {
5598
+ runId: string;
5599
+ }, namespace: string, clientTenant: Pick<StartOptions, 'tenantId' | 'tenantKind'>, signal: {
5600
+ token: string;
5601
+ payload?: unknown;
5602
+ }): Promise<{
5603
+ runId: string;
5604
+ signalled: boolean;
5605
+ }>;
5606
+ /**
5607
+ * A tenant's `publishEvent`, scoped to `namespace` (`WorkflowEngine.publishEventForTenant`).
5608
+ * Resolves how many runs it resumed or started. Optional, like {@link listSchedules}.
5609
+ */
5610
+ publishEventForTenant?(name: string, payload: unknown, namespace: string, opts?: {
5611
+ id?: string;
5612
+ }): Promise<number>;
5481
5613
  /** Live lifecycle events for one run; returns an unsubscribe fn. Framework-agnostic (no rxjs). */
5482
5614
  abstract subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
5483
5615
  }
@@ -7013,6 +7145,21 @@ interface StartRunMessage {
7013
7145
  * the tenant caller has already returned.
7014
7146
  */
7015
7147
  concurrency?: ConcurrencyQuota | undefined;
7148
+ /**
7149
+ * The workflow's `@Workflow({ singleton })`, evaluated by the starting app against this input: the
7150
+ * serialization key, the limit and the queue depth. A control plane that serves the workflow by
7151
+ * convention (it has no registration of its own, so it cannot evaluate the key) stamps the run
7152
+ * `singleton:<key>` and admits it against `limit`, like a local singleton. A control plane with its
7153
+ * own registration of the workflow applies its own `singleton` instead, and one older than this
7154
+ * field ignores it.
7155
+ */
7156
+ singleton?: StartRunSingleton | undefined;
7157
+ }
7158
+ /** A singleton key the starter evaluated (see {@link StartRunMessage.singleton}). */
7159
+ interface StartRunSingleton {
7160
+ key: string;
7161
+ limit?: number | undefined;
7162
+ maxQueueDepth?: number | undefined;
7016
7163
  }
7017
7164
  /**
7018
7165
  * A tenant worker → control plane read/control request over the shared transport. Enqueued on
@@ -7084,6 +7231,23 @@ type RunRequestKind = {
7084
7231
  kind: 'signal';
7085
7232
  token: string;
7086
7233
  payload: unknown;
7234
+ opts?: SignalOptions | undefined;
7235
+ } | {
7236
+ kind: 'signalWithStart';
7237
+ start: Omit<StartRunMessage, 'tenant'> & {
7238
+ runId: string;
7239
+ };
7240
+ signal: {
7241
+ token: string;
7242
+ payload?: unknown;
7243
+ };
7244
+ } | {
7245
+ kind: 'publishEvent';
7246
+ name: string;
7247
+ payload: unknown;
7248
+ opts?: {
7249
+ id?: string;
7250
+ } | undefined;
7087
7251
  } | {
7088
7252
  kind: 'schedule';
7089
7253
  id: string;
@@ -10113,4 +10277,4 @@ declare function prevRRuleFireMs(rule: ParsedRRule, atMs: number): number | null
10113
10277
  */
10114
10278
  declare function settleResultsWithPlainCalls(store: Pick<StateStore, 'getRun' | 'getCheckpoint'> & Partial<Pick<StateStore, 'getRuns' | 'getCheckpointsForSettle' | 'getCheckpoints' | 'settleCheckpointsIfPending'>>, results: StepResultSettlement[]): Promise<(StepCheckpoint | null)[]>;
10115
10279
 
10116
- export { ACCUMULATOR_SEEN_MAX, ANNOUNCED_SCHEDULE_TAG, ANY_WAIT_GROUP, type AccumulatorHost, type AccumulatorStartOptions, type Admission, type AdmissionBackend, type AdmissionItem, type AllOptions, type AllSettledOptions, type AllStepsOptions, type AllStepsSettledOptions, type AnnouncedSchedule, type AnnouncedScheduleSync, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type AttributedEngineEvent, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, type BufferedSignalRow, CHILD_EDGE_PREFIXES, CONTROL_FLOW_SIGNAL, CORE_ORIGIN, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type CheckpointAggregatingStore, type CheckpointNameKind, type CheckpointQuery, type CheckpointStat, type ChildCallOptions, type ChildWait, CodecStateStore, type CodecStateStoreOptions, type ConcurrencyConfig, ConcurrencyLimitError, type ConcurrencyQuota, type ConsoleCapabilities, type ConsoleFederation, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_ANNOUNCED_SCHEDULE_GRACE_MS, DEFAULT_CONCURRENCY_STATUSES, DEFAULT_PARTITION, DEFAULT_STALLED_AFTER_MS, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type Disagreement, type DispatchDiagnostics, type DispatchPlan, DuplicateDurableCopyError, type DurableCopy, type DurableExecution, type DurableExecutionWrapper, type DurableTopology, type DurableWebhook, DurableWorkflow, type DynamicWorkflowCtx, ENGINE_MINTED_TAG_PREFIXES, ENTITY_WORKFLOW, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, type EngineTenancy, Entities, type EntityConfig, type EntityHandler, type EntityHost, type EntityWorkflowHost, EventAccumulators, type EventBatchConfig, type EventSubscription, FAN_SUMMARY_FAILURES, type FanJoin, type FanPage, type FanPageQuery, type FanSummary, type FanWait, FatalError, type FindStalledRunsOptions, GatherError, type GatherItemFailure, type GroupHealth, HANDOFF_SEQ_BASE, type Heartbeat, type HeartbeatSighting, type HeartbeatStatus, type HistoryEvent, InMemoryAdmissionBackend, InMemoryRunQueue, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, LEGACY_V1_CAPABILITIES, LEGACY_V1_PROTOCOL, LIFECYCLE_COALESCED_TAG_PREFIX, LIFECYCLE_HEAL_WINDOW_MS, LIFECYCLE_ORPHAN_MS, LIFECYCLE_OWED_TAG_PREFIX, LIFECYCLE_PENDING_TAG, LIFECYCLE_REGISTRY_HEARTBEAT_MS, LIFECYCLE_REGISTRY_STALE_MS, LIFECYCLE_REGISTRY_TAG, LIFECYCLE_REGISTRY_TTL_MS, LIFECYCLE_REGISTRY_WORKFLOW, LIFECYCLE_TRACE_TAG_PREFIX, LIFECYCLE_TRIGGERED_TAG_PREFIX, LIFECYCLE_TRIGGER_FAILED_TAG_PREFIX, type LifecycleDelivery, type LifecycleDeliveryState, type LifecycleEventOf, type LifecycleKind, type LifecycleRegistryEntry, type LifecycleSource, type LifecycleSubscriptionLink, type ListStalledRunsOptions, type MetricsCollector, type MetricsSnapshot, NO_LIVE_WORKER, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NestedWorkflowCallError, NonDeterminismError, type OnErrorInput, type OnErrorRoute, type OnEventEntry, type OwnedLeaseReclaim, PARENT_CLOSE_TAG_PREFIX, type ParentClosePolicy, type ParsedRRule, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, REMOTE_EVENT, RUN_HISTORY_FIXTURE_VERSION, RUN_VALUE_FACET_LIMIT, RUN_VALUE_FACET_SCAN, RUN_WAIT_TOKEN_PREFIX, type RawWorkerDescriptor, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RepublishLifecycleResult, type RepublishLifecycleTarget, type RetentionPolicy, type RoutableDispatch, type RoutableResolution, type RoutingResolution, type RunAppAttribution, RunAppStamper, type RunAppTopologyOptions, type RunAttributeRow, type RunConsumerOptions, type RunDetail, type RunDetailOptions, type RunDispatch, type RunDispatcher, type RunFacetQuery, type RunFacetRow, RunGateway, type RunListItem, type RunQuery, type RunQueueOptions, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunScope, type RunStatus, type RunTenant, type RunValueAxis, type RunValueFacetOptions, type RunValueFacetOrder, type RunValueFacetRow, type RunWaitLink, type RunWaiting, SINGLETON_ACTIVE_STATUSES, SINGLETON_ADMITTED_TAG, SINGLETON_LOCK_CHUNK, SINGLETON_RESERVED_TAGS, SINGLETON_TRACKED_TAG, STATE_STORE, STATE_STORE_CANONICAL, SUMMARY_CHILD_LIMIT, type ScalarAttributeFilter, type ScheduleAction, ScheduleAlreadyExistsError, type ScheduleAnnouncement, ScheduleClient, type ScheduleClientOptions, type ScheduleDescription, type ScheduleHost, type ScheduleListQuery, ScheduleNotFoundError, type ScheduleOptions, type ScheduleQuery, type ScheduleRecord, type ScheduleTickEngine, type ScheduledWorkflow, type SchemaIssue, type SchemaValidationCode, SchemaValidationError, type SearchAttributes, type SearchAttributesSchema, type Settled, type SignalOptions, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StalePendingStep, type StalledRunInfo, 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 StepResultSettlement, type StepScope, type StepSettlement, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type TenantFilter, type TenantRow, type TenantTokenSource, type TenantVerifier, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, VERSION_UNDECLARED_TAG, type VerifiedTenant, WORKFLOW_NAME_KEY, type WaitAnyCondition, type WaitAnyOutcome, type WaitAnyResult, type WaitCondition, type WaitConditionSpec, type WaitForRunOptions, 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 WorkflowLifecycleEvent, type WorkflowLifecycleLinks, WorkflowNotRegistered, type WorkflowOutputOf, type WorkflowRef, type WorkflowRegistration, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, acceptingSubscription, accumulatorRunId, aggregateAnnouncements, aggregatesCheckpoints, announcedScheduleId, announcementsOf, anyCheckpointName, applyAttributeQuery, assertConcurrency, assertRoutes, assertSingleDurableCopy, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, bufferedEventReaches, buildWorkflowDirectory, canRoute, capableWorkers, carriesLifecyclePending, checkpointNameKind, checkpointStatsOf, childIdsOf, classifyWaiterToken, clearDurableExecutionWrappers, clearTerminalSingletonAdmission, coalescedSubscribersOf, codeAndDetails, codeOf, collectMetrics, concurrencyTag, controlPlaneAttribution, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentStepScope, currentWorkflowCtx, debug, describeWorker, descriptorHash, detailsOf, durableCopies, error, etagMatches, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, extendEtag, facetOrigin, fanPageBounds, fanPageEtag, findStalledRuns, foldedCount, getRunsByIds, grantsClientTenant, handoffHandlerId, handoffName, hasDurableExecutionWrappers, heartbeatStatus, hmacTenantVerifier, indexWaitersByRun, info, inheritTenant, isAnyCheckpoint, isAnyMember, isEngineMintedTag, isEventToken, isFailedMember, isLegacyDescriptor, isLifecycleTag, isNonEmptyRunScope, isRemoteEvent, isWorkflowControlFlowSignal, legacySingletonHolders, lifecycleDeliveriesOf, lifecycleEventName, lifecycleEventOf, lifecycleKindOf, lifecycleRegistryNamespace, lifecycleRegistryRunId, lifecycleRegistrySubscriptions, lifecycleRunId, lifecycleSourceOf, lifecycleTraceparentOf, listSignalWaitersOfRuns, liveHandoff, log, markRemoteEvent, matchesAttributes, matchesTenantPredicates, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, nextRRuleFireMs, nextScheduleFireAt, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, onErrorRunId, owedSubscribersOf, pageFan, pageFanFromStore, parentRunIdOf, parseDuration, parseLifecycleEvent, parseRRule, parseWebhookToken, partitionOfToken, planDispatch, poolNamespace, prevCronFireMs, prevRRuleFireMs, queryCheckpointsOf, readBufferedEvent, readRunsByIds, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, resolveTenantToken, resolveWireTenant, retentionKeeps, retiredHandoffName, routeFor, rowTenant, runCompletedEvent, runDetailEtag, runDurableExecution, runFailedEvent, runInStepLogger, runInStepScope, runInWorkflowCtx, runOutsideWorkflowCtx, runSchedules, runStepHandler, runTraceId, runValueFacetsFromRuns, runWaitPrefix, runWaitTargetOf, runWaitToken, sanitizeQueueToken, scheduleRunIdAt, scheduledRunId, scopeBufferedEvent, scopeTenantQuery, sealDurableCopies, settleResultsWithPlainCalls, signTenantToken, singletonAdmissionDenialPatch, singletonAdmissionTags, singletonClaimantIds, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, summarizeFan, summarizeRunFromStore, summarizeTimeline, tenantAppOf, tenantGroup, tenantIdsFor, tenantVisible, toEventSubscription, traceIdOfTraceparent, triggerFailedSubscribersOf, triggeredRunsOf, triggeredSubscribersOf, useDurableExecution, verifyWireTenant, warn, withSingletonTracked, withoutSingletonMarkers, workflowName };
10280
+ export { ACCUMULATOR_SEEN_MAX, ANNOUNCED_SCHEDULE_TAG, ANY_WAIT_GROUP, type AccumulatorHost, type AccumulatorStartOptions, type Admission, type AdmissionBackend, type AdmissionItem, type AllOptions, type AllSettledOptions, type AllStepsOptions, type AllStepsSettledOptions, type AnnouncedSchedule, type AnnouncedScheduleSync, type AnnouncedWorkflow, type AnnouncedWorkflowOptions, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type AttributedEngineEvent, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, type BufferedSignalRow, CHILD_EDGE_PREFIXES, CONTROL_FLOW_SIGNAL, CORE_ORIGIN, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type CheckpointAggregatingStore, type CheckpointNameKind, type CheckpointQuery, type CheckpointStat, type ChildCallOptions, type ChildWait, CodecStateStore, type CodecStateStoreOptions, type ConcurrencyConfig, ConcurrencyLimitError, type ConcurrencyQuota, type ConsoleCapabilities, type ConsoleFederation, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_ANNOUNCED_SCHEDULE_GRACE_MS, DEFAULT_CONCURRENCY_STATUSES, DEFAULT_PARTITION, DEFAULT_STALLED_AFTER_MS, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type Disagreement, type DispatchDiagnostics, type DispatchPlan, DuplicateDurableCopyError, type DurableCopy, type DurableExecution, type DurableExecutionWrapper, type DurableTopology, type DurableWebhook, DurableWorkflow, type DynamicWorkflowCtx, ENGINE_MINTED_TAG_PREFIXES, ENTITY_WORKFLOW, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, type EngineTenancy, Entities, type EntityConfig, type EntityHandler, type EntityHost, type EntityWorkflowHost, EventAccumulators, type EventBatchConfig, type EventSubscription, FAN_SUMMARY_FAILURES, type FanJoin, type FanPage, type FanPageQuery, type FanSummary, type FanWait, FatalError, type FindStalledRunsOptions, GatherError, type GatherItemFailure, type GroupHealth, HANDOFF_SEQ_BASE, type Heartbeat, type HeartbeatSighting, type HeartbeatStatus, type HistoryEvent, InMemoryAdmissionBackend, InMemoryRunQueue, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, LEGACY_V1_CAPABILITIES, LEGACY_V1_PROTOCOL, LIFECYCLE_COALESCED_TAG_PREFIX, LIFECYCLE_HEAL_WINDOW_MS, LIFECYCLE_ORPHAN_MS, LIFECYCLE_OWED_TAG_PREFIX, LIFECYCLE_PENDING_TAG, LIFECYCLE_REGISTRY_HEARTBEAT_MS, LIFECYCLE_REGISTRY_STALE_MS, LIFECYCLE_REGISTRY_TAG, LIFECYCLE_REGISTRY_TTL_MS, LIFECYCLE_REGISTRY_WORKFLOW, LIFECYCLE_TRACE_TAG_PREFIX, LIFECYCLE_TRIGGERED_TAG_PREFIX, LIFECYCLE_TRIGGER_FAILED_TAG_PREFIX, type LifecycleDelivery, type LifecycleDeliveryState, type LifecycleEventOf, type LifecycleKind, type LifecycleRegistryEntry, type LifecycleSource, type LifecycleSubscriptionLink, type ListStalledRunsOptions, type MetricsCollector, type MetricsSnapshot, NO_LIVE_WORKER, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NestedWorkflowCallError, NonDeterminismError, type OnErrorInput, type OnErrorRoute, type OnEventEntry, type OwnedLeaseReclaim, PARENT_CLOSE_TAG_PREFIX, type ParentClosePolicy, type ParsedRRule, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, REMOTE_EVENT, RUN_HISTORY_FIXTURE_VERSION, RUN_VALUE_FACET_LIMIT, RUN_VALUE_FACET_SCAN, RUN_WAIT_TOKEN_PREFIX, type RawWorkerDescriptor, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RepublishLifecycleResult, type RepublishLifecycleTarget, type RetentionPolicy, type RoutableDispatch, type RoutableResolution, type RoutingResolution, type RunAppAttribution, RunAppStamper, type RunAppTopologyOptions, type RunAttributeRow, type RunConsumerOptions, type RunDetail, type RunDetailOptions, type RunDispatch, type RunDispatcher, type RunFacetQuery, type RunFacetRow, RunGateway, type RunListItem, type RunQuery, type RunQueueOptions, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunScope, type RunStatus, type RunTenant, type RunValueAxis, type RunValueFacetOptions, type RunValueFacetOrder, type RunValueFacetRow, type RunWaitLink, type RunWaiting, SINGLETON_ACTIVE_STATUSES, SINGLETON_ADMITTED_TAG, SINGLETON_LOCK_CHUNK, SINGLETON_RESERVED_TAGS, SINGLETON_TRACKED_TAG, STATE_STORE, STATE_STORE_CANONICAL, SUMMARY_CHILD_LIMIT, type ScalarAttributeFilter, type ScheduleAction, ScheduleAlreadyExistsError, type ScheduleAnnouncement, ScheduleClient, type ScheduleClientOptions, type ScheduleDescription, type ScheduleHost, type ScheduleListQuery, ScheduleNotFoundError, type ScheduleOptions, type ScheduleQuery, type ScheduleRecord, type ScheduleTickEngine, type ScheduledWorkflow, type SchemaIssue, type SchemaValidationCode, SchemaValidationError, type SearchAttributes, type SearchAttributesSchema, type Settled, type SignalOptions, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StalePendingStep, type StalledRunInfo, StandardSchemaV1, type StartOptions, type StartRunMessage, type StartRunSingleton, 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 StepResultSettlement, type StepScope, type StepSettlement, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type TenantFilter, type TenantRow, type TenantTokenSource, type TenantVerifier, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, VERSION_UNDECLARED_TAG, type VerifiedTenant, WORKFLOW_NAME_KEY, type WaitAnyCondition, type WaitAnyOutcome, type WaitAnyResult, type WaitCondition, type WaitConditionSpec, type WaitForRunOptions, 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 WorkflowLifecycleEvent, type WorkflowLifecycleLinks, WorkflowNotRegistered, type WorkflowOutputOf, type WorkflowRef, type WorkflowRegistration, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, acceptingSubscription, accumulatorRunId, aggregateAnnouncements, aggregatesCheckpoints, announcedScheduleId, announcementsOf, anyCheckpointName, applyAttributeQuery, assertConcurrency, assertRoutes, assertSingleDurableCopy, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, bufferedEventReaches, buildWorkflowDirectory, canRoute, capableWorkers, carriesLifecyclePending, checkpointNameKind, checkpointStatsOf, childIdsOf, classifyWaiterToken, clearDurableExecutionWrappers, clearTerminalSingletonAdmission, coalescedSubscribersOf, codeAndDetails, codeOf, collectMetrics, concurrencyTag, controlPlaneAttribution, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentStepScope, currentWorkflowCtx, debug, describeWorker, descriptorHash, detailsOf, durableCopies, error, etagMatches, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, extendEtag, facetOrigin, fanPageBounds, fanPageEtag, findStalledRuns, foldedCount, getRunsByIds, grantsClientTenant, handoffHandlerId, handoffName, hasDurableExecutionWrappers, heartbeatStatus, hmacTenantVerifier, indexWaitersByRun, info, inheritTenant, isAnyCheckpoint, isAnyMember, isEngineMintedTag, isEventToken, isFailedMember, isLegacyDescriptor, isLifecycleTag, isNonEmptyRunScope, isRemoteEvent, isWorkflowControlFlowSignal, legacySingletonHolders, lifecycleDeliveriesOf, lifecycleEventName, lifecycleEventOf, lifecycleKindOf, lifecycleRegistryNamespace, lifecycleRegistryRunId, lifecycleRegistrySubscriptions, lifecycleRunId, lifecycleSourceOf, lifecycleTraceparentOf, listSignalWaitersOfRuns, liveHandoff, log, markRemoteEvent, matchesAttributes, matchesTenantPredicates, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, nextRRuleFireMs, nextScheduleFireAt, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, onErrorRunId, owedSubscribersOf, pageFan, pageFanFromStore, parentRunIdOf, parseDuration, parseLifecycleEvent, parseRRule, parseWebhookToken, partitionOfToken, planDispatch, poolNamespace, prevCronFireMs, prevRRuleFireMs, queryCheckpointsOf, readBufferedEvent, readRunsByIds, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, resolveTenantToken, resolveWireTenant, retentionKeeps, retiredHandoffName, routeFor, rowTenant, runCompletedEvent, runDetailEtag, runDurableExecution, runFailedEvent, runInStepLogger, runInStepScope, runInWorkflowCtx, runOutsideWorkflowCtx, runSchedules, runStepHandler, runTraceId, runValueFacetsFromRuns, runWaitPrefix, runWaitTargetOf, runWaitToken, sanitizeQueueToken, scheduleRunIdAt, scheduledRunId, scopeBufferedEvent, scopeTenantQuery, sealDurableCopies, settleResultsWithPlainCalls, signTenantToken, singletonAdmissionDenialPatch, singletonAdmissionTags, singletonClaimantIds, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, summarizeFan, summarizeRunFromStore, summarizeTimeline, tenantAppOf, tenantGroup, tenantIdsFor, tenantVisible, toEventSubscription, traceIdOfTraceparent, triggerFailedSubscribersOf, triggeredRunsOf, triggeredSubscribersOf, useDurableExecution, verifyWireTenant, warn, withSingletonTracked, withoutSingletonMarkers, workflowName };