@dudousxd/nestjs-durable 0.47.1 → 0.48.1

package/dist/index.js

@@ -125,6 +125,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,
@@ -202,6 +203,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) => {
@@ -404,6 +425,66 @@ function scanSteps(discovery, scanner, register) {
 }
 __name(scanSteps, "scanSteps");
 
+// src/on-error-handlers.ts
+import { workflowName as workflowName2 } from "@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: workflowName2(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;
@@ -443,34 +524,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([
   Injectable2(),
-  _ts_param(1, Inject(DURABLE_WORKER_RUNTIME)),
-  _ts_param(2, Inject(DURABLE_OPTIONS_CANONICAL)),
+  _ts_param(2, Inject(DURABLE_WORKER_RUNTIME)),
+  _ts_param(3, Inject(DURABLE_OPTIONS_CANONICAL)),
   _ts_metadata2("design:type", Function),
   _ts_metadata2("design:paramtypes", [
     typeof DiscoveryService === "undefined" ? Object : DiscoveryService,
+    typeof MetadataScanner === "undefined" ? Object : MetadataScanner,
     Object,
     typeof DurableModuleOptions === "undefined" ? Object : DurableModuleOptions
   ])
@@ -526,6 +602,7 @@ var ThinWorkerBootstrap = class {
     const options = this.options;
     const runtime = this.runtime;
     if (runtime === null || !isPureThinWorker(options) || options.connection === void 0) return;
+    if (options.consumers === false) return;
     const handle = await this.runRedisWorker({
       runtime,
       connection: options.connection,
@@ -897,21 +974,14 @@ 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() {
     const options = this.options;
     const runtime = this.runtime;
     if (runtime === null || !isCoLocatedWorker(options) || options.connection === void 0) return;
+    if (options.consumers === false) return;
     const handle = await this.runRedisWorker({
       runtime,
       connection: options.connection,
@@ -995,7 +1065,212 @@ function inAppWorkerProviders() {
 __name(inAppWorkerProviders, "inAppWorkerProviders");
 
 // src/proxy-run-gateway.ts
+import { SUMMARY_CHILD_LIMIT, childIdsOf, pageFan, summarizeTimeline } from "@dudousxd/nestjs-durable-core";
 import { Injectable as Injectable6 } from "@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") {
@@ -1016,6 +1291,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");
@@ -1023,11 +1307,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) {
@@ -1037,6 +1328,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));
     }
@@ -1072,20 +1365,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 } = summarizeTimeline(detail.timeline, over);
+    const ids = childIdsOf(detail.timeline);
+    return {
+      ...detail,
+      timeline,
+      children: ids.slice(0, 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 ? 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. */
@@ -1175,6 +1507,7 @@ ProxyRunGateway = _ts_decorate6([
   _ts_metadata6("design:paramtypes", [
     typeof Transport === "undefined" ? Object : Transport,
     String,
+    void 0,
     void 0
   ])
 ], ProxyRunGateway);
@@ -1372,170 +1705,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
-import { STATE_STORE_CANONICAL as STATE_STORE_CANONICAL2, SUMMARY_CHILD_LIMIT, WorkflowEngine as WorkflowEngine2, childIdsOf, indexWaitersByRun, listSignalWaitersOfRuns, mergeRunFacetRows, pageFan, resolveRunWaiting, summarizeTimeline } from "@dudousxd/nestjs-durable-core";
+import { STATE_STORE_CANONICAL as STATE_STORE_CANONICAL2, SUMMARY_CHILD_LIMIT as SUMMARY_CHILD_LIMIT2, WorkflowEngine as WorkflowEngine2, aggregatesCheckpoints, childIdsOf as childIdsOf2, etagMatches, fanPageEtag, indexWaitersByRun, listSignalWaitersOfRuns, mergeRunFacetRows, pageFan as pageFan2, pageFanFromStore, resolveRunWaiting, runDetailEtag, summarizeRunFromStore, summarizeTimeline as summarizeTimeline2 } from "@dudousxd/nestjs-durable-core";
 import { Inject as Inject5, Injectable as Injectable8 } from "@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;
@@ -1593,13 +1764,31 @@ var StoreRunGateway = class {
         children
       };
     }
+    if (aggregatesCheckpoints(this.store)) {
+      const stats = await this.store.checkpointStats(runId);
+      const etag = runDetailEtag(run, stats, over);
+      if (etagMatches(options?.ifNoneMatch, etag)) {
+        return {
+          run,
+          timeline: [],
+          children: [],
+          notModified: true,
+          etag
+        };
+      }
+      return {
+        run,
+        ...await summarizeRunFromStore(this.store, runId, over, stats),
+        etag
+      };
+    }
     const full = await this.store.listCheckpoints(runId);
-    const { timeline, fans } = summarizeTimeline(full, over);
-    const ids = childIdsOf(full);
+    const { timeline, fans } = summarizeTimeline2(full, over);
+    const ids = childIdsOf2(full);
     return {
       run,
       timeline,
-      children: ids.slice(0, SUMMARY_CHILD_LIMIT),
+      children: ids.slice(0, SUMMARY_CHILD_LIMIT2),
       fans,
       childCount: ids.length
     };
@@ -1609,7 +1798,25 @@ var StoreRunGateway = class {
   }
   async getFanMembers(runId, group, query) {
     if (!await this.store.getRun(runId)) return null;
-    return pageFan(await this.store.listCheckpoints(runId), group, query);
+    if (aggregatesCheckpoints(this.store)) {
+      const stats = await this.store.checkpointStats(runId, {
+        group
+      });
+      const etag = fanPageEtag(group, stats, query);
+      if (etagMatches(query.ifNoneMatch, etag)) {
+        return {
+          items: [],
+          total: 0,
+          notModified: true,
+          etag
+        };
+      }
+      return {
+        ...await pageFanFromStore(this.store, runId, group, query, stats),
+        etag
+      };
+    }
+    return pageFan2(await this.store.listCheckpoints(runId), group, query);
   }
   async listRuns(query) {
     const runs = await this.store.listRuns(query);
@@ -1900,7 +2107,7 @@ var CONTEXT_ACCESSOR = Symbol.for("@dudousxd/nestjs-context:accessor");
 var RUN_GATEWAY = RunGateway;
 
 // src/workflow.registrar.ts
-import { DURABLE_OPTIONS_CANONICAL as DURABLE_OPTIONS_CANONICAL6, RemoteWorkflowExecutor, STATE_STORE_CANONICAL as STATE_STORE_CANONICAL3, WorkflowEngine as WorkflowEngine4, bindWorkflowClass, parseDuration as parseDuration2, sanitizeQueueToken, tenantGroup, workflowName as workflowName2 } from "@dudousxd/nestjs-durable-core";
+import { DURABLE_OPTIONS_CANONICAL as DURABLE_OPTIONS_CANONICAL6, RemoteWorkflowExecutor, STATE_STORE_CANONICAL as STATE_STORE_CANONICAL3, WorkflowEngine as WorkflowEngine4, bindWorkflowClass, parseDuration as parseDuration2, sanitizeQueueToken, tenantGroup, workflowName as workflowName3 } from "@dudousxd/nestjs-durable-core";
 import { Inject as Inject7, Injectable as Injectable10 } from "@nestjs/common";
 import { DiscoveryService as DiscoveryService4, MetadataScanner as MetadataScanner4 } from "@nestjs/core";
 
@@ -1970,6 +2177,7 @@ function _ts_param7(paramIndex, decorator) {
   };
 }
 __name(_ts_param7, "_ts_param");
+var UNSERVED_ROUTES_RECHECK_MS = 3e4;
 var WorkflowRegistrar = class {
   static {
     __name(this, "WorkflowRegistrar");
@@ -2040,6 +2248,12 @@ var WorkflowRegistrar = class {
         windowMs: parseDuration2(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
@@ -2054,6 +2268,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.
@@ -2083,10 +2298,11 @@ var WorkflowRegistrar = class {
         });
         deadLetterByWorkflow.set(meta.name, dlqName);
       } else if (meta.deadLetterWorkflow) {
-        deadLetterByWorkflow.set(meta.name, workflowName2(meta.deadLetterWorkflow));
+        deadLetterByWorkflow.set(meta.name, workflowName3(meta.deadLetterWorkflow));
       }
     });
     this.reportUnattributed(unattributed);
+    void this.reportUnservedOnErrorRoutes();
     this.installDeadLetterRouting(deadLetterByWorkflow);
   }
   /**
@@ -2099,6 +2315,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);
@@ -2116,7 +2346,7 @@ var WorkflowRegistrar = class {
   * a `dlq:<runId>` id, so re-recovery never double-dispatches.
   */
   installDeadLetterRouting(byWorkflow) {
-    const fallback = this.options.deadLetterWorkflow ? workflowName2(this.options.deadLetterWorkflow) : void 0;
+    const fallback = this.options.deadLetterWorkflow ? workflowName3(this.options.deadLetterWorkflow) : void 0;
     if (byWorkflow.size === 0 && !fallback) return;
     this.engine.onDead((run) => {
       const target = byWorkflow.get(run.workflow) ?? fallback;
@@ -2308,6 +2538,15 @@ function scopedStore(store, options) {
   });
 }
 __name(scopedStore, "scopedStore");
+function deferTransportConsumers(transport) {
+  const deferrable = transport;
+  if (typeof deferrable.deferConsumers === "function") {
+    deferrable.deferConsumers();
+    return;
+  }
+  console.warn(`[nestjs-durable] consumers: false \u2014 ${transport.constructor?.name ?? "this transport"} cannot defer its consumers and will keep consuming in this process`);
+}
+__name(deferTransportConsumers, "deferTransportConsumers");
 function assertValidRole(options) {
   const hasStore = options.store !== void 0;
   const hasConnection = options.connection !== void 0;
@@ -2534,6 +2773,14 @@ 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());
+            if (options.consumers === false) {
+              for (const t of [
+                transport,
+                ...(options.transports ?? []).map((n) => n.transport)
+              ]) {
+                if (t) deferTransportConsumers(t);
+              }
+            }
             const engine = new WorkflowEngine6({
               store,
               transport: transport ?? void 0,
@@ -2651,9 +2898,11 @@ export {
   IN_APP_WORKER_RUNNERS,
   IN_APP_WORKER_RUNTIME,
   InAppWorkerBootstrap,
+  ON_ERROR_METADATA,
   ON_EVENT_METADATA,
   On,
   OnDurableEvent,
+  OnError,
   OnEvent,
   ProxyRunGateway,
   RUN_GATEWAY,
@@ -2668,6 +2917,7 @@ export {
   ThinStepRegistrar,
   ThinWorkerBootstrap,
   ThinWorkflowRegistrar,
+  UNSUPPORTED_RUN_REQUEST,
   WORKFLOW_METADATA,
   Workflow,
   WorkflowEngine7 as WorkflowEngine,
@@ -2683,6 +2933,7 @@ export {
   isDrivingOperator,
   isOperatorRole,
   isStepInterceptor,
+  onErrorCodesOf,
   readSearchAttributes2 as readSearchAttributes,
   thinWorkerProviders,
   unavailableRunGateway