@dudousxd/nestjs-durable 0.47.0 → 0.48.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { WorkflowCtx, SearchAttributes, WorkflowClass, StepError, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, EngineEvent, RunRequest, RunReply, StepInvocation, WorkflowRun, TenantEvent } from '@dudousxd/nestjs-durable-core';
-export { AttributeFilter, DynamicWorkflowCtx, EngineEvent, InferSearchAttributes, RunDetail, RunGateway, RunListItem, RunQuery, RunStatus, RunWaiting, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowRun, readSearchAttributes } from '@dudousxd/nestjs-durable-core';
+import { WorkflowCtx, SearchAttributes, WorkflowClass, StepError, OnErrorInput, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, EngineEvent, RunRequest, RunReply, StepInvocation, WorkflowRun, TenantEvent } from '@dudousxd/nestjs-durable-core';
+export { AttributeFilter, DynamicWorkflowCtx, EngineEvent, InferSearchAttributes, OnErrorInput, RunDetail, RunGateway, RunListItem, RunQuery, RunStatus, RunWaiting, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowRun, readSearchAttributes } from '@dudousxd/nestjs-durable-core';
 import { z } from 'zod';
 import { ConcurrencyOption, StartRunDeps, RunRedisWorkerOptions, RunningWorker, DurableWorkerRuntime } from '@dudousxd/durable-worker';
 import { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown, Provider } from '@nestjs/common';
