rcf-lite 0.12.0 → 0.14.0

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "deploy-cloudflare-workers-REQ-010",
+  "prdId": "PRD-001",
+  "title": "Every promote runs bounded served-surface probes against the production URL and fails the release on breach",
+  "description": "Immediately after a successful `promoteVersion` call, the promote workflow (REQ-008) invokes the Served-surface Verifier (TAC-1305). The verifier hits a fixed set of probe paths on the PRODUCTION URL (not the preview URL) with bounded retry semantics: at least three probe paths chosen by the project, each requested at most six times over at most sixty seconds, with a per-request timeout at most five seconds. A probe passes when the response status is in the project-declared success set and the response body carries the expected shape (for a health probe, a body containing the version-id string that was just promoted; for a smoke path, a project-declared invariant string). If any probe path fails every retry the workflow exits non-zero with a stable code `PROMOTE_VERIFY_FAILED`, records the failed probe path, the response status seen, the elapsed time, and refuses to mark the release successful.",
+  "category": "nonFunctional",
+  "domain": "deploy",
+  "priority": "must",
+  "rationale": "A promote that does not verify the served surface is a promote taken on trust of the vendor's own success signal. The vendor's success signal covers 'the version is now the serving version', which is not the same as 'the served surface answers correctly'. Bounded retries are the discipline that catches propagation-lag class failures without turning transient blips into a stuck workflow.",
+  "tags": [
+    "blueprint:deploy-cloudflare-workers",
+    "category:10-verify-served"
+  ],
+  "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-011.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "deploy-cloudflare-workers-REQ-011",
+  "prdId": "PRD-001",
+  "title": "Local dev-mode is an emulator; the ship gate never treats a dev-mode signal as authoritative",
+  "description": "The vendor's local development mode (`wrangler dev` on the default vendor) is an emulator, not the deployed runtime. It approximates the runtime shape but carries known behavioural differences (differing regular-expression engines, differing static-assets ordering, differing binding-emulation surface, differing timeout behaviour). The project may use dev-mode for developer-loop iteration. The ship gate does not: no test authored against `wrangler dev` counts as passing coverage for a deployed AC; the coverage tag `deployed` on any AC requires the served-surface probe hit an actual uploaded Worker (preview URL is fine; production URL is fine; dev-mode local URL is not). A project-side lint or CI check catches an AC-to-TC binding that attempts to substitute a dev-mode observation for a deployed one.",
+  "category": "technical",
+  "domain": "deploy",
+  "priority": "must",
+  "rationale": "The reason a runtime-verify layer exists in RCF is that codebase-level tests cannot cover deployed behaviour. Letting an emulator stand in for the deployed runtime re-opens exactly the class of drift the deployed-scope tag exists to close. Naming the class of dev-mode-only tests inadmissible-as-deployed-coverage is the discipline.",
+  "tags": [
+    "blueprint:deploy-cloudflare-workers",
+    "category:11-dev-mode-drift"
+  ],
+  "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-012.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "deploy-cloudflare-workers-REQ-012",
+  "prdId": "PRD-001",
+  "title": "Every uploaded version carries build-provenance attributes readable at runtime",
+  "description": "Every version uploaded by the `build-and-upload` workflow carries three provenance attributes accessible from within the Worker at runtime: the commit sha of the source tree the version was built from, the ISO 8601 timestamp of the build, and the URL of the CI run that produced the upload. The three values are injected into the Worker's build (as build-time constants baked into the bundle, as `vars` populated by the CI step, or as a runtime-readable metadata surface the Deploy Adapter's `describeVersion` verb returns; the project picks the mechanism). A health probe exposes them on a fixed path; the response body carries a stable JSON shape whose `versionSha`, `builtAt`, and `ciRunUrl` fields are the served-surface verifier's evidence that the promoted version is the version it thinks it promoted.",
+  "category": "technical",
+  "domain": "deploy",
+  "priority": "must",
+  "rationale": "Without provenance the served-surface verifier cannot tell a successful promote from a stale response served by a routing layer that has not converged. Baking provenance into the version and surfacing it on a health probe is what makes the verifier's success signal load-bearing; it is also what makes incident triage answerable in one request.",
+  "tags": [
+    "blueprint:deploy-cloudflare-workers",
+    "category:12-provenance"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/tacs/tac-1301-deploy-cloudflare-workers-deploy-adapter.json

@@ -0,0 +1,54 @@
+{
+  "tacId": "TAC-1301-deploy-cloudflare-workers-deploy-adapter",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Deploy Adapter",
+  "purpose": "The one project module that talks to the deploy vendor. Wraps the vendor's CLI (or SDK) behind a fixed named-verb surface every other module imports. Uploads versions, promotes versions, lists version history, resolves the newest-of-main from the preview alias, and describes any single version's provenance and URLs. Nothing else in the project spawns the vendor CLI or issues a vendor deploy call.",
+  "responsibilities": [
+    "Expose `uploadVersion({ previewAlias })` that uploads the current build to the vendor and returns `{ versionId, versionIdUrl, previewAliasUrl }`; refuse an empty `previewAlias` with `DEPLOY_PREVIEW_ALIAS_REQUIRED` (AC-12102-2, AC-12103-1).",
+    "Expose `promoteVersion({ versionId })` that routes production traffic to the named version and returns `{ promotedVersionId, versionSha, previousVersionId }`; the returned `promotedVersionId` is the vendor-assigned version UUID (the string `wrangler versions deploy` took) and the returned `versionSha` is the git commit sha of the source tree the promoted version was built from (read from the version's provenance surface via `describeVersion`); refuse when `versionId` is absent from `listVersions()` with `DEPLOY_VERSION_NOT_FOUND` (AC-12102-3, AC-12108-3).",
+    "Expose `listVersions()` returning the recent version history with the currently-serving id marked (AC-12109-1).",
+    "Expose `resolveNewestOfMain()` that returns the version id currently behind the operator-chosen preview alias by reading `wrangler versions list --json` and picking the item with the greatest `metadata.created_on` whose `annotations['workers/alias']` matches the alias; there is no vendor CLI verb that maps an alias to a version id directly (AC-12108-2).",
+    "Expose `describeVersion({ versionId })` returning provenance (`versionSha`, `builtAt`, `ciRunUrl`) and URLs (`versionIdUrl`) for the named version; `versionSha` is the git commit sha baked into the version's bundle by `build-and-upload`, distinct from the version UUID `versionId` names (AC-12112-1, AC-12112-2).",
+    "Expose `resolveSubdomain()` that returns the account's workers.dev subdomain string every URL-assembly path needs; reads the `WORKERS_DEV_SUBDOMAIN` env var when set (project pin) and otherwise queries the vendor's `GET /accounts/<accountId>/workers/subdomain` REST endpoint; caches the value for the process's lifetime (AC-12105-1).",
+    "Refuse a manifest whose production route resolves to the same host as the preview alias URL with `DEPLOY_URL_COLLAPSED` (AC-12105-2).",
+    "Route every CLI invocation through a redactor that scrubs the vendor API token and account id from every emitted log line (AC-12107-3, AC-12106-2)."
+  ],
+  "internalStructure": "One stateless class per process with an injected vendor binding and an injected redactor. The vendor binding is a project-authored module implementing the port in the interfaces block; the default vendor binding shells to the `wrangler` CLI and lives under the same package as the adapter. Every verb is a thin translation from the named surface to a vendor CLI invocation (or SDK call) plus response parsing plus provenance-URL assembly.",
+  "interfaces": [
+    {
+      "name": "vendorBinding",
+      "kind": "read-write-api",
+      "description": "Project-supplied vendor binding implementing `uploadArtefact({ configPath, previewAlias })`, `deployVersion({ versionId })`, `listVersions()`, `resolveAlias({ alias })`, `getSubdomain({ accountId })`. The default binding shells to `wrangler versions upload --preview-alias <alias>`, `wrangler versions deploy <versionId>`, and `wrangler versions list --json` respectively; `resolveAlias` filters the `versions list --json` output on `annotations['workers/alias']` and picks the newest by `metadata.created_on` because wrangler 4.x has no CLI verb that resolves an alias to a version id (`wrangler versions view` accepts a version UUID only); `getSubdomain` calls the vendor's `GET /accounts/<accountId>/workers/subdomain` REST endpoint because `wrangler whoami` does not return the subdomain."
+    },
+    {
+      "name": "redactor",
+      "kind": "callback",
+      "description": "Log-line filter that replaces any bytes matching the vendor API token or account id with a fixed placeholder before emitting; runs on every stdout and stderr line the vendor CLI produces."
+    },
+    {
+      "name": "manifest",
+      "kind": "read-api",
+      "description": "The wrangler-manifest loader (TAC-1302) resolving the current Worker's config, the production route or custom-domain declaration, and the declared binding names."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Wrangler Manifest",
+      "kind": "tac",
+      "tacId": "TAC-1302-deploy-cloudflare-workers-wrangler-manifest",
+      "description": "Upstream source of the config the adapter passes to the vendor CLI, and the manifest the collapsed-URL guard reads."
+    },
+    {
+      "name": "Preview URL Resolver",
+      "kind": "tac",
+      "tacId": "TAC-1303-deploy-cloudflare-workers-preview-url-resolver",
+      "description": "Assembles the preview alias URL and version-id URL strings the adapter returns; consulted from `uploadVersion` and `describeVersion`."
+    }
+  ],
+  "tradeoffs": "The adapter is process-local and stateless; every call reaches the vendor. That means a chain of adapter calls in one CI step costs one vendor round-trip per call rather than a shared session. The trade keeps the adapter easy to reason about and easy to reimplement against a different vendor. A project that wants a session-shared invocation supplies a vendor binding whose backing is a long-lived process rather than a CLI spawn per call; the port shape does not change.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/tacs/tac-1302-deploy-cloudflare-workers-wrangler-manifest.json

@@ -0,0 +1,45 @@
+{
+  "tacId": "TAC-1302-deploy-cloudflare-workers-wrangler-manifest",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Wrangler Manifest",
+  "purpose": "The repo-root deploy-configuration file (`wrangler.toml` or `wrangler.jsonc`) as loaded, validated, and exposed to the Deploy Adapter. Parses the manifest into an object the adapter and the CI gates consult, enforces the shape rules (required top-level keys, declared bindings, no inline secrets, no collapsed URLs), and refuses malformed or leaky manifests loudly.",
+  "responsibilities": [
+    "Parse `wrangler.toml` (or `wrangler.jsonc`) at the repo root; refuse absence with `WRANGLER_MANIFEST_MISSING` (AC-12101-1).",
+    "Validate the top-level keys `name`, `main`, `compatibility_date` are present and correctly typed; validate `main` resolves to an existing entry file; validate `compatibility_date` matches `\\d{4}-\\d{2}-\\d{2}` (AC-12101-1).",
+    "Cross-check every binding name referenced from the Worker source (via env-accessor scans keyed by binding name) against the manifest declarations; refuse a missing declaration with `WRANGLER_BINDING_UNDECLARED` naming the offending source path and the missing binding (AC-12101-2).",
+    "Refuse a manifest that carries any inline secret value; scan the parsed object for keys under the vendor's secret-declaration primitive whose value is not an empty declaration (AC-12101-3, AC-12106-1).",
+    "Refuse a manifest whose production route stanza resolves to the same host as the preview alias URL with `DEPLOY_URL_COLLAPSED` (AC-12105-2).",
+    "Expose a `bindings()` accessor listing every declared binding (kind, name) for downstream consumers.",
+    "Expose a `productionUrl()` accessor deriving the production URL from the `routes`/`route`/`workers_dev`/custom-domain declaration."
+  ],
+  "internalStructure": "One parser module per format (TOML and JSONC), one validator that walks the parsed object against the shape rules, one binding-usage scanner that walks the Worker source AST for env-accessor patterns, and one URL-derivation module that inspects the routes stanza. All pure functions; no I/O outside the initial file read.",
+  "interfaces": [
+    {
+      "name": "manifestFile",
+      "kind": "read-api",
+      "description": "Reads `wrangler.toml` or `wrangler.jsonc` at the repo root. The file's presence is required; the file's format is autodetected from the extension."
+    },
+    {
+      "name": "workerSourceScanner",
+      "kind": "read-api",
+      "description": "AST or regex scanner over the Worker source tree that emits every binding name referenced through env-accessor patterns (for the default JS/TS Worker, `env.<NAME>.<method>` and `process.env.<NAME>` are both matched)."
+    },
+    {
+      "name": "bindings",
+      "kind": "read-api",
+      "description": "Structured list of declared bindings emitted for downstream consumers. Each entry names the binding kind (KV, D1, R2, Durable Object, static assets, var, secret, service, queue) and the binding name."
+    },
+    {
+      "name": "productionUrl",
+      "kind": "read-api",
+      "description": "Returns the production URL derived from the manifest. When multiple routes are declared, returns the ordered list; when `workers_dev = true`, returns the workers.dev host."
+    }
+  ],
+  "dependencies": [],
+  "tradeoffs": "The loader owns validation but does not own the vendor's own manifest-level validation (which happens later at the vendor CLI). Two-stage validation means a manifest that passes this loader can still fail the vendor's own load; the trade keeps the loader project-local and fast (no vendor round-trip on every CI step) while catching the classes this blueprint cares about (undeclared bindings, inline secrets, collapsed URLs) before the vendor call. A project can point the loader at a project-authored TOML dialect (a preprocessor step) by wrapping the manifestFile interface.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/tacs/tac-1303-deploy-cloudflare-workers-preview-url-resolver.json

@@ -0,0 +1,46 @@
+{
+  "tacId": "TAC-1303-deploy-cloudflare-workers-preview-url-resolver",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Preview URL Resolver",
+  "purpose": "The single project source of the string patterns for the two preview URL kinds (per-version-id URL, stable alias URL) and the mapping between an alias string and the version id it currently resolves to. Consulted by the Deploy Adapter's `uploadVersion` and `describeVersion` verbs and by every path that needs to reach the preview surface for review or verification.",
+  "responsibilities": [
+    "Assemble the per-version-id URL for a given version id and the currently-configured Worker name and vendor subdomain (AC-12103-1, AC-12103-2).",
+    "Assemble the stable preview alias URL for a given alias string and the currently-configured Worker name and vendor subdomain; ensure the alias is quoted verbatim in the host segment (AC-12102-2, AC-12103-1).",
+    "Given an alias string, query the vendor for the version id currently behind the alias and return it (`resolveNewestOfMain` on the Deploy Adapter delegates here) (AC-12108-2).",
+    "Refuse an alias string that would collide with the production route's host segment; return `DEPLOY_URL_COLLAPSED` (AC-12105-2).",
+    "Guarantee the preview URL host segment can never equal the production URL host segment; the invariant is a property test at build time (AC-12105-3).",
+    "Expose a `probeUrl(kind, id-or-alias)` verb that returns the URL to hit for a given probe target (`versionId`, `alias`, or `production`), so the Served-surface Verifier need not know URL assembly."
+  ],
+  "internalStructure": "Pure string-assembly module plus a thin query wrapper over the vendor's alias-lookup call. No cache: every alias query goes to the vendor because the alias is expected to change on every upload and the freshness cost of caching is not worth the complexity.",
+  "interfaces": [
+    {
+      "name": "workerIdentity",
+      "kind": "read-api",
+      "description": "Reads the Worker name from the wrangler manifest. Reads the vendor account's workers.dev subdomain from the Deploy Adapter's `resolveSubdomain()` verb (which honours a `WORKERS_DEV_SUBDOMAIN` env-var pin ahead of calling the vendor's `GET /accounts/<accountId>/workers/subdomain` REST endpoint, because no wrangler CLI verb returns the subdomain). Returns both as strings the URL-assembly functions consume."
+    },
+    {
+      "name": "aliasQuery",
+      "kind": "read-api",
+      "description": "Queries the vendor for the version id currently behind an alias by reading `wrangler versions list --json` and filtering on `annotations['workers/alias']`, returning the item with the greatest `metadata.created_on`; there is no direct CLI verb (`wrangler versions view` accepts a version UUID only). Returns the id or a stable `DEPLOY_ALIAS_UNKNOWN` error when no version carries the alias annotation."
+    },
+    {
+      "name": "probeUrl",
+      "kind": "read-api",
+      "description": "Named-verb URL accessor for downstream consumers. `probeUrl('versionId', 'v-123')` returns the per-version URL; `probeUrl('alias', 'main')` returns the alias URL; `probeUrl('production', null)` returns the production URL from the manifest."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Wrangler Manifest",
+      "kind": "tac",
+      "tacId": "TAC-1302-deploy-cloudflare-workers-wrangler-manifest",
+      "description": "Reads the Worker name and the production route stanza; the collapsed-URL invariant is checked against `productionUrl()`."
+    }
+  ],
+  "tradeoffs": "The resolver treats the vendor's URL-string patterns as stable within the blueprint's major version. When the vendor changes the pattern (a new subdomain scheme, a new alias-in-host format), a blueprint major bump is what tracks the change; a project that pinned an older pattern by hand-editing the resolver loses the invariant guard. The trade is a small coupling to the vendor's public URL contract in exchange for one place to change when it moves.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/tacs/tac-1304-deploy-cloudflare-workers-promote-gate.json

@@ -0,0 +1,57 @@
+{
+  "tacId": "TAC-1304-deploy-cloudflare-workers-promote-gate",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Promote Gate",
+  "purpose": "The project-side guard that enforces production only changes on an explicit operator promote. Wraps the `promote` workflow's input handling, its version-id resolution, its call into the Deploy Adapter, and its post-promote invocation of the Served-surface Verifier. Emits the structured deploy-log record every promote leaves behind.",
+  "responsibilities": [
+    "Accept the `versionId` input from the promote workflow trigger; when empty, invoke `deployAdapter.resolveNewestOfMain()` to fill it (AC-12108-1, AC-12108-2).",
+    "Refuse a `versionId` absent from `deployAdapter.listVersions()` before any vendor call is issued; return `DEPLOY_VERSION_NOT_FOUND` (AC-12108-3).",
+    "Invoke `deployAdapter.promoteVersion({ versionId })`; capture the returned `{ promotedVersionId, versionSha, previousVersionId }` for the deploy-log record. `promotedVersionId` is the vendor-assigned version UUID; `versionSha` is the git commit sha of the source tree the promoted version was built from, read from the version's provenance surface; both are required on the record and both feed the Served-surface Verifier (the verifier reconciles the served health-probe body's `versionSha` against the record's `versionSha`) (AC-12104-3, AC-12109-1).",
+    "Immediately invoke the Served-surface Verifier against the production URL, passing the promote record's `versionSha` as the substitution value for `expectShape.versionSha` in the health-probe declaration; on any verifier failure exit non-zero with `PROMOTE_VERIFY_FAILED` and refuse to mark the release successful (AC-12109-3, AC-12110-1, AC-12110-3).",
+    "Emit the deploy-log record with fields `promotedVersionId`, `versionSha`, `promotedBy`, `previousVersionId`, `promotedAt`; every field is populated; no field carries a secret value (AC-12104-3).",
+    "Refuse to run when the invocation context is not the platform's explicit-manual-trigger primitive (a `workflow_dispatch` guard as the first step of the workflow) (AC-12104-1, AC-12104-2)."
+  ],
+  "internalStructure": "One workflow-orchestration function per CI platform (the default GitHub Actions form is shipped as an asset; other platforms adapt the same shape). The function is stateless; the workflow's own outputs are the durable state. The deploy-log record is written to a project-chosen sink (a JSONL file in a durable location, an audit event bus, a database table) through an injected `deployLog.append` callback.",
+  "interfaces": [
+    {
+      "name": "deployAdapter",
+      "kind": "read-write-api",
+      "description": "The Deploy Adapter port (TAC-1301). The promote gate calls `listVersions`, `resolveNewestOfMain`, and `promoteVersion` through this interface."
+    },
+    {
+      "name": "verifier",
+      "kind": "read-api",
+      "description": "The Served-surface Verifier callable that runs the post-promote probes and returns pass or a `PROMOTE_VERIFY_FAILED` failure description."
+    },
+    {
+      "name": "deployLog",
+      "kind": "callback",
+      "description": "Append callback invoked with the promote record `{ promotedVersionId, versionSha, promotedBy, previousVersionId, promotedAt }` on every successful promote and on every verifier-failed promote."
+    },
+    {
+      "name": "triggerContext",
+      "kind": "read-api",
+      "description": "Returns the platform's trigger information (event name, actor login). The gate refuses to proceed when the event name is not the platform's explicit-manual-trigger name (`workflow_dispatch` on GitHub Actions)."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Deploy Adapter",
+      "kind": "tac",
+      "tacId": "TAC-1301-deploy-cloudflare-workers-deploy-adapter",
+      "description": "Every version operation routes through the adapter; no direct vendor CLI call from the gate."
+    },
+    {
+      "name": "Served-surface Verifier",
+      "kind": "tac",
+      "tacId": "TAC-1305-deploy-cloudflare-workers-served-surface-verifier",
+      "description": "The post-promote probe layer; the gate invokes the verifier and honours its failure signal."
+    }
+  ],
+  "tradeoffs": "The gate is coupled to the workflow platform's explicit-trigger primitive. A project that runs on a CI platform without a distinct manual-trigger event needs a project-authored wrapper that supplies the equivalent (a manual-approval step; a webhook with an operator token check). The trade is the workflow platforms that ship this primitive natively (GitHub Actions, GitLab CI's manual jobs, Buildkite's block steps) all get the invariant enforced cheaply; the rest layer their own equivalent above.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/tacs/tac-1305-deploy-cloudflare-workers-served-surface-verifier.json

@@ -0,0 +1,51 @@
+{
+  "tacId": "TAC-1305-deploy-cloudflare-workers-served-surface-verifier",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Served-surface Verifier",
+  "purpose": "The post-promote probe layer. Hits the SERVED surface (production URL by default; the preview alias URL when the promote gate is running a preview-only verify) with a fixed set of probe paths, retries within a bounded window, and returns a structured pass or fail the promote gate honours. Never targets a dev-mode local URL; refuses to accept a probe URL matching the dev-mode pattern.",
+  "responsibilities": [
+    "Hit every declared probe path against the target URL after `promoteVersion` returns success; each probe retries up to six times over up to sixty seconds with per-request timeouts of at most five seconds (AC-12110-1).",
+    "Pass a probe when the response status is in the project-declared success set AND the response body carries the expected shape. For the mandatory health probe, `expectShape.versionSha` is substituted at verify time with the promote record's `versionSha` field (the git commit sha the promoted version was built from), NOT with the promote record's `promotedVersionId` (the vendor-assigned version UUID); the two identifiers name different things and are never equal (AC-12110-2, AC-12112-3).",
+    "Fail the verify when any probe exhausts its retries without passing; emit the failing probe path, the last response status seen, and the elapsed time; return `PROMOTE_VERIFY_FAILED` (AC-12110-3).",
+    "Refuse a target URL matching the dev-mode local pattern (`http://localhost:*`, `http://127.0.0.1:*`, or the vendor's local emulator loopback host); return `DEPLOY_DEV_MODE_INADMISSIBLE` (AC-12111-1).",
+    "Accept a target URL matching the vendor's preview or production URL patterns (per-version-id URL, alias URL, custom-domain URL, workers.dev production host) (AC-12111-2).",
+    "Emit structured probe records the deploy log can persist: `{ probePath, status, elapsedMs, outcome, versionShaSeen }` per probe attempt."
+  ],
+  "internalStructure": "One async probe-runner per probe path, each retrying against the same target URL. The runner is a small state machine: attempt, on-fail sleep, retry until budget exhausted, resolve pass or fail. A property test enforces the retry-count and window bounds at build time. The probe-path set and the success-status set are project-declared configuration.",
+  "interfaces": [
+    {
+      "name": "probeConfig",
+      "kind": "read-api",
+      "description": "Project-supplied probe declaration: an array of `{ path, method?: 'GET'|'HEAD', successStatus: number[], expectShape?: object }`. At least one probe must be declared; the health probe is the mandatory one."
+    },
+    {
+      "name": "urlTarget",
+      "kind": "read-api",
+      "description": "The URL the verifier hits. Sourced from the Preview URL Resolver's `probeUrl('production', null)` for a promote verify, or `probeUrl('alias', <alias>)` for a preview-only verify."
+    },
+    {
+      "name": "httpClient",
+      "kind": "read-api",
+      "description": "The HTTP client the verifier drives (Node.js `fetch` in the default form; project-supplied for a project running under a different runtime)."
+    },
+    {
+      "name": "resultSink",
+      "kind": "callback",
+      "description": "Structured-record sink invoked with each probe attempt's outcome `{ probePath, status, elapsedMs, outcome, versionShaSeen }`."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Preview URL Resolver",
+      "kind": "tac",
+      "tacId": "TAC-1303-deploy-cloudflare-workers-preview-url-resolver",
+      "description": "Source of the URL the verifier hits; the resolver's `probeUrl` verb keeps URL assembly out of the verifier."
+    }
+  ],
+  "tradeoffs": "The retry bounds are opinionated (six attempts over sixty seconds). A project whose vendor propagates faster shrinks the window; a project whose vendor propagates slower buys a bigger budget by superseding the AC's numeric bound with a project-level ADR. The trade is the default catches propagation lag without turning a stuck workflow into a silent one; the numeric floor is the shape a project changes deliberately, not by drift. The verifier's probe path is a DEPLOY-blueprint surface whose response body carries build provenance; it is distinct from any external-supervisor probe surface a composing observability-probe-endpoints application declares. The two coexist on distinct paths with distinct contracts; see `assets/verification/served-surface-probes.md` for the boundary. A project composing both blueprints picks separate paths (`/health` for the profile, `/healthz` for the verifier, or equivalents) and refuses to collapse them.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/tacs/tac-1306-deploy-cloudflare-workers-deploy-ci-workflows.json

@@ -0,0 +1,64 @@
+{
+  "tacId": "TAC-1306-deploy-cloudflare-workers-deploy-ci-workflows",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Deploy CI Workflows",
+  "purpose": "The two CI workflow files that operationalise the upload-and-promote model. `build-and-upload` runs on every merge to main and produces an uploaded version at the preview alias URL. `promote` runs only on explicit operator trigger and routes production to a named version id (or the newest-of-main) through the Promote Gate. Both workflows are the project's sole vendor-authenticated ship paths.",
+  "responsibilities": [
+    "Ship a `build-and-upload` workflow file whose trigger set is `push` scoped to the main branch (and any linear-history proxy), with no `pull_request` or `schedule` trigger (AC-12107-1, AC-12104-1).",
+    "The `build-and-upload` workflow checks out the tree at the merged commit, installs pinned dependencies, runs the project build, invokes `deployAdapter.uploadVersion({ previewAlias })`, and writes `versionId`, `versionIdUrl`, `previewAliasUrl` to the workflow's structured output and to the run summary (AC-12103-1, AC-12107-2).",
+    "The `build-and-upload` workflow injects the commit sha, an ISO 8601 build timestamp, and the CI run URL into the built bundle before `uploadVersion` runs; the values become the version's provenance surface (AC-12112-1).",
+    "Ship a `promote` workflow file whose trigger set is exclusively the platform's explicit-manual-trigger primitive (`workflow_dispatch` on GitHub Actions), declaring exactly one input `versionId` typed as an optional string (AC-12104-2, AC-12108-1).",
+    "The `promote` workflow calls the Promote Gate with the input `versionId`; on gate-side success, the workflow's summary carries `promotedVersionId`, `previousVersionId`, `promotedBy`, `promotedAt` (AC-12104-3, AC-12108-2, AC-12108-3).",
+    "Both workflows authenticate to the vendor using named CI secrets (`CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` for the default vendor); the secrets are populated only into the vendor CLI's environment; no log line prints either byte sequence (AC-12107-3, AC-12106-2).",
+    "The CI gate that guards both workflows scans the change for wrangler-manifest issues (undeclared bindings, inline secrets, collapsed URLs) before the deploy verbs run; a lint failure refuses the workflow with a stable-coded error (AC-12101-2, AC-12101-3, AC-12105-2, AC-12106-3)."
+  ],
+  "internalStructure": "Two YAML workflow files (GitHub Actions form shipped as an asset under `assets/ci-workflows/`) plus a Node.js orchestration script per workflow that both files invoke. The scripts are the durable form; the YAML files are thin shims that platform-adapt the trigger set and input handling. A project on another CI platform authors platform-native trigger stanzas and calls the same orchestration scripts.",
+  "interfaces": [
+    {
+      "name": "workflowRuntime",
+      "kind": "read-api",
+      "description": "The CI platform's runtime (event context, actor login, workflow inputs, run URL, summary sink, structured-output sink). Consumed by the orchestration scripts."
+    },
+    {
+      "name": "promoteGate",
+      "kind": "read-write-api",
+      "description": "The Promote Gate (TAC-1304) callable; the `promote` workflow invokes it with the resolved `versionId` and the `promotedBy` principal from the workflow runtime."
+    },
+    {
+      "name": "buildStep",
+      "kind": "read-api",
+      "description": "Project-authored build step invoked by `build-and-upload` before `uploadVersion` runs; must produce the artefact the wrangler manifest's `main` points at."
+    },
+    {
+      "name": "secretBinding",
+      "kind": "read-api",
+      "description": "Named CI secrets the workflows read: `CLOUDFLARE_API_TOKEN` (or the operator-chosen vendor token name) and `CLOUDFLARE_ACCOUNT_ID` (or the operator-chosen account-id name); values populate the vendor CLI's environment via the platform's secret-injection primitive."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Deploy Adapter",
+      "kind": "tac",
+      "tacId": "TAC-1301-deploy-cloudflare-workers-deploy-adapter",
+      "description": "The workflows' only path to the vendor: `uploadVersion` from `build-and-upload`, and `promoteVersion` via the Promote Gate from `promote`."
+    },
+    {
+      "name": "Promote Gate",
+      "kind": "tac",
+      "tacId": "TAC-1304-deploy-cloudflare-workers-promote-gate",
+      "description": "The `promote` workflow delegates its full body to the gate; the workflow's role is trigger-set enforcement and input-declaration plumbing."
+    },
+    {
+      "name": "Wrangler Manifest",
+      "kind": "tac",
+      "tacId": "TAC-1302-deploy-cloudflare-workers-wrangler-manifest",
+      "description": "The CI gate's pre-flight lint reads the manifest and enforces the shape rules before either workflow's deploy verbs run."
+    }
+  ],
+  "tradeoffs": "The GitHub Actions form is shipped as a first-class asset because it is the CI platform the estate the blueprint targets uses today. A project on GitLab CI, Buildkite, CircleCI, or a self-hosted runner adapts the trigger stanzas and the input primitive; the orchestration scripts stay identical. The trade is a project on a non-GHA platform has to author the platform-native wrapper themselves; the payoff is the durable behaviour is in Node.js, not YAML.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/user-stories/deploy-cloudflare-workers-us-12101.json

@@ -0,0 +1,54 @@
+{
+  "usId": "deploy-cloudflare-workers-US-12101",
+  "prdId": "PRD-001",
+  "reqId": "deploy-cloudflare-workers-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The repo-root wrangler manifest is the sole declaration of the Worker's deploy shape",
+  "asA": "operator reading a fresh repo",
+  "iWant": "one file at the repo root that declares the Worker name, entry, compatibility settings, and every binding",
+  "soThat": "the deploy shape is legible without reading CI scripts or a vendor dashboard",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12101-1",
+      "description": "A `wrangler.toml` (or `wrangler.jsonc`) exists at the repo root, parses as valid config, and its top-level object carries `name`, `main`, `compatibility_date`, and every non-secret binding block the Worker's runtime code references (KV namespaces, D1 databases, R2 buckets, Durable Object namespaces, static-assets binding, and non-secret environment variables); secret bindings are implicit through env-accessor references in the Worker source and 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).",
+      "given": "a fresh clone of a repo that has applied the blueprint and realised the manifest",
+      "when": "a manifest loader parses the file",
+      "then": "the loader returns a config object whose `name` is a non-empty string, `main` resolves to an existing entry file, `compatibility_date` matches `\\d{4}-\\d{2}-\\d{2}`, and every non-secret binding name referenced from the Worker's source appears as a declaration key in the config; the config carries no `[secrets]` block",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-12101-2",
+      "description": "A CI gate scans the Worker's source tree for references to bindings (env accessors keyed by binding name) and refuses the build when a referenced binding name has no matching declaration in `wrangler.toml`.",
+      "given": "a change adds `env.NEW_KV.get(...)` to the Worker source and does not add `NEW_KV` to `wrangler.toml`",
+      "when": "the CI gate runs on the change",
+      "then": "the run fails with a stable-coded `WRANGLER_BINDING_UNDECLARED` error naming the offending source path and the missing binding name",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-12101-3",
+      "description": "The manifest never carries a secret VALUE; a source-tree scan across every file that could contribute a bound value at deploy time (the wrangler config, any `.env`-shaped file the deploy step reads, any CI environment block committed to the repo) finds no match for any value the secrets contract resolves.",
+      "given": "the secrets contract resolves a set of secret values `V` for the current environment",
+      "when": "a redaction-scanner runs against `wrangler.toml`, any committed environment file, and the CI workflows",
+      "then": "no file in the scanned set contains any byte sequence in `V`",
+      "testable": true,
+      "scope": "deployed"
+    },
+    {
+      "id": "AC-12101-4",
+      "description": "When the manifest declares an `[assets]` block AND the Worker's fetch handler installs an auth gate on any route whose path could be shadowed by a file under the assets `directory`, the manifest MUST declare `[assets] run_worker_first` naming every gated route (glob-matched); a deployed request to any listed path is answered by the fetch handler before the assets pipeline runs. Without the listing, the assets pipeline serves the shadowing file directly and the auth gate is silently bypassed at the edge.",
+      "given": "a Worker whose fetch handler installs an auth middleware on `/notes` and a `./public/notes.html` file present at build time; the deployed Worker is reachable at production URL P",
+      "when": "an unauthenticated HTTP GET hits `P/notes`",
+      "then": "the response is the auth middleware's unauthenticated response (a redirect to sign-in, a 401, or the middleware's declared shape); the response is NOT the byte content of `./public/notes.html`; a manifest that omits `/notes` from `[assets] run_worker_first` fails the deployed observation because the assets pipeline answered before the fetch handler ran",
+      "testable": true,
+      "scope": "deployed"
+    }
+  ],
+  "tacIds": [
+    "TAC-1302-deploy-cloudflare-workers-wrangler-manifest"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/user-stories/deploy-cloudflare-workers-us-12102.json

@@ -0,0 +1,45 @@
+{
+  "usId": "deploy-cloudflare-workers-US-12102",
+  "prdId": "PRD-001",
+  "reqId": "deploy-cloudflare-workers-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "One deploy adapter is the sole caller of the deploy CLI",
+  "asA": "engineer reading the project",
+  "iWant": "a single named module every path imports to talk to the deploy vendor",
+  "soThat": "changing vendors is a one-module change and duplicate CLI call paths cannot drift",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12102-1",
+      "description": "The project exposes one Deploy Adapter module whose public surface is `uploadVersion`, `promoteVersion`, `listVersions`, `resolveNewestOfMain`, and `describeVersion`; the module is the only source file that spawns the vendor CLI binary or imports the vendor's deploy SDK.",
+      "given": "a project that has applied the blueprint and realised TAC-1301",
+      "when": "the source tree is scanned for spawns of `wrangler` (or the vendor's CLI binary name) and for imports of the vendor's deploy SDK identifier",
+      "then": "the only source file that matches either scan is the Deploy Adapter module; no other module names an alternative deploy call path",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-12102-2",
+      "description": "The adapter's `uploadVersion({ previewAlias })` verb returns `{ versionId, versionIdUrl, previewAliasUrl }` on success and refuses to complete when the alias argument is empty.",
+      "given": "a Deploy Adapter instance backed by the default vendor",
+      "when": "a caller invokes `deployAdapter.uploadVersion({ previewAlias: 'main' })`",
+      "then": "the call resolves with a `versionId` string matching the vendor's version-id format, a `versionIdUrl` naming the per-version URL, and a `previewAliasUrl` whose host segment carries the alias `main`; a call with `previewAlias: ''` throws a `DEPLOY_PREVIEW_ALIAS_REQUIRED` error",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-12102-3",
+      "description": "The adapter's `promoteVersion({ versionId })` verb refuses when `versionId` is not present in `listVersions()`.",
+      "given": "an adapter whose `listVersions()` returns a set that does not include the id `bogus-v1`",
+      "when": "a caller invokes `deployAdapter.promoteVersion({ versionId: 'bogus-v1' })`",
+      "then": "the call throws a `DEPLOY_VERSION_NOT_FOUND` error naming `bogus-v1` and no vendor promote call is issued",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1301-deploy-cloudflare-workers-deploy-adapter"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/user-stories/deploy-cloudflare-workers-us-12103.json

@@ -0,0 +1,46 @@
+{
+  "usId": "deploy-cloudflare-workers-US-12103",
+  "prdId": "PRD-001",
+  "reqId": "deploy-cloudflare-workers-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Every merge to main produces an uploaded version at a stable preview alias URL",
+  "asA": "reviewer of a merged change",
+  "iWant": "a stable preview URL that always resolves to the newest-of-main uploaded version",
+  "soThat": "I can look at the change on a live surface without waiting for a production promote",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12103-1",
+      "description": "A successful `build-and-upload` CI run on a merge to main leaves the preview alias URL resolving to the version id the run just uploaded, and the version-id URL resolving to the same version permanently.",
+      "given": "a merge to main triggers `build-and-upload` and it exits zero with recorded `versionId` V and `previewAliasUrl` A and `versionIdUrl` U",
+      "when": "an HTTP request hits A and then a second HTTP request hits U within five minutes of the run completing",
+      "then": "both responses carry the `versionSha` field of V's build provenance in the health-probe body, and the two responses agree on that field",
+      "testable": true,
+      "scope": "deployed"
+    },
+    {
+      "id": "AC-12103-2",
+      "description": "A subsequent merge that produces a new upload W leaves the preview alias URL resolving to W while the version-id URL for the previous version V still resolves to V.",
+      "given": "an upload V behind preview alias A followed by a fresh merge that produces upload W",
+      "when": "requests hit A and the version-id URLs for V and W after W's run completes",
+      "then": "the response at A carries W's `versionSha`; the response at V's version-id URL still carries V's `versionSha`; the two are distinct",
+      "testable": true,
+      "scope": "deployed"
+    },
+    {
+      "id": "AC-12103-3",
+      "description": "The uploaded version does not serve production traffic; the production URL continues to serve the version that was serving before the upload.",
+      "given": "production is serving version P and a merge lands producing upload W",
+      "when": "the `build-and-upload` run completes and no promote has run",
+      "then": "the production URL's health probe carries P's `versionSha`, not W's",
+      "testable": true,
+      "scope": "deployed"
+    }
+  ],
+  "tacIds": [
+    "TAC-1303-deploy-cloudflare-workers-preview-url-resolver",
+    "TAC-1301-deploy-cloudflare-workers-deploy-adapter"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/contributions/user-stories/deploy-cloudflare-workers-us-12104.json

@@ -0,0 +1,46 @@
+{
+  "usId": "deploy-cloudflare-workers-US-12104",
+  "prdId": "PRD-001",
+  "reqId": "deploy-cloudflare-workers-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Production only changes via an explicit promote step",
+  "asA": "operator responsible for what production serves",
+  "iWant": "no code path that changes production as a side effect of a merge",
+  "soThat": "every ship is a deliberate act with a named principal on the record",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12104-1",
+      "description": "The project's CI workflow set contains no workflow that both triggers on `push` to main AND calls the Deploy Adapter's `promoteVersion` verb (or the vendor's coupled deploy verb `wrangler deploy`).",
+      "given": "the CI workflow set of a project that has applied the blueprint",
+      "when": "a lint scan walks every workflow file and inspects the trigger set of each and the deploy verb it invokes",
+      "then": "no workflow file both matches trigger `push` on branch `main` (or a linear-history proxy) AND invokes a promote verb; the scan reports zero offenders",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-12104-2",
+      "description": "The `promote` workflow triggers only on explicit manual operator action, not on any push, pull-request, or schedule.",
+      "given": "the `promote` workflow file",
+      "when": "the trigger stanza is parsed",
+      "then": "the only trigger present is the platform's explicit-manual-trigger primitive (`workflow_dispatch` on GitHub Actions or the equivalent) and no `push`, `pull_request`, or `schedule` trigger appears",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-12104-3",
+      "description": "Every successful promote leaves a structured record naming the version id promoted, the operator principal, the previously-serving version id, and the timestamp.",
+      "given": "a successful invocation of the `promote` workflow",
+      "when": "the deploy log store is inspected after the run",
+      "then": "a new record exists whose fields include `promotedVersionId`, `promotedBy`, `previousVersionId`, and `promotedAt`; every field is populated and no field carries a secret value",
+      "testable": true,
+      "scope": "deployed"
+    }
+  ],
+  "tacIds": [
+    "TAC-1304-deploy-cloudflare-workers-promote-gate",
+    "TAC-1306-deploy-cloudflare-workers-deploy-ci-workflows"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}