@pithy-sh/core 0.9.0 → 0.11.0

package/dist/migrations/groups.js

@@ -0,0 +1,191 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { SQLiteDate } from "../data/codecs.js";
+import { chunkByBoundParameters, chunkRowsByBoundParameters } from "../data/boundParameters.js";
+import { MIGRATION_GROUP_TABLE, appliedMigrationChain, migrationKysely } from "./bookkeeping.js";
+import { z } from "zod";
+import { sql } from "kysely";
+//#region src/migrations/groups.ts
+/**
+* **Which run applied each migration — the group a rollback names (#694).**
+*
+* `pithy migrate --rollback` used to step back one migration in every database the environment binds, and
+* nothing recorded what a single run had applied. So reversing a deploy that moved three migrations was
+* three invocations and the count came from outside the tool — a human's memory, or a CI log read under
+* pressure. Every run belongs to a group now: the caller's own `--group <value>`, or a generated ISO-8601
+* timestamp, recorded here against every migration the run applies, in every database it touches.
+*
+* **It cannot live in the ledger.** `pithy_migrations` is Kysely's own table, renamed off its default
+* (`./bookkeeping`); Kysely creates it and its insert sets `name` and `timestamp` only. So the group sits
+* in a table *beside* it, written by the runner from the `MigrationResult[]` Kysely hands back — the same
+* placement, and the same reasoning, as `pithy_migrations_owner`: it is not a migration, so no capability
+* ships it, `--rollback` cannot step it back, and `pithy seed --redo`'s full reset cannot wipe it. What a
+* reversal removes is the reversed migrations' own rows, which is bookkeeping catching up with the ledger.
+*
+* **The rows say which run; the ledger says which order.** Every applied migration is recorded here as it
+* applies and forgotten as it is reversed, so these rows are the membership. Where a group *sits* is a
+* question about the ledger, though, because the ledger is what Kysely steps down from — so {@link
+* readGroupPosition} reads both (`appliedMigrationChain`) and compares the group against the chain's tail.
+* Reading the group table alone would answer from the order this table happened to be written in, and the
+* two differ in exactly the cases that matter: a migration applied with no group row at all.
+*
+* **What it cannot see, it names.** A migration applied before this table existed carries no row, and so
+* does one a `seed --redo` reset reapplied or one whose group write failed. Such a migration over a group
+* buries it — reversing the group would reverse a migration nobody recorded — and the position says so by
+* name rather than calling the group reversible. Reading is cheap and additive: one group row per applied
+* migration, and the table is created on the first run that applies anything.
+*/
+/** One applied migration and the run that applied it. The three columns are the whole table. */
+const MigrationGroupRecord = z.object({
+	groupKey: z.string().describe("The group this migration was applied under — the caller's `--group` value, or the generated ISO-8601 timestamp of the run. Not `group`: that is SQL's own word, and an operator reading this table by hand should not have to quote a column."),
+	migration: z.string().describe("The composed migration name, exactly as the ledger records it."),
+	appliedAt: SQLiteDate.describe("When this migration was applied — the moment the run recorded it.")
+}).describe("One applied migration's membership of a migration group, recorded beside the ledger.");
+/**
+* The group a run with no `--group` belongs to: an **ISO-8601 timestamp**, `2026-10-03T19:52:47.611Z`.
+*
+* A timestamp rather than a date, because one run is one group. Date-only would silently merge two
+* unrelated runs on a busy day into one group, and reversing it would then undo more than the caller did.
+* The precision costs nothing, it sorts lexicographically into chronological order, and it tells an
+* operator *when* without their having named anything.
+*/
+function generatedMigrationGroup(now = /* @__PURE__ */ new Date()) {
+	return now.toISOString();
+}
+/** Whether the group table has been created yet — a plain `sqlite_master` select, which D1 permits. */
+async function groupTableExists(db) {
+	const { rows } = await sql`select name from sqlite_master where type = 'table' and name = ${MIGRATION_GROUP_TABLE}`.execute(db);
+	return rows.length > 0;
+}
+/** Every row, in the order it was written — which is the order the migrations applied. */
+async function groupRows(db) {
+	if (!await groupTableExists(db)) return [];
+	return (await db.selectFrom("pithy_migrations_groups").select([
+		"groupKey",
+		"migration",
+		"appliedAt"
+	]).orderBy("id").execute()).map((row) => MigrationGroupRecord.parse(row));
+}
+/**
+* How many parameters one group row binds — derived from the schema, so a fourth column re-derives the
+* chunk size instead of silently taking the insert back over D1's cap.
+*/
+const GROUP_ROW_COLUMNS = Object.keys(MigrationGroupRecord.shape).length;
+/**
+* Record a group against the migrations a run just applied, creating the table on demand. Idempotent in
+* the only sense that matters: a migration applies once, so a name arrives here once — and a second call
+* under the same group **extends** it, which is the retry case a release whose migrate half-failed needs.
+*/
+async function recordMigrationGroup(database, options) {
+	if (options.migrations.length === 0) return;
+	const db = migrationKysely(database);
+	await db.schema.createTable(MIGRATION_GROUP_TABLE).ifNotExists().addColumn("id", "integer", (column) => column.primaryKey().autoIncrement()).addColumn("groupKey", "text", (column) => column.notNull()).addColumn("migration", "text", (column) => column.notNull()).addColumn("appliedAt", "integer", (column) => column.notNull()).execute();
+	const appliedAt = options.at ?? /* @__PURE__ */ new Date();
+	const rows = options.migrations.map((migration) => MigrationGroupRecord.encode({
+		groupKey: options.group,
+		migration,
+		appliedAt
+	}));
+	for (const chunk of chunkRowsByBoundParameters(rows, GROUP_ROW_COLUMNS)) await db.insertInto("pithy_migrations_groups").values(chunk).execute();
+}
+/**
+* Every group this database records, oldest first by when each last applied something — and so the last
+* entry is the newest group, which is what a rollback with no `--group` names. Empty for a database
+* nothing has grouped, and reading creates nothing.
+*/
+async function readMigrationGroups(database) {
+	const rows = await groupRows(migrationKysely(database));
+	const byGroup = /* @__PURE__ */ new Map();
+	for (const [index, row] of rows.entries()) {
+		const existing = byGroup.get(row.groupKey);
+		if (existing) {
+			existing.migrations.push(row.migration);
+			existing.appliedAt = row.appliedAt > existing.appliedAt ? row.appliedAt : existing.appliedAt;
+			existing.order = index;
+			continue;
+		}
+		byGroup.set(row.groupKey, {
+			group: row.groupKey,
+			appliedAt: row.appliedAt,
+			migrations: [row.migration],
+			order: index
+		});
+	}
+	return [...byGroup.values()].sort((left, right) => left.order - right.order).map(({ group, appliedAt, migrations }) => ({
+		group,
+		appliedAt,
+		migrations
+	}));
+}
+/**
+* Where `group` sits in this database's chain — see {@link GroupPosition}.
+*
+* The test is *is this group the tail of the **ledger***, not *is it the newest by timestamp*: a group
+* extended after another run has the later timestamp and still has that run's migration inside it, so
+* reversing it would reverse the other group's work. Hence the two halves of one rule — nothing applied
+* over the group's newest migration, and nothing applied inside it between two of its own.
+*
+* **Against the ledger, because the ledger is what comes down.** `migrateDown()` steps the ledger's tip,
+* so a group whose rows are the tail of the *group table* is still buried when an ungrouped migration sits
+* over it in the ledger — and that state is reachable from the ordinary dev loop, where `seed --redo`'s
+* reset reapplies a pending migration under no group at all. Asked of the group table alone, this returned
+* `top`, the `down` reversed a migration nobody asked about, and the refusal arrived after the damage.
+*/
+async function readGroupPosition(database, group) {
+	const db = migrationKysely(database);
+	const groupOf = new Map((await groupRows(db)).map((row) => [row.migration, row.groupKey]));
+	const chain = await appliedMigrationChain(db);
+	const held = (name) => groupOf.get(name) === group;
+	const first = chain.findIndex(held);
+	if (first === -1) return { state: "absent" };
+	const last = chain.length - 1 - [...chain].reverse().findIndex(held);
+	const span = chain.slice(first, last + 1);
+	const over = chain.slice(last + 1);
+	const inside = span.filter((name) => !held(name));
+	if (over.length === 0 && inside.length === 0) return {
+		state: "top",
+		migrations: span.filter(held).reverse()
+	};
+	const blocking = [...[...over].reverse(), ...[...inside].reverse()];
+	const above = [...new Set(blocking.map((name) => groupOf.get(name)).filter(isGroupKey))];
+	const ungrouped = blocking.filter((name) => !groupOf.has(name));
+	const top = contiguousTipGroup(chain, groupOf);
+	return {
+		state: "buried",
+		above,
+		ungrouped,
+		...top === void 0 ? {} : { top }
+	};
+}
+/** A `groupOf` lookup that found a group, for narrowing the `above` list. */
+function isGroupKey(key) {
+	return key !== void 0;
+}
+/**
+* The group whose own migrations are the contiguous tip of `chain`, if any.
+*
+* What it is for is the refusals: *reverse the group on top first* is only advice if such a group exists,
+* and after a group was extended over another one none does — each is inside the other, so naming either
+* prints a command that refuses in its turn and the operator is sent in a circle (#694). The candidate can
+* only be the group holding the tip migration, so there is one to test, not a search.
+*/
+function contiguousTipGroup(chain, groupOf) {
+	const tip = chain.at(-1);
+	const candidate = tip === void 0 ? void 0 : groupOf.get(tip);
+	if (candidate === void 0) return void 0;
+	const held = chain.filter((name) => groupOf.get(name) === candidate).length;
+	return chain.slice(chain.length - held).every((name) => groupOf.get(name) === candidate) ? candidate : void 0;
+}
+/**
+* Forget the group rows of migrations that are no longer applied — what a reversal writes once the `down`
+* has run. By migration name alone, because the ledger's name is unique: one applied migration, one row.
+* A database with no group table has nothing to forget.
+*/
+async function forgetMigrationGroups(database, migrations) {
+	if (migrations.length === 0) return;
+	const db = migrationKysely(database);
+	if (!await groupTableExists(db)) return;
+	for (const chunk of chunkByBoundParameters(migrations, 0)) await db.deleteFrom("pithy_migrations_groups").where("migration", "in", chunk).execute();
+}
+//#endregion
+export { MigrationGroupRecord, forgetMigrationGroups, generatedMigrationGroup, readGroupPosition, readMigrationGroups, recordMigrationGroup };

