@dudousxd/nestjs-durable-core 0.101.0 → 0.103.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.
@@ -4441,6 +4766,13 @@ declare class WorkflowEngine {
4441
4766
  * — the caller has already ensured this is the decision for the currently-awaited turn.
4442
4767
  */
4443
4768
  private applyDecision;
4769
+ /**
4770
+ * A remote turn that ended in `ctx.continueAsNew(input)`: record what the turn ran, complete this
4771
+ * run and start its continuation (`<runId>~N`) with `input` on a clean history — the in-process
4772
+ * engine's handoff, with the run's partition and tenant carried over. A run cancelled while the
4773
+ * turn replayed stays cancelled and starts nothing.
4774
+ */
4775
+ private applyRemoteContinueAsNew;
4444
4776
  /**
4445
4777
  * Re-drive a run whose turn was computed from a history OLDER than the store's.
4446
4778
  *
@@ -4539,6 +4871,59 @@ declare class WorkflowEngine {
4539
4871
  * {@link redriveLostCall}). A terminal turn (completed/failed/cancelled) applies its commands only
4540
4872
  * to record what already ran, and must never dispatch anything new. */
4541
4873
  private applyCommands;
4874
+ /**
4875
+ * Park a remote turn on signal `token` at `seq`: register a waiter so `engine.signal(token)` lands
4876
+ * the resolving `signal` checkpoint here and resumes the run. If the signal was already delivered
4877
+ * (buffered before the workflow reached this point — e.g. signalWithStart), resolve it now and
4878
+ * re-drive on a macrotask, AFTER this turn suspends and frees the run lock (a re-entrant resume
4879
+ * bails).
4880
+ */
4881
+ private parkRemoteOnSignal;
4882
+ /** Re-drive `runId` on a macrotask, after the current turn has suspended and freed its lease. */
4883
+ private resumeSoon;
4884
+ /**
4885
+ * Stamp the deadline of a BOUNDED remote wait at `deadlineSeq`, once: the first apply records
4886
+ * `now + timeoutMs` as a `timeout:<label>` timer, and every later one reads the recorded deadline
4887
+ * back (the in-process `stampDeadline`). The checkpoint's `input` names the wait it bounds, so the
4888
+ * deadline can drop that wait's waiter when it lapses — see {@link expireRemoteDeadlines}.
4889
+ */
4890
+ private stampRemoteDeadline;
4891
+ /**
4892
+ * Before a remote turn reads its history: a bounded wait whose deadline has lapsed drops its waiter
4893
+ * (exact row only), so a signal or event arriving later cannot resolve a wait the turn already saw
4894
+ * time out — the in-process wait removes its waiter the same way when it finds the deadline past.
4895
+ * A delivery that took the waiter first wins: its checkpoint is read back into `checkpoints`, and the
4896
+ * worker's replay checks the wait before the deadline. Returns the (possibly extended) list.
4897
+ */
4898
+ private expireRemoteDeadlines;
4899
+ /**
4900
+ * Claim one buffered event `name` whose payload satisfies `match` and that this run's tenant may
4901
+ * see — the remote twin of the in-process `waitForEvent`'s buffered consumption (oldest first; a
4902
+ * candidate claimed elsewhere first is skipped, not waited on). Expired candidates are pruned when
4903
+ * {@link eventBufferTtlMs} is set, like the reconcile sweep.
4904
+ */
4905
+ private claimBufferedEvent;
4906
+ /** The lease a freshly dispatched remote `call` parks on: its liveness `timeoutMs` when its policy
4907
+ * sets one, else the lost-dispatch window (`remoteRedispatchMs`), else none. */
4908
+ private callLease;
4909
+ /**
4910
+ * A re-emitted remote `call` that carries its step's policy: apply the policy to the step's
4911
+ * checkpoint exactly as the in-process `ctx.step` path ({@link callRemote} / {@link
4912
+ * callRemoteInMemory}) applies it, so a step declared with retries, backoff or a timeout on a tenant
4913
+ * behaves as it does on a standalone engine. Returns the time to park the run on (`undefined`: no
4914
+ * timer, the step's result or the next turn moves it), or `null` when the policy has nothing to say
4915
+ * and the lost-dispatch self-heal ({@link redriveLostCall}) decides.
4916
+ *
4917
+ * - FAILED and retried (see `remoteCallRetries`): the first sight stamps the backoff deadline on
4918
+ * the failed checkpoint (`wakeAt`, durable and stable across replays); once due, the step is
4919
+ * dispatched again under the same `stepId` with `attempts + 1`.
4920
+ * - PENDING with a `timeoutMs`: the step's lease is `timeoutMs` from its dispatch. A lapsed lease
4921
+ * re-dispatches while attempts remain, then fails the step with a `remote_step_timeout` error the
4922
+ * workflow can catch, as `RemoteStepTimeout` would surface in-process.
4923
+ */
4924
+ private applyCallPolicy;
4925
+ /** Dispatch a policed remote `call` again as attempt `attempt` (a retry, or a timed-out attempt). */
4926
+ private redispatchCall;
4542
4927
  /**
4543
4928
  * Undo the registered saga compensations in reverse and settle the run `cancelled`. Shared by EVERY
4544
4929
  * exit path of a run with a compensating cancel in flight — whether the resumed replay returned,
@@ -4856,355 +5241,142 @@ declare class WorkflowEngine {
4856
5241
  private settleResultsReturning;
4857
5242
  /**
4858
5243
  * 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.
5244
+ * resumes the run if it is `suspended` and, for a step of a fan, the fan's barrier is open. A
5245
+ * resume of a run that had in fact moved on replays to its current wait and re-parks.
5127
5246
  */
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>;
5247
+ private resumeForRedelivered;
5137
5248
  /**
5138
- * Fire again from the next window after now — the windows skipped while paused are NOT caught up.
5249
+ * The join barrier of a step fan: a result for one of its steps resumes the parent only once no
5250
+ * step of the fan is still `pending` (a settled wave), or on a failure (failFast surfaces it, and a
5251
+ * retry needs the parent to schedule it). Without it every result would replay the whole parent,
5252
+ * which makes a fan of N steps cost O(N²) checkpoint reads. `barriers` holds the answer per fan
5253
+ * for the rest of a batch. A barrier that cannot be read counts as open: a spare resume replays and
5254
+ * re-suspends, a lost one strands the run. A fan with a result waiting in `queuedIn` is left to
5255
+ * that result (see {@link completeRemoteResults}).
5139
5256
  */
5140
- resume(id: string): Promise<ScheduleDescription>;
5257
+ private stepFanStillRunning;
5258
+ /** Whether any step of a step fan's seq range is still `pending`. */
5259
+ private stepFanHasPending;
5141
5260
  /**
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.
5261
+ * Apply a remote workflow-turn {@link WorkflowDecision} durably — runs on WHATEVER instance receives
5262
+ * it over the broker (the dispatching one may be gone, or a point-to-point broker handed it to a
5263
+ * non-dispatcher). The durable, multi-instance-safe twin of {@link completeRemoteResult} for the
5264
+ * workflow TURN: look the run up by `decision.runId`, verify the decision matches the run's
5265
+ * CURRENTLY-awaited turn (`awaitingDecisionTaskId`) — so a stale / duplicate / foreign / re-driven
5266
+ * decision is dropped (applied AT MOST ONCE) — lease it, clear the marker, and apply the decision.
5144
5267
  */
5145
- trigger(id: string): Promise<RunResult>;
5268
+ private completeRemoteDecision;
5269
+ /** Earliest clock time a suspended turn's deadline is worth LOOKING at again (`runId` → clock ms) —
5270
+ * the read throttle for {@link rearmDecisionDeadline}, the run-scoped sibling of
5271
+ * {@link stepLeaseRearms}. */
5272
+ private readonly decisionDeadlineRearms;
5146
5273
  /**
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`.
5274
+ * A run-scoped heartbeat for a run suspended awaiting a workflow-turn decision (the dispatch path):
5275
+ * push its durable re-drive deadline (`wakeAt`) forward so a still-working worker's turn is not
5276
+ * re-dispatched. The durable counterpart of an inline turn's in-memory `heartbeatResets` rearm.
5277
+ *
5278
+ * THROTTLED exactly as {@link rearmStepLease} is, and for the same reason: a long workflow turn's
5279
+ * worker beats every couple of seconds, and each beat otherwise cost a `getRun` + `updateRun`.
5280
+ * The window here is `remoteAdvanceSilenceMs`, and a renewal buys at most one of them — so it is
5281
+ * only worth a write once the window is half spent, which leaves a full half-window of headroom
5282
+ * before the timer poller would re-drive the turn. The in-memory mark is a pure optimisation: a
5283
+ * cold (or different) instance re-derives the same answer from the run's own `wakeAt`.
5149
5284
  */
5150
- private startFor;
5285
+ private rearmDecisionDeadline;
5151
5286
  /**
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).
5287
+ * A slot freed on `queue` (a fleet-wide signal): resume this instance's runs blocked on it so they
5288
+ * re-contend now instead of at their retry tick. Snapshot-and-clear — a run still blocked after the
5289
+ * retry re-registers itself, and one that's gone (cancelled/admitted) is dropped. Best-effort.
5157
5290
  */
5158
- tick(nowMs?: number, opts?: {
5159
- tag?: string;
5160
- }): Promise<string[]>;
5291
+ private wakeQueueWaiters;
5292
+ /** Release the flow-control slot a dispatched step held (if any), by its stepId. */
5293
+ private releaseQueueSlot;
5294
+ /** In-memory await path for a remote step with a liveness `timeoutMs` (re-dispatch on timeout). */
5295
+ private callRemoteInMemory;
5161
5296
  /**
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.
5297
+ * Await `resultPromise`, but reject with `onTimeout()` if neither it settles nor a heartbeat for `id`
5298
+ * arrives within `timeoutMs`. Each heartbeat (delivered via `transport.onHeartbeat`, looked up in
5299
+ * `heartbeatResets` by `id`) REARMS the window, so a worker that keeps beating stays alive past
5300
+ * `timeoutMs`. Shared by the remote-STEP liveness (keyed by stepId) and the remote-WORKFLOW advance
5301
+ * liveness (keyed by runId); the caller supplies the timeout error and any extra cleanup via `onTimeout`.
5167
5302
  */
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;
5303
+ private awaitWithLivenessDeadline;
5304
+ /** Remote-STEP liveness: await a worker result, timing out (with the step's pending-map cleanup) to
5305
+ * `RemoteStepTimeout` if it neither lands nor beats within `timeoutMs`. See {@link awaitWithLivenessDeadline}. */
5306
+ private awaitWithHeartbeat;
5307
+ }
5308
+ /** Raised inside the workflow when a remote worker reports a step failure. */
5309
+ declare class RemoteStepError extends Error {
5310
+ readonly stepError?: StepError | undefined;
5311
+ constructor(stepError?: StepError);
5312
+ }
5313
+ /** Checkpoint names that record a parent→child edge: an awaited child, a folded group of them, a spawn. */
5314
+ declare const CHILD_EDGE_PREFIXES: string[];
5315
+ /** The child run ids a parent's {@link CHILD_EDGE_PREFIXES} checkpoints point at (others are skipped). */
5316
+ declare function childIdsOf(checkpoints: StepCheckpoint[]): string[];
5317
+
5318
+ /**
5319
+ * One end of a `ctx.waitForRun` wait, as a run detail lists it: the run waited for (`waitsFor`) or
5320
+ * the waiting run (`awaitedBy`), the waiting run's `seq` of the call, and the other run's status and
5321
+ * namespace when it was read.
5322
+ */
5323
+ interface RunWaitLink {
5324
+ runId: string;
5325
+ seq: number;
5326
+ status?: RunStatus | undefined;
5327
+ namespace?: string | undefined;
5328
+ }
5329
+ /**
5330
+ * Where a settled run's lifecycle event stands for one subscriber:
5331
+ * - `started`: its run exists (`runId`, a `durable:triggered:<subscriber>` tag);
5332
+ * - `owed`: still pending (a `durable:lifecycle:owed:<subscriber>` tag);
5333
+ * - `coalesced`: routed into a debounce/batch accumulator (a `durable:coalesced:<subscriber>` tag,
5334
+ * or the caller's `coalesced` map; `runId` is the accumulator's, when it can be derived);
5335
+ * - `failed`: its start failed (a `durable:trigger_failed:<subscriber>` tag): its `where` threw, its
5336
+ * input was rejected, its start threw, or the sweep dropped it as orphaned. A republish retries it;
5337
+ * - `not-started`: no run and nothing owed: its `where` declined the event, or it subscribed after
5338
+ * the run settled.
5339
+ */
5340
+ type LifecycleDeliveryState = 'started' | 'owed' | 'coalesced' | 'failed' | 'not-started';
5341
+ /** One subscriber of a settled run's lifecycle event, as the run detail lists it. */
5342
+ interface LifecycleDelivery {
5343
+ subscriber: string;
5344
+ state: LifecycleDeliveryState;
5345
+ /** The subscriber's run when `started`; the accumulator run when `coalesced` and derivable. */
5346
+ runId?: string | undefined;
5347
+ /** The status of a `started` subscriber's run, when it was read. */
5348
+ status?: RunStatus | undefined;
5349
+ /** The namespace of a `started` subscriber's run, when it was read. */
5350
+ namespace?: string | undefined;
5351
+ /** When an `owed` subscriber became owed: the settled run's last update (epoch ms). */
5352
+ owedSince?: number | undefined;
5173
5353
  /**
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.
5354
+ * When the lifecycle sweep drops an `owed` subscriber that no live instance registers or
5355
+ * announces for the run's namespace (epoch ms; see {@link LIFECYCLE_ORPHAN_MS}). Absent while one
5356
+ * does.
5178
5357
  */
5179
- private waitingForWorker;
5358
+ orphanAt?: number | undefined;
5180
5359
  /**
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.
5192
- *
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.
5360
+ * Why a `failed` subscriber did not start, when the caller knows it (the run's tags record only
5361
+ * that it failed; the `run.trigger_failed` event carries the message). {@link lifecycleDeliveriesOf}
5362
+ * leaves it unset.
5196
5363
  */
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;
5364
+ error?: string | undefined;
5207
5365
  }
