rcf-lite 0.12.0 → 0.14.0

package/blueprints/deploy-cloudflare-workers/assets/wrangler-samples/preview-alias-shape.md

@@ -0,0 +1,86 @@
+# Preview alias and per-version URL patterns
+
+Reference shape for the three URL kinds this blueprint mandates. Every value with `<...>` is a placeholder the operator fills; no real hostname appears here.
+
+## The three URL kinds
+
+Given a Worker named `<worker-name>` on an account whose workers.dev subdomain is `<subdomain>` and a production custom domain of `<production-hostname>`, the Deploy Adapter's `deploy status` surfaces three URLs:
+
+| Kind | URL pattern | Changes on | Purpose |
+|---|---|---|---|
+| Per-version-id URL | `<version-prefix>-<worker-name>.<subdomain>.workers.dev` | Every upload assigns a new one; the URL for a given version is permanent | Pin a change-review link to a specific version id; never rots |
+| Stable preview alias URL | `<alias>-<worker-name>.<subdomain>.workers.dev` | Never (points at a moving target: the newest-of-`<alias>`) | Persistent shareable review surface for stakeholders |
+| Production URL, custom-domain branch | `<production-hostname>` (paired with `workers_dev = false`) | Only on an explicit `promote` workflow | User-facing traffic when a custom domain owns production |
+| Production URL, workers.dev-only branch | `<worker-name>.<subdomain>.workers.dev` (paired with `workers_dev = true`) | Only on an explicit `promote` workflow | User-facing traffic when no custom domain is mapped |
+
+The alias string is operator-chosen; `main` is the common default when the operator wants "the newest of the main branch" as the persistent preview. A project running multiple long-lived branches can allocate additional aliases (`staging`, `next`), each fixed to the newest-of-that-branch upload.
+
+## Discovering the workers.dev subdomain
+
+The `<subdomain>` segment in every workers.dev URL above is a per-account value the operator does not name in `wrangler.toml`. `wrangler whoami` prints the account id and email but does NOT print the subdomain; there is no wrangler 4.x CLI verb that returns it. The vendor's REST API returns it:
+
+```
+GET https://api.cloudflare.com/client/v4/accounts/<accountId>/workers/subdomain
+Authorization: Bearer <cloudflareApiToken>
+```
+
+Response:
+
+```json
+{ "result": { "subdomain": "<subdomain>" }, "success": true, "errors": [], "messages": [] }
+```
+
+The Deploy Adapter's `resolveSubdomain()` verb (TAC-1301) wraps this call; every URL-assembly path calls the verb on boot and caches the value for the process's lifetime. A project that would rather pin the value in configuration sets an unambiguous `WORKERS_DEV_SUBDOMAIN` env var and the resolver returns that value ahead of the API call; the discovery path is the fallback so a fresh checkout works with no environment tuning.
+
+## The upload verb
+
+```
+wrangler versions upload --preview-alias <alias>
+```
+
+Uploads the current build as a new version. Assigns a version id and returns two URLs on stdout: the per-version-id URL (unique per upload, permanent) and the stable preview alias URL (fixed to `<alias>`, always pointing at the version this upload just produced). The uploaded version does NOT serve production traffic; only the promote verb changes production.
+
+`versions upload` refuses on a Worker that has not been deployed at least once (`You cannot upload a new version of a Worker that does not yet exist. Please run the 'deploy' command first.`). The first-time-per-Worker bootstrap uses `wrangler deploy --secrets-file <path>`; see `bootstrap-vs-steady-state.md`. Every subsequent ship rides `versions upload`.
+
+## The promote verb
+
+```
+wrangler versions deploy <version-id>
+```
+
+Routes production traffic to the named version id. Requires the version id to be present in `wrangler versions list`. The blueprint's promote workflow calls this verb through the Deploy Adapter after resolving the version id from either the input `versionId` field or, when the input is empty, from the newest-of-alias resolution described below.
+
+## Newest-of-alias resolution
+
+The promote workflow's optional `versionId` input defaults to newest-of-`<alias>` when empty. There is no wrangler CLI verb that maps an alias string to a version id directly (`wrangler versions view` accepts a version UUID as a positional argument only; it does not accept an alias). The working resolution reads the versions list as JSON and filters by the alias annotation:
+
+```
+wrangler versions list --json
+```
+
+Each item carries `id`, `number`, `metadata.created_on`, and `annotations.workers/alias` (when the version was uploaded with `--preview-alias <alias>`). Newest-of-`<alias>` is the item whose `annotations.workers/alias` equals `<alias>` with the greatest `metadata.created_on`. A worked shape:
+
+```javascript
+// Inside the Deploy Adapter's default vendor binding.
+const listOut = await runVendorCli(['versions', 'list', '--json']);
+const versions = JSON.parse(listOut.stdout);
+const forAlias = versions
+  .filter(v => v.annotations?.['workers/alias'] === alias)
+  .sort((a, b) => Date.parse(b.metadata.created_on) - Date.parse(a.metadata.created_on));
+if (forAlias.length === 0) {
+  throw new Error(`DEPLOY_ALIAS_UNKNOWN: no version behind alias '${alias}'`);
+}
+return forAlias[0].id;
+```
+
+A project that runs a single alias (the common `main`-only case) can drop the filter and pick the newest of any; the semantic is identical when only one alias exists.
+
+## The rollback verb
+
+Rollback IS a promote of a prior version id. The blueprint's Deploy Adapter surfaces one path (`promoteVersion`); the vendor's convenience shortcut `wrangler rollback [<version-id>]` is optional operator documentation for a break-glass path that bypasses the deploy-log record and the served-surface verifier. Do not use it as the recorded ship path.
+
+## Reader notes
+
+- The exact `<version-prefix>` string the vendor uses in the per-version-id URL is a vendor implementation detail; the operator does not name it. The URL is the whole shape; the adapter's `describeVersion` returns it verbatim.
+- The alias URL host segment is a function of the alias string; the alias `main` produces the host segment `main-<worker-name>`. The Preview URL Resolver (TAC-1303) refuses an alias whose assembled host would equal the production URL host; a manifest that would collapse them refuses to load. Collapse is only reachable on the workers.dev-only production branch where alias `<worker-name>` (or any string that assembles to the same host) would collide with the production host; the branch's default alias `main` is safe by inspection.
+- The production URL is derived from the wrangler manifest's `routes`/`route`/`workers_dev` block. When a custom domain owns production, the vendor's own custom-hostname primitive is what binds the domain to the Worker; the blueprint does not itself provision DNS or issue TLS. When `workers_dev = true` owns production, the URL is `<worker-name>.<subdomain>.workers.dev` and the resolver's `resolveSubdomain()` fills the `<subdomain>` segment.