package/dist/migrations/migrateStep.d.ts

@@ -0,0 +1,13 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { type AmbientEnv } from "../env/ambient";
+/**
+ * **The step that migrates the environment a Worker runs in**, as a sentence ends with it: `then ${step}.`
+ *
+ * `pithy migrate` defaults to `dev`, so a line that names it bare sends a staging Worker's operator to migrate
+ * their laptop (#711). A Worker knows its environment when the composition stamped one (`ENVIRONMENT`), and then
+ * the command names it; when it does not, the line says which flag to name rather than naming a command that
+ * would act on the wrong database.
+ */
+export declare function migrateStep(env: AmbientEnv): string;
+//# sourceMappingURL=migrateStep.d.ts.map

package/dist/migrations/migrateStep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrateStep.d.ts","sourceRoot":"","sources":["../../src/migrations/migrateStep.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,UAAU,EAA0B,MAAM,gBAAgB,CAAC;AAEzE;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAInD"}

package/dist/migrations/migrateStep.js

@@ -0,0 +1,20 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { commandName, pithyCommand } from "../cli/command.js";
+import { compositionEnvironment } from "../env/ambient.js";
+//#region src/migrations/migrateStep.ts
+/**
+* **The step that migrates the environment a Worker runs in**, as a sentence ends with it: `then ${step}.`
+*
+* `pithy migrate` defaults to `dev`, so a line that names it bare sends a staging Worker's operator to migrate
+* their laptop (#711). A Worker knows its environment when the composition stamped one (`ENVIRONMENT`), and then
+* the command names it; when it does not, the line says which flag to name rather than naming a command that
+* would act on the wrong database.
+*/
+function migrateStep(env) {
+	const environment = compositionEnvironment(env);
+	if (environment === void 0) return `migrate this environment with ${commandName("migrate")}, naming it with --env`;
+	return `run ${pithyCommand("migrate", { flags: { "--env": environment } })}`;
+}
+//#endregion
+export { migrateStep };

