rcf-lite 0.12.0 → 0.13.0

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

@@ -0,0 +1,45 @@
+{
+  "usId": "deploy-cloudflare-workers-US-12111",
+  "prdId": "PRD-001",
+  "reqId": "deploy-cloudflare-workers-REQ-011",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Local dev-mode is never authoritative for ship coverage",
+  "asA": "engineer authoring runtime-verify tests",
+  "iWant": "the ship gate to refuse a deployed-scope AC bound to a dev-mode probe",
+  "soThat": "no emulator drift can pass for a real runtime signal",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12111-1",
+      "description": "A test case whose runtime probe hits the local dev-mode URL (matching the pattern for the vendor's local emulator, for example `http://localhost:8787` or the `wrangler dev` bound port) is refused as coverage for any AC whose `scope` is `deployed`.",
+      "given": "an AC with `scope: 'deployed'` bound to a TC whose runtime target URL matches the dev-mode pattern",
+      "when": "the coverage gate walks the AC-to-TC bindings",
+      "then": "the gate reports the binding as `DEPLOY_DEV_MODE_INADMISSIBLE`, refuses to count it toward the AC's coverage, and lists the offending TC and its target URL",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-12111-2",
+      "description": "A probe against a preview alias URL, a version-id URL, or the production URL is accepted as coverage for a deployed-scope AC.",
+      "given": "an AC with `scope: 'deployed'` bound to a TC whose runtime target URL matches the vendor's preview or production URL patterns",
+      "when": "the coverage gate walks the AC-to-TC bindings",
+      "then": "the gate accepts the binding as valid coverage; the coverage counter increments for the AC",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-12111-3",
+      "description": "The project's runtime-verify catalogue documents the dev-mode drift classes (regular-expression engine differences, static-assets ordering differences, binding-emulation differences, timeout behaviour) so an engineer authoring a probe knows which behaviours cannot be trusted at the local surface.",
+      "given": "the project's runtime-verify catalogue file",
+      "when": "the file is read",
+      "then": "the file names at least four dev-mode drift classes with a one-line example of each and a pointer to the vendor's changelog or release notes where the class is described",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-1305-deploy-cloudflare-workers-served-surface-verifier"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

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

@@ -0,0 +1,46 @@
+{
+  "usId": "deploy-cloudflare-workers-US-12112",
+  "prdId": "PRD-001",
+  "reqId": "deploy-cloudflare-workers-REQ-012",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Every uploaded version carries build-provenance readable at runtime",
+  "asA": "operator triaging an incident",
+  "iWant": "one HTTP request to the running Worker to name the commit, the build time, and the CI run URL",
+  "soThat": "the served surface is self-identifying without any dashboard step",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-12112-1",
+      "description": "The `build-and-upload` workflow injects the commit sha, the build ISO 8601 timestamp, and the CI run URL into the Worker's bundle (as build-time constants, as `vars`, or via the Deploy Adapter's `describeVersion` surface); the values are readable from within the Worker at request time.",
+      "given": "a `build-and-upload` run at commit C at time T triggered from CI run R",
+      "when": "the resulting Worker's runtime code reads the provenance surface",
+      "then": "the surface returns an object whose `versionSha` equals C's short sha, whose `builtAt` equals T formatted as ISO 8601, and whose `ciRunUrl` equals R",
+      "testable": true,
+      "scope": "deployed"
+    },
+    {
+      "id": "AC-12112-2",
+      "description": "A fixed health-probe path (project-declared, `/healthz` by common default) responds with a JSON body carrying stable field names `versionSha`, `builtAt`, and `ciRunUrl` on any deployed URL (preview alias, version id, production).",
+      "given": "a deployed Worker at any of the three URL kinds",
+      "when": "an HTTP GET hits the project's declared health-probe path",
+      "then": "the response body is JSON with fields `versionSha`, `builtAt`, `ciRunUrl`; all three fields are populated with non-empty strings; the response status is in the success set",
+      "testable": true,
+      "scope": "deployed"
+    },
+    {
+      "id": "AC-12112-3",
+      "description": "The Served-surface Verifier uses the `versionSha` field on the probe response body (the git commit sha the served version was built from) to confirm the promoted version is the version being served; the value the verifier compares against is the promote record's `versionSha` field, distinct from the promote record's `promotedVersionId` (the vendor-assigned version UUID). A promote whose post-promote probe returns a `versionSha` that does not match the promote record's `versionSha` fails the release.",
+      "given": "a promote of version W with promote record `{ promotedVersionId: 'v-uuid-W', versionSha: 'sha-W' }`",
+      "when": "the verifier's post-promote probe returns a body whose `versionSha` reads `sha-P` (a stale prior version)",
+      "then": "the verifier records the mismatch as `PROMOTE_VERIFY_FAILED` with the observed `sha-P` and the expected `sha-W`; the release is not marked successful",
+      "testable": true,
+      "scope": "deployed"
+    }
+  ],
+  "tacIds": [
+    "TAC-1305-deploy-cloudflare-workers-served-surface-verifier",
+    "TAC-1306-deploy-cloudflare-workers-deploy-ci-workflows"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/deploy-cloudflare-workers/docs/topics.md

@@ -0,0 +1,46 @@
+# deploy-cloudflare-workers blueprint coordination vocabulary
+
+This file is the deploy-cloudflare-workers half of the cross-blueprint contract. The Phase 1 conflict detector matches scope:global ADR topics by EXACT string equality, and AC ids are unnamespaced by the 0.4.4 grammar. Any blueprint intended to compose with this one must reuse these exact strings and respect these bands.
+
+## Global ADR topics this blueprint contributes (exact strings)
+
+| Topic string | deploy-cloudflare-workers contribution | Origin | Composition note |
+|---|---|---|---|
+| `deploymentTarget` | ADR-1301-deploy-cloudflare-workers-deployment-target | Minted here; pre-cleared as unclaimed against application-spa (`clientRouting`, `theming`, `clientState`, `errorEnvelope`, `authModel`), application-api-rest (`errorEnvelope`, `authModel`, `apiVersioning`, `logging`), security-auth-magic-link (`authModel`), persistence-data-sqlite (`persistenceStore`, `migrationDiscipline`), ci-pipeline (`ciGates`, `strictCoverageGate`), observability-essentials (`healthProbes`, `readinessSemantics`, `statusPageContract`), security-secrets-management (`secretsSource`), and the hello-panel walkthrough exemplar (`operatorPanel`) | The one project-wide model for how bits reach a running target: an artefact-upload + explicit-promote model, versions addressable at stable preview URLs, one adapter as the sole vendor caller, one served-surface verifier on every promote. A composing blueprint that holds a different opinion on the deployment shape (a container-image-per-commit + rolling-deploy blueprint, a coupled-merge-to-production blueprint, a serverless-function-per-endpoint blueprint) contributes its own scope:global ADR on this exact string and lets composition surface the pairing. Expected resolution: one project-level ADR that fixes the deployment shape and the vendor selection |
+
+The deploy-cloudflare-workers blueprint claims one global topic. Every other contribution is scope-local (ADR-1302 through ADR-1305 name the default vendor, the preview-vs-production URL model, the rollback-is-promote posture, and the dev-mode drift posture without contributing global topics; a composing blueprint that holds a different opinion on any of them authors its own project-level ADR if it wants to override).
+
+Rules for new topics (inherited from the application-spa, application-api-rest, security-auth-magic-link, persistence-data-sqlite, ci-pipeline, observability-essentials, and security-secrets-management vocabularies, restated as law): lower camel case, one concept per topic, no version suffixes. A topic names the decision area, not the chosen answer. Do not mint variants of existing strings (`deploy`, `deployVendor`, `deployPipeline`, `shipTarget` are all wrong when `deploymentTarget` already exists).
+
+## Id number bands (registry bootstrap)
+
+AC ids (and therefore US numeric ids, which anchor them) are NOT namespaced by the 0.5.0 schema grammar; the band allocation IS the AC-collision enforcement mechanism. Composing blueprints take a fresh band rather than proposing namespaced AC ids. Band allocation is ratified policy (2026-08-19); this table is the shared registry-bootstrap replicated across every shipped and forthcoming blueprint's `docs/topics.md` until a mechanism-side central registry lands (v1.1 candidate).
+
+This table is maintained shelf-wide across every blueprint's `docs/topics.md`. Rows are recorded at ship, never predicted.
+
+| Blueprint | US band | ADR/TAC suffix block | Status | Global topics |
+|---|---|---|---|---|
+| application-spa | 1101-1899 | 2xx | shipped v1.3.0 | `clientRouting`, `theming`, `clientState`, `errorEnvelope`, `authModel` |
+| application-api-rest | 2101-2899 | 3xx | shipped v1.0.0 | `errorEnvelope`, `authModel`, `apiVersioning`, `logging` |
+| security-auth-magic-link | 3101-3899 | 5xx | shipped v1.0.0 | `authModel` |
+| email-smtp-resend | 4101-4899 | 4xx | shipped v1.0.0 | none |
+| hello-panel (walkthrough exemplar) | 4101-4899 | 4xx | doc-reserved; teaching exemplar in `packages/rcf-lite/docs/blueprint-authoring-walkthrough.md`, not shipped as a blueprint directory | `operatorPanel` |
+| persistence-data-sqlite | 5101-5899 | 6xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| ci-pipeline | 6101-6899 | 7xx | shipped v1.0.0 | `ciGates`, `strictCoverageGate` |
+| observability-essentials | 7101-7899 | 8xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics`, `statusPageContract` |
+| security-secrets-management | 8101-8899 | 9xx | shipped v1.0.0 | `secretsSource` |
+| security-auth-clerk | 9101-9899 | 10xx | shipped v1.0.0 | `authModel` |
+| security-auth-oauth2 | 10101-10899 | 11xx | shipped v1.0.0 | `authModel` |
+| security-auth-keycloak | 11101-11899 | 12xx | shipped v1.0.0 | `authModel` |
+| deploy-cloudflare-workers | 12101-12899 | 13xx | shipped v1.0.0 | `deploymentTarget` |
+| persistence-data-d1 | 13101-13899 | 14xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| observability-probe-endpoints | 14101-14899 | 15xx | shipped v1.0.0 | `healthProbes`, `readinessSemantics` |
+
+US 12101-12112 sit at the LOW end of the 12101-12899 band on purpose. A project-side story that mechanically derives from a deploy-cloudflare-workers REQ id into the number `12112` would collide against deploy-cloudflare-workers-US-12112 in this package; the band leaves headroom at the HIGH end (US 12181-12899) so a project's own stories anchored to deploy-cloudflare-workers REQs can allocate without conflict. The watchpost run4 lesson applies here too. Band spacing between the last shipped block (security-secrets-management, 8101-8899, 9xx) and this one (12101-12899, 13xx) leaves the 9xxx-11xxx US bands and the 10xx-12xx suffix blocks open for concurrent-lane authoring so a peer authoring another blueprint in the same PR window does not collide with this one.
+
+## Shared expectations for future composing blueprints
+
+- Reuse `deploymentTarget` exactly as spelled here when your blueprint holds an opinion on the project's deployment shape; contribute your own scope:global ADR on that string and let composition surface the pairing. A container-image-per-commit blueprint, a merge-to-production blueprint, or a serverless-function-per-endpoint blueprint will conflict here by design and expect a project-level ADR resolution.
+- Vendor choice sits at ADR-1302 (scope-local) by design: the contract is at ADR-1301, the default is at ADR-1302. A composing blueprint that wants a different DEFAULT vendor without changing the contract does not conflict on `deploymentTarget`; the operator supersedes ADR-1302 with a project-level ADR and swaps the vendor binding.
+- Preview-vs-production URL model (ADR-1303), rollback-is-promote posture (ADR-1304), and dev-mode drift posture (ADR-1305) are scope-local. A composing blueprint that holds an opinion on any of them authors its own project-level ADR; none of them are minted as globals because the space of legitimate variations is smaller than the space of legitimate `deploymentTarget` variations.
+- Global topics that plausibly belong to a future blueprint and are NOT claimed by any shipped blueprint: `messageSerialisation` and `deliverySemantics` (a message-consumer blueprint's natural globals), `caching` (unclaimed by every shipped blueprint), `metricsExport` and `tracingProtocol` (natural globals for a metrics or tracing blueprint), `deploymentPackaging` (unclaimed; a natural global for a container-image or artefact-bundling blueprint that composes above the deploy target). Define any of these in your own package's topics doc, in this file's format, and consider whether the band-registry table above needs your slug added.

package/blueprints/deploy-cloudflare-workers/guide/deploy-cloudflare-workers.md

@@ -0,0 +1,74 @@
+# Deploy Cloudflare Workers blueprint guide
+
+## What it is
+
+A default deployment floor for small greenfield rcf-lite projects that ship to an edge-runtime target. The blueprint contributes the WHAT of a deployment pattern: how the project declares its deploy shape in a repo-root wrangler manifest, how one Deploy Adapter is the sole caller of the deploy vendor, how every merge to the main branch uploads an artefact version reachable at both a permanent per-version-id URL and a stable preview alias URL, how production only changes when the operator triggers an explicit promote workflow, how rollback rides the same promote path with a prior version id supplied, how every promote runs bounded served-surface probes against the production URL, how local dev-mode is refused as coverage for deployed-scope ACs, and how every uploaded version carries build provenance readable at a fixed health probe.
+
+Concretely, the blueprint ships twelve requirements, twelve user stories (thirty-six acceptance criteria), six architecture components, and five architecture decision records. One ADR is `scope: global` on the `deploymentTarget` topic; the other four are scope-local operational ADRs (default vendor, preview-vs-production URL model, rollback-is-promote posture, dev-mode drift posture) that a composing blueprint does not conflict with by default.
+
+## What it is not
+
+Not a vendor CLI. The default vendor named in ADR-1302 is Cloudflare Workers via the `wrangler` CLI, chosen for the zero-infrastructure floor the rcf-lite tier expects. Larger deployments supersede ADR-1302 with a project-level ADR and swap the adapter's vendor binding for Fly, Vercel, a hyperscaler's FaaS surface, or a project-authored target; the ADR-1301 contract stays intact.
+
+Not a promote-approval workflow. The blueprint mandates that production only changes on an explicit operator trigger; who is allowed to hit the trigger and whether a second reviewer must approve first is a CI-platform authorisation concern that layers above the `workflow_dispatch` primitive. A project that wants two-person integrity on every promote wraps the `promote` workflow in the platform's manual-approval primitive.
+
+Not a canary controller. The vendor's own gradual-rollout primitives (percentage-scoped promotes on Cloudflare's `wrangler versions deploy`, or the equivalent on another vendor) are optional operator patterns above the blueprint. The blueprint mandates the served-surface verifier on the eventual full promote; a project running a percentage rollout invokes the verifier on the final 100% promote and adds its own probe cadence during the ramp.
+
+Not an artefact registry. The deploy vendor's own version-upload primitive IS the artefact store. The blueprint does not introduce a container registry, a bundle archive, or an object-storage-backed release store; a project that wants those authors them above the blueprint.
+
+Not a status page. The observability-essentials blueprint owns `statusPageContract`; this blueprint's deploy-log feeds records into whatever status-page implementation the operator wires above. The blueprint fixes the SHAPE of the deploy-log record, not where the records land or how they are rendered to users.
+
+Not the secrets pipeline. The security-secrets-management blueprint owns `secretsSource`; this blueprint consumes the secrets contract for the vendor API token and any application secret bindings the Worker reads at runtime. A project that has not applied the secrets blueprint authors an equivalent contract themselves; the deploy blueprint's REQ-006 references the contract by shape, not by that blueprint's slug.
+
+## When to reach for it
+
+Reach for the deploy-cloudflare-workers blueprint when:
+
+- The project ships to an edge-runtime target or is willing to fit into one; the runtime model (per-request handler, no long-lived process, bindings for storage and compute) matches what the project needs.
+- The default vendor's zero-infrastructure floor is real for the project (no cluster to run, no image registry to feed, no per-region deploy control needed on day one), or the operator is willing to supersede ADR-1302 with a different vendor and swap the adapter's binding.
+- The team wants merge-to-preview and explicit-promote-to-production as a durable pattern, not as a discipline held by convention. The blueprint's promote-is-explicit invariant is enforced at the workflow-file level, not at the reviewer's memory.
+- Rollback needs to sit on the same ship path as forward promote; the same audit trail, the same secret binding, the same served-surface verifier. An incident is the wrong time to discover a bespoke rollback script has drifted.
+- The project is willing to run bounded served-surface probes against the production URL immediately after every promote. A promote that does not verify what it just shipped is not the shape this blueprint contributes.
+- The project is a small greenfield rcf-lite deployment (single Worker or a small Worker fleet, one small team or one solo operator, no ops team standing by) where the zero-infrastructure deploy story is a feature.
+
+## When it does not fit
+
+Do not reach for the deploy-cloudflare-workers blueprint when:
+
+- The project runs a long-lived process (a WebSocket server holding thousands of connections, a queue worker with a heavy warm-up, a stateful game server). The Worker runtime is per-request; the blueprint's contract assumes an artefact-upload + explicit-promote model. A project on a long-lived-process shape wants a different deploy target and a different blueprint.
+- The project has a hard corporate mandate for a specific hyperscaler and there is no useful default to ship on day one because everything already lives in that hyperscaler. Apply the blueprint anyway if you want the ADR-1301 contract, but expect to supersede ADR-1302 with a project-level ADR at apply time and swap the vendor binding.
+- The project requires per-region deploy control finer than what the default vendor's own gradual-rollout primitives support. The blueprint composes cleanly with a canary controller layered above; if the controller is the ship path itself, the blueprint's promote-is-explicit invariant becomes a fit only if the controller wraps the promote workflow rather than replacing it.
+- Compliance requires a deploy audit stream shape different from the one the blueprint fixes (a regulator-mandated field set, a specific SIEM schema). The blueprint fixes the SHAPE of the deploy-log record; a project with a stricter schema supersedes the relevant TAC responsibility with a project-level ADR that names the target schema and the mapping.
+- The deploy target has no working custom-domain or workers.dev production route (a fully self-hosted stack, an air-gapped deployment). The blueprint's URL model assumes both a preview alias URL and a production URL exist and are distinct hostnames; a fully self-hosted target picks a different blueprint (a future `deploy-docker-compose-vps` blueprint at a different altitude would fit).
+
+An earlier design pass scoped a Fly.io-paired shipping candidate (`deploy-fly-io`) alongside this one under a two-or-none rule for accountBound blueprints. The rule was amended (2026-08-30) from a hard shipping gate to demand-driven direction; a second accountBound deploy blueprint mints when demand arrives. Neutrality is served by the ADR-1301 contract, by the vendor-agnostic adapter port at TAC-1301, and by ADR-1302 explicitly reserving Fly.io, Vercel, hyperscaler FaaS, and self-hosted VPS as promotion paths superseded through a project-level ADR.
+
+## What a good outcome looks like
+
+A project applies the blueprint on a fresh tree, declares its Worker in `wrangler.toml` at the repo root (name, main entry, `compatibility_date`, and every binding the Worker reads), picks its preview alias string (`main` is the common default), realises the six TACs in project-authored FBSes with the default `wrangler`-shelling vendor binding, wires the two GHA workflows from the ship assets, and lands on a deployed application where:
+
+- Every merge to main produces an uploaded Worker version reachable at a stable preview alias URL (say `main-app.example.workers.dev`) and at a permanent per-version-id URL (a hostname prefixed by the vendor's version-id primitive). The `build-and-upload` run's summary carries both URLs and the version id.
+- The production URL (say `app.example.com` on a mapped custom domain) is a third, distinct hostname. It continues to serve the previously-promoted version until an operator triggers the `promote` workflow.
+- The `promote` workflow runs on `workflow_dispatch` with an optional `versionId` input. Empty defaults to the newest-of-main resolved through the Deploy Adapter's `resolveNewestOfMain`; a hotfix or rollback supplies an explicit version id from `deployAdapter.listVersions()`.
+- Every promote runs the Served-surface Verifier against the production URL: at least the `/healthz` probe returning a JSON body whose `versionSha` matches the promoted version's build sha, plus one project smoke probe. A probe breach fails the workflow with `PROMOTE_VERIFY_FAILED` and refuses to mark the release successful.
+- Rollback is `promote` with a prior version id supplied. The audit trail is uniform: the same `promotedVersionId`, `promotedBy`, `previousVersionId`, `promotedAt` fields on every promote record, indistinguishable in shape between a forward promote and a rollback.
+- The Worker's health probe answers with the commit sha, the build ISO 8601 timestamp, and the CI run URL that produced the version. A single request to `/healthz` on any of the three URL kinds identifies which version is being served without any dashboard step.
+- The wrangler manifest is safe to review: no secret value lives in it; every secret binding is declared by name only and populated on the deploy target through the secrets contract. A CI redactor guarantees no log line emits any resolved secret value.
+- Tests scoped `deployed` in the RCF coverage tag run against the preview URL, the per-version-id URL, or the production URL; the coverage gate refuses a binding whose target is a dev-mode local URL. Dev-mode remains valid for `runtime`-scope tests and for developer-loop iteration.
+
+## Operator decisions that remain open after apply
+
+- Vendor choice (Cloudflare Workers default, or a superseding project-level ADR selecting Fly.io, Vercel, AWS Lambda, GCP Cloud Run, or a project-authored target). Blueprint owns the contract on both sides of the boundary; project owns the vendor.
+- Preview alias string (`main` common default; project-specific names supported). Blueprint owns the alias-URL discipline; project owns the string.
+- Production URL shape (custom domain mapped through the vendor, or a workers.dev production hostname on projects without a custom domain). Blueprint owns the constraint that production and preview URLs are distinct; project owns the choice.
+- Probe set for the served-surface verifier (the health probe is mandatory; each smoke probe is a project decision informed by the project's own surface). Blueprint owns the retry bounds and the pass criteria; project owns the paths and the expected shapes.
+- Health-probe path (`/healthz` common default; project may pick another). Blueprint owns the response-body shape and its role as verifier evidence; project owns the path.
+- CI platform (GitHub Actions default, ships as a shipped asset; other platforms adapt the trigger stanzas and input handling). Blueprint owns the workflow behaviour; project owns the platform adaptation.
+- Promote authorisation model (the CI platform's own permission model on the manual-trigger primitive, plus any operator-added approval steps). Blueprint owns that promote is an explicit act; project owns who may perform it.
+- Deploy-log sink (a JSONL file in a durable location, an audit event bus, a database table, a status-page ingestion source through the observability-essentials blueprint). Blueprint owns the record shape; project owns where records land.
+- Rollback-window depth (how many prior versions the operator keeps discoverable through `listVersions`). Blueprint owns that rollback IS a promote; project owns the depth policy.
+- Custom-domain provisioning (project-owned; the blueprint does not itself mint DNS or issue TLS). The vendor's own custom-hostname primitive is where the project binds the production URL to a domain it controls.
+
+## Cost-honesty paragraph
+
+Shipping this doc set costs the project the following. Every ship to production is now a two-step act (merge to main, then an operator-triggered promote) instead of a single-step merge-to-production; the discipline is intentional and adds a small friction to prototype-shaped work where merge-to-production is fine. The default Cloudflare Workers vendor commits the project to an edge-runtime shape; a project whose runtime needs a long-lived process cannot use the default and has to supersede ADR-1302. The served-surface verifier fails CI on real drift; a project that wants faster promotes buys them by tightening the probe set or by accepting a larger risk of a failed promote, neither is free. The three URL kinds (per-version-id, stable alias, production) are three hostnames the project has to reason about; a project that would rather have one hostname loses the class of leaks-through-collapsed-URL the blueprint's ADR-1303 closes. The wrangler manifest becomes a piece of documentation the project maintains as part of its normal change flow; a project that would rather push deploy config into ad-hoc shell scripts loses the manifest's own validation gate. The deploy-log record is a stream the project now maintains; wiring it to a real sink (a status page, a SIEM, a data warehouse) is a project cost the blueprint does not carry. The blueprint says nothing about the vendor's own dashboard workflows, about DNS and TLS provisioning outside the vendor's own custom-hostname primitive, about compliance reporting on deploy events, or about staged canary or blue-green rollouts; a project that needs any of those spends its own build cycles on them and this blueprint does not save it any work there.

package/blueprints/email-smtp-resend/README.md

@@ -0,0 +1,45 @@
+# Email SMTP Resend blueprint (v1.0.0)
+
+The ninth content blueprint on the rcf-build-lite blueprint mechanism. Scope: a Resend-backed mail-adapter that fills the magic-link blueprint's `TAC-504-security-auth-magic-link-email-delivery-adapter` slot as a shipped default. Transport is Resend's SMTP submission endpoint (keeps the adapter close to a generic SMTP shape a follow-up `email-smtp-<othervendor>` blueprint can sibling cleanly). Vendor default is Resend; the mail-adapter contract itself lives on the magic-link blueprint and remains vendor-neutral. Ships two TACs (send adapter, delivery-webhook verifier), no scope:global ADRs.
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/email-smtp-resend
+```
+
+Phase 1 resolves local path sources only; registry and git-ref resolution is a mechanism follow-up. Apply is idempotent; `rcf define blueprint list` shows the applied entry grouped under the `email` category; `rcf define blueprint remove email-smtp-resend` cleanly removes an unreferenced application.
+
+## Anatomy
+
+| Piece | Where | What |
+|---|---|---|
+| Metadata | `blueprint.json` | Slug, version, category `email`, and 16 contributions (all scope-local) |
+| Doc set | `contributions/` | 6 REQs, 6 USs (15 ACs), 2 TACs, 2 ADRs, all schema-valid and namespaced (`email-smtp-resend-REQ-001` prefix family; `TAC-401-email-smtp-resend-send-adapter` suffix family) |
+| Stub adapter reference | `assets/stub-adapter.md` | Record-only test double shape-compatible with the real adapter and with the magic-link blueprint's `TAC-504` interface |
+| From-address rotation pattern | `assets/from-address-rotation-pattern.md` | Generic reference-per-surface routing shape for projects that ship several product surfaces from several verified domains; placeholder values only |
+| Resend verification pointer | `assets/resend-verification-pointer.md` | Public-docs pointer for Resend's sender-domain verification workflow; no embedded checklist |
+| Guide | `guide/email-smtp-resend.md` | Operator-facing: when to use it, when not, what stays your call, the promotion signals for an API-transport supersede and a sibling vendor blueprint |
+| Coordination vocabulary | `docs/topics.md` | The id band this blueprint owns (US 4101-4899, ADR/TAC 4xx), the shared id-band registry across the shipped set, and the reason this blueprint contributes zero scope:global topics |
+
+The doc set is contributions (copied into the project tree by `rcf define blueprint add`); the guide, assets, and docs are package-resident references. Guide rendering into `rcf/knowledge/docs/blueprint-guides/` and asset ingestion are mechanism follow-ups; until they land, the working agent reads them from the applied blueprint's source path recorded in `manifest.blueprints[].source`.
+
+## What it contributes, and what it deliberately does not
+
+Contributed kinds: REQ, US (with inline ACs), TAC, ADR. Adherence is expressed as ACs; the blueprint ships no test files (ratified decision 5) and no code.
+
+No FBS contributions, as a matter of principle (ratified policy 2026-08-19): FBSes are the work of the implementing agent, not the blueprint; project constraints have to be applied at the time of creation. The blueprint contributes the WHAT (the send-contract shape, the SMTP transport choice, the four-class error taxonomy, the retry-and-backoff posture, the webhook signature verification, the replay defence, the boundary discipline on the SMTP client library and the secret references); the implementing agent derives the HOW-tasks (FBS) in the host project, where the ACs contributed here get picked up by the project's own build sequencing.
+
+Deliberately not contributed: the magic-link blueprint's auth routes themselves (they live on the magic-link blueprint; this blueprint is an ADAPTER only); the mail-adapter interface as a global topic (the interface belongs to the magic-link blueprint's `TAC-504`, not to this blueprint); an SMTP client library or an HTTP client library (project picks from what it already carries; the adapter injects the client at boot); a specific YAML or JSON schema library; a Secrets Manager client (composable with the shipped `security-secrets-management` blueprint or with a project-authored secret-reference resolver of the same shape); a shared event bus for delivery events (the verifier hands parsed events to a downstream handler the project realises; where those events go beyond the handler is a project concern); regulatory or compliance workflow (double-opt-in surfaces, unsubscribe UI, retention of consent records live outside this blueprint's scope); the Resend HTTP API path (project supersedes ADR-401 and swaps the adapter's internal client if the API path is preferred, without changing the interface the auth routes call).
+
+## The zero-global-topic story
+
+This blueprint contributes no `scope: "global"` ADR topics on purpose. The mail-adapter contract is owned upstream on the magic-link blueprint's `TAC-504`; the transport choice and the retry posture are project-local decisions a project can supersede with a project-level ADR without cross-blueprint conflict. Neither is a shared vocabulary a composing blueprint needs to conflict with by string equality. See `docs/topics.md` for the exact reasoning, the id-band allocation (US 4101-4899, ADR/TAC suffix block 4xx), and the shared-registry table.
+
+## Quality bar
+
+One `send({ to, subject, textBody, htmlBody })` method as the sole auth-facing surface; the fixed outcome shape `{ ok, providerStatus, providerMessageId, error }` on every call; exactly one SMTP submission per adapter call on the successful path; four-class error taxonomy (`RESEND_RATE_LIMITED`, `RESEND_SENDER_UNVERIFIED`, `RESEND_RECIPIENT_REJECTED`, `RESEND_TRANSPORT_ERROR`) surfaced on the `error` field with no recipient identity leaked; bounded jittered retry on transient classes and immediate return on terminal classes; webhook signature verification against the configured signing secret with constant-time comparison; HTTP 401 empty-body refusal on mismatch with a `webhookVerificationFailed` audit; stale-timestamp refusal against the configured tolerance window with a `webhookReplayStale` audit; duplicate-event-id refusal against a bounded event-id store with a `webhookReplayDuplicate` audit and HTTP 200 acknowledgement; the SMTP client library imported from exactly one module (the adapter); no literal SMTP credential, sender address, or signing secret in adapter source. Every bar is carried by ACs in the doc set, not by this README.
+
+## Known mechanism-reach gaps
+
+None at v1.0.0. Every AC on every story is bound to at least one TAC that the host project must realise, and every AC's `then` clause is runtime-observable in the deployed application (SMTP submission counters for send-side ACs, byte-scan for recipient-identity suppression, HTTP status and audit-sink observation for webhook ACs, source-tree import-graph scan for the SMTP-client boundary property, source-scan for the no-literal-credential property). The mechanism-reach principle from the authoring standard section 7 is satisfied at ship: a project that applies this blueprint and does not realise a TAC leaves an unresolved `tacIds` reference on the story that `rcf define validate` and `rcf audit coverage` refuse. The one operational surface a project must own on its own is the SMTP client library selection and the event-id store choice (an in-memory LRU for a single-process deployment, a shared store for a horizontally-scaled deployment); each is stated as a TAC interface, not as a smuggled runtime probe. The one AC whose runtime observability depends on operator readiness is AC-4101-2 (the happy-path successful send), which requires a verified sender domain with the provider; the AC is scoped to a running project whose configuration passes verification, and the `assets/resend-verification-pointer.md` pointer names where the operator completes that work.