package/blueprints/deploy-cloudflare-workers/assets/wrangler-samples/wrangler-toml-shape.md

@@ -0,0 +1,85 @@
+# wrangler.toml shape sample
+
+Reference shape for a Worker that reads a KV namespace, a D1 database, a set of secrets, and serves static assets behind an auth gate. Every value with `<...>` is a placeholder the project fills. Two production-URL branches are shown, custom-domain and workers.dev-only; pick one, delete the other.
+
+```toml
+# repo-root wrangler.toml
+name = "<worker-name>"
+main = "src/worker.ts"
+compatibility_date = "2026-08-01"
+compatibility_flags = ["nodejs_compat"]
+
+# --- production routing: pick ONE branch ---
+
+# Branch A: custom domain owns production (workers_dev = false so production
+# is unambiguously the custom domain; the preview alias URL still lives on
+# workers.dev regardless).
+routes = [
+  { pattern = "<production-hostname>", custom_domain = true }
+]
+workers_dev = false
+
+# Branch B (workers.dev-only, no custom domain): production is
+# <worker-name>.<subdomain>.workers.dev, where <subdomain> is the account's
+# workers.dev subdomain. Discover it via the CF REST API (see
+# `preview-alias-shape.md` under `Discovering the workers.dev subdomain`);
+# do NOT hardcode.
+# workers_dev = true
+# (delete the `routes = [...]` block above when using Branch B)
+
+# --- static-assets binding ---
+# The assets pipeline serves any file under `directory` at its file-path
+# BEFORE the Worker's fetch handler runs. That means `./public/notes.html`
+# is reachable at `/notes` and at `/notes.html` from the edge cache with
+# no code executing. On any Worker with an auth gate, that ordering
+# silently bypasses the gate for any collision path.
+#
+# `run_worker_first` is the switch that inverts the ordering: for every
+# listed path (glob-matched), the fetch handler runs FIRST and the assets
+# pipeline is a fallback. Set it whenever the Worker gates access to
+# anything a static-file path could shadow.
+[assets]
+directory = "./public"
+binding = "ASSETS"
+run_worker_first = [
+  "/api/*",
+  "/<auth-gated-path-1>",
+  "/<auth-gated-path-2>"
+]
+
+# --- non-secret vars (populated into env.<NAME> at runtime) ---
+[vars]
+LOG_LEVEL = "info"
+
+# --- KV namespace binding (id filled by the operator; not a secret) ---
+[[kv_namespaces]]
+binding = "SESSION_KV"
+id = "<kv-namespace-id>"
+
+# --- D1 database binding ---
+[[d1_databases]]
+binding = "APP_DB"
+database_name = "<database-name>"
+database_id = "<database-id>"
+
+# --- Secret bindings: NO DECLARATION BLOCK IN THIS FILE ---
+# wrangler 4.x has no top-level `[secrets]` key. Secret binding NAMES
+# are declared implicitly by the Worker code reading `env.<NAME>`; the
+# vendor's pre-flight refuses `wrangler deploy` when a referenced secret
+# has not been set on the target Worker. See `bootstrap-vs-steady-state.md`
+# for the first-deploy path (`wrangler deploy --secrets-file <tmp>`) and
+# the steady-state path (`wrangler secret put <NAME>` from CI).
+#
+# A project that wants a human-readable manifest of required secrets can
+# maintain one in a README section or a project-owned `SECRETS.md`; that
+# manifest is intent-documentation and is NOT vendor-parsed.
+```
+
+## Reader notes
+
+- `name`, `main`, and `compatibility_date` are the three top-level keys the manifest loader (TAC-1302) refuses to load without. `compatibility_date` must match `\d{4}-\d{2}-\d{2}`.
+- Every binding name referenced from `src/worker.ts` (through `env.SESSION_KV.get(...)`, `env.APP_DB.prepare(...)`, `env.<SECRET_NAME>`, and so on) must appear as a declaration key in this file OR as a secret set on the Worker via the vendor's secret-set flow. The manifest loader's binding-usage scan refuses the build with `WRANGLER_BINDING_UNDECLARED` when a non-secret binding is missing; the vendor's pre-flight refuses the deploy when a secret is missing on the target.
+- **Assets-binding auth-gate discipline (security-class).** The `[assets] run_worker_first` list is load-bearing whenever the Worker gates access to any path that a static file under `directory` could shadow. Without it, a request to `/<gated-path>` is answered from `./public/<gated-path>.html` (if the file exists) BEFORE the fetch handler runs; the auth check is silently bypassed. The manifest loader flags a manifest that declares `[assets]` and a fetch handler with an auth middleware but no `run_worker_first` entries covering the middleware's protected routes; a project unsure which routes to list defaults to `run_worker_first = ["/*"]` and accepts serving static assets only under `not_found_handling`.
+- Secret binding VALUES never appear in this file. There is no `[secrets]` block in wrangler 4.x; the vendor treats every `env.<NAME>` reference from Worker code as an implicit binding declaration and enforces its presence at deploy time. Values arrive on the Worker via the vendor's secret-set flow (see `bootstrap-vs-steady-state.md`) sourced from the project's secrets contract (see the `security-secrets-management` blueprint at slug `security-secrets-management`, or the equivalent project-authored pipeline).
+- `routes` and `workers_dev` together declare the production URL. Branch A (`workers_dev = false` with a `routes = [...]` custom-domain entry) is the shape for projects that own a custom domain. Branch B (`workers_dev = true`, no `routes`) is the shape for greenfield workers.dev-only projects; production is then `<worker-name>.<subdomain>.workers.dev` and the Deploy Adapter discovers `<subdomain>` at boot rather than hardcoding it.
+- Build-provenance values (`versionSha`, `builtAt`, `ciRunUrl`) are NOT declared here. They are injected into the built bundle by the `build-and-upload` workflow (see `assets/ci-workflows/build-and-upload.yml.md`). The `versionSha` served on the health probe is the git commit sha (`github.sha`), NOT the vendor-assigned version UUID; see `served-surface-probes.md` for the distinction.

