@horizon-republic/nestjs-jetstream 2.5.1 → 2.7.0

package/dist/index.cjs

@@ -42,9 +42,14 @@ __export(index_exports, {
   JetstreamRecordBuilder: () => JetstreamRecordBuilder,
   JetstreamStrategy: () => JetstreamStrategy,
   JsonCodec: () => JsonCodec,
+  MessageKind: () => MessageKind,
+  PatternPrefix: () => PatternPrefix,
   RpcContext: () => RpcContext,
+  StreamKind: () => StreamKind,
   TransportEvent: () => TransportEvent,
   getClientToken: () => getClientToken,
+  isCoreRpcMode: () => isCoreRpcMode,
+  isJetStreamRpcMode: () => isJetStreamRpcMode,
   toNanos: () => toNanos
 });
 module.exports = __toCommonJS(index_exports);
@@ -58,6 +63,11 @@ var import_microservices = require("@nestjs/microservices");
 var import_nats2 = require("nats");
 
 // src/interfaces/hooks.interface.ts
+var MessageKind = /* @__PURE__ */ ((MessageKind2) => {
+  MessageKind2["Event"] = "event";
+  MessageKind2["Rpc"] = "rpc";
+  return MessageKind2;
+})(MessageKind || {});
 var TransportEvent = /* @__PURE__ */ ((TransportEvent2) => {
   TransportEvent2["Connect"] = "connect";
   TransportEvent2["Disconnect"] = "disconnect";
@@ -71,6 +81,15 @@ var TransportEvent = /* @__PURE__ */ ((TransportEvent2) => {
   return TransportEvent2;
 })(TransportEvent || {});
 
+// src/interfaces/stream.interface.ts
+var StreamKind = /* @__PURE__ */ ((StreamKind2) => {
+  StreamKind2["Event"] = "ev";
+  StreamKind2["Command"] = "cmd";
+  StreamKind2["Broadcast"] = "broadcast";
+  StreamKind2["Ordered"] = "ordered";
+  return StreamKind2;
+})(StreamKind || {});
+
 // src/jetstream.constants.ts
 var import_nats = require("nats");
 var JETSTREAM_OPTIONS = /* @__PURE__ */ Symbol("JETSTREAM_OPTIONS");
@@ -95,7 +114,7 @@ var baseStreamConfig = {
   num_replicas: 1,
   discard: import_nats.DiscardPolicy.Old,
   allow_direct: true,
-  compression: import_nats.StoreCompression.None
+  compression: import_nats.StoreCompression.S2
 };
 var DEFAULT_EVENT_STREAM_CONFIG = {
   ...baseStreamConfig,
@@ -187,13 +206,20 @@ var internalName = (name) => `${name}__microservice`;
 var buildSubject = (serviceName, kind, pattern) => `${internalName(serviceName)}.${kind}.${pattern}`;
 var buildBroadcastSubject = (pattern) => `broadcast.${pattern}`;
 var streamName = (serviceName, kind) => {
-  if (kind === "broadcast") return "broadcast-stream";
+  if (kind === "broadcast" /* Broadcast */) return "broadcast-stream";
   return `${internalName(serviceName)}_${kind}-stream`;
 };
 var consumerName = (serviceName, kind) => {
-  if (kind === "broadcast") return `${internalName(serviceName)}_broadcast-consumer`;
+  if (kind === "broadcast" /* Broadcast */) return `${internalName(serviceName)}_broadcast-consumer`;
   return `${internalName(serviceName)}_${kind}-consumer`;
 };
+var PatternPrefix = /* @__PURE__ */ ((PatternPrefix2) => {
+  PatternPrefix2["Broadcast"] = "broadcast:";
+  PatternPrefix2["Ordered"] = "ordered:";
+  return PatternPrefix2;
+})(PatternPrefix || {});
+var isJetStreamRpcMode = (rpc) => rpc?.mode === "jetstream";
+var isCoreRpcMode = (rpc) => !rpc || rpc.mode === "core";
 
 // src/client/jetstream.record.ts
 var JetstreamRecord = class {
@@ -308,10 +334,13 @@ var JetstreamClient = class extends import_microservices.ClientProxy {
     this.codec = codec;
     this.eventBus = eventBus;
     this.targetName = targetServiceName;
+    this.callerName = internalName(this.rootOptions.name);
   }
   logger = new import_common.Logger("Jetstream:Client");
   /** Target service name this client sends messages to. */
   targetName;
+  /** Pre-cached caller name derived from rootOptions.name, computed once in constructor. */
+  callerName;
   /** Shared inbox for JetStream-mode RPC responses. */
   inbox = null;
   inboxSubscription = null;
@@ -331,7 +360,7 @@ var JetstreamClient = class extends import_microservices.ClientProxy {
    */
   async connect() {
     const nc = await this.connection.getConnection();
-    if (this.isJetStreamRpcMode() && !this.inboxSubscription) {
+    if (isJetStreamRpcMode(this.rootOptions.rpc) && !this.inboxSubscription) {
       this.setupInbox(nc);
     }
     this.statusSubscription ??= this.connection.status$.subscribe((status) => {
@@ -366,11 +395,11 @@ var JetstreamClient = class extends import_microservices.ClientProxy {
    * depending on the subject prefix.
    */
   async dispatchEvent(packet) {
-    const nc = await this.connect();
+    await this.connect();
     const { data, hdrs, messageId } = this.extractRecordData(packet.data);
     const subject = this.buildEventSubject(packet.pattern);
     const msgHeaders = this.buildHeaders(hdrs, { subject });
-    const ack = await nc.jetstream().publish(subject, this.codec.encode(data), {
+    const ack = await this.connection.getJetStreamClient().publish(subject, this.codec.encode(data), {
       headers: msgHeaders,
       msgID: messageId ?? crypto.randomUUID()
     });
@@ -386,26 +415,23 @@ var JetstreamClient = class extends import_microservices.ClientProxy {
    * JetStream mode: publishes to stream + waits for inbox response.
    */
   publish(packet, callback) {
-    const subject = buildSubject(this.targetName, "cmd", packet.pattern);
+    const subject = buildSubject(this.targetName, "cmd" /* Command */, packet.pattern);
     const { data, hdrs, timeout, messageId } = this.extractRecordData(packet.data);
     const onUnhandled = (err) => {
       this.logger.error("Unhandled publish error:", err);
       callback({ err: new Error("Internal transport error"), response: null, isDisposed: true });
     };
     let jetStreamCorrelationId = null;
-    if (this.isCoreRpcMode()) {
+    if (isCoreRpcMode(this.rootOptions.rpc)) {
       this.publishCoreRpc(subject, data, hdrs, timeout, callback).catch(onUnhandled);
     } else {
       jetStreamCorrelationId = crypto.randomUUID();
-      this.publishJetStreamRpc(
-        subject,
-        data,
-        hdrs,
+      this.publishJetStreamRpc(subject, data, callback, {
+        headers: hdrs,
         timeout,
-        callback,
-        jetStreamCorrelationId,
+        correlationId: jetStreamCorrelationId,
         messageId
-      ).catch(onUnhandled);
+      }).catch(onUnhandled);
     }
     return () => {
       if (jetStreamCorrelationId) {
@@ -442,35 +468,46 @@ var JetstreamClient = class extends import_microservices.ClientProxy {
     }
   }
   /** JetStream mode: publish to stream + wait for inbox response. */
-  async publishJetStreamRpc(subject, data, customHeaders, timeout, callback, correlationId = crypto.randomUUID(), messageId) {
-    const effectiveTimeout = timeout ?? this.getRpcTimeout();
+  async publishJetStreamRpc(subject, data, callback, options) {
+    const { headers: customHeaders, correlationId, messageId } = options;
+    const effectiveTimeout = options.timeout ?? this.getRpcTimeout();
     this.pendingMessages.set(correlationId, callback);
-    const timeoutId = setTimeout(() => {
-      if (!this.pendingMessages.has(correlationId)) return;
-      this.pendingTimeouts.delete(correlationId);
-      this.pendingMessages.delete(correlationId);
-      this.logger.error(`JetStream RPC timeout (${effectiveTimeout}ms): ${subject}`);
-      this.eventBus.emit("rpcTimeout" /* RpcTimeout */, subject, correlationId);
-      callback({ err: new Error("RPC timeout"), response: null, isDisposed: true });
-    }, effectiveTimeout);
-    this.pendingTimeouts.set(correlationId, timeoutId);
     try {
-      const nc = await this.connect();
+      await this.connect();
+      if (!this.pendingMessages.has(correlationId)) return;
       if (!this.inbox) {
-        throw new Error("Inbox not initialized \u2014 JetStream RPC mode requires a connected inbox");
+        this.pendingMessages.delete(correlationId);
+        callback({
+          err: new Error("Inbox not initialized \u2014 JetStream RPC mode requires a connected inbox"),
+          response: null,
+          isDisposed: true
+        });
+        return;
       }
+      const timeoutId = setTimeout(() => {
+        if (!this.pendingMessages.has(correlationId)) return;
+        this.pendingTimeouts.delete(correlationId);
+        this.pendingMessages.delete(correlationId);
+        this.logger.error(`JetStream RPC timeout (${effectiveTimeout}ms): ${subject}`);
+        this.eventBus.emit("rpcTimeout" /* RpcTimeout */, subject, correlationId);
+        callback({ err: new Error("RPC timeout"), response: null, isDisposed: true });
+      }, effectiveTimeout);
+      this.pendingTimeouts.set(correlationId, timeoutId);
       const hdrs = this.buildHeaders(customHeaders, {
         subject,
         correlationId,
         replyTo: this.inbox
       });
-      await nc.jetstream().publish(subject, this.codec.encode(data), {
+      await this.connection.getJetStreamClient().publish(subject, this.codec.encode(data), {
         headers: hdrs,
         msgID: messageId ?? crypto.randomUUID()
       });
     } catch (err) {
-      clearTimeout(timeoutId);
-      this.pendingTimeouts.delete(correlationId);
+      const existingTimeout = this.pendingTimeouts.get(correlationId);
+      if (existingTimeout) {
+        clearTimeout(existingTimeout);
+        this.pendingTimeouts.delete(correlationId);
+      }
       if (!this.pendingMessages.has(correlationId)) return;
       this.pendingMessages.delete(correlationId);
       const error = err instanceof Error ? err : new Error("Unknown error");
@@ -546,19 +583,23 @@ var JetstreamClient = class extends import_microservices.ClientProxy {
   }
   /** Build event subject — workqueue, broadcast, or ordered. */
   buildEventSubject(pattern) {
-    if (pattern.startsWith("broadcast:")) {
-      return buildBroadcastSubject(pattern.slice("broadcast:".length));
-    }
-    if (pattern.startsWith("ordered:")) {
-      return buildSubject(this.targetName, "ordered", pattern.slice("ordered:".length));
+    if (pattern.startsWith("broadcast:" /* Broadcast */)) {
+      return buildBroadcastSubject(pattern.slice("broadcast:" /* Broadcast */.length));
+    }
+    if (pattern.startsWith("ordered:" /* Ordered */)) {
+      return buildSubject(
+        this.targetName,
+        "ordered" /* Ordered */,
+        pattern.slice("ordered:" /* Ordered */.length)
+      );
     }
-    return buildSubject(this.targetName, "ev", pattern);
+    return buildSubject(this.targetName, "ev" /* Event */, pattern);
   }
   /** Build NATS headers merging custom headers with transport headers. */
   buildHeaders(customHeaders, transport) {
     const hdrs = (0, import_nats2.headers)();
     hdrs.set("x-subject" /* Subject */, transport.subject);
-    hdrs.set("x-caller-name" /* CallerName */, internalName(this.rootOptions.name));
+    hdrs.set("x-caller-name" /* CallerName */, this.callerName);
     if (transport.correlationId) {
       hdrs.set("x-correlation-id" /* CorrelationId */, transport.correlationId);
     }
@@ -584,15 +625,9 @@ var JetstreamClient = class extends import_microservices.ClientProxy {
     }
     return { data: rawData, hdrs: null, timeout: void 0, messageId: void 0 };
   }
-  isCoreRpcMode() {
-    return !this.rootOptions.rpc || this.rootOptions.rpc.mode === "core";
-  }
-  isJetStreamRpcMode() {
-    return this.rootOptions.rpc?.mode === "jetstream";
-  }
   getRpcTimeout() {
     if (!this.rootOptions.rpc) return DEFAULT_RPC_TIMEOUT;
-    const defaultTimeout = this.isJetStreamRpcMode() ? DEFAULT_JETSTREAM_RPC_TIMEOUT : DEFAULT_RPC_TIMEOUT;
+    const defaultTimeout = isJetStreamRpcMode(this.rootOptions.rpc) ? DEFAULT_JETSTREAM_RPC_TIMEOUT : DEFAULT_RPC_TIMEOUT;
     return this.rootOptions.rpc.timeout ?? defaultTimeout;
   }
 };
@@ -613,6 +648,10 @@ var JsonCodec = class {
 var import_common2 = require("@nestjs/common");
 var import_nats4 = require("nats");
 var import_rxjs = require("rxjs");
+var DEFAULT_OPTIONS = {
+  maxReconnectAttempts: -1,
+  reconnectTimeWait: 1e3
+};
 var ConnectionProvider = class {
   constructor(options, eventBus) {
     this.options = options;
@@ -632,6 +671,7 @@ var ConnectionProvider = class {
   logger = new import_common2.Logger("Jetstream:Connection");
   connection = null;
   connectionPromise = null;
+  jsClient = null;
   jsmInstance = null;
   jsmPromise = null;
   /**
@@ -670,6 +710,22 @@ var ConnectionProvider = class {
     });
     return this.jsmPromise;
   }
+  /**
+   * Get a cached JetStream client.
+   *
+   * Invalidated automatically on reconnect and shutdown so consumers always
+   * operate against the live connection.
+   *
+   * @returns The cached JetStreamClient.
+   * @throws Error if the connection has not been established yet.
+   */
+  getJetStreamClient() {
+    if (!this.connection || this.connection.isClosed()) {
+      throw new Error("Not connected \u2014 call getConnection() before getJetStreamClient()");
+    }
+    this.jsClient ??= this.connection.jetstream();
+    return this.jsClient;
+  }
   /** Direct access to the raw NATS connection, or `null` if not yet connected. */
   get unwrap() {
     return this.connection;
@@ -698,6 +754,7 @@ var ConnectionProvider = class {
     } finally {
       this.connection = null;
       this.connectionPromise = null;
+      this.jsClient = null;
       this.jsmInstance = null;
       this.jsmPromise = null;
     }
@@ -707,6 +764,7 @@ var ConnectionProvider = class {
     const name = internalName(this.options.name);
     try {
       const nc = await (0, import_nats4.connect)({
+        ...DEFAULT_OPTIONS,
         ...this.options.connectionOptions,
         servers: this.options.servers,
         name
@@ -732,6 +790,7 @@ var ConnectionProvider = class {
             this.eventBus.emit("disconnect" /* Disconnect */);
             break;
           case import_nats4.Events.Reconnect:
+            this.jsClient = null;
             this.jsmInstance = null;
             this.jsmPromise = null;
             this.eventBus.emit("reconnect" /* Reconnect */, nc.getServer());
@@ -771,6 +830,23 @@ var EventBus = class {
   emit(event, ...args) {
     const hook = this.hooks[event];
     if (!hook) return;
+    this.callHook(event, hook, ...args);
+  }
+  /**
+   * Hot-path optimized emit for MessageRouted events.
+   * Avoids rest/spread overhead of the generic `emit()`.
+   */
+  emitMessageRouted(subject, kind) {
+    const hook = this.hooks["messageRouted" /* MessageRouted */];
+    if (!hook) return;
+    this.callHook(
+      "messageRouted" /* MessageRouted */,
+      hook,
+      subject,
+      kind
+    );
+  }
+  callHook(event, hook, ...args) {
     try {
       const result = hook(...args);
       if (result && typeof result.catch === "function") {
@@ -850,7 +926,7 @@ JetstreamHealthIndicator = __decorateClass([
 // src/server/strategy.ts
 var import_microservices2 = require("@nestjs/microservices");
 var JetstreamStrategy = class extends import_microservices2.Server {
-  constructor(options, connection, patternRegistry, streamProvider, consumerProvider, messageProvider, eventRouter, rpcRouter, coreRpcServer) {
+  constructor(options, connection, patternRegistry, streamProvider, consumerProvider, messageProvider, eventRouter, rpcRouter, coreRpcServer, ackWaitMap = /* @__PURE__ */ new Map()) {
     super();
     this.options = options;
     this.connection = connection;
@@ -861,6 +937,7 @@ var JetstreamStrategy = class extends import_microservices2.Server {
     this.eventRouter = eventRouter;
     this.rpcRouter = rpcRouter;
     this.coreRpcServer = coreRpcServer;
+    this.ackWaitMap = ackWaitMap;
   }
   transportId = /* @__PURE__ */ Symbol("jetstream-transport");
   // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
@@ -878,17 +955,17 @@ var JetstreamStrategy = class extends import_microservices2.Server {
     }
     this.started = true;
     this.patternRegistry.registerHandlers(this.getHandlers());
-    const streamKinds = this.resolveStreamKinds();
-    const durableKinds = this.resolveDurableConsumerKinds();
+    const { streams: streamKinds, durableConsumers: durableKinds } = this.resolveRequiredKinds();
     if (streamKinds.length > 0) {
       await this.streamProvider.ensureStreams(streamKinds);
       if (durableKinds.length > 0) {
         const consumers = await this.consumerProvider.ensureConsumers(durableKinds);
+        this.populateAckWaitMap(consumers);
         this.eventRouter.updateMaxDeliverMap(this.buildMaxDeliverMap(consumers));
         this.messageProvider.start(consumers);
       }
       if (this.patternRegistry.hasOrderedHandlers()) {
-        const orderedStreamName = this.streamProvider.getStreamName("ordered");
+        const orderedStreamName = this.streamProvider.getStreamName("ordered" /* Ordered */);
         await this.messageProvider.startOrdered(
           orderedStreamName,
           this.patternRegistry.getOrderedSubjects(),
@@ -898,11 +975,11 @@ var JetstreamStrategy = class extends import_microservices2.Server {
       if (this.patternRegistry.hasEventHandlers() || this.patternRegistry.hasBroadcastHandlers() || this.patternRegistry.hasOrderedHandlers()) {
         this.eventRouter.start();
       }
-      if (this.isJetStreamRpcMode() && this.patternRegistry.hasRpcHandlers()) {
-        this.rpcRouter.start();
+      if (isJetStreamRpcMode(this.options.rpc) && this.patternRegistry.hasRpcHandlers()) {
+        await this.rpcRouter.start();
       }
     }
-    if (this.isCoreRpcMode() && this.patternRegistry.hasRpcHandlers()) {
+    if (isCoreRpcMode(this.options.rpc) && this.patternRegistry.hasRpcHandlers()) {
       await this.coreRpcServer.start();
     }
     callback();
@@ -943,36 +1020,34 @@ var JetstreamStrategy = class extends import_microservices2.Server {
   getPatternRegistry() {
     return this.patternRegistry;
   }
-  /** Determine which JetStream streams are needed. */
-  resolveStreamKinds() {
-    const kinds = [];
+  /** Determine which streams and durable consumers are needed. */
+  resolveRequiredKinds() {
+    const streams = [];
+    const durableConsumers = [];
     if (this.patternRegistry.hasEventHandlers()) {
-      kinds.push("ev");
+      streams.push("ev" /* Event */);
+      durableConsumers.push("ev" /* Event */);
     }
-    if (this.patternRegistry.hasOrderedHandlers()) {
-      kinds.push("ordered");
-    }
-    if (this.isJetStreamRpcMode() && this.patternRegistry.hasRpcHandlers()) {
-      kinds.push("cmd");
+    if (isJetStreamRpcMode(this.options.rpc) && this.patternRegistry.hasRpcHandlers()) {
+      streams.push("cmd" /* Command */);
+      durableConsumers.push("cmd" /* Command */);
     }
     if (this.patternRegistry.hasBroadcastHandlers()) {
-      kinds.push("broadcast");
+      streams.push("broadcast" /* Broadcast */);
+      durableConsumers.push("broadcast" /* Broadcast */);
     }
-    return kinds;
-  }
-  /** Determine which stream kinds need durable consumers (ordered consumers are ephemeral). */
-  resolveDurableConsumerKinds() {
-    const kinds = [];
-    if (this.patternRegistry.hasEventHandlers()) {
-      kinds.push("ev");
-    }
-    if (this.isJetStreamRpcMode() && this.patternRegistry.hasRpcHandlers()) {
-      kinds.push("cmd");
+    if (this.patternRegistry.hasOrderedHandlers()) {
+      streams.push("ordered" /* Ordered */);
     }
-    if (this.patternRegistry.hasBroadcastHandlers()) {
-      kinds.push("broadcast");
+    return { streams, durableConsumers };
+  }
+  /** Populate the shared ack_wait map from actual NATS consumer configs. */
+  populateAckWaitMap(consumers) {
+    for (const [kind, info] of consumers) {
+      if (info.config.ack_wait) {
+        this.ackWaitMap.set(kind, info.config.ack_wait);
+      }
     }
-    return kinds;
   }
   /** Build max_deliver map from actual NATS consumer configs (not options). */
   buildMaxDeliverMap(consumers) {
@@ -986,12 +1061,6 @@ var JetstreamStrategy = class extends import_microservices2.Server {
     }
     return map;
   }
-  isCoreRpcMode() {
-    return !this.options.rpc || this.options.rpc.mode === "core";
-  }
-  isJetStreamRpcMode() {
-    return this.options.rpc?.mode === "jetstream";
-  }
 };
 
 // src/server/core-rpc.server.ts
@@ -1001,6 +1070,13 @@ var import_nats5 = require("nats");
 // src/context/rpc.context.ts
 var import_microservices3 = require("@nestjs/microservices");
 var RpcContext = class extends import_microservices3.BaseRpcContext {
+  _shouldRetry = false;
+  _retryDelay;
+  _shouldTerminate = false;
+  _terminateReason;
+  // ---------------------------------------------------------------------------
+  // Message accessors
+  // ---------------------------------------------------------------------------
   /**
    * Get the underlying NATS message.
    *
@@ -1035,6 +1111,122 @@ var RpcContext = class extends import_microservices3.BaseRpcContext {
   isJetStream() {
     return "ack" in this.args[0];
   }
+  // ---------------------------------------------------------------------------
+  // JetStream metadata (return undefined for Core NATS messages)
+  // ---------------------------------------------------------------------------
+  /** How many times this message has been delivered. */
+  getDeliveryCount() {
+    return this.asJetStream()?.info.deliveryCount;
+  }
+  /** The JetStream stream this message belongs to. */
+  getStream() {
+    return this.asJetStream()?.info.stream;
+  }
+  /** The stream sequence number. */
+  getSequence() {
+    return this.asJetStream()?.seq;
+  }
+  /** The message timestamp as a `Date` (derived from `info.timestampNanos`). */
+  getTimestamp() {
+    const nanos = this.asJetStream()?.info.timestampNanos;
+    return typeof nanos === "number" ? new Date(nanos / 1e6) : void 0;
+  }
+  /** The name of the service that published this message (from `x-caller-name` header). */
+  getCallerName() {
+    return this.getHeader("x-caller-name" /* CallerName */);
+  }
+  // ---------------------------------------------------------------------------
+  // Handler-controlled settlement
+  // ---------------------------------------------------------------------------
+  /**
+   * Signal the transport to retry (nak) this message instead of acknowledging it.
+   *
+   * Use for business-level retries without throwing errors.
+   * Only affects JetStream event handlers (workqueue/broadcast).
+   *
+   * @param opts - Optional delay in ms before redelivery.
+   * @throws Error if {@link terminate} was already called.
+   */
+  retry(opts) {
+    this.assertJetStream("retry");
+    if (this._shouldTerminate) {
+      throw new Error("Cannot retry \u2014 terminate() was already called");
+    }
+    this._shouldRetry = true;
+    this._retryDelay = opts?.delayMs;
+  }
+  /**
+   * Signal the transport to permanently reject (term) this message.
+   *
+   * Use when a message is no longer relevant and should not be retried or sent to DLQ.
+   * Only affects JetStream event handlers (workqueue/broadcast).
+   *
+   * @param reason - Optional reason for termination (logged by NATS).
+   * @throws Error if {@link retry} was already called.
+   */
+  terminate(reason) {
+    this.assertJetStream("terminate");
+    if (this._shouldRetry) {
+      throw new Error("Cannot terminate \u2014 retry() was already called");
+    }
+    this._shouldTerminate = true;
+    this._terminateReason = reason;
+  }
+  /** Narrow to JsMsg or return null for Core messages. Used by metadata getters. */
+  asJetStream() {
+    return this.isJetStream() ? this.args[0] : null;
+  }
+  /** Ensure the message is JetStream — settlement actions are not available for Core NATS. */
+  assertJetStream(method) {
+    if (!this.isJetStream()) {
+      throw new Error(`${method}() is only available for JetStream messages`);
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Transport-facing state (read by EventRouter)
+  // ---------------------------------------------------------------------------
+  /** @internal */
+  get shouldRetry() {
+    return this._shouldRetry;
+  }
+  /** @internal */
+  get retryDelay() {
+    return this._retryDelay;
+  }
+  /** @internal */
+  get shouldTerminate() {
+    return this._shouldTerminate;
+  }
+  /** @internal */
+  get terminateReason() {
+    return this._terminateReason;
+  }
+};
+
+// src/utils/ack-extension.ts
+var DEFAULT_ACK_EXTENSION_INTERVAL = 5e3;
+var MIN_ACK_EXTENSION_INTERVAL = 500;
+var resolveAckExtensionInterval = (config, ackWaitNanos) => {
+  if (config === false || config === void 0) return null;
+  if (typeof config === "number") {
+    if (!Number.isFinite(config) || config <= 0) return null;
+    return Math.floor(config);
+  }
+  if (!ackWaitNanos) return DEFAULT_ACK_EXTENSION_INTERVAL;
+  const interval = Math.floor(ackWaitNanos / 1e6 / 2);
+  return Math.max(interval, MIN_ACK_EXTENSION_INTERVAL);
+};
+var startAckExtensionTimer = (msg, interval) => {
+  if (interval === null || interval <= 0) return null;
+  const timer2 = setInterval(() => {
+    try {
+      msg.working();
+    } catch {
+    }
+  }, interval);
+  return () => {
+    clearInterval(timer2);
+  };
 };
 
 // src/utils/serialize-error.ts
@@ -1047,15 +1239,20 @@ var serializeError = (err) => {
 
 // src/utils/unwrap-result.ts
 var import_rxjs2 = require("rxjs");
-var unwrapResult = async (result) => {
+var RESOLVED_VOID = Promise.resolve(void 0);
+var RESOLVED_NULL = Promise.resolve(null);
+var unwrapResult = (result) => {
+  if (result === void 0) return RESOLVED_VOID;
+  if (result === null) return RESOLVED_NULL;
   if ((0, import_rxjs2.isObservable)(result)) {
     return subscribeToFirst(result);
   }
-  const resolved = await result;
-  if ((0, import_rxjs2.isObservable)(resolved)) {
-    return subscribeToFirst(resolved);
+  if (typeof result.then === "function") {
+    return result.then(
+      (resolved) => (0, import_rxjs2.isObservable)(resolved) ? subscribeToFirst(resolved) : resolved
+    );
   }
-  return resolved;
+  return Promise.resolve(result);
 };
 var subscribeToFirst = (obs) => new Promise((resolve, reject) => {
   let done = false;
@@ -1123,13 +1320,17 @@ var CoreRpcServer = class {
   }
   /** Handle an incoming Core NATS request. */
   async handleRequest(msg) {
+    if (!msg.reply) {
+      this.logger.warn(`Ignoring fire-and-forget message on RPC subject: ${msg.subject}`);
+      return;
+    }
     const handler = this.patternRegistry.getHandler(msg.subject);
     if (!handler) {
       this.logger.warn(`No handler for Core RPC: ${msg.subject}`);
       this.respondWithError(msg, new Error(`No handler for subject: ${msg.subject}`));
       return;
     }
-    this.eventBus.emit("messageRouted" /* MessageRouted */, msg.subject, "rpc");
+    this.eventBus.emitMessageRouted(msg.subject, "rpc" /* Rpc */);
     let data;
     try {
       data = this.codec.decode(msg.data);
@@ -1187,14 +1388,14 @@ var StreamProvider = class {
   getSubjects(kind) {
     const name = internalName(this.options.name);
     switch (kind) {
-      case "ev":
-        return [`${name}.ev.>`];
-      case "cmd":
-        return [`${name}.cmd.>`];
-      case "broadcast":
+      case "ev" /* Event */:
+        return [`${name}.${"ev" /* Event */}.>`];
+      case "cmd" /* Command */:
+        return [`${name}.${"cmd" /* Command */}.>`];
+      case "broadcast" /* Broadcast */:
         return ["broadcast.>"];
-      case "ordered":
-        return [`${name}.ordered.>`];
+      case "ordered" /* Ordered */:
+        return [`${name}.${"ordered" /* Ordered */}.>`];
     }
   }
   /** Ensure a single stream exists, creating or updating as needed. */
@@ -1231,26 +1432,26 @@ var StreamProvider = class {
   /** Get default config for a stream kind. */
   getDefaults(kind) {
     switch (kind) {
-      case "ev":
+      case "ev" /* Event */:
         return DEFAULT_EVENT_STREAM_CONFIG;
-      case "cmd":
+      case "cmd" /* Command */:
         return DEFAULT_COMMAND_STREAM_CONFIG;
-      case "broadcast":
+      case "broadcast" /* Broadcast */:
         return DEFAULT_BROADCAST_STREAM_CONFIG;
-      case "ordered":
+      case "ordered" /* Ordered */:
         return DEFAULT_ORDERED_STREAM_CONFIG;
     }
   }
   /** Get user-provided overrides for a stream kind. */
   getOverrides(kind) {
     switch (kind) {
-      case "ev":
+      case "ev" /* Event */:
         return this.options.events?.stream ?? {};
-      case "cmd":
+      case "cmd" /* Command */:
         return this.options.rpc?.mode === "jetstream" ? this.options.rpc.stream ?? {} : {};
-      case "broadcast":
+      case "broadcast" /* Broadcast */:
         return this.options.broadcast?.stream ?? {};
-      case "ordered":
+      case "ordered" /* Ordered */:
         return this.options.ordered?.stream ?? {};
     }
   }
@@ -1313,7 +1514,7 @@ var ConsumerProvider = class {
     const serviceName = internalName(this.options.name);
     const defaults = this.getDefaults(kind);
     const overrides = this.getOverrides(kind);
-    if (kind === "broadcast") {
+    if (kind === "broadcast" /* Broadcast */) {
       const broadcastPatterns = this.patternRegistry.getBroadcastPatterns();
       if (broadcastPatterns.length === 0) {
         throw new Error("Broadcast consumer requested but no broadcast patterns are registered");
@@ -1335,7 +1536,10 @@ var ConsumerProvider = class {
         filter_subjects: broadcastPatterns
       };
     }
-    const filter_subject = kind === "ev" ? `${serviceName}.ev.>` : `${serviceName}.cmd.>`;
+    if (kind !== "ev" /* Event */ && kind !== "cmd" /* Command */) {
+      throw new Error(`Unexpected durable consumer kind: ${kind}`);
+    }
+    const filter_subject = `${serviceName}.${kind}.>`;
     return {
       ...defaults,
       ...overrides,
@@ -1347,26 +1551,26 @@ var ConsumerProvider = class {
   /** Get default config for a consumer kind. */
   getDefaults(kind) {
     switch (kind) {
-      case "ev":
+      case "ev" /* Event */:
         return DEFAULT_EVENT_CONSUMER_CONFIG;
-      case "cmd":
+      case "cmd" /* Command */:
         return DEFAULT_COMMAND_CONSUMER_CONFIG;
-      case "broadcast":
+      case "broadcast" /* Broadcast */:
         return DEFAULT_BROADCAST_CONSUMER_CONFIG;
-      case "ordered":
+      case "ordered" /* Ordered */:
         throw new Error("Ordered consumers are ephemeral and should not use durable config");
     }
   }
   /** Get user-provided overrides for a consumer kind. */
   getOverrides(kind) {
     switch (kind) {
-      case "ev":
+      case "ev" /* Event */:
         return this.options.events?.consumer ?? {};
-      case "cmd":
+      case "cmd" /* Command */:
         return this.options.rpc?.mode === "jetstream" ? this.options.rpc.consumer ?? {} : {};
-      case "broadcast":
+      case "broadcast" /* Broadcast */:
         return this.options.broadcast?.consumer ?? {};
-      case "ordered":
+      case "ordered" /* Ordered */:
         throw new Error("Ordered consumers are ephemeral and should not use durable config");
     }
   }
@@ -1377,9 +1581,10 @@ var import_common7 = require("@nestjs/common");
 var import_nats8 = require("nats");
 var import_rxjs3 = require("rxjs");
 var MessageProvider = class {
-  constructor(connection, eventBus) {
+  constructor(connection, eventBus, consumeOptionsMap = /* @__PURE__ */ new Map()) {
     this.connection = connection;
     this.eventBus = eventBus;
+    this.consumeOptionsMap = consumeOptionsMap;
   }
   logger = new import_common7.Logger("Jetstream:Message");
   activeIterators = /* @__PURE__ */ new Set();
@@ -1429,6 +1634,7 @@ var MessageProvider = class {
    *
    * @param streamName - JetStream stream to consume from.
    * @param filterSubjects - NATS subjects to filter on.
+   * @param orderedConfig - Optional overrides for ordered consumer options.
    */
   async startOrdered(streamName2, filterSubjects, orderedConfig) {
     const consumerOpts = { filterSubjects };
@@ -1454,6 +1660,11 @@ var MessageProvider = class {
   }
   /** Stop all consumer flows and reinitialize subjects for potential restart. */
   destroy() {
+    if (this.orderedReadyReject) {
+      this.orderedReadyReject(new Error("Destroyed before ordered consumer connected"));
+      this.orderedReadyResolve = null;
+      this.orderedReadyReject = null;
+    }
     this.destroy$.next();
     this.destroy$.complete();
     for (const messages of this.activeIterators) {
@@ -1473,42 +1684,17 @@ var MessageProvider = class {
   /** Create a self-healing consumer flow for a specific kind. */
   createFlow(kind, info) {
     const target$ = this.getTargetSubject(kind);
-    let consecutiveFailures = 0;
-    let lastRunFailed = false;
-    return (0, import_rxjs3.defer)(() => this.consumeOnce(info, target$)).pipe(
-      (0, import_rxjs3.tap)(() => {
-        lastRunFailed = false;
-      }),
-      (0, import_rxjs3.catchError)((err) => {
-        consecutiveFailures++;
-        lastRunFailed = true;
-        this.logger.error(`Consumer ${info.name} error, will restart:`, err);
-        this.eventBus.emit(
-          "error" /* Error */,
-          err instanceof Error ? err : new Error(String(err)),
-          "message-provider"
-        );
-        return import_rxjs3.EMPTY;
-      }),
-      (0, import_rxjs3.repeat)({
-        delay: () => {
-          if (!lastRunFailed) {
-            consecutiveFailures = 0;
-          }
-          const delay = Math.min(100 * Math.pow(2, consecutiveFailures), 3e4);
-          this.logger.warn(`Consumer ${info.name} stream ended, restarting in ${delay}ms...`);
-          return (0, import_rxjs3.timer)(delay);
-        }
-      }),
-      (0, import_rxjs3.takeUntil)(this.destroy$)
-    );
+    return this.createSelfHealingFlow(() => this.consumeOnce(kind, info, target$), info.name);
   }
   /** Single iteration: get consumer -> pull messages -> emit to subject. */
-  async consumeOnce(info, target$) {
-    const js = (await this.connection.getConnection()).jetstream();
+  async consumeOnce(kind, info, target$) {
+    const js = this.connection.getJetStreamClient();
     const consumer = await js.consumers.get(info.stream_name, info.name);
-    const messages = await consumer.consume();
+    const defaults = { idle_heartbeat: 5e3 };
+    const userOptions = this.consumeOptionsMap.get(kind) ?? {};
+    const messages = await consumer.consume({ ...defaults, ...userOptions });
     this.activeIterators.add(messages);
+    this.monitorConsumerHealth(messages, info.name);
     try {
       for await (const msg of messages) {
         target$.next(msg);
@@ -1520,47 +1706,73 @@ var MessageProvider = class {
   /** Get the target subject for a consumer kind. */
   getTargetSubject(kind) {
     switch (kind) {
-      case "ev":
+      case "ev" /* Event */:
         return this.eventMessages$;
-      case "cmd":
+      case "cmd" /* Command */:
         return this.commandMessages$;
-      case "broadcast":
+      case "broadcast" /* Broadcast */:
         return this.broadcastMessages$;
-      case "ordered":
+      case "ordered" /* Ordered */:
         return this.orderedMessages$;
+      default: {
+        const _exhaustive = kind;
+        throw new Error(`Unknown stream kind: ${_exhaustive}`);
+      }
     }
   }
+  /** Monitor heartbeats and restart the consumer iterator on prolonged silence. */
+  monitorConsumerHealth(messages, name) {
+    (async () => {
+      for await (const status of await messages.status()) {
+        if (status.type === import_nats8.ConsumerEvents.HeartbeatsMissed && status.data >= 2) {
+          this.logger.warn(`Consumer ${name}: ${status.data} heartbeats missed, restarting`);
+          messages.stop();
+          break;
+        }
+      }
+    })().catch((err) => {
+      if (err) {
+        this.logger.debug(`Consumer ${name} health monitor ended:`, err);
+      }
+    });
+  }
   /** Create a self-healing ordered consumer flow. */
   createOrderedFlow(streamName2, consumerOpts) {
+    return this.createSelfHealingFlow(
+      () => this.consumeOrderedOnce(streamName2, consumerOpts),
+      "ordered" /* Ordered */,
+      (err) => {
+        if (this.orderedReadyReject) {
+          this.orderedReadyReject(err);
+          this.orderedReadyReject = null;
+          this.orderedReadyResolve = null;
+        }
+      }
+    );
+  }
+  /** Shared self-healing flow: defer -> retry with exponential backoff on error/completion. */
+  createSelfHealingFlow(source, label, onFirstError) {
     let consecutiveFailures = 0;
-    let lastRunFailed = false;
-    return (0, import_rxjs3.defer)(() => this.consumeOrderedOnce(streamName2, consumerOpts)).pipe(
+    return (0, import_rxjs3.defer)(source).pipe(
       (0, import_rxjs3.tap)(() => {
-        lastRunFailed = false;
+        consecutiveFailures = 0;
       }),
       (0, import_rxjs3.catchError)((err) => {
         consecutiveFailures++;
-        lastRunFailed = true;
-        this.logger.error("Ordered consumer error, will restart:", err);
+        this.logger.error(`Consumer ${label} error, will restart:`, err);
         this.eventBus.emit(
           "error" /* Error */,
           err instanceof Error ? err : new Error(String(err)),
           "message-provider"
         );
-        if (this.orderedReadyReject) {
-          this.orderedReadyReject(err);
-          this.orderedReadyReject = null;
-          this.orderedReadyResolve = null;
-        }
+        onFirstError?.(err);
+        onFirstError = void 0;
         return import_rxjs3.EMPTY;
       }),
       (0, import_rxjs3.repeat)({
         delay: () => {
-          if (!lastRunFailed) {
-            consecutiveFailures = 0;
-          }
           const delay = Math.min(100 * Math.pow(2, consecutiveFailures), 3e4);
-          this.logger.warn(`Ordered consumer stream ended, restarting in ${delay}ms...`);
+          this.logger.warn(`Consumer ${label} stream ended, restarting in ${delay}ms...`);
           return (0, import_rxjs3.timer)(delay);
         }
       })
@@ -1568,7 +1780,7 @@ var MessageProvider = class {
   }
   /** Single iteration: create ordered consumer -> iterate messages. */
   async consumeOrderedOnce(streamName2, consumerOpts) {
-    const js = (await this.connection.getConnection()).jetstream();
+    const js = this.connection.getJetStreamClient();
     const consumer = await js.consumers.get(streamName2, consumerOpts);
     const messages = await consumer.consume();
     if (this.orderedReadyResolve) {
@@ -1589,12 +1801,24 @@ var MessageProvider = class {
 
 // src/server/routing/pattern-registry.ts
 var import_common8 = require("@nestjs/common");
+var HANDLER_LABELS = {
+  ["broadcast" /* Broadcast */]: "broadcast" /* Broadcast */,
+  ["ordered" /* Ordered */]: "ordered" /* Ordered */,
+  ["ev" /* Event */]: "event" /* Event */,
+  ["cmd" /* Command */]: "rpc" /* Rpc */
+};
 var PatternRegistry = class {
   constructor(options) {
     this.options = options;
   }
   logger = new import_common8.Logger("Jetstream:PatternRegistry");
   registry = /* @__PURE__ */ new Map();
+  // Cached after registerHandlers() — the registry is immutable from that point
+  cachedPatterns = null;
+  _hasEvents = false;
+  _hasCommands = false;
+  _hasBroadcasts = false;
+  _hasOrdered = false;
   /**
    * Register all handlers from the NestJS strategy.
    *
@@ -1612,16 +1836,12 @@ var PatternRegistry = class {
           `Handler "${pattern}" cannot be both broadcast and ordered. Use one or the other.`
         );
       }
-      let fullSubject;
-      if (isBroadcast) {
-        fullSubject = buildBroadcastSubject(pattern);
-      } else if (isOrdered) {
-        fullSubject = buildSubject(serviceName, "ordered", pattern);
-      } else if (isEvent) {
-        fullSubject = buildSubject(serviceName, "ev", pattern);
-      } else {
-        fullSubject = buildSubject(serviceName, "cmd", pattern);
-      }
+      let kind;
+      if (isBroadcast) kind = "broadcast" /* Broadcast */;
+      else if (isOrdered) kind = "ordered" /* Ordered */;
+      else if (isEvent) kind = "ev" /* Event */;
+      else kind = "cmd" /* Command */;
+      const fullSubject = kind === "broadcast" /* Broadcast */ ? buildBroadcastSubject(pattern) : buildSubject(serviceName, kind, pattern);
       this.registry.set(fullSubject, {
         handler,
         pattern,
@@ -1629,18 +1849,13 @@ var PatternRegistry = class {
         isBroadcast,
         isOrdered
       });
-      let kind;
-      if (isBroadcast) {
-        kind = "broadcast";
-      } else if (isOrdered) {
-        kind = "ordered";
-      } else if (isEvent) {
-        kind = "event";
-      } else {
-        kind = "rpc";
-      }
-      this.logger.debug(`Registered ${kind}: ${pattern} -> ${fullSubject}`);
+      this.logger.debug(`Registered ${HANDLER_LABELS[kind]}: ${pattern} -> ${fullSubject}`);
     }
+    this.cachedPatterns = this.buildPatternsByKind();
+    this._hasEvents = this.cachedPatterns.events.length > 0;
+    this._hasCommands = this.cachedPatterns.commands.length > 0;
+    this._hasBroadcasts = this.cachedPatterns.broadcasts.length > 0;
+    this._hasOrdered = this.cachedPatterns.ordered.length > 0;
     this.logSummary();
   }
   /** Find handler for a full NATS subject. */
@@ -1649,33 +1864,53 @@ var PatternRegistry = class {
   }
   /** Get all registered broadcast patterns (for consumer filter_subject setup). */
   getBroadcastPatterns() {
-    return Array.from(this.registry.values()).filter((r) => r.isBroadcast).map((r) => `broadcast.${r.pattern}`);
+    return this.getPatternsByKind().broadcasts.map((p) => buildBroadcastSubject(p));
   }
-  /** Check if any broadcast handlers are registered. */
   hasBroadcastHandlers() {
-    return Array.from(this.registry.values()).some((r) => r.isBroadcast);
+    return this._hasBroadcasts;
   }
-  /** Check if any RPC (command) handlers are registered. */
   hasRpcHandlers() {
-    return Array.from(this.registry.values()).some(
-      (r) => !r.isEvent && !r.isBroadcast && !r.isOrdered
-    );
+    return this._hasCommands;
   }
-  /** Check if any workqueue event handlers are registered. */
   hasEventHandlers() {
-    return Array.from(this.registry.values()).some((r) => r.isEvent && !r.isBroadcast);
+    return this._hasEvents;
   }
-  /** Check if any ordered event handlers are registered. */
   hasOrderedHandlers() {
-    return Array.from(this.registry.values()).some((r) => r.isOrdered);
+    return this._hasOrdered;
   }
   /** Get fully-qualified NATS subjects for ordered handlers. */
   getOrderedSubjects() {
-    const name = internalName(this.options.name);
-    return Array.from(this.registry.values()).filter((r) => r.isOrdered).map((r) => `${name}.ordered.${r.pattern}`);
+    return this.getPatternsByKind().ordered.map(
+      (p) => buildSubject(this.options.name, "ordered" /* Ordered */, p)
+    );
   }
-  /** Get patterns grouped by kind. */
+  /** Get patterns grouped by kind (cached after registration). */
   getPatternsByKind() {
+    const patterns = this.cachedPatterns ?? this.buildPatternsByKind();
+    return {
+      events: [...patterns.events],
+      commands: [...patterns.commands],
+      broadcasts: [...patterns.broadcasts],
+      ordered: [...patterns.ordered]
+    };
+  }
+  /** Normalize a full NATS subject back to the user-facing pattern. */
+  normalizeSubject(subject) {
+    const name = internalName(this.options.name);
+    const prefixes = [
+      `${name}.${"cmd" /* Command */}.`,
+      `${name}.${"ev" /* Event */}.`,
+      `${name}.${"ordered" /* Ordered */}.`,
+      `${"broadcast" /* Broadcast */}.`
+    ];
+    for (const prefix of prefixes) {
+      if (subject.startsWith(prefix)) {
+        return subject.slice(prefix.length);
+      }
+    }
+    return subject;
+  }
+  buildPatternsByKind() {
     const events = [];
     const commands = [];
     const broadcasts = [];
@@ -1688,18 +1923,6 @@ var PatternRegistry = class {
     }
     return { events, commands, broadcasts, ordered };
   }
-  /** Normalize a full NATS subject back to the user-facing pattern. */
-  normalizeSubject(subject) {
-    const name = internalName(this.options.name);
-    const prefixes = [`${name}.cmd.`, `${name}.ev.`, `${name}.ordered.`, "broadcast."];
-    for (const prefix of prefixes) {
-      if (subject.startsWith(prefix)) {
-        return subject.slice(prefix.length);
-      }
-    }
-    return subject;
-  }
-  /** Log a summary of all registered handlers. */
   logSummary() {
     const { events, commands, broadcasts, ordered } = this.getPatternsByKind();
     const parts = [
@@ -1718,12 +1941,14 @@ var PatternRegistry = class {
 var import_common9 = require("@nestjs/common");
 var import_rxjs4 = require("rxjs");
 var EventRouter = class {
-  constructor(messageProvider, patternRegistry, codec, eventBus, deadLetterConfig) {
+  constructor(messageProvider, patternRegistry, codec, eventBus, deadLetterConfig, processingConfig, ackWaitMap) {
     this.messageProvider = messageProvider;
     this.patternRegistry = patternRegistry;
     this.codec = codec;
     this.eventBus = eventBus;
     this.deadLetterConfig = deadLetterConfig;
+    this.processingConfig = processingConfig;
+    this.ackWaitMap = ackWaitMap;
   }
   logger = new import_common9.Logger("Jetstream:EventRouter");
   subscriptions = [];
@@ -1737,10 +1962,10 @@ var EventRouter = class {
   }
   /** Start routing event, broadcast, and ordered messages to handlers. */
   start() {
-    this.subscribeToStream(this.messageProvider.events$, "workqueue");
-    this.subscribeToStream(this.messageProvider.broadcasts$, "broadcast");
+    this.subscribeToStream(this.messageProvider.events$, "ev" /* Event */);
+    this.subscribeToStream(this.messageProvider.broadcasts$, "broadcast" /* Broadcast */);
     if (this.patternRegistry.hasOrderedHandlers()) {
-      this.subscribeToStream(this.messageProvider.ordered$, "ordered", true);
+      this.subscribeToStream(this.messageProvider.ordered$, "ordered" /* Ordered */);
     }
   }
   /** Stop routing and unsubscribe from all streams. */
@@ -1751,41 +1976,88 @@ var EventRouter = class {
     this.subscriptions.length = 0;
   }
   /** Subscribe to a message stream and route each message. */
-  subscribeToStream(stream$, label, isOrdered = false) {
-    const route = (msg) => (0, import_rxjs4.defer)(() => isOrdered ? this.handleOrdered(msg) : this.handle(msg)).pipe(
-      (0, import_rxjs4.catchError)((err) => {
-        this.logger.error(`Unexpected error in ${label} event router`, err);
-        return import_rxjs4.EMPTY;
-      })
+  subscribeToStream(stream$, kind) {
+    const isOrdered = kind === "ordered" /* Ordered */;
+    const ackExtensionInterval = isOrdered ? null : resolveAckExtensionInterval(this.getAckExtensionConfig(kind), this.ackWaitMap?.get(kind));
+    const concurrency = this.getConcurrency(kind);
+    const route = (msg) => (0, import_rxjs4.from)(
+      isOrdered ? this.handleOrderedSafe(msg) : this.handleSafe(msg, ackExtensionInterval, kind)
     );
-    const subscription = stream$.pipe(isOrdered ? (0, import_rxjs4.concatMap)(route) : (0, import_rxjs4.mergeMap)(route)).subscribe();
+    const subscription = stream$.pipe(isOrdered ? (0, import_rxjs4.concatMap)(route) : (0, import_rxjs4.mergeMap)(route, concurrency)).subscribe();
     this.subscriptions.push(subscription);
   }
-  /** Handle a single event message: decode -> execute handler -> ack/nak. */
-  handle(msg) {
+  getConcurrency(kind) {
+    if (kind === "ev" /* Event */) return this.processingConfig?.events?.concurrency;
+    if (kind === "broadcast" /* Broadcast */) return this.processingConfig?.broadcast?.concurrency;
+    return void 0;
+  }
+  getAckExtensionConfig(kind) {
+    if (kind === "ev" /* Event */) return this.processingConfig?.events?.ackExtension;
+    if (kind === "broadcast" /* Broadcast */) return this.processingConfig?.broadcast?.ackExtension;
+    return void 0;
+  }
+  /** Handle a single event message with error isolation. */
+  async handleSafe(msg, ackExtensionInterval, kind) {
+    try {
+      const resolved = this.decodeMessage(msg);
+      if (!resolved) return;
+      await this.executeHandler(
+        resolved.handler,
+        resolved.data,
+        resolved.ctx,
+        msg,
+        ackExtensionInterval
+      );
+    } catch (err) {
+      this.logger.error(`Unexpected error in ${kind} event router`, err);
+    }
+  }
+  /** Handle an ordered message with error isolation. */
+  async handleOrderedSafe(msg) {
+    try {
+      const resolved = this.decodeMessage(msg, true);
+      if (!resolved) return;
+      await unwrapResult(resolved.handler(resolved.data, resolved.ctx));
+      if (resolved.ctx.shouldRetry || resolved.ctx.shouldTerminate) {
+        this.logger.warn(
+          `retry()/terminate() ignored for ordered message ${msg.subject} \u2014 ordered consumers auto-acknowledge`
+        );
+      }
+    } catch (err) {
+      this.logger.error(`Ordered handler error (${msg.subject}):`, err);
+    }
+  }
+  /** Resolve handler, decode payload, and build context. Returns null on failure. */
+  decodeMessage(msg, isOrdered = false) {
     const handler = this.patternRegistry.getHandler(msg.subject);
     if (!handler) {
-      msg.term(`No handler for event: ${msg.subject}`);
-      this.logger.error(`No handler for event subject: ${msg.subject}`);
-      return import_rxjs4.EMPTY;
+      if (!isOrdered) msg.term(`No handler for event: ${msg.subject}`);
+      this.logger.error(`No handler for subject: ${msg.subject}`);
+      return null;
     }
     let data;
     try {
       data = this.codec.decode(msg.data);
     } catch (err) {
-      msg.term("Decode error");
+      if (!isOrdered) msg.term("Decode error");
       this.logger.error(`Decode error for ${msg.subject}:`, err);
-      return import_rxjs4.EMPTY;
+      return null;
     }
-    this.eventBus.emit("messageRouted" /* MessageRouted */, msg.subject, "event");
-    const ctx = new RpcContext([msg]);
-    return (0, import_rxjs4.from)(this.executeHandler(handler, data, ctx, msg));
+    this.eventBus.emitMessageRouted(msg.subject, "event" /* Event */);
+    return { handler, data, ctx: new RpcContext([msg]) };
   }
   /** Execute handler, then ack on success or nak/dead-letter on failure. */
-  async executeHandler(handler, data, ctx, msg) {
+  async executeHandler(handler, data, ctx, msg, ackExtensionInterval) {
+    const stopAckExtension = startAckExtensionTimer(msg, ackExtensionInterval);
     try {
       await unwrapResult(handler(data, ctx));
-      msg.ack();
+      if (ctx.shouldTerminate) {
+        msg.term(ctx.terminateReason);
+      } else if (ctx.shouldRetry) {
+        msg.nak(ctx.retryDelay);
+      } else {
+        msg.ack();
+      }
     } catch (err) {
       this.logger.error(`Event handler error (${msg.subject}):`, err);
       if (this.isDeadLetter(msg)) {
@@ -1793,30 +2065,10 @@ var EventRouter = class {
       } else {
         msg.nak();
       }
+    } finally {
+      stopAckExtension?.();
     }
   }
-  /** Handle an ordered message: decode -> execute handler -> no ack/nak. */
-  handleOrdered(msg) {
-    const handler = this.patternRegistry.getHandler(msg.subject);
-    if (!handler) {
-      this.logger.error(`No handler for ordered subject: ${msg.subject}`);
-      return import_rxjs4.EMPTY;
-    }
-    let data;
-    try {
-      data = this.codec.decode(msg.data);
-    } catch (err) {
-      this.logger.error(`Decode error for ordered ${msg.subject}:`, err);
-      return import_rxjs4.EMPTY;
-    }
-    this.eventBus.emit("messageRouted" /* MessageRouted */, msg.subject, "event");
-    const ctx = new RpcContext([msg]);
-    return (0, import_rxjs4.from)(
-      unwrapResult(handler(data, ctx)).catch((err) => {
-        this.logger.error(`Ordered handler error (${msg.subject}):`, err);
-      })
-    );
-  }
   /** Check if the message has exhausted all delivery attempts. */
   isDeadLetter(msg) {
     if (!this.deadLetterConfig) return false;
@@ -1837,7 +2089,10 @@ var EventRouter = class {
       timestamp: new Date(msg.info.timestampNanos / 1e6).toISOString()
     };
     this.eventBus.emit("deadLetter" /* DeadLetter */, info);
-    if (!this.deadLetterConfig) return;
+    if (!this.deadLetterConfig) {
+      msg.term("Dead letter config unavailable");
+      return;
+    }
     try {
       await this.deadLetterConfig.onDeadLetter(info);
       msg.term("Dead letter processed");
@@ -1853,71 +2108,83 @@ var import_common10 = require("@nestjs/common");
 var import_nats9 = require("nats");
 var import_rxjs5 = require("rxjs");
 var RpcRouter = class {
-  constructor(messageProvider, patternRegistry, connection, codec, eventBus, timeout) {
+  constructor(messageProvider, patternRegistry, connection, codec, eventBus, rpcOptions, ackWaitMap) {
     this.messageProvider = messageProvider;
     this.patternRegistry = patternRegistry;
     this.connection = connection;
     this.codec = codec;
     this.eventBus = eventBus;
-    this.timeout = timeout ?? DEFAULT_JETSTREAM_RPC_TIMEOUT;
+    this.rpcOptions = rpcOptions;
+    this.ackWaitMap = ackWaitMap;
+    this.timeout = rpcOptions?.timeout ?? DEFAULT_JETSTREAM_RPC_TIMEOUT;
+    this.concurrency = rpcOptions?.concurrency;
   }
   logger = new import_common10.Logger("Jetstream:RpcRouter");
   timeout;
+  concurrency;
+  resolvedAckExtensionInterval;
   subscription = null;
+  cachedNc = null;
+  /** Lazily resolve the ack extension interval (needs ackWaitMap populated at runtime). */
+  get ackExtensionInterval() {
+    if (this.resolvedAckExtensionInterval !== void 0) return this.resolvedAckExtensionInterval;
+    this.resolvedAckExtensionInterval = resolveAckExtensionInterval(
+      this.rpcOptions?.ackExtension,
+      this.ackWaitMap?.get("cmd" /* Command */)
+    );
+    return this.resolvedAckExtensionInterval;
+  }
   /** Start routing command messages to handlers. */
-  start() {
-    this.subscription = this.messageProvider.commands$.pipe(
-      (0, import_rxjs5.mergeMap)(
-        (msg) => (0, import_rxjs5.defer)(() => this.handle(msg)).pipe(
-          (0, import_rxjs5.catchError)((err) => {
-            this.logger.error("Unexpected error in RPC router", err);
-            return import_rxjs5.EMPTY;
-          })
-        )
-      )
-    ).subscribe();
+  async start() {
+    this.cachedNc = await this.connection.getConnection();
+    this.subscription = this.messageProvider.commands$.pipe((0, import_rxjs5.mergeMap)((msg) => (0, import_rxjs5.from)(this.handleSafe(msg)), this.concurrency)).subscribe();
   }
   /** Stop routing and unsubscribe. */
   destroy() {
     this.subscription?.unsubscribe();
     this.subscription = null;
   }
-  /** Handle a single RPC command message. */
-  handle(msg) {
-    const handler = this.patternRegistry.getHandler(msg.subject);
-    if (!handler) {
-      msg.term(`No handler for RPC: ${msg.subject}`);
-      this.logger.error(`No handler for RPC subject: ${msg.subject}`);
-      return import_rxjs5.EMPTY;
-    }
-    const replyTo = msg.headers?.get("x-reply-to" /* ReplyTo */);
-    const correlationId = msg.headers?.get("x-correlation-id" /* CorrelationId */);
-    if (!replyTo || !correlationId) {
-      msg.term("Missing required headers (reply-to or correlation-id)");
-      this.logger.error(`Missing headers for RPC: ${msg.subject}`);
-      return import_rxjs5.EMPTY;
-    }
-    let data;
+  /** Handle a single RPC command message with error isolation. */
+  async handleSafe(msg) {
     try {
-      data = this.codec.decode(msg.data);
+      const handler = this.patternRegistry.getHandler(msg.subject);
+      if (!handler) {
+        msg.term(`No handler for RPC: ${msg.subject}`);
+        this.logger.error(`No handler for RPC subject: ${msg.subject}`);
+        return;
+      }
+      const { headers: msgHeaders } = msg;
+      const replyTo = msgHeaders?.get("x-reply-to" /* ReplyTo */);
+      const correlationId = msgHeaders?.get("x-correlation-id" /* CorrelationId */);
+      if (!replyTo || !correlationId) {
+        msg.term("Missing required headers (reply-to or correlation-id)");
+        this.logger.error(`Missing headers for RPC: ${msg.subject}`);
+        return;
+      }
+      let data;
+      try {
+        data = this.codec.decode(msg.data);
+      } catch (err) {
+        msg.term("Decode error");
+        this.logger.error(`Decode error for RPC ${msg.subject}:`, err);
+        return;
+      }
+      this.eventBus.emitMessageRouted(msg.subject, "rpc" /* Rpc */);
+      await this.executeHandler(handler, data, msg, replyTo, correlationId);
     } catch (err) {
-      msg.term("Decode error");
-      this.logger.error(`Decode error for RPC ${msg.subject}:`, err);
-      return import_rxjs5.EMPTY;
+      this.logger.error("Unexpected error in RPC router", err);
     }
-    this.eventBus.emit("messageRouted" /* MessageRouted */, msg.subject, "rpc");
-    return (0, import_rxjs5.from)(this.executeHandler(handler, data, msg, replyTo, correlationId));
   }
   /** Execute handler, publish response, settle message. */
   async executeHandler(handler, data, msg, replyTo, correlationId) {
-    const nc = await this.connection.getConnection();
+    const nc = this.cachedNc ?? await this.connection.getConnection();
     const ctx = new RpcContext([msg]);
-    const hdrs = (0, import_nats9.headers)();
-    hdrs.set("x-correlation-id" /* CorrelationId */, correlationId);
     let settled = false;
+    const stopAckExtension = startAckExtensionTimer(msg, this.ackExtensionInterval);
     const timeoutId = setTimeout(() => {
       if (settled) return;
       settled = true;
+      stopAckExtension?.();
       this.logger.error(`RPC timeout (${this.timeout}ms): ${msg.subject}`);
       this.eventBus.emit("rpcTimeout" /* RpcTimeout */, msg.subject, correlationId);
       msg.term("Handler timeout");
@@ -1927,8 +2194,11 @@ var RpcRouter = class {
       if (settled) return;
       settled = true;
       clearTimeout(timeoutId);
+      stopAckExtension?.();
       msg.ack();
       try {
+        const hdrs = (0, import_nats9.headers)();
+        hdrs.set("x-correlation-id" /* CorrelationId */, correlationId);
         nc.publish(replyTo, this.codec.encode(result), { headers: hdrs });
       } catch (publishErr) {
         this.logger.error(`Failed to publish RPC response for ${msg.subject}`, publishErr);
@@ -1937,7 +2207,10 @@ var RpcRouter = class {
       if (settled) return;
       settled = true;
       clearTimeout(timeoutId);
+      stopAckExtension?.();
       try {
+        const hdrs = (0, import_nats9.headers)();
+        hdrs.set("x-correlation-id" /* CorrelationId */, correlationId);
         hdrs.set("x-error" /* Error */, "true");
         nc.publish(replyTo, this.codec.encode(serializeError(err)), { headers: hdrs });
       } catch (encodeErr) {
@@ -1960,7 +2233,7 @@ var ShutdownManager = class {
   /**
    * Execute the full shutdown sequence.
    *
-   * @param strategy Optional strategy to close (stops consumers and subscriptions).
+   * @param strategy Optional stoppable to close (stops consumers and subscriptions).
    */
   async shutdown(strategy) {
     this.eventBus.emit("shutdownStart" /* ShutdownStart */);
@@ -1983,6 +2256,7 @@ var ShutdownManager = class {
 };
 
 // src/jetstream.module.ts
+var JETSTREAM_ACK_WAIT_MAP = /* @__PURE__ */ Symbol("JETSTREAM_ACK_WAIT_MAP");
 var JetstreamModule = class {
   constructor(shutdownManager, strategy) {
     this.shutdownManager = shutdownManager;
@@ -2167,13 +2441,26 @@ var JetstreamModule = class {
           return new ConsumerProvider(options, connection, streamProvider, patternRegistry);
         }
       },
+      // Shared ack_wait map — populated by strategy after ensureConsumers()
+      {
+        provide: JETSTREAM_ACK_WAIT_MAP,
+        useFactory: () => /* @__PURE__ */ new Map()
+      },
       // MessageProvider — pull-based message consumption
       {
         provide: MessageProvider,
         inject: [JETSTREAM_OPTIONS, JETSTREAM_CONNECTION, JETSTREAM_EVENT_BUS],
         useFactory: (options, connection, eventBus) => {
           if (options.consumer === false) return null;
-          return new MessageProvider(connection, eventBus);
+          const consumeOptionsMap = /* @__PURE__ */ new Map();
+          if (options.events?.consume)
+            consumeOptionsMap.set("ev" /* Event */, options.events.consume);
+          if (options.broadcast?.consume)
+            consumeOptionsMap.set("broadcast" /* Broadcast */, options.broadcast.consume);
+          if (options.rpc?.mode === "jetstream" && options.rpc.consume) {
+            consumeOptionsMap.set("cmd" /* Command */, options.rpc.consume);
+          }
+          return new MessageProvider(connection, eventBus, consumeOptionsMap);
         }
       },
       // EventRouter — routes event and broadcast messages to handlers
@@ -2184,20 +2471,33 @@ var JetstreamModule = class {
           MessageProvider,
           PatternRegistry,
           JETSTREAM_CODEC,
-          JETSTREAM_EVENT_BUS
+          JETSTREAM_EVENT_BUS,
+          JETSTREAM_ACK_WAIT_MAP
         ],
-        useFactory: (options, messageProvider, patternRegistry, codec, eventBus) => {
+        useFactory: (options, messageProvider, patternRegistry, codec, eventBus, ackWaitMap) => {
           if (options.consumer === false) return null;
           const deadLetterConfig = options.onDeadLetter ? {
             maxDeliverByStream: /* @__PURE__ */ new Map(),
             onDeadLetter: options.onDeadLetter
           } : void 0;
+          const processingConfig = {
+            events: {
+              concurrency: options.events?.concurrency,
+              ackExtension: options.events?.ackExtension
+            },
+            broadcast: {
+              concurrency: options.broadcast?.concurrency,
+              ackExtension: options.broadcast?.ackExtension
+            }
+          };
           return new EventRouter(
             messageProvider,
             patternRegistry,
             codec,
             eventBus,
-            deadLetterConfig
+            deadLetterConfig,
+            processingConfig,
+            ackWaitMap
           );
         }
       },
@@ -2210,18 +2510,24 @@ var JetstreamModule = class {
           PatternRegistry,
           JETSTREAM_CONNECTION,
           JETSTREAM_CODEC,
-          JETSTREAM_EVENT_BUS
+          JETSTREAM_EVENT_BUS,
+          JETSTREAM_ACK_WAIT_MAP
         ],
-        useFactory: (options, messageProvider, patternRegistry, connection, codec, eventBus) => {
+        useFactory: (options, messageProvider, patternRegistry, connection, codec, eventBus, ackWaitMap) => {
           if (options.consumer === false) return null;
-          const timeout = options.rpc?.mode === "jetstream" ? options.rpc.timeout : void 0;
+          const rpcOptions = options.rpc?.mode === "jetstream" ? {
+            timeout: options.rpc.timeout,
+            concurrency: options.rpc.concurrency,
+            ackExtension: options.rpc.ackExtension
+          } : void 0;
           return new RpcRouter(
             messageProvider,
             patternRegistry,
             connection,
             codec,
             eventBus,
-            timeout
+            rpcOptions,
+            ackWaitMap
           );
         }
       },
@@ -2252,9 +2558,10 @@ var JetstreamModule = class {
           MessageProvider,
           EventRouter,
           RpcRouter,
-          CoreRpcServer
+          CoreRpcServer,
+          JETSTREAM_ACK_WAIT_MAP
         ],
-        useFactory: (options, connection, patternRegistry, streamProvider, consumerProvider, messageProvider, eventRouter, rpcRouter, coreRpcServer) => {
+        useFactory: (options, connection, patternRegistry, streamProvider, consumerProvider, messageProvider, eventRouter, rpcRouter, coreRpcServer, ackWaitMap) => {
           if (options.consumer === false) return null;
           return new JetstreamStrategy(
             options,
@@ -2265,7 +2572,8 @@ var JetstreamModule = class {
             messageProvider,
             eventRouter,
             rpcRouter,
-            coreRpcServer
+            coreRpcServer,
+            ackWaitMap
           );
         }
       }
@@ -2346,8 +2654,13 @@ JetstreamModule = __decorateClass([
   JetstreamRecordBuilder,
   JetstreamStrategy,
   JsonCodec,
+  MessageKind,
+  PatternPrefix,
   RpcContext,
+  StreamKind,
   TransportEvent,
   getClientToken,
+  isCoreRpcMode,
+  isJetStreamRpcMode,
   toNanos
 });