@dudousxd/nestjs-durable 0.52.7 → 0.54.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.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { WorkflowCtx, SearchAttributes, WorkflowClass, StandardSchemaV1, StepError, OnErrorInput, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, StalledRunInfo, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, TenantVerifier, TenantTokenSource, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, RunRequest, RunReply, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, WorkflowRun, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, EngineEvent, StepInvocation, TenantEvent } from '@dudousxd/nestjs-durable-core';
2
- export { AttributeFilter, DynamicWorkflowCtx, EngineEvent, InferSearchAttributes, OnErrorInput, RunDetail, RunGateway, RunListItem, RunQuery, RunSchedulesOptions, RunStatus, RunWaiting, ScheduledWorkflow, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, TenantTokenSource, TenantVerifier, VerifiedTenant, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowRun, hmacTenantVerifier, prevCronFireMs, readSearchAttributes, runSchedules, scheduleRunIdAt, scheduledRunId, signTenantToken } from '@dudousxd/nestjs-durable-core';
1
+ import { WorkflowCtx, SearchAttributes, WorkflowClass, StandardSchemaV1, StepError, OnEventEntry, OnErrorInput, LifecycleEventOf, WorkflowLifecycleEvent, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, EventBatchConfig, StateStore, Transport, NamedTransport, ControlPlane, StalledRunInfo, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, TenantVerifier, TenantTokenSource, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, RunRequest, RunReply, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, WorkflowRun, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, RepublishLifecycleTarget, RepublishLifecycleResult, WorkflowLifecycleLinks, EngineEvent, StepInvocation, LifecycleKind, TenantEvent } from '@dudousxd/nestjs-durable-core';
2
+ export { AttributeFilter, DynamicWorkflowCtx, EngineEvent, EventSubscription, InferSearchAttributes, LIFECYCLE_PENDING_TAG, LifecycleEventOf, LifecycleKind, OnErrorInput, OnEventEntry, RunDetail, RunGateway, RunListItem, RunQuery, RunSchedulesOptions, RunStatus, RunWaiting, ScheduledWorkflow, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, TenantTokenSource, TenantVerifier, VerifiedTenant, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowLifecycleEvent, WorkflowRun, hmacTenantVerifier, lifecycleRunId, lifecycleSourceOf, prevCronFireMs, readSearchAttributes, runCompletedEvent, runFailedEvent, runSchedules, scheduleRunIdAt, scheduledRunId, signTenantToken, triggeredRunsOf } from '@dudousxd/nestjs-durable-core';
3
3
  import { z } from 'zod';
4
4
  import { ConcurrencyOption, StartRunDeps, RunRedisWorkerOptions, RunningWorker, DurableWorkerRuntime } from '@dudousxd/durable-worker';
5
5
  import { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown, Provider } from '@nestjs/common';
