@bymax-one/nest-core 1.5.3 → 1.6.1

package/CHANGELOG.md

@@ -11,6 +11,216 @@ heading here.
 
 ## [Unreleased]
 
+## [1.6.1] - 2026-09-05
+
+A library contributing an OpenAPI component under a name the application already
+declared had its entry discarded, and neither side could tell. The document
+validated, the served output looked exactly as it would have had nothing been
+offered, and the contributing library received no signal at all — so the failure
+was indistinguishable from success at both ends.
+
+Two changes, and they are independent: an empty placeholder no longer counts as a
+declaration, and every genuine collision is now reported.
+
+**This patch adds public surface**, which a patch number cannot tell you:
+`discarded` on `OpenApiMountOutcome`, and the `DiscardedComponent` type it holds.
+Both are additive and nothing is removed or renamed, so the digit stays at a
+patch under this project's versioning policy — which means this paragraph, rather
+than the version, is what says there is something new to look for.
+
+**Apply to a derived backend:** nothing is required, and no served document loses
+anything it carried. A schema the application declares with a shape of its own
+still wins, exactly as before. What changes is that a schema present only as
+`{"type":"object","properties":{}}` — which `@nestjs/swagger` emits for every DTO
+in a package built without its plugin — is now filled from the contribution
+rather than preferred over it. Read `discarded` on the `OpenApiMountOutcome` to
+see what a contributor offered and did not place; the boot log reports the same
+entries.
+
+### Added
+
+- **`discarded` on `OpenApiMountOutcome`, and the `DiscardedComponent` type.**
+  Lists every contributed component entry the document already declared with a
+  shape of its own, naming the contributor, the member and the entry. Present
+  whenever the document mounted, empty when every contribution was placed — an
+  empty array reports that the merge looked and found none, which absence would
+  confuse with not having looked.
+
+  Carries the contributor's label because a collision is only actionable if you
+  know whose entry lost: an application with several contributing libraries would
+  otherwise be told a name was dropped without being told by whom.
+
+  A warning reports the same entries on the way up, elided into a count on the
+  same reasoning as the unsecured-operation line beside it — a library contributing a
+  schema per DTO turns one collision into a hundred, and the version that prints
+  them all is the one an operator learns to skip.
+
+### Changed
+
+- **A schema that describes no shape no longer counts as a declaration.** The
+  merge still prefers what the document carries: a consumer authored theirs on
+  purpose, and a library silently overwriting it is the worse defect wearing the
+  other sign. But `@nestjs/swagger` emits `{"type":"object","properties":{}}` for
+  every DTO in a package built without its plugin, so the name is never actually
+  missing and a contributed schema under it would never be written. The more
+  correct the library's own schema, the more completely it was discarded, because
+  a correct schema and an empty one collide on the same key.
+
+  This is the rule `mergeResponses` already applied to responses, arriving
+  through a different placeholder — a `200` carrying a description and no
+  `content` occupies its status the same way. Filling one in is additive: it
+  constrains nothing before and describes a shape after.
+
+  The test is deliberately narrow. `type` must be absent or `object`, because
+  `{"type":"string"}` carries no properties and is nonetheless complete;
+  reading "no properties" as "no shape" would discard a real schema, which is
+  the failure this path exists to prevent. An empty `required` and a
+  `description` do not change that; any other keyword, or a single property,
+  makes the entry a declaration. A description the document
+  wrote survives being filled in, the same carve-out `mergeResponses` makes.
+
+  The carve-out applies to `schemas` alone. A parameter carries `name` and `in`
+  rather than `properties`, so a schema-shaped emptiness test reads every one of
+  them as a placeholder and would let a contributor overwrite one the consumer
+  wrote — the precedence failure inverted, arriving through the fix for the
+  other one.
+
+  This package's own catalogue, under `openapi.includeCoreSchemas`, is placed by
+  the same rule and before any library. A placeholder under a catalogue name is
+  filled with the package's definition, so a library offering that name meets a
+  declaration and is reported rather than outranking the package.
+
+- **`fastify` and `@nestjs/platform-fastify` devDependency floors raised to
+  `^5.12.5` and `^11.2.4`.** Shipped in the tarball's manifest only; `dist/` is
+  unchanged by them.
+
+## [1.6.0] - 2026-08-29
+
+A readiness check that fails without rejecting left no record an operator would
+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
@@ -875,4 +1085,6 @@ have regressed from. They are kept because the reasoning is worth having.
 [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
 [1.5.3]: https://github.com/bymaxone/nest-core/compare/v1.5.2...v1.5.3
-[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.5.3...HEAD
+[1.6.0]: https://github.com/bymaxone/nest-core/compare/v1.5.3...v1.6.0
+[1.6.1]: https://github.com/bymaxone/nest-core/compare/v1.6.0...v1.6.1
+[Unreleased]: https://github.com/bymaxone/nest-core/compare/v1.6.1...HEAD

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
 
@@ -757,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
@@ -900,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
@@ -1079,10 +1163,35 @@ can emit it once and never branch:
 
 | Result                                     | Meaning                                                 |
 | ------------------------------------------ | ------------------------------------------------------- |
-| `{ mounted: true, path }`                  | The UI and the document are served at `path`.           |
+| `{ mounted: true, path, discarded }`       | The UI and the document are served at `path`.           |
 | `{ mounted: false, reason: 'disabled' }`   | `openapi.enabled` is off.                               |
 | `{ mounted: false, reason: 'production' }` | The runtime is production. Nothing was built or served. |
 
+`discarded` lists every component entry a library contributed that the served
+document already defined with a shape of its own — a `DiscardedComponent` per
+entry, naming the contributor, the member and the name. It is empty when every
+contribution was placed, and the boot log reports the same entries.
+
+A collision is not an error and does not stop the boot: the merge prefers
+whatever holds the name already. That is usually your own declaration, and you
+authored it on purpose — but it may also be a core schema this package
+contributes under `openapi.includeCoreSchemas`, or an earlier contributor's
+entry, since contributors merge in class-name order. The report names what was
+dropped and by whom, not who owns the definition that won, so read the document
+before deciding what to remove.
+
+It is reported because it is otherwise unobservable from either side: the
+contributing library cannot tell its entry lost, the application cannot tell one
+was offered, and the served document looks the same either way.
+
+A schema present only as `{"type":"object","properties":{}}` is **not** a
+declaration for this purpose. `@nestjs/swagger` emits exactly that for every DTO
+in a package built without its plugin, so such a name is filled from the
+contribution rather than preferred over it, and does not appear in `discarded`.
+An empty `required: []` and a `description` do not change that; anything else
+does. `{"type":"object"}` and `{}` are deliberate declarations — "any object" and
+"any value" — and are kept.
+
 ### Production is a closed door
 
 `NODE_ENV` decides, and the decision is fail-closed: only `development` and
@@ -1636,7 +1745,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.                                                     |
@@ -1667,6 +1777,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.                 |
 
@@ -1685,6 +1798,7 @@ in the sections above.
 | -------------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------ |
 | `applyBymaxOpenApi`                                                                    | function            | Builds and mounts the document; call it before `app.listen()`.                 |
 | `OpenApiMountOutcome`                                                                  | type                | What the helper did: mounted at a path, or skipped with a reason.              |
+| `DiscardedComponent`                                                                   | type                | A contributed component entry the document already declared.                   |
 | `OpenApiSkipReason`                                                                    | type                | Why it was skipped: `'disabled'` or `'production'`.                            |
 | `BymaxOpenApiContributor`, `BYMAX_OPENAPI_CONTRIBUTOR_METADATA`                        | decorator, constant | Marks a provider as describing its own routes, and the metadata key behind it. |
 | `IOpenApiContributor`, `OpenApiFragment`, `OpenApiFragmentObject`, `OpenApiHandlerKey` | types               | The contributor contract and the shape of what it returns.                     |

package/dist/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

package/dist/health.transition-B_IgXJTz.d.cts

@@ -0,0 +1,119 @@
+/**
+ * @fileoverview The readiness transition contract: a sink that receives one
+ * event each time a check changes state, and the cause that says why.
+ *
+ * This exists because a readiness failure can otherwise leave no record an
+ * operator will ever read. There are three ways for a check to be down, and the
+ * aggregator is the only place that can tell them apart: the indicator rejected,
+ * the indicator reported `down` on purpose, or the aggregator gave up waiting.
+ * The third is knowledge that exists nowhere else — an indicator the aggregator
+ * abandoned is never told, so it cannot report anything — and it is the shape a
+ * hung dependency takes. A database under load, a network partition and a paused
+ * container all hang; a refusal comes back immediately.
+ *
+ * Two decisions elsewhere combine to make that silence total in a typical
+ * deployment, and each is right on its own. Probe paths are excluded from the
+ * HTTP log surface, because probes are the highest-volume request a backend
+ * serves. And a well-written indicator returns `{ status: 'down' }` rather than
+ * throwing, because readiness is usually unauthenticated and a driver's error
+ * carries hosts, ports and sometimes credentials — which is exactly the row this
+ * package's own contract steers implementations toward.
+ *
+ * **Transitions, not outcomes.** The sink is called once per *change* of state
+ * per check name, never once per probe. That rule lives in the aggregator rather
+ * than in the sink deliberately: a readiness check runs every few seconds, so a
+ * line per failure turns one outage into thousands of identical records that
+ * bury the one carrying the cause. Leaving the de-duplication to each consumer
+ * would mean every backend re-deriving the same rule, and re-deriving it subtly
+ * differently. A sink that never sees raw outcomes cannot get it wrong.
+ * @layer Contract
+ */
+/**
+ * Why a check is down, as only the aggregator can distinguish it.
+ *
+ * A discriminated union rather than a string, so a consumer switches
+ * exhaustively and the compiler reports the arm it has not handled when a future
+ * version adds one. "The dependency answered that it is down" and "the
+ * dependency accepted the work and never answered" are different outages calling
+ * for different responses, and the readiness body cannot tell them apart because
+ * it carries only `up` or `down`.
+ */
+type HealthTransitionCause = {
+    /** The indicator rejected, or threw synchronously. */
+    readonly kind: 'rejected';
+    /**
+     * The rejection's top-level message, truncated to 300 characters. Never
+     * the raw error, its stack, or any nested cause.
+     *
+     * This reaches the sink whether or not `health.exposeIndicatorErrors` is
+     * set: that option governs what is written into the HTTP response, which
+     * is typically unauthenticated, while a sink is application-side code at
+     * the same trust level as the logger. An indicator usually does not author
+     * this text — it lets a driver's error propagate — so treat it as
+     * potentially carrying hosts and ports, and send it where access is
+     * already controlled.
+     */
+    readonly message: string;
+} | {
+    /** The indicator answered, and reported its dependency unhealthy. */
+    readonly kind: 'reported-down';
+} | {
+    /** The aggregator gave up waiting for the indicator. */
+    readonly kind: 'timed-out';
+    /** The bound that elapsed, from `health.indicatorTimeoutMs`. */
+    readonly timeoutMs: number;
+};
+/**
+ * One change of state for one check.
+ *
+ * A discriminated union on `isUp` rather than an object with an optional cause,
+ * so the compiler guarantees that a transition to `down` carries one and that a
+ * transition to `up` does not — a recovery has no cause to describe.
+ */
+type HealthTransition = {
+    /** The check's name, as {@link IHealthIndicator.name} declares it. */
+    readonly name: string;
+    /** The dependency is reachable again. */
+    readonly isUp: true;
+} | {
+    /** The check's name, as {@link IHealthIndicator.name} declares it. */
+    readonly name: string;
+    /** The dependency is not reachable. */
+    readonly isUp: false;
+    /** Why, as far as the aggregator can tell. */
+    readonly cause: HealthTransitionCause;
+};
+/**
+ * Receives one event per change of readiness state, per check.
+ *
+ * Bind an implementation under `BYMAX_HEALTH_TRANSITION_SINK` from a module of
+ * your own marked `@Global()`. Nothing is bound by default, and with no sink the
+ * aggregator writes its own transition lines to Nest's logger, so a readiness
+ * failure is never silent.
+ *
+ * Binding a sink stands that line down. Both destinations are usually the same
+ * logger in a consuming application, so keeping it would put two records of one
+ * transition side by side — 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.
+ *
+ * Called synchronously from the readiness path, so an implementation must be
+ * cheap and must not block: hand the event to a logger and return. A throw is
+ * caught and reported by the aggregator rather than failing the probe — a
+ * readiness endpoint that answers `500` because its *logging* broke would take a
+ * healthy deployment out of rotation — but do not rely on that as flow control.
+ *
+ * Takes a single object, matching `ITimingSink.record`, so a later field is an
+ * additive change rather than a new positional parameter.
+ */
+interface IHealthTransitionSink {
+    /**
+     * Record one change of readiness state.
+     *
+     * @param transition - The check that changed, its new state, and the cause
+     *   when it went down.
+     */
+    record(transition: HealthTransition): void;
+}
+
+export type { HealthTransition as H, IHealthTransitionSink as I, HealthTransitionCause as a };