@bymax-one/nest-core 1.6.1 → 1.6.2

package/CHANGELOG.md

@@ -11,6 +11,56 @@ heading here.
 
 ## [Unreleased]
 
+## [1.6.2] - 2026-10-22
+
+An unexpected error became `500 BYMAX_INTERNAL_ERROR` and the application had no
+way to record what it was. `BymaxCoreModule` builds the filter itself, and the
+only seam — the protected `onUnexpectedError` — is reachable only by subclassing
+a filter the module never lets you substitute. So the access log saw the status
+and nothing else, and a 500 on a read endpoint left no recoverable cause.
+
+**This patch adds public surface**, which a patch number cannot tell you: the
+`BYMAX_UNEXPECTED_ERROR_SINK` token and the `IUnexpectedErrorSink` and
+`UnexpectedErrorReport` types. All are additive and nothing is removed or
+renamed, so the digit stays at a patch under this project's versioning policy.
+
+**Apply to a derived backend:** nothing is required; with no sink bound the
+filter behaves as before. To record each unexpected error's cause, bind an
+`IUnexpectedErrorSink` under `BYMAX_UNEXPECTED_ERROR_SINK` from a `@Global()`
+module of your own, as the README's "Recording the cause of a 500" shows. A
+backend registered through `forRootAsync` with `telemetry.exposeTraceId` on
+starts serving `traceId` in its error envelopes, which it was configured to do
+and did not; see Fixed.
+
+### Added
+
+- **`BYMAX_UNEXPECTED_ERROR_SINK`, `IUnexpectedErrorSink` and
+  `UnexpectedErrorReport`.** The filter calls `record(report)` once per
+  unexpected error, before replying, with the original thrown value, the
+  method, the matched route template (`<unmatched>` before routing), and the
+  correlation and trace ids when they resolve. An `HttpException` and an
+  exposed `4xx` from the body pipeline never reach it.
+
+  The report carries no raw URL, query string, headers or body: a log outlives
+  the request and a query string is where tokens end up. The thrown value is
+  passed uncut whatever `envelope.exposeInternals` says, since that option
+  governs the response and the sink is not the response.
+
+  The response never depends on the sink. A synchronous throw is caught and an
+  `async record()` rejection is contained, both silently. The interface is
+  structural, so a logging library can ship a compatible class without
+  importing this package. The protected `onUnexpectedError` seam is unchanged
+  and runs alongside the sink.
+
+### Fixed
+
+- **`forRootAsync` never put the trace id in the error envelope.** The async
+  filter slot is built by a factory whose injection list did not include
+  `BYMAX_TRACE_CONTEXT`, so the filter fell back to its no-op reader: with
+  `telemetry.exposeTraceId` on, `forRoot` served `traceId` and `forRootAsync`
+  silently did not. The factory now injects every dependency the sync path
+  resolves through the class.
+
 ## [1.6.1] - 2026-09-05
 
 A library contributing an OpenAPI component under a name the application already
@@ -1087,4 +1137,5 @@ have regressed from. They are kept because the reasoning is worth having.
 [1.5.3]: https://github.com/bymaxone/nest-core/compare/v1.5.2...v1.5.3
 [1.6.0]: https://github.com/bymaxone/nest-core/compare/v1.5.3...v1.6.0
 [1.6.1]: https://github.com/bymaxone/nest-core/compare/v1.6.0...v1.6.1
