@pithy-sh/cli 0.1.0

package/src/migrations/run.ts

@@ -0,0 +1,1066 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import type { D1Database } from "@cloudflare/workers-types";
+import { CloudflareClients } from "@pithy-sh/cloudflare/src/client/clients";
+import type { Capability } from "@pithy-sh/core/src/capability/capability";
+import { composeDatabases } from "@pithy-sh/core/src/data/databases";
+import { InternalError, NotFoundError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { claimMigrationOwnership } from "@pithy-sh/core/src/migrations/owner";
+import { createMigrationRegistry, type NamespacedMigrations } from "@pithy-sh/core/src/migrations/registry";
+import {
+  dropMigrations,
+  type MigrationLedger,
+  type MigrationTarget,
+  readMigrationLedger,
+  resetMigrations,
+  rollbackMigration,
+  runMigrations,
+} from "@pithy-sh/core/src/migrations/runner";
+import { partialWriteReport } from "@pithy-sh/secrets/src/cli/partialWrite";
+import { parse } from "comment-json";
+import type { Migration, MigrationProvider, MigrationResult } from "kysely/migration";
+import { Miniflare } from "miniflare";
+import { z } from "zod";
+import { type CloudflareAccountSelection, cloudflareEnv } from "../cloudflare/config";
+import { resolveWorkers } from "../project/workerScope";
+import { wranglerConfigPath } from "../provision/featureConfig";
+import { assertLedgerDeclared, UndeclaredMigration } from "./ledger";
+import { collectMigrationSets } from "./registry";
+
+/**
+ * `pithy migrate` fans out over Workers. There is no root Worker: every Worker lives in `apps/<name>/`
+ * with its own `pithy.config.ts` (its capabilities) and its own `wrangler.jsonc` (its bindings), so a
+ * migration run is one pass per Worker over that Worker's own registry.
+ *
+ * Two things follow from Workers sharing resources **by binding name**:
+ *
+ *  - **Bindings are per-Worker, local state is per-project.** Each Worker's D1 bindings come from its own
+ *    `wrangler.jsonc`, but the local Miniflare store stays at `<projectRoot>/.wrangler/state` — the one
+ *    `wrangler dev` uses. Giving each Worker its own persistence directory would silently hand two Workers
+ *    that both declare `DB` two different local databases.
+ *  - **A shared database migrates once.** Workers whose entries resolve to the same D1 are grouped, their
+ *    migration sets merged into one ordered provider, and that provider runs a single time. Each result is
+ *    then credited back to the Worker whose capability declared it, so the report and `--json` stay truthful.
+ */
+
+/**
+ * Build the remote D1 for a binding — the REST-backed `D1Database` `pithy migrate --env staging`
+ * runs against. Injectable so tests substitute an in-memory D1 for the network client (issue #24's
+ * `CloudflareD1Manager` is tested separately).
+ */
+export type RemoteD1Factory = (args: { binding: string; databaseId: string }) => D1Database;
+
+/**
+ * One Worker in a fan-out: its name, its directory (where its `wrangler.jsonc` lives), and the
+ * capabilities its own `pithy.config.ts` composes. `ResolvedWorker` satisfies this structurally, so a
+ * caller that already resolved the set passes it straight through.
+ */
+export interface WorkerScope {
+  /** The Worker's name — its `wrangler.jsonc` name, else its `apps/<dir>` basename. */
+  name: string;
+  /** The Worker's directory: its `wrangler.jsonc` supplies the D1 bindings and their ids. */
+  dir: string;
+  /** The capabilities that Worker composes, libraries first and its app last. */
+  capabilities: Capability[];
+}
+
+/**
+ * The fan-out every project-scoped migration entry point shares — which project root, which
+ * environment, which Workers. It carries no project **name**, because it is also what the read-only
+ * entry points take: {@link readProjectLedger} and {@link previewReset} inspect a database without
+ * writing to it, so they have no claim to make and `pithy doctor` may run them on a nameless project.
+ */
+export interface MigrationFanOutOptions {
+  /**
+   * The project root — the parent of `apps/`, and the owner of the `.wrangler/state` store every
+   * Worker's local D1 lives in.
+   */
+  projectDir: string;
+  /**
+   * The Cloudflare account this project belongs to. A remote migration alters a real schema, so the
+   * wrong account's credentials would run it against another company's database (#206).
+   *
+   * **Required (#234).** `null` is the answer for a project that names no account, and it has to be
+   * written down: `account?:` let seven callers — `capabilities/flow.ts`, `capabilities/reconcile.ts`,
+   * `capabilities/remove.ts`, `feature/provision.ts`, `feature/create.ts`, `commands/feature.ts` and
+   * `seed/run.ts` — reach a live D1 without ever saying whose it was, and none of those omissions was
+   * visible in a diff. A `dev` run never touches the network, so `null` there costs nothing; a
+   * `--env staging` run is the one this exists for.
+   */
+  account: CloudflareAccountSelection | null;
+  /** Target environment. `dev` runs locally via Miniflare; staging/prod run over the D1 REST API. */
+  env: string;
+  /** Narrow the fan-out to one Worker, by its name or its `apps/<dir>` basename. */
+  worker?: string;
+  /** Test seam: build the remote D1 for a binding instead of the default REST-backed client. */
+  remoteD1?: RemoteD1Factory;
+  /**
+   * The Workers to run against, already resolved. Skips `apps/` discovery for the run's **scope** — for a
+   * caller that resolved the set itself (`pithy add` hands over the one Worker it just wired), and for
+   * tests, whose fixture Workers carry no importable `pithy.config.ts`. The project is still discovered
+   * behind it, best effort, so a database one of these Workers shares with another migrates as a whole;
+   * what is reported and applied stays exactly this set.
+   */
+  workers?: WorkerScope[];
+}
+
+/** The options for a run that **writes**: the fan-out, plus the project every database it touches is claimed for. */
+export interface MigrateProjectOptions extends MigrationFanOutOptions {
+  /**
+   * The project this run belongs to — the root `pithy.config.ts` `name` (`requireProjectName`, never
+   * `resolveProjectName`). Every database the run touches is stamped with it on first use and checked
+   * against it afterwards, so a database another project owns is refused by name instead of silently
+   * merging two schemas (`claimMigrationOwnership`).
+   *
+   * **Required, on every entry point that can change a database.** It was optional once, and the result
+   * was a guard `pithy migrate` honored while `pithy add`, `pithy remove`, `pithy upgrade --migrate`,
+   * and the three `pithy feature` paths quietly wrote unstamped — a database no project owns is one any
+   * project may later claim. A caller that cannot resolve a stable name has no business writing here.
+   */
+  project: string;
+  /** Step the latest applied migration back instead of running forward. */
+  rollback?: boolean;
+}
+
+/** A reset never rolls back — it rolls *everything* back, then reapplies everything. */
+export type ResetProjectOptions = Omit<MigrateProjectOptions, "rollback">;
+
+/** One database's migration run: which database, its binding, and what Kysely did. */
+export interface DatabaseRun {
+  /** The database name (a capability's `databases` key). */
+  database: string;
+  /** The D1 binding it resolves to in this Worker's `wrangler.jsonc`. */
+  binding: string;
+  /**
+   * The migrations this Worker's capabilities contributed, and how each fared. A shared database always
+   * migrates as a whole — a run narrowed to one Worker still applies what the Workers it shares with
+   * contributed — but every result is credited to the Worker that declared it, so a row never claims a
+   * migration its own capabilities do not own.
+   */
+  results: MigrationResult[];
+  /**
+   * The other Workers bound to this same physical D1. Present only when a database is shared: the
+   * merged registry ran once for all of them, and each Worker is credited with its own migrations.
+   */
+  sharedWith?: string[];
+}
+
+/** One Worker's slice of a fan-out run: the Worker, and each database its registry touched. */
+export interface WorkerMigrationRun {
+  /** The Worker's name. */
+  worker: string;
+  /** Its databases, in registry order. Empty when the Worker composes no migrations. */
+  databases: DatabaseRun[];
+}
+
+/** One Worker's claim on one database: the sets it contributes, and the binding it declares. */
+interface WorkerPlanEntry {
+  /** The Worker's name. */
+  worker: string;
+  /** The database name this Worker knows it by. */
+  database: string;
+  /** The D1 binding in this Worker's `wrangler.jsonc`. */
+  binding: string;
+  /** This Worker's migration sets for that database. */
+  sets: NamespacedMigrations[];
+}
+
+/**
+ * One physical D1 and everything that migrates into it — the unit a run actually executes.
+ *
+ * Exported for {@link ./ledger}, which compares each group's provider against the ledger of the database
+ * this same run is about to write to. A type-only import there, so the two files do not form a cycle.
+ */
+export interface DatabaseGroup {
+  /** The resolved D1 identity every entry shares: locally the binding/name fallback, remotely the `database_id`. */
+  id: string;
+  /** The first entry's database name — the group's label in the report. */
+  database: string;
+  /** The first entry's binding — the group's label, and what the remote factory is told. */
+  binding: string;
+  /** The remote `database_id`, when the target env's stanza declares one. */
+  databaseId?: string;
+  /** Every Worker claim on this database, in Worker order. */
+  entries: WorkerPlanEntry[];
+  /** The merged, ordered provider — every contributing Worker's sets in one registry. */
+  provider: MigrationProvider;
+  /** Composed migration name → the Worker credited with it. */
+  owners: Map<string, string>;
+}
+
+/** A resolved set of D1s to migrate — the only thing that differs between local and remote — plus teardown. */
+export interface MigrationDriver {
+  /** The D1 for a group; every group is resolved before the run loop reads it. */
+  database(group: DatabaseGroup): D1Database;
+  /** Release the driver's resources (Miniflare instance locally; a no-op remotely). */
+  dispose(): Promise<void>;
+}
+
+/**
+ * One D1 binding entry in wrangler.jsonc — the fields migrate reads to resolve a database's id.
+ * `database_name` is not among them: wrangler ignores it when binding a local D1 (see {@link idsFor}),
+ * so migrate must ignore it too. Leaving it off the type makes reading it a compile error.
+ */
+interface D1Binding {
+  binding: string;
+  database_id?: string;
+}
+
+/** The wrangler.jsonc slice migrate reads: the local (top-level) bindings and each env's bindings. */
+interface WranglerD1Config {
+  d1_databases?: D1Binding[];
+  env?: Record<string, { d1_databases?: D1Binding[] } | undefined>;
+}
+
+/**
+ * Read and parse the config that describes this Worker in this environment. A missing file yields an
+ * empty config.
+ *
+ * Through {@link wranglerConfigPath}, which is what makes a feature environment read the generated
+ * config under `.wrangler/` rather than the tracked one (#242) — provisioning writes a feature's ids
+ * there, so reading `wrangler.jsonc` here would find no `env.feature` stanza and refuse the migrate.
+ */
+async function readWranglerConfig(workerDir: string, env: string): Promise<WranglerD1Config> {
+  try {
+    const raw = await readFile(wranglerConfigPath(workerDir, env), "utf8");
+    return parse(raw) as unknown as WranglerD1Config;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Map binding → id from a set of D1 entries. Locally the id is `database_id` else the binding — the
+ * exact chain wrangler's `d1DatabaseEntry({ binding, database_id, preview_database_id })` uses to key
+ * the Miniflare store (`getRemoteId(preview_database_id ?? database_id) ?? binding`). **`database_name`
+ * is deliberately absent**: wrangler does not read it for the local binding at all, so folding it in
+ * would migrate a store `pithy dev` never opens — and `pithy add` writes exactly that stanza
+ * (`database_name`, no id), so every request would fail `D1_ERROR: no such table`. Remotely (`idOnly`)
+ * only a real `database_id` counts, so a binding with none is caught as an actionable error, not run
+ * against the wrong database.
+ */
+function idsFor(entries: D1Binding[] | undefined, idOnly = false): Map<string, string> {
+  const ids = new Map<string, string>();
+  for (const entry of entries ?? []) {
+    const value = idOnly ? entry.database_id : (entry.database_id ?? entry.binding);
+    if (value) ids.set(entry.binding, value);
+  }
+  return ids;
+}
+
+/**
+ * One Worker's claims: every database it has migrations for, resolved to the binding its own
+ * capabilities declare. Rejects two databases sharing one binding within a Worker (they would migrate
+ * against a single physical D1 store, colliding on data and migration bookkeeping) — that is a wiring
+ * mistake, unlike two *Workers* sharing a binding, which is how they share a resource.
+ */
+function buildPlan(worker: WorkerScope): WorkerPlanEntry[] {
+  const databases = composeDatabases(worker.capabilities);
+  const byDatabase = new Map<string, NamespacedMigrations[]>();
+  for (const set of collectMigrationSets(worker.capabilities)) {
+    const existing = byDatabase.get(set.database);
+    if (existing) existing.push(set);
+    else byDatabase.set(set.database, [set]);
+  }
+
+  const plan: WorkerPlanEntry[] = [];
+  const bindingOwner = new Map<string, string>();
+  for (const [database, sets] of byDatabase) {
+    const group = databases[database];
+    if (!group) {
+      throw new InternalError({
+        message: `Database "${database}" has migrations but no capability declares it.`,
+        action: "Declare the database (binding and tables) in a capability. Run pithy migrate again.",
+      });
+    }
+    const owner = bindingOwner.get(group.binding);
+    if (owner) {
+      throw new InternalError({
+        message: `Databases "${owner}" and "${database}" are both bound to "${group.binding}".`,
+        action: "Give each database its own binding. Run pithy migrate again.",
+      });
+    }
+    bindingOwner.set(group.binding, database);
+    plan.push({ worker: worker.name, database, binding: group.binding, sets });
+  }
+  return plan;
+}
+
+/**
+ * Whether two entries under one key are the same migration — identity, not resemblance. A capability
+ * ships its migrations as module-level objects (`multiplayer_0001_results`), so composing one capability
+ * into two Workers hands both the *same* object even when the capability itself is built per Worker by a
+ * factory; a spread that rebuilds the record still carries the same `up`/`down`. Two capabilities that
+ * merely agree on a key name do not, which is the whole point: `0001_init` is the canonical first key, so
+ * a name-only test calls two unrelated migrations identical and silently drops one.
+ */
+function sameMigration(a: Migration, b: Migration): boolean {
+  return a === b || (a.up === b.up && a.down === b.down);
+}
+
+/**
+ * Whether two sets carry the same migrations — the test for "the same capability, composed twice".
+ * Same order, same keys, and the same migration behind every key: anything else is two different sets
+ * wearing one namespace, which the caller rejects rather than silently dropping one.
+ */
+function sameMigrations(a: NamespacedMigrations, b: NamespacedMigrations): boolean {
+  if (a.order !== b.order) return false;
+  const left = Object.keys(a.migrations).sort();
+  const right = Object.keys(b.migrations).sort();
+  if (left.length !== right.length) return false;
+  return left.every((key, index) => {
+    if (key !== right[index]) return false;
+    const one = a.migrations[key];
+    const two = b.migrations[key];
+    return one !== undefined && two !== undefined && sameMigration(one, two);
+  });
+}
+
+/**
+ * Merge every contributing Worker's sets for one physical D1 into a single ordered provider, and record
+ * which Worker each composed migration name belongs to.
+ *
+ * A namespace claimed by two Workers is the *same capability* composed into both — dedupe it, so a
+ * shared database migrates once. A namespace claimed twice with **different** migrations is two
+ * different capabilities wearing one name: their composed keys would collide in the ledger, so that
+ * fails loudly rather than letting one silently shadow the other.
+ */
+async function mergeGroup(
+  database: string,
+  binding: string,
+  entries: WorkerPlanEntry[],
+): Promise<{ provider: MigrationProvider; owners: Map<string, string> }> {
+  const kept = new Map<string, { set: NamespacedMigrations; worker: string }>();
+  for (const entry of entries) {
+    for (const set of entry.sets) {
+      const prior = kept.get(set.namespace);
+      if (!prior) {
+        kept.set(set.namespace, { set, worker: entry.worker });
+        continue;
+      }
+      if (sameMigrations(prior.set, set)) continue;
+      throw new InternalError({
+        message: `Workers "${prior.worker}" and "${entry.worker}" both migrate "${binding}" under the "${set.namespace}" namespace, with different migrations.`,
+        action: "Rename one capability, or bind the workers to different databases. Run pithy migrate again.",
+      });
+    }
+  }
+
+  const sets = [...kept.values()].map(({ set }) => ({ ...set, database }));
+  const provider = createMigrationRegistry(sets)[database] ?? { getMigrations: async () => ({}) };
+
+  // Credit each composed name to its Worker by composing that one set through the same registry, so the
+  // key format stays core's single definition rather than a copy that can drift.
+  const owners = new Map<string, string>();
+  for (const { set, worker } of kept.values()) {
+    const single = createMigrationRegistry([{ ...set, database }])[database];
+    for (const name of Object.keys((await single?.getMigrations()) ?? {})) owners.set(name, worker);
+  }
+  return { provider, owners };
+}
+
+/**
+ * Group every Worker's claims by the physical D1 they resolve to, and merge each group's registries.
+ * Grouping is by resolved id — locally `database_id` else the binding (wrangler's own chain, see
+ * {@link idsFor}), remotely the env stanza's `database_id` — falling back to the binding name when no id
+ * is declared, since Workers share a resource precisely by declaring the same binding.
+ *
+ * `workers` is always the **complete** set, never the run's narrowed scope: a database is migrated as a
+ * whole, so every Worker bound to it must be in its group even when only one of them is being reported
+ * (see {@link scopedGroups}). `scope` names the Workers the run actually targets — a Worker outside it
+ * that has no stanza for a non-`dev` env has never migrated there, so it is skipped rather than failing
+ * a run that never asked about it.
+ */
+async function buildGroups(workers: WorkerScope[], env: string, scope: Set<string>): Promise<DatabaseGroup[]> {
+  const ordered: { id: string; database: string; binding: string; databaseId?: string; entries: WorkerPlanEntry[] }[] =
+    [];
+  const byId = new Map<string, (typeof ordered)[number]>();
+
+  for (const worker of workers) {
+    const plan = buildPlan(worker);
+    if (plan.length === 0) continue;
+    const config = await readWranglerConfig(worker.dir, env);
+    if (env !== "dev" && !config.env?.[env]) {
+      if (!scope.has(worker.name)) continue;
+      throw new ValidationError({
+        message: `${worker.name}: wrangler.jsonc has no env.${env} stanza.`,
+        action: `Add the ${env} environment to ${worker.name}'s wrangler.jsonc with its D1 bindings. Run pithy migrate --env ${env} again.`,
+      });
+    }
+    const local = idsFor(config.d1_databases);
+    const remote = idsFor(config.env?.[env]?.d1_databases, true);
+
+    for (const entry of plan) {
+      const databaseId = remote.get(entry.binding);
+      const id = env === "dev" ? (local.get(entry.binding) ?? entry.binding) : (databaseId ?? entry.binding);
+      const existing = byId.get(id);
+      if (existing) {
+        existing.entries.push(entry);
+        continue;
+      }
+      const group = {
+        id,
+        database: entry.database,
+        binding: entry.binding,
+        ...(databaseId !== undefined ? { databaseId } : {}),
+        entries: [entry],
+      };
+      byId.set(id, group);
+      ordered.push(group);
+    }
+  }
+
+  const groups: DatabaseGroup[] = [];
+  for (const group of ordered) {
+    const { provider, owners } = await mergeGroup(group.database, group.binding, group.entries);
+    groups.push({ ...group, provider, owners });
+  }
+  return groups;
+}
+
+/**
+ * The local driver: the same D1 store `wrangler dev` uses, under `<projectRoot>/.wrangler/state`, via
+ * Miniflare. Persistence is deliberately project-scoped, not Worker-scoped — two Workers that declare
+ * the same binding are meant to share one local database. Each group gets a synthetic Miniflare binding
+ * (groups are keyed by id, and two Workers can name one id under one binding), so the persistence key
+ * is the resolved id and nothing else. Miniflare needs a script even though no request runs — migrations
+ * go through the D1 bindings alone.
+ */
+async function localDriver(persistRoot: string, groups: DatabaseGroup[]): Promise<MigrationDriver> {
+  const bindings: Record<string, string> = {};
+  groups.forEach((group, index) => {
+    bindings[`d1_${index}`] = group.id;
+  });
+
+  const miniflare = new Miniflare({
+    modules: true,
+    script: "export default {};",
+    d1Databases: bindings,
+    d1Persist: join(persistRoot, ".wrangler", "state", "v3", "d1"),
+  });
+
+  const cache = new Map<string, D1Database>();
+  for (const [index, group] of groups.entries()) {
+    cache.set(group.id, (await miniflare.getD1Database(`d1_${index}`)) as unknown as D1Database);
+  }
+  return { database: (group) => databaseOf(cache, group), dispose: () => miniflare.dispose() };
+}
+
+/** The D1 for a group, or an internal error — the driver populates every group up front. */
+function databaseOf(cache: Map<string, D1Database>, group: DatabaseGroup): D1Database {
+  const database = cache.get(group.id);
+  if (!database) throw new InternalError({ detail: `No D1 resolved for binding "${group.binding}".` });
+  return database;
+}
+
+/**
+ * Build the default REST-backed D1 factory: read CF creds from the environment (the project root's
+ * `.dev.vars` — one shared file for the whole repo — then `process.env`) and back each binding with a
+ * `@pithy-sh/cloudflare` D1 client (a shared client memoizes managers by database id). Only ever called
+ * for the real REST path; an injected `override` replaces it wholesale.
+ */
+function defaultRemoteD1(env: string, account: CloudflareAccountSelection | null): RemoteD1Factory {
+  const vars = cloudflareEnv({ account });
+  const accountId = vars.CLOUDFLARE_ACCOUNT_ID ?? "";
+  // The active CF token: the bootstrap token locally, or the least-privilege `ci-system` token in CI
+  // (an operator mints it with `pithy token mint ci-system` and sets it as CI's CLOUDFLARE_API_TOKEN).
+  const apiToken = vars.CLOUDFLARE_API_TOKEN ?? "";
+  if (!accountId || !apiToken) {
+    throw new ValidationError({
+      message: "Cloudflare credentials are missing.",
+      action: `Set CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN to migrate --env ${env}.`,
+    });
+  }
+  const clients = new CloudflareClients({ accountId, apiToken });
+  return ({ databaseId }) => clients.d1(databaseId) as unknown as D1Database;
+}
+
+/**
+ * The remote driver: the same migration registries, executed over the D1 REST API through
+ * `@pithy-sh/cloudflare`. Each group's remote id comes from the owning Worker's `wrangler.jsonc` env
+ * block. The REST-backed D1 is the *only* thing that differs from local; the registries, ordering, and
+ * per-database runs are shared. An injected `override` — a test's in-memory D1 — replaces the REST
+ * client wholesale, so credentials are demanded only for the real path (mirrors the seed driver, which
+ * is likewise credential-lazy): substituting the network client must never require ambient CF creds.
+ */
+function remoteDriver(
+  env: string,
+  groups: DatabaseGroup[],
+  account: CloudflareAccountSelection | null,
+  override?: RemoteD1Factory,
+): MigrationDriver {
+  // Build the REST-backed D1 per binding; the default reaches for creds, an override bypasses them.
+  const resolveD1: RemoteD1Factory = override ?? defaultRemoteD1(env, account);
+
+  const cache = new Map<string, D1Database>();
+  for (const group of groups) {
+    if (!group.databaseId) {
+      throw new ValidationError({
+        message: `wrangler.jsonc env.${env} has no database_id for the "${group.binding}" binding.`,
+        action: `Provision the ${env} D1 and set its id on ${group.binding}. Run pithy migrate --env ${env} again.`,
+      });
+    }
+    cache.set(group.id, resolveD1({ binding: group.binding, databaseId: group.databaseId }));
+  }
+  return { database: (group) => databaseOf(cache, group), dispose: async () => {} };
+}
+
+/** Everything a run needs once the Workers are resolved: where state lives, and how D1 is reached. */
+interface RunContext {
+  /** The Workers in the fan-out, in report order — the run's scope, already narrowed by `--worker`. */
+  workers: WorkerScope[];
+  /**
+   * Every Worker a database in scope may be shared with — the set each group's merged provider is built
+   * from. It is the whole project, not the narrowed scope: the ledger of a shared D1 records both
+   * Workers' migrations, so a provider covering only one of them reads as corrupted state to Kysely.
+   */
+  groupWorkers: WorkerScope[];
+  /** The project root whose `.wrangler/state` holds the local D1 every Worker shares. */
+  persistRoot: string;
+  /**
+   * The Cloudflare account this project belongs to, carried from the run's options. A remote migration
+   * alters a real schema, so the wrong account's credentials would run it against another company's
+   * database (#206).
+   */
+  account: CloudflareAccountSelection | null;
+  /** Target environment. */
+  env: string;
+  /** The owning project every touched database is stamped with and checked against. Optional. */
+  project?: string;
+  /** Test seam for the remote D1 client. */
+  remoteD1?: RemoteD1Factory;
+}
+
+/** Pick the driver for the target environment: Miniflare for `dev`, the D1 REST API otherwise. */
+function driverFor(context: RunContext, groups: DatabaseGroup[]): Promise<MigrationDriver> {
+  return context.env === "dev"
+    ? localDriver(context.persistRoot, groups)
+    : Promise.resolve(remoteDriver(context.env, groups, context.account, context.remoteD1));
+}
+
+/**
+ * The fan-out set: the caller's pre-resolved Workers, else discovery over `apps/`, narrowed by `worker`.
+ * Exported because `pithy seed` fans out over exactly the same set, under exactly the same rules — one
+ * definition of "which Workers does this command act on" for both data-plane commands.
+ */
+export async function resolveWorkerScopes(options: {
+  /** The project root — the parent of `apps/`. */
+  projectDir: string;
+  /** Narrow to one Worker, by its name or its `apps/<dir>` basename. */
+  worker?: string;
+  /** Pre-resolved Workers, skipping `apps/` discovery. */
+  workers?: WorkerScope[];
+}): Promise<WorkerScope[]> {
+  if (!options.workers) {
+    return resolveWorkers({
+      projectDir: options.projectDir,
+      ...(options.worker !== undefined ? { worker: options.worker } : {}),
+    });
+  }
+  if (options.worker === undefined) return options.workers;
+  const found = options.workers.filter(
+    (candidate) => candidate.name === options.worker || candidate.dir.endsWith(`/${options.worker}`),
+  );
+  if (found.length === 0) {
+    throw new NotFoundError({
+      message: `No worker named "${options.worker}".`,
+      action: `Run pithy worker list to see this project's workers. Known: ${options.workers.map((w) => w.name).join(", ")}.`,
+    });
+  }
+  return found;
+}
+
+/** An empty report row per Worker, in fan-out order — a Worker with no migrations still appears. */
+function emptyReport(workers: WorkerScope[]): WorkerMigrationRun[] {
+  return workers.map((worker) => ({ worker: worker.name, databases: [] }));
+}
+
+/**
+ * Fold one group's run into the per-Worker report: each result goes to the Worker whose capability
+ * declared it, and a database shared by several Workers names the others on every row.
+ */
+function record(report: WorkerMigrationRun[], group: DatabaseGroup, results: MigrationResult[]): void {
+  for (const entry of group.entries) {
+    const row = report.find((candidate) => candidate.worker === entry.worker);
+    if (!row) continue;
+    const others = group.entries.filter((other) => other.worker !== entry.worker).map((other) => other.worker);
+    row.databases.push({
+      database: entry.database,
+      binding: entry.binding,
+      results: results.filter((result) => group.owners.get(result.migrationName) === entry.worker),
+      ...(others.length > 0 ? { sharedWith: others } : {}),
+    });
+  }
+}
+
+/**
+ * The groups a run touches: every database at least one in-scope Worker claims, each carrying **every**
+ * Worker bound to it. Narrowing (`--worker`, and every `pithy add`/`remove`/`upgrade --migrate`, which
+ * always scope to one Worker) narrows what is reported and which databases are visited — never the
+ * registry a visited database runs. A shared D1's ledger holds both Workers' migrations, so a provider
+ * missing one of them is corrupted state to Kysely and the run aborts.
+ */
+async function scopedGroups(context: RunContext): Promise<DatabaseGroup[]> {
+  const scope = new Set(context.workers.map((worker) => worker.name));
+  const groups = await buildGroups(context.groupWorkers, context.env, scope);
+  return groups.filter((group) => group.entries.some((entry) => scope.has(entry.worker)));
+}
+
+/**
+ * Claim every database in the run for this project **before any of them is written to**. The stamp
+ * lives in the migration bookkeeping, so the first run adopts a database and every later one checks
+ * it; a database another project owns throws, naming both. Doing the whole pass up front is the point
+ * — a foreign database in the set aborts the run rather than being discovered halfway through, with
+ * some of the project's databases already moved.
+ *
+ * **This is the single choke point, and it refuses rather than shrugs.** Every entry point that can
+ * change a database — forward, rollback, reset, capability drop — runs through {@link runGroups} and so
+ * through here, which is why the check lives at this one line instead of at each of the eight callers.
+ * It used to return quietly on a missing project, and that is precisely how the guard shipped honored
+ * by two commands and ignored by six. A nameless run is now impossible to *reach* the write with.
+ */
+async function claimGroups(context: RunContext, driver: MigrationDriver, groups: DatabaseGroup[]): Promise<void> {
+  const project = context.project;
+  if (project === undefined) {
+    throw new ValidationError({
+      message: "A migration run needs a project name.",
+      action:
+        "Set `name` in pithy.config.ts. It stamps each database as this project's, so another project's database is refused instead of silently merged.",
+      detail: `No project on a run over ${groups.map((group) => group.binding).join(", ") || "no databases"}.`,
+    });
+  }
+  for (const group of groups) {
+    await claimMigrationOwnership(driver.database(group), { project, binding: group.binding });
+  }
+}
+
+/**
+ * One pass over every database in a run: what to do to each, and whether the provider doing it speaks
+ * for the whole ledger.
+ */
+interface MigrationPass {
+  /** The work itself. The target rides along so a failure names the database it failed on (#282). */
+  execute: (database: D1Database, provider: MigrationProvider, target: MigrationTarget) => Promise<MigrationResult[]>;
+  /**
+   * Whether the provider carries every migration the ledger could hold.
+   *
+   * True for migrate, rollback and reset, which run the whole composed registry — so a ledger row the
+   * provider does not carry is a migration this project no longer declares, and the run is refused
+   * before it writes. False for `pithy remove --drop`, whose provider is *deliberately* one capability's
+   * migrations against a database full of other capabilities' rows: to it every other row is
+   * undeclared, and a check here would refuse the command it exists to serve.
+   */
+  spansLedger: boolean;
+}
+
+/**
+ * What a fan-out changed before it stopped, in the three states a database in scope can be left in
+ * (#380).
+ *
+ * A run visits one database at a time and each one is a **write**. The pass on the third throws, the
+ * first two have already moved their schema, and the return value that would have named them never
+ * happens — so the operator is told a migration failed and nothing at all about which databases are now
+ * ahead of the others. That is the record you need most when a run dies partway, and it was the one the
+ * throw took with it.
+ *
+ * The three fields are three different facts and they share no entry, which is the point: `migrated` is
+ * what definitely ran, `failed` is the one database whose pass threw, and `unreached` is every database
+ * the run never opened. An empty `unreached` means the failure was on the last database — never "no
+ * scan". Absent and unknown do not collapse into one another here.
+ *
+ * **Nothing derived from the failure is in it.** The report names databases and bindings; what a
+ * migration throws names a statement, a table, or an id, and that stays on the error the operator is
+ * already reading.
+ */
+export interface MigrationProgress {
+  /**
+   * Per-Worker rows for every database whose pass **completed**, in fan-out order — exactly the report a
+   * finished run returns, truncated at the failure. A Worker whose databases were all unreached appears
+   * with an empty `databases`, as it does in a clean run.
+   */
+  migrated: WorkerMigrationRun[];
+  /** The database the run died on. Its schema is in whatever state the failed pass left it. */
+  failed: MigrationTarget;
+  /** Every database in scope this run never opened, in fan-out order. Empty means the failure was the last one. */
+  unreached: MigrationTarget[];
+}
+
+/** A carried value arrives as `unknown`; this is the narrowing, never a cast. */
+function isMigrationProgress(value: unknown): value is MigrationProgress {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as Partial<MigrationProgress>;
+  if (!Array.isArray(candidate.migrated) || !Array.isArray(candidate.unreached)) return false;
+  return typeof candidate.failed === "object" && candidate.failed !== null;
+}
+
+/**
+ * **Where the record of a partial run rides out of a failure (#380).**
+ *
+ * The mechanism is `partialWriteReport`'s, the same one `mintDeclaredSecrets` carries its minted
+ * secrets on (#324) and `dispatchSecretWrite` its reached environments (#325). Carried, never replaced:
+ * the failure an operator reads is the failure that happened, and what the run wrote is what makes the
+ * remedy in it safe to perform.
+ */
+const progressReport = partialWriteReport<MigrationProgress>("pithy.cli.migrationProgress", isMigrationProgress);
+
+/**
+ * What a failed fan-out ({@link migrateProject}, {@link resetProject}, a capability drop) changed before
+ * it failed, or `undefined` for a throw from anywhere else — which is the honest answer when the run
+ * never reached a database at all.
+ */
+export function migratedBeforeFailure(error: unknown): MigrationProgress | undefined {
+  return progressReport.read(error);
+}
+
+/**
+ * Open the driver, run the pass per group, fold the results into a per-Worker report, and tear down.
+ *
+ * **The run still stops at the first database that fails, and it still throws.** Every entry point that
+ * writes a schema comes through here, and a pass that failed for a reason belonging to the whole run —
+ * a revoked token, an account that is not this project's — would otherwise carry on applying migrations
+ * to the databases behind it. What changed is that the record survives the throw: {@link
+ * migratedBeforeFailure} reads back which databases moved, which one died, and which were never opened
+ * (#380).
+ *
+ * **The three steps above the loop are deliberately not guarded.** `scopedGroups`, `claimGroups` and
+ * `assertLedgerDeclared` decide *what* the run is over and whether it may write at all — the loop's
+ * preconditions, not contributors to it — so their failure is not one database missing, it is there
+ * being no run. `claimGroups` in particular is the choke point that refuses another project's database,
+ * and a guard around it would be a guard around the refusal.
+ */
+async function runGroups(context: RunContext, pass: MigrationPass): Promise<WorkerMigrationRun[]> {
+  const report = emptyReport(context.workers);
+  const groups = await scopedGroups(context);
+  if (groups.length === 0) return report;
+
+  const driver = await driverFor(context, groups);
+  try {
+    await claimGroups(context, driver, groups);
+    if (pass.spansLedger) await assertLedgerDeclared({ env: context.env, driver, groups });
+    for (const [index, group] of groups.entries()) {
+      const target = { binding: group.binding, database: group.database };
+      let results: MigrationResult[];
+      // `try`/`catch` rather than `.catch()`: a pass that throws before it returns a promise — a driver
+      // handing back a database that is not there, a provider that will not build — is not a rejected
+      // promise, and a `.catch()` would not see it (#371).
+      try {
+        results = await pass.execute(driver.database(group), group.provider, target);
+      } catch (error) {
+        // The guard takes no binding. The two names are what an operator acts on; what a migration
+        // throws is already on the error being rethrown, untouched.
+        throw progressReport.carry(error, {
+          migrated: report,
+          failed: target,
+          unreached: groups.slice(index + 1).map((rest) => ({ binding: rest.binding, database: rest.database })),
+        });
+      }
+      record(report, group, results);
+    }
+    return report;
+  } finally {
+    await driver.dispose();
+  }
+}
+
+/**
+ * Every Worker a database in scope could be shared with — the set each group's provider is merged from.
+ *
+ * With nothing pre-resolved that is plain `apps/` discovery, narrowed later, never here. A caller can
+ * also hand over an **already narrowed** set: `pithy add`/`remove`/`upgrade --migrate` pass the single
+ * Worker they just wired. A database that Worker shares still migrates as a whole, so the rest of the
+ * project is discovered alongside it. Best effort by design — a project with nothing importable (a test
+ * fixture, an uninstalled checkout) contributes no neighbors and the caller's set stands alone, exactly
+ * as it did before.
+ */
+async function projectWorkers(options: MigrationFanOutOptions): Promise<WorkerScope[]> {
+  if (!options.workers) return resolveWorkerScopes({ projectDir: options.projectDir });
+
+  const discovered = await resolveWorkerScopes({ projectDir: options.projectDir }).catch(() => []);
+  const workers = [...options.workers];
+  for (const found of discovered) {
+    const known = workers.some((candidate) => resolve(candidate.dir) === resolve(found.dir));
+    if (!known) workers.push(found);
+  }
+  return workers;
+}
+
+/**
+ * Turn the public fan-out options into a run context: the whole project (what each database's registry is
+ * built from) and the run's own scope (what is reported, and which databases are visited). The scope is
+ * always the caller's set narrowed by `--worker`, so an unknown name still fails naming the same Workers.
+ */
+async function contextFor(options: MigrationFanOutOptions & { project?: string }): Promise<RunContext> {
+  const groupWorkers = await projectWorkers(options);
+  return {
+    workers: await resolveWorkerScopes({
+      projectDir: options.projectDir,
+      workers: options.workers ?? groupWorkers,
+      ...(options.worker !== undefined ? { worker: options.worker } : {}),
+    }),
+    groupWorkers,
+    persistRoot: options.projectDir,
+    account: options.account,
+    env: options.env,
+    ...(options.project !== undefined ? { project: options.project } : {}),
+    ...(options.remoteD1 ? { remoteD1: options.remoteD1 } : {}),
+  };
+}
+
+/**
+ * Run (or roll back) every Worker's migration registry — the logic behind `pithy migrate`. Each Worker
+ * contributes its own capabilities; Workers bound to the same physical D1 merge into one run so a shared
+ * database migrates once. Locally that D1 is a Miniflare store under the project root's `.wrangler/state`
+ * (shared with `wrangler dev`); for staging/prod it is the remote database over the D1 REST API.
+ * The registries, ordering, and per-database runs are identical — only the driver differs.
+ */
+export function migrateProject(options: MigrateProjectOptions): Promise<WorkerMigrationRun[]> {
+  return contextFor(options).then((context) =>
+    runGroups(context, {
+      spansLedger: true,
+      execute: (database, provider, target) =>
+        options.rollback ? rollbackMigration(database, provider, target) : runMigrations(database, provider, target),
+    }),
+  );
+}
+
+/**
+ * Fully reset every migrated database's schema — the seam behind `pithy seed --redo`'s destructive
+ * rebuild. Runs the **same fan-out, grouping, and driver** as {@link migrateProject} but calls
+ * `resetMigrations` per database instead of running or rolling back: every applied migration's `down`
+ * runs (all of them, not just the latest), then every migration's `up` reapplies from empty. **This
+ * destroys every row in every table the registry owns — hand-inserted data included — by design**, not
+ * just the rows a seed fixture wrote. Callers gate this behind the same escalating confirmation a
+ * destructive seed needs before calling it.
+ */
+export function resetProject(options: ResetProjectOptions): Promise<WorkerMigrationRun[]> {
+  return contextFor(options).then((context) => runGroups(context, { spansLedger: true, execute: resetMigrations }));
+}
+
+/** One database's place in a {@link resetProject} run: which database, its binding, and how many migrations it carries. */
+export interface ResetPreviewEntry {
+  /** The database being reset (matches a capability's `databases` key). */
+  database: string;
+  /** The D1 binding the database resolves to. */
+  binding: string;
+  /** The number of migrations the merged registry carries for this database — how many roll back, then reapply. */
+  migrations: number;
+}
+
+/**
+ * Preview a {@link resetProject}: which databases are in scope and how many migrations each carries.
+ * Computed from the composed registries and each Worker's `wrangler.jsonc` alone — no backend access, no
+ * credentials, nothing read or written — so it is safe to call for `pithy seed --redo --dry-run` (and to
+ * compute the same numbers a real reset will produce, for the run report). One entry per physical
+ * database, so a database two Workers share is previewed once, with their merged migration count.
+ */
+export async function previewReset(options: MigrationFanOutOptions): Promise<ResetPreviewEntry[]> {
+  const groups = await scopedGroups(await contextFor(options));
+  const preview: ResetPreviewEntry[] = [];
+  for (const group of groups) {
+    const migrations = await group.provider.getMigrations();
+    preview.push({ database: group.database, binding: group.binding, migrations: Object.keys(migrations).length });
+  }
+  return preview;
+}
+
+/** One database in scope whose ledger could not be read at all. Named, because the fix is on that one. */
+export const UnreadableLedger = z
+  .object({
+    database: z.string().describe("The database name — a capability's `databases` key."),
+    binding: z
+      .string()
+      .describe("The D1 binding it resolves to, as wrangler.jsonc declares it — the name an adopter recognizes."),
+  })
+  .describe(
+    "One database whose ledger could not be read on this pass. It carries no reason: what the read threw is throw-site context about somebody's database, and the actionable fact is which database went unread.",
+  );
+export type UnreadableLedger = z.infer<typeof UnreadableLedger>;
+
+/** The two halves of the comparison, over the databases that answered. */
+export const LedgerCounts = z
+  .object({
+    pending: z.number().int().nonnegative().describe("How many declared migrations have not run yet."),
+    undeclared: z
+      .array(UndeclaredMigration)
+      .describe(
+        "Every applied migration this project no longer declares, in group order. Non-empty means `migrate` refuses — see {@link ./ledger} — so a reporter that shows the count and hides this is the #282 bug.",
+      ),
+  })
+  .describe("What the databases that answered have applied, against what this project declares.");
+export type LedgerCounts = z.infer<typeof LedgerCounts>;
+
+/**
+ * What one environment's databases have applied, against what this project declares — **and whether
+ * every one of them answered** (#371).
+ *
+ * A project migrates several databases and the counts are a sum over them, so one unreachable D1 used to
+ * throw out of the loop and lose the ledger for every other database with it. Guarding the loop is only
+ * half the fix: a sum computed over four databases out of five is not the same number as a sum over five,
+ * and nothing in `{ pending, undeclared }` could say so.
+ *
+ * So the scalars live **behind the discriminant**, on #350's rule. `read` carries them flat; `partial`
+ * nests them under `counted` beside the databases that went unread, which is what stops
+ * `if (ledger.state !== "unavailable") use(ledger.pending)` from compiling and quietly reporting a short
+ * sum. `unavailable` carries no number at all.
+ *
+ * **`readProjectLedger` never returns `unavailable`.** It throws instead, because enumerating the
+ * databases is not a contributor to this aggregate — it is the aggregate's precondition, and there is no
+ * partial answer to give when nothing could be enumerated. The state exists for the caller that catches
+ * that throw and still has siblings of its own to report ({@link ../capabilities/reconcile}).
+ */
+export const ProjectLedger = z
+  .discriminatedUnion("state", [
+    z
+      .object({
+        state: z.literal("read").describe("Every database in scope answered."),
+        pending: LedgerCounts.shape.pending.describe("How many declared migrations have not run yet, across them all."),
+        undeclared: LedgerCounts.shape.undeclared.describe(
+          "Every applied migration this project no longer declares, in group order.",
+        ),
+      })
+      .describe("The whole comparison, over every database in scope."),
+    z
+      .object({
+        state: z.literal("partial").describe("Some databases answered and at least one could not be read."),
+        counted: LedgerCounts.describe(
+          "The comparison over the databases that answered — a sum with a known hole in it, which is why it is not spelled the way `read` spells it.",
+        ),
+        unreadable: z
+          .array(UnreadableLedger)
+          .min(1)
+          .describe("Every database whose ledger could not be read. Non-empty, or this would be `read`."),
+      })
+      .describe("A comparison over some of the databases, naming the ones it could not include."),
+    z
+      .object({
+        state: z.literal("unavailable").describe("The ledger could not be read at all."),
+      })
+      .describe(
+        "No comparison was made. Deliberately empty: nothing derived from the failure travels, and there is no number here to mistake for a zero.",
+      ),
+  ])
+  .describe(
+    "What one environment's databases have applied against what this project declares, and whether every database answered. The counts sit behind the discriminant, so a short sum cannot be read as a whole one.",
+  );
+export type ProjectLedger = z.infer<typeof ProjectLedger>;
+
+/**
+ * Read every Worker's databases for an environment against what the project declares — read-only,
+ * applying nothing. It runs the same fan-out, grouping, and driver as {@link migrateProject}, so it
+ * reports against the same D1s (local under the project root's `.wrangler/state`, or the remote
+ * databases over REST) migrate would touch, and reads a database two Workers share once. The seam behind
+ * `pithy doctor`'s migrations line and `pithy deploy`'s warn-only "schema is behind" check.
+ *
+ * **Both directions, because the count alone was the fault.** This replaced `countPendingMigrations`,
+ * whose callers could only ever learn that a declared migration had not run — never that the ledger held
+ * one the project had dropped, which is the state that stops migrate dead (#282). Returning one object
+ * is what keeps a caller from re-acquiring half the question.
+ *
+ * **One database at a time, because the answer is a sum (#371).** A project migrates several databases,
+ * and one of them being unreachable — a revoked token, a deleted D1, a `wrangler.jsonc` naming an id that
+ * is gone — used to throw out of this loop and lose the ledger for every other database in the project.
+ * Each group is read under its own guard now, and a group that will not read is named on `unreadable`
+ * rather than absorbed into a smaller `pending`.
+ *
+ * **Enumerating the databases is not one of the contributors.** `contextFor`, `scopedGroups` and
+ * `driverFor` run before the loop and still throw: they decide *what* the aggregate is over, so their
+ * failure is not one contributor missing, it is there being nothing to aggregate. A caller that wants to
+ * survive that catches it — {@link ../capabilities/reconcile} does, into `unavailable`.
+ *
+ * **The guard takes no binding.** What a D1 read throws names a database id, a token, or a query, and none
+ * of that is anybody's business but the adopter's — so nothing derived from it is kept, which is a
+ * property of the code rather than a promise about it (#350).
+ */
+export async function readProjectLedger(options: MigrationFanOutOptions): Promise<ProjectLedger> {
+  const context = await contextFor(options);
+  const groups = await scopedGroups(context);
+  if (groups.length === 0) return { state: "read", pending: 0, undeclared: [] };
+
+  const driver = await driverFor(context, groups);
+  try {
+    let pending = 0;
+    const undeclared: UndeclaredMigration[] = [];
+    const unreadable: UnreadableLedger[] = [];
+    for (const group of groups) {
+      let read: MigrationLedger;
+      try {
+        read = await readMigrationLedger(driver.database(group), group.provider);
+      } catch {
+        unreadable.push({ database: group.database, binding: group.binding });
+        continue;
+      }
+      pending += read.pending.length;
+      for (const name of read.undeclared) {
+        undeclared.push({ database: group.database, binding: group.binding, name });
+      }
+    }
+    return unreadable.length === 0
+      ? { state: "read", pending, undeclared }
+      : { state: "partial", counted: { pending, undeclared }, unreadable };
+  } finally {
+    await driver.dispose();
+  }
+}
+
+/** Options for {@link dropCapabilityTables}: the capability, the Worker it is wired into, and the env. */
+export interface DropCapabilityOptions {
+  /** The capability being removed, whose migrations to reverse. */
+  capability: Capability;
+  /** The Worker's directory — its `wrangler.jsonc` supplies the D1 bindings and their ids. */
+  workerDir: string;
+  /** The project root whose `.wrangler/state` holds the local D1 every Worker shares. */
+  persistRoot: string;
+  /**
+   * The Cloudflare account this project belongs to. A remote drop reverses migrations against a real
+   * database, so it must be the account the project claims and no other (#206). Required (#234): this
+   * is the most destructive thing `pithy remove` can do, and `defaultRemoveSteps` named no account for
+   * as long as the field was optional.
+   */
+  account: CloudflareAccountSelection | null;
+  /** Target environment. `dev` runs locally via Miniflare; staging/prod over the D1 REST API. */
+  env: string;
+  /**
+   * The project this drop belongs to — the root `pithy.config.ts` `name` (`requireProjectName`).
+   * Checked against the database's recorded owner before a single `down` runs, so a project never
+   * reverses another project's migrations. Required: this is the most destructive thing `pithy remove`
+   * can do, and it ran unchecked for as long as the field was optional.
+   */
+  project: string;
+  /** Test seam: build the remote D1 for a binding instead of the default REST-backed client. */
+  remoteD1?: RemoteD1Factory;
+}
+
+/**
+ * Drop a single capability's tables for an environment — the seam behind `pithy remove --drop`. It runs
+ * the **same grouping and driver** as {@link migrateProject} but over just the removed capability, in
+ * just the Worker it is wired into, so only that capability's migrations are reversed (via
+ * {@link dropMigrations}); every other capability's tables and ledger rows are untouched — including
+ * those of another Worker sharing the same physical D1. Runs before the capability is
+ * unwired/uninstalled, while its `down` code is still present.
+ */
+export async function dropCapabilityTables(options: DropCapabilityOptions): Promise<DatabaseRun[]> {
+  const worker: WorkerScope = {
+    name: options.capability.name,
+    dir: options.workerDir,
+    capabilities: [options.capability],
+  };
+  const context: RunContext = {
+    workers: [worker],
+    // Deliberately just this capability: `dropMigrations` reverses the provider's own migrations
+    // directly, never through Kysely's stepwise `Migrator`, so a partial registry is the point — every
+    // other capability's tables and ledger rows, on this D1 or a Worker sharing it, stay untouched.
+    groupWorkers: [worker],
+    persistRoot: options.persistRoot,
+    account: options.account,
+    env: options.env,
+    project: options.project,
+    ...(options.remoteD1 ? { remoteD1: options.remoteD1 } : {}),
+  };
+  // `spansLedger: false`: this provider is one capability's migrations, and every other capability's row
+  // in the same database is undeclared to it. See {@link MigrationPass}.
+  const [run] = await runGroups(context, { spansLedger: false, execute: dropMigrations });
+  return run?.databases ?? [];
+}