@ultimat3/core 21.0.0 → 22.0.0

package/src/dev-secrets.ts

@@ -0,0 +1,45 @@
+// Single responsibility: the boot refusal of a shipped development signing secret outside a local
+// environment. `x doctor` reported it; nothing failed — so a production pod that forgot
+// ULTIMATE_CURSOR_SECRET signed every cursor with a key published in this package.
+
+import { usesDevCursorSecret } from './cursor';
+import { isLocal } from './environment';
+import { UltimateError } from './errors';
+
+/**
+ * `X_CURSOR_SECRET_DEV`, the code `x doctor` already reports for this key — one condition, one code.
+ * Doctor warns; this refuses the boot.
+ */
+export class CursorSecretDevError extends UltimateError {
+  static readonly code = 'X_CURSOR_SECRET_DEV';
+  override readonly name = 'CursorSecretDevError';
+
+  // One secret today, so the fix is a literal: a spliced name would be a value in a pasted command.
+  constructor() {
+    super({
+      code: CursorSecretDevError.code,
+      cause:
+        'ULTIMATE_CURSOR_SECRET is unset, so this process signs cursors with the development key the framework ships — anyone can forge a page position',
+      fix: "x secrets set ULTIMATE_CURSOR_SECRET — or export ULTIMATE_CURSOR_SECRET from the platform's secret store",
+      meta: { variable: 'ULTIMATE_CURSOR_SECRET' },
+    });
+  }
+}
+
+export interface DevSecretsOptions {
+  /** Which environment the boot is — defaults to `process.env`. */
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+}
+
+/**
+ * Throws when a shipped dev secret is in use and the environment is not `development`/`test`.
+ *
+ * FAILS CLOSED: a process with neither `ULTIMATE_ENV` nor `NODE_ENV` resolves as `production`
+ * here, the answer `templates/scaffold-auth.ts` already gives — `isLocal()`'s own fallback is
+ * `development`, which is exactly the process that forgot to say. The secret itself is read where
+ * signing reads it, so this refuses what the process WILL sign with, not what `env` claims.
+ */
+export function assertNoDevSecretsOutsideLocal(options: DevSecretsOptions = {}): void {
+  if (isLocal({ env: options.env, fallback: 'production' })) return;
+  if (usesDevCursorSecret()) throw new CursorSecretDevError();
+}

package/src/exports/secrets.ts

@@ -66,6 +66,7 @@ export {
   SECRETS_KEY_MODE,
   secretsFileExists,
   secretsPath,
+  stagedMasterKeyPath,
   writeMasterKeyFile,
   writeSecretsFile,
 } from '../secrets-store';

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

@@ -41,6 +41,8 @@ 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';
@@ -96,6 +98,7 @@ export type {
   AuthConfig,
   CacheConfig,
   DatabaseConfig,
+  DrainConfig,
   JobsConfig,
   McpConfig,
   NotifyConfig,
@@ -133,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,
@@ -320,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,
@@ -353,7 +349,6 @@ export {
   reportError,
   requestDuration,
   requests,
-  resetDefaultSampler,
   resetErrorReporting,
   resetMetrics,
   resetTelemetry,
@@ -368,7 +363,6 @@ export {
   startSpan,
   traceparent,
   tryOtlpEndpoint,
-  unixNano,
   withSpan,
   withSpanContext,
 } from './exports/observability';
@@ -396,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,
@@ -427,6 +411,7 @@ export {
   secretsFileExists,
   secretsPath,
   serializeSecretValues,
+  stagedMasterKeyPath,
   writeMasterKeyFile,
   writeSecretsFile,
 } from './exports/secrets';
@@ -441,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,
@@ -456,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,
@@ -488,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,
@@ -503,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,
@@ -516,7 +503,6 @@ export type {
   ShutdownHook,
   ShutdownPhase,
   ShutdownReason,
-  SignalHandlerOptions,
 } from './lifecycle';
 export {
   beginWork,
@@ -527,23 +513,37 @@ 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';
@@ -582,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';
@@ -608,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

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);
+  };
+}

package/src/lifecycle.ts

@@ -7,6 +7,7 @@ import { UltimateError } from './errors';
 import { finiteCount } from './finite-option';
 import { settleWithin } from './lifecycle-deadline';
 import { lifecycleDrained } from './lifecycle-errors';
+import { defaultReadinessGraceMs, readinessGraceIssue } from './lifecycle-grace';
 import { type LogFields, type Logger, logger as rootLogger } from './logger';
 
 export type HealthState = 'starting' | 'ready' | 'draining' | 'stopped';
@@ -54,6 +55,15 @@ export interface LifecycleOptions {
    * 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;
   readonly clock?: Clock | undefined;
   readonly logger?: Logger | undefined;
 }
