@ultimat3/core 16.0.0 → 18.0.0

package/CLAUDE.md

@@ -77,17 +77,28 @@ It is not a general sanitiser: a cause is prose and keeps its quotes,
 its backslashes and its percent signs — only the control range is touched. Line breaks are the
 structural half; the rest of C0 and DEL ride along because a terminal reads a raw `\u001b` as an ANSI
 escape, so a cause could repaint the screen or hide the line above it. `@ultimat3/schema` carries a
-deliberate duplicate for the tier-0 reason below, pinned behaviourally by
-`single-line-pin.test.ts` in `@ultimat3/cli`.
-
-`describeValue` in `error-render.ts` is a deliberate duplicate of `describeValue` in
-`packages/schema/src/describe-value.ts`, for the same tier-0 reason `SCHEMA_ERROR_CODE_TITLES` is
-one: schema and core are both tier 0 and `core → schema` is **not** a declared edge in
-`scripts/lib/tiers.ts`, so neither may import the other. Keep the two ANSWERING identically — that
-is the contract, and the source is no longer character-for-character: schema counts characters
-through `char-count.ts`, which core copies privately. A pin test in
-`@ultimat3/cli` (which may legally import both) is the mechanical half, the same shape as
-`schema-error-codes-pin.test.ts`. **A string's length is CODE POINTS in both, `As of 2026-08-22`**
+deliberate duplicate — `schema -> core` stays forbidden, so that direction cannot be collapsed —
+pinned behaviourally by `single-line-pin.test.ts`, which lives HERE `As of 2026-08-27`, at the tier
+the invariant belongs to, and pins `ERROR_DOCS_URL` and the brand key beside it.
+
+**`core -> schema` is a declared edge `As of 2026-08-27`, and FIVE copies went with it.**
+`describeValue`, `charCount`, `CURRENCY_CODE_PATTERN`, `SCHEMA_ERROR_CODES` and `isIanaZoneName`
+were all restated here because both packages are tier 0 and neither could import the other; they
+were held equal by 394 lines of pin test in `@ultimat3/cli`, a TIER-5 package pinning a tier-0
+invariant that no rule required to exist. `describeValue` is the one that made it urgent — it
+prints INSTEAD of a rejected password, so the safety property of the framework's most
+security-sensitive renderer rested on a 63-line behavioural pin at tier 5. `error-render.ts`
+re-exports schema's now, and the four pin files are deleted.
+
+The edge cost was MEASURED before it was declared, because axiom 6 makes it a measurement and not
+an argument — `docs/architecture/01-package-map.md` carries the table. Short version: the edge
+alone TRIPLED a core-only browser chunk (6,362 → 19,018 B), because importing schema's barrel with
+no `sideEffects` field forces a bundler to keep every module it reaches; `@ultimat3/schema` now
+declares `sideEffects: false`, which `bun run side-effects` had already measured as true of it, and
+the cost drops to ~1 kB — while `moneyText` from `@ultimat3/ui`, which always carried schema, comes
+out 7.8 kB SMALLER.
+
+**A string's length is CODE POINTS, `As of 2026-08-22`**
 — `validators.ts` rejects in that unit and `json-schema.ts` publishes `minLength` in it, so
 `.length` made `t.string.min(3).safeParse('👍a')` say "at least 3 chars, received a string of 3
 characters". The rule it enforces: a `cause` reaches the log index AND the
@@ -125,7 +136,7 @@ shape against a locally declared sample interface for exactly that reason.
 | the five above, composed into one typed-client call | `client-flight.ts` + `client-wire.ts` | `@ultimat3/action` and `@ultimat3/query` both project a typed client and are both tier 3, so neither could import the other: it shipped as a byte-identical 288-line + 85-line copy in each, policed by a `client-twin.test.ts` in both. Both packages re-export these names, so their public surface is unchanged. Declares NO code of its own — `X_SUPERSEDED`, `X_TIMEOUT` and `X_FLIGHT_GATE_OVERLOADED` are already here |
 | is this `unknown` a keyed record? | `json-object.ts` | `isJsonObject`, which was the same three terms in both those packages' `stable.ts`. A `Date` and a class instance PASS: it narrows a shape, it does not certify provenance |
 | a value that must not be printed | `secret.ts` | redacted by VALUE; `revealSecret()` is the one way out, on purpose greppable |
