@horizon-republic/nestjs-jetstream 2.8.0 → 2.9.1

package/dist/index.js

@@ -14,7 +14,7 @@ var __decorateParam = (index, decorator) => (target, key) => decorator(target, k
 import {
   Global,
   Inject,
-  Logger as Logger12,
+  Logger as Logger14,
   Module,
   Optional
 } from "@nestjs/common";
@@ -121,7 +121,7 @@ var DEFAULT_BROADCAST_STREAM_CONFIG = {
   max_msgs_per_subject: 1e6,
   max_msgs: 1e7,
   max_bytes: 2 * GB,
-  max_age: toNanos(1, "days"),
+  max_age: toNanos(1, "hours"),
   duplicate_window: toNanos(2, "minutes")
 };
 var DEFAULT_ORDERED_STREAM_CONFIG = {
@@ -136,6 +136,18 @@ var DEFAULT_ORDERED_STREAM_CONFIG = {
   max_age: toNanos(1, "days"),
   duplicate_window: toNanos(2, "minutes")
 };
+var DEFAULT_DLQ_STREAM_CONFIG = {
+  ...baseStreamConfig,
+  retention: RetentionPolicy.Workqueue,
+  allow_rollup_hdrs: false,
+  max_consumers: 100,
+  max_msg_size: 10 * MB,
+  max_msgs_per_subject: 5e6,
+  max_msgs: 5e7,
+  max_bytes: 5 * GB,
+  max_age: toNanos(30, "days"),
+  duplicate_window: toNanos(2, "minutes")
+};
 var DEFAULT_EVENT_CONSUMER_CONFIG = {
   ack_wait: toNanos(10, "seconds"),
   max_deliver: 3,
@@ -163,6 +175,12 @@ var DEFAULT_BROADCAST_CONSUMER_CONFIG = {
 var DEFAULT_RPC_TIMEOUT = 3e4;
 var DEFAULT_JETSTREAM_RPC_TIMEOUT = 18e4;
 var DEFAULT_SHUTDOWN_TIMEOUT = 1e4;
+var DEFAULT_METADATA_BUCKET = "handler_registry";
+var DEFAULT_METADATA_REPLICAS = 1;
+var DEFAULT_METADATA_HISTORY = 1;
+var DEFAULT_METADATA_TTL = 3e4;
+var MIN_METADATA_TTL = 5e3;
+var metadataKey = (serviceName, kind, pattern) => `${serviceName}.${kind}.${pattern}`;
 var JetstreamHeader = /* @__PURE__ */ ((JetstreamHeader2) => {
   JetstreamHeader2["CorrelationId"] = "x-correlation-id";
   JetstreamHeader2["ReplyTo"] = "x-reply-to";
@@ -171,6 +189,14 @@ var JetstreamHeader = /* @__PURE__ */ ((JetstreamHeader2) => {
   JetstreamHeader2["Error"] = "x-error";
   return JetstreamHeader2;
 })(JetstreamHeader || {});
+var JetstreamDlqHeader = /* @__PURE__ */ ((JetstreamDlqHeader2) => {
+  JetstreamDlqHeader2["DeadLetterReason"] = "x-dead-letter-reason";
+  JetstreamDlqHeader2["OriginalSubject"] = "x-original-subject";
+  JetstreamDlqHeader2["OriginalStream"] = "x-original-stream";
+  JetstreamDlqHeader2["FailedAt"] = "x-failed-at";
+  JetstreamDlqHeader2["DeliveryCount"] = "x-delivery-count";
+  return JetstreamDlqHeader2;
+})(JetstreamDlqHeader || {});
 var RESERVED_HEADERS = /* @__PURE__ */ new Set([
   "x-correlation-id" /* CorrelationId */,
   "x-reply-to" /* ReplyTo */,
@@ -183,6 +209,9 @@ var streamName = (serviceName, kind) => {
   if (kind === "broadcast" /* Broadcast */) return "broadcast-stream";
   return `${internalName(serviceName)}_${kind}-stream`;
 };
+var dlqStreamName = (serviceName) => {
+  return `${internalName(serviceName)}_dlq-stream`;
+};
 var consumerName = (serviceName, kind) => {
   if (kind === "broadcast" /* Broadcast */) return `${internalName(serviceName)}_broadcast-consumer`;
   return `${internalName(serviceName)}_${kind}-consumer`;
@@ -197,12 +226,13 @@ var isCoreRpcMode = (rpc) => !rpc || rpc.mode === "core";
 
 // src/client/jetstream.record.ts
 var JetstreamRecord = class {
-  constructor(data, headers2, timeout, messageId, schedule) {
+  constructor(data, headers2, timeout, messageId, schedule, ttl) {
     this.data = data;
     this.headers = headers2;
     this.timeout = timeout;
     this.messageId = messageId;
     this.schedule = schedule;
+    this.ttl = ttl;
   }
 };
 var JetstreamRecordBuilder = class {
@@ -211,6 +241,7 @@ var JetstreamRecordBuilder = class {
   timeout;
   messageId;
   scheduleOptions;
+  ttlDuration;
   constructor(data) {
     this.data = data;
   }
@@ -302,6 +333,33 @@ var JetstreamRecordBuilder = class {
     this.scheduleOptions = { at: new Date(ts) };
     return this;
   }
+  /**
+   * Set per-message TTL (time-to-live).
+   *
+   * The message expires individually after the specified duration,
+   * independent of the stream's `max_age`. Requires NATS >= 2.11 and
+   * `allow_msg_ttl: true` on the stream.
+   *
+   * Only meaningful for events (`client.emit()`). If used with RPC
+   * (`client.send()`), a warning is logged and the TTL is ignored.
+   *
+   * @param nanos - TTL in nanoseconds. Use {@link toNanos} for human-readable values.
+   *
+   * @example
+   * ```typescript
+   * import { toNanos } from '@horizon-republic/nestjs-jetstream';
+   *
+   * new JetstreamRecordBuilder(payload).ttl(toNanos(30, 'minutes')).build();
+   * new JetstreamRecordBuilder(payload).ttl(toNanos(24, 'hours')).build();
+   * ```
+   */
+  ttl(nanos) {
+    if (!Number.isFinite(nanos) || nanos <= 0) {
+      throw new Error("TTL must be a positive finite value");
+    }
+    this.ttlDuration = nanosToGoDuration(nanos);
+    return this;
+  }
   /**
    * Build the immutable {@link JetstreamRecord}.
    *
@@ -314,7 +372,8 @@ var JetstreamRecordBuilder = class {
       new Map(this.headers),
       this.timeout,
       this.messageId,
-      schedule
+      schedule,
+      this.ttlDuration
     );
   }
   /** Validate that a header key is not reserved. */
@@ -326,8 +385,20 @@ var JetstreamRecordBuilder = class {
     }
   }
 };
+var NS_PER_MS = 1e6;
+var NS_PER_S = 1e9;
+var NS_PER_M = 60 * NS_PER_S;
+var NS_PER_H = 60 * NS_PER_M;
+var nanosToGoDuration = (nanos) => {
+  if (nanos >= NS_PER_H && nanos % NS_PER_H === 0) return `${nanos / NS_PER_H}h`;
+  if (nanos >= NS_PER_M && nanos % NS_PER_M === 0) return `${nanos / NS_PER_M}m`;
+  if (nanos >= NS_PER_S && nanos % NS_PER_S === 0) return `${nanos / NS_PER_S}s`;
+  if (nanos >= NS_PER_MS && nanos % NS_PER_MS === 0) return `${nanos / NS_PER_MS}ms`;
+  return `${nanos}ns`;
+};
 
 // src/client/jetstream.client.ts
+var BROADCAST_SUBJECT_PREFIX = "broadcast.";
 var JetstreamClient = class extends ClientProxy {
   constructor(rootOptions, targetServiceName, connection, codec, eventBus) {
     super();
@@ -337,12 +408,33 @@ var JetstreamClient = class extends ClientProxy {
     this.eventBus = eventBus;
     this.targetName = targetServiceName;
     this.callerName = internalName(this.rootOptions.name);
+    const targetInternal = internalName(targetServiceName);
+    this.eventSubjectPrefix = `${targetInternal}.${"ev" /* Event */}.`;
+    this.commandSubjectPrefix = `${targetInternal}.${"cmd" /* Command */}.`;
+    this.orderedSubjectPrefix = `${targetInternal}.${"ordered" /* Ordered */}.`;
+    this.isCoreMode = isCoreRpcMode(this.rootOptions.rpc);
+    this.defaultRpcTimeout = isJetStreamRpcMode(this.rootOptions.rpc) ? this.rootOptions.rpc?.timeout ?? DEFAULT_JETSTREAM_RPC_TIMEOUT : this.rootOptions.rpc?.timeout ?? DEFAULT_RPC_TIMEOUT;
   }
   logger = new 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;
+  /**
+   * Subject prefixes of the form `{serviceName}__microservice.{kind}.` — one
+   * per stream kind this client may publish to. Built once in the constructor
+   * so producing a full subject is a single string concat with the user pattern.
+   */
+  eventSubjectPrefix;
+  commandSubjectPrefix;
+  orderedSubjectPrefix;
+  /**
+   * RPC configuration snapshots. The values are derived from rootOptions at
+   * construction time so the publish hot path never has to re-run
+   * isCoreRpcMode / getRpcTimeout on every call.
+   */
+  isCoreMode;
+  defaultRpcTimeout;
   /** Shared inbox for JetStream-mode RPC responses. */
   inbox = null;
   inboxSubscription = null;
@@ -352,6 +444,12 @@ var JetstreamClient = class extends ClientProxy {
   pendingTimeouts = /* @__PURE__ */ new Map();
   /** Subscription to connection status events for disconnect handling. */
   statusSubscription = null;
+  /**
+   * Cached readiness flag. Once `connect()` has wired the inbox and status
+   * subscription, subsequent publishes skip the `await connect()` microtask
+   * and reach for the underlying connection synchronously instead.
+   */
+  readyForPublish = false;
   /**
    * Establish connection. Called automatically by NestJS on first use.
    *
@@ -362,7 +460,7 @@ var JetstreamClient = class extends ClientProxy {
    */
   async connect() {
     const nc = await this.connection.getConnection();
-    if (isJetStreamRpcMode(this.rootOptions.rpc) && !this.inboxSubscription) {
+    if (!this.isCoreMode && !this.inboxSubscription) {
       this.setupInbox(nc);
     }
     this.statusSubscription ??= this.connection.status$.subscribe((status) => {
@@ -370,12 +468,14 @@ var JetstreamClient = class extends ClientProxy {
         this.handleDisconnect();
       }
     });
+    this.readyForPublish = true;
     return nc;
   }
   /** Clean up resources: reject pending RPCs, unsubscribe from status events. */
   async close() {
     this.statusSubscription?.unsubscribe();
     this.statusSubscription = null;
+    this.readyForPublish = false;
     this.rejectPendingRpcs(new Error("Client closed"));
   }
   /**
@@ -399,8 +499,8 @@ var JetstreamClient = class extends ClientProxy {
    * set to the original event subject.
    */
   async dispatchEvent(packet) {
-    await this.connect();
-    const { data, hdrs, messageId, schedule } = this.extractRecordData(packet.data);
+    if (!this.readyForPublish) await this.connect();
+    const { data, hdrs, messageId, schedule, ttl } = this.extractRecordData(packet.data);
     const eventSubject = this.buildEventSubject(packet.pattern);
     const msgHeaders = this.buildHeaders(hdrs, { subject: eventSubject });
     if (schedule) {
@@ -408,6 +508,7 @@ var JetstreamClient = class extends ClientProxy {
       const ack = await this.connection.getJetStreamClient().publish(scheduleSubject, this.codec.encode(data), {
         headers: msgHeaders,
         msgID: messageId ?? nuid.next(),
+        ttl,
         schedule: {
           specification: schedule.at,
           target: eventSubject
@@ -421,7 +522,8 @@ var JetstreamClient = class extends ClientProxy {
     } else {
       const ack = await this.connection.getJetStreamClient().publish(eventSubject, this.codec.encode(data), {
         headers: msgHeaders,
-        msgID: messageId ?? nuid.next()
+        msgID: messageId ?? nuid.next(),
+        ttl
       });
       if (ack.duplicate) {
         this.logger.warn(`Duplicate event publish detected: ${eventSubject} (seq: ${ack.seq})`);
@@ -436,19 +538,24 @@ var JetstreamClient = class extends ClientProxy {
    * JetStream mode: publishes to stream + waits for inbox response.
    */
   publish(packet, callback) {
-    const subject = buildSubject(this.targetName, "cmd" /* Command */, packet.pattern);
-    const { data, hdrs, timeout, messageId, schedule } = this.extractRecordData(packet.data);
+    const subject = this.commandSubjectPrefix + packet.pattern;
+    const { data, hdrs, timeout, messageId, schedule, ttl } = this.extractRecordData(packet.data);
     if (schedule) {
       this.logger.warn(
         "scheduleAt() is ignored for RPC (client.send()). Use client.emit() for scheduled events."
       );
     }
+    if (ttl) {
+      this.logger.warn(
+        "ttl() is ignored for RPC (client.send()). Use client.emit() for events with TTL."
+      );
+    }
     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 (isCoreRpcMode(this.rootOptions.rpc)) {
+    if (this.isCoreMode) {
       this.publishCoreRpc(subject, data, hdrs, timeout, callback).catch(onUnhandled);
     } else {
       jetStreamCorrelationId = nuid.next();
@@ -473,8 +580,8 @@ var JetstreamClient = class extends ClientProxy {
   /** Core mode: nc.request() with timeout. */
   async publishCoreRpc(subject, data, customHeaders, timeout, callback) {
     try {
-      const nc = await this.connect();
-      const effectiveTimeout = timeout ?? this.getRpcTimeout();
+      const nc = this.readyForPublish ? this.connection.unwrap : await this.connect();
+      const effectiveTimeout = timeout ?? this.defaultRpcTimeout;
       const hdrs = this.buildHeaders(customHeaders, { subject });
       const response = await nc.request(subject, this.codec.encode(data), {
         timeout: effectiveTimeout,
@@ -496,10 +603,10 @@ var JetstreamClient = class extends ClientProxy {
   /** JetStream mode: publish to stream + wait for inbox response. */
   async publishJetStreamRpc(subject, data, callback, options) {
     const { headers: customHeaders, correlationId, messageId } = options;
-    const effectiveTimeout = options.timeout ?? this.getRpcTimeout();
+    const effectiveTimeout = options.timeout ?? this.defaultRpcTimeout;
     this.pendingMessages.set(correlationId, callback);
     try {
-      await this.connect();
+      if (!this.readyForPublish) await this.connect();
       if (!this.pendingMessages.has(correlationId)) return;
       if (!this.inbox) {
         this.pendingMessages.delete(correlationId);
@@ -545,6 +652,7 @@ var JetstreamClient = class extends ClientProxy {
   handleDisconnect() {
     this.rejectPendingRpcs(new Error("Connection lost"));
     this.inbox = null;
+    this.readyForPublish = false;
   }
   /** Reject all pending RPC callbacks, clear timeouts, and tear down inbox. */
   rejectPendingRpcs(error) {
@@ -558,6 +666,7 @@ var JetstreamClient = class extends ClientProxy {
     this.pendingTimeouts.clear();
     this.inboxSubscription?.unsubscribe();
     this.inboxSubscription = null;
+    this.inbox = null;
   }
   /** Setup shared inbox subscription for JetStream RPC responses. */
   setupInbox(nc) {
@@ -607,19 +716,22 @@ var JetstreamClient = class extends ClientProxy {
       this.pendingMessages.delete(correlationId);
     }
   }
-  /** Build event subject — workqueue, broadcast, or ordered. */
+  /**
+   * Resolve a user pattern to a fully-qualified NATS subject, dispatching
+   * between the event, broadcast, and ordered prefixes.
+   *
+   * The leading-char check short-circuits the `startsWith` comparisons for
+   * patterns that cannot possibly carry a broadcast/ordered marker, which is
+   * the overwhelmingly common case.
+   */
   buildEventSubject(pattern) {
-    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)
-      );
+    if (pattern.charCodeAt(0) === 98 && pattern.startsWith("broadcast:" /* Broadcast */)) {
+      return BROADCAST_SUBJECT_PREFIX + pattern.slice("broadcast:" /* Broadcast */.length);
+    }
+    if (pattern.charCodeAt(0) === 111 && pattern.startsWith("ordered:" /* Ordered */)) {
+      return this.orderedSubjectPrefix + pattern.slice("ordered:" /* Ordered */.length);
     }
-    return buildSubject(this.targetName, "ev" /* Event */, pattern);
+    return this.eventSubjectPrefix + pattern;
   }
   /** Build NATS headers merging custom headers with transport headers. */
   buildHeaders(customHeaders, transport) {
@@ -644,10 +756,11 @@ var JetstreamClient = class extends ClientProxy {
     if (rawData instanceof JetstreamRecord) {
       return {
         data: rawData.data,
-        hdrs: rawData.headers.size > 0 ? new Map(rawData.headers) : null,
+        hdrs: rawData.headers.size > 0 ? rawData.headers : null,
         timeout: rawData.timeout,
         messageId: rawData.messageId,
-        schedule: rawData.schedule
+        schedule: rawData.schedule,
+        ttl: rawData.ttl
       };
     }
     return {
@@ -655,7 +768,8 @@ var JetstreamClient = class extends ClientProxy {
       hdrs: null,
       timeout: void 0,
       messageId: void 0,
-      schedule: void 0
+      schedule: void 0,
+      ttl: void 0
     };
   }
   /**
@@ -685,11 +799,6 @@ var JetstreamClient = class extends ClientProxy {
     const pattern = withoutPrefix.slice(dotIndex + 1);
     return `${targetPrefix}_sch.${pattern}`;
   }
-  getRpcTimeout() {
-    if (!this.rootOptions.rpc) return DEFAULT_RPC_TIMEOUT;
-    const defaultTimeout = isJetStreamRpcMode(this.rootOptions.rpc) ? DEFAULT_JETSTREAM_RPC_TIMEOUT : DEFAULT_RPC_TIMEOUT;
-    return this.rootOptions.rpc.timeout ?? defaultTimeout;
-  }
 };
 
 // src/codec/json.codec.ts
@@ -704,6 +813,19 @@ var JsonCodec = class {
   }
 };
 
+// src/codec/msgpack.codec.ts
+var MsgpackCodec = class {
+  constructor(packr) {
+    this.packr = packr;
+  }
+  encode(data) {
+    return this.packr.pack(data);
+  }
+  decode(data) {
+    return this.packr.unpack(data);
+  }
+};
+
 // src/connection/connection.provider.ts
 import { Logger as Logger2 } from "@nestjs/common";
 import {
@@ -921,6 +1043,15 @@ var EventBus = class {
       kind
     );
   }
+  /**
+   * Check whether a hook is registered for the given event.
+   *
+   * Used by the routing hot path to elide the emit call entirely when the
+   * transport owner did not register a listener.
+   */
+  hasHook(event) {
+    return this.hooks[event] !== void 0;
+  }
   callHook(event, hook, ...args) {
     try {
       const result = hook(...args);
@@ -975,9 +1106,14 @@ var JetstreamHealthIndicator = class {
    * Returns `{ [key]: { status: 'up', ... } }` on success.
    * Throws an error with `{ [key]: { status: 'down', ... } }` on failure.
    *
+   * The thrown error sets `isHealthCheckError: true` and `causes` — the
+   * duck-type contract that Terminus `HealthCheckExecutor` uses to distinguish
+   * health failures from unexpected exceptions. Works with both Terminus v10
+   * (`instanceof HealthCheckError`) and v11+ (`error?.isHealthCheckError`).
+   *
    * @param key - Health indicator key (default: `'jetstream'`).
    * @returns Object with status, server, and latency under the given key.
-   * @throws Error with `{ [key]: { status: 'down' } }` when disconnected.
+   * @throws Error with `isHealthCheckError`, `causes`, and `{ [key]: { status: 'down' } }`.
    */
   async isHealthy(key = "jetstream") {
     const status = await this.check();
@@ -987,8 +1123,10 @@ var JetstreamHealthIndicator = class {
       latency: status.latency
     };
     if (!status.connected) {
+      const causes = { [key]: details };
       throw Object.assign(new Error("Jetstream health check failed"), {
-        [key]: details
+        causes,
+        isHealthCheckError: true
       });
     }
     return { [key]: details };
@@ -1001,7 +1139,7 @@ JetstreamHealthIndicator = __decorateClass([
 // src/server/strategy.ts
 import { Server } from "@nestjs/microservices";
 var JetstreamStrategy = class extends Server {
-  constructor(options, connection, patternRegistry, streamProvider, consumerProvider, messageProvider, eventRouter, rpcRouter, coreRpcServer, ackWaitMap = /* @__PURE__ */ new Map()) {
+  constructor(options, connection, patternRegistry, streamProvider, consumerProvider, messageProvider, eventRouter, rpcRouter, coreRpcServer, ackWaitMap = /* @__PURE__ */ new Map(), metadataProvider) {
     super();
     this.options = options;
     this.connection = connection;
@@ -1013,6 +1151,7 @@ var JetstreamStrategy = class extends Server {
     this.rpcRouter = rpcRouter;
     this.coreRpcServer = coreRpcServer;
     this.ackWaitMap = ackWaitMap;
+    this.metadataProvider = metadataProvider;
   }
   transportId = /* @__PURE__ */ Symbol("jetstream-transport");
   // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
@@ -1057,10 +1196,14 @@ var JetstreamStrategy = class extends Server {
     if (isCoreRpcMode(this.options.rpc) && this.patternRegistry.hasRpcHandlers()) {
       await this.coreRpcServer.start();
     }
+    if (this.metadataProvider && this.patternRegistry.hasMetadata()) {
+      await this.metadataProvider.publish(this.patternRegistry.getMetadataEntries());
+    }
     callback();
   }
-  /** Stop all consumers, routers, and subscriptions. Called during shutdown. */
+  /** Stop all consumers, routers, subscriptions, and metadata heartbeat. Called during shutdown. */
   close() {
+    this.metadataProvider?.destroy();
     this.eventRouter.destroy();
     this.rpcRouter.destroy();
     this.coreRpcServer.stop();
@@ -1291,16 +1434,71 @@ var resolveAckExtensionInterval = (config, ackWaitNanos) => {
   const interval = Math.floor(ackWaitNanos / 1e6 / 2);
   return Math.max(interval, MIN_ACK_EXTENSION_INTERVAL);
 };
+var AckExtensionPool = class {
+  entries = /* @__PURE__ */ new Set();
+  handle = null;
+  handleFireAt = 0;
+  schedule(msg, interval) {
+    const entry = {
+      msg,
+      interval,
+      nextFireAt: Date.now() + interval,
+      active: true
+    };
+    this.entries.add(entry);
+    this.ensureWake(entry.nextFireAt);
+    return entry;
+  }
+  cancel(entry) {
+    if (!entry.active) return;
+    entry.active = false;
+    this.entries.delete(entry);
+    if (this.entries.size === 0 && this.handle !== null) {
+      clearTimeout(this.handle);
+      this.handle = null;
+      this.handleFireAt = 0;
+    }
+  }
+  /**
+   * Ensure the shared timer will fire no later than `dueAt`. If an earlier
+   * wake is already scheduled, leave it; otherwise replace it with a tighter one.
+   */
+  ensureWake(dueAt) {
+    if (this.handle !== null && this.handleFireAt <= dueAt) return;
+    if (this.handle !== null) clearTimeout(this.handle);
+    const delay = Math.max(0, dueAt - Date.now());
+    const handle = setTimeout(() => {
+      this.tick();
+    }, delay);
+    if (typeof handle.unref === "function") handle.unref();
+    this.handle = handle;
+    this.handleFireAt = dueAt;
+  }
+  tick() {
+    this.handle = null;
+    this.handleFireAt = 0;
+    const now = Date.now();
+    let earliest = Infinity;
+    for (const entry of this.entries) {
+      if (!entry.active) continue;
+      if (entry.nextFireAt <= now) {
+        try {
+          entry.msg.working();
+        } catch {
+        }
+        entry.nextFireAt = now + entry.interval;
+      }
+      if (entry.nextFireAt < earliest) earliest = entry.nextFireAt;
+    }
+    if (earliest !== Infinity) this.ensureWake(earliest);
+  }
+};
+var pool = new AckExtensionPool();
 var startAckExtensionTimer = (msg, interval) => {
   if (interval === null || interval <= 0) return null;
-  const timer2 = setInterval(() => {
-    try {
-      msg.working();
-    } catch {
-    }
-  }, interval);
+  const entry = pool.schedule(msg, interval);
   return () => {
-    clearInterval(timer2);
+    pool.cancel(entry);
   };
 };
 
@@ -1314,11 +1512,8 @@ var serializeError = (err) => {
 
 // src/utils/unwrap-result.ts
 import { isObservable } from "rxjs";
-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 (result === void 0 || result === null) return result;
   if (isObservable(result)) {
     return subscribeToFirst(result);
   }
@@ -1327,8 +1522,9 @@ var unwrapResult = (result) => {
       (resolved) => isObservable(resolved) ? subscribeToFirst(resolved) : resolved
     );
   }
-  return Promise.resolve(result);
+  return result;
 };
+var isPromiseLike = (value) => value !== null && typeof value === "object" && typeof value.then === "function";
 var subscribeToFirst = (obs) => new Promise((resolve, reject) => {
   let done = false;
   let subscription = null;
@@ -1416,7 +1612,8 @@ var CoreRpcServer = class {
     }
     const ctx = new RpcContext([msg]);
     try {
-      const result = await unwrapResult(handler(data, ctx));
+      const raw = unwrapResult(handler(data, ctx));
+      const result = isPromiseLike(raw) ? await raw : raw;
       msg.respond(this.codec.encode(result));
     } catch (err) {
       this.logger.error(`Handler error for Core RPC ${msg.subject}:`, err);
@@ -1436,24 +1633,180 @@ var CoreRpcServer = class {
 };
 
 // src/server/infrastructure/stream.provider.ts
+import { Logger as Logger6 } from "@nestjs/common";
+import { JetStreamApiError as JetStreamApiError2 } from "@nats-io/jetstream";
+
+// src/server/infrastructure/nats-error-codes.ts
+var NatsErrorCode = /* @__PURE__ */ ((NatsErrorCode2) => {
+  NatsErrorCode2[NatsErrorCode2["ConsumerNotFound"] = 10014] = "ConsumerNotFound";
+  NatsErrorCode2[NatsErrorCode2["ConsumerAlreadyExists"] = 10148] = "ConsumerAlreadyExists";
+  NatsErrorCode2[NatsErrorCode2["StreamNotFound"] = 10059] = "StreamNotFound";
+  return NatsErrorCode2;
+})(NatsErrorCode || {});
+
+// src/server/infrastructure/stream-config-diff.ts
+var TRANSPORT_CONTROLLED_PROPERTIES = /* @__PURE__ */ new Set([
+  "retention"
+]);
+var IMMUTABLE_PROPERTIES = /* @__PURE__ */ new Set([
+  "storage"
+]);
+var ENABLE_ONLY_PROPERTIES = /* @__PURE__ */ new Set([
+  "allow_msg_schedules",
+  "allow_msg_ttl",
+  "deny_delete",
+  "deny_purge"
+]);
+var compareStreamConfig = (current, desired) => {
+  const changes = [];
+  for (const key of Object.keys(desired)) {
+    const currentVal = current[key];
+    const desiredVal = desired[key];
+    if (isEqual(currentVal, desiredVal)) continue;
+    changes.push({
+      property: key,
+      current: currentVal,
+      desired: desiredVal,
+      mutability: classifyMutability(key, currentVal, desiredVal)
+    });
+  }
+  const hasImmutableChanges = changes.some((c) => c.mutability === "immutable");
+  const hasMutableChanges = changes.some(
+    (c) => c.mutability === "mutable" || c.mutability === "enable-only"
+  );
+  const hasTransportControlledConflicts = changes.some(
+    (c) => c.mutability === "transport-controlled"
+  );
+  return {
+    hasChanges: changes.length > 0,
+    hasMutableChanges,
+    hasImmutableChanges,
+    hasTransportControlledConflicts,
+    changes
+  };
+};
+var classifyMutability = (key, current, desired) => {
+  if (TRANSPORT_CONTROLLED_PROPERTIES.has(key)) return "transport-controlled";
+  if (IMMUTABLE_PROPERTIES.has(key)) return "immutable";
+  if (ENABLE_ONLY_PROPERTIES.has(key)) {
+    return current === true && desired === false ? "immutable" : "enable-only";
+  }
+  return "mutable";
+};
+var isEqual = (a, b) => {
+  if (a === b) return true;
+  if (a == null && b == null) return true;
+  return JSON.stringify(a) === JSON.stringify(b);
+};
+
+// src/server/infrastructure/stream-migration.ts
 import { Logger as Logger5 } from "@nestjs/common";
 import { JetStreamApiError } from "@nats-io/jetstream";
-var STREAM_NOT_FOUND = 10059;
+var MIGRATION_BACKUP_SUFFIX = "__migration_backup";
+var DEFAULT_SOURCING_TIMEOUT_MS = 3e4;
+var SOURCING_POLL_INTERVAL_MS = 100;
+var StreamMigration = class {
+  constructor(sourcingTimeoutMs = DEFAULT_SOURCING_TIMEOUT_MS) {
+    this.sourcingTimeoutMs = sourcingTimeoutMs;
+  }
+  logger = new Logger5("Jetstream:Stream");
+  async migrate(jsm, streamName2, newConfig) {
+    const backupName = `${streamName2}${MIGRATION_BACKUP_SUFFIX}`;
+    const startTime = Date.now();
+    const currentInfo = await jsm.streams.info(streamName2);
+    await this.cleanupOrphanedBackup(jsm, backupName);
+    const messageCount = currentInfo.state.messages;
+    this.logger.log(`Stream ${streamName2}: destructive migration started`);
+    let originalDeleted = false;
+    try {
+      if (messageCount > 0) {
+        this.logger.log(`  Phase 1/4: Backing up ${messageCount} messages \u2192 ${backupName}`);
+        await jsm.streams.add({
+          ...currentInfo.config,
+          name: backupName,
+          subjects: [],
+          sources: [{ name: streamName2 }]
+        });
+        await this.waitForSourcing(jsm, backupName, messageCount);
+      }
+      this.logger.log(`  Phase 2/4: Deleting old stream`);
+      await jsm.streams.delete(streamName2);
+      originalDeleted = true;
+      this.logger.log(`  Phase 3/4: Creating stream with new config`);
+      await jsm.streams.add(newConfig);
+      if (messageCount > 0) {
+        const backupInfo = await jsm.streams.info(backupName);
+        await jsm.streams.update(backupName, { ...backupInfo.config, sources: [] });
+        this.logger.log(`  Phase 4/4: Restoring ${messageCount} messages from backup`);
+        await jsm.streams.update(streamName2, {
+          ...newConfig,
+          sources: [{ name: backupName }]
+        });
+        await this.waitForSourcing(jsm, streamName2, messageCount);
+        await jsm.streams.update(streamName2, { ...newConfig, sources: [] });
+        await jsm.streams.delete(backupName);
+      }
+    } catch (err) {
+      if (originalDeleted && messageCount > 0) {
+        this.logger.error(
+          `Migration failed after deleting original stream. Backup ${backupName} preserved for manual recovery.`
+        );
+      } else {
+        await this.cleanupOrphanedBackup(jsm, backupName);
+      }
+      throw err;
+    }
+    const durationMs = Date.now() - startTime;
+    this.logger.log(
+      `Stream ${streamName2}: migration complete (${messageCount} messages preserved, took ${(durationMs / 1e3).toFixed(1)}s)`
+    );
+  }
+  async waitForSourcing(jsm, streamName2, expectedCount) {
+    const deadline = Date.now() + this.sourcingTimeoutMs;
+    while (Date.now() < deadline) {
+      const info = await jsm.streams.info(streamName2);
+      if (info.state.messages >= expectedCount) return;
+      await new Promise((r) => setTimeout(r, SOURCING_POLL_INTERVAL_MS));
+    }
+    throw new Error(
+      `Stream sourcing timeout: ${streamName2} has not reached ${expectedCount} messages within ${this.sourcingTimeoutMs / 1e3}s`
+    );
+  }
+  async cleanupOrphanedBackup(jsm, backupName) {
+    try {
+      await jsm.streams.info(backupName);
+      this.logger.warn(`Found orphaned migration backup stream: ${backupName}, cleaning up`);
+      await jsm.streams.delete(backupName);
+    } catch (err) {
+      if (err instanceof JetStreamApiError && err.apiError().err_code === 10059 /* StreamNotFound */) {
+        return;
+      }
+      throw err;
+    }
+  }
+};
+
+// src/server/infrastructure/stream.provider.ts
 var StreamProvider = class {
   constructor(options, connection) {
     this.options = options;
     this.connection = connection;
   }
-  logger = new Logger5("Jetstream:Stream");
+  logger = new Logger6("Jetstream:Stream");
+  migration = new StreamMigration();
   /**
    * Ensure all required streams exist with correct configuration.
    *
    * @param kinds Which stream kinds to create. Determined by the module based
    *              on RPC mode and registered handler patterns.
+   * If the dlq option is enabled, also ensures the DLQ stream exists.
    */
   async ensureStreams(kinds) {
     const jsm = await this.connection.getJetStreamManager();
     await Promise.all(kinds.map((kind) => this.ensureStream(jsm, kind)));
+    if (this.options.dlq) {
+      await this.ensureDlqStream(jsm);
+    }
   }
   /** Get the stream name for a given kind. */
   getStreamName(kind) {
@@ -1488,17 +1841,85 @@ var StreamProvider = class {
     const config = this.buildConfig(kind);
     this.logger.log(`Ensuring stream: ${config.name}`);
     try {
-      await jsm.streams.info(config.name);
-      this.logger.debug(`Stream exists, updating: ${config.name}`);
-      return await jsm.streams.update(config.name, config);
+      const currentInfo = await jsm.streams.info(config.name);
+      return await this.handleExistingStream(jsm, currentInfo, config);
     } catch (err) {
-      if (err instanceof JetStreamApiError && err.apiError().err_code === STREAM_NOT_FOUND) {
+      if (err instanceof JetStreamApiError2 && err.apiError().err_code === 10059 /* StreamNotFound */) {
         this.logger.log(`Creating stream: ${config.name}`);
         return await jsm.streams.add(config);
       }
       throw err;
     }
   }
+  /** Ensure a dead-letter queue stream exists, creating or updating as needed. */
+  async ensureDlqStream(jsm) {
+    const config = this.buildDlqConfig();
+    this.logger.log(`Ensuring DLQ stream: ${config.name}`);
+    try {
+      const currentInfo = await jsm.streams.info(config.name);
+      return await this.handleExistingStream(jsm, currentInfo, config);
+    } catch (err) {
+      if (err instanceof JetStreamApiError2 && err.apiError().err_code === 10059 /* StreamNotFound */) {
+        this.logger.log(`Creating DLQ stream: ${config.name}`);
+        return await jsm.streams.add(config);
+      }
+      throw err;
+    }
+  }
+  async handleExistingStream(jsm, currentInfo, config) {
+    const diff = compareStreamConfig(currentInfo.config, config);
+    if (!diff.hasChanges) {
+      this.logger.debug(`Stream ${config.name}: no config changes`);
+      return currentInfo;
+    }
+    this.logChanges(config.name, diff, !!this.options.allowDestructiveMigration);
+    if (diff.hasTransportControlledConflicts) {
+      const conflicts = diff.changes.filter((c) => c.mutability === "transport-controlled").map((c) => `${c.property}: ${JSON.stringify(c.current)} \u2192 ${JSON.stringify(c.desired)}`).join(", ");
+      throw new Error(
+        `Stream ${config.name} has transport-controlled config conflicts that cannot be migrated: ${conflicts}. The retention policy is managed by the transport and must match the stream kind.`
+      );
+    }
+    if (!diff.hasImmutableChanges) {
+      this.logger.debug(`Stream exists, updating: ${config.name}`);
+      return await jsm.streams.update(config.name, config);
+    }
+    if (!this.options.allowDestructiveMigration) {
+      this.logger.warn(
+        `Stream ${config.name} has immutable config conflicts. Enable allowDestructiveMigration to recreate the stream.`
+      );
+      if (diff.hasMutableChanges) {
+        const mutableConfig = this.buildMutableOnlyConfig(config, currentInfo.config, diff);
+        return await jsm.streams.update(config.name, mutableConfig);
+      }
+      return currentInfo;
+    }
+    await this.migration.migrate(jsm, config.name, config);
+    return await jsm.streams.info(config.name);
+  }
+  buildMutableOnlyConfig(config, currentConfig, diff) {
+    const nonMutableKeys = new Set(
+      diff.changes.filter((c) => c.mutability === "immutable" || c.mutability === "transport-controlled").map((c) => c.property)
+    );
+    const filtered = { ...config };
+    for (const key of nonMutableKeys) {
+      filtered[key] = currentConfig[key];
+    }
+    return filtered;
+  }
+  logChanges(streamName2, diff, migrationEnabled) {
+    for (const c of diff.changes) {
+      const detail = `${c.property}: ${JSON.stringify(c.current)} \u2192 ${JSON.stringify(c.desired)}`;
+      if (c.mutability === "transport-controlled") {
+        this.logger.error(
+          `Stream ${streamName2}: ${detail} \u2014 transport-controlled, cannot be changed`
+        );
+      } else if (c.mutability === "immutable" && !migrationEnabled) {
+        this.logger.warn(`Stream ${streamName2}: ${detail} \u2014 requires allowDestructiveMigration`);
+      } else {
+        this.logger.log(`Stream ${streamName2}: ${detail}`);
+      }
+    }
+  }
   /** Build the full stream config by merging defaults with user overrides. */
   buildConfig(kind) {
     const name = this.getStreamName(kind);
@@ -1514,6 +1935,26 @@ var StreamProvider = class {
       description
     };
   }
+  /**
+   * Build the stream configuration for the Dead-Letter Queue (DLQ).
+   *
+   * Merges the library default DLQ config with user-provided overrides.
+   * Ensures transport-controlled settings like retention are safely decoupled.
+   */
+  buildDlqConfig() {
+    const name = dlqStreamName(this.options.name);
+    const subjects = [name];
+    const description = `JetStream DLQ stream for ${this.options.name}`;
+    const overrides = this.options.dlq?.stream ?? {};
+    const safeOverrides = this.stripTransportControlled(overrides);
+    return {
+      ...DEFAULT_DLQ_STREAM_CONFIG,
+      ...safeOverrides,
+      name,
+      subjects,
+      description
+    };
+  }
   /** Get default config for a stream kind. */
   getDefaults(kind) {
     switch (kind) {
@@ -1532,25 +1973,44 @@ var StreamProvider = class {
     const overrides = this.getOverrides(kind);
     return overrides.allow_msg_schedules === true;
   }
-  /** Get user-provided overrides for a stream kind. */
+  /** Get user-provided overrides for a stream kind, stripping transport-controlled properties. */
   getOverrides(kind) {
+    let overrides;
     switch (kind) {
       case "ev" /* Event */:
-        return this.options.events?.stream ?? {};
+        overrides = this.options.events?.stream ?? {};
+        break;
       case "cmd" /* Command */:
-        return this.options.rpc?.mode === "jetstream" ? this.options.rpc.stream ?? {} : {};
+        overrides = this.options.rpc?.mode === "jetstream" ? this.options.rpc.stream ?? {} : {};
+        break;
       case "broadcast" /* Broadcast */:
-        return this.options.broadcast?.stream ?? {};
+        overrides = this.options.broadcast?.stream ?? {};
+        break;
       case "ordered" /* Ordered */:
-        return this.options.ordered?.stream ?? {};
+        overrides = this.options.ordered?.stream ?? {};
+        break;
     }
+    return this.stripTransportControlled(overrides);
+  }
+  /**
+   * Remove transport-controlled properties from user overrides.
+   * `retention` is managed by the transport (Workqueue/Limits per stream kind)
+   * and silently stripped to protect users from misconfiguration.
+   */
+  stripTransportControlled(overrides) {
+    if (!("retention" in overrides)) return overrides;
+    this.logger.debug(
+      "Stripping user-provided retention override \u2014 retention is managed by the transport"
+    );
+    const cleaned = { ...overrides };
+    delete cleaned.retention;
+    return cleaned;
   }
 };
 
 // src/server/infrastructure/consumer.provider.ts
-import { Logger as Logger6 } from "@nestjs/common";
-import { JetStreamApiError as JetStreamApiError2 } from "@nats-io/jetstream";
-var CONSUMER_NOT_FOUND = 10014;
+import { Logger as Logger7 } from "@nestjs/common";
+import { JetStreamApiError as JetStreamApiError3 } from "@nats-io/jetstream";
 var ConsumerProvider = class {
   constructor(options, connection, streamProvider, patternRegistry) {
     this.options = options;
@@ -1558,7 +2018,7 @@ var ConsumerProvider = class {
     this.streamProvider = streamProvider;
     this.patternRegistry = patternRegistry;
   }
-  logger = new Logger6("Jetstream:Consumer");
+  logger = new Logger7("Jetstream:Consumer");
   /**
    * Ensure consumers exist for the specified kinds.
    *
@@ -1579,7 +2039,11 @@ var ConsumerProvider = class {
   getConsumerName(kind) {
     return consumerName(this.options.name, kind);
   }
-  /** Ensure a single consumer exists, creating if needed. */
+  /**
+   * Ensure a single consumer exists with the desired config.
+   * Used at **startup** — creates or updates the consumer to match
+   * the current pod's configuration.
+   */
   async ensureConsumer(jsm, kind) {
     const stream = this.streamProvider.getStreamName(kind);
     const config = this.buildConfig(kind);
@@ -1590,13 +2054,74 @@ var ConsumerProvider = class {
       this.logger.debug(`Consumer exists, updating: ${name}`);
       return await jsm.consumers.update(stream, name, config);
     } catch (err) {
-      if (err instanceof JetStreamApiError2 && err.apiError().err_code === CONSUMER_NOT_FOUND) {
-        this.logger.log(`Creating consumer: ${name}`);
-        return await jsm.consumers.add(stream, config);
+      if (!(err instanceof JetStreamApiError3) || err.apiError().err_code !== 10014 /* ConsumerNotFound */) {
+        throw err;
+      }
+      return await this.createConsumer(jsm, stream, name, config);
+    }
+  }
+  /**
+   * Recover a consumer that disappeared during runtime.
+   * Used by **self-healing** — creates if missing, but NEVER updates config.
+   *
+   * If a migration backup stream exists, another pod is mid-migration — we
+   * throw so the self-healing retry loop waits with backoff until migration
+   * completes and the backup is cleaned up.
+   *
+   * This prevents old pods from:
+   * - Overwriting a newer pod's consumer config during rolling updates
+   * - Creating consumers during migration (which would consume and delete
+   *   workqueue messages while they're being restored)
+   */
+  async recoverConsumer(jsm, kind) {
+    const stream = this.streamProvider.getStreamName(kind);
+    const config = this.buildConfig(kind);
+    const name = config.durable_name;
+    this.logger.log(`Recovering consumer: ${name} on stream: ${stream}`);
+    await this.assertNoMigrationInProgress(jsm, stream);
+    try {
+      return await jsm.consumers.info(stream, name);
+    } catch (err) {
+      if (!(err instanceof JetStreamApiError3) || err.apiError().err_code !== 10014 /* ConsumerNotFound */) {
+        throw err;
+      }
+      return await this.createConsumer(jsm, stream, name, config);
+    }
+  }
+  /**
+   * Throw if a migration backup stream exists for this stream.
+   * The self-healing retry loop catches the error and retries with backoff,
+   * naturally waiting until the migrating pod finishes and cleans up the backup.
+   */
+  async assertNoMigrationInProgress(jsm, stream) {
+    const backupName = `${stream}${MIGRATION_BACKUP_SUFFIX}`;
+    try {
+      await jsm.streams.info(backupName);
+      throw new Error(
+        `Stream ${stream} is being migrated (backup ${backupName} exists). Waiting for migration to complete before recovering consumer.`
+      );
+    } catch (err) {
+      if (err instanceof JetStreamApiError3 && err.apiError().err_code === 10059 /* StreamNotFound */) {
+        return;
       }
       throw err;
     }
   }
+  /**
+   * Create a consumer, handling the race where another pod creates it first.
+   */
+  async createConsumer(jsm, stream, name, config) {
+    this.logger.log(`Creating consumer: ${name}`);
+    try {
+      return await jsm.consumers.add(stream, config);
+    } catch (addErr) {
+      if (addErr instanceof JetStreamApiError3 && addErr.apiError().err_code === 10148 /* ConsumerAlreadyExists */) {
+        this.logger.debug(`Consumer ${name} created by another pod, using existing`);
+        return await jsm.consumers.info(stream, name);
+      }
+      throw addErr;
+    }
+  }
   /** Build consumer config by merging defaults with user overrides. */
   // eslint-disable-next-line @typescript-eslint/naming-convention -- NATS API uses snake_case
   buildConfig(kind) {
@@ -1649,6 +2174,7 @@ var ConsumerProvider = class {
         return DEFAULT_BROADCAST_CONSUMER_CONFIG;
       case "ordered" /* Ordered */:
         throw new Error("Ordered consumers are ephemeral and should not use durable config");
+      /* v8 ignore next 5 -- exhaustive switch guard, unreachable */
       default: {
         const _exhaustive = kind;
         throw new Error(`Unexpected StreamKind: ${_exhaustive}`);
@@ -1666,6 +2192,7 @@ var ConsumerProvider = class {
         return this.options.broadcast?.consumer ?? {};
       case "ordered" /* Ordered */:
         throw new Error("Ordered consumers are ephemeral and should not use durable config");
+      /* v8 ignore next 5 -- exhaustive switch guard, unreachable */
       default: {
         const _exhaustive = kind;
         throw new Error(`Unexpected StreamKind: ${_exhaustive}`);
@@ -1675,7 +2202,7 @@ var ConsumerProvider = class {
 };
 
 // src/server/infrastructure/message.provider.ts
-import { Logger as Logger7 } from "@nestjs/common";
+import { Logger as Logger8 } from "@nestjs/common";
 import { DeliverPolicy as DeliverPolicy2 } from "@nats-io/jetstream";
 import {
   catchError,
@@ -1689,12 +2216,13 @@ import {
   timer
 } from "rxjs";
 var MessageProvider = class {
-  constructor(connection, eventBus, consumeOptionsMap = /* @__PURE__ */ new Map()) {
+  constructor(connection, eventBus, consumeOptionsMap = /* @__PURE__ */ new Map(), consumerRecoveryFn) {
     this.connection = connection;
     this.eventBus = eventBus;
     this.consumeOptionsMap = consumeOptionsMap;
+    this.consumerRecoveryFn = consumerRecoveryFn;
   }
-  logger = new Logger7("Jetstream:Message");
+  logger = new Logger8("Jetstream:Message");
   activeIterators = /* @__PURE__ */ new Set();
   orderedReadyResolve = null;
   orderedReadyReject = null;
@@ -1797,20 +2325,49 @@ var MessageProvider = class {
   /** Single iteration: get consumer -> pull messages -> emit to subject. */
   async consumeOnce(kind, info, target$) {
     const js = this.connection.getJetStreamClient();
-    const consumer = await js.consumers.get(info.stream_name, info.name);
+    let consumer;
+    let consumerName2 = info.name;
+    try {
+      consumer = await js.consumers.get(info.stream_name, info.name);
+    } catch (err) {
+      if (this.isConsumerNotFound(err) && this.consumerRecoveryFn) {
+        this.logger.warn(`Consumer ${info.name} not found, recreating...`);
+        const recovered = await this.consumerRecoveryFn(kind);
+        consumerName2 = recovered.name;
+        this.logger.log(`Consumer ${consumerName2} recreated, resuming consumption`);
+        consumer = await js.consumers.get(recovered.stream_name, consumerName2);
+      } else {
+        throw err;
+      }
+    }
     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) {
+    const messages = await consumer.consume({
+      ...defaults,
+      ...userOptions,
+      callback: (msg) => {
         target$.next(msg);
       }
+    });
+    this.activeIterators.add(messages);
+    this.monitorConsumerHealth(messages, consumerName2);
+    try {
+      await messages.closed();
     } finally {
       this.activeIterators.delete(messages);
     }
   }
+  /**
+   * Detect "consumer not found" errors from `js.consumers.get()`.
+   *
+   * Unlike JetStream Manager calls (which throw `JetStreamApiError`),
+   * the JetStream client's `consumers.get()` throws a plain `Error`
+   * with the error code embedded in the message text.
+   */
+  isConsumerNotFound(err) {
+    if (!(err instanceof Error)) return false;
+    return err.message.includes("consumer not found") || err.message.includes(String(10014 /* ConsumerNotFound */));
+  }
   /** Get the target subject for a consumer kind. */
   getTargetSubject(kind) {
     switch (kind) {
@@ -1822,6 +2379,7 @@ var MessageProvider = class {
         return this.broadcastMessages$;
       case "ordered" /* Ordered */:
         return this.orderedMessages$;
+      /* v8 ignore next 5 -- exhaustive switch guard, unreachable */
       default: {
         const _exhaustive = kind;
         throw new Error(`Unknown stream kind: ${_exhaustive}`);
@@ -1886,11 +2444,16 @@ var MessageProvider = class {
       })
     );
   }
-  /** Single iteration: create ordered consumer -> iterate messages. */
+  /** Single iteration: create ordered consumer -> push messages into the subject. */
   async consumeOrderedOnce(streamName2, consumerOpts) {
     const js = this.connection.getJetStreamClient();
     const consumer = await js.consumers.get(streamName2, consumerOpts);
-    const messages = await consumer.consume();
+    const orderedMessages$ = this.orderedMessages$;
+    const messages = await consumer.consume({
+      callback: (msg) => {
+        orderedMessages$.next(msg);
+      }
+    });
     if (this.orderedReadyResolve) {
       this.orderedReadyResolve();
       this.orderedReadyResolve = null;
@@ -1898,17 +2461,117 @@ var MessageProvider = class {
     }
     this.activeIterators.add(messages);
     try {
-      for await (const msg of messages) {
-        this.orderedMessages$.next(msg);
-      }
+      await messages.closed();
     } finally {
       this.activeIterators.delete(messages);
     }
   }
 };
 
+// src/server/infrastructure/metadata.provider.ts
+import { Logger as Logger9 } from "@nestjs/common";
+import { Kvm } from "@nats-io/kv";
+var MetadataProvider = class {
+  constructor(options, connection) {
+    this.connection = connection;
+    this.bucketName = options.metadata?.bucket ?? DEFAULT_METADATA_BUCKET;
+    this.replicas = options.metadata?.replicas ?? DEFAULT_METADATA_REPLICAS;
+    this.ttl = Math.max(options.metadata?.ttl ?? DEFAULT_METADATA_TTL, MIN_METADATA_TTL);
+  }
+  logger = new Logger9("Jetstream:Metadata");
+  bucketName;
+  replicas;
+  ttl;
+  currentEntries;
+  heartbeatTimer;
+  cachedKv;
+  /**
+   * Write handler metadata entries to the KV bucket and start heartbeat.
+   *
+   * Creates the bucket if it doesn't exist (idempotent).
+   * Skips silently when entries map is empty.
+   * Starts a heartbeat interval that refreshes entries every `ttl / 2`
+   * to prevent TTL expiry while the pod is alive.
+   *
+   * Non-critical — errors are logged but do not prevent transport startup.
+   *
+   * @param entries Map of KV key → metadata object.
+   */
+  async publish(entries) {
+    if (entries.size === 0) return;
+    try {
+      const kv = await this.openBucket();
+      await this.writeEntries(kv, entries);
+      this.currentEntries = entries;
+      this.startHeartbeat();
+      this.logger.log(
+        `Published ${entries.size} handler metadata entries to KV bucket "${this.bucketName}"`
+      );
+    } catch (err) {
+      this.logger.error("Failed to publish handler metadata to KV", err);
+    }
+  }
+  /**
+   * Stop the heartbeat timer.
+   *
+   * After this call, entries will expire via TTL once the heartbeat window passes.
+   * Called during transport shutdown (strategy.close()).
+   */
+  destroy() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = void 0;
+    }
+    this.currentEntries = void 0;
+    this.cachedKv = void 0;
+  }
+  /** Write entries to KV with per-entry error handling. */
+  async writeEntries(kv, entries) {
+    for (const [key, meta] of entries) {
+      try {
+        await kv.put(key, JSON.stringify(meta));
+      } catch (err) {
+        this.logger.error(`Failed to write metadata entry "${key}"`, err);
+      }
+    }
+  }
+  /** Start heartbeat interval that refreshes entries every ttl/2. */
+  startHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+    }
+    const interval = Math.floor(this.ttl / 2);
+    this.heartbeatTimer = setInterval(() => {
+      void this.refreshEntries();
+    }, interval);
+    this.heartbeatTimer.unref();
+  }
+  /** Refresh all current entries in KV (heartbeat tick). */
+  async refreshEntries() {
+    if (!this.currentEntries || this.currentEntries.size === 0) return;
+    try {
+      const kv = await this.openBucket();
+      await this.writeEntries(kv, this.currentEntries);
+    } catch (err) {
+      this.logger.error("Failed to refresh handler metadata in KV", err);
+    }
+  }
+  /** Create or open the KV bucket (cached after first call). */
+  async openBucket() {
+    if (this.cachedKv) return this.cachedKv;
+    const js = this.connection.getJetStreamClient();
+    const kvm = new Kvm(js);
+    this.cachedKv = await kvm.create(this.bucketName, {
+      history: DEFAULT_METADATA_HISTORY,
+      replicas: this.replicas,
+      ttl: this.ttl
+    });
+    return this.cachedKv;
+  }
+};
+
 // src/server/routing/pattern-registry.ts
-import { Logger as Logger8 } from "@nestjs/common";
+import { Logger as Logger10 } from "@nestjs/common";
 var HANDLER_LABELS = {
   ["broadcast" /* Broadcast */]: "broadcast" /* Broadcast */,
   ["ordered" /* Ordered */]: "ordered" /* Ordered */,
@@ -1919,7 +2582,7 @@ var PatternRegistry = class {
   constructor(options) {
     this.options = options;
   }
-  logger = new Logger8("Jetstream:PatternRegistry");
+  logger = new Logger10("Jetstream:PatternRegistry");
   registry = /* @__PURE__ */ new Map();
   // Cached after registerHandlers() — the registry is immutable from that point
   cachedPatterns = null;
@@ -1927,6 +2590,7 @@ var PatternRegistry = class {
   _hasCommands = false;
   _hasBroadcasts = false;
   _hasOrdered = false;
+  _hasMetadata = false;
   /**
    * Register all handlers from the NestJS strategy.
    *
@@ -1939,6 +2603,7 @@ var PatternRegistry = class {
       const isEvent = handler.isEventHandler ?? false;
       const isBroadcast = !!extras?.broadcast;
       const isOrdered = !!extras?.ordered;
+      const meta = extras?.meta;
       if (isBroadcast && isOrdered) {
         throw new Error(
           `Handler "${pattern}" cannot be both broadcast and ordered. Use one or the other.`
@@ -1955,7 +2620,8 @@ var PatternRegistry = class {
         pattern,
         isEvent: isEvent && !isOrdered,
         isBroadcast,
-        isOrdered
+        isOrdered,
+        meta
       });
       this.logger.debug(`Registered ${HANDLER_LABELS[kind]}: ${pattern} -> ${fullSubject}`);
     }
@@ -1964,6 +2630,7 @@ var PatternRegistry = class {
     this._hasCommands = this.cachedPatterns.commands.length > 0;
     this._hasBroadcasts = this.cachedPatterns.broadcasts.length > 0;
     this._hasOrdered = this.cachedPatterns.ordered.length > 0;
+    this._hasMetadata = [...this.registry.values()].some((entry) => entry.meta !== void 0);
     this.logSummary();
   }
   /** Find handler for a full NATS subject. */
@@ -1992,6 +2659,26 @@ var PatternRegistry = class {
       (p) => buildSubject(this.options.name, "ordered" /* Ordered */, p)
     );
   }
+  /** Check if any registered handler has metadata. */
+  hasMetadata() {
+    return this._hasMetadata;
+  }
+  /**
+   * Get handler metadata entries for KV publishing.
+   *
+   * Returns a map of KV key -> metadata object for all handlers that have `meta`.
+   * Key format: `{serviceName}.{kind}.{pattern}`.
+   */
+  getMetadataEntries() {
+    const entries = /* @__PURE__ */ new Map();
+    for (const entry of this.registry.values()) {
+      if (!entry.meta) continue;
+      const kind = this.resolveStreamKind(entry);
+      const key = metadataKey(this.options.name, kind, entry.pattern);
+      entries.set(key, entry.meta);
+    }
+    return entries;
+  }
   /** Get patterns grouped by kind (cached after registration). */
   getPatternsByKind() {
     const patterns = this.cachedPatterns ?? this.buildPatternsByKind();
@@ -2031,6 +2718,12 @@ var PatternRegistry = class {
     }
     return { events, commands, broadcasts, ordered };
   }
+  resolveStreamKind(entry) {
+    if (entry.isBroadcast) return "broadcast" /* Broadcast */;
+    if (entry.isOrdered) return "ordered" /* Ordered */;
+    if (entry.isEvent) return "ev" /* Event */;
+    return "cmd" /* Command */;
+  }
   logSummary() {
     const { events, commands, broadcasts, ordered } = this.getPatternsByKind();
     const parts = [
@@ -2046,10 +2739,10 @@ var PatternRegistry = class {
 };
 
 // src/server/routing/event.router.ts
-import { Logger as Logger9 } from "@nestjs/common";
-import { concatMap, from as from2, mergeMap } from "rxjs";
+import { Logger as Logger11 } from "@nestjs/common";
+import { headers as natsHeaders3 } from "@nats-io/transport-node";
 var EventRouter = class {
-  constructor(messageProvider, patternRegistry, codec, eventBus, deadLetterConfig, processingConfig, ackWaitMap) {
+  constructor(messageProvider, patternRegistry, codec, eventBus, deadLetterConfig, processingConfig, ackWaitMap, connection, options) {
     this.messageProvider = messageProvider;
     this.patternRegistry = patternRegistry;
     this.codec = codec;
@@ -2057,8 +2750,10 @@ var EventRouter = class {
     this.deadLetterConfig = deadLetterConfig;
     this.processingConfig = processingConfig;
     this.ackWaitMap = ackWaitMap;
+    this.connection = connection;
+    this.options = options;
   }
-  logger = new Logger9("Jetstream:EventRouter");
+  logger = new Logger11("Jetstream:EventRouter");
   subscriptions = [];
   /**
    * Update the max_deliver thresholds from actual NATS consumer configs.
@@ -2083,15 +2778,194 @@ var EventRouter = class {
     }
     this.subscriptions.length = 0;
   }
-  /** Subscribe to a message stream and route each message. */
+  /** Subscribe to a message stream and route each message to its handler. */
   subscribeToStream(stream$, kind) {
     const isOrdered = kind === "ordered" /* Ordered */;
+    const patternRegistry = this.patternRegistry;
+    const codec = this.codec;
+    const eventBus = this.eventBus;
+    const logger = this.logger;
+    const deadLetterConfig = this.deadLetterConfig;
     const ackExtensionInterval = isOrdered ? null : resolveAckExtensionInterval(this.getAckExtensionConfig(kind), this.ackWaitMap?.get(kind));
+    const hasAckExtension = ackExtensionInterval !== null && ackExtensionInterval > 0;
     const concurrency = this.getConcurrency(kind);
-    const route = (msg) => from2(
-      isOrdered ? this.handleOrderedSafe(msg) : this.handleSafe(msg, ackExtensionInterval, kind)
-    );
-    const subscription = stream$.pipe(isOrdered ? concatMap(route) : mergeMap(route, concurrency)).subscribe();
+    const hasDlqCheck = deadLetterConfig !== void 0;
+    const emitRouted = eventBus.hasHook("messageRouted" /* MessageRouted */);
+    const isDeadLetter = (msg) => {
+      if (!hasDlqCheck) return false;
+      const maxDeliver = deadLetterConfig.maxDeliverByStream?.get(msg.info.stream);
+      if (maxDeliver === void 0 || maxDeliver <= 0) return false;
+      return msg.info.deliveryCount >= maxDeliver;
+    };
+    const handleDeadLetter = hasDlqCheck ? (msg, data, err) => this.handleDeadLetter(msg, data, err) : null;
+    const settleSuccess = (msg, ctx) => {
+      if (ctx.shouldTerminate) msg.term(ctx.terminateReason);
+      else if (ctx.shouldRetry) msg.nak(ctx.retryDelay);
+      else msg.ack();
+    };
+    const settleFailure = async (msg, data, err) => {
+      if (handleDeadLetter !== null && isDeadLetter(msg)) {
+        await handleDeadLetter(msg, data, err);
+        return;
+      }
+      msg.nak();
+    };
+    const resolveEvent = (msg) => {
+      const subject = msg.subject;
+      try {
+        const handler = patternRegistry.getHandler(subject);
+        if (!handler) {
+          msg.term(`No handler for event: ${subject}`);
+          logger.error(`No handler for subject: ${subject}`);
+          return null;
+        }
+        let data;
+        try {
+          data = codec.decode(msg.data);
+        } catch (err) {
+          msg.term("Decode error");
+          logger.error(`Decode error for ${subject}:`, err);
+          return null;
+        }
+        if (emitRouted) eventBus.emitMessageRouted(subject, "event" /* Event */);
+        return { handler, data };
+      } catch (err) {
+        logger.error(`Unexpected error in ${kind} event router`, err);
+        try {
+          msg.term("Unexpected router error");
+        } catch (termErr) {
+          logger.error(`Failed to terminate message ${subject}:`, termErr);
+        }
+        return null;
+      }
+    };
+    const handleSafe = (msg) => {
+      const resolved = resolveEvent(msg);
+      if (resolved === null) return void 0;
+      const { handler, data } = resolved;
+      const ctx = new RpcContext([msg]);
+      const stopAckExtension = hasAckExtension ? startAckExtensionTimer(msg, ackExtensionInterval) : null;
+      let pending;
+      try {
+        pending = unwrapResult(handler(data, ctx));
+      } catch (err) {
+        logger.error(`Event handler error (${msg.subject}) in ${kind} router:`, err);
+        if (stopAckExtension !== null) stopAckExtension();
+        return settleFailure(msg, data, err);
+      }
+      if (!isPromiseLike(pending)) {
+        settleSuccess(msg, ctx);
+        if (stopAckExtension !== null) stopAckExtension();
+        return void 0;
+      }
+      return pending.then(
+        () => {
+          settleSuccess(msg, ctx);
+          if (stopAckExtension !== null) stopAckExtension();
+        },
+        async (err) => {
+          logger.error(`Event handler error (${msg.subject}) in ${kind} router:`, err);
+          try {
+            await settleFailure(msg, data, err);
+          } finally {
+            if (stopAckExtension !== null) stopAckExtension();
+          }
+        }
+      );
+    };
+    const handleOrderedSafe = (msg) => {
+      const subject = msg.subject;
+      let handler;
+      let data;
+      try {
+        handler = patternRegistry.getHandler(subject);
+        if (!handler) {
+          logger.error(`No handler for subject: ${subject}`);
+          return void 0;
+        }
+        try {
+          data = codec.decode(msg.data);
+        } catch (err) {
+          logger.error(`Decode error for ${subject}:`, err);
+          return void 0;
+        }
+        if (emitRouted) eventBus.emitMessageRouted(subject, "event" /* Event */);
+      } catch (err) {
+        logger.error(`Ordered handler error (${subject}):`, err);
+        return void 0;
+      }
+      const ctx = new RpcContext([msg]);
+      const warnIfSettlementAttempted = () => {
+        if (ctx.shouldRetry || ctx.shouldTerminate) {
+          logger.warn(
+            `retry()/terminate() ignored for ordered message ${subject} \u2014 ordered consumers auto-acknowledge`
+          );
+        }
+      };
+      let pending;
+      try {
+        pending = unwrapResult(handler(data, ctx));
+      } catch (err) {
+        logger.error(`Ordered handler error (${subject}):`, err);
+        return void 0;
+      }
+      if (!isPromiseLike(pending)) {
+        warnIfSettlementAttempted();
+        return void 0;
+      }
+      return pending.then(warnIfSettlementAttempted, (err) => {
+        logger.error(`Ordered handler error (${subject}):`, err);
+      });
+    };
+    const route = isOrdered ? handleOrderedSafe : handleSafe;
+    const maxActive = isOrdered ? 1 : concurrency ?? Number.POSITIVE_INFINITY;
+    const backlogWarnThreshold = 1e3;
+    let active = 0;
+    let backlogWarned = false;
+    const backlog = [];
+    const onAsyncDone = () => {
+      active--;
+      drainBacklog();
+    };
+    const drainBacklog = () => {
+      while (active < maxActive) {
+        const next = backlog.shift();
+        if (next === void 0) return;
+        active++;
+        const result = route(next);
+        if (result !== void 0) {
+          void result.finally(onAsyncDone);
+        } else {
+          active--;
+        }
+      }
+      if (backlog.length < backlogWarnThreshold) backlogWarned = false;
+    };
+    const subscription = stream$.subscribe({
+      next: (msg) => {
+        if (active >= maxActive) {
+          backlog.push(msg);
+          if (!backlogWarned && backlog.length >= backlogWarnThreshold) {
+            backlogWarned = true;
+            logger.warn(
+              `${kind} backlog reached ${backlog.length} messages \u2014 consumer may be falling behind`
+            );
+          }
+          return;
+        }
+        active++;
+        const result = route(msg);
+        if (result !== void 0) {
+          void result.finally(onAsyncDone);
+        } else {
+          active--;
+          if (backlog.length > 0) drainBacklog();
+        }
+      },
+      error: (err) => {
+        logger.error(`Stream error in ${kind} router`, err);
+      }
+    });
     this.subscriptions.push(subscription);
   }
   getConcurrency(kind) {
@@ -2104,87 +2978,94 @@ var EventRouter = class {
     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 a dead letter: invoke callback, then term or nak based on result. */
+  /**
+   * Fallback execution for a dead letter when DLQ is disabled, or when
+   * publishing to the DLQ stream fails (due to network or NATS errors).
+   *
+   * Triggers the user-provided `onDeadLetter` hook for logging/alerting.
+   * On success, terminates the message. On error, leaves it unacknowledged (nak)
+   * so NATS can retry the delivery on the next cycle.
+   */
+  async fallbackToOnDeadLetterCallback(info, msg) {
+    if (!this.deadLetterConfig) {
+      msg.term("Dead letter config unavailable");
+      return;
     }
-  }
-  /** 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);
+      await this.deadLetterConfig.onDeadLetter(info);
+      msg.term("Dead letter processed via fallback callback");
+    } catch (hookErr) {
+      this.logger.error(
+        `Fallback onDeadLetter callback failed for ${msg.subject}, nak for retry:`,
+        hookErr
+      );
+      msg.nak();
     }
   }
-  /** Resolve handler, decode payload, and build context. Returns null on failure. */
-  decodeMessage(msg, isOrdered = false) {
-    const handler = this.patternRegistry.getHandler(msg.subject);
-    if (!handler) {
-      if (!isOrdered) msg.term(`No handler for event: ${msg.subject}`);
-      this.logger.error(`No handler for subject: ${msg.subject}`);
-      return null;
+  /**
+   * Publish a dead letter to the configured Dead-Letter Queue (DLQ) stream.
+   *
+   * Appends diagnostic metadata headers to the original message and preserves
+   * the primary payload. If publishing succeeds, it notifies the standard
+   * `onDeadLetter` callback and terminates the message. If it fails, it falls
+   * back to the callback entirely to prevent silent data loss.
+   */
+  async publishToDlq(msg, info, error) {
+    const serviceName = this.options?.name;
+    if (!this.connection || !serviceName) {
+      this.logger.error(
+        `Cannot publish to DLQ for ${msg.subject}: Connection or Module Options unavailable`
+      );
+      await this.fallbackToOnDeadLetterCallback(info, msg);
+      return;
     }
-    let data;
-    try {
-      data = this.codec.decode(msg.data);
-    } catch (err) {
-      if (!isOrdered) msg.term("Decode error");
-      this.logger.error(`Decode error for ${msg.subject}:`, err);
-      return null;
+    const destinationSubject = dlqStreamName(serviceName);
+    const hdrs = natsHeaders3();
+    if (msg.headers) {
+      for (const [k, v] of msg.headers) {
+        for (const val of v) {
+          hdrs.append(k, val);
+        }
+      }
     }
-    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, ackExtensionInterval) {
-    const stopAckExtension = startAckExtensionTimer(msg, ackExtensionInterval);
+    let reason = String(error);
+    if (error instanceof Error) {
+      reason = error.message;
+    } else if (typeof error === "object" && error !== null && "message" in error) {
+      reason = String(error.message);
+    }
+    hdrs.set("x-dead-letter-reason" /* DeadLetterReason */, reason);
+    hdrs.set("x-original-subject" /* OriginalSubject */, msg.subject);
+    hdrs.set("x-original-stream" /* OriginalStream */, msg.info.stream);
+    hdrs.set("x-failed-at" /* FailedAt */, (/* @__PURE__ */ new Date()).toISOString());
+    hdrs.set("x-delivery-count" /* DeliveryCount */, msg.info.deliveryCount.toString());
     try {
-      await unwrapResult(handler(data, ctx));
-      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)) {
-        await this.handleDeadLetter(msg, data, err);
-      } else {
-        msg.nak();
+      const js = this.connection.getJetStreamClient();
+      await js.publish(destinationSubject, msg.data, { headers: hdrs });
+      this.logger.log(`Message sent to DLQ: ${msg.subject}`);
+      if (this.deadLetterConfig?.onDeadLetter) {
+        try {
+          await this.deadLetterConfig.onDeadLetter(info);
+        } catch (hookErr) {
+          this.logger.warn(
+            `onDeadLetter callback failed after successful DLQ publish for ${msg.subject}`,
+            hookErr
+          );
+        }
       }
-    } finally {
-      stopAckExtension?.();
+      msg.term("Moved to DLQ stream");
+    } catch (publishErr) {
+      this.logger.error(`Failed to publish to DLQ for ${msg.subject}:`, publishErr);
+      await this.fallbackToOnDeadLetterCallback(info, msg);
     }
   }
-  /** Check if the message has exhausted all delivery attempts. */
-  isDeadLetter(msg) {
-    if (!this.deadLetterConfig) return false;
-    const maxDeliver = this.deadLetterConfig.maxDeliverByStream.get(msg.info.stream);
-    if (maxDeliver === void 0 || maxDeliver <= 0) return false;
-    return msg.info.deliveryCount >= maxDeliver;
-  }
-  /** Handle a dead letter: invoke callback, then term or nak based on result. */
+  /**
+   * Orchestrates the handling of a message that has exhausted delivery limits.
+   *
+   * Emits a system event and delegates either to the robust DLQ stream publisher
+   * or directly to the fallback callback based on the active module configuration.
+   */
   async handleDeadLetter(msg, data, error) {
     const info = {
       subject: msg.subject,
@@ -2197,24 +3078,17 @@ var EventRouter = class {
       timestamp: new Date(msg.info.timestampNanos / 1e6).toISOString()
     };
     this.eventBus.emit("deadLetter" /* DeadLetter */, info);
-    if (!this.deadLetterConfig) {
-      msg.term("Dead letter config unavailable");
-      return;
-    }
-    try {
-      await this.deadLetterConfig.onDeadLetter(info);
-      msg.term("Dead letter processed");
-    } catch (hookErr) {
-      this.logger.error(`onDeadLetter callback failed for ${msg.subject}, nak for retry:`, hookErr);
-      msg.nak();
+    if (!this.options?.dlq) {
+      await this.fallbackToOnDeadLetterCallback(info, msg);
+    } else {
+      await this.publishToDlq(msg, info, error);
     }
   }
 };
 
 // src/server/routing/rpc.router.ts
-import { Logger as Logger10 } from "@nestjs/common";
+import { Logger as Logger12 } from "@nestjs/common";
 import { headers } from "@nats-io/transport-node";
-import { from as from3, mergeMap as mergeMap2 } from "rxjs";
 var RpcRouter = class {
   constructor(messageProvider, patternRegistry, connection, codec, eventBus, rpcOptions, ackWaitMap) {
     this.messageProvider = messageProvider;
@@ -2227,7 +3101,7 @@ var RpcRouter = class {
     this.timeout = rpcOptions?.timeout ?? DEFAULT_JETSTREAM_RPC_TIMEOUT;
     this.concurrency = rpcOptions?.concurrency;
   }
-  logger = new Logger10("Jetstream:RpcRouter");
+  logger = new Logger12("Jetstream:RpcRouter");
   timeout;
   concurrency;
   resolvedAckExtensionInterval;
@@ -2245,105 +3119,203 @@ var RpcRouter = class {
   /** Start routing command messages to handlers. */
   async start() {
     this.cachedNc = await this.connection.getConnection();
-    this.subscription = this.messageProvider.commands$.pipe(mergeMap2((msg) => from3(this.handleSafe(msg)), this.concurrency)).subscribe();
-  }
-  /** Stop routing and unsubscribe. */
-  destroy() {
-    this.subscription?.unsubscribe();
-    this.subscription = null;
-  }
-  /** Handle a single RPC command message with error isolation. */
-  async handleSafe(msg) {
-    try {
-      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) {
-      this.logger.error("Unexpected error in RPC router", err);
-    }
-  }
-  /** Execute handler, publish response, settle message. */
-  async executeHandler(handler, data, msg, replyTo, correlationId) {
-    const nc = this.cachedNc ?? await this.connection.getConnection();
-    const ctx = new RpcContext([msg]);
-    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");
-    }, this.timeout);
-    try {
-      const result = await unwrapResult(handler(data, ctx));
-      if (settled) return;
-      settled = true;
-      clearTimeout(timeoutId);
-      stopAckExtension?.();
-      msg.ack();
+    const nc = this.cachedNc;
+    const patternRegistry = this.patternRegistry;
+    const codec = this.codec;
+    const eventBus = this.eventBus;
+    const logger = this.logger;
+    const timeout = this.timeout;
+    const ackExtensionInterval = this.ackExtensionInterval;
+    const hasAckExtension = ackExtensionInterval !== null && ackExtensionInterval > 0;
+    const maxActive = this.concurrency ?? Number.POSITIVE_INFINITY;
+    const emitRpcTimeout = (subject, correlationId) => {
+      eventBus.emit("rpcTimeout" /* RpcTimeout */, subject, correlationId);
+    };
+    const publishReply = (replyTo, correlationId, payload) => {
       try {
         const hdrs = headers();
         hdrs.set("x-correlation-id" /* CorrelationId */, correlationId);
-        nc.publish(replyTo, this.codec.encode(result), { headers: hdrs });
+        nc.publish(replyTo, codec.encode(payload), { headers: hdrs });
       } catch (publishErr) {
-        this.logger.error(`Failed to publish RPC response for ${msg.subject}`, publishErr);
+        logger.error(`Failed to publish RPC response`, publishErr);
       }
-    } catch (err) {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timeoutId);
-      stopAckExtension?.();
+    };
+    const publishErrorReply = (replyTo, correlationId, subject, err) => {
       try {
         const hdrs = headers();
         hdrs.set("x-correlation-id" /* CorrelationId */, correlationId);
         hdrs.set("x-error" /* Error */, "true");
-        nc.publish(replyTo, this.codec.encode(serializeError(err)), { headers: hdrs });
+        nc.publish(replyTo, codec.encode(serializeError(err)), { headers: hdrs });
       } catch (encodeErr) {
-        this.logger.error(`Failed to encode RPC error for ${msg.subject}`, encodeErr);
+        logger.error(`Failed to encode RPC error for ${subject}`, encodeErr);
       }
-      msg.term(`Handler error: ${msg.subject}`);
-    }
+    };
+    const resolveCommand = (msg) => {
+      const subject = msg.subject;
+      try {
+        const handler = patternRegistry.getHandler(subject);
+        if (!handler) {
+          msg.term(`No handler for RPC: ${subject}`);
+          logger.error(`No handler for RPC subject: ${subject}`);
+          return null;
+        }
+        const msgHeaders = msg.headers;
+        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)");
+          logger.error(`Missing headers for RPC: ${subject}`);
+          return null;
+        }
+        let data;
+        try {
+          data = codec.decode(msg.data);
+        } catch (err) {
+          msg.term("Decode error");
+          logger.error(`Decode error for RPC ${subject}:`, err);
+          return null;
+        }
+        eventBus.emitMessageRouted(subject, "rpc" /* Rpc */);
+        return { handler, data, replyTo, correlationId };
+      } catch (err) {
+        logger.error("Unexpected error in RPC router", err);
+        try {
+          msg.term("Unexpected router error");
+        } catch (termErr) {
+          logger.error(`Failed to terminate RPC message ${subject}:`, termErr);
+        }
+        return null;
+      }
+    };
+    const handleSafe = (msg) => {
+      const resolved = resolveCommand(msg);
+      if (resolved === null) return void 0;
+      const { handler, data, replyTo, correlationId } = resolved;
+      const subject = msg.subject;
+      const ctx = new RpcContext([msg]);
+      const stopAckExtension = hasAckExtension ? startAckExtensionTimer(msg, ackExtensionInterval) : null;
+      let pending;
+      try {
+        pending = unwrapResult(handler(data, ctx));
+      } catch (err) {
+        if (stopAckExtension !== null) stopAckExtension();
+        logger.error(`RPC handler error (${subject}):`, err);
+        publishErrorReply(replyTo, correlationId, subject, err);
+        msg.term(`Handler error: ${subject}`);
+        return void 0;
+      }
+      if (!isPromiseLike(pending)) {
+        if (stopAckExtension !== null) stopAckExtension();
+        msg.ack();
+        publishReply(replyTo, correlationId, pending);
+        return void 0;
+      }
+      let settled = false;
+      const timeoutId = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        if (stopAckExtension !== null) stopAckExtension();
+        logger.error(`RPC timeout (${timeout}ms): ${subject}`);
+        emitRpcTimeout(subject, correlationId);
+        msg.term("Handler timeout");
+      }, timeout);
+      return pending.then(
+        (result) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timeoutId);
+          if (stopAckExtension !== null) stopAckExtension();
+          msg.ack();
+          publishReply(replyTo, correlationId, result);
+        },
+        (err) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timeoutId);
+          if (stopAckExtension !== null) stopAckExtension();
+          logger.error(`RPC handler error (${subject}):`, err);
+          publishErrorReply(replyTo, correlationId, subject, err);
+          msg.term(`Handler error: ${subject}`);
+        }
+      );
+    };
+    const backlogWarnThreshold = 1e3;
+    let active = 0;
+    let backlogWarned = false;
+    const backlog = [];
+    const onAsyncDone = () => {
+      active--;
+      drainBacklog();
+    };
+    const drainBacklog = () => {
+      while (active < maxActive) {
+        const next = backlog.shift();
+        if (next === void 0) return;
+        active++;
+        const result = handleSafe(next);
+        if (result !== void 0) {
+          void result.finally(onAsyncDone);
+        } else {
+          active--;
+        }
+      }
+      if (backlog.length < backlogWarnThreshold) backlogWarned = false;
+    };
+    this.subscription = this.messageProvider.commands$.subscribe({
+      next: (msg) => {
+        if (active >= maxActive) {
+          backlog.push(msg);
+          if (!backlogWarned && backlog.length >= backlogWarnThreshold) {
+            backlogWarned = true;
+            logger.warn(
+              `RPC backlog reached ${backlog.length} messages \u2014 consumer may be falling behind`
+            );
+          }
+          return;
+        }
+        active++;
+        const result = handleSafe(msg);
+        if (result !== void 0) {
+          void result.finally(onAsyncDone);
+        } else {
+          active--;
+          if (backlog.length > 0) drainBacklog();
+        }
+      },
+      error: (err) => {
+        logger.error("Stream error in RPC router", err);
+      }
+    });
+  }
+  /** Stop routing and unsubscribe. */
+  destroy() {
+    this.subscription?.unsubscribe();
+    this.subscription = null;
   }
 };
 
 // src/shutdown/shutdown.manager.ts
-import { Logger as Logger11 } from "@nestjs/common";
+import { Logger as Logger13 } from "@nestjs/common";
 var ShutdownManager = class {
   constructor(connection, eventBus, timeout) {
     this.connection = connection;
     this.eventBus = eventBus;
     this.timeout = timeout;
   }
-  logger = new Logger11("Jetstream:Shutdown");
+  logger = new Logger13("Jetstream:Shutdown");
+  shutdownPromise;
   /**
    * Execute the full shutdown sequence.
    *
+   * Idempotent — concurrent or repeated calls return the same promise.
+   *
    * @param strategy Optional stoppable to close (stops consumers and subscriptions).
    */
   async shutdown(strategy) {
+    this.shutdownPromise ??= this.doShutdown(strategy);
+    return this.shutdownPromise;
+  }
+  async doShutdown(strategy) {
     this.eventBus.emit("shutdownStart" /* ShutdownStart */);
     this.logger.log(`Graceful shutdown started (timeout: ${this.timeout}ms)`);
     strategy?.close();
@@ -2478,7 +3450,7 @@ var JetstreamModule = class {
         provide: JETSTREAM_EVENT_BUS,
         inject: [JETSTREAM_OPTIONS],
         useFactory: (options) => {
-          const logger = new Logger12("Jetstream:Module");
+          const logger = new Logger14("Jetstream:Module");
           return new EventBus(logger, options.hooks);
         }
       },
@@ -2557,8 +3529,8 @@ var JetstreamModule = class {
       // MessageProvider — pull-based message consumption
       {
         provide: MessageProvider,
-        inject: [JETSTREAM_OPTIONS, JETSTREAM_CONNECTION, JETSTREAM_EVENT_BUS],
-        useFactory: (options, connection, eventBus) => {
+        inject: [JETSTREAM_OPTIONS, JETSTREAM_CONNECTION, JETSTREAM_EVENT_BUS, ConsumerProvider],
+        useFactory: (options, connection, eventBus, consumerProvider) => {
           if (options.consumer === false) return null;
           const consumeOptionsMap = /* @__PURE__ */ new Map();
           if (options.events?.consume)
@@ -2568,7 +3540,11 @@ var JetstreamModule = class {
           if (options.rpc?.mode === "jetstream" && options.rpc.consume) {
             consumeOptionsMap.set("cmd" /* Command */, options.rpc.consume);
           }
-          return new MessageProvider(connection, eventBus, consumeOptionsMap);
+          const consumerRecoveryFn = consumerProvider ? async (kind) => {
+            const jsm = await connection.getJetStreamManager();
+            return consumerProvider.recoverConsumer(jsm, kind);
+          } : void 0;
+          return new MessageProvider(connection, eventBus, consumeOptionsMap, consumerRecoveryFn);
         }
       },
       // EventRouter — routes event and broadcast messages to handlers
@@ -2580,9 +3556,10 @@ var JetstreamModule = class {
           PatternRegistry,
           JETSTREAM_CODEC,
           JETSTREAM_EVENT_BUS,
-          JETSTREAM_ACK_WAIT_MAP
+          JETSTREAM_ACK_WAIT_MAP,
+          JETSTREAM_CONNECTION
         ],
-        useFactory: (options, messageProvider, patternRegistry, codec, eventBus, ackWaitMap) => {
+        useFactory: (options, messageProvider, patternRegistry, codec, eventBus, ackWaitMap, connection) => {
           if (options.consumer === false) return null;
           const deadLetterConfig = options.onDeadLetter ? {
             maxDeliverByStream: /* @__PURE__ */ new Map(),
@@ -2605,7 +3582,9 @@ var JetstreamModule = class {
             eventBus,
             deadLetterConfig,
             processingConfig,
-            ackWaitMap
+            ackWaitMap,
+            connection,
+            options
           );
         }
       },
@@ -2654,6 +3633,15 @@ var JetstreamModule = class {
           return new CoreRpcServer(options, connection, patternRegistry, codec, eventBus);
         }
       },
+      // MetadataProvider — handler metadata KV registry (decoupled from stream/consumer infra)
+      {
+        provide: MetadataProvider,
+        inject: [JETSTREAM_OPTIONS, JETSTREAM_CONNECTION],
+        useFactory: (options, connection) => {
+          if (options.consumer === false) return null;
+          return new MetadataProvider(options, connection);
+        }
+      },
       // JetstreamStrategy — server-side transport (only when consumer enabled)
       {
         provide: JetstreamStrategy,
@@ -2667,9 +3655,10 @@ var JetstreamModule = class {
           EventRouter,
           RpcRouter,
           CoreRpcServer,
-          JETSTREAM_ACK_WAIT_MAP
+          JETSTREAM_ACK_WAIT_MAP,
+          MetadataProvider
         ],
-        useFactory: (options, connection, patternRegistry, streamProvider, consumerProvider, messageProvider, eventRouter, rpcRouter, coreRpcServer, ackWaitMap) => {
+        useFactory: (options, connection, patternRegistry, streamProvider, consumerProvider, messageProvider, eventRouter, rpcRouter, coreRpcServer, ackWaitMap, metadataProvider) => {
           if (options.consumer === false) return null;
           return new JetstreamStrategy(
             options,
@@ -2681,7 +3670,8 @@ var JetstreamModule = class {
             eventRouter,
             rpcRouter,
             coreRpcServer,
-            ackWaitMap
+            ackWaitMap,
+            metadataProvider
           );
         }
       }
@@ -2748,12 +3738,26 @@ JetstreamModule = __decorateClass([
   __decorateParam(1, Inject(JetstreamStrategy))
 ], JetstreamModule);
 export {
-  EventBus,
+  DEFAULT_BROADCAST_CONSUMER_CONFIG,
+  DEFAULT_BROADCAST_STREAM_CONFIG,
+  DEFAULT_COMMAND_CONSUMER_CONFIG,
+  DEFAULT_COMMAND_STREAM_CONFIG,
+  DEFAULT_DLQ_STREAM_CONFIG,
+  DEFAULT_EVENT_CONSUMER_CONFIG,
+  DEFAULT_EVENT_STREAM_CONFIG,
+  DEFAULT_JETSTREAM_RPC_TIMEOUT,
+  DEFAULT_METADATA_BUCKET,
+  DEFAULT_METADATA_HISTORY,
+  DEFAULT_METADATA_REPLICAS,
+  DEFAULT_METADATA_TTL,
+  DEFAULT_ORDERED_STREAM_CONFIG,
+  DEFAULT_RPC_TIMEOUT,
+  DEFAULT_SHUTDOWN_TIMEOUT,
   JETSTREAM_CODEC,
   JETSTREAM_CONNECTION,
-  JETSTREAM_EVENT_BUS,
   JETSTREAM_OPTIONS,
   JetstreamClient,
+  JetstreamDlqHeader,
   JetstreamHeader,
   JetstreamHealthIndicator,
   JetstreamModule,
@@ -2761,17 +3765,24 @@ export {
   JetstreamRecordBuilder,
   JetstreamStrategy,
   JsonCodec,
+  MIN_METADATA_TTL,
   MessageKind,
+  MsgpackCodec,
+  NatsErrorCode,
   PatternPrefix,
+  RESERVED_HEADERS,
   RpcContext,
   StreamKind,
   TransportEvent,
+  buildBroadcastSubject,
   buildSubject,
   consumerName,
+  dlqStreamName,
   getClientToken,
   internalName,
   isCoreRpcMode,
   isJetStreamRpcMode,
+  metadataKey,
   streamName,
   toNanos
 };