@ultimat3/cli 23.0.0 → 25.0.0

package/src/doctor-auth.ts

@@ -0,0 +1,95 @@
+// `x doctor`'s auth-storage checks: what an upgrade leaves in the database for an operator to
+// finish — second-factor secrets written before they were sealed, and a framework table no
+// release reads any more. Reaching the server is `authStorageProbe`, deciding is
+// `authStorageFindings` — the split `doctor-sealed.ts` makes.
+
+import { countUnsealedMfaSecrets, postgresAuthAdapter } from '@ultimat3/auth';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import { postgresClient, raw } from '@ultimat3/db';
+import type { Finding } from './output';
+
+/**
+ * Framework tables an earlier release created and none reads now, each with the command that
+ * removes it. The boot never drops one: a replica still on the previous release may be using it
+ * for the length of a rolling deploy. A whole literal per table — nothing is spliced into a fix.
+ */
+type RetiredTable = 'x_auth_failures';
+
+// A Map, not an object: a table name is looked up by key, and an object answers `constructor`.
+const RETIRED_TABLE_FIXES: ReadonlyMap<RetiredTable, string> = new Map([
+  [
+    'x_auth_failures',
+    `psql "$DATABASE_URL" -c 'drop table if exists x_auth_failures'   # once every replica runs this release`,
+  ],
+]);
+
+export const RETIRED_FRAMEWORK_TABLES: readonly RetiredTable[] = Object.freeze([
+  ...RETIRED_TABLE_FIXES.keys(),
+]);
+
+export interface AuthStorageFact {
+  /** `x_users` rows holding an `mfa_secret` that is not sealed. */
+  readonly unsealedMfaSecrets: number;
+  /** Which of `RETIRED_FRAMEWORK_TABLES` are still present. */
+  readonly retiredTables: readonly RetiredTable[];
+}
+
+/** What a database that was not asked — embedded, or unreachable — answers: nothing to report. */
+export const NO_AUTH_STORAGE_FACT: AuthStorageFact = Object.freeze({
+  unsealedMfaSecrets: 0,
+  retiredTables: Object.freeze([]),
+});
+
+/** The rule, pure. */
+export function authStorageFindings(fact: AuthStorageFact): readonly Finding[] {
+  const findings: Finding[] = [];
+  if (fact.unsealedMfaSecrets > 0) {
+    findings.push({
+      code: 'X_MFA_SECRET_UNSEALED',
+      cause: `${fact.unsealedMfaSecrets} user(s) hold a second-factor secret that is not sealed; the framework never reads a plaintext secret, so each of them is refused at the second factor until it is sealed`,
+      fix: 'x auth seal-mfa --json',
+      docs: ERROR_DOCS_URL,
+    });
+  }
+  for (const table of fact.retiredTables) {
+    const fix = RETIRED_TABLE_FIXES.get(table);
+    if (fix === undefined) continue;
+    findings.push({
+      code: 'X_FRAMEWORK_TABLE_ORPHANED',
+      cause: `${table} is still in the database and no release reads it any more; the boot does not drop it, because a replica on the previous release may still be writing to it during a rolling deploy`,
+      fix,
+      docs: ERROR_DOCS_URL,
+    });
+  }
+  return findings;
+}
+
+/**
+ * Asks an EXTERNAL database only — `probeDatabase`'s own rule: opening the embedded one boots
+ * PGlite and takes the single-writer lock the next command needs. A server that does not answer
+ * is `database()`'s finding to make, so every failure here is "nothing to report".
+ */
+export async function authStorageProbe(url: string | undefined): Promise<AuthStorageFact> {
+  if (url === undefined || url.trim() === '') return NO_AUTH_STORAGE_FACT;
+  const client = postgresClient({ url, applicationName: 'x-doctor' });
+  try {
+    const present = async (table: string): Promise<boolean> => {
+      const rows = await client.query<{ readonly present: boolean }>(
+        raw(`select to_regclass('public.${table}') is not null as present`),
+      );
+      return rows[0]?.present === true;
+    };
+    const retiredTables: RetiredTable[] = [];
+    for (const table of RETIRED_FRAMEWORK_TABLES) {
+      if (await present(table)) retiredTables.push(table);
+    }
+    const unsealedMfaSecrets = (await present('x_users'))
+      ? await countUnsealedMfaSecrets({ adapter: postgresAuthAdapter(client) })
+      : 0;
+    return { unsealedMfaSecrets, retiredTables };
+  } catch {
+    return NO_AUTH_STORAGE_FACT;
+  } finally {
+    await client.close();
+  }
+}