-| an `Intl` formatter cache | `intl-cache.ts` (`cachedFormatter`, `canonicalLocale`, `MAX_CACHED_FORMATTERS`) | a locale and a zone arrive from a request header, so the key must be canonical AND the cache bounded — never a second copy of either half |
+| 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 and a zone arrive from a request header, so the tag must be REFUSED when it is not a tag (`X_LOCALE_INVALID`), the key must be canonical AND the cache bounded — never a second copy of any of the three. The refusal is bounded too: the `cause` quotes back at most `MAX_LOCALE_EXCERPT` (35, RFC 5646 §4.4.1) code points and says so when it cut, and the whole tag rides in `meta.locale` — a `cause` reaches the 400 body and the log line, where a value with no key has nothing a redactor can address |
 | the committed encrypted values | `secrets.ts` (envelope) + `secrets-store.ts` (files, `installSecrets`) | plaintext is a flat map of ENV NAMES; there is no `secrets.get()` |
 
 `installSecrets()` is the ONLY path from `secrets.enc.json` to an app value, and it lands in
@@ -144,6 +155,15 @@ and live in one file for that reason: a canonical key bounds nothing (an unknown
 value survives canonicalization as a distinct string) and the cap alone lets one locale evict
 itself under three spellings. Never build an `Intl` formatter on a caller string without both.
 
+`assertLocale` and `X_LOCALE_INVALID` moved here from `@ultimat3/time` in 16.x, for the third
+time the same argument was made: `@ultimat3/money` handed a malformed `Accept-Language` tag
+straight to `Intl.NumberFormat` at four entry points and let a bare `RangeError` out, and copying
+time's screen down would have been a second answer to one question. Validating and keying are ONE
+step — `getCanonicalLocales` runs exactly the check `supportedLocalesOf` throws on and hands back
+the spelling the cache keys on — which is why the screen lives in this file and not beside it. A
+code has one declaration: `X_LOCALE_INVALID` left `TIME_ERROR_CODES` in the same change, or
+`registerErrorCodes` would raise `X_ERROR_CODE_DUPLICATE` the moment both packages loaded.
+
 `secrets-errors.ts` registers its seven codes through `registerErrorCodes()` rather than joining
 `CORE_CODE_TITLES` — the codes and the module that throws them ship together, and `registerErrorCodes`
 is the one mechanism that raises `X_ERROR_CODE_DUPLICATE` if anything else claims one. Consequence
@@ -153,12 +173,14 @@ the master key) purely so *wrong key* and *edited file* are two codes and not on
 cannot tell them apart.
 
 `schema-error-codes.ts` is the same shape a second time, for codes this package does not even own.
-`@ultimat3/schema` is tier 0 like `core` and so can neither call `registerErrorCodes()` itself nor
-import core to reach it — the four codes' titles are a deliberate, tested duplicate of
-`SCHEMA_ERROR_CODES` in `packages/schema/src/errors.ts`, registered unconditionally at import time
-so any process that imports core (not just `@ultimat3/cli`, which used to be the only registrant)
-renders schema's real titles. Neither tier-0 package can check the duplicate against its source, so
-the pin (`schema-error-codes-pin.test.ts`) lives in `@ultimat3/cli`, which may legally import both.
+`@ultimat3/schema` is tier 0 like `core` and cannot call `registerErrorCodes()` itself — that would
+be `schema -> core`, which stays forbidden. So core READS `SCHEMA_ERROR_CODES` over the declared
+edge and registers it unconditionally at import time, and any process that imports core (not just
+`@ultimat3/cli`, which used to be the only registrant) renders schema's real titles. The retry
+classification is derived from the same set rather than typed out beside it: a fifth code would
+have been silently absent from a hand-written list, and an unregistered code reads as UNCLASSIFIED,
+so a schema refusal inside a job body burns the whole retry policy re-proving an answer no attempt
+can change.
 
 `timing-safe-equal.ts` holds the one constant-time string comparison `@ultimat3/auth` and
 `@ultimat3/storage` both need — core is the lowest tier both can reach, so the shared code lives
@@ -218,6 +240,28 @@ the layer imports anything but this package, nothing runs at import time, and ev
 non-determinism — the roll, the sleep, the clock, the timer — is injected, because a schedule
 provable only by waiting is a schedule no test pins.
 
