@ultimat3/cli 1.2.0 → 3.0.0

package/src/cmd-db.ts

@@ -1,187 +1,492 @@
-// `x db gen|migrate|reset|studio|branch` — everything that touches the database, including the
-// branch DB that makes destructive work safe. An agent that can clone the database in a second
-// can migrate, seed and break things without a human deciding whether to let it.
+// `x db gen|migrate|reset|seed|studio|branch|backfill` — everything that touches the database. One
+// subcommand per line and no fall-through: a word this file does not know is refused, never
+// re-read as an argument to the last branch. `branch` itself is `cmd-db-branch.ts`.
+//
+// Every subcommand here runs `@ultimat3/db`'s own engine, which is the engine `ROLE=migrate` runs
+// (`serve.ts`): one `x_migrations` ledger, one checksum rule, one advisory lock, from a laptop to
+// a release phase. Until 1.2.0 these shelled out to `bunx drizzle-kit` — a second engine with a
+// second journal, declared in no `package.json` and fetched unpinned at run time.
 
-import { existsSync, readdirSync } from 'node:fs';
+// `node:fs/promises` for `rm` — `Bun.file().delete()` takes one file, and `x db reset` removes a
+// directory tree. `node:path` for `join` — Bun exposes no path joiner.
 import { rm } from 'node:fs/promises';
 import { join } from 'node:path';
-import { branchPglite } from '@ultimat3/db';
+import { resolveEnvironment } from '@ultimat3/core';
+import { type DriftReport, driftError, withTransaction } from '@ultimat3/db';
+import { postgresDriver } from '@ultimat3/entity';
+import { BackfillPendingError } from '@ultimat3/jobs';
+import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
+import { runBranchCommand } from './cmd-db-branch';
+import { plannedSubcommand } from './cmd-planned';
 import type { CliCommand, CommandContext } from './command';
+import type { BackfillAction, BackfillPlanRow } from './db-backfill';
+import {
+  listBackfills,
+  pendingReport,
+  pendingToJson,
+  planToJson,
+  readAppliedMigrations,
+  renderBackfillTable,
+  renderPendingTable,
+  renderPlanTable,
+  runBackfills,
+} from './db-backfill';
+import { BRANCH_SUBCOMMANDS } from './db-branch';
+import { stepFinding } from './db-finding';
+import { generateAppMigration } from './db-generate';
+import type { SeedPassRow } from './db-seed';
+import {
+  discoverSeeds,
+  parseSeedTierFlag,
+  renderSeedTable,
+  runSeeds,
+  seedPassToJson,
+  seedTotals,
+  selectSeeds,
+} from './db-seed';
 import { resolveServices } from './dev-services';
-import { checkDrift, writeSchemaHash } from './drift';
-import { CliNotImplementedError } from './errors';
-import type { ExecResult } from './exec';
-import { execOutput } from './exec';
+import {
+  BadFlagError,
+  CliNotImplementedError,
+  MissingSubcommandError,
+  UnknownCommandError,
+} from './errors';
+import { withJobDriver } from './jobs-driver';
+import { backfillToJson } from './jobs-json';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import { findingFrom } from './output';
-import { flagString } from './parse';
+import { flagBool, flagString } from './parse';
+import { runMigrations } from './serve';
 
-export const DB_SUBCOMMANDS = ['gen', 'migrate', 'reset', 'studio', 'branch'] as const;
+export const DB_SUBCOMMANDS = [
+  'gen',
+  'migrate',
+  'reset',
+  'seed',
+  'studio',
+  'branch',
+  'backfill',
+] as const;
 
