Naming rules and limits

One rule

Naming is the concept page. The names this governs land as bindings and tables, and the ceilings it derives against are accepted limits.

<project>-<env>-<thing>

Kebab-case, project first, environment second. No namespace is exempt.

Why there is a rule at all

Every Cloudflare namespace Pithy writes into is flat and account-wide — D1, KV, R2, queues, Vectorize, Artifacts namespaces, Worker scripts, Workflows, the Secrets Store, the API-token list. None 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.

Provisioning finds a resource by name and reuses it. Without a project segment, find-then-create means a second project silently inherits the first’s database.

The namespaces

NamespaceNameExample
D1<project>-<env>-<binding>acme-prod-db
KV<project>-<env>-<binding>acme-prod-sessions
R2<project>-<env>-<capability>acme-prod-storage
Queue<project>-<env>-<binding>acme-prod-jobs
Vectorize<project>-<env>-<capability>-<index>acme-prod-vector-docs, acme-prod-support-messages
Artifacts namespace<project>-<env>, one per environment. A feature’s is <project>-f<issue>-<slug>--artifactsacme-prod
Worker script (capability host)<project>-<env>-<capability>, or <project>-<env>-<worker>---<capability> for a Worker’s own hostacme-prod-email, acme-prod-billing---email
Worker script (your own, per environment)<project>-<env>-<worker>acme-prod-api
Workflow<project>-<env>-<capability>-<job>, or <project>-<env>-<worker>---<capability>-<job> on a Worker’s own hostacme-prod-email-send, acme-prod-billing---email-send
Secrets Store entry<project>-<env>-<secret>acme-prod-secrets-encryption-keys
CF API token<project>-<env>-<profile>acme-prod-ci-system
Email Routing rule<project>-<env>-<capability>-<purpose>, or global for one the project sharesacme-prod-support-inbound, acme-global-email-bounce
Turnstile widget<project>-prod-turnstile-<mode>acme-prod-turnstile-visible

Three things deliberately not on that list

Worker binding names — DB, SESSIONS, MEDIA_BUCKET — never carry the project. A binding is a variable name inside your own Worker; two projects cannot collide on it, and renaming one is a breaking change to your code for no benefit.

Secret registry keys never carry it either. For a Secrets Store secret the registry key is the binding name and the .dev.vars variable name — only the store entry it resolves to is scoped.

Table names stay pithy_<capability>_<table>. They live inside one database, which is already project-scoped by the database’s own name.

Shared by default, owned when a Worker says so

Every binding is shared by name. Two Workers that both declare DB are backed by one D1, and adding a Worker costs a directory under apps/, not a new database.

A Worker that lists a binding in ownBindings gets its own resource instead. The list lives in that Worker’s pithy.worker.jsonc:

// apps/billing/pithy.worker.jsonc
{
  "ownBindings": ["DB", "SESSIONS"]
}

The owned resource puts the Worker in the thing segment, joined by three hyphens:

<project>-<env>-<worker>---<thing>

<worker> is the apps/<worker> directory, never the deploy name. So apps/billing owning DB in acme is acme-prod-billing---db, beside the shared acme-prod-db every other Worker binds. It applies to every kind provision creates per binding: D1, KV, R2 and queues, and to the kit hosts that read them (below). Your Worker code does not change; env.DB is still env.DB.

Three hyphens keep it apart from two things. From every shared name, because a kebab never holds a run of hyphens: billing---db is the Worker owning DB, and billing-db is a shared BILLING_DB. And from every feature, because -- is a feature’s: the first -- in an owned name is followed by a third hyphen, and a feature name’s thing never starts with one, so no declared environment’s name parses as a feature’s.

Only the thing is fitted, and the separator survives. When <worker>---<thing> does not fit, each side keeps a head and a hash of the whole follows: <w>---<t>-<hash>. The project and environment stay verbatim, as everywhere else, so the project-name cap does not move.

A scope: "global" binding cannot be owned. It is one resource for the project by definition. pithy provision, pithy add and pithy worker sync refuse the entry, naming the binding and the capability. An entry naming no D1, KV, R2 or queue binding the Worker composes owns nothing, and pithy provision and pithy doctor say so.

