@ultimat3/core 24.0.0 → 25.0.0

package/src/client-problem.ts

@@ -11,6 +11,33 @@ import type { ErrorRetry } from './error-retry';
 import { UltimateError } from './errors';
 import { isJsonObject } from './json-object';
 
+/**
+ * The longest remote title a client renders. Every framework title is well under it; a body that
+ * sends more is not a title, and the overflow is cut rather than trusted.
+ */
+export const MAX_REMOTE_TITLE_LENGTH = 120;
+
+/**
+ * A problem document's `title`, as untrusted DISPLAY text: a non-blank string of at most
+ * `MAX_REMOTE_TITLE_LENGTH` code points, control and format characters removed, or nothing. It reaches every renderer as text — `<ErrorState>` writes
+ * it as a JSX text node, the terminal and `--json` as a string — and `UltimateError` makes it one
+ * line, so no markup or second log line rides in on it. Used only where this realm registered no
+ * title for the code (`UltimateErrorInit.remoteTitle`).
+ */
+export function remoteTitleOf(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  // Control characters become a space and format characters (`\p{Cf}`: bidi overrides, isolates,
+  // zero-width joiners) are dropped BEFORE the cap, so the cap is the length shown — escaping a
+  // newline after cutting rendered two characters for one — and the cut is by CODE POINT, so it
+  // never leaves half a surrogate pair.
+  const shown = value
+    .replace(/\p{Cc}+/gu, ' ')
+    .replace(/\p{Cf}/gu, '')
+    .replace(/ {2,}/g, ' ');
+  const title = Array.from(shown.trim()).slice(0, MAX_REMOTE_TITLE_LENGTH).join('').trim();
+  return title === '' ? undefined : title;
+}
+
 /** An absolute HTTP(S) link, or nothing: a server's `docs` is data and may be `javascript:`. */
 const HTTP_URL = /^https?:\/\/[^\s]+$/;
 
@@ -19,15 +46,23 @@ const HTTP_URL = /^https?:\/\/[^\s]+$/;
  * marked `origin: 'remote'` — the code may be one this bundle never registered. Anything else is
  * a proxy or a gateway answering instead of the app.
  */
-export function problemError(status: number, text: string, url: string): UltimateError {
+export function problemError(
+  status: number,
+  text: string,
+  url: string,
+  retryAfterSeconds?: number,
+): UltimateError {
   const body = problemOf(text);
   const code = body['code'];
+  // The delay a 429 or 503 named, under core's ONE spelling (`statedDelayMs` reads it), so the
+  // flight waits what the responder said whether or not this realm registered the code.
+  const stated = retryAfterSeconds === undefined ? {} : { retryAfterSeconds };
   if (typeof code !== 'string' || !FRAMEWORK_CODE.test(code)) {
     return transportFailed(
       'status',
       `${url} answered HTTP ${status} without a problem+json body naming a framework code`,
-      retryForStatus('X_CLIENT_TRANSPORT_FAILED', status),
-      { url, status },
+      retryForStatus('X_CLIENT_TRANSPORT_FAILED', status, retryAfterSeconds),
+      { url, status, ...stated },
     );
   }
   const docs = [body['docs'], body['type']].find(
@@ -37,13 +72,34 @@ export function problemError(status: number, text: string, url: string): Ultimat
     code,
     cause: text1(body['cause']) ?? text1(body['detail']) ?? `${url} failed with HTTP ${status}`,
     fix: text1(body['fix']) ?? `x errors explain ${renderFixShellArg(code, '<code>')} --json`,
-    retry: retryForStatus(code, status),
-    // The server's declared keys FIRST, so the three this decoder owns win a collision.
-    meta: { ...serverMeta(body['meta'], body['issues']), origin: 'remote', status, url },
+    remoteTitle: remoteTitleOf(body['title']),
+    retry: retryForStatus(code, status, retryAfterSeconds),
+    // The server's declared keys FIRST, so the ones this decoder owns win a collision.
+    meta: withStatedDelay(
+      { ...serverMeta(body['meta'], body['issues']), origin: 'remote', status, url },
+      retryAfterSeconds,
+    ),
     ...(docs === undefined ? {} : { docs }),
   });
 }
 
