@fluojs/terminus 1.0.2 → 1.0.4

package/README.ko.md

@@ -24,7 +24,11 @@ fluo 애플리케이션을 위한 헬스 인디케이터(Health Indicator) 툴
 pnpm add @fluojs/terminus
 ```
 
-`path`로 health endpoint를 custom path 아래에 mount할 수 있고, `readinessChecks`로 애플리케이션별 readiness logic을 Terminus indicator 및 platform readiness check와 합성할 수 있습니다.
+Redis indicator subpath를 사용할 때만 선택적 peer를 설치하세요.
+
+```bash
+pnpm add @fluojs/redis ioredis
+```
 
 ## 사용 시점
 
@@ -68,7 +72,7 @@ class AppModule {}
 
 ### DI 기반 인디케이터
 
-Redis나 DB 클라이언트와 같이 DI 컨테이너의 의존성이 필요한 인디케이터를 사용할 때는, 모듈 로드 시점에 피어 의존성을 import하지 않도록 제공되는 provider 팩토리를 사용하세요.
+Redis나 DB 클라이언트와 같이 DI 컨테이너의 의존성이 필요한 인디케이터를 사용할 때는, 모듈 로드 시점에 피어 의존성을 import하지 않도록 문서화된 provider 팩토리를 사용하세요. 이 helper들은 `TerminusModule.forRoot({ indicatorProviders })`에 전달할 indicator provider entry를 만들며 module facade를 대체하지 않습니다.
 
 ```typescript
 import { TerminusModule } from '@fluojs/terminus';
@@ -92,6 +96,8 @@ TerminusModule.forRoot({
 });
 ```
 
+`@fluojs/terminus/redis`를 통해 만든 Redis indicator는 `@fluojs/redis`에서 받은 client가 있으면 lifecycle-aware로 동작합니다. Terminus는 `PING`을 보내기 전에 Redis connection state를 `createRedisPlatformStatusSnapshot(...)`으로 매핑하므로, client가 `wait`, `connecting`, `reconnecting`, `close`, `end` 상태이면 raw ping만 믿지 않고 `/health`와 `/ready`를 unavailable로 표시합니다. Custom `ping` callback은 manual probe용으로 계속 지원되지만, lifecycle metadata는 Redis client가 `status`를 노출할 때만 붙습니다.
+
 Drizzle의 경우 `createDrizzleHealthIndicatorProvider()`는 `@fluojs/drizzle`이 노출하는 lifecycle-aware `DrizzleDatabase` wrapper를 우선 사용합니다. Drizzle이 종료 중이거나 중지되었거나 `DrizzleDatabase.createPlatformStatusSnapshot()` 기준으로 준비되지 않은 상태이면 SQL probe를 실행하기 전에 해당 indicator를 `down`으로 보고합니다. legacy raw `DRIZZLE_DATABASE` handle만 등록된 경우에는 기존 lightweight SQL probe 동작을 유지합니다.
 
 Provider factory는 반복 등록할 수 있습니다. 각 인스턴스가 서로 다른 indicator key나 dependency option을 사용한다면 같은 factory가 만든 provider 여러 개를 하나의 `indicatorProviders` 배열에 등록할 수 있으며, Terminus는 나중에 등록된 같은 타입 provider가 앞선 provider를 덮어쓰지 않도록 각 provider 인스턴스를 별도 DI token으로 보관합니다.
@@ -111,6 +117,8 @@ TerminusModule.forRoot({
 });
 ```
 
+`path`로 health endpoint를 custom path 아래에 mount할 수 있고, `readinessChecks`로 애플리케이션별 readiness logic을 Terminus indicator 및 platform readiness check와 합성할 수 있습니다.
+
 ### 실패 시맨틱
 
 인디케이터가 실패하면 `HealthCheckError`를 던집니다. `TerminusHealthService`는 이 실패들을 모아 보고서를 작성합니다.
