@pithy-sh/core 0.1.0

package/src/naming/domains.ts

@@ -0,0 +1,194 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { ENVIRONMENTS } from "./environment";
+
+/**
+ * Where a Worker answers, declared once per Worker per environment.
+ *
+ * ## The problem this replaces
+ *
+ * Nothing in `pithy.config.ts` described a Worker's address, so three commands each reconstructed it
+ * differently and none of them reconciled: `pithy env` scraped the first `routes` pattern out of
+ * `wrangler.jsonc`, `pithy email provision` and `pithy turnstile` read a hand-set `vars.BASE_URL`, and
+ * `pithy deploy` scraped the last URL wrangler happened to print. `email provision` refused to run
+ * without `vars.BASE_URL` while `pithy env` cheerfully printed a URL derived from routes, and nothing
+ * noticed when the two disagreed. Three answers to one question, in one CLI.
+ *
+ * So the address is declared, and everything else is generated from it — the `routes` entry with
+ * `custom_domain` and `zone_name`, and `vars.BASE_URL`. `BASE_URL` stays a wrangler var because the
+ * **Worker reads it at runtime**: `@pithy-sh/email` builds tracking and unsubscribe links against it and
+ * Turnstile binds its widget to that domain. What changes is that it is derived rather than hand-set and
+ * able to contradict the routes beside it.
+ *
+ * ## Per Worker, per environment
+ *
+ * Per Worker because each serves its own hostname. Per environment because `staging.api.example.com` and
+ * `api.example.com` are one Worker in two environments, and `env.<name>` stanzas in `wrangler.jsonc`
+ * replace rather than merge — so one declaration has to fan out to all of them.
+ *
+ * ## `dev` carries no domain
+ *
+ * Deliberately absent from the accepted keys. Local answers on `http://localhost:<port>` from the port
+ * the feature's `.dev.config.json` pinned at creation, and a domain there would be a second answer to a
+ * question the port allocator already answers. `requireManagedEnvironment` refuses `dev` for the same
+ * reason everywhere else.
+ */
+
+/** A hostname a Worker answers on. No scheme, no path, no port — wrangler's `routes` pattern is a host. */
+const HOSTNAME_PATTERN = /^(?!-)[a-z0-9-]{1,63}(?<!-)(\.(?!-)[a-z0-9-]{1,63}(?<!-))+$/;
+
+/** The environments a domain may be declared for — every managed one, never `dev`. */
+export const DOMAIN_ENVIRONMENTS = ENVIRONMENTS.filter((environment) => environment !== "dev");
+
+/** 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.",
+      ),
+  })
+  .describe("Where one Worker answers in one environment: the hostname, and the Cloudflare zone it sits under.")
+  .check((ctx) => {
+    // A pattern outside its own zone produces a `routes` entry Cloudflare refuses at deploy, with an
+    // error naming neither of the two values that disagree. Catching it here names both.
+    const { pattern, zone } = ctx.value;
+    if (pattern !== zone && !pattern.endsWith(`.${zone}`)) {
+      ctx.issues.push({
+        code: "custom",
+        input: ctx.value,
+        path: ["pattern"],
+        message: `The domain \`${pattern}\` is not inside the zone \`${zone}\`. A custom domain must sit on the zone it names — set \`zone\` to the registrable domain \`${pattern}\` belongs to.`,
+      });
+    }
+  });
+export type WorkerDomain = z.infer<typeof WorkerDomain>;
+
+/**
+ * A Worker's domains, keyed by environment.
+ *
+ * Every key optional: a project with no domain yet is legitimate, and so is one that has staging wired
+ * and production not. Adding one later is a config edit plus a deploy, never a rescaffold.
+ */
+export const WorkerDomains = z
+  .object({
+    staging: WorkerDomain.optional().describe("Where this Worker answers in `staging`, if it has a domain yet."),
+    prod: WorkerDomain.optional().describe("Where this Worker answers in `prod`, if it has a domain yet."),
+  })
+  .describe(
+    "Where this Worker answers, per environment. `dev` is absent by design — local runs on `http://localhost:<port>` from the port pinned in `.dev.config.json`. Everything else is generated from this: the `routes` entry with `custom_domain` and `zone_name`, and `vars.BASE_URL`.",
+  );
+export type WorkerDomains = z.infer<typeof WorkerDomains>;
+
+/**
+ * The declared domain for one environment, or null where none is declared (including every `dev`).
+ *
+ * `environment` may be `undefined`, which is what `compositionEnvironment()` answers when nothing stamped
+ * one. That is not a `dev` default — it is "this composition names no environment", and an environment
+ * nobody named has declared no domain, so the answer is the same `null` an undeclared one gets.
+ */
+export function domainFor(domains: WorkerDomains | undefined, environment: string | undefined): WorkerDomain | null {
+  if (!domains) return null;
+  if (environment === "staging") return domains.staging ?? null;
+  if (environment === "prod") return domains.prod ?? null;
+  return null;
+}
+
+/** The base URL a declared domain implies. Always `https` — a custom domain on Cloudflare is TLS-terminated. */
+export function baseUrlFor(domain: WorkerDomain): string {
+  return `https://${domain.pattern}`;
+}
+
+/**
+ * The origin an environment with no declared domain resolves to.
+ *
+ * **No port, and that is the whole design.** Local dev's port is assigned per Worker per run from the
+ * feature's reserved block, so it is the one address nobody can write down — `@pithy-sh/auth` resolves
+ * dev's base URL from the host the request arrived at for exactly that reason, and a config-time value
+ * could only ever be a stale guess at it. So this is a *placeholder that fails closed*: a link built
+ * against it goes nowhere, which is useless rather than harmful.
+ *
+ * Compare what it replaces. Every capability that made an adopter write an origin got production's
+ * written into staging, and the failure was never "the link is broken" — it was a staging deploy mailing
+ * real users magic links **into production**, an unsubscribe from a staging test unsubscribing that
+ * person in production, and a Checkout return landing a staging payer in production on an account that
+ * had bought nothing. A fallback that goes nowhere is the only one that cannot do any of that.
+ */
+export const LOCAL_ORIGIN = "http://localhost";
+
+/** An environment's public origin, and whether the declaration is where it came from. */
+export interface ResolvedOrigin {
+  /** The absolute origin — scheme and host, never a trailing slash. */
+  origin: string;
+  /** The hostname alone: a route pattern, and what Turnstile binds a widget to. */
+  hostname: string;
+  /** Whether `domains` declared it. `false` means {@link LOCAL_ORIGIN} was substituted. */
+  declared: boolean;
+}
+
+/**
+ * **Where is this Worker publicly reachable, in this environment?** — asked once, answered once.
+ *
+ * The two halves already existed ({@link domainFor} and {@link baseUrlFor}) and nothing composed them,
+ * so every caller that needed the answer did the two-step for itself and every *adopter* who needed it
+ * wrote a URL down. The first adopter's one Worker config carried `https://app.pithy.sh` three times —
+ * `auth.baseURL`, `email.baseUrl`, and the Stripe return URLs — each wrong for staging in its own way,
+ * each found on a different day. Fixing it inside one capability does not stop the next capability
+ * asking the same question, so the question gets one answer that anyone can call.
+ *
+ * **The fallback never reaches for another environment's origin.** An environment absent from `domains`
+ * is one that is not published, so it resolves to {@link LOCAL_ORIGIN} and nothing else. Falling back to
+ * production's is what the shape being replaced did, and it is the one behavior here that was actively
+ * dangerous rather than merely wrong.
+ *
+ * **A deployed environment must never *keep* that fallback**, and it is not this function's job to say
+ * so — `pithy deploy --env <name>` refuses an environment whose origin its config does not declare
+ * (#253), and `pithy doctor` reports it first. One rule in two halves: this one cannot invent another
+ * environment's origin, and deploy makes sure the placeholder never ships.
+ *
+ * **Not every origin should derive from this, and `controlplane.issuer` is the one to name.** That is an
+ * **identity**, not an address: a connection stores the issuer it was created with and verification
+ * checks that stored value, so a per-environment issuer would make a connection minted in staging
+ * unverifiable in production. That may be the better isolation, but it is a decision about trust rather
+ * than about reachability, and a helper whose job is "where am I reachable" must not sweep it up.
+ */
+export function resolveOrigin(environment: string | undefined, domains: WorkerDomains | undefined): ResolvedOrigin {
+  const domain = domainFor(domains, environment);
+  if (domain) return { origin: baseUrlFor(domain), hostname: domain.pattern, declared: true };
+  return { origin: LOCAL_ORIGIN, hostname: "localhost", declared: false };
+}
+
+/**
+ * The one line an adopter writes: this Worker's public origin for the environment it is running in.
+ *
+ * ```ts
+ * const DOMAINS = { staging: { … }, prod: { … } };
+ * const PUBLIC_ORIGIN = originFor(compositionEnvironment(), DOMAINS);
+ * ```
+ *
+ * That is the line `pithy init` scaffolds, so an adopter who never thinks about it gets it right and one
+ * who wants a literal can still write one. `compositionEnvironment()` is `string | undefined`, and it is
+ * taken as such rather than defaulted to `dev` at the call site: an unstamped composition has declared no
+ * domain either way, and a `?? "dev"` in every adopter's config would be a default nobody chose.
+ *
+ * Named for what it is rather than for who asked. The first adopter's own version was called
+ * `AUTH_BASE_URL`, which is part of why `email` and `payments` were missed for days: the constant read
+ * as auth's private business when it is the Worker's address, and every capability that needs an origin
+ * needs this one.
+ */
+export function originFor(environment: string | undefined, domains: WorkerDomains | undefined): string {
+  return resolveOrigin(environment, domains).origin;
+}

