@btravstack/core 0.14.0 → 0.15.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AsyncResult, Result } from "unthrown";
+import { AsyncResult, FailureView, Result } from "unthrown";
 import { AnyPort, Context, DependencyGate, Module, PortClass, PortInstance, Scope, SeedEntry, ServiceOf } from "@btravstack/di";
 import { Env, Environment } from "@btravstack/config";
 //#region src/instrumentation.d.ts
@@ -47,6 +47,16 @@ export declare class HealthCheckFailed extends HealthCheckFailed_base<{
 type HealthCheck = {
   readonly name: string;
   readonly check: () => AsyncResult<void, HealthCheckFailed>;
+  /**
+   * How long this component gets to answer, overriding the fold's own default.
+   *
+   * It is on the CONTRIBUTION because only the contributor knows: a `SELECT 1`
+   * over a warm pool and an SMTP relay's greeting are two orders of magnitude
+   * apart, and one number for both is either a false unhealthy or a probe that
+   * outlives the orchestrator's patience. A component with nothing to say about
+   * its own latency omits it.
+   */
+  readonly timeoutMs?: number;
 };
 declare const HealthChecks_base: import("@btravstack/di").ManyPortClass<"HealthChecks">;
 /**
@@ -68,6 +78,10 @@ type HealthReport = {
   readonly status: "healthy" | "unhealthy";
   readonly components: readonly ComponentHealth[];
 };
+type HealthOptions = {
+  /** Per check, not for the fold: the checks run concurrently. Default {@link DEFAULT_HEALTH_TIMEOUT_MS}. */
+  readonly timeoutMs?: number;
+};
 /**
  * Runs every check and folds the results into one report — the whole app is
  * unhealthy if any single component is.
@@ -80,8 +94,15 @@ type HealthReport = {
  * a defecting `AsyncResult` alike are recovered into an unhealthy line —
  * escaped, the first would reach the kernel's own `uncaughtException` handler
  * and the second would leave `/healthz` hanging with nothing written.
+ *
+ * **A check that never settles is the third case, and it needed a deadline
+ * rather than a recovery.** Neither recovery above can see one: there is no
+ * error and no defect, only silence, so `/healthz` held a socket open per hit
+ * while kubelet timed out against a report that named nothing. Each check now
+ * races {@link HealthOptions.timeoutMs}, and the component that hung is named
+ * in the report like any other unhealthy one.
  */
-export declare const runHealthChecks: (checks: readonly HealthCheck[]) => AsyncResult<HealthReport, never>;
+export declare const runHealthChecks: (checks: readonly HealthCheck[], options?: HealthOptions) => AsyncResult<HealthReport, never>;
 //#endregion
 //#region src/observability.d.ts
 /**
@@ -292,6 +313,21 @@ export declare const noObserver: () => Settle;
  * twice and doubles a failure count.
  */
 export declare const observe: (observers: readonly ((operation: Operation) => Settle)[], operation: Operation) => Settle;
