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

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).