@bymax-one/nest-core 1.3.2 → 1.5.0

package/README.md

@@ -75,7 +75,7 @@ never loads its peer, which the release gate asserts against the packed tarball.
 
 ### ⏱️ Observability
 
-- ✅ **Request timing** — one sample per completed request, handed to the sink you register;
+- ✅ **Request timing** — one sample per closed request, rejections included, handed to the sink you register;
   the library stores nothing itself
 - ✅ **Slow-request flag** — samples above `slowRequestThresholdMs` are marked, so a sink can
   branch without re-deriving the threshold
@@ -120,7 +120,7 @@ never loads its peer, which the release gate asserts against the packed tarball.
 
 | Subpath        | Contents                                                                                                                                                                                                                                                            |
 | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `.`            | `BymaxCoreModule`, the error envelope and its code catalog, the timing interceptor, the DI tokens, and every option type                                                                                                                                            |
+| `.`            | `BymaxCoreModule`, the error envelope and its code catalog, the request-timing middleware, the DI tokens, and every option type                                                                                                                                     |
 | `./pagination` | `normalizePageQuery`, `buildPageResult`, `normalizeCursorQuery`, `buildCursorResult`, `encodeCursor`, `decodeCursor` and their types — pure functions, no NestJS provider involved                                                                                  |
 | `./health`     | `IHealthIndicator`, `HealthResponse`, the indicator contracts and the `@BymaxHealthIndicator()` marker, so a package that only implements an indicator does not import the module                                                                                   |
 | `./metrics`    | `IMetricsContributor` and the `@BymaxMetricsContributor()` marker, so a package that only publishes metrics imports neither the module nor its DI tokens. The one subpath whose types name `prom-client`, which anyone implementing the contract already depends on |
@@ -213,7 +213,7 @@ falls back to the documented default. Pass only what you want to change.
 
 | Option                   | Type      | Default | Description                                                                    |
 | ------------------------ | --------- | ------- | ------------------------------------------------------------------------------ |
-| `enabled`                | `boolean` | `true`  | Registers the request-timing interceptor.                                      |
+| `enabled`                | `boolean` | `true`  | Applies the request-timing middleware to every route.                          |
 | `slowRequestThresholdMs` | `number`  | unset   | Samples above this duration are flagged `slow: true`. Absent means never slow. |
 
 ### `health`
