rcf-lite 0.12.0 → 0.14.0

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` |
+| delivery-ci-workflows | 6101-6899 | 7xx | shipped v2.0.0 (renamed from ci-pipeline) | `ciGates`, `strictCoverageGate`, `releaseArtefacts` |
+| 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, delivery-ci-workflows, 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 delivery-ci-workflows blueprint's shipped ruleset. Project-side workaround: author the grep gate as a project-authored TC bound to AC-7106-1.

package/blueprints/observability-essentials/assets/probe-samples/liveness-body.json

@@ -0,0 +1,4 @@
+{
+  "status": "pass",
+  "checkedAt": "2026-08-24T12:34:56.789Z"
+}

package/blueprints/observability-essentials/assets/probe-samples/readiness-body.json

@@ -0,0 +1,18 @@
+{
+  "status": "fail",
+  "checkedAt": "2026-08-24T12:34:56.789Z",
+  "checks": {
+    "primary-store": {
+      "state": "pass",
+      "checkedAt": "2026-08-24T12:34:55.501Z"
+    },
+    "payments-provider": {
+      "state": "fail",
+      "checkedAt": "2026-08-24T12:34:55.502Z"
+    },
+    "sms-gateway": {
+      "state": "pass",
+      "checkedAt": "2026-08-24T12:34:55.503Z"
+    }
+  }
+}

package/blueprints/observability-essentials/assets/status-page-samples/status-page-clean.html

@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="en">
+<head><title>Service status</title></head>
+<body>
+  <main>
+    <section class="notices" data-testid="notices-region" data-empty-state="true">
+      <p class="notices-empty">No active notices.</p>
+    </section>
+    <section class="components" data-testid="components-region">
+      <article class="component" data-name="payments" data-state="operational">
+        <h3 class="component-name">Payments</h3>
+      </article>
+      <article class="component" data-name="notifications" data-state="operational">
+        <h3 class="component-name">Notifications</h3>
+      </article>
+      <article class="component" data-name="data" data-state="operational">
+        <h3 class="component-name">Data</h3>
+      </article>
+    </section>
+  </main>
+</body>
+</html>

package/blueprints/observability-essentials/assets/status-page-samples/status-page-with-notice.html

@@ -0,0 +1,25 @@
+<!doctype html>
+<html lang="en">
+<head><title>Service status</title></head>
+<body>
+  <main>
+    <section class="notices" data-testid="notices-region">
+      <article class="notice" data-severity="warning" data-started-at="2026-08-24T11:02:00Z" data-component-ids="payments,notifications">
+        <h2 class="notice-title" data-testid="notice-title">Payments partner slowdown</h2>
+        <p class="notice-body" data-testid="notice-body">Our payments partner is responding slowly. Card payments may take up to 30 seconds to complete. We are monitoring.</p>
+      </article>
+    </section>
+    <section class="components" data-testid="components-region">
+      <article class="component" data-name="payments" data-state="degraded">
+        <h3 class="component-name">Payments</h3>
+      </article>
+      <article class="component" data-name="notifications" data-state="operational">
+        <h3 class="component-name">Notifications</h3>
+      </article>
+      <article class="component" data-name="data" data-state="operational">
+        <h3 class="component-name">Data</h3>
+      </article>
+    </section>
+  </main>
+</body>
+</html>

package/blueprints/observability-essentials/blueprint.json

@@ -0,0 +1,54 @@
+{
+  "slug": "observability-essentials",
+  "version": "1.0.0",
+  "category": "observability",
+  "contributions": [
+    { "id": "observability-essentials-REQ-001", "kind": "req", "path": "requirements/observability-essentials-req-001.json" },
+    { "id": "observability-essentials-REQ-002", "kind": "req", "path": "requirements/observability-essentials-req-002.json" },
+    { "id": "observability-essentials-REQ-003", "kind": "req", "path": "requirements/observability-essentials-req-003.json" },
+    { "id": "observability-essentials-REQ-004", "kind": "req", "path": "requirements/observability-essentials-req-004.json" },
+    { "id": "observability-essentials-REQ-005", "kind": "req", "path": "requirements/observability-essentials-req-005.json" },
+    { "id": "observability-essentials-REQ-006", "kind": "req", "path": "requirements/observability-essentials-req-006.json" },
+    { "id": "observability-essentials-REQ-007", "kind": "req", "path": "requirements/observability-essentials-req-007.json" },
+    { "id": "observability-essentials-REQ-008", "kind": "req", "path": "requirements/observability-essentials-req-008.json" },
+    { "id": "observability-essentials-REQ-009", "kind": "req", "path": "requirements/observability-essentials-req-009.json" },
+    { "id": "observability-essentials-REQ-010", "kind": "req", "path": "requirements/observability-essentials-req-010.json" },
+    { "id": "observability-essentials-US-7101", "kind": "us", "path": "user-stories/observability-essentials-us-7101.json" },
+    { "id": "observability-essentials-US-7102", "kind": "us", "path": "user-stories/observability-essentials-us-7102.json" },
+    { "id": "observability-essentials-US-7103", "kind": "us", "path": "user-stories/observability-essentials-us-7103.json" },
+    { "id": "observability-essentials-US-7104", "kind": "us", "path": "user-stories/observability-essentials-us-7104.json" },
+    { "id": "observability-essentials-US-7105", "kind": "us", "path": "user-stories/observability-essentials-us-7105.json" },
+    { "id": "observability-essentials-US-7106", "kind": "us", "path": "user-stories/observability-essentials-us-7106.json" },
+    { "id": "observability-essentials-US-7107", "kind": "us", "path": "user-stories/observability-essentials-us-7107.json" },
+    { "id": "observability-essentials-US-7108", "kind": "us", "path": "user-stories/observability-essentials-us-7108.json" },
+    { "id": "observability-essentials-US-7109", "kind": "us", "path": "user-stories/observability-essentials-us-7109.json" },
+    { "id": "observability-essentials-US-7110", "kind": "us", "path": "user-stories/observability-essentials-us-7110.json" },
+    { "id": "TAC-801-observability-essentials-liveness-probe", "kind": "tac", "path": "tacs/tac-801-observability-essentials-liveness-probe.json" },
+    { "id": "TAC-802-observability-essentials-readiness-probe", "kind": "tac", "path": "tacs/tac-802-observability-essentials-readiness-probe.json" },
+    { "id": "TAC-803-observability-essentials-status-page", "kind": "tac", "path": "tacs/tac-803-observability-essentials-status-page.json" },
+    { "id": "TAC-804-observability-essentials-notification-outcome", "kind": "tac", "path": "tacs/tac-804-observability-essentials-notification-outcome.json" },
+    {
+      "id": "ADR-801-observability-essentials-health-probes",
+      "kind": "adr",
+      "path": "adrs/adr-801-observability-essentials-health-probes.json",
+      "scope": "global",
+      "topic": "healthProbes"
+    },
+    {
+      "id": "ADR-802-observability-essentials-readiness-semantics",
+      "kind": "adr",
+      "path": "adrs/adr-802-observability-essentials-readiness-semantics.json",
+      "scope": "global",
+      "topic": "readinessSemantics"
+    },
+    {
+      "id": "ADR-803-observability-essentials-status-page-contract",
+      "kind": "adr",
+      "path": "adrs/adr-803-observability-essentials-status-page-contract.json",
+      "scope": "global",
+      "topic": "statusPageContract"
+    },
+    { "id": "ADR-804-observability-essentials-probe-secrecy", "kind": "adr", "path": "adrs/adr-804-observability-essentials-probe-secrecy.json" },
+    { "id": "ADR-805-observability-essentials-notification-outcome-model", "kind": "adr", "path": "adrs/adr-805-observability-essentials-notification-outcome-model.json" }
+  ]
+}

package/blueprints/observability-essentials/contributions/adrs/adr-801-observability-essentials-health-probes.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-801-observability-essentials-health-probes",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Two HTTP health probes served on the request-traffic listener: liveness on /healthz, readiness on /readyz, with a stable JSON body shape",
+  "context": "Every deployed application runs under an orchestrator that needs a restart signal and under a load balancer that needs a routing signal. The two signals answer different questions: 'is this process wedged, restart it' versus 'is this process able to serve, route around it if not'. A single probe folded across both questions produces the outage-amplifying failure mode where a downstream dependency blip triggers a restart storm that dwarfs the original blip. The probes have to be structurally separate at the endpoint and semantically separate at the answer.",
+  "decision": "The application serves two probe endpoints on the same HTTP listener that serves request traffic: a liveness probe at /healthz (or the configured override) and a readiness probe at /readyz (or the configured override). Both respond with Content-Type application/json and a stable body shape: { status: 'pass' | 'fail', checkedAt: <ISO-8601> } for liveness, plus a { checks: { <depName>: { state, checkedAt } } } object for readiness. Liveness returns 200 whenever the event loop is responsive and never depends on any external condition; readiness returns 200 when every declared dependency's cached state is pass and 503 otherwise. Both endpoints are auth-exempt (see ADR-804). The probes bind to the request-traffic listener rather than a separate operator port so the load balancer's probe observes the same reachability the traffic will observe.",
+  "consequences": "The orchestrator's restart action is coupled only to true process wedging: a downstream dependency outage never triggers a restart. The load balancer's rotation action is coupled to declared-dependency health only: an unready replica gets pulled from rotation without a restart the replica cannot recover from. The stable JSON shape lets third-party monitoring integrations wire once. A change to the probe path defaults or a rename of a top-level probe body field is a major version bump on this blueprint. Composing blueprints that hold a different opinion on the endpoint contract (a project that wants /health as a single endpoint answering both questions, a project that wants gRPC probes, a project that wants both probes on a separate admin port) conflict on the healthProbes topic; the expected resolution is one project-level ADR that fixes the endpoint contract.",
+  "alternativesConsidered": [
+    {
+      "name": "Single /health endpoint answering both liveness and readiness with one status code",
+      "summary": "One HTTP path, one 200/503 answer, one probe both orchestrator and load balancer consume.",
+      "reasonNotChosen": "Folds the two signals into one and creates the restart-storm failure mode. A downstream dep outage that fails the single endpoint gets read as 'restart me' by the orchestrator, which does, and the restarted process comes back to the same failing dep and fails again. The industry has settled on the /healthz + /readyz split (Kubernetes liveness/readiness probes are the reference); the pattern exists precisely because the fused shape has bitten enough deployments."
+    },
+    {
+      "name": "gRPC health protocol instead of HTTP JSON",
+      "summary": "The application exposes the standard gRPC health service instead of two HTTP endpoints.",
+      "reasonNotChosen": "The rcf-lite tier this blueprint targets is small greenfield HTTP-shaped applications; a gRPC probe surface requires a gRPC listener the tier does not otherwise need. A project that runs a gRPC application supersedes this ADR and contributes its own project-level ADR selecting the gRPC health protocol; the readiness dependency semantics (ADR-802) are engine-agnostic and carry over."
+    },
+    {
+      "name": "Probes on a separate admin port distinct from the request-traffic listener",
+      "summary": "The probes bind to a dedicated admin listener; only the operator/orchestrator can reach them.",
+      "reasonNotChosen": "A load balancer probing a separate admin port does not observe the same reachability path that request traffic takes; a firewall rule or listener config drift can make the admin port reachable while the traffic port is not. Binding the probes on the traffic listener makes 'the probe answers' equivalent to 'requests reach the listener', which is the property the load balancer needs."
+    }
+  ],
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/observability-essentials/contributions/adrs/adr-802-observability-essentials-readiness-semantics.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-802-observability-essentials-readiness-semantics",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Readiness fails on any declared dependency's failure; the readiness dependency set is an explicit boot-time declaration",
+  "context": "Readiness aggregates the health of dependencies the process needs to serve traffic. The two questions the semantics have to answer are (1) which dependencies count and (2) what aggregation rule turns per-dependency states into the ready/not-ready answer. Answered implicitly, the first collapses to 'every dependency ever touched by the process' which produces false-negative readiness (pulling replicas out of rotation because a rarely-used dep is offline) and false-positive readiness (a critical dep the developer never registered). Answered wrongly, the second (e.g. quorum, majority) produces surprising behaviour under partial outage.",
+  "decision": "The readiness dependency set is an explicit boot-time declaration in application configuration, refused if malformed. Every declared dependency contributes to the aggregate readiness answer under a strict-any-fail rule: readiness is pass when every declared dependency's cached state is pass; readiness is fail when at least one declared dependency's cached state is fail. Dependencies not declared in the set do not appear in the probe response, do not contribute to readiness, and get surfaced through the status page or through the notification outcome record (or through project-authored authenticated dashboards) but never through the readiness probe. The evaluation is against per-dependency cached state maintained by a background evaluator on its own cadence (see ADR-801 and TAC-802); no synchronous downstream network call is made from the probe handler.",
+  "consequences": "The operator's contract with readiness is the declaration set and the strict-any-fail rule: one glance at the declaration answers 'what could make this replica unready'. False-negative readiness (a rarely-used dep failing) is prevented by keeping the declaration narrow: a dep whose failure does not mean 'do not send me traffic' does not belong in the readiness set. False-positive readiness (missing a critical dep) is prevented by boot-time refusal on a malformed declaration and by review discipline on the declaration itself. Composing blueprints that hold a different opinion on readiness semantics (a quorum-based aggregation, a write-path-only readiness, a graceful-degradation model where some dep failures mean serve-partial rather than not-ready) conflict on the readinessSemantics topic; the expected resolution is one project-level ADR that fixes the aggregation and the declaration scope for the project.",
+  "alternativesConsidered": [
+    {
+      "name": "Implicit readiness dependency set (every registered client or connection pool)",
+      "summary": "The readiness answer aggregates over every downstream client the process has registered, with no explicit declaration.",
+      "reasonNotChosen": "Produces both false-negative and false-positive readiness. A rarely-used analytics client failing shouldn't pull the replica; a mistakenly-unregistered payment client failing must. The declaration is the operator's chance to make the set explicit and reviewable."
+    },
+    {
+      "name": "Quorum or majority aggregation (readiness passes if K of N deps are healthy)",
+      "summary": "The aggregation is a threshold count over the per-dep states rather than strict-any-fail.",
+      "reasonNotChosen": "Turns readiness into a soft signal that lets partial outages go under-reported. The rcf-lite tier is small greenfield where dependencies are almost always all-required; if any one is optional, it does not belong in the readiness set. A project that genuinely runs a graceful-degradation model where some deps are optional supersedes this ADR."
+    },
+    {
+      "name": "Synchronous per-probe evaluation (each probe hit evaluates each dep with a real network call)",
+      "summary": "The probe handler queries every declared dep on the probe hit and aggregates the results synchronously.",
+      "reasonNotChosen": "Turns downstream latency into probe-response latency; a slow dep causes the load balancer to time out the probe and the replica goes unready for reasons unrelated to whether it could actually serve traffic. The cached-state pattern breaks that coupling; the per-cadence staleness is a lower cost than the cascading-timeout failure mode."
+    }
+  ],
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/observability-essentials/contributions/adrs/adr-803-observability-essentials-status-page-contract.json

@@ -0,0 +1,30 @@
+{
+  "adrId": "ADR-803-observability-essentials-status-page-contract",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Public status page renders a declared component list with a fixed state enum and stable-fielded incident notices; no internal detail",
+  "context": "A public status page is the project's canonical answer to 'is this service up right now' for external readers who cannot reach the operator's authenticated dashboards. The page's audience is uncredentialed: customers, partners, anonymous visitors. Two failure shapes commonly bite public status pages: (1) drift-into-marketing where the page becomes a curated narrative not tied to any observed component state, and (2) leak-of-internals where the page exposes hostnames, replica ids, metric values, or dependency names that were never intended as public contract. Both undermine the page's function.",
+  "decision": "The public status page contract is: a declared component list (component name plus current state), a fixed state enum { operational, degraded, outage, maintenance }, a notices region for active incident notices with fields { title, body, severity, startedAt, componentIds? } and severity drawn from { info, warning, critical }. The declared component list is the public vocabulary; nothing outside it is renderable on the page. Internal identifiers, raw metric values, and declared readiness dependency names are refused by render invariant (AC-7109-1, AC-7109-2, AC-7109-3). Historical uptime charts and rolling reliability numbers are out of scope at v1.0.0; they are documented as a known mechanism-reach gap with the promotion signal being a shipped metrics-store blueprint that can back the retention story.",
+  "consequences": "External readers get a stable, machine-parseable public surface: downstream RSS aggregators and partner dashboards can consume it without hand-regexing HTML. Internal detail is a bright-line refusal not a hedged 'usually not'. A change to the state enum or the notice field set is a major version bump on this blueprint; extensions to the component vocabulary (per-region breakdowns, sub-component roll-ups) are project-authored on top of the declared component list. Composing blueprints that hold a different opinion on the public status contract (a blueprint that wants historical uptime cells as part of v1, a blueprint that wants machine-readable JSON at /status.json alongside the HTML page, a blueprint that wants incident notices posted through a webhook instead of an operator-authored store) conflict on the statusPageContract topic; the expected resolution is one project-level ADR that fixes the public contract shape.",
+  "alternativesConsidered": [
+    {
+      "name": "Ship a historical uptime chart per component as a v1.0.0 required AC",
+      "summary": "The status page renders a rolling window of per-component uptime alongside the current state.",
+      "reasonNotChosen": "History requires a metrics store the blueprint does not own, a retention window the blueprint should not decide, and turns a runtime-observable AC ('the uptime chart renders 30 days at 1-day granularity') into either document-observable or dependent on an unowned subsystem. The current-state contract is defensibly complete at v1.0.0; history is a v1.1 candidate once a metrics-store blueprint ships or the persistence-data-sqlite blueprint's event log is fed forward. Recorded as a known mechanism-reach gap in the README, not smuggled in as a v1 requirement."
+    },
+    {
+      "name": "Machine-readable /status.json endpoint alongside the HTML page",
+      "summary": "The status vocabulary is served as JSON at /status.json for programmatic consumers, HTML at /status for humans.",
+      "reasonNotChosen": "The HTML page renders machine-readable data attributes on component and notice elements, so a programmatic consumer parses the page without a separate JSON endpoint. Shipping the JSON surface as well doubles the contract surface without changing what a machine consumer can read. A future project that wants a formal JSON endpoint contributes it project-side and does not need a blueprint-side decision."
+    },
+    {
+      "name": "Auto-derived component state from the readiness dependency set",
+      "summary": "The status page's components map 1:1 to the readiness dependency set and their states derive from the readiness cache.",
+      "reasonNotChosen": "Leaks the internal dependency vocabulary as public contract (see ADR-804 secrecy). The public component list is deliberately distinct from the readiness set; the operator maps one to the other on their own side. A project that wants the two vocabularies unified authors that mapping project-side."
+    }
+  ],
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/observability-essentials/contributions/adrs/adr-804-observability-essentials-probe-secrecy.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-804-observability-essentials-probe-secrecy",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Probes and status page are auth-exempt; readiness body names deps, status page does not; no metric values on any public surface",
+  "context": "The three public surfaces this blueprint contributes (liveness probe, readiness probe, public status page) have different audiences and therefore different acceptable leak surfaces. Orchestrators cannot hold service credentials, so probes must be auth-exempt. The readiness probe body is read by operators and integrations that already know the dependency set; naming deps in the probe response is functional. The status page is read by uncredentialed external readers; naming deps there is a leak. Getting the split wrong in either direction (auth-gate the probes, or leak internals to the public page) breaks the surfaces' function.",
+  "decision": "The liveness path, the readiness path, and the status page path are declared at boot as auth-exempt in the application's authentication middleware. No cookie, no header, no source-IP allowlist gates access to those three paths. The readiness probe response body names each declared readiness dependency (state and checkedAt per dep); the public status page never names a readiness dependency, never renders internal identifiers (hostnames, replica ids, database identifiers, queue names, internal URLs, build hashes), and never renders raw metric values (request counts, latency numbers, error rates, queue depths). The status page vocabulary is the declared component list plus the declared notice fields; anything more granular belongs on an authenticated operator surface the project owns, not on the public page.",
+  "consequences": "The public reader sees only what the operator has committed to as public contract; a security review of the public surface only inventories the declared component list and the declared notice fields. Operators who need the granular story fetch it from the readiness body (declared deps) or from project-authored authenticated dashboards. Auth-exempt is one-directional: an authenticated caller hitting a probe or the status page still gets the response (the exemption removes the gate, it does not gate against authenticated callers). A composing blueprint that wants the probes gated (e.g. a hardened-tier blueprint requiring source-IP allowlist on /readyz) authors a project-level auth policy that supersedes this ADR piecewise.",
+  "alternativesConsidered": [
+    {
+      "name": "Probes require a service token; the auth-exempt list is a v1.1 opt-in",
+      "summary": "The three surfaces are auth-gated by default; a project opts them out at deploy time if the orchestrator cannot hold credentials.",
+      "reasonNotChosen": "The default outcome would be projects that skip the opt-out step and ship gated probes the orchestrator cannot use, and gated status pages the intended readers cannot reach. The rcf-lite tier this blueprint targets does not have a security posture that justifies making unauth the opt-in shape."
+    },
+    {
+      "name": "Public status page derives components from the readiness dependency set",
+      "summary": "The status page's component list is auto-generated from the readiness registry; no separate declaration.",
+      "reasonNotChosen": "Leaks the internal dependency vocabulary as public contract. Dependency names are chosen for operator clarity (payments-provider, sms-gateway); public component names are chosen for external reader clarity (Payments, Notifications). Merging the two surfaces the wrong names in the wrong audience."
+    }
+  ],
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}