5366
+ /**
5367
+ * The {@link LifecycleDelivery} of each subscriber of a settled run, sorted by subscriber: the
5368
+ * union of `subscribers` (the ones the run's event goes to now) and the owed, triggered, coalesced
5369
+ * and trigger-failed tags. `live` names the subscribers a live instance registers or announces; an owed subscriber
5370
+ * outside it gets `orphanAt`. `coalesced` maps each subscriber that coalesces its events to its
5371
+ * accumulator run id (undefined when it cannot be derived). Empty for a run that has not settled.
5372
+ */
5373
+ declare function lifecycleDeliveriesOf(run: Pick<WorkflowRun, 'id' | 'status' | 'tags' | 'updatedAt'>, opts: {
5374
+ subscribers: readonly string[];
5375
+ live: ReadonlySet<string>;
5376
+ coalesced?: ReadonlyMap<string, string | undefined> | undefined;
5377
+ }): LifecycleDelivery[];
5378
+ /** The trace id of a W3C `traceparent` (`00-<trace id>-<span id>-<flags>`), or undefined. */
5379
+ declare function traceIdOfTraceparent(traceparent: string | undefined): string | undefined;
5208
5380
 
5209
5381
  /** A run as returned by the gateway's list — the durable run plus an optional {@link RunWaiting}
5210
5382
  * descriptor the control plane resolves (what a suspended run is parked on), so the dashboard can
@@ -5475,9 +5647,29 @@ declare abstract class RunGateway {
5475
5647
  * Deliver `payload` to the run waiting on `token` (`WorkflowEngine.signal`). Null when no run waits
5476
5648
  * on it. Optional, like {@link listSchedules}.
5477
5649
  */
