@bymax-one/nest-core 1.6.0 → 1.6.2

package/dist/index.d.cts

@@ -564,6 +564,12 @@ declare const BYMAX_HEALTH_INDICATORS: unique symbol;
  * stands that line down in favour of the sink.
  */
 declare const BYMAX_HEALTH_TRANSITION_SINK: unique symbol;
+/**
+ * Provide the `IUnexpectedErrorSink` that receives the cause of each collapsed
+ * `500 BYMAX_INTERNAL_ERROR`. Nothing is bound by default, and with no
+ * sink the filter records nothing.
+ */
+declare const BYMAX_UNEXPECTED_ERROR_SINK: unique symbol;
 /**
  * Provide the `prom-client` `Registry` backing the metrics endpoint. Bound
  * lazily and only when the metrics feature is enabled.
@@ -636,6 +642,100 @@ interface ITraceContextProvider {
     getTraceContext(): TraceContext | undefined;
 }
 
+/**
+ * @fileoverview The unexpected-error contract: a sink that receives the
+ * original value behind every collapsed `500 BYMAX_INTERNAL_ERROR`, with the
+ * request it failed.
+ *
+ * This exists because the collapse is what makes the response safe, and that
+ * same collapse is what makes the cause unrecoverable. The envelope carries a
+ * fixed message by design, an access log sees only the status, and the thrown
+ * value is gone the moment the filter replies. Nothing downstream of the filter
+ * can get it back, so the filter has to hand it over before it goes.
+ *
+ * **Structural on purpose.** A sink is matched by shape, not by inheritance, so
+ * a logging library can ship a compatible class without importing this package
+ * or declaring it as a peer. Nothing here is a class or a value.
+ *
+ * **What the report leaves out.** No request body, no headers, no query string
+ * and no raw URL: `route` is the template the router matched, the same
+ * bounded label the timing sample carries. A sink usually writes to a log that
+ * outlives the request and is read by more people than the request's sender,
+ * and a query string is where tokens and personal data end up. A sink that
+ * needs more than this reads it from its own request context.
+ *
+ * The thrown value itself is passed as is, uncut and unsanitised, whatever
+ * `envelope.exposeInternals` says. That option controls the response body,
+ * which goes to an untrusted client; a sink is application code at the same
+ * trust level as the logger, and a cause cut down to make it safe is not much
+ * of a cause. Treat what reaches it as possibly carrying hosts, queries and
+ * credentials from a driver's error message, and send it where access is
+ * already controlled.
+ * @layer Contract
+ */
+/**
+ * One unexpected error, as the filter saw it when collapsing it.
+ *
+ * Optional fields are **absent** when unknown, never present holding
+ * `undefined`, so a sink that spreads the report into a structured log line
+ * writes no empty keys.
+ */
+interface UnexpectedErrorReport {
+    /** The original thrown value: an `Error`, or anything else that was thrown. */
+    readonly error: unknown;
+    /** HTTP method, read through the adapter (Express and Fastify neutral). */
+    readonly method: string;
+    /**
+     * Route template the request matched, for example `"/invoices/:id"`, or
+     * `UNMATCHED_ROUTE` when it matched none: an error raised by middleware
+     * before routing. Never the raw URL.
+     */
+    readonly route: string;
+    /** Correlation id for the request; absent when no provider resolves one. */
+    readonly correlationId?: string;
+    /**
+     * Trace the request ran under; absent when telemetry is off or nothing was
+     * recording. Present whatever `telemetry.exposeTraceId` says, because that
+     * option controls the response body and the sink is not the response.
+     */
+    readonly traceId?: string;
+}
+/**
+ * Receives the cause of each collapsed `500 BYMAX_INTERNAL_ERROR`.
+ *
+ * Bind an implementation under `BYMAX_UNEXPECTED_ERROR_SINK` from a module of
+ * your own marked `@Global()`. Nothing is bound by default, and with no sink the
+ * filter records nothing: this package owns no logger.
+ *
+ * Called once per unexpected error, never for an `HttpException` and never for
+ * a 4xx the framework's body pipeline raised (a malformed JSON body, a payload
+ * over the limit) — those are not unexpected, and a sink would otherwise get a
+ * flood of client mistakes mixed in with server failures.
+ *
+ * Called synchronously from the exception filter, before the response is
+ * written, so an implementation must be cheap and must not block: hand the
+ * report to a logger and return. Whatever it does, the response does not
+ * change. A synchronous throw is caught, and an `async record()` that rejects
+ * is contained, and both are dropped silently: the filter is the last thing
+ * between an error and the client, and anything it reported about its own sink
+ * would push aside the failure the caller actually needs to see.
+ *
+ * Runs alongside the protected `BymaxExceptionFilter.onUnexpectedError` seam,
+ * not instead of it; a subclass overriding that seam still receives every call.
+ *
+ * Takes a single object, matching `ITimingSink.record` and
+ * `IHealthTransitionSink.record`, so a later field is an additive change rather
+ * than a new positional parameter.
+ */
+interface IUnexpectedErrorSink {
+    /**
+     * Record one unexpected error.
+     *
+     * @param report - The original thrown value and the request it failed.
+     */
+    record(report: UnexpectedErrorReport): void;
+}
+
 /**
  * Neutral view of the current request handed to {@link BymaxExceptionFilter}
  * mappers and to the {@link BymaxExceptionFilter.onUnexpectedError} seam. It
@@ -665,6 +765,7 @@ interface FilterErrorContext {
 declare class BymaxExceptionFilter implements ExceptionFilter {
     private readonly options;
     private readonly adapterHost;
+    private readonly unexpectedErrorSink?;
     /** Clock used to stamp the envelope timestamp; overridable in tests via fake timers. */
     private readonly now;
     /** The resolved correlation provider, or the no-op fallback when none is bound. */
