@ultimat3/cli 11.3.0 → 12.0.0

package/CLAUDE.md

@@ -14,7 +14,7 @@ Tier 5. May import tiers 0–4. Nothing imports this except `create-ultimate`.
 | Bare subcommands | `CommandSpec.defaultSubcommand`, **declared**. The parser answered `subcommands[0]` until 1.2.0, so `x db` ran `gen` — the migration GENERATOR — because it sorted first, and `x mcp` started a server. A command with no defensible default declares none and `MissingSubcommandError` refuses the bare form; `parse.test.ts` pins the set at exactly `db` and `mcp`. Its fix is `x help <command>`. Both forms answer now: `--help` is read off the flag loop and `readSubcommand` is SKIPPED when it is set, so `x db --help`, `x mcp --help` and `x pr --help` print usage instead of exiting 1 with this same refusal — which is what they did on every command taking a subcommand until 2026-08 (`parse.test.ts` pins it across the shipped registry) |
 | Closed flag values | a flag whose values are a closed set is READ through a function that refuses the rest — `cmd-build.ts`'s `readTarget`, `cmd-deploy.ts`'s `readMethod`, `cmd-routes.ts`'s `readSurfaceFilter`, `cmd-mcp.ts`'s `isTransport`. `=== 'helm' ? 'helm' : 'compose'` made `x deploy --method helmm` a COMPOSE deploy reporting `method: "compose"`, and `--surface App` reported `0 routes` and exit 0 — a typo and an empty table rendering identically. The set is the framework's own where one exists (`SURFACES` from `@ultimat3/render`), never a list restated here |
 | App root | `CommandSpec.requiresApp`, **enforced by `dispatch.ts`** before `target.run` — the field's doc said so for 17 commands and nothing read it, so the promise was kept only by each command remembering to call `requireAppRoot` itself. Those 17 calls stay (they hand the command its root, and name subcommands the dispatcher cannot see), but the DECLARATION is what decides, ahead of any check a command makes about its own arguments; `--help` is exempt, because `target` is the help command by then |
-| Result helpers | `command.ts`'s `ok()` / `failed()` write `ok` **after** the `extra` spread: the function's name is the verdict and nothing a caller passes can overturn it. Spread last, `failed('verify', '1 of 19 steps failed', { ok: true })` answered `ok: true` and `exitCodeFor` exited **0** on it — a green CI over a red command (`command.test.ts`) |
+| Result helpers | `command.ts`'s `ok()` / `failed()` write `ok` **after** the `extra` spread: the function's name is the verdict and nothing a caller passes can overturn it. Spread last, `failed('verify', '1 of 20 steps failed', { ok: true })` answered `ok: true` and `exitCodeFor` exited **0** on it — a green CI over a red command (`command.test.ts`) |
 | I/O | only `dispatch.ts` renders or exits; commands return `CommandResult` |
 | Staying up | a command still listening when `run` resolves returns `hold` (`hold.ts`), or `bin.ts` exits out from under it |
 | `--json` | every command, no exceptions — same data as the human render |
@@ -80,6 +80,54 @@ source only: a test file's import is not judged, because `packages/*` here decla
 read is its own finding rather than a silent skip — a skipped workspace is a hiding place for the
 very edge the rule is looking for.
 
