feat(health): define machine-readable health status enums and OpenAPI contract

docs/kubernetes-health-probes.md

@@ -29,11 +29,20 @@ All endpoints are public (no authentication required) and excluded from rate lim
 
 ### Status values
 
-| Value | Meaning |
-|---|---|
-| `ok` | All components healthy |
-| `degraded` | Some non-critical components down (readiness only) |
-| `error` | One or more critical components down — returns HTTP 503 |
+| Enum (`HealthStatus`) | Value | Meaning | HTTP Status Mapping |
+|---|---|---|---|
+| `HealthStatus.OK` | `ok` | All components healthy | `200 OK` |
+| `HealthStatus.DEGRADED` | `degraded` | Some non-critical components down (readiness only) | `200 OK` |
+| `HealthStatus.ERROR` | `error` | One or more critical components down | `503 Service Unavailable` |
+
+### Component status values
+
+| Enum (`ComponentStatus`) | Value | Meaning |
+|---|---|---|
+| `ComponentStatus.UP` | `up` | Subsystem responding within timeout threshold |
+| `ComponentStatus.DOWN` | `down` | Subsystem unreachable or throwing error |
+| `ComponentStatus.DEGRADED` | `degraded` | Subsystem responding with high latency or partial capacity |
+| `ComponentStatus.UNKNOWN` | `unknown` | Status evaluation skipped or unconfigured |
 
 ## Kubernetes probe configuration
 

src/health/dto/health-response.dto.ts

@@ -1,8 +1,26 @@
 import { ApiProperty } from "@nestjs/swagger";
 
+export enum ComponentStatus {
+  UP = "up",
+  DOWN = "down",
+  DEGRADED = "degraded",
+  UNKNOWN = "unknown",
+}
+
+export enum HealthStatus {
+  OK = "ok",
+  DEGRADED = "degraded",
+  ERROR = "error",
+}
+
 export class ComponentStatusDto {
-  @ApiProperty({ enum: ["up", "down"], example: "up" })
-  status: "up" | "down";
+  @ApiProperty({
+    enum: ComponentStatus,
+    enumName: "ComponentStatus",
+    example: ComponentStatus.UP,
+    description: "Component availability status: up, down, degraded, or unknown",
+  })
+  status: ComponentStatus | "up" | "down" | "degraded" | "unknown";
 
   @ApiProperty({
     required: false,
@@ -17,14 +35,15 @@ export class ComponentStatusDto {
 
 export class HealthResponseDto {
   @ApiProperty({
-    enum: ["ok", "degraded", "error"],
-    example: "ok",
+    enum: HealthStatus,
+    enumName: "HealthStatus",
+    example: HealthStatus.OK,
     description:
       "ok = all components up; degraded = some up; error = all critical components down",
   })
-  status: "ok" | "degraded" | "error";
+  status: HealthStatus | "ok" | "degraded" | "error";
 
-  @ApiProperty({ example: "2024-01-01T00:00:00.000Z" })
+  @ApiProperty({ example: "2024-01-01T00:00:00.000Z", description: "ISO 8601 evaluation timestamp" })
   timestamp: string;
 
   @ApiProperty({ example: 123.456, description: "Process uptime in seconds" })
@@ -37,6 +56,7 @@ export class HealthResponseDto {
       database: { status: "up", responseTime: 5 },
       redis: { status: "up", responseTime: 2 },
     },
+    description: "Map of component health details keyed by subsystem identifier",
   })
   components: Record<string, ComponentStatusDto>;
-}
+}