@horizon-republic/nestjs-jetstream 2.9.1 → 2.11.0

package/dist/index.js

@@ -13,20 +13,22 @@ var __decorateParam = (index, decorator) => (target, key) => decorator(target, k
 // src/jetstream.module.ts
 import {
   Global,
-  Inject,
-  Logger as Logger14,
-  Module,
-  Optional
+  Inject as Inject2,
+  Logger as Logger20,
+  Module as Module2,
+  Optional as Optional2
 } from "@nestjs/common";
 
 // src/client/jetstream.client.ts
-import { Logger } from "@nestjs/common";
+import { Logger as Logger5 } 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
+  headers as natsHeaders,
+  TimeoutError
 } from "@nats-io/transport-node";
-import { nuid } from "@nats-io/nuid";
 
 // src/interfaces/hooks.interface.ts
 var MessageKind = /* @__PURE__ */ ((MessageKind2) => {
@@ -44,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 || {});
 
@@ -224,6 +230,920 @@ var PatternPrefix = /* @__PURE__ */ ((PatternPrefix2) => {
 var isJetStreamRpcMode = (rpc) => rpc?.mode === "jetstream";
 var isCoreRpcMode = (rpc) => !rpc || rpc.mode === "core";
 
+// src/otel/constants.ts
+var TRACER_NAME = "@horizon-republic/nestjs-jetstream";
+
+// src/otel/attribute-keys.ts
+var ATTR_MESSAGING_SYSTEM = "messaging.system";
+var ATTR_MESSAGING_DESTINATION_NAME = "messaging.destination.name";
+var ATTR_MESSAGING_DESTINATION_TEMPLATE = "messaging.destination.template";
+var ATTR_MESSAGING_CLIENT_ID = "messaging.client.id";
+var ATTR_MESSAGING_OPERATION_NAME = "messaging.operation.name";
+var ATTR_MESSAGING_OPERATION_TYPE = "messaging.operation.type";
+var ATTR_MESSAGING_MESSAGE_BODY_SIZE = "messaging.message.body.size";
+var ATTR_MESSAGING_MESSAGE_ID = "messaging.message.id";
+var ATTR_MESSAGING_MESSAGE_CONVERSATION_ID = "messaging.message.conversation_id";
+var ATTR_MESSAGING_CONSUMER_GROUP_NAME = "messaging.consumer.group.name";
+var ATTR_MESSAGING_HEADER_PREFIX = "messaging.header.";
+var ATTR_MESSAGING_NATS_STREAM_NAME = "messaging.nats.stream.name";
+var ATTR_MESSAGING_NATS_STREAM_SEQUENCE = "messaging.nats.message.stream_sequence";
+var ATTR_MESSAGING_NATS_CONSUMER_SEQUENCE = "messaging.nats.message.consumer_sequence";
+var ATTR_MESSAGING_NATS_DELIVERY_COUNT = "messaging.nats.message.delivery_count";
+var ATTR_MESSAGING_NATS_BODY = "messaging.nats.message.body";
+var ATTR_MESSAGING_NATS_BODY_TRUNCATED = "messaging.nats.message.body.truncated";
+var ATTR_SERVER_ADDRESS = "server.address";
+var ATTR_SERVER_PORT = "server.port";
+var ATTR_JETSTREAM_SERVICE_NAME = "jetstream.service.name";
+var ATTR_JETSTREAM_KIND = "jetstream.kind";
+var ATTR_JETSTREAM_RPC_REPLY_HAS_ERROR = "jetstream.rpc.reply.has_error";
+var ATTR_JETSTREAM_RPC_REPLY_ERROR_CODE = "jetstream.rpc.reply.error.code";
+var ATTR_JETSTREAM_PROVISIONING_ENTITY = "jetstream.provisioning.entity";
+var ATTR_JETSTREAM_PROVISIONING_ACTION = "jetstream.provisioning.action";
+var ATTR_JETSTREAM_PROVISIONING_NAME = "jetstream.provisioning.name";
+var ATTR_JETSTREAM_SELF_HEALING_REASON = "jetstream.self_healing.reason";
+var ATTR_JETSTREAM_MIGRATION_REASON = "jetstream.migration.reason";
+var ATTR_JETSTREAM_DEAD_LETTER_REASON = "jetstream.dead_letter.reason";
+var ATTR_JETSTREAM_SCHEDULE_TARGET = "jetstream.schedule.target";
+var ATTR_NATS_CONNECTION_SERVER = "nats.connection.server";
+var NATS_MSG_ID_HEADER = "Nats-Msg-Id";
+var HOOK_PUBLISH = "publishHook";
+var HOOK_CONSUME = "consumeHook";
+var HOOK_RESPONSE = "responseHook";
+var SPAN_NAME_PUBLISH = "publish";
+var SPAN_NAME_PROCESS = "process";
+var SPAN_NAME_SEND = "send";
+var SPAN_NAME_DEAD_LETTER = "dead_letter";
+var SPAN_NAME_NATS_CONNECTION = "nats.connection";
+var SPAN_NAME_JETSTREAM_SHUTDOWN = "jetstream.shutdown";
+var SPAN_NAME_JETSTREAM_SELF_HEALING = "jetstream.self_healing";
+var SPAN_NAME_JETSTREAM_MIGRATION = "jetstream.migration";
+var SPAN_NAME_JETSTREAM_PROVISIONING_PREFIX = "jetstream.provisioning.";
+var EVENT_CONNECTION_DISCONNECTED = "connection.disconnected";
+var EVENT_CONNECTION_RECONNECTED = "connection.reconnected";
+var messagingHeaderAttr = (headerName) => `${ATTR_MESSAGING_HEADER_PREFIX}${headerName.toLowerCase()}`;
+
+// src/otel/trace-kinds.ts
+var JetstreamTrace = /* @__PURE__ */ ((JetstreamTrace2) => {
+  JetstreamTrace2["Publish"] = "publish";
+  JetstreamTrace2["Consume"] = "consume";
+  JetstreamTrace2["RpcClientSend"] = "rpc.client.send";
+  JetstreamTrace2["DeadLetter"] = "dead_letter";
+  JetstreamTrace2["ConnectionLifecycle"] = "connection.lifecycle";
+  JetstreamTrace2["SelfHealing"] = "self_healing";
+  JetstreamTrace2["Provisioning"] = "provisioning";
+  JetstreamTrace2["Migration"] = "migration";
+  JetstreamTrace2["Shutdown"] = "shutdown";
+  return JetstreamTrace2;
+})(JetstreamTrace || {});
+var DEFAULT_TRACES = [
+  "publish" /* Publish */,
+  "consume" /* Consume */,
+  "rpc.client.send" /* RpcClientSend */,
+  "dead_letter" /* DeadLetter */
+];
+
+// src/otel/capture.ts
+var NEGATION_PREFIX = "!";
+var REGEX_SPECIAL_RE = /[.+?^${}()|[\]\\*]/gu;
+var escapeForRegex = (input) => input.replace(REGEX_SPECIAL_RE, "\\$&");
+var globToRegex = (glob) => {
+  const escaped = escapeForRegex(glob.toLowerCase()).replace(/\\\*/gu, ".*");
+  return new RegExp(`^${escaped}$`, "u");
+};
+var compileHeaderAllowlist = (allowlist) => {
+  if (allowlist === true) return () => true;
+  if (allowlist === false) return () => false;
+  if (allowlist.length === 0) return () => false;
+  const includes = [];
+  const excludes = [];
+  for (const pattern of allowlist) {
+    const isExclude = pattern.startsWith(NEGATION_PREFIX);
+    const body = isExclude ? pattern.slice(NEGATION_PREFIX.length) : pattern;
+    const regex = globToRegex(body);
+    if (isExclude) excludes.push(regex);
+    else includes.push(regex);
+  }
+  return (name) => {
+    const lower = name.toLowerCase();
+    if (!includes.some((re) => re.test(lower))) return false;
+    if (excludes.some((re) => re.test(lower))) return false;
+    return true;
+  };
+};
+var subjectMatcherCache = /* @__PURE__ */ new WeakMap();
+var compileSubjectAllowlist = (allowlist) => {
+  if (!allowlist || allowlist.length === 0) return () => true;
+  const cached = subjectMatcherCache.get(allowlist);
+  if (cached) return cached;
+  const regexes = allowlist.map(globToRegex);
+  const matcher = (subject) => {
+    const lower = subject.toLowerCase();
+    return regexes.some((re) => re.test(lower));
+  };
+  subjectMatcherCache.set(allowlist, matcher);
+  return matcher;
+};
+var subjectMatchesAllowlist = (subject, allowlist) => compileSubjectAllowlist(allowlist)(subject);
+var HEADER_DENYLIST = /* @__PURE__ */ new Set([
+  "traceparent",
+  "tracestate",
+  "baggage",
+  "sentry-trace",
+  "b3",
+  "x-b3-traceid",
+  "x-b3-spanid",
+  "x-b3-parentspanid",
+  "x-b3-sampled",
+  "x-b3-flags",
+  "uber-trace-id",
+  "x-correlation-id",
+  "x-reply-to",
+  "x-error",
+  "x-subject",
+  "x-caller-name"
+]);
+var isNatsServerHeader = (lower) => lower.startsWith("nats-");
+var captureMatchingHeaders = (headers2, matcher) => {
+  if (!headers2) return {};
+  const out = {};
+  for (const key of headers2.keys()) {
+    const lower = key.toLowerCase();
+    if (HEADER_DENYLIST.has(lower)) continue;
+    if (isNatsServerHeader(lower)) continue;
+    if (!matcher(key)) continue;
+    const value = headers2.get(key);
+    if (value === "") continue;
+    out[messagingHeaderAttr(lower)] = value;
+  }
+  return out;
+};
+var tryUtf8Decode = (bytes) => {
+  try {
+    return new TextDecoder("utf-8", { fatal: false }).decode(bytes);
+  } catch {
+    return Buffer.from(bytes).toString("base64");
+  }
+};
+var captureBodyAttribute = (subject, payload, capture) => {
+  if (capture === false) return {};
+  if (payload.byteLength === 0) return {};
+  if (!subjectMatchesAllowlist(subject, capture.subjectAllowlist)) return {};
+  const { maxBytes } = capture;
+  const truncated = payload.byteLength > maxBytes;
+  const slice = truncated ? payload.subarray(0, maxBytes) : payload;
+  const decoded = tryUtf8Decode(slice);
+  const out = { [ATTR_MESSAGING_NATS_BODY]: decoded };
+  if (truncated) out[ATTR_MESSAGING_NATS_BODY_TRUNCATED] = true;
+  return out;
+};
+
+// src/otel/config.ts
+var PublishKind = /* @__PURE__ */ ((PublishKind2) => {
+  PublishKind2["Event"] = "event";
+  PublishKind2["RpcRequest"] = "rpc.request";
+  PublishKind2["Broadcast"] = "broadcast";
+  PublishKind2["Ordered"] = "ordered";
+  return PublishKind2;
+})(PublishKind || {});
+var ConsumeKind = /* @__PURE__ */ ((ConsumeKind2) => {
+  ConsumeKind2["Event"] = "event";
+  ConsumeKind2["Rpc"] = "rpc";
+  ConsumeKind2["Broadcast"] = "broadcast";
+  ConsumeKind2["Ordered"] = "ordered";
+  return ConsumeKind2;
+})(ConsumeKind || {});
+var DEFAULT_CAPTURE_HEADERS = ["x-request-id"];
+var DEFAULT_CAPTURE_BODY_MAX_BYTES = 4096;
+var NESTJS_BARE_ERROR_MESSAGE = "Internal server error";
+var isNestjsBareErrorSentinel = (obj) => obj.status === "error" && obj.message === NESTJS_BARE_ERROR_MESSAGE;
+var defaultErrorClassifier = (err) => {
+  if (err === null || typeof err !== "object") return "unexpected";
+  if (!(err instanceof Error)) {
+    if (isNestjsBareErrorSentinel(err)) return "unexpected";
+    return "expected";
+  }
+  let proto = err;
+  while (proto) {
+    const name = proto.constructor?.name;
+    if (name === "RpcException" || name === "HttpException") return "expected";
+    proto = Object.getPrototypeOf(proto);
+  }
+  return "unexpected";
+};
+var expandTracesOption = (option) => {
+  if (option === void 0 || option === "default") return new Set(DEFAULT_TRACES);
+  if (option === "all") return new Set(Object.values(JetstreamTrace));
+  if (option === "none") return /* @__PURE__ */ new Set();
+  return new Set(option);
+};
+var compileHeaderMatcher = (option) => compileHeaderAllowlist(option ?? DEFAULT_CAPTURE_HEADERS);
+var resolveCaptureBody = (option) => {
+  if (option === void 0 || option === false) return false;
+  if (option === true) return { maxBytes: DEFAULT_CAPTURE_BODY_MAX_BYTES };
+  return {
+    maxBytes: option.maxBytes ?? DEFAULT_CAPTURE_BODY_MAX_BYTES,
+    subjectAllowlist: option.subjectAllowlist
+  };
+};
+var resolveOtelOptions = (options = {}) => {
+  return {
+    enabled: options.enabled ?? true,
+    traces: expandTracesOption(options.traces),
+    captureHeaders: compileHeaderMatcher(options.captureHeaders),
+    captureBody: resolveCaptureBody(options.captureBody),
+    publishHook: options.publishHook,
+    consumeHook: options.consumeHook,
+    responseHook: options.responseHook,
+    shouldTracePublish: options.shouldTracePublish,
+    shouldTraceConsume: options.shouldTraceConsume,
+    errorClassifier: options.errorClassifier ?? defaultErrorClassifier
+  };
+};
+
+// src/otel/internal-utils.ts
+import { Logger } from "@nestjs/common";
+var logger = new Logger("Jetstream:Otel");
+var safelyInvokeHook = (hookName, hook, ...args) => {
+  if (!hook) return;
+  const logHookFailure = (err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    logger.debug(`OTel ${hookName} threw: ${message}`);
+  };
+  try {
+    const result = hook(...args);
+    if (result !== null && typeof result === "object" && "then" in result && typeof result.then === "function") {
+      result.then(void 0, logHookFailure);
+    }
+  } catch (err) {
+    logHookFailure(err);
+  }
+};
+var stripIpv6Brackets = (host) => host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+var parsePort = (portRaw) => {
+  if (!portRaw) return void 0;
+  const port = Number.parseInt(portRaw, 10);
+  return Number.isInteger(port) ? port : void 0;
+};
+var parseServerAddress = (servers) => {
+  const raw = servers[0];
+  if (!raw) return null;
+  if (raw.includes("://")) {
+    try {
+      const url = new URL(raw);
+      if (url.hostname.length === 0) return null;
+      const host2 = stripIpv6Brackets(url.hostname);
+      const port2 = parsePort(url.port || void 0);
+      return port2 === void 0 ? { host: host2 } : { host: host2, port: port2 };
+    } catch {
+      return null;
+    }
+  }
+  if (raw.startsWith("[")) {
+    const closeIdx = raw.indexOf("]");
+    if (closeIdx <= 0) return null;
+    const host2 = raw.slice(1, closeIdx);
+    const port2 = parsePort(raw.slice(closeIdx + 1).replace(/^:/u, ""));
+    return port2 === void 0 ? { host: host2 } : { host: host2, port: port2 };
+  }
+  const [host, portRaw] = raw.split(":");
+  if (!host) return null;
+  const port = parsePort(portRaw);
+  return port === void 0 ? { host } : { host, port };
+};
+var deriveOtelAttrs = (options) => ({
+  otel: resolveOtelOptions(options.otel),
+  serviceName: internalName(options.name),
+  serverEndpoint: parseServerAddress(options.servers)
+});
+
+// src/otel/propagator.ts
+import {
+  propagation
+} from "@opentelemetry/api";
+var injectContext = (ctx, carrier, setter) => {
+  propagation.inject(ctx, carrier, setter);
+};
+var extractContext = (ctx, carrier, getter) => propagation.extract(ctx, carrier, getter);
+
+// src/otel/tracer.ts
+import { trace } from "@opentelemetry/api";
+var PACKAGE_VERSION = true ? "2.11.0" : "0.0.0";
+var getTracer = () => trace.getTracer(TRACER_NAME, PACKAGE_VERSION);
+
+// src/otel/carrier.ts
+var hdrsSetter = {
+  set: (headers2, key, value) => {
+    headers2.set(key, value);
+  }
+};
+var hdrsGetter = {
+  keys: (headers2) => headers2 ? headers2.keys() : [],
+  get: (headers2, key) => {
+    if (!headers2) return void 0;
+    const all = typeof headers2.values === "function" ? headers2.values(key) : void 0;
+    if (Array.isArray(all)) {
+      const nonEmpty = all.filter((value) => value !== "");
+      if (nonEmpty.length === 0) return void 0;
+      return nonEmpty.join(",");
+    }
+    const single = headers2.get(key);
+    return single === "" ? void 0 : single;
+  }
+};
+
+// src/otel/attributes.ts
+var MESSAGING_SYSTEM = "nats";
+var baseMessagingAttributes = (ctx) => {
+  const attrs = {
+    [ATTR_MESSAGING_SYSTEM]: MESSAGING_SYSTEM,
+    [ATTR_MESSAGING_DESTINATION_NAME]: ctx.subject,
+    [ATTR_MESSAGING_CLIENT_ID]: ctx.serviceName
+  };
+  if (ctx.serverAddress) attrs[ATTR_SERVER_ADDRESS] = ctx.serverAddress;
+  if (ctx.serverPort !== void 0) attrs[ATTR_SERVER_PORT] = ctx.serverPort;
+  if (ctx.pattern && ctx.pattern !== ctx.subject) {
+    attrs[ATTR_MESSAGING_DESTINATION_TEMPLATE] = ctx.pattern;
+  }
+  return attrs;
+};
+var jetstreamKindForPublish = (kind) => kind === "rpc.request" /* RpcRequest */ ? "rpc" /* Rpc */ : kind;
+var buildPublishAttributes = (ctx) => {
+  const attrs = {
+    ...baseMessagingAttributes(ctx),
+    [ATTR_MESSAGING_OPERATION_NAME]: SPAN_NAME_PUBLISH,
+    [ATTR_MESSAGING_OPERATION_TYPE]: SPAN_NAME_SEND,
+    [ATTR_MESSAGING_MESSAGE_BODY_SIZE]: ctx.payloadBytes,
+    [ATTR_JETSTREAM_KIND]: jetstreamKindForPublish(ctx.kind)
+  };
+  if (ctx.messageId) attrs[ATTR_MESSAGING_MESSAGE_ID] = ctx.messageId;
+  if (ctx.correlationId) attrs[ATTR_MESSAGING_MESSAGE_CONVERSATION_ID] = ctx.correlationId;
+  return attrs;
+};
+var buildConsumeAttributes = (ctx) => {
+  const { msg, info, kind, payloadBytes } = ctx;
+  const attrs = {
+    ...baseMessagingAttributes(ctx),
+    [ATTR_MESSAGING_OPERATION_NAME]: SPAN_NAME_PROCESS,
+    [ATTR_MESSAGING_OPERATION_TYPE]: SPAN_NAME_PROCESS,
+    [ATTR_MESSAGING_MESSAGE_BODY_SIZE]: payloadBytes,
+    [ATTR_JETSTREAM_KIND]: kind
+  };
+  if (info) {
+    attrs[ATTR_MESSAGING_NATS_STREAM_NAME] = info.stream;
+    attrs[ATTR_MESSAGING_CONSUMER_GROUP_NAME] = info.consumer;
+    attrs[ATTR_MESSAGING_NATS_STREAM_SEQUENCE] = info.streamSequence;
+    attrs[ATTR_MESSAGING_NATS_CONSUMER_SEQUENCE] = info.deliverySequence;
+    attrs[ATTR_MESSAGING_NATS_DELIVERY_COUNT] = info.deliveryCount;
+  }
+  const messageId = msg.headers?.get(NATS_MSG_ID_HEADER);
+  if (messageId) attrs[ATTR_MESSAGING_MESSAGE_ID] = messageId;
+  return attrs;
+};
+var buildRpcClientAttributes = (ctx) => {
+  const attrs = {
+    ...baseMessagingAttributes(ctx),
+    [ATTR_MESSAGING_OPERATION_NAME]: SPAN_NAME_SEND,
+    [ATTR_MESSAGING_OPERATION_TYPE]: SPAN_NAME_SEND,
+    [ATTR_MESSAGING_MESSAGE_BODY_SIZE]: ctx.payloadBytes,
+    [ATTR_JETSTREAM_KIND]: "rpc" /* Rpc */
+  };
+  if (ctx.correlationId) attrs[ATTR_MESSAGING_MESSAGE_CONVERSATION_ID] = ctx.correlationId;
+  if (ctx.messageId) attrs[ATTR_MESSAGING_MESSAGE_ID] = ctx.messageId;
+  return attrs;
+};
+var buildDeadLetterAttributes = (ctx) => {
+  const attrs = {
+    ...baseMessagingAttributes(ctx),
+    [ATTR_MESSAGING_OPERATION_NAME]: SPAN_NAME_DEAD_LETTER,
+    [ATTR_MESSAGING_OPERATION_TYPE]: SPAN_NAME_PROCESS,
+    [ATTR_MESSAGING_NATS_DELIVERY_COUNT]: ctx.finalDeliveryCount
+  };
+  if (ctx.reason) attrs[ATTR_JETSTREAM_DEAD_LETTER_REASON] = ctx.reason;
+  return attrs;
+};
+var extractFromRpcException = (record) => {
+  const getError = record.getError;
+  if (typeof getError !== "function") return void 0;
+  return codeFromPayload(getError.call(record));
+};
+var extractFromHttpException = (record) => {
+  const getStatus = record.getStatus;
+  if (typeof getStatus !== "function") return void 0;
+  const status = getStatus.call(record);
+  return typeof status === "number" && Number.isFinite(status) ? `HTTP_${status}` : void 0;
+};
+var extractFromOwnCode = (record) => {
+  const code = record.code ?? record.errorCode;
+  return typeof code === "string" && isStableErrorCode(code) ? code : void 0;
+};
+var extractExpectedErrorCode = (err) => {
+  if (err === null || typeof err !== "object") return void 0;
+  const record = err;
+  if (hasAncestorNamed(err, "RpcException")) {
+    const fromPayload = extractFromRpcException(record);
+    if (fromPayload !== void 0) return fromPayload;
+  }
+  if (hasAncestorNamed(err, "HttpException")) {
+    const fromStatus = extractFromHttpException(record);
+    if (fromStatus !== void 0) return fromStatus;
+  }
+  return extractFromOwnCode(record);
+};
+var hasAncestorNamed = (err, name) => {
+  let proto = Object.getPrototypeOf(err);
+  while (proto) {
+    const ctorName = proto.constructor?.name;
+    if (ctorName === name) return true;
+    proto = Object.getPrototypeOf(proto);
+  }
+  return false;
+};
+var STABLE_ERROR_CODE_RE = /^[A-Z][A-Z0-9_]*$/u;
+var isStableErrorCode = (value) => STABLE_ERROR_CODE_RE.test(value);
+var codeFromPayload = (payload) => {
+  if (payload === null || payload === void 0) return void 0;
+  if (typeof payload === "string") return isStableErrorCode(payload) ? payload : void 0;
+  if (typeof payload === "object") {
+    const code = payload.code;
+    if (typeof code === "string" && isStableErrorCode(code)) return code;
+  }
+  return void 0;
+};
+var buildExpectedErrorAttributes = (err) => {
+  const attrs = {
+    [ATTR_JETSTREAM_RPC_REPLY_HAS_ERROR]: true
+  };
+  const code = extractExpectedErrorCode(err);
+  if (code !== void 0) attrs[ATTR_JETSTREAM_RPC_REPLY_ERROR_CODE] = code;
+  return attrs;
+};
+var applyExpectedErrorAttributes = (span, err) => {
+  span.setAttributes(buildExpectedErrorAttributes(err));
+};
+
+// src/otel/spans/publish.ts
+import { Logger as Logger2 } from "@nestjs/common";
+import { SpanKind, SpanStatusCode, context, trace as trace2 } from "@opentelemetry/api";
+var logger2 = new Logger2("Jetstream:Otel");
+var shouldTracePublishSafe = (predicate, subject, record) => {
+  if (!predicate) return true;
+  try {
+    return predicate(subject, record);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    logger2.debug(`OTel shouldTracePublish threw: ${message}`);
+    return true;
+  }
+};
+var withPublishSpan = async (ctx, config, fn) => {
+  if (!config.enabled) return fn();
+  const shouldCreateSpan = config.traces.has("publish" /* Publish */) && shouldTracePublishSafe(config.shouldTracePublish, ctx.subject, ctx.record);
+  if (!shouldCreateSpan) {
+    injectContext(context.active(), ctx.headers, hdrsSetter);
+    return fn();
+  }
+  const tracer = getTracer();
+  const span = tracer.startSpan(`${SPAN_NAME_PUBLISH} ${ctx.subject}`, {
+    kind: SpanKind.PRODUCER,
+    attributes: {
+      ...buildPublishAttributes({
+        subject: ctx.subject,
+        pattern: ctx.pattern,
+        serviceName: ctx.serviceName,
+        serverAddress: ctx.endpoint?.host,
+        serverPort: ctx.endpoint?.port,
+        kind: ctx.kind,
+        payloadBytes: ctx.payloadBytes,
+        messageId: ctx.messageId,
+        correlationId: ctx.correlationId
+      }),
+      ...ctx.scheduleTarget ? { [ATTR_JETSTREAM_SCHEDULE_TARGET]: ctx.scheduleTarget } : {},
+      ...captureMatchingHeaders(ctx.headers, config.captureHeaders),
+      ...captureBodyAttribute(ctx.subject, ctx.payload, config.captureBody)
+    }
+  });
+  const ctxWithSpan = trace2.setSpan(context.active(), span);
+  injectContext(ctxWithSpan, ctx.headers, hdrsSetter);
+  const start = Date.now();
+  const invokeResponseHook = (error) => {
+    context.with(ctxWithSpan, () => {
+      safelyInvokeHook(HOOK_RESPONSE, config.responseHook, span, {
+        subject: ctx.subject,
+        durationMs: Date.now() - start,
+        error
+      });
+    });
+  };
+  try {
+    const result = await context.with(ctxWithSpan, async () => {
+      safelyInvokeHook(HOOK_PUBLISH, config.publishHook, span, {
+        subject: ctx.subject,
+        record: ctx.record,
+        kind: ctx.kind
+      });
+      return fn();
+    });
+    span.setStatus({ code: SpanStatusCode.OK });
+    invokeResponseHook();
+    return result;
+  } catch (err) {
+    const error = err instanceof Error ? err : new Error(String(err));
+    span.recordException(error);
+    span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+    invokeResponseHook(error);
+    throw err;
+  } finally {
+    span.end();
+  }
+};
+
+// src/otel/spans/consume.ts
+import {
+  ROOT_CONTEXT,
+  SpanKind as SpanKind2,
+  SpanStatusCode as SpanStatusCode2,
+  context as context2,
+  trace as trace3
+} from "@opentelemetry/api";
+var isPromiseLike = (value) => typeof value === "object" && value !== null && typeof value.then === "function";
+var applyExpectedError = (span, err) => {
+  span.setStatus({ code: SpanStatusCode2.OK });
+  applyExpectedErrorAttributes(span, err);
+};
+var applyUnexpectedError = (span, err) => {
+  const error = err instanceof Error ? err : new Error(String(err));
+  span.recordException(error);
+  span.setStatus({ code: SpanStatusCode2.ERROR, message: error.message });
+};
+var withConsumeSpan = (ctx, config, fn, options = {}) => {
+  if (!config.enabled) return fn();
+  const parentCtx = extractContext(ROOT_CONTEXT, ctx.msg.headers, hdrsGetter);
+  const shouldCreateSpan = config.traces.has("consume" /* Consume */) && (config.shouldTraceConsume?.(ctx.subject, ctx.msg) ?? true);
+  if (!shouldCreateSpan) {
+    return context2.with(parentCtx, fn);
+  }
+  const tracer = getTracer();
+  const span = tracer.startSpan(
+    `${SPAN_NAME_PROCESS} ${ctx.subject}`,
+    {
+      kind: SpanKind2.CONSUMER,
+      attributes: {
+        ...buildConsumeAttributes({
+          subject: ctx.subject,
+          pattern: ctx.pattern,
+          msg: ctx.msg,
+          info: ctx.info,
+          kind: ctx.kind,
+          payloadBytes: ctx.payloadBytes,
+          serviceName: ctx.serviceName,
+          serverAddress: ctx.endpoint?.host,
+          serverPort: ctx.endpoint?.port
+        }),
+        ...captureMatchingHeaders(ctx.msg.headers, config.captureHeaders),
+        ...captureBodyAttribute(ctx.subject, ctx.msg.data, config.captureBody)
+      }
+    },
+    parentCtx
+  );
+  const ctxWithSpan = trace3.setSpan(parentCtx, span);
+  const start = Date.now();
+  let finalized = false;
+  const { signal, timeoutLabel = "handler.timeout" } = options;
+  let detachAbort = null;
+  const invokeResponseHook = (durationMs, error) => {
+    context2.with(ctxWithSpan, () => {
+      safelyInvokeHook(HOOK_RESPONSE, config.responseHook, span, {
+        subject: ctx.subject,
+        durationMs,
+        error
+      });
+    });
+  };
+  const finishOk2 = () => {
+    if (finalized) return;
+    finalized = true;
+    detachAbort?.();
+    span.setStatus({ code: SpanStatusCode2.OK });
+    invokeResponseHook(Date.now() - start);
+    span.end();
+  };
+  const finishError2 = (err) => {
+    if (finalized) return;
+    finalized = true;
+    detachAbort?.();
+    let classification = "unexpected";
+    try {
+      classification = config.errorClassifier(err);
+    } catch {
+    }
+    if (classification === "expected") {
+      applyExpectedError(span, err);
+    } else {
+      applyUnexpectedError(span, err);
+    }
+    invokeResponseHook(Date.now() - start, err instanceof Error ? err : new Error(String(err)));
+    span.end();
+  };
+  const onAbort = () => {
+    if (finalized) return;
+    finalized = true;
+    const error = new Error(timeoutLabel);
+    span.addEvent(timeoutLabel);
+    span.recordException(error);
+    span.setStatus({ code: SpanStatusCode2.ERROR, message: timeoutLabel });
+    invokeResponseHook(Date.now() - start, error);
+    span.end();
+  };
+  if (signal) {
+    if (signal.aborted) {
+      onAbort();
+    } else {
+      signal.addEventListener("abort", onAbort, { once: true });
+      detachAbort = () => {
+        signal.removeEventListener("abort", onAbort);
+      };
+    }
+  }
+  let result;
+  try {
+    result = context2.with(ctxWithSpan, () => {
+      safelyInvokeHook(HOOK_CONSUME, config.consumeHook, span, {
+        subject: ctx.subject,
+        msg: ctx.msg,
+        handlerMetadata: ctx.handlerMetadata,
+        kind: ctx.kind
+      });
+      return fn();
+    });
+  } catch (err) {
+    finishError2(err);
+    throw err;
+  }
+  if (isPromiseLike(result)) {
+    return Promise.resolve(result).then(
+      (value) => {
+        finishOk2();
+        return value;
+      },
+      (err) => {
+        finishError2(err);
+        throw err;
+      }
+    );
+  }
+  finishOk2();
+  return result;
+};
+
+// src/otel/spans/rpc-client.ts
+import { Logger as Logger3 } from "@nestjs/common";
+import { SpanKind as SpanKind3, SpanStatusCode as SpanStatusCode3, context as context3, trace as trace4 } from "@opentelemetry/api";
+var logger3 = new Logger3("Jetstream:Otel");
+var RPC_TIMEOUT_MESSAGE = "rpc.timeout";
+var beginRpcClientSpan = (ctx, config) => {
+  if (!config.enabled) {
+    return {
+      activeContext: context3.active(),
+      finish: () => void 0
+    };
+  }
+  if (!config.traces.has("rpc.client.send" /* RpcClientSend */)) {
+    injectContext(context3.active(), ctx.headers, hdrsSetter);
+    return {
+      activeContext: context3.active(),
+      finish: () => void 0
+    };
+  }
+  const tracer = getTracer();
+  const span = tracer.startSpan(`${SPAN_NAME_SEND} ${ctx.subject}`, {
+    kind: SpanKind3.CLIENT,
+    attributes: {
+      ...buildRpcClientAttributes({
+        subject: ctx.subject,
+        pattern: ctx.pattern,
+        correlationId: ctx.correlationId,
+        payloadBytes: ctx.payloadBytes,
+        messageId: ctx.messageId,
+        serviceName: ctx.serviceName,
+        serverAddress: ctx.endpoint?.host,
+        serverPort: ctx.endpoint?.port
+      }),
+      ...captureMatchingHeaders(ctx.headers, config.captureHeaders),
+      ...captureBodyAttribute(ctx.subject, ctx.payload, config.captureBody)
+    }
+  });
+  const ctxWithSpan = trace4.setSpan(context3.active(), span);
+  injectContext(ctxWithSpan, ctx.headers, hdrsSetter);
+  const start = Date.now();
+  let finalized = false;
+  const finish = (outcome) => {
+    if (finalized) return;
+    finalized = true;
+    let reply;
+    let error;
+    switch (outcome.kind) {
+      case "ok" /* Ok */:
+        reply = outcome.reply;
+        span.setStatus({ code: SpanStatusCode3.OK });
+        break;
+      case "reply-error" /* ReplyError */:
+        reply = outcome.replyPayload;
+        applyExpectedErrorAttributes(span, outcome.replyPayload);
+        span.setStatus({ code: SpanStatusCode3.OK });
+        break;
+      case "timeout" /* Timeout */:
+        error = new Error(RPC_TIMEOUT_MESSAGE);
+        span.addEvent(RPC_TIMEOUT_MESSAGE);
+        span.setStatus({ code: SpanStatusCode3.ERROR, message: RPC_TIMEOUT_MESSAGE });
+        break;
+      case "error" /* Error */:
+        error = outcome.error;
+        span.recordException(outcome.error);
+        span.setStatus({ code: SpanStatusCode3.ERROR, message: outcome.error.message });
+        break;
+      default: {
+        const unknownOutcome = outcome;
+        logger3.error(`Unhandled RPC outcome: ${String(unknownOutcome.kind)}`);
+        span.setStatus({ code: SpanStatusCode3.ERROR, message: "unknown outcome" });
+      }
+    }
+    context3.with(ctxWithSpan, () => {
+      safelyInvokeHook(HOOK_RESPONSE, config.responseHook, span, {
+        subject: ctx.subject,
+        durationMs: Date.now() - start,
+        reply,
+        error
+      });
+    });
+    span.end();
+  };
+  return { activeContext: ctxWithSpan, finish };
+};
+
+// src/otel/spans/dead-letter.ts
+import { ROOT_CONTEXT as ROOT_CONTEXT2, SpanKind as SpanKind4, SpanStatusCode as SpanStatusCode4, context as context4, trace as trace5 } from "@opentelemetry/api";
+var withDeadLetterSpan = async (ctx, config, fn) => {
+  if (!config.enabled || !config.traces.has("dead_letter" /* DeadLetter */)) {
+    return fn();
+  }
+  const parentCtx = extractContext(ROOT_CONTEXT2, ctx.msg.headers, hdrsGetter);
+  const tracer = getTracer();
+  const span = tracer.startSpan(
+    `${SPAN_NAME_DEAD_LETTER} ${ctx.msg.subject}`,
+    {
+      kind: SpanKind4.INTERNAL,
+      attributes: buildDeadLetterAttributes({
+        subject: ctx.msg.subject,
+        pattern: ctx.pattern,
+        serviceName: ctx.serviceName,
+        serverAddress: ctx.endpoint?.host,
+        serverPort: ctx.endpoint?.port,
+        finalDeliveryCount: ctx.finalDeliveryCount,
+        reason: ctx.reason
+      })
+    },
+    parentCtx
+  );
+  const ctxWithSpan = trace5.setSpan(parentCtx, span);
+  const start = Date.now();
+  const invokeResponseHook = (error) => {
+    context4.with(ctxWithSpan, () => {
+      safelyInvokeHook(HOOK_RESPONSE, config.responseHook, span, {
+        subject: ctx.msg.subject,
+        durationMs: Date.now() - start,
+        error
+      });
+    });
+  };
+  try {
+    const result = await context4.with(ctxWithSpan, fn);
+    span.setStatus({ code: SpanStatusCode4.OK });
+    invokeResponseHook();
+    return result;
+  } catch (err) {
+    const error = err instanceof Error ? err : new Error(String(err));
+    span.recordException(error);
+    span.setStatus({ code: SpanStatusCode4.ERROR, message: error.message });
+    invokeResponseHook(error);
+    throw err;
+  } finally {
+    span.end();
+  }
+};
+
+// src/otel/spans/infrastructure.ts
+import { Logger as Logger4 } from "@nestjs/common";
+import {
+  SpanKind as SpanKind5,
+  SpanStatusCode as SpanStatusCode5,
+  context as context5,
+  trace as trace6
+} from "@opentelemetry/api";
+var logger4 = new Logger4("Jetstream:Otel");
+var startInfraSpan = (config, traceKind, name, ctx, extraAttributes = {}) => {
+  if (!config.enabled || !config.traces.has(traceKind)) return null;
+  const tracer = getTracer();
+  const attributes = {
+    [ATTR_JETSTREAM_SERVICE_NAME]: ctx.serviceName
+  };
+  if (ctx.endpoint?.host) attributes[ATTR_SERVER_ADDRESS] = ctx.endpoint.host;
+  if (ctx.endpoint?.port !== void 0) attributes[ATTR_SERVER_PORT] = ctx.endpoint.port;
+  for (const [key, value] of Object.entries(extraAttributes)) {
+    if (value !== void 0) attributes[key] = value;
+  }
+  return tracer.startSpan(name, { kind: SpanKind5.INTERNAL, attributes });
+};
+var finishOk = (span) => {
+  span.setStatus({ code: SpanStatusCode5.OK });
+  span.end();
+};
+var finishError = (span, err) => {
+  const error = err instanceof Error ? err : new Error(String(err));
+  span.recordException(error);
+  span.setStatus({ code: SpanStatusCode5.ERROR, message: error.message });
+  span.end();
+};
+var wrapInfra = async (config, traceKind, name, ctx, attributes, op) => {
+  const span = startInfraSpan(config, traceKind, name, ctx, attributes);
+  if (!span) return op();
+  const ctxWithSpan = trace6.setSpan(context5.active(), span);
+  try {
+    const result = await context5.with(ctxWithSpan, op);
+    finishOk(span);
+    return result;
+  } catch (err) {
+    finishError(span, err);
+    throw err;
+  }
+};
+var beginConnectionLifecycleSpan = (config, ctx) => {
+  const span = startInfraSpan(
+    config,
+    "connection.lifecycle" /* ConnectionLifecycle */,
+    SPAN_NAME_NATS_CONNECTION,
+    ctx,
+    { [ATTR_NATS_CONNECTION_SERVER]: ctx.server }
+  );
+  if (!span) {
+    return {
+      recordEvent: () => void 0,
+      finish: () => void 0
+    };
+  }
+  let finalized = false;
+  return {
+    recordEvent: (name, attributes) => {
+      if (finalized) {
+        logger4.debug(`recordEvent('${name}') called after connection span finished`);
+        return;
+      }
+      span.addEvent(name, attributes);
+    },
+    finish: (err) => {
+      if (finalized) return;
+      finalized = true;
+      if (err === void 0) finishOk(span);
+      else finishError(span, err);
+    }
+  };
+};
+var withSelfHealingSpan = (config, ctx, op) => wrapInfra(
+  config,
+  "self_healing" /* SelfHealing */,
+  SPAN_NAME_JETSTREAM_SELF_HEALING,
+  ctx,
+  {
+    [ATTR_MESSAGING_NATS_STREAM_NAME]: ctx.stream,
+    [ATTR_MESSAGING_CONSUMER_GROUP_NAME]: ctx.consumer,
+    [ATTR_JETSTREAM_SELF_HEALING_REASON]: ctx.reason
+  },
+  op
+);
+var withProvisioningSpan = (config, ctx, op) => wrapInfra(
+  config,
+  "provisioning" /* Provisioning */,
+  `${SPAN_NAME_JETSTREAM_PROVISIONING_PREFIX}${ctx.entity}`,
+  ctx,
+  {
+    [ATTR_JETSTREAM_PROVISIONING_ENTITY]: ctx.entity,
+    [ATTR_JETSTREAM_PROVISIONING_ACTION]: ctx.action,
+    [ATTR_JETSTREAM_PROVISIONING_NAME]: ctx.name
+  },
+  op
+);
+var withMigrationSpan = (config, ctx, op) => wrapInfra(
+  config,
+  "migration" /* Migration */,
+  SPAN_NAME_JETSTREAM_MIGRATION,
+  ctx,
+  {
+    [ATTR_MESSAGING_NATS_STREAM_NAME]: ctx.stream,
+    [ATTR_JETSTREAM_MIGRATION_REASON]: ctx.reason
+  },
+  op
+);
+var withShutdownSpan = (config, ctx, op) => wrapInfra(config, "shutdown" /* Shutdown */, SPAN_NAME_JETSTREAM_SHUTDOWN, ctx, {}, op);
+
 // src/client/jetstream.record.ts
 var JetstreamRecord = class {
   constructor(data, headers2, timeout, messageId, schedule, ttl) {
@@ -376,9 +1296,14 @@ var JetstreamRecordBuilder = class {
       this.ttlDuration
     );
   }
-  /** Validate that a header key is not reserved. */
+  /**
+   * Validate that a header key is not reserved. NATS treats header names
+   * case-insensitively, so the check is against the lowercase form to keep
+   * `'X-Correlation-ID'`, `'x-correlation-id'`, and any other casing in
+   * lockstep. `RESERVED_HEADERS` is defined as an all-lowercase set.
+   */
   validateHeaderKey(key) {
-    if (RESERVED_HEADERS.has(key)) {
+    if (RESERVED_HEADERS.has(key.toLowerCase())) {
       throw new Error(
         `Header "${key}" is reserved by the JetStream transport and cannot be set manually. Reserved headers: ${[...RESERVED_HEADERS].join(", ")}`
       );
@@ -399,6 +1324,22 @@ var nanosToGoDuration = (nanos) => {
 
 // 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);
+  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();
@@ -414,8 +1355,11 @@ var JetstreamClient = class extends ClientProxy {
     this.orderedSubjectPrefix = `${targetInternal}.${"ordered" /* Ordered */}.`;
     this.isCoreMode = isCoreRpcMode(this.rootOptions.rpc);
     this.defaultRpcTimeout = isJetStreamRpcMode(this.rootOptions.rpc) ? this.rootOptions.rpc?.timeout ?? DEFAULT_JETSTREAM_RPC_TIMEOUT : this.rootOptions.rpc?.timeout ?? DEFAULT_RPC_TIMEOUT;
+    const derived = deriveOtelAttrs(this.rootOptions);
+    this.otel = derived.otel;
+    this.serverEndpoint = derived.serverEndpoint;
   }
-  logger = new Logger("Jetstream:Client");
+  logger = new Logger5("Jetstream:Client");
   /** Target service name this client sends messages to. */
   targetName;
   /** Pre-cached caller name derived from rootOptions.name, computed once in constructor. */
@@ -435,6 +1379,10 @@ var JetstreamClient = class extends ClientProxy {
    */
   isCoreMode;
   defaultRpcTimeout;
+  /** Resolved OpenTelemetry configuration, computed once in the constructor. */
+  otel;
+  /** Server endpoint parts used for `server.address` / `server.port` span attributes. */
+  serverEndpoint;
   /** Shared inbox for JetStream-mode RPC responses. */
   inbox = null;
   inboxSubscription = null;
@@ -502,32 +1450,64 @@ var JetstreamClient = class extends ClientProxy {
     if (!this.readyForPublish) await this.connect();
     const { data, hdrs, messageId, schedule, ttl } = this.extractRecordData(packet.data);
     const eventSubject = this.buildEventSubject(packet.pattern);
+    const publishSubject = schedule ? this.buildScheduleSubject(eventSubject) : eventSubject;
     const msgHeaders = this.buildHeaders(hdrs, { subject: eventSubject });
-    if (schedule) {
-      const scheduleSubject = this.buildScheduleSubject(eventSubject);
-      const ack = await this.connection.getJetStreamClient().publish(scheduleSubject, this.codec.encode(data), {
-        headers: msgHeaders,
-        msgID: messageId ?? nuid.next(),
-        ttl,
-        schedule: {
-          specification: schedule.at,
-          target: eventSubject
+    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 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;
+          }
+          const ack = await this.connection.getJetStreamClient().publish(publishSubject, encoded, {
+            headers: msgHeaders,
+            msgID: effectiveMsgId,
+            ttl
+          });
+          warnIfDuplicate("event", ack);
         }
-      });
-      if (ack.duplicate) {
-        this.logger.warn(
-          `Duplicate scheduled publish detected: ${scheduleSubject} (seq: ${ack.seq})`
-        );
-      }
-    } else {
-      const ack = await this.connection.getJetStreamClient().publish(eventSubject, this.codec.encode(data), {
-        headers: msgHeaders,
-        msgID: messageId ?? nuid.next(),
-        ttl
-      });
-      if (ack.duplicate) {
-        this.logger.warn(`Duplicate event publish detected: ${eventSubject} (seq: ${ack.seq})`);
-      }
+      );
+      this.reportPublished(declaredPattern, streamKind, startedAt, "success");
+    } catch (err) {
+      this.reportPublished(declaredPattern, streamKind, startedAt, "error");
+      throw err;
     }
     return void 0;
   }
@@ -556,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 () => {
@@ -578,38 +1561,118 @@ 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);
+    const spanHandle = beginRpcClientSpan(
+      {
+        subject,
+        payloadBytes: encoded.length,
+        payload: encoded,
+        headers: hdrs,
+        serviceName: this.callerName,
+        endpoint: this.serverEndpoint
+      },
+      this.otel
+    );
+    const startedAt = performance.now();
     try {
       const nc = this.readyForPublish ? this.connection.unwrap : await this.connect();
-      const effectiveTimeout = timeout ?? this.defaultRpcTimeout;
-      const hdrs = this.buildHeaders(customHeaders, { subject });
-      const response = await nc.request(subject, this.codec.encode(data), {
-        timeout: effectiveTimeout,
-        headers: hdrs
-      });
+      const response = await context6.with(
+        spanHandle.activeContext,
+        () => nc.request(subject, encoded, {
+          timeout: effectiveTimeout,
+          headers: hdrs
+        })
+      );
       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) {
       const error = err instanceof Error ? err : new Error("Unknown error");
-      this.logger.error(`Core RPC error (${subject}):`, err);
-      this.eventBus.emit("error" /* Error */, error, "client-rpc");
+      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;
-    this.pendingMessages.set(correlationId, callback);
+    const hdrs = this.buildHeaders(customHeaders, {
+      subject,
+      correlationId,
+      replyTo: this.inbox ?? ""
+    });
+    const encoded = this.codec.encode(data);
+    const spanHandle = beginRpcClientSpan(
+      {
+        subject,
+        correlationId,
+        payloadBytes: encoded.length,
+        payload: encoded,
+        messageId,
+        headers: hdrs,
+        serviceName: this.callerName,
+        endpoint: this.serverEndpoint
+      },
+      this.otel
+    );
+    const startedAt = performance.now();
+    this.pendingMessages.set(correlationId, (packet) => {
+      if (packet.err) {
+        if (packet.err instanceof Error) {
+          spanHandle.finish({ kind: "error" /* Error */, error: packet.err });
+        } 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);
+    });
+    const timeoutId = setTimeout(() => {
+      if (!this.pendingMessages.has(correlationId)) return;
+      this.pendingTimeouts.delete(correlationId);
+      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);
     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);
+        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,
@@ -617,24 +1680,14 @@ var JetstreamClient = class extends ClientProxy {
         });
         return;
       }
-      const timeoutId = setTimeout(() => {
-        if (!this.pendingMessages.has(correlationId)) return;
-        this.pendingTimeouts.delete(correlationId);
-        this.pendingMessages.delete(correlationId);
-        this.logger.error(`JetStream RPC timeout (${effectiveTimeout}ms): ${subject}`);
-        this.eventBus.emit("rpcTimeout" /* RpcTimeout */, subject, correlationId);
-        callback({ err: new Error("RPC timeout"), response: null, isDisposed: true });
-      }, effectiveTimeout);
-      this.pendingTimeouts.set(correlationId, timeoutId);
-      const hdrs = this.buildHeaders(customHeaders, {
-        subject,
-        correlationId,
-        replyTo: this.inbox
-      });
-      await this.connection.getJetStreamClient().publish(subject, this.codec.encode(data), {
-        headers: hdrs,
-        msgID: messageId ?? nuid.next()
-      });
+      await context6.with(
+        spanHandle.activeContext,
+        () => this.connection.getJetStreamClient().publish(subject, encoded, {
+          headers: hdrs,
+          msgID: messageId ?? nuid.next()
+        })
+      );
+      this.reportPublished(declaredPattern, "cmd" /* Command */, startedAt, "success");
     } catch (err) {
       const existingTimeout = this.pendingTimeouts.get(correlationId);
       if (existingTimeout) {
@@ -644,10 +1697,34 @@ var JetstreamClient = class extends ClientProxy {
       if (!this.pendingMessages.has(correlationId)) return;
       this.pendingMessages.delete(correlationId);
       const error = err instanceof Error ? err : new Error("Unknown error");
-      this.logger.error(`JetStream RPC publish error (${subject}):`, err);
+      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"));
@@ -827,7 +1904,7 @@ var MsgpackCodec = class {
 };
 
 // src/connection/connection.provider.ts
-import { Logger as Logger2 } from "@nestjs/common";
+import { Logger as Logger6 } from "@nestjs/common";
 import {
   connect
 } from "@nats-io/transport-node";
@@ -844,6 +1921,10 @@ var ConnectionProvider = class {
   constructor(options, eventBus) {
     this.options = options;
     this.eventBus = eventBus;
+    const derived = deriveOtelAttrs(options);
+    this.otel = derived.otel;
+    this.otelServiceName = derived.serviceName;
+    this.otelEndpoint = derived.serverEndpoint;
     this.nc$ = defer(() => this.getConnection()).pipe(
       shareReplay({ bufferSize: 1, refCount: false })
     );
@@ -856,12 +1937,16 @@ var ConnectionProvider = class {
   nc$;
   /** Live stream of connection status events (no replay). */
   status$;
-  logger = new Logger2("Jetstream:Connection");
+  logger = new Logger6("Jetstream:Connection");
   connection = null;
   connectionPromise = null;
   jsClient = null;
   jsmInstance = null;
   jsmPromise = null;
+  otel;
+  otelServiceName;
+  otelEndpoint;
+  lifecycleSpan = null;
   /**
    * Establish NATS connection. Idempotent — returns cached connection on subsequent calls.
    *
@@ -911,230 +1996,959 @@ var ConnectionProvider = class {
   get unwrap() {
     return this.connection;
   }
-  /**
-   * Gracefully shut down the connection.
-   *
-   * Sequence: drain → wait for close. Falls back to force-close on error.
-   */
-  async shutdown() {
-    if (this.connectionPromise) {
-      try {
-        await this.connectionPromise;
-      } catch {
+  /**
+   * Gracefully shut down the connection.
+   *
+   * Sequence: drain → wait for close. Falls back to force-close on error.
+   */
+  async shutdown() {
+    if (this.connectionPromise) {
+      try {
+        await this.connectionPromise;
+      } catch {
+      }
+    }
+    if (!this.connection || this.connection.isClosed()) return;
+    try {
+      await withShutdownSpan(
+        this.otel,
+        { serviceName: this.otelServiceName, endpoint: this.otelEndpoint },
+        async () => {
+          try {
+            await this.connection?.drain();
+            await this.connection?.closed();
+          } catch {
+            try {
+              await this.connection?.close();
+            } catch {
+            }
+          }
+        }
+      );
+    } finally {
+      this.lifecycleSpan?.finish();
+      this.lifecycleSpan = null;
+      this.connection = null;
+      this.connectionPromise = null;
+      this.jsClient = null;
+      this.jsmInstance = null;
+      this.jsmPromise = null;
+    }
+  }
+  async initJetStreamManager() {
+    try {
+      const nc = await this.getConnection();
+      this.jsmInstance = await jetstreamManager(nc);
+      this.logger.log("JetStream manager initialized");
+      return this.jsmInstance;
+    } finally {
+      this.jsmPromise = null;
+    }
+  }
+  /** Internal: establish the physical connection with reconnect monitoring. */
+  async establish() {
+    try {
+      const nc = await connect({
+        ...DEFAULT_OPTIONS,
+        // Default the NATS connection name to the OTel-derived service name so
+        // `nats server info` lines up with span attributes, but let user-supplied
+        // `connectionOptions.name` win when set.
+        name: this.otelServiceName,
+        ...this.options.connectionOptions,
+        servers: this.options.servers
+      });
+      this.connection = nc;
+      this.logger.log(`NATS connection established: ${nc.getServer()}`);
+      this.eventBus.emit("connect" /* Connect */, nc.getServer());
+      this.lifecycleSpan?.finish();
+      this.lifecycleSpan = beginConnectionLifecycleSpan(this.otel, {
+        serviceName: this.otelServiceName,
+        endpoint: this.otelEndpoint,
+        server: nc.getServer()
+      });
+      this.monitorStatus(nc);
+      return nc;
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("REFUSED")) {
+        throw new Error(`NATS connection refused: ${this.options.servers.join(", ")}`);
+      }
+      throw err;
+    }
+  }
+  /** Handle a single `nc.status()` event, emitting hooks and span events. */
+  handleStatusEvent(status, nc) {
+    switch (status.type) {
+      case "disconnect":
+        this.eventBus.emit("disconnect" /* Disconnect */);
+        this.lifecycleSpan?.recordEvent(EVENT_CONNECTION_DISCONNECTED);
+        break;
+      case "reconnect":
+        this.jsClient = null;
+        this.jsmInstance = null;
+        this.jsmPromise = null;
+        this.eventBus.emit("reconnect" /* Reconnect */, nc.getServer());
+        this.lifecycleSpan?.recordEvent(EVENT_CONNECTION_RECONNECTED, {
+          [ATTR_NATS_CONNECTION_SERVER]: nc.getServer()
+        });
+        break;
+      case "error":
+        this.eventBus.emit(
+          "error" /* Error */,
+          status.error,
+          "connection"
+        );
+        break;
+      case "update":
+      case "ldm":
+      case "reconnecting":
+      case "ping":
+      case "staleConnection":
+      case "forceReconnect":
+      case "slowConsumer":
+      case "close":
+        break;
+      default: {
+        const _exhaustive = status;
+        const unknown = _exhaustive.type ?? "unknown";
+        this.logger.warn(`Unhandled NATS status event: ${unknown}`);
+      }
+    }
+  }
+  /** Subscribe to connection status events and emit hooks. */
+  monitorStatus(nc) {
+    void (async () => {
+      try {
+        for await (const status of nc.status()) {
+          this.handleStatusEvent(status, nc);
+        }
+      } finally {
+        this.lifecycleSpan?.finish();
+        this.lifecycleSpan = null;
+      }
+    })().catch((err) => {
+      this.logger.error("Status monitor error", err);
+    });
+  }
+};
+
+// src/hooks/event-bus.ts
+var EventBus = class {
+  hooks;
+  logger;
+  subscribers = /* @__PURE__ */ new Map();
+  constructor(logger5, hooks) {
+    this.logger = logger5;
+    this.hooks = hooks ?? {};
+  }
+  /**
+   * 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) {
+    this.dispatch(event, args);
+  }
+  /**
+   * Hot-path optimized emit for MessageRouted events.
+   * Avoids rest/spread overhead of the generic `emit()`.
+   */
+  emitMessageRouted(subject, kind) {
+    this.dispatch("messageRouted" /* MessageRouted */, [subject, kind]);
+  }
+  /**
+   * 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 || (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 {
+      const result = hook(...args);
+      if (result && typeof result.catch === "function") {
+        result.catch((err) => {
+          this.logger.error(
+            `Async hook "${event}" rejected: ${err instanceof Error ? err.message : err}`
+          );
+        });
+      }
+    } catch (err) {
+      this.logger.error(
+        `Hook "${event}" threw an error: ${err instanceof Error ? err.message : err}`
+      );
+    }
+  }
+};
+
+// src/health/jetstream.health-indicator.ts
+import { Injectable, Logger as Logger7 } from "@nestjs/common";
+var JetstreamHealthIndicator = class {
+  constructor(connection) {
+    this.connection = connection;
+  }
+  logger = new Logger7("Jetstream:Health");
+  /**
+   * Plain health status check.
+   *
+   * Returns the current connection status without throwing.
+   * Use this for custom health endpoints or monitoring integrations.
+   *
+   * @returns Connection status with server URL and RTT latency.
+   */
+  async check() {
+    const nc = this.connection.unwrap;
+    if (!nc || nc.isClosed()) {
+      return { connected: false, server: null, latency: null };
+    }
+    try {
+      const start = performance.now();
+      await nc.rtt();
+      const latency = Math.round(performance.now() - start);
+      return { connected: true, server: nc.getServer(), latency };
+    } catch (err) {
+      this.logger.warn(`Health check failed: ${err instanceof Error ? err.message : err}`);
+      return { connected: false, server: nc.getServer(), latency: null };
+    }
+  }
+  /**
+   * Terminus-compatible health check.
+   *
+   * Returns `{ [key]: { status: 'up', ... } }` on success.
+   * Throws an error with `{ [key]: { status: 'down', ... } }` on failure.
+   *
+   * The thrown error sets `isHealthCheckError: true` and `causes` — the
+   * duck-type contract that Terminus `HealthCheckExecutor` uses to distinguish
+   * health failures from unexpected exceptions. Works with both Terminus v10
+   * (`instanceof HealthCheckError`) and v11+ (`error?.isHealthCheckError`).
+   *
+   * @param key - Health indicator key (default: `'jetstream'`).
+   * @returns Object with status, server, and latency under the given key.
+   * @throws Error with `isHealthCheckError`, `causes`, and `{ [key]: { status: 'down' } }`.
+   */
+  async isHealthy(key = "jetstream") {
+    const status = await this.check();
+    const details = {
+      status: status.connected ? "up" : "down",
+      server: status.server,
+      latency: status.latency
+    };
+    if (!status.connected) {
+      const causes = { [key]: details };
+      throw Object.assign(new Error("Jetstream health check failed"), {
+        causes,
+        isHealthCheckError: true
+      });
+    }
+    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.connection || this.connection.isClosed()) return;
+    if (this.inFlight !== null) await this.inFlight;
+  }
+  /** @internal Visible for tests. Runs one poll cycle. */
+  async tick() {
+    let jsm;
     try {
-      await this.connection.drain();
-      await this.connection.closed();
+      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 {
-        await this.connection.close();
+        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");
       }
-    } finally {
-      this.connection = null;
-      this.connectionPromise = null;
-      this.jsClient = null;
-      this.jsmInstance = null;
-      this.jsmPromise = null;
-    }
-  }
-  async initJetStreamManager() {
-    try {
-      const nc = await this.getConnection();
-      this.jsmInstance = await jetstreamManager(nc);
-      this.logger.log("JetStream manager initialized");
-      return this.jsmInstance;
-    } finally {
-      this.jsmPromise = null;
     }
   }
-  /** Internal: establish the physical connection with reconnect monitoring. */
-  async establish() {
-    const name = internalName(this.options.name);
-    try {
-      const nc = await connect({
-        ...DEFAULT_OPTIONS,
-        ...this.options.connectionOptions,
-        servers: this.options.servers,
-        name
-      });
-      this.connection = nc;
-      this.logger.log(`NATS connection established: ${nc.getServer()}`);
-      this.eventBus.emit("connect" /* Connect */, nc.getServer());
-      this.monitorStatus(nc);
-      return nc;
-    } catch (err) {
-      if (err instanceof Error && err.message.includes("REFUSED")) {
-        throw new Error(`NATS connection refused: ${this.options.servers.join(", ")}`);
+  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");
       }
-      throw err;
     }
   }
-  /** Subscribe to connection status events and emit hooks. */
-  monitorStatus(nc) {
-    void (async () => {
-      for await (const status of nc.status()) {
-        switch (status.type) {
-          case "disconnect":
-            this.eventBus.emit("disconnect" /* Disconnect */);
-            break;
-          case "reconnect":
-            this.jsClient = null;
-            this.jsmInstance = null;
-            this.jsmPromise = null;
-            this.eventBus.emit("reconnect" /* Reconnect */, nc.getServer());
-            break;
-          case "error":
-            this.eventBus.emit(
-              "error" /* Error */,
-              status.error,
-              "connection"
-            );
-            break;
-          case "update":
-          case "ldm":
-          case "reconnecting":
-          case "ping":
-          case "staleConnection":
-          case "forceReconnect":
-          case "slowConsumer":
-          case "close":
-            break;
-        }
-      }
-    })().catch((err) => {
-      this.logger.error("Status monitor error", err);
-    });
+  recordPollError(target) {
+    this.opts.metrics.metricsPollErrorsTotal.labels({ target }).inc();
   }
 };
 
-// src/hooks/event-bus.ts
-var EventBus = class {
-  hooks;
-  logger;
-  constructor(logger, hooks) {
-    this.logger = logger;
-    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.
-   */
-  emit(event, ...args) {
-    const hook = this.hooks[event];
-    if (!hook) return;
-    this.callHook(event, hook, ...args);
+// 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;
   }
-  /**
-   * 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
+  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;
+  }
   /**
-   * 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.
+   * 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.
    */
-  hasHook(event) {
-    return this.hooks[event] !== void 0;
-  }
-  callHook(event, hook, ...args) {
-    try {
-      const result = hook(...args);
-      if (result && typeof result.catch === "function") {
-        result.catch((err) => {
-          this.logger.error(
-            `Async hook "${event}" rejected: ${err instanceof Error ? err.message : err}`
-          );
-        });
-      }
-    } catch (err) {
-      this.logger.error(
-        `Hook "${event}" threw an error: ${err instanceof Error ? err.message : err}`
-      );
+  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;
   }
 };
+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/health/jetstream.health-indicator.ts
-import { Injectable, Logger as Logger3 } from "@nestjs/common";
-var JetstreamHealthIndicator = class {
-  constructor(connection) {
-    this.connection = connection;
+// 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);
   }
-  logger = new Logger3("Jetstream:Health");
-  /**
-   * Plain health status check.
-   *
-   * Returns the current connection status without throwing.
-   * Use this for custom health endpoints or monitoring integrations.
-   *
-   * @returns Connection status with server URL and RTT latency.
-   */
-  async check() {
-    const nc = this.connection.unwrap;
-    if (!nc || nc.isClosed()) {
-      return { connected: false, server: null, latency: null };
-    }
-    try {
-      const start = performance.now();
-      await nc.rtt();
-      const latency = Math.round(performance.now() - start);
-      return { connected: true, server: nc.getServer(), latency };
-    } catch (err) {
-      this.logger.warn(`Health check failed: ${err instanceof Error ? err.message : err}`);
-      return { connected: false, server: nc.getServer(), latency: null };
+};
+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: [] };
     }
-  }
-  /**
-   * Terminus-compatible health check.
-   *
-   * Returns `{ [key]: { status: 'up', ... } }` on success.
-   * Throws an error with `{ [key]: { status: 'down', ... } }` on failure.
-   *
-   * The thrown error sets `isHealthCheckError: true` and `causes` — the
-   * duck-type contract that Terminus `HealthCheckExecutor` uses to distinguish
-   * health failures from unexpected exceptions. Works with both Terminus v10
-   * (`instanceof HealthCheckError`) and v11+ (`error?.isHealthCheckError`).
-   *
-   * @param key - Health indicator key (default: `'jetstream'`).
-   * @returns Object with status, server, and latency under the given key.
-   * @throws Error with `isHealthCheckError`, `causes`, and `{ [key]: { status: 'down' } }`.
-   */
-  async isHealthy(key = "jetstream") {
-    const status = await this.check();
-    const details = {
-      status: status.connected ? "up" : "down",
-      server: status.server,
-      latency: status.latency
+    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
+      ]
     };
-    if (!status.connected) {
-      const causes = { [key]: details };
-      throw Object.assign(new Error("Jetstream health check failed"), {
-        causes,
-        isHealthCheckError: true
-      });
-    }
-    return { [key]: details };
   }
 };
-JetstreamHealthIndicator = __decorateClass([
-  Injectable()
-], JetstreamHealthIndicator);
+JetstreamMetricsModule = __decorateClass([
+  Module({})
+], JetstreamMetricsModule);
 
 // src/server/strategy.ts
 import { Server } from "@nestjs/microservices";
@@ -1210,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).
    *
@@ -1282,7 +3116,7 @@ var JetstreamStrategy = class extends Server {
 };
 
 // src/server/core-rpc.server.ts
-import { Logger as Logger4 } from "@nestjs/common";
+import { Logger as Logger11 } from "@nestjs/common";
 import { headers as natsHeaders2 } from "@nats-io/transport-node";
 
 // src/context/rpc.context.ts
@@ -1292,9 +3126,6 @@ var RpcContext = class extends BaseRpcContext {
   _retryDelay;
   _shouldTerminate = false;
   _terminateReason;
-  // ---------------------------------------------------------------------------
-  // Message accessors
-  // ---------------------------------------------------------------------------
   /**
    * Get the underlying NATS message.
    *
@@ -1329,9 +3160,6 @@ var RpcContext = class extends BaseRpcContext {
   isJetStream() {
     return "ack" in this.args[0];
   }
-  // ---------------------------------------------------------------------------
-  // JetStream metadata (return undefined for Core NATS messages)
-  // ---------------------------------------------------------------------------
   /** How many times this message has been delivered. */
   getDeliveryCount() {
     return this.asJetStream()?.info.deliveryCount;
@@ -1353,9 +3181,6 @@ var RpcContext = class extends BaseRpcContext {
   getCallerName() {
     return this.getHeader("x-caller-name" /* CallerName */);
   }
-  // ---------------------------------------------------------------------------
-  // Handler-controlled settlement
-  // ---------------------------------------------------------------------------
   /**
    * Signal the transport to retry (nak) this message instead of acknowledging it.
    *
@@ -1400,9 +3225,6 @@ var RpcContext = class extends BaseRpcContext {
       throw new Error(`${method}() is only available for JetStream messages`);
     }
   }
-  // ---------------------------------------------------------------------------
-  // Transport-facing state (read by EventRouter)
-  // ---------------------------------------------------------------------------
   /** @internal */
   get shouldRetry() {
     return this._shouldRetry;
@@ -1524,7 +3346,7 @@ var unwrapResult = (result) => {
   }
   return result;
 };
-var isPromiseLike = (value) => value !== null && typeof value === "object" && typeof value.then === "function";
+var isPromiseLike2 = (value) => value !== null && typeof value === "object" && typeof value.then === "function";
 var subscribeToFirst = (obs) => new Promise((resolve, reject) => {
   let done = false;
   let subscription = null;
@@ -1554,20 +3376,25 @@ var subscribeToFirst = (obs) => new Promise((resolve, reject) => {
 // src/server/core-rpc.server.ts
 var CoreRpcServer = class {
   constructor(options, connection, patternRegistry, codec, eventBus) {
-    this.options = options;
     this.connection = connection;
     this.patternRegistry = patternRegistry;
     this.codec = codec;
     this.eventBus = eventBus;
+    const derived = deriveOtelAttrs(options);
+    this.otel = derived.otel;
+    this.serviceName = derived.serviceName;
+    this.serverEndpoint = derived.serverEndpoint;
   }
-  logger = new Logger4("Jetstream:CoreRpc");
+  logger = new Logger11("Jetstream:CoreRpc");
   subscription = null;
+  otel;
+  serviceName;
+  serverEndpoint;
   /** Start listening for RPC requests on the command subject. */
   async start() {
     const nc = await this.connection.getConnection();
-    const serviceName = internalName(this.options.name);
-    const subject = `${serviceName}.cmd.>`;
-    const queue = `${serviceName}_cmd_queue`;
+    const subject = `${this.serviceName}.cmd.>`;
+    const queue = `${this.serviceName}_cmd_queue`;
     this.subscription = nc.subscribe(subject, {
       queue,
       callback: (err, msg) => {
@@ -1611,15 +3438,51 @@ var CoreRpcServer = class {
       return;
     }
     const ctx = new RpcContext([msg]);
+    const startedAt = performance.now();
     try {
-      const raw = unwrapResult(handler(data, ctx));
-      const result = isPromiseLike(raw) ? await raw : raw;
-      msg.respond(this.codec.encode(result));
+      const raw = await withConsumeSpan(
+        {
+          subject: msg.subject,
+          msg,
+          kind: "rpc" /* Rpc */,
+          payloadBytes: msg.data.length,
+          handlerMetadata: { pattern: msg.subject },
+          serviceName: this.serviceName,
+          endpoint: this.serverEndpoint
+        },
+        this.otel,
+        () => {
+          const out = unwrapResult(handler(data, ctx));
+          return isPromiseLike2(out) ? out : out;
+        }
+      );
+      msg.respond(this.codec.encode(raw));
+      this.reportHandlerCompleted(msg, startedAt, "success");
     } catch (err) {
-      this.logger.error(`Handler error for Core RPC ${msg.subject}:`, err);
+      this.eventBus.emit(
+        "error" /* Error */,
+        err instanceof Error ? err : new Error(String(err)),
+        `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) {
     try {
@@ -1633,7 +3496,7 @@ var CoreRpcServer = class {
 };
 
 // src/server/infrastructure/stream.provider.ts
-import { Logger as Logger6 } 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
@@ -1700,7 +3563,7 @@ var isEqual = (a, b) => {
 };
 
 // src/server/infrastructure/stream-migration.ts
-import { Logger as Logger5 } 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;
@@ -1709,7 +3572,7 @@ var StreamMigration = class {
   constructor(sourcingTimeoutMs = DEFAULT_SOURCING_TIMEOUT_MS) {
     this.sourcingTimeoutMs = sourcingTimeoutMs;
   }
-  logger = new Logger5("Jetstream:Stream");
+  logger = new Logger12("Jetstream:Stream");
   async migrate(jsm, streamName2, newConfig) {
     const backupName = `${streamName2}${MIGRATION_BACKUP_SUFFIX}`;
     const startTime = Date.now();
@@ -1791,9 +3654,16 @@ var StreamProvider = class {
   constructor(options, connection) {
     this.options = options;
     this.connection = connection;
+    const derived = deriveOtelAttrs(options);
+    this.otel = derived.otel;
+    this.otelServiceName = derived.serviceName;
+    this.otelEndpoint = derived.serverEndpoint;
   }
-  logger = new Logger6("Jetstream:Stream");
+  logger = new Logger13("Jetstream:Stream");
   migration = new StreamMigration();
+  otel;
+  otelServiceName;
+  otelEndpoint;
   /**
    * Ensure all required streams exist with correct configuration.
    *
@@ -1839,32 +3709,56 @@ var StreamProvider = class {
   /** Ensure a single stream exists, creating or updating as needed. */
   async ensureStream(jsm, kind) {
     const config = this.buildConfig(kind);
-    this.logger.log(`Ensuring stream: ${config.name}`);
-    try {
-      const currentInfo = await jsm.streams.info(config.name);
-      return await this.handleExistingStream(jsm, currentInfo, config);
-    } catch (err) {
-      if (err instanceof JetStreamApiError2 && err.apiError().err_code === 10059 /* StreamNotFound */) {
-        this.logger.log(`Creating stream: ${config.name}`);
-        return await jsm.streams.add(config);
+    return withProvisioningSpan(
+      this.otel,
+      {
+        serviceName: this.otelServiceName,
+        endpoint: this.otelEndpoint,
+        entity: "stream",
+        name: config.name,
+        action: "ensure"
+      },
+      async () => {
+        this.logger.log(`Ensuring stream: ${config.name}`);
+        try {
+          const currentInfo = await jsm.streams.info(config.name);
+          return await this.handleExistingStream(jsm, currentInfo, config);
+        } catch (err) {
+          if (err instanceof JetStreamApiError2 && err.apiError().err_code === 10059 /* StreamNotFound */) {
+            this.logger.log(`Creating stream: ${config.name}`);
+            return await jsm.streams.add(config);
+          }
+          throw err;
+        }
       }
-      throw err;
-    }
+    );
   }
   /** Ensure a dead-letter queue stream exists, creating or updating as needed. */
   async ensureDlqStream(jsm) {
     const config = this.buildDlqConfig();
-    this.logger.log(`Ensuring DLQ stream: ${config.name}`);
-    try {
-      const currentInfo = await jsm.streams.info(config.name);
-      return await this.handleExistingStream(jsm, currentInfo, config);
-    } catch (err) {
-      if (err instanceof JetStreamApiError2 && err.apiError().err_code === 10059 /* StreamNotFound */) {
-        this.logger.log(`Creating DLQ stream: ${config.name}`);
-        return await jsm.streams.add(config);
+    return withProvisioningSpan(
+      this.otel,
+      {
+        serviceName: this.otelServiceName,
+        endpoint: this.otelEndpoint,
+        entity: "stream",
+        name: config.name,
+        action: "ensure"
+      },
+      async () => {
+        this.logger.log(`Ensuring DLQ stream: ${config.name}`);
+        try {
+          const currentInfo = await jsm.streams.info(config.name);
+          return await this.handleExistingStream(jsm, currentInfo, config);
+        } catch (err) {
+          if (err instanceof JetStreamApiError2 && err.apiError().err_code === 10059 /* StreamNotFound */) {
+            this.logger.log(`Creating DLQ stream: ${config.name}`);
+            return await jsm.streams.add(config);
+          }
+          throw err;
+        }
       }
-      throw err;
-    }
+    );
   }
   async handleExistingStream(jsm, currentInfo, config) {
     const diff = compareStreamConfig(currentInfo.config, config);
@@ -1893,7 +3787,18 @@ var StreamProvider = class {
       }
       return currentInfo;
     }
-    await this.migration.migrate(jsm, config.name, config);
+    await withMigrationSpan(
+      this.otel,
+      {
+        serviceName: this.otelServiceName,
+        endpoint: this.otelEndpoint,
+        stream: config.name,
+        reason: diff.changes.filter((c) => c.mutability === "immutable").map((c) => c.property).join(", ")
+      },
+      async () => {
+        await this.migration.migrate(jsm, config.name, config);
+      }
+    );
     return await jsm.streams.info(config.name);
   }
   buildMutableOnlyConfig(config, currentConfig, diff) {
@@ -2009,7 +3914,7 @@ var StreamProvider = class {
 };
 
 // src/server/infrastructure/consumer.provider.ts
-import { Logger as Logger7 } 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) {
@@ -2017,8 +3922,15 @@ var ConsumerProvider = class {
     this.connection = connection;
     this.streamProvider = streamProvider;
     this.patternRegistry = patternRegistry;
-  }
-  logger = new Logger7("Jetstream:Consumer");
+    const derived = deriveOtelAttrs(options);
+    this.otel = derived.otel;
+    this.otelServiceName = derived.serviceName;
+    this.otelEndpoint = derived.serverEndpoint;
+  }
+  logger = new Logger14("Jetstream:Consumer");
+  otel;
+  otelServiceName;
+  otelEndpoint;
   /**
    * Ensure consumers exist for the specified kinds.
    *
@@ -2048,17 +3960,29 @@ var ConsumerProvider = class {
     const stream = this.streamProvider.getStreamName(kind);
     const config = this.buildConfig(kind);
     const name = config.durable_name;
-    this.logger.log(`Ensuring consumer: ${name} on stream: ${stream}`);
-    try {
-      await jsm.consumers.info(stream, name);
-      this.logger.debug(`Consumer exists, updating: ${name}`);
-      return await jsm.consumers.update(stream, name, config);
-    } catch (err) {
-      if (!(err instanceof JetStreamApiError3) || err.apiError().err_code !== 10014 /* ConsumerNotFound */) {
-        throw err;
+    return withProvisioningSpan(
+      this.otel,
+      {
+        serviceName: this.otelServiceName,
+        endpoint: this.otelEndpoint,
+        entity: "consumer",
+        name,
+        action: "ensure"
+      },
+      async () => {
+        this.logger.log(`Ensuring consumer: ${name} on stream: ${stream}`);
+        try {
+          await jsm.consumers.info(stream, name);
+          this.logger.debug(`Consumer exists, updating: ${name}`);
+          return await jsm.consumers.update(stream, name, config);
+        } catch (err) {
+          if (!(err instanceof JetStreamApiError3) || err.apiError().err_code !== 10014 /* ConsumerNotFound */) {
+            throw err;
+          }
+          return await this.createConsumer(jsm, stream, name, config);
+        }
       }
-      return await this.createConsumer(jsm, stream, name, config);
-    }
+    );
   }
   /**
    * Recover a consumer that disappeared during runtime.
@@ -2077,16 +4001,28 @@ var ConsumerProvider = class {
     const stream = this.streamProvider.getStreamName(kind);
     const config = this.buildConfig(kind);
     const name = config.durable_name;
-    this.logger.log(`Recovering consumer: ${name} on stream: ${stream}`);
-    await this.assertNoMigrationInProgress(jsm, stream);
-    try {
-      return await jsm.consumers.info(stream, name);
-    } catch (err) {
-      if (!(err instanceof JetStreamApiError3) || err.apiError().err_code !== 10014 /* ConsumerNotFound */) {
-        throw err;
+    return withProvisioningSpan(
+      this.otel,
+      {
+        serviceName: this.otelServiceName,
+        endpoint: this.otelEndpoint,
+        entity: "consumer",
+        name,
+        action: "recover"
+      },
+      async () => {
+        this.logger.log(`Recovering consumer: ${name} on stream: ${stream}`);
+        await this.assertNoMigrationInProgress(jsm, stream);
+        try {
+          return await jsm.consumers.info(stream, name);
+        } catch (err) {
+          if (!(err instanceof JetStreamApiError3) || err.apiError().err_code !== 10014 /* ConsumerNotFound */) {
+            throw err;
+          }
+          return await this.createConsumer(jsm, stream, name, config);
+        }
       }
-      return await this.createConsumer(jsm, stream, name, config);
-    }
+    );
   }
   /**
    * Throw if a migration backup stream exists for this stream.
@@ -2202,7 +4138,7 @@ var ConsumerProvider = class {
 };
 
 // src/server/infrastructure/message.provider.ts
-import { Logger as Logger8 } from "@nestjs/common";
+import { Logger as Logger15 } from "@nestjs/common";
 import { DeliverPolicy as DeliverPolicy2 } from "@nats-io/jetstream";
 import {
   catchError,
@@ -2212,7 +4148,6 @@ import {
   repeat,
   Subject,
   takeUntil,
-  tap,
   timer
 } from "rxjs";
 var MessageProvider = class {
@@ -2222,7 +4157,7 @@ var MessageProvider = class {
     this.consumeOptionsMap = consumeOptionsMap;
     this.consumerRecoveryFn = consumerRecoveryFn;
   }
-  logger = new Logger8("Jetstream:Message");
+  logger = new Logger15("Jetstream:Message");
   activeIterators = /* @__PURE__ */ new Set();
   orderedReadyResolve = null;
   orderedReadyReject = null;
@@ -2320,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;
@@ -2351,6 +4289,7 @@ var MessageProvider = class {
     });
     this.activeIterators.add(messages);
     this.monitorConsumerHealth(messages, consumerName2);
+    onConnected();
     try {
       await messages.closed();
     } finally {
@@ -2405,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) {
@@ -2419,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);
@@ -2445,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$;
@@ -2460,6 +4404,7 @@ var MessageProvider = class {
       this.orderedReadyReject = null;
     }
     this.activeIterators.add(messages);
+    onConnected();
     try {
       await messages.closed();
     } finally {
@@ -2469,7 +4414,7 @@ var MessageProvider = class {
 };
 
 // src/server/infrastructure/metadata.provider.ts
-import { Logger as Logger9 } from "@nestjs/common";
+import { Logger as Logger16 } from "@nestjs/common";
 import { Kvm } from "@nats-io/kv";
 var MetadataProvider = class {
   constructor(options, connection) {
@@ -2478,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 Logger9("Jetstream:Metadata");
+  logger = new Logger16("Jetstream:Metadata");
   bucketName;
   replicas;
   ttl;
@@ -2570,177 +4515,14 @@ var MetadataProvider = class {
   }
 };
 
-// src/server/routing/pattern-registry.ts
-import { Logger as Logger10 } 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 Logger10("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 Logger11 } 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 */;
+  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;
@@ -2752,9 +4534,22 @@ var EventRouter = class {
     this.ackWaitMap = ackWaitMap;
     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;
+    }
   }
-  logger = new Logger11("Jetstream:EventRouter");
+  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.
@@ -2784,13 +4579,24 @@ var EventRouter = class {
     const patternRegistry = this.patternRegistry;
     const codec = this.codec;
     const eventBus = this.eventBus;
-    const logger = this.logger;
+    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 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);
@@ -2816,7 +4622,7 @@ var EventRouter = class {
         const handler = patternRegistry.getHandler(subject);
         if (!handler) {
           msg.term(`No handler for event: ${subject}`);
-          logger.error(`No handler for subject: ${subject}`);
+          logger5.error(`No handler for subject: ${subject}`);
           return null;
         }
         let data;
@@ -2824,47 +4630,79 @@ var EventRouter = class {
           data = codec.decode(msg.data);
         } catch (err) {
           msg.term("Decode error");
-          logger.error(`Decode error for ${subject}:`, err);
+          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) {
-        logger.error(`Unexpected error in ${kind} event router`, err);
+        logger5.error(`Unexpected error in ${kind} event router`, err);
         try {
           msg.term("Unexpected router error");
         } catch (termErr) {
-          logger.error(`Failed to terminate message ${subject}:`, termErr);
+          logger5.error(`Failed to terminate message ${subject}:`, termErr);
         }
         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 = unwrapResult(handler(data, ctx));
+        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) {
-        logger.error(`Event handler error (${msg.subject}) in ${kind} router:`, err);
-        if (stopAckExtension !== null) stopAckExtension();
-        return settleFailure(msg, data, 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 (!isPromiseLike(pending)) {
+      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) => {
-          logger.error(`Event handler error (${msg.subject}) in ${kind} router:`, 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 {
@@ -2880,42 +4718,65 @@ var EventRouter = class {
       try {
         handler = patternRegistry.getHandler(subject);
         if (!handler) {
-          logger.error(`No handler for subject: ${subject}`);
+          logger5.error(`No handler for subject: ${subject}`);
           return void 0;
         }
         try {
           data = codec.decode(msg.data);
         } catch (err) {
-          logger.error(`Decode error for ${subject}:`, err);
+          logger5.error(`Decode error for ${subject}:`, err);
           return void 0;
         }
-        if (emitRouted) eventBus.emitMessageRouted(subject, "event" /* Event */);
+        eventBus.emitMessageRouted(subject, "event" /* Event */);
       } catch (err) {
-        logger.error(`Ordered handler error (${subject}):`, err);
+        logger5.error(`Ordered handler error (${subject}):`, err);
         return void 0;
       }
       const ctx = new RpcContext([msg]);
       const warnIfSettlementAttempted = () => {
         if (ctx.shouldRetry || ctx.shouldTerminate) {
-          logger.warn(
+          logger5.warn(
             `retry()/terminate() ignored for ordered message ${subject} \u2014 ordered consumers auto-acknowledge`
           );
         }
       };
+      const startedAt = performance.now();
       let pending;
       try {
-        pending = unwrapResult(handler(data, ctx));
+        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) {
-        logger.error(`Ordered handler error (${subject}):`, err);
+        logger5.error(`Ordered handler error (${subject}):`, err);
+        reportHandlerCompleted(msg, startedAt, "error");
         return void 0;
       }
-      if (!isPromiseLike(pending)) {
+      if (!isPromiseLike2(pending)) {
         warnIfSettlementAttempted();
+        reportHandlerCompleted(msg, startedAt, "success");
         return void 0;
       }
-      return pending.then(warnIfSettlementAttempted, (err) => {
-        logger.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;
@@ -2947,7 +4808,7 @@ var EventRouter = class {
           backlog.push(msg);
           if (!backlogWarned && backlog.length >= backlogWarnThreshold) {
             backlogWarned = true;
-            logger.warn(
+            logger5.warn(
               `${kind} backlog reached ${backlog.length} messages \u2014 consumer may be falling behind`
             );
           }
@@ -2963,7 +4824,7 @@ var EventRouter = class {
         }
       },
       error: (err) => {
-        logger.error(`Stream error in ${kind} router`, err);
+        logger5.error(`Stream error in ${kind} router`, err);
       }
     });
     this.subscriptions.push(subscription);
@@ -2978,14 +4839,11 @@ var EventRouter = class {
     if (kind === "broadcast" /* Broadcast */) return this.processingConfig?.broadcast?.ackExtension;
     return void 0;
   }
-  /** Handle a dead letter: invoke callback, then term or nak based on result. */
   /**
-   * Fallback execution for a dead letter when DLQ is disabled, or when
-   * publishing to the DLQ stream fails (due to network or NATS errors).
-   *
-   * Triggers the user-provided `onDeadLetter` hook for logging/alerting.
-   * On success, terminates the message. On error, leaves it unacknowledged (nak)
-   * so NATS can retry the delivery on the next cycle.
+   * Last-resort path for a dead letter: invoke `onDeadLetter`, then `term` on
+   * success or `nak` on hook failure so NATS retries on the next delivery
+   * cycle. Used when DLQ stream isn't configured, or when publishing to it
+   * failed and we still have to surface the message somewhere observable.
    */
   async fallbackToOnDeadLetterCallback(info, msg) {
     if (!this.deadLetterConfig) {
@@ -3077,20 +4935,37 @@ var EventRouter = class {
       streamSequence: msg.info.streamSequence,
       timestamp: new Date(msg.info.timestampNanos / 1e6).toISOString()
     };
-    this.eventBus.emit("deadLetter" /* DeadLetter */, info);
-    if (!this.options?.dlq) {
-      await this.fallbackToOnDeadLetterCallback(info, msg);
-    } else {
-      await this.publishToDlq(msg, info, error);
-    }
+    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 Logger12 } 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) {
+  constructor(messageProvider, patternRegistry, connection, codec, eventBus, rpcOptions, ackWaitMap, options) {
     this.messageProvider = messageProvider;
     this.patternRegistry = patternRegistry;
     this.connection = connection;
@@ -3100,13 +4975,26 @@ var RpcRouter = class {
     this.ackWaitMap = ackWaitMap;
     this.timeout = rpcOptions?.timeout ?? DEFAULT_JETSTREAM_RPC_TIMEOUT;
     this.concurrency = rpcOptions?.concurrency;
+    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;
+    }
   }
-  logger = new Logger12("Jetstream:RpcRouter");
+  logger = new Logger18("Jetstream:RpcRouter");
   timeout;
   concurrency;
   resolvedAckExtensionInterval;
   subscription = null;
   cachedNc = null;
+  otel;
+  serviceName;
+  serverEndpoint;
   /** Lazily resolve the ack extension interval (needs ackWaitMap populated at runtime). */
   get ackExtensionInterval() {
     if (this.resolvedAckExtensionInterval !== void 0) return this.resolvedAckExtensionInterval;
@@ -3123,21 +5011,37 @@ var RpcRouter = class {
     const patternRegistry = this.patternRegistry;
     const codec = this.codec;
     const eventBus = this.eventBus;
-    const logger = this.logger;
+    const logger5 = this.logger;
     const timeout = this.timeout;
     const ackExtensionInterval = this.ackExtensionInterval;
     const hasAckExtension = ackExtensionInterval !== null && ackExtensionInterval > 0;
     const maxActive = this.concurrency ?? Number.POSITIVE_INFINITY;
+    const otel = this.otel;
+    const serviceName = this.serviceName;
+    const serverEndpoint = this.serverEndpoint;
     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();
         hdrs.set("x-correlation-id" /* CorrelationId */, correlationId);
         nc.publish(replyTo, codec.encode(payload), { headers: hdrs });
       } catch (publishErr) {
-        logger.error(`Failed to publish RPC response`, publishErr);
+        logger5.error(`Failed to publish RPC response`, publishErr);
       }
     };
     const publishErrorReply = (replyTo, correlationId, subject, err) => {
@@ -3147,7 +5051,7 @@ var RpcRouter = class {
         hdrs.set("x-error" /* Error */, "true");
         nc.publish(replyTo, codec.encode(serializeError(err)), { headers: hdrs });
       } catch (encodeErr) {
-        logger.error(`Failed to encode RPC error for ${subject}`, encodeErr);
+        logger5.error(`Failed to encode RPC error for ${subject}`, encodeErr);
       }
     };
     const resolveCommand = (msg) => {
@@ -3156,7 +5060,7 @@ var RpcRouter = class {
         const handler = patternRegistry.getHandler(subject);
         if (!handler) {
           msg.term(`No handler for RPC: ${subject}`);
-          logger.error(`No handler for RPC subject: ${subject}`);
+          logger5.error(`No handler for RPC subject: ${subject}`);
           return null;
         }
         const msgHeaders = msg.headers;
@@ -3164,7 +5068,7 @@ var RpcRouter = class {
         const correlationId = msgHeaders?.get("x-correlation-id" /* CorrelationId */);
         if (!replyTo || !correlationId) {
           msg.term("Missing required headers (reply-to or correlation-id)");
-          logger.error(`Missing headers for RPC: ${subject}`);
+          logger5.error(`Missing headers for RPC: ${subject}`);
           return null;
         }
         let data;
@@ -3172,17 +5076,17 @@ var RpcRouter = class {
           data = codec.decode(msg.data);
         } catch (err) {
           msg.term("Decode error");
-          logger.error(`Decode error for RPC ${subject}:`, err);
+          logger5.error(`Decode error for RPC ${subject}:`, err);
           return null;
         }
         eventBus.emitMessageRouted(subject, "rpc" /* Rpc */);
         return { handler, data, replyTo, correlationId };
       } catch (err) {
-        logger.error("Unexpected error in RPC router", err);
+        logger5.error("Unexpected error in RPC router", err);
         try {
           msg.term("Unexpected router error");
         } catch (termErr) {
-          logger.error(`Failed to terminate RPC message ${subject}:`, termErr);
+          logger5.error(`Failed to terminate RPC message ${subject}:`, termErr);
         }
         return null;
       }
@@ -3194,20 +5098,45 @@ 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 */,
+          err instanceof Error ? err : new Error(String(err)),
+          `rpc-handler:${subject}`
+        );
+        publishErrorReply(replyTo, correlationId, subject, err);
+        msg.term(`Handler error: ${subject}`);
+      };
+      const abortController = new AbortController();
       let pending;
       try {
-        pending = unwrapResult(handler(data, ctx));
+        pending = withConsumeSpan(
+          {
+            subject,
+            msg,
+            info: msg.info,
+            kind: "rpc" /* Rpc */,
+            payloadBytes: msg.data.length,
+            handlerMetadata: { pattern: subject },
+            serviceName,
+            endpoint: serverEndpoint
+          },
+          otel,
+          () => unwrapResult(handler(data, ctx)),
+          { signal: abortController.signal, timeoutLabel: "rpc.handler.timeout" }
+        );
       } catch (err) {
         if (stopAckExtension !== null) stopAckExtension();
-        logger.error(`RPC handler error (${subject}):`, err);
-        publishErrorReply(replyTo, correlationId, subject, err);
-        msg.term(`Handler error: ${subject}`);
+        reportHandlerError(err);
+        reportHandlerCompleted(msg, startedAt, "error");
         return void 0;
       }
-      if (!isPromiseLike(pending)) {
+      if (!isPromiseLike2(pending)) {
         if (stopAckExtension !== null) stopAckExtension();
         msg.ack();
         publishReply(replyTo, correlationId, pending);
+        reportHandlerCompleted(msg, startedAt, "success");
         return void 0;
       }
       let settled = false;
@@ -3215,9 +5144,10 @@ var RpcRouter = class {
         if (settled) return;
         settled = true;
         if (stopAckExtension !== null) stopAckExtension();
-        logger.error(`RPC timeout (${timeout}ms): ${subject}`);
+        abortController.abort();
         emitRpcTimeout(subject, correlationId);
         msg.term("Handler timeout");
+        reportHandlerCompleted(msg, startedAt, "terminated");
       }, timeout);
       return pending.then(
         (result) => {
@@ -3227,15 +5157,15 @@ var RpcRouter = class {
           if (stopAckExtension !== null) stopAckExtension();
           msg.ack();
           publishReply(replyTo, correlationId, result);
+          reportHandlerCompleted(msg, startedAt, "success");
         },
         (err) => {
           if (settled) return;
           settled = true;
           clearTimeout(timeoutId);
           if (stopAckExtension !== null) stopAckExtension();
-          logger.error(`RPC handler error (${subject}):`, err);
-          publishErrorReply(replyTo, correlationId, subject, err);
-          msg.term(`Handler error: ${subject}`);
+          reportHandlerError(err);
+          reportHandlerCompleted(msg, startedAt, "error");
         }
       );
     };
@@ -3267,7 +5197,7 @@ var RpcRouter = class {
           backlog.push(msg);
           if (!backlogWarned && backlog.length >= backlogWarnThreshold) {
             backlogWarned = true;
-            logger.warn(
+            logger5.warn(
               `RPC backlog reached ${backlog.length} messages \u2014 consumer may be falling behind`
             );
           }
@@ -3283,7 +5213,7 @@ var RpcRouter = class {
         }
       },
       error: (err) => {
-        logger.error("Stream error in RPC router", err);
+        logger5.error("Stream error in RPC router", err);
       }
     });
   }
@@ -3295,14 +5225,14 @@ var RpcRouter = class {
 };
 
 // src/shutdown/shutdown.manager.ts
-import { Logger as Logger13 } 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 Logger13("Jetstream:Shutdown");
+  logger = new Logger19("Jetstream:Shutdown");
   shutdownPromise;
   /**
    * Execute the full shutdown sequence.
@@ -3342,9 +5272,6 @@ var JetstreamModule = class {
     this.shutdownManager = shutdownManager;
     this.strategy = strategy;
   }
-  // -------------------------------------------------------------------
-  // forRoot — global module registration
-  // -------------------------------------------------------------------
   /**
    * Register the JetStream transport globally.
    *
@@ -3359,21 +5286,20 @@ 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
       ]
     };
   }
-  // -------------------------------------------------------------------
-  // forRootAsync — async global module registration
-  // -------------------------------------------------------------------
   /**
    * Register the JetStream transport globally with async configuration.
    *
@@ -3386,25 +5312,24 @@ 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
       ]
     };
   }
-  // -------------------------------------------------------------------
-  // forFeature — per-module client registration
-  // -------------------------------------------------------------------
   /**
    * Register a lightweight client proxy for a target service.
    *
@@ -3430,9 +5355,6 @@ var JetstreamModule = class {
       exports: [clientToken]
     };
   }
-  // -------------------------------------------------------------------
-  // Provider factories
-  // -------------------------------------------------------------------
   static createCoreProviders(options) {
     return [
       {
@@ -3450,8 +5372,8 @@ var JetstreamModule = class {
         provide: JETSTREAM_EVENT_BUS,
         inject: [JETSTREAM_OPTIONS],
         useFactory: (options) => {
-          const logger = new Logger14("Jetstream:Module");
-          return new EventBus(logger, options.hooks);
+          const logger5 = new Logger20("Jetstream:Module");
+          return new EventBus(logger5, options.hooks);
         }
       },
       // Codec — global encode/decode
@@ -3490,10 +5412,8 @@ 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
       {
         provide: PatternRegistry,
@@ -3529,8 +5449,14 @@ var JetstreamModule = class {
       // MessageProvider — pull-based message consumption
       {
         provide: MessageProvider,
-        inject: [JETSTREAM_OPTIONS, JETSTREAM_CONNECTION, JETSTREAM_EVENT_BUS, ConsumerProvider],
-        useFactory: (options, connection, eventBus, consumerProvider) => {
+        inject: [
+          JETSTREAM_OPTIONS,
+          JETSTREAM_CONNECTION,
+          JETSTREAM_EVENT_BUS,
+          ConsumerProvider,
+          StreamProvider
+        ],
+        useFactory: (options, connection, eventBus, consumerProvider, streamProvider) => {
           if (options.consumer === false) return null;
           const consumeOptionsMap = /* @__PURE__ */ new Map();
           if (options.events?.consume)
@@ -3540,10 +5466,22 @@ var JetstreamModule = class {
           if (options.rpc?.mode === "jetstream" && options.rpc.consume) {
             consumeOptionsMap.set("cmd" /* Command */, options.rpc.consume);
           }
-          const consumerRecoveryFn = consumerProvider ? async (kind) => {
-            const jsm = await connection.getJetStreamManager();
-            return consumerProvider.recoverConsumer(jsm, kind);
-          } : void 0;
+          const derived = deriveOtelAttrs(options);
+          const { otel, serverEndpoint: otelEndpoint, serviceName: otelServiceName } = derived;
+          const consumerRecoveryFn = consumerProvider && streamProvider ? async (kind) => withSelfHealingSpan(
+            otel,
+            {
+              serviceName: otelServiceName,
+              endpoint: otelEndpoint,
+              consumer: consumerProvider.getConsumerName(kind),
+              stream: streamProvider.getStreamName(kind),
+              reason: "consumer not found"
+            },
+            async () => {
+              const jsm = await connection.getJetStreamManager();
+              return consumerProvider.recoverConsumer(jsm, kind);
+            }
+          ) : void 0;
           return new MessageProvider(connection, eventBus, consumeOptionsMap, consumerRecoveryFn);
         }
       },
@@ -3614,7 +5552,8 @@ var JetstreamModule = class {
             codec,
             eventBus,
             rpcOptions,
-            ackWaitMap
+            ackWaitMap,
+            options
           );
         }
       },
@@ -3717,9 +5656,6 @@ var JetstreamModule = class {
       }
     ];
   }
-  // -------------------------------------------------------------------
-  // Lifecycle hooks
-  // -------------------------------------------------------------------
   /**
    * Gracefully shut down the transport on application termination.
    */
@@ -3731,13 +5667,14 @@ 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,
   DEFAULT_BROADCAST_CONSUMER_CONFIG,
   DEFAULT_BROADCAST_STREAM_CONFIG,
   DEFAULT_COMMAND_CONSUMER_CONFIG,
@@ -3753,6 +5690,7 @@ export {
   DEFAULT_ORDERED_STREAM_CONFIG,
   DEFAULT_RPC_TIMEOUT,
   DEFAULT_SHUTDOWN_TIMEOUT,
+  DEFAULT_TRACES,
   JETSTREAM_CODEC,
   JETSTREAM_CONNECTION,
   JETSTREAM_OPTIONS,
@@ -3764,15 +5702,18 @@ export {
   JetstreamRecord,
   JetstreamRecordBuilder,
   JetstreamStrategy,
+  JetstreamTrace,
   JsonCodec,
   MIN_METADATA_TTL,
   MessageKind,
   MsgpackCodec,
   NatsErrorCode,
   PatternPrefix,
+  PublishKind,
   RESERVED_HEADERS,
   RpcContext,
   StreamKind,
+  TRACER_NAME,
   TransportEvent,
   buildBroadcastSubject,
   buildSubject,