+**`backoffDelay` REFUSES a non-finite bound, `As of 2026-08-26`, and that is a behaviour change.**
+It used to answer `0`, on the argument that 0 is "wrong loudly". It is not: measured,
+`retry({ attempts: 5, max: NaN })` slept `[0, 0, 0, 0]` and `factor: NaN` slept `[1000, 0, 0, 0]` —
+a retry loop with no wait at all, which is the failure backoff exists to prevent, on the tree's ONE
+curve (`bun run flight-copies`), reaching every retry in the framework. `attempt`, `base`, `max`
+and `factor` each go through `finiteOption` before the clamps, because `Math.max`, `Math.min` and
+`Math.trunc` propagate rather than validate and `Math.min(raw, Infinity)` is `Infinity`. The
+`return 0` below them stays and is still reachable, by exactly one route: `factor ** (step - 1)`
+overflows around attempt 1030 and `0 * Infinity` is `NaN` — a zero base is a caller asking for no
+wait, which is the answer it gets.
+
+**`finiteOption` / `finiteCount` (`finite-option.ts`) are the framework's ONE screen for a numeric
+option, `As of 2026-08-26`.** They landed here because `@ultimat3/jobs`, `@ultimat3/realtime` and
+`@ultimat3/query` each held a byte-identical copy; all three were deleted and now import these.
+`finiteCount(subject, option, value, min)` takes `min: 0 | 1` as a DEFAULT PARAMETER rather than
+shipping a third `finitePositive`, because only the caller knows what zero means —
+`requestTimeoutMs: 0` is "no deadline", a pool `max: 0` is a pool nothing can run on.
+`bun run finite-bounds` is the ratchet, and it recognises a repair by the SHAPE OF THE CALL: a
+package screen that does not carry `Finite` in its name is invisible to it, which is why
+`assertFiniteImageQuality`, `assertFiniteOtlpBound` and their siblings in five other packages are
+spelled that way.
+
 Two rules that are not preferences. `backoffDelay` clamps to `max` **before** jitter: capping after
 turns `full` into a distribution whose upper half is a single value at `max`, which is the
 correlation jitter exists to remove. `createFlightGate` **hands** its slot to a waiter rather than

package/README.md

@@ -30,6 +30,7 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | the committed encrypted secrets envelope, AES-256-GCM | `secrets.ts` |
 | the two secrets files, and decrypted values → `defineEnv` | `secrets-store.ts` |
 | `defineConfig()` for `app.config.ts` | `config.ts` |
+| the `pwa` block — what an install needs, and the boot refusal when it is not there | `config-pwa.ts` |
 | the closed route vocabulary every renderer names | `route-vocabulary.ts` |
 | runtime roles + `ROLE` resolution | `roles.ts` |
 | `Clock` — the only source of "now" | `clock.ts` |
@@ -316,7 +317,9 @@ nothing and still reports healthy.
 - **Sampling is honoured, not just propagated.** `startSpan` takes the parent's bit when there is
   one, else asks the `Sampler`; `span.end()` exports nothing when the bit is 0. The default reads
   `OTEL_TRACES_SAMPLER` / `OTEL_TRACES_SAMPLER_ARG` at the first span, and
-  `configureTelemetry({ sampler })` replaces it.
+  `configureTelemetry({ sampler })` replaces it. `shouldSample` is handed the TRACE ID of the span
+  being created, so `traceidratio` decides once per trace by hashing it — a roll per span left one
+  trace half exported, which is orphan children under a root the collector never saw.
 - **The OTLP exporters ship**, speaking OTLP/HTTP JSON, no dependency:
   `otlpSpanExporter({ endpoint })` (batched, with `flush()` / `shutdown()`) and
   `otlpMetricExporter({ endpoint })`. Both default to `OTEL_EXPORTER_OTLP_ENDPOINT`;
