@bymax-one/nest-core 1.0.0 → 1.1.0

package/dist/index.cjs

@@ -16,10 +16,23 @@ var __decorateClass = (decorators, target, key, kind) => {
 };
 var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
 
+// src/runtime.environment.ts
+var NON_PRODUCTION_ENVIRONMENTS = /* @__PURE__ */ new Set(["development", "test"]);
+function isProductionRuntime(value = process.env["NODE_ENV"]) {
+  if (value === void 0) {
+    return true;
+  }
+  return !NON_PRODUCTION_ENVIRONMENTS.has(value.trim().toLowerCase());
+}
+
 // src/core.options.ts
 var DEFAULT_HEALTH_PATH = "health";
 var DEFAULT_INDICATOR_TIMEOUT_MS = 5e3;
 var DEFAULT_METRICS_PATH = "metrics";
+var DEFAULT_OPENAPI_PATH = "docs";
+var DEFAULT_OPENAPI_JSON_PATH = "docs-json";
+var DEFAULT_OPENAPI_TITLE = "API";
+var DEFAULT_OPENAPI_VERSION = "1.0.0";
 function deepFreeze(value) {
   if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
     Object.freeze(value);
@@ -44,7 +57,9 @@ function resolveHealth(raw) {
   return {
     enabled: raw?.enabled ?? true,
     path: raw?.path ?? DEFAULT_HEALTH_PATH,
-    indicatorTimeoutMs: raw?.indicatorTimeoutMs ?? DEFAULT_INDICATOR_TIMEOUT_MS
+    exposeIndicatorErrors: raw?.exposeIndicatorErrors ?? false,
+    indicatorTimeoutMs: raw?.indicatorTimeoutMs ?? DEFAULT_INDICATOR_TIMEOUT_MS,
+    autoDiscover: raw?.autoDiscover ?? false
   };
 }
 function resolveMetrics(raw) {
@@ -55,12 +70,44 @@ function resolveMetrics(raw) {
     defaultLabels: { ...raw?.defaultLabels ?? {} }
   };
 }
+function cloneServers(raw) {
+  return (raw ?? []).map(
+    (server) => server.description === void 0 ? { url: server.url } : { url: server.url, description: server.description }
+  );
+}
+function resolveOpenApi(raw) {
+  const requested = raw?.enabled ?? false;
+  const production = isProductionRuntime();
+  return {
+    enabled: requested && !production,
+    suppressedInProduction: requested && production,
+    path: raw?.path ?? DEFAULT_OPENAPI_PATH,
+    jsonPath: raw?.jsonPath ?? DEFAULT_OPENAPI_JSON_PATH,
+    title: raw?.title ?? DEFAULT_OPENAPI_TITLE,
+    description: raw?.description ?? "",
+    version: raw?.version ?? DEFAULT_OPENAPI_VERSION,
+    servers: cloneServers(raw?.servers),
+    // Structured-cloned rather than shallow-copied: the values are
+    // consumer-owned nested objects, and the deep-freeze below would otherwise
+    // reach into them.
+    securitySchemes: structuredClone(raw?.securitySchemes ?? {}),
+    includeCoreSchemas: raw?.includeCoreSchemas ?? true
+  };
+}
+function resolveTelemetry(raw) {
+  return {
+    enabled: raw?.enabled ?? false,
+    exposeTraceId: raw?.exposeTraceId ?? false
+  };
+}
 function normalizeCoreOptions(raw) {
   return deepFreeze({
     envelope: resolveEnvelope(raw?.envelope),
     timing: resolveTiming(raw?.timing),
     health: resolveHealth(raw?.health),
-    metrics: resolveMetrics(raw?.metrics)
+    metrics: resolveMetrics(raw?.metrics),
+    openapi: resolveOpenApi(raw?.openapi),
+    telemetry: resolveTelemetry(raw?.telemetry)
   });
 }
 normalizeCoreOptions();
@@ -71,6 +118,70 @@ var BYMAX_CORRELATION_PROVIDER = /* @__PURE__ */ Symbol("BYMAX_CORRELATION_PROVI
 var BYMAX_TIMING_SINK = /* @__PURE__ */ Symbol("BYMAX_TIMING_SINK");
 var BYMAX_HEALTH_INDICATORS = /* @__PURE__ */ Symbol("BYMAX_HEALTH_INDICATORS");
 var BYMAX_METRICS_REGISTRY = /* @__PURE__ */ Symbol("BYMAX_METRICS_REGISTRY");
+var BYMAX_TRACE_CONTEXT = /* @__PURE__ */ Symbol("BYMAX_TRACE_CONTEXT");
+
+// src/optional-peer.ts
+function isMissingModuleError(cause) {
+  const code = cause.code;
+  return code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND";
+}
+function missingPeerMessage(option, peer) {
+  return `${option} is true but the optional peer ${peer} is not installed. Run: pnpm add ${peer}`;
+}
+
+// src/telemetry/trace-context.ts
+var MISSING_PEER_MESSAGE = missingPeerMessage("telemetry.enabled", "@opentelemetry/api");
+var NoopTraceContextProvider = class {
+  /**
+   * Resolve no trace context.
+   *
+   * @returns Always `undefined`.
+   */
+  getTraceContext() {
+    return void 0;
+  }
+};
+async function loadOtelApi() {
+  try {
+    return await import('@opentelemetry/api');
+  } catch (cause) {
+    if (isMissingModuleError(cause)) {
+      throw new Error(MISSING_PEER_MESSAGE, { cause });
+    }
+    throw cause;
+  }
+}
+var OtelTraceContextProvider = class {
+  /**
+   * @param api - The loaded OpenTelemetry API surface.
+   */
+  constructor(api) {
+    this.api = api;
+  }
+  /**
+   * Resolve the identifiers of the currently active span.
+   *
+   * @returns The active trace context, or `undefined` when no valid span is
+   *   recording.
+   */
+  getTraceContext() {
+    const span = this.api.trace.getActiveSpan();
+    if (span === void 0) {
+      return void 0;
+    }
+    const spanContext = span.spanContext();
+    if (!this.api.isSpanContextValid(spanContext)) {
+      return void 0;
+    }
+    return { traceId: spanContext.traceId, spanId: spanContext.spanId };
+  }
+};
+async function resolveTraceContextProvider(options) {
+  if (!options.telemetry.enabled) {
+    return new NoopTraceContextProvider();
+  }
+  return new OtelTraceContextProvider(await loadOtelApi());
+}
 
 // src/timing/timing.clock.ts
 var DEFAULT_MONOTONIC_CLOCK = {
@@ -101,6 +212,13 @@ var NoopTimingSink = class {
 function buildDefaultProviders() {
   return [{ provide: BYMAX_TIMING_CLOCK, useValue: DEFAULT_MONOTONIC_CLOCK }];
 }
+function buildTraceContextProvider() {
+  return {
+    provide: BYMAX_TRACE_CONTEXT,
+    useFactory: (options) => resolveTraceContextProvider(options),
+    inject: [BYMAX_CORE_OPTIONS]
+  };
+}
 
 // src/envelope/error-codes.ts
 var BYMAX_BAD_REQUEST = "BYMAX_BAD_REQUEST";
@@ -160,7 +278,8 @@ function buildErrorEnvelope(input) {
   return {
     ...base,
     ...input.details !== void 0 ? { details: input.details } : {},
-    ...input.correlationId !== void 0 ? { correlationId: input.correlationId } : {}
+    ...input.correlationId !== void 0 ? { correlationId: input.correlationId } : {},
+    ...input.traceId !== void 0 ? { traceId: input.traceId } : {}
   };
 }
 
@@ -211,12 +330,13 @@ exports.BymaxExceptionFilter = class BymaxExceptionFilter {
    *   nothing is bound, this falls back to a no-op that omits `correlationId`.
    * @param adapterHost - Host of the live HTTP adapter, resolved lazily per catch.
    */
-  constructor(options, correlation, adapterHost) {
+  constructor(options, correlation, adapterHost, traceContext) {
     this.options = options;
     this.adapterHost = adapterHost;
     /** Clock used to stamp the envelope timestamp; overridable in tests via fake timers. */
     this.now = () => /* @__PURE__ */ new Date();
     this.correlation = correlation ?? new NoopCorrelationIdProvider();
+    this.traceContext = traceContext ?? new NoopTraceContextProvider();
   }
   /**
    * Format the exception into the stable envelope and reply with it.
@@ -227,6 +347,34 @@ exports.BymaxExceptionFilter = class BymaxExceptionFilter {
    * @param exception - The error that escaped the handler.
    * @param host - The arguments host for the current execution context.
    */
+  /**
+   * Resolve one optional annotation for the envelope, treating any failure as
+   * "absent".
+   *
+   * Both annotations this filter attaches — the correlation id and the trace id
+   * — come from providers it does not own: one is supplied by the consumer, the
+   * other reads a third-party API. Their contracts say they do not throw, but
+   * this filter is the last thing standing between an error and the client, and
+   * a guarantee that depends on someone else's good behavior is not one. A
+   * failed lookup costs an optional field; an unguarded one would cost the whole
+   * response.
+   *
+   * The failure is deliberately silent, and the same reasoning applies as for
+   * the {@link BymaxExceptionFilter.onUnexpectedError} seam a few lines below:
+   * this runs while an error is already being formatted, so reporting a
+   * telemetry failure here would replace the failure the caller actually needs
+   * to see.
+   *
+   * @param read - The lookup to attempt.
+   * @returns The resolved value, or `undefined` when absent or on failure.
+   */
+  readAnnotation(read) {
+    try {
+      return read();
+    } catch {
+      return void 0;
+    }
+  }
   catch(exception, host) {
     if (host.getType() !== "http") {
       throw exception;
@@ -235,11 +383,13 @@ exports.BymaxExceptionFilter = class BymaxExceptionFilter {
     const ctx = host.switchToHttp();
     const request = ctx.getRequest();
     const response = ctx.getResponse();
-    const correlationId = this.correlation.getCorrelationId();
+    const correlationId = this.readAnnotation(() => this.correlation.getCorrelationId());
+    const traceId = this.readAnnotation(() => this.traceContext.getTraceContext()?.traceId);
     const context = {
       method: String(httpAdapter.getRequestMethod(request)),
       path: String(httpAdapter.getRequestUrl(request)),
-      ...correlationId !== void 0 ? { correlationId } : {}
+      ...correlationId !== void 0 ? { correlationId } : {},
+      ...traceId !== void 0 ? { traceId } : {}
     };
     const envelope = this.buildEnvelope(exception, context);
     httpAdapter.reply(response, envelope, envelope.statusCode);
@@ -333,7 +483,11 @@ exports.BymaxExceptionFilter = class BymaxExceptionFilter {
       path: context.path,
       now: this.now,
       ...details !== void 0 ? { details } : {},
-      ...context.correlationId !== void 0 ? { correlationId: context.correlationId } : {}
+      ...context.correlationId !== void 0 ? { correlationId: context.correlationId } : {},
+      // Gated separately from the context above: the trace id reaches the
+      // observability seam either way, and the response body only when the
+      // operator opted into publishing it.
+      ...this.options.telemetry.exposeTraceId && context.traceId !== void 0 ? { traceId: context.traceId } : {}
     });
   }
   /**
@@ -355,7 +509,9 @@ exports.BymaxExceptionFilter = __decorateClass([
   __decorateParam(0, common.Inject(BYMAX_CORE_OPTIONS)),
   __decorateParam(1, common.Optional()),
   __decorateParam(1, common.Inject(BYMAX_CORRELATION_PROVIDER)),
-  __decorateParam(2, common.Inject(core.HttpAdapterHost))
+  __decorateParam(2, common.Inject(core.HttpAdapterHost)),
+  __decorateParam(3, common.Optional()),
+  __decorateParam(3, common.Inject(BYMAX_TRACE_CONTEXT))
 ], exports.BymaxExceptionFilter);
 
 // src/timing/request-info.accessor.ts
@@ -391,11 +547,16 @@ exports.TimingInterceptor = class TimingInterceptor {
    * @param clock - Monotonic clock seam; defaults to `performance.now()`, and
    *   is bound explicitly through {@link BYMAX_TIMING_CLOCK} so tests inject a
    *   stub advancing by controlled amounts.
+   * @param traceContext - Reads the active span's identifiers. Injected with
+   *   `@Optional()` so this interceptor stays constructible on its own; when
+   *   nothing resolves, a no-op resolves no trace and the sample simply omits
+   *   the fields.
    */
-  constructor(options, sink, clock = DEFAULT_MONOTONIC_CLOCK) {
+  constructor(options, sink, clock = DEFAULT_MONOTONIC_CLOCK, traceContext) {
     this.options = options;
     this.clock = clock;
     this.sink = sink ?? new NoopTimingSink();
+    this.traceContext = traceContext ?? new NoopTraceContextProvider();
   }
   /**
    * Measure the handler chain and record exactly one sample per completed
@@ -456,9 +617,22 @@ exports.TimingInterceptor = class TimingInterceptor {
     const durationMs = this.clock.now() - start;
     const threshold = this.options.timing.slowRequestThresholdMs;
     const slow = threshold !== void 0 && durationMs > threshold;
-    const sample = { method, route, statusCode, durationMs, slow };
+    let trace;
+    try {
+      trace = this.traceContext.getTraceContext();
+    } catch {
+    }
     try {
-      this.sink.record(sample);
+      this.sink.record({
+        method,
+        route,
+        statusCode,
+        durationMs,
+        slow,
+        // Spread rather than assigned: an absent trace must leave the keys off
+        // the sample entirely, so a sink cannot mistake `undefined` for an id.
+        ...trace !== void 0 ? { traceId: trace.traceId, spanId: trace.spanId } : {}
+      });
     } catch {
     }
   }
@@ -468,7 +642,9 @@ exports.TimingInterceptor = __decorateClass([
   __decorateParam(0, common.Inject(BYMAX_CORE_OPTIONS)),
   __decorateParam(1, common.Optional()),
   __decorateParam(1, common.Inject(BYMAX_TIMING_SINK)),
-  __decorateParam(2, common.Inject(BYMAX_TIMING_CLOCK))
+  __decorateParam(2, common.Inject(BYMAX_TIMING_CLOCK)),
+  __decorateParam(3, common.Optional()),
+  __decorateParam(3, common.Inject(BYMAX_TRACE_CONTEXT))
 ], exports.TimingInterceptor);
 
 // src/passthrough.providers.ts
@@ -515,6 +691,53 @@ function selectAsyncExceptionFilter(options, correlation, adapterHost) {
 function selectAsyncTimingInterceptor(options, sink, clock) {
   return options.timing.enabled ? new exports.TimingInterceptor(options, sink, clock) : new PassThroughInterceptor();
 }
+
+// src/discovery.ts
+function labelFor(className, token) {
+  return className === "" ? String(token) : className;
+}
+function findMarkedProviders(discovery, reflector, metadataKey) {
+  const marked = [];
+  for (const wrapper of discovery.getProviders()) {
+    const metatype = wrapper.metatype;
+    if (typeof metatype !== "function") {
+      continue;
+    }
+    if (reflector.get(metadataKey, metatype) !== true) {
+      continue;
+    }
+    marked.push({ instance: wrapper.instance, label: labelFor(metatype.name, wrapper.name) });
+  }
+  return marked;
+}
+var BYMAX_HEALTH_INDICATOR_METADATA = "bymax-one:health-indicator";
+
+// src/health/health.discovery.ts
+function isIndicator(instance) {
+  if (instance === null || instance === void 0) {
+    return false;
+  }
+  const candidate = instance;
+  return typeof candidate.name === "string" && candidate.name !== "" && typeof candidate.check === "function";
+}
+function discoverIndicators(discovery, reflector) {
+  const discovered = [];
+  for (const marked of findMarkedProviders(discovery, reflector, BYMAX_HEALTH_INDICATOR_METADATA)) {
+    if (!isIndicator(marked.instance)) {
+      throw new Error(
+        `[BymaxCoreModule] "${marked.label}" is marked with @BymaxHealthIndicator() but does not implement IHealthIndicator: it must expose a non-empty "name" and a "check" method.`
+      );
+    }
+    discovered.push(marked.instance);
+  }
+  return discovered.sort((left, right) => left.name.localeCompare(right.name));
+}
+function mergeIndicators(explicit, discovered) {
+  const claimed = new Set(explicit.map((indicator) => indicator.name));
+  return [...explicit, ...discovered.filter((indicator) => !claimed.has(indicator.name))];
+}
+
+// src/health/health.service.ts
 var MAX_ERROR_MESSAGE_LENGTH = 300;
 var TRUNCATION_ELLIPSIS = "...";
 function summarizeRejection(reason) {
@@ -529,18 +752,18 @@ function summarizeRejection(reason) {
   }
   return `${message.slice(0, MAX_ERROR_MESSAGE_LENGTH - TRUNCATION_ELLIPSIS.length)}${TRUNCATION_ELLIPSIS}`;
 }
-async function runIndicator(indicator, timeoutMs) {
+async function runIndicator(indicator, timeoutMs, exposeErrors, logger) {
   let timer;
   const timedOut = new Promise((resolve) => {
     timer = setTimeout(() => {
       resolve({ name: indicator.name, status: "down", details: { timedOutAfterMs: timeoutMs } });
     }, timeoutMs);
   });
-  const checked = Promise.resolve().then(() => indicator.check()).then((result) => ({ ...result, name: indicator.name })).catch((reason) => ({
-    name: indicator.name,
-    status: "down",
-    details: { error: summarizeRejection(reason) }
-  }));
+  const checked = Promise.resolve().then(() => indicator.check()).then((result) => ({ ...result, name: indicator.name })).catch((reason) => {
+    const message = summarizeRejection(reason);
+    logger.warn(`Health indicator "${indicator.name}" reported down: ${message}`);
+    return exposeErrors ? { name: indicator.name, status: "down", details: { error: message } } : { name: indicator.name, status: "down" };
+  });
   try {
     return await Promise.race([checked, timedOut]);
   } finally {
@@ -549,16 +772,71 @@ async function runIndicator(indicator, timeoutMs) {
 }
 var HealthService = class {
   /**
-   * @param indicators - Every registered indicator; empty when none resolve.
-   *   Injected with `@Optional()`: `BymaxCoreModule` binds no local default for
-   *   this token, so a consumer's own `BYMAX_HEALTH_INDICATORS` binding (from
-   *   their own, globally-visible module) is not shadowed by one; when nothing
-   *   is bound, this defaults to an empty array.
+   * @param indicators - Every explicitly registered indicator; empty when none
+   *   resolve. Injected with `@Optional()`: `BymaxCoreModule` binds no local
+   *   default for this token, so a consumer's own `BYMAX_HEALTH_INDICATORS`
+   *   binding (from their own, globally-visible module) is not shadowed by one;
+   *   when nothing is bound, this defaults to an empty array.
    * @param options - Resolved core options; supplies `indicatorTimeoutMs`.
+   * @param discovery - Nest's provider-graph reader, present only when
+   *   `DiscoveryModule` is imported, which `BymaxCoreModule` does exactly when
+   *   discovery can be needed. Optional so this service stays constructible
+   *   without it when the feature is off.
+   * @param reflector - Nest's metadata reader, used to match the indicator
+   *   marker. Optional for the same reason.
    */
-  constructor(indicators = [], options) {
+  constructor(indicators = [], options, discovery, reflector) {
     this.indicators = indicators;
     this.options = options;
+    this.discovery = discovery;
+    this.reflector = reflector;
+    /**
+     * Nest's own logger, scoped to this class. The failure reason of a `down`
+     * indicator is written here rather than into the HTTP response, so the
+     * diagnostic survives without being served to whoever can reach the probe.
+     */
+    this.logger = new common.Logger(HealthService.name);
+  }
+  /**
+   * Resolve the readiness set once the whole container is instantiated.
+   *
+   * Bound to `onApplicationBootstrap`, not `onModuleInit`: module-init hooks run
+   * concurrently across modules, so a provider this scan needs may not exist
+   * yet. Running here also means a provider marked as an indicator but not
+   * implementing the contract fails the boot, instead of failing the first
+   * readiness probe in production.
+   */
+  onApplicationBootstrap() {
+    this.resolveIndicators();
+  }
+  /**
+   * The effective readiness set, computed on first use and memoized.
+   *
+   * @returns The explicit indicators, plus the discovered ones when the feature
+   *   is enabled.
+   * @throws Error When discovery is enabled but Nest's discovery services are
+   *   not reachable, which means this service was constructed outside
+   *   `BymaxCoreModule`; a silent fallback would leave an operator believing
+   *   checks are running that never run.
+   */
+  resolveIndicators() {
+    if (this.effectiveIndicators !== void 0) {
+      return this.effectiveIndicators;
+    }
+    if (!this.options.health.enabled || !this.options.health.autoDiscover) {
+      this.effectiveIndicators = this.indicators;
+      return this.effectiveIndicators;
+    }
+    if (this.discovery === void 0 || this.reflector === void 0) {
+      throw new Error(
+        "[BymaxCoreModule] health.autoDiscover is enabled but Nest's DiscoveryService is not available. Register the health feature through BymaxCoreModule, which imports DiscoveryModule for it."
+      );
+    }
+    this.effectiveIndicators = mergeIndicators(
+      this.indicators,
+      discoverIndicators(this.discovery, this.reflector)
+    );
+    return this.effectiveIndicators;
   }
   /**
    * Liveness check: the process is up and able to respond. Runs no
@@ -570,7 +848,7 @@ var HealthService = class {
     return { status: "ok", checks: [] };
   }
   /**
-   * Readiness check: run every registered indicator concurrently and
+   * Readiness check: run every indicator in the effective set concurrently and
    * aggregate the results. `status` is `'ok'` only when every indicator
    * reports `up`; an empty indicator list is vacuously `'ok'`.
    *
@@ -578,8 +856,11 @@ var HealthService = class {
    */
   async checkReadiness() {
     const timeoutMs = this.options.health.indicatorTimeoutMs;
+    const exposeErrors = this.options.health.exposeIndicatorErrors;
     const checks = await Promise.all(
-      this.indicators.map((indicator) => runIndicator(indicator, timeoutMs))
+      this.resolveIndicators().map(
+        (indicator) => runIndicator(indicator, timeoutMs, exposeErrors, this.logger)
+      )
     );
     const status = checks.every((check) => check.status === "up") ? "ok" : "error";
     return { status, checks };
@@ -589,7 +870,11 @@ HealthService = __decorateClass([
   common.Injectable(),
   __decorateParam(0, common.Optional()),
   __decorateParam(0, common.Inject(BYMAX_HEALTH_INDICATORS)),
-  __decorateParam(1, common.Inject(BYMAX_CORE_OPTIONS))
+  __decorateParam(1, common.Inject(BYMAX_CORE_OPTIONS)),
+  __decorateParam(2, common.Optional()),
+  __decorateParam(2, common.Inject(core.DiscoveryService)),
+  __decorateParam(3, common.Optional()),
+  __decorateParam(3, common.Inject(core.Reflector))
 ], HealthService);
 
 // src/health/health.controller.ts
@@ -639,6 +924,98 @@ function createHealthController(registeredPath) {
   ], HealthController);
   return HealthController;
 }
+var BYMAX_METRICS_CONTRIBUTOR_METADATA = "bymax-one:metrics-contributor";
+
+// src/metrics/metrics.contribution.ts
+function isContributor(instance) {
+  if (instance === null || instance === void 0) {
+    return false;
+  }
+  return typeof instance.registerMetrics === "function";
+}
+function discoverContributors(discovery, reflector) {
+  const found = [];
+  for (const marked of findMarkedProviders(
+    discovery,
+    reflector,
+    BYMAX_METRICS_CONTRIBUTOR_METADATA
+  )) {
+    if (!isContributor(marked.instance)) {
+      throw new Error(
+        `[BymaxCoreModule] "${marked.label}" is marked with @BymaxMetricsContributor() but does not implement IMetricsContributor: it must expose a "registerMetrics" method.`
+      );
+    }
+    found.push({ contributor: marked.instance, label: marked.label });
+  }
+  return found.sort((left, right) => left.label.localeCompare(right.label));
+}
+function applyContributions(contributors, registry) {
+  for (const { contributor, label } of contributors) {
+    try {
+      contributor.registerMetrics(registry);
+    } catch (cause) {
+      const reason = cause instanceof Error ? cause.message : String(cause);
+      throw new Error(`[BymaxCoreModule] "${label}" failed to register its metrics: ${reason}`, {
+        cause
+      });
+    }
+  }
+}
+var MetricsContributionRunner = class {
+  /**
+   * @param options - Resolved core options; the metrics gate is read from here.
+   * @param registry - The registry the scrape endpoint serves. On the async path
+   *   this resolves to a guarded placeholder while metrics are disabled, which is
+   *   why the gate below runs before the registry is ever passed on.
+   * @param discovery - Nest's provider-graph reader, present when
+   *   `DiscoveryModule` is imported. Optional so this service stays constructible
+   *   without it.
+   * @param reflector - Nest's metadata reader, used to match the marker.
+   */
+  constructor(options, registry, discovery, reflector) {
+    this.options = options;
+    this.registry = registry;
+    this.discovery = discovery;
+    this.reflector = reflector;
+    /** Nest's logger, scoped to the module, for the one line this feature writes. */
+    this.logger = new common.Logger("BymaxCoreModule");
+  }
+  /**
+   * Find the contributors and let each register its collectors.
+   *
+   * @throws Error When a marked provider is not a contributor, when one fails to
+   *   register, or when metrics are enabled without Nest's discovery services —
+   *   which means this runner was constructed outside `BymaxCoreModule`, and a
+   *   silent skip would leave an operator with an endpoint quietly missing every
+   *   metric a library publishes.
+   */
+  onApplicationBootstrap() {
+    if (!this.options.metrics.enabled) {
+      return;
+    }
+    if (this.discovery === void 0 || this.reflector === void 0) {
+      throw new Error(
+        "[BymaxCoreModule] metrics are enabled but Nest's DiscoveryService is not available. Register the metrics feature through BymaxCoreModule, which imports DiscoveryModule for it."
+      );
+    }
+    const contributors = discoverContributors(this.discovery, this.reflector);
+    applyContributions(contributors, this.registry);
+    if (contributors.length > 0) {
+      this.logger.log(
+        `Registered metrics from ${contributors.length} contributor(s): ${contributors.map(({ label }) => label).join(", ")}`
+      );
+    }
+  }
+};
+MetricsContributionRunner = __decorateClass([
+  common.Injectable(),
+  __decorateParam(0, common.Inject(BYMAX_CORE_OPTIONS)),
+  __decorateParam(1, common.Inject(BYMAX_METRICS_REGISTRY)),
+  __decorateParam(2, common.Optional()),
+  __decorateParam(2, common.Inject(core.DiscoveryService)),
+  __decorateParam(3, common.Optional()),
+  __decorateParam(3, common.Inject(core.Reflector))
+], MetricsContributionRunner);
 function assertControllerMatchesOptions2(options, registeredPath) {
   assertAsyncFeatureEnabled("metrics", options.metrics.enabled);
   if (options.metrics.path !== registeredPath) {
@@ -680,17 +1057,13 @@ function createMetricsController(registeredPath) {
 }
 
 // src/metrics/metrics.registry.ts
-var MISSING_PEER_MESSAGE = "metrics.enabled is true but the optional peer prom-client is not installed. Run: pnpm add prom-client";
-function isMissingModuleError(cause) {
-  const code = cause.code;
-  return code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND";
-}
+var MISSING_PEER_MESSAGE2 = missingPeerMessage("metrics.enabled", "prom-client");
 async function loadPromClient() {
   try {
     return await import('prom-client');
   } catch (cause) {
     if (isMissingModuleError(cause)) {
-      throw new Error(MISSING_PEER_MESSAGE, { cause });
+      throw new Error(MISSING_PEER_MESSAGE2, { cause });
     }
     throw cause;
   }
@@ -836,8 +1209,12 @@ function buildSyncProviders(resolved) {
   if (resolved.health.enabled) {
     providers.push(HealthService);
   }
+  if (resolved.telemetry.enabled) {
+    providers.push(buildTraceContextProvider());
+  }
   if (resolved.metrics.enabled) {
     providers.push(buildMetricsRegistryProvider());
+    providers.push(MetricsContributionRunner);
     if (resolved.timing.enabled) {
       providers.push(buildMetricsTimingSinkProvider());
     }
@@ -872,10 +1249,11 @@ function buildAsyncSlots() {
     }
   ];
 }
-function augmentModule(base, providers, controllers, exportTokens = [BYMAX_CORE_OPTIONS]) {
+function augmentModule(base, providers, controllers, exportTokens = [BYMAX_CORE_OPTIONS], imports = []) {
   return {
     ...base,
     module: exports.BymaxCoreModule,
+    imports: [...base.imports ?? [], ...imports],
     providers: [...base.providers ?? [], ...providers],
     controllers: [...base.controllers ?? [], ...controllers],
     exports: [...base.exports ?? [], ...exportTokens]
@@ -907,11 +1285,14 @@ exports.BymaxCoreModule = class BymaxCoreModule extends BymaxCoreModuleBase {
         exportTokens.push(BYMAX_TIMING_SINK);
       }
     }
+    const scansProviders = resolved.health.enabled && resolved.health.autoDiscover || resolved.metrics.enabled;
+    const imports = scansProviders ? [core.DiscoveryModule] : [];
     return augmentModule(
       super.forRoot(options),
       providers,
       buildControllers(resolved),
-      exportTokens
+      exportTokens,
+      imports
     );
   }
   /**
@@ -945,13 +1326,16 @@ exports.BymaxCoreModule = class BymaxCoreModule extends BymaxCoreModuleBase {
       ...buildAsyncSlots(),
       HealthService,
       buildMetricsRegistryProvider(),
-      buildMetricsTimingSinkProvider()
+      buildMetricsTimingSinkProvider(),
+      MetricsContributionRunner,
+      buildTraceContextProvider()
     ];
     return augmentModule(
       super.forRootAsync(options),
       providers,
       [createHealthController(DEFAULT_HEALTH_PATH), createMetricsController(DEFAULT_METRICS_PATH)],
-      [BYMAX_CORE_OPTIONS, BYMAX_TIMING_SINK, BYMAX_METRICS_REGISTRY]
+      [BYMAX_CORE_OPTIONS, BYMAX_TIMING_SINK, BYMAX_METRICS_REGISTRY],
+      [core.DiscoveryModule]
     );
   }
 };
@@ -976,6 +1360,7 @@ exports.BYMAX_PAYLOAD_TOO_LARGE = BYMAX_PAYLOAD_TOO_LARGE;
 exports.BYMAX_SERVICE_UNAVAILABLE = BYMAX_SERVICE_UNAVAILABLE;
 exports.BYMAX_TIMING_SINK = BYMAX_TIMING_SINK;
 exports.BYMAX_TOO_MANY_REQUESTS = BYMAX_TOO_MANY_REQUESTS;
+exports.BYMAX_TRACE_CONTEXT = BYMAX_TRACE_CONTEXT;
 exports.BYMAX_UNAUTHORIZED = BYMAX_UNAUTHORIZED;
 exports.BYMAX_UNPROCESSABLE_ENTITY = BYMAX_UNPROCESSABLE_ENTITY;
 exports.BYMAX_UNSUPPORTED_MEDIA_TYPE = BYMAX_UNSUPPORTED_MEDIA_TYPE;