rcf-lite 0.12.0 → 0.14.0

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

package/blueprints/observability-essentials/contributions/tacs/tac-803-observability-essentials-status-page.json

@@ -0,0 +1,37 @@
+{
+  "tacId": "TAC-803-observability-essentials-status-page",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Public status page",
+  "purpose": "Owns the public status page: the HTTP handler that renders it, the declared component registry it renders from, and the active-notice reader it renders alongside. The public reader is the primary audience; the renderer commits to the declared component vocabulary and the declared notice fields and to nothing else.",
+  "responsibilities": [
+    "Register a GET handler on the configured status page path (default /status) at the application's HTTP router; respond with 200 and Content-Type text/html to unauthenticated requests (AC-7104-1, AC-7108-1, AC-7108-2).",
+    "Render exactly the declared component list in declared order, with each component's current state as a machine-readable attribute drawn from the operational/degraded/outage/maintenance enum; no phantom components, no missing components, no other state values (AC-7104-1, AC-7104-2, AC-7104-3).",
+    "Render active incident notices in a notices region above the component list; each notice element carries the title, body, severity, startedAt, and componentIds fields as machine-readable attributes with severity drawn from the info/warning/critical enum; when no notices are active, the notices region is either absent or carries an emptyState marker (AC-7105-1, AC-7105-2, AC-7105-3).",
+    "Refuse to render internal identifiers, raw metric values, or declared readiness dependency names on the page; the vocabulary is the declared component names and the declared notice fields, and nothing else (AC-7109-1, AC-7109-2, AC-7109-3)."
+  ],
+  "internalStructure": "One handler module exporting createStatusPageHandler({ path, componentRegistry, noticeReader, now }) -> { path, handler }. The componentRegistry is the declared component list (name, order) loaded at boot from configuration. The noticeReader is a project-supplied async () -> Notice[] the handler invokes per render (with the same non-blocking budget the readiness pattern uses if the notice store is remote). The renderer emits HTML with machine-readable data attributes on component and notice elements so downstream consumers can parse the page without regex over prose.",
+  "interfaces": [
+    {
+      "name": "createStatusPageHandler",
+      "kind": "factory",
+      "description": "createStatusPageHandler({ path, componentRegistry, noticeReader, now }) -> { path, handler }. Returns the configured status path and a handler that renders the declared components and the notices reader's current notices."
+    },
+    {
+      "name": "componentRegistry",
+      "kind": "config",
+      "description": "Declared component list loaded at boot: an ordered list of { name, currentState? } entries. currentState may be static (operator-updated via a project-authored side channel) or read via a per-component reader function the project supplies."
+    },
+    {
+      "name": "noticeReader",
+      "kind": "callback",
+      "description": "Project-supplied async () -> Notice[] returning the current active notice list. Each Notice has { title, body, severity, startedAt, componentIds? } fields."
+    }
+  ],
+  "dependencies": [],
+  "tradeoffs": "The declared-component vocabulary is a public commitment the project owns; renaming a component is an operator-visible change to the public surface. That constraint is what keeps the page stable for external readers. Projects that want a richer public surface (component sub-states, historical uptime cells, per-region breakdowns) extend the declared component vocabulary rather than baking undocumented fields into the render. History over time (historical uptime chart, rolling reliability) is out of scope at v1.0.0; see the blueprint README's Known mechanism-reach gaps for the promotion signal.",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/observability-essentials/contributions/tacs/tac-804-observability-essentials-notification-outcome.json

@@ -0,0 +1,42 @@
+{
+  "tacId": "TAC-804-observability-essentials-notification-outcome",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Notification outcome sink",
+  "purpose": "Owns the durable sink that records the outcome of every notification the application attempts to send. The sink is the operator's answer to 'did the customer get the email'. Every notification-attempting code path in the project routes through a project-supplied recordOutcome verb this component wires; queries by recipient and window are the operator's read surface.",
+  "responsibilities": [
+    "Expose a recordOutcome verb the project's notification-attempting code paths invoke exactly once per attempt, before the attempting call returns; the verb accepts { notificationId, channel, recipient, outcome, attemptedAt, errorCode? } and writes a durable record on the sink (AC-7106-1).",
+    "Refuse to accept a record whose outcome is not one of delivered, failed, pending, or suppressed, or whose channel is not a member of the declared channel enum; the refusal is a stable-coded error the caller must handle (AC-7106-2).",
+    "Expose a queryByRecipient(recipient, { from, to }) verb returning the outcome records that match, with an empty result set when no records match rather than an error (AC-7106-3).",
+    "Persist records to a durable substrate the project owns; the substrate implementation lives inside the project (SQLite table when composing with the persistence-data-sqlite blueprint, a project-owned table otherwise). This TAC owns the sink verbs and the record shape, not the substrate choice."
+  ],
+  "internalStructure": "One module exporting createOutcomeSink({ substrate, channelEnum, now }) -> { recordOutcome, queryByRecipient }. The substrate parameter is a project-supplied durable writer conforming to a narrow interface (append(record), queryByRecipient(recipient, window)); when composing with the persistence-data-sqlite blueprint, the substrate is a facade verb on that store. The channelEnum is loaded at boot from configuration; declaration-set validation runs against every incoming record.",
+  "interfaces": [
+    {
+      "name": "createOutcomeSink",
+      "kind": "factory",
+      "description": "createOutcomeSink({ substrate, channelEnum, now }) -> { recordOutcome, queryByRecipient }. Returns the sink's write and read verbs bound to the project-owned substrate."
+    },
+    {
+      "name": "recordOutcome",
+      "kind": "write-api",
+      "description": "recordOutcome({ notificationId, channel, recipient, outcome, attemptedAt, errorCode? }) -> Promise<void>; refuses on unknown channel or unknown outcome with a stable error code."
+    },
+    {
+      "name": "queryByRecipient",
+      "kind": "read-api",
+      "description": "queryByRecipient(recipient, { from, to }) -> Promise<OutcomeRecord[]>; returns matching records; empty array on no match."
+    },
+    {
+      "name": "substrate",
+      "kind": "callback",
+      "description": "Project-supplied durable writer: { append(record) -> Promise<void>, queryByRecipient(recipient, window) -> Promise<OutcomeRecord[]> }. When composing with the persistence-data-sqlite blueprint, this is a facade verb on that store."
+    }
+  ],
+  "dependencies": [],
+  "tradeoffs": "The sink commits every project's notification code path to a single recordOutcome verb, which is a discipline: a code path that sends a notification without invoking the verb produces the silent-notification defect this blueprint exists to prevent. A grep-level gate ('every call to the notification transport is preceded by recordOutcome') is the practical enforcement; the blueprint states the invariant but does not ship the gate. Projects that want richer per-outcome metadata (correlation ids, retry counts) extend the record shape; the four required fields plus errorCode are the floor.",
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/observability-essentials/contributions/user-stories/observability-essentials-us-7101.json

@@ -0,0 +1,45 @@
+{
+  "usId": "observability-essentials-US-7101",
+  "prdId": "PRD-001",
+  "reqId": "observability-essentials-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Orchestrator restarts a stuck replica via the liveness probe without external dependency coupling",
+  "asA": "orchestrator running the deployed application under a supervising process (Kubernetes kubelet, systemd, or equivalent)",
+  "iWant": "a liveness endpoint that answers pass or fail strictly on whether the process is running its event loop",
+  "soThat": "I restart a wedged replica without letting a downstream dependency outage cascade into a restart storm across every replica",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-7101-1",
+      "description": "The application serves the liveness endpoint at a stable HTTP path declared in configuration (default /healthz); a GET returns 200 when the process is running its event loop and returns application/json with a status field equal to pass.",
+      "given": "the process is running normally with its event loop responsive",
+      "when": "an unauthenticated GET is issued against the liveness path",
+      "then": "the response status code is 200, the Content-Type is application/json, and the JSON body's status field equals pass",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-7101-2",
+      "description": "The liveness probe handler evaluates entirely in-process; a probe hit issues zero network calls to any declared dependency, verifiable by observing the network egress from the probe path.",
+      "given": "the process is running and a network-egress observer is attached to the probe path",
+      "when": "a GET is issued against the liveness path",
+      "then": "the observer records zero egress connections attributable to the probe handler between request receipt and response send",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-7101-3",
+      "description": "The liveness probe answer is independent of the readiness dependency set: pulling a declared readiness dependency offline never turns the liveness probe fail on its own.",
+      "given": "the process is running and every declared readiness dependency is offline",
+      "when": "a GET is issued against the liveness path",
+      "then": "the response status code is 200 and the JSON body's status field equals pass",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-801-observability-essentials-liveness-probe"
+  ],
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/observability-essentials/contributions/user-stories/observability-essentials-us-7102.json

@@ -0,0 +1,45 @@
+{
+  "usId": "observability-essentials-US-7102",
+  "prdId": "PRD-001",
+  "reqId": "observability-essentials-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Load balancer pulls an unready replica from rotation via the readiness probe without triggering a restart",
+  "asA": "load balancer or service mesh routing traffic across replicas of the deployed application",
+  "iWant": "a readiness endpoint that answers pass or fail based on whether the process can serve request traffic against its declared dependencies",
+  "soThat": "I stop routing traffic to a replica that has lost a required dependency without the orchestrator restarting a process that would come back to the same failure",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-7102-1",
+      "description": "The application serves the readiness endpoint at a stable HTTP path declared in configuration (default /readyz), distinct from the liveness path; a GET returns 200 with a JSON body when every declared readiness dependency is passing and returns 503 with a JSON body when at least one declared readiness dependency is failing.",
+      "given": "the process is running and the readiness dependency set is declared",
+      "when": "an unauthenticated GET is issued against the readiness path against a healthy dependency set, then against a set with at least one failing dependency",
+      "then": "the first response has status code 200 with JSON body status equal to pass; the second response has status code 503 with JSON body status equal to fail; both bodies have Content-Type application/json",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-7102-2",
+      "description": "The readiness path is served on the same HTTP listener as the application's request traffic (not on a separate operator port), so a load balancer probing readiness observes the same reachability the traffic will observe.",
+      "given": "the process is running and the request-traffic listener address is declared",
+      "when": "a GET is issued against the readiness path targeting the same listener address as request traffic",
+      "then": "the response is served by the application, not refused with a connection error, and the readiness handler and a representative request handler both bind to the same address:port pair as reported by the process",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-7102-3",
+      "description": "A readiness probe fail never triggers a process exit: the process remains up and continues answering liveness with pass while readiness answers fail.",
+      "given": "the process is running with at least one declared readiness dependency in a failed state",
+      "when": "the readiness probe returns 503 across a five-minute window",
+      "then": "the process exit code is not emitted, the process remains running throughout the window, and the liveness probe continues to return 200 with status pass",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-802-observability-essentials-readiness-probe"
+  ],
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/observability-essentials/contributions/user-stories/observability-essentials-us-7103.json

@@ -0,0 +1,45 @@
+{
+  "usId": "observability-essentials-US-7103",
+  "prdId": "PRD-001",
+  "reqId": "observability-essentials-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Operator sees which dependency turned the replica unready by reading the readiness probe body",
+  "asA": "operator debugging why a replica went unready under load-balancer rotation",
+  "iWant": "the readiness probe response body to name each declared dependency, its individual pass/fail state, and when that state was last evaluated",
+  "soThat": "I move from 'readiness is failing' to 'the payments-provider check has been failing since 14:02' in one step, without opening a shell on the replica",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-7103-1",
+      "description": "The readiness dependency set is declared at boot from application configuration; the application refuses to boot with a stable error code if the declaration is missing or if any declared entry lacks a name, and the declaration set is inspectable from the running process through the probe response.",
+      "given": "the process is configured with a readiness dependency declaration that names each dependency",
+      "when": "the readiness probe is hit after successful boot",
+      "then": "the JSON body's checks object contains one entry per declared dependency, keyed by the dependency name from the declaration, with no additional keys and no missing keys",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-7103-2",
+      "description": "Each entry in the checks object carries a state field (one of pass or fail) and a checkedAt ISO-8601 timestamp naming when the per-dependency state was last evaluated by the background evaluator.",
+      "given": "the readiness probe is hit against a running process with a mixed dependency state",
+      "when": "the response body is inspected",
+      "then": "every entry in the checks object has a state field valued pass or fail and a checkedAt field valued as a parseable ISO-8601 timestamp no older than the readiness evaluation budget declared in configuration",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-7103-3",
+      "description": "Dependencies not present in the readiness declaration never appear in the probe response and never affect the aggregate status.",
+      "given": "the process depends on several downstream services but declares only a strict subset as readiness dependencies",
+      "when": "the readiness probe is hit while an undeclared downstream service is offline",
+      "then": "the undeclared service name never appears as a key in the checks object, and the aggregate status field remains pass so long as every declared dependency is passing",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-802-observability-essentials-readiness-probe"
+  ],
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}

package/blueprints/observability-essentials/contributions/user-stories/observability-essentials-us-7104.json

@@ -0,0 +1,45 @@
+{
+  "usId": "observability-essentials-US-7104",
+  "prdId": "PRD-001",
+  "reqId": "observability-essentials-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "External reader sees the current state of every declared component on a public status page",
+  "asA": "external reader visiting the status page without a login (customer, partner, or anonymous visitor)",
+  "iWant": "a public page that lists every declared component and shows its current state from a fixed vocabulary",
+  "soThat": "I answer 'is this service up right now' without opening a support ticket",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-7104-1",
+      "description": "The application serves the status page at a stable HTTP path declared in configuration (default /status), responds to an unauthenticated GET with 200 and text/html, and renders exactly the declared component list with no phantom components and no missing components.",
+      "given": "the process is running with a component declaration that names N components",
+      "when": "an unauthenticated GET is issued against the status page path",
+      "then": "the response status code is 200, the Content-Type begins with text/html, and the rendered document contains exactly N component elements, each carrying the declared component name as text content",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-7104-2",
+      "description": "Each rendered component element carries its current state as a machine-readable attribute drawn from the fixed enum (operational, degraded, outage, maintenance); the attribute value is one of those four strings and no other.",
+      "given": "the status page has been rendered with the declared components in mixed states",
+      "when": "the rendered document is queried for the per-component state attribute",
+      "then": "every component element carries a state attribute whose value is one of the four enum strings; no other value appears",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-7104-3",
+      "description": "The component render order on the page matches the declaration order in configuration; a component appearing at position K in the declaration renders at position K on the page.",
+      "given": "the component declaration lists components in an order the operator has chosen",
+      "when": "the status page is rendered",
+      "then": "the rendered component elements appear in the same order as the declaration, verified by walking the rendered document's component elements top-to-bottom and comparing to the declared order",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "tacIds": [
+    "TAC-803-observability-essentials-status-page"
+  ],
+  "createdAt": "2026-08-24T00:00:00Z",
+  "updatedAt": "2026-08-24T00:00:00Z"
+}