@bymax-one/nest-core 1.5.2 → 1.6.0

package/CHANGELOG.md

@@ -11,6 +11,228 @@ heading here.
 
 ## [Unreleased]
 
+## [1.6.0] - 2026-08-29
+
+A readiness check that fails without rejecting left no record an operator would
+ever read, and one that fails by rejecting left one per probe. Both are the same
+missing seam, and this release adds it: the aggregator now holds the last state
+of every check and reports each **change** — to its own logger, and to an
+optional sink a consumer binds.
+
+**Apply to a derived backend:** nothing is required. Transitions now reach Nest's
+logger on every path, where before only a rejection did. Bind
+`BYMAX_HEALTH_TRANSITION_SINK` to route them into a structured logging surface,
+and read `cause.kind` to tell the three failure shapes apart. If you have written
+a health reporter of your own, delete it — including any wrapper that races a
+timer beneath `health.indicatorTimeoutMs` to recover a verdict, which this seam
+makes unnecessary.
+
+### Added
+
+- **`IHealthTransitionSink`, bound under `BYMAX_HEALTH_TRANSITION_SINK`.**
+  Receives one `HealthTransition` per change of readiness state, per check name —
+  never one per probe. `@Optional()` and unbound by default, like
+  `BYMAX_HEALTH_INDICATORS`, so a consumer's binding is never shadowed by a local
+  one.
+
+  With no sink the aggregator writes the transition to Nest's logger, so a
+  readiness failure is never silent by default; binding one stands that line down
+  in favour of the sink. Both destinations are usually the same logger in a
+  consuming application, and two records of one transition side by side is the
+  noise this feature exists to remove. The sink is handed the cause as structured
+  data, strictly more than the line renders, so what reaches the log after that
+  is the consumer's decision rather than this package's.
+
+  The de-duplication rule lives in the aggregator rather than in the sink, and
+  that is the whole point. A readiness check runs every few seconds, so a line
+  per failing probe turns one outage into thousands of identical records that
+  bury the one carrying the cause; leaving that rule to each consumer means every
+  backend re-deriving it, slightly differently. A sink that never sees raw
+  outcomes cannot get it wrong.
+
+  Overlapping probes are ordered by when they started, not by when they
+  finished. Readiness is not called one at a time — an orchestrator's probe and a
+  load balancer's health check reach it concurrently — and a dependency that
+  hangs until the bound elapses is exactly what makes an earlier probe finish
+  last. Comparing states alone would write such an outage backwards: the later
+  probe reports the recovery, and the earlier one's timeout lands behind it and
+  reports the dependency down again on evidence that is already stale.
+
+  The rule is asymmetric on a first observation, deliberately. A first
+  observation that is **failing** is reported — a process that boots against a
+  dependency already down would otherwise look healthy in the log forever — while
+  a first observation that is healthy is not, since announcing the expected state
+  would write one line per dependency on every boot.
+
+- **`HealthTransitionCause`, distinguishing the three ways a check is down.**
+  `reported-down` (the indicator answered and said so), `rejected` (carrying the
+  summarized message, bounded to 300 characters), and `timed-out` (carrying the
+  `timeoutMs` that elapsed). A discriminated union rather than a string, so a
+  consumer switches exhaustively and the compiler names the arm it has not
+  handled if a future version adds one.
+
+  `timed-out` is the one that exists nowhere else. An indicator this package
+  gave up on is never told, so it reports nothing, and a consumer racing its own
+  timer beneath `indicatorTimeoutMs` still never learns the bound that actually
+  applied. A hung dependency is also the common shape rather than a refused one:
+  a database under load, a network partition and a paused container all hang,
+  while a refusal returns immediately and would have been reported. The obstacle
+  for a consumer is information, not effort — which is the argument for this
+  living in the library at all.
+
+### Fixed
+
+- **An `Error` whose `message` is not a string broke the readiness aggregation.**
+  `message` is a writable property, so `Object.assign(new Error(), { message:
+null })` is an `Error` that reads without throwing and then throws on every
+  string operation. The summarizer coerced a non-`Error` reason but trusted an
+  `Error`'s own `message`, then measured and truncated it outside that guard.
+
+  It surfaced where the guard was supposed to hold. Summarizing runs inside the
+  rejection-to-`down` conversion, so an indicator rejecting with such an error
+  rejected the whole aggregation: the probe answered `500` instead of `503`, and
+  reported nothing about the dependencies that were healthy — the exact outcome
+  the conversion exists to prevent.
+
+  **This is present in 1.5.3 and earlier**, on the indicator path. The transition
+  sink added in this release reaches the same summarizer, so the fix covers both.
+
+- **An `async` timing sink could take the process down.** `ITimingSink.record`
+  is declared to return `void`, and TypeScript accepts any return value in a
+  void-returning position, so `async record()` compiles — and it is the natural
+  shape when the backend behind the sink is async. Its rejection settled a
+  microtask after the recorder's `try`/`catch` had exited, so instead of the
+  contained failure the contract promises it became an unhandled rejection, able
+  to kill the process under `--unhandled-rejections=strict`. An observer that can
+  break what it observes is the one thing a fire-and-forget contract exists to
+  rule out.
+
+  Both the middleware and the deprecated interceptor were affected, and both now
+  route delivery through one implementation rather than two copies of the same
+  `try`/`catch` — the containment guarantee is worth exactly as much as its least
+  careful copy. Nothing to change in a consumer: a sink that already returned
+  synchronously behaves identically, and an `async` one is now caught.
+
+  Found while reviewing the health transition sink, which had the same hole
+  before release.
+
+### Changed
+
+- **A rejecting indicator is logged once per outage, not once per probe.** The
+  aggregator already wrote a warning for a rejection, on every readiness check
+  for as long as the dependency stayed down: roughly sixty identical lines for a
+  ten-minute outage probed every ten seconds. That line now follows the
+  transition rule like every other path. No API moves; log volume does, and a
+  recovery now writes a line where nothing did before.
+
+  This arrives with the upgrade, not with the binding — a deployment that wires
+  no sink still stops repeating.
+
+  The cost is stated rather than hidden: a dependency that stays down while its
+  failure mode changes underneath keeps the cause observed **at the transition**.
+  That is the trade for one line per outage instead of one per probe.
+
+- **The root bundle's size budget moved from 15 to 17 KiB brotli**, measured
+  14.25 → 15.82. Checked before the number moved: the transition contract is
+  types-only and erases at build time, no module entered the root that was not
+  already there, and the rationale prose was moved into the erased file — this
+  bundle ships its comments — before the budget was touched.
+
+## [1.5.3] - 2026-08-18
+
+Three findings from a functional and security audit of a derived backend
+running against real Postgres, Redis and MinIO, plus the corrections that
+review found inside those fixes.
+
+The one that reaches a running deployment: an unprotected `/metrics` was
+documented as **requiring a credential**. The endpoint answers anyone when no
+`metrics.authToken` is set — the documented "protected at the edge"
+arrangement — and it inherited the document-level default instead of declaring
+itself public. That is the opposite of what 1.5.0 fixed and the more dangerous
+direction: documenting a guarded route as open fails loudly at the first
+generated client that omits the credential, while documenting an open route as
+guarded fails nowhere and hands the wrong answer to whoever opened the document
+to ask what is exposed.
+
+**Apply to a derived backend:** bump the dependency. Nothing to change in code.
+If you serve a document and leave the scrape endpoint unprotected, re-render it
+and confirm `/metrics` now carries `security: []`. If your page indexes reach
+SQL, `maxOffset` is now available and is opt-in.
+
+### Fixed
+
+- **An unprotected `/metrics` was documented as requiring a credential.** This
+  package writes an explicit `security: []` on its health probes so they do not
+  inherit a document-level default, and did not do the same for the scrape
+  endpoint. With `metrics.authToken` unset — the documented "protected at the
+  edge" arrangement, where the endpoint answers anyone — `GET /metrics` fell
+  through and inherited the default, so a document served by any backend with a
+  default claimed a credential was required for an endpoint serving process
+  metrics to whoever asked.
+
+  Measured on a running derived backend, not reasoned about: no credential →
+  `200` with the full Prometheus body, while the served document said
+  `security: [{ bymaxAuthAccessCookie: [] }]`.
+
+  **One half of the fix is covered by unit tests only, and that is worth saying
+  rather than leaving it to look field-verified.** The reported symptom reaches
+  a deployment through `openapi.security`, and that path was measured. Review
+  then found the same hole on the other path — a document that arrives carrying
+  its own default, whose `openapi.security` is therefore empty — and it is fixed
+  by reading the effective default from the document that will be served. No
+  consumer known to this project reaches that state today, so the only coverage
+  that can be pointed at is this repository's tests — which is a statement about
+  what is known, not a guarantee that nothing else exercises it. The health probes carried the same defect on
+  that path and are fixed by the same change.
+
+  This is the more dangerous of the two ways to describe a route wrongly, and
+  the opposite of what 1.5.0 fixed. Documenting a **guarded** route as open
+  fails loudly — a generated client omits the credential and gets a `401`.
+  Documenting an **open** route as guarded fails nowhere, and hands the wrong
+  answer to whoever opened the document to ask what is exposed.
+
+### Added
+
+- **`maxOffset`, a bound on how far into a dataset a request may start.**
+  `normalizePageQuery` capped the page size through `maxLimit` and bounded the
+  page index only for arithmetic safety, so `?page=1000000000&limit=20` resolved
+  to `OFFSET 19999999980`. Harmless against an in-memory repository and paid in
+  full by an offset-paginated database: twenty bytes of query for a table scan.
+
+  It 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. `0` is a valid bound meaning "the
+  first page only"; any value that is not a non-negative safe integer reads as
+  absent rather than as an invented cap. Clamping matches how `maxLimit` already
+  behaves, and the resolved values come back in `meta`.
+
+### Documentation
+
+- **What the error filter classifies from, and what it cannot.** An error raised
+  before any handler ran becomes a clean `4xx` because the filter recognizes it
+  by **shape** — `expose: true` with a `4xx` status, the convention Node's body
+  pipeline follows — not by class. An error carrying no such marking is a `500`
+  even when a client caused it: a few kilobytes nested thousands of levels deep
+  overflows the stack during validation and surfaces as `RangeError`, well under
+  any size limit.
+
+  That is deliberate. Mapping `RangeError` to a `4xx` would make the filter
+  infer causation from an error class and would be wrong where it matters most —
+  a genuine stack overflow in application code is a `500` that should page
+  someone. Body-shape limits are the application's floor, applied in the one
+  window where the body exists and nothing has walked it yet.
+
+  **Apply to a derived backend:** cap nesting depth **after the body parser and
+  before validation**, so a hostile body is rejected as the `400` it is instead
+  of becoming a `5xx` that pollutes your error rate and writes a stack per
+  request. On Express that means module middleware, not `app.use()` during
+  bootstrap — measured, a middleware registered there runs ahead of Nest's own
+  parser and sees `req.body` as `undefined`, so the guard inspects nothing and
+  protects nothing while reading as present. Walk the parsed body iteratively; a
+  recursive depth check on a hostile payload overflows the stack it exists to
+  protect. The README carries the per-adapter table and a test that proves the
+  floor by behaviour rather than by where it is registered.
+
 ## [1.5.2] - 2026-08-15
 
 The production guard read `NODE_ENV` and nothing else, and treated an unset
