@horizon-republic/nestjs-jetstream 2.8.0 → 2.9.0

package/dist/index.cjs

@@ -29,12 +29,17 @@ var __decorateParam = (index, decorator) => (target, key) => decorator(target, k
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  DEFAULT_METADATA_BUCKET: () => DEFAULT_METADATA_BUCKET,
+  DEFAULT_METADATA_HISTORY: () => DEFAULT_METADATA_HISTORY,
+  DEFAULT_METADATA_REPLICAS: () => DEFAULT_METADATA_REPLICAS,
+  DEFAULT_METADATA_TTL: () => DEFAULT_METADATA_TTL,
   EventBus: () => EventBus,
   JETSTREAM_CODEC: () => JETSTREAM_CODEC,
   JETSTREAM_CONNECTION: () => JETSTREAM_CONNECTION,
   JETSTREAM_EVENT_BUS: () => JETSTREAM_EVENT_BUS,
   JETSTREAM_OPTIONS: () => JETSTREAM_OPTIONS,
   JetstreamClient: () => JetstreamClient,
+  JetstreamDlqHeader: () => JetstreamDlqHeader,
   JetstreamHeader: () => JetstreamHeader,
   JetstreamHealthIndicator: () => JetstreamHealthIndicator,
   JetstreamModule: () => JetstreamModule,
@@ -42,24 +47,28 @@ __export(index_exports, {
   JetstreamRecordBuilder: () => JetstreamRecordBuilder,
   JetstreamStrategy: () => JetstreamStrategy,
   JsonCodec: () => JsonCodec,
+  MIN_METADATA_TTL: () => MIN_METADATA_TTL,
   MessageKind: () => MessageKind,
   PatternPrefix: () => PatternPrefix,
   RpcContext: () => RpcContext,
   StreamKind: () => StreamKind,
   TransportEvent: () => TransportEvent,
+  buildBroadcastSubject: () => buildBroadcastSubject,
   buildSubject: () => buildSubject,
   consumerName: () => consumerName,
+  dlqStreamName: () => dlqStreamName,
   getClientToken: () => getClientToken,
   internalName: () => internalName,
   isCoreRpcMode: () => isCoreRpcMode,
   isJetStreamRpcMode: () => isJetStreamRpcMode,
+  metadataKey: () => metadataKey,
   streamName: () => streamName,
   toNanos: () => toNanos
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/jetstream.module.ts
-var import_common12 = require("@nestjs/common");
+var import_common14 = require("@nestjs/common");
 
 // src/client/jetstream.client.ts
 var import_common = require("@nestjs/common");
@@ -152,7 +161,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 = {
@@ -167,6 +176,18 @@ var DEFAULT_ORDERED_STREAM_CONFIG = {
   max_age: toNanos(1, "days"),
   duplicate_window: toNanos(2, "minutes")
 };
+var DEFAULT_DLQ_STREAM_CONFIG = {
+  ...baseStreamConfig,
+  retention: import_jetstream.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,
@@ -194,6 +215,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";
@@ -202,6 +229,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 */,
@@ -214,6 +249,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`;
@@ -228,12 +266,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 {
@@ -242,6 +281,7 @@ var JetstreamRecordBuilder = class {
   timeout;
   messageId;
   scheduleOptions;
+  ttlDuration;
   constructor(data) {
     this.data = data;
   }
@@ -333,6 +373,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}.
    *
@@ -345,7 +412,8 @@ var JetstreamRecordBuilder = class {
       new Map(this.headers),
       this.timeout,
       this.messageId,
-      schedule
+      schedule,
+      this.ttlDuration
     );
   }
   /** Validate that a header key is not reserved. */
@@ -357,6 +425,17 @@ 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 JetstreamClient = class extends import_microservices.ClientProxy {
@@ -431,7 +510,7 @@ var JetstreamClient = class extends import_microservices.ClientProxy {
    */
   async dispatchEvent(packet) {
     await this.connect();
-    const { data, hdrs, messageId, schedule } = this.extractRecordData(packet.data);
+    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) {
@@ -439,6 +518,7 @@ var JetstreamClient = class extends import_microservices.ClientProxy {
       const ack = await this.connection.getJetStreamClient().publish(scheduleSubject, this.codec.encode(data), {
         headers: msgHeaders,
         msgID: messageId ?? import_nuid.nuid.next(),
+        ttl,
         schedule: {
           specification: schedule.at,
           target: eventSubject
@@ -452,7 +532,8 @@ var JetstreamClient = class extends import_microservices.ClientProxy {
     } else {
       const ack = await this.connection.getJetStreamClient().publish(eventSubject, this.codec.encode(data), {
         headers: msgHeaders,
-        msgID: messageId ?? import_nuid.nuid.next()
+        msgID: messageId ?? import_nuid.nuid.next(),
+        ttl
       });
       if (ack.duplicate) {
         this.logger.warn(`Duplicate event publish detected: ${eventSubject} (seq: ${ack.seq})`);
@@ -468,12 +549,17 @@ var JetstreamClient = class extends import_microservices.ClientProxy {
    */
   publish(packet, callback) {
     const subject = buildSubject(this.targetName, "cmd" /* Command */, packet.pattern);
-    const { data, hdrs, timeout, messageId, schedule } = this.extractRecordData(packet.data);
+    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 });
@@ -589,6 +675,7 @@ var JetstreamClient = class extends import_microservices.ClientProxy {
     this.pendingTimeouts.clear();
     this.inboxSubscription?.unsubscribe();
     this.inboxSubscription = null;
+    this.inbox = null;
   }
   /** Setup shared inbox subscription for JetStream RPC responses. */
   setupInbox(nc) {
@@ -678,7 +765,8 @@ var JetstreamClient = class extends import_microservices.ClientProxy {
         hdrs: rawData.headers.size > 0 ? new Map(rawData.headers) : null,
         timeout: rawData.timeout,
         messageId: rawData.messageId,
-        schedule: rawData.schedule
+        schedule: rawData.schedule,
+        ttl: rawData.ttl
       };
     }
     return {
@@ -686,7 +774,8 @@ var JetstreamClient = class extends import_microservices.ClientProxy {
       hdrs: null,
       timeout: void 0,
       messageId: void 0,
-      schedule: void 0
+      schedule: void 0,
+      ttl: void 0
     };
   }
   /**
@@ -1001,9 +1090,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();
@@ -1013,8 +1107,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 };
@@ -1027,7 +1123,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, 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;
@@ -1039,6 +1135,7 @@ var JetstreamStrategy = class extends import_microservices2.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
@@ -1083,10 +1180,14 @@ var JetstreamStrategy = class extends import_microservices2.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();
@@ -1462,24 +1563,172 @@ var CoreRpcServer = class {
 };
 
 // src/server/infrastructure/stream.provider.ts
+var import_common6 = require("@nestjs/common");
+var import_jetstream14 = require("@nats-io/jetstream");
+
+// 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
 var import_common5 = require("@nestjs/common");
 var import_jetstream13 = require("@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 import_common5.Logger("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 import_jetstream13.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 import_common5.Logger("Jetstream:Stream");
+  logger = new import_common6.Logger("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) {
@@ -1514,17 +1763,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 import_jetstream13.JetStreamApiError && err.apiError().err_code === STREAM_NOT_FOUND) {
+      if (err instanceof import_jetstream14.JetStreamApiError && 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 import_jetstream14.JetStreamApiError && 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);
@@ -1540,6 +1857,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) {
@@ -1558,25 +1895,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
-var import_common6 = require("@nestjs/common");
-var import_jetstream15 = require("@nats-io/jetstream");
-var CONSUMER_NOT_FOUND = 10014;
+var import_common7 = require("@nestjs/common");
+var import_jetstream16 = require("@nats-io/jetstream");
 var ConsumerProvider = class {
   constructor(options, connection, streamProvider, patternRegistry) {
     this.options = options;
@@ -1584,7 +1940,7 @@ var ConsumerProvider = class {
     this.streamProvider = streamProvider;
     this.patternRegistry = patternRegistry;
   }
-  logger = new import_common6.Logger("Jetstream:Consumer");
+  logger = new import_common7.Logger("Jetstream:Consumer");
   /**
    * Ensure consumers exist for the specified kinds.
    *
@@ -1605,7 +1961,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);
@@ -1616,13 +1976,74 @@ var ConsumerProvider = class {
       this.logger.debug(`Consumer exists, updating: ${name}`);
       return await jsm.consumers.update(stream, name, config);
     } catch (err) {
-      if (err instanceof import_jetstream15.JetStreamApiError && err.apiError().err_code === CONSUMER_NOT_FOUND) {
-        this.logger.log(`Creating consumer: ${name}`);
-        return await jsm.consumers.add(stream, config);
+      if (!(err instanceof import_jetstream16.JetStreamApiError) || 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 import_jetstream16.JetStreamApiError) || 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 import_jetstream16.JetStreamApiError && 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 import_jetstream16.JetStreamApiError && 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) {
@@ -1675,6 +2096,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}`);
@@ -1692,6 +2114,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}`);
@@ -1701,16 +2124,17 @@ var ConsumerProvider = class {
 };
 
 // src/server/infrastructure/message.provider.ts
-var import_common7 = require("@nestjs/common");
-var import_jetstream17 = require("@nats-io/jetstream");
+var import_common8 = require("@nestjs/common");
+var import_jetstream18 = require("@nats-io/jetstream");
 var import_rxjs3 = require("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 import_common7.Logger("Jetstream:Message");
+  logger = new import_common8.Logger("Jetstream:Message");
   activeIterators = /* @__PURE__ */ new Set();
   orderedReadyResolve = null;
   orderedReadyReject = null;
@@ -1762,7 +2186,7 @@ var MessageProvider = class {
    */
   async startOrdered(streamName2, filterSubjects, orderedConfig) {
     const consumerOpts = { filter_subjects: filterSubjects };
-    if (orderedConfig?.deliverPolicy !== void 0 && orderedConfig.deliverPolicy !== import_jetstream17.DeliverPolicy.All) {
+    if (orderedConfig?.deliverPolicy !== void 0 && orderedConfig.deliverPolicy !== import_jetstream18.DeliverPolicy.All) {
       consumerOpts.deliver_policy = orderedConfig.deliverPolicy;
     }
     if (orderedConfig?.optStartSeq !== void 0) {
@@ -1813,12 +2237,26 @@ 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);
+    this.monitorConsumerHealth(messages, consumerName2);
     try {
       for await (const msg of messages) {
         target$.next(msg);
@@ -1827,6 +2265,17 @@ var MessageProvider = class {
       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) {
@@ -1838,6 +2287,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}`);
@@ -1923,8 +2373,110 @@ var MessageProvider = class {
   }
 };
 
+// src/server/infrastructure/metadata.provider.ts
+var import_common9 = require("@nestjs/common");
+var import_kv = require("@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 import_common9.Logger("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 import_kv.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
-var import_common8 = require("@nestjs/common");
+var import_common10 = require("@nestjs/common");
 var HANDLER_LABELS = {
   ["broadcast" /* Broadcast */]: "broadcast" /* Broadcast */,
   ["ordered" /* Ordered */]: "ordered" /* Ordered */,
@@ -1935,7 +2487,7 @@ var PatternRegistry = class {
   constructor(options) {
     this.options = options;
   }
-  logger = new import_common8.Logger("Jetstream:PatternRegistry");
+  logger = new import_common10.Logger("Jetstream:PatternRegistry");
   registry = /* @__PURE__ */ new Map();
   // Cached after registerHandlers() — the registry is immutable from that point
   cachedPatterns = null;
@@ -1943,6 +2495,7 @@ var PatternRegistry = class {
   _hasCommands = false;
   _hasBroadcasts = false;
   _hasOrdered = false;
+  _hasMetadata = false;
   /**
    * Register all handlers from the NestJS strategy.
    *
@@ -1955,6 +2508,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.`
@@ -1971,7 +2525,8 @@ var PatternRegistry = class {
         pattern,
         isEvent: isEvent && !isOrdered,
         isBroadcast,
-        isOrdered
+        isOrdered,
+        meta
       });
       this.logger.debug(`Registered ${HANDLER_LABELS[kind]}: ${pattern} -> ${fullSubject}`);
     }
@@ -1980,6 +2535,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. */
@@ -2008,6 +2564,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();
@@ -2047,6 +2623,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 = [
@@ -2062,10 +2644,11 @@ var PatternRegistry = class {
 };
 
 // src/server/routing/event.router.ts
-var import_common9 = require("@nestjs/common");
+var import_common11 = require("@nestjs/common");
 var import_rxjs4 = require("rxjs");
+var import_transport_node4 = require("@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;
@@ -2073,8 +2656,10 @@ var EventRouter = class {
     this.deadLetterConfig = deadLetterConfig;
     this.processingConfig = processingConfig;
     this.ackWaitMap = ackWaitMap;
+    this.connection = connection;
+    this.options = options;
   }
-  logger = new import_common9.Logger("Jetstream:EventRouter");
+  logger = new import_common11.Logger("Jetstream:EventRouter");
   subscriptions = [];
   /**
    * Update the max_deliver thresholds from actual NATS consumer configs.
@@ -2201,6 +2786,93 @@ var EventRouter = class {
     return msg.info.deliveryCount >= maxDeliver;
   }
   /** 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;
+    }
+    try {
+      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();
+    }
+  }
+  /**
+   * 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;
+    }
+    const destinationSubject = dlqStreamName(serviceName);
+    const hdrs = (0, import_transport_node4.headers)();
+    if (msg.headers) {
+      for (const [k, v] of msg.headers) {
+        for (const val of v) {
+          hdrs.append(k, val);
+        }
+      }
+    }
+    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 {
+      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
+          );
+        }
+      }
+      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);
+    }
+  }
+  /**
+   * 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,
@@ -2213,23 +2885,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
-var import_common10 = require("@nestjs/common");
-var import_transport_node4 = require("@nats-io/transport-node");
+var import_common12 = require("@nestjs/common");
+var import_transport_node5 = require("@nats-io/transport-node");
 var import_rxjs5 = require("rxjs");
 var RpcRouter = class {
   constructor(messageProvider, patternRegistry, connection, codec, eventBus, rpcOptions, ackWaitMap) {
@@ -2243,7 +2909,7 @@ var RpcRouter = class {
     this.timeout = rpcOptions?.timeout ?? DEFAULT_JETSTREAM_RPC_TIMEOUT;
     this.concurrency = rpcOptions?.concurrency;
   }
-  logger = new import_common10.Logger("Jetstream:RpcRouter");
+  logger = new import_common12.Logger("Jetstream:RpcRouter");
   timeout;
   concurrency;
   resolvedAckExtensionInterval;
@@ -2321,7 +2987,7 @@ var RpcRouter = class {
       stopAckExtension?.();
       msg.ack();
       try {
-        const hdrs = (0, import_transport_node4.headers)();
+        const hdrs = (0, import_transport_node5.headers)();
         hdrs.set("x-correlation-id" /* CorrelationId */, correlationId);
         nc.publish(replyTo, this.codec.encode(result), { headers: hdrs });
       } catch (publishErr) {
@@ -2333,7 +2999,7 @@ var RpcRouter = class {
       clearTimeout(timeoutId);
       stopAckExtension?.();
       try {
-        const hdrs = (0, import_transport_node4.headers)();
+        const hdrs = (0, import_transport_node5.headers)();
         hdrs.set("x-correlation-id" /* CorrelationId */, correlationId);
         hdrs.set("x-error" /* Error */, "true");
         nc.publish(replyTo, this.codec.encode(serializeError(err)), { headers: hdrs });
@@ -2346,20 +3012,27 @@ var RpcRouter = class {
 };
 
 // src/shutdown/shutdown.manager.ts
-var import_common11 = require("@nestjs/common");
+var import_common13 = require("@nestjs/common");
 var ShutdownManager = class {
   constructor(connection, eventBus, timeout) {
     this.connection = connection;
     this.eventBus = eventBus;
     this.timeout = timeout;
   }
-  logger = new import_common11.Logger("Jetstream:Shutdown");
+  logger = new import_common13.Logger("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();
@@ -2494,7 +3167,7 @@ var JetstreamModule = class {
         provide: JETSTREAM_EVENT_BUS,
         inject: [JETSTREAM_OPTIONS],
         useFactory: (options) => {
-          const logger = new import_common12.Logger("Jetstream:Module");
+          const logger = new import_common14.Logger("Jetstream:Module");
           return new EventBus(logger, options.hooks);
         }
       },
@@ -2573,8 +3246,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)
@@ -2584,7 +3257,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
@@ -2596,9 +3273,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(),
@@ -2621,7 +3299,9 @@ var JetstreamModule = class {
             eventBus,
             deadLetterConfig,
             processingConfig,
-            ackWaitMap
+            ackWaitMap,
+            connection,
+            options
           );
         }
       },
@@ -2670,6 +3350,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,
@@ -2683,9 +3372,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,
@@ -2697,7 +3387,8 @@ var JetstreamModule = class {
             eventRouter,
             rpcRouter,
             coreRpcServer,
-            ackWaitMap
+            ackWaitMap,
+            metadataProvider
           );
         }
       }
@@ -2756,21 +3447,26 @@ var JetstreamModule = class {
   }
 };
 JetstreamModule = __decorateClass([
-  (0, import_common12.Global)(),
-  (0, import_common12.Module)({}),
-  __decorateParam(0, (0, import_common12.Optional)()),
-  __decorateParam(0, (0, import_common12.Inject)(ShutdownManager)),
-  __decorateParam(1, (0, import_common12.Optional)()),
-  __decorateParam(1, (0, import_common12.Inject)(JetstreamStrategy))
+  (0, import_common14.Global)(),
+  (0, import_common14.Module)({}),
+  __decorateParam(0, (0, import_common14.Optional)()),
+  __decorateParam(0, (0, import_common14.Inject)(ShutdownManager)),
+  __decorateParam(1, (0, import_common14.Optional)()),
+  __decorateParam(1, (0, import_common14.Inject)(JetstreamStrategy))
 ], JetstreamModule);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DEFAULT_METADATA_BUCKET,
+  DEFAULT_METADATA_HISTORY,
+  DEFAULT_METADATA_REPLICAS,
+  DEFAULT_METADATA_TTL,
   EventBus,
   JETSTREAM_CODEC,
   JETSTREAM_CONNECTION,
   JETSTREAM_EVENT_BUS,
   JETSTREAM_OPTIONS,
   JetstreamClient,
+  JetstreamDlqHeader,
   JetstreamHeader,
   JetstreamHealthIndicator,
   JetstreamModule,
@@ -2778,17 +3474,21 @@ JetstreamModule = __decorateClass([
   JetstreamRecordBuilder,
   JetstreamStrategy,
   JsonCodec,
+  MIN_METADATA_TTL,
   MessageKind,
   PatternPrefix,
   RpcContext,
   StreamKind,
   TransportEvent,
+  buildBroadcastSubject,
   buildSubject,
   consumerName,
+  dlqStreamName,
   getClientToken,
   internalName,
   isCoreRpcMode,
   isJetStreamRpcMode,
+  metadataKey,
   streamName,
   toNanos
 });