@pithy-sh/core 0.6.1 → 0.7.0

package/src/migrations/retained.ts

@@ -0,0 +1,319 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { CamelCasePlugin } from "kysely";
+import type { Migration, MigrationProvider } from "kysely/migration";
+import { ValidationError } from "../error/pithyError";
+import { declareRetainedDown, retainedTablesOf, retainedTablesOfDown } from "./retainedDeclaration";
+
+/**
+ * **A retained table holds rows that exist nowhere else (#588).**
+ *
+ * A migration's `down` is the tested inverse of its `up`, and for schema that is exactly right. For a
+ * vault it is a `drop table` on the only copy of a credential Google issued. `0100_secrets_0001_init` is
+ * the whole history of the secrets database, so one `pithy migrate --rollback` — which steps back one
+ * migration in every composed database — emptied it in place, on staging, with nothing said first.
+ *
+ * So a capability **declares** a table retained, beside the migrations that create it
+ * (`DatabaseSpec.retained`), and the declaration is recorded on those migrations' own `down` functions
+ * (`./retainedDeclaration`) — by `defineCapability`, and again by `createMigrationRegistry` for a set that
+ * carries it. The refusal is on the operation that runs a `down`, not on a list of commands:
+ * {@link guardRetained} wraps every `down` a provider yields, and the runner applies it to every provider
+ * it is handed.
+ *
+ * ## What is TRUE
+ *
+ * **No `down` runs against a database while a table declared retained in that database holds rows**,
+ * beyond what the caller's {@link RetainedBudget} agreed to destroy. A count, not a boolean, so a flag
+ * somebody has in their shell history for another database does not also authorize this one — and one
+ * budget spent across a whole run, so an agreement to five rows cannot destroy five in every database.
+ *
+ * The budget is the operator's number and nothing else. The CLI's preflight also demands it *equal* the
+ * rows in scope; this floor demands only that no more are spent, and it is deliberately not handed the
+ * preflight's count — a guard fed the answer by the check above it is not a second guard.
+ *
+ * ## Its reach, stated so it can be checked
+ *
+ * - **Database-wide, deliberately.** A `down` cannot be inspected for which tables it drops without running
+ *   it, so any `down` against a database holding retained rows is refused — including a migration of a
+ *   different capability that never touches them. Over-refusing costs an override; under-refusing costs a
+ *   vault.
+ * - **Every `down` through `runner.ts`** — `rollbackMigration`, `resetMigrations`, `dropMigrations` — whose
+ *   function was declared: the registry's providers, the fan-out's merged ones, and a provider written by
+ *   hand, so long as it yields the capability's own migration objects (or spreads of them).
+ * - **Counted over the set the runner is handed as the database.** Rollback and reset are handed one
+ *   provider, and Kysely refuses one that does not span the ledger, so it is the database's. A drop reverses a
+ *   part, and is handed the part and the database separately (`DropSelection`): it counts the database's,
+ *   and refuses to reverse a migration the database's set does not carry. The CLI's `remove --drop` builds
+ *   that set from the Worker's whole composition and every Worker discovered beside it — a capability sharing
+ *   `SECRETS` and declaring nothing is refused while the vault holds rows.
+ * - **Not seen:** a drop whose caller hands the part as the database too (`{ database: part, reverse: part }`
+ *   counts only the part); for `remove --drop`, a table declared only by a Worker whose config does not load;
+ *   a Kysely `Migrator` constructed outside `runner.ts`; a `down` whose capability was never constructed in
+ *   this process and whose set never passed through the registry; a `down` re-wrapped in a new function by
+ *   anything but {@link beforeEachDown} or {@link beforeEachMigration}; and a table no capability declares — a
+ *   capability removed from the config takes its declaration with it.
+ */
+
+/** The snake_case the `CamelCasePlugin` writes, read from the plugin itself so there is one definition. */
+class TableNames extends CamelCasePlugin {
+  sqlName(key: string): string {
+    return this.snakeCase(key);
+  }
+}
+
+const NAMES = new TableNames();
+
+/** The SQL name of a declared table key — `pithySecretsSystemSecrets` → `pithy_secrets_system_secrets`. */
+export function retainedTableName(key: string): string {
+  return NAMES.sqlName(key);
+}
+
+/** One retained table that holds rows, on the binding it was counted through. */
+export interface RetainedRows {
+  /** The D1 binding the table lives behind — the name an adopter recognizes. */
+  binding: string;
+  /** The SQL table name. */
+  table: string;
+  /** How many rows it holds. Always positive: an empty or absent table is not at risk. */
+  rows: number;
+}
+
+/** The SQL names of the retained tables a provider's migrations declare. Reads no database. */
+export async function retainedTableNames(provider: MigrationProvider): Promise<string[]> {
+  return retainedTablesOf(await provider.getMigrations()).map(retainedTableName);
+}
+
+/**
+ * Count the rows in every retained table these migrations declare that is present in the database.
+ * Read-only. Returns only the tables holding rows, so an empty result means nothing retained is at risk.
+ */
+export async function countRetainedRows(
+  database: D1Database,
+  migrations: Readonly<Record<string, Migration>>,
+  binding: string,
+): Promise<RetainedRows[]> {
+  const counted: RetainedRows[] = [];
+  for (const key of retainedTablesOf(migrations)) {
+    const table = retainedTableName(key);
+    const present = await database
+      .prepare("select name from sqlite_master where type = 'table' and name = ?")
+      .bind(table)
+      .first<{ name: string }>();
+    if (!present) continue;
+    // The name came from a capability's declaration and through the plugin's own snake-casing, never from
+    // input, and it has just been matched against `sqlite_master` — quoting it is belt, not braces.
+    const row = await database.prepare(`select count(*) as n from "${table}"`).first<{ n: number }>();
+    const rows = row?.n ?? 0;
+    if (rows > 0) counted.push({ binding, table, rows });
+  }
+  return counted;
+}
+
+/**
+ * The refusals raised ahead of a `down`. A `Migrator` catches whatever a `down` throws and hands it back as
+ * a result, and the runner turns that into "Couldn't roll back" with a remedy to fix the migration — which
+ * is wrong for a refusal, where no migration is broken. So the runner asks {@link isDownRefusal} and
+ * rethrows one unchanged.
+ */
+const REFUSALS = new WeakSet<object>();
+
+/**
+ * Mark an error as a refusal to run a `down`, so it reaches the operator as itself rather than as a failed
+ * migration. For a guard written outside this module — the CLI's shared-database floor is one.
+ */
+export function downRefusal<E extends ValidationError>(error: E): E {
+  REFUSALS.add(error);
+  return error;
+}
+
+/** Whether `error` refused a `down` before it ran — as opposed to a migration that failed. */
+export function isDownRefusal(error: unknown): error is ValidationError {
+  return typeof error === "object" && error !== null && REFUSALS.has(error);
+}
+
+/** `5 rows`, `1 row`. */
+function rowsLabel(count: number): string {
+  return `${count} row${count === 1 ? "" : "s"}`;
+}
+
+/**
+ * What a refusal was raised ahead of, as the sentence ends: `Refused before <this>.` A `down` for the
+ * runner and the migration fan-out; a database deletion for a teardown that removes the database whole
+ * (#591), where "any down ran" would name an operation that was never going to happen.
+ */
+export type RefusedBefore = "any down against them ran" | "anything was deleted";
+
+/**
+ * The refusal, in one wording for every place that raises it — the fan-out's preflight, which names every
+ * database before any of them moves, {@link guardRetained}, which is the floor under it, and a teardown
+ * that deletes a database holding retained tables (`pithy secrets deprovision`, #591).
+ *
+ * `consent` is what the caller passed. The action always prints the number that would work, because that
+ * number is the one fact the operator has to read before typing it.
+ */
+export function retainedRefusal(
+  atRisk: readonly RetainedRows[],
+  consent: number | undefined,
+  before: RefusedBefore = "any down against them ran",
+): ValidationError {
+  return downRefusal(refusalFor(atRisk, consent, before));
+}
+
+/**
+ * **The preflight: refuse unless the operator counted exactly the retained rows in scope.**
+ *
+ * Absent a count, only an empty scope passes; given one, only the same number does — a count that is too
+ * high is a count of something else, and agreeing to it would let a stale number from shell history through
+ * the day the rows it described are joined by more. Call it with every database the operation will touch,
+ * counted before the first of them moves, so the refusal names them all with nothing changed.
+ *
+ * The floor under it is {@link RetainedBudget}, fed the operator's number and never this function's
+ * count.
+ */
+export function assertRetainedAgreed(
+  atRisk: readonly RetainedRows[],
+  consent: number | undefined,
+  before: RefusedBefore = "any down against them ran",
+): void {
+  const total = atRisk.reduce((sum, entry) => sum + entry.rows, 0);
+  const agreed = consent === undefined ? total === 0 : consent === total;
+  if (!agreed) throw retainedRefusal(atRisk, consent, before);
+}
+
+function refusalFor(
+  atRisk: readonly RetainedRows[],
+  consent: number | undefined,
+  before: RefusedBefore,
+): ValidationError {
+  const total = atRisk.reduce((sum, entry) => sum + entry.rows, 0);
+  const named = atRisk.map((entry) => `${entry.table} on ${entry.binding} (${rowsLabel(entry.rows)})`).join(", ");
+  const mismatch =
+    consent === undefined ? "" : `--destroy-retained ${consent} does not match the ${rowsLabel(total)} at risk. `;
+  if (total === 0) {
+    return new ValidationError({
+      message: `${mismatch}Nothing retained is at risk. Refused before ${before === "anything was deleted" ? before : "any down ran"}.`,
+      action: "Run it again without --destroy-retained.",
+    });
+  }
+  return new ValidationError({
+    message: `${mismatch}Retained ${rowsLabel(total)} would be dropped: ${named}. Refused before ${before}.`,
+    action: `They exist nowhere else. Back them up, or pass --destroy-retained ${total} to drop them.`,
+    detail:
+      "A retained table is declared by its capability. Any down against its database, and any deletion of the database, is refused while it holds rows.",
+  });
+}
+
+/**
+ * **How many retained rows a run has agreed to destroy, spent as each database is reached.**
+ *
+ * One per run, shared by every database in it. Absent an agreement it holds nothing, so any retained row
+ * refuses. A database whose rows exceed what is left is refused whole — nothing is spent on a refusal.
+ */
+export class RetainedBudget {
+  /** What the caller agreed to, as they typed it — the number a refusal quotes back. */
+  readonly agreed: number | undefined;
+  #remaining: number;
+
+  constructor(agreed: number | undefined) {
+    this.agreed = agreed;
+    this.#remaining = agreed ?? 0;
+  }
+
+  /** Spend `rows` if the budget covers them. False, and nothing spent, when it does not. */
+  spend(rows: number): boolean {
+    if (rows > this.#remaining) return false;
+    this.#remaining -= rows;
+    return true;
+  }
+}
+
+/**
+ * Wrap a provider so no `down` it yields runs while the database holds retained rows the budget does not
+ * cover. The check runs once, at the first `down`, and its answer stands for the rest of the run: a reset
+ * whose first `down` dropped the vault must not refuse its second for finding it empty.
+ *
+ * Counted at the `down`, not before: a row written after somebody else counted is a row this refuses.
+ */
+export function guardRetained(
+  provider: MigrationProvider,
+  database: D1Database,
+  options: { binding: string; budget: RetainedBudget },
+): MigrationProvider {
+  let cleared: Promise<void> | undefined;
+  const check = async (): Promise<void> => {
+    const atRisk = await countRetainedRows(database, await provider.getMigrations(), options.binding);
+    const total = atRisk.reduce((sum, entry) => sum + entry.rows, 0);
+    if (!options.budget.spend(total)) throw retainedRefusal(atRisk, options.budget.agreed);
+  };
+  return beforeEachDown(provider, async () => {
+    cleared ??= check();
+    await cleared;
+  });
+}
+
+/** Which way one migration is about to move — Kysely's own spelling, as a `MigrationResult` carries it. */
+export type MigrationDirection = "Up" | "Down";
+
+/** Called ahead of one migration's body, with its composed name and the direction it is about to move. */
+export type BeforeMigration = (name: string, direction: MigrationDirection) => Promise<void>;
+
+/**
+ * Wrap a provider so `before` runs ahead of every migration body it yields, in each of `directions` — and a
+ * throw from `before` means that body never runs. A direction not listed passes through untouched.
+ *
+ * **Each new `down` keeps the declaration of the one it wraps.** That is the reason this is the one way to
+ * wrap a provider's migrations: a hand-rolled wrapper is a new function the declaration has never heard of,
+ * and {@link guardRetained} handed it would find nothing declared and let every `down` through.
+ */
+function wrapEach(
+  provider: MigrationProvider,
+  before: BeforeMigration,
+  directions: readonly MigrationDirection[],
+): MigrationProvider {
+  return {
+    getMigrations: async (): Promise<Record<string, Migration>> => {
+      const migrations = await provider.getMigrations();
+      return Object.fromEntries(
+        Object.entries(migrations).map(([name, migration]) => {
+          const { up, down } = migration;
+          const wrappedUp = directions.includes("Up")
+            ? async (db: Parameters<typeof up>[0]): Promise<void> => {
+                await before(name, "Up");
+                await up(db);
+              }
+            : up;
+          if (!down || !directions.includes("Down")) return [name, { ...migration, up: wrappedUp }];
+          const wrappedDown = async (db: Parameters<typeof down>[0]): Promise<void> => {
+            await before(name, "Down");
+            await down(db);
+          };
+          declareRetainedDown(wrappedDown, retainedTablesOfDown(down));
+          const wrapped: Migration = { up: wrappedUp, down: wrappedDown };
+          return [name, wrapped];
+        }),
+      );
+    },
+  };
+}
+
+/**
+ * Wrap a provider so `before` runs ahead of every `down` it yields — and a throw from `before` means the
+ * `down` never runs. Ups pass through untouched. A declared `down` stays declared: see {@link wrapEach}.
+ */
+export function beforeEachDown(provider: MigrationProvider, before: () => Promise<void>): MigrationProvider {
+  return wrapEach(provider, () => before(), ["Down"]);
+}
+
+/**
+ * Wrap a provider so `before` hears each migration's name and direction ahead of its body, up or down (#583).
+ *
+ * The seam a caller uses to say which migration it is on while it is on it: the CLI raises a `▸` step here,
+ * because a remote migration is a D1 round trip per statement and an operator watching nothing happen
+ * cannot tell a slow schema change from a hung one. Core carries no terminal concern — it hands over the
+ * name and the direction, and what is done with them is the caller's. A declared `down` stays declared.
+ */
+export function beforeEachMigration(provider: MigrationProvider, before: BeforeMigration): MigrationProvider {
+  return wrapEach(provider, before, ["Up", "Down"]);
+}

package/src/migrations/retainedDeclaration.ts

@@ -0,0 +1,56 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Migration } from "kysely/migration";
+
+/**
+ * **Where a retained declaration is kept: on the `down` that would destroy the table (#588).**
+ *
+ * A capability says which of its tables are retained (`DatabaseSpec.retained`). The runner has to know it
+ * at the moment a `down` is about to run, and by then all it holds is a `MigrationProvider` — Kysely's
+ * interface, rebuilt by the registry, merged by the fan-out, wrapped by `batchedProvider`, and written by
+ * hand in every capability's own migration tests. A declaration kept on any of those objects is lost the
+ * first time somebody builds a new one.
+ *
+ * The `down` function survives all of that. A registry keeps the capability's migration object; a spread
+ * that rebuilds the record keeps the same `down`; a hand-built provider in a test names the very
+ * `secrets_0001_init` the capability ships. So the declaration is keyed on the function itself, and any
+ * provider that yields it carries it.
+ *
+ * Kept apart from `./retained` so `defineCapability` can declare without importing Kysely's runtime.
+ */
+
+/** The destructive function → the retained table keys (camelCase, as `tables` declares them) it can drop. */
+const DECLARED = new WeakMap<object, readonly string[]>();
+
+/** Record that every `down` in `migrations` runs against a database holding these retained tables. */
+export function declareRetained(migrations: Readonly<Record<string, Migration>>, tables: readonly string[]): void {
+  if (tables.length === 0) return;
+  for (const migration of Object.values(migrations)) {
+    if (migration.down) declareRetainedDown(migration.down, tables);
+  }
+}
+
+/** Record one `down` — for a wrapper that replaces a declared `down` with its own function. */
+export function declareRetainedDown(down: object, tables: readonly string[]): void {
+  if (tables.length === 0) return;
+  DECLARED.set(down, [...new Set([...(DECLARED.get(down) ?? []), ...tables])]);
+}
+
+/** The retained table keys declared on one `down`. */
+export function retainedTablesOfDown(down: object): readonly string[] {
+  return DECLARED.get(down) ?? [];
+}
+
+/**
+ * The retained table keys any migration in a set declares — the database-wide answer, since a `down` is
+ * refused for rows in *any* retained table of the database it runs against.
+ */
+export function retainedTablesOf(migrations: Readonly<Record<string, Migration>>): string[] {
+  const tables = new Set<string>();
+  for (const migration of Object.values(migrations)) {
+    if (!migration.down) continue;
+    for (const table of retainedTablesOfDown(migration.down)) tables.add(table);
+  }
+  return [...tables].sort();
+}

