rcf-lite 0.12.0 → 0.13.0

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "email-smtp-resend-REQ-005",
+  "prdId": "PRD-001",
+  "title": "Delivery events posted by Resend's webhook are signature-verified and refused when verification fails",
+  "description": "The project exposes one HTTP route the Resend webhook posts delivery events to. The webhook verifier reads the incoming request's signature header (name declared as a configuration reference), reads the timestamp header (name declared as a configuration reference), and computes the expected signature using the webhook signing secret sourced from configuration (`RESEND_WEBHOOK_SIGNING_SECRET` placeholder reference). The verifier compares the computed signature against the header using a constant-time comparison. On mismatch the verifier returns HTTP 401 with an empty body and emits a structured `webhookVerificationFailed` audit event; the delivery event is not delivered to any downstream handler. The signing secret never appears on any log line, error string, or exception message. The header names, the signing algorithm identifier, and the timestamp-tolerance window are configuration references, not literals baked into the verifier.",
+  "category": "functional",
+  "domain": "email",
+  "priority": "must",
+  "rationale": "The webhook is an inbound trust boundary. Without signature verification any process on the network can post fabricated delivery events into the project's event stream and corrupt any downstream state that keys on them. Constant-time comparison closes the timing-side-channel that variable-time comparison opens. Sourcing the signing algorithm and header names from configuration rather than literals lets a project rotate the algorithm or track a provider header-name change without editing the adapter.",
+  "tags": [
+    "blueprint:email-smtp-resend",
+    "category:05-webhook-signature"
+  ],
+  "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-006.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "email-smtp-resend-REQ-006",
+  "prdId": "PRD-001",
+  "title": "The webhook verifier refuses replayed events by rejecting stale timestamps and refusing already-seen delivery ids inside a bounded window",
+  "description": "The verifier reads the webhook timestamp header and refuses any request whose timestamp is older than the configured tolerance window (default 300 seconds, project-configurable via a numeric configuration reference); a refused request returns HTTP 401 with an empty body and emits a `webhookReplayStale` audit event. On a verification-passing request, the verifier extracts the provider's delivery event id from the payload and consults a bounded event-id store (a stateful component the project realises: an in-memory LRU sized to the tolerance window's expected event volume, or a persisted store with a matching TTL); an event id that already appears in the store is refused with HTTP 200 (idempotent replay acknowledged, no downstream side effect), and emits a `webhookReplayDuplicate` audit event. New event ids are recorded in the store with an expiry equal to the tolerance window.",
+  "category": "functional",
+  "domain": "email",
+  "priority": "must",
+  "rationale": "Signature verification alone does not defend against replay: a captured signed request can be replayed inside its signature's validity window. A timestamp-tolerance check bounds the window to what fresh delivery requires; a delivery-id memory refuses a replay inside that window. The 200-on-duplicate posture matches provider expectations that a webhook consumer be idempotent under retry; the audit event tells the operator the duplicate arrived and was handled.",
+  "tags": [
+    "blueprint:email-smtp-resend",
+    "category:06-replay-defence"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/email-smtp-resend/contributions/tacs/tac-401-email-smtp-resend-send-adapter.json

@@ -0,0 +1,53 @@
+{
+  "tacId": "TAC-401-email-smtp-resend-send-adapter",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Resend SMTP send adapter",
+  "purpose": "The one module in the project that submits outbound mail to Resend's SMTP endpoint. Satisfies the `send({ to, subject, textBody, htmlBody }) -> Promise<{ ok, providerStatus, providerMessageId, error }>` interface named by the magic-link blueprint's `TAC-504-security-auth-magic-link-email-delivery-adapter`. Normalises provider-specific status codes and error prose into the four declared fields, applies the bounded jittered retry posture named by ADR-402, and sources every credential and the from-address through configured references rather than embedded literals. Every module that hands mail to the provider imports this adapter; nothing else imports the SMTP client library or reaches around the interface.",
+  "responsibilities": [
+    "Expose `send({ to, subject, textBody, htmlBody })` as the sole auth-facing method and no other public method matching that shape (AC-4101-1).",
+    "Return `{ ok, providerStatus, providerMessageId, error }` on every call; on success `ok === true`, `providerStatus` the provider's accepted-status integer, `providerMessageId` the provider's returned identifier, `error === null` (AC-4101-2).",
+    "Dispatch exactly one SMTP submission per adapter call on the successful path (AC-4101-3).",
+    "Classify every non-success provider response into `RESEND_RATE_LIMITED`, `RESEND_SENDER_UNVERIFIED`, `RESEND_RECIPIENT_REJECTED`, or `RESEND_TRANSPORT_ERROR` and place the code at the start of the `error` string; carry the provider's own status code on `providerStatus` when the provider surfaced one (AC-4102-1, AC-4103-2).",
+    "Suppress recipient address, subject, and body from the `error` string, every log line the adapter writes for the call, and every exception the adapter throws for the call (AC-4102-2).",
+    "Retry on `RESEND_TRANSPORT_ERROR` and `RESEND_RATE_LIMITED` up to the configured budget (default 2) with exponential backoff and full jitter (base 250ms, cap 8000ms); stop on first success or on budget exhaustion (AC-4103-1, AC-4103-2).",
+    "Do not retry on `RESEND_SENDER_UNVERIFIED` or `RESEND_RECIPIENT_REJECTED`; return one result with the terminal-class code (AC-4103-3).",
+    "Be the sole importer of the SMTP client library across the deployed application's import graph (AC-4106-1).",
+    "Resolve `RESEND_SMTP_USER`, `RESEND_SMTP_PASSWORD`, and `RESEND_FROM_ADDRESS` at boot through the project's configured secret-reference resolver; carry no literal for any of the three values in adapter source (AC-4106-2)."
+  ],
+  "internalStructure": "One stateless class per process, constructed at boot with an injected SMTP client library reference, an injected secret-reference resolver (a Secrets Manager client instance, a project-authored resolver, or an environment shim satisfying the same read interface), and an injected clock and jitter source the retry loop consults. The retry loop is a private method inside the class; the public surface is one method. Provider-response classification is a private function that maps SMTP reply codes and known provider prose to the four class codes; the classification table lives in the adapter's own module and is unit-testable in isolation.",
+  "interfaces": [
+    {
+      "name": "send",
+      "kind": "async-method",
+      "description": "send({ to, subject, textBody, htmlBody }) -> Promise<{ ok, providerStatus, providerMessageId, error }>; the sole auth-facing surface, shape-compatible with TAC-504-security-auth-magic-link-email-delivery-adapter."
+    },
+    {
+      "name": "smtpClient",
+      "kind": "read-write-api",
+      "description": "Project-supplied SMTP client library binding the adapter dials the Resend SMTP endpoint through; injected at boot, imported by no other module of the application."
+    },
+    {
+      "name": "secretResolver",
+      "kind": "read-api",
+      "description": "Project-supplied resolver returning the value for a configured reference name; the adapter calls it at boot for `RESEND_SMTP_USER`, `RESEND_SMTP_PASSWORD`, and `RESEND_FROM_ADDRESS`."
+    },
+    {
+      "name": "retryClock",
+      "kind": "callback",
+      "description": "Project-supplied clock and jitter source the retry loop consults; a real clock in production, a test double in unit tests. Injected at boot; deterministic under test."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Configured secret-reference resolver",
+      "kind": "external",
+      "description": "The project's secret-reference resolver. May be a Secrets Manager client from the shipped `security-secrets-management` blueprint, a project-authored resolver, or an environment-variable shim. The adapter reads through it and does not care which."
+    }
+  ],
+  "tradeoffs": "The adapter holds the resolved SMTP credential and the resolved from-address in memory for the lifetime of the process; a heap dump of a compromised process exposes both. That trade means the credential is materialised once at boot and the hot path is a memory read plus an SMTP submission, which is what keeps the successful path affordable. A project that wants per-send credential rotation supplies a resolver whose read on every call is not free and accepts the vendor round trip on every send. The jitter cap of 8000ms bounds worst-case adapter latency at roughly 20 seconds across the default 2-retry budget; a project running under a tighter latency SLA lowers the cap through configuration rather than bypassing the retry loop.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/email-smtp-resend/contributions/tacs/tac-402-email-smtp-resend-webhook-verifier.json

@@ -0,0 +1,56 @@
+{
+  "tacId": "TAC-402-email-smtp-resend-webhook-verifier",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Resend delivery-webhook verifier",
+  "purpose": "The inbound trust boundary for Resend delivery events. Gates the downstream handler on a constant-time signature check against the configured signing secret, refuses stale timestamps against a bounded tolerance window, and refuses replayed delivery ids against a bounded event-id store. Every request the downstream handler sees has passed all three checks; nothing else in the project accepts delivery events.",
+  "responsibilities": [
+    "Read the signature header, the timestamp header, and the request body; compute the expected signature from the body, the timestamp, and the signing secret using the configured algorithm; compare in constant time (AC-4104-1, AC-4104-2).",
+    "On mismatch, respond HTTP 401 with an empty body, skip the downstream handler, and emit one `webhookVerificationFailed` audit event (AC-4104-2).",
+    "Suppress the signing secret from the response body, from every log line the verifier writes for the call, and from every exception the verifier throws for the call (AC-4104-3).",
+    "Refuse a webhook whose timestamp header is older than the configured tolerance window (default 300 seconds) with HTTP 401, empty body, no handler invocation, and one `webhookReplayStale` audit event (AC-4105-1).",
+    "On a signature-passing request, read the provider's delivery event id from the payload and consult the bounded event-id store; refuse a duplicate with HTTP 200, no handler invocation, and one `webhookReplayDuplicate` audit event; record a new id with an expiry equal to the tolerance window (AC-4105-2).",
+    "Resolve `RESEND_WEBHOOK_SIGNING_SECRET`, the signature header name, the timestamp header name, the signing algorithm identifier, and the tolerance window at boot through the project's configured resolver; carry no literal for the signing secret in verifier source (AC-4106-2)."
+  ],
+  "internalStructure": "One stateless verifier per process, constructed at boot with an injected signature-computation function (a project-selected HMAC implementation matching the configured algorithm identifier), an injected event-id store (an in-memory LRU sized to the tolerance window or a project-authored persistent store with a matching TTL, satisfying the same put-if-absent-with-expiry interface), an injected audit sink, and an injected clock the tolerance check consults. The route handler is a thin adapter over the verifier: the verifier is the thing under test, the route wiring is not.",
+  "interfaces": [
+    {
+      "name": "verify",
+      "kind": "async-method",
+      "description": "verify({ headers, rawBody }) -> Promise<{ ok, status, event, refusal }>; returns `ok: true` with the parsed event on a passing request, `ok: false` with the HTTP status and a refusal class on any refused request."
+    },
+    {
+      "name": "eventIdStore",
+      "kind": "read-write-api",
+      "description": "Project-supplied bounded store implementing `putIfAbsentWithExpiry(id, ttlSeconds) -> Promise<{ inserted }>`; returns `inserted: false` for a duplicate id inside the window and `inserted: true` for a fresh id."
+    },
+    {
+      "name": "auditSink",
+      "kind": "callback",
+      "description": "Structured-event sink invoked with `{ event, at, principal }` for `webhookVerificationFailed`, `webhookReplayStale`, and `webhookReplayDuplicate`; never invoked with the signing secret."
+    },
+    {
+      "name": "verifierClock",
+      "kind": "read-api",
+      "description": "Project-supplied clock the tolerance check consults; a real clock in production, a test double in unit tests. Injected at boot; deterministic under test."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Configured secret-reference resolver",
+      "kind": "external",
+      "description": "The project's secret-reference resolver. May be a Secrets Manager client from the shipped `security-secrets-management` blueprint, a project-authored resolver, or an environment-variable shim. The verifier reads the signing secret and header-name references through it at boot."
+    },
+    {
+      "name": "Resend SMTP send adapter",
+      "kind": "tac",
+      "tacId": "TAC-401-email-smtp-resend-send-adapter",
+      "description": "Sibling adapter that dispatches outbound mail; the verifier and the adapter share the configured secret-reference resolver and belong to the same shelf-level blueprint."
+    }
+  ],
+  "tradeoffs": "The event-id store is a stateful component the project realises; an in-memory LRU sized to the tolerance window is cheap and defends the replay class the tolerance window bounds, but does not defend cross-process replay in a horizontally-scaled deployment. Projects running multiple webhook-consuming processes supply a shared store (a small Redis, a small database table) implementing the same put-if-absent-with-expiry interface. The constant-time comparison assumes a comparison function that itself runs in constant time over the byte length of the expected signature; a project that provides a naive comparison re-opens the timing side channel the verifier is closing.",
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/email-smtp-resend/contributions/user-stories/email-smtp-resend-us-4101.json

@@ -0,0 +1,45 @@
+{
+  "usId": "email-smtp-resend-US-4101",
+  "prdId": "PRD-001",
+  "reqId": "email-smtp-resend-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The magic-link route hands a composed sign-in URL to the adapter and the adapter dispatches one message",
+  "asA": "operator using a project that composed this blueprint alongside the magic-link blueprint",
+  "iWant": "the auth flow's mint step to call the adapter's send method and see a real message go out",
+  "soThat": "sign-in works on the deployed application without a project-authored provider shim",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-4101-1",
+      "description": "The adapter exposes exactly the `send({ to, subject, textBody, htmlBody })` method the magic-link blueprint's TAC-504 names and no other auth-facing method.",
+      "given": "the adapter module imported into a running process",
+      "when": "the process enumerates the adapter's exported surface",
+      "then": "the enumeration returns `send` as the sole async method and no other public method matches the auth-facing shape",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-4101-2",
+      "description": "A successful send resolves the fixed outcome shape `{ ok, providerStatus, providerMessageId, error }` with `ok: true`, `providerStatus` equal to the provider's own accepted-status code, `providerMessageId` equal to the provider's returned identifier, and `error` equal to null.",
+      "given": "a running project with valid configuration and a recipient the provider accepts",
+      "when": "the magic-link route calls `adapter.send({ to, subject, textBody, htmlBody })`",
+      "then": "the returned object matches the shape with `ok === true`, `providerStatus` a positive integer, `providerMessageId` a non-empty string, and `error === null`",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-4101-3",
+      "description": "Exactly one SMTP submission is dispatched per adapter call on the successful path; the adapter does not fan out to duplicates.",
+      "given": "a running project instrumented to count SMTP submissions",
+      "when": "the magic-link route triggers one adapter send",
+      "then": "the submission counter increments by exactly one and no additional submission is observed within the retry window",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-401-email-smtp-resend-send-adapter"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/email-smtp-resend/contributions/user-stories/email-smtp-resend-us-4102.json

@@ -0,0 +1,36 @@
+{
+  "usId": "email-smtp-resend-US-4102",
+  "prdId": "PRD-001",
+  "reqId": "email-smtp-resend-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The provider's unverified-sender refusal maps to a stable error code and does not leak the recipient",
+  "asA": "operator running a deployed project where the sender domain has not yet been verified with the provider",
+  "iWant": "the adapter to surface the refusal as a stable error class rather than a raw provider string",
+  "soThat": "downstream code and log readers can act on the class without parsing provider prose",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-4102-1",
+      "description": "When the provider refuses the submission because the sender domain or address is unverified, the adapter returns `{ ok: false, providerStatus, providerMessageId: null, error }` with `error` beginning with the code `RESEND_SENDER_UNVERIFIED` and `providerStatus` equal to the provider's own refusal status.",
+      "given": "a running project whose configured from-address is not verified with the provider",
+      "when": "the magic-link route calls `adapter.send({ to, subject, textBody, htmlBody })`",
+      "then": "the returned object matches the shape with `ok === false`, `providerMessageId === null`, `providerStatus` a positive integer, and `error` starting with `RESEND_SENDER_UNVERIFIED`",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-4102-2",
+      "description": "On any adapter refusal, the recipient address, subject, and body do not appear on the returned `error` string, on the adapter's log stream during the call, or on any exception the adapter throws for the call.",
+      "given": "a running project whose configured from-address is not verified with the provider and a distinctive recipient address the test can byte-scan for",
+      "when": "the magic-link route calls `adapter.send({ to: distinctiveRecipient, subject: distinctiveSubject, textBody: distinctiveBody, htmlBody })` and the call resolves",
+      "then": "the returned `error` string, every line the adapter emitted during the call, and every exception message caught contain none of the distinctive recipient, subject, or body substrings",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-401-email-smtp-resend-send-adapter"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/email-smtp-resend/contributions/user-stories/email-smtp-resend-us-4103.json

@@ -0,0 +1,45 @@
+{
+  "usId": "email-smtp-resend-US-4103",
+  "prdId": "PRD-001",
+  "reqId": "email-smtp-resend-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "A rate-limited provider triggers bounded jittered retry and returns one adapter result on budget exhaustion",
+  "asA": "operator whose project is receiving rate-limit refusals from the provider",
+  "iWant": "the adapter to retry inside a bounded budget with jittered backoff and then surface one clean failure",
+  "soThat": "a transient rate-limit refusal converts to a bounded delay rather than a retry storm the caller has to defend against",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-4103-1",
+      "description": "On a `RESEND_RATE_LIMITED` provider return the adapter retries with exponential backoff and full jitter and stops on either a successful attempt or the configured retry budget, whichever comes first; the number of SMTP submissions equals `1 + observed_retries` and observed_retries is at most the configured budget (default 2).",
+      "given": "a running project instrumented to count SMTP submissions and a provider seam that returns rate-limited on the first attempt and accepts on a later attempt within the budget",
+      "when": "the magic-link route triggers one adapter send",
+      "then": "the submission counter after the adapter returns equals `1 + observed_retries`, `observed_retries` is at least one and at most the configured budget, and the returned object has `ok === true`",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-4103-2",
+      "description": "When every attempt in the budget window returns rate-limited, the adapter returns exactly one result with `ok: false`, `error` starting with `RESEND_RATE_LIMITED`, and the submission counter equals `1 + configured_budget`.",
+      "given": "a running project with a provider seam that returns rate-limited on every attempt and configured retry budget of 2",
+      "when": "the magic-link route triggers one adapter send",
+      "then": "the adapter returns once, `ok === false`, `error` starts with `RESEND_RATE_LIMITED`, and the SMTP submission counter equals 3",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-4103-3",
+      "description": "On a `RESEND_SENDER_UNVERIFIED` or `RESEND_RECIPIENT_REJECTED` provider return the adapter does not retry; the submission counter after the adapter returns equals 1.",
+      "given": "a running project with a provider seam that returns the terminal-invalid class on the first attempt",
+      "when": "the magic-link route triggers one adapter send",
+      "then": "the submission counter equals 1 and the returned object has `ok === false` with `error` starting with the terminal class code",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-401-email-smtp-resend-send-adapter"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/email-smtp-resend/contributions/user-stories/email-smtp-resend-us-4104.json

@@ -0,0 +1,45 @@
+{
+  "usId": "email-smtp-resend-US-4104",
+  "prdId": "PRD-001",
+  "reqId": "email-smtp-resend-REQ-005",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "A webhook request with a valid signature reaches the downstream handler; a mismatched signature is refused",
+  "asA": "operator whose project accepts webhook posts from the provider",
+  "iWant": "the verifier to gate downstream delivery on a constant-time signature check",
+  "soThat": "fabricated delivery events cannot corrupt the project's event stream",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-4104-1",
+      "description": "A webhook POST whose signature header matches the expected signature computed from the request body, the timestamp header, and the configured signing secret reaches the downstream handler; the verifier returns HTTP 200 and the handler observes the parsed event exactly once.",
+      "given": "a running project with a downstream handler that counts invocations, a configured signing secret, and a POST whose signature header carries the signature the verifier computes",
+      "when": "the POST is delivered to the webhook route",
+      "then": "the response status is 200, the handler invocation counter increments by exactly one, and the parsed event delivered to the handler matches the POST body",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-4104-2",
+      "description": "A webhook POST whose signature header does not match the expected signature is refused with HTTP 401 and an empty body; the downstream handler is not invoked and a `webhookVerificationFailed` audit event is emitted.",
+      "given": "a running project instrumented to observe the audit sink and a POST whose signature header carries a mismatched value",
+      "when": "the POST is delivered to the webhook route",
+      "then": "the response status is 401, the response body is empty, the handler invocation counter is unchanged, and the audit sink observes exactly one `webhookVerificationFailed` event",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-4104-3",
+      "description": "The signing secret does not appear on the response body, on any log line the verifier writes during the call, or on any exception the verifier throws during the call.",
+      "given": "a running project instrumented to capture the verifier's log stream and any thrown exceptions, and a distinctive signing secret the test can byte-scan for",
+      "when": "a mix of matched and mismatched webhook posts is delivered",
+      "then": "no captured response body, log line, or exception message contains the distinctive signing secret substring",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-402-email-smtp-resend-webhook-verifier"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/email-smtp-resend/contributions/user-stories/email-smtp-resend-us-4105.json

@@ -0,0 +1,36 @@
+{
+  "usId": "email-smtp-resend-US-4105",
+  "prdId": "PRD-001",
+  "reqId": "email-smtp-resend-REQ-006",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "A stale-timestamp webhook is refused; a replayed delivery id is acknowledged once and never delivered twice",
+  "asA": "operator whose project stores state keyed on delivery events",
+  "iWant": "the verifier to reject replays inside the tolerance window and acknowledge duplicates without re-invoking the handler",
+  "soThat": "a captured signed request cannot corrupt downstream state and the provider's retry-on-non-2xx behaviour stays idempotent-safe",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-4105-1",
+      "description": "A webhook POST whose timestamp header is older than the configured tolerance window is refused with HTTP 401 and an empty body; the downstream handler is not invoked and a `webhookReplayStale` audit event is emitted.",
+      "given": "a running project with a configured tolerance window of 300 seconds and a POST whose timestamp header is set to a value 301 or more seconds in the past",
+      "when": "the POST is delivered to the webhook route",
+      "then": "the response status is 401, the response body is empty, the handler invocation counter is unchanged, and the audit sink observes exactly one `webhookReplayStale` event",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-4105-2",
+      "description": "A signature-valid webhook POST whose delivery event id already appears in the bounded event-id store is acknowledged with HTTP 200 without invoking the downstream handler; a `webhookReplayDuplicate` audit event is emitted.",
+      "given": "a running project with a signature-valid POST that has already been processed once (event id recorded in the store) and a second POST carrying the same event id inside the tolerance window",
+      "when": "the second POST is delivered to the webhook route",
+      "then": "the response status is 200, the handler invocation counter is unchanged from before the second POST, and the audit sink observes exactly one `webhookReplayDuplicate` event on the second POST",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-402-email-smtp-resend-webhook-verifier"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/email-smtp-resend/contributions/user-stories/email-smtp-resend-us-4106.json

@@ -0,0 +1,37 @@
+{
+  "usId": "email-smtp-resend-US-4106",
+  "prdId": "PRD-001",
+  "reqId": "email-smtp-resend-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "The adapter module is the sole importer of the SMTP client and every credential is sourced through the configured reference",
+  "asA": "operator scanning the deployed application for boundary hygiene",
+  "iWant": "the SMTP transport surface confined to the adapter module and every secret sourced from configuration",
+  "soThat": "a code-path leak of the SMTP credential cannot happen from outside the adapter and no secret material is embedded in the shipped code",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-4106-1",
+      "description": "A source-tree import-graph scan of the deployed application finds the SMTP client library imported from exactly one module: the adapter module. No other module of the application imports the SMTP client library.",
+      "given": "a project that composed this blueprint and realised TAC-401 against an SMTP client library",
+      "when": "an import-graph scan enumerates every module of the application that imports the SMTP client library",
+      "then": "the scan returns exactly one module and that module is the adapter module",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-4106-2",
+      "description": "The adapter resolves the SMTP username, the SMTP password, the from-address, and the webhook signing secret through the project's configured secret-reference resolver (a Secrets Manager client, a project-authored resolver, or an environment shim); no literal for any of the four values appears in the adapter's own source.",
+      "given": "the adapter module source and the four configuration references `RESEND_SMTP_USER`, `RESEND_SMTP_PASSWORD`, `RESEND_FROM_ADDRESS`, `RESEND_WEBHOOK_SIGNING_SECRET`",
+      "when": "the adapter source is scanned for literals and the reference names are cross-checked against the resolver invocation shape",
+      "then": "the source contains no literal for any of the four values, and each of the four reference names appears exactly at the resolver invocation site the adapter calls at boot",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-401-email-smtp-resend-send-adapter",
+    "TAC-402-email-smtp-resend-webhook-verifier"
+  ],
+  "createdAt": "2026-08-30T00:00:00Z",
+  "updatedAt": "2026-08-30T00:00:00Z"
+}

package/blueprints/email-smtp-resend/docs/topics.md

@@ -0,0 +1,44 @@
+# email-smtp-resend blueprint coordination vocabulary
+
+This file is the email-smtp-resend 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 respect these bands; email-smtp-resend contributes no scope:global ADR topics of its own.
+
+## Global ADR topics this blueprint contributes (exact strings)
+
+None. The Resend send adapter and the delivery-webhook verifier are project-local capabilities that fill the magic-link blueprint's `TAC-504-security-auth-magic-link-email-delivery-adapter` slot and the parallel delivery-event verification slot; they are not a cross-project vocabulary. Both ADRs shipped by the blueprint (ADR-401 on transport choice, ADR-402 on retry-and-backoff posture) are scope-local. A project holding a different opinion on either supersedes with a project-level ADR without conflicting on any global topic string.
+
+The neutrality rule (round-2 amendment) applies: `email-smtp-resend` ships alone in round 2 without a paired second-vendor blueprint minting alongside it. A sibling `email-smtp-<othervendor>` blueprint would inherit the same shape (SMTP transport, four-class error taxonomy, retry-and-backoff posture, webhook signature verification, replay defence) and would also ship no globals; the shared mail-adapter contract lives inside the magic-link blueprint's `TAC-504` and is a suffix-family ADR concern (`authModel` global at the magic-link blueprint) not an email-blueprint concern.
+
+## Id number bands (registry bootstrap)
+
+AC ids (and therefore US numeric ids, which anchor them) are NOT namespaced by the 0.4.4 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.
+
+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 4101-4106 sit at the LOW end of the 4101-4899 band on purpose. A project-side story that mechanically derives from an email-smtp-resend REQ id into the number `4106` (leading `4` + sequence `106`) would collide against email-smtp-resend-US-4106 in this package; the band leaves headroom at the HIGH end (US 4181-4899) so a project's own stories anchored to email-smtp-resend REQs can allocate without conflict. The watchpost run4 lesson applies here too.
+
+## Shared expectations for future composing blueprints
+
+- The mail-adapter contract itself is owned by the magic-link blueprint's `TAC-504-security-auth-magic-link-email-delivery-adapter`, not by this blueprint. A sibling `email-smtp-<othervendor>` blueprint that plugs into the same slot inherits the four-class error taxonomy (`RESEND_*` codes generalise to a `<VENDOR>_*` prefix on the sibling; the class semantics stay the same), the retry-and-backoff posture (ADR-402 is a supersede target), and the webhook signature-and-replay discipline (the header names, the algorithm identifier, and the tolerance window remain configuration references; the vendor's specifics live on the sibling's own `docs/topics.md`).
+- 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), `emailWebhookContract` (unclaimed; a project intending to fan email-delivery events into a shared bus would benefit from a global here, but this blueprint deliberately does not mint it in v1). 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.
+
+## Rename awareness
+
+Cross-references in this blueprint's prose use the target-state slugs from the ratified renames pass: `security-auth-magic-link` (for the shipped `auth` blueprint), `persistence-data-sqlite`, `observability-essentials`, `application-spa`, `application-api-rest`. If the rename PR has not yet merged when this blueprint ships, a rebase against the rename PR is required before merge; the cross-references above stay valid at the target state.

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

@@ -0,0 +1,71 @@
+# Email SMTP Resend blueprint guide
+
+## What it is
+
+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. The blueprint contributes the WHAT of a Resend integration: the send-contract shape the auth code calls, the SMTP transport that satisfies it, the four-class error taxonomy the adapter normalises provider responses into, the bounded jittered retry posture on transient classes, the webhook signature verification for Resend delivery events, the replay defence against stale timestamps and duplicate event ids, and the boundary discipline that keeps the SMTP client library confined to one module and every credential sourced from a configured reference.
+
+Concretely, the blueprint ships six requirements, six user stories (fifteen acceptance criteria), two architecture components, and two architecture decision records. Both ADRs are scope-local (ADR-401 on transport choice, ADR-402 on retry-and-backoff posture); no `scope: global` ADR ships from this blueprint.
+
+## What it is not
+
+Not the magic-link auth flow. Those routes live on the magic-link blueprint; this blueprint is the adapter the routes call. Apply the magic-link blueprint separately and compose the two.
+
+Not the mail-adapter interface itself. The interface is owned by the magic-link blueprint's `TAC-504`; this blueprint's job is to satisfy it with a shipped default. A sibling `email-smtp-<othervendor>` blueprint would satisfy the same interface with a different vendor default.
+
+Not an SMTP client library. Any SMTP-speaking Node client the project already carries or picks up works; the adapter injects the client at boot and treats it as a project-supplied binding. The blueprint declares no runtime dependency on a specific SMTP package.
+
+Not a mail-templating engine. The adapter takes `textBody` and `htmlBody` as pre-composed strings; how the auth flow (or any other caller) composes them is not this blueprint's concern.
+
+Not a domain-verification workflow. Sender-domain setup is a provider-owned operation the operator completes against Resend's own docs; the blueprint gates on the unverified-sender refusal class at runtime (AC-4102-1) and points the operator at Resend's docs (`assets/resend-verification-pointer.md`).
+
+Not a compliance layer. Regulatory requirements (double-opt-in, unsubscribe surfaces, retention of consent records) live outside this blueprint; a project subject to them handles them separately.
+
+Not the Resend HTTP API. ADR-401 chooses the SMTP endpoint as the default transport; a project that wants the API path supersedes ADR-401 with a project-level ADR and swaps the adapter's internal client without changing the interface the auth routes call.
+
+## When to reach for it
+
+Reach for the email-smtp-resend blueprint when:
+
+- The project composed the magic-link auth blueprint and needs a real mail transport to fill the `TAC-504` slot; the operator has an account with Resend or intends to open one.
+- The project ships one or a few outbound mail flows (sign-in links, transactional notifications) and does not need a full transactional-email vendor SDK.
+- The team is comfortable with SMTP as the transport shape and wants an adapter close enough to generic SMTP that a follow-up vendor blueprint (`email-smtp-ses`, `email-smtp-postmark`, whichever the estate mints later) can sibling cleanly.
+- Boundary hygiene matters: the SMTP client library must be imported from exactly one module, and no SMTP credential can be committed to the repo or embedded in adapter source.
+- The Resend delivery webhook is a trust boundary the project needs verified (signature check, replay defence) rather than an assumed-trusted stream.
+
+## When it does not fit
+
+Do not reach for the email-smtp-resend blueprint when:
+
+- The project has an established mail vendor that is not Resend and no reason to change. Author a project-local adapter (or a sibling `email-smtp-<othervendor>` blueprint if the vendor is one the estate would benefit from) rather than adopting Resend just to have a shipped default.
+- The project needs per-send provider metadata Resend's SMTP path does not surface (custom tags, native idempotency keys, structured JSON error prose, per-message analytics keying). Supersede ADR-401 with a project-level ADR selecting the Resend HTTP API and swap the adapter's internal client.
+- The project is a public reference or a demo where no real mail transport should ever be reached and every send lands on a stub. Apply the blueprint anyway if the AC set matters, but wire the stub adapter (`assets/stub-adapter.md`) in production and let the deployment's own configuration refuse the real adapter.
+- The mail volume or the delivery-analytics surface has requirements a mail service provider (Sendgrid, Mailgun, SES with an established sender reputation) covers better than Resend at the tier the project runs at. Choose the appropriate vendor and either compose a sibling blueprint if one exists or author a project-local adapter.
+- The project has no Node runtime that can hold an SMTP connection long enough to submit (a strictly serverless surface with sub-second execution budgets and no keep-alive path). Consider the Resend HTTP API supersede for that shape, and note that this blueprint's retry cap of 8000ms is already close to the edge of serverless-friendly budgets.
+
+An earlier design pass considered leading with the Resend HTTP API as the default. The SMTP endpoint won because a generic SMTP adapter shape ports cleanly to a sibling vendor and because the SMTP client library footprint is smaller and more stable than the HTTP-plus-vendor-JSON-shape footprint the API path implies. The API path remains the reference supersede for projects that need the richer per-send metadata.
+
+## What a good outcome looks like
+
+A project applies the magic-link blueprint, applies this blueprint, wires the adapter reference into the auth routes at composition time, sources `RESEND_SMTP_USER`, `RESEND_SMTP_PASSWORD`, `RESEND_FROM_ADDRESS`, and `RESEND_WEBHOOK_SIGNING_SECRET` through the project's secret resolver (the shipped `security-secrets-management` client, a project-authored resolver, or an environment shim), completes Resend's sender-domain verification, and lands on a deployed application where:
+
+- The magic-link mint step calls the adapter and observes `{ ok: true, providerStatus: 202, providerMessageId: '<vendor-id>', error: null }` on the successful path; exactly one SMTP submission goes out per call.
+- An unverified-sender configuration surfaces immediately as `{ ok: false, error: 'RESEND_SENDER_UNVERIFIED: ...' }`; no recipient identity appears on any log line the adapter emits or on any error string it returns.
+- A rate-limit refusal converts to a bounded delay (jittered exponential backoff, default 2 retries, cap 8000ms per attempt) rather than a retry storm; the caller sees one adapter return.
+- The webhook route accepts only signature-passing requests; a mismatched signature returns HTTP 401 with an empty body and emits a `webhookVerificationFailed` audit event; a stale-timestamp request is refused with `webhookReplayStale`; a duplicate delivery id inside the tolerance window is acknowledged HTTP 200 without re-invoking the downstream handler and emits `webhookReplayDuplicate`.
+- A source-tree import-graph scan of the deployed application finds the SMTP client library imported from exactly one module (the adapter); a source-scan of the adapter finds no literal for the SMTP credential, the from-address, or the signing secret.
+
+## Operator decisions that remain open after apply
+
+- Transport choice (SMTP default at ADR-401, or a superseding project-level ADR selecting the Resend HTTP API). Blueprint owns the interface; project owns the transport.
+- SMTP client library selection (whichever Node SMTP-speaking library the project already carries or picks up). Blueprint owns the adapter shape; project owns the client.
+- Event-id store realisation (in-memory LRU for a single-process deployment, or a shared store for a horizontally-scaled deployment). Blueprint fixes the put-if-absent-with-expiry interface; project owns the store.
+- Retry budget and jitter cap (defaults 2 retries and 8000ms respectively, both project-configurable via numeric references). Blueprint owns the posture; project owns the numbers.
+- Tolerance window for webhook timestamps (default 300 seconds, project-configurable via a numeric reference). Blueprint owns the semantics; project owns the number.
+- Webhook route path and mounting point (the blueprint fixes the verifier's shape; the route path lives on the project's own HTTP layer).
+- Secret-reference resolver (the shipped `security-secrets-management` client, a project-authored resolver, or an environment shim). Blueprint owns the boundary; project owns the resolver.
+- Sender-domain verification (Resend-owned operation the operator completes before running the happy-path AC). Blueprint gates on the refusal class at runtime; project owns the verification.
+- Stub adapter usage in test environments (record-only test double shape-compatible with the real adapter). Blueprint ships the shape; project owns the wiring and the deployment-side refusal of the stub in production.
+
+## Cost-honesty paragraph
+
+Shipping this doc set costs the project the following. Every send now runs through one adapter module, which is a small friction on ad-hoc scripts that would otherwise reach a mail library directly; the discipline is intentional and pays off on the day someone needs to change transport or add per-vendor observability. The webhook route is a stateful component (the event-id store) the project maintains; wiring it to a shared store on a horizontally-scaled deployment is a project cost the blueprint does not carry. The retry budget bounds worst-case adapter latency around 20 seconds on the transient classes; a project running behind a tighter SLA lowers the cap and accepts the trade against a higher rate of surfaced transient failures. The four-class error taxonomy means every consumer branches on the class code rather than parsing provider prose; the class table lives in the adapter and needs an update when the provider changes reply-code phrasing, which is a real (small) maintenance cost. The blueprint says nothing about templating, about sender reputation management, about analytics fan-out, about regulatory compliance, or about mail-list management; a project that needs any of those spends its own build cycles on them and this blueprint does not save it any work there. The default SMTP transport is a deliberate trade against the Resend HTTP API's richer per-send metadata; a project that needs that metadata pays the supersede-and-swap cost, which the ADR-401 alternatives block sizes explicitly.

package/blueprints/observability-essentials/README.md

@@ -0,0 +1,53 @@
+# Observability blueprint (v1.0.0)
+
+The fifth content blueprint on the rcf-build-lite blueprint mechanism (design brief v2, ratified; Phase 5 of the blueprint programme). Scope: two HTTP health probes (liveness /healthz answering strictly on in-process state, readiness /readyz aggregating over an explicit boot-time-declared dependency set with strict-any-fail semantics), a public status page rendering a declared component list plus stable-fielded incident notices, and a durable notification-outcome sink recording every attempt's outcome for later query by recipient and window. Targeted at small greenfield rcf-lite projects. Historical uptime charts, metrics export, and distributed tracing are documented future variants; the v1.0.0 blueprint ships the current-state contract only.
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/observability-essentials
+```
+
+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; `rcf define blueprint remove observability-essentials` cleanly removes an unreferenced application.
+
+## Anatomy
+
+| Piece | Where | What |
+|---|---|---|
+| Metadata | `blueprint.json` | Slug, version, and the 29 contributions with scope/topic on the three global ADRs |
+| Doc set | `contributions/` | 10 REQs, 10 USs (30 ACs), 4 TACs, 5 ADRs, all schema-valid against rcf-schemas 0.4.5 and namespaced (`observability-essentials-REQ-001` prefix family; `ADR-801-observability-essentials-health-probes` suffix family) |
+| Probe body sample | `assets/probe-samples/liveness-body.json` | Exact shape of the liveness probe response body at v1.0.0 |
+| Readiness body sample | `assets/probe-samples/readiness-body.json` | Exact shape of the readiness probe response body with the checks object |
+| Status page sample | `assets/status-page-samples/status-page-with-notice.html` | Illustrative rendered HTML with two components and one active incident notice, showing the machine-readable data attributes |
+| Status page empty sample | `assets/status-page-samples/status-page-clean.html` | Illustrative rendered HTML with no active notice, showing the emptyState marker |
+| Guide | `guide/observability-essentials.md` | Operator-facing: when to use it, when not, what stays your call, and the promotion signal for the future metrics and tracing variants |
+| Coordination vocabulary | `docs/topics.md` | The three global-topic strings this blueprint contributes, the shared id band registry (application-spa, application-api-rest, security-auth-magic-link, hello-panel, persistence-data-sqlite, ci-pipeline, observability-essentials) |
+
+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): FBSs 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 liveness probe contract, the readiness probe contract with its dependency-set declaration and cached-state evaluator, the public status page contract with its declared component list and stable notice fields, the notification outcome sink contract with its recordOutcome and queryByRecipient verbs); 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: historical uptime charts and rolling reliability numbers on the status page (out of scope at v1.0.0; see 'Known mechanism-reach gaps' below and the guide 'when it does not fit'); a metrics-export surface (Prometheus scrape endpoints, StatsD emission, OpenTelemetry metrics); a distributed-tracing surface (span emission, propagation, sampling); a log-shipping surface (the application-api-rest blueprint's `logging` topic already governs the wire-log shape; this blueprint neither extends nor conflicts with it); an authenticated operator dashboard for granular internal state (the operator gets granular state through the readiness probe body and through project-authored authenticated surfaces, not through this blueprint); the durable substrate for the notification outcome sink (project-owned; the persistence-data-sqlite blueprint is the natural compose partner). An operator-panel-style authenticated drift surface is deliberately outside this blueprint's scope: `operatorPanel` is claimed by the hello-panel walkthrough exemplar and this blueprint does not overlap it.
+
+## The three global decisions
+
+ADR-801-observability-essentials-health-probes ships `scope: global` on topic `healthProbes`. This is the project's HTTP health endpoint contract: two probes on the request-traffic listener, stable JSON body shape, semantic split of liveness vs readiness. A composing blueprint that holds a different endpoint contract (a single /health endpoint, gRPC health protocol, probes on a separate admin port) conflicts here by design.
+
+ADR-802-observability-essentials-readiness-semantics ships `scope: global` on topic `readinessSemantics`. This is the project's readiness aggregation rule and declaration scope: strict-any-fail over an explicit boot-time-declared dependency set, evaluated against per-dep cached state populated by a background evaluator. A composing blueprint that holds a different opinion (quorum aggregation, write-path-only readiness, graceful-degradation model) conflicts here by design.
+
+ADR-803-observability-essentials-status-page-contract ships `scope: global` on topic `statusPageContract`. This is the project's public status surface: declared component list with a fixed operational/degraded/outage/maintenance state enum, plus stable-fielded incident notices with a fixed info/warning/critical severity enum. A composing blueprint that wants a different public contract (a JSON /status.json endpoint, historical uptime cells as v1 requirement, webhook-posted notices) conflicts here by design.
+
+See `docs/topics.md` for the exact strings, the expected resolutions, the delineation from the hello-panel walkthrough's `operatorPanel` topic (which governs the authenticated operator drift surface, not the public status surface), the delineation from the application-api-rest blueprint's `logging` topic, and the AC id band allocation (observability-essentials owns 7101-7899).
+
+## Quality bar
+
+Two HTTP health probes on the request-traffic listener with stable paths and a stable JSON body shape; liveness answers strictly on in-process event-loop responsiveness with zero network egress from the handler; readiness answers strict-any-fail over an explicit boot-time-declared dependency set with cached per-dep state maintained by a background evaluator on its own cadence; readiness never blocks on a synchronous downstream network call from inside the probe handler; a public status page with no auth gate, a declared component list rendered in declared order, a fixed state enum, stable-fielded incident notices, no internal identifiers, no raw metric values, no readiness dependency names on the public surface; a durable notification outcome sink where every attempt records exactly one outcome record with a stable field set and a fixed outcome enum including suppressed as first-class; a queryable-by-recipient-and-window read surface on the sink returning empty rather than error on no match. Every bar is carried by ACs in the doc set, not by this README.
+
+## Known mechanism-reach gaps
+
+- **Historical uptime chart on the status page.** Not shipped at v1.0.0. The status page contract (ADR-803) commits to declared components with current state plus incident notices; a rolling window of per-component uptime numbers would require a metrics store the blueprint does not own and a retention window the blueprint should not decide unilaterally. Turning it into a runtime-observable AC ('the chart renders the last 30 days at 1-day granularity') either becomes document-observable ('a chart element is present') or depends on an unowned subsystem. Recorded here rather than smuggled in as a v1 requirement. Promotion signal: a shipped `metrics-store` blueprint (or the persistence-data-sqlite blueprint's event log fed forward) that a metrics-backed `statusPageContract` v1.1 can build on. Project-side workaround until then: a project that wants a history chart authors it on top of the declared component vocabulary using a project-owned metrics substrate.
+- **Notification outcome grep gate.** ADR-805 requires every notification-attempting code path to invoke `recordOutcome` exactly once before returning. The blueprint states the invariant as an AC (AC-7106-1); the mechanism does not compel a project's source tree to only call the transport through the sink. The practical enforcement is a project-side grep gate ('every call to the notification transport is preceded by recordOutcome for that notificationId'), which the blueprint does not ship. A project that skips the gate produces the silent-notification defect the blueprint exists to prevent, and no build-cycle gate refuses the FBS. Promotion signal: a lint-rule or CI-gate contribution in a future rcf-lite blueprint or in the ci-pipeline blueprint's shipped ruleset. Project-side workaround: author the grep gate as a project-authored TC bound to AC-7106-1.