package/blueprints/email-smtp-resend/assets/from-address-rotation-pattern.md

@@ -0,0 +1,44 @@
+# From-address rotation pattern (generic)
+
+The adapter's from-address is one configuration reference (`RESEND_FROM_ADDRESS`). A project that ships one product from one verified domain sets one value and moves on. A project that ships several product surfaces from several verified domains uses this pattern to keep the reference-per-surface story clean without hardcoding domain literals into the adapter or the auth wiring.
+
+## Shape
+
+```yaml
+mailFromByProduct:
+  productAlpha:
+    reference: FROM_ADDRESS_PRODUCT_ALPHA
+    subjectPrefix: "Product Alpha"
+  productBeta:
+    reference: FROM_ADDRESS_PRODUCT_BETA
+    subjectPrefix: "Product Beta"
+  transactional:
+    reference: FROM_ADDRESS_TRANSACTIONAL
+    subjectPrefix: null
+```
+
+- One reference name per surface. Values live in the vendor the project's secret resolver reads from; the map above carries only the reference names.
+- The `subjectPrefix` is an optional string a surface may want prepended to the outbound subject; leave `null` for surfaces that pass a fully-composed subject.
+- Any real domain, product name, or sender local-part stays out of this file; the map is a routing table over reference names, not a directory of live addresses.
+
+## How the adapter reads the map
+
+The project's composition wires a `mailFromSelector({ productKey })` in front of the adapter. The selector reads the map, resolves the reference name against the project's secret resolver, and passes the resolved from-address into the adapter's `send` call. The adapter itself continues to consume one from-address per call; the routing lives one level up.
+
+## What the pattern is not
+
+- Not a mail-templating engine. The `subjectPrefix` is a routing detail, not a template layer.
+- Not a domain-verification workflow. The pattern assumes every reference in the map resolves to a value the provider has already verified; see `resend-verification-pointer.md` for where to point the operator for verification.
+- Not a rate-limiting policy. Sending volume decisions live in a project-level ADR, not in this file.
+
+## Example generic values (placeholders only)
+
+The reference names above are illustrative. Real values look like generic placeholders and never appear in this file:
+
+```
+FROM_ADDRESS_PRODUCT_ALPHA -> notifications@example.test
+FROM_ADDRESS_PRODUCT_BETA -> notifications@example.test
+FROM_ADDRESS_TRANSACTIONAL -> notifications@example.test
+```
+
+`example.test` is the IETF reserved test domain; a real project resolves each reference to its own verified sender address inside the vendor the secret resolver reads from.