@@ -457,13 +460,16 @@ never a silently wrong page.
 ## One bounded cache for every `Intl` formatter
 
 ```ts
-import { cachedFormatter, canonicalLocale } from '@ultimat3/core';
+import { assertLocale, cachedFormatter } from '@ultimat3/core';
 
 const cache = new Map<string, Intl.NumberFormat>();
 
 export function euroFormatter(locale: string): Intl.NumberFormat {
-  // `EN-us` and `en-latn-us` collapse to one key, so one locale cannot evict itself.
-  const tag = canonicalLocale(locale) ?? locale;
+  // Validates AND canonicalizes: `EN-us` and `en-latn-us` collapse to one key, and a tag `Intl`
+  // cannot parse is `X_LOCALE_INVALID` here rather than a bare `RangeError` out of the constructor
+  // below. `canonicalLocale(locale) ?? locale` is the same call with the refusal deleted — it is
+  // what `@ultimat3/money` did, and an `Accept-Language` value of `en_US` took the request down.
+  const tag = assertLocale(locale);
   return cachedFormatter(
     cache,
     `${tag}|EUR`,
@@ -482,6 +488,17 @@ string, and the cap alone lets one locale evict itself under three spellings. A
 `Intl` construction, never a wrong answer, which is what makes the bound safe. It lives here rather
 than in `@ultimat3/time` because `@ultimat3/money` needs it too and tier 1 may not import sideways.
 
+The **refusal** is bounded for the same reason the cache is. `X_LOCALE_INVALID` answers 400 and
+`@ultimat3/http`'s `toProblem` copies a `cause` into the response `detail` **and** into the log
+line, so a tag echoed verbatim is a stranger-chosen string of unbounded length in a shared log
+index. `localeInvalid` quotes back the first `MAX_LOCALE_EXCERPT` (35) code points — RFC 5646
+§4.4.1's own figure for the longest tag the registry can form — and appends
+`(truncated at 35 characters)` when there were more, so a cut value is never read as a whole one.
+`describeValue` is deliberately **not** used here: "a 5-character string" deletes the only
+actionable content in a sentence whose job is to name the tag. The whole tag rides in
+`meta.locale`, which is the half that gives a redactor a key to address; a value spliced into
+prose has none.
+
 ## One flight layer — wait, classify, share, bound, fence
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "16.0.0",
+  "version": "18.0.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",
@@ -30,11 +30,13 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.3.0"
+    "bun": ">=1.4.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
-  "dependencies": {}
+  "dependencies": {
+    "@ultimat3/schema": "18.0.0"
+  }
 }

package/src/backoff.ts

@@ -3,6 +3,8 @@
 // (equal jitter), `@ultimat3/ai` (full jitter, `Math.random` inline and so untestable),
 // `@ultimat3/realtime` (full jitter, 0-based attempt) and `@ultimat3/db` (no backoff at all).
 
+import { finiteOption } from './finite-option';
+
 export type BackoffCurve = 'exponential' | 'linear' | 'fixed';
 
 /**
@@ -12,6 +14,9 @@ export type BackoffCurve = 'exponential' | 'linear' | 'fixed';
  */
 export type JitterMode = 'full' | 'equal' | 'none';
 
+/** Named in every refusal below, so a reader knows which call built the schedule. */
+const SUBJECT = 'backoffDelay';
+
 /** Injected everywhere. A delay only provable by observing a range is a delay no test pins. */
 export type Random = () => number;
 
@@ -38,19 +43,26 @@ export interface BackoffOptions {
  * jitter exists to remove.
  */
 export function backoffDelay(options: BackoffOptions): number {
-  const step = Math.max(1, Math.trunc(options.attempt));
-  const base = Math.max(0, options.base);
-  const factor = options.factor ?? 2;
+  // Every bound is REFUSED before it is clamped, because the clamps are not validators: measured,
+  // `retry({ attempts: 5, max: NaN })` slept `[0, 0, 0, 0]` and `factor: NaN` slept
+  // `[1000, 0, 0, 0]` — `Math.max`, `Math.min` and `Math.trunc` each propagate it,
+  // `Math.min(raw, Infinity)` is `Infinity`, and the `return 0` below then turns the whole
+  // schedule into a spin.
+  const step = Math.max(1, Math.trunc(finiteOption(SUBJECT, 'attempt', options.attempt)));
+  const base = Math.max(0, finiteOption(SUBJECT, 'base', options.base));
+  const max = finiteOption(SUBJECT, 'max', options.max);
+  const factor = finiteOption(SUBJECT, 'factor', options.factor ?? 2);
 
   let raw: number;
   if (options.curve === 'fixed') raw = base;
   else if (options.curve === 'linear') raw = base * step;
   else raw = base * factor ** (step - 1);
 
-  const capped = Math.max(0, Math.min(raw, options.max));
-  // A NaN reaches here from an unvalidated config value, and `setTimeout(NaN)` fires IMMEDIATELY —
-  // a retry loop with no wait at all, which is the failure mode backoff exists to prevent. 0 is
-  // wrong too, but it is wrong loudly: the next attempt still happens once, not in a tight spin.
+  const capped = Math.max(0, Math.min(raw, max));
+  // Still reachable with four finite inputs, and only one way: `factor ** (step - 1)` overflows to
+  // `Infinity` around attempt 1030, and `0 * Infinity` is `NaN`. A zero base is a caller asking
+  // for no wait, so 0 is the answer it asked for — it is no longer the answer an unvalidated
+  // config value gets, which is what this line used to be.
   if (!Number.isFinite(capped)) return 0;
 
   const roll = options.random ?? Math.random;

package/src/config-pwa.ts

@@ -0,0 +1,118 @@
+// Single responsibility: the `pwa` block of `app.config.ts` — what an app must say before a
+// browser will offer to install it, and the boot-time refusal when it has not.
+//
+// SPLIT OUT OF `config.ts` because that file reached its 500-line ceiling, and this is the seam
+// that costs nothing to cross: `enabled` turns four other requirements on, so the shape, the screen
+// and the remedy are one subject. `config.ts` keeps the one call.
+//
+// WHY THE SCREEN IS HERE AND NOT AT EMIT. `@ultimat3/pwa`'s `generateWebManifest` refuses a blank
+// title too, and that refusal arrives at `x build` — which is the wrong moment: an agent that ran
+// `x dev`, saw a served app and shipped it would meet the missing title in CI. Two checks, two
+// subjects (a config file, and a function argument a library caller supplies directly).
+
+import { describeValue } from './error-render';
+// `app.config.ts` CONSUMES the route vocabulary; it does not own it — `config.ts`'s rule, and the
+// reason `OfflineStrategy` is imported rather than restated.
+import type { OfflineStrategy } from './route-vocabulary';
+
+/**
+ * `installPrompt` was removed 2026-08, same rule: `@ultimat3/pwa`'s `createInstallController` is
+ * real and complete, nothing ever threaded the flag into it, and both tracked apps plus every
+ * scaffolded app set a switch with no wire. Call the controller from your own affordance instead.
+ */
+export interface PwaConfig {
+  readonly enabled: boolean;
+  readonly offline: OfflineStrategy;
+  readonly backgroundSync: boolean;
+  readonly push: boolean;
+  /**
+   * The install title, and the one manifest member nothing can derive. `AppConfig.name` is a slug
+   * (`^[a-z][a-z0-9-]{1,63}$`) and an install prompt shows a person a title, so `ledger-demo` is
+   * the wrong answer rather than a rough one. Required once `enabled` is true; `''` is what a
+   * disabled block resolves to.
+   */
+  readonly name: string;
+  /**
+   * `theme_color` and `background_color`, per scheme. Required once `enabled` is true, and
+   * `undefined` otherwise — never a colour the framework picked. There is no defensible default:
+   * an install splash painted in a colour nobody chose is a wrong-looking app that boots, which is
+   * worse than a boot that names the four values it needs.
+   */
+  readonly colors: PwaColors | undefined;
+}
+
+/**
+ * The install chrome's two colours for one scheme, as CSS colour strings.
+ *
+ * ONE OF THE TWO PLACES A RAW COLOUR IS LEGAL, alongside `ThemeConfig.tokens` one section up, and
+ * for a stronger reason than that one has: a browser paints the install splash and the address bar
+ * from these before a single stylesheet has loaded, so there is no token to resolve them against
+ * and no component anywhere in the loop.
+ */
+export interface PwaSchemeColors {
+  readonly themeColor: string;
+  readonly backgroundColor: string;
+}
+
+/**
+ * Both schemes, because a web manifest carries exactly one `theme_color` and `<head>` carries a
+ * media-scoped `<meta name="theme-color">` per scheme. One value would make the dark answer the
+ * light one's, on the surface a reader sees before the app has painted anything.
+ */
+export interface PwaColors {
+  readonly light: PwaSchemeColors;
+  readonly dark: PwaSchemeColors;
+}
+
+/**
+ * The two schemes and the two colours `validate` screens, for `INBOX_RETENTION_KEYS`' reason: a
+ * third member added to `PwaColors` or `PwaSchemeColors` without a row here is a value an app can
+ * leave blank, and `config.test.ts` asserts both lists against the types so the omission is a red
+ * test rather than a manifest with an empty `theme_color`.
+ */
+export const PWA_SCHEMES = ['light', 'dark'] as const;
+export const PWA_COLOR_KEYS = ['themeColor', 'backgroundColor'] as const;
+
+/**
+ * Appended only when the `pwa` block is what failed, and it carries the whole block rather than
+ * the missing key: `pwa.enabled` is what turns four other requirements on, so a reader who set one
+ * boolean needs to see the complete shape and the opt-out in the same line.
+ */
+export const PWA_FIX =
+  "in app.config.ts, complete the pwa block: pwa: { enabled: true, offline: 'runtime', name: 'My App', colors: { light: { themeColor: '#1b1f3b', backgroundColor: '#ffffff' }, dark: { themeColor: '#1b1f3b', backgroundColor: '#0b0d1a' } } } — a browser paints the install splash and the address bar from those four values before any stylesheet loads, so there is nothing for the framework to derive them from; or set pwa.enabled: false";
+
+/**
+ * Every rule `validate` applies to the block, appended to the caller's own issue list. Answers
+ * whether IT found anything, so the pwa remedy rides only on a pwa finding: `issues` may already
+ * hold a bad locale, and a fix line naming the install block for that is axiom 4 broken.
+ *
+ * `describeValue` for the reason the retention windows use it — this is where an untyped config
+ * object crosses into the framework, so every value here is `unknown` however the interface types it.
+ */
+export function pwaIssues(pwa: PwaConfig, issues: string[]): boolean {
+  if (!pwa.enabled) return false;
+  const before = issues.length;
+  const { name, colors } = pwa;
+  if (typeof name !== 'string' || name.trim() === '') {
+    issues.push(`pwa.name is required when pwa.enabled is true, and is ${describeValue(name)}`);
+  }
+  // `typeof !== 'object' || null`, never `=== undefined`: an untyped `app.config.ts` writing
+  // `pwa.colors: null` reached `null[scheme]` one line down and took the boot out with a native
+  // `TypeError`, from the validator whose whole job is producing an instruction instead of one.
+  if (colors === null || typeof colors !== 'object') {
+    issues.push(
+      `pwa.colors is required when pwa.enabled is true, for both light and dark, and is ${describeValue(colors)}`,
+    );
+  } else {
+    for (const scheme of PWA_SCHEMES) {
+      for (const key of PWA_COLOR_KEYS) {
+        const value: unknown = colors[scheme]?.[key];
+        if (typeof value === 'string' && value.trim() !== '') continue;
+        issues.push(
+          `pwa.colors.${scheme}.${key} must be a CSS colour, not ${describeValue(value)}`,
+        );
+      }
+    }
+  }
+  return issues.length > before;
+}

package/src/config.ts

@@ -2,16 +2,16 @@
 // 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 { PwaConfig } from './config-pwa';
+import { PWA_FIX, pwaIssues } from './config-pwa';
+import { describeValue } from './error-render';
 import { ConfigInvalidError } from './errors';
 import { ROLES, type Role } from './roles';
-// `app.config.ts` CONSUMES the route vocabulary; it does not own it. Declaring `OfflineStrategy`
-// here is what made it copyable — `render`, `manifest` and `pwa` each wrote their own rather than
-// import a name that reads like a config key.
-import type { OfflineStrategy } from './route-vocabulary';
 import { isIanaZoneName } from './time-zone-name';
 
 export type ThemeMode = 'light' | 'dark' | 'system';
@@ -41,17 +41,37 @@ export interface AuthConfig {
 }
 
 /**
- * `installPrompt` was removed 2026-08, same rule: `@ultimat3/pwa`'s `createInstallController` is
- * real and complete, nothing ever threaded the flag into it, and both tracked apps plus every
- * scaffolded app set a switch with no wire. Call the controller from your own affordance instead.
+ * Retention for `x_notify_inbox`, and the one framework table whose window the framework may not
+ * pick. Every other one holds bookkeeping whose job ENDS — an idempotency key, a rate-limit
+ * bucket, an auth challenge, a delivery claim — and a sweep is unambiguously right. An inbox row
+ * is a message a person has not read yet, so when it disappears is a product decision, which is
+ * axiom 8: Ultimate ships mechanism, your app ships convention.
+ *
+ * BOTH DEFAULT TO `undefined`, meaning never swept, and that is the only safe default here: the
+ * failure mode of keeping rows is a table that grows, and the failure mode of guessing a number is
+ * a notification the recipient never got to read.
+ *
+ * TWO WINDOWS RATHER THAN ONE, because the axiom-8 objection is only about UNREAD messages. An app
+ * that wants read notices gone in a month and unread ones kept forever must be able to say exactly
+ * that, and `SQL_NOTIFY_INBOX_MARK_READ` already stamps the time that makes it expressible.
+ *
+ * Milliseconds and not a `DurationInput`: that type lives in `@ultimat3/jobs` (tier 3) and this
+ * package is tier 0, which is the same reason `cache.defaultTtlMs` and `jobs.visibilityTimeoutMs`
+ * are spelled this way.
  */
-export interface PwaConfig {
-  readonly enabled: boolean;
-  readonly offline: OfflineStrategy;
-  readonly backgroundSync: boolean;
-  readonly push: boolean;
+export interface NotifyConfig {
+  /** Age of a row's `read_at`, not its `created_at` — a row ages from when it was READ. */
+  readonly inboxReadRetentionMs: number | undefined;
+  /** Age of an unread row's `created_at`. Setting this deletes messages nobody has read. */
+  readonly inboxUnreadRetentionMs: number | undefined;
 }
 
+/**
+ * Every window `validate` screens, derived from nothing — a third one added to `NotifyConfig`
+ * without a row here is a window an app can set to `-1`, and `config.test.ts` asserts the two
+ * lists agree so the omission is a red test rather than a silent hole.
+ */
+export const INBOX_RETENTION_KEYS = ['inboxReadRetentionMs', 'inboxUnreadRetentionMs'] as const;
 /**
  * Deliberately thin. `urlEnv`, `poolSize` and `schema` were removed 2026-08 because **nothing
  * read them** — the only reader of any `config.database.*` field in the repo was this file's own
@@ -166,6 +186,7 @@ export interface AppConfig {
   readonly cache: CacheConfig;
   readonly jobs: JobsConfig;
   readonly realtime: RealtimeConfig;
+  readonly notify: NotifyConfig;
   readonly ai: AiConfig;
 }
 
@@ -190,6 +211,7 @@ export interface AppConfigInput {
   readonly cache?: Input<CacheConfig> | undefined;
   readonly jobs?: Input<JobsConfig> | undefined;
   readonly realtime?: Input<RealtimeConfig> | undefined;
+  readonly notify?: Input<NotifyConfig> | undefined;
   readonly ai?: AiConfigInput | undefined;
 }
 
@@ -212,18 +234,13 @@ function section<T extends object>(base: T, patch: Input<T> | undefined): T {
 const NAME_RE = /^[a-z][a-z0-9-]{1,63}$/;
 
 /**
- * A deliberate duplicate of `CURRENCY_CODE_PATTERN` in `packages/schema/src/money-value.ts`, which
- * is the framework's ONE declaration of what an ISO 4217 code looks like and the source
- * `isCurrencyCode`, the published OpenAPI `pattern` and `@ultimat3/entity`'s Postgres CHECK all
- * derive from. This file cannot import it: `core` and `schema` are both tier 0 and `core → schema`
- * is not in `SIDEWAYS_ALLOW` (`scripts/lib/tiers.ts`), the same wall that makes `describeValue` a
- * character-for-character copy in `error-render.ts`.
- *
- * So keep the two identical, and keep the pattern inside the syntax ECMAScript, JSON Schema and
- * POSIX ERE spell identically — a `defaultCurrency` this accepts and `t.money` refuses is an app
- * whose configured currency cannot be written to a row.
+ * 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 = /^[A-Z]{3}$/;
+const CURRENCY_RE = new RegExp(CURRENCY_CODE_PATTERN);
 
 function isLocale(value: string): boolean {
   try {
@@ -241,7 +258,14 @@ function defaults(name: string): Omit<AppConfig, 'name'> {
     defaultCurrency: 'USD',
     theme: { defaultMode: 'system', tokens: {} },
     auth: { signInPath: null },
-    pwa: { enabled: false, offline: 'network-only', backgroundSync: false, push: false },
+    pwa: {
+      enabled: false,
+      offline: 'network-only',
+      backgroundSync: false,
+      push: false,
+      name: '',
+      colors: undefined,
+    },
     roles: [...ROLES],
     database: { driver: 'postgres', ssl: false },
     cache: { defaultTtlMs: 60_000, tiers: ['request-memo', 'lru'] },
@@ -253,6 +277,7 @@ function defaults(name: string): Omit<AppConfig, 'name'> {
       visibilityTimeoutMs: 30_000,
     },
     realtime: { enabled: false, transport: 'memory', urlEnv: undefined },
+    notify: { inboxReadRetentionMs: undefined, inboxUnreadRetentionMs: undefined },
     ai: { mcp: { expose: true, path: '/mcp' } },
   };
 }
@@ -284,6 +309,8 @@ function validate(config: AppConfig): void {
   // 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.
   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)) {
     issues.push(`name "${config.name}" must match ${String(NAME_RE)}`);
@@ -313,6 +340,27 @@ function validate(config: AppConfig): void {
   if (config.realtime.transport !== 'memory' && config.realtime.urlEnv === undefined) {
     issues.push(`realtime.transport "${config.realtime.transport}" requires realtime.urlEnv`);
   }
+  // BOTH RETENTION WINDOWS OR NEITHER — `undefined` is a real value here (never swept) and the
+  // only other legal one is a positive, finite count of milliseconds. Zero is refused rather than
+  // read as "immediately": a sweep at age 0 deletes every row the instant it is written, which is
+  // an inbox that silently receives nothing, and nobody types it on purpose. `describeValue`
+  // rather than `${…}`: this validator is the boundary a JS app's untyped config crosses, so the
+  // value here is `unknown` in practice however the interface types it.
+  for (const key of INBOX_RETENTION_KEYS) {
+    const ms: unknown = config.notify[key];
+    if (ms === undefined) continue;
+    if (typeof ms !== 'number' || !Number.isFinite(ms) || ms <= 0) {
+      issues.push(
+        `notify.${key} must be a positive number of milliseconds, not ${describeValue(ms)}`,
+      );
+    }
+  }
+
+  // What an install needs, asked at BOOT and not at emit — `config-pwa.ts` owns the rules and the
+  // remedy, because `pwa.enabled` turning four other requirements on is a question about that block
+  // and nothing else here.
+  if (pwaIssues(config.pwa, issues)) pwaFix.push(PWA_FIX);
+
   // 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.
@@ -327,7 +375,7 @@ 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, BASE_FIX].join('. '),
+      fix: [...zoneFix, ...tierFix, ...pwaFix, BASE_FIX].join('. '),
       meta: { issues },
     });
   }
@@ -363,6 +411,7 @@ export function defineConfig(
     cache: section(base.cache, merged.cache),
     jobs: section(base.jobs, merged.jobs),
     realtime: section(base.realtime, merged.realtime),
+    notify: section(base.notify, merged.notify),
     ai: { mcp: section(base.ai.mcp, merged.ai?.mcp) },
   };
 

package/src/context.ts

@@ -34,6 +34,7 @@ import { type Actor, anonymousActor } from './actor';
 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 { type Logger, logger as rootLogger, setLoggerContextFields } from './logger';
 import { type Role, resolveRole } from './roles';
@@ -173,7 +174,7 @@ export function createContext(init: CtxInit = {}): Ctx {
     now: () => clock.now(),
     logger: base.child({ requestId, traceId: trace }),
     signal: init.signal ?? neverAborted,
-    deadlineAt: init.deadlineAt ?? null,
+    deadlineAt: screenDeadline(init.deadlineAt),
   };
   // A registered service (`defineService`) closes over the ctx it is built for — actor, clock,
   // tz — so it has to run HERE, against this exact call's fields, rather than once at boot and
@@ -231,6 +232,35 @@ export function hasContext(): boolean {
   return tryUseContext() !== undefined;
 }
 
+/**
+ * The tighter of two instants, where absent means "no bound" — the bounded form
+ * `lifecycle.ts`'s drain budget uses, over two optional values instead of one. Returns
+ * `undefined` rather than `null` because that is what `CtxInit.deadlineAt` spells.
+ */
+function earliest(left: number | undefined, right: number | null | undefined): number | undefined {
+  if (left === undefined) return right ?? undefined;
+  if (right === undefined || right === null) return left;
+  return Math.min(left, right);
+}
+
+/**
+ * The one screen over `deadlineAt`, at both boundaries that can set it. A deadline is an instant,
+ * not a count, so `finiteOption` rather than `finiteCount` — a clock epoch is legitimately large
+ * and a test clock's is legitimately small.
+ *
+ * WHY IT IS REFUSED AND NOT CLAMPED, in this file specifically: `Math.min` PROPAGATES `NaN`, so one
+ * non-finite side poisons the child's deadline as well as its own. `remainingBudgetMs` then asks
+ * `left >= 1` of a `NaN`, gets `false`, and answers `undefined` — the same answer it gives for "no
+ * deadline at all". So the `x-request-timeout-ms` header is silently omitted and the next hop falls
+ * back to its OWN configured budget, which `request-budget.ts`'s own header calls "the exact
+ * failure this header exists to prevent". A deadline that quietly stops bounding anything is the
+ * dangerous direction, and it is the direction `??` cannot see, because `NaN` is not nullish.
+ */
+function screenDeadline(value: number | null | undefined): number | null {
+  if (value === undefined || value === null) return null;
+  return finiteOption('the request context', 'deadlineAt', value);
+}
+
 /**
  * Derive a narrowed context — impersonation, a locale switch, a per-step abort signal.
  * `requestId` is deliberately not patchable: one request, one id.
@@ -256,8 +286,10 @@ export function withChildContext<T>(patch: CtxPatch, fn: () => T): T {
     logger: patch.logger ?? parent.logger,
     // One request, one budget: a child scope inherits the deadline for the same reason it
     // inherits `requestId`. A patch may SHORTEN it (a step with its own budget); nothing here
-    // lengthens it, because the socket the parent is answering does not move.
-    deadlineAt: patch.deadlineAt ?? parent.deadlineAt ?? undefined,
+    // lengthens it, because the socket the parent is answering does not move. `??` alone said
+    // 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,
     services: { ...carried, ...(patch.services ?? {}) },
   });

package/src/error-codes.ts

@@ -52,6 +52,9 @@ const CORE_CODE_TITLES = {
   X_IMAGE_UNSUPPORTED: 'the built-in image pipeline cannot read or write this format',
   X_INTERNAL: 'unexpected internal framework error',
   X_INVARIANT: 'invariant violated',
+  // Owned here rather than by `@ultimat3/time`, which declared it until 16.x: `@ultimat3/money`
+  // needs the same screen and tier 1 may not import sideways. One code, one declaration.
+  X_LOCALE_INVALID: 'not a well-formed BCP 47 tag',
   X_METRIC_CARDINALITY:
     'a metric exceeded its series ceiling and is folding into one overflow series',
   X_METRIC_NAME_INVALID: