@ultimat3/cli 7.0.0 → 9.0.0

package/CLAUDE.md

@@ -6,10 +6,12 @@ Tier 5. May import tiers 0–4. Nothing imports this except `create-ultimate`.
 |---|---|
 | Entry | `src/bin.ts` (`#!/usr/bin/env bun`) — argv, stdout, exit code only |
 | stdout | `write-line.ts`'s `writeLine` — synchronous fd 1, never `process.stdout.write`, which truncates at the 64KB pipe buffer when `process.exit` follows. Exported, because `create-ultimate`'s entry point needs the same one |
+| stderr | `write-line.ts`'s `writeErrorLine` — the same loop on fd 2, for a line that is not the command's answer. A `CommandResult` declaring `stream: 'stderr'` is routed there by `dispatch.ts`'s `sinkFor`, and `x mcp serve --transport stdio` is the one case: its fd 1 carries JSON-RPC frames, so the `✓ mcp stdio serving 13 tools` line rendered after the loop was a malformed frame. Neither renderer carries `stream`, exactly like `hold` |
+| Boot logs under `--json` | `dispatch.ts` calls core's `setLogStream('stderr')` when `args.json` is set, once, for all thirty commands. `x db migrate --json` printed the boot logger's `ultimate migrate applied` and then the command's own object, so `json.load` raised on the second document. A server's stdout stays its log stream; this is the CLI process only |
 | Numeric flags | `flag-number.ts` — one reader for `--port` / `--workers` / `--shard`. A bare `Number.parseInt` accepts `4abc` and answers `NaN`, which turned three checks into ones that cannot fail |
 | Shell quoting | `shell-quote.ts`'s `quoteArg` — every value the CLI pastes into a `fix:` or a reproduce line, `exec.ts`'s missing-program refusal and `test-shards.ts`'s reproduce command both. A name holding a space or a `;` interpolated bare is an instruction that runs something else |
 | Missing positionals | `MissingPositionalError`, never `BadFlagError` (names a flag that does not exist) and never `UnknownCommandError` (says a known command form is not one). Its `example` is a REAL invocation — `x g route <name>` in a shell is a redirect |
-| 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>`, never `x <command> --help`: the subcommand is resolved *after* the flag loop, so the latter throws the same error again — a fix line that reproduced its own failure |
+| 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`) |
@@ -533,6 +535,7 @@ hand-written layout and `readMigrations` skips it — read as a migration it sor
 | `dev-queue.ts` | the db + queue pair alone, and the one place that takes every ambient accessor back |
 | `dev-runtime.ts` | start the rest on top of it and install the remaining accessors (storage, mail, transport) |
 | `dev-cache.ts` | which cache tiers this process reads through, and the cross-instance invalidation hop |
+| `dev-purge.ts` | the hourly retention sweep: which framework tables this boot owns, the `purge()` job over them and the `task` that fires it |
 | `dev-sync.ts` | the `sync` role: its live-query registry, who is dialling it, and the socket it owns |
 | `runtime-overrides.ts` | the one field a host hands the framework a driver through |
 | `sync-authenticator.ts` | the app's HTTP authenticator, seen as the sync node's |
@@ -600,6 +603,8 @@ relay draining it.
 | the durable scheduler | `pgSchedulerState` + `createPgLeaseLeader` in `startRoles` | a watermark forgotten on restart, and every replica its own leader |
 | the Postgres event bus | `dev-queue.ts` | `step.waitForEvent` forgot every correlation on restart |
 | the shared idempotency store | `dev-queue.ts` | a retry on another replica charged the card twice |
+| the shared auth limiter | `configureAuthLimiters` in `startServices` | account lockouts counted per POD, so N replicas granted `maxAttempts × N` guesses |
+| the retention sweep | `dev-purge.ts`, declared in `startServices` | three `purgeExpired()` with no caller — every row `x_idempotency`, `x_rate_limit` and `x_auth_*` ever took was kept |
 | the cache tiers | `dev-cache.ts` | only the CDN tier was registered; memo, LRU and Redis had zero callers |
 | WebSocket authentication | `dev-sync.ts` | `actorId: null` on every socket — realtime was single-tenant by wiring |
 | OTLP export | `otlp-export.ts` | the chart set the variable and no code read it |