Kit hosts a Worker owns

A Worker that owns a binding a capability’s host binds gets that host to itself. Its email jobs, audit rows and every other host’s work sit in its own resources, so a host shared with the other Workers would read the wrong ones. The host takes the owner in its thing segment the way an owned resource does: apps/billing owning DB and composing email has acme-prod-billing---email, with Workflows acme-prod-billing---email-send and acme-prod-billing---email-schedule, beside the shared acme-prod-email every other Worker reaches. A Worker that owns SECRETS has its own secrets manager the same way, acme-prod-billing---secrets, writing through acme-prod-billing---secrets-write. The shared manager binds that vault as VAULT_BILLING to re-seal it, and binds a Worker’s own database holding an encrypted column as <BINDING>_OF_<WORKER>, so DB_OF_BILLING. A host that binds nothing the Worker owns stays shared.

On a feature branch the host is named for the feature and the owner: <project>-f<issue>-<slug>--<worker>---<capability>, so acme-f12-x--billing---email. Locally, pithy dev runs it as billing---email on a pinned port of its own.

A Worker or Workflow name is never fitted. One that does not fit is refused, naming the directory: Shorten the apps/<worker> Worker's directory name, or take the binding out of its ownBindings.

A host that keys a bucket to its database’s rows takes both or neither. Storage’s sweep deletes every derived object with no row in the database it reads, and audit’s checkpoint keys name a tenant and a count, never the database. So a Worker that owns storage’s DB and shares STORAGE_BUCKET, or owns audit’s database and shares AUDIT_CHECKPOINTS, is refused by pithy provision, pithy deploy and pithy dev: <worker> owns DB but shares STORAGE_BUCKET., with Add STORAGE_BUCKET to apps/<worker>/pithy.worker.jsonc ownBindings, or take DB out. Audit’s pair is refused the other way too: a Worker that owns AUDIT_CHECKPOINTS and shares audit’s database would put a second checkpoint and prune host on the shared chain, each keeping its tombstones in a bucket the other never reads, so it is refused with <worker> owns AUDIT_CHECKPOINTS but shares DB. Owning storage’s bucket alone is no split, and media’s bucket holds nothing keyed to a row, so media is not refused.

A Worker’s own host fills Vectorize indexes of its own. A vector or support index holds vectors keyed to the rows of the database its host reads, so a Worker’s own host binds <project>-<env>-<worker>---vector-<index> and <project>-<env>-<worker>---support-messages, created by pithy vector provision --worker <worker> and pithy support provision --worker <worker>, and a feature’s are <project>-f<issue>-<slug>--<worker>---<thing>.

Moving a binding between shared and owned is a repoint, and nothing moves the rows. A stanza still pointing at the other resource is refused by pithy provision --env unless the run passes --repoint, and the old resource keeps its data (pithy provision). Locally, an owned D1 entry carries a top-level database_id of its own, so pithy dev, migrate and seed keep it apart from the shared one. pithy doctor’s Resource names: block reports a stanza naming anything other than what provision would compose for that Worker.

Your own Worker, and the names it may not take

The Worker you deploy is named by wrangler, not by the kit: wrangler deploy --env staging appends the environment to the top-level name unless the stanza declares one. So this is the one name here the kit reads rather than composes — and pithy init and pithy worker add write it out, <project>-<env>-<worker>, so the read finds the kit’s shape. Everything belonging to one environment then sorts together in an account listing, which is how an account is actually read and how blast radius is actually reasoned about. You compare an environment’s whole set; you do not compare one app’s two environments.

A project that never declared a name keeps the one it has. The fallback is still wrangler’s <name>-<env>, unchanged and deliberately so: recomputing it would rename the deployed Worker of every existing adopter, and a Worker script is a name you cannot change without leaving the old one live, serving, and billing. New projects get the convention; existing ones keep theirs, and pithy doctor says so once, as a convention rather than a fault. pithy provision reads a declared name and writes one only where there is none, for the same reason.