+/**
+ * A remote error's `meta` with the delay the HEADER stated, and only that: a `retryAfterSeconds`
+ * copied off the problem body is dropped first. The framework's server never writes one there —
+ * `registerProblemMeta` refuses framework codes, and an error carrying the key gets a
+ * `Retry-After` header from `@ultimat3/http` (exposed cross-origin by its CORS default) — so a body
+ * value is never the server's statement, and it must not drive a wait `statedDelayMs` reads. The
+ * one rule for both decoders: this one and `@ultimat3/action`'s `RemoteActionError`.
+ */
+export function withStatedDelay(
+  meta: Readonly<Record<string, unknown>>,
+  retryAfterSeconds: number | undefined,
+): Record<string, unknown> {
+  // Object rest copies own keys with CreateDataProperty, so a parsed `__proto__` stays a plain key.
+  const { retryAfterSeconds: _fromTheBody, ...kept } = meta;
+  return retryAfterSeconds === undefined ? kept : { ...kept, retryAfterSeconds };
+}
+
 /**
  * WHICH way no usable answer came back, on `meta.failure` — what a caller branches on, since the
  * code is the same for all three: `network` (no response at all — the one an offline outbox

package/src/client-retry-after.ts

@@ -0,0 +1,47 @@
+/**
+ * A `Retry-After` header off the wire, as the delay a responder named — the one reader core has.
+ * `clientTransport` hands it to the decoders, so a browser waits what a 429 or 503 said even when
+ * it never loaded the package that registered the code's `retry-after` class.
+ */
+
+/**
+ * The longest stated delay a client will take at its word: one day. A responder naming a year is a
+ * misconfigured proxy, not a schedule, and `retryDecision` still clamps to the policy's own `max`.
+ */
+export const MAX_RETRY_AFTER_SECONDS = 86_400;
+
+/** RFC 9110 delta-seconds: `1*DIGIT`, nothing else — no sign, no fraction, no exponent. */
+const DELTA_SECONDS = /^\d+$/;
+
+/**
+ * Seconds to wait, or `undefined` when the header is absent or is neither form. A date is measured
+ * against the SAME response's `Date` header — the responder's clock against the responder's clock,
+ * so a browser whose clock is an hour off still waits what was meant — and a date with no `Date`
+ * beside it (or one a cross-origin response does not expose) is ignored, as is `0` or a past date.
+ */
+export function retryAfterSecondsOf(
+  header: string | null,
+  date: string | null,
+): number | undefined {
+  if (header === null) return undefined;
+  const value = header.trim();
+  if (DELTA_SECONDS.test(value)) return stated(Number(value));
+  // RFC 9110's preferred HTTP-date, IMF-fixdate (`Wed, 21 Oct 2015 07:28:00 GMT`), is exactly what
+  // `toUTCString()` writes — so the round trip IS the format check, and it also refuses a day
+  // `Date.parse` rolled forward (`31 Feb`) and the two obsolete forms, whose parse is engine-defined.
+  const at = Date.parse(value);
+  const now = date === null ? Number.NaN : Date.parse(date);
+  if (!Number.isFinite(at) || !Number.isFinite(now) || new Date(at).toUTCString() !== value) {
+    return undefined;
+  }
+  return stated(Math.ceil((at - now) / 1_000));
+}
+
+/**
+ * Only a POSITIVE delay is a statement — the rule `@ultimat3/http`'s `retryAfterOf` applies
+ * outbound and realtime's sync protocol applies to `held`. A `0` or a date already past reads as
+ * "retry now", which is the stampede: every attempt fires at once and a webhook dead-letters in
+ * seconds. Unstated, the caller falls back to its own jittered curve instead.
+ */
+const stated = (seconds: number): number | undefined =>
+  seconds > 0 ? Math.min(seconds, MAX_RETRY_AFTER_SECONDS) : undefined;