@@ -767,9 +772,12 @@ Promoting it to `x verify`'s `boundaries` host check is one line in `scripts/ver
 rule over names. Two stronger rules were measured and rejected: "the read must not be a property
 initializer" reports six flags, five of which work (`x db --allow-destructive`, `x jobs --queue`);
 "the summary must match the behaviour" is undecidable. So the flag's summary now says what it does,
-and forcing a reload stays what it always was — `@ultimat3/pwa`'s `updateSignal({ reason:
-'security' })`, which `As of 2026-08` has **no runtime caller anywhere**, in that package or
-outside it. Wiring the flag means giving that function a caller first.
+and forcing a reload is **not a thing this framework does**, `As of 2026-08`. `updateSignal`
+had no runtime caller for four majors and 9.0.0 deleted it rather than wiring it: `pwa` is tier 4
+and the two runtimes holding both build ids — `http` (2) and `sync` (3) — are below it, so no
+legal import could ever have reached the function. A deploy command has no channel to a running
+client regardless; the plan is `docker compose up` or `helm upgrade`. What ships is notification:
+`useConnection().updateAvailable` from `@ultimat3/realtime`.
 
 ## Planned commands are commands
 
@@ -833,6 +841,18 @@ refuses). A guard returning `[1n]` is `X_GUARD_FINDING_INVALID`, per candidate,
 entry costs its own line and not the real findings beside it. The mechanism whose job is producing
 structured failures handing back a stack trace is the one outcome it exists to prevent.
 
+**`x new` ships four guards, `As of 2026-08-22`.** The scaffolded `AGENTS.md` states nine
+non-negotiables, and five of them used to be prose — each proven green on `x verify`: a hardcoded
+JSX string beside a `t()` call, `color: #ff0000` in a stylesheet whose own scaffolded header called
+it "a lint failure", `toLocaleDateString('en-US')` with no `timeZone`, `t.number` money, and a bare
+`throw new Error` in a repo. Four of the five are now guards the scaffold writes —
+`guard-raw-colour`, `guard-unzoned-date`, `guard-bare-error`, `guard-untranslated-string` — so the
+rule is a build error the day the app is created rather than a sentence an agent may skip. The
+fifth, money-as-float, has **no static signature**; the scaffolded `AGENTS.md` row now points at the
+`MoneyInput` type error that already fires, because shipping a guard that cannot work is worse than
+naming the mechanism that does. Their codes are app codes derived from the guard name, so none of
+them appears in `wiki/Error-Codes.md` or the manifest.
+
 `x g guard <name>` writes `guards/<name>.ts` and its test, and nothing else — no index, no
 registry row, no manifest entry. The emitted rule is the class of failure a guard exists for: a
 migration that adds a `NOT NULL` column with no `DEFAULT` applies cleanly to an empty local

package/README.md

