@ultimat3/core 21.0.0 → 22.0.0

package/README.md

@@ -8,7 +8,6 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | `UltimateError`, the 3-line rendering, `--json` shape | `errors.ts` |
 | rendering an app's value into a `cause` / `fix` without throwing | `error-render.ts` |
 | code → `{ title, docs }` registry, `registerErrorCodes()` | `error-codes.ts` |
-| `Result<T, E>` for boundaries where throwing is wrong | `result.ts` |
 | the one lazy `AsyncLocalStorage`, every ambient scope in the framework | `async-context.ts` |
 | request context on that seam | `context.ts` |
 | `Actor` (`user \| service \| agent \| anonymous`) | `actor.ts` |
@@ -33,10 +32,12 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | typed env validated at boot | `env.ts` |
 | `.env.example` rendered from that schema, and its drift check | `env-example.ts` |
 | named environments + `ULTIMATE_ENV` resolution | `environment.ts` |
+| the boot refusal of a shipped dev signing secret outside development/test — `X_CURSOR_SECRET_DEV` | `dev-secrets.ts` |
 | a value that cannot be printed by accident | `secret.ts` |
 | the committed encrypted secrets envelope, AES-256-GCM | `secrets.ts` |
 | the two secrets files, and decrypted values → `defineEnv` | `secrets-store.ts` |
 | `defineConfig()` for `app.config.ts` | `config.ts` |
+| how overlays layer onto it — per section, key by key | `config-merge.ts` |
 | the `pwa` block — what an install needs, and the boot refusal when it is not there | `config-pwa.ts` |
 | the closed route vocabulary every renderer names | `route-vocabulary.ts` |
 | runtime roles + `ROLE` resolution | `roles.ts` |
@@ -54,6 +55,9 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | the `/metrics` scrape body | `metrics-text.ts` |
 | the series every process emits, incl. what the chart scales on | `runtime-metrics.ts` |
 | graceful drain, `/healthz`, `/readyz` | `lifecycle.ts` |
+| the readiness grace between `/readyz` → 503 and the listener closing (`drain.readinessGraceMs`) | `lifecycle-grace.ts` |
+| SIGTERM/SIGINT → the one drain | `lifecycle-signals.ts` |
+| which network an IP literal belongs to — `classifyAddress`, for SSRF screens | `address-class.ts` |
 | the sockets this process opened, so a self-request is not egress | `listeners.ts` |
 | `defineService('orgs', …)` → `ctx.orgs`, rebuilt per actor | `service.ts` |
 | the registrar table one same-tier package reaches another through | `registrar.ts` |
@@ -164,6 +168,40 @@ Enforced, not documented: `x verify`'s `errors` step fails with `X_ERROR_RENDER_
 parameter typed `unknown` reaches a `cause:` or `fix:` through `JSON.stringify`, `String()` or a
 bare interpolation (`scripts/error-render.ts`).
 
