@ultimat3/core 23.0.0 → 25.0.0

package/src/image/png-pixels.ts

@@ -3,6 +3,14 @@
 // safe zone `@ultimat3/pwa` promises is a composite. So this file exists for exactly that one hop:
 // Bun re-encodes to PNG, this reads the pixels back, `canvas.ts` blits, this writes them again.
 
+// why: `Bun.inflateSync` takes no output bound — measured, it ignores `maxOutputLength` and
+// returns the whole stream — and `DecompressionStream` is async where this seam is synchronous.
+// `node:zlib` is the one inflate here that can be told when to stop. A NAMESPACE import, never a
+// named one: the browser polyfill of this module has no `inflateRawSync`, and a named import of a
+// missing export fails the BUNDLE of every browser graph that reaches the barrel
+// (`async-context.test.ts` builds one) — for a function no browser ever calls.
+import * as zlib from 'node:zlib';
+import { stringField } from '../error-render';
 import { imageDecodeFailed, imageUnsupported } from './errors';
 import {
   adler32,
@@ -14,7 +22,7 @@ import {
   unshared,
   writeU32,
 } from './png-bytes';
-import { type Raster, rasterFrom } from './raster';
+import { assertPixelBudget, type Raster, rasterFrom } from './raster';
 
 /** Truecolour with alpha, 8 bits per channel — the ONE shape `Raster` is. */
 const RGBA_COLOR_TYPE = 8 << 4;
@@ -105,8 +113,13 @@ function readHeader(bytes: Uint8Array): PngHeader {
   return { width: readU32(bytes, 16), height: readU32(bytes, 20) };
 }
 
-/** Every IDAT concatenated: a PNG may split its stream across any number of them. */
-function idatStream(bytes: Uint8Array): Uint8Array {
+/**
+ * Every IDAT concatenated — a PNG may split its stream across any number of them — and inflated
+ * to AT MOST `limit` bytes, which is what the header says the pixels need. Inflating first and
+ * measuring after is the decompression bomb: deflate packs zeros ~1000:1, so a file of a few
+ * hundred kilobytes declaring 1x1 allocated hundreds of megabytes before anything compared it to 5.
+ */
+function idatStream(bytes: Uint8Array, limit: number): Uint8Array {
   const parts: Uint8Array[] = [];
   let at = 8;
   while (at + 12 <= bytes.length) {
@@ -123,8 +136,16 @@ function idatStream(bytes: Uint8Array): Uint8Array {
   try {
     // The 2-byte zlib header and the 4-byte Adler-32 trailer are PNG's envelope, stripped here
     // so the payload inflates as RAW deflate — see the encoder above for the mirror image.
-    return Bun.inflateSync(unshared(stream.subarray(2, stream.length - 4)), { windowBits: -15 });
-  } catch {
+    return zlib.inflateRawSync(unshared(stream.subarray(2, stream.length - 4)), {
+      maxOutputLength: limit,
+    });
+  } catch (error) {
+    if (stringField(error, 'code') === 'ERR_BUFFER_TOO_LARGE') {
+      throw imageDecodeFailed(
+        `the PNG IDAT stream inflates to more than the ${limit} bytes its header's size needs`,
+        { length: stream.length, limit },
+      );
+    }
     throw imageDecodeFailed(`the PNG IDAT stream (${stream.length} bytes) could not be inflated`, {
       length: stream.length,
     });
@@ -171,8 +192,10 @@ function unfilter(raw: Uint8Array, width: number, height: number): Uint8ClampedA
 /** PNG bytes to RGBA pixels. Refuses anything but 8-bit RGBA, naming the pipeline that reads it. */
 export function decodeImage(bytes: Uint8Array): Raster {
   const { width, height } = readHeader(bytes);
-  const raw = idatStream(bytes);
+  // From the HEADER, before the stream is touched: it bounds `expected`, which bounds the inflate.
+  assertPixelBudget(width, height, 'PNG');
   const expected = (width * BYTES_PER_PIXEL + 1) * height;
+  const raw = idatStream(bytes, expected);
   if (raw.length !== expected) {
     throw imageDecodeFailed(
       `the PNG inflates to ${raw.length} bytes but ${width}x${height} RGBA needs ${expected}`,

package/src/image/probe.ts

@@ -66,8 +66,13 @@ function requireBytes(bytes: Uint8Array, needed: number, format: string, missing
 
 const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] as const;
 
-/** `mif1` is the generic HEIF brand AVIF files carry; `avis` is an image sequence. */
-const AVIF_BRANDS: ReadonlySet<string> = new Set(['avif', 'avis', 'mif1']);
+/**
+ * `avif` is a still, `avis` an image sequence. NOT `mif1`: that is the generic HEIF brand, which
+ * an AVIF file lists as a COMPATIBLE brand and a HEIC file lists too — counting it sniffed every
+ * iPhone photo as AVIF, and the probe then read (or failed to read) it as one. An AVIF whose major
+ * brand is `mif1` still names `avif` among its compatible brands, which the scan below reads.
+ */
+const AVIF_BRANDS: ReadonlySet<string> = new Set(['avif', 'avis']);
 
 function isAvif(bytes: Uint8Array): boolean {
   if (!ascii(bytes, 4, 'ftyp')) return false;

package/src/image/raster.ts

@@ -25,7 +25,9 @@ export const MAX_IMAGE_PIXELS = 64_000_000;
 /** Checked from the header before a single byte is allocated. */
 export function assertPixelBudget(width: number, height: number, source: string): void {
   if (!Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1) {
-    throw imageTooLarge(`${source} declares a ${width}x${height} image, which is not a size`, {
+    // Decode-failed, not too-large: a header declaring zero, a fraction or `NaN` pixels is
+    // inconsistent bytes, and the too-large fix — downscale it — has nothing to act on.
+    throw imageDecodeFailed(`${source} declares a ${width}x${height} image, which is not a size`, {
       width,
       height,
       source,
@@ -41,7 +43,7 @@ export function assertPixelBudget(width: number, height: number, source: string)
 }
 
 /** A transparent canvas of the given size, budget already checked. */
-export function createRaster(width: number, height: number, source = 'raster'): Raster {
+export function blankRaster(width: number, height: number, source = 'raster'): Raster {
   assertPixelBudget(width, height, source);
   return { width, height, pixels: new Uint8ClampedArray(width * height * 4) };
 }
@@ -61,6 +63,29 @@ export function rasterFrom(width: number, height: number, pixels: Uint8ClampedAr
   return { width, height, pixels };
 }
 
+/** A rectangle of a raster, in its pixels. */
+export interface ImageRegion extends ImageSize {
+  readonly x: number;
+  readonly y: number;
+}
+
+/** The pixels of `region`, copied row by row. The region must lie inside the raster. */
+export function cropRaster(raster: Raster, region: ImageRegion): Raster {
+  const { x, y, width, height } = region;
+  if (x < 0 || y < 0 || x + width > raster.width || y + height > raster.height) {
+    throw imageDecodeFailed(
+      `crop ${width}x${height}+${x}+${y} lies outside the ${raster.width}x${raster.height} raster`,
+      { x, y, width, height, rasterWidth: raster.width, rasterHeight: raster.height },
+    );
+  }
+  const out = blankRaster(width, height, 'crop');
+  for (let row = 0; row < height; row += 1) {
+    const from = ((y + row) * raster.width + x) * 4;
+    out.pixels.set(raster.pixels.subarray(from, from + width * 4), row * width * 4);
+  }
+  return out;
+}
+
 /** Whether any pixel is not fully opaque — decides PNG vs JPEG when nobody asked. */
 export function hasAlpha(raster: Raster): boolean {
   const { pixels } = raster;

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,8 +198,13 @@ export {
   useService,
   withChildContext,
 } from './context';
+/** 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,
@@ -174,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,
@@ -194,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,
@@ -267,7 +313,6 @@ export {
   statedDelayMs,
   stringField,
   toUltimateError,
-  ULTIMATE_ERROR_BRAND,
   UltimateError,
 } from './exports/error-contract';
 export type {
@@ -336,7 +381,6 @@ export {
   configureTelemetry,
   connections,
   counter,
-  createLogger,
   currentSampler,
   currentSpan,
   currentSpanContext,
@@ -403,6 +447,7 @@ export {
   setLogStream,
   startMetricExport,
   startSpan,
+  structuredLogger,
   traceparent,
   tryOtlpEndpoint,
   withSpan,
@@ -432,6 +477,7 @@ export {
   masterKeyPath,
   openSecrets,
   parseMasterKey,
+  promoteStagedMasterKey,
   readSecretsFile,
   requireMasterKey,
   revealOptionalSecret,
@@ -443,6 +489,7 @@ export {
   SECRETS_KEY_MODE,
   SecretsFileInvalidError,
   SecretsFileMissingError,
+  SecretsKeyAclError,
   SecretsKeyInvalidError,
   SecretsKeyMismatchError,
   SecretsKeyMissingError,
@@ -454,6 +501,7 @@ export {
   secretsPath,
   serializeSecretValues,
   stagedMasterKeyPath,
+  stageMasterKeyFile,
   writeMasterKeyFile,
   writeSecretsFile,
 } from './exports/secrets';
@@ -464,12 +512,16 @@ 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';
 export { ANY_HOST, hostDecision, hostMatches } from './host-rules';
+export { escapeHtml } from './html-escape';
 export type { Brand, Id } from './ids';
 export {
   isSpanId,
@@ -482,8 +534,8 @@ export {
   spanId,
   traceId,
   typedId,
-  uuid,
   uuidTimestamp,
+  uuidV7,
 } from './ids';
 export type { ImageFit, ResizeSpec } from './image/canvas';
 export { parseColor } from './image/color';
@@ -517,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';
@@ -579,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';
@@ -588,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,
@@ -614,8 +673,11 @@ export {
   CLIENT_SYNC_META,
   CLIENT_SYNC_WORKER_META,
 } from './page-meta';
+/** The structural Postgres seam http, auth, action and jobs share without a `@ultimat3/db` edge. */
+export type { PgExecutor } from './pg-executor';
 export type { ProcessMetricsOptions, ProcessReading } from './process-metrics';
 export { readProcess, resetProcessMetrics, startProcessMetrics } from './process-metrics';
+export { hasPublicCause, registerPublicCause, resetPublicCauses } from './public-cause';
 export { type CappedBody, readWithinLimit } from './read-capped';
 export type { RecordEnvelope, RecordRows } from './record-envelope';
 export { decodeRecordEnvelope, encodeRecordEnvelope, RECORDS_HEADER } from './record-envelope';
@@ -646,6 +708,7 @@ export { retry, retryDecision } from './retry';
 export { isRetryableStatus, RETRYABLE_STATUSES } from './retryable-status';
 export type { ResolveRoleOptions, Role, RoleInfo, ScalingSignal } from './roles';
 export { DEFAULT_ROLE, isRole, ROLE_INFO, ROLES, resolveRole } from './roles';
+export { routeRank } from './route-rank';
 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';
@@ -676,8 +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) {