package/blueprints/deploy-cloudflare-workers/blueprint.json

@@ -0,0 +1,48 @@
+{
+  "slug": "deploy-cloudflare-workers",
+  "version": "1.1.0",
+  "category": "deploy",
+  "contributions": [
+    { "id": "deploy-cloudflare-workers-REQ-001", "kind": "req", "path": "requirements/deploy-cloudflare-workers-req-001.json" },
+    { "id": "deploy-cloudflare-workers-REQ-002", "kind": "req", "path": "requirements/deploy-cloudflare-workers-req-002.json" },
+    { "id": "deploy-cloudflare-workers-REQ-003", "kind": "req", "path": "requirements/deploy-cloudflare-workers-req-003.json" },
+    { "id": "deploy-cloudflare-workers-REQ-004", "kind": "req", "path": "requirements/deploy-cloudflare-workers-req-004.json" },
+    { "id": "deploy-cloudflare-workers-REQ-005", "kind": "req", "path": "requirements/deploy-cloudflare-workers-req-005.json" },
+    { "id": "deploy-cloudflare-workers-REQ-006", "kind": "req", "path": "requirements/deploy-cloudflare-workers-req-006.json" },
+    { "id": "deploy-cloudflare-workers-REQ-007", "kind": "req", "path": "requirements/deploy-cloudflare-workers-req-007.json" },
+    { "id": "deploy-cloudflare-workers-REQ-008", "kind": "req", "path": "requirements/deploy-cloudflare-workers-req-008.json" },
+    { "id": "deploy-cloudflare-workers-REQ-009", "kind": "req", "path": "requirements/deploy-cloudflare-workers-req-009.json" },
+    { "id": "deploy-cloudflare-workers-REQ-010", "kind": "req", "path": "requirements/deploy-cloudflare-workers-req-010.json" },
+    { "id": "deploy-cloudflare-workers-REQ-011", "kind": "req", "path": "requirements/deploy-cloudflare-workers-req-011.json" },
+    { "id": "deploy-cloudflare-workers-REQ-012", "kind": "req", "path": "requirements/deploy-cloudflare-workers-req-012.json" },
+    { "id": "deploy-cloudflare-workers-US-12101", "kind": "us", "path": "user-stories/deploy-cloudflare-workers-us-12101.json" },
+    { "id": "deploy-cloudflare-workers-US-12102", "kind": "us", "path": "user-stories/deploy-cloudflare-workers-us-12102.json" },
+    { "id": "deploy-cloudflare-workers-US-12103", "kind": "us", "path": "user-stories/deploy-cloudflare-workers-us-12103.json" },
+    { "id": "deploy-cloudflare-workers-US-12104", "kind": "us", "path": "user-stories/deploy-cloudflare-workers-us-12104.json" },
+    { "id": "deploy-cloudflare-workers-US-12105", "kind": "us", "path": "user-stories/deploy-cloudflare-workers-us-12105.json" },
+    { "id": "deploy-cloudflare-workers-US-12106", "kind": "us", "path": "user-stories/deploy-cloudflare-workers-us-12106.json" },
+    { "id": "deploy-cloudflare-workers-US-12107", "kind": "us", "path": "user-stories/deploy-cloudflare-workers-us-12107.json" },
+    { "id": "deploy-cloudflare-workers-US-12108", "kind": "us", "path": "user-stories/deploy-cloudflare-workers-us-12108.json" },
+    { "id": "deploy-cloudflare-workers-US-12109", "kind": "us", "path": "user-stories/deploy-cloudflare-workers-us-12109.json" },
+    { "id": "deploy-cloudflare-workers-US-12110", "kind": "us", "path": "user-stories/deploy-cloudflare-workers-us-12110.json" },
+    { "id": "deploy-cloudflare-workers-US-12111", "kind": "us", "path": "user-stories/deploy-cloudflare-workers-us-12111.json" },
+    { "id": "deploy-cloudflare-workers-US-12112", "kind": "us", "path": "user-stories/deploy-cloudflare-workers-us-12112.json" },
+    { "id": "TAC-1301-deploy-cloudflare-workers-deploy-adapter", "kind": "tac", "path": "tacs/tac-1301-deploy-cloudflare-workers-deploy-adapter.json" },
+    { "id": "TAC-1302-deploy-cloudflare-workers-wrangler-manifest", "kind": "tac", "path": "tacs/tac-1302-deploy-cloudflare-workers-wrangler-manifest.json" },
+    { "id": "TAC-1303-deploy-cloudflare-workers-preview-url-resolver", "kind": "tac", "path": "tacs/tac-1303-deploy-cloudflare-workers-preview-url-resolver.json" },
+    { "id": "TAC-1304-deploy-cloudflare-workers-promote-gate", "kind": "tac", "path": "tacs/tac-1304-deploy-cloudflare-workers-promote-gate.json" },
+    { "id": "TAC-1305-deploy-cloudflare-workers-served-surface-verifier", "kind": "tac", "path": "tacs/tac-1305-deploy-cloudflare-workers-served-surface-verifier.json" },
+    { "id": "TAC-1306-deploy-cloudflare-workers-deploy-ci-workflows", "kind": "tac", "path": "tacs/tac-1306-deploy-cloudflare-workers-deploy-ci-workflows.json" },
+    {
+      "id": "ADR-1301-deploy-cloudflare-workers-deployment-target",
+      "kind": "adr",
+      "path": "adrs/adr-1301-deploy-cloudflare-workers-deployment-target.json",
+      "scope": "global",
+      "topic": "deploymentTarget"
+    },
+    { "id": "ADR-1302-deploy-cloudflare-workers-default-vendor", "kind": "adr", "path": "adrs/adr-1302-deploy-cloudflare-workers-default-vendor.json" },
+    { "id": "ADR-1303-deploy-cloudflare-workers-preview-vs-production", "kind": "adr", "path": "adrs/adr-1303-deploy-cloudflare-workers-preview-vs-production.json" },
+    { "id": "ADR-1304-deploy-cloudflare-workers-rollback-is-promote", "kind": "adr", "path": "adrs/adr-1304-deploy-cloudflare-workers-rollback-is-promote.json" },
+    { "id": "ADR-1305-deploy-cloudflare-workers-dev-mode-drift", "kind": "adr", "path": "adrs/adr-1305-deploy-cloudflare-workers-dev-mode-drift.json" }
+  ]
+}