package/blueprints/email-smtp-resend/assets/resend-verification-pointer.md

@@ -0,0 +1,25 @@
+# Resend sender-domain verification pointer
+
+Sender-domain verification is a provider-owned operation the project performs against Resend before any outbound message is accepted. This file is a pointer to Resend's own public documentation, not a copy of Resend's verification checklist. Copies drift; the pointer does not.
+
+## Where the operator goes
+
+Resend maintains public documentation covering sender-domain setup and the DNS records required (SPF, DKIM, DMARC alignment). The operator applies the blueprint, then walks Resend's own step list against the domain they intend to send from. The blueprint does not restate those steps because Resend owns the source and updates it on its own cadence.
+
+- Resend's public docs are hosted under the provider's own docs site; the operator finds the sender-domains section through the provider's own top-level navigation.
+- The DNS records the provider requires are published on the provider's own docs page; they change from time to time and the provider's page is the current source.
+- The verification-passing UI signal is published on the provider's own dashboard; the operator confirms verification there before running the blueprint's runtime-verify AC that requires a real send.
+
+## What the blueprint gates on locally
+
+Independent of Resend's verification workflow, this blueprint's `AC-4102-1` gates the runtime-verify of the unverified-sender refusal class: a fresh project applying the blueprint before verifying the from-address with the provider will observe `RESEND_SENDER_UNVERIFIED` returned from the adapter. The refusal is the AC's binding, not a bug; the AC passes because the class is surfaced correctly. The operator then completes the provider-side verification and observes the happy-path AC (AC-4101-2) pass on the same running project.
+
+## What this file is not
+
+- Not a substitute for the provider's docs. If a step here contradicts the provider's own page, the provider's page is authoritative.
+- Not a domain-selection guide. Which domain the project sends from is a project-side decision this blueprint does not touch.
+- Not a compliance checklist. Regulatory requirements (double-opt-in, unsubscribe surfaces, retention of consent records) live outside this blueprint's scope; a project subject to them handles them separately.
+
+## Placeholder-only examples
+
+The example addresses that appear elsewhere in this blueprint's assets use IETF reserved test domains (`example.test`, `example.com` where the RFC permits) and are never real deliverable addresses. A real project resolves its own verified addresses through the configured secret resolver and never commits them to the repo.

