@ultimat3/core 23.0.0 → 25.0.0

package/src/config.ts

@@ -2,31 +2,42 @@
 // defaults, validated eagerly, and composable so a big app can split it across `config/*.ts`
 // without inventing a second config mechanism.
 
-import { CURRENCY_CODE_PATTERN } from '@ultimat3/schema';
 // Same rule for the same reason: `app.config.ts` CONSUMES the cache tier names, it does not own
 // 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 type { AiConfig, AiConfigInput } from './config-ai';
 import { countIssue } from './config-count';
-import { BASE_FIX, CACHE_TIER_FIX, TIMEZONE_FIX } from './config-fixes';
-import type { DrainConfig, HealthConfig } from './config-health';
-import { readinessModeIssue } from './config-health';
+import { configDefaults } from './config-defaults';
+import { BASE_FIX, CACHE_TIER_FIX } from './config-fixes';
+import { type DrainConfig, type HealthConfig, readinessModeIssue } from './config-health';
 import type { IslandsConfig, IslandsSectionInput } from './config-islands';
 import { islandsIssues, mergeIslands } from './config-islands';
+import { type JobsConcurrency, jobsConcurrencyIssues } from './config-jobs';
+import { refuseUnknownKeys } from './config-keys';
+import { type MailConfig, type MailSectionInput, mailIssues, mergeMail } from './config-mail';
 import { type Input, lastSaid, layered } from './config-merge';
 import type { NavigationConfig, NavigationSectionInput } from './config-navigation';
 import { mergeNavigation, navigationIssues } from './config-navigation';
 import type { PwaConfig, PwaOfflineConfig } from './config-pwa';
 import { PWA_FIX, pwaIssues } from './config-pwa';
+import { removedKeyFix, removedKeyIssue, removedKeysIn } from './config-removed';
+import {
+  booleanIssue,
+  nameListIssues,
+  oneOfIssue,
+  routePathIssue,
+  shapeIssues,
+} from './config-shape';
 import type { SeoConfig, SiteConfig, SiteSectionsInput } from './config-site';
 import { mergeSite, siteIssues } from './config-site';
+import { drainIssues } from './drain-deadline';
 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 const THEME_MODES = ['light', 'dark', 'system'] as const;
+export type ThemeMode = (typeof THEME_MODES)[number];
 /**
  * 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.
@@ -34,10 +45,12 @@ export type ThemeMode = 'light' | 'dark' | 'system';
 export const REALTIME_TRANSPORTS = ['memory', 'nats'] as const;
 export type RealtimeTransport = (typeof REALTIME_TRANSPORTS)[number];
 
+/**
+ * No `tokens` (deleted in 25.0.0): read by nothing once the theme seam landed — the app's theme is
+ * `export const brand = defineTheme(…)` from `@ultimat3/ui`. A second theming path nothing read.
+ */
 export interface ThemeConfig {
   readonly defaultMode: ThemeMode;
-  /** Semantic design tokens. Raw hex is a lint error in components, never here. */
-  readonly tokens: Readonly<Record<string, string>>;
 }
 
 /**
@@ -99,8 +112,10 @@ export const INBOX_RETENTION_KEYS = ['inboxReadRetentionMs', 'inboxUnreadRetenti
  * 3 applied to configuration: a value that produces neither a build error nor a runtime effect is
  * worse than no field, because an SRE sets `poolSize: 3`, redeploys, and nothing changes.
  */
+const DATABASE_DRIVERS = ['postgres'] as const;
+
 export interface DatabaseConfig {
-  readonly driver: 'postgres';
+  readonly driver: (typeof DATABASE_DRIVERS)[number];
   readonly ssl: boolean;
 }
 
