@bymax-one/nest-core 1.6.0 → 1.6.2

package/CHANGELOG.md

@@ -11,6 +11,139 @@ 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
+declared had its entry discarded, and neither side could tell. The document
+validated, the served output looked exactly as it would have had nothing been
+offered, and the contributing library received no signal at all — so the failure
+was indistinguishable from success at both ends.
+
+Two changes, and they are independent: an empty placeholder no longer counts as a
+declaration, and every genuine collision is now reported.
+
+**This patch adds public surface**, which a patch number cannot tell you:
+`discarded` on `OpenApiMountOutcome`, and the `DiscardedComponent` type it holds.
+Both are additive and nothing is removed or renamed, so the digit stays at a
+patch under this project's versioning policy — which means this paragraph, rather
+than the version, is what says there is something new to look for.
+
+**Apply to a derived backend:** nothing is required, and no served document loses
+anything it carried. A schema the application declares with a shape of its own
+still wins, exactly as before. What changes is that a schema present only as
+`{"type":"object","properties":{}}` — which `@nestjs/swagger` emits for every DTO
+in a package built without its plugin — is now filled from the contribution
+rather than preferred over it. Read `discarded` on the `OpenApiMountOutcome` to
+see what a contributor offered and did not place; the boot log reports the same
+entries.
+
+### Added
+
+- **`discarded` on `OpenApiMountOutcome`, and the `DiscardedComponent` type.**
+  Lists every contributed component entry the document already declared with a
+  shape of its own, naming the contributor, the member and the entry. Present
+  whenever the document mounted, empty when every contribution was placed — an
+  empty array reports that the merge looked and found none, which absence would
+  confuse with not having looked.
+
+  Carries the contributor's label because a collision is only actionable if you
+  know whose entry lost: an application with several contributing libraries would
+  otherwise be told a name was dropped without being told by whom.
+
+  A warning reports the same entries on the way up, elided into a count on the
+  same reasoning as the unsecured-operation line beside it — a library contributing a
+  schema per DTO turns one collision into a hundred, and the version that prints
+  them all is the one an operator learns to skip.
+
+### Changed
+
+- **A schema that describes no shape no longer counts as a declaration.** The
+  merge still prefers what the document carries: a consumer authored theirs on
+  purpose, and a library silently overwriting it is the worse defect wearing the
+  other sign. But `@nestjs/swagger` emits `{"type":"object","properties":{}}` for
+  every DTO in a package built without its plugin, so the name is never actually
+  missing and a contributed schema under it would never be written. The more
+  correct the library's own schema, the more completely it was discarded, because
+  a correct schema and an empty one collide on the same key.
+
+  This is the rule `mergeResponses` already applied to responses, arriving
+  through a different placeholder — a `200` carrying a description and no
+  `content` occupies its status the same way. Filling one in is additive: it
+  constrains nothing before and describes a shape after.
+
+  The test is deliberately narrow. `type` must be absent or `object`, because
+  `{"type":"string"}` carries no properties and is nonetheless complete;
+  reading "no properties" as "no shape" would discard a real schema, which is
+  the failure this path exists to prevent. An empty `required` and a
+  `description` do not change that; any other keyword, or a single property,
+  makes the entry a declaration. A description the document
+  wrote survives being filled in, the same carve-out `mergeResponses` makes.
+
+  The carve-out applies to `schemas` alone. A parameter carries `name` and `in`
+  rather than `properties`, so a schema-shaped emptiness test reads every one of
+  them as a placeholder and would let a contributor overwrite one the consumer
+  wrote — the precedence failure inverted, arriving through the fix for the
+  other one.
+
+  This package's own catalogue, under `openapi.includeCoreSchemas`, is placed by
+  the same rule and before any library. A placeholder under a catalogue name is
+  filled with the package's definition, so a library offering that name meets a
+  declaration and is reported rather than outranking the package.
+
+- **`fastify` and `@nestjs/platform-fastify` devDependency floors raised to
+  `^5.12.5` and `^11.2.4`.** Shipped in the tarball's manifest only; `dist/` is
+  unchanged by them.
+
 ## [1.6.0] - 2026-08-29
 
 A readiness check that fails without rejecting left no record an operator would
@@ -1003,4 +1136,6 @@ have regressed from. They are kept because the reasoning is worth having.
 [1.5.2]: https://github.com/bymaxone/nest-core/compare/v1.5.1...v1.5.2
 [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
-[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.6.0...HEAD
+[1.6.1]: https://github.com/bymaxone/nest-core/compare/v1.6.0...v1.6.1
+[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
@@ -1163,10 +1221,35 @@ can emit it once and never branch:
 
 | Result                                     | Meaning                                                 |
 | ------------------------------------------ | ------------------------------------------------------- |
-| `{ mounted: true, path }`                  | The UI and the document are served at `path`.           |
+| `{ mounted: true, path, discarded }`       | The UI and the document are served at `path`.           |
 | `{ mounted: false, reason: 'disabled' }`   | `openapi.enabled` is off.                               |
 | `{ mounted: false, reason: 'production' }` | The runtime is production. Nothing was built or served. |
 
+`discarded` lists every component entry a library contributed that the served
+document already defined with a shape of its own — a `DiscardedComponent` per
+entry, naming the contributor, the member and the name. It is empty when every
+contribution was placed, and the boot log reports the same entries.
+
+A collision is not an error and does not stop the boot: the merge prefers
+whatever holds the name already. That is usually your own declaration, and you
+authored it on purpose — but it may also be a core schema this package
+contributes under `openapi.includeCoreSchemas`, or an earlier contributor's
+entry, since contributors merge in class-name order. The report names what was
+dropped and by whom, not who owns the definition that won, so read the document
+before deciding what to remove.
+
+It is reported because it is otherwise unobservable from either side: the
+contributing library cannot tell its entry lost, the application cannot tell one
+was offered, and the served document looks the same either way.
+
+A schema present only as `{"type":"object","properties":{}}` is **not** a
+declaration for this purpose. `@nestjs/swagger` emits exactly that for every DTO
+in a package built without its plugin, so such a name is filled from the
+contribution rather than preferred over it, and does not appear in `discarded`.
+An empty `required: []` and a `description` do not change that; anything else
+does. `{"type":"object"}` and `{}` are deliberate declarations — "any object" and
+"any value" — and are kept.
+
 ### Production is a closed door
 
 `NODE_ENV` decides, and the decision is fail-closed: only `development` and
@@ -1714,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`
 
@@ -1773,6 +1857,7 @@ in the sections above.
 | -------------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------ |
 | `applyBymaxOpenApi`                                                                    | function            | Builds and mounts the document; call it before `app.listen()`.                 |
 | `OpenApiMountOutcome`                                                                  | type                | What the helper did: mounted at a path, or skipped with a reason.              |
+| `DiscardedComponent`                                                                   | type                | A contributed component entry the document already declared.                   |
 | `OpenApiSkipReason`                                                                    | type                | Why it was skipped: `'disabled'` or `'production'`.                            |
 | `BymaxOpenApiContributor`, `BYMAX_OPENAPI_CONTRIBUTOR_METADATA`                        | decorator, constant | Marks a provider as describing its own routes, and the metadata key behind it. |
 | `IOpenApiContributor`, `OpenApiFragment`, `OpenApiFragmentObject`, `OpenApiHandlerKey` | types               | The contributor contract and the shape of what it returns.                     |

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;