@bymax-one/nest-core 1.6.1 → 1.6.3

package/CHANGELOG.md

@@ -11,6 +11,110 @@ heading here.
 
 ## [Unreleased]
 
+## [1.6.3] - 2026-10-23
+
+The error envelope's `path` carried the query string, and the documented
+recipe for pairing with `@bymax-one/nest-logger` bound nothing.
+
+**Apply to a derived backend:**
+
+- **`path` changes in the response body.** An application that reads `path`
+  from the envelope now gets the request path alone. `/invoices/42?token=x`
+  and `http://host/invoices/42` both now read `/invoices/42`. The query string was never part of the documented
+  contract, and is where reset codes and tokens travel.
+- **The nest-logger correlation recipe changes.** An application that
+  followed the previous README recipe bound
+  `BYMAX_CORRELATION_PROVIDER` to `LogContextService` with `useExisting`, and
+  got no correlation id at all. Replace it with the `useFactory` in the
+  README's "Integration with `@bymax-one/nest-logger`", and make sure
+  nest-logger's request-id middleware is mounted (`applyAccessLog(app)` or
+  `applyRequestIdMiddleware(consumer)`). Without it there is no id to read.
+
+### Fixed
+
+- **The envelope `path` no longer carries the query string.** Both adapters
+  report the original URL, query included: Express returns `originalUrl`, and
+  Fastify the raw URL. The filter copied that into `path`, which is documented
+  as the request URL path. So a query-string secret reached the client and any
+  log that stores the envelope. An absolute-form target, as a proxy sends it,
+  also carried its scheme, authority and any credentials; only the path is
+  kept now. The `onUnexpectedError` context now receives the same path. The unexpected-error sink already reported the route
+  template and is unaffected.
+- **The nest-logger integration recipe binds what it promises.** It imported
+  `NestLoggerModule`, which does not exist; the module is `BymaxLoggerModule`.
+  It also aliased `LogContextService` with `useExisting`, but that service
+  has no `getCorrelationId()`. The binding was inert, and silently so: the
+  filter treats a failing correlation read as "no id". The README and the
+  specification now adapt the `requestId` key with a factory; the README
+  binds `PinoUnexpectedErrorSink` (nest-logger 1.4.1) beside it. The snippet
+  passed the published-surface gate before only because that gate ignores
+  diagnostics from a peer the fixture does not install.
+- **A thrown value that cannot be described no longer breaks the response.**
+  With `envelope.exposeInternals` on, a value with no prototype, or an `Error`
+  whose `stack` getter throws, threw out of the filter. The internals dump now
+  degrades to a fixed message, and the hooks still run.
+- **The discard warning no longer claims a mismatch for identical entries.**
+  It now says a generated client will not match the library's own types only
+  where the two definitions differ.
+
+### Changed
+
+- **Served component order (since 1.6.1).** Since 1.6.1, a document's own
+  `components.schemas` and `components.parameters` entries are listed before
+  this package's catalogue and before contributed entries. The 1.6.1 entry did
+  not say so. Order in a components map carries no meaning in OpenAPI, but it
+  shows in Swagger UI's model list and in a stored `openapi.json` snapshot.
+
+## [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 +1191,6 @@ 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
+[1.6.3]: https://github.com/bymaxone/nest-core/compare/v1.6.2...v1.6.3
+[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.6.3...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
@@ -1488,27 +1546,67 @@ your samples and your logs.
 
 ## 🔗 Integration with `@bymax-one/nest-logger`
 
-Pairing this package with `@bymax-one/nest-logger` yields correlated logs and
-error responses with one binding and no hard coupling: `LogContextService`
-satisfies `ICorrelationIdProvider` out of the box, so `useExisting` aliases it
-onto the shared token. Bind it from a `@Global()` module of your own so the
-binding is visible outside the module that declares it:
+Pairing this package with `@bymax-one/nest-logger` gives correlated logs and
+error responses without either package importing the other. nest-logger's
+request-id middleware stores the id under the `requestId` key of
+`LogContextService`. That service is not itself an `ICorrelationIdProvider` —
+it has no `getCorrelationId()` — so adapt it with a factory. `useExisting` on
+it binds an object without that method, and the filter then reads no id and
+reports nothing. Bind both tokens from a `@Global()` module of your own so they
+are visible outside the module that declares them:
 
 ```typescript
 import { Global, Module } from '@nestjs/common'
-import { BYMAX_CORRELATION_PROVIDER } from '@bymax-one/nest-core'
-import { LogContextService, NestLoggerModule } from '@bymax-one/nest-logger'
+import { BYMAX_CORRELATION_PROVIDER, BYMAX_UNEXPECTED_ERROR_SINK } from '@bymax-one/nest-core'
+import type { ICorrelationIdProvider } from '@bymax-one/nest-core'
+import {
+  BymaxLoggerModule,
+  LogContextService,
+  PinoUnexpectedErrorSink
+} from '@bymax-one/nest-logger'
 
 @Global()
 @Module({
-  imports: [NestLoggerModule.forRoot()],
-  providers: [{ provide: BYMAX_CORRELATION_PROVIDER, useExisting: LogContextService }],
-  exports: [BYMAX_CORRELATION_PROVIDER]
+  imports: [BymaxLoggerModule.forRoot({ service: { name: 'api', version: '1.0.0' } })],
+  providers: [
+    {
+      provide: BYMAX_CORRELATION_PROVIDER,
+      inject: [LogContextService],
+      useFactory: (context: LogContextService): ICorrelationIdProvider => ({
+        getCorrelationId: () => context.get<string>('requestId')
+      })
+    },
+    { provide: BYMAX_UNEXPECTED_ERROR_SINK, useClass: PinoUnexpectedErrorSink }
+  ],
+  exports: [BYMAX_CORRELATION_PROVIDER, BYMAX_UNEXPECTED_ERROR_SINK]
 })
 export class ObservabilityModule {}
 ```
 
-Every error envelope now carries the same correlation id your logs do. The
+The id exists only once nest-logger's request-id middleware runs, and
+`BymaxLoggerModule` mounts none on its own. Mount it in `main.ts`, or call
+`applyRequestIdMiddleware(consumer)` from a module's `configure()`:
+
+> **Express only.** nest-logger's request-id middleware supports
+> `@nestjs/platform-express`; the Fastify adapter is unsupported, so do not
+> rely on this correlation provider there.
+
+```typescript
+import { NestFactory } from '@nestjs/core'
+import { applyAccessLog } from '@bymax-one/nest-logger'
+import { AppModule } from './app.module'
+
+async function bootstrap(): Promise<void> {
+  const app = await NestFactory.create(AppModule)
+  applyAccessLog(app) // opens the request context that carries `requestId`
+  await app.listen(3000)
+}
+void bootstrap()
+```
+
+Every error envelope now carries the same correlation id your logs do, and the
+cause of every collapsed `500` is logged with it (`PinoUnexpectedErrorSink`
+needs `@bymax-one/nest-logger` 1.4.1 or later). The
 same `@Global()`-module pattern is how every pluggable token in this package
 is overridden: `BYMAX_TIMING_SINK` and `BYMAX_HEALTH_INDICATORS` follow it
 identically.
@@ -1739,26 +1837,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,10 +338,40 @@ 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";
 var VALIDATION_FAILED_MESSAGE = "Validation failed";
+var ABSOLUTE_FORM_PREFIX = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//;
+function pathOf(url) {
+  let target = String(url);
+  const prefix = ABSOLUTE_FORM_PREFIX.exec(target);
+  if (prefix !== null) {
+    const afterScheme = target.slice(prefix[0].length);
+    const authorityEnd = afterScheme.search(/[/?#]/);
+    target = authorityEnd === -1 ? "" : afterScheme.slice(authorityEnd);
+  }
+  const pathEnd = target.search(/[?#]/);
+  const path = pathEnd === -1 ? target : target.slice(0, pathEnd);
+  return path === "" ? "/" : path;
+}
 function resolveErrorCarrier(response) {
   if (typeof response !== "object" || response === null) {
     return void 0;
@@ -393,11 +433,16 @@ function extractHttpMessage(response, exception, carrier) {
   }
   return exception.message;
 }
+var UNREPRESENTABLE_MESSAGE = "Unrepresentable thrown value";
 function buildInternalDetails(exception) {
-  if (exception instanceof Error) {
-    return exception.stack !== void 0 ? { message: exception.message, stack: exception.stack } : { message: exception.message };
+  try {
+    if (exception instanceof Error) {
+      return exception.stack !== void 0 ? { message: exception.message, stack: exception.stack } : { message: exception.message };
+    }
+    return { message: String(exception) };
+  } catch {
+    return { message: UNREPRESENTABLE_MESSAGE };
   }
-  return { message: String(exception) };
 }
 exports.BymaxExceptionFilter = class BymaxExceptionFilter {
   /**
@@ -408,10 +453,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();
@@ -466,23 +514,24 @@ exports.BymaxExceptionFilter = class BymaxExceptionFilter {
     const traceId = this.readAnnotation(() => this.traceContext.getTraceContext()?.traceId);
     const context = {
       method: String(httpAdapter.getRequestMethod(request)),
-      path: String(httpAdapter.getRequestUrl(request)),
+      path: pathOf(httpAdapter.getRequestUrl(request)),
       ...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 +544,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 +666,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 +685,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 +714,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 +1426,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 +1584,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 +1899,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,10 +336,40 @@ 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";
 var VALIDATION_FAILED_MESSAGE = "Validation failed";
+var ABSOLUTE_FORM_PREFIX = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//;
+function pathOf(url) {
+  let target = String(url);
+  const prefix = ABSOLUTE_FORM_PREFIX.exec(target);
+  if (prefix !== null) {
+    const afterScheme = target.slice(prefix[0].length);
+    const authorityEnd = afterScheme.search(/[/?#]/);
+    target = authorityEnd === -1 ? "" : afterScheme.slice(authorityEnd);
+  }
+  const pathEnd = target.search(/[?#]/);
+  const path = pathEnd === -1 ? target : target.slice(0, pathEnd);
+  return path === "" ? "/" : path;
+}
 function resolveErrorCarrier(response) {
   if (typeof response !== "object" || response === null) {
     return void 0;
@@ -391,11 +431,16 @@ function extractHttpMessage(response, exception, carrier) {
   }
   return exception.message;
 }
+var UNREPRESENTABLE_MESSAGE = "Unrepresentable thrown value";
 function buildInternalDetails(exception) {
-  if (exception instanceof Error) {
-    return exception.stack !== void 0 ? { message: exception.message, stack: exception.stack } : { message: exception.message };
+  try {
+    if (exception instanceof Error) {
+      return exception.stack !== void 0 ? { message: exception.message, stack: exception.stack } : { message: exception.message };
+    }
+    return { message: String(exception) };
+  } catch {
+    return { message: UNREPRESENTABLE_MESSAGE };
   }
-  return { message: String(exception) };
 }
 var BymaxExceptionFilter = class {
   /**
@@ -406,10 +451,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();
@@ -464,23 +512,24 @@ var BymaxExceptionFilter = class {
     const traceId = this.readAnnotation(() => this.traceContext.getTraceContext()?.traceId);
     const context = {
       method: String(httpAdapter.getRequestMethod(request)),
-      path: String(httpAdapter.getRequestUrl(request)),
+      path: pathOf(httpAdapter.getRequestUrl(request)),
       ...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 +542,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 +664,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 +683,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 +712,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 +1424,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 +1582,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 +1877,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]: {
@@ -738,7 +737,7 @@ function warnDiscardedComponents(logger, discarded) {
   const elided = discarded.length - MAX_WARNED_OPERATIONS;
   const listed = discarded.slice(0, MAX_WARNED_OPERATIONS).map(({ contributor, member, name }) => `${contributor} -> ${member}.${name}`).join(", ");
   logger.warn(
-    `the served OpenAPI document already defines ${discarded.length} component entry(ies) a library also contributes: ${listed}${elided > 0 ? `, and ${elided} more` : ""}. The contributed version is not served, so a client generated from this document will not match that library's own types. What holds the name may be the application's own declaration, a core schema under openapi.includeCoreSchemas, or a contributor that sorted earlier \u2014 read the document before deciding what to remove.`
+    `the served OpenAPI document already defines ${discarded.length} component entry(ies) a library also contributes: ${listed}${elided > 0 ? `, and ${elided} more` : ""}. The contributed version is not served, so where the two differ a client generated from this document will not match that library's own types. What holds the name may be the application's own declaration, a core schema under openapi.includeCoreSchemas, or a contributor that sorted earlier \u2014 read the document before deciding what to remove.`
   );
 }
 function buildConfig(builder, options) {

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]: {
@@ -736,7 +735,7 @@ function warnDiscardedComponents(logger, discarded) {
   const elided = discarded.length - MAX_WARNED_OPERATIONS;
   const listed = discarded.slice(0, MAX_WARNED_OPERATIONS).map(({ contributor, member, name }) => `${contributor} -> ${member}.${name}`).join(", ");
   logger.warn(
-    `the served OpenAPI document already defines ${discarded.length} component entry(ies) a library also contributes: ${listed}${elided > 0 ? `, and ${elided} more` : ""}. The contributed version is not served, so a client generated from this document will not match that library's own types. What holds the name may be the application's own declaration, a core schema under openapi.includeCoreSchemas, or a contributor that sorted earlier \u2014 read the document before deciding what to remove.`
+    `the served OpenAPI document already defines ${discarded.length} component entry(ies) a library also contributes: ${listed}${elided > 0 ? `, and ${elided} more` : ""}. The contributed version is not served, so where the two differ a client generated from this document will not match that library's own types. What holds the name may be the application's own declaration, a core schema under openapi.includeCoreSchemas, or a contributor that sorted earlier \u2014 read the document before deciding what to remove.`
   );
 }
 function buildConfig(builder, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-core",
-  "version": "1.6.1",
+  "version": "1.6.3",
   "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",