rcf-lite 0.11.0 → 0.13.0

package/blueprints/deploy-cloudflare-workers/assets/ci-workflows/promote.yml.md

@@ -0,0 +1,120 @@
+# promote workflow (GitHub Actions form)
+
+Reference shape for the `promote` workflow. Every value with `<...>` is a placeholder the project fills. The workflow triggers only on `workflow_dispatch`, accepts an optional `versionId` input, invokes the Promote Gate, and honours the Served-surface Verifier's pass or fail.
+
+```yaml
+# .github/workflows/promote.yml
+name: promote
+
+on:
+  workflow_dispatch:
+    inputs:
+      versionId:
+        description: "Version id to promote. Leave blank for newest-of-main."
+        required: false
+        type: string
+
+concurrency:
+  group: promote
+  cancel-in-progress: false
+
+jobs:
+  promote:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+
+      - uses: pnpm/action-setup@v4
+
+      - name: Install pinned dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Promote and verify
+        id: promote
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          PROMOTED_BY: ${{ github.actor }}
+        run: node scripts/deploy/promote.mjs --version-id "${{ inputs.versionId }}"
+
+      - name: Write run summary
+        if: always()
+        run: |
+          {
+            echo "## Promote outcome"
+            echo ""
+            echo "- promotedVersionId: \`${{ steps.promote.outputs.promotedVersionId }}\`"
+            echo "- versionSha:        \`${{ steps.promote.outputs.versionSha }}\`"
+            echo "- previousVersionId: \`${{ steps.promote.outputs.previousVersionId }}\`"
+            echo "- promotedBy:        \`${{ github.actor }}\`"
+            echo "- outcome:           \`${{ steps.promote.outcome }}\`"
+          } >> "$GITHUB_STEP_SUMMARY"
+```
+
+## The Node.js orchestration script
+
+`scripts/deploy/promote.mjs` is the project-authored script the workflow invokes. Its body:
+
+```javascript
+#!/usr/bin/env node
+// Invoked by the promote workflow. Wraps the Promote Gate (TAC-1304).
+// Resolves the newest-of-main when --version-id is blank; refuses an unknown
+// version id before any vendor call; invokes the Served-surface Verifier
+// after promoteVersion returns success; writes structured outputs.
+
+import { appendFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { createDeployAdapter } from '../../src/deploy/adapter.mjs';
+import { createServedSurfaceVerifier } from '../../src/deploy/verifier.mjs';
+import { createPromoteGate } from '../../src/deploy/promote-gate.mjs';
+
+const { values } = parseArgs({
+  options: { 'version-id': { type: 'string', default: '' } }
+});
+
+const adapter = createDeployAdapter();
+const verifier = createServedSurfaceVerifier({ adapter });
+const gate = createPromoteGate({ adapter, verifier });
+
+try {
+  const record = await gate.promote({
+    versionId: values['version-id'] || null,
+    promotedBy: process.env.PROMOTED_BY || 'unknown'
+  });
+  const out = process.env.GITHUB_OUTPUT;
+  if (out) {
+    // promotedVersionId is the vendor-assigned version UUID (the string
+    // `wrangler versions deploy` takes). versionSha is the git commit sha
+    // of the source tree the promoted version was built from; the verifier
+    // substitutes this into the health probe's `expectShape.versionSha`
+    // slot to reconcile served against promoted. Both identifiers are
+    // required on the promote record; they are never equal.
+    appendFileSync(out, `promotedVersionId=${record.promotedVersionId}\n`);
+    appendFileSync(out, `versionSha=${record.versionSha}\n`);
+    appendFileSync(out, `previousVersionId=${record.previousVersionId}\n`);
+  }
+  process.exit(0);
+} catch (err) {
+  console.error(`${err.code || 'PROMOTE_FAILED'}: ${err.message}`);
+  process.exit(1);
+}
+```
+
+## Reader notes
+
+- The Worker being promoted must have been bootstrapped once with `wrangler deploy --secrets-file <path>` before the first `wrangler versions upload` from `build-and-upload` can succeed; see `assets/wrangler-samples/bootstrap-vs-steady-state.md`. Steady-state ship (this workflow's world) assumes bootstrap has already run.
+- The promote record carries two identifiers: `promotedVersionId` (vendor-assigned UUID, the value `wrangler versions deploy` took) and `versionSha` (git commit sha the promoted version was built from). The verifier reconciles the served health-probe body's `versionSha` against the promote record's `versionSha`, NOT against `promotedVersionId`; see `assets/verification/served-surface-probes.md` for the boundary.
+- Triggers ONLY on `workflow_dispatch`. No `push`, no `pull_request`, no `schedule`. AC-12104-2 refuses any other trigger; AC-12104-1 refuses any workflow that pushes-to-main AND promotes.
+- The `versionId` input is optional (`required: false`). Blank defaults to newest-of-main, resolved by the Promote Gate through the Deploy Adapter. AC-12108-1 requires exactly one optional input; AC-12108-2 requires the blank case to resolve through `resolveNewestOfMain`.
+- The Promote Gate refuses a `versionId` absent from `listVersions()` BEFORE any vendor promote call. AC-12108-3 requires the refusal to exit non-zero with `DEPLOY_VERSION_NOT_FOUND` and to leave no promote record.
+- The Served-surface Verifier runs after `promoteVersion` returns success. A verifier failure exits non-zero with `PROMOTE_VERIFY_FAILED` and refuses to mark the release successful. AC-12110-3 requires this.
+- `PROMOTED_BY: ${{ github.actor }}` binds the operator principal from the trigger context into the deploy-log record. AC-12104-3 requires the record.
+- To rollback: invoke this workflow with the prior version id supplied as the `versionId` input. AC-12109-1 requires no separate rollback path. AC-12109-3 requires rollback promotes to run the same verifier.
+- Additional approver-gating (a two-person integrity policy on every promote) layers above `workflow_dispatch` through the platform's manual-approval primitive; the blueprint's ADR set does not fix that policy.

package/blueprints/deploy-cloudflare-workers/assets/verification/served-surface-probes.md

@@ -0,0 +1,90 @@
+# Served-surface probe pattern
+
+Reference shape for the Served-surface Verifier's probe declaration. Every value with `<...>` is a placeholder the project fills.
+
+## Two identifiers, one probe body
+
+The verifier reconciles a promoted version against what production is serving. The reconciliation compares two named identifiers the vendor and the project both know:
+
+| Identifier | What it is | Where it lives | Written by |
+|---|---|---|---|
+| `promotedVersionId` | The vendor-assigned version UUID (`06839e70-1f7c-414f-99a9-babf3969efca`), the string `wrangler versions deploy` takes as its positional argument | The promote record's `promotedVersionId` field, emitted by the Promote Gate on every promote | The vendor CLI's response to `wrangler versions deploy`, captured by the Deploy Adapter's `promoteVersion` return value |
+| `versionSha` | The git commit sha of the source tree the version was built from (the 40-character hex the `github.sha` context carries), baked into the built bundle by `build-and-upload` | The bundle as a build-time constant AND the Worker's health-probe response body | The `build-and-upload` workflow, which sets `BUILD_VERSION_SHA=${{ github.sha }}` before the build step |
+
+The two identifiers name two different things on two different systems. They are NEVER equal by construction: `promotedVersionId` is a UUID assigned by the vendor at upload time; `versionSha` is a git sha assigned by the source-control system at commit time. Any teaching that "substitutes the promoted id into the probe body" and expects a match is wrong on the wire.
+
+The verifier's reconciliation is: the Promote Gate captures BOTH identifiers on every promote (the vendor returns `promotedVersionId`; the project pairs it with the `versionSha` of the source-tree the version was built from, carried on the promote record's `versionSha` field). At verify time, the verifier substitutes the promote record's `versionSha` into the probe's `expectShape.versionSha` slot and refuses the probe when the served body's `versionSha` does not match.
+
+## The probe declaration
+
+```javascript
+// src/deploy/verify-config.mjs
+// Consumed by the Served-surface Verifier (TAC-1305). The health probe is
+// mandatory; add project smoke probes for surfaces where a served-surface
+// check adds signal a health probe does not.
+
+export const probes = [
+  {
+    path: '/healthz',
+    method: 'GET',
+    successStatus: [200],
+    expectShape: {
+      // <PROMOTED_VERSION_SHA> is substituted at verify time from the
+      // promote record's `versionSha` field (the git sha), NOT from the
+      // promote record's `promotedVersionId` (the vendor UUID). The two
+      // are different identifiers on two different systems.
+      versionSha: '<PROMOTED_VERSION_SHA>'
+    }
+  },
+  {
+    // A project smoke probe: a read that exercises one binding and one
+    // Worker code path a health probe does not. Keep it stateless, idempotent,
+    // and observable in one round trip.
+    path: '/api/status',
+    method: 'GET',
+    successStatus: [200],
+    expectShape: {
+      ok: true
+    }
+  }
+];
+
+export const retryBounds = {
+  // At most six attempts per probe over at most sixty seconds; per-request
+  // timeout at most five seconds. AC-12110-1 refuses a bound looser than these.
+  maxAttemptsPerProbe: 6,
+  windowMs: 60_000,
+  perRequestTimeoutMs: 5_000
+};
+```
+
+## The verifier's runtime shape
+
+The Served-surface Verifier consumes the config through the `probeConfig` interface (TAC-1305). Per probe:
+
+1. Compose the request against the target URL (from `probeUrl('production', null)` for a promote verify, from `probeUrl('alias', <alias>)` for a preview-only verify).
+2. Send the request; on transport error or on a status outside `successStatus`, sleep with an exponential-shaped backoff bounded by `windowMs / maxAttemptsPerProbe`.
+3. On a status in `successStatus`, parse the response body as JSON and check every key in `expectShape` matches the value in the response. `<PROMOTED_VERSION_SHA>` in `expectShape` is substituted at verify time with the promote record's `versionSha` field (the git commit sha the promoted version was built from).
+4. Pass on the first attempt whose status AND body-shape match.
+5. Fail the verify when any probe exhausts `maxAttemptsPerProbe` or when the cumulative elapsed time exceeds `windowMs`, whichever comes first. Emit `{ probePath, status, elapsedMs, outcome: 'failed', versionShaSeen }` on the result sink.
+
+## Compose boundary with observability-probe-endpoints
+
+The `/healthz` probe declared above is a DEPLOY-blueprint surface. Its body carries build provenance (`versionSha`, `builtAt`, `ciRunUrl`) because the verifier's reconciliation requires it (AC-12112-3). That body shape is NOT a supervisor-integration probe response; it is the deploy blueprint's own provenance readback.
+
+The `observability-probe-endpoints` blueprint contributes an operator-supervised probe interface derived from a target integration profile (`kubernetes`, `loadBalancer`, `uptimeMonitor`, `systemd`, `dockerHealthcheck`, `reverseProxy`). Every profile mandates a minimal response contract: `loadBalancer` requires an empty body; `kubernetes` requires exactly `{"status": "pass"|"fail"}`; the profile validator refuses any override that would add a field beyond the enumerated set. That contract's audience is the external supervisor whose conventions drive the wire shape; adding build-provenance fields to it would leak reconnaissance value to unintended readers and would fail the profile validator.
+
+When both blueprints compose, the project runs TWO probe surfaces with distinct paths and distinct contracts:
+
+- One `/health` (or the profile-declared path) owned by `observability-probe-endpoints`, whose body is minimal per its profile.
+- One `/healthz` (or the deploy-blueprint's chosen path, distinct from the profile's) owned by `deploy-cloudflare-workers`, whose body carries `{ versionSha, builtAt, ciRunUrl }` for the verifier.
+
+The two surfaces coexist on purpose; the deploy verifier never hits the profile-owned path and the external supervisor never hits the deploy-owned path. A project unsure which path is which picks distinct strings at apply time (`/health` for the profile, `/healthz` for the deploy verifier; or `/health` for the profile and `/build-info` for the deploy verifier) and documents both on the project's ADR set. Collapsing the two onto one path is not supported; the deploy verifier's provenance body would fail the profile validator, and stripping provenance from the body would break the verifier's reconciliation.
+
+## Reader notes
+
+- A dev-mode local URL (`http://localhost:<port>`, `http://127.0.0.1:<port>`) is refused by the verifier with `DEPLOY_DEV_MODE_INADMISSIBLE`. AC-12111-1 makes this a hard refusal at the verifier layer; AC-12111-2 accepts the vendor's preview and production URL patterns.
+- The health probe's response body carries `{ versionSha, builtAt, ciRunUrl }`. The Worker reads these at request time from the build-time constants injected by `build-and-upload`. AC-12112-2 requires the shape; AC-12112-3 makes the `versionSha` field the verifier's evidence that the promoted version is the version being served.
+- A probe path that returns 200 with the WRONG `versionSha` fails the probe. A stale response served by a routing layer that has not converged yet fails the probe; the retry window buys the propagation-lag window; a full exhaustion fails the release.
+- The project may add authenticated smoke probes; each carries an operator-chosen auth binding (a signed request header, a probe-only token) that lives in the secrets contract, not in this file. The verifier does not carry an `Authorization` header that would bypass a production auth layer; a probe surface that requires auth is exposed on a project-declared unauthenticated path (a signed-header contract for probes only, with a rotation cadence tied to the deploy-log).
+- The `/healthz` path (or whichever path the project picks) MUST be listed in `[assets] run_worker_first` when the Worker declares an `[assets]` binding whose directory contains any file that could shadow the path. Without the listing, the assets pipeline may serve a stale (or absent) response before the fetch handler runs, and the verifier reads a shape that is not the Worker's answer; see `wrangler-toml-shape.md` for the discipline.

