Skip to content

Cloudflare Naming Canon

Substrate-specific application of the universal naming convention to the Cloudflare resources operated under the RTOpacks account.

Authority. This doc subordinates to ops/architecture-decisions.md ADR-018 (architectural cartography is a canonical artefact). ADR-018 holds the universal naming convention; this doc captures Cloudflare-substrate-specific facts (resource-type rename feasibility, character constraints, KV's uppercase-underscore exception) that the universal convention does not encode.

Last reconciled: 2026-05-26 per CANON-VS-ADR-018-RECONCILIATION-01.

The universal convention (per ADR-018 v4)

Every named Cloudflare resource carries a name following the shape:

<scope-prefix>-<domain-or-module>-<function>-<artefact-type>-<environment>

with each segment serving a distinct semantic role:

  • Scope prefix. Three categories: rtopacks-* (platform-owned), rto-* (client-facing), or no prefix (utility infrastructure). Determined by the ADR-018 four-clause test (Q1 → Q1b → Q2 → Q3).
  • Domain-or-module. What the resource is or relates to, in plain words. External-source acronyms (per ADR-018 worked examples) are permitted when they describe the data source; vendor brands (Stripe, QuickBooks) resolve to full words.
  • Function. What the resource does, in plain words.
  • Artefact-type. Drawn from ADR-018's closed vocabulary: module, bus, wrapper, proxy, queue, db, kv, r2, worker, surface, connector.
  • Environment. -prod, -dev, -staging — full-word, closed set.

Refer to ADR-018 for the determination test, vocabulary definitions, and worked examples. This doc does not duplicate that content.

Cloudflare-substrate exceptions

KV namespaces use uppercase-underscore throughout

Cloudflare's KV namespace naming permits broader characters than Workers/D1/R2/Queues, and existing substrate uses uppercase-underscore conventionally (e.g. STATS_CACHE, RTOPACKS_OPERATIONAL_KEYS). This is a substrate-imposed convention divergence, not a CF-enforced constraint.

KV naming shape:

<SCOPE_PREFIX>_<DOMAIN_OR_MODULE>_<FUNCTION>_<ARTEFACT_TYPE>_<ENVIRONMENT>
  • Uppercase letters
  • Underscore-separated (not hyphen)
  • Environment markers as _PROD / _DEV / _STAGING (underscore-prefixed, uppercase)

The artefact-type segment is typically KV when KV is the primary substrate identity; it may be omitted when the descriptive purpose word makes the artefact-type self-evident (e.g. STATS_CACHE — "cache" implies KV).

This exception is explicit, not implicit. All other Cloudflare resource types use the universal lowercase-hyphen shape per ADR-018.

Cloudflare character constraints

Resource type Allowed characters Separator
Workers alphanumeric + hyphen hyphen
D1 databases alphanumeric + hyphen hyphen
R2 buckets alphanumeric + hyphen (lowercase) hyphen
Queues alphanumeric + hyphen hyphen
KV namespaces broader (underscore + uppercase permitted) underscore (per substrate convention above)

Underscores, slashes, dots, and tildes are disallowed in Workers/D1/R2/Queues names. The universal convention's lowercase-hyphen shape satisfies all four constraints.

Per-resource-type rename feasibility (verified 2026-05-26)

Rename cost is asymmetric per resource type. Verified against current Cloudflare documentation:

Resource type Renamable? Mechanism Cost
Workers Yes New /workers/workers/{id} API with stable UUID across rename; routes need re-attachment. Reference: /changelog/post/2025-09-03-new-workers-api/ Cheap
KV namespaces Yes wrangler kv namespace rename [OLD-NAME] --new-name <NEW>. Namespace ID stable. Reference: /kv/reference/kv-commands/ Cheap
D1 databases No No rename CLI command; database UUID stable but display name not mutable. Reference: /d1/wrangler-commands/ Create-new-and-migrate-data
R2 buckets No No rename command; bucket name forms part of the S3-compatible endpoint URL. Reference: /r2/buckets/public-buckets/ Create-new-and-copy-objects
Queues No "You cannot change your queue name after you have set it." Reference: /queues/get-started/ Create-new-and-migrate-consumers
Service bindings Yes (via Worker rename) Bindings reference Workers; Worker UUID survives rename. Binding name in wrangler.toml is per-Worker config. Cheap if both sides redeployed

Implication for rename briefs. Phase sequencing in ADR-018's rename-conformance approach reflects this asymmetry:

  • Phase 1 (immediate): Workers + KV namespaces. Both renamable cheaply.
  • Phase 2 (opportunistic): D1 databases, R2 buckets, Queues. Bundled with migration briefs that touch them anyway (schema migrations, OPS-DB split, etc.).
  • Phase 3 (deliberate): Remaining D1/R2/Queue renames that lack a natural migration vehicle. Dedicated brief if cost-benefit justifies; otherwise deferred indefinitely.

Verification is point-in-time. If Cloudflare adds rename APIs for additional resource types, this table updates and Phase 1 expands accordingly.

Substrate-specific guidance

Domain-word usage for cross-product bridges

ADR-018 v4 scope prefixes are rtopacks-*, rto-*, or unprefixed (utility). The ucca- prefix is not present in the reconciled vocabulary — UCCA Online lives on a separate Cloudflare account and RTOpacks substrate does not host UCCA-product-owned resources.

However, ucca (and analogously any external-product name RTOpacks integrates with deeply) is permitted as a domain-or-function-segment word when the resource is RTOpacks-owned and the function bridges to that external product. Worked example:

rtopacks-ucca-export-worker-prod

A hypothetical future RTOpacks worker that exports Studio build requests to UCCA and receives built content back. Platform-owned (Q3 → rtopacks-); function reaches the UCCA product (function segment ucca-export); artefact-type worker. The name broadcasts: "RTOpacks platform infrastructure that exports to UCCA."

The principle generalises: any external product RTOpacks integrates with substantively — UCCA, future external partners, integrated portals — follows the same rule. External product name in the domain/function segments; RTOpacks-account scope prefix per the ADR-018 determination test.

Database-to-surface alignment

When a single database serves a single user-facing surface, the database name should align with the surface name. Example: rto-landscape-db-prod serves the Landscape surface; the shared landscape domain word is the alignment.

When multiple surfaces share a database, the database name describes the data shape rather than any one surface. Example: rtopacks-nrt-db-prod is consumed by Radar, Marketer, and others — its name describes the data (NRT corpus) not any specific consumer.

Surface-to-database mapping is documented in cloudflare-resource-inventory.md.

Reference-data resources

The -ref suffix from prior canon revisions is retired from the name level. The semantic contract (externally sourced data, shared across environments by design, single privileged writer, schema rarely changes) is preserved as a documented property in cloudflare-resource-inventory.md — each reference-data resource carries an explicit reference-data: yes annotation alongside its inventory entry. The contract lives in the inventory, not in the name. Resources matching this shape (rtopacks-nrt-db-prod, rtopacks-abs-db-prod, etc.) carry standard environment suffixes; their reference-data status is the inventory annotation, not a suffix on the name.

Naming-pause discipline

This canon is the substrate-specific application of the NAMING-PAUSE RULE in ops/standing-rules.md. When this canon and any older convention disagree, this canon wins. When this canon and ADR-018 disagree, ADR-018 wins (ADR-018 is the universal authority; this canon is the substrate-specific addendum).

If a new resource doesn't have an obvious canonical name, pause. Either it fits a pattern the canon already covers (apply the convention), or it surfaces a gap that the canon needs to absorb (extend with named reasoning in a canon update or successor ADR), or the resource is being created on the fly without clear intent (defer creation).

Companion documents

  • ops/architecture-decisions.md — ADR-018 is the canonical naming-convention authority; this doc subordinates to it.
  • ops/standing-rules.md — substrate-neutral NAMING-PAUSE RULE.
  • infrastructure/cloudflare-resource-inventory.md — applied inventory of resources by canonical name and content.
  • infrastructure/google-cloud.md — sister canon for GCP resources.
  • ops/infrastructure-reference.md — broader infrastructure reference.

Changes to this canon

Per the standing rule on canonical doc changes:

  1. A Tim-approved reason for the change
  2. Updated version committed to this path
  3. Existing resources audited against the new canon — drift is fixed or documented as exception
  4. Project Files copy re-uploaded

Reconciliation history

  • 2026-05-26 — Reconciled with ADR-018 v4 per CANON-VS-ADR-018-RECONCILIATION-01. Substantial rewrite. Universal naming-convention shape, scope prefixes, env-suffix vocabulary, artefact-type vocabulary, determination test, utility category all delegated to ADR-018 (no longer duplicated here). Canon retained for: KV uppercase-underscore exception, per-resource-type rename feasibility (verified against current CF docs), Cloudflare character constraints, cross-product domain-word usage, database-to-surface alignment guidance, reference-data contract. Previously: 179 lines, 9 substrate-neutral principles + 6 resource-type rules + exceptions. Now: substrate-specific addendum that delegates the universal convention to ADR-018.