package/src/naming/environment.ts

@@ -0,0 +1,224 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { PithyError, ValidationError } from "../error/pithyError";
+import { NAME_SEGMENT } from "./segment";
+
+/**
+ * What an environment may be called, in one module.
+ *
+ * An environment name is not decoration: it sits in the middle of every Cloudflare name a project
+ * composes (`<project>-<env>-<thing>`), so its length is subtracted from every other segment's
+ * budget, and its characters have to be legal in every namespace Pithy writes into. Until this
+ * module existed, `--env` was a bare string that nothing checked — a fourteen-character environment
+ * quietly ate the room a project name had already been accepted against.
+ */
+
+/**
+ * The three first-class environments: local `dev`, `staging` for test users, `prod` for paid ones.
+ *
+ * **`prod`, not `production`.** The long form cost three characters of every project name, in a
+ * budget where thirty-three was the ceiling, and bought nothing a four-letter word does not say.
+ */
+export const ENVIRONMENTS = ["dev", "staging", "prod"] as const;
+
+/** One of Pithy's first-class environments. A custom environment is a `string`, and still validated. */
+export type Environment = (typeof ENVIRONMENTS)[number];
+
+/**
+ * The scope that sits beside the environments: one value shared by all of them.
+ *
+ * It occupies the same slot as an environment in a composed name, which is exactly why an
+ * environment may not be *called* `global` — a project would then have one set of names for two
+ * different scopes, and teardown could not tell them apart.
+ */
+export const GLOBAL_SCOPE = "global";
+
+/**
+ * The environment one branch gets — the `env.feature` stanza a feature's provisioning run writes into.
+ *
+ * **A legal environment name, and never a declared one.** Legal because it is a real wrangler stanza
+ * key, so every rule that governs a key governs it: seven characters, which is
+ * {@link MAX_ENVIRONMENT_NAME} exactly. Never declared because the two kinds of environment write to
+ * different files — a declared environment's ids are source, in the tracked `wrangler.jsonc`; a
+ * feature's are a build artifact under `.wrangler/`. A project that declared this name would own two
+ * files claiming one stanza, and the resolver that picks between them answers "generated" for this
+ * name — so a migrate would read bytes no provisioning run wrote.
+ *
+ * It lives here rather than beside the scope that uses it because it is first an environment name, and
+ * because {@link DeclaredEnvironments} has to refuse it: a constant defined downstream of the schema
+ * that rejects it would be a cycle.
+ */
+export const FEATURE_ENVIRONMENT = "feature";
+
+/**
+ * The longest an environment name may be — **the longest canonical one, `staging`**.
+ *
+ * This is a derivation input, not a preference: `WORKFLOW_DERIVED_PROJECT_NAME` and
+ * `FEATURE_DERIVED_PROJECT_NAME` are both computed against it, so every project name Pithy has ever
+ * accepted was accepted on the assumption that no environment exceeds it. Letting a custom
+ * environment run longer would retroactively shrink that cap — and a provisioned project cannot be
+ * renamed. So a longer environment is refused here, at the one place that can still say no.
+ *
+ * Read off {@link ENVIRONMENTS} rather than typed, so adding an environment cannot leave the two
+ * disagreeing.
+ */
+export const MAX_ENVIRONMENT_NAME = Math.max(...ENVIRONMENTS.map((environment) => environment.length));
+
+/**
+ * Is this a name an environment may carry?
+ *
+ * **Read raw, never kebabbed** — and that is the difference between this rule and the project rule.
+ * A project name is prose an adopter types once into `pithy.config.ts`, so `Acme Corp` is politely
+ * composed into `acme-corp`. An environment is an identifier repeated in `--env`, in
+ * `.dev.vars.<environment>`, and in a wrangler environment key; normalizing `Prod` to `prod` would
+ * make two spellings name one environment in some places and two in others.
+ */
+export function isValidEnvironment(name: string): boolean {
+  if (name === GLOBAL_SCOPE) return false;
+  return name.length <= MAX_ENVIRONMENT_NAME && NAME_SEGMENT.test(name);
+}
+
+/**
+ * Refuse a name no environment may carry, as a `ValidationError` — an environment comes from a flag
+ * or a config file, so it is a 400 with an action, never an internal fault.
+ *
+ * Three different mistakes get three different sentences, because "invalid environment" helps with
+ * none of them: `production` is the old spelling and gets the new one, a long name gets the number,
+ * and anything else gets the charset.
+ */
+export function assertValidEnvironment(name: string): void {
+  if (isValidEnvironment(name)) return;
+  if (name === "production") {
+    throw new ValidationError({
+      message: `"production" is not an environment name in Pithy.`,
+      action: "Use `prod`.",
+      detail: `An environment stops at ${MAX_ENVIRONMENT_NAME} characters, the length of the longest of ${ENVIRONMENTS.join(", ")}.`,
+    });
+  }
+  if (name === GLOBAL_SCOPE) {
+    throw new ValidationError({
+      message: `"${GLOBAL_SCOPE}" is a scope, not an environment.`,
+      action: `Name the environment one of ${ENVIRONMENTS.join(", ")}.`,
+      detail: `${GLOBAL_SCOPE} occupies the environment slot of a composed name for values shared across every environment.`,
+    });
+  }
+  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}.`,
+      action: `Use one of ${ENVIRONMENTS.join(", ")}, or a shorter name.`,
+      detail: `Every project-name budget is derived against a ${MAX_ENVIRONMENT_NAME}-character environment, and a provisioned project cannot be renamed.`,
+    });
+  }
+  throw new ValidationError({
+    message: `"${name}" can't be an environment name.`,
+    action: "Use lowercase letters, digits, and single hyphens, starting with a letter.",
+    detail: `An environment is used verbatim in Cloudflare resource names, so it must match ${NAME_SEGMENT.source}.`,
+  });
+}
+
+/**
+ * The environments a project has when it declares nothing: `staging` for test users, `prod` for paid ones.
+ *
+ * The same two {@link ENVIRONMENTS} names minus `dev`, and the same two the starter scaffolded from a
+ * hardcoded template before anything could say otherwise — so a project that never opens this setting
+ * gets exactly what it got before.
+ */
+export const DEFAULT_ENVIRONMENTS = ["staging", "prod"] as const;
+
+/**
+ * The local environment. Never declared: it is the top-level wrangler stanza, and it always exists.
+ *
+ * Exported because "always exists and is never declared" is a fact other code has to act on, not only a
+ * rule this schema enforces. Anything deriving something over *every* environment a project has must add
+ * this one itself — {@link DeclaredEnvironments} will never hand it over — and a caller spelling `"dev"`
+ * inline is a caller that can spell it differently.
+ */
+export const LOCAL_ENVIRONMENT = "dev";
+
+/**
+ * **The set of deployed environments a project has**, declared once in the root `pithy.config.ts`.
+ *
+ * Until this existed a project never said. The set lived only as `env.<name>` stanzas in each Worker's
+ * `wrangler.jsonc` — per Worker, so two Workers in one project could disagree and nothing reconciled them
+ * — while `ManagedEnvironment` held a closed enum of two and `seed.productionEnvironments` invited a
+ * project to name a third. An adopter adding `env.live` got `pithy migrate --env live` working and
+ * `pithy secrets provision` skipping it in silence, because the three answers were never the same answer.
+ *
+ * **Ordered, and the order is meaningful.** It is the order provisioning walks — least-production first,
+ * so a mistake is made in staging before it is made in prod — and the last entry is the one a
+ * `global` account-level secret is written through (see `@pithy-sh/secrets`'s `resolveWriteTargets`).
+ * `["staging", "prod"]` therefore behaves exactly as the hardcoded pair did.
+ *
+ * **`dev` is not declarable.** It is local, it is the top-level wrangler stanza rather than an `env.dev`,
+ * and it resolves from Miniflare rather than an account — so a project always has it and provisioning
+ * never has it. Declaring it would ask a deploy to happen for an environment that never deploys.
+ *
+ * **Nothing is renamed by editing this.** `<project>-<env>-<thing>` is computed from the declaration and
+ * never stored, so changing a name here orphans everything already provisioned under the old one, exactly
+ * as renaming `name` does. `pithy doctor` reports the change rather than applying it.
+ */
+export const DeclaredEnvironments = z
+  .array(
+    z
+      .string()
+      .describe(
+        "One deployed environment's name, used verbatim in the middle of every Cloudflare name the project composes and in each Worker's `env.<name>` wrangler stanza.",
+      ),
+  )
+  .check((ctx) => {
+    if (ctx.value.length === 0) {
+      ctx.issues.push({
+        code: "custom",
+        input: ctx.value,
+        message: `Declare at least one environment. A project with none can never deploy — ${DEFAULT_ENVIRONMENTS.join(" and ")} is the default.`,
+      });
+    }
+    const seen = new Set<string>();
+    for (const name of ctx.value) {
+      if (name === LOCAL_ENVIRONMENT) {
+        ctx.issues.push({
+          code: "custom",
+          input: ctx.value,
+          message: `"${LOCAL_ENVIRONMENT}" is local and always present, so it is never declared. List only the environments this project deploys.`,
+        });
+        continue;
+      }
+      if (name === FEATURE_ENVIRONMENT) {
+        ctx.issues.push({
+          code: "custom",
+          input: ctx.value,
+          message: `"${FEATURE_ENVIRONMENT}" is the environment a branch gets, and its config is generated rather than committed. Declaring it would give one stanza two owners.`,
+        });
+        continue;
+      }
+      if (seen.has(name)) {
+        ctx.issues.push({
+          code: "custom",
+          input: ctx.value,
+          message: `"${name}" is declared twice. One environment is one set of Cloudflare names.`,
+        });
+        continue;
+      }
+      seen.add(name);
+      // The naming rule is `assertValidEnvironment`'s, not a second copy of it — a declaration that
+      // core's namer would refuse must be refused in the declaration's own sentence, or a project could
+      // write down an environment nothing could ever provision a resource for.
+      try {
+        assertValidEnvironment(name);
+      } catch (error) {
+        ctx.issues.push({
+          code: "custom",
+          input: ctx.value,
+          message: error instanceof PithyError ? error.payload.message : `"${name}" can't be an environment name.`,
+        });
+      }
+    }
+  })
+  .describe(
+    "Every deployed environment this project has, in the order provisioning walks them — least-production first. Declared once in the root pithy.config.ts, because the set cannot be per-Worker. `dev` is never listed: it is local and always present.",
+  );
+
+/** Every deployed environment a project has. Same name as its schema, as every Zod object here is. */
+export type DeclaredEnvironments = z.output<typeof DeclaredEnvironments>;