5478
- signal?(token: string, payload: unknown): Promise<RunResult | null>;
5650
+ signal?(token: string, payload: unknown, opts?: SignalOptions): Promise<RunResult | null>;
5479
5651
  /** The id of the run waiting on signal `token`, or null when none waits on it yet. Optional. */
5480
5652
  signalWaiter?(token: string): Promise<string | null>;
5653
+ /**
5654
+ * A tenant's `signalWithStart` (`WorkflowEngine.signalWithStartForTenant`): start `start` in
5655
+ * `namespace` unless its run exists, then signal it. Optional, like {@link listSchedules}.
5656
+ */
5657
+ signalWithStartForTenant?(start: StartRunMessage & {
5658
+ runId: string;
5659
+ }, namespace: string, clientTenant: Pick<StartOptions, 'tenantId' | 'tenantKind'>, signal: {
5660
+ token: string;
5661
+ payload?: unknown;
5662
+ }): Promise<{
5663
+ runId: string;
5664
+ signalled: boolean;
5665
+ }>;
5666
+ /**
5667
+ * A tenant's `publishEvent`, scoped to `namespace` (`WorkflowEngine.publishEventForTenant`).
5668
+ * Resolves how many runs it resumed or started. Optional, like {@link listSchedules}.
5669
+ */
5670
+ publishEventForTenant?(name: string, payload: unknown, namespace: string, opts?: {
5671
+ id?: string;
5672
+ }): Promise<number>;
5481
5673
  /** Live lifecycle events for one run; returns an unsubscribe fn. Framework-agnostic (no rxjs). */