@@ -779,4 +1001,6 @@ have regressed from. They are kept because the reasoning is worth having.
 [1.5.0]: https://github.com/bymaxone/nest-core/compare/v1.4.0...v1.5.0
 [1.5.1]: https://github.com/bymaxone/nest-core/compare/v1.5.0...v1.5.1
 [1.5.2]: https://github.com/bymaxone/nest-core/compare/v1.5.1...v1.5.2
-[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.5.2...HEAD
+[1.5.3]: https://github.com/bymaxone/nest-core/compare/v1.5.2...v1.5.3
+[1.6.0]: https://github.com/bymaxone/nest-core/compare/v1.5.3...v1.6.0
+[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.6.0...HEAD

package/README.md

@@ -515,9 +515,9 @@ requirement.
 
 ## 🔑 DI Tokens
 
-Every token is a `Symbol`. `BYMAX_CORRELATION_PROVIDER` and
-`BYMAX_HEALTH_INDICATORS` are consumed with `@Optional()` and are not bound by
-the module: provide either from your own module to supply your own
+Every token is a `Symbol`. `BYMAX_CORRELATION_PROVIDER`,
+`BYMAX_HEALTH_INDICATORS` and `BYMAX_HEALTH_TRANSITION_SINK` are consumed with
+`@Optional()` and are not bound by the module: provide either from your own module to supply your own
 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
@@ -528,14 +528,15 @@ consumer `BYMAX_TIMING_SINK` override is honored on `forRoot` but shadowed on
 [Integration with `@bymax-one/nest-logger`](#-integration-with-bymax-onenest-logger)
 below.
 
-| Token                        | Provides                              | When you do not provide one                                                                                       |
-| ---------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `BYMAX_CORE_OPTIONS`         | The resolved `BymaxCoreModuleOptions` | always set by the module                                                                                          |
-| `BYMAX_CORRELATION_PROVIDER` | `ICorrelationIdProvider`              | internal no-op (omits `correlationId`)                                                                            |
-| `BYMAX_TIMING_SINK`          | `ITimingSink`                         | internal no-op, or the metrics bridge when timing and metrics are both enabled                                    |
-| `BYMAX_HEALTH_INDICATORS`    | `IHealthIndicator[]`                  | treated as an empty indicator set                                                                                 |
-| `BYMAX_METRICS_REGISTRY`     | the `prom-client` `Registry`          | bound when metrics are enabled; on `forRootAsync` always registered, guarded-placeholder when off                 |
-| `BYMAX_TRACE_CONTEXT`        | `ITraceContextProvider`               | bound on every path: the OpenTelemetry reader when telemetry is enabled, a no-op that resolves no trace otherwise |
+| Token                          | Provides                              | When you do not provide one                                                                                       |
+| ------------------------------ | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `BYMAX_CORE_OPTIONS`           | The resolved `BymaxCoreModuleOptions` | always set by the module                                                                                          |
+| `BYMAX_CORRELATION_PROVIDER`   | `ICorrelationIdProvider`              | internal no-op (omits `correlationId`)                                                                            |
+| `BYMAX_TIMING_SINK`            | `ITimingSink`                         | internal no-op, or the metrics bridge when timing and metrics are both enabled                                    |
+| `BYMAX_HEALTH_INDICATORS`      | `IHealthIndicator[]`                  | treated as an empty indicator set                                                                                 |
+| `BYMAX_HEALTH_TRANSITION_SINK` | `IHealthTransitionSink`               | no sink; readiness transitions go to Nest's logger instead (binding one stands that line down)                    |
+| `BYMAX_METRICS_REGISTRY`       | the `prom-client` `Registry`          | bound when metrics are enabled; on `forRootAsync` always registered, guarded-placeholder when off                 |
+| `BYMAX_TRACE_CONTEXT`          | `ITraceContextProvider`               | bound on every path: the OpenTelemetry reader when telemetry is enabled, a no-op that resolves no trace otherwise |
 
 ## 🚨 Error Envelope
 
@@ -576,6 +577,96 @@ import { BadRequestException } from '@nestjs/common'
 throw new BadRequestException({ code: 'INVOICE_OVERDUE', message: 'Invoice is overdue' })
 ```
 
+### 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 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 Timing
 
 One `RequestTimingSample` is delivered to whatever implements `ITimingSink` for
@@ -667,6 +758,13 @@ 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.
+
 ## 📄 Pagination
 
 Framework-neutral, pure functions on the `./pagination` subpath: no NestJS
@@ -689,13 +787,36 @@ export class InvoiceController {
 
   @Get()
   async list(@Query() raw: Record<string, unknown>): Promise<PageResult<Invoice>> {
-    const query = normalizePageQuery(raw, { maxLimit: 50 })
+    const query = normalizePageQuery(raw, { maxLimit: 50, maxOffset: 100_000 })
     const { rows, total } = await this.invoices.findPage(query)
     return buildPageResult(rows, total, query)
   }
 }
 ```
 
+#### 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".
+
+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.
+
 ### Cursor pagination
 
 ```typescript
@@ -787,6 +908,82 @@ 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.
 
+### A failing check leaves a record
+
+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.
+
+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:
+
+```typescript
+import { Injectable } from '@nestjs/common'
+import type { HealthTransition, IHealthTransitionSink } from '@bymax-one/nest-core/health'
+
+@Injectable()
+export class HealthTransitionLogger implements IHealthTransitionSink {
+  constructor(private readonly logger: MyStructuredLogger) {}
+
+  record(transition: HealthTransition): void {
+    if (transition.isUp) {
+      this.logger.info('HEALTH_CHECK_RECOVERED', { check: transition.name })
+      return
+    }
+    this.logger.warn('HEALTH_CHECK_DEGRADED', {
+      check: transition.name,
+      cause: transition.cause.kind
+    })
+  }
+}
+```
+
+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:
+
+| `cause.kind`    | Meaning                                            | Carries     |
+| --------------- | -------------------------------------------------- | ----------- |
+| `reported-down` | The indicator answered, and reported it down.      | —           |
+| `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.
+
 ### Discovered indicators
 
 Registering every indicator by hand stops scaling once the libraries an
@@ -1212,13 +1409,23 @@ being asked:
 | Route                               | Documented as                                           |
 | ----------------------------------- | ------------------------------------------------------- |
 | `GET /health/live`, `/health/ready` | Public (`security: []`), when a document default exists |
-| `GET /metrics`                      | Bearer-protected **iff** `metrics.authToken` is set     |
+| `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.
+
 ## 🧵 Trace correlation
 
 Off by default. Enabled, it reads the span your instrumentation already opened
@@ -1513,7 +1720,8 @@ in the sections above.
 | `BymaxCoreModuleOptions`, `EnvelopeOptions`, `TimingOptions`, `HealthOptions`, `MetricsOptions`, `TelemetryOptions`, `OpenApiOptions`, `OpenApiServerDescriptor`, `OpenApiSecurityScheme`, `ResolvedCoreOptions` | types     | The options surface and its resolved shape.                                        |
 | `OpenApiSecurityRequirement`, `OpenApiHttpMethod`, `OpenApiOperationKey`, `OperationSecurityMap`                                                                                                                 | types     | The operation-key contract a sibling library targets to ship its own security map. |
 | `OpenApiOperationIdFactory`                                                                                                                                                                                      | type      | Names the operations in the generated document.                                    |
-| `BYMAX_CORE_OPTIONS`, `BYMAX_CORRELATION_PROVIDER`, `BYMAX_TIMING_SINK`, `BYMAX_HEALTH_INDICATORS`, `BYMAX_METRICS_REGISTRY`                                                                                     | tokens    | The DI tokens; see the [token table](#-di-tokens).                                 |
+| `BYMAX_CORE_OPTIONS`, `BYMAX_CORRELATION_PROVIDER`, `BYMAX_TIMING_SINK`, `BYMAX_HEALTH_INDICATORS`, `BYMAX_HEALTH_TRANSITION_SINK`, `BYMAX_METRICS_REGISTRY`, `BYMAX_TRACE_CONTEXT`                              | tokens    | The DI tokens; see the [token table](#-di-tokens).                                 |
+| `IHealthTransitionSink`, `HealthTransition`, `HealthTransitionCause`                                                                                                                                             | types     | The readiness-transition contract; also on `./health`.                             |
 | `ICorrelationIdProvider`                                                                                                                                                                                         | type      | The correlation-provider contract.                                                 |
 | `ITraceContextProvider`, `TraceContext`                                                                                                                                                                          | types     | The trace-context contract and the identifiers it resolves.                        |
 | `BymaxExceptionFilter`                                                                                                                                                                                           | class     | The envelope exception filter.                                                     |
@@ -1544,6 +1752,9 @@ in the sections above.
 | `HealthIndicatorResult`           | type     | The outcome of a single indicator check.            |
 | `HealthCheckEntry`                | type     | One named entry in a `HealthResponse.checks` array. |
 | `HealthResponse`                  | type     | The stable liveness and readiness response shape.   |
+| `IHealthTransitionSink`           | type     | Receives one event per change of readiness state.   |
+| `HealthTransition`                | type     | One change of state, for one check.                 |
+| `HealthTransitionCause`           | type     | Why a check went down, as the aggregator sees it.   |
 | `BymaxHealthIndicator`            | function | Class decorator marking a provider as discoverable. |
 | `BYMAX_HEALTH_INDICATOR_METADATA` | constant | The metadata key the marker writes.                 |
 

package/dist/health/index.d.cts

@@ -1,4 +1,5 @@
 import { CustomDecorator } from '@nestjs/common';
+export { H as HealthTransition, a as HealthTransitionCause, I as IHealthTransitionSink } from '../health.transition-B_IgXJTz.cjs';
 
 /**
  * Reflect metadata key carrying the discoverable marker. Namespaced so it cannot

package/dist/health/index.d.ts

@@ -1,4 +1,5 @@
 import { CustomDecorator } from '@nestjs/common';
+export { H as HealthTransition, a as HealthTransitionCause, I as IHealthTransitionSink } from '../health.transition-B_IgXJTz.js';
 
 /**
  * Reflect metadata key carrying the discoverable marker. Namespaced so it cannot