@ultimat3/core 23.0.0 → 24.0.0

package/CLAUDE.md

@@ -60,8 +60,10 @@ top-level `UltimateError` use in `error-codes.ts`.
 | Concept | Owner | Note |
 |---|---|---|
 | which deploy this is | `environment.ts` (`ULTIMATE_ENV`) | the twin of `ROLE`; never a second env var |
+| one-home helpers | `store-mode` `html-escape` `cookie` `fnv1a` `pg-executor` | never copied (`X_HELPER_COPY`) |
 | what this process does | `roles.ts` (`ROLE`) | |
 | how a route renders, caches offline and hydrates | `route-vocabulary.ts` (`RENDER_MODES`, `OFFLINE_STRATEGIES`, `HYDRATE_STRATEGIES`) | every union is `(typeof ARRAY)[number]`, pinned in `type-pins.ts`; `scripts/render-modes.test.ts` refuses a second declaration. Re-export it, never restate it |
+| which of two route patterns wins a pathname | `route-rank.ts` (`routeRank`) | the request router's order as one integer: segment by segment, literal 3 > `:param` 2 > `*catch-all` 1, ENDED 4, packed base 5 over 22 segments. Read by `@ultimat3/render`'s `compilePattern` and `@ultimat3/pwa`'s rule order — both tier 4, so the one copy lives here. `@ultimat3/http`'s trie encodes the same order by its walk, not by this number. Never a sum: 100/10/1 ranked `/:a/b/c` above `/a/:x/:y` |
 | which rungs a cache ladder has | `cache-vocabulary.ts` (`CACHE_TIERS`) | `@ultimat3/cache`'s `TIER_ORDER` IS this array. `isr` is a `RenderMode`, never a tier |
 | which build of the APP this is | `app-version.ts` (`APP_VERSION`) | one reader, `dev` by default |
 | the values | `env.ts` | `checkEnv().values` holds REAL secrets — printing goes through `maskedEnvValues()` |
@@ -79,6 +81,8 @@ top-level `UltimateError` use in `error-codes.ts`.
 | which row survives a conflict | `conflict-policy.ts` (`ConflictPolicy`, `resolveConflict`, `Row`) | read by `action`'s mutator and `realtime`'s rebase |
 | the four shapes of an async region | `async-state.ts` (`AsyncState`) | `realtime` returns it, `ui` renders it. `bun run render-modes` refuses a second status union sharing three members |
 | is this `unknown` a keyed record? | `json-object.ts` (`isJsonObject`) | narrows a shape; does not certify provenance |
+| may a caller read this 5xx `cause`? | `public-cause.ts` (`hasPublicCause`) | one table for http, mcp, ai. `registerPublicCause` is `@ultimat3/http`'s `registerProblemMeta` writing it — never an app's door |
+| is this field a credential? | `logger.ts` (`isRedactedKey`) | exact keys + `CREDENTIAL_NAME`; a bare `token` suffix is NOT one (`idempotencyToken`, `maxTokens`). Log line, monitor envelope and `action`'s audit ask it |
 | a value that must not be printed | `secret.ts` | redacted by VALUE; `revealSecret()` is the one, greppable, way out |
 | an `Intl` formatter cache, and the screen in front of it | `intl-cache.ts` (`cachedFormatter`, `canonicalLocale`, `assertLocale`, `MAX_CACHED_FORMATTERS`, `MAX_LOCALE_EXCERPT`) | a locale arrives from a header: refuse a non-tag (`X_LOCALE_INVALID`), key canonically AND bound the cache — never a copy of any of the three. The cause quotes at most `MAX_LOCALE_EXCERPT` (35) code points; the whole tag rides in `meta.locale` |
 | the text direction of a locale | `locale-direction.ts` (`directionOf`, `isRtl`, `Direction`) | re-exported by `@ultimat3/i18n`; lives here so `@ultimat3/ui` need not reach the i18n barrel |
@@ -192,6 +196,8 @@ is the bug:
   WHOLE drain's; `DEFAULT_DEADLINE_MS` (25 s) always applies; it is real monotonic time
   (`systemClock`), never the injected `clock`. `drainDeadlineMs()` is the one decision point.
   `settleWithin` attaches a rejection handler unconditionally.
