@horizon-republic/nestjs-jetstream 2.12.1 → 2.13.0

package/dist/index.js

@@ -14,18 +14,17 @@ var __decorateParam = (index, decorator) => (target, key) => decorator(target, k
 import {
   Global,
   Inject as Inject2,
-  Logger as Logger20,
+  Logger as Logger23,
   Module as Module2,
   Optional as Optional2
 } from "@nestjs/common";
 
 // src/client/jetstream.client.ts
-import { Logger as Logger5 } from "@nestjs/common";
+import { Logger as Logger6 } from "@nestjs/common";
 import { ClientProxy } from "@nestjs/microservices";
 import { context as context6 } from "@opentelemetry/api";
 import { nuid } from "@nats-io/nuid";
 import {
-  createInbox,
   headers as natsHeaders,
   TimeoutError
 } from "@nats-io/transport-node";
@@ -53,6 +52,13 @@ var TransportEvent = /* @__PURE__ */ ((TransportEvent2) => {
   return TransportEvent2;
 })(TransportEvent || {});
 
+// src/interfaces/options.interface.ts
+var ManagementMode = /* @__PURE__ */ ((ManagementMode2) => {
+  ManagementMode2["Auto"] = "auto";
+  ManagementMode2["Manual"] = "manual";
+  return ManagementMode2;
+})(ManagementMode || {});
+
 // src/interfaces/stream.interface.ts
 var StreamKind = /* @__PURE__ */ ((StreamKind2) => {
   StreamKind2["Event"] = "ev";
@@ -210,8 +216,27 @@ var RESERVED_HEADERS = /* @__PURE__ */ new Set([
 ]);
 var NATS_CONTROL_HEADER_PREFIX = "nats-";
 var internalName = (name) => `${name}__microservice`;
-var buildSubject = (serviceName, kind, pattern) => `${internalName(serviceName)}.${kind}.${pattern}`;
-var buildBroadcastSubject = (pattern) => `broadcast.${pattern}`;
+var subjectPrefix = (serviceName, kind) => `${internalName(serviceName)}.${kind}.`;
+var buildSubject = (serviceName, kind, pattern) => `${subjectPrefix(serviceName, kind)}${pattern}`;
+var BROADCAST_SUBJECT_PREFIX = "broadcast.";
+var SCHEDULE_SEGMENT = "_sch.";
+var buildBroadcastSubject = (pattern) => `${BROADCAST_SUBJECT_PREFIX}${pattern}`;
+var conventionScheduleSubjectBase = (targetName, eventSubject) => {
+  if (eventSubject.startsWith(BROADCAST_SUBJECT_PREFIX)) {
+    const bare = eventSubject.slice(BROADCAST_SUBJECT_PREFIX.length);
+    return `${BROADCAST_SUBJECT_PREFIX}${SCHEDULE_SEGMENT}${bare}`;
+  }
+  const targetPrefix = `${internalName(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}`);
+  }
+  return `${targetPrefix}${SCHEDULE_SEGMENT}${withoutPrefix.slice(dotIndex + 1)}`;
+};
 var streamName = (serviceName, kind) => {
   if (kind === "broadcast" /* Broadcast */) return "broadcast-stream";
   return `${internalName(serviceName)}_${kind}-stream`;
@@ -231,6 +256,118 @@ var PatternPrefix = /* @__PURE__ */ ((PatternPrefix2) => {
 var isJetStreamRpcMode = (rpc) => rpc?.mode === "jetstream";
 var isCoreRpcMode = (rpc) => !rpc || rpc.mode === "core";
 
+// src/server/infrastructure/management.ts
+var kindOptionsBlock = (options, kind) => {
+  switch (kind) {
+    case "ev" /* Event */:
+      return options.events;
+    case "broadcast" /* Broadcast */:
+      return options.broadcast;
+    case "ordered" /* Ordered */:
+      return options.ordered;
+    case "cmd" /* Command */:
+      return isJetStreamRpcMode(options.rpc) ? options.rpc : void 0;
+    /* v8 ignore next 5 -- exhaustive switch guard, unreachable */
+    default: {
+      const _exhaustive = kind;
+      throw new Error(`Unhandled StreamKind: ${String(_exhaustive)}`);
+    }
+  }
+};
+var entityManagementFor = (options, kind) => {
+  if (kind === "dlq") return options.dlq?.management;
+  return kindOptionsBlock(options, kind)?.management;
+};
+var resolveManagementMode = (options, kind, entity) => entityManagementFor(options, kind)?.[entity] ?? options.provisioning?.management ?? "auto" /* Auto */;
+
+// src/server/infrastructure/name-resolver.ts
+var NameResolver = class {
+  constructor(options) {
+    this.options = options;
+    this.dlq = options.dlq?.stream?.name ?? dlqStreamName(options.name);
+    this.kinds = this.buildKindMap();
+  }
+  kinds;
+  dlq;
+  streamName(kind) {
+    return this.get(kind).stream;
+  }
+  consumerName(kind) {
+    return this.get(kind).consumer;
+  }
+  dlqStreamName() {
+    return this.dlq;
+  }
+  subject(kind, pattern) {
+    return `${this.get(kind).prefix}${pattern}`;
+  }
+  filterSubject(kind) {
+    return `${this.get(kind).prefix}>`;
+  }
+  schedulePrefix(kind) {
+    return this.get(kind).schedulePrefix;
+  }
+  hasCustomPrefix(kind) {
+    return this.get(kind).custom;
+  }
+  /**
+   * Map a resolved event subject back to its schedule-holder base subject
+   * (the `_sch` namespace twin, without the per-message unique suffix).
+   */
+  scheduleSubjectBase(eventSubject) {
+    for (const kind of ["broadcast" /* Broadcast */, "ev" /* Event */, "ordered" /* Ordered */]) {
+      const { prefix, schedulePrefix } = this.get(kind);
+      if (eventSubject.startsWith(prefix)) {
+        return `${schedulePrefix}${eventSubject.slice(prefix.length)}`;
+      }
+    }
+    throw new Error(`Unexpected event subject format: ${eventSubject}`);
+  }
+  get(kind) {
+    const entry = this.kinds.get(kind);
+    if (!entry) throw new Error(`Unknown StreamKind: ${String(kind)}`);
+    return entry;
+  }
+  buildKindMap() {
+    const map = /* @__PURE__ */ new Map();
+    const { name } = this.options;
+    for (const kind of Object.values(StreamKind)) {
+      const block = kindOptionsBlock(this.options, kind);
+      const customPrefix = block?.subjectPrefix;
+      const custom = customPrefix !== void 0;
+      const prefix = custom ? this.normalizePrefix(customPrefix) : this.conventionPrefix(name, kind);
+      map.set(kind, {
+        stream: block?.stream?.name ?? streamName(name, kind),
+        consumer: block?.consumer?.durable_name ?? consumerName(name, kind),
+        prefix,
+        schedulePrefix: custom ? `${prefix}${SCHEDULE_SEGMENT}` : this.conventionSchedulePrefix(name, kind),
+        custom
+      });
+    }
+    return map;
+  }
+  normalizePrefix(raw) {
+    let end = raw.length;
+    while (end > 0 && raw[end - 1] === ".") end -= 1;
+    const trimmed = raw.slice(0, end);
+    const tokens = trimmed.split(".");
+    if (trimmed.length === 0 || tokens.some((t) => t.length === 0 || t === ">")) {
+      throw new Error(
+        `Invalid subjectPrefix "${raw}": expected non-empty dot-separated tokens without ">".`
+      );
+    }
+    return `${trimmed}.`;
+  }
+  conventionPrefix(name, kind) {
+    if (kind === "broadcast" /* Broadcast */) return BROADCAST_SUBJECT_PREFIX;
+    return subjectPrefix(name, kind);
+  }
+  conventionSchedulePrefix(name, kind) {
+    if (kind === "broadcast" /* Broadcast */) return `${BROADCAST_SUBJECT_PREFIX}${SCHEDULE_SEGMENT}`;
+    return `${internalName(name)}.${SCHEDULE_SEGMENT}`;
+  }
+};
+
 // src/otel/constants.ts
 var TRACER_NAME = "@horizon-republic/nestjs-jetstream";
 
@@ -533,7 +670,7 @@ var extractContext = (ctx, carrier, getter) => propagation.extract(ctx, carrier,
 
 // src/otel/tracer.ts
 import { trace } from "@opentelemetry/api";
-var PACKAGE_VERSION = true ? "2.12.1" : "0.0.0";
+var PACKAGE_VERSION = true ? "2.13.0" : "0.0.0";
 var getTracer = () => trace.getTracer(TRACER_NAME, PACKAGE_VERSION);
 
 // src/otel/carrier.ts
@@ -1337,17 +1474,137 @@ var nanosToGoDuration = (nanos) => {
   return `${nanos}ns`;
 };
 
+// src/client/rpc-reply-inbox.ts
+import { Logger as Logger5 } from "@nestjs/common";
+import {
+  createInbox
+} from "@nats-io/transport-node";
+var RpcReplyInbox = class {
+  constructor(codec, inboxPrefix) {
+    this.codec = codec;
+    this.inboxPrefix = inboxPrefix;
+  }
+  logger = new Logger5("Jetstream:RpcInbox");
+  inbox = null;
+  subscription = null;
+  pending = /* @__PURE__ */ new Map();
+  timeouts = /* @__PURE__ */ new Map();
+  /** Reply-to subject for outgoing requests; null until {@link setup} ran. */
+  get address() {
+    return this.inbox;
+  }
+  /** True while the inbox subscription is live. */
+  get active() {
+    return this.subscription !== null;
+  }
+  /** Create the inbox subject and subscribe reply routing on it. */
+  setup(nc) {
+    this.inbox = createInbox(this.inboxPrefix);
+    this.subscription = nc.subscribe(this.inbox, {
+      callback: (err, msg) => {
+        if (err) {
+          this.logger.error("Inbox subscription error:", err);
+          return;
+        }
+        this.route(msg);
+      }
+    });
+    this.logger.debug(`Inbox subscription: ${this.inbox}`);
+  }
+  /** Register the callback that settles the round-trip for `correlationId`. */
+  register(correlationId, callback) {
+    this.pending.set(correlationId, callback);
+  }
+  /**
+   * Arm the request deadline. When it fires while the request is still
+   * pending, both registry entries are removed before `onExpired` runs.
+   */
+  armTimeout(correlationId, ms, onExpired) {
+    const existing = this.timeouts.get(correlationId);
+    if (existing !== void 0) clearTimeout(existing);
+    const timeoutId = setTimeout(() => {
+      if (!this.pending.has(correlationId)) return;
+      this.timeouts.delete(correlationId);
+      this.pending.delete(correlationId);
+      onExpired();
+    }, ms);
+    this.timeouts.set(correlationId, timeoutId);
+  }
+  /** True while the request has not been settled or discarded. */
+  has(correlationId) {
+    return this.pending.has(correlationId);
+  }
+  /**
+   * Drop a request without invoking its callback: clears the deadline and
+   * returns whether the request was still pending.
+   */
+  discard(correlationId) {
+    const timeoutId = this.timeouts.get(correlationId);
+    if (timeoutId !== void 0) {
+      clearTimeout(timeoutId);
+      this.timeouts.delete(correlationId);
+    }
+    return this.pending.delete(correlationId);
+  }
+  /** Fail every pending request with `error` and tear the inbox down. */
+  rejectAll(error) {
+    for (const callback of this.pending.values()) {
+      callback({ err: error, response: null, isDisposed: true });
+    }
+    for (const timeoutId of this.timeouts.values()) {
+      clearTimeout(timeoutId);
+    }
+    this.pending.clear();
+    this.timeouts.clear();
+    this.subscription?.unsubscribe();
+    this.subscription = null;
+    this.inbox = null;
+  }
+  /** Route an inbox reply to the matching pending callback. */
+  route(msg) {
+    const correlationId = msg.headers?.get("x-correlation-id" /* CorrelationId */);
+    if (!correlationId) {
+      this.logger.warn("Inbox reply without correlation-id, ignoring");
+      return;
+    }
+    const callback = this.pending.get(correlationId);
+    if (!callback) {
+      this.logger.warn(`No pending handler for correlation-id: ${correlationId}`);
+      return;
+    }
+    const timeoutId = this.timeouts.get(correlationId);
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+      this.timeouts.delete(correlationId);
+    }
+    try {
+      const decoded = this.codec.decode(msg.data);
+      if (msg.headers?.get("x-error" /* Error */)) {
+        callback({ err: decoded, response: null, isDisposed: true });
+      } else {
+        callback({ err: null, response: decoded, isDisposed: true });
+      }
+    } catch (err) {
+      callback({
+        err: err instanceof Error ? err : new Error("Decode error"),
+        response: null,
+        isDisposed: true
+      });
+    } finally {
+      this.pending.delete(correlationId);
+    }
+  }
+};
+
 // src/client/jetstream.client.ts
-var BROADCAST_SUBJECT_PREFIX = "broadcast.";
 var detectEventKind = (pattern) => {
   if (pattern.startsWith("broadcast:" /* Broadcast */)) return "broadcast" /* Broadcast */;
   if (pattern.startsWith("ordered:" /* Ordered */)) return "ordered" /* Ordered */;
   return "event" /* Event */;
 };
-var declaredEventPattern = (pattern) => {
-  if (pattern.startsWith("broadcast:" /* Broadcast */))
-    return pattern.slice("broadcast:" /* Broadcast */.length);
-  if (pattern.startsWith("ordered:" /* Ordered */)) return pattern.slice("ordered:" /* Ordered */.length);
+var declaredEventPattern = (pattern, kind) => {
+  if (kind === "broadcast" /* Broadcast */) return pattern.slice("broadcast:" /* Broadcast */.length);
+  if (kind === "ordered" /* Ordered */) return pattern.slice("ordered:" /* Ordered */.length);
   return pattern;
 };
 var eventStreamKind = (kind) => {
@@ -1356,7 +1613,7 @@ var eventStreamKind = (kind) => {
   return "ev" /* Event */;
 };
 var JetstreamClient = class extends ClientProxy {
-  constructor(rootOptions, targetServiceName, connection, codec, eventBus) {
+  constructor(rootOptions, targetServiceName, connection, codec, eventBus, names) {
     super();
     this.rootOptions = rootOptions;
     this.connection = connection;
@@ -1364,29 +1621,34 @@ var JetstreamClient = class extends ClientProxy {
     this.eventBus = eventBus;
     this.targetName = targetServiceName;
     this.callerName = internalName(this.rootOptions.name);
+    const isSelf = targetServiceName === rootOptions.name;
+    const ownNames = names ?? (isSelf ? new NameResolver(rootOptions) : null);
+    this.selfNames = isSelf ? ownNames : null;
+    this.broadcastPrefix = ownNames ? ownNames.subject("broadcast" /* Broadcast */, "") : BROADCAST_SUBJECT_PREFIX;
     const targetInternal = internalName(targetServiceName);
     this.eventSubjectPrefix = `${targetInternal}.${"ev" /* Event */}.`;
     this.commandSubjectPrefix = `${targetInternal}.${"cmd" /* Command */}.`;
     this.orderedSubjectPrefix = `${targetInternal}.${"ordered" /* Ordered */}.`;
+    this.rpcInbox = new RpcReplyInbox(codec, this.callerName);
     this.isCoreMode = isCoreRpcMode(this.rootOptions.rpc);
-    this.defaultRpcTimeout = isJetStreamRpcMode(this.rootOptions.rpc) ? this.rootOptions.rpc?.timeout ?? DEFAULT_JETSTREAM_RPC_TIMEOUT : this.rootOptions.rpc?.timeout ?? DEFAULT_RPC_TIMEOUT;
+    this.defaultRpcTimeout = isJetStreamRpcMode(this.rootOptions.rpc) ? this.rootOptions.rpc.timeout ?? DEFAULT_JETSTREAM_RPC_TIMEOUT : this.rootOptions.rpc?.timeout ?? DEFAULT_RPC_TIMEOUT;
     const derived = deriveOtelAttrs(this.rootOptions);
     this.otel = derived.otel;
     this.serverEndpoint = derived.serverEndpoint;
   }
-  logger = new Logger5("Jetstream:Client");
+  logger = new Logger6("Jetstream:Client");
   /** Target service name this client sends messages to. */
   targetName;
   /** Pre-cached caller name derived from rootOptions.name, computed once in constructor. */
   callerName;
-  /**
-   * Subject prefixes of the form `{serviceName}__microservice.{kind}.` — one
-   * per stream kind this client may publish to. Built once in the constructor
-   * so producing a full subject is a single string concat with the user pattern.
-   */
+  /** Convention subject prefixes for foreign targets; one per stream kind. */
   eventSubjectPrefix;
   commandSubjectPrefix;
   orderedSubjectPrefix;
+  /** Broadcast subject prefix derived from the own resolver; never null. */
+  broadcastPrefix;
+  /** Resolver for self-target subjects; null when targeting a foreign service. */
+  selfNames;
   /**
    * RPC configuration snapshots. The values are derived from rootOptions at
    * construction time so the publish hot path never has to re-run
@@ -1398,13 +1660,8 @@ var JetstreamClient = class extends ClientProxy {
   otel;
   /** Server endpoint parts used for `server.address` / `server.port` span attributes. */
   serverEndpoint;
-  /** Shared inbox for JetStream-mode RPC responses. */
-  inbox = null;
-  inboxSubscription = null;
-  /** Pending JetStream-mode RPC callbacks, keyed by correlation ID. */
-  pendingMessages = /* @__PURE__ */ new Map();
-  /** Pending JetStream-mode RPC timeouts, keyed by correlation ID. */
-  pendingTimeouts = /* @__PURE__ */ new Map();
+  /** Reply inbox and pending-request registry for JetStream-mode RPC. */
+  rpcInbox;
   /** Subscription to connection status events for disconnect handling. */
   statusSubscription = null;
   /**
@@ -1423,8 +1680,8 @@ var JetstreamClient = class extends ClientProxy {
    */
   async connect() {
     const nc = await this.connection.getConnection();
-    if (!this.isCoreMode && !this.inboxSubscription) {
-      this.setupInbox(nc);
+    if (!this.isCoreMode && !this.rpcInbox.active) {
+      this.rpcInbox.setup(nc);
     }
     this.statusSubscription ??= this.connection.status$.subscribe((status) => {
       if (status.type === "disconnect") {
@@ -1439,7 +1696,7 @@ var JetstreamClient = class extends ClientProxy {
     this.statusSubscription?.unsubscribe();
     this.statusSubscription = null;
     this.readyForPublish = false;
-    this.rejectPendingRpcs(new Error("Client closed"));
+    this.rpcInbox.rejectAll(new Error("Client closed"));
   }
   /**
    * Direct access to the raw NATS connection.
@@ -1449,7 +1706,7 @@ var JetstreamClient = class extends ClientProxy {
   unwrap() {
     const nc = this.connection.unwrap;
     if (!nc) {
-      throw new Error("Not connected \u2014 call connect() before unwrap()");
+      throw new Error("Not connected; call connect() before unwrap()");
     }
     return nc;
   }
@@ -1476,7 +1733,7 @@ var JetstreamClient = class extends ClientProxy {
     const encoded = this.codec.encode(data);
     const effectiveMsgId = messageId ?? nuid.next();
     const record = packet.data instanceof JetstreamRecord ? packet.data : new JetstreamRecord(data, /* @__PURE__ */ new Map());
-    const declaredPattern = declaredEventPattern(packet.pattern);
+    const declaredPattern = declaredEventPattern(packet.pattern, publishKind);
     const streamKind = eventStreamKind(publishKind);
     const startedAt = performance.now();
     try {
@@ -1496,13 +1753,6 @@ var JetstreamClient = class extends ClientProxy {
         },
         this.otel,
         async () => {
-          const warnIfDuplicate = (kindLabel, ack2) => {
-            if (ack2.duplicate) {
-              this.logger.warn(
-                `Duplicate ${kindLabel} publish detected: ${publishSubject} (seq: ${ack2.seq})`
-              );
-            }
-          };
           if (schedule) {
             const ack2 = await this.connection.getJetStreamClient().publish(publishSubject, encoded, {
               headers: msgHeaders,
@@ -1513,7 +1763,7 @@ var JetstreamClient = class extends ClientProxy {
                 ttl
               }
             });
-            warnIfDuplicate("scheduled", ack2);
+            this.warnIfDuplicate("scheduled", publishSubject, ack2);
             return;
           }
           const ack = await this.connection.getJetStreamClient().publish(publishSubject, encoded, {
@@ -1521,7 +1771,7 @@ var JetstreamClient = class extends ClientProxy {
             msgID: effectiveMsgId,
             ttl
           });
-          warnIfDuplicate("event", ack);
+          this.warnIfDuplicate("event", publishSubject, ack);
         }
       );
       this.reportPublished(declaredPattern, streamKind, startedAt, "success");
@@ -1538,7 +1788,7 @@ var JetstreamClient = class extends ClientProxy {
    * JetStream mode: publishes to stream + waits for inbox response.
    */
   publish(packet, callback) {
-    const subject = this.commandSubjectPrefix + packet.pattern;
+    const subject = this.selfNames ? this.selfNames.subject("cmd" /* Command */, packet.pattern) : this.commandSubjectPrefix + packet.pattern;
     const { data, hdrs, timeout, messageId, schedule, ttl } = this.extractRecordData(packet.data);
     if (schedule) {
       this.logger.warn(
@@ -1571,12 +1821,7 @@ var JetstreamClient = class extends ClientProxy {
     }
     return () => {
       if (jetStreamCorrelationId) {
-        const timeoutId = this.pendingTimeouts.get(jetStreamCorrelationId);
-        if (timeoutId) {
-          clearTimeout(timeoutId);
-          this.pendingTimeouts.delete(jetStreamCorrelationId);
-        }
-        this.pendingMessages.delete(jetStreamCorrelationId);
+        this.rpcInbox.discard(jetStreamCorrelationId);
       }
     };
   }
@@ -1641,7 +1886,7 @@ var JetstreamClient = class extends ClientProxy {
     const hdrs = this.buildHeaders(customHeaders, {
       subject,
       correlationId,
-      replyTo: this.inbox ?? ""
+      replyTo: this.rpcInbox.address ?? ""
     });
     const encoded = this.codec.encode(data);
     const spanHandle = beginRpcClientSpan(
@@ -1658,7 +1903,7 @@ var JetstreamClient = class extends ClientProxy {
       this.otel
     );
     const startedAt = performance.now();
-    this.pendingMessages.set(correlationId, (packet) => {
+    const settleRoundTrip = (packet) => {
       if (packet.err) {
         if (packet.err instanceof Error) {
           spanHandle.finish({ kind: "error" /* Error */, error: packet.err });
@@ -1671,30 +1916,25 @@ var JetstreamClient = class extends ClientProxy {
         this.reportRpcCompleted(declaredPattern, startedAt, "success");
       }
       callback(packet);
-    });
-    const timeoutId = setTimeout(() => {
-      if (!this.pendingMessages.has(correlationId)) return;
-      this.pendingTimeouts.delete(correlationId);
-      this.pendingMessages.delete(correlationId);
+    };
+    this.rpcInbox.register(correlationId, settleRoundTrip);
+    this.rpcInbox.armTimeout(correlationId, effectiveTimeout, () => {
       spanHandle.finish({ kind: "timeout" /* Timeout */ });
       this.eventBus.emit("rpcTimeout" /* RpcTimeout */, subject, correlationId);
       this.reportRpcCompleted(declaredPattern, startedAt, "timeout");
       callback({ err: new Error(RPC_TIMEOUT_MESSAGE), response: null, isDisposed: true });
-    }, effectiveTimeout);
-    this.pendingTimeouts.set(correlationId, timeoutId);
+    });
     try {
       if (!this.readyForPublish) await this.connect();
-      if (!this.pendingMessages.has(correlationId)) return;
-      if (!this.inbox) {
-        clearTimeout(timeoutId);
-        this.pendingTimeouts.delete(correlationId);
-        this.pendingMessages.delete(correlationId);
+      if (!this.rpcInbox.has(correlationId)) return;
+      if (!this.rpcInbox.address) {
+        this.rpcInbox.discard(correlationId);
         const inboxError = new Error("Inbox not initialized");
         spanHandle.finish({ kind: "error" /* Error */, error: inboxError });
         this.reportPublished(declaredPattern, "cmd" /* Command */, startedAt, "error");
         this.reportRpcCompleted(declaredPattern, startedAt, "error");
         callback({
-          err: new Error("Inbox not initialized \u2014 JetStream RPC mode requires a connected inbox"),
+          err: new Error("Inbox not initialized; JetStream RPC mode requires a connected inbox"),
           response: null,
           isDisposed: true
         });
@@ -1714,13 +1954,7 @@ var JetstreamClient = class extends ClientProxy {
       }
       this.reportPublished(declaredPattern, "cmd" /* Command */, startedAt, "success");
     } catch (err) {
-      const existingTimeout = this.pendingTimeouts.get(correlationId);
-      if (existingTimeout) {
-        clearTimeout(existingTimeout);
-        this.pendingTimeouts.delete(correlationId);
-      }
-      if (!this.pendingMessages.has(correlationId)) return;
-      this.pendingMessages.delete(correlationId);
+      if (!this.rpcInbox.discard(correlationId)) return;
       const error = err instanceof Error ? err : new Error("Unknown error");
       spanHandle.finish({ kind: "error" /* Error */, error });
       this.eventBus.emit("error" /* Error */, error, `jetstream-rpc-publish:${subject}`);
@@ -1729,6 +1963,11 @@ var JetstreamClient = class extends ClientProxy {
       callback({ err: error, response: null, isDisposed: true });
     }
   }
+  warnIfDuplicate(kindLabel, subject, ack) {
+    if (ack.duplicate) {
+      this.logger.warn(`Duplicate ${kindLabel} publish detected: ${subject} (seq: ${ack.seq})`);
+    }
+  }
   // hasHook is per-emit so late subscribers (JetstreamMetricsService during
   // OnApplicationBootstrap) still receive events.
   reportPublished(declaredPattern, kind, startedAt, status) {
@@ -1752,87 +1991,23 @@ var JetstreamClient = class extends ClientProxy {
   }
   /** Fail-fast all pending JetStream RPC callbacks on connection loss. */
   handleDisconnect() {
-    this.rejectPendingRpcs(new Error("Connection lost"));
-    this.inbox = null;
+    this.rpcInbox.rejectAll(new Error("Connection lost"));
     this.readyForPublish = false;
   }
-  /** Reject all pending RPC callbacks, clear timeouts, and tear down inbox. */
-  rejectPendingRpcs(error) {
-    for (const callback of this.pendingMessages.values()) {
-      callback({ err: error, response: null, isDisposed: true });
-    }
-    for (const timeoutId of this.pendingTimeouts.values()) {
-      clearTimeout(timeoutId);
-    }
-    this.pendingMessages.clear();
-    this.pendingTimeouts.clear();
-    this.inboxSubscription?.unsubscribe();
-    this.inboxSubscription = null;
-    this.inbox = null;
-  }
-  /** Setup shared inbox subscription for JetStream RPC responses. */
-  setupInbox(nc) {
-    this.inbox = createInbox(internalName(this.rootOptions.name));
-    this.inboxSubscription = nc.subscribe(this.inbox, {
-      callback: (err, msg) => {
-        if (err) {
-          this.logger.error("Inbox subscription error:", err);
-          return;
-        }
-        this.routeInboxReply(msg);
-      }
-    });
-    this.logger.debug(`Inbox subscription: ${this.inbox}`);
-  }
-  /** Route an inbox reply to the matching pending callback. */
-  routeInboxReply(msg) {
-    const correlationId = msg.headers?.get("x-correlation-id" /* CorrelationId */);
-    if (!correlationId) {
-      this.logger.warn("Inbox reply without correlation-id, ignoring");
-      return;
-    }
-    const callback = this.pendingMessages.get(correlationId);
-    if (!callback) {
-      this.logger.warn(`No pending handler for correlation-id: ${correlationId}`);
-      return;
-    }
-    const timeoutId = this.pendingTimeouts.get(correlationId);
-    if (timeoutId) {
-      clearTimeout(timeoutId);
-      this.pendingTimeouts.delete(correlationId);
-    }
-    try {
-      const decoded = this.codec.decode(msg.data);
-      if (msg.headers?.get("x-error" /* Error */)) {
-        callback({ err: decoded, response: null, isDisposed: true });
-      } else {
-        callback({ err: null, response: decoded, isDisposed: true });
-      }
-    } catch (err) {
-      callback({
-        err: err instanceof Error ? err : new Error("Decode error"),
-        response: null,
-        isDisposed: true
-      });
-    } finally {
-      this.pendingMessages.delete(correlationId);
-    }
-  }
   /**
-   * Resolve a user pattern to a fully-qualified NATS subject, dispatching
-   * between the event, broadcast, and ordered prefixes.
-   *
-   * The leading-char check short-circuits the `startsWith` comparisons for
-   * patterns that cannot possibly carry a broadcast/ordered marker, which is
-   * the overwhelmingly common case.
+   * Resolve a user pattern to a fully-qualified NATS subject. Self-targets go
+   * through the resolver so custom subjectPrefix options are honoured.
    */
   buildEventSubject(pattern) {
-    if (pattern.charCodeAt(0) === 98 && pattern.startsWith("broadcast:" /* Broadcast */)) {
-      return BROADCAST_SUBJECT_PREFIX + pattern.slice("broadcast:" /* Broadcast */.length);
+    if (pattern.startsWith("broadcast:" /* Broadcast */)) {
+      return this.broadcastPrefix + pattern.slice("broadcast:" /* Broadcast */.length);
     }
-    if (pattern.charCodeAt(0) === 111 && pattern.startsWith("ordered:" /* Ordered */)) {
-      return this.orderedSubjectPrefix + pattern.slice("ordered:" /* Ordered */.length);
+    if (pattern.startsWith("ordered:" /* Ordered */)) {
+      const bare = pattern.slice("ordered:" /* Ordered */.length);
+      if (this.selfNames) return this.selfNames.subject("ordered" /* Ordered */, bare);
+      return this.orderedSubjectPrefix + bare;
     }
+    if (this.selfNames) return this.selfNames.subject("ev" /* Event */, pattern);
     return this.eventSubjectPrefix + pattern;
   }
   /** Build NATS headers merging custom headers with transport headers. */
@@ -1877,33 +2052,16 @@ var JetstreamClient = class extends ClientProxy {
   /**
    * 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.
-   *
-   * A unique per-message suffix is appended because the server stores schedules
-   * as rollup messages — one active schedule per subject (ADR-51). Without it,
-   * concurrent schedules of the same pattern would silently replace each other.
-   *
-   * Examples:
-   * - `{svc}__microservice.ev.order.reminder` → `{svc}__microservice._sch.order.reminder.<nuid>`
-   * - `broadcast.config.updated` → `broadcast._sch.config.updated.<nuid>`
+   * The holder lives in the same stream as the target but under the `_sch`
+   * namespace no consumer filter matches; the server publishes it to the
+   * target subject when the schedule fires. The unique per-message suffix
+   * exists because the server stores schedules as rollup messages, one
+   * active schedule per subject (ADR-51): without it, concurrent schedules
+   * of the same pattern would silently replace each other.
    */
   buildScheduleSubject(eventSubject) {
-    if (eventSubject.startsWith("broadcast.")) {
-      return `${eventSubject.replace("broadcast.", "broadcast._sch.")}.${nuid.next()}`;
-    }
-    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}.${nuid.next()}`;
+    const base = this.selfNames ? this.selfNames.scheduleSubjectBase(eventSubject) : conventionScheduleSubjectBase(this.targetName, eventSubject);
+    return `${base}.${nuid.next()}`;
   }
 };
 
@@ -1935,7 +2093,7 @@ var MsgpackCodec = class {
 };
 
 // src/connection/connection.provider.ts
-import { Logger as Logger6 } from "@nestjs/common";
+import { Logger as Logger7 } from "@nestjs/common";
 import {
   connect
 } from "@nats-io/transport-node";
@@ -1968,7 +2126,7 @@ var ConnectionProvider = class {
   nc$;
   /** Live stream of connection status events (no replay). */
   status$;
-  logger = new Logger6("Jetstream:Connection");
+  logger = new Logger7("Jetstream:Connection");
   connection = null;
   connectionPromise = null;
   jsClient = null;
@@ -1979,7 +2137,7 @@ var ConnectionProvider = class {
   otelEndpoint;
   lifecycleSpan = null;
   /**
-   * Establish NATS connection. Idempotent — returns cached connection on subsequent calls.
+   * Establish NATS connection. Idempotent: returns cached connection on subsequent calls.
    *
    * @throws Error if connection is refused (fail fast).
    */
@@ -2018,7 +2176,7 @@ var ConnectionProvider = class {
    */
   getJetStreamClient() {
     if (!this.connection || this.connection.isClosed()) {
-      throw new Error("Not connected \u2014 call getConnection() before getJetStreamClient()");
+      throw new Error("Not connected; call getConnection() before getJetStreamClient()");
     }
     this.jsClient ??= jetstream(this.connection);
     return this.jsClient;
@@ -2030,7 +2188,7 @@ var ConnectionProvider = class {
   /**
    * Gracefully shut down the connection.
    *
-   * Sequence: drain → wait for close. Falls back to force-close on error.
+   * Sequence: drain -> wait for close. Falls back to force-close on error.
    */
   async shutdown() {
     if (this.connectionPromise) {
@@ -2233,12 +2391,12 @@ var EventBus = class {
 };
 
 // src/health/jetstream.health-indicator.ts
-import { Injectable, Logger as Logger7 } from "@nestjs/common";
+import { Injectable, Logger as Logger8 } from "@nestjs/common";
 var JetstreamHealthIndicator = class {
   constructor(connection) {
     this.connection = connection;
   }
-  logger = new Logger7("Jetstream:Health");
+  logger = new Logger8("Jetstream:Health");
   /**
    * Plain health status check.
    *
@@ -2268,7 +2426,7 @@ 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
+   * 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`).
@@ -2302,7 +2460,7 @@ JetstreamHealthIndicator = __decorateClass([
 import { Module } from "@nestjs/common";
 
 // src/server/routing/pattern-registry.ts
-import { Logger as Logger8 } from "@nestjs/common";
+import { Logger as Logger9 } from "@nestjs/common";
 var HANDLER_LABELS = {
   ["broadcast" /* Broadcast */]: "broadcast" /* Broadcast */,
   ["ordered" /* Ordered */]: "ordered" /* Ordered */,
@@ -2310,12 +2468,13 @@ var HANDLER_LABELS = {
   ["cmd" /* Command */]: "rpc" /* Rpc */
 };
 var PatternRegistry = class {
-  constructor(options) {
+  constructor(options, names) {
     this.options = options;
+    this.names = names;
   }
-  logger = new Logger8("Jetstream:PatternRegistry");
+  logger = new Logger9("Jetstream:PatternRegistry");
   registry = /* @__PURE__ */ new Map();
-  // Cached after registerHandlers() — the registry is immutable from that point
+  // Cached after registerHandlers(); the registry is immutable from that point
   cachedPatterns = null;
   _hasEvents = false;
   _hasCommands = false;
@@ -2328,7 +2487,6 @@ var PatternRegistry = class {
    * @param handlers Map of pattern -> MessageHandler from `Server.getHandlers()`.
    */
   registerHandlers(handlers) {
-    const serviceName = this.options.name;
     for (const [pattern, handler] of handlers) {
       const extras = handler.extras;
       const isEvent = handler.isEventHandler ?? false;
@@ -2345,7 +2503,7 @@ var PatternRegistry = class {
       else if (isOrdered) kind = "ordered" /* Ordered */;
       else if (isEvent) kind = "ev" /* Event */;
       else kind = "cmd" /* Command */;
-      const fullSubject = kind === "broadcast" /* Broadcast */ ? buildBroadcastSubject(pattern) : buildSubject(serviceName, kind, pattern);
+      const fullSubject = this.names.subject(kind, pattern);
       this.registry.set(fullSubject, {
         handler,
         pattern,
@@ -2372,7 +2530,7 @@ var PatternRegistry = class {
    * Resolve the declared pattern and {@link StreamKind} for a full NATS subject.
    *
    * Returns `null` when the subject is not registered. The declared pattern is
-   * the value the user passed to `@EventPattern`/`@MessagePattern` — stable and
+   * the value the user passed to `@EventPattern`/`@MessagePattern`: stable and
    * bounded, suitable for use as a Prometheus label without cardinality risk.
    */
   resolveDeclared(subject) {
@@ -2382,7 +2540,17 @@ var PatternRegistry = class {
   }
   /** Get all registered broadcast patterns (for consumer filter_subject setup). */
   getBroadcastPatterns() {
-    return this.getPatternsByKind().broadcasts.map((p) => buildBroadcastSubject(p));
+    return this.getPatternsByKind().broadcasts.map(
+      (p) => this.names.subject("broadcast" /* Broadcast */, p)
+    );
+  }
+  /** Get registered event patterns as raw user-declared patterns. */
+  getEventPatterns() {
+    return this.getPatternsByKind().events;
+  }
+  /** Get registered command patterns as raw user-declared patterns. */
+  getCommandPatterns() {
+    return this.getPatternsByKind().commands;
   }
   hasBroadcastHandlers() {
     return this._hasBroadcasts;
@@ -2398,9 +2566,7 @@ var PatternRegistry = class {
   }
   /** Get fully-qualified NATS subjects for ordered handlers. */
   getOrderedSubjects() {
-    return this.getPatternsByKind().ordered.map(
-      (p) => buildSubject(this.options.name, "ordered" /* Ordered */, p)
-    );
+    return this.getPatternsByKind().ordered.map((p) => this.names.subject("ordered" /* Ordered */, p));
   }
   /** Check if any registered handler has metadata. */
   hasMetadata() {
@@ -2432,22 +2598,6 @@ var PatternRegistry = class {
       ordered: [...patterns.ordered]
     };
   }
-  /** Normalize a full NATS subject back to the user-facing pattern. */
-  normalizeSubject(subject) {
-    const name = internalName(this.options.name);
-    const prefixes = [
-      `${name}.${"cmd" /* Command */}.`,
-      `${name}.${"ev" /* Event */}.`,
-      `${name}.${"ordered" /* Ordered */}.`,
-      `${"broadcast" /* Broadcast */}.`
-    ];
-    for (const prefix of prefixes) {
-      if (subject.startsWith(prefix)) {
-        return subject.slice(prefix.length);
-      }
-    }
-    return subject;
-  }
   buildPatternsByKind() {
     const events = [];
     const commands = [];
@@ -2502,7 +2652,7 @@ var ERROR_CONTEXT_PREFIXES = [
   ["consume", "consume"],
   ["core-rpc-handler", "handler"],
   ["rpc-handler", "handler"],
-  // EventRouter formats contexts as `${StreamKind.*}-handler:...` — the enum
+  // EventRouter formats contexts as `${StreamKind.*}-handler:...`; the enum
   // uses short forms (`ev`, `ordered`, `broadcast`) so both surface in the wild.
   ["ev-handler", "handler"],
   ["event-handler", "handler"],
@@ -2523,7 +2673,7 @@ var STREAM_KIND_LABEL = {
 import {
   Inject,
   Injectable as Injectable2,
-  Logger as Logger10,
+  Logger as Logger11,
   Optional
 } from "@nestjs/common";
 
@@ -2648,12 +2798,12 @@ var createMetrics = (opts) => {
 };
 
 // src/metrics/poll-runner.ts
-import { Logger as Logger9 } from "@nestjs/common";
+import { Logger as Logger10 } from "@nestjs/common";
 var PollRunner = class {
   constructor(opts) {
     this.opts = opts;
   }
-  logger = new Logger9("Jetstream:Metrics:Poll");
+  logger = new Logger10("Jetstream:Metrics:Poll");
   timer = null;
   inFlight = null;
   start() {
@@ -2662,7 +2812,7 @@ var PollRunner = class {
     if (this.opts.targets.length === 0) return;
     this.timer = setInterval(() => {
       if (this.inFlight !== null) {
-        this.logger.warn("Skipping poll tick \u2014 previous cycle still in flight");
+        this.logger.warn("Skipping poll tick; previous cycle still in flight");
         return;
       }
       this.inFlight = this.tick().finally(() => {
@@ -2725,15 +2875,16 @@ var PollRunner = class {
 
 // src/metrics/metrics.service.ts
 var JetstreamMetricsService = class {
-  constructor(eventBus, config, promClient, options, patternRegistry, connection = null) {
+  constructor(eventBus, config, promClient, options, patternRegistry, connection = null, names = null) {
     this.eventBus = eventBus;
     this.config = config;
     this.promClient = promClient;
     this.options = options;
     this.patternRegistry = patternRegistry;
     this.connection = connection;
+    this.names = names;
   }
-  logger = new Logger10("Jetstream:Metrics");
+  logger = new Logger11("Jetstream:Metrics");
   metrics = null;
   pollRunner = null;
   activeServers = /* @__PURE__ */ new Set();
@@ -2742,7 +2893,7 @@ var JetstreamMetricsService = class {
     if (!this.options.metrics || !this.config || !this.promClient) return;
     if (!this.config.register) {
       throw new Error(
-        "JetstreamMetricsService requires a prom-client Registry \u2014 none was resolved by JetstreamMetricsModule."
+        "JetstreamMetricsService requires a prom-client Registry; none was resolved by JetstreamMetricsModule."
       );
     }
     this.metrics = createMetrics({
@@ -2769,7 +2920,7 @@ var JetstreamMetricsService = class {
   }
   /**
    * NATS connects during early bootstrap, before this service subscribes to
-   * the EventBus — the initial `Connect` emission misses us. Mirror the
+   * the EventBus, so the initial `Connect` emission misses us. Mirror the
    * current state here so `connection_up` reflects reality the moment metrics
    * come online; later disconnects/reconnects update it normally.
    */
@@ -2802,26 +2953,32 @@ var JetstreamMetricsService = class {
     if (registry.hasEventHandlers()) {
       targets.push({
         kind: "ev" /* Event */,
-        stream: streamName(this.options.name, "ev" /* Event */),
-        consumer: consumerName(this.options.name, "ev" /* Event */)
+        stream: this.resolveStreamName("ev" /* Event */),
+        consumer: this.resolveConsumerName("ev" /* Event */)
       });
     }
     if (registry.hasRpcHandlers() && isJetStreamRpcMode(this.options.rpc)) {
       targets.push({
         kind: "cmd" /* Command */,
-        stream: streamName(this.options.name, "cmd" /* Command */),
-        consumer: consumerName(this.options.name, "cmd" /* Command */)
+        stream: this.resolveStreamName("cmd" /* Command */),
+        consumer: this.resolveConsumerName("cmd" /* Command */)
       });
     }
     if (registry.hasBroadcastHandlers()) {
       targets.push({
         kind: "broadcast" /* Broadcast */,
-        stream: streamName(this.options.name, "broadcast" /* Broadcast */),
-        consumer: consumerName(this.options.name, "broadcast" /* Broadcast */)
+        stream: this.resolveStreamName("broadcast" /* Broadcast */),
+        consumer: this.resolveConsumerName("broadcast" /* Broadcast */)
       });
     }
     return targets;
   }
+  resolveStreamName(kind) {
+    return this.names ? this.names.streamName(kind) : streamName(this.options.name, kind);
+  }
+  resolveConsumerName(kind) {
+    return this.names ? this.names.consumerName(kind) : consumerName(this.options.name, kind);
+  }
   subscribeToEvents() {
     this.eventBus.subscribe("connect" /* Connect */, this.onConnect);
     this.eventBus.subscribe("disconnect" /* Disconnect */, this.onDisconnect);
@@ -2856,7 +3013,7 @@ var JetstreamMetricsService = class {
     const subjectLabel = declared?.pattern ?? UNMATCHED_SUBJECT_LABEL;
     this.metrics?.rpcTimeoutTotal.labels({ subject: subjectLabel }).inc();
   };
-  // `_kind` collapses broadcast/ordered into MessageKind.Event — we use
+  // `_kind` collapses broadcast/ordered into MessageKind.Event; we use
   // declared.kind from PatternRegistry for the precise label instead.
   onMessageRouted = (subject, _kind) => {
     if (!this.metrics) return;
@@ -2866,7 +3023,7 @@ var JetstreamMetricsService = class {
       return;
     }
     this.metrics.messagesReceivedTotal.labels({
-      stream: streamName(this.options.name, declared.kind),
+      stream: this.resolveStreamName(declared.kind),
       subject: declared.pattern,
       kind: STREAM_KIND_LABEL[declared.kind]
     }).inc();
@@ -2882,7 +3039,7 @@ var JetstreamMetricsService = class {
   };
   onHandlerCompleted = (pattern, kind, durationMs, status) => {
     if (!this.metrics) return;
-    const stream = streamName(this.options.name, kind);
+    const stream = this.resolveStreamName(kind);
     const kindLabel = STREAM_KIND_LABEL[kind];
     const labels = { stream, subject: pattern, kind: kindLabel, status };
     this.metrics.messagesProcessedTotal.labels(labels).inc();
@@ -2908,7 +3065,8 @@ JetstreamMetricsService = __decorateClass([
   __decorateParam(3, Inject(JETSTREAM_OPTIONS)),
   __decorateParam(4, Optional()),
   __decorateParam(5, Optional()),
-  __decorateParam(5, Inject(JETSTREAM_CONNECTION))
+  __decorateParam(5, Inject(JETSTREAM_CONNECTION)),
+  __decorateParam(6, Optional())
 ], JetstreamMetricsService);
 
 // src/metrics/metrics.module.ts
@@ -2963,9 +3121,18 @@ var JetstreamMetricsModule = class {
         JETSTREAM_METRICS_PROM_CLIENT,
         JETSTREAM_OPTIONS,
         { token: PatternRegistry, optional: true },
-        { token: JETSTREAM_CONNECTION, optional: true }
+        { token: JETSTREAM_CONNECTION, optional: true },
+        { token: NameResolver, optional: true }
       ],
-      useFactory: (eventBus, cfg, runtime, opts, patternRegistry, connection) => new JetstreamMetricsService(eventBus, cfg, runtime, opts, patternRegistry, connection)
+      useFactory: (eventBus, cfg, runtime, opts, patternRegistry, connection, names) => new JetstreamMetricsService(
+        eventBus,
+        cfg,
+        runtime,
+        opts,
+        patternRegistry,
+        connection,
+        names
+      )
     };
     return {
       module: JetstreamMetricsModule,
@@ -3026,31 +3193,22 @@ var JetstreamStrategy = class extends Server {
     this.started = false;
   }
   /**
-   * Override NestJS `Server.addHandler` to fail-fast on duplicate pattern registration.
+   * Override NestJS `Server.addHandler` to fail fast on duplicate pattern registration.
    *
-   * The base class silently overwrites duplicate RPC handlers (last wins) and appends
-   * duplicate event handlers to a linked list. Both behaviors are hazardous in a
-   * JetStream context: silent overwrite drops a handler the user wrote, and double
-   * event dispatch double-acks/double-processes the same JetStream message.
-   *
-   * We treat any pattern collision as a fatal misconfiguration so it surfaces at
-   * bootstrap instead of in production traffic.
+   * The base class silently overwrites duplicate RPC handlers and chains duplicate event
+   * handlers, which would double-ack the same JetStream message. Any collision is treated
+   * as a fatal misconfiguration so it surfaces at bootstrap, not in production traffic.
    */
   addHandler(pattern, callback, isEventHandler = false, extras = {}) {
     const normalizedPattern = this.normalizePattern(pattern);
     if (this.messageHandlers.has(normalizedPattern)) {
       throw new Error(
-        `Duplicate handler registered for pattern "${normalizedPattern}". Each @EventPattern() / @MessagePattern() value must be unique within a microservice \u2014 find and remove the second declaration.`
+        `Duplicate handler registered for pattern "${normalizedPattern}". Each @EventPattern() / @MessagePattern() value must be unique within a microservice; find and remove the second declaration.`
       );
     }
     super.addHandler(pattern, callback, isEventHandler, extras);
   }
-  /**
-   * Register event listener (required by Server base class).
-   *
-   * Stores callbacks for client use. Primary lifecycle events
-   * are routed through EventBus.
-   */
+  /** Register event listener (required by Server base class); lifecycle events use EventBus. */
   // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
   on(event, callback) {
     const existing = this.listeners.get(event) ?? [];
@@ -3065,7 +3223,7 @@ var JetstreamStrategy = class extends Server {
   unwrap() {
     const nc = this.connection.unwrap;
     if (!nc) {
-      throw new Error("Not connected \u2014 transport has not started");
+      throw new Error("Not connected; transport has not started");
     }
     return nc;
   }
@@ -3075,7 +3233,7 @@ var JetstreamStrategy = class extends Server {
   }
   async doListen(callback) {
     if (this.started) {
-      this.logger.warn("listen() called more than once \u2014 ignoring");
+      this.logger.warn("listen() called more than once; ignoring");
       return;
     }
     this.started = true;
@@ -3166,7 +3324,7 @@ var JetstreamStrategy = class extends Server {
 };
 
 // src/server/core-rpc.server.ts
-import { Logger as Logger11 } from "@nestjs/common";
+import { Logger as Logger12 } from "@nestjs/common";
 import { headers as natsHeaders2 } from "@nats-io/transport-node";
 
 // src/context/rpc.context.ts
@@ -3243,7 +3401,7 @@ var RpcContext = class extends BaseRpcContext {
   retry(opts) {
     this.assertJetStream("retry");
     if (this._shouldTerminate) {
-      throw new Error("Cannot retry \u2014 terminate() was already called");
+      throw new Error("Cannot retry; terminate() was already called");
     }
     this._shouldRetry = true;
     this._retryDelay = opts?.delayMs;
@@ -3260,7 +3418,7 @@ var RpcContext = class extends BaseRpcContext {
   terminate(reason) {
     this.assertJetStream("terminate");
     if (this._shouldRetry) {
-      throw new Error("Cannot terminate \u2014 retry() was already called");
+      throw new Error("Cannot terminate; retry() was already called");
     }
     this._shouldTerminate = true;
     this._terminateReason = reason;
@@ -3269,7 +3427,7 @@ var RpcContext = class extends BaseRpcContext {
   asJetStream() {
     return this.isJetStream() ? this.args[0] : null;
   }
-  /** Ensure the message is JetStream — settlement actions are not available for Core NATS. */
+  /** Ensure the message is JetStream; settlement actions are not available for Core NATS. */
   assertJetStream(method) {
     if (!this.isJetStream()) {
       throw new Error(`${method}() is only available for JetStream messages`);
@@ -3434,17 +3592,18 @@ var subscribeToFirst = (obs) => new Promise((resolve, reject) => {
 
 // src/server/core-rpc.server.ts
 var CoreRpcServer = class {
-  constructor(options, connection, patternRegistry, codec, eventBus) {
+  constructor(options, connection, patternRegistry, codec, eventBus, names) {
     this.connection = connection;
     this.patternRegistry = patternRegistry;
     this.codec = codec;
     this.eventBus = eventBus;
+    this.names = names;
     const derived = deriveOtelAttrs(options);
     this.otel = derived.otel;
     this.serviceName = derived.serviceName;
     this.serverEndpoint = derived.serverEndpoint;
   }
-  logger = new Logger11("Jetstream:CoreRpc");
+  logger = new Logger12("Jetstream:CoreRpc");
   subscription = null;
   otel;
   serviceName;
@@ -3452,7 +3611,7 @@ var CoreRpcServer = class {
   /** Start listening for RPC requests on the command subject. */
   async start() {
     const nc = await this.connection.getConnection();
-    const subject = `${this.serviceName}.cmd.>`;
+    const subject = this.names ? this.names.filterSubject("cmd" /* Command */) : `${this.serviceName}.cmd.>`;
     const queue = `${this.serviceName}_cmd_queue`;
     this.subscription = nc.subscribe(subject, {
       queue,
@@ -3555,7 +3714,7 @@ var CoreRpcServer = class {
 };
 
 // src/server/infrastructure/stream.provider.ts
-import { Logger as Logger13 } from "@nestjs/common";
+import { Logger as Logger14 } from "@nestjs/common";
 import {
   JetStreamApiError as JetStreamApiError2,
   RetentionPolicy as RetentionPolicy2,
@@ -3629,7 +3788,7 @@ var assertStorageBudget = async (jsm, serviceName, reservations, logger5) => {
       );
     }
   } catch (err) {
-    logger5.debug(`Storage preflight skipped \u2014 account info unavailable: ${String(err)}`);
+    logger5.debug(`Storage preflight skipped; account info unavailable: ${String(err)}`);
   }
 };
 
@@ -3650,7 +3809,7 @@ var JetstreamProvisioningError = class _JetstreamProvisioningError extends Error
   numReplicas;
   reservation;
   constructor(fields) {
-    const reservationNote = fields.reservation !== void 0 ? ` reservation=${fields.reservation}B (max_bytes=${fields.maxBytes}B \xD7 replicas=${fields.numReplicas}).` : "";
+    const reservationNote = fields.reservation !== void 0 ? ` reservation=${fields.reservation}B (max_bytes=${fields.maxBytes}B x replicas=${fields.numReplicas}).` : "";
     super(
       `JetStream ${fields.entity} provisioning failed for "${fields.target}" (kind=${fields.kind}): ${fields.errDescription} [err_code=${fields.errCode}].${reservationNote} ${fields.remediation}`,
       { cause: fields.cause }
@@ -3702,18 +3861,22 @@ var formatAge = (nanos) => {
   if (nanos >= NANOS_PER_HOUR) return `${(nanos / NANOS_PER_HOUR).toFixed(1)}h`;
   return `${(nanos / NANOS_PER_SECOND).toFixed(0)}s`;
 };
-var formatProvisioningSummary = (serviceName, reservations) => {
-  const lines = [`Provisioning ${reservations.length} stream(s) for "${serviceName}":`];
+var formatProvisioningSummary = (serviceName, reservations, external = []) => {
+  const totalStreams = reservations.length + external.length;
+  const lines = [`Provisioning ${totalStreams} stream(s) for "${serviceName}":`];
   let totalFileMaxBytes = 0;
   for (const r of reservations) {
     if (r.storage === StorageType3.File) totalFileMaxBytes += r.maxBytes;
     const clusterReservation = r.maxBytes * r.numReplicas;
     lines.push(
-      `  \u2022 ${r.name} [${r.kind}] storage=${r.storage} replicas=${r.numReplicas} max_bytes=${formatBytes(r.maxBytes)} max_age=${formatAge(r.maxAge)} retention=${r.retention} \u2192 cluster reservation ${formatBytes(clusterReservation)}`
+      `  - ${r.name} [${r.kind}] storage=${r.storage} replicas=${r.numReplicas} max_bytes=${formatBytes(r.maxBytes)} max_age=${formatAge(r.maxAge)} retention=${r.retention} -> cluster reservation ${formatBytes(clusterReservation)}`
     );
   }
+  for (const e of external) {
+    lines.push(`  - ${e.name} [${e.kind}] external (bound)`);
+  }
   lines.push(
-    `  \u03A3 per-node file-backed footprint \u2248 ${formatBytes(totalFileMaxBytes)} (sum of max_bytes; worst case replicas = nodes). Ensure the NATS server max_file_store accommodates the sum across ALL services.`
+    `  Total per-node file-backed footprint ~ ${formatBytes(totalFileMaxBytes)} (sum of max_bytes; worst case replicas = nodes). Ensure the NATS server max_file_store accommodates the sum across ALL services.`
   );
   return lines.join("\n");
 };
@@ -3774,7 +3937,7 @@ var isEqual = (a, b) => {
 };
 
 // src/server/infrastructure/stream-migration.ts
-import { Logger as Logger12 } from "@nestjs/common";
+import { Logger as Logger13 } from "@nestjs/common";
 import {
   JetStreamApiError
 } from "@nats-io/jetstream";
@@ -3789,7 +3952,7 @@ var StreamMigration = class {
     this.sourcingTimeoutMs = sourcingTimeoutMs;
     this.peerWaitMs = peerWaitMs;
   }
-  logger = new Logger12("Jetstream:Stream");
+  logger = new Logger13("Jetstream:Stream");
   async migrate(jsm, streamName2, newConfig) {
     const backupName = `${streamName2}${MIGRATION_BACKUP_SUFFIX}`;
     const startTime = Date.now();
@@ -3808,7 +3971,7 @@ var StreamMigration = class {
       await jsm.streams.update(streamName2, { ...currentInfo.config, subjects: [] });
       drainedCount = (await jsm.streams.info(streamName2)).state.messages;
       if (drainedCount > 0) {
-        this.logger.log(`  Phase 2/4: Backing up ${drainedCount} messages \u2192 ${backupName}`);
+        this.logger.log(`  Phase 2/4: Backing up ${drainedCount} messages -> ${backupName}`);
         await jsm.streams.add({
           ...currentInfo.config,
           name: backupName,
@@ -3829,7 +3992,7 @@ var StreamMigration = class {
     } catch (err) {
       if (originalDeleted) {
         this.logger.error(
-          `Migration of ${streamName2} failed after the original was deleted. Backup ${backupName} preserved \u2014 restoration resumes on the next startup.`
+          `Migration of ${streamName2} failed after the original was deleted. Backup ${backupName} preserved; restoration resumes on the next startup.`
         );
       } else {
         await this.rollbackBeforeDelete(jsm, streamName2, currentInfo, backupName);
@@ -3897,7 +4060,7 @@ var StreamMigration = class {
     await jsm.streams.update(streamName2, { ...streamConfig, sources: [] });
   }
   /**
-   * Lag-based drain check — live publishes cannot fake completion. A fresh
+   * Lag-based drain check: live publishes cannot fake completion. A fresh
    * source reports lag 0 / active -1 before its first sync (NATS 2.12.6),
    * hence the active guard.
    */
@@ -3916,13 +4079,13 @@ var StreamMigration = class {
     );
   }
   /**
-   * A backup present at migrate() start is a live peer migration — wait it
+   * A backup present at migrate() start is a live peer migration; wait it
    * out. Stale leftovers were already handled by recoverInterrupted().
    */
   async waitOutPeerMigration(jsm, backupName) {
     if (await this.tryInfo(jsm, backupName) === null) return false;
     this.logger.warn(
-      `Migration backup ${backupName} exists \u2014 another instance appears to be migrating; waiting`
+      `Migration backup ${backupName} exists; another instance appears to be migrating; waiting`
     );
     const deadline = Date.now() + this.peerWaitMs;
     while (Date.now() < deadline) {
@@ -3943,7 +4106,7 @@ var StreamMigration = class {
       }
     } catch (rollbackErr) {
       this.logger.error(
-        `Rollback of ${streamName2} after a failed migration also failed \u2014 the stream may be left quiesced:`,
+        `Rollback of ${streamName2} after a failed migration also failed; the stream may be left quiesced:`,
         rollbackErr
       );
     }
@@ -3967,7 +4130,7 @@ var StreamMigration = class {
   }
 };
 
-// src/server/infrastructure/stream.provider.ts
+// src/server/infrastructure/subject-utils.ts
 var subjectCovers = (broad, narrow) => {
   if (broad === narrow) return false;
   const broadTokens = broad.split(".");
@@ -3979,16 +4142,21 @@ var subjectCovers = (broad, narrow) => {
   }
   return broadTokens.length === narrowTokens.length;
 };
+var coversOrEquals = (broad, subject) => broad === subject || subjectCovers(broad, subject);
+
+// src/server/infrastructure/stream.provider.ts
 var StreamProvider = class {
-  constructor(options, connection) {
+  constructor(options, connection, names, binder) {
     this.options = options;
     this.connection = connection;
+    this.names = names;
+    this.binder = binder;
     const derived = deriveOtelAttrs(options);
     this.otel = derived.otel;
     this.otelServiceName = derived.serviceName;
     this.otelEndpoint = derived.serverEndpoint;
   }
-  logger = new Logger13("Jetstream:Stream");
+  logger = new Logger14("Jetstream:Stream");
   migration = new StreamMigration();
   otel;
   otelServiceName;
@@ -4002,42 +4170,48 @@ var StreamProvider = class {
    */
   async ensureStreams(kinds) {
     const jsm = await this.connection.getJetStreamManager();
-    const reservations = kinds.map((kind) => this.buildReservation(kind, this.buildConfig(kind)));
+    const { autoKinds, externalKinds } = this.partitionByManagement(kinds);
+    const reservations = autoKinds.map(
+      (kind) => this.buildReservation(kind, this.buildConfig(kind))
+    );
+    const external = externalKinds.map((kind) => ({
+      kind,
+      name: this.names.streamName(kind)
+    }));
+    const dlqIsManual = !!this.options.dlq && resolveManagementMode(this.options, "dlq", "stream") === "manual" /* Manual */;
     if (this.options.dlq) {
-      reservations.push(this.buildReservation("dlq", this.buildDlqConfig()));
+      if (dlqIsManual) {
+        external.push({ kind: "dlq", name: this.names.dlqStreamName() });
+      } else {
+        reservations.push(this.buildReservation("dlq", this.buildDlqConfig()));
+      }
     }
     this.logger.log(`
-${formatProvisioningSummary(this.options.name, reservations)}`);
-    if (this.options.provisioning?.preflightStorageCheck) {
+${formatProvisioningSummary(this.options.name, reservations, external)}`);
+    if (this.options.provisioning?.preflightStorageCheck && reservations.length > 0) {
       await assertStorageBudget(jsm, this.options.name, reservations, this.logger);
     }
-    await Promise.all(kinds.map((kind) => this.ensureStream(jsm, kind)));
+    await Promise.all([
+      ...autoKinds.map((kind) => this.ensureStream(jsm, kind)),
+      ...externalKinds.map((kind) => this.bindStream(jsm, kind))
+    ]);
     if (this.options.dlq) {
-      await this.ensureDlqStream(jsm);
+      if (dlqIsManual) {
+        await this.bindDlqStream(jsm);
+      } else {
+        await this.ensureDlqStream(jsm);
+      }
     }
   }
   /** Get the stream name for a given kind. */
   getStreamName(kind) {
-    return streamName(this.options.name, kind);
+    return this.names.streamName(kind);
   }
   /** Get the subjects pattern for a given kind. */
   getSubjects(kind) {
-    const name = internalName(this.options.name);
-    switch (kind) {
-      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 "ordered" /* Ordered */:
-        return [`${name}.${"ordered" /* Ordered */}.>`];
-    }
+    const filter = this.names.filterSubject(kind);
+    const dedicatedSchedule = kind === "ev" /* Event */ && this.isSchedulingEnabled(kind) && !this.names.hasCustomPrefix(kind);
+    return dedicatedSchedule ? [filter, `${this.names.schedulePrefix(kind)}>`] : [filter];
   }
   /** Ensure a single stream exists, creating or updating as needed. */
   async ensureStream(jsm, kind) {
@@ -4114,7 +4288,7 @@ ${formatProvisioningSummary(this.options.name, reservations)}`);
     }
     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(", ");
+      const conflicts = diff.changes.filter((c) => c.mutability === "transport-controlled").map((c) => `${c.property}: ${JSON.stringify(c.current)} -> ${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.`
       );
@@ -4164,13 +4338,13 @@ ${formatProvisioningSummary(this.options.name, reservations)}`);
   }
   logChanges(streamName2, diff, migrationEnabled) {
     for (const c of diff.changes) {
-      const detail = `${c.property}: ${JSON.stringify(c.current)} \u2192 ${JSON.stringify(c.desired)}`;
+      const detail = `${c.property}: ${JSON.stringify(c.current)} -> ${JSON.stringify(c.desired)}`;
       if (c.mutability === "transport-controlled") {
         this.logger.error(
-          `Stream ${streamName2}: ${detail} \u2014 transport-controlled, cannot be changed`
+          `Stream ${streamName2}: ${detail}; transport-controlled, cannot be changed`
         );
       } else if (c.mutability === "immutable" && !migrationEnabled) {
-        this.logger.warn(`Stream ${streamName2}: ${detail} \u2014 requires allowDestructiveMigration`);
+        this.logger.warn(`Stream ${streamName2}: ${detail}; requires allowDestructiveMigration`);
       } else {
         this.logger.log(`Stream ${streamName2}: ${detail}`);
       }
@@ -4208,7 +4382,47 @@ ${formatProvisioningSummary(this.options.name, reservations)}`);
       throw err;
     }
   }
-  /** The broadcast stream is global — every service in the cluster shares it. */
+  partitionByManagement(kinds) {
+    const autoKinds = [];
+    const externalKinds = [];
+    for (const kind of kinds) {
+      if (resolveManagementMode(this.options, kind, "stream") === "manual" /* Manual */) {
+        externalKinds.push(kind);
+      } else {
+        autoKinds.push(kind);
+      }
+    }
+    return { autoKinds, externalKinds };
+  }
+  async bindStream(jsm, kind) {
+    const name = this.names.streamName(kind);
+    return withProvisioningSpan(
+      this.otel,
+      {
+        serviceName: this.otelServiceName,
+        endpoint: this.otelEndpoint,
+        entity: "stream",
+        name,
+        action: "bind"
+      },
+      () => this.binder.bindStream(jsm, kind)
+    );
+  }
+  async bindDlqStream(jsm) {
+    const name = this.names.dlqStreamName();
+    return withProvisioningSpan(
+      this.otel,
+      {
+        serviceName: this.otelServiceName,
+        endpoint: this.otelEndpoint,
+        entity: "stream",
+        name,
+        action: "bind"
+      },
+      () => this.binder.bindDlqStream(jsm)
+    );
+  }
+  /** The broadcast stream is global; every service in the cluster shares it. */
   isSharedStream(name) {
     return name === this.getStreamName("broadcast" /* Broadcast */);
   }
@@ -4228,13 +4442,11 @@ ${formatProvisioningSummary(this.options.name, reservations)}`);
     };
   }
   /**
-   * 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.
+   * Build the DLQ stream config: library defaults merged with user overrides,
+   * with transport-controlled settings like retention stripped.
    */
   buildDlqConfig() {
-    const name = dlqStreamName(this.options.name);
+    const name = this.names.dlqStreamName();
     const subjects = [name];
     const description = `JetStream DLQ stream for ${this.options.name}`;
     const overrides = this.options.dlq?.stream ?? {};
@@ -4267,22 +4479,7 @@ ${formatProvisioningSummary(this.options.name, reservations)}`);
   }
   /** Get user-provided overrides for a stream kind, stripping transport-controlled properties. */
   getOverrides(kind) {
-    let overrides;
-    switch (kind) {
-      case "ev" /* Event */:
-        overrides = this.options.events?.stream ?? {};
-        break;
-      case "cmd" /* Command */:
-        overrides = this.options.rpc?.mode === "jetstream" ? this.options.rpc.stream ?? {} : {};
-        break;
-      case "broadcast" /* Broadcast */:
-        overrides = this.options.broadcast?.stream ?? {};
-        break;
-      case "ordered" /* Ordered */:
-        overrides = this.options.ordered?.stream ?? {};
-        break;
-    }
-    return this.stripTransportControlled(overrides);
+    return this.stripTransportControlled(kindOptionsBlock(this.options, kind)?.stream ?? {});
   }
   /**
    * Remove transport-controlled properties from user overrides.
@@ -4292,7 +4489,7 @@ ${formatProvisioningSummary(this.options.name, reservations)}`);
   stripTransportControlled(overrides) {
     if (!("retention" in overrides)) return overrides;
     this.logger.debug(
-      "Stripping user-provided retention override \u2014 retention is managed by the transport"
+      "Stripping user-provided retention override; retention is managed by the transport"
     );
     const cleaned = { ...overrides };
     delete cleaned.retention;
@@ -4301,20 +4498,22 @@ ${formatProvisioningSummary(this.options.name, reservations)}`);
 };
 
 // src/server/infrastructure/consumer.provider.ts
-import { Logger as Logger14 } from "@nestjs/common";
+import { Logger as Logger15 } from "@nestjs/common";
 import { JetStreamApiError as JetStreamApiError3 } from "@nats-io/jetstream";
 var ConsumerProvider = class {
-  constructor(options, connection, streamProvider, patternRegistry) {
+  constructor(options, connection, streamProvider, patternRegistry, names, binder) {
     this.options = options;
     this.connection = connection;
     this.streamProvider = streamProvider;
     this.patternRegistry = patternRegistry;
+    this.names = names;
+    this.binder = binder;
     const derived = deriveOtelAttrs(options);
     this.otel = derived.otel;
     this.otelServiceName = derived.serviceName;
     this.otelEndpoint = derived.serverEndpoint;
   }
-  logger = new Logger14("Jetstream:Consumer");
+  logger = new Logger15("Jetstream:Consumer");
   otel;
   otelServiceName;
   otelEndpoint;
@@ -4336,24 +4535,33 @@ var ConsumerProvider = class {
   }
   /** Get the consumer name for a given kind. */
   getConsumerName(kind) {
-    return consumerName(this.options.name, kind);
+    return this.names.consumerName(kind);
   }
   /**
    * Ensure a single consumer exists with the desired config.
-   * Used at **startup** — creates or updates the consumer to match
-   * the current pod's configuration.
+   * Startup path: 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);
     const name = config.durable_name;
+    const spanAttrs = {
+      serviceName: this.otelServiceName,
+      endpoint: this.otelEndpoint,
+      entity: "consumer",
+      name
+    };
+    if (resolveManagementMode(this.options, kind, "consumer") === "manual" /* Manual */) {
+      return withProvisioningSpan(
+        this.otel,
+        { ...spanAttrs, action: "bind" },
+        () => this.binder.bindConsumer(jsm, kind)
+      );
+    }
     return withProvisioningSpan(
       this.otel,
       {
-        serviceName: this.otelServiceName,
-        endpoint: this.otelEndpoint,
-        entity: "consumer",
-        name,
+        ...spanAttrs,
         action: "ensure"
       },
       async () => {
@@ -4374,28 +4582,40 @@ var ConsumerProvider = class {
   }
   /**
    * 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)
+   * Self-healing path: creates if missing but never updates config, so an old pod
+   * cannot overwrite a newer pod's config during rolling updates. If a migration
+   * backup stream exists, throws so the retry loop backs off until migration completes;
+   * creating a consumer mid-migration would eat workqueue messages being restored.
    */
   async recoverConsumer(jsm, kind) {
     const stream = this.streamProvider.getStreamName(kind);
     const config = this.buildConfig(kind);
     const name = config.durable_name;
+    const spanAttrs = {
+      serviceName: this.otelServiceName,
+      endpoint: this.otelEndpoint,
+      entity: "consumer",
+      name
+    };
+    if (resolveManagementMode(this.options, kind, "consumer") === "manual" /* Manual */) {
+      return withProvisioningSpan(this.otel, { ...spanAttrs, action: "rebind" }, async () => {
+        try {
+          return await jsm.consumers.info(stream, name);
+        } catch (err) {
+          if (err instanceof JetStreamApiError3 && err.apiError().err_code === 10014 /* ConsumerNotFound */) {
+            throw new Error(
+              `Consumer ${name} on ${stream} is externally managed and currently absent; waiting for it to be restored.`
+            );
+          }
+          throw err;
+        }
+      });
+    }
     return withProvisioningSpan(
       this.otel,
       {
-        serviceName: this.otelServiceName,
-        endpoint: this.otelEndpoint,
-        entity: "consumer",
-        name,
+        ...spanAttrs,
         action: "recover"
       },
       async () => {
@@ -4431,9 +4651,7 @@ var ConsumerProvider = class {
       throw err;
     }
   }
-  /**
-   * Create a consumer, handling the race where another pod creates it first.
-   */
+  /** Create a consumer, handling the race where another pod creates it first. */
   async createConsumer(jsm, stream, name, kind, config) {
     this.logger.log(`Creating consumer: ${name}`);
     const ctx = { entity: "consumer", name, kind };
@@ -4461,10 +4679,8 @@ var ConsumerProvider = class {
     }
   }
   /** Build consumer config by merging defaults with user overrides. */
-  // eslint-disable-next-line @typescript-eslint/naming-convention -- NATS API uses snake_case
   buildConfig(kind) {
-    const name = this.getConsumerName(kind);
-    const serviceName = internalName(this.options.name);
+    const durableName = this.getConsumerName(kind);
     const defaults = this.getDefaults(kind);
     const overrides = this.getOverrides(kind);
     if (kind === "broadcast" /* Broadcast */) {
@@ -4476,31 +4692,54 @@ var ConsumerProvider = class {
         return {
           ...defaults,
           ...overrides,
-          name,
-          durable_name: name,
+          name: durableName,
+          durable_name: durableName,
           filter_subject: broadcastPatterns[0]
         };
       }
       return {
         ...defaults,
         ...overrides,
-        name,
-        durable_name: name,
+        name: durableName,
+        durable_name: durableName,
         filter_subjects: broadcastPatterns
       };
     }
     if (kind !== "ev" /* Event */ && kind !== "cmd" /* Command */) {
       throw new Error(`Unexpected durable consumer kind: ${kind}`);
     }
-    const filter_subject = `${serviceName}.${kind}.>`;
+    if (this.names.hasCustomPrefix(kind)) {
+      return this.buildCustomPrefixConfig(kind, durableName, defaults, overrides);
+    }
+    const filter_subject = this.names.filterSubject(kind);
     return {
       ...defaults,
       ...overrides,
-      name,
-      durable_name: name,
+      name: durableName,
+      durable_name: durableName,
       filter_subject
     };
   }
+  buildCustomPrefixConfig(kind, durableName, defaults, overrides) {
+    const patterns = kind === "ev" /* Event */ ? this.patternRegistry.getEventPatterns() : this.patternRegistry.getCommandPatterns();
+    const subjects = patterns.map((p) => this.names.subject(kind, p));
+    if (subjects.length === 1) {
+      return {
+        ...defaults,
+        ...overrides,
+        name: durableName,
+        durable_name: durableName,
+        filter_subject: subjects[0]
+      };
+    }
+    return {
+      ...defaults,
+      ...overrides,
+      name: durableName,
+      durable_name: durableName,
+      filter_subjects: subjects
+    };
+  }
   /** Get default config for a consumer kind. */
   getDefaults(kind) {
     switch (kind) {
@@ -4521,26 +4760,12 @@ var ConsumerProvider = class {
   }
   /** Get user-provided overrides for a consumer kind. */
   getOverrides(kind) {
-    switch (kind) {
-      case "ev" /* Event */:
-        return this.options.events?.consumer ?? {};
-      case "cmd" /* Command */:
-        return this.options.rpc?.mode === "jetstream" ? this.options.rpc.consumer ?? {} : {};
-      case "broadcast" /* Broadcast */:
-        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}`);
-      }
-    }
+    return kindOptionsBlock(this.options, kind)?.consumer ?? {};
   }
 };
 
 // src/server/infrastructure/message.provider.ts
-import { Logger as Logger15 } from "@nestjs/common";
+import { Logger as Logger16 } from "@nestjs/common";
 import { DeliverPolicy as DeliverPolicy2 } from "@nats-io/jetstream";
 import {
   catchError,
@@ -4559,7 +4784,7 @@ var MessageProvider = class {
     this.consumeOptionsMap = consumeOptionsMap;
     this.consumerRecoveryFn = consumerRecoveryFn;
   }
-  logger = new Logger15("Jetstream:Message");
+  logger = new Logger16("Jetstream:Message");
   activeIterators = /* @__PURE__ */ new Set();
   orderedReadyResolve = null;
   orderedReadyReject = null;
@@ -4602,7 +4827,7 @@ var MessageProvider = class {
   /**
    * Start an ordered consumer for strict sequential delivery.
    *
-   * Unlike durable consumers, ordered consumers are ephemeral — created at
+   * Unlike durable consumers, ordered consumers are ephemeral: created at
    * consumption time, no durable state. nats.js handles auto-recreation.
    *
    * @param streamName - JetStream stream to consume from.
@@ -4816,7 +5041,7 @@ var MessageProvider = class {
 };
 
 // src/server/infrastructure/metadata.provider.ts
-import { Logger as Logger16 } from "@nestjs/common";
+import { Logger as Logger17 } from "@nestjs/common";
 import { Kvm } from "@nats-io/kv";
 var MetadataProvider = class {
   constructor(options, connection) {
@@ -4825,7 +5050,7 @@ var MetadataProvider = class {
     this.replicas = options.metadata?.replicas ?? DEFAULT_METADATA_REPLICAS;
     this.ttl = Math.max(options.metadata?.ttl ?? DEFAULT_METADATA_TTL, MIN_METADATA_TTL);
   }
-  logger = new Logger16("Jetstream:Metadata");
+  logger = new Logger17("Jetstream:Metadata");
   bucketName;
   replicas;
   ttl;
@@ -4833,16 +5058,12 @@ var MetadataProvider = class {
   heartbeatTimer;
   cachedKv;
   /**
-   * Write handler metadata entries to the KV bucket and start heartbeat.
+   * Write handler metadata entries to the KV bucket and start the 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.
+   * Creates the bucket if missing; skips silently when the map is empty.
+   * Non-critical: errors are logged but do not prevent transport startup.
    *
-   * Non-critical — errors are logged but do not prevent transport startup.
-   *
-   * @param entries Map of KV key → metadata object.
+   * @param entries Map of KV key to metadata object.
    */
   async publish(entries) {
     if (entries.size === 0) return;
@@ -4918,396 +5139,626 @@ var MetadataProvider = class {
 };
 
 // src/server/routing/event.router.ts
-import { Logger as Logger17 } from "@nestjs/common";
+import { Logger as Logger19 } from "@nestjs/common";
+
+// src/server/routing/concurrency-gate.ts
+var BACKLOG_WARN_THRESHOLD = 1e3;
+var ConcurrencyGate = class {
+  constructor(maxActive, route, parkTimer, logger5, label) {
+    this.maxActive = maxActive;
+    this.route = route;
+    this.parkTimer = parkTimer;
+    this.logger = logger5;
+    this.label = label;
+  }
+  active = 0;
+  backlogWarned = false;
+  backlog = [];
+  /** Entry point for each incoming message. */
+  push(msg) {
+    if (this.active >= this.maxActive) {
+      this.backlog.push({
+        msg,
+        stopAckExtension: this.parkTimer ? this.parkTimer(msg) : null
+      });
+      if (!this.backlogWarned && this.backlog.length >= BACKLOG_WARN_THRESHOLD) {
+        this.backlogWarned = true;
+        this.logger.warn(
+          `${this.label} backlog reached ${this.backlog.length} messages; consumer may be falling behind`
+        );
+      }
+      return;
+    }
+    this.active++;
+    const result = this.routeSafely(msg);
+    if (result !== void 0) {
+      this.trackAsync(result, msg);
+    } else {
+      this.active--;
+      if (this.backlog.length > 0) this.drainBacklog();
+    }
+  }
+  /** Stop parked timers and drop the backlog. */
+  dispose() {
+    for (const queued of this.backlog) {
+      queued.stopAckExtension?.();
+    }
+    this.backlog.length = 0;
+  }
+  onAsyncDone = () => {
+    this.active--;
+    this.drainBacklog();
+  };
+  /** A throw here must not leak the concurrency slot or kill the subscription. */
+  routeSafely(msg) {
+    try {
+      return this.route(msg);
+    } catch (err) {
+      this.logger.error(`Unexpected routing failure for ${msg.subject}:`, err);
+      return void 0;
+    }
+  }
+  trackAsync(result, msg) {
+    void result.catch((err) => {
+      this.logger.error(`Unexpected routing failure for ${msg.subject}:`, err);
+    }).finally(this.onAsyncDone);
+  }
+  drainBacklog() {
+    while (this.active < this.maxActive) {
+      const next = this.backlog.shift();
+      if (next === void 0) break;
+      next.stopAckExtension?.();
+      this.active++;
+      const result = this.routeSafely(next.msg);
+      if (result !== void 0) {
+        this.trackAsync(result, next.msg);
+      } else {
+        this.active--;
+      }
+    }
+    if (this.backlog.length < BACKLOG_WARN_THRESHOLD) this.backlogWarned = false;
+  }
+};
+
+// src/server/routing/dead-letter-capture.ts
+import { Logger as Logger18 } from "@nestjs/common";
 import { headers as natsHeaders3 } from "@nats-io/transport-node";
 var DLQ_PUBLISH_ATTEMPTS = 3;
-var eventConsumeKindFor = (kind) => {
-  if (kind === "broadcast" /* Broadcast */) return "broadcast" /* Broadcast */;
-  if (kind === "ordered" /* Ordered */) return "ordered" /* Ordered */;
-  return "event" /* Event */;
-};
-var EventRouter = class {
-  constructor(messageProvider, patternRegistry, codec, eventBus, deadLetterConfig, processingConfig, ackWaitMap, connection, options) {
-    this.messageProvider = messageProvider;
+var DeadLetterCapture = class {
+  constructor(patternRegistry, eventBus, deadLetterConfig, otel, serviceName, serverEndpoint, connection, options, names) {
     this.patternRegistry = patternRegistry;
-    this.codec = codec;
     this.eventBus = eventBus;
     this.deadLetterConfig = deadLetterConfig;
-    this.processingConfig = processingConfig;
-    this.ackWaitMap = ackWaitMap;
+    this.otel = otel;
+    this.serviceName = serviceName;
+    this.serverEndpoint = serverEndpoint;
     this.connection = connection;
     this.options = options;
-    if (options) {
-      const derived = deriveOtelAttrs(options);
-      this.otel = derived.otel;
-      this.serviceName = derived.serviceName;
-      this.serverEndpoint = derived.serverEndpoint;
-    } else {
-      this.otel = resolveOtelOptions({ enabled: false });
-      this.serviceName = "";
-      this.serverEndpoint = null;
-    }
+    this.names = names;
+  }
+  logger = new Logger18("Jetstream:DeadLetter");
+  /** True when this delivery is the consumer's last attempt for the message. */
+  isFinalDelivery(msg) {
+    const maxDeliver = this.deadLetterConfig.maxDeliverByStream?.get(msg.info.stream);
+    if (maxDeliver === void 0 || maxDeliver <= 0) return false;
+    return msg.info.deliveryCount >= maxDeliver;
+  }
+  /** Emit the dead-letter event and route the message to the DLQ or the fallback callback. */
+  async capture(msg, data, error) {
+    const info = {
+      subject: msg.subject,
+      data,
+      headers: msg.headers,
+      error,
+      deliveryCount: msg.info.deliveryCount,
+      stream: msg.info.stream,
+      streamSequence: msg.info.streamSequence,
+      timestamp: new Date(msg.info.timestampNanos / 1e6).toISOString()
+    };
+    await withDeadLetterSpan(
+      {
+        msg,
+        // Surface the registered pattern so APM can filter dead letters by
+        // handler; falls back to the raw subject when no handler matches.
+        pattern: this.patternRegistry.getHandler(msg.subject) ? msg.subject : void 0,
+        finalDeliveryCount: msg.info.deliveryCount,
+        reason: error instanceof Error ? error.message : String(error),
+        serviceName: this.serviceName,
+        endpoint: this.serverEndpoint
+      },
+      this.otel,
+      async () => {
+        this.eventBus.emit("deadLetter" /* DeadLetter */, info);
+        if (!this.options?.dlq) {
+          await this.fallbackToOnDeadLetterCallback(info, msg);
+        } else {
+          await this.publishToDlq(msg, info, error);
+        }
+      }
+    );
   }
-  logger = new Logger17("Jetstream:EventRouter");
-  subscriptions = [];
-  otel;
-  serviceName;
-  serverEndpoint;
   /**
-   * Update the max_deliver thresholds from actual NATS consumer configs.
-   * Called after consumers are ensured so the DLQ map reflects reality.
+   * Publish the dead letter to the DLQ stream with diagnostic headers. On
+   * success the `onDeadLetter` callback is notified and the message termed;
+   * on failure everything falls back to the callback to avoid silent loss.
    */
-  updateMaxDeliverMap(consumerMaxDelivers) {
-    if (!this.deadLetterConfig) return;
-    this.deadLetterConfig.maxDeliverByStream = consumerMaxDelivers;
-  }
-  /** Start routing event, broadcast, and ordered messages to handlers. */
-  start() {
-    this.subscribeToStream(this.messageProvider.events$, "ev" /* Event */);
-    this.subscribeToStream(this.messageProvider.broadcasts$, "broadcast" /* Broadcast */);
-    if (this.patternRegistry.hasOrderedHandlers()) {
-      this.subscribeToStream(this.messageProvider.ordered$, "ordered" /* Ordered */);
+  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;
     }
-  }
-  /** Stop routing and unsubscribe from all streams. */
-  destroy() {
-    for (const sub of this.subscriptions) {
-      sub.unsubscribe();
+    const dlqStreamOverride = this.options.dlq?.stream?.name;
+    const destinationSubject = this.names ? this.names.dlqStreamName() : dlqStreamOverride ?? dlqStreamName(serviceName);
+    const hdrs = this.buildDlqHeaders(msg);
+    hdrs.set("x-dead-letter-reason" /* DeadLetterReason */, this.extractErrorReason(error));
+    hdrs.set("x-original-subject" /* OriginalSubject */, msg.subject);
+    hdrs.set("x-original-stream" /* OriginalStream */, msg.info.stream);
+    hdrs.set("x-failed-at" /* FailedAt */, (/* @__PURE__ */ new Date()).toISOString());
+    hdrs.set("x-delivery-count" /* DeliveryCount */, msg.info.deliveryCount.toString());
+    try {
+      await this.publishWithRetry(this.connection, destinationSubject, msg.data, hdrs);
+      this.logger.log(`Message sent to DLQ: ${msg.subject}`);
+      await this.notifyDeadLetterCallback(info, msg);
+    } catch (publishErr) {
+      this.logger.error(`Failed to publish to DLQ for ${msg.subject}:`, publishErr);
+      await this.fallbackToOnDeadLetterCallback(info, msg);
     }
-    this.subscriptions.length = 0;
   }
-  /** Subscribe to a message stream and route each message to its handler. */
-  subscribeToStream(stream$, kind) {
-    const isOrdered = kind === "ordered" /* Ordered */;
-    const patternRegistry = this.patternRegistry;
-    const codec = this.codec;
-    const eventBus = this.eventBus;
-    const logger5 = this.logger;
-    const deadLetterConfig = this.deadLetterConfig;
-    const otel = this.otel;
-    const serviceName = this.serviceName;
-    const serverEndpoint = this.serverEndpoint;
-    const spanKind = eventConsumeKindFor(kind);
-    const ackExtensionInterval = isOrdered ? null : resolveAckExtensionInterval(this.getAckExtensionConfig(kind), this.ackWaitMap?.get(kind));
-    const hasAckExtension = ackExtensionInterval !== null && ackExtensionInterval > 0;
-    const concurrency = this.getConcurrency(kind);
-    const hasDlqCheck = deadLetterConfig !== void 0;
-    const reportHandlerCompleted = (msg, startedAt, status) => {
-      if (!eventBus.hasHook("handlerCompleted" /* HandlerCompleted */)) return;
-      const declared = patternRegistry.resolveDeclared(msg.subject);
-      const pattern = declared?.pattern ?? msg.subject;
-      const declaredKind = declared?.kind ?? kind;
-      const durationMs = performance.now() - startedAt;
-      eventBus.emit("handlerCompleted" /* HandlerCompleted */, pattern, declaredKind, durationMs, status);
-    };
-    const isDeadLetter = (msg) => {
-      if (!hasDlqCheck) return false;
-      const maxDeliver = deadLetterConfig.maxDeliverByStream?.get(msg.info.stream);
-      if (maxDeliver === void 0 || maxDeliver <= 0) return false;
-      return msg.info.deliveryCount >= maxDeliver;
-    };
-    const handleDeadLetter = hasDlqCheck ? (msg, data, err) => this.handleDeadLetter(msg, data, err) : null;
-    const settleSuccess = (msg, ctx, data) => {
-      if (ctx.shouldTerminate) {
-        settleQuietly(logger5, `Failed to term ${msg.subject}:`, () => {
-          msg.term(ctx.terminateReason);
-        });
-        return void 0;
-      }
-      if (ctx.shouldRetry) {
-        if (handleDeadLetter !== null && isDeadLetter(msg)) {
-          return handleDeadLetter(
-            msg,
-            data,
-            new Error("Retry requested on the final delivery attempt")
+  /**
+   * Past max_deliver the server never redelivers, so these in-process attempts
+   * are the only second chance a dead letter gets. No artificial delay: an
+   * unreachable broker already spaces attempts via its own request timeout.
+   */
+  async publishWithRetry(connection, subject, data, headers2) {
+    let lastErr;
+    for (let attempt = 1; attempt <= DLQ_PUBLISH_ATTEMPTS; attempt += 1) {
+      try {
+        await connection.getJetStreamClient().publish(subject, data, { headers: headers2 });
+        return;
+      } catch (err) {
+        lastErr = err;
+        if (attempt < DLQ_PUBLISH_ATTEMPTS) {
+          this.logger.warn(
+            `DLQ publish attempt ${attempt}/${DLQ_PUBLISH_ATTEMPTS} failed for ${subject}, retrying`
           );
         }
-        settleQuietly(logger5, `Failed to nak ${msg.subject}:`, () => {
-          msg.nak(ctx.retryDelay);
-        });
-        return void 0;
       }
-      settleQuietly(logger5, `Failed to ack ${msg.subject}:`, () => {
-        msg.ack();
-      });
-      return void 0;
-    };
-    const settleFailure = async (msg, data, err) => {
-      if (handleDeadLetter !== null && isDeadLetter(msg)) {
-        await handleDeadLetter(msg, data, err);
-        return;
+    }
+    throw lastErr;
+  }
+  /**
+   * Copy headers for the DLQ republish, dropping NATS control headers: a
+   * copied Nats-TTL would expire the DLQ entry, Nats-Msg-Id trips dedup.
+   */
+  buildDlqHeaders(msg) {
+    const hdrs = natsHeaders3();
+    if (!msg.headers) return hdrs;
+    for (const [k, v] of msg.headers) {
+      if (k.toLowerCase().startsWith(NATS_CONTROL_HEADER_PREFIX)) continue;
+      for (const val of v) {
+        hdrs.append(k, val);
       }
-      settleQuietly(logger5, `Failed to nak ${msg.subject}:`, () => {
-        msg.nak();
-      });
-    };
-    const captureUnroutable = (capture, msg, err) => {
-      let data;
+    }
+    return hdrs;
+  }
+  async notifyDeadLetterCallback(info, msg) {
+    if (this.deadLetterConfig.onDeadLetter) {
       try {
-        data = codec.decode(msg.data);
-      } catch {
-        data = void 0;
+        await this.deadLetterConfig.onDeadLetter(info);
+      } catch (hookErr) {
+        this.logger.warn(
+          `onDeadLetter callback failed after successful DLQ publish for ${msg.subject}`,
+          hookErr
+        );
       }
-      return capture(msg, data, err).catch((captureErr) => {
-        logger5.error(`Dead-letter capture failed for unroutable ${msg.subject}:`, captureErr);
+    }
+    settleQuietly(this.logger, `Failed to term ${msg.subject}:`, () => {
+      msg.term("Moved to DLQ stream");
+    });
+  }
+  /**
+   * Last resort: invoke onDeadLetter, then term on success. On failure the
+   * message is nak'd: never redelivered past max_deliver, but preserved.
+   */
+  async fallbackToOnDeadLetterCallback(info, msg) {
+    const onDeadLetter = this.deadLetterConfig.onDeadLetter;
+    if (!onDeadLetter) {
+      this.logger.error(
+        `Dead letter for ${msg.subject} could not be captured (DLQ publish failed, no onDeadLetter callback); leaving the message in the stream`
+      );
+      settleQuietly(this.logger, `Failed to nak ${msg.subject}:`, () => {
+        msg.nak();
       });
-    };
-    const resolveEvent = (msg) => {
-      const subject = msg.subject;
-      try {
-        const handler = patternRegistry.getHandler(subject);
-        if (!handler) {
-          logger5.error(`No handler for subject: ${subject}`);
-          if (handleDeadLetter !== null) {
-            return captureUnroutable(
-              handleDeadLetter,
-              msg,
-              new Error(`No handler for event: ${subject}`)
-            );
-          }
-          msg.term(`No handler for event: ${subject}`);
-          return null;
-        }
-        let data;
-        try {
-          data = codec.decode(msg.data);
-        } catch (err) {
-          logger5.error(`Decode error for ${subject}:`, err);
-          if (handleDeadLetter !== null) {
-            return captureUnroutable(
-              handleDeadLetter,
-              msg,
-              new Error(`Decode error: ${err instanceof Error ? err.message : String(err)}`)
-            );
-          }
-          msg.term("Decode error");
-          return null;
+      return;
+    }
+    try {
+      await onDeadLetter(info);
+      settleQuietly(this.logger, `Failed to term ${msg.subject}:`, () => {
+        msg.term("Dead letter processed via fallback callback");
+      });
+    } catch (hookErr) {
+      this.logger.error(
+        `Fallback onDeadLetter callback failed for ${msg.subject}; the message stays in the stream and will not be redelivered (max_deliver exhausted); recover it manually:`,
+        hookErr
+      );
+      settleQuietly(this.logger, `Failed to nak ${msg.subject}:`, () => {
+        msg.nak();
+      });
+    }
+  }
+  extractErrorReason(error) {
+    if (error instanceof Error) {
+      return error.message;
+    }
+    if (typeof error === "object" && error !== null && "message" in error) {
+      return String(error.message);
+    }
+    return String(error);
+  }
+};
+
+// src/server/routing/settlement.ts
+var statusForContext = (ctx) => {
+  if (ctx.shouldTerminate) return "terminated";
+  if (ctx.shouldRetry) return "retried";
+  return "success";
+};
+var createSettlement = (logger5, capture) => {
+  const settleSuccess = (msg, ctx, data) => {
+    if (ctx.shouldTerminate) {
+      settleQuietly(logger5, `Failed to term ${msg.subject}:`, () => {
+        msg.term(ctx.terminateReason);
+      });
+      return void 0;
+    }
+    if (ctx.shouldRetry) {
+      if (capture?.isFinalDelivery(msg)) {
+        return capture.capture(
+          msg,
+          data,
+          new Error("Retry requested on the final delivery attempt")
+        );
+      }
+      settleQuietly(logger5, `Failed to nak ${msg.subject}:`, () => {
+        msg.nak(ctx.retryDelay);
+      });
+      return void 0;
+    }
+    settleQuietly(logger5, `Failed to ack ${msg.subject}:`, () => {
+      msg.ack();
+    });
+    return void 0;
+  };
+  const settleFailure = async (msg, data, err) => {
+    if (capture?.isFinalDelivery(msg)) {
+      await capture.capture(msg, data, err);
+      return;
+    }
+    settleQuietly(logger5, `Failed to nak ${msg.subject}:`, () => {
+      msg.nak();
+    });
+  };
+  return { settleSuccess, settleFailure };
+};
+
+// src/server/routing/event-pipeline.ts
+var createHandlerReporter = (rctx) => {
+  const { eventBus, patternRegistry, kind } = rctx;
+  return (msg, startedAt, status) => {
+    if (!eventBus.hasHook("handlerCompleted" /* HandlerCompleted */)) return;
+    const declared = patternRegistry.resolveDeclared(msg.subject);
+    const pattern = declared?.pattern ?? msg.subject;
+    const declaredKind = declared?.kind ?? kind;
+    const durationMs = performance.now() - startedAt;
+    eventBus.emit("handlerCompleted" /* HandlerCompleted */, pattern, declaredKind, durationMs, status);
+  };
+};
+var createEventResolver = (rctx) => {
+  const { patternRegistry, codec, eventBus, logger: logger5, capture, kind } = rctx;
+  const captureUnroutable = (activeCapture, msg, err) => {
+    let data;
+    try {
+      data = codec.decode(msg.data);
+    } catch {
+      data = void 0;
+    }
+    return activeCapture.capture(msg, data, err).catch((captureErr) => {
+      logger5.error(`Dead-letter capture failed for unroutable ${msg.subject}:`, captureErr);
+    });
+  };
+  return (msg) => {
+    const subject = msg.subject;
+    try {
+      const handler = patternRegistry.getHandler(subject);
+      if (!handler) {
+        logger5.error(`No handler for subject: ${subject}`);
+        if (capture !== null) {
+          return captureUnroutable(capture, msg, new Error(`No handler for event: ${subject}`));
         }
-        eventBus.emitMessageRouted(subject, "event" /* Event */);
-        return { handler, data };
+        msg.term(`No handler for event: ${subject}`);
+        return null;
+      }
+      let data;
+      try {
+        data = codec.decode(msg.data);
       } catch (err) {
-        logger5.error(`Unexpected error in ${kind} event router`, err);
-        try {
-          msg.term("Unexpected router error");
-        } catch (termErr) {
-          logger5.error(`Failed to terminate message ${subject}:`, termErr);
+        logger5.error(`Decode error for ${subject}:`, err);
+        if (capture !== null) {
+          return captureUnroutable(
+            capture,
+            msg,
+            new Error(`Decode error: ${err instanceof Error ? err.message : String(err)}`)
+          );
         }
+        msg.term("Decode error");
         return null;
       }
-    };
-    const statusForContext = (ctx) => {
-      if (ctx.shouldTerminate) return "terminated";
-      if (ctx.shouldRetry) return "retried";
-      return "success";
-    };
-    const handleSafe = (msg) => {
-      const resolved = resolveEvent(msg);
-      if (resolved === null) return void 0;
-      if (isPromiseLike2(resolved)) return resolved;
-      const { handler, data } = resolved;
-      const ctx = new RpcContext([msg]);
-      const stopAckExtension = hasAckExtension ? startAckExtensionTimer(msg, ackExtensionInterval) : null;
-      const startedAt = performance.now();
-      let pending;
+      eventBus.emitMessageRouted(subject, "event" /* Event */);
+      return { handler, data };
+    } catch (err) {
+      logger5.error(`Unexpected error in ${kind} event router`, err);
       try {
-        pending = withConsumeSpan(
-          {
-            subject: msg.subject,
-            msg,
-            info: msg.info,
-            kind: spanKind,
-            payloadBytes: msg.data.length,
-            handlerMetadata: { pattern: msg.subject },
-            serviceName,
-            endpoint: serverEndpoint
-          },
-          otel,
-          () => unwrapResult(handler(data, ctx))
-        );
-      } catch (err) {
+        msg.term("Unexpected router error");
+      } catch (termErr) {
+        logger5.error(`Failed to terminate message ${subject}:`, termErr);
+      }
+      return null;
+    }
+  };
+};
+var createWorkqueuePipeline = (rctx) => {
+  const { kind, spanKind, logger: logger5, eventBus, otel, serviceName, serverEndpoint } = rctx;
+  const { ackExtensionInterval } = rctx;
+  const hasAckExtension = ackExtensionInterval !== null && ackExtensionInterval > 0;
+  const reportHandlerCompleted = createHandlerReporter(rctx);
+  const resolveEvent = createEventResolver(rctx);
+  const { settleSuccess, settleFailure } = createSettlement(logger5, rctx.capture);
+  return (msg) => {
+    const resolved = resolveEvent(msg);
+    if (resolved === null) return void 0;
+    if (isPromiseLike2(resolved)) return resolved;
+    const { handler, data } = resolved;
+    const ctx = new RpcContext([msg]);
+    const stopAckExtension = hasAckExtension ? startAckExtensionTimer(msg, ackExtensionInterval) : null;
+    const startedAt = performance.now();
+    let pending;
+    try {
+      pending = withConsumeSpan(
+        {
+          subject: msg.subject,
+          msg,
+          info: msg.info,
+          kind: spanKind,
+          payloadBytes: msg.data.length,
+          handlerMetadata: { pattern: msg.subject },
+          serviceName,
+          endpoint: serverEndpoint
+        },
+        otel,
+        () => unwrapResult(handler(data, ctx))
+      );
+    } catch (err) {
+      eventBus.emit(
+        "error" /* Error */,
+        err instanceof Error ? err : new Error(String(err)),
+        `${kind}-handler:${msg.subject}`
+      );
+      reportHandlerCompleted(msg, startedAt, "error");
+      return settleFailure(msg, data, err).finally(() => {
+        if (stopAckExtension !== null) stopAckExtension();
+      });
+    }
+    if (!isPromiseLike2(pending)) {
+      const settled = settleSuccess(msg, ctx, data);
+      reportHandlerCompleted(msg, startedAt, statusForContext(ctx));
+      if (settled === void 0) {
+        if (stopAckExtension !== null) stopAckExtension();
+        return void 0;
+      }
+      return settled.finally(() => {
+        if (stopAckExtension !== null) stopAckExtension();
+      });
+    }
+    return pending.then(
+      async () => {
+        try {
+          await settleSuccess(msg, ctx, data);
+          reportHandlerCompleted(msg, startedAt, statusForContext(ctx));
+        } finally {
+          if (stopAckExtension !== null) stopAckExtension();
+        }
+      },
+      async (err) => {
         eventBus.emit(
           "error" /* Error */,
           err instanceof Error ? err : new Error(String(err)),
           `${kind}-handler:${msg.subject}`
         );
         reportHandlerCompleted(msg, startedAt, "error");
-        return settleFailure(msg, data, err).finally(() => {
-          if (stopAckExtension !== null) stopAckExtension();
-        });
-      }
-      if (!isPromiseLike2(pending)) {
-        const settled = settleSuccess(msg, ctx, data);
-        reportHandlerCompleted(msg, startedAt, statusForContext(ctx));
-        if (settled === void 0) {
+        try {
+          await settleFailure(msg, data, err);
+        } finally {
           if (stopAckExtension !== null) stopAckExtension();
-          return void 0;
         }
-        return settled.finally(() => {
-          if (stopAckExtension !== null) stopAckExtension();
-        });
       }
-      return pending.then(
-        async () => {
-          try {
-            await settleSuccess(msg, ctx, data);
-            reportHandlerCompleted(msg, startedAt, statusForContext(ctx));
-          } finally {
-            if (stopAckExtension !== null) stopAckExtension();
-          }
-        },
-        async (err) => {
-          eventBus.emit(
-            "error" /* Error */,
-            err instanceof Error ? err : new Error(String(err)),
-            `${kind}-handler:${msg.subject}`
-          );
-          reportHandlerCompleted(msg, startedAt, "error");
-          try {
-            await settleFailure(msg, data, err);
-          } finally {
-            if (stopAckExtension !== null) stopAckExtension();
-          }
-        }
-      );
-    };
-    const handleOrderedSafe = (msg) => {
-      const subject = msg.subject;
-      let handler;
-      let data;
-      try {
-        handler = patternRegistry.getHandler(subject);
-        if (!handler) {
-          logger5.error(`No handler for subject: ${subject}`);
-          return void 0;
-        }
-        try {
-          data = codec.decode(msg.data);
-        } catch (err) {
-          logger5.error(`Decode error for ${subject}:`, err);
-          return void 0;
-        }
-        eventBus.emitMessageRouted(subject, "event" /* Event */);
-      } catch (err) {
-        logger5.error(`Ordered handler error (${subject}):`, err);
+    );
+  };
+};
+var createOrderedPipeline = (rctx) => {
+  const { spanKind, codec, logger: logger5, eventBus, patternRegistry, otel } = rctx;
+  const { serviceName, serverEndpoint } = rctx;
+  const reportHandlerCompleted = createHandlerReporter(rctx);
+  return (msg) => {
+    const subject = msg.subject;
+    let handler;
+    let data;
+    try {
+      handler = patternRegistry.getHandler(subject);
+      if (!handler) {
+        logger5.error(`No handler for subject: ${subject}`);
         return void 0;
       }
-      const ctx = new RpcContext([msg]);
-      const warnIfSettlementAttempted = () => {
-        if (ctx.shouldRetry || ctx.shouldTerminate) {
-          logger5.warn(
-            `retry()/terminate() ignored for ordered message ${subject} \u2014 ordered consumers auto-acknowledge`
-          );
-        }
-      };
-      const startedAt = performance.now();
-      let pending;
       try {
-        pending = withConsumeSpan(
-          {
-            subject: msg.subject,
-            msg,
-            info: msg.info,
-            kind: spanKind,
-            payloadBytes: msg.data.length,
-            handlerMetadata: { pattern: msg.subject },
-            serviceName,
-            endpoint: serverEndpoint
-          },
-          otel,
-          () => unwrapResult(handler(data, ctx))
-        );
+        data = codec.decode(msg.data);
       } catch (err) {
-        logger5.error(`Ordered handler error (${subject}):`, err);
-        reportHandlerCompleted(msg, startedAt, "error");
+        logger5.error(`Decode error for ${subject}:`, err);
         return void 0;
       }
-      if (!isPromiseLike2(pending)) {
-        warnIfSettlementAttempted();
-        reportHandlerCompleted(msg, startedAt, "success");
-        return void 0;
+      eventBus.emitMessageRouted(subject, "event" /* Event */);
+    } catch (err) {
+      logger5.error(`Ordered handler error (${subject}):`, err);
+      return void 0;
+    }
+    const ctx = new RpcContext([msg]);
+    const warnIfSettlementAttempted = () => {
+      if (ctx.shouldRetry || ctx.shouldTerminate) {
+        logger5.warn(
+          `retry()/terminate() ignored for ordered message ${subject}; ordered consumers auto-acknowledge`
+        );
       }
-      return pending.then(
-        () => {
-          warnIfSettlementAttempted();
-          reportHandlerCompleted(msg, startedAt, "success");
+    };
+    const startedAt = performance.now();
+    let pending;
+    try {
+      pending = withConsumeSpan(
+        {
+          subject: msg.subject,
+          msg,
+          info: msg.info,
+          kind: spanKind,
+          payloadBytes: msg.data.length,
+          handlerMetadata: { pattern: msg.subject },
+          serviceName,
+          endpoint: serverEndpoint
         },
-        (err) => {
-          logger5.error(`Ordered handler error (${subject}):`, err);
-          reportHandlerCompleted(msg, startedAt, "error");
-        }
+        otel,
+        () => unwrapResult(handler(data, ctx))
       );
-    };
-    const route = isOrdered ? handleOrderedSafe : handleSafe;
-    const maxActive = isOrdered ? 1 : concurrency ?? Number.POSITIVE_INFINITY;
-    const backlogWarnThreshold = 1e3;
-    let active = 0;
-    let backlogWarned = false;
-    const backlog = [];
-    const onAsyncDone = () => {
-      active--;
-      drainBacklog();
-    };
-    const routeSafely = (msg) => {
-      try {
-        return route(msg);
-      } catch (err) {
-        logger5.error(`Unexpected routing failure for ${msg.subject}:`, err);
-        return void 0;
-      }
-    };
-    const trackAsync = (result, msg) => {
-      void result.catch((err) => {
-        logger5.error(`Unexpected routing failure for ${msg.subject}:`, err);
-      }).finally(onAsyncDone);
-    };
-    const drainBacklog = () => {
-      while (active < maxActive) {
-        const next = backlog.shift();
-        if (next === void 0) return;
-        next.stopAckExtension?.();
-        active++;
-        const result = routeSafely(next.msg);
-        if (result !== void 0) {
-          trackAsync(result, next.msg);
-        } else {
-          active--;
-        }
+    } catch (err) {
+      logger5.error(`Ordered handler error (${subject}):`, err);
+      reportHandlerCompleted(msg, startedAt, "error");
+      return void 0;
+    }
+    if (!isPromiseLike2(pending)) {
+      warnIfSettlementAttempted();
+      reportHandlerCompleted(msg, startedAt, "success");
+      return void 0;
+    }
+    return pending.then(
+      () => {
+        warnIfSettlementAttempted();
+        reportHandlerCompleted(msg, startedAt, "success");
+      },
+      (err) => {
+        logger5.error(`Ordered handler error (${subject}):`, err);
+        reportHandlerCompleted(msg, startedAt, "error");
       }
-      if (backlog.length < backlogWarnThreshold) backlogWarned = false;
+    );
+  };
+};
+
+// src/server/routing/event.router.ts
+var eventConsumeKindFor = (kind) => {
+  if (kind === "broadcast" /* Broadcast */) return "broadcast" /* Broadcast */;
+  if (kind === "ordered" /* Ordered */) return "ordered" /* Ordered */;
+  return "event" /* Event */;
+};
+var EventRouter = class {
+  constructor(messageProvider, patternRegistry, codec, eventBus, deadLetterConfig, processingConfig, ackWaitMap, connection, options, names) {
+    this.messageProvider = messageProvider;
+    this.patternRegistry = patternRegistry;
+    this.codec = codec;
+    this.eventBus = eventBus;
+    this.deadLetterConfig = deadLetterConfig;
+    this.processingConfig = processingConfig;
+    this.ackWaitMap = ackWaitMap;
+    if (options) {
+      const derived = deriveOtelAttrs(options);
+      this.otel = derived.otel;
+      this.serviceName = derived.serviceName;
+      this.serverEndpoint = derived.serverEndpoint;
+    } else {
+      this.otel = resolveOtelOptions({ enabled: false });
+      this.serviceName = "";
+      this.serverEndpoint = null;
+    }
+    this.capture = deadLetterConfig ? new DeadLetterCapture(
+      patternRegistry,
+      eventBus,
+      deadLetterConfig,
+      this.otel,
+      this.serviceName,
+      this.serverEndpoint,
+      connection,
+      options,
+      names
+    ) : null;
+  }
+  logger = new Logger19("Jetstream:EventRouter");
+  subscriptions = [];
+  otel;
+  serviceName;
+  serverEndpoint;
+  capture;
+  /**
+   * Update the max_deliver thresholds from actual NATS consumer configs.
+   * Called after consumers are ensured so the DLQ map reflects reality.
+   */
+  updateMaxDeliverMap(consumerMaxDelivers) {
+    if (!this.deadLetterConfig) return;
+    this.deadLetterConfig.maxDeliverByStream = consumerMaxDelivers;
+  }
+  /** Start routing event, broadcast, and ordered messages to handlers. */
+  start() {
+    this.subscribeToStream(this.messageProvider.events$, "ev" /* Event */);
+    this.subscribeToStream(this.messageProvider.broadcasts$, "broadcast" /* Broadcast */);
+    if (this.patternRegistry.hasOrderedHandlers()) {
+      this.subscribeToStream(this.messageProvider.ordered$, "ordered" /* Ordered */);
+    }
+  }
+  /** Stop routing and unsubscribe from all streams. */
+  destroy() {
+    for (const sub of this.subscriptions) {
+      sub.unsubscribe();
+    }
+    this.subscriptions.length = 0;
+  }
+  /** Assemble the pipeline and concurrency gate for one stream and subscribe. */
+  subscribeToStream(stream$, kind) {
+    const isOrdered = kind === "ordered" /* Ordered */;
+    const ackExtensionInterval = isOrdered ? null : resolveAckExtensionInterval(this.getAckExtensionConfig(kind), this.ackWaitMap?.get(kind));
+    const rctx = {
+      kind,
+      spanKind: eventConsumeKindFor(kind),
+      codec: this.codec,
+      logger: this.logger,
+      eventBus: this.eventBus,
+      patternRegistry: this.patternRegistry,
+      otel: this.otel,
+      serviceName: this.serviceName,
+      serverEndpoint: this.serverEndpoint,
+      ackExtensionInterval,
+      capture: this.capture
     };
+    const route = isOrdered ? createOrderedPipeline(rctx) : createWorkqueuePipeline(rctx);
+    const maxActive = isOrdered ? 1 : this.getConcurrency(kind) ?? Number.POSITIVE_INFINITY;
+    const hasAckExtension = ackExtensionInterval !== null && ackExtensionInterval > 0;
+    const parkTimer = hasAckExtension ? (msg) => startAckExtensionTimer(msg, ackExtensionInterval) : null;
+    const gate = new ConcurrencyGate(maxActive, route, parkTimer, this.logger, kind);
     const subscription = stream$.subscribe({
-      next: (msg) => {
-        if (active >= maxActive) {
-          backlog.push({
-            msg,
-            stopAckExtension: hasAckExtension ? startAckExtensionTimer(msg, ackExtensionInterval) : null
-          });
-          if (!backlogWarned && backlog.length >= backlogWarnThreshold) {
-            backlogWarned = true;
-            logger5.warn(
-              `${kind} backlog reached ${backlog.length} messages \u2014 consumer may be falling behind`
-            );
-          }
-          return;
-        }
-        active++;
-        const result = routeSafely(msg);
-        if (result !== void 0) {
-          trackAsync(result, msg);
-        } else {
-          active--;
-          if (backlog.length > 0) drainBacklog();
-        }
+      next: (msg) => {
+        gate.push(msg);
       },
       error: (err) => {
-        logger5.error(`Stream error in ${kind} router`, err);
+        this.logger.error(`Stream error in ${kind} router`, err);
       }
     });
     subscription.add(() => {
-      for (const queued of backlog) {
-        queued.stopAckExtension?.();
-      }
-      backlog.length = 0;
+      gate.dispose();
     });
     this.subscriptions.push(subscription);
   }
@@ -5321,169 +5772,10 @@ var EventRouter = class {
     if (kind === "broadcast" /* Broadcast */) return this.processingConfig?.broadcast?.ackExtension;
     return void 0;
   }
-  /**
-   * Last resort: invoke onDeadLetter, then term on success. On failure the
-   * message is nak'd — never redelivered past max_deliver, but preserved.
-   */
-  async fallbackToOnDeadLetterCallback(info, msg) {
-    const onDeadLetter = this.deadLetterConfig?.onDeadLetter;
-    if (!onDeadLetter) {
-      this.logger.error(
-        `Dead letter for ${msg.subject} could not be captured (DLQ publish failed, no onDeadLetter callback) \u2014 leaving the message in the stream`
-      );
-      settleQuietly(this.logger, `Failed to nak ${msg.subject}:`, () => {
-        msg.nak();
-      });
-      return;
-    }
-    try {
-      await onDeadLetter(info);
-      settleQuietly(this.logger, `Failed to term ${msg.subject}:`, () => {
-        msg.term("Dead letter processed via fallback callback");
-      });
-    } catch (hookErr) {
-      this.logger.error(
-        `Fallback onDeadLetter callback failed for ${msg.subject} \u2014 the message stays in the stream and will not be redelivered (max_deliver exhausted); recover it manually:`,
-        hookErr
-      );
-      settleQuietly(this.logger, `Failed to nak ${msg.subject}:`, () => {
-        msg.nak();
-      });
-    }
-  }
-  /**
-   * Copy headers for the DLQ republish, dropping NATS control headers — a
-   * copied Nats-TTL would expire the DLQ entry, Nats-Msg-Id trips dedup.
-   */
-  buildDlqHeaders(msg) {
-    const hdrs = natsHeaders3();
-    if (!msg.headers) return hdrs;
-    for (const [k, v] of msg.headers) {
-      if (k.toLowerCase().startsWith(NATS_CONTROL_HEADER_PREFIX)) continue;
-      for (const val of v) {
-        hdrs.append(k, val);
-      }
-    }
-    return hdrs;
-  }
-  /**
-   * Past max_deliver the server never redelivers, so these in-process attempts
-   * are the only second chance a dead letter gets. No artificial delay — an
-   * unreachable broker already spaces attempts via its own request timeout.
-   */
-  async publishToDlqWithRetry(connection, subject, data, headers2) {
-    let lastErr;
-    for (let attempt = 1; attempt <= DLQ_PUBLISH_ATTEMPTS; attempt += 1) {
-      try {
-        await connection.getJetStreamClient().publish(subject, data, { headers: headers2 });
-        return;
-      } catch (err) {
-        lastErr = err;
-        if (attempt < DLQ_PUBLISH_ATTEMPTS) {
-          this.logger.warn(
-            `DLQ publish attempt ${attempt}/${DLQ_PUBLISH_ATTEMPTS} failed for ${subject}, retrying`
-          );
-        }
-      }
-    }
-    throw lastErr;
-  }
-  /**
-   * 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 = this.buildDlqHeaders(msg);
-    let reason = String(error);
-    if (error instanceof Error) {
-      reason = error.message;
-    } else if (typeof error === "object" && error !== null && "message" in error) {
-      reason = String(error.message);
-    }
-    hdrs.set("x-dead-letter-reason" /* DeadLetterReason */, reason);
-    hdrs.set("x-original-subject" /* OriginalSubject */, msg.subject);
-    hdrs.set("x-original-stream" /* OriginalStream */, msg.info.stream);
-    hdrs.set("x-failed-at" /* FailedAt */, (/* @__PURE__ */ new Date()).toISOString());
-    hdrs.set("x-delivery-count" /* DeliveryCount */, msg.info.deliveryCount.toString());
-    try {
-      await this.publishToDlqWithRetry(this.connection, destinationSubject, msg.data, 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
-          );
-        }
-      }
-      settleQuietly(this.logger, `Failed to term ${msg.subject}:`, () => {
-        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,
-      data,
-      headers: msg.headers,
-      error,
-      deliveryCount: msg.info.deliveryCount,
-      stream: msg.info.stream,
-      streamSequence: msg.info.streamSequence,
-      timestamp: new Date(msg.info.timestampNanos / 1e6).toISOString()
-    };
-    await withDeadLetterSpan(
-      {
-        msg,
-        // Pattern resolution mirrors event-routing: when a registered
-        // pattern matches, surface it on the DLQ span so APM can filter
-        // dead letters by handler without parsing the subject. Falls back
-        // to the subject itself when no glob handler is in play.
-        pattern: this.patternRegistry.getHandler(msg.subject) ? msg.subject : void 0,
-        finalDeliveryCount: msg.info.deliveryCount,
-        reason: error instanceof Error ? error.message : String(error),
-        serviceName: this.serviceName,
-        endpoint: this.serverEndpoint
-      },
-      this.otel,
-      async () => {
-        this.eventBus.emit("deadLetter" /* DeadLetter */, info);
-        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 Logger18 } from "@nestjs/common";
+import { Logger as Logger20 } from "@nestjs/common";
 import { headers } from "@nats-io/transport-node";
 var RpcRouter = class {
   constructor(messageProvider, patternRegistry, connection, codec, eventBus, rpcOptions, ackWaitMap, options) {
@@ -5507,7 +5799,7 @@ var RpcRouter = class {
       this.serverEndpoint = null;
     }
   }
-  logger = new Logger18("Jetstream:RpcRouter");
+  logger = new Logger20("Jetstream:RpcRouter");
   timeout;
   concurrency;
   resolvedAckExtensionInterval;
@@ -5698,75 +5990,18 @@ var RpcRouter = class {
         }
       );
     };
-    const backlogWarnThreshold = 1e3;
-    let active = 0;
-    let backlogWarned = false;
-    const backlog = [];
-    const onAsyncDone = () => {
-      active--;
-      drainBacklog();
-    };
-    const routeSafely = (msg) => {
-      try {
-        return handleSafe(msg);
-      } catch (err) {
-        logger5.error(`Unexpected routing failure for ${msg.subject}:`, err);
-        return void 0;
-      }
-    };
-    const trackAsync = (result, msg) => {
-      void result.catch((err) => {
-        logger5.error(`Unexpected routing failure for ${msg.subject}:`, err);
-      }).finally(onAsyncDone);
-    };
-    const drainBacklog = () => {
-      while (active < maxActive) {
-        const next = backlog.shift();
-        if (next === void 0) return;
-        next.stopAckExtension?.();
-        active++;
-        const result = routeSafely(next.msg);
-        if (result !== void 0) {
-          trackAsync(result, next.msg);
-        } else {
-          active--;
-        }
-      }
-      if (backlog.length < backlogWarnThreshold) backlogWarned = false;
-    };
+    const parkTimer = hasAckExtension ? (msg) => startAckExtensionTimer(msg, ackExtensionInterval) : null;
+    const gate = new ConcurrencyGate(maxActive, handleSafe, parkTimer, logger5, "RPC");
     this.subscription = this.messageProvider.commands$.subscribe({
       next: (msg) => {
-        if (active >= maxActive) {
-          backlog.push({
-            msg,
-            stopAckExtension: hasAckExtension ? startAckExtensionTimer(msg, ackExtensionInterval) : null
-          });
-          if (!backlogWarned && backlog.length >= backlogWarnThreshold) {
-            backlogWarned = true;
-            logger5.warn(
-              `RPC backlog reached ${backlog.length} messages \u2014 consumer may be falling behind`
-            );
-          }
-          return;
-        }
-        active++;
-        const result = routeSafely(msg);
-        if (result !== void 0) {
-          trackAsync(result, msg);
-        } else {
-          active--;
-          if (backlog.length > 0) drainBacklog();
-        }
+        gate.push(msg);
       },
       error: (err) => {
         logger5.error("Stream error in RPC router", err);
       }
     });
     this.subscription.add(() => {
-      for (const queued of backlog) {
-        queued.stopAckExtension?.();
-      }
-      backlog.length = 0;
+      gate.dispose();
     });
   }
   /** Stop routing and unsubscribe. */
@@ -5776,20 +6011,220 @@ var RpcRouter = class {
   }
 };
 
+// src/server/infrastructure/infrastructure-binder.ts
+import { Logger as Logger21 } from "@nestjs/common";
+import { JetStreamApiError as JetStreamApiError4, RetentionPolicy as RetentionPolicy3 } from "@nats-io/jetstream";
+var WORKQUEUE_KINDS = /* @__PURE__ */ new Set(["ev" /* Event */, "cmd" /* Command */]);
+var manualRemediation = (entity) => `Management mode is Manual; the ${entity} must be provisioned externally before boot.`;
+var isSchedulingEnabled = (options, kind) => kindOptionsBlock(options, kind)?.stream?.allow_msg_schedules === true;
+var resolveAckExtension = (options, kind) => kindOptionsBlock(options, kind)?.ackExtension;
+var filterCoversSubject = (filter_subject, filter_subjects, subject) => {
+  if (filter_subject !== void 0) {
+    return coversOrEquals(filter_subject, subject);
+  }
+  if (filter_subjects !== void 0) {
+    return filter_subjects.some((f) => coversOrEquals(f, subject));
+  }
+  return true;
+};
+var InfrastructureBinder = class {
+  constructor(options, names, registry) {
+    this.options = options;
+    this.names = names;
+    this.registry = registry;
+  }
+  logger = new Logger21("Jetstream:Binder");
+  async bindStream(jsm, kind) {
+    const name = this.names.streamName(kind);
+    const info = await this.fetchStream(jsm, name, kind);
+    await this.warnOnOrphanedMigrationBackup(jsm, name);
+    if (isSchedulingEnabled(this.options, kind)) {
+      this.assertScheduleCoverage(info, kind);
+      this.warnOnSchedulesDisabled(info, kind);
+    }
+    if (WORKQUEUE_KINDS.has(kind)) {
+      this.warnOnRetention(info, kind);
+    }
+    return info;
+  }
+  async bindDlqStream(jsm) {
+    const dlqName = this.names.dlqStreamName();
+    const info = await this.fetchStream(jsm, dlqName, "dlq");
+    await this.warnOnOrphanedMigrationBackup(jsm, dlqName);
+    this.assertDlqSubjectCoverage(info);
+    return info;
+  }
+  async bindConsumer(jsm, kind) {
+    const info = await this.fetchConsumer(jsm, kind);
+    this.assertHandlersCovered(info, kind);
+    this.assertScheduleHoldersNotConsumed(info, kind);
+    this.warnOnUnlimitedDelivery(info, kind);
+    this.warnOnShortAckWait(info, kind);
+    return info;
+  }
+  async fetchStream(jsm, name, kind) {
+    try {
+      return await jsm.streams.info(name);
+    } catch (err) {
+      if (err instanceof JetStreamApiError4 && err.apiError().err_code === 10059 /* StreamNotFound */) {
+        const api = err.apiError();
+        throw new JetstreamProvisioningError({
+          entity: "stream",
+          target: name,
+          kind: String(kind),
+          errCode: api.err_code,
+          errDescription: api.description,
+          remediation: manualRemediation("stream"),
+          cause: err
+        });
+      }
+      throw err;
+    }
+  }
+  async fetchConsumer(jsm, kind) {
+    const stream = this.names.streamName(kind);
+    const consumer = this.names.consumerName(kind);
+    try {
+      return await jsm.consumers.info(stream, consumer);
+    } catch (err) {
+      if (err instanceof JetStreamApiError4 && err.apiError().err_code === 10014 /* ConsumerNotFound */) {
+        const api = err.apiError();
+        throw new JetstreamProvisioningError({
+          entity: "consumer",
+          target: `${consumer} on stream "${stream}"`,
+          kind: String(kind),
+          errCode: api.err_code,
+          errDescription: api.description,
+          remediation: manualRemediation("consumer"),
+          cause: err
+        });
+      }
+      throw err;
+    }
+  }
+  assertHandlersCovered(info, kind) {
+    const subjects = this.resolveHandlerSubjects(kind);
+    if (subjects.length === 0) return;
+    const { filter_subject, filter_subjects } = info.config;
+    const uncovered = subjects.filter(
+      (s) => !filterCoversSubject(filter_subject, filter_subjects, s)
+    );
+    if (uncovered.length > 0) {
+      throw new Error(
+        `Consumer "${this.names.consumerName(kind)}" (kind=${String(kind)}) does not cover the following registered handler subjects: ${uncovered.join(", ")}. Update the consumer's filter_subject / filter_subjects to include them.`
+      );
+    }
+  }
+  assertDlqSubjectCoverage(info) {
+    const dlqSubject = this.names.dlqStreamName();
+    const covered = info.config.subjects.some((s) => coversOrEquals(s, dlqSubject));
+    if (!covered) {
+      throw new Error(
+        `DLQ stream "${dlqSubject}" subjects do not cover "${dlqSubject}" (dead letters publish to a subject equal to the stream name). Add it to the stream's subjects list.`
+      );
+    }
+  }
+  assertScheduleCoverage(info, kind) {
+    const scheduleWildcard = `${this.names.schedulePrefix(kind)}>`;
+    const covered = info.config.subjects.some((s) => coversOrEquals(s, scheduleWildcard));
+    if (!covered) {
+      throw new Error(
+        `Stream "${this.names.streamName(kind)}" (kind=${String(kind)}) has scheduling enabled (allow_msg_schedules=true) but its subjects do not cover the schedule prefix "${this.names.schedulePrefix(kind)}". Add "${scheduleWildcard}" to the stream's subjects.`
+      );
+    }
+  }
+  assertScheduleHoldersNotConsumed(info, kind) {
+    if (!isSchedulingEnabled(this.options, kind)) return;
+    const scheduleWildcard = `${this.names.schedulePrefix(kind)}>`;
+    const { filter_subject, filter_subjects } = info.config;
+    const filters = filter_subjects ?? (filter_subject !== void 0 ? [filter_subject] : []);
+    const swallowing = filters.length === 0 ? ["<no filter, consumes the whole stream>"] : filters.filter((f) => coversOrEquals(f, scheduleWildcard));
+    if (swallowing.length > 0) {
+      throw new Error(
+        `Consumer "${this.names.consumerName(kind)}" (kind=${String(kind)}) filter ${swallowing.join(", ")} also matches the schedule namespace "${this.names.schedulePrefix(kind)}". Consuming schedule holders removes pending schedules from the stream. Use exact filter_subjects for the registered handler subjects instead.`
+      );
+    }
+  }
+  async warnOnOrphanedMigrationBackup(jsm, streamName2) {
+    const backupName = `${streamName2}${MIGRATION_BACKUP_SUFFIX}`;
+    try {
+      await jsm.streams.info(backupName);
+    } catch {
+      return;
+    }
+    this.logger.warn(
+      `Found migration backup "${backupName}" for the externally managed stream "${streamName2}". A previous Auto-managed migration was interrupted and undelivered messages may still reside in the backup. Recover them by sourcing the backup back, or re-enable Auto management for one boot to let the library finish the recovery.`
+    );
+  }
+  warnOnSchedulesDisabled(info, kind) {
+    if (info.config.allow_msg_schedules === true) return;
+    this.logger.warn(
+      `Stream "${this.names.streamName(kind)}" (kind=${String(kind)}) does not report allow_msg_schedules=true, but scheduling is enabled in the application options. Scheduled publishes will be rejected by the server until the stream allows message schedules.`
+    );
+  }
+  warnOnRetention(info, kind) {
+    if (info.config.retention !== RetentionPolicy3.Workqueue) {
+      this.logger.warn(
+        `Stream "${this.names.streamName(kind)}" (kind=${String(kind)}) retention is "${String(info.config.retention)}"; expected "workqueue" for reliable at-least-once delivery.`
+      );
+    }
+  }
+  warnOnUnlimitedDelivery(info, kind) {
+    if (!this.options.dlq) return;
+    const maxDeliver = info.config.max_deliver;
+    if (maxDeliver === void 0 || maxDeliver <= 0) {
+      this.logger.warn(
+        `Consumer "${this.names.consumerName(kind)}" (kind=${String(kind)}) has unlimited max_deliver but options.dlq is enabled; messages will never be dead-lettered. Set max_deliver > 0 on the consumer.`
+      );
+    }
+  }
+  warnOnShortAckWait(info, kind) {
+    const ackExtConfig = resolveAckExtension(this.options, kind);
+    if (ackExtConfig === void 0 || ackExtConfig === false) return;
+    const ackWaitNanos = info.config.ack_wait;
+    const intervalMs = resolveAckExtensionInterval(ackExtConfig, ackWaitNanos);
+    if (intervalMs === null) return;
+    const ackWaitMs = ackWaitNanos !== void 0 ? ackWaitNanos / 1e6 : void 0;
+    if (ackWaitMs !== void 0 && ackWaitMs < intervalMs) {
+      this.logger.warn(
+        `Consumer "${this.names.consumerName(kind)}" (kind=${String(kind)}) ack_wait (${ackWaitMs}ms) is shorter than the ackExtension interval (${intervalMs}ms). Messages may redeliver before the handler finishes. Increase ack_wait.`
+      );
+    }
+  }
+  resolveHandlerSubjects(kind) {
+    const patterns = this.registry.getPatternsByKind();
+    switch (kind) {
+      case "ev" /* Event */:
+        return patterns.events.map((p) => this.names.subject("ev" /* Event */, p));
+      case "cmd" /* Command */:
+        return patterns.commands.map((p) => this.names.subject("cmd" /* Command */, p));
+      case "broadcast" /* Broadcast */:
+        return this.registry.getBroadcastPatterns();
+      case "ordered" /* Ordered */:
+        return this.registry.getOrderedSubjects();
+      /* v8 ignore next 5 -- exhaustive switch guard, unreachable */
+      default: {
+        const _exhaustive = kind;
+        throw new Error(`Unhandled StreamKind: ${String(_exhaustive)}`);
+      }
+    }
+  }
+};
+
 // src/shutdown/shutdown.manager.ts
-import { Logger as Logger19 } from "@nestjs/common";
+import { Logger as Logger22 } from "@nestjs/common";
 var ShutdownManager = class {
   constructor(connection, eventBus, timeout) {
     this.connection = connection;
     this.eventBus = eventBus;
     this.timeout = timeout;
   }
-  logger = new Logger19("Jetstream:Shutdown");
+  logger = new Logger22("Jetstream:Shutdown");
   shutdownPromise;
   /**
    * Execute the full shutdown sequence.
    *
-   * Idempotent — concurrent or repeated calls return the same promise.
+   * Idempotent: concurrent or repeated calls return the same promise.
    *
    * @param strategy Optional stoppable to close (stops consumers and subscriptions).
    */
@@ -5819,6 +6254,12 @@ var ShutdownManager = class {
 
 // src/jetstream.module.ts
 var JETSTREAM_ACK_WAIT_MAP = /* @__PURE__ */ Symbol("JETSTREAM_ACK_WAIT_MAP");
+var DESTRUCTIVE_MIGRATION_MANUAL_WARNING = "allowDestructiveMigration has no effect under provisioning.management: Manual; the library never migrates externally managed streams.";
+var warnIfManualWithDestructive = (options, logger5) => {
+  if (options.allowDestructiveMigration && options.provisioning?.management === "manual" /* Manual */) {
+    logger5.warn(DESTRUCTIVE_MIGRATION_MANUAL_WARNING);
+  }
+};
 var JetstreamModule = class {
   constructor(shutdownManager, strategy) {
     this.shutdownManager = shutdownManager;
@@ -5848,7 +6289,8 @@ var JetstreamModule = class {
         PatternRegistry,
         ShutdownManager,
         JetstreamStrategy,
-        JetstreamHealthIndicator
+        JetstreamHealthIndicator,
+        NameResolver
       ]
     };
   }
@@ -5877,7 +6319,8 @@ var JetstreamModule = class {
         PatternRegistry,
         ShutdownManager,
         JetstreamStrategy,
-        JetstreamHealthIndicator
+        JetstreamHealthIndicator,
+        NameResolver
       ]
     };
   }
@@ -5894,10 +6337,23 @@ var JetstreamModule = class {
     const clientToken = getClientToken(options.name);
     const clientProvider = {
       provide: clientToken,
-      inject: [JETSTREAM_OPTIONS, JETSTREAM_CONNECTION, JETSTREAM_CODEC, JETSTREAM_EVENT_BUS],
-      useFactory: (rootOptions, connection, rootCodec, eventBus) => {
+      inject: [
+        JETSTREAM_OPTIONS,
+        JETSTREAM_CONNECTION,
+        JETSTREAM_CODEC,
+        JETSTREAM_EVENT_BUS,
+        { token: NameResolver, optional: true }
+      ],
+      useFactory: (rootOptions, connection, rootCodec, eventBus, names) => {
         const codec = options.codec ?? rootCodec;
-        return new JetstreamClient(rootOptions, options.name, connection, codec, eventBus);
+        return new JetstreamClient(
+          rootOptions,
+          options.name,
+          connection,
+          codec,
+          eventBus,
+          names ?? void 0
+        );
       }
     };
     return {
@@ -5918,16 +6374,14 @@ var JetstreamModule = class {
   /** Create providers that depend on JETSTREAM_OPTIONS (shared by sync and async). */
   static createCoreDependentProviders() {
     return [
-      // EventBus — hook system with Logger fallback
       {
         provide: JETSTREAM_EVENT_BUS,
         inject: [JETSTREAM_OPTIONS],
         useFactory: (options) => {
-          const logger5 = new Logger20("Jetstream:Module");
+          const logger5 = new Logger23("Jetstream:Module");
           return new EventBus(logger5, options.hooks);
         }
       },
-      // Codec — global encode/decode
       {
         provide: JETSTREAM_CODEC,
         inject: [JETSTREAM_OPTIONS],
@@ -5935,7 +6389,6 @@ var JetstreamModule = class {
           return options.codec ?? new JsonCodec();
         }
       },
-      // ConnectionProvider — single NATS connection
       {
         provide: JETSTREAM_CONNECTION,
         inject: [JETSTREAM_OPTIONS, JETSTREAM_EVENT_BUS],
@@ -5943,7 +6396,6 @@ var JetstreamModule = class {
           return new ConnectionProvider(options, eventBus);
         }
       },
-      // JetstreamHealthIndicator — health check for NATS connection
       {
         provide: JetstreamHealthIndicator,
         inject: [JETSTREAM_CONNECTION],
@@ -5951,7 +6403,6 @@ var JetstreamModule = class {
           return new JetstreamHealthIndicator(connection);
         }
       },
-      // ShutdownManager — graceful shutdown orchestration
       {
         provide: ShutdownManager,
         inject: [JETSTREAM_CONNECTION, JETSTREAM_EVENT_BUS, JETSTREAM_OPTIONS],
@@ -5963,41 +6414,69 @@ var JetstreamModule = class {
           );
         }
       },
-      // Consumer infrastructure — only created when consumer !== false.
-      // Providers return null when consumer is disabled (publisher-only mode).
-      // PatternRegistry — subject-to-handler mapping
+      // Consumer infrastructure providers below return null when consumer === false
+      // (publisher-only mode). NameResolver is the exception: clients need it too.
       {
-        provide: PatternRegistry,
+        provide: NameResolver,
         inject: [JETSTREAM_OPTIONS],
         useFactory: (options) => {
+          const logger5 = new Logger23("Jetstream:Module");
+          warnIfManualWithDestructive(options, logger5);
+          return new NameResolver(options);
+        }
+      },
+      {
+        provide: PatternRegistry,
+        inject: [JETSTREAM_OPTIONS, NameResolver],
+        useFactory: (options, names) => {
+          if (options.consumer === false) return null;
+          return new PatternRegistry(options, names);
+        }
+      },
+      {
+        provide: InfrastructureBinder,
+        inject: [JETSTREAM_OPTIONS, NameResolver, PatternRegistry],
+        useFactory: (options, names, registry) => {
           if (options.consumer === false) return null;
-          return new PatternRegistry(options);
+          return new InfrastructureBinder(options, names, registry);
         }
       },
-      // StreamProvider — JetStream stream lifecycle
       {
         provide: StreamProvider,
-        inject: [JETSTREAM_OPTIONS, JETSTREAM_CONNECTION],
-        useFactory: (options, connection) => {
+        inject: [JETSTREAM_OPTIONS, JETSTREAM_CONNECTION, NameResolver, InfrastructureBinder],
+        useFactory: (options, connection, names, binder) => {
           if (options.consumer === false) return null;
-          return new StreamProvider(options, connection);
+          return new StreamProvider(options, connection, names, binder);
         }
       },
-      // ConsumerProvider — JetStream consumer lifecycle (receives PatternRegistry for broadcast filtering)
+      // ConsumerProvider needs PatternRegistry for broadcast filtering.
       {
         provide: ConsumerProvider,
-        inject: [JETSTREAM_OPTIONS, JETSTREAM_CONNECTION, StreamProvider, PatternRegistry],
-        useFactory: (options, connection, streamProvider, patternRegistry) => {
+        inject: [
+          JETSTREAM_OPTIONS,
+          JETSTREAM_CONNECTION,
+          StreamProvider,
+          PatternRegistry,
+          NameResolver,
+          InfrastructureBinder
+        ],
+        useFactory: (options, connection, streamProvider, patternRegistry, names, binder) => {
           if (options.consumer === false) return null;
-          return new ConsumerProvider(options, connection, streamProvider, patternRegistry);
+          return new ConsumerProvider(
+            options,
+            connection,
+            streamProvider,
+            patternRegistry,
+            names,
+            binder
+          );
         }
       },
-      // Shared ack_wait map — populated by strategy after ensureConsumers()
+      // Shared ack_wait map, populated by the strategy after ensureConsumers().
       {
         provide: JETSTREAM_ACK_WAIT_MAP,
         useFactory: () => /* @__PURE__ */ new Map()
       },
-      // MessageProvider — pull-based message consumption
       {
         provide: MessageProvider,
         inject: [
@@ -6036,7 +6515,6 @@ var JetstreamModule = class {
           return new MessageProvider(connection, eventBus, consumeOptionsMap, consumerRecoveryFn);
         }
       },
-      // EventRouter — routes event and broadcast messages to handlers
       {
         provide: EventRouter,
         inject: [
@@ -6046,9 +6524,10 @@ var JetstreamModule = class {
           JETSTREAM_CODEC,
           JETSTREAM_EVENT_BUS,
           JETSTREAM_ACK_WAIT_MAP,
-          JETSTREAM_CONNECTION
+          JETSTREAM_CONNECTION,
+          NameResolver
         ],
-        useFactory: (options, messageProvider, patternRegistry, codec, eventBus, ackWaitMap, connection) => {
+        useFactory: (options, messageProvider, patternRegistry, codec, eventBus, ackWaitMap, connection, names) => {
           if (options.consumer === false) return null;
           const deadLetterConfig = options.onDeadLetter || options.dlq ? {
             maxDeliverByStream: /* @__PURE__ */ new Map(),
@@ -6073,11 +6552,11 @@ var JetstreamModule = class {
             processingConfig,
             ackWaitMap,
             connection,
-            options
+            options,
+            names
           );
         }
       },
-      // RpcRouter — routes RPC command messages in JetStream mode
       {
         provide: RpcRouter,
         inject: [
@@ -6108,7 +6587,6 @@ var JetstreamModule = class {
           );
         }
       },
-      // CoreRpcServer — RPC via NATS Core request/reply
       {
         provide: CoreRpcServer,
         inject: [
@@ -6116,14 +6594,14 @@ var JetstreamModule = class {
           JETSTREAM_CONNECTION,
           PatternRegistry,
           JETSTREAM_CODEC,
-          JETSTREAM_EVENT_BUS
+          JETSTREAM_EVENT_BUS,
+          NameResolver
         ],
-        useFactory: (options, connection, patternRegistry, codec, eventBus) => {
+        useFactory: (options, connection, patternRegistry, codec, eventBus, names) => {
           if (options.consumer === false) return null;
-          return new CoreRpcServer(options, connection, patternRegistry, codec, eventBus);
+          return new CoreRpcServer(options, connection, patternRegistry, codec, eventBus, names);
         }
       },
-      // MetadataProvider — handler metadata KV registry (decoupled from stream/consumer infra)
       {
         provide: MetadataProvider,
         inject: [JETSTREAM_OPTIONS, JETSTREAM_CONNECTION],
@@ -6132,7 +6610,6 @@ var JetstreamModule = class {
           return new MetadataProvider(options, connection);
         }
       },
-      // JetstreamStrategy — server-side transport (only when consumer enabled)
       {
         provide: JetstreamStrategy,
         inject: [
@@ -6257,6 +6734,7 @@ export {
   JetstreamTrace,
   JsonCodec,
   MIN_METADATA_TTL,
+  ManagementMode,
   MessageKind,
   MsgpackCodec,
   NatsErrorCode,