@ultimat3/core 24.0.0 → 25.0.0

package/src/index.ts

@@ -5,15 +5,17 @@
 // secrets — because each is one subject spread over a dozen modules. Every name they carry is
 // still written out below: `export *` would make the contract something a reader has to resolve.
 
-// Anchored on purpose, and NOT by the `sideEffects` array: Bun reads any array as `false` and drops
-// the module regardless (oven-sh/bun#40650). This module registers @ultimat3/schema's error TITLES,
-// because schema is tier 0 and cannot register its own — and what reads them is `UltimateError`'s
-// constructor, which never imports this file. Shaken out, every X_VALIDATION_FAILED renders
-// untitled in the browser with nothing to say why. `SIDE_EFFECTS_ANCHORS` carries the argument and
-// `bun run side-effects` enforces it. `context.ts`, `lifecycle-errors.ts` and `secrets-errors.ts`
-// are declared side-effecting too and are deliberately NOT anchored: each is reached by whatever
-// uses it, and anchoring `context.ts` alone measured +3,485 B on a browser chunk for a provider a
-// browser can never fire.
+// Anchored on purpose, and not by the `sideEffects` array alone: Bun before 1.4.1 read any array as
+// `false` and dropped the module regardless (oven-sh/bun#40650), and a bare import holds on every
+// bundler — the array still lists both, because one that honours it drops a bare import of a module
+// it does not list. This module registers @ultimat3/schema's error TITLES, because schema is tier 0
+// and cannot register its own — and what reads them is `UltimateError`'s constructor, which never
+// imports this file. Shaken out, every X_VALIDATION_FAILED renders untitled in the browser with
+// nothing to say why. `SIDE_EFFECTS_ANCHORS` carries the argument and `bun run side-effects`
+// enforces it. `context.ts`, `lifecycle-errors.ts` and `secrets-errors.ts` also run something at
+// import and are neither anchored NOR listed: only their own bindings need the effect, so they ride
+// along exactly where they are used. Listed, Bun 1.4.2 kept all three in every chunk reaching this
+// barrel, ~5.4 kB an island (`SIDE_EFFECTS_BY_USE` in `scripts/side-effects.ts`).
 import './core-error-codes';
 import './schema-error-codes';
 
