@bymax-one/nest-core 1.6.6 → 1.6.8

package/README.md

@@ -6,7 +6,7 @@
 
 <p align="center">
   <strong>Zero-dependency application foundation kit for NestJS</strong><br />
-  <sub>Error Envelope · Request Timing · Offset &amp; Cursor Pagination · Health Probes · Prometheus Metrics · Zero Runtime Dependencies</sub>
+  <sub>Error Envelope · Request Timing · Offset &amp; Cursor Pagination · Health Probes · Prometheus Metrics · HTTP Floors · Zero Runtime Dependencies</sub>
 </p>
 
 <p align="center">
@@ -33,22 +33,21 @@
 
 ## ✨ Overview
 
-`@bymax-one/nest-core` is the layer every service in a fleet ends up writing for itself: one
-error shape, one timing sample, one pagination contract, one health probe, one metrics
-endpoint. Writing it per service is how five services end up answering the same failure five
-different ways, and how a client integration breaks because one of them changed its error
-body.
+`@bymax-one/nest-core` is the layer every NestJS service ends up writing for itself: one error
+shape, one timing sample, one pagination contract, one health probe, one metrics endpoint.
+Writing it per service is how services end up answering the same failure differently, and how a
+client integration breaks when one of them changes its error body.
 
 It ships `"dependencies": {}`. Everything it touches — NestJS, `rxjs`, `reflect-metadata`, and
-the three optional peers behind the features that need them (`prom-client`, `@nestjs/swagger`,
-`@opentelemetry/api`) — is a peer whose version you already control. A feature you leave off
-never loads its peer, which the release gate asserts against the packed tarball.
+the optional peers behind the features that need them (`prom-client`, `@nestjs/swagger`,
+`@opentelemetry/api`, `helmet`) — is a peer whose version you already control. A feature you
+leave off never loads its peer, which the release gate asserts against the packed tarball.
 
 ### Why nest-core?
 
-- **One error shape, fleet-wide.** A versioned code catalog and a fixed envelope, so a client
-  writes one error handler instead of one per service — and an unknown failure becomes a
-  generic 500 rather than whatever the framework happened to serialize.
+- **One error shape.** A versioned code catalog and a fixed envelope, so a client writes one
+  error handler — and an unknown failure becomes a generic 500 rather than whatever the
+  framework happened to serialize.
 - **Features register only when enabled.** Turning metrics off does not leave a disabled
   provider in the container; it leaves no provider, and `prom-client` is never imported. That
   is what lets it stay an optional peer.
@@ -70,15 +69,22 @@ never loads its peer, which the release gate asserts against the packed tarball.
   and the rest, exported as constants so a client maps a `code` rather than a message string
 - ✅ **Internals stay internal** — an unknown error becomes a generic 500; its message and
   stack go to the `BYMAX_UNEXPECTED_ERROR_SINK` seam when you bind one, and reach the body
-  only under `exposeInternals`. A 5xx
-  never carries `details` either, whichever library threw it, unless `exposeInternals` is on
+  only under `exposeInternals`. A 5xx never carries `details` either, whichever library threw
+  it, unless `exposeInternals` is on
 - ✅ **Correlation id** — resolved through `BYMAX_CORRELATION_PROVIDER`, so the id comes from
   wherever your request context already keeps it
 
+### 🛡️ Request floors
+
+- ✅ **Body-depth guard** — opt-in `bodyDepth` answers a request body nested too deeply with a
+  `400` through the envelope, before a recursive validator overflows the stack into a `500`
+- ✅ **HTTP floors** — `applyHttpFloors` from `./http` sets security headers without HSTS,
+  refuses compressed request bodies with `415`, and bounds header and request time
+
 ### ⏱️ Observability
 
-- ✅ **Request timing** — one sample per closed request, rejections included, handed to the sink you register;
-  the library stores nothing itself
+- ✅ **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
 - ✅ **Prometheus endpoint** — opt-in scrape route over `BYMAX_METRICS_REGISTRY`;
@@ -105,9 +111,7 @@ never loads its peer, which the release gate asserts against the packed tarball.
 
 ### 🧩 Developer Experience
 
-- ✅ **Zero runtime dependencies** — `@nestjs/*`, `rxjs` and `reflect-metadata` arrive as
-  peers, so you pin the versions
-- ✅ **Five subpaths** — the module, plus `./pagination`, `./health`, `./metrics` and
+- ✅ **Subpaths** — the module, plus `./pagination`, `./health`, `./metrics`, `./http` and
   `./openapi` that a package can import without pulling the module in
 - ✅ **Dual-format output** — ESM + CJS with declarations for each format, verified against
   the packed tarball on every run
@@ -126,6 +130,7 @@ never loads its peer, which the release gate asserts against the packed tarball.
 | `./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 |
+| `./http`       | `applyHttpFloors`, the one bootstrap call for the HTTP-level floors: security headers, compressed request bodies refused, and the header and request timeouts — separate so an application that never calls it never loads `helmet`                                 |
 | `./openapi`    | `applyBymaxOpenApi`, the one bootstrap call that builds and mounts the OpenAPI document — separate so an application that never documents its API never loads the code that does                                                                                    |
 
 Each subpath ships ESM and CommonJS with its own `.d.ts` and `.d.cts`, so
@@ -138,13 +143,14 @@ pnpm add @bymax-one/nest-core @nestjs/common @nestjs/core reflect-metadata rxjs
 ```
 
 Add `prom-client` if you enable the metrics feature, `@nestjs/swagger` if you
-enable the OpenAPI feature, and `@opentelemetry/api` if you enable trace
-correlation. All three are optional peer dependencies: none is required, or ever
-loaded, unless you turn its feature on.
+enable the OpenAPI feature, `@opentelemetry/api` if you enable trace
+correlation, and `helmet` if you call `applyHttpFloors`. Each is an optional peer
+dependency: none is required, or ever loaded, unless you turn its feature on.
 
 ```bash
 pnpm add prom-client
 pnpm add @opentelemetry/api
+pnpm add helmet
 pnpm add -D @nestjs/swagger
 ```
 
