@horizon-republic/nestjs-jetstream 2.7.1 → 2.9.0

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";
@@ -24,9 +24,9 @@ import { Logger } from "@nestjs/common";
 import { ClientProxy } from "@nestjs/microservices";
 import {
   createInbox,
-  Events,
   headers as natsHeaders
-} from "nats";
+} from "@nats-io/transport-node";
+import { nuid } from "@nats-io/nuid";
 
 // src/interfaces/hooks.interface.ts
 var MessageKind = /* @__PURE__ */ ((MessageKind2) => {
@@ -65,7 +65,7 @@ import {
   RetentionPolicy,
   StorageType,
   StoreCompression
-} from "nats";
+} from "@nats-io/jetstream";
 var JETSTREAM_OPTIONS = /* @__PURE__ */ Symbol("JETSTREAM_OPTIONS");
 var JETSTREAM_CONNECTION = /* @__PURE__ */ Symbol("JETSTREAM_CONNECTION");
 var JETSTREAM_CODEC = /* @__PURE__ */ Symbol("JETSTREAM_CODEC");
@@ -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,11 +226,13 @@ var isCoreRpcMode = (rpc) => !rpc || rpc.mode === "core";
 
 // src/client/jetstream.record.ts
 var JetstreamRecord = class {
-  constructor(data, headers2, timeout, messageId) {
+  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 {
@@ -209,6 +240,8 @@ var JetstreamRecordBuilder = class {
   headers = /* @__PURE__ */ new Map();
   timeout;
   messageId;
+  scheduleOptions;
+  ttlDuration;
   constructor(data) {
     this.data = data;
   }
@@ -276,17 +309,71 @@ var JetstreamRecordBuilder = class {
     this.timeout = ms;
     return this;
   }
+  /**
+   * Schedule one-shot delayed delivery.
+   *
+   * The message is held by NATS and delivered to the event consumer
+   * at the specified time. Requires NATS >= 2.12 and `allow_msg_schedules: true`
+   * on the event stream (via `events: { stream: { allow_msg_schedules: true } }`).
+   *
+   * Only meaningful for events (`client.emit()`). If used with RPC
+   * (`client.send()`), a warning is logged and the schedule is ignored.
+   *
+   * @param date - Delivery time. Must be in the future.
+   * @throws Error if the date is not in the future.
+   */
+  scheduleAt(date) {
+    const ts = date.getTime();
+    if (Number.isNaN(ts)) {
+      throw new Error("Schedule date is invalid");
+    }
+    if (ts <= Date.now()) {
+      throw new Error("Schedule date must be in the future");
+    }
+    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}.
    *
    * @returns A frozen record ready to pass to `client.send()` or `client.emit()`.
    */
   build() {
+    const schedule = this.scheduleOptions ? { at: new Date(this.scheduleOptions.at.getTime()) } : void 0;
     return new JetstreamRecord(
       this.data,
       new Map(this.headers),
       this.timeout,
-      this.messageId
+      this.messageId,
+      schedule,
+      this.ttlDuration
     );
   }
   /** Validate that a header key is not reserved. */
@@ -298,6 +385,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 ClientProxy {
@@ -338,7 +436,7 @@ var JetstreamClient = class extends ClientProxy {
       this.setupInbox(nc);
     }
     this.statusSubscription ??= this.connection.status$.subscribe((status) => {
-      if (status.type === Events.Disconnect) {
+      if (status.type === "disconnect") {
         this.handleDisconnect();
       }
     });
@@ -366,19 +464,40 @@ var JetstreamClient = class extends ClientProxy {
    * Publish a fire-and-forget event to JetStream.
    *
    * Events are published to either the workqueue stream or broadcast stream
-   * depending on the subject prefix.
+   * depending on the subject prefix. When a schedule is present the message
+   * is published to a `_sch` subject within the same stream, with the target
+   * set to the original event subject.
    */
   async dispatchEvent(packet) {
     await this.connect();
-    const { data, hdrs, messageId } = this.extractRecordData(packet.data);
-    const subject = this.buildEventSubject(packet.pattern);
-    const msgHeaders = this.buildHeaders(hdrs, { subject });
-    const ack = await this.connection.getJetStreamClient().publish(subject, this.codec.encode(data), {
-      headers: msgHeaders,
-      msgID: messageId ?? crypto.randomUUID()
-    });
-    if (ack.duplicate) {
-      this.logger.warn(`Duplicate event publish detected: ${subject} (seq: ${ack.seq})`);
+    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) {
+      const scheduleSubject = this.buildScheduleSubject(eventSubject);
+      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
+        }
+      });
+      if (ack.duplicate) {
+        this.logger.warn(
+          `Duplicate scheduled publish detected: ${scheduleSubject} (seq: ${ack.seq})`
+        );
+      }
+    } else {
+      const ack = await this.connection.getJetStreamClient().publish(eventSubject, this.codec.encode(data), {
+        headers: msgHeaders,
+        msgID: messageId ?? nuid.next(),
+        ttl
+      });
+      if (ack.duplicate) {
+        this.logger.warn(`Duplicate event publish detected: ${eventSubject} (seq: ${ack.seq})`);
+      }
     }
     return void 0;
   }
@@ -390,7 +509,17 @@ var JetstreamClient = class extends ClientProxy {
    */
   publish(packet, callback) {
     const subject = buildSubject(this.targetName, "cmd" /* Command */, packet.pattern);
-    const { data, hdrs, timeout, messageId } = 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 });
@@ -399,7 +528,7 @@ var JetstreamClient = class extends ClientProxy {
     if (isCoreRpcMode(this.rootOptions.rpc)) {
       this.publishCoreRpc(subject, data, hdrs, timeout, callback).catch(onUnhandled);
     } else {
-      jetStreamCorrelationId = crypto.randomUUID();
+      jetStreamCorrelationId = nuid.next();
       this.publishJetStreamRpc(subject, data, callback, {
         headers: hdrs,
         timeout,
@@ -474,7 +603,7 @@ var JetstreamClient = class extends ClientProxy {
       });
       await this.connection.getJetStreamClient().publish(subject, this.codec.encode(data), {
         headers: hdrs,
-        msgID: messageId ?? crypto.randomUUID()
+        msgID: messageId ?? nuid.next()
       });
     } catch (err) {
       const existingTimeout = this.pendingTimeouts.get(correlationId);
@@ -506,6 +635,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) {
@@ -587,17 +717,53 @@ var JetstreamClient = class extends ClientProxy {
     }
     return hdrs;
   }
-  /** Extract data, headers, and timeout from raw packet data or JetstreamRecord. */
+  /** Extract data, headers, timeout, and schedule from raw packet data or JetstreamRecord. */
   extractRecordData(rawData) {
     if (rawData instanceof JetstreamRecord) {
       return {
         data: rawData.data,
         hdrs: rawData.headers.size > 0 ? new Map(rawData.headers) : null,
         timeout: rawData.timeout,
-        messageId: rawData.messageId
+        messageId: rawData.messageId,
+        schedule: rawData.schedule,
+        ttl: rawData.ttl
       };
     }
-    return { data: rawData, hdrs: null, timeout: void 0, messageId: void 0 };
+    return {
+      data: rawData,
+      hdrs: null,
+      timeout: void 0,
+      messageId: void 0,
+      schedule: void 0,
+      ttl: void 0
+    };
+  }
+  /**
+   * Build a schedule-holder subject for NATS message scheduling.
+   *
+   * The schedule-holder subject resides in the same stream as the target but
+   * uses a separate `_sch` namespace that is NOT matched by any consumer filter.
+   * NATS holds the message and publishes it to the target subject after the delay.
+   *
+   * Examples:
+   * - `{svc}__microservice.ev.order.reminder` → `{svc}__microservice._sch.order.reminder`
+   * - `broadcast.config.updated` → `broadcast._sch.config.updated`
+   */
+  buildScheduleSubject(eventSubject) {
+    if (eventSubject.startsWith("broadcast.")) {
+      return eventSubject.replace("broadcast.", "broadcast._sch.");
+    }
+    const targetPrefix = `${internalName(this.targetName)}.`;
+    if (!eventSubject.startsWith(targetPrefix)) {
+      throw new Error(`Unexpected event subject format: ${eventSubject}`);
+    }
+    const withoutPrefix = eventSubject.slice(targetPrefix.length);
+    const dotIndex = withoutPrefix.indexOf(".");
+    if (dotIndex === -1) {
+      throw new Error(`Event subject missing pattern segment: ${eventSubject}`);
+    }
+    const pattern = withoutPrefix.slice(dotIndex + 1);
+    return `${targetPrefix}_sch.${pattern}`;
   }
   getRpcTimeout() {
     if (!this.rootOptions.rpc) return DEFAULT_RPC_TIMEOUT;
@@ -607,25 +773,26 @@ var JetstreamClient = class extends ClientProxy {
 };
 
 // src/codec/json.codec.ts
-import { JSONCodec as NatsJSONCodec } from "nats";
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
 var JsonCodec = class {
-  inner = NatsJSONCodec();
   encode(data) {
-    return this.inner.encode(data);
+    return encoder.encode(JSON.stringify(data));
   }
   decode(data) {
-    return this.inner.decode(data);
+    return JSON.parse(decoder.decode(data));
   }
 };
 
 // src/connection/connection.provider.ts
 import { Logger as Logger2 } from "@nestjs/common";
 import {
-  connect,
-  DebugEvents,
-  Events as Events2,
-  NatsError
-} from "nats";
+  connect
+} from "@nats-io/transport-node";
+import {
+  jetstream,
+  jetstreamManager
+} from "@nats-io/jetstream";
 import { defer, from, share, shareReplay, switchMap } from "rxjs";
 var DEFAULT_OPTIONS = {
   maxReconnectAttempts: -1,
@@ -679,14 +846,7 @@ var ConnectionProvider = class {
   async getJetStreamManager() {
     if (this.jsmInstance) return this.jsmInstance;
     if (this.jsmPromise) return this.jsmPromise;
-    this.jsmPromise = (async () => {
-      const nc = await this.getConnection();
-      this.jsmInstance = await nc.jetstreamManager();
-      this.logger.log("JetStream manager initialized");
-      return this.jsmInstance;
-    })().finally(() => {
-      this.jsmPromise = null;
-    });
+    this.jsmPromise = this.initJetStreamManager();
     return this.jsmPromise;
   }
   /**
@@ -702,7 +862,7 @@ var ConnectionProvider = class {
     if (!this.connection || this.connection.isClosed()) {
       throw new Error("Not connected \u2014 call getConnection() before getJetStreamClient()");
     }
-    this.jsClient ??= this.connection.jetstream();
+    this.jsClient ??= jetstream(this.connection);
     return this.jsClient;
   }
   /** Direct access to the raw NATS connection, or `null` if not yet connected. */
@@ -738,6 +898,16 @@ var ConnectionProvider = class {
       this.jsmPromise = null;
     }
   }
+  async initJetStreamManager() {
+    try {
+      const nc = await this.getConnection();
+      this.jsmInstance = await jetstreamManager(nc);
+      this.logger.log("JetStream manager initialized");
+      return this.jsmInstance;
+    } finally {
+      this.jsmPromise = null;
+    }
+  }
   /** Internal: establish the physical connection with reconnect monitoring. */
   async establish() {
     const name = internalName(this.options.name);
@@ -754,7 +924,7 @@ var ConnectionProvider = class {
       this.monitorStatus(nc);
       return nc;
     } catch (err) {
-      if (err instanceof NatsError && err.code === "CONNECTION_REFUSED") {
+      if (err instanceof Error && err.message.includes("REFUSED")) {
         throw new Error(`NATS connection refused: ${this.options.servers.join(", ")}`);
       }
       throw err;
@@ -762,27 +932,33 @@ var ConnectionProvider = class {
   }
   /** Subscribe to connection status events and emit hooks. */
   monitorStatus(nc) {
-    (async () => {
+    void (async () => {
       for await (const status of nc.status()) {
         switch (status.type) {
-          case Events2.Disconnect:
+          case "disconnect":
             this.eventBus.emit("disconnect" /* Disconnect */);
             break;
-          case Events2.Reconnect:
+          case "reconnect":
             this.jsClient = null;
             this.jsmInstance = null;
             this.jsmPromise = null;
             this.eventBus.emit("reconnect" /* Reconnect */, nc.getServer());
             break;
-          case Events2.Error:
-            this.eventBus.emit("error" /* Error */, new Error(String(status.data)), "connection");
+          case "error":
+            this.eventBus.emit(
+              "error" /* Error */,
+              status.error,
+              "connection"
+            );
             break;
-          case Events2.Update:
-          case Events2.LDM:
-          case DebugEvents.Reconnecting:
-          case DebugEvents.PingTimer:
-          case DebugEvents.StaleConnection:
-          case DebugEvents.ClientInitiatedReconnect:
+          case "update":
+          case "ldm":
+          case "reconnecting":
+          case "ping":
+          case "staleConnection":
+          case "forceReconnect":
+          case "slowConsumer":
+          case "close":
             break;
         }
       }
@@ -879,9 +1055,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();
@@ -891,8 +1072,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 };
@@ -905,7 +1088,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;
@@ -917,6 +1100,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
@@ -961,10 +1145,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();
@@ -1044,7 +1232,7 @@ var JetstreamStrategy = class extends Server {
 
 // src/server/core-rpc.server.ts
 import { Logger as Logger4 } from "@nestjs/common";
-import { headers as natsHeaders2 } from "nats";
+import { headers as natsHeaders2 } from "@nats-io/transport-node";
 
 // src/context/rpc.context.ts
 import { BaseRpcContext } from "@nestjs/microservices";
@@ -1340,24 +1528,172 @@ 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/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 { NatsError as NatsError2 } from "nats";
-var STREAM_NOT_FOUND = 10059;
+import { JetStreamApiError } from "@nats-io/jetstream";
+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) {
@@ -1367,12 +1703,22 @@ var StreamProvider = class {
   getSubjects(kind) {
     const name = internalName(this.options.name);
     switch (kind) {
-      case "ev" /* Event */:
-        return [`${name}.${"ev" /* Event */}.>`];
+      case "ev" /* Event */: {
+        const subjects = [`${name}.${"ev" /* Event */}.>`];
+        if (this.isSchedulingEnabled(kind)) {
+          subjects.push(`${name}._sch.>`);
+        }
+        return subjects;
+      }
       case "cmd" /* Command */:
         return [`${name}.${"cmd" /* Command */}.>`];
-      case "broadcast" /* Broadcast */:
-        return ["broadcast.>"];
+      case "broadcast" /* Broadcast */: {
+        const subjects = ["broadcast.>"];
+        if (this.isSchedulingEnabled(kind)) {
+          subjects.push("broadcast._sch.>");
+        }
+        return subjects;
+      }
       case "ordered" /* Ordered */:
         return [`${name}.${"ordered" /* Ordered */}.>`];
     }
@@ -1382,17 +1728,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 NatsError2 && err.api_error?.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);
@@ -1408,6 +1822,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) {
@@ -1421,25 +1855,49 @@ var StreamProvider = class {
         return DEFAULT_ORDERED_STREAM_CONFIG;
     }
   }
-  /** Get user-provided overrides for a stream kind. */
+  /** Check if scheduling is enabled for a stream kind via `allow_msg_schedules` override. */
+  isSchedulingEnabled(kind) {
+    const overrides = this.getOverrides(kind);
+    return overrides.allow_msg_schedules === true;
+  }
+  /** 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 { NatsError as NatsError3 } from "nats";
-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;
@@ -1447,7 +1905,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.
    *
@@ -1468,7 +1926,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);
@@ -1479,13 +1941,74 @@ var ConsumerProvider = class {
       this.logger.debug(`Consumer exists, updating: ${name}`);
       return await jsm.consumers.update(stream, name, config);
     } catch (err) {
-      if (err instanceof NatsError3 && err.api_error?.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) {
@@ -1538,6 +2061,11 @@ 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}`);
+      }
     }
   }
   /** Get user-provided overrides for a consumer kind. */
@@ -1551,16 +2079,18 @@ 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}`);
+      }
     }
   }
 };
 
 // src/server/infrastructure/message.provider.ts
-import { Logger as Logger7 } from "@nestjs/common";
-import {
-  ConsumerEvents,
-  DeliverPolicy as DeliverPolicy2
-} from "nats";
+import { Logger as Logger8 } from "@nestjs/common";
+import { DeliverPolicy as DeliverPolicy2 } from "@nats-io/jetstream";
 import {
   catchError,
   defer as defer2,
@@ -1573,12 +2103,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;
@@ -1629,7 +2160,7 @@ var MessageProvider = class {
    * @param orderedConfig - Optional overrides for ordered consumer options.
    */
   async startOrdered(streamName2, filterSubjects, orderedConfig) {
-    const consumerOpts = { filterSubjects };
+    const consumerOpts = { filter_subjects: filterSubjects };
     if (orderedConfig?.deliverPolicy !== void 0 && orderedConfig.deliverPolicy !== DeliverPolicy2.All) {
       consumerOpts.deliver_policy = orderedConfig.deliverPolicy;
     }
@@ -1681,12 +2212,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);
@@ -1695,6 +2240,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) {
@@ -1706,6 +2262,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}`);
@@ -1714,10 +2271,10 @@ var MessageProvider = class {
   }
   /** Monitor heartbeats and restart the consumer iterator on prolonged silence. */
   monitorConsumerHealth(messages, name) {
-    (async () => {
-      for await (const status of await messages.status()) {
-        if (status.type === ConsumerEvents.HeartbeatsMissed && status.data >= 2) {
-          this.logger.warn(`Consumer ${name}: ${status.data} heartbeats missed, restarting`);
+    void (async () => {
+      for await (const status of messages.status()) {
+        if (status.type === "heartbeats_missed" && status.count >= 2) {
+          this.logger.warn(`Consumer ${name}: ${status.count} heartbeats missed, restarting`);
           messages.stop();
           break;
         }
@@ -1791,8 +2348,110 @@ var MessageProvider = class {
   }
 };
 
+// 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 */,
@@ -1803,7 +2462,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;
@@ -1811,6 +2470,7 @@ var PatternRegistry = class {
   _hasCommands = false;
   _hasBroadcasts = false;
   _hasOrdered = false;
+  _hasMetadata = false;
   /**
    * Register all handlers from the NestJS strategy.
    *
@@ -1823,6 +2483,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.`
@@ -1839,7 +2500,8 @@ var PatternRegistry = class {
         pattern,
         isEvent: isEvent && !isOrdered,
         isBroadcast,
-        isOrdered
+        isOrdered,
+        meta
       });
       this.logger.debug(`Registered ${HANDLER_LABELS[kind]}: ${pattern} -> ${fullSubject}`);
     }
@@ -1848,6 +2510,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. */
@@ -1876,6 +2539,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();
@@ -1915,6 +2598,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 = [
@@ -1930,10 +2619,11 @@ var PatternRegistry = class {
 };
 
 // src/server/routing/event.router.ts
-import { Logger as Logger9 } from "@nestjs/common";
+import { Logger as Logger11 } from "@nestjs/common";
 import { concatMap, from as from2, mergeMap } from "rxjs";
+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;
@@ -1941,8 +2631,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.
@@ -2069,6 +2761,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 = natsHeaders3();
+    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,
@@ -2081,23 +2860,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 { headers } from "nats";
+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) {
@@ -2111,7 +2884,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;
@@ -2214,20 +2987,27 @@ var RpcRouter = class {
 };
 
 // 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();
@@ -2362,7 +3142,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);
         }
       },
@@ -2441,8 +3221,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)
@@ -2452,7 +3232,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
@@ -2464,9 +3248,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(),
@@ -2489,7 +3274,9 @@ var JetstreamModule = class {
             eventBus,
             deadLetterConfig,
             processingConfig,
-            ackWaitMap
+            ackWaitMap,
+            connection,
+            options
           );
         }
       },
@@ -2538,6 +3325,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,
@@ -2551,9 +3347,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,
@@ -2565,7 +3362,8 @@ var JetstreamModule = class {
             eventRouter,
             rpcRouter,
             coreRpcServer,
-            ackWaitMap
+            ackWaitMap,
+            metadataProvider
           );
         }
       }
@@ -2632,12 +3430,17 @@ JetstreamModule = __decorateClass([
   __decorateParam(1, Inject(JetstreamStrategy))
 ], JetstreamModule);
 export {
+  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,
@@ -2645,17 +3448,21 @@ export {
   JetstreamRecordBuilder,
   JetstreamStrategy,
   JsonCodec,
+  MIN_METADATA_TTL,
   MessageKind,
   PatternPrefix,
   RpcContext,
   StreamKind,
   TransportEvent,
+  buildBroadcastSubject,
   buildSubject,
   consumerName,
+  dlqStreamName,
   getClientToken,
   internalName,
   isCoreRpcMode,
   isJetStreamRpcMode,
+  metadataKey,
   streamName,
   toNanos
 };