@pithy-sh/core 0.1.0

package/src/migrations/bookkeeping.ts

@@ -0,0 +1,85 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import type { DatabaseIntrospector, DatabaseMetadataOptions, SchemaMetadata, TableMetadata } from "kysely";
+import { CamelCasePlugin, Kysely } from "kysely";
+import { D1Dialect } from "kysely-d1";
+
+/**
+ * The bookkeeping a Pithy database carries beside the tables its capabilities own — the ledger, the
+ * lock, the owning project — and the one Kysely every reader and writer of them is built from.
+ *
+ * It lives apart from the runner because two modules need it: `runner.ts` migrates through it, and
+ * `owner.ts` stamps the owning project through it. Sharing the dialect is not a convenience — the
+ * introspector below is a workaround, and a second copy of it would drift.
+ *
+ * Kysely's `Migrator` checks for its bookkeeping tables through the dialect's introspector, and the
+ * stock `SqliteIntrospector` joins `pragma_table_info(...)` — a table-valued pragma D1 rejects with
+ * `SQLITE_AUTH`. So this dialect's introspector reads `sqlite_master` alone, which is all the
+ * `Migrator` needs (table names). `CamelCasePlugin` is installed like every Pithy database — write
+ * camelCase, store snake_case.
+ */
+
+/** The `sqlite_master` rows the introspector reads; D1 permits plain selects against it. */
+interface SqliteMasterDatabase {
+  sqlite_master: { name: string; type: string };
+}
+
+/**
+ * The applied-migration ledger. Renamed off Kysely's `kysely_migration` default: an adopter running
+ * their own Kysely migrations on the same D1 would otherwise collide on it (principle 1).
+ */
+export const MIGRATION_TABLE = "pithy_migrations";
+
+/** The migration lock, renamed off Kysely's `kysely_migration_lock` default for the same reason. */
+export const MIGRATION_LOCK_TABLE = "pithy_migrations_lock";
+
+/**
+ * The owning project's stamp — one row, written by `claimMigrationOwnership`, read by `pithy migrate`
+ * before it applies anything. Deliberately *beside* the ledger rather than inside it: it is not a
+ * migration, so a rollback or a full reset must not remove it, and no capability has to ship it.
+ */
+export const MIGRATION_OWNER_TABLE = "pithy_migrations_owner";
+
+/** Pithy's bookkeeping tables — hidden by the introspector the way Kysely hides its own defaults. */
+const INTERNAL_TABLES = [MIGRATION_TABLE, MIGRATION_LOCK_TABLE, MIGRATION_OWNER_TABLE];
+
+/** Table names from `sqlite_master` only — no pragma joins, no column metadata. */
+class D1Introspector implements DatabaseIntrospector {
+  readonly #db: Kysely<SqliteMasterDatabase>;
+
+  constructor(db: Kysely<SqliteMasterDatabase>) {
+    this.#db = db;
+  }
+
+  async getSchemas(): Promise<SchemaMetadata[]> {
+    return [];
+  }
+
+  async getTables(options: DatabaseMetadataOptions = { withInternalKyselyTables: false }): Promise<TableMetadata[]> {
+    let query = this.#db
+      .selectFrom("sqlite_master")
+      .where("type", "in", ["table", "view"])
+      .where("name", "not like", "sqlite_%")
+      .select(["name", "type"])
+      .orderBy("name");
+    if (!options.withInternalKyselyTables) {
+      query = query.where("name", "not in", INTERNAL_TABLES);
+    }
+    const rows = await query.execute();
+    return rows.map((row) => ({ name: row.name, isView: row.type === "view", isForeign: false, columns: [] }));
+  }
+}
+
+/** The D1 dialect Pithy migrates through: stock kysely-d1, with the `sqlite_master`-only introspector. */
+export class D1MigrationDialect extends D1Dialect {
+  override createIntrospector(db: Kysely<unknown>): DatabaseIntrospector {
+    return new D1Introspector(db as Kysely<SqliteMasterDatabase>);
+  }
+}
+
+/** A Kysely over one D1 binding, with Pithy's dialect and `CamelCasePlugin` — the one way in. */
+export function migrationKysely<DB = unknown>(database: D1Database): Kysely<DB> {
+  return new Kysely<DB>({ dialect: new D1MigrationDialect({ database }), plugins: [new CamelCasePlugin()] });
+}