package/blueprints/email-smtp-resend/assets/stub-adapter.md

@@ -0,0 +1,65 @@
+# Stub Resend send adapter (record-only test double)
+
+TAC-401 names a stub-adapter implementation the project wires into its test harness in place of the real Resend transport. The stub records every outgoing call in memory, resolves a fixed successful outcome by default, and lets a test override the outcome on a per-call basis. The stub satisfies exactly the same `send({ to, subject, textBody, htmlBody })` interface the real adapter does, so a project can swap it in without touching the auth wiring.
+
+## Interface satisfied
+
+```
+send({ to, subject, textBody, htmlBody })
+  -> Promise<{ ok, providerStatus, providerMessageId, error }>
+```
+
+The stub is shape-compatible with the magic-link blueprint's `TAC-504-security-auth-magic-link-email-delivery-adapter` and with the real Resend send adapter (`TAC-401-email-smtp-resend-send-adapter`); either can be swapped for the other at composition time.
+
+## Fixed outcome (default successful case)
+
+```json
+{
+  "ok": true,
+  "providerStatus": 202,
+  "providerMessageId": "stub-<n>",
+  "error": null
+}
+```
+
+`<n>` is the 1-based ordinal of the call in the recording session, so a test asserting on `providerMessageId` has a stable value to bind to.
+
+## Fixed outcome (constructed failure case)
+
+Constructed by the test with an override on the stub:
+
+```json
+{
+  "ok": false,
+  "providerStatus": 429,
+  "providerMessageId": null,
+  "error": "RESEND_RATE_LIMITED: stub configured to fail on attempt 1"
+}
+```
+
+Every failure the stub returns starts with one of the four class codes named by REQ-003 (`RESEND_RATE_LIMITED`, `RESEND_SENDER_UNVERIFIED`, `RESEND_RECIPIENT_REJECTED`, `RESEND_TRANSPORT_ERROR`); tests binding to the class code are portable between the stub and the real adapter.
+
+## In-memory call log shape
+
+The stub exposes `sends`, an array of every call in the order received:
+
+```json
+[
+  {
+    "to": "operator@example.test",
+    "subject": "Sign in",
+    "textBody": "Someone asked to sign in ...",
+    "htmlBody": "<!doctype html>..."
+  }
+]
+```
+
+Tests assert on `sends[0].to`, `sends[0].textBody.includes(signInUrl)`, and `sends.length === 1` per AC-4101-3.
+
+## Retry harness
+
+For AC-4103-1 and AC-4103-2, the stub exposes a `program` on which the test scripts a sequence of return values consumed one per attempt: `[{ ok: false, error: 'RESEND_RATE_LIMITED: ...' }, { ok: true, providerStatus: 202, ... }]` returns rate-limited on the first attempt and accepts on the second. The stub increments a `submissionCounter` on every call the retry loop makes, which is the counter AC-4103-1 through AC-4103-3 bind to.
+
+## Do not use in production
+
+The stub is a test surface. Loading the stub in a production build silently defeats the send flow: mint succeeds, no message ever leaves the process, and only the presence of the stub in the deployment's dependency graph would tell an operator what happened. A project's deployment configuration refuses the stub adapter's module name in production; the mechanism for that refusal is a project-side configuration decision, not shipped in this blueprint.