-const failure = (result: ExecResult, code: string, fix: string): Finding => ({
-  code,
-  cause: `${result.command.join(' ')} exited ${result.code}: ${execOutput(result).slice(0, 400)}`,
-  fix,
-  docs: `https://ultimate.dev/errors/${code}`,
-});
+export const dbCommand: CliCommand = {
+  spec: {
+    name: 'db',
+    summary: 'gen, migrate, reset, seed, studio, branch, backfill',
+    usage:
+      'x db gen "add publish_at" | migrate | reset | seed [<name>] [--tier reference|dev] [--dry-run] | studio | branch ls | branch create <name> | branch drop <name> | backfill [<name>|--all] [--write] [--force] | backfill --pending | backfill --list [--name n] [--status s] [--limit n]',
+    requiresApp: true,
+    subcommands: DB_SUBCOMMANDS,
+    // Declared from the constant `runBranchCommand` validates against, never a second literal: it
+    // is what lets the `errors` step resolve `x db branch ls` — a fix line three shipped errors
+    // hand out, which read `ls` as a branch name and cloned a database until 1.2.x.
+    subcommandPositionals: { branch: BRANCH_SUBCOMMANDS },
+    flags: [
+      {
+        name: 'name',
+        type: 'string',
+        summary: 'migration, branch or seed name, or backfill to filter',
+      },
+      {
+        name: 'tier',
+        type: 'string',
+        summary: 'seed: which tier to run — reference or dev; also ULTIMATE_SEED_TIER',
+      },
+      {
+        name: 'dry-run',
+        type: 'boolean',
+        summary: 'seed: report what each seed would write, and write nothing',
+      },
+      { name: 'list', type: 'boolean', summary: 'backfill: print the x_backfills ledger' },
+      {
+        name: 'pending',
+        type: 'boolean',
+        summary: 'backfill: declared minus completed; non-zero exit when anything is unswept',
+      },
+      { name: 'all', type: 'boolean', summary: 'backfill: every pending sweep, isolated per name' },
+      { name: 'write', type: 'boolean', summary: 'backfill: enqueue the pass; dry run without it' },
+      {
+        name: 'force',
+        type: 'boolean',
+        summary: 'backfill: sweep a name the ledger records as completed, as a NEW ledger row',
+      },
+      {
+        name: 'status',
+        type: 'string',
+        summary: 'backfill: filter by running, completed or failed',
+      },
+      { name: 'limit', type: 'string', summary: 'backfill: max ledger rows to return' },
+      // Declared because `X_MIGRATION_IRREVERSIBLE`'s own fix line names it. A `fix:` is copied
+      // and run verbatim, so a flag the parser refuses would make the error unfollowable.
+      {
+        name: 'allow-destructive',
+        type: 'boolean',
+        summary: 'let x db gen emit a drop whose down cannot restore the rows',
+      },
+    ],
+  },
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const root = requireAppRoot('db', ctx.cwd).dir;
+    // No default, and no `?? 'migrate'` here either: `gen` writes a migration file and `reset`
+    // drops the database, so "whatever the caller left out" is not a safe guess for any of the six.
+    // The parser refuses a bare `x db`; this covers a `ParsedArgs` built by hand.
+    const sub = ctx.args.subcommand;
+    if (sub === undefined)
+      throw new MissingSubcommandError({ command: 'db', known: DB_SUBCOMMANDS });
+    const argument = ctx.args.positionals[0] ?? flagString(ctx.args, 'name');
 
-/** `x db branch <name>` on a real Postgres: copy-on-write clone, cheap and disposable. */
-export function branchSql(source: string, branch: string): string {
-  return `CREATE DATABASE "${branch}" TEMPLATE "${source}"`;
-}
+    if (sub === 'gen') return runGen(ctx, root, argument ?? 'change');
+    if (sub === 'migrate') return runMigrate(ctx, root, msg('cli.db.migrate.applied'));
+    if (sub === 'reset') return runReset(ctx, root);
+    if (sub === 'seed') return runSeed(ctx, root);
+    if (sub === 'studio') throw plannedSubcommand('db', 'studio');
+    if (sub === 'backfill') return runBackfill(ctx, root);
+    if (sub === 'branch') return runBranchCommand(ctx, root);
 
-export function branchDatabaseName(source: string, branch: string): string {
-  return `${source}_branch_${branch.replace(/[^a-zA-Z0-9_]/g, '_')}`;
+    // Never a fall-through. This used to end `return runBranch(ctx, root, argument ?? 'preview')`,
+    // so ANY subcommand the parser had not already refused was reinterpreted as a branch NAME and
+    // cloned a database out of it. A word this command does not know is a refusal, not a guess.
+    throw new UnknownCommandError({
+      path: `db ${sub}`,
+      known: DB_SUBCOMMANDS,
+      // Help, and not the nearest name: `studio` is planned, and `branch`/`backfill` both need a
+      // word this refusal does not have — a suggestion that refuses in turn is not a fix.
+      suggestion: 'help db',
+    });
+  },
+};
+
+/**
+ * Source in, files out — no database is opened, so this answers the same in CI and on a laptop
+ * with nothing running. A diff that finds nothing writes no MIGRATION and still exits 0: "no
+ * change" is an answer, and an empty migration would take a ledger row and a checksum forever. It
+ * may still write the `.hash` sidecar `x verify`'s `drift` step reads, which is what makes
+ * `X_DB_DRIFT`'s `fix:` — this command — a real instruction rather than a no-op.
+ *
+ * So there are THREE answers, not two, and `--json` carries `outcome` on every one: collapsing
+ * `hash-recorded` into either neighbour tells the machine reading this output that a migration
+ * exists when none does, or that nothing was written when the sidecar was.
+ */
+async function runGen(ctx: CommandContext, root: string, name: string): Promise<CommandResult> {
+  let generated: Awaited<ReturnType<typeof generateAppMigration>>;
+  try {
+    generated = await generateAppMigration(root, {
+      name,
+      allowDestructive: flagBool(ctx.args, 'allow-destructive'),
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      command: 'db',
+      summary: msg('cli.db.gen.failed'),
+      findings: [stepFinding(error, 'X_DB_GEN_FAILED')],
+    };
+  }
+  const migration = generated.migration;
+  if (migration === undefined) {
+    return {
+      ok: generated.findings.length === 0,
+      command: 'db',
+      // The sidecar path, never a bare id: `hash-recorded` writes exactly one, and it is the file
+      // the `drift` step reads back.
+      summary:
+        generated.outcome === 'hash-recorded'
+          ? msg('cli.db.gen.recorded', { file: generated.files[0] ?? '' })
+          : msg('cli.db.gen.unchanged'),
+      findings: generated.findings,
+      // `files` is what this command WROTE, so the empty array here was a false claim.
+      lines: generated.files.map((file) => `  ${file}`),
+      data: {
+        outcome: generated.outcome,
+        migration: null,
+        files: [...generated.files],
+        schemaHash: generated.schemaHash ?? null,
+      },
+    };
+  }
+  return {
+    ok: true,
+    command: 'db',
+    summary: msg('cli.db.gen.written', { id: migration.id }),
+    lines: generated.files.map((file) => `  ${file}`),
+    data: {
+      outcome: generated.outcome,
+      migration: migration.id,
+      name: migration.name,
+      files: [...generated.files],
+      schemaHash: generated.schemaHash ?? null,
+    },
+  };
 }
 
-export const previewUrl = (branch: string, port: number): string =>
-  `http://${branch}.localhost:${port}`;
+/**
+ * The post-migrate report, rendered. Through `driftError` rather than a second literal: the
+ * three-line `X_DB_DRIFT` output is pinned by the framework contract, and this command must not be
+ * where a copy of it drifts from the one `x verify` prints.
+ */
+export const driftFindings = (report: DriftReport): readonly Finding[] =>
+  report.differences.map((difference) => findingFrom(driftError(difference)));
 
-async function runBranch(
+/**
+ * `runMigrations` is `serve.ts`'s, unchanged and unwrapped: the developer applying a migration and
+ * the release-phase container applying it run the same function, over the same file list, through
+ * the same ledger, and verify the same post-condition — the live schema against that ledger. A
+ * database that migrated cleanly and still disagrees is the failure this command exists to
+ * surface, and only a check that opened the connection can see it.
+ *
+ * The *source* half — an entity edited with no migration generated — is `x verify`'s `drift` step
+ * (`checkSourceDrift`) and is deliberately not repeated here: two reporters of one condition is the
+ * duplication this package's own rule forbids, and that one needs no database at all.
+ */
+async function runMigrate(
   ctx: CommandContext,
   root: string,
-  branch: string,
+  summary: string,
 ): Promise<CommandResult> {
+  try {
+    const migrated = await runMigrations({ root, env: ctx.env });
+    const report = migrated.report;
+    return {
+      ok: migrated.drift.ok,
+      command: 'db',
+      summary,
+      findings: driftFindings(migrated.drift),
+      data: {
+        applied: report.applied.map((entry) => entry.id),
+        skipped: report.skipped.length,
+        appVersion: report.appVersion,
+        durationMs: report.durationMs,
+      },
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      command: 'db',
+      summary: msg('cli.db.migrate.failed'),
+      findings: [stepFinding(error, 'X_DB_MIGRATE_FAILED')],
+    };
+  }
+}
+
+/**
+ * Embedded only: `rm -rf` against a database this process does not own is not a reset, it is an
+ * outage. The data directory goes before the migrator starts, so the run that follows is a fresh
+ * database with an empty ledger rather than a re-apply over a live one.
+ */
+async function runReset(ctx: CommandContext, root: string): Promise<CommandResult> {
   const services = resolveServices(root, ctx.env);
-  const port = Number.parseInt(ctx.env['PORT'] ?? '3000', 10);
-  const url = previewUrl(branch, port);
-  if (services.db.mode === 'embedded') {
-    // @ultimat3/db owns embedded branching, name validation and the on-disk layout. Shelling out
-    // to `cp` here was a second implementation of all three — and `--reflink` is a GNU-only flag.
-    try {
-      const info = await branchPglite(branch, { from: services.db.url });
-      return {
-        ok: true,
-        command: 'db',
-        summary: msg('cli.db.branch.ready', { name: branch }),
-        data: { branch, database: info.dataDir, preview: url, mode: 'embedded' },
-      };
-    } catch (error) {
-      return {
-        ok: false,
-        command: 'db',
-        summary: msg('cli.usage'),
-        findings: [findingFrom(error)],
-      };
-    }
+  if (services.db.mode === 'external') {
+    throw new CliNotImplementedError({
+      feature: 'x db reset against an external Postgres',
+      fix: 'drop and recreate the database yourself, then run: x db migrate',
+    });
   }
-  const source = services.db.url.split('/').at(-1) ?? 'postgres';
-  const database = branchDatabaseName(source, branch);
-  const psql = await ctx.runner(['psql', services.db.url, '-c', branchSql(source, database)], {
-    cwd: root,
+  await rm(join(services.stateDir, 'pgdata'), { recursive: true, force: true });
+  return runMigrate(ctx, root, msg('cli.db.reset.done'));
+}
+
+/**
+ * `x db seed [<name>]` — the fixture graph, applied and replayable.
+ *
+ * The environment is resolved BEFORE anything is imported or connected: a run this environment does
+ * not take must refuse without having opened a connection to the database it was refusing to write
+ * to. `selectSeeds` asks the same question a second time, on the seeds themselves, because seeding
+ * is the one irreversible thing this command does (`db-seed.ts`).
+ *
+ * `withJobDriver` is the boot, though nothing here claims a job: it is the CLI's one answer to
+ * "which database is this command talking to", and it also puts a real queue behind any
+ * `handle.enqueue()` a seeded write triggers. A second boot path would be a second answer.
+ */
+async function runSeed(ctx: CommandContext, root: string): Promise<CommandResult> {
+  const environment = resolveEnvironment({ env: ctx.env });
+  const requested = parseSeedTierFlag(
+    flagString(ctx.args, 'tier') ?? ctx.env['ULTIMATE_SEED_TIER'],
+  );
+  const name = ctx.args.positionals[0] ?? flagString(ctx.args, 'name');
+  const dryRun = flagBool(ctx.args, 'dry-run');
+  const discovery = await discoverSeeds(root);
+  const chosen = selectSeeds({
+    discovered: discovery.seeds,
+    ...(name === undefined ? {} : { name }),
+    environment,
+    requested,
   });
-  if (!psql.ok) {
+  if (chosen.length === 0) {
     return {
-      ok: false,
+      ok: true,
       command: 'db',
-      summary: msg('cli.usage'),
-      findings: [
-        failure(
-          psql,
-          'X_DB_BRANCH_FAILED',
-          `close open connections to "${source}" (a TEMPLATE clone needs none), then retry`,
-        ),
-      ],
+      summary: msg('cli.db.seed.none'),
+      findings: discovery.findings,
+      data: seedPassToJson([]),
     };
   }
+  return withJobDriver(root, ctx, async () => {
+    const rows = await runSeeds({
+      seeds: chosen,
+      driver: postgresDriver(),
+      dryRun,
+      env: ctx.env,
+      // One transaction per seed, so a seed that throws takes only its own rows with it.
+      transaction: (work) => withTransaction(() => work()),
+    });
+    return seedPassResult(rows, dryRun, discovery.findings);
+  });
+}
+
+function seedPassResult(
+  rows: readonly SeedPassRow[],
+  dryRun: boolean,
+  findings: readonly Finding[],
+): CommandResult {
+  const totals = seedTotals(rows);
+  const failures = rows.flatMap((row) => (row.finding === null ? [] : [row.finding]));
   return {
-    ok: true,
+    ok: failures.length === 0 && findings.length === 0,
     command: 'db',
-    summary: msg('cli.db.branch.ready', { name: branch }),
-    data: { branch, database, preview: url, mode: 'external' },
+    summary:
+      totals.failed > 0
+        ? msg('cli.db.seed.failed', { failed: totals.failed, count: rows.length })
+        : dryRun
+          ? msg('cli.db.seed.dryRun', { count: rows.length })
+          : msg('cli.db.seed.done', {
+              count: rows.length,
+              inserted: totals.inserted,
+              updated: totals.updated,
+              skipped: totals.skipped,
+            }),
+    findings: [...failures, ...findings],
+    lines: renderSeedTable(rows).map((line) => `  ${line}`),
+    data: seedPassToJson(rows),
   };
 }
 
-export const dbCommand: CliCommand = {
-  spec: {
-    name: 'db',
-    summary: 'gen, migrate, reset, studio, branch',
-    usage: 'x db gen "add publish_at" | migrate | reset | studio | branch <name>',
-    requiresApp: true,
-    subcommands: DB_SUBCOMMANDS,
-    flags: [{ name: 'name', type: 'string', summary: 'migration or branch name' }],
-  },
-  async run(ctx: CommandContext): Promise<CommandResult> {
-    const root = requireAppRoot('db', ctx.cwd).dir;
-    const sub = ctx.args.subcommand ?? 'migrate';
-    const argument = ctx.args.positionals[0] ?? flagString(ctx.args, 'name');
+/**
+ * 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.
+ */
+async function runBackfill(ctx: CommandContext, root: string): Promise<CommandResult> {
+  if (flagBool(ctx.args, 'list')) return runBackfillList(ctx, root);
+  const all = flagBool(ctx.args, 'all');
+  const name = ctx.args.positionals[0] ?? flagString(ctx.args, 'name');
+  if (flagBool(ctx.args, 'pending')) return runBackfillPending(ctx, root);
+  if (all) return runBackfillPass(ctx, root, 'all');
+  if (name !== undefined) return runBackfillPass(ctx, root, [name]);
+  throw new BadFlagError({
+    flag: 'list',
+    command: 'db',
+    reason:
+      'x db backfill needs a shape: --list (the ledger), --pending (declared minus completed), <name> or --all (run one, or every pending one)',
+    fix: 'x db backfill --pending --json',
+  });
+}
 
-    if (sub === 'gen') {
-      const name = (argument ?? 'change').replace(/[^a-zA-Z0-9]+/g, '_').toLowerCase();
-      const result = await ctx.runner(['bunx', 'drizzle-kit', 'generate', '--name', name], {
-        cwd: root,
-      });
-      if (!result.ok) {
-        return {
-          ok: false,
-          command: 'db',
-          summary: msg('cli.usage'),
-          findings: [failure(result, 'X_DB_GEN_FAILED', 'x doctor --json')],
-        };
-      }
-      const hash = await writeSchemaHash(root, latestMigration(root, name));
-      return {
-        ok: true,
-        command: 'db',
-        summary: `migration ${name} generated`,
-        data: { migration: name, schemaHash: hash },
-      };
-    }
-
-    if (sub === 'migrate') {
-      const result = await ctx.runner(['bunx', 'drizzle-kit', 'migrate'], { cwd: root });
-      const drift = await checkDrift(root);
-      return {
-        ok: result.ok && drift.length === 0,
-        command: 'db',
-        summary: result.ok ? 'migrations applied' : 'migration failed',
-        findings: result.ok ? drift : [failure(result, 'X_DB_MIGRATE_FAILED', 'x db reset')],
-        data: { applied: result.ok },
-      };
-    }
-
-    if (sub === 'reset') {
-      const services = resolveServices(root, ctx.env);
-      if (services.db.mode === 'external') {
-        throw new CliNotImplementedError({
-          feature: 'x db reset against an external Postgres',
-          fix: 'drop and recreate the database yourself, then run: x db migrate',
-        });
-      }
-      await rm(join(services.stateDir, 'pgdata'), { recursive: true, force: true });
-      const migrate = await ctx.runner(['bunx', 'drizzle-kit', 'migrate'], { cwd: root });
-      return {
-        ok: migrate.ok,
-        command: 'db',
-        summary: migrate.ok ? 'database reset and migrated' : 'reset failed',
-        findings: migrate.ok ? [] : [failure(migrate, 'X_DB_MIGRATE_FAILED', 'x doctor --json')],
-        data: { stateDir: services.stateDir },
-      };
-    }
-
-    if (sub === 'studio') {
-      const result = await ctx.runner(['bunx', 'drizzle-kit', 'studio'], { cwd: root });
-      return {
-        ok: result.ok,
-        command: 'db',
-        summary: result.ok ? 'studio exited' : 'studio failed to start',
-        findings: result.ok ? [] : [failure(result, 'X_DB_STUDIO_FAILED', 'x doctor --json')],
-      };
-    }
-
-    return runBranch(ctx, root, argument ?? 'preview');
-  },
-};
+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),
+    };
+  });
+}
 
-/** drizzle-kit names files `<index>_<name>.sql`; the hash sidecar has to match that base name. */
-function latestMigration(root: string, name: string): string {
-  const dir = join(root, 'packages', 'db', 'migrations');
-  if (!existsSync(dir)) return `0000_${name}`;
-  const matches = readdirSync(dir)
-    .filter((file) => file.endsWith(`_${name}.sql`))
-    .sort();
-  const newest = matches.at(-1);
-  return newest === undefined ? `0000_${name}` : newest.replace(/\.sql$/, '');
+/**
+ * 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),
+  };
 }