+### Error classes
+
+Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
+a job boundary the class is gone and the `code` is what survives — match on that.
+
+| Class | Code | Declared in |
+|---|---|---|
+| `ConfigInvalidError` | `X_CONFIG_INVALID` | `src/errors.ts` |
+| `CursorInvalidError` | `X_CURSOR_INVALID` | `src/cursor.ts` |
+| `CursorSecretDevError` | `X_CURSOR_SECRET_DEV` | `src/dev-secrets.ts` |
+| `EnvExampleDriftError` | `X_ENV_EXAMPLE_DRIFT` | `src/env-example.ts` |
+| `EnvironmentInvalidError` | `X_ENVIRONMENT_INVALID` | `src/environment.ts` |
+| `EnvMissingError` | `X_ENV_MISSING` | `src/errors.ts` |
+| `ErrorReporterDsnInvalidError` | `X_ERROR_REPORTER_DSN_INVALID` | `src/error-reporter-sentry.ts` |
+| `ImageDecodeFailedError` | `X_IMAGE_DECODE_FAILED` | `src/image/errors.ts` |
+| `ImageTooLargeError` | `X_IMAGE_TOO_LARGE` | `src/image/errors.ts` |
+| `ImageUnsupportedError` | `X_IMAGE_UNSUPPORTED` | `src/image/errors.ts` |
+| `InternalError` | `X_INTERNAL` | `src/errors.ts` |
+| `MetricCardinalityError` | `X_METRIC_CARDINALITY` | `src/metrics.ts` |
+| `MetricNameInvalidError` | `X_METRIC_NAME_INVALID` | `src/metric-names.ts` |
+| `MetricValueInvalidError` | `X_METRIC_VALUE_INVALID` | `src/metrics.ts` |
+| `NotImplementedError` | `X_NOT_IMPLEMENTED` | `src/errors.ts` |
+| `OtlpEndpointInvalidError` | `X_OTLP_ENDPOINT_INVALID` | `src/otlp.ts` |
+| `OtlpHeadersInvalidError` | `X_OTLP_HEADERS_INVALID` | `src/otlp.ts` |
+| `OtlpProtocolUnsupportedError` | `X_OTLP_PROTOCOL_UNSUPPORTED` | `src/otlp.ts` |
+| `SecretsFileInvalidError` | `X_SECRETS_FILE_INVALID` | `src/secrets-errors.ts` |
+| `SecretsFileMissingError` | `X_SECRETS_FILE_MISSING` | `src/secrets-errors.ts` |
+| `SecretsKeyInvalidError` | `X_SECRETS_KEY_INVALID` | `src/secrets-errors.ts` |
+| `SecretsKeyMismatchError` | `X_SECRETS_KEY_MISMATCH` | `src/secrets-errors.ts` |
+| `SecretsKeyMissingError` | `X_SECRETS_KEY_MISSING` | `src/secrets-errors.ts` |
+| `SecretsPlaintextInvalidError` | `X_SECRETS_PLAINTEXT_INVALID` | `src/secrets-errors.ts` |
+| `SecretsTamperedError` | `X_SECRETS_TAMPERED` | `src/secrets-errors.ts` |
+| `UltimateError` | any registered code — every class in the framework extends it | `src/errors.ts` |
+
 ## Context
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "21.0.0",
+  "version": "22.0.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",
@@ -40,6 +40,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/schema": "21.0.0"
+    "@ultimat3/schema": "22.0.0"
   }
 }

package/src/address-class.ts

