@ultimat3/core 17.0.0 → 19.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, and the screen in front of it | `intl-cache.ts` (`cachedFormatter`, `canonicalLocale`, `assertLocale`, `MAX_CACHED_FORMATTERS`) | 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 |
+| 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
@@ -162,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

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` |
@@ -487,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": "17.0.0",
+  "version": "19.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": "19.0.0"
+  }
 }

package/src/config-pwa.ts

@@ -0,0 +1,149 @@
+// 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';
+
+/**
+ * `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.
+ */
+/**
+ * What the service worker needs that no route can say for itself.
+ *
+ * `fallback` is the document a navigation gets when the network is gone and the cache has no
+ * answer — the one thing an offline app cannot do without, and the reason this block replaced a
+ * bare `offline: OfflineStrategy`. That key was an app-wide DEFAULT for a field `defineRoute`
+ * makes **required** on every route (`route.ts` refuses a route without one), so it defaulted
+ * nothing, was read by nobody, and could not be given a reader without inventing a meaning for it
+ * (#390).
+ *
+ * The other three are `@ultimat3/pwa`'s `OfflineConfig` verbatim, and each is read by the emitter
+ * that builds `sw.js`: a placeholder image, a placeholder font, and the request patterns that must
+ * never be answered from a cache — auth and payments, where a stale 200 is worse than a failure.
+ */
+export interface PwaOfflineConfig {
+  /** Absolute route path of the offline document, e.g. `/offline`. Required once `enabled`. */
+  readonly fallback: string | null;
+  readonly image: string | null;
+  readonly font: string | null;
+  readonly neverCache: readonly string[];
+}
+
+export interface PwaConfig {
+  readonly enabled: boolean;
+  readonly offline: PwaOfflineConfig;
+  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: { fallback: '/offline' }, 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, and offline.fallback is the document the emitted sw.js serves when the network is gone, so add a route at that path too; 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)}`);
+  }
+  // An ABSOLUTE path, screened here rather than at emit for this file's own stated reason: a
+  // relative one resolves against whatever document registered the worker, so `offline` served
+  // under `/posts/1` is `/posts/offline` — a 404 cached as the answer to every offline navigation.
+  // `pwa.enabled` means an installable app, and an installable app that shows the browser's error
+  // page offline is the failure the whole block exists to prevent, so this is required rather
+  // than optional: the alternative is two meanings for one switch (axiom 1).
+  const fallback: unknown = pwa.offline?.fallback;
+  if (typeof fallback !== 'string' || !fallback.startsWith('/')) {
+    issues.push(
+      `pwa.offline.fallback is required when pwa.enabled is true and must be an absolute route path like "/offline", and is ${describeValue(fallback)}`,
+    );
+  }
+  // `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, PwaOfflineConfig } 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;
 }
 
@@ -176,6 +197,17 @@ export interface AiConfigInput {
   readonly mcp?: Input<McpConfig> | undefined;
 }
 
+/**
+ * `offline` is NESTED for `AiConfigInput`'s reason, and here it is load-bearing rather than
+ * ergonomic: `section` applies a patch ONE level deep, so an app writing
+ * `offline: { fallback: '/offline' }` under a flat `Input<PwaConfig>` would replace the whole
+ * default block — leaving `image`, `font` and `neverCache` absent at run time while the type says
+ * they are there, which is the exact shape of defect this repo keeps re-shipping.
+ */
+export interface PwaConfigInput extends Omit<Input<PwaConfig>, 'offline'> {
+  readonly offline?: Input<PwaOfflineConfig> | undefined;
+}
+
 export interface AppConfigInput {
   readonly name: string;
   readonly locales?: readonly string[] | undefined;
@@ -184,12 +216,13 @@ export interface AppConfigInput {
   readonly defaultCurrency?: string | undefined;
   readonly theme?: Input<ThemeConfig> | undefined;
   readonly auth?: Input<AuthConfig> | undefined;
-  readonly pwa?: Input<PwaConfig> | undefined;
+  readonly pwa?: PwaConfigInput | undefined;
   readonly roles?: readonly Role[] | undefined;
   readonly database?: Input<DatabaseConfig> | undefined;
   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 +245,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 +269,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: { fallback: null, image: null, font: null, neverCache: [] },
+      backgroundSync: false,
+      push: false,
+      name: '',
+      colors: undefined,
+    },
     roles: [...ROLES],
     database: { driver: 'postgres', ssl: false },
     cache: { defaultTtlMs: 60_000, tiers: ['request-memo', 'lru'] },
@@ -253,6 +288,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 +320,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 +351,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 +386,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 },
     });
   }
