@ultimat3/cli 23.0.0 → 24.0.0

package/src/dev-dashboard.ts

@@ -1,6 +1,6 @@
 // Mounting `@ultimat3/admin`'s `/_x` dashboard in the `x dev` process. The CLI contributes only
-// what no registry holds — a SQL runner on the live dev database, the caught outbox, the committed
-// manifest, and two panels of process facts — and projects the dashboard onto HTTP routes.
+// what no registry holds — the live dev database, the caught outbox, the committed manifest, and
+// two panels of process facts — and projects the dashboard onto HTTP routes behind a Host check.
 // A panel implemented here instead of in `admin` would be the second copy this seam exists to ban.
 
 import type {
@@ -14,7 +14,13 @@ import type {
   SqlResult,
   StatementLoopFact,
 } from '@ultimat3/admin/dev';
-import { DEV_BASE_PATH, DEV_PANELS, defaultDevSources, devDashboard } from '@ultimat3/admin/dev';
+import {
+  DEV_BASE_PATH,
+  DEV_PANELS,
+  defaultDevSources,
+  devDashboard,
+  readOnlySql,
+} from '@ultimat3/admin/dev';
 import { recentInvalidations } from '@ultimat3/cache';
 import type { Role } from '@ultimat3/core';
 import type { Route, UltimateRequest } from '@ultimat3/http';
@@ -24,6 +30,7 @@ import { isMemoryDriver } from '@ultimat3/mail';
 import type { Manifest } from '@ultimat3/manifest';
 import { appManifest, readAppManifest } from './app-manifest';
 import { appBoundaryFindings } from './boundary-findings';
+import { assertSameOrigin, hostRefusal, SQL_BODY, sqlOnGet } from './dev-dashboard-guard';
 import type { StatementLedger } from './dev-n-plus-one';
 import { devPolicyMatrix } from './dev-policy';
 import type { TraceRecorder } from './dev-traces';
@@ -53,24 +60,6 @@ export interface DevDashboardInput {
   readonly statements?: StatementLedger | undefined;
 }
 
-/**
- * Read-only is already enforced by `assertReadOnly` inside `dbPanel`, before `runSql` is ever
- * reached. A second gate here would be a second authz: two places to update when what the panel
- * allows changes, and one of them would eventually disagree.
- */
-async function runSql(input: DevDashboardInput, sql: string): Promise<SqlResult> {
-  const started = performance.now();
-  const rows = await input.runtime.db.query<Readonly<Record<string, unknown>>>({
-    text: sql,
-    values: [],
-  });
-  const elapsedMs = Math.round(performance.now() - started);
-  // Columns come from the first row because the driver returns objects, not a described result
-  // set; no rows means no columns to name, which the panel renders as an empty grid.
-  const columns = Object.keys(rows[0] ?? {});
-  return { columns, rows: rows.map((row) => columns.map((column) => row[column])), elapsedMs };
-}
-
 /** `MailMessage.locale` is non-optional in `@ultimat3/mail`, so the panel never has to guess. */
 function mailFacts(outbox: MemoryMailDriver): readonly MailFact[] {
   return outbox.outbox().map((entry) => ({
@@ -137,9 +126,13 @@ export function devSources(input: DevDashboardInput): DevSources {
   // the messages are at the provider, so the hook is omitted rather than answered with `[]` —
   // an empty outbox claims nobody was mailed, which is a different and unearned answer.
   const outbox = isMemoryDriver(input.runtime.mail) ? input.runtime.mail : undefined;
+  // `dbPanel`'s `assertReadOnly` is the parse guard; `readOnlySql` is the server saying no — its own
+  // `BEGIN READ ONLY` that always rolls back, a statement timeout and a row ceiling. The plain
+  // `db.query` it replaces ran whatever the guard let through with the app's own credentials.
+  const runSql = readOnlySql(input.runtime.db);
   return defaultDevSources({
     hooks: {
-      runSql: (sql: string): Promise<SqlResult> => runSql(input, sql),
+      runSql: (sql: string): Promise<SqlResult> => runSql(sql),
       ...(outbox === undefined
         ? {}
         : { mail: (): Promise<readonly MailFact[]> => Promise.resolve(mailFacts(outbox)) }),
@@ -222,8 +215,13 @@ const notClaimed = (path: string): Response =>
     { status: 404 },
   );
 
-const devRoute = (path: string, name: string, handler: Route['handler']): Route => ({
-  method: 'GET',
+const devRoute = (
+  path: string,
+  name: string,
+  handler: Route['handler'],
+  method: 'GET' | 'POST' = 'GET',
+): Route => ({
+  method,
   path,
   // Public: /_x exists to be read without credentials by whatever drives the dev loop, and
   // `devDashboard` refuses to construct at all outside development.
@@ -232,9 +230,10 @@ const devRoute = (path: string, name: string, handler: Route['handler']): Route
 });
 
 /**
- * One route for the base path plus one per panel, because the router matches exact paths. The
- * dashboard is built once — its sources close over this process, and rebuilding per request would
- * re-run `assertDevOnly` on every hit for no new answer.
+ * One route for the base path plus one per panel, because the router matches exact paths, and a
+ * `POST` for the SQL panel — the only `/_x` read that runs something. The dashboard is built once
+ * — its sources close over this process, and rebuilding per request would re-run `assertDevOnly`
+ * on every hit for no new answer. Every route answers this machine's Host only.
  */
 export function devDashboardRoutes(input: DevDashboardInput): readonly Route[] {
   const panels = devPanels(input);
@@ -245,13 +244,36 @@ export function devDashboardRoutes(input: DevDashboardInput): readonly Route[] {
     ...(input.env === undefined ? {} : { env: input.env }),
   });
 
-  const handler = async (request: UltimateRequest): Promise<Response> =>
-    (await dashboard.handle(request.raw)) ?? notClaimed(request.pathname);
+  const sqlPath = `${DEV_BASE_PATH}/db`;
+  const handler = async (request: UltimateRequest): Promise<Response> => {
+    const devUrl = input.status().url;
+    const refused = hostRefusal(request, devUrl);
+    if (refused !== undefined) return refused;
+    if (request.pathname === sqlPath && request.url.searchParams.has('sql')) throw sqlOnGet(devUrl);
+    return (await dashboard.handle(request.raw)) ?? notClaimed(request.pathname);
+  };
+  // The statement moves from the body onto the panel's own parameter, server side: `dbPanel`
+  // reads `sql` off the query, and this is the one caller allowed to put it there.
+  const runStatement = async (request: UltimateRequest): Promise<Response> => {
+    const refused = hostRefusal(request, input.status().url);
+    if (refused !== undefined) return refused;
+    assertSameOrigin(request);
+    const { sql } = await request.body(SQL_BODY);
+    const target = new URL(request.url);
+    target.searchParams.set('sql', sql);
+    // A GET carries no body, so the body's own headers stay behind; `accept` and the rest ride.
+    const headers = new Headers(request.headers);
+    headers.delete('content-type');
+    headers.delete('content-length');
+    const forwarded = new Request(target, { headers });
+    return (await dashboard.handle(forwarded)) ?? notClaimed(request.pathname);
+  };
 
   return [
     devRoute(DEV_BASE_PATH, 'dev._x', handler),
     ...panels.map((panel) =>
       devRoute(`${DEV_BASE_PATH}/${panel.key}`, `dev._x.${panel.key}`, handler),
     ),
+    devRoute(sqlPath, 'dev._x.db.run', runStatement, 'POST'),
   ];
 }

package/src/dev-lock.ts

@@ -18,6 +18,7 @@ import { closeSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync
 import { join } from 'node:path';
 import { stringField, UltimateError } from '@ultimat3/core';
 import { exec, type Runner } from './exec';
+import { portPairAfter } from './flag-number';
 import { quoteArg } from './shell-quote';
 
 /** Where the running dev server records itself, inside the state directory it already owns. */
@@ -220,12 +221,6 @@ export class DevPortInUseError extends UltimateError {
   }
 }
 
-/**
- * The next port to suggest. Never `port + 1` at the top of the range — 65536 is not a port, and a
- * `fix:` that cannot run is the failure this whole module exists to end.
- */
-export const suggestPort = (port: number): number => (port >= 65535 ? port - 1 : port + 1);
-
 /**
  * Is anything listening? A successful bind-then-close is the only answer that does not lie.
  *
@@ -379,7 +374,9 @@ export const preflight = async (input: PreflightInput): Promise<PreflightResult>
     release();
     throw new DevPortInUseError({
       port: input.port,
-      suggestion: suggestPort(input.port),
+      // `portPairAfter`, never `port + 1`: `x dev` binds a PAIR, so the holder is most often
+      // another `x dev` whose sync role already sits on `port + 1`.
+      suggestion: portPairAfter(input.port),
       holder: await (input.holder ?? portHolder)(input.port),
     });
   }

package/src/dispatch.ts

@@ -6,9 +6,9 @@ import { isAbsolute, resolve } from 'node:path';
 import { setLogStream } from '@ultimat3/core';
 import { requireAppRoot, requireBunVersion } from './app-root';
 import { createHelpCommand } from './cmd-help';
-import { plannedCommandFor } from './cmd-planned';
+import { plannedCommandError, plannedCommandFor } from './cmd-planned';
 import type { CommandContext } from './command';
-import { CliNotImplementedError, UnknownCommandError } from './errors';
+import { UnknownCommandError } from './errors';
 import type { Runner } from './exec';
 import { exec } from './exec';
 import type { CommandResult } from './output';
@@ -91,10 +91,7 @@ export async function dispatch(options: DispatchOptions): Promise<number> {
     // X_NOT_IMPLEMENTED with a runnable fix. Substituted here rather than in `parse.ts`, which is
     // pure and knows nothing about what a command means; the precedent is the help swap below.
     const planned = plannedCommandFor(commandFor(options.argv[0] ?? '')?.spec.name);
-    const failure =
-      planned === undefined
-        ? error
-        : new CliNotImplementedError({ feature: `x ${planned.name}`, fix: planned.fix });
+    const failure = planned === undefined ? error : plannedCommandError(planned);
     // `wantsJson`, not `includes('--json')`: a typo'd flag or a typo'd command is exactly the case
     // an agent hits while always passing `-j`, and the short form rendered prose it then parsed.
     const result = errorResult(planned?.name ?? 'x', failure);

package/src/doctor-app-url.ts

@@ -0,0 +1,39 @@
+// `x doctor`'s APP_URL rule, pure: a set APP_URL must be an origin a browser can match, and a
+// loopback one must name the port `x dev` serves on — OAuth's redirect, absolute links and the sync
+// node's admitted origin all read it, and a laptop origin on another port reaches another server.
+
+import { ERROR_DOCS_URL, renderFixShellArg } from '@ultimat3/core';
+import { isLoopbackHostname } from './loopback-host';
+import type { Finding } from './output';
+import { findingFrom } from './output';
+import { syncOriginsFrom } from './sync-url';
+
+/**
+ * Unset is no finding: `x dev` serves without one, and a production build warns on its own
+ * (`originWarning`). A public origin is not judged against the dev port — that is the deploy's
+ * address, not this machine's. The parse is the sync boot's own (`syncOriginsFrom`), so doctor
+ * refuses exactly the values the boot would.
+ */
+export function appUrlFindings(raw: string | undefined, port: number): readonly Finding[] {
+  let origins: readonly string[];
+  try {
+    origins = syncOriginsFrom({ APP_URL: raw });
+  } catch (error) {
+    return [findingFrom(error)];
+  }
+  const origin = origins[0];
+  if (origin === undefined) return [];
+  const url = new URL(origin);
+  if (!isLoopbackHostname(url.hostname)) return [];
+  const declared = url.port === '' ? (url.protocol === 'https:' ? 443 : 80) : Number(url.port);
+  if (declared === port) return [];
+  const wanted = `${url.protocol}//${url.hostname}:${String(port)}`;
+  return [
+    {
+      code: 'X_APP_URL_PORT_MISMATCH',
+      cause: `APP_URL is ${origin}, but x dev serves this app on port ${String(port)} — OAuth redirects, absolute links and the sync origin would point at another server`,
+      fix: `export APP_URL=${renderFixShellArg(wanted, 'http://localhost:3000')}`,
+      docs: ERROR_DOCS_URL,
+    },
+  ];
+}

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 { BuiltinAdapter, countUnsealedMfaSecrets } from '@ultimat3/auth';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import { createPostgresClient, 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 = createPostgresClient({ 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: new BuiltinAdapter(client) })
+      : 0;
+    return { unsealedMfaSecrets, retiredTables };
+  } catch {
+    return NO_AUTH_STORAGE_FACT;
+  } finally {
+    await client.close();
+  }
+}

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: its live queries' `subscribes:` plus every params channel's `records`
+ * tables, 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/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,19 @@ 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',
 ] 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 +293,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 +400,18 @@ 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',
 };
 
 // One unconditional call, so a second package claiming one of the CLI's codes throws

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];
 }