package/src/client-transport.ts

@@ -5,7 +5,7 @@
  * deduped when a `ClientFlight` is supplied. Anything else is a write: never deduped, never
  * aborted by the fence, and its records never adopted across one.
  *
- * `createClientFlight` is NOT imported here at value level — a caller passes one, and only then
+ * `clientFlight` is NOT imported here at value level — a caller passes one, and only then
  * does its graph enter the bundle. Neither is `traceHeaders()`: the trace and budget headers come
  * from an outbound slot that `runWithContext`/`startSpan` fill SERVER-side (`outbound-headers.ts`),
  * so a browser, which never has either, carries zero bytes of telemetry, context or logger.
@@ -44,6 +44,8 @@ export async function clientTransport<T = unknown>(req: TransportRequest): Promi
               ? flight.keyFor(req.url, { signal: req.signal, fresh: req.fresh })
               : undefined,
             abortable: read,
+            // The caller's own signal ends a WAIT between attempts; each attempt already reads it.
+            signal: req.signal,
             // A stream is read once, so a second attempt re-sends a body that is already spent —
             // and fails as the network would, until the attempts run out. One attempt, always.
             retry: req.rawBody instanceof ReadableStream ? ONCE : req.retry,

package/src/client-wire.ts

@@ -81,9 +81,22 @@ export function problemOf(text: string): Record<string, unknown> {
   return isJsonObject(body) ? body : {};
 }
 
+/** The statuses whose `Retry-After` names a delay to wait (RFC 9110 §10.2.3), and no others. */
+const RETRY_AFTER_STATUSES: ReadonlySet<number> = new Set([429, 503]);
+
 /**
  * The classification a failure off the wire carries, or `undefined` to leave the code's own
- * standing. The STATUS decides only when nobody has declared one for the code: a 503 is the
+ * standing.
+ *
+ * A 429 or 503 that STATED a delay (`retryAfterSeconds`, read off `Retry-After` by
+ * `retryAfterSecondsOf`) is `retry-after` by status: the header is the responder's own word, and
+ * a browser often never loaded the package that registered the code's class — before this, a 429
+ * from `@ultimat3/http` read as `retryable` in an island and was retried on the backoff curve
+ * instead of after the delay it named. A registered class yields to it, because `retryable` says
+ * less than a stated delay — except `terminal`, which is somebody's decision that the same call
+ * fails forever, and a header does not overrule that.
+ *
+ * Otherwise the STATUS decides only when nobody has declared one for the code: a 503 is the
  * canonical "send it again", but `X_NOT_IMPLEMENTED` behind a 501 and a config fault behind a 500
  * are permanent answers somebody already gave, and a status that overrode them would have a client
  * hammer a service that will refuse it identically forever.
@@ -92,7 +105,18 @@ export function problemOf(text: string): Record<string, unknown> {
  * so before this every 502 out of a typed client read as "never try again", on the one field the
  * framework promises a client never has to infer.
  */
