@btravstack/core 0.13.0 → 0.15.0

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
 /**
@@ -31,7 +31,7 @@ declare const Instrumentations_base: import("@btravstack/di").ManyPortClass<"Ins
  * without it registers nothing and pays nothing — the Spring Boot starter
  * shape, in one port.
  */
-declare class Instrumentations extends Instrumentations_base<InstrumentationLoader> {}
+export declare class Instrumentations extends Instrumentations_base<InstrumentationLoader> {}
 //#endregion
 //#region src/health.d.ts
 declare const HealthCheckFailed_base: import("unthrown").TaggedErrorConstructor<"HealthCheckFailed">;
@@ -40,13 +40,23 @@ declare const HealthCheckFailed_base: import("unthrown").TaggedErrorConstructor<
  * 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<{
+export 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>;
+  /**
+   * 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">;
 /**
@@ -57,7 +67,7 @@ declare const HealthChecks_base: import("@btravstack/di").ManyPortClass<"HealthC
  * application never composed contributes nothing — no registration call to
  * forget, and no order to get wrong.
  */
-declare class HealthChecks extends HealthChecks_base<HealthCheck> {}
+export declare class HealthChecks extends HealthChecks_base<HealthCheck> {}
 type ComponentHealth = {
   readonly name: string;
   readonly status: "healthy" | "unhealthy";
@@ -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.
  */
-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
 /**
@@ -91,7 +112,7 @@ declare const runHealthChecks: (checks: readonly HealthCheck[]) => AsyncResult<H
  */
 type Level = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
 /** The levels in order, least severe first — what `isEnabled` compares through. */
-declare const LEVELS: readonly Level[];
+export declare const LEVELS: readonly Level[];
 /**
  * What a line, a span or a measurement carries besides itself: a flat record of
  * scalars.
@@ -137,9 +158,9 @@ declare const Logger_base: import("@btravstack/di").PortClass<"Logger">;
  * problem into an outage. Synchronous `void`, not an `AsyncResult` — thesis 6's
  * one deliberate exemption, since a lost line is not a modeled error.
  */
-declare class Logger extends Logger_base<LoggerService> {}
+export declare class Logger extends Logger_base<LoggerService> {}
 /** A span's outcome: unset until something says otherwise, then `ok` or `error`. */
-declare const SPAN_STATUS: {
+export declare const SPAN_STATUS: {
   readonly unset: 0;
   readonly ok: 1;
   readonly error: 2;
@@ -169,7 +190,7 @@ declare const Tracer_base: import("@btravstack/di").PortClass<"Tracer">;
  * because a port typed as a vendor's type points the dependency arrow outwards
  * and makes the whole family install that vendor.
  */
-declare class Tracer extends Tracer_base<TracerService> {}
+export declare class Tracer extends Tracer_base<TracerService> {}
 /** A monotonic count. */
 type Counter = {
   readonly add: (value: number, attributes?: Attributes) => void;
@@ -196,7 +217,7 @@ type MeterService = {
 };
 declare const Meter_base: import("@btravstack/di").PortClass<"Meter">;
 /** The application's meter, as a port. See {@link Tracer} for why it does not name a vendor. */
-declare class Meter extends Meter_base<MeterService> {}
+export declare class Meter extends Meter_base<MeterService> {}
 //#endregion
 //#region src/observation.d.ts
 /**
@@ -277,9 +298,9 @@ declare const Observers_base: import("@btravstack/di").ManyPortClass<"Observers"
  * NOTHING provides is an unmet dependency, at plan time and in `Needs` alike.
  * Several no-ops in one graph cost a call each and nothing else.
  */
-declare class Observers extends Observers_base<(operation: Operation) => Settle> {}
+export declare class Observers extends Observers_base<(operation: Operation) => Settle> {}
 /** The no-op member every reader of {@link Observers} contributes, so the set is never empty. */
-declare const noObserver: () => Settle;
+export declare const noObserver: () => Settle;
 /**
  * Run every observer around one operation, and hand back the one finisher that
  * settles them all.
@@ -291,14 +312,29 @@ declare const noObserver: () => Settle;
  * `tapFailure` on the same chain, or a retry, is exactly the shape that fires
  * twice and doubles a failure count.
  */
-declare const observe: (observers: readonly ((operation: Operation) => Settle)[], operation: Operation) => Settle;
+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 = {
   readonly now: () => number;
   readonly sleep: (ms: number, signal?: AbortSignal) => AsyncResult<void, never>;
 };
-declare const systemClock: Clock;
+export declare const systemClock: Clock;
 //#endregion
 //#region src/units.d.ts
 /**
@@ -317,7 +353,7 @@ type UnitRecord = {
   readonly tenantId: string | undefined;
   readonly signal: AbortSignal;
 };
-declare const currentUnit: () => UnitRecord | undefined;
+export declare const currentUnit: () => UnitRecord | undefined;
 /**
  * What a runtime says about one piece of work as it submits it. `kind` is the
  * category (`"http"`, `"tick"`, `"job"`); `id` identifies **this** unit.
@@ -350,7 +386,7 @@ type UnitRegistry = {
 //#endregion
 //#region src/runtime.d.ts
 declare const RuntimeStartFailed_base: import("unthrown").TaggedErrorConstructor<"RuntimeStartFailed">;
-declare class RuntimeStartFailed extends RuntimeStartFailed_base<{
+export declare class RuntimeStartFailed extends RuntimeStartFailed_base<{
   readonly runtime: string;
   readonly cause: unknown;
 }> {
@@ -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;
@@ -442,7 +505,7 @@ type Runtime<Resolves extends AnyPort = never, Info = never> = {
  * process boots exactly one, while each carries its own `Resolves`/`Info` in
  * the type.
  */
-declare const RuntimePort: PortClass<"Runtime">;
+export declare const RuntimePort: PortClass<"Runtime">;
 /** The instance type every runtime port shares — `Extract` this from a module's exports to find its runtime. */
 type RuntimeInstance = InstanceType<PortClass<"Runtime">>;
 /** The `Runtime<Resolves, Info>` a module exports, or `never` when it exports none. */
@@ -480,7 +543,7 @@ type RuntimeInfoOf<X> = RuntimeOf<X> extends {
  * const traceId = typeof parent === "string" ? traceIdOfTraceparent(parent) : undefined;
  * ```
  */
-declare const traceIdOfTraceparent: (header: string) => string | undefined;
+export declare const traceIdOfTraceparent: (header: string) => string | undefined;
 /**
  * `running`, but no later than the kernel's drain deadline — the primitive a
  * `Serving.drain` needs when the work it awaits settles on somebody else's
@@ -500,7 +563,7 @@ declare const traceIdOfTraceparent: (header: string) => string | undefined;
  * (`drain.ts` uses `clock.sleep` for exactly that, so a fake clock can control
  * it) — do not fold the two together.
  */
-declare const releasedBy: (signal: AbortSignal, running: AsyncResult<void, never>) => AsyncResult<void, never>;
+export declare const releasedBy: (signal: AbortSignal, running: AsyncResult<void, never>) => AsyncResult<void, never>;
 //#endregion
 //#region src/drain.d.ts
 type DrainReport = {
@@ -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";
 } | {
@@ -560,7 +656,7 @@ type KernelEvent = {
   readonly cause: unknown;
 };
 type EventSink = (event: KernelEvent) => void;
-declare const stderrSink: EventSink;
+export declare const stderrSink: EventSink;
 //#endregion
 //#region src/phase.d.ts
 type Phase = "building" | "starting" | "serving" | "draining" | "stopping" | "exited";
@@ -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> = {
@@ -668,7 +798,7 @@ type PortIdOf<P> = P extends PortInstance<infer Id, infer _Service> ? Id : P;
 type StartGate<X, N = never> = [Exclude<N, Scope | Env>] extends [never] ? [Extract<X, RuntimeInstance>] extends [never] ? "NO RUNTIME — the module exports no port declared over RuntimePort" : [InstanceType<RuntimeResolvesOf<X>>] extends [X] ? unknown : "UNSATISFIED RUNTIME PORTS — the runtime resolves a port the module does not export" : {
   readonly "UNSATISFIED DEPENDENCIES — nothing provides": PortIdOf<Exclude<N, Scope | Env>>;
 };
-declare const start: <X, E, N>(module: Module<X, E, N> & StartGate<X, N>, options?: StartOptions) => RunningApp<E, RuntimeInfoOf<X>>;
+export declare const start: <X, E, N>(module: Module<X, E, N> & StartGate<X, N>, options?: StartOptions) => RunningApp<E, RuntimeInfoOf<X>>;
 //#endregion
 //#region src/run-main.d.ts
 /**
@@ -690,6 +820,7 @@ declare const start: <X, E, N>(module: Module<X, E, N> & StartGate<X, N>, option
  * | 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` |
  *
@@ -703,6 +834,6 @@ declare const start: <X, E, N>(module: Module<X, E, N> & StartGate<X, N>, option
  * await runMain(OrderApi);
  * ```
  */
-declare const runMain: <X, E, N>(module: Module<X, E, N> & StartGate<X, N>, options?: StartOptions, exit?: (code: number) => void) => Promise<void>;
+export declare const runMain: <X, E, N>(module: Module<X, E, N> & StartGate<X, N>, options?: StartOptions, exit?: (code: number) => void) => Promise<void>;
 //#endregion
-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, Observers, type Operation, type Phase, type RunUnit, type RunningApp, type Runtime, type RuntimeHost, type RuntimeInfoOf, RuntimePort, RuntimeStartFailed, SPAN_STATUS, type Serving, type Settle, type Settled, type Span, type SpanStatusCode, type StartGate, type StartOptions, type TeardownError, Tracer, type TracerService, type UnitHost, type UnitMeta, type UnitRecord, type UnitRegistry, type UnitWork, currentUnit, noObserver, observe, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock, traceIdOfTraceparent };
+export type { Attributes, Clock, ComponentHealth, Counter, DrainReport, EventSink, ExitReport, HealthCheck, HealthReport, Histogram, InstrumentationLoader, KernelEvent, Level, LoggerService, MeterService, Operation, Phase, RunUnit, RunningApp, Runtime, RuntimeHost, RuntimeInfoOf, Serving, Settle, Settled, Span, SpanStatusCode, StartGate, StartOptions, TeardownError, TracerService, UnitHost, UnitMeta, UnitRecord, UnitRegistry, UnitWork };