+- **Who a health endpoint tells what is ONE rule, here** (`health-disclosure.ts`): `healthBody` +
+  `healthPeerListed`, called by http and by realtime's sync listener. Never a second copy.
 - **A readiness grace runs before the `accept` phase** (`lifecycle-grace.ts`): `/readyz` answers 503
   with the socket still open for `drain.readinessGraceMs`, ADDED to `deadlineMs` (a chart's
   `terminationGracePeriodSeconds` must exceed the sum — 5 s + 25 s by default). Unset: 0 in

package/README.md

@@ -32,6 +32,7 @@ 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` |
+| which store backs a seam — `storeMode(env)`: `memory` under `test`, `database` everywhere else | `store-mode.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` |
@@ -40,8 +41,11 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | the key ring those work under: the current key plus retired ones | `seal-keys.ts` |
 | `defineConfig()` for `app.config.ts` | `config.ts` |
 | how overlays layer onto it — per section, key by key | `config-merge.ts` |
+| what each key is when no layer says | `config-defaults.ts` |
+| the shape screens that run before any rule reads a value — section, list, boolean, closed set, path, locale list | `config-shape.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` |
+| which of two route patterns wins a pathname (`routeRank`) | `route-rank.ts` |
 | runtime roles + `ROLE` resolution | `roles.ts` |
 | `Clock` — the only source of "now" | `clock.ts` |
 | UUIDv7, nanoid, branded ids | `ids.ts` |
@@ -51,6 +55,7 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | OTLP/HTTP JSON: endpoint, headers, value encoding | `otlp.ts` |
 | `SpanExporter` on the wire, batched | `otlp-span-exporter.ts` |
 | `MetricExporter` on the wire | `otlp-metric-exporter.ts` |
+| may a caller read this 5xx code's `cause`? `hasPublicCause(code)` — one predicate for the HTTP problem document, MCP error data and an agent `tool_result` | `public-cause.ts` |
 | `reportError` + the `ErrorReporter` seam, no-op by default | `error-reporter.ts` |
 | that seam on the wire, Sentry's envelope and DSN | `error-reporter-sentry.ts` |
 | OTel-shaped counter / gauge / histogram, same seam | `metrics.ts` |
@@ -58,6 +63,7 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | the series every process emits, incl. what the chart scales on | `runtime-metrics.ts` |
 | what the process itself costs: `process_resident_memory_bytes`, `process_heap_used_bytes`, `process_heap_total_bytes`, `process_external_memory_bytes`, `process_cpu_seconds_total`, `process_event_loop_lag_seconds`, `process_start_time_seconds`, `process_info{role}` — **server-only**, never on `@ultimat3/core/page` | `process-metrics.ts` (`startProcessMetrics`, `readProcess`) |
 | graceful drain, `/healthz`, `/readyz` | `lifecycle.ts` |
+| what a health endpoint tells whom — `healthBody(report, role, detailed)`, `healthPeerListed(peers, address)`, `DEFAULT_HEALTH_DETAIL_PEERS`; the one rule `@ultimat3/http` and the sync node's own listener both call | `health-disclosure.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` |
@@ -66,6 +72,13 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | the registrar table one same-tier package reaches another through | `registrar.ts` |
 | decode → resize → encode, the one image pipeline (over `Bun.Image`) | `image/` |
 | `assertNever`, `invariant` | `assert.ts` |
+| the one HTML character table — `escapeHtml`, text and attributes alike (`& < > " '`) | `html-escape.ts` |
+| the one `Cookie:` reader — `readCookie(header, name)`, `null` when absent, never a throw | `cookie.ts` |
+| 32-bit FNV-1a — a BUCKET (rollouts, factory seeds), never a sharing key (`fingerprint` is) | `fnv1a.ts` |
+| `PgExecutor` — the structural `query(text, values)` seam every Postgres store takes | `pg-executor.ts` |
+
+Each of the four, and `fingerprint`, `storeMode` and render's `contentHash`, has ONE implementation:
+`bun run flight-copies` refuses a second by its shape (`X_HELPER_COPY`), whatever it is named.
 
 ## Errors are instructions
 
@@ -312,6 +325,10 @@ fallback of its own; the caller does.
 is not our key. This is the twin of `roles.ts` — `ROLE` says what the process does,
 `ULTIMATE_ENV` says which deploy it belongs to.
 
