@horizon-republic/nestjs-jetstream 2.10.0 → 2.11.0

package/dist/index.js

@@ -13,10 +13,10 @@ var __decorateParam = (index, decorator) => (target, key) => decorator(target, k
 // src/jetstream.module.ts
 import {
   Global,
-  Inject,
-  Logger as Logger18,
-  Module,
-  Optional
+  Inject as Inject2,
+  Logger as Logger20,
+  Module as Module2,
+  Optional as Optional2
 } from "@nestjs/common";
 
 // src/client/jetstream.client.ts
@@ -46,6 +46,10 @@ var TransportEvent = /* @__PURE__ */ ((TransportEvent2) => {
   TransportEvent2["ShutdownStart"] = "shutdownStart";
   TransportEvent2["ShutdownComplete"] = "shutdownComplete";
   TransportEvent2["DeadLetter"] = "deadLetter";
+  TransportEvent2["ConsumerRecovered"] = "consumerRecovered";
+  TransportEvent2["HandlerCompleted"] = "handlerCompleted";
+  TransportEvent2["Published"] = "published";
+  TransportEvent2["RpcCompleted"] = "rpcCompleted";
   return TransportEvent2;
 })(TransportEvent || {});
 
@@ -523,7 +527,7 @@ var extractContext = (ctx, carrier, getter) => propagation.extract(ctx, carrier,
 
 // src/otel/tracer.ts
 import { trace } from "@opentelemetry/api";
-var PACKAGE_VERSION = true ? "2.10.0" : "0.0.0";
+var PACKAGE_VERSION = true ? "2.11.0" : "0.0.0";
 var getTracer = () => trace.getTracer(TRACER_NAME, PACKAGE_VERSION);
 
 // src/otel/carrier.ts
@@ -1325,6 +1329,17 @@ var detectEventKind = (pattern) => {
   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);
+  return pattern;
+};
+var eventStreamKind = (kind) => {
+  if (kind === "broadcast" /* Broadcast */) return "broadcast" /* Broadcast */;
+  if (kind === "ordered" /* Ordered */) return "ordered" /* Ordered */;
+  return "ev" /* Event */;
+};
 var JetstreamClient = class extends ClientProxy {
   constructor(rootOptions, targetServiceName, connection, codec, eventBus) {
     super();
@@ -1440,50 +1455,60 @@ 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());
-    await withPublishSpan(
-      {
-        subject: publishSubject,
-        pattern: packet.pattern,
-        record,
-        kind: detectEventKind(packet.pattern),
-        payloadBytes: encoded.length,
-        payload: encoded,
-        messageId: effectiveMsgId,
-        headers: msgHeaders,
-        serviceName: this.callerName,
-        endpoint: this.serverEndpoint,
-        scheduleTarget: schedule ? eventSubject : void 0
-      },
-      this.otel,
-      async () => {
-        const warnIfDuplicate = (kindLabel, ack2) => {
-          if (ack2.duplicate) {
-            this.logger.warn(
-              `Duplicate ${kindLabel} publish detected: ${publishSubject} (seq: ${ack2.seq})`
-            );
+    const publishKind = detectEventKind(packet.pattern);
+    const declaredPattern = declaredEventPattern(packet.pattern);
+    const streamKind = eventStreamKind(publishKind);
+    const startedAt = performance.now();
+    try {
+      await withPublishSpan(
+        {
+          subject: publishSubject,
+          pattern: packet.pattern,
+          record,
+          kind: publishKind,
+          payloadBytes: encoded.length,
+          payload: encoded,
+          messageId: effectiveMsgId,
+          headers: msgHeaders,
+          serviceName: this.callerName,
+          endpoint: this.serverEndpoint,
+          scheduleTarget: schedule ? eventSubject : void 0
+        },
+        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,
+              msgID: effectiveMsgId,
+              ttl,
+              schedule: {
+                specification: schedule.at,
+                target: eventSubject
+              }
+            });
+            warnIfDuplicate("scheduled", ack2);
+            return;
           }
-        };
-        if (schedule) {
-          const ack2 = await this.connection.getJetStreamClient().publish(publishSubject, encoded, {
+          const ack = await this.connection.getJetStreamClient().publish(publishSubject, encoded, {
             headers: msgHeaders,
             msgID: effectiveMsgId,
-            ttl,
-            schedule: {
-              specification: schedule.at,
-              target: eventSubject
-            }
+            ttl
           });
-          warnIfDuplicate("scheduled", ack2);
-          return;
+          warnIfDuplicate("event", ack);
         }
-        const ack = await this.connection.getJetStreamClient().publish(publishSubject, encoded, {
-          headers: msgHeaders,
-          msgID: effectiveMsgId,
-          ttl
-        });
-        warnIfDuplicate("event", ack);
-      }
-    );
+      );
+      this.reportPublished(declaredPattern, streamKind, startedAt, "success");
+    } catch (err) {
+      this.reportPublished(declaredPattern, streamKind, startedAt, "error");
+      throw err;
+    }
     return void 0;
   }
   /**
@@ -1511,14 +1536,17 @@ var JetstreamClient = class extends ClientProxy {
     };
     let jetStreamCorrelationId = null;
     if (this.isCoreMode) {
-      this.publishCoreRpc(subject, data, hdrs, timeout, callback).catch(onUnhandled);
+      this.publishCoreRpc(subject, data, hdrs, timeout, callback, packet.pattern).catch(
+        onUnhandled
+      );
     } else {
       jetStreamCorrelationId = nuid.next();
       this.publishJetStreamRpc(subject, data, callback, {
         headers: hdrs,
         timeout,
         correlationId: jetStreamCorrelationId,
-        messageId
+        messageId,
+        declaredPattern: packet.pattern
       }).catch(onUnhandled);
     }
     return () => {
@@ -1533,7 +1561,7 @@ var JetstreamClient = class extends ClientProxy {
     };
   }
   /** Core mode: nc.request() with timeout. */
-  async publishCoreRpc(subject, data, customHeaders, timeout, callback) {
+  async publishCoreRpc(subject, data, customHeaders, timeout, callback, declaredPattern) {
     const effectiveTimeout = timeout ?? this.defaultRpcTimeout;
     const hdrs = this.buildHeaders(customHeaders, { subject });
     const encoded = this.codec.encode(data);
@@ -1548,6 +1576,7 @@ var JetstreamClient = class extends ClientProxy {
       },
       this.otel
     );
+    const startedAt = performance.now();
     try {
       const nc = this.readyForPublish ? this.connection.unwrap : await this.connect();
       const response = await context6.with(
@@ -1560,9 +1589,13 @@ var JetstreamClient = class extends ClientProxy {
       const decoded = this.codec.decode(response.data);
       if (response.headers?.get("x-error" /* Error */)) {
         spanHandle.finish({ kind: "reply-error" /* ReplyError */, replyPayload: decoded });
+        this.reportPublished(declaredPattern, "cmd" /* Command */, startedAt, "success");
+        this.reportRpcCompleted(declaredPattern, startedAt, "error");
         callback({ err: decoded, response: null, isDisposed: true });
       } else {
         spanHandle.finish({ kind: "ok" /* Ok */, reply: decoded });
+        this.reportPublished(declaredPattern, "cmd" /* Command */, startedAt, "success");
+        this.reportRpcCompleted(declaredPattern, startedAt, "success");
         callback({ err: null, response: decoded, isDisposed: true });
       }
     } catch (err) {
@@ -1570,16 +1603,20 @@ var JetstreamClient = class extends ClientProxy {
       if (error instanceof TimeoutError) {
         spanHandle.finish({ kind: "timeout" /* Timeout */ });
         this.eventBus.emit("rpcTimeout" /* RpcTimeout */, subject, "");
+        this.reportPublished(declaredPattern, "cmd" /* Command */, startedAt, "success");
+        this.reportRpcCompleted(declaredPattern, startedAt, "timeout");
       } else {
         spanHandle.finish({ kind: "error" /* Error */, error });
         this.eventBus.emit("error" /* Error */, error, "client-rpc");
+        this.reportPublished(declaredPattern, "cmd" /* Command */, startedAt, "error");
+        this.reportRpcCompleted(declaredPattern, startedAt, "error");
       }
       callback({ err: error, response: null, isDisposed: true });
     }
   }
   /** JetStream mode: publish to stream + wait for inbox response. */
   async publishJetStreamRpc(subject, data, callback, options) {
-    const { headers: customHeaders, correlationId, messageId } = options;
+    const { headers: customHeaders, correlationId, messageId, declaredPattern } = options;
     const effectiveTimeout = options.timeout ?? this.defaultRpcTimeout;
     const hdrs = this.buildHeaders(customHeaders, {
       subject,
@@ -1600,6 +1637,7 @@ var JetstreamClient = class extends ClientProxy {
       },
       this.otel
     );
+    const startedAt = performance.now();
     this.pendingMessages.set(correlationId, (packet) => {
       if (packet.err) {
         if (packet.err instanceof Error) {
@@ -1607,8 +1645,10 @@ var JetstreamClient = class extends ClientProxy {
         } else {
           spanHandle.finish({ kind: "reply-error" /* ReplyError */, replyPayload: packet.err });
         }
+        this.reportRpcCompleted(declaredPattern, startedAt, "error");
       } else {
         spanHandle.finish({ kind: "ok" /* Ok */, reply: packet.response });
+        this.reportRpcCompleted(declaredPattern, startedAt, "success");
       }
       callback(packet);
     });
@@ -1618,6 +1658,7 @@ var JetstreamClient = class extends ClientProxy {
       this.pendingMessages.delete(correlationId);
       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);
@@ -1630,6 +1671,8 @@ var JetstreamClient = class extends ClientProxy {
         this.pendingMessages.delete(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"),
           response: null,
@@ -1644,6 +1687,7 @@ var JetstreamClient = class extends ClientProxy {
           msgID: messageId ?? nuid.next()
         })
       );
+      this.reportPublished(declaredPattern, "cmd" /* Command */, startedAt, "success");
     } catch (err) {
       const existingTimeout = this.pendingTimeouts.get(correlationId);
       if (existingTimeout) {
@@ -1655,9 +1699,32 @@ var JetstreamClient = class extends ClientProxy {
       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}`);
+      this.reportPublished(declaredPattern, "cmd" /* Command */, startedAt, "error");
+      this.reportRpcCompleted(declaredPattern, startedAt, "error");
       callback({ err: error, response: null, isDisposed: true });
     }
   }
+  // hasHook is per-emit so late subscribers (JetstreamMetricsService during
+  // OnApplicationBootstrap) still receive events.
+  reportPublished(declaredPattern, kind, startedAt, status) {
+    if (!this.eventBus.hasHook("published" /* Published */)) return;
+    this.eventBus.emit(
+      "published" /* Published */,
+      declaredPattern,
+      kind,
+      performance.now() - startedAt,
+      status
+    );
+  }
+  reportRpcCompleted(declaredPattern, startedAt, status) {
+    if (!this.eventBus.hasHook("rpcCompleted" /* RpcCompleted */)) return;
+    this.eventBus.emit(
+      "rpcCompleted" /* RpcCompleted */,
+      declaredPattern,
+      performance.now() - startedAt,
+      status
+    );
+  }
   /** Fail-fast all pending JetStream RPC callbacks on connection loss. */
   handleDisconnect() {
     this.rejectPendingRpcs(new Error("Connection lost"));
@@ -2068,43 +2135,53 @@ var ConnectionProvider = class {
 var EventBus = class {
   hooks;
   logger;
+  subscribers = /* @__PURE__ */ new Map();
   constructor(logger5, hooks) {
     this.logger = logger5;
     this.hooks = hooks ?? {};
   }
   /**
-   * Emit a lifecycle event. Dispatches to custom hook if registered, otherwise no-op.
-   *
-   * @param event - The {@link TransportEvent} to emit.
-   * @param args - Arguments matching the hook signature for this event.
+   * Subscribe to a transport event. Used by built-in observers (e.g. metrics).
+   * Multiple subscribers per event are supported; each is called independently.
+   */
+  subscribe(event, handler) {
+    const list = this.subscribers.get(event) ?? [];
+    list.push(handler);
+    this.subscribers.set(event, list);
+  }
+  /**
+   * Emit a lifecycle event. Dispatches to all internal subscribers and the
+   * registered user hook (if any).
    */
   emit(event, ...args) {
-    const hook = this.hooks[event];
-    if (!hook) return;
-    this.callHook(event, hook, ...args);
+    this.dispatch(event, args);
   }
   /**
    * Hot-path optimized emit for MessageRouted events.
    * Avoids rest/spread overhead of the generic `emit()`.
    */
   emitMessageRouted(subject, kind) {
-    const hook = this.hooks["messageRouted" /* MessageRouted */];
-    if (!hook) return;
-    this.callHook(
-      "messageRouted" /* MessageRouted */,
-      hook,
-      subject,
-      kind
-    );
+    this.dispatch("messageRouted" /* MessageRouted */, [subject, kind]);
   }
   /**
-   * Check whether a hook is registered for the given event.
-   *
-   * Used by the routing hot path to elide the emit call entirely when the
-   * transport owner did not register a listener.
+   * Check whether any listener (user hook or internal subscriber) is registered
+   * for the given event. Used by routing hot path to elide the emit call when
+   * no one is listening.
    */
   hasHook(event) {
-    return this.hooks[event] !== void 0;
+    return this.hooks[event] !== void 0 || (this.subscribers.get(event)?.length ?? 0) > 0;
+  }
+  dispatch(event, args) {
+    const subs = this.subscribers.get(event);
+    if (subs?.length) {
+      for (const sub of [...subs]) {
+        this.callHook(event, sub, ...args);
+      }
+    }
+    const hook = this.hooks[event];
+    if (hook) {
+      this.callHook(event, hook, ...args);
+    }
   }
   callHook(event, hook, ...args) {
     try {
@@ -2183,12 +2260,695 @@ var JetstreamHealthIndicator = class {
         isHealthCheckError: true
       });
     }
-    return { [key]: details };
+    return { [key]: details };
+  }
+};
+JetstreamHealthIndicator = __decorateClass([
+  Injectable()
+], JetstreamHealthIndicator);
+
+// src/metrics/metrics.module.ts
+import { Module } from "@nestjs/common";
+
+// src/server/routing/pattern-registry.ts
+import { Logger as Logger8 } from "@nestjs/common";
+var HANDLER_LABELS = {
+  ["broadcast" /* Broadcast */]: "broadcast" /* Broadcast */,
+  ["ordered" /* Ordered */]: "ordered" /* Ordered */,
+  ["ev" /* Event */]: "event" /* Event */,
+  ["cmd" /* Command */]: "rpc" /* Rpc */
+};
+var PatternRegistry = class {
+  constructor(options) {
+    this.options = options;
+  }
+  logger = new Logger8("Jetstream:PatternRegistry");
+  registry = /* @__PURE__ */ new Map();
+  // Cached after registerHandlers() — the registry is immutable from that point
+  cachedPatterns = null;
+  _hasEvents = false;
+  _hasCommands = false;
+  _hasBroadcasts = false;
+  _hasOrdered = false;
+  _hasMetadata = false;
+  /**
+   * Register all handlers from the NestJS strategy.
+   *
+   * @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;
+      const isBroadcast = !!extras?.broadcast;
+      const isOrdered = !!extras?.ordered;
+      const meta = extras?.meta;
+      if (isBroadcast && isOrdered) {
+        throw new Error(
+          `Handler "${pattern}" cannot be both broadcast and ordered. Use one or the other.`
+        );
+      }
+      let kind;
+      if (isBroadcast) kind = "broadcast" /* Broadcast */;
+      else if (isOrdered) kind = "ordered" /* Ordered */;
+      else if (isEvent) kind = "ev" /* Event */;
+      else kind = "cmd" /* Command */;
+      const fullSubject = kind === "broadcast" /* Broadcast */ ? buildBroadcastSubject(pattern) : buildSubject(serviceName, kind, pattern);
+      this.registry.set(fullSubject, {
+        handler,
+        pattern,
+        isEvent: isEvent && !isOrdered,
+        isBroadcast,
+        isOrdered,
+        meta
+      });
+      this.logger.debug(`Registered ${HANDLER_LABELS[kind]}: ${pattern} -> ${fullSubject}`);
+    }
+    this.cachedPatterns = this.buildPatternsByKind();
+    this._hasEvents = this.cachedPatterns.events.length > 0;
+    this._hasCommands = this.cachedPatterns.commands.length > 0;
+    this._hasBroadcasts = this.cachedPatterns.broadcasts.length > 0;
+    this._hasOrdered = this.cachedPatterns.ordered.length > 0;
+    this._hasMetadata = [...this.registry.values()].some((entry) => entry.meta !== void 0);
+    this.logSummary();
+  }
+  /** Find handler for a full NATS subject. */
+  getHandler(subject) {
+    return this.registry.get(subject)?.handler ?? null;
+  }
+  /**
+   * 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
+   * bounded, suitable for use as a Prometheus label without cardinality risk.
+   */
+  resolveDeclared(subject) {
+    const entry = this.registry.get(subject);
+    if (!entry) return null;
+    return { pattern: entry.pattern, kind: this.resolveStreamKind(entry) };
+  }
+  /** Get all registered broadcast patterns (for consumer filter_subject setup). */
+  getBroadcastPatterns() {
+    return this.getPatternsByKind().broadcasts.map((p) => buildBroadcastSubject(p));
+  }
+  hasBroadcastHandlers() {
+    return this._hasBroadcasts;
+  }
+  hasRpcHandlers() {
+    return this._hasCommands;
+  }
+  hasEventHandlers() {
+    return this._hasEvents;
+  }
+  hasOrderedHandlers() {
+    return this._hasOrdered;
+  }
+  /** Get fully-qualified NATS subjects for ordered handlers. */
+  getOrderedSubjects() {
+    return this.getPatternsByKind().ordered.map(
+      (p) => buildSubject(this.options.name, "ordered" /* Ordered */, p)
+    );
+  }
+  /** Check if any registered handler has metadata. */
+  hasMetadata() {
+    return this._hasMetadata;
+  }
+  /**
+   * Get handler metadata entries for KV publishing.
+   *
+   * Returns a map of KV key -> metadata object for all handlers that have `meta`.
+   * Key format: `{serviceName}.{kind}.{pattern}`.
+   */
+  getMetadataEntries() {
+    const entries = /* @__PURE__ */ new Map();
+    for (const entry of this.registry.values()) {
+      if (!entry.meta) continue;
+      const kind = this.resolveStreamKind(entry);
+      const key = metadataKey(this.options.name, kind, entry.pattern);
+      entries.set(key, entry.meta);
+    }
+    return entries;
+  }
+  /** Get patterns grouped by kind (cached after registration). */
+  getPatternsByKind() {
+    const patterns = this.cachedPatterns ?? this.buildPatternsByKind();
+    return {
+      events: [...patterns.events],
+      commands: [...patterns.commands],
+      broadcasts: [...patterns.broadcasts],
+      ordered: [...patterns.ordered]
+    };
+  }
+  /** Normalize a full NATS subject back to the user-facing pattern. */
+  normalizeSubject(subject) {
+    const name = internalName(this.options.name);
+    const prefixes = [
+      `${name}.${"cmd" /* Command */}.`,
+      `${name}.${"ev" /* Event */}.`,
+      `${name}.${"ordered" /* Ordered */}.`,
+      `${"broadcast" /* Broadcast */}.`
+    ];
+    for (const prefix of prefixes) {
+      if (subject.startsWith(prefix)) {
+        return subject.slice(prefix.length);
+      }
+    }
+    return subject;
+  }
+  buildPatternsByKind() {
+    const events = [];
+    const commands = [];
+    const broadcasts = [];
+    const ordered = [];
+    for (const entry of this.registry.values()) {
+      if (entry.isBroadcast) broadcasts.push(entry.pattern);
+      else if (entry.isOrdered) ordered.push(entry.pattern);
+      else if (entry.isEvent) events.push(entry.pattern);
+      else commands.push(entry.pattern);
+    }
+    return { events, commands, broadcasts, ordered };
+  }
+  resolveStreamKind(entry) {
+    if (entry.isBroadcast) return "broadcast" /* Broadcast */;
+    if (entry.isOrdered) return "ordered" /* Ordered */;
+    if (entry.isEvent) return "ev" /* Event */;
+    return "cmd" /* Command */;
+  }
+  logSummary() {
+    const { events, commands, broadcasts, ordered } = this.getPatternsByKind();
+    const parts = [
+      `${commands.length} RPC`,
+      `${events.length} events`,
+      `${broadcasts.length} broadcasts`
+    ];
+    if (ordered.length > 0) {
+      parts.push(`${ordered.length} ordered`);
+    }
+    this.logger.log(`Registered handlers: ${parts.join(", ")}`);
+  }
+};
+
+// src/metrics/metrics.constants.ts
+var JETSTREAM_METRICS_CONFIG = /* @__PURE__ */ Symbol("JETSTREAM_METRICS_CONFIG");
+var JETSTREAM_METRICS_REGISTRY = /* @__PURE__ */ Symbol("JETSTREAM_METRICS_REGISTRY");
+var JETSTREAM_METRICS_PROM_CLIENT = /* @__PURE__ */ Symbol("JETSTREAM_METRICS_PROM_CLIENT");
+var DEFAULT_METRICS_PREFIX = "jetstream_";
+var DEFAULT_POLL_INTERVAL_MS = 15e3;
+var DEFAULT_HISTOGRAM_BUCKETS = {
+  handlerDuration: [1e-3, 5e-3, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
+  publishDuration: [1e-3, 5e-3, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
+  rpcDuration: [1e-3, 5e-3, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]
+};
+var ERROR_CONTEXT_PREFIXES = [
+  ["connection", "connection"],
+  ["codec", "codec"],
+  ["client-rpc", "publish"],
+  ["jetstream-rpc-publish", "publish"],
+  ["publish", "publish"],
+  ["message-provider", "consume"],
+  ["consume", "consume"],
+  ["core-rpc-handler", "handler"],
+  ["rpc-handler", "handler"],
+  // 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"],
+  ["broadcast-handler", "handler"],
+  ["ordered-handler", "handler"],
+  ["handler", "handler"],
+  ["shutdown", "shutdown"]
+];
+var UNMATCHED_SUBJECT_LABEL = "<unmatched>";
+var STREAM_KIND_LABEL = {
+  ["ev" /* Event */]: "event",
+  ["cmd" /* Command */]: "command",
+  ["broadcast" /* Broadcast */]: "broadcast",
+  ["ordered" /* Ordered */]: "ordered"
+};
+
+// src/metrics/metrics.service.ts
+import {
+  Inject,
+  Injectable as Injectable2,
+  Logger as Logger10,
+  Optional
+} from "@nestjs/common";
+
+// src/metrics/error-context-mapper.ts
+var mapErrorContext = (context7) => {
+  if (!context7) return "other";
+  for (const [prefix, mapped] of ERROR_CONTEXT_PREFIXES) {
+    if (context7 === prefix || context7.startsWith(`${prefix}:`)) {
+      return mapped;
+    }
+  }
+  return "other";
+};
+
+// src/metrics/metrics.factory.ts
+var createMetrics = (opts) => {
+  const { register, promClient } = opts;
+  const prefix = opts.prefix ?? DEFAULT_METRICS_PREFIX;
+  const buckets = {
+    handlerDuration: opts.buckets?.handlerDuration ?? DEFAULT_HISTOGRAM_BUCKETS.handlerDuration,
+    publishDuration: opts.buckets?.publishDuration ?? DEFAULT_HISTOGRAM_BUCKETS.publishDuration,
+    rpcDuration: opts.buckets?.rpcDuration ?? DEFAULT_HISTOGRAM_BUCKETS.rpcDuration
+  };
+  if (opts.defaultLabels && Object.keys(opts.defaultLabels).length > 0) {
+    register.setDefaultLabels(opts.defaultLabels);
+  }
+  const counter = (name, help, labelNames) => new promClient.Counter({ name: `${prefix}${name}`, help, labelNames, registers: [register] });
+  const histogram = (name, help, labelNames, bucketArr) => new promClient.Histogram({
+    name: `${prefix}${name}`,
+    help,
+    labelNames,
+    buckets: bucketArr,
+    registers: [register]
+  });
+  const gauge = (name, help, labelNames) => new promClient.Gauge({ name: `${prefix}${name}`, help, labelNames, registers: [register] });
+  return {
+    messagesReceivedTotal: counter(
+      "messages_received_total",
+      "Total messages routed to a handler.",
+      ["stream", "subject", "kind"]
+    ),
+    messagesProcessedTotal: counter(
+      "messages_processed_total",
+      "Total messages whose handler completed.",
+      ["stream", "subject", "kind", "status"]
+    ),
+    messagesUnhandledTotal: counter(
+      "messages_unhandled_total",
+      "Messages received but not matching any registered handler.",
+      ["subject"]
+    ),
+    messagesDeadLetterTotal: counter(
+      "messages_dead_letter_total",
+      "Messages routed to dead-letter after exhausting redelivery attempts.",
+      ["stream", "subject"]
+    ),
+    publishTotal: counter(
+      "publish_total",
+      "Total publish/send operations performed by the client.",
+      ["subject", "kind", "status"]
+    ),
+    rpcTimeoutTotal: counter("rpc_timeout_total", "RPC calls that exceeded the timeout deadline.", [
+      "subject"
+    ]),
+    consumerRecoveredTotal: counter(
+      "consumer_recovered_total",
+      "Self-healing recoveries after consume-loop failures.",
+      ["kind"]
+    ),
+    errorsTotal: counter("errors_total", "Transport-level errors emitted on the EventBus.", [
+      "context"
+    ]),
+    handlerDurationSeconds: histogram(
+      "handler_duration_seconds",
+      "Wall-clock duration of handler execution.",
+      ["stream", "subject", "kind", "status"],
+      buckets.handlerDuration
+    ),
+    publishDurationSeconds: histogram(
+      "publish_duration_seconds",
+      "Wall-clock duration of client publish/send operations.",
+      ["subject", "kind", "status"],
+      buckets.publishDuration
+    ),
+    rpcDurationSeconds: histogram(
+      "rpc_duration_seconds",
+      "Wall-clock duration of RPC round-trips from client perspective.",
+      ["subject", "status"],
+      buckets.rpcDuration
+    ),
+    consumerNumPending: gauge(
+      "consumer_num_pending",
+      "Messages not yet delivered to this consumer.",
+      ["stream", "consumer", "kind"]
+    ),
+    consumerNumAckPending: gauge(
+      "consumer_num_ack_pending",
+      "Messages delivered but not yet acked.",
+      ["stream", "consumer", "kind"]
+    ),
+    consumerNumRedelivered: gauge(
+      "consumer_num_redelivered",
+      "Messages currently in redelivery state.",
+      ["stream", "consumer", "kind"]
+    ),
+    consumerNumWaiting: gauge(
+      "consumer_num_waiting",
+      "Pull-request waiting count for this consumer.",
+      ["stream", "consumer", "kind"]
+    ),
+    streamMessages: gauge("stream_messages", "Total messages stored in this stream.", ["stream"]),
+    streamBytes: gauge("stream_bytes", "Total bytes stored in this stream.", ["stream"]),
+    connectionUp: gauge("connection_up", "NATS connection state (1 connected, 0 disconnected).", [
+      "server"
+    ]),
+    metricsPollErrorsTotal: counter(
+      "metrics_poll_errors_total",
+      "Errors encountered while polling JetStreamManager for gauge data.",
+      ["target"]
+    )
+  };
+};
+
+// src/metrics/poll-runner.ts
+import { Logger as Logger9 } from "@nestjs/common";
+var PollRunner = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  logger = new Logger9("Jetstream:Metrics:Poll");
+  timer = null;
+  inFlight = null;
+  start() {
+    if (this.timer !== null) return;
+    if (this.opts.intervalMs <= 0) return;
+    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");
+        return;
+      }
+      this.inFlight = this.tick().finally(() => {
+        this.inFlight = null;
+      });
+    }, this.opts.intervalMs);
+  }
+  async stop() {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (this.inFlight !== null) await this.inFlight;
+  }
+  /** @internal Visible for tests. Runs one poll cycle. */
+  async tick() {
+    let jsm;
+    try {
+      jsm = await this.opts.jsmFactory();
+    } catch {
+      this.recordPollError("jsm.connect");
+      return;
+    }
+    await Promise.all([this.pollConsumers(jsm), this.pollStreams(jsm)]);
+  }
+  async pollConsumers(jsm) {
+    for (const target of this.opts.targets) {
+      try {
+        const info = await jsm.consumers.info(target.stream, target.consumer);
+        const labels = {
+          stream: target.stream,
+          consumer: target.consumer,
+          kind: STREAM_KIND_LABEL[target.kind]
+        };
+        this.opts.metrics.consumerNumPending.labels(labels).set(info.num_pending);
+        this.opts.metrics.consumerNumAckPending.labels(labels).set(info.num_ack_pending);
+        this.opts.metrics.consumerNumRedelivered.labels(labels).set(info.num_redelivered);
+        this.opts.metrics.consumerNumWaiting.labels(labels).set(info.num_waiting);
+      } catch {
+        this.recordPollError("consumer.info");
+      }
+    }
+  }
+  async pollStreams(jsm) {
+    const uniqueStreams = new Set(this.opts.targets.map((t) => t.stream));
+    for (const stream of uniqueStreams) {
+      try {
+        const info = await jsm.streams.info(stream);
+        this.opts.metrics.streamMessages.labels({ stream }).set(info.state.messages);
+        this.opts.metrics.streamBytes.labels({ stream }).set(info.state.bytes);
+      } catch {
+        this.recordPollError("stream.info");
+      }
+    }
+  }
+  recordPollError(target) {
+    this.opts.metrics.metricsPollErrorsTotal.labels({ target }).inc();
+  }
+};
+
+// src/metrics/metrics.service.ts
+var JetstreamMetricsService = class {
+  constructor(eventBus, config, promClient, options, patternRegistry, connection = null) {
+    this.eventBus = eventBus;
+    this.config = config;
+    this.promClient = promClient;
+    this.options = options;
+    this.patternRegistry = patternRegistry;
+    this.connection = connection;
+  }
+  logger = new Logger10("Jetstream:Metrics");
+  metrics = null;
+  pollRunner = null;
+  activeServers = /* @__PURE__ */ new Set();
+  async onApplicationBootstrap() {
+    if (this.metrics !== null) return;
+    if (!this.config.register) {
+      throw new Error(
+        "JetstreamMetricsService requires a prom-client Registry \u2014 none was resolved by JetstreamMetricsModule."
+      );
+    }
+    this.metrics = createMetrics({
+      register: this.config.register,
+      promClient: this.promClient,
+      prefix: this.config.prefix,
+      defaultLabels: this.config.defaultLabels,
+      buckets: this.config.buckets
+    });
+    this.subscribeToEvents();
+    this.syncInitialConnectionState();
+    this.startPolling();
+    this.logger.log(
+      `Metrics enabled (prefix=${this.config.prefix ?? DEFAULT_METRICS_PREFIX}, poll=${this.getEffectivePollInterval()}ms)`
+    );
+  }
+  async onModuleDestroy() {
+    await this.pollRunner?.stop();
+    this.pollRunner = null;
+  }
+  /** @internal Visible for tests. `0` disables polling. */
+  getEffectivePollInterval() {
+    return this.config.pollInterval ?? DEFAULT_POLL_INTERVAL_MS;
+  }
+  /**
+   * NATS connects during early bootstrap, before this service subscribes to
+   * the EventBus — 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.
+   */
+  syncInitialConnectionState() {
+    const nc = this.connection?.unwrap;
+    if (!nc) return;
+    const server = nc.getServer();
+    this.activeServers.add(server);
+    this.metrics?.connectionUp.labels({ server }).set(1);
+  }
+  /** Skips polling for publisher-only deployments and when no kinds are active. */
+  startPolling() {
+    const interval = this.getEffectivePollInterval();
+    const connection = this.connection;
+    if (interval <= 0 || !this.patternRegistry || !connection || !this.metrics) return;
+    const targets = this.buildPollTargets();
+    if (targets.length === 0) return;
+    this.pollRunner = new PollRunner({
+      intervalMs: interval,
+      jsmFactory: async () => connection.getJetStreamManager(),
+      metrics: this.metrics,
+      targets
+    });
+    this.pollRunner.start();
+  }
+  buildPollTargets() {
+    const registry = this.patternRegistry;
+    if (!registry) return [];
+    const targets = [];
+    if (registry.hasEventHandlers()) {
+      targets.push({
+        kind: "ev" /* Event */,
+        stream: streamName(this.options.name, "ev" /* Event */),
+        consumer: consumerName(this.options.name, "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 */)
+      });
+    }
+    if (registry.hasBroadcastHandlers()) {
+      targets.push({
+        kind: "broadcast" /* Broadcast */,
+        stream: streamName(this.options.name, "broadcast" /* Broadcast */),
+        consumer: consumerName(this.options.name, "broadcast" /* Broadcast */)
+      });
+    }
+    return targets;
+  }
+  subscribeToEvents() {
+    this.eventBus.subscribe("connect" /* Connect */, this.onConnect);
+    this.eventBus.subscribe("disconnect" /* Disconnect */, this.onDisconnect);
+    this.eventBus.subscribe("reconnect" /* Reconnect */, this.onReconnect);
+    this.eventBus.subscribe("error" /* Error */, this.onError);
+    this.eventBus.subscribe("rpcTimeout" /* RpcTimeout */, this.onRpcTimeout);
+    this.eventBus.subscribe("messageRouted" /* MessageRouted */, this.onMessageRouted);
+    this.eventBus.subscribe("deadLetter" /* DeadLetter */, this.onDeadLetter);
+    this.eventBus.subscribe("consumerRecovered" /* ConsumerRecovered */, this.onConsumerRecovered);
+    this.eventBus.subscribe("handlerCompleted" /* HandlerCompleted */, this.onHandlerCompleted);
+    this.eventBus.subscribe("published" /* Published */, this.onPublished);
+    this.eventBus.subscribe("rpcCompleted" /* RpcCompleted */, this.onRpcCompleted);
+  }
+  onConnect = (server) => {
+    this.activeServers.add(server);
+    this.metrics?.connectionUp.labels({ server }).set(1);
+  };
+  onReconnect = (server) => {
+    this.activeServers.add(server);
+    this.metrics?.connectionUp.labels({ server }).set(1);
+  };
+  onDisconnect = () => {
+    for (const server of this.activeServers) {
+      this.metrics?.connectionUp.labels({ server }).set(0);
+    }
+  };
+  onError = (_err, context7) => {
+    this.metrics?.errorsTotal.labels({ context: mapErrorContext(context7) }).inc();
+  };
+  onRpcTimeout = (subject, _correlationId) => {
+    const declared = this.resolveDeclared(subject);
+    const subjectLabel = declared?.pattern ?? UNMATCHED_SUBJECT_LABEL;
+    this.metrics?.rpcTimeoutTotal.labels({ subject: subjectLabel }).inc();
+  };
+  // `_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;
+    const declared = this.resolveDeclared(subject);
+    if (!declared) {
+      this.metrics.messagesUnhandledTotal.labels({ subject: UNMATCHED_SUBJECT_LABEL }).inc();
+      return;
+    }
+    this.metrics.messagesReceivedTotal.labels({
+      stream: streamName(this.options.name, declared.kind),
+      subject: declared.pattern,
+      kind: STREAM_KIND_LABEL[declared.kind]
+    }).inc();
+  };
+  onDeadLetter = (info) => {
+    const declared = this.resolveDeclared(info.subject);
+    const subjectLabel = declared?.pattern ?? UNMATCHED_SUBJECT_LABEL;
+    this.metrics?.messagesDeadLetterTotal.labels({ stream: info.stream, subject: subjectLabel }).inc();
+  };
+  onConsumerRecovered = (label, _attempts) => {
+    const kindLabel = STREAM_KIND_LABEL[label] ?? String(label);
+    this.metrics?.consumerRecoveredTotal.labels({ kind: kindLabel }).inc();
+  };
+  onHandlerCompleted = (pattern, kind, durationMs, status) => {
+    if (!this.metrics) return;
+    const stream = streamName(this.options.name, kind);
+    const kindLabel = STREAM_KIND_LABEL[kind];
+    const labels = { stream, subject: pattern, kind: kindLabel, status };
+    this.metrics.messagesProcessedTotal.labels(labels).inc();
+    this.metrics.handlerDurationSeconds.labels(labels).observe(durationMs / 1e3);
+  };
+  onPublished = (pattern, kind, durationMs, status) => {
+    if (!this.metrics) return;
+    const labels = { subject: pattern, kind: STREAM_KIND_LABEL[kind], status };
+    this.metrics.publishTotal.labels(labels).inc();
+    this.metrics.publishDurationSeconds.labels(labels).observe(durationMs / 1e3);
+  };
+  onRpcCompleted = (pattern, durationMs, status) => {
+    this.metrics?.rpcDurationSeconds.labels({ subject: pattern, status }).observe(durationMs / 1e3);
+  };
+  resolveDeclared(subject) {
+    return this.patternRegistry?.resolveDeclared(subject) ?? null;
   }
 };
-JetstreamHealthIndicator = __decorateClass([
-  Injectable()
-], JetstreamHealthIndicator);
+JetstreamMetricsService = __decorateClass([
+  Injectable2(),
+  __decorateParam(1, Inject(JETSTREAM_METRICS_CONFIG)),
+  __decorateParam(2, Inject(JETSTREAM_METRICS_PROM_CLIENT)),
+  __decorateParam(3, Inject(JETSTREAM_OPTIONS)),
+  __decorateParam(4, Optional()),
+  __decorateParam(5, Optional()),
+  __decorateParam(5, Inject(JETSTREAM_CONNECTION))
+], JetstreamMetricsService);
+
+// src/metrics/metrics.module.ts
+var PROM_CLIENT_INSTALL_MESSAGE = "prom-client is required when JetstreamModule.forRoot({ metrics: ... }) is enabled. Install it with: pnpm add prom-client";
+var resolvePromClient = async () => {
+  try {
+    return await import("prom-client");
+  } catch {
+    throw new Error(PROM_CLIENT_INSTALL_MESSAGE);
+  }
+};
+var normalizeMetricsConfig = (option, promClient) => {
+  const user = option && option !== true ? option : {};
+  return {
+    register: user.register ?? promClient.register,
+    prefix: user.prefix ?? DEFAULT_METRICS_PREFIX,
+    defaultLabels: user.defaultLabels,
+    pollInterval: user.pollInterval ?? DEFAULT_POLL_INTERVAL_MS,
+    buckets: user.buckets
+  };
+};
+var JetstreamMetricsModule = class {
+  static forFeature(metricsOption) {
+    if (!metricsOption) {
+      return { module: JetstreamMetricsModule, providers: [], exports: [] };
+    }
+    const promClientProvider = {
+      provide: JETSTREAM_METRICS_PROM_CLIENT,
+      useFactory: async () => {
+        const mod = await resolvePromClient();
+        return { Counter: mod.Counter, Histogram: mod.Histogram, Gauge: mod.Gauge };
+      }
+    };
+    const configProvider = {
+      provide: JETSTREAM_METRICS_CONFIG,
+      useFactory: async () => {
+        const mod = await resolvePromClient();
+        return normalizeMetricsConfig(metricsOption, mod);
+      }
+    };
+    const registryProvider = {
+      provide: JETSTREAM_METRICS_REGISTRY,
+      inject: [JETSTREAM_METRICS_CONFIG],
+      useFactory: (cfg) => cfg.register
+    };
+    const serviceProvider = {
+      provide: JetstreamMetricsService,
+      inject: [
+        JETSTREAM_EVENT_BUS,
+        JETSTREAM_METRICS_CONFIG,
+        JETSTREAM_METRICS_PROM_CLIENT,
+        JETSTREAM_OPTIONS,
+        { token: PatternRegistry, optional: true },
+        { token: JETSTREAM_CONNECTION, optional: true }
+      ],
+      useFactory: (eventBus, cfg, runtime, opts, patternRegistry, connection) => new JetstreamMetricsService(eventBus, cfg, runtime, opts, patternRegistry, connection)
+    };
+    return {
+      module: JetstreamMetricsModule,
+      providers: [promClientProvider, configProvider, registryProvider, serviceProvider],
+      exports: [
+        JetstreamMetricsService,
+        JETSTREAM_METRICS_CONFIG,
+        JETSTREAM_METRICS_REGISTRY,
+        JETSTREAM_METRICS_PROM_CLIENT
+      ]
+    };
+  }
+};
+JetstreamMetricsModule = __decorateClass([
+  Module({})
+], JetstreamMetricsModule);
 
 // src/server/strategy.ts
 import { Server } from "@nestjs/microservices";
@@ -2264,6 +3024,26 @@ var JetstreamStrategy = class extends Server {
     this.messageProvider.destroy();
     this.started = false;
   }
+  /**
+   * 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.
+   */
+  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.`
+      );
+    }
+    super.addHandler(pattern, callback, isEventHandler, extras);
+  }
   /**
    * Register event listener (required by Server base class).
    *
@@ -2336,7 +3116,7 @@ var JetstreamStrategy = class extends Server {
 };
 
 // src/server/core-rpc.server.ts
-import { Logger as Logger8 } from "@nestjs/common";
+import { Logger as Logger11 } from "@nestjs/common";
 import { headers as natsHeaders2 } from "@nats-io/transport-node";
 
 // src/context/rpc.context.ts
@@ -2605,7 +3385,7 @@ var CoreRpcServer = class {
     this.serviceName = derived.serviceName;
     this.serverEndpoint = derived.serverEndpoint;
   }
-  logger = new Logger8("Jetstream:CoreRpc");
+  logger = new Logger11("Jetstream:CoreRpc");
   subscription = null;
   otel;
   serviceName;
@@ -2658,6 +3438,7 @@ var CoreRpcServer = class {
       return;
     }
     const ctx = new RpcContext([msg]);
+    const startedAt = performance.now();
     try {
       const raw = await withConsumeSpan(
         {
@@ -2676,6 +3457,7 @@ var CoreRpcServer = class {
         }
       );
       msg.respond(this.codec.encode(raw));
+      this.reportHandlerCompleted(msg, startedAt, "success");
     } catch (err) {
       this.eventBus.emit(
         "error" /* Error */,
@@ -2683,7 +3465,23 @@ var CoreRpcServer = class {
         `core-rpc-handler:${msg.subject}`
       );
       this.respondWithError(msg, err);
-    }
+      this.reportHandlerCompleted(msg, startedAt, "error");
+    }
+  }
+  // See EventRouter.reportHandlerCompleted for the rationale on declared
+  // pattern + per-emit hasHook check.
+  reportHandlerCompleted(msg, startedAt, status) {
+    if (!this.eventBus.hasHook("handlerCompleted" /* HandlerCompleted */)) return;
+    const declared = this.patternRegistry.resolveDeclared(msg.subject);
+    const pattern = declared?.pattern ?? msg.subject;
+    const kind = declared?.kind ?? "cmd" /* Command */;
+    this.eventBus.emit(
+      "handlerCompleted" /* HandlerCompleted */,
+      pattern,
+      kind,
+      performance.now() - startedAt,
+      status
+    );
   }
   /** Send an error response back to the caller with x-error header. */
   respondWithError(msg, error) {
@@ -2698,7 +3496,7 @@ var CoreRpcServer = class {
 };
 
 // src/server/infrastructure/stream.provider.ts
-import { Logger as Logger10 } from "@nestjs/common";
+import { Logger as Logger13 } from "@nestjs/common";
 import { JetStreamApiError as JetStreamApiError2 } from "@nats-io/jetstream";
 
 // src/server/infrastructure/nats-error-codes.ts
@@ -2765,7 +3563,7 @@ var isEqual = (a, b) => {
 };
 
 // src/server/infrastructure/stream-migration.ts
-import { Logger as Logger9 } from "@nestjs/common";
+import { Logger as Logger12 } from "@nestjs/common";
 import { JetStreamApiError } from "@nats-io/jetstream";
 var MIGRATION_BACKUP_SUFFIX = "__migration_backup";
 var DEFAULT_SOURCING_TIMEOUT_MS = 3e4;
@@ -2774,7 +3572,7 @@ var StreamMigration = class {
   constructor(sourcingTimeoutMs = DEFAULT_SOURCING_TIMEOUT_MS) {
     this.sourcingTimeoutMs = sourcingTimeoutMs;
   }
-  logger = new Logger9("Jetstream:Stream");
+  logger = new Logger12("Jetstream:Stream");
   async migrate(jsm, streamName2, newConfig) {
     const backupName = `${streamName2}${MIGRATION_BACKUP_SUFFIX}`;
     const startTime = Date.now();
@@ -2861,7 +3659,7 @@ var StreamProvider = class {
     this.otelServiceName = derived.serviceName;
     this.otelEndpoint = derived.serverEndpoint;
   }
-  logger = new Logger10("Jetstream:Stream");
+  logger = new Logger13("Jetstream:Stream");
   migration = new StreamMigration();
   otel;
   otelServiceName;
@@ -3116,7 +3914,7 @@ var StreamProvider = class {
 };
 
 // src/server/infrastructure/consumer.provider.ts
-import { Logger as Logger11 } from "@nestjs/common";
+import { Logger as Logger14 } from "@nestjs/common";
 import { JetStreamApiError as JetStreamApiError3 } from "@nats-io/jetstream";
 var ConsumerProvider = class {
   constructor(options, connection, streamProvider, patternRegistry) {
@@ -3129,7 +3927,7 @@ var ConsumerProvider = class {
     this.otelServiceName = derived.serviceName;
     this.otelEndpoint = derived.serverEndpoint;
   }
-  logger = new Logger11("Jetstream:Consumer");
+  logger = new Logger14("Jetstream:Consumer");
   otel;
   otelServiceName;
   otelEndpoint;
@@ -3340,7 +4138,7 @@ var ConsumerProvider = class {
 };
 
 // src/server/infrastructure/message.provider.ts
-import { Logger as Logger12 } from "@nestjs/common";
+import { Logger as Logger15 } from "@nestjs/common";
 import { DeliverPolicy as DeliverPolicy2 } from "@nats-io/jetstream";
 import {
   catchError,
@@ -3350,7 +4148,6 @@ import {
   repeat,
   Subject,
   takeUntil,
-  tap,
   timer
 } from "rxjs";
 var MessageProvider = class {
@@ -3360,7 +4157,7 @@ var MessageProvider = class {
     this.consumeOptionsMap = consumeOptionsMap;
     this.consumerRecoveryFn = consumerRecoveryFn;
   }
-  logger = new Logger12("Jetstream:Message");
+  logger = new Logger15("Jetstream:Message");
   activeIterators = /* @__PURE__ */ new Set();
   orderedReadyResolve = null;
   orderedReadyReject = null;
@@ -3458,10 +4255,13 @@ var MessageProvider = class {
   /** Create a self-healing consumer flow for a specific kind. */
   createFlow(kind, info) {
     const target$ = this.getTargetSubject(kind);
-    return this.createSelfHealingFlow(() => this.consumeOnce(kind, info, target$), info.name);
+    return this.createSelfHealingFlow(
+      (onConnected) => this.consumeOnce(kind, info, target$, onConnected),
+      info.name
+    );
   }
   /** Single iteration: get consumer -> pull messages -> emit to subject. */
-  async consumeOnce(kind, info, target$) {
+  async consumeOnce(kind, info, target$, onConnected) {
     const js = this.connection.getJetStreamClient();
     let consumer;
     let consumerName2 = info.name;
@@ -3489,6 +4289,7 @@ var MessageProvider = class {
     });
     this.activeIterators.add(messages);
     this.monitorConsumerHealth(messages, consumerName2);
+    onConnected();
     try {
       await messages.closed();
     } finally {
@@ -3543,7 +4344,7 @@ var MessageProvider = class {
   /** Create a self-healing ordered consumer flow. */
   createOrderedFlow(streamName2, consumerOpts) {
     return this.createSelfHealingFlow(
-      () => this.consumeOrderedOnce(streamName2, consumerOpts),
+      (onConnected) => this.consumeOrderedOnce(streamName2, consumerOpts, onConnected),
       "ordered" /* Ordered */,
       (err) => {
         if (this.orderedReadyReject) {
@@ -3557,10 +4358,15 @@ var MessageProvider = class {
   /** Shared self-healing flow: defer -> retry with exponential backoff on error/completion. */
   createSelfHealingFlow(source, label, onFirstError) {
     let consecutiveFailures = 0;
-    return defer2(source).pipe(
-      tap(() => {
-        consecutiveFailures = 0;
-      }),
+    const onConnected = () => {
+      if (consecutiveFailures > 0) {
+        const attempts = consecutiveFailures;
+        this.logger.log(`Consumer ${label} recovered after ${attempts} failed attempt(s)`);
+        this.eventBus.emit("consumerRecovered" /* ConsumerRecovered */, label, attempts);
+      }
+      consecutiveFailures = 0;
+    };
+    return defer2(() => source(onConnected)).pipe(
       catchError((err) => {
         consecutiveFailures++;
         this.logger.error(`Consumer ${label} error, will restart:`, err);
@@ -3583,7 +4389,7 @@ var MessageProvider = class {
     );
   }
   /** Single iteration: create ordered consumer -> push messages into the subject. */
-  async consumeOrderedOnce(streamName2, consumerOpts) {
+  async consumeOrderedOnce(streamName2, consumerOpts, onConnected) {
     const js = this.connection.getJetStreamClient();
     const consumer = await js.consumers.get(streamName2, consumerOpts);
     const orderedMessages$ = this.orderedMessages$;
@@ -3598,6 +4404,7 @@ var MessageProvider = class {
       this.orderedReadyReject = null;
     }
     this.activeIterators.add(messages);
+    onConnected();
     try {
       await messages.closed();
     } finally {
@@ -3607,7 +4414,7 @@ var MessageProvider = class {
 };
 
 // src/server/infrastructure/metadata.provider.ts
-import { Logger as Logger13 } from "@nestjs/common";
+import { Logger as Logger16 } from "@nestjs/common";
 import { Kvm } from "@nats-io/kv";
 var MetadataProvider = class {
   constructor(options, connection) {
@@ -3616,7 +4423,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 Logger13("Jetstream:Metadata");
+  logger = new Logger16("Jetstream:Metadata");
   bucketName;
   replicas;
   ttl;
@@ -3708,176 +4515,8 @@ var MetadataProvider = class {
   }
 };
 
-// src/server/routing/pattern-registry.ts
-import { Logger as Logger14 } from "@nestjs/common";
-var HANDLER_LABELS = {
-  ["broadcast" /* Broadcast */]: "broadcast" /* Broadcast */,
-  ["ordered" /* Ordered */]: "ordered" /* Ordered */,
-  ["ev" /* Event */]: "event" /* Event */,
-  ["cmd" /* Command */]: "rpc" /* Rpc */
-};
-var PatternRegistry = class {
-  constructor(options) {
-    this.options = options;
-  }
-  logger = new Logger14("Jetstream:PatternRegistry");
-  registry = /* @__PURE__ */ new Map();
-  // Cached after registerHandlers() — the registry is immutable from that point
-  cachedPatterns = null;
-  _hasEvents = false;
-  _hasCommands = false;
-  _hasBroadcasts = false;
-  _hasOrdered = false;
-  _hasMetadata = false;
-  /**
-   * Register all handlers from the NestJS strategy.
-   *
-   * @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;
-      const isBroadcast = !!extras?.broadcast;
-      const isOrdered = !!extras?.ordered;
-      const meta = extras?.meta;
-      if (isBroadcast && isOrdered) {
-        throw new Error(
-          `Handler "${pattern}" cannot be both broadcast and ordered. Use one or the other.`
-        );
-      }
-      let kind;
-      if (isBroadcast) kind = "broadcast" /* Broadcast */;
-      else if (isOrdered) kind = "ordered" /* Ordered */;
-      else if (isEvent) kind = "ev" /* Event */;
-      else kind = "cmd" /* Command */;
-      const fullSubject = kind === "broadcast" /* Broadcast */ ? buildBroadcastSubject(pattern) : buildSubject(serviceName, kind, pattern);
-      this.registry.set(fullSubject, {
-        handler,
-        pattern,
-        isEvent: isEvent && !isOrdered,
-        isBroadcast,
-        isOrdered,
-        meta
-      });
-      this.logger.debug(`Registered ${HANDLER_LABELS[kind]}: ${pattern} -> ${fullSubject}`);
-    }
-    this.cachedPatterns = this.buildPatternsByKind();
-    this._hasEvents = this.cachedPatterns.events.length > 0;
-    this._hasCommands = this.cachedPatterns.commands.length > 0;
-    this._hasBroadcasts = this.cachedPatterns.broadcasts.length > 0;
-    this._hasOrdered = this.cachedPatterns.ordered.length > 0;
-    this._hasMetadata = [...this.registry.values()].some((entry) => entry.meta !== void 0);
-    this.logSummary();
-  }
-  /** Find handler for a full NATS subject. */
-  getHandler(subject) {
-    return this.registry.get(subject)?.handler ?? null;
-  }
-  /** Get all registered broadcast patterns (for consumer filter_subject setup). */
-  getBroadcastPatterns() {
-    return this.getPatternsByKind().broadcasts.map((p) => buildBroadcastSubject(p));
-  }
-  hasBroadcastHandlers() {
-    return this._hasBroadcasts;
-  }
-  hasRpcHandlers() {
-    return this._hasCommands;
-  }
-  hasEventHandlers() {
-    return this._hasEvents;
-  }
-  hasOrderedHandlers() {
-    return this._hasOrdered;
-  }
-  /** Get fully-qualified NATS subjects for ordered handlers. */
-  getOrderedSubjects() {
-    return this.getPatternsByKind().ordered.map(
-      (p) => buildSubject(this.options.name, "ordered" /* Ordered */, p)
-    );
-  }
-  /** Check if any registered handler has metadata. */
-  hasMetadata() {
-    return this._hasMetadata;
-  }
-  /**
-   * Get handler metadata entries for KV publishing.
-   *
-   * Returns a map of KV key -> metadata object for all handlers that have `meta`.
-   * Key format: `{serviceName}.{kind}.{pattern}`.
-   */
-  getMetadataEntries() {
-    const entries = /* @__PURE__ */ new Map();
-    for (const entry of this.registry.values()) {
-      if (!entry.meta) continue;
-      const kind = this.resolveStreamKind(entry);
-      const key = metadataKey(this.options.name, kind, entry.pattern);
-      entries.set(key, entry.meta);
-    }
-    return entries;
-  }
-  /** Get patterns grouped by kind (cached after registration). */
-  getPatternsByKind() {
-    const patterns = this.cachedPatterns ?? this.buildPatternsByKind();
-    return {
-      events: [...patterns.events],
-      commands: [...patterns.commands],
-      broadcasts: [...patterns.broadcasts],
-      ordered: [...patterns.ordered]
-    };
-  }
-  /** Normalize a full NATS subject back to the user-facing pattern. */
-  normalizeSubject(subject) {
-    const name = internalName(this.options.name);
-    const prefixes = [
-      `${name}.${"cmd" /* Command */}.`,
-      `${name}.${"ev" /* Event */}.`,
-      `${name}.${"ordered" /* Ordered */}.`,
-      `${"broadcast" /* Broadcast */}.`
-    ];
-    for (const prefix of prefixes) {
-      if (subject.startsWith(prefix)) {
-        return subject.slice(prefix.length);
-      }
-    }
-    return subject;
-  }
-  buildPatternsByKind() {
-    const events = [];
-    const commands = [];
-    const broadcasts = [];
-    const ordered = [];
-    for (const entry of this.registry.values()) {
-      if (entry.isBroadcast) broadcasts.push(entry.pattern);
-      else if (entry.isOrdered) ordered.push(entry.pattern);
-      else if (entry.isEvent) events.push(entry.pattern);
-      else commands.push(entry.pattern);
-    }
-    return { events, commands, broadcasts, ordered };
-  }
-  resolveStreamKind(entry) {
-    if (entry.isBroadcast) return "broadcast" /* Broadcast */;
-    if (entry.isOrdered) return "ordered" /* Ordered */;
-    if (entry.isEvent) return "ev" /* Event */;
-    return "cmd" /* Command */;
-  }
-  logSummary() {
-    const { events, commands, broadcasts, ordered } = this.getPatternsByKind();
-    const parts = [
-      `${commands.length} RPC`,
-      `${events.length} events`,
-      `${broadcasts.length} broadcasts`
-    ];
-    if (ordered.length > 0) {
-      parts.push(`${ordered.length} ordered`);
-    }
-    this.logger.log(`Registered handlers: ${parts.join(", ")}`);
-  }
-};
-
 // src/server/routing/event.router.ts
-import { Logger as Logger15 } from "@nestjs/common";
+import { Logger as Logger17 } from "@nestjs/common";
 import { headers as natsHeaders3 } from "@nats-io/transport-node";
 var eventConsumeKindFor = (kind) => {
   if (kind === "broadcast" /* Broadcast */) return "broadcast" /* Broadcast */;
@@ -3906,7 +4545,7 @@ var EventRouter = class {
       this.serverEndpoint = null;
     }
   }
-  logger = new Logger15("Jetstream:EventRouter");
+  logger = new Logger17("Jetstream:EventRouter");
   subscriptions = [];
   otel;
   serviceName;
@@ -3950,7 +4589,14 @@ var EventRouter = class {
     const hasAckExtension = ackExtensionInterval !== null && ackExtensionInterval > 0;
     const concurrency = this.getConcurrency(kind);
     const hasDlqCheck = deadLetterConfig !== void 0;
-    const emitRouted = eventBus.hasHook("messageRouted" /* MessageRouted */);
+    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);
@@ -3987,7 +4633,7 @@ var EventRouter = class {
           logger5.error(`Decode error for ${subject}:`, err);
           return null;
         }
-        if (emitRouted) eventBus.emitMessageRouted(subject, "event" /* Event */);
+        eventBus.emitMessageRouted(subject, "event" /* Event */);
         return { handler, data };
       } catch (err) {
         logger5.error(`Unexpected error in ${kind} event router`, err);
@@ -3999,12 +4645,18 @@ var EventRouter = class {
         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;
       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(
@@ -4027,18 +4679,21 @@ var EventRouter = class {
           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)) {
         settleSuccess(msg, ctx);
+        reportHandlerCompleted(msg, startedAt, statusForContext(ctx));
         if (stopAckExtension !== null) stopAckExtension();
         return void 0;
       }
       return pending.then(
         () => {
           settleSuccess(msg, ctx);
+          reportHandlerCompleted(msg, startedAt, statusForContext(ctx));
           if (stopAckExtension !== null) stopAckExtension();
         },
         async (err) => {
@@ -4047,6 +4702,7 @@ var EventRouter = class {
             err instanceof Error ? err : new Error(String(err)),
             `${kind}-handler:${msg.subject}`
           );
+          reportHandlerCompleted(msg, startedAt, "error");
           try {
             await settleFailure(msg, data, err);
           } finally {
@@ -4071,7 +4727,7 @@ var EventRouter = class {
           logger5.error(`Decode error for ${subject}:`, err);
           return void 0;
         }
-        if (emitRouted) eventBus.emitMessageRouted(subject, "event" /* Event */);
+        eventBus.emitMessageRouted(subject, "event" /* Event */);
       } catch (err) {
         logger5.error(`Ordered handler error (${subject}):`, err);
         return void 0;
@@ -4084,6 +4740,7 @@ var EventRouter = class {
           );
         }
       };
+      const startedAt = performance.now();
       let pending;
       try {
         pending = withConsumeSpan(
@@ -4102,15 +4759,24 @@ var EventRouter = class {
         );
       } 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, (err) => {
-        logger5.error(`Ordered handler error (${subject}):`, err);
-      });
+      return pending.then(
+        () => {
+          warnIfSettlementAttempted();
+          reportHandlerCompleted(msg, startedAt, "success");
+        },
+        (err) => {
+          logger5.error(`Ordered handler error (${subject}):`, err);
+          reportHandlerCompleted(msg, startedAt, "error");
+        }
+      );
     };
     const route = isOrdered ? handleOrderedSafe : handleSafe;
     const maxActive = isOrdered ? 1 : concurrency ?? Number.POSITIVE_INFINITY;
@@ -4296,7 +4962,7 @@ var EventRouter = class {
 };
 
 // src/server/routing/rpc.router.ts
-import { Logger as Logger16 } from "@nestjs/common";
+import { Logger as Logger18 } from "@nestjs/common";
 import { headers } from "@nats-io/transport-node";
 var RpcRouter = class {
   constructor(messageProvider, patternRegistry, connection, codec, eventBus, rpcOptions, ackWaitMap, options) {
@@ -4320,7 +4986,7 @@ var RpcRouter = class {
       this.serverEndpoint = null;
     }
   }
-  logger = new Logger16("Jetstream:RpcRouter");
+  logger = new Logger18("Jetstream:RpcRouter");
   timeout;
   concurrency;
   resolvedAckExtensionInterval;
@@ -4356,6 +5022,19 @@ var RpcRouter = class {
     const emitRpcTimeout = (subject, correlationId) => {
       eventBus.emit("rpcTimeout" /* RpcTimeout */, subject, correlationId);
     };
+    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 ?? "cmd" /* Command */;
+      eventBus.emit(
+        "handlerCompleted" /* HandlerCompleted */,
+        pattern,
+        declaredKind,
+        performance.now() - startedAt,
+        status
+      );
+    };
     const publishReply = (replyTo, correlationId, payload) => {
       try {
         const hdrs = headers();
@@ -4419,6 +5098,7 @@ var RpcRouter = class {
       const subject = msg.subject;
       const ctx = new RpcContext([msg]);
       const stopAckExtension = hasAckExtension ? startAckExtensionTimer(msg, ackExtensionInterval) : null;
+      const startedAt = performance.now();
       const reportHandlerError = (err) => {
         eventBus.emit(
           "error" /* Error */,
@@ -4449,12 +5129,14 @@ var RpcRouter = class {
       } catch (err) {
         if (stopAckExtension !== null) stopAckExtension();
         reportHandlerError(err);
+        reportHandlerCompleted(msg, startedAt, "error");
         return void 0;
       }
       if (!isPromiseLike2(pending)) {
         if (stopAckExtension !== null) stopAckExtension();
         msg.ack();
         publishReply(replyTo, correlationId, pending);
+        reportHandlerCompleted(msg, startedAt, "success");
         return void 0;
       }
       let settled = false;
@@ -4465,6 +5147,7 @@ var RpcRouter = class {
         abortController.abort();
         emitRpcTimeout(subject, correlationId);
         msg.term("Handler timeout");
+        reportHandlerCompleted(msg, startedAt, "terminated");
       }, timeout);
       return pending.then(
         (result) => {
@@ -4474,6 +5157,7 @@ var RpcRouter = class {
           if (stopAckExtension !== null) stopAckExtension();
           msg.ack();
           publishReply(replyTo, correlationId, result);
+          reportHandlerCompleted(msg, startedAt, "success");
         },
         (err) => {
           if (settled) return;
@@ -4481,6 +5165,7 @@ var RpcRouter = class {
           clearTimeout(timeoutId);
           if (stopAckExtension !== null) stopAckExtension();
           reportHandlerError(err);
+          reportHandlerCompleted(msg, startedAt, "error");
         }
       );
     };
@@ -4540,14 +5225,14 @@ var RpcRouter = class {
 };
 
 // src/shutdown/shutdown.manager.ts
-import { Logger as Logger17 } from "@nestjs/common";
+import { Logger as Logger19 } from "@nestjs/common";
 var ShutdownManager = class {
   constructor(connection, eventBus, timeout) {
     this.connection = connection;
     this.eventBus = eventBus;
     this.timeout = timeout;
   }
-  logger = new Logger17("Jetstream:Shutdown");
+  logger = new Logger19("Jetstream:Shutdown");
   shutdownPromise;
   /**
    * Execute the full shutdown sequence.
@@ -4601,12 +5286,14 @@ var JetstreamModule = class {
     return {
       module: JetstreamModule,
       global: true,
+      imports: options.metrics ? [JetstreamMetricsModule.forFeature(options.metrics)] : [],
       providers,
       exports: [
         JETSTREAM_CONNECTION,
         JETSTREAM_CODEC,
         JETSTREAM_EVENT_BUS,
         JETSTREAM_OPTIONS,
+        PatternRegistry,
         ShutdownManager,
         JetstreamStrategy,
         JetstreamHealthIndicator
@@ -4625,16 +5312,18 @@ var JetstreamModule = class {
   static forRootAsync(asyncOptions) {
     const asyncProviders = this.createAsyncOptionsProvider(asyncOptions);
     const coreProviders = this.createCoreDependentProviders();
+    const metricsImports = asyncOptions.metrics ? [JetstreamMetricsModule.forFeature(asyncOptions.metrics)] : [];
     return {
       module: JetstreamModule,
       global: true,
-      imports: asyncOptions.imports ?? [],
+      imports: [...asyncOptions.imports ?? [], ...metricsImports],
       providers: [...asyncProviders, ...coreProviders],
       exports: [
         JETSTREAM_CONNECTION,
         JETSTREAM_CODEC,
         JETSTREAM_EVENT_BUS,
         JETSTREAM_OPTIONS,
+        PatternRegistry,
         ShutdownManager,
         JetstreamStrategy,
         JetstreamHealthIndicator
@@ -4683,7 +5372,7 @@ var JetstreamModule = class {
         provide: JETSTREAM_EVENT_BUS,
         inject: [JETSTREAM_OPTIONS],
         useFactory: (options) => {
-          const logger5 = new Logger18("Jetstream:Module");
+          const logger5 = new Logger20("Jetstream:Module");
           return new EventBus(logger5, options.hooks);
         }
       },
@@ -4978,11 +5667,11 @@ var JetstreamModule = class {
 };
 JetstreamModule = __decorateClass([
   Global(),
-  Module({}),
-  __decorateParam(0, Optional()),
-  __decorateParam(0, Inject(ShutdownManager)),
-  __decorateParam(1, Optional()),
-  __decorateParam(1, Inject(JetstreamStrategy))
+  Module2({}),
+  __decorateParam(0, Optional2()),
+  __decorateParam(0, Inject2(ShutdownManager)),
+  __decorateParam(1, Optional2()),
+  __decorateParam(1, Inject2(JetstreamStrategy))
 ], JetstreamModule);
 export {
   ConsumeKind,