@pithy-sh/core 0.1.0

package/src/naming/limits.ts

@@ -0,0 +1,223 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { MAX_ENVIRONMENT_NAME } from "./environment";
+
+/**
+ * What Cloudflare will actually accept as a name, per namespace — and, where it publishes nothing,
+ * what Pithy chooses instead.
+ *
+ * Pithy used to hold one number, 63, against every namespace it writes into, justified as "R2's
+ * cap". That is true of R2 and of nothing else. It over-truncated a KV title by a factor of eight
+ * and truncated D1 databases, Secrets Store entries, and API token labels against limits that do
+ * not exist — `secrets-encryption-keys` came out of it as `secrets-encryp-91c2e9`, hashed for
+ * nothing. A truncated name is not merely ugly: it is the name teardown must recompute exactly, and
+ * the name a human has to recognize in a dashboard listing that cannot be filtered.
+ *
+ * Every row below carries its source. `cloudflare` means the number is documented (limits page,
+ * OpenAPI schema, or wrangler's own constant, verified 2026-07-31); `pithy` means Cloudflare
+ * publishes no cap and this is our ceiling, chosen and stated as ours.
+ */
+
+/** Where a limit comes from — Cloudflare's documentation, or Pithy's own judgment. */
+export type LimitSource = "cloudflare" | "pithy";
+
+/**
+ * What to do with a name that will not fit.
+ *
+ * **`refuse`** where the name is a durable address: a Workflow (renaming orphans every running
+ * instance), a Worker script (renaming orphans the deployment and every `service` binding pointing
+ * at it), a Vectorize index (renaming orphans the vectors — they cannot be re-embedded for free).
+ * A build error naming the limit is strictly better than a silent rename.
+ *
+ * **`truncate`** where Pithy recomputes the name from the same inputs on every command — a D1
+ * database, a KV namespace, a bucket, a secret entry, a token. Truncation is deterministic and
+ * hash-disambiguated, so provision and teardown still agree, and a failed CI run is avoided.
+ */
+export type OverflowPolicy = "refuse" | "truncate";
+
+/** One namespace's rule: how long a name may be, and what happens when it would be longer. */
+export interface NamespaceLimit {
+  /** How an error message names this namespace, e.g. `an R2 bucket name`. */
+  readonly label: string;
+  /** The longest name the namespace accepts. Pithy composes ASCII only, so characters are bytes. */
+  readonly maxLength: number;
+  /** The shortest name the namespace accepts. Only R2 states one; everywhere else it is 1. */
+  readonly minLength: number;
+  /** What happens to a name that would exceed {@link maxLength}. */
+  readonly policy: OverflowPolicy;
+  /** Whether {@link maxLength} is Cloudflare's number or Pithy's. */
+  readonly source: LimitSource;
+}
+
+/**
+ * Pithy's ceiling for a namespace Cloudflare does not cap — D1 database names, Secrets Store
+ * entries, API token labels.
+ *
+ * **This is our number, not Cloudflare's.** No published cap is not the same as no cap: a name is
+ * read by humans in unfilterable listings, echoed in CLI output, and pasted into wrangler configs,
+ * so it needs an end. 128 is twice the longest limit Cloudflare does publish (64) and roughly twice
+ * the longest name Pithy can compose today, which leaves room for a capability with a long tail
+ * without ever reaching for the truncator.
+ */
+export const MAX_PITHY_NAME = 128;
+
+/**
+ * The rule per namespace. Read it, do not re-derive it — a limit enforced in two places eventually
+ * disagrees with itself, and the number an error quotes must be the number the check used.
+ */
+export const NAMESPACE_LIMITS = {
+  /**
+   * A Workflow name: 64 characters, `^[a-zA-Z0-9_][a-zA-Z0-9-_]*$`. Documented on the Workflows
+   * limits page, `maxLength: 64` in the OpenAPI schema, and `MAX_WORKFLOW_NAME_LENGTH` in wrangler.
+   */
+  workflow: { label: "a Workflow name", maxLength: 64, minLength: 1, policy: "refuse", source: "cloudflare" },
+  /**
+   * A Worker script name: 255 in general, **63 once workers.dev is on**, alphanumeric and dashes
+   * with no leading or trailing dash. Pithy holds the 63: it is the only number that stays true
+   * after an adopter enables a workers.dev subdomain, and a script cannot be renamed afterwards.
+   * Deliberately one *less* than the Workflow cap — they are different resources with different
+   * numbers, and collapsing them would loosen this one.
+   */
+  worker: { label: "a Worker script name", maxLength: 63, minLength: 1, policy: "refuse", source: "cloudflare" },
+  /**
+   * An R2 bucket: 3–63 characters, lowercase letters, digits and hyphens, and it must **start and
+   * end alphanumeric**. The one namespace where 63 was always the right answer.
+   */
+  r2: { label: "an R2 bucket name", maxLength: 63, minLength: 3, policy: "truncate", source: "cloudflare" },
+  /**
+   * A Vectorize index: 64 bytes, `^([a-z]+[a-z0-9_-]*[a-z0-9]+)$` — it must start with a letter,
+   * which the project rule already guarantees. Refused rather than truncated because a renamed
+   * index is an empty index until everything is re-embedded.
+   */
+  vectorizeIndex: {
+    label: "a Vectorize index name",
+    maxLength: 64,
+    minLength: 2,
+    policy: "refuse",
+    source: "cloudflare",
+  },
+  /**
+   * A KV namespace title: 512 characters, no pattern at all — spaces and mixed case are accepted
+   * (`workers-kv_namespace_title.maxLength` in the OpenAPI schema). Pithy still composes a kebab
+   * title, for the same reason it composes every other name the same way; what changed is that it
+   * no longer hashes one at 63.
+   */
+  kv: { label: "a KV namespace title", maxLength: 512, minLength: 1, policy: "truncate", source: "cloudflare" },
+  /**
+   * A D1 database name: `^[a-zA-Z0-9][a-zA-Z0-9_-]*$` in the OpenAPI schema, and **no documented
+   * length cap** — the limits page has no row for it. So the ceiling here is {@link MAX_PITHY_NAME}.
+   */
+  d1: { label: "a D1 database name", maxLength: MAX_PITHY_NAME, minLength: 1, policy: "truncate", source: "pithy" },
+  /**
+   * A Secrets Store entry name: "cannot contain spaces", wrangler enforces `/^[A-z0-9-_]+$/`, and
+   * **no documented length cap**. Ours, therefore — {@link MAX_PITHY_NAME}.
+   */
+  secretEntry: {
+    label: "a Secrets Store entry name",
+    maxLength: MAX_PITHY_NAME,
+    minLength: 1,
+    policy: "truncate",
+    source: "pithy",
+  },
+  /**
+   * A Cloudflare API token name: a free-text label with **no documented cap**. Ours —
+   * {@link MAX_PITHY_NAME} — and it matters least of all, since nothing addresses a token by name.
+   */
+  apiToken: {
+    label: "a Cloudflare API token name",
+    maxLength: MAX_PITHY_NAME,
+    minLength: 1,
+    policy: "truncate",
+    source: "pithy",
+  },
+} as const satisfies Record<string, NamespaceLimit>;
+
+/** Every namespace the naming facade can compose into. */
+export type Namespace = keyof typeof NAMESPACE_LIMITS;
+
+/**
+ * The longest `<capability>-<job>` tail any capability registry declares today. Read off the
+ * registries, not guessed: `media-audio-transcribe` and `media-video-transcribe` are both 22, ahead
+ * of `payments-reconcile` (18), `vector-reprocess` (16), `support-classify` (16), `email-schedule`
+ * (14), `secrets-rotate` (14), `storage-sweep` (13), `testers-daily` (13).
+ *
+ * {@link WORKFLOW_DERIVED_PROJECT_NAME} is derived against it, so the two move together — and
+ * `workflowScriptName` refuses a longer tail rather than letting a new capability silently
+ * invalidate the project-name cap every existing project was accepted under.
+ */
+export const MAX_CAPABILITY_JOB = "media-audio-transcribe".length;
+
+/**
+ * Digits a feature's issue number may carry. Six — `f999999`, just under a million open issues in one
+ * repository, which nothing this toolkit will serve is going to exhaust.
+ *
+ * The count is not free: every digit reserved here costs one character of **every** adopter's project
+ * name, because {@link FEATURE_DERIVED_PROJECT_NAME} is computed against it and a project name cannot
+ * be changed once anything is provisioned. Seven digits would buy ten million issues nobody asked for
+ * and charge every project a character for them.
+ */
+export const MAX_ISSUE_DIGITS = 6;
+
+/**
+ * The slug length a feature resource name keeps verbatim at the worst legal project name.
+ *
+ * Twelve, because that is where a feature slug stops being readable in a listing: below it,
+ * `fitSegment` has to fall back to a short head plus a six-hex disambiguator, and
+ * `acme-f95-medi-8f21c4-db-d1` tells a human nothing about which branch owns the database.
+ */
+export const MIN_LEGIBLE_SLUG = 12;
+
+/**
+ * The binding length a feature resource name keeps verbatim at the worst legal project name.
+ *
+ * Also twelve — `MEDIA_BUCKET`, `SESSIONS`, `CACHE`, `ASSETS`, `DB`, `ROOMS` all fit. It is
+ * deliberately **not** the longest binding Pithy declares (`EMAIL_SUPPRESSIONS`, 18): reserving
+ * that would cost every adopter six characters of project name to protect a purely cosmetic
+ * property, since a longer binding truncates deterministically and stays unique through its hash,
+ * and teardown recomputes the name rather than matching a prefix.
+ */
+export const MIN_VERBATIM_BINDING = 12;
+
+/** The longest feature resource kind — `d1`, `kv`, `r2` are all two characters. `feature.test.ts` pins it. */
+export const MAX_FEATURE_KIND = 2;
+
+/**
+ * What the longest Workflow name leaves a project.
+ *
+ * ```
+ *     64   a Workflow name (NAMESPACE_LIMITS.workflow)
+ *   -  1   the hyphen before the environment
+ *   -  7   the longest environment, `staging` (MAX_ENVIRONMENT_NAME)
+ *   -  1   the hyphen before the tail
+ *   - 22   the longest <capability>-<job>, `media-audio-transcribe`
+ *   ----
+ *     33
+ * ```
+ */
+export const WORKFLOW_DERIVED_PROJECT_NAME =
+  NAMESPACE_LIMITS.workflow.maxLength - 1 - MAX_ENVIRONMENT_NAME - 1 - MAX_CAPABILITY_JOB;
+
+/**
+ * What the longest feature resource name leaves a project — `<project>-f<issue>-<slug>-<binding>-<kind>`,
+ * against R2's 63 (the strictest of the three kinds a feature provisions, and the same number a
+ * feature Worker script gets).
+ *
+ * ```
+ *     63   an R2 bucket name (NAMESPACE_LIMITS.r2)
+ *   -  2   `-f`
+ *   -  6   the issue number, six digits — `f999999` (MAX_ISSUE_DIGITS)
+ *   - 13   `-` + a legible slug (MIN_LEGIBLE_SLUG)
+ *   - 13   `-` + a binding kept whole (MIN_VERBATIM_BINDING)
+ *   -  3   `-` + the kind, `d1` | `kv` | `r2`
+ *   ----
+ *     26
+ * ```
+ */
+export const FEATURE_DERIVED_PROJECT_NAME =
+  NAMESPACE_LIMITS.r2.maxLength -
+  2 -
+  MAX_ISSUE_DIGITS -
+  (1 + MIN_LEGIBLE_SLUG) -
+  (1 + MIN_VERBATIM_BINDING) -
+  (1 + MAX_FEATURE_KIND);