package/blueprints/email-smtp-resend/blueprint.json

@@ -0,0 +1,23 @@
+{
+  "slug": "email-smtp-resend",
+  "version": "1.0.0",
+  "category": "email",
+  "contributions": [
+    { "id": "email-smtp-resend-REQ-001", "kind": "req", "path": "requirements/email-smtp-resend-req-001.json" },
+    { "id": "email-smtp-resend-REQ-002", "kind": "req", "path": "requirements/email-smtp-resend-req-002.json" },
+    { "id": "email-smtp-resend-REQ-003", "kind": "req", "path": "requirements/email-smtp-resend-req-003.json" },
+    { "id": "email-smtp-resend-REQ-004", "kind": "req", "path": "requirements/email-smtp-resend-req-004.json" },
+    { "id": "email-smtp-resend-REQ-005", "kind": "req", "path": "requirements/email-smtp-resend-req-005.json" },
+    { "id": "email-smtp-resend-REQ-006", "kind": "req", "path": "requirements/email-smtp-resend-req-006.json" },
+    { "id": "email-smtp-resend-US-4101", "kind": "us", "path": "user-stories/email-smtp-resend-us-4101.json" },
+    { "id": "email-smtp-resend-US-4102", "kind": "us", "path": "user-stories/email-smtp-resend-us-4102.json" },
+    { "id": "email-smtp-resend-US-4103", "kind": "us", "path": "user-stories/email-smtp-resend-us-4103.json" },
+    { "id": "email-smtp-resend-US-4104", "kind": "us", "path": "user-stories/email-smtp-resend-us-4104.json" },
+    { "id": "email-smtp-resend-US-4105", "kind": "us", "path": "user-stories/email-smtp-resend-us-4105.json" },
+    { "id": "email-smtp-resend-US-4106", "kind": "us", "path": "user-stories/email-smtp-resend-us-4106.json" },
+    { "id": "TAC-401-email-smtp-resend-send-adapter", "kind": "tac", "path": "tacs/tac-401-email-smtp-resend-send-adapter.json" },
+    { "id": "TAC-402-email-smtp-resend-webhook-verifier", "kind": "tac", "path": "tacs/tac-402-email-smtp-resend-webhook-verifier.json" },
+    { "id": "ADR-401-email-smtp-resend-transport-choice", "kind": "adr", "path": "adrs/adr-401-email-smtp-resend-transport-choice.json" },
+    { "id": "ADR-402-email-smtp-resend-retry-and-backoff-posture", "kind": "adr", "path": "adrs/adr-402-email-smtp-resend-retry-and-backoff-posture.json" }
+  ]
+}

