@ultimat3/cli 28.0.0 → 29.0.0

package/CLAUDE.md

@@ -98,7 +98,7 @@ Commands: `bun test packages/cli` (from the repo root — the test preload lives
 | `app-config-load.ts` | the ONE reader of an app's `app.config.ts`: `loadAppConfig(root)` — the `config` export through core's `defineConfig`, so validated and default-merged; `undefined` with no file; no `config` object is `X_CONFIG_INVALID`. Every boot fact (`app-auth.ts`, `theme-boot.ts`, `site-config.ts`, `pwa-artifacts.ts`, …) reads a section off it, and `startServices` loads it once. An `import(` of the config module anywhere else is `X_CONFIG_IMPORT_OUTSIDE_LOADER` (`scripts/lib/config-import.ts`) |
 | `theme-brand.ts` | the ONE reader of an app's theme: `export const brand` in `apps/web/shared/theme.ts` (ui's `defineTheme`), inlined after the surface stylesheet with its hash in `style-src`; none → nothing emitted |
 | `runtime-jobs.ts` / `runtime-realtime.ts` / `runtime-notify-retention.ts` / `runtime-cache.ts` / `runtime-purge.ts` / `runtime-replica.ts` | `app.config.ts` sections the boot obeys (`*Of(config)` over the one loaded config), and what each wires |
-| `runtime-jobs.ts` (queues) | union of `jobs.queues` + registered queues; `WORKER_QUEUES` set = the EXACT set, `jobs.worker.queue-unserved` names the rest. `jobs.concurrency` passes as written |
+| `runtime-jobs.ts` (queues) | `jobs.queues` ∪ registered queues; `WORKER_QUEUES` = the EXACT set, each entry in that union or `X_WORKER_QUEUE_UNKNOWN`; `queue-unserved` warns the rest |
 | `serve-retire.ts` / `dev-restart-retire.ts` | the worker retire — `stop()`: claim nothing, abort nothing — on SIGUSR2 under `runRole` (armed before boot, then drain + exit 0; none on win32; the chart's `roles.worker.retireSeconds` preStop sends it), and before a supervised `x dev` restart's drain (#677) |
 | `role-start.ts` / `role-start-types.ts` / `role-realtime.ts` | `--role` selection and start/stop for `web`, `sync`, `worker`, `scheduler`; `realtime.enabled: false` drops `sync` and `replicator` |
 | `role-wake.ts` | the worker's LISTEN session (`@ultimat3/jobs`' `startQueueWake`) — worker role only, only over a client that `canListen` — and `queue_wake_live` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "28.0.0",
+  "version": "29.0.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -30,7 +30,7 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.3"
+    "bun": ">=1.4.4"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
@@ -38,34 +38,34 @@
     "dev": "bun run src/bin.ts dev"
   },
   "dependencies": {
-    "@babel/core": "^8.0.1",
-    "@ultimat3/action": "28.0.0",
-    "@ultimat3/admin": "28.0.0",
-    "@ultimat3/ai": "28.0.0",
-    "@ultimat3/auth": "28.0.0",
-    "@ultimat3/cache": "28.0.0",
-    "@ultimat3/core": "28.0.0",
-    "@ultimat3/db": "28.0.0",
-    "@ultimat3/entity": "28.0.0",
-    "@ultimat3/flags": "28.0.0",
-    "@ultimat3/http": "28.0.0",
-    "@ultimat3/i18n": "28.0.0",
-    "@ultimat3/jobs": "28.0.0",
-    "@ultimat3/mail": "28.0.0",
-    "@ultimat3/manifest": "28.0.0",
-    "@ultimat3/mcp": "28.0.0",
-    "@ultimat3/money": "28.0.0",
-    "@ultimat3/notify": "28.0.0",
-    "@ultimat3/policy": "28.0.0",
-    "@ultimat3/pwa": "28.0.0",
-    "@ultimat3/query": "28.0.0",
-    "@ultimat3/realtime": "28.0.0",
-    "@ultimat3/render": "28.0.0",
-    "@ultimat3/schema": "28.0.0",
-    "@ultimat3/seo": "28.0.0",
-    "@ultimat3/storage": "28.0.0",
-    "@ultimat3/testing": "28.0.0",
-    "@ultimat3/time": "28.0.0",
-    "babel-preset-solid": "^1.9.15"
+    "@babel/core": "^8.0.7",
+    "@ultimat3/action": "29.0.0",
+    "@ultimat3/admin": "29.0.0",
+    "@ultimat3/ai": "29.0.0",
+    "@ultimat3/auth": "29.0.0",
+    "@ultimat3/cache": "29.0.0",
+    "@ultimat3/core": "29.0.0",
+    "@ultimat3/db": "29.0.0",
+    "@ultimat3/entity": "29.0.0",
+    "@ultimat3/flags": "29.0.0",
+    "@ultimat3/http": "29.0.0",
+    "@ultimat3/i18n": "29.0.0",
+    "@ultimat3/jobs": "29.0.0",
+    "@ultimat3/mail": "29.0.0",
+    "@ultimat3/manifest": "29.0.0",
+    "@ultimat3/mcp": "29.0.0",
+    "@ultimat3/money": "29.0.0",
+    "@ultimat3/notify": "29.0.0",
+    "@ultimat3/policy": "29.0.0",
+    "@ultimat3/pwa": "29.0.0",
+    "@ultimat3/query": "29.0.0",
+    "@ultimat3/realtime": "29.0.0",
+    "@ultimat3/render": "29.0.0",
+    "@ultimat3/schema": "29.0.0",
+    "@ultimat3/seo": "29.0.0",
+    "@ultimat3/storage": "29.0.0",
+    "@ultimat3/testing": "29.0.0",
+    "@ultimat3/time": "29.0.0",
+    "babel-preset-solid": "^1.9.16"
   }
 }

