@pithy-sh/core 0.1.2 → 0.1.4

package/dist/migrations/owner.js

@@ -0,0 +1,105 @@
+import { ConflictError, ValidationError } from "../error/pithyError.js";
+import { SQLiteDate } from "../data/codecs.js";
+import { MIGRATION_OWNER_TABLE, migrationKysely } from "./bookkeeping.js";
+import { z } from "zod";
+import { sql } from "kysely";
+//#region src/migrations/owner.ts
+/**
+* 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. */
+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.");
+/** Whether the owner table has been created yet — a plain `sqlite_master` select, which D1 permits. */
+async function ownerTableExists(db) {
+	const { rows } = await sql`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) {
+	if (!await ownerTableExists(db)) return void 0;
+	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) {
+	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.
+*/
+async function readMigrationOwner(database) {
+	return currentOwner(migrationKysely(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.
+*/
+async function claimMigrationOwnership(database, options) {
+	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(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: /* @__PURE__ */ new Date()
+	});
+	await db.insertInto("pithy_migrations_owner").values({
+		id: OWNER_ROW_ID,
+		...record
+	}).onConflict((conflict) => conflict.doNothing()).execute();
+	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
+	};
+}
+//#endregion
+export { MigrationOwner, claimMigrationOwnership, readMigrationOwner };

package/dist/migrations/registry.d.ts

@@ -0,0 +1,36 @@
+import type { Migration, MigrationProvider } from "kysely/migration";
+/** Maximum per-capability `order`, derived from the prefix width so the two never drift. */
+export declare const MAX_MIGRATION_ORDER: number;
+/** Capability namespace: lowercase, starts with a letter, no separators (keeps keys injective). */
+export declare const NAMESPACE_PATTERN: RegExp;
+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>;
+}
+/**
+ * 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 declare function createMigrationRegistry(sets: NamespacedMigrations[]): Record<string, MigrationProvider>;
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +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;AAMrE,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;CACvC;AA6DD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,oBAAoB,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAavG"}

package/dist/migrations/registry.js

@@ -0,0 +1,70 @@
+import { InternalError } from "../error/pithyError.js";
+//#region src/migrations/registry.ts
+/** 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. */
+const MAX_MIGRATION_ORDER = 10 ** ORDER_DIGITS - 1;
+/** Capability namespace: lowercase, starts with a letter, no separators (keeps keys injective). */
+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_]+$/;
+function assertValidNamespace(namespace) {
+	if (!NAMESPACE_PATTERN.test(namespace)) throw new InternalError({ message: `migration namespace "${namespace}" must match ${NAMESPACE_PATTERN}` });
+}
+function assertValidOrder(order, namespace) {
+	if (!Number.isInteger(order) || order < 0 || order > 9999) throw new InternalError({ message: `migration order ${order} (namespace "${namespace}") must be an integer in 0..${MAX_MIGRATION_ORDER}` });
+}
+function assertValidLocalKey(localKey, namespace) {
+	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, sets) {
+	const seenOrders = /* @__PURE__ */ new Set();
+	const seenNamespaces = /* @__PURE__ */ new Set();
+	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 = {};
+	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 () => 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.
+*/
+function createMigrationRegistry(sets) {
+	const byDatabase = /* @__PURE__ */ new Map();
+	for (const set of sets) {
+		const group = byDatabase.get(set.database);
+		if (group) group.push(set);
+		else byDatabase.set(set.database, [set]);
+	}
+	const registry = {};
+	for (const [database, dbSets] of byDatabase) registry[database] = composeDatabase(database, dbSets);
+	return registry;
+}
+//#endregion
+export { MAX_MIGRATION_ORDER, NAMESPACE_PATTERN, createMigrationRegistry };

package/dist/migrations/runner.d.ts

@@ -0,0 +1,67 @@
+import type { D1Database } from "@cloudflare/workers-types";
+import { type MigrationProvider, type MigrationResult } from "kysely/migration";
+/**
+ * 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 declare function runMigrations(database: D1Database, provider: MigrationProvider, target?: MigrationTarget): 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. */
+    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 declare function readMigrationLedger(database: D1Database, provider: MigrationProvider): Promise<MigrationLedger>;
+/** Step the latest applied migration back — one step, the `pithy migrate --rollback` seam. */
+export declare function rollbackMigration(database: D1Database, provider: MigrationProvider, target?: MigrationTarget): 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
+ * `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 declare function resetMigrations(database: D1Database, provider: MigrationProvider, target?: MigrationTarget): Promise<MigrationResult[]>;
+/**
+ * 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 declare function dropMigrations(database: D1Database, provider: MigrationProvider, target?: MigrationTarget): Promise<MigrationResult[]>;
+//# sourceMappingURL=runner.d.ts.map

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

@@ -0,0 +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;AA0DzG;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,wFAAwF;IACxF,OAAO,EAAE,MAAM,CAAC;IAChB,uGAAuG;IACvG,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,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,8FAA8F;AAC9F,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,UAAU,EACpB,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,eAAe,EAAE,CAAC,CAG5B;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,UAAU,EACpB,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,eAAe,EAAE,CAAC,CAO5B;AAgBD;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,UAAU,EACpB,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,eAAe,EAAE,CAAC,CA+B5B"}

package/dist/migrations/runner.js

@@ -0,0 +1,218 @@
+import { InternalError } from "../error/pithyError.js";
+import { causeMessage } from "../error/cause.js";
+import { MIGRATION_LOCK_TABLE, MIGRATION_TABLE, migrationKysely } from "./bookkeeping.js";
+import { batchedProvider } from "./batch.js";
+import { sql } from "kysely";
+import { Migrator, NO_MIGRATIONS } from "kysely/migration";
+//#region src/migrations/runner.ts
+/**
+* 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, provider) {
+	return new Migrator({
+		db: migrationKysely(database),
+		provider: batchedProvider(provider, database),
+		migrationTableName: MIGRATION_TABLE,
+		migrationLockTableName: MIGRATION_LOCK_TABLE,
+		allowUnorderedMigrations: true
+	});
+}
+/** Run every pending migration to latest. An empty provider resolves to `[]`. */
+async function runMigrations(database, provider, target) {
+	const { error, results } = await migrator(database, provider).migrateToLatest();
+	return settle("run", error, results, target);
+}
+/**
+* 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.
+*/
+async function readMigrationLedger(database, provider) {
+	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. */
+async function rollbackMigration(database, provider, target) {
+	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.
+*/
+async function resetMigrations(database, provider, target) {
+	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) {
+	if ((await sql`select name from sqlite_master where type = 'table' and name = ${"pithy_migrations"}`.execute(db)).rows.length === 0) return /* @__PURE__ */ new Set();
+	const { rows } = await sql`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.
+*/
+async function dropMigrations(database, provider, target) {
+	const db = migrationKysely(database);
+	const migrations = await batchedProvider(provider, database).getMigrations();
+	const applied = await appliedMigrationNames(db);
+	const results = [];
+	for (const name of Object.keys(migrations).sort().reverse()) {
+		if (!applied.has(name)) continue;
+		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) => `Couldn't apply "${key}"`,
+		fallback: "The migration run failed",
+		action: "Fix the migration. Run pithy migrate again."
+	},
+	rollback: {
+		failed: (key) => `Couldn't roll back "${key}"`,
+		fallback: "The rollback failed",
+		action: "Fix the migration. Run pithy migrate --rollback again."
+	},
+	resetDown: {
+		failed: (key) => `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) => `Couldn't reapply "${key}" during reset`,
+		fallback: "The schema reset failed while reapplying",
+		action: "Fix the migration. Run pithy seed --redo again."
+	}
+};
+/** ` on DB`, or nothing at all — every problem line here ends with this and then a period. */
+function on(target) {
+	return target ? ` on ${target.binding}` : "";
+}
+/** The throw-site half of the same fact: the database name behind the binding, for `detail`. */
+function where(target) {
+	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) {
+	const reason = (causeMessage(error) ?? String(error)).trim();
+	return reason.endsWith(".") ? reason : `${reason}.`;
+}
+function settle(verb, error, results, target) {
+	if (error !== void 0) {
+		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;
+		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 ?? [];
+}
+//#endregion
+export { dropMigrations, readMigrationLedger, resetMigrations, rollbackMigration, runMigrations };

package/dist/naming/domains.d.ts

@@ -0,0 +1,108 @@
+import { z } from "zod";
+/** The environments a domain may be declared for — every managed one, never `dev`. */
+export declare const DOMAIN_ENVIRONMENTS: ("prod" | "staging")[];
+/** One environment's public address for one Worker. */
+export declare const WorkerDomain: z.ZodObject<{
+    pattern: z.ZodString;
+    zone: z.ZodString;
+}, z.core.$strip>;
+export type WorkerDomain = z.infer<typeof WorkerDomain>;
+/**
+ * A Worker's domains, keyed by environment.
+ *
+ * Every key optional: a project with no domain yet is legitimate, and so is one that has staging wired
+ * and production not. Adding one later is a config edit plus a deploy, never a rescaffold.
+ */
+export declare const WorkerDomains: z.ZodObject<{
+    staging: z.ZodOptional<z.ZodObject<{
+        pattern: z.ZodString;
+        zone: z.ZodString;
+    }, z.core.$strip>>;
+    prod: z.ZodOptional<z.ZodObject<{
+        pattern: z.ZodString;
+        zone: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type WorkerDomains = z.infer<typeof WorkerDomains>;
+/**
+ * The declared domain for one environment, or null where none is declared (including every `dev`).
+ *
+ * `environment` may be `undefined`, which is what `compositionEnvironment()` answers when nothing stamped
+ * one. That is not a `dev` default — it is "this composition names no environment", and an environment
+ * nobody named has declared no domain, so the answer is the same `null` an undeclared one gets.
+ */
+export declare function domainFor(domains: WorkerDomains | undefined, environment: string | undefined): WorkerDomain | null;
+/** The base URL a declared domain implies. Always `https` — a custom domain on Cloudflare is TLS-terminated. */
+export declare function baseUrlFor(domain: WorkerDomain): string;
+/**
+ * The origin an environment with no declared domain resolves to.
+ *
+ * **No port, and that is the whole design.** Local dev's port is assigned per Worker per run from the
+ * feature's reserved block, so it is the one address nobody can write down — `@pithy-sh/auth` resolves
+ * dev's base URL from the host the request arrived at for exactly that reason, and a config-time value
+ * could only ever be a stale guess at it. So this is a *placeholder that fails closed*: a link built
+ * against it goes nowhere, which is useless rather than harmful.
+ *
+ * Compare what it replaces. Every capability that made an adopter write an origin got production's
+ * written into staging, and the failure was never "the link is broken" — it was a staging deploy mailing
+ * real users magic links **into production**, an unsubscribe from a staging test unsubscribing that
+ * person in production, and a Checkout return landing a staging payer in production on an account that
+ * had bought nothing. A fallback that goes nowhere is the only one that cannot do any of that.
+ */
+export declare const LOCAL_ORIGIN = "http://localhost";
+/** An environment's public origin, and whether the declaration is where it came from. */
+export interface ResolvedOrigin {
+    /** The absolute origin — scheme and host, never a trailing slash. */
+    origin: string;
+    /** The hostname alone: a route pattern, and what Turnstile binds a widget to. */
+    hostname: string;
+    /** Whether `domains` declared it. `false` means {@link LOCAL_ORIGIN} was substituted. */
+    declared: boolean;
+}
+/**
+ * **Where is this Worker publicly reachable, in this environment?** — asked once, answered once.
+ *
+ * The two halves already existed ({@link domainFor} and {@link baseUrlFor}) and nothing composed them,
+ * so every caller that needed the answer did the two-step for itself and every *adopter* who needed it
+ * wrote a URL down. The first adopter's one Worker config carried `https://app.pithy.sh` three times —
+ * `auth.baseURL`, `email.baseUrl`, and the Stripe return URLs — each wrong for staging in its own way,
+ * each found on a different day. Fixing it inside one capability does not stop the next capability
+ * asking the same question, so the question gets one answer that anyone can call.
+ *
+ * **The fallback never reaches for another environment's origin.** An environment absent from `domains`
+ * is one that is not published, so it resolves to {@link LOCAL_ORIGIN} and nothing else. Falling back to
+ * production's is what the shape being replaced did, and it is the one behavior here that was actively
+ * dangerous rather than merely wrong.
+ *
+ * **A deployed environment must never *keep* that fallback**, and it is not this function's job to say
+ * so — `pithy deploy --env <name>` refuses an environment whose origin its config does not declare
+ * (#253), and `pithy doctor` reports it first. One rule in two halves: this one cannot invent another
+ * environment's origin, and deploy makes sure the placeholder never ships.
+ *
+ * **Not every origin should derive from this, and `controlplane.issuer` is the one to name.** That is an
+ * **identity**, not an address: a connection stores the issuer it was created with and verification
+ * checks that stored value, so a per-environment issuer would make a connection minted in staging
+ * unverifiable in production. That may be the better isolation, but it is a decision about trust rather
+ * than about reachability, and a helper whose job is "where am I reachable" must not sweep it up.
+ */
+export declare function resolveOrigin(environment: string | undefined, domains: WorkerDomains | undefined): ResolvedOrigin;
+/**
+ * The one line an adopter writes: this Worker's public origin for the environment it is running in.
+ *
+ * ```ts
+ * const DOMAINS = { staging: { … }, prod: { … } };
+ * const PUBLIC_ORIGIN = originFor(compositionEnvironment(), DOMAINS);
+ * ```
+ *
+ * That is the line `pithy init` scaffolds, so an adopter who never thinks about it gets it right and one
+ * who wants a literal can still write one. `compositionEnvironment()` is `string | undefined`, and it is
+ * taken as such rather than defaulted to `dev` at the call site: an unstamped composition has declared no
+ * domain either way, and a `?? "dev"` in every adopter's config would be a default nobody chose.
+ *
+ * Named for what it is rather than for who asked. The first adopter's own version was called
+ * `AUTH_BASE_URL`, which is part of why `email` and `payments` were missed for days: the constant read
+ * as auth's private business when it is the Worker's address, and every capability that needs an origin
+ * needs this one.
+ */
+export declare function originFor(environment: string | undefined, domains: WorkerDomains | undefined): string;
+//# sourceMappingURL=domains.d.ts.map

package/dist/naming/domains.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domains.d.ts","sourceRoot":"","sources":["../../src/naming/domains.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAsCxB,sFAAsF;AACtF,eAAO,MAAM,mBAAmB,wBAA8D,CAAC;AAE/F,uDAAuD;AACvD,eAAO,MAAM,YAAY;;;iBA+BrB,CAAC;AACL,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD;;;;;GAKG;AACH,eAAO,MAAM,aAAa;;;;;;;;;iBAOvB,CAAC;AACJ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY,GAAG,IAAI,CAKlH;AAED,gHAAgH;AAChH,wBAAgB,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAEvD;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,qBAAqB,CAAC;AAE/C,yFAAyF;AACzF,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,aAAa,GAAG,SAAS,GAAG,cAAc,CAIjH;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,aAAa,GAAG,SAAS,GAAG,MAAM,CAErG"}