5482
5674
  abstract subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
5483
5675
  }
@@ -7013,6 +7205,21 @@ interface StartRunMessage {
7013
7205
  * the tenant caller has already returned.
7014
7206
  */
7015
7207
  concurrency?: ConcurrencyQuota | undefined;
7208
+ /**
7209
+ * The workflow's `@Workflow({ singleton })`, evaluated by the starting app against this input: the
7210
+ * serialization key, the limit and the queue depth. A control plane that serves the workflow by
7211
+ * convention (it has no registration of its own, so it cannot evaluate the key) stamps the run
7212
+ * `singleton:<key>` and admits it against `limit`, like a local singleton. A control plane with its
7213
+ * own registration of the workflow applies its own `singleton` instead, and one older than this
7214
+ * field ignores it.
7215
+ */
7216
+ singleton?: StartRunSingleton | undefined;
7217
+ }
7218
+ /** A singleton key the starter evaluated (see {@link StartRunMessage.singleton}). */
7219
+ interface StartRunSingleton {
7220
+ key: string;
7221
+ limit?: number | undefined;
7222
+ maxQueueDepth?: number | undefined;
7016
7223
  }
7017
7224
  /**
7018
7225
  * A tenant worker → control plane read/control request over the shared transport. Enqueued on
@@ -7084,6 +7291,23 @@ type RunRequestKind = {
7084
7291
  kind: 'signal';
7085
7292
  token: string;
7086
7293
  payload: unknown;
7294
+ opts?: SignalOptions | undefined;
7295
+ } | {
7296
+ kind: 'signalWithStart';
7297
+ start: Omit<StartRunMessage, 'tenant'> & {
7298
+ runId: string;
7299
+ };
7300
+ signal: {
7301
+ token: string;
7302
+ payload?: unknown;
7303
+ };
7304
+ } | {
7305
+ kind: 'publishEvent';
7306
+ name: string;
7307
+ payload: unknown;
7308
+ opts?: {
7309
+ id?: string;
7310
+ } | undefined;
7087
7311
  } | {
7088
7312
  kind: 'schedule';
7089
7313
  id: string;
@@ -7207,6 +7431,39 @@ interface WorkflowTask {
7207
7431
  */