package/src/app-root.ts

@@ -36,7 +36,7 @@ export const MANIFEST_FILE = 'x.manifest.json';
  * declared supported would hang on graceful shutdown the moment its database went away. The full
  * measurement is in `.github/actions/setup/action.yml`; read it before lowering this.
  */
-export const REQUIRED_BUN = '1.4.3';
+export const REQUIRED_BUN = '1.4.4';
 
 export interface AppRoot {
   readonly dir: string;

package/src/cmd-deploy-compose.ts

@@ -84,7 +84,16 @@ export function composeStrategies(text: string | undefined): ReadonlyMap<string,
   }
   const services = isRecord(parsed) ? parsed['services'] : undefined;
   if (!isRecord(services)) return new Map();
-  return new Map(SERVING_ROLES.map((role) => [role, strategyOf(services[role])]));
+  const strategies = new Map<string, ComposeStrategy>(
+    SERVING_ROLES.map((role) => [role, strategyOf(services[role])]),
+  );
+  if (Object.hasOwn(services, 'replicator')) {
+    strategies.set('replicator', {
+      kind: 'stop-first',
+      why: 'the replicator is a singleton: the old process must stop before its replacement starts',
+    });
+  }
+  return strategies;
 }
 
 /** The compose file at `path`, or `undefined` when there is none to read. */

package/src/cmd-deploy-start-first.ts

@@ -1,6 +1,7 @@
 // One compose role rolled start-first: the new containers come up beside the old ones, are waited
-// on until healthy, and only then are the old ones stopped and removed. Converges on the declared
-// replica count, so a rerun after a half-finished deploy finishes it rather than adding replicas.
+// on until healthy, and only then are the old ones stopped and removed, converging on the declared
+// replica count. A replica is the requested version only when compose's config hash AND the image
+// it runs BOTH match: a tag republished under the same name leaves that hash untouched.
 
 import type { ExecOptions, Runner } from './exec';
 
@@ -13,7 +14,13 @@ export const COMPOSE_WAIT_TIMEOUT_SECONDS = 300;
 
 /** The label compose stamps on each container: the hash of the service definition it was made from. */
 const CONFIG_HASH = 'com.docker.compose.config-hash';