package/blueprints/deploy-cloudflare-workers/contributions/adrs/adr-1301-deploy-cloudflare-workers-deployment-target.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-1301-deploy-cloudflare-workers-deployment-target",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "The project's deployment target is an artefact-upload + explicit-promote model, versions addressable at stable preview URLs, one adapter as the sole vendor caller",
+  "context": "Every non-trivial project ships to a running target. The failure modes accumulate the same way secrets ones do: an ad-hoc deploy shell script on a laptop, a CI step that pushes to production on every merge, a rollback path nobody has tested since the last incident, a review URL that is production itself. A single-source-of-truth model addresses the root cause: one manifest, one adapter, one upload verb, one promote verb, one served-surface verifier. This topic is scoped as a project-level global because a composing blueprint that holds a different opinion on the deployment shape (a container-image-per-commit + rolling-deploy blueprint, a monolithic-deploy blueprint, a serverless-function-per-endpoint blueprint) needs to conflict here and be resolved by the operator.",
+  "decision": "The project's deployment target is an artefact-upload + explicit-promote model. The Deploy Adapter (TAC-1301) is the sole caller of the deploy vendor; the wrangler manifest (TAC-1302) is the sole declaration of the deploy shape. Every merge to the main branch uploads a version through the adapter's `uploadVersion` verb and produces two addressable URLs (a per-version-id URL and a stable preview alias URL). Production only changes when the operator runs the `promote` workflow, which invokes `promoteVersion` on the adapter with a resolved version id. Rollback is a promote of a prior version id. Every promote runs the Served-surface Verifier against the production URL and fails the release on any probe breach. The vendor is pluggable; the interface is not. The default vendor is named in ADR-1302; alternatives supersede this ADR at the project level.",
+  "consequences": "One place to change vendors, one place to audit the deploy trail, one place to enforce the promote-is-explicit invariant. The manifest becomes a piece of documentation the project maintains as part of its normal change flow, which is the intended cost. Preview URLs and production URLs are always distinct and both discoverable through the adapter's `deploy status` verb. Composition with a blueprint that would import a vendor deploy SDK directly or that would auto-promote on merge conflicts here by design; the operator supersedes with a project-level ADR that either accepts the composed blueprint's shape or restates this one's.",
+  "alternativesConsidered": [
+    {
+      "name": "Merge-to-production (coupled upload + promote)",
+      "summary": "Every merge to main deploys straight to production; no distinct promote step; the vendor CLI's coupled `deploy` verb is called from the merge workflow.",
+      "reasonNotChosen": "This is the default state most small projects drift into and the state this blueprint exists to end. Every merge is a production act; a bad merge is a bad release; rollback is a git revert followed by a second merge-to-production; the review URL is production itself. Fine for a solo project on a low-stakes surface; the wrong default for anything with users. A project that legitimately wants the coupled shape can still apply this blueprint, restate ADR-1301 with a project-level ADR that permits coupled deploy, and set the `promote` workflow to trigger on merge. The blueprint does not fight the operator; it makes the default a distinct step."
+    },
+    {
+      "name": "Per-commit container image + rolling deploy on a Kubernetes-shaped target",
+      "summary": "Every merge builds a container image tagged by commit; a controller rolls the image out to a fleet of replicas; canary and progressive delivery layer above.",
+      "reasonNotChosen": "A legitimate shape at a larger scale; wrong altitude for the rcf-lite tier this blueprint targets. The trade against the artefact-upload + promote model is running the controller and the fleet; the payoff is finer-grained rollout control. A project outgrowing the artefact-upload model authors a project-level ADR that adopts a container-oriented target and applies a different deploy blueprint (a future `deploy-k8s-service` blueprint would sit at that altitude)."
+    },
+    {
+      "name": "Vendor-committed opinionated blueprint (Cloudflare Workers only, at the contract layer)",
+      "summary": "Ship the blueprint tied to Cloudflare Workers at the contract layer; the manifest is `wrangler.toml`, the CLI is `wrangler`, the URLs are workers.dev, no adapter port.",
+      "reasonNotChosen": "Locks the project to a vendor at the blueprint layer, which the doctrine of round-2 refuses (vendor default belongs at ADR-1302, contract belongs here). A composing blueprint or a project that wants a different vendor can only escape by removing this blueprint. Splitting the contract from the default keeps both moves available; the adapter port shape (see TAC-1301) is what makes a vendor swap a project-side ADR change plus an adapter reimplementation, not a blueprint change."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/adrs/adr-1302-deploy-cloudflare-workers-default-vendor.json

@@ -0,0 +1,35 @@
+{
+  "adrId": "ADR-1302-deploy-cloudflare-workers-default-vendor",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "The default deployment vendor is Cloudflare Workers via the wrangler CLI",
+  "context": "ADR-1301 fixes the contract; a project applying this blueprint still needs a working default vendor on day one. The rcf-lite tier this blueprint targets is small greenfield projects: a single Worker or a small handful, one small team or one solo operator, no ops team standing by. A default vendor for that tier should ship with zero infrastructure to run, a small operational footprint, a runtime whose primitive shape (edge-runtime request handler, bound resources) fits the artefact-upload + promote model, and a CLI that surfaces the upload/promote/list primitives the adapter needs. Larger deployments will supersede this decision with a different vendor; the point of a default is that day one works.",
+  "decision": "The default deployment vendor is Cloudflare Workers accessed through the `wrangler` CLI. The Deploy Adapter's default backing binding shells to `wrangler versions upload --preview-alias <alias>` for `uploadVersion`, `wrangler versions deploy <versionId>` for `promoteVersion`, `wrangler versions list` for `listVersions`, and the vendor's alias-lookup verb for `resolveNewestOfMain`. The wrangler manifest at the repo root is `wrangler.toml` (or `wrangler.jsonc` at operator preference). The preview URL patterns are the vendor's public URL contracts (per-version-id hostnames and per-alias hostnames on the workers.dev subdomain, or their custom-hostname mapped equivalents). The default is chosen because the zero-infrastructure floor is real for the target tier: no cluster to run, no image registry to feed, per-request cold-start amortised by the vendor, and the primitives ship the artefact-upload + promote split as first-class CLI verbs. Projects that outgrow the default supersede this ADR with a project-level ADR selecting a different deploy vendor and swap the adapter's vendor binding.",
+  "consequences": "The project ships with a working deploy flow on day one and does not force an ops decision before the first commit. The Cloudflare account, an account id, and an API token become first-class pieces of operator state the project manages (the token scoped to the account with the minimum verbs the adapter uses; the token is a secret bound through the secrets contract, not committed anywhere). The Worker runtime shape (edge-runtime, request-scoped, no long-lived process) is now a constraint the Worker's own code respects; a project that outgrows that shape supersedes ADR-1302 with a different vendor and adapts the code to the new runtime. Composition with a vendor-specific superseding blueprint (a project-authored `deploy-fly-io` blueprint minted on demand, a future `deploy-vercel` or `deploy-k8s-service` blueprint) is a project-level ADR change and a vendor-binding swap; the ADR-1301 contract stays intact.",
+  "alternativesConsidered": [
+    {
+      "name": "Fly.io",
+      "summary": "Deploy a Docker image to a Fly.io app; the vendor binding shells to `flyctl deploy`.",
+      "reasonNotChosen": "A genuinely different vendor shape (persistent VMs, per-region deploy control, a Docker image as the artefact). A reasonable pair candidate when a project wants a general-purpose deploy target with more control over the runtime. Not the day-one default because the edge-runtime shape of Cloudflare Workers fits more of the estate's actual live projects; a future `deploy-fly-io` blueprint mints on demand and composes cleanly through the ADR-1301 contract with a project-level supersede on ADR-1302."
+    },
+    {
+      "name": "Vercel",
+      "summary": "Deploy through Vercel's preview + production deploy model; the vendor binding shells to `vercel deploy` and `vercel promote`.",
+      "reasonNotChosen": "Vercel's preview-vs-production shape maps well onto the ADR-1301 contract. Reserved as a natural future blueprint on demand for projects that want Vercel's Next.js-first surface. Not the day-one default because the estate's live footprint is on Cloudflare Workers; a project on Vercel supersedes ADR-1302 and adapts the binding."
+    },
+    {
+      "name": "AWS Lambda / Google Cloud Run / other cloud-native FaaS",
+      "summary": "Deploy a function image or bundle to a hyperscaler's FaaS surface; the vendor binding shells to the cloud SDK's deploy verb.",
+      "reasonNotChosen": "Ties the project to one cloud at the deploy layer; the doctrine of ADR-1301 keeps the contract vendor-agnostic on purpose. Excellent choice for a project already committed to one cloud and using its identity model for deploy authentication; a project-level ADR supersede is the intended path."
+    },
+    {
+      "name": "Self-hosted VPS + a Docker Compose stack",
+      "summary": "SSH to a VPS and run `docker compose pull && docker compose up -d`; no vendor account, no per-request billing.",
+      "reasonNotChosen": "The self-hosted shape does not fit the artefact-upload + promote model without additional plumbing (a bespoke version-store, a bespoke promote step, a bespoke rollback path). A legitimate ecosystem choice for a project that wants full self-hosted control; a future `deploy-docker-compose-vps` blueprint would live at a different altitude and would not need to be `accountBound` at all."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/adrs/adr-1303-deploy-cloudflare-workers-preview-vs-production.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-1303-deploy-cloudflare-workers-preview-vs-production",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Preview URLs (per-version-id + stable alias) and production URL are distinct addressable surfaces; the promote step is what changes which one production maps to",
+  "context": "The failure mode this ADR closes is the collapsed URL: a project where the reviewer of a merged change and the visitor to the deployed application look at the same URL. When the preview surface and the production surface are the same string, every merge is a production act, review is what happens after users notice, and rollback is a second merge landing before enough users notice. The vendor's own primitive shape supports keeping them distinct: every uploaded version has a permanent per-version-id URL and a mutable stable-alias URL that can be pointed at the newest-of-main; production is the mapped custom domain (or the workers.dev production host) whose current version id changes only on an explicit deploy verb.",
+  "decision": "The blueprint mandates three URL kinds per Worker, all distinct hostnames, all discoverable through the Deploy Adapter's `deploy status` verb: (1) a per-VERSION-ID URL, unique per upload, permanent, useful for pinning a change-review link; (2) a STABLE PREVIEW ALIAS URL fixed to an operator-chosen alias string (the common default is `main`), always resolving to the newest-of-main uploaded version, useful for a persistent stakeholder-shareable link; (3) a PRODUCTION URL, declared under the wrangler manifest's `route`/`routes`/`workers_dev`/custom-domain stanza, changing which version it maps to only when a `promote` workflow runs. The Preview URL Resolver (TAC-1303) assembles the first two and refuses any alias string whose assembled host segment equals the production URL's host segment. The manifest loader refuses a wrangler config whose production route resolves to the preview alias URL host with `DEPLOY_URL_COLLAPSED`.",
+  "consequences": "Reviewers and stakeholders reach the newest-of-main at a persistent, memorable URL that never masquerades as production. Users hit production at a hostname that only changes version behind an explicit operator act. Change-review links are pinnable to a specific version id and never rot. The trade is one Worker now surfaces three URLs the project has to reason about (and the operator has to explain once when a new engineer joins); the payoff is the class of leaks-through-collapsed-URL is closed by the manifest's own validation, not by discipline.",
+  "alternativesConsidered": [
+    {
+      "name": "Preview alias URL and production URL as the same string with a query parameter switching mode",
+      "summary": "One hostname, `?preview=1` flips to the newest-of-main; production is the default response.",
+      "reasonNotChosen": "The query-parameter mode is trivially forgettable and does not survive a link-shortener, an email quoting, or a browser that strips query strings. The class of leak this ADR closes reopens exactly when the operator hands out the URL to someone who does not add the query parameter."
+    },
+    {
+      "name": "Per-version URLs only; no stable alias URL",
+      "summary": "Every upload gets a URL; the stable-shareable-review-URL story is 'copy the URL from the CI run'.",
+      "reasonNotChosen": "The per-version-id URL is essential for pinning a change; the stable alias URL is essential for a persistent 'the latest' surface stakeholders can bookmark. Shipping only the first fails the persistent-review use case; the vendor's own primitive supports both cheaply so both ship."
+    },
+    {
+      "name": "Preview URL = production URL under a special header",
+      "summary": "One hostname; the vendor routes to the newest-of-main when a specific request header is set (a signed cookie, an auth-only bypass).",
+      "reasonNotChosen": "Same class as the query-parameter option: the mode is invisible to the URL string and non-portable across link handoffs. It also couples the preview surface to an auth model that may not exist on day one."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/adrs/adr-1304-deploy-cloudflare-workers-rollback-is-promote.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-1304-deploy-cloudflare-workers-rollback-is-promote",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Rollback is a promote of a prior version id; the promote workflow is the sole ship-to-production path",
+  "context": "Rollback is one of the two shapes a project reaches for at exactly the wrong time to discover drift. The failure mode: a project ships a rollback verb once during setup, does not exercise it under pressure until an incident lands, then discovers the rollback path diverged from the ship path (a different vendor call, a different auth path, a different secret binding, a stale probe set, no served-surface verify). Framing rollback as a promote of a known-good version id keeps the audit shape uniform, the auth path identical, the probe set the same, and the served-surface verifier applied unconditionally.",
+  "decision": "Rolling production back to a previous version is not a distinct code path in the project. It is the same `promote` workflow triggered with the prior version id supplied as the `versionId` input. `listVersions` on the Deploy Adapter exposes the history with the currently-serving id marked so the operator can pick a known-good id. The deploy-log record for a rollback carries the same fields as any promote (`promotedVersionId`, `promotedBy`, `previousVersionId`, `promotedAt`). The vendor's own convenience verbs (a `wrangler rollback` shortcut when the default vendor is in play) are optional operator documentation; at the blueprint's contract level any such shortcut is a promote of a prior version id and the audit trail is identical. A project-authored `rollback` script that bypasses the Promote Gate, the deploy log, or the Served-surface Verifier is not permitted.",
+  "consequences": "One ship path serves every ship-to-production act: the merge-to-main promote, the hotfix promote of an out-of-sequence upload, the rollback promote of a prior version id. The audit trail is uniform; a query for 'every production change in the last week' answers the same way for a forward promote and a rollback. The trade: an operator responding to an incident with `wrangler rollback` at the command line (rather than through the `promote` workflow) bypasses the deploy-log record and the served-surface verifier; the blueprint documents this in the guide as a break-glass path that is not the recorded ship path.",
+  "alternativesConsidered": [
+    {
+      "name": "Bespoke `rollback` workflow with its own trigger and its own vendor call",
+      "summary": "A `rollback` workflow file separate from `promote`; triggers on manual dispatch; calls `wrangler rollback` (or the vendor's rollback verb) directly.",
+      "reasonNotChosen": "Two ship paths is one too many. The bespoke workflow drifts from the promote path over time (different secret binding, different logging, different probe set) and the drift is invisible until an incident. Keeping rollback on the same path as promote closes the class."
+    },
+    {
+      "name": "Rollback as a git revert + normal promote of the reverted-merge upload",
+      "summary": "Rollback is not a distinct verb at all; the operator opens a revert PR, waits for the merge, waits for the `build-and-upload` run, then promotes the new upload.",
+      "reasonNotChosen": "The revert flow works for cases where the incident is not urgent and the correct answer is a proper revert. It fails the incident case where the fix is a known-good version id from thirty minutes ago that the operator wants serving now. The chosen model handles both cases on one path."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/adrs/adr-1305-deploy-cloudflare-workers-dev-mode-drift.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-1305-deploy-cloudflare-workers-dev-mode-drift",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Local dev-mode is an emulator; ship-gate coverage never counts a dev-mode probe as a deployed observation",
+  "context": "Every deploy vendor of any complexity ships a local development mode: a process that runs on the developer's laptop and answers requests at a loopback port, approximating the deployed runtime. The failure mode is the emulator being treated as authoritative for ship coverage: an AC scoped `deployed` gets a test case that hits the dev-mode URL and passes there because the emulator handles the case, then fails on production because the emulator's regular-expression engine differs, or its static-assets ordering differs, or its binding-emulation surface differs. The RCF `deployed` scope tag exists precisely to close this class; the blueprint has to make the class refuseable at the coverage-gate layer.",
+  "decision": "The blueprint's `deployed`-scope ACs are only satisfied by a probe against an actual uploaded Worker: a per-version-id URL, a preview alias URL, or the production URL. A test case whose runtime target URL matches the dev-mode local pattern (`http://localhost:*`, `http://127.0.0.1:*`, or the vendor's local emulator loopback host) is refused as coverage for a `deployed`-scope AC with the code `DEPLOY_DEV_MODE_INADMISSIBLE`. Dev-mode remains a valid target for `runtime`-scope and `library`-scope ACs, and for developer-loop iteration; it is inadmissible for `deployed`-scope coverage. The project's runtime-verify catalogue names the dev-mode drift classes the operator authoring probes must be aware of; the catalogue is kept current against the vendor's release notes.",
+  "consequences": "The ship gate refuses a class of easy-to-hit false positives that would otherwise let a passing local test carry a broken deployed AC to green. The trade: some kinds of probe (a startup-behaviour probe, a code-shape probe) that would run cheaply against dev-mode now cost a full upload-plus-preview to satisfy the deployed-scope AC; the blueprint's guide names those as the classes the operator authors as `runtime`-scope ACs against dev-mode where the deployed observation adds no signal, and as `deployed`-scope ACs against the preview URL where it does.",
+  "alternativesConsidered": [
+    {
+      "name": "Treat dev-mode as fully-authoritative when a project-declared fidelity flag is set",
+      "summary": "The project declares 'dev-mode is close enough for our purposes' and the coverage gate accepts dev-mode probes for deployed-scope ACs.",
+      "reasonNotChosen": "The flag becomes an escape hatch that quietly disables the gate the RCF `deployed` scope tag exists to enforce. When the emulator drifts in a way the project does not yet know about, the flag masks it. If a project genuinely wants dev-mode as its runtime target, it authors those ACs as `runtime`-scope and does not need the flag."
+    },
+    {
+      "name": "Warn on dev-mode probes for deployed-scope ACs; do not refuse",
+      "summary": "The coverage gate emits a warning and counts the coverage anyway.",
+      "reasonNotChosen": "Warnings that do not refuse become noise. The class of drift this ADR closes is precisely the class where a project shipped for months on a warning nobody read. Refusing at the gate keeps the invariant load-bearing."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/requirements/deploy-cloudflare-workers-req-001.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "deploy-cloudflare-workers-REQ-001",
+  "prdId": "PRD-001",
+  "title": "The repo-root wrangler manifest is the single declaration of the Worker's deploy shape",
+  "description": "A `wrangler.toml` (or the equivalent `wrangler.jsonc`) at the repo root is the sole declaration of the Worker's deploy shape. It carries the Worker `name`, the entrypoint `main`, a pinned `compatibility_date`, any `compatibility_flags`, and every non-secret binding the runtime needs: KV namespaces, D1 databases, R2 buckets, Durable Object namespaces, static-assets binding, and non-secret environment variables. Secret bindings are NOT declared in the manifest (wrangler 4.x has no `[secrets]` block, no `secrets.required[]` list, and no empty-value binding entry for secrets); the vendor treats every env-accessor reference from Worker code as an implicit secret binding declaration and enforces its presence at deploy time by refusing `wrangler deploy` when a referenced secret has not been set on the target. Nothing outside the manifest may configure a non-secret binding at deploy time; a non-secret binding referenced from Worker code but absent from the manifest is a build refusal (an implicitly-referenced secret is caught by the vendor's own pre-deploy refusal instead). No secret VALUE ever appears in the manifest.",
+  "category": "technical",
+  "domain": "deploy",
+  "priority": "must",
+  "rationale": "A scattered deploy configuration is the failure mode this blueprint exists to end. If bindings are declared in ad-hoc scripts, CI environment blocks, or hand-edited before deploy, no one knows what the deployed Worker actually looks like. A single manifest at a known path makes the deploy shape legible to humans, to CI gates, to the vendor's deploy step, and to review of every change that touches a binding.",
+  "tags": [
+    "blueprint:deploy-cloudflare-workers",
+    "category:01-manifest"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/requirements/deploy-cloudflare-workers-req-002.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "deploy-cloudflare-workers-REQ-002",
+  "prdId": "PRD-001",
+  "title": "One deploy adapter module is the sole caller of the deploy CLI",
+  "description": "The project exposes a single Deploy Adapter module that wraps the deploy CLI (the vendor's `wrangler` binary when the default vendor is in play). Every path that uploads a version, promotes a version, lists versions, or reads deploy state routes through this module. Nothing else in the project source tree spawns the CLI, imports the vendor SDK, or issues an HTTP call to the vendor's deploy API. The module exposes a fixed named-verb surface (`uploadVersion`, `promoteVersion`, `listVersions`, `resolveNewestOfMain`, `describeVersion`) that is stable across the blueprint's major version.",
+  "category": "technical",
+  "domain": "deploy",
+  "priority": "must",
+  "rationale": "A vendor-neutral adapter port keeps the project free to change deploy vendors under the same interface. It also removes the class of bugs where two paths call the CLI with different flags and drift silently. One module, one boundary, one behaviour. The blueprint mandates the CONTRACT and defaults the VENDOR; a project that supersedes the default vendor swaps only the adapter's implementation.",
+  "tags": [
+    "blueprint:deploy-cloudflare-workers",
+    "category:02-adapter-boundary"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/requirements/deploy-cloudflare-workers-req-003.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "deploy-cloudflare-workers-REQ-003",
+  "prdId": "PRD-001",
+  "title": "Every merge to the main branch uploads a Worker version addressable at a stable preview alias URL",
+  "description": "The CI pipeline runs a build+upload step on every merge to the main branch. The step produces an uploaded Worker version (the vendor's version primitive) with two addressable URLs recorded on the CI run: a permanent per-version-id URL, and a stable ALIAS URL fixed to the string `main` (or an equivalent operator-chosen alias) that always resolves to the newest-of-main upload. The alias URL never changes across re-uploads; the version-id URL is unique per upload and durable. The uploaded version does NOT serve production traffic; it exists only at the preview URLs until an explicit promote step runs. The version id and both URLs are surfaced in the CI run output.",
+  "category": "functional",
+  "domain": "deploy",
+  "priority": "must",
+  "rationale": "Uploading a version on merge without promoting it separates two concerns most teams tangle at their cost: 'is the artefact built and cleanly uploaded' from 'is production serving it now'. The stable preview alias URL is the shape a stakeholder can bookmark and share; the version-id URL is the shape a change-review workflow references verbatim. Both matter and both come from the same upload step.",
+  "tags": [
+    "blueprint:deploy-cloudflare-workers",
+    "category:03-preview-upload"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/requirements/deploy-cloudflare-workers-req-004.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "deploy-cloudflare-workers-REQ-004",
+  "prdId": "PRD-001",
+  "title": "Production only changes via an explicit promote step; no upload path auto-promotes",
+  "description": "Production traffic serving is a distinct action from uploading a version. No CI path may take an uploaded version and route production traffic to it as a side effect of the upload. Production only changes when a Promote step runs and names the version id to serve. The promote step is authored as a separate CI workflow triggered by explicit operator action (`workflow_dispatch` on GitHub Actions or the equivalent manual-trigger primitive on other CI platforms). The promote workflow accepts one input: `versionId` (empty defaults to the newest-of-main resolved from the preview alias); every promote emits a structured record naming the version id promoted, the operator principal that triggered the workflow, the previously-serving version id, and the timestamp.",
+  "category": "functional",
+  "domain": "deploy",
+  "priority": "must",
+  "rationale": "The failure mode this ends: a merge lands, the CI pipeline deploys straight to production, and nobody notices the bad release until the phone rings. Decoupling upload from promote makes the ship-to-production act a first-class human decision. The default of newest-of-main keeps the promote fast for the common case; the explicit versionId keeps rollback and hotfix promotes on the same code path.",
+  "tags": [
+    "blueprint:deploy-cloudflare-workers",
+    "category:04-explicit-promote"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/requirements/deploy-cloudflare-workers-req-005.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "deploy-cloudflare-workers-REQ-005",
+  "prdId": "PRD-001",
+  "title": "Preview and production surfaces are addressable at distinct URLs both discoverable from the manifest",
+  "description": "The deployed application is reachable at two distinct kinds of URL: a PREVIEW surface (per-version alias URLs and per-version-id URLs, both provided by the vendor at upload time on the workers.dev subdomain) and a PRODUCTION surface (a route or custom domain declared in `wrangler.toml` under a `route`/`routes`/`workers_dev` block, or a mapped custom hostname). A `deploy status` verb on the Deploy Adapter surfaces both URL kinds for the current state without requiring an operator to consult the vendor dashboard. The preview alias URL and the production URL are never the same string; a project that would collapse them into one URL is a misconfiguration the adapter refuses.",
+  "category": "functional",
+  "domain": "deploy",
+  "priority": "must",
+  "rationale": "Two URLs, two purposes. The preview URL is where a change lives before promote, where stakeholder review happens, where end-to-end probes hit the newest-of-main. The production URL is where users hit the promoted version. Collapsing them is the failure mode where reviewing a change means reviewing production; keeping them distinct is what makes the promote step meaningful.",
+  "tags": [
+    "blueprint:deploy-cloudflare-workers",
+    "category:05-url-model"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/requirements/deploy-cloudflare-workers-req-006.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "deploy-cloudflare-workers-REQ-006",
+  "prdId": "PRD-001",
+  "title": "Secret bindings resolve through the project's secrets contract, never plaintext in the wrangler manifest",
+  "description": "Every secret the Worker reads at runtime is referenced implicitly through the runtime's env accessor (in the default JS/TS Worker, `env.<NAME>`); wrangler 4.x has no `[secrets]` block, no `secrets.required[]` list, and no empty-value binding entry for secrets, and the vendor treats every such env-accessor reference from Worker code as an implicit secret binding declaration, refusing `wrangler deploy` when a referenced secret has not been set on the target. Each such name is populated on the deploy target through the vendor's own secret-set flow (first-deploy via `wrangler deploy --secrets-file <tmp>`, steady-state via `wrangler secret put <NAME>`; see `assets/wrangler-samples/bootstrap-vs-steady-state.md`). The value is sourced from the project's secrets contract (as fixed by the `security-secrets-management` blueprint at slug `security-secrets-management` when applied, or by the equivalent project-authored contract). No secret VALUE ever lives in `wrangler.toml`, in a committed environment file, in a CI variable readable outside the promote job, or in the CI run's captured logs. A CI-side redactor scrubs any log line that would emit a resolved secret value.",
+  "category": "security",
+  "domain": "deploy",
+  "priority": "must",
+  "rationale": "Secrets in deploy config is one of the two shapes of leak this blueprint refuses (the other is production auto-promote). Declaring bindings by name only forces the value to arrive through a controlled channel and keeps the manifest safe to review in a PR. The blueprint mandates the CONTRACT (values arrive through the secrets pipeline); the vendor default binds through `wrangler secret put`.",
+  "tags": [
+    "blueprint:deploy-cloudflare-workers",
+    "category:06-secrets-boundary"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/requirements/deploy-cloudflare-workers-req-007.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "deploy-cloudflare-workers-REQ-007",
+  "prdId": "PRD-001",
+  "title": "A build-and-upload CI workflow runs on every merge to the main branch and records the uploaded version id",
+  "description": "A CI workflow named `build-and-upload` (or the project's chosen equivalent) triggers on `push` to the main branch (and on any linear-history proxy the project uses). It checks the tree out, installs dependencies at the pinned versions, runs the project's build step, then invokes the Deploy Adapter's `uploadVersion` verb naming the operator-chosen preview alias string. On success it writes the uploaded version id, the version-id URL, and the preview alias URL to the CI run's job summary and to a structured output the promote workflow reads. The workflow authenticates to the vendor through named CI secrets (a vendor API token and a vendor account id); the token is scoped to the Worker's account and never appears in any log line.",
+  "category": "functional",
+  "domain": "deploy",
+  "priority": "must",
+  "rationale": "The build-and-upload workflow is the mechanism half of REQ-003: every merge produces an uploaded, addressable version, without touching production. Making the version id and URLs discoverable in the CI run output is what makes the promote step's `newest-of-main` default computable and what makes the change reviewable at the preview URL by anyone with the CI run link.",
+  "tags": [
+    "blueprint:deploy-cloudflare-workers",
+    "category:07-ci-build-upload"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/requirements/deploy-cloudflare-workers-req-008.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "deploy-cloudflare-workers-REQ-008",
+  "prdId": "PRD-001",
+  "title": "A promote CI workflow runs on explicit manual trigger and accepts an optional versionId input",
+  "description": "A CI workflow named `promote` (or the project's chosen equivalent) triggers only on manual operator action (`workflow_dispatch` on GitHub Actions or the equivalent explicit-trigger primitive on other CI platforms). It accepts one input field `versionId`: when supplied, the workflow promotes that exact version; when blank, the workflow calls the Deploy Adapter's `resolveNewestOfMain` verb to look up the current version id behind the preview alias and promotes THAT. It then invokes `promoteVersion` on the Deploy Adapter and, on success, invokes the served-surface verifier (REQ-010) before declaring the run successful. The workflow authenticates through the same named vendor CI secrets as `build-and-upload` and emits a structured record of the promote for the deploy log.",
+  "category": "functional",
+  "domain": "deploy",
+  "priority": "must",
+  "rationale": "One workflow for both cases keeps the promote path narrow and reviewable. The empty-input default answers the common case (ship what merged); the explicit-id input answers hotfix promotes and rollbacks without a second code path. Every promote runs through the same served-surface verifier gate so no promote can quietly ship a broken version.",
+  "tags": [
+    "blueprint:deploy-cloudflare-workers",
+    "category:08-ci-promote"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/requirements/deploy-cloudflare-workers-req-009.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "deploy-cloudflare-workers-REQ-009",
+  "prdId": "PRD-001",
+  "title": "Rollback is a promote of a prior version id; the promote workflow is the sole ship-to-production path",
+  "description": "Rolling production back to a previous version is not a distinct code path in the project's deploy tooling. It is the same `promote` workflow (REQ-008) triggered with the prior version id supplied as the `versionId` input. The prior version id is discoverable by calling the Deploy Adapter's `listVersions` verb, which returns the recent history with the currently-serving id marked. A project may surface a `wrangler rollback` shortcut in operator documentation for convenience, but at the contract level the shortcut is a promote of the second-most-recent version id and the audit trail records it the same way. No project-authored `rollback` verb bypasses the promote workflow's structured record or the post-promote verifier.",
+  "category": "functional",
+  "domain": "deploy",
+  "priority": "must",
+  "rationale": "Two ship paths is one too many. If rollback has its own bespoke script, the script drifts from the promote path in exactly the moments an incident is the wrong time to discover drift. Framing rollback as a promote of a known-good version id keeps the ship path narrow, the audit shape uniform, and the post-promote verifier applied unconditionally.",
+  "tags": [
+    "blueprint:deploy-cloudflare-workers",
+    "category:09-rollback"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}