@@ -0,0 +1,143 @@
+// Single responsibility: which kind of network an IP address literal belongs to. Tier 0 because the
+// SSRF screens that need it sit in packages that may not import each other — `@ultimat3/jobs`'
+// webhook delivery (tier 3) and `@ultimat3/scraping` (tier 5) — and a copy per screen is how one
+// of them comes to miss `::ffff:127.0.0.1`.
+
+/**
+ * `reserved` is every range that is neither a host network nor public: multicast, broadcast,
+ * `240.0.0.0/4`, the documentation and benchmarking nets. A screen allowing only `public` refuses
+ * all of them, which is the point of naming them rather than calling them public.
+ */
+export type AddressClass =
+  | 'loopback'
+  | 'private'
+  | 'link-local'
+  | 'ula'
+  | 'cgnat'
+  | 'unspecified'
+  | 'reserved'
+  | 'public';
+
+/** `[network, prefixBits]` over the 32-bit value; ordered, first match wins. */
+const V4_RULES: readonly (readonly [number, number, AddressClass])[] = [
+  [0x00000000, 8, 'unspecified'],
+  [0x7f000000, 8, 'loopback'],
+  [0x0a000000, 8, 'private'],
+  [0xac100000, 12, 'private'],
+  [0xc0a80000, 16, 'private'],
+  [0xa9fe0000, 16, 'link-local'],
+  [0x64400000, 10, 'cgnat'],
+  [0xc0000000, 24, 'reserved'], // 192.0.0.0/24, IETF protocol assignments
+  [0xc0000200, 24, 'reserved'], // 192.0.2.0/24, TEST-NET-1
+  [0xc6120000, 15, 'reserved'], // 198.18.0.0/15, benchmarking
+  [0xc6336400, 24, 'reserved'], // 198.51.100.0/24, TEST-NET-2
+  [0xcb007100, 24, 'reserved'], // 203.0.113.0/24, TEST-NET-3
+  [0xe0000000, 4, 'reserved'], // multicast
+  [0xf0000000, 4, 'reserved'], // 240.0.0.0/4 and the broadcast address inside it
+];
+
+/**
+ * Strict dotted quad: four decimal octets, no leading zero. `010.0.0.1` is octal to some parsers
+ * and decimal to others, so it is not an address this module will vouch for — a screen that
+ * refuses what it cannot classify is the only safe reader of it.
+ */
+function parseV4(text: string): number | undefined {
+  const parts = text.split('.');
+  if (parts.length !== 4) return undefined;
+  let value = 0;
+  for (const part of parts) {
+    if (!/^(?:0|[1-9]\d{0,2})$/.test(part)) return undefined;
+    const octet = Number(part);
+    if (octet > 255) return undefined;
+    value = value * 256 + octet;
+  }
+  return value;
+}
+
+function classifyV4(value: number): AddressClass {
+  for (const [network, bits, kind] of V4_RULES) {
+    const size = 2 ** (32 - bits);
+    if (value >= network && value < network + size) return kind;
+  }
+  return 'public';
+}
+
+/** Eight 16-bit groups, or `undefined`. A trailing dotted quad fills the last two. */
+function parseV6(text: string): readonly number[] | undefined {
+  let body = text;
+  let tail: number[] = [];
+  const lastColon = body.lastIndexOf(':');
+  if (body.includes('.', lastColon)) {
+    const v4 = parseV4(body.slice(lastColon + 1));
+    if (v4 === undefined) return undefined;
+    tail = [Math.floor(v4 / 0x10000), v4 % 0x10000];
+    // `::ffff:1.2.3.4` keeps `::ffff`; `::1.2.3.4` keeps its `::`, the one colon that is syntax.
+    const head = body.slice(0, lastColon + 1);
+    body = head.endsWith('::') ? head : head.slice(0, -1);
+  }
+  const halves = body.split('::');
+  if (halves.length > 2) return undefined;
+  const groups = (half: string): number[] | undefined => {
+    if (half === '') return [];
+    const out: number[] = [];
+    for (const group of half.split(':')) {
+      if (!/^[0-9a-f]{1,4}$/i.test(group)) return undefined;
+      out.push(Number.parseInt(group, 16));
+    }
+    return out;
+  };
+  const head = groups(halves[0] ?? '');
+  const rest = halves.length === 2 ? groups(halves[1] ?? '') : [];
+  if (head === undefined || rest === undefined) return undefined;
+  const width = head.length + rest.length + tail.length;
+  if (halves.length === 1) return width === 8 ? [...head, ...tail] : undefined;
+  if (width > 7) return undefined;
+  return [...head, ...new Array<number>(8 - width).fill(0), ...rest, ...tail];
+}
+
+const embeddedV4 = (g: readonly number[]): number => (g[6] ?? 0) * 0x10000 + (g[7] ?? 0);
+
+function classifyV6(g: readonly number[]): AddressClass {
+  const zeroUpTo = (n: number): boolean => g.slice(0, n).every((group) => group === 0);
+  if (zeroUpTo(8)) return 'unspecified';
+  if (zeroUpTo(7) && g[7] === 1) return 'loopback';
+  // IPv4-mapped `::ffff:a.b.c.d`, IPv4-compatible `::a.b.c.d` and NAT64 `64:ff9b::/96`: each is
+  // routed to the IPv4 address it carries, so that address is what gets classified.
+  if (zeroUpTo(5) && g[5] === 0xffff) return classifyV4(embeddedV4(g));
+  if (zeroUpTo(6)) return classifyV4(embeddedV4(g));
+  if (g[0] === 0x64 && g[1] === 0xff9b && g.slice(2, 6).every((group) => group === 0)) {
+    return classifyV4(embeddedV4(g));
+  }
+  const first = g[0] ?? 0;
+  if ((first & 0xffc0) === 0xfe80) return 'link-local';
+  if ((first & 0xffc0) === 0xfec0) return 'private'; // deprecated site-local
+  if ((first & 0xfe00) === 0xfc00) return 'ula';
+  if ((first & 0xff00) === 0xff00) return 'reserved'; // multicast
+  if (first === 0x2001 && g[1] === 0x0db8) return 'reserved'; // documentation
+  if (first === 0x0100 && g.slice(1, 4).every((group) => group === 0)) return 'reserved'; // 100::/64
+
+  return 'public';
+}
+
+/**
+ * The class of an IP address LITERAL — IPv4, IPv6, bracketed `[::1]`, a zone id `fe80::1%eth0`,
+ * and every IPv6 form carrying an IPv4 address. `undefined` means "not an address literal": a
+ * hostname must be resolved first and each resolved address classified, never this string.
+ */
+export function classifyAddress(address: string): AddressClass | undefined {
+  let text = address.trim();
+  if (text.startsWith('[') && text.endsWith(']')) text = text.slice(1, -1);
+  const zone = text.indexOf('%');
+  if (zone !== -1 && text.includes(':')) text = text.slice(0, zone);
+  if (text.includes(':')) {
+    const groups = parseV6(text);
+    return groups === undefined ? undefined : classifyV6(groups);
+  }
+  const v4 = parseV4(text);
+  return v4 === undefined ? undefined : classifyV4(v4);
+}
+
+/** Fails CLOSED: anything but a literal classified `public` — a hostname included — is `false`. */
+export function isPublicAddress(address: string): boolean {
+  return classifyAddress(address) === 'public';
+}