@@ -111,6 +121,8 @@ interface Registration {
 const DEFAULT_DEADLINE_MS = 25_000;
 
 let deadlineMs = DEFAULT_DEADLINE_MS;
+/** `undefined` means "the environment's default", read when a drain starts, not at import. */
+let graceMs: number | undefined;
 let clock: Clock = systemClock;
 let log: Logger = rootLogger;
 let state: HealthState = 'starting';
@@ -131,6 +143,18 @@ export function configureLifecycle(options: LifecycleOptions): void {
   if (options.deadlineMs !== undefined) {
     deadlineMs = finiteCount('configureLifecycle', 'deadlineMs', options.deadlineMs, 0);
   }
+  if (options.readinessGraceMs !== undefined) {
+    const issue = readinessGraceIssue(options.readinessGraceMs);
+    if (issue !== undefined) {
+      throw new UltimateError({
+        code: 'X_CONFIG_INVALID',
+        cause: issue,
+        fix: 'pass configureLifecycle({ readinessGraceMs: 5_000 }) — or set drain: { readinessGraceMs: 5_000 } in app.config.ts',
+        meta: { key: 'drain.readinessGraceMs' },
+      });
+    }
+    graceMs = options.readinessGraceMs;
+  }
   if (options.clock !== undefined) {
     clock = options.clock;
     startedAtMono = clock.monotonic();
@@ -316,6 +340,11 @@ export function drainDeadlineMs(): number {
   return deadlineMs;
 }
 
+/** The grace the next drain will wait out — configured, else the environment's default. */
+export function readinessGraceMs(): number {
+  return graceMs ?? defaultReadinessGraceMs();
+}
+
 /**
  * What is left of that budget. Read per hook, not per phase: the deadline bounds the WHOLE drain,
  * so a hook that spent it leaves nothing for the ones behind it — which is what
@@ -354,10 +383,20 @@ async function runPhase(phase: ShutdownPhase, reason: ShutdownReason): Promise<v
   }
 }
 
-/** The three phases, in order, under one budget. Never rejects — `drain()` depends on that. */
-async function runDrain(signal: string, reason: ShutdownReason): Promise<void> {
+/**
+ * The three phases, in order, under one budget. Never rejects — `drain()` depends on that.
+ *
+ * The readiness grace runs FIRST and OUTSIDE the budget: `state` is already `draining`, so
+ * `/readyz` answers 503 while the listener still accepts what was routed here before the flip.
+ * The deadline starts after it, so a chart's `terminationGracePeriodSeconds` must exceed
+ * `readinessGraceMs + deadlineMs`.
+ */
+async function runDrain(signal: string): Promise<void> {
   try {
-    report('info', 'draining', { signal, deadlineMs, inflight });
+    const grace = readinessGraceMs();
+    report('info', 'draining', { signal, deadlineMs, readinessGraceMs: grace, inflight });
+    if (grace > 0) await Bun.sleep(grace);
+    const reason: ShutdownReason = { signal, deadlineAt: systemClock.monotonic() + deadlineMs };
     await runPhase('accept', reason);
 
     // Real monotonic, like `deadlineAt` itself: `waitForIdle` sleeps on a real `setTimeout`, and
@@ -401,7 +440,6 @@ async function runDrain(signal: string, reason: ShutdownReason): Promise<void> {
 export function drain(signal = 'manual'): Promise<void> {
   if (drainPromise !== undefined) return drainPromise;
   state = 'draining';
-  const reason: ShutdownReason = { signal, deadlineAt: systemClock.monotonic() + deadlineMs };
   let published!: () => void;
   drainPromise = new Promise<void>((resolve) => {
     published = resolve;
@@ -409,41 +447,10 @@ export function drain(signal = 'manual'): Promise<void> {
   // Both settle paths, for the reason `installSignalHandlers` gives below: `runDrain` cannot
   // reject today — that is its `try/finally`, not luck — and a rejected memo would re-reject for
   // every later caller and end the process the drain was trying to end cleanly.
-  void runDrain(signal, reason).then(published, published);
+  void runDrain(signal).then(published, published);
   return drainPromise;
 }
 
-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 the `try/finally` above, 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);
-  };
-}
-
 export function healthReport(): HealthReport {
   const checks = readinessChecks();
   return {
@@ -479,6 +486,7 @@ export function readyzPayload(): HealthPayload {
 /** Test-only: forget all hooks and return to `starting`. */
 export function resetLifecycle(): void {
   deadlineMs = DEFAULT_DEADLINE_MS;
+  graceMs = undefined;
   clock = systemClock;
   log = rootLogger;
   state = 'starting';