7208
7432
  priority?: number | undefined;
7209
7433
  attempt: number;
7434
+ /**
7435
+ * The workflow-decision features the control plane that dispatched this turn can apply — see
7436
+ * {@link REMOTE_WORKFLOW_FEATURES}. A worker checks it before emitting a command an older control
7437
+ * plane would not understand, and fails the turn with a clear error instead. Absent on a task from
7438
+ * a control plane that predates feature negotiation: only the original command kinds are safe.
7439
+ */
7440
+ features?: string[] | undefined;
7441
+ }
7442
+ /**
7443
+ * The workflow-decision features this control plane applies, advertised on every {@link WorkflowTask}
7444
+ * it dispatches (`task.features`):
7445
+ * - `callPolicy` — a `call` command's `policy` (retries, backoff, liveness `timeoutMs`) is enforced;
7446
+ * - `sleepUntil`, `waitSignalTimeout`, `waitEvent`, `spawnChild`, `continueAsNew` — the command kinds
7447
+ * of the same names.
7448
+ * A worker must not emit a command (or a `call` policy) whose feature the task does not list.
7449
+ */
7450
+ declare const REMOTE_WORKFLOW_FEATURES: readonly ["callPolicy", "sleepUntil", "waitSignalTimeout", "waitEvent", "spawnChild", "continueAsNew"];
7451
+ /** One of {@link REMOTE_WORKFLOW_FEATURES}. */
7452
+ type RemoteWorkflowFeature = (typeof REMOTE_WORKFLOW_FEATURES)[number];
7453
+ /**
7454
+ * The durable dispatch policy a remote `call` command carries (feature `callPolicy`): the same fields,
7455
+ * defaults and semantics as the in-process `ctx.step` policy ({@link StepOptions}) — `retries` is the
7456
+ * total number of attempts; without `timeoutMs` a failed attempt is re-dispatched after `backoff`
7457
+ * unless the worker marked the error non-retryable; with `timeoutMs` an attempt that returns no
7458
+ * result within the window is re-dispatched (up to `retries`) and a reported failure is final.
7459
+ */
7460
+ interface RemoteCallPolicy {
7461
+ retries?: number | undefined;
7462
+ backoff?: BackoffStrategy | undefined;
7463
+ backoffMs?: number | undefined;
7464
+ backoffMaxMs?: number | undefined;
7465
+ jitter?: boolean | undefined;
7466
+ timeoutMs?: number | undefined;
7210
7467
  }
