rcf-lite 0.11.0 → 0.13.0

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

package/blueprints/observability-essentials/contributions/adrs/adr-805-observability-essentials-notification-outcome-model.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-805-observability-essentials-notification-outcome-model",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Every notification attempt records a durable outcome record; suppressed is a first-class outcome; substrate is project-owned",
+  "context": "Notification channels drop messages silently at multiple layers: the transport rejects the send, the provider queues but never delivers, the recipient filters it, the operator suppresses it during an active incident. Without an outcome record per attempt, 'the customer says they never got the email' is unanswerable: was it never sent, sent but dropped, sent but filtered, or sent but suppressed. The record turns that question into a query.",
+  "decision": "Every notification-attempting code path in the project invokes the recordOutcome verb (TAC-804) exactly once before returning. The record shape is { notificationId, channel, recipient, outcome, attemptedAt, errorCode? }. The outcome enum is { delivered, failed, pending, suppressed }; suppressed is a first-class value covering the case where an active incident notice or a policy toggle suppressed the send. The channel enum is declared at boot from configuration. The substrate is project-owned: when composing with the persistence-data-sqlite blueprint, it is a facade verb on the persistence store; when standalone, it is a project-authored durable writer conforming to the substrate interface. The blueprint owns the record shape, the enums, the verb signatures, and the query semantics; it does not own the durable substrate.",
+  "consequences": "Operators can answer 'did the customer get the notification' by querying the sink by recipient and window. Suppressed sends are visible after the fact, which lets the operator audit whether the suppression policy did what the operator intended. A code path that sends a notification without invoking recordOutcome produces the silent-notification defect the blueprint exists to prevent; a project-side grep gate ('every call to the notification transport is preceded by recordOutcome for that notificationId') is the practical enforcement. A composing blueprint that wants richer outcome metadata (correlation ids, retry counts, provider ids) extends the record shape project-side; the four required fields plus errorCode are the floor. When composing with the persistence-data-sqlite blueprint, the sink is one of that blueprint's facade verbs; when composing with the security-auth-magic-link blueprint, notification attempts against security-auth-magic-link-adjacent flows (magic-link sends) route through the same recordOutcome verb.",
+  "alternativesConsidered": [
+    {
+      "name": "Ship the durable substrate as part of this blueprint (a project-embedded SQLite table)",
+      "summary": "The blueprint contributes both the sink verbs and a concrete SQLite-backed substrate implementation.",
+      "reasonNotChosen": "Would create a store contribution the persistence-data-sqlite blueprint already owns. A project composing observability with persistence would end up with two store contracts fighting over the same substrate. Leaving the substrate to the project (with the persistence-data-sqlite blueprint as the natural compose partner) keeps the layering clean."
+    },
+    {
+      "name": "Fold suppressed into failed with an errorCode of 'suppressed'",
+      "summary": "The outcome enum has three values; suppression is a subtype of failure.",
+      "reasonNotChosen": "Suppression is not a failure: the operator's policy actively chose not to send. Conflating them makes an operator audit of 'how many notifications did the policy suppress this hour' harder to query. First-class suppressed keeps the record shape unambiguous."
+    }
+  ],
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/observability-essentials/contributions/requirements/observability-essentials-req-001.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "observability-essentials-REQ-001",
+  "prdId": "PRD-001",
+  "title": "The application exposes a liveness probe endpoint that answers whether the process is stuck",
+  "description": "The application serves a liveness probe at a stable HTTP path. A 2xx response from the endpoint means the process is running its event loop and is not wedged; a 5xx response means the process is stuck and the orchestrator should restart it. The endpoint's answer never depends on the health of any external dependency: a database outage, a broker outage, or a partner API outage never turns liveness red on its own. The endpoint runs entirely inside the process boundary.",
+  "category": "functional",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "Liveness is the orchestrator's restart signal. Coupling it to external dependency health causes a database blip to cascade into a full restart storm across every replica, and cascades cause outages that dwarf the original blip. The invariant that liveness answers strictly on in-process state (event loop responsive, main thread not deadlocked) is what makes restart the correct action when the probe fails.",
+  "tags": [
+    "blueprint:observability-essentials",
+    "category:01-liveness-probe"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/observability-essentials/contributions/requirements/observability-essentials-req-002.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "observability-essentials-REQ-002",
+  "prdId": "PRD-001",
+  "title": "The application exposes a readiness probe endpoint that answers whether the process can serve traffic",
+  "description": "The application serves a readiness probe at a stable HTTP path distinct from the liveness path. A 2xx response means the process is ready to accept request traffic; a 5xx response means the orchestrator should stop routing traffic to this replica while the process itself remains up. The readiness answer aggregates the health of the specific dependencies the process needs to serve requests correctly (declared as the readiness dependency set), evaluated on each probe hit through non-blocking cached checks that never hang the endpoint on a slow dep.",
+  "category": "functional",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "Readiness is the load-balancer's routing signal. A ready replica should be able to serve; an unready replica should be pulled from rotation without a restart. The split from liveness matters: an outage of a downstream dependency that makes serving impossible is a readiness failure (route around me) not a liveness failure (restart me).",
+  "tags": [
+    "blueprint:observability-essentials",
+    "category:02-readiness-probe"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/observability-essentials/contributions/requirements/observability-essentials-req-003.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "observability-essentials-REQ-003",
+  "prdId": "PRD-001",
+  "title": "The readiness dependency set is declared in configuration and every declared dependency is named in the probe response",
+  "description": "The set of dependencies whose health contributes to the readiness answer is declared at boot from application configuration. Each declared dependency has a stable string name that appears in the readiness probe's structured response body under a checks field, alongside its individual pass/fail state and the timestamp of the last check evaluation. Dependencies not declared in the readiness set never appear in the probe response, never affect readiness, and are surfaced to operators only through the status page or the notification outcome record.",
+  "category": "functional",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "An operator debugging why a replica went unready must be able to read the probe response and see which dependency failed the check. An implicit dependency set (every registered client, every imported library) surprises the operator; the declaration set is the operator's contract with the readiness signal. Naming dependencies not in the readiness set inside the probe muddies which failure will actually pull the replica from rotation.",
+  "tags": [
+    "blueprint:observability-essentials",
+    "category:03-readiness-deps"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/observability-essentials/contributions/requirements/observability-essentials-req-004.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "observability-essentials-REQ-004",
+  "prdId": "PRD-001",
+  "title": "The application serves a public status page listing every declared component and its current state",
+  "description": "The application serves a public status page at a stable HTTP path intended for external readers (users, partners, unauthenticated visitors). The page renders a list of declared components (subsystems the project chooses to publish state for), each with a current state field from a fixed enum (operational, degraded, outage, maintenance) and a human-readable component name. The page has no login gate. The component list, the enum, and the display order are declared at boot from application configuration; no component appears on the page that was not declared.",
+  "category": "functional",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "External readers need a single canonical answer to 'is the service up right now' without support tickets. A public status page bounded by a declared component list is the industry-standard shape; the declared-list constraint is what stops the page from silently gaining or losing surfaces across deploys.",
+  "tags": [
+    "blueprint:observability-essentials",
+    "category:04-status-page"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/observability-essentials/contributions/requirements/observability-essentials-req-005.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "observability-essentials-REQ-005",
+  "prdId": "PRD-001",
+  "title": "The status page surfaces active incident notices with a stable structure and stable field names",
+  "description": "When the operator has posted one or more active incident notices, the status page renders them above the component list. Each notice carries a title (short human string), a body (longer human string), a severity from a fixed enum (info, warning, critical), a startedAt ISO-8601 timestamp, and an optional componentIds array naming which declared components the notice relates to. When no notices are active, the notice region is either absent from the rendered page or clearly labelled as empty; no phantom notices, no stale notices carried over from a previous incident.",
+  "category": "functional",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "A status page with no incident affordance forces the operator to communicate outages through side channels the external reader does not watch. A stable notice structure and stable field names is what lets a downstream RSS aggregator or partner-facing dashboard consume the surface without hand-parsing HTML.",
+  "tags": [
+    "blueprint:observability-essentials",
+    "category:05-incident-notices"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/observability-essentials/contributions/requirements/observability-essentials-req-006.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "observability-essentials-REQ-006",
+  "prdId": "PRD-001",
+  "title": "Every notification the application sends records an outcome on a durable sink that operators can query by recipient and window",
+  "description": "The application records the outcome of every notification it attempts to send (email, SMS, push, webhook, or any other channel the project ships) as a structured record on a durable outcome sink. Each record carries a notification identifier, a channel name from a fixed enum, a recipient identifier, an outcome from a fixed enum (delivered, failed, pending, suppressed), an attemptedAt ISO-8601 timestamp, and an optional errorCode string when the outcome is failed. An operator queries the sink by recipient identifier and time window and receives the outcome records that match. Notifications never succeed silently: an attempt with no recorded outcome is a defect the project must gate against.",
+  "category": "functional",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "A silent notification channel is the shape that produces 'the customer says they never got the email' with no way to distinguish 'we never sent it' from 'the provider dropped it' from 'the recipient filtered it'. The outcome record is what turns that question into a query. The suppressed outcome value covers the case where an active incident notice suppresses noisy notifications; the record still lands so the operator can audit the suppression later.",
+  "tags": [
+    "blueprint:observability-essentials",
+    "category:06-notification-outcome"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/observability-essentials/contributions/requirements/observability-essentials-req-007.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "observability-essentials-REQ-007",
+  "prdId": "PRD-001",
+  "title": "Probe responses carry a stable JSON body shape with stable field names and an ISO-8601 timestamp",
+  "description": "The liveness and readiness probe endpoints respond with a JSON body carrying a stable shape: a status field (one of pass or fail), a checkedAt field with an ISO-8601 timestamp of when the probe body was evaluated, and, on the readiness probe, a checks field mapping declared-dependency name to that dependency's individual pass/fail. Content-Type is application/json. Field names do not change across patch or minor versions of the blueprint; a change is a major version bump.",
+  "category": "functional",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "Probes get consumed by orchestrators, dashboards, and third-party monitoring integrations. A stable JSON shape with stable field names is what lets those consumers wire once and not re-wire on every deploy. HTTP status code drives routing decisions; the JSON body drives the operator's next diagnostic step.",
+  "tags": [
+    "blueprint:observability-essentials",
+    "category:07-probe-shape"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/observability-essentials/contributions/requirements/observability-essentials-req-008.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "observability-essentials-REQ-008",
+  "prdId": "PRD-001",
+  "title": "Probes and the public status page are served without an authentication gate",
+  "description": "The liveness probe, the readiness probe, and the public status page respond to unauthenticated HTTP requests. No cookie, no header, no source-IP allowlist gates access to these three surfaces. The three paths are declared at boot as auth-exempt in whatever authentication middleware the application uses, and that exemption is the only auth policy the surfaces run under.",
+  "category": "nonFunctional",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "Orchestrators, load balancers, and external status-page readers cannot be expected to hold service credentials. A probe that requires auth is a probe the orchestrator cannot use; a status page that requires auth is not a public status page. The auth-exempt declaration is what makes the exemption an operator-visible policy rather than a piece of implicit middleware ordering.",
+  "tags": [
+    "blueprint:observability-essentials",
+    "category:08-probe-auth-exempt"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/observability-essentials/contributions/requirements/observability-essentials-req-009.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "observability-essentials-REQ-009",
+  "prdId": "PRD-001",
+  "title": "The public status page never leaks internal identifiers, metric values, or dependency detail beyond the declared surface",
+  "description": "The public status page renders only the declared component list and their per-component states, plus the active incident notices. It never renders internal identifiers (host names, replica ids, database identifiers, queue names), never renders raw metric values (request counts, latency numbers, error rates), and never names the specific dependencies that failed a readiness check. The status enum values, the component names, and the incident notice fields are the public vocabulary; anything more granular is operator-only surface, exposed through the readiness probe body or an authenticated operator dashboard.",
+  "category": "security",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "A public surface with unrestricted readers cannot reveal internal topology or performance detail: those are reconnaissance material for a targeted attack, and they are inventory the project does not want to commit to as stable contract. The declared component list is the vocabulary the public reader gets; the operator gets the granular story through authenticated surfaces.",
+  "tags": [
+    "blueprint:observability-essentials",
+    "category:09-status-page-secrecy"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/observability-essentials/contributions/requirements/observability-essentials-req-010.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "observability-essentials-REQ-010",
+  "prdId": "PRD-001",
+  "title": "Probe handlers evaluate in bounded time and never block on a network call to a downstream dependency",
+  "description": "The liveness probe handler completes its evaluation entirely in-process and returns without issuing any network call. The readiness probe handler completes within a bounded ceiling (the readiness evaluation budget, declared at boot with a documented default) and never blocks on a synchronous network round trip to a declared dependency: readiness checks read from a per-dependency last-known state that a background evaluator refreshes on its own cadence. A slow or hanging downstream dependency causes the last-known state for that dependency to age or fail, not the probe handler itself to hang.",
+  "category": "nonFunctional",
+  "domain": "observability",
+  "priority": "must",
+  "rationale": "A probe handler that blocks on a downstream network call is a probe that turns a downstream partial outage into an orchestrator-visible full outage: replicas get pulled from rotation because their readiness probes timed out waiting on the same slow dep. The cached-last-known-state pattern is what breaks that coupling: the probe answers on cached state at endpoint response time, the dep-health worker refreshes on its own cadence with its own budget, and a hung dep hangs the worker not the probe.",
+  "tags": [
+    "blueprint:observability-essentials",
+    "category:10-probe-non-blocking"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/observability-essentials/contributions/tacs/tac-801-observability-essentials-liveness-probe.json

@@ -0,0 +1,32 @@
+{
+  "tacId": "TAC-801-observability-essentials-liveness-probe",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Liveness probe",
+  "purpose": "Owns the in-process HTTP handler that answers the liveness endpoint. The handler is coupled to nothing outside the process boundary: no downstream dependency, no I/O, no cache; its answer reflects strictly whether the event loop is responsive. The handler is the one place the liveness contract lives, and its registration on the HTTP router is the one place the liveness path binds.",
+  "responsibilities": [
+    "Register a GET handler on the configured liveness path (default /healthz) at the application's HTTP router, no earlier than the router is initialised and no later than the first request bind (AC-7101-1, AC-7108-2).",
+    "Return 200 with Content-Type application/json and a body of shape { status: 'pass', checkedAt: <ISO-8601> } whenever the handler is invoked while the process event loop is responsive (AC-7101-1, AC-7107-1).",
+    "Perform zero network egress from inside the handler; the handler's only work is filling in the response body and writing it to the response stream (AC-7101-2, AC-7110-3).",
+    "Answer independently of the readiness dependency state: the handler holds no reference to the readiness dependency registry and no readiness state changes affect the liveness answer (AC-7101-3)."
+  ],
+  "internalStructure": "One handler module that exports a factory: createLivenessHandler({ path, now }) -> { path, handler }. The factory closes over the configured path and a now() function (default () -> new Date()); handler is an async function (req, res) that writes the JSON body and returns. The registrar module wires the handler into the HTTP router at boot; the auth-exempt list registration is co-located with the router wiring so a single review reads both facts.",
+  "interfaces": [
+    {
+      "name": "createLivenessHandler",
+      "kind": "factory",
+      "description": "createLivenessHandler({ path, now }) -> { path, handler }. Returns the configured probe path and a stateless async handler for it. Called once at boot; the returned handler is bound at the HTTP router."
+    },
+    {
+      "name": "livenessPath",
+      "kind": "config",
+      "description": "Configured liveness HTTP path; defaults to /healthz if the configuration does not override it. Consumed by the registrar and by the auth-exempt list."
+    }
+  ],
+  "dependencies": [],
+  "tradeoffs": "The handler owns its answer entirely on in-process state; that means it cannot report on any external condition, which is precisely the point. A project that wants a smarter liveness answer (e.g. 'restart me if my heap has been over 90 percent for 60 seconds') wires that logic as an additional heartbeat that faults the event loop when the class the project cares about occurs, rather than folding it into the handler. The default 200-pass shape is deliberately trivial to keep the coupling low.",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/observability-essentials/contributions/tacs/tac-802-observability-essentials-readiness-probe.json

@@ -0,0 +1,43 @@
+{
+  "tacId": "TAC-802-observability-essentials-readiness-probe",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Readiness probe",
+  "purpose": "Owns the HTTP handler for the readiness endpoint and the background dep-health evaluator that feeds it. The handler answers from a per-dependency cache the evaluator maintains on its own cadence; the handler itself never blocks on a synchronous downstream call. The dependency registry is the operator's contract with the probe's answer.",
+  "responsibilities": [
+    "Register a GET handler on the configured readiness path (default /readyz) at the application's HTTP router, on the same listener that serves request traffic (AC-7102-1, AC-7102-2, AC-7108-2).",
+    "Read from a per-dependency last-known state cache populated by the background evaluator; return 200 with status pass when every declared dependency's cached state is pass, return 503 with status fail otherwise; response body includes the checks object with state and checkedAt per declared dependency (AC-7102-1, AC-7103-1, AC-7103-2, AC-7107-2, AC-7110-1).",
+    "Complete the handler evaluation within the readiness evaluation budget (default 1 second) regardless of any dependency's real-endpoint responsiveness; no synchronous network call is issued from inside the handler (AC-7110-1).",
+    "Run the background dep-health evaluator on its declared cadence, evaluating every declared dependency at least once per interval independently of any other dependency's state, so a hanging dep does not starve the others' evaluations (AC-7110-2).",
+    "Refuse boot with a stable error code if the readiness dependency declaration is missing or if any entry lacks a name; the exact declared set is the exact set of keys in the probe response's checks object (AC-7103-1, AC-7103-3)."
+  ],
+  "internalStructure": "Two modules: a handler module exporting createReadinessHandler({ path, registry, budgetMs, now }) -> { path, handler } and an evaluator module exporting createEvaluator({ registry, cadenceMs, checkFor, now }) -> { start, stop, snapshot } where snapshot() returns the current { depName -> { state, checkedAt } } map the handler reads. The registry is the declared dependency set loaded at boot from configuration and refused if malformed. The checkFor function is a project-supplied per-dependency probe implementation the evaluator invokes on its own cadence with its own per-dependency timeout budget.",
+  "interfaces": [
+    {
+      "name": "createReadinessHandler",
+      "kind": "factory",
+      "description": "createReadinessHandler({ path, registry, budgetMs, now }) -> { path, handler }. Returns the configured readiness path and a handler that reads only from the evaluator's snapshot(); never blocks on a network call."
+    },
+    {
+      "name": "createEvaluator",
+      "kind": "factory",
+      "description": "createEvaluator({ registry, cadenceMs, checkFor, now }) -> { start, stop, snapshot }. The background evaluator; start() and stop() control the loop, snapshot() exposes the last-known state to the handler."
+    },
+    {
+      "name": "dependencyRegistry",
+      "kind": "config",
+      "description": "Declared readiness dependency set loaded at boot: a list of { name, evaluateBudgetMs? } entries. The names are the probe response's checks-object keys."
+    },
+    {
+      "name": "checkFor",
+      "kind": "callback",
+      "description": "Project-supplied per-dependency probe: (name) -> Promise<{ state: 'pass' | 'fail', checkedAt: <ISO-8601> }>. Called by the evaluator, not by the handler."
+    }
+  ],
+  "dependencies": [],
+  "tradeoffs": "The cached-state pattern means the probe response is at worst one cadence interval stale; a dep that fails mid-cycle takes up to the cadence to reflect on the probe. That staleness is the cost of never hanging the probe handler. Projects that want tighter freshness turn down the cadence at the cost of extra background work; projects that never want the probe to falsely fail on a transient dep blip turn up the cadence at the cost of slower fail-open detection.",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}