package/src/doctor-offline.ts

@@ -4,11 +4,12 @@
 // diagnostic over.
 
 import { ERROR_DOCS_URL } from '@ultimat3/core';
-import { describeRoutes } from '@ultimat3/render';
+import { describePages } from '@ultimat3/render';
 import { loadApp } from './app-load';
 import { APP_CONFIG_FILE } from './app-root';
 import type { Finding } from './output';
 import { loadPwaArtifacts } from './pwa-artifacts';
+import { quoteArg } from './shell-quote';
 
 /** A route as this check reads one: the URL it answers, and the surface that answers it. */
 export interface NavigableRoute {
@@ -46,7 +47,7 @@ export interface OfflineFallbackFact {
  * below already refuses `--surface app`, so the check and the remedy disagreed about one code.
  *
  * Residual, and NOT closed by this: a `site/` route declaring `render: 'ssr'` is not prerendered
- * either. `NavigableRoute` carries no render mode, and `describeRoutes()` has one — the narrower
+ * either. `NavigableRoute` carries no render mode, and `describePages()` has one — the narrower
  * check belongs with it.
  */
 const NAVIGABLE: ReadonlySet<string> = new Set(['site']);
@@ -100,13 +101,13 @@ export function offlineFallbackFinding(fact: OfflineFallbackFact): Finding | und
   const name = GENERATABLE.exec(fallback)?.[1];
   return name === undefined
     ? finding(cause, `set pwa.offline.fallback in ${APP_CONFIG_FILE} to a path a route serves`)
-    : finding(cause, `x g route ${name} --surface site`);
+    : finding(cause, `x g route ${quoteArg(name)} --surface site`);
 }
 
 /**
  * The fact, read off a real app root. Both halves come from the framework's own answers — the
  * config through `loadPwaArtifacts` (the one reader of that file) and the routes through
- * `describeRoutes()` (the projection `x.manifest.json`, `/_x`, the sitemap and `sw.js` are all
+ * `describePages()` (the projection `x.manifest.json`, `/_x`, the sitemap and `sw.js` are all
  * built from), so this check and the service worker cannot disagree about which routes exist.
  */
 export async function offlineFallbackProbe(root: string): Promise<OfflineFallbackFact> {
@@ -117,6 +118,6 @@ export async function offlineFallbackProbe(root: string): Promise<OfflineFallbac
     routes:
       app.findings.length > 0
         ? undefined
-        : describeRoutes().map((route) => ({ path: route.path, surface: route.surface })),
+        : describePages().map((route) => ({ path: route.path, surface: route.surface })),
   };
 }

package/src/document-options.ts

