@ultimat3/core 20.2.1 → 22.0.0

package/src/host-rules.ts

@@ -0,0 +1,71 @@
+// `allowHosts`, as a decision every browser driver asks before a request leaves — never a note in
+// a README. A headless browser inside your network is the widest SSRF surface an app can own: one
+// injected `<img src="http://169.254.169.254/…">` on a page you do not control is a credential
+// read. In core because two tier-5 packages drive a browser (`scraping`, and `cli`'s `x shot`) and
+// neither may import the other; two copies of this rule would be two answers to "may it leave".
+
+export type HostRule = string;
+
+/** The one spelling that means "every host", written out so it is visible in review. */
+export const ANY_HOST: HostRule = '*';
+
+/**
+ * Schemes with no host to match. `about:blank` is where every browser starts, `data:` and `blob:`
+ * never leave the process — refusing them would refuse the first page load of every run.
+ */
+const HOSTLESS_SCHEMES = new Set(['about:', 'data:', 'blob:']);
+
+/**
+ * Hostless AND refused, which is why it is not on the line above — it sat there until 2026-09.
+ * `javascript:` has no host for the same reason `data:` has none, and that is the whole
+ * resemblance: the other three are inert content this process renders, while this one is code
+ * EXECUTED in the current document's origin, with the session's cookies and the session's
+ * `localStorage` already in scope. `allowHosts` cannot say anything about a URL with no host to
+ * name, so "no host, therefore allowed" was the allow list opting itself out of the one navigation
+ * that needs no host to exfiltrate through — `javascript:fetch('/admin').then(post_elsewhere)` is
+ * a same-origin read on an allow-listed site. Fail closed; there is no legitimate scrape verb that
+ * needs it (`page.eval` is the declared seam).
+ */
+const REFUSED_SCHEMES = new Set(['javascript:']);
+
+export interface HostDecision {
+  readonly allowed: boolean;
+  /** The host the URL resolved to, `''` for a hostless scheme. */
+  readonly host: string;
+}
+
+/**
+ * `example.com` matches that host EXACTLY. `*.example.com` matches any subdomain and NOT the
+ * apex — the two are written separately on purpose: an allow list that silently included every
+ * subdomain would let a `cdn-user-content.example.com` (whose contents somebody else controls)
+ * through a rule an author wrote for the apex.
+ */
+export function hostMatches(host: string, rule: HostRule): boolean {
+  if (rule === ANY_HOST) return true;
+  const normalised = host.toLowerCase();
+  const cleaned = rule.trim().toLowerCase();
+  if (cleaned.startsWith('*.')) {
+    const suffix = cleaned.slice(1);
+    return normalised.endsWith(suffix) && normalised.length > suffix.length;
+  }
+  return normalised === cleaned;
+}
+
+/**
+ * Fails CLOSED: a URL that cannot be parsed is refused. A driver handed a malformed request has
+ * no way to know where it would have gone, and "we could not tell, so we let it through" is the
+ * decision that makes the whole list advisory.
+ */
+export function hostDecision(url: string, allowHosts: readonly HostRule[]): HostDecision {
+  const scheme = url.slice(0, Math.max(0, url.indexOf(':') + 1)).toLowerCase();
+  if (REFUSED_SCHEMES.has(scheme)) return { allowed: false, host: '' };
+  if (HOSTLESS_SCHEMES.has(scheme)) return { allowed: true, host: '' };
+  let host: string;
+  try {
+    host = new URL(url).hostname;
+  } catch {
+    return { allowed: false, host: '' };
+  }
+  if (host === '') return { allowed: false, host };
+  return { allowed: allowHosts.some((rule) => hostMatches(host, rule)), host };
+}

package/src/image/exif-orientation.ts