package/src/naming/provisionScope.ts

@@ -0,0 +1,143 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { assertValidEnvironment, FEATURE_ENVIRONMENT, GLOBAL_SCOPE } from "./environment";
+import {
+  type FeatureIdentity,
+  type FeatureResourceKind,
+  featureResourceName,
+  featureSecretEntryName,
+  featureWorkerName,
+} from "./feature";
+import { resourceNames } from "./resourceNames";
+
+/**
+ * **What a provisioning run names its resources, and which `env.<name>` stanza it writes them into —
+ * as one object, never two arguments.**
+ *
+ * Provisioning was specified for ephemeral feature environments and parameterized by `--env` before it
+ * was generalized to named ones. That left the namer and the target stanza as independent inputs, and
+ * A feature's namer with a declared environment beside it was the reachable consequence: it composed
+ * `<project>-f<issue>-<slug>-db` and wrote it in as `staging`'s `DB`. Nothing refused it, the ids went
+ * into a checked-in `wrangler.jsonc`, and a remote migrate ran against them.
+ *
+ * A guard against that combination would be a list of forbidden pairs. This is the invariant instead:
+ * **a scope is chosen once, and it carries both halves.** There is no call path that takes an
+ * environment name and a naming scheme separately, so there is no pair left to get wrong.
+ *
+ * Two scopes exist, and they are the two kinds of environment a project has:
+ *
+ * - {@link environmentScope} — a **declared** environment (`staging`, `prod`, whatever the root
+ *   `pithy.config.ts` lists). Names are `<project>-<env>-<thing>`, the rule every other namer in the
+ *   kit follows, so the environment segment of a name is always the stanza the name lives in.
+ * - {@link featureScope} — one branch's **ephemeral** environment. Names are
+ *   `<project>-f<issue>-<slug>-<thing>`, with no environment segment because a feature *is* an
+ *   environment, and the `f<issue>` marker is what teardown recomputes and what keeps a feature's
+ *   database from ever being mistaken for a deployed one's.
+ */
+
+/**
+ * Whether a secret's value differs per environment or is one value every environment binds.
+ *
+ * The same two words `@pithy-sh/secrets`' `SecretScope` uses, restated here as a literal union rather
+ * than imported: core carries the secret-registry *seam* and not the package, for the same reason
+ * `SecretRegistryEntrySeam` types `backend` as a `string`.
+ */
+export type SecretNameScope = "environment" | "global";
+
+/** Where a provisioning run's resources are named, and where their ids are written. */
+export interface ProvisionScope {
+  /** The `env.<stanza>` key in each Worker's config that this scope's ids are written into. */
+  readonly stanza: string;
+  /**
+   * **Are this scope's ids source, or a build artifact?**
+   *
+   * The same provisioning step produces both, and the difference is not cosmetic. A declared
+   * environment's ids are long-lived facts about the repository: they belong in the tracked
+   * `wrangler.jsonc`, under review, in a pull request a human reads. A feature's are facts about one
+   * job — the branch is deleted, the resources are destroyed, and the ids name nothing afterwards.
+   *
+   * Writing a feature's into the tracked file was correct as designed *in CI*, where the checkout is
+   * throwaway, and an expectation everywhere else: a developer's worktree carried a modified tracked
+   * file they never edited, with no note saying it must not be committed, and `git add -A` put ids for
+   * deleted resources onto `main`. So a build artifact goes somewhere untracked instead, and the
+   * question "which is this?" is answered here, once, by the same object that answers "what is it
+   * called?" and "which stanza does it go in?" — because those three answers have to agree.
+   */
+  readonly source: boolean;
+  /** This scope's Cloudflare name for a provisionable binding. */
+  resource(binding: string, kind: FeatureResourceKind): string;
+  /** The script name a Worker deploys under in this scope. */
+  worker(worker: string): string;
+  /**
+   * This scope's CF Secrets Store entry name for a declared secret.
+   *
+   * A `global` secret is the one name that does **not** take the scope's segment: it is a single
+   * account-level value every environment binds, so every scope resolves it to the project's
+   * `<project>-global-<secret>`. Scoping it would mint a second copy of a value defined as one.
+   */
+  secretEntry(secret: string, secretScope: SecretNameScope): string;
+}
+
+/** The wrangler binding array a resource kind's name is composed for. */
+const KIND_NAMER: Record<FeatureResourceKind, "d1" | "kv" | "r2"> = { d1: "d1", kv: "kv", r2: "r2" };
+
+/**
+ * The one branch every scope shares: a `global` secret resolves to the project's single
+ * `<project>-global-<secret>` entry, and everything else to the scope's own name for it.
+ *
+ * Written once here rather than in each scope, because "global is not scoped" is a property of the
+ * secret and not of the environment asking — and two copies of it is how one of them would drift.
+ */
+function secretEntryName(project: string, secret: string, secretScope: SecretNameScope, scoped: () => string): string {
+  if (secretScope === GLOBAL_SCOPE) return resourceNames(project).global.secretEntry(secret);
+  return scoped();
+}
+
+/**
+ * A declared environment's scope — `staging`, `prod`, or whatever the root `pithy.config.ts` lists.
+ *
+ * The environment is validated here, once, before a single name exists: it is the middle segment of
+ * every name below, so an illegal one must fail before anything is created rather than at the fourth
+ * getter that happened to use it.
+ *
+ * **A Worker's script name is wrangler's own, `<script>-<env>`, deliberately.** It is the one name here
+ * that is not `<project>-<env>-<thing>`, because `wrangler deploy --env staging` has always appended the
+ * environment to the top-level `name` — so every project that ever deployed is already at that address.
+ * A Worker script is a `refuse`-policy namespace precisely because renaming one orphans the deployment
+ * and every `service` binding pointing at it; composing a "more correct" name here would do exactly
+ * that, silently, on the next deploy. The name is written out rather than left implicit so a service
+ * binding and a deploy agree on one string that is in the file.
+ */
+export function environmentScope(project: string, environment: string): ProvisionScope {
+  assertValidEnvironment(environment);
+  const names = resourceNames(project).env(environment);
+  return {
+    stanza: environment,
+    // Long-lived ids for an environment the project ships to: reviewed, committed, kept.
+    source: true,
+    resource: (binding, kind) => names[KIND_NAMER[kind]](binding),
+    worker: (worker) => `${worker}-${environment}`,
+    secretEntry: (secret, secretScope) =>
+      secretEntryName(project, secret, secretScope, () => names.secretEntry(secret)),
+  };
+}
+
+/**
+ * One feature's scope — the ephemeral environment a branch gets, named from the branch rather than from
+ * an environment.
+ *
+ * Its stanza is {@link FEATURE_ENVIRONMENT} and nothing else, which is what makes a feature's resources
+ * in a declared environment's stanza unexpressible rather than merely discouraged.
+ */
+export function featureScope(identity: FeatureIdentity): ProvisionScope {
+  return {
+    stanza: FEATURE_ENVIRONMENT,
+    // One job's ids, for resources `destroy` deletes. Never a tracked file.
+    source: false,
+    resource: (binding, kind) => featureResourceName(identity, binding, kind),
+    worker: (worker) => featureWorkerName(identity, worker),
+    secretEntry: (secret, secretScope) =>
+      secretEntryName(identity.project, secret, secretScope, () => featureSecretEntryName(identity, secret)),
+  };
+}

