@pithy-sh/core 0.6.2 → 0.7.0

package/dist/text/comments.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"comments.d.ts","sourceRoot":"","sources":["../../src/text/comments.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAgCpD"}
+{"version":3,"file":"comments.d.ts","sourceRoot":"","sources":["../../src/text/comments.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE9D"}

package/dist/text/comments.js

@@ -62,6 +62,26 @@
 * `worker-safety.test.ts` exists to enforce, so the gate now polices the stripper it reads with.
 */
 function blankComments(source) {
+	return blank(source, false);
+}
+/**
+* `source` with every comment **and every string's contents** blanked — for a gate asking whether a name is
+* *called*, where {@link blankComments}' own rule points the wrong way.
+*
+* `blankComments` keeps strings because its callers look for a forbidden read, and a string that merely contains
+* one is a false positive, the safe direction. A gate looking for a *required* call inverts that: a validator named
+* only inside an error message — `"requireEnvironment(args.env)"` — is a call that never runs, and counting it
+* passes the file. So this blanks the contents too, delimiters kept, character for character.
+*
+* **A template literal goes whole, `${}` included.** A call written only inside an interpolation is not seen. For
+* a presence check that is the safe direction again — the file is flagged, never passed — and a scan for a read
+* belongs on {@link blankComments}, where the interpolation stays.
+*/
+function blankCommentsAndStrings(source) {
+	return blank(source, true);
+}
+/** The one walk behind both: comments always blanked, a quoted run kept or blanked inside its delimiters. */
+function blank(source, strings) {
 	let out = "";
 	let previous = "";
 	let index = 0;
@@ -76,7 +96,8 @@ function blankComments(source) {
 		}
 		if (char === "\"" || char === "'" || char === "`") {
 			const stop = endOfQuoted(source, index, char, char !== "`");
-			out += source.slice(index, stop);
+			const run = source.slice(index, stop);
+			out += strings ? blankInside(run, char) : run;
 			index = stop;
 			previous = char;
 			continue;
@@ -94,6 +115,11 @@ function blankComments(source) {
 	}
 	return out;
 }
+/** A quoted run with everything between its delimiters blanked, newlines kept. An unterminated run has no closer. */
+function blankInside(run, quote) {
+	const closed = run.length > 1 && run.endsWith(quote);
+	return `${quote}${run.slice(1, closed ? -1 : void 0).replace(/[^\n]/g, " ")}${closed ? quote : ""}`;
+}
 /**
 * After one of these, a `/` opens a regex literal; after anything else it divides. The empty string is
 * the start of the file. A wrong guess is bounded — see {@link endOfRegex}.
@@ -160,4 +186,4 @@ function endOfRegex(source, start) {
 	return source.length;
 }
 //#endregion
-export { blankComments };
+export { blankComments, blankCommentsAndStrings };

package/dist/version.generated.d.ts

@@ -3,5 +3,5 @@
 /** This package's npm name — the join key against a release feed. */
 export declare const PACKAGE_NAME = "@pithy-sh/core";
 /** This package's version, stamped from its own package.json at generation time. */
-export declare const PACKAGE_VERSION = "0.6.2";
+export declare const PACKAGE_VERSION = "0.7.0";
 //# sourceMappingURL=version.generated.d.ts.map

package/dist/version.generated.js

@@ -4,6 +4,6 @@
 /** This package's npm name — the join key against a release feed. */
 const PACKAGE_NAME = "@pithy-sh/core";
 /** This package's version, stamped from its own package.json at generation time. */
-const PACKAGE_VERSION = "0.6.2";
+const PACKAGE_VERSION = "0.7.0";
 //#endregion
 export { PACKAGE_NAME, PACKAGE_VERSION };

package/dist/workflow/host.d.ts

@@ -127,6 +127,14 @@ export interface WorkflowHostParams {
      * not depend on `@pithy-sh/secrets`, which owns that naming.
      */
     masterKeySecretName?: string;
+    /**
+     * Secrets Store binding name → the entry it resolves to in this environment, for every store secret the
+     * host reads besides the master key. Filled **only** for the bindings listed, like
+     * {@link databaseNames}; the names come from the capability, which composes them with the same namer
+     * provisioning created the entries with. Core composes none of them itself, for the reason
+     * {@link masterKeySecretName} gives.
+     */
+    secretNames?: Record<string, string>;
     /** Vars merged over the template's, e.g. the capability's config serialized as one JSON blob. */
     vars?: Record<string, string>;
     /**

package/dist/workflow/host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/workflow/host.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/workflow/host.ts"],"names":[],"mappings":"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"}

package/dist/workflow/host.js

@@ -59,11 +59,14 @@ function resolveWorkflowHost(template, params) {
 	if (resolved.send_email) resolved.send_email = resolved.send_email.map((entry) => withRemote(entry, entry.name, remote));
 	if (resolved.secrets_store_secrets && params.secretsStoreId !== void 0) {
 		const storeId = params.secretsStoreId;
-		const masterKey = params.masterKeySecretName;
+		const names = {
+			...params.masterKeySecretName !== void 0 ? { SECRETS_ENCRYPTION_KEYS: params.masterKeySecretName } : {},
+			...params.secretNames
+		};
 		resolved.secrets_store_secrets = resolved.secrets_store_secrets.map((entry) => ({
 			...entry,
 			store_id: storeId,
-			secret_name: masterKey !== void 0 && entry.binding === "SECRETS_ENCRYPTION_KEYS" ? masterKey : entry.secret_name
+			secret_name: Object.hasOwn(names, entry.binding) ? names[entry.binding] : entry.secret_name
 		}));
 	}
 	if (resolved.workflows) {

package/dist/workflow/hostEnv.d.ts

@@ -40,7 +40,7 @@ export type HostEnvProviderKind = z.infer<typeof HostEnvProviderKind>;
 /**
  * What provides one field. The whole point of the declaration: a report that says `BASE_URL is
  * missing` sends a developer looking, and a report that says `Var BASE_URL in the host's
- * wrangler.jsonc. Run pithy email provision --env dev.` ends the search.
+ * wrangler.jsonc. Run pithy email provision.` ends the search.
  */
 export declare const HostEnvProvider: z.ZodObject<{
     kind: z.ZodEnum<{

package/dist/workflow/hostEnv.js

@@ -41,7 +41,7 @@ const HostEnvProviderKind = z.enum([
 /**
 * What provides one field. The whole point of the declaration: a report that says `BASE_URL is
 * missing` sends a developer looking, and a report that says `Var BASE_URL in the host's
-* wrangler.jsonc. Run pithy email provision --env dev.` ends the search.
+* wrangler.jsonc. Run pithy email provision.` ends the search.
 */
 const HostEnvProvider = z.object({
 	kind: HostEnvProviderKind.describe("Which kind of thing fills this field."),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pithy-sh/core",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/capability/capability.ts

@@ -19,6 +19,7 @@ import type { LocaleContext } from "../i18n/locale";
 import type { Translator } from "../i18n/translator";
 import type { KvNamespaceSpecMap } from "../kv/namespaces";
 import type { Logger } from "../logger/logger";
+import { declareRetained } from "../migrations/retainedDeclaration";
 import type { SeedSet } from "../seed/seed";
 import type { WorkflowSpecMap } from "../workflow/spec";
 import { BindingSpec, type BindingSpecInput } from "./bindings";
@@ -595,6 +596,11 @@ export function defineCapability<
   const Name extends string = string,
   const Workflows extends WorkflowSpecMap = Record<never, never>,
 >(input: CapabilityInput<Databases, Namespaces, Name, Workflows>): Capability<Databases, Namespaces, Name, Workflows> {
+  // A retained table is declared on the `down`s that could drop it the moment the capability exists, so a
+  // migration the runner is handed carries it however its provider was built (#588).
+  for (const spec of Object.values(input.databases ?? {})) {
+    if (spec.migrations && spec.retained) declareRetained(spec.migrations, spec.retained);
+  }
   return {
     ...input,
     requiredBindings: input.requiredBindings.map((binding) => BindingSpec.parse(binding)),

package/src/capability/settings.ts

@@ -112,8 +112,21 @@ export interface SettingsAccountReader {
   d1Databases(): Promise<readonly string[]>;
   /** Whether this account holds a Cloudflare zone covering the hostname — the prerequisite for onboarding it. */
   zone(hostname: string): Promise<boolean>;
-  /** Whether a declared secret has a value in that environment. The name is the registry's, not a binding's. */
-  secret(request: { name: string; environment: string }): Promise<boolean>;
+  /**
+   * Whether that environment's **D1 vault** holds a value under this registry name — asked of its manager
+   * Worker, the only thing that can open it.
+   *
+   * Named for the store it asks, because it used to be `secret()` — "does this secret have a value" — and
+   * that question has two stores behind it (#596). A check asking it about a `cf-secrets-store` secret got a
+   * confident `false` from a vault the secret never lives in. Ask {@link storeEntry} about one of those.
+   */
+  vaultSecret(request: { name: string; environment: string }): Promise<boolean>;
+  /**
+   * Whether the account's **Secrets Store** holds an entry of exactly this name. The name is the entry's, not
+   * the registry's: compose it with `environmentScope(project, env).secretEntry(...)`, the namer provisioning
+   * created it with, so the check looks where the value went.
+   */
+  storeEntry(name: string): Promise<boolean>;
 }
 
 /** What the account tier is told: everything the local tier gets, plus the account it may ask. */

package/src/data/databases.ts

@@ -29,6 +29,17 @@ export interface DatabaseSpec<Tables extends SchemaMap = SchemaMap> {
   migrations?: Record<string, Migration>;
   /** Sort order within this database relative to other capabilities (core low, app high). Required with `migrations`. */
   migrationOrder?: number;
+  /**
+   * The tables in this slice whose rows **exist nowhere else** — a vault's sealed credentials, a
+   * suppression list of people who asked not to be mailed. Keys of `tables`, declared beside the
+   * `migrations` that create them (required with them).
+   *
+   * A schema `down` is right to drop a table; for these it destroys the only copy. So while one of them
+   * holds rows, no `down` runs against this database — a rollback, a `seed --redo` reset, a
+   * `remove --drop` — unless the operator passes the exact row count (`--destroy-retained <n>`). The
+   * refusal lives in the migration runner, so a new command that reverses migrations inherits it (#588).
+   */
+  retained?: readonly (keyof Tables & string)[];
 }
 
 /** A capability's databases: database name → {@link DatabaseSpec}. */

package/src/migrations/registry.ts

@@ -3,6 +3,7 @@
 
 import type { Migration, MigrationProvider } from "kysely/migration";
 import { InternalError } from "../error/pithyError";
+import { declareRetained } from "./retainedDeclaration";
 
 /** Width of the zero-padded `order` prefix in a composed key — the stable anchor. */
 const ORDER_DIGITS = 4;
@@ -29,6 +30,12 @@ export interface NamespacedMigrations {
   order: number;
   /** Stable, per-namespace keys, each `^\d{4}_[a-z0-9_]+$` (e.g. "0001_init"). */
   migrations: Record<string, Migration>;
+  /**
+   * The table keys (camelCase, as the capability's `tables` declares them) this set's capability retains
+   * in this database — rows that exist nowhere else. Recorded on this set's `down`s, and the runner refuses
+   * any `down` against the database while one of them holds rows. See `./retained`.
+   */
+  retained?: readonly string[];
 }
 
 // These guard build-time registry invariants — a capability author wired its migrations wrong.
@@ -85,6 +92,9 @@ function composeDatabase(database: string, sets: NamespacedMigrations[]): Migrat
     }
   }
 
+  // Recorded on each migration's own `down`, so the runner enforces it on this provider and on anything
+  // later built from these same migrations — no caller has to remember to pass it along (#588).
+  for (const set of sets) declareRetained(set.migrations, set.retained ?? []);
   return {
     getMigrations: async (): Promise<Record<string, Migration>> => composed,
   };

package/src/migrations/retained.ts

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

package/src/migrations/retainedDeclaration.ts

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