@@ -108,6 +108,11 @@ interface WorkflowMeta {
     version: string;
     /** The workflow this workflow's dead runs route to (a name or a class). See `WorkflowOptions`. */
     deadLetterWorkflow?: WorkflowRef | undefined;
+    /** Where failed runs are routed by error code. See `WorkflowOptions`. */
+    onError?: {
+        code?: string | ErrorClassWithCode;
+        workflow: WorkflowRef;
+    }[] | undefined;
     /** Static searchable labels stamped on every run of this workflow. See `WorkflowOptions`. */
     tags?: string[] | undefined;
     /** Per-key serialization (a durable mutex). See `WorkflowOptions`. */
@@ -146,6 +151,16 @@ interface WorkflowOptions {
      * {@link DeadLetter} payload, idempotent by a `dlq:<runId>` id.
      */
     deadLetterWorkflow?: WorkflowRef;
+    /**
+     * Route failed runs of this workflow to other **registered** workflows by error code — the
+     * separate-class form of an `@OnError` method (see it for the semantics). Each handler receives an
+     * {@link OnErrorInput}; omit `code` for the catch-all. A code routed here and by an `@OnError`
+     * method on the class is a boot-time error.
+     */
+    onError?: {
+        code?: string | ErrorClassWithCode;
+        workflow: WorkflowRef;
+    }[];
     /**
      * Static labels stamped on **every run** of this workflow (e.g. `tags: ['etl', 'critical']`) and
      * merged with any per-run tags passed to `start`. Searchable/filterable in the dashboard.
@@ -356,6 +371,42 @@ interface DeadLetter<TInput = unknown> {
  */
 declare function DeadLetter(): MethodDecorator;
 declare function isDeadLetterHandler(method: Function): boolean;
+declare const ON_ERROR_METADATA: unique symbol;
+/**
+ * An error class that declares the `code` it is thrown with (`static readonly code = 'invalid_line'`).
+ * `@OnError(Class)` matches on that code, not on `instanceof`: a dispatched step's error reaches the
+ * workflow as a plain `{ message, code }`, without its class.
+ */
+interface ErrorClassWithCode {
+    readonly code: string;
+}
+type WorkflowShape = {
+    run(ctx: any, input: any): Promise<unknown>;
+};
+/**
+ * An `@OnError` method: a workflow body that receives the failed run's {@link OnErrorInput}, typed with
+ * `run`'s input, and returns what `run` returns.
+ */
+type OnErrorMethod<T extends WorkflowShape> = (ctx: WorkflowCtx<any>, failure: OnErrorInput<Parameters<T['run']>[1]>) => Promise<Awaited<ReturnType<T['run']>>>;
+/**
+ * Marks a method on a `@Workflow` class as the handler for a failure of that workflow's runs. When a
+ * run ends `failed` with an error of the given `code` (a string, or an {@link ErrorClassWithCode}),
+ * the engine starts the method as its own durable workflow — registered as
+ * `<workflow>.onError.<method>`, with a `<runId>.onError` id — and the failed run waits for it, then
+ * settles with its outcome: the method's return value as its output, or its error. Without an
+ * argument it takes any failure no other code matches.
+ *
+ * The engine routes the failure, so this holds for whatever ran the body (inline, an in-app worker,
+ * another runtime). The method's signature is checked against the workflow: `(ctx, failure)`, with
+ * `failure.input` typed as `run`'s input and the return type as `run`'s. Stack the decorator to give
+ * one method several codes. Saga compensations of the failed body run before the handoff;
+ * cancellation and non-determinism are never routed.
+ */
+declare function OnError(match?: string | ErrorClassWithCode): <T extends WorkflowShape>(_target: T, _propertyKey: string | symbol, descriptor: {
+    value?: OnErrorMethod<T> | undefined;
+}) => void;
+/** The codes an `@OnError` method takes (`undefined` for the catch-all), or undefined if it has none. */
+declare function onErrorCodesOf(method: Function): (string | undefined)[] | undefined;
 declare const ON_EVENT_METADATA: unique symbol;
 /**
  * Subscribe a `@Workflow` class to one or more events: when any of them is published via
@@ -500,6 +551,37 @@ interface DurableModuleOptions {
      * Ignored when `remoteRedispatchMs` is unset. Operator only.
      */
     remoteRedispatchMax?: number;
+    /**
+     * Fallback wake-up (ms) for a run suspended on an event (child, signal, `waitForEvent`, remote
+     * result) whose wake-up was lost: the reconcile pass re-drives it after this window, an idempotent
+     * replay that re-suspends a still-pending wait. Defaults to 300000 (5min); `0` disables it.
+     * See `WorkflowEngineDeps.reconcileMs`. Operator only.
+     */
+    reconcileMs?: number;
+    /**
+     * The most due timers one timer-poll pass loads and drives, most overdue first, so a wave of
+     * thousands of due runs is worked through in batches. Defaults to 500; a non-finite or sub-1 value
+     * falls back to the default. See `WorkflowEngineDeps.timerBatchSize`. Operator only.
+     */
+    timerBatchSize?: number;
+    /**
+     * Retention (ms) for a buffered event that no `waitForEvent` ever claims; the reconcile pass prunes
+     * rows past `publishedAt + eventBufferTtlMs`. Omit (or `0`) to keep them until consumed, the
+     * default. See `WorkflowEngineDeps.eventBufferTtlMs`. Operator only.
+     */
+    eventBufferTtlMs?: number;
+    /**
+     * How long (ms) a run parked `blocked` (no capable, protocol-compatible live worker) waits before
+     * the blocked-recovery poll re-checks the fleet. Defaults to 5000. See
+     * `WorkflowEngineDeps.blockedPollMs`. Operator only.
+     */
+    blockedPollMs?: number;
+    /**
+     * Persist a `running` checkpoint when a local step's body begins, so an in-flight step survives a
+     * dashboard reload. Defaults to `true`; set `false` on hot paths with many short local steps to
+     * halve their checkpoint writes. See `WorkflowEngineDeps.trackStepStart`. Operator only.
+     */
+    trackStepStart?: boolean;
     /**
      * The **default** workflow to route dead-lettered runs to, for workflows that don't declare their
      * own. When a run is moved to `dead` (exceeded `maxRecoveryAttempts`), the started handler gets a
@@ -773,9 +855,10 @@ type RunRedisWorkerFn = (opts: RunRedisWorkerOptions) => Promise<RunningWorker>;
  */
 declare class ThinWorkflowRegistrar implements OnModuleInit {
     private readonly discovery;
+    private readonly metadataScanner;
     private readonly runtime;
     private readonly options;
-    constructor(discovery: DiscoveryService, runtime: DurableWorkerRuntime | null, options: DurableModuleOptions);
+    constructor(discovery: DiscoveryService, metadataScanner: MetadataScanner, runtime: DurableWorkerRuntime | null, options: DurableModuleOptions);
     onModuleInit(): void;
 }
 /**
@@ -940,13 +1023,25 @@ declare class ProxyRunGateway implements RunGateway {
     private readonly transport;
     private readonly tenant;
     private readonly timeoutMs;
+    private readonly capabilityTtlMs;
     private readonly pending;
-    constructor(transport: Transport, tenant: string, timeoutMs?: number);
+    /** Verb → when to ask the control plane for it again, after it answered that it does not know it.
+     *  During a rolling upgrade the control plane is several pods of mixed versions behind one queue,
+     *  and a reply does not say which pod sent it, so the whole control plane is assumed old until the
+     *  entry expires. */
+    private readonly unsupportedUntil;
+    constructor(transport: Transport, tenant: string, timeoutMs?: number, capabilityTtlMs?: number);
     private handleReply;
     private request;
     topology(): DurableTopology;
+    /**
+     * A control plane that predates {@link RunDetailOptions} ignores them and sends the full detail;
+     * a summarized detail always carries `fans`, so its absence means the summary is made here.
+     */
     getRunDetail(runId: string, options?: RunDetailOptions): Promise<RunDetail | null>;
+    /** Paged from the full detail when the control plane is too old to page a fan itself. */
     getFanMembers(runId: string, group: string, query: FanPageQuery): Promise<FanPage | null>;
+    private knownUnsupported;
     /** The control plane's `StoreRunGateway` resolves each run's `waiting` descriptor; the reply carries
      *  it through as plain JSON, so a tenant's list rows name the wait too. */
     listRuns(query: RunQuery): Promise<RunListItem[]>;
@@ -989,6 +1084,12 @@ declare function isOperatorRole(options: DurableModuleOptions): boolean;
  */
 declare function isDrivingOperator(options: DurableModuleOptions): boolean;
 
+/**
+ * The error `code` a responder replies with for a verb it does not know, so a newer tenant can tell
+ * "this control plane is older than me" from a real failure and fall back at once. Earlier
+ * responders reply `ok: true` with no `data` instead; `ProxyRunGateway` reads both.
+ */
+declare const UNSUPPORTED_RUN_REQUEST = "unsupported-request";
 /** The narrow slice of `Transport` the responder needs — a tenant's read/control request in, a
  *  correlated reply out. Both are OPTIONAL on the full `Transport` interface (only broker
  *  transports carry the run-request/reply protocol); the caller capability-checks before wiring
@@ -1204,4 +1305,4 @@ declare class WorkflowService {
     }): Promise<number>;
 }
 
-export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, ON_EVENT_METADATA, On, OnDurableEvent, OnEvent, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowAttributesOf, type WorkflowMeta, type WorkflowOptions, WorkflowService, attributesOf, entityConfigFor, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, thinWorkerProviders, unavailableRunGateway };
+export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, 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, ON_ERROR_METADATA, ON_EVENT_METADATA, On, OnDurableEvent, OnError, type OnErrorMethod, OnEvent, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, 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 };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { WorkflowCtx, SearchAttributes, WorkflowClass, StepError, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, EngineEvent, RunRequest, RunReply, StepInvocation, WorkflowRun, TenantEvent } from '@dudousxd/nestjs-durable-core';
-export { AttributeFilter, DynamicWorkflowCtx, EngineEvent, InferSearchAttributes, RunDetail, RunGateway, RunListItem, RunQuery, RunStatus, RunWaiting, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowRun, readSearchAttributes } from '@dudousxd/nestjs-durable-core';
+import { WorkflowCtx, SearchAttributes, WorkflowClass, StepError, OnErrorInput, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, EngineEvent, RunRequest, RunReply, StepInvocation, WorkflowRun, TenantEvent } from '@dudousxd/nestjs-durable-core';
+export { AttributeFilter, DynamicWorkflowCtx, EngineEvent, InferSearchAttributes, OnErrorInput, RunDetail, RunGateway, RunListItem, RunQuery, RunStatus, RunWaiting, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowRun, readSearchAttributes } from '@dudousxd/nestjs-durable-core';
 import { z } from 'zod';
 import { ConcurrencyOption, StartRunDeps, RunRedisWorkerOptions, RunningWorker, DurableWorkerRuntime } from '@dudousxd/durable-worker';
 import { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown, Provider } from '@nestjs/common';
@@ -108,6 +108,11 @@ interface WorkflowMeta {
     version: string;
     /** The workflow this workflow's dead runs route to (a name or a class). See `WorkflowOptions`. */
     deadLetterWorkflow?: WorkflowRef | undefined;
+    /** Where failed runs are routed by error code. See `WorkflowOptions`. */
+    onError?: {
+        code?: string | ErrorClassWithCode;
+        workflow: WorkflowRef;
+    }[] | undefined;
     /** Static searchable labels stamped on every run of this workflow. See `WorkflowOptions`. */
     tags?: string[] | undefined;
     /** Per-key serialization (a durable mutex). See `WorkflowOptions`. */
@@ -146,6 +151,16 @@ interface WorkflowOptions {
      * {@link DeadLetter} payload, idempotent by a `dlq:<runId>` id.
      */
     deadLetterWorkflow?: WorkflowRef;
+    /**
+     * Route failed runs of this workflow to other **registered** workflows by error code — the
+     * separate-class form of an `@OnError` method (see it for the semantics). Each handler receives an
+     * {@link OnErrorInput}; omit `code` for the catch-all. A code routed here and by an `@OnError`
+     * method on the class is a boot-time error.
+     */
+    onError?: {
+        code?: string | ErrorClassWithCode;
+        workflow: WorkflowRef;
+    }[];
     /**
      * Static labels stamped on **every run** of this workflow (e.g. `tags: ['etl', 'critical']`) and
      * merged with any per-run tags passed to `start`. Searchable/filterable in the dashboard.
@@ -356,6 +371,42 @@ interface DeadLetter<TInput = unknown> {
  */
 declare function DeadLetter(): MethodDecorator;
 declare function isDeadLetterHandler(method: Function): boolean;
+declare const ON_ERROR_METADATA: unique symbol;
+/**
+ * An error class that declares the `code` it is thrown with (`static readonly code = 'invalid_line'`).
+ * `@OnError(Class)` matches on that code, not on `instanceof`: a dispatched step's error reaches the
+ * workflow as a plain `{ message, code }`, without its class.
+ */
+interface ErrorClassWithCode {
+    readonly code: string;
+}
+type WorkflowShape = {
+    run(ctx: any, input: any): Promise<unknown>;
+};
+/**
+ * An `@OnError` method: a workflow body that receives the failed run's {@link OnErrorInput}, typed with
+ * `run`'s input, and returns what `run` returns.
+ */
+type OnErrorMethod<T extends WorkflowShape> = (ctx: WorkflowCtx<any>, failure: OnErrorInput<Parameters<T['run']>[1]>) => Promise<Awaited<ReturnType<T['run']>>>;
+/**
+ * Marks a method on a `@Workflow` class as the handler for a failure of that workflow's runs. When a
+ * run ends `failed` with an error of the given `code` (a string, or an {@link ErrorClassWithCode}),
+ * the engine starts the method as its own durable workflow — registered as
+ * `<workflow>.onError.<method>`, with a `<runId>.onError` id — and the failed run waits for it, then
+ * settles with its outcome: the method's return value as its output, or its error. Without an
+ * argument it takes any failure no other code matches.
+ *
+ * The engine routes the failure, so this holds for whatever ran the body (inline, an in-app worker,
+ * another runtime). The method's signature is checked against the workflow: `(ctx, failure)`, with
+ * `failure.input` typed as `run`'s input and the return type as `run`'s. Stack the decorator to give
+ * one method several codes. Saga compensations of the failed body run before the handoff;
+ * cancellation and non-determinism are never routed.
+ */
+declare function OnError(match?: string | ErrorClassWithCode): <T extends WorkflowShape>(_target: T, _propertyKey: string | symbol, descriptor: {
+    value?: OnErrorMethod<T> | undefined;
+}) => void;
+/** The codes an `@OnError` method takes (`undefined` for the catch-all), or undefined if it has none. */
+declare function onErrorCodesOf(method: Function): (string | undefined)[] | undefined;
 declare const ON_EVENT_METADATA: unique symbol;
 /**
  * Subscribe a `@Workflow` class to one or more events: when any of them is published via
@@ -500,6 +551,37 @@ interface DurableModuleOptions {
      * Ignored when `remoteRedispatchMs` is unset. Operator only.
      */
     remoteRedispatchMax?: number;
+    /**
+     * Fallback wake-up (ms) for a run suspended on an event (child, signal, `waitForEvent`, remote
+     * result) whose wake-up was lost: the reconcile pass re-drives it after this window, an idempotent
+     * replay that re-suspends a still-pending wait. Defaults to 300000 (5min); `0` disables it.
+     * See `WorkflowEngineDeps.reconcileMs`. Operator only.
+     */
+    reconcileMs?: number;
+    /**
+     * The most due timers one timer-poll pass loads and drives, most overdue first, so a wave of
+     * thousands of due runs is worked through in batches. Defaults to 500; a non-finite or sub-1 value
+     * falls back to the default. See `WorkflowEngineDeps.timerBatchSize`. Operator only.
+     */
+    timerBatchSize?: number;
+    /**
+     * Retention (ms) for a buffered event that no `waitForEvent` ever claims; the reconcile pass prunes
+     * rows past `publishedAt + eventBufferTtlMs`. Omit (or `0`) to keep them until consumed, the
+     * default. See `WorkflowEngineDeps.eventBufferTtlMs`. Operator only.
+     */
+    eventBufferTtlMs?: number;
+    /**
+     * How long (ms) a run parked `blocked` (no capable, protocol-compatible live worker) waits before
+     * the blocked-recovery poll re-checks the fleet. Defaults to 5000. See
+     * `WorkflowEngineDeps.blockedPollMs`. Operator only.
+     */
+    blockedPollMs?: number;
+    /**
+     * Persist a `running` checkpoint when a local step's body begins, so an in-flight step survives a
+     * dashboard reload. Defaults to `true`; set `false` on hot paths with many short local steps to
+     * halve their checkpoint writes. See `WorkflowEngineDeps.trackStepStart`. Operator only.
+     */
+    trackStepStart?: boolean;
     /**
      * The **default** workflow to route dead-lettered runs to, for workflows that don't declare their
      * own. When a run is moved to `dead` (exceeded `maxRecoveryAttempts`), the started handler gets a
@@ -773,9 +855,10 @@ type RunRedisWorkerFn = (opts: RunRedisWorkerOptions) => Promise<RunningWorker>;
  */
 declare class ThinWorkflowRegistrar implements OnModuleInit {
     private readonly discovery;
+    private readonly metadataScanner;
     private readonly runtime;
     private readonly options;
-    constructor(discovery: DiscoveryService, runtime: DurableWorkerRuntime | null, options: DurableModuleOptions);
+    constructor(discovery: DiscoveryService, metadataScanner: MetadataScanner, runtime: DurableWorkerRuntime | null, options: DurableModuleOptions);
     onModuleInit(): void;
 }
 /**
@@ -940,13 +1023,25 @@ declare class ProxyRunGateway implements RunGateway {
     private readonly transport;
     private readonly tenant;
     private readonly timeoutMs;
+    private readonly capabilityTtlMs;
     private readonly pending;
-    constructor(transport: Transport, tenant: string, timeoutMs?: number);
+    /** Verb → when to ask the control plane for it again, after it answered that it does not know it.
+     *  During a rolling upgrade the control plane is several pods of mixed versions behind one queue,
+     *  and a reply does not say which pod sent it, so the whole control plane is assumed old until the
+     *  entry expires. */
+    private readonly unsupportedUntil;
+    constructor(transport: Transport, tenant: string, timeoutMs?: number, capabilityTtlMs?: number);
     private handleReply;
     private request;
     topology(): DurableTopology;
+    /**
+     * A control plane that predates {@link RunDetailOptions} ignores them and sends the full detail;
+     * a summarized detail always carries `fans`, so its absence means the summary is made here.
+     */
     getRunDetail(runId: string, options?: RunDetailOptions): Promise<RunDetail | null>;
+    /** Paged from the full detail when the control plane is too old to page a fan itself. */
     getFanMembers(runId: string, group: string, query: FanPageQuery): Promise<FanPage | null>;
+    private knownUnsupported;
     /** The control plane's `StoreRunGateway` resolves each run's `waiting` descriptor; the reply carries
      *  it through as plain JSON, so a tenant's list rows name the wait too. */
     listRuns(query: RunQuery): Promise<RunListItem[]>;
@@ -989,6 +1084,12 @@ declare function isOperatorRole(options: DurableModuleOptions): boolean;
  */
 declare function isDrivingOperator(options: DurableModuleOptions): boolean;
 
+/**
+ * The error `code` a responder replies with for a verb it does not know, so a newer tenant can tell
+ * "this control plane is older than me" from a real failure and fall back at once. Earlier
+ * responders reply `ok: true` with no `data` instead; `ProxyRunGateway` reads both.
+ */
+declare const UNSUPPORTED_RUN_REQUEST = "unsupported-request";
 /** The narrow slice of `Transport` the responder needs — a tenant's read/control request in, a
  *  correlated reply out. Both are OPTIONAL on the full `Transport` interface (only broker
  *  transports carry the run-request/reply protocol); the caller capability-checks before wiring
@@ -1204,4 +1305,4 @@ declare class WorkflowService {
     }): Promise<number>;
 }
 
-export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, ON_EVENT_METADATA, On, OnDurableEvent, OnEvent, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowAttributesOf, type WorkflowMeta, type WorkflowOptions, WorkflowService, attributesOf, entityConfigFor, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, thinWorkerProviders, unavailableRunGateway };
+export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DURABLE_WORKER_RUNTIME, DeadLetter, 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, ON_ERROR_METADATA, ON_EVENT_METADATA, On, OnDurableEvent, OnError, type OnErrorMethod, OnEvent, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, 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 };