7211
7468
  /** One resolved durable op in a run's history — a superset of a completed {@link StepCheckpoint}. */
7212
7469
  interface HistoryEvent {
@@ -7222,6 +7479,11 @@ interface HistoryEvent {
7222
7479
  output?: unknown;
7223
7480
  /** Set when the op resolved to a failure (e.g. a failed remote step the workflow may catch). */
7224
7481
  error?: StepError | undefined;
7482
+ /**
7483
+ * For a `call`: how many times the step was dispatched. A worker applying a `call` policy reads it
7484
+ * to decide whether a failed attempt is retried (see {@link RemoteCallPolicy}).
7485
+ */
7486
+ attempts?: number | undefined;
7225
7487
  }
7226
7488
  /** A decision the workflow function produced at a `seq` that was not yet in history. */
7227
7489
  type WorkflowCommand =
@@ -7236,6 +7498,10 @@ type WorkflowCommand =
7236
7498
  group: string;
7237
7499
  input: unknown;
7238
7500
  parallelGroup?: string;
7501
+ /** The step's durable dispatch policy (feature `callPolicy`). Re-sent on every turn the step is
7502
+ * not resolved, so whichever control-plane instance applies the turn enforces it. A failed
7503
+ * attempt the policy retries is re-emitted with it instead of raised. */
7504
+ policy?: RemoteCallPolicy;
7239
7505
  }
7240
7506
  /** `ctx.step(name, body)` — a LOCAL step the worker already ran this turn; the engine persists its
7241
7507
  * result so replay returns it instead of re-running (durability for side-effectful work).
@@ -7262,12 +7528,59 @@ type WorkflowCommand =
7262
7528
  seq: number;
7263
7529
  ms: number;
7264
7530
  }
7531
+ /** `ctx.sleepUntil(when)` — a durable timer to an absolute epoch-ms deadline (feature `sleepUntil`). */
7532
+ | {
7533
+ kind: 'sleepUntil';
7534
+ seq: number;
7535
+ until: number;
7536
+ }
7265
7537
  /** `ctx.wait_signal(name)` — block until a signal `name` is delivered to the run. */
7266
7538
  | {
7267
7539
  kind: 'waitSignal';
7268
7540
  seq: number;
7269
7541
  signal: string;
7270
7542
  }