package/src/migrations/owner.ts

@@ -0,0 +1,166 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import type { Kysely } from "kysely";
+import { sql } from "kysely";
+import { z } from "zod";
+import { SQLiteDate } from "../data/codecs";
+import { ConflictError, ValidationError } from "../error/pithyError";
+import { MIGRATION_OWNER_TABLE, migrationKysely } from "./bookkeeping";
+
+/**
+ * Which project owns a database — the guard behind `pithy migrate`.
+ *
+ * Table names stay `pithy_<capability>_<table>` in every project, on purpose: they are baked into
+ * migration keys and every meta-test, and the prefix exists to avoid clashing with the *adopter's*
+ * tables, not with another Pithy app's. The cost is that two unrelated projects pointed at one D1
+ * merge their schemas silently, each applying migrations the other has never heard of. So the name
+ * stays and the database records its owner instead: the first run stamps the project, every later run
+ * checks it, and a second project is refused by name rather than quietly joined.
+ *
+ * The stamp is bookkeeping, not a migration. It sits in its own table beside the ledger and the lock,
+ * created on demand, so no capability ships it, `--rollback` cannot step it back, and `pithy seed
+ * --redo`'s full reset — which rolls every migration down and back up — cannot wipe it. A database
+ * that once belonged to a project keeps saying so even with no schema left in it.
+ *
+ * Workers sharing one database is the supported path and is unaffected: they share by declaring the
+ * same binding name *within one project*, so every one of them claims the same owner.
+ */
+
+/** The single bookkeeping row's fixed primary key — one owner per database, by construction. */
+const OWNER_ROW_ID = 1;
+
+/** The recorded owner of a database: who stamped it, and when. */
+export const MigrationOwner = z
+  .object({
+    project: z
+      .string()
+      .describe("The owning project — the root pithy.config.ts `name`, kebab-cased, as it was at first migrate."),
+    stampedAt: SQLiteDate.describe("When the project first claimed this database. Never rewritten by a later run."),
+  })
+  .describe("One database's owning project, recorded in the migration bookkeeping the first time it is migrated.");
+export type MigrationOwner = z.output<typeof MigrationOwner>;
+
+/**
+ * The owner table as Kysely sees it: the schema's `z.input` (SQLite row) side — derived, never a
+ * hand-written row interface — plus the fixed primary key that makes a second owner unrepresentable.
+ * The key is the table's real name because `MIGRATION_OWNER_TABLE` is the single source of it;
+ * `CamelCasePlugin` passes an already-snake_case identifier through unchanged, and still maps the
+ * `stampedAt` column both ways.
+ */
+interface OwnerDatabase {
+  pithy_migrations_owner: z.input<typeof MigrationOwner> & { id: number };
+}
+
+/** How a claim resolved: the database had no owner, or it already had this one. */
+export type OwnershipOutcome = "adopted" | "confirmed";
+
+/** The result of a successful claim — a refused one throws instead. */
+export interface ProjectOwnership {
+  /** The claiming project, which is now (or already was) the recorded owner. */
+  project: string;
+  /** `adopted` on the first migrate of a database, `confirmed` on every run after it. */
+  outcome: OwnershipOutcome;
+  /** When the owner was first recorded — the original stamp, not this run. */
+  stampedAt: Date;
+}
+
+/** Who is claiming, and how to name the database if the claim is refused. */
+export interface ClaimOwnershipOptions {
+  /** The claiming project — the root `pithy.config.ts` `name`, kebab-cased (`requireProjectName`). */
+  project: string;
+  /** The binding this database is reached by (`DB`), so a refusal names it. Optional. */
+  binding?: string;
+}
+
+/** Whether the owner table has been created yet — a plain `sqlite_master` select, which D1 permits. */
+async function ownerTableExists(db: Kysely<OwnerDatabase>): Promise<boolean> {
+  const { rows } = await sql<{
+    name: string;
+  }>`select name from sqlite_master where type = 'table' and name = ${MIGRATION_OWNER_TABLE}`.execute(db);
+  return rows.length > 0;
+}
+
+/** The recorded owner, validated through the codec, or `undefined` when nothing has claimed it. */
+async function currentOwner(db: Kysely<OwnerDatabase>): Promise<MigrationOwner | undefined> {
+  if (!(await ownerTableExists(db))) return undefined;
+  const row = await db
+    .selectFrom("pithy_migrations_owner")
+    .select(["project", "stampedAt"])
+    .where("id", "=", OWNER_ROW_ID)
+    .executeTakeFirst();
+  return row ? MigrationOwner.parse(row) : undefined;
+}
+
+/** The refusal: both project names in the problem line, both remedies in the action line. */
+function foreignDatabase(owner: string, project: string, binding: string | undefined): ConflictError {
+  return new ConflictError({
+    message: `${binding ?? "This database"} belongs to project "${owner}", not "${project}".`,
+    action: `Bind ${project} to its own database, or set the project name back to ${owner}. Run pithy migrate again.`,
+    detail: `Recorded owner "${owner}" in ${MIGRATION_OWNER_TABLE}.`,
+  });
+}
+
+/**
+ * The project recorded as this database's owner, or `undefined` when none is — read-only, creating
+ * nothing. `pithy doctor` and any other reporter reads the stamp through this; only
+ * {@link claimMigrationOwnership} writes it.
+ */
+export async function readMigrationOwner(database: D1Database): Promise<MigrationOwner | undefined> {
+  return currentOwner(migrationKysely<OwnerDatabase>(database));
+}
+
+/**
+ * Claim a database for a project, or refuse it to a foreign one. Idempotent and safe to re-run: an
+ * unstamped database is adopted (nothing has shipped, so a first run has no ambiguity to preserve),
+ * the owning project re-claims as a no-op, and any other project throws a `core/conflict` naming both
+ * projects. The insert is `on conflict do nothing` against a fixed primary key and is followed by a
+ * re-read, so two runs racing the very first claim settle on one owner rather than two rows.
+ */
+export async function claimMigrationOwnership(
+  database: D1Database,
+  options: ClaimOwnershipOptions,
+): Promise<ProjectOwnership> {
+  const project = options.project.trim();
+  if (!project) {
+    throw new ValidationError({
+      message: "A migration run needs a project name.",
+      action: "Set `name` in pithy.config.ts. It is what stamps the database as this project's.",
+    });
+  }
+
+  const db = migrationKysely<OwnerDatabase>(database);
+  const existing = await currentOwner(db);
+  if (existing) {
+    if (existing.project !== project) throw foreignDatabase(existing.project, project, options.binding);
+    return { project, outcome: "confirmed", stampedAt: existing.stampedAt };
+  }
+
+  await db.schema
+    .createTable(MIGRATION_OWNER_TABLE)
+    .ifNotExists()
+    .addColumn("id", "integer", (column) => column.primaryKey())
+    .addColumn("project", "text", (column) => column.notNull())
+    .addColumn("stampedAt", "integer", (column) => column.notNull())
+    .execute();
+
+  const record = MigrationOwner.encode({ project, stampedAt: new Date() });
+  await db
+    .insertInto("pithy_migrations_owner")
+    .values({ id: OWNER_ROW_ID, ...record })
+    .onConflict((conflict) => conflict.doNothing())
+    .execute();
+
+  // Re-read rather than trust the insert: a concurrent first run may have won the row.
+  const settled = await currentOwner(db);
+  if (!settled) {
+    throw new ConflictError({
+      message: `${options.binding ?? "This database"} could not be stamped as "${project}".`,
+      action: "Check the database is writable. Run pithy migrate again.",
+      detail: `No row in ${MIGRATION_OWNER_TABLE} after the claim insert.`,
+    });
+  }
+  if (settled.project !== project) throw foreignDatabase(settled.project, project, options.binding);
+  return { project, outcome: "adopted", stampedAt: settled.stampedAt };
+}