+`app-permissions.ts` is the `policy` step, and it is the twentieth. Two references in the whole
+framework are bare strings nothing checks — `RoleDef.grants` and `RouteGuard.permission` — while
+`can()` calls `assertPermission` and throws `X_PERMISSION_UNKNOWN` on the first request that
+reaches the route. So `x new` shipped an app that granted `dashboard:read`, required it on
+`/dashboard` and declared it nowhere: HTTP 500 on two of its three routes, from the first `x dev`,
+under a green gate. It reads `roleDefinitions()` and `routeEntries()` after `loadApp` and reports
+each reference `isKnownPermission` refuses — **that predicate and no other**, because it is the one
+`assertPermission` uses, including its rule that an app which has declared NOTHING is not checked
+at all. A gate that disagreed with the process it gates would be worse than none. The cause and the
+`fix:` are `permissionUnknown`'s, so `@ultimat3/policy` owns both wordings; `X_PERMISSION_UNKNOWN`
+is in `CLI_BORROWED_ERROR_CODES`. Its own step rather than a rider on `budgets`, by that step's own
+test: reported there, an authz defect would hand the reader a byte budget (axiom 4). It costs no
+second app load.
+
+`dev-replica.ts` is where read-replica routing is WIRED, and it had to be wired in two places
+because it was opt-in twice. `@ultimat3/db`'s `defaultClient()` is the one composer of
+`replicatedClient(primary, replica)` from `DATABASE_REPLICA_URL`, and it runs only from
+`baseClient()` — "the client an app installed none for" — while every process the framework boots
+calls `setDbClient` in `dev-queue.ts`, so no booted process had ever read that variable. Routing
+also needs an open `withReplicaReads` scope, and nothing opened one. `startDb` now installs the
+replicated pair as the AMBIENT client while keeping the primary for everything this boot does
+itself (`applySchema`, the queue's `PgExecutor`, `ping`, `close` — DDL and a claim are writes), and
+`cmd-dev.ts` / `serve.ts` prepend one middleware frame that opens the scope per request. Both
+halves are `undefined`/empty with no replica configured, and an EMBEDDED binding never gets one:
+PGlite has no standby. Not `@ultimat3/http`'s pipeline, which would make the HTTP tier know what a
+database is; the boot is the only tier that may know about a request and a pool.
+
+`port-probe.ts` is the one `portFree`, because two commands ask it and must not disagree:
+`x doctor` reports it as a finding for BOTH ports `x dev` binds — the web port and the `PORT + 1`
+sync port, each labelled with the role that wants it — and `startSync` asks it after a failed
+`listenSyncNode` so a taken neighbour is `X_PORT_IN_USE` rather than `X_CLI_UNEXPECTED` over
+`Bun.serve`'s own English rendered into a `cause:`. It is ASKED, never read off the caught value,
+which is what `scripts/catch-render.ts` refuses; anything else the listener failed on is re-thrown
+untouched. `x doctor` also probes `DATABASE_URL` with a real `select 1` through
+`@ultimat3/db`'s `checkDb` — a TCP connect answers "reachable" for a running server with wrong
+credentials, which is the case an operator most needs told about — and reports `X_DB_UNAVAILABLE`
+with that package's own two-branch fix. An EMBEDDED binding is not probed: that lock is `x dev`'s.
+
+`i18n-index.ts` is the one writer of an app's `packages/i18n/src/index.ts`, shared by `x g` and
+`x i18n add|sync`. A catalog on disk and a SELECTABLE locale were two different sets: `x i18n add
+fr` wrote the file, exited 0, and left `x verify --only i18n` red with `X_CATALOG_UNREGISTERED`
+whose `fix:` named an edit that had already been made — an agent following it verbatim changes
+nothing and loops forever, on the command whose whole job is adding a locale. `unregisteredFix`
+(`i18n-registration.ts`) is the other half: one code over two causes, so where the index EXISTS and
+does not name the locale's own `catalogs/<tag>.json` import, the CLI substitutes a fix that
+performs the registration. The package's own "move the `defineCatalogs()` call" line still stands
+for the cause it was written for.
+
 `app-agents-md.ts` is why the `manifest` step declares no `applies` at all. The drift half needs
 a committed `x.manifest.json` to compare against, but `AGENTS.md` is required of every repo the
 gate runs in — so the step always has a question to answer, and gating both halves on the file
@@ -655,6 +703,7 @@ hand-written layout and `readMigrations` skips it — read as a migration it sor
 | `dev-assets.ts` | the image pipeline's only HTTP surface: `/icons/*` and `/media/*` |
 | `favicon.ts` | `/favicon.ico`: the app's own file, and the bytes the framework answers with when there is none |
 | `dev-hooks.ts` | the pipeline's `authorize` seam, decided from the app's own `Policy` objects |
+| `dev-replica.ts` | which boot gets a standby, and the one middleware frame that opens the read scope |
 | `dev-roles.ts` | `--role` selection plus start/stop for `web`, `sync`, `worker`, `scheduler` |
 | `dev-dashboard.ts` | the `DevSources` hooks only this process can answer, and the two CLI panels |
 | `dev-traces.ts` | core's spans → the `/_x` timeline's request traces |

package/README.md

@@ -11,7 +11,7 @@ Commands and the `x verify` step count, `As of 2026-08`:
 | `x new <name>` | scaffolds the monorepo | interactive-free; auth, seeded DB, example route |
 | `x dev` | every role in one process | embedded Postgres/events/storage, `/_x` mounted |
 | `x build --target docker\|binary\|static` | one artifact | `ROLE` selects behaviour at start |
-| `x verify` | **the gate** | 19 named steps, each with pass/fail + duration |
+| `x verify` | **the gate** | 20 named steps, each with pass/fail + duration |
 | `x g <primitive> <name>` | scaffolds a primitive **with a passing test** | never a TODO stub |
 | `x db gen\|migrate\|reset\|branch\|backfill` | everything DB | `branch` = copy-on-write clone + preview URL; `backfill` dry-runs unless `--write`. `x db studio` is **planned** — it parses, and exits `X_NOT_IMPLEMENTED` naming `/_x`'s db panel |
 | `x mcp serve` | `@ultimat3/mcp`'s 13 dev tools, over stdio or HTTP | one catalog, one scope set, both transports |
@@ -47,15 +47,15 @@ X_DB_DRIFT: schema differs from migrations
 
 ```sh
 x verify --json
-# {"ok":false,"command":"verify","summary":"1 of 19 steps failed","steps":[...]}
+# {"ok":false,"command":"verify","summary":"1 of 20 steps failed","steps":[...]}
 ```
 
 ## `x verify` steps
 
 `typecheck lint boundaries filesize package-shape errors unit contract live job e2e eval drift
-contract-diff budgets seo i18n manifest roadmap`
+contract-diff budgets seo i18n policy manifest roadmap`
 
-Nineteen, in cost order, defined once as `VERIFY_STEP_NAMES` (`verify-step.ts`) — the summary
+Twenty, in cost order, defined once as `VERIFY_STEP_NAMES` (`verify-step.ts`) — the summary
 count above is projected from that list, and the framework repo's own gate (`bun run verify`)
 runs exactly it. A step with nothing to check here reports as skipped, never as
 passed. Never bails early: an agent fixing three things needs all three findings from one run.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "11.3.0",
+  "version": "12.0.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -37,33 +37,33 @@
   },
   "dependencies": {
     "@babel/core": "^7.28.4",
-    "@ultimat3/action": "11.3.0",
-    "@ultimat3/admin": "11.3.0",
-    "@ultimat3/ai": "11.3.0",
-    "@ultimat3/auth": "11.3.0",
-    "@ultimat3/cache": "11.3.0",
-    "@ultimat3/core": "11.3.0",
-    "@ultimat3/db": "11.3.0",
-    "@ultimat3/entity": "11.3.0",
-    "@ultimat3/flags": "11.3.0",
-    "@ultimat3/http": "11.3.0",
-    "@ultimat3/i18n": "11.3.0",
-    "@ultimat3/jobs": "11.3.0",
-    "@ultimat3/mail": "11.3.0",
-    "@ultimat3/manifest": "11.3.0",
-    "@ultimat3/mcp": "11.3.0",
-    "@ultimat3/money": "11.3.0",
-    "@ultimat3/policy": "11.3.0",
-    "@ultimat3/pwa": "11.3.0",
-    "@ultimat3/query": "11.3.0",
-    "@ultimat3/realtime": "11.3.0",
-    "@ultimat3/render": "11.3.0",
-    "@ultimat3/schema": "11.3.0",
-    "@ultimat3/scraping": "11.3.0",
-    "@ultimat3/seo": "11.3.0",
-    "@ultimat3/storage": "11.3.0",
-    "@ultimat3/testing": "11.3.0",
-    "@ultimat3/time": "11.3.0",
+    "@ultimat3/action": "12.0.0",
+    "@ultimat3/admin": "12.0.0",
+    "@ultimat3/ai": "12.0.0",
+    "@ultimat3/auth": "12.0.0",
+    "@ultimat3/cache": "12.0.0",
+    "@ultimat3/core": "12.0.0",
+    "@ultimat3/db": "12.0.0",
+    "@ultimat3/entity": "12.0.0",
+    "@ultimat3/flags": "12.0.0",
+    "@ultimat3/http": "12.0.0",
+    "@ultimat3/i18n": "12.0.0",
+    "@ultimat3/jobs": "12.0.0",
+    "@ultimat3/mail": "12.0.0",
+    "@ultimat3/manifest": "12.0.0",
+    "@ultimat3/mcp": "12.0.0",
+    "@ultimat3/money": "12.0.0",
+    "@ultimat3/policy": "12.0.0",
+    "@ultimat3/pwa": "12.0.0",
+    "@ultimat3/query": "12.0.0",
+    "@ultimat3/realtime": "12.0.0",
+    "@ultimat3/render": "12.0.0",
+    "@ultimat3/schema": "12.0.0",
+    "@ultimat3/scraping": "12.0.0",
+    "@ultimat3/seo": "12.0.0",
+    "@ultimat3/storage": "12.0.0",
+    "@ultimat3/testing": "12.0.0",
+    "@ultimat3/time": "12.0.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/cmd-dev.ts

@@ -26,6 +26,7 @@ import { devDashboardRoutes, devPanels } from './dev-dashboard';
 import { clearLock, preflight, writeLock } from './dev-lock';
 import { createStatementLedger } from './dev-n-plus-one';
 import { appRoutes } from './dev-render';
+import { replicaOverrides } from './dev-replica';
 import type { RunningRoles } from './dev-roles';
 import { DEV_BINDING, DEV_ROLES, selectRoles, startRoles } from './dev-roles';
 import type { RunningServices } from './dev-runtime';
@@ -195,6 +196,7 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     ...appRoutes({ buildId, resolveIsland: (file) => state.islands.resolverFor(file) }),
   ];
 
+  const replicaOverride = replicaOverrides(undefined, services.db, options.env);
   const running = await startRoles({
     roles: options.roles ?? DEV_ROLES,
     port: options.port,
@@ -223,6 +225,10 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     // diagnostic to call.
     devNotices: (ctx: RequestContext): readonly OverlayNotice[] =>
       statements.repeatsFor(asCtx(ctx)).map(loopFacts).map(loopNotice),
+    // The read-replica scope, opened per request. Absent for every app that names no
+    // `DATABASE_REPLICA_URL` — which is every embedded boot by construction, since PGlite has no
+    // standby — so this key does not exist on a homework app's boot at all.
+    ...(replicaOverride === undefined ? {} : { overrides: replicaOverride }),
   });
 
   const stopWatching = watchApp(options.root, (file) => {

package/src/cmd-doctor.ts

@@ -5,6 +5,7 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { ERROR_DOCS_URL, tryResolveEnvironment, usesDevCursorSecret } from '@ultimat3/core';
+import { checkDb, createPostgresClient } from '@ultimat3/db';
 import { STORAGE_SIGNING_SECRET_KEY, usesDevStorageSecret } from '@ultimat3/storage';
 import { findAppRoot, REQUIRED_BUN, versionAtLeast } from './app-root';
 import type { CliCommand, CommandContext } from './command';
@@ -15,6 +16,7 @@ import { intFlagOr, neighbouringPort, PORT_RANGE } from './flag-number';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import type { ParsedArgs } from './parse';
+import { portFree } from './port-probe';
 
 /**
  * The injection seam `runDoctor` reads instead of the environment. Not a semver surface —
@@ -40,6 +42,16 @@ export interface DoctorProbe {
   readonly production: boolean;
   exists(relativePath: string): boolean;
   portFree(port: number): Promise<boolean>;
+  /**
+   * Is the configured database reachable, and what refused? `null` is "reachable, or there is
+   * nothing external to reach" — an unset `DATABASE_URL` is embedded PGlite, which `x dev` owns
+   * and which a probe would take the single-writer lock on.
+   *
+   * Until this existed `x doctor` answered "no findings — environment is shippable" against
+   * `DATABASE_URL=postgres://nope:nope@localhost:5432/nope`, while `x db migrate` on the same env
+   * correctly answered `X_DB_UNAVAILABLE` (#F5).
+   */
+  database(): Promise<Finding | null>;
   drift(): Promise<readonly Finding[]>;
   /**
    * The other half of the migrations directory: a newest migration with no `.snapshot.json`, which
@@ -59,6 +71,39 @@ export const OFFLINE_FALLBACK = 'apps/web/app/offline.tsx';
 /** The port `x dev` binds by default, so the probe answers about the port the developer will use. */
 const DEFAULT_DOCTOR_PORT = 3000;
 
+/**
+ * Both ports `x dev` binds, each labelled with the role that wants it. `x dev --port 3999` printed
+ * `web listening on 3999`, then died on 4000 as `X_CLI_UNEXPECTED` with a caught `Error` rendered
+ * into its cause — and `x doctor --port 3999` answered "no findings", because it probed the web
+ * port and only the web port (#F5). The neighbouring port is not an implementation detail an
+ * operator can ignore: `docker-compose.prod.yml` publishes `3001:3001` from it and `docker/helm`
+ * derives `PORT = .port - 1` from it, so it is part of the contract `x dev` runs by.
+ *
+ * The suggested port moves BOTH: `x dev --port N` occupies N and N+1, so a free N beside a taken
+ * N+1 is still not a runnable command.
+ */
+async function portFindings(probe: DoctorProbe): Promise<readonly Finding[]> {
+  const wanted = [
+    { port: probe.port, role: 'web' },
+    { port: neighbouringPort(probe.port), role: 'sync' },
+  ] as const;
+  const findings: Finding[] = [];
+  for (const entry of wanted) {
+    if (await probe.portFree(entry.port)) continue;
+    findings.push(
+      finding(
+        'X_PORT_IN_USE',
+        `port ${entry.port} is already listening, and \`x dev --port ${probe.port}\` binds it for the ${entry.role} role`,
+        // Unchanged, and deliberately: the neighbour below the top of the range is the one port
+        // `x dev` is guaranteed to accept (`X_CLI_BAD_FLAG` otherwise), which is what
+        // `cmd-doctor.test.ts` pins by parsing this line with `x dev`'s own flag reader.
+        `x dev --port ${neighbouringPort(probe.port)}`,
+      ),
+    );
+  }
+  return findings;
+}
+
 /**
  * Ordered cheapest-first so the first failure is usually the root cause: a wrong Bun explains
  * every other symptom, and running outside an app explains the rest.
@@ -120,15 +165,7 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
       ),
     );
   }
-  if (!(await probe.portFree(probe.port))) {
-    findings.push(
-      finding(
-        'X_PORT_IN_USE',
-        `port ${probe.port} is already listening`,
-        `x dev --port ${neighbouringPort(probe.port)}`,
-      ),
-    );
-  }
+  findings.push(...(await portFindings(probe)));
   // `@ultimat3/pwa`'s own codes, not CLI twins of them. `X_PWA_NO_ICON_SOURCE` and
   // `X_PWA_NO_FALLBACK` used to be declared here for the same two conditions the package already
   // names — two codes for one condition, one of them registered by nobody, so `x errors explain`
@@ -156,6 +193,8 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
       ),
     );
   }
+  const database = await probe.database();
+  if (database !== null) findings.push(database);
   findings.push(...(await probe.drift()));
   // Last, and it is why `X_CLI_UNEXPECTED`'s `fix: x doctor --json` is not a dead end on the path an
   // author reaches it from: `x db gen` throwing `X_MIGRATION_SNAPSHOT_MISSING` used to be a
@@ -176,15 +215,33 @@ export const doctorPort = (args: ParsedArgs): number =>
     DEFAULT_DOCTOR_PORT,
   );
 
-const portFree = async (port: number): Promise<boolean> => {
+/**
+ * A real `select 1` through the app's own driver, not a TCP connect: a running Postgres with the
+ * wrong credentials or a database that does not exist accepts the socket and refuses the session,
+ * which is the case an operator most needs told about before a deploy.
+ *
+ * The pool is CLOSED on every path — this command exits, and a held pool is a connection slot the
+ * next `x db migrate` cannot have.
+ */
+async function probeDatabase(url: string | undefined): Promise<Finding | null> {
+  if (url === undefined || url.trim() === '') return null;
+  const client = createPostgresClient({ url, applicationName: 'x-doctor' });
   try {
-    const server = Bun.serve({ port, fetch: () => new Response('') });
-    await server.stop(true);
-    return true;
-  } catch {
-    return false;
+    const report = await checkDb(client);
+    if (report.ok) return null;
+    // `DbHealthReport.error` is `checkDb`'s own rendering of what refused, never this file's — the
+    // caught value is `checkDb`'s to read, and it is the one function that already reads it safely.
+    return finding(
+      'X_DB_UNAVAILABLE',
+      `DATABASE_URL does not answer \`select 1\`: ${report.error ?? 'no reason reported'}`,
+      // `dbUnavailable`'s own two branches, verbatim: a second wording for one condition is two
+      // answers to "what do I do", and this one is reached first, before any command opens a pool.
+      'set DATABASE_URL to a reachable Postgres url, or run `x dev` to use the embedded PGlite',
+    );
+  } finally {
+    await client.close();
   }
-};
+}
 
 export function probeFor(cwd: string, bunVersion: string, port: number): DoctorProbe {
   const root = findAppRoot(cwd)?.dir;
@@ -204,6 +261,7 @@ export function probeFor(cwd: string, bunVersion: string, port: number): DoctorP
     production: tryResolveEnvironment() === 'production',
     exists: (relativePath) => (root === undefined ? false : existsSync(join(root, relativePath))),
     portFree,
+    database: () => probeDatabase(process.env['DATABASE_URL']),
     drift: async () => (root === undefined ? [] : checkSourceDrift(root)),
     snapshots: async () => (root === undefined ? [] : checkMigrationSnapshots(root)),
   };

package/src/cmd-errors.ts

@@ -94,6 +94,12 @@ export const errorsCommand: CliCommand = {
     // which names `<CODE>` and hands back a real invocation. `list` would silently print 200 rows
     // to a caller who meant to explain one — see `MissingPositionalError`'s own note.
     defaultSubcommand: 'explain',
+    // `x errors X_PERMISSION_UNKNOWN` is the form every reader tries first — `x help` prints
+    // `errors  an X_* code, explained`, which reads as exactly that — and it answered
+    // `X_CLI_UNKNOWN_COMMAND … fix: x help`, which leads back to the line that suggested it.
+    // Safe to declare here and nowhere else so far: the only thing that is not `explain` or
+    // `list` in this slot is a code, and a near miss of either is still refused (#F16).
+    defaultSubcommandTakesPositional: true,
   },
   // `async` is load-bearing: a synchronous throw would escape every caller that awaits the
   // promise this signature promises, including the dispatcher's own error path.

package/src/cmd-generate.ts

@@ -11,10 +11,11 @@ import { generate } from './generate-files';
 import { GENERATORS, readKind, readName, readSurface } from './generate-kinds';
 import { containedPath, writeFiles } from './generate-write';
 import { resolveCatalogModule } from './i18n-audit';
+import { syncI18nIndex } from './i18n-index';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import { flagBool, flagList, flagString } from './parse';
-import { CATALOG_ROOT, i18nIndex, resolveLocales } from './templates';
+import { resolveLocales } from './templates';
 
 // One import path for the generator, unchanged by the split: `index.ts`, `x new` and the scaffold
 // fixture reach the kinds, the pure file list and the writer through this module, and a second path
@@ -26,32 +27,6 @@ export { GENERATORS } from './generate-kinds';
 export type { WriteReport } from './generate-write';
 export { dedupe, writeFiles } from './generate-write';
 
-const I18N_INDEX_PATH = 'packages/i18n/src/index.ts';
-
-/**
- * `packages/i18n/src/index.ts` is the one module the app imports catalogs through, and it is
- * written once, at `x new` time, importing whichever locales existed then. A later `x g
- * ... --locales=es` lands `packages/i18n/catalogs/es.json` on disk, but nothing would otherwise
- * teach the index about it — the catalog file would exist with real keys in it and the app could
- * still never select that locale. Every run that wrote at least one file re-derives the FULL
- * locale set from `packages/i18n/catalogs/` — not just the locales this invocation asked for —
- * and rewrites the index to match. Bypasses `writeFiles` on purpose: this file is a projection of
- * the catalog directory, never app-authored content a conflict check should protect. An app with
- * no i18n package (deleted, or never scaffolded) is left alone.
- */
-async function syncI18nIndex(root: string): Promise<void> {
-  const indexAbsolute = containedPath(root, I18N_INDEX_PATH);
-  if (!existsSync(indexAbsolute)) return;
-  const catalogDir = containedPath(root, CATALOG_ROOT);
-  const locales: string[] = [];
-  if (existsSync(catalogDir)) {
-    for await (const entry of new Bun.Glob('*.json').scan({ cwd: catalogDir, absolute: false })) {
-      locales.push(entry.replace(/\.json$/, ''));
-    }
-  }
-  await Bun.write(indexAbsolute, i18nIndex(locales));
-}
-
 export const generateCommand: CliCommand = {
   spec: {
     name: 'g',

package/src/cmd-i18n.ts

@@ -23,6 +23,7 @@ import {
   serializeCatalog,
   syncCatalog,
 } from './i18n-audit';
+import { syncI18nIndex } from './i18n-index';
 import {
   checkRegistration,
   loudMiss,
@@ -179,6 +180,12 @@ async function runAdd(root: string, ctx: CommandContext): Promise<CommandResult>
   const from = resolveDefaultLocale(app.defaultLocale, catalogs);
   const seeded = seedCatalog(from === undefined ? {} : (catalogs[from] ?? {}));
   await writeNewCatalog(join(root, path), locale, serializeCatalog(seeded));
+  // The second half of adding a locale, and without it this command SHIPPED A RED GATE: the file
+  // landed, `packages/i18n/src/index.ts` still said `locales: { en }`, and `x verify --only i18n`
+  // answered `X_CATALOG_UNREGISTERED` with a fix naming an edit that had already been made. Same
+  // writer `x g --locales` already uses, so a catalog on disk and a selectable locale can never be
+  // two different sets (#F4).
+  const registered = await syncI18nIndex(root);
 
   const keys = catalogKeys(seeded).length;
   return {
@@ -189,7 +196,9 @@ async function runAdd(root: string, ctx: CommandContext): Promise<CommandResult>
     command: 'i18n',
     summary: msg('cli.i18n.added', { locale, keys, from: from ?? locale }),
     findings: app.findings,
-    data: { locale, from: from ?? locale, keys, path },
+    // `registered` is false only for an app with no `packages/i18n` at all — a fact a caller has
+    // to be able to read, because it is the one case where the locale is on disk and unselectable.
+    data: { locale, from: from ?? locale, keys, path, registered },
   };
 }
 
@@ -250,6 +259,11 @@ async function runSync(root: string, ctx: CommandContext): Promise<CommandResult
     : (catalogs[from] ?? {});
   const { merged, added } = syncCatalog(target, source);
   if (added.length > 0) await Bun.write(join(root, catalogPath(locale)), serializeCatalog(merged));
+  // Unconditional, and not only when keys moved: a catalog that reached disk some other way — a
+  // hand-created file, a `git merge` — is exactly the unregistered locale the gate refuses, and
+  // this is the command its `fix:` names. Re-deriving an index that is already correct writes the
+  // same bytes.
+  const registered = await syncI18nIndex(root);
 
   const total = catalogKeys(merged).length;
   return {
@@ -268,6 +282,7 @@ async function runSync(root: string, ctx: CommandContext): Promise<CommandResult
       added,
       total,
       path: catalogPath(locale),
+      registered,
       // Which of `added` still need a human. Empty on a real merge, where every value is a real
       // string copied from the default locale — `--json` must be able to tell the two apart.
       placeholders: seeded ? added : [],

package/src/dev-queue.ts

@@ -8,6 +8,7 @@ import {
   type PostgresIdempotencyStore,
   postgresIdempotencyStore,
   resetIdempotency,
+  SQL_AUDIT_TABLE,
   SQL_IDEMPOTENCY_TABLE,
   setIdempotencyStore,
 } from '@ultimat3/action';
@@ -36,12 +37,19 @@ import {
   setJobDriver,
   setJobsFacade,
 } from '@ultimat3/jobs';
+import { attachReplica, type ReplicaEnv, replicaUrlFor } from './dev-replica';
 import type { DevServices } from './dev-services';
 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 +70,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 +91,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 };
 }
 
 /**
@@ -111,6 +133,13 @@ async function applySchema(client: DevDbClient): Promise<void> {
   for (const ddl of [
     SQL_JOBS_TABLE,
     SQL_IDEMPOTENCY_TABLE,
+    // The DDL only, and deliberately NO `setAuditSink` beside `setIdempotencyStore` below: there
+    // is no default audit sink on purpose, so `X_AUDIT_SINK_MISSING` keeps firing at boot for an
+    // app that declares `audit: true` and installs none. Applying the table without installing a
+    // sink is the same call `SQL_RATE_LIMIT_TABLE` already makes — one round trip at boot on a
+    // possibly-unused table, against `postgresAuditSink` failing its first write with
+    // `relation "x_audit" does not exist`.
+    SQL_AUDIT_TABLE,
     SQL_RATE_LIMIT_TABLE,
     SQL_AUTH_LIMIT_TABLES,
   ]) {
@@ -148,7 +177,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 +204,7 @@ async function startJobs(client: DevDbClient, overrides?: RuntimeOverrides): Pro
     outbox,
     events,
     idempotency,
-    stop: () => releaseQueue(client, driver),
+    stop: () => releaseQueue(client, driver, replica),
   };
 }
 
@@ -184,7 +217,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 +230,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 +245,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.
     }