7543
+ /** `ctx.waitForSignal(name, { timeoutMs })` (feature `waitSignalTimeout`): like the in-process ctx it
7544
+ * takes TWO positions — `deadlineSeq` for the deadline timer (stamped once, at `now + timeoutMs`
7545
+ * when first applied) and `seq` for the wait. Whichever resolves first shows in history: the signal
7546
+ * at `seq`, or a `timer` at `deadlineSeq`, which the worker raises as a `SignalTimeoutError`. */
7547
+ | {
7548
+ kind: 'waitSignalTimeout';
7549
+ seq: number;
7550
+ deadlineSeq: number;
7551
+ signal: string;
7552
+ timeoutMs: number;
7553
+ }
7554
+ /** `ctx.waitForEvent(name, { match, timeoutMs })` (feature `waitEvent`): wait for a named event
7555
+ * published with `engine.publishEvent`, buffered events included. Bounded like
7556
+ * `waitSignalTimeout` when `timeoutMs` is set (then `deadlineSeq` is the deadline's position). */
7557
+ | {
7558
+ kind: 'waitEvent';
7559
+ seq: number;
7560
+ name: string;
7561
+ match?: Record<string, unknown>;
7562
+ deadlineSeq?: number;
7563
+ timeoutMs?: number;
7564
+ }
7565
+ /** `ctx.startChild(workflow, input, opts)` (feature `spawnChild`): start a child run WITHOUT awaiting
7566
+ * it. The worker returns `childId` immediately and the turn goes on; the control plane starts the
7567
+ * child once (idempotent by id) and journals a `spawn:<childId>` step at `seq`. */
7568
+ | {
7569
+ kind: 'spawnChild';
7570
+ seq: number;
7571
+ workflow: string;
7572
+ input: unknown;
7573
+ childId: string;
7574
+ priority?: number;
7575
+ }
7576
+ /** `ctx.continueAsNew(input)` (feature `continueAsNew`): the LAST command of a turn. The control
7577
+ * plane completes this run and starts its continuation (`<runId>~N`) with `input`, as the
7578
+ * in-process engine does. `seq` is the position the body had reached (not consumed). */
7579
+ | {
7580
+ kind: 'continueAsNew';
7581
+ seq: number;
7582
+ input: unknown;
7583
+ }
7271
7584
  /** `ctx.waitForAny(name, conditions)` — block until the first of `conditions` happens. The engine
7272
7585
  * resolves it exactly as the in-process ctx does (see `wait-any.ts`), journals `{ key, value }` at
7273
7586
  * `seq` and replays it as an `any` {@link HistoryEvent}. A timer's `ms` counts from when the engine
@@ -9546,6 +9859,24 @@ declare function runSchedules(engine: ScheduleTickEngine, schedules: readonly Sc
9546
9859
  */
9547
9860
  type ScheduleTickEngine = Pick<WorkflowEngine, 'start' | 'getRun'> & Partial<Pick<WorkflowEngine, 'isDraining' | 'listRuns'>>;
9548
9861
 
9862
+ /**
9863
+ * The durable dispatch policy of a `ctx.step` call as a remote `call` command carries it: the
9864
+ * `@Step`-declared config, with a per-call `opts` field winning wherever it is set — the same merge
9865
+ * the in-process `ctx.step` applies. `undefined` when neither declares any policy field, so a call
9866
+ * without one stays wire-identical to a call from before policies were carried.
9867
+ */
9868
+ declare function remoteCallPolicyOf(config: StepConfig | undefined, opts: StepDispatchOpts | undefined): RemoteCallPolicy | undefined;
9869
+ /** Total dispatch attempts a policy allows (`retries`, at least one) — the in-process rule. */
9870
+ declare function remoteCallMaxAttempts(policy: RemoteCallPolicy | undefined): number;
9871
+ /**
9872
+ * Whether a remote `call` whose attempt `attempts` FAILED with `error` is dispatched again under
9873
+ * `policy`, exactly as the in-process durable path decides it: never with a liveness `timeoutMs`
9874
+ * (there only a timeout is retried, a reported failure is final), never for an error the worker
9875
+ * marked non-retryable, and only while attempts remain. The worker's replay and the control plane
9876
+ * both decide with this one function, so they cannot disagree about a retry.
9877
+ */
9878
+ declare function remoteCallRetries(policy: RemoteCallPolicy | undefined, attempts: number, error: StepError | undefined): boolean;
9879
+
9549
9880
  /**
9550
9881
  * A {@link StepLogger} that appends to `events`, stamping each line with `now()`. Shared by the
9551
9882
  * local-step path (`ctx.step`) and the remote-worker path (`runStepHandler`) so a step records
@@ -10113,4 +10444,4 @@ declare function prevRRuleFireMs(rule: ParsedRRule, atMs: number): number | null
10113
10444
  */
10114
10445
  declare function settleResultsWithPlainCalls(store: Pick<StateStore, 'getRun' | 'getCheckpoint'> & Partial<Pick<StateStore, 'getRuns' | 'getCheckpointsForSettle' | 'getCheckpoints' | 'settleCheckpointsIfPending'>>, results: StepResultSettlement[]): Promise<(StepCheckpoint | null)[]>;
10115
10446
 
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 };
10447
+ 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, REMOTE_WORKFLOW_FEATURES, RUN_HISTORY_FIXTURE_VERSION, RUN_VALUE_FACET_LIMIT, RUN_VALUE_FACET_SCAN, RUN_WAIT_TOKEN_PREFIX, type RawWorkerDescriptor, type RemoteCallPolicy, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, type RemoteWorkflowFeature, 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, remoteCallMaxAttempts, remoteCallPolicyOf, remoteCallRetries, 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 };