@@ -32,6 +32,13 @@ export interface DocumentOptions {
    * decided by `app.config.ts`, which the boot read and the renderer cannot.
    */
   readonly themeHead?: string;
+  /**
+   * The app's brand `<style>` from `theme-brand.ts`, or absent for an app with no
+   * `apps/web/shared/theme.ts`. Rendered AFTER the surface stylesheet `<link>`, never in the head
+   * block `themeHead` rides: the brand answers `theme.scss` at equal specificity, so only a later
+   * position in the cascade lets it win.
+   */
+  readonly brandHead?: string;
   /**
    * The page's sync target — `pageSync(…).head` — rendered as render's `clientSyncTags` on every
    * document this process serves. Principal-free, so a shareable document carries it too; absent

package/src/drift-replica-identity.ts

@@ -0,0 +1,42 @@
+// Single responsibility: which declared tables the drift step expects a migration to have made
+// `REPLICA IDENTITY FULL` — the same set `x db gen` emits the ALTER for (`replicaIdentityTables`),
+// or that command's own refusal as a finding. A tier-3 fact no entity carries, so no source hash
+// moves when a channel with params is added over a table that already exists.
+
+import { describeQueries } from '@ultimat3/query';
+import { QuerySubscribesUnknownError, replicaIdentityTables } from './db-subscribes';
+import { MIGRATIONS_DIR } from './migrations';
+import type { Finding } from './output';
+import { findingFrom } from './output';
+
+/** The tables needing FULL, given the tables the app's entities declare. Injected for tests. */
+export type ReplicaIdentityWanted = (tables: ReadonlySet<string>) => readonly string[];
+
+/**
+ * The app's own answer: every params channel's `records` tables, with its live queries'
+ * `subscribes:` validated but never granted (#518), read off the registries `loadApp` filled. One function with `db-generate.ts`, so the gate
+ * can never expect an identity the generator would not grant, or miss one it would.
+ */
+export const appReplicaIdentity: ReplicaIdentityWanted = (tables) =>
+  replicaIdentityTables(describeQueries(), tables);
+
+export type WantedIdentity =
+  | { readonly tables: ReadonlySet<string> }
+  | { readonly finding: Finding };
+
+/**
+ * `x db gen` refuses a `subscribes:` name no entity declares (`X_QUERY_SUBSCRIBES_UNKNOWN`), and the
+ * gate reports the same refusal rather than letting it escape the step: every other throw is a
+ * defect in this process and is rethrown as one.
+ */
+export function wantedReplicaIdentity(
+  wanted: ReplicaIdentityWanted,
+  tables: ReadonlySet<string>,
+): WantedIdentity {
+  try {
+    return { tables: new Set(wanted(tables)) };
+  } catch (error) {
+    if (!(error instanceof QuerySubscribesUnknownError)) throw error;
+    return { finding: { ...findingFrom(error), at: MIGRATIONS_DIR } };
+  }
+}

package/src/drift.ts

@@ -53,16 +53,39 @@ async function declaredSchemaJson(root: string): Promise<string> {
  */
 export async function schemaHash(root: string): Promise<string> {
   const glob = new Bun.Glob(SCHEMA_GLOB);
-  const paths: string[] = [];
+  const sources: SchemaSource[] = [];
   for await (const path of glob.scan({ cwd: root, absolute: false })) {
-    if (!path.includes('.test.')) paths.push(path);
+    if (path.includes('.test.')) continue;
+    sources.push({ path, text: await Bun.file(join(root, path)).text() });
   }
-  paths.sort();
+  return hashSchemaSources(await declaredSchemaJson(root), sources);
+}
+
+/** One file under `SCHEMA_GLOB`: its path relative to the app root, as the OS spelled it. */
+export interface SchemaSource {
+  readonly path: string;
+  readonly text: string;
+}
+
+/**
+ * The hash itself, pure. The sidecar is committed and compared on every OS, so what a checkout
+ * spells differently is folded away first: `\` separators (a Windows glob) become `/` BEFORE the
+ * sort — `seed2.ts` and `seed/index.ts` order differently under the two — and CRLF text (Git for
+ * Windows' `core.autocrlf=true`) becomes LF. An LF tree on POSIX is hashed exactly as before, so no
+ * sidecar already recorded moves.
+ */
+export function hashSchemaSources(schemaJson: string, sources: readonly SchemaSource[]): string {
+  const files = sources
+    .map(({ path, text }) => ({
+      path: path.replaceAll('\\', '/'),
+      text: text.replaceAll('\r\n', '\n'),
+    }))
+    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
   const hasher = new Bun.CryptoHasher('sha256');
-  hasher.update(await declaredSchemaJson(root));
-  for (const path of paths) {
+  hasher.update(schemaJson);
+  for (const { path, text } of files) {
     hasher.update(path);
-    hasher.update(await Bun.file(join(root, path)).text());
+    hasher.update(text);
   }
   return hasher.digest('hex').slice(0, 16);
 }

package/src/error-catalog.ts

@@ -46,21 +46,18 @@ export const CATALOG_PACKAGES = [
 ] as const;
 
 /**
- * The packages the catalog may import WITHOUT `@ultimat3/cli` declaring them. `admin` and `ui`
- * reach for a JSX runtime an app has and a bare CLI process does not, so a hard dependency would
- * make the CLI uninstallable where the codes are merely absent today. `scraping` is an app's own
- * choice since 22.0.0: `x shot` drives Chrome over raw CDP and imports nothing from it, so its codes
+ * The packages the catalog may import WITHOUT `@ultimat3/cli` declaring them — never one it does
+ * declare (`error-catalog.test.ts`), which is why `admin` is not here: `x dev` imports it and
+ * `package.json` depends on it. `ui` reaches the CLI only as `admin`'s own dependency, so an
+ * installer that keeps transitive packages private reports its codes `unavailable` rather than
+ * the CLI declaring a package no command imports. `scraping` is an app's own choice since 22.0.0: `x shot` drives Chrome over raw CDP and imports nothing from it, so its codes
  * answer where the app installed it and are reported `unavailable` where it did not. Every other
  * entry above is a real runtime import and must be a declared dependency — `error-catalog.test.ts`
  * holds the list to exactly that, because an undeclared one resolves through workspace symlinks
  * here and through nothing in an installed app, where `x errors explain X_FLAG_EXPIRED` then
  * refuses a code the wiki promises.
  */
-export const CATALOG_OPTIONAL_HOSTS: readonly string[] = [
-  '@ultimat3/admin',
-  '@ultimat3/scraping',
-  '@ultimat3/ui',
-];
+export const CATALOG_OPTIONAL_HOSTS: readonly string[] = ['@ultimat3/scraping', '@ultimat3/ui'];
 
 export interface ErrorCatalog {
   /** Packages whose codes are now registered. */

package/src/error-codes.ts

@@ -220,11 +220,22 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_ADMIN_RESOURCE_UNWIRED',
   'X_IMAGE_NOT_PREBUILT',
   'X_ADMIN_UNSCANNED',
+  'X_FRAMEWORK_TABLE_ORPHANED',
+  'X_BUILD_OUT_UNSAFE',
+  'X_FRAMEWORK_SCHEMA_UNAPPLIED',
+  'X_APP_URL_PORT_MISMATCH',
+  'X_DEV_HOST_REFUSED',
+  'X_TRUSTED_PROXY_HOPS_INVALID',
+  'X_PERMISSION_BORROWED',
+  'X_ERROR_CODE_UNTHROWN_STALE',
+  'X_DEV_STATE_UNWRITABLE',
+  'X_PACKAGE_TEST_ONLY_SHIPPED',
+  'X_ISLAND_MODULE_DUPLICATED',
 ] as const;
 
 /**
- * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s — `CliNotImplementedError` and every planned command
- * throw it, and none of them may declare a title for it. The CLI is the process that imports every
+ * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s — every planned command throws it through core's
+ * own `NotImplementedError`, and none of them may declare a title for it. The CLI is the process that imports every
  * package (`error-catalog.ts`), so a title declared twice here is the one that would win by load
  * order rather than by ownership.
  *
@@ -285,7 +296,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_ERROR_CODE_UNREGISTERED: 'the error reference documents a code no package registers',
   X_ERROR_CODE_UNRESOLVED: 'an error code is written as a name this repository cannot resolve',
   X_ERROR_CODE_UNTHROWN:
-    'a registered error code is constructed by nothing and its reference row does not say so',
+    'a registered error code is constructed by nothing and UNTHROWN_CODES in packages/cli/src/unthrown-codes.ts does not list it',
   X_FRAMEWORK_SCHEMA_FAILED: 'a framework table could not be created at boot',
   X_STORAGE_UNWRITABLE: 'the storage disk this process needs cannot be written to',
   X_STORAGE_SECRET_DEV: 'upload grants would be signed with the shipped development key',
@@ -392,6 +403,21 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
     'a container role built at boot what the image build should have: island chunks or stylesheets',
   X_ADMIN_UNSCANNED:
     'a defineAdmin() declaration sits outside the app scan, so the admin is never mounted',
+  X_FRAMEWORK_TABLE_ORPHANED:
+    'a framework table no release reads any more is still in the database',
+  X_BUILD_OUT_UNSAFE: 'the static export directory is not one a build may empty',
+  X_FRAMEWORK_SCHEMA_UNAPPLIED:
+    'a serving role booted over a database whose framework schema this build never applied',
+  X_APP_URL_PORT_MISMATCH: 'APP_URL names a loopback port x dev does not serve',
+  X_DEV_HOST_REFUSED: 'a /_x request named a host that is not this machine',
+  X_TRUSTED_PROXY_HOPS_INVALID:
+    'TRUSTED_PROXY_HOPS is not a whole number of proxies the boot accepts',
+  X_PERMISSION_BORROWED: 'an app rule requires a permission only an imported package declared',
+  X_ERROR_CODE_UNTHROWN_STALE:
+    'a code UNTHROWN_CODES lists as thrown by nothing is thrown again — delete it from UNTHROWN_CODES in packages/cli/src/unthrown-codes.ts',
+  X_DEV_STATE_UNWRITABLE: 'x dev cannot claim its state directory',
+  X_PACKAGE_TEST_ONLY_SHIPPED: 'a test-only module ships in the tarball',
+  X_ISLAND_MODULE_DUPLICATED: 'An island chunk bundles one module more than once',
 };
 
 // One unconditional call, so a second package claiming one of the CLI's codes throws

package/src/error-page-csp.ts

@@ -1,15 +1,11 @@
-// The `style-src` sources that admit an app's own error pages. `error-pages.ts` serves
-// `apps/web/site/errors/<status>.html` verbatim, and such a page is a self-contained document —
-// it carries its own `<style>`, because the app's stylesheet bundle is not linked from it. Under
-// the enforced policy a container sends, `style-src 'self' <overlay hash>` blocked that block and
-// the page rendered unstyled; `x dev` sends the policy report-only, so the same page looked fine
-// on every author's machine. Hashed at boot, like the hydration runtime: a hash is a function of
-// the body, and these files do not change while a container runs.
+// The inline `<style>` bodies of an app's own error pages, for `style-src` to admit. Such a page
+// (`apps/web/site/errors/<status>.html`, served verbatim by `error-pages.ts`) carries its own
+// `<style>` — no stylesheet bundle is linked from it — and under the container's enforced policy an
+// unadmitted block is a page rendered unstyled; `x dev` is report-only, so it looked fine there.
 
 // why: Bun exposes no path-join primitive, and the directory is app-root-relative — the same
 // necessity `error-pages.ts` records.
 import { join } from 'node:path';
-import { cspHashSource } from '@ultimat3/http';
 import { ERROR_PAGE_DIR } from './error-pages';
 
 /**
@@ -26,18 +22,21 @@ export function inlineStyleBodies(html: string): readonly string[] {
 }
 
 /**
- * One hash per distinct `<style>` body across every error page the app ships. Read once at boot:
- * a page an author drops in while `x dev` runs is served (the reader is per request) but not yet
- * admitted, which the report-only policy there turns into a console report, not a blank page.
+ * Every distinct `<style>` body across every error page the app ships, sorted — BODIES, because
+ * `startRoles({ inlineStyles })` hashes what it is given (`style-csp.ts`). This returned the hashes
+ * until 2026-10, and the boot hashed them again: the policy admitted the hash of a hash, and every
+ * app error page carrying a `<style>` rendered unstyled under the container's enforced CSP. Read
+ * once at boot: a page an author drops in while `x dev` runs is served (the reader is per request)
+ * but not yet admitted, which the report-only policy there turns into a console report.
  */
-export async function errorPageStyleSources(root: string): Promise<readonly string[]> {
+export async function errorPageStyleBodies(root: string): Promise<readonly string[]> {
   const dir = join(root, ERROR_PAGE_DIR);
-  const sources = new Set<string>();
+  const bodies = new Set<string>();
   for (const name of await htmlFilesIn(dir)) {
     const html = await Bun.file(join(dir, name)).text();
-    for (const body of inlineStyleBodies(html)) sources.add(cspHashSource(body));
+    for (const body of inlineStyleBodies(html)) bodies.add(body);
   }
-  return [...sources].sort();
+  return [...bodies].sort();
 }
 
 /** `Bun.Glob.scan` throws `ENOENT` on a missing directory, and no error pages is the common case. */

package/src/error-unthrown.ts

@@ -1,7 +1,8 @@
 // A registered code nothing constructs. The registry and the reference keep a shipped code alive
 // forever — which is right — and that is exactly why a code can outlive its last thrower with no
 // gate noticing: `X_RPC_FAILED` sat registered and documented as live after the transport change
-// took its only throw site away. The reference row has to SAY so, or this reports it.
+// took its only throw site away. It has to be LISTED as unthrown (`UNTHROWN_CODES`), or this
+// reports it.
 
 import { join } from 'node:path';
 import { ERROR_DOCS_URL, maskLiterals, stripComments } from '@ultimat3/core';
@@ -9,6 +10,7 @@ import { RESERVED_HEADING } from './error-contract';
 import type { Finding } from './output';
 import { eachSourceFile, isGenerated, isTest } from './source-files';
 import { isCodeRegistry } from './ts-scan';
+import { UNTHROWN_CODES, UNTHROWN_CODES_FILE } from './unthrown-codes';
 
 const CODE_LITERAL = /(['"`])(X_[A-Z0-9_]+)\1/g;
 const TITLE_KEY = /^[\t ]*(X_[A-Z0-9_]+)\s*:/gm;
@@ -18,9 +20,6 @@ const LIST_LINE = /^[\t ]*(['"`])X_[A-Z0-9_]+\1\s*,?\s*$/;
 const TABLE_ENTRY = /\b([a-z][A-Za-z0-9]*)\s*:\s*(['"`])(X_[A-Z0-9_]+)\2/g;
 const MEMBER_READ = /\.([A-Za-z_$][\w$]*)/g;
 
-/** Phrases a reference row uses to say, in words, that nothing throws the code any more. */
-const DECLARED_UNTHROWN = /thrown by nothing|not thrown/i;
-
 export interface CodeUse {
   /** Every code a package registry names. */
   readonly registered: ReadonlySet<string>;
@@ -78,6 +77,8 @@ export async function collectCodeUse(root: string): Promise<CodeUse> {
   const members = new Set<string>();
   for await (const source of eachSourceFile(root)) {
     if (!/^packages\/[^/]+\/src\//.test(source) || isTest(source) || isGenerated(source)) continue;
+    // The list names every code it waives, and naming one is not throwing it.
+    if (source === UNTHROWN_CODES_FILE) continue;
     const use = codeUseOf(await Bun.file(join(root, source)).text());
     for (const code of use.registered) registered.add(code);
     for (const code of use.used) used.add(code);
@@ -88,28 +89,36 @@ export async function collectCodeUse(root: string): Promise<CodeUse> {
   return { registered, used };
 }
 
-/** Codes whose reference row says nothing throws them, or that sit under the reserved heading. */
+/** Codes that sit under the reserved heading — declared unthrown by WHERE they are, not by words. */
 export function declaredUnthrown(markdown: string): ReadonlySet<string> {
   const out = new Set<string>();
   let reserved = false;
   for (const line of markdown.split('\n')) {
     if (line.trim() === RESERVED_HEADING) reserved = true;
     const row = /^\|\s*`(X_[A-Z0-9_]+)`\s*\|/.exec(line);
-    if (row !== null && (reserved || DECLARED_UNTHROWN.test(line))) out.add(row[1] ?? '');
+    if (row !== null && reserved) out.add(row[1] ?? '');
   }
   return out;
 }
 
 const unthrownFinding = (code: string, page: string): Finding => ({
   code: 'X_ERROR_CODE_UNTHROWN',
-  cause: `${code} is registered and ${page} presents it as live, but no shipped source constructs it — a reader matching on it waits for an error that cannot arrive`,
+  cause: `${code} is registered and ${page} presents it as live, but no shipped source constructs it — a reader matching on it waits for an error that cannot arrive. Add it to UNTHROWN_CODES in ${UNTHROWN_CODES_FILE} and say so in its row, or throw it again where it belongs`,
   // Never "delete the registration": a shipped code is stable forever, and an old log line must
   // still explain. The row is what has to change.
-  fix: `write "registered, thrown by nothing since <version>" into ${code}'s row in ${page}, naming the code that replaced it — or throw it again where it belongs`,
+  fix: 'x errors explain X_ERROR_CODE_UNTHROWN --json',
   docs: ERROR_DOCS_URL,
   at: page,
 });
 
+const staleFinding = (code: string): Finding => ({
+  code: 'X_ERROR_CODE_UNTHROWN_STALE',
+  cause: `${code} is listed in UNTHROWN_CODES and shipped source constructs it again — the listing would excuse a code that is live, so delete it from UNTHROWN_CODES in ${UNTHROWN_CODES_FILE}`,
+  fix: 'x errors explain X_ERROR_CODE_UNTHROWN_STALE --json',
+  docs: ERROR_DOCS_URL,
+  at: UNTHROWN_CODES_FILE,
+});
+
 /**
  * Registered, used by nothing, and not declared unthrown on the reference. A host check — the page
  * is the host repo's to name, and only a monorepo's walk sees every package's source; in a
@@ -118,13 +127,22 @@ const unthrownFinding = (code: string, page: string): Finding => ({
 export async function checkErrorCodesThrown(
   root: string,
   page: string,
+  listed: ReadonlySet<string> = UNTHROWN_CODES,
 ): Promise<readonly Finding[]> {
   const reference = Bun.file(join(root, page));
   if (!(await reference.exists())) return [];
-  const exempt = declaredUnthrown(await reference.text());
+  const reserved = declaredUnthrown(await reference.text());
   const { registered, used } = await collectCodeUse(root);
-  return [...registered]
-    .filter((code) => !used.has(code) && !exempt.has(code))
+  const unthrown = [...registered]
+    .filter((code) => !used.has(code) && !listed.has(code) && !reserved.has(code))
     .sort()
     .map((code) => unthrownFinding(code, page));
+  // Only the THROWN-again direction: a listed name no registry holds waives nothing (the code it
+  // was meant to name is still reported), and a host repo's fixture registering none of this
+  // repo's codes would otherwise read every listing as stale.
+  const stale = [...listed]
+    .filter((code) => used.has(code))
+    .sort()
+    .map((code) => staleFinding(code));
+  return [...unthrown, ...stale];
 }

package/src/errors.ts

@@ -2,6 +2,7 @@
 // that resolves it — the codes themselves, their titles and their registration are `./error-codes`,
 // so a package importing a class does not pull the table and vice versa.
 import { UltimateError } from '@ultimat3/core';
+import type { Finding } from './output';
 import { quoteArg } from './shell-quote';
 
 /** An unknown command or subcommand. Carries a suggestion so the retry is one keystroke away. */
@@ -301,14 +302,59 @@ export class FixTargetUnknownError extends UltimateError {
   }
 }
 
-// The build and bundle refusals live in `build-errors.ts` (split at the 500-line ceiling); re-exported
-// here so every existing `from './errors'` import keeps resolving.
-export type { FrameworkScriptKind } from './build-errors';
-export {
-  BuildEntryMissingError,
-  FrameworkScriptBuildFailedError,
-  IslandBuildFailedError,
-} from './build-errors';
+/**
+ * A client entry would not compile. `X_BUILD_FAILED`, not a code of its own: an island is a bundle
+ * entry point like any other, and the target's own logs are what says which line. The fix builds
+ * exactly that one file, so the next message an author reads is the compiler's and not the CLI's.
+ */
+export class IslandBuildFailedError extends UltimateError {
+  constructor(input: { file: string; logs: string }) {
+    super({
+      code: 'X_BUILD_FAILED',
+      cause: `${input.file} is an island entry point and would not bundle: ${input.logs}`,
+      fix: `bun build --target browser ${input.file}`,
+    });
+  }
+}
+
+/** Which framework script a page ships: the sync worker, the page boot, or the client router. */
+export type FrameworkScriptKind = 'sync worker' | 'page boot' | 'client router';
+
+/**
+ * One of the page's framework scripts would not bundle. Same code as an island: "a browser entry
+ * the framework builds did not build" is one condition, and the entry here is framework code, not
+ * the app's — the cause names WHICH script, so the reader knows what the page is now missing.
+ */
+export class FrameworkScriptBuildFailedError extends UltimateError {
+  constructor(input: { what: FrameworkScriptKind; entry: string; logs: string }) {
+    super({
+      code: 'X_BUILD_FAILED',
+      cause: `the ${input.what} (${input.entry}) would not bundle for the browser: ${input.logs}`,
+      fix: `bun build --target browser --format iife ${quoteArg(input.entry)}`,
+    });
+  }
+}
+
+/**
+ * A static build over an app whose modules did not all import. The route registry is filled BY the
+ * import, so a page whose module threw is not skipped but absent — and an export without it, with
+ * `x build` green, is a deploy that deletes a page. The `manifest` step owns load findings
+ * (`load-findings.ts`), so the fix is the command that lists every one with its own fix.
+ */
+export class PrerenderLoadFailedError extends UltimateError {
+  constructor(findings: readonly Finding[]) {
+    const listed = findings.map((finding) =>
+      finding.at === undefined
+        ? `${finding.code} ${finding.cause}`
+        : `${finding.at}: ${finding.code} ${finding.cause}`,
+    );
+    super({
+      code: 'X_BUILD_FAILED',
+      cause: `the static export renders the routes the app's modules register, and ${findings.length} module load finding(s) left it short: ${listed.join('; ')}`,
+      fix: 'x verify --only manifest --json',
+    });
+  }
+}
 
 /**
  * `ROLE` selects what a container is. One image runs every role, so a typo is a process that would
@@ -363,36 +409,6 @@ export class PortInvalidError extends UltimateError {
   }
 }
 
-/**
- * `x env` was run in an app whose `app.config.ts` exports no `envSchema`. Not a silent success:
- * writing a `.env.example` with no variables in it, or reporting "0 declared variables, all
- * present", both read as a working environment declaration to whoever runs the command next.
- *
- * `X_CONFIG_INVALID` is core's code for "a configuration this process cannot boot on — env or
- * `app.config.ts`", which is exactly this; the CLI names it in `CLI_BORROWED_ERROR_CODES` rather
- * than minting a synonym.
- */
-export class EnvSchemaMissingError extends UltimateError {
-  constructor(input: { subcommand: string }) {
-    super({
-      code: 'X_CONFIG_INVALID',
-      cause: `x env ${input.subcommand} needs the env declaration, and app.config.ts exports no "envSchema"`,
-      fix: "add to app.config.ts: export const envSchema = { DATABASE_URL: { type: 'url', description: 'Postgres connection URL' } } satisfies EnvSchema; export const env = defineEnv(envSchema);",
-    });
-  }
-}
-
-/** An interface-complete command path whose remote/native half is not written yet. */
-export class CliNotImplementedError extends UltimateError {
-  constructor(input: { feature: string; fix: string }) {
-    super({
-      code: 'X_NOT_IMPLEMENTED',
-      cause: `${input.feature} is not implemented in this build`,
-      fix: input.fix,
-    });
-  }
-}
-
 /**
  * The process could not obtain a storage disk to write to.
  *
@@ -432,48 +448,3 @@ export class LocalDiskUnsafeError extends UltimateError {
     });
   }
 }
-
-/**
- * `x secrets edit` decrypts into a buffer and hands it to `$EDITOR`. There is no fallback editor:
- * guessing one and opening a decrypted file in it is the last place a surprise belongs.
- */
-export class SecretsEditorMissingError extends UltimateError {
-  constructor(input: { vars: readonly string[] }) {
-    super({
-      code: 'X_SECRETS_EDITOR_MISSING',
-      cause: `x secrets edit opens the decrypted secrets in an editor and none of ${input.vars.join(', ')} is set`,
-      fix: 'EDITOR=nano x secrets edit',
-    });
-  }
-}
-
-/**
- * The editor exited non-zero — a crash, or a deliberate abort. The buffer is discarded either way
- * and the committed file is left exactly as it was: resealing a buffer whose editor failed would
- * commit whatever half-written state the crash left behind.
- */
-export class SecretsEditFailedError extends UltimateError {
-  constructor(input: { editor: string; code: number }) {
-    super({
-      code: 'X_SECRETS_EDIT_FAILED',
-      cause: `"${input.editor}" exited ${input.code}, so the decrypted buffer was discarded and the committed secrets file was not rewritten`,
-      fix: 'x secrets edit',
-    });
-  }
-}
-
-/**
- * `x secrets init` would overwrite a file that already exists. `X_GENERATE_CONFLICT` is this
- * package's own code for exactly that, and a second name for "a generator would clobber something"
- * is the duplication the code registry exists to prevent. Losing a master key is unrecoverable —
- * the committed file it opens is then ciphertext nobody can read again.
- */
-export class SecretsExistsError extends UltimateError {
-  constructor(input: { path: string; fix: string }) {
-    super({
-      code: 'X_GENERATE_CONFLICT',
-      cause: `${input.path} already exists, and x secrets init would replace it`,
-      fix: input.fix,
-    });
-  }
-}