@@ -357,12 +416,19 @@ export function defineConfig(
     defaultCurrency: merged.defaultCurrency ?? base.defaultCurrency,
     theme: section(base.theme, merged.theme),
     auth: section(base.auth, merged.auth),
-    pwa: section(base.pwa, merged.pwa),
+    // Two `section` calls, one per level: the outer one may not see `offline` at all, or it would
+    // drop the nested defaults `PwaConfigInput` exists to keep. Hence the cast — the outer patch is
+    // this block minus the key the inner call owns.
+    pwa: {
+      ...section(base.pwa, { ...merged.pwa, offline: undefined } as Input<PwaConfig>),
+      offline: section(base.pwa.offline, merged.pwa?.offline),
+    },
     roles: merged.roles ?? base.roles,
     database: section(base.database, merged.database),
     cache: section(base.cache, merged.cache),
     jobs: section(base.jobs, merged.jobs),
     realtime: section(base.realtime, merged.realtime),
+    notify: section(base.notify, merged.notify),
     ai: { mcp: section(base.ai.mcp, merged.ai?.mcp) },
   };
 

package/src/error-render.ts

@@ -252,57 +252,14 @@ export function renderMetaRecord(
  * There is no dev-only escape hatch on purpose — a flag is one misconfigured environment away
  * from being the same breach.
  *
- * A deliberate duplicate of `describeValue` in `packages/schema/src/describe-value.ts`, for the
- * reason `SCHEMA_ERROR_CODE_TITLES` is one: `@ultimat3/schema` is tier 0 alongside this package,
- * so neither may import the other. Keep the two answering IDENTICALLY — that is what
- * `packages/cli/src/describe-value-pin.test.ts` holds — and changing one alone is the bug.
- */
-export function describeValue(value: unknown): string {
-  if (value === undefined) return 'undefined';
-  if (value === null) return 'null';
-  switch (typeof value) {
-    case 'string':
-      return countOf(charCount(value), 'string', 'character');
-    case 'number':
-      return describeNumber(value);
-    case 'boolean':
-      return 'a boolean';
-    case 'bigint':
-      return 'a bigint';
-    case 'symbol':
-      return 'a symbol';
-    case 'function':
-      return 'a function';
-    default:
-      break;
-  }
-  if (Array.isArray(value)) return countOf(value.length, 'array', 'item');
-  // `getTime()` rather than a value: an invalid Date is the one Date fact a caller can act on.
-  if (value instanceof Date) return Number.isNaN(value.getTime()) ? 'an invalid Date' : 'a Date';
-  return 'an object';
-}
-
-function describeNumber(value: number): string {
-  if (Number.isNaN(value)) return 'NaN';
-  if (value === Number.POSITIVE_INFINITY) return 'Infinity';
-  if (value === Number.NEGATIVE_INFINITY) return '-Infinity';
-  return 'a number';
-}
-
-function countOf(size: number, noun: string, unit: string): string {
-  if (size === 0) return `an empty ${noun}`;
-  const article = noun === 'array' ? 'an' : 'a';
-  return `${article} ${noun} of ${size} ${unit}${size === 1 ? '' : 's'}`;
-}
-
-/**
- * The twin of `@ultimat3/schema`'s `char-count.ts`, duplicated for the same reason `describeValue`
- * is: both packages are tier 0 and neither may import the other. Code points, because the rules
- * that reject a string count in them and the message must quote the same unit — `'👍'.length` is 2.
- * Only a surrogate makes the two counts differ, so every ASCII value keeps the O(1) read.
+ * DECLARED IN `@ultimat3/schema` and re-exported here, `As of 2026-08-27`. It was a
+ * character-for-character copy of `packages/schema/src/describe-value.ts` — the two tier-0
+ * packages could not import each other — held equal by a 63-line behavioural pin in
+ * `@ultimat3/cli`, a TIER-5 package, that no rule required to exist. Whose function it is has not
+ * changed: schema's `expected()` is the other reader, and a widening that leaks a value is now one
+ * edit in one file rather than two files that can drift apart in silence.
+ *
+ * `charCount` went with it — the same duplication, one call deep — so the unit a message quotes
+ * and the unit a length rule counts in are the same code, not two files that agree today.
  */
-const HAS_SURROGATE = /[\uD800-\uDBFF]/;
-
-function charCount(value: string): number {
-  return HAS_SURROGATE.test(value) ? [...value].length : value.length;
-}
+export { describeValue } from '@ultimat3/schema';

package/src/index.ts

@@ -5,6 +5,17 @@
 // secrets — because each is one subject spread over a dozen modules. Every name they carry is
 // still written out below: `export *` would make the contract something a reader has to resolve.
 
+// Anchored on purpose, and NOT by the `sideEffects` array: Bun reads any array as `false` and drops
+// the module regardless (oven-sh/bun#40650). This module registers @ultimat3/schema's error TITLES,
+// because schema is tier 0 and cannot register its own — and what reads them is `UltimateError`'s
+// constructor, which never imports this file. Shaken out, every X_VALIDATION_FAILED renders
+// untitled in the browser with nothing to say why. `SIDE_EFFECTS_ANCHORS` carries the argument and
+// `bun run side-effects` enforces it. `context.ts`, `lifecycle-errors.ts` and `secrets-errors.ts`
+// are declared side-effecting too and are deliberately NOT anchored: each is reached by whatever
+// uses it, and anchoring `context.ts` alone measured +3,485 B on a browser chunk for a provider a
+// browser can never fire.
+import './schema-error-codes';
+
 export type {
   Actor,
   ActorFactKey,
@@ -65,13 +76,16 @@ export type {
   DatabaseConfig,
   JobsConfig,
   McpConfig,
-  PwaConfig,
+  NotifyConfig,
+  PwaConfigInput,
   RealtimeConfig,
   RealtimeTransport,
   ThemeConfig,
   ThemeMode,
 } from './config';
-export { defineConfig } from './config';
+export { defineConfig, INBOX_RETENTION_KEYS } from './config';
+export type { PwaColors, PwaConfig, PwaOfflineConfig, PwaSchemeColors } from './config-pwa';
+export { PWA_COLOR_KEYS, PWA_SCHEMES } from './config-pwa';
 export type { Ctx, CtxFacts, CtxInit, CtxPatch, CtxServices, ServiceBag } from './context';
 export {
   createContext,
@@ -461,6 +475,7 @@ export {
   canonicalLocale,
   localeInvalid,
   MAX_CACHED_FORMATTERS,
+  MAX_LOCALE_EXCERPT,
 } from './intl-cache';
 export { isJsonObject } from './json-object';
 export type {

package/src/intl-cache.ts

@@ -27,6 +27,16 @@ export function cachedFormatter<T>(cache: Map<string, T>, key: string, build: ()
   return formatter;
 }
 
+/**
+ * The cap on the tag an `X_LOCALE_INVALID` cause quotes back, in code points.
+ *
+ * 35 is RFC 5646 §4.4.1's own number — Figure 7 derives it as the longest tag the registry can
+ * form (language 8 + script 5 + region 4 + two variants 9+9), and the same section says a protocol
+ * with a fixed buffer "MUST allow for language tags of at least 35 characters". So every tag a
+ * caller could legitimately have meant fits, and nothing longer is a tag being debugged.
+ */
+export const MAX_LOCALE_EXCERPT = 35;
+
 /**
  * The canonical BCP 47 spelling, or `undefined` when the tag is not structurally valid at all
  * (`en_US`, `''`, `not a locale`). Well-formed but unknown to ICU (`zz`) is a locale — `Intl`
@@ -53,11 +63,47 @@ export function canonicalLocale(locale: string): string | undefined {
 export function localeInvalid(locale: string): UltimateError {
   return new UltimateError({
     code: 'X_LOCALE_INVALID',
-    cause: `"${locale}" is not a well-formed BCP 47 language tag`,
+    cause: `${localeExcerpt(locale)} is not a well-formed BCP 47 language tag`,
     fix: "pass a tag like 'en', 'en-GB' or 'de-DE' — screen a header-supplied value with Intl.DateTimeFormat.supportedLocalesOf([tag]) before it reaches a formatter",
+    // The raw tag, under a NAME. A `cause` is copied into the 400 body and into the log line by
+    // `@ultimat3/http`'s `toProblem`, and a logger redacts by key — so a caller's value spliced
+    // into prose has no key left to redact, which is the whole argument `describeValue` rests on.
+    // `meta` is the key, and it is machine-read, so it carries the value WHOLE: an excerpt here
+    // would be a value a redactor or a bug report reads as complete when it is not.
+    meta: { locale },
   });
 }
 
+/**
+ * The tag as a reader can act on it: the first `MAX_LOCALE_EXCERPT` code points, quoted, and SAID
+ * to be cut when there were more.
+ *
+ * `describeValue` is the usual answer for a caller-supplied value in a `cause` and it is the wrong
+ * one here — it renders `en_US` as "a 5-character string", deleting the only actionable content in
+ * a sentence whose entire job is to say WHICH tag was refused. Bounding it keeps the diagnostic and
+ * removes the part a stranger chooses: without a cap the whole of an `Accept-Language` value —
+ * megabytes, at the caller's option — became the error's `message`, its 400 body and its log line.
+ *
+ * Code points, never `slice`: cutting between a surrogate pair leaves a lone surrogate, which is
+ * not text and survives no encoder between here and the log index. The string iterator is lazy, so
+ * a megabyte tag costs 35 steps rather than a megabyte-long array.
+ *
+ * No escaping here: `UltimateError`'s constructor runs `singleLine` over every line-bearing field
+ * exactly once, which is what keeps a newline in a tag from writing a second line an operator reads
+ * as a genuine framework message. A second pass at this call site would be a second place that has
+ * to be right.
+ */
+function localeExcerpt(locale: string): string {
+  let head = '';
+  let taken = 0;
+  for (const char of locale) {
+    if (taken === MAX_LOCALE_EXCERPT) return `"${head}" (truncated at ${taken} characters)`;
+    head += char;
+    taken += 1;
+  }
+  return `"${head}"`;
+}
+
 /**
  * The canonical spelling of a well-formed tag, or `X_LOCALE_INVALID`. The ONE screen a
  * caller-supplied BCP 47 tag passes before it reaches an `Intl` constructor.

package/src/schema-error-codes.ts

@@ -1,32 +1,33 @@
 // Single responsibility: register `@ultimat3/schema`'s error codes so their titles render for any
 // process that imports `@ultimat3/core` — not just the CLI. `@ultimat3/schema` is tier 0 alongside
-// this package, so it cannot call `registerErrorCodes()` itself (that would mean importing core,
-// a same-tier import) and this package cannot import schema to read its declarations back (same
-// reason, the other direction). The codes below are a deliberate, tested duplicate of
-// `SCHEMA_ERROR_CODES` in `packages/schema/src/errors.ts` — `schema-error-codes-pin.test.ts`, in a
-// package that may legally import both (`@ultimat3/cli`), asserts them equal so a title edited in
-// one place and not the other fails the build instead of quietly disagreeing at runtime.
+// this package and cannot call `registerErrorCodes()` itself: that would be `schema -> core`, an
+// import this package's own dependency-free promise forbids in that direction and always will.
+// The other direction is DECLARED (`core -> schema`, `scripts/lib/tiers.ts`), so the titles are
+// READ from schema rather than restated here.
+//
+// They were a hand-kept duplicate until 2026-08-27, held equal by `schema-error-codes-pin.test.ts`
+// in `@ultimat3/cli` — a tier-5 package pinning a tier-0 invariant, which nothing required to
+// exist. It is deleted with this change.
 
+import { SCHEMA_ERROR_CODES } from '@ultimat3/schema';
 import { registerErrorCodes } from './error-codes';
 import { registerErrorRetry } from './error-retry';
 
-/** Mirrors `SCHEMA_ERROR_CODES` in `packages/schema/src/errors.ts`. Keep the titles identical. */
-export const SCHEMA_ERROR_CODE_TITLES: Readonly<Record<string, string>> = Object.freeze({
-  X_VALIDATION_FAILED: 'value did not match its schema',
-  X_SCHEMA_UNSUPPORTED: 'the active schema provider cannot do this',
-  X_SCHEMA_DISCRIMINANT_INVALID: 'a discriminated union member can never be dispatched to',
-  X_SCHEMA_DEFAULT_UNSHAREABLE: 'a schema default cannot be copied per parse',
-});
+/**
+ * Schema's own declarations, projected to titles. Kept as an export because it is public API
+ * shipped since 1.0; it is now DERIVED and can no longer disagree with its source.
+ */
+export const SCHEMA_ERROR_CODE_TITLES: Readonly<Record<string, string>> = Object.freeze(
+  Object.fromEntries(
+    Object.entries(SCHEMA_ERROR_CODES).map(([code, declared]) => [code, declared.title]),
+  ),
+);
 
 // Registered here rather than in `error-codes.ts`'s `CORE_CODE_TITLES` because core does not own
 // these codes — `@ultimat3/schema` does — and `registerErrorCodes` is the one mechanism that
 // raises `X_ERROR_CODE_DUPLICATE` if a package that DOES own one of them ever tries to register it
-// too, which pins ownership even though the titles live in two files.
-registerErrorCodes(
-  Object.fromEntries(
-    Object.entries(SCHEMA_ERROR_CODE_TITLES).map(([code, title]) => [code, { title }]),
-  ),
-);
+// too, which pins ownership even though the registration happens here.
+registerErrorCodes(SCHEMA_ERROR_CODES);
 
 // And how each is RETRIED, here for the same tier reason the titles are here.
 //
@@ -41,9 +42,10 @@ registerErrorCodes(
 // `packages/scraping/src/cdp-target.ts` names the gap and says it cannot be closed from there.
 //
 // A value that does not match its schema does not match it on attempt five either.
-registerErrorRetry({
-  X_VALIDATION_FAILED: 'terminal',
-  X_SCHEMA_UNSUPPORTED: 'terminal',
-  X_SCHEMA_DISCRIMINANT_INVALID: 'terminal',
-  X_SCHEMA_DEFAULT_UNSHAREABLE: 'terminal',
-});
+//
+// DERIVED from the same set, so a code schema adds cannot arrive unclassified: the list was typed
+// out here and a fifth code would have been silently missing from it, which is precisely the
+// "unregistered reads as unclassified" failure the paragraph above describes.
+registerErrorRetry(
+  Object.fromEntries(Object.keys(SCHEMA_ERROR_CODES).map((code) => [code, 'terminal' as const])),
+);

package/src/time-zone-name.ts

@@ -1,43 +1,14 @@
-// Single responsibility: is a string an IANA zone NAME? Tier 0's statement of the one rule
-// `@ultimat3/time` enforces everywhere above it — a zone is `Area/Location`, and `UTC` is the one
-// exception. It is stated twice because `core` is tier 0 and may not import `@ultimat3/time`;
-// `packages/time/src/zone-canonical.ts` is where the rule and its reasoning are written down.
+// Single responsibility: re-export `@ultimat3/schema`'s IANA zone-name predicate, so `app.config.ts`
+// and `t.timezone` judge a zone with ONE function.
+//
+// This file held a character-for-character copy of it until 2026-08-27 — `core` and `schema` are
+// both tier 0 and neither could import the other — kept equal by a 123-line pin test in
+// `@ultimat3/cli`, a tier-5 package pinning a tier-0 invariant that no rule required to exist.
+// `core -> schema` is now a declared edge (`scripts/lib/tiers.ts`), so the copy is gone.
+//
+// The rule itself, and why a bare `new Intl.DateTimeFormat(…)` probe is not it — ICU 78 resolves
+// `CET`, `EST`, `Japan`, `GMT` and `Zulu`, so `defaultTimeZone: 'CET'` passed validation at boot
+// and threw `X_TIMEZONE_INVALID` on the first `format` call (issue #257) — is written down in
+// `packages/schema/src/time-zone-name.ts` and in `packages/time/src/zone-canonical.ts`.
 
-/**
- * A LEADING sign is a fixed offset, which carries no DST rules. `Etc/GMT+2` keeps its `+`.
- *
- * Unobservable on ICU 78 — `+01:00` resolves to itself, so the slash rule below already refuses it,
- * and deleting this line changes no answer this package can currently produce. It stays because it
- * guards the runtime that folds an offset into `Etc/GMT-1`, which WOULD carry a slash, and because
- * `packages/time/src/zone-canonical.ts` carries the same line: two statements of one rule may not
- * differ, least of all in the half that is hard to test.
- */
-const NUMERIC_OFFSET = /^[+-]/;
-
-/**
- * Structural, and never delegated to `Intl` — the reasoning, and why a denylist is not the
- * alternative, is `packages/time/src/zone-canonical.ts`'s and is not re-derived here. What this
- * file enforces is that same rule for `app.config.ts`: an identifier is `Area/Location`, `UTC` is
- * the one legal exception, and a leading sign is an offset rather than a name.
- *
- * It exists because a bare `new Intl.DateTimeFormat(…)` probe was the second answer to that
- * question, and the two stopped agreeing: ICU 78 (Bun 1.4) resolves `CET`, `EST`, `Japan`, `GMT`,
- * `Zulu` and the whole `backward`/abbreviation family, so `defaultTimeZone: 'CET'` passed validation
- * at boot and threw `X_TIMEZONE_INVALID` on the first `format` call — a config file accepting a
- * value nothing downstream can use (issue #257).
- *
- * The judgement is made on the RESOLVED name, not the input, so a casing (`utc`) and a runtime that
- * folds an alias into its target (`Etc/UTC` → `UTC`) both answer correctly. No cache: this is read
- * once per process at config validation, never off a request header — a zone that arrives from a
- * caller goes through `@ultimat3/time`'s `canonicalTimeZone`, which is bounded and canonicalizing.
- */
-export function isIanaZoneName(value: string): boolean {
-  if (value === '' || NUMERIC_OFFSET.test(value)) return false;
-  try {
-    const resolved = new Intl.DateTimeFormat('en-US', { timeZone: value }).resolvedOptions()
-      .timeZone;
-    return resolved === 'UTC' || resolved.includes('/');
-  } catch {
-    return false;
-  }
-}
+export { isIanaZoneName } from '@ultimat3/schema';