package/src/canonical-json.ts

@@ -50,6 +50,27 @@ function hashCollection(value: Map<unknown, unknown> | Set<unknown>): string {
   return `${value instanceof Map ? 'Map' : 'Set'}(${entries.sort().join(',')})`;
 }
 
+/** Lowercase hex, two digits a byte. Not `toBase64`: this module ships to browsers that lack it. */
+function hexOf(bytes: Uint8Array): string {
+  let out = '';
+  for (const byte of bytes) out += byte.toString(16).padStart(2, '0');
+  return out;
+}
+
+/**
+ * Tagged, because a typed array's indices ARE own enumerable keys: `Uint8Array([1])` rendered
+ * `{"0":1}`, one key with the plain object `{ 0: 1 }`. The view's OWN window is read, never the
+ * whole backing buffer, and any view but a `Uint8Array` carries its type name — a `Uint16Array([1])`
+ * and a `Uint8Array([1, 0])` hold the same bytes and are different payloads.
+ */
+function hashBytes(value: ArrayBuffer | ArrayBufferView): string {
+  if (value instanceof ArrayBuffer) return `ArrayBuffer(${hexOf(new Uint8Array(value))})`;
+  const bytes = new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  const tag =
+    value instanceof Uint8Array ? 'Bytes' : Object.prototype.toString.call(value).slice(8, -1);
+  return `${tag}(${hexOf(bytes)})`;
+}
+
 /**
  * JSON with object keys sorted at every depth, and every value a JSON document would fold onto
  * `null` or `{}` given a token of its own. No timestamps, no insertion-order leaks.
@@ -64,7 +85,8 @@ export function canonicalJson(value: unknown): string {
     case 'boolean':
       return String(value);
     case 'bigint':
-      return JSON.stringify(`${value}n`);
+      // A bare token like `Date(…)`: quoted as `"5n"`, it was one key with the STRING `'5n'`.
+      return `BigInt(${value})`;
     case 'undefined':
     case 'function':
     case 'symbol':
@@ -77,6 +99,7 @@ export function canonicalJson(value: unknown): string {
   // every set alike.
   if (value instanceof Date) return hashDate(value);
   if (value instanceof Map || value instanceof Set) return hashCollection(value);
+  if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) return hashBytes(value);
   if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
   const record = value as Record<string, unknown>;
   const keys = Object.keys(record)

package/src/client-flight.ts

@@ -275,8 +275,11 @@ export function createClientFlight(options: ClientFlightOptions = {}): ClientFli
       const work = (): Promise<T> =>
         gate === undefined ? dispatch(plan) : gate.run(() => dispatch(plan));
       // The single flight sits OUTSIDE the gate: a joiner takes no slot, so dedup relieves the
-      // ceiling instead of queueing behind it.
-      return settle(plan.key === undefined ? work() : flights.run(plan.key, work), issued);
+      // ceiling instead of queueing behind it. Keyed by GENERATION too: `bump()` aborts the old
+      // flights, but each holds its key until its rejection settles, and a same-key read issued
+      // in that window joined the aborted one and was answered with its AbortError.
+      const key = plan.key === undefined ? undefined : JSON.stringify([issued, plan.key]);
+      return settle(key === undefined ? work() : flights.run(key, work), issued);
     },
 
     get inflight(): number {

package/src/config-count.ts

@@ -0,0 +1,19 @@
+// Single responsibility: the numeric domain a config count or window must sit in. Takes the key as
+// a string and the value as `unknown`, because `validate` is the boundary an untyped JS config
+// crosses — a `'60s'` arrives here however the interface types the field.
+
+import { describeValue } from './error-render';
+
+/**
+ * Why `value` is not a whole number ≥ `min`, or `undefined` when it is one. `NaN`, `Infinity` and
+ * `2.5` each passed `concurrency < 1` — every comparison with `NaN` is false — and a fraction or an
+ * infinity then reaches `Array.from({ length })`, a `setTimeout` or a loop bound.
+ */
+export function countIssue(key: string, value: unknown, min: 0 | 1): string | undefined {
+  if (typeof value === 'number' && Number.isSafeInteger(value) && value >= min) return undefined;
+  // A number is printed as itself — `describeValue` answers "a number" for 2.5 and -3 alike.
+  const shown = typeof value === 'number' ? numberText(value) : describeValue(value);
+  return `${key} must be a whole number ${min === 1 ? 'of at least 1' : 'of 0 or more'}, not ${shown}`;
+}
+
+const numberText = (value: number): string => `${value}`;