@@ -227,20 +233,41 @@ and the classification table: [Production is a closed door](#production-is-a-clo
 
 ### `timing`
 
-| Option                   | Type      | Default | Description                                                                    |
-| ------------------------ | --------- | ------- | ------------------------------------------------------------------------------ |
-| `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. |
+| Option                   | Type      | Default | Description                                                                                                       |
+| ------------------------ | --------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
+| `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; a positive integer, or boot fails. |
+
+### `bodyDepth`
+
+| Option     | Type      | Default | Description                                                                                        |
+| ---------- | --------- | ------- | -------------------------------------------------------------------------------------------------- |
+| `enabled`  | `boolean` | `false` | Refuses a request body nested deeper than `maxDepth` with a `400` through the envelope. See below. |
+| `maxDepth` | `number`  | `32`    | The deepest nesting a body may have. A flat object or array is depth 1. A positive safe integer.   |
+
+**Off by default, and worth turning on.** Enabling it rejects bodies that are accepted without
+it, so it is a decision rather than a side effect. Turn it on: a body of about 2,000 nested
+arrays is only 4 KB, and the recursion in a validator or transformer (`class-validator`,
+`class-transformer`) overflows the stack on it, so the filter answers `500` for a request that
+was only malformed — no credential needed. This package ships no validation of its own, so the
+limit sits in front of yours: the check runs before routing, on the body Nest's parsers already
+produced, and answers `400 BYMAX_BAD_REQUEST` ("Request body is nested too deeply"), so it
+protects every route, this package's own included.
+
+It covers the Express adapter. It does nothing when the application disables Nest's body
+parsers or parses bodies after module middleware has run, and it is not mounted on Fastify,
+whose middleware runs before the body is parsed.
 
 ### `health`
 
-| Option                  | Type      | Default    | Description                                                                                                             |
-| ----------------------- | --------- | ---------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `enabled`               | `boolean` | `true`     | Registers the health controller.                                                                                        |
-| `path`                  | `string`  | `'health'` | Route prefix: `GET /<path>/live`, `GET /<path>/ready`.                                                                  |
-| `indicatorTimeoutMs`    | `number`  | `5000`     | Per-indicator timeout before a check reports down.                                                                      |
-| `exposeIndicatorErrors` | `boolean` | `false`    | Includes the failing indicator's message in the response under `details.error`. Never enable in production — see below. |
-| `autoDiscover`          | `boolean` | `false`    | Also aggregates every provider marked `@BymaxHealthIndicator()`, anywhere in the application.                           |
+| Option                  | Type      | Default    | Description                                                                                                                                        |
+| ----------------------- | --------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `enabled`               | `boolean` | `true`     | Registers the health controller.                                                                                                                   |
+| `path`                  | `string`  | `'health'` | Route prefix: `GET /<path>/live`, `GET /<path>/ready`.                                                                                             |
+| `indicatorTimeoutMs`    | `number`  | `5000`     | Per-indicator timeout before a check reports down; a positive integer up to `2147483647`, or boot fails.                                           |
+| `readinessCacheMs`      | `number`  | `1000`     | How long a finished readiness answer is reused; `0` turns the cache off. Probes already in flight always share one run.                            |
+| `exposeIndicatorErrors` | `boolean` | `false`    | Serves what an indicator returned in `details`, and the failing indicator's message under `details.error`. Never enable in production — see below. |
+| `autoDiscover`          | `boolean` | `false`    | Also aggregates every provider marked `@BymaxHealthIndicator()`, anywhere in the application.                                                      |
 
 On `forRoot`, `enabled` and `path` are applied at module-definition time: a
 disabled feature registers no controller, and a custom `path` mounts the routes.
@@ -304,237 +331,21 @@ BymaxCoreModule.forRoot({
 | `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
-options have resolved, so a custom `path` is honored on both registration paths.
-
-#### Documenting authentication
-
-Set the default on the document and mark the exceptions. `security` names
-schemes declared in `securitySchemes`; `operationSecurity` overrides it for one
-operation, and an **empty array is how the specification says "public"** — which
-matters more than it looks, because an operation with _absent_ security inherits
-the document default, so a generated client would attach credentials to your
-registration endpoint.
-
-```ts
-openapi: {
-  enabled: true,
-  securitySchemes: {
-    cookieAuth: { type: 'apiKey', in: 'cookie', name: 'access_token' },
-    refreshCookie: { type: 'apiKey', in: 'cookie', name: 'refresh_token' }
-  },
-  security: [{ cookieAuth: [] }],
-  operationSecurity: {
-    'POST /auth/login': [],
-    'POST /auth/register': [],
-    'POST /auth/refresh': [{ refreshCookie: [] }]
-  }
-}
-```
-
-An operation that already declares its own requirement — because you decorated
-the handler — is never overwritten, on either path.
-
-#### The operation key is a contract
-
-Keys are `"<METHOD> <path>"`, and the format is documented rather than
-incidental: a sibling library can ship a plain-data map of its own operations
-keyed this way, so you spread it in instead of restating which of its routes are
-public. Import `OperationSecurityMap` to have that map checked at the library's
-own compile time — it is a type-only export, so nothing couples at runtime.
-
-- The method is **uppercase**, separated by exactly one space.
-- The path is written **exactly as it appears in the generated document**:
-  leading slash, OpenAPI template braces (`/users/{id}`), no trailing slash, and
-  **including any global prefix**. `@nestjs/swagger` puts
-  `app.setGlobalPrefix('api')` into the documented paths, so the key becomes
-  `'POST /api/auth/login'` in an application that sets one.
-
-Because of that last point, a library shipping such a map should expose a
-**function taking the prefix**, not a frozen constant — the call site is the only
-place that knows it:
-
-```ts
-// in the library
-export function authOperationSecurity(prefix = ''): OperationSecurityMap {
-  return {} /* … */
-}
-
-// in the application
-BymaxCoreModule.forRoot({
-  openapi: { operationSecurity: { ...authOperationSecurity('api'), ...myOwnOverrides } }
-})
-```
-
-A requirement naming a scheme that is not declared **fails the document build**
-too, listing the names that missed and the ones the document defines. A
-requirement is a reference, and a reference to nothing yields a document whose
-security cannot be resolved: a client generator looks the name up, finds
-nothing, and either fails or emits an unauthenticated client.
-
-A key matching no operation **fails the document build**, listing both the keys
-that missed and the operations that exist. Silence would be worse: a route
-renamed out from under a stale key would quietly inherit the document default
-and be documented as authenticated when it is not, or the reverse. Failing is
-safe here in a way it rarely is — the document is only ever built outside
-production, so this can only stop a developer.
-
-One consequence for conditionally-registered routes: the map is static wiring
-while a route may not be. If an operation belongs to a feature you register per
-environment — your own conditional module, or a library feature toggled off
-somewhere — a key naming it fails the boot in whichever docs-enabled environment
-lacks that route. That is the intended loud behavior, so build the map the same
-way you build the modules: assemble it per feature and spread the fragments in,
-rather than writing one flat literal that outlives the routes it names.
-
-That last sentence cuts both ways, and the consequence is worth stating rather
-than discovering. **These checks only run when the document is actually built.**
-With `openapi.enabled` false, or in a production runtime where the feature is
-forced off, nothing validates: a stale key, a renamed route, or a requirement
-naming a scheme you deleted all sit there quietly until someone turns the
-document on. That is deliberate — refusing to boot a production service over a
-documentation setting it never serves would be the wrong trade — but it means
-the errors surface on a developer's machine or in CI, **not** at the moment the
-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.
-
-**There is one shape this warning cannot report.** If you remove _every_
-requirement at once — no library describing anything, no decorator, no override,
-no document default — the second condition above is never met: nothing states a
-requirement, so there are no bare operations sitting _beside_ described ones.
-That follows from the trigger and therefore holds in every version; it is not a
-gap a later release closes, and a reader who expects one is exactly the reader
-who stops checking.
-
-The limit belongs to **anything reading only the rendered document**. Such a
-document is indistinguishable from that of an API which is public on purpose —
-both are a set of operations asking for nothing — and this package cannot tell
-them apart without also warning at every genuinely public API, which is how a
-warning earns the right to be ignored.
-
-**Your own suite has no such handicap, because you know which one you are.**
-Assert it, and the check runs on every commit rather than when somebody
-remembers to look:
-
-```ts
-it('still requires a credential everywhere it should', () => {
-  const document = buildYourDocument()
-
-  // Assert the default you expect, not merely that one exists. `[]` is a
-  // defined value that requires nothing, so a "toBeDefined" check passes for
-  // a default that degraded to empty — which is the regression this test is
-  // here to catch, wearing the shape of a pass.
-  expect(document.security).toEqual([{ cookieAuth: [] }])
-
-  // An explicit `[]` is how an operation says "public". The set of operations
-  // saying it should be the set you meant — no more, no fewer.
-  expect(publicOperationsOf(document)).toEqual(['POST /auth/login'])
-})
-```
-
-Render-and-diff keeps a narrower job, and it is a good one: when you are
-_changing_ something — adopting a library that describes its own routes, moving
-a default — render with and without the change and compare the operations you
-mount. It shows you what moved without your having to predict it. Then turn what
-it showed you into an assertion, so the next change is caught rather than
-inspected.
-
-#### A contributed scheme's presence is part of the contributor's configuration
-
-A library contributes security schemes, and **which** ones it contributes can
-depend on how you configured it. Any of them, gated on any of its inputs, and
-often on more than one — the scheme you have in mind may be the absent one, and
-the setting you are thinking of may not be the only gate. The names are stable;
-their presence is not.
-
-That has one consequence worth stating as a rule, because getting it wrong
-produces a failure at either end of the loudness scale:
-
-> Derive a document-level default from **the same configuration the contributor
-> reads**, never from the scheme names, and never from what the document
-> happened to contain before you adopted the library.
-
-Writing the name as a literal is correct only for the configuration you wrote it
-against. Under a configuration that declares that scheme plus another, the
-default still resolves but describes one of two credentials the route accepts —
-**quietly incomplete**. Under one that declares it not at all, the name resolves
-to nothing and the document build **fails** with the undeclared-scheme error
-above. Guarding on whether the scheme exists is the tempting fix and it is the
-wrong one: it clears the case that already announced itself and ships the one
-that does not.
-
-Note what a document-level default does not let you _say_. Its entries are
-**alternatives** — any one of them satisfies an operation — and they apply to
-every operation that states nothing. So a backend whose routes sit behind **two
-different credential families** can certainly list both, and nothing rejects it:
-the result is a document asserting that _either_ credential works for _every_
-inheriting route. That is not an incomplete document, it is a false one, and it
-is false in the permissive direction — it tells a client that a credential the
-route will reject is one the route accepts.
-
-Give the majority family the default and the minority explicit
-`operationSecurity` entries. Those outrank the default, and an operation
-carrying one is never named by the warning above, because it states a
-requirement.
+Unlike `health` and `metrics`, this block behaves identically on `forRoot` and `forRootAsync`:
+the document is mounted from the bootstrap helper, after the options have resolved. How to
+document authentication and the rest of the feature: [OpenAPI](#-openapi).
 
 ## 🔑 DI Tokens
 
-Every token is a `Symbol`. `BYMAX_CORRELATION_PROVIDER`,
-`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
-module always binds and exports both (the timing sink as the metrics bridge or a
-no-op, the registry as a guarded placeholder when metrics are off), so a
-consumer `BYMAX_TIMING_SINK` override is honored on `forRoot` but shadowed on
-`forRootAsync`. Follow the pattern in
-[Integration with `@bymax-one/nest-logger`](#-integration-with-bymax-onenest-logger)
-below.
+Every token is a `Symbol`. `BYMAX_CORRELATION_PROVIDER`, `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, 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: the
+module always binds and exports both (the timing sink as the metrics bridge or a no-op, the
+registry as a guarded placeholder when metrics are off), so a consumer `BYMAX_TIMING_SINK`
+override is honored on `forRoot` but shadowed on `forRootAsync`. Follow the pattern in
+[Integration with `@bymax-one/nest-logger`](#-integration-with-bymax-onenest-logger).
 
 | Token                          | Provides                              | When you do not provide one                                                                                       |
 | ------------------------------ | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
@@ -581,19 +392,15 @@ something you bind. With `@bymax-one/nest-logger` that is its request-id
 middleware; see
 [Integration with `@bymax-one/nest-logger`](#-integration-with-bymax-onenest-logger).
 
-**A server error carries no `details` by default.** For a status of 500 or above, the filter omits `details`
-from the body, whichever library threw the `HttpException` and whether it wrote them flat or
-under `error`; the `code` and `message` stay, because they are text the thrower chose for the
-caller. `envelope.exposeInternals` keeps the details, for local debugging only. The filter owns no
-logger and does not record a 5xx's `details` itself, so whatever throws such an error should log
-that context on the server and must not interpolate internal data into its `message`. Client
-errors are unchanged: their details are the contract. The reasoning follows the OWASP
+**A server error carries no `details` by default.** For a status of 500 or above the filter
+omits `details`, whichever library threw the `HttpException` and whether it wrote them flat or
+under `error`; `code` and `message` stay, because the thrower chose them for the caller.
+`envelope.exposeInternals` keeps the details, for local debugging only. The filter owns no
+logger, so whatever throws such an error should log that context server side and must not
+interpolate internal data into its `message`. Client errors are unchanged: their details are the
+contract. This follows the OWASP
 [Error Handling Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Error_Handling_Cheat_Sheet.html)
-(a generic client response, details logged server side), RFC 9457
-[sections 3.1.4 and 5](https://www.rfc-editor.org/rfc/rfc9457.html) (a problem detail helps the client
-correct the problem rather than debug, and no implementation details leave through the HTTP
-interface), and the NestJS [exception filters](https://docs.nestjs.com/exception-filters) behaviour
-of serializing an `HttpException` response object as the whole body.
+and RFC 9457 [sections 3.1.4 and 5](https://www.rfc-editor.org/rfc/rfc9457.html).
 
 Codes are stable strings under a reserved `BYMAX_` prefix, derived from the
 HTTP status: `BYMAX_NOT_FOUND` for 404, `BYMAX_VALIDATION_FAILED` for the
@@ -632,107 +439,31 @@ Every code the package assigns is exported from `@bymax-one/nest-core` as a cons
 
 ### What the filter classifies from, and what it cannot
 
-An error raised before any handler ran — a malformed JSON body, a payload over
-the size limit — still becomes a clean `4xx` envelope rather than a 500. The
-filter recognizes those by **shape**, not by class: it honours an error that
-marks itself `expose: true` with a `4xx` status, which is the `http-errors`
-convention Node's body pipeline follows. Nothing in the application failed, so
-it is not routed through the unexpected-error seam either.
+An error raised before any handler ran — a malformed JSON body, a payload over the size limit —
+still becomes a clean `4xx` envelope rather than a 500. The filter recognizes those by **shape**,
+not by class: it honours an error that marks itself `expose: true` with a `4xx` status, the
+`http-errors` convention Node's body pipeline follows. Nothing in the application failed, so it
+is not routed through the unexpected-error seam either.
 
 The message of such a refusal is fixed per status — `Malformed request` (400),
-`Request entity too large` (413), `Unsupported media type` (415) — because the
-parser's own text quotes the request: a JSON excerpt, a header value, the path.
-A `BadRequestException` a middleware throws before routing gets the same 400
-message; throw it with a `code` to keep its own. Fastify is not covered.
-
-**An error that carries no such marking is a 500, including when a client
-caused it.** The clearest case is depth: a body of a few kilobytes nested
-thousands of levels deep overflows the stack during validation and surfaces as
-`RangeError: Maximum call stack size exceeded` — well under any size limit, and
-answered `500 BYMAX_INTERNAL_ERROR`.
-
-That is deliberate, and the alternative is worse. Mapping `RangeError` to a
-`4xx` would make the filter infer causation from an error class, and it would be
-wrong exactly where it matters: a genuine stack overflow in your own code is a
-`500` that should page someone, and relabelling it as a client error would hide
-the failure the `500` exists to surface. By the time the filter sees the error,
-the body that caused it is gone.
-
-**So body-shape limits are the application's floor, not the filter's.** Cap
-nesting depth and the request is rejected as the `400` it is, instead of
-becoming a `5xx` that pollutes your error rate and writes a stack per request.
-
-**Position it after the body parser and before validation** — that window is the
-only place the body exists in a form you can measure and nothing has walked it
-yet. Earlier there is nothing to inspect; later the overflow has already
-happened, which is the failure you are trying to prevent.
-
-**Where that window is depends on the adapter, and the obvious answer is wrong
-on Express.** Measured against a real Nest application:
-
-| Registration point                       | `req.body` when it runs |
-| ---------------------------------------- | ----------------------- |
-| `app.use(...)` in `bootstrap.ts`         | **`undefined`**         |
-| Module middleware, `configure(consumer)` | the parsed body         |
-
-Nest registers its own parser during `app.init()`, so a middleware added with
-`app.use()` before that is mounted _ahead_ of it — a depth guard there inspects
-nothing and silently protects nothing. Register it as module middleware
-instead. On Fastify the ordering differs again, since Nest middleware runs
-through `@fastify/middie` ahead of body parsing; a `preValidation` hook is the
-place to look, and it is worth measuring rather than assuming.
-
-**Registering it in the right place is not enough — the route pattern silently
-skips paths too.** This package hit the same trap with its own timing
-middleware, and the measured behaviour is in `core.module.ts`:
-
-| `forRoutes(...)` | Express        | Fastify          |
-| ---------------- | -------------- | ---------------- |
-| `'*splat'`       | skips the root | —                |
-| `'{*splat}'`     | skips `/api`   | every path       |
-| `'/'`            | every path     | matches `/` only |
-
-So the named-wildcard form every migration guide reaches for leaves `POST /`
-unguarded on Express. A consumer measured exactly that: with `'*path'`, a
-2000-level body to the root returned `404` because the middleware never ran;
-with `'{*path}'`, `400`. If your application mounts nothing at the root, both
-forms answer `4xx` and the status alone cannot tell you which one you have.
-
-**Verify by behaviour, not by wiring — this is the part worth insisting on.**
-Checking where the middleware is registered is what the consumer above did; it
-looked correct, they confirmed it to us, and the guard was inert. Send a body
-nested past your ceiling and require your own rejection:
-
-```ts
-it('refuses a body nested past the ceiling', async () => {
-  const deep = JSON.parse(`${'['.repeat(2000)}${']'.repeat(2000)}`)
-
-  const res = await request(app.getHttpServer()).post('/anything').send({ name: deep })
-
-  // Match your guard's own message, not the status: a validation pipe rejects
-  // this shape with a 400 as well, so a status assertion passes with the floor
-  // removed and proves nothing.
-  expect(res.body.message).toBe('Request body is nested too deeply.')
-})
-```
-
-Use a depth that actually overflows, and assert the guard's own message. A test
-at a depth your DTO validation already rejects passes identically with the guard
-deleted — which is a check that cannot produce a negative result, and the reason
-this defect survived a green suite.
-
-A depth ceiling well above anything a legitimate payload nests and well below
-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.
+`Request entity too large` (413), `Unsupported media type` (415) — because the parser's own text
+quotes the request: a JSON excerpt, a header value, the path. A `BadRequestException` a
+middleware throws before routing gets the same 400 message; throw it with a `code` to keep its
+own. Fastify is not covered.
+
+**An error that carries no such marking is a 500, including when a client caused it.** A body of
+a few kilobytes nested thousands of levels deep overflows the stack during validation and
+surfaces as `RangeError: Maximum call stack size exceeded`, answered
+`500 BYMAX_INTERNAL_ERROR`. Mapping `RangeError` to a `4xx` would infer causation from an error
+class and hide a genuine stack overflow in your own code, which is a `500` that should page
+someone. The floor for that case is the opt-in [`bodyDepth`](#bodydepth) guard, which refuses
+the body as the `400` it is before validation runs.
 
 ### 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:
+An error the filter does not recognise collapses to a fixed `500 BYMAX_INTERNAL_ERROR`, so the
+client learns nothing about your internals, and the thrown value is gone once the response is
+written. Bind an `IUnexpectedErrorSink` and the filter hands it the original value first:
 
 ```typescript
 import { Global, Logger, Module } from '@nestjs/common'
@@ -758,29 +489,19 @@ export class UnexpectedErrorLogger implements IUnexpectedErrorSink {
 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.
+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. 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; no raw URL, query string, headers or body. The value is passed uncut
+whatever `envelope.exposeInternals` says, since that option governs the response body, so send the
+report where access is already controlled.
+
+The response never depends on the sink: a sink that throws, or an `async record()` that rejects,
+is absorbed, and it runs synchronously before the reply, so hand the report off and return.
+`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.
 
 ## ⏱️ Request Timing
 
@@ -799,20 +520,17 @@ export interface RequestTimingSample {
 }
 ```
 
-`TimingInterceptor` is still exported and is **deprecated**: nothing registers it. It
-was the recorder until `BymaxTimingMiddleware` replaced it, because guards run
-before interceptors and a request a guard rejected never reached it. Registering it
-as well records a second sample for every request that reaches a handler, so leave
-it out.
+`TimingInterceptor` is still exported and is **deprecated**: nothing registers it, and
+registering it alongside the middleware records a second sample for every request that reaches
+a handler, so leave it out.
 
 ### 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:
+The recorder is middleware (`BymaxTimingMiddleware`), applied to every route by `BymaxCoreModule`
+when `timing.enabled` is `true`. 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 in either place is blind to exactly the traffic
+that matters during an incident:
 
 | What happens                   | Status | Visible to an interceptor | Visible here |
 | ------------------------------ | ------ | ------------------------- | ------------ |
@@ -823,40 +541,28 @@ to exactly the traffic that matters during an incident:
 | 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.
+A credential-stuffing run is a flood of `401`s, route enumeration a flood of `404`s, and a
+throttler doing its job a flood of `429`s.
+
+Requests that matched no route are recorded under the fixed label `UNMATCHED_ROUTE`
+(`<unmatched>`), never the requested path: the raw path is attacker-controlled, and a metrics
+label that follows it lets anyone mint one time series per probe.
+
+The sample is emitted when the connection closes, so a client that hangs up before the response
+finishes is still counted, and `durationMs` covers guards and middleware as well as the handler.
+An aborted request keeps whatever status the response held, `200` in Node unless something
+settled another one; no sentinel status is introduced.
+
+Express and Fastify behave identically here, and that is asserted end to end on both. The module
+resolves the two platform differences for you: Fastify runs middleware through `@fastify/middie`,
+which hands it the raw `IncomingMessage` without route metadata, and `forRoutes('/')` is a mount
+on Express but an exact match on Fastify.
+
+> **One gap 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 — reaches no
+> middleware and is not recorded. `/api/nope` is recorded under `<unmatched>`. The module cannot
+> register the recorder outside its own scope; open an issue rather than wiring it by hand,
+> which would double-count.
 
 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
@@ -881,12 +587,10 @@ class LoggerTimingSink implements ITimingSink {
 export class ObservabilityModule {}
 ```
 
-A sink that fails cannot reach the request: both a synchronous throw and a
-rejection from an `async record()` are absorbed. Write it `async` if the backend
-behind it is async — the `void` return type accepts it, and the rejection is
-caught. The failure is swallowed rather than logged, unlike a health transition
-sink, because this runs on every request and a systematically failing sink would
-otherwise become a second flood beside the first.
+A sink that fails cannot reach the request: a synchronous throw and a rejection from an `async
+record()` are both absorbed. The failure is swallowed rather than logged, unlike a health
+transition sink, because this runs on every request and a failing sink would otherwise become a
+second flood beside the first.
 
 ## 📄 Pagination
 
@@ -919,26 +623,16 @@ export class InvoiceController {
 
 #### Bound the offset, not just the page size
 
-`maxLimit` caps how many rows a request reads. `maxOffset` caps how far in it
-starts — and on an offset-paginated database that is the half that costs:
-
-```
-GET /invoices?page=1000000000&limit=20     →  OFFSET 19999999980
-```
-
-Twenty bytes of query, and Postgres walks the table to reach a page that does
-not exist. The page index has a floor of `1` and an arithmetic guard that keeps
-`(page - 1) * limit` an exact integer, but nothing bounds the product itself
-unless you say so.
-
-`maxOffset` is **absent by default and deliberately so**: legitimate deep paging
-exists, and a silent ceiling would change the rows a working query returns. Set
-it wherever the page index reaches SQL and your dataset has a knowable ceiling.
-`0` is a valid bound and means "the first page only".
+`maxLimit` caps how many rows a request reads; `maxOffset` caps how far in it starts, which is
+the half that costs on an offset-paginated database: `GET /invoices?page=1000000000&limit=20`
+becomes `OFFSET 19999999980`, and Postgres walks the table to reach a page that does not exist.
+The page index has a floor of `1` and an arithmetic guard that keeps `(page - 1) * limit` an
+exact integer, but nothing bounds the product unless you say so.
 
-Clamping matches how `maxLimit` already behaves — the resolved values come back
-in `meta`, so a caller that cares can compare what it asked for against what it
-got.
+`maxOffset` is **absent by default**, because legitimate deep paging exists and a silent ceiling
+would change the rows a working query returns. Set it wherever the page index reaches SQL and
+your dataset has a knowable ceiling; `0` means "the first page only". Values are clamped the way
+`maxLimit` is, and the resolved values come back in `meta`.
 
 ### Cursor pagination
 
@@ -976,11 +670,12 @@ Liveness always replies `200` with an empty checks array; readiness runs
 every registered indicator concurrently and replies `200` only when every
 indicator reports `up`, `503` otherwise, naming every check either way.
 
-A failing indicator is named but not quoted: the response says which check is
-down, and the reason goes to the logger. See
+A check is named but not quoted: the response carries each indicator's name and
+status, never the `details` it returned, and a failing indicator's reason goes to
+the logger. See
 [the security model](#-security-model) for why, and
-`health.exposeIndicatorErrors` if you want the message in the response while
-debugging locally.
+`health.exposeIndicatorErrors` if you want the details and the message in the
+response while debugging locally.
 
 ```json
 { "status": "ok", "checks": [{ "name": "redis", "status": "up" }] }
@@ -1028,22 +723,25 @@ export class HealthIndicatorsModule {}
 ```
 
 A rejecting, throwing, or slow indicator (past `indicatorTimeoutMs`) is
-converted to a `down` entry with a safe, bounded diagnostic detail; it never
-hides the results of the other registered indicators.
+converted to a `down` entry; it never hides the results of the other registered
+indicators.
 
-### A failing check leaves a record
+Readiness is usually reachable without credentials, so probe volume does not set dependency
+volume: probes that arrive while a run is in progress share it, and its answer is reused for
+`readinessCacheMs`. `check()` receives an `AbortSignal` that is aborted when the indicator times
+out, so an indicator that can cancel its query should pass the signal on.
+
+When shutdown begins, readiness answers `503` at once, without running an indicator and whatever
+is cached, so a load balancer stops routing to an instance that is draining. Nest only runs
+`beforeApplicationShutdown` on `app.close()` or, for a signal, after `app.enableShutdownHooks()`.
 
-A readiness failure that nothing records is a `503` an orchestrator acts on with
-an empty log behind it, and diagnosing it means reproducing it. That is easy to
-arrive at without deciding to: probe paths are the highest-volume request a
-backend serves, so they are usually excluded from the HTTP log surface, and a
-well-written indicator returns `{ status: 'down' }` rather than throwing —
-because readiness is typically unauthenticated and a driver's error carries
-hosts, ports and sometimes credentials.
+### A failing check leaves a record
 
-So the aggregator records it. It holds the last state of every check and reports
-each **change** — never once per probe — to its own logger, and to a sink you
-bind:
+Probe paths are usually excluded from the HTTP log, and a well-written indicator returns
+`{ status: 'down' }` rather than throwing, because a driver's error carries hosts, ports and
+sometimes credentials. So a readiness `503` could leave nothing behind. The aggregator therefore
+holds the last state of every check and reports each **change** — never once per probe — to its
+own logger and to a sink you bind:
 
 ```typescript
 import { Injectable } from '@nestjs/common'
@@ -1066,19 +764,9 @@ export class HealthTransitionLogger implements IHealthTransitionSink {
 }
 ```
 
-Bind it under `BYMAX_HEALTH_TRANSITION_SINK` from your own `@Global()` module,
-the same override pattern as the indicator token above.
-
-Binding nothing is supported, and is not the silent case: the transitions reach
-Nest's logger instead, so a readiness failure always leaves a record. **Binding a
-sink stands that line down** — both destinations are usually the same logger, so
-keeping it would put two records of one transition side by side, which is the
-noise this feature exists to remove. Your sink receives the cause as structured
-data, strictly more than the line renders, so what reaches the log after that is
-your decision rather than this package's.
-
-`transition.cause` distinguishes the three ways a check can be down, which the
-`up`/`down` response body cannot:
+Bind it under `BYMAX_HEALTH_TRANSITION_SINK` from your own `@Global()` module. With nothing
+bound, transitions reach Nest's logger; **binding a sink stands that line down**, so one
+transition is not recorded twice. The sink receives the cause as structured data:
 
 | `cause.kind`    | Meaning                                            | Carries     |
 | --------------- | -------------------------------------------------- | ----------- |
@@ -1086,26 +774,12 @@ your decision rather than this package's.
 | `rejected`      | The indicator rejected or threw.                   | `message`   |
 | `timed-out`     | The aggregator gave up after `indicatorTimeoutMs`. | `timeoutMs` |
 
-`timed-out` is the one that cannot be observed anywhere else. An indicator the
-aggregator abandoned is never told, so it reports nothing — and a hung
-dependency is the common shape, not a refused one: a database under load, a
-network partition and a paused container all hang, while a refusal comes back
-immediately and would have been reported. That is why the rule lives in the
-aggregator rather than in each backend: the obstacle is information, not effort.
-
-Two details worth knowing before you rely on it. A first observation that is
-**failing** is reported, while a first observation that is healthy is not — a
-process that boots against a dependency already down would otherwise look
-healthy in the log forever, whereas announcing every healthy check would write a
-line per dependency on every boot. And the cause is the one seen **at the
-transition**: a dependency that stays down while its failure mode changes
-underneath keeps the first cause, which is the cost of one line per outage
-instead of one per probe.
-
-The sink is called synchronously on the readiness path, so keep it cheap. A
-throw is caught and logged rather than failing the probe — readiness answering
-`500` because its own logging broke would take a healthy deployment out of
-rotation — but do not use that as flow control.
+`timed-out` cannot be observed anywhere else: an abandoned indicator is never told, and a hung
+dependency is the common shape. A first observation that is **failing** is reported and a first
+healthy one is not, so a process that boots against a dependency already down does not look
+healthy in the log forever. The cause is the one seen **at the transition**, so a dependency that
+stays down while its failure mode changes keeps the first cause. The sink runs synchronously on
+the readiness path, so keep it cheap; a throw is caught and logged rather than failing the probe.
 
 ### Discovered indicators
 
@@ -1167,6 +841,14 @@ is `true`. If you enable metrics without installing it, the module fails fast
 at boot with a descriptive error naming the missing package and the install
 command, rather than a cryptic resolution failure at the first scrape.
 
+npm marks `prom-client` 15.x deprecated in favour of `@prometheus-io/client`. This library stays on
+`prom-client` `^15`: the collectors you register and the `MetricsRegistry` must come from one package.
+
+`prom-client`'s default collectors keep a garbage-collection observer and an event-loop histogram for
+the life of the process, and it offers no way to stop them. Neither keeps the process alive, so
+`app.close()` still lets it exit. It matters only to a host that creates many applications in one
+process, a test runner or a hot reload, where each application leaves a small observer behind.
+
 When timing and metrics are both enabled, an internal bridge feeds two
 default HTTP metrics with a bounded label set:
 
@@ -1214,45 +896,28 @@ BymaxCoreModule.forRoot({ metrics: { enabled: true } })
 | Named failures     | A registration failure — usually a metric name another library already claimed — fails the boot naming the contributor. `prom-client` names the metric; this names who registered it. |
 | Off with metrics   | With the metrics feature disabled, no contributor runs and `prom-client` is never loaded.                                                                                             |
 
-**Naming and labels.** Contributors share one registry and one namespace, so the
-conventions are part of the contract:
-
-- Prefix every metric with `bymax_<library>_` (`bymax_queue_depth`,
-  `bymax_cache_hits_total`). An application's own metrics need no prefix — they
-  have no one to collide with but themselves.
-- Follow Prometheus naming: `_total` for counters, `_seconds` for durations, base
-  units, no units in the middle of a name.
-- Keep labels bounded. Route templates, never raw paths; status codes, never
-  messages. **Never** a tenant, user, or request id — one unbounded label is
-  enough to make a scrape endpoint the most expensive route in a service.
-  `tenantId` deserves naming twice: every library in this family is
-  tenant-aware, so it is the first label anyone reaches for and it is unbounded
-  by construction.
-- **Publish the list.** A library that contributes metrics documents them in its
-  own README — name, type, labels. This package deliberately keeps no central
-  catalogue: a list of everyone else's metrics rots the moment a library ships a
-  new one. What it does require is that the list exists somewhere an operator
-  can find it.
-
-**Why these rules live here.** A Prometheus registry is a flat namespace, and
-`prom-client` rejects a duplicate metric name. If two libraries independently
-pick `bymax_operations_total`, the collision surfaces at the **consumer's** boot
-— in an application neither library's CI ever assembles, as a hard failure, in
-front of whoever wired the app. Neither library can test for it. A namespace
-rule is the only thing that prevents it, and it can only be arbitrated by the
-dependency they share, which is this package.
-
-The rules are documentation, not enforcement. This package could inspect the
-registry around each contributor and reject an unprefixed name, but that would
-need a per-contributor prefix on the contract, and it would wrongly reject the
-case that matters most — an **application's own** contributor, which has no
-business being pushed into a `bymax_` namespace.
+**Naming and labels.** Contributors share one registry and one flat namespace, and `prom-client`
+rejects a duplicate name, so a collision between two libraries surfaces at the **consumer's**
+boot, in an application neither library's CI assembles. The conventions are therefore part of
+the contract:
+
+- Prefix every library metric with `bymax_<library>_` (`bymax_queue_depth`). An application's own
+  metrics need no prefix.
+- Follow Prometheus naming: `_total` for counters, `_seconds` for durations, base units.
+- Keep labels bounded: route templates, never raw paths; status codes, never messages. **Never**
+  a tenant, user or request id: one unbounded label makes the scrape endpoint the most expensive
+  route in a service.
+- **Publish the list.** A library that contributes metrics documents name, type and labels in its
+  own README; this package keeps no central catalogue.
+
+These rules are documentation, not enforcement: rejecting an unprefixed name would need a
+per-contributor prefix on the contract and would wrongly reject an application's own contributor.
 
 ## 📘 OpenAPI
 
-Disabled by default, and **never served in production**. Enabling it and calling
-one helper during bootstrap publishes an interactive UI at `GET /docs` and the
-raw document at `GET /docs-json`:
+Disabled by default, and **never served in production**. Enabling it and calling one helper
+during bootstrap publishes an interactive UI at `GET /docs` and the raw document at
+`GET /docs-json`:
 
 ```typescript
 // app.module.ts — configuration lives with every other feature
@@ -1275,14 +940,11 @@ void bootstrap()
 ```
 
 > [!IMPORTANT]
-> Call `applyBymaxOpenApi` **before** `app.listen()`. Mounting the document
-> re-registers routes on the HTTP adapter, and doing that against an
-> already-initialized Express 5 application replaces the router: the document
-> appears and every other route in the application — yours and this package's
-> health endpoints alike — starts returning 404.
+> Call `applyBymaxOpenApi` **before** `app.listen()`. Mounting the document re-registers routes
+> on the HTTP adapter, and doing that against an already-initialized Express 5 application
+> replaces the router: the document appears and every other route starts returning 404.
 
-The call is safe to make unconditionally. It returns what it did, so a template
-can emit it once and never branch:
+The call is safe to make unconditionally. It returns what it did:
 
 | Result                                     | Meaning                                                 |
 | ------------------------------------------ | ------------------------------------------------------- |
@@ -1290,55 +952,25 @@ can emit it once and never branch:
 | `{ 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.
+`discarded` lists each component a library contributed that the document already defined with a
+shape of its own (a `DiscardedComponent` naming the contributor, the member and the name); the
+boot log reports the same entries. A collision is not an error: the merge keeps whatever holds
+the name, which is usually your own declaration but may be a core schema or an earlier
+contributor's entry. A schema that is only `{"type":"object","properties":{}}` — what
+`@nestjs/swagger` emits for every DTO in a package built without its plugin — is not a
+declaration, so it is filled from the contribution; `{"type":"object"}` and `{}` are kept.
 
 ### Production is a closed door
 
-`NODE_ENV` decides, and the decision is fail-closed: only `development` and
-`test` are non-production. Any other value is production, and in production the
-document is never built and never mounted, whatever the configuration says. The
-guard runs twice, independently: the option resolver forces the feature off, and
-the bootstrap helper classifies the runtime again without trusting that
-resolution.
-
-**`NODE_ENV` cannot be overridden.** With it set to anything, no option serves
-the document in a runtime it named production.
-
-Enabling it in production is not an error, it is a no-op with a warning naming
-the option that was ignored, so a single configuration can be shared across
-environments.
-
-#### When your application validates its own environment variable
-
-Plenty of applications parse an `APP_ENV` through a config schema and never set
-`NODE_ENV` at all. Those deployments used to be classified as production —
-absence was the only evidence available — so the document was refused in an
-environment that never asked for the refusal, with no way to answer back.
+`NODE_ENV` decides, and the decision is fail-closed: only `development` and `test` are
+non-production. Any other value is production, and in production the document is never built or
+mounted, whatever the configuration says. The guard runs twice, independently: the option
+resolver forces the feature off, and the bootstrap helper classifies the runtime again.
+Enabling it in production is a no-op with a warning naming the ignored option, so one
+configuration can be shared across environments. `NODE_ENV` cannot be overridden.
 
-Declare the environment and it is used **where the process declares nothing**:
+An application that validates its own `APP_ENV` and never sets `NODE_ENV` declares it, and the
+declaration is used **only where the process declares nothing**:
 
 ```typescript
 BymaxCoreModule.forRootAsync({
@@ -1359,25 +991,13 @@ BymaxCoreModule.forRootAsync({
 | unset, or blank | `staging`     | **production** |
 | unset, or blank | unset         | **production** |
 
-Two properties are worth reading off that table. A declaration never overrules a
-process that named its own environment — the first row is the one that matters,
-and it is asserted in both guards rather than in one. And the declaration enters
-the same fail-closed classification, so an unrecognized name is production like
-any other; this is a second **source** for the value, never a second set of
-rules.
-
-The narrowing is deliberate and worth naming rather than burying: in the one
-case where the process declares nothing, the configuration a consumer bound does
-decide the answer, because there is nothing else to decide it with. Replacing a
-guess with a declaration is not the same as allowing an override — but it is a
-real change to what the second guard depends on, and you should know it before
-relying on either.
+A declaration never overrules a process that named its own environment, and it goes through the
+same fail-closed classification: an unrecognized name is production.
 
 ### Testing the enabled path under Jest
 
-`applyBymaxOpenApi` loads `@nestjs/swagger` through a dynamic `import()` — that
-is what keeps the peer optional for everyone who never enables the document —
-and Jest's module registry cannot service a dynamic import without a flag:
+`applyBymaxOpenApi` loads `@nestjs/swagger` through a dynamic `import()`, which Jest's module
+registry cannot service without a flag:
 
 ```jsonc
 // package.json
@@ -1386,15 +1006,98 @@ and Jest's module registry cannot service a dynamic import without a flag:
 }
 ```
 
-Without it, only the **enabled** case fails, with `dynamic import callback
-invoked without --experimental-vm-modules`. The disabled and production cases
-never reach the loader and pass either way, which is what makes the omission
-confusing when you meet it.
+Without it only the **enabled** case fails, with `dynamic import callback invoked without
+--experimental-vm-modules`; the disabled and production cases never reach the loader.
+
+### Documenting authentication
+
+Set the default on the document and mark the exceptions. `security` names schemes declared in
+`securitySchemes`; `operationSecurity` overrides it for one operation, and an **empty array is
+how the specification says "public"**: an operation with _absent_ security inherits the document
+default, so a generated client would attach credentials to your registration endpoint.
+
+```ts
+openapi: {
+  enabled: true,
+  securitySchemes: {
+    cookieAuth: { type: 'apiKey', in: 'cookie', name: 'access_token' },
+    refreshCookie: { type: 'apiKey', in: 'cookie', name: 'refresh_token' }
+  },
+  security: [{ cookieAuth: [] }],
+  operationSecurity: {
+    'POST /auth/login': [],
+    'POST /auth/register': [],
+    'POST /auth/refresh': [{ refreshCookie: [] }]
+  }
+}
+```
+
+An operation that already declares its own requirement, because you decorated the handler, is
+never overwritten.
+
+**The operation key is a contract.** Keys are `"<METHOD> <path>"`: the method uppercase, one
+space, and the path exactly as it appears in the generated document — leading slash, template
+braces (`/users/{id}`), no trailing slash, **including any global prefix**
+(`'POST /api/auth/login'` when the application sets `setGlobalPrefix('api')`). A library that
+ships such a map should expose a **function taking the prefix**, because only the call site
+knows it; `OperationSecurityMap` is a type-only export for checking that map:
+
+```ts
+// in the library
+export function authOperationSecurity(prefix = ''): OperationSecurityMap {
+  return {} /* … */
+}
+
+// in the application
+BymaxCoreModule.forRoot({
+  openapi: { operationSecurity: { ...authOperationSecurity('api'), ...myOwnOverrides } }
+})
+```
+
+**What fails the document build.** A requirement naming an undeclared scheme, and a key matching
+no operation, each fail the build and list what missed and what exists: a stale key would
+otherwise quietly document a route as authenticated, or the reverse. These checks run **only
+when the document is built**: with `openapi.enabled` false, or in production, a stale key or a
+deleted scheme sits there until someone turns the document on. Keep at least one environment
+that runs your tests with the document enabled. A key naming a route that exists only in some
+environments fails the boot in a docs-enabled environment that lacks it, so assemble the map per
+feature the way you assemble the modules.
+
+**An operation that ends up requiring nothing** is a valid document, so nothing else catches it,
+and a client generated from it sends no credentials. When the document declares no top-level
+`security`, at least one other operation states a requirement, and the bare operation is not one
+of this package's own, the build logs a warning 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 because a public API is a legitimate configuration; `operationSecurity: {
+'GET /examples': [] }` states the intent and silences it. It cannot report the case where
+_every_ requirement is removed at once, since a document with no described operations is
+indistinguishable from a public API. Your own suite knows which one you are, so assert the
+default you expect (`expect(document.security).toEqual([{ cookieAuth: [] }])`, not
+`toBeDefined`, since `[]` is defined) and the set of operations that say `[]`.
+
+**A contributed scheme's presence belongs to the contributor's configuration.** A library
+decides which schemes it contributes from its own options. Derive a document-level default from
+the **same configuration the contributor reads**, never from a scheme name written as a literal:
+a literal is right only for the configuration you wrote it against, and under another it either
+describes one of two accepted credentials or fails the build as undeclared. The default's entries
+are **alternatives** — any one satisfies an operation — and apply to every operation that states
+nothing, so listing two credential families asserts that _either_ works for _every_ inheriting
+route, which is false. Give the majority family the default and the minority explicit
+`operationSecurity` entries, which outrank it.
 
 ### What the library contributes
 
-With `includeCoreSchemas` on, the document carries the contracts this package
-already serves, so an operation can `$ref` them instead of redeclaring them:
+With `includeCoreSchemas` on, the document carries the contracts this package serves, so an
+operation can `$ref` them:
 
 | Component                                                             | Describes                               |
 | --------------------------------------------------------------------- | --------------------------------------- |
@@ -1403,49 +1106,25 @@ already serves, so an operation can `$ref` them instead of redeclaring them:
 | `BymaxPageResult`, `BymaxPageMeta`, `BymaxCursorResult`               | The offset and cursor page shapes       |
 | `BymaxPageQueryPage`, `BymaxPageQueryLimit`, `BymaxCursorQueryCursor` | The pagination query parameters         |
 
-They are contributed as plain specification objects, not as decorated classes.
-That is what keeps `@nestjs/swagger` genuinely optional: a decorator runs when
-its class is defined, so describing these contracts with `@ApiProperty` would
-load the peer in every application that imports this package, including the ones
-that never enable the feature.
-
-A contributed entry never overwrites one the document already has: if you
-document your own `BymaxErrorEnvelope`, yours wins.
-
-Contributing the schemas is only half of it — the operations **reference** them,
-which is what a generated client actually reads:
-
-- every operation gains a `default` response pointing at `BymaxErrorEnvelope`,
-  because every error path in this package answers with that envelope. It is
-  attached as `default` rather than guessed per status code: this package knows
-  what an error looks like and does not know which statuses your handler emits.
-  It follows the feature: with `envelope.enabled` off, errors are shaped by Nest
-  or by your own handler, so nothing is documented;
-- the health endpoints gain an explicit `200` pointing at `BymaxHealthResponse`,
-  which this package _does_ know precisely, having registered them itself.
-
-`@nestjs/swagger` emits a placeholder response for every handler — a `200` with
-a description and no content — so "already documented" is judged on whether a
-response declares a **shape**: one carrying `content` — or written as a bare
-`$ref`, which points at a shape declared elsewhere — is yours and is left alone,
-one without either gets filled in while keeping any description you wrote.
-
-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.
+They are plain specification objects, not decorated classes: a decorator runs when its class is
+defined, so `@ApiProperty` would load `@nestjs/swagger` in every application that imports this
+package. A contributed entry never overwrites one the document already has.
 
-### A library can describe its own routes
+The operations **reference** them: every operation gains a `default` response pointing at
+`BymaxErrorEnvelope` (only while `envelope.enabled`, since otherwise errors are shaped by Nest or
+your handler), and the health endpoints gain an explicit `200` pointing at `BymaxHealthResponse`.
+A response is "already documented" when it declares a **shape** — `content`, or a bare `$ref` —
+and is left alone; the placeholder `@nestjs/swagger` emits is filled in, keeping any description
+you wrote. Both halves are one switch: `includeCoreSchemas: false` opts out of both, because a
+reference to a schema that was not contributed would dangle.
 
-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.
+### A library can describe its own routes
 
-So a library marks a provider and returns fragments keyed by **handler
-identity**, which survives every prefix, version and mount point:
+A library that ships controllers cannot document them itself: decorating them with
+`@nestjs/swagger` would load that peer in every importing application, and a consumer-side map
+keyed by path fails because a library mounted through `RouterModule.register` does not know its
+final paths. So a library marks a provider and returns fragments keyed by **handler identity**,
+which survives every prefix, version and mount point:
 
 ```ts
 import { Injectable } from '@nestjs/common'
@@ -1489,10 +1168,8 @@ export class AuthOpenApi implements IOpenApiContributor {
 }
 ```
 
-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
+Nothing is wired by the application: enabling the document runs the scan, and a library that is
+never imported contributes nothing.
 
 | Rule                  | Behavior                                                                                                                                                                       |
 | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -1504,60 +1181,26 @@ library that is never imported contributes nothing.
 | Versioned contract    | A fragment declares `contractVersion` as `BYMAX_OPENAPI_CONTRACT_VERSION`, currently `1`. A fragment declaring another version fails the document build, naming both versions. |
 | 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.
+**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. 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`, or to the format `@nestjs/swagger` produces, so a client
+generated before adopting this keeps working. A library that wants its schemas to track its own
+validation decorators derives them in its own build and commits the result, with a test that
+generated matches committed; this package takes no dependency on a validation library.
 
 ### The document describes _this_ deployment
 
-A feature you turned off has its routes removed from the document. With
-`metrics: { enabled: false }` the runtime answers `GET /metrics` with a 404
-envelope — on `forRootAsync` the controller is mounted unconditionally and
-guards each request, because route metadata is fixed before the async options
-resolve — so a document still listing the route would describe something this
-deployment does not serve. The filter reads the same resolved snapshot the
-runtime guard reads, which is what keeps the two from drifting.
-
-Your own routes are safe from it. `@nestjs/swagger` documents paths including
-`app.setGlobalPrefix()`, so the match cannot be on equality — but a bare tail
-match would treat `/tenants/{id}/health/live` as this package's probe and delete
-it from your document. What separates the two is that a global prefix prefixes
-_everything_: a tail match counts only when whatever precedes it also precedes
-every other path in the document. `/api/v2` qualifies; `/tenants/{id}` does not,
-because it does not prefix `/invoices`.
-
-This package also documents the security of the three routes it owns, without
-being asked:
+A feature you turned off has its routes removed from the document: with
+`metrics: { enabled: false }` the runtime answers `GET /metrics` with a 404 envelope, so a
+document still listing it would describe something this deployment does not serve. Your own
+routes are safe from the filter: it matches this package's paths including a global prefix, but
+a tail match counts only when whatever precedes it also precedes every other path in the
+document, so `/tenants/{id}/health/live` is never mistaken for the probe.
+
+This package also documents the security of the routes it owns, without being asked:
 
 | Route                               | Documented as                                           |
 | ----------------------------------- | ------------------------------------------------------- |
@@ -1565,19 +1208,11 @@ being asked:
 | `GET /metrics`, token set           | Bearer-protected                                        |
 | `GET /metrics`, no token            | Public (`security: []`), when a document default exists |
 
-The probes are polled by an orchestrator holding no credential, and the scrape
-endpoint is protected exactly when you configured a token — this package owns
-both the route and the option, so you should not have to restate either. Your
-own `operationSecurity` entry still wins.
-
-The last row matters more than it looks. Without a token the scrape endpoint
-answers anyone, which is the deliberate "protected at the edge" arrangement — and
-an open route must **say** it is open rather than inherit your document default.
-Of the two ways to describe a route wrongly, this is the direction that hides:
-documenting a guarded route as open fails loudly at the first generated client
-that omits the credential and gets a `401`, while documenting an open route as
-guarded fails nowhere at all, and hands the wrong answer to whoever opened the
-document to ask what is exposed.
+The probes are polled by an orchestrator holding no credential, and the scrape endpoint is
+protected exactly when you configured a token. An open route must **say** it is open rather than
+inherit your document default: documenting a guarded route as open fails at the first client
+that omits the credential, while documenting an open route as guarded fails nowhere. Your own
+`operationSecurity` entry still wins.
 
 ## 🧵 Trace correlation
 
@@ -1601,29 +1236,20 @@ collector setup already does, and doing it twice produces two spans per request.
 `@opentelemetry/api` is an optional peer, loaded once at bootstrap and only when
 the feature is on.
 
-A request with nothing recording, or an all-zero span context, resolves to no
-trace at all: the fields are absent rather than set to a sentinel, so a sink
-never has to recognize a string of zeros.
-
-### Publishing the id is a separate decision
+A request with nothing recording, or an all-zero span context, resolves to no trace at all: the
+fields are absent rather than set to a sentinel.
 
-`exposeTraceId` is off by default. A trace id is not a secret, but in a response
-body it tells a caller that a tracing backend exists and hands them the
-identifier that ties their request to everything else in that trace. Support
-teams often want exactly that, which is why the option exists; it is opt-in so it
-is a decision rather than a side effect. With it off, the identifiers still reach
-your samples and your logs.
+`exposeTraceId` is off by default: a trace id is not a secret, but in a response body it tells a
+caller that a tracing backend exists and hands them the identifier that ties their request to
+everything else in that trace. With it off, the identifiers still reach your samples and logs.
 
 ## 🔗 Integration with `@bymax-one/nest-logger`
 
-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:
+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`, which has no `getCorrelationId()`, so adapt it
+with a factory (`useExisting` would bind an object without that method, and the filter would read
+no id). Bind both tokens from a `@Global()` module of your own:
 
 ```typescript
 import { Global, Module } from '@nestjs/common'
@@ -1653,9 +1279,9 @@ import {
 export class ObservabilityModule {}
 ```
 
-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()`:
+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
@@ -1674,12 +1300,63 @@ async function bootstrap(): Promise<void> {
 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.
+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 overrides every pluggable token in this package.
+
+## 🧱 HTTP Floors
+
+`applyHttpFloors` (from `@bymax-one/nest-core/http`) is the HTTP-level protection that every
+backend wants and none should tune per deployment. One call, before `app.init()` and `app.listen()`:
+
+```typescript
+import { NestFactory } from '@nestjs/core'
+import { applyHttpFloors } from '@bymax-one/nest-core/http'
+import { AppModule } from './app.module'
+
+async function bootstrap(): Promise<void> {
+  const app = await NestFactory.create(AppModule)
+  await applyHttpFloors(app)
+  await app.listen(3000)
+}
+void bootstrap()
+```
+
+| What               | Default                                                                                                                                                                                                                                                                                                                             |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Security headers   | `helmet()` with `strictTransportSecurity: false` (TLS is normally ended in front of the app, which owns HSTS). Pass `helmet: { ... }` to tune it, for example the CSP of a browser-serving backend, or `helmet: false` to leave it out. `strictTransportSecurity: undefined` is not `false`: it turns helmet's HSTS default back on |
+| Request bodies     | The JSON and urlencoded parsers refuse a compressed body (`Content-Encoding`) with `415` instead of decompressing it, on every route and before routing. Only these two parsers: a raw or text parser you add yourself still decompresses. Size limits and the extended form syntax keep the parsers' defaults                      |
+| `headersTimeoutMs` | `15000`: the longest a client may take to send its complete header block. Node's own default is 60 s, which leaves a header block sent a byte at a time open as a cheap denial of service                                                                                                                                           |
+| `requestTimeoutMs` | `30000`: the longest a single request, headers and body together, may take. Node's default is 5 minutes. Must not be below `headersTimeoutMs`                                                                                                                                                                                       |
+
+`keepAliveTimeout` is left at Node's 5 s, which is too short behind a load balancer. A balancer whose
+idle timeout is longer than the server's reuses a connection Node has just closed and answers an
+intermittent `502`, so set it above the balancer's idle timeout, for example 61 s behind a 60 s one:
+`app.getHttpServer().keepAliveTimeout = 61_000`. The cost is that an idle socket is kept that much
+longer. Measured on Node 24, a `headersTimeoutMs` shorter than `keepAliveTimeout` (500 ms and 1 s
+against 3 s and 5 s) did not close an idle keep-alive socket, so the two need no particular order.
+
+Node enforces both timeouts from a sweep over the open connections, not from a timer per
+connection, and the sweep runs every 30 s by default: measured, a 1 s header timeout left a
+dribbled header block open for 30 s. The helper therefore also sets the server's
+`connectionsCheckingInterval` to one second (or the header timeout, if that is shorter), so a
+connection is cut within a second of its timeout expiring. Nest creates the server without
+exposing its options, so this is a property set before `listen()`: Node reads it when the server
+starts listening, and the helper throws if the server is already listening. The sweep walks every
+open connection each time, so a server holding very many sockets can set
+`connectionsCheckingIntervalMs` higher, at the cost of cutting up to that long after the timeout.
+
+**Order is part of the contract.** Call it before `app.init()` and right after `applyAccessLog` from
+`@bymax-one/nest-logger`, and before everything that reads the request: helmet is mounted first,
+so even a request the body parsers refuse carries the headers, and the parsers are registered
+here so Nest's own defaults, which accept gzip, are not (an application that needs a raw body on a route mounts that parser before calling it). Cookie parsing, the trusted-proxy
+setting and `applyBymaxOpenApi` stay with you and go after it. On an application that is already initialised the helper throws, because Nest's own parsers and the routes are registered ahead of anything mounted later:
+`applyAccessLog` → `applyHttpFloors` → cookie parser → trusted proxies → `applyBymaxOpenApi`.
+
+Express only; on another adapter it throws before applying anything. `helmet` is an optional
+peer, loaded only when the helper runs, and a missing one fails with the install command. An
+unusable timeout (zero, fractional, or a header timeout above the request timeout) throws
+rather than leaving a socket limit switched off.
 
 ## 🏗️ Architecture
 
@@ -1712,139 +1389,105 @@ BYMAX_CORRELATION_PROVIDER               no module,
  comes from)                             script or a test
 ```
 
-Four opt-in integrations attach to that spine rather than adding columns to it:
-
-```
-health/     + @BymaxHealthIndicator()   → a marked provider joins readiness
-metrics/    + @BymaxMetricsContributor() → a marked provider publishes on the registry
-envelope/   + telemetry                  → the active trace id reaches the envelope and the seam
-timing/     + telemetry                  → the sample carries traceId and spanId
-./openapi                                → one bootstrap call serves the document, in development
-```
-
-Each feature registers only when it is on. Turning metrics off does not leave a
-disabled provider in the container — it leaves no provider, and `prom-client` is
-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 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.
+Opt-in integrations attach to that spine rather than adding columns to it: a provider marked
+`@BymaxHealthIndicator()` joins readiness, one marked `@BymaxMetricsContributor()` publishes on
+the registry, telemetry puts the trace id on the envelope and the timing sample, and `./openapi`
+serves the document in development. No request data is retained: the timing middleware emits
+and forgets, and the pagination helpers are functions of their arguments.
 
 ### Design Principles
 
-| Principle                          | Description                                                                                                                                                               |
-| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🎭 **One shape for every failure** | The filter's job is to make a client's error handling independent of which service failed and how. An unknown error becomes a generic 500 with a code, not a leaked stack |
-| 🔌 **Enabled means registered**    | A feature that is off registers no provider at all, which is what lets `prom-client` remain an optional peer instead of an always-installed one                           |
-| 🧮 **Pure where it can be**        | Pagination is functions on their own subpath — no provider, no module, no container. A script can use it                                                                  |
-| 🧊 **Zero runtime dependencies**   | `dependencies` is `{}`. Every version you install is one you chose                                                                                                        |
-| 🩺 **A probe cannot hang**         | The aggregator converts a rejecting or slow indicator to `down` itself, so an indicator implementation never needs to guard its own timeout                               |
-| 🧬 **Explicit DI tokens**          | Tokens are `Symbol()`, so no string token can collide with them, and every injectable constructor parameter is decorated explicitly                                       |
+| Principle                          | Description                                                                                                                                                                                                   |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🎭 **One shape for every failure** | A client's error handling is independent of which service failed and how. An unknown error becomes a generic 500 with a code, not a leaked stack                                                              |
+| 🔌 **Enabled means registered**    | A feature that is off registers no provider at all, which is what keeps `prom-client`, `@nestjs/swagger`, `@opentelemetry/api` and `helmet` optional peers; the release gate asserts it on the packed tarball |
+| 🧮 **Pure where it can be**        | Pagination is functions on their own subpath — no provider, no module, no container                                                                                                                           |
+| 🧊 **Zero runtime dependencies**   | `dependencies` is `{}`. Every version you install is one you chose                                                                                                                                            |
+| 🩺 **A probe cannot hang**         | The aggregator converts a rejecting or slow indicator to `down` itself                                                                                                                                        |
+| 🧬 **Explicit DI tokens**          | Tokens are registered symbols (`Symbol.for`), so every bundle of this package resolves the same identity, and every injectable constructor parameter is decorated explicitly                                  |
 
 ---
 
 ## 🔐 Security Model
 
-This library writes the response a client sees when something fails, and exposes the
-endpoints an operator scrapes. Its security contract is about what those two surfaces
-disclose.
+This library writes the response a client sees when something fails, and exposes the endpoints an
+operator scrapes. Its security contract is about what those surfaces disclose.
 
 ### An error envelope is an exfiltration surface
 
-The filter's job is to make every failure look the same to a client, so an unknown error
-becomes a generic 500 whose body carries the fixed envelope fields and the generic message,
-and not the cause unless `exposeInternals` is on. The original message and stack go to the
-`BYMAX_UNEXPECTED_ERROR_SINK` seam when you bind one.
-`envelope.exposeInternals` puts them in the body and exists for local debugging — its own
-documentation says never to enable it in production, and it defaults to `false`.
+An unknown error becomes a generic 500 whose body carries the fixed envelope fields and the
+generic message, and not the cause unless `exposeInternals` is on. The original message and stack
+go to the `BYMAX_UNEXPECTED_ERROR_SINK` seam when you bind one. `envelope.exposeInternals` exists
+for local debugging only and defaults to `false`.
 
 ### The readiness response names the failure, it does not describe it
 
-A failing indicator produces `{ name, status: 'down' }` and nothing else. The reason goes
-to the logger.
-
-That split is deliberate. Readiness is usually unauthenticated and reachable by whatever
-probes it, and an indicator rarely authors its own failure text — it writes
-`await this.redis.ping()` and lets the driver's error propagate. Driver errors carry hosts,
-ports, and in the case of a connection string, credentials. Putting that text in the
-response publishes it to everyone who can reach the endpoint; putting it in the log keeps
-it where access is already controlled, without losing the diagnostic.
-
-`health.exposeIndicatorErrors` puts the message back in the response for local debugging.
-It defaults to `false`, and its documentation says the same thing `envelope.exposeInternals`
-does: never enable it in production. The two options are the same decision, made the same
-way, about the same risk.
-
-What reaches the log is bounded the same way it always was: the top-level `Error#message`
-only — never the raw error, its stack, or a nested cause — truncated at 300 characters.
-A slow indicator is converted to `down` by the aggregator rather than hanging the probe,
-and its `timedOutAfterMs` stays in the response either way, because that number is one this
-library chose rather than text an indicator produced.
+A failing indicator produces `{ name, status: 'down' }` and nothing else; the reason goes to the
+logger. Readiness is usually unauthenticated, and a driver's error carries hosts, ports and, in a
+connection string, credentials: in the response it is published to everyone who can reach the
+endpoint, in the log it stays where access is controlled. `health.exposeIndicatorErrors` puts the
+message back for local debugging, defaults to `false`, and carries the same warning as
+`exposeInternals`. What reaches the log is the top-level `Error#message` only — never the raw
+error, its stack or a nested cause — truncated at 300 characters. A slow indicator is converted to
+`down` by the aggregator, and its `timedOutAfterMs` stays in the response because that number is
+one this library chose.
 
 ### 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.
+Request timing is a security signal: 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 reaches a handler, so a recorder placed after the guards sees none of them.
+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.
+The label on a timing sample comes from the matched route **template**, and a request that matched
+nothing is recorded under the constant `UNMATCHED_ROUTE` (`<unmatched>`), never the requested
+path. Following the path would let anyone mint one Prometheus time series per probe and grow the
+registry without bound.
 
 ### Cursors are opaque, not secret
 
-`encodeCursor` produces a token a client can round-trip; it is not encrypted and not
-authenticated. Do not put anything in a cursor that the client is not allowed to read, and
-do not treat a cursor as proof of anything.
+`encodeCursor` produces a token a client can round-trip; it is neither encrypted nor
+authenticated. Put nothing in a cursor the client may not read, and do not treat one as proof of
+anything.
 
 ### The metrics endpoint is a route like any other
 
-It is off by default. When it is on, nothing in this library authenticates it — apply the
-guard you would apply to any internal endpoint, or keep it off the public listener.
+It is off by default. When on, nothing authenticates it unless you set `metrics.authToken`: apply
+the guard you would apply to any internal endpoint, or keep it off the public listener.
 
 ### The OpenAPI document does not exist in production
 
-A published document is a map of every route, parameter and error shape an application has —
-useful to a developer, and just as useful to anyone probing the service. So unlike the metrics
-endpoint, it is not left to a guard: it is refused outright whenever the runtime is not
-positively `development` or `test`, in two independent layers. **`NODE_ENV` cannot be
-overridden** — with it set to anything, no option serves the document in a runtime it named
-production. A runtime that declares nothing is classified from the application's own
-[`environment`](#environment) when it supplied one, and counts as production otherwise, because
-the deployment nobody configured is the one most likely to be exposed.
+A published document maps every route, parameter and error shape, which is as useful to someone
+probing the service as to a developer. So unlike the metrics endpoint it is not left to a guard:
+it is refused whenever the runtime is not positively `development` or `test`, in two independent
+layers. **`NODE_ENV` cannot be overridden.** A runtime that declares nothing is classified from the
+application's own [`environment`](#environment) when it supplied one, and counts as production
+otherwise.
 
 ---
 
 ## 🛡️ Security Table
 
-| Layer               | Implementation                                                                                                                                                                   |
-| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Error responses     | One shape for everything; unknown errors become a generic 500                                                                                                                    |
-| Internals           | Message and stack handed to the unexpected-error sink when bound, in the body only under `exposeInternals` (default `false`)                                                     |
-| 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                                                   |
-| Discovered checks   | Matched by an explicit marker, never by shape; off by default, because it lets an imported library fail your readiness probe                                                     |
-| Contributed metrics | Called only when marked; a name collision fails the boot naming the contributor rather than half-populating a scrape                                                             |
-| Trace ids           | Read-only, never used as a metric label; published in a response body only under `telemetry.exposeTraceId` (default off)                                                         |
-| Supply chain        | `dependencies: {}`; third-party Actions pinned by commit SHA (org-internal reusables by tag); CodeQL and OpenSSF Scorecard                                                       |
+| Layer               | Implementation                                                                                                                                                                                                                |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Error responses     | One shape for everything; unknown errors become a generic 500                                                                                                                                                                 |
+| Internals           | Message and stack handed to the unexpected-error sink when bound, in the body only under `exposeInternals` (default `false`)                                                                                                  |
+| Health output       | The response carries each indicator's name and status, never the `details` it returned; a failing indicator's 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                                                                                                                                       |
+| Body nesting        | Opt-in `bodyDepth` refuses a body nested deeper than `maxDepth` with a `400`, so a few kilobytes of nested arrays cannot overflow a recursive validator into a `500`                                                          |
+| HTTP floors         | `applyHttpFloors`: compressed request bodies refused with `415`, header and request timeouts of 15 s and 30 s, `helmet` headers without HSTS                                                                                  |
+| 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                                                                                                |
+| Discovered checks   | Matched by an explicit marker, never by shape; off by default, because it lets an imported library fail your readiness probe                                                                                                  |
+| Contributed metrics | Called only when marked; a name collision fails the boot naming the contributor rather than half-populating a scrape                                                                                                          |
+| Trace ids           | Read-only, never used as a metric label; published in a response body only under `telemetry.exposeTraceId` (default off)                                                                                                      |
+| Supply chain        | `dependencies: {}`; third-party Actions pinned by commit SHA (org-internal reusables by tag); CodeQL and OpenSSF Scorecard                                                                                                    |
 
 > [!IMPORTANT]
 > **`exposeInternals` is a debugging switch, not a verbosity setting.** With it on,
@@ -1860,8 +1503,10 @@ the deployment nobody configured is the one most likely to be exposed.
 - **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
+  OpenAPI is enabled, `@opentelemetry/api ^1.9` when trace correlation is enabled, `helmet ^8`
+  when `applyHttpFloors` runs — none is imported while its feature is off
+- **Adapters:** Express and Fastify for timing, the filter and health; the body-depth guard and
+  `applyHttpFloors` are Express only
 - **Build:** tsup — ESM + CJS per subpath, with `.d.ts` _and_ `.d.cts` declarations
 - **Tests:** Jest (unit + e2e over real Nest applications, Express **and** Fastify) + Stryker (mutation)
 - **TypeScript:** 5.x strict (`noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`), zero `any`
@@ -1874,10 +1519,9 @@ This library sits in the path of every request and every failure of every servic
 installs it, so the suite is held to a bar beyond "the tests pass".
 
 - ✅ **100% line coverage** — statements, branches, functions and lines, enforced as a gate
-- ✅ **100% mutation score** — verified with [Stryker](https://stryker-mutator.io/) at
-  `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))
+- ✅ **100% mutation score** — [Stryker](https://stryker-mutator.io/) runs with `break: 100`, so
+  a surviving mutant fails the run; a mutant no test can kill carries its reason on the line it
+  applies to ([report](./docs/mutation_testing_results.md))
 - ✅ **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
@@ -1895,7 +1539,7 @@ installs it, so the suite is held to a bar beyond "the tests pass".
 pnpm test          # unit suite
 pnpm test:cov      # unit suite with the 100% coverage gate
 pnpm test:e2e      # end-to-end against real Nest applications (Express and Fastify)
-pnpm mutation      # Stryker mutation testing (break: 95)
+pnpm mutation      # Stryker mutation testing (break: 100)
 pnpm typecheck     # tsc strict check
 pnpm lint          # ESLint
 ```
@@ -1909,27 +1553,28 @@ 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_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, registered nowhere.** `BymaxTimingMiddleware` replaced it as the recorder because guards run before interceptors, so it never saw a request a guard rejected; wiring it by hand next to the middleware records a second sample for every request that reaches a handler. Kept so code that wired it by hand keeps compiling. |
-| `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`, `BodyDepthOptions`, `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.                                                                                                                                                                                                                                                              |
+| `BymaxBodyDepthMiddleware`                                                                                                                                                                                                           | class     | Refuses a body nested deeper than `bodyDepth.maxDepth` with a `400`; applied to every route, after the timing middleware, only when `bodyDepth.enabled` is true.                                                                                                                                                                           |
+| `UNMATCHED_ROUTE`                                                                                                                                                                                                                    | constant  | The bounded label recorded when a request matched no route (`<unmatched>`).                                                                                                                                                                                                                                                                |
+| `TimingInterceptor`                                                                                                                                                                                                                  | class     | **Deprecated, registered nowhere.** `BymaxTimingMiddleware` replaced it as the recorder because guards run before interceptors, so it never saw a request a guard rejected; wiring it by hand next to the middleware records a second sample for every request that reaches a handler. Kept so code that wired it by hand keeps compiling. |
+| `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`
 
@@ -1963,6 +1608,13 @@ in the sections above.
 | `IMetricsContributor`                | type     | The contract: `registerMetrics(registry)`.                   |
 | `MetricsRegistry`                    | type     | The `prom-client` registry the scrape endpoint serves.       |
 
+### `./http`
+
+| Export                                         | Kind     | Description                                                                               |
+| ---------------------------------------------- | -------- | ----------------------------------------------------------------------------------------- |
+| `applyHttpFloors`                              | function | Applies the headers, the body-parser floor and the timeouts; call it before `app.init()`. |
+| `HttpFloorsOptions`, `HttpFloorsHelmetOptions` | types    | The `helmet`, `headersTimeoutMs` and `requestTimeoutMs` options.                          |
+
 ### `./openapi`
 
 | Export                                                                                 | Kind                | Description                                                                                       |
@@ -1975,24 +1627,28 @@ in the sections above.
 | `BYMAX_OPENAPI_CONTRACT_VERSION`                                                       | constant            | The version of the fragment contract, currently `1`; a fragment declares it as `contractVersion`. |
 | `IOpenApiContributor`, `OpenApiFragment`, `OpenApiFragmentObject`, `OpenApiHandlerKey` | types               | The contributor contract and the shape of what it returns.                                        |
 
-## 🧩 Compatibility
-
-- Node.js `>= 24`
-- NestJS `^11`
-- 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.
+## 🚫 What This Library Does NOT Do
+
+- **It mints no request id.** `correlationId` is whatever the `BYMAX_CORRELATION_PROVIDER` you
+  bind returns; with none bound the field is absent.
+- **It creates no span and configures no OpenTelemetry SDK.** Trace correlation only reads the
+  span your instrumentation already opened.
+- **It validates no request body.** There is no validation pipe here; `bodyDepth` only bounds
+  nesting, ahead of yours.
+- **It authenticates and authorizes nothing.** The one credential it knows is the optional
+  `metrics.authToken`; guards, sessions and roles are yours.
+- **It keeps no request data.** Timing samples go to the sink you register.
+- **It does not cover GraphQL or RPC execution contexts.** The error envelope and request timing
+  pass those through untouched.
+- **It does not cover Fastify** for the body-depth guard, `applyHttpFloors`, or the fixed messages
+  of refusals raised before routing. Request timing and the envelope's path handling are
+  asserted end to end on both Express and Fastify.
+- **It never serves the OpenAPI document in production,** whatever the configuration says.
 
 ## 🤝 Contributing
 
 Pull requests are welcome. Please open an issue first for significant changes.
 
-- Read [`docs/technical_specification.md`](./docs/technical_specification.md) for architecture decisions.
 - Run the full gate listed in [`CONTRIBUTING.md`](./CONTRIBUTING.md) before opening a PR.
 - Conventional Commits are enforced by `commitlint.config.cjs`.