@@ -53,13 +53,18 @@ x verify --json
 ## `x verify` steps
 
 `typecheck lint boundaries filesize package-shape errors unit contract live job e2e eval drift
-contract-diff budgets manifest roadmap`
+contract-diff budgets seo i18n manifest roadmap`
 
-Seventeen, in cost order, defined once as `VERIFY_STEP_NAMES` (`verify-step.ts`) — the summary
+Nineteen, 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.
-There is no `--only` and no `--skip`; the exit code is non-zero if any step fails.
+
+`--only <step>` runs one step, for an iteration loop — it prints `NOT A GATE RUN` in the human
+summary **and** in `--json` (`data.notAGateRun`), and it writes no floor file. **The gate is this
+command with no flag**, which is what "one command means shippable" means. There is no `--skip`:
+a knob that removes a step from a run that still calls itself the gate is the one thing this
+command must not offer. The exit code is non-zero if any step fails.
 
 A committed `x.verify.json` is the floor, `As of 2026-08`: it names the steps this repo has already
 proved it can run, and a step it names that reports nothing is `X_VERIFY_SUITE_VANISHED` rather

package/package.json

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

package/src/app-boundaries.ts

@@ -15,8 +15,9 @@ import { join as joinPath } from 'node:path';
 // The POSIX variants resolve specifiers against import-graph keys, which are POSIX on every host.
 import { dirname, join, normalize, relative } from 'node:path/posix';
 import type { BoundaryRule, ImportGraph } from '@ultimat3/render';
-import { checkSurfaceBoundary, importGraph } from '@ultimat3/render';
+import { checkSurfaceBoundary, importGraph, SURFACES } from '@ultimat3/render';
 import type { Finding } from './output';
+import { quoteArg } from './shell-quote';
 
 export const BOUNDARY_CODES = [
   'X_BOUNDARY_SITE_TO_APP',
@@ -132,8 +133,57 @@ const surfaceFindings = (graph: ImportGraph): readonly Finding[] =>
     };
   });
 
-/** `apps/web/app/posts/service.ts` → `posts`: the primitive a generator would be told to make. */
-const subjectOf = (path: string, fallback: string): string => path.split('/').at(-2) ?? fallback;
+/**
+ * The surface names, from `@ultimat3/render`'s own list rather than a copy: a resource can never
+ * be called one, because the directory carrying that name is the surface itself.
+ */
+const SURFACE_NAMES: ReadonlySet<string> = new Set<string>(SURFACES);
+
+/**
+ * `apps/web/app/posts/service.ts` → `posts`: the primitive a generator would be told to make.
+ *
+ * `undefined` at a surface ROOT, where the directory above the file is the surface. The old
+ * answer there was the surface's own name, so `X_BOUNDARY_ROUTE_TO_DB` on `apps/web/site/page.tsx`
+ * said `x g query site` — a runnable line that generates seven files and a `sites` table for a
+ * landing page whose only problem is one import. A fix that does the wrong thing successfully is
+ * worse than one that refuses, so the caller names the file and asks for a name instead.
+ */
+function subjectOf(path: string): string | undefined {
+  const parent = path.split('/').at(-2);
+  return parent === undefined || SURFACE_NAMES.has(parent) ? undefined : parent;
+}
+
+/**
+ * Control characters, `\u00xx`-escaped. The path is a value read off the repository being scanned,
+ * and it rides in a `#` comment: a directory holding a NEWLINE ends that comment, so everything
+ * after it is a second command in a line whose whole purpose is to be pasted into a shell.
+ * Escaped rather than deleted, because the comment still has to name the file the reader owns.
+ */
+const commentSafe = (path: string): string =>
+  [...path]
+    .map((char) => {
+      const code = char.codePointAt(0) ?? 0;
+      return code < 0x20 || code === 0x7f ? `\\u${code.toString(16).padStart(4, '0')}` : char;
+    })
+    .join('');
+
+/**
+ * `x g query posts` where the path names a resource, `x g query <name>` where it names a surface.
+ * The placeholder form is the shape `MissingPositionalError` already hands out (`x g route
+ * <name>`) and the one the `errors` step leaves unjudged in that slot — an open positional, where
+ * a reader substituting a word makes the line run. The path rides in the `#` comment because a
+ * `fix:` is copied on its own, and `Finding.at` is a field an agent pasting one line never sees.
+ *
+ * BOTH halves come from the scanned path, so both are hostile: the subject is an ARGUMENT and goes
+ * through `quoteArg` — a directory named `posts; id` emitted a fix that ran `id` — and the comment
+ * goes through `commentSafe`. `<name>` alone stays literal: it is a placeholder a reader replaces,
+ * and `'<name>'` would be pasted as a resource actually called that.
+ */
+const generate = (kind: 'query' | 'action', path: string, then: string): string => {
+  const subject = subjectOf(path);
+  const named = subject === undefined ? '<name>' : quoteArg(subject);
+  return `x g ${kind} ${named}   # ${then} ${commentSafe(path)}`;
+};
 
 /**
  * Both fixes are one runnable line, with the rest of the instruction behind a `#` — a fix a
@@ -147,7 +197,7 @@ function layerFindings(scanned: readonly ScannedFile[]): readonly Finding[] {
         findings.push({
           code: 'X_BOUNDARY_ROUTE_TO_DB',
           cause: `route imports the database ("${specifier}") — routes call actions and queries`,
-          fix: `x g query ${subjectOf(file.path, 'rows')}   # then call it from the route`,
+          fix: generate('query', file.path, 'then call it from'),
           docs: docs('X_BOUNDARY_ROUTE_TO_DB'),
           at: file.path,
         });
@@ -156,7 +206,7 @@ function layerFindings(scanned: readonly ScannedFile[]): readonly Finding[] {
         findings.push({
           code: 'X_BOUNDARY_SERVICE_TO_HTTP',
           cause: `service imports HTTP ("${specifier}") — a service that knows about requests cannot be reused by a job`,
-          fix: `x g action ${subjectOf(file.path, 'service')}   # read the request there, pass the service plain values`,
+          fix: generate('action', file.path, 'read the request there and pass plain values to'),
           docs: docs('X_BOUNDARY_SERVICE_TO_HTTP'),
           at: file.path,
         });

package/src/app-load.ts

@@ -11,6 +11,13 @@ import { localeConfig } from '@ultimat3/i18n';
 import type { ErrorCodeFact } from '@ultimat3/manifest';
 import { registerQueries } from '@ultimat3/query';
 import { isRouteConfig, pageComponentOf, registerRoute } from '@ultimat3/render';
+// For the SIDE EFFECT, and it is this module's to hold: importing `@ultimat3/render/server`
+// installs the `.tsx`/`.scss` Bun plugin, a plugin only transforms modules loaded AFTER it, and
+// every app module below is loaded by the dynamic `import()` in this file. Before the render
+// barrel split it came free with the line above; after it, the only other path to `/server` from
+// here is six hops through `error-contract` → `fix-command` → the command registry, which is an
+// accident one refactor away from compiling every app's `.tsx` to `React.createElement`.
+import '@ultimat3/render/server';
 import { collectDeclaredCodes } from './error-contract';
 import type { Finding } from './output';
 import { findingFrom } from './output';

package/src/bin.ts

@@ -3,9 +3,11 @@
 // dispatch.ts, so the whole CLI is testable without spawning a process.
 
 import { dispatch } from './dispatch';
-// The write itself is `write-line.ts`: `create-ultimate`'s entry point needs the identical one,
-// and a second copy of a note about pipe truncation is a second copy that drifts.
-import { writeLine } from './write-line';
+// The writes themselves are `write-line.ts`: `create-ultimate`'s entry point needs the identical
+// one, and a second copy of a note about pipe truncation is a second copy that drifts. Two sinks,
+// because fd 1 is not always this process's to write on — `x mcp serve --transport stdio` hands it
+// to the protocol, and `dispatch` addresses that result to the second.
+import { writeErrorLine, writeLine } from './write-line';
 
 const code = await dispatch({
   argv: Bun.argv.slice(2),
@@ -13,6 +15,7 @@ const code = await dispatch({
   env: Bun.env,
   bunVersion: Bun.version,
   write: writeLine,
+  writeError: writeErrorLine,
 });
 
 process.exit(code);

package/src/cmd-db-backfill.ts

@@ -0,0 +1,240 @@
+// `x db backfill`'s wiring alone: which of the four shapes an invocation asked for, and the one
+// finding-and-table projection each answers with. Split from `cmd-db.ts` the way `cmd-db-branch.ts`
+// was — that file had reached the 500-line ceiling, and "which subcommand ran" and "what a sweep
+// pass reports" are two jobs. The facts live in `db-backfill.ts`; nothing here opens a database.
+
+import { resolveEnvironment } from '@ultimat3/core';
+import { BackfillPendingError } from '@ultimat3/jobs';
+import { loadApp } from './app-load';
+import type { CommandContext } from './command';
+import type { BackfillAction, BackfillPlanRow } from './db-backfill';
+import {
+  listBackfills,
+  pendingReport,
+  pendingToJson,
+  planToJson,
+  readAppliedMigrations,
+  renderBackfillTable,
+  renderPendingTable,
+  renderPlanTable,
+  runBackfills,
+} from './db-backfill';
+import { BadFlagError } from './errors';
+import { withJobDriver } from './jobs-driver';
+import { backfillToJson } from './jobs-json';
+import { msg } from './messages';
+import type { CommandResult } from './output';
+import { findingFrom } from './output';
+import type { ParsedArgs } from './parse';
+import { flagBool, flagString } from './parse';
+
+/** Which of the four questions an invocation asked. `pass` is `<name>` and `--all` both. */
+type BackfillShape = 'list' | 'pending' | 'pass';
+
+/**
+ * Every flag that belongs to exactly ONE shape — `x db backfill`'s own usage line, executable.
+ *
+ * `--name` is absent because it is two things: `--list`'s filter and the pass's target, decided by
+ * `readShape` below. Everything else reads for one shape and is ignored by the other two, which is
+ * the silence this table ends.
+ */
+const SHAPE_OF_FLAG = Object.freeze<Record<string, BackfillShape>>({
+  status: 'list',
+  limit: 'list',
+  write: 'pass',
+  force: 'pass',
+});
+
+/** One runnable line per shape, so a refusal hands back the invocation the caller meant. */
+const FIX_OF_SHAPE = Object.freeze<Record<BackfillShape, string>>({
+  list: 'x db backfill --list --json',
+  pending: 'x db backfill --pending --json',
+  pass: 'x db backfill --all --write --json',
+});
+
+const refuseShape = (flag: string, reason: string, fix: string): never => {
+  throw new BadFlagError({ flag, command: 'db', reason, fix });
+};
+
+/**
+ * Exactly one shape, and only the flags that shape reads — refused before anything opens a
+ * database, never resolved by precedence.
+ *
+ * Precedence is what this replaces, and it was silent in the dangerous direction:
+ * `x db backfill cleanup --all --write` took the `--all` branch and ENQUEUED every pending sweep
+ * while the operator had named one, and `--list --pending` reported the ledger for a command that
+ * asked what was unswept. Axiom 1 — one way to do each thing — makes a second reading of one argv
+ * a refusal rather than a choice the command makes on the caller's behalf.
+ */
+function readShape(args: ParsedArgs): { readonly shape: BackfillShape; readonly name?: string } {
+  const list = flagBool(args, 'list');
+  const positional = args.positionals[0];
+  const named = flagString(args, 'name');
+  // `--name` is a FILTER under `--list` and a target everywhere else, so it selects a shape only
+  // where `--list` is absent. Two spellings of one target are still two, and are refused.
+  const target = list ? undefined : (positional ?? named);
+  if (!list && positional !== undefined && named !== undefined) {
+    return refuseShape(
+      'name',
+      `x db backfill names two backfills ("${positional}" and "${named}") — a pass sweeps the positional or --name, never both`,
+      `x db backfill ${positional} --write --json`,
+    );
+  }
+  const asked = [
+    ...(list ? ['--list'] : []),
+    ...(flagBool(args, 'pending') ? ['--pending'] : []),
+    ...(flagBool(args, 'all') ? ['--all'] : []),
+    ...(target === undefined ? [] : [target]),
+  ];
+  if (asked.length > 1) {
+    // The SECOND shape is the one that would have been dropped, so it is the one the cause names:
+    // `--all` won over a named sweep and the operator was never told which of the two ran.
+    const second = asked[1] ?? '';
+    return refuseShape(
+      second.startsWith('--') ? second.slice(2) : 'name',
+      `x db backfill was asked for ${asked.join(' and ')} — one shape per invocation: --list, --pending, <name> or --all`,
+      `x db backfill ${asked[0]} --json`,
+    );
+  }
+  if (asked.length === 0) {
+    return refuseShape(
+      'list',
+      'x db backfill needs a shape: --list (the ledger), --pending (declared minus completed), <name> or --all (run one, or every pending one)',
+      'x db backfill --pending --json',
+    );
+  }
+  const shape: BackfillShape = list ? 'list' : flagBool(args, 'pending') ? 'pending' : 'pass';
+  for (const [flag, owner] of Object.entries(SHAPE_OF_FLAG)) {
+    if (owner === shape || !args.flags.has(flag)) continue;
+    refuseShape(
+      flag,
+      `x db backfill --${flag} belongs to ${owner === 'pass' ? 'a <name>/--all pass' : `--${owner}`}, and this invocation asked for ${asked[0]}`,
+      FIX_OF_SHAPE[owner],
+    );
+  }
+  return target === undefined ? { shape } : { shape, name: target };
+}
+
+/**
+ * Four shapes, one subcommand: `--list` reads the `x_backfills` ledger, `--pending` diffs it
+ * against what the app DECLARED, and `<name>` / `--all` gate a pass and put it on the queue. A
+ * bare `x db backfill` is still refused rather than defaulted — the four answer four different
+ * questions, and picking one for the operator is the ambiguity axiom 1 exists to refuse.
+ *
+ * An empty ledger is `ok: true`. "Nothing has swept this database yet" is an answer to the
+ * question asked, and a command that failed over it would be unrunnable on a fresh app.
+ */
+export async function runBackfillCommand(
+  ctx: CommandContext,
+  root: string,
+): Promise<CommandResult> {
+  const asked = readShape(ctx.args);
+  if (asked.shape === 'list') return runBackfillList(ctx, root);
+  if (asked.shape === 'pending') return runBackfillPending(ctx, root);
+  return runBackfillPass(ctx, root, asked.name === undefined ? 'all' : [asked.name]);
+}
+
+async function runBackfillList(ctx: CommandContext, root: string): Promise<CommandResult> {
+  return withJobDriver(root, ctx, async (driver) => {
+    const rows = await listBackfills(driver, {
+      name: flagString(ctx.args, 'name'),
+      status: flagString(ctx.args, 'status'),
+      limit: flagString(ctx.args, 'limit'),
+    });
+    return {
+      ok: true,
+      command: 'db',
+      summary:
+        rows.length === 0
+          ? msg('cli.db.backfill.empty')
+          : msg('cli.db.backfill.listed', { count: rows.length }),
+      lines: rows.length === 0 ? [] : renderBackfillTable(rows).map((line) => `  ${line}`),
+      data: rows.map(backfillToJson),
+    };
+  });
+}
+
+/**
+ * The alarm the framework did not have. Non-zero when anything is unswept, so a cron or a deploy
+ * check can read the exit code — a `--json` nobody has to parse to know something is wrong.
+ * `loadApp` first: importing the app's modules IS the declaration, and a diff run without it
+ * would report a clean database against an empty declaration list.
+ */
+async function runBackfillPending(ctx: CommandContext, root: string): Promise<CommandResult> {
+  await loadApp(root);
+  const environment = resolveEnvironment({ env: ctx.env });
+  return withJobDriver(root, ctx, async (driver) => {
+    const report = await pendingReport(driver, environment);
+    return {
+      ok: report.pending.length === 0,
+      command: 'db',
+      summary:
+        report.pending.length === 0
+          ? msg('cli.db.backfill.swept', { declared: report.rows.length })
+          : msg('cli.db.backfill.pending', {
+              count: report.pending.length,
+              declared: report.rows.length,
+            }),
+      findings: report.pending.map((row) =>
+        findingFrom(new BackfillPendingError({ backfill: row.name, environment })),
+      ),
+      lines: report.rows.length === 0 ? [] : renderPendingTable(report).map((line) => `  ${line}`),
+      data: pendingToJson(report),
+    };
+  });
+}
+
+/**
+ * DRY RUN by default: `--write` is never implied, because the alternative is a command whose
+ * inspection form writes to a production table. What `--write` does is ENQUEUE — the queue is a
+ * job's execution surface, so the sweep runs on the workers already serving the new release
+ * rather than inside this process.
+ */
+async function runBackfillPass(
+  ctx: CommandContext,
+  root: string,
+  names: readonly string[] | 'all',
+): Promise<CommandResult> {
+  await loadApp(root);
+  const environment = resolveEnvironment({ env: ctx.env });
+  const write = flagBool(ctx.args, 'write');
+  return withJobDriver(root, ctx, async (driver) => {
+    const rows = await runBackfills({
+      driver,
+      names,
+      write,
+      force: flagBool(ctx.args, 'force'),
+      environment,
+      appliedMigrations: await readAppliedMigrations(),
+    });
+    return backfillPassResult(rows, write);
+  });
+}
+
+/**
+ * A blocked or deduped name is a finding and a non-zero exit, and every OTHER name still ran —
+ * that isolation is what stops one wedged cleanup blocking every later one forever.
+ */
+function backfillPassResult(rows: readonly BackfillPlanRow[], write: boolean): CommandResult {
+  const findings = rows.flatMap((row) => (row.finding === null ? [] : [row.finding]));
+  // Counted per action, never derived from the total: a deduped pass is neither enqueued nor
+  // blocked, and `rows.length - enqueued` reported it as blocked while `--json` reported it as
+  // deduped. `planToJson` is the same list, so the two renders now add up to the same run.
+  const tally = (action: BackfillAction): number =>
+    rows.filter((row) => row.action === action).length;
+  return {
+    ok: findings.length === 0,
+    command: 'db',
+    summary: write
+      ? msg('cli.db.backfill.planned', {
+          count: rows.length,
+          enqueued: tally('enqueued'),
+          deduped: tally('deduped'),
+          blocked: tally('blocked'),
+        })
+      : msg('cli.db.backfill.dryRun', { count: rows.length }),
+    findings,
+    lines: rows.length === 0 ? [] : renderPlanTable(rows).map((line) => `  ${line}`),
+    data: planToJson(rows),
+  };
+}

