@bymax-one/nest-core 1.5.3 → 1.6.0

package/CHANGELOG.md

@@ -11,6 +11,133 @@ 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
@@ -875,4 +1002,5 @@ 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
+[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
 
@@ -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
@@ -1636,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.                                                     |
@@ -1667,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

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 };

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

@@ -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 };