@ultimat3/cli 1.2.0 → 2.0.0

package/src/mcp-errors.ts

@@ -4,8 +4,9 @@
 
 import { describeErrorCode, hasErrorCode, listErrorCodes } from '@ultimat3/core';
 import type { ErrorExplanation } from '@ultimat3/mcp';
-import type { CliErrorCode } from './errors';
-import { CLI_ERROR_CODES, docsFor } from './errors';
+import type { CliErrorCode } from './error-codes';
+import { CLI_ERROR_CODES, docsFor } from './error-codes';
+import { codeFixes, codeFixScan } from './error-fixes';
 
 /**
  * One runnable command per CLI code. Typed over `CliErrorCode`, so a new code fails the build.
@@ -18,17 +19,25 @@ import { CLI_ERROR_CODES, docsFor } from './errors';
  */
 const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_CLI_UNKNOWN_COMMAND: 'x help --json',
-  X_CLI_BAD_FLAG: 'x help <command> --json',
+  // Runnable first, the narrowing behind a `#`: `x help <command> --json` pasted into a shell
+  // is a redirect, not a command, and this table is copied verbatim by whoever reads it.
+  X_CLI_BAD_FLAG: 'x help --json   # then narrow to the command the cause names',
   X_VERIFY_FAILED: 'x verify --json',
   X_NOT_IN_APP: 'x new myapp --json && cd myapp',
   X_BUN_VERSION: 'bun upgrade',
   X_NOT_IMPLEMENTED: 'x doctor --json',
-  X_TEST_NO_FILES: 'x test --cwd <repo root> --json',
+  // Core's three env codes, answered by the command that covers each. `X_CONFIG_INVALID` gets
+  // `x doctor` rather than `x env check`: its causes are env *and* `app.config.ts` fields, and
+  // `x env check` on a config the app cannot boot on would throw this same code straight back.
+  X_CONFIG_INVALID: 'x doctor --json',
+  X_ENV_MISSING: 'x env check --json',
+  X_ENV_EXAMPLE_DRIFT: 'x env example --json',
+  X_TEST_NO_FILES: 'x test --json   # from the repo root, or pass --cwd to it',
   X_TEST_SHARD_FAILED: 'x test --workers 1 --json',
-  X_SCAFFOLD_PATH_ESCAPE: 'x g route <name> --json   # a path with no ".." segment',
+  X_SCAFFOLD_PATH_ESCAPE: 'x g route posts --json   # a path with no ".." segment',
   X_GENERATE_JSON_INVALID:
     'bun test packages/cli/src/cmd-generate.test.ts   # the error names the template to fix',
-  X_APP_PACKAGE_INVALID: 'bun pm pkg set name=<app> version=0.1.0',
+  X_APP_PACKAGE_INVALID: 'bun pm pkg set name=my-app version=0.1.0',
   X_ERROR_CODE_UNKNOWN: 'x errors list --json',
   X_DECLARATION_UNKNOWN: 'x actions list --json',
   X_JOB_UNKNOWN: 'x jobs ls --json',
@@ -41,20 +50,41 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_TYPECHECK_FAILED: 'bunx tsc -b --pretty false',
   X_LINT_FAILED: 'bunx biome check --write .',
   X_TEST_FAILED: 'x test --json   # the finding carries the exact bun test invocation that failed',
+  // The same two edits `vanishedSuiteFinding` names, verbatim, so both surfaces of this code hand
+  // an agent one instruction. Neither edit is scripted here on purpose: a command that rewrites
+  // x.verify.json is the gate editing its own ratchet, which is the false green the floor closes.
+  X_VERIFY_SUITE_VANISHED:
+    'x verify --json   # restore the suite, or drop its name from x.verify.json in the commit that says why',
   X_FILE_TOO_LONG: 'x verify --json   # the finding names the file to split',
-  X_PACKAGE_SHAPE: 'bun run scripts/new-package.ts <pkg> --only <file>',
+  X_PACKAGE_SHAPE: 'bun run verify --json   # every finding carries its own new-package.ts command',
+  // NOT `bunx tsc -b`: an unreferenced package is one `tsc -b` skips by definition, so it exits 0
+  // while the finding stands — a fix that runs clean and changes nothing is the failure axiom 4
+  // exists to prevent. The gate is what re-emits the finding, whose own `fix:` carries the exact
+  // `{ "path": … }` entry; the `tsc -b` that then reports the type errors the package had been
+  // hiding is a step of the same run.
+  X_PACKAGE_UNREFERENCED:
+    'x verify --json   # the package-shape finding carries the tsconfig.json entry to add',
   X_RELEASE_VERSION_SKEW: 'bun run scripts/release.ts --bump patch --dry-run --json',