package/src/cmd-db-branch.ts

@@ -3,6 +3,7 @@
 // `x db branch ls` used to clone a database called `ls`, because the argument was the name.
 // The facts (what a branch is, per mode) are `db-branch.ts`; the client lifetime is here.
 
+import { nearestName } from '@ultimat3/core';
 import { createPostgresClient, type DbClient } from '@ultimat3/db';
 import type { CommandContext } from './command';
 import type { BranchRow } from './db-branch';
@@ -27,7 +28,7 @@ import { resolveServices } from './dev-services';
 import { MissingPositionalError, UnknownCommandError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
-import { flagString, nearest } from './parse';
+import { flagString } from './parse';
 import { portFromEnv } from './serve';
 import { renderTable } from './table';
 
@@ -46,7 +47,7 @@ const LIST_FIX = `x ${LIST_ARGV}`;
  * `x` excluded — the error class adds it.
  */
 function branchRetry(word: string, name: string | undefined): string {
-  const near = nearest(word, [...BRANCH_SUBCOMMANDS]);
+  const near = nearestName(word, [...BRANCH_SUBCOMMANDS]);
   if (near !== undefined) return name === undefined ? LIST_ARGV : `db branch ${near} ${name}`;
   return isBranchName(word) ? `db branch create ${word}` : LIST_ARGV;
 }