package/src/migrations/registry.ts

@@ -0,0 +1,121 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Migration, MigrationProvider } from "kysely/migration";
+import { InternalError } from "../error/pithyError";
+
+/** Width of the zero-padded `order` prefix in a composed key — the stable anchor. */
+const ORDER_DIGITS = 4;
+
+/** Maximum per-capability `order`, derived from the prefix width so the two never drift. */
+export const MAX_MIGRATION_ORDER = 10 ** ORDER_DIGITS - 1;
+
+/** Capability namespace: lowercase, starts with a letter, no separators (keeps keys injective). */
+export const NAMESPACE_PATTERN = /^[a-z][a-z0-9]*$/;
+
+/** Local migration key: a zero-padded sequence + lowercase snake, e.g. "0001_init". */
+const LOCAL_KEY_PATTERN = /^\d{4}_[a-z0-9_]+$/;
+
+export interface NamespacedMigrations {
+  /**
+   * Target database name — the same name used in a capability's `databases:` map (e.g. "app",
+   * "analytics"). D1 is multi-database; each database migrates independently, so every set names
+   * the database it belongs to. A capability with tables in two databases contributes one set per.
+   */
+  database: string;
+  /** Capability namespace, e.g. "core", "auth", "app". Must match `^[a-z][a-z0-9]*$`. */
+  namespace: string;
+  /** Sort order within its database (core low, app high). Unique per database; 0..MAX_MIGRATION_ORDER. */
+  order: number;
+  /** Stable, per-namespace keys, each `^\d{4}_[a-z0-9_]+$` (e.g. "0001_init"). */
+  migrations: Record<string, Migration>;
+}
+
+// These guard build-time registry invariants — a capability author wired its migrations wrong.
+// They surface at startup/build, not per request, so the offending value rides in the message.
+function assertValidNamespace(namespace: string): void {
+  if (!NAMESPACE_PATTERN.test(namespace)) {
+    throw new InternalError({ message: `migration namespace "${namespace}" must match ${NAMESPACE_PATTERN}` });
+  }
+}
+
+function assertValidOrder(order: number, namespace: string): void {
+  if (!Number.isInteger(order) || order < 0 || order > MAX_MIGRATION_ORDER) {
+    throw new InternalError({
+      message: `migration order ${order} (namespace "${namespace}") must be an integer in 0..${MAX_MIGRATION_ORDER}`,
+    });
+  }
+}
+
+function assertValidLocalKey(localKey: string, namespace: string): void {
+  if (!LOCAL_KEY_PATTERN.test(localKey)) {
+    throw new InternalError({
+      message: `migration key "${localKey}" (namespace "${namespace}") must match ${LOCAL_KEY_PATTERN}`,
+    });
+  }
+}
+
+/** Merge one database's sets into a provider, enforcing the per-database invariants. */
+function composeDatabase(database: string, sets: NamespacedMigrations[]): MigrationProvider {
+  const seenOrders = new Set<number>();
+  const seenNamespaces = new Set<string>();
+
+  for (const set of sets) {
+    assertValidNamespace(set.namespace);
+    assertValidOrder(set.order, set.namespace);
+    for (const localKey of Object.keys(set.migrations)) assertValidLocalKey(localKey, set.namespace);
+    if (seenOrders.has(set.order)) {
+      throw new InternalError({
+        message: `duplicate migration order ${set.order} in database "${database}" (namespace "${set.namespace}")`,
+      });
+    }
+    if (seenNamespaces.has(set.namespace)) {
+      throw new InternalError({ message: `duplicate namespace "${set.namespace}" in database "${database}"` });
+    }
+    seenOrders.add(set.order);
+    seenNamespaces.add(set.namespace);
+  }
+
+  const composed: Record<string, Migration> = {};
+  for (const set of [...sets].sort((a, b) => a.order - b.order)) {
+    const prefix = String(set.order).padStart(ORDER_DIGITS, "0");
+    for (const localKey of Object.keys(set.migrations).sort()) {
+      const migration = set.migrations[localKey];
+      if (migration) composed[`${prefix}_${set.namespace}_${localKey}`] = migration;
+    }
+  }
+
+  return {
+    getMigrations: async (): Promise<Record<string, Migration>> => composed,
+  };
+}
+
+/**
+ * Merge namespaced migration sets into one ordered `MigrationProvider` **per database** — matching
+ * multi-database D1, where each `c.var.db.<database>` is its own binding and schema. The result is
+ * keyed by database name (the future `pithy migrate` maps each to its binding and runs its provider);
+ * an empty input yields `{}`.
+ *
+ * Within each database the keys are `NNNN_<namespace>_<localKey>` (NNNN = zero-padded `order`).
+ * Kysely orders migrations by name (`localeCompare`); the enforced namespace/key formats keep that
+ * sort equal to a plain lexicographic one and dependency-correct (core before app), and make the key
+ * scheme injective. Keys never change across releases — new migrations append within a namespace — so
+ * Kysely's recorded names stay valid and an upgrade ships migrations without renumbering.
+ *
+ * `order` and `namespace` uniqueness scope **per database**: the same value may recur across
+ * different databases; a duplicate within one database throws.
+ */
+export function createMigrationRegistry(sets: NamespacedMigrations[]): Record<string, MigrationProvider> {
+  const byDatabase = new Map<string, NamespacedMigrations[]>();
+  for (const set of sets) {
+    const group = byDatabase.get(set.database);
+    if (group) group.push(set);
+    else byDatabase.set(set.database, [set]);
+  }
+
+  const registry: Record<string, MigrationProvider> = {};
+  for (const [database, dbSets] of byDatabase) {
+    registry[database] = composeDatabase(database, dbSets);
+  }
+  return registry;
+}