+  // Two real remedies and the command cannot know which one this deployment wants, so it names
+  // the one that inspects the binding rather than guessing between a volume and a bucket.
+  X_STORAGE_UNWRITABLE: 'x doctor --json',
+  X_STORAGE_SECRET_DEV: 'export STORAGE_SIGNING_SECRET="$(openssl rand -hex 32)"',
   X_MANIFEST_STALE: 'x manifest --json',
-  X_BUDGET_UNMEASURED: 'x build --json && x verify --json',
+  // `--target static`, not a bare `x build`: `--target` defaults to `docker`, and only the static
+  // target runs `apps/web/prerender.ts` — the one caller of `writeBuildStats`. Without the flag
+  // this fix builds an image, writes no `.x/build-stats.json`, and the next `x verify` reports the
+  // same code. Byte-identical to `checkBudgets`'s own finding, which is the other half of the pair.
+  X_BUDGET_UNMEASURED: 'x build --target static --json && x verify --json',
   X_BUILD_FAILED: 'x build --json   # the finding names the failing step',
   X_BUILD_ENTRY_MISSING:
-    'x new <name> --dry-run --json   # the file list names every entry a build needs',
+    'x new scratch-app --dry-run --json   # the file list names every entry a build needs',
   X_DEPLOY_FAILED: 'x deploy --json   # the finding carries the command to re-run directly',
   // The container's own environment, so the answer is the run that sets it — never an `x` command,
   // which is not what is running when a `ROLE=wroker` pod refuses to boot.
-  X_ROLE_UNKNOWN: 'docker run -e ROLE=web <image>',
-  X_PORT_INVALID: 'docker run -e PORT=3000 <image>',
-  X_GENERATE_CONFLICT: 'x g <kind> <name> --force --json',
+  X_ROLE_UNKNOWN: 'docker run -e ROLE=web my-app:latest',
+  X_PORT_INVALID: 'docker run -e PORT=3000 my-app:latest',
+  X_RUNTIME_DRIVER_SPLIT: 'x dev --json   # the boot names the driver the app installed twice',
+  X_GENERATE_CONFLICT: 'x g route posts --force --json',
   X_PORT_IN_USE: 'x dev --port 3001 --json',
   // Not `x db status`: there is no such subcommand (`x db` is gen, migrate, reset, studio, branch),
   // so the fix answered a failed step with X_CLI_UNKNOWN_COMMAND. `x doctor` is what reports
@@ -63,20 +93,91 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_DB_MIGRATE_FAILED: 'x doctor --json   # cause carries the Postgres error verbatim',
   X_DB_BRANCH_FAILED: 'x db branch ls --json',
   X_DB_STUDIO_FAILED: 'x doctor --json',
-  X_BOUNDARY_SITE_TO_APP: 'x fix boundary <file> --json',
-  X_BOUNDARY_SHARED_LEAF: 'x fix boundary <file> --json',
-  X_BOUNDARY_APP_TO_API: 'x fix boundary <file> --json',
-  X_BOUNDARY_ROUTE_TO_DB: 'x fix boundary <file> --json',
-  X_BOUNDARY_SERVICE_TO_HTTP: 'x fix boundary <file> --json',
+  X_BOUNDARY_SITE_TO_APP:
+    'x verify --json   # then: x fix boundary <the file the finding names> --json',
+  X_BOUNDARY_SHARED_LEAF:
+    'x verify --json   # then: x fix boundary <the file the finding names> --json',
+  X_BOUNDARY_APP_TO_API:
+    'x verify --json   # then: x fix boundary <the file the finding names> --json',
+  X_BOUNDARY_ROUTE_TO_DB:
+    'x verify --json   # then: x fix boundary <the file the finding names> --json',
+  X_BOUNDARY_SERVICE_TO_HTTP:
+    'x verify --json   # then: x fix boundary <the file the finding names> --json',
+  // The app's own guards. All three are reported by the gate and by nothing else, so the runnable
+  // half is the gate — the narrowing behind the `#` is the edit, because only the finding knows
+  // which file in `guards/` is the one to open.
+  X_GUARD_INVALID: 'x verify --json   # then export a `guard` from the file the finding names',
+  X_GUARD_FAILED: 'x verify --json   # the cause carries the throw the guard raised, verbatim',
+  X_GUARD_FINDING_INVALID:
+    'x verify --json   # then give the finding an X_ code, a cause and a fix naming a command',
+  // `EDITOR=` inline rather than `export`: the variable is only needed for the one invocation, and
+  // an agent copying this line gets a working command instead of a shell it has to keep.
+  X_SECRETS_EDITOR_MISSING: 'EDITOR=nano x secrets edit',
+  X_SECRETS_EDIT_FAILED: 'x secrets show --json   # then re-open the buffer: x secrets edit',
+  // Render's code, thrown here by the bundler half: the cause names the specifier and the file it
+  // resolved to, and `x g island` is what puts that file where the page already says it is.
+  X_ISLAND_INVALID: 'x routes --json   # the cause names the src; then: x g island <name>',
 };
 
 const isCliCode = (code: string): code is CliErrorCode =>
   (CLI_ERROR_CODES as readonly string[]).includes(code);
 