package/blueprints/email-smtp-resend/contributions/adrs/adr-401-email-smtp-resend-transport-choice.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-401-email-smtp-resend-transport-choice",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "The default Resend transport is the SMTP submission endpoint, not the Resend HTTP API",
+  "context": "Resend supports both an HTTP API and an SMTP submission endpoint. The blueprint's job is to fill the magic-link blueprint's `TAC-504-security-auth-magic-link-email-delivery-adapter` slot with a shipped default. A shipped default has to make a transport choice; both surfaces satisfy the mail-adapter contract. The choice is scope-local: a project that prefers the API path supersedes this decision with a project-level ADR and swaps the adapter's internal client without changing the interface the auth routes call.",
+  "decision": "The default transport is the Resend SMTP submission endpoint. The adapter uses a plain SMTP client library the project already carries or picks up, dialled at the endpoint host and port declared as configuration references. This keeps the adapter's shape close to a generic SMTP surface: a follow-up `email-smtp-<othervendor>` blueprint (a Postmark-SMTP, an SES-SMTP, a Mailgun-SMTP) can sibling with a minimal delta on the classification table and the endpoint references, sharing the retry loop, the credential resolution, and the boundary discipline. The SMTP path also keeps the adapter's runtime dependency footprint to one SMTP client library and Node built-ins, which is the rcf-lite tier's shape.",
+  "consequences": "The adapter is close to reusable across SMTP-speaking providers; a sibling blueprint is a delta, not a rewrite. The trade against the Resend HTTP API is that the API surfaces richer per-provider metadata (tag propagation, native idempotency keys, structured provider errors) the SMTP path does not carry; a project that needs that metadata supersedes this ADR and swaps in an API-based adapter that still satisfies the shared send contract. The SMTP path also inherits SMTP's operational quirks (SMTP-specific rate-limit signalling, provider-specific reply-code prose the classification table has to know about, connection reuse patterns the SMTP client library governs); the classification table lives in one place in the adapter for exactly this reason.",
+  "alternativesConsidered": [
+    {
+      "name": "Resend HTTP API as the default transport",
+      "summary": "Adapter posts to Resend's REST endpoint using an API key; retries and classification key off HTTP status codes and the provider's JSON error shape.",
+      "reasonNotChosen": "Reserved as the primary supersede path for projects that want the provider's richer per-send metadata (tags, custom headers, idempotency keys). The trade against SMTP is a heavier runtime binding (an HTTP client and a provider-specific JSON contract) and adapter shape that does not port cleanly to a non-Resend follow-up blueprint. A project-level ADR supersede plus an adapter swap is the intended path."
+    },
+    {
+      "name": "Provider-agnostic SMTP with no vendor commitment at v1",
+      "summary": "Ship a generic SMTP adapter and let the project point it at any SMTP-speaking provider.",
+      "reasonNotChosen": "The round-2 reference commits this blueprint to a vendor default; a shipped default lets the project apply and run rather than compose and configure. A generic SMTP shape re-appears as the shared substrate a sibling blueprint reuses, without abandoning the default here."
+    },
+    {
+      "name": "Provider-native SDK",
+      "summary": "Adapter uses Resend's own SDK.",
+      "reasonNotChosen": "Pulls a vendor SDK into the runtime footprint and pins the adapter to that SDK's release cadence. The SMTP client library shape is a smaller, more stable surface the project can pick from an existing dependency it likely already has."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/email-smtp-resend/contributions/adrs/adr-402-email-smtp-resend-retry-and-backoff-posture.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-402-email-smtp-resend-retry-and-backoff-posture",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Retry is bounded to two attempts on transient classes with exponential full-jitter backoff; terminal classes never retry",
+  "context": "Every mail-adapter default has to pick a retry posture. Unbounded retry against a rate-limited transport is a self-reinforcing failure: every caller retries in lockstep, the transport's throttle escalates, and the outage lengthens. Zero retry surfaces transient network glitches as apparent hard failures the caller has to defend against on its own. The classes the classification table produces split naturally into transient (`RESEND_RATE_LIMITED`, `RESEND_TRANSPORT_ERROR`) and terminal (`RESEND_SENDER_UNVERIFIED`, `RESEND_RECIPIENT_REJECTED`); the retry posture is different for each split.",
+  "decision": "On the transient classes the adapter retries up to a bounded budget (default 2 retries, project-configurable via a numeric configuration reference; total attempts including the first are therefore at most 3) using exponential backoff with full jitter, base 250ms and cap 8000ms. On the terminal classes the adapter does not retry: it returns one result immediately with the terminal-class code. The budget and the backoff parameters live behind configuration references; a project running under a tighter latency SLA lowers the cap, a project running behind a proxy layer that already retries lowers the budget to zero, without touching the adapter source.",
+  "consequences": "A transient rate-limit refusal converts to a bounded delay (worst-case around 20 seconds across the default budget) rather than a retry storm the caller has to defend against. A terminally-invalid input (an unverified domain, a malformed recipient) surfaces immediately as one adapter return rather than looping into a rate-limit escalation. The budget and cap are ADR-scoped defaults, not blueprint-immutable numbers; a project with a firmer SLA or a heavier proxy retry layer tunes them without an ADR supersede. The full-jitter algorithm chosen is the AWS-reference exponential-backoff-with-full-jitter shape: `sleep = random_between(0, min(cap, base * 2 ** attempt))`. A project that wants a different jitter shape (equal jitter, decorrelated jitter) supersedes this ADR at the project level and swaps the jitter function; the interface the retry loop consults (`retryClock`) is factored out to support the swap.",
+  "alternativesConsidered": [
+    {
+      "name": "No retry at any layer inside the adapter",
+      "summary": "The adapter returns the first result verbatim; every caller decides its own retry policy.",
+      "reasonNotChosen": "Pushes a decision the caller almost never varies onto every caller, and lets each caller diverge on a class the transport itself treats as retryable. The class distinction is a property of the provider, not a property of the caller; centralising it in the adapter is the correct scope."
+    },
+    {
+      "name": "Unbounded retry until first success",
+      "summary": "Loop until the provider accepts.",
+      "reasonNotChosen": "Turns rate-limit refusal into a self-reinforcing outage. The bounded budget with jitter is the standard defence and is what every well-behaved SMTP-consumer library ships."
+    },
+    {
+      "name": "Retry on the terminal classes as well",
+      "summary": "Retry every non-success return regardless of class.",
+      "reasonNotChosen": "Wastes budget on an outcome the provider has already classified as invalid, and risks an unverified-sender loop tripping the provider's rate limiter. The class distinction is the point of the classification table."
+    }
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/email-smtp-resend/contributions/requirements/email-smtp-resend-req-001.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "email-smtp-resend-REQ-001",
+  "prdId": "PRD-001",
+  "title": "The adapter satisfies the mail-adapter interface named by the shipped magic-link blueprint's TAC-504",
+  "description": "The Resend send adapter exposes exactly the `send({ to, subject, textBody, htmlBody })` method the magic-link blueprint's `TAC-504-security-auth-magic-link-email-delivery-adapter` names, and resolves the fixed outcome shape `{ ok, providerStatus, providerMessageId, error }` on every call. No other method is added to the auth-facing surface; provider status codes and provider message ids are normalised into the four declared fields inside the adapter. A project composing this blueprint alongside the magic-link blueprint wires the adapter reference into the auth routes at composition time and calls `adapter.send` directly.",
+  "category": "functional",
+  "domain": "email",
+  "priority": "must",
+  "rationale": "The mail-adapter contract is the mandate the auth flow gates on; this blueprint's only reason to exist is to fill that mandate with a shipped default a project can apply and rely on. A shape that differs from TAC-504 leaves the auth routes unable to call the adapter without a project-authored shim, which defeats the shipped-default posture. Normalising provider-specific vocabulary inside the adapter keeps the auth code provider-neutral.",
+  "tags": [
+    "blueprint:email-smtp-resend",
+    "category:01-mail-adapter-contract"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/email-smtp-resend/contributions/requirements/email-smtp-resend-req-002.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "email-smtp-resend-REQ-002",
+  "prdId": "PRD-001",
+  "title": "Transport is Resend's SMTP endpoint, credentialed from placeholder-referenced secrets and a placeholder-referenced verified sender address",
+  "description": "The adapter dials Resend's SMTP submission endpoint (host and port declared as configuration references, not literal in-code strings) and authenticates with an SMTP username and an SMTP password sourced from a Secrets Manager slice. The from-address on every outgoing message is a project-configured verified sender address, also sourced from configuration rather than a literal. Three configuration references are named by the adapter: `RESEND_SMTP_USER`, `RESEND_SMTP_PASSWORD`, and `RESEND_FROM_ADDRESS`. The names are references only; the values live in the vendor the project's Secrets Manager resolves against. No SMTP credential, no signing secret, and no real sender domain is ever committed to the repo or embedded in the adapter's code paths.",
+  "category": "functional",
+  "domain": "email",
+  "priority": "must",
+  "rationale": "SMTP over the Resend endpoint keeps the adapter close to a generic SMTP shape a follow-up `email-smtp-<othervendor>` blueprint can sibling cleanly. Sourcing credentials and the sender address through placeholder references defers vendor-side secrets custody to the project's secrets-management posture (composable with the shipped `security-secrets-management` blueprint or with a project-authored equivalent) and keeps this blueprint's on-disk footprint free of secret material.",
+  "tags": [
+    "blueprint:email-smtp-resend",
+    "category:02-transport-and-credentials"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/email-smtp-resend/contributions/requirements/email-smtp-resend-req-003.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "email-smtp-resend-REQ-003",
+  "prdId": "PRD-001",
+  "title": "Provider-side failure modes are enumerated and each maps to a stable-coded error the adapter returns without leaking recipient identity",
+  "description": "The adapter enumerates four provider-side failure classes and maps each to a stable error code on the `error` field of the send-contract return shape, with `ok: false` and the provider's own status code on `providerStatus` when the provider surfaced one. The classes are: rate-limit refusal (`RESEND_RATE_LIMITED`), unverified sender domain or address (`RESEND_SENDER_UNVERIFIED`), invalid or malformed recipient input the provider rejected before dispatch (`RESEND_RECIPIENT_REJECTED`), and generic transport error covering network faults and the provider's 5xx range (`RESEND_TRANSPORT_ERROR`). The error string carries the class code and a short structured reason; the recipient address, the message subject, and the message body never appear on the returned error string, on any log line the adapter writes, or on any exception the adapter throws.",
+  "category": "functional",
+  "domain": "email",
+  "priority": "must",
+  "rationale": "A single fuzzy `error` string forces every consumer to reverse-engineer the provider's vocabulary. Enumerated codes let the auth flow, the retry policy (REQ-004), and any project-side observability layer branch on class without matching provider prose that may change. Suppressing recipient identity on the error surface keeps the anti-enumeration posture the auth blueprint gates on intact: an operator reading the adapter's log stream cannot use it to confirm a recipient exists.",
+  "tags": [
+    "blueprint:email-smtp-resend",
+    "category:03-failure-modes"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/email-smtp-resend/contributions/requirements/email-smtp-resend-req-004.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "email-smtp-resend-REQ-004",
+  "prdId": "PRD-001",
+  "title": "Retry-and-backoff posture is bounded, jittered, and refuses to loop on a rejection the provider has already classified as terminal",
+  "description": "On a `RESEND_TRANSPORT_ERROR` or a `RESEND_RATE_LIMITED` return, the adapter retries up to a bounded budget (default 2 retries, project-configurable via a numeric configuration reference; total attempts including the first are therefore at most 3) with exponential backoff and full jitter (base 250ms, cap 8000ms). On `RESEND_SENDER_UNVERIFIED` and `RESEND_RECIPIENT_REJECTED` the adapter does not retry: the provider classified the request as terminally invalid and looping wastes budget and risks a rate-limit escalation. After exhausting the retry budget the adapter returns `{ ok: false, ... }` with the last-observed provider status and the class code that caused the exhaustion; the caller sees one adapter return, not a retry storm.",
+  "category": "functional",
+  "domain": "email",
+  "priority": "must",
+  "rationale": "Unbounded or unjittered retry against a rate-limited transport is a self-reinforcing failure: every caller retries in lockstep and the transport's own throttle escalates. A jittered, bounded budget converts a transient class into a bounded delay and a terminal class into an immediate return. Skipping retry on the terminally-invalid classes stops the adapter from turning a configuration mistake (unverified domain, malformed recipient) into a retry loop the operator has to hunt.",
+  "tags": [
+    "blueprint:email-smtp-resend",
+    "category:04-retry-and-backoff"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}