@pithy-sh/core 0.9.0 → 0.11.0

package/src/migrations/runner.ts

@@ -4,10 +4,12 @@
 import type { D1Database } from "@cloudflare/workers-types";
 import { type Kysely, sql } from "kysely";
 import { type MigrationProvider, type MigrationResult, Migrator, NO_MIGRATIONS } from "kysely/migration";
+import { pithyCommand } from "../cli/command";
 import { causeMessage } from "../error/cause";
-import { InternalError } from "../error/pithyError";
+import { InternalError, ValidationError } from "../error/pithyError";
 import { batchedProvider } from "./batch";
-import { MIGRATION_LOCK_TABLE, MIGRATION_TABLE, migrationKysely } from "./bookkeeping";
+import { appliedMigrationChain, MIGRATION_LOCK_TABLE, MIGRATION_TABLE, migrationKysely } from "./bookkeeping";
+import { forgetMigrationGroups, generatedMigrationGroup, readGroupPosition, recordMigrationGroup } from "./groups";
 import { guardRetained, isDownRefusal, RetainedBudget } from "./retained";
 
 /**
@@ -33,6 +35,12 @@ import { guardRetained, isDownRefusal, RetainedBudget } from "./retained";
  * 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.
+ *
+ * **Every run belongs to a group, and a reversal names one — see `./groups` (#694).** A forward run
+ * records the group it applied each migration under, in a table beside the ledger;
+ * {@link reverseMigrationGroup} reverses one group's portion of one database, in reverse chain order and
+ * nothing outside it. {@link rollbackMigration} is still the single step underneath, for a caller holding
+ * one migration rather than a release — it is not what `pithy migrate --rollback` runs any more.
  */
 
 /**
@@ -105,13 +113,63 @@ function guardOptions(
   return { binding: target?.binding ?? "this database", budget: consent?.budget ?? new RetainedBudget(undefined) };
 }
 
-/** Run every pending migration to latest. An empty provider resolves to `[]`. */
+/**
+ * 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 async function runMigrations(
   database: D1Database,
   provider: MigrationProvider,
   target?: MigrationTarget,
+  options?: RunGroupOptions,
 ): Promise<MigrationResult[]> {
   const { error, results } = await migrator(database, provider, target, undefined).migrateToLatest();
+  const applied = (results ?? [])
+    .filter((result) => result.direction === "Up" && result.status === "Success")
+    .map((result) => result.migrationName);
+  try {
+    await recordMigrationGroup(database, {
+      group: options?.group ?? generatedMigrationGroup(),
+      migrations: applied,
+    });
+  } catch (cause) {
+    // A migration failure is the operator's first problem and wins the throw; `settle` raises it below.
+    // With the run otherwise clean, a ledger that records a migration no group claims is its own fault.
+    if (error === undefined) {
+      throw new InternalError(
+        {
+          message: `Applied ${applied.length === 1 ? "a migration" : `${applied.length} migrations`}${on(target)}, then couldn't record the group.`,
+          detail: `${where(target)} ${reasonOf(cause)}`,
+          // Never "run pithy migrate again to record the group": the second run has nothing pending, so it
+          // records nothing and prints `Nothing to migrate.` while the group stays lost. The honest fact is
+          // what these migrations can no longer be — the group they were applied under is gone (#694).
+          action:
+            "Check the database is writable. A second run records nothing for them, so they cannot be reversed by group.",
+        },
+        { cause },
+      );
+    }
+  }
   return settle("run", error, results, target);
 }
 
@@ -153,9 +211,17 @@ export async function readMigrationLedger(database: D1Database, provider: Migrat
 }
 
 /**
- * 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 async function rollbackMigration(
   database: D1Database,
@@ -164,9 +230,115 @@ export async function rollbackMigration(
   consent?: RetainedConsent,
 ): Promise<MigrationResult[]> {
   const { error, results } = await migrator(database, provider, target, consent).migrateDown();
+  await forgetReversed(database, results);
   return settle("rollback", error, results, target);
 }
 
+/** 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 async function reverseMigrationGroup(
+  database: D1Database,
+  provider: MigrationProvider,
+  step: MigrationGroupStep,
+  target?: MigrationTarget,
+  consent?: RetainedConsent,
+): Promise<MigrationResult[]> {
+  if (step.migrations.length === 0) return [];
+  // Asked of the ledger before the first `down`, so the ordinary ways to get this wrong — another group
+  // applied over this one, or a migration applied under no group at all — are refused rather than
+  // diagnosed afterwards, from under a `down` that has already run.
+  const position = await readGroupPosition(database, step.group);
+  if (position.state !== "top") {
+    throw new InternalError({
+      message: `Group "${step.group}" is not the top of ${target?.binding ?? "this database"}'s chain.`,
+      detail: `${where(target)} ${position.state === "absent" ? "It records nothing under that group." : `Applied over it: ${overIt(position.above, position.ungrouped)}.`}`,
+      action: `Run ${pithyCommand("doctor")} to see where each database stands.`,
+    });
+  }
+  // What comes down is what the ledger says this group holds, never the caller's list: a step naming a
+  // migration the group does not hold would otherwise be reversed on the caller's word.
+  const remaining = new Set(position.migrations);
+  const runner = migrator(database, provider, target, consent);
+  const reversed: MigrationResult[] = [];
+  while (remaining.size > 0) {
+    const { error, results } = await runner.migrateDown();
+    await forgetReversed(database, results);
+    const settled = settle("rollback", error, results, target);
+    if (settled.length === 0) break;
+    for (const result of settled) {
+      // **A migration with no `down` is a refusal, not a reversal.** Kysely's `#migrateDown` runs the body
+      // and deletes the ledger row only `if (migration.down)`, so one without it comes back `NotExecuted`
+      // — no error, row intact — and `./batch` preserves that shape deliberately. Counted as reversed, the
+      // group reported itself fully rolled back while part of it was still applied and still carried its
+      // group rows; and when the `down`-less migration was the group's newest, the next pass got the same
+      // tip back and the throw below blamed the chain's order for a missing `down`. So it stops here, in
+      // the one wording that names the cause, before the rest of the group comes down around it.
+      if (result.status !== "Success") {
+        throw new ValidationError({
+          message: `Migration "${result.migrationName}" has no down, so group "${step.group}" cannot be reversed${on(target)}.`,
+          action: `Give ${result.migrationName} a down, then reverse the group again.`,
+          // What already came down stays down, and the operator needs it by name to know where they are —
+          // the same fact `settle` reports for a forward run that failed partway.
+          detail: [
+            where(target),
+            reversed.length === 0
+              ? "Nothing was reversed. A group reverses completely or not at all."
+              : `Reversed before the refusal: ${reversed.map((entry) => `"${entry.migrationName}"`).join(", ")}. The rest of the group is still applied.`,
+          ]
+            .filter(Boolean)
+            .join(" "),
+        });
+      }
+      if (!remaining.delete(result.migrationName)) {
+        throw new InternalError({
+          message: `Reversing group "${step.group}"${on(target)} would have reversed "${result.migrationName}", which is not in it.`,
+          detail: `${where(target)} The group was not the top of this database's chain. Kysely steps down from the tip, so only the newest group can be reversed.`,
+          action: `Run ${pithyCommand("doctor")} to see where each database stands.`,
+        });
+      }
+      reversed.push(result);
+    }
+  }
+  return reversed;
+}
+
+/** Forget the group rows of whatever actually came down, whether or not the step then failed. */
+async function forgetReversed(database: D1Database, results: MigrationResult[] | undefined): Promise<void> {
+  const names = (results ?? [])
+    .filter((result) => result.direction === "Down" && result.status === "Success")
+    .map((result) => result.migrationName);
+  await forgetMigrationGroups(database, names);
+}
+
 /**
  * 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
@@ -175,6 +347,16 @@ export async function rollbackMigration(
  * 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 async function resetMigrations(
   database: D1Database,
@@ -191,17 +373,12 @@ export async function resetMigrations(
 }
 
 /**
- * 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".
+ * The applied migration names recorded in the ledger — empty when the ledger table doesn't exist yet. The
+ * set half of `appliedMigrationChain`, which is the one read of the ledger: order matters to a group
+ * rollback and not at all to a membership test, and two reads of one table would drift.
  */
 async function appliedMigrationNames(db: Kysely<unknown>): Promise<Set<string>> {
-  const present = await sql<{
-    name: string;
-  }>`select name from sqlite_master where type = 'table' and name = ${MIGRATION_TABLE}`.execute(db);
-  if (present.rows.length === 0) return new Set();
-  const { rows } = await sql<{ name: string }>`select name from ${sql.table(MIGRATION_TABLE)}`.execute(db);
-  return new Set(rows.map((row) => row.name));
+  return new Set(await appliedMigrationChain(db));
 }
 
 /**
@@ -264,6 +441,9 @@ export async function dropMigrations(
     try {
       await down(db);
       await sql`delete from ${sql.table(MIGRATION_TABLE)} where name = ${name}`.execute(db);
+      // The group bookkeeping follows the ledger row it describes: a dropped migration is not applied,
+      // so nothing may go on recording which run applied it.
+      await forgetMigrationGroups(database, [name]);
       results.push({ migrationName: name, direction: "Down", status: "Success" });
     } catch (error) {
       // A refusal is not a failed drop: nothing is broken, and "fix the migration's down" would be a lie.
@@ -273,7 +453,7 @@ export async function dropMigrations(
         {
           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.",
+          action: "Fix the migration's down, or drop its table by hand. Then run this again.",
         },
         { cause: error },
       );
@@ -287,27 +467,39 @@ const VOICE = {
   run: {
     failed: (key: string) => `Couldn't apply "${key}"`,
     fallback: "The migration run failed",
-    action: "Fix the migration. Run pithy migrate again.",
+    action: "Fix the migration, then run this again.",
   },
   rollback: {
     failed: (key: string) => `Couldn't roll back "${key}"`,
     fallback: "The rollback failed",
-    // Never "run --rollback again": a rollback steps back every database, so a second one after a partial
-    // failure reverses a second migration in each database that already moved (#588).
-    action: "Fix the migration's down. Run pithy doctor to see where each database stands.",
+    // Still not a bare "run --rollback again" — that command reverses nothing now, and before #694 it
+    // stepped a second migration back in every database that had already moved (#588). Re-running the
+    // *same group* is the safe retry: each migration's group row is forgotten as it comes down, so a
+    // second pass reverses what is left and nothing else. The group is on the command, not here.
+    action: `Fix the migration's down. Run ${pithyCommand("doctor")} to see where each database stands.`,
   },
   resetDown: {
     failed: (key: string) => `Couldn't roll back "${key}" during reset`,
     fallback: "The schema reset failed while rolling back",
-    action: "Fix the migration. Run pithy seed --redo again.",
+    action: "Fix the migration, then run this again.",
   },
   resetUp: {
     failed: (key: string) => `Couldn't reapply "${key}" during reset`,
     fallback: "The schema reset failed while reapplying",
-    action: "Fix the migration. Run pithy seed --redo again.",
+    action: "Fix the migration, then run this again.",
   },
 } as const;
 
+/**
+ * What sits over a buried group, groups and ungrouped migrations alike, newest first.
+ *
+ * An ungrouped migration is named with its state, because the two are different problems: another group is
+ * something to reverse first, while a migration no group claims cannot be reversed by group at all.
+ */
+function overIt(above: readonly string[], ungrouped: readonly string[]): string {
+  return [...above, ...ungrouped.map((name) => `${name} (ungrouped)`)].join(", ");
+}
+
 /** ` on DB`, or nothing at all — every problem line here ends with this and then a period. */
 function on(target: MigrationTarget | undefined): string {
   return target ? ` on ${target.binding}` : "";

package/src/migrations/state.ts

@@ -0,0 +1,94 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import type { MigrationProvider } from "kysely/migration";
+import { appliedMigrationChain, migrationKysely } from "./bookkeeping";
+import { readGroupPosition, readMigrationGroups } from "./groups";
+import { readMigrationLedger } from "./runner";
+
+/**
+ * **Where one database stands, read in one place (#729).**
+ *
+ * The control-plane seam answers `GET {basePath}/migrations` from this: what is applied, what this build
+ * declares and the database lacks, what the database holds and this build no longer declares, and which
+ * run put it there. Each half already had a reader — {@link readMigrationLedger} for both directions,
+ * {@link readMigrationGroups} and {@link readGroupPosition} for the group (#694) — and this composes them
+ * rather than reading either table a second way.
+ *
+ * Read-only. It applies nothing, creates nothing, and reverses nothing: a screen somebody opened to *ask*
+ * must not be the thing that changes the schema.
+ */
+
+/** Whether the last group can still be taken back by name — {@link readGroupPosition}, minus `absent`. */
+export type MigrationGroupStanding =
+  | {
+      /** The group's migrations are the contiguous tip of this ledger. The CLI's rollback has refusals of its own. */
+      state: "top";
+    }
+  | {
+      /** Something sits over the group or inside it, so reversing it by name is refused. */
+      state: "buried";
+      /** The groups in the way, newest first. */
+      above: string[];
+      /** The migrations in the way that no group claims, newest first. */
+      ungrouped: string[];
+    };
+
+/** The newest group with anything still applied here, and whether it is still reversible. */
+export interface MigrationLastGroup {
+  /** The group's value — what `--rollback --group` takes. */
+  group: string;
+  /** When it last applied something here. */
+  appliedAt: Date;
+  /** What it applied here and is still applied, in application order. */
+  migrations: string[];
+  /** Whether it is the tip of the chain, or what is in its way. */
+  position: MigrationGroupStanding;
+}
+
+/** One database's migration state. */
+export interface MigrationState {
+  /** Every applied migration, in the order the ledger applied them. */
+  applied: string[];
+  /** Declared and not yet applied, in the order they would run. */
+  pending: string[];
+  /** Applied and not declared by this build, sorted. Kysely refuses the whole chain on any one of these. */
+  undeclared: string[];
+  /** The newest group with anything applied here, or null when nothing applied here was ever grouped. */
+  lastGroup: MigrationLastGroup | null;
+}
+
+/**
+ * Read one database's migration state against the provider this build composes for it.
+ *
+ * **The last group is the newest one with something still applied.** Group rows are forgotten as their
+ * migrations come down, so this is ordinarily the newest group recorded. A group whose rows outlived their
+ * ledger rows reads as `absent` and is passed over: naming it as where the environment stands would name a
+ * release that is no longer in the database.
+ */
+export async function readMigrationState(database: D1Database, provider: MigrationProvider): Promise<MigrationState> {
+  const { pending, undeclared } = await readMigrationLedger(database, provider);
+  const applied = await appliedMigrationChain(migrationKysely(database));
+  return { applied, pending, undeclared, lastGroup: await lastGroupOf(database, applied) };
+}
+
+/** Walk the groups newest first and stop at the first one this database still holds any of. */
+async function lastGroupOf(database: D1Database, applied: readonly string[]): Promise<MigrationLastGroup | null> {
+  const held = new Set(applied);
+  const groups = await readMigrationGroups(database);
+  for (const group of [...groups].reverse()) {
+    const position = await readGroupPosition(database, group.group);
+    if (position.state === "absent") continue;
+    return {
+      group: group.group,
+      appliedAt: group.appliedAt,
+      migrations: group.migrations.filter((name) => held.has(name)),
+      position:
+        position.state === "top"
+          ? { state: "top" }
+          : { state: "buried", above: position.above, ungrouped: position.ungrouped },
+    };
+  }
+  return null;
+}

package/src/naming/domains.ts

@@ -72,7 +72,73 @@ const PUNYCODE_LABEL = /(^|\.)xn--/;
  * them rather than a side effect of a parser version.
  */
 export function isPublicHostname(hostname: string): boolean {
-  return hostname.length <= 253 && HOSTNAME_PATTERN.test(hostname) && !PUNYCODE_LABEL.test(hostname);
+  return publicHostnameProblem(hostname) === null;
+}
+
+/** The DNS limit on a whole name, and the only length any caller measures. */
+const MAX_HOSTNAME_LENGTH = 253;
+
+/**
+ * Why a string is not a hostname a Worker can answer on — the reason, not a boolean.
+ *
+ * **It exists so a refusal can say which rule it broke.** {@link isPublicHostname} is the answer when the
+ * caller only needs yes or no; `WorkerDomain` needs the reason, because the three are not interchangeable
+ * to the adopter reading the message. A name over the limit is a typo. A name with a scheme on it is a
+ * misunderstanding. An internationalized name is neither — it is a thing this kit cannot do, for a reason
+ * that is not this kit's, and a message about bare hostnames would send that adopter looking for a typo
+ * they do not have (#665).
+ *
+ * Ordered by how specific the answer is. The length check is first because a name that long is over the
+ * limit whatever else is wrong with it, and `punycode` last because it is only reachable for a string that
+ * is otherwise a well-formed hostname.
+ */
+export function publicHostnameProblem(hostname: string): HostnameProblem | null {
+  if (hostname.length > MAX_HOSTNAME_LENGTH) return "too-long";
+  if (!HOSTNAME_PATTERN.test(hostname)) return "shape";
+  if (PUNYCODE_LABEL.test(hostname)) return "punycode";
+  return null;
+}
+
+/** The three ways a string fails {@link publicHostnameProblem}, each with its own sentence to say. */
+export type HostnameProblem = "too-long" | "shape" | "punycode";
+
+/**
+ * What an adopter is told, per reason, for a hostname this kit refuses.
+ *
+ * `shape` is the caller's to say, because what a bare hostname is differs between a `pattern` and a
+ * `zone` and each already had a sentence worth keeping. The other two are the same wherever they are hit.
+ *
+ * **The internationalized-domain sentence names Cloudflare**, and that is deliberate: the limit is not
+ * ours. `pithy-sh/pithy#691` tested it against a real zone — adding `tëst.pithy-sh.com` as a Worker
+ * Custom Domain returns *Internationalized Domain Names not supported* — so the kit refuses what the
+ * platform will not route rather than inventing a rule of its own. `docs/ACCEPTED-LIMITS.md` carries the
+ * evidence and the condition that would lift it.
+ */
+const HOSTNAME_PROBLEM_MESSAGES: Readonly<Record<Exclude<HostnameProblem, "shape">, string>> = {
+  "too-long": `A hostname is at most ${MAX_HOSTNAME_LENGTH} characters — the DNS limit on a whole name.`,
+  punycode:
+    "Internationalized domains are not supported: Cloudflare Workers will not route one, so a Worker could never answer on it. Use an ASCII hostname.",
+};
+
+/**
+ * One `pattern` or `zone` field, held to the one hostname rule.
+ *
+ * **Through {@link publicHostnameProblem}, never `HOSTNAME_PATTERN` directly.** A configured domain was
+ * the third caller of that rule and the only one that did not go through the function — it handed the
+ * pattern to `.regex()`, so it took a punycode A-label and a 267-character name that `pithy seed --host`
+ * refused for the same string. Two answers to one question, forty lines apart (#665). A rule added to the
+ * function now reaches a configured domain without anyone remembering to.
+ */
+function hostnameField(shapeMessage: string): z.ZodString {
+  return z.string().check((ctx) => {
+    const problem = publicHostnameProblem(ctx.value);
+    if (problem === null) return;
+    ctx.issues.push({
+      code: "custom",
+      input: ctx.value,
+      message: problem === "shape" ? shapeMessage : HOSTNAME_PROBLEM_MESSAGES[problem],
+    });
+  });
 }
 
 /** The environments a domain may be declared for — every managed one, never `dev`. */
@@ -81,21 +147,14 @@ export const DOMAIN_ENVIRONMENTS = ENVIRONMENTS.filter((environment) => environm
 /** One environment's public address for one Worker. */
 export const WorkerDomain = z
   .object({
-    pattern: z
-      .string()
-      .regex(
-        HOSTNAME_PATTERN,
-        "A domain is a bare hostname — no scheme, no path, no port (e.g. `api.example.com`, not `https://api.example.com/`).",
-      )
-      .describe(
-        "The hostname this Worker answers on in this environment, e.g. `api.example.com`. Written into `wrangler.jsonc` as a `routes` entry with `custom_domain: true`, and into `vars.BASE_URL` as `https://<pattern>`. A bare hostname rather than a URL, because that is what wrangler's route matcher takes — a scheme here would be silently wrong.",
-      ),
-    zone: z
-      .string()
-      .regex(HOSTNAME_PATTERN, "A zone is the registrable domain on your Cloudflare account, e.g. `example.com`.")
-      .describe(
-        "The Cloudflare zone `pattern` sits under — the registrable domain as it appears on your account, e.g. `example.com` for `api.example.com`. Cloudflare needs it to attach a custom domain, and it is not always derivable from the hostname: a zone can be a subdomain, and a public-suffix guess would be wrong for exactly the adopters who are hardest to debug.",
-      ),
+    pattern: hostnameField(
+      "A domain is a bare hostname — no scheme, no path, no port (e.g. `api.example.com`, not `https://api.example.com/`).",
+    ).describe(
+      "The hostname this Worker answers on in this environment, e.g. `api.example.com`. Written into `wrangler.jsonc` as a `routes` entry with `custom_domain: true`, and into `vars.BASE_URL` as `https://<pattern>`. A bare hostname rather than a URL, because that is what wrangler's route matcher takes — a scheme here would be silently wrong.",
+    ),
+    zone: hostnameField("A zone is the registrable domain on your Cloudflare account, e.g. `example.com`.").describe(
+      "The Cloudflare zone `pattern` sits under — the registrable domain as it appears on your account, e.g. `example.com` for `api.example.com`. Cloudflare needs it to attach a custom domain, and it is not always derivable from the hostname: a zone can be a subdomain, and a public-suffix guess would be wrong for exactly the adopters who are hardest to debug.",
+    ),
   })
   .describe("Where one Worker answers in one environment: the hostname, and the Cloudflare zone it sits under.")
   .check((ctx) => {

package/src/naming/environment.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import { z } from "zod";
+import { commandName } from "../cli/command";
 import { PithyError, ValidationError } from "../error/pithyError";
 import { NAME_SEGMENT } from "./segment";
 
@@ -144,7 +145,7 @@ export function assertValidEnvironment(name: string): void {
     throw new ValidationError({
       message: `"${name}" starts the way a feature's name does.`,
       action: "Start the environment with something other than f and a number.",
-      detail: `A feature takes the environment's slot with f<issue>, so <project>-${name}-<worker> can be a feature's Worker name exactly, and \`pithy feature destroy\` deletes that Worker.`,
+      detail: `A feature takes the environment's slot with f<issue>, so <project>-${name}-<worker> can be a feature's Worker name exactly, and \`${commandName("feature destroy")}\` deletes that Worker.`,
     });
   }
   if (name.length > MAX_ENVIRONMENT_NAME && NAME_SEGMENT.test(name)) {

package/src/naming/feature.ts

@@ -34,11 +34,26 @@ import { assertValidProjectName, kebab } from "./resource";
  * implementation rather than two that drift.
  */
 
-/** A Cloudflare resource kind a feature can provision. All two characters — `MAX_FEATURE_KIND` in `./limits`. */
-export type FeatureResourceKind = "d1" | "kv" | "r2";
+/** A Cloudflare resource kind Pithy names and creates — in a feature, and in every declared environment. */
+export type FeatureResourceKind = "d1" | "kv" | "r2" | "queue";
 
 /** Every feature resource kind, for tests and for callers that enumerate. */
-export const FEATURE_RESOURCE_KINDS: readonly FeatureResourceKind[] = ["d1", "kv", "r2"];
+export const FEATURE_RESOURCE_KINDS: readonly FeatureResourceKind[] = ["d1", "kv", "r2", "queue"];
+
+/**
+ * **The segment each kind ends a feature resource's name with — never more than `MAX_FEATURE_KIND` (#662).**
+ *
+ * `d1`, `kv` and `r2` spell themselves. A queue is `q`, and that is load-bearing: `MAX_FEATURE_KIND` is a term in
+ * `FEATURE_DERIVED_PROJECT_NAME`, so spelling it `queue` would take the project budget from 26 to 23 — and a
+ * project name is stable forever once anything is provisioned, so a smaller budget orphans every resource of a
+ * project already named against the old one. `feature.test.ts` fails on a segment longer than the budget.
+ */
+export const FEATURE_KIND_SEGMENT: Readonly<Record<FeatureResourceKind, string>> = {
+  d1: "d1",
+  kv: "kv",
+  r2: "r2",
+  queue: "q",
+};
 
 /** The identity of a feature — everything a feature name is derived from. */
 export interface FeatureIdentity {
@@ -292,10 +307,11 @@ export function assertFeatureSlugFits(identity: FeatureIdentity, shapes: readonl
 }
 
 /**
- * The full Cloudflare resource name for a feature's binding — `<project>-f<issue>-<slug>--<binding>-<kind>`.
+ * The full Cloudflare resource name for a feature's binding — `<project>-f<issue>-<slug>--<binding>-<kind>`, the
+ * kind spelled by {@link FEATURE_KIND_SEGMENT}.
  *
- * Held to **R2's 63**, the strictest of the three kinds a feature provisions, so one shape is legal for
- * all of them: lowercase, hyphenated, alphanumeric at both ends. A D1 or KV name could be longer, but a
+ * Held to **R2's 63**, the strictest of the kinds a feature provisions and a queue's number too, so one shape is
+ * legal for all of them: lowercase, hyphenated, alphanumeric at both ends. A D1 or KV name could be longer, but a
  * feature that provisions a bucket and a database wants them recognizably the same name.
  */
 export function featureResourceName(identity: FeatureIdentity, binding: string, kind: FeatureResourceKind): string {
@@ -303,7 +319,7 @@ export function featureResourceName(identity: FeatureIdentity, binding: string,
     identity,
     kebab(identity.slug),
     kebab(binding),
-    `-${kind}`,
+    `-${FEATURE_KIND_SEGMENT[kind]}`,
     NAMESPACE_LIMITS.r2.maxLength,
     NAMESPACE_LIMITS.r2.label,
   );
@@ -364,6 +380,29 @@ export function featureWorkerName(identity: FeatureIdentity, app: string): strin
   );
 }
 
+/** The `<thing>` a feature's Artifacts namespace ends with, after {@link FEATURE_TAIL_SEPARATOR} (#673). */
+export const FEATURE_ARTIFACTS_THING = "artifacts";
+
+/**
+ * A feature's **Artifacts namespace** — `<project>-f<issue>-<slug>--artifacts` (#673).
+ *
+ * A declared environment's namespace is `<project>-<env>` and has no `<thing>`. A feature's needs one, because the
+ * separator and what follows it are what make a name a feature name: {@link isFeatureOwnedName} reads this one back
+ * as this feature's, so `pithy feature destroy` reaps the repos of exactly this branch and of no sibling. Held to the
+ * namespace's 63, the same number the rest of a feature's names are derived against, and `artifacts` is shorter than
+ * the shortest binding tail, so it moves no slug budget.
+ */
+export function featureArtifactsNamespace(identity: FeatureIdentity): string {
+  return composeFeatureName(
+    identity,
+    kebab(identity.slug),
+    FEATURE_ARTIFACTS_THING,
+    "",
+    NAMESPACE_LIMITS.artifactsNamespace.maxLength,
+    NAMESPACE_LIMITS.artifactsNamespace.label,
+  );
+}
+
 /**
  * The deployed name of one of a feature's **Workflows** — `<project>-f<issue>-<slug>--<capability>-<job>` (#643).
  *