And that is why a Worker may not be called email. Under this shape apps/email deploys as <project>-<env>-email — byte-identical to the host Worker the email capability’s own provision creates. Cloudflare’s script namespace is account-flat, so a deploy replaces it silently and the capability’s Workflows stop running. Every capability that ships a host Worker owns its name: pithy init --worker, pithy worker add and pithy worker rename refuse it, and pithy doctor reports an existing project that declares one. The set is read from the host registry at run time rather than written down, so a capability that ships a host later is covered the day it is registered. email-api is fine; the collision is with the exact name, not with a prefix.

The length caps, and whose they are

NamespaceMaxOverflowSource
Workflow64RefuseCloudflare
Vectorize index64 bytesRefuseCloudflare
Worker script63RefuseCloudflare
R2 bucket63 (min 3)TruncateCloudflare
Queue63TruncateCloudflare
Artifacts namespace63 (min 2)Truncate, and never long enough to beCloudflare
Artifacts repo63 (min 2)RefusePithy’s
KV namespace title512TruncateCloudflare
D1 database128TruncatePithy’s
Secrets Store entry128TruncatePithy’s
API token label128TruncatePithy’s

Where the source is Pithy’s, Cloudflare documents no cap. 128 is the kit’s own ceiling for the three it composes. An Artifacts repo stops at 63, mirroring the namespace, and is refused rather than shortened for a reason of its own: Pithy does not compose it. It is a random UUID or a name somebody chose, it is in every clone URL, and a name somebody chose is never silently changed. Its charset is Cloudflare’s: a letter or digit, then letters, digits, ., _ and -.

The project-name budget

A project name is capped at 26 characters, and that number is derived rather than chosen — it is what the longest feature resource name leaves against R2’s 63:

    63   an R2 bucket name
  -  2   `-f`
  -  6   the issue number, six digits
  - 12   `-` + a slug legible at 11
  - 14   `--` + a binding kept whole at 12
  -  3   `-` + the kind
  ----
    26

The Workflow namespace is the other binding constraint, leaving 33:

    64   a Workflow name
  -  1   the hyphen
  -  7   the longest environment, `staging`
  -  1   the hyphen
  - 22   the longest capability-job, `media-audio-transcribe`
  ----
    33

A longer capability-job tail is refused rather than letting a new capability silently invalidate the project-name cap every existing project was accepted under.

The feature-branch budget

A feature environment is an environment, so f<issue>-<slug> occupies the environment slot. It is the tightest shape Pithy composes:

<project>-f<issue>-<slug>--<binding>-<kind>

Held to R2’s 63 — the strictest of the kinds a feature provisions, and a queue’s cap too — so one shape is legal for the bucket, the database, the KV namespace and the queue alike. Eight characters are fixed: -f, four more hyphens (two of them together, after the slug), and a kind of at most two characters. A queue’s kind is q, not queue: three more characters there would come out of every project name. That leaves 55 to divide four ways:

project + issue + slug + binding = 55

The issue number is reserved 6 digits — f999999, just under a million open issues in one repository. Every digit reserved here costs one character of every project name, so it is six rather than seven. At the worst case the slug gets 49 - project - binding. Here is what that leaves the slug, the longest a feature is allowed, at a 6-digit issue:

projectDBASSETSMEDIA_BUCKETEMAIL_SUPPRESSIONS
443373327
839332923
1235292519
1631252115
2027211711
262115115

A real issue number is rarely six digits, and every digit you do not use comes straight back to the slug. Issue 95 on a 12-character project with a DB binding gets 39 slug characters, not 35.

A slug over budget is refused, not shortened. It used to become a truncated head plus a six-hex hash, and a hash is a slug another branch can have whole. The table is the resource shape only: the real budget is the least room any name the feature composes leaves, and a Workflow such as media-audio-transcribe, in a Workflow’s 64, is usually as tight as EMAIL_SUPPRESSIONS.

The guidance that falls out of it. Keep the branch slug to roughly 20 characters — feature/95-project-scope rather than feature/95-project-scope-resources-and-limits. Only the part after the issue number becomes the slug. The refusal says the maximum, so a slug that fits is one rename away.

