@pithy-sh/core 0.9.0 → 0.10.0

package/dist/migrations/runner.js

@@ -1,9 +1,11 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
-import { InternalError } from "../error/pithyError.js";
+import { InternalError, ValidationError } from "../error/pithyError.js";
+import { pithyCommand } from "../cli/command.js";
 import { causeMessage } from "../error/cause.js";
-import { MIGRATION_LOCK_TABLE, MIGRATION_TABLE, migrationKysely } from "./bookkeeping.js";
+import { MIGRATION_LOCK_TABLE, MIGRATION_TABLE, appliedMigrationChain, migrationKysely } from "./bookkeeping.js";
 import { batchedProvider } from "./batch.js";
+import { forgetMigrationGroups, generatedMigrationGroup, readGroupPosition, recordMigrationGroup } from "./groups.js";
 import { RetainedBudget, guardRetained, isDownRefusal } from "./retained.js";
 import { sql } from "kysely";
 import { Migrator, NO_MIGRATIONS } from "kysely/migration";
@@ -31,6 +33,12 @@ import { Migrator, NO_MIGRATIONS } from "kysely/migration";
 * 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.
 */
 /**
 * **`allowUnorderedMigrations` is on, and it is not a loosening.** A composed key leads with its
@@ -63,9 +71,30 @@ function guardOptions(target, consent) {
 		budget: consent?.budget ?? new RetainedBudget(void 0)
 	};
 }
-/** Run every pending migration to latest. An empty provider resolves to `[]`. */
-async function runMigrations(database, provider, target) {
+/**
+* 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.
+*/
+async function runMigrations(database, provider, target, options) {
 	const { error, results } = await migrator(database, provider, target, void 0).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) {
+		if (error === void 0) 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)}`,
+			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);
 }
 /**
@@ -94,15 +123,79 @@ async function readMigrationLedger(database, provider) {
 	};
 }
 /**
-* 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).
 */
 async function rollbackMigration(database, provider, target, consent) {
 	const { error, results } = await migrator(database, provider, target, consent).migrateDown();
+	await forgetReversed(database, results);
 	return settle("rollback", error, results, target);
 }
 /**
+* **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.
+*/
+async function reverseMigrationGroup(database, provider, step, target, consent) {
+	if (step.migrations.length === 0) return [];
+	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.`
+	});
+	const remaining = new Set(position.migrations);
+	const runner = migrator(database, provider, target, consent);
+	const reversed = [];
+	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) {
+			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.`,
+				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, results) {
+	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
 * `up` reapplies from empty. The seam behind `pithy seed --redo`'s destructive rebuild: because the
@@ -110,6 +203,16 @@ async function rollbackMigration(database, provider, target, consent) {
 * 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.
 */
 async function resetMigrations(database, provider, target, consent) {
 	const runner = migrator(database, provider, target, consent);
@@ -120,14 +223,12 @@ async function resetMigrations(database, provider, target, consent) {
 	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".
+* 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) {
-	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));
+	return new Set(await appliedMigrationChain(db));
 }
 /**
 * Surgically drop **one capability's** migrations: run each of `drop.reverse`'s `down` functions in
@@ -160,6 +261,7 @@ async function dropMigrations(database, drop, target, consent) {
 		try {
 			await down(db);
 			await sql`delete from ${sql.table(MIGRATION_TABLE)} where name = ${name}`.execute(db);
+			await forgetMigrationGroups(database, [name]);
 			results.push({
 				migrationName: name,
 				direction: "Down",
@@ -171,7 +273,7 @@ async function dropMigrations(database, drop, target, consent) {
 			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."
+				action: "Fix the migration's down, or drop its table by hand. Then run this again."
 			}, { cause: error });
 		}
 	}
@@ -182,24 +284,33 @@ const VOICE = {
 	run: {
 		failed: (key) => `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) => `Couldn't roll back "${key}"`,
 		fallback: "The rollback failed",
-		action: "Fix the migration's down. Run pithy doctor to see where each database stands."
+		action: `Fix the migration's down. Run ${pithyCommand("doctor")} to see where each database stands.`
 	},
 	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."
+		action: "Fix the migration, then run this 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."
+		action: "Fix the migration, then run this again."
 	}
 };