package/blueprints/deploy-cloudflare-workers/assets/wrangler-samples/bootstrap-vs-steady-state.md

@@ -0,0 +1,87 @@
+# First-deploy bootstrap versus steady-state upload
+
+The blueprint's ship path (`wrangler versions upload` on every merge, `wrangler versions deploy <versionId>` on operator-triggered promote) works only against a Worker that already exists on the vendor. A fresh Worker has to be bootstrapped once with a different verb. This asset documents both flows.
+
+## Why the distinction exists
+
+The vendor refuses `wrangler versions upload` against 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 vendor also refuses `wrangler secret put <NAME>` against a Worker that does not yet exist:
+
+```
+This Worker does not exist yet, so secrets cannot be set in advance
+with 'wrangler secret put'.
+```
+
+And the vendor refuses `wrangler deploy` when the Worker code references secret bindings that have not been set:
+
+```
+The following required secrets have not been set: <NAME>, <NAME>, ...
+```
+
+The three refusals compose into one bootstrap constraint: the FIRST deploy has to (a) create the Worker, (b) set every referenced secret in the same act. Only `wrangler deploy --secrets-file <path>` satisfies both.
+
+## The bootstrap flow (once per Worker)
+
+Run this once, from an operator machine with the vendor credentials in the environment. The secrets file is a temp file in a directory the repo ignores; it must not touch the working tree and must not survive the run.
+
+```bash
+# 1. Compose a temp secrets file. Sourced from the project's secrets
+#    contract (see the security-secrets-management blueprint or the
+#    equivalent project-authored pipeline). NO plaintext in the shell
+#    history; use a here-doc into a temp path outside the repo.
+TMP_SECRETS="$(mktemp -t bootstrap-secrets.XXXXXX.json)"
+trap 'rm -f "$TMP_SECRETS"' EXIT
+
+# 2. Write the JSON object of secret NAME -> VALUE the Worker needs.
+#    The value strings are resolved from the secrets contract; this
+#    example shows the shape, not the values.
+cat > "$TMP_SECRETS" <<'JSON'
+{
+  "<SECRET_NAME_1>": "<value-from-secrets-contract>",
+  "<SECRET_NAME_2>": "<value-from-secrets-contract>"
+}
+JSON
+
+# 3. First deploy: creates the Worker on the vendor AND sets every
+#    secret in one atomic act.
+wrangler deploy --secrets-file "$TMP_SECRETS"
+
+# 4. The trap removes the temp file. Verify it's gone.
+[ ! -f "$TMP_SECRETS" ] || { echo "bootstrap-secrets leaked" >&2; exit 1; }
+```
+
+After the bootstrap deploy returns success, the Worker exists on the vendor, every referenced secret is set, and the steady-state ship path becomes available.
+
+## The steady-state flow (every merge and every operator-triggered promote)
+
+Once the Worker exists, the blueprint's ship path is the only one used:
+
+```bash
+# On every merge to main (build-and-upload workflow, see
+# `ci-workflows/build-and-upload.yml.md`):
+wrangler versions upload --preview-alias main
+
+# On operator-triggered promote (promote workflow, see
+# `ci-workflows/promote.yml.md`):
+wrangler versions deploy <versionId>
+
+# When a secret's value has to rotate, steady-state is `wrangler secret
+# put <NAME>` invoked from a CI step whose environment has the new value
+# from the secrets contract. No temp file, because the Worker already
+# exists.
+wrangler secret put <NAME>
+```
+
+## Reader notes
+
+- The bootstrap flow is a one-time operator act. The blueprint's Deploy Adapter (TAC-1301) does NOT wrap it; the adapter's verbs are the steady-state surface. A project that automates bootstrap wraps this shell flow in a project-local script under `scripts/deploy/` and gates it behind an explicit operator invocation.
+- The temp secrets file is the only shape wrangler 4.x accepts for pre-existence secret provisioning. Any alternative (`wrangler secret put` before `wrangler deploy`, an interactive prompt, environment-variable smuggling into `wrangler.toml`) either fails or leaks the value.
+- The `--secrets-file` path must be outside the repo working tree, deleted on shell exit, and never emitted to stdout. The bootstrap shell above uses `mktemp` and a `trap` to enforce this.
+- After bootstrap, the CI workflows never invoke `wrangler deploy`. Every version reaches the vendor via `wrangler versions upload` (which does NOT change the served version) and every production change rides `wrangler versions deploy <versionId>` from the promote workflow. Preserving this discipline is what keeps the promote-is-explicit invariant load-bearing.
+- A project that superseded the default vendor (per ADR-1302) with a different target (Fly.io, Vercel, a hyperscaler's FaaS, a self-hosted target) authors an equivalent bootstrap flow against that vendor's own create-and-provision primitives; the WHEN (once per environment, before steady-state) stays; the WHAT (which CLI verb, which primitive) is vendor-specific.

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"
+}