@dudousxd/nestjs-durable 0.47.1 → 0.48.0

package/dist/index.cjs

@@ -49,14 +49,16 @@ __export(index_exports, {
   IN_APP_WORKER_RUNNERS: () => IN_APP_WORKER_RUNNERS,
   IN_APP_WORKER_RUNTIME: () => IN_APP_WORKER_RUNTIME,
   InAppWorkerBootstrap: () => InAppWorkerBootstrap,
+  ON_ERROR_METADATA: () => ON_ERROR_METADATA,
   ON_EVENT_METADATA: () => ON_EVENT_METADATA,
   On: () => On,
   OnDurableEvent: () => OnDurableEvent,
+  OnError: () => OnError,
   OnEvent: () => OnEvent,
   ProxyRunGateway: () => ProxyRunGateway,
   RUN_GATEWAY: () => RUN_GATEWAY,
   RUN_REDIS_WORKER: () => RUN_REDIS_WORKER,
-  RunGateway: () => import_nestjs_durable_core15.RunGateway,
+  RunGateway: () => import_nestjs_durable_core17.RunGateway,
   RunRequestResponder: () => RunRequestResponder,
   STEP_INTERCEPTOR_METADATA: () => STEP_INTERCEPTOR_METADATA,
   Step: () => Step,
@@ -66,9 +68,10 @@ __export(index_exports, {
   ThinStepRegistrar: () => ThinStepRegistrar,
   ThinWorkerBootstrap: () => ThinWorkerBootstrap,
   ThinWorkflowRegistrar: () => ThinWorkflowRegistrar,
+  UNSUPPORTED_RUN_REQUEST: () => UNSUPPORTED_RUN_REQUEST,
   WORKFLOW_METADATA: () => WORKFLOW_METADATA,
   Workflow: () => Workflow,
-  WorkflowEngine: () => import_nestjs_durable_core15.WorkflowEngine,
+  WorkflowEngine: () => import_nestjs_durable_core17.WorkflowEngine,
   WorkflowService: () => WorkflowService,
   attributesOf: () => attributesOf,
   entityConfigFor: () => entityConfigFor,
@@ -81,7 +84,8 @@ __export(index_exports, {
   isDrivingOperator: () => isDrivingOperator,
   isOperatorRole: () => isOperatorRole,
   isStepInterceptor: () => isStepInterceptor,
-  readSearchAttributes: () => import_nestjs_durable_core15.readSearchAttributes,
+  onErrorCodesOf: () => onErrorCodesOf,
+  readSearchAttributes: () => import_nestjs_durable_core17.readSearchAttributes,
   thinWorkerProviders: () => thinWorkerProviders,
   unavailableRunGateway: () => unavailableRunGateway
 });
@@ -211,6 +215,7 @@ function Workflow(options) {
       name: options.name,
       version: options.version ?? "1",
       deadLetterWorkflow: options.deadLetterWorkflow,
+      onError: options.onError,
       tags: options.tags,
       singleton: options.singleton,
       concurrency: options.concurrency,
@@ -288,6 +293,26 @@ function isDeadLetterHandler(method) {
   return Reflect.getMetadata(DEAD_LETTER_METADATA, method) === true;
 }
 __name(isDeadLetterHandler, "isDeadLetterHandler");
+var ON_ERROR_METADATA = Symbol("nestjs-durable:on-error");
+function OnError(match) {
+  const code = match === void 0 || typeof match === "string" ? match : match.code;
+  if (match !== void 0 && typeof code !== "string") {
+    throw new Error('@OnError(ErrorClass): the class has no static `code`. Declare `static readonly code = "..."` on it, or pass the code string.');
+  }
+  return (_target, _propertyKey, descriptor) => {
+    const method = descriptor.value;
+    const codes = Reflect.getMetadata(ON_ERROR_METADATA, method) ?? [];
+    Reflect.defineMetadata(ON_ERROR_METADATA, [
+      ...codes,
+      code
+    ], method);
+  };
+}
+__name(OnError, "OnError");
+function onErrorCodesOf(method) {
+  return Reflect.getMetadata(ON_ERROR_METADATA, method);
+}
+__name(onErrorCodesOf, "onErrorCodesOf");
 var ON_EVENT_METADATA = Symbol("nestjs-durable:on-event");
 function OnDurableEvent(...events) {
   return (target) => {
@@ -449,7 +474,7 @@ function tenantUnsupported(method) {
 __name(tenantUnsupported, "tenantUnsupported");
 
 // src/durable-worker.module.ts
-var import_nestjs_durable_core4 = require("@dudousxd/nestjs-durable-core");
+var import_nestjs_durable_core5 = require("@dudousxd/nestjs-durable-core");
 var import_common2 = require("@nestjs/common");
 var import_core = require("@nestjs/core");
 
@@ -490,6 +515,66 @@ function scanSteps(discovery, scanner, register) {
 }
 __name(scanSteps, "scanSteps");
 
+// src/on-error-handlers.ts
+var import_nestjs_durable_core4 = require("@dudousxd/nestjs-durable-core");
+function onErrorHandlersOf(meta, instance, scanner) {
+  const handlers = [];
+  const routes = [];
+  for (const methodName of scanner.getAllMethodNames(Object.getPrototypeOf(instance))) {
+    const method = instance[methodName];
+    const codes = typeof method === "function" ? onErrorCodesOf(method) : void 0;
+    if (!codes) continue;
+    const name = `${meta.name}.onError.${methodName}`;
+    handlers.push([
+      name,
+      (ctx, input) => method.call(instance, ctx, input)
+    ]);
+    for (const code of codes) routes.push({
+      code,
+      workflow: name
+    });
+  }
+  for (const r of meta.onError ?? []) {
+    routes.push({
+      code: r.code === void 0 || typeof r.code === "string" ? r.code : r.code.code,
+      workflow: (0, import_nestjs_durable_core4.workflowName)(r.workflow)
+    });
+  }
+  return {
+    handlers,
+    routes
+  };
+}
+__name(onErrorHandlersOf, "onErrorHandlersOf");
+
+// src/runtime-registration.ts
+function registerOnRuntime(runtime, scanner, meta, instance, origin) {
+  const { handlers, routes } = onErrorHandlersOf(meta, instance, scanner);
+  const announced = {
+    version: meta.version,
+    ...origin !== void 0 ? {
+      origin
+    } : {}
+  };
+  runtime.registerWorkflow(meta.name, (ctx, input) => instance.run(ctx, input), {
+    ...announced,
+    ...meta.requires !== void 0 ? {
+      requires: meta.requires
+    } : {},
+    // A catch-all goes on the wire without a `code` key, not with an undefined one.
+    ...routes.length > 0 ? {
+      onError: routes.map(({ code, workflow }) => code === void 0 ? {
+        workflow
+      } : {
+        code,
+        workflow
+      })
+    } : {}
+  });
+  for (const [name, fn] of handlers) runtime.registerWorkflow(name, fn, announced);
+}
+__name(registerOnRuntime, "registerOnRuntime");
+
 // src/durable-worker.module.ts
 function _ts_decorate2(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -529,34 +614,29 @@ var ThinWorkflowRegistrar = class {
     __name(this, "ThinWorkflowRegistrar");
   }
   discovery;
+  metadataScanner;
   runtime;
   options;
-  constructor(discovery, runtime, options) {
+  constructor(discovery, metadataScanner, runtime, options) {
     this.discovery = discovery;
+    this.metadataScanner = metadataScanner;
     this.runtime = runtime;
     this.options = options;
   }
   onModuleInit() {
     const runtime = this.runtime;
     if (runtime === null || !isPureThinWorker(this.options)) return;
-    scanWorkflows(this.discovery, (meta, instance, origin) => runtime.registerWorkflow(meta.name, (ctx, input) => instance.run(ctx, input), {
-      version: meta.version,
-      ...meta.requires !== void 0 ? {
-        requires: meta.requires
-      } : {},
-      ...origin !== void 0 ? {
-        origin
-      } : {}
-    }));
+    scanWorkflows(this.discovery, (meta, instance, origin) => registerOnRuntime(runtime, this.metadataScanner, meta, instance, origin));
   }
 };
 ThinWorkflowRegistrar = _ts_decorate2([
   (0, import_common2.Injectable)(),
-  _ts_param(1, (0, import_common2.Inject)(DURABLE_WORKER_RUNTIME)),
-  _ts_param(2, (0, import_common2.Inject)(import_nestjs_durable_core4.DURABLE_OPTIONS_CANONICAL)),
+  _ts_param(2, (0, import_common2.Inject)(DURABLE_WORKER_RUNTIME)),
+  _ts_param(3, (0, import_common2.Inject)(import_nestjs_durable_core5.DURABLE_OPTIONS_CANONICAL)),
   _ts_metadata2("design:type", Function),
   _ts_metadata2("design:paramtypes", [
     typeof import_core.DiscoveryService === "undefined" ? Object : import_core.DiscoveryService,
+    typeof import_core.MetadataScanner === "undefined" ? Object : import_core.MetadataScanner,
     Object,
     typeof DurableModuleOptions === "undefined" ? Object : DurableModuleOptions
   ])
@@ -584,7 +664,7 @@ var ThinStepRegistrar = class {
 ThinStepRegistrar = _ts_decorate2([
   (0, import_common2.Injectable)(),
   _ts_param(2, (0, import_common2.Inject)(DURABLE_WORKER_RUNTIME)),
-  _ts_param(3, (0, import_common2.Inject)(import_nestjs_durable_core4.DURABLE_OPTIONS_CANONICAL)),
+  _ts_param(3, (0, import_common2.Inject)(import_nestjs_durable_core5.DURABLE_OPTIONS_CANONICAL)),
   _ts_metadata2("design:type", Function),
   _ts_metadata2("design:paramtypes", [
     typeof import_core.DiscoveryService === "undefined" ? Object : import_core.DiscoveryService,
@@ -638,7 +718,7 @@ var ThinWorkerBootstrap = class {
 ThinWorkerBootstrap = _ts_decorate2([
   (0, import_common2.Injectable)(),
   _ts_param(0, (0, import_common2.Inject)(DURABLE_WORKER_RUNTIME)),
-  _ts_param(1, (0, import_common2.Inject)(import_nestjs_durable_core4.DURABLE_OPTIONS_CANONICAL)),
+  _ts_param(1, (0, import_common2.Inject)(import_nestjs_durable_core5.DURABLE_OPTIONS_CANONICAL)),
   _ts_param(2, (0, import_common2.Inject)(RUN_REDIS_WORKER)),
   _ts_param(3, (0, import_common2.Inject)(DURABLE_WORKER_RUNNERS)),
   _ts_metadata2("design:type", Function),
@@ -668,7 +748,7 @@ function thinWorkerProviders() {
         workflowGroup: options.partition ?? ""
       }) : null, "useFactory"),
       inject: [
-        import_nestjs_durable_core4.DURABLE_OPTIONS_CANONICAL
+        import_nestjs_durable_core5.DURABLE_OPTIONS_CANONICAL
       ]
     },
     {
@@ -738,12 +818,12 @@ function unavailableRunGateway() {
 __name(unavailableRunGateway, "unavailableRunGateway");
 
 // src/durable.module.ts
-var import_nestjs_durable_core14 = require("@dudousxd/nestjs-durable-core");
+var import_nestjs_durable_core16 = require("@dudousxd/nestjs-durable-core");
 var import_common12 = require("@nestjs/common");
 var import_core5 = require("@nestjs/core");
 
 // src/durable-step.registrar.ts
-var import_nestjs_durable_core5 = require("@dudousxd/nestjs-durable-core");
+var import_nestjs_durable_core6 = require("@dudousxd/nestjs-durable-core");
 var import_common3 = require("@nestjs/common");
 var import_core2 = require("@nestjs/core");
 
@@ -811,8 +891,8 @@ var DurableStepRegistrar = class {
 };
 DurableStepRegistrar = _ts_decorate3([
   (0, import_common3.Injectable)(),
-  _ts_param2(2, (0, import_common3.Inject)(import_nestjs_durable_core5.TRANSPORT_CANONICAL)),
-  _ts_param2(3, (0, import_common3.Inject)(import_nestjs_durable_core5.DURABLE_OPTIONS_CANONICAL)),
+  _ts_param2(2, (0, import_common3.Inject)(import_nestjs_durable_core6.TRANSPORT_CANONICAL)),
+  _ts_param2(3, (0, import_common3.Inject)(import_nestjs_durable_core6.DURABLE_OPTIONS_CANONICAL)),
   _ts_metadata3("design:type", Function),
   _ts_metadata3("design:paramtypes", [
     typeof import_core2.DiscoveryService === "undefined" ? Object : import_core2.DiscoveryService,
@@ -823,7 +903,7 @@ DurableStepRegistrar = _ts_decorate3([
 ], DurableStepRegistrar);
 
 // src/entity.ts
-var import_nestjs_durable_core6 = require("@dudousxd/nestjs-durable-core");
+var import_nestjs_durable_core7 = require("@dudousxd/nestjs-durable-core");
 var import_common4 = require("@nestjs/common");
 var import_reflect_metadata2 = require("reflect-metadata");
 function _ts_decorate4(decorators, target, key, desc) {
@@ -906,12 +986,12 @@ EntityService = _ts_decorate4([
   (0, import_common4.Injectable)(),
   _ts_metadata4("design:type", Function),
   _ts_metadata4("design:paramtypes", [
-    typeof import_nestjs_durable_core6.WorkflowEngine === "undefined" ? Object : import_nestjs_durable_core6.WorkflowEngine
+    typeof import_nestjs_durable_core7.WorkflowEngine === "undefined" ? Object : import_nestjs_durable_core7.WorkflowEngine
   ])
 ], EntityService);
 
 // src/in-app-worker.ts
-var import_nestjs_durable_core7 = require("@dudousxd/nestjs-durable-core");
+var import_nestjs_durable_core8 = require("@dudousxd/nestjs-durable-core");
 var import_common5 = require("@nestjs/common");
 var import_core3 = require("@nestjs/core");
 function _ts_decorate5(decorators, target, key, desc) {
@@ -983,15 +1063,7 @@ var InAppWorkerBootstrap = class {
   onModuleInit() {
     const runtime = this.runtime;
     if (runtime === null || !isCoLocatedWorker(this.options)) return;
-    scanWorkflows(this.discovery, (meta, instance, origin) => runtime.registerWorkflow(meta.name, (ctx, input) => instance.run(ctx, input), {
-      version: meta.version,
-      ...meta.requires !== void 0 ? {
-        requires: meta.requires
-      } : {},
-      ...origin !== void 0 ? {
-        origin
-      } : {}
-    }));
+    scanWorkflows(this.discovery, (meta, instance, origin) => registerOnRuntime(runtime, this.metadataScanner, meta, instance, origin));
     scanSteps(this.discovery, this.metadataScanner, (meta, handler) => runtime.registerStep(meta.name, handler));
   }
   async onApplicationBootstrap() {
@@ -1023,7 +1095,7 @@ var InAppWorkerBootstrap = class {
 };
 InAppWorkerBootstrap = _ts_decorate5([
   (0, import_common5.Injectable)(),
-  _ts_param3(2, (0, import_common5.Inject)(import_nestjs_durable_core7.DURABLE_OPTIONS_CANONICAL)),
+  _ts_param3(2, (0, import_common5.Inject)(import_nestjs_durable_core8.DURABLE_OPTIONS_CANONICAL)),
   _ts_param3(3, (0, import_common5.Inject)(IN_APP_WORKER_RUNTIME)),
   _ts_param3(4, (0, import_common5.Inject)(IN_APP_RUN_REDIS_WORKER)),
   _ts_param3(5, (0, import_common5.Inject)(IN_APP_WORKER_RUNNERS)),
@@ -1043,8 +1115,8 @@ function inAppWorkerProviders() {
       provide: IN_APP_WORKER_BINDING,
       useFactory: /* @__PURE__ */ __name((transport, options) => inAppWorkerBinding(transport, options), "useFactory"),
       inject: [
-        import_nestjs_durable_core7.TRANSPORT_CANONICAL,
-        import_nestjs_durable_core7.DURABLE_OPTIONS_CANONICAL
+        import_nestjs_durable_core8.TRANSPORT_CANONICAL,
+        import_nestjs_durable_core8.DURABLE_OPTIONS_CANONICAL
       ]
     },
     {
@@ -1064,7 +1136,7 @@ function inAppWorkerProviders() {
         workflowGroup: options.partition ?? ""
       }) : null, "useFactory"),
       inject: [
-        import_nestjs_durable_core7.DURABLE_OPTIONS_CANONICAL
+        import_nestjs_durable_core8.DURABLE_OPTIONS_CANONICAL
       ]
     },
     {
@@ -1081,7 +1153,212 @@ function inAppWorkerProviders() {
 __name(inAppWorkerProviders, "inAppWorkerProviders");
 
 // src/proxy-run-gateway.ts
+var import_nestjs_durable_core9 = require("@dudousxd/nestjs-durable-core");
 var import_common6 = require("@nestjs/common");
+
+// src/run-request-responder.ts
+var UNSUPPORTED_RUN_REQUEST = "unsupported-request";
+var KNOWN_KINDS = /* @__PURE__ */ new Set([
+  "getRunDetail",
+  "getFanMembers",
+  "listRuns",
+  "runFacets",
+  "runValueFacets",
+  "workerHealth",
+  "cancel",
+  "retry",
+  "continue",
+  "retryWithInput",
+  "redispatch",
+  "waitingFor"
+]);
+var RunRequestResponder = class {
+  static {
+    __name(this, "RunRequestResponder");
+  }
+  transport;
+  gateway;
+  constructor(transport, gateway) {
+    this.transport = transport;
+    this.gateway = gateway;
+  }
+  /** Register the consumer on the transport. Each request is answered independently; a handler
+  *  failure never throws back into the transport (errors are captured into an error reply). */
+  start() {
+    this.transport.onRunRequest(async (msg) => {
+      let reply;
+      try {
+        reply = await this.handle(msg);
+      } catch (err) {
+        reply = {
+          requestId: msg.requestId,
+          result: {
+            ok: false,
+            error: {
+              message: err instanceof Error ? err.message : String(err)
+            }
+          }
+        };
+      }
+      await this.transport.publishRunReply(reply);
+    });
+  }
+  async handle(msg) {
+    const { body } = msg;
+    if (!KNOWN_KINDS.has(body.kind)) {
+      return {
+        requestId: msg.requestId,
+        result: {
+          ok: false,
+          error: {
+            message: `the control plane does not support the ${String(body.kind)} run request`,
+            code: UNSUPPORTED_RUN_REQUEST
+          }
+        }
+      };
+    }
+    if (body.kind === "listRuns") {
+      const data = await this.gateway.listRuns({
+        ...body.query,
+        namespace: msg.tenant
+      });
+      return {
+        requestId: msg.requestId,
+        result: {
+          ok: true,
+          data
+        }
+      };
+    }
+    if (body.kind === "runFacets") {
+      const data = await this.gateway.runFacets({
+        ...body.query,
+        namespace: msg.tenant
+      });
+      return {
+        requestId: msg.requestId,
+        result: {
+          ok: true,
+          data
+        }
+      };
+    }
+    if (body.kind === "runValueFacets") {
+      const data = await this.gateway.runValueFacets(body.axis, {
+        ...body.query,
+        namespace: msg.tenant
+      }, body.opts);
+      return {
+        requestId: msg.requestId,
+        result: {
+          ok: true,
+          data
+        }
+      };
+    }
+    if (body.kind === "workerHealth") {
+      const all = await this.gateway.workerHealth();
+      const data = all.filter((h) => h.group.endsWith(`@${msg.tenant}`));
+      return {
+        requestId: msg.requestId,
+        result: {
+          ok: true,
+          data
+        }
+      };
+    }
+    if (body.kind === "waitingFor") {
+      const all = await this.gateway.waitingFor(body.runIds);
+      const owned = await Promise.all(Object.entries(all).map(async ([runId, waiting]) => {
+        const owner = this.gateway.getRun ? await this.gateway.getRun(runId) : (await this.gateway.getRunDetail(runId))?.run;
+        return owner && owner.namespace === msg.tenant ? [
+          runId,
+          waiting
+        ] : void 0;
+      }));
+      const data = {};
+      for (const entry of owned) {
+        if (entry) data[entry[0]] = entry[1];
+      }
+      return {
+        requestId: msg.requestId,
+        result: {
+          ok: true,
+          data
+        }
+      };
+    }
+    const detail = body.kind === "getRunDetail" || !this.gateway.getRun ? await this.gateway.getRunDetail(body.runId, body.kind === "getRunDetail" ? body.options : void 0) : void 0;
+    const run = detail !== void 0 ? detail?.run ?? null : await this.gateway.getRun?.(body.runId);
+    if (run && run.namespace !== msg.tenant) {
+      return {
+        requestId: msg.requestId,
+        result: {
+          ok: false,
+          error: {
+            message: "run belongs to another tenant",
+            code: "cross-tenant"
+          }
+        }
+      };
+    }
+    if (body.kind === "getRunDetail") {
+      return {
+        requestId: msg.requestId,
+        result: {
+          ok: true,
+          data: detail
+        }
+      };
+    }
+    if (body.kind === "getFanMembers") {
+      const data = run ? await this.gateway.getFanMembers?.(body.runId, body.group, body.query) ?? null : null;
+      return {
+        requestId: msg.requestId,
+        result: {
+          ok: true,
+          data
+        }
+      };
+    }
+    try {
+      const data = await this.callVerb(body);
+      return {
+        requestId: msg.requestId,
+        result: {
+          ok: true,
+          data
+        }
+      };
+    } catch (err) {
+      return {
+        requestId: msg.requestId,
+        result: {
+          ok: false,
+          error: {
+            message: err instanceof Error ? err.message : String(err)
+          }
+        }
+      };
+    }
+  }
+  callVerb(body) {
+    switch (body.kind) {
+      case "cancel":
+        return this.gateway.cancel(body.runId, body.opts);
+      case "retry":
+        return this.gateway.retry(body.runId);
+      case "continue":
+        return this.gateway.continue(body.runId);
+      case "retryWithInput":
+        return this.gateway.retryWithInput(body.runId, body.input);
+      case "redispatch":
+        return this.gateway.redispatchPending(body.runId);
+    }
+  }
+};
+
+// src/proxy-run-gateway.ts
 function _ts_decorate6(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
@@ -1102,6 +1379,15 @@ function _ts_metadata6(metadataKey, metadataValue) {
   }
 }
 __name(_ts_metadata6, "_ts_metadata");
+var UnsupportedRunRequestError = class UnsupportedRunRequestError2 extends Error {
+  static {
+    __name(this, "UnsupportedRunRequestError");
+  }
+};
+function isUnsupported(err) {
+  return err instanceof UnsupportedRunRequestError;
+}
+__name(isUnsupported, "isUnsupported");
 var ProxyRunGateway = class {
   static {
     __name(this, "ProxyRunGateway");
@@ -1109,11 +1395,18 @@ var ProxyRunGateway = class {
   transport;
   tenant;
   timeoutMs;
+  capabilityTtlMs;
   pending = /* @__PURE__ */ new Map();
-  constructor(transport, tenant, timeoutMs = 1e4) {
+  /** 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. */
+  unsupportedUntil = /* @__PURE__ */ new Map();
+  constructor(transport, tenant, timeoutMs = 1e4, capabilityTtlMs = 6e4) {
     this.transport = transport;
     this.tenant = tenant;
     this.timeoutMs = timeoutMs;
+    this.capabilityTtlMs = capabilityTtlMs;
     this.transport.onRunReply?.((reply) => this.handleReply(reply));
   }
   handleReply(reply) {
@@ -1123,6 +1416,8 @@ var ProxyRunGateway = class {
     this.pending.delete(reply.requestId);
     if (reply.result.ok) {
       pending.resolve(reply.result.data);
+    } else if (reply.result.error.code === UNSUPPORTED_RUN_REQUEST) {
+      pending.reject(new UnsupportedRunRequestError(reply.result.error.message));
     } else {
       pending.reject(new Error(reply.result.error.message));
     }
@@ -1158,20 +1453,59 @@ var ProxyRunGateway = class {
       tenant: this.tenant
     };
   }
-  getRunDetail(runId, options) {
-    return this.request({
+  /**
+  * 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.
+  */
+  async getRunDetail(runId, options) {
+    const detail = await this.request(options === void 0 ? {
+      kind: "getRunDetail",
+      runId
+    } : {
       kind: "getRunDetail",
       runId,
       options
     });
+    const over = options?.summarizeFansOver;
+    if (over === void 0 || !detail || detail.fans !== void 0) return detail;
+    const { timeline, fans } = (0, import_nestjs_durable_core9.summarizeTimeline)(detail.timeline, over);
+    const ids = (0, import_nestjs_durable_core9.childIdsOf)(detail.timeline);
+    return {
+      ...detail,
+      timeline,
+      children: ids.slice(0, import_nestjs_durable_core9.SUMMARY_CHILD_LIMIT),
+      fans,
+      childCount: ids.length
+    };
   }
-  getFanMembers(runId, group, query) {
-    return this.request({
-      kind: "getFanMembers",
-      runId,
-      group,
-      query
+  /** Paged from the full detail when the control plane is too old to page a fan itself. */
+  async getFanMembers(runId, group, query) {
+    if (!this.knownUnsupported("getFanMembers")) {
+      try {
+        const page = await this.request({
+          kind: "getFanMembers",
+          runId,
+          group,
+          query
+        });
+        if (page !== void 0) return page;
+      } catch (err) {
+        if (!isUnsupported(err)) throw err;
+      }
+      this.unsupportedUntil.set("getFanMembers", Date.now() + this.capabilityTtlMs);
+    }
+    const detail = await this.request({
+      kind: "getRunDetail",
+      runId
     });
+    return detail ? (0, import_nestjs_durable_core9.pageFan)(detail.timeline, group, query) : null;
+  }
+  knownUnsupported(kind) {
+    const until = this.unsupportedUntil.get(kind);
+    if (until === void 0) return false;
+    if (Date.now() < until) return true;
+    this.unsupportedUntil.delete(kind);
+    return false;
   }
   /** 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. */
@@ -1261,12 +1595,13 @@ ProxyRunGateway = _ts_decorate6([
   _ts_metadata6("design:paramtypes", [
     typeof Transport === "undefined" ? Object : Transport,
     String,
+    void 0,
     void 0
   ])
 ], ProxyRunGateway);
 
 // src/retention-poller.ts
-var import_nestjs_durable_core8 = require("@dudousxd/nestjs-durable-core");
+var import_nestjs_durable_core10 = require("@dudousxd/nestjs-durable-core");
 var import_common7 = require("@nestjs/common");
 
 // src/settle-within.ts
@@ -1332,10 +1667,10 @@ function validateRetention(retention) {
     if (policy.maxAge == null && policy.maxCount == null) {
       throw new Error("durable retention: each policy must set maxAge and/or maxCount");
     }
-    if (policy.maxAge != null) (0, import_nestjs_durable_core8.parseDuration)(policy.maxAge);
+    if (policy.maxAge != null) (0, import_nestjs_durable_core10.parseDuration)(policy.maxAge);
     for (const status of policy.statuses) {
-      if (!import_nestjs_durable_core8.TERMINAL_RUN_STATUSES.includes(status)) {
-        throw new Error(`durable retention: status "${status}" is not terminal; only ${import_nestjs_durable_core8.TERMINAL_RUN_STATUSES.join(", ")} can be pruned`);
+      if (!import_nestjs_durable_core10.TERMINAL_RUN_STATUSES.includes(status)) {
+        throw new Error(`durable retention: status "${status}" is not terminal; only ${import_nestjs_durable_core10.TERMINAL_RUN_STATUSES.join(", ")} can be pruned`);
       }
       const key = `${scopeKey}|${status}`;
       if (seen.has(key)) {
@@ -1387,7 +1722,7 @@ var RetentionPoller = class {
       return;
     }
     await this.sweep();
-    const intervalMs = retention.sweepInterval != null ? (0, import_nestjs_durable_core8.parseDuration)(retention.sweepInterval) : DEFAULT_SWEEP_INTERVAL_MS;
+    const intervalMs = retention.sweepInterval != null ? (0, import_nestjs_durable_core10.parseDuration)(retention.sweepInterval) : DEFAULT_SWEEP_INTERVAL_MS;
     if (intervalMs > 0) {
       this.timer = setInterval(() => void this.sweep(), intervalMs);
       this.timer.unref?.();
@@ -1449,8 +1784,8 @@ var RetentionPoller = class {
 };
 RetentionPoller = _ts_decorate7([
   (0, import_common7.Injectable)(),
-  _ts_param4(0, (0, import_common7.Inject)(import_nestjs_durable_core8.STATE_STORE_CANONICAL)),
-  _ts_param4(1, (0, import_common7.Inject)(import_nestjs_durable_core8.DURABLE_OPTIONS_CANONICAL)),
+  _ts_param4(0, (0, import_common7.Inject)(import_nestjs_durable_core10.STATE_STORE_CANONICAL)),
+  _ts_param4(1, (0, import_common7.Inject)(import_nestjs_durable_core10.DURABLE_OPTIONS_CANONICAL)),
   _ts_metadata7("design:type", Function),
   _ts_metadata7("design:paramtypes", [
     Object,
@@ -1458,170 +1793,8 @@ RetentionPoller = _ts_decorate7([
   ])
 ], RetentionPoller);
 
-// src/run-request-responder.ts
-var RunRequestResponder = class {
-  static {
-    __name(this, "RunRequestResponder");
-  }
-  transport;
-  gateway;
-  constructor(transport, gateway) {
-    this.transport = transport;
-    this.gateway = gateway;
-  }
-  /** Register the consumer on the transport. Each request is answered independently; a handler
-  *  failure never throws back into the transport (errors are captured into an error reply). */
-  start() {
-    this.transport.onRunRequest(async (msg) => {
-      const reply = await this.handle(msg);
-      await this.transport.publishRunReply(reply);
-    });
-  }
-  async handle(msg) {
-    const { body } = msg;
-    if (body.kind === "listRuns") {
-      const data = await this.gateway.listRuns({
-        ...body.query,
-        namespace: msg.tenant
-      });
-      return {
-        requestId: msg.requestId,
-        result: {
-          ok: true,
-          data
-        }
-      };
-    }
-    if (body.kind === "runFacets") {
-      const data = await this.gateway.runFacets({
-        ...body.query,
-        namespace: msg.tenant
-      });
-      return {
-        requestId: msg.requestId,
-        result: {
-          ok: true,
-          data
-        }
-      };
-    }
-    if (body.kind === "runValueFacets") {
-      const data = await this.gateway.runValueFacets(body.axis, {
-        ...body.query,
-        namespace: msg.tenant
-      }, body.opts);
-      return {
-        requestId: msg.requestId,
-        result: {
-          ok: true,
-          data
-        }
-      };
-    }
-    if (body.kind === "workerHealth") {
-      const all = await this.gateway.workerHealth();
-      const data = all.filter((h) => h.group.endsWith(`@${msg.tenant}`));
-      return {
-        requestId: msg.requestId,
-        result: {
-          ok: true,
-          data
-        }
-      };
-    }
-    if (body.kind === "waitingFor") {
-      const all = await this.gateway.waitingFor(body.runIds);
-      const owned = await Promise.all(Object.entries(all).map(async ([runId, waiting]) => {
-        const owner = this.gateway.getRun ? await this.gateway.getRun(runId) : (await this.gateway.getRunDetail(runId))?.run;
-        return owner && owner.namespace === msg.tenant ? [
-          runId,
-          waiting
-        ] : void 0;
-      }));
-      const data = {};
-      for (const entry of owned) {
-        if (entry) data[entry[0]] = entry[1];
-      }
-      return {
-        requestId: msg.requestId,
-        result: {
-          ok: true,
-          data
-        }
-      };
-    }
-    const detail = body.kind === "getRunDetail" || !this.gateway.getRun ? await this.gateway.getRunDetail(body.runId, body.kind === "getRunDetail" ? body.options : void 0) : void 0;
-    const run = detail !== void 0 ? detail?.run ?? null : await this.gateway.getRun?.(body.runId);
-    if (run && run.namespace !== msg.tenant) {
-      return {
-        requestId: msg.requestId,
-        result: {
-          ok: false,
-          error: {
-            message: "run belongs to another tenant",
-            code: "cross-tenant"
-          }
-        }
-      };
-    }
-    if (body.kind === "getRunDetail") {
-      return {
-        requestId: msg.requestId,
-        result: {
-          ok: true,
-          data: detail
-        }
-      };
-    }
-    if (body.kind === "getFanMembers") {
-      const data = run ? await this.gateway.getFanMembers?.(body.runId, body.group, body.query) ?? null : null;
-      return {
-        requestId: msg.requestId,
-        result: {
-          ok: true,
-          data
-        }
-      };
-    }
-    try {
-      const data = await this.callVerb(body);
-      return {
-        requestId: msg.requestId,
-        result: {
-          ok: true,
-          data
-        }
-      };
-    } catch (err) {
-      return {
-        requestId: msg.requestId,
-        result: {
-          ok: false,
-          error: {
-            message: err instanceof Error ? err.message : String(err)
-          }
-        }
-      };
-    }
-  }
-  callVerb(body) {
-    switch (body.kind) {
-      case "cancel":
-        return this.gateway.cancel(body.runId, body.opts);
-      case "retry":
-        return this.gateway.retry(body.runId);
-      case "continue":
-        return this.gateway.continue(body.runId);
-      case "retryWithInput":
-        return this.gateway.retryWithInput(body.runId, body.input);
-      case "redispatch":
-        return this.gateway.redispatchPending(body.runId);
-    }
-  }
-};
-
 // src/store-run-gateway.ts
-var import_nestjs_durable_core9 = require("@dudousxd/nestjs-durable-core");
+var import_nestjs_durable_core11 = require("@dudousxd/nestjs-durable-core");
 var import_common8 = require("@nestjs/common");
 function _ts_decorate8(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -1679,13 +1852,31 @@ var StoreRunGateway = class {
         children
       };
     }
+    if ((0, import_nestjs_durable_core11.aggregatesCheckpoints)(this.store)) {
+      const stats = await this.store.checkpointStats(runId);
+      const etag = (0, import_nestjs_durable_core11.runDetailEtag)(run, stats, over);
+      if ((0, import_nestjs_durable_core11.etagMatches)(options?.ifNoneMatch, etag)) {
+        return {
+          run,
+          timeline: [],
+          children: [],
+          notModified: true,
+          etag
+        };
+      }
+      return {
+        run,
+        ...await (0, import_nestjs_durable_core11.summarizeRunFromStore)(this.store, runId, over, stats),
+        etag
+      };
+    }
     const full = await this.store.listCheckpoints(runId);
-    const { timeline, fans } = (0, import_nestjs_durable_core9.summarizeTimeline)(full, over);
-    const ids = (0, import_nestjs_durable_core9.childIdsOf)(full);
+    const { timeline, fans } = (0, import_nestjs_durable_core11.summarizeTimeline)(full, over);
+    const ids = (0, import_nestjs_durable_core11.childIdsOf)(full);
     return {
       run,
       timeline,
-      children: ids.slice(0, import_nestjs_durable_core9.SUMMARY_CHILD_LIMIT),
+      children: ids.slice(0, import_nestjs_durable_core11.SUMMARY_CHILD_LIMIT),
       fans,
       childCount: ids.length
     };
@@ -1695,13 +1886,31 @@ var StoreRunGateway = class {
   }
   async getFanMembers(runId, group, query) {
     if (!await this.store.getRun(runId)) return null;
-    return (0, import_nestjs_durable_core9.pageFan)(await this.store.listCheckpoints(runId), group, query);
+    if ((0, import_nestjs_durable_core11.aggregatesCheckpoints)(this.store)) {
+      const stats = await this.store.checkpointStats(runId, {
+        group
+      });
+      const etag = (0, import_nestjs_durable_core11.fanPageEtag)(group, stats, query);
+      if ((0, import_nestjs_durable_core11.etagMatches)(query.ifNoneMatch, etag)) {
+        return {
+          items: [],
+          total: 0,
+          notModified: true,
+          etag
+        };
+      }
+      return {
+        ...await (0, import_nestjs_durable_core11.pageFanFromStore)(this.store, runId, group, query, stats),
+        etag
+      };
+    }
+    return (0, import_nestjs_durable_core11.pageFan)(await this.store.listCheckpoints(runId), group, query);
   }
   async listRuns(query) {
     const runs = await this.store.listRuns(query);
-    const waiterByRun = (0, import_nestjs_durable_core9.indexWaitersByRun)(await (0, import_nestjs_durable_core9.listSignalWaitersOfRuns)(this.store, runs.filter((run) => run.status === "suspended").map((run) => run.id)));
+    const waiterByRun = (0, import_nestjs_durable_core11.indexWaitersByRun)(await (0, import_nestjs_durable_core11.listSignalWaitersOfRuns)(this.store, runs.filter((run) => run.status === "suspended").map((run) => run.id)));
     return runs.map((run) => {
-      const waiting = (0, import_nestjs_durable_core9.resolveRunWaiting)(run, waiterByRun);
+      const waiting = (0, import_nestjs_durable_core11.resolveRunWaiting)(run, waiterByRun);
       return waiting ? {
         ...run,
         waiting
@@ -1717,7 +1926,7 @@ var StoreRunGateway = class {
   async runFacets(query) {
     if (this.store.runFacets) return this.store.runFacets(query);
     const runs = await this.store.listRuns(query);
-    return (0, import_nestjs_durable_core9.mergeRunFacetRows)(runs.map((r) => ({
+    return (0, import_nestjs_durable_core11.mergeRunFacetRows)(runs.map((r) => ({
       status: r.status,
       origin: r.origin,
       count: 1
@@ -1752,13 +1961,13 @@ var StoreRunGateway = class {
           "suspended"
         ]
       }),
-      (0, import_nestjs_durable_core9.listSignalWaitersOfRuns)(this.store, runIds)
+      (0, import_nestjs_durable_core11.listSignalWaitersOfRuns)(this.store, runIds)
     ]);
-    const waiterByRun = (0, import_nestjs_durable_core9.indexWaitersByRun)(waiters);
+    const waiterByRun = (0, import_nestjs_durable_core11.indexWaitersByRun)(waiters);
     const result = {};
     for (const run of suspended) {
       if (!idSet.has(run.id)) continue;
-      const waiting = (0, import_nestjs_durable_core9.resolveRunWaiting)(run, waiterByRun);
+      const waiting = (0, import_nestjs_durable_core11.resolveRunWaiting)(run, waiterByRun);
       if (waiting) result[run.id] = waiting;
     }
     return result;
@@ -1792,11 +2001,11 @@ var StoreRunGateway = class {
 };
 StoreRunGateway = _ts_decorate8([
   (0, import_common8.Injectable)(),
-  _ts_param5(0, (0, import_common8.Inject)(import_nestjs_durable_core9.STATE_STORE_CANONICAL)),
+  _ts_param5(0, (0, import_common8.Inject)(import_nestjs_durable_core11.STATE_STORE_CANONICAL)),
   _ts_metadata8("design:type", Function),
   _ts_metadata8("design:paramtypes", [
     typeof StateStore === "undefined" ? Object : StateStore,
-    typeof import_nestjs_durable_core9.WorkflowEngine === "undefined" ? Object : import_nestjs_durable_core9.WorkflowEngine
+    typeof import_nestjs_durable_core11.WorkflowEngine === "undefined" ? Object : import_nestjs_durable_core11.WorkflowEngine
   ])
 ], StoreRunGateway);
 
@@ -1842,7 +2051,7 @@ var TenantEventRepublisher = class {
 };
 
 // src/timer-poller.ts
-var import_nestjs_durable_core10 = require("@dudousxd/nestjs-durable-core");
+var import_nestjs_durable_core12 = require("@dudousxd/nestjs-durable-core");
 var import_common9 = require("@nestjs/common");
 function _ts_decorate9(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -1954,7 +2163,7 @@ var TimerPoller = class {
       await this.sweep("sweepTimeouts", () => this.engine.sweepTimeouts());
       const schedules = this.options.schedules;
       if (schedules && schedules.length > 0) {
-        await this.sweep("schedules", () => (0, import_nestjs_durable_core10.runSchedules)(this.engine, schedules, Date.now()));
+        await this.sweep("schedules", () => (0, import_nestjs_durable_core12.runSchedules)(this.engine, schedules, Date.now()));
       }
       if (this.options.persistedSchedules) {
         await this.sweep("persistedSchedules", () => this.engine.schedules.tick());
@@ -1972,21 +2181,21 @@ var TimerPoller = class {
 };
 TimerPoller = _ts_decorate9([
   (0, import_common9.Injectable)(),
-  _ts_param6(1, (0, import_common9.Inject)(import_nestjs_durable_core10.DURABLE_OPTIONS_CANONICAL)),
+  _ts_param6(1, (0, import_common9.Inject)(import_nestjs_durable_core12.DURABLE_OPTIONS_CANONICAL)),
   _ts_metadata9("design:type", Function),
   _ts_metadata9("design:paramtypes", [
-    typeof import_nestjs_durable_core10.WorkflowEngine === "undefined" ? Object : import_nestjs_durable_core10.WorkflowEngine,
+    typeof import_nestjs_durable_core12.WorkflowEngine === "undefined" ? Object : import_nestjs_durable_core12.WorkflowEngine,
     typeof DurableModuleOptions === "undefined" ? Object : DurableModuleOptions
   ])
 ], TimerPoller);
 
 // src/tokens.ts
-var import_nestjs_durable_core11 = require("@dudousxd/nestjs-durable-core");
+var import_nestjs_durable_core13 = require("@dudousxd/nestjs-durable-core");
 var CONTEXT_ACCESSOR = Symbol.for("@dudousxd/nestjs-context:accessor");
-var RUN_GATEWAY = import_nestjs_durable_core11.RunGateway;
+var RUN_GATEWAY = import_nestjs_durable_core13.RunGateway;
 
 // src/workflow.registrar.ts
-var import_nestjs_durable_core12 = require("@dudousxd/nestjs-durable-core");
+var import_nestjs_durable_core14 = require("@dudousxd/nestjs-durable-core");
 var import_common10 = require("@nestjs/common");
 var import_core4 = require("@nestjs/core");
 
@@ -2056,6 +2265,7 @@ function _ts_param7(paramIndex, decorator) {
   };
 }
 __name(_ts_param7, "_ts_param");
+var UNSERVED_ROUTES_RECHECK_MS = 3e4;
 var WorkflowRegistrar = class {
   static {
     __name(this, "WorkflowRegistrar");
@@ -2119,13 +2329,19 @@ var WorkflowRegistrar = class {
       const validateInput = meta.validateInput ?? (meta.inputSchema ? classValidatorInput(meta.inputSchema) : void 0);
       const eventBatch = meta.debounce ? {
         mode: "debounce",
-        windowMs: (0, import_nestjs_durable_core12.parseDuration)(meta.debounce)
+        windowMs: (0, import_nestjs_durable_core14.parseDuration)(meta.debounce)
       } : meta.batch ? {
         mode: "batch",
         maxSize: meta.batch.maxSize,
-        windowMs: (0, import_nestjs_durable_core12.parseDuration)(meta.batch.within)
+        windowMs: (0, import_nestjs_durable_core14.parseDuration)(meta.batch.within)
       } : void 0;
       const workflowCtor = workflow.constructor;
+      const onError = onErrorHandlersOf(meta, workflow, this.metadataScanner);
+      for (const [name, fn] of onError.handlers) {
+        this.engine.register(name, meta.version, fn, {
+          origin
+        });
+      }
       this.engine.register(meta.name, meta.version, (ctx, input) => workflow.run(ctx, input), {
         // Stamped onto every run this workflow starts (see `WorkflowRun.origin`). Derived from the
         // class's declaring file, so a lib gets attributed without opting in; `undefined` when it
@@ -2140,6 +2356,7 @@ var WorkflowRegistrar = class {
         searchAttributesSchema: meta.searchAttributes,
         onEvent: getOnEvents(meta, workflowCtor),
         eventBatch,
+        onError: onError.routes,
         // Uniform dispatch (opt-in): when an in-app worker is configured, register the body GROUP-SERVED
         // so the engine dispatches its turns over the transport instead of running it inline; the
         // co-located worker consumer (Task 5: one queue PER REGISTERED NAME) replays the same body.
@@ -2150,11 +2367,11 @@ var WorkflowRegistrar = class {
         // so a turn dispatched under the wrong token would never be consumed. Absent → the inline fast
         // path (unchanged).
         ...this.inAppWorker ? {
-          group: (0, import_nestjs_durable_core12.tenantGroup)((0, import_nestjs_durable_core12.sanitizeQueueToken)(meta.name), this.inAppWorker.partition),
-          executor: new import_nestjs_durable_core12.RemoteWorkflowExecutor(this.inAppWorker.transport, meta.name, this.inAppWorker.partition)
+          group: (0, import_nestjs_durable_core14.tenantGroup)((0, import_nestjs_durable_core14.sanitizeQueueToken)(meta.name), this.inAppWorker.partition),
+          executor: new import_nestjs_durable_core14.RemoteWorkflowExecutor(this.inAppWorker.transport, meta.name, this.inAppWorker.partition)
         } : {}
       });
-      (0, import_nestjs_durable_core12.bindWorkflowClass)(workflowCtor, {
+      (0, import_nestjs_durable_core14.bindWorkflowClass)(workflowCtor, {
         start: /* @__PURE__ */ __name((name, input, runId, opts) => this.engine.start(name, input, runId, opts), "start"),
         waitForRun: /* @__PURE__ */ __name((runId, opts) => this.engine.waitForRun(runId, opts), "waitForRun")
       });
@@ -2169,10 +2386,11 @@ var WorkflowRegistrar = class {
         });
         deadLetterByWorkflow.set(meta.name, dlqName);
       } else if (meta.deadLetterWorkflow) {
-        deadLetterByWorkflow.set(meta.name, (0, import_nestjs_durable_core12.workflowName)(meta.deadLetterWorkflow));
+        deadLetterByWorkflow.set(meta.name, (0, import_nestjs_durable_core14.workflowName)(meta.deadLetterWorkflow));
       }
     });
     this.reportUnattributed(unattributed);
+    void this.reportUnservedOnErrorRoutes();
     this.installDeadLetterRouting(deadLetterByWorkflow);
   }
   /**
@@ -2185,6 +2403,20 @@ var WorkflowRegistrar = class {
     if (names.length === 0) return;
     console.warn(`[nestjs-durable] could not derive an origin (declaring package) for ${names.length} workflow(s): ${names.join(", ")}. Their runs carry no origin and will not match an origin filter.`);
   }
+  /**
+  * Says, once after boot, which onError routes name a handler workflow nothing can run, so a typo is
+  * caught before the first failure goes nowhere. Routes unserved at boot are checked again after
+  * {@link UNSERVED_ROUTES_RECHECK_MS}, so a handler whose workers start after this process is not
+  * reported.
+  */
+  async reportUnservedOnErrorRoutes(recheckMs = UNSERVED_ROUTES_RECHECK_MS) {
+    if ((await this.engine.unservedOnErrorRoutes().catch(() => [])).length === 0) return;
+    await new Promise((resolve) => setTimeout(resolve, recheckMs).unref());
+    const unserved = await this.engine.unservedOnErrorRoutes().catch(() => []);
+    if (unserved.length === 0) return;
+    const list = unserved.map(({ workflow, route }) => `${workflow} \u2192 ${route.workflow} (code ${route.code ?? "*"})`).join(", ");
+    console.warn(`[nestjs-durable] ${unserved.length} onError route(s) name a handler workflow that is not registered here and has no live worker: ${list}.`);
+  }
   /** Returns the instance's `@DeadLetter()` method bound to the instance, or undefined if none. */
   findDeadLetterHandler(instance) {
     const prototype = Object.getPrototypeOf(instance);
@@ -2202,7 +2434,7 @@ var WorkflowRegistrar = class {
   * a `dlq:<runId>` id, so re-recovery never double-dispatches.
   */
   installDeadLetterRouting(byWorkflow) {
-    const fallback = this.options.deadLetterWorkflow ? (0, import_nestjs_durable_core12.workflowName)(this.options.deadLetterWorkflow) : void 0;
+    const fallback = this.options.deadLetterWorkflow ? (0, import_nestjs_durable_core14.workflowName)(this.options.deadLetterWorkflow) : void 0;
     if (byWorkflow.size === 0 && !fallback) return;
     this.engine.onDead((run) => {
       const target = byWorkflow.get(run.workflow) ?? fallback;
@@ -2227,14 +2459,14 @@ var WorkflowRegistrar = class {
 };
 WorkflowRegistrar = _ts_decorate10([
   (0, import_common10.Injectable)(),
-  _ts_param7(3, (0, import_common10.Inject)(import_nestjs_durable_core12.STATE_STORE_CANONICAL)),
-  _ts_param7(4, (0, import_common10.Inject)(import_nestjs_durable_core12.DURABLE_OPTIONS_CANONICAL)),
+  _ts_param7(3, (0, import_common10.Inject)(import_nestjs_durable_core14.STATE_STORE_CANONICAL)),
+  _ts_param7(4, (0, import_common10.Inject)(import_nestjs_durable_core14.DURABLE_OPTIONS_CANONICAL)),
   _ts_param7(5, (0, import_common10.Inject)(IN_APP_WORKER_BINDING)),
   _ts_metadata10("design:type", Function),
   _ts_metadata10("design:paramtypes", [
     typeof import_core4.DiscoveryService === "undefined" ? Object : import_core4.DiscoveryService,
     typeof import_core4.MetadataScanner === "undefined" ? Object : import_core4.MetadataScanner,
-    typeof import_nestjs_durable_core12.WorkflowEngine === "undefined" ? Object : import_nestjs_durable_core12.WorkflowEngine,
+    typeof import_nestjs_durable_core14.WorkflowEngine === "undefined" ? Object : import_nestjs_durable_core14.WorkflowEngine,
     Object,
     typeof DurableModuleOptions === "undefined" ? Object : DurableModuleOptions,
     Object
@@ -2243,7 +2475,7 @@ WorkflowRegistrar = _ts_decorate10([
 
 // src/workflow.service.ts
 var import_node_crypto = require("crypto");
-var import_nestjs_durable_core13 = require("@dudousxd/nestjs-durable-core");
+var import_nestjs_durable_core15 = require("@dudousxd/nestjs-durable-core");
 var import_common11 = require("@nestjs/common");
 function _ts_decorate11(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -2312,7 +2544,7 @@ WorkflowService = _ts_decorate11([
   (0, import_common11.Injectable)(),
   _ts_metadata11("design:type", Function),
   _ts_metadata11("design:paramtypes", [
-    typeof import_nestjs_durable_core13.WorkflowEngine === "undefined" ? Object : import_nestjs_durable_core13.WorkflowEngine
+    typeof import_nestjs_durable_core15.WorkflowEngine === "undefined" ? Object : import_nestjs_durable_core15.WorkflowEngine
   ])
 ], WorkflowService);
 
@@ -2515,14 +2747,14 @@ var RunGatewayBootstrap = class RunGatewayBootstrap2 {
 };
 RunGatewayBootstrap = _ts_decorate12([
   (0, import_common12.Injectable)(),
-  _ts_param8(1, (0, import_common12.Inject)(import_nestjs_durable_core14.TRANSPORT_CANONICAL)),
-  _ts_param8(3, (0, import_common12.Inject)(import_nestjs_durable_core14.STATE_STORE_CANONICAL)),
-  _ts_param8(4, (0, import_common12.Inject)(import_nestjs_durable_core14.DURABLE_OPTIONS_CANONICAL)),
+  _ts_param8(1, (0, import_common12.Inject)(import_nestjs_durable_core16.TRANSPORT_CANONICAL)),
+  _ts_param8(3, (0, import_common12.Inject)(import_nestjs_durable_core16.STATE_STORE_CANONICAL)),
+  _ts_param8(4, (0, import_common12.Inject)(import_nestjs_durable_core16.DURABLE_OPTIONS_CANONICAL)),
   _ts_metadata12("design:type", Function),
   _ts_metadata12("design:paramtypes", [
-    typeof import_nestjs_durable_core14.WorkflowEngine === "undefined" ? Object : import_nestjs_durable_core14.WorkflowEngine,
+    typeof import_nestjs_durable_core16.WorkflowEngine === "undefined" ? Object : import_nestjs_durable_core16.WorkflowEngine,
     Object,
-    typeof import_nestjs_durable_core14.RunGateway === "undefined" ? Object : import_nestjs_durable_core14.RunGateway,
+    typeof import_nestjs_durable_core16.RunGateway === "undefined" ? Object : import_nestjs_durable_core16.RunGateway,
     Object,
     typeof DurableModuleOptions === "undefined" ? Object : DurableModuleOptions
   ])
@@ -2534,13 +2766,13 @@ var DurableModule = class _DurableModule {
   static forRoot(options) {
     _DurableModule.assertValid(options);
     return _DurableModule.build({
-      provide: import_nestjs_durable_core14.DURABLE_OPTIONS_CANONICAL,
+      provide: import_nestjs_durable_core16.DURABLE_OPTIONS_CANONICAL,
       useValue: resolveTopology(options)
     });
   }
   static forRootAsync(options) {
     return _DurableModule.build({
-      provide: import_nestjs_durable_core14.DURABLE_OPTIONS_CANONICAL,
+      provide: import_nestjs_durable_core16.DURABLE_OPTIONS_CANONICAL,
       useFactory: /* @__PURE__ */ __name(async (...args) => {
         const resolved = await options.useFactory(...args);
         _DurableModule.assertValid(resolved);
@@ -2573,41 +2805,41 @@ var DurableModule = class _DurableModule {
       providers: [
         optionsProvider,
         {
-          provide: import_nestjs_durable_core14.STATE_STORE_CANONICAL,
+          provide: import_nestjs_durable_core16.STATE_STORE_CANONICAL,
           useFactory: /* @__PURE__ */ __name((options) => options.store !== void 0 ? scopedStore(options.store, options) : null, "useFactory"),
           inject: [
-            import_nestjs_durable_core14.DURABLE_OPTIONS_CANONICAL
+            import_nestjs_durable_core16.DURABLE_OPTIONS_CANONICAL
           ]
         },
         {
-          provide: import_nestjs_durable_core14.TRANSPORT_CANONICAL,
+          provide: import_nestjs_durable_core16.TRANSPORT_CANONICAL,
           // With a POOL (`transports`) and no singular `transport`, the canonical transport is the
           // pool's PRIMARY — the same one the engine dispatches on first. Leaving it null starved
           // the step registrar / in-app worker of a transport, so a pool-configured operator
           // registered NO step handlers and its own steps parked in `wait` with no consumer.
           useFactory: /* @__PURE__ */ __name((options) => options.transport ?? options.transports?.[0]?.transport ?? null, "useFactory"),
           inject: [
-            import_nestjs_durable_core14.DURABLE_OPTIONS_CANONICAL
+            import_nestjs_durable_core16.DURABLE_OPTIONS_CANONICAL
           ]
         },
         // Legacy back-compat aliases (deprecated tokens still resolve to the same instances):
         {
-          provide: import_nestjs_durable_core14.STATE_STORE,
-          useExisting: import_nestjs_durable_core14.STATE_STORE_CANONICAL
+          provide: import_nestjs_durable_core16.STATE_STORE,
+          useExisting: import_nestjs_durable_core16.STATE_STORE_CANONICAL
         },
         {
-          provide: import_nestjs_durable_core14.TRANSPORT,
-          useExisting: import_nestjs_durable_core14.TRANSPORT_CANONICAL
+          provide: import_nestjs_durable_core16.TRANSPORT,
+          useExisting: import_nestjs_durable_core16.TRANSPORT_CANONICAL
         },
         {
-          provide: import_nestjs_durable_core14.DURABLE_OPTIONS,
-          useExisting: import_nestjs_durable_core14.DURABLE_OPTIONS_CANONICAL
+          provide: import_nestjs_durable_core16.DURABLE_OPTIONS,
+          useExisting: import_nestjs_durable_core16.DURABLE_OPTIONS_CANONICAL
         },
         {
           // Shared token, bound EXACTLY once: a real engine for the operator role, or a store-less
           // `DurableStartClient` facade for a thin worker (no `store`) — either way, `WorkflowService`
           // and app code call `engine.start(...)` unchanged.
-          provide: import_nestjs_durable_core14.WorkflowEngine,
+          provide: import_nestjs_durable_core16.WorkflowEngine,
           useFactory: /* @__PURE__ */ __name(async (options, store, transport, moduleRef) => {
             if (options.store === void 0) {
               return new DurableStartClient(options);
@@ -2620,7 +2852,7 @@ var DurableModule = class _DurableModule {
             const context = options.context ?? (accessor ? () => carrierFromAccessor(accessor) : void 0);
             const runtime = accessor ? await resolveContextRuntime() : void 0;
             const rehydrate = runtime && ((carrier, fn) => carrier && Object.keys(carrier).length > 0 ? runtime.deserialize(carrier, fn) : fn());
-            const engine = new import_nestjs_durable_core14.WorkflowEngine({
+            const engine = new import_nestjs_durable_core16.WorkflowEngine({
               store,
               transport: transport ?? void 0,
               transports: options.transports,
@@ -2658,9 +2890,9 @@ var DurableModule = class _DurableModule {
             return engine;
           }, "useFactory"),
           inject: [
-            import_nestjs_durable_core14.DURABLE_OPTIONS_CANONICAL,
-            import_nestjs_durable_core14.STATE_STORE_CANONICAL,
-            import_nestjs_durable_core14.TRANSPORT_CANONICAL,
+            import_nestjs_durable_core16.DURABLE_OPTIONS_CANONICAL,
+            import_nestjs_durable_core16.STATE_STORE_CANONICAL,
+            import_nestjs_durable_core16.TRANSPORT_CANONICAL,
             import_core5.ModuleRef
           ]
         },
@@ -2674,7 +2906,7 @@ var DurableModule = class _DurableModule {
         // or (for a thin worker, no `store`) a `ProxyRunGateway` over `transport` when given, else a
         // gateway whose every method rejects with a clear tenant error.
         {
-          provide: import_nestjs_durable_core14.RunGateway,
+          provide: import_nestjs_durable_core16.RunGateway,
           useFactory: /* @__PURE__ */ __name((options, store, engine) => {
             if (options.store !== void 0) {
               if (!store) {
@@ -2685,9 +2917,9 @@ var DurableModule = class _DurableModule {
             return options.transport ? new ProxyRunGateway(options.transport, options.partition ?? "default", options.runGatewayTimeoutMs) : unavailableRunGateway();
           }, "useFactory"),
           inject: [
-            import_nestjs_durable_core14.DURABLE_OPTIONS_CANONICAL,
-            import_nestjs_durable_core14.STATE_STORE_CANONICAL,
-            import_nestjs_durable_core14.WorkflowEngine
+            import_nestjs_durable_core16.DURABLE_OPTIONS_CANONICAL,
+            import_nestjs_durable_core16.STATE_STORE_CANONICAL,
+            import_nestjs_durable_core16.WorkflowEngine
           ]
         },
         RunGatewayBootstrap,
@@ -2701,13 +2933,13 @@ var DurableModule = class _DurableModule {
       exports: [
         WorkflowService,
         EntityService,
-        import_nestjs_durable_core14.WorkflowEngine,
-        import_nestjs_durable_core14.STATE_STORE,
-        import_nestjs_durable_core14.STATE_STORE_CANONICAL,
-        import_nestjs_durable_core14.TRANSPORT,
-        import_nestjs_durable_core14.TRANSPORT_CANONICAL,
-        import_nestjs_durable_core14.DURABLE_OPTIONS_CANONICAL,
-        import_nestjs_durable_core14.RunGateway
+        import_nestjs_durable_core16.WorkflowEngine,
+        import_nestjs_durable_core16.STATE_STORE,
+        import_nestjs_durable_core16.STATE_STORE_CANONICAL,
+        import_nestjs_durable_core16.TRANSPORT,
+        import_nestjs_durable_core16.TRANSPORT_CANONICAL,
+        import_nestjs_durable_core16.DURABLE_OPTIONS_CANONICAL,
+        import_nestjs_durable_core16.RunGateway
       ]
     };
   }
@@ -2717,7 +2949,7 @@ DurableModule = _ts_decorate12([
 ], DurableModule);
 
 // src/index.ts
-var import_nestjs_durable_core15 = require("@dudousxd/nestjs-durable-core");
+var import_nestjs_durable_core17 = require("@dudousxd/nestjs-durable-core");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CONTEXT_ACCESSOR,
@@ -2738,9 +2970,11 @@ var import_nestjs_durable_core15 = require("@dudousxd/nestjs-durable-core");
   IN_APP_WORKER_RUNNERS,
   IN_APP_WORKER_RUNTIME,
   InAppWorkerBootstrap,
+  ON_ERROR_METADATA,
   ON_EVENT_METADATA,
   On,
   OnDurableEvent,
+  OnError,
   OnEvent,
   ProxyRunGateway,
   RUN_GATEWAY,
@@ -2755,6 +2989,7 @@ var import_nestjs_durable_core15 = require("@dudousxd/nestjs-durable-core");
   ThinStepRegistrar,
   ThinWorkerBootstrap,
   ThinWorkflowRegistrar,
+  UNSUPPORTED_RUN_REQUEST,
   WORKFLOW_METADATA,
   Workflow,
   WorkflowEngine,
@@ -2770,6 +3005,7 @@ var import_nestjs_durable_core15 = require("@dudousxd/nestjs-durable-core");
   isDrivingOperator,
   isOperatorRole,
   isStepInterceptor,
+  onErrorCodesOf,
   readSearchAttributes,
   thinWorkerProviders,
   unavailableRunGateway