+`storeMode(Bun.env)` is the one answer to "memory store or database store?" for a seam with both —
+`memory` under `test` (no database client is installed there), `database` everywhere else, `x dev`'s
+embedded PGlite included. Never a `DATABASE_URL` truthiness check: `x dev` sets none.
+
 ## A secret is redacted by value, not by name
 
 ```ts
@@ -320,7 +337,21 @@ logger.info('boot', { dsn });        // {"dsn":"[redacted]"}
 connect(revealSecret(dsn));          // the one greppable way out
 ```
 
-`redactKeys()` catches a secret travelling under a name someone remembered to list. A `Secret`
+`isRedactedKey(key)` is the one answer to "is this field a credential?" — the log line, the error
+monitor's envelope and `@ultimat3/action`'s audit row all ask it. It matches the exact names
+`redactKeys()` holds (`defineEnv` adds every `secret: true` variable) **and** a credential-bearing
+name it was never told about: `password` / `passphrase` anywhere, `secret` as the last word, any
+`…token` that is not a dedupe or paging key (`resetToken`, `githubToken`, `NPM_TOKEN`), key
+material by its qualifier (`signingKey`, `masterKey`, `accessKeyId`), a value that embeds a
+credential (`connectionString`, `dsn`, `databaseUrl`), the one-time codes
+(`totpCode`, `recoveryCode`) and a stored hash of any of them (`passwordHash`, `tokenHash`,
+`keyHash`). It deliberately leaves `idempotencyToken`, a paging token, `maxTokens` and an error
+`code` readable — a redacted field is one an operator cannot correlate on.
+
+`LOG_LEVEL` is refused when it is not one of `LOG_LEVELS` (lowercase), exactly as
+`createLogger({ level })` refuses it; unset or empty is `info`.
+
+A `Secret`
 box catches the other case: `String()`, template literals, `+`, `JSON.stringify`, `console.log`,
 the logger and an error's `meta` all render `[redacted]`, whatever key it sits under. It is
 frozen and everything but `label` is non-enumerable, so `{ ...dsn }` cannot spread the value back
@@ -554,7 +585,7 @@ never a silently wrong page.
 | | |
 |---|---|
 | Signature | truncated HMAC-SHA256, compared in constant time |
-| Secret | `configureCursorSigning()` at boot, else `ULTIMATE_CURSOR_SECRET`. **Read when a cursor is signed, never at import** — an app whose `openSecrets()` sets the variable during boot would otherwise sign every cursor with the dev key. Rotating it invalidates every open cursor |
+| Secret | `configureCursorSigning()` at boot, else `ULTIMATE_CURSOR_SECRET`. An EMPTY value is unset — never an empty HMAC key — so `usesDevCursorSecret()` reports it and the boot refuses it outside a local environment. **Read when a cursor is signed, never at import** — an app whose `openSecrets()` sets the variable during boot would otherwise sign every cursor with the dev key. Rotating it invalidates every open cursor |
 | Also keys | `keyedFingerprint(value, purpose)` — `h1:<key id>:<HMAC>` over `canonicalJson`, under a per-purpose key derived from this secret; the fingerprint to PERSIST (`@ultimat3/action`'s idempotency `requestHash`). `compareFingerprint` answers `match` / `mismatch` / `unverifiable` (other key), and still checks a legacy bare `fingerprint()` exactly. Rotating the secret makes in-window stored fingerprints `unverifiable` |
 | Signed, not encrypted | the client already has these rows; what it must not do is *invent* a position |
 | `usesDevCursorSecret()` | true while the shipped dev key is in use |
@@ -649,7 +680,7 @@ nothing consulted it before deciding to try again. `As of 2026-08-23`.
 |---|---|---|
 | `backoffDelay({ attempt, base, max, factor?, curve?, jitter?, random? })` | one curve — `exponential \| linear \| fixed`, `full \| equal \| none` — 1-based `attempt`, clamped to `max` **before** jitter, rounded, and `0` rather than `NaN` | how long to wait. `random` is injectable, so a schedule is a unit test rather than a range |
 | `createSingleFlight({ deadlineMs?, schedule? })` → `run(key, work, join?)`, `size` | N callers on one key are ONE run | who pays for a miss. Eviction is identity-checked, so a load that settles late never drops the load that replaced it; `deadlineMs` frees the KEY a wedged load would hold forever — it never cancels the work and never rejects a joiner |
-| `createFlightGate({ maxConcurrent, maxQueued }, { subject?, overflow? })` | one bound, one queue, one refusal | how many at once. Past the queue the answer is `X_FLIGHT_GATE_OVERLOADED` (503) and never a longer queue; the slot is HANDED to a waiter, never released and re-acquired |
+| `createFlightGate({ maxConcurrent, maxQueued }, { subject?, overflow? })` | one bound, one queue, one refusal | how many at once. Past the queue the answer is `X_FLIGHT_GATE_OVERLOADED` (503) and never a longer queue; the slot is HANDED to a waiter, never released and re-acquired. Both limits are screened at construction (`finiteCount`, 0 allowed); a width of 0 refuses every caller rather than queueing for a slot that never frees |
 | `createFence(subject)` → `generation()`, `bump()`, `guard(issued)` | whether an answer still applies | `X_SUPERSEDED` (499) and `isSuperseded(error)` — the piece nothing in the tree had. `guard` compares `!==`, never `<` |
 | `isRetryableStatus(status)`, `RETRYABLE_STATUSES` | `>= 500`, plus 408, 409, 425, 429 | which HTTP answers are worth repeating |
 | `retry(work, policy, { sleep, now?, random? })`, `retryDecision(policy, attempt, error, random?)` | the executor and the pure decision behind the classification | whether to try again at all. `createClientFlight` is its one caller in the framework; `jobs`, `ai` and `db` each keep their own loop and delegate only the arithmetic and the classification |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "23.0.0",
+  "version": "24.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": "23.0.0"
+    "@ultimat3/schema": "24.0.0"
   }
 }