@@ -0,0 +1,40 @@
+// Single responsibility: the EXIF orientation tag (0x0112) of one JPEG APP1 segment. The decoder
+// applies it — `Bun.Image` reports a 40x20 sensor image tagged `6` as 20x40 — so a probe that
+// ignored it reserved a layout box with width and height swapped.
+
+const EXIF_HEADER = [0x45, 0x78, 0x69, 0x66, 0x00, 0x00]; // "Exif\0\0"
+const ORIENTATION_TAG = 0x0112;
+const SHORT = 3;
+
+/**
+ * The orientation (1–8) an APP1 payload declares, or `1` when it declares none or cannot be read.
+ * Never throws: EXIF is metadata beside the image, and a malformed block is one the decoder
+ * ignores too — refusing the whole image over it would fail a file every browser renders.
+ *
+ * `payload` is the segment body after its length word.
+ */
+export function exifOrientation(payload: Uint8Array): number {
+  if (payload.length < EXIF_HEADER.length + 8) return 1;
+  if (EXIF_HEADER.some((byte, index) => payload[index] !== byte)) return 1;
+  const tiff = payload.subarray(EXIF_HEADER.length);
+  const view = new DataView(tiff.buffer, tiff.byteOffset, tiff.byteLength);
+  const order = view.getUint16(0);
+  if (order !== 0x4949 && order !== 0x4d4d) return 1;
+  const little = order === 0x4949;
+  if (view.getUint16(2, little) !== 42) return 1;
+  const ifd = view.getUint32(4, little);
+  if (ifd + 2 > tiff.length) return 1;
+  const entries = view.getUint16(ifd, little);
+  for (let index = 0; index < entries; index += 1) {
+    const at = ifd + 2 + index * 12;
+    if (at + 12 > tiff.length) return 1;
+    if (view.getUint16(at, little) !== ORIENTATION_TAG) continue;
+    if (view.getUint16(at + 2, little) !== SHORT) return 1;
+    const value = view.getUint16(at + 8, little);
+    return value >= 1 && value <= 8 ? value : 1;
+  }
+  return 1;
+}
+
+/** Orientations 5–8 transpose the image: the stored width is the displayed height. */
+export const swapsAxes = (orientation: number): boolean => orientation >= 5 && orientation <= 8;

package/src/image/probe.ts

@@ -5,6 +5,7 @@
 // than in header bytes, so that reading lives in `probe-svg.ts`.
 
 import { imageDecodeFailed, imageUnsupported } from './errors';
+import { exifOrientation, swapsAxes } from './exif-orientation';
 import { hasSvgRoot, probeSvg } from './probe-svg';
 import { assertPixelBudget, type ImageSize } from './raster';
 