+/**
+ * {@link observe}, wrapped around one call: every observer is started before
+ * `call` runs and settled from whichever channel it comes back on — `ok` on
+ * success, `error` carrying the `Err` or the defect as `cause` otherwise. The
+ * wrapper is transparent to the `Result`: whatever `call` answers is what the
+ * caller receives.
+ *
+ * `settled` replaces either default where a starter has more to say: `ok`
+ * receives the value (a cache reports a hit or a miss), `failure` the
+ * `FailureView` (a store reports a missing object as an ordinary answer).
+ */
+export declare const observed: <T, E>(observers: readonly ((operation: Operation) => Settle)[], operation: Operation, call: () => AsyncResult<T, E>, settled?: {
+  readonly ok?: (value: T) => Settled;
+  readonly failure?: (failure: FailureView<E, T>) => Settled;
+}) => AsyncResult<T, E>;
 //#endregion
 //#region src/clock.d.ts
 type Clock = {
@@ -425,6 +461,33 @@ type Serving<Info = never> = {
   readonly drain: (signal: AbortSignal) => AsyncResult<void, never>;
   readonly stop: () => AsyncResult<void, never>;
   readonly info?: Info;
+  /**
+   * Settles when the runtime has stopped serving **on its own account** —
+   * nobody asked it to, and it is not coming back.
+   *
+   * Without this a runtime has no way to say so, and the kernel's lifecycle
+   * only ever moves on a signal or a `stop()` call. So a Temporal worker whose
+   * `run()` rejected mid-flight, or an AMQP consumer the server cancelled and
+   * nothing re-subscribed, left the process alive and `/readyz` answering
+   * `200` — a pod in a Service's endpoints, consuming nothing. The orchestrator
+   * has no way to learn that on its own: liveness answers from `building`
+   * onward, and readiness is the lifecycle's, not the transport's.
+   *
+   * The kernel races it against its own shutdown deferred and reports
+   * `reason: "runtimeStopped"`, which `runMain` exits `1` for — a restart,
+   * which is the right answer to a transport that has given up.
+   *
+   * **Optional, and a runtime that cannot know omits it.** An HTTP server that
+   * is listening is serving; there is no third state for it to report, and a
+   * field it had to write `OkAsync()` into would be a promise it could not
+   * keep. A `never`-settling `AsyncResult` is the other honest spelling for a
+   * runtime that could report this and has nothing to say yet.
+   *
+   * It says nothing about WHY. The runtime that knows writes that line itself,
+   * through `Observers` or its own diagnostics; this channel exists so the
+   * process ends, not so the reason travels.
+   */
+  readonly stopped?: () => AsyncResult<void, never>;
 };
 type Runtime<Resolves extends AnyPort = never, Info = never> = {
   readonly name: string;
@@ -512,7 +575,28 @@ type DrainReport = {
    * reporting, where `inFlightAtStart - abandoned` can go negative.
    */
   readonly completed: number;
-  /** Units still open at the deadline. The exit-code decision reads this. */
+  /**
+   * Units still open at the deadline. The exit-code decision reads this.
+   *
+   * **It means "no longer AWAITED", not "did not finish".** The kernel stops
+   * waiting and aborts each unit's signal; it cannot cancel work, and the
+   * transport underneath keeps running on its own clock. An abandoned AMQP
+   * delivery usually goes on to be acked, and an abandoned Temporal activity
+   * goes on to complete — after this report said they did not.
+   *
+   * **The consequence, stated because nothing else states it: the process may
+   * not end by itself.** `runMain` sets an exit code and deliberately never
+   * calls `process.exit()`, so the process ends when the event loop empties —
+   * and a transport still winding down is holding it open. Nothing here
+   * terminates it.
+   *
+   * Under a Kubernetes-initiated shutdown that ends at
+   * `terminationGracePeriodSeconds`, with SIGKILL, so exit `2` is what the
+   * report SAYS rather than what the orchestrator observes. Outside that
+   * lifecycle there is no SIGKILL: the process simply stays alive until the
+   * transport is done. `kubectl logs --previous` carries the report either
+   * way, which is what it is for.
+   */
   readonly abandoned: number;
 };
 //#endregion
@@ -547,6 +631,18 @@ type KernelEvent = {
 } | {
   readonly type: "drained";
   readonly report: DrainReport;
+} | {
+  /**
+   * The kernel stopped WAITING for a phase that has no deadline of its own,
+   * and reported anyway. Without it a stop that ran long and a stop that
+   * finished are the same two lines on stderr (`stopping`, `exited`), which
+   * is the silence `ExitReport.abandonedAt` exists to end.
+   */
+  readonly type: "stoppedWaiting";
+  /** `"stop"` for `Serving.stop` and the finalisers, `"build"` for a graph that never served. */
+  readonly phase: "build" | "stop";
+  /** The deadline that expired, or `undefined` when a second signal cut the wait short. */
+  readonly afterMs: number | undefined;
 } | {
   readonly type: "stopping";
 } | {
@@ -575,22 +671,41 @@ type ExitReport = {
   readonly drain: DrainReport | undefined;
   readonly teardownErrors: readonly TeardownError[];
   readonly uptimeMs: number;
+  /**
+   * Set when the kernel stopped WAITING for a phase that has no deadline of its
+   * own — `"stop"` for a `Serving.stop` or a finaliser still running at
+   * `stopTimeoutMs`, `"build"` for a graph abandoned before it ever served.
+   *
+   * It is "stopped waiting", not "cancelled": nothing here can cancel a
+   * finaliser, so a wedged one can still hold the event loop past this report
+   * and end in SIGKILL. What the field buys is that the report EXISTS and says
+   * which phase ran long — where the alternative was a process stuck in
+   * `stopping` with no event, no code and no exit report at all.
+   */
+  readonly abandonedAt?: "build" | "stop";
 };
 type StartOptions = {
   /**
    * The environment the graph is configured from, provided to it as the `Env`
-   * port and read for the kernel's own `PROBE_PORT`. Defaults to
-   * `process.env`.
+   * port and read for the kernel's own variables. Defaults to `process.env`.
    */
   readonly env?: Environment;
   readonly clock?: Clock;
   readonly signals?: boolean;
   /**
-   * The probe server's port. Unset, it is bound from `PROBE_PORT` in `env`
-   * (default `9000`); `false` disables the probe server.
+   * The probe server's port and interface. Unset, they are bound from
+   * `PROBE_PORT` (default `9000`) and `PROBE_HOST` (default `0.0.0.0`) in
+   * `env`; `false` disables the probe server and reads neither.
+   *
+   * `0.0.0.0` matches `HOST`'s own default for `HOST`'s own reason: a kubelet
+   * `httpGet` probe connects over the POD IP, so the loopback-only bind this
+   * used to hardcode could not answer the probe shape every manifest reaches
+   * for first. Pin `host: "127.0.0.1"` where the port is shared with something
+   * else on the host, and probe it with `exec` from inside the container.
    */
   readonly probes?: {
     readonly port: number;
+    readonly host?: string;
   } | false;
   /**
    * How long readiness stays false before the runtime is told to stop
@@ -608,6 +723,21 @@ type StartOptions = {
    * together, in the same manifest.
    */
   readonly drainTimeoutMs?: number;
+  /**
+   * How long the kernel waits for `Serving.stop` and the application scope's
+   * finalisers together before it stops waiting and reports
+   * `ExitReport.abandonedAt: "stop"`. Unset, it is bound from
+   * `STOP_TIMEOUT_MS` in `env` (default `5_000`).
+   *
+   * It exists because beat 3's deadline covers in-flight WORK and nothing
+   * covered the teardown: a `release` that never settles — a socket to a host
+   * that stopped answering — left the phase at `stopping` with no exit report,
+   * which is the one artefact the lifecycle exists to produce. The three
+   * timings are cumulative against the pod's
+   * `terminationGracePeriodSeconds`, so the defaults sum to 30 s exactly
+   * (`5_000 + 20_000 + 5_000`): raise one and raise the grace period with it.
+   */
+  readonly stopTimeoutMs?: number;
   readonly onEvent?: EventSink;
 };
 type RunningApp<E, Info = never> = {
@@ -690,6 +820,7 @@ export declare const start: <X, E, N>(module: Module<X, E, N> & StartGate<X, N>,
  * | a configuration port that could not be bound (`ConfigInvalid`, `PROBE_PORT` included) | `78` |
  * | drained with work abandoned | `2` |
  * | exited with teardown errors | `2` |
+ * | stopped waiting for the teardown or a build (`ExitReport.abandonedAt`) | `2` |
  * | stopped by an uncaught exception or unhandled rejection | `70` |
  * | a defect | `70` |
  *

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { AnyPort, Context, DependencyGate, Module, PortClass, PortInstance, Scope, SeedEntry, ServiceOf } from "@btravstack/di";
-import { AsyncResult, Result } from "unthrown";
+import { AsyncResult, FailureView, Result } from "unthrown";
 import { Env, Environment } from "@btravstack/config";
 //#region src/instrumentation.d.ts
 /**
@@ -47,6 +47,16 @@ export declare class HealthCheckFailed extends HealthCheckFailed_base<{
 type HealthCheck = {
   readonly name: string;
   readonly check: () => AsyncResult<void, HealthCheckFailed>;
+  /**
+   * How long this component gets to answer, overriding the fold's own default.
+   *
+   * It is on the CONTRIBUTION because only the contributor knows: a `SELECT 1`
+   * over a warm pool and an SMTP relay's greeting are two orders of magnitude
+   * apart, and one number for both is either a false unhealthy or a probe that
+   * outlives the orchestrator's patience. A component with nothing to say about
+   * its own latency omits it.
+   */
+  readonly timeoutMs?: number;
 };
 declare const HealthChecks_base: import("@btravstack/di").ManyPortClass<"HealthChecks">;
 /**
@@ -68,6 +78,10 @@ type HealthReport = {
   readonly status: "healthy" | "unhealthy";
   readonly components: readonly ComponentHealth[];
 };
+type HealthOptions = {
+  /** Per check, not for the fold: the checks run concurrently. Default {@link DEFAULT_HEALTH_TIMEOUT_MS}. */
+  readonly timeoutMs?: number;
+};
 /**
  * Runs every check and folds the results into one report — the whole app is
  * unhealthy if any single component is.
@@ -80,8 +94,15 @@ type HealthReport = {
  * a defecting `AsyncResult` alike are recovered into an unhealthy line —
  * escaped, the first would reach the kernel's own `uncaughtException` handler
  * and the second would leave `/healthz` hanging with nothing written.
+ *
+ * **A check that never settles is the third case, and it needed a deadline
+ * rather than a recovery.** Neither recovery above can see one: there is no
+ * error and no defect, only silence, so `/healthz` held a socket open per hit
+ * while kubelet timed out against a report that named nothing. Each check now
+ * races {@link HealthOptions.timeoutMs}, and the component that hung is named
+ * in the report like any other unhealthy one.
  */
-export declare const runHealthChecks: (checks: readonly HealthCheck[]) => AsyncResult<HealthReport, never>;
+export declare const runHealthChecks: (checks: readonly HealthCheck[], options?: HealthOptions) => AsyncResult<HealthReport, never>;
 //#endregion
 //#region src/observability.d.ts
 /**
@@ -292,6 +313,21 @@ export declare const noObserver: () => Settle;
  * twice and doubles a failure count.
  */
 export declare const observe: (observers: readonly ((operation: Operation) => Settle)[], operation: Operation) => Settle;
+/**
+ * {@link observe}, wrapped around one call: every observer is started before
+ * `call` runs and settled from whichever channel it comes back on — `ok` on
+ * success, `error` carrying the `Err` or the defect as `cause` otherwise. The
+ * wrapper is transparent to the `Result`: whatever `call` answers is what the
+ * caller receives.
+ *
+ * `settled` replaces either default where a starter has more to say: `ok`
+ * receives the value (a cache reports a hit or a miss), `failure` the
+ * `FailureView` (a store reports a missing object as an ordinary answer).
+ */
+export declare const observed: <T, E>(observers: readonly ((operation: Operation) => Settle)[], operation: Operation, call: () => AsyncResult<T, E>, settled?: {
+  readonly ok?: (value: T) => Settled;
+  readonly failure?: (failure: FailureView<E, T>) => Settled;
+}) => AsyncResult<T, E>;
 //#endregion
 //#region src/clock.d.ts
 type Clock = {
@@ -425,6 +461,33 @@ type Serving<Info = never> = {
   readonly drain: (signal: AbortSignal) => AsyncResult<void, never>;
   readonly stop: () => AsyncResult<void, never>;
   readonly info?: Info;
+  /**
+   * Settles when the runtime has stopped serving **on its own account** —
+   * nobody asked it to, and it is not coming back.
+   *
+   * Without this a runtime has no way to say so, and the kernel's lifecycle
+   * only ever moves on a signal or a `stop()` call. So a Temporal worker whose
+   * `run()` rejected mid-flight, or an AMQP consumer the server cancelled and
+   * nothing re-subscribed, left the process alive and `/readyz` answering
+   * `200` — a pod in a Service's endpoints, consuming nothing. The orchestrator
+   * has no way to learn that on its own: liveness answers from `building`
+   * onward, and readiness is the lifecycle's, not the transport's.
+   *
+   * The kernel races it against its own shutdown deferred and reports
+   * `reason: "runtimeStopped"`, which `runMain` exits `1` for — a restart,
+   * which is the right answer to a transport that has given up.
+   *
+   * **Optional, and a runtime that cannot know omits it.** An HTTP server that
+   * is listening is serving; there is no third state for it to report, and a
+   * field it had to write `OkAsync()` into would be a promise it could not
+   * keep. A `never`-settling `AsyncResult` is the other honest spelling for a
+   * runtime that could report this and has nothing to say yet.
+   *
+   * It says nothing about WHY. The runtime that knows writes that line itself,
+   * through `Observers` or its own diagnostics; this channel exists so the
+   * process ends, not so the reason travels.
+   */
+  readonly stopped?: () => AsyncResult<void, never>;
 };
 type Runtime<Resolves extends AnyPort = never, Info = never> = {
   readonly name: string;
@@ -512,7 +575,28 @@ type DrainReport = {
    * reporting, where `inFlightAtStart - abandoned` can go negative.
    */
   readonly completed: number;
-  /** Units still open at the deadline. The exit-code decision reads this. */
+  /**
+   * Units still open at the deadline. The exit-code decision reads this.
+   *
+   * **It means "no longer AWAITED", not "did not finish".** The kernel stops
+   * waiting and aborts each unit's signal; it cannot cancel work, and the
+   * transport underneath keeps running on its own clock. An abandoned AMQP
+   * delivery usually goes on to be acked, and an abandoned Temporal activity
+   * goes on to complete — after this report said they did not.
+   *
+   * **The consequence, stated because nothing else states it: the process may
+   * not end by itself.** `runMain` sets an exit code and deliberately never
+   * calls `process.exit()`, so the process ends when the event loop empties —
+   * and a transport still winding down is holding it open. Nothing here
+   * terminates it.
+   *
+   * Under a Kubernetes-initiated shutdown that ends at
+   * `terminationGracePeriodSeconds`, with SIGKILL, so exit `2` is what the
+   * report SAYS rather than what the orchestrator observes. Outside that
+   * lifecycle there is no SIGKILL: the process simply stays alive until the
+   * transport is done. `kubectl logs --previous` carries the report either
+   * way, which is what it is for.
+   */
   readonly abandoned: number;
 };
 //#endregion
@@ -547,6 +631,18 @@ type KernelEvent = {
 } | {
   readonly type: "drained";
   readonly report: DrainReport;
+} | {
+  /**
+   * The kernel stopped WAITING for a phase that has no deadline of its own,
+   * and reported anyway. Without it a stop that ran long and a stop that
+   * finished are the same two lines on stderr (`stopping`, `exited`), which
+   * is the silence `ExitReport.abandonedAt` exists to end.
+   */
+  readonly type: "stoppedWaiting";
+  /** `"stop"` for `Serving.stop` and the finalisers, `"build"` for a graph that never served. */
+  readonly phase: "build" | "stop";
+  /** The deadline that expired, or `undefined` when a second signal cut the wait short. */
+  readonly afterMs: number | undefined;
 } | {
   readonly type: "stopping";
 } | {
@@ -575,22 +671,41 @@ type ExitReport = {
   readonly drain: DrainReport | undefined;
   readonly teardownErrors: readonly TeardownError[];
   readonly uptimeMs: number;
+  /**
+   * Set when the kernel stopped WAITING for a phase that has no deadline of its
+   * own — `"stop"` for a `Serving.stop` or a finaliser still running at
+   * `stopTimeoutMs`, `"build"` for a graph abandoned before it ever served.
+   *
+   * It is "stopped waiting", not "cancelled": nothing here can cancel a
+   * finaliser, so a wedged one can still hold the event loop past this report
+   * and end in SIGKILL. What the field buys is that the report EXISTS and says
+   * which phase ran long — where the alternative was a process stuck in
+   * `stopping` with no event, no code and no exit report at all.
+   */
+  readonly abandonedAt?: "build" | "stop";
 };
 type StartOptions = {
   /**
    * The environment the graph is configured from, provided to it as the `Env`
-   * port and read for the kernel's own `PROBE_PORT`. Defaults to
-   * `process.env`.
+   * port and read for the kernel's own variables. Defaults to `process.env`.
    */
   readonly env?: Environment;
   readonly clock?: Clock;
   readonly signals?: boolean;
   /**
-   * The probe server's port. Unset, it is bound from `PROBE_PORT` in `env`
-   * (default `9000`); `false` disables the probe server.
+   * The probe server's port and interface. Unset, they are bound from
+   * `PROBE_PORT` (default `9000`) and `PROBE_HOST` (default `0.0.0.0`) in
+   * `env`; `false` disables the probe server and reads neither.
+   *
+   * `0.0.0.0` matches `HOST`'s own default for `HOST`'s own reason: a kubelet
+   * `httpGet` probe connects over the POD IP, so the loopback-only bind this
+   * used to hardcode could not answer the probe shape every manifest reaches
+   * for first. Pin `host: "127.0.0.1"` where the port is shared with something
+   * else on the host, and probe it with `exec` from inside the container.
    */
   readonly probes?: {
     readonly port: number;
+    readonly host?: string;
   } | false;
   /**
    * How long readiness stays false before the runtime is told to stop
@@ -608,6 +723,21 @@ type StartOptions = {
    * together, in the same manifest.
    */
   readonly drainTimeoutMs?: number;
+  /**
+   * How long the kernel waits for `Serving.stop` and the application scope's
+   * finalisers together before it stops waiting and reports
+   * `ExitReport.abandonedAt: "stop"`. Unset, it is bound from
+   * `STOP_TIMEOUT_MS` in `env` (default `5_000`).
+   *
+   * It exists because beat 3's deadline covers in-flight WORK and nothing
+   * covered the teardown: a `release` that never settles — a socket to a host
+   * that stopped answering — left the phase at `stopping` with no exit report,
+   * which is the one artefact the lifecycle exists to produce. The three
+   * timings are cumulative against the pod's
+   * `terminationGracePeriodSeconds`, so the defaults sum to 30 s exactly
+   * (`5_000 + 20_000 + 5_000`): raise one and raise the grace period with it.
+   */
+  readonly stopTimeoutMs?: number;
   readonly onEvent?: EventSink;
 };
 type RunningApp<E, Info = never> = {
@@ -690,6 +820,7 @@ export declare const start: <X, E, N>(module: Module<X, E, N> & StartGate<X, N>,
  * | a configuration port that could not be bound (`ConfigInvalid`, `PROBE_PORT` included) | `78` |
  * | drained with work abandoned | `2` |
  * | exited with teardown errors | `2` |
+ * | stopped waiting for the teardown or a build (`ExitReport.abandonedAt`) | `2` |
  * | stopped by an uncaught exception or unhandled rejection | `70` |
  * | a defect | `70` |
  *