@btravstack/core 0.5.0 → 0.7.0

package/README.md

@@ -112,10 +112,13 @@ is a module that exports no runtime port at all.
 ## What you get
 
 - **A drain that survives Kubernetes.** On SIGTERM: readiness flips false, the
-  kernel waits `preDrainDelayMs` (default `5_000`) before telling the runtime
-  to stop accepting — endpoint removal is eventually consistent — then
-  in-flight work gets `drainTimeoutMs` (default `20_000`); whatever is still
-  open is aborted and reported `abandoned`. A second signal skips the drain.
+  kernel waits `preDrainDelayMs` (`PRE_DRAIN_DELAY_MS`, default `5_000`) before
+  telling the runtime to stop accepting — endpoint removal is eventually
+  consistent — then in-flight work gets `drainTimeoutMs` (`DRAIN_TIMEOUT_MS`,
+  default `20_000`); whatever is still open is aborted and reported
+  `abandoned`. A second signal skips the drain. Both timings have to agree with
+  the pod's `terminationGracePeriodSeconds`, which is why the deployment can
+  set them and the option only pins them.
 - **Probes from the state machine.** `GET /livez` and `GET /readyz` on
   `PROBE_PORT` (default `9000`), up before the graph is built.
 - **Configuration from the environment, typed.** The kernel provides

package/dist/index.cjs

@@ -1,9 +1,59 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-let unthrown = require("unthrown");
 let _btravstack_di = require("@btravstack/di");
+let unthrown = require("unthrown");
 let _btravstack_config = require("@btravstack/config");
 let node_http = require("node:http");
 let node_async_hooks = require("node:async_hooks");