package/dist/migrations/owner.d.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 import type { D1Database } from "@cloudflare/workers-types";
 import { z } from "zod";
+import { ConflictError } from "../error/pithyError";
 /** The recorded owner of a database: who stamped it, and when. */
 export declare const MigrationOwner: z.ZodObject<{
     project: z.ZodString;
@@ -26,6 +27,12 @@ export interface ClaimOwnershipOptions {
     /** The binding this database is reached by (`DB`), so a refusal names it. Optional. */
     binding?: string;
 }
+/**
+ * The refusal for a database another project owns: both project names in the problem line, both remedies in the
+ * action line. Exported so a reader that only checks the claim — `pithy migrate --dry-run`, which stamps nothing —
+ * refuses in the words the claim refuses with, rather than a copy of them (#697).
+ */
+export declare function foreignOwnerRefusal(owner: string, project: string, binding: string | undefined): ConflictError;
 /**
  * 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

package/dist/migrations/owner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"owner.d.ts","sourceRoot":"","sources":["../../src/migrations/owner.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAG5D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA2BxB,kEAAkE;AAClE,eAAO,MAAM,cAAc;;;iBAOuF,CAAC;AACnH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAa7D,mFAAmF;AACnF,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,WAAW,CAAC;AAEvD,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,uFAAuF;IACvF,OAAO,EAAE,gBAAgB,CAAC;IAC1B,4EAA4E;IAC5E,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,6EAA6E;AAC7E,MAAM,WAAW,qBAAqB;IACpC,oGAAoG;IACpG,OAAO,EAAE,MAAM,CAAC;IAChB,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA8BD;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAElG;AAED;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,UAAU,EACpB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,gBAAgB,CAAC,CA0C3B"}
+{"version":3,"file":"owner.d.ts","sourceRoot":"","sources":["../../src/migrations/owner.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAG5D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,aAAa,EAAmB,MAAM,qBAAqB,CAAC;AAyBrE,kEAAkE;AAClE,eAAO,MAAM,cAAc;;;iBAOuF,CAAC;AACnH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAa7D,mFAAmF;AACnF,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,WAAW,CAAC;AAEvD,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,uFAAuF;IACvF,OAAO,EAAE,gBAAgB,CAAC;IAC1B,4EAA4E;IAC5E,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,6EAA6E;AAC7E,MAAM,WAAW,qBAAqB;IACpC,oGAAoG;IACpG,OAAO,EAAE,MAAM,CAAC;IAChB,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAqBD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,CAM9G;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAElG;AAED;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,UAAU,EACpB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,gBAAgB,CAAC,CA0C3B"}

package/dist/migrations/owner.js

@@ -42,11 +42,15 @@ async function currentOwner(db) {
 	const row = await db.selectFrom("pithy_migrations_owner").select(["project", "stampedAt"]).where("id", "=", OWNER_ROW_ID).executeTakeFirst();
 	return row ? MigrationOwner.parse(row) : void 0;
 }
-/** The refusal: both project names in the problem line, both remedies in the action line. */
-function foreignDatabase(owner, project, binding) {
+/**
+* The refusal for a database another project owns: both project names in the problem line, both remedies in the
+* action line. Exported so a reader that only checks the claim — `pithy migrate --dry-run`, which stamps nothing —
+* refuses in the words the claim refuses with, rather than a copy of them (#697).
+*/
+function foreignOwnerRefusal(owner, project, binding) {
 	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.`,
+		action: `Bind ${project} to its own database, or set the project name back to ${owner}. Then run this again.`,
 		detail: `Recorded owner "${owner}" in ${MIGRATION_OWNER_TABLE}.`
 	});
 }
@@ -74,7 +78,7 @@ async function claimMigrationOwnership(database, options) {
 	const db = migrationKysely(database);
 	const existing = await currentOwner(db);
 	if (existing) {
-		if (existing.project !== project) throw foreignDatabase(existing.project, project, options.binding);
+		if (existing.project !== project) throw foreignOwnerRefusal(existing.project, project, options.binding);
 		return {
 			project,
 			outcome: "confirmed",
@@ -93,10 +97,10 @@ async function claimMigrationOwnership(database, options) {
 	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.",
+		action: "Check the database is writable, then run this again.",
 		detail: `No row in ${MIGRATION_OWNER_TABLE} after the claim insert.`
 	});
-	if (settled.project !== project) throw foreignDatabase(settled.project, project, options.binding);
+	if (settled.project !== project) throw foreignOwnerRefusal(settled.project, project, options.binding);
 	return {
 		project,
 		outcome: "adopted",
@@ -104,4 +108,4 @@ async function claimMigrationOwnership(database, options) {
 	};
 }
 //#endregion
-export { MigrationOwner, claimMigrationOwnership, readMigrationOwner };
+export { MigrationOwner, claimMigrationOwnership, foreignOwnerRefusal, readMigrationOwner };

package/dist/migrations/registry.d.ts

@@ -25,6 +25,32 @@ export interface NamespacedMigrations {
      */
     retained?: readonly string[];
 }
+/**
+ * The composed key for one of a set's migrations: `NNNN_<namespace>_<localKey>`. The one place the shape is
+ * written, so the registry and anything naming a declared migration's namespace build the same string.
+ */
+export declare function composedMigrationKey(set: Pick<NamespacedMigrations, "order" | "namespace">, localKey: string): string;
+/** A composed key taken back apart: the three parts {@link createMigrationRegistry} joined. */
+export interface ComposedMigrationKey {
+    /** The capability's `migrationOrder` — the zero-padded prefix, as a number. */
+    order: number;
+    /** The capability namespace — its `name`, which the manifest reports beside every capability. */
+    namespace: string;
+    /** The capability's own stable key, e.g. `0001_init`. */
+    localKey: string;
+}
+/**
+ * Take a composed key back apart — the inverse of the composition below.
+ *
+ * A declared migration's namespace is known from the set it came from. An **undeclared** one — applied in
+ * the database, carried by no provider this build composes — has nothing but its key, so this is the only
+ * way to say whose it was. **Null for a key no registry could have composed**, a migration written by hand
+ * or by another tool: guessing a namespace for it would be inventing one.
+ *
+ * The patterns are the same constants the composition enforces, so the two cannot disagree about what a
+ * key looks like.
+ */
+export declare function decomposeMigrationKey(key: string): ComposedMigrationKey | null;
 /**
  * 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

package/dist/migrations/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/migrations/registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAOrE,4FAA4F;AAC5F,eAAO,MAAM,mBAAmB,QAAyB,CAAC;AAE1D,mGAAmG;AACnG,eAAO,MAAM,iBAAiB,QAAqB,CAAC;AAKpD,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,uFAAuF;IACvF,SAAS,EAAE,MAAM,CAAC;IAClB,wGAAwG;IACxG,KAAK,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B;AAgED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,oBAAoB,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAavG"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/migrations/registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAOrE,4FAA4F;AAC5F,eAAO,MAAM,mBAAmB,QAAyB,CAAC;AAE1D,mGAAmG;AACnG,eAAO,MAAM,iBAAiB,QAAqB,CAAC;AAKpD,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,uFAAuF;IACvF,SAAS,EAAE,MAAM,CAAC;IAClB,wGAAwG;IACxG,KAAK,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B;AA0BD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,oBAAoB,EAAE,OAAO,GAAG,WAAW,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAErH;AAED,+FAA+F;AAC/F,MAAM,WAAW,oBAAoB;IACnC,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAC;IACd,iGAAiG;IACjG,SAAS,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAUD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAM9E;AAuCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,oBAAoB,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAavG"}

package/dist/migrations/registry.js

@@ -20,6 +20,40 @@ function assertValidOrder(order, namespace) {
 function assertValidLocalKey(localKey, namespace) {
 	if (!LOCAL_KEY_PATTERN.test(localKey)) throw new InternalError({ message: `migration key "${localKey}" (namespace "${namespace}") must match ${LOCAL_KEY_PATTERN}` });
 }
+/**
+* The composed key for one of a set's migrations: `NNNN_<namespace>_<localKey>`. The one place the shape is
+* written, so the registry and anything naming a declared migration's namespace build the same string.
+*/
+function composedMigrationKey(set, localKey) {
+	return `${String(set.order).padStart(ORDER_DIGITS, "0")}_${set.namespace}_${localKey}`;
+}
+/**
+* The composed key shape, anchored at both ends: the order prefix, a namespace (which admits no separator,
+* so the first underscore after it is the boundary), then a local key, which may hold any number.
+*/
+const COMPOSED_KEY_PATTERN = new RegExp(`^(\\d{${ORDER_DIGITS}})_(${NAMESPACE_PATTERN.source.slice(1, -1)})_(${LOCAL_KEY_PATTERN.source.slice(1, -1)})$`);
+/**
+* Take a composed key back apart — the inverse of the composition below.
+*
+* A declared migration's namespace is known from the set it came from. An **undeclared** one — applied in
+* the database, carried by no provider this build composes — has nothing but its key, so this is the only
+* way to say whose it was. **Null for a key no registry could have composed**, a migration written by hand
+* or by another tool: guessing a namespace for it would be inventing one.
+*
+* The patterns are the same constants the composition enforces, so the two cannot disagree about what a
+* key looks like.
+*/
+function decomposeMigrationKey(key) {
+	const match = COMPOSED_KEY_PATTERN.exec(key);
+	if (!match) return null;
+	const [, order, namespace, localKey] = match;
+	if (order === void 0 || namespace === void 0 || localKey === void 0) return null;
+	return {
+		order: Number(order),
+		namespace,
+		localKey
+	};
+}
 /** Merge one database's sets into a provider, enforcing the per-database invariants. */
 function composeDatabase(database, sets) {
 	const seenOrders = /* @__PURE__ */ new Set();
@@ -34,12 +68,9 @@ function composeDatabase(database, sets) {
 		seenNamespaces.add(set.namespace);
 	}
 	const composed = {};
-	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;
-		}
+	for (const set of [...sets].sort((a, b) => a.order - b.order)) for (const localKey of Object.keys(set.migrations).sort()) {
+		const migration = set.migrations[localKey];
+		if (migration) composed[composedMigrationKey(set, localKey)] = migration;
 	}
 	for (const set of sets) declareRetained(set.migrations, set.retained ?? []);
 	return { getMigrations: async () => composed };
@@ -71,4 +102,4 @@ function createMigrationRegistry(sets) {
 	return registry;
 }
 //#endregion
-export { MAX_MIGRATION_ORDER, NAMESPACE_PATTERN, createMigrationRegistry };
+export { MAX_MIGRATION_ORDER, NAMESPACE_PATTERN, composedMigrationKey, createMigrationRegistry, decomposeMigrationKey };

package/dist/migrations/retained.js

@@ -9,8 +9,8 @@ import { CamelCasePlugin } from "kysely";
 *
 * 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.
+* the whole history of the secrets database, so one `pithy migrate --rollback` — which then stepped 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

package/dist/migrations/runner.d.ts

@@ -30,8 +30,30 @@ export interface RetainedConsent {
      */
     budget?: RetainedBudget;
 }
-/** Run every pending migration to latest. An empty provider resolves to `[]`. */
-export declare function runMigrations(database: D1Database, provider: MigrationProvider, target?: MigrationTarget): Promise<MigrationResult[]>;
+/**
+ * What a forward run records about itself (#694) — see `./groups`.
+ *
+ * Optional, and absent still records: a run with no group named is a group of its own, stamped with the
+ * moment it ran. There is always a group, so a rollback never has to fall back to counting migrations.
+ */
+export interface RunGroupOptions {
+    /**
+     * The group every migration this run applies is recorded under. Absent, a generated ISO-8601 timestamp
+     * is used — per run, by construction. A caller spanning several databases passes **one** value to all
+     * of them, so one run is one group however many databases it touches.
+     */
+    group?: string;
+}
+/**
+ * Run every pending migration to latest, recording the run's group against each one. An empty provider
+ * resolves to `[]` and records nothing.
+ *
+ * **The group is written from what Kysely hands back, and before the failure is raised.** A run that
+ * half-applies is retried with the key it already has, so the migrations that stuck have to be in the
+ * group — otherwise the retry's group would sit on top of an ungrouped migration, and reversing the
+ * retry would leave half a release applied with nothing recording it.
+ */
+export declare function runMigrations(database: D1Database, provider: MigrationProvider, target?: MigrationTarget, options?: RunGroupOptions): Promise<MigrationResult[]>;
 /** 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. */
@@ -61,11 +83,50 @@ export interface MigrationLedger {
  */
 export declare function readMigrationLedger(database: D1Database, provider: MigrationProvider): Promise<MigrationLedger>;
 /**
- * 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).
+ * Step this database's latest applied migration back — **one** step, in **one** database.
+ *
+ * It is no longer what `pithy migrate --rollback` runs: a rollback names a group and reverses that
+ * group's portion of each database ({@link reverseMigrationGroup}, #694). What this is, is the single
+ * step underneath — the primitive every capability's "its `down` is the inverse of its `up`" suite
+ * reverses one migration with, and the honest answer for a caller holding one migration rather than a
+ * release.
+ *
+ * It forgets the reversed migration's group row, so the group bookkeeping follows the ledger whichever
+ * way a migration came down. Refused while a retained table here holds rows the caller has not counted in
+ * `consent` (#588).
  */
 export declare function rollbackMigration(database: D1Database, provider: MigrationProvider, target?: MigrationTarget, consent?: RetainedConsent): Promise<MigrationResult[]>;
+/** What one database reverses of a group: the group, and its migrations newest first. */
+export interface MigrationGroupStep {
+    /** The group being reversed — what the caller passed to `--group`. */
+    group: string;
+    /**
+     * This database's portion of it, in the order it comes down: newest first. The caller reads it from
+     * `readGroupPosition`, which is also what proves the group is the top of this database's chain. It says
+     * **whether** there is anything to reverse here; what comes down is read from the ledger again below, so
+     * a step that named a migration from the group underneath could not reverse it on the caller's word.
+     */
+    migrations: readonly string[];
+}
+/**
+ * **Reverse one group's portion of one database — the operation behind `pithy migrate --rollback
+ * --group` (#694).**
+ *
+ * Kysely steps down from the tip, so this is `migrateDown()` once per migration in the group, in reverse
+ * chain order, and **nothing outside it**. Both halves of that are read from the ledger here, not taken on
+ * the caller's word: the group has to be the ledger's own tail before the first `down`, and what each step
+ * brings down has to be one of the migrations that read said the group holds — anything else is an
+ * internal fault and throws rather than carrying on. **And a migration with no `down` stops the group**:
+ * Kysely reports one as `NotExecuted` and leaves it applied, so counting it as reversed is how a group
+ * reported itself fully rolled back with half of it still in the database. The caller's pre-flight is what
+ * makes a group reverse completely or not at all across databases; this is the floor under it.
+ *
+ * **One migrator for the whole group**, so the retained guard clears once and the caller's budget is spent
+ * once across every `down` it covers (#588). Each migration's group row is forgotten as it comes down —
+ * before the step's failure is raised — so a group reversal that dies partway can be re-run under the
+ * same group and reverses what is left.
+ */
+export declare function reverseMigrationGroup(database: D1Database, provider: MigrationProvider, step: MigrationGroupStep, target?: MigrationTarget, consent?: RetainedConsent): Promise<MigrationResult[]>;
 /**
  * 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
@@ -74,6 +135,16 @@ export declare function rollbackMigration(database: D1Database, provider: Migrat
  * 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. Refused, before the first `down`, while a
  * retained table here holds rows the caller has not counted in `consent` (#588).
+ *
+ * **It leaves the group bookkeeping exactly as it was (#694).** The table is not a migration, so the `down`
+ * pass cannot remove it, and rewriting the rows would restamp somebody's release as having happened during
+ * a `seed --redo`. Every group row still describes a migration this reset reapplied.
+ *
+ * **What it does not do is record a group for the rest.** A reset reapplies everything *declared*, which
+ * includes migrations that were pending when it started, and those come back applied under no group — this
+ * takes no group and invents none. Such a migration sits over the groups below it, so a `--rollback
+ * --group` of one of them is refused by name (`./groups`, `readGroupPosition`) rather than reversing a
+ * migration nobody recorded.
  */
 export declare function resetMigrations(database: D1Database, provider: MigrationProvider, target?: MigrationTarget, consent?: RetainedConsent): Promise<MigrationResult[]>;
 /**

package/dist/migrations/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/migrations/runner.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAA2B,MAAM,kBAAkB,CAAC;AAKzG,OAAO,EAAgC,cAAc,EAAE,MAAM,YAAY,CAAC;AA4D1E;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,wFAAwF;IACxF,OAAO,EAAE,MAAM,CAAC;IAChB,uGAAuG;IACvG,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAUD,iFAAiF;AACjF,wBAAsB,aAAa,CACjC,QAAQ,EAAE,UAAU,EACpB,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,eAAe,EAAE,CAAC,CAG5B;AAED,8GAA8G;AAC9G,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;;OAGG;IACH,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC,CAOrH;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,UAAU,EACpB,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,CAAC,EAAE,eAAe,EACxB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,eAAe,EAAE,CAAC,CAG5B;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,UAAU,EACpB,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,CAAC,EAAE,eAAe,EACxB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,eAAe,EAAE,CAAC,CAO5B;AAgBD;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,qGAAqG;IACrG,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,yEAAyE;IACzE,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,UAAU,EACpB,IAAI,EAAE,aAAa,EACnB,MAAM,CAAC,EAAE,eAAe,EACxB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,eAAe,EAAE,CAAC,CA4C5B"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/migrations/runner.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAA2B,MAAM,kBAAkB,CAAC;AAOzG,OAAO,EAAgC,cAAc,EAAE,MAAM,YAAY,CAAC;AAkE1E;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,wFAAwF;IACxF,OAAO,EAAE,MAAM,CAAC;IAChB,uGAAuG;IACvG,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAUD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,UAAU,EACpB,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,CAAC,EAAE,eAAe,EACxB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,eAAe,EAAE,CAAC,CA6B5B;AAED,8GAA8G;AAC9G,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;;OAGG;IACH,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC,CAOrH;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,UAAU,EACpB,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,CAAC,EAAE,eAAe,EACxB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,eAAe,EAAE,CAAC,CAI5B;AAED,yFAAyF;AACzF,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,UAAU,EACpB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,kBAAkB,EACxB,MAAM,CAAC,EAAE,eAAe,EACxB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,eAAe,EAAE,CAAC,CA0D5B;AAUD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,UAAU,EACpB,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,CAAC,EAAE,eAAe,EACxB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,eAAe,EAAE,CAAC,CAO5B;AAWD;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,qGAAqG;IACrG,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,yEAAyE;IACzE,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,UAAU,EACpB,IAAI,EAAE,aAAa,EACnB,MAAM,CAAC,EAAE,eAAe,EACxB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,eAAe,EAAE,CAAC,CA+C5B"}