@@ -679,8 +780,10 @@ declare class BymaxExceptionFilter implements ExceptionFilter {
      *   (from their own, globally-visible module) is not shadowed by one; when
      *   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.
+     * @param traceContext - Reader for the active trace; a no-op when unbound.
+     * @param unexpectedErrorSink - Receives every unexpected error; unbound by default.
      */
-    constructor(options: ResolvedCoreOptions, correlation: ICorrelationIdProvider | undefined, adapterHost: HttpAdapterHost, traceContext?: ITraceContextProvider);
+    constructor(options: ResolvedCoreOptions, correlation: ICorrelationIdProvider | undefined, adapterHost: HttpAdapterHost, traceContext?: ITraceContextProvider, unexpectedErrorSink?: IUnexpectedErrorSink | undefined);
     /**
      * Format the exception into the stable envelope and reply with it.
      *
@@ -715,14 +818,25 @@ declare class BymaxExceptionFilter implements ExceptionFilter {
     catch(exception: unknown, host: ArgumentsHost): void;
     /**
      * Select the mapping rule for the exception and build its envelope. An
-     * unknown error is handed to the observability seam before it collapses, so
-     * an integration can record the original error with the request context.
+     * unknown error is handed to the observability seam once its envelope is
+     * built, so an integration can record the original error with the context.
      *
      * @param exception - The error that escaped the handler.
      * @param context - The neutral request context.
+     * @param request - The framework request, read only for the sink's route template.
      * @returns The formatted envelope.
      */
     private buildEnvelope;
+    /**
+     * Hand an unexpected error to the bound sink, if any. Whatever the sink does
+     * — throw, or return a promise that rejects — is absorbed: the response must
+     * not depend on it. See `IUnexpectedErrorSink` for the contract.
+     *
+     * @param error - The original thrown value.
+     * @param context - The neutral request context.
+     * @param request - The framework request, read for its route template only.
+     */
+    private reportUnexpected;
     /**
      * Map an `HttpException` to the envelope. A domain error passes its own code,
      * message and details through, whether it wrote them flat on the response or
@@ -758,7 +872,7 @@ declare class BymaxExceptionFilter implements ExceptionFilter {
     private toEnvelope;
     /**
      * Observability seam invoked for every unexpected (non-`HttpException`) error
-     * before it collapses to the generic 500. The base implementation is a no-op:
+     * collapsed to the generic 500. The base implementation is a no-op:
      * this library owns no logger. An integration (for example
      * `@bymax-one/nest-logger`) subclasses the filter and overrides this to record
      * the original error with the current request context and correlation id.
@@ -1179,4 +1293,4 @@ declare const BYMAX_GATEWAY_TIMEOUT = "BYMAX_GATEWAY_TIMEOUT";
  */
 declare function codeForStatus(status: number): string;
 
-export { BYMAX_BAD_GATEWAY, BYMAX_BAD_REQUEST, BYMAX_CLIENT_ERROR, BYMAX_CONFLICT, BYMAX_CORE_OPTIONS, BYMAX_CORRELATION_PROVIDER, BYMAX_FORBIDDEN, BYMAX_GATEWAY_TIMEOUT, BYMAX_HEALTH_INDICATORS, BYMAX_HEALTH_TRANSITION_SINK, BYMAX_INTERNAL_ERROR, BYMAX_METRICS_REGISTRY, BYMAX_NOT_FOUND, BYMAX_NOT_IMPLEMENTED, BYMAX_PAYLOAD_TOO_LARGE, BYMAX_SERVICE_UNAVAILABLE, BYMAX_TIMING_SINK, BYMAX_TOO_MANY_REQUESTS, BYMAX_TRACE_CONTEXT, BYMAX_UNAUTHORIZED, BYMAX_UNPROCESSABLE_ENTITY, BYMAX_UNSUPPORTED_MEDIA_TYPE, BYMAX_VALIDATION_FAILED, type BuildErrorEnvelopeInput, BymaxCoreModule, type BymaxCoreModuleOptions, BymaxExceptionFilter, BymaxTimingMiddleware, type EnvelopeOptions, type ErrorDetails, type ErrorEnvelope, type FilterErrorContext, type HealthOptions, type ICorrelationIdProvider, type ITimingSink, type ITraceContextProvider, type MetricsOptions, type OpenApiHttpMethod, type OpenApiOperationIdFactory, type OpenApiOperationKey, type OpenApiOptions, type OpenApiSecurityRequirement, type OpenApiSecurityScheme, type OpenApiServerDescriptor, type OperationSecurityMap, type RequestTimingSample, type ResolvedCoreOptions, type TelemetryOptions, TimingInterceptor, type TimingOptions, type TraceContext, UNMATCHED_ROUTE, buildErrorEnvelope, codeForStatus };
+export { BYMAX_BAD_GATEWAY, BYMAX_BAD_REQUEST, BYMAX_CLIENT_ERROR, BYMAX_CONFLICT, BYMAX_CORE_OPTIONS, BYMAX_CORRELATION_PROVIDER, BYMAX_FORBIDDEN, BYMAX_GATEWAY_TIMEOUT, BYMAX_HEALTH_INDICATORS, BYMAX_HEALTH_TRANSITION_SINK, BYMAX_INTERNAL_ERROR, BYMAX_METRICS_REGISTRY, BYMAX_NOT_FOUND, BYMAX_NOT_IMPLEMENTED, BYMAX_PAYLOAD_TOO_LARGE, BYMAX_SERVICE_UNAVAILABLE, BYMAX_TIMING_SINK, BYMAX_TOO_MANY_REQUESTS, BYMAX_TRACE_CONTEXT, BYMAX_UNAUTHORIZED, BYMAX_UNEXPECTED_ERROR_SINK, BYMAX_UNPROCESSABLE_ENTITY, BYMAX_UNSUPPORTED_MEDIA_TYPE, BYMAX_VALIDATION_FAILED, type BuildErrorEnvelopeInput, BymaxCoreModule, type BymaxCoreModuleOptions, BymaxExceptionFilter, BymaxTimingMiddleware, type EnvelopeOptions, type ErrorDetails, type ErrorEnvelope, type FilterErrorContext, type HealthOptions, type ICorrelationIdProvider, type ITimingSink, type ITraceContextProvider, type IUnexpectedErrorSink, type MetricsOptions, type OpenApiHttpMethod, type OpenApiOperationIdFactory, type OpenApiOperationKey, type OpenApiOptions, type OpenApiSecurityRequirement, type OpenApiSecurityScheme, type OpenApiServerDescriptor, type OperationSecurityMap, type RequestTimingSample, type ResolvedCoreOptions, type TelemetryOptions, TimingInterceptor, type TimingOptions, type TraceContext, UNMATCHED_ROUTE, type UnexpectedErrorReport, buildErrorEnvelope, codeForStatus };

package/dist/index.d.ts

@@ -564,6 +564,12 @@ declare const BYMAX_HEALTH_INDICATORS: unique symbol;
  * stands that line down in favour of the sink.
  */
 declare const BYMAX_HEALTH_TRANSITION_SINK: unique symbol;
+/**
+ * Provide the `IUnexpectedErrorSink` that receives the cause of each collapsed
+ * `500 BYMAX_INTERNAL_ERROR`. Nothing is bound by default, and with no
+ * sink the filter records nothing.
+ */
+declare const BYMAX_UNEXPECTED_ERROR_SINK: unique symbol;
 /**
  * Provide the `prom-client` `Registry` backing the metrics endpoint. Bound
  * lazily and only when the metrics feature is enabled.
@@ -636,6 +642,100 @@ interface ITraceContextProvider {
     getTraceContext(): TraceContext | undefined;
 }
 
+/**
+ * @fileoverview The unexpected-error contract: a sink that receives the
+ * original value behind every collapsed `500 BYMAX_INTERNAL_ERROR`, with the
+ * request it failed.
+ *
+ * This exists because the collapse is what makes the response safe, and that
+ * same collapse is what makes the cause unrecoverable. The envelope carries a
+ * fixed message by design, an access log sees only the status, and the thrown
+ * value is gone the moment the filter replies. Nothing downstream of the filter
+ * can get it back, so the filter has to hand it over before it goes.
+ *
+ * **Structural on purpose.** A sink is matched by shape, not by inheritance, so
+ * a logging library can ship a compatible class without importing this package
+ * or declaring it as a peer. Nothing here is a class or a value.
+ *
+ * **What the report leaves out.** No request body, no headers, no query string
+ * and no raw URL: `route` is the template the router matched, the same
+ * bounded label the timing sample carries. A sink usually writes to a log that
+ * outlives the request and is read by more people than the request's sender,
+ * and a query string is where tokens and personal data end up. A sink that
+ * needs more than this reads it from its own request context.
+ *
+ * The thrown value itself is passed as is, uncut and unsanitised, whatever
+ * `envelope.exposeInternals` says. That option controls the response body,
+ * which goes to an untrusted client; a sink is application code at the same
+ * trust level as the logger, and a cause cut down to make it safe is not much
+ * of a cause. Treat what reaches it as possibly carrying hosts, queries and
+ * credentials from a driver's error message, and send it where access is
+ * already controlled.
+ * @layer Contract
+ */
+/**
+ * One unexpected error, as the filter saw it when collapsing it.
+ *
+ * Optional fields are **absent** when unknown, never present holding
+ * `undefined`, so a sink that spreads the report into a structured log line
+ * writes no empty keys.
+ */
+interface UnexpectedErrorReport {
+    /** The original thrown value: an `Error`, or anything else that was thrown. */
+    readonly error: unknown;
+    /** HTTP method, read through the adapter (Express and Fastify neutral). */
+    readonly method: string;
+    /**
+     * Route template the request matched, for example `"/invoices/:id"`, or
+     * `UNMATCHED_ROUTE` when it matched none: an error raised by middleware
+     * before routing. Never the raw URL.
+     */
+    readonly route: string;
+    /** Correlation id for the request; absent when no provider resolves one. */
+    readonly correlationId?: string;
+    /**
+     * Trace the request ran under; absent when telemetry is off or nothing was
+     * recording. Present whatever `telemetry.exposeTraceId` says, because that
+     * option controls the response body and the sink is not the response.
+     */
+    readonly traceId?: string;
+}
+/**
+ * Receives the cause of each collapsed `500 BYMAX_INTERNAL_ERROR`.
+ *
+ * Bind an implementation under `BYMAX_UNEXPECTED_ERROR_SINK` from a module of
+ * your own marked `@Global()`. Nothing is bound by default, and with no sink the
+ * filter records nothing: this package owns no logger.
+ *
+ * Called once per unexpected error, never for an `HttpException` and never for
+ * a 4xx the framework's body pipeline raised (a malformed JSON body, a payload
+ * over the limit) — those are not unexpected, and a sink would otherwise get a
+ * flood of client mistakes mixed in with server failures.
+ *
+ * Called synchronously from the exception filter, before the response is
+ * written, so an implementation must be cheap and must not block: hand the
+ * report to a logger and return. Whatever it does, the response does not
+ * change. A synchronous throw is caught, and an `async record()` that rejects
+ * is contained, and both are dropped silently: the filter is the last thing
+ * between an error and the client, and anything it reported about its own sink
+ * would push aside the failure the caller actually needs to see.
+ *
+ * Runs alongside the protected `BymaxExceptionFilter.onUnexpectedError` seam,
+ * not instead of it; a subclass overriding that seam still receives every call.
+ *
+ * Takes a single object, matching `ITimingSink.record` and
+ * `IHealthTransitionSink.record`, so a later field is an additive change rather
+ * than a new positional parameter.
+ */
+interface IUnexpectedErrorSink {
+    /**
+     * Record one unexpected error.
+     *
+     * @param report - The original thrown value and the request it failed.
+     */
+    record(report: UnexpectedErrorReport): void;
+}
+
 /**
  * Neutral view of the current request handed to {@link BymaxExceptionFilter}
  * mappers and to the {@link BymaxExceptionFilter.onUnexpectedError} seam. It
@@ -665,6 +765,7 @@ interface FilterErrorContext {
 declare class BymaxExceptionFilter implements ExceptionFilter {
     private readonly options;
     private readonly adapterHost;
+    private readonly unexpectedErrorSink?;
     /** Clock used to stamp the envelope timestamp; overridable in tests via fake timers. */
     private readonly now;
     /** The resolved correlation provider, or the no-op fallback when none is bound. */
@@ -679,8 +780,10 @@ declare class BymaxExceptionFilter implements ExceptionFilter {
      *   (from their own, globally-visible module) is not shadowed by one; when
      *   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.
+     * @param traceContext - Reader for the active trace; a no-op when unbound.
+     * @param unexpectedErrorSink - Receives every unexpected error; unbound by default.
      */
-    constructor(options: ResolvedCoreOptions, correlation: ICorrelationIdProvider | undefined, adapterHost: HttpAdapterHost, traceContext?: ITraceContextProvider);
+    constructor(options: ResolvedCoreOptions, correlation: ICorrelationIdProvider | undefined, adapterHost: HttpAdapterHost, traceContext?: ITraceContextProvider, unexpectedErrorSink?: IUnexpectedErrorSink | undefined);
     /**
      * Format the exception into the stable envelope and reply with it.
      *
@@ -715,14 +818,25 @@ declare class BymaxExceptionFilter implements ExceptionFilter {
     catch(exception: unknown, host: ArgumentsHost): void;
     /**
      * Select the mapping rule for the exception and build its envelope. An
-     * unknown error is handed to the observability seam before it collapses, so
-     * an integration can record the original error with the request context.
+     * unknown error is handed to the observability seam once its envelope is
+     * built, so an integration can record the original error with the context.
      *
      * @param exception - The error that escaped the handler.
      * @param context - The neutral request context.
+     * @param request - The framework request, read only for the sink's route template.
      * @returns The formatted envelope.
      */
     private buildEnvelope;
+    /**
+     * Hand an unexpected error to the bound sink, if any. Whatever the sink does
+     * — throw, or return a promise that rejects — is absorbed: the response must
+     * not depend on it. See `IUnexpectedErrorSink` for the contract.
+     *
+     * @param error - The original thrown value.
+     * @param context - The neutral request context.
+     * @param request - The framework request, read for its route template only.
+     */
+    private reportUnexpected;
     /**
      * Map an `HttpException` to the envelope. A domain error passes its own code,
      * message and details through, whether it wrote them flat on the response or
@@ -758,7 +872,7 @@ declare class BymaxExceptionFilter implements ExceptionFilter {
     private toEnvelope;
     /**
      * Observability seam invoked for every unexpected (non-`HttpException`) error
-     * before it collapses to the generic 500. The base implementation is a no-op:
+     * collapsed to the generic 500. The base implementation is a no-op:
      * this library owns no logger. An integration (for example
      * `@bymax-one/nest-logger`) subclasses the filter and overrides this to record
      * the original error with the current request context and correlation id.
@@ -1179,4 +1293,4 @@ declare const BYMAX_GATEWAY_TIMEOUT = "BYMAX_GATEWAY_TIMEOUT";
  */
 declare function codeForStatus(status: number): string;
 
-export { BYMAX_BAD_GATEWAY, BYMAX_BAD_REQUEST, BYMAX_CLIENT_ERROR, BYMAX_CONFLICT, BYMAX_CORE_OPTIONS, BYMAX_CORRELATION_PROVIDER, BYMAX_FORBIDDEN, BYMAX_GATEWAY_TIMEOUT, BYMAX_HEALTH_INDICATORS, BYMAX_HEALTH_TRANSITION_SINK, BYMAX_INTERNAL_ERROR, BYMAX_METRICS_REGISTRY, BYMAX_NOT_FOUND, BYMAX_NOT_IMPLEMENTED, BYMAX_PAYLOAD_TOO_LARGE, BYMAX_SERVICE_UNAVAILABLE, BYMAX_TIMING_SINK, BYMAX_TOO_MANY_REQUESTS, BYMAX_TRACE_CONTEXT, BYMAX_UNAUTHORIZED, BYMAX_UNPROCESSABLE_ENTITY, BYMAX_UNSUPPORTED_MEDIA_TYPE, BYMAX_VALIDATION_FAILED, type BuildErrorEnvelopeInput, BymaxCoreModule, type BymaxCoreModuleOptions, BymaxExceptionFilter, BymaxTimingMiddleware, type EnvelopeOptions, type ErrorDetails, type ErrorEnvelope, type FilterErrorContext, type HealthOptions, type ICorrelationIdProvider, type ITimingSink, type ITraceContextProvider, type MetricsOptions, type OpenApiHttpMethod, type OpenApiOperationIdFactory, type OpenApiOperationKey, type OpenApiOptions, type OpenApiSecurityRequirement, type OpenApiSecurityScheme, type OpenApiServerDescriptor, type OperationSecurityMap, type RequestTimingSample, type ResolvedCoreOptions, type TelemetryOptions, TimingInterceptor, type TimingOptions, type TraceContext, UNMATCHED_ROUTE, buildErrorEnvelope, codeForStatus };
+export { BYMAX_BAD_GATEWAY, BYMAX_BAD_REQUEST, BYMAX_CLIENT_ERROR, BYMAX_CONFLICT, BYMAX_CORE_OPTIONS, BYMAX_CORRELATION_PROVIDER, BYMAX_FORBIDDEN, BYMAX_GATEWAY_TIMEOUT, BYMAX_HEALTH_INDICATORS, BYMAX_HEALTH_TRANSITION_SINK, BYMAX_INTERNAL_ERROR, BYMAX_METRICS_REGISTRY, BYMAX_NOT_FOUND, BYMAX_NOT_IMPLEMENTED, BYMAX_PAYLOAD_TOO_LARGE, BYMAX_SERVICE_UNAVAILABLE, BYMAX_TIMING_SINK, BYMAX_TOO_MANY_REQUESTS, BYMAX_TRACE_CONTEXT, BYMAX_UNAUTHORIZED, BYMAX_UNEXPECTED_ERROR_SINK, BYMAX_UNPROCESSABLE_ENTITY, BYMAX_UNSUPPORTED_MEDIA_TYPE, BYMAX_VALIDATION_FAILED, type BuildErrorEnvelopeInput, BymaxCoreModule, type BymaxCoreModuleOptions, BymaxExceptionFilter, BymaxTimingMiddleware, type EnvelopeOptions, type ErrorDetails, type ErrorEnvelope, type FilterErrorContext, type HealthOptions, type ICorrelationIdProvider, type ITimingSink, type ITraceContextProvider, type IUnexpectedErrorSink, type MetricsOptions, type OpenApiHttpMethod, type OpenApiOperationIdFactory, type OpenApiOperationKey, type OpenApiOptions, type OpenApiSecurityRequirement, type OpenApiSecurityScheme, type OpenApiServerDescriptor, type OperationSecurityMap, type RequestTimingSample, type ResolvedCoreOptions, type TelemetryOptions, TimingInterceptor, type TimingOptions, type TraceContext, UNMATCHED_ROUTE, type UnexpectedErrorReport, buildErrorEnvelope, codeForStatus };

package/dist/index.mjs

@@ -158,6 +158,9 @@ var BYMAX_HEALTH_INDICATORS = /* @__PURE__ */ Symbol.for(
 var BYMAX_HEALTH_TRANSITION_SINK = /* @__PURE__ */ Symbol.for(
   "@bymax-one/nest-core:health-transition-sink"
 );
+var BYMAX_UNEXPECTED_ERROR_SINK = /* @__PURE__ */ Symbol.for(
+  "@bymax-one/nest-core:unexpected-error-sink"
+);
 var BYMAX_METRICS_REGISTRY = /* @__PURE__ */ Symbol.for(
   "@bymax-one/nest-core:metrics-registry"
 );
@@ -263,6 +266,13 @@ function buildTraceContextProvider() {
   };
 }
 
+// src/contain-rejection.ts
+function containRejection(returned, onFailure) {
+  if (typeof returned?.then === "function") {
+    Promise.resolve(returned).catch(onFailure);
+  }
+}
+
 // src/envelope/error-codes.ts
 var BYMAX_BAD_REQUEST = "BYMAX_BAD_REQUEST";
 var BYMAX_VALIDATION_FAILED = "BYMAX_VALIDATION_FAILED";
@@ -326,6 +336,23 @@ function buildErrorEnvelope(input) {
   };
 }
 
+// src/timing/request-info.accessor.ts
+var UNMATCHED_ROUTE = "<unmatched>";
+function readExpressTemplate(request) {
+  const path = request.route?.path;
+  return path === void 0 ? void 0 : `${request.baseUrl ?? ""}${path}`;
+}
+function readFastifyTemplate(request) {
+  return request.routeOptions?.url;
+}
+function readRequestInfo(request) {
+  const template = readExpressTemplate(request) ?? readFastifyTemplate(request);
+  return { method: request.method ?? "", route: template ?? UNMATCHED_ROUTE };
+}
+function extractRequestInfo(context) {
+  return readRequestInfo(context.switchToHttp().getRequest());
+}
+
 // src/envelope/exception.filter.ts
 var INTERNAL_ERROR_STATUS = 500;
 var INTERNAL_ERROR_MESSAGE = "Internal server error";
@@ -406,10 +433,13 @@ var BymaxExceptionFilter = class {
    *   (from their own, globally-visible module) is not shadowed by one; when
    *   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.
+   * @param traceContext - Reader for the active trace; a no-op when unbound.
+   * @param unexpectedErrorSink - Receives every unexpected error; unbound by default.
    */
-  constructor(options, correlation, adapterHost, traceContext) {
+  constructor(options, correlation, adapterHost, traceContext, unexpectedErrorSink) {
     this.options = options;
     this.adapterHost = adapterHost;
+    this.unexpectedErrorSink = unexpectedErrorSink;
     /** Clock used to stamp the envelope timestamp; overridable in tests via fake timers. */
     this.now = () => /* @__PURE__ */ new Date();
     this.correlation = correlation ?? new NoopCorrelationIdProvider();
@@ -468,19 +498,20 @@ var BymaxExceptionFilter = class {
       ...correlationId !== void 0 ? { correlationId } : {},
       ...traceId !== void 0 ? { traceId } : {}
     };
-    const envelope = this.buildEnvelope(exception, context);
+    const envelope = this.buildEnvelope(exception, context, request);
     httpAdapter.reply(response, envelope, envelope.statusCode);
   }
   /**
    * Select the mapping rule for the exception and build its envelope. An
-   * unknown error is handed to the observability seam before it collapses, so
-   * an integration can record the original error with the request context.
+   * unknown error is handed to the observability seam once its envelope is
+   * built, so an integration can record the original error with the context.
    *
    * @param exception - The error that escaped the handler.
    * @param context - The neutral request context.
+   * @param request - The framework request, read only for the sink's route template.
    * @returns The formatted envelope.
    */
-  buildEnvelope(exception, context) {
+  buildEnvelope(exception, context, request) {
     if (exception instanceof HttpException) {
       return this.mapHttpException(exception, context);
     }
@@ -493,11 +524,39 @@ var BymaxExceptionFilter = class {
         context
       );
     }
+    const envelope = this.mapUnknown(exception, context);
     try {
       this.onUnexpectedError(exception, context);
     } catch {
     }
-    return this.mapUnknown(exception, context);
+    this.reportUnexpected(exception, context, request);
+    return envelope;
+  }
+  /**
+   * Hand an unexpected error to the bound sink, if any. Whatever the sink does
+   * — throw, or return a promise that rejects — is absorbed: the response must
+   * not depend on it. See `IUnexpectedErrorSink` for the contract.
+   *
+   * @param error - The original thrown value.
+   * @param context - The neutral request context.
+   * @param request - The framework request, read for its route template only.
+   */
+  reportUnexpected(error, context, request) {
+    const sink = this.unexpectedErrorSink;
+    if (sink === void 0) {
+      return;
+    }
+    try {
+      const report = {
+        error,
+        method: context.method,
+        route: readRequestInfo(request).route,
+        ...context.correlationId !== void 0 ? { correlationId: context.correlationId } : {},
+        ...context.traceId !== void 0 ? { traceId: context.traceId } : {}
+      };
+      containRejection(sink.record(report), () => void 0);
+    } catch {
+    }
   }
   /**
    * Map an `HttpException` to the envelope. A domain error passes its own code,
@@ -587,7 +646,7 @@ var BymaxExceptionFilter = class {
   }
   /**
    * Observability seam invoked for every unexpected (non-`HttpException`) error
-   * before it collapses to the generic 500. The base implementation is a no-op:
+   * collapsed to the generic 500. The base implementation is a no-op:
    * this library owns no logger. An integration (for example
    * `@bymax-one/nest-logger`) subclasses the filter and overrides this to record
    * the original error with the current request context and correlation id.
@@ -606,7 +665,9 @@ BymaxExceptionFilter = __decorateClass([
   __decorateParam(1, Inject(BYMAX_CORRELATION_PROVIDER)),
   __decorateParam(2, Inject(HttpAdapterHost)),
   __decorateParam(3, Optional()),
-  __decorateParam(3, Inject(BYMAX_TRACE_CONTEXT))
+  __decorateParam(3, Inject(BYMAX_TRACE_CONTEXT)),
+  __decorateParam(4, Optional()),
+  __decorateParam(4, Inject(BYMAX_UNEXPECTED_ERROR_SINK))
 ], BymaxExceptionFilter);
 var PassThroughExceptionFilter = class {
   constructor(adapterHost) {
@@ -633,15 +694,8 @@ function assertAsyncFeatureEnabled(feature, enabled) {
     );
   }
 }
-function selectAsyncExceptionFilter(options, correlation, adapterHost) {
-  return options.envelope.enabled ? new BymaxExceptionFilter(options, correlation, adapterHost) : new PassThroughExceptionFilter(adapterHost);
-}
-
-// src/contain-rejection.ts
-function containRejection(returned, onFailure) {
-  if (typeof returned?.then === "function") {
-    Promise.resolve(returned).catch(onFailure);
-  }
+function selectAsyncExceptionFilter(options, correlation, adapterHost, traceContext, unexpectedErrorSink) {
+  return options.envelope.enabled ? new BymaxExceptionFilter(options, correlation, adapterHost, traceContext, unexpectedErrorSink) : new PassThroughExceptionFilter(adapterHost);
 }
 
 // src/discovery.ts
@@ -1352,23 +1406,6 @@ function isFastifyInstance(instance) {
   return typeof instance?.addHook === "function";
 }
 
-// src/timing/request-info.accessor.ts
-var UNMATCHED_ROUTE = "<unmatched>";
-function readExpressTemplate(request) {
-  const path = request.route?.path;
-  return path === void 0 ? void 0 : `${request.baseUrl ?? ""}${path}`;
-}
-function readFastifyTemplate(request) {
-  return request.routeOptions?.url;
-}
-function readRequestInfo(request) {
-  const template = readExpressTemplate(request) ?? readFastifyTemplate(request);
-  return { method: request.method ?? "", route: template ?? UNMATCHED_ROUTE };
-}
-function extractRequestInfo(context) {
-  return readRequestInfo(context.switchToHttp().getRequest());
-}
-
 // src/timing/timing.sample.ts
 function readTraceContext(traceContext) {
   try {
@@ -1527,11 +1564,22 @@ function buildAsyncSlots() {
   return [
     {
       provide: APP_FILTER,
-      useFactory: (options, correlation, adapterHost) => selectAsyncExceptionFilter(options, correlation, adapterHost),
+      useFactory: (options, correlation, adapterHost, traceContext, unexpectedErrorSink) => selectAsyncExceptionFilter(
+        options,
+        correlation,
+        adapterHost,
+        traceContext,
+        unexpectedErrorSink
+      ),
+      // Every constructor dependency the sync path resolves through `useClass`
+      // has to be listed here by hand; one left out reaches the filter as its
+      // no-op fallback and nothing fails.
       inject: [
         BYMAX_CORE_OPTIONS,
         { token: BYMAX_CORRELATION_PROVIDER, optional: true },
-        HttpAdapterHost
+        HttpAdapterHost,
+        BYMAX_TRACE_CONTEXT,
+        { token: BYMAX_UNEXPECTED_ERROR_SINK, optional: true }
       ]
     }
   ];
@@ -1811,4 +1859,4 @@ TimingInterceptor = __decorateClass([
   __decorateParam(3, Inject(BYMAX_TRACE_CONTEXT))
 ], TimingInterceptor);
 
-export { BYMAX_BAD_GATEWAY, BYMAX_BAD_REQUEST, BYMAX_CLIENT_ERROR, BYMAX_CONFLICT, BYMAX_CORE_OPTIONS, BYMAX_CORRELATION_PROVIDER, BYMAX_FORBIDDEN, BYMAX_GATEWAY_TIMEOUT, BYMAX_HEALTH_INDICATORS, BYMAX_HEALTH_TRANSITION_SINK, BYMAX_INTERNAL_ERROR, BYMAX_METRICS_REGISTRY, BYMAX_NOT_FOUND, BYMAX_NOT_IMPLEMENTED, BYMAX_PAYLOAD_TOO_LARGE, BYMAX_SERVICE_UNAVAILABLE, BYMAX_TIMING_SINK, BYMAX_TOO_MANY_REQUESTS, BYMAX_TRACE_CONTEXT, BYMAX_UNAUTHORIZED, BYMAX_UNPROCESSABLE_ENTITY, BYMAX_UNSUPPORTED_MEDIA_TYPE, BYMAX_VALIDATION_FAILED, BymaxCoreModule, BymaxExceptionFilter, BymaxTimingMiddleware, TimingInterceptor, UNMATCHED_ROUTE, buildErrorEnvelope, codeForStatus };
+export { BYMAX_BAD_GATEWAY, BYMAX_BAD_REQUEST, BYMAX_CLIENT_ERROR, BYMAX_CONFLICT, BYMAX_CORE_OPTIONS, BYMAX_CORRELATION_PROVIDER, BYMAX_FORBIDDEN, BYMAX_GATEWAY_TIMEOUT, BYMAX_HEALTH_INDICATORS, BYMAX_HEALTH_TRANSITION_SINK, BYMAX_INTERNAL_ERROR, BYMAX_METRICS_REGISTRY, BYMAX_NOT_FOUND, BYMAX_NOT_IMPLEMENTED, BYMAX_PAYLOAD_TOO_LARGE, BYMAX_SERVICE_UNAVAILABLE, BYMAX_TIMING_SINK, BYMAX_TOO_MANY_REQUESTS, BYMAX_TRACE_CONTEXT, BYMAX_UNAUTHORIZED, BYMAX_UNEXPECTED_ERROR_SINK, BYMAX_UNPROCESSABLE_ENTITY, BYMAX_UNSUPPORTED_MEDIA_TYPE, BYMAX_VALIDATION_FAILED, BymaxCoreModule, BymaxExceptionFilter, BymaxTimingMiddleware, TimingInterceptor, UNMATCHED_ROUTE, buildErrorEnvelope, codeForStatus };