@fluojs/terminus 1.0.4 → 1.1.0

package/README.ko.md

@@ -14,6 +14,7 @@ fluo 애플리케이션을 위한 헬스 인디케이터(Health Indicator) 툴
   - [DI 기반 인디케이터](#di-기반-인디케이터)
   - [실행 가드레일](#실행-가드레일)
   - [실패 시맨틱](#실패-시맨틱)
+- [NestJS 마이그레이션 경계](#nestjs-마이그레이션-경계)
 - [공개 API 개요](#공개-api-개요)
 - [관련 패키지](#관련-패키지)
 - [예제 소스](#예제-소스)
@@ -24,10 +25,12 @@ fluo 애플리케이션을 위한 헬스 인디케이터(Health Indicator) 툴
 pnpm add @fluojs/terminus
 ```
 
-Redis indicator subpath를 사용할 때만 선택적 peer를 설치하세요.
+사용하는 indicator provider seam에 필요한 선택적 peer만 설치하세요.
 
 ```bash
 pnpm add @fluojs/redis ioredis
+pnpm add @fluojs/prisma @prisma/client
+pnpm add @fluojs/drizzle drizzle-orm
 ```
 
 ## 사용 시점
@@ -100,12 +103,16 @@ TerminusModule.forRoot({
 
 Drizzle의 경우 `createDrizzleHealthIndicatorProvider()`는 `@fluojs/drizzle`이 노출하는 lifecycle-aware `DrizzleDatabase` wrapper를 우선 사용합니다. Drizzle이 종료 중이거나 중지되었거나 `DrizzleDatabase.createPlatformStatusSnapshot()` 기준으로 준비되지 않은 상태이면 SQL probe를 실행하기 전에 해당 indicator를 `down`으로 보고합니다. legacy raw `DRIZZLE_DATABASE` handle만 등록된 경우에는 기존 lightweight SQL probe 동작을 유지합니다.
 
+Prisma의 경우 `createPrismaHealthIndicatorProvider()`는 `@fluojs/prisma`가 노출하는 lifecycle-aware `PrismaService` / `PrismaServiceFacade` token을 우선 사용하고, probe 전에 `createPlatformStatusSnapshot()`을 확인한 뒤 `current()`를 호출해 ambient transaction/lifecycle seam이 health probe에 보이도록 합니다. 기본 Prisma registration을 대상으로 하려면 `name`을 생략하고, `PrismaModule.forRoot({ name })`으로 등록한 named registration을 대상으로 하려면 `name`을 전달하세요. 수동 provider graph에서는 명시적인 `serviceToken` / `clientToken` 값을 전달할 수 있습니다. raw Prisma client token만 등록된 경우에는 root package에서 optional Prisma peer를 import하지 않으면서 기존 lightweight query probe 동작을 유지합니다.
+
 Provider factory는 반복 등록할 수 있습니다. 각 인스턴스가 서로 다른 indicator key나 dependency option을 사용한다면 같은 factory가 만든 provider 여러 개를 하나의 `indicatorProviders` 배열에 등록할 수 있으며, Terminus는 나중에 등록된 같은 타입 provider가 앞선 provider를 덮어쓰지 않도록 각 provider 인스턴스를 별도 DI token으로 보관합니다.
 
 ### 실행 가드레일
 
 커스텀 인디케이터가 멈추거나 느린 하위 서비스에 의존할 수 있다면 `execution.indicatorTimeoutMs`를 사용하세요. probe가 설정된 시간을 넘기면 Terminus는 무기한 대기하지 않고 해당 인디케이터를 `down`으로 표시합니다.
 
+Terminus는 각 `TerminusHealthService` / application container 안에서 같은 indicator instance에 대한 check도 직렬화합니다. Timeout된 probe나 느린 probe가 아직 실행 중일 때 같은 container의 다른 `/health` 또는 `/ready` 요청이 들어오면, Terminus는 같은 downstream에 겹치는 probe를 새로 시작하지 않고 해당 indicator를 새 요청에서 `down`으로 보고합니다. 테스트나 multi-app process가 같은 indicator object를 재사용하더라도 별도 application container는 독립적인 in-flight state를 유지합니다. Built-in HTTP indicator는 자체 timeout이 만료되면 `fetch` 요청을 abort하지만, 다른 driver와 custom callback은 cancellation을 노출하지 않을 수 있으므로 원래 promise가 settle될 때까지 overlap을 막는 방식으로 보호합니다.
+
 ```typescript
 TerminusModule.forRoot({
   execution: {
@@ -121,7 +128,7 @@ TerminusModule.forRoot({
 
 ### 실패 시맨틱
 
-인디케이터가 실패하면 `HealthCheckError`를 던집니다. `TerminusHealthService`는 이 실패들을 모아 보고서를 작성합니다.
+인디케이터가 `down` 결과를 반환하거나 `HealthCheckError`를 던지면, `TerminusHealthService`는 이 실패들을 모아 보고서를 작성합니다.
 
 - 하나 이상의 인디케이터가 실패하면 `/health`는 HTTP `503`을 반환합니다.
 - 등록된 indicator가 실패하거나, custom readiness check가 `false`를 반환하거나, runtime shutdown이 시작되었거나, platform readiness가 `ready`가 아닌 경우 `/ready`는 HTTP `503`을 반환합니다. Platform `critical` metadata는 diagnostics에 보존되지만 HTTP readiness endpoint 자체는 binary ready/unavailable gate이며 warning severity bucket을 노출하지 않습니다.
@@ -130,11 +137,20 @@ TerminusModule.forRoot({
 - 지원하지 않는 status, 빈 결과, 객체가 아닌 인디케이터 결과는 조용히 버려지지 않고 `down` 진단으로 보고됩니다.
 - Blank indicator result key는 healthy entry로 기여하지 않고 `down` 진단으로 보고됩니다.
 - 같은 실행에서 이미 보고된 key를 다른 인디케이터가 다시 사용하면, Terminus는 먼저 기록된 entry를 유지하고 데이터를 조용히 덮어쓰는 대신 결정적인 `*-duplicate-key-error` contributor를 추가합니다.
-- 플랫폼 health/readiness 실패는 `/health` 응답에서 결정적인 `fluo-platform-health`, `fluo-platform-readiness` contributor로 노출됩니다.
+- 플랫폼 health/readiness 실패는 `/health` 응답에서 결정적인 `fluo-platform-health`, `fluo-platform-readiness` contributor로 노출됩니다. 이 key들은 platform diagnostic용으로 예약되어 있으며, platform failure 중 user indicator가 같은 key를 반환하면 Terminus는 platform payload를 예약 key 아래에 유지하고 runtime state를 떨어뜨리지 않도록 결정적인 `*-user-key-collision` diagnostic을 추가합니다.
 - Runtime diagnostics가 있으면 `/health` response에 platform health/readiness detail을 담은 `platform` block이 포함될 수 있습니다.
+- DI provider로 생성한 Prisma indicator는 query보다 먼저 `@fluojs/prisma` service lifecycle readiness/health state를 반영하므로, raw client handle이 아직 호출 가능하더라도 종료 중이거나 중지되었거나 아직 연결되지 않은 통합은 `/health`와 `/ready`를 unavailable로 표시합니다.
 - DI provider로 생성한 Drizzle indicator는 SQL probe보다 먼저 Drizzle lifecycle readiness/health state를 반영하므로, underlying driver가 raw ping을 아직 받을 수 있어도 종료 중이거나 중지된 통합은 `/health`와 `/ready`를 unavailable로 표시합니다.
 - Redis subpath로 생성한 Redis indicator는 `PING` 전에 `@fluojs/redis` client lifecycle state를 반영하므로, 종료 중이거나 연결이 끊긴 Redis client는 command 실행 전에도 `/health`와 `/ready`를 unavailable로 표시합니다.
 
+## NestJS 마이그레이션 경계
+
+`@nestjs/terminus`에서 마이그레이션할 때는 `TerminusModule.forRoot(...)`를 fluo의 기본 API로 취급하세요. fluo는 `HealthCheckService.check([...])`를 호출하는 controller-level `@HealthCheck()` 메서드를 주요 애플리케이션 계약으로 모델링하지 않습니다. 테스트나 커스텀 애플리케이션 코드에서 `TerminusHealthService.check()`를 직접 호출할 수는 있지만, 프로덕션 엔드포인트 등록은 indicator와 readiness hook을 module option에 두어 runtime `/health`와 `/ready` 경로가 platform diagnostics를 일관되게 포함하도록 해야 합니다.
+
+Terminus는 별도의 process-only liveness route도 기본으로 만들지 않습니다. 기본 route model은 집계 헬스를 위한 `GET /health`, readiness를 위한 `GET /ready`입니다. 배포 환경에서 좁은 의미의 process liveness probe가 필요하다면, Terminus가 NestJS-style 추가 route를 만들어 준다고 가정하지 말고 애플리케이션 또는 배포 계층에서 해당 probe를 정의하세요.
+
+Runtime-specific indicator는 subpath별로 분리되어 있습니다. Node.js memory 및 disk check에는 `@fluojs/terminus/node`를 사용하고, Redis check에는 `@fluojs/terminus/redis`를 사용하세요. Prisma와 Drizzle provider helper는 token-only DI seam을 해석하므로 해당 선택적 peer가 없어도 root package import는 안전하게 유지되며, Node disk filesystem access도 lazy하게 유지되어 애플리케이션이 runtime-specific probe에 명시적으로 opt in합니다.
+
 ## 공개 API 개요
 
 ### `TerminusModule`
@@ -153,7 +169,7 @@ TerminusModule.forRoot({
 ### 직접 helper와 token
 
 - `runHealthCheck(...)`, `assertHealthCheck(...)`: 직접 aggregation/testing helper입니다.
-- `TERMINUS_HEALTH_INDICATORS`, `TERMINUS_INDICATOR_PROVIDER_TOKENS`: 등록된 indicator와 provider token을 위한 DI token입니다.
+- `TERMINUS_HEALTH_INDICATORS`, `TERMINUS_INDICATOR_PROVIDER_TOKENS`: 등록된 indicator와 provider token을 위한 DI token입니다. `TerminusModule.forRoot(...)`는 두 token을 모두 export하므로 downstream module은 Terminus 내부를 재구성하지 않고도 구성된 indicator/provider-token set을 확인할 수 있습니다.
 - Built-in indicator는 `create*HealthIndicator()` 및 `create*HealthIndicatorProvider()` helper도 노출합니다. Provider helper는 `indicatorProviders`를 위한 의도적인 DI composition 예외이며, 애플리케이션 등록은 계속 `TerminusModule.forRoot(...)`를 사용해야 합니다.
 
 ### `@fluojs/terminus/redis`

package/README.md

@@ -14,6 +14,7 @@ Health indicator toolkit for fluo applications. `@fluojs/terminus` layers on top
   - [DI-Backed Indicators](#di-backed-indicators)
   - [Execution Guardrails](#execution-guardrails)
   - [Failure Semantics](#failure-semantics)
+- [NestJS Migration Boundaries](#nestjs-migration-boundaries)
 - [Public API Overview](#public-api-overview)
 - [Related Packages](#related-packages)
 - [Example Sources](#example-sources)
@@ -24,10 +25,12 @@ Health indicator toolkit for fluo applications. `@fluojs/terminus` layers on top
 pnpm add @fluojs/terminus
 ```
 
-Install the optional peer only when you use the Redis indicator subpath:
+Install optional peers only for the indicator provider seams you enable:
 
 ```bash
 pnpm add @fluojs/redis ioredis
+pnpm add @fluojs/prisma @prisma/client
+pnpm add @fluojs/drizzle drizzle-orm
 ```
 
 ## When to Use
@@ -100,12 +103,16 @@ Redis indicators created through `@fluojs/terminus/redis` are lifecycle-aware wh
 
 For Drizzle, `createDrizzleHealthIndicatorProvider()` prefers the lifecycle-aware `DrizzleDatabase` wrapper exported by `@fluojs/drizzle`. The indicator reports `down` before probing SQL whenever Drizzle is shutting down, stopped, or otherwise not ready according to `DrizzleDatabase.createPlatformStatusSnapshot()`. If only the legacy raw `DRIZZLE_DATABASE` handle is registered, the provider keeps the previous lightweight SQL probe behavior.
 
+For Prisma, `createPrismaHealthIndicatorProvider()` prefers the lifecycle-aware `PrismaService` / `PrismaServiceFacade` token exported by `@fluojs/prisma`, checks `createPlatformStatusSnapshot()` before probing, and then calls `current()` so ambient transaction/lifecycle seams stay visible to the health probe. Omit `name` to target the default Prisma registration, pass `name` to target `PrismaModule.forRoot({ name })`, or pass explicit `serviceToken` / `clientToken` values for manual provider graphs. If only a raw Prisma client token is registered, the provider keeps the previous lightweight query probe behavior without importing the optional Prisma peer from the root package.
+
 Provider factories are repeatable. You may register multiple providers created by the same factory in one `indicatorProviders` array when each instance uses a distinct indicator key or dependency option; Terminus keeps every provider instance under its own DI token instead of letting later same-type providers overwrite earlier ones.
 
 ### Execution Guardrails
 
 Use `execution.indicatorTimeoutMs` when custom indicators might hang or depend on slow downstreams. When a probe exceeds the configured timeout, Terminus marks that indicator as `down` instead of waiting forever.
 
+Terminus also serializes checks per indicator instance inside each `TerminusHealthService` / application container. If a timed-out or otherwise slow probe is still running when another `/health` or `/ready` request arrives for the same container, Terminus reports that indicator as `down` for the new request instead of starting an overlapping probe against the same downstream. Separate application containers keep independent in-flight state even when tests or multi-app processes reuse the same indicator object. Built-in HTTP indicators abort their `fetch` request when their own timeout expires; other drivers and custom callbacks may not expose cancellation, so they are protected from overlap until the original promise settles.
+
 ```typescript
 TerminusModule.forRoot({
   execution: {
@@ -121,7 +128,7 @@ Use `path` to mount the health endpoints under a custom path, and `readinessChec
 
 ### Failure Semantics
 
-When an indicator fails, it throws a `HealthCheckError`. The `TerminusHealthService` aggregates these failures into a report:
+When an indicator returns a `down` result or throws a `HealthCheckError`, the `TerminusHealthService` aggregates the failure into a report:
 
 - `/health` returns HTTP `503` if any indicator fails.
 - `/ready` returns HTTP `503` when registered indicators fail, a custom readiness check returns `false`, runtime shutdown has begun, or platform readiness is anything other than `ready`. Platform `critical` metadata is preserved in diagnostics, but the HTTP readiness endpoint itself is a binary ready/unavailable gate and does not expose warning severity buckets.
@@ -130,11 +137,20 @@ When an indicator fails, it throws a `HealthCheckError`. The `TerminusHealthServ
 - Unsupported, empty, or non-object indicator results are reported as `down` diagnostics instead of being silently discarded.
 - Blank indicator result keys are reported as `down` diagnostics instead of contributing healthy entries.
 - If an indicator reuses a key that was already reported earlier in the same run, Terminus keeps the first entry and adds a deterministic `*-duplicate-key-error` contributor instead of silently overwriting data.
-- Platform health/readiness failures are surfaced as deterministic `fluo-platform-health` and `fluo-platform-readiness` contributors in `/health` responses.
+- Platform health/readiness failures are surfaced as deterministic `fluo-platform-health` and `fluo-platform-readiness` contributors in `/health` responses. These keys are reserved for platform diagnostics; if a user indicator returns one of them during a platform failure, Terminus keeps the platform payload under the reserved key and adds a deterministic `*-user-key-collision` diagnostic instead of dropping runtime state.
 - `/health` responses may include a `platform` block with platform health/readiness details when runtime diagnostics are available.
+- Prisma indicators created through the DI provider map `@fluojs/prisma` service lifecycle readiness/health state before querying, so shutdown, stopped, or not-yet-connected integrations mark `/health` and `/ready` unavailable even when the raw client handle is still callable.
 - Drizzle indicators created through the DI provider map Drizzle lifecycle readiness/health state before SQL probing, so shutdown or stopped integrations mark `/health` and `/ready` as unavailable even if the underlying driver still accepts a raw ping.
 - Redis indicators created through the Redis subpath map `@fluojs/redis` client lifecycle state before `PING`, so shutdown or disconnected Redis clients mark `/health` and `/ready` as unavailable even before command execution.
 
+## NestJS Migration Boundaries
+
+When migrating from `@nestjs/terminus`, treat `TerminusModule.forRoot(...)` as the primary fluo API. fluo does not model controller-level `@HealthCheck()` methods that call `HealthCheckService.check([...])` as the main application contract. You can still call `TerminusHealthService.check()` directly from tests or custom application code, but production endpoint registration should keep indicators and readiness hooks in module options so the runtime `/health` and `/ready` routes include platform diagnostics consistently.
+
+Terminus also does not create a separate process-only liveness route by default. The default route model remains `GET /health` for aggregated health and `GET /ready` for readiness. If your deployment requires a narrow process liveness probe, define that probe at the application or deployment layer instead of assuming Terminus will add a NestJS-style extra route.
+
+Runtime-specific indicators are split by subpath. Use `@fluojs/terminus/node` for Node.js memory and disk checks, and use `@fluojs/terminus/redis` for Redis checks. Prisma and Drizzle provider helpers resolve token-only DI seams so the root package stays import-safe when those optional peers are absent, and Node disk filesystem access stays lazy so applications opt into runtime-specific probes explicitly.
+
 ## Public API Overview
 
 ### `TerminusModule`
@@ -153,7 +169,7 @@ When an indicator fails, it throws a `HealthCheckError`. The `TerminusHealthServ
 ### Direct helpers and tokens
 
 - `runHealthCheck(...)`, `assertHealthCheck(...)`: Direct aggregation/testing helpers.
-- `TERMINUS_HEALTH_INDICATORS`, `TERMINUS_INDICATOR_PROVIDER_TOKENS`: DI tokens for registered indicators and provider tokens.
+- `TERMINUS_HEALTH_INDICATORS`, `TERMINUS_INDICATOR_PROVIDER_TOKENS`: DI tokens for registered indicators and provider tokens. `TerminusModule.forRoot(...)` exports both tokens so downstream modules can inspect the composed indicator/provider-token set without rebuilding Terminus internals.
 - Built-in indicators also expose `create*HealthIndicator()` and `create*HealthIndicatorProvider()` helpers. Provider helpers are intentional DI-composition exceptions for `indicatorProviders`, while application registration should still go through `TerminusModule.forRoot(...)`.
 
 ### `@fluojs/terminus/redis`

package/dist/health-check.d.ts

@@ -2,6 +2,11 @@ import type { HealthCheckExecutionOptions, HealthCheckReport, HealthIndicator }
 /**
  * Run every registered health indicator and aggregate their results.
  *
+ * @remarks
+ * Direct helper calls receive an isolated execution scope. Use `TerminusHealthService`
+ * when repeated checks should serialize overlapping probes for a container-owned
+ * indicator set.
+ *
  * @param indicators Indicator instances to execute for the current health probe.
  * @param executionOptions Optional timeout guardrails for indicator execution.
  * @returns A structured report containing `info`, `error`, and full `details` maps.
@@ -20,6 +25,7 @@ export declare function assertHealthCheck(report: HealthCheckReport, message?: s
 export declare class TerminusHealthService {
     private readonly indicators;
     private readonly executionOptions;
+    private readonly runningIndicatorChecks;
     constructor(indicators: readonly HealthIndicator[], executionOptions?: HealthCheckExecutionOptions);
     /**
      * Execute all registered indicators once.

package/dist/health-check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"health-check.d.ts","sourceRoot":"","sources":["../src/health-check.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,2BAA2B,EAC3B,iBAAiB,EACjB,eAAe,EAGhB,MAAM,YAAY,CAAC;AAyQpB;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,gBAAgB,GAAE,2BAAgC,GACjD,OAAO,CAAC,iBAAiB,CAAC,CAoB5B;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,EAAE,OAAO,SAAyB,GAAG,iBAAiB,CAMhH;AAED,0FAA0F;AAC1F,qBAAa,qBAAqB;IAE9B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;gBADhB,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,gBAAgB,GAAE,2BAAgC;IAGrE;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAIzC;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;CAGpC"}
+{"version":3,"file":"health-check.d.ts","sourceRoot":"","sources":["../src/health-check.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,2BAA2B,EAC3B,iBAAiB,EACjB,eAAe,EAGhB,MAAM,YAAY,CAAC;AAsVpB;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,gBAAgB,GAAE,2BAAgC,GACjD,OAAO,CAAC,iBAAiB,CAAC,CAE5B;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,EAAE,OAAO,SAAyB,GAAG,iBAAiB,CAMhH;AAED,0FAA0F;AAC1F,qBAAa,qBAAqB;IAI9B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IAJnC,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAyC;gBAG7D,UAAU,EAAE,SAAS,eAAe,EAAE,EACtC,gBAAgB,GAAE,2BAAgC;IAGrE;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAIzC;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;CAGpC"}

package/dist/health-check.js

@@ -8,6 +8,32 @@ function normalizeIndicatorTimeoutMs(value) {
 function createTimeoutMessage(timeoutMs) {
   return `Health indicator timed out after ${String(timeoutMs)}ms.`;
 }
+function createInFlightResult(key) {
+  return {
+    [key]: {
+      message: 'A previous health indicator probe is still running; Terminus will not start an overlapping probe for the same indicator instance.',
+      status: 'down'
+    }
+  };
+}
+function startSerializedIndicatorCheck(indicator, key, runningIndicatorChecks) {
+  const runningCheck = runningIndicatorChecks.get(indicator);
+  if (runningCheck) {
+    return undefined;
+  }
+  const check = Promise.resolve().then(() => indicator.check(key));
+  runningIndicatorChecks.set(indicator, check);
+  check.then(() => {
+    if (runningIndicatorChecks.get(indicator) === check) {
+      runningIndicatorChecks.delete(indicator);
+    }
+  }, () => {
+    if (runningIndicatorChecks.get(indicator) === check) {
+      runningIndicatorChecks.delete(indicator);
+    }
+  });
+  return check;
+}
 async function withTimeout(promise, timeoutMs) {
   let timer;
   try {
@@ -134,11 +160,18 @@ function createDuplicateKeyFailure(indicatorKey, duplicateKeys, seenKeys) {
     status: 'down'
   }];
 }
-async function runIndicator(indicator, index, executionOptions) {
+async function runIndicator(indicator, index, executionOptions, runningIndicatorChecks) {
   const key = inferIndicatorKey(indicator, index);
   const indicatorTimeoutMs = normalizeIndicatorTimeoutMs(executionOptions.indicatorTimeoutMs);
+  const runningCheck = startSerializedIndicatorCheck(indicator, key, runningIndicatorChecks);
+  if (!runningCheck) {
+    return {
+      entries: Object.entries(createInFlightResult(key)),
+      indicatorKey: key
+    };
+  }
   try {
-    const result = indicatorTimeoutMs === undefined ? await indicator.check(key) : await withTimeout(indicator.check(key), indicatorTimeoutMs);
+    const result = indicatorTimeoutMs === undefined ? await runningCheck : await withTimeout(runningCheck, indicatorTimeoutMs);
     return {
       entries: normalizeIndicatorResult(key, result),
       indicatorKey: key
@@ -178,16 +211,8 @@ function aggregateIndicatorEntries(checks) {
   }
   return aggregatedEntries;
 }
-
-/**
- * Run every registered health indicator and aggregate their results.
- *
- * @param indicators Indicator instances to execute for the current health probe.
- * @param executionOptions Optional timeout guardrails for indicator execution.
- * @returns A structured report containing `info`, `error`, and full `details` maps.
- */
-export async function runHealthCheck(indicators, executionOptions = {}) {
-  const checks = aggregateIndicatorEntries(await Promise.all(indicators.map((indicator, index) => runIndicator(indicator, index, executionOptions))));
+async function executeHealthCheck(indicators, executionOptions = {}, runningIndicatorChecks) {
+  const checks = aggregateIndicatorEntries(await Promise.all(indicators.map((indicator, index) => runIndicator(indicator, index, executionOptions, runningIndicatorChecks))));
   const details = Object.fromEntries(checks);
   const infoEntries = checks.filter(([, result]) => result.status === 'up');
   const errorEntries = checks.filter(([, result]) => result.status === 'down');
@@ -204,6 +229,22 @@ export async function runHealthCheck(indicators, executionOptions = {}) {
   };
 }
 
+/**
+ * Run every registered health indicator and aggregate their results.
+ *
+ * @remarks
+ * Direct helper calls receive an isolated execution scope. Use `TerminusHealthService`
+ * when repeated checks should serialize overlapping probes for a container-owned
+ * indicator set.
+ *
+ * @param indicators Indicator instances to execute for the current health probe.
+ * @param executionOptions Optional timeout guardrails for indicator execution.
+ * @returns A structured report containing `info`, `error`, and full `details` maps.
+ */
+export async function runHealthCheck(indicators, executionOptions = {}) {
+  return executeHealthCheck(indicators, executionOptions, new WeakMap());
+}
+
 /**
  * Assert that an aggregated health report is fully healthy.
  *
@@ -221,6 +262,7 @@ export function assertHealthCheck(report, message = 'Health check failed.') {
 
 /** Service facade that resolves and runs the health indicators registered in Terminus. */
 export class TerminusHealthService {
+  runningIndicatorChecks = new WeakMap();
   constructor(indicators, executionOptions = {}) {
     this.indicators = indicators;
     this.executionOptions = executionOptions;
@@ -232,7 +274,7 @@ export class TerminusHealthService {
    * @returns The aggregated health report for this check cycle.
    */
   async check() {
-    return runHealthCheck(this.indicators, this.executionOptions);
+    return executeHealthCheck(this.indicators, this.executionOptions, this.runningIndicatorChecks);
   }
 
   /**

package/dist/indicators/drizzle.js

@@ -1,5 +1,5 @@
 import { optional } from '@fluojs/di';
-import { createDownResult, createUpResult, resolveIndicatorKey, throwHealthCheckError, withIndicatorTimeout } from './utils.js';
+import { createDownResult, createUpResult, resolveIndicatorKey, resolveIndicatorTimeoutMs, throwHealthCheckError, withIndicatorTimeout } from './utils.js';
 const DRIZZLE_DATABASE = Symbol.for('fluo.drizzle.database');
 const DRIZZLE_HANDLE_PROVIDER = Symbol.for('fluo.drizzle.handle-provider');
 
@@ -85,8 +85,8 @@ export class DrizzleHealthIndicator {
   }
   async check(key) {
     const indicatorKey = resolveIndicatorKey('drizzle', this.options.key ?? key);
-    const timeoutMs = this.options.timeoutMs ?? DEFAULT_DRIZZLE_TIMEOUT_MS;
     try {
+      const timeoutMs = resolveIndicatorTimeoutMs(this.options.timeoutMs, DEFAULT_DRIZZLE_TIMEOUT_MS, indicatorKey);
       const snapshot = createDrizzleLifecycleSnapshot(this.options.handleProvider);
       const lifecycleDownResult = snapshot ? createDrizzleLifecycleDownResult(indicatorKey, snapshot) : undefined;
       if (lifecycleDownResult) {

package/dist/indicators/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/indicators/http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAI3C,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE1E,wDAAwD;AACxD,MAAM,WAAW,0BAA0B;IACzC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;CACb;AAoBD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,0BAA0B,GAAG,eAAe,CAE9F;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,OAAO,EAAE,0BAA0B,GAAG,QAAQ,CAO/F;AAED,6EAA6E;AAC7E,qBAAa,mBAAoB,YAAW,eAAe;IAG7C,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEJ,OAAO,EAAE,0BAA0B;IAI1D,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;CA6CzD"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/indicators/http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAI3C,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE1E,wDAAwD;AACxD,MAAM,WAAW,0BAA0B;IACzC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;CACb;AA8BD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,0BAA0B,GAAG,eAAe,CAE9F;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,OAAO,EAAE,0BAA0B,GAAG,QAAQ,CAO/F;AAED,6EAA6E;AAC7E,qBAAa,mBAAoB,YAAW,eAAe;IAG7C,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEJ,OAAO,EAAE,0BAA0B;IAI1D,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAmDzD"}

package/dist/indicators/http.js

@@ -1,4 +1,4 @@
-import { createDownResult, createUpResult, resolveIndicatorKey, throwHealthCheckError } from './utils.js';
+import { createDownResult, createUpResult, resolveIndicatorKey, resolveIndicatorTimeoutMs, throwHealthCheckError } from './utils.js';
 import { HealthCheckError } from '../errors.js';
 
 /** Options for probing one upstream HTTP dependency. */
@@ -16,6 +16,13 @@ function isExpectedStatus(status, expected) {
   }
   return status >= 200 && status < 300;
 }
+function cancelResponseBody(response) {
+  const body = response.body;
+  if (!body) {
+    return;
+  }
+  void body.cancel().catch(() => undefined);
+}
 
 /**
  * Create an HTTP-backed health indicator.
@@ -50,39 +57,45 @@ export class HttpHealthIndicator {
   }
   async check(key) {
     const indicatorKey = resolveIndicatorKey('http', this.options.key ?? key);
-    const timeoutMs = this.options.timeoutMs ?? DEFAULT_HTTP_TIMEOUT_MS;
     const method = this.options.method ?? 'GET';
-    const abortController = new AbortController();
-    const startedAt = Date.now();
-    const timeout = setTimeout(() => {
-      abortController.abort(new Error(`HTTP health check timed out after ${String(timeoutMs)}ms.`));
-    }, timeoutMs);
     try {
-      const response = await fetch(this.options.url, {
-        headers: this.options.headers,
-        method,
-        signal: abortController.signal
-      });
-      const responseTimeMs = Date.now() - startedAt;
-      if (!isExpectedStatus(response.status, this.options.expectedStatus)) {
-        throwHealthCheckError('HTTP health check failed.', createDownResult(indicatorKey, `Unexpected status code ${String(response.status)} from ${this.options.url}.`, {
-          responseTimeMs,
-          statusCode: response.status,
-          url: this.options.url
-        }));
+      const timeoutMs = resolveIndicatorTimeoutMs(this.options.timeoutMs, DEFAULT_HTTP_TIMEOUT_MS, indicatorKey);
+      const abortController = new AbortController();
+      const startedAt = Date.now();
+      const timeout = setTimeout(() => {
+        abortController.abort(new Error(`HTTP health check timed out after ${String(timeoutMs)}ms.`));
+      }, timeoutMs);
+      try {
+        const response = await fetch(this.options.url, {
+          headers: this.options.headers,
+          method,
+          signal: abortController.signal
+        });
+        const responseTimeMs = Date.now() - startedAt;
+        try {
+          if (!isExpectedStatus(response.status, this.options.expectedStatus)) {
+            throwHealthCheckError('HTTP health check failed.', createDownResult(indicatorKey, `Unexpected status code ${String(response.status)} from ${this.options.url}.`, {
+              responseTimeMs,
+              statusCode: response.status,
+              url: this.options.url
+            }));
+          }
+          return createUpResult(indicatorKey, {
+            responseTimeMs,
+            statusCode: response.status,
+            url: this.options.url
+          });
+        } finally {
+          cancelResponseBody(response);
+        }
+      } finally {
+        clearTimeout(timeout);
       }
-      return createUpResult(indicatorKey, {
-        responseTimeMs,
-        statusCode: response.status,
-        url: this.options.url
-      });
     } catch (error) {
       if (error instanceof HealthCheckError) {
         throw error;
       }
       throwHealthCheckError('HTTP health check failed.', createDownResult(indicatorKey, error instanceof Error ? error.message : `HTTP health check failed for ${this.options.url}.`));
-    } finally {
-      clearTimeout(timeout);
     }
   }
 }

package/dist/indicators/prisma.d.ts

@@ -1,4 +1,5 @@
-import type { Provider } from '@fluojs/di';
+import type { Token } from '@fluojs/core';
+import { type Provider } from '@fluojs/di';
 import type { HealthIndicator, HealthIndicatorResult } from '../types.js';
 interface PrismaClientLike {
     $executeRaw?: (...args: unknown[]) => Promise<unknown>;
@@ -6,28 +7,60 @@ interface PrismaClientLike {
     $queryRaw?: (...args: unknown[]) => Promise<unknown>;
     $queryRawUnsafe?: (query: string) => Promise<unknown>;
 }
+interface PrismaLifecycleSnapshotLike {
+    details?: Record<string, unknown>;
+    health: {
+        reason?: string;
+        status: 'healthy' | 'degraded' | 'unhealthy';
+    };
+    readiness: {
+        reason?: string;
+        status: 'ready' | 'not-ready';
+    };
+}
+interface PrismaServiceLike {
+    createPlatformStatusSnapshot?: () => PrismaLifecycleSnapshotLike;
+    current?: () => PrismaClientLike | unknown;
+}
 /** Options for probing Prisma-backed database connectivity. */
 export interface PrismaHealthIndicatorOptions {
+    /** Raw Prisma client to probe when no lifecycle-aware service facade is supplied. */
     client?: PrismaClientLike;
+    /** Explicit raw-client token to resolve when using `createPrismaHealthIndicatorProvider(...)`. */
+    clientToken?: Token;
+    /** Indicator result key override. Defaults to the key passed to `check(...)`, then `prisma`. */
     key?: string;
+    /** Named Prisma registration to resolve when using `createPrismaHealthIndicatorProvider(...)`. */
+    name?: string;
+    /** Custom ping callback for manual probes or tests. Lifecycle state is only mapped when `service` is available. */
     ping?: () => Promise<unknown> | unknown;
+    /** Lifecycle-aware Prisma service/facade handle, usually resolved from `getPrismaServiceToken(name)`. */
+    service?: PrismaServiceLike;
+    /** Explicit Prisma service token to resolve when using `createPrismaHealthIndicatorProvider(...)`. */
+    serviceToken?: Token;
+    /** Maximum time to wait for the ping operation. Defaults to `2_000` ms. */
     timeoutMs?: number;
 }
 /**
  * Create a Prisma health indicator.
  *
- * @param options Optional Prisma client, ping callback, timeout, and key override.
- * @returns A health indicator that executes a lightweight Prisma round trip.
+ * @param options Optional lifecycle-aware service facade, Prisma client, ping callback, timeout, and key override.
+ * @returns A health indicator that checks Prisma lifecycle state before executing a lightweight round trip.
  */
 export declare function createPrismaHealthIndicator(options?: PrismaHealthIndicatorOptions): HealthIndicator;
 /**
- * Create a Terminus indicator provider collection entry that resolves a Prisma client from DI.
+ * Create a Terminus indicator provider collection entry that resolves Prisma from DI.
+ *
+ * The provider prefers `getPrismaServiceToken(options.name)` so `@fluojs/prisma`
+ * lifecycle snapshots participate in health/readiness diagnostics. It falls back
+ * to the matching raw client token for compatibility with manual provider graphs.
+ * Explicit `serviceToken` and `clientToken` values override the name-derived tokens.
  *
- * @param options Optional timeout, key override, or custom ping callback.
+ * @param options Optional name hint, explicit tokens, timeout, key override, or custom ping callback.
  * @returns A factory provider with a unique internal DI token for `TerminusModule` indicatorProviders.
  */
-export declare function createPrismaHealthIndicatorProvider(options?: Omit<PrismaHealthIndicatorOptions, 'client'>): Provider;
-/** Health indicator that probes Prisma connectivity with a trivial query. */
+export declare function createPrismaHealthIndicatorProvider(options?: Omit<PrismaHealthIndicatorOptions, 'client' | 'service'>): Provider;
+/** Health indicator that maps Prisma lifecycle status and probes connectivity with a trivial query. */
 export declare class PrismaHealthIndicator implements HealthIndicator {
     private readonly options;
     readonly key: string | undefined;

package/dist/indicators/prisma.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prisma.d.ts","sourceRoot":"","sources":["../../src/indicators/prisma.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG3C,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAI1E,UAAU,gBAAgB;IACxB,WAAW,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACvD,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACxD,SAAS,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACrD,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACvD;AAED,+DAA+D;AAC/D,MAAM,WAAW,4BAA4B;IAC3C,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAuCD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,GAAE,4BAAiC,GAAG,eAAe,CAEvG;AAED;;;;;GAKG;AACH,wBAAgB,mCAAmC,CAAC,OAAO,GAAE,IAAI,CAAC,4BAA4B,EAAE,QAAQ,CAAM,GAAG,QAAQ,CAQxH;AAED,6EAA6E;AAC7E,qBAAa,qBAAsB,YAAW,eAAe;IAG/C,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEJ,OAAO,GAAE,4BAAiC;IAIjE,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAczD"}
+{"version":3,"file":"prisma.d.ts","sourceRoot":"","sources":["../../src/indicators/prisma.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGrD,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAK1E,UAAU,gBAAgB;IACxB,WAAW,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACvD,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACxD,SAAS,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACrD,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACvD;AAED,UAAU,2BAA2B;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,MAAM,EAAE;QACN,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;KAC9C,CAAC;IACF,SAAS,EAAE;QACT,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,OAAO,GAAG,WAAW,CAAC;KAC/B,CAAC;CACH;AAED,UAAU,iBAAiB;IACzB,4BAA4B,CAAC,EAAE,MAAM,2BAA2B,CAAC;IACjE,OAAO,CAAC,EAAE,MAAM,gBAAgB,GAAG,OAAO,CAAC;CAC5C;AAED,+DAA+D;AAC/D,MAAM,WAAW,4BAA4B;IAC3C,qFAAqF;IACrF,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,kGAAkG;IAClG,WAAW,CAAC,EAAE,KAAK,CAAC;IACpB,gGAAgG;IAChG,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kGAAkG;IAClG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mHAAmH;IACnH,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACxC,yGAAyG;IACzG,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,sGAAsG;IACtG,YAAY,CAAC,EAAE,KAAK,CAAC;IACrB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA+HD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,GAAE,4BAAiC,GAAG,eAAe,CAEvG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mCAAmC,CACjD,OAAO,GAAE,IAAI,CAAC,4BAA4B,EAAE,QAAQ,GAAG,SAAS,CAAM,GACrE,QAAQ,CA8BV;AAED,uGAAuG;AACvG,qBAAa,qBAAsB,YAAW,eAAe;IAG/C,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEJ,OAAO,GAAE,4BAAiC;IAIjE,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;CA2BzD"}

package/dist/indicators/prisma.js

@@ -1,5 +1,7 @@
-import { createDownResult, createUpResult, resolveIndicatorKey, throwHealthCheckError, withIndicatorTimeout } from './utils.js';
+import { optional } from '@fluojs/di';
+import { createDownResult, createUpResult, resolveIndicatorKey, resolveIndicatorTimeoutMs, throwHealthCheckError, withIndicatorTimeout } from './utils.js';
 const PRISMA_CLIENT = Symbol.for('fluo.prisma.client');
+const PRISMA_SERVICE = Symbol.for('fluo.prisma.service');
 
 /** Options for probing Prisma-backed database connectivity. */
 
@@ -9,7 +11,7 @@ async function runPrismaPing(options) {
     await options.ping();
     return;
   }
-  const client = options.client;
+  const client = resolveCurrentPrismaClient(options.service) ?? options.client;
   if (!client) {
     throw new Error('Prisma indicator requires either a client or ping callback.');
   }
@@ -31,36 +33,108 @@ async function runPrismaPing(options) {
   }
   throw new Error('Prisma indicator requires a client with query/execute capabilities or a ping callback.');
 }
+function normalizePrismaRegistrationName(name) {
+  if (name === undefined) {
+    return undefined;
+  }
+  const normalizedName = name.trim();
+  if (normalizedName.length === 0) {
+    throw new Error('Prisma health indicator registration name must be a non-empty string when provided.');
+  }
+  return normalizedName;
+}
+function getPrismaClientToken(name) {
+  const normalizedName = normalizePrismaRegistrationName(name);
+  return normalizedName === undefined ? PRISMA_CLIENT : Symbol.for(`fluo.prisma.client:${normalizedName}`);
+}
+function getPrismaServiceToken(name) {
+  const normalizedName = normalizePrismaRegistrationName(name);
+  return normalizedName === undefined ? PRISMA_SERVICE : Symbol.for(`fluo.prisma.service:${normalizedName}`);
+}
+function resolveCurrentPrismaClient(service) {
+  if (!service || typeof service.current !== 'function') {
+    return undefined;
+  }
+  return service.current();
+}
+function createPrismaLifecycleSnapshot(service) {
+  if (!service || typeof service.createPlatformStatusSnapshot !== 'function') {
+    return undefined;
+  }
+  return service.createPlatformStatusSnapshot();
+}
+function createPrismaLifecycleDownResult(indicatorKey, snapshot) {
+  const healthStatus = snapshot.health.status;
+  const readinessStatus = snapshot.readiness.status;
+  if (healthStatus === 'healthy' && readinessStatus === 'ready') {
+    return undefined;
+  }
+  const message = snapshot.readiness.reason ?? snapshot.health.reason ?? `Prisma lifecycle reported health=${healthStatus} readiness=${readinessStatus}.`;
+  return createDownResult(indicatorKey, message, {
+    details: snapshot.details,
+    healthStatus,
+    readinessStatus
+  });
+}
+function createPrismaLifecycleUpDetails(snapshot) {
+  if (!snapshot) {
+    return {};
+  }
+  return {
+    details: snapshot.details,
+    healthStatus: snapshot.health.status,
+    readinessStatus: snapshot.readiness.status
+  };
+}
+function toPrismaService(value) {
+  return typeof value === 'object' && value !== null ? value : undefined;
+}
 
 /**
  * Create a Prisma health indicator.
  *
- * @param options Optional Prisma client, ping callback, timeout, and key override.
- * @returns A health indicator that executes a lightweight Prisma round trip.
+ * @param options Optional lifecycle-aware service facade, Prisma client, ping callback, timeout, and key override.
+ * @returns A health indicator that checks Prisma lifecycle state before executing a lightweight round trip.
  */
 export function createPrismaHealthIndicator(options = {}) {
   return new PrismaHealthIndicator(options);
 }
 
 /**
- * Create a Terminus indicator provider collection entry that resolves a Prisma client from DI.
+ * Create a Terminus indicator provider collection entry that resolves Prisma from DI.
  *
- * @param options Optional timeout, key override, or custom ping callback.
+ * The provider prefers `getPrismaServiceToken(options.name)` so `@fluojs/prisma`
+ * lifecycle snapshots participate in health/readiness diagnostics. It falls back
+ * to the matching raw client token for compatibility with manual provider graphs.
+ * Explicit `serviceToken` and `clientToken` values override the name-derived tokens.
+ *
+ * @param options Optional name hint, explicit tokens, timeout, key override, or custom ping callback.
  * @returns A factory provider with a unique internal DI token for `TerminusModule` indicatorProviders.
  */
 export function createPrismaHealthIndicatorProvider(options = {}) {
   const indicatorProviderToken = Symbol('fluo.terminus.prisma-health-indicator');
+  const hasExplicitServiceToken = options.serviceToken !== undefined;
+  const hasExplicitClientToken = options.clientToken !== undefined;
+  const serviceToken = hasExplicitServiceToken || !hasExplicitClientToken ? options.serviceToken ?? getPrismaServiceToken(options.name) : undefined;
+  const clientToken = hasExplicitClientToken || !hasExplicitServiceToken ? options.clientToken ?? getPrismaClientToken(options.name) : undefined;
+  const inject = [...(serviceToken === undefined ? [] : [optional(serviceToken)]), ...(clientToken === undefined ? [] : [optional(clientToken)])];
   return {
-    inject: [PRISMA_CLIENT],
+    inject,
     provide: indicatorProviderToken,
-    useFactory: client => new PrismaHealthIndicator({
-      ...options,
-      client: client
-    })
+    useFactory: (...resolvedDependencies) => {
+      const resolvedService = serviceToken === undefined ? undefined : resolvedDependencies[0];
+      const resolvedClientIndex = serviceToken === undefined ? 0 : 1;
+      const resolvedClient = clientToken === undefined ? undefined : resolvedDependencies[resolvedClientIndex];
+      return new PrismaHealthIndicator({
+        ...options,
+        client: resolvedClient,
+        service: toPrismaService(resolvedService)
+      });
+    }
   };
 }
 
-/** Health indicator that probes Prisma connectivity with a trivial query. */
+/** Health indicator that maps Prisma lifecycle status and probes connectivity with a trivial query. */
 export class PrismaHealthIndicator {
   key;
   constructor(options = {}) {
@@ -69,11 +143,19 @@ export class PrismaHealthIndicator {
   }
   async check(key) {
     const indicatorKey = resolveIndicatorKey('prisma', this.options.key ?? key);
-    const timeoutMs = this.options.timeoutMs ?? DEFAULT_PRISMA_TIMEOUT_MS;
     try {
+      const timeoutMs = resolveIndicatorTimeoutMs(this.options.timeoutMs, DEFAULT_PRISMA_TIMEOUT_MS, indicatorKey);
+      const snapshot = createPrismaLifecycleSnapshot(this.options.service);
+      const lifecycleDownResult = snapshot ? createPrismaLifecycleDownResult(indicatorKey, snapshot) : undefined;
+      if (lifecycleDownResult) {
+        throwHealthCheckError('Prisma health check failed.', lifecycleDownResult);
+      }
       await withIndicatorTimeout(runPrismaPing(this.options), timeoutMs, indicatorKey);
-      return createUpResult(indicatorKey);
+      return createUpResult(indicatorKey, createPrismaLifecycleUpDetails(snapshot));
     } catch (error) {
+      if (error instanceof Error && error.name === 'HealthCheckError') {
+        throw error;
+      }
       throwHealthCheckError('Prisma health check failed.', createDownResult(indicatorKey, error instanceof Error ? error.message : 'Prisma health check failed.'));
     }
   }

package/dist/indicators/redis.js

@@ -1,5 +1,5 @@
 import { createRedisPlatformStatusSnapshot, getRedisClientToken, getRedisComponentId } from '@fluojs/redis';
-import { createDownResult, createUpResult, resolveIndicatorKey, throwHealthCheckError, withIndicatorTimeout } from './utils.js';
+import { createDownResult, createUpResult, resolveIndicatorKey, resolveIndicatorTimeoutMs, throwHealthCheckError, withIndicatorTimeout } from './utils.js';
 
 /**
  * Options for probing Redis connectivity.
@@ -98,8 +98,8 @@ export class RedisHealthIndicator {
   }
   async check(key) {
     const indicatorKey = resolveIndicatorKey('redis', this.options.key ?? key);
-    const timeoutMs = this.options.timeoutMs ?? DEFAULT_REDIS_TIMEOUT_MS;
     try {
+      const timeoutMs = resolveIndicatorTimeoutMs(this.options.timeoutMs, DEFAULT_REDIS_TIMEOUT_MS, indicatorKey);
       const lifecycleDownResult = createRedisLifecycleDownResult(indicatorKey, this.options);
       if (lifecycleDownResult) {
         throwHealthCheckError('Redis health check failed.', lifecycleDownResult);

package/dist/indicators/utils.d.ts

@@ -3,6 +3,16 @@ import type { HealthIndicatorResult } from '../types.js';
 export interface IndicatorTimeoutOptions {
     timeoutMs?: number;
 }
+/**
+ * Resolve an indicator timeout budget before it reaches timeout scheduling.
+ *
+ * @param timeoutMs Caller-provided timeout budget in milliseconds.
+ * @param defaultTimeoutMs Default timeout budget used when `timeoutMs` is omitted.
+ * @param indicatorName Indicator name used in timeout validation errors.
+ * @returns A positive integer timeout budget in milliseconds.
+ * @throws {Error} When the resolved timeout is zero, negative, `NaN`, or infinite.
+ */
+export declare function resolveIndicatorTimeoutMs(timeoutMs: number | undefined, defaultTimeoutMs: number, indicatorName: string): number;
 /**
  * Create an `up` indicator result payload.
  *

package/dist/indicators/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/indicators/utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzD,6EAA6E;AAC7E,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,qBAAqB,CAOxG;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACpC,qBAAqB,CAQvB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,CAAC,CAAC,CAiBZ;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,MAAM,CAER;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB,GAAG,KAAK,CAE3F"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/indicators/utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzD,6EAA6E;AAC7E,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAUD;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,gBAAgB,EAAE,MAAM,EACxB,aAAa,EAAE,MAAM,GACpB,MAAM,CAER;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,qBAAqB,CAOxG;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACpC,qBAAqB,CAQvB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,CAAC,CAAC,CAyBZ;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,MAAM,CAER;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB,GAAG,KAAK,CAE3F"}

package/dist/indicators/utils.js

@@ -2,6 +2,26 @@ import { HealthCheckError } from '../errors.js';
 
 /** Timeout settings shared by indicators that call external dependencies. */
 
+function normalizePositiveFiniteTimeoutMs(timeoutMs, indicatorName) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new Error(`${indicatorName} health indicator timeoutMs must be a positive finite number.`);
+  }
+  return Math.max(1, Math.floor(timeoutMs));
+}
+
+/**
+ * Resolve an indicator timeout budget before it reaches timeout scheduling.
+ *
+ * @param timeoutMs Caller-provided timeout budget in milliseconds.
+ * @param defaultTimeoutMs Default timeout budget used when `timeoutMs` is omitted.
+ * @param indicatorName Indicator name used in timeout validation errors.
+ * @returns A positive integer timeout budget in milliseconds.
+ * @throws {Error} When the resolved timeout is zero, negative, `NaN`, or infinite.
+ */
+export function resolveIndicatorTimeoutMs(timeoutMs, defaultTimeoutMs, indicatorName) {
+  return normalizePositiveFiniteTimeoutMs(timeoutMs ?? defaultTimeoutMs, indicatorName);
+}
+
 /**
  * Create an `up` indicator result payload.
  *
@@ -45,10 +65,16 @@ export function createDownResult(key, message, details = {}) {
  * @returns The original promise result when it finishes in time.
  */
 export function withIndicatorTimeout(promise, timeoutMs, indicatorName) {
+  let normalizedTimeoutMs;
+  try {
+    normalizedTimeoutMs = normalizePositiveFiniteTimeoutMs(timeoutMs, indicatorName);
+  } catch (error) {
+    return Promise.reject(error);
+  }
   return new Promise((resolve, reject) => {
     const timer = setTimeout(() => {
-      reject(new Error(`${indicatorName} health indicator timed out after ${String(timeoutMs)}ms.`));
-    }, timeoutMs);
+      reject(new Error(`${indicatorName} health indicator timed out after ${String(normalizedTimeoutMs)}ms.`));
+    }, normalizedTimeoutMs);
     promise.then(value => {
       clearTimeout(timer);
       resolve(value);

package/dist/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,UAAU,EAIhB,MAAM,iBAAiB,CAAC;AAIzB,OAAO,KAAK,EAA4D,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAyQlH,uFAAuF;AACvF,qBAAa,cAAc;IACzB;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,qBAA0B,GAAG,UAAU;CAGhE"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,UAAU,EAKhB,MAAM,iBAAiB,CAAC;AAIzB,OAAO,KAAK,EAA4D,qBAAqB,EAAE,MAAM,YAAY,CAAC;AA6RlH,uFAAuF;AACvF,qBAAa,cAAc;IACzB;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,qBAA0B,GAAG,UAAU;CAGhE"}

package/dist/module.js

@@ -83,7 +83,7 @@ function createPlatformReadinessDiagnostic(readiness) {
   };
 }
 function createPlatformDiagnosticCollisionKey(diagnosticKey, seenKeys) {
-  const baseKey = `${diagnosticKey}-duplicate-key-error`;
+  const baseKey = `${diagnosticKey}-user-key-collision`;
   if (!seenKeys.has(baseKey)) {
     return baseKey;
   }
@@ -95,42 +95,51 @@ function createPlatformDiagnosticCollisionKey(diagnosticKey, seenKeys) {
   }
   return candidate;
 }
-function appendPlatformDiagnostic(entries, existingKeys, diagnosticKey, diagnostic) {
+function appendPlatformDiagnostic(entries, collisionEntries, diagnosticKey, diagnostic) {
   if (diagnostic === undefined) {
     return;
   }
-  if (!existingKeys.has(diagnosticKey) && !(diagnosticKey in entries)) {
-    entries[diagnosticKey] = diagnostic;
-    return;
+  if (diagnosticKey in collisionEntries) {
+    const collisionKey = createPlatformDiagnosticCollisionKey(diagnosticKey, new Set([...Object.keys(entries), ...Object.keys(collisionEntries)]));
+    entries[collisionKey] = {
+      message: `User health result key "${diagnosticKey}" is reserved for Terminus platform diagnostics; the platform diagnostic remains available under the reserved key.`,
+      status: 'down'
+    };
   }
-  const collisionKey = createPlatformDiagnosticCollisionKey(diagnosticKey, new Set([...existingKeys, ...Object.keys(entries)]));
-  entries[collisionKey] = {
-    message: `Platform diagnostic key "${diagnosticKey}" collided with an existing health result key.`,
-    status: 'down'
-  };
+  entries[diagnosticKey] = diagnostic;
+}
+function withoutKeys(entries, keys) {
+  return Object.fromEntries(Object.entries(entries).filter(([key]) => !keys.has(key)));
+}
+function remapContributors(contributors, reservedKeys, platformDiagnosticKeys) {
+  return contributors.filter(key => !reservedKeys.has(key) && !platformDiagnosticKeys.includes(key));
 }
 function withPlatformDiagnostics(report, health, readiness) {
   const platformDiagnostics = {};
   const healthDiagnostic = createPlatformHealthDiagnostic(health);
   const readinessDiagnostic = createPlatformReadinessDiagnostic(readiness);
-  const existingKeys = new Set(Object.keys(report.details));
-  appendPlatformDiagnostic(platformDiagnostics, existingKeys, 'fluo-platform-health', healthDiagnostic);
-  appendPlatformDiagnostic(platformDiagnostics, existingKeys, 'fluo-platform-readiness', readinessDiagnostic);
+  appendPlatformDiagnostic(platformDiagnostics, report.details, 'fluo-platform-health', healthDiagnostic);
+  appendPlatformDiagnostic(platformDiagnostics, report.details, 'fluo-platform-readiness', readinessDiagnostic);
   const platformDiagnosticKeys = Object.keys(platformDiagnostics);
+  const platformReservedKeys = new Set([...(healthDiagnostic ? ['fluo-platform-health'] : []), ...(readinessDiagnostic ? ['fluo-platform-readiness'] : [])]);
+  const reportDetails = withoutKeys(report.details, platformReservedKeys);
+  const reportInfo = withoutKeys(report.info, platformReservedKeys);
+  const reportError = withoutKeys(report.error, platformReservedKeys);
   return {
     ...report,
     contributors: {
-      down: [...report.contributors.down, ...platformDiagnosticKeys],
-      up: [...report.contributors.up]
+      down: [...remapContributors(report.contributors.down, platformReservedKeys, platformDiagnosticKeys), ...platformDiagnosticKeys],
+      up: remapContributors(report.contributors.up, platformReservedKeys, platformDiagnosticKeys)
     },
     details: {
-      ...report.details,
+      ...reportDetails,
       ...platformDiagnostics
     },
     error: {
-      ...report.error,
+      ...reportError,
       ...platformDiagnostics
     },
+    info: reportInfo,
     platform: {
       health,
       readiness
@@ -159,7 +168,7 @@ function createTerminusRuntimeModule(options = {}) {
   const TERMINUS_READINESS_REGISTRAR = Symbol('fluo.terminus.readiness-registrar');
   class TerminusRuntimeModule {}
   return defineModule(TerminusRuntimeModule, {
-    exports: [TERMINUS_HEALTH_INDICATORS, TerminusHealthService],
+    exports: [TERMINUS_HEALTH_INDICATORS, TERMINUS_INDICATOR_PROVIDER_TOKENS, TerminusHealthService],
     imports: [healthModule],
     providers: [...createTerminusProviders({
       execution: options.execution,

package/package.json

@@ -9,7 +9,7 @@
     "liveness",
     "health-check"
   ],
-  "version": "1.0.4",
+  "version": "1.1.0",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -44,15 +44,15 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.0.3",
-    "@fluojs/di": "^1.1.0",
-    "@fluojs/http": "^1.1.0",
-    "@fluojs/runtime": "^1.1.6"
+    "@fluojs/core": "^1.1.0",
+    "@fluojs/di": "^2.0.0",
+    "@fluojs/http": "^2.0.1",
+    "@fluojs/runtime": "^2.0.1"
   },
   "peerDependencies": {
-    "@fluojs/drizzle": "^1.0.2",
-    "@fluojs/prisma": "^1.0.2",
-    "@fluojs/redis": "^1.0.1"
+    "@fluojs/drizzle": "^1.1.1",
+    "@fluojs/prisma": "^1.1.1",
+    "@fluojs/redis": "^1.1.0"
   },
   "peerDependenciesMeta": {
     "@fluojs/drizzle": {
@@ -67,7 +67,7 @@
   },
   "devDependencies": {
     "vitest": "^3.2.4",
-    "@fluojs/testing": "^1.0.5"
+    "@fluojs/testing": "^2.0.0"
   },
   "scripts": {
     "prebuild": "node ../../tooling/scripts/clean-dist.mjs",