package/src/naming/feature.ts

@@ -0,0 +1,162 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { ValidationError } from "../error/pithyError";
+import { MAX_ISSUE_DIGITS, NAMESPACE_LIMITS } from "./limits";
+import { assertValidProjectName, fitSegment, kebab } from "./resource";
+
+/**
+ * The names a feature environment provisions under: `<project>-f<issue>-<slug>-<binding>-<kind>` for a
+ * resource, `<project>-f<issue>-<slug>-<worker>` for a Worker script.
+ *
+ * **No environment segment, and no Worker segment.** A feature *is* an environment, and two Workers that
+ * declare the same binding are meant to share one resource — so the binding name, not the topology, is
+ * where sharing is expressed.
+ *
+ * Every name here is **derived and recomputed**, never stored: `provision` and `destroy` both compute the
+ * same string from `(identity, binding, kind)`, which is what lets teardown reconcile exactly rather than
+ * scan a prefix a hyphenated sibling slug could ambiguously match. That is also why these names
+ * **truncate** where a capability's Workflow refuses: a feature name addresses nothing that outlives the
+ * feature, and failing a CI run because a branch slug was long would be the worse failure.
+ *
+ * It lives in `core`, beside the rest of the naming rule, so the CLI and the facade compose one
+ * 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";
+
+/** Every feature resource kind, for tests and for callers that enumerate. */
+export const FEATURE_RESOURCE_KINDS: readonly FeatureResourceKind[] = ["d1", "kv", "r2"];
+
+/** The identity of a feature — everything a feature name is derived from. */
+export interface FeatureIdentity {
+  /** The project name, from the root `pithy.config.ts` (e.g. `acme`). */
+  project: string;
+  /** The issue number as a string (e.g. `69`). Digits only, up to {@link MAX_ISSUE_DIGITS}. */
+  issue: string;
+  /** The kebab-case feature slug, from the branch (e.g. `media-cli`). */
+  slug: string;
+}
+
+/** Below this the slug segment isn't worth keeping legible; the trailing segment is truncated to give it room. */
+const MIN_SLUG_BUDGET = 3;
+
+/**
+ * Refuse an issue number the budgets were not derived against.
+ *
+ * `MAX_ISSUE_DIGITS` is a term in {@link FEATURE_DERIVED_PROJECT_NAME}, so an eight-digit issue would
+ * quietly spend a character every project name was already accepted against. It is also the cheapest
+ * possible check that the value is an issue number at all — `featureResourceName` used to interpolate
+ * whatever string it was handed straight into a Cloudflare name.
+ */
+function assertIssue(issue: string): void {
+  if (new RegExp(`^[0-9]{1,${MAX_ISSUE_DIGITS}}$`).test(issue)) return;
+  throw new ValidationError({
+    message: `"${issue}" is not an issue number.`,
+    action: `Use the issue's digits, up to ${MAX_ISSUE_DIGITS} of them.`,
+    detail: `Feature resource names reserve ${MAX_ISSUE_DIGITS} digits, and every project-name budget is derived against that.`,
+  });
+}
+
+/** The `<project>-f<issue>` head both feature shapes share, with the project held to the one project rule. */
+function head(identity: FeatureIdentity): string {
+  assertValidProjectName(identity.project);
+  assertIssue(identity.issue);
+  return `${kebab(identity.project)}-f${identity.issue}`;
+}
+
+/**
+ * Fit `<head>-<slug>-<tail><fixed>` into `budget`, truncating the slug first and the tail only if the
+ * tail is what is eating the name. `fixed` is never touched — it carries the kind suffix, which is the
+ * only thing telling a `DB` bucket from a `DB` database.
+ *
+ * Deterministic in its inputs and hash-disambiguated on both variable segments, so two long inputs
+ * sharing a prefix still produce two different names.
+ */
+function composeFeatureName(headSegment: string, slug: string, tail: string, fixed: string, budget: number): string {
+  for (const [role, value] of [
+    ["slug", slug],
+    ["binding or worker", tail],
+  ] as const) {
+    if (value) continue;
+    // An empty segment composed `acme-f69--db-d1`, or a name ending in a dash. Neither is a legal
+    // bucket or script name, and both used to come out of here without a word.
+    throw new ValidationError({
+      message: `A feature resource name needs a ${role}.`,
+      action: "Use letters, digits, and hyphens — something that survives kebabbing.",
+      detail: `composeFeatureName received an empty ${role} segment for "${headSegment}".`,
+    });
+  }
+
+  const inner = budget - fixed.length;
+  let tailSegment = tail;
+  let slugBudget = inner - headSegment.length - 1 - (1 + tailSegment.length);
+
+  if (slugBudget < MIN_SLUG_BUDGET) {
+    // The tail is eating the name — truncate it too, reserving the slug its minimum.
+    const tailBudget = inner - headSegment.length - 1 - MIN_SLUG_BUDGET - 1;
+    tailSegment = fitSegment(tailSegment, Math.max(1, tailBudget));
+    slugBudget = inner - headSegment.length - 1 - (1 + tailSegment.length);
+  }
+
+  return `${headSegment}-${fitSegment(slug, Math.max(1, slugBudget))}-${tailSegment}${fixed}`;
+}
+
+/**
+ * The full Cloudflare resource name for a feature's binding — `<project>-f<issue>-<slug>-<binding>-<kind>`.
+ *
+ * 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
+ * feature that provisions a bucket and a database wants them recognizably the same name.
+ */
+export function featureResourceName(identity: FeatureIdentity, binding: string, kind: FeatureResourceKind): string {
+  return composeFeatureName(
+    head(identity),
+    kebab(identity.slug),
+    kebab(binding),
+    `-${kind}`,
+    NAMESPACE_LIMITS.r2.maxLength,
+  );
+}
+
+/**
+ * The CF Secrets Store entry name holding one of a feature's **environment-scoped** secrets —
+ * `<project>-f<issue>-<slug>-<secret>`.
+ *
+ * A Cloudflare account has one Secrets Store, flat and unpartitionable, so the entry name is the only
+ * partition there is. A feature therefore needs its own names for the same reason it needs its own
+ * database: without them a branch would adopt staging's master key, and its teardown would delete it.
+ *
+ * Held to the **Secrets Store** limit rather than R2's 63, like every other entry name — an entry has
+ * no documented Cloudflare cap, and holding it to the strictest kind's would hash
+ * `secrets-encryption-keys` down to nothing for no reason.
+ *
+ * A `global` secret is not named here at all: it is one account-level value every environment binds,
+ * so a feature binds the project's `<project>-global-<secret>` rather than minting a second copy.
+ */
+export function featureSecretEntryName(identity: FeatureIdentity, secret: string): string {
+  return composeFeatureName(
+    head(identity),
+    kebab(identity.slug),
+    kebab(secret),
+    "",
+    NAMESPACE_LIMITS.secretEntry.maxLength,
+  );
+}
+
+/**
+ * The Worker **script name** for one of a feature's workers — `<project>-f<issue>-<slug>-<worker>`.
+ *
+ * This is the name the feature's Workers deploy under, and therefore the name a sibling's `service`
+ * binding must target, so RPC inside a feature environment reaches that feature's deployment rather than
+ * production's.
+ *
+ * Held to the **Worker rule** ({@link NAMESPACE_LIMITS.worker}), which is the bug this used to have: it
+ * floored the slug at one character and never touched the worker segment, so it ran unbounded — 69
+ * characters for a worker called `collaboration-realtime-gateway`, 109 for a 70-character one. `apps/<name>`
+ * has a charset rule and no length rule, so nothing upstream was going to stop it either.
+ */
+export function featureWorkerName(identity: FeatureIdentity, worker: string): string {
+  return composeFeatureName(head(identity), kebab(identity.slug), kebab(worker), "", NAMESPACE_LIMITS.worker.maxLength);
+}