+/**
+* 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, ungrouped) {
+	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) {
 	return target ? ` on ${target.binding}` : "";
@@ -243,4 +354,4 @@ function settle(verb, error, results, target) {
 	return results ?? [];
 }
 //#endregion
-export { dropMigrations, readMigrationLedger, resetMigrations, rollbackMigration, runMigrations };
+export { dropMigrations, readMigrationLedger, resetMigrations, reverseMigrationGroup, rollbackMigration, runMigrations };

package/dist/naming/domains.d.ts

@@ -24,6 +24,23 @@ import { type AmbientEnv } from "../env/ambient";
  * them rather than a side effect of a parser version.
  */
 export declare function isPublicHostname(hostname: string): boolean;
+/**
+ * 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 declare function publicHostnameProblem(hostname: string): HostnameProblem | null;
+/** The three ways a string fails {@link publicHostnameProblem}, each with its own sentence to say. */
+export type HostnameProblem = "too-long" | "shape" | "punycode";
 /** 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. */

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

@@ -1 +1 @@
-{"version":3,"file":"domains.d.ts","sourceRoot":"","sources":["../../src/naming/domains.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,KAAK,UAAU,EAAc,MAAM,gBAAgB,CAAC;AAgD7D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,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;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAetG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,OAAO,EAAE,aAAa,GAAG,SAAS,EAClC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,GAC3B,cAAc,CAShB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,SAAS,CACvB,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,OAAO,EAAE,aAAa,GAAG,SAAS,EAClC,GAAG,GAAE,UAAyB,GAC7B,MAAM,CAER"}
+{"version":3,"file":"domains.d.ts","sourceRoot":"","sources":["../../src/naming/domains.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,KAAK,UAAU,EAAc,MAAM,gBAAgB,CAAC;AAgD7D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE1D;AAKD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAK9E;AAED,sGAAsG;AACtG,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,OAAO,GAAG,UAAU,CAAC;AAyChE,sFAAsF;AACtF,eAAO,MAAM,mBAAmB,wBAA8D,CAAC;AAE/F,uDAAuD;AACvD,eAAO,MAAM,YAAY;;;iBAwBrB,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;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAetG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,OAAO,EAAE,aAAa,GAAG,SAAS,EAClC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,GAC3B,cAAc,CAShB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,SAAS,CACvB,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,OAAO,EAAE,aAAa,GAAG,SAAS,EAClC,GAAG,GAAE,UAAyB,GAC7B,MAAM,CAER"}

package/dist/naming/domains.js

@@ -68,14 +68,72 @@ const PUNYCODE_LABEL = /(^|\.)xn--/;
 * them rather than a side effect of a parser version.
 */
 function isPublicHostname(hostname) {
-	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.
+*/
+function publicHostnameProblem(hostname) {
+	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;
+}
+/**
+* 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 = {
+	"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) {
+	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`. */
 const DOMAIN_ENVIRONMENTS = ENVIRONMENTS.filter((environment) => environment !== "dev");
 /** One environment's public address for one Worker. */
 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) => {
 	const { pattern, zone } = ctx.value;
 	if (pattern !== zone && !pattern.endsWith(`.${zone}`)) ctx.issues.push({
@@ -234,4 +292,4 @@ function originFor(environment, domains, env = ambientEnv()) {
 	return resolveOrigin(environment, domains, env[BASE_URL_VAR]).origin;
 }
 //#endregion
-export { DOMAIN_ENVIRONMENTS, LOCAL_ORIGIN, WorkerDomain, WorkerDomains, baseUrlFor, domainFor, featureOrigin, isPublicHostname, originFor, resolveOrigin };
+export { DOMAIN_ENVIRONMENTS, LOCAL_ORIGIN, WorkerDomain, WorkerDomains, baseUrlFor, domainFor, featureOrigin, isPublicHostname, originFor, publicHostnameProblem, resolveOrigin };

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

@@ -1 +1 @@
-{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../src/naming/environment.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,YAAY,YAAI,KAAK,EAAE,SAAS,EAAE,MAAM,CAAU,CAAC;AAEhE,wGAAwG;AACxG,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,WAAW,CAAC;AAErC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,YAAY,CAAC;AAE7C;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAKD,kHAAkH;AAClH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAExD;AAgBD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,QAAqE,CAAC;AAEvG;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIxD;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAmCzD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,YAAI,SAAS,EAAE,MAAM,CAAU,CAAC;AAEjE;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,oBAAoB,yBA2D9B,CAAC;AAEJ,sGAAsG;AACtG,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC"}
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../src/naming/environment.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,YAAY,YAAI,KAAK,EAAE,SAAS,EAAE,MAAM,CAAU,CAAC;AAEhE,wGAAwG;AACxG,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,WAAW,CAAC;AAErC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,YAAY,CAAC;AAE7C;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAKD,kHAAkH;AAClH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAExD;AAgBD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,QAAqE,CAAC;AAEvG;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIxD;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAmCzD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,YAAI,SAAS,EAAE,MAAM,CAAU,CAAC;AAEjE;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,oBAAoB,yBA2D9B,CAAC;AAEJ,sGAAsG;AACtG,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/naming/environment.js

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 import { PithyError, ValidationError } from "../error/pithyError.js";
+import { commandName } from "../cli/command.js";
 import { NAME_SEGMENT } from "./segment.js";
 import { z } from "zod";
 //#region src/naming/environment.ts
@@ -129,7 +130,7 @@ function assertValidEnvironment(name) {
 	if (startsWithFeatureMarker(name)) 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)) throw new ValidationError({
 		message: `"${name}" is ${name.length} characters. An environment stops at ${MAX_ENVIRONMENT_NAME}.`,

package/dist/naming/packageName.d.ts

@@ -0,0 +1,17 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+/**
+ * The package a bare specifier names: `@pithy-sh/payments` from `@pithy-sh/payments/src/capability`, and
+ * `stripe` from `stripe/lib/x` — **scope-aware, and the only copy in the kit (#709)**.
+ *
+ * There were five. Three took the first segment or two depending on a leading `@`; two took the first two
+ * segments whatever they were, which is right for every `@pithy-sh/*` name they were written against and
+ * wrong for the first unscoped dependency anyone passed them. A rule that small drifts precisely because
+ * nobody thinks it needs a home, so it has one. That it is the only copy is a gate, not a claim: `packages/cli/src/ci/packageOfCopies.test.ts` fails on any source that writes the rule out by hand, because the first migration left three behind and said it had not.
+ *
+ * Total, and deliberately unopinionated about what it is handed: a caller with a relative path, a `#`
+ * import or a URL gets the first segment back. Deciding whether a specifier is a package at all is the
+ * unresolved-import classifier's job (`error/unresolved.ts`), not this function's.
+ */
+export declare function packageOf(specifier: string): string;
+//# sourceMappingURL=packageName.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"packageName.d.ts","sourceRoot":"","sources":["../../src/naming/packageName.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAGnD"}

package/dist/naming/packageName.js

@@ -0,0 +1,22 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+//#region src/naming/packageName.ts
+/**
+* The package a bare specifier names: `@pithy-sh/payments` from `@pithy-sh/payments/src/capability`, and
+* `stripe` from `stripe/lib/x` — **scope-aware, and the only copy in the kit (#709)**.
+*
+* There were five. Three took the first segment or two depending on a leading `@`; two took the first two
+* segments whatever they were, which is right for every `@pithy-sh/*` name they were written against and
+* wrong for the first unscoped dependency anyone passed them. A rule that small drifts precisely because
+* nobody thinks it needs a home, so it has one. That it is the only copy is a gate, not a claim: `packages/cli/src/ci/packageOfCopies.test.ts` fails on any source that writes the rule out by hand, because the first migration left three behind and said it had not.
+*
+* Total, and deliberately unopinionated about what it is handed: a caller with a relative path, a `#`
+* import or a URL gets the first segment back. Deciding whether a specifier is a package at all is the
+* unresolved-import classifier's job (`error/unresolved.ts`), not this function's.
+*/
+function packageOf(specifier) {
+	const parts = specifier.split("/");
+	return specifier.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0] ?? specifier;
+}
+//#endregion
+export { packageOf };

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

@@ -1 +1 @@
-{"version":3,"file":"provisionScope.d.ts","sourceRoot":"","sources":["../../src/naming/provisionScope.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAEhE,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EAIzB,MAAM,WAAW,CAAC;AAInB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,QAAQ,CAAC;AAEvD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAoB,SAAQ,aAAa;IACxD,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;CAC1B;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,oBAAoB;IACnC,2GAA2G;IAC3G,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,oGAAoG;IACpG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B,6FAA6F;IAC7F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,aAAa,GAAG,MAAM,CAAC;IACpF;;;;;;;;;OASG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,MAAM,EAAE,oBAAoB,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChE;;;;;;;OAOG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,eAAe,GAAG,MAAM,CAAC;IAClE;;;;;;;;OAQG;IACH,QAAQ,CAAC,YAAY,EAAE,IAAI,CAAC,qBAAqB,EAAE,YAAY,CAAC,CAAC;CAClE;AAiBD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,mBAAmB,EACzB,MAAM,EAAE,mBAAmB,GAC1B,MAAM,CAAC;AACV,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,mBAAmB,EACzB,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAChC,MAAM,CAAC;AAsBV;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAKpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,cAAc,CA8BrF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,cAAc,CAiBtE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,oBAAoB,GAAG,MAAM,EAAE,CAY1G"}
+{"version":3,"file":"provisionScope.d.ts","sourceRoot":"","sources":["../../src/naming/provisionScope.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAEhE,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,mBAAmB,EAIzB,MAAM,WAAW,CAAC;AAInB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,QAAQ,CAAC;AAEvD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAoB,SAAQ,aAAa;IACxD,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;CAC1B;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,oBAAoB;IACnC,2GAA2G;IAC3G,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,oGAAoG;IACpG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B,6FAA6F;IAC7F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,aAAa,GAAG,MAAM,CAAC;IACpF;;;;;;;;;OASG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,MAAM,EAAE,oBAAoB,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChE;;;;;;;OAOG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,eAAe,GAAG,MAAM,CAAC;IAClE;;;;;;;;OAQG;IACH,QAAQ,CAAC,YAAY,EAAE,IAAI,CAAC,qBAAqB,EAAE,YAAY,CAAC,CAAC;CAClE;AAiBD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,mBAAmB,EACzB,MAAM,EAAE,mBAAmB,GAC1B,MAAM,CAAC;AACV,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,mBAAmB,EACzB,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAChC,MAAM,CAAC;AAsBV;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAKpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,cAAc,CA8BrF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,cAAc,CAiBtE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,oBAAoB,GAAG,MAAM,EAAE,CAY1G"}

package/dist/naming/provisionScope.js

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 import { InternalError, ValidationError } from "../error/pithyError.js";
+import { commandName } from "../cli/command.js";
 import { FEATURE_ENVIRONMENT, assertValidEnvironment, isFeatureMarker } from "./environment.js";
 import { kebab } from "./resource.js";
 import { featureResourceName, featureSecretEntryName, featureWorkerName } from "./feature.js";
@@ -93,7 +94,7 @@ function environmentScope(project, environment) {
 			if (isFeatureName(project, name)) throw new ValidationError({
 				message: `The ${environment} Worker "${name}" is named the way a feature's Worker is.`,
 				action: `Rename it in env.${environment}.name, or the Worker's top-level name, so it does not follow ${kebab(project)}- with f and a number.`,
-				detail: `${declared === void 0 ? "Composed by wrangler from the deploy name" : `Declared in env.${environment}.name`}. A feature's Worker is <project>-f<issue>-<slug>-<app>, and \`pithy feature destroy\` deletes it by that exact name.`
+				detail: `${declared === void 0 ? "Composed by wrangler from the deploy name" : `Declared in env.${environment}.name`}. A feature's Worker is <project>-f<issue>-<slug>-<app>, and \`${commandName("feature destroy")}\` deletes it by that exact name.`
 			});
 			return name;
 		},

package/dist/openapi/document.d.ts

@@ -0,0 +1,106 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Hono } from "hono";
+import { z } from "zod";
+/**
+ * **The OpenAPI contract, read off a composed app.**
+ *
+ * Nothing here is written by hand. A route's request schemas come from its `validate` middleware, its
+ * summary, verification and responses from its `describeRoute`, and both are found by walking
+ * `app.routes` — the same table Hono dispatches from. So the document describes exactly what the Worker
+ * serves, the adopter's own routes included, and a schema edit reaches it with no second step.
+ *
+ * Zod is already the source of truth for every request and response, and every field carries a
+ * `.describe()` (CLAUDE.md §Zod). `z.toJSONSchema` keeps those descriptions, which is what lets a client
+ * generated in Swift or Kotlin carry the same documentation as the TypeScript one.
+ *
+ * OpenAPI 3.1, whose schema dialect is JSON Schema 2020-12 — the dialect `z.toJSONSchema` writes — so
+ * every schema crosses unchanged.
+ */
+/** The OpenAPI version this module writes. */
+export declare const OPENAPI_VERSION = "3.1.0";
+/** One entry of a Hono app's route table: a method, a path and one handler. */
+export type RouterRoute = Hono["routes"][number];
+/** One capability's routes, as registered by its `routes` hook. Becomes one tag. */
+export interface RouteGroup {
+    /** The tag, normally the capability's name. */
+    readonly tag: string;
+    /** What the capability does, for the tag's description. */
+    readonly description?: string;
+    /** The routes it registered, in registration order. */
+    readonly routes: readonly RouterRoute[];
+}
+/** The document's `info` block. */
+export interface ContractInfo {
+    readonly title: string;
+    readonly version: string;
+    readonly description?: string;
+}
+/** A JSON Schema object, as `z.toJSONSchema` writes one. */
+export type JsonSchema = Record<string, unknown>;
+/** The subset of an OpenAPI 3.1 document this module writes. */
+export interface OpenApiDocument {
+    openapi: string;
+    info: ContractInfo;
+    tags: {
+        name: string;
+        description?: string;
+    }[];
+    paths: Record<string, Record<string, unknown>>;
+    components: {
+        schemas: Record<string, JsonSchema>;
+        responses: Record<string, unknown>;
+        securitySchemes: Record<string, unknown>;
+    };
+}
+/** A route that registered no `describeRoute`, so the contract can say nothing true about it. */
+export interface UndescribedRoute {
+    readonly method: string;
+    readonly path: string;
+}
+/** Hono's `/a/:id{[0-9]+}/*` as OpenAPI's `/a/{id}/{path}`. */
+export declare function openApiPath(path: string): string;
+/**
+ * `get` + `/leaderboard/{board}/top` → `getLeaderboardByBoardTop`. A parameter reads as `By<Name>`, so
+ * `/items/{id}` and `/items/id` do not meet. Stable, but not unique on its own — `/a-b` and `/a/b` still
+ * share one — so {@link openApiDocument} numbers a repeat rather than writing an invalid document.
+ */
+export declare function operationId(method: string, path: string): string;
+/** A Zod schema as JSON Schema, without the `$schema` key OpenAPI does not want inside a document. */
+export declare function jsonSchema(schema: z.ZodType, io: "input" | "output"): JsonSchema;
+/** Every route in these groups that registered no `describeRoute`. Empty is the contract being met. */
+export declare function undescribedRoutes(groups: readonly RouteGroup[]): UndescribedRoute[];
+/** How {@link openApiDocument} treats a route with no `describeRoute`. */
+export interface DocumentOptions {
+    /**
+     * `omit` (the default) leaves it out, which is right for the kit: {@link undescribedRoutes} keeps that
+     * set empty, so anything missing is a bug the gate names. `include` writes what the validators alone
+     * can say — the path, its parameters and body — marked `x-pithy-undescribed`, which is right for an
+     * adopter's own routes: a client generated from the contract still reaches them, and the mark says
+     * which ones to describe.
+     */
+    readonly undescribed?: "omit" | "include";
+}
+/**
+ * The OpenAPI document for these route groups. Undescribed routes are left out rather than guessed at,
+ * unless {@link DocumentOptions.undescribed} says otherwise; {@link undescribedRoutes} is the check that
+ * keeps that set empty.
+ */
+export declare function openApiDocument(info: ContractInfo, groups: readonly RouteGroup[], options?: DocumentOptions): OpenApiDocument;
+/** One schema property somewhere in the document that carries no `description`. */
+export interface UndescribedField {
+    /** A JSON pointer to the property, e.g. `/paths/~1leaderboard/get/responses/200/…/properties/rank`. */
+    readonly pointer: string;
+}
+/**
+ * Every object property and every parameter in the document without a description. The kit holds every
+ * Zod field to `.describe()`, and this is how that rule is checked on the wire shape a client actually
+ * generates from, rather than on the source it came from.
+ */
+export declare function undescribedFields(document: OpenApiDocument): UndescribedField[];
+/**
+ * The same sweep over any part of a contract document, from a JSON pointer: every object property and every
+ * OpenAPI parameter below `node` without a description. The AsyncAPI document runs it over its messages.
+ */
+export declare function undescribedFieldsIn(node: unknown, at: string): UndescribedField[];
+//# sourceMappingURL=document.d.ts.map

package/dist/openapi/document.d.ts.map

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