@@ -272,19 +272,20 @@ BymaxCoreModule.forRoot({
 
 ### `openapi`
 
-| Option               | Type                      | Default       | Description                                                                    |
-| -------------------- | ------------------------- | ------------- | ------------------------------------------------------------------------------ |
-| `enabled`            | `boolean`                 | `false`       | Builds and serves the document. Ignored in production, where it is always off. |
-| `path`               | `string`                  | `'docs'`      | Route serving the interactive UI.                                              |
-| `jsonPath`           | `string`                  | `'docs-json'` | Route serving the raw JSON document.                                           |
-| `title`              | `string`                  | `'API'`       | Document title.                                                                |
-| `description`        | `string`                  | `''`          | Document description.                                                          |
-| `version`            | `string`                  | `'1.0.0'`     | Document version, independent of the package version.                          |
-| `servers`            | `{ url, description? }[]` | `[]`          | Servers advertised by the document.                                            |
-| `securitySchemes`    | `Record<string, object>`  | `{}`          | Security schemes copied into the document's components.                        |
-| `security`           | `SecurityRequirement[]`   | `[]`          | The requirement every operation carries unless it says otherwise.              |
-| `operationSecurity`  | `OperationSecurityMap`    | `{}`          | Per-operation overrides. An empty array marks that operation public.           |
-| `includeCoreSchemas` | `boolean`                 | `true`        | Contributes this package's own schemas and references them from the responses. |
+| Option               | Type                                       | Default       | Description                                                                         |
+| -------------------- | ------------------------------------------ | ------------- | ----------------------------------------------------------------------------------- |
+| `enabled`            | `boolean`                                  | `false`       | Builds and serves the document. Ignored in production, where it is always off.      |
+| `path`               | `string`                                   | `'docs'`      | Route serving the interactive UI.                                                   |
+| `jsonPath`           | `string`                                   | `'docs-json'` | Route serving the raw JSON document.                                                |
+| `title`              | `string`                                   | `'API'`       | Document title.                                                                     |
+| `description`        | `string`                                   | `''`          | Document description.                                                               |
+| `version`            | `string`                                   | `'1.0.0'`     | Document version, independent of the package version.                               |
+| `servers`            | `{ url, description? }[]`                  | `[]`          | Servers advertised by the document.                                                 |
+| `securitySchemes`    | `Record<string, object>`                   | `{}`          | Security schemes copied into the document's components.                             |
+| `security`           | `SecurityRequirement[]`                    | `[]`          | The requirement every operation carries unless it says otherwise.                   |
+| `operationSecurity`  | `OperationSecurityMap`                     | `{}`          | Per-operation overrides. An empty array marks that operation public.                |
+| `operationIdFactory` | `(controller, method, version?) => string` | peer default  | Names the operations. Leave unset and nothing an existing client generated changes. |
+| `includeCoreSchemas` | `boolean`                                  | `true`        | Contributes this package's own schemas and references them from the responses.      |
 
 Unlike `health` and `metrics`, this block behaves identically on `forRoot` and
 `forRootAsync`: the document is mounted from the bootstrap helper, after the
@@ -378,6 +379,56 @@ configuration went wrong. If you gate the document behind an environment flag,
 make sure at least one environment that runs your tests has it on, or these
 checks never fire.
 
+#### When an operation ends up requiring nothing
+
+The checks above catch a requirement that points at nothing. The opposite
+mistake — an operation that ends up pointing at _no requirement at all_ — breaks
+nothing, and that is what makes it dangerous. It is a valid document. No name
+dangles. The runtime still answers `401`. A document test that asserts only the
+operations you enumerated stays green. The only thing that changed is that a
+client generated from the document now sends no credentials.
+
+The edit that produces it is ordinary: a library starts describing its own
+routes, its adoption note tells you to delete the entries you had written for
+them, and the document-level `security` default is sitting in the same options
+block and goes with them. Every route _you_ own then reads as public.
+
+So the document build says so, once, naming the operations:
+
+```
+[BymaxCoreModule] a client generated from the OpenAPI document will send no
+credentials to 2 operation(s): GET /examples, POST /orders. They state no
+security requirement, the document declares no default, and other operations in
+it do state one — so this is more often a missing openapi.security default than
+a public API. Set openapi.security, or state the intent per operation with an
+explicit [] in openapi.operationSecurity.
+```
+
+It is a **warning, not a failure**: an API that is public on purpose is a
+legitimate configuration, and failing a boot over one would be worse than the
+silence it replaces. The trigger is deliberately narrow, so the line stays worth
+reading:
+
+| Condition                                               | Why                                                                                                                    |
+| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| The document declares no top-level `security`           | With a default present, a bare operation inherits it. An explicit `security: []` counts as an answer, not an omission. |
+| At least one other operation _does_ state a requirement | Somebody described a posture on purpose, so the bare ones beside it are an omission rather than a public API.          |
+| The operation is not one of this package's own          | A health probe carrying nothing is the correct description of a route an orchestrator polls without a credential.      |
+
+The escape hatch is to say what you mean, in the document's own vocabulary
+rather than by silencing output: `operationSecurity: { 'GET /examples': [] }`
+marks the operation public, and it stops being reported. A library can do the
+same for its own routes by contributing `security: []` in its fragment.
+
+**And there is one shape nothing can warn you about, so the diff is the only
+check that covers it.** If you remove _every_ requirement at once — no library
+describing anything, no decorator, no override, no document default — what
+remains is indistinguishable from the document of an API that is public on
+purpose. Both are a set of operations that ask for nothing. No tool can separate
+the two without also shouting at every genuinely public API, which is how a
+warning earns the right to be ignored. Render the document twice and compare; it
+is the one step that does not depend on somebody having anticipated your case.
+
 ## 🔑 DI Tokens
 
 Every token is a `Symbol`. `BYMAX_CORRELATION_PROVIDER` and
@@ -443,8 +494,8 @@ throw new BadRequestException({ code: 'INVOICE_OVERDUE', message: 'Invoice is ov
 
 ## ⏱️ Request Timing
 
-One `RequestTimingSample` is delivered per completed request, success or
-error, to whatever implements `ITimingSink`:
+One `RequestTimingSample` is delivered to whatever implements `ITimingSink` for
+**every request the server closes** — not only the ones a handler answered:
 
 ```typescript
 export interface RequestTimingSample {
@@ -456,6 +507,59 @@ export interface RequestTimingSample {
 }
 ```
 
+### Rejected requests are counted too
+
+The recorder is middleware (`BymaxTimingMiddleware`), applied to every route by
+`BymaxCoreModule` when `timing.enabled` is `true`. That placement is the whole
+point. Nest runs **middleware → guards → interceptors → pipes → handler**, so a
+request rejected by a guard never reaches an interceptor, and a request matching
+no route never reaches a controller. A recorder sitting in either place is blind
+to exactly the traffic that matters during an incident:
+
+| What happens                   | Status | Visible to an interceptor | Visible here |
+| ------------------------------ | ------ | ------------------------- | ------------ |
+| Handler answers                | `2xx`  | ✅                        | ✅           |
+| Authentication guard rejects   | `401`  | ❌                        | ✅           |
+| Authorization guard rejects    | `403`  | ❌                        | ✅           |
+| Rate limiter sheds the request | `429`  | ❌                        | ✅           |
+| No route matches               | `404`  | ❌                        | ✅           |
+| Client hangs up mid-request    | —      | ❌                        | ✅           |
+
+A credential-stuffing run is a flood of `401`s, route enumeration is a flood of
+`404`s, and a throttler doing its job is a flood of `429`s. All three used to
+leave the error graph flat.
+
+Requests that matched no route are recorded under the fixed label
+`UNMATCHED_ROUTE` (`<unmatched>`), never the path that was requested. The raw
+path is attacker-controlled, and a metrics label that follows it lets anyone
+mint one time series per probe until the process runs out of memory.
+
+The sample is emitted when the connection closes, so a client that hangs up
+before the response finishes is still counted — that is what a scanner does, and
+`durationMs` covers guards and middleware as well as the handler.
+
+An aborted request keeps whatever status the response held, which is `200` in
+Node unless something settled another one. No sentinel status is introduced:
+that would change the value of `status_code="200"` series that already exist in
+your dashboards, without any change in traffic.
+
+**Express and Fastify behave identically here**, and that is asserted end to
+end on both. It needs saying because the two platforms disagree underneath: Nest
+runs middleware on Fastify through `@fastify/middie`, which hands it the raw
+`IncomingMessage` carrying no route metadata, and `forRoutes('/')` is a mount on
+Express but an exact match on Fastify. The module resolves both for you.
+
+> **One gap remains, and it is Nest's scoping rule, not a setting.** Module
+> middleware is scoped to the global prefix, so with `setGlobalPrefix('api')` a
+> request to `/nope` — outside the prefix entirely — reaches no middleware and
+> is not recorded. Requests to `/api/nope` are recorded normally, under
+> `<unmatched>`, so a scan that probes below your prefix is still visible; only
+> one that probes above it is not. Covering that too is not supported yet: the
+> module has no way to register the recorder outside its own scope, and
+> `BymaxTimingMiddleware` is only provided when `timing` is enabled — at which
+> point the module already applies it, so resolving and re-registering it would
+> double-count. If you need it, open an issue rather than wiring it by hand.
+
 Bind your own sink by providing `BYMAX_TIMING_SINK` from your own module, the
 same override pattern shown below for the correlation provider. This applies on
 the `forRoot` path; on `forRootAsync` the module owns `BYMAX_TIMING_SINK` (the
@@ -856,6 +960,105 @@ Both halves are the same switch. Referencing a schema that was not contributed
 would leave a dangling `$ref`, and a document that resolves nowhere is worse
 than one that says less — so `includeCoreSchemas: false` opts out of both.
 
+### A library can describe its own routes
+
+A library that ships controllers cannot document them itself. Decorating them
+with `@nestjs/swagger` would load that peer in every application importing the
+library, including the ones that never build a document — and a consumer-side
+map keyed by path does not work either, because a library mounted through
+`RouterModule.register` does not know its own final paths: the same route is
+`/auth/login` in one deployment and `/api/v2/identity/login` in another, from one
+build.
+
+So a library marks a provider and returns fragments keyed by **handler
+identity**, which survives every prefix, version and mount point:
+
+```ts
+import { BymaxOpenApiContributor } from '@bymax-one/nest-core/openapi'
+import type { IOpenApiContributor, OpenApiFragment } from '@bymax-one/nest-core/openapi'
+
+@BymaxOpenApiContributor()
+@Injectable()
+export class AuthOpenApi implements IOpenApiContributor {
+  constructor(private readonly options: ResolvedAuthOptions) {}
+
+  contributeOpenApi(): OpenApiFragment {
+    return {
+      // Required, and declared rather than inferred: a fragment crosses a
+      // boundary between independently released packages, where each side
+      // type-checked against its own copy.
+      contractVersion: 1,
+      components: {
+        securitySchemes: {
+          // Derived from resolved options — which is why this cannot be a
+          // static map a consumer writes by hand.
+          authCookie: { type: 'apiKey', in: 'cookie', name: this.options.cookies.accessTokenName },
+          // Declared because the refresh operation below requires it: a
+          // requirement naming an undeclared scheme fails the document build.
+          refreshCookie: {
+            type: 'apiKey',
+            in: 'cookie',
+            name: this.options.cookies.refreshTokenName
+          }
+        }
+      },
+      operations: {
+        'AuthController.login': { security: [] },
+        'AuthController.refresh': { security: [{ refreshCookie: [] }] }
+      }
+    }
+  }
+}
+```
+
+Nothing is wired by the application: enabling the document runs the scan, and a
+library that is never imported contributes nothing.
+
+#### What the merge guarantees
+
+| Rule                  | Behavior                                                                                                                                                                     |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Marked, not shaped    | Only providers carrying the marker are called. A class that merely exposes `contributeOpenApi` is never touched.                                                             |
+| Called once           | While the document is built, after options resolve — so a contributor may derive its contribution from its own configuration.                                                |
+| Stable order          | Contributors run sorted by class name, so two libraries describing the same operation resolve the same way on every boot.                                                    |
+| Data, not mutation    | A contributor returns fragments; this package decides what to write. That is what makes precedence enforceable.                                                              |
+| Named failures        | A marked class that cannot contribute, one that throws, or a fragment addressing a handler the application does not have all fail the document build naming the contributor. |
+| Off with the document | With `openapi.enabled` false, no contributor runs.                                                                                                                           |
+
+**Precedence, weakest first:** what this package infers about its own routes,
+then what a library contributed, then what the consumer configured, and above
+all of them whatever the operation already declared — a decorated handler is the
+consumer speaking directly and is never overwritten. So a deployment can always
+overrule a dependency's description of its own routes through
+`operationSecurity`.
+
+**Operation ids are untouched.** This package installs an operation-id factory
+to learn which handler produced which operation, and delegates the id string —
+to `openapi.operationIdFactory` when you set one, to the format `@nestjs/swagger`
+itself produces otherwise. A client generated from your document before adopting
+this keeps working after.
+
+**The fragment shape is translatable to an OpenAPI Overlay, deliberately.** The
+[Overlay Specification](https://spec.openapis.org/overlay/v1.0.0.html) is the
+OpenAPI Initiative's format for describing changes to a document, and a
+contributor's fragments are that in all but notation: a handler key resolves to
+an operation id, which resolves to a JSONPath target, which is what an overlay
+action addresses. Overlays are not used as the mechanism — their targets are
+paths, which is the one thing a library mounted through `RouterModule.register`
+cannot write, and a JSONPath engine would be a runtime dependency this package
+does not have. But the translation is mechanical, so a tool that emits a
+library's contribution as a standalone overlay can exist the day a pipeline
+wants one. No such tool ships here, and none is promised.
+
+**Deriving the fragments is the library's business, not this package's.** A
+library that wants its schemas to track its own validation decorators should
+generate them in its own build or test suite, where that dependency already
+exists, and commit the result — with a test asserting generated matches
+committed, so drift fails in the repository that caused it. This package takes
+no dependency on any validation library and merges what it is given. An
+application's own DTOs need none of this: `@nestjs/swagger`'s CLI plugin already
+derives them, which is a route a precompiled library does not have.
+
 ### The document describes _this_ deployment
 
 A feature you turned off has its routes removed from the document. With
@@ -961,7 +1164,7 @@ identically.
     │           │               │               │           │
  envelope/    timing/        health/       pagination/   metrics/
     │           │               │               │           │
-APP_FILTER  APP_INTERCEPTOR  liveness +    pure functions  Prometheus
+APP_FILTER  middleware       liveness +    pure functions  Prometheus
     │           │            readiness     on their own    scrape route
     │           │               │           subpath        (opt-in)
     ▼           ▼               ▼               │             │
@@ -996,7 +1199,7 @@ never imported, which is why it can stay an optional peer. The same holds for
 `@nestjs/swagger` and `@opentelemetry/api`: the release gate loads the packed
 tarball and fails if any of the three is reachable with its feature off.
 
-Nothing here holds state across requests. The timing interceptor emits and forgets;
+Nothing here holds state across requests. The timing middleware emits and forgets;
 the health service runs the indicators the app registered and folds their results;
 the pagination helpers are functions of their arguments.
 
@@ -1050,6 +1253,26 @@ A slow indicator is converted to `down` by the aggregator rather than hanging th
 and its `timedOutAfterMs` stays in the response either way, because that number is one this
 library chose rather than text an indicator produced.
 
+### A metric an attack cannot be seen in is not a control
+
+Request timing is counted as a security signal, not a performance one. A
+credential-stuffing run is a flood of `401`s, a privilege probe a flood of
+`403`s, route enumeration a flood of `404`s, and a rate limiter doing its job a
+flood of `429`s. None of those reaches a handler, so a recorder placed after the
+guards sees none of them — and an operator watching a flat error graph concludes
+nothing is happening. The recorder is middleware for that reason, and every
+closed request is counted whatever ended it.
+
+### A route label is attacker-controlled input
+
+The label on a timing sample comes from the matched route **template**, and a
+request that matched nothing is recorded under the single constant
+`UNMATCHED_ROUTE` (`<unmatched>`) rather than the path that was asked for.
+Following the path would let anyone mint one Prometheus time series per probe:
+a scan would grow the registry without bound, make the scrape endpoint the most
+expensive route in the service, and end as an out-of-memory kill. The bound is
+why the unmatched case is a fixed string and not a fallback to the URL.
+
 ### Cursors are opaque, not secret
 
 `encodeCursor` produces a token a client can round-trip; it is not encrypted and not
@@ -1081,6 +1304,8 @@ most likely to be exposed.
 | Health output       | The response names which indicator is down and nothing more; the reason goes to the logger. `exposeIndicatorErrors` (default `false`) puts it back in the response for debugging |
 | Slow indicators     | Converted to `down` by the aggregator, so a probe cannot hang on one                                                                                                             |
 | Correlation         | Resolved through `BYMAX_CORRELATION_PROVIDER` — the app decides where the id comes from                                                                                          |
+| Request accounting  | Every closed request is counted, including the ones a guard rejected (`401`/`403`/`429`) and the ones that matched no route (`404`), so an attack in progress moves the graph    |
+| Route labels        | Taken from the matched template; an unmatched request records the constant `<unmatched>`, never the requested path, so a scan cannot grow the metric registry without bound      |
 | Pagination cursors  | Opaque, not authenticated; treated as client-supplied input on the way back in                                                                                                   |
 | Metrics             | Opt-in; `prom-client` never imported while it is off                                                                                                                             |
 | OpenAPI             | Opt-in and development-only; refused in production by two independent guards, `@nestjs/swagger` never imported while it is off                                                   |
@@ -1099,13 +1324,13 @@ most likely to be exposed.
 ## 🧱 Tech Stack
 
 - **Runtime:** Node.js 24+
-- **Framework:** NestJS 11 (`ConfigurableModuleBuilder`, `APP_FILTER`, `APP_INTERCEPTOR`)
+- **Framework:** NestJS 11 (`ConfigurableModuleBuilder`, `APP_FILTER`, `NestModule.configure`)
 - **Peers:** `@nestjs/common ^11`, `@nestjs/core ^11`, `rxjs ^7`, `reflect-metadata ^0.2`
 - **Optional peers:** `prom-client ^15` when metrics are enabled, `@nestjs/swagger ^11` when
   OpenAPI is enabled, `@opentelemetry/api ^1.9` when trace correlation is enabled — none is
   imported while its feature is off
 - **Build:** tsup — ESM + CJS per subpath, with `.d.ts` _and_ `.d.cts` declarations
-- **Tests:** Jest (unit + e2e over a real Nest application) + Stryker (mutation)
+- **Tests:** Jest (unit + e2e over real Nest applications, Express **and** Fastify) + Stryker (mutation)
 - **TypeScript:** 5.x strict (`noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`), zero `any`
 
 ---
@@ -1120,9 +1345,11 @@ installs it, so the suite is held to a bar beyond "the tests pass".
   `break: 95`; every killable survivor was killed by a strengthened test, with no production
   change, and the nine equivalents that no test can kill each carry their reason on the line
   they apply to ([report](./docs/mutation_testing_results.md))
-- ✅ **End-to-end against a real application** — the filter, the interceptor, the health and
-  metrics routes, the served OpenAPI document, discovered indicators, contributed metrics and
-  trace correlation are all exercised through a booted Nest app, not against mocks of it
+- ✅ **End-to-end against real applications, on both platforms** — the filter, the middleware,
+  the health and metrics routes, the served OpenAPI document, discovered indicators,
+  contributed metrics and trace correlation are all exercised through a booted Nest app, not
+  against mocks of it. Timing is asserted on **Express and Fastify**, because the two differ
+  underneath in ways that make a passing Express suite say nothing about Fastify
 - ✅ **Published-artifact gates** — `check:exports` resolves the types the way each module
   system does, `check:runtime` loads every subpath from the packed tarball in ESM and
   CommonJS, and `check:published` compiles this README's snippets against `dist/`
@@ -1134,7 +1361,7 @@ installs it, so the suite is held to a bar beyond "the tests pass".
 ```bash
 pnpm test          # unit suite
 pnpm test:cov      # unit suite with the 100% coverage gate
-pnpm test:e2e      # end-to-end against a real Nest application
+pnpm test:e2e      # end-to-end against real Nest applications (Express and Fastify)
 pnpm mutation      # Stryker mutation testing (break: 95)
 pnpm typecheck     # tsc strict check
 pnpm lint          # ESLint
@@ -1154,6 +1381,7 @@ in the sections above.
 | `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_METRICS_REGISTRY`                                                                                     | tokens    | The DI tokens; see the [token table](#-di-tokens).                                 |
 | `ICorrelationIdProvider`                                                                                                                                                                                         | type      | The correlation-provider contract.                                                 |
 | `ITraceContextProvider`, `TraceContext`                                                                                                                                                                          | types     | The trace-context contract and the identifiers it resolves.                        |
@@ -1161,7 +1389,9 @@ in the sections above.
 | `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.                                       |
-| `TimingInterceptor`                                                                                                                                                                                              | class     | The request-timing interceptor.                                                    |
+| `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.                                        |
@@ -1197,20 +1427,26 @@ in the sections above.
 
 ### `./openapi`
 
-| Export                | Kind     | Description                                                       |
-| --------------------- | -------- | ----------------------------------------------------------------- |
-| `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. |
-| `OpenApiSkipReason`   | type     | Why it was skipped: `'disabled'` or `'production'`.               |
+| Export                                                                                 | Kind                | Description                                                                    |
+| -------------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------ |
+| `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.              |
+| `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.                     |
 
 ## 🧩 Compatibility
 
 - Node.js `>= 24`
 - NestJS `^11`
-- Express and Fastify, through framework-agnostic accessors for path, method,
-  and status. GraphQL and RPC execution contexts are out of scope for the
-  error envelope and the timing interceptor in this release; both pass errors
-  and requests through untouched.
+- Express and Fastify, both covered end to end. The accessors are
+  framework-agnostic for path, method and status, and the module absorbs the
+  two places the platforms genuinely differ: the route mount, and the fact that
+  Nest runs middleware on Fastify through `@fastify/middie`, which strips the
+  route metadata off the object the middleware receives.
+- GraphQL and RPC execution contexts are out of scope for the error envelope and
+  the request timing in this release; both pass errors and requests through
+  untouched.
 
 ## 🤝 Contributing