package/src/config-fixes.ts

@@ -0,0 +1,23 @@
+// Single responsibility: the remedies `app.config.ts`'s validator appends to X_CONFIG_INVALID. Split
+// from `config.ts` so the validator stays under its line ceiling; each string is carried only when
+// its own key is what failed.
+
+export const BASE_FIX = 'edit app.config.ts to fix the fields named in cause, then run: x verify';
+
+/**
+ * Appended only when the zone is what failed. Axiom 4: an operator holding `'CET'` needs the
+ * spelling to write, and the two refused classes have different remedies — a single-label legacy
+ * name swaps mechanically, an abbreviation or an offset has no replacement at all because it names
+ * no jurisdiction. Deliberately parallel to `@ultimat3/time`'s `X_TIMEZONE_INVALID` fix, since the
+ * two refuse the same strings and an operator may meet either first.
+ */
+export const TIMEZONE_FIX =
+  "set defaultTimeZone to an Area/Location name, or UTC — list every accepted one with bun -e \"console.log(Intl.supportedValuesOf('timeZone').join('\\n'))\" — where a legacy single-label name swaps mechanically (Japan → Asia/Tokyo, GB → Europe/London, Universal → UTC), while an abbreviation or numeric offset (CET, EST5EDT, +01:00) carries no DST rule and has no replacement, so name the city whose clock you mean (Europe/Paris, America/New_York)";
+
+/**
+ * Appended only when a tier name is what failed, and it names the rename rather than the rule: the
+ * three refused spellings are the ones 8.0.0 accepted, and two of them have a mechanical
+ * replacement while `isr` has none — it is a `RenderMode`, and no cache tier ever served it.
+ */
+export const CACHE_TIER_FIX =
+  "in app.config.ts, rewrite cache.tiers with the rung names the ladder serves — request-memo, lru, redis, cdn — where memo becomes request-memo and shared becomes redis, and isr is dropped: it is a render mode, so move it to render: 'isr' on the routes that want it";

package/src/config-merge.ts

@@ -0,0 +1,36 @@
+// Single responsibility: how `defineConfig` layers `app.config.ts` and its `config/*.ts` overlays —
+// per section and key by key. Carries no config KEY on purpose: `config-readers` counts a property
+// access outside `config.ts` as a reader, so this file only ever sees sections as opaque records.
+
+/** A section's patch: every key optional, and an explicit `undefined` meaning "not said". */
+export type Input<T> = { readonly [K in keyof T]?: T[K] | undefined };
+
+/**
+ * Apply a partial section over its defaults. Explicit `undefined` never wins — that is what
+ * makes every config field deeply optional without `exactOptionalPropertyTypes` fighting back.
+ */
+export function section<T extends object>(base: T, patch: Input<T> | undefined): T {
+  if (patch === undefined) return base;
+  const out: Record<string, unknown> = { ...(base as Record<string, unknown>) };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value !== undefined) out[key] = value;
+  }
+  return out as T;
+}
+
+/**
+ * Every layer's patch applied in order, each one KEY BY KEY. The input and the overlays used to be
+ * `Object.assign`ed first and the section merged once, so `{ jobs: { maxAttempts: 9 } }` in an
+ * overlay replaced the base's whole `jobs` patch — its `queues` and `concurrency` fell back to the
+ * framework defaults — and an overlay's `{ realtime: undefined }` erased the base's section.
+ */
+export function layered<T extends object>(base: T, patches: readonly (Input<T> | undefined)[]): T {
+  return patches.reduce<T>((out, patch) => section(out, patch), base);
+}
+
+/** A whole-value key (`locales`, `roles`): the last layer that said something wins. */
+export function lastSaid<T>(base: T, values: readonly (T | undefined)[]): T {
+  let out = base;
+  for (const value of values) if (value !== undefined) out = value;
+  return out;
+}

package/src/config.ts

@@ -7,15 +7,24 @@ import { CURRENCY_CODE_PATTERN } from '@ultimat3/schema';
 // them. Declaring them here is what let `cache.tiers` and the ladder `@ultimat3/cache` orders by
 // drift into two vocabularies with no map between them (issue #293).
 import { CACHE_TIERS, type CacheTierName } from './cache-vocabulary';
