@ultimat3/cli 11.3.0 → 13.0.0

package/src/dev-queue.ts

@@ -8,10 +8,8 @@ import {
   type PostgresIdempotencyStore,
   postgresIdempotencyStore,
   resetIdempotency,
-  SQL_IDEMPOTENCY_TABLE,
   setIdempotencyStore,
 } from '@ultimat3/action';
-import { SQL_AUTH_LIMIT_TABLES } from '@ultimat3/auth';
 import type { DbClient, PgliteClient, PostgresClient, SqlFragment } from '@ultimat3/db';
 import {
   createPgliteClient,
@@ -22,7 +20,6 @@ import {
   setDbClient,
 } from '@ultimat3/db';
 import type { Tx } from '@ultimat3/entity';
-import { SQL_RATE_LIMIT_TABLE } from '@ultimat3/http';
 import type { EventBus, JobDriver, OutboxStore, PgExecutor } from '@ultimat3/jobs';
 import {
   createJobsFacade,
@@ -31,17 +28,24 @@ import {
   createPgOutboxStore,
   resetJobDriver,
   resetJobsFacade,
-  SQL_JOBS_TABLE,
   setEventBus,
   setJobDriver,
   setJobsFacade,
 } from '@ultimat3/jobs';
+import { attachReplica, type ReplicaEnv, replicaUrlFor } from './dev-replica';
 import type { DevServices } from './dev-services';
+import { applyFrameworkSchema } from './framework-schema';
 import type { RuntimeOverrides } from './runtime-overrides';
 
 /** Both embedded and external clients boot lazily and close explicitly. */
 export type DevDbClient = PgliteClient | PostgresClient;
 
+/** The primary this boot owns, plus the standby pool it opened — `stop()` closes both. */
+interface StartedDb {
+  readonly client: DevDbClient;
+  readonly replica: PostgresClient | undefined;
+}
+
 export interface RunningQueue {
   readonly db: DevDbClient;
   readonly jobs: JobDriver;
@@ -62,7 +66,20 @@ export interface RunningQueue {
   stop(): Promise<void>;
 }
 
-function startDb(services: DevServices): DevDbClient {
+/**
+ * The boot's own client, and the AMBIENT one, which are deliberately not always the same object.
+ *
+ * `setDbClient` receives the replicated pair when `DATABASE_REPLICA_URL` names a standby, so an
+ * app repository reading through `db()` inside an open `withReplicaReads` scope can be served by
+ * it. Everything this file does itself — `applySchema`, the `PgExecutor` behind the queue, the
+ * outbox, `ping()`, `close()` — keeps the PRIMARY: DDL, a claim and a migration are writes by
+ * definition, and routing one would be `25006` at best.
+ *
+ * Before this, `defaultClient()` was the only composer of a replicated pair in the framework and
+ * it runs only from `baseClient()` — the client an app installed NONE for. This line installs one,
+ * so `DATABASE_REPLICA_URL` was read by no booted process at all.
+ */
+function startDb(services: DevServices, env: ReplicaEnv = process.env): StartedDb {
   const binding = services.db;
   const client =
     binding.mode === 'embedded'
@@ -70,8 +87,9 @@ function startDb(services: DevServices): DevDbClient {
         // here is a second thing to keep right when the form changes.
         createPgliteClient({ dataDir: pgliteDataDir(binding.url) })
       : createPostgresClient({ url: binding.url });
-  setDbClient(client);
-  return client;
+  const attached = attachReplica(client, replicaUrlFor(binding, env));
+  setDbClient(attached.client);
+  return { client, replica: attached.replica };
 }
 
 /**
@@ -91,33 +109,18 @@ export function pgExecutorFor(client: DbClient): PgExecutor {
 /**
  * Every table this process's framework packages own, applied before anything reads one.
  *
- * PGlite speaks the extended protocol, which carries one statement per round trip, so the DDL is
- * applied statement by statement. Safe to split on `;`: every constant is fixed, with no semicolon
- * inside a literal, and each package's own SQL test is where that stays true.
+ * The LIST is `FRAMEWORK_SCHEMA` and lives in `framework-schema.ts`, not here: this function is on
+ * every boot path the framework has — `x dev`, each served role, `x jobs`, `x db backfill`,
+ * `x mcp serve` and `ROLE=migrate` all reach it through `startQueue` — so the list it reads is the
+ * one place a framework table can be forgotten, and it is worth being a table somebody can read
+ * rather than an array literal inside a boot function.
  *
- * `SQL_IDEMPOTENCY_TABLE`, `SQL_RATE_LIMIT_TABLE` and `SQL_AUTH_LIMIT_TABLES` are here and not in
- * `@ultimat3/action`, `@ultimat3/http` or `@ultimat3/auth` because a package that holds no
- * database dependency cannot apply its own schema
- * — the same reason `SQL_JOBS_TABLE` is applied here. Each one absent is the same failure at a
- * different door: a retried `POST /api/payments/charge` charges the card twice, and the FIRST
- * request a `rateLimitStore` deployment serves dies on a missing `x_rate_limit` relation. The
- * table is installed whether or not this boot passes `runtime.rateLimitStore` — `create table if
- * not exists` on an unused table costs one round trip at boot, and a store installed later must
- * not be the thing that discovers the schema was never applied. The auth pair is the strongest
- * case for that rule: `defineAuth` builds its limiter when the APP's modules import, which is
- * after this, so the first failed sign-in would otherwise be what discovers the missing relation.
+ * Each package's DDL is here and not in `@ultimat3/action`, `@ultimat3/http`, `@ultimat3/auth` or
+ * `@ultimat3/notify` because a package that holds no database dependency cannot apply its own
+ * schema — the same reason `SQL_JOBS_TABLE` is applied by the boot.
  */
 async function applySchema(client: DevDbClient): Promise<void> {
-  for (const ddl of [
-    SQL_JOBS_TABLE,
-    SQL_IDEMPOTENCY_TABLE,
-    SQL_RATE_LIMIT_TABLE,
-    SQL_AUTH_LIMIT_TABLES,
-  ]) {
-    for (const statement of ddl.split(';')) {
-      if (statement.trim().length > 0) await client.execute(raw(statement));
-    }
-  }
+  await applyFrameworkSchema((statement) => client.execute(raw(statement)));
 }
 
 /**
@@ -148,7 +151,11 @@ async function applySchema(client: DevDbClient): Promise<void> {
  * `startServices` runs before `loadApp`, so the store is in place before `registerAction`
  * evaluates a `scope: 'shared'` declaration against it.
  */
-async function startJobs(client: DevDbClient, overrides?: RuntimeOverrides): Promise<RunningQueue> {
+async function startJobs(
+  client: DevDbClient,
+  replica: PostgresClient | undefined,
+  overrides?: RuntimeOverrides,
+): Promise<RunningQueue> {
   await applySchema(client);
   const executor = pgExecutorFor(client);
   const driver = overrides?.jobs ?? createPgDriver({ executor });
@@ -171,7 +178,7 @@ async function startJobs(client: DevDbClient, overrides?: RuntimeOverrides): Pro
     outbox,
     events,
     idempotency,
-    stop: () => releaseQueue(client, driver),
+    stop: () => releaseQueue(client, driver, replica),
   };
 }
 
@@ -184,7 +191,11 @@ async function startJobs(client: DevDbClient, overrides?: RuntimeOverrides): Pro
  * The facade goes with the driver for the same reason: an enqueue routed through a store bound to
  * a closed client is a staged row nothing will ever publish.
  */
-async function releaseQueue(db: DevDbClient, jobs: JobDriver | undefined): Promise<void> {
+async function releaseQueue(
+  db: DevDbClient,
+  jobs: JobDriver | undefined,
+  replica?: PostgresClient,
+): Promise<void> {
   // The idempotency store goes back to the memory default for the same reason the facade does: it
   // holds this client, and the next command in this process would reserve keys over a closed one.
   resetIdempotency();
@@ -193,6 +204,9 @@ async function releaseQueue(db: DevDbClient, jobs: JobDriver | undefined): Promi
   setDbClient(undefined);
   await jobs?.close?.();
   await db.close();
+  // After the primary, and never instead of it: a standby pool left open is a connection slot on
+  // the other server that nothing in this process can reach again.
+  await replica?.close();
 }
 
 /**
@@ -205,18 +219,18 @@ export async function startQueue(
   services: DevServices,
   overrides?: RuntimeOverrides,
 ): Promise<RunningQueue> {
-  const db = startDb(services);
+  const { client: db, replica } = startDb(services);
   try {
     // Pay the Postgres boot here, so the first request is not the slow one and a broken database
     // fails at boot rather than on some later query.
     await db.ping();
-    return await startJobs(db, overrides);
+    return await startJobs(db, replica, overrides);
   } catch (error) {
     // `db.ping()` or `startJobs` is where a broken database is supposed to fail. Without this,
     // the caller exits holding the PGlite lock and the ambient accessors, and nothing is left to
     // release them. The rejection that started the unwind is the one worth reporting.
     try {
-      await releaseQueue(db, undefined);
+      await releaseQueue(db, undefined, replica);
     } catch {
       // Cleanup noise never replaces the boot failure.
     }

package/src/dev-replica.ts

@@ -0,0 +1,99 @@
+// Read-replica routing, WIRED. `@ultimat3/db` ships both halves and a booted process reached
+// neither, so the capability was shipped and unactivated — the "declared and never wired" class
+// this release exists to eliminate.
+//
+// Two things had to be false for it to route, and both were:
+//
+// 1. `defaultClient()` is the one place db composes `replicatedClient(primary, replica)` from
+//    `DATABASE_REPLICA_URL`, and it runs only from `baseClient()` — "the client an app installed
+//    none for". Every process the framework boots installs one: `dev-queue.ts` calls
+//    `setDbClient(createPgliteClient(…) | createPostgresClient({ url }))`, so `defaultClient()` was
+//    unreachable from `x dev`, from `apps/web/server.ts` and from every container role.
+// 2. Routing needs an OPEN scope as well as a configured replica, and nothing opened one.
+//
+// This file answers both from the boot, which is the only tier that may know about a request AND
+// about a pool. It is deliberately NOT a change to `@ultimat3/http`'s pipeline: that would make the
+// HTTP tier depend on `@ultimat3/db` — legal downward, and still a package that would then know
+// what a database is.
+
+import type { DbClient, PostgresClient } from '@ultimat3/db';
+import {
+  createPostgresClient,
+  REPLICA_URL_ENV,
+  replicatedClient,
+  withReplicaReads,
+} from '@ultimat3/db';
+import type { Middleware } from '@ultimat3/http';
+import type { ServiceBinding } from './dev-services';
+import type { RuntimeOverrides } from './runtime-overrides';
+
+export type ReplicaEnv = Readonly<Record<string, string | undefined>>;
+
+/**
+ * The replica url this boot should use, or `undefined`. Two conditions, and the second is the one
+ * a homework app depends on: an EMBEDDED database is PGlite in this process, which has no standby
+ * and never will, so a `DATABASE_REPLICA_URL` left over in a shell must not silently open a second
+ * pool beside it.
+ */
+export function replicaUrlFor(binding: ServiceBinding, env: ReplicaEnv): string | undefined {
+  if (binding.mode !== 'external') return undefined;
+  const url = env[REPLICA_URL_ENV];
+  return url === undefined || url.trim() === '' ? undefined : url;
+}
+
+/** What a boot has to hold on to: the ambient client, and the pool `stop()` must close. */
+export interface ReplicaAttachment {
+  /** What `setDbClient()` receives — the pair when one is configured, the primary otherwise. */
+  readonly client: DbClient;
+  /** The standby pool this boot opened, or nothing. `ReplicatedClient` has no `close()`. */
+  readonly replica: PostgresClient | undefined;
+}
+
+/**
+ * The primary as it is, or the primary with a standby behind it. Composed here rather than by
+ * calling `defaultClient()`, because that function builds its own primary from `DATABASE_URL` and
+ * this boot has already RESOLVED which database it is talking to (`resolveServices`) — asking the
+ * environment a second question is how a process ends up with two answers to "which database is
+ * this". The pieces are db's own, so the routing rule is still stated in one place.
+ */
+export function attachReplica(
+  primary: DbClient,
+  replicaUrl: string | undefined,
+): ReplicaAttachment {
+  if (replicaUrl === undefined) return { client: primary, replica: undefined };
+  const replica = createPostgresClient({ url: replicaUrl, applicationName: 'ultimate-replica' });
+  return { client: replicatedClient(primary, replica), replica };
+}
+
+/**
+ * The scope, opened once per request, OUTSIDE the handler — so a write early in a request pins
+ * every later read in it to the primary, which is what read-your-writes means. `compose()` wraps
+ * each route handler, and every read and write a request makes happens inside one.
+ *
+ * EMPTY when no replica is configured, and that is the whole cost argument: a homework app
+ * installs no middleware, allocates no scope object and enters no `AsyncLocalStorage` run per
+ * request. With one configured, the list is a single frame.
+ */
+export function replicaMiddleware(binding: ServiceBinding, env: ReplicaEnv): readonly Middleware[] {
+  if (replicaUrlFor(binding, env) === undefined) return [];
+  return [(request, ctx, next) => withReplicaReads(() => next(request, ctx))];
+}
+
+/**
+ * The boot's `RuntimeOverrides` with the scope middleware laid in FRONT of whatever a host
+ * supplied — `compose([a, b])` runs `a` outermost, and the scope must open outside every read and
+ * write the request makes or a write early in it cannot pin the reads after it.
+ *
+ * Returns the caller's own value UNCHANGED when no replica is configured, which is what keeps a
+ * homework app from paying for this: no key added, no empty array, nothing for `startRoles` to
+ * forward.
+ */
+export function replicaOverrides(
+  overrides: RuntimeOverrides | undefined,
+  binding: ServiceBinding,
+  env: ReplicaEnv,
+): RuntimeOverrides | undefined {
+  const middleware = replicaMiddleware(binding, env);
+  if (middleware.length === 0) return overrides;
+  return { ...overrides, middleware: [...middleware, ...(overrides?.middleware ?? [])] };
+}

package/src/dev-roles-fixture.ts

@@ -7,6 +7,7 @@
 
 import { noopPurgeDriver } from '@ultimat3/cache';
 import { resetLifecycle } from '@ultimat3/core';
+import { resetHttpConfig } from '@ultimat3/http';
 import {
   createMemoryDriver,
   createMemoryEventBus,
@@ -64,4 +65,10 @@ export function resetDevRolesState(): void {
   resetJobsFacade();
   resetTasks();
   resetLifecycle();
+  // `configureHttp()` is a process-global registration made at MODULE scope, so one file that
+  // loads an app leaves that app's CORS origins, body limit and buckets standing for every later
+  // file in the same `bun test` process — and a scaffolded app now ships such a module
+  // (`apps/web/app/http.ts`). Nothing is broken today; this is the same rule the four resets above
+  // already follow, applied to the fifth global before it is the one that costs an afternoon.
+  resetHttpConfig();
 }

package/src/dev-roles.ts

@@ -9,7 +9,13 @@
 import type { Role } from '@ultimat3/core';
 import { createContext, isRole, logger, ROLES } from '@ultimat3/core';
 import type { RateLimitStore, Route, ServerHandle, ServerHooks } from '@ultimat3/http';
-import { configuredAuthenticator, createServer, defineHttpConfig } from '@ultimat3/http';
+import {
+  configuredAuthenticator,
+  configuredHttp,
+  createServer,
+  defineHttpConfig,
+  mergeHttpConfig,
+} from '@ultimat3/http';
 import type { OutboxRelay, Scheduler, Worker } from '@ultimat3/jobs';
 import {
   createOutboxRelay,
@@ -257,37 +263,45 @@ function startWeb(options: StartRolesOptions): ServerHandle {
       ? {}
       : { middleware: options.overrides.middleware }),
     ...(store === undefined ? {} : { rateLimitStore: store }),
-    config: defineHttpConfig({
-      port: options.port,
-      dev: binding.dev,
-      buildId: options.buildId,
-      hostname: binding.hostname,
-      signInPath: options.signInPath ?? null,
-      // One declaration, never half of one: `defineHttpConfig` refuses `trustProxy` without hops.
-      ...(hops === null ? {} : { trustProxy: true, trustedProxyHops: hops }),
-      // `scope` is mandatory since @ultimat3/http made an undeclared limiter a boot error, and it
-      // is DERIVED from the store rather than hardcoded — a literal here would be a second
-      // declaration quietly contradicting the object beside it, and `assertRateLimitScope` holds
-      // the two halves together. It answered `'process'` on every real boot until `startServices`
-      // resolved a store, so the shipped chart's three `web` replicas enforced `login: { limit: 5 }`
-      // as fifteen attempts, with `x verify` green.
-      rateLimit: { scope: store?.scope ?? 'process' },
-      // Hashes, never `'unsafe-inline'`: a `render: 'static'` page is a file on disk, so
-      // nothing can stamp a per-response nonce into it, but its body is fixed and a hash is a
-      // function of that body. Read after `loadApp` — importing the app IS what registered them.
-      // BOTH directives, and the script half is the one that was missing: the hydration runtime
-      // is emitted inline in every document that carries an island, so `script-src 'self'` meant
-      // no island booted anywhere the policy is enforced — which is every container, and never
-      // `x dev`, where it is report-only.
-      security: {
-        csp: {
-          extend: {
-            'style-src': inlineStyleSources(options.inlineStyles ?? []),
-            'script-src': inlineScriptSources(),
+    // The app's own declaration UNDERNEATH, this boot's facts on top. Without the first half the
+    // entire HTTP tuning surface was unreachable from a shipped app — this literal was its only
+    // construction, so `cors.origins` stayed `[]` in every deployment (no cross-origin call could
+    // ever succeed), `bodyLimitBytes` stayed 1 MiB and `requestTimeoutMs` 30s for a bank and a
+    // blog alike. The ORDER is not a preference: `buildId`, the port, the CSP hashes of what this
+    // process emits and the scope of the store it installed are facts only the boot has.
+    config: defineHttpConfig(
+      mergeHttpConfig(configuredHttp(), {
+        port: options.port,
+        dev: binding.dev,
+        buildId: options.buildId,
+        hostname: binding.hostname,
+        signInPath: options.signInPath ?? null,
+        // One declaration, never half of one: `defineHttpConfig` refuses `trustProxy` without hops.
+        ...(hops === null ? {} : { trustProxy: true, trustedProxyHops: hops }),
+        // `scope` is mandatory since @ultimat3/http made an undeclared limiter a boot error, and it
+        // is DERIVED from the store rather than hardcoded — a literal here would be a second
+        // declaration quietly contradicting the object beside it, and `assertRateLimitScope` holds
+        // the two halves together. It answered `'process'` on every real boot until `startServices`
+        // resolved a store, so the shipped chart's three `web` replicas enforced
+        // `login: { limit: 5 }` as fifteen attempts, with `x verify` green.
+        rateLimit: { scope: store?.scope ?? 'process' },
+        // Hashes, never `'unsafe-inline'`: a `render: 'static'` page is a file on disk, so
+        // nothing can stamp a per-response nonce into it, but its body is fixed and a hash is a
+        // function of that body. Read after `loadApp` — importing the app IS what registered them.
+        // BOTH directives, and the script half is the one that was missing: the hydration runtime
+        // is emitted inline in every document that carries an island, so `script-src 'self'` meant
+        // no island booted anywhere the policy is enforced — which is every container, and never
+        // `x dev`, where it is report-only.
+        security: {
+          csp: {
+            extend: {
+              'style-src': inlineStyleSources(options.inlineStyles ?? []),
+              'script-src': inlineScriptSources(),
+            },
           },
         },
-      },
-    }),
+      }),
+    ),
   }).start();
 }
 

package/src/dev-sync.ts

@@ -16,6 +16,7 @@ import {
 } from '@ultimat3/realtime/server';
 import type { StartRolesOptions } from './dev-roles';
 import { neighbouringPort, PORT_RANGE } from './flag-number';
+import { portFree } from './port-probe';
 import { syncAuthenticator } from './sync-authenticator';
 
 /**
@@ -35,6 +36,46 @@ class SyncPortUnavailableError extends UltimateError {
   }
 }
 
+/**
+ * The neighbour was already listening. `X_PORT_IN_USE` is this package's own and is exactly what
+ * `x doctor` reports for the same condition, so one taken port has one name wherever it is found.
+ *
+ * What shipped instead: `listenSyncNode`'s `Bun.serve` threw, `startSync` re-threw, and the
+ * dispatcher rendered the caught value into `X_CLI_UNEXPECTED`'s cause —
+ * `cause: Error: Failed to start server. Is port 4000 in use?`, `fix: x doctor --json`, from a
+ * command that had just printed `web listening on 3999`. Three defects in one output: an
+ * unstable code, a caught value rendered into a refusal, and a `fix:` that answered
+ * "no findings — environment is shippable" when run (#F5).
+ */
+class SyncPortInUseError extends UltimateError {
+  constructor(input: { port: number; webPort: number }) {
+    super({
+      code: 'X_PORT_IN_USE',
+      cause: `the sync role binds PORT + 1, so \`x dev --port ${input.webPort}\` needs port ${input.port} and something is already listening on it`,
+      fix: `x dev --port ${neighbouringPort(input.webPort)}   # or free port ${input.port}: lsof -nP -iTCP:${input.port} -sTCP:LISTEN`,
+      meta: { port: input.port, webPort: input.webPort },
+    });
+  }
+}
+
+/**
+ * What a failed `listenSyncNode` really was, ASKED rather than read off the caught value: the
+ * thrown thing is `Bun.serve`'s own English and interpolating it into a `cause:` is what
+ * `scripts/catch-render.ts` refuses. `undefined` means "not a taken port" and the original value
+ * is re-thrown untouched — a catch-all that renamed every listener failure would be worse than
+ * the bare one it replaced.
+ *
+ * `probe` is injected so a test can be exactly "the port was taken" without racing a real socket.
+ */
+export async function syncBindRefusal(
+  webPort: number,
+  port: number,
+  probe: (value: number) => Promise<boolean> = portFree,
+): Promise<UltimateError | undefined> {
+  if (await probe(port)) return undefined;
+  return new SyncPortInUseError({ port, webPort });
+}
+
 /**
  * The port the sync node listens on. `PORT + 1`, and `0` stays `0` — the kernel picks, and adding
  * one to it would pick a specific port instead.
@@ -131,8 +172,9 @@ export async function startSync(options: StartRolesOptions): Promise<RunningSync
     }),
   });
   await node.start();
+  const port = syncPortFor(options.port);
   try {
-    const listener = listenSyncNode(node, { port: syncPortFor(options.port) });
+    const listener = listenSyncNode(node, { port });
     return {
       url: listener.url,
       stop: async () => {
@@ -142,6 +184,8 @@ export async function startSync(options: StartRolesOptions): Promise<RunningSync
     };
   } catch (error) {
     await node.stop();
+    const refusal = await syncBindRefusal(options.port, port);
+    if (refusal !== undefined) throw refusal;
     throw error;
   }
 }

package/src/error-catalog.ts

@@ -30,6 +30,7 @@ export const CATALOG_PACKAGES = [
   '@ultimat3/manifest',
   '@ultimat3/mcp',
   '@ultimat3/money',
+  '@ultimat3/notify',
   '@ultimat3/policy',
   '@ultimat3/pwa',
   '@ultimat3/query',

package/src/error-codes.ts

@@ -49,9 +49,20 @@ export const CLI_OWNED_ERROR_CODES = [
   // reading — the hole that let `scripts/` hold seven type errors under a green gate.
   'X_PACKAGE_UNREFERENCED',
   'X_RELEASE_VERSION_SKEW',
+  // The framework's own tables, refused by name rather than by the driver's rejection: a raw
+  // `permission denied for schema public` says which statement failed and neither which framework
+  // table it was creating nor which package wants it.
+  'X_FRAMEWORK_SCHEMA_FAILED',
   'X_STORAGE_UNWRITABLE',
   'X_STORAGE_SECRET_DEV',
   'X_MANIFEST_STALE',
+  // The other half of the same file, and the one that was silence: `x manifest` writes
+  // `x.manifest.json`, `AGENTS.md` tells an agent that facts live in it, `x dev` prints its path —
+  // and nothing ever ran the command, so the gate's `manifest` step reported green over a file
+  // that has never existed in any app `x new` produced. Its own code because the repair differs
+  // from both neighbours: `X_MANIFEST_DRIFT` means the committed file disagrees with the code and
+  // `X_MANIFEST_STALE` means `openapi.json` does; this one means there is nothing there at all.
+  'X_MANIFEST_MISSING',
   'X_BUDGET_UNMEASURED',
   // The other half of #271, and the half no runtime can raise: a route reads a live hook and boots
   // no module in a browser, so its rows have nowhere to arrive and the page renders its loading
@@ -146,6 +157,14 @@ export const CLI_OWNED_ERROR_CODES = [
  */
 export const CLI_BORROWED_ERROR_CODES = [
   'X_NOT_IMPLEMENTED',
+  // `@ultimat3/policy`'s, and the gate's `policy` step reports it verbatim — cause, fix and the
+  // nearest declared name all come from `permissionUnknown`. A CLI-owned twin would be a second
+  // wording for the condition `can()` already refuses at run time, and the two would drift.
+  'X_PERMISSION_UNKNOWN',
+  // `@ultimat3/db`'s, reported by `x doctor`'s database probe with that package's own two-branch
+  // fix. The CLI is the half that asks BEFORE a pool is opened; the condition and the remedy are
+  // both db's, and a CLI twin would be one unreachable database with two names.
+  'X_DB_UNAVAILABLE',
   'X_CONFIG_INVALID',
   'X_ENV_MISSING',
   'X_ENV_EXAMPLE_DRIFT',
@@ -183,6 +202,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_ERROR_CODE_UNDOCUMENTED: 'a shipped error code has no row in the error reference',
   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_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',
   X_CLI_UNEXPECTED: 'the CLI itself failed',
@@ -195,6 +215,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_PACKAGE_UNREFERENCED: 'a published workspace is not in the root tsconfig build graph',
   X_RELEASE_VERSION_SKEW: 'a workspace is not at the lockstep version',
   X_MANIFEST_STALE: 'openapi.json is stale',
+  X_MANIFEST_MISSING: 'the app ships no x.manifest.json',
   X_BUDGET_UNMEASURED: 'a route declares a budget the build never measured',
   X_LIVE_ROUTE_NO_ISLAND: 'a route reads live rows and boots nothing that could receive them',
   X_BUILD_FAILED: 'x build failed',