@ultimat3/core 23.0.0 → 25.0.0

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

package/src/config-navigation.ts

@@ -6,7 +6,6 @@
 // were: shape, merge and screen are one subject.
 
 import { describeValue } from './error-render';
-import { ConfigInvalidError } from './errors';
 
 /**
  * The surfaces that render documents a browser navigates between. `api` answers JSON and `shared`
@@ -73,7 +72,7 @@ export interface NavigationSectionInput {
 }
 
 /**
- * Whole-value keys: the last layer that listed surfaces wins, as `locales` does — and so does the
+ * Whole-value keys: the last layer that listed surfaces wins, as `roles` does — and so does the
  * last one that set `speculation.prefetch` or listed `speculation.exclude`, each on its own.
  */
 export function mergeNavigation(layers: readonly NavigationSectionInput[]): NavigationSection {
@@ -138,29 +137,6 @@ function speculationIssues(speculation: unknown, issues: string[]): void {
   }
 }
 
-/**
- * `navigation.speculation` as some reader OUTSIDE `defineConfig` found it (`@ultimat3/cli` imports
- * the app's config module structurally): the defaults for what it does not say, and the SAME
- * refusal `defineConfig` gives for what it says wrongly. One validator — a second reader that
- * coerced `'eager'` to `'moderate'` or dropped a bad pattern would serve rules the app never wrote.
- */
-export function resolveSpeculation(said: unknown): SpeculationConfig {
-  if (said === undefined) return DEFAULT_SPECULATION;
-  const { speculation } = mergeNavigation([
-    { navigation: { speculation: said as SpeculationInput } },
-  ]).navigation;
-  const issues: string[] = [];
-  speculationIssues(speculation, issues);
-  if (issues.length > 0) {
-    throw new ConfigInvalidError({
-      cause: issues.join('; '),
-      fix: 'Correct navigation.speculation in app.config.ts: prefetch is "moderate", "conservative" or false, and exclude is a list of path patterns starting with "/"',
-      meta: { issues },
-    });
-  }
-  return speculation;
-}
-
 /** Appends every refusal the section earns to `issues`, `config.ts`' one list. */
 export function navigationIssues(config: NavigationSection, issues: string[]): void {
   speculationIssues(config.navigation.speculation, issues);

package/src/config-pwa.ts

@@ -13,7 +13,7 @@
 import { describeValue } from './error-render';
 
 /**
- * `installPrompt` was removed 2026-08, same rule: `@ultimat3/pwa`'s `createInstallController` is
+ * `installPrompt` was removed 2026-08, same rule: `@ultimat3/pwa`'s `installController` 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.
  */
@@ -115,8 +115,8 @@ export interface PwaScreenshot {
 /**
  * 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
+ * THE ONE PLACE IN `app.config.ts` A RAW COLOUR IS LEGAL (`theme.tokens`, the other, was deleted in
+ * 25.0.0 — the theme is `defineTheme` in `@ultimat3/ui`), because 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.
  */
@@ -173,10 +173,20 @@ export function pwaIssues(pwa: PwaConfig, issues: string[]): boolean {
   // `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).
+  // Same origin, too: `//host/offline` and `/\host/offline` start with `/` and are still another
+  // host, which the worker would precache and serve as this app's offline page.
   const fallback: unknown = pwa.offline?.fallback;
-  if (typeof fallback !== 'string' || !fallback.startsWith('/')) {
+  if (!isSameOriginPath(fallback)) {
     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)}`,
+      `pwa.offline.fallback is required when pwa.enabled is true and must be an absolute route path on this origin like "/offline", and is ${describeValue(fallback)}`,
+    );
+  }
+  for (const key of ['image', 'font'] as const) {
+    const placeholder: unknown = pwa.offline?.[key];
+    if (placeholder === undefined || placeholder === null || isSameOriginPath(placeholder))
+      continue;
+    issues.push(
+      `pwa.offline.${key} must be a path on this origin like "/offline.svg", and is ${describeValue(placeholder)}`,
     );
   }
   const personal: unknown = pwa.offline?.personalPages;
@@ -233,3 +243,30 @@ function manifestIssues(pwa: PwaConfig, issues: string[]): void {
     }
   }
 }
+
+/** An origin no relative path can reach: a value that resolves anywhere else left this origin. */
+const PROBE_ORIGIN = 'http://x.invalid';
+
+/**
+ * A path on THIS origin, as a browser will resolve it — the one predicate for every URL the worker
+ * precaches and serves as an offline answer (`@ultimat3/pwa`'s build asks the same question).
+ * Judged by RESOLUTION, never by the raw prefix: the URL parser strips a tab, CR or LF anywhere and
+ * reads `\` as `/`, so `/\t/evil.test/x` is `//evil.test/x` once parsed. Every C0 control and DEL
+ * is refused before the parse, as `@ultimat3/http`'s sign-in redirect does; a dot segment that
+ * leaves a `//` pathname (`/.//evil.test`) is refused after it, since any reader without the base
+ * takes that pathname as a host.
+ */
+export function isSameOriginPath(value: unknown): value is string {
+  if (typeof value !== 'string' || !value.startsWith('/')) return false;
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code < 0x20 || code === 0x7f) return false;
+  }
+  let resolved: URL;
+  try {
+    resolved = new URL(value, PROBE_ORIGIN);
+  } catch {
+    return false;
+  }
+  return resolved.origin === PROBE_ORIGIN && !resolved.pathname.startsWith('//');
+}

package/src/config-removed.ts

@@ -0,0 +1,131 @@
+// Single responsibility: the `app.config.ts` keys a major DELETED, and the refusal an app still
+// writing one gets. A deleted key the validator ignores is a switch with no wire — an operator sets
+// it, redeploys and nothing changes — so each is refused by name, with the line that replaces it.
+
+import { isJsonObject } from './json-object';
+
+export interface RemovedConfigKey {
+  /** The major that deleted it. */
+  readonly removedIn: string;
+  /** What an app writes instead — the second half of the `fix:`. */
+  readonly instead: string;
+}
+
+/**
+ * Dotted paths, one row per deleted leaf. Every row older than 25.0.0 was silently carried through
+ * `section()` until 25.0.0 refused it — this table by name, then `config-keys.ts` closing the
+ * shape for any other key; a row is what turns "not a key" into the line that replaces it. A row
+ * is never removed: a config written against an older major must keep getting the instruction,
+ * not silence. `Object.freeze`d, read through `Object.hasOwn`, so `__proto__` in a layer names no
+ * row.
+ */
+export const REMOVED_CONFIG_KEYS: Readonly<Record<string, RemovedConfigKey>> = Object.freeze({
+  locales: {
+    removedIn: '25.0.0',
+    instead:
+      "the app's locales are the keys of its catalogs: defineCatalogs({ default: 'en', locales: { en, es } }) from @ultimat3/i18n, in packages/i18n/src/index.ts",
+  },
+  defaultLocale: {
+    removedIn: '25.0.0',
+    instead:
+      "the fallback locale is defineCatalogs({ default: 'en', locales: { en } })'s default, from @ultimat3/i18n",
+  },
+  defaultTimeZone: {
+    removedIn: '25.0.0',
+    instead:
+      "nothing read it; there is no ambient zone — pass one at every call: formatDate(at, { locale, zone: 'Europe/Paris' }), task({ tz }), userActor({ tz })",
+  },
+  defaultCurrency: {
+    removedIn: '25.0.0',
+    instead:
+      "nothing read it; every Money carries its own currency ({ minor, currency: 'USD' }) — an app that wants a default declares its own constant in an app module",
+  },
+  'jobs.driver': {
+    removedIn: '5.0.0',
+    instead:
+      'nothing read it and boot always built Postgres; the driver is code — setJobDriver(postgresJobDriver({ executor })) from @ultimat3/jobs, or setJobDriver(memoryJobDriver()) in a test',
+  },
+  'realtime.heartbeatMs': {
+    removedIn: '4.0.0',
+    instead:
+      "nothing read it; the page socket's beat is the sync node's, named in its hello reply, and the presence beat is a third of the presence ttl",
+  },
+  'database.urlEnv': {
+    removedIn: '4.0.0',
+    instead:
+      'nothing read it; the connection string is the DATABASE_URL environment variable, read by @ultimat3/db',
+  },
+  'database.poolSize': {
+    removedIn: '4.0.0',
+    instead:
+      'nothing read it; the pool is sized by the DATABASE_POOL_MAX environment variable, per process',
+  },
+  'database.schema': {
+    removedIn: '4.0.0',
+    instead:
+      'nothing read it and nothing emits SET search_path; entity() tables live in public, and there is no replacement',
+  },
+  'pwa.installPrompt': {
+    removedIn: '8.0.0',
+    instead:
+      'nothing read it; call installController() from @ultimat3/pwa in your own install affordance',
+  },
+  'auth.afterSignInPath': {
+    removedIn: '8.0.0',
+    instead:
+      'nothing read it; send the visitor where you mean from your sign-in route, the only code that can honour it',
+  },
+  'ai.modelEnv': {
+    removedIn: '8.0.0',
+    instead:
+      "nothing read it; the model is the prompt's own, or llm({ model }) from @ultimat3/ai — read your own env key and pass it there",
+  },
+  'cache.driver': {
+    removedIn: '9.0.0',
+    instead:
+      "cache.tiers is the one selector — name the rung: cache: { tiers: ['request-memo', 'lru', 'redis'] }",
+  },
+  'cache.urlEnv': {
+    removedIn: '9.0.0',
+    instead:
+      "nothing read it; the redis tier reads the REDIS_URL environment variable, so name 'redis' in cache.tiers and set REDIS_URL",
+  },
+  'realtime.tier': {
+    removedIn: '10.0.0',
+    instead:
+      "nothing read it; an app's realtime tier is what it declares — a channel() topic, a live: true query, persist: true on an entity",
+  },
+  'theme.tokens': {
+    removedIn: '25.0.0',
+    instead:
+      "nothing read it; the app's theme is declared once with export const brand = defineTheme({ … }) from @ultimat3/ui, in apps/web/shared/theme.ts",
+  },
+  'ai.mcp.path': {
+    removedIn: '25.0.0',
+    instead:
+      "an MCP endpoint's path is its own: defineAppMcp({ path: '/mcp' }) from @ultimat3/mcp, in apps/<app>/mcp.ts — the default is /mcp, and every endpoint mounts where its own metadata says",
+  },
+});
+
+const said = (layer: unknown, path: string): boolean => {
+  let at: unknown = layer;
+  for (const segment of path.split('.')) {
+    if (!isJsonObject(at) || !Object.hasOwn(at, segment)) return false;
+    at = at[segment];
+  }
+  // `undefined` is a layer not saying, the rule every other key follows.
+  return at !== undefined;
+};
+
+/** The removed keys one layer still writes, in table order. */
+export function removedKeysIn(layer: unknown): readonly string[] {
+  return Object.keys(REMOVED_CONFIG_KEYS).filter((path) => said(layer, path));
+}
+
+/** One cause line per removed key, naming the major. */
+export const removedKeyIssue = (path: string): string =>
+  `${path} was removed in ${REMOVED_CONFIG_KEYS[path]?.removedIn ?? 'a major'} and is no longer read`;
+
+/** One instruction per removed key: delete the line, and what replaces it. */
+export const removedKeyFix = (path: string): string =>
+  `delete ${path} from app.config.ts — ${REMOVED_CONFIG_KEYS[path]?.instead ?? ''}`;

package/src/config-shape.ts

@@ -0,0 +1,79 @@
+// 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`);
+    }
+  }
+}

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)) {