+//#region src/instrumentation.ts
+/**
+* The set port a package contributes its instrumentation to.
+*
+* Nothing collects it unless an OTel SDK is composed, which is the point: a
+* starter DECLARES what it can instrument, and composing
+* `@btravstack/observability/otel` is what turns the declarations on. A graph
+* without it registers nothing and pays nothing — the Spring Boot starter
+* shape, in one port.
+*/
+var Instrumentations = class extends _btravstack_di.Port.many("Instrumentations") {};
+//#endregion
+//#region src/health.ts
+/**
+* A component could not answer for itself. Modeled rather than thrown, because
+* a health check that throws is a bug in the check; one that fails is the news
+* `/healthz` exists to carry.
+*/
+var HealthCheckFailed = class extends (0, unthrown.TaggedError)("HealthCheckFailed") {};
+/**
+* The set port every starter contributes to and the kernel reads whole.
+*
+* A set port rather than a registry the kernel hands out: a starter DECLARES
+* its check the same way it declares anything else, and a starter an
+* application never composed contributes nothing — no registration call to
+* forget, and no order to get wrong.
+*/
+var HealthChecks = class extends _btravstack_di.Port.many("HealthChecks") {};
+/**
+* Runs every check and folds the results into one report — the whole app is
+* unhealthy if any single component is.
+*
+* Each check's failure is recovered into a component line BEFORE `allAsync`
+* sees it, so a failing dependency cannot short-circuit the others: a report
+* naming one component is worth less than one naming all of them. What
+* survives to `allAsync`'s error channel is a `Defect` alone — a check that
+* threw rather than answered, which is a bug in the check.
+*/
+const runHealthChecks = (checks) => (0, unthrown.allAsync)(checks.map((health) => health.check().map(() => ({
+	name: health.name,
+	status: "healthy"
+})).recoverErrCases((matcher) => matcher.with(unthrown.P.tag("HealthCheckFailed"), (error) => ({
+	name: health.name,
+	status: "unhealthy",
+	reason: error.reason
+}))))).map((components) => ({
+	status: components.every((c) => c.status === "healthy") ? "healthy" : "unhealthy",
+	components
+}));
+//#endregion
 //#region src/clock.ts
 const systemClock = {
 	now: () => Date.now(),
@@ -185,6 +235,12 @@ const startProbeServer = (args) => (0, unthrown.fromSafePromise)(new Promise((re
 			respond(response, args.ready(), "ready");
 			return;
 		}
+		if (request.url === "/healthz") {
+			args.health().map((report) => {
+				response.writeHead(report.status === "healthy" ? 200 : 503, { "content-type": "application/json" }).end(JSON.stringify(report));
+			});
+			return;
+		}
 		response.writeHead(404).end();
 	});
 	const onBindError = (cause) => {
@@ -305,6 +361,37 @@ const createUnitRegistry = () => {
 //#endregion
 //#region src/start.ts
 const providesEnv = (module) => module.provides.some((provider) => provider.port.portId === _btravstack_config.Env.portId) || module.imports.some(providesEnv);
+/**
+* What the kernel reads from the environment for itself. Each field is pinned
+* by the matching `StartOptions` field — explicit beats environment beats
+* default, per field, exactly as a starter's own configuration is.
+*/
+const KERNEL_DEFAULTS = {
+	probePort: 9e3,
+	preDrainDelayMs: 5e3,
+	drainTimeoutMs: 2e4
+};
+const readKernelConfig = (options, env) => {
+	const probePort = options.probes === void 0 ? void 0 : options.probes === false ? KERNEL_DEFAULTS.probePort : options.probes.port;
+	const result = _btravstack_config.Config.object({
+		probePort: _btravstack_config.Config.pinned(probePort, _btravstack_config.Config.port("PROBE_PORT", { default: KERNEL_DEFAULTS.probePort })),
+		preDrainDelayMs: _btravstack_config.Config.pinned(options.preDrainDelayMs, _btravstack_config.Config.integer("PRE_DRAIN_DELAY_MS", {
+			default: KERNEL_DEFAULTS.preDrainDelayMs,
+			min: 0
+		})),
+		drainTimeoutMs: _btravstack_config.Config.pinned(options.drainTimeoutMs, _btravstack_config.Config.integer("DRAIN_TIMEOUT_MS", {
+			default: KERNEL_DEFAULTS.drainTimeoutMs,
+			min: 0
+		}))
+	})["~standard"].validate(env);
+	return result.issues === void 0 ? (0, unthrown.Ok)(result.value) : (0, unthrown.Err)(new RuntimeStartFailed({
+		runtime: "kernel",
+		cause: new _btravstack_config.ConfigInvalid({
+			port: "kernel",
+			issues: result.issues
+		})
+	}));
+};
 const start = (module, options = {}) => {
 	const clock = options.clock ?? systemClock;
 	const env = options.env ?? process.env;
@@ -326,8 +413,8 @@ const start = (module, options = {}) => {
 	const shutdown = Promise.withResolvers();
 	const teardownErrors = [];
 	const startedAt = clock.now();
-	const preDrainDelayMs = options.preDrainDelayMs ?? 5e3;
-	const drainTimeoutMs = options.drainTimeoutMs ?? 2e4;
+	const kernelConfig = readKernelConfig(options, env);
+	const { preDrainDelayMs, drainTimeoutMs } = kernelConfig.getOrElse(() => KERNEL_DEFAULTS);
 	const skipDrain = new AbortController();
 	let shutdownRequestedAt = startedAt;
 	let shutdownRequested = false;
@@ -359,24 +446,18 @@ const start = (module, options = {}) => {
 		requestShutdown("uncaught");
 	});
 	let disposeProbes = () => {};
+	let healthChecks = [];
+	const health = () => runHealthChecks(healthChecks);
 	const probeBound = Promise.withResolvers();
 	const runtimePublished = Promise.withResolvers();
 	emit({ type: "building" });
-	const probesOptions = options.probes === void 0 ? _btravstack_config.Config.port("PROBE_PORT", { default: 9e3 }).parse(env["PROBE_PORT"]).map((port) => ({ port })).mapErrCases((matcher) => matcher.with(unthrown.P.tag("ConfigFieldInvalid"), ({ reason }) => new RuntimeStartFailed({
-		runtime: "probes",
-		cause: new _btravstack_config.ConfigInvalid({
-			port: "probes",
-			issues: [{
-				message: reason,
-				path: ["PROBE_PORT"]
-			}]
-		})
-	}))) : (0, unthrown.Ok)(options.probes);
+	const probesOptions = kernelConfig.map(({ probePort }) => options.probes === false ? false : { port: probePort });
 	if (options.probes === false) probeBound.resolve(void 0);
 	const probesStarted = probesOptions.toAsync().flatMap((probes) => probes === false ? (0, unthrown.OkAsync)() : startProbeServer({
 		port: probes.port,
 		live,
-		ready
+		ready,
+		health
 	}).tap((server) => {
 		probeBoundPort = server.port;
 		probeBound.resolve(server.port);
@@ -444,6 +525,7 @@ const start = (module, options = {}) => {
 			tracker.advanceTo("starting");
 			const runtime = ctx.get(RuntimePort);
 			runtimeName = runtime.name;
+			healthChecks = ctx.get(HealthChecks);
 			const runtimeCtx = ctx;
 			const unit = options.unit;
 			const run = (meta, work) => registry.run(meta, (signal) => {
@@ -554,6 +636,9 @@ const runMain = async (module, options = {}, exit = (code) => {
 	await awaitExit(start(module, options), exit);
 };
 //#endregion
+exports.HealthCheckFailed = HealthCheckFailed;
+exports.HealthChecks = HealthChecks;
+exports.Instrumentations = Instrumentations;
 exports.LEVELS = LEVELS;
 exports.Logger = Logger;
 exports.Meter = Meter;
@@ -563,6 +648,7 @@ exports.SPAN_STATUS = SPAN_STATUS;
 exports.Tracer = Tracer;
 exports.currentUnit = currentUnit;
 exports.releasedBy = releasedBy;
+exports.runHealthChecks = runHealthChecks;
 exports.runMain = runMain;
 exports.start = start;
 exports.stderrSink = stderrSink;

package/dist/index.d.cts

@@ -1,6 +1,85 @@
 import { AsyncResult, Result } from "unthrown";
 import { AnyPort, Context, Module, PortClass, Scope, ServiceOf } from "@btravstack/di";
 import { Env, Environment } from "@btravstack/config";
+//#region src/instrumentation.d.ts
+/**
+ * One package's offer of an OpenTelemetry instrumentation.
+ *
+ * **Async, and answers `undefined` rather than failing, because the package
+ * supplying the instrumentation is an OPTIONAL peer.** A starter cannot know at
+ * composition time whether the consumer installed it, so it contributes the
+ * ATTEMPT and the collector drops what did not load — which is what lets
+ * `@btravstack/prisma` declare engine tracing without making every consumer
+ * install `@prisma/instrumentation`. A contributor that wants to say why its
+ * load answered nothing logs that itself; it is the one that knows.
+ *
+ * The instrumentation is `unknown` on purpose. Naming OpenTelemetry's
+ * `Instrumentation` would put the vendor in the package every other one peers
+ * on — the same reason `Tracer` and `Meter` are declared as narrowings rather
+ * than as OTel's own types. The collector
+ * (`@btravstack/observability/otel`) is where the vendor is already a
+ * dependency, so that is where the cast belongs.
+ */
+type InstrumentationLoader = () => Promise<unknown>;
+declare const Instrumentations_base: import("@btravstack/di").ManyPortClass<"Instrumentations">;
+/**
+ * The set port a package contributes its instrumentation to.
+ *
+ * Nothing collects it unless an OTel SDK is composed, which is the point: a
+ * starter DECLARES what it can instrument, and composing
+ * `@btravstack/observability/otel` is what turns the declarations on. A graph
+ * without it registers nothing and pays nothing — the Spring Boot starter
+ * shape, in one port.
+ */
+declare class Instrumentations extends Instrumentations_base<InstrumentationLoader> {}
+//#endregion
+//#region src/health.d.ts
+declare const HealthCheckFailed_base: import("unthrown").TaggedErrorConstructor<"HealthCheckFailed">;
+/**
+ * A component could not answer for itself. Modeled rather than thrown, because
+ * a health check that throws is a bug in the check; one that fails is the news
+ * `/healthz` exists to carry.
+ */
+declare class HealthCheckFailed extends HealthCheckFailed_base<{
+  readonly reason: string;
+}> {}
+/** One contribution: what to call the component, and how to ask it. */
+type HealthCheck = {
+  readonly name: string;
+  readonly check: () => AsyncResult<void, HealthCheckFailed>;
+};
+declare const HealthChecks_base: import("@btravstack/di").ManyPortClass<"HealthChecks">;
+/**
+ * The set port every starter contributes to and the kernel reads whole.
+ *
+ * A set port rather than a registry the kernel hands out: a starter DECLARES
+ * its check the same way it declares anything else, and a starter an
+ * application never composed contributes nothing — no registration call to
+ * forget, and no order to get wrong.
+ */
+declare class HealthChecks extends HealthChecks_base<HealthCheck> {}
+type ComponentHealth = {
+  readonly name: string;
+  readonly status: "healthy" | "unhealthy";
+  /** Present only when the component is unhealthy. */
+  readonly reason?: string;
+};
+type HealthReport = {
+  readonly status: "healthy" | "unhealthy";
+  readonly components: readonly ComponentHealth[];
+};
+/**
+ * Runs every check and folds the results into one report — the whole app is
+ * unhealthy if any single component is.
+ *
+ * Each check's failure is recovered into a component line BEFORE `allAsync`
+ * sees it, so a failing dependency cannot short-circuit the others: a report
+ * naming one component is worth less than one naming all of them. What
+ * survives to `allAsync`'s error channel is a `Defect` alone — a check that
+ * threw rather than answered, which is a bug in the check.
+ */
+declare const runHealthChecks: (checks: readonly HealthCheck[]) => AsyncResult<HealthReport, never>;
+//#endregion
 //#region src/clock.d.ts
 type Clock = {
   readonly now: () => number;
@@ -379,7 +458,21 @@ type StartOptions<UnitX = never, UnitNeeds = never> = {
   readonly probes?: {
     readonly port: number;
   } | false;
+  /**
+   * How long readiness stays false before the runtime is told to stop
+   * accepting. Unset, it is bound from `PRE_DRAIN_DELAY_MS` in `env` (default
+   * `5_000`) — the window that covers Kubernetes' eventually-consistent
+   * endpoint removal, which is a property of the cluster rather than of the
+   * code, so a deployment must be able to set it.
+   */
   readonly preDrainDelayMs?: number;
+  /**
+   * How long in-flight work gets before it is aborted and reported
+   * `abandoned`. Unset, it is bound from `DRAIN_TIMEOUT_MS` in `env` (default
+   * `20_000`). Keep it under the pod's `terminationGracePeriodSeconds`, which
+   * is the reason this one belongs in the environment: the two are set
+   * together, in the same manifest.
+   */
   readonly drainTimeoutMs?: number;
   readonly onEvent?: EventSink;
 };
@@ -455,4 +548,4 @@ declare const start: <X, E, UnitX = never, UnitNeeds = never>(module: Module<X,
  */
 declare const runMain: <X, E, UnitX = never, UnitNeeds = never>(module: Module<X, E, Scope | Env> & StartGate<X, UnitNeeds>, options?: StartOptions<UnitX, UnitNeeds>, exit?: (code: number) => void) => Promise<void>;
 //#endregion
-export { type Attributes, type Clock, type Counter, type DrainReport, type EventSink, type ExitReport, type Histogram, type KernelEvent, LEVELS, type Level, Logger, type LoggerService, Meter, type MeterService, type Phase, type RunUnit, type RunningApp, type Runtime, type RuntimeHost, type RuntimeInfoOf, RuntimePort, RuntimeStartFailed, SPAN_STATUS, type Serving, type Span, type SpanStatusCode, type StartGate, type StartOptions, type TeardownError, Tracer, type TracerService, type UnitMeta, type UnitRecord, type UnitRegistry, type UnitWork, currentUnit, releasedBy, runMain, start, stderrSink, systemClock };
+export { type Attributes, type Clock, type ComponentHealth, type Counter, type DrainReport, type EventSink, type ExitReport, type HealthCheck, HealthCheckFailed, HealthChecks, type HealthReport, type Histogram, type InstrumentationLoader, Instrumentations, type KernelEvent, LEVELS, type Level, Logger, type LoggerService, Meter, type MeterService, type Phase, type RunUnit, type RunningApp, type Runtime, type RuntimeHost, type RuntimeInfoOf, RuntimePort, RuntimeStartFailed, SPAN_STATUS, type Serving, type Span, type SpanStatusCode, type StartGate, type StartOptions, type TeardownError, Tracer, type TracerService, type UnitMeta, type UnitRecord, type UnitRegistry, type UnitWork, currentUnit, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock };

package/dist/index.d.mts

@@ -1,6 +1,85 @@
-import { AsyncResult, Result } from "unthrown";
 import { AnyPort, Context, Module, PortClass, Scope, ServiceOf } from "@btravstack/di";
+import { AsyncResult, Result } from "unthrown";
 import { Env, Environment } from "@btravstack/config";
+//#region src/instrumentation.d.ts
+/**
+ * One package's offer of an OpenTelemetry instrumentation.
+ *
+ * **Async, and answers `undefined` rather than failing, because the package
+ * supplying the instrumentation is an OPTIONAL peer.** A starter cannot know at
+ * composition time whether the consumer installed it, so it contributes the
+ * ATTEMPT and the collector drops what did not load — which is what lets
+ * `@btravstack/prisma` declare engine tracing without making every consumer
+ * install `@prisma/instrumentation`. A contributor that wants to say why its
+ * load answered nothing logs that itself; it is the one that knows.
+ *
+ * The instrumentation is `unknown` on purpose. Naming OpenTelemetry's
+ * `Instrumentation` would put the vendor in the package every other one peers
+ * on — the same reason `Tracer` and `Meter` are declared as narrowings rather
+ * than as OTel's own types. The collector
+ * (`@btravstack/observability/otel`) is where the vendor is already a
+ * dependency, so that is where the cast belongs.
+ */
+type InstrumentationLoader = () => Promise<unknown>;
+declare const Instrumentations_base: import("@btravstack/di").ManyPortClass<"Instrumentations">;
+/**
+ * The set port a package contributes its instrumentation to.
+ *
+ * Nothing collects it unless an OTel SDK is composed, which is the point: a
+ * starter DECLARES what it can instrument, and composing
+ * `@btravstack/observability/otel` is what turns the declarations on. A graph
+ * without it registers nothing and pays nothing — the Spring Boot starter
+ * shape, in one port.
+ */
+declare class Instrumentations extends Instrumentations_base<InstrumentationLoader> {}
+//#endregion
+//#region src/health.d.ts
+declare const HealthCheckFailed_base: import("unthrown").TaggedErrorConstructor<"HealthCheckFailed">;
+/**
+ * A component could not answer for itself. Modeled rather than thrown, because
+ * a health check that throws is a bug in the check; one that fails is the news
+ * `/healthz` exists to carry.
+ */
+declare class HealthCheckFailed extends HealthCheckFailed_base<{
+  readonly reason: string;
+}> {}
+/** One contribution: what to call the component, and how to ask it. */
+type HealthCheck = {
+  readonly name: string;
+  readonly check: () => AsyncResult<void, HealthCheckFailed>;
+};
+declare const HealthChecks_base: import("@btravstack/di").ManyPortClass<"HealthChecks">;
+/**
+ * The set port every starter contributes to and the kernel reads whole.
+ *
+ * A set port rather than a registry the kernel hands out: a starter DECLARES
+ * its check the same way it declares anything else, and a starter an
+ * application never composed contributes nothing — no registration call to
+ * forget, and no order to get wrong.
+ */
+declare class HealthChecks extends HealthChecks_base<HealthCheck> {}
+type ComponentHealth = {
+  readonly name: string;
+  readonly status: "healthy" | "unhealthy";
+  /** Present only when the component is unhealthy. */
+  readonly reason?: string;
+};
+type HealthReport = {
+  readonly status: "healthy" | "unhealthy";
+  readonly components: readonly ComponentHealth[];
+};
+/**
+ * Runs every check and folds the results into one report — the whole app is
+ * unhealthy if any single component is.
+ *
+ * Each check's failure is recovered into a component line BEFORE `allAsync`
+ * sees it, so a failing dependency cannot short-circuit the others: a report
+ * naming one component is worth less than one naming all of them. What
+ * survives to `allAsync`'s error channel is a `Defect` alone — a check that
+ * threw rather than answered, which is a bug in the check.
+ */
+declare const runHealthChecks: (checks: readonly HealthCheck[]) => AsyncResult<HealthReport, never>;
+//#endregion
 //#region src/clock.d.ts
 type Clock = {
   readonly now: () => number;
@@ -379,7 +458,21 @@ type StartOptions<UnitX = never, UnitNeeds = never> = {
   readonly probes?: {
     readonly port: number;
   } | false;
+  /**
+   * How long readiness stays false before the runtime is told to stop
+   * accepting. Unset, it is bound from `PRE_DRAIN_DELAY_MS` in `env` (default
+   * `5_000`) — the window that covers Kubernetes' eventually-consistent
+   * endpoint removal, which is a property of the cluster rather than of the
+   * code, so a deployment must be able to set it.
+   */
   readonly preDrainDelayMs?: number;
+  /**
+   * How long in-flight work gets before it is aborted and reported
+   * `abandoned`. Unset, it is bound from `DRAIN_TIMEOUT_MS` in `env` (default
+   * `20_000`). Keep it under the pod's `terminationGracePeriodSeconds`, which
+   * is the reason this one belongs in the environment: the two are set
+   * together, in the same manifest.
+   */
   readonly drainTimeoutMs?: number;
   readonly onEvent?: EventSink;
 };
@@ -455,4 +548,4 @@ declare const start: <X, E, UnitX = never, UnitNeeds = never>(module: Module<X,
  */
 declare const runMain: <X, E, UnitX = never, UnitNeeds = never>(module: Module<X, E, Scope | Env> & StartGate<X, UnitNeeds>, options?: StartOptions<UnitX, UnitNeeds>, exit?: (code: number) => void) => Promise<void>;
 //#endregion
-export { type Attributes, type Clock, type Counter, type DrainReport, type EventSink, type ExitReport, type Histogram, type KernelEvent, LEVELS, type Level, Logger, type LoggerService, Meter, type MeterService, type Phase, type RunUnit, type RunningApp, type Runtime, type RuntimeHost, type RuntimeInfoOf, RuntimePort, RuntimeStartFailed, SPAN_STATUS, type Serving, type Span, type SpanStatusCode, type StartGate, type StartOptions, type TeardownError, Tracer, type TracerService, type UnitMeta, type UnitRecord, type UnitRegistry, type UnitWork, currentUnit, releasedBy, runMain, start, stderrSink, systemClock };
+export { type Attributes, type Clock, type ComponentHealth, type Counter, type DrainReport, type EventSink, type ExitReport, type HealthCheck, HealthCheckFailed, HealthChecks, type HealthReport, type Histogram, type InstrumentationLoader, Instrumentations, type KernelEvent, LEVELS, type Level, Logger, type LoggerService, Meter, type MeterService, type Phase, type RunUnit, type RunningApp, type Runtime, type RuntimeHost, type RuntimeInfoOf, RuntimePort, RuntimeStartFailed, SPAN_STATUS, type Serving, type Span, type SpanStatusCode, type StartGate, type StartOptions, type TeardownError, Tracer, type TracerService, type UnitMeta, type UnitRecord, type UnitRegistry, type UnitWork, currentUnit, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock };

package/dist/index.mjs

@@ -1,8 +1,58 @@
-import { Err, Ok, OkAsync, P, TaggedError, fromSafePromise } from "unthrown";
 import { Module, Port, Provider } from "@btravstack/di";
+import { Err, Ok, OkAsync, P, TaggedError, allAsync, fromSafePromise } from "unthrown";
 import { Config, ConfigInvalid, Env } from "@btravstack/config";
 import { createServer } from "node:http";
 import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/instrumentation.ts
+/**
+* The set port a package contributes its instrumentation to.
+*
+* Nothing collects it unless an OTel SDK is composed, which is the point: a
+* starter DECLARES what it can instrument, and composing
+* `@btravstack/observability/otel` is what turns the declarations on. A graph
+* without it registers nothing and pays nothing — the Spring Boot starter
+* shape, in one port.
+*/
+var Instrumentations = class extends Port.many("Instrumentations") {};
+//#endregion
+//#region src/health.ts
+/**
+* A component could not answer for itself. Modeled rather than thrown, because
+* a health check that throws is a bug in the check; one that fails is the news
+* `/healthz` exists to carry.
+*/
+var HealthCheckFailed = class extends TaggedError("HealthCheckFailed") {};
+/**
+* The set port every starter contributes to and the kernel reads whole.
+*
+* A set port rather than a registry the kernel hands out: a starter DECLARES
+* its check the same way it declares anything else, and a starter an
+* application never composed contributes nothing — no registration call to
+* forget, and no order to get wrong.
+*/
+var HealthChecks = class extends Port.many("HealthChecks") {};
+/**
+* Runs every check and folds the results into one report — the whole app is
+* unhealthy if any single component is.
+*
+* Each check's failure is recovered into a component line BEFORE `allAsync`
+* sees it, so a failing dependency cannot short-circuit the others: a report
+* naming one component is worth less than one naming all of them. What
+* survives to `allAsync`'s error channel is a `Defect` alone — a check that
+* threw rather than answered, which is a bug in the check.
+*/
+const runHealthChecks = (checks) => allAsync(checks.map((health) => health.check().map(() => ({
+	name: health.name,
+	status: "healthy"
+})).recoverErrCases((matcher) => matcher.with(P.tag("HealthCheckFailed"), (error) => ({
+	name: health.name,
+	status: "unhealthy",
+	reason: error.reason
+}))))).map((components) => ({
+	status: components.every((c) => c.status === "healthy") ? "healthy" : "unhealthy",
+	components
+}));
+//#endregion
 //#region src/clock.ts
 const systemClock = {
 	now: () => Date.now(),
@@ -184,6 +234,12 @@ const startProbeServer = (args) => fromSafePromise(new Promise((resolve) => {
 			respond(response, args.ready(), "ready");
 			return;
 		}
+		if (request.url === "/healthz") {
+			args.health().map((report) => {
+				response.writeHead(report.status === "healthy" ? 200 : 503, { "content-type": "application/json" }).end(JSON.stringify(report));
+			});
+			return;
+		}
 		response.writeHead(404).end();
 	});
 	const onBindError = (cause) => {
@@ -304,6 +360,37 @@ const createUnitRegistry = () => {
 //#endregion
 //#region src/start.ts
 const providesEnv = (module) => module.provides.some((provider) => provider.port.portId === Env.portId) || module.imports.some(providesEnv);
+/**
+* What the kernel reads from the environment for itself. Each field is pinned
+* by the matching `StartOptions` field — explicit beats environment beats
+* default, per field, exactly as a starter's own configuration is.
+*/
+const KERNEL_DEFAULTS = {
+	probePort: 9e3,
+	preDrainDelayMs: 5e3,
+	drainTimeoutMs: 2e4
+};
+const readKernelConfig = (options, env) => {
+	const probePort = options.probes === void 0 ? void 0 : options.probes === false ? KERNEL_DEFAULTS.probePort : options.probes.port;
+	const result = Config.object({
+		probePort: Config.pinned(probePort, Config.port("PROBE_PORT", { default: KERNEL_DEFAULTS.probePort })),
+		preDrainDelayMs: Config.pinned(options.preDrainDelayMs, Config.integer("PRE_DRAIN_DELAY_MS", {
+			default: KERNEL_DEFAULTS.preDrainDelayMs,
+			min: 0
+		})),
+		drainTimeoutMs: Config.pinned(options.drainTimeoutMs, Config.integer("DRAIN_TIMEOUT_MS", {
+			default: KERNEL_DEFAULTS.drainTimeoutMs,
+			min: 0
+		}))
+	})["~standard"].validate(env);
+	return result.issues === void 0 ? Ok(result.value) : Err(new RuntimeStartFailed({
+		runtime: "kernel",
+		cause: new ConfigInvalid({
+			port: "kernel",
+			issues: result.issues
+		})
+	}));
+};
 const start = (module, options = {}) => {
 	const clock = options.clock ?? systemClock;
 	const env = options.env ?? process.env;
@@ -325,8 +412,8 @@ const start = (module, options = {}) => {
 	const shutdown = Promise.withResolvers();
 	const teardownErrors = [];
 	const startedAt = clock.now();
-	const preDrainDelayMs = options.preDrainDelayMs ?? 5e3;
-	const drainTimeoutMs = options.drainTimeoutMs ?? 2e4;
+	const kernelConfig = readKernelConfig(options, env);
+	const { preDrainDelayMs, drainTimeoutMs } = kernelConfig.getOrElse(() => KERNEL_DEFAULTS);
 	const skipDrain = new AbortController();
 	let shutdownRequestedAt = startedAt;
 	let shutdownRequested = false;
@@ -358,24 +445,18 @@ const start = (module, options = {}) => {
 		requestShutdown("uncaught");
 	});
 	let disposeProbes = () => {};
+	let healthChecks = [];
+	const health = () => runHealthChecks(healthChecks);
 	const probeBound = Promise.withResolvers();
 	const runtimePublished = Promise.withResolvers();
 	emit({ type: "building" });
-	const probesOptions = options.probes === void 0 ? Config.port("PROBE_PORT", { default: 9e3 }).parse(env["PROBE_PORT"]).map((port) => ({ port })).mapErrCases((matcher) => matcher.with(P.tag("ConfigFieldInvalid"), ({ reason }) => new RuntimeStartFailed({
-		runtime: "probes",
-		cause: new ConfigInvalid({
-			port: "probes",
-			issues: [{
-				message: reason,
-				path: ["PROBE_PORT"]
-			}]
-		})
-	}))) : Ok(options.probes);
+	const probesOptions = kernelConfig.map(({ probePort }) => options.probes === false ? false : { port: probePort });
 	if (options.probes === false) probeBound.resolve(void 0);
 	const probesStarted = probesOptions.toAsync().flatMap((probes) => probes === false ? OkAsync() : startProbeServer({
 		port: probes.port,
 		live,
-		ready
+		ready,
+		health
 	}).tap((server) => {
 		probeBoundPort = server.port;
 		probeBound.resolve(server.port);
@@ -443,6 +524,7 @@ const start = (module, options = {}) => {
 			tracker.advanceTo("starting");
 			const runtime = ctx.get(RuntimePort);
 			runtimeName = runtime.name;
+			healthChecks = ctx.get(HealthChecks);
 			const runtimeCtx = ctx;
 			const unit = options.unit;
 			const run = (meta, work) => registry.run(meta, (signal) => {
@@ -553,4 +635,4 @@ const runMain = async (module, options = {}, exit = (code) => {
 	await awaitExit(start(module, options), exit);
 };
 //#endregion
-export { LEVELS, Logger, Meter, RuntimePort, RuntimeStartFailed, SPAN_STATUS, Tracer, currentUnit, releasedBy, runMain, start, stderrSink, systemClock };
+export { HealthCheckFailed, HealthChecks, Instrumentations, LEVELS, Logger, Meter, RuntimePort, RuntimeStartFailed, SPAN_STATUS, Tracer, currentUnit, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/core",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "The application kernel: boot a di module into a running process, and stop it without losing work",
   "keywords": [
     "application",
@@ -53,13 +53,13 @@
     "typescript": "7.0.2",
     "unthrown": "5.7.0",
     "vitest": "4.1.11",
-    "@btravstack/config": "0.5.0",
-    "@btravstack/di": "0.5.0"
+    "@btravstack/config": "0.7.0",
+    "@btravstack/di": "0.7.0"
   },
   "peerDependencies": {
     "unthrown": "^5.0.0",
-    "@btravstack/config": "^0.5.0",
-    "@btravstack/di": "^0.5.0"
+    "@btravstack/config": "^0.7.0",
+    "@btravstack/di": "^0.7.0"
   },
   "engines": {
     "node": ">=22"