package/src/config-defaults.ts

@@ -0,0 +1,46 @@
+// Single responsibility: the value every `app.config.ts` key has when no layer says otherwise.
+// Split from `config.ts`, which sits at its 500-line ceiling; literals only, so it reads no key.
+
+import type { AppConfig } from './config';
+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';
+
+export function configDefaults(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' },
+  };
+}

package/src/config-merge.ts

@@ -2,6 +2,8 @@
 // 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.
 
+import { isJsonObject } from './json-object';
+
 /** 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 };
 
@@ -11,6 +13,12 @@ export type Input<T> = { readonly [K in keyof T]?: T[K] | undefined };
  */
 export function section<T extends object>(base: T, patch: Input<T> | undefined): T {
   if (patch === undefined) return base;
+  // A layer that wrote something other than an object (`null`, a string, a list) has no key to
+  // merge, and `Object.entries(null)` below was a native `TypeError` out of the validator's own
+  // caller. It is carried through AS WRITTEN — and stays, whatever later layers say — so the shape
+  // screen refuses it by name; dropped here, the app would run on defaults it believed it replaced.
+  if (!isJsonObject(base)) return base;
+  if (!isJsonObject(patch)) return patch as T;
   const out: Record<string, unknown> = { ...(base as Record<string, unknown>) };
   for (const [key, value] of Object.entries(patch)) {
     if (value !== undefined) out[key] = value;

package/src/config-shape.ts

@@ -0,0 +1,112 @@
+// Single responsibility: the SHAPE half of `app.config.ts` validation — is this a section, a list,
+// a boolean, one of a closed set — asked before any rule reads the value. Takes every key as a
+// string and every value as `unknown`, and names no config key of its own: `config-readers` counts
+// a property access outside the declaring files as a reader, so this file must not make one.
+
+import { describeValue } from './error-render';
+import { isJsonObject } from './json-object';
+
+/** A string is worth echoing — it is the typo; anything else is described by shape. */
+const said = (value: unknown): string =>
+  typeof value === 'string' ? `"${value}"` : describeValue(value);
+
+/**
+ * Every section and list one LAYER wrote, compared with the same position in `reference` — the
+ * defaults merged with no layer, so the screen is derived and never a hand list of key names.
+ * Structure only: where the reference holds a section the layer may hold a section, where it holds
+ * a list, a list. `undefined` is a layer not saying; scalars are the per-key rules' business; and
+ * a position the reference leaves `null` or `undefined` (an optional block) is not judged here.
+ *
+ * It runs BEFORE the merge and its issues end the validation, because the merge and every rule
+ * after it read through the structure: `Object.entries(null)` and `null.length` are the native
+ * `TypeError`s the validator exists to replace with an instruction.
+ */
+export function shapeIssues(reference: unknown, layer: unknown, issues: string[], path = ''): void {
+  if (!isJsonObject(reference) || !isJsonObject(layer)) return;
+  for (const [key, expected] of Object.entries(reference)) {
+    const at = path === '' ? key : `${path}.${key}`;
+    const value: unknown = layer[key];
+    if (value === undefined) continue;
+    if (Array.isArray(expected)) {
+      if (!Array.isArray(value)) issues.push(`${at} must be a list, not ${describeValue(value)}`);
+    } else if (isJsonObject(expected)) {
+      if (isJsonObject(value)) shapeIssues(expected, value, issues, at);
+      else issues.push(`${at} must be an object, not ${describeValue(value)}`);
+    }
+  }
+}
+
+/** Why `value` is not one of `allowed`, or `undefined` when it is. */
+export function oneOfIssue(
+  key: string,
+  value: unknown,
+  allowed: readonly string[],
+): string | undefined {
+  if (allowed.some((known) => known === value)) return undefined;
+  return `${key} ${said(value)} is not one of ${allowed.join(', ')}`;
+}
+
+/**
+ * `typeof`, never truthiness: an untyped config writing `'false'` — a string out of an environment
+ * variable — is truthy, so the switch it meant to turn off stayed on and nothing said so.
+ */
+export function booleanIssue(key: string, value: unknown): string | undefined {
+  return typeof value === 'boolean'
+    ? undefined
+    : `${key} must be true or false, not ${said(value)}`;
+}
+
+/** A route path the framework mounts or redirects to: absolute, or the browser resolves it. */
+export function routePathIssue(key: string, value: unknown): string | undefined {
+  return typeof value === 'string' && value.startsWith('/')
+    ? undefined
+    : `${key} must be a path starting with /, not ${said(value)}`;
+}
+
+/** A list that names things: at least one entry, each a non-empty string, `what` each. */
+export function nameListIssues(
+  key: string,
+  list: readonly unknown[],
+  what: string,
+  issues: string[],
+): void {
+  if (list.length === 0) issues.push(`${key} must list at least one ${what}`);
+  for (const entry of list) {
+    if (typeof entry !== 'string' || entry.trim() === '') {
+      issues.push(`${key} contains ${said(entry)}, not a ${what} name`);
+    }
+  }
+}
+
+function canonicalTag(tag: unknown): string | undefined {
+  if (typeof tag !== 'string') return undefined;
+  try {
+    const canonical = Intl.getCanonicalLocales(tag);
+    return canonical.length === 1 ? canonical[0] : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The locale list and the tag that must be in it. Two spellings of ONE locale are refused: the
+ * list keys a catalog, a route prefix and an `hreflang` each, and `['EN', 'en']` is two of every
+ * one of them for a single language.
+ */
+export function localeIssues(tags: readonly unknown[], fallback: unknown, issues: string[]): void {
+  if (tags.length === 0) issues.push('locales must list at least one locale');
+  const seen = new Map<string, unknown>();
+  for (const tag of tags) {
+    const canonical = canonicalTag(tag);
+    if (canonical === undefined) {
+      issues.push(`locales contains ${said(tag)}, not a BCP-47 tag`);
+    } else if (seen.has(canonical)) {
+      issues.push(
+        `locales lists ${canonical} twice, as ${said(seen.get(canonical))} and ${said(tag)}`,
+      );
+    } else {
+      seen.set(canonical, tag);
+    }
+  }
+  if (!tags.includes(fallback)) issues.push(`defaultLocale ${said(fallback)} is not in locales`);
+}

package/src/config-site.ts

@@ -3,6 +3,7 @@
 // Split from `config.ts` for `config-pwa.ts`' reason: that file sits at its 500-line ceiling.
 
 import { type Input, layered } from './config-merge';
+import { describeValue } from './error-render';
 
 export interface SiteConfig {
   /**
@@ -108,10 +109,20 @@ export function siteIssues(config: SiteSections, issues: string[]): void {
     const issue = originIssue(origin);
     if (issue !== undefined) issues.push(issue);
   }
-  for (const path of config.seo.robots.disallow) {
-    if (!path.startsWith('/')) issues.push(`seo.robots.disallow entry "${path}" must start with /`);
+  // `unknown` entries: an untyped config reaches here with whatever it listed, and `5.startsWith`
+  // was a native `TypeError` thrown by the validator itself.
+  for (const path of config.seo.robots.disallow as readonly unknown[]) {
+    if (typeof path !== 'string') {
+      issues.push(`seo.robots.disallow entry must be a path string, not ${describeValue(path)}`);
+    } else if (!path.startsWith('/')) {
+      issues.push(`seo.robots.disallow entry "${path}" must start with /`);
+    }
   }
-  for (const path of config.seo.sitemap.extra) {
+  for (const path of config.seo.sitemap.extra as readonly unknown[]) {
+    if (typeof path !== 'string') {
+      issues.push(`seo.sitemap.extra entry must be a path string, not ${describeValue(path)}`);
+      continue;
+    }
     // A PATH, never a URL: every `<loc>` is built against the one declared origin, and a query or
     // a fragment names a variant of a page, which a sitemap lists by its canonical URL alone.
     if (!path.startsWith('/') || path.startsWith('//') || /[?#]/.test(path)) {

package/src/config.ts

@@ -8,6 +8,7 @@ import { CURRENCY_CODE_PATTERN } from '@ultimat3/schema';
 // 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 { configDefaults } from './config-defaults';
 import { BASE_FIX, CACHE_TIER_FIX, TIMEZONE_FIX } from './config-fixes';
 import type { DrainConfig, HealthConfig } from './config-health';
 import { readinessModeIssue } from './config-health';
@@ -18,15 +19,24 @@ import type { NavigationConfig, NavigationSectionInput } from './config-navigati
 import { mergeNavigation, navigationIssues } from './config-navigation';
 import type { PwaConfig, PwaOfflineConfig } from './config-pwa';
 import { PWA_FIX, pwaIssues } from './config-pwa';
+import {
+  booleanIssue,
+  localeIssues,
+  nameListIssues,
+  oneOfIssue,
+  routePathIssue,
+  shapeIssues,
+} from './config-shape';
 import type { SeoConfig, SiteConfig, SiteSectionsInput } from './config-site';
 import { mergeSite, siteIssues } from './config-site';
 import { describeValue } from './error-render';
 import { ConfigInvalidError } from './errors';
-import { defaultReadinessGraceMs, readinessGraceIssue } from './lifecycle-grace';
+import { 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.
@@ -99,8 +109,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;
 }
 
@@ -125,6 +137,8 @@ export interface CacheConfig {
   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
@@ -140,7 +154,7 @@ export interface JobsConfig {
   readonly queues: readonly string[];
   readonly concurrency: number;
   readonly maxAttempts: number;
-  readonly backoff: 'exponential' | 'fixed';
+  readonly backoff: (typeof JOB_BACKOFFS)[number];
   readonly visibilityTimeoutMs: number;
 }
 
@@ -255,52 +269,6 @@ const NAME_RE = /^[a-z][a-z0-9-]{1,63}$/;
  */
 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.
@@ -311,16 +279,13 @@ function validate(config: AppConfig): void {
   // 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`);
-  }
+  localeIssues(config.locales, config.defaultLocale, issues);
   // `@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.
@@ -334,25 +299,33 @@ 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');
-  // 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)[] = [
+  // 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)),
     countIssue('jobs.concurrency', config.jobs.concurrency, 1),
     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),
+    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),
+    routePathIssue('ai.mcp.path', config.ai.mcp.path),
+    booleanIssue('realtime.enabled', config.realtime.enabled),
+    oneOfIssue('realtime.transport', config.realtime.transport, REALTIME_TRANSPORTS),
     readinessGraceIssue(config.drain.readinessGraceMs),
     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
@@ -381,6 +354,9 @@ function validate(config: AppConfig): void {
   // 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(', ')}`);
@@ -399,20 +375,14 @@ function validate(config: AppConfig): void {
 }
 
 /**
- * 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,
+function merge(name: string, layers: readonly AppConfigOverlay[]): AppConfig {
+  const base = configDefaults(name);
+  return {
+    name,
     locales: lastSaid(
       base.locales,
       layers.map((layer) => layer.locales),
@@ -492,7 +462,28 @@ export function defineConfig(
     ...mergeNavigation(layers),
     ...mergeIslands(layers),
   };
+}
 
+/**
+ * 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];
+  // 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 };
+  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

@@ -272,6 +272,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.
@@ -301,7 +313,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);