+import { countIssue } from './config-count';
+import { BASE_FIX, CACHE_TIER_FIX, TIMEZONE_FIX } from './config-fixes';
+import { type Input, lastSaid, layered } from './config-merge';
 import type { PwaConfig, PwaOfflineConfig } from './config-pwa';
 import { PWA_FIX, pwaIssues } from './config-pwa';
 import { describeValue } from './error-render';
 import { ConfigInvalidError } from './errors';
+import { defaultReadinessGraceMs, readinessGraceIssue } from './lifecycle-grace';
 import { ROLES, type Role } from './roles';
 import { isIanaZoneName } from './time-zone-name';
 
 export type ThemeMode = 'light' | 'dark' | 'system';
-export type RealtimeTransport = 'memory' | 'nats' | 'redis';
+/**
+ * The buses `@ultimat3/realtime`'s `selectTransport` builds, and nothing else. `'redis'` was in
+ * this union until 22.0.0 with no Redis transport anywhere: it booted whatever `NATS_URL` chose.
+ */
+export const REALTIME_TRANSPORTS = ['memory', 'nats'] as const;
+export type RealtimeTransport = (typeof REALTIME_TRANSPORTS)[number];
 
 export interface ThemeConfig {
   readonly defaultMode: ThemeMode;
@@ -172,6 +181,20 @@ export interface AiConfig {
   readonly mcp: McpConfig;
 }
 
+/**
+ * How a SIGTERM'd process leaves the load balancer. Read by `@ultimat3/http`'s `createServer`
+ * (`ServerOptions.drain`), which hands it to core's `configureLifecycle`.
+ */
+export interface DrainConfig {
+  /**
+   * `/readyz` answers 503 for this long before the listener closes, so endpoints stop routing here
+   * first. Default 0 in development/test and 5000 everywhere else — a process naming NO environment
+   * included. A whole number, 0–60000. The chart's `terminationGracePeriodSeconds` must exceed it
+   * plus the drain budget.
+   */
+  readonly readinessGraceMs: number;
+}
+
 export interface AppConfig {
   readonly name: string;
   readonly locales: readonly string[];
@@ -188,10 +211,9 @@ export interface AppConfig {
   readonly realtime: RealtimeConfig;
   readonly notify: NotifyConfig;
   readonly ai: AiConfig;
+  readonly drain: DrainConfig;
 }
 
-type Input<T> = { readonly [K in keyof T]?: T[K] | undefined };
-
 /** `mcp` is the only member, and it is NESTED — `Input<AiConfig>` would make it all-or-nothing. */
 export interface AiConfigInput {
   readonly mcp?: Input<McpConfig> | undefined;
@@ -224,24 +246,12 @@ export interface AppConfigInput {
   readonly realtime?: Input<RealtimeConfig> | undefined;
   readonly notify?: Input<NotifyConfig> | undefined;
   readonly ai?: AiConfigInput | undefined;
+  readonly drain?: Input<DrainConfig> | undefined;
 }
 
 /** An overlay from `config/<concern>.ts`. No `name` — the base owns it. */
 export type AppConfigOverlay = Omit<AppConfigInput, 'name'> & { readonly name?: string };
 
-/**
- * Apply a partial section over its defaults. Explicit `undefined` never wins — that is what
- * makes every config field deeply optional without `exactOptionalPropertyTypes` fighting back.
- */
-function section<T extends object>(base: T, patch: Input<T> | undefined): T {
-  if (patch === undefined) return base;
-  const out: Record<string, unknown> = { ...(base as Record<string, unknown>) };
-  for (const [key, value] of Object.entries(patch)) {
-    if (value !== undefined) out[key] = value;
-  }
-  return out as T;
-}
-
 const NAME_RE = /^[a-z][a-z0-9-]{1,63}$/;
 
 /**
@@ -287,32 +297,16 @@ function defaults(name: string): Omit<AppConfig, 'name'> {
       backoff: 'exponential',
       visibilityTimeoutMs: 30_000,
     },
-    realtime: { enabled: false, transport: 'memory', urlEnv: undefined },
+    // ON by default since 22.0.0, when the boot began obeying the key: an app with no section
+    // keeps the `sync` node it always got, and `enabled: false` is the explicit opt-out.
+    realtime: { enabled: true, transport: 'memory', urlEnv: undefined },
     notify: { inboxReadRetentionMs: undefined, inboxUnreadRetentionMs: undefined },
     ai: { mcp: { expose: true, path: '/mcp' } },
+    // Read from the process env when the config is DEFINED — the same env the drain will run in.
+    drain: { readinessGraceMs: defaultReadinessGraceMs() },
   };
 }
 
-const BASE_FIX = 'edit app.config.ts to fix the fields named in cause, then run: x verify';
-
-/**
- * Appended only when the zone is what failed. Axiom 4: an operator holding `'CET'` needs the
- * spelling to write, and the two refused classes have different remedies — a single-label legacy
- * name swaps mechanically, an abbreviation or an offset has no replacement at all because it names
- * no jurisdiction. Deliberately parallel to `@ultimat3/time`'s `X_TIMEZONE_INVALID` fix, since the
- * two refuse the same strings and an operator may meet either first.
- */
-const TIMEZONE_FIX =
-  "set defaultTimeZone to an Area/Location name, or UTC — list every accepted one with bun -e \"console.log(Intl.supportedValuesOf('timeZone').join('\\n'))\" — where a legacy single-label name swaps mechanically (Japan → Asia/Tokyo, GB → Europe/London, Universal → UTC), while an abbreviation or numeric offset (CET, EST5EDT, +01:00) carries no DST rule and has no replacement, so name the city whose clock you mean (Europe/Paris, America/New_York)";
-
-/**
- * Appended only when a tier name is what failed, and it names the rename rather than the rule: the
- * three refused spellings are the ones 8.0.0 accepted, and two of them have a mechanical
- * replacement while `isr` has none — it is a `RenderMode`, and no cache tier ever served it.
- */
-const CACHE_TIER_FIX =
-  "in app.config.ts, rewrite cache.tiers with the rung names the ladder serves — request-memo, lru, redis, cdn — where memo becomes request-memo and shared becomes redis, and isr is dropped: it is a render mode, so move it to render: 'isr' on the routes that want it";
-
 function validate(config: AppConfig): void {
   const issues: string[] = [];
   // Zero or one entry: the zone's own remedy, carried only when the zone is what failed.
@@ -346,10 +340,25 @@ function validate(config: AppConfig): void {
     issues.push(`defaultCurrency "${config.defaultCurrency}" is not a 3-letter ISO 4217 code`);
   }
   if (config.roles.length === 0) issues.push('roles must list at least one runtime role');
-  if (config.jobs.concurrency < 1) issues.push('jobs.concurrency must be >= 1');
+  // A domain per numeric key, never a bare `< 1`: every comparison with `NaN` is false, so the old
+  // `concurrency < 1` passed `NaN`, `2.5` and `Infinity`, and nothing screened the other three.
+  const counts: readonly (string | undefined)[] = [
+    countIssue('jobs.concurrency', config.jobs.concurrency, 1),
+    countIssue('jobs.maxAttempts', config.jobs.maxAttempts, 1),
+    countIssue('jobs.visibilityTimeoutMs', config.jobs.visibilityTimeoutMs, 1),
+    countIssue('cache.defaultTtlMs', config.cache.defaultTtlMs, 0),
+    readinessGraceIssue(config.drain.readinessGraceMs),
+  ];
+  for (const issue of counts) if (issue !== undefined) issues.push(issue);
   if (config.jobs.queues.length === 0) issues.push('jobs.queues must list at least one queue');
-  if (config.realtime.transport !== 'memory' && config.realtime.urlEnv === undefined) {
-    issues.push(`realtime.transport "${config.realtime.transport}" requires realtime.urlEnv`);
+  // An untyped config reaches here with whatever it wrote: a string is a name worth echoing, and
+  // anything else goes through `describeValue` rather than `${…}`.
+  const transport: unknown = config.realtime.transport;
+  if (!REALTIME_TRANSPORTS.some((known) => known === transport)) {
+    const said = typeof transport === 'string' ? `"${transport}"` : describeValue(transport);
+    issues.push(`realtime.transport ${said} is not one of ${REALTIME_TRANSPORTS.join(', ')}`);
+  } else if (transport === 'nats' && config.realtime.urlEnv === undefined) {
+    issues.push(`realtime.transport "nats" requires realtime.urlEnv`);
   }
   // BOTH RETENTION WINDOWS OR NEITHER — `undefined` is a real value here (never swept) and the
   // only other legal one is a positive, finite count of milliseconds. Zero is refused rather than
@@ -401,35 +410,83 @@ export function defineConfig(
   ...overlays: readonly AppConfigOverlay[]
 ): AppConfig {
   const base = defaults(input.name);
-  // One `Object.assign` over all overlays rather than a spread per overlay: `reduce` with a
-  // spread copies every key again on each step, and config is merged at boot on every start.
-  // `name` is applied last because it identifies the app — an overlay may not rename it.
-  const merged: AppConfigInput = Object.assign({}, input, ...overlays, {
-    name: input.name,
-  }) as AppConfigInput;
+  // Every layer, in order, merged per section and KEY BY KEY — see `layered`. `name` comes from
+  // the input alone because it identifies the app: an overlay may not rename it.
+  const layers: readonly AppConfigOverlay[] = [input, ...overlays];
 
   const config: AppConfig = {
-    name: merged.name,
-    locales: merged.locales ?? base.locales,
-    defaultLocale: merged.defaultLocale ?? base.defaultLocale,
-    defaultTimeZone: merged.defaultTimeZone ?? base.defaultTimeZone,
-    defaultCurrency: merged.defaultCurrency ?? base.defaultCurrency,
-    theme: section(base.theme, merged.theme),
-    auth: section(base.auth, merged.auth),
-    // Two `section` calls, one per level: the outer one may not see `offline` at all, or it would
-    // drop the nested defaults `PwaConfigInput` exists to keep. Hence the cast — the outer patch is
-    // this block minus the key the inner call owns.
+    name: input.name,
+    locales: lastSaid(
+      base.locales,
+      layers.map((layer) => layer.locales),
+    ),
+    defaultLocale: lastSaid(
+      base.defaultLocale,
+      layers.map((layer) => layer.defaultLocale),
+    ),
+    defaultTimeZone: lastSaid(
+      base.defaultTimeZone,
+      layers.map((layer) => layer.defaultTimeZone),
+    ),
+    defaultCurrency: lastSaid(
+      base.defaultCurrency,
+      layers.map((layer) => layer.defaultCurrency),
+    ),
+    theme: layered(
+      base.theme,
+      layers.map((layer) => layer.theme),
+    ),
+    auth: layered(
+      base.auth,
+      layers.map((layer) => layer.auth),
+    ),
+    // Two merges, one per level: the outer one may not see `offline` at all, or it would drop the
+    // nested defaults `PwaConfigInput` exists to keep. Hence the cast — the outer patch is this
+    // block minus the key the inner merge owns.
     pwa: {
-      ...section(base.pwa, { ...merged.pwa, offline: undefined } as Input<PwaConfig>),
-      offline: section(base.pwa.offline, merged.pwa?.offline),
+      ...layered(
+        base.pwa,
+        layers.map((layer) => ({ ...layer.pwa, offline: undefined }) as Input<PwaConfig>),
+      ),
+      offline: layered(
+        base.pwa.offline,
+        layers.map((layer) => layer.pwa?.offline),
+      ),
+    },
+    roles: lastSaid(
+      base.roles,
+      layers.map((layer) => layer.roles),
+    ),
+    database: layered(
+      base.database,
+      layers.map((layer) => layer.database),
+    ),
+    cache: layered(
+      base.cache,
+      layers.map((layer) => layer.cache),
+    ),
+    jobs: layered(
+      base.jobs,
+      layers.map((layer) => layer.jobs),
+    ),
+    realtime: layered(
+      base.realtime,
+      layers.map((layer) => layer.realtime),
+    ),
+    notify: layered(
+      base.notify,
+      layers.map((layer) => layer.notify),
+    ),
+    ai: {
+      mcp: layered(
+        base.ai.mcp,
+        layers.map((layer) => layer.ai?.mcp),
+      ),
     },
-    roles: merged.roles ?? base.roles,
-    database: section(base.database, merged.database),
-    cache: section(base.cache, merged.cache),
-    jobs: section(base.jobs, merged.jobs),
-    realtime: section(base.realtime, merged.realtime),
-    notify: section(base.notify, merged.notify),
-    ai: { mcp: section(base.ai.mcp, merged.ai?.mcp) },
+    drain: layered(
+      base.drain,
+      layers.map((layer) => layer.drain),
+    ),
   };
 
   validate(config);

package/src/core-error-codes.ts

@@ -16,6 +16,7 @@ const CORE_CODE_TITLES = {
   X_CLIENT_TRANSPORT_FAILED: 'a browser request got no answer from the app',
   X_CONFIG_INVALID: 'app.config.ts is invalid',
   X_CURSOR_INVALID: 'pagination cursor is malformed, tampered with or from another query',
+  // `x doctor` reports it; `assertNoDevSecretsOutsideLocal()` throws it at boot.
   X_CURSOR_SECRET_DEV: 'cursors are signed with the shipped development key',
   X_DRAINING: 'process is draining and refuses new work',
   X_ENV_EXAMPLE_DRIFT: '.env.example does not declare every variable the schema requires',