@ultimat3/cli 1.0.0

package/src/hold.ts

@@ -0,0 +1,48 @@
+// Staying up. A command whose server is still listening when `run` resolves is a command whose
+// process `bin.ts` exits out from under — so it hands back a hold, and `dispatch` awaits that
+// before the exit code. Ctrl-C then takes core's own three-phase drain (stop accepting, finish
+// in-flight, close) instead of killing a query mid-round-trip.
+
+import { drain, installSignalHandlers, onShutdown } from '@ultimat3/core';
+
+/**
+ * Wait for a shutdown, then release what core's lifecycle does not own.
+ *
+ * The wait is on the drain's first phase, never on a signal table of our own: core already owns
+ * which signals mean stop, and a second list here would be a second answer to that question. It
+ * also means anything else that calls `drain()` — a test, a supervisor, a later role — releases
+ * this command too.
+ *
+ * `release` runs after the drain completes, so in-flight requests still see the database the
+ * handler opened them against. It is the resources core never learned about: the embedded
+ * Postgres, the worker, the file watcher.
+ */
+export function holdUntilShutdown(name: string, release: () => Promise<void>): () => Promise<void> {
+  const uninstall = installSignalHandlers({ exit: false });
+  let unregister = (): void => {};
+  const shuttingDown = new Promise<void>((resolve) => {
+    unregister = onShutdown(
+      `cli:${name}:hold`,
+      () => {
+        resolve();
+      },
+      { phase: 'accept' },
+    );
+  });
+
+  let held: Promise<void> | undefined;
+  return () => {
+    // Memoised: awaiting a hold twice must not release twice, and `dispatch` is not the only
+    // caller a test can be.
+    held ??= (async () => {
+      await shuttingDown;
+      // Idempotent in core: this joins the drain already in flight and resolves when its last
+      // phase is done. Calling it is what makes `release` the step after the drain, not beside it.
+      await drain();
+      unregister();
+      uninstall();
+      await release();
+    })();
+    return held;
+  };
+}

package/src/i18n-audit.ts