@@ -137,9 +138,12 @@ const isStandaloneMarker = (marker: number): boolean =>
 /**
  * Walks segment lengths to the first SOF. Baseline, progressive and lossless all declare their
  * size the same way — probing is not decoding, so a format the decoder refuses still measures.
+ * An EXIF orientation met on the way (APP1, always ahead of the SOF) is applied to the answer,
+ * because the decoder applies it: the box reserved must be the box that renders.
  */
 function probeJpeg(bytes: Uint8Array): ImageSize {
   const view = viewOf(bytes);
+  let orientation = 1;
   let at = 2;
   while (at + 3 < bytes.length) {
     if (byteAt(bytes, at) !== 0xff) {
@@ -164,7 +168,15 @@ function probeJpeg(bytes: Uint8Array): ImageSize {
     const length = view.getUint16(at + 2);
     if (isSofMarker(marker)) {
       requireBytes(bytes, at + 9, 'JPEG', 'the SOF segment width and height');
-      return { width: view.getUint16(at + 7), height: view.getUint16(at + 5) };
+      const width = view.getUint16(at + 7);
+      const height = view.getUint16(at + 5);
+      return swapsAxes(orientation) ? { width: height, height: width } : { width, height };
+    }
+    // The first APP1 declaring a turn decides; XMP also rides APP1 and reads as none.
+    if (marker === 0xe1 && orientation === 1 && length >= 2) {
+      orientation = exifOrientation(
+        bytes.subarray(at + 4, Math.min(bytes.length, at + 2 + length)),
+      );
     }
     if (length < 2) {
       throw imageDecodeFailed(`JPEG segment 0xFF${marker.toString(16)} declares length ${length}`, {

package/src/in-process-fetch.ts

@@ -0,0 +1,39 @@
+// Where a SERVER-side typed call goes when its answer lives in this process. The build's
+// measurement render has no server to reach, so a route `load` reading the app's own queries over
+// `queryClient()` failed as the network; the process that owns the route table answers instead.
+//
+// ZERO bytes in a browser, by construction: the transport's dispatch already calls
+// `globalThis.fetch` at call time, so this module wraps THAT, once, in the process that first opens
+// a scope — and only a server process ever imports this module. Outside a scope the wrapper hands
+// every call to the fetch it wrapped, untouched. The first version added a slot read to the
+// dispatch itself, and that was 46 B in every island that calls `rpc()` or `queryClient()`.
+import { asyncContext } from './async-context';
+import type { FetchLike } from './client-dispatch';
+
+const scope = asyncContext<FetchLike>('the in-process dispatch');
+
+const INSTALLED: unique symbol = Symbol.for('ultimate.in-process-fetch');
+
+/** Wrap `globalThis.fetch` once per process; a re-wrap after someone replaced it wraps theirs. */
+function install(): void {
+  const current = globalThis.fetch as typeof fetch & { [INSTALLED]?: true };
+  if (current[INSTALLED] === true) return;
+  const wrapped = (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    const inProcess = scope.get();
+    if (inProcess === undefined) return current(input, init);
+    const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+    return inProcess(url, init ?? {});
+  };
+  globalThis.fetch = Object.assign(wrapped, current, { [INSTALLED]: true as const });
+}
+
+/**
+ * Run `fn` with every `fetch` inside it — so every `clientTransport` call, `queryClient()` and
+ * `rpc()` included — answered by `fetchImpl`: the app's own HTTP pipeline handed a `Request`,
+ * rather than the network. A caller's explicit `fetchImpl` never reaches `globalThis.fetch` at all,
+ * so a test's double is never overridden by an ambient scope.
+ */
+export function withInProcessFetch<T>(fetchImpl: FetchLike, fn: () => T): T {
+  install();
+  return scope.run(fetchImpl, fn);
+}

package/src/index.ts

@@ -14,6 +14,7 @@
 // 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.
+import './core-error-codes';
 import './schema-error-codes';
 
 export type {
@@ -40,13 +41,19 @@ export {
   userActor,
   withFacts,
 } from './actor';
+export type { AddressClass } from './address-class';
+export { 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 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';
 export type { BackoffCurve, BackoffOptions, JitterMode, Random } from './backoff';
 export { backoffDelay } from './backoff';
 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';
 /**
  * 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
@@ -61,6 +68,23 @@ export type {
   FlightPlan,
 } from './client-flight';
 export { createClientFlight, DEFAULT_CLIENT_RETRY, isTransientFailure } from './client-flight';
+export type { ActionRoute } from './client-paths';
+export {
+  actionPath,
+  actionRoute,
+  pluralize,
+  QUERY_PATH_PREFIX,
+  queryPath,
+  splitWords,
+} from './client-paths';
+export type { TransportFailure } from './client-problem';
+/**
+ * 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.
+ */
+export type { ClientScope } from './client-scope';
+export { onRescope, rescope } from './client-scope';
+export { clientTransport } from './client-transport';
 /** What a typed client puts on the wire. `retryForStatus` is what fills a failure's `retry`. */
 export type { WireAnswer } from './client-wire';
 export { FRAMEWORK_CODE, problemOf, retryForStatus, traceHeaders } from './client-wire';
@@ -74,6 +98,7 @@ export type {
   AuthConfig,
   CacheConfig,
   DatabaseConfig,
+  DrainConfig,
   JobsConfig,
   McpConfig,
   NotifyConfig,
@@ -86,6 +111,8 @@ export type {
 export { defineConfig, INBOX_RETENTION_KEYS } from './config';
 export type { PwaColors, PwaConfig, PwaOfflineConfig, PwaSchemeColors } from './config-pwa';
 export { PWA_COLOR_KEYS, PWA_SCHEMES } from './config-pwa';
+export type { ConflictPolicy, ResolveConflictOptions, Row } from './conflict-policy';
+export { resolveConflict } from './conflict-policy';
 export type { Ctx, CtxFacts, CtxInit, CtxPatch, CtxServices, ServiceBag } from './context';
 export {
   createContext,
@@ -109,6 +136,8 @@ export {
   usesDevCursorSecret,
 } from './cursor';
 export { compareDecimalText } from './decimal-order';
+export type { DevSecretsOptions } from './dev-secrets';
+export { assertNoDevSecretsOutsideLocal, CursorSecretDevError } from './dev-secrets';
 export type {
   Env,
   EnvBooleanVar,
@@ -296,22 +325,13 @@ export {
   noopErrorReporter,
   noopExporter,
   noopMetricExporter,
-  OTEL_SAMPLER_ARG_KEY,
-  OTEL_SAMPLER_KEY,
-  OTLP_ENDPOINT_KEY,
-  OTLP_HEADERS_KEY,
-  OTLP_PROTOCOL_KEY,
-  OTLP_SCOPE,
   OtlpEndpointInvalidError,
   OtlpHeadersInvalidError,
   OtlpProtocolUnsupportedError,
-  OVERFLOW_ATTRIBUTE,
-  otlpAttributes,
   otlpEndpoint,
   otlpHeaders,
   otlpMetricExporter,
   otlpMetricsRequest,
-  otlpResource,
   otlpSpanExporter,
   otlpTraceRequest,
   parentBasedRatioSampler,
@@ -329,7 +349,6 @@ export {
   reportError,
   requestDuration,
   requests,
-  resetDefaultSampler,
   resetErrorReporting,
   resetMetrics,
   resetTelemetry,
@@ -344,7 +363,6 @@ export {
   startSpan,
   traceparent,
   tryOtlpEndpoint,
-  unixNano,
   withSpan,
   withSpanContext,
 } from './exports/observability';
@@ -372,25 +390,15 @@ export {
   masterKeyPath,
   openSecrets,
   parseMasterKey,
-  parseSecretsEnvelope,
   readSecretsFile,
   requireMasterKey,
   revealOptionalSecret,
   revealSecret,
-  SECRET_BRAND,
-  SECRET_NAME,
-  SECRETS_ALG,
   SECRETS_ERROR_CODES,
   SECRETS_FILE,
-  SECRETS_IV_BYTES,
-  SECRETS_KEY_BYTES,
   SECRETS_KEY_ENV,
   SECRETS_KEY_FILE,
-  SECRETS_KEY_HEX_LENGTH,
-  SECRETS_KEY_ID_LENGTH,
   SECRETS_KEY_MODE,
-  SECRETS_TAG_BYTES,
-  SECRETS_VERSION,
   SecretsFileInvalidError,
   SecretsFileMissingError,
   SecretsKeyInvalidError,
@@ -403,6 +411,7 @@ export {
   secretsFileExists,
   secretsPath,
   serializeSecretValues,
+  stagedMasterKeyPath,
   writeMasterKeyFile,
   writeSecretsFile,
 } from './exports/secrets';
@@ -417,6 +426,8 @@ export { createFlightGate, gateOverloaded } from './flight-gate';
 export { formatBytes } from './format-bytes';
 export type { GenerationFence } from './generation-fence';
 export { createFence, isSuperseded } from './generation-fence';
+export type { HostDecision, HostRule } from './host-rules';
+export { ANY_HOST, hostDecision, hostMatches } from './host-rules';
 export type { Brand, Id } from './ids';
 export {
   isSpanId,
@@ -432,7 +443,7 @@ export {
   uuid,
   uuidTimestamp,
 } from './ids';
-export { fitBox, type ImageFit, type ResizeSpec, scaledToFit } from './image/canvas';
+export type { ImageFit, ResizeSpec } from './image/canvas';
 export { parseColor } from './image/color';
 export {
   ImageDecodeFailedError,
@@ -464,13 +475,12 @@ 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 {
-  assertPixelBudget,
   createRaster,
   hasAlpha,
   MAX_IMAGE_PIXELS,
-  rasterFrom,
 } from './image/raster';
 export { impersonate, impersonationReason, isImpersonating } from './impersonate';
+export { withInProcessFetch } from './in-process-fetch';
 export {
   assertLocale,
   cachedFormatter,
@@ -479,6 +489,7 @@ export {
   MAX_CACHED_FORMATTERS,
   MAX_LOCALE_EXCERPT,
 } from './intl-cache';
+export { isIsoDateTime } from './iso-date';
 export { isJsonObject } from './json-object';
 export type {
   HealthPayload,
@@ -492,7 +503,6 @@ export type {
   ShutdownHook,
   ShutdownPhase,
   ShutdownReason,
-  SignalHandlerOptions,
 } from './lifecycle';
 export {
   beginWork,
@@ -503,25 +513,56 @@ export {
   healthzPayload,
   idleWaiterCount,
   inflightCount,
-  installSignalHandlers,
   isDraining,
   lifecycleState,
   markReady,
   onShutdown,
   readinessCheckCount,
   readinessChecks,
+  readinessGraceMs,
   readyzPayload,
   registerReadinessCheck,
   resetLifecycle,
   SHUTDOWN_PHASES,
   shutdownHookCount,
 } from './lifecycle';
+export {
+  defaultReadinessGraceMs,
+  READINESS_GRACE_DEFAULT_MS,
+  READINESS_GRACE_MAX_MS,
+} from './lifecycle-grace';
+export type { SignalHandlerOptions } from './lifecycle-signals';
+export { installSignalHandlers } from './lifecycle-signals';
 export { isSelfOrigin, listeningOrigins, markListening, resetListeners } from './listeners';
 export type { Direction } from './locale-direction';
 export { directionOf, isRtl } from './locale-direction';
 export { isMcpExposed, type McpExposureDeclaration } from './mcp-exposure';
+export type { MeasurementActorFactory } from './measurement-actor';
+export {
+  defineMeasurementActor,
+  MEASUREMENT_ACTOR_ID,
+  measurementActor,
+  resetMeasurementActor,
+} from './measurement-actor';
 export { nearestName } from './nearest-name';
+/** The message pwa's `sw.js` posts and realtime's outbox listens for. */
+export { OUTBOX_DRAIN_MESSAGE, type OutboxDrainMessage } from './outbox-drain';
+/** The `<meta name>`s render writes and the page client, realtime and pwa read. */
+export {
+  APP_UPDATE_MESSAGE,
+  CLIENT_BUILD_META,
+  CLIENT_PERSIST_META,
+  CLIENT_SCOPE_HEADER,
+  CLIENT_SCOPE_META,
+  CLIENT_SYNC_META,
+  CLIENT_SYNC_WORKER_META,
+} from './page-meta';
 export { type CappedBody, readWithinLimit } from './read-capped';
+export type { RecordEnvelope, RecordRows } from './record-envelope';
+export { decodeRecordEnvelope, encodeRecordEnvelope, RECORDS_HEADER } from './record-envelope';
+export { RECORDS_OPENAPI_HEADER, recordEnvelopeSchema } from './record-envelope-openapi';
+export type { PageClient, RecordSink } from './record-sink';
+export { pageClient } from './record-sink';
 export type {
   ModuleRegistrar,
   PrimitiveFactory,
@@ -541,8 +582,6 @@ export {
   REQUEST_TIMEOUT_HEADER,
   remainingBudgetMs,
 } from './request-budget';
-export type { Err, Ok, Result } from './result';
-export { err, isErr, isOk, map, mapErr, ok, tryCatch, unwrap, unwrapOr } from './result';
 export type { RetryDecision, RetryDeps, RetryPolicy, RetryStopReason } from './retry';
 export { retry, retryDecision } from './retry';
 export { isRetryableStatus, RETRYABLE_STATUSES } from './retryable-status';
@@ -551,7 +590,13 @@ export { DEFAULT_ROLE, isRole, ROLE_INFO, ROLES, resolveRole } from './roles';
 export type { HydrateStrategy, OfflineStrategy, RenderMode } from './route-vocabulary';
 export { HYDRATE_STRATEGIES, OFFLINE_STRATEGIES, RENDER_MODES } from './route-vocabulary';
 export { safeUrl, URL_ATTRIBUTES } from './safe-url';
-export { defineService, resetServices, type ServiceFactory } from './service';
+export {
+  defineService,
+  installedServices,
+  registeredServiceNames,
+  resetServices,
+  type ServiceFactory,
+} from './service';
 export type { FlightJoin, Scheduler, SingleFlight, SingleFlightOptions } from './single-flight';
 export { createSingleFlight } from './single-flight';
 export { endOfLiteral, maskLiterals, QUOTES, stripComments } from './source-mask';
@@ -561,7 +606,6 @@ export {
   readPackageVersion,
   resolveVersion,
   VERSION_DEFINE,
-  VERSION_MANIFEST,
 } from './version';
 // The webhook wire format, at the tier both halves can reach — `@ultimat3/jobs` signs a delivery
 // and `@ultimat3/http` verifies one, and neither may import the other. Same argument
@@ -584,3 +628,9 @@ export {
   webhookSignature,
   webhookSigningString,
 } from './webhook-signature';
+/**
+ * A write's public name — the digest of its idempotency key — and the server scope that carries it
+ * from `@ultimat3/action`'s HTTP projection to the layers that stamp it on a `records` frame.
+ */
+export { isWriteDigest, WRITE_DIGEST_LENGTH, writeDigest } from './write-digest';
+export { currentWriteOrigin, WRITE_ORIGIN_WAL_PREFIX, withWriteOrigin } from './write-origin';

package/src/iso-date.ts

@@ -0,0 +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.
+
+export { isIsoDateTime } from '@ultimat3/schema';

package/src/lifecycle-grace.ts

@@ -0,0 +1,44 @@
+// Single responsibility: the readiness grace's default and its domain. One module because the
+// config validator and `configureLifecycle` must refuse the same values and default the same way.
+
+import { countIssue } from './config-count';
+import { tryResolveEnvironment } from './environment';
+
+/**
+ * Outside a local environment. Long enough for the endpoints controller to observe `/readyz` at
+ * 503 and for kube-proxy/the ingress to stop routing here (`periodSeconds: 5` in the shipped chart
+ * is the dominant term); short enough to sit well inside a 30s `terminationGracePeriodSeconds`
+ * beside the 25s drain budget it is ADDED to.
+ */
+export const READINESS_GRACE_DEFAULT_MS = 5000;
+
+/** A grace past a minute is a stalled rollout, not a drain. */
+export const READINESS_GRACE_MAX_MS = 60_000;
+
+type EnvRecord = Readonly<Record<string, string | undefined>>;
+
+/**
+ * `0` in `development`/`test`, where no load balancer is routing and a Ctrl-C should be instant;
+ * the full grace everywhere else. FAILS CLOSED: a process naming no environment — or a
+ * `ULTIMATE_ENV` that is not one — is production here, because the process that forgot to say is
+ * exactly the one a 502 on every deploy would reach.
+ */
+export function defaultReadinessGraceMs(env?: EnvRecord): number {
+  const environment = tryResolveEnvironment({ env, fallback: 'production' });
+  return environment === 'development' || environment === 'test' ? 0 : READINESS_GRACE_DEFAULT_MS;
+}
+
+/**
+ * Why a value is not a grace, or `undefined` when it is one. A whole number of milliseconds in
+ * `0 ≤ v ≤ 60000`; a fraction is refused rather than rounded, since `setTimeout` would round it
+ * and nothing would say so.
+ */
+export function readinessGraceIssue(value: unknown): string | undefined {
+  const count = countIssue(GRACE_KEY, value, 0);
+  if (count !== undefined) return count;
+  return (value as number) > READINESS_GRACE_MAX_MS
+    ? `${GRACE_KEY} must be at most ${READINESS_GRACE_MAX_MS} milliseconds — a longer grace is a stalled rollout, not a drain`
+    : undefined;
+}
+
+const GRACE_KEY = 'drain.readinessGraceMs';

package/src/lifecycle-signals.ts

@@ -0,0 +1,35 @@
+// Single responsibility: wiring process signals to the one drain. Split from `lifecycle.ts`, which
+// owns the state machine and the phases, when the readiness grace took it past its line ceiling.
+
+import { drain, type ProcessSignal } from './lifecycle';
+
+export interface SignalHandlerOptions {
+  readonly signals?: readonly ProcessSignal[] | undefined;
+  /** Call `process.exit()` once drained. Off in tests. */
+  readonly exit?: boolean | undefined;
+}
+
+/** Install SIGTERM/SIGINT handling. Returns an uninstall function. */
+export function installSignalHandlers(options?: SignalHandlerOptions): () => void {
+  const signals: readonly ProcessSignal[] = options?.signals ?? ['SIGTERM', 'SIGINT'];
+  const handlers = new Map<ProcessSignal, () => void>();
+
+  for (const signal of signals) {
+    const handler = (): void => {
+      // Attached on BOTH settle paths, for the reason `settleWithin` gives: an unhandled rejection
+      // ends the process before the drain does, and the exit is what the kubelet is waiting for.
+      // `drain()` cannot reject today — that is `runDrain`'s `try/finally` in `lifecycle.ts`, not luck — and this is
+      // the one line that keeps it true when someone changes the body.
+      const done = (): void => {
+        if (options?.exit === true) process.exit(0);
+      };
+      void drain(signal).then(done, done);
+    };
+    handlers.set(signal, handler);
+    process.on(signal, handler);
+  }
+
+  return () => {
+    for (const [signal, handler] of handlers) process.off(signal, handler);
+  };
+}