-[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.6.1...HEAD
+[1.6.2]: https://github.com/bymaxone/nest-core/compare/v1.6.1...v1.6.2
+[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.6.2...HEAD

package/README.md

@@ -516,8 +516,9 @@ requirement.
 ## 🔑 DI Tokens
 
 Every token is a `Symbol`. `BYMAX_CORRELATION_PROVIDER`,
-`BYMAX_HEALTH_INDICATORS` and `BYMAX_HEALTH_TRANSITION_SINK` are consumed with
-`@Optional()` and are not bound by the module: provide either from your own module to supply your own
+`BYMAX_HEALTH_INDICATORS`, `BYMAX_HEALTH_TRANSITION_SINK` and
+`BYMAX_UNEXPECTED_ERROR_SINK` are consumed with `@Optional()` and are not bound
+by the module: provide any of them from your own module to supply your own
 implementation, otherwise the internal fallback in the last column applies.
 `BYMAX_TIMING_SINK` and `BYMAX_METRICS_REGISTRY` behave differently on
 `forRootAsync`, where options resolve after the module is defined: there the
@@ -535,6 +536,7 @@ below.
 | `BYMAX_TIMING_SINK`            | `ITimingSink`                         | internal no-op, or the metrics bridge when timing and metrics are both enabled                                    |
 | `BYMAX_HEALTH_INDICATORS`      | `IHealthIndicator[]`                  | treated as an empty indicator set                                                                                 |
 | `BYMAX_HEALTH_TRANSITION_SINK` | `IHealthTransitionSink`               | no sink; readiness transitions go to Nest's logger instead (binding one stands that line down)                    |
+| `BYMAX_UNEXPECTED_ERROR_SINK`  | `IUnexpectedErrorSink`                | no sink; the cause of a `500 BYMAX_INTERNAL_ERROR` is not recorded anywhere                                       |
 | `BYMAX_METRICS_REGISTRY`       | the `prom-client` `Registry`          | bound when metrics are enabled; on `forRootAsync` always registered, guarded-placeholder when off                 |
 | `BYMAX_TRACE_CONTEXT`          | `ITraceContextProvider`               | bound on every path: the OpenTelemetry reader when telemetry is enabled, a no-op that resolves no trace otherwise |
 
@@ -667,6 +669,62 @@ what exhausts the stack leaves a wide margin: one consumer runs `32`, against
 the ~2000 levels that overflow. Walk the parsed body iteratively — a recursive
 depth check on a hostile payload overflows the stack it was written to protect.
 
+### Recording the cause of a 500
+
+An error the filter does not recognise collapses to a fixed
+`500 BYMAX_INTERNAL_ERROR`, and that collapse is the point: the client learns
+nothing about your internals. It also means that once the response is written,
+the thrown value is gone — an access log sees only the status. Bind an
+`IUnexpectedErrorSink` and the filter hands it the original value first:
+
+```typescript
+import { Global, Logger, Module } from '@nestjs/common'
+import { BYMAX_UNEXPECTED_ERROR_SINK } from '@bymax-one/nest-core'
+import type { IUnexpectedErrorSink, UnexpectedErrorReport } from '@bymax-one/nest-core'
+
+export class UnexpectedErrorLogger implements IUnexpectedErrorSink {
+  private readonly logger = new Logger('UnexpectedError')
+
+  record({ error, method, route, correlationId }: UnexpectedErrorReport): void {
+    this.logger.error(
+      `${method} ${route} failed (correlationId=${correlationId ?? '-'})`,
+      error instanceof Error ? error.stack : String(error)
+    )
+  }
+}
+
+@Global()
+@Module({
+  providers: [{ provide: BYMAX_UNEXPECTED_ERROR_SINK, useClass: UnexpectedErrorLogger }],
+  exports: [BYMAX_UNEXPECTED_ERROR_SINK]
+})
+export class ErrorReportingModule {}
+```
+
+The sink is called once per unexpected error, on both registration paths, and
+for nothing else: an `HttpException` is a deliberate answer and an exposed `4xx`
+from the body pipeline is a client mistake, so neither reaches it. The report
+carries the thrown value as it was thrown, the method, the route **template**
+(`/invoices/:id`, or `<unmatched>` for an error raised before routing), and the
+correlation and trace ids when they resolve. It carries no raw URL, query
+string, headers or body.
+
+The response never depends on the sink. A sink that throws, or an
+`async record()` that rejects, is absorbed and the client receives the same
+envelope it would have received with no sink bound, so a broken logger cannot
+turn one failure into two. It runs synchronously before the reply, so hand the
+report off and return.
+
+The value is passed uncut whatever `envelope.exposeInternals` says, since that
+option governs the response body and the sink is not the response. A driver's
+error message can carry hosts and query fragments: send the report where access
+is already controlled.
+
+`IUnexpectedErrorSink` is matched by shape, so a library can ship a compatible
+class without importing this package. Subclassing `BymaxExceptionFilter` and
+overriding `onUnexpectedError` still works and runs alongside the sink; the
+sink is what reaches the filter `BymaxCoreModule` registers itself.
+
 ## ⏱️ Request Timing
 
 One `RequestTimingSample` is delivered to whatever implements `ITimingSink` for
@@ -1739,26 +1797,27 @@ in the sections above.
 
 ### `.` (root)
 
-| Export                                                                                                                                                                                                           | Kind      | Description                                                                        |
-| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------- |
-| `BymaxCoreModule`                                                                                                                                                                                                | class     | The dynamic module: `forRoot` and `forRootAsync`.                                  |
-| `BymaxCoreModuleOptions`, `EnvelopeOptions`, `TimingOptions`, `HealthOptions`, `MetricsOptions`, `TelemetryOptions`, `OpenApiOptions`, `OpenApiServerDescriptor`, `OpenApiSecurityScheme`, `ResolvedCoreOptions` | types     | The options surface and its resolved shape.                                        |
-| `OpenApiSecurityRequirement`, `OpenApiHttpMethod`, `OpenApiOperationKey`, `OperationSecurityMap`                                                                                                                 | types     | The operation-key contract a sibling library targets to ship its own security map. |
-| `OpenApiOperationIdFactory`                                                                                                                                                                                      | type      | Names the operations in the generated document.                                    |
-| `BYMAX_CORE_OPTIONS`, `BYMAX_CORRELATION_PROVIDER`, `BYMAX_TIMING_SINK`, `BYMAX_HEALTH_INDICATORS`, `BYMAX_HEALTH_TRANSITION_SINK`, `BYMAX_METRICS_REGISTRY`, `BYMAX_TRACE_CONTEXT`                              | tokens    | The DI tokens; see the [token table](#-di-tokens).                                 |
-| `IHealthTransitionSink`, `HealthTransition`, `HealthTransitionCause`                                                                                                                                             | types     | The readiness-transition contract; also on `./health`.                             |
-| `ICorrelationIdProvider`                                                                                                                                                                                         | type      | The correlation-provider contract.                                                 |
-| `ITraceContextProvider`, `TraceContext`                                                                                                                                                                          | types     | The trace-context contract and the identifiers it resolves.                        |
-| `BymaxExceptionFilter`                                                                                                                                                                                           | class     | The envelope exception filter.                                                     |
-| `FilterErrorContext`                                                                                                                                                                                             | type      | The neutral request context passed to the filter's observability seam.             |
-| `buildErrorEnvelope`                                                                                                                                                                                             | function  | Pure builder assembling an `ErrorEnvelope`.                                        |
-| `ErrorEnvelope`, `ErrorDetails`, `BuildErrorEnvelopeInput`                                                                                                                                                       | types     | The envelope contract and its builder input.                                       |
-| `BymaxTimingMiddleware`                                                                                                                                                                                          | class     | The request-timing middleware, applied to every route when timing is enabled.      |
-| `UNMATCHED_ROUTE`                                                                                                                                                                                                | constant  | The bounded label recorded when a request matched no route (`<unmatched>`).        |
-| `TimingInterceptor`                                                                                                                                                                                              | class     | Deprecated: superseded by `BymaxTimingMiddleware`, which the module registers.     |
-| `ITimingSink`, `RequestTimingSample`                                                                                                                                                                             | types     | The timing-sink contract and its sample shape.                                     |
-| `BYMAX_BAD_GATEWAY` … `BYMAX_VALIDATION_FAILED`                                                                                                                                                                  | constants | The full error-code catalog (see [Error envelope](#-error-envelope)).              |
-| `codeForStatus`                                                                                                                                                                                                  | function  | Derives a catalog code from an HTTP status.                                        |
+| Export                                                                                                                                                                                                             | Kind      | Description                                                                                                                             |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `BymaxCoreModule`                                                                                                                                                                                                  | class     | The dynamic module: `forRoot` and `forRootAsync`.                                                                                       |
+| `BymaxCoreModuleOptions`, `EnvelopeOptions`, `TimingOptions`, `HealthOptions`, `MetricsOptions`, `TelemetryOptions`, `OpenApiOptions`, `OpenApiServerDescriptor`, `OpenApiSecurityScheme`, `ResolvedCoreOptions`   | types     | The options surface and its resolved shape.                                                                                             |
+| `OpenApiSecurityRequirement`, `OpenApiHttpMethod`, `OpenApiOperationKey`, `OperationSecurityMap`                                                                                                                   | types     | The operation-key contract a sibling library targets to ship its own security map.                                                      |
+| `OpenApiOperationIdFactory`                                                                                                                                                                                        | type      | Names the operations in the generated document.                                                                                         |
+| `BYMAX_CORE_OPTIONS`, `BYMAX_CORRELATION_PROVIDER`, `BYMAX_TIMING_SINK`, `BYMAX_HEALTH_INDICATORS`, `BYMAX_HEALTH_TRANSITION_SINK`, `BYMAX_UNEXPECTED_ERROR_SINK`, `BYMAX_METRICS_REGISTRY`, `BYMAX_TRACE_CONTEXT` | tokens    | The DI tokens; see the [token table](#-di-tokens).                                                                                      |
+| `IHealthTransitionSink`, `HealthTransition`, `HealthTransitionCause`                                                                                                                                               | types     | The readiness-transition contract; also on `./health`.                                                                                  |
+| `ICorrelationIdProvider`                                                                                                                                                                                           | type      | The correlation-provider contract.                                                                                                      |
+| `ITraceContextProvider`, `TraceContext`                                                                                                                                                                            | types     | The trace-context contract and the identifiers it resolves.                                                                             |
+| `BymaxExceptionFilter`                                                                                                                                                                                             | class     | The envelope exception filter.                                                                                                          |
+| `FilterErrorContext`                                                                                                                                                                                               | type      | The neutral request context passed to the filter's observability seam.                                                                  |
+| `IUnexpectedErrorSink`, `UnexpectedErrorReport`                                                                                                                                                                    | types     | Receives the cause behind each collapsed `500 BYMAX_INTERNAL_ERROR`; see [Recording the cause of a 500](#recording-the-cause-of-a-500). |
+| `buildErrorEnvelope`                                                                                                                                                                                               | function  | Pure builder assembling an `ErrorEnvelope`.                                                                                             |
+| `ErrorEnvelope`, `ErrorDetails`, `BuildErrorEnvelopeInput`                                                                                                                                                         | types     | The envelope contract and its builder input.                                                                                            |
+| `BymaxTimingMiddleware`                                                                                                                                                                                            | class     | The request-timing middleware, applied to every route when timing is enabled.                                                           |
+| `UNMATCHED_ROUTE`                                                                                                                                                                                                  | constant  | The bounded label recorded when a request matched no route (`<unmatched>`).                                                             |
+| `TimingInterceptor`                                                                                                                                                                                                | class     | Deprecated: superseded by `BymaxTimingMiddleware`, which the module registers.                                                          |
+| `ITimingSink`, `RequestTimingSample`                                                                                                                                                                               | types     | The timing-sink contract and its sample shape.                                                                                          |
+| `BYMAX_BAD_GATEWAY` … `BYMAX_VALIDATION_FAILED`                                                                                                                                                                    | constants | The full error-code catalog (see [Error envelope](#-error-envelope)).                                                                   |
+| `codeForStatus`                                                                                                                                                                                                    | function  | Derives a catalog code from an HTTP status.                                                                                             |
 
 ### `./pagination`
 

package/dist/index.cjs

@@ -160,6 +160,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"
 );
@@ -265,6 +268,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";
@@ -328,6 +338,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";
@@ -408,10 +435,13 @@ exports.BymaxExceptionFilter = class BymaxExceptionFilter {
    *   (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();
@@ -470,19 +500,20 @@ exports.BymaxExceptionFilter = class BymaxExceptionFilter {
       ...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 common.HttpException) {
       return this.mapHttpException(exception, context);
     }
@@ -495,11 +526,39 @@ exports.BymaxExceptionFilter = class BymaxExceptionFilter {
         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,
@@ -589,7 +648,7 @@ exports.BymaxExceptionFilter = class BymaxExceptionFilter {
   }
   /**
    * 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.
@@ -608,7 +667,9 @@ exports.BymaxExceptionFilter = __decorateClass([
   __decorateParam(1, common.Inject(BYMAX_CORRELATION_PROVIDER)),
   __decorateParam(2, common.Inject(core.HttpAdapterHost)),
   __decorateParam(3, common.Optional()),
-  __decorateParam(3, common.Inject(BYMAX_TRACE_CONTEXT))
+  __decorateParam(3, common.Inject(BYMAX_TRACE_CONTEXT)),
+  __decorateParam(4, common.Optional()),
+  __decorateParam(4, common.Inject(BYMAX_UNEXPECTED_ERROR_SINK))
 ], exports.BymaxExceptionFilter);
 var PassThroughExceptionFilter = class {
   constructor(adapterHost) {
@@ -635,15 +696,8 @@ function assertAsyncFeatureEnabled(feature, enabled) {
     );
   }
 }
-function selectAsyncExceptionFilter(options, correlation, adapterHost) {
-  return options.envelope.enabled ? new exports.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 exports.BymaxExceptionFilter(options, correlation, adapterHost, traceContext, unexpectedErrorSink) : new PassThroughExceptionFilter(adapterHost);
 }
 
 // src/discovery.ts
@@ -1354,23 +1408,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 {
@@ -1529,11 +1566,22 @@ function buildAsyncSlots() {
   return [
     {
       provide: core.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 },
-        core.HttpAdapterHost
+        core.HttpAdapterHost,
+        BYMAX_TRACE_CONTEXT,
+        { token: BYMAX_UNEXPECTED_ERROR_SINK, optional: true }
       ]
     }
   ];
@@ -1833,6 +1881,7 @@ 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_UNEXPECTED_ERROR_SINK = BYMAX_UNEXPECTED_ERROR_SINK;
 exports.BYMAX_UNPROCESSABLE_ENTITY = BYMAX_UNPROCESSABLE_ENTITY;
 exports.BYMAX_UNSUPPORTED_MEDIA_TYPE = BYMAX_UNSUPPORTED_MEDIA_TYPE;
 exports.BYMAX_VALIDATION_FAILED = BYMAX_VALIDATION_FAILED;

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 };

package/dist/openapi/index.cjs

@@ -594,14 +594,13 @@ function augmentDocument(document, options, pathPrefixes = [""], contributions =
   const merged = new Map(Object.entries(components));
   if (openapi.includeCoreSchemas) {
     const keep = () => void 0;
-    merged.set(
-      "schemas",
-      placeComponentEntries(components["schemas"], "schemas", CORE_SCHEMAS, keep)
-    );
-    merged.set(
-      "parameters",
-      placeComponentEntries(components["parameters"], "parameters", CORE_PARAMETERS, keep)
-    );
+    const catalogue = [
+      ["schemas", CORE_SCHEMAS],
+      ["parameters", CORE_PARAMETERS]
+    ];
+    for (const [member, entries] of catalogue) {
+      merged.set(member, placeComponentEntries(merged.get(member), member, entries, keep));
+    }
   }
   const scrapeScheme = options.metrics.authToken === void 0 ? {} : {
     [METRICS_SCHEME_NAME]: {

package/dist/openapi/index.mjs

@@ -592,14 +592,13 @@ function augmentDocument(document, options, pathPrefixes = [""], contributions =
   const merged = new Map(Object.entries(components));
   if (openapi.includeCoreSchemas) {
     const keep = () => void 0;
-    merged.set(
-      "schemas",
-      placeComponentEntries(components["schemas"], "schemas", CORE_SCHEMAS, keep)
-    );
-    merged.set(
-      "parameters",
-      placeComponentEntries(components["parameters"], "parameters", CORE_PARAMETERS, keep)
-    );
+    const catalogue = [
+      ["schemas", CORE_SCHEMAS],
+      ["parameters", CORE_PARAMETERS]
+    ];
+    for (const [member, entries] of catalogue) {
+      merged.set(member, placeComponentEntries(merged.get(member), member, entries, keep));
+    }
   }
   const scrapeScheme = options.metrics.authToken === void 0 ? {} : {
     [METRICS_SCHEME_NAME]: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-core",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "description": "Zero-dependency NestJS 11 application foundation kit: error-envelope exception filter, request-timing interceptor, pagination helpers, health endpoints with indicator discovery, an optional Prometheus metrics endpoint with a contribution contract, OpenAPI documents in development, and OpenTelemetry trace correlation.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",