+/**
+ * The fix a code's own throw site writes, for every code this table does not own.
+ *
+ * The table above stays the answer for `CliErrorCode` and only for it: those lines are typed,
+ * build-enforced, and several of them are deliberately NOT the throw site's wording (the comments
+ * above say which and why). Everywhere else the throw site is the definition and this is a
+ * projection of it — one `fix:`, written once, `x errors explain` and the raised error agreeing by
+ * construction rather than by review.
+ *
+ * Both fallbacks name what they do not know. `x verify --json` was the old answer for all 327 of
+ * them, and it is a lie for every runtime code: the gate does not raise `X_UNAUTHENTICATED`, so
+ * running it reports green and the reader is exactly where they started.
+ */
+function projectedFix(code: string): string {
+  const sites = codeFixes().get(code) ?? [];
+  const readable = sites.filter((site) => site.fix !== undefined);
+  const first = readable[0];
+  if (first?.fix === undefined) {
+    const site = sites[0];
+    if (site !== undefined) {
+      // The file comes FIRST and carries no verb. `open …` read as a command — `open(1)`,
+      // `xdg-open` — and an agent that executed it got `command not found`, which is the same
+      // axiom-4 failure as the `x verify --json` this replaced, one step further along. There is
+      // genuinely no command here: the fix is assembled from values only the raised error holds.
+      // "A file they can open" is the error contract's own fourth shape (`COMMAND_TOKENS`), and
+      // citing a command that does not really fix it is the mistake `fix-command.ts` warns about.
+      // `x errors explain --json` carries the same site as DATA, so nothing has to parse this.
+      return `${site.at}:${site.line} — the fix is built there out of values only the raised error carries, so reproduce the error and read its own fix line`;
+    }
+    if (codeFixScan() === 'unread') {
+      // Not "nothing raises it": nothing LOOKED. `cmd-docs.ts` answers the same broken install
+      // with the same line, because it is the same condition seen from a second command.
+      return `bun install && x doctor --json   # the installed @ultimat3 packages could not be read, so no throw site could be quoted for ${code}`;
+    }
+    return `x errors list --json   # nothing in the installed framework raises ${code}, so the package that registered it owns its fix`;
+  }
+  // Both notes name a thing this answer does NOT know, because an answer that hides either is one
+  // an agent acts on without noticing: which of several throw sites it is quoting, and which words
+  // in it were an interpolation at the throw site and are a placeholder here.
+  const notes: string[] = [];
+  if (readable.length > 1) {
+    notes.push(
+      `${code} is raised at ${readable.length} sites; this one is ${first.at}:${first.line}`,
+    );
+  }
+  if (first.fix.includes('<value>')) {
+    notes.push('each <value> is filled in by the error that raises it');
+  }
+  return notes.length === 0 ? first.fix : `${first.fix}   # ${notes.join('; ')}`;
+}
+
 /**
  * `undefined` for a code nobody registered — the tool then answers "unknown error code", which
  * beats an invented explanation. The framework-wide registry holds a title and a docs URL but no
- * fix (a thrown error carries its own), so a non-CLI code points at the gate that surfaces it.
+ * fix, so the fix comes from `error-fixes.ts`'s read of the throw sites; a caller that has not
+ * awaited `loadCodeFixes()` gets the honest fallback rather than a stale answer.
  */
 export function explainErrorCode(code: string): ErrorExplanation | undefined {
   const cli = isCliCode(code);
@@ -85,7 +186,7 @@ export function explainErrorCode(code: string): ErrorExplanation | undefined {
   return {
     code,
     cause: described.title,
-    fix: cli ? CLI_FIXES[code] : 'x verify --json',
+    fix: cli ? CLI_FIXES[code] : projectedFix(code),
     docs: cli ? docsFor(code) : described.docs,
   };
 }

package/src/mcp-host.ts

@@ -3,11 +3,17 @@
 // the gate. The description half is the framework's own `frameworkIntrospection`, so nothing here
 // is a second catalog of routes, entities, actions, queries or jobs.
 
-import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { agentActor, UltimateError } from '@ultimat3/core';
+import { agentActor, isUltimateError, UltimateError } from '@ultimat3/core';
 import type { DbClient } from '@ultimat3/db';
-import { ensureReadOnlyRole, readLedger, readOnlyQuery } from '@ultimat3/db';
+import {
+  ensureReadOnlyRole,
+  isLedgerMissing,
+  migrate,
+  pendingMigrations,
+  readLedger,
+  readOnlyQuery,
+} from '@ultimat3/db';
 import { inspectJobList, inspectQueues } from '@ultimat3/jobs';
 import { MANIFEST_FILENAME } from '@ultimat3/manifest';
 import type {
@@ -28,13 +34,14 @@ import type { RunningServices } from './dev-runtime';
 import { startServices } from './dev-runtime';
 import type { DevServices, Env } from './dev-services';
 import { resolveServices } from './dev-services';
-import { MIGRATIONS_DIR } from './drift';
+import { loadCodeFixes } from './error-fixes';
 import { CliNotImplementedError } from './errors';
 import type { Runner } from './exec';
 import { execOutput } from './exec';
 import { databaseTarget } from './mcp-db-target';
 import { explainErrorCode } from './mcp-errors';
 import { parseBunTest } from './mcp-test-output';
+import { readMigrations } from './migrations';
 
 export interface DevHostInput {
   readonly root: string;
@@ -106,20 +113,25 @@ export function lazyServices(input: DevHostInput): LazyServices {
   };
 }
 
-/** Migration ids on disk (`0001_init.sql` → `0001_init`) that the ledger does not record. */
-async function pendingMigrations(root: string, lazy: LazyServices): Promise<readonly string[]> {
-  const dir = join(root, MIGRATIONS_DIR);
-  if (!existsSync(dir)) return [];
-  const ids: string[] = [];
-  for await (const file of new Bun.Glob('*.sql').scan({ cwd: dir, absolute: false })) {
-    if (!file.endsWith('.down.sql')) ids.push(file.replace(/\.sql$/, ''));
-  }
+/**
+ * Migration ids on disk that the ledger does not record. Both halves are the framework's own —
+ * `readMigrations` is the list `ROLE=migrate` applies and `pendingMigrations` is the filter
+ * `migrate()` applies it through, so this tool can never report a pending set the migrator would
+ * disagree with.
+ */
+async function pendingIds(root: string, lazy: LazyServices): Promise<readonly string[]> {
+  const migrations = await readMigrations(root);
+  if (migrations.length === 0) return [];
   const { db } = await lazy.running();
   // No ledger table means nothing has been applied. `ensureLedger` would create it, and a dry run
-  // is not allowed to write.
-  const ledger = await readLedger(db).catch(() => []);
-  const applied = new Set(ledger.map((row) => row.id));
-  return ids.filter((id) => !applied.has(id)).sort();
+  // is not allowed to write. Only that condition: a permission denied or an unreachable server is
+  // a ledger nobody read, and answering it with `[]` reports every migration as pending against a
+  // database whose state this tool never saw.
+  const ledger = await readLedger(db).catch((error: unknown) => {
+    if (!isLedgerMissing(error)) throw error;
+    return [];
+  });
+  return pendingMigrations(ledger, migrations).map((migration) => migration.id);
 }
 
 // ── the capabilities ─────────────────────────────────────────────────────────
@@ -164,7 +176,7 @@ function capabilities(input: DevHostInput, lazy: LazyServices): DevCapabilities
   let readOnlyRole: Promise<string | null> | undefined;
 
   return {
-    database: databaseTarget(lazy.services),
+    database: databaseTarget(lazy.services, input.env),
 
     async runQuery(sql: string, limits: QueryLimits): Promise<QueryRows> {
       const { db } = await lazy.running();
@@ -175,20 +187,24 @@ function capabilities(input: DevHostInput, lazy: LazyServices): DevCapabilities
     },
 
     async runMigrations(branch: string, dryRun: boolean) {
-      const before = await pendingMigrations(root, lazy);
+      const before = await pendingIds(root, lazy);
       if (dryRun) return { branch, applied: [], pending: before };
-      const result = await runner(['bunx', 'drizzle-kit', 'migrate'], { cwd: root });
-      if (!result.ok) {
+      const { db } = await lazy.running();
+      try {
+        await migrate({ migrations: await readMigrations(root), client: db });
+      } catch (error) {
         // Thrown, not returned: `server.ts` renders any X_* error as the three-line
-        // code/cause/fix result, which is what an agent needs to act without a round trip.
+        // code/cause/fix result, which is what an agent needs to act without a round trip. The
+        // engine's own errors already carry that shape and pass through untouched.
+        if (isUltimateError(error)) throw error;
         throw new UltimateError({
           code: 'X_DB_MIGRATE_FAILED',
-          cause: `${result.command.join(' ')} exited ${result.code}: ${execOutput(result).slice(0, 400)}`,
+          cause: error instanceof Error ? error.message : String(error),
           fix: 'x db reset',
         });
       }
-      // The ledger is the evidence for "applied" — never the migrator's own stdout.
-      const pending = await pendingMigrations(root, lazy);
+      // The ledger is the evidence for "applied" — never the migrator's own return value.
+      const pending = await pendingIds(root, lazy);
       return { branch, applied: before.filter((id) => !pending.includes(id)), pending };
     },
 
@@ -270,7 +286,10 @@ function capabilities(input: DevHostInput, lazy: LazyServices): DevCapabilities
  * introspection tool then answers from the framework's own registries, not from a scan.
  */
 export async function createDevMcpServer(input: DevHostInput): Promise<CliMcpServer> {
-  await loadApp(input.root);
+  // `explainError` is synchronous by `DevCapabilities`' own signature, so the walk that reads the
+  // framework's `fix:` lines happens here, once, or `errors.explain` answers with the fallback for
+  // every code it could have quoted.
+  await Promise.all([loadApp(input.root), loadCodeFixes()]);
   const lazy = lazyServices(input);
   const introspection = frameworkIntrospection({
     routes: () => describeRoutes(),

package/src/messages.ts

@@ -10,6 +10,7 @@ const CATALOG = {
   'cli.flags.heading': 'flags',
   'cli.commands.heading': 'commands',
   'cli.build.done': 'built {target}',
+  'cli.build.failed': '{target} build failed',
   // `describeCron`'s vocabulary. `@ultimat3/time` is tier 1 and reaches no i18n runtime, so the
   // caller supplies the words — and the caller here is a rendered `x tasks show` line, which is
   // exactly what this catalog holds. `msg()` leaves an un-supplied `{n}`/`{time}`/`{days}`/
@@ -24,7 +25,31 @@ const CATALOG = {
   'cli.cron.inMonths': 'in {months}',
   'cli.cron.onDaysOfMonth': 'on day {days} of the month',
   'cli.cron.onWeekdays': 'on {days}',
+  'cli.db.backfill.empty': 'no backfill has run against this database yet',
+  'cli.db.backfill.listed': '{count} backfill pass(es)',
+  /** The empty cell in a `x db backfill --list` column — a value, not a column key. */
+  'cli.db.backfill.none': '-',
+  'cli.db.backfill.pending': '{count} of {declared} declared backfill(s) never completed',
+  'cli.db.backfill.swept': 'every one of {declared} declared backfill(s) has completed',
+  // Every action counted, never derived: `count - enqueued` folded a deduped pass into "blocked",
+  // so the summary said blocked while `--json` said deduped for the same row — two renderers
+  // stating different facts about one run, which is the thing `--json` exists to make impossible.
+  'cli.db.backfill.planned':
+    '{count} backfill(s): {enqueued} enqueued, {deduped} already live, {blocked} blocked',
+  'cli.db.backfill.dryRun': '{count} backfill(s) would run — nothing written without --write',
   'cli.db.branch.ready': 'branch {name} ready',
+  'cli.db.branch.dropped': 'branch {name} dropped',
+  'cli.db.branch.failed': 'branch command failed',
+  'cli.db.branch.listed': '{count} branch(es) of this database',
+  'cli.db.branch.none': 'this database has no branch',
+  /** The empty cell in an `x db branch ls` column — a value, not a column key. */
+  'cli.db.branch.unknown': '-',
+  'cli.db.gen.failed': 'migration not generated',
+  'cli.db.gen.unchanged': 'entities and migrations agree — nothing to generate',
+  'cli.db.gen.written': 'migration {id} generated',
+  'cli.db.migrate.applied': 'migrations applied',
+  'cli.db.migrate.failed': 'migration failed',
+  'cli.db.reset.done': 'database reset and migrated',
   'cli.dev.ready': 'dev ready on {url} — /_x mounted ({panels} panels), {services}',
   // The mail and CDN halves of that boot line. Rendered text, so it lives here — while
   // `describeMail`/`describeCdn` keep the same wording as the fixed vocabulary `x dev --json`
@@ -33,6 +58,7 @@ const CATALOG = {
   'cli.dev.cdn.none': 'cdn=none',
   'cli.dev.mail.embedded': 'mail=embedded',
   'cli.dev.mail.external': 'mail=external({driver} via {detail})',
+  'cli.dev.mail.refused': 'mail=refused({detail})',
   'cli.dev.hmr': 'reloaded {file} in {ms}ms',
   'cli.dev.roles': '  roles {roles}',
   'cli.dev.panels': '  panels {panels}',
@@ -41,17 +67,42 @@ const CATALOG = {
   'cli.deploy.plan': 'containers only: {images} image, roles {roles}',
   'cli.doctor.clean': 'no findings — environment is shippable',
   'cli.doctor.findings': '{count} finding(s)',
+  'cli.docs.code': '{code} is an error code — x errors explain answers it',
+  'cli.docs.exports': 'exports: {list}',
+  'cli.docs.installed': 'installed: {list}',
+  'cli.docs.tryErrors': 'every X_* code, with its fix',
+  'cli.docs.tryActions': "this app's own primitives, not the framework's",
+  'cli.docs.found': '{count} doc(s) for "{query}"',
+  'cli.docs.none': 'no framework doc matches "{query}"',
+  'cli.docs.unresolved': 'the installed framework packages could not be located',
   'cli.errors.count': '{count} registered error code(s)',
   'cli.errors.explained': '{code} — {title}',
+  // One rendering of "this file was written", for every command that writes files — `x g`, its
+  // own `--dry-run`, and `x new`. Three copies of the same two characters is how a fourth writer
+  // arrives with a fifth marker; `--json` carries the paths themselves in `data.files`.
+  'cli.file.added': '  + {path}',
   'cli.fix.clean': 'no boundary violation involves {file}',
-  'cli.fix.plan': '{count} boundary violation(s) involve {file} — {edits} edit(s) to make',
+  // "nothing written", the same admission `cli.generate.planned` makes and for the same reason: a
+  // command called `fix` that only ever REPORTS teaches an agent to expect a repair and act as
+  // though one happened. There is no `--write` and there is not going to be one
+  // (`docs/architecture/02-boundaries.md`), so the line that runs says so every time.
+  'cli.fix.plan':
+    '{count} boundary violation(s) involve {file} — {edits} edit(s) to make, nothing written',
   'cli.generate.wrote': 'wrote {count} file(s) for {kind} {name}',
+  // A distinct key, not the same sentence with a flag beside it: `--dry-run` reported "wrote 4
+  // file(s)" while `data.dryRun` said nothing had landed, so an agent branching on `summary`
+  // believed the files were on disk.
+  'cli.generate.planned': 'would write {count} file(s) for {kind} {name} — nothing written',
   'cli.i18n.added': 'added {locale} — {keys} key(s) seeded from {from}',
   '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',
   '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',
+  'cli.jobs.cancelled': 'job {id} cancelled — {state}',
+  'cli.jobs.backfillRow': '{name} — {rows} row(s) so far, cursor {cursor}',
+  'cli.jobs.backfills': '{count} backfill(s) in flight:',
   'cli.jobs.deadLetters': '{count} dead letter(s):',
   'cli.jobs.depth':
     '{ready} ready · {running} running · {delayed} delayed · {dead} dead across {queues} queue(s)',
@@ -69,7 +120,10 @@ const CATALOG = {
   'cli.manifest.wrote': 'manifest written to {path} ({routes} routes, {actions} actions)',
   'cli.mcp.serving': 'mcp {transport} serving {tools} tools',
   'cli.mcp.scopes': '  scopes {scopes}',
-  'cli.new.done': 'created {name} — next: cd {name} && x dev',
+  // `x db gen "initial"` is a first step, not an optional one: the scaffold writes no migration, so
+  // the app has a schema no migration records and `x verify`'s drift step says so until it runs.
+  'cli.new.done':
+    'created {name} — next: cd {name} && bun install && x db gen "initial" && x db migrate && x dev',
   'cli.policy.count':
     '{permissions} permission(s), {roles} role(s), {enforced} enforced by a declaration',
   // One row per (declaration, actor) pair, never per role: a permission two declarations enforce
@@ -97,6 +151,31 @@ const CATALOG = {
   'cli.test.type.pass': '{type} — {files} test file(s) on {workers} worker(s) passed in {ms}ms',
   'cli.verify.pass': 'all {count} steps passed in {ms}ms',
   'cli.verify.fail': '{failed} of {count} steps failed',
+  // A skipped step is not a passed one, so the two counts never share a sentence — and the skipped
+  // ones are named, because "which suite has nothing to run here?" is the question a green gate
+  // over a missing suite has to answer on its own line. Whole sentences per case rather than a
+  // clause the caller glues on, the same shape `cli.jobs.drained`/`drainedPartial` already uses.
+  'cli.verify.passSkipped':
+    '{passed} of {count} steps passed in {ms}ms — {skipped} skipped: {names}',
+  'cli.verify.failSkipped': '{failed} of {count} steps failed — {skipped} skipped: {names}',
+  'cli.verify.serial': 'serial',
+  'cli.verify.workers': '{workers} workers',
+  'cli.env.checked': '{count} declared variable(s), all present and valid',
+  'cli.env.invalid': '{count} of {total} declared variable(s) missing or malformed',
+  'cli.env.wrote': 'wrote {path} — {count} declared variable(s)',
+  'cli.env.fresh': '{path} already matches the declaration',
+  'cli.secrets.init': 'sealed {path} — master key {kid}, and .gitignore now covers the key file',
+  'cli.secrets.deploy': '  carry the key into a deploy with {env}="$(cat {keyPath})"',
+  'cli.secrets.redeploy': '  set {env}="$(cat {keyPath})" in every deploy before the next release',
+  'cli.secrets.shown': '{count} secret(s) in {path}, sealed with master key {kid}',
+  'cli.secrets.empty': '{path} holds no secrets yet',
+  'cli.secrets.undeclared':
+    '{count} secret(s) no envSchema declares, so nothing reads them: {names}',
+  'cli.secrets.edited': '{path} resealed — {added} added, {updated} changed, {removed} removed',
+  'cli.secrets.unchanged': '{path} unchanged — nothing was written',
+  'cli.secrets.set': 'sealed {name} into {path} — {count} secret(s)',
+  'cli.secrets.rotated':
+    'rotated {path} from master key {from} to {to} — {count} secret(s) resealed',
 } as const;
 
 export type MessageKey = keyof typeof CATALOG;

package/src/metrics-endpoint.ts

@@ -14,9 +14,10 @@ import {
  * A port of its own, and NOT the role's HTTP port, for one reason the chart makes concrete:
  * `docker/helm/templates/ingress.yaml` routes `path: /` `Prefix` to the web Service, so a
  * `/metrics` mounted beside `/healthz` on port 3000 is `/metrics` on the internet — route
- * patterns, request volumes and error rates, published. Nothing in the chart fronts this port:
- * `service.yaml` only publishes `http`, so the endpoint is cluster-internal by construction
- * rather than by an ingress exclusion somebody has to remember to write.
+ * patterns, request volumes and error rates, published. `service.yaml` does publish this port
+ * so a `ServiceMonitor` has a named target, but `ingress.yaml` selects its backend port BY NAME
+ * (`http`), so the endpoint stays cluster-internal by construction rather than by an ingress
+ * exclusion somebody has to remember to write.
  *
  * It is also the only thing `worker`, `scheduler` and `replicator` could ever be scraped on —
  * they open no HTTP socket at all, and `queue_depth` is exactly the signal one of them owns.

package/src/migrations.ts

@@ -4,11 +4,18 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import type { Migration } from '@ultimat3/db';
+import type { Migration, SchemaDescription } from '@ultimat3/db';
+import { parseSnapshot } from '@ultimat3/db';
 
-/** Where `x new` writes them and where `x db gen` adds to. App-root-relative, POSIX. */
+/** Where `x db gen` — the only writer — puts them. App-root-relative, POSIX. */
 export const MIGRATIONS_DIR = 'packages/db/migrations';
 
+/** The schema `<id>` leaves behind, written by `x db gen` so the next one can diff against it. */
+export const snapshotFileName = (id: string): string => `${id}.snapshot.json`;
+
+/** The hash of the entity source `<id>` was generated from. `drift.ts` writes and reads it. */
+export const hashFileName = (id: string): string => `${id}.hash`;
+
 /**
  * `-- down` alone on a line splits a migration file. Anchored to the whole line so a comment that
  * merely mentions the word — `-- down migrations are required` — is not mistaken for the marker.
@@ -25,21 +32,47 @@ export function parseMigrationSql(id: string, sql: string): Migration {
   return { id, name: migrationName(id), up, down };
 }
 
+/**
+ * A snapshot that will not parse is *absent*, never a half-read one: the `up` beside it is still
+ * the migration this app applies, so the file list stays whole. What that absence then means is
+ * the caller's — `x db gen` refuses with `X_MIGRATION_SNAPSHOT_MISSING` when it is the newest
+ * migration's, because there is nothing left to diff the entities against.
+ */
+async function readSnapshot(dir: string, id: string): Promise<SchemaDescription | undefined> {
+  const file = Bun.file(join(dir, snapshotFileName(id)));
+  if (!(await file.exists())) return undefined;
+  // Parsed to the last nested field by `@ultimat3/db`, never asserted: `{"tables":[null]}` is
+  // valid JSON and a cast made it a `SchemaDescription` the diff then threw on.
+  return parseSnapshot(await file.json().catch(() => undefined));
+}
+
 /**
  * Sorted by id, because that is the apply order and `pendingMigrations` re-sorts on the same key.
  * A missing directory is an empty list rather than a throw: an app can legitimately declare no
  * entity yet, and the count is reported so "nothing was applied" is never silent.
+ *
+ * `<id>.down.sql` is skipped and never read as a migration of its own. Migrations before 1.2.0
+ * were hand-written as a `<id>.sql` / `<id>.down.sql` pair — a layout no generator ever produced
+ * and this reader would have applied as a migration named `<id>.down`, dropping every table the
+ * pair exists to reverse. One migration is one file, split by the `-- down` marker.
  */
 export async function readMigrations(root: string): Promise<readonly Migration[]> {
   const dir = join(root, MIGRATIONS_DIR);
   if (!existsSync(dir)) return [];
   const files: string[] = [];
-  for await (const file of new Bun.Glob('*.sql').scan({ cwd: dir })) files.push(file);
+  for await (const file of new Bun.Glob('*.sql').scan({ cwd: dir })) {
+    if (!file.endsWith('.down.sql')) files.push(file);
+  }
   files.sort();
   const migrations: Migration[] = [];
   for (const file of files) {
+    const id = file.replace(/\.sql$/, '');
     const text = await Bun.file(join(dir, file)).text();
-    migrations.push(parseMigrationSql(file.replace(/\.sql$/, ''), text));
+    const snapshot = await readSnapshot(dir, id);
+    migrations.push({
+      ...parseMigrationSql(id, text),
+      ...(snapshot === undefined ? {} : { snapshot }),
+    });
   }
   return migrations;
 }

package/src/otlp-export.ts

@@ -0,0 +1,64 @@
+// OTLP export, switched on by the variable the shipped Helm chart already sets. Until this file
+// `OTEL_EXPORTER_OTLP_ENDPOINT` was in `docker/helm/values.yaml` and **no code read it**: a
+// deployment configured a collector, the collector received nothing, and the only signal that
+// anything was wrong was an empty dashboard.
+
+import {
+  configureMetrics,
+  configureTelemetry,
+  logger,
+  onShutdown,
+  otlpMetricExporter,
+  otlpSpanExporter,
+  startMetricExport,
+  tryOtlpEndpoint,
+} from '@ultimat3/core';
+import type { Env } from './dev-services';
+
+/** How often counters are pushed. Core's own default; named here because the boot chose it. */
+export const METRIC_EXPORT_INTERVAL_MS = 60_000;
+
+/**
+ * Install whichever exporters an endpoint was configured for, and return the release.
+ *
+ * `tryOtlpEndpoint` is asked FIRST, per signal, because both constructors throw
+ * `X_OTLP_ENDPOINT_INVALID` when nothing configured one — deliberately, so that a telemetry
+ * exporter can never silently send nowhere. Asking is what makes the exporter optional without
+ * making it silent.
+ *
+ * Both are registered with `onShutdown(..., { phase: 'close' })`: the last spans of a drain are
+ * the ones that explain the drain, and a process that exits with a full queue loses exactly the
+ * window an operator went looking for.
+ */
+export function startOtlpExport(env: Env = process.env): () => void {
+  const releases: (() => void)[] = [];
+
+  // The boot's OWN env, not `process.env`, and the resolved endpoint is then passed to the
+  // exporter explicitly: `runRole({ env })` is a real seam — a test and an in-process host both
+  // pass an env that is not the process's — and an exporter that re-read `process.env` would
+  // answer a different question from the one this function just asked.
+  const traces = tryOtlpEndpoint('traces', env);
+  if (traces !== undefined) {
+    const exporter = otlpSpanExporter({ endpoint: traces });
+    configureTelemetry({ exporter });
+    releases.push(onShutdown('otlp-traces', () => exporter.shutdown(), { phase: 'close' }));
+    logger.info('ultimate otlp traces', { endpoint: traces });
+  }
+
+  const metrics = tryOtlpEndpoint('metrics', env);
+  if (metrics !== undefined) {
+    const exporter = otlpMetricExporter({ endpoint: metrics });
+    configureMetrics({ exporter });
+    // The push loop, and not only the exporter: `configureMetrics` names where a snapshot goes
+    // and nothing decides when one is taken, so without this the collector receives one export —
+    // the drain's — for the whole life of the process.
+    const stopTimer = startMetricExport(METRIC_EXPORT_INTERVAL_MS);
+    releases.push(stopTimer);
+    releases.push(onShutdown('otlp-metrics', () => exporter.flush(), { phase: 'close' }));
+    logger.info('ultimate otlp metrics', { endpoint: metrics });
+  }
+
+  return () => {
+    for (const release of releases.reverse()) release();
+  };
+}