Initial Commit

openspec/archive/2026-05-24-health-check/proposal.md

@@ -0,0 +1,39 @@
+# Proposal — Migrate @suaveplan/health-check to genesis
+
+## Why
+
+`@suaveplan/health-check` is the server-tier orchestrator for `/health`, `/ready`, and `/live` endpoints with dependency checks. The upstream package at `/mnt/s/web/suaveplan/packages/server/health-check/` predates the genesis enterprise gates: it uses the upstream `EventEmitter` shape, calls global `Date.now()`/`setTimeout`/`fetch`/`node:net` directly, has no error-code registry, no OTel self-telemetry, and no Zod boundary validation. This change re-lands the package at `packages/observability/monitor/health-check/` (sibling to `logger`, `audit-logging`, `opentelemetry`) at full feature surface with the genesis contract.
+
+## What
+
+Land `@suaveplan/health-check@0.1.0` with the following feature modules (one per folder, 5-files-per-feature):
+
+- `health-checker/` — `HealthChecker` orchestrator with `EventBus<HealthEventMap>` and injectable `Clock` / `TimersLike` / `LoggerLike`
+- `http-check/` — `createHttpCheck` factory with injectable `fetchImpl` + `Clock`
+- `tcp-check/` — `createTcpCheck` factory with injectable `TcpConnectFn` + `Clock`
+- `response-builder/` — `ResponseBuilder` mapping `CheckStatus` → HTTP status codes
+- `error-codes/` — `HEALTH_CHECK_CODES` via `defineCodes` + public-ctor `HealthCheckError`
+- `telemetry/` — OTel meter (`health_check_runs_total`, `health_check_aggregate_status_total`, `health_check_duration_ms`)
+- `types/` — shared `CheckResult`/`CheckFn`/`DependencyCheckConfig`/`HealthResponse`/`ReadinessResponse`/`LivenessResponse`/`HttpHealthResponse`/`HttpCheckConfig`/`TcpCheckConfig`/`HealthEvent`/`HealthEventMap`
+
+## Source mapping
+
+| Upstream file | Genesis file | Notes |
+| --- | --- | --- |
+| `src/checker/health-checker.ts` | `src/health-checker/health-checker.ts` | `EventEmitter` → `EventBus<HealthEventMap>`; `Clock`+`TimersLike`+`LoggerLike` injected; Zod-validated options; `HealthCheckError` on every failure |
+| `src/checks/http-check.ts` | `src/http-check/http-check.ts` | `fetchImpl` injection replaces global `fetch`; Zod options |
+| `src/checks/tcp-check.ts` | `src/tcp-check/tcp-check.ts` | `TcpConnectFn` injection replaces direct `node:net.connect`; settled-flag guards late events |
+| `src/response/response-builder.ts` | `src/response-builder/response-builder.ts` | Same algorithm, renamed file |
+| `src/types/types.ts` | `src/types/types.ts` | Adds `HealthEventMap`, `TcpConnectFn`/`TcpSocketLike`, `HttpCheckConfig.fetchImpl`, `TcpCheckConfig.connectImpl` |
+| `src/index.ts` | `src/index.ts` | Explicit named re-exports only |
+| (none) | `src/error-codes/error-codes.ts` | New — required by genesis rule |
+| (none) | `src/telemetry/telemetry.ts` | New — required by genesis rule |
+
+## Deviations from upstream
+
+1. Upstream uses `@suaveplan/events`' `EventEmitter` with variadic tuple payloads. Genesis `@suaveplan/events` exposes `EventBus<TMap>` with single-payload `emit(type, payload)`. `STATUS_CHANGED` therefore emits `{ previous, current }` object instead of two positional args. Exposed as `HealthChecker.events`.
+2. Upstream calls `Date.now()` and `setTimeout` directly. Genesis injects `Clock` + `TimersLike` per the universal-tier contract.
+3. Upstream has no error-code registry. Genesis adds `HEALTH_CHECK_CODES` + public-ctor `HealthCheckError`.
+4. Upstream HTTP / TCP checks depend on the runtime's global `fetch` and `node:net`. Genesis injects them so tests never touch real sockets.
+5. Upstream emits no self-telemetry. Genesis adds a `telemetry/` module emitting per-check counters + duration histogram + aggregate-status counter.
+6. Boundary validation: every public option object is now Zod-validated; failures throw `HealthCheckError(INVALID_OPTIONS)`.