-export function retryForStatus(code: string, status: number): ErrorRetry | undefined {
-  if (declaredErrorRetry(code) !== undefined) return undefined;
+export function retryForStatus(
+  code: string,
+  status: number,
+  retryAfterSeconds?: number,
+): ErrorRetry | undefined {
+  const declared = declaredErrorRetry(code);
+  if (
+    retryAfterSeconds !== undefined &&
+    RETRY_AFTER_STATUSES.has(status) &&
+    declared !== 'terminal'
+  )
+    return 'retry-after';
+  if (declared !== undefined) return undefined;
   return isRetryableStatus(status) ? 'retryable' : undefined;
 }

package/src/config-ai.ts

@@ -0,0 +1,32 @@
+// Single responsibility: the `ai` block of `app.config.ts` — whether the app's MCP endpoints are
+// mounted. Split from `config.ts`, which sits at its 500-line ceiling; the merge and the
+// screen stay there, as `jobs` and `cache` do.
+
+import type { Input } from './config-merge';
+
+/**
+ * No `path` (deleted in 25.0.0). It moved endpoint #0 off its own `defineAppMcp({ path })` while
+ * that endpoint's RFC 9728 metadata and advertised resource still named the defineAppMcp path —
+ * with OAuth on, a client was told of a resource at a URL nothing served. Where an endpoint mounts
+ * is `defineAppMcp`'s one fact; a written `ai.mcp.path` is refused (`config-removed.ts`).
+ */
+export interface McpConfig {
+  readonly expose: boolean;
+}
+
+/**
+ * No `modelEnv` (deleted in 8.0.0; refused by name since 25.0.0, `config-removed.ts`). It named the
+ * env KEY holding the model id, "so no model string is baked into the image" — and its only reader
+ * was `config.ts`'s own merge, copying input to output, so `modelEnv: 'ANTHROPIC_MODEL'` selected
+ * no model: `@ultimat3/ai` reads env for API KEYS only. There is no framework default model either
+ * (since 25.0.0): an app names the model on the prompt or on `llm({ model })` — read your own env
+ * key and pass it there.
+ */
+export interface AiConfig {
+  readonly mcp: McpConfig;
+}
+
+/** `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;
+}

package/src/config-defaults.ts

@@ -2,19 +2,17 @@
 // Split from `config.ts`, which sits at its 500-line ceiling; literals only, so it reads no key.
 
 import type { AppConfig } from './config';
+import { JOBS_CONCURRENCY_DEFAULT } from './config-jobs';
+import { DRAIN_DEADLINE_DEFAULT_MS } from './drain-deadline';
 import { defaultReadinessGraceMs } from './lifecycle-grace';
 import { ROLES } from './roles';
 
-/** The keys `config-site.ts`, `config-navigation.ts` and `config-islands.ts` default themselves. */
-type Sectioned = 'name' | 'site' | 'seo' | 'navigation' | 'islands';
+/** The keys their own files default: `config-site.ts`, `-navigation`, `-islands`, `-mail`. */
+type Sectioned = 'name' | 'site' | 'seo' | 'navigation' | 'islands' | 'mail';
 
 export function configDefaults(name: string): Omit<AppConfig, Sectioned> {
   return {
-    locales: ['en'],
-    defaultLocale: 'en',
-    defaultTimeZone: 'UTC',
-    defaultCurrency: 'USD',
-    theme: { defaultMode: 'system', tokens: {} },
+    theme: { defaultMode: 'system' },
     auth: { signInPath: null },
     pwa: {
       enabled: false,
@@ -29,18 +27,27 @@ export function configDefaults(name: string): Omit<AppConfig, Sectioned> {
     cache: { defaultTtlMs: 60_000, tiers: ['request-memo', 'lru'] },
     jobs: {
       queues: [`${name}-default`],
-      concurrency: 8,
+      concurrency: JOBS_CONCURRENCY_DEFAULT,
       maxAttempts: 5,
       backoff: 'exponential',
       visibilityTimeoutMs: 30_000,
     },
     // 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 },
+    // `maxSubscriptionsPerActor` unset means the sync node's own default, `DEFAULT_MAX_PER_ACTOR`
+    // (1,000) in `@ultimat3/realtime` — a tenth of its 10,000 windows, so no one actor fills it.
+    realtime: {
+      enabled: true,
+      transport: 'memory',
+      urlEnv: undefined,
+      maxSubscriptionsPerActor: undefined,
+      // Unset: the sync node's `DEFAULT_MAX_SOCKETS_PER_ACTOR` (16).
+      maxSocketsPerActor: undefined,
+    },
     notify: { inboxReadRetentionMs: undefined, inboxUnreadRetentionMs: undefined },
-    ai: { mcp: { expose: true, path: '/mcp' } },
+    ai: { mcp: { expose: true } },
     // Read from the process env when the config is DEFINED — the same env the drain will run in.
-    drain: { readinessGraceMs: defaultReadinessGraceMs() },
+    drain: { readinessGraceMs: defaultReadinessGraceMs(), deadlineMs: DRAIN_DEADLINE_DEFAULT_MS },
     health: { readiness: 'dependencies' },
   };
 }

package/src/config-fixes.ts

@@ -4,16 +4,6 @@
 
 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

package/src/config-health.ts

@@ -25,7 +25,7 @@ export interface HealthConfig {
 }
 
 /**
- * How a SIGTERM'd process leaves the load balancer. Read by `@ultimat3/http`'s `createServer`
+ * How a SIGTERM'd process leaves the load balancer. Read by `@ultimat3/http`'s `httpServer`
  * (`ServerOptions.drain`), which hands it to core's `configureLifecycle`.
  */
 export interface DrainConfig {
@@ -33,9 +33,16 @@ 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.
+   * plus `deadlineMs`.
    */
   readonly readinessGraceMs: number;
+  /**
+   * The drain budget: how long a SIGTERM'd process has to finish what it holds — in-flight requests,
+   * a running job — after the grace, before the lifecycle abandons the rest. Applied to EVERY role,
+   * so this is the knob that gives a long job room to finish on a deploy. Default 25000. A whole
+   * number, 1–3600000. The ONE drain budget, the web role's included.
+   */
+  readonly deadlineMs: number;
 }
 
 /** Why a value is not a readiness mode, or `undefined` when it is one. */

package/src/config-jobs.ts

@@ -0,0 +1,51 @@
+// Single responsibility: `jobs.concurrency`'s domain — one slot count for every queue a worker
+// serves, or a table of slots per queue (issue #676). Takes the value as `unknown` and names no
+// other key, so `config.ts` keeps its one-line-per-key rule list.
+
+import { countIssue } from './config-count';
+import { describeValue } from './error-render';
+import { isJsonObject } from './json-object';
+
+/**
+ * `jobs.concurrency` when no layer says, and what a queue the table does NOT name gets: the
+ * number an app that never wrote `concurrency` runs every queue at. ONE constant, read by
+ * `@ultimat3/jobs`' `jobWorker` for its own default too — it kept a 5 until 25.0.0, so a
+ * `concurrency: { banks: 4 }` left `default` at 5 beside an unset config's 8.
+ */
+export const JOBS_CONCURRENCY_DEFAULT = 8;
+
+/** One slot count for every queue, or slots per queue name — `jobWorker`'s own `concurrency`. */
+export type JobsConcurrency = number | Readonly<Record<string, number>>;
+
+const KEY = 'jobs.concurrency';
+
+/** A queue name is shown quoted: it is the typo, and a blank one is otherwise invisible. */
+const quoted = (name: string): string => `"${name}"`;
+
+/**
+ * Why `value` is not a `jobs.concurrency`, one issue per wrong entry. A table must name at least
+ * one queue: `{}` reads as "every queue at the default", which the number form already says — an
+ * empty table is a config whose author meant to write something and did not.
+ */
+export function jobsConcurrencyIssues(value: unknown): readonly string[] {
+  if (typeof value === 'number') {
+    const count = countIssue(KEY, value, 1);
+    return count === undefined ? [] : [count];
+  }
+  if (!isJsonObject(value)) {
+    return [
+      `${KEY} must be a whole number of at least 1, or a table of slots per queue like { mail: 4 }, not ${describeValue(value)}`,
+    ];
+  }
+  const entries = Object.entries(value);
+  if (entries.length === 0) {
+    return [`${KEY} must name at least one queue, or be a number for every queue`];
+  }
+  const issues: string[] = [];
+  for (const [queue, slots] of entries) {
+    if (queue.trim() === '') issues.push(`${KEY} names ${quoted(queue)}, not a queue`);
+    const count = countIssue(`${KEY}.${queue}`, slots, 1);
+    if (count !== undefined) issues.push(count);
+  }
+  return issues;
+}

package/src/config-keys.ts

@@ -0,0 +1,170 @@
+// Single responsibility: `app.config.ts` is a CLOSED shape — a key the framework does not declare,
+// at any depth and in any layer, is refused by path with the key it most likely meant. A key that
+// is merged and read by nothing is the switch with no wire, and a typo (`drian`) is the same defect.
+
+import { BASE_FIX } from './config-fixes';
+import type { MailRetainMimeConfig } from './config-mail';
+import type { NavigationConfig, SpeculationConfig } from './config-navigation';
+import type {
+  PwaColors,
+  PwaConfig,
+  PwaImage,
+  PwaSchemeColors,
+  PwaScreenshot,
+  PwaShortcut,
+} from './config-pwa';
+import { ConfigInvalidError } from './errors';
+import { isJsonObject } from './json-object';
+import { nearestName } from './nearest-name';
+
+type Unlisted<T, K extends readonly string[]> = Exclude<keyof T & string, K[number]>;
+
+/**
+ * Every key of `T`, or a type error naming the one left out: a member added to an interface below
+ * without a row here would be a key the screen refuses, so the omission is `tsc`'s, not an app's.
+ */
+const keysOf =
+  <T>() =>
+  <const K extends readonly (keyof T & string)[]>(
+    keys: K & ([Unlisted<T, K>] extends [never] ? unknown : { readonly unlisted: Unlisted<T, K> }),
+  ): K =>
+    keys;
+
+/**
+ * The sections the DEFAULTS cannot show: optional members with no default (`pwa.id`), blocks that
+ * default to `undefined` or `false` (`pwa.colors`, `mail.retainMime`), list elements (`[]`), and
+ * `navigation`, which `defineConfig` leaves out of its shape reference. Everywhere else the known
+ * keys are the defaults' own — derived, never a second hand list.
+ */
+export const SECTION_KEYS: Readonly<Record<string, readonly string[]>> = Object.freeze({
+  pwa: keysOf<PwaConfig>()([
+    'enabled',
+    'offline',
+    'backgroundSync',
+    'push',
+    'name',
+    'colors',
+    'id',
+    'description',
+    'categories',
+    'shortcuts',
+    'screenshots',
+  ]),
+  'pwa.colors': keysOf<PwaColors>()(['light', 'dark']),
+  'pwa.colors.light': keysOf<PwaSchemeColors>()(['themeColor', 'backgroundColor']),
+  'pwa.colors.dark': keysOf<PwaSchemeColors>()(['themeColor', 'backgroundColor']),
+  'pwa.shortcuts[]': keysOf<PwaShortcut>()(['name', 'shortName', 'description', 'url', 'icons']),
+  'pwa.shortcuts[].icons[]': keysOf<PwaImage>()(['src', 'sizes', 'type', 'purpose']),
+  'pwa.screenshots[]': keysOf<PwaScreenshot>()(['src', 'sizes', 'type', 'formFactor', 'label']),
+  'mail.retainMime': keysOf<MailRetainMimeConfig>()(['maxBytes']),
+  navigation: keysOf<NavigationConfig>()(['client', 'speculation']),
+  'navigation.speculation': keysOf<SpeculationConfig>()(['prefetch', 'exclude']),
+});
+
+/**
+ * The positions whose KEYS the app chooses, never walked: each is a `PwaText`, one string or a
+ * record keyed by locale tag (`{ en: …, 'es-co': … }`), and a locale is not a key this file knows.
+ */
+export const OPEN_CONFIG_PATHS: ReadonlySet<string> = new Set([
+  'pwa.description',
+  'pwa.shortcuts[].name',
+  'pwa.shortcuts[].shortName',
+  'pwa.shortcuts[].description',
+  'pwa.screenshots[].src',
+  'pwa.screenshots[].label',
+]);
+
+export interface UnknownConfigKey {
+  /** As an app reads it: `pwa.shortcuts[0].href`. */
+  readonly path: string;
+  /** The keys its section does hold, in declared order. */
+  readonly known: readonly string[];
+  /** The nearest of `known`, when one is close enough to be the typo. */
+  readonly near: string | undefined;
+}
+
+const join = (path: string, key: string): string => (path === '' ? key : `${path}.${key}`);
+
+/**
+ * CLOSED BY DEFAULT: an object is walked wherever it is written, its known keys the reference's
+ * plus `SECTION_KEYS`' — so an object at a key whose default is `undefined` (`realtime.urlEnv`)
+ * knows no keys and every one is refused. Two exceptions: `OPEN_CONFIG_PATHS`, and a position the
+ * defaults hold a VALUE at (`site.origin: null`), whose own rule names the wrong value in better
+ * words than "unknown key".
+ */
+/** `SECTION_KEYS`' row for `path`, own keys only: a layer key `constructor` must not read the prototype. */
+const sectionKeysAt = (path: string): readonly string[] | undefined =>
+  Object.hasOwn(SECTION_KEYS, path) ? SECTION_KEYS[path] : undefined;
+
+function walk(
+  reference: unknown,
+  layer: unknown,
+  at: { readonly schema: string; readonly shown: string },
+  found: UnknownConfigKey[],
+): void {
+  if (OPEN_CONFIG_PATHS.has(at.schema)) return;
+  if (Array.isArray(layer)) {
+    // A list's elements are walked only where an element is a declared section (`pwa.shortcuts`);
+    // `jobs.queues` holds names, and a wrong element there is the name screen's to refuse.
+    const element = `${at.schema}[]`;
+    if (sectionKeysAt(element) === undefined) return;
+    for (const [index, item] of layer.entries()) {
+      walk(undefined, item, { schema: element, shown: `${at.shown}[${index}]` }, found);
+    }
+    return;
+  }
+  if (!isJsonObject(layer)) return;
+  const declared = sectionKeysAt(at.schema);
+  if (declared === undefined && reference !== undefined && !isJsonObject(reference)) return;
+  const ref = isJsonObject(reference) ? reference : {};
+  const known = [...new Set([...Object.keys(ref), ...(declared ?? [])])];
+  for (const [key, value] of Object.entries(layer)) {
+    if (value === undefined) continue;
+    const next = { schema: join(at.schema, key), shown: join(at.shown, key) };
+    if (!known.includes(key)) {
+      found.push({ path: next.shown, known, near: nearestName(key, known) });
+      continue;
+    }
+    walk(ref[key], value, next, found);
+  }
+}
+
+/** Every key one layer writes that `reference` (the defaults) and `SECTION_KEYS` do not declare. */
+export function unknownConfigKeys(reference: unknown, layer: unknown): readonly UnknownConfigKey[] {
+  const found: UnknownConfigKey[] = [];
+  walk(reference, layer, { schema: '', shown: '' }, found);
+  return found;
+}
+
+const parentOf = (path: string): string => {
+  const cut = path.lastIndexOf('.');
+  return cut === -1 ? '' : path.slice(0, cut);
+};
+
+const issueOf = (key: UnknownConfigKey): string =>
+  `${key.path} is not an app.config.ts key${key.near === undefined ? '' : ` — did you mean ${key.near}?`}`;
+
+const holds = (key: UnknownConfigKey): string =>
+  key.known.length === 0
+    ? `${parentOf(key.path)} is a value, not a section`
+    : `${parentOf(key.path) || 'the top level'} holds ${key.known.join(', ')}`;
+
+const fixOf = (key: UnknownConfigKey): string =>
+  key.near === undefined
+    ? `delete ${key.path} from app.config.ts — ${holds(key)}`
+    : `rename ${key.path} to ${join(parentOf(key.path), key.near)} in app.config.ts`;
+
+/**
+ * Every layer asked, so a stale `config/realtime.ts` overlay is caught as surely as the base, and
+ * every unknown key named in ONE refusal rather than one per restart.
+ */
+export function refuseUnknownKeys(reference: unknown, layers: readonly unknown[]): void {
+  const unknown = layers.flatMap((layer) => unknownConfigKeys(reference, layer));
+  if (unknown.length === 0) return;
+  const issues = unknown.map(issueOf);
+  throw new ConfigInvalidError({
+    cause: issues.join('; '),
+    fix: [...new Set(unknown.map(fixOf)), BASE_FIX].join('. '),
+    meta: { issues, unknown: [...new Set(unknown.map((key) => key.path))] },
+  });
+}

package/src/config-mail.ts

@@ -0,0 +1,73 @@
+// Single responsibility: the `mail` block of `app.config.ts` — what the boot hands
+// `@ultimat3/mail`'s `selectMailDriver` that an environment cannot say. Its own file for the
+// reason `config-islands.ts` is: shape, merge and screen are one subject, and `config.ts` is at its
+// 500-line ceiling.
+
+import { describeValue } from './error-render';
+import { isJsonObject } from './json-object';
+
+/**
+ * Keep the exact MIME bytes the SMTP and SES transports hand their provider, bounded — the audit
+ * half of a send (`SendResult.mime`). `false` keeps nothing, the default. `maxBytes` unset is
+ * mail's own default cap; its ceiling is mail's to enforce, at driver selection
+ * (`X_CONFIG_INVALID`), because tier 0 cannot import the package that owns the number. Resend
+ * builds the MIME on its own side, so asking for it with `RESEND_API_KEY` set refuses the boot.
+ *
+ * Data only: the durable `onRetained` callback is a function and lives with the code that writes
+ * the audit row, not in a config value.
+ */
+export interface MailRetainMimeConfig {
+  readonly maxBytes: number | undefined;
+}
+
+export interface MailConfig {
+  readonly retainMime: MailRetainMimeConfig | false;
+}
+
+export interface MailSection {
+  readonly mail: MailConfig;
+}
+
+export interface MailSectionInput {
+  readonly mail?:
+    | {
+        /** `true` is `{}` — retained under mail's default cap. */
+        readonly retainMime?: boolean | { readonly maxBytes?: number | undefined } | undefined;
+      }
+    | undefined;
+}
+
+/** The last layer that said it wins, as every scalar does. `true` is the default cap. */
+export function mergeMail(layers: readonly MailSectionInput[]): MailSection {
+  let retainMime: MailConfig['retainMime'] = false;
+  for (const layer of layers) {
+    const said = layer.mail?.retainMime;
+    if (said === undefined) continue;
+    if (said === true) retainMime = { maxBytes: undefined };
+    else if (isJsonObject(said)) retainMime = { maxBytes: said['maxBytes'] as number | undefined };
+    // `false`, or a wrong value from an untyped file — `'yes'`, `[]` — carried through AS WRITTEN
+    // for `mailIssues` to refuse: read as an object it became `{ maxBytes: undefined }`, retention
+    // switched on. `isJsonObject`, never `typeof`: a list is an object to `typeof`.
+    else retainMime = said as MailConfig['retainMime'];
+  }
+  return { mail: { retainMime } };
+}
+
+/** Appends every refusal the section earns to `issues`, `config.ts`' one list. */
+export function mailIssues(config: MailSection, issues: string[]): void {
+  // `unknown`: an untyped config file reaches this validator with whatever it wrote.
+  const retain: unknown = config.mail.retainMime;
+  if (retain === false) return;
+  if (!isJsonObject(retain)) {
+    issues.push(
+      `mail.retainMime must be true, false or { maxBytes }, not ${describeValue(retain)}`,
+    );
+    return;
+  }
+  const maxBytes: unknown = retain['maxBytes'];
+  if (maxBytes !== undefined && (!Number.isSafeInteger(maxBytes) || (maxBytes as number) < 1)) {
+    issues.push(
+      `mail.retainMime.maxBytes must be a whole number of bytes above 0, not ${describeValue(maxBytes)}`,
+    );
+  }
+}

package/src/config-merge.ts

@@ -36,7 +36,7 @@ export function layered<T extends object>(base: T, patches: readonly (Input<T> |
   return patches.reduce<T>((out, patch) => section(out, patch), base);
 }
 
-/** A whole-value key (`locales`, `roles`): the last layer that said something wins. */
+/** A whole-value key (`roles`, `jobs.queues`): 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;