@@ -30,6 +32,7 @@ export {
   ACTOR_KINDS,
   actorFact,
   actorLabel,
+  actorOf,
   actorOrigin,
   agentActor,
   anonymousActor,
@@ -42,22 +45,45 @@ export {
   withFacts,
 } from './actor';
 export type { AddressClass } from './address-class';
-export { classifyAddress, isPublicAddress } from './address-class';
+export { addressNetwork, classifyAddress, isPublicAddress } from './address-class';
 export { APP_VERSION_KEY, appVersion, DEFAULT_APP_VERSION } from './app-version';
-export { assert, assertNever, type InvariantOptions, invariant } from './assert';
+export { type AssertCodedOptions, assert, assertCoded, assertNever } from './assert';
 export { type AsyncContext, asyncContext } from './async-context';
 /** The four shapes an async region can be in — produced by `realtime`, rendered by `ui`. */
 export type { AsyncState } from './async-state';
+/** The audit seam `action` and `query` share: one record shape, one installed sink. */
+export type {
+  AuditFailure,
+  AuditOutcome,
+  AuditPrimitive,
+  AuditRecord,
+  AuditSink,
+  AuditSurface,
+} from './audit';
+export {
+  AUDIT_RECORD_FIELDS,
+  getAuditSink,
+  resetAuditSink,
+  setAuditSink,
+} from './audit';
+export type {
+  AwsCredentials,
+  AwsPayload,
+  SignAwsRequestInput,
+  SignedAwsRequest,
+} from './aws-sigv4';
+export { signAwsRequest, UNSIGNED_PAYLOAD } from './aws-sigv4';
 export type { BackoffCurve, BackoffOptions, JitterMode, Random } from './backoff';
-export { backoffDelay } from './backoff';
+export { backoffDelay, jitterStatedDelay } from './backoff';
+export { isCompiledBundle } from './bunfs';
 export { CACHE_TIERS, type CacheTierName } from './cache-vocabulary';
 export { canonicalJson, fingerprint } from './canonical-json';
 export type { FetchLike, TransportRequest } from './client-dispatch';
-export { IDEMPOTENCY_HEADER } from './client-dispatch';
+export { BUILD_ID_HEADER, IDEMPOTENCY_HEADER } from './client-dispatch';
 /**
  * Flight control for a typed client, and OPT-IN by construction: `@ultimat3/action`'s and
  * `@ultimat3/query`'s `client.ts` each name `ClientFlight` as a TYPE only, so a caller that never
- * mentions `createClientFlight` pays nothing for the fence, the dedup map or the retry loop.
+ * mentions `clientFlight` pays nothing for the fence, the dedup map or the retry loop.
  * Both packages re-export these names unchanged; this is the one copy.
  */
 export type {
@@ -67,7 +93,7 @@ export type {
   FlightKeyOptions,
   FlightPlan,
 } from './client-flight';
-export { createClientFlight, DEFAULT_CLIENT_RETRY, isTransientFailure } from './client-flight';
+export { clientFlight, DEFAULT_CLIENT_RETRY, isTransientFailure } from './client-flight';
 export type { ActionPathStyle, ActionRoute } from './client-paths';
 export {
   ACTION_PATH_PREFIX,
@@ -80,6 +106,9 @@ export {
   splitWords,
 } from './client-paths';
 export type { TransportFailure } from './client-problem';
+export { MAX_REMOTE_TITLE_LENGTH, remoteTitleOf, withStatedDelay } from './client-problem';
+/** What a decoder reads off a refusal: the stated `Retry-After`, and the body's display title. */
+export { MAX_RETRY_AFTER_SECONDS, retryAfterSecondsOf } from './client-retry-after';
 /**
  * The browser seam (plan 101): ONE HTTP function, the records envelope it decodes, the per-tab
  * page handle records land in, and the principal fence every client layer subscribes to.
@@ -93,8 +122,6 @@ export { FRAMEWORK_CODE, problemOf, retryForStatus, traceHeaders } from './clien
 export { notifyClientWrite, onClientWrite } from './client-writes';
 export { type Clock, type FrozenClock, frozenClock, systemClock } from './clock';
 export type {
-  AiConfig,
-  AiConfigInput,
   AppConfig,
   AppConfigInput,
   AppConfigOverlay,
@@ -102,7 +129,6 @@ export type {
   CacheConfig,
   DatabaseConfig,
   JobsConfig,
-  McpConfig,
   NotifyConfig,
   PwaConfigInput,
   RealtimeConfig,
@@ -111,9 +137,17 @@ export type {
   ThemeMode,
 } from './config';
 export { defineConfig, INBOX_RETENTION_KEYS } from './config';
+export type { AiConfig, AiConfigInput, McpConfig } from './config-ai';
 export type { DrainConfig, HealthConfig, ReadinessMode } from './config-health';
 export { READINESS_MODES } from './config-health';
 export type { IslandsConfig, IslandsSection, IslandsSectionInput } from './config-islands';
+export { JOBS_CONCURRENCY_DEFAULT, type JobsConcurrency } from './config-jobs';
+export type {
+  MailConfig,
+  MailRetainMimeConfig,
+  MailSection,
+  MailSectionInput,
+} from './config-mail';
 export type {
   NavigationConfig,
   NavigationSection,
@@ -125,7 +159,6 @@ export type {
 export {
   DEFAULT_SPECULATION,
   NAVIGATION_SURFACES,
-  resolveSpeculation,
   SPECULATION_EAGERNESS,
 } from './config-navigation';
 export type {
@@ -138,7 +171,7 @@ export type {
   PwaShortcut,
   PwaText,
 } from './config-pwa';
-export { PWA_COLOR_KEYS, PWA_SCHEMES } from './config-pwa';
+export { isSameOriginPath, PWA_COLOR_KEYS, PWA_SCHEMES } from './config-pwa';
 export type {
   SeoConfig,
   SeoConfigInput,
@@ -154,7 +187,7 @@ export type { ConflictPolicy, ResolveConflictOptions, Row } from './conflict-pol
 export { resolveConflict } from './conflict-policy';
 export type { Ctx, CtxFacts, CtxInit, CtxPatch, CtxServices, ServiceBag } from './context';
 export {
-  createContext,
+  ctxOf,
   DEFAULT_LOCALE,
   DEFAULT_TIME_ZONE,
   hasContext,
@@ -165,10 +198,13 @@ export {
   useService,
   withChildContext,
 } from './context';
-/** The one `Cookie:` reader — auth, http and i18n each parsed the header and could not share it. */
-export { readCookie } from './cookie';
+/** The one cookie codec — auth, http and i18n each parsed `Cookie:` and spelled `Set-Cookie`. */
+export type { CookiePriority, CookieSameSite, SetCookieOptions } from './cookie';
+export { CookieInvalidError, readCookie, serializeSetCookie } from './cookie';
 export type { CursorPayload } from './cursor';
 export {
+  CURSOR_SECRET_FIX,
+  CURSOR_SECRET_KEY,
   CursorInvalidError,
   configureCursorSigning,
   decodeCursor,
@@ -176,9 +212,19 @@ export {
   resetCursorSigning,
   usesDevCursorSecret,
 } from './cursor';
+/** The ONE page shape — `nextCursor` is `null` exactly when `hasMore` is false (25.0.0). */
+export type { Page } from './cursor-page';
+export { pageOf } from './cursor-page';
 export { compareDecimalText } from './decimal-order';
+export type { Deprecation, DeprecationField, DeprecationRender } from './deprecation';
+export { recordDeprecatedCall, renderDeprecation } from './deprecation';
 export type { DevSecretsOptions } from './dev-secrets';
-export { assertNoDevSecretsOutsideLocal, CursorSecretDevError } from './dev-secrets';
+export {
+  assertNoDevSecretsOutsideLocal,
+  CursorSecretDevError,
+  devSecretsRefused,
+} from './dev-secrets';
+export { DRAIN_DEADLINE_DEFAULT_MS, DRAIN_DEADLINE_MAX_MS } from './drain-deadline';
 export type {
   Env,
   EnvBooleanVar,
@@ -196,10 +242,8 @@ export type {
 export { checkEnv, defineEnv, describeEnv, maskedEnvValues } from './env';
 export type { EnvExampleOptions, EnvExampleReport } from './env-example';
 export {
-  assertEnvExample,
   checkEnvExample,
   ENV_EXAMPLE_PATH,
-  EnvExampleDriftError,
   envFileCandidates,
   parseEnvKeys,
   renderEnvExample,
@@ -269,7 +313,6 @@ export {
   statedDelayMs,
   stringField,
   toUltimateError,
-  ULTIMATE_ERROR_BRAND,
   UltimateError,
 } from './exports/error-contract';
 export type {
@@ -338,7 +381,6 @@ export {
   configureTelemetry,
   connections,
   counter,
-  createLogger,
   currentSampler,
   currentSpan,
   currentSpanContext,
@@ -405,6 +447,7 @@ export {
   setLogStream,
   startMetricExport,
   startSpan,
+  structuredLogger,
   traceparent,
   tryOtlpEndpoint,
   withSpan,
@@ -434,6 +477,7 @@ export {
   masterKeyPath,
   openSecrets,
   parseMasterKey,
+  promoteStagedMasterKey,
   readSecretsFile,
   requireMasterKey,
   revealOptionalSecret,
@@ -445,6 +489,7 @@ export {
   SECRETS_KEY_MODE,
   SecretsFileInvalidError,
   SecretsFileMissingError,
+  SecretsKeyAclError,
   SecretsKeyInvalidError,
   SecretsKeyMismatchError,
   SecretsKeyMissingError,
@@ -456,6 +501,7 @@ export {
   secretsPath,
   serializeSecretValues,
   stagedMasterKeyPath,
+  stageMasterKeyFile,
   writeMasterKeyFile,
   writeSecretsFile,
 } from './exports/secrets';
@@ -466,11 +512,11 @@ export type {
   FlightGateOptions,
   FlightGateState,
 } from './flight-gate';
-export { createFlightGate, gateOverloaded } from './flight-gate';
+export { flightGate, gateOverloaded } from './flight-gate';
 export { fnv1a } from './fnv1a';
 export { formatBytes } from './format-bytes';
 export type { GenerationFence } from './generation-fence';
-export { createFence, isSuperseded } from './generation-fence';
+export { generationFence, isSuperseded } from './generation-fence';
 export type { PublicHealthBody } from './health-disclosure';
 export { DEFAULT_HEALTH_DETAIL_PEERS, healthBody, healthPeerListed } from './health-disclosure';
 export type { HostDecision, HostRule } from './host-rules';
@@ -488,8 +534,8 @@ export {
   spanId,
   traceId,
   typedId,
-  uuid,
   uuidTimestamp,
+  uuidV7,
 } from './ids';
 export type { ImageFit, ResizeSpec } from './image/canvas';
 export { parseColor } from './image/color';
@@ -523,7 +569,7 @@ export type { ImageFormat, ImageInfo } from './image/probe';
 export { IMAGE_FORMATS, IMAGE_MIME_TYPES, probeImage, sniffImageFormat } from './image/probe';
 export type { ImageSize, Raster } from './image/raster';
 export {
-  createRaster,
+  blankRaster,
   hasAlpha,
   MAX_IMAGE_PIXELS,
 } from './image/raster';
@@ -585,7 +631,7 @@ export {
 } from './lifecycle-grace';
 export type { ReadinessCheck, ReadinessStatus } from './lifecycle-readiness';
 export type { SignalHandlerOptions } from './lifecycle-signals';
-export { installSignalHandlers } from './lifecycle-signals';
+export { drainSignals, installSignalHandlers } from './lifecycle-signals';
 export { isSelfOrigin, listeningOrigins, markListening, resetListeners } from './listeners';
 export type { Direction } from './locale-direction';
 export { directionOf, isRtl } from './locale-direction';
@@ -594,9 +640,16 @@ export { localeSegment, localizePath, splitLocalePath } from './locale-path';
 // The process logger's test seam, beside nothing it groups with: where a default-writer line goes.
 export type { LogSink } from './logger';
 export { setLogSink } from './logger';
-export { isMcpExposed, type McpExposureDeclaration } from './mcp-exposure';
+export {
+  isMcpExposed,
+  type McpAnnotationHints,
+  type McpExposureDeclaration,
+  type McpListFilterOp,
+  type McpListParams,
+} from './mcp-exposure';
 export type { MeasurementActorFactory } from './measurement-actor';
 export {
+  declaredMeasurementActor,
   defineMeasurementActor,
   MEASUREMENT_ACTOR_ID,
   measurementActor,
@@ -686,10 +739,11 @@ export {
   type ServiceFactory,
 } from './service';
 export type { FlightJoin, Scheduler, SingleFlight, SingleFlightOptions } from './single-flight';
-export { createSingleFlight } from './single-flight';
+export { singleFlight } from './single-flight';
 export { endOfLiteral, maskLiterals, QUOTES, stripComments } from './source-mask';
 export type { StoreMode } from './store-mode';
 export { STORE_MODES, storeMode } from './store-mode';
+export { THEME_STORAGE_KEY } from './theme-storage';
 export { timingSafeEqual } from './timing-safe-equal';
 export {
   frameworkVersion,

package/src/iso-date.ts

@@ -1,5 +1,5 @@
 // Single responsibility: re-export `@ultimat3/schema`'s ISO date-time predicate, so a package that
 // depends on core and not on schema — `@ultimat3/ui` formats dates, it validates nothing — judges a
-// date string with the ONE rule `t.date` and `timestamp()` use. The `time-zone-name.ts` shape.
+// date string with the ONE rule `t.date` and `timestamp()` use.
 
 export { isIsoDateTime } from '@ultimat3/schema';

package/src/lifecycle-errors.ts

@@ -15,7 +15,7 @@ registerErrorCodes({
  *
  * Loud rather than tolerant, because the silent version was measured and is worse than a failed
  * boot: `state` never leaves `stopped` and `drain()` has memoized its promise, so a second
- * `createServer().start()` bound a real port, answered `X_DRAINING` (503) to every request, and was
+ * `httpServer().start()` bound a real port, answered `X_DRAINING` (503) to every request, and was
  * still accepting connections after its own `stop()` returned — a dead listener holding a port,
  * with no log line naming what happened.
  *

package/src/lifecycle-readiness.ts

@@ -1,5 +1,8 @@
-// Single responsibility: the readiness CHECK — its signature and its two answers. The mode that
-// decides what a failing one does to `/readyz` is `config-health.ts`'s.
+// Single responsibility: the readiness CHECK — its signature, its two answers, and the registry of
+// named checks `/readyz` runs. The mode that decides what a failing one does to `/readyz` is
+// `config-health.ts`'s; the lifecycle that reports through them is `lifecycle.ts`.
+
+import { UltimateError } from './errors';
 
 export type ReadinessStatus = 'ok' | 'failing';
 
@@ -19,3 +22,58 @@ export type ReadinessStatus = 'ok' | 'failing';
  * is `failing`.
  */
 export type ReadinessCheck = () => boolean;
+
+const checks = new Map<string, ReadinessCheck>();
+
+/**
+ * Register a named readiness check. Returns its unregister — the same shape as `onShutdown`, and
+ * owned by whoever can be started twice, for the same reason.
+ */
+export function registerReadinessCheck(name: string, check: ReadinessCheck): () => void {
+  if (checks.has(name)) {
+    throw new UltimateError({
+      code: 'X_READINESS_CHECK_DUPLICATE',
+      cause: `a readiness check named "${name}" is already registered (have: ${[...checks.keys()].join(', ')})`,
+      fix: `name the second check for what it actually probes, e.g. registerReadinessCheck('${name}-replica', check) — or hold the unregister the first registration returned and call it first`,
+      meta: { name },
+    });
+  }
+  checks.set(name, check);
+  return () => {
+    if (checks.get(name) === check) checks.delete(name);
+  };
+}
+
+/** Test-only: registered checks. A count that climbs across a start/stop cycle is a leak. */
+export function readinessCheckCount(): number {
+  return checks.size;
+}
+
+/** Drop every check — `resetLifecycle()`'s, and nothing else's. */
+export function clearReadinessChecks(): void {
+  checks.clear();
+}
+
+/**
+ * Every check, run now, by name. A check that throws is `failing` — never an unhandled error —
+ * and is handed to `onThrow`, which `lifecycle.ts` routes through its total `report`.
+ *
+ * Built through `Object.fromEntries`, never by assigning `results[name]`: assignment to the one
+ * name `__proto__` sets the PROTOTYPE instead of adding a key, so that check vanished from the
+ * report, `ready` was computed over an empty object — vacuously true — and a failing check
+ * answered 200. `fromEntries` defines own properties and has no such name.
+ */
+export function runReadinessChecks(
+  onThrow: (name: string, thrown: unknown) => void,
+): Readonly<Record<string, ReadinessStatus>> {
+  const results: [string, ReadinessStatus][] = [];
+  for (const [name, check] of checks) {
+    try {
+      results.push([name, check() ? 'ok' : 'failing']);
+    } catch (thrown) {
+      results.push([name, 'failing']);
+      onThrow(name, thrown);
+    }
+  }
+  return Object.fromEntries(results);
+}

package/src/lifecycle-signals.ts

@@ -7,11 +7,36 @@ export interface SignalHandlerOptions {
   readonly signals?: readonly ProcessSignal[] | undefined;
   /** Call `process.exit()` once drained. Off in tests. */
   readonly exit?: boolean | undefined;
+  /** Whose default signal set to install — `process.platform` unless a test names one. */
+  readonly platform?: string | undefined;
 }
 
-/** Install SIGTERM/SIGINT handling. Returns an uninstall function. */
+const POSIX_SIGNALS: readonly ProcessSignal[] = Object.freeze(['SIGTERM', 'SIGINT']);
+
+/**
+ * Windows never sends SIGTERM to a console process: a service stop or a closed console window
+ * arrives as SIGHUP, and Ctrl-Break as SIGBREAK. Listening for the POSIX pair alone meant either
+ * one killed the process outright, mid-request, with no drain. SIGHUP stays off POSIX on purpose:
+ * there it is a terminal hang-up a supervised process should not read as "stop".
+ */
+const WINDOWS_SIGNALS: readonly ProcessSignal[] = Object.freeze([
+  'SIGTERM',
+  'SIGINT',
+  'SIGHUP',
+  'SIGBREAK',
+]);
+
+/** The signals that start a drain on `platform`. */
+export function drainSignals(platform: string = process.platform): readonly ProcessSignal[] {
+  return platform === 'win32' ? WINDOWS_SIGNALS : POSIX_SIGNALS;
+}
+
+/**
+ * Install drain-on-signal handling — SIGTERM/SIGINT, plus SIGHUP/SIGBREAK on Windows
+ * (`drainSignals`). Returns an uninstall function.
+ */
 export function installSignalHandlers(options?: SignalHandlerOptions): () => void {
-  const signals: readonly ProcessSignal[] = options?.signals ?? ['SIGTERM', 'SIGINT'];
+  const signals = options?.signals ?? drainSignals(options?.platform);
   const handlers = new Map<ProcessSignal, () => void>();
 
   for (const signal of signals) {

package/src/lifecycle-types.ts

@@ -0,0 +1,96 @@
+// Single responsibility: the lifecycle's data model — its states, phases, hook and option shapes,
+// and the health report it answers with. The mechanism that moves between them is `lifecycle.ts`,
+// which re-exports every name here so a caller keeps one import path.
+
+import type { Clock } from './clock';
+import type { ReadinessMode } from './config-health';
+import type { ReadinessStatus } from './lifecycle-readiness';
+import type { Logger } from './logger';
+
+export type HealthState = 'starting' | 'ready' | 'draining' | 'stopped';
+
+/** Ordered. `accept` runs first, `close` last. */
+export type ShutdownPhase = 'accept' | 'inflight' | 'close';
+
+export const SHUTDOWN_PHASES: readonly ShutdownPhase[] = ['accept', 'inflight', 'close'];
+
+/**
+ * Signals Ultimate reacts to. Narrower than `NodeJS.Signals` on purpose. `SIGBREAK` is Windows'
+ * Ctrl-Break — the one console signal there that is neither Ctrl-C nor a window closing.
+ */
+export type ProcessSignal = 'SIGTERM' | 'SIGINT' | 'SIGHUP' | 'SIGQUIT' | 'SIGBREAK';
+
+export interface ShutdownReason {
+  readonly signal: string;
+  /**
+   * Real monotonic ms (`systemClock`) after which hooks are abandoned — deliberately NOT the
+   * injected clock. The budget this bounds is `terminationGracePeriodSeconds`, counted by the
+   * kubelet in real seconds, so a frozen clock must be unable to extend it: read off `clock` a
+   * test that advanced an hour of fake time handed the drain a 16-minute grace period, while
+   * `waitForIdle` went on sleeping on a real `setTimeout`. `clock` still owns `uptimeMs`.
+   */
+  readonly deadlineAt: number;
+}
+
+export type ShutdownHook = (reason: ShutdownReason) => void | Promise<void>;
+
+export interface OnShutdownOptions {
+  readonly phase?: ShutdownPhase | undefined;
+}
+
+export interface LifecycleOptions {
+  /**
+   * The whole drain's budget — the in-flight wait AND every hook, in every phase. 25s by default,
+   * and **enforced whether or not an app sets it**: `ShutdownReason.deadlineAt` was always computed
+   * and handed to every hook, so the deadline was declared by the design and only the enforcement
+   * was missing. No hook reads `deadlineAt`, which is why it has to be imposed here.
+   *
+   * The lever is a LARGER value, not the absence of one: a `worker` holding a 10-minute job wants
+   * `configureLifecycle({ deadlineMs: 600_000 })` and a `terminationGracePeriodSeconds` at least as
+   * large. Left at 25s it is abandoned and the process exits clean — the row's visibility lease
+   * lapses and another worker re-claims it, which is what at-least-once already promises. The
+   * alternative is not "the job finishes": it is the same duplicate, delivered by SIGKILL at the
+   * kubelet's grace period, with no log line naming what overran.
+   *
+   * Screened where it is assigned: a whole number of milliseconds, 0 or more. `0` is "drain now".
+   */
+  readonly deadlineMs?: number | undefined;
+  /**
+   * How long `/readyz` answers 503 BEFORE the `accept` phase closes the listener — the time the
+   * endpoints controller and the ingress need to stop routing here. Closing on the flip itself left
+   * endpoints pointing at a closed socket, and a POST in that window got a 502. Added to
+   * `deadlineMs`, never taken from it. Unset: `defaultReadinessGraceMs()` of the process env at
+   * drain time — 0 in development/test, 5000 everywhere else, including a process naming no env.
+   * A whole number from 0 to 60000; 0 is no grace.
+   */
+  readonly readinessGraceMs?: number | undefined;
+  /** What a failing check does to `/readyz` — see `ReadinessMode`. Default `'dependencies'`. */
+  readonly readiness?: ReadinessMode | undefined;
+  readonly clock?: Clock | undefined;
+  readonly logger?: Logger | undefined;
+}
+
+export interface HealthReport {
+  readonly state: HealthState;
+  readonly ready: boolean;
+  readonly uptimeMs: number;
+  readonly inflight: number;
+  readonly buildId: string;
+  /** Named, because "alert on check failures BY CHECK NAME" is not writable against a boolean. */
+  readonly checks: Readonly<Record<string, ReadinessStatus>>;
+  /**
+   * How many checks are registered. `checks: {}` reads identically for "every check passed" and
+   * "nobody registered one", and only the second is a `/readyz` that means no more than "the
+   * socket is bound" — which is what the chart's and compose's healthchecks route traffic on.
+   * Reported rather than enforced: an empty registry is still ready, so a role that genuinely has
+   * no dependency does not have to invent a check to boot.
+   */
+  readonly registered: number;
+}
+
+export interface HealthPayload {
+  readonly ok: boolean;
+  /** The status code the HTTP layer should return. Core stays HTTP-free; this is just data. */
+  readonly status: number;
+  readonly body: HealthReport;
+}