@@ -0,0 +1,183 @@
+// Pure facts behind `x i18n`: the source scan, the catalogs on disk, the audit, and the seed/sync
+// key sets. No CLI shapes and no msg() — an app root in, plain data out, so every path here is
+// testable without a ParsedArgs or a rendered message.
+
+// `node:` and not Bun: Bun exposes no existence check (`existsSync`, which is how a missing
+// `catalogs/` directory reads as "nothing shipped" instead of a throw) and no path API at all —
+// `join` builds the absolute path `Bun.file` reads, and `relative`/`sep` turn it back into the
+// root-relative POSIX shape every CLI-reported path is keyed by.
+import { existsSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import type { Catalog, Extraction, ExtractReport, Locale } from '@ultimat3/i18n';
+import {
+  auditCatalogs,
+  catalogInvalid,
+  catalogKeys,
+  DEFAULT_LOCALE,
+  extractFromFiles,
+  loadCatalog,
+  missingFrom,
+  nestCatalog,
+} from '@ultimat3/i18n';
+import { eachSourceFile, isTest } from './source-files';
+import { CATALOG_ROOT, catalogPath } from './templates/locales';
+
+/**
+ * Every `t()` call the app's own source makes. `source-files.ts` (`eachSourceFile`) is the one
+ * glob set every text-scanning gate step already shares (`errors`, `filesize`) — a second glob
+ * here would mean this command and `x verify` disagree on what "the app's source" is. Test files
+ * are excluded: a fixture's `t('fixture.key')` is not a gap the shipped catalogs owe an answer to.
+ * `extractFromFiles` reads by absolute path, so its `file` label is rewritten back to the same
+ * root-relative POSIX shape `app-load.ts` uses for every other CLI-reported path.
+ */
+export async function scanSource(root: string): Promise<Extraction> {
+  const files: string[] = [];
+  for await (const file of eachSourceFile(root)) {
+    if (!isTest(file)) files.push(file);
+  }
+  const extraction = await extractFromFiles(files.map((file) => join(root, file)));
+  const toRelative = (file: string): string => relative(root, file).split(sep).join('/');
+  return {
+    usages: extraction.usages.map((usage) => ({ ...usage, file: toRelative(usage.file) })),
+    dynamic: extraction.dynamic.map((entry) => ({ ...entry, file: toRelative(entry.file) })),
+  };
+}
+
+/**
+ * A `JSON.parse` failure is still a catalog problem, not a bare-Error crash through this command —
+ * reported through the same factory a structural violation (`loadCatalog` below) uses.
+ */
+function parseCatalogJson(path: string, raw: string): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw catalogInvalid(path, error instanceof Error ? error.message : String(error));
+  }
+}
+
+/**
+ * Every `packages/i18n/catalogs/*.json` on disk, parsed and flattened through `loadCatalog` —
+ * never a bare `JSON.parse`: a nested `{ one, other }` plural authored by hand is a known past
+ * bug, and `loadCatalog` is the seam that fails it loud (`X_CATALOG_INVALID`) instead of auditing
+ * it as an empty catalog. No `catalogs/` directory yet (a fresh app, or `packages/i18n` never
+ * scaffolded) yields `{}` — every caller here treats that as "nothing shipped", not an error.
+ */
+export async function loadCatalogs(root: string): Promise<Readonly<Record<Locale, Catalog>>> {
+  const dir = join(root, CATALOG_ROOT);
+  if (!existsSync(dir)) return {};
+  const catalogs: Record<string, Catalog> = {};
+  for await (const entry of new Bun.Glob('*.json').scan({ cwd: dir, absolute: false })) {
+    const locale = entry.replace(/\.json$/, '');
+    const path = catalogPath(locale);
+    const raw = await Bun.file(join(root, path)).text();
+    catalogs[locale] = loadCatalog(parseCatalogJson(path, raw));
+  }
+  return catalogs;
+}
+
+export interface AuditFacts {
+  readonly report: ExtractReport;
+  readonly catalogs: Readonly<Record<Locale, Catalog>>;
+}
+
+/** The static head of a template literal, up to its first interpolation. */
+const TEMPLATE_HEAD = /^`([^`$]*)\$\{/;
+
+/**
+ * `unused` is the half of the audit an agent acts on destructively — it reads as "safe to delete".
+ * A key only ever reached through `t(`plans.${plan}.name`)` is used, and reporting it unused is
+ * how a live key gets deleted. `AuditInput.ignoreUnused` exists for exactly this, so every dynamic
+ * call contributes its own static head as a `prefix*` pattern. An expression that is not a template
+ * literal (a ternary over string literals, a bare variable) contributes nothing: guessing a prefix
+ * from it would suppress real findings, and the `dynamic` list already names it for a human.
+ */
+export function runtimeKeyPatterns(extraction: Extraction): readonly string[] {
+  const patterns = new Set<string>();
+  for (const entry of extraction.dynamic) {
+    const head = TEMPLATE_HEAD.exec(entry.expression)?.[1];
+    if (head !== undefined && head.length > 0) patterns.add(`${head}*`);
+  }
+  return [...patterns].sort();
+}
+
+/** The source scan and the catalogs on disk, audited together — the one fact `x i18n check` reports. */
+export async function auditApp(root: string): Promise<AuditFacts> {
+  const [extraction, catalogs] = await Promise.all([scanSource(root), loadCatalogs(root)]);
+  const ignoreUnused = runtimeKeyPatterns(extraction);
+  return { report: auditCatalogs({ extraction, catalogs, ignoreUnused }), catalogs };
+}
+
+/**
+ * Which locale is the source of truth for seeding (`x i18n add`) and syncing (`x i18n sync`).
+ * `declared` is the app's own `defineCatalogs({ default })`, projected by `app-load.ts` from
+ * `@ultimat3/i18n`'s `localeConfig()` — the framework's answer to its own question, never a parse
+ * of the app's source. Three rules, in order:
+ *  1. `declared`, trusted only when a catalog for it actually exists on disk.
+ *  2. `en`, when a catalog for it exists — every app `x new` scaffolds has one, so this covers
+ *     every real app even when the i18n module would not import.
+ *  3. The sole catalog on disk, when there is exactly one.
+ * `undefined` when none of the three resolve (no catalogs yet, or several with no `en` and nothing
+ * on disk answering `declared`) — callers seed/sync from an empty source rather than guess at one.
+ */
+export function resolveDefaultLocale(
+  declared: string | undefined,
+  catalogs: Readonly<Record<Locale, Catalog>>,
+): Locale | undefined {
+  if (declared !== undefined && Object.hasOwn(catalogs, declared)) return declared;
+  if (Object.hasOwn(catalogs, DEFAULT_LOCALE)) return DEFAULT_LOCALE;
+  const locales = Object.keys(catalogs);
+  return locales.length === 1 ? locales[0] : undefined;
+}
+
+/**
+ * A sorted copy of `catalog`. Every write below goes through this, so a later `sync` (or a second
+ * `add`) diffs only the keys that actually changed, never a reshuffle.
+ */
+function sortCatalog(catalog: Catalog): Catalog {
+  const out: Record<string, string> = {};
+  for (const key of catalogKeys(catalog)) {
+    const value = catalog[key];
+    if (value !== undefined) out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * `x i18n add`'s seed: every key the default locale defines, values copied verbatim — an
+ * untranslated string that renders is strictly better than a missing key that renders `⟦key⟧`.
+ */
+export function seedCatalog(source: Catalog): Catalog {
+  return sortCatalog(source);
+}
+
+export interface SyncResult {
+  readonly merged: Catalog;
+  readonly added: readonly string[];
+}
+
+/**
+ * `x i18n sync`: every key `source` has that `target` does not, added; every key `target` already
+ * has stays exactly as written, translated or not.
+ */
+export function syncCatalog(target: Catalog, source: Catalog): SyncResult {
+  const added = missingFrom(source, target);
+  if (added.length === 0) return { merged: target, added };
+  const merged: Record<string, string> = { ...target };
+  for (const key of added) {
+    const value = source[key];
+    if (value !== undefined) merged[key] = value;
+  }
+  return { merged: sortCatalog(merged), added };
+}
+
+/**
+ * `Bun.write`'s contents for any catalog this command writes: **nested**, sorted, 2-space indent,
+ * a trailing newline — the shape a hand-authored catalog already has, so the next `sync` or edit
+ * produces a clean diff. Nested is load-bearing, not cosmetic: `Catalog` is the flat dot-key form
+ * the translator reads, and a file written in it is one `loadCatalog` refuses on the very next
+ * read (`X_CATALOG_INVALID` — a dot is not a key segment). `nestCatalog` is `@ultimat3/i18n`'s own
+ * inverse of the flatten every read does, so a catalog this command writes round-trips through it.
+ */
+export function serializeCatalog(catalog: Catalog): string {
+  return `${JSON.stringify(nestCatalog(sortCatalog(catalog)), null, 2)}\n`;
+}

package/src/index.ts

@@ -0,0 +1,179 @@
+// Public API of @ultimat3/cli. Explicit re-exports only: create-ultimate and the test suite build
+// on these, and a barrel that re-exports everything would make every internal a compatibility
+// promise.
+
+export type { BoundaryCode, SourceFile } from './app-boundaries';
+export {
+  appImportGraph,
+  BOUNDARY_CODES,
+  checkAppBoundaries,
+  checkImportRules,
+  readAppSources,
+  resolveSpecifier,
+  scanRuntimeImports,
+} from './app-boundaries';
+export type { LoadedApp } from './app-load';
+export { loadApp, resetAppLoad } from './app-load';
+export type { AppManifest } from './app-manifest';
+export { appManifest, policyFacts, readAppManifest, writeAppManifest } from './app-manifest';
+export { OPENAPI_FILE, openApiJson } from './app-openapi';
+export type { AppRoot } from './app-root';
+export { findAppRoot, requireAppRoot, requireBunVersion, versionAtLeast } from './app-root';
+export type { BoundaryCut, BoundarySplit } from './boundary-cuts';
+export { planBoundaryCuts } from './boundary-cuts';
+export type { BuildStats, RouteStats } from './budgets';
+export { BUILD_STATS_FILE, checkBudgets, readBuildStats } from './budgets';
+export type { BuildTarget } from './cmd-build';
+export { argsFor, BUILD_TARGETS, buildCommand, readTarget } from './cmd-build';
+export { branchDatabaseName, branchSql, dbCommand, previewUrl } from './cmd-db';
+export type { DeployPlan } from './cmd-deploy';
+export { deployCommand, planDeploy } from './cmd-deploy';
+export type { DevServer, StartDevOptions } from './cmd-dev';
+export { devCommand, startDev } from './cmd-dev';
+export type { DoctorProbe } from './cmd-doctor';
+export { doctorCommand, OFFLINE_FALLBACK, probeFor, runDoctor } from './cmd-doctor';
+export { ERRORS_SUBCOMMANDS, errorsCommand } from './cmd-errors';
+export { FIX_SUBCOMMANDS, fixCommand } from './cmd-fix';
+export type { GenerateOptions, Generator } from './cmd-generate';
+export { GENERATORS, generate, generateCommand, writeFiles } from './cmd-generate';
+export { createHelpCommand, createVersionCommand, renderHelp } from './cmd-help';
+export { buildDrainTarget, JOBS_SUBCOMMANDS, jobsCommand } from './cmd-jobs';
+export { manifestCommand } from './cmd-manifest';
+export type { McpHttpServer } from './cmd-mcp';
+export { mcpCommand, startMcpHttp } from './cmd-mcp';
+export type { NewAppOptions, WrittenApp } from './cmd-new';
+export { newCommand, planNewApp, writeNewApp } from './cmd-new';
+export type { PlannedCommand } from './cmd-planned';
+export { PLANNED_COMMANDS, plannedCommands } from './cmd-planned';
+export { actionsCommand, entitiesCommand, queriesCommand } from './cmd-registries';
+export { renderRouteTable, routesCommand } from './cmd-routes';
+export { availableCpus, testCommand } from './cmd-test';
+export { runVerify, VERIFY_STEPS, verifyCommand, verifyStepNames } from './cmd-verify';
+export type { CliCommand, CommandContext } from './command';
+export { failed, ok } from './command';
+export type { AssetRoutesOptions } from './dev-assets';
+export {
+  assetRoutes,
+  ICON_BASE_PATH,
+  ICON_SOURCE,
+  MEDIA_BASE_PATH,
+} from './dev-assets';
+export type { DevDashboardInput, DevStatus } from './dev-dashboard';
+export { devDashboardRoutes, devPanels, devSources } from './dev-dashboard';
+export { devHooks } from './dev-hooks';
+export type { DevDbClient, RunningQueue } from './dev-queue';
+export { startQueue } from './dev-queue';
+export type { DevRenderOptions, DevRouteData } from './dev-render';
+export { appRoutes } from './dev-render';
+export type { RunningRoles, StartRolesOptions } from './dev-roles';
+export { DEV_ROLES, selectRoles, startRoles } from './dev-roles';
+export type { RunningServices } from './dev-runtime';
+export { startServices } from './dev-runtime';
+export type { DevServices, ServiceBinding } from './dev-services';
+export { describeServices, resolveServices } from './dev-services';
+export type { DispatchOptions } from './dispatch';
+export { dispatch } from './dispatch';
+export { checkDrift, recordedHashes, schemaHash, writeSchemaHash } from './drift';
+export type { ErrorCatalog } from './error-catalog';
+export {
+  buildErrorCatalog,
+  CATALOG_PACKAGES,
+  loadErrorCatalog,
+  registeredErrorCodes,
+  resetErrorCatalog,
+} from './error-catalog';
+export {
+  BANNED_PHRASES,
+  COMMAND_TOKENS,
+  checkErrorCodeDocs,
+  checkErrorCodeRegistry,
+  checkErrorFixes,
+  collectDeclaredCodes,
+  documentedCodes,
+  fixProblem,
+  liveCodes,
+  RESERVED_HEADING,
+  staticFix,
+} from './error-contract';
+export type { CliErrorCode } from './errors';
+export {
+  BadFlagError,
+  BunVersionError,
+  CatalogExistsError,
+  CLI_ERROR_CODES,
+  CLI_ERROR_TITLES,
+  CliNotImplementedError,
+  DeclarationUnknownError,
+  ErrorCodeUnknownError,
+  FixTargetUnknownError,
+  JobUnknownError,
+  NoTestFilesError,
+  NotInAppError,
+  UnknownCommandError,
+  VerifyFailedError,
+} from './errors';
+export type { ExecOptions, ExecResult, Runner } from './exec';
+export { exec, execOutput } from './exec';
+export type { DrainFailure, DrainOutcome, DrainSkip } from './jobs-drain';
+export { drainJobs } from './jobs-drain';
+export type { JobsListFilter, JobsListResult } from './jobs-report';
+export { JOB_STATES, listJobs, retryJob, showJob } from './jobs-report';
+export { renderJobTable } from './jobs-table';
+export type { CliMcpServer, DevHostInput } from './mcp-host';
+export { createDevMcpServer, DEV_TOOL_SCOPES, localCaller } from './mcp-host';
+export { messageKeys, msg } from './messages';
+export type { CommandResult, Finding, JsonValue, StepResult } from './output';
+export {
+  exitCodeFor,
+  findingFrom,
+  isUltimateErrorShape,
+  render,
+  renderFinding,
+  renderHuman,
+  renderJson,
+  renderUltimateError,
+} from './output';
+export type { CommandSpec, FlagSpec, ParsedArgs } from './parse';
+export { flagBool, flagList, flagString, GLOBAL_FLAGS, nearest, parseArgs } from './parse';
+export { CLI_VERSION, COMMANDS, commandFor, SPECS } from './registry';
+export {
+  eachSourceFile,
+  isGenerated,
+  isTest,
+  isVendored,
+  SOURCE_GLOBS,
+} from './source-files';
+export type { TestFile } from './test-select';
+export { belongsToType, discoverTests, sampleFiles } from './test-select';
+export type { ReproduceOptions, RunShardsOptions, Shard } from './test-shards';
+export { planShards, quoteArg, reproduceFor, runShards, shardArgs } from './test-shards';
+export type { CodeSite, FixSite, SourceSite } from './ts-scan';
+export {
+  isCodeRegistry,
+  maskLiterals,
+  scanBorrowedCodes,
+  scanCodes,
+  scanFixes,
+  stripComments,
+} from './ts-scan';
+export type {
+  HostCheck,
+  StepOutcome,
+  VerifyContext,
+  VerifyStep,
+  VerifyStepName,
+} from './verify-step';
+export { VERIFY_STEP_NAMES } from './verify-step';
+export type { TestType } from './verify-tests';
+export { TEST_STEPS, TEST_TYPES, testStepCommand, typeFilterOf } from './verify-tests';
+export type { ManifestFacts } from './workspace-checks';
+export {
+  checkFileSizes,
+  checkLockstep,
+  checkPackageShape,
+  frameworkDepsOf,
+  hasWorkspacePackages,
+  LINE_CEILING,
+  PACKAGE_FILES,
+  workspacePackages,
+} from './workspace-checks';

package/src/jobs-drain.ts

@@ -0,0 +1,151 @@
+// `x jobs drain`: moving in-flight work from one queue driver onto another. Its own file because
+// it is the only command here that WRITES to two drivers at once, and the ordering rule that makes
+// that safe — lease, copy steps, enqueue, then ack — has to be readable in one screen.
+
+import { uuid } from '@ultimat3/core';
+import type { JobDriver, JobRecord, JobState } from '@ultimat3/jobs';
+import { inspectJobList } from '@ultimat3/jobs';
+import type { Finding } from './output';
+import { findingFrom } from './output';
+
+/** `running` is deliberately excluded: a job a worker is mid-execution on is not "pending". */
+const PENDING_STATES: readonly JobState[] = ['ready', 'delayed', 'suspended'];
+
+/**
+ * The lease has to outlive the WHOLE transfer loop, not one record: the batch is claimed up
+ * front, and a lease expiring mid-drain would hand a half-transferred job back to a source
+ * worker. The snapshot is bounded by the drivers' own 100-row-per-state list cap, so this is a
+ * ceiling over a few hundred sequential enqueues rather than a guess about one.
+ */
+const DRAIN_LEASE_MS = 300_000;
+
+const NO_LEASE = 'no lease could be taken — not yet due, or a worker is already running it';
+
+export interface DrainFailure {
+  readonly id: string;
+  readonly name: string;
+  readonly finding: Finding;
+}
+
+/** A candidate the drain deliberately left alone, because it could not prove it owned the job. */
+export interface DrainSkip {
+  readonly id: string;
+  readonly name: string;
+  readonly queue: string;
+  readonly state: JobState;
+  readonly reason: string;
+}
+
+export interface DrainOutcome {
+  readonly from: string;
+  readonly to: string;
+  readonly dryRun: boolean;
+  readonly candidates: readonly JobRecord[];
+  readonly moved: readonly JobRecord[];
+  readonly skipped: readonly DrainSkip[];
+  readonly failures: readonly DrainFailure[];
+}
+
+/**
+ * The lease IS the proof of ownership. `ack()` takes only a job id, so a drain that ack'd rows
+ * off a snapshot could acknowledge a job a source worker claimed and is executing right now —
+ * the target would then run a duplicate of a job still in flight. One batch claim over the
+ * candidates' own queues; whatever comes back is the drain's to move, and everything else is
+ * left alone. `queues` is always explicit because the pg driver reads an empty list as
+ * `['default']` rather than as "every queue".
+ */
+function leaseCandidates(
+  source: JobDriver,
+  candidates: readonly JobRecord[],
+): Promise<readonly JobRecord[]> {
+  if (candidates.length === 0) return Promise.resolve([]);
+  return source.claim({
+    queues: [...new Set(candidates.map((record) => record.queue))],
+    limit: candidates.length,
+    visibilityTimeoutMs: DRAIN_LEASE_MS,
+    workerId: `x-jobs-drain:${uuid()}`,
+  });
+}
+
+/** Steps carry their own `runId`, so a copy lands under the same key the target job resumes on. */
+async function copySteps(source: JobDriver, target: JobDriver, runId: string): Promise<void> {
+  for (const record of await source.steps.list(runId)) await target.steps.put(record);
+}
+
+/**
+ * Hand a leased job back exactly as the drain found it. `countsAsAttempt: false` is the point:
+ * a transfer that failed is not a failed attempt, and burning one per `x jobs drain` retry would
+ * dead-letter a job nobody ever ran. It parks as `suspended`, which every driver claims.
+ */
+async function releaseLease(source: JobDriver, id: string): Promise<void> {
+  try {
+    await source.nack(id, { delayMs: 0, countsAsAttempt: false });
+  } catch {
+    // The lease expires on its own. Masking the transfer's real error with this one helps nobody.
+  }
+}
+
+const toSkip = (record: JobRecord): DrainSkip => ({
+  id: record.id,
+  name: record.name,
+  queue: record.queue,
+  state: record.state,
+  reason: NO_LEASE,
+});
+
+/**
+ * Move every pending job the drain can take a lease on from `source` onto `target`. `--dry-run`
+ * reports the candidate list, takes no lease and enqueues nothing. Per-record try/catch, not a
+ * batch operation: one record that cannot enqueue on the target (a redis/nats stub, a transient
+ * error) must not stop the rest from moving, and the caller reports each failure on its own.
+ */
+export async function drainJobs(
+  source: JobDriver,
+  target: JobDriver,
+  dryRun: boolean,
+): Promise<DrainOutcome> {
+  const lists = await Promise.all(PENDING_STATES.map((state) => inspectJobList(source, { state })));
+  const candidates = lists.flat();
+  const base = { from: source.name, to: target.name, candidates };
+  if (dryRun) return { ...base, dryRun: true, moved: [], skipped: [], failures: [] };
+
+  const leased = await leaseCandidates(source, candidates);
+  const held = new Set(leased.map((record) => record.id));
+  const found = new Map(candidates.map((record) => [record.id, record]));
+  const skipped = candidates.filter((record) => !held.has(record.id)).map(toSkip);
+
+  const moved: JobRecord[] = [];
+  const failures: DrainFailure[] = [];
+  for (const record of leased) {
+    let enqueued = false;
+    try {
+      // Steps BEFORE the job: a worker on the target must never be able to claim a run whose
+      // checkpoint has not landed, or it repeats completed steps or loses them outright.
+      await copySteps(source, target, record.runId);
+      await target.enqueue({
+        name: record.name,
+        queue: record.queue,
+        input: record.input,
+        idempotencyKey: record.idempotencyKey,
+        runId: record.runId,
+        maxAttempts: record.maxAttempts,
+        runAt: record.runAt,
+        ...(record.tenantId === undefined ? {} : { tenantId: record.tenantId }),
+      });
+      enqueued = true;
+      // Only now is the ack the drain's to make: the lease proves no source worker holds this
+      // job, and the target already has both the row and its steps. A crash between the two
+      // leaves the job live on both drivers, where `idempotencyKey` dedupes it.
+      await source.ack(record.id);
+      // Report the row as the drain FOUND it: `claim()` returns it mid-lease (`running`, one
+      // attempt higher), a state nothing on either driver is in once this returns.
+      moved.push(found.get(record.id) ?? record);
+    } catch (error) {
+      // A failed enqueue left nothing on the target, so the lease goes back. A failed ack did
+      // not: the job is already live there, and releasing it would race the target's worker.
+      if (!enqueued) await releaseLease(source, record.id);
+      failures.push({ id: record.id, name: record.name, finding: findingFrom(error) });
+    }
+  }
+  return { ...base, dryRun: false, moved, skipped, failures };
+}