package/src/naming/resource.ts

@@ -0,0 +1,266 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { InternalError, ValidationError } from "../error/pithyError";
+import { MAX_ENVIRONMENT_NAME } from "./environment";
+import {
+  FEATURE_DERIVED_PROJECT_NAME,
+  MAX_CAPABILITY_JOB,
+  NAMESPACE_LIMITS,
+  WORKFLOW_DERIVED_PROJECT_NAME,
+} from "./limits";
+import { NAME_SEGMENT } from "./segment";
+
+/**
+ * One naming rule, in one module: **`<project>-<env>-<thing>`**, kebab-case.
+ *
+ * Every Cloudflare namespace Pithy writes into is flat and account-wide — D1, KV, R2, Worker
+ * scripts, Workflows, the single Secrets Store, the API-token list. None of them can be
+ * partitioned, so the *name* is the partition, and the project segment is the only thing keeping
+ * two Pithy projects in one account from adopting or overwriting each other's resources.
+ *
+ * **Project first** because that is the ownership boundary everything turns on: teardown, the
+ * token listing's prefix filter, and the reaper's reservation all key on it. **Environment second**
+ * because these end up in listings nobody can filter — `wrangler d1 list`, the account dashboard,
+ * the Secrets Store — and sorting by name should group a project's resources and then that
+ * project's environments, so everything belonging to prod sits together. Environment last
+ * would scatter prod through the listing, interleaved with staging, which is exactly when
+ * someone acts on the wrong one.
+ *
+ * A `global`-scoped thing puts the literal `global` in the environment slot rather than omitting
+ * it, so the scheme has no exception to remember.
+ *
+ * This module is in `core` because it has no dependencies and every layer needs it — capabilities,
+ * the CLI, and the Workers runtime alike. It therefore uses **no `node:` builtin**: core is bundled
+ * into the adopter's Worker, where `node:crypto` is not free.
+ */
+
+/**
+ * The default budget of the un-namespaced {@link resourceName} composer: the strictest cap of any
+ * namespace Pithy writes into, which is R2's 63.
+ *
+ * A caller that knows its namespace does **not** use this — it passes that namespace's own limit
+ * from `./limits`, or, better, goes through the facade in `./resourceNames`, which cannot pick the
+ * wrong budget. This number is the conservative answer for a call site that has no namespace at all.
+ */
+export const MAX_RESOURCE_NAME = NAMESPACE_LIMITS.r2.maxLength;
+
+/** Below this the trailing segment is not worth keeping legible, so a name this tight is refused instead. */
+const MIN_THING_BUDGET = 1;
+
+/**
+ * The cap on a project name — **derived, not chosen, and derived from two shapes rather than one**.
+ *
+ * A project name has to survive every name it will ever be the head of, so it gets the *smaller* of
+ * the two worst cases (`./limits` carries both derivations with their arithmetic):
+ *
+ * - {@link WORKFLOW_DERIVED_PROJECT_NAME} — `<project>-<env>-<capability>-<job>` against a Workflow's
+ *   64 characters, after the longest environment and the longest `<capability>-<job>`.
+ * - {@link FEATURE_DERIVED_PROJECT_NAME} — `<project>-f<issue>-<slug>-<binding>-<kind>` against R2's
+ *   63, with room for the reserved issue digits, a legible slug, and a binding kept whole.
+ *
+ * Neither number is repeated here. Each is a computed constant with its arithmetic in `./limits`, and a
+ * copy in this sentence is a copy that goes stale the first time a term of the derivation moves.
+ *
+ * The feature shape is the binding one, and it used to be invisible: the cap was derived from the
+ * Workflow alone, so a project inside it could still compose a feature name whose slug was hashed
+ * away to nothing. Taking the minimum is the only version that is true of both.
+ *
+ * **Why the cap belongs on the project name rather than on each composed name:** without it the
+ * refusal lands at the first `pithy <capability> provision`, by which time `pithy add` has created
+ * real R2 buckets and D1 databases under a name that fits *their* budget. The project is
+ * half-provisioned, and the only documented remedy — renaming — orphans everything already made.
+ * Capped here, `pithy init` and `requireProjectName` refuse it before anything is written.
+ */
+export const MAX_PROJECT_NAME = Math.min(WORKFLOW_DERIVED_PROJECT_NAME, FEATURE_DERIVED_PROJECT_NAME);
+
+/** Lowercase, collapse any run of non-`[a-z0-9]` to one `-`, and trim leading/trailing `-`. */
+export function kebab(input: string): string {
+  return input
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/**
+ * A stable 6-hex-character digest, FNV-1a. Pure arithmetic rather than `node:crypto` so this module
+ * runs unchanged in a Worker. It is a *disambiguator for truncated names*, never a security
+ * primitive — collision resistance beyond "two different capability names look different" is not
+ * claimed and must not be relied on.
+ */
+export function hash6(input: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < input.length; i += 1) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h.toString(16).padStart(8, "0").slice(0, 6);
+}
+
+/**
+ * Fit a kebab segment into `budget` characters: verbatim when it fits, otherwise a truncated head
+ * plus a short stable hash so it stays distinct and within budget. Deterministic in `segment`
+ * alone, so two commands computing the same name agree without storing it. The hash shrinks for
+ * tiny budgets, and the result never exceeds `budget` nor trails a hyphen.
+ */
+export function fitSegment(segment: string, budget: number): string {
+  if (budget <= 0) return "";
+  if (segment.length <= budget) return segment;
+  if (budget < 4) return hash6(segment).slice(0, budget);
+  const hashLen = Math.min(6, Math.max(2, budget - 2));
+  const headLen = Math.max(1, budget - hashLen - 1);
+  return `${segment.slice(0, headLen).replace(/-+$/, "")}-${hash6(segment).slice(0, hashLen)}`;
+}
+
+/** The parts of a provisioned name. Every field is required — an absent segment is a naming bug, not a default. */
+export interface ResourceNameParts {
+  /**
+   * The project name — the root `pithy.config.ts` `name`, resolved by `requireProjectName` and
+   * **never guessed**. This is the ownership boundary; a wrong value here writes into another
+   * project's resources.
+   */
+  project: string;
+  /** The environment (`dev`, `staging`, `prod`), or the literal `global` for a value shared across all of them. */
+  env: string;
+  /** What this resource is — a capability, a binding, a secret, a token profile. The only segment ever truncated. */
+  thing: string;
+}
+
+/**
+ * Compose `<project>-<env>-<thing>`, kebab-cased and fitted to `budget`.
+ *
+ * **Only `thing` is ever truncated.** The project and environment segments are taken verbatim,
+ * because a hashed project segment would let two long project names share a prefix — and the token
+ * listing filters on exactly that prefix, so a collision there means one project enumerating and
+ * acting on another's credentials. If project and environment alone cannot fit, that is refused
+ * with the limit named rather than quietly hashed into an ambiguous name.
+ *
+ * `budget` defaults to {@link MAX_RESOURCE_NAME}; a namespace with its own limit passes it in.
+ *
+ * The project segment is held to {@link isValidProjectName} — the same rule the Worker and Workflow
+ * namers apply — so a project this accepts is one every namespace accepts. It is a backstop, not the
+ * gate: the real refusal belongs at `pithy init` and `requireProjectName`, before anything is written.
+ */
+export function resourceName(parts: ResourceNameParts, budget: number = MAX_RESOURCE_NAME): string {
+  const project = kebab(parts.project);
+  const env = kebab(parts.env);
+  const thing = kebab(parts.thing);
+
+  for (const [role, value] of [
+    ["project", project],
+    ["environment", env],
+    ["thing", thing],
+  ] as const) {
+    if (!value) {
+      throw new ValidationError({
+        message: `A resource name needs a ${role}.`,
+        action: role === "project" ? "Set `name` in pithy.config.ts." : undefined,
+        detail: `resourceName received an empty ${role} segment (raw: ${JSON.stringify(parts)})`,
+      });
+    }
+  }
+
+  assertValidProjectName(parts.project);
+
+  const head = `${project}-${env}`;
+  const thingBudget = budget - head.length - 1;
+  if (thingBudget < MIN_THING_BUDGET) {
+    throw new InternalError({
+      message: `The project and environment names alone exceed the ${budget}-character limit for this resource.`,
+      action: "Shorten `name` in pithy.config.ts.",
+      detail: `"${head}" leaves ${thingBudget} characters for "${thing}"`,
+    });
+  }
+
+  return `${head}-${fitSegment(thing, thingBudget)}`;
+}
+
+/**
+ * Could every Cloudflare name this project generates be created? The one rule, in one place, so no
+ * namespace re-derives a looser version of it.
+ *
+ * **Read after kebabbing**, for the same reason {@link isReservedProjectName} is: the raw string never
+ * reaches an account, only what the composer made of it. `Acme Corp` is legal (it becomes `acme-corp`);
+ * `2026 Launch` is not, and neither answer can be read off the raw characters.
+ *
+ * **Two dimensions, one answer: charset and length.** Both have the same failure mode and so must have
+ * the same home — {@link NAME_SEGMENT} for the charset, {@link MAX_PROJECT_NAME} for the number. The
+ * charset is the shared segment rule rather than a project-specific one: a project name is the head of
+ * every composed name, so it is held to exactly what every other segment is held to.
+ *
+ * The rule matters at the *source* — `pithy init` and `requireProjectName` — because the namespaces
+ * disagree about it. A digit-leading project composes a legal D1 database name, a legal KV title, and a
+ * legal bucket name, so `pithy add` provisions all three for real; only the first host-worker deploy
+ * refuses it, by which point the documented remedy — rename the project — orphans everything already
+ * created. A 33-character project fails exactly the same way, one deploy later. One rule, enforced
+ * before anything is written, is the only version of this that is safe.
+ */
+export function isValidProjectName(name: string): boolean {
+  const normalized = kebab(name);
+  return normalized.length <= MAX_PROJECT_NAME && NAME_SEGMENT.test(normalized);
+}
+
+/**
+ * Refuse a project name no Cloudflare namespace could carry, as a **`ValidationError`**: a project name
+ * is something a human typed, so it is a 400 with an action, never an internal 500 blamed on the toolkit.
+ *
+ * Length and charset are one rule with two sentences, because they are two different mistakes: a name
+ * that is merely long is otherwise perfect, and "use lowercase letters" would be no help at all.
+ */
+export function assertValidProjectName(name: string): void {
+  if (isValidProjectName(name)) return;
+  const normalized = kebab(name);
+  if (normalized.length > MAX_PROJECT_NAME && NAME_SEGMENT.test(normalized)) {
+    throw new ValidationError({
+      message: `"${name}" is ${normalized.length} characters. A project name stops at ${MAX_PROJECT_NAME}.`,
+      action: `Shorten \`name\` in pithy.config.ts to ${MAX_PROJECT_NAME} characters or fewer.`,
+      detail: `${MAX_PROJECT_NAME} is the smaller of what a 64-character Workflow name leaves after a ${MAX_ENVIRONMENT_NAME}-character environment and a ${MAX_CAPABILITY_JOB}-character <capability>-<job> (${WORKFLOW_DERIVED_PROJECT_NAME}), and what a 63-character feature resource name leaves after a six-digit issue, a legible slug, and a binding (${FEATURE_DERIVED_PROJECT_NAME}).`,
+    });
+  }
+  throw new ValidationError({
+    message: `"${name}" can't be a project name.`,
+    action: "Use lowercase letters, digits, and single hyphens, starting with a letter.",
+    detail: `"${name}" kebabs to "${normalized}", which does not match ${NAME_SEGMENT.source}.`,
+  });
+}
+
+/**
+ * **`pithy-int-` is reserved for Pithy's own live integration tests, on any account.**
+ *
+ * Every Cloudflare name a live test creates begins with it, no real project's name may, and the
+ * test-debris reaper deletes nothing without it. The reservation is what makes automatic reaping safe
+ * in both directions: without it the reaper is guessing — either it fails to recognize the names a
+ * suite invented, and debris accumulates silently on a real account, or it matches loosely enough to
+ * one day delete a customer's database. With it, membership is decidable from the name alone.
+ *
+ * It lives here, next to the composer, because both halves of the reservation are naming facts.
+ * `<project>-<env>-<thing>` puts the project first and takes it **verbatim**, so the prefix of every
+ * generated name is decided by the project name and nothing else — which is what lets one guard, on
+ * `pithy init`, keep the two sets from ever overlapping. See {@link isReservedProjectName}.
+ *
+ * This is deliberately narrower than the product's own `pithy` prefix. A project may legitimately be
+ * named `pithy-app`, and everything it provisions is real; `pithy-int-…` is debris by definition.
+ */
+export const RESERVED_TEST_PREFIX = "pithy-int-";
+
+/**
+ * Would a project of this name generate resource names inside the reservation? The one rule
+ * `pithy init` enforces, stated once so no call site re-derives it.
+ *
+ * Two traps make the obvious `name.startsWith(RESERVED_TEST_PREFIX)` wrong, and both are reachable
+ * with a name a human would type.
+ *
+ * **Kebabbing.** The composer kebabs the project before using it, so the raw string is not what
+ * Cloudflare sees. `"Pithy Int Ruse"` is not prefixed by `pithy-int-`, and it normalizes straight into
+ * the reservation.
+ *
+ * **The trailing hyphen.** The composer appends one after the project. A project named exactly
+ * `pithy-int` is not prefixed by `pithy-int-` either, and it generates `pithy-int-dev-db` — inside the
+ * namespace the reaper deletes.
+ *
+ * Testing `` `${kebab(name)}-` `` against the prefix closes both: it compares the form the composer
+ * actually uses, including the separator it actually adds.
+ */
+export function isReservedProjectName(name: string): boolean {
+  return `${kebab(name)}-`.startsWith(RESERVED_TEST_PREFIX);
+}