A feature’s Worker scripts share the head and drop the kind: <project>-f<issue>-<slug>--<worker>, held to the Worker script rule of 63. <worker> is the apps/<worker> directory, not the deploy name — pithy init replay --worker board deploys apps/board as replay-board, and its feature Worker is replay-f69-demo--board, the project once. A Worker directory whose name leaves no room for the slug is refused too, naming the directory.

A binding a Worker owns is the one exception to a feature resource having no Worker segment: <project>-f<issue>-<slug>--<worker>---<binding>-<kind>, so apps/billing owning DB on feature/12-x is acme-f12-x--billing---db-d1. Every other binding is shared by name, as it is in a declared environment. The feature’s record names the owner, and pithy feature destroy recomputes the owned name like any other.

An owned binding is a longer shape, and only a project that owns one pays for it. <worker>--- sits before the binding, so the slug budget of a project that declares ownBindings counts every owned name too. A project that owns nothing keeps the table above.

Nothing is shared with a feature

A feature shares nothing with any other feature, with staging or production, in its own project or in another project in the same account — except its rate-limit namespaces, which every feature shares and no declared environment can. The account and its one Secrets Store are the only containers that cannot be split; every name inside them is the feature’s own. Two rules make that true of the names rather than merely likely:

  • Two hyphens end the slug. Every other segment Pithy composes is kebab-cased, and a kebab never holds two hyphens in a row. The one run a declared environment’s name can hold is an owned binding’s three, and a feature’s thing never starts with a hyphen, so no declared environment of any project can compose a feature’s name. And the slug ends where the first double hyphen starts, so feature/12-x binding PROD_DB and feature/12-x-prod binding DB no longer name one database.
  • A project with features has no f<digits> segment in its name. A feature name is read from the first f<digits> segment, which is the issue. acme-f12-x’s feature 3 on y and acme’s feature 12 on x-f3-y would be one string. pithy init refuses such a name, pithy provision --feature refuses to create features for an existing one, and pithy doctor names the segment. Its staging and production are unaffected, and nothing is renamed: a rename orphans everything already provisioned.

Together they make every feature name parse back to exactly one project, issue and slug, which is how the isolation gates check ownership — by parsing, never by prefix. The issue is read without leading zeros, so feature/0643-foo is feature/643-foo.

Rate-limit namespaces are the one thing features share, and only with each other. Cloudflare keys a limiter’s counters by namespace_id across the whole account. A feature binds an integer from 1000000000 through 1999999999, a range no project running this kit may declare, in any Worker or stanza: pithy provision for every environment and pithy deploy refuse one, and pithy doctor reports it, whether or not the project ever provisions a feature. The id is read as the integer it spells, so "01031275746" is 1031275746 and is refused too.

Each limiter’s feature namespace is fixed: its declared namespace_id plus 1000000000, so 1001 is 1000001001 in every feature of every project. An offset cannot collide, so two distinct limiters never merge, and two Workers bound to one namespace in production share one in every feature. A limiter whose namespace cannot be offset into the range is refused by pithy provision --feature before anything is created: one with no namespace_id, one not spelled in decimal digits, or one outside 1 through 999999999. Nothing is allocated, recorded or released, and nothing account-wide is created for rate limiting.

Environments

dev, staging and prod are first class; staging at 7 characters is the longest, and that is the number the budgets above reserve.

A custom environment is a string, and still validated. dev can never be declared — it is the top-level stanza and it always exists.

And an environment cannot start the way a feature does. A feature takes the same slot with f<issue>, and its Worker is <project>-f<issue>-<slug>--<worker> with no kind suffix. Before the double hyphen, an environment called f1-demo stamped <project>-f1-demo-api into its stanza, which was feature 1-demo’s Worker character for character, and pithy feature destroy on feature/1-demo deleted it. So an environment whose first segment is f and digits is refused — f1, f12-ab, f01 — and nothing else: fr-1, f1a and fix are fine, because no name composed under them can be a feature’s.

Every declared environment is managed. There is no second, narrower list, because an environment deployed and not managed is one whose secrets have no master key.

Charset rules worth knowing

An R2 bucket must start and end alphanumeric. So must a queue.

A Vectorize index must start with a letter — which the project rule already guarantees, so the two agree by construction.

A Workflow name may start with an underscore. A Worker script may not start or end with a dash.

ESC