@@ -121,26 +136,32 @@ export interface DatabaseConfig {
  */
 export interface CacheConfig {
   readonly defaultTtlMs: number;
-  /** Order is fixed by `TIER_ORDER`; listing order here selects rungs, it does not rank them. */
+  /** Order is fixed by `CACHE_TIERS`; listing order here selects rungs, it does not rank them. */
   readonly tiers: readonly CacheTierName[];
 }
 
+const JOB_BACKOFFS = ['exponential', 'fixed'] as const;
+
 export interface JobsConfig {
   /**
    * No `driver`. It accepted `'postgres' | 'redis' | 'nats'`, was read by NOTHING, and boot always
-   * built `createPgDriver` — so `jobs: { driver: 'redis' }` did not throw, did not warn, and
-   * silently gave you Postgres. Deleted 2026-08-20, and it is the worse shape of the same defect
-   * `realtime.heartbeatMs` was: a knob that fails SILENTLY in the dangerous direction.
+   * built the Postgres driver — so `jobs: { driver: 'redis' }` did not throw, did not warn, and
+   * silently gave you Postgres. Deleted 2026-08-20 (5.0.0); since 25.0.0 a config still writing it
+   * is REFUSED by name (`config-removed.ts`) rather than carried through the spread.
    *
-   * The seam that works is `setJobDriver(driver)` — `setJobDriver(createPgDriver({ executor }))`,
-   * or `setJobDriver(createMemoryDriver())` in a test. Swap the driver, zero job-code change, which
-   * is the whole of what the `JobDriver` interface buys. There is no config line, and one that
-   * cannot be honoured is worse than none.
+   * The seam that works is `setJobDriver(driver)` —
+   * `setJobDriver(postgresJobDriver({ executor }))`, or `setJobDriver(memoryJobDriver())` in a
+   * test. Swap the driver, zero job-code change, which is the whole of what the `JobDriver`
+   * interface buys. There is no config line, and one that cannot be honoured is worse than none.
    */
   readonly queues: readonly string[];
-  readonly concurrency: number;
+  /**
+   * Slots per worker process: one number for every queue it serves, or a table per queue
+   * (`{ banks: 4, 'banks-long': 2 }`, a queue it does not name at `JOBS_CONCURRENCY_DEFAULT`).
+   */
+  readonly concurrency: JobsConcurrency;
   readonly maxAttempts: number;
-  readonly backoff: 'exponential' | 'fixed';
+  readonly backoff: (typeof JOB_BACKOFFS)[number];
   readonly visibilityTimeoutMs: number;
 }
 
@@ -153,37 +174,28 @@ export interface JobsConfig {
  *
  * No `tier` either (deleted 2026-08-23): no file read it, so `tier: 'local-first'` bought nothing.
  * An app's realtime tier is what it DECLARES — a `channel()` topic, a `live: true` query, a local
- * store — never a config key; `transport` and `urlEnv` are the only fields any code reads.
+ * store — never a config key. `transport`, `urlEnv` and the two per-actor caps (read by the `sync`
+ * role into its registry and node) are the fields code reads.
  */
 export interface RealtimeConfig {
   readonly enabled: boolean;
   readonly transport: RealtimeTransport;
   readonly urlEnv: string | undefined;
-}
-
-export interface McpConfig {
-  readonly expose: boolean;
-  readonly path: string;
+  /** Live subscriptions one actor (or anonymous network) may hold per sync node. Unset: 1,000. */
+  readonly maxSubscriptionsPerActor?: number | undefined;
+  /** Sockets one actor (or anonymous network) may hold per sync node. Unset: 16. */
+  readonly maxSocketsPerActor?: number | undefined;
 }
 
 /**
- * No `modelEnv`. It named the env KEY holding the model id, "so no model string is baked into the
- * image" — and its only reader was this file's own merge, copying input to output. Nothing
- * consumed the merged value, so `modelEnv: 'ANTHROPIC_MODEL'` selected no model: `@ultimat3/ai`
- * reads env for API KEYS only, and the model is `request.model ?? DEFAULT_MODEL`, a compile-time
- * constant in `models.ts`. The exact thing the key existed to prevent is what it delivered.
- * Deleted 2026-08 — pass `model` on the request, or read your own env key and pass it.
+ * No `locales` / `defaultLocale`, `defaultTimeZone` or `defaultCurrency` (deleted in 25.0.0, and
+ * REFUSED by name when written — `config-removed.ts`). The locales were a second declaration of
+ * `defineCatalogs({ default })`; the zone and the currency were read by nothing, and an ambient
+ * default for either is the defect the framework forbids (every format call takes its zone, every
+ * `Money` its currency).
  */
-export interface AiConfig {
-  readonly mcp: McpConfig;
-}
-
 export interface AppConfig {
   readonly name: string;
-  readonly locales: readonly string[];
-  readonly defaultLocale: string;
-  readonly defaultTimeZone: string;
-  readonly defaultCurrency: string;
   readonly theme: ThemeConfig;
   readonly auth: AuthConfig;
   readonly pwa: PwaConfig;
@@ -200,11 +212,7 @@ export interface AppConfig {
   readonly seo: SeoConfig;
   readonly navigation: NavigationConfig;
   readonly islands: IslandsConfig;
-}
-
-/** `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;
+  readonly mail: MailConfig;
 }
 
 /**
@@ -221,12 +229,9 @@ export interface PwaConfigInput extends Omit<Input<PwaConfig>, 'offline'> {
 export interface AppConfigInput
   extends SiteSectionsInput,
     NavigationSectionInput,
-    IslandsSectionInput {
+    IslandsSectionInput,
+    MailSectionInput {
   readonly name: string;
-  readonly locales?: readonly string[] | undefined;
-  readonly defaultLocale?: string | undefined;
-  readonly defaultTimeZone?: string | undefined;
-  readonly defaultCurrency?: string | undefined;
   readonly theme?: Input<ThemeConfig> | undefined;
   readonly auth?: Input<AuthConfig> | undefined;
   readonly pwa?: PwaConfigInput | undefined;
@@ -246,113 +251,52 @@ export type AppConfigOverlay = Omit<AppConfigInput, 'name'> & { readonly name?:
 
 const NAME_RE = /^[a-z][a-z0-9-]{1,63}$/;
 
-/**
- * Built from `@ultimat3/schema`'s `CURRENCY_CODE_PATTERN`, the framework's ONE declaration of what
- * an ISO 4217 code looks like — the same source `isCurrencyCode`, the published OpenAPI `pattern`
- * and `@ultimat3/entity`'s Postgres CHECK all derive from. It was a character-for-character copy
- * here until the `core -> schema` edge was declared (`scripts/lib/tiers.ts`), held equal only by a
- * pin test in `@ultimat3/cli`.
- */
-const CURRENCY_RE = new RegExp(CURRENCY_CODE_PATTERN);
-
-function isLocale(value: string): boolean {
-  try {
-    return Intl.getCanonicalLocales(value).length === 1;
-  } catch {
-    return false;
-  }
-}
-
-type Sectioned = 'name' | 'site' | 'seo' | 'navigation' | 'islands';
-function defaults(name: string): Omit<AppConfig, Sectioned> {
-  return {
-    locales: ['en'],
-    defaultLocale: 'en',
-    defaultTimeZone: 'UTC',
-    defaultCurrency: 'USD',
-    theme: { defaultMode: 'system', tokens: {} },
-    auth: { signInPath: null },
-    pwa: {
-      enabled: false,
-      offline: { fallback: null, image: null, font: null, neverCache: [], personalPages: 'never' },
-      backgroundSync: false,
-      push: false,
-      name: '',
-      colors: undefined,
-    },
-    roles: [...ROLES],
-    database: { driver: 'postgres', ssl: false },
-    cache: { defaultTtlMs: 60_000, tiers: ['request-memo', 'lru'] },
-    jobs: {
-      queues: [`${name}-default`],
-      concurrency: 8,
-      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 },
-    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() },
-    health: { readiness: 'dependencies' },
-  };
-}
-
 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.
-  const zoneFix: string[] = [];
-  // Same shape, and it exists for the upgrade: an 8.0.0 app carrying `['memo', 'shared']` in an
-  // untyped config file reaches here rather than the compiler, and needs the new spelling.
+  // Zero or one entry, and it exists for the upgrade: an 8.0.0 app carrying `['memo', 'shared']`
+  // in an untyped config file reaches here rather than the compiler, and needs the new spelling.
   const tierFix: string[] = [];
   // Same shape again: carried only when an installable app is missing what an install needs.
   const pwaFix: string[] = [];
 
-  if (!NAME_RE.test(config.name)) {
+  // `typeof` first: `NAME_RE.test(undefined)` tests the string "undefined", which matches.
+  if (typeof config.name !== 'string') {
+    issues.push(`name must be a string like "my-app", not ${describeValue(config.name)}`);
+  } else if (!NAME_RE.test(config.name)) {
     issues.push(`name "${config.name}" must match ${String(NAME_RE)}`);
   }
-  if (config.locales.length === 0) issues.push('locales must list at least one locale');
-  for (const locale of config.locales) {
-    if (!isLocale(locale)) issues.push(`locales contains "${locale}", not a BCP-47 tag`);
-  }
-  if (!config.locales.includes(config.defaultLocale)) {
-    issues.push(`defaultLocale "${config.defaultLocale}" is not in locales`);
-  }
-  // `@ultimat3/time`'s rule, restated because tier 0 cannot import tier 1 — see
-  // `time-zone-name.ts`. One validator means a zone `app.config.ts` accepts is a zone every
-  // `format` call, `task()` and `toZoned` below it can then do arithmetic in.
-  if (!isIanaZoneName(config.defaultTimeZone)) {
-    issues.push(
-      `defaultTimeZone "${config.defaultTimeZone}" is not an IANA Area/Location zone name`,
-    );
-    zoneFix.push(TIMEZONE_FIX);
-  }
-  if (!CURRENCY_RE.test(config.defaultCurrency)) {
-    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');
-  // 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),
+  // ONE check per key, each against the key's own domain. A number is never a bare `< 1` — every
+  // comparison with `NaN` is false, so `concurrency < 1` passed `NaN`, `2.5` and `Infinity` — and
+  // a switch is never read for truthiness: `ssl: 'false'` and `enabled: 'false'` were both ON.
+  const perKey: readonly (string | undefined)[] = [
+    ...config.roles.map((role) => oneOfIssue('roles', role, ROLES)),
+    ...jobsConcurrencyIssues(config.jobs.concurrency),
     countIssue('jobs.maxAttempts', config.jobs.maxAttempts, 1),
     countIssue('jobs.visibilityTimeoutMs', config.jobs.visibilityTimeoutMs, 1),
+    oneOfIssue('jobs.backoff', config.jobs.backoff, JOB_BACKOFFS),
     countIssue('cache.defaultTtlMs', config.cache.defaultTtlMs, 0),
-    readinessGraceIssue(config.drain.readinessGraceMs),
+    oneOfIssue('database.driver', config.database.driver, DATABASE_DRIVERS),
+    booleanIssue('database.ssl', config.database.ssl),
+    oneOfIssue('theme.defaultMode', config.theme.defaultMode, THEME_MODES),
+    // `null` is the documented "no redirect"; a path that is said must be one a browser can follow.
+    config.auth.signInPath === null
+      ? undefined
+      : routePathIssue('auth.signInPath', config.auth.signInPath),
+    booleanIssue('ai.mcp.expose', config.ai.mcp.expose),
+    booleanIssue('realtime.enabled', config.realtime.enabled),
+    oneOfIssue('realtime.transport', config.realtime.transport, REALTIME_TRANSPORTS),
+    ...(['maxSubscriptionsPerActor', 'maxSocketsPerActor'] as const).map((key) =>
+      config.realtime[key] === undefined
+        ? undefined
+        : countIssue(`realtime.${key}`, config.realtime[key], 1),
+    ),
+    ...drainIssues(config.drain),
     readinessModeIssue(config.health.readiness),
   ];
-  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');
-  // 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) {
+  for (const issue of perKey) if (issue !== undefined) issues.push(issue);
+  nameListIssues('jobs.queues', config.jobs.queues, 'queue', issues);
+  if (config.realtime.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
@@ -377,10 +321,14 @@ function validate(config: AppConfig): void {
   siteIssues(config, issues);
   navigationIssues(config, issues);
   islandsIssues(config, issues);
+  mailIssues(config, issues);
 
   // A rung the ladder cannot build is the defect this key had: `sortTiers` places a name by its
   // index in `CACHE_TIERS`, and a name missing from it sorts to `-1` — AHEAD of the request memo.
   // So an unknown tier is refused at boot rather than silently ignored or silently placed first.
+  // An EMPTY ladder is refused with the unknown rung: it builds no tier at all, so every read
+  // misses and nothing says the cache was configured away.
+  if (config.cache.tiers.length === 0) issues.push('cache.tiers must list at least one tier');
   for (const tier of config.cache.tiers) {
     if (CACHE_TIERS.includes(tier)) continue;
     issues.push(`cache.tiers contains "${tier}", which is not one of ${CACHE_TIERS.join(', ')}`);
@@ -392,43 +340,21 @@ function validate(config: AppConfig): void {
       cause: issues.join('; '),
       // The generic instruction goes LAST so the fix line still ends in a command that can be
       // pasted — a trailing `.` after `x verify` is a command nobody can run.
-      fix: [...zoneFix, ...tierFix, ...pwaFix, BASE_FIX].join('. '),
+      fix: [...tierFix, ...pwaFix, BASE_FIX].join('. '),
       meta: { issues },
     });
   }
 }
 
 /**
- * The single config entry point. Later overlays win, so `config/jobs.ts` can own jobs without
- * touching `app.config.ts`.
+ * 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. No layer at all is the
+ * defaults, which is the reference `shapeIssues` compares each layer against.
  */
-export function defineConfig(
-  input: AppConfigInput,
-  ...overlays: readonly AppConfigOverlay[]
-): AppConfig {
-  const base = defaults(input.name);
-  // 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: 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),
-    ),
+function merge(name: string, layers: readonly AppConfigOverlay[]): AppConfig {
+  const base = configDefaults(name);
+  return {
+    name,
     theme: layered(
       base.theme,
       layers.map((layer) => layer.theme),
@@ -491,8 +417,50 @@ export function defineConfig(
     ...mergeSite(layers),
     ...mergeNavigation(layers),
     ...mergeIslands(layers),
+    ...mergeMail(layers),
   };
+}
+
+/**
+ * FIRST, before shape: a removed key is an instruction the app is still giving, and the answer is
+ * the line to delete and what replaces it — never silence, and never a shape complaint about a
+ * section (`theme.tokens: null`) that no longer has the key at all. Every layer is asked, so a
+ * stale `config/theme.ts` overlay is caught as surely as the base.
+ */
+function refuseRemovedKeys(layers: readonly unknown[]): void {
+  const removed = [...new Set(layers.flatMap((layer) => removedKeysIn(layer)))];
+  if (removed.length === 0) return;
+  const issues = removed.map(removedKeyIssue);
+  throw new ConfigInvalidError({
+    cause: issues.join('; '),
+    fix: [...removed.map(removedKeyFix), BASE_FIX].join('. '),
+    meta: { issues, removed },
+  });
+}
 
+/**
+ * The single config entry point. Later overlays win, so `config/jobs.ts` can own jobs without
+ * touching `app.config.ts`.
+ */
+export function defineConfig(
+  input: AppConfigInput,
+  ...overlays: readonly AppConfigOverlay[]
+): AppConfig {
+  const layers: readonly AppConfigOverlay[] = [input, ...overlays];
+  refuseRemovedKeys(layers);
+  // Structure FIRST, per layer and before the merge: a section written as `null` or a list
+  // written as a string is what `Object.entries` and `.length` raised a native `TypeError` on.
+  const issues: string[] = [];
+  // `navigation` is left out: `config-navigation.ts` carries a wrong shape through AS WRITTEN and
+  // refuses it in its own words, with the surfaces it accepts.
+  const reference = { ...merge(input.name, []), navigation: undefined };
+  // Closed BEFORE shape: a typo'd section (`drian: null`) is the wrong name, not the wrong kind.
+  refuseUnknownKeys(reference, layers);
+  for (const layer of layers) shapeIssues(reference, layer, issues);
+  if (issues.length > 0) {
+    throw new ConfigInvalidError({ cause: issues.join('; '), fix: BASE_FIX, meta: { issues } });
+  }
+  const config = merge(input.name, layers);
   validate(config);
   return Object.freeze(config);
 }

package/src/context.ts

@@ -3,9 +3,9 @@
 // parameters — otherwise every signature in the framework grows a `ctx` argument twice.
 //
 // THERE IS EXACTLY ONE ASSERTION IN THIS FILE AND IT IS IRREDUCIBLE (`As of 2026-08-24`). It is
-// the `as Ctx` in `createContext`, and it is the LAST one: the second — over `preview` — is gone,
+// the `as Ctx` in `ctxOf`, and it is the LAST one: the second — over `preview` — is gone,
 // because `CtxFacts` gives that value an honest type, and `@ultimat3/http`'s
-// `createRequestContext` now composes this function instead of building a second context beside
+// `requestContext` now composes this function instead of building a second context beside
 // it, so that package has none at all.
 //
 // Why the last one cannot go. `Ctx extends CtxServices`, and `CtxServices` is the seam an app
@@ -20,9 +20,9 @@
 // Four alternatives were built and measured before this line was kept. Making the augmented half
 // `Partial<CtxServices>` removes the assertion and turns `ctx.posts` into `PostRepo | undefined`
 // for every app — true, and a breaking change to the documented seam. Requiring `CtxInit.services`
-// to be a `CtxServices` moves the proof to the caller and breaks every internal `createContext()`
+// to be a `CtxServices` moves the proof to the caller and breaks every internal `ctxOf()`
 // in an app's program, because an app typechecks the framework's sources through its project
-// references. A generic `createContext<S>` returns a context no framework caller can pass where a
+// references. A generic `ctxOf<S>` returns a context no framework caller can pass where a
 // `Ctx` is wanted. And an overload whose implementation signature returns the looser type compiles
 // only through TypeScript's documented bivariance hole — the same assertion, laundered.
 //
@@ -35,7 +35,7 @@ import { asyncContext } from './async-context';
 import { type Clock, systemClock } from './clock';
 import { UltimateError } from './errors';
 import { finiteOption } from './finite-option';
-import { traceId as newTraceId, uuid } from './ids';
+import { traceId as newTraceId, uuidV7 } from './ids';
 import { type Logger, logger as rootLogger, setLoggerContextFields } from './logger';
 import { installTraceHeaders } from './outbound-headers';
 import { type Role, resolveRole } from './roles';
@@ -73,7 +73,7 @@ export interface ServiceBag {
  * against a type carrying members only the app's boot knows about: `Ctx extends CtxServices`, an
  * app augments `CtxServices` with `declare module`, and every service it declares then became a
  * REQUIRED member of every context literal in the framework. `@ultimat3/http`'s
- * `createRequestContext` stopped compiling inside `examples/dummy` for exactly that reason
+ * `requestContext` stopped compiling inside `examples/dummy` for exactly that reason
  * (`TS2739: missing posts, orgs`), while the framework's own gate — which augments nothing —
  * stayed green.
  *
@@ -157,6 +157,10 @@ const requestContext = asyncContext<Ctx>('the request context');
 
 const neverAborted = new AbortController().signal;
 
+/**
+ * The framework's default locale — the ONE declaration: `@ultimat3/i18n` imports it rather than
+ * restating it (a second `'en'` there could drift from the context's own default).
+ */
 export const DEFAULT_LOCALE = 'en';
 export const DEFAULT_TIME_ZONE = 'UTC';
 
@@ -164,9 +168,9 @@ function buildId(): string {
   return process.env['BUILD_ID'] ?? 'dev';
 }
 
-export function createContext(init: CtxInit = {}): Ctx {
+export function ctxOf(init: CtxInit = {}): Ctx {
   const clock = init.clock ?? systemClock;
-  const requestId = init.requestId ?? uuid(clock);
+  const requestId = init.requestId ?? uuidV7(clock);
   const trace = init.traceId ?? newTraceId();
   const base = init.logger ?? rootLogger;
   const explicit: ServiceBag = Object.freeze({ ...(init.services ?? {}) });
@@ -233,7 +237,7 @@ export function useContext(): Ctx {
     throw new UltimateError({
       code: 'X_NO_CONTEXT',
       cause: 'useContext() was called outside of runWithContext()',
-      fix: 'wrap the entry point in runWithContext(createContext({ ... }), fn)',
+      fix: 'wrap the entry point in runWithContext(ctxOf({ ... }), fn)',
     });
   }
   return ctx;
@@ -272,6 +276,18 @@ function screenDeadline(value: number | null | undefined): number | null {
   return finiteOption('the request context', 'deadlineAt', value);
 }
 
+/**
+ * A patched signal is ADDED to the parent's, never swapped for it — the deadline's own rule, one
+ * field over. `patch ?? parent` made a step that brought its own signal blind to the request it
+ * runs inside: the client disconnected, the request timed out, and `ctx.signal.aborted` stayed
+ * false in the child. The shared never-aborting default is skipped rather than composed, so a
+ * context with no request behind it does not grow a listener per child.
+ */
+function composeSignal(parent: AbortSignal, patch: AbortSignal | undefined): AbortSignal {
+  if (patch === undefined || patch === parent) return parent;
+  return parent === neverAborted ? patch : AbortSignal.any([parent, patch]);
+}
+
 /**
  * Derive a narrowed context — impersonation, a locale switch, a per-step abort signal.
  * `requestId` is deliberately not patchable: one request, one id.
@@ -279,13 +295,13 @@ function screenDeadline(value: number | null | undefined): number | null {
 export function withChildContext<T>(patch: CtxPatch, fn: () => T): T {
   const parent = useContext();
   // A factory-managed service was built for the PARENT's actor; forwarding it verbatim into an
-  // impersonated child would answer every call with the parent's tenant. `createContext` below
+  // impersonated child would answer every call with the parent's tenant. `ctxOf` below
   // rebuilds every registered factory fresh against the child's own actor, so only services no
   // factory owns — a hand-built mock nothing registered — carry forward unrebuilt.
   const carried = Object.fromEntries(
     Object.entries(parent.services).filter(([name]) => !isManagedService(name)),
   );
-  const child = createContext({
+  const child = ctxOf({
     requestId: parent.requestId,
     traceId: patch.traceId ?? parent.traceId,
     actor: patch.actor ?? parent.actor,
@@ -301,7 +317,7 @@ export function withChildContext<T>(patch: CtxPatch, fn: () => T): T {
     // that and did not do it — a patched hour replaced a parent's second outright, and
     // `remainingBudgetMs` then put the hour on `x-request-timeout-ms` for the next hop.
     deadlineAt: earliest(screenDeadline(patch.deadlineAt) ?? undefined, parent.deadlineAt),
-    signal: patch.signal ?? parent.signal,
+    signal: composeSignal(parent.signal, patch.signal),
     services: { ...carried, ...(patch.services ?? {}) },
   });
   return requestContext.run(child, fn);
@@ -318,7 +334,7 @@ export function useService<T>(name: string): T {
     throw new UltimateError({
       code: 'X_SERVICE_MISSING',
       cause: `"${name}" is not on ctx.services (have: ${Object.keys(ctx.services).join(', ')})`,
-      fix: `pass it in createContext({ services: { ${name} } })`,
+      fix: `pass it in ctxOf({ services: { ${name} } })`,
       meta: { name },
     });
   }