@@ -141,8 +141,8 @@ interface WorkflowMeta {
141
141
  validateInput?: ((input: unknown) => void | Promise<void>) | undefined;
142
142
  /** Typed/validated `searchAttributes` shape. See `WorkflowOptions`. */
143
143
  searchAttributes?: SearchAttributesSchema | undefined;
144
- /** Event names that start a fresh run of this workflow. See `WorkflowOptions`. */
145
- onEvent?: string[] | undefined;
144
+ /** Events that start a fresh run of this workflow. See `WorkflowOptions`. */
145
+ onEvent?: OnEventEntry[] | undefined;
146
146
  /** Debounce `onEvent` triggers — fire once it's quiet for this long. See `WorkflowOptions`. */
147
147
  debounce?: string | number | undefined;
148
148
  /** Batch `onEvent` triggers — fire on size or window. See `WorkflowOptions`. */
@@ -277,9 +277,10 @@ interface WorkflowOptions {
277
277
  * Start a fresh run of this workflow whenever any of these events is published via
278
278
  * `publishEvent(name, payload)` — the payload becomes the run's input. e.g.
279
279
  * `onEvent: ['user.registered', 'user.invited']`. The same subscription can also be declared with
280
- * the `@OnDurableEvent(...)` class decorator; the two are merged.
280
+ * the `@OnDurableEvent(...)` class decorator; the two are merged. An entry can also be
281
+ * `{ event, where }`, where `where(payload)` decides per event whether this workflow starts.
281
282
  */
282
- onEvent?: string[];
283
+ onEvent?: OnEventEntry[];
283
284
  /**
284
285
  * Coalesce `onEvent` triggers by **debouncing** — start one run only once events have been quiet
285
286
  * for this long (resets on each event), with the LAST payload. e.g. `debounce: '30s'`.
@@ -458,11 +459,121 @@ declare const ON_EVENT_METADATA: unique symbol;
458
459
  * Named "durable" on purpose: `@nestjs/event-emitter` exports an `@OnEvent` decorator, and in an
459
460
  * app using both libs an auto-import picking the wrong one fails silently in either direction.
460
461
  */
461
- declare function OnDurableEvent(...events: string[]): ClassDecorator;
462
+ declare function OnDurableEvent(...events: OnEventEntry[]): ClassDecorator;
463
+ /**
464
+ * Coalesce a subscriber's triggers by **debouncing**: start it once events have been quiet for
465
+ * `windowMs`, with the last one. `key` splits that per key: it receives the subscriber's input (what
466
+ * `input` builds), and each distinct key debounces on its own.
467
+ */
468
+ interface SubscriberDebounce<TRunInput> {
469
+ windowMs: number | string;
470
+ key?: ((input: TRunInput) => string) | undefined;
471
+ }
472
+ /**
473
+ * Coalesce a subscriber's triggers by **batching**: start it with `{ events }` once `maxSize` arrive
474
+ * or `windowMs` passes since the first. `key` batches each distinct key on its own.
475
+ */
476
+ interface SubscriberBatch<TRunInput> {
477
+ maxSize: number;
478
+ windowMs: number | string;
479
+ key?: ((input: TRunInput) => string) | undefined;
480
+ }
481
+ /** Options for {@link OnWorkflowCompleted} / {@link OnWorkflowFailed}. */
482
+ interface OnWorkflowSettledOptions<TEvent, TRunInput> {
483
+ /** Start only for the settled runs this returns true for, e.g. by `input` or `searchAttributes`. */
484
+ where?: ((event: TEvent) => boolean) | undefined;
485
+ /**
486
+ * The started run's input, built from the event. Without it the run receives the
487
+ * {@link WorkflowLifecycleEvent} itself. Lets an existing workflow subscribe with its own input
488
+ * shape, and keeps the settled run's whole input and output out of the new run's row.
489
+ */
490
+ input?: ((event: TEvent) => TRunInput) | undefined;
491
+ /**
492
+ * Debounce this workflow's triggers (see {@link SubscriberDebounce}). Sets the workflow's
493
+ * `onEvent` coalescing, so it applies to every event it subscribes to; a different `debounce` or
494
+ * `batch` already declared on it fails at registration. Not with `batch`.
495
+ */
496
+ debounce?: SubscriberDebounce<TRunInput> | undefined;
497
+ /**
498
+ * Batch this workflow's triggers (see {@link SubscriberBatch}); the run's input becomes
499
+ * `{ events: TRunInput[] }`. Same scope and conflicts as `debounce`. Not with `debounce`.
500
+ */
501
+ batch?: SubscriberBatch<TRunInput> | undefined;
502
+ }
503
+ /** Options for {@link OnWorkflowFailed}: also which endings start the subscriber. */
504
+ interface OnWorkflowFailedOptions<TEvent, TRunInput> extends OnWorkflowSettledOptions<TEvent, TRunInput> {
505
+ /** The endings that start it. Defaults to all three: `failed`, `cancelled` and `dead`. */
506
+ statuses?: Array<'failed' | 'cancelled' | 'dead'> | undefined;
507
+ }
508
+ /** `O` with a required `batch` (and no `debounce`): the overload whose subscriber takes `{ events }`. */
509
+ type Batched<O, TRunInput> = O & {
510
+ batch: SubscriberBatch<TRunInput>;
511
+ debounce?: undefined;
512
+ };
513
+ /** `O` without `batch`: the overload whose subscriber takes `TRunInput` itself. */
514
+ type Unbatched<O> = O & {
515
+ batch?: undefined;
516
+ };
517
+ /**
518
+ * A class decorator that only accepts a workflow whose `run(ctx, input)` takes `TRunInput`, so a
519
+ * subscriber with the wrong input shape fails to compile instead of failing at runtime.
520
+ */
521
+ type SubscriberDecorator<TRunInput> = <T extends abstract new (...args: never[]) => {
522
+ run: (ctx: never, input: TRunInput) => unknown;
523
+ }>(target: T) => void;
524
+ /**
525
+ * Start a fresh run of the decorated workflow whenever a run of `workflow` **completes**. The new
526
+ * run's input is the {@link WorkflowLifecycleEvent} (run id, input, output, tags, search
527
+ * attributes), or what `input` builds from it. The settling workflow does not know about its
528
+ * subscribers. Exactly once per settled run: see `runCompletedEvent` in
529
+ * `@dudousxd/nestjs-durable-core`.
530
+ *
531
+ * With a class ref, the decorated workflow's `run` input is type-checked against the event (or
532
+ * against `input`'s return type, or `{ events }` of it with `batch`). Child runs publish too, so a
533
+ * workflow that `etl` starts as a child also starts its subscribers.
534
+ *
535
+ * ```ts
536
+ * @Workflow({ name: 'refresh-summaries' })
537
+ * @OnWorkflowCompleted(IngestionWorkflow, {
538
+ * where: (e) => e.input.type === 'mvr',
539
+ * input: (e) => ({ baseId: e.input.baseId }),
540
+ * debounce: { windowMs: '30s', key: (input) => input.baseId },
541
+ * })
542
+ * class RefreshSummariesWorkflow {
543
+ * async run(ctx: WorkflowCtx, input: { baseId: string }) {}
544
+ * }
545
+ * ```
546
+ */
547
+ declare function OnWorkflowCompleted<C extends WorkflowClass, TRunInput = LifecycleEventOf<C>>(workflow: C, options: Batched<OnWorkflowSettledOptions<LifecycleEventOf<C>, TRunInput>, TRunInput>): SubscriberDecorator<{
548
+ events: TRunInput[];
549
+ }>;
550
+ declare function OnWorkflowCompleted<C extends WorkflowClass, TRunInput = LifecycleEventOf<C>>(workflow: C, options?: Unbatched<OnWorkflowSettledOptions<LifecycleEventOf<C>, TRunInput>>): SubscriberDecorator<TRunInput>;
551
+ declare function OnWorkflowCompleted(workflow: string, options?: OnWorkflowSettledOptions<WorkflowLifecycleEvent, unknown>): ClassDecorator;
552
+ /**
553
+ * Start a fresh run of the decorated workflow whenever a run of `workflow` ends **failed,
554
+ * cancelled or dead** (narrow it with `statuses`). Same contract as {@link OnWorkflowCompleted};
555
+ * the event carries `error` and `status` instead of `output`.
556
+ */
557
+ declare function OnWorkflowFailed<C extends WorkflowClass, TRunInput = LifecycleEventOf<C>>(workflow: C, options: Batched<OnWorkflowFailedOptions<LifecycleEventOf<C>, TRunInput>, TRunInput>): SubscriberDecorator<{
558
+ events: TRunInput[];
559
+ }>;
560
+ declare function OnWorkflowFailed<C extends WorkflowClass, TRunInput = LifecycleEventOf<C>>(workflow: C, options?: Unbatched<OnWorkflowFailedOptions<LifecycleEventOf<C>, TRunInput>>): SubscriberDecorator<TRunInput>;
561
+ declare function OnWorkflowFailed(workflow: string, options?: OnWorkflowFailedOptions<WorkflowLifecycleEvent, unknown>): ClassDecorator;
562
+ /** Metadata key for the `onEvent` coalescing `@OnWorkflowCompleted` / `@OnWorkflowFailed` declare. */
563
+ declare const ON_EVENT_BATCH_METADATA: unique symbol;
564
+ /**
565
+ * How a workflow coalesces its `onEvent` triggers: `@Workflow({ debounce | batch })`, or what its
566
+ * `@OnWorkflowCompleted` / `@OnWorkflowFailed` declare. Throws when both are set and differ, so a
567
+ * workflow never silently coalesces one way while its decorator says another.
568
+ */
569
+ declare function eventBatchOf(meta: WorkflowMeta, target: object): EventBatchConfig | undefined;
462
570
  /** @deprecated Renamed to `OnDurableEvent` — this alias clashes with `@nestjs/event-emitter`'s `@OnEvent` and will be removed in the next minor. */
463
571
  declare const OnEvent: typeof OnDurableEvent;
464
- /** All events a workflow class subscribes to — the union of `@Workflow({ onEvent })` and `@OnDurableEvent`. */
465
- declare function getOnEvents(meta: WorkflowMeta, target: object): string[];
572
+ /**
573
+ * All events a workflow class subscribes to: `@Workflow({ onEvent })`, `@OnDurableEvent`,
574
+ * `@OnWorkflowCompleted` and `@OnWorkflowFailed`. Repeated bare names collapse to one.
575
+ */
576
+ declare function getOnEvents(meta: WorkflowMeta, target: object): OnEventEntry[];
466
577
 
467
578
  /**
468
579
  * Retention config for the {@link RetentionPoller}. One or more {@link RetentionPolicy policies}
@@ -563,6 +674,11 @@ interface DurableModuleOptions {
563
674
  * (a poison pill that crashes the process every boot). Omit for unlimited. Operator only.
564
675
  */
565
676
  maxRecoveryAttempts?: number;
677
+ /**
678
+ * How long (ms) a run may stay unresumable because its workflow version is registered nowhere (a
679
+ * renamed or deleted workflow) before it is dead-lettered. Default 24h; `0` skips it forever.
680
+ */
681
+ unregisteredWorkflowGraceMs?: number;
566
682
  /**
567
683
  * Opt-in liveness deadline (ms) for a remote (polyglot) workflow `advance`. If the worker neither
568
684
  * returns a decision nor sends a run-scoped heartbeat within this window, the engine presumes it dead
@@ -1104,6 +1220,10 @@ declare function inAppWorkerProviders(): Provider[];
1104
1220
  * responders reply `ok: true` with no `data` instead; `ProxyRunGateway` reads both.
1105
1221
  */
1106
1222
  declare const UNSUPPORTED_RUN_REQUEST = "unsupported-request";
1223
+ /** The error `code` a responder replies with for a request it rejects as malformed or not allowed. */
1224
+ declare const BAD_RUN_REQUEST = "bad-request";
1225
+ /** The most settled runs one tenant republish reads; a larger `limit` is lowered to it. */
1226
+ declare const TENANT_REPUBLISH_MAX_LIMIT = 1000;
1107
1227
  /** The narrow slice of `Transport` the responder needs — a tenant's read/control request in, a
1108
1228
  * correlated reply out. Both are OPTIONAL on the full `Transport` interface (only broker
1109
1229
  * transports carry the run-request/reply protocol); the caller capability-checks before wiring
@@ -1128,20 +1248,6 @@ interface RunRequestResponderOptions {
1128
1248
  */
1129
1249
  warnWithoutVerifier?: boolean | undefined;
1130
1250
  }
1131
- /**
1132
- * Operator-side consumer of a tenant's {@link RunRequest}s: answers each one against a
1133
- * `RunGateway`, enforcing the tenant boundary before touching the run. For every runId-bearing
1134
- * verb it loads the run via `getRunDetail` FIRST and compares `run.namespace` to the requesting
1135
- * `msg.tenant` — a mismatch short-circuits into a `cross-tenant` error reply WITHOUT calling the
1136
- * verb, so a tenant can never read or act on another tenant's run. `listRuns` is scoped by
1137
- * overwriting the query's `namespace` with the requester's tenant, ignoring whatever the client
1138
- * sent. This is the security boundary of the tenant run gateway — do not weaken it.
1139
- *
1140
- * With {@link RunRequestResponderOptions.verifyTenant}, every request is authenticated FIRST: the
1141
- * wire `tenant` is treated as a signed token, the real tenant is derived from it, and an invalid
1142
- * token short-circuits into an `unauthorized` error reply before any run is touched. A verifier
1143
- * that throws becomes an error reply too.
1144
- */
1145
1251
  declare class RunRequestResponder {
1146
1252
  private readonly transport;
1147
1253
  private readonly gateway;
@@ -1151,20 +1257,34 @@ declare class RunRequestResponder {
1151
1257
  * failure never throws back into the transport (errors are captured into an error reply). */
1152
1258
  start(): void;
1153
1259
  private handle;
1260
+ /**
1261
+ * `detail` scoped to `tenant` (see {@link scopeRunLinks}), with its lifecycle links
1262
+ * (`workflowLifecycle`, `lifecycleSubscribers`) narrowed to the subscriptions of `tenant`'s
1263
+ * namespace, as the `workflowLifecycle` verb answers them.
1264
+ */
1265
+ private scopeLifecycle;
1266
+ /**
1267
+ * Why a tenant republish naming `subscriber` is refused, or undefined when it may go ahead: the
1268
+ * subscriber must be owed the event of `workflow` settling (as `kind`, when given) by a run of
1269
+ * the tenant's namespace (the gateway's `lifecycleSubscribers`, else the tenant's
1270
+ * `workflowLifecycle` links), so a tenant cannot have the event owed to an arbitrary name. Without
1271
+ * `subscriber` there is nothing to check.
1272
+ */
1273
+ private refuseSubscriber;
1154
1274
  private callVerb;
1155
1275
  }
1156
1276
 
1157
1277
  /**
1158
1278
  * An error reply from the control plane. `code` carries the reply's machine-readable reason when it
1159
1279
  * sent one — `unauthorized` (the tenant token was rejected), `cross-tenant` (the run belongs to
1160
- * another tenant), ... — so a caller can tell an authentication failure from a real one, as with
1280
+ * another tenant), `bad-request` (the request was malformed or not allowed), ... — so a caller can tell an authentication failure from a real one, as with
1161
1281
  * Agora's proxy.
1162
1282
  */
1163
1283
  /**
1164
1284
  * The codes the run-request responder replies with. `string & {}` keeps a code from a newer control
1165
1285
  * plane assignable without losing autocomplete on the known ones.
1166
1286
  */
1167
- type RunGatewayErrorCode = 'unauthorized' | 'cross-tenant' | typeof UNSUPPORTED_RUN_REQUEST | (string & {});
1287
+ type RunGatewayErrorCode = 'unauthorized' | 'cross-tenant' | typeof BAD_RUN_REQUEST | typeof UNSUPPORTED_RUN_REQUEST | (string & {});
1168
1288
  declare class RunGatewayError extends Error {
1169
1289
  readonly code: RunGatewayErrorCode | undefined;
1170
1290
  constructor(message: string, code?: RunGatewayErrorCode);
@@ -1246,6 +1366,20 @@ declare class ProxyRunGateway implements RunGateway {
1246
1366
  redispatchPending(runId: string): Promise<(RunResult & {
1247
1367
  redispatched: number;
1248
1368
  }) | null>;
1369
+ /**
1370
+ * Republished on the control plane: a one-run target is checked against this tenant like
1371
+ * `retry`, a by-workflow one is read over this tenant's namespace only. A control plane too old to
1372
+ * know the verb fails it with an {@link UNSUPPORTED_RUN_REQUEST} error rather than a timeout.
1373
+ */
1374
+ republishLifecycle(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
1375
+ /** Answered by the control plane's engine; same version-skew error as {@link republishLifecycle}. */
1376
+ workflowLifecycle(workflow: string): Promise<WorkflowLifecycleLinks>;
1377
+ /**
1378
+ * A verb with no fallback on an older control plane: its unsupported-request error, or the empty
1379
+ * `ok: true` reply the oldest responders send for an unknown verb, becomes a
1380
+ * {@link RunGatewayError} with code {@link UNSUPPORTED_RUN_REQUEST}.
1381
+ */
1382
+ private requestNewVerb;
1249
1383
  subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
1250
1384
  }
1251
1385
 
@@ -1294,6 +1428,18 @@ declare class StoreRunGateway implements RunGateway {
1294
1428
  constructor(store: StateStore, engine: WorkflowEngine);
1295
1429
  topology(): DurableTopology;
1296
1430
  getRunDetail(runId: string, options?: RunDetailOptions): Promise<RunDetail | null>;
1431
+ /**
1432
+ * What a run detail reads beyond the run row and its checkpoints: what this run's settling
1433
+ * started, the subscribers its lifecycle event goes to (of its namespace) and where it stands for
1434
+ * each, what started it, its workflow's lifecycle links, and the `ctx.waitForRun` waits on either
1435
+ * side of it with the other run's status. A few reads per detail: the run's own waiters while it
1436
+ * is suspended, the waiters on it (one prefix read), and one batched read of every linked run.
1437
+ */
1438
+ private lifecycleLinks;
1439
+ workflowLifecycle(workflow: string, opts?: {
1440
+ namespace?: string | undefined;
1441
+ }): Promise<WorkflowLifecycleLinks>;
1442
+ lifecycleSubscribers(workflow: string, kind: LifecycleKind, namespace: string): Promise<string[]>;
1297
1443
  getRun(runId: string): Promise<WorkflowRun | null>;
1298
1444
  getFanMembers(runId: string, group: string, query: FanPageQuery): Promise<FanPage | null>;
1299
1445
  listRuns(query: RunQuery): Promise<RunListItem[]>;
@@ -1338,6 +1484,7 @@ declare class StoreRunGateway implements RunGateway {
1338
1484
  redispatchPending(runId: string): Promise<(RunResult & {
1339
1485
  redispatched: number;
1340
1486
  }) | null>;
1487
+ republishLifecycle(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
1341
1488
  subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
1342
1489
  }
1343
1490
 
@@ -1452,6 +1599,18 @@ declare class WorkflowService {
1452
1599
  id?: string;
1453
1600
  buffer?: boolean;
1454
1601
  }): Promise<number>;
1602
+ /**
1603
+ * The runs started by `runId` settling, through `@OnWorkflowCompleted` / `@OnWorkflowFailed` (or
1604
+ * an `onEvent` on `runCompletedEvent(...)`). Only subscribers registered on this engine are
1605
+ * considered. For the reverse link, `lifecycleSourceOf(run)` reads it from the run itself.
1606
+ */
1607
+ triggeredRuns(runId: string): Promise<string[]>;
1608
+ /**
1609
+ * Publish settled runs' lifecycle events again: to a subscriber registered after they settled, or
1610
+ * one restricted by `subscriber`. Subscribers already started for a run are not started again.
1611
+ * See `WorkflowEngine.republishLifecycle`.
1612
+ */
1613
+ republishLifecycle(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
1455
1614
  }
1456
1615
 
1457
- export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, type DtoClass, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, type ErrorClassWithCode, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, type IoSchema, ON_ERROR_METADATA, ON_EVENT_METADATA, On, OnDurableEvent, OnError, type OnErrorMethod, OnEvent, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, RunGatewayError, type RunGatewayErrorCode, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestResponderOptions, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, UNSUPPORTED_RUN_REQUEST, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowAttributesOf, type WorkflowMeta, type WorkflowOptions, WorkflowService, attributesOf, entityConfigFor, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, onErrorCodesOf, thinWorkerProviders, unavailableRunGateway };
1616
+ export { BAD_RUN_REQUEST, CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, type DtoClass, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, type ErrorClassWithCode, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, type IoSchema, ON_ERROR_METADATA, ON_EVENT_BATCH_METADATA, ON_EVENT_METADATA, On, OnDurableEvent, OnError, type OnErrorMethod, OnEvent, OnWorkflowCompleted, OnWorkflowFailed, type OnWorkflowFailedOptions, type OnWorkflowSettledOptions, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, RunGatewayError, type RunGatewayErrorCode, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestResponderOptions, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, type SubscriberBatch, type SubscriberDebounce, type SubscriberDecorator, TENANT_REPUBLISH_MAX_LIMIT, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, UNSUPPORTED_RUN_REQUEST, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowAttributesOf, type WorkflowMeta, type WorkflowOptions, WorkflowService, attributesOf, entityConfigFor, eventBatchOf, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, onErrorCodesOf, thinWorkerProviders, unavailableRunGateway };
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { WorkflowCtx, SearchAttributes, WorkflowClass, StandardSchemaV1, StepError, OnErrorInput, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, StalledRunInfo, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, TenantVerifier, TenantTokenSource, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, RunRequest, RunReply, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, WorkflowRun, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, EngineEvent, StepInvocation, TenantEvent } from '@dudousxd/nestjs-durable-core';
2
- export { AttributeFilter, DynamicWorkflowCtx, EngineEvent, InferSearchAttributes, OnErrorInput, RunDetail, RunGateway, RunListItem, RunQuery, RunSchedulesOptions, RunStatus, RunWaiting, ScheduledWorkflow, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, TenantTokenSource, TenantVerifier, VerifiedTenant, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowRun, hmacTenantVerifier, prevCronFireMs, readSearchAttributes, runSchedules, scheduleRunIdAt, scheduledRunId, signTenantToken } from '@dudousxd/nestjs-durable-core';
1
+ import { WorkflowCtx, SearchAttributes, WorkflowClass, StandardSchemaV1, StepError, OnEventEntry, OnErrorInput, LifecycleEventOf, WorkflowLifecycleEvent, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, EventBatchConfig, StateStore, Transport, NamedTransport, ControlPlane, StalledRunInfo, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, TenantVerifier, TenantTokenSource, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, RunRequest, RunReply, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, WorkflowRun, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, RepublishLifecycleTarget, RepublishLifecycleResult, WorkflowLifecycleLinks, EngineEvent, StepInvocation, LifecycleKind, TenantEvent } from '@dudousxd/nestjs-durable-core';
2
+ export { AttributeFilter, DynamicWorkflowCtx, EngineEvent, EventSubscription, InferSearchAttributes, LIFECYCLE_PENDING_TAG, LifecycleEventOf, LifecycleKind, OnErrorInput, OnEventEntry, RunDetail, RunGateway, RunListItem, RunQuery, RunSchedulesOptions, RunStatus, RunWaiting, ScheduledWorkflow, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, TenantTokenSource, TenantVerifier, VerifiedTenant, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowLifecycleEvent, WorkflowRun, hmacTenantVerifier, lifecycleRunId, lifecycleSourceOf, prevCronFireMs, readSearchAttributes, runCompletedEvent, runFailedEvent, runSchedules, scheduleRunIdAt, scheduledRunId, signTenantToken, triggeredRunsOf } from '@dudousxd/nestjs-durable-core';
3
3
  import { z } from 'zod';
4
4
  import { ConcurrencyOption, StartRunDeps, RunRedisWorkerOptions, RunningWorker, DurableWorkerRuntime } from '@dudousxd/durable-worker';
5
5
  import { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown, Provider } from '@nestjs/common';
@@ -141,8 +141,8 @@ interface WorkflowMeta {
141
141
  validateInput?: ((input: unknown) => void | Promise<void>) | undefined;
142
142
  /** Typed/validated `searchAttributes` shape. See `WorkflowOptions`. */
143
143
  searchAttributes?: SearchAttributesSchema | undefined;
144
- /** Event names that start a fresh run of this workflow. See `WorkflowOptions`. */
145
- onEvent?: string[] | undefined;
144
+ /** Events that start a fresh run of this workflow. See `WorkflowOptions`. */
145
+ onEvent?: OnEventEntry[] | undefined;
146
146
  /** Debounce `onEvent` triggers — fire once it's quiet for this long. See `WorkflowOptions`. */
147
147
  debounce?: string | number | undefined;
148
148
  /** Batch `onEvent` triggers — fire on size or window. See `WorkflowOptions`. */
@@ -277,9 +277,10 @@ interface WorkflowOptions {
277
277
  * Start a fresh run of this workflow whenever any of these events is published via
278
278
  * `publishEvent(name, payload)` — the payload becomes the run's input. e.g.
279
279
  * `onEvent: ['user.registered', 'user.invited']`. The same subscription can also be declared with
280
- * the `@OnDurableEvent(...)` class decorator; the two are merged.
280
+ * the `@OnDurableEvent(...)` class decorator; the two are merged. An entry can also be
281
+ * `{ event, where }`, where `where(payload)` decides per event whether this workflow starts.
281
282
  */
282
- onEvent?: string[];
283
+ onEvent?: OnEventEntry[];
283
284
  /**
284
285
  * Coalesce `onEvent` triggers by **debouncing** — start one run only once events have been quiet
285
286
  * for this long (resets on each event), with the LAST payload. e.g. `debounce: '30s'`.
@@ -458,11 +459,121 @@ declare const ON_EVENT_METADATA: unique symbol;
458
459
  * Named "durable" on purpose: `@nestjs/event-emitter` exports an `@OnEvent` decorator, and in an
459
460
  * app using both libs an auto-import picking the wrong one fails silently in either direction.
460
461
  */
461
- declare function OnDurableEvent(...events: string[]): ClassDecorator;
462
+ declare function OnDurableEvent(...events: OnEventEntry[]): ClassDecorator;
463
+ /**
464
+ * Coalesce a subscriber's triggers by **debouncing**: start it once events have been quiet for
465
+ * `windowMs`, with the last one. `key` splits that per key: it receives the subscriber's input (what
466
+ * `input` builds), and each distinct key debounces on its own.
467
+ */
468
+ interface SubscriberDebounce<TRunInput> {
469
+ windowMs: number | string;
470
+ key?: ((input: TRunInput) => string) | undefined;
471
+ }
472
+ /**
473
+ * Coalesce a subscriber's triggers by **batching**: start it with `{ events }` once `maxSize` arrive
474
+ * or `windowMs` passes since the first. `key` batches each distinct key on its own.
475
+ */
476
+ interface SubscriberBatch<TRunInput> {
477
+ maxSize: number;
478
+ windowMs: number | string;
479
+ key?: ((input: TRunInput) => string) | undefined;
480
+ }
481
+ /** Options for {@link OnWorkflowCompleted} / {@link OnWorkflowFailed}. */
482
+ interface OnWorkflowSettledOptions<TEvent, TRunInput> {
483
+ /** Start only for the settled runs this returns true for, e.g. by `input` or `searchAttributes`. */
484
+ where?: ((event: TEvent) => boolean) | undefined;
485
+ /**
486
+ * The started run's input, built from the event. Without it the run receives the
487
+ * {@link WorkflowLifecycleEvent} itself. Lets an existing workflow subscribe with its own input
488
+ * shape, and keeps the settled run's whole input and output out of the new run's row.
489
+ */
490
+ input?: ((event: TEvent) => TRunInput) | undefined;
491
+ /**
492
+ * Debounce this workflow's triggers (see {@link SubscriberDebounce}). Sets the workflow's
493
+ * `onEvent` coalescing, so it applies to every event it subscribes to; a different `debounce` or
494
+ * `batch` already declared on it fails at registration. Not with `batch`.
495
+ */
496
+ debounce?: SubscriberDebounce<TRunInput> | undefined;
497
+ /**
498
+ * Batch this workflow's triggers (see {@link SubscriberBatch}); the run's input becomes
499
+ * `{ events: TRunInput[] }`. Same scope and conflicts as `debounce`. Not with `debounce`.
500
+ */
501
+ batch?: SubscriberBatch<TRunInput> | undefined;
502
+ }
503
+ /** Options for {@link OnWorkflowFailed}: also which endings start the subscriber. */
504
+ interface OnWorkflowFailedOptions<TEvent, TRunInput> extends OnWorkflowSettledOptions<TEvent, TRunInput> {
505
+ /** The endings that start it. Defaults to all three: `failed`, `cancelled` and `dead`. */
506
+ statuses?: Array<'failed' | 'cancelled' | 'dead'> | undefined;
507
+ }
508
+ /** `O` with a required `batch` (and no `debounce`): the overload whose subscriber takes `{ events }`. */
509
+ type Batched<O, TRunInput> = O & {
510
+ batch: SubscriberBatch<TRunInput>;
511
+ debounce?: undefined;
512
+ };
513
+ /** `O` without `batch`: the overload whose subscriber takes `TRunInput` itself. */
514
+ type Unbatched<O> = O & {
515
+ batch?: undefined;
516
+ };
517
+ /**
518
+ * A class decorator that only accepts a workflow whose `run(ctx, input)` takes `TRunInput`, so a
519
+ * subscriber with the wrong input shape fails to compile instead of failing at runtime.
520
+ */
521
+ type SubscriberDecorator<TRunInput> = <T extends abstract new (...args: never[]) => {
522
+ run: (ctx: never, input: TRunInput) => unknown;
523
+ }>(target: T) => void;
524
+ /**
525
+ * Start a fresh run of the decorated workflow whenever a run of `workflow` **completes**. The new
526
+ * run's input is the {@link WorkflowLifecycleEvent} (run id, input, output, tags, search
527
+ * attributes), or what `input` builds from it. The settling workflow does not know about its
528
+ * subscribers. Exactly once per settled run: see `runCompletedEvent` in
529
+ * `@dudousxd/nestjs-durable-core`.
530
+ *
531
+ * With a class ref, the decorated workflow's `run` input is type-checked against the event (or
532
+ * against `input`'s return type, or `{ events }` of it with `batch`). Child runs publish too, so a
533
+ * workflow that `etl` starts as a child also starts its subscribers.
534
+ *
535
+ * ```ts
536
+ * @Workflow({ name: 'refresh-summaries' })
537
+ * @OnWorkflowCompleted(IngestionWorkflow, {
538
+ * where: (e) => e.input.type === 'mvr',
539
+ * input: (e) => ({ baseId: e.input.baseId }),
540
+ * debounce: { windowMs: '30s', key: (input) => input.baseId },
541
+ * })
542
+ * class RefreshSummariesWorkflow {
543
+ * async run(ctx: WorkflowCtx, input: { baseId: string }) {}
544
+ * }
545
+ * ```
546
+ */
547
+ declare function OnWorkflowCompleted<C extends WorkflowClass, TRunInput = LifecycleEventOf<C>>(workflow: C, options: Batched<OnWorkflowSettledOptions<LifecycleEventOf<C>, TRunInput>, TRunInput>): SubscriberDecorator<{
548
+ events: TRunInput[];
549
+ }>;
550
+ declare function OnWorkflowCompleted<C extends WorkflowClass, TRunInput = LifecycleEventOf<C>>(workflow: C, options?: Unbatched<OnWorkflowSettledOptions<LifecycleEventOf<C>, TRunInput>>): SubscriberDecorator<TRunInput>;
551
+ declare function OnWorkflowCompleted(workflow: string, options?: OnWorkflowSettledOptions<WorkflowLifecycleEvent, unknown>): ClassDecorator;
552
+ /**
553
+ * Start a fresh run of the decorated workflow whenever a run of `workflow` ends **failed,
554
+ * cancelled or dead** (narrow it with `statuses`). Same contract as {@link OnWorkflowCompleted};
555
+ * the event carries `error` and `status` instead of `output`.
556
+ */
557
+ declare function OnWorkflowFailed<C extends WorkflowClass, TRunInput = LifecycleEventOf<C>>(workflow: C, options: Batched<OnWorkflowFailedOptions<LifecycleEventOf<C>, TRunInput>, TRunInput>): SubscriberDecorator<{
558
+ events: TRunInput[];
559
+ }>;
560
+ declare function OnWorkflowFailed<C extends WorkflowClass, TRunInput = LifecycleEventOf<C>>(workflow: C, options?: Unbatched<OnWorkflowFailedOptions<LifecycleEventOf<C>, TRunInput>>): SubscriberDecorator<TRunInput>;
561
+ declare function OnWorkflowFailed(workflow: string, options?: OnWorkflowFailedOptions<WorkflowLifecycleEvent, unknown>): ClassDecorator;
562
+ /** Metadata key for the `onEvent` coalescing `@OnWorkflowCompleted` / `@OnWorkflowFailed` declare. */
563
+ declare const ON_EVENT_BATCH_METADATA: unique symbol;
564
+ /**
565
+ * How a workflow coalesces its `onEvent` triggers: `@Workflow({ debounce | batch })`, or what its
566
+ * `@OnWorkflowCompleted` / `@OnWorkflowFailed` declare. Throws when both are set and differ, so a
567
+ * workflow never silently coalesces one way while its decorator says another.
568
+ */
569
+ declare function eventBatchOf(meta: WorkflowMeta, target: object): EventBatchConfig | undefined;
462
570
  /** @deprecated Renamed to `OnDurableEvent` — this alias clashes with `@nestjs/event-emitter`'s `@OnEvent` and will be removed in the next minor. */
463
571
  declare const OnEvent: typeof OnDurableEvent;
464
- /** All events a workflow class subscribes to — the union of `@Workflow({ onEvent })` and `@OnDurableEvent`. */
465
- declare function getOnEvents(meta: WorkflowMeta, target: object): string[];
572
+ /**
573
+ * All events a workflow class subscribes to: `@Workflow({ onEvent })`, `@OnDurableEvent`,
574
+ * `@OnWorkflowCompleted` and `@OnWorkflowFailed`. Repeated bare names collapse to one.
575
+ */
576
+ declare function getOnEvents(meta: WorkflowMeta, target: object): OnEventEntry[];
466
577
 
467
578
  /**
468
579
  * Retention config for the {@link RetentionPoller}. One or more {@link RetentionPolicy policies}
@@ -563,6 +674,11 @@ interface DurableModuleOptions {
563
674
  * (a poison pill that crashes the process every boot). Omit for unlimited. Operator only.
564
675
  */
565
676
  maxRecoveryAttempts?: number;
677
+ /**
678
+ * How long (ms) a run may stay unresumable because its workflow version is registered nowhere (a
679
+ * renamed or deleted workflow) before it is dead-lettered. Default 24h; `0` skips it forever.
680
+ */
681
+ unregisteredWorkflowGraceMs?: number;
566
682
  /**
567
683
  * Opt-in liveness deadline (ms) for a remote (polyglot) workflow `advance`. If the worker neither
568
684
  * returns a decision nor sends a run-scoped heartbeat within this window, the engine presumes it dead
@@ -1104,6 +1220,10 @@ declare function inAppWorkerProviders(): Provider[];
1104
1220
  * responders reply `ok: true` with no `data` instead; `ProxyRunGateway` reads both.
1105
1221
  */
1106
1222
  declare const UNSUPPORTED_RUN_REQUEST = "unsupported-request";
1223
+ /** The error `code` a responder replies with for a request it rejects as malformed or not allowed. */
1224
+ declare const BAD_RUN_REQUEST = "bad-request";
1225
+ /** The most settled runs one tenant republish reads; a larger `limit` is lowered to it. */
1226
+ declare const TENANT_REPUBLISH_MAX_LIMIT = 1000;
1107
1227
  /** The narrow slice of `Transport` the responder needs — a tenant's read/control request in, a
1108
1228
  * correlated reply out. Both are OPTIONAL on the full `Transport` interface (only broker
1109
1229
  * transports carry the run-request/reply protocol); the caller capability-checks before wiring
@@ -1128,20 +1248,6 @@ interface RunRequestResponderOptions {
1128
1248
  */
1129
1249
  warnWithoutVerifier?: boolean | undefined;
1130
1250
  }
1131
- /**
1132
- * Operator-side consumer of a tenant's {@link RunRequest}s: answers each one against a
1133
- * `RunGateway`, enforcing the tenant boundary before touching the run. For every runId-bearing
1134
- * verb it loads the run via `getRunDetail` FIRST and compares `run.namespace` to the requesting
1135
- * `msg.tenant` — a mismatch short-circuits into a `cross-tenant` error reply WITHOUT calling the
1136
- * verb, so a tenant can never read or act on another tenant's run. `listRuns` is scoped by
1137
- * overwriting the query's `namespace` with the requester's tenant, ignoring whatever the client
1138
- * sent. This is the security boundary of the tenant run gateway — do not weaken it.
1139
- *
1140
- * With {@link RunRequestResponderOptions.verifyTenant}, every request is authenticated FIRST: the
1141
- * wire `tenant` is treated as a signed token, the real tenant is derived from it, and an invalid
1142
- * token short-circuits into an `unauthorized` error reply before any run is touched. A verifier
1143
- * that throws becomes an error reply too.
1144
- */
1145
1251
  declare class RunRequestResponder {
1146
1252
  private readonly transport;
1147
1253
  private readonly gateway;
@@ -1151,20 +1257,34 @@ declare class RunRequestResponder {
1151
1257
  * failure never throws back into the transport (errors are captured into an error reply). */
1152
1258
  start(): void;
1153
1259
  private handle;
1260
+ /**
1261
+ * `detail` scoped to `tenant` (see {@link scopeRunLinks}), with its lifecycle links
1262
+ * (`workflowLifecycle`, `lifecycleSubscribers`) narrowed to the subscriptions of `tenant`'s
1263
+ * namespace, as the `workflowLifecycle` verb answers them.
1264
+ */
1265
+ private scopeLifecycle;
1266
+ /**
1267
+ * Why a tenant republish naming `subscriber` is refused, or undefined when it may go ahead: the
1268
+ * subscriber must be owed the event of `workflow` settling (as `kind`, when given) by a run of
1269
+ * the tenant's namespace (the gateway's `lifecycleSubscribers`, else the tenant's
1270
+ * `workflowLifecycle` links), so a tenant cannot have the event owed to an arbitrary name. Without
1271
+ * `subscriber` there is nothing to check.
1272
+ */
1273
+ private refuseSubscriber;
1154
1274
  private callVerb;
1155
1275
  }
1156
1276
 
1157
1277
  /**
1158
1278
  * An error reply from the control plane. `code` carries the reply's machine-readable reason when it
1159
1279
  * sent one — `unauthorized` (the tenant token was rejected), `cross-tenant` (the run belongs to
1160
- * another tenant), ... — so a caller can tell an authentication failure from a real one, as with
1280
+ * another tenant), `bad-request` (the request was malformed or not allowed), ... — so a caller can tell an authentication failure from a real one, as with
1161
1281
  * Agora's proxy.
1162
1282
  */
1163
1283
  /**
1164
1284
  * The codes the run-request responder replies with. `string & {}` keeps a code from a newer control
1165
1285
  * plane assignable without losing autocomplete on the known ones.
1166
1286
  */
1167
- type RunGatewayErrorCode = 'unauthorized' | 'cross-tenant' | typeof UNSUPPORTED_RUN_REQUEST | (string & {});
1287
+ type RunGatewayErrorCode = 'unauthorized' | 'cross-tenant' | typeof BAD_RUN_REQUEST | typeof UNSUPPORTED_RUN_REQUEST | (string & {});
1168
1288
  declare class RunGatewayError extends Error {
1169
1289
  readonly code: RunGatewayErrorCode | undefined;
1170
1290
  constructor(message: string, code?: RunGatewayErrorCode);
@@ -1246,6 +1366,20 @@ declare class ProxyRunGateway implements RunGateway {
1246
1366
  redispatchPending(runId: string): Promise<(RunResult & {
1247
1367
  redispatched: number;
1248
1368
  }) | null>;
1369
+ /**
1370
+ * Republished on the control plane: a one-run target is checked against this tenant like
1371
+ * `retry`, a by-workflow one is read over this tenant's namespace only. A control plane too old to
1372
+ * know the verb fails it with an {@link UNSUPPORTED_RUN_REQUEST} error rather than a timeout.
1373
+ */
1374
+ republishLifecycle(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
1375
+ /** Answered by the control plane's engine; same version-skew error as {@link republishLifecycle}. */
1376
+ workflowLifecycle(workflow: string): Promise<WorkflowLifecycleLinks>;
1377
+ /**
1378
+ * A verb with no fallback on an older control plane: its unsupported-request error, or the empty
1379
+ * `ok: true` reply the oldest responders send for an unknown verb, becomes a
1380
+ * {@link RunGatewayError} with code {@link UNSUPPORTED_RUN_REQUEST}.
1381
+ */
1382
+ private requestNewVerb;
1249
1383
  subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
1250
1384
  }
1251
1385
 
@@ -1294,6 +1428,18 @@ declare class StoreRunGateway implements RunGateway {
1294
1428
  constructor(store: StateStore, engine: WorkflowEngine);
1295
1429
  topology(): DurableTopology;
1296
1430
  getRunDetail(runId: string, options?: RunDetailOptions): Promise<RunDetail | null>;
1431
+ /**
1432
+ * What a run detail reads beyond the run row and its checkpoints: what this run's settling
1433
+ * started, the subscribers its lifecycle event goes to (of its namespace) and where it stands for
1434
+ * each, what started it, its workflow's lifecycle links, and the `ctx.waitForRun` waits on either
1435
+ * side of it with the other run's status. A few reads per detail: the run's own waiters while it
1436
+ * is suspended, the waiters on it (one prefix read), and one batched read of every linked run.
1437
+ */
1438
+ private lifecycleLinks;
1439
+ workflowLifecycle(workflow: string, opts?: {
1440
+ namespace?: string | undefined;
1441
+ }): Promise<WorkflowLifecycleLinks>;
1442
+ lifecycleSubscribers(workflow: string, kind: LifecycleKind, namespace: string): Promise<string[]>;
1297
1443
  getRun(runId: string): Promise<WorkflowRun | null>;
1298
1444
  getFanMembers(runId: string, group: string, query: FanPageQuery): Promise<FanPage | null>;
1299
1445
  listRuns(query: RunQuery): Promise<RunListItem[]>;
@@ -1338,6 +1484,7 @@ declare class StoreRunGateway implements RunGateway {
1338
1484
  redispatchPending(runId: string): Promise<(RunResult & {
1339
1485
  redispatched: number;
1340
1486
  }) | null>;
1487
+ republishLifecycle(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
1341
1488
  subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
1342
1489
  }
1343
1490
 
@@ -1452,6 +1599,18 @@ declare class WorkflowService {
1452
1599
  id?: string;
1453
1600
  buffer?: boolean;
1454
1601
  }): Promise<number>;
1602
+ /**
1603
+ * The runs started by `runId` settling, through `@OnWorkflowCompleted` / `@OnWorkflowFailed` (or
1604
+ * an `onEvent` on `runCompletedEvent(...)`). Only subscribers registered on this engine are
1605
+ * considered. For the reverse link, `lifecycleSourceOf(run)` reads it from the run itself.
1606
+ */
1607
+ triggeredRuns(runId: string): Promise<string[]>;
1608
+ /**
1609
+ * Publish settled runs' lifecycle events again: to a subscriber registered after they settled, or
1610
+ * one restricted by `subscriber`. Subscribers already started for a run are not started again.
1611
+ * See `WorkflowEngine.republishLifecycle`.
1612
+ */
1613
+ republishLifecycle(target: RepublishLifecycleTarget): Promise<RepublishLifecycleResult>;
1455
1614
  }
1456
1615
 
1457
- export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, type DtoClass, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, type ErrorClassWithCode, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, type IoSchema, ON_ERROR_METADATA, ON_EVENT_METADATA, On, OnDurableEvent, OnError, type OnErrorMethod, OnEvent, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, RunGatewayError, type RunGatewayErrorCode, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestResponderOptions, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, UNSUPPORTED_RUN_REQUEST, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowAttributesOf, type WorkflowMeta, type WorkflowOptions, WorkflowService, attributesOf, entityConfigFor, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, onErrorCodesOf, thinWorkerProviders, unavailableRunGateway };
1616
+ export { BAD_RUN_REQUEST, CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, type DtoClass, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, type ErrorClassWithCode, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, type IoSchema, ON_ERROR_METADATA, ON_EVENT_BATCH_METADATA, ON_EVENT_METADATA, On, OnDurableEvent, OnError, type OnErrorMethod, OnEvent, OnWorkflowCompleted, OnWorkflowFailed, type OnWorkflowFailedOptions, type OnWorkflowSettledOptions, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, RunGatewayError, type RunGatewayErrorCode, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestResponderOptions, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, type SubscriberBatch, type SubscriberDebounce, type SubscriberDecorator, TENANT_REPUBLISH_MAX_LIMIT, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, UNSUPPORTED_RUN_REQUEST, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowAttributesOf, type WorkflowMeta, type WorkflowOptions, WorkflowService, attributesOf, entityConfigFor, eventBatchOf, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, onErrorCodesOf, thinWorkerProviders, unavailableRunGateway };