package/src/migrations/runner.ts

@@ -0,0 +1,295 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { type Kysely, sql } from "kysely";
+import { type MigrationProvider, type MigrationResult, Migrator, NO_MIGRATIONS } from "kysely/migration";
+import { causeMessage } from "../error/cause";
+import { InternalError } from "../error/pithyError";
+import { batchedProvider } from "./batch";
+import { MIGRATION_LOCK_TABLE, MIGRATION_TABLE, migrationKysely } from "./bookkeeping";
+
+/**
+ * The per-database migration runner. The registry yields one `MigrationProvider` per database
+ * (`createMigrationRegistry`); the caller pairs each provider with that database's D1 binding and
+ * runs them independently — there is no global run across databases. `pithy migrate` is a thin
+ * wrapper over these two functions.
+ *
+ * Both take the raw binding, not a Kysely instance: the dialect, the `CamelCasePlugin`, and the
+ * renamed bookkeeping tables all live in `./bookkeeping`, and the runner builds its Kysely from
+ * there (`owner.ts` builds the same one to stamp the owning project). Migration `up`/`down`
+ * functions receive that instance — write camelCase, store snake_case, like every Pithy database.
+ *
+ * One runner at a time per database. Kysely's SQLite adapter reports no transactional DDL and its
+ * migration lock is a no-op, so concurrent runs can interleave. That fits the deployment model —
+ * migrations run from `pithy migrate` (CLI/CI), not inside request handlers — but it is an
+ * assumption, not a guard. On failure the thrown `InternalError` names the failed key, the database
+ * it was running against, and **what the runtime actually said**, all in `message`; `detail` keeps
+ * the throw-site half — the database name behind the binding, and the migrations applied before the
+ * failure, since those stay applied.
+ *
+ * **Each migration body is one `d1.batch()` — see `./batch`, which is where the failure semantics
+ * are argued.** The short version: a migration is now all-or-nothing where it used to be able to
+ * half-apply, and nothing across a migration boundary changed, because the ledger names migrations
+ * and a partial chain has to stay representable in it.
+ */
+
+/**
+ * **`allowUnorderedMigrations` is on, and it is not a loosening.** A composed key leads with its
+ * capability's `migrationOrder` (`0250_audit_0001_init`), so the sorted registry *is* the order Pithy
+ * promises — and it is the same order whatever sequence an adopter typed `pithy add` in. Kysely's
+ * default mode additionally requires the applied ledger to be a prefix of that order, which nothing in
+ * the model can guarantee: add `email` (200), then `auth` (300), then `audit` (250), and audit's
+ * migration sorts between two applied ones. Every later run then failed, naming keys and index
+ * positions the adopter never chose, and the only recovery was wiping the database.
+ *
+ * Unordered mode still applies pending migrations in `migrationOrder`. It drops one thing: the demand
+ * that the past agree with it. That is sound here because no capability's tables reference another's
+ * — order across capabilities is arbitrary by design, and order *within* one is preserved, since a
+ * 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 {
+  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),
+    migrationTableName: MIGRATION_TABLE,
+    migrationLockTableName: MIGRATION_LOCK_TABLE,
+    allowUnorderedMigrations: true,
+  });
+}
+
+/**
+ * Which database a run is reporting on — what a failure names.
+ *
+ * Optional at every entry point, and defaulted the same way `claimMigrationOwnership`'s refusal defaults
+ * its own binding — a runner handed nothing still has a sentence. The CLI always passes one, from the
+ * group it is running, because "which database" is the first question a failed migration raises and the
+ * runner is the only place that can answer it in the same breath as the error (#282).
+ */
+export interface MigrationTarget {
+  /** The D1 binding, as `wrangler.jsonc` declares it — the name an adopter recognizes. */
+  binding: string;
+  /** The database name: a capability's `databases` key. Throw-site context, not the adopter's handle. */
+  database: string;
+}
+
+/** 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();
+  return settle("run", error, results, target);
+}
+
+/** One database's ledger beside the declaration it is supposed to match — see {@link readMigrationLedger}. */
+export interface MigrationLedger {
+  /** Declared and not yet applied, in the order they would run. */
+  pending: string[];
+  /**
+   * Applied and no longer declared, sorted. Kysely refuses the whole chain on any one of these, so
+   * this is not drift a later run works around — it is the reason nothing can run at all.
+   */
+  undeclared: string[];
+}
+
+/**
+ * What this database has applied, against what this project declares — **both directions, one read**.
+ *
+ * `pithy doctor` used to ask only how many declared migrations had not run, because that is the
+ * question Kysely's own `getMigrations` answers: it maps over the *provider's* migrations and looks
+ * each one up in the ledger, so a row the provider does not carry is not in the result at all. A
+ * subtraction cannot see an extra. A database holding a migration the project has since deleted
+ * therefore reported `none pending ✓` while the migrator refused to run against it at all — Kysely
+ * reads an unrecognized applied migration as a corrupted chain and applies nothing (#282).
+ *
+ * Asking both halves in one function is the point. Two functions — one counting pending, one hunting
+ * undeclared — is how the first half shipped alone, and the caller reaching for the count is exactly
+ * the caller who needs the other answer.
+ *
+ * Read-only, applying nothing: the seam behind `pithy doctor`'s migrations line, `pithy deploy`'s
+ * warn-only "schema is behind" check, and the refusal `pithy migrate` raises before it writes.
+ */
+export async function readMigrationLedger(database: D1Database, provider: MigrationProvider): Promise<MigrationLedger> {
+  const declared = Object.keys(await provider.getMigrations()).sort();
+  const applied = await appliedMigrationNames(migrationKysely(database));
+  return {
+    pending: declared.filter((name) => !applied.has(name)),
+    undeclared: [...applied].filter((name) => !declared.includes(name)).sort(),
+  };
+}
+
+/** Step the latest applied migration back — one step, the `pithy migrate --rollback` seam. */
+export async function rollbackMigration(
+  database: D1Database,
+  provider: MigrationProvider,
+  target?: MigrationTarget,
+): Promise<MigrationResult[]> {
+  const { error, results } = await migrator(database, provider).migrateDown();
+  return settle("rollback", error, results, target);
+}
+
+/**
+ * Fully reset one database's schema: every applied migration's `down` runs, in one pass, in reverse
+ * chronological order — Kysely's `NO_MIGRATIONS` target, not just the latest — then every migration's
+ * `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.
+ */
+export async function resetMigrations(
+  database: D1Database,
+  provider: MigrationProvider,
+  target?: MigrationTarget,
+): Promise<MigrationResult[]> {
+  const runner = migrator(database, provider);
+  const down = await runner.migrateTo(NO_MIGRATIONS);
+  const downResults = settle("resetDown", down.error, down.results, target);
+  const up = await runner.migrateToLatest();
+  const upResults = settle("resetUp", up.error, up.results, target);
+  return [...downResults, ...upResults];
+}
+
+/**
+ * The applied migration names recorded in the ledger — empty when the ledger table doesn't exist yet.
+ * Existence is checked against `sqlite_master` (a plain select D1 permits) rather than by catching the
+ * read's error, so a genuine read failure surfaces instead of being silently treated as "none applied".
+ */
+async function appliedMigrationNames(db: Kysely<unknown>): Promise<Set<string>> {
+  const present = await sql<{
+    name: string;
+  }>`select name from sqlite_master where type = 'table' and name = ${MIGRATION_TABLE}`.execute(db);
+  if (present.rows.length === 0) return new Set();
+  const { rows } = await sql<{ name: string }>`select name from ${sql.table(MIGRATION_TABLE)}`.execute(db);
+  return new Set(rows.map((row) => row.name));
+}
+
+/**
+ * Surgically drop **one capability's** migrations: run each of the provider'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.
+ */
+export async function dropMigrations(
+  database: D1Database,
+  provider: MigrationProvider,
+  target?: MigrationTarget,
+): 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();
+  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()) {
+    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`.
+    const down = migrations[name]?.down;
+    if (!down) continue;
+    try {
+      await down(db);
+      await sql`delete from ${sql.table(MIGRATION_TABLE)} where name = ${name}`.execute(db);
+      results.push({ migrationName: name, direction: "Down", status: "Success" });
+    } catch (error) {
+      const dropped = results.map((result) => `"${result.migrationName}"`);
+      throw new InternalError(
+        {
+          message: `Couldn't drop "${name}"${on(target)}. ${reasonOf(error)}`,
+          detail: `${where(target)}${dropped.length ? ` Dropped before the failure: ${dropped.join(", ")}.` : ""}`,
+          action: "Fix the migration's down, or drop its table by hand. Run pithy remove --drop again.",
+        },
+        { cause: error },
+      );
+    }
+  }
+  return results;
+}
+
+/** Brand-voice problem and action lines per direction (docs/CLI.md §3.3). */
+const VOICE = {
+  run: {
+    failed: (key: string) => `Couldn't apply "${key}"`,
+    fallback: "The migration run failed",
+    action: "Fix the migration. Run pithy migrate again.",
+  },
+  rollback: {
+    failed: (key: string) => `Couldn't roll back "${key}"`,
+    fallback: "The rollback failed",
+    action: "Fix the migration. Run pithy migrate --rollback again.",
+  },
+  resetDown: {
+    failed: (key: string) => `Couldn't roll back "${key}" during reset`,
+    fallback: "The schema reset failed while rolling back",
+    action: "Fix the migration. Run pithy seed --redo again.",
+  },
+  resetUp: {
+    failed: (key: string) => `Couldn't reapply "${key}" during reset`,
+    fallback: "The schema reset failed while reapplying",
+    action: "Fix the migration. Run pithy seed --redo again.",
+  },
+} as const;
+
+/** ` on DB`, or nothing at all — every problem line here ends with this and then a period. */
+function on(target: MigrationTarget | undefined): string {
+  return target ? ` on ${target.binding}` : "";
+}
+
+/** The throw-site half of the same fact: the database name behind the binding, for `detail`. */
+function where(target: MigrationTarget | undefined): string {
+  return target ? `Database "${target.database}" on binding ${target.binding}.` : "";
+}
+
+/**
+ * The underlying failure, as a sentence — **in `message`, where it is actually rendered**.
+ *
+ * It used to go to `detail` alone, and `detail` is the field the terminal renderer never prints and the
+ * HTTP codec strips. So `pithy migrate` said *Migration run failed. Fix the migration.* and nothing
+ * else, over a Kysely error that had already named the migration and the reason (#282). A migration
+ * failure is D1 answering our own SQL — `no such column: tenant`, `corrupted migrations: previously
+ * executed migration X is missing` — and that sentence *is* the actionable content. Withholding it is
+ * not a security boundary, it is the bug.
+ *
+ * Deliberately not through `safeReason`: that filter drops anything over 160 characters, and a silent
+ * drop is what this whole path is being fixed for. Color codes come off, because they are formatting
+ * a runtime added.
+ */
+function reasonOf(error: unknown): string {
+  const reason = (causeMessage(error) ?? String(error)).trim();
+  return reason.endsWith(".") ? reason : `${reason}.`;
+}
+
+function settle(
+  verb: keyof typeof VOICE,
+  error: unknown,
+  results: MigrationResult[] | undefined,
+  target?: MigrationTarget,
+): MigrationResult[] {
+  if (error !== undefined) {
+    const voice = VOICE[verb];
+    const failed = results?.find((result) => result.status === "Error");
+    const applied = results?.filter((result) => result.status === "Success").map((result) => result.migrationName);
+    const problem = failed ? voice.failed(failed.migrationName) : voice.fallback;
+    // The chain is applied one migration at a time, so name what stuck before the failure. The
+    // failed migration itself is not among them: its body was one batch, and the batch rolled back.
+    const stuck = applied?.length
+      ? `Applied before the failure: ${applied.map((name) => `"${name}"`).join(", ")}.`
+      : "";
+    throw new InternalError(
+      {
+        message: `${problem}${on(target)}. ${reasonOf(error)}`,
+        detail: [where(target), stuck].filter(Boolean).join(" "),
+        action: voice.action,
+      },
+      { cause: error },
+    );
+  }
+  return results ?? [];
+}