@@ -125,6 +133,7 @@ TerminusModule.forRoot({
 - 플랫폼 health/readiness 실패는 `/health` 응답에서 결정적인 `fluo-platform-health`, `fluo-platform-readiness` contributor로 노출됩니다.
 - Runtime diagnostics가 있으면 `/health` response에 platform health/readiness detail을 담은 `platform` block이 포함될 수 있습니다.
 - 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로 표시합니다.
 
 ## 공개 API 개요
 
@@ -145,12 +154,13 @@ TerminusModule.forRoot({
 
 - `runHealthCheck(...)`, `assertHealthCheck(...)`: 직접 aggregation/testing helper입니다.
 - `TERMINUS_HEALTH_INDICATORS`, `TERMINUS_INDICATOR_PROVIDER_TOKENS`: 등록된 indicator와 provider token을 위한 DI token입니다.
-- Built-in indicator는 `create*HealthIndicator()` 및 `create*HealthIndicatorProvider()` helper도 노출합니다.
+- Built-in indicator는 `create*HealthIndicator()` 및 `create*HealthIndicatorProvider()` helper도 노출합니다. Provider helper는 `indicatorProviders`를 위한 의도적인 DI composition 예외이며, 애플리케이션 등록은 계속 `TerminusModule.forRoot(...)`를 사용해야 합니다.
 
 ### `@fluojs/terminus/redis`
 
 - `RedisHealthIndicator`, `createRedisHealthIndicator()`, `createRedisHealthIndicatorProvider()`
   - Redis 전용 인디케이터 헬퍼는 선택적 Redis 피어가 설치되지 않은 환경에서도 루트 패키지 import가 안전하도록 전용 subpath에서 export됩니다.
+  - Provider는 기본적으로 default `@fluojs/redis` client token을 resolve하고, `clientName`이 있으면 named token을 resolve하며, Redis platform status semantics를 readiness 진단에 재사용합니다.
 
 ### `@fluojs/terminus/node`
 

package/README.md

@@ -24,6 +24,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:
+
+```bash
+pnpm add @fluojs/redis ioredis
+```
+
 ## When to Use
 
 - When you need to monitor external dependencies (databases, Redis, APIs) as part of your application's health status.
@@ -66,7 +72,7 @@ The package provides several indicators out of the box:
 
 ### DI-Backed Indicators
 
-To use indicators that require dependencies from the DI container (like Redis or Database clients) without importing peer dependencies at module load time, use the provider factories.
+To use indicators that require dependencies from the DI container (like Redis or Database clients) without importing peer dependencies at module load time, use the documented provider factories. These helpers create indicator provider entries for `TerminusModule.forRoot({ indicatorProviders })`; they do not replace the module facade.
 
 ```typescript
 import { TerminusModule } from '@fluojs/terminus';
@@ -90,6 +96,8 @@ TerminusModule.forRoot({
 });
 ```
 
+Redis indicators created through `@fluojs/terminus/redis` are lifecycle-aware when they receive a client from `@fluojs/redis`. Terminus maps the Redis connection state with `createRedisPlatformStatusSnapshot(...)` before sending `PING`, so clients in `wait`, `connecting`, `reconnecting`, `close`, or `end` states mark `/health` and `/ready` unavailable instead of relying on a raw ping alone. Custom `ping` callbacks remain supported for manual probes, but lifecycle metadata is only attached when a Redis client exposes its `status`.
+
 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.
 
 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.
@@ -125,6 +133,7 @@ When an indicator fails, it throws a `HealthCheckError`. The `TerminusHealthServ
 - Platform health/readiness failures are surfaced as deterministic `fluo-platform-health` and `fluo-platform-readiness` contributors in `/health` responses.
 - `/health` responses may include a `platform` block with platform health/readiness details when runtime diagnostics are available.
 - 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.
 
 ## Public API Overview
 
@@ -145,12 +154,13 @@ When an indicator fails, it throws a `HealthCheckError`. The `TerminusHealthServ
 
 - `runHealthCheck(...)`, `assertHealthCheck(...)`: Direct aggregation/testing helpers.
 - `TERMINUS_HEALTH_INDICATORS`, `TERMINUS_INDICATOR_PROVIDER_TOKENS`: DI tokens for registered indicators and provider tokens.
-- Built-in indicators also expose `create*HealthIndicator()` and `create*HealthIndicatorProvider()` helpers.
+- 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`
 
 - `RedisHealthIndicator`, `createRedisHealthIndicator()`, `createRedisHealthIndicatorProvider()`
   - Redis-specific indicator helpers are exported from the dedicated subpath so the root package stays import-safe without the optional Redis peer installed.
+  - The provider resolves the default `@fluojs/redis` client token by default, or a named token when `clientName` is supplied, and reuses Redis platform status semantics for readiness diagnostics.
 
 ### `@fluojs/terminus/node`
 

package/dist/indicators/memory.d.ts

@@ -1,17 +1,28 @@
 import type { Provider } from '@fluojs/di';
 import type { HealthIndicator, HealthIndicatorResult } from '../types.js';
+/** Snapshot returned by a memory usage sampler. */
+export interface MemoryUsageSnapshot {
+    arrayBuffers: number;
+    external: number;
+    heapTotal: number;
+    heapUsed: number;
+    rss: number;
+}
+/** Function that samples runtime memory usage for `MemoryHealthIndicator`. */
+export type MemoryUsageSampler = () => MemoryUsageSnapshot;
 /** Options for checking process heap and RSS thresholds. */
 export interface MemoryHealthIndicatorOptions {
     heapUsedThresholdBytes?: number;
     heapUsedThresholdRatio?: number;
     key?: string;
+    memoryUsage?: MemoryUsageSampler;
     rssThresholdBytes?: number;
 }
 /**
  * Create a process-memory health indicator.
  *
  * @param options Optional heap and RSS thresholds plus an indicator key override.
- * @returns A health indicator backed by `process.memoryUsage()`.
+ * @returns A health indicator backed by the Node runtime memory sampler.
  */
 export declare function createMemoryHealthIndicator(options?: MemoryHealthIndicatorOptions): HealthIndicator;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/indicators/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG3C,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE1E,4DAA4D;AAC5D,MAAM,WAAW,4BAA4B;IAC3C,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAYD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,GAAE,4BAAiC,GAAG,eAAe,CAEvG;AAED;;;;;GAKG;AACH,wBAAgB,mCAAmC,CAAC,OAAO,GAAE,4BAAiC,GAAG,QAAQ,CAOxG;AAED,qEAAqE;AACrE,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;CAiCzD"}
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/indicators/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAI3C,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE1E,mDAAmD;AACnD,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,8EAA8E;AAC9E,MAAM,MAAM,kBAAkB,GAAG,MAAM,mBAAmB,CAAC;AAE3D,4DAA4D;AAC5D,MAAM,WAAW,4BAA4B;IAC3C,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAYD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,GAAE,4BAAiC,GAAG,eAAe,CAEvG;AAED;;;;;GAKG;AACH,wBAAgB,mCAAmC,CAAC,OAAO,GAAE,4BAAiC,GAAG,QAAQ,CAOxG;AAED,qEAAqE;AACrE,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;CAiCzD"}

package/dist/indicators/memory.js

@@ -1,4 +1,9 @@
 import { createDownResult, createUpResult, resolveIndicatorKey, throwHealthCheckError } from './utils.js';
+import { readNodeMemoryUsage } from '../node-runtime.js';
+
+/** Snapshot returned by a memory usage sampler. */
+
+/** Function that samples runtime memory usage for `MemoryHealthIndicator`. */
 
 /** Options for checking process heap and RSS thresholds. */
 
@@ -14,7 +19,7 @@ function exceedsRatioThreshold(used, total, threshold) {
  * Create a process-memory health indicator.
  *
  * @param options Optional heap and RSS thresholds plus an indicator key override.
- * @returns A health indicator backed by `process.memoryUsage()`.
+ * @returns A health indicator backed by the Node runtime memory sampler.
  */
 export function createMemoryHealthIndicator(options = {}) {
   return new MemoryHealthIndicator(options);
@@ -44,7 +49,7 @@ export class MemoryHealthIndicator {
   async check(key) {
     const indicatorKey = resolveIndicatorKey('memory', this.options.key ?? key);
     const heapRatioThreshold = this.options.heapUsedThresholdRatio ?? DEFAULT_HEAP_RATIO_THRESHOLD;
-    const usage = process.memoryUsage();
+    const usage = (this.options.memoryUsage ?? readNodeMemoryUsage)();
     const usageDetails = {
       arrayBuffers: usage.arrayBuffers,
       external: usage.external,

package/dist/indicators/redis.d.ts

@@ -1,31 +1,49 @@
 import type { Provider } from '@fluojs/di';
+import { type RedisStatusAdapterInput } from '@fluojs/redis';
 import type { HealthIndicator, HealthIndicatorResult } from '../types.js';
 interface RedisClientLike {
     ping?: () => Promise<unknown>;
+    status?: RedisStatusAdapterInput['status'];
 }
-/** Options for probing Redis connectivity. */
+/**
+ * Options for probing Redis connectivity.
+ *
+ * `client` may be a raw `ioredis`-compatible handle resolved from `@fluojs/redis`.
+ * When that handle exposes a Redis `status`, Terminus maps the lifecycle state into
+ * health/readiness metadata before issuing `PING`, so shutdown or disconnected clients
+ * fail readiness even if a raw ping callback would still be callable.
+ */
 export interface RedisHealthIndicatorOptions {
+    /** Raw Redis client to probe. Its `status` is used for lifecycle-aware readiness when available. */
     client?: RedisClientLike;
+    /** Named Redis registration to resolve when using `createRedisHealthIndicatorProvider(...)`. */
     clientName?: string;
+    /** Indicator result key override. Defaults to the key passed to `check(...)`, then `redis`. */
     key?: string;
+    /** Custom ping callback for manual probes or tests. Lifecycle state is only mapped when `client.status` is available. */
     ping?: () => Promise<unknown> | unknown;
+    /** Maximum time to wait for the ping operation. Defaults to `2_000` ms. */
     timeoutMs?: number;
 }
 /**
  * Create a Redis health indicator.
  *
- * @param options Optional Redis client, ping callback, timeout, and key override.
- * @returns A health indicator that checks Redis with `PING` semantics.
+ * @param options Optional Redis client, named-client hint, ping callback, timeout, and key override.
+ * @returns A health indicator that checks Redis lifecycle status before `PING` when client state is available.
  */
 export declare function createRedisHealthIndicator(options?: RedisHealthIndicatorOptions): HealthIndicator;
 /**
  * Create a provider that resolves a Redis client from DI and wraps it as an indicator.
  *
- * @param options Optional timeout, key override, or custom ping callback.
+ * The provider resolves `getRedisClientToken(options.clientName)`, preserving the
+ * default-vs-named client lifecycle boundary from `@fluojs/redis` while keeping the
+ * Redis-specific peer dependency isolated to `@fluojs/terminus/redis`.
+ *
+ * @param options Optional named-client hint, timeout, key override, or custom ping callback.
  * @returns A factory provider that exposes `RedisHealthIndicator` from the DI container.
  */
 export declare function createRedisHealthIndicatorProvider(options?: Omit<RedisHealthIndicatorOptions, 'client'>): Provider;
-/** Health indicator that checks Redis reachability with a ping-like operation. */
+/** Health indicator that maps Redis lifecycle status and checks reachability with a ping-like operation. */
 export declare class RedisHealthIndicator implements HealthIndicator {
     private readonly options;
     readonly key: string | undefined;

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

@@ -1 +1 @@
-{"version":3,"file":"redis.d.ts","sourceRoot":"","sources":["../../src/indicators/redis.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAI3C,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE1E,UAAU,eAAe;IACvB,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/B;AAED,8CAA8C;AAC9C,MAAM,WAAW,2BAA2B;IAC1C,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAmBD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,2BAAgC,GAAG,eAAe,CAErG;AAED;;;;;GAKG;AACH,wBAAgB,kCAAkC,CAAC,OAAO,GAAE,IAAI,CAAC,2BAA2B,EAAE,QAAQ,CAAM,GAAG,QAAQ,CAQtH;AAED,kFAAkF;AAClF,qBAAa,oBAAqB,YAAW,eAAe;IAG9C,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEJ,OAAO,GAAE,2BAAgC;IAIhE,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAczD"}
+{"version":3,"file":"redis.d.ts","sourceRoot":"","sources":["../../src/indicators/redis.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAA+E,KAAK,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAG1I,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE1E,UAAU,eAAe;IACvB,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B,MAAM,CAAC,EAAE,uBAAuB,CAAC,QAAQ,CAAC,CAAC;CAC5C;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,2BAA2B;IAC1C,oGAAoG;IACpG,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,gGAAgG;IAChG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+FAA+F;IAC/F,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yHAAyH;IACzH,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACxC,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAoED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,2BAAgC,GAAG,eAAe,CAErG;AAED;;;;;;;;;GASG;AACH,wBAAgB,kCAAkC,CAAC,OAAO,GAAE,IAAI,CAAC,2BAA2B,EAAE,QAAQ,CAAM,GAAG,QAAQ,CAQtH;AAED,4GAA4G;AAC5G,qBAAa,oBAAqB,YAAW,eAAe;IAG9C,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEJ,OAAO,GAAE,2BAAgC;IAIhE,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAwBzD"}

package/dist/indicators/redis.js

@@ -1,7 +1,14 @@
-import { getRedisClientToken } from '@fluojs/redis';
+import { createRedisPlatformStatusSnapshot, getRedisClientToken, getRedisComponentId } from '@fluojs/redis';
 import { createDownResult, createUpResult, resolveIndicatorKey, throwHealthCheckError, withIndicatorTimeout } from './utils.js';
 
-/** Options for probing Redis connectivity. */
+/**
+ * Options for probing Redis connectivity.
+ *
+ * `client` may be a raw `ioredis`-compatible handle resolved from `@fluojs/redis`.
+ * When that handle exposes a Redis `status`, Terminus maps the lifecycle state into
+ * health/readiness metadata before issuing `PING`, so shutdown or disconnected clients
+ * fail readiness even if a raw ping callback would still be callable.
+ */
 
 const DEFAULT_REDIS_TIMEOUT_MS = 2_000;
 async function runRedisPing(options) {
@@ -15,12 +22,46 @@ async function runRedisPing(options) {
   }
   await client.ping();
 }
+function createRedisLifecycleDownResult(indicatorKey, options) {
+  const status = options.client?.status;
+  if (!status) {
+    return undefined;
+  }
+  const snapshot = createRedisPlatformStatusSnapshot({
+    componentId: getRedisComponentId(options.clientName),
+    status
+  });
+  if (snapshot.health.status === 'healthy' && snapshot.readiness.status === 'ready') {
+    return undefined;
+  }
+  const message = snapshot.readiness.reason ?? snapshot.health.reason ?? `Redis lifecycle reported health=${snapshot.health.status} readiness=${snapshot.readiness.status}.`;
+  return createDownResult(indicatorKey, message, {
+    details: snapshot.details,
+    healthStatus: snapshot.health.status,
+    readinessStatus: snapshot.readiness.status
+  });
+}
+function createRedisLifecycleUpDetails(options) {
+  const status = options.client?.status;
+  if (!status) {
+    return {};
+  }
+  const snapshot = createRedisPlatformStatusSnapshot({
+    componentId: getRedisComponentId(options.clientName),
+    status
+  });
+  return {
+    details: snapshot.details,
+    healthStatus: snapshot.health.status,
+    readinessStatus: snapshot.readiness.status
+  };
+}
 
 /**
  * Create a Redis health indicator.
  *
- * @param options Optional Redis client, ping callback, timeout, and key override.
- * @returns A health indicator that checks Redis with `PING` semantics.
+ * @param options Optional Redis client, named-client hint, ping callback, timeout, and key override.
+ * @returns A health indicator that checks Redis lifecycle status before `PING` when client state is available.
  */
 export function createRedisHealthIndicator(options = {}) {
   return new RedisHealthIndicator(options);
@@ -29,7 +70,11 @@ export function createRedisHealthIndicator(options = {}) {
 /**
  * Create a provider that resolves a Redis client from DI and wraps it as an indicator.
  *
- * @param options Optional timeout, key override, or custom ping callback.
+ * The provider resolves `getRedisClientToken(options.clientName)`, preserving the
+ * default-vs-named client lifecycle boundary from `@fluojs/redis` while keeping the
+ * Redis-specific peer dependency isolated to `@fluojs/terminus/redis`.
+ *
+ * @param options Optional named-client hint, timeout, key override, or custom ping callback.
  * @returns A factory provider that exposes `RedisHealthIndicator` from the DI container.
  */
 export function createRedisHealthIndicatorProvider(options = {}) {
@@ -44,7 +89,7 @@ export function createRedisHealthIndicatorProvider(options = {}) {
   };
 }
 
-/** Health indicator that checks Redis reachability with a ping-like operation. */
+/** Health indicator that maps Redis lifecycle status and checks reachability with a ping-like operation. */
 export class RedisHealthIndicator {
   key;
   constructor(options = {}) {
@@ -55,9 +100,16 @@ export class RedisHealthIndicator {
     const indicatorKey = resolveIndicatorKey('redis', this.options.key ?? key);
     const timeoutMs = this.options.timeoutMs ?? DEFAULT_REDIS_TIMEOUT_MS;
     try {
+      const lifecycleDownResult = createRedisLifecycleDownResult(indicatorKey, this.options);
+      if (lifecycleDownResult) {
+        throwHealthCheckError('Redis health check failed.', lifecycleDownResult);
+      }
       await withIndicatorTimeout(runRedisPing(this.options), timeoutMs, indicatorKey);
-      return createUpResult(indicatorKey);
+      return createUpResult(indicatorKey, createRedisLifecycleUpDetails(this.options));
     } catch (error) {
+      if (error instanceof Error && error.name === 'HealthCheckError') {
+        throw error;
+      }
       throwHealthCheckError('Redis health check failed.', createDownResult(indicatorKey, error instanceof Error ? error.message : 'Redis health check failed.'));
     }
   }

package/dist/node-runtime.d.ts

@@ -0,0 +1,11 @@
+interface NodeMemoryUsageSnapshot {
+    arrayBuffers: number;
+    external: number;
+    heapTotal: number;
+    heapUsed: number;
+    rss: number;
+}
+/** Read Node.js process memory usage through the Terminus Node runtime seam. */
+export declare function readNodeMemoryUsage(): NodeMemoryUsageSnapshot;
+export {};
+//# sourceMappingURL=node-runtime.d.ts.map

package/dist/node-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-runtime.d.ts","sourceRoot":"","sources":["../src/node-runtime.ts"],"names":[],"mappings":"AAAA,UAAU,uBAAuB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb;AAkBD,gFAAgF;AAChF,wBAAgB,mBAAmB,IAAI,uBAAuB,CAQ7D"}

package/dist/node-runtime.js

@@ -0,0 +1,13 @@
+function resolveNodeProcess() {
+  const runtimeGlobal = globalThis;
+  return runtimeGlobal.process;
+}
+
+/** Read Node.js process memory usage through the Terminus Node runtime seam. */
+export function readNodeMemoryUsage() {
+  const memoryUsage = resolveNodeProcess()?.memoryUsage;
+  if (typeof memoryUsage !== 'function') {
+    throw new Error('Node.js process.memoryUsage() is not available in this runtime.');
+  }
+  return memoryUsage();
+}

package/package.json

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