package/src/migrations/runner.ts

@@ -8,6 +8,7 @@ import { causeMessage } from "../error/cause";
 import { InternalError } from "../error/pithyError";
 import { batchedProvider } from "./batch";
 import { MIGRATION_LOCK_TABLE, MIGRATION_TABLE, migrationKysely } from "./bookkeeping";
+import { guardRetained, isDownRefusal, RetainedBudget } from "./retained";
 
 /**
  * The per-database migration runner. The registry yields one `MigrationProvider` per database
@@ -49,12 +50,18 @@ import { MIGRATION_LOCK_TABLE, MIGRATION_TABLE, migrationKysely } from "./bookke
  * capability arrives with its whole set. Refusing the add with an actionable error was the
  * alternative; it explains the corner instead of removing it.
  */
-function migrator(database: D1Database, provider: MigrationProvider): Migrator {
+function migrator(
+  database: D1Database,
+  provider: MigrationProvider,
+  target: MigrationTarget | undefined,
+  consent: RetainedConsent | undefined,
+): Migrator {
   return new Migrator({
     db: migrationKysely(database),
     // Each migration body applies in one `d1.batch()`; the ledger row stays on the ordinary path,
-    // so nothing batches across a migration boundary. See `./batch`.
-    provider: batchedProvider(provider, database),
+    // so nothing batches across a migration boundary. See `./batch`. Every `down` is guarded before it
+    // is batched: no reversal runs while a retained table in this database holds rows (#588).
+    provider: batchedProvider(guardRetained(provider, database, guardOptions(target, consent)), database),
     migrationTableName: MIGRATION_TABLE,
     migrationLockTableName: MIGRATION_LOCK_TABLE,
     allowUnorderedMigrations: true,
@@ -76,13 +83,35 @@ export interface MigrationTarget {
   database: string;
 }
 
+/**
+ * What a caller that reverses migrations says about retained rows (#588) — see `./retained`.
+ *
+ * Optional, and absent is the safe answer: a caller that says nothing has counted nothing, so any `down`
+ * against a database holding retained rows is refused.
+ */
+export interface RetainedConsent {
+  /**
+   * The retained rows the caller agreed to destroy. Pass one budget to every database in a run, so one
+   * agreement is spent once; a caller reversing a single database builds its own. Absent means none.
+   */
+  budget?: RetainedBudget;
+}
+
+/** The guard's options: the binding its refusal names, and the budget the caller agreed to. */
+function guardOptions(
+  target: MigrationTarget | undefined,
+  consent: RetainedConsent | undefined,
+): { binding: string; budget: RetainedBudget } {
+  return { binding: target?.binding ?? "this database", budget: consent?.budget ?? new RetainedBudget(undefined) };
+}
+
 /** Run every pending migration to latest. An empty provider resolves to `[]`. */
 export async function runMigrations(
   database: D1Database,
   provider: MigrationProvider,
   target?: MigrationTarget,
 ): Promise<MigrationResult[]> {
-  const { error, results } = await migrator(database, provider).migrateToLatest();
+  const { error, results } = await migrator(database, provider, target, undefined).migrateToLatest();
   return settle("run", error, results, target);
 }
 
@@ -123,13 +152,18 @@ export async function readMigrationLedger(database: D1Database, provider: Migrat
   };
 }
 
-/** Step the latest applied migration back — one step, the `pithy migrate --rollback` seam. */
+/**
+ * Step this database's latest applied migration back — one step, per database. `pithy migrate --rollback`
+ * calls it once for **every** database in its fan-out. Refused while a retained table here holds rows the
+ * caller has not counted in `consent` (#588).
+ */
 export async function rollbackMigration(
   database: D1Database,
   provider: MigrationProvider,
   target?: MigrationTarget,
+  consent?: RetainedConsent,
 ): Promise<MigrationResult[]> {
-  const { error, results } = await migrator(database, provider).migrateDown();
+  const { error, results } = await migrator(database, provider, target, consent).migrateDown();
   return settle("rollback", error, results, target);
 }
 
@@ -139,14 +173,16 @@ export async function rollbackMigration(
  * `up` reapplies from empty. The seam behind `pithy seed --redo`'s destructive rebuild: because the
  * schema comes back empty, the ordinary non-destructive seed writes (`INSERT OR IGNORE`, KV
  * skip-if-exists) simply work afterward — there is no per-row identity problem to solve. An empty
- * ledger rolls back nothing; an empty provider reapplies nothing.
+ * ledger rolls back nothing; an empty provider reapplies nothing. Refused, before the first `down`, while a
+ * retained table here holds rows the caller has not counted in `consent` (#588).
  */
 export async function resetMigrations(
   database: D1Database,
   provider: MigrationProvider,
   target?: MigrationTarget,
+  consent?: RetainedConsent,
 ): Promise<MigrationResult[]> {
-  const runner = migrator(database, provider);
+  const runner = migrator(database, provider, target, consent);
   const down = await runner.migrateTo(NO_MIGRATIONS);
   const downResults = settle("resetDown", down.error, down.results, target);
   const up = await runner.migrateToLatest();
@@ -169,26 +205,57 @@ async function appliedMigrationNames(db: Kysely<unknown>): Promise<Set<string>>
 }
 
 /**
- * Surgically drop **one capability's** migrations: run each of the provider's `down` functions in
+ * What a drop reverses, and the database it reverses it in.
+ *
+ * Two providers because they answer two questions. `reverse` is the part being removed — one capability's
+ * migrations. `database` is every migration composed into that D1, and it is what the retained guard counts:
+ * a table is retained in a *database*, and the capability being dropped is the one least likely to declare
+ * the vault it shares a database with (#588). Handed only the part, the guard counted what the part declared
+ * — nothing — while the vault beside it held rows.
+ */
+export interface DropSelection {
+  /** Every migration composed into this database — the set whose retained declarations are counted. */
+  database: MigrationProvider;
+  /** The migrations to reverse: a part of `database`, by composed name. */
+  reverse: MigrationProvider;
+}
+
+/**
+ * Surgically drop **one capability's** migrations: run each of `drop.reverse`'s `down` functions in
  * reverse order and delete only those ledger rows, leaving every other capability's tables and
  * bookkeeping untouched. The seam behind `pithy remove --drop`. Kysely's stepwise `Migrator` refuses a
  * provider that doesn't span the whole ledger (it reads a foreign row as corrupt state), so a
  * per-capability drop can't go through it — this reverses the capability's own migrations directly.
- * Only migrations recorded in the ledger are reversed; an absent ledger drops nothing.
+ * Only migrations recorded in the ledger are reversed; an absent ledger drops nothing. Refused, before the
+ * first `down`, while a retained table **anywhere in `drop.database`** holds rows the caller has not counted
+ * in `consent` (#588). A name `drop.reverse` carries that `drop.database` does not is an internal fault: the
+ * guard would not have counted the database the `down` runs in.
  */
 export async function dropMigrations(
   database: D1Database,
-  provider: MigrationProvider,
+  drop: DropSelection,
   target?: MigrationTarget,
+  consent?: RetainedConsent,
 ): Promise<MigrationResult[]> {
   const db = migrationKysely(database);
-  // Batched here too: `down` pays the same per-statement cost `up` does, and a drop is all DDL.
-  const migrations = await batchedProvider(provider, database).getMigrations();
+  // Batched here too: `down` pays the same per-statement cost `up` does, and a drop is all DDL. Guarded
+  // first, exactly as the `Migrator` path is (#588) — over the whole database's set, so the count is too.
+  const guarded = guardRetained(drop.database, database, guardOptions(target, consent));
+  const migrations = await batchedProvider(guarded, database).getMigrations();
+  const reversing = Object.keys(await drop.reverse.getMigrations());
+  const stray = reversing.filter((name) => !(name in migrations));
+  if (stray.length > 0) {
+    throw new InternalError({
+      message: `Couldn't drop ${stray.map((name) => `"${name}"`).join(", ")}${on(target)}. The database's migrations do not carry it.`,
+      detail: `${where(target)} A drop counts retained rows over the database's whole set, so every migration it reverses must be in it.`,
+      action: "Build the drop from the database's composed migrations. Nothing was dropped.",
+    });
+  }
   const applied = await appliedMigrationNames(db);
 
   const results: MigrationResult[] = [];
   // Reverse application order: drop the newest of the capability's migrations first.
-  for (const name of Object.keys(migrations).sort().reverse()) {
+  for (const name of reversing.sort().reverse()) {
     if (!applied.has(name)) continue;
     // No `down` — the migration can't be reversed, so leave both its table and its ledger row in place
     // (deleting the row would desync the ledger from the schema). Every Pithy migration ships a `down`.
@@ -199,6 +266,8 @@ export async function dropMigrations(
       await sql`delete from ${sql.table(MIGRATION_TABLE)} where name = ${name}`.execute(db);
       results.push({ migrationName: name, direction: "Down", status: "Success" });
     } catch (error) {
+      // A refusal is not a failed drop: nothing is broken, and "fix the migration's down" would be a lie.
+      if (isDownRefusal(error)) throw error;
       const dropped = results.map((result) => `"${result.migrationName}"`);
       throw new InternalError(
         {
@@ -223,7 +292,9 @@ const VOICE = {
   rollback: {
     failed: (key: string) => `Couldn't roll back "${key}"`,
     fallback: "The rollback failed",
-    action: "Fix the migration. Run pithy migrate --rollback again.",
+    // Never "run --rollback again": a rollback steps back every database, so a second one after a partial
+    // failure reverses a second migration in each database that already moved (#588).
+    action: "Fix the migration's down. Run pithy doctor to see where each database stands.",
   },
   resetDown: {
     failed: (key: string) => `Couldn't roll back "${key}" during reset`,
@@ -273,6 +344,9 @@ function settle(
   target?: MigrationTarget,
 ): MigrationResult[] {
   if (error !== undefined) {
+    // A guard refused before a `down` ran. It already names what it protected and the way past it, and
+    // nothing about it is a migration to fix — so it reaches the operator as itself (#588).
+    if (isDownRefusal(error)) throw error;
     const voice = VOICE[verb];
     const failed = results?.find((result) => result.status === "Error");
     const applied = results?.filter((result) => result.status === "Success").map((result) => result.migrationName);

package/src/naming/environment.ts

@@ -52,6 +52,41 @@ export const GLOBAL_SCOPE = "global";
  */
 export const FEATURE_ENVIRONMENT = "feature";
 
+/**
+ * **The segment a feature takes where an environment sits** — `f<issue>`, as in `<project>-f69-demo-db-d1`.
+ *
+ * Defined here, beside the environment rule, because the two share a slot in every composed name and the
+ * environment rule has to refuse this shape: `feature.ts` composes a feature's head with it, and
+ * {@link isValidEnvironment} refuses an environment that starts with one. A marker composed in one module and
+ * recognized in another would be two statements of one shape, and the next person to change one would not
+ * find the other.
+ */
+export function featureMarker(issue: string): string {
+  return `f${issue}`;
+}
+
+/** Every string {@link featureMarker} can compose: an `f` and one or more digits, as a whole segment. */
+const FEATURE_MARKER = /^f[0-9]+$/;
+
+/** Is this whole hyphen-delimited segment a feature's marker? `f1` and `f01` are; `f1a` and `feature` are not. */
+export function isFeatureMarker(segment: string): boolean {
+  return FEATURE_MARKER.test(segment);
+}
+
+/**
+ * Does this environment start where a feature's name does?
+ *
+ * **Exactly the environments that can collide with a feature (#587).** A declared environment composes
+ * `<project>-<env>-<thing>`, a feature `<project>-f<issue>-<slug>-<thing>`, and a feature Worker's name has no
+ * kind suffix to tell the two apart. After the shared `<project>-`, the two strings can only be equal when the
+ * environment's first segment is the feature's marker — `f1-demo` meets feature 1-demo's Worker `api`, and `f1`
+ * meets it too, through a Worker called `demo-api`. Any other first segment differs from every marker, so no
+ * name composed under it can be a feature's. So this is the whole rule, not one case of it.
+ */
+function startsWithFeatureMarker(name: string): boolean {
+  return isFeatureMarker(name.split("-")[0] ?? "");
+}
+
 /**
  * The longest an environment name may be — **the longest canonical one, `staging`**.
  *
@@ -77,6 +112,7 @@ export const MAX_ENVIRONMENT_NAME = Math.max(...ENVIRONMENTS.map((environment) =
  */
 export function isValidEnvironment(name: string): boolean {
   if (name === GLOBAL_SCOPE) return false;
+  if (startsWithFeatureMarker(name)) return false;
   return name.length <= MAX_ENVIRONMENT_NAME && NAME_SEGMENT.test(name);
 }
 
@@ -104,6 +140,13 @@ export function assertValidEnvironment(name: string): void {
       detail: `${GLOBAL_SCOPE} occupies the environment slot of a composed name for values shared across every environment.`,
     });
   }
+  if (startsWithFeatureMarker(name)) {
+    throw new ValidationError({
+      message: `"${name}" starts the way a feature's name does.`,
+      action: "Start the environment with something other than f and a number.",
+      detail: `A feature takes the environment's slot with f<issue>, so <project>-${name}-<worker> can be a feature's Worker name exactly, and \`pithy feature destroy\` deletes that Worker.`,
+    });
+  }
   if (name.length > MAX_ENVIRONMENT_NAME && NAME_SEGMENT.test(name)) {
     throw new ValidationError({
       message: `"${name}" is ${name.length} characters. An environment stops at ${MAX_ENVIRONMENT_NAME}.`,

package/src/naming/feature.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import { ValidationError } from "../error/pithyError";
+import { featureMarker } from "./environment";
 import { MAX_ISSUE_DIGITS, NAMESPACE_LIMITS } from "./limits";
 import { assertValidProjectName, fitSegment, kebab } from "./resource";
 
@@ -63,7 +64,7 @@ function assertIssue(issue: string): void {
 function head(identity: FeatureIdentity): string {
   assertValidProjectName(identity.project);
   assertIssue(identity.issue);
-  return `${kebab(identity.project)}-f${identity.issue}`;
+  return `${kebab(identity.project)}-${featureMarker(identity.issue)}`;
 }
 
 /**
@@ -156,7 +157,13 @@ export function featureSecretEntryName(identity: FeatureIdentity, secret: string
  * floored the slug at one character and never touched the worker segment, so it ran unbounded — 69
  * characters for a worker called `collaboration-realtime-gateway`, 109 for a 70-character one. `apps/<name>`
  * has a charset rule and no length rule, so nothing upstream was going to stop it either.
+ *
+ * **`app` is the `apps/<app>` directory, never the deploy name.** A scaffolded Worker deploys as
+ * `<project>-<app>`, and handing that here composed `<project>-f<issue>-<slug>-<project>-<app>` — the
+ * project twice, spent out of the budget above (#587). This function takes a string and cannot tell the
+ * two apart, so the provisioning path reaches it only through `featureScope`, which is handed both names
+ * and picks.
  */
-export function featureWorkerName(identity: FeatureIdentity, worker: string): string {
-  return composeFeatureName(head(identity), kebab(identity.slug), kebab(worker), "", NAMESPACE_LIMITS.worker.maxLength);
+export function featureWorkerName(identity: FeatureIdentity, app: string): string {
+  return composeFeatureName(head(identity), kebab(identity.slug), kebab(app), "", NAMESPACE_LIMITS.worker.maxLength);
 }