-const INSPECT_FORMAT = `{{.Id}} {{.Created}} {{index .Config.Labels "${CONFIG_HASH}"}}`;
+
+/**
+ * One `docker inspect` reads BOTH facts a replica carries: the definition it was made from (the
+ * config hash) and the build it runs (the image id). One call, one format string — two calls could
+ * describe two different moments, and the pair would be a fiction.
+ */
+const INSPECT_FORMAT = `{{.Id}} {{.Created}} {{index .Config.Labels "${CONFIG_HASH}"}} {{.Image}}`;
 
 /** The `up` that starts the new replicas beside the running ones; `--no-recreate` keeps the old. */
 export function startFirstUp(
@@ -63,42 +70,68 @@ const linesOf = (stdout: string): readonly string[] =>
 const hashOf = (stdout: string): string | undefined => linesOf(stdout)[0]?.split(/\s+/)[1];
 
 /**
- * The running containers split by the definition they were made from: `current` already runs the
- * one being deployed (newest first), `stale` anything else. A container `inspect` did not describe
- * is stale — stopping one too many is a restart, keeping one too many is the old build serving.
+ * The running containers split by the TWO facts a replica carries: `current` already runs the one
+ * being deployed (newest first), `stale` anything else. A container `inspect` did not describe is
+ * stale — stopping one too many is a restart, keeping one too many is the old build serving.
+ *
+ * BOTH facts must match: compose's config hash (the definition) AND the image id (the build). The
+ * hash alone is not enough — a tag republished under the same name leaves the compose file, and
+ * with it that hash, untouched, so the previous build would hash-match and the deploy would report
+ * a rollout it never did.
+ *
+ * A requested image whose id could not be resolved is UNKNOWN, and unknown is never read as
+ * "unchanged": every replica is then stale — the safe direction, the role is rolled and compose
+ * fetches the image during the `up`.
  */
 function partition(
   running: readonly string[],
   inspected: string,
   want: string,
+  wantImage: string | undefined,
 ): { readonly current: readonly string[]; readonly stale: readonly string[] } {
   const described = new Map(
     linesOf(inspected).map((line) => {
-      const [id = '', created = '', hash = ''] = line.split(/\s+/);
-      return [id, { created, hash }] as const;
+      const [id = '', created = '', hash = '', image = ''] = line.split(/\s+/);
+      return [id, { created, hash, image }] as const;
     }),
   );
   const facts = running.map((id) => {
     const match = [...described].find(([full]) => full === id || full.startsWith(id));
-    return { id, created: match?.[1].created ?? '', hash: match?.[1].hash };
+    return {
+      id,
+      created: match?.[1].created ?? '',
+      hash: match?.[1].hash,
+      image: match?.[1].image,
+    };
   });
   return {
     current: facts
-      .filter((fact) => fact.hash === want)
+      .filter((fact) => wantImage !== undefined && fact.hash === want && fact.image === wantImage)
       .sort((a, b) => (a.created < b.created ? 1 : -1))
       .map((fact) => fact.id),
-    stale: facts.filter((fact) => fact.hash !== want).map((fact) => fact.id),
+    stale: facts
+      .filter((fact) => wantImage === undefined || fact.hash !== want || fact.image !== wantImage)
+      .map((fact) => fact.id),
   };
 }
 
 /**
- * Start-first for one role. The containers running now are listed and split by compose's config
- * hash against the definition being deployed: those already on it are kept (up to `replicas`,
- * newest first), and only the shortfall is created BESIDE the rest (`--scale running + shortfall
- * --no-recreate`, so compose builds the extra containers from the new definition and leaves the
- * others alone). Everything is waited on until its healthcheck — `/readyz` for web and sync, the
- * scrape port for the others — answers. Only then are the stale containers and any surplus stopped
- * (SIGTERM, then the `stop_grace_period` compose stamped on each as its stop timeout) and removed.
+ * Start-first for one role. The containers running now are listed and split against the version
+ * being deployed: those already on it — compose's config hash AND the image id they run — are kept
+ * (up to `replicas`, newest first), and only the shortfall is created BESIDE the rest (`--scale
+ * running + shortfall --no-recreate`, so compose builds the extra containers from the new
+ * definition and leaves the others alone). Everything is waited on until its healthcheck — `/readyz`
+ * for web and sync, the scrape port for the others — answers. Only then are the stale containers
+ * and any surplus stopped (SIGTERM, then the `stop_grace_period` compose stamped on each as its
+ * stop timeout) and removed.
+ *
+ * The image id is half of what "the version being deployed" means, and the hash cannot carry it:
+ * a tag republished under the same name leaves the compose file, and with it the config hash,
+ * untouched — the hash alone would call the previous build the requested one, the shortfall would
+ * be zero, and the deploy would report a rollout it never did. The requested id is the one the
+ * deploy was ASKED for (the `--image` reference) resolves to on the daemon; a reference that
+ * resolves to nothing is UNKNOWN, and unknown is never read as "unchanged": every container is
+ * then stale and the role is rolled — compose fetches the image during the `up`.
  *
  * Counting the shortfall rather than `running + replicas` is what makes a rerun safe: after a
  * deploy that brought the new containers up and then failed to stop the old, running it again
@@ -113,10 +146,12 @@ export async function runStartFirst(step: {
   readonly role: string;
   readonly base: readonly string[];
   readonly replicas: number;
+  /** The reference the deploy was asked for — the image the plan reports and compose runs. */
+  readonly image: string;
   readonly runner: Runner;
   readonly options: ExecOptions;
 }): Promise<StartFirstOutcome> {
-  const { role, base, replicas, runner, options } = step;
+  const { role, base, replicas, image, runner, options } = step;
   const run = async (command: readonly string[]) => {
     const result = await runner(command, options);
     return { result, failed: { ok: false as const, code: result.code, command } };
@@ -132,10 +167,19 @@ export async function runStartFirst(step: {
   if (!config.result.ok) return config.failed;
   const inspect = await run(['docker', 'inspect', '--format', INSPECT_FORMAT, ...running]);
   if (!inspect.result.ok) return inspect.failed;
+  // The id the REQUESTED reference resolves to on the daemon. Unresolved is UNKNOWN and not a
+  // failure: compose fetches the image during the `up`, so a tag that is not on the daemon yet is
+  // the ordinary case — and unknown must never read as "unchanged" (see `partition`).
+  const resolved = await runner(
+    ['docker', 'image', 'inspect', '--format', '{{.Id}}', image],
+    options,
+  );
+  const wantImage = resolved.ok ? linesOf(resolved.stdout)[0] : undefined;
   const { current, stale } = partition(
     running,
     inspect.result.stdout,
     hashOf(config.result.stdout) ?? '',
+    wantImage,
   );
   const shortfall = Math.max(0, replicas - current.length);
   const up = await run(startFirstUp(base, role, running.length + shortfall));

package/src/cmd-deploy.ts

@@ -236,7 +236,12 @@ export function planDeploy(
     // header documents `IMAGE=… docker compose …` as the way to run it by hand; this is that line,
     // performed.
     env: { IMAGE: image },
-    steps: DEPLOY_ROLES.map((role) => composeStep(composeBase(root), role, strategies.get(role))),
+    steps: DEPLOY_ROLES.flatMap((role) => {
+      const step = composeStep(composeBase(root), role, strategies.get(role));
+      return role === 'backfill' && strategies.has('replicator')
+        ? [composeStep(composeBase(root), 'replicator', strategies.get('replicator')), step]
+        : [step];
+    }),
   };
 }
 
@@ -413,6 +418,10 @@ export const deployCommand: CliCommand = {
               role: step.role,
               base: composeBase(root),
               replicas: step.strategy.replicas,
+              // The reference the deploy was asked for, named here rather than read off
+              // `options.env`: the image the plan reports and the image compose runs must be one
+              // fact, and the roll decides on the id this reference resolves to.
+              image: plan.image,
               runner: ctx.runner,
               options,
             })

package/src/cmd-i18n.ts

@@ -8,7 +8,7 @@
 // would, and `node:path` because Bun exposes no path API to build what either of them takes.
 import { type FileHandle, mkdir, open } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-import { stringField } from '@ultimat3/core';
+import { DEFAULT_LOCALE, stringField } from '@ultimat3/core';
 import type { Catalog } from '@ultimat3/i18n';
 import { auditCatalogs, catalogKeys } from '@ultimat3/i18n';
 import { loadApp } from './app-load';
@@ -26,6 +26,7 @@ import {
   syncCatalog,
 } from './i18n-audit';
 import { syncI18nIndex } from './i18n-index';
+import { localeParityFindings } from './i18n-locale-parity';
 import {
   checkRegistration,
   loudMiss,
@@ -126,8 +127,13 @@ async function runCheck(root: string): Promise<CommandResult> {
   // The runtime question, asked after the file question and never instead of it: a catalog can be
   // complete on disk, used everywhere in source, and reach no registry at all (issue #249).
   const registration = await checkRegistration({ root, catalogs, extraction, ignoreUnused });
+  // The two rules only a comparison with the reference locale can see: a slot one side does not
+  // have, and a string nobody translated. The same call `x verify`'s `i18n` step makes, so the
+  // command and the gate answer about an app with one voice.
+  const parity = localeParityFindings(catalogs);
+  const parityLocales = new Set(parity.map((finding) => finding.meta?.['locale'])).size;
 
-  const findings: Finding[] = [...missingKeyFindings(report), ...registration.findings];
+  const findings: Finding[] = [...missingKeyFindings(report), ...registration.findings, ...parity];
 
   // Whether the LOCALE has a catalog is the wrong question — the framework's own `en` is always
   // registered, so a locale-presence column reads `yes` for an app whose every key is a loud miss.
@@ -165,10 +171,26 @@ async function runCheck(root: string): Promise<CommandResult> {
   const missingTotal =
     report.locales.reduce((sum, audit) => sum + audit.missing.length, 0) +
     registration.unregistered;
-  const ok = report.ok && registration.ok;
-  const summary = ok
-    ? msg('cli.i18n.ok', { locales: report.locales.length, keys: report.used.length })
-    : msg('cli.i18n.gaps', { missing: missingTotal, locales: gapLocales });
+  const ok = report.ok && registration.ok && parity.length === 0;
+  // The summary names the parity findings when there are any: `cli.i18n.gaps` counts MISSING KEYS,
+  // so a locale whose slots drifted and whose string was never translated answered "0 missing
+  // key(s) across 0 locale(s)" — a green-looking line over a red command. The missing count keeps
+  // a line of its own, so neither fact is lost.
+  let summary: string;
+  if (parity.length > 0) {
+    summary = msg('cli.i18n.parity', {
+      count: parity.length,
+      locales: parityLocales,
+      reference: DEFAULT_LOCALE,
+    });
+    if (missingTotal > 0) {
+      lines.push(`  ${msg('cli.i18n.gaps', { missing: missingTotal, locales: gapLocales })}`);
+    }
+  } else {
+    summary = ok
+      ? msg('cli.i18n.ok', { locales: report.locales.length, keys: report.used.length })
+      : msg('cli.i18n.gaps', { missing: missingTotal, locales: gapLocales });
+  }
 
   return {
     ok,

package/src/dev-route-table.ts

@@ -92,6 +92,10 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
   // `site.origin` and `seo.robots.disallow`: the absolute URLs every document and the sitemap carry.
   const site = await loadSiteSettings(input.root);
   const origin = publicOrigin(input.env, site);
+  // The app's own favicon is NOT resolved here: the document resolves it, per render, from the
+  // app root below. The route table is built once and the watcher rebuilds only the manifest and
+  // the islands, so a head minted at boot would name the icon's bytes as they were and go stale
+  // on the first save.
   // The same call `serve.ts` makes, so the two boots cannot serve different sync targets.
   const sync = await pageSync(input.root, input.env, input.buildId, input.realtime);
   // The client router, when a surface opted in (`navigation.client`) — the same call in both boots.
@@ -186,6 +190,8 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
     }),
     ...appRoutes({
       buildId: input.buildId,
+      // The app root: the document resolves the app's own favicon from it, per render.
+      root: input.root,
       ...(input.isr === undefined ? {} : { isr: input.isr }),
       resolveIsland: (file) => input.islands().resolverFor(file),
       realtimeIslands: () => input.islands().realtime,

package/src/document-options.ts

@@ -75,4 +75,14 @@ export interface DocumentOptions {
    * carries none, because the router prefetches by its own rules.
    */
   readonly speculationHead?: string;
+  /**
+   * `<link rel="icon" type="image/svg+xml" href="…">` — the app's own favicon, resolved once at
+   * boot by `runtime-render.ts`'s `appFaviconHead` into the content-hashed site-asset URL
+   * `/assets/*` serves.
+   *
+   * Document-level for `pwaHead`'s reason: it is the same one link on every page of the app, and
+   * it is decided by `app.config.ts`, which the boot read and the renderer cannot. Absent when the
+   * app declares no favicon — the browser's own `/favicon.ico` request is then the only one.
+   */
+  readonly faviconHead?: string;
 }

package/src/error-codes.ts

@@ -234,6 +234,9 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_BACKFILL_SLICE_ENTITY',
   'X_LAYOUT_SIBLING_MODULE',
   'X_SLICE_POLICY_INCOMPLETE',
+  'X_CATALOG_SLOT_MISMATCH',
+  'X_CATALOG_UNTRANSLATED',
+  'X_WORKER_QUEUE_UNKNOWN',
 ] as const;
 
 /**
@@ -424,6 +427,9 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_BACKFILL_SLICE_ENTITY: 'the slice holds no entity a generated backfill can sweep',
   X_LAYOUT_SIBLING_MODULE: 'a primitive module beside its directory',
   X_SLICE_POLICY_INCOMPLETE: 'a generator needs an export the slice policy.ts does not declare',
+  X_CATALOG_SLOT_MISMATCH: 'two locales define one key with different interpolation slots',
+  X_CATALOG_UNTRANSLATED: "a locale still carries the reference locale's value",
+  X_WORKER_QUEUE_UNKNOWN: 'WORKER_QUEUES names a queue no job and no jobs.queues entry declares',
 };
 
 // One unconditional call, so a second package claiming one of the CLI's codes throws

package/src/i18n-locale-parity.ts

@@ -0,0 +1,134 @@
+// The two rules a locale's catalog must satisfy against the reference locale's: the same
+// interpolation slots, and no untranslated copy of the reference's string. Both already hold at the
+// APP level (examples/dummy's catalog test asserts them over its en/es catalogs); this module is
+// the same rule as a finding, so a broken locale fails the gate instead of shipping.
+
+import { DEFAULT_LOCALE, ERROR_DOCS_URL } from '@ultimat3/core';
+import type { Catalog, Locale } from '@ultimat3/i18n';
+import { isMiss, placeholdersOf } from '@ultimat3/i18n';
+import type { Finding } from './output';
+import { catalogPath } from './templates/locales';
+
+/**
+ * The length above which two identical values are a copy rather than a name. `Postly`, `Free` and
+ * `Blog` read the same in every language; a sentence of 25 characters does not, and shipping it
+ * untranslated is the defect this rule exists to name.
+ */
+const COPY_LENGTH = 24;
+
+/** The slots, as `{name}` — the way a cause and a fix name them. */
+const shownSlots = (slots: readonly string[]): string =>
+  slots.map((slot) => `{${slot}}`).join(', ');
+
+/** The slots as the loud miss `interpolate` renders for each of them. */
+const shownMisses = (slots: readonly string[]): string =>
+  slots.map((slot) => `⟦${slot}⟧`).join(', ');
+
+/** A value, capped: a cause is one line, and a 300-character string is not a cause. */
+const shownValue = (value: string): string =>
+  value.length > 60 ? `${value.slice(0, 60)}…` : value;
+
+/**
+ * Every defect one locale's catalog holds against the reference's, as findings.
+ *
+ * Pure: catalogs in, findings out. A slot is read with `placeholdersOf` — @ultimat3/i18n's one
+ * definition, the same function `interpolate` substitutes by — because a second regex here could
+ * only ever disagree with the runtime about what a slot is.
+ *
+ * The reference is `en` — core's `DEFAULT_LOCALE`, never a second `'en'` spelled here. An app
+ * that ships no `en` catalog is not compared at all: there is no reference to compare against, and
+ * a rule with nothing to compare is noise on a healthy app.
+ */
+export function localeParityFindings(
+  catalogs: Readonly<Record<Locale, Catalog>>,
+): readonly Finding[] {
+  const reference = catalogs[DEFAULT_LOCALE];
+  if (reference === undefined) return [];
+  const findings: Finding[] = [];
+  for (const locale of Object.keys(catalogs).sort()) {
+    if (locale === DEFAULT_LOCALE) continue;
+    const catalog = catalogs[locale];
+    if (catalog === undefined) continue;
+    for (const key of Object.keys(reference).sort()) {
+      const value = reference[key];
+      const translated = catalog[key];
+      // Only a key BOTH define: a key one catalog holds alone is a MISSING key, and that is
+      // `X_CATALOG_MISSING_KEYS`'s finding. Reporting it here too would be one defect under two
+      // codes, and the second code's repair is not the first one's.
+      if (value === undefined || translated === undefined) continue;
+      findings.push(...keyFindings(locale, key, value, translated));
+    }
+  }
+  return findings;
+}
+
+/**
+ * The findings for one key, in one order: the slots the locale adds, the slots it drops, and the
+ * copy. A slot mismatch is TWO findings, because the two repairs differ — one is a rename, the
+ * other an addition — and a single cause could only name one of them.
+ *
+ * Every `fix:` opens with the command and names the edit behind a `#`: a fix is pasted from its
+ * first character, so a sentence the reader has to translate first is what the `fix-prose`
+ * ratchet refuses.
+ */
+function keyFindings(
+  locale: Locale,
+  key: string,
+  reference: string,
+  translated: string,
+): readonly Finding[] {
+  const path = catalogPath(locale);
+  // A loud miss (`⟦key⟧`) is a placeholder, not a translation, and it carries no slot of its own:
+  // a slot comparison across it blames the marker — `x i18n sync` seeds one into every key
+  // nobody has translated — and prints a fix ("add {name}") that edits the placeholder. The hole
+  // is `X_CATALOG_MISSING_KEYS`'s finding, already reported: a second code for one defect, with a
+  // repair that would destroy the marker. So the comparison waits for a real string on both sides.
+  const comparable = !isMiss(reference) && !isMiss(translated);
+  const referenceSlots = placeholdersOf(reference);
+  const translatedSlots = placeholdersOf(translated);
+  const extra = translatedSlots.filter((slot) => !referenceSlots.includes(slot));
+  const missing = referenceSlots.filter((slot) => !translatedSlots.includes(slot));
+  const findings: Finding[] = [];
+
+  if (comparable && extra.length > 0) {
+    findings.push({
+      code: 'X_CATALOG_SLOT_MISMATCH',
+      cause: `${path} defines "${key}" with ${shownSlots(extra)}, which ${catalogPath(DEFAULT_LOCALE)} does not — interpolate substitutes by name, so ${locale} renders ${shownMisses(extra)}`,
+      fix:
+        referenceSlots.length === 0
+          ? `x i18n check --json   # remove ${shownSlots(extra)} from "${key}" in ${path}`
+          : `x i18n check --json   # use ${shownSlots(referenceSlots)} instead of ${shownSlots(extra)} in "${key}" in ${path}`,
+      docs: ERROR_DOCS_URL,
+      at: path,
+      meta: { locale, key },
+    });
+  }
+
+  if (comparable && missing.length > 0) {
+    findings.push({
+      code: 'X_CATALOG_SLOT_MISMATCH',
+      cause: `${catalogPath(DEFAULT_LOCALE)} defines "${key}" with ${shownSlots(missing)}, which ${path} does not — the value it carries never renders in ${locale}`,
+      fix: `x i18n check --json   # add ${shownSlots(missing)} to "${key}" in ${path}`,
+      docs: ERROR_DOCS_URL,
+      at: path,
+      meta: { locale, key },
+    });
+  }
+
+  // A value longer than the bar that is byte-identical to the reference's is a copy nobody
+  // translated. A marker is NOT a copy: `⟦key⟧` is the loud miss `X_CATALOG_MISSING_KEYS` already
+  // reports, and a placeholder seeded into two locales would otherwise be one hole under two
+  // codes. `isMiss` is the framework's own predicate for that marker.
+  if (translated === reference && reference.length > COPY_LENGTH && !isMiss(reference)) {
+    findings.push({
+      code: 'X_CATALOG_UNTRANSLATED',
+      cause: `${path} defines "${key}" exactly as ${catalogPath(DEFAULT_LOCALE)} does ("${shownValue(reference)}") — ${reference.length} characters, so ${locale} reads the reference's sentence instead of its own`,
+      fix: `x i18n check --json   # translate "${key}" in ${path}`,
+      docs: ERROR_DOCS_URL,
+      at: path,
+      meta: { locale, key },
+    });
+  }
+
+  return findings;
+}

package/src/i18n-registration.ts

@@ -25,6 +25,7 @@ import { loadApp } from './app-load';
 import type { DuplicateProbe } from './duplicate-packages';
 import { duplicateCause, duplicateFinding, findDuplicateInstalls } from './duplicate-packages';
 import { auditApp } from './i18n-audit';
+import { localeParityFindings } from './i18n-locale-parity';
 import type { Finding } from './output';
 import { findingFrom } from './output';
 import { CATALOG_ROOT, catalogPath } from './templates/locales';
@@ -287,6 +288,10 @@ export function missingKeyFindings(report: ExtractReport): readonly Finding[] {
  * Both halves of one question — does every string this app renders resolve? — for a caller that
  * wants the verdict and not the table. `x verify`'s `i18n` step is that caller; `cmd-i18n.ts`
  * composes the same two pieces itself because it also renders per-locale rows.
+ *
+ * The locale parity joins them: a catalog can hold every key source uses and still be wrong in
+ * the two ways only a comparison with the reference locale can see — a slot one side does not
+ * have, and a string nobody translated.
  */
 export async function catalogFindings(root: string): Promise<readonly Finding[]> {
   const { report, catalogs, extraction, ignoreUnused } = await auditApp(root);
@@ -294,5 +299,6 @@ export async function catalogFindings(root: string): Promise<readonly Finding[]>
   return [
     ...missingKeyFindings(withPlaceholdersMissing(report, catalogs)),
     ...registration.findings,
+    ...localeParityFindings(catalogs),
   ];
 }

package/src/mcp-errors.ts

@@ -306,6 +306,12 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x verify --only boundaries --json   # then move each declaration in X.ts to X/<name>.ts, one primitive per file',
   X_SLICE_POLICY_INCOMPLETE:
     'x policy list --json   # names the slice policy module; add the export lines the thrown fix spells out to it, then run the generator again',
+  X_CATALOG_SLOT_MISMATCH:
+    'x i18n check --json   # the finding names the locale, the key and the slots that differ',
+  X_CATALOG_UNTRANSLATED:
+    'x i18n check --json   # the finding names the locale and the key still carrying the reference value',
+  X_WORKER_QUEUE_UNKNOWN:
+    'x jobs list --json   # set WORKER_QUEUES to queues it lists, or add the queue to jobs.queues in app.config.ts',
 };
 
 const isCliCode = (code: string): code is CliErrorCode =>

package/src/messages.ts

@@ -139,6 +139,10 @@ const CATALOG = {
   'cli.i18n.dynamic': '{count} dynamic t() call(s) the extractor cannot verify:',
   'cli.i18n.gaps': '{missing} missing key(s) across {locales} locale(s)',
   'cli.i18n.ok': '{locales} locale(s), {keys} key(s) used — no gaps',
+  // The summary a locale-parity finding needs: `cli.i18n.gaps` counts MISSING KEYS, so it cannot
+  // say "this locale's slots drifted and this string was never translated".
+  'cli.i18n.parity':
+    '{count} locale-parity finding(s) across {locales} locale(s) — a slot or an untranslated copy against {reference}',
   'cli.i18n.synced': 'synced {locale} from {from} — {added} key(s) added, {total} total',
   'cli.i18n.unused': '{count} key(s) defined in {locale} and never used:',
   'cli.jobs.backfillNoCursor': 'no cursor yet',

package/src/prerender.ts

@@ -195,6 +195,8 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   const theme = themeBoot(await loadThemeMode(options.root));
   // The brand the served process carries, so an exported page and a served one paint alike.
   const brand = await loadThemeBrand(options.root);
+  // The app's own favicon is resolved by the DOCUMENT, per render, from the app root below — the
+  // link the served surfaces emit, so an exported document and a served one carry the same icon.
   // The client router, for the surfaces that opted in: written BEFORE any document names it, for
   // the register's reason below — `measureDocumentJs` weighs it off disk, and it is charged to
   // the route (the interactivity the app asked for), so it must be there to be weighed.
@@ -266,6 +268,9 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   // Started on the first route that needs weighing, and released however the loop ends.
   const database = measureDatabase(options.root);
   const documentOptions = {
+    // The app root: the document resolves the app's own favicon from it, per render. `writeSiteAssets`
+    // above copied the icon into the artifact under the same hashed URL this resolves.
+    root: options.root,
     resolveIsland: (file: string) => islands.resolverFor(file),
     realtimeIslands: () => islands.realtime,
     themeHead: theme.head,